From 8b0bf53875ab0f2149a9232f339921157f64dcf4 Mon Sep 17 00:00:00 2001 From: Rob Browning Date: Sun, 14 Jun 2015 12:41:01 -0500 Subject: [PATCH] Remove DFSG incompatible files Remove files that are incompatible with the Debian Free Software Guidelines. --- admin/unidata/IVD_Sequences.txt | 38461 ------------------------ doc/emacs/ChangeLog | 10693 ------- doc/emacs/Makefile.in | 291 - doc/emacs/abbrevs.texi | 448 - doc/emacs/ack.texi | 1457 - doc/emacs/anti.texi | 113 - doc/emacs/arevert-xtra.texi | 189 - doc/emacs/basic.texi | 827 - doc/emacs/buffers.texi | 702 - doc/emacs/building.texi | 1614 - doc/emacs/cal-xtra.texi | 1022 - doc/emacs/calendar.texi | 1632 - doc/emacs/cmdargs.texi | 1145 - doc/emacs/commands.texi | 185 - doc/emacs/custom.texi | 2548 -- doc/emacs/dired-xtra.texi | 50 - doc/emacs/dired.texi | 1456 - doc/emacs/display.texi | 1667 - doc/emacs/doclicense.texi | 505 - doc/emacs/emacs-xtra.texi | 137 - doc/emacs/emacs.texi | 1612 - doc/emacs/emerge-xtra.texi | 413 - doc/emacs/entering.texi | 165 - doc/emacs/files.texi | 2052 -- doc/emacs/fixit.texi | 417 - doc/emacs/fortran-xtra.texi | 581 - doc/emacs/frames.texi | 1207 - doc/emacs/glossary.texi | 1472 - doc/emacs/gnu.texi | 551 - doc/emacs/gpl.texi | 717 - doc/emacs/help.texi | 648 - doc/emacs/indent.texi | 255 - doc/emacs/killing.texi | 917 - doc/emacs/kmacro.texi | 574 - doc/emacs/m-x.texi | 71 - doc/emacs/macos.texi | 218 - doc/emacs/maintaining.texi | 2395 -- doc/emacs/makefile.w32-in | 153 - doc/emacs/mark.texi | 471 - doc/emacs/mini.texi | 802 - doc/emacs/misc.texi | 2619 -- doc/emacs/modes.texi | 449 - doc/emacs/msdog-xtra.texi | 620 - doc/emacs/msdog.texi | 990 - doc/emacs/mule.texi | 1831 -- doc/emacs/package.texi | 299 - doc/emacs/picture-xtra.texi | 289 - doc/emacs/programs.texi | 1839 -- doc/emacs/regs.texi | 385 - doc/emacs/rmail.texi | 1578 - doc/emacs/screen.texi | 324 - doc/emacs/search.texi | 1509 - doc/emacs/sending.texi | 697 - doc/emacs/text.texi | 2818 -- doc/emacs/trouble.texi | 1238 - doc/emacs/vc-xtra.texi | 25 - doc/emacs/vc1-xtra.texi | 447 - doc/emacs/windows.texi | 461 - doc/emacs/xresources.texi | 821 - doc/lispintro/ChangeLog | 753 - doc/lispintro/Makefile.in | 207 - doc/lispintro/README | 45 - doc/lispintro/cons-1.eps | 578 - doc/lispintro/cons-1.pdf | 71 - doc/lispintro/cons-2.eps | 600 - doc/lispintro/cons-2.pdf | Bin 1399 -> 0 bytes doc/lispintro/cons-2a.eps | 594 - doc/lispintro/cons-2a.pdf | Bin 1504 -> 0 bytes doc/lispintro/cons-3.eps | 624 - doc/lispintro/cons-3.pdf | Bin 1475 -> 0 bytes doc/lispintro/cons-4.eps | 677 - doc/lispintro/cons-4.pdf | Bin 1587 -> 0 bytes doc/lispintro/cons-5.eps | 622 - doc/lispintro/cons-5.pdf | Bin 1511 -> 0 bytes doc/lispintro/doclicense.texi | 505 - doc/lispintro/drawers.eps | 510 - doc/lispintro/drawers.pdf | Bin 3906 -> 0 bytes doc/lispintro/emacs-lisp-intro.texi | 21977 -------------- doc/lispintro/lambda-1.eps | 465 - doc/lispintro/lambda-1.pdf | 69 - doc/lispintro/lambda-2.eps | 465 - doc/lispintro/lambda-2.pdf | Bin 1225 -> 0 bytes doc/lispintro/lambda-3.eps | 465 - doc/lispintro/lambda-3.pdf | 69 - doc/lispintro/makefile.w32-in | 85 - doc/lispref/ChangeLog | 13388 --------- doc/lispref/Makefile.in | 262 - doc/lispref/README | 48 - doc/lispref/abbrevs.texi | 497 - doc/lispref/anti.texi | 139 - doc/lispref/back.texi | 38 - doc/lispref/backups.texi | 776 - doc/lispref/book-spine.texi | 28 - doc/lispref/buffers.texi | 1238 - doc/lispref/commands.texi | 3515 --- doc/lispref/compile.texi | 744 - doc/lispref/control.texi | 1457 - doc/lispref/customize.texi | 1467 - doc/lispref/debugging.texi | 866 - doc/lispref/display.texi | 6741 ----- doc/lispref/doclicense.texi | 505 - doc/lispref/edebug.texi | 1635 - doc/lispref/elisp.texi | 1622 - doc/lispref/errors.texi | 221 - doc/lispref/eval.texi | 874 - doc/lispref/files.texi | 3391 --- doc/lispref/frames.texi | 2670 -- doc/lispref/functions.texi | 2022 -- doc/lispref/gpl.texi | 717 - doc/lispref/hash.texi | 355 - doc/lispref/help.texi | 712 - doc/lispref/hooks.texi | 278 - doc/lispref/index.texi | 26 - doc/lispref/internals.texi | 1652 - doc/lispref/intro.texi | 555 - doc/lispref/keymaps.texi | 2955 -- doc/lispref/lay-flat.texi | 44 - doc/lispref/lists.texi | 1956 -- doc/lispref/loading.texi | 1074 - doc/lispref/macros.texi | 632 - doc/lispref/makefile.w32-in | 128 - doc/lispref/maps.texi | 199 - doc/lispref/markers.texi | 708 - doc/lispref/minibuf.texi | 2371 -- doc/lispref/modes.texi | 4068 --- doc/lispref/nonascii.texi | 1977 -- doc/lispref/numbers.texi | 1245 - doc/lispref/objects.texi | 2123 -- doc/lispref/os.texi | 2727 -- doc/lispref/package.texi | 379 - doc/lispref/positions.texi | 999 - doc/lispref/processes.texi | 3127 -- doc/lispref/searching.texi | 1911 -- doc/lispref/sequences.texi | 874 - doc/lispref/spellfile | 730 - doc/lispref/streams.texi | 835 - doc/lispref/strings.texi | 1168 - doc/lispref/symbols.texi | 571 - doc/lispref/syntax.texi | 1201 - doc/lispref/text.texi | 4539 --- doc/lispref/tips.texi | 1076 - doc/lispref/two-volume-cross-refs.txt | 319 - doc/lispref/two-volume.make | 236 - doc/lispref/variables.texi | 2177 -- doc/lispref/windows.texi | 3995 --- doc/misc/ada-mode.texi | 1526 - doc/misc/auth.texi | 540 - doc/misc/autotype.texi | 669 - doc/misc/bovine.texi | 475 - doc/misc/calc.texi | 37099 ----------------------- doc/misc/cc-mode.texi | 7243 ----- doc/misc/cl.texi | 5150 ---- doc/misc/dbus.texi | 2041 -- doc/misc/dired-x.texi | 1112 - doc/misc/doclicense.texi | 505 - doc/misc/ebrowse.texi | 1418 - doc/misc/ede.texi | 4283 --- doc/misc/ediff.texi | 2534 -- doc/misc/edt.texi | 944 - doc/misc/eieio.texi | 1911 -- doc/misc/emacs-gnutls.texi | 215 - doc/misc/emacs-mime.texi | 1893 -- doc/misc/epa.texi | 516 - doc/misc/erc.texi | 864 - doc/misc/ert.texi | 879 - doc/misc/eshell.texi | 1231 - doc/misc/eudc.texi | 942 - doc/misc/eww.texi | 236 - doc/misc/flymake.texi | 787 - doc/misc/forms.texi | 978 - doc/misc/gnus-coding.texi | 392 - doc/misc/gnus-faq.texi | 2293 -- doc/misc/gnus-news.texi | 371 - doc/misc/gnus-overrides.texi | 0 doc/misc/gnus.texi | 30657 ------------------- doc/misc/gpl.texi | 717 - doc/misc/htmlfontify.texi | 1595 - doc/misc/idlwave.texi | 4300 --- doc/misc/ido.texi | 805 - doc/misc/info.texi | 1276 - doc/misc/mairix-el.texi | 352 - doc/misc/message.texi | 2532 -- doc/misc/mh-e.texi | 9094 ------ doc/misc/newsticker.texi | 316 - doc/misc/nxml-mode.texi | 916 - doc/misc/octave-mode.texi | 446 - doc/misc/org.texi | 18550 ------------ doc/misc/pcl-cvs.texi | 1441 - doc/misc/pgg.texi | 512 - doc/misc/rcirc.texi | 949 - doc/misc/reftex.texi | 6097 ---- doc/misc/remember.texi | 445 - doc/misc/sasl.texi | 276 - doc/misc/sc.texi | 1926 -- doc/misc/sem-user.texi | 1325 - doc/misc/semantic.texi | 627 - doc/misc/ses.texi | 1169 - doc/misc/sieve.texi | 366 - doc/misc/smtpmail.texi | 443 - doc/misc/speedbar.texi | 1232 - doc/misc/srecode.texi | 1800 -- doc/misc/todo-mode.texi | 1921 -- doc/misc/tramp.texi | 3978 --- doc/misc/trampver.texi | 69 - doc/misc/url.texi | 1316 - doc/misc/vip.texi | 1947 -- doc/misc/viper.texi | 4552 --- doc/misc/widget.texi | 1806 -- doc/misc/wisent.texi | 2040 -- doc/misc/woman.texi | 1434 - etc/CENSORSHIP | 87 - etc/DEVEL.HUMOR | 204 - etc/GNU | 544 - etc/JOKES | 647 - etc/LINUX-GNU | 147 - etc/THE-GNU-PROJECT | 903 - etc/WHY-FREE | 244 - src/macuvs.h | 9208 ------ 218 files changed, 424494 deletions(-) delete mode 100644 admin/unidata/IVD_Sequences.txt delete mode 100644 doc/emacs/ChangeLog delete mode 100644 doc/emacs/Makefile.in delete mode 100644 doc/emacs/abbrevs.texi delete mode 100644 doc/emacs/ack.texi delete mode 100644 doc/emacs/anti.texi delete mode 100644 doc/emacs/arevert-xtra.texi delete mode 100644 doc/emacs/basic.texi delete mode 100644 doc/emacs/buffers.texi delete mode 100644 doc/emacs/building.texi delete mode 100644 doc/emacs/cal-xtra.texi delete mode 100644 doc/emacs/calendar.texi delete mode 100644 doc/emacs/cmdargs.texi delete mode 100644 doc/emacs/commands.texi delete mode 100644 doc/emacs/custom.texi delete mode 100644 doc/emacs/dired-xtra.texi delete mode 100644 doc/emacs/dired.texi delete mode 100644 doc/emacs/display.texi delete mode 100644 doc/emacs/doclicense.texi delete mode 100644 doc/emacs/emacs-xtra.texi delete mode 100644 doc/emacs/emacs.texi delete mode 100644 doc/emacs/emerge-xtra.texi delete mode 100644 doc/emacs/entering.texi delete mode 100644 doc/emacs/files.texi delete mode 100644 doc/emacs/fixit.texi delete mode 100644 doc/emacs/fortran-xtra.texi delete mode 100644 doc/emacs/frames.texi delete mode 100644 doc/emacs/glossary.texi delete mode 100644 doc/emacs/gnu.texi delete mode 100644 doc/emacs/gpl.texi delete mode 100644 doc/emacs/help.texi delete mode 100644 doc/emacs/indent.texi delete mode 100644 doc/emacs/killing.texi delete mode 100644 doc/emacs/kmacro.texi delete mode 100644 doc/emacs/m-x.texi delete mode 100644 doc/emacs/macos.texi delete mode 100644 doc/emacs/maintaining.texi delete mode 100644 doc/emacs/makefile.w32-in delete mode 100644 doc/emacs/mark.texi delete mode 100644 doc/emacs/mini.texi delete mode 100644 doc/emacs/misc.texi delete mode 100644 doc/emacs/modes.texi delete mode 100644 doc/emacs/msdog-xtra.texi delete mode 100644 doc/emacs/msdog.texi delete mode 100644 doc/emacs/mule.texi delete mode 100644 doc/emacs/package.texi delete mode 100644 doc/emacs/picture-xtra.texi delete mode 100644 doc/emacs/programs.texi delete mode 100644 doc/emacs/regs.texi delete mode 100644 doc/emacs/rmail.texi delete mode 100644 doc/emacs/screen.texi delete mode 100644 doc/emacs/search.texi delete mode 100644 doc/emacs/sending.texi delete mode 100644 doc/emacs/text.texi delete mode 100644 doc/emacs/trouble.texi delete mode 100644 doc/emacs/vc-xtra.texi delete mode 100644 doc/emacs/vc1-xtra.texi delete mode 100644 doc/emacs/windows.texi delete mode 100644 doc/emacs/xresources.texi delete mode 100644 doc/lispintro/ChangeLog delete mode 100644 doc/lispintro/Makefile.in delete mode 100644 doc/lispintro/README delete mode 100644 doc/lispintro/cons-1.eps delete mode 100644 doc/lispintro/cons-1.pdf delete mode 100644 doc/lispintro/cons-2.eps delete mode 100644 doc/lispintro/cons-2.pdf delete mode 100644 doc/lispintro/cons-2a.eps delete mode 100644 doc/lispintro/cons-2a.pdf delete mode 100644 doc/lispintro/cons-3.eps delete mode 100644 doc/lispintro/cons-3.pdf delete mode 100644 doc/lispintro/cons-4.eps delete mode 100644 doc/lispintro/cons-4.pdf delete mode 100644 doc/lispintro/cons-5.eps delete mode 100644 doc/lispintro/cons-5.pdf delete mode 100644 doc/lispintro/doclicense.texi delete mode 100644 doc/lispintro/drawers.eps delete mode 100644 doc/lispintro/drawers.pdf delete mode 100644 doc/lispintro/emacs-lisp-intro.texi delete mode 100644 doc/lispintro/lambda-1.eps delete mode 100644 doc/lispintro/lambda-1.pdf delete mode 100644 doc/lispintro/lambda-2.eps delete mode 100644 doc/lispintro/lambda-2.pdf delete mode 100644 doc/lispintro/lambda-3.eps delete mode 100644 doc/lispintro/lambda-3.pdf delete mode 100644 doc/lispintro/makefile.w32-in delete mode 100644 doc/lispref/ChangeLog delete mode 100644 doc/lispref/Makefile.in delete mode 100644 doc/lispref/README delete mode 100644 doc/lispref/abbrevs.texi delete mode 100644 doc/lispref/anti.texi delete mode 100644 doc/lispref/back.texi delete mode 100644 doc/lispref/backups.texi delete mode 100644 doc/lispref/book-spine.texi delete mode 100644 doc/lispref/buffers.texi delete mode 100644 doc/lispref/commands.texi delete mode 100644 doc/lispref/compile.texi delete mode 100644 doc/lispref/control.texi delete mode 100644 doc/lispref/customize.texi delete mode 100644 doc/lispref/debugging.texi delete mode 100644 doc/lispref/display.texi delete mode 100644 doc/lispref/doclicense.texi delete mode 100644 doc/lispref/edebug.texi delete mode 100644 doc/lispref/elisp.texi delete mode 100644 doc/lispref/errors.texi delete mode 100644 doc/lispref/eval.texi delete mode 100644 doc/lispref/files.texi delete mode 100644 doc/lispref/frames.texi delete mode 100644 doc/lispref/functions.texi delete mode 100644 doc/lispref/gpl.texi delete mode 100644 doc/lispref/hash.texi delete mode 100644 doc/lispref/help.texi delete mode 100644 doc/lispref/hooks.texi delete mode 100644 doc/lispref/index.texi delete mode 100644 doc/lispref/internals.texi delete mode 100644 doc/lispref/intro.texi delete mode 100644 doc/lispref/keymaps.texi delete mode 100644 doc/lispref/lay-flat.texi delete mode 100644 doc/lispref/lists.texi delete mode 100644 doc/lispref/loading.texi delete mode 100644 doc/lispref/macros.texi delete mode 100644 doc/lispref/makefile.w32-in delete mode 100644 doc/lispref/maps.texi delete mode 100644 doc/lispref/markers.texi delete mode 100644 doc/lispref/minibuf.texi delete mode 100644 doc/lispref/modes.texi delete mode 100644 doc/lispref/nonascii.texi delete mode 100644 doc/lispref/numbers.texi delete mode 100644 doc/lispref/objects.texi delete mode 100644 doc/lispref/os.texi delete mode 100644 doc/lispref/package.texi delete mode 100644 doc/lispref/positions.texi delete mode 100644 doc/lispref/processes.texi delete mode 100644 doc/lispref/searching.texi delete mode 100644 doc/lispref/sequences.texi delete mode 100644 doc/lispref/spellfile delete mode 100644 doc/lispref/streams.texi delete mode 100644 doc/lispref/strings.texi delete mode 100644 doc/lispref/symbols.texi delete mode 100644 doc/lispref/syntax.texi delete mode 100644 doc/lispref/text.texi delete mode 100644 doc/lispref/tips.texi delete mode 100644 doc/lispref/two-volume-cross-refs.txt delete mode 100644 doc/lispref/two-volume.make delete mode 100644 doc/lispref/variables.texi delete mode 100644 doc/lispref/windows.texi delete mode 100644 doc/misc/ada-mode.texi delete mode 100644 doc/misc/auth.texi delete mode 100644 doc/misc/autotype.texi delete mode 100644 doc/misc/bovine.texi delete mode 100644 doc/misc/calc.texi delete mode 100644 doc/misc/cc-mode.texi delete mode 100644 doc/misc/cl.texi delete mode 100644 doc/misc/dbus.texi delete mode 100644 doc/misc/dired-x.texi delete mode 100644 doc/misc/doclicense.texi delete mode 100644 doc/misc/ebrowse.texi delete mode 100644 doc/misc/ede.texi delete mode 100644 doc/misc/ediff.texi delete mode 100644 doc/misc/edt.texi delete mode 100644 doc/misc/eieio.texi delete mode 100644 doc/misc/emacs-gnutls.texi delete mode 100644 doc/misc/emacs-mime.texi delete mode 100644 doc/misc/epa.texi delete mode 100644 doc/misc/erc.texi delete mode 100644 doc/misc/ert.texi delete mode 100644 doc/misc/eshell.texi delete mode 100644 doc/misc/eudc.texi delete mode 100644 doc/misc/eww.texi delete mode 100644 doc/misc/flymake.texi delete mode 100644 doc/misc/forms.texi delete mode 100644 doc/misc/gnus-coding.texi delete mode 100644 doc/misc/gnus-faq.texi delete mode 100644 doc/misc/gnus-news.texi delete mode 100644 doc/misc/gnus-overrides.texi delete mode 100644 doc/misc/gnus.texi delete mode 100644 doc/misc/gpl.texi delete mode 100644 doc/misc/htmlfontify.texi delete mode 100644 doc/misc/idlwave.texi delete mode 100644 doc/misc/ido.texi delete mode 100644 doc/misc/info.texi delete mode 100644 doc/misc/mairix-el.texi delete mode 100644 doc/misc/message.texi delete mode 100644 doc/misc/mh-e.texi delete mode 100644 doc/misc/newsticker.texi delete mode 100644 doc/misc/nxml-mode.texi delete mode 100644 doc/misc/octave-mode.texi delete mode 100644 doc/misc/org.texi delete mode 100644 doc/misc/pcl-cvs.texi delete mode 100644 doc/misc/pgg.texi delete mode 100644 doc/misc/rcirc.texi delete mode 100644 doc/misc/reftex.texi delete mode 100644 doc/misc/remember.texi delete mode 100644 doc/misc/sasl.texi delete mode 100644 doc/misc/sc.texi delete mode 100644 doc/misc/sem-user.texi delete mode 100644 doc/misc/semantic.texi delete mode 100644 doc/misc/ses.texi delete mode 100644 doc/misc/sieve.texi delete mode 100644 doc/misc/smtpmail.texi delete mode 100644 doc/misc/speedbar.texi delete mode 100644 doc/misc/srecode.texi delete mode 100644 doc/misc/todo-mode.texi delete mode 100644 doc/misc/tramp.texi delete mode 100644 doc/misc/trampver.texi delete mode 100644 doc/misc/url.texi delete mode 100644 doc/misc/vip.texi delete mode 100644 doc/misc/viper.texi delete mode 100644 doc/misc/widget.texi delete mode 100644 doc/misc/wisent.texi delete mode 100644 doc/misc/woman.texi delete mode 100644 etc/CENSORSHIP delete mode 100644 etc/DEVEL.HUMOR delete mode 100644 etc/GNU delete mode 100644 etc/JOKES delete mode 100644 etc/LINUX-GNU delete mode 100644 etc/THE-GNU-PROJECT delete mode 100644 etc/WHY-FREE delete mode 100644 src/macuvs.h diff --git a/admin/unidata/IVD_Sequences.txt b/admin/unidata/IVD_Sequences.txt deleted file mode 100644 index fdf21e8a308..00000000000 --- a/admin/unidata/IVD_Sequences.txt +++ /dev/null @@ -1,38461 +0,0 @@ -# IVD_Sequences -# -# History: -# -# 2014-05-16 Combined registration of the Moji_Joho collection and of -# sequences in that collection. -# -# 2012-07-02 File restored due to corruption on the server. -# -# 2012-03-02 Registration of additional sequences in the Adobe-Japan1 -# collection. Registration of additional sequences in the -# Hanyo-Denshi collection. -# -# 2010-11-14 Combined registration of the Hanyo-Denshi collection and of -# sequences in that collection. -# -# 2007-12-14 Combined registration of the Adobe-Japan1 collection and of -# sequences in that collection. -# -# This file is part of the Unicode Ideographic Variation Database (IVD). -# For more details on the IVD, see UTS #37: -# http://www.unicode.org/reports/tr37/ -# -# Copyright 2006-2014 Unicode, Inc. -# For terms of use, see: http://www.unicode.org/terms_of_use.html -# -3402 E0100; Adobe-Japan1; CID+13698 -3402 E0101; Adobe-Japan1; CID+13697 -3402 E0102; Adobe-Japan1; CID+13699 -3402 E0103; Hanyo-Denshi; IA0102 -3402 E0104; Hanyo-Denshi; TK01000160 -3404 E0100; Hanyo-Denshi; IA0103 -3404 E0100; Moji_Joho; MJ000008 -3404 E0101; Hanyo-Denshi; KS152700 -3404 E0101; Moji_Joho; MJ000007 -3405 E0100; Adobe-Japan1; CID+15387 -3406 E0100; Adobe-Japan1; CID+17242 -3427 E0100; Adobe-Japan1; CID+13910 -3427 E0101; Hanyo-Denshi; IA0105 -3427 E0102; Hanyo-Denshi; TK01000500 -342A E0100; Hanyo-Denshi; IA0106 -342A E0101; Hanyo-Denshi; JTC0B3 -342A E0101; Moji_Joho; MJ000023 -342A E0102; Hanyo-Denshi; TK01024240 -342A E0103; Moji_Joho; MJ000022 -342C E0100; Adobe-Japan1; CID+17246 -342C E0101; Hanyo-Denshi; IA0107 -342C E0101; Moji_Joho; MJ000025 -342C E0102; Hanyo-Denshi; KS098140 -342C E0102; Moji_Joho; MJ057397 -342E E0100; Adobe-Japan1; CID+14216 -342E E0101; Moji_Joho; MJ000027 -342E E0102; Moji_Joho; MJ000028 -342E E0103; Moji_Joho; MJ000029 -3436 E0100; Hanyo-Denshi; IA0112 -3436 E0100; Moji_Joho; MJ000036 -3436 E0101; Hanyo-Denshi; JTAD47 -3436 E0101; Moji_Joho; MJ000037 -3441 E0100; Hanyo-Denshi; IA0114 -3441 E0100; Moji_Joho; MJ000045 -3441 E0101; Hanyo-Denshi; JT3441 -3441 E0101; Moji_Joho; MJ000046 -3442 E0100; Moji_Joho; MJ000047 -3442 E0101; Moji_Joho; MJ000048 -344D E0100; Hanyo-Denshi; IA0923 -344D E0101; Hanyo-Denshi; TK01003470 -3464 E0100; Hanyo-Denshi; IA0126 -3464 E0100; Moji_Joho; MJ000074 -3464 E0101; Hanyo-Denshi; KS009720 -3464 E0101; Moji_Joho; MJ000073 -3468 E0100; Adobe-Japan1; CID+14047 -346A E0100; Adobe-Japan1; CID+17269 -3479 E0100; Hanyo-Denshi; IA0128 -3479 E0100; Moji_Joho; MJ000089 -3479 E0101; Hanyo-Denshi; JTAD8C -3479 E0101; Moji_Joho; MJ013511 -3479 E0102; Hanyo-Denshi; KS158120 -3479 E0102; Moji_Joho; MJ057674 -3488 E0100; Adobe-Japan1; CID+15442 -348A E0100; Hanyo-Denshi; IA0968 -348A E0100; Moji_Joho; MJ000106 -348A E0101; Hanyo-Denshi; KS014050 -348A E0101; Moji_Joho; MJ000105 -3492 E0100; Adobe-Japan1; CID+17294 -3496 E0100; Hanyo-Denshi; KS013950 -3496 E0101; Hanyo-Denshi; TK01005910 -34A7 E0100; Hanyo-Denshi; IA0980 -34A7 E0100; Moji_Joho; MJ000129 -34A7 E0101; Hanyo-Denshi; KS015310 -34A7 E0101; Moji_Joho; MJ000130 -34B5 E0100; Adobe-Japan1; CID+16793 -34B8 E0100; Hanyo-Denshi; KS017260 -34B8 E0100; Moji_Joho; MJ000143 -34B8 E0101; Hanyo-Denshi; KS412410 -34B8 E0101; Moji_Joho; MJ000144 -34B9 E0100; Hanyo-Denshi; IA1003 -34B9 E0100; Moji_Joho; MJ000146 -34B9 E0101; Hanyo-Denshi; KS017740 -34B9 E0101; Moji_Joho; MJ000145 -34BB E0100; Hanyo-Denshi; IA1004 -34BB E0101; Hanyo-Denshi; TK01084400 -34BC E0100; Adobe-Japan1; CID+17303 -34BC E0101; Hanyo-Denshi; IA0133 -34BC E0101; Moji_Joho; MJ000150 -34BC E0102; Hanyo-Denshi; KS018450 -34BC E0102; Moji_Joho; MJ057021 -34BD E0100; Hanyo-Denshi; IA1005 -34BD E0101; Hanyo-Denshi; TK01039610 -34C1 E0100; Adobe-Japan1; CID+18384 -34C3 E0100; Hanyo-Denshi; IA0135 -34C3 E0100; Moji_Joho; MJ000156 -34C3 E0101; Hanyo-Denshi; JTADF7 -34C3 E0101; Moji_Joho; MJ000157 -34C7 E0100; Adobe-Japan1; CID+17307 -34C7 E0101; Hanyo-Denshi; JD0315 -34C7 E0102; Hanyo-Denshi; TK01008590 -34CC E0100; Hanyo-Denshi; IA1015 -34CC E0101; Hanyo-Denshi; TK01008700 -34D7 E0100; Hanyo-Denshi; IA0136 -34D7 E0100; Moji_Joho; MJ000175 -34D7 E0101; Hanyo-Denshi; KS020320 -34D7 E0101; Moji_Joho; MJ000176 -34DB E0100; Adobe-Japan1; CID+15425 -34DE E0100; Hanyo-Denshi; IA1026 -34DE E0100; Moji_Joho; MJ000183 -34DE E0101; Hanyo-Denshi; KS022440 -34DE E0102; Hanyo-Denshi; KS022450 -34DE E0102; Moji_Joho; MJ000184 -34DE E0103; Hanyo-Denshi; KS022460 -34DE E0103; Moji_Joho; MJ000185 -34EE E0100; Hanyo-Denshi; IA1036 -34EE E0101; Hanyo-Denshi; TK01010020 -34F2 E0100; Hanyo-Denshi; IA0141 -34F2 E0101; Hanyo-Denshi; TK01010050 -34F5 E0100; Hanyo-Denshi; IA1042 -34F5 E0100; Moji_Joho; MJ000206 -34F5 E0101; Hanyo-Denshi; KS024690 -34F5 E0101; Moji_Joho; MJ000207 -34F6 E0100; Hanyo-Denshi; IA1043 -34F6 E0100; Moji_Joho; MJ000208 -34F6 E0101; Hanyo-Denshi; KS024700 -34F6 E0101; Moji_Joho; MJ000209 -3515 E0100; Hanyo-Denshi; IA0144 -3515 E0101; Hanyo-Denshi; TK01010390 -351C E0100; Hanyo-Denshi; IA0147 -351C E0100; Moji_Joho; MJ000242 -351C E0101; Hanyo-Denshi; KS027290 -351C E0101; Moji_Joho; MJ000241 -351F E0100; Adobe-Japan1; CID+13865 -351F E0101; Hanyo-Denshi; IA0148 -351F E0101; Moji_Joho; MJ000245 -351F E0102; Hanyo-Denshi; JTAE38 -351F E0102; Moji_Joho; MJ059383 -3520 E0100; Hanyo-Denshi; IA1069 -3520 E0101; Hanyo-Denshi; TK01010820 -3520 E0102; Hanyo-Denshi; TK01010920 -3526 E0100; Hanyo-Denshi; IA0149 -3526 E0101; Hanyo-Denshi; TK01011250 -3526 E0102; Hanyo-Denshi; TK01011300 -3530 E0100; Hanyo-Denshi; IA0152 -3530 E0100; Moji_Joho; MJ000265 -3530 E0101; Hanyo-Denshi; KS030440 -3530 E0101; Moji_Joho; MJ000264 -3531 E0100; Hanyo-Denshi; IA0153 -3531 E0100; Moji_Joho; MJ000266 -3531 E0101; Hanyo-Denshi; JTAE5B -3531 E0101; Moji_Joho; MJ000267 -3534 E0100; Hanyo-Denshi; IA0155 -3534 E0100; Moji_Joho; MJ000269 -3534 E0101; Hanyo-Denshi; KS030960 -3534 E0101; Moji_Joho; MJ000270 -353A E0100; Hanyo-Denshi; IA0157 -353A E0100; Moji_Joho; MJ000276 -353A E0101; Hanyo-Denshi; KS031460 -353A E0101; Moji_Joho; MJ000277 -353A E0102; Moji_Joho; MJ000278 -353E E0100; Adobe-Japan1; CID+14110 -353E E0101; Hanyo-Denshi; IA0159 -353E E0102; Hanyo-Denshi; TK01012370 -3553 E0100; Hanyo-Denshi; IA0161 -3553 E0100; Moji_Joho; MJ000303 -3553 E0101; Hanyo-Denshi; KS035250 -3553 E0101; Moji_Joho; MJ000302 -355B E0100; Moji_Joho; MJ000309 -355B E0101; Moji_Joho; MJ000310 -355C E0100; Moji_Joho; MJ000311 -355C E0101; Moji_Joho; MJ000312 -355D E0100; Adobe-Japan1; CID+17341 -355E E0100; Adobe-Japan1; CID+17342 -3561 E0100; Moji_Joho; MJ000317 -3561 E0101; Moji_Joho; MJ000318 -3563 E0100; Adobe-Japan1; CID+17344 -356E E0100; Adobe-Japan1; CID+17348 -356F E0100; Hanyo-Denshi; IA0170 -356F E0100; Moji_Joho; MJ000332 -356F E0101; Hanyo-Denshi; JTAEB5 -356F E0101; Moji_Joho; MJ000333 -35A6 E0100; Adobe-Japan1; CID+17369 -35A8 E0100; Adobe-Japan1; CID+17371 -35B6 E0100; Hanyo-Denshi; IA0178 -35B6 E0100; Moji_Joho; MJ000381 -35B6 E0101; Hanyo-Denshi; KS044620 -35B6 E0101; Moji_Joho; MJ000380 -35C5 E0100; Adobe-Japan1; CID+17377 -35D4 E0100; Moji_Joho; MJ000405 -35D4 E0101; Moji_Joho; MJ000406 -35D6 E0100; Hanyo-Denshi; IA0183 -35D6 E0100; Moji_Joho; MJ000408 -35D6 E0101; Hanyo-Denshi; JTAEF9 -35D6 E0101; Moji_Joho; MJ000409 -35DA E0100; Adobe-Japan1; CID+17386 -35DE E0100; Adobe-Japan1; CID+20067 -35F4 E0100; Adobe-Japan1; CID+17395 -35F4 E0101; Hanyo-Denshi; JD0434 -35F4 E0101; Moji_Joho; MJ000433 -35F4 E0102; Hanyo-Denshi; IA1205 -35F4 E0102; Moji_Joho; MJ000432 -35FB E0100; Hanyo-Denshi; IB0306 -35FB E0100; Moji_Joho; MJ000437 -35FB E0101; Hanyo-Denshi; IB0635 -35FB E0101; Moji_Joho; MJ000436 -3605 E0100; Adobe-Japan1; CID+17402 -3614 E0100; Adobe-Japan1; CID+19131 -361D E0100; Moji_Joho; MJ000462 -361D E0101; Moji_Joho; MJ000463 -3628 E0100; Hanyo-Denshi; IA1309 -3628 E0101; Hanyo-Denshi; TK01016350 -3634 E0100; Moji_Joho; MJ000485 -3634 E0101; Moji_Joho; MJ000486 -3642 E0100; Hanyo-Denshi; IA1325 -3642 E0101; Hanyo-Denshi; TK01016890 -3644 E0100; Hanyo-Denshi; IA0192 -3644 E0100; Moji_Joho; MJ000499 -3644 E0101; Hanyo-Denshi; JTAF5E -3644 E0101; Moji_Joho; MJ000500 -364A E0100; Adobe-Japan1; CID+17441 -364F E0100; Hanyo-Denshi; KS060680 -364F E0101; Hanyo-Denshi; TK01017230 -3651 E0100; Hanyo-Denshi; IA1335 -3651 E0101; Hanyo-Denshi; TK01017390 -365B E0100; Hanyo-Denshi; IA1342 -365B E0100; Moji_Joho; MJ000519 -365B E0101; Hanyo-Denshi; JTAF74 -365B E0101; Moji_Joho; MJ000520 -365B E0102; Hanyo-Denshi; TK01017280 -3669 E0100; Hanyo-Denshi; IA1354 -3669 E0101; Hanyo-Denshi; TK01017970 -3685 E0100; Hanyo-Denshi; IA1375 -3685 E0101; Hanyo-Denshi; TK01018450 -3687 E0100; Hanyo-Denshi; KS065480 -3687 E0100; Moji_Joho; MJ057255 -3687 E0101; Hanyo-Denshi; KS065500 -3687 E0101; Moji_Joho; MJ000557 -3689 E0100; Hanyo-Denshi; IA0203 -3689 E0100; Moji_Joho; MJ000560 -3689 E0101; Hanyo-Denshi; KS066150 -3689 E0101; Moji_Joho; MJ000559 -3689 E0102; Hanyo-Denshi; TK01018830 -3691 E0100; Adobe-Japan1; CID+17473 -3691 E0101; Hanyo-Denshi; IA0204 -3691 E0101; Moji_Joho; MJ000568 -3691 E0102; Hanyo-Denshi; JTAFBF -3691 E0102; Moji_Joho; MJ000567 -3696 E0100; Adobe-Japan1; CID+17477 -3699 E0100; Adobe-Japan1; CID+17475 -36AB E0100; Hanyo-Denshi; IA1406 -36AB E0101; Hanyo-Denshi; TK01020030 -36C3 E0100; Hanyo-Denshi; IA1426 -36C3 E0101; Hanyo-Denshi; TK01020180 -36C3 E0102; Hanyo-Denshi; TK01020240 -36CF E0100; Adobe-Japan1; CID+17494 -36EE E0100; Moji_Joho; MJ000648 -36EE E0101; Moji_Joho; MJ000649 -36FA E0100; Hanyo-Denshi; IA1468 -36FA E0100; Moji_Joho; MJ000660 -36FA E0101; Hanyo-Denshi; KS074820 -36FA E0101; Moji_Joho; MJ000661 -36FC E0100; Hanyo-Denshi; IA1470 -36FC E0100; Moji_Joho; MJ000663 -36FC E0101; Hanyo-Denshi; KS075180 -36FC E0101; Moji_Joho; MJ000664 -3719 E0100; Hanyo-Denshi; IA1489 -3719 E0101; Hanyo-Denshi; TK01020700 -372F E0100; Hanyo-Denshi; IA1514 -372F E0101; Hanyo-Denshi; TK01020900 -372F E0102; Hanyo-Denshi; TK01020930 -3732 E0100; Hanyo-Denshi; IA1517 -3732 E0100; Moji_Joho; MJ000711 -3732 E0101; Hanyo-Denshi; KS078360 -3732 E0101; Moji_Joho; MJ000712 -3761 E0100; Adobe-Japan1; CID+17528 -3762 E0100; Adobe-Japan1; CID+17529 -3762 E0101; Hanyo-Denshi; JD0805 -3762 E0102; Hanyo-Denshi; TK01022260 -3763 E0100; Hanyo-Denshi; KS082260 -3763 E0101; Hanyo-Denshi; TK01022240 -3763 E0102; Hanyo-Denshi; TK01022300 -3769 E0100; Hanyo-Denshi; KS082760 -3769 E0101; Hanyo-Denshi; TK01022450 -376B E0100; Adobe-Japan1; CID+17533 -376B E0101; Hanyo-Denshi; JD0809 -376B E0102; Hanyo-Denshi; TK01022630 -376C E0100; Adobe-Japan1; CID+17532 -3775 E0100; Adobe-Japan1; CID+17536 -3778 E0100; Hanyo-Denshi; IA0221 -3778 E0100; Moji_Joho; MJ034205 -3778 E0101; Hanyo-Denshi; KS085370 -3778 E0101; Moji_Joho; MJ000778 -378D E0100; Adobe-Japan1; CID+13850 -37A4 E0100; Hanyo-Denshi; IA1639 -37A4 E0101; Hanyo-Denshi; TK01024350 -37B7 E0100; Hanyo-Denshi; IA0227 -37B7 E0100; Moji_Joho; MJ000836 -37B7 E0101; Hanyo-Denshi; KS088980 -37B7 E0101; Moji_Joho; MJ000835 -37C1 E0100; Adobe-Japan1; CID+17550 -37C1 E0101; Hanyo-Denshi; IA0232 -37C1 E0102; Hanyo-Denshi; TK01024680 -37C1 E0103; Hanyo-Denshi; TK01024690 -37D0 E0100; Hanyo-Denshi; KS092070 -37D0 E0100; Moji_Joho; MJ000859 -37D0 E0101; Hanyo-Denshi; KS092330 -37D0 E0101; Moji_Joho; MJ000860 -37DF E0100; Hanyo-Denshi; IA0237 -37DF E0100; Moji_Joho; MJ000873 -37DF E0101; Hanyo-Denshi; JTB079 -37DF E0101; Moji_Joho; MJ000874 -37E2 E0100; Adobe-Japan1; CID+14123 -37E7 E0100; Hanyo-Denshi; IA0240 -37E7 E0100; Moji_Joho; MJ000879 -37E7 E0101; Hanyo-Denshi; KS094210 -37E7 E0101; Moji_Joho; MJ000880 -37E8 E0100; Adobe-Japan1; CID+17570 -37F1 E0100; Hanyo-Denshi; KS094420 -37F1 E0101; Hanyo-Denshi; TK01025570 -37F4 E0100; Adobe-Japan1; CID+17573 -37FD E0100; Adobe-Japan1; CID+17576 -3800 E0100; Adobe-Japan1; CID+17578 -3809 E0100; Hanyo-Denshi; IA0245 -3809 E0100; Moji_Joho; MJ000910 -3809 E0101; Hanyo-Denshi; KS096130 -3809 E0101; Moji_Joho; MJ000911 -3817 E0100; Hanyo-Denshi; IA0251 -3817 E0100; Moji_Joho; MJ000926 -3817 E0101; Hanyo-Denshi; JTB085 -3817 E0101; Moji_Joho; MJ000927 -382F E0100; Adobe-Japan1; CID+17588 -382F E0101; Hanyo-Denshi; IA0254 -382F E0101; Moji_Joho; MJ000946 -382F E0102; Hanyo-Denshi; KS099080 -382F E0102; Moji_Joho; MJ000944 -382F E0103; Hanyo-Denshi; JD0879 -382F E0103; Moji_Joho; MJ000945 -3836 E0100; Adobe-Japan1; CID+17589 -3836 E0101; Hanyo-Denshi; JD0881 -3836 E0101; Moji_Joho; MJ000951 -3836 E0102; Hanyo-Denshi; JTB09F -3836 E0102; Moji_Joho; MJ059541 -3836 E0103; Hanyo-Denshi; TK01026830 -3840 E0100; Adobe-Japan1; CID+17590 -384C E0100; Hanyo-Denshi; IA0256 -384C E0100; Moji_Joho; MJ000973 -384C E0101; Hanyo-Denshi; IB0669 -384C E0101; Moji_Joho; MJ000974 -3855 E0100; Hanyo-Denshi; KS101790 -3855 E0101; Hanyo-Denshi; TK01027100 -385B E0100; Hanyo-Denshi; KS102110 -385B E0100; Moji_Joho; MJ000988 -385B E0101; Hanyo-Denshi; KS102300 -385B E0101; Moji_Joho; MJ000989 -385C E0100; Adobe-Japan1; CID+17594 -3861 E0100; Adobe-Japan1; CID+17596 -3862 E0100; Hanyo-Denshi; IA0258 -3862 E0100; Moji_Joho; MJ000996 -3862 E0101; Hanyo-Denshi; JTB0BC -3862 E0101; Moji_Joho; MJ000997 -386D E0100; Moji_Joho; MJ001007 -386D E0101; Moji_Joho; MJ001008 -3895 E0100; Hanyo-Denshi; IA0268 -3895 E0101; Hanyo-Denshi; TK01028200 -38A1 E0100; Adobe-Japan1; CID+20171 -38A2 E0100; Moji_Joho; MJ001058 -38A2 E0101; Moji_Joho; MJ001059 -38A3 E0100; Moji_Joho; MJ001060 -38A3 E0101; Moji_Joho; MJ001061 -38AD E0100; Adobe-Japan1; CID+19132 -38B4 E0100; Hanyo-Denshi; IA0275 -38B4 E0100; Moji_Joho; MJ001075 -38B4 E0101; Hanyo-Denshi; JTB10A -38B4 E0101; Moji_Joho; MJ001076 -38C7 E0100; Hanyo-Denshi; IA1841 -38C7 E0100; Moji_Joho; MJ001092 -38C7 E0101; Hanyo-Denshi; KS112160 -38C7 E0101; Moji_Joho; MJ001093 -38D2 E0100; Hanyo-Denshi; IA1850 -38D2 E0101; Hanyo-Denshi; TK01030370 -38DF E0100; Hanyo-Denshi; IA1857 -38DF E0101; Hanyo-Denshi; TK01030630 -38F7 E0100; Hanyo-Denshi; IA1867 -38F7 E0101; Hanyo-Denshi; TK01031320 -38FA E0100; Adobe-Japan1; CID+13852 -38FA E0101; Moji_Joho; MJ001132 -38FA E0102; Moji_Joho; MJ001133 -38FC E0100; Moji_Joho; MJ001135 -38FC E0101; Moji_Joho; MJ001136 -3900 E0100; Hanyo-Denshi; KS117270 -3900 E0100; Moji_Joho; MJ057490 -3900 E0101; Hanyo-Denshi; KS117330 -3900 E0101; Moji_Joho; MJ057493 -3905 E0100; Moji_Joho; MJ001144 -3905 E0101; Moji_Joho; MJ001145 -3906 E0100; Hanyo-Denshi; IA1876 -3906 E0101; Hanyo-Denshi; TK01031420 -3917 E0100; Adobe-Japan1; CID+17625 -3917 E0101; Hanyo-Denshi; IA0290 -3917 E0101; Moji_Joho; MJ001164 -3917 E0102; Hanyo-Denshi; JTC0E4 -3917 E0102; Moji_Joho; MJ001165 -391A E0100; Adobe-Japan1; CID+17628 -393A E0100; Hanyo-Denshi; IA0304 -393A E0100; Moji_Joho; MJ001199 -393A E0101; Hanyo-Denshi; KS119130 -393A E0101; Moji_Joho; MJ001198 -396F E0100; Adobe-Japan1; CID+17643 -396F E0101; Hanyo-Denshi; JD1264 -396F E0101; Moji_Joho; MJ001247 -396F E0102; Hanyo-Denshi; KS125570 -396F E0102; Moji_Joho; MJ001248 -3971 E0100; Moji_Joho; MJ001250 -3971 E0101; Moji_Joho; MJ001251 -3983 E0100; Hanyo-Denshi; IA1974 -3983 E0101; Hanyo-Denshi; TK01033220 -399E E0100; Hanyo-Denshi; IA0320 -399E E0101; Hanyo-Denshi; TK01034210 -39A2 E0100; Hanyo-Denshi; IA2004 -39A2 E0100; Moji_Joho; MJ001297 -39A2 E0101; Hanyo-Denshi; JT39A2 -39A2 E0101; Moji_Joho; MJ001298 -39A2 E0102; Hanyo-Denshi; TK01033780 -39A2 E0103; Hanyo-Denshi; TK01034160 -39A4 E0100; Adobe-Japan1; CID+20122 -39A5 E0100; Hanyo-Denshi; IA0323 -39A5 E0101; Hanyo-Denshi; TK01034360 -39AE E0100; Hanyo-Denshi; IA0324 -39AE E0100; Moji_Joho; MJ001313 -39AE E0101; Hanyo-Denshi; KS130240 -39AE E0101; Moji_Joho; MJ057537 -39AE E0102; Moji_Joho; MJ001314 -39B6 E0100; Hanyo-Denshi; IA0327 -39B6 E0100; Moji_Joho; MJ001323 -39B6 E0101; Hanyo-Denshi; JTB1CE -39B6 E0101; Moji_Joho; MJ001322 -39B8 E0100; Adobe-Japan1; CID+20123 -39B8 E0101; Moji_Joho; MJ001325 -39B8 E0102; Moji_Joho; MJ057539 -39DE E0100; Hanyo-Denshi; IA0330 -39DE E0100; Moji_Joho; MJ001356 -39DE E0101; Hanyo-Denshi; IB0688S -39DE E0101; Moji_Joho; MJ001357 -39DE E0102; Hanyo-Denshi; TK01035250 -3A17 E0100; Hanyo-Denshi; IA0334 -3A17 E0100; Moji_Joho; MJ001407 -3A17 E0101; Hanyo-Denshi; JTB208 -3A17 E0101; Moji_Joho; MJ001408 -3A28 E0100; Hanyo-Denshi; IA2192 -3A28 E0101; Hanyo-Denshi; TK01035930 -3A2F E0100; Moji_Joho; MJ001429 -3A2F E0101; Moji_Joho; MJ001430 -3A3F E0100; Moji_Joho; MJ001446 -3A3F E0101; Moji_Joho; MJ001447 -3A5C E0100; Adobe-Japan1; CID+20127 -3A6E E0100; Adobe-Japan1; CID+17713 -3A6E E0101; Hanyo-Denshi; IA0341 -3A6E E0101; Moji_Joho; MJ001487 -3A6E E0102; Hanyo-Denshi; IP6511 -3A6E E0102; Moji_Joho; MJ001486 -3A73 E0100; Adobe-Japan1; CID+17716 -3A85 E0100; Adobe-Japan1; CID+20142 -3A9C E0100; Hanyo-Denshi; IA2288 -3A9C E0100; Moji_Joho; MJ001528 -3A9C E0101; Hanyo-Denshi; KS149250 -3A9C E0101; Moji_Joho; MJ057606 -3AA4 E0100; Hanyo-Denshi; IA2301 -3AA4 E0100; Moji_Joho; MJ001537 -3AA4 E0101; Hanyo-Denshi; KS149630 -3AA4 E0101; Moji_Joho; MJ001536 -3AB4 E0100; Hanyo-Denshi; IA2313 -3AB4 E0101; Hanyo-Denshi; TK01037540 -3AC4 E0100; Adobe-Japan1; CID+20135 -3ACB E0100; Adobe-Japan1; CID+20136 -3AD6 E0100; Adobe-Japan1; CID+17731 -3AD7 E0100; Adobe-Japan1; CID+17758 -3AE0 E0100; Hanyo-Denshi; JTB290 -3AE0 E0100; Moji_Joho; MJ001588 -3AE0 E0101; Hanyo-Denshi; IA0359 -3AE0 E0102; Moji_Joho; MJ001589 -3AE6 E0100; Hanyo-Denshi; IA0361 -3AE6 E0100; Moji_Joho; MJ001595 -3AE6 E0101; Hanyo-Denshi; KS156500 -3AE6 E0101; Moji_Joho; MJ001594 -3AEA E0100; Adobe-Japan1; CID+17741 -3AEF E0100; Hanyo-Denshi; IA0365 -3AEF E0101; Hanyo-Denshi; TK01039510 -3AF3 E0100; Adobe-Japan1; CID+15424 -3AF4 E0100; Moji_Joho; MJ001608 -3AF4 E0101; Moji_Joho; MJ001609 -3AF7 E0100; Hanyo-Denshi; IA0369 -3AF7 E0100; Moji_Joho; MJ001613 -3AF7 E0101; Hanyo-Denshi; KS157460 -3AF7 E0101; Moji_Joho; MJ001612 -3B05 E0100; Hanyo-Denshi; IA2357 -3B05 E0101; Hanyo-Denshi; TK01040200 -3B08 E0100; Hanyo-Denshi; IB2026 -3B08 E0100; Moji_Joho; MJ001627 -3B08 E0101; Hanyo-Denshi; KS158740 -3B08 E0101; Moji_Joho; MJ001628 -3B0A E0100; Hanyo-Denshi; IA0372 -3B0A E0100; Moji_Joho; MJ001630 -3B0A E0101; Hanyo-Denshi; JT3B0A -3B0A E0101; Moji_Joho; MJ001631 -3B0E E0100; Adobe-Japan1; CID+17752 -3B15 E0100; Hanyo-Denshi; TK01040230 -3B15 E0101; Hanyo-Denshi; TK01040590 -3B19 E0100; Hanyo-Denshi; IA2372 -3B19 E0101; Hanyo-Denshi; TK01040670 -3B1A E0100; Adobe-Japan1; CID+17756 -3B1C E0100; Adobe-Japan1; CID+17757 -3B1C E0101; Hanyo-Denshi; IA0374 -3B1C E0102; Hanyo-Denshi; TK01040820 -3B1D E0100; Hanyo-Denshi; IA0375 -3B1D E0100; Moji_Joho; MJ001649 -3B1D E0101; Hanyo-Denshi; IB2038 -3B1D E0101; Moji_Joho; MJ001650 -3B22 E0100; Adobe-Japan1; CID+15433 -3B26 E0100; Hanyo-Denshi; IA0378 -3B26 E0100; Moji_Joho; MJ001659 -3B26 E0101; Hanyo-Denshi; KS160390 -3B26 E0101; Moji_Joho; MJ001658 -3B27 E0100; Hanyo-Denshi; IA0602 -3B27 E0100; Moji_Joho; MJ001660 -3B27 E0101; Hanyo-Denshi; JT3B27 -3B27 E0101; Moji_Joho; MJ001661 -3B27 E0102; Hanyo-Denshi; JTB85C -3B27 E0102; Moji_Joho; MJ001662 -3B2D E0100; Hanyo-Denshi; IA2383 -3B2D E0101; Hanyo-Denshi; TK01040970 -3B36 E0100; Hanyo-Denshi; IA0381 -3B36 E0101; Hanyo-Denshi; TK01042000 -3B3C E0100; Hanyo-Denshi; IA0382 -3B3C E0100; Moji_Joho; MJ001683 -3B3C E0101; Hanyo-Denshi; KS162030 -3B3C E0101; Moji_Joho; MJ001682 -3B52 E0100; Hanyo-Denshi; IA2410 -3B52 E0100; Moji_Joho; MJ001696 -3B52 E0101; Hanyo-Denshi; KS165470 -3B52 E0101; Moji_Joho; MJ057714 -3B5B E0100; Hanyo-Denshi; IA2415 -3B5B E0101; Hanyo-Denshi; TK01043800 -3B69 E0100; Hanyo-Denshi; IA2423 -3B69 E0101; Hanyo-Denshi; TK01044190 -3B69 E0102; Hanyo-Denshi; TK01044390 -3B6D E0100; Adobe-Japan1; CID+17804 -3B74 E0100; Hanyo-Denshi; IA0391 -3B74 E0100; Moji_Joho; MJ001726 -3B74 E0101; Hanyo-Denshi; JTB32B -3B74 E0101; Moji_Joho; MJ001727 -3B77 E0100; Adobe-Japan1; CID+17797 -3B78 E0100; Hanyo-Denshi; IA0392 -3B78 E0100; Moji_Joho; MJ001730 -3B78 E0101; Hanyo-Denshi; KS168370 -3B78 E0101; Moji_Joho; MJ001729 -3B87 E0100; Adobe-Japan1; CID+17826 -3B88 E0100; Adobe-Japan1; CID+13965 -3B8D E0100; Adobe-Japan1; CID+17828 -3B8D E0101; Hanyo-Denshi; JD1512 -3B8D E0102; Hanyo-Denshi; TK01045160 -3B91 E0100; Hanyo-Denshi; IA2450 -3B91 E0101; Hanyo-Denshi; TK01044010 -3BA4 E0100; Adobe-Japan1; CID+17834 -3BA4 E0101; Hanyo-Denshi; JD1520 -3BA4 E0102; Hanyo-Denshi; TK01045380 -3BAB E0100; Hanyo-Denshi; IA2470 -3BAB E0101; Hanyo-Denshi; TK01045670 -3BAE E0100; Hanyo-Denshi; IA2473 -3BAE E0100; Moji_Joho; MJ001784 -3BAE E0101; Hanyo-Denshi; KS173700 -3BAE E0101; Moji_Joho; MJ057785 -3BB5 E0100; Hanyo-Denshi; IA0404 -3BB5 E0100; Moji_Joho; MJ001792 -3BB5 E0101; Hanyo-Denshi; KS173070 -3BB5 E0101; Moji_Joho; MJ001791 -3BB6 E0100; Adobe-Japan1; CID+16910 -3BB8 E0100; Hanyo-Denshi; IB0715 -3BB8 E0100; Moji_Joho; MJ001795 -3BB8 E0101; Hanyo-Denshi; JTB35F -3BB8 E0101; Moji_Joho; MJ001796 -3BC3 E0100; Adobe-Japan1; CID+16911 -3BCD E0100; Adobe-Japan1; CID+17848 -3BCD E0101; Hanyo-Denshi; JD1540 -3BCD E0101; Moji_Joho; MJ001814 -3BCD E0102; Hanyo-Denshi; JTB368 -3BCD E0102; Moji_Joho; MJ057784 -3BEC E0100; Moji_Joho; MJ001840 -3BEC E0101; Moji_Joho; MJ001841 -3BF0 E0100; Adobe-Japan1; CID+17865 -3BF3 E0100; Adobe-Japan1; CID+20151 -3BF3 E0101; Hanyo-Denshi; IA0412 -3BF3 E0101; Moji_Joho; MJ001848 -3BF3 E0102; Hanyo-Denshi; KS177780 -3BF3 E0102; Moji_Joho; MJ001849 -3BFE E0100; Hanyo-Denshi; IB0319 -3BFE E0100; Moji_Joho; MJ001855 -3BFE E0101; Hanyo-Denshi; IB0723 -3BFE E0101; Moji_Joho; MJ001854 -3C05 E0100; Hanyo-Denshi; IB0320 -3C05 E0100; Moji_Joho; MJ001863 -3C05 E0101; Hanyo-Denshi; JTB3B4 -3C05 E0101; Moji_Joho; MJ001862 -3C0D E0100; Hanyo-Denshi; IA2548 -3C0D E0100; Moji_Joho; MJ001870 -3C0D E0101; Hanyo-Denshi; KS180330 -3C0D E0101; Moji_Joho; MJ001871 -3C0F E0100; Adobe-Japan1; CID+16919 -3C1B E0100; Hanyo-Denshi; KS181050 -3C1B E0101; Hanyo-Denshi; TK01047210 -3C26 E0100; Adobe-Japan1; CID+17887 -3C4E E0100; Hanyo-Denshi; IA2609 -3C4E E0100; Moji_Joho; MJ001937 -3C4E E0101; Hanyo-Denshi; KS184420 -3C4E E0101; Moji_Joho; MJ001936 -3C4F E0100; Hanyo-Denshi; IA0423 -3C4F E0100; Moji_Joho; MJ001938 -3C4F E0101; Hanyo-Denshi; KS184580 -3C4F E0101; Moji_Joho; MJ057890 -3C73 E0100; Hanyo-Denshi; IA2637 -3C73 E0101; Hanyo-Denshi; KS187680 -3C8A E0100; Hanyo-Denshi; IA0426 -3C8A E0100; Moji_Joho; MJ001992 -3C8A E0101; Hanyo-Denshi; KS189320 -3C8A E0101; Moji_Joho; MJ001991 -3CBA E0100; Hanyo-Denshi; IA2702 -3CBA E0101; Hanyo-Denshi; TK01048280 -3CC3 E0100; Adobe-Japan1; CID+17916 -3CD2 E0100; Adobe-Japan1; CID+17921 -3CDF E0100; Hanyo-Denshi; IA0438 -3CDF E0100; Moji_Joho; MJ002064 -3CDF E0101; Hanyo-Denshi; JTB42BS -3CDF E0101; Moji_Joho; MJ002066 -3CDF E0102; Moji_Joho; MJ002065 -3CE4 E0100; Hanyo-Denshi; IA2722 -3CE4 E0100; Moji_Joho; MJ002067 -3CE4 E0101; Hanyo-Denshi; KS198370 -3CE4 E0101; Moji_Joho; MJ002068 -3CF8 E0100; Hanyo-Denshi; IA2804 -3CF8 E0101; Hanyo-Denshi; KS198930 -3CFD E0100; Hanyo-Denshi; IB2232 -3CFD E0101; Hanyo-Denshi; TK01049980 -3D00 E0100; Hanyo-Denshi; IA0442 -3D00 E0100; Moji_Joho; MJ002093 -3D00 E0101; Hanyo-Denshi; KS199680 -3D00 E0101; Moji_Joho; MJ002094 -3D04 E0100; Hanyo-Denshi; IA2814 -3D04 E0100; Moji_Joho; MJ002099 -3D04 E0101; Hanyo-Denshi; KS198350 -3D04 E0101; Moji_Joho; MJ002098 -3D0A E0100; Hanyo-Denshi; IA2819 -3D0A E0101; Hanyo-Denshi; TK01049870 -3D11 E0100; Adobe-Japan1; CID+17957 -3D1B E0100; Moji_Joho; MJ002118 -3D1B E0101; Moji_Joho; MJ002119 -3D1E E0100; Adobe-Japan1; CID+17968 -3D1E E0101; Hanyo-Denshi; IA0443 -3D1E E0101; Moji_Joho; MJ002123 -3D1E E0102; Hanyo-Denshi; JTB45B -3D1E E0102; Moji_Joho; MJ002122 -3D20 E0100; Hanyo-Denshi; IA0444 -3D20 E0101; Hanyo-Denshi; TK01050370 -3D31 E0100; Adobe-Japan1; CID+20158 -3D31 E0101; Moji_Joho; MJ002139 -3D31 E0102; Moji_Joho; MJ002140 -3D41 E0100; Hanyo-Denshi; IA2858 -3D41 E0101; Hanyo-Denshi; KS204600 -3D4E E0100; Adobe-Japan1; CID+7655 -3D5D E0100; Moji_Joho; MJ002176 -3D5D E0101; Moji_Joho; MJ002177 -3D64 E0100; Adobe-Japan1; CID+17994 -3D64 E0101; Hanyo-Denshi; IA0453 -3D64 E0102; Hanyo-Denshi; TK01053100 -3D67 E0100; Hanyo-Denshi; IA0454 -3D67 E0100; Moji_Joho; MJ002187 -3D67 E0101; Hanyo-Denshi; KS207740 -3D67 E0101; Moji_Joho; MJ002188 -3D69 E0100; Hanyo-Denshi; IA2886 -3D69 E0101; Hanyo-Denshi; KS207840 -3D6A E0100; Hanyo-Denshi; IA2887 -3D6A E0101; Hanyo-Denshi; TK01052420 -3D6A E0102; Hanyo-Denshi; TK01052850 -3D7E E0100; Hanyo-Denshi; IB0323 -3D7E E0100; Moji_Joho; MJ002213 -3D7E E0101; Hanyo-Denshi; IB0736 -3D7E E0101; Moji_Joho; MJ002214 -3D80 E0100; Hanyo-Denshi; IA2911 -3D80 E0100; Moji_Joho; MJ002216 -3D80 E0101; Hanyo-Denshi; JT3D80 -3D80 E0101; Moji_Joho; MJ002217 -3D87 E0100; Hanyo-Denshi; IA2916 -3D87 E0101; Hanyo-Denshi; TK01053650 -3D93 E0100; Hanyo-Denshi; IA0458 -3D93 E0100; Moji_Joho; MJ002231 -3D93 E0101; Hanyo-Denshi; KS211230 -3D93 E0101; Moji_Joho; MJ002230 -3D98 E0100; Hanyo-Denshi; IA2926 -3D98 E0101; Hanyo-Denshi; JTB7E3 -3D9A E0100; Adobe-Japan1; CID+18008 -3DA7 E0100; Hanyo-Denshi; IA2936 -3DA7 E0101; Hanyo-Denshi; TK01054240 -3DB3 E0100; Hanyo-Denshi; IA2944 -3DB3 E0100; Moji_Joho; MJ002258 -3DB3 E0101; Hanyo-Denshi; KS214450 -3DB3 E0101; Moji_Joho; MJ057991 -3DC0 E0100; Adobe-Japan1; CID+18026 -3DC0 E0101; Hanyo-Denshi; IA0461 -3DC0 E0101; Moji_Joho; MJ002269 -3DC0 E0102; Hanyo-Denshi; KS215050 -3DC0 E0102; Moji_Joho; MJ002268 -3DCC E0100; Adobe-Japan1; CID+19133 -3DD4 E0100; Adobe-Japan1; CID+18031 -3DD4 E0101; Hanyo-Denshi; IA0463 -3DD4 E0101; Moji_Joho; MJ002287 -3DD4 E0102; Hanyo-Denshi; KS216430 -3DD4 E0102; Moji_Joho; MJ002286 -3DD5 E0100; Hanyo-Denshi; IA2966 -3DD5 E0101; Hanyo-Denshi; TK01055100 -3DD5 E0102; Hanyo-Denshi; TK01055150 -3DDF E0100; Hanyo-Denshi; IB0324 -3DDF E0100; Moji_Joho; MJ002294 -3DDF E0101; Hanyo-Denshi; IB0740 -3DDF E0101; Moji_Joho; MJ002293 -3DEC E0100; Hanyo-Denshi; IA2977 -3DEC E0101; Hanyo-Denshi; KS217740 -3DED E0100; Hanyo-Denshi; IB0325 -3DED E0100; Moji_Joho; MJ002306 -3DED E0101; Hanyo-Denshi; IB0742 -3DED E0101; Moji_Joho; MJ002305 -3DF1 E0100; Hanyo-Denshi; IA0465 -3DF1 E0100; Moji_Joho; MJ002310 -3DF1 E0101; Hanyo-Denshi; KS217650 -3DF1 E0101; Moji_Joho; MJ058003 -3E02 E0100; Hanyo-Denshi; IB0326 -3E02 E0100; Moji_Joho; MJ002325 -3E02 E0101; Hanyo-Denshi; IB0746 -3E02 E0101; Moji_Joho; MJ002324 -3E05 E0100; Adobe-Japan1; CID+18043 -3E0F E0100; Hanyo-Denshi; IA0466 -3E0F E0100; Moji_Joho; MJ002335 -3E0F E0101; Hanyo-Denshi; JTB560 -3E0F E0101; Moji_Joho; MJ002336 -3E14 E0100; Hanyo-Denshi; KS260370 -3E14 E0100; Moji_Joho; MJ058161 -3E14 E0101; Hanyo-Denshi; KS261060 -3E14 E0101; Moji_Joho; MJ058168 -3E35 E0100; Hanyo-Denshi; IA3039 -3E35 E0101; Hanyo-Denshi; TK01057100 -3E37 E0100; Hanyo-Denshi; IA3041 -3E37 E0100; Moji_Joho; MJ002374 -3E37 E0101; Hanyo-Denshi; KS225220 -3E37 E0101; Moji_Joho; MJ002375 -3E3F E0100; Adobe-Japan1; CID+16968 -3E40 E0100; Adobe-Japan1; CID+20170 -3E60 E0100; Adobe-Japan1; CID+18059 -3E66 E0100; Adobe-Japan1; CID+18061 -3E68 E0100; Adobe-Japan1; CID+18062 -3E83 E0100; Adobe-Japan1; CID+18069 -3E83 E0101; Hanyo-Denshi; JD8041 -3E83 E0101; Moji_Joho; MJ002447 -3E83 E0102; Hanyo-Denshi; KS230610 -3E83 E0102; Moji_Joho; MJ002448 -3E8A E0100; Adobe-Japan1; CID+15427 -3E94 E0100; Adobe-Japan1; CID+18075 -3E9A E0100; Hanyo-Denshi; IB0327 -3E9A E0100; Moji_Joho; MJ002469 -3E9A E0101; Hanyo-Denshi; IB0751 -3E9A E0101; Moji_Joho; MJ002468 -3EBF E0100; Hanyo-Denshi; IA3152 -3EBF E0101; Hanyo-Denshi; TK01058350 -3EDA E0100; Adobe-Japan1; CID+15432 -3F0B E0100; Hanyo-Denshi; IA0484 -3F0B E0100; Moji_Joho; MJ002551 -3F0B E0101; Hanyo-Denshi; KS239730 -3F0B E0101; Moji_Joho; MJ002550 -3F1B E0100; Hanyo-Denshi; IA3217 -3F1B E0100; Moji_Joho; MJ002567 -3F1B E0101; Hanyo-Denshi; KS241040 -3F1B E0101; Moji_Joho; MJ002568 -3F57 E0100; Adobe-Japan1; CID+18123 -3F72 E0100; Adobe-Japan1; CID+16984 -3F75 E0100; Adobe-Japan1; CID+18137 -3F77 E0100; Adobe-Japan1; CID+18139 -3FAE E0100; Adobe-Japan1; CID+18157 -3FB1 E0100; Adobe-Japan1; CID+14164 -3FC2 E0100; Hanyo-Denshi; IA0490 -3FC2 E0100; Moji_Joho; MJ002721 -3FC2 E0101; Hanyo-Denshi; JTB611 -3FC2 E0101; Moji_Joho; MJ002722 -3FC9 E0100; Adobe-Japan1; CID+18168 -3FCA E0100; Hanyo-Denshi; IA3377 -3FCA E0100; Moji_Joho; MJ002730 -3FCA E0101; Hanyo-Denshi; KS252420 -3FCA E0101; Moji_Joho; MJ002731 -3FD7 E0100; Adobe-Japan1; CID+18173 -3FDC E0100; Adobe-Japan1; CID+19134 -3FDF E0100; Hanyo-Denshi; IA0494 -3FDF E0100; Moji_Joho; MJ002750 -3FDF E0101; Hanyo-Denshi; KS254470 -3FDF E0101; Moji_Joho; MJ002749 -3FE9 E0100; Hanyo-Denshi; IA3408 -3FE9 E0101; Hanyo-Denshi; TK01061920 -3FFC E0100; Hanyo-Denshi; IA3426 -3FFC E0100; Moji_Joho; MJ002780 -3FFC E0101; Hanyo-Denshi; KS257310 -3FFC E0101; Moji_Joho; MJ002781 -4018 E0100; Hanyo-Denshi; IA3452 -4018 E0100; Moji_Joho; MJ002807 -4018 E0101; Hanyo-Denshi; KS260480 -4018 E0101; Moji_Joho; MJ002808 -4039 E0100; Adobe-Japan1; CID+18191 -4048 E0100; Hanyo-Denshi; IA0505 -4048 E0100; Moji_Joho; MJ002856 -4048 E0101; Hanyo-Denshi; KS262130 -4048 E0101; Moji_Joho; MJ002855 -404F E0100; Hanyo-Denshi; IA3504 -404F E0100; Moji_Joho; MJ002863 -404F E0101; Hanyo-Denshi; KS263350 -404F E0101; Moji_Joho; MJ002864 -4050 E0100; Hanyo-Denshi; IA0506 -4050 E0100; Moji_Joho; MJ002865 -4050 E0101; Hanyo-Denshi; KS262880 -4050 E0101; Moji_Joho; MJ002866 -4054 E0100; Hanyo-Denshi; IA3507 -4054 E0101; Hanyo-Denshi; TK01062970 -4058 E0100; Adobe-Japan1; CID+18198 -4071 E0100; Hanyo-Denshi; IA0509 -4071 E0100; Moji_Joho; MJ002897 -4071 E0101; Hanyo-Denshi; JTB661 -4071 E0101; Moji_Joho; MJ059940 -4071 E0102; Hanyo-Denshi; JTB662 -4071 E0102; Moji_Joho; MJ059941 -407E E0100; Hanyo-Denshi; IA3544 -407E E0101; Hanyo-Denshi; KS266100 -407E E0101; Moji_Joho; MJ002911 -407E E0102; Moji_Joho; MJ002910 -408A E0100; Hanyo-Denshi; IA0510 -408A E0101; Hanyo-Denshi; TK01063340 -408A E0102; Hanyo-Denshi; TK01063350 -4093 E0100; Adobe-Japan1; CID+15436 -4096 E0100; Hanyo-Denshi; IA0512 -4096 E0100; Moji_Joho; MJ002936 -4096 E0101; Hanyo-Denshi; JTB670 -4096 E0101; Moji_Joho; MJ002934 -4096 E0102; Hanyo-Denshi; KS268410 -4096 E0102; Moji_Joho; MJ002935 -40AE E0100; Hanyo-Denshi; IA3583 -40AE E0100; Moji_Joho; MJ002960 -40AE E0101; Hanyo-Denshi; KS270280 -40AE E0101; Moji_Joho; MJ002961 -40CD E0100; Hanyo-Denshi; IA0516 -40CD E0100; Moji_Joho; MJ002986 -40CD E0101; Hanyo-Denshi; KS271840 -40CD E0101; Moji_Joho; MJ002985 -40DD E0100; Hanyo-Denshi; IA0517 -40DD E0101; Hanyo-Denshi; TK01064120 -40EE E0100; Hanyo-Denshi; IA3639 -40EE E0101; Hanyo-Denshi; TK01064130 -40FD E0100; Hanyo-Denshi; IB0329 -40FD E0100; Moji_Joho; MJ003032 -40FD E0101; Hanyo-Denshi; IB0767 -40FD E0101; Moji_Joho; MJ003031 -40FE E0100; Hanyo-Denshi; IA0519 -40FE E0100; Moji_Joho; MJ003034 -40FE E0101; Hanyo-Denshi; IB0770 -40FE E0101; Moji_Joho; MJ003033 -4101 E0100; Hanyo-Denshi; IA3653 -4101 E0101; Hanyo-Denshi; TK01064660 -4102 E0100; Hanyo-Denshi; IA0521 -4102 E0100; Moji_Joho; MJ003038 -4102 E0101; Hanyo-Denshi; KS275710 -4102 E0101; Moji_Joho; MJ003039 -4103 E0100; Adobe-Japan1; CID+15439 -4103 E0101; Hanyo-Denshi; IB0779 -4103 E0101; Moji_Joho; MJ003040 -4103 E0102; Hanyo-Denshi; IA0522 -4103 E0103; Moji_Joho; MJ003041 -4104 E0100; Hanyo-Denshi; IB0333 -4104 E0100; Moji_Joho; MJ003043 -4104 E0101; Hanyo-Denshi; IB0785 -4104 E0101; Moji_Joho; MJ003042 -4105 E0100; Adobe-Japan1; CID+18235 -4105 E0101; Hanyo-Denshi; IA0523 -4105 E0101; Moji_Joho; MJ003044 -4105 E0102; Hanyo-Denshi; JD8268 -4105 E0102; Moji_Joho; MJ003045 -4106 E0100; Hanyo-Denshi; IA3654 -4106 E0101; Hanyo-Denshi; TK01064830 -4107 E0100; Hanyo-Denshi; IA0524 -4107 E0100; Moji_Joho; MJ003049 -4107 E0101; Hanyo-Denshi; JTB6E6 -4107 E0101; Moji_Joho; MJ003050 -4107 E0102; Moji_Joho; MJ003048 -410C E0100; Hanyo-Denshi; IA3658 -410C E0101; Hanyo-Denshi; TK01065280 -410D E0100; Hanyo-Denshi; IB0335 -410D E0100; Moji_Joho; MJ003057 -410D E0101; Hanyo-Denshi; JTB6ED -410D E0101; Moji_Joho; MJ003056 -410F E0100; Hanyo-Denshi; IB0336 -410F E0100; Moji_Joho; MJ003060 -410F E0101; Hanyo-Denshi; IB0801 -410F E0101; Moji_Joho; MJ003059 -4112 E0100; Hanyo-Denshi; IA0525 -4112 E0100; Moji_Joho; MJ003064 -4112 E0101; Hanyo-Denshi; KS276970 -4112 E0101; Moji_Joho; MJ003063 -4113 E0100; Hanyo-Denshi; IA3662 -4113 E0101; Hanyo-Denshi; TK01065500 -4120 E0100; Hanyo-Denshi; IB0343 -4120 E0100; Moji_Joho; MJ003078 -4120 E0101; Hanyo-Denshi; IB0824 -4120 E0101; Moji_Joho; MJ003077 -412A E0100; Hanyo-Denshi; IA0527 -412A E0100; Moji_Joho; MJ003088 -412A E0101; Hanyo-Denshi; KS279260 -412A E0101; Moji_Joho; MJ003087 -412F E0100; Hanyo-Denshi; IA3681 -412F E0100; Moji_Joho; MJ003093 -412F E0101; Hanyo-Denshi; KS280550 -412F E0101; Moji_Joho; MJ003094 -4146 E0100; Hanyo-Denshi; IA0531 -4146 E0100; Moji_Joho; MJ003114 -4146 E0101; Hanyo-Denshi; KS280290 -4146 E0101; Moji_Joho; MJ003113 -4148 E0100; Adobe-Japan1; CID+18247 -4148 E0101; Hanyo-Denshi; JD8284 -4148 E0101; Moji_Joho; MJ003117 -4148 E0102; Hanyo-Denshi; KS280540 -4148 E0102; Moji_Joho; MJ003116 -4148 E0103; Hanyo-Denshi; TK01066850 -414F E0100; Adobe-Japan1; CID+18250 -4163 E0100; Adobe-Japan1; CID+18254 -4164 E0100; Hanyo-Denshi; IA3724 -4164 E0101; Hanyo-Denshi; TK01067590 -4165 E0100; Moji_Joho; MJ003146 -4165 E0101; Moji_Joho; MJ003147 -417E E0100; Hanyo-Denshi; IA3747 -417E E0101; Hanyo-Denshi; TK01068200 -4181 E0100; Hanyo-Denshi; IA0539 -4181 E0101; Hanyo-Denshi; TK01068270 -4183 E0100; Hanyo-Denshi; IB0347 -4183 E0100; Moji_Joho; MJ003178 -4183 E0101; Hanyo-Denshi; IB0834 -4183 E0101; Moji_Joho; MJ003177 -4183 E0102; Hanyo-Denshi; TK01068150 -4192 E0100; Hanyo-Denshi; IA0540 -4192 E0100; Moji_Joho; MJ003190 -4192 E0101; Hanyo-Denshi; JTB76D -4192 E0101; Moji_Joho; MJ003191 -4196 E0100; Hanyo-Denshi; IA3764 -4196 E0101; Hanyo-Denshi; TK01068430 -41B3 E0100; Hanyo-Denshi; IB0836 -41B3 E0100; Moji_Joho; MJ003224 -41B3 E0101; Hanyo-Denshi; JTB77F -41B3 E0101; Moji_Joho; MJ003225 -41B4 E0100; Adobe-Japan1; CID+18269 -41B4 E0101; Hanyo-Denshi; JD8319 -41B4 E0102; Hanyo-Denshi; TK01068690 -41BF E0100; Adobe-Japan1; CID+18272 -41CC E0100; Hanyo-Denshi; IA3817 -41CC E0101; Hanyo-Denshi; TK01068920 -41D2 E0100; Hanyo-Denshi; IA0543 -41D2 E0100; Moji_Joho; MJ003258 -41D2 E0101; Hanyo-Denshi; KS288800 -41D2 E0101; Moji_Joho; MJ003257 -41E6 E0100; Adobe-Japan1; CID+18283 -41EE E0100; Adobe-Japan1; CID+18287 -41F1 E0100; Hanyo-Denshi; IA0546 -41F1 E0100; Moji_Joho; MJ003290 -41F1 E0101; Hanyo-Denshi; KS290980 -41F1 E0101; Moji_Joho; MJ003289 -41F3 E0100; Adobe-Japan1; CID+18284 -41F8 E0100; Hanyo-Denshi; IA3853 -41F8 E0101; Hanyo-Denshi; TK01069610 -4207 E0100; Adobe-Japan1; CID+18294 -420E E0100; Adobe-Japan1; CID+18297 -4227 E0100; Hanyo-Denshi; IA0552 -4227 E0100; Moji_Joho; MJ003346 -4227 E0101; Hanyo-Denshi; KS296840 -4227 E0101; Moji_Joho; MJ003345 -422A E0100; Hanyo-Denshi; IA3894 -422A E0100; Moji_Joho; MJ003347 -422A E0101; Hanyo-Denshi; KS295030 -422A E0101; Moji_Joho; MJ003348 -4234 E0100; Hanyo-Denshi; IA0553 -4234 E0101; Hanyo-Denshi; TK01070180 -4240 E0100; Hanyo-Denshi; IA3921 -4240 E0101; Hanyo-Denshi; TK01070160 -4264 E0100; Adobe-Japan1; CID+14176 -4274 E0100; Hanyo-Denshi; IA3968 -4274 E0101; Hanyo-Denshi; TK01070510 -4274 E0102; Hanyo-Denshi; TK01070570 -4275 E0100; Hanyo-Denshi; KS504120 -4275 E0100; Moji_Joho; MJ003424 -4275 E0101; Hanyo-Denshi; KS504190 -4275 E0101; Moji_Joho; MJ003425 -427D E0100; Hanyo-Denshi; IA0560 -427D E0101; Hanyo-Denshi; TK01070680 -4291 E0100; Hanyo-Denshi; IA0563 -4291 E0101; Hanyo-Denshi; TK01070910 -4293 E0100; Adobe-Japan1; CID+15440 -4294 E0100; Hanyo-Denshi; KS302030 -4294 E0101; Hanyo-Denshi; TK01070850 -42A3 E0100; Hanyo-Denshi; IA0567 -42A3 E0101; Hanyo-Denshi; TK01071060 -42AE E0100; Hanyo-Denshi; IA4019 -42AE E0101; Hanyo-Denshi; TK01071130 -42B8 E0100; Hanyo-Denshi; IA4027 -42B8 E0100; Moji_Joho; MJ003496 -42B8 E0101; Hanyo-Denshi; KS304690 -42B8 E0101; Moji_Joho; MJ003497 -42BA E0100; Hanyo-Denshi; IA4028 -42BA E0101; Hanyo-Denshi; JTB819 -42C6 E0100; Adobe-Japan1; CID+18335 -42C6 E0101; Hanyo-Denshi; IA0571 -42C6 E0101; Moji_Joho; MJ003510 -42C6 E0102; Hanyo-Denshi; JD8411 -42C6 E0102; Moji_Joho; MJ003511 -42C6 E0103; Hanyo-Denshi; TK01071510 -42C7 E0100; Hanyo-Denshi; IA0572 -42C7 E0101; Hanyo-Denshi; TK01071470 -42D6 E0100; Adobe-Japan1; CID+18346 -42DA E0100; Hanyo-Denshi; IA4054 -42DA E0101; Hanyo-Denshi; TK01071780 -42DD E0100; Adobe-Japan1; CID+18350 -42E3 E0100; Hanyo-Denshi; IA4060 -42E3 E0100; Moji_Joho; MJ003541 -42E3 E0101; Hanyo-Denshi; KS307630 -42E3 E0101; Moji_Joho; MJ003542 -42E3 E0102; Hanyo-Denshi; TK01071790 -4301 E0100; Hanyo-Denshi; IA4088 -4301 E0100; Moji_Joho; MJ003571 -4301 E0101; Hanyo-Denshi; KS309930 -4301 E0101; Moji_Joho; MJ003572 -4302 E0100; Adobe-Japan1; CID+18364 -4313 E0100; Hanyo-Denshi; IA0580 -4313 E0101; Hanyo-Denshi; KS311240 -4313 E0101; Moji_Joho; MJ003589 -4313 E0102; Moji_Joho; MJ003588 -432B E0100; Adobe-Japan1; CID+18377 -4334 E0100; Hanyo-Denshi; IA4134 -4334 E0100; Moji_Joho; MJ003623 -4334 E0101; Hanyo-Denshi; KS314040 -4334 E0101; Moji_Joho; MJ003624 -4343 E0100; Adobe-Japan1; CID+18379 -4343 E0101; Hanyo-Denshi; JD8465 -4343 E0101; Moji_Joho; MJ003627 -4343 E0102; Hanyo-Denshi; KS314320 -4343 E0102; Moji_Joho; MJ003628 -4359 E0100; Hanyo-Denshi; IA4222 -4359 E0100; Moji_Joho; MJ003649 -4359 E0101; Hanyo-Denshi; KS316060 -4359 E0101; Moji_Joho; MJ003650 -4395 E0100; Hanyo-Denshi; IA4278 -4395 E0101; Hanyo-Denshi; TK01074010 -43A8 E0100; Hanyo-Denshi; IA4294 -43A8 E0101; Hanyo-Denshi; TK01074340 -43A9 E0100; Hanyo-Denshi; IA0588 -43A9 E0100; Moji_Joho; MJ003730 -43A9 E0101; Hanyo-Denshi; KS323160 -43A9 E0101; Moji_Joho; MJ003729 -43AA E0100; Hanyo-Denshi; IA4301 -43AA E0101; Hanyo-Denshi; TK01074350 -43AF E0100; Hanyo-Denshi; IA4304 -43AF E0101; Hanyo-Denshi; TK01074420 -43CA E0100; Hanyo-Denshi; IA0589 -43CA E0100; Moji_Joho; MJ003762 -43CA E0101; Hanyo-Denshi; KS326000 -43CA E0101; Moji_Joho; MJ003763 -43CB E0100; Hanyo-Denshi; IA0590 -43CB E0101; Hanyo-Denshi; TK01032910 -43CB E0102; Hanyo-Denshi; TK01075110 -43D5 E0100; Hanyo-Denshi; IA0591 -43D5 E0100; Moji_Joho; MJ003777 -43D5 E0101; Hanyo-Denshi; KS326950 -43D5 E0101; Moji_Joho; MJ003776 -43D5 E0102; Hanyo-Denshi; TK01075190 -43DC E0100; Hanyo-Denshi; IA4345 -43DC E0101; Hanyo-Denshi; TK01041310 -43EE E0100; Adobe-Japan1; CID+18423 -43F0 E0100; Adobe-Japan1; CID+18426 -43F0 E0101; Hanyo-Denshi; JD8534 -43F0 E0101; Moji_Joho; MJ003807 -43F0 E0102; Hanyo-Denshi; IA4360 -43F0 E0102; Moji_Joho; MJ003806 -4408 E0100; Adobe-Japan1; CID+18432 -440C E0100; Adobe-Japan1; CID+15426 -440C E0101; Hanyo-Denshi; IA0605 -440C E0101; Moji_Joho; MJ003836 -440C E0102; Hanyo-Denshi; KS330260 -440C E0102; Moji_Joho; MJ003835 -4417 E0100; Adobe-Japan1; CID+18434 -441C E0100; Adobe-Japan1; CID+18435 -4422 E0100; Adobe-Japan1; CID+18437 -4453 E0100; Adobe-Japan1; CID+14195 -445B E0100; Adobe-Japan1; CID+17060 -446B E0100; Hanyo-Denshi; IA4474 -446B E0100; Moji_Joho; MJ003927 -446B E0101; Hanyo-Denshi; KS340060 -446B E0101; Moji_Joho; MJ003928 -4476 E0100; Adobe-Japan1; CID+18460 -4476 E0101; Hanyo-Denshi; IA0613 -4476 E0102; Hanyo-Denshi; TK01075970 -447A E0100; Adobe-Japan1; CID+18461 -4491 E0100; Adobe-Japan1; CID+18467 -4493 E0100; Hanyo-Denshi; IA4509 -4493 E0101; Hanyo-Denshi; KS342120 -4494 E0100; Hanyo-Denshi; IA0616 -4494 E0100; Moji_Joho; MJ003965 -4494 E0101; Hanyo-Denshi; KS342200 -4494 E0101; Moji_Joho; MJ003966 -4498 E0100; Hanyo-Denshi; IA4512 -4498 E0101; Hanyo-Denshi; KS342640 -44A0 E0100; Hanyo-Denshi; KS343370 -44A0 E0101; Hanyo-Denshi; TK01076420 -44A2 E0100; Hanyo-Denshi; IA0617 -44A2 E0100; Moji_Joho; MJ003980 -44A2 E0101; Hanyo-Denshi; KS343600 -44A2 E0101; Moji_Joho; MJ003981 -44A7 E0100; Hanyo-Denshi; IA4525 -44A7 E0101; Hanyo-Denshi; KS344620 -44A9 E0100; Hanyo-Denshi; IA0618 -44A9 E0100; Moji_Joho; MJ003989 -44A9 E0101; Hanyo-Denshi; JTB956 -44A9 E0101; Moji_Joho; MJ003990 -44AB E0100; Hanyo-Denshi; IA0619 -44AB E0100; Moji_Joho; MJ003992 -44AB E0101; Hanyo-Denshi; KS345270 -44AB E0101; Moji_Joho; MJ003993 -44B1 E0100; Hanyo-Denshi; IA0620 -44B1 E0100; Moji_Joho; MJ003997 -44B1 E0101; Hanyo-Denshi; KS346270 -44B1 E0101; Moji_Joho; MJ003998 -44B3 E0100; Adobe-Japan1; CID+18494 -44B3 E0101; Hanyo-Denshi; IA0621 -44B3 E0101; Moji_Joho; MJ004000 -44B3 E0102; Hanyo-Denshi; JTB976 -44B3 E0102; Moji_Joho; MJ004001 -44B6 E0100; Hanyo-Denshi; IA0622 -44B6 E0100; Moji_Joho; MJ004004 -44B6 E0101; Hanyo-Denshi; KS346540 -44B6 E0101; Moji_Joho; MJ004005 -44B9 E0100; Hanyo-Denshi; IA0623 -44B9 E0100; Moji_Joho; MJ004010 -44B9 E0101; Hanyo-Denshi; JTB966 -44B9 E0101; Moji_Joho; MJ004008 -44B9 E0102; Hanyo-Denshi; JTB973 -44B9 E0102; Moji_Joho; MJ004011 -44B9 E0103; Hanyo-Denshi; KS346770 -44B9 E0103; Moji_Joho; MJ004009 -44B9 E0104; Hanyo-Denshi; TK01076990 -44BA E0100; Hanyo-Denshi; IA4535 -44BA E0101; Hanyo-Denshi; KS346840 -44BE E0100; Adobe-Japan1; CID+18492 -44BE E0101; Hanyo-Denshi; IA0624 -44BE E0101; Moji_Joho; MJ004018 -44BE E0102; Hanyo-Denshi; KS347240S -44BE E0102; Moji_Joho; MJ004019 -44C1 E0100; Hanyo-Denshi; IA0625 -44C1 E0100; Moji_Joho; MJ004021 -44C1 E0101; Hanyo-Denshi; KS347950 -44C1 E0101; Moji_Joho; MJ004020 -44C6 E0100; Hanyo-Denshi; IA4543 -44C6 E0101; Hanyo-Denshi; KS348170 -44C7 E0100; Hanyo-Denshi; IB2806 -44C7 E0101; Hanyo-Denshi; KS348480 -44CC E0100; Hanyo-Denshi; IA0626 -44CC E0100; Moji_Joho; MJ004034 -44CC E0101; Hanyo-Denshi; KS348720 -44CC E0101; Moji_Joho; MJ004035 -44D0 E0100; Hanyo-Denshi; JT44D0 -44D0 E0100; Moji_Joho; MJ004039 -44D0 E0101; Hanyo-Denshi; KS349030 -44D0 E0101; Moji_Joho; MJ004040 -44D3 E0100; Hanyo-Denshi; IA0628 -44D3 E0100; Moji_Joho; MJ004043 -44D3 E0101; Hanyo-Denshi; KS349390 -44D3 E0101; Moji_Joho; MJ004044 -44D4 E0100; Adobe-Japan1; CID+18493 -44D4 E0101; Hanyo-Denshi; JD8620 -44D4 E0101; Moji_Joho; MJ004045 -44D4 E0102; Hanyo-Denshi; KS349990 -44D4 E0102; Moji_Joho; MJ004046 -44E1 E0100; Hanyo-Denshi; IB2820 -44E1 E0101; Hanyo-Denshi; KS351630 -44E4 E0100; Hanyo-Denshi; IA4564 -44E4 E0101; Hanyo-Denshi; KS351860 -44E6 E0100; Hanyo-Denshi; IA0629 -44E6 E0100; Moji_Joho; MJ004064 -44E6 E0101; Hanyo-Denshi; KS352010 -44E6 E0101; Moji_Joho; MJ004065 -44E7 E0100; Hanyo-Denshi; KS352090 -44E7 E0101; Hanyo-Denshi; TK01078090 -44EA E0100; Hanyo-Denshi; KS352810S -44EA E0101; Hanyo-Denshi; TK01078570 -44F2 E0100; Hanyo-Denshi; IA0630 -44F2 E0100; Moji_Joho; MJ004072 -44F2 E0101; Hanyo-Denshi; KS353950 -44F2 E0101; Moji_Joho; MJ004073 -44F2 E0102; Hanyo-Denshi; TK01079060 -44F5 E0100; Hanyo-Denshi; IA0631 -44F5 E0100; Moji_Joho; MJ004077 -44F5 E0101; Hanyo-Denshi; KS354080 -44F5 E0101; Moji_Joho; MJ004078 -44F6 E0100; Hanyo-Denshi; IA0632 -44F6 E0101; Hanyo-Denshi; TK01079050 -44FA E0100; Hanyo-Denshi; IA0633 -44FA E0100; Moji_Joho; MJ004084 -44FA E0101; Hanyo-Denshi; KS355110 -44FA E0101; Moji_Joho; MJ004085 -4506 E0100; Hanyo-Denshi; IA0634 -4506 E0100; Moji_Joho; MJ004097 -4506 E0101; Hanyo-Denshi; KS356910 -4506 E0101; Moji_Joho; MJ004098 -4508 E0100; Adobe-Japan1; CID+18524 -4508 E0101; Hanyo-Denshi; IA0635 -4508 E0101; Moji_Joho; MJ004100 -4508 E0102; Hanyo-Denshi; JTBA18 -4508 E0102; Moji_Joho; MJ004101 -450A E0100; Hanyo-Denshi; IA0636 -450A E0100; Moji_Joho; MJ004103 -450A E0101; Hanyo-Denshi; KS357580 -450A E0101; Moji_Joho; MJ004104 -450D E0100; Adobe-Japan1; CID+18520 -450D E0101; Hanyo-Denshi; JD8652 -450D E0102; Hanyo-Denshi; TK01080200 -450F E0100; Hanyo-Denshi; IB0360 -450F E0100; Moji_Joho; MJ004110 -450F E0101; Hanyo-Denshi; IB0867 -450F E0101; Moji_Joho; MJ004109 -4524 E0100; Hanyo-Denshi; IA0637 -4524 E0100; Moji_Joho; MJ004131 -4524 E0101; Hanyo-Denshi; KS360190 -4524 E0101; Moji_Joho; MJ004132 -4525 E0100; Adobe-Japan1; CID+14206 -4525 E0101; Hanyo-Denshi; IA0638 -4525 E0101; Moji_Joho; MJ004133 -4525 E0102; Hanyo-Denshi; JTBA37 -4525 E0102; Moji_Joho; MJ004134 -4531 E0100; Hanyo-Denshi; IA4622 -4531 E0101; Hanyo-Denshi; KS361330 -4532 E0100; Hanyo-Denshi; IA4623 -4532 E0101; Hanyo-Denshi; KS361390 -4535 E0100; Hanyo-Denshi; IA0639 -4535 E0100; Moji_Joho; MJ004148 -4535 E0101; Hanyo-Denshi; KS361450 -4535 E0101; Moji_Joho; MJ004149 -453B E0100; Hanyo-Denshi; IA0640 -453B E0100; Moji_Joho; MJ004155 -453B E0101; Hanyo-Denshi; JTBA4A -453B E0101; Moji_Joho; MJ004156 -453C E0100; Hanyo-Denshi; IA0644 -453C E0100; Moji_Joho; MJ004157 -453C E0101; Hanyo-Denshi; KS362020 -453C E0101; Moji_Joho; MJ004158 -453D E0100; Hanyo-Denshi; IA4631 -453D E0101; Hanyo-Denshi; KS362110 -4540 E0100; Hanyo-Denshi; IA4634 -4540 E0101; Hanyo-Denshi; KS362360 -4543 E0100; Adobe-Japan1; CID+18540 -4543 E0101; Hanyo-Denshi; IA0641 -4543 E0101; Moji_Joho; MJ004166 -4543 E0102; Hanyo-Denshi; JTBA54 -4543 E0102; Moji_Joho; MJ058538 -4543 E0103; Hanyo-Denshi; JTBA47 -4543 E0103; Moji_Joho; MJ004167 -454C E0100; Hanyo-Denshi; IA0642 -454C E0100; Moji_Joho; MJ004177 -454C E0101; Hanyo-Denshi; KS364180 -454C E0101; Moji_Joho; MJ004176 -454C E0102; Moji_Joho; MJ004178 -454F E0100; Hanyo-Denshi; IA4645 -454F E0101; Hanyo-Denshi; KS364780 -455C E0100; Hanyo-Denshi; TK01074070 -455C E0101; Hanyo-Denshi; TK01081430 -455E E0100; Hanyo-Denshi; IA0645 -455E E0100; Moji_Joho; MJ004197 -455E E0101; Hanyo-Denshi; JTBA89 -455E E0101; Moji_Joho; MJ004198 -455E E0102; Hanyo-Denshi; KS366780 -455E E0102; Moji_Joho; MJ004196 -4568 E0100; Hanyo-Denshi; KS368140 -4568 E0101; Hanyo-Denshi; TK01082040 -456A E0100; Hanyo-Denshi; IA4667 -456A E0101; Hanyo-Denshi; KS368310 -4572 E0100; Hanyo-Denshi; KS368900 -4572 E0100; Moji_Joho; MJ004220 -4572 E0101; Hanyo-Denshi; KS368960 -4572 E0101; Moji_Joho; MJ004221 -4576 E0100; Hanyo-Denshi; IA0647 -4576 E0100; Moji_Joho; MJ004226 -4576 E0101; Hanyo-Denshi; JTBAA8 -4576 E0101; Moji_Joho; MJ004225 -457A E0100; Adobe-Japan1; CID+15435 -457A E0101; Hanyo-Denshi; IA0648 -457A E0101; Moji_Joho; MJ004230 -457A E0102; Hanyo-Denshi; KS370040 -457A E0102; Moji_Joho; MJ004231 -457E E0100; Hanyo-Denshi; IA0649 -457E E0100; Moji_Joho; MJ004235 -457E E0101; Hanyo-Denshi; KS370910 -457E E0101; Moji_Joho; MJ004236 -4587 E0100; Hanyo-Denshi; IA0650 -4587 E0100; Moji_Joho; MJ004244 -4587 E0101; Hanyo-Denshi; KS371520 -4587 E0101; Moji_Joho; MJ004245 -458D E0100; Hanyo-Denshi; IA0651 -458D E0100; Moji_Joho; MJ004251 -458D E0101; Hanyo-Denshi; JTBAB2 -458D E0101; Moji_Joho; MJ004252 -458D E0102; Hanyo-Denshi; TK01082710 -458E E0100; Hanyo-Denshi; IA0652 -458E E0100; Moji_Joho; MJ004255 -458E E0101; Hanyo-Denshi; JTBE72 -458E E0101; Moji_Joho; MJ004256 -4594 E0100; Hanyo-Denshi; IA4704 -4594 E0101; Hanyo-Denshi; TK01082920 -4596 E0100; Hanyo-Denshi; IA4706 -4596 E0101; Hanyo-Denshi; TK01082900 -4596 E0102; Hanyo-Denshi; TK01082910 -4598 E0100; Hanyo-Denshi; IA4708 -4598 E0101; Hanyo-Denshi; TK01083050 -4598 E0102; Hanyo-Denshi; TK01083060 -459D E0100; Adobe-Japan1; CID+17108 -459D E0101; Hanyo-Denshi; IA0655 -459D E0101; Moji_Joho; MJ004277 -459D E0102; Hanyo-Denshi; JC9149 -459D E0102; Moji_Joho; MJ004276 -459F E0100; Hanyo-Denshi; IA4802 -459F E0100; Moji_Joho; MJ004279 -459F E0101; Hanyo-Denshi; KS373580 -459F E0101; Moji_Joho; MJ004280 -45B8 E0100; Adobe-Japan1; CID+18592 -45BE E0100; Adobe-Japan1; CID+19135 -45C8 E0100; Hanyo-Denshi; IA4837 -45C8 E0100; Moji_Joho; MJ004319 -45C8 E0101; Hanyo-Denshi; KS378240 -45C8 E0101; Moji_Joho; MJ004320 -45CE E0100; Hanyo-Denshi; IA4844 -45CE E0100; Moji_Joho; MJ004326 -45CE E0101; Hanyo-Denshi; KS379470 -45CE E0101; Moji_Joho; MJ004327 -45CF E0100; Hanyo-Denshi; IA4845 -45CF E0100; Moji_Joho; MJ004328 -45CF E0101; Hanyo-Denshi; KS379520 -45CF E0101; Moji_Joho; MJ058641 -45D7 E0100; Hanyo-Denshi; IA4851 -45D7 E0100; Moji_Joho; MJ004335 -45D7 E0101; Hanyo-Denshi; KS382770 -45D7 E0101; Moji_Joho; MJ004336 -45E5 E0100; Adobe-Japan1; CID+18618 -45E6 E0100; Hanyo-Denshi; IB0373 -45E6 E0100; Moji_Joho; MJ004352 -45E6 E0101; Hanyo-Denshi; IB0880 -45E6 E0101; Moji_Joho; MJ004351 -45EA E0100; Adobe-Japan1; CID+17113 -460D E0100; Hanyo-Denshi; IA0664 -460D E0100; Moji_Joho; MJ004387 -460D E0101; Hanyo-Denshi; KS385700 -460D E0101; Moji_Joho; MJ004388 -460F E0100; Adobe-Japan1; CID+18634 -4610 E0100; Adobe-Japan1; CID+19136 -462F E0100; Hanyo-Denshi; IA4925 -462F E0101; Hanyo-Denshi; TK01083800 -4635 E0100; Hanyo-Denshi; IA4929 -4635 E0101; Hanyo-Denshi; TK01083980 -4638 E0100; Moji_Joho; MJ004426 -4638 E0101; Moji_Joho; MJ004427 -4641 E0100; Adobe-Japan1; CID+18648 -4645 E0100; Hanyo-Denshi; IA4944 -4645 E0100; Moji_Joho; MJ004440 -4645 E0101; Hanyo-Denshi; KS391680 -4645 E0101; Moji_Joho; MJ058700 -465C E0100; Hanyo-Denshi; IB0375 -465C E0100; Moji_Joho; MJ004459 -465C E0101; Hanyo-Denshi; IB0885 -465C E0101; Moji_Joho; MJ004458 -465D E0100; Moji_Joho; MJ004460 -465D E0101; Moji_Joho; MJ004461 -4665 E0100; Adobe-Japan1; CID+15438 -4670 E0100; Hanyo-Denshi; IA4976 -4670 E0100; Moji_Joho; MJ004480 -4670 E0101; Hanyo-Denshi; KS394780 -4670 E0101; Moji_Joho; MJ004479 -4674 E0100; Hanyo-Denshi; IA0674 -4674 E0100; Moji_Joho; MJ004485 -4674 E0101; Hanyo-Denshi; IB2915 -4674 E0101; Moji_Joho; MJ004487 -4674 E0102; Hanyo-Denshi; KS395250 -4674 E0102; Moji_Joho; MJ004486 -4674 E0103; Hanyo-Denshi; KS395330 -4674 E0103; Moji_Joho; MJ058717 -46A1 E0100; Adobe-Japan1; CID+18665 -46AC E0100; Moji_Joho; MJ004539 -46AC E0101; Moji_Joho; MJ004540 -46AE E0100; Adobe-Japan1; CID+15441 -46AF E0100; Adobe-Japan1; CID+18669 -46B0 E0100; Moji_Joho; MJ004544 -46B0 E0101; Moji_Joho; MJ004545 -46CE E0100; Hanyo-Denshi; IA5058 -46CE E0101; Hanyo-Denshi; TK01085040 -46E3 E0100; Hanyo-Denshi; IA5075 -46E3 E0101; Hanyo-Denshi; TK01085190 -4704 E0100; Hanyo-Denshi; KS407130 -4704 E0100; Moji_Joho; MJ004627 -4704 E0101; Hanyo-Denshi; KS408550 -4704 E0101; Moji_Joho; MJ004628 -470C E0100; Adobe-Japan1; CID+18690 -470C E0101; Hanyo-Denshi; JD8875 -470C E0101; Moji_Joho; MJ004636 -470C E0102; Hanyo-Denshi; KS408560 -470C E0102; Moji_Joho; MJ058764 -471A E0100; Hanyo-Denshi; IB0377 -471A E0100; Moji_Joho; MJ004649 -471A E0101; Hanyo-Denshi; IB0892 -471A E0101; Moji_Joho; MJ004648 -471F E0100; Adobe-Japan1; CID+20219 -471F E0101; Moji_Joho; MJ004654 -471F E0102; Moji_Joho; MJ004655 -4722 E0100; Moji_Joho; MJ004658 -4722 E0101; Moji_Joho; MJ004659 -475E E0100; Hanyo-Denshi; IA5177 -475E E0101; Hanyo-Denshi; TK01086630 -475F E0100; Hanyo-Denshi; IA5178 -475F E0100; Moji_Joho; MJ004711 -475F E0101; Hanyo-Denshi; KS415180 -475F E0101; Moji_Joho; MJ004712 -4764 E0100; Adobe-Japan1; CID+18712 -4768 E0100; Hanyo-Denshi; IA0702 -4768 E0100; Moji_Joho; MJ004721 -4768 E0101; Hanyo-Denshi; JTBBC3 -4768 E0101; Moji_Joho; MJ004722 -477C E0100; Hanyo-Denshi; IB0379 -477C E0100; Moji_Joho; MJ004741 -477C E0101; Hanyo-Denshi; IB0904 -477C E0101; Moji_Joho; MJ004742 -4797 E0100; Hanyo-Denshi; IA5225 -4797 E0101; Hanyo-Denshi; TK01087430 -47E6 E0100; Adobe-Japan1; CID+14224 -47E6 E0101; Hanyo-Denshi; IA0710 -47E6 E0101; Moji_Joho; MJ004840 -47E6 E0102; Hanyo-Denshi; KS424680 -47E6 E0102; Moji_Joho; MJ058806 -47FD E0100; Adobe-Japan1; CID+18724 -47FD E0101; Hanyo-Denshi; IA0711 -47FD E0102; Hanyo-Denshi; TK01087720 -4816 E0100; Adobe-Japan1; CID+18734 -481E E0100; Adobe-Japan1; CID+20225 -4844 E0100; Adobe-Japan1; CID+17141 -484E E0100; Adobe-Japan1; CID+18746 -484E E0101; Hanyo-Denshi; IA0715 -484E E0101; Moji_Joho; MJ004939 -484E E0102; Hanyo-Denshi; JD8960 -484E E0102; Moji_Joho; MJ004940 -4871 E0100; Hanyo-Denshi; IA0716 -4871 E0100; Moji_Joho; MJ004976 -4871 E0101; Hanyo-Denshi; KS435580 -4871 E0101; Moji_Joho; MJ004975 -4875 E0100; Hanyo-Denshi; IB0382 -4875 E0100; Moji_Joho; MJ004981 -4875 E0101; Hanyo-Denshi; IB0910 -4875 E0101; Moji_Joho; MJ004980 -4885 E0100; Hanyo-Denshi; IA5451 -4885 E0101; Hanyo-Denshi; TK01088530 -4889 E0100; Hanyo-Denshi; IA0717 -4889 E0100; Moji_Joho; MJ004995 -4889 E0101; Hanyo-Denshi; KS437540 -4889 E0101; Moji_Joho; MJ004994 -488C E0100; Hanyo-Denshi; IB0385 -488C E0100; Moji_Joho; MJ004999 -488C E0101; Hanyo-Denshi; IB0918 -488C E0101; Moji_Joho; MJ004998 -4890 E0100; Hanyo-Denshi; IB0388 -4890 E0100; Moji_Joho; MJ005003 -4890 E0101; Hanyo-Denshi; IB0925 -4890 E0101; Moji_Joho; MJ005002 -4893 E0100; Hanyo-Denshi; IA5507 -4893 E0101; Hanyo-Denshi; TK01088960 -4894 E0100; Hanyo-Denshi; IB0391 -4894 E0100; Moji_Joho; MJ005009 -4894 E0101; Hanyo-Denshi; IB0936 -4894 E0101; Moji_Joho; MJ005008 -4896 E0100; Hanyo-Denshi; IA5509 -4896 E0101; Hanyo-Denshi; TK01088920 -4897 E0100; Hanyo-Denshi; IA0718 -4897 E0101; Hanyo-Denshi; TK01088990 -48A5 E0100; Hanyo-Denshi; TK01089800 -48A5 E0101; Hanyo-Denshi; TK01090140 -48A6 E0100; Hanyo-Denshi; IB0417 -48A6 E0100; Moji_Joho; MJ005030 -48A6 E0101; Hanyo-Denshi; JTBD06 -48A6 E0101; Moji_Joho; MJ005029 -48AB E0100; Hanyo-Denshi; IB0425 -48AB E0100; Moji_Joho; MJ005036 -48AB E0101; Hanyo-Denshi; IB1002 -48AB E0101; Moji_Joho; MJ005035 -48B0 E0100; Hanyo-Denshi; IB0429 -48B0 E0100; Moji_Joho; MJ005042 -48B0 E0101; Hanyo-Denshi; IB1006 -48B0 E0101; Moji_Joho; MJ005041 -48B5 E0100; Adobe-Japan1; CID+18779 -48CA E0100; Hanyo-Denshi; IA5548 -48CA E0101; Hanyo-Denshi; TK01090990 -48D0 E0100; Hanyo-Denshi; IA0722 -48D0 E0100; Moji_Joho; MJ005072 -48D0 E0101; Hanyo-Denshi; KS448540 -48D0 E0101; Moji_Joho; MJ005073 -4921 E0100; Hanyo-Denshi; IA5624 -4921 E0101; Hanyo-Denshi; TK01092060 -4938 E0100; Hanyo-Denshi; IA5637 -4938 E0101; Hanyo-Denshi; TK01093220 -493F E0100; Hanyo-Denshi; IA5643 -493F E0100; Moji_Joho; MJ005179 -493F E0101; Hanyo-Denshi; KS462830 -493F E0101; Moji_Joho; MJ005180 -493F E0102; Hanyo-Denshi; KS462850 -493F E0102; Moji_Joho; MJ005181 -4940 E0100; Hanyo-Denshi; IA5644 -4940 E0101; Hanyo-Denshi; TK01093770 -4943 E0100; Hanyo-Denshi; IA0741 -4943 E0101; Hanyo-Denshi; TK01093910 -494E E0100; Hanyo-Denshi; IA0743 -494E E0100; Moji_Joho; MJ005198 -494E E0101; Hanyo-Denshi; KS463340 -494E E0101; Moji_Joho; MJ005197 -496C E0100; Hanyo-Denshi; IA0746 -496C E0100; Moji_Joho; MJ005225 -496C E0101; Hanyo-Denshi; KS465430 -496C E0101; Moji_Joho; MJ005226 -4995 E0100; Hanyo-Denshi; IA5702 -4995 E0100; Moji_Joho; MJ005252 -4995 E0101; Hanyo-Denshi; KS469670 -4995 E0101; Moji_Joho; MJ005253 -4995 E0102; Hanyo-Denshi; TK01095060 -49A8 E0100; Moji_Joho; MJ005272 -49A8 E0101; Moji_Joho; MJ005273 -49B0 E0100; Adobe-Japan1; CID+17183 -49D3 E0100; Hanyo-Denshi; IA5742 -49D3 E0101; Hanyo-Denshi; TK01095720 -49E2 E0100; Hanyo-Denshi; IA0764 -49E2 E0100; Moji_Joho; MJ005322 -49E2 E0101; Hanyo-Denshi; KS474470 -49E2 E0101; Moji_Joho; MJ005323 -49E7 E0100; Adobe-Japan1; CID+18898 -49FA E0100; Adobe-Japan1; CID+18902 -4A04 E0100; Adobe-Japan1; CID+18907 -4A22 E0100; Moji_Joho; MJ005384 -4A22 E0101; Moji_Joho; MJ005385 -4A24 E0100; Hanyo-Denshi; IB0438 -4A24 E0100; Moji_Joho; MJ005388 -4A24 E0101; Hanyo-Denshi; IB1032 -4A24 E0101; Moji_Joho; MJ005387 -4A28 E0100; Hanyo-Denshi; IB0439 -4A28 E0100; Moji_Joho; MJ005392 -4A28 E0101; Hanyo-Denshi; IB1033 -4A28 E0101; Moji_Joho; MJ005391 -4A29 E0100; Adobe-Japan1; CID+18910 -4A3C E0100; Hanyo-Denshi; IB1041 -4A3C E0100; Moji_Joho; MJ005411 -4A3C E0101; Hanyo-Denshi; JTBEBD -4A3C E0101; Moji_Joho; MJ005412 -4A7F E0100; Hanyo-Denshi; IA5909 -4A7F E0100; Moji_Joho; MJ005477 -4A7F E0101; Hanyo-Denshi; KS487580 -4A7F E0101; Moji_Joho; MJ059013 -4AA7 E0100; Hanyo-Denshi; IA5946 -4AA7 E0100; Moji_Joho; MJ005515 -4AA7 E0101; Hanyo-Denshi; KS490160 -4AA7 E0101; Moji_Joho; MJ005516 -4AAB E0100; Hanyo-Denshi; IA5948 -4AAB E0100; Moji_Joho; MJ005520 -4AAB E0101; Hanyo-Denshi; KS490490 -4AAB E0101; Moji_Joho; MJ005521 -4AB4 E0100; Moji_Joho; MJ005530 -4AB4 E0101; Moji_Joho; MJ005531 -4AB5 E0100; Hanyo-Denshi; IA0777 -4AB5 E0100; Moji_Joho; MJ005533 -4AB5 E0101; Hanyo-Denshi; IA0777S -4AB5 E0101; Moji_Joho; MJ005532 -4ABC E0100; Adobe-Japan1; CID+18934 -4ADD E0100; Moji_Joho; MJ005572 -4ADD E0101; Moji_Joho; MJ005573 -4B12 E0100; Hanyo-Denshi; IA6048 -4B12 E0100; Moji_Joho; MJ005624 -4B12 E0101; Hanyo-Denshi; KS497040 -4B12 E0101; Moji_Joho; MJ059037 -4B13 E0100; Hanyo-Denshi; IA6049 -4B13 E0100; Moji_Joho; MJ005625 -4B13 E0101; Hanyo-Denshi; KS497050 -4B13 E0101; Moji_Joho; MJ005626 -4B19 E0100; Hanyo-Denshi; IA6054 -4B19 E0100; Moji_Joho; MJ005632 -4B19 E0101; Hanyo-Denshi; KS497080 -4B19 E0101; Moji_Joho; MJ005633 -4B1F E0100; Hanyo-Denshi; IA6061 -4B1F E0100; Moji_Joho; MJ005639 -4B1F E0101; Hanyo-Denshi; KS497760 -4B1F E0101; Moji_Joho; MJ005640 -4B22 E0100; Hanyo-Denshi; IA0781 -4B22 E0100; Moji_Joho; MJ005644 -4B22 E0101; Hanyo-Denshi; IB1044 -4B22 E0101; Moji_Joho; MJ005643 -4B2A E0100; Hanyo-Denshi; IB0448 -4B2A E0100; Moji_Joho; MJ005653 -4B2A E0101; Hanyo-Denshi; IB1053 -4B2A E0101; Moji_Joho; MJ005652 -4B2E E0100; Hanyo-Denshi; IB0454 -4B2E E0100; Moji_Joho; MJ005658 -4B2E E0101; Hanyo-Denshi; IB1062 -4B2E E0101; Moji_Joho; MJ005657 -4B30 E0100; Hanyo-Denshi; IA6075 -4B30 E0101; Hanyo-Denshi; TK01098450 -4B33 E0100; Hanyo-Denshi; IB0450 -4B33 E0100; Moji_Joho; MJ005665 -4B33 E0101; Hanyo-Denshi; IB1057 -4B33 E0101; Moji_Joho; MJ005664 -4B34 E0100; Hanyo-Denshi; IB0451 -4B34 E0100; Moji_Joho; MJ005667 -4B34 E0101; Hanyo-Denshi; IB1059 -4B34 E0101; Moji_Joho; MJ005666 -4B36 E0100; Hanyo-Denshi; IA6080 -4B36 E0101; Hanyo-Denshi; TK01098440 -4B38 E0100; Adobe-Japan1; CID+13791 -4B39 E0100; Hanyo-Denshi; IB0456 -4B39 E0100; Moji_Joho; MJ005673 -4B39 E0101; Hanyo-Denshi; IB1066 -4B39 E0101; Moji_Joho; MJ005672 -4B3B E0100; Adobe-Japan1; CID+18958 -4B3B E0101; Hanyo-Denshi; IA0782 -4B3B E0101; Moji_Joho; MJ005675 -4B3B E0102; Hanyo-Denshi; JD9253 -4B3B E0102; Moji_Joho; MJ005676 -4B3C E0100; Hanyo-Denshi; IB0458 -4B3C E0100; Moji_Joho; MJ005678 -4B3C E0101; Hanyo-Denshi; IB1068 -4B3C E0101; Moji_Joho; MJ005677 -4B40 E0100; Hanyo-Denshi; IB0460 -4B40 E0100; Moji_Joho; MJ005683 -4B40 E0101; Hanyo-Denshi; IB1072 -4B40 E0101; Moji_Joho; MJ005682 -4B42 E0100; Hanyo-Denshi; IA6087 -4B42 E0101; Hanyo-Denshi; TK01098490 -4B43 E0100; Hanyo-Denshi; IB0464 -4B43 E0100; Moji_Joho; MJ005688 -4B43 E0101; Hanyo-Denshi; IB1080 -4B43 E0101; Moji_Joho; MJ005687 -4B45 E0100; Hanyo-Denshi; IB0465 -4B45 E0100; Moji_Joho; MJ005691 -4B45 E0101; Hanyo-Denshi; IB1082 -4B45 E0101; Moji_Joho; MJ005690 -4B47 E0100; Hanyo-Denshi; IB0470 -4B47 E0100; Moji_Joho; MJ005694 -4B47 E0101; Hanyo-Denshi; IB1090 -4B47 E0101; Moji_Joho; MJ005693 -4B49 E0100; Hanyo-Denshi; IB0474 -4B49 E0100; Moji_Joho; MJ005697 -4B49 E0101; Hanyo-Denshi; IB1105 -4B49 E0101; Moji_Joho; MJ005696 -4B4B E0100; Hanyo-Denshi; IB0477 -4B4B E0100; Moji_Joho; MJ005700 -4B4B E0101; Hanyo-Denshi; IB1112 -4B4B E0101; Moji_Joho; MJ005699 -4B50 E0100; Hanyo-Denshi; IB0482 -4B50 E0100; Moji_Joho; MJ005705 -4B50 E0101; Hanyo-Denshi; IB1117 -4B50 E0101; Moji_Joho; MJ005704 -4B51 E0100; Hanyo-Denshi; IB0483 -4B51 E0100; Moji_Joho; MJ005707 -4B51 E0101; Hanyo-Denshi; IB1119 -4B51 E0101; Moji_Joho; MJ005706 -4B52 E0100; Hanyo-Denshi; IB0485 -4B52 E0100; Moji_Joho; MJ005709 -4B52 E0101; Hanyo-Denshi; IB1122 -4B52 E0101; Moji_Joho; MJ005708 -4B54 E0100; Hanyo-Denshi; IB0487 -4B54 E0100; Moji_Joho; MJ005712 -4B54 E0101; Hanyo-Denshi; IB1125 -4B54 E0101; Moji_Joho; MJ005711 -4B61 E0100; Hanyo-Denshi; IB0507 -4B61 E0100; Moji_Joho; MJ005725 -4B61 E0101; Hanyo-Denshi; KS503940 -4B61 E0101; Moji_Joho; MJ005724 -4B63 E0100; Hanyo-Denshi; IB0508 -4B63 E0100; Moji_Joho; MJ005728 -4B63 E0101; Hanyo-Denshi; IB1156 -4B63 E0101; Moji_Joho; MJ005727 -4B68 E0100; Hanyo-Denshi; IA6116 -4B68 E0100; Moji_Joho; MJ005734 -4B68 E0101; Hanyo-Denshi; JTBFCD -4B68 E0101; Moji_Joho; MJ005733 -4B69 E0100; Hanyo-Denshi; IB0512S -4B69 E0100; Moji_Joho; MJ005736 -4B69 E0101; Hanyo-Denshi; IB1165S -4B69 E0101; Moji_Joho; MJ005735 -4B7E E0100; Adobe-Japan1; CID+19137 -4BB2 E0100; Hanyo-Denshi; IA0788 -4BB2 E0101; Hanyo-Denshi; TK01099380 -4BC2 E0100; Adobe-Japan1; CID+18995 -4BCA E0100; Adobe-Japan1; CID+18997 -4BD2 E0100; Adobe-Japan1; CID+18999 -4BE8 E0100; Adobe-Japan1; CID+15430 -4BEC E0100; Hanyo-Denshi; IA0793 -4BEC E0100; Moji_Joho; MJ005861 -4BEC E0101; Hanyo-Denshi; JTBFF6 -4BEC E0101; Moji_Joho; MJ005862 -4C17 E0100; Adobe-Japan1; CID+17204 -4C17 E0101; Hanyo-Denshi; IA0802 -4C17 E0101; Moji_Joho; MJ005901 -4C17 E0102; Hanyo-Denshi; JC9430 -4C17 E0102; Moji_Joho; MJ005902 -4C17 E0103; Hanyo-Denshi; JTC000 -4C17 E0103; Moji_Joho; MJ005903 -4C1F E0100; Hanyo-Denshi; IA6280 -4C1F E0101; Hanyo-Denshi; TK01099900 -4C20 E0100; Adobe-Japan1; CID+19016 -4C27 E0100; Hanyo-Denshi; IA6286 -4C27 E0101; Hanyo-Denshi; TK01099940 -4C38 E0100; Adobe-Japan1; CID+19138 -4C50 E0100; Hanyo-Denshi; IA6326 -4C50 E0100; Moji_Joho; MJ005955 -4C50 E0101; Hanyo-Denshi; JT4C50 -4C50 E0101; Moji_Joho; MJ005956 -4C95 E0100; Hanyo-Denshi; IA6388 -4C95 E0100; Moji_Joho; MJ006021 -4C95 E0101; Hanyo-Denshi; KS526710 -4C95 E0101; Moji_Joho; MJ006020 -4CB7 E0100; Hanyo-Denshi; KS174800 -4CB7 E0101; Hanyo-Denshi; TK01046630 -4CC4 E0100; Adobe-Japan1; CID+19076 -4CCE E0100; Hanyo-Denshi; IA6434 -4CCE E0100; Moji_Joho; MJ006068 -4CCE E0101; Hanyo-Denshi; KS531110 -4CCE E0101; Moji_Joho; MJ006069 -4CD1 E0100; Adobe-Japan1; CID+19079 -4CE1 E0100; Adobe-Japan1; CID+19139 -4CE9 E0100; Hanyo-Denshi; IA6458 -4CE9 E0101; Hanyo-Denshi; TK01100930 -4CF1 E0100; Hanyo-Denshi; KS533930 -4CF1 E0100; Moji_Joho; MJ006104 -4CF1 E0101; Hanyo-Denshi; KS535420 -4CF1 E0101; Moji_Joho; MJ006105 -4D07 E0100; Adobe-Japan1; CID+19099 -4D1F E0100; Hanyo-Denshi; IA0815 -4D1F E0100; Moji_Joho; MJ006144 -4D1F E0101; Hanyo-Denshi; KS538690 -4D1F E0101; Moji_Joho; MJ006143 -4D2A E0100; Hanyo-Denshi; IB0515 -4D2A E0100; Moji_Joho; MJ006154 -4D2A E0101; Hanyo-Denshi; IB1175 -4D2A E0101; Moji_Joho; MJ006153 -4D34 E0100; Hanyo-Denshi; IA6525 -4D34 E0100; Moji_Joho; MJ006164 -4D34 E0101; Hanyo-Denshi; KS540590 -4D34 E0101; Moji_Joho; MJ006165 -4D39 E0100; Hanyo-Denshi; IA6530 -4D39 E0100; Moji_Joho; MJ006170 -4D39 E0101; Hanyo-Denshi; KS541140 -4D39 E0101; Moji_Joho; MJ006171 -4D43 E0100; Hanyo-Denshi; IA6541 -4D43 E0100; Moji_Joho; MJ006181 -4D43 E0101; Hanyo-Denshi; KS541640 -4D43 E0101; Moji_Joho; MJ006182 -4D77 E0100; Adobe-Japan1; CID+19115 -4D82 E0100; Hanyo-Denshi; IA6609 -4D82 E0101; Hanyo-Denshi; TK01101480 -4D91 E0100; Hanyo-Denshi; IA0817 -4D91 E0101; Hanyo-Denshi; JTC09D -4DB0 E0100; Hanyo-Denshi; IA0820 -4DB0 E0101; Hanyo-Denshi; JT4DB0 -4DB0 E0101; Moji_Joho; MJ006289 -4DB0 E0102; Moji_Joho; MJ006288 -4E00 E0100; Adobe-Japan1; CID+1200 -4E01 E0100; Adobe-Japan1; CID+3000 -4E02 E0100; Adobe-Japan1; CID+17234 -4E03 E0100; Adobe-Japan1; CID+2275 -4E04 E0100; Adobe-Japan1; CID+14296 -4E05 E0100; Adobe-Japan1; CID+14297 -4E07 E0100; Adobe-Japan1; CID+3754 -4E07 E0101; Hanyo-Denshi; JA4392 -4E07 E0101; Moji_Joho; MJ006300 -4E07 E0102; Hanyo-Denshi; IB0602 -4E07 E0102; Moji_Joho; MJ006301 -4E07 E0103; Hanyo-Denshi; TK01000050 -4E08 E0100; Adobe-Japan1; CID+2510 -4E08 E0101; Adobe-Japan1; CID+13463 -4E08 E0102; Moji_Joho; MJ006303 -4E08 E0103; Moji_Joho; MJ006304 -4E09 E0100; Adobe-Japan1; CID+2174 -4E0A E0100; Adobe-Japan1; CID+2509 -4E0B E0100; Adobe-Japan1; CID+1340 -4E0C E0100; Adobe-Japan1; CID+19140 -4E0D E0100; Adobe-Japan1; CID+3526 -4E0E E0100; Adobe-Japan1; CID+3881 -4E0E E0101; Adobe-Japan1; CID+20073 -4E0E E0102; Hanyo-Denshi; JA4531 -4E0E E0102; Moji_Joho; MJ006310 -4E0E E0103; Hanyo-Denshi; KS000260 -4E0E E0103; Moji_Joho; MJ006311 -4E0E E0104; Hanyo-Denshi; KS000380 -4E0E E0104; Moji_Joho; MJ006312 -4E0F E0100; Adobe-Japan1; CID+17235 -4E10 E0100; Adobe-Japan1; CID+4091 -4E11 E0100; Adobe-Japan1; CID+1233 -4E11 E0101; Hanyo-Denshi; JA1715 -4E11 E0101; Moji_Joho; MJ006315 -4E11 E0102; Hanyo-Denshi; JTAD08 -4E11 E0102; Moji_Joho; MJ006318 -4E11 E0103; Hanyo-Denshi; KS000350 -4E11 E0103; Moji_Joho; MJ056824 -4E11 E0104; Moji_Joho; MJ006320 -4E12 E0100; Adobe-Japan1; CID+17236 -4E12 E0101; Hanyo-Denshi; JB1605 -4E12 E0101; Moji_Joho; MJ006316 -4E12 E0102; Hanyo-Denshi; IB0603 -4E12 E0102; Moji_Joho; MJ006319 -4E12 E0103; Moji_Joho; MJ006317 -4E14 E0100; Adobe-Japan1; CID+1484 -4E15 E0100; Adobe-Japan1; CID+4092 -4E16 E0100; Adobe-Japan1; CID+2632 -4E17 E0100; Adobe-Japan1; CID+4311 -4E18 E0100; Adobe-Japan1; CID+1648 -4E18 E0101; Hanyo-Denshi; JA2154 -4E18 E0102; Hanyo-Denshi; TK01000130 -4E19 E0100; Adobe-Japan1; CID+3594 -4E19 E0101; Adobe-Japan1; CID+14009 -4E19 E0102; Hanyo-Denshi; JA4226 -4E19 E0102; Moji_Joho; MJ006327 -4E19 E0103; Hanyo-Denshi; KS000540 -4E19 E0103; Moji_Joho; MJ006328 -4E19 E0104; Moji_Joho; MJ006329 -4E1E E0100; Adobe-Japan1; CID+2511 -4E1E E0101; Hanyo-Denshi; JA3071 -4E1E E0102; Hanyo-Denshi; TK01000240 -4E1F E0100; Adobe-Japan1; CID+14298 -4E21 E0100; Adobe-Japan1; CID+3974 -4E23 E0100; Adobe-Japan1; CID+19141 -4E24 E0100; Adobe-Japan1; CID+19142 -4E26 E0100; Adobe-Japan1; CID+3602 -4E26 E0101; Adobe-Japan1; CID+20074 -4E26 E0102; Hanyo-Denshi; JA4234 -4E26 E0102; Moji_Joho; MJ006341 -4E26 E0103; Hanyo-Denshi; KS000820 -4E26 E0103; Moji_Joho; MJ006340 -4E26 E0104; Hanyo-Denshi; TK01007400 -4E28 E0100; Adobe-Japan1; CID+8371 -4E29 E0100; Adobe-Japan1; CID+17237 -4E2A E0100; Adobe-Japan1; CID+4093 -4E2B E0100; Adobe-Japan1; CID+14299 -4E2C E0100; Adobe-Japan1; CID+14157 -4E2D E0100; Adobe-Japan1; CID+2980 -4E2D E0101; Hanyo-Denshi; JA3570 -4E2D E0102; Hanyo-Denshi; TK01000430 -4E2E E0100; Adobe-Japan1; CID+17238 -4E2F E0100; Adobe-Japan1; CID+14300 -4E30 E0100; Adobe-Japan1; CID+14301 -4E30 E0101; Adobe-Japan1; CID+15386 -4E30 E0102; Hanyo-Denshi; JB1613 -4E30 E0102; Moji_Joho; MJ006350 -4E30 E0103; Hanyo-Denshi; IB1306 -4E30 E0103; Moji_Joho; MJ006351 -4E31 E0100; Adobe-Japan1; CID+4094 -4E32 E0100; Adobe-Japan1; CID+1778 -4E35 E0100; Adobe-Japan1; CID+21075 -4E35 E0101; Hanyo-Denshi; JB1614 -4E35 E0101; Moji_Joho; MJ006355 -4E35 E0102; Hanyo-Denshi; IB1308 -4E35 E0102; Moji_Joho; MJ006356 -4E36 E0100; Adobe-Japan1; CID+4095 -4E37 E0100; Adobe-Japan1; CID+13981 -4E38 E0100; Adobe-Japan1; CID+1561 -4E38 E0101; Hanyo-Denshi; JA2061 -4E38 E0101; Moji_Joho; MJ006358 -4E38 E0102; Hanyo-Denshi; KS001100 -4E38 E0102; Moji_Joho; MJ006359 -4E39 E0100; Adobe-Japan1; CID+2926 -4E39 E0101; Adobe-Japan1; CID+13914 -4E39 E0102; Moji_Joho; MJ006360 -4E39 E0103; Moji_Joho; MJ056826 -4E3A E0100; Hanyo-Denshi; KS000410 -4E3A E0101; Hanyo-Denshi; TK01000520 -4E3B E0100; Adobe-Japan1; CID+2323 -4E3B E0101; Adobe-Japan1; CID+13812 -4E3B E0102; Hanyo-Denshi; JA2871 -4E3B E0102; Moji_Joho; MJ006362 -4E3B E0103; Hanyo-Denshi; JTAD1E -4E3B E0103; Moji_Joho; MJ006363 -4E3C E0100; Adobe-Japan1; CID+4096 -4E3D E0100; Hanyo-Denshi; IP4E3D -4E3D E0100; Moji_Joho; MJ006365 -4E3D E0101; Hanyo-Denshi; KS001200 -4E3D E0101; Moji_Joho; MJ006366 -4E3D E0102; Hanyo-Denshi; TK01000270 -4E3F E0100; Adobe-Japan1; CID+4097 -4E40 E0100; Adobe-Japan1; CID+14302 -4E41 E0100; Adobe-Japan1; CID+14303 -4E42 E0100; Adobe-Japan1; CID+4098 -4E42 E0101; Moji_Joho; MJ006372 -4E42 E0102; Moji_Joho; MJ006373 -4E42 E0103; Moji_Joho; MJ006374 -4E43 E0100; Adobe-Japan1; CID+3307 -4E44 E0100; Adobe-Japan1; CID+14304 -4E44 E0101; Moji_Joho; MJ006376 -4E44 E0102; Moji_Joho; MJ006377 -4E45 E0100; Adobe-Japan1; CID+1649 -4E45 E0101; Moji_Joho; MJ006378 -4E45 E0102; Moji_Joho; MJ006379 -4E47 E0100; Adobe-Japan1; CID+17239 -4E47 E0101; Hanyo-Denshi; JB1618 -4E47 E0101; Moji_Joho; MJ006381 -4E47 E0102; Hanyo-Denshi; KS001530 -4E47 E0102; Moji_Joho; MJ056858 -4E48 E0100; Adobe-Japan1; CID+14126 -4E4B E0100; Adobe-Japan1; CID+3309 -4E4D E0100; Adobe-Japan1; CID+3259 -4E4E E0100; Adobe-Japan1; CID+1911 -4E4F E0100; Adobe-Japan1; CID+3681 -4E51 E0100; Adobe-Japan1; CID+17241 -4E54 E0100; Hanyo-Denshi; KS067130 -4E54 E0101; Hanyo-Denshi; TK01000650 -4E55 E0100; Adobe-Japan1; CID+6480 -4E55 E0101; Hanyo-Denshi; JA7341 -4E55 E0101; Moji_Joho; MJ006395 -4E55 E0102; Hanyo-Denshi; KS001760 -4E55 E0102; Moji_Joho; MJ006394 -4E55 E0103; Hanyo-Denshi; JTB0A2 -4E55 E0103; Moji_Joho; MJ059544 -4E55 E0104; Hanyo-Denshi; TK01000680 -4E55 E0105; Hanyo-Denshi; TK01026870 -4E55 E0106; Moji_Joho; MJ006396 -4E56 E0100; Adobe-Japan1; CID+4099 -4E57 E0100; Adobe-Japan1; CID+2512 -4E58 E0100; Adobe-Japan1; CID+4100 -4E58 E0101; Hanyo-Denshi; JA4811 -4E58 E0102; Hanyo-Denshi; TK01007640 -4E59 E0100; Adobe-Japan1; CID+1333 -4E5A E0100; Adobe-Japan1; CID+14305 -4E5C E0100; Adobe-Japan1; CID+21076 -4E5D E0100; Adobe-Japan1; CID+1757 -4E5E E0100; Adobe-Japan1; CID+1956 -4E5F E0100; Adobe-Japan1; CID+3829 -4E62 E0100; Adobe-Japan1; CID+4659 -4E63 E0100; Adobe-Japan1; CID+21077 -4E68 E0100; Adobe-Japan1; CID+21078 -4E69 E0100; Adobe-Japan1; CID+17244 -4E6D E0100; Hanyo-Denshi; TK01063480 -4E6D E0101; Hanyo-Denshi; TK01120320 -4E71 E0100; Adobe-Japan1; CID+3930 -4E73 E0100; Adobe-Japan1; CID+3285 -4E73 E0101; Adobe-Japan1; CID+13968 -4E73 E0102; Hanyo-Denshi; JA3893 -4E73 E0102; Moji_Joho; MJ006417 -4E73 E0103; Hanyo-Denshi; JTAD27 -4E73 E0103; Moji_Joho; MJ006416 -4E74 E0100; Adobe-Japan1; CID+21079 -4E75 E0100; Adobe-Japan1; CID+21080 -4E75 E0101; Hanyo-Denshi; JB1626 -4E75 E0101; Moji_Joho; MJ006419 -4E75 E0102; Hanyo-Denshi; JTAD26 -4E75 E0102; Moji_Joho; MJ006420 -4E79 E0100; Adobe-Japan1; CID+19143 -4E7E E0100; Adobe-Japan1; CID+1505 -4E7F E0100; Adobe-Japan1; CID+14306 -4E80 E0100; Adobe-Japan1; CID+1615 -4E80 E0101; Hanyo-Denshi; JA2121 -4E80 E0102; Hanyo-Denshi; TK01101960 -4E82 E0100; Adobe-Japan1; CID+4101 -4E82 E0101; Hanyo-Denshi; JA4812 -4E82 E0101; Moji_Joho; MJ006426 -4E82 E0102; Hanyo-Denshi; JTAD28S -4E82 E0102; Moji_Joho; MJ006427 -4E85 E0100; Adobe-Japan1; CID+4102 -4E86 E0100; Adobe-Japan1; CID+3971 -4E86 E0101; Hanyo-Denshi; JA4627 -4E86 E0102; Hanyo-Denshi; TK01001070 -4E88 E0100; Adobe-Japan1; CID+3879 -4E89 E0100; Adobe-Japan1; CID+2794 -4E8A E0100; Adobe-Japan1; CID+4104 -4E8B E0100; Adobe-Japan1; CID+2244 -4E8C E0100; Adobe-Japan1; CID+3275 -4E8D E0100; Adobe-Japan1; CID+14307 -4E8E E0100; Adobe-Japan1; CID+4107 -4E91 E0100; Adobe-Japan1; CID+1248 -4E92 E0100; Adobe-Japan1; CID+1939 -4E94 E0100; Adobe-Japan1; CID+1938 -4E94 E0101; Hanyo-Denshi; JA2462 -4E94 E0101; Moji_Joho; MJ006444 -4E94 E0102; Hanyo-Denshi; KS000230S -4E94 E0102; Moji_Joho; MJ056822 -4E95 E0100; Adobe-Japan1; CID+1194 -4E96 E0100; Adobe-Japan1; CID+14308 -4E97 E0100; Adobe-Japan1; CID+21081 -4E98 E0100; Adobe-Japan1; CID+4081 -4E98 E0101; Hanyo-Denshi; JA4743 -4E98 E0102; Hanyo-Denshi; TK01001180 -4E99 E0100; Adobe-Japan1; CID+4080 -4E99 E0101; Hanyo-Denshi; JA4742 -4E99 E0102; Hanyo-Denshi; TK01001160 -4E9B E0100; Adobe-Japan1; CID+2083 -4E9C E0100; Adobe-Japan1; CID+1125 -4E9D E0100; Adobe-Japan1; CID+17245 -4E9E E0100; Adobe-Japan1; CID+4108 -4E9F E0100; Adobe-Japan1; CID+4109 -4E9F E0101; Hanyo-Denshi; JA4820 -4E9F E0101; Moji_Joho; MJ006458 -4E9F E0102; Hanyo-Denshi; JTAD14 -4E9F E0102; Moji_Joho; MJ006457 -4E9F E0103; Moji_Joho; MJ006459 -4EA0 E0100; Adobe-Japan1; CID+4110 -4EA0 E0101; Moji_Joho; MJ006460 -4EA0 E0102; Moji_Joho; MJ006461 -4EA1 E0100; Adobe-Japan1; CID+3682 -4EA1 E0101; Adobe-Japan1; CID+14031 -4EA1 E0102; Hanyo-Denshi; JA4320 -4EA1 E0102; Moji_Joho; MJ006463 -4EA1 E0103; Hanyo-Denshi; KS003470 -4EA1 E0103; Moji_Joho; MJ006462 -4EA2 E0100; Adobe-Japan1; CID+4111 -4EA2 E0101; Hanyo-Denshi; JA4822 -4EA2 E0101; Moji_Joho; MJ006464 -4EA2 E0102; Hanyo-Denshi; KS003510 -4EA2 E0102; Moji_Joho; MJ056886 -4EA2 E0103; Hanyo-Denshi; TK01009210 -4EA4 E0100; Adobe-Japan1; CID+1958 -4EA4 E0101; Adobe-Japan1; CID+13439 -4EA4 E0102; Hanyo-Denshi; JA2482 -4EA4 E0102; Moji_Joho; MJ006467 -4EA4 E0103; Hanyo-Denshi; KS003610 -4EA4 E0103; Moji_Joho; MJ006468 -4EA4 E0104; Moji_Joho; MJ006469 -4EA5 E0100; Adobe-Japan1; CID+1195 -4EA5 E0101; Hanyo-Denshi; JA1671 -4EA5 E0101; Moji_Joho; MJ006470 -4EA5 E0102; Hanyo-Denshi; JTAD2B -4EA5 E0102; Moji_Joho; MJ006471 -4EA6 E0100; Adobe-Japan1; CID+3744 -4EA8 E0100; Adobe-Japan1; CID+1686 -4EA8 E0101; Hanyo-Denshi; JA2192 -4EA8 E0101; Moji_Joho; MJ006473 -4EA8 E0102; Hanyo-Denshi; KS003720 -4EA8 E0102; Moji_Joho; MJ056890 -4EAB E0100; Adobe-Japan1; CID+1687 -4EAB E0101; Hanyo-Denshi; JA2193 -4EAB E0101; Moji_Joho; MJ006474 -4EAB E0102; Hanyo-Denshi; KS003860 -4EAB E0102; Moji_Joho; MJ056895 -4EAC E0100; Adobe-Japan1; CID+1688 -4EAD E0100; Adobe-Japan1; CID+3070 -4EAE E0100; Adobe-Japan1; CID+3972 -4EAE E0101; Hanyo-Denshi; JA4628 -4EAE E0101; Moji_Joho; MJ006477 -4EAE E0102; Hanyo-Denshi; IB1321 -4EAE E0102; Moji_Joho; MJ006478 -4EAF E0100; Adobe-Japan1; CID+21082 -4EB0 E0100; Adobe-Japan1; CID+4112 -4EB3 E0100; Adobe-Japan1; CID+4113 -4EB6 E0100; Adobe-Japan1; CID+4114 -4EB6 E0101; Hanyo-Denshi; JA4825 -4EB6 E0101; Moji_Joho; MJ006485 -4EB6 E0102; Hanyo-Denshi; KS004100 -4EB6 E0102; Moji_Joho; MJ006486 -4EB6 E0103; Hanyo-Denshi; IB1322 -4EB6 E0103; Moji_Joho; MJ006487 -4EB7 E0100; Hanyo-Denshi; JTB797 -4EB7 E0100; Moji_Joho; MJ006489 -4EB7 E0101; Hanyo-Denshi; KS288640 -4EB7 E0101; Moji_Joho; MJ006488 -4EB9 E0100; Adobe-Japan1; CID+14309 -4EB9 E0101; Hanyo-Denshi; JB1634 -4EB9 E0101; Moji_Joho; MJ006491 -4EB9 E0102; Hanyo-Denshi; IB1325 -4EB9 E0102; Moji_Joho; MJ006490 -4EB9 E0103; Moji_Joho; MJ006492 -4EBA E0100; Adobe-Japan1; CID+2579 -4EBB E0100; Adobe-Japan1; CID+13856 -4EBC E0100; Adobe-Japan1; CID+17247 -4EC0 E0100; Adobe-Japan1; CID+2372 -4EC1 E0100; Adobe-Japan1; CID+2580 -4EC2 E0100; Adobe-Japan1; CID+4119 -4EC3 E0100; Adobe-Japan1; CID+17248 -4EC4 E0100; Adobe-Japan1; CID+4117 -4EC4 E0101; Hanyo-Denshi; JA4828 -4EC4 E0102; Hanyo-Denshi; TK01012590 -4EC6 E0100; Adobe-Japan1; CID+4118 -4EC7 E0100; Adobe-Japan1; CID+1650 -4EC7 E0101; Hanyo-Denshi; JA2156 -4EC7 E0102; Hanyo-Denshi; TK01002350 -4EC8 E0100; Adobe-Japan1; CID+17249 -4ECA E0100; Adobe-Japan1; CID+2067 -4ECA E0101; Adobe-Japan1; CID+13780 -4ECB E0100; Adobe-Japan1; CID+1392 -4ECB E0101; Hanyo-Denshi; JA1880 -4ECB E0102; Hanyo-Denshi; TK01002230 -4ECD E0100; Adobe-Japan1; CID+4116 -4ECE E0100; Adobe-Japan1; CID+4115 -4ECF E0100; Adobe-Japan1; CID+3577 -4ED0 E0100; Adobe-Japan1; CID+14310 -4ED4 E0100; Adobe-Japan1; CID+2196 -4ED5 E0100; Adobe-Japan1; CID+2195 -4ED6 E0100; Adobe-Japan1; CID+2846 -4ED7 E0100; Adobe-Japan1; CID+4120 -4ED7 E0101; Hanyo-Denshi; JA4831 -4ED7 E0102; Hanyo-Denshi; IB1334S -4ED7 E0102; Moji_Joho; MJ056911 -4ED7 E0103; Moji_Joho; MJ006518 -4ED7 E0104; Moji_Joho; MJ006519 -4ED8 E0100; Adobe-Japan1; CID+3527 -4ED9 E0100; Adobe-Japan1; CID+2699 -4EDA E0100; Adobe-Japan1; CID+17251 -4EDB E0100; Adobe-Japan1; CID+21083 -4EDD E0100; Adobe-Japan1; CID+656 -4EDE E0100; Adobe-Japan1; CID+4121 -4EDE E0101; Hanyo-Denshi; JA4832 -4EDE E0101; Moji_Joho; MJ006526 -4EDE E0102; Hanyo-Denshi; FT2065 -4EDE E0102; Moji_Joho; MJ006527 -4EDF E0100; Adobe-Japan1; CID+4123 -4EE0 E0100; Adobe-Japan1; CID+14311 -4EE1 E0100; Adobe-Japan1; CID+8372 -4EE2 E0100; Adobe-Japan1; CID+21084 -4EE2 E0101; Hanyo-Denshi; JB1641 -4EE2 E0101; Moji_Joho; MJ006531 -4EE2 E0102; Hanyo-Denshi; KS004840 -4EE2 E0102; Moji_Joho; MJ056903 -4EE3 E0100; Adobe-Japan1; CID+2885 -4EE4 E0100; Adobe-Japan1; CID+4009 -4EE4 E0101; Hanyo-Denshi; JA4665 -4EE4 E0101; Moji_Joho; MJ006533 -4EE4 E0102; Hanyo-Denshi; KS004910 -4EE4 E0102; Moji_Joho; MJ056905 -4EE5 E0100; Adobe-Japan1; CID+1166 -4EE8 E0100; Adobe-Japan1; CID+21085 -4EEB E0100; Adobe-Japan1; CID+17250 -4EED E0100; Adobe-Japan1; CID+4122 -4EED E0101; Moji_Joho; MJ006538 -4EED E0102; Moji_Joho; MJ006539 -4EEE E0100; Adobe-Japan1; CID+1342 -4EEF E0100; Adobe-Japan1; CID+21086 -4EF0 E0100; Adobe-Japan1; CID+1724 -4EF1 E0100; Adobe-Japan1; CID+17252 -4EF1 E0101; Hanyo-Denshi; JB1644 -4EF1 E0102; Hanyo-Denshi; TK01003080 -4EF2 E0100; Adobe-Japan1; CID+2981 -4EF3 E0100; Adobe-Japan1; CID+19144 -4EF5 E0100; Adobe-Japan1; CID+17253 -4EF6 E0100; Adobe-Japan1; CID+1861 -4EF7 E0100; Adobe-Japan1; CID+4124 -4EFB E0100; Adobe-Japan1; CID+3290 -4EFC E0100; Adobe-Japan1; CID+8373 -4EFD E0100; Adobe-Japan1; CID+14312 -4EFE E0100; Adobe-Japan1; CID+21087 -4EFF E0100; Adobe-Japan1; CID+14313 -4F00 E0100; Adobe-Japan1; CID+8374 -4F00 E0101; Hanyo-Denshi; JB1650 -4F00 E0101; Moji_Joho; MJ006558 -4F00 E0102; Hanyo-Denshi; IB1332 -4F00 E0102; Moji_Joho; MJ006559 -4F01 E0100; Adobe-Japan1; CID+1575 -4F02 E0100; Adobe-Japan1; CID+21088 -4F03 E0100; Adobe-Japan1; CID+8375 -4F04 E0100; Hanyo-Denshi; IP4F04 -4F04 E0101; Hanyo-Denshi; TK01002780 -4F08 E0100; Adobe-Japan1; CID+21089 -4F09 E0100; Adobe-Japan1; CID+4125 -4F09 E0101; Hanyo-Denshi; JA4836 -4F09 E0102; Hanyo-Denshi; TK01002790 -4F0A E0100; Adobe-Japan1; CID+1167 -4F0A E0101; Hanyo-Denshi; JA1643 -4F0A E0101; Moji_Joho; MJ006569 -4F0A E0102; Hanyo-Denshi; JTAD4D -4F0A E0102; Moji_Joho; MJ059314 -4F0B E0100; Adobe-Japan1; CID+14314 -4F0B E0101; Hanyo-Denshi; JB1654 -4F0B E0101; Moji_Joho; MJ006571 -4F0B E0102; Hanyo-Denshi; JTAD49 -4F0B E0102; Moji_Joho; MJ006570 -4F0C E0100; Adobe-Japan1; CID+19145 -4F0D E0100; Adobe-Japan1; CID+1940 -4F0E E0100; Adobe-Japan1; CID+1576 -4F0F E0100; Adobe-Japan1; CID+3564 -4F10 E0100; Adobe-Japan1; CID+3398 -4F11 E0100; Adobe-Japan1; CID+1651 -4F12 E0100; Adobe-Japan1; CID+21090 -4F15 E0100; Adobe-Japan1; CID+14315 -4F16 E0100; Adobe-Japan1; CID+17254 -4F16 E0101; Hanyo-Denshi; JB1658 -4F16 E0102; Hanyo-Denshi; TK01002960 -4F17 E0100; Adobe-Japan1; CID+21091 -4F17 E0101; Hanyo-Denshi; JB1659 -4F17 E0102; Hanyo-Denshi; TK01002810 -4F19 E0100; Adobe-Japan1; CID+19146 -4F1A E0100; Adobe-Japan1; CID+1393 -4F1C E0100; Adobe-Japan1; CID+4160 -4F1D E0100; Adobe-Japan1; CID+3131 -4F2B E0100; Adobe-Japan1; CID+19147 -4F2E E0100; Adobe-Japan1; CID+19148 -4F2F E0100; Adobe-Japan1; CID+3362 -4F30 E0100; Adobe-Japan1; CID+4127 -4F31 E0100; Adobe-Japan1; CID+19149 -4F33 E0100; Adobe-Japan1; CID+21092 -4F33 E0101; Moji_Joho; MJ006599 -4F33 E0102; Moji_Joho; MJ006600 -4F34 E0100; Adobe-Japan1; CID+3408 -4F34 E0101; Adobe-Japan1; CID+13984 -4F34 E0102; Hanyo-Denshi; JA4028 -4F34 E0102; Moji_Joho; MJ006602 -4F34 E0103; Hanyo-Denshi; JTAD51 -4F34 E0103; Moji_Joho; MJ006601 -4F35 E0100; Adobe-Japan1; CID+21093 -4F35 E0101; Hanyo-Denshi; JB1665 -4F35 E0102; Hanyo-Denshi; TK01003180 -4F36 E0100; Adobe-Japan1; CID+4010 -4F36 E0101; Hanyo-Denshi; JA4666 -4F36 E0101; Moji_Joho; MJ006605 -4F36 E0102; Hanyo-Denshi; KS006490 -4F36 E0102; Moji_Joho; MJ006606 -4F37 E0100; Adobe-Japan1; CID+17256 -4F38 E0100; Adobe-Japan1; CID+2547 -4F39 E0100; Adobe-Japan1; CID+8376 -4F3A E0100; Adobe-Japan1; CID+2197 -4F3B E0100; Adobe-Japan1; CID+14317 -4F3C E0100; Adobe-Japan1; CID+2245 -4F3C E0101; Hanyo-Denshi; JA2787 -4F3C E0102; Hanyo-Denshi; TK01002650 -4F3D E0100; Adobe-Japan1; CID+1344 -4F3E E0100; Adobe-Japan1; CID+17257 -4F40 E0100; Adobe-Japan1; CID+21094 -4F40 E0101; Hanyo-Denshi; JB1670 -4F40 E0101; Moji_Joho; MJ006616 -4F40 E0102; Hanyo-Denshi; JTAD52 -4F40 E0102; Moji_Joho; MJ006617 -4F42 E0100; Adobe-Japan1; CID+21095 -4F43 E0100; Adobe-Japan1; CID+3053 -4F46 E0100; Adobe-Japan1; CID+2912 -4F47 E0100; Adobe-Japan1; CID+4131 -4F48 E0100; Adobe-Japan1; CID+16779 -4F49 E0100; Adobe-Japan1; CID+14318 -4F4B E0100; Adobe-Japan1; CID+21096 -4F4C E0100; Adobe-Japan1; CID+21097 -4F4D E0100; Adobe-Japan1; CID+1168 -4F4E E0100; Adobe-Japan1; CID+3071 -4F4F E0100; Adobe-Japan1; CID+2373 -4F4F E0101; Adobe-Japan1; CID+13820 -4F4F E0102; Hanyo-Denshi; JA2927 -4F4F E0102; Moji_Joho; MJ006632 -4F4F E0103; Hanyo-Denshi; JTAD53 -4F4F E0103; Moji_Joho; MJ006633 -4F50 E0100; Adobe-Japan1; CID+2084 -4F50 E0101; Hanyo-Denshi; JA2620 -4F50 E0102; Hanyo-Denshi; TK01002730 -4F51 E0100; Adobe-Japan1; CID+3854 -4F52 E0100; Adobe-Japan1; CID+21098 -4F53 E0100; Adobe-Japan1; CID+2862 -4F53 E0101; Hanyo-Denshi; JA3446 -4F53 E0101; Moji_Joho; MJ006637 -4F53 E0102; Hanyo-Denshi; KS006410 -4F53 E0102; Moji_Joho; MJ006638 -4F54 E0100; Adobe-Japan1; CID+14319 -4F55 E0100; Adobe-Japan1; CID+1343 -4F56 E0100; Adobe-Japan1; CID+8377 -4F57 E0100; Adobe-Japan1; CID+4130 -4F58 E0100; Adobe-Japan1; CID+17258 -4F59 E0100; Adobe-Japan1; CID+3880 -4F5A E0100; Adobe-Japan1; CID+4126 -4F5B E0100; Adobe-Japan1; CID+4128 -4F5C E0100; Adobe-Japan1; CID+2142 -4F5D E0100; Adobe-Japan1; CID+4129 -4F5E E0100; Adobe-Japan1; CID+4563 -4F5F E0100; Adobe-Japan1; CID+16780 -4F5F E0101; Hanyo-Denshi; JB1680 -4F5F E0102; Hanyo-Denshi; TK01003230 -4F60 E0100; Adobe-Japan1; CID+14316 -4F60 E0101; Adobe-Japan1; CID+15388 -4F60 E0102; Hanyo-Denshi; JB1663 -4F60 E0102; Moji_Joho; MJ006651 -4F60 E0103; Hanyo-Denshi; IB1339 -4F60 E0103; Moji_Joho; MJ006652 -4F60 E0104; Hanyo-Denshi; JTAD50 -4F63 E0100; Adobe-Japan1; CID+21099 -4F64 E0100; Adobe-Japan1; CID+17255 -4F69 E0100; Adobe-Japan1; CID+4137 -4F69 E0101; Hanyo-Denshi; JA4848 -4F69 E0101; Moji_Joho; MJ006658 -4F69 E0102; Hanyo-Denshi; KS006460 -4F69 E0102; Moji_Joho; MJ056914 -4F6A E0100; Adobe-Japan1; CID+16781 -4F6A E0101; Hanyo-Denshi; JB1682 -4F6A E0102; Hanyo-Denshi; KS008520 -4F6C E0100; Adobe-Japan1; CID+16782 -4F6D E0100; Hanyo-Denshi; IP4F6D -4F6D E0100; Moji_Joho; MJ006664 -4F6D E0101; Hanyo-Denshi; KS006630 -4F6D E0101; Moji_Joho; MJ006663 -4F6E E0100; Adobe-Japan1; CID+21100 -4F6F E0100; Adobe-Japan1; CID+4140 -4F70 E0100; Adobe-Japan1; CID+4138 -4F71 E0100; Adobe-Japan1; CID+21101 -4F73 E0100; Adobe-Japan1; CID+1346 -4F73 E0101; Adobe-Japan1; CID+20076 -4F75 E0100; Adobe-Japan1; CID+3595 -4F75 E0101; Adobe-Japan1; CID+13383 -4F76 E0100; Adobe-Japan1; CID+4132 -4F76 E0101; Hanyo-Denshi; JA4843 -4F76 E0102; Hanyo-Denshi; TK01003250 -4F77 E0100; Adobe-Japan1; CID+17260 -4F78 E0100; Adobe-Japan1; CID+17261 -4F79 E0100; Adobe-Japan1; CID+21102 -4F7A E0100; Adobe-Japan1; CID+14320 -4F7A E0101; Hanyo-Denshi; JB1689 -4F7A E0101; Moji_Joho; MJ006678 -4F7A E0102; Hanyo-Denshi; JTAD5A -4F7A E0102; Moji_Joho; MJ006679 -4F7B E0100; Adobe-Japan1; CID+4136 -4F7C E0100; Adobe-Japan1; CID+1959 -4F7C E0101; Moji_Joho; MJ006681 -4F7C E0102; Moji_Joho; MJ006682 -4F7D E0100; Adobe-Japan1; CID+14321 -4F7D E0101; Hanyo-Denshi; JB1690 -4F7D E0101; Moji_Joho; MJ006683 -4F7D E0102; Hanyo-Denshi; IB1346 -4F7D E0102; Moji_Joho; MJ006684 -4F7E E0100; Adobe-Japan1; CID+14322 -4F7E E0101; Hanyo-Denshi; JB1691 -4F7E E0101; Moji_Joho; MJ006686 -4F7E E0102; Hanyo-Denshi; JTAD5C -4F7E E0102; Moji_Joho; MJ006685 -4F7F E0100; Adobe-Japan1; CID+2198 -4F7F E0101; Adobe-Japan1; CID+13450 -4F7F E0102; Moji_Joho; MJ006687 -4F7F E0103; Moji_Joho; MJ006688 -4F81 E0100; Adobe-Japan1; CID+21103 -4F82 E0100; Adobe-Japan1; CID+17262 -4F83 E0100; Adobe-Japan1; CID+1506 -4F83 E0101; Moji_Joho; MJ006692 -4F83 E0102; Moji_Joho; MJ059324 -4F84 E0100; Adobe-Japan1; CID+19150 -4F85 E0100; Adobe-Japan1; CID+17263 -4F86 E0100; Adobe-Japan1; CID+4141 -4F88 E0100; Adobe-Japan1; CID+4133 -4F89 E0100; Adobe-Japan1; CID+21104 -4F89 E0101; Hanyo-Denshi; JB1702 -4F89 E0101; Moji_Joho; MJ006698 -4F89 E0102; Hanyo-Denshi; KS007490 -4F89 E0102; Moji_Joho; MJ056918 -4F8A E0100; Adobe-Japan1; CID+8379 -4F8B E0100; Adobe-Japan1; CID+4011 -4F8C E0100; Adobe-Japan1; CID+21105 -4F8D E0100; Adobe-Japan1; CID+2246 -4F8E E0100; Adobe-Japan1; CID+21106 -4F8F E0100; Adobe-Japan1; CID+4134 -4F90 E0100; Adobe-Japan1; CID+21107 -4F91 E0100; Adobe-Japan1; CID+4139 -4F92 E0100; Adobe-Japan1; CID+8378 -4F93 E0100; Adobe-Japan1; CID+21108 -4F94 E0100; Adobe-Japan1; CID+8381 -4F96 E0100; Adobe-Japan1; CID+4142 -4F96 E0101; Hanyo-Denshi; JA4853 -4F96 E0101; Moji_Joho; MJ006711 -4F96 E0102; Hanyo-Denshi; KS007500 -4F96 E0102; Moji_Joho; MJ056919 -4F96 E0103; Hanyo-Denshi; KS008530 -4F96 E0103; Moji_Joho; MJ056926 -4F97 E0100; Adobe-Japan1; CID+14323 -4F98 E0100; Adobe-Japan1; CID+4135 -4F99 E0100; Adobe-Japan1; CID+21109 -4F9A E0100; Adobe-Japan1; CID+8380 -4F9B E0100; Adobe-Japan1; CID+1689 -4F9C E0100; Hanyo-Denshi; IP4F9C -4F9C E0100; Moji_Joho; MJ006718 -4F9C E0101; Hanyo-Denshi; JT4F9C -4F9C E0101; Moji_Joho; MJ006717 -4F9D E0100; Adobe-Japan1; CID+1169 -4F9E E0100; Adobe-Japan1; CID+19151 -4F9F E0100; Adobe-Japan1; CID+21110 -4FA0 E0100; Adobe-Japan1; CID+1690 -4FA1 E0100; Adobe-Japan1; CID+1345 -4FA1 E0101; Hanyo-Denshi; JA1833 -4FA1 E0101; Moji_Joho; MJ006723 -4FA1 E0102; Hanyo-Denshi; KS007450 -4FA1 E0102; Moji_Joho; MJ056917 -4FAB E0100; Adobe-Japan1; CID+4564 -4FAB E0101; Hanyo-Denshi; JA5305 -4FAB E0101; Moji_Joho; MJ006725 -4FAB E0102; Hanyo-Denshi; JTAFE3S -4FAB E0102; Moji_Joho; MJ006726 -4FAD E0100; Adobe-Japan1; CID+3751 -4FAE E0100; Adobe-Japan1; CID+3552 -4FAE E0101; Adobe-Japan1; CID+13382 -4FAE E0102; Hanyo-Denshi; JA4178 -4FAE E0103; Hanyo-Denshi; JC1424 -4FAF E0100; Adobe-Japan1; CID+1960 -4FAF E0101; Hanyo-Denshi; JA2484 -4FAF E0102; Hanyo-Denshi; TK01004220 -4FB1 E0100; Hanyo-Denshi; IB1358 -4FB1 E0100; Moji_Joho; MJ006732 -4FB1 E0101; Hanyo-Denshi; IP4FB1 -4FB1 E0101; Moji_Joho; MJ006731 -4FB2 E0100; Adobe-Japan1; CID+17265 -4FB5 E0100; Adobe-Japan1; CID+2549 -4FB5 E0101; Adobe-Japan1; CID+13851 -4FB5 E0102; Hanyo-Denshi; JA3115 -4FB5 E0102; Moji_Joho; MJ006737 -4FB5 E0103; Hanyo-Denshi; JTAD63 -4FB5 E0103; Moji_Joho; MJ006736 -4FB6 E0100; Adobe-Japan1; CID+3967 -4FB7 E0100; Adobe-Japan1; CID+19152 -4FB9 E0100; Adobe-Japan1; CID+21111 -4FB9 E0101; Hanyo-Denshi; JB1717 -4FB9 E0101; Moji_Joho; MJ006742 -4FB9 E0102; Hanyo-Denshi; JTAD6E -4FB9 E0102; Moji_Joho; MJ006741 -4FBB E0100; Adobe-Japan1; CID+21112 -4FBB E0101; Hanyo-Denshi; JB1718 -4FBB E0102; Hanyo-Denshi; TK01003430 -4FBB E0103; Hanyo-Denshi; TK01004050 -4FBC E0100; Adobe-Japan1; CID+21113 -4FBD E0100; Adobe-Japan1; CID+21114 -4FBE E0100; Adobe-Japan1; CID+14324 -4FBF E0100; Adobe-Japan1; CID+3624 -4FBF E0101; Adobe-Japan1; CID+13506 -4FBF E0102; Moji_Joho; MJ006749 -4FBF E0103; Moji_Joho; MJ006750 -4FC0 E0100; Adobe-Japan1; CID+21115 -4FC1 E0100; Adobe-Japan1; CID+21116 -4FC2 E0100; Adobe-Japan1; CID+1806 -4FC3 E0100; Adobe-Japan1; CID+2821 -4FC4 E0100; Adobe-Japan1; CID+1380 -4FC5 E0100; Adobe-Japan1; CID+17266 -4FC6 E0100; Adobe-Japan1; CID+21117 -4FC8 E0100; Adobe-Japan1; CID+21118 -4FC8 E0101; Hanyo-Denshi; JB1726 -4FC8 E0102; Hanyo-Denshi; TK01004060 -4FC9 E0100; Adobe-Japan1; CID+8364 -4FCA E0100; Adobe-Japan1; CID+2397 -4FCA E0101; Hanyo-Denshi; JA2951 -4FCA E0101; Moji_Joho; MJ006763 -4FCA E0102; Hanyo-Denshi; KS007990 -4FCA E0102; Moji_Joho; MJ006762 -4FCB E0100; Adobe-Japan1; CID+17267 -4FCC E0100; Adobe-Japan1; CID+21119 -4FCD E0100; Adobe-Japan1; CID+8382 -4FCE E0100; Adobe-Japan1; CID+4146 -4FCF E0100; Adobe-Japan1; CID+14325 -4FD0 E0100; Adobe-Japan1; CID+4151 -4FD1 E0100; Adobe-Japan1; CID+4149 -4FD2 E0100; Adobe-Japan1; CID+17268 -4FD3 E0100; Adobe-Japan1; CID+15407 -4FD4 E0100; Adobe-Japan1; CID+4144 -4FD7 E0100; Adobe-Japan1; CID+2831 -4FD8 E0100; Adobe-Japan1; CID+4147 -4FD8 E0101; Hanyo-Denshi; JA4858 -4FD8 E0101; Moji_Joho; MJ006776 -4FD8 E0102; Hanyo-Denshi; FT2067 -4FD8 E0102; Moji_Joho; MJ006777 -4FDA E0100; Adobe-Japan1; CID+4150 -4FDB E0100; Adobe-Japan1; CID+4148 -4FDC E0100; Adobe-Japan1; CID+21120 -4FDD E0100; Adobe-Japan1; CID+3629 -4FDE E0100; Hanyo-Denshi; IB1361 -4FDE E0100; Moji_Joho; MJ006784 -4FDE E0101; Hanyo-Denshi; IP4FDE -4FDE E0101; Moji_Joho; MJ006783 -4FDE E0102; Hanyo-Denshi; JTAD68 -4FDE E0102; Moji_Joho; MJ006785 -4FDF E0100; Adobe-Japan1; CID+4145 -4FE0 E0100; Adobe-Japan1; CID+7660 -4FE1 E0100; Adobe-Japan1; CID+2548 -4FE2 E0100; Adobe-Japan1; CID+21121 -4FE3 E0100; Adobe-Japan1; CID+3745 -4FE4 E0100; Adobe-Japan1; CID+4152 -4FE5 E0100; Adobe-Japan1; CID+4153 -4FE6 E0100; Adobe-Japan1; CID+17264 -4FEE E0100; Adobe-Japan1; CID+2350 -4FEF E0100; Adobe-Japan1; CID+4166 -4FF0 E0100; Adobe-Japan1; CID+21122 -4FF1 E0100; Adobe-Japan1; CID+13731 -4FF2 E0100; Adobe-Japan1; CID+17270 -4FF3 E0100; Adobe-Japan1; CID+3334 -4FF5 E0100; Adobe-Japan1; CID+3496 -4FF6 E0100; Adobe-Japan1; CID+4161 -4FF8 E0100; Adobe-Japan1; CID+3648 -4FFA E0100; Adobe-Japan1; CID+1334 -4FFC E0100; Adobe-Japan1; CID+21123 -4FFD E0100; Adobe-Japan1; CID+14326 -4FFE E0100; Adobe-Japan1; CID+4165 -4FFF E0100; Adobe-Japan1; CID+8385 -5000 E0100; Adobe-Japan1; CID+14327 -5001 E0100; Adobe-Japan1; CID+14328 -5002 E0100; Adobe-Japan1; CID+20299 -5002 E0101; Hanyo-Denshi; JC1428 -5002 E0101; Moji_Joho; MJ006816 -5002 E0102; Hanyo-Denshi; IP5002 -5002 E0102; Moji_Joho; MJ006815 -5004 E0100; Adobe-Japan1; CID+19153 -5005 E0100; Adobe-Japan1; CID+4159 -5006 E0100; Adobe-Japan1; CID+4168 -5007 E0100; Adobe-Japan1; CID+21124 -5008 E0100; Hanyo-Denshi; IP5008 -5008 E0101; Hanyo-Denshi; TK01004230 -5009 E0100; Adobe-Japan1; CID+2772 -500A E0100; Adobe-Japan1; CID+21125 -500B E0100; Adobe-Japan1; CID+1912 -500C E0100; Adobe-Japan1; CID+19154 -500D E0100; Adobe-Japan1; CID+3346 -500E E0100; Adobe-Japan1; CID+16783 -500F E0100; Adobe-Japan1; CID+5632 -500F E0101; Hanyo-Denshi; JA6439 -500F E0101; Moji_Joho; MJ006829 -500F E0102; Hanyo-Denshi; KS010830 -500F E0102; Moji_Joho; MJ006830 -5010 E0100; Adobe-Japan1; CID+14329 -5010 E0101; Hanyo-Denshi; JB1748 -5010 E0101; Moji_Joho; MJ006831 -5010 E0102; Hanyo-Denshi; JTAD82 -5010 E0102; Moji_Joho; MJ006832 -5011 E0100; Adobe-Japan1; CID+4167 -5012 E0100; Adobe-Japan1; CID+3159 -5013 E0100; Adobe-Japan1; CID+17271 -5014 E0100; Adobe-Japan1; CID+4156 -5016 E0100; Adobe-Japan1; CID+1962 -5016 E0101; Hanyo-Denshi; JA2486 -5016 E0101; Moji_Joho; MJ006838 -5016 E0102; Hanyo-Denshi; JTAD73 -5016 E0102; Moji_Joho; MJ006839 -5017 E0100; Adobe-Japan1; CID+21126 -5017 E0101; Hanyo-Denshi; JB1750 -5017 E0102; Hanyo-Denshi; TK01004660 -5018 E0100; Adobe-Japan1; CID+16784 -5019 E0100; Adobe-Japan1; CID+1961 -501A E0100; Adobe-Japan1; CID+4154 -501B E0100; Adobe-Japan1; CID+14330 -501C E0100; Adobe-Japan1; CID+17272 -501C E0101; Hanyo-Denshi; JB1753 -501C E0102; Hanyo-Denshi; TK01004650 -501D E0100; Adobe-Japan1; CID+21127 -501E E0100; Adobe-Japan1; CID+8386 -501F E0100; Adobe-Japan1; CID+2310 -5021 E0100; Adobe-Japan1; CID+4162 -5022 E0100; Adobe-Japan1; CID+8384 -5023 E0100; Adobe-Japan1; CID+3647 -5024 E0100; Adobe-Japan1; CID+2955 -5024 E0101; Adobe-Japan1; CID+13919 -5025 E0100; Adobe-Japan1; CID+4158 -5025 E0101; Hanyo-Denshi; JA4869 -5025 E0101; Moji_Joho; MJ006856 -5025 E0102; Hanyo-Denshi; JTAD74 -5025 E0102; Moji_Joho; MJ006857 -5026 E0100; Adobe-Japan1; CID+1863 -5026 E0101; Adobe-Japan1; CID+7674 -5026 E0102; Hanyo-Denshi; JA2381 -5026 E0102; Moji_Joho; MJ006859 -5026 E0103; Hanyo-Denshi; FT1790 -5026 E0103; Moji_Joho; MJ006858 -5027 E0100; Adobe-Japan1; CID+14331 -5028 E0100; Adobe-Japan1; CID+4155 -5029 E0100; Adobe-Japan1; CID+4163 -5029 E0101; Hanyo-Denshi; JA4874 -5029 E0101; Moji_Joho; MJ006862 -5029 E0102; Hanyo-Denshi; FT2068 -5029 E0102; Moji_Joho; MJ006863 -502A E0100; Adobe-Japan1; CID+4157 -502B E0100; Adobe-Japan1; CID+3993 -502B E0101; Hanyo-Denshi; JA4649 -502B E0102; Hanyo-Denshi; TK01004100 -502C E0100; Adobe-Japan1; CID+4164 -502D E0100; Adobe-Japan1; CID+4071 -502E E0100; Adobe-Japan1; CID+14332 -5030 E0100; Adobe-Japan1; CID+21128 -5030 E0101; Hanyo-Denshi; JB1759 -5030 E0101; Moji_Joho; MJ006871 -5030 E0102; Hanyo-Denshi; JTAD72 -5030 E0102; Moji_Joho; MJ006872 -5032 E0100; Adobe-Japan1; CID+21129 -5033 E0100; Adobe-Japan1; CID+21130 -5035 E0100; Adobe-Japan1; CID+21131 -5036 E0100; Adobe-Japan1; CID+1758 -5036 E0101; Hanyo-Denshi; JA2270 -5036 E0101; Moji_Joho; MJ006878 -5036 E0102; Hanyo-Denshi; JTAD66 -5036 E0102; Moji_Joho; MJ006879 -5039 E0100; Adobe-Japan1; CID+1862 -503B E0100; Adobe-Japan1; CID+14336 -5040 E0100; Adobe-Japan1; CID+8383 -5040 E0101; Hanyo-Denshi; JB1763 -5040 E0101; Moji_Joho; MJ006885 -5040 E0102; Hanyo-Denshi; JTAD7E -5040 E0102; Moji_Joho; MJ006886 -5041 E0100; Adobe-Japan1; CID+16785 -5042 E0100; Adobe-Japan1; CID+8389 -5042 E0101; Hanyo-Denshi; JB1765 -5042 E0101; Moji_Joho; MJ006888 -5042 E0102; Hanyo-Denshi; JTAD83 -5042 E0102; Moji_Joho; MJ006889 -5043 E0100; Adobe-Japan1; CID+4169 -5043 E0101; Moji_Joho; MJ006890 -5043 E0102; Moji_Joho; MJ006891 -5045 E0100; Adobe-Japan1; CID+21132 -5046 E0100; Adobe-Japan1; CID+8387 -5047 E0100; Adobe-Japan1; CID+4170 -5048 E0100; Adobe-Japan1; CID+4174 -5048 E0101; Hanyo-Denshi; JA4885 -5048 E0101; Moji_Joho; MJ006896 -5048 E0102; Hanyo-Denshi; FT2070 -5048 E0102; Moji_Joho; MJ006897 -5049 E0100; Adobe-Japan1; CID+1170 -5049 E0101; Adobe-Japan1; CID+13409 -5049 E0102; Hanyo-Denshi; JA1646 -5049 E0102; Moji_Joho; MJ006899 -5049 E0103; Hanyo-Denshi; KS009840S -5049 E0103; Moji_Joho; MJ006898 -5049 E0104; Hanyo-Denshi; TK01005740 -5049 E0105; Moji_Joho; MJ006900 -504A E0100; Adobe-Japan1; CID+21133 -504C E0100; Adobe-Japan1; CID+19155 -504C E0101; Hanyo-Denshi; JB1769 -504C E0101; Moji_Joho; MJ006903 -504C E0102; Hanyo-Denshi; KS009870 -504C E0102; Moji_Joho; MJ006904 -504E E0100; Adobe-Japan1; CID+17273 -504F E0100; Adobe-Japan1; CID+3616 -504F E0101; Adobe-Japan1; CID+14014 -504F E0102; Hanyo-Denshi; JA4248 -504F E0102; Moji_Joho; MJ006908 -504F E0103; Hanyo-Denshi; JTAD7B -504F E0103; Moji_Joho; MJ006907 -5050 E0100; Adobe-Japan1; CID+4173 -5050 E0101; Hanyo-Denshi; JA4884 -5050 E0101; Moji_Joho; MJ006909 -5050 E0102; Hanyo-Denshi; FT2069 -5050 E0102; Moji_Joho; MJ006910 -5051 E0100; Adobe-Japan1; CID+21134 -5052 E0100; Adobe-Japan1; CID+21135 -5053 E0100; Adobe-Japan1; CID+17274 -5055 E0100; Adobe-Japan1; CID+4172 -5055 E0101; Hanyo-Denshi; JA4883 -5055 E0102; Hanyo-Denshi; TK01004250 -5056 E0100; Adobe-Japan1; CID+4176 -5056 E0101; Adobe-Japan1; CID+20077 -5056 E0102; Hanyo-Denshi; JA4887 -5056 E0102; Moji_Joho; MJ006915 -5056 E0103; Hanyo-Denshi; FT2071 -5056 E0103; Moji_Joho; MJ006916 -5057 E0100; Adobe-Japan1; CID+14333 -5059 E0100; Adobe-Japan1; CID+21136 -505A E0100; Adobe-Japan1; CID+4175 -505C E0100; Adobe-Japan1; CID+3072 -505C E0101; Hanyo-Denshi; JA3668 -505C E0101; Moji_Joho; MJ006922 -505C E0102; Hanyo-Denshi; KS011720 -505C E0102; Moji_Joho; MJ056942 -505F E0100; Adobe-Japan1; CID+19156 -5060 E0100; Adobe-Japan1; CID+21137 -5060 E0101; Hanyo-Denshi; JB1777 -5060 E0101; Moji_Joho; MJ006926 -5060 E0102; Hanyo-Denshi; IB1376 -5060 E0102; Moji_Joho; MJ006927 -5062 E0100; Adobe-Japan1; CID+19157 -5063 E0100; Adobe-Japan1; CID+17275 -5064 E0100; Hanyo-Denshi; IP5064 -5064 E0101; Hanyo-Denshi; TK01005110 -5065 E0100; Adobe-Japan1; CID+1864 -5065 E0101; Adobe-Japan1; CID+13435 -5065 E0102; Hanyo-Denshi; JA2382 -5065 E0102; Moji_Joho; MJ006933 -5065 E0103; Hanyo-Denshi; KS011760 -5065 E0103; Moji_Joho; MJ056945 -5065 E0104; Moji_Joho; MJ006934 -5066 E0100; Adobe-Japan1; CID+14334 -5067 E0100; Adobe-Japan1; CID+21138 -506A E0100; Adobe-Japan1; CID+14335 -506C E0100; Adobe-Japan1; CID+4177 -506D E0100; Adobe-Japan1; CID+21139 -5070 E0100; Adobe-Japan1; CID+8388 -5070 E0101; Hanyo-Denshi; JB1784 -5070 E0101; Moji_Joho; MJ006945 -5070 E0102; Hanyo-Denshi; JTAD7F -5070 E0102; Moji_Joho; MJ006947 -5070 E0103; Hanyo-Denshi; IB1377 -5070 E0103; Moji_Joho; MJ006946 -5071 E0100; Adobe-Japan1; CID+21140 -5072 E0100; Adobe-Japan1; CID+2289 -5074 E0100; Adobe-Japan1; CID+2822 -5075 E0100; Adobe-Japan1; CID+3073 -5076 E0100; Adobe-Japan1; CID+1774 -5077 E0100; Adobe-Japan1; CID+19158 -5077 E0101; Hanyo-Denshi; JTAD7D -5077 E0101; Moji_Joho; MJ006955 -5077 E0102; Hanyo-Denshi; KS010790 -5077 E0102; Moji_Joho; MJ006954 -5078 E0100; Adobe-Japan1; CID+4178 -507D E0100; Adobe-Japan1; CID+1616 -5080 E0100; Adobe-Japan1; CID+4179 -5081 E0100; Adobe-Japan1; CID+21141 -5083 E0100; Adobe-Japan1; CID+21142 -5084 E0100; Adobe-Japan1; CID+21143 -5085 E0100; Adobe-Japan1; CID+4181 -5085 E0101; Adobe-Japan1; CID+13520 -5085 E0102; Hanyo-Denshi; JA4892 -5085 E0102; Moji_Joho; MJ006967 -5085 E0103; Hanyo-Denshi; FT2073 -5085 E0103; Moji_Joho; MJ006968 -5085 E0104; Hanyo-Denshi; TK01005290 -5085 E0105; Hanyo-Denshi; TK01005420 -5086 E0100; Adobe-Japan1; CID+21144 -5088 E0100; Adobe-Japan1; CID+17277 -508A E0100; Adobe-Japan1; CID+21145 -508B E0100; Hanyo-Denshi; IP508B -508B E0100; Moji_Joho; MJ006976 -508B E0101; Hanyo-Denshi; JT508B -508B E0101; Moji_Joho; MJ006977 -508D E0100; Adobe-Japan1; CID+3683 -508D E0101; Hanyo-Denshi; JA4321 -508D E0101; Moji_Joho; MJ006979 -508D E0102; Hanyo-Denshi; JTAD8A -508D E0102; Moji_Joho; MJ006980 -508E E0100; Adobe-Japan1; CID+19159 -508E E0101; Hanyo-Denshi; JB1792 -508E E0101; Moji_Joho; MJ006981 -508E E0102; Hanyo-Denshi; JTAD8E -508E E0102; Moji_Joho; MJ006982 -508E E0103; Hanyo-Denshi; TK01005320 -508F E0100; Adobe-Japan1; CID+14337 -5090 E0100; Adobe-Japan1; CID+21146 -5090 E0101; Hanyo-Denshi; JB1794 -5090 E0102; Hanyo-Denshi; TK01005620 -5091 E0100; Adobe-Japan1; CID+1852 -5091 E0101; Adobe-Japan1; CID+13433 -5091 E0102; Adobe-Japan1; CID+13743 -5091 E0103; Hanyo-Denshi; JA2370 -5091 E0103; Moji_Joho; MJ006987 -5091 E0104; Hanyo-Denshi; KS011150 -5091 E0104; Moji_Joho; MJ006986 -5091 E0105; Moji_Joho; MJ006988 -5092 E0100; Adobe-Japan1; CID+17278 -5093 E0100; Adobe-Japan1; CID+17279 -5093 E0101; Hanyo-Denshi; JB1802 -5093 E0102; Hanyo-Denshi; TK01005470 -5094 E0100; Adobe-Japan1; CID+8390 -5094 E0101; Hanyo-Denshi; JB1803 -5094 E0101; Moji_Joho; MJ006991 -5094 E0102; Hanyo-Denshi; JTAD8F -5094 E0102; Moji_Joho; MJ006992 -5095 E0100; Adobe-Japan1; CID+17280 -5096 E0100; Adobe-Japan1; CID+14338 -5098 E0100; Adobe-Japan1; CID+2175 -5099 E0100; Adobe-Japan1; CID+3467 -5099 E0101; Hanyo-Denshi; JA4087 -5099 E0101; Moji_Joho; MJ006997 -5099 E0102; Hanyo-Denshi; KS012180 -5099 E0102; Moji_Joho; MJ006998 -509A E0100; Adobe-Japan1; CID+4180 -509B E0100; Adobe-Japan1; CID+21147 -509C E0100; Adobe-Japan1; CID+14339 -509E E0100; Adobe-Japan1; CID+19160 -509F E0100; Adobe-Japan1; CID+21148 -50A0 E0100; Adobe-Japan1; CID+21149 -50A1 E0100; Adobe-Japan1; CID+21150 -50A2 E0100; Adobe-Japan1; CID+19161 -50A2 E0101; Hanyo-Denshi; JB1811 -50A2 E0101; Moji_Joho; MJ007007 -50A2 E0102; Hanyo-Denshi; IB1390 -50A2 E0102; Moji_Joho; MJ007008 -50A3 E0100; Adobe-Japan1; CID+17276 -50AA E0100; Adobe-Japan1; CID+17281 -50AA E0101; Hanyo-Denshi; JB1812 -50AA E0102; Hanyo-Denshi; TK01005920 -50AC E0100; Adobe-Japan1; CID+2101 -50AD E0100; Adobe-Japan1; CID+3885 -50AF E0100; Adobe-Japan1; CID+21151 -50AF E0101; Hanyo-Denshi; JB1813 -50AF E0101; Moji_Joho; MJ007016 -50AF E0102; Hanyo-Denshi; JTAD97 -50AF E0102; Moji_Joho; MJ007017 -50B0 E0100; Adobe-Japan1; CID+21152 -50B0 E0101; Hanyo-Denshi; JB1814 -50B0 E0102; Hanyo-Denshi; TK01005830 -50B1 E0100; Adobe-Japan1; CID+17283 -50B2 E0100; Adobe-Japan1; CID+4183 -50B3 E0100; Adobe-Japan1; CID+4186 -50B3 E0101; Hanyo-Denshi; JA4903 -50B3 E0101; Moji_Joho; MJ007023 -50B3 E0102; Hanyo-Denshi; JTAD95 -50B3 E0102; Moji_Joho; MJ007024 -50B3 E0103; Hanyo-Denshi; TK01005870 -50B4 E0100; Adobe-Japan1; CID+4182 -50B4 E0101; Hanyo-Denshi; JA4893 -50B4 E0101; Moji_Joho; MJ007026 -50B4 E0102; Hanyo-Denshi; JTAD93 -50B4 E0102; Moji_Joho; MJ007027 -50B5 E0100; Adobe-Japan1; CID+2100 -50B7 E0100; Adobe-Japan1; CID+2439 -50B9 E0100; Adobe-Japan1; CID+21153 -50B9 E0101; Hanyo-Denshi; JB1815 -50B9 E0101; Moji_Joho; MJ007032 -50B9 E0102; Hanyo-Denshi; KS012610 -50B9 E0102; Moji_Joho; MJ007033 -50BA E0100; Adobe-Japan1; CID+17284 -50BB E0100; Adobe-Japan1; CID+17285 -50BB E0101; Hanyo-Denshi; JD0183 -50BB E0101; Moji_Joho; MJ007036 -50BB E0102; Hanyo-Denshi; KS012090 -50BB E0102; Moji_Joho; MJ007035 -50BD E0100; Adobe-Japan1; CID+21154 -50BD E0101; Hanyo-Denshi; JB1817 -50BD E0101; Moji_Joho; MJ007038 -50BD E0102; Hanyo-Denshi; KS012620 -50BD E0102; Moji_Joho; MJ007039 -50BE E0100; Adobe-Japan1; CID+1807 -50C0 E0100; Adobe-Japan1; CID+21155 -50C2 E0100; Adobe-Japan1; CID+4187 -50C3 E0100; Adobe-Japan1; CID+19162 -50C3 E0101; Hanyo-Denshi; JB1819 -50C3 E0101; Moji_Joho; MJ007045 -50C3 E0102; Hanyo-Denshi; KS012220 -50C3 E0102; Moji_Joho; MJ007046 -50C4 E0100; Adobe-Japan1; CID+17286 -50C5 E0100; Adobe-Japan1; CID+1735 -50C5 E0101; Adobe-Japan1; CID+7662 -50C5 E0102; Hanyo-Denshi; JA2247 -50C5 E0102; Moji_Joho; MJ007048 -50C5 E0103; Hanyo-Denshi; FT1779 -50C5 E0103; Moji_Joho; MJ007049 -50C7 E0100; Adobe-Japan1; CID+17287 -50C9 E0100; Adobe-Japan1; CID+4184 -50C9 E0101; Hanyo-Denshi; JA4901 -50C9 E0101; Moji_Joho; MJ007053 -50C9 E0102; Hanyo-Denshi; KS010840 -50C9 E0102; Moji_Joho; MJ056936 -50CA E0100; Adobe-Japan1; CID+4185 -50CA E0101; Adobe-Japan1; CID+7982 -50CA E0102; Adobe-Japan1; CID+14101 -50CA E0103; Hanyo-Denshi; JA4902 -50CA E0103; Moji_Joho; MJ007056 -50CA E0104; Hanyo-Denshi; KS012310 -50CA E0104; Moji_Joho; MJ007054 -50CA E0105; Hanyo-Denshi; JTAD94S -50CA E0105; Moji_Joho; MJ007055 -50CA E0106; Hanyo-Denshi; FT2074 -50CA E0106; Moji_Joho; MJ007057 -50CC E0100; Adobe-Japan1; CID+14340 -50CD E0100; Adobe-Japan1; CID+3207 -50CE E0100; Adobe-Japan1; CID+17290 -50CF E0100; Adobe-Japan1; CID+2814 -50CF E0101; Adobe-Japan1; CID+13474 -50CF E0102; Hanyo-Denshi; JA3392 -50CF E0102; Moji_Joho; MJ007062 -50CF E0103; Hanyo-Denshi; KS013380 -50CF E0103; Moji_Joho; MJ007063 -50CF E0104; Hanyo-Denshi; FT2824 -50CF E0104; Moji_Joho; MJ007064 -50CF E0105; Hanyo-Denshi; TK01006070 -50D0 E0100; Adobe-Japan1; CID+16787 -50D0 E0101; Hanyo-Denshi; JB1824 -50D0 E0102; Hanyo-Denshi; TK01005930 -50D1 E0100; Adobe-Japan1; CID+1691 -50D3 E0100; Adobe-Japan1; CID+21156 -50D4 E0100; Adobe-Japan1; CID+17292 -50D5 E0100; Adobe-Japan1; CID+3707 -50D6 E0100; Adobe-Japan1; CID+4188 -50D8 E0100; Adobe-Japan1; CID+8392 -50D8 E0101; Hanyo-Denshi; JB1827 -50D8 E0102; Hanyo-Denshi; TK01006030 -50D9 E0100; Adobe-Japan1; CID+15408 -50D9 E0101; Hanyo-Denshi; JD0191 -50D9 E0102; Hanyo-Denshi; TK01005640 -50D9 E0103; Hanyo-Denshi; TK01005780 -50DA E0100; Adobe-Japan1; CID+3973 -50DB E0100; Moji_Joho; MJ007077 -50DB E0101; Moji_Joho; MJ007078 -50DC E0100; Adobe-Japan1; CID+21157 -50DD E0100; Adobe-Japan1; CID+21158 -50DE E0100; Adobe-Japan1; CID+4189 -50DE E0101; Hanyo-Denshi; JA4906 -50DE E0101; Moji_Joho; MJ007081 -50DE E0102; Hanyo-Denshi; FT2075 -50DE E0102; Moji_Joho; MJ007082 -50DF E0100; Adobe-Japan1; CID+21159 -50DF E0101; Hanyo-Denshi; JB1830 -50DF E0102; Hanyo-Denshi; TK01005880 -50DF E0103; Hanyo-Denshi; TK01005950 -50E1 E0100; Adobe-Japan1; CID+17293 -50E2 E0100; Adobe-Japan1; CID+21160 -50E2 E0101; Hanyo-Denshi; JB1831 -50E2 E0101; Moji_Joho; MJ007089 -50E2 E0102; Hanyo-Denshi; KS012930 -50E2 E0102; Moji_Joho; MJ007088 -50E3 E0100; Adobe-Japan1; CID+4192 -50E4 E0100; Adobe-Japan1; CID+21161 -50E4 E0101; Hanyo-Denshi; JB1832 -50E4 E0102; Hanyo-Denshi; TK01005280 -50E5 E0100; Adobe-Japan1; CID+4190 -50E6 E0100; Adobe-Japan1; CID+14341 -50E7 E0100; Adobe-Japan1; CID+2768 -50E7 E0101; Adobe-Japan1; CID+13360 -50E7 E0102; Hanyo-Denshi; JA3346 -50E7 E0102; Moji_Joho; MJ007095 -50E7 E0103; Hanyo-Denshi; KS012500 -50E7 E0103; Moji_Joho; MJ007094 -50E7 E0104; Hanyo-Denshi; JTAD9C -50E7 E0104; Moji_Joho; MJ007096 -50E7 E0105; Hanyo-Denshi; JC1441 -50E8 E0100; Adobe-Japan1; CID+19163 -50E8 E0101; Hanyo-Denshi; JB1834 -50E8 E0101; Moji_Joho; MJ007097 -50E8 E0102; Hanyo-Denshi; KS014030 -50E8 E0102; Moji_Joho; MJ056951 -50E9 E0100; Adobe-Japan1; CID+14342 -50ED E0100; Adobe-Japan1; CID+4191 -50ED E0101; Adobe-Japan1; CID+20078 -50ED E0102; Hanyo-Denshi; JA4908 -50ED E0102; Moji_Joho; MJ007102 -50ED E0103; Hanyo-Denshi; JTADADS -50ED E0103; Moji_Joho; MJ007103 -50EE E0100; Adobe-Japan1; CID+4193 -50EE E0101; Hanyo-Denshi; JA4910 -50EE E0101; Moji_Joho; MJ007104 -50EE E0102; Hanyo-Denshi; KS013450 -50EE E0102; Moji_Joho; MJ007105 -50EF E0100; Adobe-Japan1; CID+14343 -50EF E0101; Hanyo-Denshi; JB1836 -50EF E0101; Moji_Joho; MJ007107 -50EF E0102; Hanyo-Denshi; JTAD9F -50EF E0102; Moji_Joho; MJ007106 -50F0 E0100; Adobe-Japan1; CID+15409 -50F1 E0100; Adobe-Japan1; CID+19164 -50F2 E0100; Adobe-Japan1; CID+16786 -50F2 E0101; Adobe-Japan1; CID+21164 -50F2 E0102; Hanyo-Denshi; JB1849 -50F2 E0102; Moji_Joho; MJ007110 -50F2 E0103; Hanyo-Denshi; JC1438 -50F2 E0103; Moji_Joho; MJ007111 -50F2 E0104; Hanyo-Denshi; JTADA7S -50F2 E0104; Moji_Joho; MJ007112 -50F3 E0100; Adobe-Japan1; CID+17288 -50F4 E0100; Adobe-Japan1; CID+8391 -50F5 E0100; Adobe-Japan1; CID+4195 -50F6 E0100; Adobe-Japan1; CID+21162 -50F6 E0101; Hanyo-Denshi; JB1838 -50F6 E0101; Moji_Joho; MJ007117 -50F6 E0102; Hanyo-Denshi; KS014070 -50F6 E0102; Moji_Joho; MJ056953 -50F6 E0103; Moji_Joho; MJ007116 -50F7 E0100; Hanyo-Denshi; KS013500 -50F7 E0101; Hanyo-Denshi; TK01006050 -50F9 E0100; Adobe-Japan1; CID+4194 -50FA E0100; Adobe-Japan1; CID+21163 -50FB E0100; Adobe-Japan1; CID+3608 -50FE E0100; Adobe-Japan1; CID+19165 -5100 E0100; Adobe-Japan1; CID+1617 -5101 E0100; Adobe-Japan1; CID+4197 -5102 E0100; Adobe-Japan1; CID+4198 -5103 E0100; Adobe-Japan1; CID+16789 -5103 E0101; Hanyo-Denshi; JB1841 -5103 E0102; Hanyo-Denshi; TK01006130 -5104 E0100; Adobe-Japan1; CID+1327 -5104 E0101; Hanyo-Denshi; JA1815 -5104 E0101; Moji_Joho; MJ007133 -5104 E0102; Hanyo-Denshi; JTADA5 -5104 E0102; Moji_Joho; MJ007134 -5106 E0100; Adobe-Japan1; CID+16788 -5106 E0101; Hanyo-Denshi; JB1842 -5106 E0101; Moji_Joho; MJ007137 -5106 E0102; Hanyo-Denshi; JTADA6 -5106 E0102; Moji_Joho; MJ007136 -5107 E0100; Adobe-Japan1; CID+19166 -5108 E0100; Adobe-Japan1; CID+14344 -5108 E0101; Hanyo-Denshi; JB1844 -5108 E0101; Moji_Joho; MJ007139 -5108 E0102; Hanyo-Denshi; JTAD9E -5108 E0102; Moji_Joho; MJ059332 -5108 E0103; Hanyo-Denshi; KS013410 -5108 E0103; Moji_Joho; MJ056949 -5109 E0100; Adobe-Japan1; CID+4196 -510B E0100; Adobe-Japan1; CID+14345 -510C E0100; Adobe-Japan1; CID+19167 -510D E0100; Adobe-Japan1; CID+19168 -510D E0101; Hanyo-Denshi; JB1847 -510D E0101; Moji_Joho; MJ007144 -510D E0102; Hanyo-Denshi; KS013890 -510D E0102; Moji_Joho; MJ007143 -510E E0100; Adobe-Japan1; CID+19169 -5110 E0100; Adobe-Japan1; CID+14346 -5110 E0101; Hanyo-Denshi; JB1850 -5110 E0101; Moji_Joho; MJ007146 -5110 E0102; Hanyo-Denshi; JTADB0 -5110 E0102; Moji_Joho; MJ007147 -5112 E0100; Adobe-Japan1; CID+2336 -5114 E0100; Adobe-Japan1; CID+4201 -5114 E0101; Hanyo-Denshi; JA4918 -5114 E0101; Moji_Joho; MJ007151 -5114 E0102; Hanyo-Denshi; JTADAC -5114 E0102; Moji_Joho; MJ007152 -5115 E0100; Adobe-Japan1; CID+4200 -5116 E0100; Adobe-Japan1; CID+4199 -5117 E0100; Adobe-Japan1; CID+17296 -5118 E0100; Adobe-Japan1; CID+4143 -5119 E0100; Adobe-Japan1; CID+21165 -511A E0100; Adobe-Japan1; CID+4202 -511A E0101; Adobe-Japan1; CID+14102 -511A E0102; Hanyo-Denshi; JA4919 -511A E0102; Moji_Joho; MJ007158 -511A E0103; Hanyo-Denshi; KS014320 -511A E0103; Moji_Joho; MJ007159 -511B E0100; Adobe-Japan1; CID+14347 -511B E0101; Hanyo-Denshi; JB1853 -511B E0101; Moji_Joho; MJ007161 -511B E0102; Hanyo-Denshi; KS014330S -511B E0102; Moji_Joho; MJ007160 -511C E0100; Adobe-Japan1; CID+21166 -511D E0100; Adobe-Japan1; CID+21167 -511E E0100; Adobe-Japan1; CID+14348 -511F E0100; Adobe-Japan1; CID+2440 -5121 E0100; Adobe-Japan1; CID+4203 -5123 E0100; Adobe-Japan1; CID+21168 -5125 E0100; Moji_Joho; MJ007171 -5125 E0101; Moji_Joho; MJ007172 -5127 E0100; Adobe-Japan1; CID+21169 -5128 E0100; Adobe-Japan1; CID+21170 -512A E0100; Adobe-Japan1; CID+3855 -512A E0101; Hanyo-Denshi; JA4505 -512A E0101; Moji_Joho; MJ007179 -512A E0102; Hanyo-Denshi; JTADB3 -512A E0102; Moji_Joho; MJ007180 -512A E0103; Hanyo-Denshi; KS014610 -512A E0103; Moji_Joho; MJ007178 -512B E0100; Hanyo-Denshi; IP512B -512B E0101; Hanyo-Denshi; TK01006330 -512C E0100; Adobe-Japan1; CID+21171 -512C E0101; Hanyo-Denshi; JB1860 -512C E0101; Moji_Joho; MJ007182 -512C E0102; Hanyo-Denshi; JTADAF -512C E0102; Moji_Joho; MJ007183 -512D E0100; Adobe-Japan1; CID+21172 -512F E0100; Adobe-Japan1; CID+21173 -5131 E0100; Adobe-Japan1; CID+21174 -5131 E0101; Hanyo-Denshi; JB1863 -5131 E0101; Moji_Joho; MJ007188 -5131 E0102; Hanyo-Denshi; KS014940 -5131 E0102; Moji_Joho; MJ007189 -5132 E0100; Adobe-Japan1; CID+3813 -5132 E0101; Adobe-Japan1; CID+7798 -5132 E0102; Hanyo-Denshi; JA4457 -5132 E0102; Moji_Joho; MJ007190 -5132 E0103; Hanyo-Denshi; FT1926 -5132 E0103; Moji_Joho; MJ007191 -5133 E0100; Adobe-Japan1; CID+19170 -5134 E0100; Adobe-Japan1; CID+21175 -5135 E0100; Adobe-Japan1; CID+16790 -5137 E0100; Adobe-Japan1; CID+4205 -5138 E0100; Adobe-Japan1; CID+19171 -5139 E0100; Adobe-Japan1; CID+21176 -513A E0100; Adobe-Japan1; CID+4204 -513A E0101; Hanyo-Denshi; JA4921 -513A E0101; Moji_Joho; MJ007199 -513A E0102; Hanyo-Denshi; FT2076 -513A E0102; Moji_Joho; MJ007200 -513B E0100; Adobe-Japan1; CID+4207 -513B E0101; Hanyo-Denshi; JA4924 -513B E0101; Moji_Joho; MJ007201 -513B E0102; Hanyo-Denshi; FT2077 -513B E0102; Moji_Joho; MJ007202 -513C E0100; Adobe-Japan1; CID+4206 -513C E0101; Hanyo-Denshi; JA4923 -513C E0101; Moji_Joho; MJ007203 -513C E0102; Hanyo-Denshi; KS015070 -513C E0102; Moji_Joho; MJ056958 -513C E0103; Hanyo-Denshi; TK01006460 -513F E0100; Adobe-Japan1; CID+4208 -5140 E0100; Adobe-Japan1; CID+4209 -5141 E0100; Adobe-Japan1; CID+1208 -5142 E0100; Adobe-Japan1; CID+21177 -5142 E0101; Hanyo-Denshi; JB1869 -5142 E0101; Moji_Joho; MJ007212 -5142 E0102; Hanyo-Denshi; KS015530 -5142 E0102; Moji_Joho; MJ007210 -5142 E0103; Moji_Joho; MJ007211 -5142 E0104; Moji_Joho; MJ056966 -5143 E0100; Adobe-Japan1; CID+1897 -5144 E0100; Adobe-Japan1; CID+1809 -5145 E0100; Adobe-Japan1; CID+2374 -5145 E0101; Hanyo-Denshi; JA2928 -5145 E0101; Moji_Joho; MJ007216 -5145 E0102; Hanyo-Denshi; KS015560 -5145 E0102; Moji_Joho; MJ007215 -5146 E0100; Adobe-Japan1; CID+3001 -5146 E0101; Adobe-Japan1; CID+13477 -5146 E0102; Moji_Joho; MJ007217 -5146 E0103; Moji_Joho; MJ007218 -5147 E0100; Adobe-Japan1; CID+1692 -5147 E0101; Hanyo-Denshi; JA2204 -5147 E0101; Moji_Joho; MJ007219 -5147 E0102; Hanyo-Denshi; KS015720 -5147 E0102; Moji_Joho; MJ056967 -5148 E0100; Adobe-Japan1; CID+2700 -5149 E0100; Adobe-Japan1; CID+1963 -514A E0100; Adobe-Japan1; CID+8393 -514A E0101; Hanyo-Denshi; JB1870 -514A E0101; Moji_Joho; MJ007222 -514A E0102; Hanyo-Denshi; JTADB8 -514A E0102; Moji_Joho; MJ007224 -514A E0103; Hanyo-Denshi; TK01009240 -514A E0104; Moji_Joho; MJ007223 -514B E0100; Adobe-Japan1; CID+2048 -514C E0100; Adobe-Japan1; CID+4211 -514C E0101; Hanyo-Denshi; JA4928 -514C E0101; Moji_Joho; MJ007227 -514C E0102; Hanyo-Denshi; JTADBC -514C E0102; Moji_Joho; MJ007228 -514D E0100; Adobe-Japan1; CID+3796 -514D E0101; Adobe-Japan1; CID+13389 -514D E0102; Hanyo-Denshi; JA4440 -514D E0102; Moji_Joho; MJ007230 -514D E0103; Hanyo-Denshi; KS015850S -514D E0103; Moji_Joho; MJ007229 -514D E0104; Hanyo-Denshi; JC1448 -514E E0100; Adobe-Japan1; CID+3136 -514E E0101; Adobe-Japan1; CID+13949 -514E E0102; Hanyo-Denshi; JA3738 -514E E0102; Moji_Joho; MJ007232 -514E E0103; Hanyo-Denshi; FT2918 -514E E0103; Moji_Joho; MJ007231 -514F E0100; Adobe-Japan1; CID+21178 -5150 E0100; Adobe-Japan1; CID+2247 -5152 E0100; Adobe-Japan1; CID+4210 -5152 E0101; Hanyo-Denshi; JA4927 -5152 E0101; Moji_Joho; MJ007236 -5152 E0102; Hanyo-Denshi; IB0612 -5152 E0102; Moji_Joho; MJ007237 -5152 E0103; Hanyo-Denshi; TK01006670 -5153 E0100; Adobe-Japan1; CID+21179 -5153 E0101; Hanyo-Denshi; JB1872 -5153 E0101; Moji_Joho; MJ007240 -5153 E0102; Hanyo-Denshi; KS016040 -5153 E0102; Moji_Joho; MJ007239 -5154 E0100; Adobe-Japan1; CID+7814 -5154 E0101; Adobe-Japan1; CID+4212 -5154 E0102; Adobe-Japan1; CID+14103 -5154 E0103; Hanyo-Denshi; JA4929 -5154 E0103; Moji_Joho; MJ007242 -5154 E0104; Hanyo-Denshi; JTADC1S -5154 E0104; Moji_Joho; MJ007243 -5154 E0105; Hanyo-Denshi; FT1942 -5154 E0105; Moji_Joho; MJ007241 -5155 E0100; Adobe-Japan1; CID+16791 -5157 E0100; Adobe-Japan1; CID+16792 -5158 E0100; Adobe-Japan1; CID+21180 -515A E0100; Adobe-Japan1; CID+3160 -515C E0100; Adobe-Japan1; CID+1491 -515F E0100; Adobe-Japan1; CID+14349 -5160 E0100; Adobe-Japan1; CID+17298 -5160 E0101; Hanyo-Denshi; JD0306 -5160 E0102; Hanyo-Denshi; TK01009470 -5162 E0100; Adobe-Japan1; CID+4213 -5164 E0100; Adobe-Japan1; CID+8394 -5164 E0101; Hanyo-Denshi; JB1877 -5164 E0101; Moji_Joho; MJ007259 -5164 E0102; Hanyo-Denshi; IB3305 -5164 E0103; Hanyo-Denshi; JTADC4 -5164 E0103; Moji_Joho; MJ007260 -5164 E0104; Hanyo-Denshi; TK01028660 -5164 E0105; Hanyo-Denshi; TK01101400 -5165 E0100; Adobe-Japan1; CID+3286 -5166 E0100; Adobe-Japan1; CID+21181 -5167 E0100; Adobe-Japan1; CID+13966 -5168 E0100; Adobe-Japan1; CID+2742 -5168 E0101; Adobe-Japan1; CID+13890 -5168 E0102; Hanyo-Denshi; JA3320 -5168 E0102; Moji_Joho; MJ007268 -5168 E0103; Hanyo-Denshi; JTADC5 -5168 E0103; Moji_Joho; MJ007267 -5168 E0104; Hanyo-Denshi; TK01002610 -5169 E0100; Adobe-Japan1; CID+4215 -5169 E0101; Hanyo-Denshi; JA4932 -5169 E0101; Moji_Joho; MJ007270 -5169 E0102; Hanyo-Denshi; JTADC7 -5169 E0102; Moji_Joho; MJ007269 -516A E0100; Adobe-Japan1; CID+4216 -516A E0101; Hanyo-Denshi; JA4933 -516A E0101; Moji_Joho; MJ007271 -516A E0102; Hanyo-Denshi; FT2079 -516A E0102; Moji_Joho; MJ007272 -516B E0100; Adobe-Japan1; CID+3392 -516B E0101; Adobe-Japan1; CID+20079 -516B E0102; Hanyo-Denshi; JA4012 -516B E0102; Moji_Joho; MJ007273 -516B E0103; Hanyo-Denshi; FT2050 -516B E0103; Moji_Joho; MJ007274 -516C E0100; Adobe-Japan1; CID+1964 -516C E0101; Adobe-Japan1; CID+13440 -516C E0102; Hanyo-Denshi; JA2488 -516C E0102; Moji_Joho; MJ007275 -516C E0103; Hanyo-Denshi; FT1623 -516C E0103; Moji_Joho; MJ007276 -516D E0100; Adobe-Japan1; CID+4065 -516E E0100; Adobe-Japan1; CID+4217 -516E E0101; Hanyo-Denshi; JA4934 -516E E0101; Moji_Joho; MJ007278 -516E E0102; Hanyo-Denshi; FT2080 -516E E0102; Moji_Joho; MJ007279 -5171 E0100; Adobe-Japan1; CID+1694 -5173 E0100; Adobe-Japan1; CID+17300 -5173 E0101; Hanyo-Denshi; JD0308 -5173 E0101; Moji_Joho; MJ007284 -5173 E0102; Hanyo-Denshi; KS017040 -5173 E0102; Moji_Joho; MJ007283 -5174 E0100; Adobe-Japan1; CID+19172 -5175 E0100; Adobe-Japan1; CID+3596 -5176 E0100; Adobe-Japan1; CID+2838 -5177 E0100; Adobe-Japan1; CID+1769 -5177 E0101; Adobe-Japan1; CID+13733 -5177 E0102; Hanyo-Denshi; JA2281 -5177 E0102; Moji_Joho; MJ007288 -5177 E0103; Hanyo-Denshi; JTADCC -5177 E0103; Moji_Joho; MJ007290 -5177 E0104; Hanyo-Denshi; JTADD3 -5177 E0104; Moji_Joho; MJ007289 -5178 E0100; Adobe-Japan1; CID+3119 -5178 E0101; Moji_Joho; MJ007291 -5178 E0102; Moji_Joho; MJ056983 -5179 E0100; Adobe-Japan1; CID+14201 -517B E0100; Adobe-Japan1; CID+18393 -517B E0101; Hanyo-Denshi; JD8484 -517B E0101; Moji_Joho; MJ007293 -517B E0102; Hanyo-Denshi; JTB879 -517B E0102; Moji_Joho; MJ007294 -517C E0100; Adobe-Japan1; CID+1865 -517C E0101; Adobe-Japan1; CID+13748 -517C E0102; Hanyo-Denshi; JA2383 -517C E0102; Moji_Joho; MJ007297 -517C E0103; Hanyo-Denshi; IB0616 -517C E0103; Moji_Joho; MJ007298 -517C E0104; Hanyo-Denshi; IB0301 -517C E0104; Moji_Joho; MJ007296 -517C E0105; Hanyo-Denshi; KS017380S -517C E0105; Moji_Joho; MJ056985 -517C E0106; Hanyo-Denshi; KS017430 -517C E0106; Moji_Joho; MJ056989 -517E E0100; Adobe-Japan1; CID+21182 -5180 E0100; Adobe-Japan1; CID+4218 -5180 E0101; Hanyo-Denshi; JA4935 -5180 E0101; Moji_Joho; MJ007300 -5180 E0102; Hanyo-Denshi; KS017700 -5180 E0102; Moji_Joho; MJ056999 -5182 E0100; Adobe-Japan1; CID+4219 -5183 E0100; Adobe-Japan1; CID+17301 -5184 E0100; Adobe-Japan1; CID+19173 -5185 E0100; Adobe-Japan1; CID+3258 -5185 E0101; Hanyo-Denshi; JA3866 -5185 E0101; Moji_Joho; MJ007304 -5185 E0102; Hanyo-Denshi; KS017830 -5185 E0102; Moji_Joho; MJ057000 -5186 E0100; Adobe-Japan1; CID+1281 -5189 E0100; Adobe-Japan1; CID+4222 -5189 E0101; Adobe-Japan1; CID+7815 -5189 E0102; Hanyo-Denshi; JA4939 -5189 E0102; Moji_Joho; MJ007308 -5189 E0103; Hanyo-Denshi; FT1943 -5189 E0103; Moji_Joho; MJ007307 -518A E0100; Adobe-Japan1; CID+2157 -518B E0100; Adobe-Japan1; CID+17302 -518C E0100; Adobe-Japan1; CID+4221 -518D E0100; Adobe-Japan1; CID+20061 -518D E0101; Adobe-Japan1; CID+2102 -518D E0102; Hanyo-Denshi; JA2638 -518D E0102; Moji_Joho; MJ007313 -518D E0103; Hanyo-Denshi; KS017970 -518D E0103; Moji_Joho; MJ007312 -518D E0104; Hanyo-Denshi; KS018040 -518D E0104; Moji_Joho; MJ057004 -518E E0100; Adobe-Japan1; CID+21183 -518E E0101; Hanyo-Denshi; JB1883 -518E E0101; Moji_Joho; MJ007314 -518E E0102; Hanyo-Denshi; KS018060 -518E E0102; Moji_Joho; MJ057006 -518E E0103; Hanyo-Denshi; KS018070 -518E E0103; Moji_Joho; MJ057007 -518F E0100; Adobe-Japan1; CID+4223 -5190 E0100; Adobe-Japan1; CID+6235 -5191 E0100; Adobe-Japan1; CID+4224 -5192 E0100; Adobe-Japan1; CID+3695 -5192 E0101; Adobe-Japan1; CID+14038 -5192 E0102; Hanyo-Denshi; JA4333 -5192 E0102; Moji_Joho; MJ007319 -5192 E0103; Hanyo-Denshi; JTB644 -5192 E0103; Moji_Joho; MJ007318 -5193 E0100; Adobe-Japan1; CID+4225 -5193 E0101; Adobe-Japan1; CID+13521 -5193 E0102; Hanyo-Denshi; JA4942 -5193 E0102; Moji_Joho; MJ007321 -5193 E0103; Hanyo-Denshi; KS018290 -5193 E0103; Moji_Joho; MJ007320 -5193 E0104; Hanyo-Denshi; JTADE5 -5193 E0104; Moji_Joho; MJ007322 -5193 E0105; Hanyo-Denshi; KS018350 -5193 E0105; Moji_Joho; MJ057016 -5195 E0100; Adobe-Japan1; CID+7816 -5195 E0101; Adobe-Japan1; CID+4226 -5195 E0102; Adobe-Japan1; CID+14104 -5195 E0103; Hanyo-Denshi; JA4943 -5195 E0103; Moji_Joho; MJ007324 -5195 E0104; Hanyo-Denshi; IB1432S -5195 E0104; Moji_Joho; MJ007326 -5195 E0105; Hanyo-Denshi; FT1944 -5195 E0105; Moji_Joho; MJ007325 -5195 E0106; Hanyo-Denshi; JTADE8S -5195 E0106; Moji_Joho; MJ007327 -5196 E0100; Adobe-Japan1; CID+4227 -5197 E0100; Adobe-Japan1; CID+2513 -5197 E0101; Hanyo-Denshi; JA3073 -5197 E0101; Moji_Joho; MJ007329 -5197 E0102; Hanyo-Denshi; IB0203 -5197 E0102; Moji_Joho; MJ007330 -5198 E0100; Adobe-Japan1; CID+17304 -5198 E0101; Hanyo-Denshi; JB1884 -5198 E0101; Moji_Joho; MJ007331 -5198 E0102; Hanyo-Denshi; KS018710 -5198 E0102; Moji_Joho; MJ057022 -5199 E0100; Adobe-Japan1; CID+2296 -519B E0100; Hanyo-Denshi; TK01008260 -519B E0101; Hanyo-Denshi; TK01008280 -519D E0100; Adobe-Japan1; CID+8395 -519D E0101; Hanyo-Denshi; JB1885 -519D E0101; Moji_Joho; MJ007334 -519D E0102; Hanyo-Denshi; IB1434 -519D E0102; Moji_Joho; MJ007335 -51A0 E0100; Adobe-Japan1; CID+1507 -51A1 E0100; Adobe-Japan1; CID+14350 -51A1 E0101; Moji_Joho; MJ007339 -51A1 E0102; Moji_Joho; MJ007340 -51A2 E0100; Adobe-Japan1; CID+4230 -51A2 E0101; Hanyo-Denshi; JA4947 -51A2 E0101; Moji_Joho; MJ007342 -51A2 E0102; Hanyo-Denshi; FT2081S -51A2 E0102; Moji_Joho; MJ007341 -51A2 E0103; Hanyo-Denshi; JTADF1 -51A2 E0103; Moji_Joho; MJ007343 -51A2 E0104; Hanyo-Denshi; JTADF2 -51A2 E0104; Moji_Joho; MJ007344 -51A3 E0100; Adobe-Japan1; CID+17305 -51A4 E0100; Adobe-Japan1; CID+4228 -51A4 E0101; Adobe-Japan1; CID+7817 -51A4 E0102; Hanyo-Denshi; JA4945 -51A4 E0102; Moji_Joho; MJ007347 -51A4 E0103; Hanyo-Denshi; HG1603 -51A4 E0103; Moji_Joho; MJ007346 -51A4 E0104; Hanyo-Denshi; JTADF5S -51A4 E0104; Moji_Joho; MJ007349 -51A4 E0105; Moji_Joho; MJ007348 -51A5 E0100; Adobe-Japan1; CID+3785 -51A5 E0101; Hanyo-Denshi; JA4429 -51A5 E0101; Moji_Joho; MJ007350 -51A5 E0102; Hanyo-Denshi; KS018990 -51A5 E0102; Moji_Joho; MJ057027 -51A6 E0100; Adobe-Japan1; CID+4229 -51A6 E0101; Hanyo-Denshi; JA4946 -51A6 E0101; Moji_Joho; MJ007351 -51A6 E0102; Hanyo-Denshi; JTADF3 -51A6 E0102; Moji_Joho; MJ007352 -51A8 E0100; Adobe-Japan1; CID+3532 -51A9 E0100; Adobe-Japan1; CID+4231 -51AA E0100; Adobe-Japan1; CID+4232 -51AA E0101; Hanyo-Denshi; JA4949 -51AA E0101; Moji_Joho; MJ007356 -51AA E0102; Hanyo-Denshi; KS019150 -51AA E0102; Moji_Joho; MJ007355 -51AB E0100; Adobe-Japan1; CID+4233 -51AC E0100; Adobe-Japan1; CID+13954 -51AC E0101; Adobe-Japan1; CID+3161 -51AC E0102; Hanyo-Denshi; JA3763 -51AC E0102; Moji_Joho; MJ007359 -51AC E0103; Hanyo-Denshi; JTADF8 -51AC E0103; Moji_Joho; MJ007358 -51AD E0100; Adobe-Japan1; CID+17306 -51B0 E0100; Adobe-Japan1; CID+4237 -51B1 E0100; Adobe-Japan1; CID+4235 -51B2 E0100; Adobe-Japan1; CID+4236 -51B3 E0100; Adobe-Japan1; CID+4234 -51B4 E0100; Adobe-Japan1; CID+2131 -51B4 E0101; Adobe-Japan1; CID+13404 -51B4 E0102; Adobe-Japan1; CID+13787 -51B4 E0103; Hanyo-Denshi; JA2667 -51B4 E0103; Moji_Joho; MJ007369 -51B4 E0104; Hanyo-Denshi; JTADFC -51B4 E0104; Moji_Joho; MJ007367 -51B4 E0105; Moji_Joho; MJ007368 -51B4 E0106; Moji_Joho; MJ007370 -51B5 E0100; Adobe-Japan1; CID+4238 -51B5 E0101; Hanyo-Denshi; JA4955 -51B5 E0101; Moji_Joho; MJ007372 -51B5 E0102; Hanyo-Denshi; KS003220 -51B5 E0102; Moji_Joho; MJ007371 -51B6 E0100; Adobe-Japan1; CID+3830 -51B7 E0100; Adobe-Japan1; CID+4012 -51B8 E0100; Adobe-Japan1; CID+19174 -51BA E0100; Adobe-Japan1; CID+19175 -51BC E0100; Adobe-Japan1; CID+14351 -51BD E0100; Adobe-Japan1; CID+4239 -51BE E0100; Adobe-Japan1; CID+8396 -51BF E0100; Adobe-Japan1; CID+21184 -51C2 E0100; Adobe-Japan1; CID+21185 -51C3 E0100; Adobe-Japan1; CID+15410 -51C4 E0100; Adobe-Japan1; CID+2636 -51C5 E0100; Adobe-Japan1; CID+4240 -51C6 E0100; Adobe-Japan1; CID+2404 -51C8 E0100; Adobe-Japan1; CID+19176 -51C9 E0100; Adobe-Japan1; CID+4241 -51CA E0100; Adobe-Japan1; CID+16794 -51CA E0101; Hanyo-Denshi; JC1454 -51CA E0101; Moji_Joho; MJ007391 -51CA E0102; Hanyo-Denshi; IB1442 -51CA E0102; Moji_Joho; MJ007392 -51CB E0100; Adobe-Japan1; CID+3002 -51CB E0101; Adobe-Japan1; CID+7742 -51CB E0102; Hanyo-Denshi; JA3592 -51CB E0102; Moji_Joho; MJ007394 -51CB E0103; Hanyo-Denshi; FT1861 -51CB E0103; Moji_Joho; MJ007393 -51CC E0100; Adobe-Japan1; CID+3975 -51CC E0101; Hanyo-Denshi; JA4631 -51CC E0101; Moji_Joho; MJ007396 -51CC E0102; Hanyo-Denshi; KS019870 -51CC E0102; Moji_Joho; MJ007395 -51CD E0100; Adobe-Japan1; CID+3162 -51CF E0100; Adobe-Japan1; CID+19177 -51D1 E0100; Adobe-Japan1; CID+19178 -51D2 E0100; Adobe-Japan1; CID+21186 -51D3 E0100; Adobe-Japan1; CID+19179 -51D4 E0100; Adobe-Japan1; CID+19180 -51D5 E0100; Adobe-Japan1; CID+21187 -51D6 E0100; Adobe-Japan1; CID+4314 -51D8 E0100; Adobe-Japan1; CID+19181 -51DB E0100; Adobe-Japan1; CID+4242 -51DB E0101; Adobe-Japan1; CID+13522 -51DB E0102; Hanyo-Denshi; JA4959 -51DB E0103; Hanyo-Denshi; TK01009150 -51DC E0100; Adobe-Japan1; CID+8284 -51DD E0100; Adobe-Japan1; CID+1725 -51DE E0100; Adobe-Japan1; CID+20300 -51DE E0101; Adobe-Japan1; CID+20307 -51DE E0102; Adobe-Japan1; CID+14352 -51DE E0103; Adobe-Japan1; CID+20081 -51DE E0104; Adobe-Japan1; CID+8542 -51DE E0105; Hanyo-Denshi; JB1908 -51DE E0106; Hanyo-Denshi; KS020430 -51DE E0106; Moji_Joho; MJ007413 -51DE E0107; Hanyo-Denshi; JC1455 -51DE E0107; Moji_Joho; MJ007414 -51DE E0108; Moji_Joho; MJ030203 -51DE E0109; Moji_Joho; MJ030204 -51DE E010A; Moji_Joho; MJ030205 -51DE E010B; Moji_Joho; MJ059370 -51DF E0100; Adobe-Japan1; CID+19182 -51E0 E0100; Adobe-Japan1; CID+4243 -51E1 E0100; Adobe-Japan1; CID+3724 -51E1 E0101; Adobe-Japan1; CID+14041 -51E2 E0100; Adobe-Japan1; CID+16795 -51E2 E0101; Hanyo-Denshi; JB1909 -51E2 E0101; Moji_Joho; MJ007418 -51E2 E0102; Hanyo-Denshi; JTAD24 -51E2 E0102; Moji_Joho; MJ007419 -51E5 E0100; Adobe-Japan1; CID+21188 -51E6 E0100; Adobe-Japan1; CID+2418 -51E7 E0100; Adobe-Japan1; CID+2908 -51E9 E0100; Adobe-Japan1; CID+4245 -51EA E0100; Adobe-Japan1; CID+3260 -51EC E0100; Adobe-Japan1; CID+8397 -51ED E0100; Adobe-Japan1; CID+4246 -51EE E0100; Adobe-Japan1; CID+14353 -51EF E0100; Hanyo-Denshi; TK01009320 -51EF E0101; Hanyo-Denshi; TK01009370 -51F0 E0100; Adobe-Japan1; CID+4247 -51F1 E0100; Adobe-Japan1; CID+1420 -51F2 E0100; Adobe-Japan1; CID+21189 -51F3 E0100; Adobe-Japan1; CID+17309 -51F4 E0100; Adobe-Japan1; CID+14354 -51F5 E0100; Adobe-Japan1; CID+4248 -51F6 E0100; Adobe-Japan1; CID+1695 -51F6 E0101; Hanyo-Denshi; JA2207 -51F6 E0101; Moji_Joho; MJ007438 -51F6 E0102; Hanyo-Denshi; KS021320 -51F6 E0102; Moji_Joho; MJ057037 -51F7 E0100; Adobe-Japan1; CID+21190 -51F8 E0100; Adobe-Japan1; CID+3236 -51F9 E0100; Adobe-Japan1; CID+1308 -51FA E0100; Adobe-Japan1; CID+2394 -51FD E0100; Adobe-Japan1; CID+3381 -51FD E0101; Adobe-Japan1; CID+20082 -51FD E0102; Hanyo-Denshi; JA4001 -51FD E0102; Moji_Joho; MJ007443 -51FD E0103; Hanyo-Denshi; KS021580 -51FD E0103; Moji_Joho; MJ007444 -51FE E0100; Adobe-Japan1; CID+4249 -51FE E0101; Hanyo-Denshi; JA4966 -51FE E0101; Moji_Joho; MJ007445 -51FE E0102; Hanyo-Denshi; JTAE86 -51FE E0102; Moji_Joho; MJ007446 -5200 E0100; Adobe-Japan1; CID+3163 -5201 E0100; Adobe-Japan1; CID+14355 -5202 E0100; Adobe-Japan1; CID+14356 -5203 E0100; Adobe-Japan1; CID+2581 -5203 E0101; Adobe-Japan1; CID+13858 -5203 E0102; Hanyo-Denshi; JA3147 -5203 E0102; Moji_Joho; MJ007451 -5203 E0103; Hanyo-Denshi; IB0302 -5203 E0103; Moji_Joho; MJ007450 -5204 E0100; Adobe-Japan1; CID+4250 -5204 E0101; Moji_Joho; MJ007452 -5204 E0102; Moji_Joho; MJ007453 -5205 E0100; Adobe-Japan1; CID+19183 -5206 E0100; Adobe-Japan1; CID+3580 -5206 E0101; Adobe-Japan1; CID+13499 -5206 E0102; Hanyo-Denshi; JA4212 -5206 E0102; Moji_Joho; MJ007455 -5206 E0103; Hanyo-Denshi; FT1668 -5206 E0103; Moji_Joho; MJ007456 -5207 E0100; Adobe-Japan1; CID+2686 -5207 E0101; Hanyo-Denshi; JA3258 -5207 E0101; Moji_Joho; MJ007457 -5207 E0102; Hanyo-Denshi; IB0620 -5207 E0102; Moji_Joho; MJ007459 -5207 E0103; Moji_Joho; MJ007460 -5208 E0100; Adobe-Japan1; CID+1502 -520A E0100; Adobe-Japan1; CID+1509 -520B E0100; Adobe-Japan1; CID+4251 -520B E0101; Moji_Joho; MJ007464 -520B E0102; Moji_Joho; MJ007465 -520E E0100; Adobe-Japan1; CID+4253 -5211 E0100; Adobe-Japan1; CID+1808 -5212 E0100; Adobe-Japan1; CID+17310 -5213 E0100; Adobe-Japan1; CID+14357 -5213 E0101; Hanyo-Denshi; JB1920 -5213 E0101; Moji_Joho; MJ007473 -5213 E0102; Hanyo-Denshi; JTAE13 -5213 E0102; Moji_Joho; MJ007474 -5214 E0100; Adobe-Japan1; CID+4252 -5215 E0100; Adobe-Japan1; CID+8398 -5216 E0100; Adobe-Japan1; CID+17311 -5217 E0100; Adobe-Japan1; CID+4027 -5218 E0100; Adobe-Japan1; CID+21191 -521D E0100; Adobe-Japan1; CID+2419 -521F E0100; Hanyo-Denshi; IP521F -521F E0101; Hanyo-Denshi; TK01009740 -5220 E0100; Hanyo-Denshi; JT5220 -5220 E0100; Moji_Joho; MJ007487 -5220 E0101; Hanyo-Denshi; JTAE16 -5220 E0101; Moji_Joho; MJ007486 -5222 E0100; Adobe-Japan1; CID+21192 -5224 E0100; Adobe-Japan1; CID+3409 -5224 E0101; Adobe-Japan1; CID+13985 -5224 E0102; Hanyo-Denshi; JA4029 -5224 E0102; Moji_Joho; MJ007491 -5224 E0103; Hanyo-Denshi; KS022690 -5224 E0103; Moji_Joho; MJ007493 -5224 E0104; Hanyo-Denshi; JTAE15 -5224 E0104; Moji_Joho; MJ007492 -5225 E0100; Adobe-Japan1; CID+3612 -5225 E0101; Hanyo-Denshi; JA4244 -5225 E0102; Hanyo-Denshi; TK01009760 -5226 E0100; Adobe-Japan1; CID+19184 -5227 E0100; Adobe-Japan1; CID+4254 -5228 E0100; Adobe-Japan1; CID+19185 -5229 E0100; Adobe-Japan1; CID+3938 -522A E0100; Adobe-Japan1; CID+4255 -522B E0100; Adobe-Japan1; CID+19186 -522E E0100; Adobe-Japan1; CID+4256 -5230 E0100; Adobe-Japan1; CID+3192 -5231 E0100; Adobe-Japan1; CID+19187 -5232 E0100; Adobe-Japan1; CID+19188 -5233 E0100; Adobe-Japan1; CID+4257 -5235 E0100; Adobe-Japan1; CID+19189 -5236 E0100; Adobe-Japan1; CID+2637 -5237 E0100; Adobe-Japan1; CID+2158 -5238 E0100; Adobe-Japan1; CID+1866 -5238 E0101; Adobe-Japan1; CID+13749 -5238 E0102; Hanyo-Denshi; JA2384 -5238 E0102; Moji_Joho; MJ007512 -5238 E0103; Hanyo-Denshi; IB1454 -5238 E0103; Moji_Joho; MJ007513 -5239 E0100; Adobe-Japan1; CID+4258 -523A E0100; Adobe-Japan1; CID+2199 -523B E0100; Adobe-Japan1; CID+2049 -523B E0101; Hanyo-Denshi; JA2579 -523B E0101; Moji_Joho; MJ007516 -523B E0102; Hanyo-Denshi; JTAE19 -523B E0102; Moji_Joho; MJ007517 -523C E0100; Adobe-Japan1; CID+19190 -5243 E0100; Adobe-Japan1; CID+3074 -5244 E0100; Adobe-Japan1; CID+4260 -5245 E0100; Adobe-Japan1; CID+21193 -5247 E0100; Adobe-Japan1; CID+2823 -5249 E0100; Adobe-Japan1; CID+14358 -524A E0100; Adobe-Japan1; CID+2143 -524A E0101; Adobe-Japan1; CID+13789 -524A E0102; Hanyo-Denshi; JA2679 -524A E0102; Moji_Joho; MJ007528 -524A E0103; Hanyo-Denshi; JTAE1E -524A E0103; Moji_Joho; MJ007527 -524B E0100; Adobe-Japan1; CID+4261 -524C E0100; Adobe-Japan1; CID+4262 -524D E0100; Adobe-Japan1; CID+2738 -524D E0101; Adobe-Japan1; CID+13889 -524D E0102; Hanyo-Denshi; JA3316 -524D E0102; Moji_Joho; MJ007532 -524D E0103; Hanyo-Denshi; JTAE1B -524D E0103; Moji_Joho; MJ007531 -524F E0100; Adobe-Japan1; CID+4259 -524F E0101; Moji_Joho; MJ007534 -524F E0102; Moji_Joho; MJ007535 -5254 E0100; Adobe-Japan1; CID+4264 -5255 E0100; Adobe-Japan1; CID+17313 -5256 E0100; Adobe-Japan1; CID+3684 -5257 E0100; Adobe-Japan1; CID+16796 -5258 E0100; Adobe-Japan1; CID+21194 -525A E0100; Adobe-Japan1; CID+19191 -525B E0100; Adobe-Japan1; CID+2038 -525C E0100; Adobe-Japan1; CID+17314 -525D E0100; Adobe-Japan1; CID+7774 -525E E0100; Adobe-Japan1; CID+4263 -525F E0100; Adobe-Japan1; CID+21195 -5260 E0100; Adobe-Japan1; CID+19192 -5261 E0100; Adobe-Japan1; CID+14359 -5263 E0100; Adobe-Japan1; CID+1867 -5264 E0100; Adobe-Japan1; CID+2126 -5264 E0101; Adobe-Japan1; CID+20084 -5265 E0100; Adobe-Japan1; CID+3363 -5266 E0100; Adobe-Japan1; CID+14360 -5268 E0100; Hanyo-Denshi; IP5268 -5268 E0100; Moji_Joho; MJ007557 -5268 E0101; Hanyo-Denshi; KS024680 -5268 E0101; Moji_Joho; MJ007558 -5269 E0100; Adobe-Japan1; CID+4267 -526A E0100; Adobe-Japan1; CID+4265 -526A E0101; Hanyo-Denshi; JA4982 -526A E0101; Moji_Joho; MJ007560 -526A E0102; Hanyo-Denshi; FT2084 -526A E0102; Moji_Joho; MJ007561 -526C E0100; Adobe-Japan1; CID+17315 -526E E0100; Adobe-Japan1; CID+19193 -526F E0100; Adobe-Japan1; CID+3565 -5270 E0100; Adobe-Japan1; CID+2514 -5271 E0100; Adobe-Japan1; CID+4274 -5271 E0101; Adobe-Japan1; CID+20085 -5271 E0102; Hanyo-Denshi; JA4991 -5271 E0103; Hanyo-Denshi; JTAE22 -5271 E0103; Moji_Joho; MJ007569 -5271 E0104; Moji_Joho; MJ007568 -5271 E0105; Moji_Joho; MJ007570 -5272 E0100; Adobe-Japan1; CID+13684 -5272 E0101; Adobe-Japan1; CID+1474 -5272 E0102; Adobe-Japan1; CID+20086 -5272 E0103; Hanyo-Denshi; JA1968 -5272 E0103; Moji_Joho; MJ007571 -5272 E0104; Hanyo-Denshi; KS025050S -5272 E0104; Moji_Joho; MJ007572 -5272 E0105; Hanyo-Denshi; JTAE24S -5272 E0105; Moji_Joho; MJ007573 -5273 E0100; Adobe-Japan1; CID+4268 -5273 E0101; Hanyo-Denshi; JA4985 -5273 E0101; Moji_Joho; MJ007574 -5273 E0102; Hanyo-Denshi; KS024770 -5273 E0102; Moji_Joho; MJ007575 -5274 E0100; Adobe-Japan1; CID+4266 -5275 E0100; Adobe-Japan1; CID+2769 -5275 E0101; Adobe-Japan1; CID+7723 -5275 E0102; Hanyo-Denshi; JA3347 -5275 E0102; Moji_Joho; MJ007577 -5275 E0103; Hanyo-Denshi; FT2926 -5275 E0103; Moji_Joho; MJ007578 -5277 E0100; Adobe-Japan1; CID+17316 -5278 E0100; Adobe-Japan1; CID+19194 -5279 E0100; Adobe-Japan1; CID+19195 -527D E0100; Adobe-Japan1; CID+4270 -527F E0100; Adobe-Japan1; CID+4269 -527F E0101; Hanyo-Denshi; JA4986 -527F E0101; Moji_Joho; MJ007589 -527F E0102; Hanyo-Denshi; JTAE28 -527F E0102; Moji_Joho; MJ007590 -5280 E0100; Adobe-Japan1; CID+21196 -5282 E0100; Adobe-Japan1; CID+17318 -5283 E0100; Adobe-Japan1; CID+1442 -5283 E0101; Moji_Joho; MJ007594 -5283 E0102; Moji_Joho; MJ007595 -5284 E0100; Adobe-Japan1; CID+17317 -5285 E0100; Adobe-Japan1; CID+21197 -5287 E0100; Adobe-Japan1; CID+1846 -5288 E0100; Adobe-Japan1; CID+4275 -5289 E0100; Adobe-Japan1; CID+3957 -5289 E0101; Hanyo-Denshi; JA4613 -5289 E0101; Moji_Joho; MJ007602 -5289 E0102; Hanyo-Denshi; KS025890 -5289 E0102; Moji_Joho; MJ007601 -5289 E0103; Hanyo-Denshi; KS025760 -5289 E0103; Moji_Joho; MJ057057 -528A E0100; Adobe-Japan1; CID+19196 -528C E0100; Adobe-Japan1; CID+19197 -528D E0100; Adobe-Japan1; CID+4271 -528D E0101; Adobe-Japan1; CID+14106 -528D E0102; Hanyo-Denshi; JA4988 -528D E0103; Hanyo-Denshi; TK01010190 -5291 E0100; Adobe-Japan1; CID+4276 -5291 E0101; Hanyo-Denshi; JA4993 -5291 E0101; Moji_Joho; MJ007609 -5291 E0102; Hanyo-Denshi; JTAE2E -5291 E0102; Moji_Joho; MJ007610 -5292 E0100; Adobe-Japan1; CID+4273 -5292 E0101; Hanyo-Denshi; JA4990 -5292 E0101; Moji_Joho; MJ007611 -5292 E0102; Hanyo-Denshi; FT2087 -5292 E0102; Moji_Joho; MJ007612 -5293 E0100; Adobe-Japan1; CID+14361 -5294 E0100; Adobe-Japan1; CID+4272 -5294 E0101; Hanyo-Denshi; JA4989 -5294 E0102; Hanyo-Denshi; TK01010250 -5294 E0103; Moji_Joho; MJ007614 -5294 E0104; Moji_Joho; MJ007615 -5295 E0100; Adobe-Japan1; CID+21198 -5296 E0100; Adobe-Japan1; CID+21199 -5297 E0100; Adobe-Japan1; CID+21200 -5298 E0100; Adobe-Japan1; CID+17320 -5298 E0101; Hanyo-Denshi; JB1954 -5298 E0101; Moji_Joho; MJ007619 -5298 E0102; Hanyo-Denshi; JTAE2F -5298 E0102; Moji_Joho; MJ007620 -529A E0100; Adobe-Japan1; CID+21201 -529B E0100; Adobe-Japan1; CID+3991 -529C E0100; Adobe-Japan1; CID+8399 -529F E0100; Adobe-Japan1; CID+1965 -52A0 E0100; Adobe-Japan1; CID+1347 -52A3 E0100; Adobe-Japan1; CID+4028 -52A4 E0100; Adobe-Japan1; CID+17322 -52A5 E0100; Adobe-Japan1; CID+21202 -52A6 E0100; Adobe-Japan1; CID+8400 -52A7 E0100; Adobe-Japan1; CID+21203 -52A9 E0100; Adobe-Japan1; CID+2431 -52A9 E0101; Hanyo-Denshi; JA2985 -52A9 E0101; Moji_Joho; MJ007634 -52A9 E0102; Hanyo-Denshi; KS027050 -52A9 E0102; Moji_Joho; MJ057064 -52AA E0100; Adobe-Japan1; CID+3154 -52AB E0100; Adobe-Japan1; CID+2039 -52AC E0100; Adobe-Japan1; CID+4279 -52AD E0100; Adobe-Japan1; CID+4280 -52AF E0100; Adobe-Japan1; CID+8573 -52B0 E0100; Adobe-Japan1; CID+21204 -52B1 E0100; Adobe-Japan1; CID+4013 -52B4 E0100; Adobe-Japan1; CID+4049 -52B5 E0100; Adobe-Japan1; CID+4282 -52B5 E0101; Hanyo-Denshi; JA5005 -52B5 E0101; Moji_Joho; MJ007645 -52B5 E0102; Hanyo-Denshi; FT2089 -52B5 E0102; Moji_Joho; MJ007646 -52B6 E0100; Adobe-Japan1; CID+21205 -52B7 E0100; Adobe-Japan1; CID+21206 -52B8 E0100; Adobe-Japan1; CID+21207 -52B9 E0100; Adobe-Japan1; CID+1966 -52BA E0100; Adobe-Japan1; CID+17323 -52BB E0100; Adobe-Japan1; CID+17324 -52BC E0100; Adobe-Japan1; CID+4281 -52BD E0100; Adobe-Japan1; CID+21208 -52BE E0100; Adobe-Japan1; CID+1421 -52BE E0101; Hanyo-Denshi; JA1915 -52BE E0101; Moji_Joho; MJ007655 -52BE E0102; Hanyo-Denshi; JTAE33 -52BE E0102; Moji_Joho; MJ007656 -52C0 E0100; Adobe-Japan1; CID+8401 -52C1 E0100; Adobe-Japan1; CID+4283 -52C1 E0101; Hanyo-Denshi; JA5006 -52C1 E0102; Hanyo-Denshi; TK01010630 -52C2 E0100; Hanyo-Denshi; IP52C2 -52C2 E0101; Hanyo-Denshi; TK01010710 -52C3 E0100; Adobe-Japan1; CID+3716 -52C4 E0100; Adobe-Japan1; CID+21209 -52C4 E0101; Hanyo-Denshi; JB1970 -52C4 E0102; Hanyo-Denshi; TK01010590 -52C5 E0100; Adobe-Japan1; CID+3032 -52C6 E0100; Adobe-Japan1; CID+21210 -52C6 E0101; Hanyo-Denshi; JB1971 -52C6 E0101; Moji_Joho; MJ007665 -52C6 E0102; Hanyo-Denshi; JTAE35 -52C6 E0102; Moji_Joho; MJ007666 -52C7 E0100; Adobe-Japan1; CID+3856 -52C7 E0101; Adobe-Japan1; CID+14070 -52C7 E0102; Hanyo-Denshi; JA4506 -52C7 E0102; Moji_Joho; MJ007668 -52C7 E0103; Hanyo-Denshi; JTAE37 -52C7 E0103; Moji_Joho; MJ007667 -52C8 E0100; Adobe-Japan1; CID+14362 -52C9 E0100; Adobe-Japan1; CID+13385 -52C9 E0101; Adobe-Japan1; CID+3625 -52C9 E0102; Hanyo-Denshi; JA4257 -52C9 E0103; Hanyo-Denshi; JC1467 -52CA E0100; Adobe-Japan1; CID+17325 -52CC E0100; Adobe-Japan1; CID+16797 -52CC E0101; Hanyo-Denshi; JB1973 -52CC E0101; Moji_Joho; MJ007672 -52CC E0102; Hanyo-Denshi; JTAE3E -52CC E0102; Moji_Joho; MJ007673 -52CC E0103; Hanyo-Denshi; IB1478 -52CC E0104; Hanyo-Denshi; JTAE3F -52CC E0104; Moji_Joho; MJ007674 -52CC E0105; Hanyo-Denshi; TK01010740 -52CC E0106; Hanyo-Denshi; TK01010910 -52CC E0107; Hanyo-Denshi; TK01010930 -52CD E0100; Adobe-Japan1; CID+4284 -52CE E0100; Hanyo-Denshi; IP52CE -52CE E0101; Hanyo-Denshi; TK01010850 -52CF E0100; Adobe-Japan1; CID+21211 -52D0 E0100; Adobe-Japan1; CID+14056 -52D1 E0100; Adobe-Japan1; CID+17326 -52D2 E0100; Adobe-Japan1; CID+7150 -52D2 E0101; Hanyo-Denshi; JA8053 -52D2 E0101; Moji_Joho; MJ007687 -52D2 E0102; Hanyo-Denshi; JTAE3C -52D2 E0102; Moji_Joho; MJ007688 -52D4 E0100; Adobe-Japan1; CID+21212 -52D5 E0100; Adobe-Japan1; CID+3208 -52D6 E0100; Adobe-Japan1; CID+16798 -52D6 E0101; Hanyo-Denshi; JB1977 -52D6 E0101; Moji_Joho; MJ007692 -52D6 E0102; Hanyo-Denshi; IB0303 -52D6 E0102; Moji_Joho; MJ007693 -52D7 E0100; Adobe-Japan1; CID+4285 -52D7 E0101; Adobe-Japan1; CID+14107 -52D7 E0102; Hanyo-Denshi; JA5008 -52D7 E0102; Moji_Joho; MJ007695 -52D7 E0103; Hanyo-Denshi; KS027790 -52D7 E0103; Moji_Joho; MJ007694 -52D8 E0100; Adobe-Japan1; CID+1510 -52D8 E0101; Hanyo-Denshi; JA2010 -52D8 E0101; Moji_Joho; MJ007696 -52D8 E0102; Hanyo-Denshi; JTAE41 -52D8 E0102; Moji_Joho; MJ059386 -52D8 E0103; Hanyo-Denshi; JTAE42 -52D8 E0103; Moji_Joho; MJ059387 -52D8 E0104; Hanyo-Denshi; TK01010880 -52D9 E0100; Adobe-Japan1; CID+3775 -52DB E0100; Adobe-Japan1; CID+8402 -52DB E0101; Hanyo-Denshi; JB1978 -52DB E0102; Hanyo-Denshi; TK01010870 -52DC E0100; Adobe-Japan1; CID+21213 -52DD E0100; Adobe-Japan1; CID+2441 -52DD E0101; Adobe-Japan1; CID+13829 -52DD E0102; Hanyo-Denshi; JA3001 -52DD E0102; Moji_Joho; MJ007701 -52DD E0103; Hanyo-Denshi; JTAE44 -52DD E0103; Moji_Joho; MJ007700 -52DE E0100; Adobe-Japan1; CID+4286 -52DF E0100; Adobe-Japan1; CID+3639 -52DF E0101; Hanyo-Denshi; JA4271 -52DF E0101; Moji_Joho; MJ007703 -52DF E0102; Hanyo-Denshi; KS028100 -52DF E0102; Moji_Joho; MJ007704 -52DF E0103; Hanyo-Denshi; TK01078860 -52E0 E0100; Adobe-Japan1; CID+4290 -52E0 E0101; Hanyo-Denshi; JA5013 -52E0 E0101; Moji_Joho; MJ007705 -52E0 E0102; Hanyo-Denshi; FT2092 -52E0 E0102; Moji_Joho; MJ007706 -52E1 E0100; Adobe-Japan1; CID+19198 -52E2 E0100; Adobe-Japan1; CID+2638 -52E2 E0101; Adobe-Japan1; CID+13866 -52E3 E0100; Adobe-Japan1; CID+4287 -52E4 E0100; Adobe-Japan1; CID+1736 -52E4 E0101; Adobe-Japan1; CID+13338 -52E4 E0102; Hanyo-Denshi; JA2248 -52E4 E0102; Moji_Joho; MJ007710 -52E4 E0103; Hanyo-Denshi; JC1472 -52E4 E0104; Hanyo-Denshi; JTAE45 -52E4 E0104; Moji_Joho; MJ059388 -52E4 E0105; Hanyo-Denshi; JTAE46 -52E4 E0105; Moji_Joho; MJ059389 -52E4 E0106; Hanyo-Denshi; TK01011100 -52E4 E0107; Hanyo-Denshi; TK01011130 -52E4 E0108; Hanyo-Denshi; TK01011210 -52E5 E0100; Adobe-Japan1; CID+21214 -52E5 E0101; Hanyo-Denshi; JB1981 -52E5 E0102; Hanyo-Denshi; TK01011270 -52E6 E0100; Adobe-Japan1; CID+4288 -52E6 E0101; Hanyo-Denshi; JA5011 -52E6 E0101; Moji_Joho; MJ007714 -52E6 E0102; Hanyo-Denshi; FT2090S -52E6 E0102; Moji_Joho; MJ007715 -52E7 E0100; Adobe-Japan1; CID+1511 -52E8 E0100; Adobe-Japan1; CID+21215 -52E8 E0101; Moji_Joho; MJ007717 -52E8 E0102; Moji_Joho; MJ007718 -52E9 E0100; Adobe-Japan1; CID+19199 -52EA E0100; Adobe-Japan1; CID+21216 -52EC E0100; Adobe-Japan1; CID+21217 -52EC E0101; Hanyo-Denshi; JB1985 -52EC E0101; Moji_Joho; MJ007722 -52EC E0102; Hanyo-Denshi; IB1482 -52EC E0102; Moji_Joho; MJ007723 -52EF E0100; Hanyo-Denshi; IP52EF -52EF E0101; Hanyo-Denshi; TK01011280 -52F0 E0100; Adobe-Japan1; CID+14363 -52F1 E0100; Adobe-Japan1; CID+19200 -52F1 E0101; Hanyo-Denshi; JB1987 -52F1 E0101; Moji_Joho; MJ007729 -52F1 E0102; Hanyo-Denshi; JTAE4F -52F1 E0102; Moji_Joho; MJ007730 -52F2 E0100; Adobe-Japan1; CID+1796 -52F2 E0101; Hanyo-Denshi; JA2314 -52F2 E0101; Moji_Joho; MJ007731 -52F2 E0102; Hanyo-Denshi; JTAE51 -52F2 E0102; Moji_Joho; MJ007732 -52F3 E0100; Adobe-Japan1; CID+4291 -52F3 E0101; Hanyo-Denshi; JA5014 -52F3 E0101; Moji_Joho; MJ007733 -52F3 E0102; Hanyo-Denshi; FT2093 -52F3 E0102; Moji_Joho; MJ007734 -52F4 E0100; Adobe-Japan1; CID+21218 -52F5 E0100; Adobe-Japan1; CID+4292 -52F5 E0101; Hanyo-Denshi; JA5015 -52F5 E0101; Moji_Joho; MJ007736 -52F5 E0102; Hanyo-Denshi; KS028720 -52F5 E0102; Moji_Joho; MJ007737 -52F6 E0100; Adobe-Japan1; CID+21219 -52F7 E0100; Adobe-Japan1; CID+17328 -52F8 E0100; Adobe-Japan1; CID+4293 -52F8 E0101; Hanyo-Denshi; JA5016 -52F8 E0101; Moji_Joho; MJ007740 -52F8 E0102; Hanyo-Denshi; KS028870 -52F8 E0102; Moji_Joho; MJ007741 -52F8 E0103; Hanyo-Denshi; TK01011360 -52F9 E0100; Adobe-Japan1; CID+4294 -52F9 E0101; Moji_Joho; MJ007742 -52F9 E0102; Moji_Joho; MJ007743 -52FA E0100; Adobe-Japan1; CID+13807 -52FA E0101; Adobe-Japan1; CID+2311 -52FA E0102; Hanyo-Denshi; JA2859 -52FA E0102; Moji_Joho; MJ007745 -52FA E0103; Hanyo-Denshi; JTAE53 -52FA E0103; Moji_Joho; MJ007744 -52FB E0100; Adobe-Japan1; CID+16799 -52FE E0100; Adobe-Japan1; CID+1967 -52FF E0100; Adobe-Japan1; CID+3818 -5300 E0100; Adobe-Japan1; CID+8403 -5300 E0101; Adobe-Japan1; CID+14287 -5301 E0100; Adobe-Japan1; CID+3828 -5302 E0100; Adobe-Japan1; CID+3279 -5303 E0100; Adobe-Japan1; CID+19201 -5304 E0100; Hanyo-Denshi; IP5304 -5304 E0100; Moji_Joho; MJ007755 -5304 E0101; Hanyo-Denshi; KS029180 -5304 E0101; Moji_Joho; MJ007756 -5305 E0100; Adobe-Japan1; CID+3649 -5305 E0101; Adobe-Japan1; CID+14019 -5305 E0102; Hanyo-Denshi; JA4281 -5305 E0102; Moji_Joho; MJ007758 -5305 E0103; Hanyo-Denshi; IB1488 -5305 E0103; Moji_Joho; MJ007757 -5306 E0100; Adobe-Japan1; CID+4295 -5306 E0101; Hanyo-Denshi; JA5018 -5306 E0101; Moji_Joho; MJ007760 -5306 E0102; Hanyo-Denshi; JTAE55 -5306 E0102; Moji_Joho; MJ007759 -5307 E0100; Adobe-Japan1; CID+20301 -5307 E0101; Adobe-Japan1; CID+8404 -5307 E0102; Hanyo-Denshi; JC1476 -5307 E0102; Moji_Joho; MJ007761 -5307 E0103; Hanyo-Denshi; JTAFB6 -5307 E0103; Moji_Joho; MJ007762 -5308 E0100; Adobe-Japan1; CID+4296 -5308 E0101; Hanyo-Denshi; JA5019 -5308 E0101; Moji_Joho; MJ007763 -5308 E0102; Hanyo-Denshi; KS029160 -5308 E0103; Hanyo-Denshi; KS029170 -5308 E0103; Moji_Joho; MJ057080 -5308 E0104; Hanyo-Denshi; KS029220 -5308 E0104; Moji_Joho; MJ057081 -530A E0100; Adobe-Japan1; CID+14364 -530B E0100; Adobe-Japan1; CID+14365 -530B E0101; Moji_Joho; MJ007766 -530B E0102; Moji_Joho; MJ057082 -530B E0103; Moji_Joho; MJ057083 -530C E0100; Adobe-Japan1; CID+21220 -530D E0100; Adobe-Japan1; CID+4298 -530F E0100; Adobe-Japan1; CID+4300 -530F E0101; Hanyo-Denshi; JA5023 -530F E0101; Moji_Joho; MJ007770 -530F E0102; Hanyo-Denshi; FT2094 -530F E0102; Moji_Joho; MJ007771 -5310 E0100; Adobe-Japan1; CID+4299 -5311 E0100; Adobe-Japan1; CID+19202 -5313 E0100; Adobe-Japan1; CID+21221 -5315 E0100; Adobe-Japan1; CID+4301 -5315 E0101; Adobe-Japan1; CID+7983 -5316 E0100; Adobe-Japan1; CID+1341 -5316 E0101; Adobe-Japan1; CID+13665 -5316 E0102; Hanyo-Denshi; JA1829 -5316 E0102; Moji_Joho; MJ007779 -5316 E0103; Hanyo-Denshi; JTAD40 -5316 E0103; Moji_Joho; MJ007778 -5317 E0100; Adobe-Japan1; CID+3706 -5317 E0101; Moji_Joho; MJ007780 -5317 E0102; Moji_Joho; MJ007781 -5318 E0100; Adobe-Japan1; CID+21222 -5319 E0100; Adobe-Japan1; CID+2156 -531A E0100; Adobe-Japan1; CID+4302 -531B E0100; Adobe-Japan1; CID+21223 -531C E0100; Adobe-Japan1; CID+16800 -531D E0100; Adobe-Japan1; CID+2779 -531E E0100; Adobe-Japan1; CID+21224 -531F E0100; Adobe-Japan1; CID+19203 -5320 E0100; Adobe-Japan1; CID+2442 -5321 E0100; Adobe-Japan1; CID+1697 -5323 E0100; Adobe-Japan1; CID+4303 -5324 E0100; Adobe-Japan1; CID+8405 -5324 E0101; Hanyo-Denshi; JD0346 -5324 E0102; Hanyo-Denshi; TK01011620 -5325 E0100; Adobe-Japan1; CID+21225 -5327 E0100; Adobe-Japan1; CID+21226 -5328 E0100; Adobe-Japan1; CID+21227 -5329 E0100; Adobe-Japan1; CID+21228 -532A E0100; Adobe-Japan1; CID+3439 -532B E0100; Adobe-Japan1; CID+21229 -532C E0100; Adobe-Japan1; CID+21230 -532C E0101; Hanyo-Denshi; JB2014 -532C E0101; Moji_Joho; MJ007802 -532C E0102; Hanyo-Denshi; KS030860 -532C E0102; Moji_Joho; MJ007803 -532D E0100; Adobe-Japan1; CID+19204 -532F E0100; Adobe-Japan1; CID+4304 -5330 E0100; Adobe-Japan1; CID+21231 -5331 E0100; Adobe-Japan1; CID+4305 -5332 E0100; Adobe-Japan1; CID+19205 -5333 E0100; Adobe-Japan1; CID+4306 -5335 E0100; Adobe-Japan1; CID+17329 -5335 E0101; Hanyo-Denshi; JB2018 -5335 E0101; Moji_Joho; MJ007811 -5335 E0102; Hanyo-Denshi; IB1502 -5335 E0102; Moji_Joho; MJ007812 -5336 E0100; Hanyo-Denshi; KS031140 -5336 E0100; Moji_Joho; MJ007813 -5336 E0101; Hanyo-Denshi; KS031190 -5336 E0101; Moji_Joho; MJ007814 -5338 E0100; Adobe-Japan1; CID+4307 -5339 E0100; Adobe-Japan1; CID+3478 -5339 E0101; Adobe-Japan1; CID+13994 -5339 E0102; Hanyo-Denshi; JA4104 -5339 E0102; Moji_Joho; MJ007818 -5339 E0103; Hanyo-Denshi; KS030150S -5339 E0103; Moji_Joho; MJ007817 -533A E0100; Adobe-Japan1; CID+1760 -533B E0100; Adobe-Japan1; CID+1193 -533B E0101; Hanyo-Denshi; JA1669 -533B E0101; Moji_Joho; MJ007820 -533B E0102; Hanyo-Denshi; KS030470 -533B E0102; Moji_Joho; MJ007821 -533C E0100; Adobe-Japan1; CID+21232 -533C E0101; Hanyo-Denshi; JB2019 -533C E0101; Moji_Joho; MJ007822 -533C E0102; Hanyo-Denshi; IB1503 -533C E0102; Moji_Joho; MJ007823 -533C E0103; Hanyo-Denshi; JTAE5F -533C E0103; Moji_Joho; MJ007824 -533D E0100; Adobe-Japan1; CID+19206 -533D E0101; Moji_Joho; MJ007825 -533D E0102; Moji_Joho; MJ007826 -533E E0100; Adobe-Japan1; CID+14366 -533E E0101; Hanyo-Denshi; JB2021 -533E E0101; Moji_Joho; MJ007827 -533E E0102; Hanyo-Denshi; KS030840 -533E E0102; Moji_Joho; MJ007828 -533E E0103; Moji_Joho; MJ007829 -533F E0100; Adobe-Japan1; CID+3223 -533F E0101; Adobe-Japan1; CID+20087 -533F E0102; Hanyo-Denshi; JA3831 -533F E0102; Moji_Joho; MJ007830 -533F E0103; Hanyo-Denshi; KS030800 -533F E0103; Moji_Joho; MJ007831 -5340 E0100; Adobe-Japan1; CID+4308 -5340 E0101; Adobe-Japan1; CID+13524 -5340 E0102; Hanyo-Denshi; JA5031 -5340 E0102; Moji_Joho; MJ007832 -5340 E0103; Hanyo-Denshi; KS030850 -5340 E0103; Moji_Joho; MJ007833 -5341 E0100; Adobe-Japan1; CID+2375 -5342 E0100; Adobe-Japan1; CID+17330 -5343 E0100; Adobe-Japan1; CID+2701 -5344 E0100; Hanyo-Denshi; IP5344 -5344 E0100; Moji_Joho; MJ007837 -5344 E0101; Hanyo-Denshi; KS031360 -5344 E0101; Moji_Joho; MJ057090 -5345 E0100; Adobe-Japan1; CID+4310 -5345 E0101; Hanyo-Denshi; JA5033 -5345 E0101; Moji_Joho; MJ007838 -5345 E0102; Hanyo-Denshi; KS031680 -5345 E0102; Moji_Joho; MJ057092 -5346 E0100; Adobe-Japan1; CID+4309 -5347 E0100; Adobe-Japan1; CID+2443 -5347 E0101; Hanyo-Denshi; JA3003 -5347 E0102; Hanyo-Denshi; TK01011770 -5347 E0103; Hanyo-Denshi; TK01011780 -5347 E0104; Hanyo-Denshi; TK01011790 -5348 E0100; Adobe-Japan1; CID+1941 -5349 E0100; Adobe-Japan1; CID+4312 -534A E0100; Adobe-Japan1; CID+3410 -534A E0101; Adobe-Japan1; CID+13986 -534A E0102; Hanyo-Denshi; JA4030 -534A E0102; Moji_Joho; MJ007844 -534A E0103; Hanyo-Denshi; JTAE62 -534A E0103; Moji_Joho; MJ007843 -534B E0100; Adobe-Japan1; CID+14368 -534B E0101; Hanyo-Denshi; JB2024 -534B E0102; Hanyo-Denshi; TK01011860 -534C E0100; Adobe-Japan1; CID+14367 -534D E0100; Adobe-Japan1; CID+4313 -5351 E0100; Adobe-Japan1; CID+13378 -5351 E0101; Adobe-Japan1; CID+3440 -5351 E0102; Hanyo-Denshi; JA4060 -5351 E0103; Hanyo-Denshi; JC1478 -5352 E0100; Adobe-Japan1; CID+2836 -5352 E0101; Hanyo-Denshi; JA3420 -5352 E0101; Moji_Joho; MJ007852 -5352 E0102; Hanyo-Denshi; KS031880 -5352 E0102; Moji_Joho; MJ007853 -5353 E0100; Adobe-Japan1; CID+2894 -5354 E0100; Adobe-Japan1; CID+1696 -5357 E0100; Adobe-Japan1; CID+3270 -5358 E0100; Adobe-Japan1; CID+2927 -5359 E0100; Adobe-Japan1; CID+21233 -535A E0100; Adobe-Japan1; CID+3364 -535A E0101; Adobe-Japan1; CID+13976 -535A E0102; Hanyo-Denshi; JA3978 -535A E0102; Moji_Joho; MJ007860 -535A E0103; Hanyo-Denshi; JTAE6E -535A E0103; Moji_Joho; MJ007862 -535A E0104; Hanyo-Denshi; JTAE73 -535A E0104; Moji_Joho; MJ007859 -535A E0105; Hanyo-Denshi; JTAE6D -535A E0105; Moji_Joho; MJ059398 -535A E0106; Hanyo-Denshi; JTAE6C -535A E0106; Moji_Joho; MJ007861 -535A E0107; Hanyo-Denshi; TK01012070 -535A E0108; Hanyo-Denshi; TK01012160 -535A E0109; Hanyo-Denshi; TK01012170 -535A E010A; Moji_Joho; MJ059399 -535A E010B; Moji_Joho; MJ059400 -535B E0100; Adobe-Japan1; CID+21234 -535C E0100; Adobe-Japan1; CID+3708 -535E E0100; Adobe-Japan1; CID+4315 -535E E0101; Hanyo-Denshi; JA5038 -535E E0101; Moji_Joho; MJ007868 -535E E0102; Hanyo-Denshi; KS032260 -535E E0102; Moji_Joho; MJ007869 -5360 E0100; Adobe-Japan1; CID+2702 -5361 E0100; Adobe-Japan1; CID+14369 -5363 E0100; Adobe-Japan1; CID+16801 -5365 E0100; Adobe-Japan1; CID+19207 -5365 E0101; Adobe-Japan1; CID+21235 -5366 E0100; Adobe-Japan1; CID+1803 -5367 E0100; Adobe-Japan1; CID+17333 -5368 E0100; Hanyo-Denshi; IP5368 -5368 E0101; Hanyo-Denshi; TK01012360 -5369 E0100; Adobe-Japan1; CID+4316 -536C E0100; Adobe-Japan1; CID+14370 -536D E0100; Adobe-Japan1; CID+19208 -536E E0100; Adobe-Japan1; CID+4317 -536F E0100; Adobe-Japan1; CID+1230 -536F E0101; Hanyo-Denshi; JA1712 -536F E0101; Moji_Joho; MJ007885 -536F E0102; Hanyo-Denshi; KS032970 -536F E0102; Moji_Joho; MJ057108 -5370 E0100; Adobe-Japan1; CID+1209 -5371 E0100; Adobe-Japan1; CID+1577 -5371 E0101; Adobe-Japan1; CID+13696 -5371 E0102; Hanyo-Denshi; JA2077 -5371 E0102; Moji_Joho; MJ007888 -5371 E0103; Hanyo-Denshi; KS099150 -5371 E0103; Moji_Joho; MJ007889 -5371 E0104; Hanyo-Denshi; JTAE75 -5371 E0104; Moji_Joho; MJ007887 -5372 E0100; Adobe-Japan1; CID+8406 -5373 E0100; Adobe-Japan1; CID+2824 -5373 E0101; Hanyo-Denshi; JA3408 -5373 E0101; Moji_Joho; MJ007891 -5373 E0102; Hanyo-Denshi; KS033160 -5373 E0102; Moji_Joho; MJ007892 -5374 E0100; Adobe-Japan1; CID+1643 -5375 E0100; Adobe-Japan1; CID+3931 -5377 E0100; Adobe-Japan1; CID+4320 -5377 E0101; Hanyo-Denshi; JA5043 -5377 E0101; Moji_Joho; MJ007897 -5377 E0102; Hanyo-Denshi; JTAE76 -5377 E0102; Moji_Joho; MJ007898 -5377 E0103; Hanyo-Denshi; FT2101S -5377 E0103; Moji_Joho; MJ007900 -5377 E0104; Hanyo-Denshi; KS099280 -5377 E0104; Moji_Joho; MJ057415 -5377 E0105; Hanyo-Denshi; TK01007370 -5377 E0106; Moji_Joho; MJ007899 -5378 E0100; Adobe-Japan1; CID+1335 -5378 E0101; Adobe-Japan1; CID+13663 -5378 E0102; Moji_Joho; MJ007902 -5378 E0103; Moji_Joho; MJ007903 -5379 E0100; Adobe-Japan1; CID+19209 -537A E0100; Adobe-Japan1; CID+17334 -537B E0100; Adobe-Japan1; CID+4319 -537B E0101; Hanyo-Denshi; JA5042 -537B E0101; Moji_Joho; MJ007906 -537B E0102; Hanyo-Denshi; JTAE7A -537B E0102; Moji_Joho; MJ007907 -537D E0100; Adobe-Japan1; CID+13365 -537D E0101; Hanyo-Denshi; JC1481 -537D E0101; Moji_Joho; MJ007909 -537D E0102; Hanyo-Denshi; JTAE7B -537D E0102; Moji_Joho; MJ007893 -537E E0100; Adobe-Japan1; CID+19210 -537F E0100; Adobe-Japan1; CID+13719 -537F E0101; Adobe-Japan1; CID+1698 -537F E0102; Adobe-Japan1; CID+7661 -537F E0103; Hanyo-Denshi; JA2210 -537F E0103; Moji_Joho; MJ007911 -537F E0104; Hanyo-Denshi; FT1778 -537F E0104; Moji_Joho; MJ007915 -537F E0105; Hanyo-Denshi; KS033360 -537F E0105; Moji_Joho; MJ007913 -537F E0106; Hanyo-Denshi; JTAE7E -537F E0106; Moji_Joho; MJ007914 -537F E0107; Hanyo-Denshi; KS033350 -537F E0107; Moji_Joho; MJ007912 -5382 E0100; Adobe-Japan1; CID+4321 -5383 E0100; Adobe-Japan1; CID+21236 -5384 E0100; Adobe-Japan1; CID+3837 -5384 E0101; Hanyo-Denshi; JA4481 -5384 E0102; Hanyo-Denshi; TK01012610 -5387 E0100; Adobe-Japan1; CID+21237 -5388 E0100; Adobe-Japan1; CID+21238 -5389 E0100; Adobe-Japan1; CID+14288 -538B E0100; Hanyo-Denshi; TK01016250 -538B E0101; Hanyo-Denshi; TK01016280 -538E E0100; Adobe-Japan1; CID+21239 -5393 E0100; Adobe-Japan1; CID+8407 -5394 E0100; Adobe-Japan1; CID+19211 -5396 E0100; Adobe-Japan1; CID+4322 -5396 E0101; Hanyo-Denshi; JA5045 -5396 E0101; Moji_Joho; MJ007931 -5396 E0102; Hanyo-Denshi; JTAE85S -5396 E0102; Moji_Joho; MJ007932 -5398 E0100; Adobe-Japan1; CID+3994 -5399 E0100; Adobe-Japan1; CID+19212 -539A E0100; Adobe-Japan1; CID+1968 -539D E0100; Adobe-Japan1; CID+16802 -539F E0100; Adobe-Japan1; CID+1898 -53A0 E0100; Adobe-Japan1; CID+4323 -53A1 E0100; Adobe-Japan1; CID+21240 -53A4 E0100; Adobe-Japan1; CID+17335 -53A5 E0100; Adobe-Japan1; CID+4325 -53A6 E0100; Adobe-Japan1; CID+4324 -53A8 E0100; Adobe-Japan1; CID+2597 -53A9 E0100; Adobe-Japan1; CID+1243 -53A9 E0101; Adobe-Japan1; CID+7640 -53A9 E0102; Adobe-Japan1; CID+7964 -53A9 E0103; Adobe-Japan1; CID+13412 -53A9 E0104; Adobe-Japan1; CID+13647 -53A9 E0105; Adobe-Japan1; CID+20271 -53A9 E0106; Hanyo-Denshi; JA1725 -53A9 E0106; Moji_Joho; MJ007948 -53A9 E0107; Hanyo-Denshi; HG1614 -53A9 E0107; Moji_Joho; MJ007953 -53A9 E0108; Hanyo-Denshi; KS034890 -53A9 E0108; Moji_Joho; MJ007951 -53A9 E0109; Hanyo-Denshi; KS034790 -53A9 E0109; Moji_Joho; MJ007950 -53A9 E010A; Hanyo-Denshi; FT1758 -53A9 E010A; Moji_Joho; MJ007952 -53A9 E010B; Hanyo-Denshi; JTAE90 -53A9 E010B; Moji_Joho; MJ007955 -53A9 E010C; Moji_Joho; MJ007949 -53A9 E010D; Moji_Joho; MJ007954 -53AA E0100; Adobe-Japan1; CID+19213 -53AB E0100; Adobe-Japan1; CID+14371 -53AD E0100; Adobe-Japan1; CID+1280 -53AE E0100; Adobe-Japan1; CID+4326 -53AF E0100; Adobe-Japan1; CID+19214 -53B0 E0100; Adobe-Japan1; CID+4327 -53B0 E0101; Hanyo-Denshi; JA5050 -53B0 E0101; Moji_Joho; MJ007962 -53B0 E0102; Hanyo-Denshi; FT2102 -53B0 E0102; Moji_Joho; MJ007963 -53B2 E0100; Adobe-Japan1; CID+8408 -53B2 E0101; Hanyo-Denshi; JB2048 -53B2 E0101; Moji_Joho; MJ007966 -53B2 E0102; Hanyo-Denshi; KS035150 -53B2 E0102; Moji_Joho; MJ007965 -53B3 E0100; Adobe-Japan1; CID+1899 -53B4 E0100; Adobe-Japan1; CID+17336 -53B5 E0100; Adobe-Japan1; CID+21241 -53B6 E0100; Adobe-Japan1; CID+4328 -53B7 E0100; Adobe-Japan1; CID+17338 -53B7 E0101; Hanyo-Denshi; JB2051 -53B7 E0102; Hanyo-Denshi; TK01013110 -53B8 E0100; Adobe-Japan1; CID+21242 -53BA E0100; Adobe-Japan1; CID+19215 -53BB E0100; Adobe-Japan1; CID+1672 -53BD E0100; Adobe-Japan1; CID+21243 -53C0 E0100; Adobe-Japan1; CID+17339 -53C1 E0100; Adobe-Japan1; CID+19216 -53C2 E0100; Adobe-Japan1; CID+2176 -53C3 E0100; Adobe-Japan1; CID+4329 -53C4 E0100; Adobe-Japan1; CID+19217 -53C5 E0100; Adobe-Japan1; CID+19218 -53C8 E0100; Adobe-Japan1; CID+3746 -53C8 E0101; Moji_Joho; MJ007985 -53C8 E0102; Moji_Joho; MJ007986 -53C9 E0100; Adobe-Japan1; CID+2085 -53C9 E0101; Adobe-Japan1; CID+20281 -53C9 E0102; Moji_Joho; MJ007987 -53C9 E0103; Moji_Joho; MJ007988 -53CA E0100; Adobe-Japan1; CID+1652 -53CA E0101; Adobe-Japan1; CID+13710 -53CA E0102; Hanyo-Denshi; JA2158 -53CA E0102; Moji_Joho; MJ007990 -53CA E0103; Hanyo-Denshi; JTAE9B -53CA E0103; Moji_Joho; MJ007989 -53CA E0104; Hanyo-Denshi; TK01000530 -53CB E0100; Adobe-Japan1; CID+3857 -53CC E0100; Adobe-Japan1; CID+2770 -53CD E0100; Adobe-Japan1; CID+3411 -53CE E0100; Adobe-Japan1; CID+2345 -53CE E0101; Adobe-Japan1; CID+13455 -53CE E0102; Moji_Joho; MJ007995 -53CE E0103; Moji_Joho; MJ007996 -53CF E0100; Adobe-Japan1; CID+21244 -53D0 E0100; Hanyo-Denshi; IP53D0 -53D0 E0100; Moji_Joho; MJ007998 -53D0 E0101; Hanyo-Denshi; KS001630S -53D0 E0101; Moji_Joho; MJ056859 -53D2 E0100; Adobe-Japan1; CID+21245 -53D3 E0100; Adobe-Japan1; CID+21246 -53D3 E0101; Hanyo-Denshi; JB2059 -53D3 E0102; Hanyo-Denshi; TK01013420 -53D4 E0100; Adobe-Japan1; CID+2385 -53D4 E0101; Hanyo-Denshi; JA2939 -53D4 E0101; Moji_Joho; MJ008002 -53D4 E0102; Hanyo-Denshi; KS036640 -53D4 E0102; Moji_Joho; MJ057135 -53D5 E0100; Adobe-Japan1; CID+17343 -53D6 E0100; Adobe-Japan1; CID+2324 -53D7 E0100; Adobe-Japan1; CID+2337 -53D7 E0101; Adobe-Japan1; CID+13813 -53D9 E0100; Adobe-Japan1; CID+2432 -53DA E0100; Adobe-Japan1; CID+14372 -53DB E0100; Adobe-Japan1; CID+3412 -53DB E0101; Adobe-Japan1; CID+7978 -53DB E0102; Hanyo-Denshi; JA4032 -53DB E0102; Moji_Joho; MJ008010 -53DB E0103; Hanyo-Denshi; FT2920 -53DB E0103; Moji_Joho; MJ008009 -53DB E0104; Hanyo-Denshi; JTAE9F -53DB E0104; Moji_Joho; MJ008011 -53DB E0105; Hanyo-Denshi; JTAEA0 -53DB E0105; Moji_Joho; MJ008012 -53DB E0106; Hanyo-Denshi; KS036810 -53DB E0106; Moji_Joho; MJ057140 -53DC E0100; Hanyo-Denshi; IP53DC -53DC E0100; Moji_Joho; MJ008013 -53DC E0101; Hanyo-Denshi; KS036800 -53DC E0101; Moji_Joho; MJ057139 -53DD E0100; Adobe-Japan1; CID+8409 -53DD E0101; Hanyo-Denshi; JB2062 -53DD E0101; Moji_Joho; MJ008014 -53DD E0102; Hanyo-Denshi; JTAE97 -53DD E0102; Moji_Joho; MJ008015 -53DE E0100; Adobe-Japan1; CID+21247 -53DF E0100; Adobe-Japan1; CID+4332 -53DF E0101; Adobe-Japan1; CID+14111 -53DF E0102; Hanyo-Denshi; JA5055 -53DF E0102; Moji_Joho; MJ008018 -53DF E0103; Hanyo-Denshi; HG1640 -53DF E0103; Moji_Joho; MJ008019 -53DF E0104; Hanyo-Denshi; KS036510 -53DF E0104; Moji_Joho; MJ008017 -53E0 E0100; Adobe-Japan1; CID+19219 -53E0 E0101; Adobe-Japan1; CID+21248 -53E1 E0100; Adobe-Japan1; CID+1253 -53E2 E0100; Adobe-Japan1; CID+2771 -53E2 E0101; Hanyo-Denshi; JA3349 -53E2 E0102; Hanyo-Denshi; TK01013670 -53E3 E0100; Adobe-Japan1; CID+1969 -53E4 E0100; Adobe-Japan1; CID+1913 -53E5 E0100; Adobe-Japan1; CID+1759 -53E6 E0100; Adobe-Japan1; CID+14373 -53E7 E0100; Adobe-Japan1; CID+21249 -53E8 E0100; Adobe-Japan1; CID+4336 -53E9 E0100; Adobe-Japan1; CID+2911 -53EA E0100; Adobe-Japan1; CID+2910 -53EB E0100; Adobe-Japan1; CID+1699 -53EB E0101; Hanyo-Denshi; JA2211 -53EB E0101; Moji_Joho; MJ008032 -53EB E0102; Hanyo-Denshi; KS037640 -53EB E0102; Moji_Joho; MJ008031 -53EC E0100; Adobe-Japan1; CID+2444 -53ED E0100; Adobe-Japan1; CID+4337 -53ED E0101; Hanyo-Denshi; JA5060 -53ED E0101; Moji_Joho; MJ008034 -53ED E0102; Hanyo-Denshi; FT2103 -53ED E0102; Moji_Joho; MJ008035 -53EE E0100; Adobe-Japan1; CID+4335 -53EF E0100; Adobe-Japan1; CID+1348 -53F0 E0100; Adobe-Japan1; CID+2886 -53F1 E0100; Adobe-Japan1; CID+2276 -53F1 E0101; Adobe-Japan1; CID+7692 -53F1 E0102; Hanyo-Denshi; JA2824 -53F1 E0102; Moji_Joho; MJ008039 -53F1 E0103; Hanyo-Denshi; JTAEA9 -53F1 E0103; Moji_Joho; MJ008040 -53F2 E0100; Adobe-Japan1; CID+2201 -53F2 E0101; Adobe-Japan1; CID+13451 -53F2 E0102; Moji_Joho; MJ008041 -53F2 E0103; Moji_Joho; MJ008042 -53F3 E0100; Adobe-Japan1; CID+1224 -53F4 E0100; Adobe-Japan1; CID+17345 -53F5 E0100; Adobe-Japan1; CID+14374 -53F6 E0100; Adobe-Japan1; CID+1486 -53F7 E0100; Adobe-Japan1; CID+2040 -53F7 E0101; Hanyo-Denshi; JA2570 -53F7 E0101; Moji_Joho; MJ008047 -53F7 E0102; Hanyo-Denshi; KS037950 -53F7 E0102; Moji_Joho; MJ057144 -53F8 E0100; Adobe-Japan1; CID+2200 -53FA E0100; Adobe-Japan1; CID+4338 -5401 E0100; Adobe-Japan1; CID+4339 -5402 E0100; Adobe-Japan1; CID+21250 -5403 E0100; Adobe-Japan1; CID+1635 -5404 E0100; Adobe-Japan1; CID+1444 -5406 E0100; Hanyo-Denshi; IP5406 -5406 E0100; Moji_Joho; MJ008060 -5406 E0101; Hanyo-Denshi; KS038410 -5406 E0101; Moji_Joho; MJ008061 -5408 E0100; Adobe-Japan1; CID+2041 -5409 E0100; Adobe-Japan1; CID+1634 -540A E0100; Adobe-Japan1; CID+3067 -540B E0100; Adobe-Japan1; CID+1223 -540C E0100; Adobe-Japan1; CID+3209 -540D E0100; Adobe-Japan1; CID+3786 -540E E0100; Adobe-Japan1; CID+1971 -540F E0100; Adobe-Japan1; CID+3939 -540F E0101; Adobe-Japan1; CID+13513 -540F E0102; Hanyo-Denshi; JA4589 -540F E0102; Moji_Joho; MJ008070 -540F E0103; Hanyo-Denshi; TK01013800 -540F E0104; Moji_Joho; MJ008071 -5410 E0100; Adobe-Japan1; CID+3137 -5411 E0100; Adobe-Japan1; CID+1970 -5412 E0100; Adobe-Japan1; CID+16803 -5413 E0100; Adobe-Japan1; CID+19220 -541A E0100; Adobe-Japan1; CID+21251 -541B E0100; Adobe-Japan1; CID+1797 -541B E0101; Hanyo-Denshi; JA2315 -541B E0101; Moji_Joho; MJ008081 -541B E0102; Hanyo-Denshi; JTAEB6 -541B E0102; Moji_Joho; MJ008082 -541D E0100; Adobe-Japan1; CID+4348 -541D E0101; Moji_Joho; MJ008084 -541D E0102; Moji_Joho; MJ008085 -541E E0100; Adobe-Japan1; CID+13964 -541F E0100; Adobe-Japan1; CID+1755 -541F E0101; Hanyo-Denshi; JA2267 -541F E0101; Moji_Joho; MJ008087 -541F E0102; Hanyo-Denshi; JTAEBES -541F E0102; Moji_Joho; MJ059417 -5420 E0100; Adobe-Japan1; CID+3704 -5421 E0100; Adobe-Japan1; CID+21252 -5424 E0100; Adobe-Japan1; CID+17346 -5426 E0100; Adobe-Japan1; CID+3441 -5427 E0100; Adobe-Japan1; CID+14375 -5428 E0100; Adobe-Japan1; CID+17347 -5429 E0100; Adobe-Japan1; CID+4347 -5429 E0101; Hanyo-Denshi; JA5070 -5429 E0101; Moji_Joho; MJ008097 -5429 E0102; Hanyo-Denshi; FT2106 -5429 E0102; Moji_Joho; MJ008098 -542A E0100; Adobe-Japan1; CID+19221 -542B E0100; Adobe-Japan1; CID+1562 -542B E0101; Hanyo-Denshi; JA2062 -542B E0101; Moji_Joho; MJ008100 -542B E0102; Hanyo-Denshi; KS040660 -542B E0102; Moji_Joho; MJ057151 -542C E0100; Adobe-Japan1; CID+4342 -542D E0100; Adobe-Japan1; CID+4343 -542E E0100; Adobe-Japan1; CID+4345 -542F E0100; Adobe-Japan1; CID+21253 -542F E0101; Hanyo-Denshi; JB2075 -542F E0102; Hanyo-Denshi; TK01013970 -542F E0103; Hanyo-Denshi; TK01034960 -5431 E0100; Adobe-Japan1; CID+19222 -5433 E0100; Adobe-Japan1; CID+13760 -5434 E0100; Adobe-Japan1; CID+19223 -5435 E0100; Adobe-Japan1; CID+19224 -5436 E0100; Adobe-Japan1; CID+4346 -5438 E0100; Adobe-Japan1; CID+1653 -5438 E0101; Adobe-Japan1; CID+13711 -5438 E0102; Hanyo-Denshi; JA2159 -5438 E0102; Moji_Joho; MJ008114 -5438 E0103; Hanyo-Denshi; JTAEB2 -5438 E0103; Moji_Joho; MJ008113 -5439 E0100; Adobe-Japan1; CID+2599 -543B E0100; Adobe-Japan1; CID+3581 -543C E0100; Adobe-Japan1; CID+4344 -543D E0100; Adobe-Japan1; CID+4340 -543E E0100; Adobe-Japan1; CID+1943 -543E E0101; Hanyo-Denshi; JA2467 -543E E0102; Hanyo-Denshi; TK01013740 -543F E0100; Adobe-Japan1; CID+13775 -5440 E0100; Adobe-Japan1; CID+4341 -5440 E0101; Adobe-Japan1; CID+20089 -5440 E0102; Hanyo-Denshi; JA5064 -5440 E0102; Moji_Joho; MJ008123 -5440 E0103; Hanyo-Denshi; FT2104SS -5440 E0103; Moji_Joho; MJ008124 -5442 E0100; Adobe-Japan1; CID+4042 -5443 E0100; Adobe-Japan1; CID+17349 -5444 E0100; Adobe-Japan1; CID+21254 -5446 E0100; Adobe-Japan1; CID+3650 -5447 E0100; Adobe-Japan1; CID+21255 -5448 E0100; Adobe-Japan1; CID+3076 -5448 E0101; Adobe-Japan1; CID+13942 -5448 E0102; Hanyo-Denshi; JA3672 -5448 E0102; Moji_Joho; MJ008133 -5448 E0103; Hanyo-Denshi; JTAEB0 -5448 E0103; Moji_Joho; MJ008134 -5448 E0104; Hanyo-Denshi; JTAEAF -5448 E0104; Moji_Joho; MJ008132 -5449 E0100; Adobe-Japan1; CID+1942 -544A E0100; Adobe-Japan1; CID+2050 -544C E0100; Adobe-Japan1; CID+19225 -544D E0100; Adobe-Japan1; CID+14376 -544E E0100; Adobe-Japan1; CID+4349 -544F E0100; Adobe-Japan1; CID+21256 -5451 E0100; Adobe-Japan1; CID+3253 -5455 E0100; Adobe-Japan1; CID+14115 -5455 E0101; Hanyo-Denshi; JD0368 -5455 E0101; Moji_Joho; MJ008144 -5455 E0102; Hanyo-Denshi; KS039610 -5455 E0102; Moji_Joho; MJ008145 -545E E0100; Adobe-Japan1; CID+21257 -545F E0100; Adobe-Japan1; CID+4353 -5462 E0100; Adobe-Japan1; CID+17350 -5464 E0100; Adobe-Japan1; CID+21258 -5466 E0100; Adobe-Japan1; CID+14377 -5467 E0100; Adobe-Japan1; CID+21259 -5468 E0100; Adobe-Japan1; CID+13815 -5468 E0101; Adobe-Japan1; CID+2346 -5468 E0102; Hanyo-Denshi; JA2894 -5468 E0102; Moji_Joho; MJ008159 -5468 E0103; Hanyo-Denshi; JTAEBAS -5468 E0103; Moji_Joho; MJ008158 -5469 E0100; Adobe-Japan1; CID+21260 -546A E0100; Adobe-Japan1; CID+2338 -546B E0100; Adobe-Japan1; CID+14378 -546C E0100; Adobe-Japan1; CID+17351 -546D E0100; Adobe-Japan1; CID+21261 -546E E0100; Adobe-Japan1; CID+21262 -5470 E0100; Adobe-Japan1; CID+4356 -5471 E0100; Adobe-Japan1; CID+4354 -5471 E0101; Hanyo-Denshi; JA5077 -5471 E0101; Moji_Joho; MJ008169 -5471 E0102; Hanyo-Denshi; KS040630 -5471 E0102; Moji_Joho; MJ008168 -5473 E0100; Adobe-Japan1; CID+3759 -5474 E0100; Adobe-Japan1; CID+14379 -5475 E0100; Adobe-Japan1; CID+4351 -5476 E0100; Adobe-Japan1; CID+4360 -5477 E0100; Adobe-Japan1; CID+4355 -547B E0100; Adobe-Japan1; CID+4358 -547C E0100; Adobe-Japan1; CID+1914 -547D E0100; Adobe-Japan1; CID+3787 -547F E0100; Adobe-Japan1; CID+16804 -5480 E0100; Adobe-Japan1; CID+4359 -5481 E0100; Adobe-Japan1; CID+21263 -5483 E0100; Adobe-Japan1; CID+21264 -5484 E0100; Adobe-Japan1; CID+4361 -5485 E0100; Adobe-Japan1; CID+21265 -5485 E0101; Hanyo-Denshi; JB2103 -5485 E0101; Moji_Joho; MJ008189 -5485 E0102; Hanyo-Denshi; JTAEBB -5485 E0102; Moji_Joho; MJ008190 -5486 E0100; Adobe-Japan1; CID+4363 -5486 E0101; Hanyo-Denshi; JA5086 -5486 E0101; Moji_Joho; MJ008191 -5486 E0102; Hanyo-Denshi; FT2108 -5486 E0102; Moji_Joho; MJ008192 -5488 E0100; Adobe-Japan1; CID+16805 -5489 E0100; Adobe-Japan1; CID+21266 -548A E0100; Adobe-Japan1; CID+8412 -548A E0101; Hanyo-Denshi; JD0376 -548A E0102; Hanyo-Denshi; TK01014170 -548B E0100; Adobe-Japan1; CID+2144 -548C E0100; Adobe-Japan1; CID+4072 -548D E0100; Adobe-Japan1; CID+14380 -548E E0100; Adobe-Japan1; CID+4352 -548E E0101; Hanyo-Denshi; JA5075 -548E E0101; Moji_Joho; MJ008201 -548E E0102; Hanyo-Denshi; KS040610 -548E E0102; Moji_Joho; MJ057147 -548E E0103; Hanyo-Denshi; KS040640 -548E E0103; Moji_Joho; MJ057149 -548F E0100; Adobe-Japan1; CID+4350 -5490 E0100; Adobe-Japan1; CID+4362 -5491 E0100; Adobe-Japan1; CID+21267 -5492 E0100; Adobe-Japan1; CID+4357 -5492 E0101; Hanyo-Denshi; JA5080 -5492 E0102; Hanyo-Denshi; TK01014080 -5495 E0100; Adobe-Japan1; CID+17352 -5496 E0100; Adobe-Japan1; CID+14381 -549C E0100; Adobe-Japan1; CID+8411 -549E E0100; Hanyo-Denshi; IP549E -549E E0100; Moji_Joho; MJ008213 -549E E0101; Hanyo-Denshi; KS039150 -549E E0101; Moji_Joho; MJ008212 -549F E0100; Adobe-Japan1; CID+21268 -54A0 E0100; Adobe-Japan1; CID+17353 -54A1 E0100; Adobe-Japan1; CID+14382 -54A2 E0100; Adobe-Japan1; CID+4365 -54A2 E0101; Hanyo-Denshi; JA5088 -54A2 E0101; Moji_Joho; MJ008217 -54A2 E0102; Hanyo-Denshi; KS041750 -54A2 E0102; Moji_Joho; MJ008218 -54A4 E0100; Adobe-Japan1; CID+4374 -54A5 E0100; Adobe-Japan1; CID+4367 -54A6 E0100; Adobe-Japan1; CID+17354 -54A7 E0100; Adobe-Japan1; CID+19226 -54A8 E0100; Adobe-Japan1; CID+4371 -54A9 E0100; Adobe-Japan1; CID+8413 -54AA E0100; Adobe-Japan1; CID+19227 -54AB E0100; Adobe-Japan1; CID+4372 -54AC E0100; Adobe-Japan1; CID+4368 -54AC E0101; Adobe-Japan1; CID+20277 -54AC E0102; Moji_Joho; MJ008228 -54AC E0103; Moji_Joho; MJ008229 -54AD E0100; Adobe-Japan1; CID+14383 -54AE E0100; Adobe-Japan1; CID+17355 -54AF E0100; Adobe-Japan1; CID+4401 -54B1 E0100; Adobe-Japan1; CID+19228 -54B2 E0100; Adobe-Japan1; CID+2137 -54B2 E0101; Adobe-Japan1; CID+13788 -54B2 E0102; Hanyo-Denshi; JA2673 -54B2 E0102; Moji_Joho; MJ008236 -54B2 E0103; Hanyo-Denshi; JTAEC5 -54B2 E0103; Moji_Joho; MJ008235 -54B3 E0100; Adobe-Japan1; CID+1423 -54B5 E0100; Hanyo-Denshi; IP54B5 -54B5 E0100; Moji_Joho; MJ008239 -54B5 E0101; Hanyo-Denshi; KS041760 -54B5 E0101; Moji_Joho; MJ008240 -54B7 E0100; Adobe-Japan1; CID+17356 -54B8 E0100; Adobe-Japan1; CID+4366 -54B9 E0100; Adobe-Japan1; CID+14384 -54BA E0100; Adobe-Japan1; CID+17357 -54BB E0100; Adobe-Japan1; CID+19229 -54BC E0100; Adobe-Japan1; CID+4376 -54BC E0101; Hanyo-Denshi; JA5105 -54BC E0101; Moji_Joho; MJ008247 -54BC E0102; Hanyo-Denshi; KS041770 -54BC E0102; Moji_Joho; MJ057153 -54BC E0103; Hanyo-Denshi; KS041780 -54BC E0103; Moji_Joho; MJ057154 -54BD E0100; Adobe-Japan1; CID+1210 -54BE E0100; Adobe-Japan1; CID+4375 -54BF E0100; Adobe-Japan1; CID+14385 -54C0 E0100; Adobe-Japan1; CID+1129 -54C1 E0100; Adobe-Japan1; CID+3516 -54C2 E0100; Adobe-Japan1; CID+4373 -54C3 E0100; Adobe-Japan1; CID+17358 -54C4 E0100; Adobe-Japan1; CID+4369 -54C6 E0100; Adobe-Japan1; CID+14386 -54C7 E0100; Adobe-Japan1; CID+4364 -54C8 E0100; Adobe-Japan1; CID+4370 -54C9 E0100; Adobe-Japan1; CID+2104 -54C9 E0101; Hanyo-Denshi; JA2640 -54C9 E0101; Moji_Joho; MJ008260 -54C9 E0102; Hanyo-Denshi; JTAEBF -54C9 E0102; Moji_Joho; MJ008261 -54CA E0100; Adobe-Japan1; CID+21269 -54CD E0100; Adobe-Japan1; CID+14387 -54CE E0100; Adobe-Japan1; CID+19230 -54CE E0101; Hanyo-Denshi; JB2128 -54CE E0101; Moji_Joho; MJ008265 -54CE E0102; Hanyo-Denshi; KS041660 -54CE E0102; Moji_Joho; MJ008266 -54D8 E0100; Adobe-Japan1; CID+4377 -54E0 E0100; Adobe-Japan1; CID+21270 -54E0 E0101; Hanyo-Denshi; JB2129 -54E0 E0101; Moji_Joho; MJ008270 -54E0 E0102; Hanyo-Denshi; JTAECA -54E0 E0102; Moji_Joho; MJ008271 -54E1 E0100; Adobe-Japan1; CID+1211 -54E2 E0100; Adobe-Japan1; CID+4386 -54E5 E0100; Adobe-Japan1; CID+4378 -54E6 E0100; Adobe-Japan1; CID+4379 -54E8 E0100; Adobe-Japan1; CID+2445 -54E8 E0101; Adobe-Japan1; CID+7703 -54E8 E0102; Hanyo-Denshi; JA3005 -54E8 E0102; Moji_Joho; MJ008280 -54E8 E0103; Hanyo-Denshi; FT1824 -54E8 E0103; Moji_Joho; MJ008279 -54E9 E0100; Adobe-Japan1; CID+3735 -54EA E0100; Adobe-Japan1; CID+19231 -54EC E0100; Adobe-Japan1; CID+17360 -54ED E0100; Adobe-Japan1; CID+4384 -54EE E0100; Adobe-Japan1; CID+4383 -54EF E0100; Adobe-Japan1; CID+17361 -54F1 E0100; Adobe-Japan1; CID+17362 -54F2 E0100; Adobe-Japan1; CID+3113 -54F2 E0101; Hanyo-Denshi; JA3715 -54F2 E0101; Moji_Joho; MJ008290 -54F2 E0102; Hanyo-Denshi; JTAEC9 -54F2 E0102; Moji_Joho; MJ008291 -54F3 E0100; Adobe-Japan1; CID+17363 -54F6 E0100; Adobe-Japan1; CID+21271 -54FA E0100; Adobe-Japan1; CID+4385 -54FC E0100; Adobe-Japan1; CID+19232 -54FD E0100; Adobe-Japan1; CID+4382 -54FD E0101; Moji_Joho; MJ008302 -54FD E0102; Moji_Joho; MJ008303 -54FE E0100; Adobe-Japan1; CID+21272 -54FE E0101; Hanyo-Denshi; JB2135 -54FE E0102; Hanyo-Denshi; TK01014440 -54FF E0100; Adobe-Japan1; CID+8414 -5500 E0100; Adobe-Japan1; CID+17364 -5501 E0100; Adobe-Japan1; CID+17365 -5504 E0100; Adobe-Japan1; CID+1238 -5505 E0100; Adobe-Japan1; CID+19233 -5506 E0100; Adobe-Japan1; CID+2086 -5506 E0101; Hanyo-Denshi; JA2622 -5506 E0101; Moji_Joho; MJ008314 -5506 E0102; Hanyo-Denshi; KS042470 -5506 E0102; Moji_Joho; MJ008313 -5507 E0100; Adobe-Japan1; CID+2550 -5508 E0100; Adobe-Japan1; CID+19234 -5509 E0100; Adobe-Japan1; CID+17366 -550C E0100; Adobe-Japan1; CID+21273 -550C E0101; Hanyo-Denshi; JB2142 -550C E0101; Moji_Joho; MJ008320 -550C E0102; Hanyo-Denshi; JTAEC3 -550C E0102; Moji_Joho; MJ008321 -550D E0100; Adobe-Japan1; CID+21274 -550E E0100; Adobe-Japan1; CID+14388 -550F E0100; Adobe-Japan1; CID+4380 -5510 E0100; Adobe-Japan1; CID+3164 -5510 E0101; Adobe-Japan1; CID+13955 -5510 E0102; Hanyo-Denshi; JA3766 -5510 E0102; Moji_Joho; MJ008326 -5510 E0103; Hanyo-Denshi; JTAEC7 -5510 E0103; Moji_Joho; MJ008325 -5514 E0100; Adobe-Japan1; CID+4381 -5515 E0100; Adobe-Japan1; CID+19235 -5516 E0100; Adobe-Japan1; CID+1126 -5527 E0100; Adobe-Japan1; CID+19236 -5527 E0101; Hanyo-Denshi; FT2112 -5527 E0102; Hanyo-Denshi; TK01014380 -552A E0100; Adobe-Japan1; CID+19237 -552B E0100; Adobe-Japan1; CID+14389 -552C E0100; Hanyo-Denshi; IP552C -552C E0101; Hanyo-Denshi; TK01014730 -552E E0100; Adobe-Japan1; CID+4391 -552F E0100; Adobe-Japan1; CID+3853 -5531 E0100; Adobe-Japan1; CID+2447 -5532 E0100; Adobe-Japan1; CID+21275 -5533 E0100; Adobe-Japan1; CID+4397 -5533 E0101; Adobe-Japan1; CID+7819 -5533 E0102; Adobe-Japan1; CID+14113 -5533 E0103; Hanyo-Denshi; JA5126 -5533 E0103; Moji_Joho; MJ008349 -5533 E0104; Hanyo-Denshi; FT1947 -5533 E0104; Moji_Joho; MJ008351 -5533 E0105; Hanyo-Denshi; JTAED3 -5533 E0105; Moji_Joho; MJ008350 -5535 E0100; Adobe-Japan1; CID+14390 -5536 E0100; Adobe-Japan1; CID+19238 -5538 E0100; Adobe-Japan1; CID+4396 -5539 E0100; Adobe-Japan1; CID+4387 -5539 E0101; Adobe-Japan1; CID+7818 -5539 E0102; Hanyo-Denshi; JA5116 -5539 E0102; Moji_Joho; MJ008357 -5539 E0103; Hanyo-Denshi; FT1946S -5539 E0103; Moji_Joho; MJ008358 -553B E0100; Adobe-Japan1; CID+21276 -553C E0100; Adobe-Japan1; CID+17367 -553D E0100; Adobe-Japan1; CID+21277 -553E E0100; Adobe-Japan1; CID+2851 -5540 E0100; Adobe-Japan1; CID+4388 -5541 E0100; Adobe-Japan1; CID+17368 -5541 E0101; Hanyo-Denshi; JB2154 -5541 E0102; Hanyo-Denshi; TK01014700 -5544 E0100; Adobe-Japan1; CID+2895 -5544 E0101; Adobe-Japan1; CID+7730 -5544 E0102; Hanyo-Denshi; JA3479 -5544 E0102; Moji_Joho; MJ008370 -5544 E0103; Hanyo-Denshi; IB1535S -5544 E0103; Moji_Joho; MJ008374 -5544 E0104; Hanyo-Denshi; FT2042 -5544 E0104; Moji_Joho; MJ008372 -5544 E0105; Hanyo-Denshi; FT1850 -5544 E0105; Moji_Joho; MJ008371 -5544 E0106; Moji_Joho; MJ008373 -5545 E0100; Adobe-Japan1; CID+4393 -5546 E0100; Adobe-Japan1; CID+2446 -5546 E0101; Adobe-Japan1; CID+13830 -5546 E0102; Hanyo-Denshi; JA3006 -5546 E0102; Moji_Joho; MJ008376 -5546 E0103; Hanyo-Denshi; JTAED2 -5546 E0103; Moji_Joho; MJ008377 -5546 E0104; Hanyo-Denshi; KS044540 -5546 E0104; Moji_Joho; MJ057166 -5547 E0100; Adobe-Japan1; CID+17370 -5547 E0101; Hanyo-Denshi; JB2155 -5547 E0101; Moji_Joho; MJ008378 -5547 E0102; Hanyo-Denshi; KS044510S -5547 E0102; Moji_Joho; MJ057165 -5549 E0100; Adobe-Japan1; CID+21278 -554A E0100; Adobe-Japan1; CID+14391 -554C E0100; Adobe-Japan1; CID+4390 -554C E0101; Hanyo-Denshi; JA5119 -554C E0101; Moji_Joho; MJ008383 -554C E0102; Hanyo-Denshi; JTAED9 -554C E0102; Moji_Joho; MJ008384 -554D E0100; Adobe-Japan1; CID+21279 -554F E0100; Adobe-Japan1; CID+3824 -5550 E0100; Adobe-Japan1; CID+16806 -5551 E0100; Adobe-Japan1; CID+19239 -5553 E0100; Adobe-Japan1; CID+1810 -5553 E0101; Adobe-Japan1; CID+13738 -5553 E0102; Hanyo-Denshi; JA2328 -5553 E0102; Moji_Joho; MJ008392 -5553 E0103; Hanyo-Denshi; JTAECE -5553 E0103; Moji_Joho; MJ008391 -5554 E0100; Hanyo-Denshi; IP5554 -5554 E0101; Hanyo-Denshi; TK01014490 -5556 E0100; Adobe-Japan1; CID+4394 -5557 E0100; Adobe-Japan1; CID+4395 -5558 E0100; Adobe-Japan1; CID+21280 -555A E0100; Adobe-Japan1; CID+21281 -555A E0101; Hanyo-Denshi; JB2162 -555A E0101; Moji_Joho; MJ008400 -555A E0102; Hanyo-Denshi; KS044550 -555A E0102; Moji_Joho; MJ008401 -555A E0103; Moji_Joho; MJ057180 -555B E0100; Adobe-Japan1; CID+21282 -555C E0100; Adobe-Japan1; CID+4392 -555D E0100; Adobe-Japan1; CID+4398 -555D E0101; Hanyo-Denshi; JA5127 -555D E0101; Moji_Joho; MJ008404 -555D E0102; Hanyo-Denshi; JTAEDA -555D E0102; Moji_Joho; MJ008405 -555E E0100; Adobe-Japan1; CID+7633 -5560 E0100; Adobe-Japan1; CID+14392 -5561 E0100; Adobe-Japan1; CID+20308 -5561 E0101; Adobe-Japan1; CID+14393 -5563 E0100; Adobe-Japan1; CID+4389 -5564 E0100; Adobe-Japan1; CID+17372 -5566 E0100; Adobe-Japan1; CID+19240 -5568 E0100; Hanyo-Denshi; IB0441 -5568 E0100; Moji_Joho; MJ008415 -5568 E0101; Hanyo-Denshi; IB1035 -5568 E0101; Moji_Joho; MJ008416 -557B E0100; Adobe-Japan1; CID+4404 -557C E0100; Adobe-Japan1; CID+4409 -557C E0101; Hanyo-Denshi; JA5138 -557C E0101; Moji_Joho; MJ008420 -557C E0102; Hanyo-Denshi; KS046180 -557C E0102; Moji_Joho; MJ008421 -557D E0100; Adobe-Japan1; CID+17374 -557E E0100; Adobe-Japan1; CID+4405 -557F E0100; Adobe-Japan1; CID+21283 -5580 E0100; Adobe-Japan1; CID+4400 -5581 E0100; Adobe-Japan1; CID+16807 -5582 E0100; Adobe-Japan1; CID+17375 -5583 E0100; Adobe-Japan1; CID+4410 -5584 E0100; Adobe-Japan1; CID+2739 -5584 E0101; Adobe-Japan1; CID+20062 -5584 E0102; Hanyo-Denshi; JA3317 -5584 E0102; Moji_Joho; MJ008429 -5584 E0103; Hanyo-Denshi; JTAEE9 -5584 E0103; Moji_Joho; MJ008431 -5584 E0104; Hanyo-Denshi; JTAEEA -5584 E0104; Moji_Joho; MJ008432 -5584 E0105; Hanyo-Denshi; JTAEEB -5584 E0105; Moji_Joho; MJ008433 -5584 E0106; Hanyo-Denshi; KS046170 -5584 E0106; Moji_Joho; MJ008430 -5586 E0100; Adobe-Japan1; CID+8415 -5586 E0101; Hanyo-Denshi; JB2172 -5586 E0101; Moji_Joho; MJ008435 -5586 E0102; Hanyo-Denshi; JTAEEC -5586 E0102; Moji_Joho; MJ008436 -5587 E0100; Adobe-Japan1; CID+4412 -5588 E0100; Adobe-Japan1; CID+14394 -5589 E0100; Adobe-Japan1; CID+1972 -558A E0100; Adobe-Japan1; CID+4402 -558B E0100; Adobe-Japan1; CID+3003 -558E E0100; Adobe-Japan1; CID+14395 -558F E0100; Adobe-Japan1; CID+19241 -558F E0101; Hanyo-Denshi; JB2175 -558F E0101; Moji_Joho; MJ008445 -558F E0102; Hanyo-Denshi; KS045010 -558F E0102; Moji_Joho; MJ008446 -5591 E0100; Adobe-Japan1; CID+17376 -5591 E0101; Hanyo-Denshi; JB2176 -5591 E0101; Moji_Joho; MJ008448 -5591 E0102; Hanyo-Denshi; KS046190 -5591 E0102; Moji_Joho; MJ008449 -5592 E0100; Adobe-Japan1; CID+19242 -5593 E0100; Adobe-Japan1; CID+21284 -5593 E0101; Hanyo-Denshi; JB2178 -5593 E0101; Moji_Joho; MJ008451 -5593 E0102; Hanyo-Denshi; JTAEEE -5593 E0102; Moji_Joho; MJ008452 -5594 E0100; Adobe-Japan1; CID+19243 -5597 E0100; Adobe-Japan1; CID+21285 -5598 E0100; Adobe-Japan1; CID+4406 -5599 E0100; Adobe-Japan1; CID+4399 -5599 E0101; Hanyo-Denshi; JA5128 -5599 E0101; Moji_Joho; MJ008458 -5599 E0102; Hanyo-Denshi; FT2111 -5599 E0102; Moji_Joho; MJ008460 -5599 E0103; Hanyo-Denshi; JTAEE5 -5599 E0103; Moji_Joho; MJ008461 -5599 E0104; Moji_Joho; MJ008459 -559A E0100; Adobe-Japan1; CID+1513 -559C E0100; Adobe-Japan1; CID+1578 -559C E0101; Adobe-Japan1; CID+20091 -559C E0102; Hanyo-Denshi; JA2078 -559C E0102; Moji_Joho; MJ008464 -559C E0103; Hanyo-Denshi; JTAEED -559C E0103; Moji_Joho; MJ008465 -559C E0104; Hanyo-Denshi; KS046220 -559C E0104; Moji_Joho; MJ057175 -559C E0105; Hanyo-Denshi; TK01014960 -559C E0106; Hanyo-Denshi; TK01015040 -559D E0100; Adobe-Japan1; CID+1475 -559D E0101; Adobe-Japan1; CID+7651 -559D E0102; Hanyo-Denshi; JA1969 -559D E0103; Hanyo-Denshi; JC1512 -559E E0100; Adobe-Japan1; CID+4407 -559E E0101; Hanyo-Denshi; JA5136 -559E E0101; Moji_Joho; MJ008469 -559E E0102; Hanyo-Denshi; KS045360 -559E E0102; Moji_Joho; MJ008470 -559F E0100; Adobe-Japan1; CID+4403 -55A3 E0100; Adobe-Japan1; CID+21286 -55A4 E0100; Adobe-Japan1; CID+19244 -55A7 E0100; Adobe-Japan1; CID+1868 -55A8 E0100; Adobe-Japan1; CID+4413 -55A8 E0101; Hanyo-Denshi; JA5142 -55A8 E0101; Moji_Joho; MJ008480 -55A8 E0102; Hanyo-Denshi; JTAEEF -55A8 E0102; Moji_Joho; MJ008481 -55A9 E0100; Adobe-Japan1; CID+4411 -55A9 E0101; Adobe-Japan1; CID+7984 -55A9 E0102; Adobe-Japan1; CID+13526 -55A9 E0103; Hanyo-Denshi; JA5140 -55A9 E0103; Moji_Joho; MJ008482 -55A9 E0104; Hanyo-Denshi; FT1682 -55A9 E0104; Moji_Joho; MJ008483 -55AA E0100; Adobe-Japan1; CID+2773 -55AA E0101; Hanyo-Denshi; JA3351 -55AA E0101; Moji_Joho; MJ008484 -55AA E0102; Hanyo-Denshi; KS046230 -55AA E0102; Moji_Joho; MJ057176 -55AB E0100; Adobe-Japan1; CID+1636 -55AB E0101; Adobe-Japan1; CID+13707 -55AB E0102; Adobe-Japan1; CID+20092 -55AB E0103; Hanyo-Denshi; JA2142 -55AB E0103; Moji_Joho; MJ008486 -55AB E0104; Hanyo-Denshi; KS045610 -55AB E0104; Moji_Joho; MJ008485 -55AB E0105; Hanyo-Denshi; KS046140S -55AB E0105; Moji_Joho; MJ008487 -55AB E0106; Hanyo-Denshi; JTAEE4 -55AB E0106; Moji_Joho; MJ008488 -55AC E0100; Adobe-Japan1; CID+1700 -55AD E0100; Adobe-Japan1; CID+16808 -55AE E0100; Adobe-Japan1; CID+4408 -55AE E0101; Hanyo-Denshi; JA5137 -55AE E0101; Moji_Joho; MJ008491 -55AE E0102; Hanyo-Denshi; KS046250 -55AE E0102; Moji_Joho; MJ057178 -55B0 E0100; Adobe-Japan1; CID+1772 -55B0 E0101; Adobe-Japan1; CID+7664 -55B0 E0102; Hanyo-Denshi; JA2284 -55B0 E0102; Moji_Joho; MJ008493 -55B0 E0103; Hanyo-Denshi; HG1618 -55B0 E0103; Moji_Joho; MJ008494 -55B2 E0100; Adobe-Japan1; CID+19245 -55B6 E0100; Adobe-Japan1; CID+1254 -55BB E0100; Hanyo-Denshi; FT2113 -55BB E0100; Moji_Joho; MJ008501 -55BB E0101; Hanyo-Denshi; JTAEE2 -55BB E0101; Moji_Joho; MJ008502 -55BF E0100; Adobe-Japan1; CID+17381 -55C1 E0100; Adobe-Japan1; CID+21287 -55C2 E0100; Hanyo-Denshi; IP55C2 -55C2 E0100; Moji_Joho; MJ008507 -55C2 E0101; Hanyo-Denshi; KS047450 -55C2 E0101; Moji_Joho; MJ008508 -55C3 E0100; Adobe-Japan1; CID+19246 -55C4 E0100; Adobe-Japan1; CID+4417 -55C5 E0100; Adobe-Japan1; CID+4415 -55C5 E0101; Hanyo-Denshi; JA5144 -55C5 E0101; Moji_Joho; MJ008511 -55C5 E0102; Hanyo-Denshi; FT2114 -55C5 E0102; Moji_Joho; MJ008512 -55C6 E0100; Adobe-Japan1; CID+19247 -55C7 E0100; Adobe-Japan1; CID+4472 -55C9 E0100; Adobe-Japan1; CID+17382 -55CB E0100; Adobe-Japan1; CID+21288 -55CC E0100; Adobe-Japan1; CID+17383 -55CE E0100; Adobe-Japan1; CID+16809 -55D0 E0100; Hanyo-Denshi; IP55D0 -55D0 E0100; Moji_Joho; MJ008523 -55D0 E0101; Hanyo-Denshi; KS047560 -55D0 E0101; Moji_Joho; MJ008524 -55D1 E0100; Adobe-Japan1; CID+17384 -55D2 E0100; Adobe-Japan1; CID+17378 -55D2 E0101; Hanyo-Denshi; JB2194 -55D2 E0101; Moji_Joho; MJ008526 -55D2 E0102; Hanyo-Denshi; KS046760 -55D2 E0102; Moji_Joho; MJ008527 -55D3 E0100; Adobe-Japan1; CID+19248 -55D4 E0100; Adobe-Japan1; CID+4420 -55D4 E0101; Hanyo-Denshi; JA5149 -55D4 E0101; Moji_Joho; MJ008529 -55D4 E0102; Hanyo-Denshi; FT2115 -55D4 E0102; Moji_Joho; MJ059423 -55D7 E0100; Adobe-Japan1; CID+21289 -55D8 E0100; Adobe-Japan1; CID+21290 -55DA E0100; Adobe-Japan1; CID+4414 -55DB E0100; Adobe-Japan1; CID+19249 -55DC E0100; Adobe-Japan1; CID+4418 -55DD E0100; Adobe-Japan1; CID+17385 -55DD E0101; Hanyo-Denshi; JD0423 -55DD E0101; Moji_Joho; MJ008539 -55DD E0102; Hanyo-Denshi; KS047040 -55DD E0102; Moji_Joho; MJ008538 -55DE E0100; Adobe-Japan1; CID+21291 -55DE E0101; Hanyo-Denshi; JB2205 -55DE E0101; Moji_Joho; MJ008540 -55DE E0102; Hanyo-Denshi; KS047050 -55DE E0102; Moji_Joho; MJ008541 -55DF E0100; Adobe-Japan1; CID+4416 -55E2 E0100; Adobe-Japan1; CID+17387 -55E2 E0101; Hanyo-Denshi; JB2206 -55E2 E0101; Moji_Joho; MJ008546 -55E2 E0102; Hanyo-Denshi; KS046260 -55E2 E0102; Moji_Joho; MJ008545 -55E3 E0100; Adobe-Japan1; CID+2202 -55E3 E0101; Hanyo-Denshi; JA2744 -55E3 E0102; Hanyo-Denshi; JTAEFF -55E4 E0100; Adobe-Japan1; CID+4419 -55E4 E0101; Adobe-Japan1; CID+7820 -55E4 E0102; Adobe-Japan1; CID+14114 -55E4 E0103; Hanyo-Denshi; JA5148 -55E4 E0103; Moji_Joho; MJ008549 -55E4 E0104; Hanyo-Denshi; JTAEF2S -55E4 E0104; Moji_Joho; MJ008550 -55E4 E0105; Hanyo-Denshi; JTAEF3 -55E4 E0105; Moji_Joho; MJ008551 -55E9 E0100; Adobe-Japan1; CID+17389 -55EC E0100; Adobe-Japan1; CID+19250 -55EE E0100; Adobe-Japan1; CID+19251 -55F1 E0100; Adobe-Japan1; CID+19252 -55F6 E0100; Adobe-Japan1; CID+19253 -55F7 E0100; Adobe-Japan1; CID+4422 -55F8 E0100; Adobe-Japan1; CID+19254 -55F9 E0100; Adobe-Japan1; CID+4427 -55F9 E0101; Hanyo-Denshi; JA5156 -55F9 E0101; Moji_Joho; MJ008562 -55F9 E0102; Hanyo-Denshi; FT2117 -55F9 E0102; Moji_Joho; MJ008561 -55FD E0100; Adobe-Japan1; CID+4425 -55FE E0100; Adobe-Japan1; CID+4424 -55FF E0100; Adobe-Japan1; CID+21292 -5605 E0100; Adobe-Japan1; CID+19255 -5605 E0101; Adobe-Japan1; CID+21293 -5605 E0102; Hanyo-Denshi; JB2210 -5605 E0102; Moji_Joho; MJ008574 -5605 E0103; Hanyo-Denshi; IB1551 -5605 E0103; Moji_Joho; MJ008576 -5605 E0104; Hanyo-Denshi; JTAF00 -5605 E0104; Moji_Joho; MJ008575 -5605 E0105; Moji_Joho; MJ008577 -5606 E0100; Adobe-Japan1; CID+13366 -5606 E0101; Adobe-Japan1; CID+2928 -5606 E0102; Hanyo-Denshi; JA3518 -5606 E0103; Hanyo-Denshi; JC1515 -5607 E0100; Adobe-Japan1; CID+17392 -5608 E0100; Adobe-Japan1; CID+14396 -5609 E0100; Adobe-Japan1; CID+1349 -5609 E0101; Adobe-Japan1; CID+20093 -5609 E0102; Hanyo-Denshi; JA1837 -5609 E0102; Moji_Joho; MJ008581 -5609 E0103; Hanyo-Denshi; JTAF03 -5609 E0103; Moji_Joho; MJ008582 -5609 E0104; Hanyo-Denshi; JTAFA8 -5609 E0104; Moji_Joho; MJ008583 -5609 E0105; Hanyo-Denshi; TK01017810 -560A E0100; Adobe-Japan1; CID+21294 -560D E0100; Adobe-Japan1; CID+19256 -560E E0100; Adobe-Japan1; CID+14397 -560F E0100; Adobe-Japan1; CID+14398 -5610 E0100; Adobe-Japan1; CID+17393 -5611 E0100; Adobe-Japan1; CID+19257 -5612 E0100; Adobe-Japan1; CID+19258 -5614 E0100; Adobe-Japan1; CID+4421 -5614 E0101; Hanyo-Denshi; JA5150 -5614 E0101; Moji_Joho; MJ008595 -5614 E0102; Hanyo-Denshi; KS048610 -5614 E0102; Moji_Joho; MJ008596 -5616 E0100; Adobe-Japan1; CID+4423 -5617 E0100; Adobe-Japan1; CID+2448 -5618 E0100; Adobe-Japan1; CID+1237 -5619 E0100; Adobe-Japan1; CID+21295 -561B E0100; Adobe-Japan1; CID+4426 -561B E0101; Hanyo-Denshi; JA5155 -561B E0101; Moji_Joho; MJ008603 -561B E0102; Hanyo-Denshi; FT2116 -561B E0102; Moji_Joho; MJ008604 -5620 E0100; Adobe-Japan1; CID+15389 -5628 E0100; Adobe-Japan1; CID+17390 -5629 E0100; Adobe-Japan1; CID+1374 -5629 E0101; Hanyo-Denshi; JA1862 -5629 E0101; Moji_Joho; MJ008610 -5629 E0102; Hanyo-Denshi; KS048620 -5629 E0102; Moji_Joho; MJ008611 -562C E0100; Adobe-Japan1; CID+19259 -562C E0101; Hanyo-Denshi; JB2220 -562C E0101; Moji_Joho; MJ008615 -562C E0102; Hanyo-Denshi; KS048650 -562C E0102; Moji_Joho; MJ008614 -562F E0100; Adobe-Japan1; CID+4437 -5630 E0100; Adobe-Japan1; CID+17394 -5630 E0101; Hanyo-Denshi; JB2221 -5630 E0101; Moji_Joho; MJ008619 -5630 E0102; Hanyo-Denshi; JTAF10 -5630 E0102; Moji_Joho; MJ008620 -5631 E0100; Adobe-Japan1; CID+2532 -5632 E0100; Adobe-Japan1; CID+4433 -5632 E0101; Adobe-Japan1; CID+7821 -5632 E0102; Hanyo-Denshi; JA5162 -5632 E0102; Moji_Joho; MJ008623 -5632 E0103; Hanyo-Denshi; FT1948 -5632 E0103; Moji_Joho; MJ008622 -5633 E0100; Adobe-Japan1; CID+21296 -5634 E0100; Adobe-Japan1; CID+4431 -5635 E0100; Adobe-Japan1; CID+19260 -5636 E0100; Adobe-Japan1; CID+4432 -5637 E0100; Adobe-Japan1; CID+14399 -5638 E0100; Adobe-Japan1; CID+4434 -5639 E0100; Adobe-Japan1; CID+19261 -563B E0100; Adobe-Japan1; CID+16810 -563C E0100; Adobe-Japan1; CID+21297 -563D E0100; Adobe-Japan1; CID+17396 -563E E0100; Hanyo-Denshi; IP563E -563E E0100; Moji_Joho; MJ008636 -563E E0101; Hanyo-Denshi; KS049860 -563E E0101; Moji_Joho; MJ008637 -563F E0100; Adobe-Japan1; CID+14400 -5640 E0100; Adobe-Japan1; CID+17397 -5641 E0100; Adobe-Japan1; CID+21298 -5642 E0100; Adobe-Japan1; CID+1247 -5642 E0101; Adobe-Japan1; CID+7642 -5642 E0102; Hanyo-Denshi; JA1729 -5642 E0102; Moji_Joho; MJ008642 -5642 E0103; Hanyo-Denshi; HG1646 -5642 E0103; Moji_Joho; MJ008641 -5642 E0104; Moji_Joho; MJ008643 -5643 E0100; Adobe-Japan1; CID+21299 -5644 E0100; Adobe-Japan1; CID+21300 -5644 E0101; Hanyo-Denshi; JB2233 -5644 E0101; Moji_Joho; MJ008645 -5644 E0102; Hanyo-Denshi; JTAF11 -5644 E0102; Moji_Joho; MJ008646 -5646 E0100; Adobe-Japan1; CID+21301 -5646 E0101; Hanyo-Denshi; JB2234 -5646 E0101; Moji_Joho; MJ008649 -5646 E0102; Hanyo-Denshi; KS049210 -5646 E0102; Moji_Joho; MJ008648 -5647 E0100; Adobe-Japan1; CID+17398 -5647 E0101; Hanyo-Denshi; JD0438 -5647 E0101; Moji_Joho; MJ008650 -5647 E0102; Hanyo-Denshi; KS049870 -5647 E0102; Moji_Joho; MJ008651 -5649 E0100; Adobe-Japan1; CID+14401 -564B E0100; Adobe-Japan1; CID+14402 -564C E0100; Adobe-Japan1; CID+2747 -564C E0101; Adobe-Japan1; CID+7721 -564C E0102; Hanyo-Denshi; JA3325 -564C E0102; Moji_Joho; MJ008656 -564C E0103; Hanyo-Denshi; HG1641 -564C E0103; Moji_Joho; MJ008657 -564D E0100; Adobe-Japan1; CID+19262 -564E E0100; Adobe-Japan1; CID+4428 -564F E0100; Adobe-Japan1; CID+14403 -5650 E0100; Adobe-Japan1; CID+4429 -5650 E0101; Hanyo-Denshi; JA5158 -5650 E0102; Hanyo-Denshi; TK01015090 -5653 E0100; Adobe-Japan1; CID+7963 -5654 E0100; Adobe-Japan1; CID+19263 -565B E0100; Adobe-Japan1; CID+1496 -565E E0100; Adobe-Japan1; CID+17399 -5660 E0100; Adobe-Japan1; CID+17400 -5660 E0101; Hanyo-Denshi; JB2241 -5660 E0101; Moji_Joho; MJ008675 -5660 E0102; Hanyo-Denshi; IB0634 -5660 E0102; Moji_Joho; MJ008674 -5661 E0100; Adobe-Japan1; CID+21302 -5662 E0100; Adobe-Japan1; CID+21303 -5663 E0100; Adobe-Japan1; CID+21304 -5664 E0100; Adobe-Japan1; CID+4436 -5666 E0100; Adobe-Japan1; CID+14404 -5668 E0100; Adobe-Japan1; CID+1579 -5668 E0101; Adobe-Japan1; CID+13333 -5668 E0102; Hanyo-Denshi; JA2079 -5668 E0102; Moji_Joho; MJ008683 -5668 E0103; Hanyo-Denshi; JC1522 -5668 E0104; Hanyo-Denshi; JTAEDB -5668 E0104; Moji_Joho; MJ057164 -5668 E0105; Hanyo-Denshi; KS230860 -5668 E0105; Moji_Joho; MJ058033 -5668 E0106; Hanyo-Denshi; TK01014990 -5668 E0107; Hanyo-Denshi; TK01015250 -5668 E0108; Hanyo-Denshi; TK01015360 -5668 E0109; Hanyo-Denshi; TK01019600 -5668 E010A; Hanyo-Denshi; TK01019620 -5669 E0100; Adobe-Japan1; CID+14405 -566A E0100; Adobe-Japan1; CID+4439 -566B E0100; Adobe-Japan1; CID+4435 -566B E0101; Hanyo-Denshi; JA5164 -566B E0101; Moji_Joho; MJ008686 -566B E0102; Hanyo-Denshi; KS050780 -566B E0102; Moji_Joho; MJ008687 -566C E0100; Adobe-Japan1; CID+4438 -566D E0100; Adobe-Japan1; CID+17401 -566F E0100; Adobe-Japan1; CID+14406 -5671 E0100; Adobe-Japan1; CID+14407 -5671 E0101; Hanyo-Denshi; JB2249 -5671 E0101; Moji_Joho; MJ008693 -5671 E0102; Hanyo-Denshi; JTAF18 -5671 E0102; Moji_Joho; MJ008694 -5672 E0100; Adobe-Japan1; CID+14408 -5674 E0100; Adobe-Japan1; CID+3582 -5674 E0101; Adobe-Japan1; CID+13500 -5674 E0102; Hanyo-Denshi; JA4214 -5674 E0103; Hanyo-Denshi; KS050480 -5674 E0103; Moji_Joho; MJ008698 -5675 E0100; Adobe-Japan1; CID+21305 -5676 E0100; Adobe-Japan1; CID+15411 -5676 E0101; Hanyo-Denshi; JC1520 -5676 E0101; Moji_Joho; MJ008702 -5676 E0102; Hanyo-Denshi; KS050600 -5676 E0102; Moji_Joho; MJ008701 -5678 E0100; Adobe-Japan1; CID+3245 -5678 E0101; Adobe-Japan1; CID+7762 -5678 E0102; Hanyo-Denshi; JA3853 -5678 E0102; Moji_Joho; MJ008704 -5678 E0103; Hanyo-Denshi; FT1882 -5678 E0103; Moji_Joho; MJ008705 -567A E0100; Adobe-Japan1; CID+3404 -5680 E0100; Adobe-Japan1; CID+4441 -5680 E0101; Hanyo-Denshi; JA5170 -5680 E0101; Moji_Joho; MJ008711 -5680 E0102; Hanyo-Denshi; FT2119 -5680 E0102; Moji_Joho; MJ008712 -5683 E0100; Hanyo-Denshi; IB0636 -5683 E0100; Moji_Joho; MJ008715 -5683 E0101; Hanyo-Denshi; IP5683 -5683 E0101; Moji_Joho; MJ008716 -5684 E0100; Adobe-Japan1; CID+21306 -5684 E0101; Hanyo-Denshi; JB2252 -5684 E0101; Moji_Joho; MJ008717 -5684 E0102; Hanyo-Denshi; JTAF20 -5684 E0102; Moji_Joho; MJ008718 -5685 E0100; Adobe-Japan1; CID+19264 -5686 E0100; Adobe-Japan1; CID+4440 -5686 E0101; Hanyo-Denshi; JA5169 -5686 E0101; Moji_Joho; MJ008720 -5686 E0102; Hanyo-Denshi; KS051060 -5686 E0102; Moji_Joho; MJ008721 -5687 E0100; Adobe-Japan1; CID+1443 -5688 E0100; Adobe-Japan1; CID+17403 -568A E0100; Adobe-Japan1; CID+4442 -568A E0101; Hanyo-Denshi; JA5171 -568A E0101; Moji_Joho; MJ008725 -568A E0102; Hanyo-Denshi; FT2120 -568A E0102; Moji_Joho; MJ008726 -568B E0100; Adobe-Japan1; CID+21307 -568C E0100; Adobe-Japan1; CID+17404 -568F E0100; Adobe-Japan1; CID+4445 -5694 E0100; Adobe-Japan1; CID+4444 -5694 E0101; Hanyo-Denshi; JA5173 -5694 E0101; Moji_Joho; MJ008733 -5694 E0102; Hanyo-Denshi; JTAF27 -5694 E0102; Moji_Joho; MJ008734 -5694 E0103; Moji_Joho; MJ008735 -5695 E0100; Adobe-Japan1; CID+14409 -5699 E0100; Adobe-Japan1; CID+7654 -569A E0100; Adobe-Japan1; CID+14410 -569D E0100; Adobe-Japan1; CID+17405 -569D E0101; Hanyo-Denshi; JB2260 -569D E0101; Moji_Joho; MJ008744 -569D E0102; Hanyo-Denshi; JTAF21 -569D E0102; Moji_Joho; MJ008745 -569E E0100; Adobe-Japan1; CID+16811 -569E E0101; Hanyo-Denshi; JB2261 -569E E0102; Hanyo-Denshi; TK01015690 -569F E0100; Adobe-Japan1; CID+19265 -56A0 E0100; Adobe-Japan1; CID+4443 -56A0 E0101; Hanyo-Denshi; JA5172 -56A0 E0101; Moji_Joho; MJ008749 -56A0 E0102; Hanyo-Denshi; JTAF22 -56A0 E0102; Moji_Joho; MJ008750 -56A2 E0100; Adobe-Japan1; CID+3311 -56A5 E0100; Adobe-Japan1; CID+4446 -56A5 E0101; Adobe-Japan1; CID+7822 -56A5 E0102; Hanyo-Denshi; JA5175 -56A5 E0102; Moji_Joho; MJ008752 -56A5 E0103; Hanyo-Denshi; FT1949 -56A5 E0103; Moji_Joho; MJ008753 -56A6 E0100; Adobe-Japan1; CID+19266 -56A7 E0100; Adobe-Japan1; CID+21308 -56A8 E0100; Adobe-Japan1; CID+17406 -56A8 E0101; Hanyo-Denshi; JB2265 -56A8 E0101; Moji_Joho; MJ008757 -56A8 E0102; Hanyo-Denshi; KS052320 -56A8 E0102; Moji_Joho; MJ008758 -56A9 E0100; Adobe-Japan1; CID+16812 -56AB E0100; Adobe-Japan1; CID+21309 -56AC E0100; Adobe-Japan1; CID+14411 -56AD E0100; Adobe-Japan1; CID+14412 -56AE E0100; Adobe-Japan1; CID+4447 -56AE E0101; Adobe-Japan1; CID+7985 -56AE E0102; Adobe-Japan1; CID+20094 -56AE E0103; Adobe-Japan1; CID+20095 -56AE E0104; Hanyo-Denshi; JA5176 -56AE E0104; Moji_Joho; MJ008764 -56AE E0105; Hanyo-Denshi; KS052180 -56AE E0105; Moji_Joho; MJ008765 -56AE E0106; Hanyo-Denshi; FT2121 -56AE E0106; Moji_Joho; MJ008766 -56AE E0107; Hanyo-Denshi; JTAF2C -56AE E0107; Moji_Joho; MJ008767 -56B1 E0100; Adobe-Japan1; CID+14413 -56B2 E0100; Adobe-Japan1; CID+17407 -56B3 E0100; Adobe-Japan1; CID+16813 -56B3 E0101; Hanyo-Denshi; JB2271 -56B3 E0102; Hanyo-Denshi; TK01015730 -56B4 E0100; Adobe-Japan1; CID+4449 -56B6 E0100; Adobe-Japan1; CID+4448 -56B7 E0100; Adobe-Japan1; CID+19267 -56BC E0100; Adobe-Japan1; CID+4451 -56BC E0101; Hanyo-Denshi; JA5180 -56BC E0101; Moji_Joho; MJ008778 -56BC E0102; Hanyo-Denshi; FT2122 -56BC E0102; Moji_Joho; MJ008779 -56BE E0100; Adobe-Japan1; CID+21310 -56C0 E0100; Adobe-Japan1; CID+4454 -56C0 E0101; Adobe-Japan1; CID+14116 -56C0 E0102; Hanyo-Denshi; JA5183 -56C0 E0102; Moji_Joho; MJ008784 -56C0 E0103; Hanyo-Denshi; HG1650 -56C0 E0103; Moji_Joho; MJ008783 -56C1 E0100; Adobe-Japan1; CID+4452 -56C1 E0101; Adobe-Japan1; CID+13527 -56C1 E0102; Moji_Joho; MJ008785 -56C1 E0103; Moji_Joho; MJ008786 -56C1 E0104; Moji_Joho; MJ008787 -56C2 E0100; Adobe-Japan1; CID+4450 -56C3 E0100; Adobe-Japan1; CID+4453 -56C5 E0100; Adobe-Japan1; CID+17408 -56C8 E0100; Adobe-Japan1; CID+4455 -56C8 E0101; Hanyo-Denshi; JA5184 -56C8 E0101; Moji_Joho; MJ008793 -56C8 E0102; Hanyo-Denshi; KS052900 -56C8 E0102; Moji_Joho; MJ008794 -56C9 E0100; Adobe-Japan1; CID+14414 -56CA E0100; Adobe-Japan1; CID+7770 -56CB E0100; Adobe-Japan1; CID+21311 -56CC E0100; Adobe-Japan1; CID+19268 -56CC E0101; Hanyo-Denshi; JB2280 -56CC E0101; Moji_Joho; MJ008798 -56CC E0102; Hanyo-Denshi; KS053160 -56CC E0102; Moji_Joho; MJ008799 -56CD E0100; Adobe-Japan1; CID+17409 -56CE E0100; Adobe-Japan1; CID+4456 -56CE E0101; Adobe-Japan1; CID+20098 -56CE E0102; Hanyo-Denshi; JA5185 -56CE E0102; Moji_Joho; MJ008801 -56CE E0103; Hanyo-Denshi; FT2124 -56CE E0103; Moji_Joho; MJ008802 -56CE E0104; Hanyo-Denshi; JTAF33 -56CE E0104; Moji_Joho; MJ008803 -56CE E0105; Moji_Joho; MJ059441 -56CF E0100; Adobe-Japan1; CID+19269 -56D0 E0100; Adobe-Japan1; CID+21312 -56D1 E0100; Adobe-Japan1; CID+4457 -56D3 E0100; Adobe-Japan1; CID+4458 -56D3 E0101; Hanyo-Denshi; JA5187 -56D3 E0101; Moji_Joho; MJ008808 -56D3 E0102; Hanyo-Denshi; JTAF34 -56D3 E0102; Moji_Joho; MJ008810 -56D3 E0103; Hanyo-Denshi; KS053280S -56D3 E0103; Moji_Joho; MJ008809 -56D7 E0100; Adobe-Japan1; CID+4459 -56D8 E0100; Adobe-Japan1; CID+4220 -56D9 E0100; Adobe-Japan1; CID+19270 -56DA E0100; Adobe-Japan1; CID+2344 -56DB E0100; Adobe-Japan1; CID+2203 -56DB E0101; Hanyo-Denshi; JA2745 -56DB E0101; Moji_Joho; MJ008816 -56DB E0102; Hanyo-Denshi; IB0638 -56DB E0102; Moji_Joho; MJ008817 -56DC E0100; Adobe-Japan1; CID+21313 -56DD E0100; Adobe-Japan1; CID+14415 -56DE E0100; Adobe-Japan1; CID+1395 -56DF E0100; Adobe-Japan1; CID+17410 -56E0 E0100; Adobe-Japan1; CID+1212 -56E1 E0100; Adobe-Japan1; CID+19271 -56E2 E0100; Hanyo-Denshi; IP56E2 -56E2 E0101; Hanyo-Denshi; TK01015800 -56E3 E0100; Adobe-Japan1; CID+2946 -56E4 E0100; Adobe-Japan1; CID+14416 -56E5 E0100; Adobe-Japan1; CID+21314 -56E6 E0100; Adobe-Japan1; CID+21315 -56E7 E0100; Adobe-Japan1; CID+21316 -56E8 E0100; Adobe-Japan1; CID+17411 -56EB E0100; Adobe-Japan1; CID+19272 -56ED E0100; Adobe-Japan1; CID+19273 -56EE E0100; Adobe-Japan1; CID+4460 -56EE E0101; Adobe-Japan1; CID+20099 -56EE E0102; Hanyo-Denshi; JA5189 -56EE E0102; Moji_Joho; MJ008836 -56EE E0103; Hanyo-Denshi; KS054080 -56EE E0103; Moji_Joho; MJ008837 -56F0 E0100; Adobe-Japan1; CID+2068 -56F1 E0100; Adobe-Japan1; CID+19274 -56F2 E0100; Adobe-Japan1; CID+1171 -56F3 E0100; Adobe-Japan1; CID+2596 -56F6 E0100; Adobe-Japan1; CID+17412 -56F6 E0101; Hanyo-Denshi; JB2301 -56F6 E0101; Moji_Joho; MJ008843 -56F6 E0102; Hanyo-Denshi; JTAF38 -56F6 E0102; Moji_Joho; MJ008844 -56F6 E0103; Hanyo-Denshi; TK01015840 -56F7 E0100; Adobe-Japan1; CID+17413 -56F9 E0100; Adobe-Japan1; CID+4461 -56FA E0100; Adobe-Japan1; CID+1915 -56FD E0100; Adobe-Japan1; CID+2051 -56FF E0100; Adobe-Japan1; CID+4463 -5700 E0100; Adobe-Japan1; CID+4462 -5701 E0100; Adobe-Japan1; CID+21317 -5702 E0100; Adobe-Japan1; CID+21318 -5702 E0101; Hanyo-Denshi; JB2304 -5702 E0101; Moji_Joho; MJ008855 -5702 E0102; Hanyo-Denshi; IB1569 -5702 E0102; Moji_Joho; MJ008856 -5703 E0100; Adobe-Japan1; CID+3632 -5704 E0100; Adobe-Japan1; CID+4464 -5707 E0100; Adobe-Japan1; CID+19275 -5708 E0100; Adobe-Japan1; CID+4466 -5708 E0101; Hanyo-Denshi; JA5201 -5708 E0101; Moji_Joho; MJ008861 -5708 E0102; Hanyo-Denshi; FT2126S -5708 E0102; Moji_Joho; MJ008862 -5709 E0100; Adobe-Japan1; CID+4465 -570A E0100; Adobe-Japan1; CID+14417 -570A E0101; Hanyo-Denshi; JB2306 -570A E0101; Moji_Joho; MJ008864 -570A E0102; Hanyo-Denshi; IB0639 -570A E0102; Moji_Joho; MJ008865 -570B E0100; Adobe-Japan1; CID+4467 -570C E0100; Adobe-Japan1; CID+19276 -570D E0100; Adobe-Japan1; CID+4468 -570D E0101; Adobe-Japan1; CID+13528 -570D E0102; Hanyo-Denshi; JA5203 -570D E0102; Moji_Joho; MJ008868 -570D E0103; Hanyo-Denshi; FT2874S -570D E0103; Moji_Joho; MJ008869 -570D E0104; Moji_Joho; MJ008870 -570D E0105; Moji_Joho; MJ008871 -570F E0100; Adobe-Japan1; CID+1869 -5711 E0100; Adobe-Japan1; CID+21319 -5711 E0101; Hanyo-Denshi; JB2308 -5711 E0101; Moji_Joho; MJ008874 -5711 E0102; Hanyo-Denshi; JTAF41 -5711 E0102; Moji_Joho; MJ008875 -5711 E0103; Moji_Joho; MJ059444 -5712 E0100; Adobe-Japan1; CID+1282 -5713 E0100; Adobe-Japan1; CID+4469 -5715 E0100; Adobe-Japan1; CID+14418 -5716 E0100; Adobe-Japan1; CID+4471 -5716 E0101; Hanyo-Denshi; JA5206 -5716 E0101; Moji_Joho; MJ008880 -5716 E0102; Hanyo-Denshi; JTAF43 -5716 E0102; Moji_Joho; MJ057207 -5716 E0103; Hanyo-Denshi; JTAF44 -5716 E0103; Moji_Joho; MJ008881 -5717 E0100; Hanyo-Denshi; IP5717 -5717 E0100; Moji_Joho; MJ008882 -5717 E0101; Hanyo-Denshi; KS055250 -5717 E0101; Moji_Joho; MJ008883 -5717 E0102; Hanyo-Denshi; TK01016200 -5718 E0100; Adobe-Japan1; CID+4470 -571A E0100; Adobe-Japan1; CID+19277 -571B E0100; Adobe-Japan1; CID+19278 -571B E0101; Hanyo-Denshi; JB2311 -571B E0101; Moji_Joho; MJ008887 -571B E0102; Hanyo-Denshi; JTAF45 -571B E0102; Moji_Joho; MJ008888 -571C E0100; Adobe-Japan1; CID+4473 -571D E0100; Adobe-Japan1; CID+19279 -571F E0100; Adobe-Japan1; CID+3156 -5720 E0100; Adobe-Japan1; CID+21320 -5721 E0100; Adobe-Japan1; CID+13952 -5722 E0100; Adobe-Japan1; CID+21321 -5723 E0100; Adobe-Japan1; CID+14419 -5723 E0101; Moji_Joho; MJ008896 -5723 E0102; Moji_Joho; MJ008897 -5724 E0100; Adobe-Japan1; CID+21322 -5725 E0100; Adobe-Japan1; CID+21323 -5726 E0100; Adobe-Japan1; CID+4474 -5727 E0100; Adobe-Japan1; CID+1145 -5728 E0100; Adobe-Japan1; CID+2127 -5729 E0100; Adobe-Japan1; CID+17416 -572A E0100; Adobe-Japan1; CID+21324 -572C E0100; Adobe-Japan1; CID+19280 -572C E0101; Hanyo-Denshi; JB2320 -572C E0101; Moji_Joho; MJ008906 -572C E0102; Hanyo-Denshi; KS055970 -572C E0102; Moji_Joho; MJ008907 -572D E0100; Adobe-Japan1; CID+1811 -572D E0101; Hanyo-Denshi; JA2329 -572D E0101; Moji_Joho; MJ008908 -572D E0102; Hanyo-Denshi; KS056670 -572D E0102; Moji_Joho; MJ057213 -572D E0103; Hanyo-Denshi; TK01016300 -572E E0100; Adobe-Japan1; CID+19281 -572F E0100; Adobe-Japan1; CID+14420 -5730 E0100; Adobe-Japan1; CID+2957 -5733 E0100; Adobe-Japan1; CID+14421 -5734 E0100; Adobe-Japan1; CID+14422 -5734 E0101; Hanyo-Denshi; JB2324 -5734 E0101; Moji_Joho; MJ008916 -5734 E0102; Hanyo-Denshi; IB1573 -5734 E0102; Moji_Joho; MJ008917 -5737 E0100; Adobe-Japan1; CID+4475 -5738 E0100; Adobe-Japan1; CID+4476 -573B E0100; Adobe-Japan1; CID+4478 -573D E0100; Adobe-Japan1; CID+19282 -573E E0100; Adobe-Japan1; CID+19283 -573F E0100; Adobe-Japan1; CID+21325 -5740 E0100; Adobe-Japan1; CID+4479 -5742 E0100; Adobe-Japan1; CID+2132 -5745 E0100; Adobe-Japan1; CID+17418 -5746 E0100; Adobe-Japan1; CID+17419 -5747 E0100; Adobe-Japan1; CID+1737 -5747 E0101; Adobe-Japan1; CID+13432 -5747 E0102; Hanyo-Denshi; JA2249 -5747 E0102; Moji_Joho; MJ008934 -5747 E0103; Hanyo-Denshi; FT1617 -5747 E0103; Moji_Joho; MJ008935 -5748 E0100; Hanyo-Denshi; KS056180 -5748 E0100; Moji_Joho; MJ008936 -5748 E0101; Hanyo-Denshi; KS056650 -5748 E0101; Moji_Joho; MJ008937 -574A E0100; Adobe-Japan1; CID+3685 -574C E0100; Adobe-Japan1; CID+14423 -574D E0100; Adobe-Japan1; CID+17420 -574E E0100; Adobe-Japan1; CID+4477 -574F E0100; Adobe-Japan1; CID+4480 -5750 E0100; Adobe-Japan1; CID+2097 -5751 E0100; Adobe-Japan1; CID+1973 -5752 E0100; Adobe-Japan1; CID+21326 -5759 E0100; Adobe-Japan1; CID+8416 -575F E0100; Adobe-Japan1; CID+19284 -5761 E0100; Adobe-Japan1; CID+4484 -5762 E0100; Adobe-Japan1; CID+21327 -5764 E0100; Adobe-Japan1; CID+2069 -5765 E0100; Adobe-Japan1; CID+8417 -5766 E0100; Adobe-Japan1; CID+2929 -5767 E0100; Adobe-Japan1; CID+21328 -5768 E0100; Adobe-Japan1; CID+17422 -5769 E0100; Adobe-Japan1; CID+4481 -576A E0100; Adobe-Japan1; CID+3062 -576A E0101; Adobe-Japan1; CID+13940 -576A E0102; Hanyo-Denshi; JA3658 -576A E0102; Moji_Joho; MJ008967 -576A E0103; Hanyo-Denshi; JTAF52 -576A E0103; Moji_Joho; MJ008966 -576B E0100; Adobe-Japan1; CID+19285 -576D E0100; Adobe-Japan1; CID+19286 -576E E0100; Adobe-Japan1; CID+21329 -576F E0100; Adobe-Japan1; CID+17423 -5770 E0100; Adobe-Japan1; CID+14424 -5771 E0100; Adobe-Japan1; CID+21330 -5773 E0100; Adobe-Japan1; CID+17424 -5774 E0100; Adobe-Japan1; CID+17425 -5774 E0101; Hanyo-Denshi; JB2344 -5774 E0102; Hanyo-Denshi; TK01016570 -5775 E0100; Adobe-Japan1; CID+17426 -5777 E0100; Adobe-Japan1; CID+16814 -5779 E0100; Adobe-Japan1; CID+21331 -577A E0100; Adobe-Japan1; CID+19287 -577A E0101; Hanyo-Denshi; JB2348 -577A E0102; Hanyo-Denshi; TK01016580 -577B E0100; Adobe-Japan1; CID+17427 -577C E0100; Adobe-Japan1; CID+16815 -577D E0100; Hanyo-Denshi; IP577D -577D E0101; Hanyo-Denshi; TK01016590 -577E E0100; Adobe-Japan1; CID+21332 -577F E0100; Adobe-Japan1; CID+4485 -5781 E0100; Adobe-Japan1; CID+21333 -5782 E0100; Adobe-Japan1; CID+2600 -5783 E0100; Adobe-Japan1; CID+19288 -5788 E0100; Adobe-Japan1; CID+4483 -5789 E0100; Adobe-Japan1; CID+4486 -5789 E0101; Hanyo-Denshi; JA5221 -5789 E0101; Moji_Joho; MJ008996 -5789 E0102; Hanyo-Denshi; FT2127 -5789 E0102; Moji_Joho; MJ008997 -578B E0100; Adobe-Japan1; CID+1813 -578B E0101; Hanyo-Denshi; JA2331 -578B E0101; Moji_Joho; MJ008998 -578B E0102; Hanyo-Denshi; KS059680 -578B E0102; Moji_Joho; MJ008999 -578C E0100; Adobe-Japan1; CID+14425 -5793 E0100; Adobe-Japan1; CID+4487 -5793 E0101; Hanyo-Denshi; JA5222 -5793 E0101; Moji_Joho; MJ009007 -5793 E0102; Hanyo-Denshi; KS058090 -5793 E0102; Moji_Joho; MJ009008 -5794 E0100; Adobe-Japan1; CID+21334 -5794 E0101; Hanyo-Denshi; JB2355 -5794 E0101; Moji_Joho; MJ009009 -5794 E0102; Hanyo-Denshi; IB1580 -5794 E0102; Moji_Joho; MJ009010 -5795 E0100; Adobe-Japan1; CID+21338 -5797 E0100; Adobe-Japan1; CID+19289 -5799 E0100; Adobe-Japan1; CID+21335 -579A E0100; Adobe-Japan1; CID+17430 -579C E0100; Adobe-Japan1; CID+14426 -579D E0100; Adobe-Japan1; CID+17431 -579D E0101; Hanyo-Denshi; JB2360 -579D E0101; Moji_Joho; MJ009019 -579D E0102; Hanyo-Denshi; JTAF56 -579D E0102; Moji_Joho; MJ009020 -579E E0100; Adobe-Japan1; CID+17432 -579F E0100; Adobe-Japan1; CID+21336 -57A0 E0100; Adobe-Japan1; CID+4488 -57A1 E0100; Adobe-Japan1; CID+21337 -57A2 E0100; Adobe-Japan1; CID+1974 -57A3 E0100; Adobe-Japan1; CID+1438 -57A4 E0100; Adobe-Japan1; CID+4490 -57A7 E0100; Adobe-Japan1; CID+21339 -57A8 E0100; Adobe-Japan1; CID+17433 -57A9 E0100; Adobe-Japan1; CID+21340 -57AA E0100; Adobe-Japan1; CID+4491 -57AA E0101; Hanyo-Denshi; JA5226 -57AA E0101; Moji_Joho; MJ009033 -57AA E0102; Hanyo-Denshi; KS059730 -57AA E0102; Moji_Joho; MJ057228 -57AC E0100; Adobe-Japan1; CID+8418 -57AE E0100; Adobe-Japan1; CID+19290 -57B0 E0100; Adobe-Japan1; CID+4492 -57B3 E0100; Adobe-Japan1; CID+4489 -57B8 E0100; Adobe-Japan1; CID+14427 -57BD E0100; Adobe-Japan1; CID+21341 -57C0 E0100; Adobe-Japan1; CID+4482 -57C3 E0100; Adobe-Japan1; CID+4493 -57C6 E0100; Adobe-Japan1; CID+4494 -57C7 E0100; Adobe-Japan1; CID+8420 -57C8 E0100; Adobe-Japan1; CID+8419 -57C8 E0101; Hanyo-Denshi; JB2372 -57C8 E0101; Moji_Joho; MJ009056 -57C8 E0102; Hanyo-Denshi; KS058820 -57C8 E0102; Moji_Joho; MJ009055 -57CB E0100; Adobe-Japan1; CID+3730 -57CC E0100; Adobe-Japan1; CID+17436 -57CE E0100; Adobe-Japan1; CID+13841 -57CE E0101; Adobe-Japan1; CID+2515 -57CE E0102; Hanyo-Denshi; JA3075 -57CE E0102; Moji_Joho; MJ009062 -57CE E0103; Hanyo-Denshi; JTAF58 -57CE E0103; Moji_Joho; MJ009063 -57CF E0100; Adobe-Japan1; CID+16817 -57D2 E0100; Adobe-Japan1; CID+4496 -57D2 E0101; Hanyo-Denshi; JA5231 -57D2 E0101; Moji_Joho; MJ009067 -57D2 E0102; Hanyo-Denshi; FT2128 -57D2 E0102; Moji_Joho; MJ009068 -57D3 E0100; Adobe-Japan1; CID+4497 -57D3 E0101; Hanyo-Denshi; JA5232 -57D3 E0101; Moji_Joho; MJ009070 -57D3 E0102; Hanyo-Denshi; JTAF5D -57D3 E0102; Moji_Joho; MJ009069 -57D3 E0103; Hanyo-Denshi; TK01035320 -57D4 E0100; Adobe-Japan1; CID+4495 -57D5 E0100; Adobe-Japan1; CID+19291 -57D5 E0101; Hanyo-Denshi; JB2375 -57D5 E0101; Moji_Joho; MJ009073 -57D5 E0102; Hanyo-Denshi; JTAF59 -57D5 E0102; Moji_Joho; MJ009074 -57D6 E0100; Adobe-Japan1; CID+4499 -57D6 E0101; Adobe-Japan1; CID+20100 -57D6 E0102; Hanyo-Denshi; JA5234 -57D6 E0102; Moji_Joho; MJ009075 -57D6 E0103; Hanyo-Denshi; KS059710 -57D6 E0103; Moji_Joho; MJ057226 -57D7 E0100; Adobe-Japan1; CID+17434 -57DC E0100; Adobe-Japan1; CID+3310 -57DD E0100; Adobe-Japan1; CID+21342 -57DE E0100; Adobe-Japan1; CID+17439 -57DF E0100; Adobe-Japan1; CID+1196 -57E0 E0100; Adobe-Japan1; CID+3528 -57E1 E0100; Adobe-Japan1; CID+21347 -57E2 E0100; Hanyo-Denshi; IP57E2 -57E2 E0101; Hanyo-Denshi; TK01017430 -57E3 E0100; Adobe-Japan1; CID+4500 -57E4 E0100; Adobe-Japan1; CID+16818 -57E5 E0100; Hanyo-Denshi; IP57E5 -57E5 E0101; Hanyo-Denshi; TK01017200 -57E6 E0100; Adobe-Japan1; CID+14428 -57E7 E0100; Adobe-Japan1; CID+19292 -57E7 E0101; Hanyo-Denshi; JB2380 -57E7 E0101; Moji_Joho; MJ009090 -57E7 E0102; Hanyo-Denshi; KS059790 -57E7 E0102; Moji_Joho; MJ009091 -57E9 E0100; Adobe-Japan1; CID+21343 -57EA E0100; Hanyo-Denshi; KS059100 -57EA E0101; Hanyo-Denshi; TK01017000 -57EA E0102; Hanyo-Denshi; TK01017210 -57ED E0100; Adobe-Japan1; CID+14429 -57F0 E0100; Adobe-Japan1; CID+17440 -57F4 E0100; Adobe-Japan1; CID+2533 -57F4 E0101; Adobe-Japan1; CID+13464 -57F4 E0102; Adobe-Japan1; CID+13843 -57F4 E0103; Hanyo-Denshi; JA3093 -57F4 E0103; Moji_Joho; MJ009107 -57F4 E0104; Hanyo-Denshi; KS059220 -57F4 E0104; Moji_Joho; MJ009106 -57F5 E0100; Adobe-Japan1; CID+14430 -57F6 E0100; Adobe-Japan1; CID+14431 -57F6 E0101; Moji_Joho; MJ009109 -57F6 E0102; Moji_Joho; MJ009110 -57F7 E0100; Adobe-Japan1; CID+2277 -57F8 E0100; Adobe-Japan1; CID+17442 -57F8 E0101; Hanyo-Denshi; JB2386 -57F8 E0101; Moji_Joho; MJ009112 -57F8 E0102; Hanyo-Denshi; JTAF62 -57F8 E0102; Moji_Joho; MJ009113 -57F9 E0100; Adobe-Japan1; CID+3347 -57FA E0100; Adobe-Japan1; CID+1580 -57FB E0100; Adobe-Japan1; CID+17443 -57FC E0100; Adobe-Japan1; CID+2139 -57FD E0100; Adobe-Japan1; CID+17444 -57FE E0100; Adobe-Japan1; CID+21344 -57FF E0100; Adobe-Japan1; CID+14432 -5800 E0100; Adobe-Japan1; CID+3719 -5802 E0100; Adobe-Japan1; CID+3210 -5803 E0100; Adobe-Japan1; CID+21345 -5804 E0100; Adobe-Japan1; CID+17445 -5805 E0100; Adobe-Japan1; CID+1870 -5806 E0100; Adobe-Japan1; CID+2863 -5807 E0100; Hanyo-Denshi; IP5807 -5807 E0101; Hanyo-Denshi; TK01016780 -5807 E0102; Hanyo-Denshi; TK01017030 -5808 E0100; Adobe-Japan1; CID+21346 -5809 E0100; Adobe-Japan1; CID+14433 -580A E0100; Adobe-Japan1; CID+4498 -580B E0100; Adobe-Japan1; CID+4501 -580B E0101; Adobe-Japan1; CID+7823 -580B E0102; Hanyo-Denshi; JA5236 -580B E0102; Moji_Joho; MJ009135 -580B E0103; Hanyo-Denshi; FT1950 -580B E0103; Moji_Joho; MJ009134 -580C E0100; Adobe-Japan1; CID+21348 -580D E0100; Adobe-Japan1; CID+19293 -580D E0101; Hanyo-Denshi; JB2402 -580D E0102; Hanyo-Denshi; TK01017050 -5815 E0100; Adobe-Japan1; CID+2852 -5819 E0100; Adobe-Japan1; CID+4502 -5819 E0101; Adobe-Japan1; CID+7986 -5819 E0102; Hanyo-Denshi; JA5237 -5819 E0102; Moji_Joho; MJ009142 -5819 E0103; Hanyo-Denshi; JTAF6C -5819 E0103; Moji_Joho; MJ009143 -581B E0100; Adobe-Japan1; CID+21349 -581D E0100; Adobe-Japan1; CID+4503 -581E E0100; Adobe-Japan1; CID+17446 -581F E0100; Adobe-Japan1; CID+21350 -581F E0101; Hanyo-Denshi; JB2405 -581F E0101; Moji_Joho; MJ009149 -581F E0102; Hanyo-Denshi; JTAF6B -581F E0102; Moji_Joho; MJ009150 -5820 E0100; Adobe-Japan1; CID+14434 -5821 E0100; Adobe-Japan1; CID+4505 -5824 E0100; Adobe-Japan1; CID+3077 -5826 E0100; Adobe-Japan1; CID+19294 -5827 E0100; Adobe-Japan1; CID+17447 -582A E0100; Adobe-Japan1; CID+1514 -582D E0100; Adobe-Japan1; CID+21351 -582F E0100; Adobe-Japan1; CID+7474 -582F E0101; Hanyo-Denshi; JA8401 -582F E0102; Hanyo-Denshi; TK01007030 -5830 E0100; Adobe-Japan1; CID+1283 -5830 E0101; Hanyo-Denshi; JA1765 -5830 E0101; Moji_Joho; MJ009167 -5830 E0102; Hanyo-Denshi; TK01017520 -5830 E0103; Moji_Joho; MJ009168 -5831 E0100; Adobe-Japan1; CID+3651 -5831 E0101; Hanyo-Denshi; JA4283 -5831 E0101; Moji_Joho; MJ009169 -5831 E0102; Hanyo-Denshi; KS061470 -5831 E0102; Moji_Joho; MJ009170 -5832 E0100; Adobe-Japan1; CID+14435 -5832 E0101; Hanyo-Denshi; JB2410 -5832 E0101; Moji_Joho; MJ009171 -5832 E0102; Hanyo-Denshi; JTAF72 -5832 E0102; Moji_Joho; MJ009172 -5834 E0100; Adobe-Japan1; CID+2516 -5834 E0101; Hanyo-Denshi; JA3076 -5834 E0101; Moji_Joho; MJ009174 -5834 E0102; Hanyo-Denshi; JTAF68 -5834 E0102; Moji_Joho; MJ009175 -5835 E0100; Adobe-Japan1; CID+3138 -5835 E0101; Adobe-Japan1; CID+7753 -5835 E0102; Hanyo-Denshi; JA3740 -5835 E0102; Moji_Joho; MJ009176 -5835 E0103; Hanyo-Denshi; FT1873 -5835 E0103; Moji_Joho; MJ009177 -5837 E0100; Hanyo-Denshi; IP5837 -5837 E0100; Moji_Joho; MJ009179 -5837 E0101; Hanyo-Denshi; KS060770 -5837 E0101; Moji_Joho; MJ009180 -5839 E0100; Adobe-Japan1; CID+17448 -583A E0100; Adobe-Japan1; CID+2134 -583D E0100; Adobe-Japan1; CID+4511 -583D E0101; Adobe-Japan1; CID+20101 -583D E0102; Hanyo-Denshi; JA5246 -583D E0102; Moji_Joho; MJ009186 -583D E0103; Hanyo-Denshi; JTAF79 -583D E0103; Moji_Joho; MJ009187 -583F E0100; Adobe-Japan1; CID+21352 -5840 E0100; Adobe-Japan1; CID+3597 -5840 E0101; Adobe-Japan1; CID+13384 -5840 E0102; Hanyo-Denshi; JA4229 -5840 E0103; Hanyo-Denshi; JC1558 -5841 E0100; Adobe-Japan1; CID+4005 -5849 E0100; Adobe-Japan1; CID+17450 -584A E0100; Adobe-Japan1; CID+1396 -584A E0101; Hanyo-Denshi; JA1884 -584A E0101; Moji_Joho; MJ009193 -584A E0102; Hanyo-Denshi; KS060750 -584A E0102; Moji_Joho; MJ057234 -584B E0100; Adobe-Japan1; CID+4507 -584C E0100; Adobe-Japan1; CID+17451 -584C E0101; Hanyo-Denshi; JB2414 -584C E0101; Moji_Joho; MJ009196 -584C E0102; Hanyo-Denshi; KS060860 -584C E0102; Moji_Joho; MJ009195 -584D E0100; Adobe-Japan1; CID+19295 -584D E0101; Hanyo-Denshi; JB2415 -584D E0102; Hanyo-Denshi; TK01017490 -584F E0100; Adobe-Japan1; CID+19296 -5850 E0100; Adobe-Japan1; CID+21353 -5851 E0100; Adobe-Japan1; CID+2748 -5851 E0101; Hanyo-Denshi; JA3326 -5851 E0101; Moji_Joho; MJ009202 -5851 E0102; Hanyo-Denshi; KS060920 -5851 E0102; Moji_Joho; MJ009201 -5852 E0100; Adobe-Japan1; CID+4510 -5854 E0100; Adobe-Japan1; CID+3165 -5854 E0101; Hanyo-Denshi; JA3767 -5854 E0101; Moji_Joho; MJ009205 -5854 E0102; Hanyo-Denshi; KS060960 -5854 E0102; Moji_Joho; MJ009206 -5855 E0100; Adobe-Japan1; CID+21354 -5857 E0100; Adobe-Japan1; CID+3139 -5858 E0100; Adobe-Japan1; CID+3166 -5858 E0101; Adobe-Japan1; CID+7757 -5858 E0102; Hanyo-Denshi; JA3768 -5858 E0102; Moji_Joho; MJ009211 -5858 E0103; Hanyo-Denshi; FT1877S -5858 E0103; Moji_Joho; MJ009210 -5859 E0100; Adobe-Japan1; CID+3405 -5859 E0101; Adobe-Japan1; CID+20102 -5859 E0102; Hanyo-Denshi; JA4025 -5859 E0102; Moji_Joho; MJ009212 -5859 E0103; Hanyo-Denshi; JTAF7F -5859 E0103; Moji_Joho; MJ009214 -5859 E0104; Hanyo-Denshi; JTAF7E -5859 E0104; Moji_Joho; MJ009213 -585A E0100; Adobe-Japan1; CID+3049 -585A E0101; Adobe-Japan1; CID+7746 -585A E0102; Adobe-Japan1; CID+8422 -585A E0103; Hanyo-Denshi; JA3645 -585A E0103; Moji_Joho; MJ009215 -585A E0104; Hanyo-Denshi; FT2045 -585A E0104; Moji_Joho; MJ009216 -585A E0105; Hanyo-Denshi; JC1555 -585A E0105; Moji_Joho; MJ030194 -585A E0106; Hanyo-Denshi; IB1603 -585A E0106; Moji_Joho; MJ030195 -585E E0100; Adobe-Japan1; CID+2105 -585F E0100; Adobe-Japan1; CID+19297 -585F E0101; Hanyo-Denshi; JB2419 -585F E0101; Moji_Joho; MJ009221 -585F E0102; Hanyo-Denshi; KS061140 -585F E0102; Moji_Joho; MJ009222 -5861 E0100; Adobe-Japan1; CID+7751 -5862 E0100; Adobe-Japan1; CID+4506 -5863 E0100; Hanyo-Denshi; IP5863 -5863 E0101; Hanyo-Denshi; TK01017570 -5864 E0100; Adobe-Japan1; CID+16819 -5867 E0100; Adobe-Japan1; CID+17452 -5867 E0101; Hanyo-Denshi; JB2422 -5867 E0102; Hanyo-Denshi; TK01017580 -5868 E0100; Adobe-Japan1; CID+21355 -5869 E0100; Adobe-Japan1; CID+1304 -5869 E0101; Hanyo-Denshi; JA1786 -5869 E0102; Hanyo-Denshi; TK01017420 -586B E0100; Adobe-Japan1; CID+3120 -586D E0100; Adobe-Japan1; CID+19298 -5870 E0100; Adobe-Japan1; CID+4508 -5870 E0101; Hanyo-Denshi; JA5243 -5870 E0101; Moji_Joho; MJ009236 -5870 E0102; Hanyo-Denshi; FT2129 -5870 E0102; Moji_Joho; MJ009237 -5870 E0103; Moji_Joho; MJ057249 -5872 E0100; Adobe-Japan1; CID+4504 -5874 E0100; Hanyo-Denshi; IP5874 -5874 E0101; Hanyo-Denshi; TK01017790 -5875 E0100; Adobe-Japan1; CID+2582 -5878 E0100; Adobe-Japan1; CID+21356 -5879 E0100; Adobe-Japan1; CID+4512 -587C E0100; Adobe-Japan1; CID+14436 -587C E0101; Hanyo-Denshi; JB2425 -587C E0102; Hanyo-Denshi; TK01017330 -587C E0103; Hanyo-Denshi; TK01017690 -587D E0100; Hanyo-Denshi; IP587D -587D E0101; Hanyo-Denshi; TK01017680 -587E E0100; Adobe-Japan1; CID+2392 -587F E0100; Adobe-Japan1; CID+19299 -5880 E0100; Adobe-Japan1; CID+14437 -5880 E0101; Hanyo-Denshi; JB2427 -5880 E0101; Moji_Joho; MJ009255 -5880 E0102; Hanyo-Denshi; KS062280 -5880 E0102; Moji_Joho; MJ009254 -5881 E0100; Adobe-Japan1; CID+19300 -5881 E0101; Hanyo-Denshi; JB2428 -5881 E0101; Moji_Joho; MJ009256 -5881 E0102; Hanyo-Denshi; IB1608 -5881 E0102; Moji_Joho; MJ009257 -5883 E0100; Adobe-Japan1; CID+1701 -5883 E0101; Hanyo-Denshi; JA2213 -5883 E0101; Moji_Joho; MJ009259 -5883 E0102; Hanyo-Denshi; JTAF7D -5883 E0102; Moji_Joho; MJ009260 -5885 E0100; Adobe-Japan1; CID+4513 -5887 E0100; Adobe-Japan1; CID+21357 -5888 E0100; Adobe-Japan1; CID+21358 -5889 E0100; Adobe-Japan1; CID+16820 -588A E0100; Adobe-Japan1; CID+17453 -588B E0100; Adobe-Japan1; CID+17454 -588C E0100; Adobe-Japan1; CID+21359 -588D E0100; Adobe-Japan1; CID+17455 -588D E0101; Hanyo-Denshi; JB2434 -588D E0101; Moji_Joho; MJ009271 -588D E0102; Hanyo-Denshi; KS061980 -588D E0102; Moji_Joho; MJ009270 -588D E0103; Hanyo-Denshi; JTAF7BS -588D E0103; Moji_Joho; MJ009272 -588F E0100; Adobe-Japan1; CID+17456 -5890 E0100; Adobe-Japan1; CID+17457 -5890 E0101; Hanyo-Denshi; JB2436 -5890 E0102; Hanyo-Denshi; TK01017740 -5893 E0100; Adobe-Japan1; CID+3640 -5893 E0101; Hanyo-Denshi; JA4272 -5893 E0101; Moji_Joho; MJ009279 -5893 E0102; Hanyo-Denshi; KS062060 -5893 E0102; Moji_Joho; MJ009280 -5894 E0100; Adobe-Japan1; CID+17458 -5896 E0100; Adobe-Japan1; CID+21360 -5897 E0100; Adobe-Japan1; CID+2815 -5898 E0100; Adobe-Japan1; CID+19301 -589C E0100; Adobe-Japan1; CID+3042 -589C E0101; Adobe-Japan1; CID+13937 -589C E0102; Hanyo-Denshi; JA3638 -589C E0102; Moji_Joho; MJ009286 -589C E0103; Hanyo-Denshi; FT2044 -589C E0103; Moji_Joho; MJ009287 -589C E0104; Hanyo-Denshi; JTAF87 -589C E0104; Moji_Joho; MJ009285 -589D E0100; Adobe-Japan1; CID+17459 -589E E0100; Adobe-Japan1; CID+8423 -589E E0101; Hanyo-Denshi; JC1561 -589E E0101; Moji_Joho; MJ009289 -589E E0102; Hanyo-Denshi; JTAF8A -589E E0102; Moji_Joho; MJ009290 -589F E0100; Adobe-Japan1; CID+4515 -589F E0101; Hanyo-Denshi; JA5250 -589F E0101; Moji_Joho; MJ009291 -589F E0102; Hanyo-Denshi; FT2130 -589F E0102; Moji_Joho; MJ009292 -58A0 E0100; Adobe-Japan1; CID+21361 -58A1 E0100; Adobe-Japan1; CID+21362 -58A2 E0100; Adobe-Japan1; CID+21363 -58A6 E0100; Adobe-Japan1; CID+21364 -58A8 E0100; Adobe-Japan1; CID+13387 -58A8 E0101; Adobe-Japan1; CID+3709 -58A8 E0102; Hanyo-Denshi; JA4347 -58A8 E0103; Hanyo-Denshi; JC1562 -58A9 E0100; Adobe-Japan1; CID+14438 -58AA E0100; Adobe-Japan1; CID+17460 -58AB E0100; Adobe-Japan1; CID+4516 -58AB E0101; Adobe-Japan1; CID+13529 -58AB E0102; Hanyo-Denshi; JA5251 -58AB E0102; Moji_Joho; MJ009304 -58AB E0103; Hanyo-Denshi; FT2131 -58AB E0103; Moji_Joho; MJ009305 -58AB E0104; Hanyo-Denshi; JTAF8F -58AB E0104; Moji_Joho; MJ009306 -58AE E0100; Adobe-Japan1; CID+4521 -58B1 E0100; Adobe-Japan1; CID+17461 -58B2 E0100; Adobe-Japan1; CID+8424 -58B3 E0100; Adobe-Japan1; CID+3583 -58B3 E0101; Hanyo-Denshi; JA4215 -58B3 E0101; Moji_Joho; MJ009315 -58B3 E0102; Hanyo-Denshi; KS063440 -58B3 E0102; Moji_Joho; MJ057244 -58B8 E0100; Adobe-Japan1; CID+4520 -58B8 E0101; Hanyo-Denshi; JA5255 -58B8 E0101; Moji_Joho; MJ009319 -58B8 E0102; Hanyo-Denshi; FT2133 -58B8 E0102; Moji_Joho; MJ009320 -58B8 E0103; Hanyo-Denshi; KS063460 -58B8 E0103; Moji_Joho; MJ057245 -58B9 E0100; Adobe-Japan1; CID+4514 -58BA E0100; Adobe-Japan1; CID+4517 -58BA E0101; Hanyo-Denshi; JA5252 -58BA E0101; Moji_Joho; MJ009322 -58BA E0102; Hanyo-Denshi; FT2132 -58BA E0102; Moji_Joho; MJ009323 -58BB E0100; Adobe-Japan1; CID+4519 -58BC E0100; Adobe-Japan1; CID+19302 -58BE E0100; Adobe-Japan1; CID+2070 -58C1 E0100; Adobe-Japan1; CID+3609 -58C2 E0100; Adobe-Japan1; CID+21366 -58C3 E0100; Adobe-Japan1; CID+17463 -58C4 E0100; Adobe-Japan1; CID+21365 -58C4 E0101; Hanyo-Denshi; JB2447 -58C4 E0101; Moji_Joho; MJ009333 -58C4 E0102; Hanyo-Denshi; KS063000 -58C4 E0102; Moji_Joho; MJ009334 -58C5 E0100; Adobe-Japan1; CID+4522 -58C7 E0100; Adobe-Japan1; CID+2947 -58C7 E0101; Hanyo-Denshi; JA3537 -58C7 E0101; Moji_Joho; MJ009337 -58C7 E0102; Hanyo-Denshi; JTAF92 -58C7 E0102; Moji_Joho; MJ009338 -58C8 E0100; Adobe-Japan1; CID+21367 -58CA E0100; Adobe-Japan1; CID+1397 -58CA E0101; Hanyo-Denshi; JA1885 -58CA E0102; Hanyo-Denshi; TK01018010 -58CC E0100; Adobe-Japan1; CID+2517 -58CD E0100; Adobe-Japan1; CID+17464 -58CE E0100; Adobe-Japan1; CID+14439 -58CE E0101; Hanyo-Denshi; JB2452 -58CE E0101; Moji_Joho; MJ009344 -58CE E0102; Hanyo-Denshi; JTAF94 -58CE E0102; Moji_Joho; MJ009345 -58D0 E0100; Adobe-Japan1; CID+14440 -58D0 E0101; Hanyo-Denshi; JB2453 -58D0 E0101; Moji_Joho; MJ009347 -58D0 E0102; Hanyo-Denshi; JTAF9A -58D0 E0102; Moji_Joho; MJ009348 -58D1 E0100; Adobe-Japan1; CID+4524 -58D2 E0100; Adobe-Japan1; CID+16822 -58D2 E0101; Hanyo-Denshi; JB2454 -58D2 E0101; Moji_Joho; MJ009350 -58D2 E0102; Hanyo-Denshi; KS063600 -58D2 E0102; Moji_Joho; MJ009351 -58D3 E0100; Adobe-Japan1; CID+4523 -58D3 E0101; Hanyo-Denshi; JA5258 -58D3 E0101; Moji_Joho; MJ009352 -58D3 E0102; Hanyo-Denshi; FT2875 -58D3 E0102; Moji_Joho; MJ009353 -58D3 E0103; Hanyo-Denshi; JTAF9FS -58D3 E0103; Moji_Joho; MJ059460 -58D4 E0100; Adobe-Japan1; CID+14441 -58D5 E0100; Adobe-Japan1; CID+2042 -58D5 E0101; Hanyo-Denshi; JA2572 -58D5 E0101; Moji_Joho; MJ009355 -58D5 E0102; Hanyo-Denshi; FT2029 -58D5 E0102; Moji_Joho; MJ009356 -58D6 E0100; Adobe-Japan1; CID+21368 -58D7 E0100; Adobe-Japan1; CID+4525 -58D8 E0100; Adobe-Japan1; CID+4527 -58D9 E0100; Adobe-Japan1; CID+4526 -58D9 E0101; Hanyo-Denshi; JA5261 -58D9 E0101; Moji_Joho; MJ009360 -58D9 E0102; Hanyo-Denshi; FT2134 -58D9 E0102; Moji_Joho; MJ009361 -58DA E0100; Adobe-Japan1; CID+14442 -58DC E0100; Adobe-Japan1; CID+4529 -58DD E0100; Adobe-Japan1; CID+21369 -58DD E0101; Hanyo-Denshi; JB2458 -58DD E0101; Moji_Joho; MJ009366 -58DD E0102; Hanyo-Denshi; IB0651 -58DD E0102; Moji_Joho; MJ009365 -58DE E0100; Adobe-Japan1; CID+4518 -58DF E0100; Adobe-Japan1; CID+4531 -58DF E0101; Hanyo-Denshi; JA5266 -58DF E0101; Moji_Joho; MJ009368 -58DF E0102; Hanyo-Denshi; KS064190 -58DF E0102; Moji_Joho; MJ009369 -58E0 E0100; Adobe-Japan1; CID+16823 -58E0 E0101; Hanyo-Denshi; JC1569 -58E0 E0101; Moji_Joho; MJ009370 -58E0 E0102; Hanyo-Denshi; KS064180 -58E0 E0102; Moji_Joho; MJ009371 -58E1 E0100; Adobe-Japan1; CID+21370 -58E1 E0101; Moji_Joho; MJ009372 -58E1 E0102; Moji_Joho; MJ009373 -58E2 E0100; Adobe-Japan1; CID+17465 -58E4 E0100; Adobe-Japan1; CID+4530 -58E5 E0100; Adobe-Japan1; CID+4528 -58E5 E0101; Hanyo-Denshi; JA5263 -58E5 E0101; Moji_Joho; MJ009377 -58E5 E0102; Hanyo-Denshi; FT2135 -58E5 E0102; Moji_Joho; MJ009378 -58E9 E0100; Adobe-Japan1; CID+14443 -58EB E0100; Adobe-Japan1; CID+2204 -58EC E0100; Adobe-Japan1; CID+2583 -58EE E0100; Adobe-Japan1; CID+2774 -58EF E0100; Adobe-Japan1; CID+4532 -58F0 E0100; Adobe-Japan1; CID+2656 -58F1 E0100; Adobe-Japan1; CID+1201 -58F2 E0100; Adobe-Japan1; CID+3354 -58F3 E0100; Adobe-Japan1; CID+17466 -58F3 E0101; Hanyo-Denshi; JB2462 -58F3 E0101; Moji_Joho; MJ009391 -58F3 E0102; Hanyo-Denshi; IB1449 -58F3 E0102; Moji_Joho; MJ009390 -58F4 E0100; Adobe-Japan1; CID+17467 -58F4 E0101; Hanyo-Denshi; JD0523 -58F4 E0101; Moji_Joho; MJ009393 -58F4 E0102; Hanyo-Denshi; KS058120 -58F4 E0102; Moji_Joho; MJ009392 -58F7 E0100; Adobe-Japan1; CID+3063 -58F7 E0101; Hanyo-Denshi; JA3659 -58F7 E0101; Moji_Joho; MJ009395 -58F7 E0102; Hanyo-Denshi; JTAFA5 -58F7 E0102; Moji_Joho; MJ059463 -58F9 E0100; Adobe-Japan1; CID+4534 -58FA E0100; Adobe-Japan1; CID+4533 -58FA E0101; Hanyo-Denshi; JA5268 -58FA E0102; Hanyo-Denshi; TK01018340 -58FB E0100; Adobe-Japan1; CID+4535 -58FC E0100; Adobe-Japan1; CID+4536 -58FD E0100; Adobe-Japan1; CID+4537 -58FD E0101; Hanyo-Denshi; JA5272 -58FD E0101; Moji_Joho; MJ009401 -58FD E0102; Hanyo-Denshi; JTAFA6 -58FD E0102; Moji_Joho; MJ057250 -58FD E0103; Hanyo-Denshi; TK01026500 -5900 E0100; Hanyo-Denshi; KS084760 -5900 E0100; Moji_Joho; MJ057355 -5900 E0101; Hanyo-Denshi; KS084770 -5900 E0101; Moji_Joho; MJ057356 -5900 E0102; Hanyo-Denshi; KS084800 -5900 E0102; Moji_Joho; MJ009404 -5900 E0103; Moji_Joho; MJ057358 -5902 E0100; Adobe-Japan1; CID+4538 -5903 E0100; Hanyo-Denshi; IP5903 -5903 E0101; Hanyo-Denshi; TK01000550 -5905 E0100; Adobe-Japan1; CID+17468 -5905 E0101; Hanyo-Denshi; JB2463 -5905 E0101; Moji_Joho; MJ009409 -5905 E0102; Hanyo-Denshi; IB1617S -5905 E0102; Moji_Joho; MJ009408 -5906 E0100; Adobe-Japan1; CID+17469 -5906 E0101; Adobe-Japan1; CID+21371 -5906 E0102; Hanyo-Denshi; JB2464 -5906 E0103; Hanyo-Denshi; TK01018410 -5909 E0100; Adobe-Japan1; CID+3617 -590A E0100; Adobe-Japan1; CID+4539 -590A E0101; Moji_Joho; MJ009413 -590A E0102; Moji_Joho; MJ009414 -590B E0100; Adobe-Japan1; CID+8425 -590C E0100; Adobe-Japan1; CID+14444 -590D E0100; Adobe-Japan1; CID+17470 -590F E0100; Adobe-Japan1; CID+1350 -590F E0101; Hanyo-Denshi; JA1838 -590F E0101; Moji_Joho; MJ009420 -590F E0102; Hanyo-Denshi; KS065510 -590F E0102; Moji_Joho; MJ009419 -590F E0103; Moji_Joho; MJ057256 -5910 E0100; Adobe-Japan1; CID+4540 -5910 E0101; Hanyo-Denshi; JA5275 -5910 E0102; Hanyo-Denshi; KS149900 -5910 E0103; Hanyo-Denshi; TK01018610 -5912 E0100; Adobe-Japan1; CID+21372 -5912 E0101; Hanyo-Denshi; JB2467 -5912 E0101; Moji_Joho; MJ009424 -5912 E0102; Hanyo-Denshi; KS065780 -5912 E0102; Moji_Joho; MJ009423 -5913 E0100; Adobe-Japan1; CID+21373 -5913 E0101; Hanyo-Denshi; JB2468 -5913 E0101; Moji_Joho; MJ009426 -5913 E0102; Hanyo-Denshi; KS065810 -5913 E0102; Moji_Joho; MJ009425 -5914 E0100; Adobe-Japan1; CID+17471 -5914 E0101; Hanyo-Denshi; JB2469 -5914 E0101; Moji_Joho; MJ009429 -5914 E0102; Hanyo-Denshi; KS065840 -5914 E0102; Moji_Joho; MJ009427 -5914 E0103; Hanyo-Denshi; KS065850 -5914 E0103; Moji_Joho; MJ009428 -5915 E0100; Adobe-Japan1; CID+3878 -5916 E0100; Adobe-Japan1; CID+1422 -5916 E0101; Hanyo-Denshi; JA1916 -5916 E0101; Moji_Joho; MJ009431 -5916 E0102; Hanyo-Denshi; FT2021 -5916 E0102; Moji_Joho; MJ009432 -5917 E0100; Hanyo-Denshi; IP5917 -5917 E0100; Moji_Joho; MJ009433 -5917 E0101; Hanyo-Denshi; KS066070 -5917 E0101; Moji_Joho; MJ009434 -5918 E0100; Adobe-Japan1; CID+4318 -5919 E0100; Adobe-Japan1; CID+2386 -591A E0100; Adobe-Japan1; CID+2847 -591B E0100; Adobe-Japan1; CID+4541 -591B E0101; Adobe-Japan1; CID+7987 -591B E0102; Hanyo-Denshi; JA5276 -591B E0102; Moji_Joho; MJ009438 -591B E0103; Hanyo-Denshi; JTAFB7 -591B E0103; Moji_Joho; MJ009439 -591B E0104; Hanyo-Denshi; TK01018730 -591C E0100; Adobe-Japan1; CID+3831 -591D E0100; Adobe-Japan1; CID+21374 -591F E0100; Adobe-Japan1; CID+19303 -5921 E0100; Adobe-Japan1; CID+21375 -5922 E0100; Adobe-Japan1; CID+3776 -5922 E0101; Hanyo-Denshi; JA4420 -5922 E0101; Moji_Joho; MJ009446 -5922 E0102; Hanyo-Denshi; KS066550 -5922 E0102; Moji_Joho; MJ009447 -5922 E0103; Hanyo-Denshi; KS066540 -5922 E0103; Moji_Joho; MJ057269 -5923 E0100; Adobe-Japan1; CID+19304 -5924 E0100; Adobe-Japan1; CID+14445 -5925 E0100; Adobe-Japan1; CID+4543 -5927 E0100; Adobe-Japan1; CID+2887 -5927 E0101; Adobe-Japan1; CID+13909 -5928 E0100; Adobe-Japan1; CID+21376 -5929 E0100; Adobe-Japan1; CID+3121 -592A E0100; Adobe-Japan1; CID+2848 -592B E0100; Adobe-Japan1; CID+3529 -592C E0100; Adobe-Japan1; CID+4544 -592D E0100; Adobe-Japan1; CID+4545 -592E E0100; Adobe-Japan1; CID+1309 -592F E0100; Adobe-Japan1; CID+14446 -5930 E0100; Adobe-Japan1; CID+21377 -5931 E0100; Adobe-Japan1; CID+2278 -5932 E0100; Adobe-Japan1; CID+4546 -5933 E0100; Adobe-Japan1; CID+21378 -5935 E0100; Adobe-Japan1; CID+21379 -5936 E0100; Adobe-Japan1; CID+21380 -5937 E0100; Adobe-Japan1; CID+1172 -5937 E0101; Hanyo-Denshi; JA1648 -5937 E0102; Hanyo-Denshi; KS067340 -5938 E0100; Adobe-Japan1; CID+4547 -5938 E0101; Hanyo-Denshi; JA5282 -5938 E0101; Moji_Joho; MJ009468 -5938 E0102; Hanyo-Denshi; KS067180 -5938 E0102; Moji_Joho; MJ009469 -5939 E0100; Adobe-Japan1; CID+14117 -593D E0100; Adobe-Japan1; CID+17474 -593E E0100; Adobe-Japan1; CID+4548 -593F E0100; Adobe-Japan1; CID+21381 -5943 E0100; Adobe-Japan1; CID+21382 -5944 E0100; Adobe-Japan1; CID+1284 -5944 E0101; Hanyo-Denshi; JA1766 -5944 E0102; Hanyo-Denshi; TK01019140 -5946 E0100; Adobe-Japan1; CID+17476 -5946 E0101; Hanyo-Denshi; JB2483 -5946 E0101; Moji_Joho; MJ009479 -5946 E0102; Hanyo-Denshi; IB1622 -5946 E0102; Moji_Joho; MJ009480 -5947 E0100; Adobe-Japan1; CID+1581 -5948 E0100; Adobe-Japan1; CID+3256 -5949 E0100; Adobe-Japan1; CID+3652 -594E E0100; Adobe-Japan1; CID+4552 -594F E0100; Adobe-Japan1; CID+2775 -594F E0101; Adobe-Japan1; CID+20103 -5950 E0100; Adobe-Japan1; CID+4551 -5951 E0100; Adobe-Japan1; CID+1814 -5951 E0101; Adobe-Japan1; CID+13739 -5951 E0102; Adobe-Japan1; CID+20104 -5951 E0103; Hanyo-Denshi; JA2332 -5951 E0103; Moji_Joho; MJ009491 -5951 E0104; Hanyo-Denshi; KS067790 -5951 E0104; Moji_Joho; MJ009490 -5951 E0105; Hanyo-Denshi; JTAFC4 -5951 E0105; Moji_Joho; MJ009493 -5951 E0106; Hanyo-Denshi; KS067880S -5951 E0106; Moji_Joho; MJ009492 -5952 E0100; Adobe-Japan1; CID+21383 -5953 E0100; Adobe-Japan1; CID+8426 -5953 E0101; Adobe-Japan1; CID+14289 -5953 E0102; Hanyo-Denshi; JB2485 -5953 E0102; Moji_Joho; MJ009496 -5953 E0103; Hanyo-Denshi; JTAFC5 -5953 E0103; Moji_Joho; MJ009495 -5954 E0100; Adobe-Japan1; CID+3721 -5954 E0101; Hanyo-Denshi; JA4359 -5954 E0101; Moji_Joho; MJ009497 -5954 E0102; Hanyo-Denshi; KS067820 -5954 E0102; Moji_Joho; MJ009498 -5955 E0100; Adobe-Japan1; CID+4550 -5956 E0100; Hanyo-Denshi; TK01019400 -5956 E0101; Hanyo-Denshi; TK01019430 -5956 E0102; Hanyo-Denshi; TK01019440 -5957 E0100; Adobe-Japan1; CID+3167 -5958 E0100; Adobe-Japan1; CID+4554 -5958 E0101; Hanyo-Denshi; JA5289 -5958 E0101; Moji_Joho; MJ009502 -5958 E0102; Hanyo-Denshi; FT2137 -5958 E0102; Moji_Joho; MJ009503 -5958 E0103; Hanyo-Denshi; TK01019270 -5959 E0100; Adobe-Japan1; CID+19305 -595A E0100; Adobe-Japan1; CID+4553 -595B E0100; Adobe-Japan1; CID+8427 -595D E0100; Adobe-Japan1; CID+8428 -595D E0101; Hanyo-Denshi; JB2488 -595D E0102; Hanyo-Denshi; TK01019590 -595E E0100; Adobe-Japan1; CID+21384 -595F E0100; Adobe-Japan1; CID+17479 -595F E0101; Hanyo-Denshi; JB2490 -595F E0101; Moji_Joho; MJ009512 -595F E0102; Hanyo-Denshi; IB1629 -595F E0102; Moji_Joho; MJ009513 -5960 E0100; Adobe-Japan1; CID+4556 -5960 E0101; Adobe-Japan1; CID+20105 -5960 E0102; Hanyo-Denshi; JA5291 -5960 E0102; Moji_Joho; MJ009514 -5960 E0103; Hanyo-Denshi; FT2139 -5960 E0103; Moji_Joho; MJ009516 -5960 E0104; Hanyo-Denshi; JTAFD0 -5960 E0104; Moji_Joho; MJ009517 -5960 E0105; Hanyo-Denshi; KS068610 -5960 E0105; Moji_Joho; MJ009515 -5960 E0106; Hanyo-Denshi; TK01019610 -5961 E0100; Adobe-Japan1; CID+14447 -5962 E0100; Adobe-Japan1; CID+4555 -5962 E0101; Adobe-Japan1; CID+20106 -5962 E0102; Hanyo-Denshi; JA5290 -5962 E0102; Moji_Joho; MJ009519 -5962 E0103; Hanyo-Denshi; FT2138 -5962 E0103; Moji_Joho; MJ009520 -5963 E0100; Adobe-Japan1; CID+8429 -5963 E0101; Hanyo-Denshi; JB2492 -5963 E0101; Moji_Joho; MJ009521 -5963 E0102; Hanyo-Denshi; JTAFCD -5963 E0102; Moji_Joho; MJ009522 -5965 E0100; Adobe-Japan1; CID+1310 -5965 E0101; Hanyo-Denshi; JA1792 -5965 E0101; Moji_Joho; MJ009524 -5965 E0102; Hanyo-Denshi; IB0654 -5965 E0102; Moji_Joho; MJ009525 -5967 E0100; Adobe-Japan1; CID+4557 -5968 E0100; Adobe-Japan1; CID+2449 -5969 E0100; Adobe-Japan1; CID+4559 -5969 E0101; Hanyo-Denshi; JA5294 -5969 E0101; Moji_Joho; MJ009530 -5969 E0102; Hanyo-Denshi; FT2140 -5969 E0102; Moji_Joho; MJ009531 -596A E0100; Adobe-Japan1; CID+2915 -596B E0100; Adobe-Japan1; CID+21385 -596C E0100; Adobe-Japan1; CID+4558 -596C E0101; Hanyo-Denshi; JA5293 -596C E0102; Hanyo-Denshi; TK01019640 -596C E0103; Hanyo-Denshi; TK01019760 -596D E0100; Adobe-Japan1; CID+14448 -596E E0100; Adobe-Japan1; CID+3587 -596F E0100; Adobe-Japan1; CID+21386 -5970 E0100; Hanyo-Denshi; IP5970 -5970 E0100; Moji_Joho; MJ009539 -5970 E0101; Hanyo-Denshi; JTAFD9 -5970 E0101; Moji_Joho; MJ059485 -5972 E0100; Adobe-Japan1; CID+21387 -5972 E0101; Hanyo-Denshi; JB2502 -5972 E0101; Moji_Joho; MJ009541 -5972 E0102; Hanyo-Denshi; JTAFDA -5972 E0102; Moji_Joho; MJ009542 -5973 E0100; Adobe-Japan1; CID+2433 -5973 E0101; Adobe-Japan1; CID+13828 -5974 E0100; Adobe-Japan1; CID+3157 -5975 E0100; Adobe-Japan1; CID+17481 -5976 E0100; Adobe-Japan1; CID+17482 -5978 E0100; Adobe-Japan1; CID+4560 -5979 E0100; Adobe-Japan1; CID+19306 -597B E0100; Adobe-Japan1; CID+21388 -597C E0100; Adobe-Japan1; CID+17483 -597D E0100; Adobe-Japan1; CID+1975 -5981 E0100; Adobe-Japan1; CID+4561 -5981 E0101; Hanyo-Denshi; JA5302 -5981 E0101; Moji_Joho; MJ009558 -5981 E0102; Hanyo-Denshi; JTAFDD -5981 E0102; Moji_Joho; MJ009557 -5982 E0100; Adobe-Japan1; CID+3287 -5983 E0100; Adobe-Japan1; CID+3442 -5983 E0101; Hanyo-Denshi; JA4062 -5983 E0101; Moji_Joho; MJ009560 -5983 E0102; Hanyo-Denshi; JTAFDC -5983 E0102; Moji_Joho; MJ009561 -5984 E0100; Adobe-Japan1; CID+3805 -5984 E0101; Adobe-Japan1; CID+14055 -5984 E0102; Hanyo-Denshi; JA4449 -5984 E0102; Moji_Joho; MJ009564 -5984 E0103; Hanyo-Denshi; JTAFDE -5984 E0103; Moji_Joho; MJ009563 -598A E0100; Adobe-Japan1; CID+3291 -598B E0100; Adobe-Japan1; CID+16825 -598C E0100; Adobe-Japan1; CID+21389 -598D E0100; Adobe-Japan1; CID+4570 -598E E0100; Adobe-Japan1; CID+21390 -5992 E0100; Adobe-Japan1; CID+16826 -5993 E0100; Adobe-Japan1; CID+1618 -5995 E0100; Adobe-Japan1; CID+21391 -5996 E0100; Adobe-Japan1; CID+3887 -5997 E0100; Adobe-Japan1; CID+19307 -5999 E0100; Adobe-Japan1; CID+3771 -599B E0100; Adobe-Japan1; CID+4665 -599B E0101; Hanyo-Denshi; JA5412 -599B E0101; Moji_Joho; MJ009587 -599B E0102; Hanyo-Denshi; JTB063 -599B E0102; Moji_Joho; MJ009586 -599D E0100; Adobe-Japan1; CID+4562 -599F E0100; Adobe-Japan1; CID+17484 -59A0 E0100; Hanyo-Denshi; IP59A0 -59A0 E0100; Moji_Joho; MJ009592 -59A0 E0101; Hanyo-Denshi; JT59A0 -59A0 E0101; Moji_Joho; MJ009593 -59A3 E0100; Adobe-Japan1; CID+4565 -59A4 E0100; Adobe-Japan1; CID+8430 -59A5 E0100; Adobe-Japan1; CID+2853 -59A5 E0101; Adobe-Japan1; CID+13903 -59A5 E0102; Hanyo-Denshi; JA3437 -59A5 E0102; Moji_Joho; MJ009599 -59A5 E0103; Hanyo-Denshi; JTAFDF -59A5 E0103; Moji_Joho; MJ009598 -59A7 E0100; Adobe-Japan1; CID+21392 -59A8 E0100; Adobe-Japan1; CID+3686 -59AC E0100; Adobe-Japan1; CID+3140 -59AD E0100; Adobe-Japan1; CID+21393 -59AE E0100; Adobe-Japan1; CID+17485 -59AF E0100; Adobe-Japan1; CID+19308 -59B0 E0100; Adobe-Japan1; CID+21394 -59B2 E0100; Adobe-Japan1; CID+4566 -59B3 E0100; Adobe-Japan1; CID+19309 -59B7 E0100; Adobe-Japan1; CID+21395 -59B9 E0100; Adobe-Japan1; CID+3731 -59BA E0100; Adobe-Japan1; CID+8431 -59BB E0100; Adobe-Japan1; CID+2106 -59BB E0101; Hanyo-Denshi; JA2642 -59BB E0102; Hanyo-Denshi; TK01020200 -59BC E0100; Adobe-Japan1; CID+17486 -59BE E0100; Adobe-Japan1; CID+2450 -59C1 E0100; Adobe-Japan1; CID+21396 -59C3 E0100; Adobe-Japan1; CID+16827 -59C4 E0100; Adobe-Japan1; CID+21397 -59C6 E0100; Adobe-Japan1; CID+4567 -59C8 E0100; Adobe-Japan1; CID+17487 -59C9 E0100; Adobe-Japan1; CID+2206 -59C9 E0101; Adobe-Japan1; CID+13452 -59CA E0100; Adobe-Japan1; CID+14449 -59CB E0100; Adobe-Japan1; CID+2205 -59CD E0100; Adobe-Japan1; CID+17488 -59CD E0101; Hanyo-Denshi; JB2530 -59CD E0101; Moji_Joho; MJ009636 -59CD E0102; Hanyo-Denshi; JTAFE2 -59CD E0102; Moji_Joho; MJ009637 -59D0 E0100; Adobe-Japan1; CID+1149 -59D1 E0100; Adobe-Japan1; CID+1916 -59D2 E0100; Adobe-Japan1; CID+14450 -59D3 E0100; Adobe-Japan1; CID+2639 -59D4 E0100; Adobe-Japan1; CID+1173 -59D8 E0100; Hanyo-Denshi; IP59D8 -59D8 E0100; Moji_Joho; MJ009647 -59D8 E0101; Hanyo-Denshi; KS072760 -59D8 E0101; Moji_Joho; MJ009648 -59D9 E0100; Adobe-Japan1; CID+4571 -59DA E0100; Adobe-Japan1; CID+4572 -59DA E0101; Adobe-Japan1; CID+13530 -59DA E0102; Moji_Joho; MJ009650 -59DA E0103; Moji_Joho; MJ009651 -59DC E0100; Adobe-Japan1; CID+4569 -59DD E0100; Adobe-Japan1; CID+14451 -59DE E0100; Adobe-Japan1; CID+17489 -59DF E0100; Adobe-Japan1; CID+19310 -59E3 E0100; Adobe-Japan1; CID+14452 -59E3 E0101; Moji_Joho; MJ009660 -59E3 E0102; Moji_Joho; MJ009661 -59E4 E0100; Adobe-Japan1; CID+14453 -59E5 E0100; Adobe-Japan1; CID+1242 -59E6 E0100; Adobe-Japan1; CID+1515 -59E7 E0100; Adobe-Japan1; CID+17490 -59E8 E0100; Adobe-Japan1; CID+4568 -59EA E0100; Adobe-Japan1; CID+3793 -59EB E0100; Adobe-Japan1; CID+3491 -59EC E0100; Adobe-Japan1; CID+13997 -59EC E0101; Adobe-Japan1; CID+13998 -59EC E0102; Hanyo-Denshi; IP59EC -59EC E0102; Moji_Joho; MJ009670 -59EC E0103; Hanyo-Denshi; JTAFE9 -59EC E0103; Moji_Joho; MJ009671 -59EE E0100; Adobe-Japan1; CID+17491 -59EF E0100; Adobe-Japan1; CID+21398 -59F1 E0100; Adobe-Japan1; CID+19311 -59F2 E0100; Adobe-Japan1; CID+21399 -59F4 E0100; Adobe-Japan1; CID+21400 -59F6 E0100; Adobe-Japan1; CID+1132 -59F7 E0100; Adobe-Japan1; CID+21401 -59F8 E0100; Adobe-Japan1; CID+19312 -59FB E0100; Adobe-Japan1; CID+1213 -59FF E0100; Adobe-Japan1; CID+2207 -59FF E0101; Adobe-Japan1; CID+13792 -59FF E0102; Adobe-Japan1; CID+13793 -59FF E0103; Hanyo-Denshi; JA2749 -59FF E0103; Moji_Joho; MJ009691 -59FF E0104; Hanyo-Denshi; JTAFE4 -59FF E0104; Moji_Joho; MJ009690 -5A00 E0100; Adobe-Japan1; CID+21402 -5A01 E0100; Adobe-Japan1; CID+1174 -5A01 E0101; Moji_Joho; MJ009693 -5A01 E0102; Moji_Joho; MJ009694 -5A03 E0100; Adobe-Japan1; CID+1127 -5A04 E0100; Adobe-Japan1; CID+14454 -5A09 E0100; Adobe-Japan1; CID+4577 -5A0C E0100; Adobe-Japan1; CID+14455 -5A0D E0100; Adobe-Japan1; CID+17495 -5A0E E0100; Adobe-Japan1; CID+21403 -5A11 E0100; Adobe-Japan1; CID+4575 -5A12 E0100; Adobe-Japan1; CID+21404 -5A13 E0100; Adobe-Japan1; CID+16828 -5A17 E0100; Adobe-Japan1; CID+17496 -5A18 E0100; Adobe-Japan1; CID+3784 -5A19 E0100; Hanyo-Denshi; IP5A19 -5A19 E0101; Hanyo-Denshi; TK01020270 -5A1A E0100; Adobe-Japan1; CID+4578 -5A1B E0100; Adobe-Japan1; CID+13761 -5A1C E0100; Adobe-Japan1; CID+4576 -5A1C E0101; Adobe-Japan1; CID+14118 -5A1C E0102; Hanyo-Denshi; JA5317 -5A1C E0102; Moji_Joho; MJ009719 -5A1C E0103; Hanyo-Denshi; JTAFE8 -5A1C E0103; Moji_Joho; MJ009720 -5A1E E0100; Adobe-Japan1; CID+21405 -5A1F E0100; Adobe-Japan1; CID+4574 -5A20 E0100; Adobe-Japan1; CID+2551 -5A23 E0100; Adobe-Japan1; CID+14456 -5A24 E0100; Adobe-Japan1; CID+21406 -5A25 E0100; Adobe-Japan1; CID+4573 -5A27 E0100; Adobe-Japan1; CID+17497 -5A27 E0101; Hanyo-Denshi; JB2554 -5A27 E0102; Hanyo-Denshi; TK01020320 -5A28 E0100; Adobe-Japan1; CID+21407 -5A29 E0100; Adobe-Japan1; CID+3626 -5A29 E0101; Adobe-Japan1; CID+7791 -5A29 E0102; Hanyo-Denshi; JA4258 -5A29 E0102; Moji_Joho; MJ009735 -5A29 E0103; Hanyo-Denshi; FT1918 -5A29 E0103; Moji_Joho; MJ009734 -5A2A E0100; Adobe-Japan1; CID+21408 -5A2D E0100; Adobe-Japan1; CID+17498 -5A2F E0100; Adobe-Japan1; CID+1944 -5A30 E0100; Adobe-Japan1; CID+21409 -5A35 E0100; Adobe-Japan1; CID+4582 -5A36 E0100; Adobe-Japan1; CID+4583 -5A36 E0101; Adobe-Japan1; CID+13531 -5A36 E0102; Moji_Joho; MJ009744 -5A36 E0103; Moji_Joho; MJ009745 -5A3C E0100; Adobe-Japan1; CID+2451 -5A40 E0100; Adobe-Japan1; CID+4579 -5A41 E0100; Adobe-Japan1; CID+4050 -5A41 E0101; Hanyo-Denshi; JA4712 -5A41 E0101; Moji_Joho; MJ009756 -5A41 E0102; Hanyo-Denshi; KS072680 -5A41 E0102; Moji_Joho; MJ057300 -5A44 E0100; Adobe-Japan1; CID+21410 -5A45 E0100; Adobe-Japan1; CID+21411 -5A46 E0100; Adobe-Japan1; CID+3330 -5A47 E0100; Adobe-Japan1; CID+14457 -5A48 E0100; Adobe-Japan1; CID+21412 -5A48 E0101; Hanyo-Denshi; JB2562 -5A48 E0101; Moji_Joho; MJ009764 -5A48 E0102; Hanyo-Denshi; KS073020 -5A48 E0102; Moji_Joho; MJ009763 -5A49 E0100; Adobe-Japan1; CID+4581 -5A4C E0100; Adobe-Japan1; CID+21413 -5A4C E0101; Moji_Joho; MJ009768 -5A4C E0102; Moji_Joho; MJ009769 -5A50 E0100; Adobe-Japan1; CID+21414 -5A55 E0100; Adobe-Japan1; CID+14458 -5A58 E0100; Hanyo-Denshi; IP5A58 -5A58 E0101; Hanyo-Denshi; TK01020510 -5A5A E0100; Adobe-Japan1; CID+2071 -5A5E E0100; Adobe-Japan1; CID+21415 -5A62 E0100; Adobe-Japan1; CID+4584 -5A63 E0100; Adobe-Japan1; CID+14459 -5A64 E0100; Hanyo-Denshi; IP5A64 -5A64 E0101; Hanyo-Denshi; TK01020460 -5A65 E0100; Adobe-Japan1; CID+17499 -5A66 E0100; Adobe-Japan1; CID+3530 -5A66 E0101; Adobe-Japan1; CID+14002 -5A66 E0102; Hanyo-Denshi; JA4156 -5A66 E0102; Moji_Joho; MJ009797 -5A66 E0103; Hanyo-Denshi; JTAFEDS -5A66 E0103; Moji_Joho; MJ009796 -5A67 E0100; Adobe-Japan1; CID+16829 -5A67 E0101; Hanyo-Denshi; JB2569 -5A67 E0101; Moji_Joho; MJ009798 -5A67 E0102; Hanyo-Denshi; IB0655 -5A67 E0102; Moji_Joho; MJ009799 -5A6A E0100; Adobe-Japan1; CID+4585 -5A6C E0100; Adobe-Japan1; CID+4580 -5A6C E0101; Hanyo-Denshi; JA5321 -5A6C E0101; Moji_Joho; MJ009804 -5A6C E0102; Hanyo-Denshi; FT2142 -5A6C E0102; Moji_Joho; MJ009805 -5A6D E0100; Adobe-Japan1; CID+14460 -5A77 E0100; Adobe-Japan1; CID+16830 -5A7A E0100; Adobe-Japan1; CID+17500 -5A7B E0100; Adobe-Japan1; CID+21416 -5A7E E0100; Adobe-Japan1; CID+14461 -5A7E E0101; Hanyo-Denshi; JB2574 -5A7E E0101; Moji_Joho; MJ009820 -5A7E E0102; Hanyo-Denshi; IB1644 -5A7E E0102; Moji_Joho; MJ009821 -5A7F E0100; Adobe-Japan1; CID+3783 -5A84 E0100; Adobe-Japan1; CID+16831 -5A8B E0100; Adobe-Japan1; CID+17501 -5A8D E0100; Hanyo-Denshi; IP5A8D -5A8D E0100; Moji_Joho; MJ009836 -5A8D E0101; Hanyo-Denshi; KS074830 -5A8D E0101; Moji_Joho; MJ057309 -5A90 E0100; Adobe-Japan1; CID+21417 -5A92 E0100; Adobe-Japan1; CID+3348 -5A93 E0100; Adobe-Japan1; CID+21418 -5A96 E0100; Adobe-Japan1; CID+21419 -5A96 E0101; Hanyo-Denshi; JB2578 -5A96 E0101; Moji_Joho; MJ009845 -5A96 E0102; Hanyo-Denshi; KS074170 -5A96 E0102; Moji_Joho; MJ009846 -5A99 E0100; Adobe-Japan1; CID+21420 -5A9A E0100; Adobe-Japan1; CID+4586 -5A9B E0100; Adobe-Japan1; CID+3492 -5A9B E0101; Adobe-Japan1; CID+7784 -5A9B E0102; Hanyo-Denshi; JA4118 -5A9B E0102; Moji_Joho; MJ009852 -5A9B E0103; Hanyo-Denshi; FT1911S -5A9B E0103; Moji_Joho; MJ009851 -5A9C E0100; Adobe-Japan1; CID+17502 -5A9E E0100; Adobe-Japan1; CID+14462 -5A9F E0100; Adobe-Japan1; CID+17503 -5AA0 E0100; Adobe-Japan1; CID+17504 -5AA2 E0100; Adobe-Japan1; CID+17505 -5AA2 E0101; Hanyo-Denshi; JB2584 -5AA2 E0101; Moji_Joho; MJ009859 -5AA2 E0102; Hanyo-Denshi; JTAFF2 -5AA2 E0102; Moji_Joho; MJ009860 -5AA7 E0100; Adobe-Japan1; CID+14463 -5AAC E0100; Adobe-Japan1; CID+14464 -5AB1 E0100; Adobe-Japan1; CID+17506 -5AB2 E0100; Adobe-Japan1; CID+19313 -5AB3 E0100; Adobe-Japan1; CID+14465 -5AB5 E0100; Adobe-Japan1; CID+17507 -5AB5 E0101; Hanyo-Denshi; JB2590 -5AB5 E0101; Moji_Joho; MJ009875 -5AB5 E0102; Hanyo-Denshi; JTAFFA -5AB5 E0102; Moji_Joho; MJ009876 -5AB8 E0100; Adobe-Japan1; CID+19314 -5ABA E0100; Adobe-Japan1; CID+17508 -5ABA E0101; Hanyo-Denshi; JB2592 -5ABA E0101; Moji_Joho; MJ009881 -5ABA E0102; Hanyo-Denshi; JTAFF7S -5ABA E0102; Moji_Joho; MJ009882 -5ABA E0103; Hanyo-Denshi; JTAFF8 -5ABA E0103; Moji_Joho; MJ009883 -5ABB E0100; Adobe-Japan1; CID+21421 -5ABC E0100; Adobe-Japan1; CID+4587 -5ABD E0100; Adobe-Japan1; CID+4591 -5ABE E0100; Adobe-Japan1; CID+4588 -5ABE E0101; Adobe-Japan1; CID+7824 -5ABE E0102; Adobe-Japan1; CID+13532 -5ABE E0103; Hanyo-Denshi; JA5329 -5ABE E0103; Moji_Joho; MJ009888 -5ABE E0104; Hanyo-Denshi; FT1951S -5ABE E0104; Moji_Joho; MJ009887 -5ABF E0100; Adobe-Japan1; CID+17509 -5ABF E0101; Hanyo-Denshi; JB2594 -5ABF E0101; Moji_Joho; MJ009889 -5ABF E0102; Hanyo-Denshi; KS074870 -5ABF E0102; Moji_Joho; MJ057310 -5AC1 E0100; Adobe-Japan1; CID+1351 -5AC1 E0101; Hanyo-Denshi; JA1839 -5AC1 E0101; Moji_Joho; MJ009891 -5AC1 E0102; Hanyo-Denshi; FT2016 -5AC1 E0102; Moji_Joho; MJ009892 -5AC2 E0100; Adobe-Japan1; CID+4590 -5AC2 E0101; Adobe-Japan1; CID+14119 -5AC2 E0102; Hanyo-Denshi; JA5331 -5AC2 E0102; Moji_Joho; MJ009893 -5AC2 E0103; Hanyo-Denshi; KS075260 -5AC2 E0103; Moji_Joho; MJ009894 -5AC2 E0104; Hanyo-Denshi; FT2145 -5AC2 E0104; Moji_Joho; MJ009895 -5AC3 E0100; Hanyo-Denshi; IP5AC3 -5AC3 E0101; Hanyo-Denshi; TK01020610 -5AC3 E0102; Hanyo-Denshi; TK01020620 -5AC4 E0100; Adobe-Japan1; CID+16832 -5AC6 E0100; Adobe-Japan1; CID+21422 -5AC6 E0101; Hanyo-Denshi; JB2602 -5AC6 E0102; Hanyo-Denshi; TK01020560 -5AC8 E0100; Adobe-Japan1; CID+21423 -5AC9 E0100; Adobe-Japan1; CID+2279 -5ACB E0100; Adobe-Japan1; CID+4589 -5ACB E0101; Hanyo-Denshi; JA5330 -5ACB E0101; Moji_Joho; MJ009907 -5ACB E0102; Hanyo-Denshi; FT2144 -5ACB E0102; Moji_Joho; MJ009908 -5ACC E0100; Adobe-Japan1; CID+1871 -5ACC E0101; Adobe-Japan1; CID+7675 -5ACC E0102; Hanyo-Denshi; JA2389 -5ACC E0102; Moji_Joho; MJ009910 -5ACC E0103; Hanyo-Denshi; FT1791S -5ACC E0103; Moji_Joho; MJ009909 -5ACF E0100; Adobe-Japan1; CID+21424 -5AD0 E0100; Adobe-Japan1; CID+4603 -5AD6 E0100; Adobe-Japan1; CID+4596 -5AD7 E0100; Adobe-Japan1; CID+4593 -5AD7 E0101; Hanyo-Denshi; JA5334 -5AD7 E0101; Moji_Joho; MJ009917 -5AD7 E0102; Hanyo-Denshi; KS076290 -5AD7 E0102; Moji_Joho; MJ009918 -5ADA E0100; Adobe-Japan1; CID+17510 -5ADA E0101; Adobe-Japan1; CID+20107 -5ADA E0102; Hanyo-Denshi; JB2605 -5ADA E0102; Moji_Joho; MJ009921 -5ADA E0103; Hanyo-Denshi; JD0574 -5ADA E0103; Moji_Joho; MJ009922 -5ADB E0100; Hanyo-Denshi; IP5ADB -5ADB E0100; Moji_Joho; MJ009923 -5ADB E0101; Hanyo-Denshi; KS076280 -5ADB E0101; Moji_Joho; MJ009924 -5ADC E0100; Adobe-Japan1; CID+17511 -5ADC E0101; Hanyo-Denshi; JB2606 -5ADC E0101; Moji_Joho; MJ009925 -5ADC E0102; Hanyo-Denshi; KS076270 -5ADC E0102; Moji_Joho; MJ009926 -5ADF E0100; Hanyo-Denshi; KS075770 -5ADF E0100; Moji_Joho; MJ009929 -5ADF E0101; Hanyo-Denshi; KS076300 -5ADF E0101; Moji_Joho; MJ009930 -5AE0 E0100; Adobe-Japan1; CID+14466 -5AE1 E0100; Adobe-Japan1; CID+2978 -5AE1 E0101; Hanyo-Denshi; JA3568 -5AE1 E0101; Moji_Joho; MJ009932 -5AE1 E0102; Hanyo-Denshi; JTAFFF -5AE1 E0102; Moji_Joho; MJ009933 -5AE2 E0100; Hanyo-Denshi; IP5AE2 -5AE2 E0101; Hanyo-Denshi; TK01020720 -5AE3 E0100; Adobe-Japan1; CID+4592 -5AE4 E0100; Hanyo-Denshi; IP5AE4 -5AE4 E0101; Hanyo-Denshi; TK01020600 -5AE5 E0100; Adobe-Japan1; CID+17512 -5AE6 E0100; Adobe-Japan1; CID+4594 -5AE9 E0100; Adobe-Japan1; CID+4595 -5AEA E0100; Adobe-Japan1; CID+19315 -5AEB E0100; Hanyo-Denshi; KS075980 -5AEB E0101; Hanyo-Denshi; TK01020630 -5AEE E0100; Adobe-Japan1; CID+17514 -5AF0 E0100; Adobe-Japan1; CID+17513 -5AF5 E0100; Adobe-Japan1; CID+17515 -5AF6 E0100; Adobe-Japan1; CID+19316 -5AF8 E0100; Hanyo-Denshi; IP5AF8 -5AF8 E0101; Hanyo-Denshi; TK01020830 -5AFA E0100; Adobe-Japan1; CID+4597 -5AFB E0100; Adobe-Japan1; CID+4598 -5AFD E0100; Adobe-Japan1; CID+21425 -5B00 E0100; Adobe-Japan1; CID+14467 -5B01 E0100; Adobe-Japan1; CID+21426 -5B05 E0100; Hanyo-Denshi; IP5B05 -5B05 E0100; Moji_Joho; MJ009970 -5B05 E0101; Hanyo-Denshi; KS076620 -5B05 E0101; Moji_Joho; MJ009969 -5B08 E0100; Adobe-Japan1; CID+17516 -5B09 E0100; Adobe-Japan1; CID+1582 -5B0B E0100; Adobe-Japan1; CID+4600 -5B0C E0100; Adobe-Japan1; CID+4599 -5B0D E0100; Hanyo-Denshi; IP5B0D -5B0D E0101; Hanyo-Denshi; TK01020570 -5B16 E0100; Adobe-Japan1; CID+4601 -5B17 E0100; Adobe-Japan1; CID+17517 -5B19 E0100; Adobe-Japan1; CID+14468 -5B1A E0100; Hanyo-Denshi; IP5B1A -5B1A E0101; Hanyo-Denshi; TK01020940 -5B1B E0100; Adobe-Japan1; CID+19317 -5B1D E0100; Adobe-Japan1; CID+19318 -5B21 E0100; Adobe-Japan1; CID+19319 -5B22 E0100; Adobe-Japan1; CID+2518 -5B25 E0100; Adobe-Japan1; CID+14469 -5B28 E0100; Hanyo-Denshi; KS077600 -5B28 E0101; Hanyo-Denshi; TK01020880 -5B2A E0100; Adobe-Japan1; CID+4604 -5B2A E0101; Hanyo-Denshi; JA5345 -5B2A E0101; Moji_Joho; MJ010008 -5B2A E0102; Hanyo-Denshi; JTB007 -5B2A E0102; Moji_Joho; MJ010009 -5B2C E0100; Adobe-Japan1; CID+3064 -5B2D E0100; Adobe-Japan1; CID+14470 -5B30 E0100; Adobe-Japan1; CID+1255 -5B32 E0100; Adobe-Japan1; CID+4602 -5B34 E0100; Adobe-Japan1; CID+17518 -5B34 E0101; Hanyo-Denshi; JB2618 -5B34 E0101; Moji_Joho; MJ010019 -5B34 E0102; Hanyo-Denshi; JTB003 -5B34 E0102; Moji_Joho; MJ010021 -5B34 E0103; Hanyo-Denshi; IB1650 -5B34 E0103; Moji_Joho; MJ010020 -5B34 E0104; Hanyo-Denshi; TK01020870 -5B36 E0100; Adobe-Japan1; CID+4605 -5B36 E0101; Hanyo-Denshi; JA5346 -5B36 E0101; Moji_Joho; MJ010024 -5B36 E0102; Hanyo-Denshi; FT2148 -5B36 E0102; Moji_Joho; MJ010025 -5B38 E0100; Adobe-Japan1; CID+19320 -5B3E E0100; Adobe-Japan1; CID+4606 -5B3E E0101; Hanyo-Denshi; JA5347 -5B3E E0101; Moji_Joho; MJ010032 -5B3E E0102; Hanyo-Denshi; FT2149 -5B3E E0102; Moji_Joho; MJ010033 -5B40 E0100; Adobe-Japan1; CID+4609 -5B41 E0100; Adobe-Japan1; CID+14471 -5B43 E0100; Adobe-Japan1; CID+4607 -5B45 E0100; Adobe-Japan1; CID+4608 -5B4B E0100; Adobe-Japan1; CID+21427 -5B4C E0100; Adobe-Japan1; CID+17519 -5B50 E0100; Adobe-Japan1; CID+2208 -5B51 E0100; Adobe-Japan1; CID+4610 -5B52 E0100; Adobe-Japan1; CID+17520 -5B54 E0100; Adobe-Japan1; CID+1976 -5B55 E0100; Adobe-Japan1; CID+4611 -5B56 E0100; Adobe-Japan1; CID+8432 -5B57 E0100; Adobe-Japan1; CID+2248 -5B58 E0100; Adobe-Japan1; CID+2840 -5B5A E0100; Adobe-Japan1; CID+4612 -5B5A E0101; Adobe-Japan1; CID+20108 -5B5A E0102; Hanyo-Denshi; JA5353 -5B5A E0102; Moji_Joho; MJ010060 -5B5A E0103; Hanyo-Denshi; KS079130 -5B5A E0103; Moji_Joho; MJ010061 -5B5B E0100; Adobe-Japan1; CID+4613 -5B5C E0100; Adobe-Japan1; CID+2216 -5B5D E0100; Adobe-Japan1; CID+1977 -5B5E E0100; Adobe-Japan1; CID+21428 -5B5F E0100; Adobe-Japan1; CID+3806 -5B63 E0100; Adobe-Japan1; CID+1602 -5B64 E0100; Adobe-Japan1; CID+1917 -5B64 E0101; Hanyo-Denshi; JA2441 -5B64 E0101; Moji_Joho; MJ010073 -5B64 E0102; Hanyo-Denshi; KS079290 -5B64 E0102; Moji_Joho; MJ010072 -5B64 E0103; Hanyo-Denshi; KS079200S -5B64 E0103; Moji_Joho; MJ010071 -5B65 E0100; Adobe-Japan1; CID+4614 -5B66 E0100; Adobe-Japan1; CID+1462 -5B68 E0100; Adobe-Japan1; CID+17521 -5B69 E0100; Adobe-Japan1; CID+4615 -5B69 E0101; Hanyo-Denshi; JA5356 -5B69 E0101; Moji_Joho; MJ010077 -5B69 E0102; Hanyo-Denshi; KS079400 -5B69 E0102; Moji_Joho; MJ010078 -5B6B E0100; Adobe-Japan1; CID+2841 -5B6B E0101; Hanyo-Denshi; JA3425 -5B6B E0102; Hanyo-Denshi; TK01021150 -5B6E E0100; Adobe-Japan1; CID+21429 -5B6F E0100; Adobe-Japan1; CID+17522 -5B70 E0100; Adobe-Japan1; CID+4616 -5B70 E0101; Hanyo-Denshi; JA5357 -5B70 E0101; Moji_Joho; MJ010084 -5B70 E0102; Hanyo-Denshi; KS079690S -5B70 E0102; Moji_Joho; MJ057322 -5B71 E0100; Adobe-Japan1; CID+4656 -5B73 E0100; Adobe-Japan1; CID+4617 -5B73 E0101; Adobe-Japan1; CID+20109 -5B73 E0102; Hanyo-Denshi; JA5358 -5B73 E0102; Moji_Joho; MJ010087 -5B73 E0103; Hanyo-Denshi; JTB011 -5B73 E0103; Moji_Joho; MJ010088 -5B75 E0100; Adobe-Japan1; CID+4618 -5B75 E0101; Hanyo-Denshi; JA5359 -5B75 E0101; Moji_Joho; MJ010090 -5B75 E0102; Hanyo-Denshi; FT2150 -5B75 E0102; Moji_Joho; MJ010091 -5B76 E0100; Adobe-Japan1; CID+14120 -5B76 E0101; Hanyo-Denshi; JT5B76 -5B76 E0101; Moji_Joho; MJ010093 -5B76 E0102; Hanyo-Denshi; KS079840 -5B76 E0102; Moji_Joho; MJ010092 -5B78 E0100; Adobe-Japan1; CID+4619 -5B7A E0100; Adobe-Japan1; CID+4621 -5B7C E0100; Adobe-Japan1; CID+14472 -5B7C E0101; Adobe-Japan1; CID+20110 -5B7C E0102; Hanyo-Denshi; JB2635 -5B7C E0102; Moji_Joho; MJ010100 -5B7C E0103; Hanyo-Denshi; KS080120 -5B7C E0103; Moji_Joho; MJ010099 -5B7D E0100; Adobe-Japan1; CID+16834 -5B7D E0101; Hanyo-Denshi; JB2636 -5B7D E0101; Moji_Joho; MJ010102 -5B7D E0102; Hanyo-Denshi; KS080140 -5B7D E0102; Moji_Joho; MJ010101 -5B7E E0100; Adobe-Japan1; CID+14473 -5B7F E0100; Adobe-Japan1; CID+14474 -5B80 E0100; Adobe-Japan1; CID+4622 -5B81 E0100; Adobe-Japan1; CID+17523 -5B82 E0100; Adobe-Japan1; CID+13840 -5B82 E0101; Hanyo-Denshi; IP5B82 -5B82 E0102; Hanyo-Denshi; TK01021460 -5B83 E0100; Adobe-Japan1; CID+4623 -5B84 E0100; Adobe-Japan1; CID+17524 -5B85 E0100; Adobe-Japan1; CID+2896 -5B85 E0101; Hanyo-Denshi; JA3480 -5B85 E0101; Moji_Joho; MJ010110 -5B85 E0102; Hanyo-Denshi; KS080680 -5B85 E0102; Moji_Joho; MJ057328 -5B86 E0100; Adobe-Japan1; CID+21430 -5B87 E0100; Adobe-Japan1; CID+1225 -5B88 E0100; Adobe-Japan1; CID+2325 -5B89 E0100; Adobe-Japan1; CID+1158 -5B8A E0100; Adobe-Japan1; CID+14475 -5B8B E0100; Adobe-Japan1; CID+2777 -5B8C E0100; Adobe-Japan1; CID+1516 -5B8D E0100; Adobe-Japan1; CID+2273 -5B8E E0100; Adobe-Japan1; CID+21431 -5B8F E0100; Adobe-Japan1; CID+1978 -5B90 E0100; Adobe-Japan1; CID+21432 -5B90 E0101; Hanyo-Denshi; JB2644 -5B90 E0101; Moji_Joho; MJ010121 -5B90 E0102; Hanyo-Denshi; KS080830 -5B90 E0102; Moji_Joho; MJ010122 -5B90 E0103; Hanyo-Denshi; TK01021520 -5B91 E0100; Adobe-Japan1; CID+21433 -5B93 E0100; Adobe-Japan1; CID+16835 -5B94 E0100; Adobe-Japan1; CID+21434 -5B95 E0100; Adobe-Japan1; CID+3168 -5B96 E0100; Adobe-Japan1; CID+17526 -5B97 E0100; Adobe-Japan1; CID+2347 -5B98 E0100; Adobe-Japan1; CID+1517 -5B99 E0100; Adobe-Japan1; CID+2982 -5B9A E0100; Adobe-Japan1; CID+3078 -5B9B E0100; Adobe-Japan1; CID+1148 -5B9C E0100; Adobe-Japan1; CID+1619 -5B9D E0100; Adobe-Japan1; CID+3653 -5B9F E0100; Adobe-Japan1; CID+2286 -5BA2 E0100; Adobe-Japan1; CID+1644 -5BA3 E0100; Adobe-Japan1; CID+2703 -5BA3 E0101; Hanyo-Denshi; JA3275 -5BA3 E0101; Moji_Joho; MJ010139 -5BA3 E0102; Hanyo-Denshi; KS081260 -5BA3 E0102; Moji_Joho; MJ010140 -5BA3 E0103; Hanyo-Denshi; TK01021730 -5BA4 E0100; Adobe-Japan1; CID+2280 -5BA4 E0101; Hanyo-Denshi; JA2828 -5BA4 E0102; Hanyo-Denshi; TK01021850 -5BA5 E0100; Adobe-Japan1; CID+3858 -5BA6 E0100; Adobe-Japan1; CID+4624 -5BA8 E0100; Adobe-Japan1; CID+21435 -5BA9 E0100; Adobe-Japan1; CID+21436 -5BAC E0100; Adobe-Japan1; CID+17527 -5BAC E0101; Hanyo-Denshi; JB2651 -5BAC E0102; Hanyo-Denshi; TK01022010 -5BAD E0100; Adobe-Japan1; CID+21437 -5BAD E0101; Hanyo-Denshi; JB2652 -5BAD E0102; Hanyo-Denshi; TK01021860 -5BAE E0100; Adobe-Japan1; CID+1654 -5BAF E0100; Adobe-Japan1; CID+21438 -5BB0 E0100; Adobe-Japan1; CID+2107 -5BB1 E0100; Adobe-Japan1; CID+21439 -5BB2 E0100; Adobe-Japan1; CID+21440 -5BB2 E0101; Hanyo-Denshi; JB2655 -5BB2 E0101; Moji_Joho; MJ010157 -5BB2 E0102; Hanyo-Denshi; JTB01C -5BB2 E0102; Moji_Joho; MJ010158 -5BB3 E0100; Adobe-Japan1; CID+1424 -5BB3 E0101; Adobe-Japan1; CID+13421 -5BB3 E0102; Adobe-Japan1; CID+13675 -5BB3 E0103; Adobe-Japan1; CID+20111 -5BB3 E0104; Hanyo-Denshi; JA1918 -5BB3 E0104; Moji_Joho; MJ010160 -5BB3 E0105; Hanyo-Denshi; KS081420S -5BB3 E0105; Moji_Joho; MJ010159 -5BB3 E0106; Hanyo-Denshi; JTB01D -5BB3 E0106; Moji_Joho; MJ010161 -5BB4 E0100; Adobe-Japan1; CID+1285 -5BB5 E0100; Adobe-Japan1; CID+2452 -5BB5 E0101; Adobe-Japan1; CID+13831 -5BB5 E0102; Hanyo-Denshi; JA3012 -5BB5 E0102; Moji_Joho; MJ010164 -5BB5 E0103; Hanyo-Denshi; JTB01B -5BB5 E0103; Moji_Joho; MJ010163 -5BB6 E0100; Adobe-Japan1; CID+1352 -5BB6 E0101; Hanyo-Denshi; JA1840 -5BB6 E0101; Moji_Joho; MJ010165 -5BB6 E0102; Hanyo-Denshi; FT2017 -5BB6 E0102; Moji_Joho; MJ010166 -5BB7 E0100; Adobe-Japan1; CID+19321 -5BB8 E0100; Adobe-Japan1; CID+4625 -5BB9 E0100; Adobe-Japan1; CID+3888 -5BBA E0100; Adobe-Japan1; CID+21441 -5BBB E0100; Hanyo-Denshi; IP5BBB -5BBB E0100; Moji_Joho; MJ010171 -5BBB E0101; Hanyo-Denshi; KS082080 -5BBB E0101; Moji_Joho; MJ057334 -5BBC E0100; Adobe-Japan1; CID+21442 -5BBF E0100; Adobe-Japan1; CID+2387 -5BC0 E0100; Adobe-Japan1; CID+8433 -5BC0 E0101; Hanyo-Denshi; JB2659 -5BC0 E0101; Moji_Joho; MJ010175 -5BC0 E0102; Hanyo-Denshi; JTB027 -5BC0 E0102; Moji_Joho; MJ010176 -5BC1 E0100; Adobe-Japan1; CID+21443 -5BC2 E0100; Adobe-Japan1; CID+2320 -5BC3 E0100; Adobe-Japan1; CID+4626 -5BC3 E0101; Adobe-Japan1; CID+14121 -5BC3 E0102; Hanyo-Denshi; JA5367 -5BC3 E0102; Moji_Joho; MJ010179 -5BC3 E0103; Hanyo-Denshi; JTB02DS -5BC3 E0103; Moji_Joho; MJ010181 -5BC3 E0104; Hanyo-Denshi; JTB024S -5BC3 E0104; Moji_Joho; MJ010180 -5BC4 E0100; Adobe-Japan1; CID+1583 -5BC5 E0100; Adobe-Japan1; CID+3242 -5BC5 E0101; Hanyo-Denshi; JA3850 -5BC5 E0102; Hanyo-Denshi; TK01022120 -5BC6 E0100; Adobe-Japan1; CID+3765 -5BC7 E0100; Adobe-Japan1; CID+4627 -5BC7 E0101; Hanyo-Denshi; JA5368 -5BC7 E0101; Moji_Joho; MJ010185 -5BC7 E0102; Hanyo-Denshi; JTB028 -5BC7 E0102; Moji_Joho; MJ010186 -5BC8 E0100; Hanyo-Denshi; IP5BC8 -5BC8 E0100; Moji_Joho; MJ010187 -5BC8 E0101; Hanyo-Denshi; JT5BC8 -5BC8 E0101; Moji_Joho; MJ010188 -5BC9 E0100; Adobe-Japan1; CID+4628 -5BCC E0100; Adobe-Japan1; CID+3531 -5BCD E0100; Adobe-Japan1; CID+21444 -5BCE E0100; Adobe-Japan1; CID+17530 -5BCF E0100; Adobe-Japan1; CID+21445 -5BCF E0101; Hanyo-Denshi; JB2662 -5BCF E0102; Hanyo-Denshi; TK01022410 -5BD0 E0100; Adobe-Japan1; CID+4630 -5BD0 E0101; Hanyo-Denshi; JA5371 -5BD0 E0101; Moji_Joho; MJ010196 -5BD0 E0102; Hanyo-Denshi; FT2152 -5BD0 E0102; Moji_Joho; MJ010197 -5BD2 E0100; Adobe-Japan1; CID+1508 -5BD2 E0101; Adobe-Japan1; CID+13688 -5BD2 E0102; Hanyo-Denshi; JA2008 -5BD2 E0102; Moji_Joho; MJ010199 -5BD2 E0103; Hanyo-Denshi; JTB02C -5BD2 E0103; Moji_Joho; MJ010200 -5BD3 E0100; Adobe-Japan1; CID+1775 -5BD4 E0100; Adobe-Japan1; CID+4629 -5BD5 E0100; Hanyo-Denshi; KS082440 -5BD5 E0101; Hanyo-Denshi; TK01022250 -5BD6 E0100; Adobe-Japan1; CID+17531 -5BD7 E0100; Adobe-Japan1; CID+19322 -5BD7 E0101; Hanyo-Denshi; JB2664 -5BD7 E0101; Moji_Joho; MJ010205 -5BD7 E0102; Hanyo-Denshi; IB1671 -5BD7 E0102; Moji_Joho; MJ010206 -5BD7 E0103; Hanyo-Denshi; JTB035 -5BD7 E0103; Moji_Joho; MJ010207 -5BD7 E0104; Hanyo-Denshi; JTC0B7 -5BD7 E0104; Moji_Joho; MJ010208 -5BD8 E0100; Adobe-Japan1; CID+8435 -5BD9 E0100; Adobe-Japan1; CID+21446 -5BD9 E0101; Hanyo-Denshi; JB2666 -5BD9 E0101; Moji_Joho; MJ010210 -5BD9 E0102; Hanyo-Denshi; KS082750 -5BD9 E0102; Moji_Joho; MJ010211 -5BDA E0100; Adobe-Japan1; CID+21447 -5BDB E0100; Adobe-Japan1; CID+1518 -5BDB E0101; Adobe-Japan1; CID+8436 -5BDB E0102; Hanyo-Denshi; JA2018 -5BDB E0102; Moji_Joho; MJ010213 -5BDB E0103; Hanyo-Denshi; JTB032S -5BDB E0103; Moji_Joho; MJ010214 -5BDD E0100; Adobe-Japan1; CID+2552 -5BDE E0100; Adobe-Japan1; CID+4634 -5BDE E0101; Hanyo-Denshi; JA5375 -5BDE E0101; Moji_Joho; MJ010217 -5BDE E0102; Hanyo-Denshi; KS082790S -5BDE E0102; Moji_Joho; MJ010218 -5BDF E0100; Adobe-Japan1; CID+2159 -5BE0 E0100; Adobe-Japan1; CID+19323 -5BE1 E0100; Adobe-Japan1; CID+1353 -5BE2 E0100; Adobe-Japan1; CID+4633 -5BE2 E0101; Hanyo-Denshi; JA5374 -5BE2 E0101; Moji_Joho; MJ010222 -5BE2 E0102; Hanyo-Denshi; JTB036 -5BE2 E0102; Moji_Joho; MJ010223 -5BE4 E0100; Adobe-Japan1; CID+4631 -5BE4 E0101; Hanyo-Denshi; JA5372 -5BE4 E0101; Moji_Joho; MJ010225 -5BE4 E0102; Hanyo-Denshi; FT2153 -5BE4 E0102; Moji_Joho; MJ010226 -5BE5 E0100; Adobe-Japan1; CID+4635 -5BE5 E0101; Hanyo-Denshi; JA5376 -5BE5 E0101; Moji_Joho; MJ010227 -5BE5 E0102; Hanyo-Denshi; FT2155 -5BE5 E0102; Moji_Joho; MJ010228 -5BE6 E0100; Adobe-Japan1; CID+4632 -5BE7 E0100; Adobe-Japan1; CID+13971 -5BE7 E0101; Adobe-Japan1; CID+3297 -5BE7 E0102; Hanyo-Denshi; JA3911 -5BE7 E0102; Moji_Joho; MJ010231 -5BE7 E0103; Hanyo-Denshi; JTB031 -5BE7 E0103; Moji_Joho; MJ010230 -5BE8 E0100; Adobe-Japan1; CID+5262 -5BE8 E0101; Adobe-Japan1; CID+14146 -5BE9 E0100; Adobe-Japan1; CID+2553 -5BEB E0100; Adobe-Japan1; CID+4636 -5BEC E0100; Adobe-Japan1; CID+20302 -5BEC E0101; Hanyo-Denshi; JC4758 -5BEC E0101; Moji_Joho; MJ010236 -5BEC E0102; Hanyo-Denshi; JTB038S -5BEC E0102; Moji_Joho; MJ010237 -5BEC E0103; Hanyo-Denshi; JTB033 -5BEC E0103; Moji_Joho; MJ010238 -5BEC E0104; Hanyo-Denshi; TK01022820 -5BED E0100; Hanyo-Denshi; IP5BED -5BED E0101; Hanyo-Denshi; TK01022460 -5BED E0102; Hanyo-Denshi; TK01022860 -5BEE E0100; Adobe-Japan1; CID+3976 -5BEF E0100; Adobe-Japan1; CID+21448 -5BF0 E0100; Adobe-Japan1; CID+4637 -5BF1 E0100; Adobe-Japan1; CID+17534 -5BF3 E0100; Adobe-Japan1; CID+4639 -5BF4 E0100; Adobe-Japan1; CID+21449 -5BF5 E0100; Adobe-Japan1; CID+3004 -5BF5 E0101; Hanyo-Denshi; JA3594 -5BF5 E0101; Moji_Joho; MJ010248 -5BF5 E0102; Hanyo-Denshi; JTB03D -5BF5 E0102; Moji_Joho; MJ010250 -5BF5 E0103; Hanyo-Denshi; KS083790 -5BF5 E0103; Moji_Joho; MJ010249 -5BF6 E0100; Adobe-Japan1; CID+4638 -5BF6 E0101; Hanyo-Denshi; JA5379 -5BF6 E0101; Moji_Joho; MJ010251 -5BF6 E0102; Hanyo-Denshi; JTB03E -5BF6 E0102; Moji_Joho; MJ059512 -5BF6 E0103; Hanyo-Denshi; TK01023180 -5BF8 E0100; Adobe-Japan1; CID+2631 -5BFA E0100; Adobe-Japan1; CID+2249 -5BFD E0100; Adobe-Japan1; CID+17535 -5BFD E0101; Hanyo-Denshi; JB2672 -5BFD E0101; Moji_Joho; MJ010256 -5BFD E0102; Hanyo-Denshi; IB1679 -5BFD E0102; Moji_Joho; MJ010257 -5BFE E0100; Adobe-Japan1; CID+2864 -5BFF E0100; Adobe-Japan1; CID+2339 -5BFF E0101; Hanyo-Denshi; JA2887 -5BFF E0101; Moji_Joho; MJ010260 -5BFF E0102; Hanyo-Denshi; KS084230 -5BFF E0102; Moji_Joho; MJ010259 -5C01 E0100; Adobe-Japan1; CID+3559 -5C02 E0100; Adobe-Japan1; CID+2704 -5C02 E0101; Hanyo-Denshi; JA3276 -5C02 E0102; Hanyo-Denshi; TK01023430 -5C03 E0100; Adobe-Japan1; CID+17537 -5C04 E0100; Adobe-Japan1; CID+2297 -5C04 E0101; Moji_Joho; MJ010265 -5C04 E0102; Moji_Joho; MJ010266 -5C05 E0100; Adobe-Japan1; CID+4640 -5C06 E0100; Adobe-Japan1; CID+13832 -5C06 E0101; Adobe-Japan1; CID+2453 -5C06 E0102; Hanyo-Denshi; JA3013 -5C06 E0102; Moji_Joho; MJ010269 -5C06 E0103; Hanyo-Denshi; JTB03F -5C06 E0103; Moji_Joho; MJ010270 -5C06 E0104; Hanyo-Denshi; JTB570 -5C06 E0104; Moji_Joho; MJ010268 -5C07 E0100; Adobe-Japan1; CID+4641 -5C07 E0101; Hanyo-Denshi; JA5382 -5C07 E0101; Moji_Joho; MJ010271 -5C07 E0102; Hanyo-Denshi; JTB56E -5C07 E0102; Moji_Joho; MJ059879 -5C07 E0103; Hanyo-Denshi; JTB040 -5C07 E0103; Moji_Joho; MJ059513 -5C07 E0104; Hanyo-Denshi; IB1682 -5C07 E0104; Moji_Joho; MJ058022 -5C08 E0100; Adobe-Japan1; CID+4642 -5C08 E0101; Hanyo-Denshi; JA5383 -5C08 E0101; Moji_Joho; MJ010272 -5C08 E0102; Hanyo-Denshi; JTB041 -5C08 E0102; Moji_Joho; MJ010273 -5C09 E0100; Adobe-Japan1; CID+1175 -5C09 E0101; Hanyo-Denshi; JA1651 -5C09 E0101; Moji_Joho; MJ010274 -5C09 E0102; Hanyo-Denshi; KS084590 -5C09 E0102; Moji_Joho; MJ057350 -5C0A E0100; Adobe-Japan1; CID+2842 -5C0A E0101; Adobe-Japan1; CID+13901 -5C0A E0102; Adobe-Japan1; CID+13902 -5C0A E0103; Hanyo-Denshi; JA3426 -5C0A E0103; Moji_Joho; MJ010276 -5C0A E0104; Hanyo-Denshi; JTB045S -5C0A E0104; Moji_Joho; MJ010275 -5C0A E0105; Hanyo-Denshi; JTB046S -5C0A E0105; Moji_Joho; MJ010277 -5C0B E0100; Adobe-Japan1; CID+2584 -5C0B E0101; Adobe-Japan1; CID+13859 -5C0B E0102; Hanyo-Denshi; JA3150 -5C0B E0102; Moji_Joho; MJ010279 -5C0B E0103; Hanyo-Denshi; JTB044 -5C0B E0103; Moji_Joho; MJ010278 -5C0B E0104; Hanyo-Denshi; TK01023600 -5C0C E0100; Adobe-Japan1; CID+21450 -5C0D E0100; Adobe-Japan1; CID+4643 -5C0E E0100; Adobe-Japan1; CID+3211 -5C0E E0101; Adobe-Japan1; CID+13962 -5C0E E0102; Hanyo-Denshi; JA3819 -5C0E E0102; Moji_Joho; MJ010282 -5C0E E0103; Hanyo-Denshi; JTB04A -5C0E E0103; Moji_Joho; MJ010283 -5C0F E0100; Adobe-Japan1; CID+2454 -5C0F E0101; Adobe-Japan1; CID+13833 -5C0F E0102; Adobe-Japan1; CID+13834 -5C11 E0100; Adobe-Japan1; CID+2455 -5C12 E0100; Adobe-Japan1; CID+16836 -5C13 E0100; Adobe-Japan1; CID+4644 -5C14 E0100; Adobe-Japan1; CID+14122 -5C16 E0100; Adobe-Japan1; CID+2705 -5C17 E0100; Adobe-Japan1; CID+21451 -5C19 E0100; Adobe-Japan1; CID+13835 -5C19 E0101; Moji_Joho; MJ010294 -5C19 E0102; Moji_Joho; MJ010295 -5C1A E0100; Adobe-Japan1; CID+2456 -5C1E E0100; Adobe-Japan1; CID+8437 -5C1F E0100; Adobe-Japan1; CID+19324 -5C20 E0100; Adobe-Japan1; CID+4645 -5C22 E0100; Adobe-Japan1; CID+4646 -5C23 E0100; Adobe-Japan1; CID+14476 -5C23 E0101; Hanyo-Denshi; JB2677 -5C23 E0101; Moji_Joho; MJ010304 -5C23 E0102; Hanyo-Denshi; JTB052 -5C23 E0102; Moji_Joho; MJ010305 -5C24 E0100; Adobe-Japan1; CID+3820 -5C26 E0100; Adobe-Japan1; CID+21452 -5C28 E0100; Adobe-Japan1; CID+4647 -5C28 E0101; Adobe-Japan1; CID+7988 -5C28 E0102; Hanyo-Denshi; JA5388 -5C28 E0102; Moji_Joho; MJ010310 -5C28 E0103; Hanyo-Denshi; IA1607 -5C28 E0103; Moji_Joho; MJ010311 -5C28 E0104; Moji_Joho; MJ010309 -5C29 E0100; Adobe-Japan1; CID+17538 -5C2A E0100; Adobe-Japan1; CID+19325 -5C2B E0100; Adobe-Japan1; CID+14477 -5C2C E0100; Adobe-Japan1; CID+19326 -5C2D E0100; Adobe-Japan1; CID+1726 -5C2D E0101; Hanyo-Denshi; JA2238 -5C2D E0101; Moji_Joho; MJ010316 -5C2D E0102; Hanyo-Denshi; KS031950S -5C2D E0102; Moji_Joho; MJ010317 -5C2D E0103; Moji_Joho; MJ010318 -5C2E E0100; Adobe-Japan1; CID+21453 -5C30 E0100; Adobe-Japan1; CID+14478 -5C31 E0100; Adobe-Japan1; CID+2348 -5C32 E0100; Adobe-Japan1; CID+21454 -5C35 E0100; Adobe-Japan1; CID+21455 -5C36 E0100; Adobe-Japan1; CID+19327 -5C38 E0100; Adobe-Japan1; CID+4648 -5C39 E0100; Adobe-Japan1; CID+4649 -5C39 E0101; Hanyo-Denshi; JA5390 -5C39 E0101; Moji_Joho; MJ010329 -5C39 E0102; Hanyo-Denshi; JTB053 -5C39 E0102; Moji_Joho; MJ010330 -5C3A E0100; Adobe-Japan1; CID+2312 -5C3B E0100; Adobe-Japan1; CID+2546 -5C3C E0100; Adobe-Japan1; CID+3276 -5C3D E0100; Adobe-Japan1; CID+2586 -5C3E E0100; Adobe-Japan1; CID+3468 -5C3F E0100; Adobe-Japan1; CID+3288 -5C40 E0100; Adobe-Japan1; CID+1729 -5C41 E0100; Adobe-Japan1; CID+4650 -5C44 E0100; Hanyo-Denshi; IP5C44 -5C44 E0101; Hanyo-Denshi; TK01024020 -5C45 E0100; Adobe-Japan1; CID+1673 -5C46 E0100; Adobe-Japan1; CID+4651 -5C46 E0101; Hanyo-Denshi; JA5392 -5C46 E0101; Moji_Joho; MJ010342 -5C46 E0102; Hanyo-Denshi; KS087260 -5C46 E0102; Moji_Joho; MJ010343 -5C48 E0100; Adobe-Japan1; CID+1782 -5C4A E0100; Adobe-Japan1; CID+3239 -5C4B E0100; Adobe-Japan1; CID+1328 -5C4B E0101; Hanyo-Denshi; JA1816 -5C4B E0102; Hanyo-Denshi; TK01024100 -5C4D E0100; Adobe-Japan1; CID+2209 -5C4E E0100; Adobe-Japan1; CID+4652 -5C4F E0100; Adobe-Japan1; CID+4655 -5C4F E0101; Moji_Joho; MJ010352 -5C4F E0102; Moji_Joho; MJ010353 -5C50 E0100; Adobe-Japan1; CID+4654 -5C51 E0100; Adobe-Japan1; CID+1781 -5C51 E0101; Adobe-Japan1; CID+7666 -5C51 E0102; Hanyo-Denshi; JA2293 -5C51 E0102; Moji_Joho; MJ010356 -5C51 E0103; Hanyo-Denshi; FT1782 -5C51 E0103; Moji_Joho; MJ010355 -5C53 E0100; Adobe-Japan1; CID+4653 -5C53 E0101; Hanyo-Denshi; JA5394 -5C53 E0101; Moji_Joho; MJ010358 -5C53 E0102; Hanyo-Denshi; KS415920 -5C53 E0102; Moji_Joho; MJ010359 -5C55 E0100; Adobe-Japan1; CID+3122 -5C55 E0101; Hanyo-Denshi; JA3724 -5C55 E0101; Moji_Joho; MJ010361 -5C55 E0102; Hanyo-Denshi; JTB059 -5C55 E0102; Moji_Joho; MJ010362 -5C58 E0100; Hanyo-Denshi; TK01021170 -5C58 E0101; Hanyo-Denshi; TK01021220 -5C59 E0100; Adobe-Japan1; CID+19328 -5C5A E0100; Adobe-Japan1; CID+21456 -5C5B E0100; Adobe-Japan1; CID+7826 -5C5C E0100; Adobe-Japan1; CID+19329 -5C5E E0100; Adobe-Japan1; CID+2832 -5C5F E0100; Adobe-Japan1; CID+17540 -5C60 E0100; Adobe-Japan1; CID+3141 -5C60 E0101; Adobe-Japan1; CID+7754 -5C60 E0102; Hanyo-Denshi; JA3743 -5C60 E0102; Moji_Joho; MJ010373 -5C60 E0103; Hanyo-Denshi; FT1874 -5C60 E0103; Moji_Joho; MJ010374 -5C61 E0100; Adobe-Japan1; CID+2292 -5C62 E0100; Adobe-Japan1; CID+7693 -5C63 E0100; Adobe-Japan1; CID+14479 -5C64 E0100; Adobe-Japan1; CID+2778 -5C64 E0101; Adobe-Japan1; CID+13361 -5C64 E0102; Hanyo-Denshi; JA3356 -5C64 E0103; Hanyo-Denshi; JC4765 -5C65 E0100; Adobe-Japan1; CID+3940 -5C65 E0101; Hanyo-Denshi; JA4590 -5C65 E0101; Moji_Joho; MJ010380 -5C65 E0102; Hanyo-Denshi; KS088540 -5C65 E0102; Moji_Joho; MJ010379 -5C67 E0100; Adobe-Japan1; CID+17541 -5C68 E0100; Adobe-Japan1; CID+17542 -5C69 E0100; Adobe-Japan1; CID+14480 -5C6C E0100; Adobe-Japan1; CID+4657 -5C6D E0100; Adobe-Japan1; CID+19330 -5C6E E0100; Adobe-Japan1; CID+16837 -5C6E E0101; Adobe-Japan1; CID+4658 -5C6E E0102; Hanyo-Denshi; JA5405 -5C6E E0103; Hanyo-Denshi; JC4766 -5C6F E0100; Adobe-Japan1; CID+3246 -5C6F E0101; Hanyo-Denshi; JA3854 -5C6F E0102; Hanyo-Denshi; TK01024230 -5C70 E0100; Adobe-Japan1; CID+17543 -5C71 E0100; Adobe-Japan1; CID+2177 -5C74 E0100; Adobe-Japan1; CID+21457 -5C75 E0100; Adobe-Japan1; CID+21458 -5C75 E0101; Hanyo-Denshi; JB2704 -5C75 E0102; Hanyo-Denshi; TK01024320 -5C76 E0100; Adobe-Japan1; CID+4660 -5C79 E0100; Adobe-Japan1; CID+4661 -5C7A E0100; Adobe-Japan1; CID+16839 -5C7B E0100; Adobe-Japan1; CID+21459 -5C7C E0100; Adobe-Japan1; CID+14481 -5C7D E0100; Adobe-Japan1; CID+21460 -5C87 E0100; Adobe-Japan1; CID+21461 -5C88 E0100; Adobe-Japan1; CID+17548 -5C88 E0101; Hanyo-Denshi; JB2710 -5C88 E0101; Moji_Joho; MJ010411 -5C88 E0102; Hanyo-Denshi; JTB062 -5C88 E0102; Moji_Joho; MJ010410 -5C8A E0100; Adobe-Japan1; CID+17549 -5C8B E0100; Hanyo-Denshi; IP5C8B -5C8B E0101; Hanyo-Denshi; TK01024480 -5C8C E0100; Adobe-Japan1; CID+4662 -5C8C E0101; Hanyo-Denshi; JA5409 -5C8C E0101; Moji_Joho; MJ010416 -5C8C E0102; Hanyo-Denshi; JTB064 -5C8C E0102; Moji_Joho; MJ010417 -5C8D E0100; Hanyo-Denshi; IP5C8D -5C8D E0100; Moji_Joho; MJ010418 -5C8D E0101; Hanyo-Denshi; JTB06C -5C8D E0101; Moji_Joho; MJ010419 -5C8F E0100; Adobe-Japan1; CID+16840 -5C90 E0100; Adobe-Japan1; CID+1584 -5C91 E0100; Adobe-Japan1; CID+4663 -5C91 E0101; Hanyo-Denshi; JA5410 -5C91 E0101; Moji_Joho; MJ010423 -5C91 E0102; Hanyo-Denshi; JTB067 -5C91 E0102; Moji_Joho; MJ059523 -5C92 E0100; Adobe-Japan1; CID+21462 -5C94 E0100; Adobe-Japan1; CID+4664 -5C94 E0101; Hanyo-Denshi; JA5411 -5C94 E0101; Moji_Joho; MJ010426 -5C94 E0102; Hanyo-Denshi; FT2157 -5C94 E0102; Moji_Joho; MJ010427 -5C9D E0100; Adobe-Japan1; CID+21463 -5C9F E0100; Adobe-Japan1; CID+16841 -5CA0 E0100; Adobe-Japan1; CID+17553 -5CA1 E0100; Adobe-Japan1; CID+1324 -5CA2 E0100; Adobe-Japan1; CID+17554 -5CA3 E0100; Adobe-Japan1; CID+16842 -5CA6 E0100; Adobe-Japan1; CID+8438 -5CA7 E0100; Adobe-Japan1; CID+17555 -5CA8 E0100; Adobe-Japan1; CID+2749 -5CA9 E0100; Adobe-Japan1; CID+1568 -5CA9 E0101; Hanyo-Denshi; JA2068 -5CA9 E0102; Hanyo-Denshi; TK01024930 -5CAA E0100; Adobe-Japan1; CID+16843 -5CAB E0100; Adobe-Japan1; CID+4666 -5CAC E0100; Adobe-Japan1; CID+3764 -5CAD E0100; Adobe-Japan1; CID+17557 -5CB1 E0100; Adobe-Japan1; CID+2866 -5CB2 E0100; Adobe-Japan1; CID+21464 -5CB3 E0100; Adobe-Japan1; CID+1463 -5CB4 E0100; Adobe-Japan1; CID+21465 -5CB5 E0100; Adobe-Japan1; CID+17558 -5CB6 E0100; Adobe-Japan1; CID+4668 -5CB7 E0100; Adobe-Japan1; CID+4670 -5CB8 E0100; Adobe-Japan1; CID+1563 -5CB8 E0101; Hanyo-Denshi; JA2063 -5CB8 E0102; Hanyo-Denshi; TK01024700 -5CBA E0100; Adobe-Japan1; CID+8439 -5CBA E0101; Hanyo-Denshi; JB2724 -5CBA E0102; Hanyo-Denshi; TK01024760 -5CBB E0100; Adobe-Japan1; CID+4667 -5CBB E0101; Hanyo-Denshi; JA5414 -5CBB E0102; Hanyo-Denshi; TK01024840 -5CBC E0100; Adobe-Japan1; CID+4669 -5CBC E0101; Hanyo-Denshi; JA5416 -5CBC E0101; Moji_Joho; MJ010465 -5CBC E0102; Hanyo-Denshi; FT2158 -5CBC E0102; Moji_Joho; MJ010466 -5CBE E0100; Adobe-Japan1; CID+4672 -5CC0 E0100; Moji_Joho; MJ010468 -5CC0 E0101; Moji_Joho; MJ068030 -5CC5 E0100; Adobe-Japan1; CID+4671 -5CC7 E0100; Adobe-Japan1; CID+4673 -5CC9 E0100; Adobe-Japan1; CID+17560 -5CCB E0100; Adobe-Japan1; CID+14482 -5CD0 E0100; Adobe-Japan1; CID+16844 -5CD2 E0100; Adobe-Japan1; CID+14483 -5CD5 E0100; Hanyo-Denshi; TK01024940 -5CD5 E0101; Hanyo-Denshi; TK01024950 -5CD7 E0100; Adobe-Japan1; CID+21466 -5CD9 E0100; Adobe-Japan1; CID+4674 -5CDD E0100; Adobe-Japan1; CID+19331 -5CE0 E0100; Adobe-Japan1; CID+3221 -5CE1 E0100; Adobe-Japan1; CID+1702 -5CE6 E0100; Adobe-Japan1; CID+14124 -5CE8 E0100; Adobe-Japan1; CID+1381 -5CE9 E0100; Adobe-Japan1; CID+4675 -5CEA E0100; Adobe-Japan1; CID+4680 -5CED E0100; Adobe-Japan1; CID+4678 -5CED E0101; Hanyo-Denshi; JA5425 -5CED E0101; Moji_Joho; MJ010506 -5CED E0102; Hanyo-Denshi; FT2160 -5CED E0102; Moji_Joho; MJ010507 -5CEE E0100; Adobe-Japan1; CID+21467 -5CEF E0100; Adobe-Japan1; CID+3655 -5CF0 E0100; Adobe-Japan1; CID+3654 -5CF1 E0100; Adobe-Japan1; CID+21468 -5CF2 E0100; Adobe-Japan1; CID+21469 -5CF4 E0100; Adobe-Japan1; CID+14484 -5CF5 E0100; Adobe-Japan1; CID+8440 -5CF6 E0100; Adobe-Japan1; CID+3169 -5CF6 E0101; Hanyo-Denshi; JA3771 -5CF6 E0102; Hanyo-Denshi; TK01025040 -5CF6 E0103; Hanyo-Denshi; TK01025130 -5CFA E0100; Adobe-Japan1; CID+4677 -5CFA E0101; Moji_Joho; MJ010521 -5CFA E0102; Moji_Joho; MJ010522 -5CFB E0100; Adobe-Japan1; CID+2398 -5CFB E0101; Hanyo-Denshi; JA2952 -5CFB E0101; Moji_Joho; MJ010524 -5CFB E0102; Hanyo-Denshi; KS091970 -5CFB E0102; Moji_Joho; MJ010523 -5CFB E0103; Hanyo-Denshi; TK01024870 -5CFC E0100; Hanyo-Denshi; IP5CFC -5CFC E0101; Hanyo-Denshi; TK01025140 -5CFD E0100; Adobe-Japan1; CID+4676 -5D01 E0100; Adobe-Japan1; CID+19332 -5D06 E0100; Adobe-Japan1; CID+17563 -5D06 E0101; Hanyo-Denshi; JB2735 -5D06 E0101; Moji_Joho; MJ010531 -5D06 E0102; Hanyo-Denshi; KS093320 -5D06 E0102; Moji_Joho; MJ010532 -5D07 E0100; Adobe-Japan1; CID+2616 -5D0B E0100; Adobe-Japan1; CID+4681 -5D0B E0101; Hanyo-Denshi; JA5428 -5D0B E0101; Moji_Joho; MJ010537 -5D0B E0102; Hanyo-Denshi; JTB075 -5D0B E0102; Moji_Joho; MJ010538 -5D0D E0100; Adobe-Japan1; CID+16846 -5D0E E0100; Adobe-Japan1; CID+2138 -5D0E E0101; Hanyo-Denshi; JA2674 -5D0E E0102; Hanyo-Denshi; TK01025460 -5D10 E0100; Adobe-Japan1; CID+17564 -5D11 E0100; Adobe-Japan1; CID+4687 -5D12 E0100; Adobe-Japan1; CID+21470 -5D14 E0100; Adobe-Japan1; CID+4688 -5D15 E0100; Adobe-Japan1; CID+4682 -5D16 E0100; Adobe-Japan1; CID+1425 -5D17 E0100; Adobe-Japan1; CID+4683 -5D18 E0100; Adobe-Japan1; CID+4692 -5D19 E0100; Adobe-Japan1; CID+4691 -5D19 E0101; Hanyo-Denshi; JA5438 -5D19 E0102; Hanyo-Denshi; TK01025070 -5D1A E0100; Adobe-Japan1; CID+4690 -5D1A E0101; Hanyo-Denshi; JA5437 -5D1A E0101; Moji_Joho; MJ010554 -5D1A E0102; Hanyo-Denshi; KS092700 -5D1A E0102; Moji_Joho; MJ010553 -5D1B E0100; Adobe-Japan1; CID+4686 -5D1D E0100; Adobe-Japan1; CID+17566 -5D1D E0101; Hanyo-Denshi; JD0847 -5D1D E0101; Moji_Joho; MJ010557 -5D1D E0102; Hanyo-Denshi; IB0664 -5D1D E0102; Moji_Joho; MJ010558 -5D1F E0100; Adobe-Japan1; CID+4685 -5D20 E0100; Adobe-Japan1; CID+17567 -5D21 E0100; Hanyo-Denshi; IP5D21 -5D21 E0100; Moji_Joho; MJ010562 -5D21 E0101; Hanyo-Denshi; KS093350 -5D21 E0101; Moji_Joho; MJ010563 -5D22 E0100; Adobe-Japan1; CID+4689 -5D22 E0101; Hanyo-Denshi; JA5436 -5D22 E0101; Moji_Joho; MJ010564 -5D22 E0102; Hanyo-Denshi; FT2161 -5D22 E0102; Moji_Joho; MJ010565 -5D23 E0100; Adobe-Japan1; CID+21471 -5D24 E0100; Adobe-Japan1; CID+14485 -5D26 E0100; Adobe-Japan1; CID+14486 -5D27 E0100; Adobe-Japan1; CID+8441 -5D27 E0101; Hanyo-Denshi; JB2742 -5D27 E0101; Moji_Joho; MJ010570 -5D27 E0102; Hanyo-Denshi; IB1731 -5D27 E0102; Moji_Joho; MJ010571 -5D29 E0100; Adobe-Japan1; CID+3656 -5D29 E0101; Adobe-Japan1; CID+14020 -5D29 E0102; Hanyo-Denshi; JA4288 -5D29 E0102; Moji_Joho; MJ010574 -5D29 E0103; Hanyo-Denshi; JTB072 -5D29 E0103; Moji_Joho; MJ010573 -5D2A E0100; Hanyo-Denshi; IP5D2A -5D2A E0100; Moji_Joho; MJ010575 -5D2A E0101; Hanyo-Denshi; KS093290 -5D2A E0101; Moji_Joho; MJ010576 -5D2B E0100; Adobe-Japan1; CID+17565 -5D31 E0100; Adobe-Japan1; CID+17568 -5D34 E0100; Adobe-Japan1; CID+19333 -5D39 E0100; Adobe-Japan1; CID+17569 -5D3D E0100; Adobe-Japan1; CID+19334 -5D3F E0100; Adobe-Japan1; CID+21472 -5D3F E0101; Hanyo-Denshi; JB2747 -5D3F E0101; Moji_Joho; MJ010592 -5D3F E0102; Hanyo-Denshi; KS094200 -5D3F E0102; Moji_Joho; MJ010593 -5D41 E0100; Moji_Joho; MJ010595 -5D41 E0101; Moji_Joho; MJ010596 -5D42 E0100; Adobe-Japan1; CID+8444 -5D43 E0100; Adobe-Japan1; CID+14487 -5D43 E0101; Hanyo-Denshi; JB2749 -5D43 E0102; Hanyo-Denshi; TK01025530 -5D45 E0100; Hanyo-Denshi; IP5D45 -5D45 E0101; Hanyo-Denshi; TK01025280 -5D46 E0100; Adobe-Japan1; CID+14488 -5D46 E0101; Hanyo-Denshi; JB2750 -5D46 E0101; Moji_Joho; MJ010602 -5D46 E0102; Hanyo-Denshi; KS094180 -5D46 E0102; Moji_Joho; MJ057388 -5D47 E0100; Adobe-Japan1; CID+16847 -5D48 E0100; Adobe-Japan1; CID+21473 -5D4A E0100; Adobe-Japan1; CID+14489 -5D4B E0100; Adobe-Japan1; CID+4696 -5D4C E0100; Adobe-Japan1; CID+4693 -5D4E E0100; Adobe-Japan1; CID+4695 -5D4E E0101; Adobe-Japan1; CID+13533 -5D50 E0100; Adobe-Japan1; CID+3932 -5D51 E0100; Adobe-Japan1; CID+21475 -5D52 E0100; Adobe-Japan1; CID+4694 -5D53 E0100; Adobe-Japan1; CID+8442 -5D53 E0101; Hanyo-Denshi; JC4785 -5D53 E0102; Hanyo-Denshi; TK01025050 -5D55 E0100; Adobe-Japan1; CID+21474 -5D59 E0100; Adobe-Japan1; CID+19335 -5D5C E0100; Adobe-Japan1; CID+4684 -5D5F E0100; Adobe-Japan1; CID+21476 -5D60 E0100; Adobe-Japan1; CID+21477 -5D61 E0100; Adobe-Japan1; CID+17571 -5D62 E0100; Adobe-Japan1; CID+21478 -5D64 E0100; Adobe-Japan1; CID+21479 -5D69 E0100; Adobe-Japan1; CID+2617 -5D69 E0101; Hanyo-Denshi; JA3183 -5D69 E0101; Moji_Joho; MJ010633 -5D69 E0102; Hanyo-Denshi; JTB07F -5D69 E0102; Moji_Joho; MJ010634 -5D6A E0100; Adobe-Japan1; CID+17572 -5D6B E0100; Hanyo-Denshi; KS094550 -5D6B E0100; Moji_Joho; MJ010636 -5D6B E0101; Hanyo-Denshi; KS094820 -5D6B E0101; Moji_Joho; MJ010637 -5D6C E0100; Adobe-Japan1; CID+4697 -5D6D E0100; Adobe-Japan1; CID+8445 -5D6E E0100; Hanyo-Denshi; IP5D6E -5D6E E0100; Moji_Joho; MJ010641 -5D6E E0101; Hanyo-Denshi; KS094600 -5D6E E0101; Moji_Joho; MJ010640 -5D6F E0100; Adobe-Japan1; CID+2087 -5D70 E0100; Adobe-Japan1; CID+17574 -5D73 E0100; Adobe-Japan1; CID+4698 -5D76 E0100; Adobe-Japan1; CID+4699 -5D76 E0101; Hanyo-Denshi; JA5446 -5D76 E0101; Moji_Joho; MJ010649 -5D76 E0102; Hanyo-Denshi; FT2162 -5D76 E0102; Moji_Joho; MJ010650 -5D79 E0100; Adobe-Japan1; CID+21480 -5D7A E0100; Adobe-Japan1; CID+21481 -5D7A E0101; Hanyo-Denshi; JB2765 -5D7A E0102; Hanyo-Denshi; TK01025710 -5D7E E0100; Adobe-Japan1; CID+19336 -5D7F E0100; Adobe-Japan1; CID+21482 -5D81 E0100; Adobe-Japan1; CID+16848 -5D82 E0100; Adobe-Japan1; CID+4702 -5D82 E0101; Hanyo-Denshi; JA5449 -5D82 E0101; Moji_Joho; MJ010662 -5D82 E0102; Hanyo-Denshi; KS095500 -5D82 E0102; Moji_Joho; MJ010663 -5D83 E0100; Adobe-Japan1; CID+19337 -5D84 E0100; Adobe-Japan1; CID+4701 -5D87 E0100; Adobe-Japan1; CID+4700 -5D87 E0101; Adobe-Japan1; CID+13534 -5D87 E0102; Hanyo-Denshi; JA5447 -5D87 E0102; Moji_Joho; MJ010668 -5D87 E0103; Hanyo-Denshi; KS095530 -5D87 E0103; Moji_Joho; MJ010669 -5D88 E0100; Adobe-Japan1; CID+17577 -5D8A E0100; Adobe-Japan1; CID+21483 -5D8B E0100; Adobe-Japan1; CID+3170 -5D8C E0100; Adobe-Japan1; CID+4679 -5D90 E0100; Adobe-Japan1; CID+4708 -5D90 E0101; Hanyo-Denshi; JA5455 -5D90 E0101; Moji_Joho; MJ010677 -5D90 E0102; Hanyo-Denshi; FT2163 -5D90 E0102; Moji_Joho; MJ010678 -5D92 E0100; Adobe-Japan1; CID+14490 -5D92 E0101; Hanyo-Denshi; JB2772 -5D92 E0101; Moji_Joho; MJ010680 -5D92 E0102; Hanyo-Denshi; IB1749 -5D92 E0102; Moji_Joho; MJ010681 -5D93 E0100; Adobe-Japan1; CID+21484 -5D94 E0100; Adobe-Japan1; CID+14491 -5D95 E0100; Adobe-Japan1; CID+21485 -5D97 E0100; Adobe-Japan1; CID+17579 -5D99 E0100; Adobe-Japan1; CID+14492 -5D99 E0101; Hanyo-Denshi; JB2776 -5D99 E0101; Moji_Joho; MJ010689 -5D99 E0102; Hanyo-Denshi; KS095860 -5D99 E0102; Moji_Joho; MJ010688 -5D9B E0100; Adobe-Japan1; CID+21486 -5D9D E0100; Adobe-Japan1; CID+4704 -5D9F E0100; Adobe-Japan1; CID+21487 -5DA0 E0100; Adobe-Japan1; CID+14493 -5DA2 E0100; Adobe-Japan1; CID+4703 -5DA4 E0100; Adobe-Japan1; CID+16849 -5DA7 E0100; Adobe-Japan1; CID+16850 -5DAB E0100; Adobe-Japan1; CID+21488 -5DAC E0100; Adobe-Japan1; CID+4705 -5DAE E0100; Adobe-Japan1; CID+4706 -5DB0 E0100; Adobe-Japan1; CID+17580 -5DB2 E0100; Adobe-Japan1; CID+15269 -5DB2 E0101; Adobe-Japan1; CID+15405 -5DB2 E0102; Hanyo-Denshi; JB7084 -5DB2 E0102; Moji_Joho; MJ010714 -5DB2 E0103; Hanyo-Denshi; JD0868 -5DB2 E0103; Moji_Joho; MJ010713 -5DB4 E0100; Adobe-Japan1; CID+17581 -5DB7 E0100; Adobe-Japan1; CID+4709 -5DB8 E0100; Adobe-Japan1; CID+8446 -5DB9 E0100; Adobe-Japan1; CID+8447 -5DBA E0100; Adobe-Japan1; CID+4014 -5DBC E0100; Adobe-Japan1; CID+4710 -5DBD E0100; Adobe-Japan1; CID+4707 -5DC1 E0100; Hanyo-Denshi; IP5DC1 -5DC1 E0100; Moji_Joho; MJ010728 -5DC1 E0101; Hanyo-Denshi; KS097070 -5DC1 E0101; Moji_Joho; MJ010727 -5DC3 E0100; Adobe-Japan1; CID+21489 -5DC3 E0101; Hanyo-Denshi; JB2786 -5DC3 E0101; Moji_Joho; MJ010730 -5DC3 E0102; Hanyo-Denshi; JTB08A -5DC3 E0102; Moji_Joho; MJ010732 -5DC3 E0103; Hanyo-Denshi; KS097360 -5DC3 E0103; Moji_Joho; MJ010731 -5DC7 E0100; Adobe-Japan1; CID+19338 -5DC9 E0100; Adobe-Japan1; CID+4711 -5DC9 E0101; Adobe-Japan1; CID+13535 -5DC9 E0102; Hanyo-Denshi; JA5458 -5DC9 E0102; Moji_Joho; MJ010737 -5DC9 E0103; Hanyo-Denshi; FT1686 -5DC9 E0103; Moji_Joho; MJ010738 -5DCB E0100; Adobe-Japan1; CID+16851 -5DCC E0100; Adobe-Japan1; CID+1564 -5DCC E0101; Adobe-Japan1; CID+13427 -5DCD E0100; Adobe-Japan1; CID+4712 -5DCD E0101; Moji_Joho; MJ010742 -5DCD E0102; Moji_Joho; MJ010743 -5DCD E0103; Moji_Joho; MJ010744 -5DCE E0100; Adobe-Japan1; CID+21490 -5DCE E0101; Hanyo-Denshi; JB2790 -5DCE E0101; Moji_Joho; MJ010746 -5DCE E0102; Hanyo-Denshi; KS097610 -5DCE E0102; Moji_Joho; MJ010745 -5DD0 E0100; Adobe-Japan1; CID+8448 -5DD1 E0100; Adobe-Japan1; CID+17583 -5DD2 E0100; Adobe-Japan1; CID+4714 -5DD3 E0100; Adobe-Japan1; CID+4713 -5DD3 E0101; Adobe-Japan1; CID+13536 -5DD3 E0102; Hanyo-Denshi; JA5460 -5DD3 E0102; Moji_Joho; MJ010751 -5DD3 E0103; Hanyo-Denshi; FT2164 -5DD3 E0103; Moji_Joho; MJ010753 -5DD3 E0104; Moji_Joho; MJ010752 -5DD6 E0100; Adobe-Japan1; CID+4715 -5DD6 E0101; Hanyo-Denshi; JA5462 -5DD6 E0101; Moji_Joho; MJ010754 -5DD6 E0102; Hanyo-Denshi; JTB08CS -5DD6 E0102; Moji_Joho; MJ059537 -5DD6 E0103; Hanyo-Denshi; JTB091 -5DD6 E0103; Moji_Joho; MJ059539 -5DD6 E0104; Hanyo-Denshi; TK01026200 -5DD7 E0100; Adobe-Japan1; CID+17584 -5DD8 E0100; Adobe-Japan1; CID+14494 -5DD9 E0100; Adobe-Japan1; CID+21491 -5DD9 E0101; Hanyo-Denshi; JB2792 -5DD9 E0101; Moji_Joho; MJ010759 -5DD9 E0102; Hanyo-Denshi; KS097790 -5DD9 E0102; Moji_Joho; MJ010757 -5DD9 E0103; Hanyo-Denshi; KS097800 -5DD9 E0103; Moji_Joho; MJ010758 -5DDB E0100; Adobe-Japan1; CID+4716 -5DDD E0100; Adobe-Japan1; CID+2706 -5DDE E0100; Adobe-Japan1; CID+2349 -5DDF E0100; Moji_Joho; MJ034906 -5DDF E0101; Moji_Joho; MJ034907 -5DE0 E0100; Adobe-Japan1; CID+14495 -5DE1 E0100; Adobe-Japan1; CID+2414 -5DE1 E0101; Adobe-Japan1; CID+13823 -5DE1 E0102; Hanyo-Denshi; JA2968 -5DE1 E0102; Moji_Joho; MJ010767 -5DE1 E0103; Hanyo-Denshi; JTBC3A -5DE1 E0103; Moji_Joho; MJ010768 -5DE2 E0100; Adobe-Japan1; CID+13362 -5DE2 E0101; Hanyo-Denshi; JC8408 -5DE2 E0101; Moji_Joho; MJ010769 -5DE2 E0102; Hanyo-Denshi; JTB323 -5DE2 E0102; Moji_Joho; MJ057404 -5DE2 E0103; Hanyo-Denshi; KS098470 -5DE2 E0103; Moji_Joho; MJ010770 -5DE3 E0100; Adobe-Japan1; CID+2789 -5DE4 E0100; Adobe-Japan1; CID+17586 -5DE5 E0100; Adobe-Japan1; CID+1979 -5DE5 E0101; Adobe-Japan1; CID+13763 -5DE5 E0102; Hanyo-Denshi; JA2509 -5DE5 E0103; Hanyo-Denshi; TK01001100 -5DE6 E0100; Adobe-Japan1; CID+2088 -5DE6 E0101; Hanyo-Denshi; JA2624 -5DE6 E0101; Moji_Joho; MJ010774 -5DE6 E0102; Hanyo-Denshi; IB0665 -5DE6 E0102; Moji_Joho; MJ057406 -5DE7 E0100; Adobe-Japan1; CID+1980 -5DE8 E0100; Adobe-Japan1; CID+1674 -5DE8 E0101; Adobe-Japan1; CID+13714 -5DE8 E0102; Hanyo-Denshi; JA2180 -5DE8 E0102; Moji_Joho; MJ010777 -5DE8 E0103; Hanyo-Denshi; KS098730 -5DE8 E0103; Moji_Joho; MJ010776 -5DE9 E0100; Adobe-Japan1; CID+17587 -5DE9 E0101; Hanyo-Denshi; JB2801 -5DE9 E0101; Moji_Joho; MJ010778 -5DE9 E0102; Hanyo-Denshi; KS098790 -5DE9 E0102; Moji_Joho; MJ010779 -5DEB E0100; Adobe-Japan1; CID+4717 -5DEE E0100; Adobe-Japan1; CID+2089 -5DF1 E0100; Adobe-Japan1; CID+1918 -5DF1 E0101; Hanyo-Denshi; JA2442 -5DF1 E0102; Hanyo-Denshi; TK01026530 -5DF1 E0103; Hanyo-Denshi; TK01026540 -5DF2 E0100; Adobe-Japan1; CID+4718 -5DF3 E0100; Adobe-Japan1; CID+3762 -5DF4 E0100; Adobe-Japan1; CID+3321 -5DF5 E0100; Adobe-Japan1; CID+4719 -5DF7 E0100; Adobe-Japan1; CID+1981 -5DF7 E0101; Adobe-Japan1; CID+7679 -5DF7 E0102; Hanyo-Denshi; JA2511 -5DF7 E0102; Moji_Joho; MJ010790 -5DF7 E0103; Hanyo-Denshi; FT1801 -5DF7 E0103; Moji_Joho; MJ010789 -5DF7 E0104; Hanyo-Denshi; TK01012430 -5DF8 E0100; Adobe-Japan1; CID+14496 -5DF8 E0101; Hanyo-Denshi; JB2802 -5DF8 E0101; Moji_Joho; MJ010791 -5DF8 E0102; Hanyo-Denshi; JTB09A -5DF8 E0102; Moji_Joho; MJ010792 -5DF8 E0103; Hanyo-Denshi; JTB09C -5DF8 E0103; Moji_Joho; MJ010794 -5DF9 E0100; Adobe-Japan1; CID+19339 -5DFB E0100; Adobe-Japan1; CID+1512 -5DFB E0101; Hanyo-Denshi; JA2012 -5DFB E0101; Moji_Joho; MJ010798 -5DFB E0102; Hanyo-Denshi; JTB099S -5DFB E0102; Moji_Joho; MJ059540 -5DFB E0103; Hanyo-Denshi; JTB098 -5DFB E0103; Moji_Joho; MJ010799 -5DFB E0104; Hanyo-Denshi; TK01026710 -5DFD E0100; Adobe-Japan1; CID+7734 -5DFD E0101; Adobe-Japan1; CID+2917 -5DFD E0102; Hanyo-Denshi; JA3507 -5DFD E0102; Moji_Joho; MJ010801 -5DFD E0103; Hanyo-Denshi; FT1854 -5DFD E0103; Moji_Joho; MJ010800 -5DFD E0104; Moji_Joho; MJ010802 -5DFE E0100; Adobe-Japan1; CID+1738 -5DFF E0100; Adobe-Japan1; CID+13794 -5E00 E0100; Adobe-Japan1; CID+14497 -5E02 E0100; Adobe-Japan1; CID+2210 -5E03 E0100; Adobe-Japan1; CID+3533 -5E06 E0100; Adobe-Japan1; CID+3413 -5E06 E0101; Adobe-Japan1; CID+13987 -5E07 E0100; Adobe-Japan1; CID+21492 -5E09 E0100; Hanyo-Denshi; IP5E09 -5E09 E0101; Hanyo-Denshi; TK01026890 -5E0B E0100; Adobe-Japan1; CID+4720 -5E0C E0100; Adobe-Japan1; CID+1585 -5E0C E0101; Hanyo-Denshi; JA2085 -5E0C E0101; Moji_Joho; MJ010817 -5E0C E0102; Hanyo-Denshi; KS100080 -5E0C E0102; Moji_Joho; MJ057418 -5E0D E0100; Adobe-Japan1; CID+21493 -5E11 E0100; Adobe-Japan1; CID+4723 -5E12 E0100; Adobe-Japan1; CID+14498 -5E13 E0100; Hanyo-Denshi; JT5E13 -5E13 E0100; Moji_Joho; MJ010822 -5E13 E0101; Hanyo-Denshi; JTB0A4 -5E13 E0101; Moji_Joho; MJ010823 -5E14 E0100; Adobe-Japan1; CID+14499 -5E15 E0100; Adobe-Japan1; CID+14500 -5E16 E0100; Adobe-Japan1; CID+3005 -5E18 E0100; Adobe-Japan1; CID+14501 -5E19 E0100; Adobe-Japan1; CID+4722 -5E1A E0100; Adobe-Japan1; CID+4721 -5E1A E0101; Hanyo-Denshi; JA5468 -5E1A E0101; Moji_Joho; MJ010830 -5E1A E0102; Hanyo-Denshi; FT2165 -5E1A E0102; Moji_Joho; MJ010831 -5E1B E0100; Adobe-Japan1; CID+4724 -5E1D E0100; Adobe-Japan1; CID+3079 -5E1D E0101; Adobe-Japan1; CID+13943 -5E1D E0102; Hanyo-Denshi; JA3675 -5E1D E0102; Moji_Joho; MJ010833 -5E1D E0103; Hanyo-Denshi; JTB0A8 -5E1D E0103; Moji_Joho; MJ010834 -5E1F E0100; Adobe-Japan1; CID+17591 -5E20 E0100; Adobe-Japan1; CID+21494 -5E23 E0100; Hanyo-Denshi; IP5E23 -5E23 E0100; Moji_Joho; MJ010840 -5E23 E0101; Hanyo-Denshi; JT5E23 -5E23 E0101; Moji_Joho; MJ010841 -5E25 E0100; Adobe-Japan1; CID+2601 -5E28 E0100; Adobe-Japan1; CID+19340 -5E28 E0101; Hanyo-Denshi; JB2814 -5E28 E0101; Moji_Joho; MJ010844 -5E28 E0102; Hanyo-Denshi; JTB0AC -5E28 E0102; Moji_Joho; MJ010845 -5E2B E0100; Adobe-Japan1; CID+2211 -5E2B E0101; Hanyo-Denshi; JA2753 -5E2B E0101; Moji_Joho; MJ010848 -5E2B E0102; Hanyo-Denshi; KS100790 -5E2B E0102; Moji_Joho; MJ057421 -5E2B E0103; Moji_Joho; MJ057420 -5E2B E0104; Moji_Joho; MJ057424 -5E2D E0100; Adobe-Japan1; CID+2670 -5E2E E0100; Adobe-Japan1; CID+14502 -5E2E E0101; Hanyo-Denshi; JB2813 -5E2E E0101; Moji_Joho; MJ010852 -5E2E E0102; Hanyo-Denshi; JTB0AD -5E2E E0102; Moji_Joho; MJ010853 -5E2F E0100; Adobe-Japan1; CID+2867 -5E2F E0101; Moji_Joho; MJ010854 -5E2F E0102; Moji_Joho; MJ057426 -5E30 E0100; Adobe-Japan1; CID+1596 -5E30 E0101; Adobe-Japan1; CID+13429 -5E30 E0102; Hanyo-Denshi; JA2102 -5E30 E0102; Moji_Joho; MJ010855 -5E30 E0103; Hanyo-Denshi; JTB0A9 -5E30 E0103; Moji_Joho; MJ010856 -5E30 E0104; Hanyo-Denshi; FT1615 -5E30 E0104; Moji_Joho; MJ010857 -5E32 E0100; Adobe-Japan1; CID+19341 -5E33 E0100; Adobe-Japan1; CID+3006 -5E35 E0100; Adobe-Japan1; CID+19342 -5E36 E0100; Adobe-Japan1; CID+4725 -5E37 E0100; Adobe-Japan1; CID+4726 -5E38 E0100; Adobe-Japan1; CID+2519 -5E3D E0100; Adobe-Japan1; CID+3687 -5E3D E0101; Adobe-Japan1; CID+14032 -5E3D E0102; Hanyo-Denshi; JA4325 -5E3D E0102; Moji_Joho; MJ010868 -5E3D E0103; Hanyo-Denshi; JTB0B1 -5E3D E0103; Moji_Joho; MJ010867 -5E3E E0100; Adobe-Japan1; CID+17592 -5E3E E0101; Hanyo-Denshi; JB2817 -5E3E E0101; Moji_Joho; MJ010869 -5E3E E0102; Hanyo-Denshi; IB1767 -5E3E E0102; Moji_Joho; MJ010870 -5E40 E0100; Adobe-Japan1; CID+4729 -5E42 E0100; Hanyo-Denshi; KS019080 -5E42 E0100; Moji_Joho; MJ010874 -5E42 E0101; Hanyo-Denshi; KS101990 -5E42 E0101; Moji_Joho; MJ010875 -5E43 E0100; Adobe-Japan1; CID+4728 -5E43 E0101; Adobe-Japan1; CID+20113 -5E43 E0102; Hanyo-Denshi; JA5475 -5E43 E0102; Moji_Joho; MJ010876 -5E43 E0103; Hanyo-Denshi; FT2166S -5E43 E0103; Moji_Joho; MJ010877 -5E43 E0104; Moji_Joho; MJ010878 -5E44 E0100; Adobe-Japan1; CID+4727 -5E45 E0100; Adobe-Japan1; CID+3567 -5E47 E0100; Adobe-Japan1; CID+4736 -5E49 E0100; Adobe-Japan1; CID+17593 -5E4B E0100; Adobe-Japan1; CID+21495 -5E4C E0100; Adobe-Japan1; CID+3720 -5E4E E0100; Adobe-Japan1; CID+4730 -5E50 E0100; Adobe-Japan1; CID+21496 -5E51 E0100; Adobe-Japan1; CID+21497 -5E54 E0100; Adobe-Japan1; CID+4732 -5E54 E0101; Adobe-Japan1; CID+14125 -5E54 E0102; Hanyo-Denshi; JA5479 -5E54 E0102; Moji_Joho; MJ010896 -5E54 E0103; Hanyo-Denshi; JTB0B7 -5E54 E0103; Moji_Joho; MJ010895 -5E55 E0100; Adobe-Japan1; CID+3737 -5E55 E0101; Hanyo-Denshi; JA4375 -5E55 E0101; Moji_Joho; MJ010897 -5E55 E0102; Hanyo-Denshi; KS102450 -5E55 E0102; Moji_Joho; MJ010898 -5E56 E0100; Adobe-Japan1; CID+17595 -5E57 E0100; Adobe-Japan1; CID+4731 -5E58 E0100; Adobe-Japan1; CID+14503 -5E59 E0100; Hanyo-Denshi; IP5E59 -5E59 E0100; Moji_Joho; MJ010903 -5E59 E0101; Hanyo-Denshi; KS102460 -5E59 E0101; Moji_Joho; MJ010902 -5E5B E0100; Adobe-Japan1; CID+19343 -5E5B E0101; Hanyo-Denshi; JB2824 -5E5B E0101; Moji_Joho; MJ010905 -5E5B E0102; Hanyo-Denshi; KS102630 -5E5B E0102; Moji_Joho; MJ010906 -5E5C E0100; Adobe-Japan1; CID+21498 -5E5E E0100; Adobe-Japan1; CID+16852 -5E5F E0100; Adobe-Japan1; CID+4733 -5E5F E0101; Hanyo-Denshi; JA5480 -5E5F E0101; Moji_Joho; MJ010910 -5E5F E0102; Hanyo-Denshi; KS102950 -5E5F E0102; Moji_Joho; MJ010911 -5E61 E0100; Adobe-Japan1; CID+3388 -5E62 E0100; Adobe-Japan1; CID+4734 -5E62 E0101; Hanyo-Denshi; JA5481 -5E62 E0101; Moji_Joho; MJ010914 -5E62 E0102; Hanyo-Denshi; KS102960 -5E62 E0102; Moji_Joho; MJ010915 -5E63 E0100; Adobe-Japan1; CID+3598 -5E63 E0101; Adobe-Japan1; CID+14010 -5E63 E0102; Hanyo-Denshi; JA4230 -5E63 E0102; Moji_Joho; MJ010917 -5E63 E0103; Hanyo-Denshi; JTB0B8S -5E63 E0103; Moji_Joho; MJ010916 -5E64 E0100; Adobe-Japan1; CID+4735 -5E64 E0101; Adobe-Japan1; CID+7827 -5E64 E0102; Hanyo-Denshi; JA5482 -5E64 E0102; Moji_Joho; MJ010918 -5E64 E0103; Hanyo-Denshi; FT2167 -5E64 E0103; Moji_Joho; MJ010919 -5E64 E0104; Hanyo-Denshi; JTB0BA -5E64 E0104; Moji_Joho; MJ059550 -5E68 E0100; Adobe-Japan1; CID+19344 -5E69 E0100; Hanyo-Denshi; IP5E69 -5E69 E0100; Moji_Joho; MJ010924 -5E69 E0101; Hanyo-Denshi; KS103080 -5E69 E0101; Moji_Joho; MJ010923 -5E6A E0100; Adobe-Japan1; CID+19345 -5E6A E0101; Hanyo-Denshi; JB2828 -5E6A E0101; Moji_Joho; MJ010926 -5E6A E0102; Hanyo-Denshi; IB1772 -5E6A E0102; Moji_Joho; MJ010927 -5E6A E0103; Hanyo-Denshi; KS103240 -5E6A E0103; Moji_Joho; MJ010925 -5E6B E0100; Adobe-Japan1; CID+14504 -5E6C E0100; Adobe-Japan1; CID+14505 -5E6D E0100; Adobe-Japan1; CID+17597 -5E6D E0101; Hanyo-Denshi; JB2831 -5E6D E0101; Moji_Joho; MJ010932 -5E6D E0102; Hanyo-Denshi; KS103400 -5E6D E0102; Moji_Joho; MJ010931 -5E6D E0103; Hanyo-Denshi; KS103340 -5E6D E0103; Moji_Joho; MJ010930 -5E6D E0104; Hanyo-Denshi; IB1773 -5E6D E0104; Moji_Joho; MJ010933 -5E6E E0100; Adobe-Japan1; CID+17598 -5E6F E0100; Hanyo-Denshi; IP5E6F -5E6F E0100; Moji_Joho; MJ010935 -5E6F E0101; Hanyo-Denshi; JT5E6F -5E6F E0101; Moji_Joho; MJ010936 -5E6F E0102; Hanyo-Denshi; TK01027310 -5E70 E0100; Adobe-Japan1; CID+21499 -5E70 E0101; Hanyo-Denshi; JB2833 -5E70 E0101; Moji_Joho; MJ010938 -5E70 E0102; Hanyo-Denshi; KS103490 -5E70 E0102; Moji_Joho; MJ010939 -5E72 E0100; Adobe-Japan1; CID+1519 -5E73 E0100; Adobe-Japan1; CID+3599 -5E73 E0101; Adobe-Japan1; CID+14011 -5E73 E0102; Hanyo-Denshi; JA4231 -5E73 E0102; Moji_Joho; MJ010943 -5E73 E0103; Hanyo-Denshi; JTB0BF -5E73 E0103; Moji_Joho; MJ010942 -5E74 E0100; Adobe-Japan1; CID+3301 -5E74 E0101; Hanyo-Denshi; JA3915 -5E74 E0101; Moji_Joho; MJ010944 -5E74 E0102; Hanyo-Denshi; IB0671 -5E74 E0102; Moji_Joho; MJ010945 -5E75 E0100; Adobe-Japan1; CID+4737 -5E75 E0101; Hanyo-Denshi; JA5484 -5E75 E0101; Moji_Joho; MJ010946 -5E75 E0102; Hanyo-Denshi; JTB0C2 -5E75 E0102; Moji_Joho; MJ010947 -5E75 E0103; Moji_Joho; MJ010948 -5E76 E0100; Adobe-Japan1; CID+4738 -5E77 E0100; Adobe-Japan1; CID+19346 -5E78 E0100; Adobe-Japan1; CID+1982 -5E78 E0101; Hanyo-Denshi; JA2512 -5E78 E0101; Moji_Joho; MJ010951 -5E78 E0102; Hanyo-Denshi; IB0672 -5E78 E0102; Moji_Joho; MJ057432 -5E79 E0100; Adobe-Japan1; CID+1520 -5E7A E0100; Adobe-Japan1; CID+4739 -5E7B E0100; Adobe-Japan1; CID+1900 -5E7C E0100; Adobe-Japan1; CID+3886 -5E7D E0100; Adobe-Japan1; CID+3859 -5E7E E0100; Adobe-Japan1; CID+1586 -5E7E E0101; Adobe-Japan1; CID+13700 -5E7E E0102; Hanyo-Denshi; JA2086 -5E7E E0102; Moji_Joho; MJ010958 -5E7E E0103; Hanyo-Denshi; KS104230 -5E7E E0103; Moji_Joho; MJ057436 -5E7E E0104; Hanyo-Denshi; KS104260 -5E7E E0104; Moji_Joho; MJ057437 -5E7F E0100; Adobe-Japan1; CID+4741 -5E80 E0100; Adobe-Japan1; CID+19347 -5E81 E0100; Adobe-Japan1; CID+3007 -5E83 E0100; Adobe-Japan1; CID+1983 -5E84 E0100; Adobe-Japan1; CID+2457 -5E87 E0100; Adobe-Japan1; CID+3443 -5E8A E0100; Adobe-Japan1; CID+2458 -5E8B E0100; Adobe-Japan1; CID+19348 -5E8E E0100; Adobe-Japan1; CID+21500 -5E8F E0100; Adobe-Japan1; CID+2434 -5E92 E0100; Hanyo-Denshi; JT5E92 -5E92 E0101; Hanyo-Denshi; TK01027600 -5E95 E0100; Adobe-Japan1; CID+3080 -5E95 E0101; Hanyo-Denshi; JA3676 -5E95 E0101; Moji_Joho; MJ010979 -5E95 E0102; Hanyo-Denshi; KS105410 -5E95 E0102; Moji_Joho; MJ057440 -5E96 E0100; Adobe-Japan1; CID+3657 -5E96 E0101; Adobe-Japan1; CID+7792 -5E96 E0102; Hanyo-Denshi; JA4289 -5E96 E0102; Moji_Joho; MJ010981 -5E96 E0103; Hanyo-Denshi; FT1919 -5E96 E0103; Moji_Joho; MJ010980 -5E97 E0100; Adobe-Japan1; CID+3123 -5E99 E0100; Adobe-Japan1; CID+14000 -5E9A E0100; Adobe-Japan1; CID+1984 -5E9C E0100; Adobe-Japan1; CID+3534 -5EA0 E0100; Adobe-Japan1; CID+4742 -5EA2 E0100; Adobe-Japan1; CID+21501 -5EA4 E0100; Adobe-Japan1; CID+21502 -5EA5 E0100; Adobe-Japan1; CID+17600 -5EA6 E0100; Adobe-Japan1; CID+3155 -5EA6 E0101; Hanyo-Denshi; JA3757 -5EA6 E0101; Moji_Joho; MJ010996 -5EA6 E0102; Hanyo-Denshi; KS105400 -5EA6 E0102; Moji_Joho; MJ057439 -5EA7 E0100; Adobe-Japan1; CID+2098 -5EA7 E0101; Adobe-Japan1; CID+20114 -5EA8 E0100; Adobe-Japan1; CID+14506 -5EAA E0100; Adobe-Japan1; CID+14507 -5EAB E0100; Adobe-Japan1; CID+1919 -5EAC E0100; Adobe-Japan1; CID+17601 -5EAC E0101; Hanyo-Denshi; JB2842 -5EAC E0101; Moji_Joho; MJ011002 -5EAC E0102; Hanyo-Denshi; IB1780 -5EAC E0102; Moji_Joho; MJ011003 -5EAC E0103; Hanyo-Denshi; JTB0CC -5EAC E0103; Moji_Joho; MJ011004 -5EAD E0100; Adobe-Japan1; CID+3081 -5EAD E0101; Adobe-Japan1; CID+13481 -5EAD E0102; Hanyo-Denshi; JA3677 -5EAD E0102; Moji_Joho; MJ011006 -5EAD E0103; Hanyo-Denshi; KS105720 -5EAD E0103; Moji_Joho; MJ057441 -5EAD E0104; Moji_Joho; MJ011005 -5EB1 E0100; Adobe-Japan1; CID+21503 -5EB3 E0100; Adobe-Japan1; CID+19349 -5EB3 E0101; Hanyo-Denshi; JB2844 -5EB3 E0101; Moji_Joho; MJ011012 -5EB3 E0102; Hanyo-Denshi; KS105730 -5EB3 E0102; Moji_Joho; MJ057442 -5EB5 E0100; Adobe-Japan1; CID+1159 -5EB6 E0100; Adobe-Japan1; CID+2424 -5EB6 E0101; Hanyo-Denshi; JA2978 -5EB6 E0101; Moji_Joho; MJ011015 -5EB6 E0102; Hanyo-Denshi; KS106260S -5EB6 E0102; Moji_Joho; MJ057448 -5EB7 E0100; Adobe-Japan1; CID+1985 -5EB7 E0101; Hanyo-Denshi; JA2515 -5EB7 E0101; Moji_Joho; MJ011017 -5EB7 E0102; Hanyo-Denshi; IB0676 -5EB7 E0102; Moji_Joho; MJ011016 -5EB8 E0100; Adobe-Japan1; CID+3889 -5EB8 E0101; Hanyo-Denshi; JA4539 -5EB8 E0101; Moji_Joho; MJ011018 -5EB8 E0102; Hanyo-Denshi; JTB0D8 -5EB8 E0102; Moji_Joho; MJ059558 -5EB8 E0103; Hanyo-Denshi; TK01028040 -5EB9 E0100; Adobe-Japan1; CID+17602 -5EB9 E0101; Hanyo-Denshi; JD1206 -5EB9 E0101; Moji_Joho; MJ011020 -5EB9 E0102; Hanyo-Denshi; KS106060 -5EB9 E0102; Moji_Joho; MJ011019 -5EBB E0100; Hanyo-Denshi; IB0674 -5EBB E0100; Moji_Joho; MJ011023 -5EBB E0101; Hanyo-Denshi; KS106210 -5EBB E0101; Moji_Joho; MJ011022 -5EBD E0100; Adobe-Japan1; CID+19350 -5EBE E0100; Adobe-Japan1; CID+14508 -5EBE E0101; Hanyo-Denshi; JB2846 -5EBE E0101; Moji_Joho; MJ011025 -5EBE E0102; Hanyo-Denshi; KS106330 -5EBE E0102; Moji_Joho; MJ011026 -5EBF E0100; Adobe-Japan1; CID+14509 -5EBF E0101; Hanyo-Denshi; JB2847 -5EBF E0101; Moji_Joho; MJ011027 -5EBF E0102; Hanyo-Denshi; KS106350 -5EBF E0102; Moji_Joho; MJ011028 -5EC1 E0100; Adobe-Japan1; CID+4743 -5EC2 E0100; Adobe-Japan1; CID+4744 -5EC3 E0100; Adobe-Japan1; CID+3335 -5EC6 E0100; Adobe-Japan1; CID+17603 -5EC8 E0100; Adobe-Japan1; CID+4745 -5EC9 E0100; Adobe-Japan1; CID+14095 -5EC9 E0101; Adobe-Japan1; CID+4031 -5EC9 E0102; Hanyo-Denshi; JA4687 -5EC9 E0102; Moji_Joho; MJ011039 -5EC9 E0103; Hanyo-Denshi; JTB0D9 -5EC9 E0103; Moji_Joho; MJ011038 -5ECA E0100; Adobe-Japan1; CID+4051 -5ECA E0101; Adobe-Japan1; CID+20303 -5ECA E0102; Adobe-Japan1; CID+13401 -5ECA E0103; Hanyo-Denshi; JA4713 -5ECA E0104; Hanyo-Denshi; JC8414 -5ECB E0100; Adobe-Japan1; CID+15390 -5ECB E0101; Adobe-Japan1; CID+14510 -5ECB E0102; Hanyo-Denshi; JB2850 -5ECB E0102; Moji_Joho; MJ011041 -5ECB E0103; Hanyo-Denshi; JC8415 -5ECB E0103; Moji_Joho; MJ011042 -5ECC E0100; Adobe-Japan1; CID+21504 -5ECE E0100; Adobe-Japan1; CID+21505 -5ECF E0100; Adobe-Japan1; CID+4747 -5ECF E0101; Adobe-Japan1; CID+7990 -5ECF E0102; Hanyo-Denshi; JA5494 -5ECF E0102; Moji_Joho; MJ011045 -5ECF E0103; Hanyo-Denshi; JTB0E0 -5ECF E0103; Moji_Joho; MJ011046 -5ED0 E0100; Adobe-Japan1; CID+4746 -5ED0 E0101; Adobe-Japan1; CID+7989 -5ED0 E0102; Hanyo-Denshi; JA5493 -5ED0 E0102; Moji_Joho; MJ011047 -5ED0 E0103; Hanyo-Denshi; KS107150S -5ED0 E0103; Moji_Joho; MJ011048 -5ED0 E0104; Hanyo-Denshi; IB0677 -5ED0 E0104; Moji_Joho; MJ011051 -5ED0 E0105; Hanyo-Denshi; FT2169 -5ED0 E0105; Moji_Joho; MJ011049 -5ED0 E0106; Hanyo-Denshi; JTB0DF -5ED0 E0106; Moji_Joho; MJ011050 -5ED0 E0107; Hanyo-Denshi; JTB0EES -5ED0 E0107; Moji_Joho; MJ011052 -5ED1 E0100; Adobe-Japan1; CID+19351 -5ED1 E0101; Hanyo-Denshi; JB2852 -5ED1 E0102; Hanyo-Denshi; TK01028100 -5ED2 E0100; Adobe-Japan1; CID+14511 -5ED3 E0100; Adobe-Japan1; CID+1445 -5ED4 E0100; Adobe-Japan1; CID+19352 -5ED5 E0100; Adobe-Japan1; CID+19353 -5ED6 E0100; Adobe-Japan1; CID+4748 -5ED6 E0101; Hanyo-Denshi; JA5501 -5ED6 E0101; Moji_Joho; MJ011058 -5ED6 E0102; Hanyo-Denshi; FT2171 -5ED6 E0102; Moji_Joho; MJ011059 -5ED9 E0100; Adobe-Japan1; CID+17604 -5ED9 E0101; Hanyo-Denshi; JD1210 -5ED9 E0101; Moji_Joho; MJ011062 -5ED9 E0102; Hanyo-Denshi; KS107200 -5ED9 E0102; Moji_Joho; MJ011063 -5EDA E0100; Adobe-Japan1; CID+4751 -5EDB E0100; Adobe-Japan1; CID+4752 -5EDC E0100; Adobe-Japan1; CID+21506 -5EDD E0100; Adobe-Japan1; CID+4750 -5EDE E0100; Adobe-Japan1; CID+21507 -5EDF E0100; Adobe-Japan1; CID+3506 -5EDF E0101; Adobe-Japan1; CID+7786 -5EDF E0102; Hanyo-Denshi; JA4132 -5EDF E0102; Moji_Joho; MJ011070 -5EDF E0103; Hanyo-Denshi; FT1913 -5EDF E0103; Moji_Joho; MJ011069 -5EE0 E0100; Adobe-Japan1; CID+2459 -5EE0 E0101; Adobe-Japan1; CID+7704 -5EE0 E0102; Hanyo-Denshi; JA3019 -5EE0 E0102; Moji_Joho; MJ011072 -5EE0 E0103; Hanyo-Denshi; FT1825S -5EE0 E0103; Moji_Joho; MJ011071 -5EE1 E0100; Adobe-Japan1; CID+4754 -5EE2 E0100; Adobe-Japan1; CID+4753 -5EE3 E0100; Adobe-Japan1; CID+4749 -5EE3 E0101; Adobe-Japan1; CID+14127 -5EE3 E0102; Adobe-Japan1; CID+20115 -5EE3 E0103; Hanyo-Denshi; JA5502 -5EE3 E0103; Moji_Joho; MJ011077 -5EE3 E0104; Hanyo-Denshi; JTB0E2 -5EE3 E0104; Moji_Joho; MJ011075 -5EE3 E0105; Hanyo-Denshi; JTB0E1S -5EE3 E0105; Moji_Joho; MJ011076 -5EE3 E0106; Hanyo-Denshi; TK01028170 -5EE3 E0107; Hanyo-Denshi; TK01028180 -5EE3 E0108; Hanyo-Denshi; TK01028240 -5EE3 E0109; Hanyo-Denshi; TK01028310 -5EE3 E010A; Hanyo-Denshi; TK01028320 -5EE3 E010B; Hanyo-Denshi; TK01028340 -5EE3 E010C; Moji_Joho; MJ011078 -5EE5 E0100; Adobe-Japan1; CID+21508 -5EE8 E0100; Adobe-Japan1; CID+4755 -5EE9 E0100; Adobe-Japan1; CID+4756 -5EEB E0100; Adobe-Japan1; CID+21509 -5EEC E0100; Adobe-Japan1; CID+4757 -5EF0 E0100; Adobe-Japan1; CID+4760 -5EF1 E0100; Adobe-Japan1; CID+4758 -5EF3 E0100; Adobe-Japan1; CID+4759 -5EF4 E0100; Adobe-Japan1; CID+4761 -5EF4 E0101; Moji_Joho; MJ011098 -5EF4 E0102; Moji_Joho; MJ011099 -5EF6 E0100; Adobe-Japan1; CID+1286 -5EF6 E0101; Adobe-Japan1; CID+13415 -5EF6 E0102; Adobe-Japan1; CID+13654 -5EF6 E0103; Hanyo-Denshi; JA1768 -5EF6 E0103; Moji_Joho; MJ011101 -5EF6 E0104; Hanyo-Denshi; IB0312SS -5EF6 E0104; Moji_Joho; MJ011102 -5EF6 E0105; Moji_Joho; MJ011100 -5EF7 E0100; Adobe-Japan1; CID+3082 -5EF7 E0101; Adobe-Japan1; CID+13482 -5EF7 E0102; Hanyo-Denshi; JA3678 -5EF7 E0102; Moji_Joho; MJ011104 -5EF7 E0103; Hanyo-Denshi; KS108170 -5EF7 E0103; Moji_Joho; MJ011103 -5EF7 E0104; Moji_Joho; MJ011105 -5EF8 E0100; Adobe-Japan1; CID+4762 -5EF8 E0101; Moji_Joho; MJ011106 -5EF8 E0102; Moji_Joho; MJ011107 -5EF9 E0100; Adobe-Japan1; CID+16853 -5EF9 E0101; Moji_Joho; MJ011108 -5EF9 E0102; Moji_Joho; MJ011109 -5EFA E0100; Adobe-Japan1; CID+1872 -5EFA E0101; Adobe-Japan1; CID+13436 -5EFA E0102; Hanyo-Denshi; JA2390 -5EFA E0102; Moji_Joho; MJ011111 -5EFA E0103; Hanyo-Denshi; KS108330 -5EFA E0103; Moji_Joho; MJ011112 -5EFA E0104; Moji_Joho; MJ011110 -5EFB E0100; Adobe-Japan1; CID+1398 -5EFB E0101; Adobe-Japan1; CID+13673 -5EFB E0102; Moji_Joho; MJ011113 -5EFB E0103; Moji_Joho; MJ011114 -5EFC E0100; Adobe-Japan1; CID+3308 -5EFC E0101; Moji_Joho; MJ011115 -5EFC E0102; Moji_Joho; MJ011116 -5EFC E0103; Moji_Joho; MJ011117 -5EFD E0100; Adobe-Japan1; CID+17606 -5EFD E0101; Moji_Joho; MJ011118 -5EFD E0102; Moji_Joho; MJ011119 -5EFE E0100; Adobe-Japan1; CID+4763 -5EFE E0101; Hanyo-Denshi; JA5516 -5EFE E0101; Moji_Joho; MJ011120 -5EFE E0102; Hanyo-Denshi; KS108410 -5EFE E0102; Moji_Joho; MJ011121 -5EFF E0100; Adobe-Japan1; CID+3283 -5F00 E0100; Adobe-Japan1; CID+16854 -5F01 E0100; Adobe-Japan1; CID+3627 -5F01 E0101; Hanyo-Denshi; JA4259 -5F01 E0102; Hanyo-Denshi; TK01028970 -5F01 E0103; Hanyo-Denshi; TK01028980S -5F02 E0100; Adobe-Japan1; CID+16855 -5F02 E0101; Hanyo-Denshi; JB2860 -5F02 E0101; Moji_Joho; MJ011125 -5F02 E0102; Hanyo-Denshi; KS108510 -5F02 E0102; Moji_Joho; MJ011126 -5F03 E0100; Adobe-Japan1; CID+4764 -5F04 E0100; Adobe-Japan1; CID+4052 -5F06 E0100; Adobe-Japan1; CID+21510 -5F07 E0100; Adobe-Japan1; CID+14512 -5F08 E0100; Adobe-Japan1; CID+17607 -5F09 E0100; Adobe-Japan1; CID+4765 -5F09 E0101; Hanyo-Denshi; JA5518 -5F09 E0101; Moji_Joho; MJ011133 -5F09 E0102; Hanyo-Denshi; FT2175 -5F09 E0102; Moji_Joho; MJ011134 -5F09 E0103; Hanyo-Denshi; TK01029040 -5F0A E0100; Adobe-Japan1; CID+3600 -5F0A E0101; Adobe-Japan1; CID+14012 -5F0A E0102; Hanyo-Denshi; JA4232 -5F0A E0102; Moji_Joho; MJ011137 -5F0A E0103; Hanyo-Denshi; JTB101S -5F0A E0103; Moji_Joho; MJ011136 -5F0B E0100; Adobe-Japan1; CID+4768 -5F0C E0100; Adobe-Japan1; CID+4090 -5F0D E0100; Adobe-Japan1; CID+4106 -5F0D E0101; Hanyo-Denshi; JA4817 -5F0D E0101; Moji_Joho; MJ011140 -5F0D E0102; Hanyo-Denshi; JTB103 -5F0D E0102; Moji_Joho; MJ011141 -5F0D E0103; Hanyo-Denshi; TK01034530 -5F0E E0100; Adobe-Japan1; CID+14513 -5F0E E0101; Hanyo-Denshi; JB2864 -5F0E E0101; Moji_Joho; MJ011143 -5F0E E0102; Hanyo-Denshi; IB1803 -5F0E E0102; Moji_Joho; MJ011144 -5F0F E0100; Adobe-Japan1; CID+2268 -5F10 E0100; Adobe-Japan1; CID+3277 -5F11 E0100; Adobe-Japan1; CID+4769 -5F13 E0100; Adobe-Japan1; CID+1655 -5F13 E0101; Hanyo-Denshi; JA2161 -5F13 E0101; Moji_Joho; MJ011149 -5F13 E0102; Hanyo-Denshi; KS109620 -5F13 E0102; Moji_Joho; MJ057459 -5F14 E0100; Adobe-Japan1; CID+3008 -5F14 E0101; Hanyo-Denshi; JA3604 -5F14 E0101; Moji_Joho; MJ011150 -5F14 E0102; Hanyo-Denshi; KS152810 -5F14 E0102; Moji_Joho; MJ057631 -5F15 E0100; Adobe-Japan1; CID+1214 -5F15 E0101; Hanyo-Denshi; JA1690 -5F15 E0102; Hanyo-Denshi; TK01029270 -5F16 E0100; Adobe-Japan1; CID+4770 -5F16 E0101; Hanyo-Denshi; JA5523 -5F16 E0101; Moji_Joho; MJ011153 -5F16 E0102; Hanyo-Denshi; KS109740 -5F16 E0102; Moji_Joho; MJ011154 -5F17 E0100; Adobe-Japan1; CID+3574 -5F17 E0101; Hanyo-Denshi; JA4206 -5F17 E0102; Hanyo-Denshi; KS152860 -5F18 E0100; Adobe-Japan1; CID+1986 -5F18 E0101; Hanyo-Denshi; JA2516 -5F18 E0102; Hanyo-Denshi; TK01013130 -5F19 E0100; Adobe-Japan1; CID+21511 -5F1B E0100; Adobe-Japan1; CID+2958 -5F1C E0100; Adobe-Japan1; CID+14514 -5F1D E0100; Adobe-Japan1; CID+14515 -5F1E E0100; Adobe-Japan1; CID+17609 -5F1F E0100; Adobe-Japan1; CID+3083 -5F1F E0101; Hanyo-Denshi; JA3679 -5F1F E0102; Hanyo-Denshi; TK01007340 -5F20 E0100; Hanyo-Denshi; TK01029340 -5F20 E0101; Hanyo-Denshi; TK01029550 -5F21 E0100; Adobe-Japan1; CID+8449 -5F21 E0101; Hanyo-Denshi; JB2868 -5F21 E0101; Moji_Joho; MJ011167 -5F21 E0102; Hanyo-Denshi; IB1806 -5F21 E0102; Moji_Joho; MJ011168 -5F22 E0100; Adobe-Japan1; CID+14516 -5F22 E0101; Hanyo-Denshi; JB2869 -5F22 E0101; Moji_Joho; MJ011169 -5F22 E0102; Hanyo-Denshi; KS110360 -5F22 E0102; Moji_Joho; MJ011170 -5F23 E0100; Adobe-Japan1; CID+16856 -5F24 E0100; Adobe-Japan1; CID+21512 -5F25 E0100; Adobe-Japan1; CID+3835 -5F25 E0101; Hanyo-Denshi; JA4479 -5F25 E0102; Hanyo-Denshi; TK01029400 -5F25 E0103; Hanyo-Denshi; TK01029460 -5F25 E0104; Hanyo-Denshi; TK01029470 -5F26 E0100; Adobe-Japan1; CID+1901 -5F27 E0100; Adobe-Japan1; CID+1920 -5F27 E0101; Hanyo-Denshi; JA2444 -5F27 E0101; Moji_Joho; MJ011178 -5F27 E0102; Hanyo-Denshi; KS110370 -5F27 E0102; Moji_Joho; MJ011177 -5F28 E0100; Adobe-Japan1; CID+14517 -5F29 E0100; Adobe-Japan1; CID+4771 -5F29 E0101; Moji_Joho; MJ011180 -5F29 E0102; Moji_Joho; MJ011181 -5F2B E0100; Adobe-Japan1; CID+21513 -5F2C E0100; Adobe-Japan1; CID+21514 -5F2D E0100; Adobe-Japan1; CID+4772 -5F2D E0101; Adobe-Japan1; CID+13537 -5F2D E0102; Moji_Joho; MJ011184 -5F2D E0103; Moji_Joho; MJ011185 -5F2E E0100; Adobe-Japan1; CID+21515 -5F2E E0101; Hanyo-Denshi; JB2875 -5F2E E0102; Hanyo-Denshi; TK01029480 -5F2F E0100; Adobe-Japan1; CID+4778 -5F30 E0100; Adobe-Japan1; CID+21516 -5F31 E0100; Adobe-Japan1; CID+2321 -5F31 E0101; Adobe-Japan1; CID+13811 -5F31 E0102; Hanyo-Denshi; JA2869 -5F31 E0102; Moji_Joho; MJ011191 -5F31 E0103; Hanyo-Denshi; JTB10E -5F31 E0103; Moji_Joho; MJ011190 -5F34 E0100; Adobe-Japan1; CID+8450 -5F35 E0100; Adobe-Japan1; CID+3009 -5F36 E0100; Adobe-Japan1; CID+14518 -5F37 E0100; Adobe-Japan1; CID+1703 -5F38 E0100; Adobe-Japan1; CID+4773 -5F38 E0101; Adobe-Japan1; CID+20116 -5F38 E0102; Hanyo-Denshi; JA5526 -5F38 E0102; Moji_Joho; MJ011198 -5F38 E0103; Hanyo-Denshi; JTB112 -5F38 E0103; Moji_Joho; MJ011197 -5F3A E0100; Adobe-Japan1; CID+13720 -5F3B E0100; Adobe-Japan1; CID+14519 -5F3C E0100; Adobe-Japan1; CID+3485 -5F3D E0100; Adobe-Japan1; CID+16857 -5F3E E0100; Adobe-Japan1; CID+2948 -5F3F E0100; Adobe-Japan1; CID+21517 -5F40 E0100; Adobe-Japan1; CID+14520 -5F41 E0100; Adobe-Japan1; CID+4774 -5F44 E0100; Adobe-Japan1; CID+21518 -5F44 E0101; Hanyo-Denshi; JB2883 -5F44 E0101; Moji_Joho; MJ011208 -5F44 E0102; Hanyo-Denshi; KS111550 -5F44 E0102; Moji_Joho; MJ011209 -5F45 E0100; Adobe-Japan1; CID+8370 -5F45 E0101; Adobe-Japan1; CID+14286 -5F45 E0102; Hanyo-Denshi; JB2884 -5F45 E0102; Moji_Joho; MJ011210 -5F45 E0103; Hanyo-Denshi; IB1818 -5F45 E0103; Moji_Joho; MJ011211 -5F45 E0104; Hanyo-Denshi; JTB11C -5F45 E0104; Moji_Joho; MJ059583 -5F45 E0105; Hanyo-Denshi; TK01029840 -5F45 E0106; Hanyo-Denshi; TK01029860 -5F47 E0100; Adobe-Japan1; CID+17610 -5F48 E0100; Adobe-Japan1; CID+4775 -5F48 E0101; Hanyo-Denshi; JA5528 -5F48 E0102; Hanyo-Denshi; TK01029820 -5F4A E0100; Adobe-Japan1; CID+1704 -5F4C E0100; Adobe-Japan1; CID+4776 -5F4C E0101; Hanyo-Denshi; JA5529 -5F4C E0101; Moji_Joho; MJ011219 -5F4C E0102; Hanyo-Denshi; JTB11D -5F4C E0102; Moji_Joho; MJ011220 -5F4C E0103; Hanyo-Denshi; JTB11E -5F4C E0103; Moji_Joho; MJ011221 -5F4D E0100; Adobe-Japan1; CID+19354 -5F4E E0100; Adobe-Japan1; CID+4777 -5F50 E0100; Adobe-Japan1; CID+14521 -5F50 E0101; Adobe-Japan1; CID+15391 -5F50 E0102; Hanyo-Denshi; JB2887 -5F50 E0102; Moji_Joho; MJ011225 -5F50 E0103; Hanyo-Denshi; JTB120 -5F50 E0103; Moji_Joho; MJ011226 -5F50 E0104; Hanyo-Denshi; KS112010 -5F50 E0104; Moji_Joho; MJ011227 -5F51 E0100; Adobe-Japan1; CID+4779 -5F53 E0100; Adobe-Japan1; CID+3184 -5F54 E0100; Adobe-Japan1; CID+16858 -5F55 E0100; Hanyo-Denshi; JT5F55 -5F55 E0100; Moji_Joho; MJ011232 -5F55 E0101; Hanyo-Denshi; KS112100 -5F55 E0101; Moji_Joho; MJ057475 -5F56 E0100; Adobe-Japan1; CID+4780 -5F56 E0101; Hanyo-Denshi; JA5533 -5F56 E0101; Moji_Joho; MJ011233 -5F56 E0102; Hanyo-Denshi; KS112230 -5F56 E0102; Moji_Joho; MJ011234 -5F56 E0103; Hanyo-Denshi; FT2177 -5F56 E0103; Moji_Joho; MJ011235 -5F57 E0100; Adobe-Japan1; CID+4781 -5F57 E0101; Hanyo-Denshi; JA5534 -5F57 E0101; Moji_Joho; MJ011236 -5F57 E0102; Hanyo-Denshi; FT2178 -5F57 E0102; Moji_Joho; MJ011237 -5F57 E0103; Moji_Joho; MJ057478 -5F58 E0100; Adobe-Japan1; CID+14522 -5F59 E0100; Adobe-Japan1; CID+4782 -5F5A E0100; Hanyo-Denshi; IP5F5A -5F5A E0100; Moji_Joho; MJ011240 -5F5A E0101; Hanyo-Denshi; JTB124 -5F5A E0101; Moji_Joho; MJ059586 -5F5A E0102; Hanyo-Denshi; KS112430 -5F5A E0102; Moji_Joho; MJ057480 -5F5A E0103; Hanyo-Denshi; TK01030070 -5F5B E0100; Adobe-Japan1; CID+21519 -5F5C E0100; Adobe-Japan1; CID+4767 -5F5C E0101; Hanyo-Denshi; JA5520 -5F5C E0101; Moji_Joho; MJ011243 -5F5C E0102; Hanyo-Denshi; FT2176 -5F5C E0102; Moji_Joho; MJ011244 -5F5D E0100; Adobe-Japan1; CID+4766 -5F5E E0100; Hanyo-Denshi; JT5F5E -5F5E E0101; Hanyo-Denshi; TK01030130 -5F60 E0100; Adobe-Japan1; CID+21520 -5F60 E0101; Hanyo-Denshi; JB2891 -5F60 E0101; Moji_Joho; MJ011249 -5F60 E0102; Hanyo-Denshi; KS112690 -5F60 E0102; Moji_Joho; MJ011248 -5F60 E0103; Hanyo-Denshi; TK01030170 -5F61 E0100; Adobe-Japan1; CID+4783 -5F62 E0100; Adobe-Japan1; CID+1815 -5F62 E0101; Adobe-Japan1; CID+20063 -5F62 E0102; Hanyo-Denshi; JA2333 -5F62 E0102; Moji_Joho; MJ011253 -5F62 E0103; Hanyo-Denshi; KS112900 -5F62 E0103; Moji_Joho; MJ011254 -5F63 E0100; Adobe-Japan1; CID+17611 -5F64 E0100; Adobe-Japan1; CID+14523 -5F65 E0100; Adobe-Japan1; CID+13996 -5F66 E0100; Adobe-Japan1; CID+3481 -5F67 E0100; Adobe-Japan1; CID+8451 -5F67 E0101; Hanyo-Denshi; JB2894 -5F67 E0102; Hanyo-Denshi; TK01030210 -5F69 E0100; Adobe-Japan1; CID+2108 -5F69 E0101; Adobe-Japan1; CID+13783 -5F69 E0102; Hanyo-Denshi; JA2644 -5F69 E0102; Moji_Joho; MJ011261 -5F69 E0103; Hanyo-Denshi; JTB125 -5F69 E0103; Moji_Joho; MJ011260 -5F6A E0100; Adobe-Japan1; CID+3497 -5F6A E0101; Hanyo-Denshi; JA4123 -5F6A E0101; Moji_Joho; MJ011262 -5F6A E0102; Hanyo-Denshi; JTB127 -5F6A E0102; Moji_Joho; MJ011263 -5F6A E0103; Hanyo-Denshi; TK01030260 -5F6B E0100; Adobe-Japan1; CID+3010 -5F6B E0101; Adobe-Japan1; CID+13928 -5F6B E0102; Hanyo-Denshi; JA3606 -5F6B E0102; Moji_Joho; MJ011267 -5F6B E0103; Hanyo-Denshi; JTB126 -5F6B E0103; Moji_Joho; MJ011266 -5F6C E0100; Adobe-Japan1; CID+3517 -5F6D E0100; Adobe-Japan1; CID+4784 -5F6F E0100; Adobe-Japan1; CID+21521 -5F70 E0100; Adobe-Japan1; CID+2460 -5F70 E0101; Hanyo-Denshi; JA3020 -5F70 E0101; Moji_Joho; MJ011272 -5F70 E0102; Hanyo-Denshi; JTB12A -5F70 E0102; Moji_Joho; MJ011273 -5F71 E0100; Adobe-Japan1; CID+1256 -5F72 E0100; Adobe-Japan1; CID+17612 -5F73 E0100; Adobe-Japan1; CID+4785 -5F74 E0100; Adobe-Japan1; CID+21522 -5F74 E0101; Hanyo-Denshi; JB2903 -5F74 E0101; Moji_Joho; MJ011277 -5F74 E0102; Hanyo-Denshi; JTB12D -5F74 E0102; Moji_Joho; MJ011278 -5F75 E0100; Adobe-Japan1; CID+21523 -5F77 E0100; Adobe-Japan1; CID+4786 -5F78 E0100; Adobe-Japan1; CID+21524 -5F79 E0100; Adobe-Japan1; CID+3838 -5F7A E0100; Adobe-Japan1; CID+21525 -5F7C E0100; Adobe-Japan1; CID+3444 -5F7D E0100; Adobe-Japan1; CID+16859 -5F7E E0100; Adobe-Japan1; CID+17613 -5F7F E0100; Adobe-Japan1; CID+4789 -5F80 E0100; Adobe-Japan1; CID+1311 -5F80 E0101; Adobe-Japan1; CID+13661 -5F80 E0102; Hanyo-Denshi; JA1793 -5F80 E0102; Moji_Joho; MJ011289 -5F80 E0103; Hanyo-Denshi; JTB12F -5F80 E0103; Moji_Joho; MJ011290 -5F81 E0100; Adobe-Japan1; CID+2640 -5F82 E0100; Adobe-Japan1; CID+4788 -5F83 E0100; Adobe-Japan1; CID+4787 -5F84 E0100; Adobe-Japan1; CID+1816 -5F85 E0100; Adobe-Japan1; CID+2868 -5F86 E0100; Hanyo-Denshi; IP5F86 -5F86 E0101; Hanyo-Denshi; TK01030590 -5F87 E0100; Adobe-Japan1; CID+4793 -5F88 E0100; Adobe-Japan1; CID+4791 -5F89 E0100; Adobe-Japan1; CID+14524 -5F8A E0100; Adobe-Japan1; CID+4790 -5F8B E0100; Adobe-Japan1; CID+3951 -5F8B E0101; Hanyo-Denshi; JA4607 -5F8B E0102; Hanyo-Denshi; TK01030740 -5F8C E0100; Adobe-Japan1; CID+1945 -5F8C E0101; Hanyo-Denshi; JA2469 -5F8C E0101; Moji_Joho; MJ011303 -5F8C E0102; Hanyo-Denshi; KS114130 -5F8C E0102; Moji_Joho; MJ011302 -5F8D E0100; Adobe-Japan1; CID+21526 -5F8F E0100; Adobe-Japan1; CID+17614 -5F8F E0101; Hanyo-Denshi; JB2911 -5F8F E0101; Moji_Joho; MJ011306 -5F8F E0102; Hanyo-Denshi; IB1837 -5F8F E0102; Moji_Joho; MJ011307 -5F90 E0100; Adobe-Japan1; CID+2435 -5F90 E0101; Hanyo-Denshi; JA2989 -5F90 E0102; Hanyo-Denshi; TK01030780 -5F91 E0100; Adobe-Japan1; CID+4792 -5F91 E0101; Hanyo-Denshi; JA5545 -5F91 E0102; Hanyo-Denshi; TK01030770 -5F92 E0100; Adobe-Japan1; CID+3142 -5F93 E0100; Adobe-Japan1; CID+2376 -5F96 E0100; Adobe-Japan1; CID+21527 -5F97 E0100; Adobe-Japan1; CID+3224 -5F98 E0100; Adobe-Japan1; CID+4796 -5F98 E0101; Adobe-Japan1; CID+13538 -5F98 E0102; Moji_Joho; MJ011315 -5F98 E0103; Moji_Joho; MJ011316 -5F99 E0100; Adobe-Japan1; CID+4795 -5F9C E0100; Adobe-Japan1; CID+14525 -5F9D E0100; Adobe-Japan1; CID+21528 -5F9E E0100; Adobe-Japan1; CID+4794 -5F9E E0101; Hanyo-Denshi; JA5547 -5F9E E0101; Moji_Joho; MJ011321 -5F9E E0102; Hanyo-Denshi; JTB13A -5F9E E0102; Moji_Joho; MJ059595 -5FA0 E0100; Adobe-Japan1; CID+4797 -5FA1 E0100; Adobe-Japan1; CID+1946 -5FA1 E0101; Adobe-Japan1; CID+20117 -5FA1 E0102; Hanyo-Denshi; JA2470 -5FA1 E0103; Hanyo-Denshi; IB0680 -5FA1 E0103; Moji_Joho; MJ011325 -5FA1 E0104; Hanyo-Denshi; KS115360 -5FA1 E0104; Moji_Joho; MJ057489 -5FA2 E0100; Adobe-Japan1; CID+17615 -5FA4 E0100; Adobe-Japan1; CID+14527 -5FA4 E0101; Moji_Joho; MJ011329 -5FA4 E0102; Moji_Joho; MJ011330 -5FA7 E0100; Adobe-Japan1; CID+14526 -5FA8 E0100; Adobe-Japan1; CID+4798 -5FA9 E0100; Adobe-Japan1; CID+3566 -5FAA E0100; Adobe-Japan1; CID+2405 -5FAB E0100; Adobe-Japan1; CID+21529 -5FAB E0101; Hanyo-Denshi; JB2917 -5FAB E0101; Moji_Joho; MJ011338 -5FAB E0102; Hanyo-Denshi; JTB139 -5FAB E0102; Moji_Joho; MJ011337 -5FAC E0100; Adobe-Japan1; CID+19355 -5FAC E0101; Hanyo-Denshi; JB2919 -5FAC E0101; Moji_Joho; MJ011339 -5FAC E0102; Hanyo-Denshi; KS115370 -5FAC E0102; Moji_Joho; MJ011340 -5FAD E0100; Adobe-Japan1; CID+4799 -5FAE E0100; Adobe-Japan1; CID+3469 -5FAE E0101; Adobe-Japan1; CID+13992 -5FAE E0102; Hanyo-Denshi; JA4089 -5FAE E0102; Moji_Joho; MJ011343 -5FAE E0103; Hanyo-Denshi; JTB13C -5FAE E0103; Moji_Joho; MJ011345 -5FAE E0104; Hanyo-Denshi; KS115640 -5FAE E0104; Moji_Joho; MJ011344 -5FAE E0105; Moji_Joho; MJ011342 -5FAF E0100; Adobe-Japan1; CID+14528 -5FB0 E0100; Adobe-Japan1; CID+21530 -5FB1 E0100; Adobe-Japan1; CID+21531 -5FB2 E0100; Hanyo-Denshi; IP5FB2 -5FB2 E0100; Moji_Joho; MJ011350 -5FB2 E0101; Hanyo-Denshi; KS115430 -5FB2 E0101; Moji_Joho; MJ011349 -5FB3 E0100; Adobe-Japan1; CID+3225 -5FB4 E0100; Adobe-Japan1; CID+3011 -5FB5 E0100; Adobe-Japan1; CID+13368 -5FB5 E0101; Adobe-Japan1; CID+13929 -5FB5 E0102; Hanyo-Denshi; JC8436 -5FB5 E0102; Moji_Joho; MJ011354 -5FB5 E0103; Hanyo-Denshi; IP5FB5S -5FB5 E0103; Moji_Joho; MJ011353 -5FB7 E0100; Adobe-Japan1; CID+8452 -5FB7 E0101; Hanyo-Denshi; JC8437 -5FB7 E0101; Moji_Joho; MJ011356 -5FB7 E0102; Hanyo-Denshi; FT2836 -5FB7 E0102; Moji_Joho; MJ011357 -5FB8 E0100; Adobe-Japan1; CID+14529 -5FB9 E0100; Adobe-Japan1; CID+3114 -5FBC E0100; Adobe-Japan1; CID+4800 -5FBD E0100; Adobe-Japan1; CID+1605 -5FBD E0101; Adobe-Japan1; CID+7658 -5FBD E0102; Hanyo-Denshi; JA2111 -5FBD E0102; Moji_Joho; MJ011362 -5FBD E0103; Hanyo-Denshi; FT1775 -5FBD E0103; Moji_Joho; MJ011363 -5FBF E0100; Hanyo-Denshi; IP5FBF -5FBF E0101; Hanyo-Denshi; TK01031350 -5FC3 E0100; Adobe-Japan1; CID+2554 -5FC4 E0100; Adobe-Japan1; CID+14530 -5FC5 E0100; Adobe-Japan1; CID+3486 -5FC7 E0100; Adobe-Japan1; CID+17616 -5FC8 E0100; Adobe-Japan1; CID+21532 -5FC9 E0100; Adobe-Japan1; CID+14531 -5FCB E0100; Adobe-Japan1; CID+17617 -5FCC E0100; Adobe-Japan1; CID+1587 -5FCD E0100; Adobe-Japan1; CID+3292 -5FCD E0101; Adobe-Japan1; CID+13969 -5FCD E0102; Hanyo-Denshi; JA3906 -5FCD E0102; Moji_Joho; MJ011379 -5FCD E0103; Hanyo-Denshi; KS117300 -5FCD E0103; Moji_Joho; MJ011380 -5FCD E0104; Hanyo-Denshi; JTB149 -5FCD E0104; Moji_Joho; MJ011378 -5FD0 E0100; Adobe-Japan1; CID+21533 -5FD1 E0100; Adobe-Japan1; CID+21534 -5FD2 E0100; Adobe-Japan1; CID+17618 -5FD3 E0100; Adobe-Japan1; CID+17619 -5FD4 E0100; Adobe-Japan1; CID+17620 -5FD6 E0100; Adobe-Japan1; CID+4801 -5FD7 E0100; Adobe-Japan1; CID+2212 -5FD8 E0100; Adobe-Japan1; CID+3688 -5FD8 E0101; Adobe-Japan1; CID+14033 -5FD8 E0102; Hanyo-Denshi; JA4326 -5FD8 E0102; Moji_Joho; MJ011393 -5FD8 E0103; Hanyo-Denshi; KS116710 -5FD8 E0103; Moji_Joho; MJ011392 -5FD9 E0100; Adobe-Japan1; CID+3689 -5FD9 E0101; Adobe-Japan1; CID+14034 -5FD9 E0102; Hanyo-Denshi; JA4327 -5FD9 E0102; Moji_Joho; MJ011395 -5FD9 E0103; Hanyo-Denshi; KS116510 -5FD9 E0103; Moji_Joho; MJ011394 -5FDC E0100; Adobe-Japan1; CID+1312 -5FDD E0100; Adobe-Japan1; CID+4806 -5FDD E0101; Adobe-Japan1; CID+20118 -5FDE E0100; Adobe-Japan1; CID+8453 -5FDE E0101; Moji_Joho; MJ011400 -5FDE E0102; Moji_Joho; MJ011401 -5FDF E0100; Moji_Joho; MJ011402 -5FDF E0101; Moji_Joho; MJ011403 -5FE0 E0100; Adobe-Japan1; CID+2983 -5FE1 E0100; Adobe-Japan1; CID+14532 -5FE2 E0100; Adobe-Japan1; CID+17621 -5FE3 E0100; Hanyo-Denshi; IP5FE3 -5FE3 E0101; Hanyo-Denshi; TK01031390 -5FE4 E0100; Adobe-Japan1; CID+4803 -5FE8 E0100; Adobe-Japan1; CID+21535 -5FE9 E0100; Adobe-Japan1; CID+14533 -5FEA E0100; Adobe-Japan1; CID+19356 -5FEB E0100; Adobe-Japan1; CID+1399 -5FEC E0100; Adobe-Japan1; CID+21536 -5FED E0100; Adobe-Japan1; CID+14534 -5FED E0101; Hanyo-Denshi; JB2941 -5FED E0101; Moji_Joho; MJ011418 -5FED E0102; Hanyo-Denshi; KS117290 -5FED E0102; Moji_Joho; MJ011419 -5FEE E0100; Adobe-Japan1; CID+17622 -5FEF E0100; Adobe-Japan1; CID+17623 -5FF0 E0100; Adobe-Japan1; CID+4854 -5FF0 E0101; Moji_Joho; MJ011422 -5FF0 E0102; Moji_Joho; MJ011423 -5FF1 E0100; Adobe-Japan1; CID+4805 -5FF2 E0100; Adobe-Japan1; CID+21537 -5FF3 E0100; Adobe-Japan1; CID+17624 -5FF5 E0100; Adobe-Japan1; CID+3302 -5FF6 E0100; Adobe-Japan1; CID+21538 -5FF8 E0100; Adobe-Japan1; CID+4804 -5FFA E0100; Adobe-Japan1; CID+21539 -5FFB E0100; Adobe-Japan1; CID+4802 -5FFC E0100; Adobe-Japan1; CID+14535 -5FFD E0100; Adobe-Japan1; CID+2060 -5FFF E0100; Adobe-Japan1; CID+4808 -5FFF E0101; Hanyo-Denshi; JA5561 -5FFF E0101; Moji_Joho; MJ011438 -5FFF E0102; Hanyo-Denshi; FT2179 -5FFF E0102; Moji_Joho; MJ011439 -6007 E0100; Adobe-Japan1; CID+19357 -600A E0100; Adobe-Japan1; CID+21540 -600D E0100; Adobe-Japan1; CID+16860 -600E E0100; Adobe-Japan1; CID+4814 -600F E0100; Adobe-Japan1; CID+4820 -6010 E0100; Adobe-Japan1; CID+4812 -6012 E0100; Adobe-Japan1; CID+3158 -6013 E0100; Adobe-Japan1; CID+21541 -6014 E0100; Adobe-Japan1; CID+16861 -6015 E0100; Adobe-Japan1; CID+4817 -6016 E0100; Adobe-Japan1; CID+3535 -6017 E0100; Adobe-Japan1; CID+14536 -6018 E0100; Adobe-Japan1; CID+16862 -6019 E0100; Adobe-Japan1; CID+4811 -601A E0100; Adobe-Japan1; CID+14537 -601B E0100; Adobe-Japan1; CID+4816 -601C E0100; Adobe-Japan1; CID+4015 -601C E0101; Hanyo-Denshi; JA4671 -601C E0102; Hanyo-Denshi; TK01031550 -601D E0100; Adobe-Japan1; CID+2213 -601F E0100; Adobe-Japan1; CID+21542 -6020 E0100; Adobe-Japan1; CID+2869 -6021 E0100; Adobe-Japan1; CID+4809 -6022 E0100; Adobe-Japan1; CID+17626 -6024 E0100; Adobe-Japan1; CID+17627 -6025 E0100; Adobe-Japan1; CID+1656 -6025 E0101; Adobe-Japan1; CID+13712 -6025 E0102; Hanyo-Denshi; JA2162 -6025 E0102; Moji_Joho; MJ011473 -6025 E0103; Hanyo-Denshi; JTB158 -6025 E0103; Moji_Joho; MJ011472 -6026 E0100; Adobe-Japan1; CID+4819 -6026 E0101; Hanyo-Denshi; JA5572 -6026 E0101; Moji_Joho; MJ011475 -6026 E0102; Hanyo-Denshi; FT2180 -6026 E0102; Moji_Joho; MJ011476 -6027 E0100; Adobe-Japan1; CID+2641 -6028 E0100; Adobe-Japan1; CID+1287 -6029 E0100; Adobe-Japan1; CID+4813 -602A E0100; Adobe-Japan1; CID+1400 -602B E0100; Adobe-Japan1; CID+4818 -602D E0100; Adobe-Japan1; CID+21543 -602F E0100; Adobe-Japan1; CID+1705 -6031 E0100; Adobe-Japan1; CID+4815 -6033 E0100; Adobe-Japan1; CID+14538 -6035 E0100; Adobe-Japan1; CID+16863 -6038 E0100; Hanyo-Denshi; IP6038 -6038 E0101; Hanyo-Denshi; TK01031690 -603A E0100; Adobe-Japan1; CID+4821 -6040 E0100; Adobe-Japan1; CID+21544 -6041 E0100; Adobe-Japan1; CID+4823 -6042 E0100; Adobe-Japan1; CID+4833 -6043 E0100; Adobe-Japan1; CID+4831 -6044 E0100; Hanyo-Denshi; IP6044 -6044 E0101; Hanyo-Denshi; TK01031670 -6046 E0100; Adobe-Japan1; CID+4828 -6047 E0100; Adobe-Japan1; CID+16864 -6048 E0100; Adobe-Japan1; CID+21545 -6049 E0100; Adobe-Japan1; CID+19358 -604A E0100; Adobe-Japan1; CID+4827 -604A E0101; Hanyo-Denshi; JA5580 -604A E0101; Moji_Joho; MJ011509 -604A E0102; Hanyo-Denshi; JTC0E5 -604A E0102; Moji_Joho; MJ057097 -604B E0100; Adobe-Japan1; CID+4032 -604C E0100; Adobe-Japan1; CID+17629 -604D E0100; Adobe-Japan1; CID+4829 -6050 E0100; Adobe-Japan1; CID+1706 -6050 E0101; Adobe-Japan1; CID+13721 -6050 E0102; Hanyo-Denshi; JA2218 -6050 E0102; Moji_Joho; MJ011515 -6050 E0103; Hanyo-Denshi; KS120450 -6050 E0103; Moji_Joho; MJ057504 -6050 E0104; Hanyo-Denshi; TK01031760 -6051 E0100; Adobe-Japan1; CID+21546 -6052 E0100; Adobe-Japan1; CID+1987 -6054 E0100; Adobe-Japan1; CID+19359 -6054 E0101; Moji_Joho; MJ011519 -6054 E0102; Moji_Joho; MJ011520 -6055 E0100; Adobe-Japan1; CID+2436 -6056 E0100; Adobe-Japan1; CID+21547 -6057 E0100; Adobe-Japan1; CID+21548 -6059 E0100; Adobe-Japan1; CID+4836 -605A E0100; Adobe-Japan1; CID+4822 -605D E0100; Adobe-Japan1; CID+8454 -605D E0101; Hanyo-Denshi; JB2971 -605D E0101; Moji_Joho; MJ011530 -605D E0102; Hanyo-Denshi; IB1855 -605D E0102; Moji_Joho; MJ011532 -605D E0103; Hanyo-Denshi; KS120460 -605D E0103; Moji_Joho; MJ011531 -605F E0100; Adobe-Japan1; CID+4826 -6060 E0100; Adobe-Japan1; CID+4810 -6061 E0100; Adobe-Japan1; CID+14539 -6062 E0100; Adobe-Japan1; CID+1402 -6062 E0101; Adobe-Japan1; CID+7648 -6062 E0102; Adobe-Japan1; CID+20269 -6062 E0103; Hanyo-Denshi; JA1890 -6062 E0103; Moji_Joho; MJ011538 -6062 E0104; Hanyo-Denshi; HG1608 -6062 E0104; Moji_Joho; MJ011537 -6062 E0105; Hanyo-Denshi; FT1765 -6062 E0105; Moji_Joho; MJ011539 -6063 E0100; Adobe-Japan1; CID+4830 -6064 E0100; Adobe-Japan1; CID+4832 -6065 E0100; Adobe-Japan1; CID+2959 -6065 E0101; Adobe-Japan1; CID+13476 -6065 E0102; Moji_Joho; MJ011542 -6065 E0103; Moji_Joho; MJ011543 -6067 E0100; Adobe-Japan1; CID+19360 -6068 E0100; Adobe-Japan1; CID+2072 -6069 E0100; Adobe-Japan1; CID+1336 -606A E0100; Adobe-Japan1; CID+4824 -606B E0100; Adobe-Japan1; CID+4835 -606C E0100; Adobe-Japan1; CID+4834 -606D E0100; Adobe-Japan1; CID+1707 -606F E0100; Adobe-Japan1; CID+2825 -6070 E0100; Adobe-Japan1; CID+1476 -6071 E0100; Adobe-Japan1; CID+21549 -6071 E0101; Hanyo-Denshi; JB2974 -6071 E0101; Moji_Joho; MJ011555 -6071 E0102; Hanyo-Denshi; JTB15B -6071 E0102; Moji_Joho; MJ011556 -6071 E0103; Hanyo-Denshi; TK01031600 -6075 E0100; Adobe-Japan1; CID+1817 -6075 E0101; Adobe-Japan1; CID+13740 -6075 E0102; Hanyo-Denshi; JA2335 -6075 E0103; Hanyo-Denshi; JTB16C -6077 E0100; Adobe-Japan1; CID+4825 -607E E0100; Adobe-Japan1; CID+21550 -607E E0101; Hanyo-Denshi; JB2975 -607E E0101; Moji_Joho; MJ011563 -607E E0102; Hanyo-Denshi; KS119760 -607E E0102; Moji_Joho; MJ011564 -607E E0103; Hanyo-Denshi; KS120500 -607E E0103; Moji_Joho; MJ011565 -607F E0100; Adobe-Japan1; CID+14540 -607F E0101; Hanyo-Denshi; JB2976 -607F E0102; Hanyo-Denshi; TK01032240 -6081 E0100; Adobe-Japan1; CID+4837 -6081 E0101; Hanyo-Denshi; JA5590 -6081 E0101; Moji_Joho; MJ011569 -6081 E0102; Hanyo-Denshi; KS118740 -6081 E0102; Moji_Joho; MJ011568 -6082 E0100; Adobe-Japan1; CID+21551 -6083 E0100; Adobe-Japan1; CID+4840 -6084 E0100; Adobe-Japan1; CID+4842 -6084 E0101; Hanyo-Denshi; JA5601 -6084 E0101; Moji_Joho; MJ011572 -6084 E0102; Hanyo-Denshi; FT2182 -6084 E0102; Moji_Joho; MJ011573 -6085 E0100; Adobe-Japan1; CID+8455 -6086 E0100; Adobe-Japan1; CID+21552 -6088 E0100; Adobe-Japan1; CID+21553 -6089 E0100; Adobe-Japan1; CID+2281 -608A E0100; Adobe-Japan1; CID+8456 -608B E0100; Adobe-Japan1; CID+4848 -608B E0101; Moji_Joho; MJ011580 -608B E0102; Moji_Joho; MJ011581 -608C E0100; Adobe-Japan1; CID+3084 -608D E0100; Adobe-Japan1; CID+4838 -608E E0100; Adobe-Japan1; CID+21554 -608E E0101; Hanyo-Denshi; JB2981 -608E E0102; Hanyo-Denshi; TK01032010 -6091 E0100; Adobe-Japan1; CID+21555 -6092 E0100; Adobe-Japan1; CID+4846 -6093 E0100; Adobe-Japan1; CID+21556 -6094 E0100; Adobe-Japan1; CID+13326 -6094 E0101; Adobe-Japan1; CID+1401 -6094 E0102; Hanyo-Denshi; JA1889 -6094 E0103; Hanyo-Denshi; JC8448 -6095 E0100; Adobe-Japan1; CID+17630 -6096 E0100; Adobe-Japan1; CID+4844 -6097 E0100; Adobe-Japan1; CID+4845 -6097 E0101; Adobe-Japan1; CID+7828 -6097 E0102; Adobe-Japan1; CID+14128 -6097 E0103; Hanyo-Denshi; JA5604 -6097 E0103; Moji_Joho; MJ011594 -6097 E0104; Hanyo-Denshi; FT1954 -6097 E0104; Moji_Joho; MJ011595 -6097 E0105; Hanyo-Denshi; JTB173S -6097 E0105; Moji_Joho; MJ011596 -6098 E0100; Adobe-Japan1; CID+21557 -6099 E0100; Hanyo-Denshi; IP6099 -6099 E0101; Hanyo-Denshi; TK01031720 -6099 E0102; Hanyo-Denshi; TK01032030 -609A E0100; Adobe-Japan1; CID+4841 -609B E0100; Adobe-Japan1; CID+4843 -609C E0100; Hanyo-Denshi; IP609C -609C E0101; Hanyo-Denshi; TK01032020 -609D E0100; Adobe-Japan1; CID+16865 -609E E0100; Adobe-Japan1; CID+14541 -609E E0101; Adobe-Japan1; CID+21558 -609F E0100; Adobe-Japan1; CID+1947 -609F E0101; Hanyo-Denshi; JA2471 -609F E0101; Moji_Joho; MJ011608 -609F E0102; Hanyo-Denshi; JTB161 -609F E0102; Moji_Joho; MJ059607 -60A0 E0100; Adobe-Japan1; CID+3860 -60A2 E0100; Adobe-Japan1; CID+21559 -60A3 E0100; Adobe-Japan1; CID+1521 -60A4 E0100; Adobe-Japan1; CID+14542 -60A4 E0101; Adobe-Japan1; CID+15392 -60A4 E0102; Hanyo-Denshi; JB2989 -60A4 E0102; Moji_Joho; MJ011613 -60A4 E0103; Hanyo-Denshi; JTB16F -60A4 E0103; Moji_Joho; MJ011614 -60A4 E0104; Hanyo-Denshi; KS121670 -60A4 E0104; Moji_Joho; MJ057507 -60A5 E0100; Adobe-Japan1; CID+21560 -60A6 E0100; Adobe-Japan1; CID+1275 -60A7 E0100; Adobe-Japan1; CID+4847 -60A8 E0100; Adobe-Japan1; CID+17631 -60A8 E0101; Hanyo-Denshi; JB2991 -60A8 E0101; Moji_Joho; MJ011618 -60A8 E0102; Hanyo-Denshi; KS121710 -60A8 E0102; Moji_Joho; MJ011619 -60A9 E0100; Adobe-Japan1; CID+3312 -60AA E0100; Adobe-Japan1; CID+1137 -60B0 E0100; Adobe-Japan1; CID+14543 -60B1 E0100; Adobe-Japan1; CID+17633 -60B2 E0100; Adobe-Japan1; CID+3445 -60B2 E0101; Adobe-Japan1; CID+13491 -60B2 E0102; Moji_Joho; MJ011624 -60B2 E0103; Moji_Joho; MJ011625 -60B3 E0100; Adobe-Japan1; CID+4807 -60B3 E0101; Hanyo-Denshi; JA5560 -60B3 E0102; Hanyo-Denshi; TK01032500 -60B3 E0103; Hanyo-Denshi; TK01032510 -60B4 E0100; Adobe-Japan1; CID+4853 -60B5 E0100; Adobe-Japan1; CID+4857 -60B6 E0100; Adobe-Japan1; CID+3825 -60B7 E0100; Adobe-Japan1; CID+21561 -60B8 E0100; Adobe-Japan1; CID+4850 -60BB E0100; Adobe-Japan1; CID+19361 -60BC E0100; Adobe-Japan1; CID+3171 -60BD E0100; Adobe-Japan1; CID+4855 -60BE E0100; Adobe-Japan1; CID+17634 -60BE E0101; Hanyo-Denshi; JB3002 -60BE E0101; Moji_Joho; MJ011639 -60BE E0102; Hanyo-Denshi; JTB175 -60BE E0102; Moji_Joho; MJ011640 -60C2 E0100; Adobe-Japan1; CID+21562 -60C4 E0100; Adobe-Japan1; CID+19362 -60C5 E0100; Adobe-Japan1; CID+2520 -60C5 E0101; Adobe-Japan1; CID+13842 -60C5 E0102; Hanyo-Denshi; JA3080 -60C5 E0102; Moji_Joho; MJ011648 -60C5 E0103; Hanyo-Denshi; JTB172 -60C5 E0103; Moji_Joho; MJ011647 -60C6 E0100; Adobe-Japan1; CID+4856 -60C6 E0101; Hanyo-Denshi; JA5615 -60C6 E0101; Moji_Joho; MJ011649 -60C6 E0102; Hanyo-Denshi; FT2185 -60C6 E0102; Moji_Joho; MJ011650 -60C7 E0100; Adobe-Japan1; CID+3247 -60C7 E0101; Hanyo-Denshi; JA3855 -60C7 E0101; Moji_Joho; MJ011651 -60C7 E0102; Hanyo-Denshi; KS122980 -60C7 E0102; Moji_Joho; MJ011652 -60C8 E0100; Adobe-Japan1; CID+17635 -60C9 E0100; Adobe-Japan1; CID+21563 -60CA E0100; Adobe-Japan1; CID+21564 -60CB E0100; Adobe-Japan1; CID+14544 -60CE E0100; Adobe-Japan1; CID+21565 -60CF E0100; Adobe-Japan1; CID+21566 -60D1 E0100; Adobe-Japan1; CID+4077 -60D3 E0100; Adobe-Japan1; CID+4852 -60D3 E0101; Hanyo-Denshi; JA5611 -60D3 E0101; Moji_Joho; MJ011664 -60D3 E0102; Hanyo-Denshi; FT2184 -60D3 E0102; Moji_Joho; MJ011665 -60D4 E0100; Adobe-Japan1; CID+16866 -60D5 E0100; Adobe-Japan1; CID+8458 -60D8 E0100; Adobe-Japan1; CID+4858 -60D8 E0101; Adobe-Japan1; CID+13539 -60D8 E0102; Hanyo-Denshi; JA5617 -60D8 E0102; Moji_Joho; MJ011670 -60D8 E0103; Hanyo-Denshi; FT1690 -60D8 E0103; Moji_Joho; MJ011672 -60D8 E0104; Hanyo-Denshi; JTB179 -60D8 E0104; Moji_Joho; MJ011671 -60D9 E0100; Adobe-Japan1; CID+17636 -60DA E0100; Adobe-Japan1; CID+2061 -60DB E0100; Adobe-Japan1; CID+14545 -60DC E0100; Adobe-Japan1; CID+2671 -60DD E0100; Adobe-Japan1; CID+16867 -60DD E0101; Hanyo-Denshi; JB3015 -60DD E0101; Moji_Joho; MJ011677 -60DD E0102; Hanyo-Denshi; JTB176 -60DD E0102; Moji_Joho; MJ011678 -60DE E0100; Adobe-Japan1; CID+8457 -60DF E0100; Adobe-Japan1; CID+1176 -60E0 E0100; Adobe-Japan1; CID+4851 -60E0 E0101; Hanyo-Denshi; JA5610 -60E0 E0101; Moji_Joho; MJ011681 -60E0 E0102; Hanyo-Denshi; IB1864 -60E0 E0102; Moji_Joho; MJ011682 -60E0 E0103; Hanyo-Denshi; JTB193 -60E0 E0103; Moji_Joho; MJ059623 -60E0 E0104; Hanyo-Denshi; TK01032040 -60E0 E0105; Hanyo-Denshi; TK01032340 -60E1 E0100; Adobe-Japan1; CID+4849 -60E2 E0100; Adobe-Japan1; CID+21567 -60E3 E0100; Adobe-Japan1; CID+2780 -60E5 E0100; Adobe-Japan1; CID+21568 -60E5 E0101; Hanyo-Denshi; JB3018 -60E5 E0101; Moji_Joho; MJ011687 -60E5 E0102; Hanyo-Denshi; KS124440 -60E5 E0102; Moji_Joho; MJ011688 -60E7 E0100; Adobe-Japan1; CID+4839 -60E7 E0101; Hanyo-Denshi; JA5592 -60E7 E0101; Moji_Joho; MJ011690 -60E7 E0102; Hanyo-Denshi; FT2181 -60E7 E0102; Moji_Joho; MJ011691 -60E8 E0100; Adobe-Japan1; CID+2178 -60EE E0100; Adobe-Japan1; CID+17637 -60F0 E0100; Adobe-Japan1; CID+2854 -60F1 E0100; Adobe-Japan1; CID+4870 -60F2 E0100; Adobe-Japan1; CID+8460 -60F3 E0100; Adobe-Japan1; CID+2781 -60F4 E0100; Adobe-Japan1; CID+4865 -60F5 E0100; Adobe-Japan1; CID+17638 -60F6 E0100; Adobe-Japan1; CID+4862 -60F7 E0100; Adobe-Japan1; CID+4863 -60F8 E0100; Adobe-Japan1; CID+14546 -60F9 E0100; Adobe-Japan1; CID+2322 -60F9 E0101; Hanyo-Denshi; JA2870 -60F9 E0101; Moji_Joho; MJ011704 -60F9 E0102; Hanyo-Denshi; KS123320 -60F9 E0102; Moji_Joho; MJ011705 -60FA E0100; Adobe-Japan1; CID+4866 -60FB E0100; Adobe-Japan1; CID+4869 -60FC E0100; Adobe-Japan1; CID+21569 -60FD E0100; Adobe-Japan1; CID+19363 -6100 E0100; Adobe-Japan1; CID+4864 -6101 E0100; Adobe-Japan1; CID+2351 -6102 E0100; Adobe-Japan1; CID+21570 -6103 E0100; Adobe-Japan1; CID+4867 -6106 E0100; Adobe-Japan1; CID+4861 -6107 E0100; Adobe-Japan1; CID+21571 -6107 E0101; Hanyo-Denshi; JB3025 -6107 E0101; Moji_Joho; MJ011720 -6107 E0102; Hanyo-Denshi; KS122590 -6107 E0102; Moji_Joho; MJ011719 -6108 E0100; Adobe-Japan1; CID+3848 -6108 E0101; Adobe-Japan1; CID+7802 -6108 E0102; Hanyo-Denshi; JA4492 -6108 E0102; Moji_Joho; MJ011722 -6108 E0103; Hanyo-Denshi; FT1930 -6108 E0103; Moji_Joho; MJ011721 -6108 E0104; Hanyo-Denshi; JTB190 -6108 E0104; Moji_Joho; MJ011723 -6108 E0105; Hanyo-Denshi; TK01033050 -6109 E0100; Adobe-Japan1; CID+3847 -6109 E0101; Adobe-Japan1; CID+14067 -6109 E0102; Hanyo-Denshi; JA4491 -6109 E0102; Moji_Joho; MJ011726 -6109 E0103; Hanyo-Denshi; JTB185 -6109 E0103; Moji_Joho; MJ011725 -610A E0100; Adobe-Japan1; CID+19364 -610C E0100; Adobe-Japan1; CID+21572 -610C E0101; Hanyo-Denshi; JB3027 -610C E0102; Hanyo-Denshi; TK01032550 -610D E0100; Adobe-Japan1; CID+4871 -610E E0100; Adobe-Japan1; CID+4872 -610F E0100; Adobe-Japan1; CID+1177 -610F E0101; Adobe-Japan1; CID+13639 -610F E0102; Hanyo-Denshi; JA1653 -610F E0102; Moji_Joho; MJ011733 -610F E0103; Hanyo-Denshi; JTB191 -610F E0103; Moji_Joho; MJ011734 -6110 E0100; Adobe-Japan1; CID+17639 -6111 E0100; Adobe-Japan1; CID+8461 -6111 E0101; Hanyo-Denshi; JB3029 -6111 E0101; Moji_Joho; MJ011736 -6111 E0102; Hanyo-Denshi; JTB186 -6111 E0102; Moji_Joho; MJ011737 -6112 E0100; Adobe-Japan1; CID+14547 -6112 E0101; Hanyo-Denshi; JB3030 -6112 E0101; Moji_Joho; MJ011738 -6112 E0102; Hanyo-Denshi; JTB17AS -6112 E0102; Moji_Joho; MJ011739 -6113 E0100; Adobe-Japan1; CID+14548 -6114 E0100; Adobe-Japan1; CID+14549 -6114 E0101; Hanyo-Denshi; JB3032 -6114 E0101; Moji_Joho; MJ011741 -6114 E0102; Hanyo-Denshi; KS123210 -6114 E0102; Moji_Joho; MJ011742 -6115 E0100; Adobe-Japan1; CID+4860 -6115 E0101; Hanyo-Denshi; JA5619 -6115 E0101; Moji_Joho; MJ011743 -6115 E0102; Hanyo-Denshi; KS123240 -6115 E0102; Moji_Joho; MJ011744 -6116 E0100; Adobe-Japan1; CID+19365 -6116 E0101; Moji_Joho; MJ011745 -6116 E0102; Moji_Joho; MJ011746 -6117 E0100; Adobe-Japan1; CID+21573 -6119 E0100; Adobe-Japan1; CID+17640 -611A E0100; Adobe-Japan1; CID+1770 -611B E0100; Adobe-Japan1; CID+1130 -611B E0101; Hanyo-Denshi; JA1606 -611B E0101; Moji_Joho; MJ011752 -611B E0102; Hanyo-Denshi; KS123500 -611B E0102; Moji_Joho; MJ011751 -611B E0103; Hanyo-Denshi; KS124430 -611B E0103; Moji_Joho; MJ057515 -611C E0100; Adobe-Japan1; CID+14550 -611E E0100; Adobe-Japan1; CID+17641 -611F E0100; Adobe-Japan1; CID+1522 -6120 E0100; Adobe-Japan1; CID+8459 -6121 E0100; Adobe-Japan1; CID+4868 -6122 E0100; Adobe-Japan1; CID+21574 -6127 E0100; Adobe-Japan1; CID+4876 -6128 E0100; Adobe-Japan1; CID+4875 -612A E0100; Adobe-Japan1; CID+19366 -612B E0100; Adobe-Japan1; CID+16868 -612C E0100; Adobe-Japan1; CID+4880 -6130 E0100; Adobe-Japan1; CID+8463 -6131 E0100; Adobe-Japan1; CID+21575 -6134 E0100; Adobe-Japan1; CID+4881 -6135 E0100; Adobe-Japan1; CID+21576 -6136 E0100; Adobe-Japan1; CID+19367 -6137 E0100; Adobe-Japan1; CID+8462 -6139 E0100; Adobe-Japan1; CID+21577 -613A E0100; Adobe-Japan1; CID+17642 -613A E0101; Hanyo-Denshi; JD1263 -613A E0101; Moji_Joho; MJ011781 -613A E0102; Hanyo-Denshi; KS123970 -613A E0102; Moji_Joho; MJ011782 -613C E0100; Adobe-Japan1; CID+4879 -613C E0101; Hanyo-Denshi; JA5638 -613C E0101; Moji_Joho; MJ011784 -613C E0102; Hanyo-Denshi; JTB197 -613C E0102; Moji_Joho; MJ011786 -613C E0103; Hanyo-Denshi; TK01032820 -613C E0104; Moji_Joho; MJ011785 -613D E0100; Adobe-Japan1; CID+4882 -613D E0101; Adobe-Japan1; CID+13540 -613D E0102; Hanyo-Denshi; JA5641 -613D E0102; Moji_Joho; MJ011788 -613D E0103; Hanyo-Denshi; FT2188 -613D E0103; Moji_Joho; MJ011790 -613D E0104; Hanyo-Denshi; JTB187 -613D E0104; Moji_Joho; MJ011789 -613E E0100; Adobe-Japan1; CID+4874 -613F E0100; Adobe-Japan1; CID+4878 -613F E0101; Hanyo-Denshi; JA5637 -613F E0102; Hanyo-Denshi; TK01032900 -6141 E0100; Adobe-Japan1; CID+17644 -6142 E0100; Adobe-Japan1; CID+4883 -6144 E0100; Adobe-Japan1; CID+4884 -6145 E0100; Adobe-Japan1; CID+21578 -6146 E0100; Adobe-Japan1; CID+17645 -6147 E0100; Adobe-Japan1; CID+4873 -6148 E0100; Adobe-Japan1; CID+2250 -6148 E0101; Adobe-Japan1; CID+20064 -6148 E0102; Hanyo-Denshi; JA2792 -6148 E0102; Moji_Joho; MJ011802 -6148 E0103; Hanyo-Denshi; KS125550 -6148 E0103; Moji_Joho; MJ011804 -6148 E0104; Hanyo-Denshi; KS124660 -6148 E0104; Moji_Joho; MJ011803 -6148 E0105; Hanyo-Denshi; TK01032880 -6149 E0100; Adobe-Japan1; CID+21579 -614A E0100; Adobe-Japan1; CID+4877 -614A E0101; Hanyo-Denshi; JA5636 -614A E0101; Moji_Joho; MJ011807 -614A E0102; Hanyo-Denshi; FT2187 -614A E0102; Moji_Joho; MJ011808 -614B E0100; Adobe-Japan1; CID+2870 -614C E0100; Adobe-Japan1; CID+1988 -614C E0101; Adobe-Japan1; CID+13764 -614C E0102; Hanyo-Denshi; JA2518 -614C E0102; Moji_Joho; MJ011810 -614C E0103; Hanyo-Denshi; KS124450 -614C E0103; Moji_Joho; MJ011812 -614C E0104; Hanyo-Denshi; KS124190 -614C E0104; Moji_Joho; MJ011811 -614D E0100; Adobe-Japan1; CID+4859 -614E E0100; Adobe-Japan1; CID+2555 -614E E0101; Adobe-Japan1; CID+13356 -614E E0102; Hanyo-Denshi; JA3121 -614E E0102; Moji_Joho; MJ011814 -614E E0103; Hanyo-Denshi; JTB18B -614E E0103; Moji_Joho; MJ011815 -6153 E0100; Adobe-Japan1; CID+4897 -6154 E0100; Hanyo-Denshi; KS124870 -6154 E0101; Hanyo-Denshi; TK01033070 -6155 E0100; Adobe-Japan1; CID+3641 -6155 E0101; Hanyo-Denshi; JA4273 -6155 E0101; Moji_Joho; MJ011821 -6155 E0102; Hanyo-Denshi; KS125690 -6155 E0102; Moji_Joho; MJ011822 -6158 E0100; Adobe-Japan1; CID+4887 -6159 E0100; Adobe-Japan1; CID+4888 -615A E0100; Adobe-Japan1; CID+4889 -615C E0100; Hanyo-Denshi; IB1887 -615C E0100; Moji_Joho; MJ011830 -615C E0101; Hanyo-Denshi; IP615C -615C E0101; Moji_Joho; MJ011829 -615D E0100; Adobe-Japan1; CID+4896 -615D E0101; Hanyo-Denshi; JA5655 -615D E0101; Moji_Joho; MJ011831 -615D E0102; Hanyo-Denshi; KS126900 -615D E0102; Moji_Joho; MJ011833 -615D E0103; Hanyo-Denshi; KS125730 -615D E0103; Moji_Joho; MJ011832 -615E E0100; Adobe-Japan1; CID+19368 -615E E0101; Hanyo-Denshi; JB3051 -615E E0101; Moji_Joho; MJ011834 -615E E0102; Hanyo-Denshi; KS125650 -615E E0102; Moji_Joho; MJ011835 -615F E0100; Adobe-Japan1; CID+4895 -6160 E0100; Adobe-Japan1; CID+17646 -6162 E0100; Adobe-Japan1; CID+3755 -6162 E0101; Adobe-Japan1; CID+20119 -6162 E0102; Hanyo-Denshi; JA4393 -6162 E0102; Moji_Joho; MJ011840 -6162 E0103; Hanyo-Denshi; KS125010 -6162 E0103; Moji_Joho; MJ011839 -6163 E0100; Adobe-Japan1; CID+1523 -6164 E0100; Adobe-Japan1; CID+19369 -6165 E0100; Adobe-Japan1; CID+4893 -6165 E0101; Hanyo-Denshi; JA5652 -6165 E0101; Moji_Joho; MJ011844 -6165 E0102; Hanyo-Denshi; IB0684 -6165 E0102; Moji_Joho; MJ011843 -6165 E0103; Hanyo-Denshi; FT2191 -6165 E0103; Moji_Joho; MJ011845 -6167 E0100; Adobe-Japan1; CID+1819 -6167 E0101; Adobe-Japan1; CID+7669 -6167 E0102; Adobe-Japan1; CID+13741 -6167 E0103; Hanyo-Denshi; JA2337 -6167 E0103; Moji_Joho; MJ011848 -6167 E0104; Hanyo-Denshi; FT1785 -6167 E0104; Moji_Joho; MJ011847 -6167 E0105; Moji_Joho; MJ059630 -6168 E0100; Adobe-Japan1; CID+1426 -6168 E0101; Adobe-Japan1; CID+13328 -6168 E0102; Adobe-Japan1; CID+13422 -6168 E0103; Adobe-Japan1; CID+13676 -6168 E0104; Adobe-Japan1; CID+13677 -6168 E0105; Adobe-Japan1; CID+13678 -6168 E0106; Hanyo-Denshi; JA1920 -6168 E0106; Moji_Joho; MJ011849 -6168 E0107; Hanyo-Denshi; KS125630 -6168 E0107; Moji_Joho; MJ011853 -6168 E0108; Hanyo-Denshi; JC8460 -6168 E0109; Hanyo-Denshi; JTB1A0 -6168 E0109; Moji_Joho; MJ011852 -6168 E010A; Hanyo-Denshi; JTB1A1S -6168 E010A; Moji_Joho; MJ011851 -6168 E010B; Hanyo-Denshi; JTB1A2S -6168 E010B; Moji_Joho; MJ011856 -6168 E010C; Hanyo-Denshi; TK01033740 -6168 E010D; Moji_Joho; MJ011850 -6168 E010E; Moji_Joho; MJ011854 -6168 E010F; Moji_Joho; MJ011855 -616B E0100; Adobe-Japan1; CID+4890 -616C E0100; Adobe-Japan1; CID+21580 -616E E0100; Adobe-Japan1; CID+3968 -616F E0100; Adobe-Japan1; CID+4892 -6170 E0100; Adobe-Japan1; CID+1178 -6171 E0100; Adobe-Japan1; CID+4894 -6171 E0101; Hanyo-Denshi; JA5653 -6171 E0102; Hanyo-Denshi; TK01032710 -6171 E0103; Hanyo-Denshi; TK01033130 -6172 E0100; Adobe-Japan1; CID+21581 -6173 E0100; Adobe-Japan1; CID+4885 -6174 E0100; Adobe-Japan1; CID+4891 -6174 E0101; Hanyo-Denshi; JA5650 -6174 E0101; Moji_Joho; MJ011869 -6174 E0102; Hanyo-Denshi; FT2190 -6174 E0102; Moji_Joho; MJ011870 -6175 E0100; Adobe-Japan1; CID+4898 -6176 E0100; Adobe-Japan1; CID+1818 -6176 E0101; Hanyo-Denshi; JA2336 -6176 E0101; Moji_Joho; MJ011873 -6176 E0102; Hanyo-Denshi; KS125900 -6176 E0102; Moji_Joho; MJ011872 -6177 E0100; Adobe-Japan1; CID+4886 -6178 E0100; Adobe-Japan1; CID+21582 -6178 E0101; Hanyo-Denshi; JB3055 -6178 E0102; Hanyo-Denshi; TK01033770 -617A E0100; Hanyo-Denshi; IP617A -617A E0100; Moji_Joho; MJ011877 -617A E0101; Hanyo-Denshi; KS125600 -617A E0101; Moji_Joho; MJ057518 -617A E0102; Hanyo-Denshi; TK01032750 -617A E0103; Moji_Joho; MJ011878 -617B E0100; Adobe-Japan1; CID+19370 -617C E0100; Adobe-Japan1; CID+14551 -617D E0100; Adobe-Japan1; CID+19371 -617E E0100; Adobe-Japan1; CID+3911 -617F E0100; Adobe-Japan1; CID+19372 -617F E0101; Hanyo-Denshi; JB3058 -617F E0101; Moji_Joho; MJ011884 -617F E0102; Hanyo-Denshi; JTB1AA -617F E0102; Moji_Joho; MJ011885 -6180 E0100; Adobe-Japan1; CID+21583 -6181 E0100; Adobe-Japan1; CID+21584 -6181 E0101; Hanyo-Denshi; JB3060 -6181 E0101; Moji_Joho; MJ011887 -6181 E0102; Hanyo-Denshi; KS125560 -6181 E0102; Moji_Joho; MJ011888 -6182 E0100; Adobe-Japan1; CID+3861 -6182 E0101; Hanyo-Denshi; JA4511 -6182 E0101; Moji_Joho; MJ011891 -6182 E0102; Hanyo-Denshi; KS125970 -6182 E0102; Moji_Joho; MJ011890 -6182 E0103; Hanyo-Denshi; KS126850 -6182 E0103; Moji_Joho; MJ057524 -6183 E0100; Adobe-Japan1; CID+21585 -6184 E0100; Adobe-Japan1; CID+21586 -6187 E0100; Adobe-Japan1; CID+4901 -618A E0100; Adobe-Japan1; CID+4905 -618A E0101; Hanyo-Denshi; JA5664 -618A E0101; Moji_Joho; MJ011899 -618A E0102; Hanyo-Denshi; JTB1B4 -618A E0102; Moji_Joho; MJ011900 -618B E0100; Adobe-Japan1; CID+21587 -618D E0100; Adobe-Japan1; CID+14552 -618E E0100; Adobe-Japan1; CID+13363 -618E E0101; Adobe-Japan1; CID+2816 -618E E0102; Hanyo-Denshi; JA3394 -618E E0103; Hanyo-Denshi; JC8462 -6190 E0100; Adobe-Japan1; CID+4033 -6190 E0101; Adobe-Japan1; CID+14096 -6190 E0102; Hanyo-Denshi; JA4689 -6190 E0102; Moji_Joho; MJ011907 -6190 E0103; Hanyo-Denshi; KS126170 -6190 E0103; Moji_Joho; MJ011906 -6190 E0104; Moji_Joho; MJ011908 -6191 E0100; Adobe-Japan1; CID+4906 -6192 E0100; Adobe-Japan1; CID+17648 -6193 E0100; Adobe-Japan1; CID+17649 -6193 E0101; Hanyo-Denshi; JB3066 -6193 E0101; Moji_Joho; MJ011911 -6193 E0102; Hanyo-Denshi; IB1886 -6193 E0102; Moji_Joho; MJ011912 -6194 E0100; Adobe-Japan1; CID+4903 -6196 E0100; Adobe-Japan1; CID+4900 -6197 E0100; Adobe-Japan1; CID+17650 -6198 E0100; Adobe-Japan1; CID+8464 -6199 E0100; Adobe-Japan1; CID+4899 -619A E0100; Adobe-Japan1; CID+4904 -619B E0100; Hanyo-Denshi; IP619B -619B E0100; Moji_Joho; MJ011920 -619B E0101; Hanyo-Denshi; KS126890 -619B E0101; Moji_Joho; MJ011921 -619C E0100; Adobe-Japan1; CID+21588 -619D E0100; Adobe-Japan1; CID+19373 -619F E0100; Adobe-Japan1; CID+14553 -61A0 E0100; Adobe-Japan1; CID+21589 -61A4 E0100; Adobe-Japan1; CID+3584 -61A4 E0101; Adobe-Japan1; CID+13501 -61A4 E0102; Hanyo-Denshi; JA4216 -61A4 E0102; Moji_Joho; MJ011930 -61A4 E0103; Hanyo-Denshi; KS127670 -61A4 E0103; Moji_Joho; MJ011931 -61A4 E0104; Moji_Joho; MJ011932 -61A5 E0100; Adobe-Japan1; CID+17651 -61A7 E0100; Adobe-Japan1; CID+3212 -61A7 E0101; Hanyo-Denshi; JA3820 -61A7 E0101; Moji_Joho; MJ011935 -61A7 E0102; Hanyo-Denshi; KS126820 -61A7 E0102; Moji_Joho; MJ011936 -61A8 E0100; Adobe-Japan1; CID+14554 -61A9 E0100; Adobe-Japan1; CID+1820 -61AA E0100; Adobe-Japan1; CID+21590 -61AB E0100; Adobe-Japan1; CID+4907 -61AC E0100; Adobe-Japan1; CID+4902 -61AD E0100; Adobe-Japan1; CID+17652 -61AE E0100; Adobe-Japan1; CID+4908 -61AF E0100; Hanyo-Denshi; JT61AF -61AF E0100; Moji_Joho; MJ011945 -61AF E0101; Hanyo-Denshi; KS126540 -61AF E0101; Moji_Joho; MJ011944 -61B2 E0100; Adobe-Japan1; CID+1873 -61B2 E0101; Adobe-Japan1; CID+13750 -61B2 E0102; Adobe-Japan1; CID+20120 -61B2 E0103; Hanyo-Denshi; JA2391 -61B2 E0103; Moji_Joho; MJ011949 -61B2 E0104; Hanyo-Denshi; JTB1B0 -61B2 E0104; Moji_Joho; MJ011951 -61B2 E0105; Hanyo-Denshi; KS127180 -61B2 E0105; Moji_Joho; MJ011948 -61B2 E0106; Hanyo-Denshi; JTB1AFS -61B2 E0106; Moji_Joho; MJ011950 -61B4 E0100; Moji_Joho; MJ011953 -61B4 E0101; Moji_Joho; MJ011954 -61B6 E0100; Adobe-Japan1; CID+1329 -61B6 E0101; Hanyo-Denshi; JA1817 -61B6 E0101; Moji_Joho; MJ011956 -61B6 E0102; Hanyo-Denshi; JTB1B5 -61B6 E0102; Moji_Joho; MJ011957 -61B8 E0100; Adobe-Japan1; CID+19374 -61B9 E0100; Adobe-Japan1; CID+16870 -61BA E0100; Adobe-Japan1; CID+4916 -61BC E0100; Adobe-Japan1; CID+16869 -61BC E0101; Hanyo-Denshi; JB3079 -61BC E0101; Moji_Joho; MJ011963 -61BC E0102; Hanyo-Denshi; JTB1BCS -61BC E0102; Moji_Joho; MJ011964 -61BD E0100; Hanyo-Denshi; IP61BD -61BD E0101; Hanyo-Denshi; KS127460 -61BE E0100; Adobe-Japan1; CID+1524 -61C0 E0100; Adobe-Japan1; CID+21591 -61C1 E0100; Adobe-Japan1; CID+21592 -61C2 E0100; Adobe-Japan1; CID+14555 -61C2 E0101; Hanyo-Denshi; JB3082 -61C2 E0101; Moji_Joho; MJ011971 -61C2 E0102; Hanyo-Denshi; KS127560 -61C2 E0102; Moji_Joho; MJ011972 -61C3 E0100; Adobe-Japan1; CID+4914 -61C6 E0100; Adobe-Japan1; CID+4915 -61C7 E0100; Adobe-Japan1; CID+2073 -61C8 E0100; Adobe-Japan1; CID+4913 -61C9 E0100; Adobe-Japan1; CID+4911 -61CA E0100; Adobe-Japan1; CID+4910 -61CA E0101; Hanyo-Denshi; JA5669 -61CA E0101; Moji_Joho; MJ011980 -61CA E0102; Hanyo-Denshi; FT2192 -61CA E0102; Moji_Joho; MJ011981 -61CB E0100; Adobe-Japan1; CID+4917 -61CC E0100; Adobe-Japan1; CID+4909 -61CC E0101; Hanyo-Denshi; JA5668 -61CC E0101; Moji_Joho; MJ011983 -61CC E0102; Hanyo-Denshi; JTB1B9 -61CC E0102; Moji_Joho; MJ011984 -61CC E0103; Hanyo-Denshi; TK01034000 -61CD E0100; Adobe-Japan1; CID+4919 -61CE E0100; Adobe-Japan1; CID+21593 -61CF E0100; Adobe-Japan1; CID+21594 -61D0 E0100; Adobe-Japan1; CID+1403 -61D0 E0101; Hanyo-Denshi; JA1891 -61D0 E0101; Moji_Joho; MJ011988 -61D0 E0102; Hanyo-Denshi; KS126860 -61D0 E0102; Moji_Joho; MJ057525 -61D5 E0100; Adobe-Japan1; CID+17654 -61D5 E0101; Hanyo-Denshi; JB3085 -61D5 E0101; Moji_Joho; MJ011991 -61D5 E0102; Hanyo-Denshi; JTB1BE -61D5 E0102; Moji_Joho; MJ011992 -61DC E0100; Adobe-Japan1; CID+19375 -61DD E0100; Adobe-Japan1; CID+17655 -61DE E0100; Adobe-Japan1; CID+21595 -61DE E0101; Hanyo-Denshi; JB3088 -61DE E0101; Moji_Joho; MJ012001 -61DE E0102; Hanyo-Denshi; IB1905 -61DE E0102; Moji_Joho; MJ012002 -61DE E0103; Hanyo-Denshi; KS128180 -61DE E0103; Moji_Joho; MJ012003 -61DF E0100; Adobe-Japan1; CID+14556 -61E1 E0100; Adobe-Japan1; CID+21596 -61E2 E0100; Adobe-Japan1; CID+19376 -61E3 E0100; Adobe-Japan1; CID+4921 -61E5 E0100; Adobe-Japan1; CID+19377 -61E5 E0101; Hanyo-Denshi; JB3094 -61E5 E0101; Moji_Joho; MJ012011 -61E5 E0102; Hanyo-Denshi; KS128310 -61E5 E0102; Moji_Joho; MJ012010 -61E6 E0100; Adobe-Japan1; CID+4920 -61E7 E0100; Adobe-Japan1; CID+21597 -61E8 E0100; Adobe-Japan1; CID+19378 -61E9 E0100; Adobe-Japan1; CID+21598 -61E9 E0101; Hanyo-Denshi; JB3093 -61E9 E0101; Moji_Joho; MJ012015 -61E9 E0102; Hanyo-Denshi; JTB1BD -61E9 E0102; Moji_Joho; MJ012016 -61EC E0100; Adobe-Japan1; CID+21599 -61EC E0101; Hanyo-Denshi; JB3101 -61EC E0101; Moji_Joho; MJ012019 -61EC E0102; Hanyo-Denshi; JTB0F2 -61EC E0102; Moji_Joho; MJ012020 -61ED E0100; Adobe-Japan1; CID+21600 -61ED E0101; Hanyo-Denshi; JB3102 -61ED E0102; Hanyo-Denshi; TK01034080 -61EF E0100; Adobe-Japan1; CID+21601 -61F2 E0100; Adobe-Japan1; CID+3012 -61F2 E0101; Adobe-Japan1; CID+13369 -61F2 E0102; Adobe-Japan1; CID+13930 -61F2 E0103; Adobe-Japan1; CID+21072 -61F2 E0104; Hanyo-Denshi; JA3608 -61F2 E0104; Moji_Joho; MJ012027 -61F2 E0105; Hanyo-Denshi; JC8465 -61F2 E0105; Moji_Joho; MJ030260 -61F2 E0106; Hanyo-Denshi; JC8465S -61F2 E0106; Moji_Joho; MJ030261 -61F2 E0107; Hanyo-Denshi; JTB1BFS -61F2 E0107; Moji_Joho; MJ012028 -61F4 E0100; Adobe-Japan1; CID+4924 -61F5 E0100; Adobe-Japan1; CID+17656 -61F5 E0101; Hanyo-Denshi; JD1281 -61F5 E0101; Moji_Joho; MJ012030 -61F5 E0102; Hanyo-Denshi; JTB1C1S -61F5 E0102; Moji_Joho; MJ012031 -61F6 E0100; Adobe-Japan1; CID+4922 -61F6 E0101; Hanyo-Denshi; JA5681 -61F6 E0101; Moji_Joho; MJ012033 -61F6 E0102; Hanyo-Denshi; FT2193 -61F6 E0102; Moji_Joho; MJ012032 -61F7 E0100; Adobe-Japan1; CID+4912 -61F8 E0100; Adobe-Japan1; CID+1874 -61F8 E0101; Adobe-Japan1; CID+20121 -61FA E0100; Adobe-Japan1; CID+4923 -61FB E0100; Hanyo-Denshi; JT61FB -61FB E0100; Moji_Joho; MJ012038 -61FB E0101; Hanyo-Denshi; KS129420 -61FB E0101; Moji_Joho; MJ012039 -61FC E0100; Adobe-Japan1; CID+4927 -61FD E0100; Adobe-Japan1; CID+4926 -61FD E0101; Hanyo-Denshi; JA5685 -61FD E0101; Moji_Joho; MJ012041 -61FD E0102; Hanyo-Denshi; KS129560 -61FD E0102; Moji_Joho; MJ012042 -61FE E0100; Adobe-Japan1; CID+4928 -61FE E0101; Adobe-Japan1; CID+13541 -61FE E0102; Moji_Joho; MJ012043 -61FE E0103; Moji_Joho; MJ012044 -61FF E0100; Adobe-Japan1; CID+4925 -61FF E0101; Hanyo-Denshi; JA5684 -61FF E0101; Moji_Joho; MJ012045 -61FF E0102; Hanyo-Denshi; JTB1C5 -61FF E0102; Moji_Joho; MJ012046 -6200 E0100; Adobe-Japan1; CID+4929 -6201 E0100; Adobe-Japan1; CID+21602 -6203 E0100; Adobe-Japan1; CID+21603 -6204 E0100; Adobe-Japan1; CID+19379 -6205 E0100; Hanyo-Denshi; IP6205 -6205 E0100; Moji_Joho; MJ012052 -6205 E0101; Hanyo-Denshi; KS129870 -6205 E0101; Moji_Joho; MJ012053 -6207 E0100; Adobe-Japan1; CID+19380 -6207 E0101; Hanyo-Denshi; JB3107 -6207 E0101; Moji_Joho; MJ012054 -6207 E0102; Hanyo-Denshi; JTB1C6 -6207 E0102; Moji_Joho; MJ012055 -6208 E0100; Adobe-Japan1; CID+4930 -6209 E0100; Adobe-Japan1; CID+4931 -620A E0100; Adobe-Japan1; CID+3642 -620C E0100; Adobe-Japan1; CID+4933 -620D E0100; Adobe-Japan1; CID+4932 -620E E0100; Adobe-Japan1; CID+2377 -620E E0101; Moji_Joho; MJ012061 -620E E0102; Moji_Joho; MJ012062 -6210 E0100; Adobe-Japan1; CID+2642 -6210 E0101; Adobe-Japan1; CID+13867 -6210 E0102; Hanyo-Denshi; JA3214 -6210 E0102; Moji_Joho; MJ012063 -6210 E0103; Hanyo-Denshi; JTB1CA -6210 E0103; Moji_Joho; MJ012064 -6210 E0104; Hanyo-Denshi; TK01034600 -6211 E0100; Adobe-Japan1; CID+1382 -6212 E0100; Adobe-Japan1; CID+1404 -6213 E0100; Adobe-Japan1; CID+8465 -6214 E0100; Adobe-Japan1; CID+4934 -6214 E0101; Hanyo-Denshi; JA5693 -6214 E0101; Moji_Joho; MJ012068 -6214 E0102; Hanyo-Denshi; KS130220 -6214 E0102; Moji_Joho; MJ057535 -6215 E0100; Adobe-Japan1; CID+14557 -6216 E0100; Adobe-Japan1; CID+1155 -621A E0100; Adobe-Japan1; CID+2672 -621A E0101; Hanyo-Denshi; JA3244 -621A E0101; Moji_Joho; MJ012072 -621A E0102; Hanyo-Denshi; KS130870 -621A E0102; Moji_Joho; MJ057540 -621B E0100; Adobe-Japan1; CID+4935 -621B E0101; Hanyo-Denshi; JA5694 -621B E0101; Moji_Joho; MJ012073 -621B E0102; Hanyo-Denshi; KS130740 -621B E0102; Moji_Joho; MJ012074 -621C E0100; Adobe-Japan1; CID+21604 -621D E0100; Adobe-Japan1; CID+6756 -621E E0100; Adobe-Japan1; CID+4936 -621F E0100; Adobe-Japan1; CID+1847 -6220 E0100; Adobe-Japan1; CID+21605 -6220 E0101; Hanyo-Denshi; JB3111 -6220 E0101; Moji_Joho; MJ012080 -6220 E0102; Hanyo-Denshi; KS130880 -6220 E0102; Moji_Joho; MJ012079 -6220 E0103; Hanyo-Denshi; KS131110 -6220 E0103; Moji_Joho; MJ012081 -6221 E0100; Adobe-Japan1; CID+4937 -6222 E0100; Adobe-Japan1; CID+16871 -6222 E0101; Hanyo-Denshi; JB3112 -6222 E0101; Moji_Joho; MJ012084 -6222 E0102; Hanyo-Denshi; KS130890 -6222 E0102; Moji_Joho; MJ012083 -6223 E0100; Adobe-Japan1; CID+17658 -6226 E0100; Adobe-Japan1; CID+2707 -6227 E0100; Adobe-Japan1; CID+21606 -6229 E0100; Adobe-Japan1; CID+14558 -622A E0100; Adobe-Japan1; CID+4938 -622B E0100; Adobe-Japan1; CID+21607 -622E E0100; Adobe-Japan1; CID+4939 -622E E0101; Hanyo-Denshi; JA5704 -622E E0101; Moji_Joho; MJ012096 -622E E0102; Hanyo-Denshi; FT2201 -622E E0102; Moji_Joho; MJ012097 -622F E0100; Adobe-Japan1; CID+1620 -6230 E0100; Adobe-Japan1; CID+4940 -6230 E0101; Hanyo-Denshi; JA5705 -6230 E0102; Hanyo-Denshi; TK01034890 -6231 E0100; Adobe-Japan1; CID+19381 -6232 E0100; Adobe-Japan1; CID+4941 -6233 E0100; Adobe-Japan1; CID+4942 -6233 E0101; Hanyo-Denshi; JA5707 -6233 E0101; Moji_Joho; MJ012102 -6233 E0102; Hanyo-Denshi; FT2202 -6233 E0102; Moji_Joho; MJ012103 -6234 E0100; Adobe-Japan1; CID+2871 -6234 E0101; Hanyo-Denshi; JA3455 -6234 E0101; Moji_Joho; MJ012104 -6234 E0102; Hanyo-Denshi; KS131690 -6234 E0102; Moji_Joho; MJ012105 -6236 E0100; Adobe-Japan1; CID+13757 -6238 E0100; Adobe-Japan1; CID+1921 -6239 E0100; Adobe-Japan1; CID+19382 -623B E0100; Adobe-Japan1; CID+3821 -623B E0101; Adobe-Japan1; CID+14059 -623B E0102; Hanyo-Denshi; JA4465 -623B E0102; Moji_Joho; MJ012112 -623B E0103; Hanyo-Denshi; KS131910 -623B E0103; Moji_Joho; MJ012111 -623D E0100; Adobe-Japan1; CID+19383 -623E E0100; Adobe-Japan1; CID+13390 -623F E0100; Adobe-Japan1; CID+3690 -623F E0101; Adobe-Japan1; CID+14035 -623F E0102; Hanyo-Denshi; JA4328 -623F E0102; Moji_Joho; MJ012117 -623F E0103; Hanyo-Denshi; JTB1D3 -623F E0103; Moji_Joho; MJ012116 -623F E0104; Hanyo-Denshi; JTB1D4 -623F E0104; Moji_Joho; MJ012118 -6240 E0100; Adobe-Japan1; CID+2420 -6240 E0101; Adobe-Japan1; CID+13826 -6240 E0102; Hanyo-Denshi; JA2974 -6240 E0102; Moji_Joho; MJ012120 -6240 E0103; Hanyo-Denshi; IB0315 -6240 E0103; Moji_Joho; MJ012119 -6241 E0100; Adobe-Japan1; CID+4943 -6241 E0101; Adobe-Japan1; CID+7991 -6241 E0102; Hanyo-Denshi; JA5708 -6241 E0102; Moji_Joho; MJ012122 -6241 E0103; Hanyo-Denshi; HG1661 -6241 E0103; Moji_Joho; MJ012121 -6242 E0100; Adobe-Japan1; CID+21608 -6243 E0100; Adobe-Japan1; CID+14559 -6244 E0100; Adobe-Japan1; CID+21609 -6246 E0100; Adobe-Japan1; CID+14560 -6246 E0101; Hanyo-Denshi; JB3122 -6246 E0102; Hanyo-Denshi; TK01035000 -6247 E0100; Adobe-Japan1; CID+2708 -6247 E0101; Adobe-Japan1; CID+13883 -6247 E0102; Hanyo-Denshi; JA3280 -6247 E0102; Moji_Joho; MJ012130 -6247 E0103; Hanyo-Denshi; JTB1D6S -6247 E0103; Moji_Joho; MJ012129 -6248 E0100; Adobe-Japan1; CID+6938 -6248 E0101; Adobe-Japan1; CID+7874 -6248 E0102; Hanyo-Denshi; JA7829 -6248 E0102; Moji_Joho; MJ012132 -6248 E0103; Hanyo-Denshi; FT2003 -6248 E0103; Moji_Joho; MJ012131 -6249 E0100; Adobe-Japan1; CID+3446 -6249 E0101; Adobe-Japan1; CID+7779 -6249 E0102; Adobe-Japan1; CID+13492 -6249 E0103; Hanyo-Denshi; JA4066 -6249 E0104; Hanyo-Denshi; FT1906 -6249 E0104; Moji_Joho; MJ012134 -6249 E0105; Moji_Joho; MJ012133 -6249 E0106; Moji_Joho; MJ012135 -6249 E0107; Moji_Joho; MJ012136 -624B E0100; Adobe-Japan1; CID+2326 -624C E0100; Adobe-Japan1; CID+14561 -624D E0100; Adobe-Japan1; CID+2109 -624D E0101; Hanyo-Denshi; JA2645 -624D E0101; Moji_Joho; MJ012140 -624D E0102; Hanyo-Denshi; JTAD0B -624D E0102; Moji_Joho; MJ059295 -624E E0100; Adobe-Japan1; CID+4944 -6250 E0100; Adobe-Japan1; CID+21610 -6251 E0100; Adobe-Japan1; CID+14562 -6252 E0100; Adobe-Japan1; CID+17659 -6253 E0100; Adobe-Japan1; CID+2855 -6254 E0100; Adobe-Japan1; CID+21611 -6255 E0100; Adobe-Japan1; CID+3575 -6256 E0100; Adobe-Japan1; CID+14563 -6258 E0100; Adobe-Japan1; CID+2897 -625A E0100; Adobe-Japan1; CID+16872 -625A E0101; Hanyo-Denshi; JB3129 -625A E0101; Moji_Joho; MJ012153 -625A E0102; Hanyo-Denshi; JTB1DB -625A E0102; Moji_Joho; MJ012154 -625B E0100; Adobe-Japan1; CID+4947 -625C E0100; Adobe-Japan1; CID+21612 -625D E0100; Hanyo-Denshi; IP625D -625D E0100; Moji_Joho; MJ012157 -625D E0101; Hanyo-Denshi; KS132940 -625D E0101; Moji_Joho; MJ012158 -625E E0100; Adobe-Japan1; CID+4945 -6260 E0100; Adobe-Japan1; CID+4948 -6260 E0101; Moji_Joho; MJ012161 -6260 E0102; Moji_Joho; MJ012162 -6261 E0100; Adobe-Japan1; CID+17660 -6263 E0100; Adobe-Japan1; CID+4946 -6264 E0100; Adobe-Japan1; CID+17661 -6268 E0100; Adobe-Japan1; CID+4949 -6268 E0101; Adobe-Japan1; CID+13542 -6268 E0102; Hanyo-Denshi; JA5714 -6268 E0103; Hanyo-Denshi; KS133090 -6268 E0103; Moji_Joho; MJ012170 -6268 E0104; Moji_Joho; MJ012171 -6268 E0105; Moji_Joho; MJ012172 -626D E0100; Adobe-Japan1; CID+17663 -626E E0100; Adobe-Japan1; CID+3585 -626E E0101; Hanyo-Denshi; JA4217 -626E E0101; Moji_Joho; MJ012174 -626E E0102; Hanyo-Denshi; FT2053 -626E E0102; Moji_Joho; MJ012175 -626F E0100; Adobe-Japan1; CID+16873 -6271 E0100; Adobe-Japan1; CID+1147 -6271 E0101; Adobe-Japan1; CID+13637 -6271 E0102; Hanyo-Denshi; JA1623 -6271 E0102; Moji_Joho; MJ012178 -6271 E0103; Hanyo-Denshi; JTB1DE -6271 E0103; Moji_Joho; MJ012179 -6273 E0100; Adobe-Japan1; CID+17664 -6276 E0100; Adobe-Japan1; CID+3536 -6279 E0100; Adobe-Japan1; CID+3447 -627A E0100; Adobe-Japan1; CID+19384 -627B E0100; Adobe-Japan1; CID+17662 -627C E0100; Adobe-Japan1; CID+4950 -627D E0100; Adobe-Japan1; CID+21613 -627E E0100; Adobe-Japan1; CID+4953 -627F E0100; Adobe-Japan1; CID+2461 -6280 E0100; Adobe-Japan1; CID+1621 -6280 E0101; Moji_Joho; MJ012194 -6280 E0102; Moji_Joho; MJ012195 -6282 E0100; Adobe-Japan1; CID+4951 -6283 E0100; Adobe-Japan1; CID+4958 -6283 E0101; Moji_Joho; MJ012198 -6283 E0102; Moji_Joho; MJ012199 -6284 E0100; Adobe-Japan1; CID+2462 -6285 E0100; Adobe-Japan1; CID+13765 -6286 E0100; Moji_Joho; MJ012202 -6286 E0101; Moji_Joho; MJ012203 -6289 E0100; Adobe-Japan1; CID+4952 -628A E0100; Adobe-Japan1; CID+3322 -628D E0100; Adobe-Japan1; CID+21614 -628E E0100; Adobe-Japan1; CID+21615 -628F E0100; Adobe-Japan1; CID+21616 -6290 E0100; Adobe-Japan1; CID+19385 -6291 E0100; Adobe-Japan1; CID+3912 -6292 E0100; Adobe-Japan1; CID+4954 -6293 E0100; Adobe-Japan1; CID+4955 -6294 E0100; Adobe-Japan1; CID+4959 -6295 E0100; Adobe-Japan1; CID+3172 -6296 E0100; Adobe-Japan1; CID+4956 -6297 E0100; Adobe-Japan1; CID+1989 -6298 E0100; Adobe-Japan1; CID+2690 -6299 E0100; Adobe-Japan1; CID+17665 -629B E0100; Adobe-Japan1; CID+4973 -629C E0100; Adobe-Japan1; CID+3400 -629E E0100; Adobe-Japan1; CID+2898 -62A3 E0100; Hanyo-Denshi; TK01011440 -62A3 E0101; Hanyo-Denshi; TK01035170 -62A6 E0100; Adobe-Japan1; CID+8466 -62A8 E0100; Adobe-Japan1; CID+19386 -62A8 E0101; Hanyo-Denshi; JB3142 -62A8 E0102; Hanyo-Denshi; TK01035260 -62AB E0100; Adobe-Japan1; CID+3448 -62AC E0100; Adobe-Japan1; CID+5042 -62B1 E0100; Adobe-Japan1; CID+3658 -62B1 E0101; Adobe-Japan1; CID+14021 -62B1 E0102; Hanyo-Denshi; JA4290 -62B1 E0102; Moji_Joho; MJ012242 -62B1 E0103; Hanyo-Denshi; JTB1E3 -62B1 E0103; Moji_Joho; MJ012241 -62B3 E0100; Adobe-Japan1; CID+21617 -62B5 E0100; Adobe-Japan1; CID+3085 -62B6 E0100; Adobe-Japan1; CID+21618 -62B7 E0100; Adobe-Japan1; CID+21619 -62B9 E0100; Adobe-Japan1; CID+3747 -62BA E0100; Adobe-Japan1; CID+21620 -62BB E0100; Adobe-Japan1; CID+4962 -62BC E0100; Adobe-Japan1; CID+1313 -62BD E0100; Adobe-Japan1; CID+2984 -62BE E0100; Adobe-Japan1; CID+21621 -62BF E0100; Adobe-Japan1; CID+21622 -62C2 E0100; Adobe-Japan1; CID+4971 -62C4 E0100; Adobe-Japan1; CID+14564 -62C5 E0100; Adobe-Japan1; CID+2930 -62C6 E0100; Adobe-Japan1; CID+4965 -62C7 E0100; Adobe-Japan1; CID+4972 -62C8 E0100; Adobe-Japan1; CID+4967 -62C9 E0100; Adobe-Japan1; CID+4974 -62CA E0100; Adobe-Japan1; CID+4970 -62CC E0100; Adobe-Japan1; CID+4969 -62CC E0101; Adobe-Japan1; CID+14130 -62CC E0102; Hanyo-Denshi; JA5734 -62CC E0102; Moji_Joho; MJ012267 -62CC E0103; Hanyo-Denshi; FT2204 -62CC E0103; Moji_Joho; MJ012268 -62CD E0100; Adobe-Japan1; CID+3365 -62CE E0100; Adobe-Japan1; CID+21623 -62CF E0100; Adobe-Japan1; CID+4963 -62CF E0101; Adobe-Japan1; CID+13543 -62D0 E0100; Adobe-Japan1; CID+1405 -62D0 E0101; Adobe-Japan1; CID+7649 -62D0 E0102; Hanyo-Denshi; JA1893 -62D0 E0102; Moji_Joho; MJ012272 -62D0 E0103; Hanyo-Denshi; FT1766 -62D0 E0103; Moji_Joho; MJ012273 -62D0 E0104; Hanyo-Denshi; IB1917 -62D0 E0104; Moji_Joho; MJ012274 -62D1 E0100; Adobe-Japan1; CID+4961 -62D2 E0100; Adobe-Japan1; CID+1675 -62D2 E0101; Adobe-Japan1; CID+13715 -62D2 E0102; Hanyo-Denshi; JA2181 -62D2 E0102; Moji_Joho; MJ012277 -62D2 E0103; Hanyo-Denshi; KS134470 -62D2 E0103; Moji_Joho; MJ012276 -62D3 E0100; Adobe-Japan1; CID+2899 -62D3 E0101; Hanyo-Denshi; JA3483 -62D3 E0102; Hanyo-Denshi; TK01035300 -62D4 E0100; Adobe-Japan1; CID+14129 -62D4 E0101; Adobe-Japan1; CID+4957 -62D4 E0102; Hanyo-Denshi; JA5722 -62D4 E0103; Hanyo-Denshi; TK01035270 -62D5 E0100; Adobe-Japan1; CID+17666 -62D6 E0100; Adobe-Japan1; CID+16874 -62D7 E0100; Adobe-Japan1; CID+4960 -62D8 E0100; Adobe-Japan1; CID+1990 -62D9 E0100; Adobe-Japan1; CID+2687 -62DA E0100; Adobe-Japan1; CID+19387 -62DB E0100; Adobe-Japan1; CID+2463 -62DC E0100; Adobe-Japan1; CID+4968 -62DD E0100; Adobe-Japan1; CID+3336 -62E0 E0100; Adobe-Japan1; CID+1676 -62E1 E0100; Adobe-Japan1; CID+1446 -62EA E0100; Adobe-Japan1; CID+21624 -62EC E0100; Adobe-Japan1; CID+1477 -62ED E0100; Adobe-Japan1; CID+2535 -62EE E0100; Adobe-Japan1; CID+4976 -62EF E0100; Adobe-Japan1; CID+4981 -62F1 E0100; Adobe-Japan1; CID+4977 -62F2 E0100; Adobe-Japan1; CID+21625 -62F3 E0100; Adobe-Japan1; CID+1875 -62F3 E0101; Adobe-Japan1; CID+7969 -62F3 E0102; Hanyo-Denshi; JA2393 -62F3 E0102; Moji_Joho; MJ012304 -62F3 E0103; Hanyo-Denshi; JTB1EB -62F3 E0103; Moji_Joho; MJ012303 -62F4 E0100; Adobe-Japan1; CID+19388 -62F4 E0101; Hanyo-Denshi; JB3156 -62F4 E0101; Moji_Joho; MJ012305 -62F4 E0102; Hanyo-Denshi; IB1919 -62F4 E0102; Moji_Joho; MJ012306 -62F5 E0100; Adobe-Japan1; CID+4982 -62F6 E0100; Adobe-Japan1; CID+2160 -62F7 E0100; Adobe-Japan1; CID+2043 -62F7 E0101; Adobe-Japan1; CID+13448 -62F7 E0102; Hanyo-Denshi; JA2573 -62F7 E0102; Moji_Joho; MJ012309 -62F7 E0103; Hanyo-Denshi; FT1630 -62F7 E0103; Moji_Joho; MJ012310 -62FC E0100; Adobe-Japan1; CID+14565 -62FC E0101; Hanyo-Denshi; JB3157 -62FC E0101; Moji_Joho; MJ012315 -62FC E0102; Hanyo-Denshi; KS137460 -62FC E0102; Moji_Joho; MJ012316 -62FD E0100; Adobe-Japan1; CID+17668 -62FE E0100; Adobe-Japan1; CID+2352 -62FF E0100; Adobe-Japan1; CID+4964 -6301 E0100; Adobe-Japan1; CID+2251 -6302 E0100; Adobe-Japan1; CID+4979 -6303 E0100; Adobe-Japan1; CID+17669 -6304 E0100; Adobe-Japan1; CID+21626 -6307 E0100; Adobe-Japan1; CID+2214 -6308 E0100; Adobe-Japan1; CID+4980 -6308 E0101; Hanyo-Denshi; JA5745 -6308 E0101; Moji_Joho; MJ012328 -6308 E0102; Hanyo-Denshi; KS136840 -6308 E0102; Moji_Joho; MJ012329 -6308 E0103; Hanyo-Denshi; FT2206 -6308 E0103; Moji_Joho; MJ012331 -6308 E0104; Hanyo-Denshi; JTB1EC -6308 E0104; Moji_Joho; MJ012330 -6309 E0100; Adobe-Japan1; CID+1160 -630A E0100; Adobe-Japan1; CID+14566 -630B E0100; Adobe-Japan1; CID+21627 -630C E0100; Adobe-Japan1; CID+4975 -630D E0100; Adobe-Japan1; CID+14567 -6310 E0100; Adobe-Japan1; CID+17670 -6311 E0100; Adobe-Japan1; CID+3013 -6313 E0100; Adobe-Japan1; CID+21628 -6316 E0100; Adobe-Japan1; CID+19389 -6318 E0100; Adobe-Japan1; CID+14568 -6319 E0100; Adobe-Japan1; CID+1677 -631B E0100; Adobe-Japan1; CID+14135 -631F E0100; Adobe-Japan1; CID+1708 -6327 E0100; Adobe-Japan1; CID+4978 -6327 E0101; Hanyo-Denshi; JA5743 -6327 E0101; Moji_Joho; MJ012350 -6327 E0102; Hanyo-Denshi; FT2205 -6327 E0102; Moji_Joho; MJ012351 -6328 E0100; Adobe-Japan1; CID+1131 -6329 E0100; Adobe-Japan1; CID+21629 -632A E0100; Adobe-Japan1; CID+19390 -632B E0100; Adobe-Japan1; CID+2099 -632D E0100; Adobe-Japan1; CID+21630 -632F E0100; Adobe-Japan1; CID+2556 -6332 E0100; Adobe-Japan1; CID+17673 -6335 E0100; Adobe-Japan1; CID+17674 -6336 E0100; Adobe-Japan1; CID+19391 -6339 E0100; Adobe-Japan1; CID+14569 -633A E0100; Adobe-Japan1; CID+3086 -633A E0101; Adobe-Japan1; CID+20286 -633A E0102; Moji_Joho; MJ012371 -633A E0103; Moji_Joho; MJ012372 -633B E0100; Adobe-Japan1; CID+17675 -633C E0100; Adobe-Japan1; CID+17676 -633C E0101; Hanyo-Denshi; JB3174 -633C E0101; Moji_Joho; MJ012374 -633C E0102; Hanyo-Denshi; JTB1F2S -633C E0102; Moji_Joho; MJ012375 -633D E0100; Adobe-Japan1; CID+3432 -633D E0101; Adobe-Japan1; CID+7778 -633D E0102; Hanyo-Denshi; JA4052 -633D E0102; Moji_Joho; MJ012377 -633D E0103; Hanyo-Denshi; FT1905 -633D E0103; Moji_Joho; MJ012376 -633E E0100; Adobe-Japan1; CID+4984 -633F E0100; Adobe-Japan1; CID+2784 -6341 E0100; Adobe-Japan1; CID+17677 -6342 E0100; Adobe-Japan1; CID+14570 -6343 E0100; Adobe-Japan1; CID+14571 -6344 E0100; Adobe-Japan1; CID+17678 -6344 E0101; Hanyo-Denshi; JB3178 -6344 E0101; Moji_Joho; MJ012384 -6344 E0102; Hanyo-Denshi; JTB1E9 -6344 E0102; Moji_Joho; MJ012385 -6346 E0100; Adobe-Japan1; CID+19392 -6349 E0100; Adobe-Japan1; CID+2826 -634A E0100; Adobe-Japan1; CID+21631 -634A E0101; Hanyo-Denshi; JB3180 -634A E0102; Hanyo-Denshi; TK01035530 -634B E0100; Adobe-Japan1; CID+19393 -634B E0101; Hanyo-Denshi; JB3181 -634B E0101; Moji_Joho; MJ012393 -634B E0102; Hanyo-Denshi; JTB1F5 -634B E0102; Moji_Joho; MJ012394 -634B E0103; Hanyo-Denshi; JTB1F6 -634C E0100; Adobe-Japan1; CID+2169 -634C E0101; Adobe-Japan1; CID+13405 -634D E0100; Adobe-Japan1; CID+4985 -634D E0101; Moji_Joho; MJ012397 -634D E0102; Moji_Joho; MJ012398 -634E E0100; Adobe-Japan1; CID+17679 -634E E0101; Hanyo-Denshi; JB3182 -634E E0102; Hanyo-Denshi; TK01035540 -634F E0100; Adobe-Japan1; CID+4987 -6350 E0100; Adobe-Japan1; CID+4983 -6350 E0101; Hanyo-Denshi; JA5748 -6350 E0101; Moji_Joho; MJ012404 -6350 E0102; Hanyo-Denshi; KS135070 -6350 E0102; Moji_Joho; MJ012403 -6352 E0100; Adobe-Japan1; CID+21632 -6353 E0100; Adobe-Japan1; CID+19394 -6353 E0101; Hanyo-Denshi; JB3184 -6353 E0101; Moji_Joho; MJ012408 -6353 E0102; Hanyo-Denshi; JB3184S -6353 E0102; Moji_Joho; MJ012407 -6354 E0100; Adobe-Japan1; CID+21633 -6354 E0101; Hanyo-Denshi; JB3185 -6354 E0101; Moji_Joho; MJ012409 -6354 E0102; Hanyo-Denshi; JTB1F1 -6354 E0102; Moji_Joho; MJ012410 -6355 E0100; Adobe-Japan1; CID+3633 -6357 E0100; Adobe-Japan1; CID+3033 -6357 E0101; Adobe-Japan1; CID+7743 -6357 E0102; Hanyo-Denshi; JA3629 -6357 E0102; Moji_Joho; MJ012414 -6357 E0103; Hanyo-Denshi; FT1862 -6357 E0103; Moji_Joho; MJ012413 -6358 E0100; Adobe-Japan1; CID+21634 -6359 E0100; Adobe-Japan1; CID+17681 -635B E0100; Adobe-Japan1; CID+21635 -635C E0100; Adobe-Japan1; CID+2782 -6365 E0100; Adobe-Japan1; CID+14572 -6366 E0100; Adobe-Japan1; CID+21636 -6367 E0100; Adobe-Japan1; CID+3659 -6367 E0101; Adobe-Japan1; CID+13507 -6368 E0100; Adobe-Japan1; CID+2298 -6368 E0101; Adobe-Japan1; CID+13804 -6368 E0102; Hanyo-Denshi; JA2846 -6368 E0102; Moji_Joho; MJ012425 -6368 E0103; Hanyo-Denshi; JTB1F8 -6368 E0103; Moji_Joho; MJ012424 -6369 E0100; Adobe-Japan1; CID+4999 -6369 E0101; Adobe-Japan1; CID+7829 -6369 E0102; Hanyo-Denshi; JA5764 -6369 E0102; Moji_Joho; MJ012426 -6369 E0103; Hanyo-Denshi; FT1955 -6369 E0103; Moji_Joho; MJ012427 -636B E0100; Adobe-Japan1; CID+4998 -636C E0100; Adobe-Japan1; CID+17684 -636D E0100; Adobe-Japan1; CID+21637 -636E E0100; Adobe-Japan1; CID+2622 -636E E0101; Adobe-Japan1; CID+13469 -636E E0102; Moji_Joho; MJ012432 -636E E0103; Moji_Joho; MJ012433 -6371 E0100; Adobe-Japan1; CID+19395 -6372 E0100; Adobe-Japan1; CID+1876 -6372 E0101; Adobe-Japan1; CID+7676 -6372 E0102; Hanyo-Denshi; JA2394 -6372 E0102; Moji_Joho; MJ012438 -6372 E0103; Hanyo-Denshi; FT1792 -6372 E0103; Moji_Joho; MJ012437 -6374 E0100; Adobe-Japan1; CID+14573 -6375 E0100; Adobe-Japan1; CID+19396 -6376 E0100; Adobe-Japan1; CID+4992 -6377 E0100; Adobe-Japan1; CID+2465 -6378 E0100; Adobe-Japan1; CID+21638 -637A E0100; Adobe-Japan1; CID+3264 -637B E0100; Adobe-Japan1; CID+3303 -637C E0100; Adobe-Japan1; CID+16875 -637D E0100; Adobe-Japan1; CID+14574 -637F E0100; Adobe-Japan1; CID+19397 -6380 E0100; Adobe-Japan1; CID+4990 -6382 E0100; Adobe-Japan1; CID+19398 -6383 E0100; Adobe-Japan1; CID+2783 -6383 E0101; Adobe-Japan1; CID+13891 -6383 E0102; Hanyo-Denshi; JA3361 -6383 E0102; Moji_Joho; MJ012456 -6383 E0103; Hanyo-Denshi; JTB1F9 -6383 E0103; Moji_Joho; MJ012455 -6384 E0100; Adobe-Japan1; CID+14575 -6387 E0100; Adobe-Japan1; CID+14576 -6388 E0100; Adobe-Japan1; CID+2340 -6388 E0101; Adobe-Japan1; CID+13814 -6389 E0100; Adobe-Japan1; CID+4995 -638A E0100; Adobe-Japan1; CID+19399 -638C E0100; Adobe-Japan1; CID+2464 -638E E0100; Adobe-Japan1; CID+4989 -638F E0100; Adobe-Japan1; CID+4994 -6390 E0100; Adobe-Japan1; CID+14577 -6392 E0100; Adobe-Japan1; CID+3337 -6392 E0101; Adobe-Japan1; CID+13487 -6392 E0102; Moji_Joho; MJ012471 -6392 E0103; Moji_Joho; MJ012472 -6394 E0100; Adobe-Japan1; CID+17687 -6395 E0100; Adobe-Japan1; CID+21639 -6395 E0101; Hanyo-Denshi; JB3211 -6395 E0101; Moji_Joho; MJ012476 -6395 E0102; Hanyo-Denshi; KS137670 -6395 E0102; Moji_Joho; MJ012475 -6396 E0100; Adobe-Japan1; CID+4988 -6398 E0100; Adobe-Japan1; CID+1783 -6399 E0100; Adobe-Japan1; CID+17685 -639A E0100; Adobe-Japan1; CID+21640 -639B E0100; Adobe-Japan1; CID+1467 -639E E0100; Adobe-Japan1; CID+14578 -639F E0100; Adobe-Japan1; CID+4996 -63A0 E0100; Adobe-Japan1; CID+3955 -63A1 E0100; Adobe-Japan1; CID+2110 -63A1 E0101; Adobe-Japan1; CID+13784 -63A1 E0102; Hanyo-Denshi; JA2646 -63A1 E0102; Moji_Joho; MJ012489 -63A1 E0103; Hanyo-Denshi; JTB1FA -63A1 E0103; Moji_Joho; MJ012488 -63A2 E0100; Adobe-Japan1; CID+2931 -63A3 E0100; Adobe-Japan1; CID+4993 -63A4 E0100; Adobe-Japan1; CID+21641 -63A5 E0100; Adobe-Japan1; CID+2688 -63A6 E0100; Adobe-Japan1; CID+21642 -63A7 E0100; Adobe-Japan1; CID+1991 -63A7 E0101; Adobe-Japan1; CID+13766 -63A7 E0102; Hanyo-Denshi; JA2521 -63A7 E0102; Moji_Joho; MJ012495 -63A7 E0103; Hanyo-Denshi; JTB1FB -63A7 E0103; Moji_Joho; MJ012496 -63A8 E0100; Adobe-Japan1; CID+2602 -63A9 E0100; Adobe-Japan1; CID+1288 -63A9 E0101; Hanyo-Denshi; JA1770 -63A9 E0101; Moji_Joho; MJ012498 -63A9 E0102; Hanyo-Denshi; KS141850 -63A9 E0102; Moji_Joho; MJ012499 -63AA E0100; Adobe-Japan1; CID+2750 -63AB E0100; Adobe-Japan1; CID+4991 -63AC E0100; Adobe-Japan1; CID+1631 -63AD E0100; Adobe-Japan1; CID+21643 -63AE E0100; Adobe-Japan1; CID+19400 -63AF E0100; Adobe-Japan1; CID+19401 -63B2 E0100; Adobe-Japan1; CID+1821 -63B4 E0100; Adobe-Japan1; CID+3051 -63B5 E0100; Adobe-Japan1; CID+4997 -63BB E0100; Adobe-Japan1; CID+2785 -63BD E0100; Adobe-Japan1; CID+17688 -63BE E0100; Adobe-Japan1; CID+5000 -63BE E0101; Hanyo-Denshi; JA5765 -63BE E0101; Moji_Joho; MJ012513 -63BE E0102; Hanyo-Denshi; JTB203 -63BE E0102; Moji_Joho; MJ012514 -63BE E0103; Hanyo-Denshi; FT2207S -63BE E0103; Moji_Joho; MJ012515 -63C0 E0100; Adobe-Japan1; CID+5002 -63C1 E0100; Adobe-Japan1; CID+21644 -63C2 E0100; Hanyo-Denshi; IP63C2 -63C2 E0101; Hanyo-Denshi; TK01035780 -63C3 E0100; Adobe-Japan1; CID+2839 -63C3 E0101; Adobe-Japan1; CID+7975 -63C3 E0102; Hanyo-Denshi; JA3423 -63C3 E0102; Moji_Joho; MJ012522 -63C3 E0103; Hanyo-Denshi; HG1637 -63C3 E0103; Moji_Joho; MJ012521 -63C4 E0100; Adobe-Japan1; CID+5008 -63C4 E0101; Hanyo-Denshi; JA5773 -63C4 E0101; Moji_Joho; MJ012523 -63C4 E0102; Hanyo-Denshi; FT2209 -63C4 E0102; Moji_Joho; MJ012524 -63C5 E0100; Adobe-Japan1; CID+21645 -63C5 E0101; Hanyo-Denshi; JB3222 -63C5 E0101; Moji_Joho; MJ012525 -63C5 E0102; Hanyo-Denshi; JTB225 -63C5 E0102; Moji_Joho; MJ012527 -63C5 E0103; Hanyo-Denshi; JTB227 -63C5 E0103; Moji_Joho; MJ012526 -63C6 E0100; Adobe-Japan1; CID+5003 -63C6 E0101; Adobe-Japan1; CID+14132 -63C8 E0100; Adobe-Japan1; CID+21646 -63C9 E0100; Adobe-Japan1; CID+5005 -63CE E0100; Adobe-Japan1; CID+21647 -63CF E0100; Adobe-Japan1; CID+3507 -63CF E0101; Hanyo-Denshi; JA4133 -63CF E0101; Moji_Joho; MJ012537 -63CF E0102; Hanyo-Denshi; KS138640 -63CF E0102; Moji_Joho; MJ012538 -63D0 E0100; Adobe-Japan1; CID+3087 -63D1 E0100; Adobe-Japan1; CID+14579 -63D1 E0101; Hanyo-Denshi; JB3225 -63D1 E0101; Moji_Joho; MJ012540 -63D1 E0102; Hanyo-Denshi; KS139750 -63D1 E0102; Moji_Joho; MJ012402 -63D2 E0100; Adobe-Japan1; CID+5006 -63D3 E0100; Adobe-Japan1; CID+21648 -63D4 E0100; Adobe-Japan1; CID+17689 -63D5 E0100; Adobe-Japan1; CID+17690 -63D6 E0100; Adobe-Japan1; CID+3862 -63D6 E0101; Moji_Joho; MJ012545 -63D6 E0102; Moji_Joho; MJ012546 -63DA E0100; Adobe-Japan1; CID+3890 -63DA E0101; Hanyo-Denshi; JA4540 -63DA E0102; Hanyo-Denshi; TK01035720 -63DB E0100; Adobe-Japan1; CID+1525 -63DC E0100; Adobe-Japan1; CID+14580 -63DE E0100; Hanyo-Denshi; IP63DE -63DE E0100; Moji_Joho; MJ012554 -63DE E0101; Hanyo-Denshi; KS139740 -63DE E0101; Moji_Joho; MJ012555 -63E0 E0100; Adobe-Japan1; CID+17691 -63E0 E0101; Hanyo-Denshi; JB3230 -63E0 E0101; Moji_Joho; MJ012557 -63E0 E0102; Hanyo-Denshi; KS139770 -63E0 E0102; Moji_Joho; MJ012558 -63E1 E0100; Adobe-Japan1; CID+1138 -63E3 E0100; Adobe-Japan1; CID+5004 -63E5 E0100; Adobe-Japan1; CID+16876 -63E5 E0101; Hanyo-Denshi; JB3231 -63E5 E0101; Moji_Joho; MJ012563 -63E5 E0102; Hanyo-Denshi; KS139670 -63E5 E0102; Moji_Joho; MJ012564 -63E9 E0100; Adobe-Japan1; CID+5001 -63EA E0100; Adobe-Japan1; CID+19402 -63EB E0100; Adobe-Japan1; CID+17692 -63EC E0100; Adobe-Japan1; CID+17693 -63EC E0101; Hanyo-Denshi; JB3233 -63EC E0102; Hanyo-Denshi; TK01035650 -63ED E0100; Adobe-Japan1; CID+13340 -63EE E0100; Adobe-Japan1; CID+1588 -63F2 E0100; Adobe-Japan1; CID+17694 -63F3 E0100; Adobe-Japan1; CID+21649 -63F3 E0101; Hanyo-Denshi; JB3235 -63F3 E0101; Moji_Joho; MJ012579 -63F3 E0102; Hanyo-Denshi; JTB20B -63F3 E0102; Moji_Joho; MJ012580 -63F3 E0103; Hanyo-Denshi; KS139660 -63F3 E0103; Moji_Joho; MJ057561 -63F4 E0100; Adobe-Japan1; CID+1289 -63F4 E0101; Adobe-Japan1; CID+13655 -63F4 E0102; Hanyo-Denshi; JA1771 -63F4 E0102; Moji_Joho; MJ012582 -63F4 E0103; Hanyo-Denshi; JTB202S -63F4 E0103; Moji_Joho; MJ012581 -63F5 E0100; Adobe-Japan1; CID+8467 -63F5 E0101; Moji_Joho; MJ012583 -63F5 E0102; Moji_Joho; MJ012584 -63F6 E0100; Adobe-Japan1; CID+5007 -63F7 E0100; Adobe-Japan1; CID+13892 -63F8 E0100; Adobe-Japan1; CID+19403 -63F9 E0100; Adobe-Japan1; CID+19404 -63FA E0100; Adobe-Japan1; CID+3891 -6406 E0100; Adobe-Japan1; CID+5011 -6406 E0101; Adobe-Japan1; CID+7830 -6406 E0102; Hanyo-Denshi; JA5776 -6406 E0102; Moji_Joho; MJ012591 -6406 E0103; Hanyo-Denshi; FT1956 -6406 E0103; Moji_Joho; MJ012592 -6409 E0100; Adobe-Japan1; CID+14581 -640A E0100; Adobe-Japan1; CID+21650 -640D E0100; Adobe-Japan1; CID+2843 -640D E0101; Hanyo-Denshi; JA3427 -640D E0101; Moji_Joho; MJ012600 -640D E0102; Hanyo-Denshi; KS139720 -640D E0102; Moji_Joho; MJ012599 -640F E0100; Adobe-Japan1; CID+5018 -640F E0101; Adobe-Japan1; CID+13545 -640F E0102; Hanyo-Denshi; JA5783 -640F E0102; Moji_Joho; MJ012602 -640F E0103; Hanyo-Denshi; FT2213 -640F E0103; Moji_Joho; MJ012603 -6410 E0100; Adobe-Japan1; CID+14582 -6412 E0100; Adobe-Japan1; CID+19405 -6412 E0101; Hanyo-Denshi; JB3242 -6412 E0101; Moji_Joho; MJ012606 -6412 E0102; Hanyo-Denshi; KS140930 -6412 E0102; Moji_Joho; MJ012607 -6413 E0100; Adobe-Japan1; CID+5012 -6414 E0100; Adobe-Japan1; CID+7724 -6416 E0100; Adobe-Japan1; CID+5009 -6417 E0100; Adobe-Japan1; CID+5016 -6418 E0100; Adobe-Japan1; CID+19406 -641C E0100; Adobe-Japan1; CID+4986 -641C E0101; Adobe-Japan1; CID+14131 -641C E0102; Hanyo-Denshi; JA5751 -641C E0102; Moji_Joho; MJ012617 -641C E0103; Hanyo-Denshi; JTB20E -641C E0103; Moji_Joho; MJ012618 -641E E0100; Adobe-Japan1; CID+17695 -6420 E0100; Adobe-Japan1; CID+19407 -6422 E0100; Adobe-Japan1; CID+14583 -6422 E0101; Hanyo-Denshi; JB3247 -6422 E0101; Moji_Joho; MJ012624 -6422 E0102; Hanyo-Denshi; IB1942 -6422 E0102; Moji_Joho; MJ012625 -6424 E0100; Adobe-Japan1; CID+19408 -6424 E0101; Hanyo-Denshi; JB3248 -6424 E0101; Moji_Joho; MJ012628 -6424 E0102; Hanyo-Denshi; IB1941 -6424 E0102; Moji_Joho; MJ012627 -6425 E0100; Adobe-Japan1; CID+17696 -6425 E0101; Hanyo-Denshi; JB3249 -6425 E0101; Moji_Joho; MJ012630 -6425 E0102; Hanyo-Denshi; JTB200 -6425 E0102; Moji_Joho; MJ012629 -6426 E0100; Adobe-Japan1; CID+5013 -6426 E0101; Hanyo-Denshi; JA5778 -6426 E0101; Moji_Joho; MJ012631 -6426 E0102; Hanyo-Denshi; FT2210 -6426 E0102; Moji_Joho; MJ012632 -6428 E0100; Adobe-Japan1; CID+5017 -6428 E0101; Adobe-Japan1; CID+14133 -6428 E0102; Hanyo-Denshi; JA5782 -6428 E0102; Moji_Joho; MJ012635 -6428 E0103; Hanyo-Denshi; FT2212 -6428 E0103; Moji_Joho; MJ012636 -6428 E0104; Hanyo-Denshi; JTB212S -6428 E0104; Moji_Joho; MJ012634 -6429 E0100; Adobe-Japan1; CID+17697 -6429 E0101; Hanyo-Denshi; JB3250 -6429 E0101; Moji_Joho; MJ012638 -6429 E0102; Hanyo-Denshi; KS140410 -6429 E0102; Moji_Joho; MJ012637 -642A E0100; Adobe-Japan1; CID+19409 -642C E0100; Adobe-Japan1; CID+3414 -642D E0100; Adobe-Japan1; CID+3173 -642D E0101; Hanyo-Denshi; JA3775 -642D E0101; Moji_Joho; MJ012642 -642D E0102; Hanyo-Denshi; KS140440 -642D E0102; Moji_Joho; MJ012643 -642F E0100; Adobe-Japan1; CID+17698 -642F E0101; Hanyo-Denshi; JB3252 -642F E0102; Hanyo-Denshi; TK01036000 -6430 E0100; Adobe-Japan1; CID+21651 -6434 E0100; Adobe-Japan1; CID+5010 -6435 E0100; Adobe-Japan1; CID+19410 -6436 E0100; Adobe-Japan1; CID+5014 -643A E0100; Adobe-Japan1; CID+1822 -643D E0100; Adobe-Japan1; CID+19411 -643D E0101; Hanyo-Denshi; JB3255 -643D E0101; Moji_Joho; MJ012660 -643D E0102; Hanyo-Denshi; KS140980 -643D E0102; Moji_Joho; MJ012661 -643E E0100; Adobe-Japan1; CID+2145 -643F E0100; Adobe-Japan1; CID+19412 -6442 E0100; Adobe-Japan1; CID+2689 -6442 E0101; Adobe-Japan1; CID+13470 -6442 E0102; Moji_Joho; MJ012666 -6442 E0103; Moji_Joho; MJ012667 -644B E0100; Adobe-Japan1; CID+21652 -644E E0100; Adobe-Japan1; CID+5022 -644E E0101; Hanyo-Denshi; JA5787 -644E E0101; Moji_Joho; MJ012671 -644E E0102; Hanyo-Denshi; FT2214 -644E E0102; Moji_Joho; MJ012672 -644F E0100; Adobe-Japan1; CID+21653 -6451 E0100; Adobe-Japan1; CID+7747 -6452 E0100; Adobe-Japan1; CID+19413 -6452 E0101; Hanyo-Denshi; JB3260 -6452 E0101; Moji_Joho; MJ012677 -6452 E0102; Hanyo-Denshi; IB1935 -6452 E0102; Moji_Joho; MJ012676 -6453 E0100; Adobe-Japan1; CID+21654 -6453 E0101; Hanyo-Denshi; JB3261 -6453 E0101; Moji_Joho; MJ012679 -6453 E0102; Hanyo-Denshi; IB0691 -6453 E0102; Moji_Joho; MJ012678 -6454 E0100; Adobe-Japan1; CID+14584 -6455 E0100; Moji_Joho; MJ012681 -6455 E0101; Moji_Joho; MJ012682 -6458 E0100; Adobe-Japan1; CID+3104 -6458 E0101; Hanyo-Denshi; JA3706 -6458 E0101; Moji_Joho; MJ012685 -6458 E0102; Hanyo-Denshi; JTB21C -6458 E0102; Moji_Joho; MJ012686 -6459 E0100; Hanyo-Denshi; IB0692 -6459 E0100; Moji_Joho; MJ012687 -6459 E0101; Hanyo-Denshi; IP6459 -6459 E0101; Moji_Joho; MJ012688 -645A E0100; Adobe-Japan1; CID+17699 -645B E0100; Adobe-Japan1; CID+14585 -645B E0101; Hanyo-Denshi; JB3264 -645B E0101; Moji_Joho; MJ012690 -645B E0102; Hanyo-Denshi; KS142170 -645B E0102; Moji_Joho; MJ057570 -645C E0100; Adobe-Japan1; CID+21655 -645D E0100; Adobe-Japan1; CID+17700 -645F E0100; Adobe-Japan1; CID+19414 -6460 E0100; Adobe-Japan1; CID+8468 -6460 E0101; Hanyo-Denshi; JB3268 -6460 E0101; Moji_Joho; MJ012695 -6460 E0102; Hanyo-Denshi; JTB21D -6460 E0102; Moji_Joho; MJ012696 -6460 E0103; Hanyo-Denshi; IB1946 -6460 E0103; Moji_Joho; MJ012697 -6461 E0100; Adobe-Japan1; CID+21656 -6461 E0101; Hanyo-Denshi; JB3269 -6461 E0101; Moji_Joho; MJ012699 -6461 E0102; Hanyo-Denshi; KS141420 -6461 E0102; Moji_Joho; MJ012698 -6463 E0100; Adobe-Japan1; CID+21657 -6466 E0100; Hanyo-Denshi; IP6466 -6466 E0100; Moji_Joho; MJ012705 -6466 E0101; Hanyo-Denshi; KS142140 -6466 E0101; Moji_Joho; MJ012704 -6467 E0100; Adobe-Japan1; CID+5019 -6469 E0100; Adobe-Japan1; CID+3726 -6469 E0101; Adobe-Japan1; CID+14039 -6469 E0102; Hanyo-Denshi; JA4364 -6469 E0102; Moji_Joho; MJ012709 -6469 E0103; Hanyo-Denshi; JTB21A -6469 E0103; Moji_Joho; MJ012708 -646D E0100; Adobe-Japan1; CID+14586 -646D E0101; Hanyo-Denshi; JB3271 -646D E0101; Moji_Joho; MJ012713 -646D E0102; Hanyo-Denshi; JTB220 -646D E0102; Moji_Joho; MJ012714 -646F E0100; Adobe-Japan1; CID+5020 -646F E0101; Adobe-Japan1; CID+20264 -6473 E0100; Adobe-Japan1; CID+17701 -6473 E0101; Hanyo-Denshi; JB3272 -6473 E0101; Moji_Joho; MJ012720 -6473 E0102; Hanyo-Denshi; KS142160 -6473 E0102; Moji_Joho; MJ012721 -6474 E0100; Adobe-Japan1; CID+19415 -6476 E0100; Adobe-Japan1; CID+5021 -6477 E0100; Hanyo-Denshi; IP6477 -6477 E0100; Moji_Joho; MJ012725 -6477 E0101; Hanyo-Denshi; KS144260 -6477 E0101; Moji_Joho; MJ012726 -6478 E0100; Adobe-Japan1; CID+3802 -6478 E0101; Hanyo-Denshi; JA4446 -6478 E0101; Moji_Joho; MJ012727 -6478 E0102; Hanyo-Denshi; KS141770 -6478 E0102; Moji_Joho; MJ012728 -6479 E0100; Adobe-Japan1; CID+16877 -6479 E0101; Hanyo-Denshi; JC8488 -6479 E0101; Moji_Joho; MJ012730 -6479 E0102; Hanyo-Denshi; KS142300 -6479 E0102; Moji_Joho; MJ012729 -647A E0100; Adobe-Japan1; CID+2630 -647A E0101; Adobe-Japan1; CID+7713 -647A E0102; Hanyo-Denshi; JA3202 -647A E0102; Moji_Joho; MJ012733 -647A E0103; Hanyo-Denshi; FT1834 -647A E0103; Moji_Joho; MJ012732 -647B E0100; Adobe-Japan1; CID+14587 -647D E0100; Adobe-Japan1; CID+17702 -6483 E0100; Adobe-Japan1; CID+1848 -6485 E0100; Adobe-Japan1; CID+21658 -6487 E0100; Adobe-Japan1; CID+17703 -6488 E0100; Adobe-Japan1; CID+5028 -648F E0100; Adobe-Japan1; CID+21659 -6490 E0100; Adobe-Japan1; CID+19416 -6490 E0101; Hanyo-Denshi; JB3279 -6490 E0101; Moji_Joho; MJ012755 -6490 E0102; Hanyo-Denshi; JTB22B -6490 E0102; Moji_Joho; MJ012754 -6490 E0103; Moji_Joho; MJ012756 -6491 E0100; Adobe-Japan1; CID+17704 -6492 E0100; Adobe-Japan1; CID+2179 -6493 E0100; Adobe-Japan1; CID+5025 -6495 E0100; Adobe-Japan1; CID+5024 -6497 E0100; Hanyo-Denshi; IP6497 -6497 E0101; Hanyo-Denshi; TK01036110 -6497 E0102; Hanyo-Denshi; TK01036130 -6498 E0100; Adobe-Japan1; CID+19417 -6499 E0100; Adobe-Japan1; CID+19418 -649A E0100; Adobe-Japan1; CID+3304 -649B E0100; Adobe-Japan1; CID+21660 -649B E0101; Hanyo-Denshi; JB3283 -649B E0101; Moji_Joho; MJ012768 -649B E0102; Hanyo-Denshi; KS142710 -649B E0102; Moji_Joho; MJ012767 -649D E0100; Adobe-Japan1; CID+8469 -649E E0100; Adobe-Japan1; CID+3213 -649E E0101; Hanyo-Denshi; JA3821 -649E E0101; Moji_Joho; MJ012771 -649E E0102; Hanyo-Denshi; KS143320 -649E E0102; Moji_Joho; MJ012772 -649F E0100; Adobe-Japan1; CID+17705 -64A1 E0100; Adobe-Japan1; CID+21661 -64A2 E0100; Hanyo-Denshi; IP64A2 -64A2 E0100; Moji_Joho; MJ012776 -64A2 E0101; Hanyo-Denshi; KS143370 -64A2 E0101; Moji_Joho; MJ012777 -64A3 E0100; Adobe-Japan1; CID+21662 -64A4 E0100; Adobe-Japan1; CID+3115 -64A5 E0100; Adobe-Japan1; CID+5026 -64A6 E0100; Adobe-Japan1; CID+21663 -64A8 E0100; Adobe-Japan1; CID+21664 -64A9 E0100; Adobe-Japan1; CID+5027 -64AB E0100; Adobe-Japan1; CID+3553 -64AC E0100; Adobe-Japan1; CID+19419 -64AD E0100; Adobe-Japan1; CID+3323 -64AE E0100; Adobe-Japan1; CID+2161 -64B0 E0100; Adobe-Japan1; CID+2709 -64B0 E0101; Adobe-Japan1; CID+7716 -64B0 E0102; Hanyo-Denshi; JA3281 -64B0 E0102; Moji_Joho; MJ012792 -64B0 E0103; Hanyo-Denshi; FT1837 -64B0 E0103; Moji_Joho; MJ012791 -64B2 E0100; Adobe-Japan1; CID+3710 -64B3 E0100; Adobe-Japan1; CID+19420 -64B9 E0100; Adobe-Japan1; CID+1447 -64B9 E0101; Hanyo-Denshi; JA1941 -64B9 E0101; Moji_Joho; MJ012797 -64B9 E0102; Hanyo-Denshi; JTB22DS -64B9 E0102; Moji_Joho; MJ012798 -64BB E0100; Adobe-Japan1; CID+5034 -64BB E0101; Hanyo-Denshi; JA5805 -64BB E0101; Moji_Joho; MJ012800 -64BB E0102; Hanyo-Denshi; FT2217 -64BB E0102; Moji_Joho; MJ012799 -64BC E0100; Adobe-Japan1; CID+5029 -64BD E0100; Adobe-Japan1; CID+21665 -64BE E0100; Adobe-Japan1; CID+14588 -64BE E0101; Hanyo-Denshi; JB3293 -64BE E0101; Moji_Joho; MJ012804 -64BE E0102; Hanyo-Denshi; IB0693 -64BE E0102; Moji_Joho; MJ012803 -64BF E0100; Adobe-Japan1; CID+14589 -64C1 E0100; Adobe-Japan1; CID+3892 -64C2 E0100; Adobe-Japan1; CID+5036 -64C4 E0100; Adobe-Japan1; CID+16878 -64C4 E0101; Hanyo-Denshi; JB3301 -64C4 E0101; Moji_Joho; MJ012810 -64C4 E0102; Hanyo-Denshi; JTB230 -64C4 E0102; Moji_Joho; MJ012811 -64C5 E0100; Adobe-Japan1; CID+5032 -64C7 E0100; Adobe-Japan1; CID+5033 -64C9 E0100; Adobe-Japan1; CID+21666 -64CA E0100; Adobe-Japan1; CID+13341 -64CA E0101; Hanyo-Denshi; JB3303 -64CA E0102; Hanyo-Denshi; TK01036180 -64CB E0100; Adobe-Japan1; CID+17706 -64CC E0100; Adobe-Japan1; CID+17707 -64CD E0100; Adobe-Japan1; CID+2786 -64CD E0101; Hanyo-Denshi; JA3364 -64CD E0101; Moji_Joho; MJ012820 -64CD E0102; Hanyo-Denshi; JTB21FS -64CD E0102; Moji_Joho; MJ059648 -64CE E0100; Adobe-Japan1; CID+8470 -64CE E0101; Hanyo-Denshi; JB3306 -64CE E0101; Moji_Joho; MJ012821 -64CE E0102; Hanyo-Denshi; KS144230S -64CE E0102; Moji_Joho; MJ012822 -64D0 E0100; Adobe-Japan1; CID+16879 -64D1 E0100; Adobe-Japan1; CID+21667 -64D2 E0100; Adobe-Japan1; CID+5031 -64D2 E0101; Hanyo-Denshi; JA5802 -64D2 E0101; Moji_Joho; MJ012826 -64D2 E0102; Hanyo-Denshi; KS144180 -64D2 E0102; Moji_Joho; MJ012827 -64D4 E0100; Adobe-Japan1; CID+4966 -64D5 E0100; Adobe-Japan1; CID+17708 -64D7 E0100; Adobe-Japan1; CID+17709 -64D8 E0100; Adobe-Japan1; CID+5035 -64DA E0100; Adobe-Japan1; CID+5030 -64DA E0101; Hanyo-Denshi; JA5801 -64DA E0101; Moji_Joho; MJ012835 -64DA E0102; Hanyo-Denshi; FT2216 -64DA E0102; Moji_Joho; MJ012836 -64DA E0103; Moji_Joho; MJ012837 -64E0 E0100; Adobe-Japan1; CID+5040 -64E1 E0100; Adobe-Japan1; CID+5041 -64E2 E0100; Adobe-Japan1; CID+3105 -64E2 E0101; Adobe-Japan1; CID+7749 -64E2 E0102; Hanyo-Denshi; JA3707 -64E2 E0102; Moji_Joho; MJ012843 -64E2 E0103; Hanyo-Denshi; FT1869 -64E2 E0103; Moji_Joho; MJ012842 -64E3 E0100; Adobe-Japan1; CID+5043 -64E4 E0100; Adobe-Japan1; CID+17711 -64E4 E0101; Hanyo-Denshi; JB3311 -64E4 E0101; Moji_Joho; MJ012845 -64E4 E0102; Hanyo-Denshi; JTB239 -64E4 E0102; Moji_Joho; MJ012846 -64E5 E0100; Adobe-Japan1; CID+14590 -64E6 E0100; Adobe-Japan1; CID+2162 -64E7 E0100; Adobe-Japan1; CID+5038 -64E9 E0100; Adobe-Japan1; CID+21668 -64EA E0100; Adobe-Japan1; CID+21669 -64EA E0101; Hanyo-Denshi; JB3314 -64EA E0101; Moji_Joho; MJ012852 -64EA E0102; Hanyo-Denshi; JTAE93 -64EA E0102; Moji_Joho; MJ012854 -64EA E0103; Hanyo-Denshi; KS145320 -64EA E0103; Moji_Joho; MJ012853 -64EC E0100; Adobe-Japan1; CID+1622 -64ED E0100; Adobe-Japan1; CID+19421 -64ED E0101; Hanyo-Denshi; JB3315 -64ED E0101; Moji_Joho; MJ012857 -64ED E0102; Hanyo-Denshi; KS144530 -64ED E0102; Moji_Joho; MJ012858 -64EF E0100; Adobe-Japan1; CID+5044 -64EF E0101; Hanyo-Denshi; JA5815 -64EF E0101; Moji_Joho; MJ012860 -64EF E0102; Hanyo-Denshi; FT2218S -64EF E0102; Moji_Joho; MJ012861 -64F0 E0100; Adobe-Japan1; CID+19422 -64F1 E0100; Adobe-Japan1; CID+5037 -64F2 E0100; Adobe-Japan1; CID+5048 -64F2 E0101; Adobe-Japan1; CID+13546 -64F2 E0102; Hanyo-Denshi; JA5819 -64F2 E0102; Moji_Joho; MJ012864 -64F2 E0103; Hanyo-Denshi; FT2221 -64F2 E0103; Moji_Joho; MJ012866 -64F2 E0104; Hanyo-Denshi; FT1692 -64F2 E0104; Moji_Joho; MJ012867 -64F2 E0105; Moji_Joho; MJ012865 -64F4 E0100; Adobe-Japan1; CID+5047 -64F4 E0101; Hanyo-Denshi; JA5818 -64F4 E0101; Moji_Joho; MJ012869 -64F4 E0102; Hanyo-Denshi; FT2220 -64F4 E0102; Moji_Joho; MJ012870 -64F4 E0103; Hanyo-Denshi; TK01036210 -64F4 E0104; Hanyo-Denshi; TK01036220 -64F4 E0105; Hanyo-Denshi; TK01036270 -64F5 E0100; Adobe-Japan1; CID+21670 -64F6 E0100; Adobe-Japan1; CID+5046 -64F6 E0101; Adobe-Japan1; CID+20126 -64F6 E0102; Hanyo-Denshi; JA5817 -64F6 E0102; Moji_Joho; MJ012876 -64F6 E0103; Hanyo-Denshi; JTB23B -64F6 E0103; Moji_Joho; MJ012875 -64F7 E0100; Adobe-Japan1; CID+14591 -64FA E0100; Adobe-Japan1; CID+5049 -64FB E0100; Adobe-Japan1; CID+14592 -64FD E0100; Adobe-Japan1; CID+5051 -64FE E0100; Adobe-Japan1; CID+2521 -64FF E0100; Adobe-Japan1; CID+17712 -64FF E0101; Hanyo-Denshi; JB3320 -64FF E0101; Moji_Joho; MJ012887 -64FF E0102; Hanyo-Denshi; IB0694 -64FF E0102; Moji_Joho; MJ012886 -64FF E0103; Hanyo-Denshi; KS145310 -64FF E0103; Moji_Joho; MJ012888 -6500 E0100; Adobe-Japan1; CID+5050 -6501 E0100; Adobe-Japan1; CID+21671 -6504 E0100; Adobe-Japan1; CID+14593 -6505 E0100; Adobe-Japan1; CID+5054 -6507 E0100; Hanyo-Denshi; IP6507 -6507 E0100; Moji_Joho; MJ012896 -6507 E0101; Hanyo-Denshi; KS145660 -6507 E0101; Moji_Joho; MJ012897 -6508 E0100; Adobe-Japan1; CID+21672 -6509 E0100; Adobe-Japan1; CID+21673 -650A E0100; Adobe-Japan1; CID+21674 -650F E0100; Adobe-Japan1; CID+17714 -650F E0101; Hanyo-Denshi; JB3326 -650F E0101; Moji_Joho; MJ012905 -650F E0102; Hanyo-Denshi; KS145650 -650F E0102; Moji_Joho; MJ012906 -6513 E0100; Adobe-Japan1; CID+21675 -6514 E0100; Adobe-Japan1; CID+17715 -6514 E0101; Hanyo-Denshi; JB3328 -6514 E0101; Moji_Joho; MJ012909 -6514 E0102; Hanyo-Denshi; JTB23F -6514 E0102; Moji_Joho; MJ012910 -6516 E0100; Adobe-Japan1; CID+14594 -6518 E0100; Adobe-Japan1; CID+5052 -6519 E0100; Adobe-Japan1; CID+14595 -651B E0100; Adobe-Japan1; CID+19423 -651C E0100; Adobe-Japan1; CID+5053 -651D E0100; Adobe-Japan1; CID+5015 -651D E0101; Adobe-Japan1; CID+13544 -651D E0102; Hanyo-Denshi; JA5780 -651D E0102; Moji_Joho; MJ012918 -651D E0103; Hanyo-Denshi; JTC0E6 -651D E0103; Moji_Joho; MJ012921 -651D E0104; Moji_Joho; MJ012919 -651D E0105; Moji_Joho; MJ012920 -651E E0100; Adobe-Japan1; CID+17717 -651F E0100; Adobe-Japan1; CID+19424 -6522 E0100; Adobe-Japan1; CID+7831 -6523 E0100; Adobe-Japan1; CID+5056 -6524 E0100; Adobe-Japan1; CID+5055 -6524 E0101; Hanyo-Denshi; JA5826 -6524 E0101; Moji_Joho; MJ012928 -6524 E0102; Hanyo-Denshi; FT2224 -6524 E0102; Moji_Joho; MJ012929 -6526 E0100; Adobe-Japan1; CID+21676 -6529 E0100; Adobe-Japan1; CID+16880 -652A E0100; Adobe-Japan1; CID+5023 -652B E0100; Adobe-Japan1; CID+5057 -652C E0100; Adobe-Japan1; CID+5045 -652C E0101; Hanyo-Denshi; JA5816 -652C E0101; Moji_Joho; MJ012936 -652C E0102; Hanyo-Denshi; JTB244S -652C E0102; Moji_Joho; MJ012937 -652E E0100; Adobe-Japan1; CID+19425 -652F E0100; Adobe-Japan1; CID+2215 -652F E0101; Moji_Joho; MJ012940 -652F E0102; Moji_Joho; MJ012941 -6531 E0100; Adobe-Japan1; CID+21677 -6532 E0100; Adobe-Japan1; CID+17718 -6534 E0100; Adobe-Japan1; CID+5058 -6534 E0101; Hanyo-Denshi; JA5829 -6534 E0102; Hanyo-Denshi; KS146620 -6535 E0100; Adobe-Japan1; CID+5059 -6535 E0101; Hanyo-Denshi; JA5830 -6535 E0102; Hanyo-Denshi; TK01036470 -6536 E0100; Adobe-Japan1; CID+5061 -6537 E0100; Adobe-Japan1; CID+5060 -6538 E0100; Adobe-Japan1; CID+5062 -6538 E0101; Hanyo-Denshi; JA5833 -6538 E0101; Moji_Joho; MJ012953 -6538 E0102; Hanyo-Denshi; KS005620 -6538 E0102; Moji_Joho; MJ012952 -6539 E0100; Adobe-Japan1; CID+1406 -653A E0100; Adobe-Japan1; CID+21678 -653B E0100; Adobe-Japan1; CID+1992 -653C E0100; Adobe-Japan1; CID+21679 -653D E0100; Adobe-Japan1; CID+21680 -653E E0100; Adobe-Japan1; CID+3660 -653F E0100; Adobe-Japan1; CID+2643 -653F E0101; Moji_Joho; MJ012960 -653F E0102; Moji_Joho; MJ012961 -6543 E0100; Adobe-Japan1; CID+21681 -6544 E0100; Adobe-Japan1; CID+17719 -6545 E0100; Adobe-Japan1; CID+1922 -6547 E0100; Adobe-Japan1; CID+14596 -6548 E0100; Adobe-Japan1; CID+5064 -6549 E0100; Adobe-Japan1; CID+19426 -654D E0100; Adobe-Japan1; CID+5067 -654E E0100; Adobe-Japan1; CID+8471 -654F E0100; Adobe-Japan1; CID+13381 -654F E0101; Adobe-Japan1; CID+3524 -654F E0102; Hanyo-Denshi; JA4150 -654F E0103; Hanyo-Denshi; JC8508 -6550 E0100; Adobe-Japan1; CID+21682 -6551 E0100; Adobe-Japan1; CID+1657 -6551 E0101; Hanyo-Denshi; JA2163 -6551 E0102; Hanyo-Denshi; TK01036590 -6552 E0100; Adobe-Japan1; CID+21683 -6554 E0100; Adobe-Japan1; CID+17720 -6555 E0100; Adobe-Japan1; CID+5066 -6556 E0100; Adobe-Japan1; CID+5065 -6557 E0100; Adobe-Japan1; CID+3338 -6558 E0100; Adobe-Japan1; CID+5068 -6559 E0100; Adobe-Japan1; CID+1709 -655D E0100; Adobe-Japan1; CID+5070 -655D E0101; Adobe-Japan1; CID+13547 -655D E0102; Hanyo-Denshi; JA5841 -655D E0102; Moji_Joho; MJ012989 -655D E0103; Hanyo-Denshi; FT1693 -655D E0103; Moji_Joho; MJ012990 -655D E0104; Hanyo-Denshi; FT2226S -655D E0104; Moji_Joho; MJ012991 -655E E0100; Adobe-Japan1; CID+5069 -655E E0101; Adobe-Japan1; CID+20129 -655E E0102; Hanyo-Denshi; JA5840 -655E E0102; Moji_Joho; MJ012992 -655E E0103; Hanyo-Denshi; JTB248 -655E E0103; Moji_Joho; MJ012993 -655F E0100; Adobe-Japan1; CID+21684 -6560 E0100; Adobe-Japan1; CID+19427 -6562 E0100; Adobe-Japan1; CID+1526 -6562 E0101; Adobe-Japan1; CID+13425 -6562 E0102; Hanyo-Denshi; JA2026 -6562 E0102; Moji_Joho; MJ012997 -6562 E0103; Hanyo-Denshi; KS148260S -6562 E0103; Moji_Joho; MJ057594 -6563 E0100; Adobe-Japan1; CID+2180 -6566 E0100; Adobe-Japan1; CID+3248 -6566 E0101; Hanyo-Denshi; JA3856 -6566 E0101; Moji_Joho; MJ013001 -6566 E0102; Hanyo-Denshi; KS149270S -6566 E0102; Moji_Joho; MJ057608 -6567 E0100; Adobe-Japan1; CID+14597 -6569 E0100; Hanyo-Denshi; IB1966 -6569 E0101; Hanyo-Denshi; TK01036750 -656B E0100; Adobe-Japan1; CID+17721 -656C E0100; Adobe-Japan1; CID+1823 -656C E0101; Hanyo-Denshi; JA2341 -656C E0101; Moji_Joho; MJ013006 -656C E0102; Hanyo-Denshi; JTB24DS -656C E0102; Moji_Joho; MJ013007 -656C E0103; Hanyo-Denshi; TK01036810 -656D E0100; Hanyo-Denshi; IP656D -656D E0101; Hanyo-Denshi; TK01036880 -6570 E0100; Adobe-Japan1; CID+2618 -6572 E0100; Adobe-Japan1; CID+5071 -6572 E0101; Hanyo-Denshi; JA5842 -6572 E0101; Moji_Joho; MJ013015 -6572 E0102; Hanyo-Denshi; JTB24F -6572 E0102; Moji_Joho; MJ013016 -6574 E0100; Adobe-Japan1; CID+2644 -6575 E0100; Adobe-Japan1; CID+3106 -6575 E0101; Hanyo-Denshi; JA3708 -6575 E0101; Moji_Joho; MJ013018 -6575 E0102; Hanyo-Denshi; JTB256 -6575 E0102; Moji_Joho; MJ013019 -6577 E0100; Adobe-Japan1; CID+3537 -6577 E0101; Adobe-Japan1; CID+14003 -6577 E0102; Hanyo-Denshi; JA4163 -6577 E0102; Moji_Joho; MJ013022 -6577 E0103; Hanyo-Denshi; JTB252 -6577 E0103; Moji_Joho; MJ013021 -6578 E0100; Adobe-Japan1; CID+5072 -6578 E0101; Hanyo-Denshi; JA5843 -6578 E0101; Moji_Joho; MJ013023 -6578 E0102; Hanyo-Denshi; JTB250S -6578 E0102; Moji_Joho; MJ059656 -6578 E0103; Hanyo-Denshi; TK01037020 -6578 E0104; Moji_Joho; MJ013024 -657A E0100; Adobe-Japan1; CID+17722 -657A E0101; Hanyo-Denshi; JB3352 -657A E0101; Moji_Joho; MJ013026 -657A E0102; Hanyo-Denshi; KS149950 -657A E0102; Moji_Joho; MJ013027 -657D E0100; Adobe-Japan1; CID+21685 -6581 E0100; Adobe-Japan1; CID+14598 -6581 E0101; Hanyo-Denshi; JB3354 -6581 E0101; Moji_Joho; MJ013031 -6581 E0102; Hanyo-Denshi; JTB258 -6581 E0102; Moji_Joho; MJ013032 -6582 E0100; Adobe-Japan1; CID+5073 -6583 E0100; Adobe-Japan1; CID+5074 -6583 E0101; Adobe-Japan1; CID+7832 -6583 E0102; Hanyo-Denshi; JA5845 -6583 E0102; Moji_Joho; MJ013034 -6583 E0103; Hanyo-Denshi; JTB25B -6583 E0103; Moji_Joho; MJ013036 -6583 E0104; Hanyo-Denshi; JTB259S -6583 E0104; Moji_Joho; MJ013035 -6584 E0100; Adobe-Japan1; CID+17723 -6585 E0100; Adobe-Japan1; CID+14599 -6587 E0100; Adobe-Japan1; CID+3592 -6587 E0101; Adobe-Japan1; CID+20131 -6587 E0102; Moji_Joho; MJ013040 -6587 E0103; Moji_Joho; MJ013041 -6588 E0100; Adobe-Japan1; CID+4620 -6588 E0101; Moji_Joho; MJ013042 -6588 E0102; Moji_Joho; MJ013043 -6589 E0100; Adobe-Japan1; CID+2666 -6589 E0101; Adobe-Japan1; CID+20132 -6589 E0102; Moji_Joho; MJ013044 -6589 E0103; Moji_Joho; MJ059659 -658A E0100; Adobe-Japan1; CID+17724 -658C E0100; Adobe-Japan1; CID+3518 -658E E0100; Adobe-Japan1; CID+2120 -658E E0101; Adobe-Japan1; CID+20134 -658E E0102; Moji_Joho; MJ013049 -658E E0103; Moji_Joho; MJ013050 -6590 E0100; Adobe-Japan1; CID+3449 -6590 E0101; Adobe-Japan1; CID+13493 -6590 E0102; Moji_Joho; MJ013051 -6590 E0103; Moji_Joho; MJ013052 -6590 E0104; Moji_Joho; MJ013053 -6591 E0100; Adobe-Japan1; CID+3415 -6592 E0100; Adobe-Japan1; CID+19428 -6595 E0100; Adobe-Japan1; CID+19429 -6597 E0100; Adobe-Japan1; CID+3143 -6598 E0100; Adobe-Japan1; CID+21686 -6599 E0100; Adobe-Japan1; CID+3977 -659B E0100; Adobe-Japan1; CID+5076 -659C E0100; Adobe-Japan1; CID+2300 -659C E0101; Adobe-Japan1; CID+13805 -659C E0102; Hanyo-Denshi; JA2848 -659C E0102; Moji_Joho; MJ013065 -659C E0103; Hanyo-Denshi; KS151460 -659C E0103; Moji_Joho; MJ013064 -659D E0100; Adobe-Japan1; CID+16881 -659F E0100; Adobe-Japan1; CID+5077 -659F E0101; Hanyo-Denshi; JA5848 -659F E0101; Moji_Joho; MJ013068 -659F E0102; Hanyo-Denshi; KS151580 -659F E0102; Moji_Joho; MJ013069 -65A0 E0100; Adobe-Japan1; CID+21687 -65A1 E0100; Adobe-Japan1; CID+1146 -65A3 E0100; Adobe-Japan1; CID+21688 -65A4 E0100; Adobe-Japan1; CID+1740 -65A5 E0100; Adobe-Japan1; CID+2673 -65A5 E0101; Hanyo-Denshi; JA3245 -65A5 E0101; Moji_Joho; MJ013075 -65A5 E0102; Hanyo-Denshi; KS151750 -65A5 E0102; Moji_Joho; MJ057624 -65A6 E0100; Adobe-Japan1; CID+21689 -65A7 E0100; Adobe-Japan1; CID+3538 -65A7 E0101; Adobe-Japan1; CID+20289 -65A7 E0102; Moji_Joho; MJ013077 -65A7 E0103; Moji_Joho; MJ013078 -65AB E0100; Adobe-Japan1; CID+5078 -65AC E0100; Adobe-Japan1; CID+2192 -65AD E0100; Adobe-Japan1; CID+2949 -65AE E0100; Adobe-Japan1; CID+21690 -65AF E0100; Adobe-Japan1; CID+2217 -65B0 E0100; Adobe-Japan1; CID+2557 -65B2 E0100; Adobe-Japan1; CID+17725 -65B2 E0101; Hanyo-Denshi; JB3365 -65B2 E0101; Moji_Joho; MJ013088 -65B2 E0102; Hanyo-Denshi; KS152280 -65B2 E0102; Moji_Joho; MJ013089 -65B3 E0100; Adobe-Japan1; CID+21691 -65B4 E0100; Adobe-Japan1; CID+19430 -65B4 E0101; Hanyo-Denshi; JB3367 -65B4 E0101; Moji_Joho; MJ013092 -65B4 E0102; Hanyo-Denshi; KS152370 -65B4 E0102; Moji_Joho; MJ013091 -65B5 E0100; Adobe-Japan1; CID+17726 -65B5 E0101; Hanyo-Denshi; JD1375 -65B5 E0101; Moji_Joho; MJ013094 -65B5 E0102; Hanyo-Denshi; IB1980 -65B5 E0102; Moji_Joho; MJ013093 -65B7 E0100; Adobe-Japan1; CID+5079 -65B7 E0101; Hanyo-Denshi; JA5850 -65B7 E0101; Moji_Joho; MJ013096 -65B7 E0102; Hanyo-Denshi; KS152560 -65B7 E0102; Moji_Joho; MJ013097 -65B8 E0100; Adobe-Japan1; CID+17727 -65B9 E0100; Adobe-Japan1; CID+3661 -65BC E0100; Adobe-Japan1; CID+1305 -65BC E0101; Adobe-Japan1; CID+13660 -65BD E0100; Adobe-Japan1; CID+2218 -65BE E0100; Adobe-Japan1; CID+19431 -65BF E0100; Adobe-Japan1; CID+17728 -65C1 E0100; Adobe-Japan1; CID+5082 -65C1 E0101; Hanyo-Denshi; JA5853 -65C1 E0101; Moji_Joho; MJ013106 -65C1 E0102; Hanyo-Denshi; KS153270S -65C1 E0102; Moji_Joho; MJ057637 -65C2 E0100; Adobe-Japan1; CID+14600 -65C3 E0100; Adobe-Japan1; CID+5080 -65C4 E0100; Adobe-Japan1; CID+5083 -65C5 E0100; Adobe-Japan1; CID+3969 -65C5 E0101; Adobe-Japan1; CID+14088 -65C5 E0102; Hanyo-Denshi; JA4625 -65C5 E0102; Moji_Joho; MJ013111 -65C5 E0103; Hanyo-Denshi; JTB272 -65C5 E0103; Moji_Joho; MJ013110 -65C6 E0100; Adobe-Japan1; CID+5081 -65C8 E0100; Adobe-Japan1; CID+19432 -65C9 E0100; Adobe-Japan1; CID+17729 -65C9 E0101; Hanyo-Denshi; JB3371 -65C9 E0101; Moji_Joho; MJ013115 -65C9 E0102; Hanyo-Denshi; JTB274S -65C9 E0102; Moji_Joho; MJ013116 -65CB E0100; Adobe-Japan1; CID+2719 -65CC E0100; Adobe-Japan1; CID+5084 -65CE E0100; Adobe-Japan1; CID+19433 -65CF E0100; Adobe-Japan1; CID+2834 -65D0 E0100; Adobe-Japan1; CID+19434 -65D2 E0100; Adobe-Japan1; CID+5085 -65D4 E0100; Adobe-Japan1; CID+17730 -65D6 E0100; Adobe-Japan1; CID+21692 -65D7 E0100; Adobe-Japan1; CID+1590 -65D8 E0100; Adobe-Japan1; CID+21693 -65D8 E0101; Hanyo-Denshi; JB3376 -65D8 E0101; Moji_Joho; MJ013130 -65D8 E0102; Hanyo-Denshi; KS153860 -65D8 E0102; Moji_Joho; MJ013131 -65D9 E0100; Adobe-Japan1; CID+5087 -65DB E0100; Adobe-Japan1; CID+5086 -65DD E0100; Hanyo-Denshi; KS154010 -65DD E0100; Moji_Joho; MJ013136 -65DD E0101; Hanyo-Denshi; KS154030 -65DD E0101; Moji_Joho; MJ013137 -65DE E0100; Hanyo-Denshi; IB0705 -65DE E0100; Moji_Joho; MJ013138 -65DE E0101; Hanyo-Denshi; IP65DE -65DE E0101; Moji_Joho; MJ013139 -65DE E0102; Hanyo-Denshi; KS154050 -65DE E0102; Moji_Joho; MJ013140 -65DF E0100; Adobe-Japan1; CID+19435 -65DF E0101; Adobe-Japan1; CID+21694 -65E0 E0100; Adobe-Japan1; CID+5088 -65E1 E0100; Adobe-Japan1; CID+5089 -65E1 E0101; Adobe-Japan1; CID+20137 -65E1 E0102; Hanyo-Denshi; JA5860 -65E1 E0102; Moji_Joho; MJ013143 -65E1 E0103; Hanyo-Denshi; FT2227S -65E1 E0103; Moji_Joho; MJ013145 -65E1 E0104; Hanyo-Denshi; TK01038080 -65E1 E0105; Moji_Joho; MJ013144 -65E2 E0100; Adobe-Japan1; CID+13334 -65E2 E0101; Adobe-Japan1; CID+1591 -65E2 E0102; Hanyo-Denshi; JA2091 -65E2 E0102; Moji_Joho; MJ013146 -65E2 E0103; Hanyo-Denshi; JTB27A -65E2 E0103; Moji_Joho; MJ013147 -65E2 E0104; Hanyo-Denshi; JC8511 -65E2 E0105; Moji_Joho; MJ057647 -65E3 E0100; Adobe-Japan1; CID+13701 -65E3 E0101; Hanyo-Denshi; IP65E3 -65E3 E0101; Moji_Joho; MJ013149 -65E3 E0102; Hanyo-Denshi; JT65E3S -65E3 E0102; Moji_Joho; MJ013148 -65E5 E0100; Adobe-Japan1; CID+3284 -65E5 E0101; Moji_Joho; MJ013151 -65E5 E0102; Moji_Joho; MJ013152 -65E6 E0100; Adobe-Japan1; CID+2932 -65E7 E0100; Adobe-Japan1; CID+1670 -65E8 E0100; Adobe-Japan1; CID+2219 -65E9 E0100; Adobe-Japan1; CID+2787 -65EC E0100; Adobe-Japan1; CID+2406 -65ED E0100; Adobe-Japan1; CID+1140 -65F0 E0100; Adobe-Japan1; CID+14601 -65F1 E0100; Adobe-Japan1; CID+5090 -65F2 E0100; Adobe-Japan1; CID+14602 -65F2 E0101; Hanyo-Denshi; JB3379 -65F2 E0102; Hanyo-Denshi; TK01038340 -65F3 E0100; Hanyo-Denshi; IP65F3 -65F3 E0100; Moji_Joho; MJ013166 -65F3 E0101; Hanyo-Denshi; JT65F3 -65F3 E0101; Moji_Joho; MJ013167 -65F4 E0100; Adobe-Japan1; CID+21695 -65F5 E0100; Adobe-Japan1; CID+21696 -65F9 E0100; Adobe-Japan1; CID+17732 -65F9 E0101; Hanyo-Denshi; JB3382 -65F9 E0102; Hanyo-Denshi; TK01038240 -65FA E0100; Adobe-Japan1; CID+1314 -65FA E0101; Hanyo-Denshi; JA1802 -65FA E0102; Hanyo-Denshi; TK01038630 -65FB E0100; Adobe-Japan1; CID+5094 -65FB E0101; Moji_Joho; MJ013173 -65FB E0102; Moji_Joho; MJ013174 -65FC E0100; Adobe-Japan1; CID+17733 -65FD E0100; Hanyo-Denshi; IP65FD -65FD E0101; Hanyo-Denshi; TK01038410 -65FE E0100; Adobe-Japan1; CID+21697 -65FE E0101; Hanyo-Denshi; JB3383 -65FE E0102; Hanyo-Denshi; TK01038250 -65FF E0100; Adobe-Japan1; CID+21698 -6600 E0100; Adobe-Japan1; CID+8472 -6600 E0101; Hanyo-Denshi; JB3385 -6600 E0101; Moji_Joho; MJ013181 -6600 E0102; Hanyo-Denshi; IB1986 -6600 E0102; Moji_Joho; MJ013182 -6602 E0100; Adobe-Japan1; CID+1993 -6602 E0101; Hanyo-Denshi; JA2523 -6602 E0101; Moji_Joho; MJ013184 -6602 E0102; Hanyo-Denshi; JTB281 -6602 E0102; Moji_Joho; MJ013185 -6603 E0100; Adobe-Japan1; CID+5093 -6604 E0100; Adobe-Japan1; CID+17734 -6606 E0100; Adobe-Japan1; CID+2075 -6607 E0100; Adobe-Japan1; CID+2466 -6607 E0101; Hanyo-Denshi; JA3026 -6607 E0101; Moji_Joho; MJ013190 -6607 E0102; Hanyo-Denshi; JTB28C -6607 E0102; Moji_Joho; MJ059678 -6607 E0103; Hanyo-Denshi; TK01038460 -6608 E0100; Adobe-Japan1; CID+17735 -6608 E0101; Hanyo-Denshi; JB3387 -6608 E0101; Moji_Joho; MJ013191 -6608 E0102; Hanyo-Denshi; IB1987 -6608 E0102; Moji_Joho; MJ013192 -6608 E0103; Hanyo-Denshi; JTB283 -6608 E0103; Moji_Joho; MJ013193 -6609 E0100; Adobe-Japan1; CID+8474 -660A E0100; Adobe-Japan1; CID+5092 -660B E0100; Hanyo-Denshi; IP660B -660B E0100; Moji_Joho; MJ013196 -660B E0101; Hanyo-Denshi; JT660B -660B E0101; Moji_Joho; MJ013197 -660C E0100; Adobe-Japan1; CID+2467 -660D E0100; Adobe-Japan1; CID+21699 -660D E0101; Hanyo-Denshi; JB3389 -660D E0102; Hanyo-Denshi; TK01038430 -660E E0100; Adobe-Japan1; CID+3788 -660E E0101; Adobe-Japan1; CID+14052 -660E E0102; Hanyo-Denshi; JA4432 -660E E0102; Moji_Joho; MJ013201 -660E E0103; Hanyo-Denshi; JTB27F -660E E0103; Moji_Joho; MJ013202 -660F E0100; Adobe-Japan1; CID+2074 -660F E0101; Hanyo-Denshi; JA2610 -660F E0101; Moji_Joho; MJ013203 -660F E0102; Hanyo-Denshi; KS156240 -660F E0102; Moji_Joho; MJ057659 -6611 E0100; Adobe-Japan1; CID+21700 -6612 E0100; Adobe-Japan1; CID+21701 -6613 E0100; Adobe-Japan1; CID+1179 -6614 E0100; Adobe-Japan1; CID+2674 -6615 E0100; Adobe-Japan1; CID+8473 -6616 E0100; Adobe-Japan1; CID+21702 -661C E0100; Adobe-Japan1; CID+5099 -661D E0100; Adobe-Japan1; CID+21703 -661D E0101; Hanyo-Denshi; JB3394 -661D E0102; Hanyo-Denshi; TK01038810 -661E E0100; Adobe-Japan1; CID+20304 -661E E0101; Adobe-Japan1; CID+8476 -661E E0102; Hanyo-Denshi; JB3401 -661E E0102; Moji_Joho; MJ013220 -661E E0103; Hanyo-Denshi; JC8515 -661E E0103; Moji_Joho; MJ013219 -661E E0104; Moji_Joho; MJ013221 -661F E0100; Adobe-Japan1; CID+2645 -6620 E0100; Adobe-Japan1; CID+1257 -6621 E0100; Adobe-Japan1; CID+17736 -6621 E0101; Hanyo-Denshi; JB3402 -6621 E0102; Hanyo-Denshi; TK01038300 -6622 E0100; Adobe-Japan1; CID+16883 -6623 E0100; Adobe-Japan1; CID+21704 -6624 E0100; Adobe-Japan1; CID+8477 -6624 E0101; Hanyo-Denshi; JB3405 -6624 E0101; Moji_Joho; MJ013228 -6624 E0102; Hanyo-Denshi; JTB28D -6624 E0102; Moji_Joho; MJ013229 -6625 E0100; Adobe-Japan1; CID+2399 -6626 E0100; Adobe-Japan1; CID+21705 -6626 E0101; Hanyo-Denshi; JB3406 -6626 E0102; Hanyo-Denshi; TK01038450 -6627 E0100; Adobe-Japan1; CID+3732 -6628 E0100; Adobe-Japan1; CID+2146 -6629 E0100; Adobe-Japan1; CID+21706 -662A E0100; Adobe-Japan1; CID+17737 -662B E0100; Adobe-Japan1; CID+16884 -662C E0100; Adobe-Japan1; CID+14603 -662C E0101; Hanyo-Denshi; JB3410 -662C E0101; Moji_Joho; MJ013237 -662C E0102; Hanyo-Denshi; KS156810 -662C E0102; Moji_Joho; MJ057666 -662D E0100; Adobe-Japan1; CID+2468 -662E E0100; Adobe-Japan1; CID+8475 -662F E0100; Adobe-Japan1; CID+2635 -6630 E0100; Adobe-Japan1; CID+16885 -6631 E0100; Adobe-Japan1; CID+8366 -6633 E0100; Adobe-Japan1; CID+16886 -6634 E0100; Adobe-Japan1; CID+5098 -6635 E0100; Adobe-Japan1; CID+5096 -6636 E0100; Adobe-Japan1; CID+5097 -6636 E0101; Hanyo-Denshi; JA5868 -6636 E0101; Moji_Joho; MJ013247 -6636 E0102; Hanyo-Denshi; KS156220 -6636 E0102; Moji_Joho; MJ013248 -6637 E0100; Adobe-Japan1; CID+21708 -6639 E0100; Adobe-Japan1; CID+21707 -663A E0100; Adobe-Japan1; CID+16882 -663B E0100; Adobe-Japan1; CID+7680 -663C E0100; Adobe-Japan1; CID+2985 -663C E0101; Hanyo-Denshi; JA3575 -663C E0101; Moji_Joho; MJ013255 -663C E0102; Hanyo-Denshi; KS087550 -663C E0102; Moji_Joho; MJ013254 -663F E0100; Adobe-Japan1; CID+5129 -6640 E0100; Adobe-Japan1; CID+21709 -6641 E0100; Adobe-Japan1; CID+5103 -6642 E0100; Adobe-Japan1; CID+2252 -6643 E0100; Adobe-Japan1; CID+1994 -6644 E0100; Adobe-Japan1; CID+5101 -6645 E0100; Adobe-Japan1; CID+17738 -6646 E0100; Adobe-Japan1; CID+21710 -6647 E0100; Hanyo-Denshi; IP6647 -6647 E0100; Moji_Joho; MJ013264 -6647 E0101; Hanyo-Denshi; KS156800 -6647 E0101; Moji_Joho; MJ057665 -6648 E0100; Adobe-Japan1; CID+16887 -6648 E0101; Hanyo-Denshi; JC8524 -6648 E0101; Moji_Joho; MJ013265 -6648 E0102; Hanyo-Denshi; JTB298S -6648 E0102; Moji_Joho; MJ013267 -6648 E0103; Moji_Joho; MJ013266 -6649 E0100; Adobe-Japan1; CID+5102 -664A E0100; Adobe-Japan1; CID+21711 -664B E0100; Adobe-Japan1; CID+2558 -664B E0101; Hanyo-Denshi; JA3124 -664B E0102; Hanyo-Denshi; TK01039320 -664C E0100; Adobe-Japan1; CID+14604 -664E E0100; Adobe-Japan1; CID+17740 -664F E0100; Adobe-Japan1; CID+5100 -6651 E0100; Adobe-Japan1; CID+17739 -6652 E0100; Adobe-Japan1; CID+2173 -6653 E0100; Hanyo-Denshi; TK01039010 -6653 E0101; Hanyo-Denshi; TK01039160 -6657 E0100; Adobe-Japan1; CID+8479 -6658 E0100; Adobe-Japan1; CID+21712 -6659 E0100; Adobe-Japan1; CID+8480 -6659 E0101; Hanyo-Denshi; JB3426 -6659 E0101; Moji_Joho; MJ013282 -6659 E0102; Hanyo-Denshi; KS156900 -6659 E0102; Moji_Joho; MJ013281 -665A E0100; Adobe-Japan1; CID+13377 -665B E0100; Adobe-Japan1; CID+14605 -665C E0100; Adobe-Japan1; CID+14606 -665D E0100; Adobe-Japan1; CID+5105 -665E E0100; Adobe-Japan1; CID+5104 -665F E0100; Adobe-Japan1; CID+5109 -665F E0101; Adobe-Japan1; CID+13548 -665F E0102; Adobe-Japan1; CID+14136 -665F E0103; Adobe-Japan1; CID+14137 -665F E0104; Hanyo-Denshi; JA5880 -665F E0104; Moji_Joho; MJ013288 -665F E0105; Hanyo-Denshi; FT1694 -665F E0105; Moji_Joho; MJ013289 -6660 E0100; Adobe-Japan1; CID+21713 -6661 E0100; Adobe-Japan1; CID+14607 -6662 E0100; Adobe-Japan1; CID+5110 -6663 E0100; Adobe-Japan1; CID+14138 -6664 E0100; Adobe-Japan1; CID+5106 -6665 E0100; Adobe-Japan1; CID+8478 -6666 E0100; Adobe-Japan1; CID+1408 -6666 E0101; Adobe-Japan1; CID+7650 -6666 E0102; Hanyo-Denshi; JA1902 -6666 E0102; Moji_Joho; MJ013296 -6666 E0103; Hanyo-Denshi; FT1767 -6666 E0103; Moji_Joho; MJ013297 -6667 E0100; Adobe-Japan1; CID+5107 -6667 E0101; Adobe-Japan1; CID+20138 -6667 E0102; Hanyo-Denshi; JA5878 -6667 E0102; Moji_Joho; MJ013298 -6667 E0103; Hanyo-Denshi; FT2229 -6667 E0103; Moji_Joho; MJ013299 -6668 E0100; Adobe-Japan1; CID+5108 -6669 E0100; Adobe-Japan1; CID+3433 -6669 E0101; Adobe-Japan1; CID+13989 -666A E0100; Adobe-Japan1; CID+17745 -666B E0100; Adobe-Japan1; CID+14608 -666C E0100; Adobe-Japan1; CID+17746 -666D E0100; Adobe-Japan1; CID+17747 -666D E0101; Hanyo-Denshi; JD1408 -666D E0102; Hanyo-Denshi; TK01039890 -666E E0100; Adobe-Japan1; CID+3539 -666E E0101; Adobe-Japan1; CID+20139 -666F E0100; Adobe-Japan1; CID+1824 -6670 E0100; Adobe-Japan1; CID+5111 -6673 E0100; Adobe-Japan1; CID+8482 -6674 E0100; Adobe-Japan1; CID+8481 -6674 E0101; Adobe-Japan1; CID+2646 -6674 E0102; Hanyo-Denshi; JA3218 -6674 E0103; Hanyo-Denshi; IB2015 -6675 E0100; Adobe-Japan1; CID+21714 -6676 E0100; Adobe-Japan1; CID+2469 -6677 E0100; Adobe-Japan1; CID+16889 -6677 E0101; Adobe-Japan1; CID+14609 -6677 E0102; Hanyo-Denshi; JB3439 -6677 E0102; Moji_Joho; MJ013316 -6677 E0103; Hanyo-Denshi; JC8532 -6677 E0103; Moji_Joho; MJ013317 -6677 E0104; Hanyo-Denshi; JTB2A3 -6677 E0104; Moji_Joho; MJ013318 -6678 E0100; Adobe-Japan1; CID+16890 -6679 E0100; Adobe-Japan1; CID+21716 -667A E0100; Adobe-Japan1; CID+2960 -667B E0100; Adobe-Japan1; CID+17748 -667C E0100; Adobe-Japan1; CID+21717 -667E E0100; Adobe-Japan1; CID+19436 -667F E0100; Adobe-Japan1; CID+21715 -6680 E0100; Adobe-Japan1; CID+17749 -6680 E0101; Hanyo-Denshi; JB3443 -6680 E0101; Moji_Joho; MJ013327 -6680 E0102; Hanyo-Denshi; JD1410 -6680 E0102; Moji_Joho; MJ013328 -6681 E0100; Adobe-Japan1; CID+1727 -6681 E0101; Adobe-Japan1; CID+13728 -6681 E0102; Hanyo-Denshi; JA2239 -6681 E0102; Moji_Joho; MJ013329 -6681 E0103; Hanyo-Denshi; JTB2B5S -6681 E0103; Moji_Joho; MJ013330 -6683 E0100; Adobe-Japan1; CID+5112 -6684 E0100; Adobe-Japan1; CID+5116 -6687 E0100; Adobe-Japan1; CID+1355 -6688 E0100; Adobe-Japan1; CID+5113 -6689 E0100; Adobe-Japan1; CID+5115 -668B E0100; Adobe-Japan1; CID+19437 -668C E0100; Adobe-Japan1; CID+19438 -668D E0100; Adobe-Japan1; CID+16891 -668E E0100; Adobe-Japan1; CID+5114 -668E E0101; Hanyo-Denshi; JA5885 -668E E0101; Moji_Joho; MJ013341 -668E E0102; Hanyo-Denshi; KS158300 -668E E0102; Moji_Joho; MJ013342 -668E E0103; Hanyo-Denshi; JTB2B3 -668E E0103; Moji_Joho; MJ013343 -6690 E0100; Adobe-Japan1; CID+17750 -6690 E0101; Hanyo-Denshi; JB3448 -6690 E0101; Moji_Joho; MJ013346 -6690 E0102; Hanyo-Denshi; KS158310S -6690 E0102; Moji_Joho; MJ013345 -6691 E0100; Adobe-Japan1; CID+2421 -6691 E0101; Adobe-Japan1; CID+13352 -6691 E0102; Hanyo-Denshi; JA2975 -6691 E0103; Hanyo-Denshi; JC8535 -6692 E0100; Adobe-Japan1; CID+17751 -6695 E0100; Hanyo-Denshi; IP6695 -6695 E0101; Hanyo-Denshi; TK01040170 -6696 E0100; Adobe-Japan1; CID+2950 -6696 E0101; Adobe-Japan1; CID+13918 -6696 E0102; Hanyo-Denshi; JA3540 -6696 E0102; Moji_Joho; MJ013355 -6696 E0103; Hanyo-Denshi; JTB2B0 -6696 E0103; Moji_Joho; MJ013354 -6697 E0100; Adobe-Japan1; CID+1161 -6697 E0101; Adobe-Japan1; CID+13638 -6697 E0102; Hanyo-Denshi; JA1637 -6697 E0102; Moji_Joho; MJ013356 -6697 E0103; Hanyo-Denshi; JTB2B1 -6697 E0103; Moji_Joho; MJ013357 -6698 E0100; Adobe-Japan1; CID+5117 -6699 E0100; Adobe-Japan1; CID+8483 -669A E0100; Adobe-Japan1; CID+21718 -669A E0101; Hanyo-Denshi; JB3451 -669A E0102; Hanyo-Denshi; TK01040060 -669B E0100; Adobe-Japan1; CID+21719 -669C E0100; Adobe-Japan1; CID+21720 -669C E0101; Hanyo-Denshi; JB3453 -669C E0101; Moji_Joho; MJ013363 -669C E0102; Hanyo-Denshi; JTB2B8 -669C E0102; Moji_Joho; MJ013364 -669D E0100; Adobe-Japan1; CID+5118 -669F E0100; Adobe-Japan1; CID+21721 -66A0 E0100; Adobe-Japan1; CID+8484 -66A0 E0101; Hanyo-Denshi; JB3455 -66A0 E0101; Moji_Joho; MJ013368 -66A0 E0102; Hanyo-Denshi; JTB2BA -66A0 E0102; Moji_Joho; MJ013369 -66A2 E0100; Adobe-Japan1; CID+3014 -66A4 E0100; Adobe-Japan1; CID+14610 -66A4 E0101; Hanyo-Denshi; JB3456 -66A4 E0102; Hanyo-Denshi; TK01040290 -66A6 E0100; Adobe-Japan1; CID+4025 -66AB E0100; Adobe-Japan1; CID+2193 -66AD E0100; Adobe-Japan1; CID+17753 -66AD E0101; Hanyo-Denshi; JB3457 -66AD E0102; Hanyo-Denshi; TK01041200 -66AE E0100; Adobe-Japan1; CID+3643 -66AE E0101; Hanyo-Denshi; JA4275 -66AE E0101; Moji_Joho; MJ013383 -66AE E0102; Hanyo-Denshi; JTB2BC -66AE E0102; Moji_Joho; MJ013384 -66B1 E0100; Adobe-Japan1; CID+17754 -66B1 E0101; Hanyo-Denshi; JB3458 -66B1 E0101; Moji_Joho; MJ013387 -66B1 E0102; Hanyo-Denshi; KS159500 -66B1 E0102; Moji_Joho; MJ013389 -66B1 E0103; Hanyo-Denshi; JTB2BF -66B1 E0103; Moji_Joho; MJ013388 -66B2 E0100; Adobe-Japan1; CID+8485 -66B3 E0100; Adobe-Japan1; CID+19439 -66B3 E0101; Hanyo-Denshi; IP66B3 -66B3 E0101; Moji_Joho; MJ013391 -66B3 E0102; Hanyo-Denshi; TK01030090 -66B3 E0103; Hanyo-Denshi; TK01040600 -66B3 E0104; Moji_Joho; MJ068052 -66B4 E0100; Adobe-Japan1; CID+3691 -66B5 E0100; Adobe-Japan1; CID+17755 -66B5 E0101; Adobe-Japan1; CID+21722 -66B8 E0100; Adobe-Japan1; CID+5125 -66B8 E0101; Hanyo-Denshi; JA5902 -66B8 E0102; Hanyo-Denshi; TK01040810 -66B9 E0100; Adobe-Japan1; CID+5120 -66B9 E0101; Hanyo-Denshi; JA5891 -66B9 E0101; Moji_Joho; MJ013401 -66B9 E0102; Hanyo-Denshi; FT2231 -66B9 E0102; Moji_Joho; MJ013400 -66BA E0100; Hanyo-Denshi; IP66BA -66BA E0101; Hanyo-Denshi; TK01040310 -66BB E0100; Adobe-Japan1; CID+16892 -66BC E0100; Adobe-Japan1; CID+5123 -66BC E0101; Hanyo-Denshi; JA5894 -66BC E0101; Moji_Joho; MJ013405 -66BC E0102; Hanyo-Denshi; FT2232S -66BC E0102; Moji_Joho; MJ013406 -66BE E0100; Adobe-Japan1; CID+5122 -66BF E0100; Adobe-Japan1; CID+8486 -66C0 E0100; Adobe-Japan1; CID+19440 -66C1 E0100; Adobe-Japan1; CID+5119 -66C1 E0101; Adobe-Japan1; CID+7992 -66C1 E0102; Adobe-Japan1; CID+20140 -66C1 E0103; Hanyo-Denshi; JA5890 -66C1 E0103; Moji_Joho; MJ013411 -66C1 E0104; Hanyo-Denshi; JTB2BE -66C1 E0104; Moji_Joho; MJ013412 -66C1 E0105; Hanyo-Denshi; JTB2C4S -66C1 E0105; Moji_Joho; MJ013413 -66C1 E0106; Hanyo-Denshi; JTB2CBS -66C1 E0106; Moji_Joho; MJ013414 -66C1 E0107; Hanyo-Denshi; TK01038100 -66C2 E0100; Adobe-Japan1; CID+21723 -66C3 E0100; Adobe-Japan1; CID+21724 -66C3 E0101; Hanyo-Denshi; JB3465 -66C3 E0101; Moji_Joho; MJ013418 -66C3 E0102; Hanyo-Denshi; IB0708 -66C3 E0102; Moji_Joho; MJ013417 -66C4 E0100; Adobe-Japan1; CID+5124 -66C4 E0101; Hanyo-Denshi; JA5901 -66C4 E0101; Moji_Joho; MJ013419 -66C4 E0102; Hanyo-Denshi; JTB2C5S -66C5 E0100; Hanyo-Denshi; JT66C5 -66C5 E0100; Moji_Joho; MJ013422 -66C5 E0101; Hanyo-Denshi; KS159730 -66C5 E0101; Moji_Joho; MJ013421 -66C6 E0100; Adobe-Japan1; CID+13397 -66C7 E0100; Adobe-Japan1; CID+3254 -66C8 E0100; Adobe-Japan1; CID+14611 -66C8 E0101; Hanyo-Denshi; JB3466 -66C8 E0101; Moji_Joho; MJ013425 -66C8 E0102; Hanyo-Denshi; KS160010 -66C8 E0102; Moji_Joho; MJ057680 -66C9 E0100; Adobe-Japan1; CID+5121 -66C9 E0101; Hanyo-Denshi; JA5892 -66C9 E0101; Moji_Joho; MJ013426 -66C9 E0102; Hanyo-Denshi; JTB2B9S -66C9 E0102; Moji_Joho; MJ059694 -66CC E0100; Adobe-Japan1; CID+21725 -66CC E0101; Hanyo-Denshi; JB3467 -66CC E0102; Hanyo-Denshi; TK01041260 -66CE E0100; Adobe-Japan1; CID+21726 -66CF E0100; Adobe-Japan1; CID+19441 -66CF E0101; Hanyo-Denshi; JB3469 -66CF E0101; Moji_Joho; MJ013432 -66CF E0102; Hanyo-Denshi; JTB2C3 -66CF E0102; Moji_Joho; MJ013433 -66CF E0103; Hanyo-Denshi; TK01040410 -66CF E0104; Hanyo-Denshi; TK01040510 -66D4 E0100; Adobe-Japan1; CID+21727 -66D6 E0100; Adobe-Japan1; CID+5126 -66D6 E0101; Hanyo-Denshi; JA5903 -66D6 E0101; Moji_Joho; MJ013444 -66D6 E0102; Hanyo-Denshi; KS160120 -66D6 E0102; Moji_Joho; MJ013443 -66D9 E0100; Adobe-Japan1; CID+2422 -66D9 E0101; Adobe-Japan1; CID+7699 -66D9 E0102; Hanyo-Denshi; JA2976 -66D9 E0102; Moji_Joho; MJ013447 -66D9 E0103; Hanyo-Denshi; FT1820 -66D9 E0103; Moji_Joho; MJ013448 -66DA E0100; Adobe-Japan1; CID+5127 -66DA E0101; Hanyo-Denshi; JA5904 -66DA E0101; Moji_Joho; MJ013449 -66DA E0102; Hanyo-Denshi; KS160360 -66DA E0102; Moji_Joho; MJ013450 -66DA E0103; Hanyo-Denshi; FT2233 -66DA E0103; Moji_Joho; MJ013451 -66DB E0100; Adobe-Japan1; CID+16893 -66DC E0100; Adobe-Japan1; CID+3893 -66DC E0101; Adobe-Japan1; CID+14077 -66DC E0102; Hanyo-Denshi; JA4543 -66DC E0102; Moji_Joho; MJ013454 -66DC E0103; Hanyo-Denshi; JTB2CDS -66DC E0103; Moji_Joho; MJ013453 -66DD E0100; Adobe-Japan1; CID+3374 -66DE E0100; Hanyo-Denshi; KS160570 -66DE E0101; Hanyo-Denshi; TK01040890 -66DF E0100; Adobe-Japan1; CID+21728 -66E0 E0100; Adobe-Japan1; CID+5128 -66E0 E0101; Hanyo-Denshi; JA5905 -66E0 E0101; Moji_Joho; MJ013459 -66E0 E0102; Hanyo-Denshi; JTB2CF -66E0 E0102; Moji_Joho; MJ013460 -66E0 E0103; Hanyo-Denshi; TK01040860 -66E0 E0104; Hanyo-Denshi; TK01040870 -66E6 E0100; Adobe-Japan1; CID+5130 -66E7 E0100; Hanyo-Denshi; KS160730 -66E7 E0101; Hanyo-Denshi; TK01040930 -66E8 E0100; Adobe-Japan1; CID+16894 -66E8 E0101; Hanyo-Denshi; JB3473 -66E8 E0101; Moji_Joho; MJ013469 -66E8 E0102; Hanyo-Denshi; KS160790 -66E8 E0102; Moji_Joho; MJ013470 -66E8 E0103; Hanyo-Denshi; TK01040940 -66E9 E0100; Adobe-Japan1; CID+5131 -66EB E0100; Adobe-Japan1; CID+21729 -66EC E0100; Adobe-Japan1; CID+14612 -66EE E0100; Adobe-Japan1; CID+21730 -66F0 E0100; Adobe-Japan1; CID+5132 -66F2 E0100; Adobe-Japan1; CID+1730 -66F3 E0100; Adobe-Japan1; CID+1258 -66F4 E0100; Adobe-Japan1; CID+1995 -66F4 E0101; Adobe-Japan1; CID+13441 -66F4 E0102; Moji_Joho; MJ013482 -66F4 E0103; Moji_Joho; MJ013483 -66F5 E0100; Adobe-Japan1; CID+5133 -66F5 E0101; Adobe-Japan1; CID+14139 -66F5 E0102; Hanyo-Denshi; JA5910 -66F5 E0102; Moji_Joho; MJ013484 -66F5 E0103; Hanyo-Denshi; IB0709 -66F5 E0103; Moji_Joho; MJ013485 -66F5 E0104; Hanyo-Denshi; JTB2D4 -66F5 E0104; Moji_Joho; MJ013486 -66F7 E0100; Adobe-Japan1; CID+5134 -66F7 E0101; Hanyo-Denshi; JA5911 -66F7 E0101; Moji_Joho; MJ013488 -66F7 E0102; Hanyo-Denshi; FT2237 -66F7 E0102; Moji_Joho; MJ013489 -66F7 E0103; Hanyo-Denshi; TK01038540 -66F8 E0100; Adobe-Japan1; CID+2427 -66F8 E0101; Adobe-Japan1; CID+13827 -66F9 E0100; Adobe-Japan1; CID+2788 -66FA E0100; Adobe-Japan1; CID+8487 -66FB E0100; Adobe-Japan1; CID+8369 -66FB E0101; Adobe-Japan1; CID+14285 -66FB E0102; Hanyo-Denshi; JB3431 -66FB E0102; Moji_Joho; MJ013496 -66FB E0103; Hanyo-Denshi; JTB292 -66FB E0103; Moji_Joho; MJ013495 -66FB E0104; Moji_Joho; MJ013497 -66FC E0100; Adobe-Japan1; CID+4333 -66FC E0101; Adobe-Japan1; CID+14112 -66FC E0102; Hanyo-Denshi; JA5056 -66FC E0102; Moji_Joho; MJ013498 -66FC E0103; Hanyo-Denshi; JTAEA3S -66FC E0103; Moji_Joho; MJ013499 -66FD E0100; Adobe-Japan1; CID+2752 -66FE E0100; Adobe-Japan1; CID+2751 -66FE E0101; Hanyo-Denshi; JA3329 -66FE E0101; Moji_Joho; MJ013501 -66FE E0102; Hanyo-Denshi; IB0710 -66FE E0102; Moji_Joho; MJ013502 -66FE E0103; Hanyo-Denshi; FT2040 -66FE E0103; Moji_Joho; MJ013503 -66FE E0104; Hanyo-Denshi; TK01039940 -66FF E0100; Adobe-Japan1; CID+2872 -6700 E0100; Adobe-Japan1; CID+2103 -6700 E0101; Adobe-Japan1; CID+20143 -6700 E0102; Hanyo-Denshi; JA2639 -6700 E0102; Moji_Joho; MJ013506 -6700 E0103; Hanyo-Denshi; KS019090 -6700 E0103; Moji_Joho; MJ013505 -6701 E0100; Adobe-Japan1; CID+17759 -6701 E0101; Hanyo-Denshi; JD1423 -6701 E0101; Moji_Joho; MJ013508 -6701 E0102; Hanyo-Denshi; KS158130S -6701 E0102; Moji_Joho; MJ013507 -6701 E0103; Hanyo-Denshi; KS158110S -6701 E0103; Moji_Joho; MJ057673 -6703 E0100; Adobe-Japan1; CID+4171 -6703 E0101; Hanyo-Denshi; JA4882 -6703 E0101; Moji_Joho; MJ013510 -6703 E0102; Hanyo-Denshi; JTAD8D -6703 E0102; Moji_Joho; MJ059330 -6703 E0103; Hanyo-Denshi; JTAD98 -6703 E0103; Moji_Joho; MJ013512 -6705 E0100; Adobe-Japan1; CID+14613 -6707 E0100; Adobe-Japan1; CID+21731 -6707 E0101; Hanyo-Denshi; JB3479 -6707 E0102; Hanyo-Denshi; TK01040950 -6707 E0103; Hanyo-Denshi; TK01040980 -6708 E0100; Adobe-Japan1; CID+1860 -6708 E0101; Adobe-Japan1; CID+13746 -6708 E0102; Hanyo-Denshi; JA2378 -6708 E0102; Moji_Joho; MJ013520 -6708 E0103; Hanyo-Denshi; JTB2DB -6708 E0103; Moji_Joho; MJ013519 -6709 E0100; Adobe-Japan1; CID+3863 -6709 E0101; Adobe-Japan1; CID+14071 -6709 E0102; Hanyo-Denshi; JA4513 -6709 E0102; Moji_Joho; MJ013521 -6709 E0103; Hanyo-Denshi; JTB2DC -6709 E0103; Moji_Joho; MJ013522 -670B E0100; Adobe-Japan1; CID+3662 -670B E0101; Adobe-Japan1; CID+14022 -670B E0102; Hanyo-Denshi; JA4294 -670B E0102; Moji_Joho; MJ013525 -670B E0103; Hanyo-Denshi; IB2048 -670B E0103; Moji_Joho; MJ013524 -670D E0100; Adobe-Japan1; CID+3568 -670D E0101; Adobe-Japan1; CID+14007 -670D E0102; Hanyo-Denshi; JA4194 -670D E0102; Moji_Joho; MJ013528 -670D E0103; Hanyo-Denshi; JTB2DE -670D E0103; Moji_Joho; MJ013527 -670E E0100; Adobe-Japan1; CID+8488 -670E E0101; Hanyo-Denshi; JB3480 -670E E0101; Moji_Joho; MJ013529 -670E E0102; Hanyo-Denshi; JTB2E3 -670E E0102; Moji_Joho; MJ013530 -670F E0100; Adobe-Japan1; CID+5135 -6712 E0100; Adobe-Japan1; CID+17760 -6713 E0100; Adobe-Japan1; CID+14614 -6713 E0101; Hanyo-Denshi; JB3481 -6713 E0101; Moji_Joho; MJ013534 -6713 E0102; Hanyo-Denshi; KS328690 -6713 E0102; Moji_Joho; MJ013535 -6714 E0100; Adobe-Japan1; CID+2147 -6714 E0101; Hanyo-Denshi; JA2683 -6714 E0101; Moji_Joho; MJ013536 -6714 E0102; Hanyo-Denshi; KS161460 -6714 E0102; Moji_Joho; MJ013537 -6714 E0103; Hanyo-Denshi; KS161350 -6714 E0103; Moji_Joho; MJ057685 -6714 E0104; Hanyo-Denshi; TK01024300 -6715 E0100; Adobe-Japan1; CID+3035 -6715 E0101; Adobe-Japan1; CID+13935 -6715 E0102; Adobe-Japan1; CID+13936 -6715 E0103; Hanyo-Denshi; JA3631 -6715 E0103; Moji_Joho; MJ013540 -6715 E0104; Hanyo-Denshi; JTB2E4 -6715 E0104; Moji_Joho; MJ013539 -6716 E0100; Adobe-Japan1; CID+5136 -6717 E0100; Adobe-Japan1; CID+20305 -6717 E0101; Adobe-Japan1; CID+4053 -6717 E0102; Adobe-Japan1; CID+8489 -6717 E0103; Adobe-Japan1; CID+14098 -6717 E0104; Hanyo-Denshi; JA4715 -6717 E0104; Moji_Joho; MJ013542 -6717 E0105; Hanyo-Denshi; JTB2E9 -6717 E0105; Moji_Joho; MJ013543 -6717 E0106; Hanyo-Denshi; JC8546 -6717 E0107; Hanyo-Denshi; TK01041570 -6719 E0100; Adobe-Japan1; CID+17762 -6719 E0101; Hanyo-Denshi; JB3482 -6719 E0101; Moji_Joho; MJ013545 -6719 E0102; Hanyo-Denshi; KS330810 -6719 E0102; Moji_Joho; MJ013546 -671A E0100; Hanyo-Denshi; IP671A -671A E0100; Moji_Joho; MJ013547 -671A E0101; Hanyo-Denshi; KS161610 -671A E0101; Moji_Joho; MJ013548 -671B E0100; Adobe-Japan1; CID+3692 -671B E0101; Adobe-Japan1; CID+14036 -671B E0102; Adobe-Japan1; CID+14037 -671B E0103; Hanyo-Denshi; JA4330 -671B E0103; Moji_Joho; MJ013550 -671B E0104; Hanyo-Denshi; JTB2E8 -671B E0104; Moji_Joho; MJ013554 -671B E0105; Hanyo-Denshi; JTB2E7 -671B E0105; Moji_Joho; MJ013553 -671B E0106; Hanyo-Denshi; JTB2E6 -671B E0106; Moji_Joho; MJ013552 -671B E0107; Hanyo-Denshi; JTB2E5 -671B E0107; Moji_Joho; MJ013549 -671B E0108; Hanyo-Denshi; TK01042170 -671B E0109; Hanyo-Denshi; TK01058220 -671B E010A; Moji_Joho; MJ013551 -671C E0100; Adobe-Japan1; CID+21732 -671D E0100; Adobe-Japan1; CID+3015 -671D E0101; Adobe-Japan1; CID+13931 -671D E0102; Hanyo-Denshi; JA3611 -671D E0102; Moji_Joho; MJ013558 -671D E0103; Hanyo-Denshi; JTB2EC -671D E0103; Moji_Joho; MJ013557 -671E E0100; Adobe-Japan1; CID+5137 -671E E0101; Hanyo-Denshi; JA5914 -671E E0101; Moji_Joho; MJ013559 -671E E0102; Hanyo-Denshi; KS161810 -671E E0102; Moji_Joho; MJ013560 -671E E0103; Hanyo-Denshi; JTB2EE -671E E0103; Moji_Joho; MJ013561 -671F E0100; Adobe-Japan1; CID+1592 -671F E0101; Adobe-Japan1; CID+13702 -671F E0102; Hanyo-Denshi; JA2092 -671F E0102; Moji_Joho; MJ013562 -671F E0103; Hanyo-Denshi; JTB2ED -671F E0103; Moji_Joho; MJ013563 -6720 E0100; Adobe-Japan1; CID+21733 -6720 E0101; Hanyo-Denshi; JB3484 -6720 E0101; Moji_Joho; MJ013564 -6720 E0102; Hanyo-Denshi; JTB2F0 -6720 E0102; Moji_Joho; MJ013565 -6721 E0100; Hanyo-Denshi; IP6721 -6721 E0100; Moji_Joho; MJ013567 -6721 E0101; Hanyo-Denshi; KS161870 -6721 E0101; Moji_Joho; MJ013566 -6722 E0100; Adobe-Japan1; CID+21734 -6722 E0101; Hanyo-Denshi; JB3485 -6722 E0101; Moji_Joho; MJ013568 -6722 E0102; Hanyo-Denshi; KS161980 -6722 E0102; Moji_Joho; MJ013569 -6722 E0103; Hanyo-Denshi; TK01042420 -6722 E0104; Hanyo-Denshi; TK01059190 -6723 E0100; Hanyo-Denshi; IP81A7 -6723 E0100; Moji_Joho; MJ013570 -6723 E0101; Hanyo-Denshi; KS162120 -6723 E0101; Moji_Joho; MJ057693 -6725 E0100; Adobe-Japan1; CID+19442 -6726 E0100; Adobe-Japan1; CID+5138 -6726 E0101; Hanyo-Denshi; JA5915 -6726 E0101; Moji_Joho; MJ013572 -6726 E0102; Hanyo-Denshi; KS162180 -6726 E0102; Moji_Joho; MJ013573 -6726 E0103; Hanyo-Denshi; FT2238 -6726 E0103; Moji_Joho; MJ013574 -6727 E0100; Adobe-Japan1; CID+5139 -6727 E0101; Moji_Joho; MJ013575 -6727 E0102; Moji_Joho; MJ045852 -6728 E0100; Adobe-Japan1; CID+3814 -672A E0100; Adobe-Japan1; CID+3760 -672B E0100; Adobe-Japan1; CID+3748 -672C E0100; Adobe-Japan1; CID+3722 -672D E0100; Adobe-Japan1; CID+2163 -672E E0100; Adobe-Japan1; CID+5141 -6731 E0100; Adobe-Japan1; CID+2327 -6733 E0100; Adobe-Japan1; CID+14615 -6734 E0100; Adobe-Japan1; CID+3711 -6735 E0100; Adobe-Japan1; CID+19443 -6736 E0100; Adobe-Japan1; CID+5143 -6737 E0100; Adobe-Japan1; CID+5146 -6738 E0100; Adobe-Japan1; CID+5145 -673A E0100; Adobe-Japan1; CID+1589 -673D E0100; Adobe-Japan1; CID+1658 -673E E0100; Adobe-Japan1; CID+21735 -673F E0100; Adobe-Japan1; CID+5142 -6741 E0100; Adobe-Japan1; CID+5144 -6743 E0100; Adobe-Japan1; CID+13751 -6745 E0100; Adobe-Japan1; CID+21736 -6746 E0100; Adobe-Japan1; CID+5147 -6747 E0100; Adobe-Japan1; CID+16895 -6748 E0100; Adobe-Japan1; CID+14616 -6748 E0101; Moji_Joho; MJ013604 -6748 E0102; Moji_Joho; MJ013605 -6749 E0100; Adobe-Japan1; CID+2623 -674C E0100; Adobe-Japan1; CID+14617 -674D E0100; Adobe-Japan1; CID+17765 -674E E0100; Adobe-Japan1; CID+3941 -674F E0100; Adobe-Japan1; CID+1165 -6750 E0100; Adobe-Japan1; CID+2128 -6750 E0101; Hanyo-Denshi; JA2664 -6750 E0102; Hanyo-Denshi; TK01042820 -6750 E0103; Hanyo-Denshi; TK01042940 -6750 E0104; Hanyo-Denshi; TK01043210 -6751 E0100; Adobe-Japan1; CID+2844 -6753 E0100; Adobe-Japan1; CID+2313 -6753 E0101; Adobe-Japan1; CID+7695 -6753 E0102; Hanyo-Denshi; JA2861 -6753 E0102; Moji_Joho; MJ013617 -6753 E0103; Hanyo-Denshi; FT1816 -6753 E0103; Moji_Joho; MJ013616 -6754 E0100; Adobe-Japan1; CID+17766 -6755 E0100; Adobe-Japan1; CID+19444 -6756 E0100; Adobe-Japan1; CID+2523 -6756 E0101; Adobe-Japan1; CID+20282 -6756 E0102; Hanyo-Denshi; JA3083 -6756 E0103; Hanyo-Denshi; JTB2FB -6756 E0103; Moji_Joho; MJ013621 -6756 E0104; Hanyo-Denshi; TK01043060 -6756 E0105; Moji_Joho; MJ013620 -6756 E0106; Moji_Joho; MJ013622 -6757 E0100; Hanyo-Denshi; IP6757 -6757 E0100; Moji_Joho; MJ013623 -6757 E0101; Hanyo-Denshi; KS163230 -6757 E0101; Moji_Joho; MJ013624 -6759 E0100; Adobe-Japan1; CID+5150 -675C E0100; Adobe-Japan1; CID+3144 -675C E0101; Hanyo-Denshi; JA3746 -675C E0101; Moji_Joho; MJ013629 -675C E0102; Hanyo-Denshi; KS164250 -675C E0102; Moji_Joho; MJ057711 -675D E0100; Adobe-Japan1; CID+17767 -675E E0100; Adobe-Japan1; CID+5148 -675E E0101; Adobe-Japan1; CID+14140 -675E E0102; Hanyo-Denshi; JA5925 -675E E0102; Moji_Joho; MJ013631 -675E E0103; Hanyo-Denshi; JTB2F6 -675E E0103; Moji_Joho; MJ013632 -675F E0100; Adobe-Japan1; CID+2827 -6760 E0100; Adobe-Japan1; CID+5149 -6761 E0100; Adobe-Japan1; CID+2522 -6761 E0101; Adobe-Japan1; CID+20144 -6761 E0102; Hanyo-Denshi; JA3082 -6761 E0103; Hanyo-Denshi; TK01042960 -6762 E0100; Adobe-Japan1; CID+3817 -6763 E0100; Adobe-Japan1; CID+5151 -6764 E0100; Adobe-Japan1; CID+5152 -6765 E0100; Adobe-Japan1; CID+3922 -6766 E0100; Adobe-Japan1; CID+8490 -6766 E0101; Hanyo-Denshi; JB3501 -6766 E0102; Hanyo-Denshi; TK01042840 -6768 E0100; Hanyo-Denshi; TK01042900 -6768 E0101; Hanyo-Denshi; TK01043170 -6768 E0102; Hanyo-Denshi; TK01043320 -676A E0100; Adobe-Japan1; CID+5157 -676C E0100; Adobe-Japan1; CID+21737 -676D E0100; Adobe-Japan1; CID+1996 -676D E0101; Hanyo-Denshi; JA2526 -676D E0102; Hanyo-Denshi; TK01043010 -676E E0100; Adobe-Japan1; CID+13681 -676F E0100; Adobe-Japan1; CID+3339 -6770 E0100; Adobe-Japan1; CID+5154 -6771 E0100; Adobe-Japan1; CID+3174 -6772 E0100; Adobe-Japan1; CID+5091 -6773 E0100; Adobe-Japan1; CID+5095 -6774 E0100; Adobe-Japan1; CID+17771 -6775 E0100; Adobe-Japan1; CID+1641 -6776 E0100; Adobe-Japan1; CID+14618 -6777 E0100; Adobe-Japan1; CID+3325 -677B E0100; Adobe-Japan1; CID+14619 -677C E0100; Adobe-Japan1; CID+5156 -677E E0100; Adobe-Japan1; CID+2470 -677E E0101; Adobe-Japan1; CID+13461 -677E E0102; Hanyo-Denshi; JA3030 -677E E0102; Moji_Joho; MJ013667 -677E E0103; Hanyo-Denshi; FT1638 -677E E0103; Moji_Joho; MJ013668 -677F E0100; Adobe-Japan1; CID+3416 -6780 E0100; Adobe-Japan1; CID+19445 -6781 E0100; Adobe-Japan1; CID+16896 -6781 E0101; Hanyo-Denshi; JB3507 -6781 E0101; Moji_Joho; MJ013672 -6781 E0102; Hanyo-Denshi; IB0225 -6781 E0102; Moji_Joho; MJ013671 -6783 E0100; Hanyo-Denshi; IP6783 -6783 E0101; Hanyo-Denshi; TK01043190 -6784 E0100; Adobe-Japan1; CID+21738 -6785 E0100; Adobe-Japan1; CID+5162 -6785 E0101; Hanyo-Denshi; JA5939 -6785 E0101; Moji_Joho; MJ013677 -6785 E0102; Hanyo-Denshi; JTB31B -6785 E0102; Moji_Joho; MJ013678 -6785 E0103; Hanyo-Denshi; JTB31C -6785 E0103; Moji_Joho; MJ013679 -6787 E0100; Adobe-Japan1; CID+3470 -6788 E0100; Hanyo-Denshi; IP6788 -6788 E0101; Hanyo-Denshi; TK01043050 -6789 E0100; Adobe-Japan1; CID+5153 -678B E0100; Adobe-Japan1; CID+5159 -678C E0100; Adobe-Japan1; CID+5158 -678C E0101; Hanyo-Denshi; JA5935 -678C E0101; Moji_Joho; MJ013687 -678C E0102; Hanyo-Denshi; FT2239 -678C E0102; Moji_Joho; MJ013688 -678E E0100; Adobe-Japan1; CID+21739 -678F E0100; Adobe-Japan1; CID+19446 -6790 E0100; Adobe-Japan1; CID+2675 -6791 E0100; Adobe-Japan1; CID+19447 -6792 E0100; Adobe-Japan1; CID+17773 -6792 E0101; Hanyo-Denshi; JD1440 -6792 E0101; Moji_Joho; MJ013695 -6792 E0102; Hanyo-Denshi; JD1440S -6792 E0102; Moji_Joho; MJ013694 -6793 E0100; Adobe-Japan1; CID+16897 -6794 E0100; Hanyo-Denshi; IP6794 -6794 E0100; Moji_Joho; MJ013697 -6794 E0101; Hanyo-Denshi; JTB309 -6794 E0101; Moji_Joho; MJ059710 -6795 E0100; Adobe-Japan1; CID+3739 -6795 E0101; Hanyo-Denshi; JA4377 -6795 E0101; Moji_Joho; MJ013698 -6795 E0102; Hanyo-Denshi; KS165530 -6795 E0102; Moji_Joho; MJ057718 -6796 E0100; Adobe-Japan1; CID+21740 -6797 E0100; Adobe-Japan1; CID+3995 -6798 E0100; Adobe-Japan1; CID+16898 -6799 E0100; Adobe-Japan1; CID+21741 -679A E0100; Adobe-Japan1; CID+3733 -679B E0100; Adobe-Japan1; CID+16899 -679C E0100; Adobe-Japan1; CID+1356 -679D E0100; Adobe-Japan1; CID+2220 -67A0 E0100; Adobe-Japan1; CID+4078 -67A1 E0100; Adobe-Japan1; CID+5161 -67A1 E0101; Hanyo-Denshi; JA5938 -67A1 E0102; Hanyo-Denshi; TK01043300 -67A1 E0103; Hanyo-Denshi; TK01043340 -67A2 E0100; Adobe-Japan1; CID+2619 -67A4 E0100; Adobe-Japan1; CID+19448 -67A6 E0100; Adobe-Japan1; CID+5160 -67A6 E0101; Adobe-Japan1; CID+7833 -67A6 E0102; Hanyo-Denshi; JA5937 -67A6 E0102; Moji_Joho; MJ013712 -67A6 E0103; Hanyo-Denshi; FT1959 -67A6 E0103; Moji_Joho; MJ013713 -67A9 E0100; Adobe-Japan1; CID+5155 -67A9 E0101; Adobe-Japan1; CID+13549 -67A9 E0102; Hanyo-Denshi; JA5932 -67A9 E0102; Moji_Joho; MJ013714 -67A9 E0103; Hanyo-Denshi; FT1701 -67A9 E0103; Moji_Joho; MJ013715 -67AF E0100; Adobe-Japan1; CID+1923 -67B0 E0100; Adobe-Japan1; CID+14620 -67B0 E0101; Hanyo-Denshi; JB3517 -67B0 E0102; Hanyo-Denshi; TK01043480 -67B1 E0100; Adobe-Japan1; CID+19449 -67B2 E0100; Adobe-Japan1; CID+14621 -67B3 E0100; Adobe-Japan1; CID+5167 -67B4 E0100; Adobe-Japan1; CID+5165 -67B5 E0100; Adobe-Japan1; CID+19450 -67B6 E0100; Adobe-Japan1; CID+1357 -67B7 E0100; Adobe-Japan1; CID+5163 -67B8 E0100; Adobe-Japan1; CID+5169 -67B9 E0100; Adobe-Japan1; CID+5175 -67B9 E0101; Hanyo-Denshi; JA5952 -67B9 E0101; Moji_Joho; MJ013730 -67B9 E0102; Hanyo-Denshi; FT2240 -67B9 E0102; Moji_Joho; MJ013731 -67BB E0100; Adobe-Japan1; CID+8491 -67BC E0100; Adobe-Japan1; CID+21742 -67BD E0100; Adobe-Japan1; CID+21743 -67BE E0100; Adobe-Japan1; CID+19451 -67C0 E0100; Adobe-Japan1; CID+8493 -67C1 E0100; Adobe-Japan1; CID+2856 -67C2 E0100; Adobe-Japan1; CID+21744 -67C3 E0100; Adobe-Japan1; CID+17777 -67C4 E0100; Adobe-Japan1; CID+3601 -67C4 E0101; Adobe-Japan1; CID+20145 -67C4 E0102; Hanyo-Denshi; JA4233 -67C4 E0102; Moji_Joho; MJ013742 -67C4 E0103; Hanyo-Denshi; JTC0E8 -67C4 E0103; Moji_Joho; MJ013743 -67C5 E0100; Adobe-Japan1; CID+21745 -67C6 E0100; Adobe-Japan1; CID+5177 -67C8 E0100; Adobe-Japan1; CID+17778 -67C8 E0101; Hanyo-Denshi; JB3529 -67C8 E0102; Hanyo-Denshi; TK01043430 -67C9 E0100; Adobe-Japan1; CID+21746 -67CA E0100; Adobe-Japan1; CID+3476 -67CA E0101; Adobe-Japan1; CID+7781 -67CA E0102; Hanyo-Denshi; JA4102 -67CA E0102; Moji_Joho; MJ013751 -67CA E0103; Hanyo-Denshi; FT1908 -67CA E0103; Moji_Joho; MJ013750 -67CE E0100; Adobe-Japan1; CID+5176 -67CF E0100; Adobe-Japan1; CID+3366 -67D0 E0100; Adobe-Japan1; CID+3693 -67D1 E0100; Adobe-Japan1; CID+1527 -67D2 E0100; Adobe-Japan1; CID+17779 -67D3 E0100; Adobe-Japan1; CID+2715 -67D4 E0100; Adobe-Japan1; CID+2378 -67D4 E0101; Adobe-Japan1; CID+13457 -67D4 E0102; Moji_Joho; MJ013761 -67D4 E0103; Moji_Joho; MJ013762 -67D7 E0100; Adobe-Japan1; CID+14623 -67D7 E0101; Hanyo-Denshi; JC8559 -67D7 E0101; Moji_Joho; MJ013765 -67D7 E0102; Hanyo-Denshi; JTB30A -67D7 E0102; Moji_Joho; MJ059711 -67D8 E0100; Adobe-Japan1; CID+3055 -67D8 E0101; Hanyo-Denshi; JA3651 -67D8 E0102; Hanyo-Denshi; TK01043550 -67D9 E0100; Adobe-Japan1; CID+14624 -67DA E0100; Adobe-Japan1; CID+3864 -67DB E0100; Adobe-Japan1; CID+17780 -67DC E0100; Adobe-Japan1; CID+21747 -67DC E0101; Hanyo-Denshi; JB3534 -67DC E0101; Moji_Joho; MJ013770 -67DC E0102; Hanyo-Denshi; JTB305 -67DC E0102; Moji_Joho; MJ013771 -67DD E0100; Adobe-Japan1; CID+5172 -67DE E0100; Adobe-Japan1; CID+5171 -67DF E0100; Hanyo-Denshi; IP67DF -67DF E0101; Hanyo-Denshi; TK01043490 -67E1 E0100; Adobe-Japan1; CID+21748 -67E2 E0100; Adobe-Japan1; CID+5173 -67E4 E0100; Adobe-Japan1; CID+5170 -67E6 E0100; Adobe-Japan1; CID+21749 -67E7 E0100; Adobe-Japan1; CID+5178 -67E7 E0101; Adobe-Japan1; CID+13550 -67E7 E0102; Hanyo-Denshi; JA5955 -67E7 E0102; Moji_Joho; MJ013784 -67E7 E0103; Hanyo-Denshi; JTB30ES -67E7 E0103; Moji_Joho; MJ013783 -67E9 E0100; Adobe-Japan1; CID+5168 -67EC E0100; Adobe-Japan1; CID+5166 -67ED E0100; Hanyo-Denshi; JT67ED -67ED E0101; Hanyo-Denshi; TK01042950 -67EE E0100; Adobe-Japan1; CID+5174 -67EF E0100; Adobe-Japan1; CID+5164 -67F0 E0100; Adobe-Japan1; CID+14625 -67F1 E0100; Adobe-Japan1; CID+2986 -67F1 E0101; Adobe-Japan1; CID+13925 -67F1 E0102; Hanyo-Denshi; JA3576 -67F1 E0102; Moji_Joho; MJ013794 -67F1 E0103; Hanyo-Denshi; JTB306 -67F1 E0103; Moji_Joho; MJ013795 -67F2 E0100; Adobe-Japan1; CID+21750 -67F3 E0100; Adobe-Japan1; CID+3844 -67F3 E0101; Hanyo-Denshi; JA4488 -67F3 E0101; Moji_Joho; MJ013797 -67F3 E0102; Hanyo-Denshi; JTB304 -67F3 E0102; Moji_Joho; MJ013798 -67F4 E0100; Adobe-Japan1; CID+2290 -67F5 E0100; Adobe-Japan1; CID+2148 -67F6 E0100; Adobe-Japan1; CID+21751 -67F7 E0100; Adobe-Japan1; CID+17781 -67F9 E0100; Adobe-Japan1; CID+14622 -67F9 E0101; Hanyo-Denshi; JB3524 -67F9 E0102; Hanyo-Denshi; TK01042990 -67FA E0100; Adobe-Japan1; CID+7834 -67FA E0101; Hanyo-Denshi; FT1960 -67FA E0101; Moji_Joho; MJ013807 -67FA E0102; Hanyo-Denshi; IP67FA -67FA E0102; Moji_Joho; MJ013806 -67FB E0100; Adobe-Japan1; CID+2090 -67FB E0101; Hanyo-Denshi; JA2626 -67FB E0102; Hanyo-Denshi; KS166860 -67FC E0100; Adobe-Japan1; CID+16900 -67FC E0101; Hanyo-Denshi; JC8560 -67FC E0102; Hanyo-Denshi; TK01043220 -67FE E0100; Adobe-Japan1; CID+3741 -67FF E0100; Adobe-Japan1; CID+1439 -6801 E0100; Adobe-Japan1; CID+14066 -6801 E0101; Adobe-Japan1; CID+8494 -6801 E0102; Hanyo-Denshi; JC8561 -6801 E0102; Moji_Joho; MJ013815 -6801 E0103; Hanyo-Denshi; FT2921 -6801 E0103; Moji_Joho; MJ013816 -6802 E0100; Adobe-Japan1; CID+3050 -6802 E0101; Adobe-Japan1; CID+20146 -6803 E0100; Adobe-Japan1; CID+3234 -6803 E0101; Hanyo-Denshi; JA3842 -6803 E0101; Moji_Joho; MJ013818 -6803 E0102; Hanyo-Denshi; JTB310 -6803 E0102; Moji_Joho; MJ013819 -6804 E0100; Adobe-Japan1; CID+1259 -6805 E0100; Adobe-Japan1; CID+7687 -6810 E0100; Adobe-Japan1; CID+17776 -6813 E0100; Adobe-Japan1; CID+2710 -6813 E0101; Adobe-Japan1; CID+7717 -6813 E0102; Hanyo-Denshi; JA3282 -6813 E0102; Moji_Joho; MJ013827 -6813 E0103; Hanyo-Denshi; JTB319 -6813 E0103; Moji_Joho; MJ013826 -6814 E0100; Adobe-Japan1; CID+21752 -6814 E0101; Hanyo-Denshi; JB3542 -6814 E0101; Moji_Joho; MJ013828 -6814 E0102; Hanyo-Denshi; KS166890 -6814 E0102; Moji_Joho; MJ013829 -6814 E0103; Hanyo-Denshi; TK01010010 -6816 E0100; Adobe-Japan1; CID+2648 -6816 E0101; Hanyo-Denshi; JA3220 -6816 E0101; Moji_Joho; MJ013832 -6816 E0102; Hanyo-Denshi; JTB31E -6816 E0102; Moji_Joho; MJ013833 -6817 E0100; Adobe-Japan1; CID+1792 -6818 E0100; Adobe-Japan1; CID+17785 -6819 E0100; Adobe-Japan1; CID+21753 -681D E0100; Adobe-Japan1; CID+16901 -681E E0100; Adobe-Japan1; CID+5180 -681F E0100; Adobe-Japan1; CID+17786 -681F E0101; Adobe-Japan1; CID+20065 -681F E0102; Hanyo-Denshi; JB3545 -681F E0102; Moji_Joho; MJ013843 -681F E0103; Hanyo-Denshi; KS169300 -681F E0103; Moji_Joho; MJ013844 -681F E0104; Hanyo-Denshi; TK01044250 -6821 E0100; Adobe-Japan1; CID+1997 -6821 E0101; Adobe-Japan1; CID+13442 -6821 E0102; Moji_Joho; MJ013846 -6821 E0103; Moji_Joho; MJ013847 -6822 E0100; Adobe-Japan1; CID+1498 -6825 E0100; Hanyo-Denshi; IP6825 -6825 E0100; Moji_Joho; MJ013851 -6825 E0101; Hanyo-Denshi; JT6825 -6825 E0101; Moji_Joho; MJ013852 -6827 E0100; Adobe-Japan1; CID+21754 -6828 E0100; Adobe-Japan1; CID+19452 -6829 E0100; Adobe-Japan1; CID+5182 -6829 E0101; Hanyo-Denshi; JA5959 -6829 E0101; Moji_Joho; MJ013856 -6829 E0102; Hanyo-Denshi; FT2241 -6829 E0102; Moji_Joho; MJ013857 -682A E0100; Adobe-Japan1; CID+1490 -682B E0100; Adobe-Japan1; CID+5188 -682C E0100; Adobe-Japan1; CID+14626 -682D E0100; Adobe-Japan1; CID+17787 -682F E0100; Adobe-Japan1; CID+21755 -6830 E0100; Adobe-Japan1; CID+14627 -6831 E0100; Adobe-Japan1; CID+14628 -6832 E0100; Adobe-Japan1; CID+5185 -6832 E0101; Hanyo-Denshi; JA5962 -6832 E0101; Moji_Joho; MJ013866 -6832 E0102; Hanyo-Denshi; JTB31A -6832 E0102; Moji_Joho; MJ013867 -6833 E0100; Adobe-Japan1; CID+17789 -6834 E0100; Adobe-Japan1; CID+2711 -6834 E0101; Hanyo-Denshi; JA3283 -6834 E0101; Moji_Joho; MJ013869 -6834 E0102; Hanyo-Denshi; KS166810 -6834 E0102; Moji_Joho; MJ013870 -6838 E0100; Adobe-Japan1; CID+1449 -6838 E0101; Hanyo-Denshi; JA1943 -6838 E0101; Moji_Joho; MJ013874 -6838 E0102; Hanyo-Denshi; JTB317 -6838 E0102; Moji_Joho; MJ013875 -6839 E0100; Adobe-Japan1; CID+2076 -683B E0100; Adobe-Japan1; CID+17790 -683C E0100; Adobe-Japan1; CID+1448 -683D E0100; Adobe-Japan1; CID+2111 -683E E0100; Adobe-Japan1; CID+17791 -683F E0100; Adobe-Japan1; CID+21756 -6840 E0100; Adobe-Japan1; CID+5183 -6840 E0101; Hanyo-Denshi; JA5960 -6840 E0101; Moji_Joho; MJ013884 -6840 E0102; Hanyo-Denshi; JTB31D -6840 E0102; Moji_Joho; MJ013883 -6840 E0103; Moji_Joho; MJ013885 -6841 E0100; Adobe-Japan1; CID+1851 -6842 E0100; Adobe-Japan1; CID+1825 -6843 E0100; Adobe-Japan1; CID+3175 -6843 E0101; Adobe-Japan1; CID+13484 -6844 E0100; Adobe-Japan1; CID+8495 -6845 E0100; Adobe-Japan1; CID+17792 -6845 E0101; Hanyo-Denshi; JB3557 -6845 E0101; Moji_Joho; MJ013890 -6845 E0102; Hanyo-Denshi; JTB318 -6845 E0102; Moji_Joho; MJ013891 -6846 E0100; Adobe-Japan1; CID+5181 -6848 E0100; Adobe-Japan1; CID+1162 -6849 E0100; Adobe-Japan1; CID+17793 -684A E0100; Adobe-Japan1; CID+21757 -684C E0100; Adobe-Japan1; CID+17794 -684D E0100; Adobe-Japan1; CID+5184 -684E E0100; Adobe-Japan1; CID+5186 -6850 E0100; Adobe-Japan1; CID+1733 -6851 E0100; Adobe-Japan1; CID+1794 -6852 E0100; Adobe-Japan1; CID+14291 -6852 E0101; Adobe-Japan1; CID+8492 -6852 E0102; Hanyo-Denshi; JB3541 -6852 E0102; Moji_Joho; MJ013904 -6852 E0103; Hanyo-Denshi; JTB302 -6852 E0103; Moji_Joho; MJ013905 -6852 E0104; Hanyo-Denshi; FT2913 -6852 E0104; Moji_Joho; MJ013907 -6852 E0105; Moji_Joho; MJ013906 -6853 E0100; Adobe-Japan1; CID+1528 -6854 E0100; Adobe-Japan1; CID+1637 -6855 E0100; Adobe-Japan1; CID+17795 -6855 E0101; Hanyo-Denshi; JB3560 -6855 E0102; Hanyo-Denshi; TK01043950 -6857 E0100; Adobe-Japan1; CID+17796 -6858 E0100; Adobe-Japan1; CID+21758 -6859 E0100; Adobe-Japan1; CID+5189 -685B E0100; Adobe-Japan1; CID+14629 -685C E0100; Adobe-Japan1; CID+2153 -685D E0100; Adobe-Japan1; CID+3743 -685D E0101; Adobe-Japan1; CID+13509 -685D E0102; Adobe-Japan1; CID+14046 -685D E0103; Hanyo-Denshi; JA4381 -685D E0103; Moji_Joho; MJ013919 -685D E0104; Hanyo-Denshi; KS166630 -685D E0104; Moji_Joho; MJ013918 -685D E0105; Moji_Joho; MJ013920 -685F E0100; Adobe-Japan1; CID+2181 -685F E0101; Hanyo-Denshi; JA2723 -685F E0102; Hanyo-Denshi; TK01043540 -6863 E0100; Adobe-Japan1; CID+5190 -6867 E0100; Adobe-Japan1; CID+3490 -686B E0100; Adobe-Japan1; CID+17798 -686E E0100; Adobe-Japan1; CID+17799 -686F E0100; Adobe-Japan1; CID+21759 -686F E0101; Hanyo-Denshi; JB3566 -686F E0102; Hanyo-Denshi; TK01044430 -6870 E0100; Adobe-Japan1; CID+21760 -6871 E0100; Adobe-Japan1; CID+21761 -6872 E0100; Adobe-Japan1; CID+14630 -6874 E0100; Adobe-Japan1; CID+5202 -6874 E0101; Hanyo-Denshi; JA5979 -6874 E0101; Moji_Joho; MJ013937 -6874 E0102; Hanyo-Denshi; FT2245 -6874 E0102; Moji_Joho; MJ013938 -6875 E0100; Adobe-Japan1; CID+14631 -6875 E0101; Hanyo-Denshi; JB3570 -6875 E0101; Moji_Joho; MJ013939 -6875 E0102; Hanyo-Denshi; JTB327S -6875 E0102; Moji_Joho; MJ013940 -6876 E0100; Adobe-Japan1; CID+1331 -6877 E0100; Adobe-Japan1; CID+5191 -6879 E0100; Adobe-Japan1; CID+21762 -687A E0100; Adobe-Japan1; CID+14632 -687A E0101; Adobe-Japan1; CID+14064 -687A E0102; Adobe-Japan1; CID+14065 -687A E0103; Hanyo-Denshi; JB3572 -687A E0104; Hanyo-Denshi; TK01043630 -687A E0105; Hanyo-Denshi; TK01044360 -687B E0100; Adobe-Japan1; CID+21763 -687C E0100; Adobe-Japan1; CID+17800 -687E E0100; Adobe-Japan1; CID+5208 -687F E0100; Adobe-Japan1; CID+5192 -6881 E0100; Adobe-Japan1; CID+3978 -6881 E0101; Adobe-Japan1; CID+14089 -6881 E0102; Hanyo-Denshi; JA4634 -6881 E0103; Hanyo-Denshi; TK01044200 -6882 E0100; Adobe-Japan1; CID+17801 -6883 E0100; Adobe-Japan1; CID+5199 -6883 E0101; Moji_Joho; MJ013957 -6883 E0102; Moji_Joho; MJ013958 -6884 E0100; Adobe-Japan1; CID+14633 -6884 E0101; Hanyo-Denshi; JB3576 -6884 E0102; Hanyo-Denshi; TK01044150 -6885 E0100; Adobe-Japan1; CID+13375 -6885 E0101; Adobe-Japan1; CID+3349 -6885 E0102; Hanyo-Denshi; JA3963 -6885 E0103; Hanyo-Denshi; JC8569 -6886 E0100; Adobe-Japan1; CID+19453 -6886 E0101; Hanyo-Denshi; JB3577 -6886 E0101; Moji_Joho; MJ013962 -6886 E0102; Hanyo-Denshi; JTB32A -6886 E0102; Moji_Joho; MJ013963 -6888 E0100; Adobe-Japan1; CID+21764 -6889 E0100; Hanyo-Denshi; IP6889 -6889 E0101; Hanyo-Denshi; TK01043780 -688D E0100; Adobe-Japan1; CID+5207 -688D E0101; Adobe-Japan1; CID+14142 -688E E0100; Adobe-Japan1; CID+7836 -688F E0100; Adobe-Japan1; CID+5194 -688F E0101; Hanyo-Denshi; JA5971 -688F E0101; Moji_Joho; MJ013973 -688F E0102; Hanyo-Denshi; FT2243 -688F E0102; Moji_Joho; MJ013974 -6890 E0100; Adobe-Japan1; CID+17802 -6893 E0100; Adobe-Japan1; CID+1144 -6894 E0100; Adobe-Japan1; CID+5196 -6896 E0100; Adobe-Japan1; CID+17803 -6897 E0100; Adobe-Japan1; CID+1998 -6897 E0101; Adobe-Japan1; CID+20279 -6897 E0102; Moji_Joho; MJ013982 -6897 E0103; Moji_Joho; MJ013983 -6898 E0100; Adobe-Japan1; CID+17805 -6899 E0100; Adobe-Japan1; CID+17806 -689A E0100; Adobe-Japan1; CID+17807 -689A E0101; Hanyo-Denshi; JB3581 -689A E0102; Hanyo-Denshi; TK01043980 -689B E0100; Adobe-Japan1; CID+5198 -689B E0101; Adobe-Japan1; CID+7835 -689B E0102; Hanyo-Denshi; JA5975 -689B E0102; Moji_Joho; MJ013989 -689B E0103; Hanyo-Denshi; FT1961 -689B E0103; Moji_Joho; MJ013988 -689C E0100; Adobe-Japan1; CID+17808 -689D E0100; Adobe-Japan1; CID+5197 -689D E0101; Adobe-Japan1; CID+14141 -689D E0102; Hanyo-Denshi; JA5974 -689D E0102; Moji_Joho; MJ013991 -689D E0103; Hanyo-Denshi; KS009710 -689D E0103; Moji_Joho; MJ056933 -689F E0100; Adobe-Japan1; CID+5193 -689F E0101; Hanyo-Denshi; JA5970 -689F E0101; Moji_Joho; MJ013993 -689F E0102; Hanyo-Denshi; JTB336 -689F E0102; Moji_Joho; MJ013994 -68A0 E0100; Adobe-Japan1; CID+5204 -68A1 E0100; Adobe-Japan1; CID+21765 -68A2 E0100; Adobe-Japan1; CID+2471 -68A2 E0101; Adobe-Japan1; CID+7705 -68A2 E0102; Hanyo-Denshi; JA3031 -68A2 E0102; Moji_Joho; MJ013998 -68A2 E0103; Hanyo-Denshi; FT1826 -68A2 E0103; Moji_Joho; MJ013997 -68A3 E0100; Adobe-Japan1; CID+16902 -68A5 E0100; Adobe-Japan1; CID+14634 -68A5 E0101; Hanyo-Denshi; JB3585 -68A5 E0101; Moji_Joho; MJ014001 -68A5 E0102; Hanyo-Denshi; IB1667 -68A5 E0102; Moji_Joho; MJ014002 -68A5 E0103; Hanyo-Denshi; TK01044410 -68A6 E0100; Adobe-Japan1; CID+4542 -68A7 E0100; Adobe-Japan1; CID+1948 -68A8 E0100; Adobe-Japan1; CID+3942 -68A9 E0100; Adobe-Japan1; CID+21766 -68AA E0100; Adobe-Japan1; CID+17809 -68AB E0100; Adobe-Japan1; CID+17810 -68AD E0100; Adobe-Japan1; CID+5195 -68AD E0101; Hanyo-Denshi; JA5972 -68AD E0101; Moji_Joho; MJ014013 -68AD E0102; Hanyo-Denshi; KS167720 -68AD E0102; Moji_Joho; MJ014012 -68AE E0100; Adobe-Japan1; CID+21767 -68AF E0100; Adobe-Japan1; CID+3088 -68B0 E0100; Adobe-Japan1; CID+1409 -68B1 E0100; Adobe-Japan1; CID+2077 -68B2 E0100; Adobe-Japan1; CID+14635 -68B3 E0100; Adobe-Japan1; CID+5187 -68B4 E0100; Adobe-Japan1; CID+17811 -68B5 E0100; Adobe-Japan1; CID+5203 -68B5 E0101; Hanyo-Denshi; JA5980 -68B5 E0101; Moji_Joho; MJ014021 -68B5 E0102; Hanyo-Denshi; JTB325 -68B5 E0102; Moji_Joho; MJ014022 -68B6 E0100; Adobe-Japan1; CID+1471 -68B9 E0100; Adobe-Japan1; CID+5201 -68BA E0100; Adobe-Japan1; CID+5205 -68BB E0100; Adobe-Japan1; CID+17812 -68BC E0100; Adobe-Japan1; CID+3176 -68C3 E0100; Adobe-Japan1; CID+17816 -68C4 E0100; Adobe-Japan1; CID+1594 -68C4 E0101; Hanyo-Denshi; JA2094 -68C4 E0101; Moji_Joho; MJ014032 -68C4 E0102; Hanyo-Denshi; KS170110 -68C4 E0102; Moji_Joho; MJ014033 -68C5 E0100; Adobe-Japan1; CID+17817 -68C6 E0100; Adobe-Japan1; CID+5235 -68C8 E0100; Adobe-Japan1; CID+8367 -68C8 E0101; Adobe-Japan1; CID+14284 -68C8 E0102; Hanyo-Denshi; JB3592 -68C8 E0102; Moji_Joho; MJ014037 -68C8 E0103; Hanyo-Denshi; IB0714 -68C8 E0103; Moji_Joho; MJ014038 -68C9 E0100; Adobe-Japan1; CID+3797 -68CA E0100; Adobe-Japan1; CID+5210 -68CB E0100; Adobe-Japan1; CID+1593 -68CC E0100; Adobe-Japan1; CID+17818 -68CC E0101; Hanyo-Denshi; JB3593 -68CC E0102; Hanyo-Denshi; TK01044800 -68CD E0100; Adobe-Japan1; CID+5217 -68CF E0100; Adobe-Japan1; CID+8496 -68CF E0101; Hanyo-Denshi; JB3594 -68CF E0101; Moji_Joho; MJ014046 -68CF E0102; Hanyo-Denshi; JTB340 -68CF E0102; Moji_Joho; MJ014047 -68D0 E0100; Adobe-Japan1; CID+14636 -68D0 E0101; Hanyo-Denshi; JB3601 -68D0 E0102; Hanyo-Denshi; TK01044850 -68D1 E0100; Adobe-Japan1; CID+21768 -68D2 E0100; Adobe-Japan1; CID+3694 -68D3 E0100; Adobe-Japan1; CID+21769 -68D4 E0100; Adobe-Japan1; CID+5218 -68D5 E0100; Adobe-Japan1; CID+5220 -68D6 E0100; Adobe-Japan1; CID+14637 -68D7 E0100; Adobe-Japan1; CID+5224 -68D8 E0100; Adobe-Japan1; CID+5212 -68D9 E0100; Adobe-Japan1; CID+17819 -68DA E0100; Adobe-Japan1; CID+2920 -68DA E0101; Adobe-Japan1; CID+7736 -68DA E0102; Hanyo-Denshi; JA3510 -68DA E0102; Moji_Joho; MJ014060 -68DA E0103; Hanyo-Denshi; FT1856 -68DA E0103; Moji_Joho; MJ014059 -68DC E0100; Adobe-Japan1; CID+21770 -68DD E0100; Adobe-Japan1; CID+21771 -68DF E0100; Adobe-Japan1; CID+3177 -68E0 E0100; Adobe-Japan1; CID+5228 -68E1 E0100; Adobe-Japan1; CID+5215 -68E3 E0100; Adobe-Japan1; CID+5225 -68E4 E0100; Adobe-Japan1; CID+17820 -68E5 E0100; Adobe-Japan1; CID+17821 -68E6 E0100; Hanyo-Denshi; IP68E6 -68E6 E0101; Hanyo-Denshi; TK01043860 -68E7 E0100; Adobe-Japan1; CID+5219 -68E8 E0100; Adobe-Japan1; CID+14638 -68EA E0100; Adobe-Japan1; CID+21772 -68EB E0100; Adobe-Japan1; CID+19454 -68EC E0100; Adobe-Japan1; CID+17822 -68ED E0100; Adobe-Japan1; CID+14639 -68EE E0100; Adobe-Japan1; CID+2559 -68EF E0100; Adobe-Japan1; CID+5229 -68F0 E0100; Adobe-Japan1; CID+14640 -68F1 E0100; Adobe-Japan1; CID+14641 -68F2 E0100; Adobe-Japan1; CID+2647 -68F5 E0100; Adobe-Japan1; CID+19455 -68F6 E0100; Adobe-Japan1; CID+21773 -68F7 E0100; Adobe-Japan1; CID+17823 -68F9 E0100; Adobe-Japan1; CID+5227 -68FA E0100; Adobe-Japan1; CID+1529 -68FB E0100; Adobe-Japan1; CID+17813 -68FB E0101; Hanyo-Denshi; JB3618 -68FB E0101; Moji_Joho; MJ014094 -68FB E0102; Hanyo-Denshi; KS169140 -68FB E0102; Moji_Joho; MJ014095 -68FC E0100; Adobe-Japan1; CID+14642 -68FD E0100; Adobe-Japan1; CID+21774 -6900 E0100; Adobe-Japan1; CID+4086 -6900 E0101; Hanyo-Denshi; JA4748 -6900 E0102; Hanyo-Denshi; JTB33E -6901 E0100; Adobe-Japan1; CID+5209 -6902 E0100; Hanyo-Denshi; IP6902 -6902 E0101; Hanyo-Denshi; TK01044810 -6903 E0100; Adobe-Japan1; CID+17824 -6903 E0101; Hanyo-Denshi; JD1506 -6903 E0102; Hanyo-Denshi; TK01044820 -6904 E0100; Adobe-Japan1; CID+5223 -6905 E0100; Adobe-Japan1; CID+1180 -6906 E0100; Adobe-Japan1; CID+21775 -6906 E0101; Hanyo-Denshi; JB3621 -6906 E0102; Hanyo-Denshi; TK01044830 -6907 E0100; Adobe-Japan1; CID+17825 -6907 E0101; Hanyo-Denshi; JD1507 -6907 E0101; Moji_Joho; MJ014111 -6907 E0102; Hanyo-Denshi; IP6907 -6907 E0102; Moji_Joho; MJ014110 -6908 E0100; Adobe-Japan1; CID+5211 -6909 E0100; Adobe-Japan1; CID+21776 -690A E0100; Adobe-Japan1; CID+16903 -690B E0100; Adobe-Japan1; CID+3782 -690C E0100; Adobe-Japan1; CID+5216 -690C E0101; Hanyo-Denshi; JA5993 -690C E0101; Moji_Joho; MJ014116 -690C E0102; Hanyo-Denshi; JTB33D -690C E0102; Moji_Joho; MJ014117 -690D E0100; Adobe-Japan1; CID+2536 -690D E0101; Adobe-Japan1; CID+13465 -690D E0102; Adobe-Japan1; CID+13845 -690D E0103; Hanyo-Denshi; JA3102 -690D E0103; Moji_Joho; MJ014118 -690D E0104; Hanyo-Denshi; KS170180 -690D E0104; Moji_Joho; MJ057753 -690D E0105; Hanyo-Denshi; TK01044570 -690E E0100; Adobe-Japan1; CID+3043 -690F E0100; Adobe-Japan1; CID+5206 -6910 E0100; Adobe-Japan1; CID+21777 -6911 E0100; Adobe-Japan1; CID+14643 -6911 E0101; Hanyo-Denshi; JB3625 -6911 E0101; Moji_Joho; MJ014123 -6911 E0102; Hanyo-Denshi; KS168340 -6911 E0102; Moji_Joho; MJ057741 -6912 E0100; Adobe-Japan1; CID+5222 -6913 E0100; Adobe-Japan1; CID+14644 -6914 E0100; Hanyo-Denshi; IP6914 -6914 E0100; Moji_Joho; MJ014126 -6914 E0101; Hanyo-Denshi; KS170290 -6914 E0101; Moji_Joho; MJ014127 -6916 E0100; Adobe-Japan1; CID+21778 -6916 E0101; Hanyo-Denshi; JB3627 -6916 E0102; Hanyo-Denshi; TK01044840 -6917 E0100; Adobe-Japan1; CID+19456 -6919 E0100; Adobe-Japan1; CID+2624 -691A E0100; Adobe-Japan1; CID+5232 -691B E0100; Adobe-Japan1; CID+1487 -691B E0101; Hanyo-Denshi; JA1981 -691B E0101; Moji_Joho; MJ014135 -691B E0102; Hanyo-Denshi; KS169840 -691B E0102; Moji_Joho; MJ014136 -691B E0103; Moji_Joho; MJ014137 -691C E0100; Adobe-Japan1; CID+1877 -6921 E0100; Adobe-Japan1; CID+5234 -6922 E0100; Adobe-Japan1; CID+5213 -6923 E0100; Adobe-Japan1; CID+5233 -6925 E0100; Adobe-Japan1; CID+5226 -6926 E0100; Adobe-Japan1; CID+5214 -6926 E0101; Hanyo-Denshi; JA5991 -6926 E0101; Moji_Joho; MJ014143 -6926 E0102; Hanyo-Denshi; FT2246 -6926 E0102; Moji_Joho; MJ014144 -6928 E0100; Adobe-Japan1; CID+5230 -692A E0100; Adobe-Japan1; CID+5231 -6930 E0100; Adobe-Japan1; CID+5248 -6930 E0101; Adobe-Japan1; CID+13552 -6930 E0102; Moji_Joho; MJ014149 -6930 E0103; Moji_Joho; MJ014150 -6931 E0100; Adobe-Japan1; CID+21779 -6931 E0101; Hanyo-Denshi; JB3629 -6931 E0102; Hanyo-Denshi; TK01044900 -6932 E0100; Hanyo-Denshi; IP6932 -6932 E0101; Hanyo-Denshi; KS170280 -6933 E0100; Adobe-Japan1; CID+19457 -6934 E0100; Adobe-Japan1; CID+3238 -6935 E0100; Adobe-Japan1; CID+14645 -6936 E0100; Adobe-Japan1; CID+5221 -6938 E0100; Adobe-Japan1; CID+19458 -6939 E0100; Adobe-Japan1; CID+5244 -6939 E0101; Hanyo-Denshi; JA6027 -6939 E0101; Moji_Joho; MJ014160 -6939 E0102; Hanyo-Denshi; KS172060 -6939 E0102; Moji_Joho; MJ014161 -6939 E0103; Hanyo-Denshi; TK01044930 -693B E0100; Adobe-Japan1; CID+14646 -693D E0100; Adobe-Japan1; CID+5246 -693D E0101; Adobe-Japan1; CID+20147 -693D E0102; Hanyo-Denshi; JA6029 -693D E0102; Moji_Joho; MJ014165 -693D E0103; Hanyo-Denshi; FT2249S -693D E0103; Moji_Joho; MJ014166 -693D E0104; Moji_Joho; MJ014167 -693F E0100; Adobe-Japan1; CID+3060 -6942 E0100; Adobe-Japan1; CID+16906 -6945 E0100; Adobe-Japan1; CID+21780 -6946 E0100; Adobe-Japan1; CID+17829 -6946 E0101; Hanyo-Denshi; JD1513 -6946 E0101; Moji_Joho; MJ014177 -6946 E0102; Hanyo-Denshi; IP6946 -6946 E0102; Moji_Joho; MJ014176 -6949 E0100; Adobe-Japan1; CID+16904 -6949 E0101; Hanyo-Denshi; JB3636 -6949 E0101; Moji_Joho; MJ014180 -6949 E0102; Hanyo-Denshi; KS170660 -6949 E0102; Moji_Joho; MJ014181 -694A E0100; Adobe-Japan1; CID+3894 -694E E0100; Adobe-Japan1; CID+21781 -6953 E0100; Adobe-Japan1; CID+3560 -6954 E0100; Adobe-Japan1; CID+5241 -6954 E0101; Hanyo-Denshi; JA6024 -6954 E0101; Moji_Joho; MJ014193 -6954 E0102; Hanyo-Denshi; KS170860 -6954 E0102; Moji_Joho; MJ014192 -6954 E0103; Hanyo-Denshi; FT2247 -6954 E0103; Moji_Joho; MJ014194 -6954 E0104; Hanyo-Denshi; KS171970S -6954 E0104; Moji_Joho; MJ057766 -6955 E0100; Adobe-Japan1; CID+2858 -6956 E0100; Hanyo-Denshi; IP6956 -6956 E0100; Moji_Joho; MJ014196 -6956 E0101; Hanyo-Denshi; JTB357 -6956 E0101; Moji_Joho; MJ014197 -6957 E0100; Adobe-Japan1; CID+14647 -6957 E0101; Moji_Joho; MJ014198 -6957 E0102; Moji_Joho; MJ014199 -6959 E0100; Adobe-Japan1; CID+5247 -695A E0100; Adobe-Japan1; CID+2753 -695B E0100; Adobe-Japan1; CID+19459 -695B E0101; Hanyo-Denshi; JB3639 -695B E0101; Moji_Joho; MJ014203 -695B E0102; Hanyo-Denshi; KS170990 -695B E0102; Moji_Joho; MJ014204 -695C E0100; Adobe-Japan1; CID+5238 -695D E0100; Adobe-Japan1; CID+5251 -695E E0100; Adobe-Japan1; CID+5250 -695E E0101; Adobe-Japan1; CID+20148 -695E E0102; Hanyo-Denshi; JA6033 -695E E0102; Moji_Joho; MJ014208 -695E E0103; Hanyo-Denshi; JTB356 -695E E0103; Moji_Joho; MJ014207 -6960 E0100; Adobe-Japan1; CID+3271 -6961 E0100; Adobe-Japan1; CID+5249 -6961 E0101; Hanyo-Denshi; JA6032 -6961 E0102; Hanyo-Denshi; TK01044910 -6962 E0100; Adobe-Japan1; CID+3266 -6962 E0101; Adobe-Japan1; CID+7768 -6962 E0102; Hanyo-Denshi; JA3874 -6962 E0102; Moji_Joho; MJ014213 -6962 E0103; Hanyo-Denshi; HG1666 -6962 E0103; Moji_Joho; MJ014214 -6962 E0104; Hanyo-Denshi; TK01045040 -6962 E0105; Moji_Joho; MJ014215 -6963 E0100; Adobe-Japan1; CID+14648 -6964 E0100; Adobe-Japan1; CID+16907 -6965 E0100; Adobe-Japan1; CID+19460 -6966 E0100; Adobe-Japan1; CID+21782 -6968 E0100; Adobe-Japan1; CID+8498 -6969 E0100; Adobe-Japan1; CID+17830 -696A E0100; Adobe-Japan1; CID+5253 -696B E0100; Adobe-Japan1; CID+5240 -696B E0101; Adobe-Japan1; CID+13551 -696B E0102; Moji_Joho; MJ014224 -696B E0103; Moji_Joho; MJ014225 -696C E0100; Adobe-Japan1; CID+17831 -696D E0100; Adobe-Japan1; CID+1728 -696D E0101; Hanyo-Denshi; JA2240 -696D E0102; Hanyo-Denshi; KS172010 -696E E0100; Adobe-Japan1; CID+5243 -696E E0101; Hanyo-Denshi; JA6026 -696E E0101; Moji_Joho; MJ014229 -696E E0102; Hanyo-Denshi; FT2248 -696E E0102; Moji_Joho; MJ014228 -696F E0100; Adobe-Japan1; CID+2407 -696F E0101; Adobe-Japan1; CID+13460 -696F E0102; Hanyo-Denshi; JA2961 -696F E0103; Hanyo-Denshi; TK01044920 -696F E0104; Moji_Joho; MJ014230 -696F E0105; Moji_Joho; MJ014231 -6970 E0100; Adobe-Japan1; CID+21783 -6971 E0100; Adobe-Japan1; CID+21784 -6972 E0100; Adobe-Japan1; CID+14649 -6973 E0100; Adobe-Japan1; CID+3350 -6974 E0100; Adobe-Japan1; CID+5245 -6975 E0100; Adobe-Japan1; CID+1731 -6977 E0100; Adobe-Japan1; CID+5237 -6978 E0100; Adobe-Japan1; CID+5239 -6979 E0100; Adobe-Japan1; CID+5236 -697A E0100; Adobe-Japan1; CID+17832 -697B E0100; Adobe-Japan1; CID+21785 -697C E0100; Adobe-Japan1; CID+4054 -697D E0100; Adobe-Japan1; CID+1464 -697E E0100; Adobe-Japan1; CID+5242 -697F E0100; Adobe-Japan1; CID+14650 -6980 E0100; Adobe-Japan1; CID+14651 -6981 E0100; Adobe-Japan1; CID+5252 -6982 E0100; Adobe-Japan1; CID+1427 -6982 E0101; Adobe-Japan1; CID+13403 -6982 E0102; Adobe-Japan1; CID+13423 -6982 E0103; Adobe-Japan1; CID+13680 -6982 E0104; Moji_Joho; MJ014250 -6982 E0105; Moji_Joho; MJ014251 -6986 E0100; Adobe-Japan1; CID+14144 -6986 E0101; Hanyo-Denshi; FT2250 -6986 E0102; Hanyo-Denshi; TK01045000 -698A E0100; Adobe-Japan1; CID+2135 -698A E0101; Adobe-Japan1; CID+7686 -698A E0102; Hanyo-Denshi; JA2671 -698A E0102; Moji_Joho; MJ014255 -698A E0103; Hanyo-Denshi; FT1808 -698A E0103; Moji_Joho; MJ014256 -698D E0100; Adobe-Japan1; CID+21786 -698E E0100; Adobe-Japan1; CID+1279 -698F E0100; Hanyo-Denshi; IP698F -698F E0101; Hanyo-Denshi; TK01045470 -6991 E0100; Adobe-Japan1; CID+5269 -6991 E0101; Hanyo-Denshi; JA6052 -6991 E0101; Moji_Joho; MJ014262 -6991 E0102; Hanyo-Denshi; FT2253 -6991 E0102; Moji_Joho; MJ014263 -6991 E0103; Hanyo-Denshi; TK01045350 -6992 E0100; Adobe-Japan1; CID+17833 -6992 E0101; Hanyo-Denshi; JB3655 -6992 E0101; Moji_Joho; MJ014264 -6992 E0102; Hanyo-Denshi; JTB36B -6992 E0102; Moji_Joho; MJ014265 -6994 E0100; Adobe-Japan1; CID+4055 -6994 E0101; Adobe-Japan1; CID+7812 -6994 E0102; Hanyo-Denshi; JA4717 -6994 E0102; Moji_Joho; MJ014267 -6994 E0103; Hanyo-Denshi; FT1940 -6994 E0103; Moji_Joho; MJ014268 -6994 E0104; Hanyo-Denshi; TK01044740 -6995 E0100; Adobe-Japan1; CID+5272 -6996 E0100; Adobe-Japan1; CID+17835 -6998 E0100; Adobe-Japan1; CID+8500 -6998 E0101; Hanyo-Denshi; JB3657 -6998 E0101; Moji_Joho; MJ014273 -6998 E0102; Hanyo-Denshi; IB2120 -6998 E0102; Moji_Joho; MJ014274 -699B E0100; Adobe-Japan1; CID+2560 -699C E0100; Adobe-Japan1; CID+5271 -699C E0101; Hanyo-Denshi; JA6054 -699C E0101; Moji_Joho; MJ014277 -699C E0102; Hanyo-Denshi; KS173690 -699C E0102; Moji_Joho; MJ014278 -69A0 E0100; Adobe-Japan1; CID+5270 -69A1 E0100; Adobe-Japan1; CID+21787 -69A3 E0100; Hanyo-Denshi; IP69A3 -69A3 E0100; Moji_Joho; MJ014284 -69A3 E0101; Hanyo-Denshi; KS173400 -69A3 E0101; Moji_Joho; MJ014285 -69A3 E0102; Hanyo-Denshi; TK01044890 -69A5 E0100; Adobe-Japan1; CID+16908 -69A6 E0100; Adobe-Japan1; CID+14652 -69A6 E0101; Hanyo-Denshi; JB3660 -69A6 E0102; Hanyo-Denshi; TK01005980 -69A7 E0100; Adobe-Japan1; CID+5267 -69A7 E0101; Adobe-Japan1; CID+13553 -69A7 E0102; Moji_Joho; MJ014290 -69A7 E0103; Moji_Joho; MJ014291 -69A8 E0100; Adobe-Japan1; CID+19461 -69AB E0100; Adobe-Japan1; CID+19462 -69AD E0100; Adobe-Japan1; CID+14653 -69AE E0100; Adobe-Japan1; CID+5255 -69AF E0100; Adobe-Japan1; CID+19463 -69B0 E0100; Adobe-Japan1; CID+17836 -69B1 E0100; Adobe-Japan1; CID+5284 -69B2 E0100; Adobe-Japan1; CID+5254 -69B4 E0100; Adobe-Japan1; CID+5273 -69B6 E0100; Hanyo-Denshi; IP69B6 -69B6 E0101; Hanyo-Denshi; TK01045800 -69B7 E0100; Adobe-Japan1; CID+14654 -69B8 E0100; Adobe-Japan1; CID+21788 -69BA E0100; Adobe-Japan1; CID+17837 -69BA E0101; Hanyo-Denshi; JB3667 -69BA E0101; Moji_Joho; MJ014311 -69BA E0102; Hanyo-Denshi; JTB36A -69BA E0102; Moji_Joho; MJ014312 -69BA E0103; Hanyo-Denshi; TK01075310 -69BA E0104; Moji_Joho; MJ014313 -69BB E0100; Adobe-Japan1; CID+5265 -69BB E0101; Adobe-Japan1; CID+14147 -69BB E0102; Hanyo-Denshi; JA6048 -69BB E0102; Moji_Joho; MJ014316 -69BB E0103; Hanyo-Denshi; KS173620 -69BB E0103; Moji_Joho; MJ014317 -69BB E0104; Hanyo-Denshi; FT2252 -69BB E0104; Moji_Joho; MJ014318 -69BC E0100; Adobe-Japan1; CID+17838 -69BD E0100; Hanyo-Denshi; IP69BD -69BD E0101; Hanyo-Denshi; TK01045810 -69BE E0100; Adobe-Japan1; CID+5260 -69BF E0100; Adobe-Japan1; CID+5257 -69C0 E0100; Adobe-Japan1; CID+17839 -69C1 E0100; Adobe-Japan1; CID+5258 -69C1 E0101; Adobe-Japan1; CID+13722 -69C1 E0102; Hanyo-Denshi; JA6041 -69C1 E0102; Moji_Joho; MJ014325 -69C1 E0103; Hanyo-Denshi; JTB381 -69C1 E0103; Moji_Joho; MJ014326 -69C3 E0100; Adobe-Japan1; CID+5266 -69C4 E0100; Hanyo-Denshi; IP69C4 -69C4 E0101; Hanyo-Denshi; TK01045820 -69C5 E0100; Adobe-Japan1; CID+21789 -69C7 E0100; Adobe-Japan1; CID+7475 -69C7 E0101; Hanyo-Denshi; JA8402 -69C7 E0101; Moji_Joho; MJ014333 -69C7 E0102; Hanyo-Denshi; JTB366 -69C7 E0102; Moji_Joho; MJ014334 -69C7 E0103; Moji_Joho; MJ014357 -69C8 E0100; Adobe-Japan1; CID+21790 -69CA E0100; Adobe-Japan1; CID+5263 -69CB E0100; Adobe-Japan1; CID+1999 -69CB E0101; Adobe-Japan1; CID+13767 -69CB E0102; Hanyo-Denshi; JA2529 -69CB E0102; Moji_Joho; MJ014339 -69CB E0103; Hanyo-Denshi; JTB35D -69CB E0103; Moji_Joho; MJ014338 -69CC E0100; Adobe-Japan1; CID+3044 -69CC E0101; Adobe-Japan1; CID+7744 -69CC E0102; Hanyo-Denshi; JA3640 -69CC E0102; Moji_Joho; MJ014340 -69CC E0103; Hanyo-Denshi; FT1863 -69CC E0103; Moji_Joho; MJ014341 -69CD E0100; Adobe-Japan1; CID+2790 -69CE E0100; Adobe-Japan1; CID+5261 -69CF E0100; Adobe-Japan1; CID+16909 -69CF E0101; Hanyo-Denshi; JC8593 -69CF E0101; Moji_Joho; MJ014346 -69CF E0102; Hanyo-Denshi; IB0235 -69CF E0102; Moji_Joho; MJ014345 -69CF E0103; Hanyo-Denshi; IP69CF -69CF E0103; Moji_Joho; MJ014344 -69D0 E0100; Adobe-Japan1; CID+5256 -69D1 E0100; Adobe-Japan1; CID+17840 -69D3 E0100; Adobe-Japan1; CID+5259 -69D6 E0100; Adobe-Japan1; CID+14655 -69D7 E0100; Adobe-Japan1; CID+14656 -69D8 E0100; Adobe-Japan1; CID+3895 -69D9 E0100; Adobe-Japan1; CID+3736 -69D9 E0101; Adobe-Japan1; CID+14045 -69D9 E0102; Hanyo-Denshi; JA4374 -69D9 E0103; Hanyo-Denshi; IB2138 -69D9 E0104; Hanyo-Denshi; TK01045990 -69DD E0100; Adobe-Japan1; CID+5264 -69DE E0100; Adobe-Japan1; CID+5274 -69E2 E0100; Adobe-Japan1; CID+8501 -69E2 E0101; Hanyo-Denshi; JB3674 -69E2 E0101; Moji_Joho; MJ014361 -69E2 E0102; Hanyo-Denshi; JTB36C -69E2 E0102; Moji_Joho; MJ059729 -69E2 E0103; Hanyo-Denshi; JTB388 -69E2 E0103; Moji_Joho; MJ014362 -69E3 E0100; Adobe-Japan1; CID+17844 -69E4 E0100; Hanyo-Denshi; IB0717 -69E4 E0100; Moji_Joho; MJ014364 -69E4 E0101; Hanyo-Denshi; IP69E4 -69E4 E0101; Moji_Joho; MJ014365 -69E5 E0100; Adobe-Japan1; CID+19464 -69E7 E0100; Adobe-Japan1; CID+5282 -69E8 E0100; Adobe-Japan1; CID+5275 -69E9 E0100; Adobe-Japan1; CID+16912 -69E9 E0101; Hanyo-Denshi; JC8603 -69E9 E0101; Moji_Joho; MJ014372 -69E9 E0102; Hanyo-Denshi; KS173870 -69E9 E0102; Moji_Joho; MJ014370 -69E9 E0103; Hanyo-Denshi; IB2132S -69E9 E0103; Moji_Joho; MJ014371 -69EA E0100; Adobe-Japan1; CID+13329 -69EA E0101; Adobe-Japan1; CID+13679 -69EA E0102; Hanyo-Denshi; JC8604 -69EA E0102; Moji_Joho; MJ014375 -69EA E0103; Hanyo-Denshi; JTB384 -69EA E0103; Moji_Joho; MJ014374 -69EA E0104; Hanyo-Denshi; JTB385 -69EA E0104; Moji_Joho; MJ014373 -69EB E0100; Adobe-Japan1; CID+5288 -69EB E0101; Hanyo-Denshi; JA6071 -69EB E0101; Moji_Joho; MJ014376 -69EB E0102; Hanyo-Denshi; JTB353 -69EB E0102; Moji_Joho; MJ014377 -69EB E0103; Hanyo-Denshi; TK01046040 -69ED E0100; Adobe-Japan1; CID+5286 -69EE E0100; Adobe-Japan1; CID+17845 -69EF E0100; Adobe-Japan1; CID+17846 -69F1 E0100; Adobe-Japan1; CID+19465 -69F1 E0101; Hanyo-Denshi; JB3678 -69F1 E0101; Moji_Joho; MJ014384 -69F1 E0102; Hanyo-Denshi; KS175330 -69F1 E0102; Moji_Joho; MJ014385 -69F2 E0100; Adobe-Japan1; CID+5281 -69F3 E0100; Adobe-Japan1; CID+17847 -69F4 E0100; Adobe-Japan1; CID+17849 -69F5 E0100; Adobe-Japan1; CID+16913 -69F6 E0100; Adobe-Japan1; CID+14143 -69F9 E0100; Adobe-Japan1; CID+5280 -69FB E0100; Adobe-Japan1; CID+3052 -69FD E0100; Adobe-Japan1; CID+2791 -69FE E0100; Adobe-Japan1; CID+17850 -69FE E0101; Adobe-Japan1; CID+21791 -69FE E0102; Hanyo-Denshi; JB3681 -69FE E0102; Moji_Joho; MJ014398 -69FE E0103; Hanyo-Denshi; JD1542 -69FE E0103; Moji_Joho; MJ014399 -69FF E0100; Adobe-Japan1; CID+5278 -69FF E0101; Hanyo-Denshi; JA6061 -69FF E0101; Moji_Joho; MJ014400 -69FF E0102; Hanyo-Denshi; FT2255 -69FF E0102; Moji_Joho; MJ014401 -69FF E0103; Hanyo-Denshi; JTB389 -69FF E0103; Moji_Joho; MJ014402 -69FF E0104; Hanyo-Denshi; TK01045430 -69FF E0105; Hanyo-Denshi; TK01045490 -6A00 E0100; Adobe-Japan1; CID+21792 -6A01 E0100; Adobe-Japan1; CID+14657 -6A01 E0101; Hanyo-Denshi; JB3683 -6A01 E0102; Hanyo-Denshi; TK01045830 -6A02 E0100; Adobe-Japan1; CID+5276 -6A02 E0101; Hanyo-Denshi; JA6059 -6A02 E0102; Hanyo-Denshi; TK01045600 -6A03 E0100; Adobe-Japan1; CID+21793 -6A05 E0100; Adobe-Japan1; CID+5283 -6A0A E0100; Adobe-Japan1; CID+5289 -6A0B E0100; Adobe-Japan1; CID+3465 -6A0B E0101; Adobe-Japan1; CID+7780 -6A0B E0102; Hanyo-Denshi; JA4085 -6A0B E0102; Moji_Joho; MJ014416 -6A0B E0103; Hanyo-Denshi; FT1907 -6A0B E0103; Moji_Joho; MJ014417 -6A0C E0100; Adobe-Japan1; CID+5295 -6A0F E0100; Adobe-Japan1; CID+14658 -6A11 E0100; Adobe-Japan1; CID+17851 -6A12 E0100; Adobe-Japan1; CID+5290 -6A13 E0100; Adobe-Japan1; CID+5293 -6A13 E0101; Hanyo-Denshi; JA6076 -6A13 E0101; Moji_Joho; MJ014425 -6A13 E0102; Hanyo-Denshi; KS175440 -6A13 E0102; Moji_Joho; MJ057816 -6A13 E0103; Hanyo-Denshi; TK01045290 -6A13 E0104; Hanyo-Denshi; TK01045330 -6A13 E0105; Hanyo-Denshi; TK01046130 -6A14 E0100; Adobe-Japan1; CID+5287 -6A14 E0101; Hanyo-Denshi; JA6070 -6A14 E0101; Moji_Joho; MJ014426 -6A14 E0102; Hanyo-Denshi; FT2257 -6A14 E0102; Moji_Joho; MJ014427 -6A15 E0100; Adobe-Japan1; CID+14659 -6A17 E0100; Adobe-Japan1; CID+2994 -6A17 E0101; Hanyo-Denshi; JA3584 -6A17 E0102; Hanyo-Denshi; TK01046020 -6A19 E0100; Adobe-Japan1; CID+3498 -6A1A E0100; Adobe-Japan1; CID+17852 -6A1B E0100; Adobe-Japan1; CID+5277 -6A1B E0101; Hanyo-Denshi; JA6060 -6A1B E0101; Moji_Joho; MJ014434 -6A1B E0102; Hanyo-Denshi; FT2254 -6A1B E0102; Moji_Joho; MJ014435 -6A1D E0100; Adobe-Japan1; CID+17853 -6A1E E0100; Adobe-Japan1; CID+5285 -6A1E E0101; Hanyo-Denshi; JA6068 -6A1E E0101; Moji_Joho; MJ014438 -6A1E E0102; Hanyo-Denshi; KS175500 -6A1E E0102; Moji_Joho; MJ014439 -6A1F E0100; Adobe-Japan1; CID+2472 -6A1F E0101; Hanyo-Denshi; JA3032 -6A1F E0101; Moji_Joho; MJ014440 -6A1F E0102; Hanyo-Denshi; KS175400 -6A1F E0102; Moji_Joho; MJ014441 -6A20 E0100; Adobe-Japan1; CID+21794 -6A20 E0101; Hanyo-Denshi; JB3690 -6A20 E0102; Hanyo-Denshi; TK01046470 -6A21 E0100; Adobe-Japan1; CID+3803 -6A21 E0101; Hanyo-Denshi; JA4447 -6A21 E0101; Moji_Joho; MJ014443 -6A21 E0102; Hanyo-Denshi; KS174770 -6A21 E0102; Moji_Joho; MJ014444 -6A22 E0100; Adobe-Japan1; CID+5305 -6A23 E0100; Adobe-Japan1; CID+5292 -6A23 E0101; Hanyo-Denshi; JA6075 -6A23 E0101; Moji_Joho; MJ014446 -6A23 E0102; Hanyo-Denshi; JTB392 -6A23 E0102; Moji_Joho; MJ014447 -6A24 E0100; Adobe-Japan1; CID+21795 -6A27 E0100; Hanyo-Denshi; IP6A27 -6A27 E0101; Hanyo-Denshi; JTB371 -6A28 E0100; Adobe-Japan1; CID+14660 -6A29 E0100; Adobe-Japan1; CID+1878 -6A2A E0100; Adobe-Japan1; CID+1315 -6A2A E0101; Hanyo-Denshi; JA1803 -6A2A E0101; Moji_Joho; MJ014455 -6A2A E0102; Hanyo-Denshi; JTB38A -6A2A E0102; Moji_Joho; MJ014456 -6A2A E0103; Hanyo-Denshi; TK01045930 -6A2A E0104; Hanyo-Denshi; TK01046010 -6A2B E0100; Adobe-Japan1; CID+1469 -6A2E E0100; Adobe-Japan1; CID+5268 -6A2E E0101; Hanyo-Denshi; JA6051 -6A2E E0102; Hanyo-Denshi; JTB383 -6A30 E0100; Adobe-Japan1; CID+8502 -6A32 E0100; Adobe-Japan1; CID+17855 -6A33 E0100; Adobe-Japan1; CID+17856 -6A33 E0101; Hanyo-Denshi; JD1548 -6A33 E0102; Hanyo-Denshi; TK01046680 -6A34 E0100; Adobe-Japan1; CID+14661 -6A34 E0101; Hanyo-Denshi; JB3701 -6A34 E0101; Moji_Joho; MJ014466 -6A34 E0102; Hanyo-Denshi; KS177170 -6A34 E0102; Moji_Joho; MJ014467 -6A35 E0100; Adobe-Japan1; CID+2473 -6A36 E0100; Adobe-Japan1; CID+5297 -6A36 E0101; Hanyo-Denshi; JA6080 -6A36 E0101; Moji_Joho; MJ014471 -6A36 E0102; Hanyo-Denshi; KS175570 -6A36 E0102; Moji_Joho; MJ014470 -6A37 E0100; Adobe-Japan1; CID+21796 -6A38 E0100; Adobe-Japan1; CID+5304 -6A39 E0100; Adobe-Japan1; CID+2341 -6A39 E0101; Moji_Joho; MJ014474 -6A39 E0102; Moji_Joho; MJ014475 -6A3A E0100; Adobe-Japan1; CID+1488 -6A3A E0101; Hanyo-Denshi; JA1982 -6A3A E0101; Moji_Joho; MJ014476 -6A3A E0102; Hanyo-Denshi; KS175630 -6A3A E0102; Moji_Joho; MJ014477 -6A3B E0100; Adobe-Japan1; CID+16915 -6A3D E0100; Adobe-Japan1; CID+2924 -6A3D E0101; Adobe-Japan1; CID+7738 -6A3D E0102; Hanyo-Denshi; JA3514 -6A3D E0102; Moji_Joho; MJ014481 -6A3D E0103; Hanyo-Denshi; HG1647 -6A3D E0103; Moji_Joho; MJ014480 -6A3E E0100; Adobe-Japan1; CID+14662 -6A3F E0100; Adobe-Japan1; CID+17857 -6A44 E0100; Adobe-Japan1; CID+5294 -6A44 E0101; Adobe-Japan1; CID+13554 -6A44 E0102; Moji_Joho; MJ014488 -6A44 E0103; Moji_Joho; MJ014489 -6A45 E0100; Adobe-Japan1; CID+14663 -6A46 E0100; Adobe-Japan1; CID+8504 -6A47 E0100; Adobe-Japan1; CID+5299 -6A48 E0100; Adobe-Japan1; CID+5303 -6A49 E0100; Adobe-Japan1; CID+17858 -6A49 E0101; Hanyo-Denshi; JB3708 -6A49 E0101; Moji_Joho; MJ014494 -6A49 E0102; Hanyo-Denshi; IB2149 -6A49 E0102; Moji_Joho; MJ014495 -6A4A E0100; Adobe-Japan1; CID+19466 -6A4B E0100; Adobe-Japan1; CID+1710 -6A4E E0100; Adobe-Japan1; CID+17860 -6A50 E0100; Adobe-Japan1; CID+14664 -6A51 E0100; Adobe-Japan1; CID+14665 -6A52 E0100; Adobe-Japan1; CID+17861 -6A54 E0100; Adobe-Japan1; CID+15412 -6A55 E0100; Adobe-Japan1; CID+19467 -6A55 E0101; Adobe-Japan1; CID+21797 -6A56 E0100; Adobe-Japan1; CID+14666 -6A58 E0100; Adobe-Japan1; CID+1638 -6A59 E0100; Adobe-Japan1; CID+5301 -6A59 E0101; Moji_Joho; MJ014511 -6A59 E0102; Moji_Joho; MJ014512 -6A5A E0100; Hanyo-Denshi; IP6A5A -6A5A E0101; Hanyo-Denshi; TK01046460 -6A5A E0102; Hanyo-Denshi; TK01046930 -6A5B E0100; Adobe-Japan1; CID+14667 -6A5D E0100; Hanyo-Denshi; IB2152 -6A5D E0100; Moji_Joho; MJ014517 -6A5D E0101; Hanyo-Denshi; IP6A5D -6A5D E0101; Moji_Joho; MJ014516 -6A5E E0100; Hanyo-Denshi; IP6A5E -6A5E E0101; Hanyo-Denshi; TK01045260 -6A5E E0102; Hanyo-Denshi; TK01046500 -6A5F E0100; Adobe-Japan1; CID+1595 -6A5F E0101; Adobe-Japan1; CID+13703 -6A5F E0102; Hanyo-Denshi; JA2101 -6A5F E0102; Moji_Joho; MJ014520 -6A5F E0103; Hanyo-Denshi; JTB39D -6A5F E0103; Moji_Joho; MJ014521 -6A61 E0100; Adobe-Japan1; CID+3235 -6A61 E0101; Hanyo-Denshi; JA3843 -6A61 E0101; Moji_Joho; MJ014523 -6A61 E0102; Hanyo-Denshi; FT2047 -6A61 E0102; Moji_Joho; MJ014524 -6A62 E0100; Adobe-Japan1; CID+5300 -6A64 E0100; Adobe-Japan1; CID+17862 -6A66 E0100; Adobe-Japan1; CID+5302 -6A66 E0101; Hanyo-Denshi; JA6085 -6A66 E0101; Moji_Joho; MJ014529 -6A66 E0102; Hanyo-Denshi; KS177160 -6A66 E0102; Moji_Joho; MJ014530 -6A67 E0100; Adobe-Japan1; CID+19468 -6A67 E0101; Hanyo-Denshi; JB3718 -6A67 E0101; Moji_Joho; MJ014531 -6A67 E0102; Hanyo-Denshi; JTB38F -6A67 E0102; Moji_Joho; MJ014532 -6A67 E0103; Hanyo-Denshi; TK01045940 -6A6A E0100; Adobe-Japan1; CID+21798 -6A6B E0100; Adobe-Japan1; CID+8503 -6A71 E0100; Adobe-Japan1; CID+19469 -6A72 E0100; Adobe-Japan1; CID+5296 -6A73 E0100; Adobe-Japan1; CID+8505 -6A73 E0101; Adobe-Japan1; CID+14292 -6A73 E0102; Hanyo-Denshi; JB3721 -6A73 E0102; Moji_Joho; MJ014545 -6A73 E0103; Hanyo-Denshi; JTB39B -6A73 E0103; Moji_Joho; MJ014547 -6A73 E0104; Hanyo-Denshi; IB0103 -6A73 E0104; Moji_Joho; MJ014546 -6A78 E0100; Adobe-Japan1; CID+5298 -6A7A E0100; Adobe-Japan1; CID+17859 -6A7E E0100; Adobe-Japan1; CID+8506 -6A7F E0100; Adobe-Japan1; CID+1470 -6A7F E0101; Hanyo-Denshi; JA1964 -6A7F E0102; Hanyo-Denshi; TK01046660 -6A80 E0100; Adobe-Japan1; CID+2951 -6A80 E0101; Hanyo-Denshi; JA3541 -6A80 E0101; Moji_Joho; MJ014554 -6A80 E0102; Hanyo-Denshi; JTB3B9 -6A80 E0102; Moji_Joho; MJ014555 -6A80 E0103; Hanyo-Denshi; TK01046870 -6A81 E0100; Adobe-Japan1; CID+21799 -6A83 E0100; Adobe-Japan1; CID+14668 -6A84 E0100; Adobe-Japan1; CID+5309 -6A86 E0100; Adobe-Japan1; CID+21800 -6A87 E0100; Adobe-Japan1; CID+21801 -6A89 E0100; Adobe-Japan1; CID+14669 -6A89 E0101; Hanyo-Denshi; JB3727 -6A89 E0101; Moji_Joho; MJ014564 -6A89 E0102; Hanyo-Denshi; JTB3AE -6A89 E0102; Moji_Joho; MJ014565 -6A8B E0100; Adobe-Japan1; CID+17864 -6A8D E0100; Adobe-Japan1; CID+5307 -6A8D E0101; Hanyo-Denshi; JA6090 -6A8D E0101; Moji_Joho; MJ014569 -6A8D E0102; Hanyo-Denshi; KS178230 -6A8D E0102; Moji_Joho; MJ014570 -6A8E E0100; Adobe-Japan1; CID+1949 -6A8E E0101; Adobe-Japan1; CID+13438 -6A8E E0102; Hanyo-Denshi; JA2473 -6A8E E0102; Moji_Joho; MJ014571 -6A8E E0103; Hanyo-Denshi; KS178280 -6A8E E0103; Moji_Joho; MJ057842 -6A90 E0100; Adobe-Japan1; CID+5306 -6A90 E0101; Adobe-Japan1; CID+13555 -6A90 E0102; Hanyo-Denshi; JA6089 -6A90 E0102; Moji_Joho; MJ014573 -6A90 E0103; Hanyo-Denshi; FT1705 -6A90 E0103; Moji_Joho; MJ014574 -6A91 E0100; Adobe-Japan1; CID+14670 -6A94 E0100; Adobe-Japan1; CID+16917 -6A94 E0101; Hanyo-Denshi; JC8620 -6A94 E0102; Hanyo-Denshi; TK01046720 -6A94 E0103; Hanyo-Denshi; TK01046860 -6A96 E0100; Hanyo-Denshi; IB0720 -6A96 E0100; Moji_Joho; MJ014581 -6A96 E0101; Hanyo-Denshi; IP6A96 -6A96 E0101; Moji_Joho; MJ014582 -6A97 E0100; Adobe-Japan1; CID+5312 -6A9B E0100; Adobe-Japan1; CID+21802 -6A9B E0101; Hanyo-Denshi; JB3730 -6A9B E0101; Moji_Joho; MJ014588 -6A9B E0102; Hanyo-Denshi; IB0721 -6A9B E0102; Moji_Joho; MJ014587 -6A9C E0100; Adobe-Japan1; CID+5179 -6A9C E0101; Adobe-Japan1; CID+20150 -6A9C E0102; Hanyo-Denshi; JA5956 -6A9C E0102; Moji_Joho; MJ014590 -6A9C E0103; Hanyo-Denshi; JTB3AD -6A9C E0103; Moji_Joho; MJ014592 -6A9C E0104; Hanyo-Denshi; JTB398 -6A9C E0104; Moji_Joho; MJ014589 -6A9C E0105; Hanyo-Denshi; JTB399 -6A9C E0105; Moji_Joho; MJ014591 -6A9D E0100; Adobe-Japan1; CID+14671 -6A9E E0100; Adobe-Japan1; CID+14672 -6A9E E0101; Hanyo-Denshi; JB3732 -6A9E E0102; Hanyo-Denshi; TK01046740 -6A9F E0100; Adobe-Japan1; CID+14673 -6AA0 E0100; Adobe-Japan1; CID+5308 -6AA0 E0101; Hanyo-Denshi; JA6091 -6AA0 E0101; Moji_Joho; MJ014596 -6AA0 E0102; Hanyo-Denshi; KS177770S -6AA0 E0102; Moji_Joho; MJ014597 -6AA1 E0100; Adobe-Japan1; CID+17866 -6AA2 E0100; Adobe-Japan1; CID+5310 -6AA2 E0101; Hanyo-Denshi; JA6093 -6AA2 E0102; Hanyo-Denshi; TK01046200 -6AA3 E0100; Adobe-Japan1; CID+5311 -6AA5 E0100; Adobe-Japan1; CID+16918 -6AA8 E0100; Hanyo-Denshi; IP6AA8 -6AA8 E0100; Moji_Joho; MJ014605 -6AA8 E0101; Hanyo-Denshi; KS177210 -6AA8 E0101; Moji_Joho; MJ057832 -6AAA E0100; Adobe-Japan1; CID+5323 -6AAB E0100; Adobe-Japan1; CID+17868 -6AAC E0100; Adobe-Japan1; CID+5319 -6AAC E0101; Hanyo-Denshi; JA6108 -6AAC E0101; Moji_Joho; MJ014608 -6AAC E0102; Hanyo-Denshi; KS178310 -6AAC E0102; Moji_Joho; MJ014609 -6AAC E0103; Hanyo-Denshi; FT2261 -6AAC E0103; Moji_Joho; MJ014610 -6AAC E0104; Moji_Joho; MJ014611 -6AAE E0100; Adobe-Japan1; CID+5200 -6AAF E0100; Adobe-Japan1; CID+19470 -6AB0 E0100; Adobe-Japan1; CID+21803 -6AB1 E0100; Adobe-Japan1; CID+21804 -6AB3 E0100; Adobe-Japan1; CID+5318 -6AB3 E0101; Hanyo-Denshi; JA6107 -6AB3 E0101; Moji_Joho; MJ014618 -6AB3 E0102; Hanyo-Denshi; FT2260S -6AB3 E0102; Moji_Joho; MJ014620 -6AB3 E0103; Moji_Joho; MJ014619 -6AB4 E0100; Adobe-Japan1; CID+21805 -6AB4 E0101; Hanyo-Denshi; JB3739 -6AB4 E0101; Moji_Joho; MJ014621 -6AB4 E0102; Hanyo-Denshi; KS178540 -6AB4 E0102; Moji_Joho; MJ014622 -6AB8 E0100; Adobe-Japan1; CID+5317 -6AB8 E0101; Hanyo-Denshi; JA6106 -6AB8 E0101; Moji_Joho; MJ014626 -6AB8 E0102; Hanyo-Denshi; FT2259 -6AB8 E0102; Moji_Joho; MJ014627 -6ABB E0100; Adobe-Japan1; CID+5314 -6ABC E0100; Hanyo-Denshi; IP6ABC -6ABC E0101; Hanyo-Denshi; TK01046840 -6ABD E0100; Adobe-Japan1; CID+17869 -6ABE E0100; Adobe-Japan1; CID+21806 -6ABF E0100; Adobe-Japan1; CID+21807 -6AC1 E0100; Adobe-Japan1; CID+5291 -6AC2 E0100; Adobe-Japan1; CID+5316 -6AC2 E0101; Hanyo-Denshi; JA6105 -6AC2 E0101; Moji_Joho; MJ014638 -6AC2 E0102; Hanyo-Denshi; FT2258 -6AC2 E0102; Moji_Joho; MJ014639 -6AC3 E0100; Adobe-Japan1; CID+5315 -6AC6 E0100; Adobe-Japan1; CID+17870 -6AC8 E0100; Adobe-Japan1; CID+19471 -6AC9 E0100; Adobe-Japan1; CID+19472 -6ACC E0100; Adobe-Japan1; CID+21808 -6ACE E0100; Hanyo-Denshi; IP6ACE -6ACE E0100; Moji_Joho; MJ014651 -6ACE E0101; Hanyo-Denshi; JTB3B7 -6ACE E0101; Moji_Joho; MJ014652 -6AD0 E0100; Adobe-Japan1; CID+17872 -6AD1 E0100; Adobe-Japan1; CID+5321 -6AD3 E0100; Adobe-Japan1; CID+4044 -6AD4 E0100; Adobe-Japan1; CID+17871 -6AD4 E0101; Hanyo-Denshi; JB3748 -6AD4 E0101; Moji_Joho; MJ014658 -6AD4 E0102; Hanyo-Denshi; KS179330 -6AD4 E0102; Moji_Joho; MJ014659 -6AD4 E0103; Hanyo-Denshi; JTB3BA -6AD4 E0103; Moji_Joho; MJ014660 -6AD4 E0104; Hanyo-Denshi; TK01046890 -6AD4 E0105; Hanyo-Denshi; TK01046920 -6AD5 E0100; Adobe-Japan1; CID+21809 -6AD6 E0100; Adobe-Japan1; CID+21810 -6AD6 E0101; Hanyo-Denshi; JB3750 -6AD6 E0102; Hanyo-Denshi; TK01047070 -6ADA E0100; Adobe-Japan1; CID+5324 -6ADB E0100; Adobe-Japan1; CID+7665 -6ADB E0101; Adobe-Japan1; CID+1779 -6ADB E0102; Adobe-Japan1; CID+13737 -6ADB E0103; Hanyo-Denshi; JA2291 -6ADB E0103; Moji_Joho; MJ014669 -6ADB E0104; Hanyo-Denshi; FT1781 -6ADB E0104; Moji_Joho; MJ014671 -6ADB E0105; Hanyo-Denshi; KS179480 -6ADB E0105; Moji_Joho; MJ014670 -6ADB E0106; Hanyo-Denshi; JTB3BB -6ADB E0106; Moji_Joho; MJ014672 -6ADC E0100; Adobe-Japan1; CID+14674 -6ADC E0101; Hanyo-Denshi; JB3751 -6ADC E0101; Moji_Joho; MJ014673 -6ADC E0102; Hanyo-Denshi; IB2168 -6ADC E0102; Moji_Joho; MJ014674 -6ADD E0100; Adobe-Japan1; CID+17873 -6ADD E0101; Hanyo-Denshi; JB3752 -6ADD E0101; Moji_Joho; MJ014675 -6ADD E0102; Hanyo-Denshi; JTB3C9 -6ADD E0102; Moji_Joho; MJ014676 -6ADE E0100; Adobe-Japan1; CID+5320 -6ADE E0101; Hanyo-Denshi; JA6109 -6ADE E0101; Moji_Joho; MJ014677 -6ADE E0102; Hanyo-Denshi; FT2262 -6ADE E0102; Moji_Joho; MJ014680 -6ADE E0103; Moji_Joho; MJ014678 -6ADE E0104; Moji_Joho; MJ014679 -6ADF E0100; Adobe-Japan1; CID+5322 -6AE2 E0100; Adobe-Japan1; CID+8507 -6AE4 E0100; Adobe-Japan1; CID+8508 -6AE4 E0101; Hanyo-Denshi; JB3753 -6AE4 E0101; Moji_Joho; MJ014686 -6AE4 E0102; Hanyo-Denshi; JTB3CB -6AE4 E0102; Moji_Joho; MJ014687 -6AE7 E0100; Adobe-Japan1; CID+14675 -6AE8 E0100; Adobe-Japan1; CID+3387 -6AEA E0100; Adobe-Japan1; CID+5325 -6AEC E0100; Adobe-Japan1; CID+14676 -6AF0 E0100; Adobe-Japan1; CID+21811 -6AF1 E0100; Adobe-Japan1; CID+17876 -6AF2 E0100; Adobe-Japan1; CID+17877 -6AF3 E0100; Adobe-Japan1; CID+17878 -6AF3 E0101; Moji_Joho; MJ014701 -6AF3 E0102; Moji_Joho; MJ014702 -6AF8 E0100; Adobe-Japan1; CID+20152 -6AFA E0100; Adobe-Japan1; CID+5329 -6AFB E0100; Adobe-Japan1; CID+5326 -6AFC E0100; Adobe-Japan1; CID+21812 -6AFD E0100; Adobe-Japan1; CID+17879 -6B02 E0100; Adobe-Japan1; CID+21813 -6B02 E0101; Hanyo-Denshi; JB3761 -6B02 E0101; Moji_Joho; MJ014713 -6B02 E0102; Hanyo-Denshi; KS180560 -6B02 E0102; Moji_Joho; MJ014714 -6B03 E0100; Adobe-Japan1; CID+19473 -6B04 E0100; Adobe-Japan1; CID+13392 -6B04 E0101; Adobe-Japan1; CID+3933 -6B04 E0102; Hanyo-Denshi; JA4583 -6B04 E0103; Hanyo-Denshi; JC8627 -6B05 E0100; Adobe-Japan1; CID+5327 -6B06 E0100; Adobe-Japan1; CID+21814 -6B07 E0100; Adobe-Japan1; CID+21815 -6B07 E0101; Moji_Joho; MJ014719 -6B07 E0102; Moji_Joho; MJ014720 -6B09 E0100; Adobe-Japan1; CID+21816 -6B0A E0100; Adobe-Japan1; CID+5279 -6B0A E0101; Hanyo-Denshi; JA6062 -6B0A E0101; Moji_Joho; MJ014723 -6B0A E0102; Hanyo-Denshi; KS180840 -6B0A E0102; Moji_Joho; MJ014724 -6B0A E0103; Hanyo-Denshi; JTB3CA -6B0A E0103; Moji_Joho; MJ059750 -6B0B E0100; Adobe-Japan1; CID+17881 -6B0F E0100; Adobe-Japan1; CID+17882 -6B10 E0100; Adobe-Japan1; CID+17883 -6B11 E0100; Adobe-Japan1; CID+17884 -6B12 E0100; Adobe-Japan1; CID+5330 -6B13 E0100; Hanyo-Denshi; IP6B13 -6B13 E0101; Hanyo-Denshi; TK01047230 -6B16 E0100; Adobe-Japan1; CID+5331 -6B17 E0100; Adobe-Japan1; CID+17886 -6B17 E0101; Hanyo-Denshi; JB3769 -6B17 E0101; Moji_Joho; MJ014734 -6B17 E0102; Hanyo-Denshi; KS181340 -6B17 E0102; Moji_Joho; MJ014735 -6B17 E0103; Hanyo-Denshi; TK01047240 -6B1B E0100; Adobe-Japan1; CID+16920 -6B1D E0100; Adobe-Japan1; CID+1239 -6B1D E0101; Adobe-Japan1; CID+7639 -6B1D E0102; Hanyo-Denshi; JA1721 -6B1D E0102; Moji_Joho; MJ014742 -6B1D E0103; Hanyo-Denshi; FT1757 -6B1D E0103; Moji_Joho; MJ014743 -6B1E E0100; Adobe-Japan1; CID+14677 -6B1F E0100; Adobe-Japan1; CID+5333 -6B1F E0101; Hanyo-Denshi; JA6122 -6B1F E0101; Moji_Joho; MJ014745 -6B1F E0102; Hanyo-Denshi; KS181580S -6B1F E0102; Moji_Joho; MJ014746 -6B20 E0100; Adobe-Japan1; CID+1853 -6B21 E0100; Adobe-Japan1; CID+2253 -6B21 E0101; Adobe-Japan1; CID+13799 -6B21 E0102; Adobe-Japan1; CID+13800 -6B21 E0103; Hanyo-Denshi; JA2801 -6B21 E0103; Moji_Joho; MJ014749 -6B21 E0104; Hanyo-Denshi; KS181650 -6B21 E0104; Moji_Joho; MJ014748 -6B23 E0100; Adobe-Japan1; CID+1741 -6B24 E0100; Adobe-Japan1; CID+14678 -6B24 E0101; Adobe-Japan1; CID+15394 -6B24 E0102; Hanyo-Denshi; JB3772 -6B24 E0102; Moji_Joho; MJ014751 -6B24 E0103; Hanyo-Denshi; KS181770S -6B24 E0103; Moji_Joho; MJ057876 -6B24 E0104; Hanyo-Denshi; TK01047250 -6B27 E0100; Adobe-Japan1; CID+1316 -6B28 E0100; Adobe-Japan1; CID+21817 -6B2B E0100; Adobe-Japan1; CID+21818 -6B2C E0100; Adobe-Japan1; CID+16921 -6B2C E0101; Hanyo-Denshi; JB3775 -6B2C E0101; Moji_Joho; MJ014760 -6B2C E0102; Hanyo-Denshi; KS182550 -6B2C E0102; Moji_Joho; MJ014761 -6B2E E0100; Moji_Joho; MJ014763 -6B2E E0101; Moji_Joho; MJ057877 -6B2F E0100; Adobe-Japan1; CID+17888 -6B32 E0100; Adobe-Japan1; CID+3913 -6B35 E0100; Adobe-Japan1; CID+14679 -6B36 E0100; Adobe-Japan1; CID+21819 -6B37 E0100; Adobe-Japan1; CID+5335 -6B38 E0100; Adobe-Japan1; CID+5334 -6B39 E0100; Adobe-Japan1; CID+5337 -6B3A E0100; Adobe-Japan1; CID+1623 -6B3B E0100; Adobe-Japan1; CID+19474 -6B3D E0100; Adobe-Japan1; CID+1742 -6B3E E0100; Adobe-Japan1; CID+1530 -6B3F E0100; Adobe-Japan1; CID+19475 -6B3F E0101; Hanyo-Denshi; JB3780 -6B3F E0101; Moji_Joho; MJ014780 -6B3F E0102; Hanyo-Denshi; JTB3D8 -6B3F E0102; Moji_Joho; MJ059754 -6B43 E0100; Adobe-Japan1; CID+5340 -6B46 E0100; Adobe-Japan1; CID+14680 -6B46 E0101; Hanyo-Denshi; JB3781 -6B46 E0101; Moji_Joho; MJ014787 -6B46 E0102; Hanyo-Denshi; KS183370 -6B46 E0102; Moji_Joho; MJ014788 -6B47 E0100; Adobe-Japan1; CID+5339 -6B47 E0101; Hanyo-Denshi; JA6128 -6B47 E0101; Moji_Joho; MJ014790 -6B47 E0102; Hanyo-Denshi; FT2266 -6B47 E0102; Moji_Joho; MJ014789 -6B49 E0100; Adobe-Japan1; CID+5341 -6B49 E0101; Hanyo-Denshi; JA6130 -6B49 E0101; Moji_Joho; MJ014792 -6B49 E0102; Hanyo-Denshi; FT2267 -6B49 E0102; Moji_Joho; MJ014793 -6B4A E0100; Adobe-Japan1; CID+17889 -6B4C E0100; Adobe-Japan1; CID+1358 -6B4D E0100; Adobe-Japan1; CID+21820 -6B4E E0100; Adobe-Japan1; CID+2933 -6B4E E0101; Adobe-Japan1; CID+13915 -6B4E E0102; Hanyo-Denshi; JA3523 -6B4E E0102; Moji_Joho; MJ014798 -6B4E E0103; Hanyo-Denshi; FT2916 -6B4E E0103; Moji_Joho; MJ014799 -6B4E E0104; Hanyo-Denshi; KS183640 -6B4E E0104; Moji_Joho; MJ057884 -6B50 E0100; Adobe-Japan1; CID+5342 -6B50 E0101; Hanyo-Denshi; JA6131 -6B50 E0101; Moji_Joho; MJ014801 -6B50 E0102; Hanyo-Denshi; KS183890 -6B50 E0102; Moji_Joho; MJ014802 -6B52 E0100; Adobe-Japan1; CID+21821 -6B53 E0100; Adobe-Japan1; CID+1531 -6B54 E0100; Adobe-Japan1; CID+5344 -6B54 E0101; Hanyo-Denshi; JA6133 -6B54 E0101; Moji_Joho; MJ014807 -6B54 E0102; Hanyo-Denshi; FT2269 -6B54 E0102; Moji_Joho; MJ014806 -6B55 E0100; Hanyo-Denshi; KS184020 -6B55 E0100; Moji_Joho; MJ014808 -6B55 E0101; Hanyo-Denshi; KS184120 -6B55 E0101; Moji_Joho; MJ014809 -6B56 E0100; Adobe-Japan1; CID+14681 -6B58 E0100; Adobe-Japan1; CID+17890 -6B59 E0100; Adobe-Japan1; CID+5343 -6B59 E0101; Hanyo-Denshi; JA6132 -6B59 E0101; Moji_Joho; MJ014813 -6B59 E0102; Hanyo-Denshi; FT2268 -6B59 E0102; Moji_Joho; MJ014814 -6B5B E0100; Adobe-Japan1; CID+5345 -6B5D E0100; Adobe-Japan1; CID+21822 -6B5F E0100; Adobe-Japan1; CID+5346 -6B60 E0100; Adobe-Japan1; CID+14682 -6B61 E0100; Adobe-Japan1; CID+5347 -6B61 E0101; Hanyo-Denshi; JA6136 -6B61 E0101; Moji_Joho; MJ014821 -6B61 E0102; Hanyo-Denshi; KS184400 -6B61 E0102; Moji_Joho; MJ014822 -6B61 E0103; Hanyo-Denshi; TK01047420 -6B62 E0100; Adobe-Japan1; CID+2221 -6B62 E0101; Hanyo-Denshi; JA2763 -6B62 E0101; Moji_Joho; MJ014823 -6B62 E0102; Hanyo-Denshi; KS184490 -6B62 E0102; Moji_Joho; MJ014824 -6B63 E0100; Adobe-Japan1; CID+2649 -6B64 E0100; Adobe-Japan1; CID+2065 -6B65 E0100; Adobe-Japan1; CID+13386 -6B66 E0100; Adobe-Japan1; CID+3554 -6B67 E0100; Adobe-Japan1; CID+16922 -6B69 E0100; Adobe-Japan1; CID+3634 -6B6A E0100; Adobe-Japan1; CID+4074 -6B6B E0100; Adobe-Japan1; CID+21823 -6B6C E0100; Adobe-Japan1; CID+17891 -6B6E E0100; Adobe-Japan1; CID+21824 -6B6F E0100; Adobe-Japan1; CID+2243 -6B6F E0101; Hanyo-Denshi; JA2785 -6B6F E0101; Moji_Joho; MJ014837 -6B6F E0102; Hanyo-Denshi; KS549120 -6B6F E0102; Moji_Joho; MJ059281 -6B70 E0100; Adobe-Japan1; CID+21825 -6B70 E0101; Hanyo-Denshi; JB3792 -6B70 E0101; Moji_Joho; MJ014838 -6B70 E0102; Hanyo-Denshi; KS185370 -6B70 E0102; Moji_Joho; MJ014839 -6B70 E0103; Hanyo-Denshi; KS185430 -6B70 E0103; Moji_Joho; MJ057898 -6B72 E0100; Adobe-Japan1; CID+13785 -6B72 E0101; Hanyo-Denshi; IP6B72 -6B72 E0101; Moji_Joho; MJ014842 -6B72 E0102; Hanyo-Denshi; JTB3E5 -6B72 E0102; Moji_Joho; MJ014843 -6B72 E0103; Hanyo-Denshi; KS185510 -6B72 E0103; Moji_Joho; MJ057899 -6B72 E0104; Moji_Joho; MJ014841 -6B72 E0105; Moji_Joho; MJ057897 -6B73 E0100; Adobe-Japan1; CID+2112 -6B73 E0101; Hanyo-Denshi; JA2648 -6B73 E0101; Moji_Joho; MJ014844 -6B73 E0102; Hanyo-Denshi; JTB3E1 -6B73 E0103; Hanyo-Denshi; JTB3E6S -6B73 E0103; Moji_Joho; MJ059760 -6B74 E0100; Adobe-Japan1; CID+4026 -6B75 E0100; Adobe-Japan1; CID+17892 -6B77 E0100; Adobe-Japan1; CID+13398 -6B78 E0100; Adobe-Japan1; CID+5348 -6B78 E0101; Hanyo-Denshi; JA6137 -6B78 E0101; Moji_Joho; MJ014849 -6B78 E0102; Hanyo-Denshi; FT2270 -6B78 E0102; Moji_Joho; MJ014850 -6B79 E0100; Adobe-Japan1; CID+5349 -6B7A E0100; Adobe-Japan1; CID+17893 -6B7B E0100; Adobe-Japan1; CID+2222 -6B7B E0101; Hanyo-Denshi; JA2764 -6B7B E0102; Hanyo-Denshi; KS185820 -6B7D E0100; Adobe-Japan1; CID+19476 -6B7E E0100; Adobe-Japan1; CID+19477 -6B7F E0100; Adobe-Japan1; CID+5350 -6B80 E0100; Adobe-Japan1; CID+5351 -6B81 E0100; Adobe-Japan1; CID+17894 -6B82 E0100; Adobe-Japan1; CID+14683 -6B83 E0100; Adobe-Japan1; CID+5353 -6B84 E0100; Adobe-Japan1; CID+5352 -6B85 E0100; Adobe-Japan1; CID+21826 -6B86 E0100; Adobe-Japan1; CID+3718 -6B89 E0100; Adobe-Japan1; CID+2408 -6B8A E0100; Adobe-Japan1; CID+2328 -6B8B E0100; Adobe-Japan1; CID+2194 -6B8D E0100; Adobe-Japan1; CID+5354 -6B8D E0101; Hanyo-Denshi; JA6143 -6B8D E0101; Moji_Joho; MJ014869 -6B8D E0102; Hanyo-Denshi; FT2271 -6B8D E0102; Moji_Joho; MJ014870 -6B95 E0100; Adobe-Japan1; CID+5356 -6B96 E0100; Adobe-Japan1; CID+2537 -6B96 E0101; Adobe-Japan1; CID+13846 -6B97 E0100; Adobe-Japan1; CID+21827 -6B98 E0100; Adobe-Japan1; CID+5355 -6B9B E0100; Adobe-Japan1; CID+17895 -6B9E E0100; Adobe-Japan1; CID+5357 -6B9F E0100; Adobe-Japan1; CID+21828 -6B9F E0101; Hanyo-Denshi; JB3806 -6B9F E0101; Moji_Joho; MJ014885 -6B9F E0102; Hanyo-Denshi; KS187460 -6B9F E0102; Moji_Joho; MJ057909 -6BA0 E0100; Adobe-Japan1; CID+21829 -6BA2 E0100; Adobe-Japan1; CID+21830 -6BA3 E0100; Adobe-Japan1; CID+21831 -6BA4 E0100; Adobe-Japan1; CID+5358 -6BA8 E0100; Adobe-Japan1; CID+21832 -6BA9 E0100; Adobe-Japan1; CID+16923 -6BA9 E0101; Hanyo-Denshi; JB3811 -6BA9 E0101; Moji_Joho; MJ014894 -6BA9 E0102; Hanyo-Denshi; JC8639 -6BA9 E0102; Moji_Joho; MJ014895 -6BAA E0100; Adobe-Japan1; CID+5359 -6BAB E0100; Adobe-Japan1; CID+5360 -6BAC E0100; Adobe-Japan1; CID+21833 -6BAD E0100; Adobe-Japan1; CID+16924 -6BAE E0100; Adobe-Japan1; CID+17896 -6BAF E0100; Adobe-Japan1; CID+5361 -6BAF E0101; Hanyo-Denshi; JA6150 -6BAF E0101; Moji_Joho; MJ014901 -6BAF E0102; Hanyo-Denshi; FT2272S -6BAF E0102; Moji_Joho; MJ014903 -6BAF E0103; Moji_Joho; MJ014902 -6BB0 E0100; Adobe-Japan1; CID+19478 -6BB0 E0101; Hanyo-Denshi; JB3815 -6BB0 E0101; Moji_Joho; MJ014904 -6BB0 E0102; Hanyo-Denshi; JTB3F0 -6BB0 E0102; Moji_Joho; MJ014905 -6BB1 E0100; Adobe-Japan1; CID+5363 -6BB2 E0100; Adobe-Japan1; CID+5362 -6BB3 E0100; Adobe-Japan1; CID+5364 -6BB3 E0101; Hanyo-Denshi; JA6153 -6BB3 E0101; Moji_Joho; MJ014908 -6BB3 E0102; Hanyo-Denshi; KS188360 -6BB3 E0102; Moji_Joho; MJ014909 -6BB4 E0100; Adobe-Japan1; CID+1317 -6BB5 E0100; Adobe-Japan1; CID+2952 -6BB7 E0100; Adobe-Japan1; CID+5365 -6BB8 E0100; Adobe-Japan1; CID+21834 -6BB8 E0101; Hanyo-Denshi; JB3816 -6BB8 E0101; Moji_Joho; MJ014914 -6BB8 E0102; Hanyo-Denshi; KS188570 -6BB8 E0102; Moji_Joho; MJ057918 -6BB9 E0100; Adobe-Japan1; CID+21835 -6BBA E0100; Adobe-Japan1; CID+13344 -6BBA E0101; Adobe-Japan1; CID+2164 -6BBA E0102; Hanyo-Denshi; JA2706 -6BBA E0103; Hanyo-Denshi; JC8641 -6BBB E0100; Adobe-Japan1; CID+1450 -6BBB E0101; Adobe-Japan1; CID+13424 -6BBB E0102; Moji_Joho; MJ014917 -6BBB E0103; Moji_Joho; MJ014918 -6BBC E0100; Adobe-Japan1; CID+5366 -6BBC E0101; Moji_Joho; MJ014919 -6BBC E0102; Moji_Joho; MJ014920 -6BBD E0100; Adobe-Japan1; CID+17898 -6BBE E0100; Adobe-Japan1; CID+14684 -6BBF E0100; Adobe-Japan1; CID+3132 -6BC0 E0100; Adobe-Japan1; CID+4509 -6BC3 E0100; Adobe-Japan1; CID+21836 -6BC4 E0100; Adobe-Japan1; CID+21837 -6BC5 E0100; Adobe-Japan1; CID+1597 -6BC6 E0100; Adobe-Japan1; CID+5367 -6BC6 E0101; Hanyo-Denshi; JA6156 -6BC6 E0101; Moji_Joho; MJ014929 -6BC6 E0102; Hanyo-Denshi; KS189140 -6BC6 E0102; Moji_Joho; MJ014930 -6BC7 E0100; Adobe-Japan1; CID+17899 -6BC8 E0100; Adobe-Japan1; CID+17900 -6BC9 E0100; Adobe-Japan1; CID+17901 -6BCB E0100; Adobe-Japan1; CID+5368 -6BCB E0101; Hanyo-Denshi; JA6157 -6BCB E0102; Hanyo-Denshi; TK01047990 -6BCC E0100; Adobe-Japan1; CID+14148 -6BCD E0100; Adobe-Japan1; CID+3644 -6BCE E0100; Adobe-Japan1; CID+3734 -6BCF E0100; Adobe-Japan1; CID+13388 -6BD2 E0100; Adobe-Japan1; CID+3231 -6BD2 E0101; Hanyo-Denshi; JA3839 -6BD2 E0101; Moji_Joho; MJ014943 -6BD2 E0102; Hanyo-Denshi; KS189680 -6BD2 E0102; Moji_Joho; MJ057930 -6BD3 E0100; Adobe-Japan1; CID+5369 -6BD3 E0101; Hanyo-Denshi; JA6158 -6BD3 E0101; Moji_Joho; MJ014944 -6BD3 E0102; Hanyo-Denshi; FT2273S -6BD3 E0102; Moji_Joho; MJ014945 -6BD3 E0103; Hanyo-Denshi; TK01048050 -6BD4 E0100; Adobe-Japan1; CID+3450 -6BD6 E0100; Adobe-Japan1; CID+8509 -6BD7 E0100; Adobe-Japan1; CID+16925 -6BD8 E0100; Adobe-Japan1; CID+3471 -6BDA E0100; Adobe-Japan1; CID+17902 -6BDB E0100; Adobe-Japan1; CID+3807 -6BDF E0100; Adobe-Japan1; CID+5370 -6BE1 E0100; Adobe-Japan1; CID+14685 -6BE3 E0100; Adobe-Japan1; CID+21838 -6BE6 E0100; Adobe-Japan1; CID+17903 -6BE7 E0100; Adobe-Japan1; CID+17904 -6BEB E0100; Adobe-Japan1; CID+5372 -6BEC E0100; Adobe-Japan1; CID+5371 -6BEE E0100; Adobe-Japan1; CID+17905 -6BEF E0100; Adobe-Japan1; CID+5374 -6BF1 E0100; Adobe-Japan1; CID+14686 -6BF3 E0100; Adobe-Japan1; CID+5373 -6BF7 E0100; Adobe-Japan1; CID+19479 -6BF9 E0100; Adobe-Japan1; CID+19480 -6BFA E0100; Hanyo-Denshi; IP6BFA -6BFA E0100; Moji_Joho; MJ014978 -6BFA E0101; Hanyo-Denshi; JT6BFA -6BFA E0101; Moji_Joho; MJ014979 -6BFF E0100; Adobe-Japan1; CID+16926 -6C02 E0100; Adobe-Japan1; CID+17906 -6C03 E0100; Hanyo-Denshi; KS191900 -6C03 E0100; Moji_Joho; MJ014988 -6C03 E0101; Hanyo-Denshi; KS192050 -6C03 E0101; Moji_Joho; MJ014989 -6C04 E0100; Adobe-Japan1; CID+19481 -6C05 E0100; Adobe-Japan1; CID+16927 -6C08 E0100; Adobe-Japan1; CID+5376 -6C08 E0101; Adobe-Japan1; CID+7993 -6C08 E0102; Adobe-Japan1; CID+13556 -6C08 E0103; Hanyo-Denshi; JA6165 -6C08 E0103; Moji_Joho; MJ014993 -6C08 E0104; Hanyo-Denshi; FT1706 -6C08 E0104; Moji_Joho; MJ014994 -6C08 E0105; Hanyo-Denshi; TK01048200 -6C08 E0106; Moji_Joho; MJ014995 -6C09 E0100; Adobe-Japan1; CID+19482 -6C0A E0100; Adobe-Japan1; CID+17907 -6C0D E0100; Adobe-Japan1; CID+19483 -6C0E E0100; Adobe-Japan1; CID+17908 -6C0E E0101; Hanyo-Denshi; JB3840 -6C0E E0101; Moji_Joho; MJ015002 -6C0E E0102; Hanyo-Denshi; IB2188 -6C0E E0102; Moji_Joho; MJ015003 -6C0F E0100; Adobe-Japan1; CID+2223 -6C10 E0100; Adobe-Japan1; CID+14687 -6C10 E0101; Hanyo-Denshi; JB3841 -6C10 E0101; Moji_Joho; MJ015005 -6C10 E0102; Hanyo-Denshi; KS192590 -6C10 E0102; Moji_Joho; MJ057935 -6C11 E0100; Adobe-Japan1; CID+3773 -6C12 E0100; Adobe-Japan1; CID+21839 -6C13 E0100; Adobe-Japan1; CID+5377 -6C13 E0101; Adobe-Japan1; CID+13557 -6C13 E0102; Hanyo-Denshi; JA6166 -6C13 E0102; Moji_Joho; MJ015008 -6C13 E0103; Hanyo-Denshi; FT2275S -6C13 E0103; Moji_Joho; MJ015009 -6C13 E0104; Hanyo-Denshi; JTB402 -6C13 E0104; Moji_Joho; MJ015010 -6C14 E0100; Adobe-Japan1; CID+5378 -6C14 E0101; Hanyo-Denshi; JA6167 -6C14 E0101; Moji_Joho; MJ015011 -6C14 E0102; Hanyo-Denshi; KS002130 -6C14 E0102; Moji_Joho; MJ056866 -6C17 E0100; Adobe-Japan1; CID+1598 -6C19 E0100; Adobe-Japan1; CID+21840 -6C1B E0100; Adobe-Japan1; CID+5379 -6C1B E0101; Hanyo-Denshi; JA6168 -6C1B E0101; Moji_Joho; MJ015015 -6C1B E0102; Hanyo-Denshi; FT2276 -6C1B E0102; Moji_Joho; MJ015016 -6C1F E0100; Adobe-Japan1; CID+21841 -6C23 E0100; Adobe-Japan1; CID+5381 -6C24 E0100; Adobe-Japan1; CID+5380 -6C26 E0100; Adobe-Japan1; CID+21842 -6C27 E0100; Adobe-Japan1; CID+21843 -6C28 E0100; Adobe-Japan1; CID+21844 -6C2C E0100; Adobe-Japan1; CID+19484 -6C2E E0100; Adobe-Japan1; CID+21845 -6C33 E0100; Adobe-Japan1; CID+14688 -6C34 E0100; Adobe-Japan1; CID+2603 -6C35 E0100; Adobe-Japan1; CID+14689 -6C36 E0100; Adobe-Japan1; CID+17909 -6C37 E0100; Adobe-Japan1; CID+3499 -6C38 E0100; Adobe-Japan1; CID+1260 -6C38 E0101; Adobe-Japan1; CID+20154 -6C3A E0100; Adobe-Japan1; CID+20309 -6C3A E0101; Adobe-Japan1; CID+14690 -6C3B E0100; Adobe-Japan1; CID+21846 -6C3E E0100; Adobe-Japan1; CID+3417 -6C3F E0100; Adobe-Japan1; CID+8510 -6C40 E0100; Adobe-Japan1; CID+3089 -6C41 E0100; Adobe-Japan1; CID+2379 -6C42 E0100; Adobe-Japan1; CID+1659 -6C42 E0101; Hanyo-Denshi; JA2165 -6C42 E0101; Moji_Joho; MJ015049 -6C42 E0102; Hanyo-Denshi; JTB405 -6C42 E0102; Moji_Joho; MJ059770 -6C42 E0103; Hanyo-Denshi; KS193900 -6C42 E0103; Moji_Joho; MJ057940 -6C47 E0100; Hanyo-Denshi; TK01048290 -6C47 E0101; Hanyo-Denshi; TK01048310 -6C4A E0100; Adobe-Japan1; CID+19485 -6C4B E0100; Adobe-Japan1; CID+21847 -6C4D E0100; Adobe-Japan1; CID+17911 -6C4D E0101; Moji_Joho; MJ015059 -6C4D E0102; Moji_Joho; MJ015060 -6C4E E0100; Adobe-Japan1; CID+3418 -6C4E E0101; Hanyo-Denshi; JA4038 -6C4E E0101; Moji_Joho; MJ015061 -6C4E E0102; Hanyo-Denshi; KS193830 -6C4E E0102; Moji_Joho; MJ015062 -6C4F E0100; Adobe-Japan1; CID+21848 -6C50 E0100; Adobe-Japan1; CID+2266 -6C52 E0100; Adobe-Japan1; CID+19486 -6C52 E0101; Hanyo-Denshi; JB3860 -6C52 E0101; Moji_Joho; MJ015066 -6C52 E0102; Hanyo-Denshi; IB2192 -6C52 E0102; Moji_Joho; MJ015067 -6C54 E0100; Adobe-Japan1; CID+19487 -6C55 E0100; Adobe-Japan1; CID+5383 -6C57 E0100; Adobe-Japan1; CID+1532 -6C59 E0100; Adobe-Japan1; CID+14691 -6C5A E0100; Adobe-Japan1; CID+1306 -6C5B E0100; Adobe-Japan1; CID+17912 -6C5B E0101; Hanyo-Denshi; JB3863 -6C5B E0101; Moji_Joho; MJ015076 -6C5B E0102; Hanyo-Denshi; JTB406 -6C5B E0102; Moji_Joho; MJ015077 -6C5C E0100; Adobe-Japan1; CID+8511 -6C5D E0100; Adobe-Japan1; CID+3274 -6C5E E0100; Adobe-Japan1; CID+5382 -6C5F E0100; Adobe-Japan1; CID+2000 -6C5F E0101; Hanyo-Denshi; JA2530 -6C5F E0102; Hanyo-Denshi; TK01048390 -6C60 E0100; Adobe-Japan1; CID+2961 -6C62 E0100; Adobe-Japan1; CID+5384 -6C67 E0100; Adobe-Japan1; CID+17930 -6C67 E0101; Hanyo-Denshi; JB3922 -6C67 E0101; Moji_Joho; MJ015091 -6C67 E0102; Hanyo-Denshi; IB2201 -6C67 E0102; Moji_Joho; MJ015090 -6C67 E0103; Hanyo-Denshi; TK01049100 -6C68 E0100; Adobe-Japan1; CID+5392 -6C6A E0100; Adobe-Japan1; CID+5385 -6C6A E0101; Hanyo-Denshi; JA6174 -6C6A E0102; Hanyo-Denshi; TK01048620 -6C6B E0100; Adobe-Japan1; CID+21849 -6C6D E0100; Adobe-Japan1; CID+17913 -6C6D E0101; Hanyo-Denshi; JB3866 -6C6D E0101; Moji_Joho; MJ015098 -6C6D E0102; Hanyo-Denshi; IB0242 -6C6D E0102; Moji_Joho; MJ015099 -6C6D E0103; Hanyo-Denshi; JTB411 -6C6D E0103; Moji_Joho; MJ015100 -6C6F E0100; Adobe-Japan1; CID+8513 -6C70 E0100; Adobe-Japan1; CID+2849 -6C72 E0100; Adobe-Japan1; CID+1660 -6C72 E0101; Adobe-Japan1; CID+7966 -6C72 E0102; Hanyo-Denshi; JA2166 -6C72 E0102; Moji_Joho; MJ015105 -6C72 E0103; Hanyo-Denshi; HG1611 -6C72 E0103; Moji_Joho; MJ015106 -6C73 E0100; Adobe-Japan1; CID+5393 -6C74 E0100; Adobe-Japan1; CID+16928 -6C74 E0101; Hanyo-Denshi; JB3868 -6C74 E0101; Moji_Joho; MJ015108 -6C74 E0102; Hanyo-Denshi; JC8652 -6C74 E0102; Moji_Joho; MJ015109 -6C76 E0100; Adobe-Japan1; CID+14692 -6C76 E0101; Moji_Joho; MJ015111 -6C76 E0102; Moji_Joho; MJ015112 -6C78 E0100; Adobe-Japan1; CID+21850 -6C79 E0100; Adobe-Japan1; CID+19488 -6C7A E0100; Adobe-Japan1; CID+1854 -6C7B E0100; Adobe-Japan1; CID+14693 -6C7D E0100; Adobe-Japan1; CID+1599 -6C7E E0100; Adobe-Japan1; CID+5391 -6C7E E0101; Hanyo-Denshi; JA6180 -6C7E E0101; Moji_Joho; MJ015120 -6C7E E0102; Hanyo-Denshi; FT2277 -6C7E E0102; Moji_Joho; MJ015121 -6C81 E0100; Adobe-Japan1; CID+5389 -6C82 E0100; Adobe-Japan1; CID+5386 -6C83 E0100; Adobe-Japan1; CID+3914 -6C84 E0100; Adobe-Japan1; CID+17914 -6C84 E0101; Hanyo-Denshi; JD7825 -6C84 E0102; Hanyo-Denshi; TK01048440 -6C85 E0100; Adobe-Japan1; CID+14694 -6C86 E0100; Adobe-Japan1; CID+8512 -6C87 E0100; Adobe-Japan1; CID+21851 -6C88 E0100; Adobe-Japan1; CID+3036 -6C88 E0101; Hanyo-Denshi; JA3632 -6C88 E0101; Moji_Joho; MJ015132 -6C88 E0102; Hanyo-Denshi; KS195890 -6C88 E0102; Moji_Joho; MJ057943 -6C88 E0103; Hanyo-Denshi; TK01048680 -6C89 E0100; Adobe-Japan1; CID+17915 -6C8C E0100; Adobe-Japan1; CID+3249 -6C8D E0100; Adobe-Japan1; CID+5387 -6C90 E0100; Adobe-Japan1; CID+5395 -6C92 E0100; Adobe-Japan1; CID+5394 -6C93 E0100; Adobe-Japan1; CID+1785 -6C94 E0100; Adobe-Japan1; CID+17917 -6C95 E0100; Adobe-Japan1; CID+14695 -6C96 E0100; Adobe-Japan1; CID+1325 -6C97 E0100; Adobe-Japan1; CID+17918 -6C97 E0101; Hanyo-Denshi; JB3879 -6C97 E0101; Moji_Joho; MJ015148 -6C97 E0102; Hanyo-Denshi; JTB419 -6C97 E0102; Moji_Joho; MJ015149 -6C97 E0103; Hanyo-Denshi; KS067600 -6C97 E0103; Moji_Joho; MJ015147 -6C98 E0100; Adobe-Japan1; CID+16929 -6C99 E0100; Adobe-Japan1; CID+2091 -6C9A E0100; Adobe-Japan1; CID+5388 -6C9B E0100; Adobe-Japan1; CID+5390 -6C9C E0100; Adobe-Japan1; CID+14696 -6C9F E0100; Adobe-Japan1; CID+21852 -6CA0 E0100; Hanyo-Denshi; IP6CA0 -6CA0 E0100; Moji_Joho; MJ015158 -6CA0 E0101; Hanyo-Denshi; JT6CA0 -6CA0 E0101; Moji_Joho; MJ015159 -6CA1 E0100; Adobe-Japan1; CID+3717 -6CA1 E0101; Hanyo-Denshi; JA4355 -6CA1 E0101; Moji_Joho; MJ015160 -6CA1 E0102; Hanyo-Denshi; KS194670 -6CA1 E0102; Moji_Joho; MJ015161 -6CA2 E0100; Adobe-Japan1; CID+2900 -6CAA E0100; Adobe-Japan1; CID+14153 -6CAA E0101; Adobe-Japan1; CID+14152 -6CAA E0102; Adobe-Japan1; CID+20155 -6CAA E0103; Hanyo-Denshi; JC8651 -6CAA E0103; Moji_Joho; MJ015163 -6CAA E0104; Hanyo-Denshi; JTB415 -6CAA E0104; Moji_Joho; MJ015164 -6CAA E0105; Hanyo-Denshi; TK01048490 -6CAB E0100; Adobe-Japan1; CID+3749 -6CAC E0100; Adobe-Japan1; CID+19489 -6CAD E0100; Adobe-Japan1; CID+17919 -6CAE E0100; Adobe-Japan1; CID+5403 -6CB0 E0100; Adobe-Japan1; CID+21853 -6CB1 E0100; Adobe-Japan1; CID+5404 -6CB2 E0100; Adobe-Japan1; CID+21854 -6CB3 E0100; Adobe-Japan1; CID+1359 -6CB4 E0100; Adobe-Japan1; CID+19490 -6CB7 E0100; Hanyo-Denshi; JTB417S -6CB7 E0100; Moji_Joho; MJ015178 -6CB7 E0101; Hanyo-Denshi; KS194890 -6CB7 E0101; Moji_Joho; MJ015177 -6CB8 E0100; Adobe-Japan1; CID+3576 -6CB9 E0100; Adobe-Japan1; CID+3849 -6CBA E0100; Adobe-Japan1; CID+5406 -6CBB E0100; Adobe-Japan1; CID+2255 -6CBC E0100; Adobe-Japan1; CID+2474 -6CBD E0100; Adobe-Japan1; CID+5399 -6CBE E0100; Adobe-Japan1; CID+5405 -6CBF E0100; Adobe-Japan1; CID+13656 -6CBF E0101; Adobe-Japan1; CID+1290 -6CBF E0102; Adobe-Japan1; CID+13416 -6CBF E0103; Hanyo-Denshi; JA1772 -6CBF E0103; Moji_Joho; MJ015186 -6CBF E0104; Hanyo-Denshi; JTB41A -6CBF E0104; Moji_Joho; MJ015187 -6CBF E0105; Hanyo-Denshi; FT1607 -6CBF E0105; Moji_Joho; MJ015188 -6CC1 E0100; Adobe-Japan1; CID+1711 -6CC2 E0100; Adobe-Japan1; CID+17920 -6CC4 E0100; Adobe-Japan1; CID+5396 -6CC5 E0100; Adobe-Japan1; CID+5401 -6CC6 E0100; Adobe-Japan1; CID+16931 -6CC9 E0100; Adobe-Japan1; CID+2712 -6CC9 E0101; Hanyo-Denshi; JA3284 -6CC9 E0102; Hanyo-Denshi; TK01048870 -6CCA E0100; Adobe-Japan1; CID+3367 -6CCC E0100; Adobe-Japan1; CID+3451 -6CCD E0100; Adobe-Japan1; CID+21855 -6CCF E0100; Adobe-Japan1; CID+21856 -6CD0 E0100; Adobe-Japan1; CID+14697 -6CD1 E0100; Adobe-Japan1; CID+21857 -6CD2 E0100; Adobe-Japan1; CID+19491 -6CD2 E0101; Hanyo-Denshi; JB3892 -6CD2 E0101; Moji_Joho; MJ015209 -6CD2 E0102; Hanyo-Denshi; JTB41E -6CD2 E0102; Moji_Joho; MJ015210 -6CD2 E0103; Hanyo-Denshi; KS195870 -6CD2 E0103; Moji_Joho; MJ015208 -6CD3 E0100; Adobe-Japan1; CID+5398 -6CD4 E0100; Adobe-Japan1; CID+14698 -6CD5 E0100; Adobe-Japan1; CID+3663 -6CD6 E0100; Adobe-Japan1; CID+14699 -6CD7 E0100; Adobe-Japan1; CID+5400 -6CD9 E0100; Adobe-Japan1; CID+5409 -6CD9 E0101; Hanyo-Denshi; JA6204 -6CD9 E0101; Moji_Joho; MJ015217 -6CD9 E0102; Hanyo-Denshi; FT2278 -6CD9 E0102; Moji_Joho; MJ015218 -6CDA E0100; Adobe-Japan1; CID+8514 -6CDB E0100; Adobe-Japan1; CID+5407 -6CDC E0100; Adobe-Japan1; CID+17922 -6CDD E0100; Adobe-Japan1; CID+5402 -6CE0 E0100; Adobe-Japan1; CID+14700 -6CE1 E0100; Adobe-Japan1; CID+3664 -6CE1 E0101; Adobe-Japan1; CID+7793 -6CE1 E0102; Hanyo-Denshi; JA4302 -6CE1 E0102; Moji_Joho; MJ015227 -6CE1 E0103; Hanyo-Denshi; FT1920 -6CE1 E0103; Moji_Joho; MJ015226 -6CE2 E0100; Adobe-Japan1; CID+3326 -6CE3 E0100; Adobe-Japan1; CID+1661 -6CE5 E0100; Adobe-Japan1; CID+3103 -6CE7 E0100; Adobe-Japan1; CID+21858 -6CE7 E0101; Moji_Joho; MJ015233 -6CE7 E0102; Moji_Joho; MJ015234 -6CE8 E0100; Adobe-Japan1; CID+2987 -6CE8 E0101; Adobe-Japan1; CID+13926 -6CE8 E0102; Adobe-Japan1; CID+12869 -6CE8 E0103; Hanyo-Denshi; JA3577 -6CE8 E0103; Moji_Joho; MJ015235 -6CE8 E0104; Hanyo-Denshi; JTB41C -6CE8 E0104; Moji_Joho; MJ015236 -6CE9 E0100; Adobe-Japan1; CID+17923 -6CEA E0100; Adobe-Japan1; CID+5410 -6CEB E0100; Adobe-Japan1; CID+14701 -6CEC E0100; Adobe-Japan1; CID+14702 -6CED E0100; Adobe-Japan1; CID+17924 -6CEE E0100; Adobe-Japan1; CID+14703 -6CEF E0100; Adobe-Japan1; CID+5408 -6CF0 E0100; Adobe-Japan1; CID+2873 -6CF0 E0101; Hanyo-Denshi; JA3457 -6CF0 E0101; Moji_Joho; MJ015245 -6CF0 E0102; Hanyo-Denshi; KS197030 -6CF0 E0102; Moji_Joho; MJ015244 -6CF0 E0103; Moji_Joho; MJ057277 -6CF1 E0100; Adobe-Japan1; CID+5397 -6CF2 E0100; Adobe-Japan1; CID+21859 -6CF3 E0100; Adobe-Japan1; CID+1261 -6CF3 E0101; Hanyo-Denshi; JA1743 -6CF3 E0102; Hanyo-Denshi; TK01049050 -6CF4 E0100; Adobe-Japan1; CID+21860 -6CFB E0100; Adobe-Japan1; CID+16930 -6CFB E0101; Hanyo-Denshi; JC8658 -6CFB E0101; Moji_Joho; MJ015252 -6CFB E0102; Hanyo-Denshi; KS195860 -6CFB E0102; Moji_Joho; MJ015251 -6D00 E0100; Adobe-Japan1; CID+17926 -6D01 E0100; Adobe-Japan1; CID+15413 -6D01 E0101; Hanyo-Denshi; IP6D01 -6D01 E0102; Hanyo-Denshi; TK01049150 -6D04 E0100; Adobe-Japan1; CID+8515 -6D07 E0100; Adobe-Japan1; CID+21861 -6D0A E0100; Adobe-Japan1; CID+14704 -6D0B E0100; Adobe-Japan1; CID+3896 -6D0C E0100; Adobe-Japan1; CID+5421 -6D0E E0100; Adobe-Japan1; CID+14705 -6D0F E0100; Adobe-Japan1; CID+21862 -6D11 E0100; Adobe-Japan1; CID+14706 -6D12 E0100; Adobe-Japan1; CID+5420 -6D13 E0100; Adobe-Japan1; CID+21863 -6D17 E0100; Adobe-Japan1; CID+2714 -6D19 E0100; Adobe-Japan1; CID+5417 -6D1A E0100; Adobe-Japan1; CID+21864 -6D1A E0101; Hanyo-Denshi; JB3918 -6D1A E0102; Hanyo-Denshi; TK01049660 -6D1B E0100; Adobe-Japan1; CID+3926 -6D1E E0100; Adobe-Japan1; CID+3214 -6D1F E0100; Adobe-Japan1; CID+5411 -6D24 E0100; Adobe-Japan1; CID+17927 -6D25 E0100; Adobe-Japan1; CID+3041 -6D25 E0101; Hanyo-Denshi; JA3637 -6D25 E0101; Moji_Joho; MJ015296 -6D25 E0102; Hanyo-Denshi; JTB433 -6D25 E0102; Moji_Joho; MJ059778 -6D25 E0103; Hanyo-Denshi; TK01048920 -6D26 E0100; Adobe-Japan1; CID+17928 -6D27 E0100; Adobe-Japan1; CID+17929 -6D28 E0100; Adobe-Japan1; CID+21865 -6D29 E0100; Adobe-Japan1; CID+1262 -6D29 E0101; Hanyo-Denshi; JA1744 -6D29 E0101; Moji_Joho; MJ015300 -6D29 E0102; Hanyo-Denshi; KS198380 -6D29 E0102; Moji_Joho; MJ057950 -6D2A E0100; Adobe-Japan1; CID+2001 -6D2B E0100; Adobe-Japan1; CID+5414 -6D2E E0100; Adobe-Japan1; CID+14707 -6D2F E0100; Adobe-Japan1; CID+17931 -6D2F E0101; Hanyo-Denshi; JB3924 -6D2F E0101; Moji_Joho; MJ015306 -6D2F E0102; Hanyo-Denshi; JTB428 -6D2F E0102; Moji_Joho; MJ015307 -6D31 E0100; Adobe-Japan1; CID+16932 -6D32 E0100; Adobe-Japan1; CID+2353 -6D33 E0100; Adobe-Japan1; CID+5419 -6D34 E0100; Adobe-Japan1; CID+17950 -6D34 E0101; Hanyo-Denshi; JD7869 -6D34 E0101; Moji_Joho; MJ015313 -6D34 E0102; Hanyo-Denshi; IP6D34 -6D34 E0102; Moji_Joho; MJ015312 -6D35 E0100; Adobe-Japan1; CID+5418 -6D36 E0100; Adobe-Japan1; CID+5413 -6D38 E0100; Adobe-Japan1; CID+5416 -6D39 E0100; Adobe-Japan1; CID+16933 -6D3A E0100; Hanyo-Denshi; IP6D3A -6D3A E0101; Hanyo-Denshi; TK01048960 -6D3B E0100; Adobe-Japan1; CID+1478 -6D3C E0100; Adobe-Japan1; CID+17932 -6D3D E0100; Adobe-Japan1; CID+5415 -6D3E E0100; Adobe-Japan1; CID+3327 -6D3E E0101; Adobe-Japan1; CID+13486 -6D3E E0102; Adobe-Japan1; CID+13974 -6D3E E0103; Hanyo-Denshi; JA3941 -6D3E E0103; Moji_Joho; MJ015325 -6D3E E0104; Hanyo-Denshi; JTB424 -6D3E E0104; Moji_Joho; MJ015324 -6D3F E0100; Adobe-Japan1; CID+16934 -6D3F E0101; Hanyo-Denshi; JB3928 -6D3F E0102; Hanyo-Denshi; TK01048840 -6D41 E0100; Adobe-Japan1; CID+3958 -6D41 E0101; Hanyo-Denshi; JA4614 -6D41 E0101; Moji_Joho; MJ015330 -6D41 E0102; Hanyo-Denshi; KS196780 -6D41 E0102; Moji_Joho; MJ015329 -6D44 E0100; Adobe-Japan1; CID+2524 -6D45 E0100; Adobe-Japan1; CID+2713 -6D57 E0100; Adobe-Japan1; CID+14708 -6D58 E0100; Adobe-Japan1; CID+16935 -6D59 E0100; Adobe-Japan1; CID+5427 -6D5A E0100; Adobe-Japan1; CID+5425 -6D5B E0100; Adobe-Japan1; CID+17933 -6D5C E0100; Adobe-Japan1; CID+3519 -6D5E E0100; Adobe-Japan1; CID+14709 -6D5F E0100; Adobe-Japan1; CID+21866 -6D60 E0100; Adobe-Japan1; CID+17934 -6D61 E0100; Adobe-Japan1; CID+19492 -6D63 E0100; Adobe-Japan1; CID+5422 -6D64 E0100; Adobe-Japan1; CID+5424 -6D65 E0100; Adobe-Japan1; CID+14710 -6D66 E0100; Adobe-Japan1; CID+1244 -6D67 E0100; Adobe-Japan1; CID+21867 -6D69 E0100; Adobe-Japan1; CID+2002 -6D69 E0101; Adobe-Japan1; CID+13768 -6D69 E0102; Hanyo-Denshi; JA2532 -6D69 E0102; Moji_Joho; MJ015356 -6D69 E0103; Hanyo-Denshi; IB2221 -6D69 E0103; Moji_Joho; MJ015355 -6D6A E0100; Adobe-Japan1; CID+4056 -6D6C E0100; Adobe-Japan1; CID+1435 -6D6E E0100; Adobe-Japan1; CID+3540 -6D6E E0101; Adobe-Japan1; CID+14004 -6D6E E0102; Hanyo-Denshi; JA4166 -6D6E E0102; Moji_Joho; MJ015362 -6D6E E0103; Hanyo-Denshi; JTB42E -6D6E E0103; Moji_Joho; MJ015361 -6D6F E0100; Adobe-Japan1; CID+8517 -6D70 E0100; Adobe-Japan1; CID+17935 -6D74 E0100; Adobe-Japan1; CID+3915 -6D77 E0100; Adobe-Japan1; CID+13327 -6D77 E0101; Adobe-Japan1; CID+1410 -6D77 E0102; Hanyo-Denshi; JA1904 -6D77 E0103; Hanyo-Denshi; JC8673 -6D78 E0100; Adobe-Japan1; CID+2561 -6D78 E0101; Adobe-Japan1; CID+13853 -6D78 E0102; Hanyo-Denshi; JA3127 -6D78 E0102; Moji_Joho; MJ015373 -6D78 E0103; Hanyo-Denshi; JTB42F -6D78 E0103; Moji_Joho; MJ015372 -6D79 E0100; Adobe-Japan1; CID+5426 -6D7C E0100; Adobe-Japan1; CID+19493 -6D80 E0100; Adobe-Japan1; CID+17936 -6D81 E0100; Adobe-Japan1; CID+17937 -6D82 E0100; Adobe-Japan1; CID+14711 -6D82 E0101; Hanyo-Denshi; JB3938 -6D82 E0102; Hanyo-Denshi; TK01049560 -6D85 E0100; Adobe-Japan1; CID+5431 -6D87 E0100; Adobe-Japan1; CID+8516 -6D88 E0100; Adobe-Japan1; CID+2475 -6D88 E0101; Adobe-Japan1; CID+13836 -6D88 E0102; Hanyo-Denshi; JA3035 -6D88 E0102; Moji_Joho; MJ015391 -6D88 E0103; Hanyo-Denshi; JTB430 -6D88 E0103; Moji_Joho; MJ015390 -6D89 E0100; Adobe-Japan1; CID+13354 -6D8A E0100; Adobe-Japan1; CID+17938 -6D8C E0100; Adobe-Japan1; CID+3866 -6D8D E0100; Adobe-Japan1; CID+17939 -6D8E E0100; Adobe-Japan1; CID+5428 -6D8E E0101; Hanyo-Denshi; JA6223 -6D8E E0101; Moji_Joho; MJ015397 -6D8E E0102; Hanyo-Denshi; FT2279 -6D8E E0102; Moji_Joho; MJ015398 -6D91 E0100; Adobe-Japan1; CID+17940 -6D92 E0100; Adobe-Japan1; CID+21868 -6D93 E0100; Adobe-Japan1; CID+5423 -6D94 E0100; Adobe-Japan1; CID+16936 -6D95 E0100; Adobe-Japan1; CID+5429 -6D96 E0100; Adobe-Japan1; CID+8518 -6D97 E0100; Adobe-Japan1; CID+21869 -6D98 E0100; Adobe-Japan1; CID+17941 -6D99 E0100; Adobe-Japan1; CID+4006 -6D9B E0100; Adobe-Japan1; CID+3181 -6D9C E0100; Adobe-Japan1; CID+3226 -6DA6 E0100; Hanyo-Denshi; JT6DA6 -6DA6 E0101; Hanyo-Denshi; TK01050010 -6DAA E0100; Adobe-Japan1; CID+16937 -6DAB E0100; Adobe-Japan1; CID+17946 -6DAC E0100; Adobe-Japan1; CID+8519 -6DAC E0101; Hanyo-Denshi; JB3947 -6DAC E0101; Moji_Joho; MJ015415 -6DAC E0102; Hanyo-Denshi; JTB43F -6DAC E0102; Moji_Joho; MJ015416 -6DAE E0100; Adobe-Japan1; CID+17947 -6DAF E0100; Adobe-Japan1; CID+1428 -6DB2 E0100; Adobe-Japan1; CID+1271 -6DB4 E0100; Adobe-Japan1; CID+17948 -6DB5 E0100; Adobe-Japan1; CID+5435 -6DB5 E0101; Hanyo-Denshi; JA6230 -6DB5 E0101; Moji_Joho; MJ015425 -6DB5 E0102; Hanyo-Denshi; JTB440 -6DB5 E0102; Moji_Joho; MJ015426 -6DB6 E0100; Hanyo-Denshi; IP6DB6 -6DB6 E0101; Hanyo-Denshi; TK01050980 -6DB7 E0100; Adobe-Japan1; CID+21870 -6DB8 E0100; Adobe-Japan1; CID+5438 -6DB9 E0100; Adobe-Japan1; CID+19494 -6DBC E0100; Adobe-Japan1; CID+3979 -6DBD E0100; Adobe-Japan1; CID+21871 -6DBF E0100; Adobe-Japan1; CID+14712 -6DBF E0101; Hanyo-Denshi; JB3952 -6DBF E0101; Moji_Joho; MJ015436 -6DBF E0102; Hanyo-Denshi; IB2230 -6DBF E0102; Moji_Joho; MJ015438 -6DC0 E0100; Adobe-Japan1; CID+3918 -6DC2 E0100; Adobe-Japan1; CID+17949 -6DC3 E0100; Hanyo-Denshi; IP6DC3 -6DC3 E0100; Moji_Joho; MJ015442 -6DC3 E0101; Hanyo-Denshi; JTB44E -6DC3 E0101; Moji_Joho; MJ015443 -6DC3 E0102; Hanyo-Denshi; JTB450 -6DC3 E0102; Moji_Joho; MJ015444 -6DC4 E0100; Adobe-Japan1; CID+14713 -6DC5 E0100; Adobe-Japan1; CID+5445 -6DC6 E0100; Adobe-Japan1; CID+5439 -6DC7 E0100; Adobe-Japan1; CID+5436 -6DC8 E0100; Adobe-Japan1; CID+17951 -6DCA E0100; Adobe-Japan1; CID+14714 -6DCA E0101; Hanyo-Denshi; JB3955 -6DCA E0101; Moji_Joho; MJ015451 -6DCA E0102; Hanyo-Denshi; JTB446 -6DCA E0102; Moji_Joho; MJ015452 -6DCB E0100; Adobe-Japan1; CID+3996 -6DCC E0100; Adobe-Japan1; CID+5442 -6DCC E0101; Hanyo-Denshi; JA6237 -6DCC E0101; Moji_Joho; MJ015454 -6DCC E0102; Hanyo-Denshi; FT2281 -6DCC E0102; Moji_Joho; MJ015455 -6DCD E0100; Hanyo-Denshi; IP6DCD -6DCD E0101; Hanyo-Denshi; TK01050160 -6DCE E0100; Adobe-Japan1; CID+17952 -6DCF E0100; Adobe-Japan1; CID+8520 -6DCF E0101; Hanyo-Denshi; JB3957 -6DCF E0101; Moji_Joho; MJ015459 -6DCF E0102; Hanyo-Denshi; JTB442 -6DCF E0102; Moji_Joho; MJ015460 -6DD0 E0100; Adobe-Japan1; CID+15414 -6DD1 E0100; Adobe-Japan1; CID+2388 -6DD2 E0100; Adobe-Japan1; CID+5444 -6DD5 E0100; Adobe-Japan1; CID+5449 -6DD6 E0100; Adobe-Japan1; CID+14715 -6DD8 E0100; Adobe-Japan1; CID+3179 -6DD9 E0100; Adobe-Japan1; CID+5447 -6DDA E0100; Adobe-Japan1; CID+13395 -6DDB E0100; Adobe-Japan1; CID+16938 -6DDC E0100; Hanyo-Denshi; IP6DDC -6DDC E0101; Hanyo-Denshi; TK01050170 -6DDD E0100; Adobe-Japan1; CID+16939 -6DDE E0100; Adobe-Japan1; CID+5441 -6DDE E0101; Hanyo-Denshi; JA6236 -6DDE E0101; Moji_Joho; MJ015477 -6DDE E0102; Hanyo-Denshi; FT2280 -6DDE E0102; Moji_Joho; MJ015478 -6DDF E0100; Adobe-Japan1; CID+17953 -6DE0 E0100; Adobe-Japan1; CID+21872 -6DE1 E0100; Adobe-Japan1; CID+2934 -6DE2 E0100; Adobe-Japan1; CID+21873 -6DE4 E0100; Adobe-Japan1; CID+5448 -6DE4 E0101; Adobe-Japan1; CID+20157 -6DE5 E0100; Adobe-Japan1; CID+21874 -6DE6 E0100; Adobe-Japan1; CID+5437 -6DE8 E0100; Adobe-Japan1; CID+5443 -6DE8 E0101; Hanyo-Denshi; JA6238 -6DE8 E0101; Moji_Joho; MJ015488 -6DE8 E0102; Hanyo-Denshi; FT2282 -6DE8 E0102; Moji_Joho; MJ015489 -6DE9 E0100; Adobe-Japan1; CID+14716 -6DEA E0100; Adobe-Japan1; CID+5450 -6DEB E0100; Adobe-Japan1; CID+1216 -6DEB E0101; Adobe-Japan1; CID+7637 -6DEB E0102; Hanyo-Denshi; JA1692 -6DEB E0102; Moji_Joho; MJ015493 -6DEB E0103; Hanyo-Denshi; FT1755 -6DEB E0103; Moji_Joho; MJ015492 -6DEC E0100; Adobe-Japan1; CID+5440 -6DEE E0100; Adobe-Japan1; CID+5451 -6DEF E0100; Adobe-Japan1; CID+21875 -6DF0 E0100; Adobe-Japan1; CID+19495 -6DF1 E0100; Adobe-Japan1; CID+2562 -6DF2 E0100; Adobe-Japan1; CID+8522 -6DF3 E0100; Adobe-Japan1; CID+2409 -6DF3 E0101; Hanyo-Denshi; JA2963 -6DF3 E0102; Hanyo-Denshi; TK01050260 -6DF4 E0100; Adobe-Japan1; CID+21876 -6DF5 E0100; Adobe-Japan1; CID+3573 -6DF5 E0101; Hanyo-Denshi; JA4205 -6DF5 E0101; Moji_Joho; MJ015504 -6DF5 E0102; Hanyo-Denshi; JTB461 -6DF5 E0102; Moji_Joho; MJ059791 -6DF5 E0103; Hanyo-Denshi; JTB43B -6DF5 E0103; Moji_Joho; MJ059782 -6DF5 E0104; Hanyo-Denshi; JTB43C -6DF5 E0104; Moji_Joho; MJ059783 -6DF6 E0100; Adobe-Japan1; CID+17954 -6DF7 E0100; Adobe-Japan1; CID+2078 -6DF8 E0100; Adobe-Japan1; CID+8521 -6DF9 E0100; Adobe-Japan1; CID+5432 -6DF9 E0101; Hanyo-Denshi; JA6227 -6DF9 E0102; Hanyo-Denshi; TK01049810 -6DFA E0100; Adobe-Japan1; CID+5446 -6DFB E0100; Adobe-Japan1; CID+3124 -6DFB E0101; Adobe-Japan1; CID+13948 -6DFB E0102; Hanyo-Denshi; JA3726 -6DFB E0102; Moji_Joho; MJ015511 -6DFB E0103; Hanyo-Denshi; JTB443 -6DFB E0103; Moji_Joho; MJ015512 -6DFC E0100; Adobe-Japan1; CID+8523 -6E00 E0100; Adobe-Japan1; CID+21877 -6E03 E0100; Hanyo-Denshi; IP6E03 -6E03 E0101; Hanyo-Denshi; KS200440 -6E04 E0100; Adobe-Japan1; CID+21878 -6E05 E0100; Adobe-Japan1; CID+2650 -6E05 E0101; Hanyo-Denshi; JA3222 -6E05 E0102; Hanyo-Denshi; TK01050470 -6E07 E0100; Adobe-Japan1; CID+1479 -6E08 E0100; Adobe-Japan1; CID+2113 -6E08 E0101; Adobe-Japan1; CID+20159 -6E09 E0100; Adobe-Japan1; CID+2476 -6E0A E0100; Adobe-Japan1; CID+5434 -6E0B E0100; Adobe-Japan1; CID+2380 -6E13 E0100; Adobe-Japan1; CID+1826 -6E13 E0101; Hanyo-Denshi; JA2344 -6E13 E0102; Hanyo-Denshi; TK01049920 -6E15 E0100; Adobe-Japan1; CID+5433 -6E17 E0100; Adobe-Japan1; CID+14150 -6E19 E0100; Adobe-Japan1; CID+5455 -6E1A E0100; Adobe-Japan1; CID+7700 -6E1A E0101; Adobe-Japan1; CID+2423 -6E1A E0102; Hanyo-Denshi; JA2977 -6E1A E0103; Hanyo-Denshi; JC8687 -6E1A E0104; Hanyo-Denshi; TK01050590 -6E1B E0100; Adobe-Japan1; CID+1902 -6E1D E0100; Adobe-Japan1; CID+5470 -6E1D E0101; Hanyo-Denshi; JA6265 -6E1D E0101; Moji_Joho; MJ015541 -6E1D E0102; Hanyo-Denshi; FT2284 -6E1D E0102; Moji_Joho; MJ015542 -6E1E E0100; Adobe-Japan1; CID+17956 -6E1F E0100; Adobe-Japan1; CID+5464 -6E20 E0100; Adobe-Japan1; CID+1678 -6E20 E0101; Hanyo-Denshi; JA2184 -6E20 E0101; Moji_Joho; MJ015545 -6E20 E0102; Hanyo-Denshi; JTB33C -6E20 E0102; Moji_Joho; MJ015546 -6E21 E0100; Adobe-Japan1; CID+3145 -6E22 E0100; Adobe-Japan1; CID+14717 -6E23 E0100; Adobe-Japan1; CID+5459 -6E23 E0101; Adobe-Japan1; CID+7994 -6E23 E0102; Adobe-Japan1; CID+13558 -6E23 E0103; Hanyo-Denshi; JA6254 -6E23 E0103; Moji_Joho; MJ015549 -6E23 E0104; Hanyo-Denshi; FT1707 -6E23 E0104; Moji_Joho; MJ015550 -6E24 E0100; Adobe-Japan1; CID+5468 -6E25 E0100; Adobe-Japan1; CID+1139 -6E26 E0100; Adobe-Japan1; CID+1236 -6E27 E0100; Adobe-Japan1; CID+8526 -6E27 E0101; Hanyo-Denshi; JB3975 -6E27 E0101; Moji_Joho; MJ015554 -6E27 E0102; Hanyo-Denshi; JTB456 -6E27 E0102; Moji_Joho; MJ015555 -6E29 E0100; Adobe-Japan1; CID+1337 -6E2B E0100; Adobe-Japan1; CID+5461 -6E2C E0100; Adobe-Japan1; CID+2828 -6E2D E0100; Adobe-Japan1; CID+5452 -6E2E E0100; Adobe-Japan1; CID+5454 -6E2E E0101; Hanyo-Denshi; JA6249 -6E2E E0101; Moji_Joho; MJ015562 -6E2E E0102; Hanyo-Denshi; KS200730 -6E2E E0102; Moji_Joho; MJ015563 -6E2F E0100; Adobe-Japan1; CID+2003 -6E2F E0101; Adobe-Japan1; CID+13769 -6E2F E0102; Hanyo-Denshi; JA2533 -6E2F E0102; Moji_Joho; MJ015565 -6E2F E0103; Hanyo-Denshi; JTB44F -6E2F E0103; Moji_Joho; MJ015564 -6E2F E0104; Hanyo-Denshi; JTB447 -6E2F E0104; Moji_Joho; MJ015566 -6E32 E0100; Adobe-Japan1; CID+17958 -6E32 E0101; Hanyo-Denshi; JB3976 -6E32 E0102; Hanyo-Denshi; TK01050460 -6E33 E0100; Moji_Joho; MJ015571 -6E33 E0101; Moji_Joho; MJ015572 -6E34 E0100; Adobe-Japan1; CID+13330 -6E36 E0100; Adobe-Japan1; CID+17955 -6E36 E0101; Hanyo-Denshi; JB3977 -6E36 E0101; Moji_Joho; MJ015575 -6E36 E0102; Hanyo-Denshi; JTB455 -6E36 E0102; Moji_Joho; MJ015576 -6E38 E0100; Adobe-Japan1; CID+5471 -6E39 E0100; Adobe-Japan1; CID+8524 -6E3A E0100; Adobe-Japan1; CID+5466 -6E3B E0100; Adobe-Japan1; CID+21879 -6E3C E0100; Adobe-Japan1; CID+8527 -6E3E E0100; Adobe-Japan1; CID+5458 -6E42 E0100; Adobe-Japan1; CID+15415 -6E43 E0100; Adobe-Japan1; CID+5465 -6E44 E0100; Adobe-Japan1; CID+16940 -6E45 E0100; Adobe-Japan1; CID+19496 -6E48 E0100; Adobe-Japan1; CID+17959 -6E49 E0100; Adobe-Japan1; CID+17960 -6E4A E0100; Adobe-Japan1; CID+3767 -6E4B E0100; Adobe-Japan1; CID+17961 -6E4B E0101; Hanyo-Denshi; JB3985 -6E4B E0102; Hanyo-Denshi; TK01051240 -6E4C E0100; Adobe-Japan1; CID+17962 -6E4D E0100; Adobe-Japan1; CID+5463 -6E4E E0100; Adobe-Japan1; CID+5467 -6E4E E0101; Hanyo-Denshi; JA6262 -6E4E E0102; Hanyo-Denshi; KS200340 -6E4F E0100; Adobe-Japan1; CID+17963 -6E51 E0100; Adobe-Japan1; CID+14718 -6E52 E0100; Adobe-Japan1; CID+21880 -6E52 E0101; Hanyo-Denshi; JB3988 -6E52 E0101; Moji_Joho; MJ015605 -6E52 E0102; Hanyo-Denshi; KS202250 -6E52 E0102; Moji_Joho; MJ015606 -6E53 E0100; Adobe-Japan1; CID+17964 -6E54 E0100; Adobe-Japan1; CID+17965 -6E56 E0100; Adobe-Japan1; CID+1924 -6E57 E0100; Adobe-Japan1; CID+17966 -6E58 E0100; Adobe-Japan1; CID+2477 -6E5B E0100; Adobe-Japan1; CID+2935 -6E5B E0101; Hanyo-Denshi; JA3525 -6E5B E0101; Moji_Joho; MJ015615 -6E5B E0102; Hanyo-Denshi; KS202240 -6E5B E0102; Moji_Joho; MJ015616 -6E5B E0103; Hanyo-Denshi; JTB462 -6E5B E0103; Moji_Joho; MJ059792 -6E5B E0104; Hanyo-Denshi; JTC0BE -6E5B E0104; Moji_Joho; MJ060382 -6E5C E0100; Adobe-Japan1; CID+8525 -6E5D E0100; Adobe-Japan1; CID+21881 -6E5E E0100; Adobe-Japan1; CID+16941 -6E5F E0100; Adobe-Japan1; CID+5457 -6E60 E0100; Hanyo-Denshi; IP6E60 -6E60 E0101; Hanyo-Denshi; TK01050310 -6E61 E0100; Hanyo-Denshi; IP6E61 -6E61 E0101; Hanyo-Denshi; KS201420 -6E62 E0100; Adobe-Japan1; CID+21882 -6E63 E0100; Adobe-Japan1; CID+17967 -6E67 E0100; Adobe-Japan1; CID+3865 -6E67 E0101; Hanyo-Denshi; JA4515 -6E67 E0101; Moji_Joho; MJ015630 -6E67 E0102; Hanyo-Denshi; KS202140 -6E67 E0102; Moji_Joho; MJ015631 -6E68 E0100; Adobe-Japan1; CID+21883 -6E6B E0100; Adobe-Japan1; CID+5460 -6E6E E0100; Adobe-Japan1; CID+5453 -6E6E E0101; Adobe-Japan1; CID+7837 -6E6E E0102; Hanyo-Denshi; JA6248 -6E6E E0102; Moji_Joho; MJ015639 -6E6E E0103; Hanyo-Denshi; JTB452 -6E6E E0103; Moji_Joho; MJ015638 -6E6E E0104; Moji_Joho; MJ015640 -6E6F E0100; Adobe-Japan1; CID+3180 -6E6F E0101; Hanyo-Denshi; JA3782 -6E6F E0102; Hanyo-Denshi; TK01050240 -6E71 E0100; Hanyo-Denshi; IP6E71 -6E71 E0101; Hanyo-Denshi; KS201650 -6E72 E0100; Adobe-Japan1; CID+5456 -6E72 E0101; Adobe-Japan1; CID+20160 -6E72 E0102; Hanyo-Denshi; JA6251 -6E72 E0102; Moji_Joho; MJ015646 -6E72 E0103; Hanyo-Denshi; FT2283 -6E72 E0103; Moji_Joho; MJ015647 -6E73 E0100; Adobe-Japan1; CID+19497 -6E74 E0100; Hanyo-Denshi; IP6E74 -6E74 E0100; Moji_Joho; MJ015649 -6E74 E0101; Hanyo-Denshi; JTB44B -6E74 E0101; Moji_Joho; MJ015650 -6E76 E0100; Adobe-Japan1; CID+5462 -6E7B E0100; Adobe-Japan1; CID+19498 -6E7C E0100; Hanyo-Denshi; IP6E7C -6E7C E0100; Moji_Joho; MJ015657 -6E7C E0101; Hanyo-Denshi; KS202220 -6E7C E0101; Moji_Joho; MJ015658 -6E7D E0100; Adobe-Japan1; CID+19499 -6E7E E0100; Adobe-Japan1; CID+4087 -6E7E E0101; Adobe-Japan1; CID+13519 -6E7E E0102; Moji_Joho; MJ015660 -6E7E E0103; Moji_Joho; MJ015661 -6E7F E0100; Adobe-Japan1; CID+2282 -6E80 E0100; Adobe-Japan1; CID+3756 -6E80 E0101; Hanyo-Denshi; JA4394 -6E80 E0101; Moji_Joho; MJ015663 -6E80 E0102; Hanyo-Denshi; JTB463 -6E80 E0102; Moji_Joho; MJ015664 -6E80 E0103; Hanyo-Denshi; TK01050820 -6E82 E0100; Adobe-Japan1; CID+5472 -6E89 E0100; Adobe-Japan1; CID+19500 -6E8C E0100; Adobe-Japan1; CID+3394 -6E8D E0100; Adobe-Japan1; CID+21884 -6E8D E0101; Hanyo-Denshi; JB4007 -6E8D E0102; Hanyo-Denshi; TK01051740 -6E8F E0100; Adobe-Japan1; CID+5484 -6E8F E0101; Hanyo-Denshi; JA6279 -6E8F E0101; Moji_Joho; MJ015670 -6E8F E0102; Hanyo-Denshi; FT2289 -6E8F E0102; Moji_Joho; MJ015671 -6E90 E0100; Adobe-Japan1; CID+1903 -6E90 E0101; Hanyo-Denshi; JA2427 -6E90 E0101; Moji_Joho; MJ015672 -6E90 E0102; Hanyo-Denshi; JTB45D -6E90 E0102; Moji_Joho; MJ059789 -6E93 E0100; Adobe-Japan1; CID+17969 -6E93 E0101; Hanyo-Denshi; JB4008 -6E93 E0101; Moji_Joho; MJ015675 -6E93 E0102; Hanyo-Denshi; JTB472 -6E93 E0102; Moji_Joho; MJ015676 -6E96 E0100; Adobe-Japan1; CID+2410 -6E98 E0100; Adobe-Japan1; CID+5474 -6E99 E0100; Adobe-Japan1; CID+21885 -6E9C E0100; Adobe-Japan1; CID+3959 -6E9D E0100; Adobe-Japan1; CID+2004 -6E9D E0101; Adobe-Japan1; CID+7681 -6E9D E0102; Hanyo-Denshi; JA2534 -6E9D E0102; Moji_Joho; MJ015687 -6E9D E0103; Hanyo-Denshi; FT1803 -6E9D E0103; Moji_Joho; MJ015686 -6E9F E0100; Adobe-Japan1; CID+5487 -6EA0 E0100; Adobe-Japan1; CID+21886 -6EA2 E0100; Adobe-Japan1; CID+1202 -6EA2 E0101; Adobe-Japan1; CID+7635 -6EA2 E0102; Adobe-Japan1; CID+21071 -6EA2 E0103; Hanyo-Denshi; JA1678 -6EA2 E0103; Moji_Joho; MJ015693 -6EA2 E0104; Hanyo-Denshi; FT2910 -6EA2 E0104; Moji_Joho; MJ015692 -6EA2 E0105; Hanyo-Denshi; JTB46E -6EA2 E0105; Moji_Joho; MJ015694 -6EA5 E0100; Adobe-Japan1; CID+5485 -6EA5 E0101; Hanyo-Denshi; JA6280 -6EA5 E0101; Moji_Joho; MJ015697 -6EA5 E0102; Hanyo-Denshi; FT2290 -6EA5 E0102; Moji_Joho; MJ015698 -6EA7 E0100; Adobe-Japan1; CID+17970 -6EAA E0100; Adobe-Japan1; CID+5473 -6EAA E0101; Hanyo-Denshi; JA6268 -6EAA E0101; Moji_Joho; MJ015703 -6EAA E0102; Hanyo-Denshi; FT2285 -6EAA E0102; Moji_Joho; MJ015704 -6EAB E0100; Adobe-Japan1; CID+13324 -6EAD E0100; Adobe-Japan1; CID+21887 -6EAE E0100; Adobe-Japan1; CID+21888 -6EAF E0100; Adobe-Japan1; CID+5479 -6EB1 E0100; Adobe-Japan1; CID+16942 -6EB2 E0100; Adobe-Japan1; CID+5481 -6EB2 E0101; Hanyo-Denshi; JA6276 -6EB2 E0101; Moji_Joho; MJ015713 -6EB2 E0102; Hanyo-Denshi; JTB43E -6EB2 E0102; Moji_Joho; MJ015712 -6EB2 E0103; Hanyo-Denshi; FT2286 -6EB2 E0103; Moji_Joho; MJ015714 -6EB2 E0104; Hanyo-Denshi; JTB454 -6EB2 E0104; Moji_Joho; MJ015715 -6EB3 E0100; Adobe-Japan1; CID+21889 -6EB4 E0100; Adobe-Japan1; CID+17971 -6EB6 E0100; Adobe-Japan1; CID+3897 -6EB7 E0100; Adobe-Japan1; CID+5476 -6EBA E0100; Adobe-Japan1; CID+3112 -6EBA E0101; Adobe-Japan1; CID+7750 -6EBA E0102; Hanyo-Denshi; JA3714 -6EBA E0102; Moji_Joho; MJ015724 -6EBA E0103; Hanyo-Denshi; HG1649 -6EBA E0103; Moji_Joho; MJ015723 -6EBB E0100; Adobe-Japan1; CID+21890 -6EBC E0100; Adobe-Japan1; CID+19501 -6EBD E0100; Adobe-Japan1; CID+5478 -6EBF E0100; Adobe-Japan1; CID+8528 -6EBF E0101; Hanyo-Denshi; JB4017 -6EBF E0101; Moji_Joho; MJ015729 -6EBF E0102; Hanyo-Denshi; JTB47C -6EBF E0102; Moji_Joho; MJ015730 -6EC0 E0100; Adobe-Japan1; CID+21891 -6EC1 E0100; Adobe-Japan1; CID+16943 -6EC2 E0100; Adobe-Japan1; CID+5486 -6EC2 E0101; Hanyo-Denshi; JA6281 -6EC2 E0101; Moji_Joho; MJ015733 -6EC2 E0102; Hanyo-Denshi; KS203830S -6EC2 E0102; Moji_Joho; MJ057962 -6EC3 E0100; Adobe-Japan1; CID+17972 -6EC4 E0100; Adobe-Japan1; CID+5480 -6EC5 E0100; Adobe-Japan1; CID+3795 -6EC7 E0100; Adobe-Japan1; CID+14719 -6EC7 E0101; Hanyo-Denshi; JB4021 -6EC7 E0101; Moji_Joho; MJ015738 -6EC7 E0102; Hanyo-Denshi; JTB476 -6EC7 E0102; Moji_Joho; MJ015739 -6EC8 E0100; Adobe-Japan1; CID+21892 -6EC9 E0100; Adobe-Japan1; CID+5475 -6ECA E0100; Adobe-Japan1; CID+14720 -6ECB E0100; Adobe-Japan1; CID+2254 -6ECB E0101; Adobe-Japan1; CID+13801 -6ECB E0102; Adobe-Japan1; CID+20161 -6ECB E0103; Hanyo-Denshi; JA2802 -6ECB E0103; Moji_Joho; MJ015743 -6ECB E0104; Hanyo-Denshi; JTB46C -6ECB E0104; Moji_Joho; MJ015746 -6ECB E0105; Hanyo-Denshi; JTB458 -6ECB E0105; Moji_Joho; MJ015744 -6ECB E0106; Hanyo-Denshi; JTB46B -6ECB E0106; Moji_Joho; MJ015745 -6ECC E0100; Adobe-Japan1; CID+5499 -6ECD E0100; Adobe-Japan1; CID+21893 -6ECE E0100; Adobe-Japan1; CID+14721 -6ECF E0100; Adobe-Japan1; CID+21894 -6ED1 E0100; Adobe-Japan1; CID+1480 -6ED3 E0100; Adobe-Japan1; CID+5477 -6ED4 E0100; Adobe-Japan1; CID+5482 -6ED4 E0101; Hanyo-Denshi; JA6277 -6ED4 E0101; Moji_Joho; MJ015755 -6ED4 E0102; Hanyo-Denshi; FT2287 -6ED4 E0102; Moji_Joho; MJ015756 -6ED5 E0100; Adobe-Japan1; CID+5483 -6ED5 E0101; Adobe-Japan1; CID+20162 -6ED5 E0102; Hanyo-Denshi; JA6278 -6ED5 E0102; Moji_Joho; MJ015758 -6ED5 E0103; Hanyo-Denshi; JTB484 -6ED5 E0103; Moji_Joho; MJ015757 -6ED5 E0104; Hanyo-Denshi; FT2288 -6ED5 E0104; Moji_Joho; MJ015759 -6ED9 E0100; Adobe-Japan1; CID+15416 -6EDA E0100; Adobe-Japan1; CID+19502 -6EDB E0100; Adobe-Japan1; CID+19503 -6EDB E0101; Adobe-Japan1; CID+20163 -6EDB E0102; Hanyo-Denshi; IP6EDB -6EDB E0102; Moji_Joho; MJ015766 -6EDB E0103; Hanyo-Denshi; KS201980 -6EDB E0103; Moji_Joho; MJ057957 -6EDB E0104; Hanyo-Denshi; TK01050730 -6EDB E0105; Hanyo-Denshi; TK01050870 -6EDD E0100; Adobe-Japan1; CID+2892 -6EDE E0100; Adobe-Japan1; CID+2874 -6EE6 E0100; Adobe-Japan1; CID+15396 -6EEB E0100; Adobe-Japan1; CID+17974 -6EEC E0100; Adobe-Japan1; CID+5491 -6EEC E0101; Adobe-Japan1; CID+7995 -6EEC E0102; Hanyo-Denshi; JA6286 -6EEC E0102; Moji_Joho; MJ015775 -6EEC E0103; Hanyo-Denshi; JTB48C -6EEC E0103; Moji_Joho; MJ015774 -6EED E0100; Adobe-Japan1; CID+21895 -6EEE E0100; Adobe-Japan1; CID+21896 -6EEF E0100; Adobe-Japan1; CID+5497 -6EF0 E0100; Hanyo-Denshi; IP6EF0 -6EF0 E0100; Moji_Joho; MJ015779 -6EF0 E0101; Hanyo-Denshi; JTB4DE -6EF0 E0101; Moji_Joho; MJ015780 -6EF2 E0100; Adobe-Japan1; CID+5495 -6EF4 E0100; Adobe-Japan1; CID+3107 -6EF4 E0101; Hanyo-Denshi; JA3709 -6EF4 E0101; Moji_Joho; MJ015783 -6EF4 E0102; Hanyo-Denshi; JTB489 -6EF4 E0102; Moji_Joho; MJ015784 -6EF7 E0100; Adobe-Japan1; CID+5502 -6EF8 E0100; Adobe-Japan1; CID+5492 -6EF9 E0100; Adobe-Japan1; CID+17975 -6EFB E0100; Adobe-Japan1; CID+17976 -6EFD E0100; Adobe-Japan1; CID+14722 -6EFE E0100; Adobe-Japan1; CID+5493 -6EFE E0101; Adobe-Japan1; CID+13560 -6EFE E0102; Hanyo-Denshi; JA6288 -6EFE E0102; Moji_Joho; MJ015794 -6EFE E0103; Hanyo-Denshi; FT1709 -6EFE E0103; Moji_Joho; MJ015795 -6EFF E0100; Adobe-Japan1; CID+5469 -6EFF E0101; Hanyo-Denshi; JA6264 -6EFF E0101; Moji_Joho; MJ015796 -6EFF E0102; Hanyo-Denshi; JTB499 -6EFF E0102; Moji_Joho; MJ059813 -6EFF E0103; Hanyo-Denshi; JTB49A -6EFF E0103; Moji_Joho; MJ015797 -6EFF E0104; Hanyo-Denshi; JTB49BS -6EFF E0104; Moji_Joho; MJ059814 -6EFF E0105; Hanyo-Denshi; TK01052000 -6F01 E0100; Adobe-Japan1; CID+1683 -6F01 E0101; Hanyo-Denshi; JA2189 -6F01 E0101; Moji_Joho; MJ015800 -6F01 E0102; Hanyo-Denshi; IB0731 -6F01 E0102; Moji_Joho; MJ015799 -6F02 E0100; Adobe-Japan1; CID+3500 -6F04 E0100; Adobe-Japan1; CID+21897 -6F06 E0100; Adobe-Japan1; CID+2283 -6F08 E0100; Adobe-Japan1; CID+21898 -6F09 E0100; Adobe-Japan1; CID+2057 -6F0A E0100; Adobe-Japan1; CID+17977 -6F0C E0100; Adobe-Japan1; CID+17978 -6F0C E0101; Hanyo-Denshi; JB4036 -6F0C E0102; Hanyo-Denshi; TK01051180 -6F0D E0100; Adobe-Japan1; CID+21899 -6F0F E0100; Adobe-Japan1; CID+4057 -6F10 E0100; Adobe-Japan1; CID+16944 -6F11 E0100; Adobe-Japan1; CID+5489 -6F11 E0101; Adobe-Japan1; CID+13559 -6F11 E0102; Adobe-Japan1; CID+14149 -6F11 E0103; Hanyo-Denshi; JA6284 -6F11 E0103; Moji_Joho; MJ015818 -6F11 E0104; Hanyo-Denshi; JTB478S -6F11 E0104; Moji_Joho; MJ015820 -6F11 E0105; Hanyo-Denshi; JTB48A -6F11 E0105; Moji_Joho; MJ015816 -6F11 E0106; Hanyo-Denshi; JTB48BS -6F11 E0106; Moji_Joho; MJ015817 -6F11 E0107; Hanyo-Denshi; JTB4AD -6F11 E0107; Moji_Joho; MJ015819 -6F11 E0108; Hanyo-Denshi; JTB4AE -6F11 E0108; Moji_Joho; MJ015821 -6F11 E0109; Moji_Joho; MJ015822 -6F13 E0100; Adobe-Japan1; CID+5501 -6F13 E0101; Hanyo-Denshi; JA6302 -6F13 E0101; Moji_Joho; MJ015824 -6F13 E0102; Hanyo-Denshi; KS205370 -6F13 E0102; Moji_Joho; MJ057964 -6F14 E0100; Adobe-Japan1; CID+1291 -6F15 E0100; Adobe-Japan1; CID+2792 -6F16 E0100; Adobe-Japan1; CID+21900 -6F18 E0100; Adobe-Japan1; CID+17979 -6F19 E0100; Hanyo-Denshi; IP6F19 -6F19 E0101; Hanyo-Denshi; TK01050380 -6F19 E0102; Hanyo-Denshi; TK01052660 -6F1A E0100; Adobe-Japan1; CID+14723 -6F1A E0101; Hanyo-Denshi; JB4040 -6F1A E0101; Moji_Joho; MJ015831 -6F1A E0102; Hanyo-Denshi; KS205350 -6F1A E0102; Moji_Joho; MJ015832 -6F1B E0100; Adobe-Japan1; CID+21901 -6F20 E0100; Adobe-Japan1; CID+3375 -6F20 E0101; Hanyo-Denshi; JA3989 -6F20 E0101; Moji_Joho; MJ015838 -6F20 E0102; Hanyo-Denshi; KS204670 -6F20 E0102; Moji_Joho; MJ015839 -6F22 E0100; Adobe-Japan1; CID+1533 -6F22 E0101; Adobe-Japan1; CID+13332 -6F22 E0102; Hanyo-Denshi; JA2033 -6F22 E0102; Moji_Joho; MJ015841 -6F22 E0103; Hanyo-Denshi; JC8705 -6F22 E0104; Hanyo-Denshi; KS552580 -6F22 E0105; Hanyo-Denshi; TK01051810 -6F22 E0106; Hanyo-Denshi; TK01051860 -6F22 E0107; Moji_Joho; MJ015842 -6F23 E0100; Adobe-Japan1; CID+7809 -6F23 E0101; Adobe-Japan1; CID+4034 -6F23 E0102; Hanyo-Denshi; JA4690 -6F23 E0102; Moji_Joho; MJ015844 -6F23 E0103; Hanyo-Denshi; FT1937 -6F23 E0103; Moji_Joho; MJ015845 -6F25 E0100; Adobe-Japan1; CID+17980 -6F26 E0100; Adobe-Japan1; CID+19504 -6F28 E0100; Hanyo-Denshi; IB0733 -6F28 E0100; Moji_Joho; MJ015850 -6F28 E0101; Hanyo-Denshi; IP6F28 -6F28 E0101; Moji_Joho; MJ015851 -6F29 E0100; Adobe-Japan1; CID+19505 -6F2A E0100; Adobe-Japan1; CID+14724 -6F2B E0100; Adobe-Japan1; CID+3757 -6F2B E0101; Hanyo-Denshi; JA4401 -6F2B E0101; Moji_Joho; MJ015855 -6F2B E0102; Hanyo-Denshi; KS204820 -6F2B E0102; Moji_Joho; MJ015854 -6F2C E0100; Adobe-Japan1; CID+3054 -6F2D E0100; Adobe-Japan1; CID+21903 -6F2D E0101; Hanyo-Denshi; JB4051 -6F2D E0101; Moji_Joho; MJ015857 -6F2D E0102; Hanyo-Denshi; JTB4BA -6F2D E0102; Moji_Joho; MJ015858 -6F2F E0100; Adobe-Japan1; CID+14725 -6F30 E0100; Adobe-Japan1; CID+19506 -6F31 E0100; Adobe-Japan1; CID+5496 -6F32 E0100; Adobe-Japan1; CID+5498 -6F33 E0100; Adobe-Japan1; CID+14726 -6F33 E0101; Hanyo-Denshi; JB4047 -6F33 E0101; Moji_Joho; MJ015864 -6F33 E0102; Hanyo-Denshi; KS205330 -6F33 E0102; Moji_Joho; MJ015865 -6F35 E0100; Adobe-Japan1; CID+17973 -6F36 E0100; Adobe-Japan1; CID+17981 -6F38 E0100; Adobe-Japan1; CID+2740 -6F3B E0100; Adobe-Japan1; CID+21902 -6F3B E0101; Hanyo-Denshi; JB4049 -6F3B E0101; Moji_Joho; MJ015873 -6F3B E0102; Hanyo-Denshi; JTB496 -6F3B E0102; Moji_Joho; MJ015874 -6F3B E0103; Hanyo-Denshi; JTB497 -6F3B E0103; Moji_Joho; MJ015875 -6F3C E0100; Adobe-Japan1; CID+17982 -6F3D E0100; Hanyo-Denshi; IP6F3D -6F3D E0101; Hanyo-Denshi; TK01052430 -6F3E E0100; Adobe-Japan1; CID+5500 -6F3E E0101; Adobe-Japan1; CID+13561 -6F3E E0102; Hanyo-Denshi; JA6301 -6F3E E0102; Moji_Joho; MJ015879 -6F3E E0103; Hanyo-Denshi; FT1710 -6F3E E0103; Moji_Joho; MJ015880 -6F3F E0100; Adobe-Japan1; CID+5494 -6F41 E0100; Adobe-Japan1; CID+5488 -6F45 E0100; Adobe-Japan1; CID+1535 -6F4F E0100; Adobe-Japan1; CID+21904 -6F51 E0100; Adobe-Japan1; CID+7776 -6F51 E0101; Adobe-Japan1; CID+13982 -6F52 E0100; Adobe-Japan1; CID+17984 -6F53 E0100; Adobe-Japan1; CID+21905 -6F53 E0101; Hanyo-Denshi; JB4055 -6F53 E0102; Hanyo-Denshi; TK01051730 -6F53 E0103; Hanyo-Denshi; TK01052580 -6F54 E0100; Adobe-Japan1; CID+1855 -6F54 E0101; Adobe-Japan1; CID+13744 -6F54 E0102; Hanyo-Denshi; JA2373 -6F54 E0102; Moji_Joho; MJ015897 -6F54 E0103; Hanyo-Denshi; KS207050 -6F54 E0103; Moji_Joho; MJ015898 -6F54 E0104; Hanyo-Denshi; KS205610 -6F54 E0104; Moji_Joho; MJ015896 -6F54 E0105; Hanyo-Denshi; JTB4A9 -6F54 E0105; Moji_Joho; MJ015899 -6F57 E0100; Adobe-Japan1; CID+17985 -6F58 E0100; Adobe-Japan1; CID+5514 -6F59 E0100; Adobe-Japan1; CID+16945 -6F5A E0100; Adobe-Japan1; CID+14727 -6F5B E0100; Adobe-Japan1; CID+5509 -6F5B E0101; Adobe-Japan1; CID+20164 -6F5B E0102; Adobe-Japan1; CID+20165 -6F5B E0103; Hanyo-Denshi; JA6310 -6F5B E0103; Moji_Joho; MJ015907 -6F5B E0104; Hanyo-Denshi; JTB4DC -6F5B E0104; Moji_Joho; MJ015910 -6F5B E0105; Hanyo-Denshi; JTB4D4 -6F5B E0105; Moji_Joho; MJ015909 -6F5B E0106; Hanyo-Denshi; JTB4C3 -6F5B E0106; Moji_Joho; MJ015908 -6F5B E0107; Moji_Joho; MJ015911 -6F5C E0100; Adobe-Japan1; CID+2716 -6F5D E0100; Adobe-Japan1; CID+21906 -6F5E E0100; Adobe-Japan1; CID+14728 -6F5F E0100; Adobe-Japan1; CID+1473 -6F60 E0100; Adobe-Japan1; CID+17986 -6F61 E0100; Adobe-Japan1; CID+16946 -6F62 E0100; Adobe-Japan1; CID+14729 -6F62 E0101; Hanyo-Denshi; JB4062 -6F62 E0102; Hanyo-Denshi; TK01051820 -6F62 E0103; Hanyo-Denshi; TK01052400 -6F64 E0100; Adobe-Japan1; CID+2411 -6F64 E0101; Adobe-Japan1; CID+20166 -6F64 E0102; Hanyo-Denshi; JA2965 -6F64 E0102; Moji_Joho; MJ015922 -6F64 E0103; Hanyo-Denshi; JTB4CB -6F64 E0103; Moji_Joho; MJ015923 -6F64 E0104; Hanyo-Denshi; TK01052650 -6F66 E0100; Adobe-Japan1; CID+5518 -6F68 E0100; Adobe-Japan1; CID+17987 -6F6B E0100; Hanyo-Denshi; KS205960 -6F6B E0101; Hanyo-Denshi; TK01052830 -6F6C E0100; Adobe-Japan1; CID+21907 -6F6D E0100; Adobe-Japan1; CID+5511 -6F6D E0101; Hanyo-Denshi; JA6312 -6F6D E0101; Moji_Joho; MJ015935 -6F6D E0102; Hanyo-Denshi; JTB4B0 -6F6D E0102; Moji_Joho; MJ015934 -6F6D E0103; Hanyo-Denshi; JTB4B1 -6F6D E0103; Moji_Joho; MJ059825 -6F6E E0100; Adobe-Japan1; CID+13932 -6F6E E0101; Adobe-Japan1; CID+3016 -6F6E E0102; Hanyo-Denshi; JA3612 -6F6E E0102; Moji_Joho; MJ015937 -6F6E E0103; Hanyo-Denshi; JTB4B2 -6F6E E0103; Moji_Joho; MJ015936 -6F6F E0100; Adobe-Japan1; CID+5508 -6F6F E0101; Hanyo-Denshi; JA6309 -6F6F E0101; Moji_Joho; MJ015938 -6F6F E0102; Hanyo-Denshi; FT2301 -6F6F E0102; Moji_Joho; MJ015939 -6F70 E0100; Adobe-Japan1; CID+3061 -6F74 E0100; Adobe-Japan1; CID+5543 -6F74 E0101; Adobe-Japan1; CID+20167 -6F74 E0102; Hanyo-Denshi; JA6344 -6F74 E0102; Moji_Joho; MJ015944 -6F74 E0103; Hanyo-Denshi; FT2311 -6F74 E0103; Moji_Joho; MJ015945 -6F78 E0100; Adobe-Japan1; CID+5505 -6F78 E0101; Hanyo-Denshi; JA6306 -6F78 E0101; Moji_Joho; MJ015949 -6F78 E0102; Hanyo-Denshi; JTB4B5 -6F78 E0102; Moji_Joho; MJ015950 -6F7A E0100; Adobe-Japan1; CID+5504 -6F7C E0100; Adobe-Japan1; CID+5513 -6F7C E0101; Hanyo-Denshi; JA6314 -6F7C E0101; Moji_Joho; MJ015954 -6F7C E0102; Hanyo-Denshi; KS207110 -6F7C E0102; Moji_Joho; MJ015955 -6F7D E0100; Adobe-Japan1; CID+14730 -6F7E E0100; Adobe-Japan1; CID+16947 -6F7E E0101; Hanyo-Denshi; JB4066 -6F7E E0101; Moji_Joho; MJ015958 -6F7E E0102; Hanyo-Denshi; JTB4B3 -6F7E E0102; Moji_Joho; MJ015959 -6F7E E0103; Moji_Joho; MJ015957 -6F7F E0100; Moji_Joho; MJ015960 -6F7F E0101; Moji_Joho; MJ015961 -6F80 E0100; Adobe-Japan1; CID+5507 -6F80 E0101; Hanyo-Denshi; JA6308 -6F80 E0101; Moji_Joho; MJ015962 -6F80 E0102; Hanyo-Denshi; FT2294 -6F80 E0102; Moji_Joho; MJ015964 -6F80 E0103; Hanyo-Denshi; KS208370 -6F80 E0103; Moji_Joho; MJ015963 -6F81 E0100; Adobe-Japan1; CID+5506 -6F82 E0100; Adobe-Japan1; CID+5512 -6F82 E0101; Hanyo-Denshi; JA6313 -6F82 E0101; Moji_Joho; MJ015966 -6F82 E0102; Hanyo-Denshi; FT2302S -6F82 E0102; Moji_Joho; MJ015968 -6F82 E0103; Hanyo-Denshi; JTB4B9S -6F82 E0103; Moji_Joho; MJ015967 -6F83 E0100; Adobe-Japan1; CID+21908 -6F84 E0100; Adobe-Japan1; CID+2629 -6F86 E0100; Adobe-Japan1; CID+5503 -6F87 E0100; Adobe-Japan1; CID+19507 -6F88 E0100; Adobe-Japan1; CID+8529 -6F8B E0100; Adobe-Japan1; CID+14731 -6F8C E0100; Adobe-Japan1; CID+16948 -6F8D E0100; Adobe-Japan1; CID+14732 -6F8E E0100; Adobe-Japan1; CID+5515 -6F90 E0100; Adobe-Japan1; CID+17988 -6F91 E0100; Adobe-Japan1; CID+5516 -6F92 E0100; Adobe-Japan1; CID+14733 -6F93 E0100; Adobe-Japan1; CID+21909 -6F94 E0100; Adobe-Japan1; CID+14734 -6F94 E0101; Hanyo-Denshi; JB4076 -6F94 E0102; Hanyo-Denshi; TK01052480 -6F96 E0100; Adobe-Japan1; CID+17989 -6F97 E0100; Adobe-Japan1; CID+1534 -6F98 E0100; Adobe-Japan1; CID+13884 -6F98 E0101; Adobe-Japan1; CID+14151 -6F98 E0102; Hanyo-Denshi; JD7924 -6F98 E0102; Moji_Joho; MJ015992 -6F98 E0103; Hanyo-Denshi; KS206230 -6F98 E0103; Moji_Joho; MJ015991 -6F9A E0100; Adobe-Japan1; CID+14735 -6F9A E0101; Hanyo-Denshi; JB4078 -6F9A E0101; Moji_Joho; MJ015993 -6F9A E0102; Hanyo-Denshi; JTC0BF -6F9A E0103; Moji_Joho; MJ015994 -6F9D E0100; Adobe-Japan1; CID+19508 -6F9F E0100; Adobe-Japan1; CID+17991 -6FA0 E0100; Adobe-Japan1; CID+16949 -6FA0 E0101; Hanyo-Denshi; JB4080 -6FA0 E0101; Moji_Joho; MJ015997 -6FA0 E0102; Hanyo-Denshi; KS208410 -6FA0 E0102; Moji_Joho; MJ015998 -6FA1 E0100; Adobe-Japan1; CID+5521 -6FA1 E0101; Hanyo-Denshi; JA6322 -6FA1 E0102; Hanyo-Denshi; TK01052380 -6FA3 E0100; Adobe-Japan1; CID+5520 -6FA4 E0100; Adobe-Japan1; CID+5522 -6FA4 E0101; Hanyo-Denshi; JA6323 -6FA4 E0101; Moji_Joho; MJ016002 -6FA4 E0102; Hanyo-Denshi; JTB4EE -6FA4 E0102; Moji_Joho; MJ016004 -6FA4 E0103; Hanyo-Denshi; JTB4C9 -6FA4 E0103; Moji_Joho; MJ016003 -6FA5 E0100; Adobe-Japan1; CID+17992 -6FA6 E0100; Adobe-Japan1; CID+21910 -6FA7 E0100; Adobe-Japan1; CID+14736 -6FA8 E0100; Adobe-Japan1; CID+14737 -6FAA E0100; Adobe-Japan1; CID+5525 -6FAB E0100; Hanyo-Denshi; IP6FAB -6FAB E0100; Moji_Joho; MJ016011 -6FAB E0101; Hanyo-Denshi; JTB4C6 -6FAB E0101; Moji_Joho; MJ016012 -6FAB E0102; Hanyo-Denshi; JTB4C7 -6FAB E0102; Moji_Joho; MJ016014 -6FAB E0103; Hanyo-Denshi; KS208420 -6FAB E0103; Moji_Joho; MJ016013 -6FAE E0100; Adobe-Japan1; CID+19509 -6FAF E0100; Adobe-Japan1; CID+17993 -6FAF E0101; Moji_Joho; MJ016018 -6FAF E0102; Moji_Joho; MJ016019 -6FB0 E0100; Adobe-Japan1; CID+21911 -6FB1 E0100; Adobe-Japan1; CID+3133 -6FB3 E0100; Adobe-Japan1; CID+5519 -6FB3 E0101; Hanyo-Denshi; JA6320 -6FB3 E0101; Moji_Joho; MJ016023 -6FB3 E0102; Hanyo-Denshi; FT2304 -6FB3 E0102; Moji_Joho; MJ016024 -6FB5 E0100; Adobe-Japan1; CID+8530 -6FB6 E0100; Adobe-Japan1; CID+14738 -6FB7 E0100; Adobe-Japan1; CID+19510 -6FB7 E0101; Hanyo-Denshi; IP6FB7 -6FB7 E0101; Moji_Joho; MJ016028 -6FB7 E0102; Hanyo-Denshi; KS208400 -6FB7 E0102; Moji_Joho; MJ016029 -6FB9 E0100; Adobe-Japan1; CID+5523 -6FBC E0100; Adobe-Japan1; CID+16950 -6FBE E0100; Adobe-Japan1; CID+17990 -6FBE E0101; Hanyo-Denshi; JD7928 -6FBE E0101; Moji_Joho; MJ016037 -6FBE E0102; Hanyo-Denshi; IB0734 -6FBE E0102; Moji_Joho; MJ016036 -6FC0 E0100; Adobe-Japan1; CID+1849 -6FC1 E0100; Adobe-Japan1; CID+2905 -6FC2 E0100; Adobe-Japan1; CID+5517 -6FC2 E0101; Hanyo-Denshi; JA6318 -6FC2 E0101; Moji_Joho; MJ016041 -6FC2 E0102; Hanyo-Denshi; JTB4CE -6FC2 E0102; Moji_Joho; MJ016042 -6FC3 E0100; Adobe-Japan1; CID+3313 -6FC4 E0100; Hanyo-Denshi; IB0735 -6FC4 E0100; Moji_Joho; MJ016044 -6FC4 E0101; Hanyo-Denshi; IP6FC4 -6FC4 E0101; Moji_Joho; MJ016045 -6FC5 E0100; Adobe-Japan1; CID+21912 -6FC6 E0100; Adobe-Japan1; CID+5524 -6FC6 E0101; Hanyo-Denshi; JA6325 -6FC6 E0101; Moji_Joho; MJ016047 -6FC6 E0102; Hanyo-Denshi; JTB4C8 -6FC6 E0102; Moji_Joho; MJ016048 -6FC7 E0100; Adobe-Japan1; CID+16951 -6FC8 E0100; Adobe-Japan1; CID+17995 -6FC8 E0101; Hanyo-Denshi; JB4093 -6FC8 E0101; Moji_Joho; MJ016050 -6FC8 E0102; Hanyo-Denshi; JTB4C1 -6FC8 E0102; Moji_Joho; MJ016051 -6FC9 E0100; Adobe-Japan1; CID+17996 -6FCA E0100; Adobe-Japan1; CID+16952 -6FD4 E0100; Adobe-Japan1; CID+5529 -6FD5 E0100; Adobe-Japan1; CID+5527 -6FD8 E0100; Adobe-Japan1; CID+5530 -6FD8 E0101; Hanyo-Denshi; JA6331 -6FD8 E0101; Moji_Joho; MJ016064 -6FD8 E0102; Hanyo-Denshi; FT2305 -6FD8 E0102; Moji_Joho; MJ016065 -6FDA E0100; Adobe-Japan1; CID+14739 -6FDB E0100; Adobe-Japan1; CID+5533 -6FDB E0101; Hanyo-Denshi; JA6334 -6FDB E0101; Moji_Joho; MJ016068 -6FDB E0102; Hanyo-Denshi; KS209160 -6FDB E0102; Moji_Joho; MJ016069 -6FDB E0103; Hanyo-Denshi; FT2307 -6FDB E0103; Moji_Joho; MJ016070 -6FDE E0100; Adobe-Japan1; CID+14740 -6FDF E0100; Adobe-Japan1; CID+5526 -6FE0 E0100; Adobe-Japan1; CID+2044 -6FE0 E0101; Hanyo-Denshi; JA2574 -6FE0 E0101; Moji_Joho; MJ016075 -6FE0 E0102; Hanyo-Denshi; JTB4D7 -6FE0 E0102; Moji_Joho; MJ016076 -6FE1 E0100; Adobe-Japan1; CID+3294 -6FE4 E0100; Adobe-Japan1; CID+5430 -6FE8 E0100; Adobe-Japan1; CID+21913 -6FE8 E0101; Hanyo-Denshi; JB4103 -6FE8 E0101; Moji_Joho; MJ016084 -6FE8 E0102; Hanyo-Denshi; KS208770 -6FE8 E0102; Moji_Joho; MJ016085 -6FE8 E0103; Hanyo-Denshi; TK01053210 -6FE9 E0100; Adobe-Japan1; CID+17997 -6FE9 E0101; Hanyo-Denshi; JB4104 -6FE9 E0101; Moji_Joho; MJ016087 -6FE9 E0102; Hanyo-Denshi; KS208790 -6FE9 E0102; Moji_Joho; MJ016088 -6FEA E0100; Hanyo-Denshi; TK01053330 -6FEA E0101; Hanyo-Denshi; TK01053430 -6FEA E0102; Hanyo-Denshi; TK01053470 -6FEA E0103; Hanyo-Denshi; TK01053570 -6FEB E0100; Adobe-Japan1; CID+3934 -6FEC E0100; Adobe-Japan1; CID+5528 -6FEC E0101; Hanyo-Denshi; JA6329 -6FEC E0102; Hanyo-Denshi; TK01053490 -6FEE E0100; Adobe-Japan1; CID+5532 -6FEF E0100; Adobe-Japan1; CID+2901 -6FEF E0101; Adobe-Japan1; CID+7731 -6FEF E0102; Hanyo-Denshi; JA3485 -6FEF E0102; Moji_Joho; MJ016098 -6FEF E0103; Hanyo-Denshi; FT1851 -6FEF E0103; Moji_Joho; MJ016097 -6FEF E0104; Moji_Joho; MJ016099 -6FF0 E0100; Adobe-Japan1; CID+16953 -6FF1 E0100; Adobe-Japan1; CID+5531 -6FF1 E0101; Hanyo-Denshi; JA6332 -6FF1 E0101; Moji_Joho; MJ016101 -6FF1 E0102; Hanyo-Denshi; FT2306S -6FF1 E0102; Moji_Joho; MJ016103 -6FF1 E0103; Moji_Joho; MJ016102 -6FF3 E0100; Adobe-Japan1; CID+5510 -6FF5 E0100; Adobe-Japan1; CID+8531 -6FF5 E0101; Hanyo-Denshi; JB4106 -6FF5 E0101; Moji_Joho; MJ016106 -6FF5 E0102; Hanyo-Denshi; JTB4CD -6FF5 E0102; Moji_Joho; MJ059833 -6FF6 E0100; Adobe-Japan1; CID+7076 -6FF9 E0100; Adobe-Japan1; CID+15395 -6FF9 E0101; Adobe-Japan1; CID+14741 -6FF9 E0102; Hanyo-Denshi; JB4107 -6FF9 E0102; Moji_Joho; MJ016109 -6FF9 E0103; Hanyo-Denshi; JC8725 -6FF9 E0103; Moji_Joho; MJ016110 -6FFA E0100; Adobe-Japan1; CID+5536 -6FFC E0100; Adobe-Japan1; CID+17999 -6FFD E0100; Adobe-Japan1; CID+21914 -6FFE E0100; Adobe-Japan1; CID+5540 -6FFF E0100; Hanyo-Denshi; KS209340 -6FFF E0101; Hanyo-Denshi; TK01053480 -7000 E0100; Adobe-Japan1; CID+18000 -7000 E0101; Hanyo-Denshi; JB4110 -7000 E0102; Hanyo-Denshi; TK01053350 -7001 E0100; Adobe-Japan1; CID+5538 -7001 E0101; Hanyo-Denshi; JA6339 -7001 E0101; Moji_Joho; MJ016119 -7001 E0102; Hanyo-Denshi; FT2308 -7001 E0102; Moji_Joho; MJ016120 -7005 E0100; Adobe-Japan1; CID+8532 -7006 E0100; Adobe-Japan1; CID+7760 -7006 E0101; Hanyo-Denshi; JB4112 -7006 E0102; Hanyo-Denshi; TK01053660 -7007 E0100; Adobe-Japan1; CID+8533 -7007 E0101; Hanyo-Denshi; JB4113 -7007 E0101; Moji_Joho; MJ016127 -7007 E0102; Hanyo-Denshi; JTB4DB -7007 E0102; Moji_Joho; MJ016128 -7009 E0100; Adobe-Japan1; CID+5534 -700A E0100; Adobe-Japan1; CID+18001 -700B E0100; Adobe-Japan1; CID+5535 -700D E0100; Adobe-Japan1; CID+19511 -700E E0100; Hanyo-Denshi; KS209670 -700E E0100; Moji_Joho; MJ057975 -700E E0101; Hanyo-Denshi; KS210010 -700E E0101; Moji_Joho; MJ016135 -700F E0100; Adobe-Japan1; CID+5539 -7010 E0100; Hanyo-Denshi; IP7010 -7010 E0100; Moji_Joho; MJ016138 -7010 E0101; Hanyo-Denshi; KS209690 -7010 E0101; Moji_Joho; MJ016137 -7011 E0100; Adobe-Japan1; CID+5537 -7013 E0100; Hanyo-Denshi; IP7013 -7013 E0100; Moji_Joho; MJ016141 -7013 E0101; Hanyo-Denshi; KS210020 -7013 E0101; Moji_Joho; MJ057976 -7015 E0100; Adobe-Japan1; CID+3520 -7015 E0101; Adobe-Japan1; CID+7787 -7015 E0102; Hanyo-Denshi; JA4146 -7015 E0102; Moji_Joho; MJ016144 -7015 E0103; Hanyo-Denshi; FT1914 -7015 E0103; Moji_Joho; MJ016143 -7017 E0100; Adobe-Japan1; CID+21915 -7017 E0101; Hanyo-Denshi; JB4115 -7017 E0102; Hanyo-Denshi; TK01053910 -7018 E0100; Adobe-Japan1; CID+5545 -701A E0100; Adobe-Japan1; CID+5542 -701A E0101; Hanyo-Denshi; JA6343 -701A E0101; Moji_Joho; MJ016150 -701A E0102; Hanyo-Denshi; FT2310 -701A E0102; Moji_Joho; MJ016151 -701B E0100; Adobe-Japan1; CID+5541 -701B E0101; Adobe-Japan1; CID+14154 -701B E0102; Hanyo-Denshi; JA6342 -701B E0102; Moji_Joho; MJ016152 -701B E0103; Hanyo-Denshi; KS211110 -701B E0103; Moji_Joho; MJ016155 -701B E0104; Hanyo-Denshi; KS210600 -701B E0104; Moji_Joho; MJ016153 -701B E0105; Hanyo-Denshi; JTB501 -701B E0105; Moji_Joho; MJ016154 -701B E0106; Hanyo-Denshi; JTB500 -701B E0106; Moji_Joho; MJ016156 -701D E0100; Adobe-Japan1; CID+5544 -701E E0100; Adobe-Japan1; CID+3244 -701E E0101; Adobe-Japan1; CID+7761 -701E E0102; Hanyo-Denshi; JA3852 -701E E0102; Moji_Joho; MJ016160 -701E E0103; Hanyo-Denshi; FT1881 -701E E0103; Moji_Joho; MJ016161 -701E E0104; Hanyo-Denshi; KS210580 -701E E0104; Moji_Joho; MJ016162 -701E E0105; Hanyo-Denshi; JTB4FA -701E E0105; Moji_Joho; MJ016163 -701E E0106; Hanyo-Denshi; IB2283 -701E E0106; Moji_Joho; MJ016159 -701E E0107; Hanyo-Denshi; TK01053770 -701F E0100; Adobe-Japan1; CID+5546 -701F E0101; Hanyo-Denshi; JA6347 -701F E0101; Moji_Joho; MJ016166 -701F E0102; Hanyo-Denshi; KS210320 -701F E0102; Moji_Joho; MJ016165 -7020 E0100; Adobe-Japan1; CID+19512 -7021 E0100; Hanyo-Denshi; IP7021 -7021 E0100; Moji_Joho; MJ016169 -7021 E0101; Hanyo-Denshi; JTB4E8 -7021 E0101; Moji_Joho; MJ016168 -7022 E0100; Hanyo-Denshi; IB0738 -7022 E0100; Moji_Joho; MJ016170 -7022 E0101; Hanyo-Denshi; IP7022 -7022 E0101; Moji_Joho; MJ016171 -7023 E0100; Adobe-Japan1; CID+18002 -7026 E0100; Adobe-Japan1; CID+2995 -7026 E0101; Adobe-Japan1; CID+7741 -7026 E0102; Hanyo-Denshi; JA3585 -7026 E0102; Moji_Joho; MJ016175 -7026 E0103; Hanyo-Denshi; FT1860 -7026 E0103; Moji_Joho; MJ016176 -7027 E0100; Adobe-Japan1; CID+2893 -7027 E0101; Adobe-Japan1; CID+13911 -7027 E0102; Hanyo-Denshi; JA3477 -7027 E0102; Moji_Joho; MJ016177 -7027 E0103; Hanyo-Denshi; IB2291 -7027 E0103; Moji_Joho; MJ016180 -7027 E0104; Hanyo-Denshi; JTB4F4 -7027 E0104; Moji_Joho; MJ016179 -7027 E0105; Hanyo-Denshi; IB2290 -7027 E0105; Moji_Joho; MJ016181 -7027 E0106; Hanyo-Denshi; JTB4FD -7027 E0106; Moji_Joho; MJ016178 -7027 E0107; Hanyo-Denshi; JTB4FF -7027 E0107; Moji_Joho; MJ016182 -7027 E0108; Hanyo-Denshi; TK01053520 -7027 E0109; Hanyo-Denshi; TK01053780 -7027 E010A; Hanyo-Denshi; TK01053940 -7028 E0100; Adobe-Japan1; CID+8534 -702A E0100; Hanyo-Denshi; KS210640 -702A E0101; Hanyo-Denshi; TK01053880 -702C E0100; Adobe-Japan1; CID+2633 -702F E0100; Adobe-Japan1; CID+21916 -7030 E0100; Adobe-Japan1; CID+5547 -7032 E0100; Adobe-Japan1; CID+5549 -7034 E0100; Adobe-Japan1; CID+21917 -7037 E0100; Adobe-Japan1; CID+21918 -7037 E0101; Hanyo-Denshi; JB4120 -7037 E0101; Moji_Joho; MJ016200 -7037 E0102; Hanyo-Denshi; KS211560 -7037 E0102; Moji_Joho; MJ057978 -7039 E0100; Adobe-Japan1; CID+14742 -703A E0100; Adobe-Japan1; CID+18004 -703C E0100; Adobe-Japan1; CID+14743 -703E E0100; Adobe-Japan1; CID+5548 -703E E0101; Hanyo-Denshi; JA6349 -703E E0101; Moji_Joho; MJ016207 -703E E0102; Hanyo-Denshi; FT2314 -703E E0102; Moji_Joho; MJ016208 -7041 E0100; Hanyo-Denshi; IP7041 -7041 E0100; Moji_Joho; MJ016211 -7041 E0101; Hanyo-Denshi; JT7041 -7041 E0101; Moji_Joho; MJ016212 -7043 E0100; Adobe-Japan1; CID+18005 -7044 E0100; Adobe-Japan1; CID+21919 -7044 E0101; Hanyo-Denshi; JB4124 -7044 E0101; Moji_Joho; MJ016215 -7044 E0102; Hanyo-Denshi; KS211580 -7044 E0102; Moji_Joho; MJ016216 -7047 E0100; Adobe-Japan1; CID+18006 -7047 E0101; Moji_Joho; MJ016219 -7047 E0102; Moji_Joho; MJ016220 -7048 E0100; Adobe-Japan1; CID+21920 -7049 E0100; Adobe-Japan1; CID+19513 -704A E0100; Adobe-Japan1; CID+20306 -704A E0101; Adobe-Japan1; CID+14744 -704A E0102; Hanyo-Denshi; JB4127 -704A E0102; Moji_Joho; MJ016223 -704A E0103; Hanyo-Denshi; KS211540 -704A E0103; Moji_Joho; MJ016224 -704B E0100; Adobe-Japan1; CID+18007 -704C E0100; Adobe-Japan1; CID+5490 -704C E0101; Hanyo-Denshi; JA6285 -704C E0101; Moji_Joho; MJ016226 -704C E0102; Hanyo-Denshi; KS211380 -704C E0102; Moji_Joho; MJ016227 -704E E0100; Adobe-Japan1; CID+16954 -7051 E0100; Adobe-Japan1; CID+5550 -7054 E0100; Adobe-Japan1; CID+14745 -7055 E0100; Adobe-Japan1; CID+21921 -7055 E0101; Hanyo-Denshi; JB4130 -7055 E0101; Moji_Joho; MJ016234 -7055 E0102; Hanyo-Denshi; KS211780 -7055 E0102; Moji_Joho; MJ057980 -7058 E0100; Adobe-Japan1; CID+3263 -7058 E0101; Adobe-Japan1; CID+7767 -7058 E0102; Hanyo-Denshi; JA3871 -7058 E0102; Moji_Joho; MJ016237 -7058 E0103; Hanyo-Denshi; FT1887 -7058 E0103; Moji_Joho; MJ016238 -7058 E0104; Hanyo-Denshi; TK01054080 -705D E0100; Adobe-Japan1; CID+14746 -705E E0100; Adobe-Japan1; CID+14747 -7061 E0100; Hanyo-Denshi; IP7061 -7061 E0101; Hanyo-Denshi; KS212080 -7061 E0102; Hanyo-Denshi; TK01054110 -7063 E0100; Adobe-Japan1; CID+5551 -7064 E0100; Adobe-Japan1; CID+14748 -7065 E0100; Adobe-Japan1; CID+18009 -7068 E0100; Hanyo-Denshi; IP7068 -7068 E0100; Moji_Joho; MJ016256 -7068 E0101; Hanyo-Denshi; KS212350 -7068 E0101; Moji_Joho; MJ016257 -7069 E0100; Adobe-Japan1; CID+18010 -706B E0100; Adobe-Japan1; CID+1360 -706C E0100; Adobe-Japan1; CID+14749 -706E E0100; Adobe-Japan1; CID+18011 -706E E0101; Hanyo-Denshi; JB4137 -706E E0101; Moji_Joho; MJ016262 -706E E0102; Hanyo-Denshi; IB2301 -706E E0102; Moji_Joho; MJ016264 -706E E0103; Moji_Joho; MJ016263 -706F E0100; Adobe-Japan1; CID+3182 -7070 E0100; Adobe-Japan1; CID+1411 -7070 E0101; Adobe-Japan1; CID+13674 -7070 E0102; Hanyo-Denshi; JA1905 -7070 E0102; Moji_Joho; MJ016267 -7070 E0103; Hanyo-Denshi; KS212510 -7070 E0103; Moji_Joho; MJ016266 -7075 E0100; Adobe-Japan1; CID+16955 -7075 E0101; Hanyo-Denshi; JB4138 -7075 E0102; Hanyo-Denshi; TK01054200 -7076 E0100; Adobe-Japan1; CID+18012 -7077 E0100; Hanyo-Denshi; IP7077 -7077 E0100; Moji_Joho; MJ016275 -7077 E0101; Hanyo-Denshi; KS213270 -7077 E0101; Moji_Joho; MJ016276 -7078 E0100; Adobe-Japan1; CID+1662 -7078 E0101; Adobe-Japan1; CID+20270 -7078 E0102; Moji_Joho; MJ016277 -7078 E0103; Moji_Joho; MJ016278 -707C E0100; Adobe-Japan1; CID+2314 -707C E0101; Adobe-Japan1; CID+7696 -707C E0102; Hanyo-Denshi; JA2862 -707C E0102; Moji_Joho; MJ016283 -707C E0103; Hanyo-Denshi; FT1817 -707C E0103; Moji_Joho; MJ016282 -707D E0100; Adobe-Japan1; CID+2114 -707D E0101; Hanyo-Denshi; JA2650 -707D E0101; Moji_Joho; MJ016284 -707D E0102; Hanyo-Denshi; KS213190 -707D E0102; Moji_Joho; MJ016285 -707E E0100; Adobe-Japan1; CID+14750 -7081 E0100; Adobe-Japan1; CID+14751 -7081 E0101; Hanyo-Denshi; JB4141 -7081 E0101; Moji_Joho; MJ016288 -7081 E0102; Hanyo-Denshi; JTB153 -7081 E0102; Moji_Joho; MJ016287 -7085 E0100; Adobe-Japan1; CID+8535 -7086 E0100; Adobe-Japan1; CID+18013 -7089 E0100; Adobe-Japan1; CID+4045 -7089 E0101; Hanyo-Denshi; JA4707 -7089 E0101; Moji_Joho; MJ016297 -7089 E0102; Hanyo-Denshi; KS212980 -7089 E0102; Moji_Joho; MJ016296 -708A E0100; Adobe-Japan1; CID+2604 -708D E0100; Hanyo-Denshi; IP708D -708D E0101; Hanyo-Denshi; TK01054230 -708E E0100; Adobe-Japan1; CID+1292 -7092 E0100; Adobe-Japan1; CID+5553 -7094 E0100; Adobe-Japan1; CID+21922 -7095 E0100; Adobe-Japan1; CID+14752 -7096 E0100; Adobe-Japan1; CID+21923 -7097 E0100; Adobe-Japan1; CID+18014 -7098 E0100; Adobe-Japan1; CID+19514 -7098 E0101; Hanyo-Denshi; JB4148 -7098 E0102; Hanyo-Denshi; TK01054250 -7099 E0100; Adobe-Japan1; CID+5552 -709B E0100; Adobe-Japan1; CID+21924 -709F E0100; Adobe-Japan1; CID+18016 -70A4 E0100; Adobe-Japan1; CID+16956 -70AB E0100; Adobe-Japan1; CID+8536 -70AC E0100; Adobe-Japan1; CID+5556 -70AC E0101; Hanyo-Denshi; JA6357 -70AC E0101; Moji_Joho; MJ016331 -70AC E0102; Hanyo-Denshi; JTB512 -70AC E0102; Moji_Joho; MJ016332 -70AD E0100; Adobe-Japan1; CID+2936 -70AD E0101; Adobe-Japan1; CID+13916 -70AD E0102; Hanyo-Denshi; JA3526 -70AD E0102; Moji_Joho; MJ016333 -70AD E0103; Hanyo-Denshi; KS213510 -70AD E0103; Moji_Joho; MJ016334 -70AE E0100; Adobe-Japan1; CID+5559 -70AE E0101; Hanyo-Denshi; JA6360 -70AE E0101; Moji_Joho; MJ016335 -70AE E0102; Hanyo-Denshi; FT2315 -70AE E0102; Moji_Joho; MJ016336 -70AF E0100; Adobe-Japan1; CID+5554 -70B0 E0100; Adobe-Japan1; CID+19515 -70B1 E0100; Adobe-Japan1; CID+18017 -70B3 E0100; Adobe-Japan1; CID+5558 -70B3 E0101; Hanyo-Denshi; JA6359 -70B3 E0101; Moji_Joho; MJ016341 -70B3 E0102; Hanyo-Denshi; JTB513 -70B3 E0102; Moji_Joho; MJ016342 -70B4 E0100; Adobe-Japan1; CID+21925 -70B7 E0100; Adobe-Japan1; CID+14753 -70B7 E0101; Hanyo-Denshi; JB4155 -70B7 E0101; Moji_Joho; MJ016346 -70B7 E0102; Hanyo-Denshi; KS213850 -70B7 E0102; Moji_Joho; MJ016347 -70B8 E0100; Adobe-Japan1; CID+5557 -70B9 E0100; Adobe-Japan1; CID+3130 -70BA E0100; Adobe-Japan1; CID+1181 -70BB E0100; Adobe-Japan1; CID+8365 -70C8 E0100; Adobe-Japan1; CID+4029 -70CA E0100; Adobe-Japan1; CID+18020 -70CB E0100; Adobe-Japan1; CID+5561 -70CF E0100; Adobe-Japan1; CID+1226 -70D1 E0100; Adobe-Japan1; CID+18021 -70D3 E0100; Adobe-Japan1; CID+14754 -70D4 E0100; Adobe-Japan1; CID+14755 -70D5 E0100; Adobe-Japan1; CID+19516 -70D6 E0100; Adobe-Japan1; CID+19517 -70D8 E0100; Adobe-Japan1; CID+14756 -70D9 E0100; Adobe-Japan1; CID+5563 -70DC E0100; Adobe-Japan1; CID+14757 -70DD E0100; Adobe-Japan1; CID+5562 -70DF E0100; Adobe-Japan1; CID+5560 -70E3 E0100; Hanyo-Denshi; IP70E3 -70E3 E0101; Hanyo-Denshi; TK01054580 -70E4 E0100; Adobe-Japan1; CID+16957 -70E4 E0101; Hanyo-Denshi; JB4164 -70E4 E0101; Moji_Joho; MJ016385 -70E4 E0102; Hanyo-Denshi; JTB516 -70E4 E0102; Moji_Joho; MJ016386 -70EC E0100; Adobe-Japan1; CID+18019 -70F1 E0100; Adobe-Japan1; CID+5555 -70F9 E0100; Adobe-Japan1; CID+3665 -70FA E0100; Adobe-Japan1; CID+21926 -70FD E0100; Adobe-Japan1; CID+5565 -7103 E0100; Adobe-Japan1; CID+18022 -7104 E0100; Adobe-Japan1; CID+8538 -7105 E0100; Adobe-Japan1; CID+21927 -7106 E0100; Adobe-Japan1; CID+18023 -7107 E0100; Adobe-Japan1; CID+14758 -7108 E0100; Adobe-Japan1; CID+18024 -7108 E0101; Hanyo-Denshi; JD7978 -7108 E0101; Moji_Joho; MJ016413 -7108 E0102; Hanyo-Denshi; JTB51C -7108 E0102; Moji_Joho; MJ016414 -7108 E0103; Hanyo-Denshi; TK01054600 -7109 E0100; Adobe-Japan1; CID+5564 -710B E0100; Adobe-Japan1; CID+21928 -710C E0100; Adobe-Japan1; CID+18025 -710F E0100; Adobe-Japan1; CID+8537 -710F E0101; Hanyo-Denshi; JB4173 -710F E0101; Moji_Joho; MJ016422 -710F E0102; Hanyo-Denshi; JTB51AS -710F E0102; Moji_Joho; MJ059859 -7114 E0100; Adobe-Japan1; CID+1293 -7118 E0100; Hanyo-Denshi; JT7118 -7118 E0101; Hanyo-Denshi; TK01054770 -7119 E0100; Adobe-Japan1; CID+5567 -711A E0100; Adobe-Japan1; CID+3586 -711C E0100; Adobe-Japan1; CID+5566 -711E E0100; Adobe-Japan1; CID+16959 -7120 E0100; Adobe-Japan1; CID+14759 -7121 E0100; Adobe-Japan1; CID+3777 -7122 E0100; Hanyo-Denshi; IP7122 -7122 E0101; Hanyo-Denshi; TK01055030 -7126 E0100; Adobe-Japan1; CID+2479 -712B E0100; Adobe-Japan1; CID+16958 -712B E0101; Hanyo-Denshi; JB4176 -712B E0101; Moji_Joho; MJ016445 -712B E0102; Hanyo-Denshi; KS215470 -712B E0102; Moji_Joho; MJ016446 -712D E0100; Adobe-Japan1; CID+21929 -712D E0101; Hanyo-Denshi; JB4177 -712D E0102; Hanyo-Denshi; TK01055010 -712E E0100; Adobe-Japan1; CID+16960 -712F E0100; Adobe-Japan1; CID+18027 -7130 E0100; Adobe-Japan1; CID+7644 -7131 E0100; Adobe-Japan1; CID+14760 -7136 E0100; Adobe-Japan1; CID+2741 -7138 E0100; Adobe-Japan1; CID+21930 -713C E0100; Adobe-Japan1; CID+2478 -7141 E0100; Adobe-Japan1; CID+21931 -7141 E0101; Moji_Joho; MJ016465 -7141 E0102; Moji_Joho; MJ016466 -7145 E0100; Adobe-Japan1; CID+19518 -7146 E0100; Adobe-Japan1; CID+8540 -7147 E0100; Adobe-Japan1; CID+8541 -7149 E0100; Adobe-Japan1; CID+7810 -7149 E0101; Adobe-Japan1; CID+4035 -7149 E0102; Hanyo-Denshi; JA4691 -7149 E0102; Moji_Joho; MJ016474 -7149 E0103; Hanyo-Denshi; FT1938 -7149 E0103; Moji_Joho; MJ016475 -714A E0100; Adobe-Japan1; CID+14761 -714B E0100; Adobe-Japan1; CID+21932 -714C E0100; Adobe-Japan1; CID+5573 -714E E0100; Adobe-Japan1; CID+2717 -714E E0101; Adobe-Japan1; CID+7718 -714E E0102; Hanyo-Denshi; JA3289 -714E E0102; Moji_Joho; MJ016481 -714E E0103; Hanyo-Denshi; FT1839 -714E E0103; Moji_Joho; MJ016480 -7150 E0100; Adobe-Japan1; CID+18028 -7150 E0101; Hanyo-Denshi; JB4188 -7150 E0102; Hanyo-Denshi; TK01055340 -7151 E0100; Adobe-Japan1; CID+16961 -7152 E0100; Adobe-Japan1; CID+14762 -7152 E0101; Adobe-Japan1; CID+21933 -7152 E0102; Hanyo-Denshi; JB4189 -7152 E0102; Moji_Joho; MJ016487 -7152 E0103; Hanyo-Denshi; JTB53AS -7152 E0103; Moji_Joho; MJ016486 -7152 E0104; Moji_Joho; MJ016488 -7153 E0100; Adobe-Japan1; CID+18029 -7155 E0100; Adobe-Japan1; CID+5569 -7156 E0100; Adobe-Japan1; CID+5574 -7156 E0101; Hanyo-Denshi; JA6375 -7156 E0101; Moji_Joho; MJ016492 -7156 E0102; Hanyo-Denshi; FT2316S -7156 E0102; Moji_Joho; MJ016493 -7157 E0100; Adobe-Japan1; CID+21934 -7159 E0100; Adobe-Japan1; CID+1294 -7159 E0101; Adobe-Japan1; CID+13657 -7159 E0102; Hanyo-Denshi; JA1776 -7159 E0102; Moji_Joho; MJ016497 -7159 E0103; Hanyo-Denshi; JTB528 -7159 E0103; Moji_Joho; MJ016496 -715A E0100; Adobe-Japan1; CID+21935 -715C E0100; Adobe-Japan1; CID+8539 -715E E0100; Adobe-Japan1; CID+18030 -7160 E0100; Adobe-Japan1; CID+14763 -7162 E0100; Adobe-Japan1; CID+5572 -7162 E0101; Adobe-Japan1; CID+14155 -7162 E0102; Hanyo-Denshi; JA6373 -7162 E0102; Moji_Joho; MJ016507 -7162 E0103; Hanyo-Denshi; JTB529 -7162 E0103; Moji_Joho; MJ016508 -7162 E0104; Moji_Joho; MJ016506 -7164 E0100; Adobe-Japan1; CID+3351 -7165 E0100; Adobe-Japan1; CID+5568 -7166 E0100; Adobe-Japan1; CID+5571 -7167 E0100; Adobe-Japan1; CID+2480 -7168 E0100; Adobe-Japan1; CID+16962 -7169 E0100; Adobe-Japan1; CID+3429 -716C E0100; Adobe-Japan1; CID+5575 -716E E0100; Adobe-Japan1; CID+13347 -716E E0101; Adobe-Japan1; CID+2301 -716E E0102; Hanyo-Denshi; JA2849 -716E E0103; Hanyo-Denshi; JC8753 -7179 E0100; Adobe-Japan1; CID+14764 -717A E0100; Hanyo-Denshi; IB0741 -717A E0100; Moji_Joho; MJ016528 -717A E0101; Hanyo-Denshi; IP717A -717A E0101; Moji_Joho; MJ016529 -717D E0100; Adobe-Japan1; CID+2718 -717D E0101; Adobe-Japan1; CID+7719 -717D E0102; Adobe-Japan1; CID+7972 -717D E0103; Hanyo-Denshi; JA3290 -717D E0103; Moji_Joho; MJ016533 -717D E0104; Hanyo-Denshi; HG1638 -717D E0104; Moji_Joho; MJ016532 -717D E0105; Hanyo-Denshi; FT1840 -717D E0105; Moji_Joho; MJ016534 -7180 E0100; Adobe-Japan1; CID+18033 -7184 E0100; Adobe-Japan1; CID+5578 -7185 E0100; Adobe-Japan1; CID+16963 -7187 E0100; Adobe-Japan1; CID+16964 -7188 E0100; Adobe-Japan1; CID+5570 -7188 E0101; Hanyo-Denshi; JA6371 -7188 E0101; Moji_Joho; MJ016545 -7188 E0102; Hanyo-Denshi; JTB547 -7188 E0102; Moji_Joho; MJ016546 -7188 E0103; Hanyo-Denshi; TK01055590 -7188 E0104; Hanyo-Denshi; TK01055750 -718A E0100; Adobe-Japan1; CID+1789 -718C E0100; Adobe-Japan1; CID+21936 -718F E0100; Adobe-Japan1; CID+5576 -7192 E0100; Adobe-Japan1; CID+14765 -7194 E0100; Adobe-Japan1; CID+3898 -7194 E0101; Adobe-Japan1; CID+7805 -7194 E0102; Hanyo-Denshi; JA4548 -7194 E0102; Moji_Joho; MJ016561 -7194 E0103; Hanyo-Denshi; FT1933 -7194 E0103; Moji_Joho; MJ016562 -7195 E0100; Adobe-Japan1; CID+5579 -7196 E0100; Adobe-Japan1; CID+18032 -7196 E0101; Hanyo-Denshi; JD7988 -7196 E0101; Moji_Joho; MJ016564 -7196 E0102; Hanyo-Denshi; KS215860 -7196 E0102; Moji_Joho; MJ057995 -7199 E0100; Adobe-Japan1; CID+8285 -7199 E0101; Hanyo-Denshi; JA8406 -7199 E0102; Hanyo-Denshi; TK01055390 -719A E0100; Adobe-Japan1; CID+21937 -719B E0100; Adobe-Japan1; CID+18034 -719C E0100; Hanyo-Denshi; IP719C -719C E0101; Hanyo-Denshi; KS217700 -719F E0100; Adobe-Japan1; CID+2393 -71A0 E0100; Adobe-Japan1; CID+18035 -71A2 E0100; Adobe-Japan1; CID+18036 -71A2 E0101; Hanyo-Denshi; JB4211 -71A2 E0101; Moji_Joho; MJ016577 -71A2 E0102; Hanyo-Denshi; IB0743 -71A2 E0102; Moji_Joho; MJ016576 -71A5 E0100; Hanyo-Denshi; IB0744 -71A5 E0100; Moji_Joho; MJ016580 -71A5 E0101; Hanyo-Denshi; IP71A5 -71A5 E0101; Moji_Joho; MJ016581 -71A8 E0100; Adobe-Japan1; CID+5580 -71AC E0100; Adobe-Japan1; CID+5581 -71AE E0100; Adobe-Japan1; CID+18037 -71AF E0100; Adobe-Japan1; CID+18038 -71B0 E0100; Adobe-Japan1; CID+21938 -71B1 E0100; Adobe-Japan1; CID+3300 -71B2 E0100; Adobe-Japan1; CID+19519 -71B3 E0100; Adobe-Japan1; CID+15397 -71B3 E0101; Adobe-Japan1; CID+14766 -71B3 E0102; Hanyo-Denshi; JB4215 -71B3 E0102; Moji_Joho; MJ016596 -71B3 E0103; Hanyo-Denshi; JD8001 -71B3 E0103; Moji_Joho; MJ016595 -71B9 E0100; Adobe-Japan1; CID+5583 -71BA E0100; Adobe-Japan1; CID+16965 -71BE E0100; Adobe-Japan1; CID+5584 -71BE E0101; Hanyo-Denshi; JA6385 -71BE E0101; Moji_Joho; MJ016605 -71BE E0102; Hanyo-Denshi; KS219130 -71BE E0102; Moji_Joho; MJ016606 -71BF E0100; Adobe-Japan1; CID+21939 -71BF E0101; Hanyo-Denshi; JB4217 -71BF E0101; Moji_Joho; MJ016607 -71BF E0102; Hanyo-Denshi; JTB543 -71BF E0102; Moji_Joho; MJ016608 -71C0 E0100; Adobe-Japan1; CID+21940 -71C1 E0100; Adobe-Japan1; CID+8543 -71C1 E0101; Hanyo-Denshi; JB4219 -71C1 E0101; Moji_Joho; MJ016611 -71C1 E0102; Hanyo-Denshi; JTC0C0 -71C1 E0102; Moji_Joho; MJ016610 -71C1 E0103; Hanyo-Denshi; JTB545 -71C1 E0103; Moji_Joho; MJ016613 -71C1 E0104; Hanyo-Denshi; JTB544 -71C1 E0104; Moji_Joho; MJ016612 -71C1 E0105; Hanyo-Denshi; TK01055710 -71C2 E0100; Hanyo-Denshi; IP71C2 -71C2 E0100; Moji_Joho; MJ016615 -71C2 E0101; Hanyo-Denshi; KS219140 -71C2 E0101; Moji_Joho; MJ016616 -71C3 E0100; Adobe-Japan1; CID+3305 -71C4 E0100; Adobe-Japan1; CID+16966 -71C8 E0100; Adobe-Japan1; CID+3183 -71C9 E0100; Adobe-Japan1; CID+5586 -71CB E0100; Adobe-Japan1; CID+14767 -71CC E0100; Adobe-Japan1; CID+21941 -71CC E0101; Hanyo-Denshi; JB4222 -71CC E0101; Moji_Joho; MJ016626 -71CC E0102; Hanyo-Denshi; KS219680 -71CC E0102; Moji_Joho; MJ058010 -71CE E0100; Adobe-Japan1; CID+5588 -71D0 E0100; Adobe-Japan1; CID+3997 -71D0 E0101; Adobe-Japan1; CID+14090 -71D0 E0102; Hanyo-Denshi; JA4653 -71D0 E0102; Moji_Joho; MJ016631 -71D0 E0103; Hanyo-Denshi; KS218660 -71D0 E0103; Moji_Joho; MJ016630 -71D0 E0104; Moji_Joho; MJ016632 -71D2 E0100; Adobe-Japan1; CID+5585 -71D3 E0100; Adobe-Japan1; CID+14768 -71D4 E0100; Adobe-Japan1; CID+5587 -71D5 E0100; Adobe-Japan1; CID+1295 -71D5 E0101; Hanyo-Denshi; JA1777 -71D5 E0101; Moji_Joho; MJ016637 -71D5 E0102; Hanyo-Denshi; KS218190 -71D5 E0102; Moji_Joho; MJ058005 -71D5 E0103; Hanyo-Denshi; TK01055690 -71D6 E0100; Adobe-Japan1; CID+14769 -71D7 E0100; Adobe-Japan1; CID+5582 -71D9 E0100; Adobe-Japan1; CID+18040 -71DA E0100; Adobe-Japan1; CID+21942 -71DC E0100; Adobe-Japan1; CID+18041 -71DF E0100; Adobe-Japan1; CID+4430 -71E0 E0100; Adobe-Japan1; CID+5589 -71E0 E0101; Hanyo-Denshi; JA6390 -71E0 E0101; Moji_Joho; MJ016646 -71E0 E0102; Hanyo-Denshi; FT2320 -71E0 E0102; Moji_Joho; MJ016647 -71E5 E0100; Adobe-Japan1; CID+2793 -71E6 E0100; Adobe-Japan1; CID+2182 -71E7 E0100; Adobe-Japan1; CID+5591 -71E7 E0101; Hanyo-Denshi; JA6392 -71E7 E0101; Moji_Joho; MJ016655 -71E7 E0102; Hanyo-Denshi; FT2321 -71E7 E0102; Moji_Joho; MJ016656 -71E7 E0103; Hanyo-Denshi; JTB558 -71E7 E0103; Moji_Joho; MJ016657 -71E7 E0104; Hanyo-Denshi; IB0745 -71E7 E0104; Moji_Joho; MJ016654 -71EC E0100; Adobe-Japan1; CID+5590 -71ED E0100; Adobe-Japan1; CID+2538 -71EE E0100; Adobe-Japan1; CID+4334 -71EE E0101; Hanyo-Denshi; JA5057 -71EE E0101; Moji_Joho; MJ016665 -71EE E0102; Hanyo-Denshi; TK01002060 -71EE E0103; Moji_Joho; MJ016664 -71F4 E0100; Adobe-Japan1; CID+19520 -71F5 E0100; Adobe-Japan1; CID+5592 -71F5 E0101; Hanyo-Denshi; JA6393 -71F5 E0101; Moji_Joho; MJ016673 -71F5 E0102; Hanyo-Denshi; FT2322 -71F5 E0102; Moji_Joho; MJ016672 -71F8 E0100; Adobe-Japan1; CID+21943 -71F9 E0100; Adobe-Japan1; CID+5594 -71FB E0100; Adobe-Japan1; CID+5577 -71FB E0101; Hanyo-Denshi; JA6378 -71FB E0101; Moji_Joho; MJ016677 -71FB E0102; Hanyo-Denshi; FT2318 -71FB E0102; Moji_Joho; MJ016678 -71FC E0100; Adobe-Japan1; CID+5593 -71FD E0100; Hanyo-Denshi; IP71FD -71FD E0101; Hanyo-Denshi; TK01056230 -71FE E0100; Adobe-Japan1; CID+8544 -71FF E0100; Adobe-Japan1; CID+5595 -71FF E0101; Adobe-Japan1; CID+13562 -71FF E0102; Hanyo-Denshi; JA6402 -71FF E0102; Moji_Joho; MJ016683 -71FF E0103; Hanyo-Denshi; FT1711 -71FF E0103; Moji_Joho; MJ016682 -7200 E0100; Adobe-Japan1; CID+14770 -7206 E0100; Adobe-Japan1; CID+3376 -7207 E0100; Adobe-Japan1; CID+18042 -7207 E0101; Hanyo-Denshi; JB4231 -7207 E0101; Moji_Joho; MJ016691 -7207 E0102; Hanyo-Denshi; KS220130 -7207 E0102; Moji_Joho; MJ016692 -7208 E0100; Adobe-Japan1; CID+21944 -7209 E0100; Adobe-Japan1; CID+21945 -7209 E0101; Hanyo-Denshi; JB4233 -7209 E0101; Moji_Joho; MJ016694 -7209 E0102; Hanyo-Denshi; JTB55D -7209 E0102; Moji_Joho; MJ016695 -720D E0100; Adobe-Japan1; CID+5596 -7210 E0100; Adobe-Japan1; CID+5597 -7213 E0100; Adobe-Japan1; CID+21946 -7215 E0100; Adobe-Japan1; CID+16967 -7217 E0100; Adobe-Japan1; CID+19521 -7217 E0101; Hanyo-Denshi; JB4235 -7217 E0101; Moji_Joho; MJ016708 -7217 E0102; Hanyo-Denshi; KS220520 -7217 E0102; Moji_Joho; MJ016709 -721A E0100; Adobe-Japan1; CID+21947 -721B E0100; Adobe-Japan1; CID+5598 -721B E0101; Hanyo-Denshi; JA6405 -721B E0101; Moji_Joho; MJ016712 -721B E0102; Hanyo-Denshi; FT2324 -721B E0102; Moji_Joho; MJ016713 -721D E0100; Adobe-Japan1; CID+14771 -721F E0100; Adobe-Japan1; CID+19522 -721F E0101; Hanyo-Denshi; JB4238 -721F E0101; Moji_Joho; MJ016718 -721F E0102; Hanyo-Denshi; IB2347 -721F E0102; Moji_Joho; MJ016717 -7224 E0100; Adobe-Japan1; CID+21948 -7224 E0101; Hanyo-Denshi; JB4239 -7224 E0101; Moji_Joho; MJ016723 -7224 E0102; Hanyo-Denshi; KS221120 -7224 E0102; Moji_Joho; MJ016724 -7224 E0103; Hanyo-Denshi; TK01056470 -7228 E0100; Adobe-Japan1; CID+7839 -7228 E0101; Adobe-Japan1; CID+5599 -7228 E0102; Hanyo-Denshi; JA6406 -7228 E0102; Moji_Joho; MJ016728 -7228 E0103; Hanyo-Denshi; KS221300S -7228 E0103; Moji_Joho; MJ016729 -7228 E0104; Hanyo-Denshi; FT1964 -7228 E0104; Moji_Joho; MJ016731 -7228 E0105; Moji_Joho; MJ016730 -722A E0100; Adobe-Japan1; CID+3066 -722B E0100; Adobe-Japan1; CID+14772 -722B E0101; Adobe-Japan1; CID+15398 -722B E0102; Hanyo-Denshi; JD8009 -722B E0103; Hanyo-Denshi; JB4240 -722C E0100; Adobe-Japan1; CID+5601 -722D E0100; Adobe-Japan1; CID+5600 -722F E0100; Adobe-Japan1; CID+21949 -722F E0101; Hanyo-Denshi; JB4241 -722F E0101; Moji_Joho; MJ016738 -722F E0102; Hanyo-Denshi; KS221650 -722F E0102; Moji_Joho; MJ058016 -722F E0103; Hanyo-Denshi; TK01056520 -7230 E0100; Adobe-Japan1; CID+5602 -7230 E0101; Hanyo-Denshi; JA6409 -7230 E0101; Moji_Joho; MJ016740 -7230 E0102; Hanyo-Denshi; KS221640 -7230 E0102; Moji_Joho; MJ016741 -7231 E0100; Hanyo-Denshi; IB1520 -7231 E0101; Hanyo-Denshi; TK01056560 -7232 E0100; Adobe-Japan1; CID+5603 -7232 E0101; Hanyo-Denshi; JA6410 -7232 E0101; Moji_Joho; MJ016743 -7232 E0102; Hanyo-Denshi; JTB563 -7232 E0102; Moji_Joho; MJ016744 -7232 E0103; Hanyo-Denshi; TK01054670 -7232 E0104; Hanyo-Denshi; TK01054680 -7234 E0100; Adobe-Japan1; CID+18044 -7235 E0100; Adobe-Japan1; CID+13809 -7235 E0101; Adobe-Japan1; CID+2315 -7235 E0102; Adobe-Japan1; CID+13808 -7235 E0103; Hanyo-Denshi; JA2863 -7235 E0103; Moji_Joho; MJ016747 -7235 E0104; Hanyo-Denshi; JTB55C -7235 E0104; Moji_Joho; MJ016748 -7236 E0100; Adobe-Japan1; CID+3541 -7236 E0101; Adobe-Japan1; CID+13497 -7236 E0102; Moji_Joho; MJ016749 -7236 E0103; Moji_Joho; MJ016750 -7238 E0100; Adobe-Japan1; CID+14773 -7238 E0101; Moji_Joho; MJ016751 -7238 E0102; Moji_Joho; MJ016752 -7239 E0100; Adobe-Japan1; CID+18045 -7239 E0101; Moji_Joho; MJ016753 -7239 E0102; Moji_Joho; MJ016754 -723A E0100; Adobe-Japan1; CID+3832 -723A E0101; Adobe-Japan1; CID+20294 -723A E0102; Moji_Joho; MJ016755 -723A E0103; Moji_Joho; MJ016756 -723B E0100; Adobe-Japan1; CID+5604 -723B E0101; Adobe-Japan1; CID+14156 -723B E0102; Moji_Joho; MJ016757 -723B E0103; Moji_Joho; MJ016758 -723C E0100; Adobe-Japan1; CID+5605 -723D E0100; Adobe-Japan1; CID+2776 -723E E0100; Adobe-Japan1; CID+2256 -723E E0101; Adobe-Japan1; CID+20169 -723E E0102; Hanyo-Denshi; JA2804 -723E E0102; Moji_Joho; MJ016762 -723E E0103; Hanyo-Denshi; JTAD19 -723E E0103; Moji_Joho; MJ016763 -723F E0100; Adobe-Japan1; CID+5606 -7240 E0100; Adobe-Japan1; CID+5607 -7240 E0101; Hanyo-Denshi; JA6414 -7240 E0101; Moji_Joho; MJ016766 -7240 E0102; Hanyo-Denshi; FT2325 -7240 E0102; Moji_Joho; MJ016767 -7241 E0100; Adobe-Japan1; CID+14774 -7242 E0100; Adobe-Japan1; CID+18046 -7243 E0100; Adobe-Japan1; CID+19523 -7245 E0100; Adobe-Japan1; CID+21950 -7246 E0100; Adobe-Japan1; CID+5608 -7246 E0101; Hanyo-Denshi; JA6415 -7246 E0101; Moji_Joho; MJ016773 -7246 E0102; Hanyo-Denshi; FT2326 -7246 E0102; Moji_Joho; MJ016774 -7247 E0100; Adobe-Japan1; CID+3618 -7247 E0101; Hanyo-Denshi; JA4250 -7247 E0101; Moji_Joho; MJ016775 -7247 E0102; Hanyo-Denshi; IB0748 -7247 E0102; Moji_Joho; MJ016776 -7247 E0103; Hanyo-Denshi; JTB573 -7247 E0103; Moji_Joho; MJ016777 -7247 E0104; Hanyo-Denshi; TK01056920 -7248 E0100; Adobe-Japan1; CID+3419 -724B E0100; Adobe-Japan1; CID+5609 -724C E0100; Adobe-Japan1; CID+3341 -724C E0101; Adobe-Japan1; CID+7771 -724C E0102; Hanyo-Denshi; JA3955 -724C E0102; Moji_Joho; MJ016784 -724C E0103; Hanyo-Denshi; FT1892 -724C E0103; Moji_Joho; MJ016783 -724E E0100; Adobe-Japan1; CID+21951 -724F E0100; Adobe-Japan1; CID+19524 -7250 E0100; Adobe-Japan1; CID+19525 -7250 E0101; Hanyo-Denshi; JB4251 -7250 E0101; Moji_Joho; MJ016788 -7250 E0102; Hanyo-Denshi; KS223410 -7250 E0102; Moji_Joho; MJ016787 -7252 E0100; Adobe-Japan1; CID+3017 -7253 E0100; Adobe-Japan1; CID+14775 -7253 E0101; Hanyo-Denshi; JB4252 -7253 E0101; Moji_Joho; MJ016791 -7253 E0102; Hanyo-Denshi; KS223800 -7253 E0102; Moji_Joho; MJ016792 -7255 E0100; Adobe-Japan1; CID+14776 -7255 E0101; Hanyo-Denshi; JB4253 -7255 E0101; Moji_Joho; MJ016794 -7255 E0102; Hanyo-Denshi; JTB785 -7255 E0102; Moji_Joho; MJ016795 -7256 E0100; Adobe-Japan1; CID+14777 -7257 E0100; Adobe-Japan1; CID+18047 -7257 E0101; Hanyo-Denshi; JD8017 -7257 E0102; Hanyo-Denshi; TK01056990 -7258 E0100; Adobe-Japan1; CID+5610 -7259 E0100; Adobe-Japan1; CID+1383 -7259 E0101; Adobe-Japan1; CID+7965 -7259 E0102; Hanyo-Denshi; JA1871 -7259 E0102; Moji_Joho; MJ016802 -7259 E0103; Hanyo-Denshi; HG1606 -7259 E0103; Moji_Joho; MJ016801 -7259 E0104; Moji_Joho; MJ016803 -725A E0100; Adobe-Japan1; CID+19526 -725A E0101; Hanyo-Denshi; JB4255 -725A E0101; Moji_Joho; MJ016805 -725A E0102; Hanyo-Denshi; JTB577 -725A E0102; Moji_Joho; MJ016804 -725B E0100; Adobe-Japan1; CID+1671 -725C E0100; Adobe-Japan1; CID+14778 -725D E0100; Adobe-Japan1; CID+3794 -725E E0100; Adobe-Japan1; CID+21952 -725F E0100; Adobe-Japan1; CID+3778 -7260 E0100; Adobe-Japan1; CID+19527 -7261 E0100; Adobe-Japan1; CID+1332 -7262 E0100; Adobe-Japan1; CID+4058 -7263 E0100; Adobe-Japan1; CID+18048 -7263 E0101; Hanyo-Denshi; JB4259 -7263 E0102; Hanyo-Denshi; TK01009770 -7267 E0100; Adobe-Japan1; CID+3712 -7268 E0100; Adobe-Japan1; CID+19528 -7269 E0100; Adobe-Japan1; CID+3578 -726B E0100; Adobe-Japan1; CID+21953 -726E E0100; Adobe-Japan1; CID+18050 -726F E0100; Adobe-Japan1; CID+18051 -7271 E0100; Adobe-Japan1; CID+21954 -7272 E0100; Adobe-Japan1; CID+2651 -7274 E0100; Adobe-Japan1; CID+5611 -7277 E0100; Adobe-Japan1; CID+19529 -7278 E0100; Adobe-Japan1; CID+18052 -7279 E0100; Adobe-Japan1; CID+3227 -727B E0100; Adobe-Japan1; CID+21955 -727C E0100; Adobe-Japan1; CID+21956 -727D E0100; Adobe-Japan1; CID+1879 -727D E0101; Moji_Joho; MJ016837 -727D E0102; Moji_Joho; MJ016838 -727E E0100; Adobe-Japan1; CID+5612 -727F E0100; Adobe-Japan1; CID+18053 -727F E0101; Hanyo-Denshi; JB4269 -727F E0102; Hanyo-Denshi; TK01057110 -7280 E0100; Adobe-Japan1; CID+2116 -7280 E0101; Hanyo-Denshi; JA2652 -7280 E0101; Moji_Joho; MJ016843 -7280 E0102; Hanyo-Denshi; KS225480 -7280 E0102; Moji_Joho; MJ016842 -7280 E0103; Hanyo-Denshi; TK01024140 -7281 E0100; Adobe-Japan1; CID+5614 -7282 E0100; Adobe-Japan1; CID+5613 -7282 E0101; Hanyo-Denshi; JA6420 -7282 E0101; Moji_Joho; MJ016845 -7282 E0102; Hanyo-Denshi; JTB57C -7282 E0102; Moji_Joho; MJ059884 -7284 E0100; Adobe-Japan1; CID+19530 -7287 E0100; Adobe-Japan1; CID+5615 -7289 E0100; Adobe-Japan1; CID+21957 -728D E0100; Adobe-Japan1; CID+14779 -728E E0100; Adobe-Japan1; CID+18054 -7292 E0100; Adobe-Japan1; CID+5616 -7293 E0100; Adobe-Japan1; CID+21958 -7296 E0100; Adobe-Japan1; CID+5617 -7297 E0100; Hanyo-Denshi; IP7297 -7297 E0100; Moji_Joho; MJ016864 -7297 E0101; Hanyo-Denshi; KS226430S -7297 E0101; Moji_Joho; MJ058026 -729B E0100; Adobe-Japan1; CID+16969 -72A0 E0100; Adobe-Japan1; CID+1624 -72A2 E0100; Adobe-Japan1; CID+5618 -72A7 E0100; Adobe-Japan1; CID+5619 -72A8 E0100; Adobe-Japan1; CID+21959 -72AC E0100; Adobe-Japan1; CID+1880 -72AD E0100; Adobe-Japan1; CID+14780 -72AE E0100; Adobe-Japan1; CID+18056 -72AE E0101; Hanyo-Denshi; JB4278 -72AE E0101; Moji_Joho; MJ016887 -72AE E0102; Hanyo-Denshi; IB0629 -72AE E0102; Moji_Joho; MJ016886 -72AE E0103; Hanyo-Denshi; TK01057180 -72AF E0100; Adobe-Japan1; CID+3420 -72AF E0101; Hanyo-Denshi; JA4040 -72AF E0101; Moji_Joho; MJ016889 -72AF E0102; Hanyo-Denshi; KS227650 -72AF E0102; Moji_Joho; MJ016890 -72B0 E0100; Adobe-Japan1; CID+18057 -72B1 E0100; Adobe-Japan1; CID+8545 -72B2 E0100; Adobe-Japan1; CID+5621 -72B3 E0100; Hanyo-Denshi; IP72B3 -72B3 E0100; Moji_Joho; MJ016894 -72B3 E0101; Hanyo-Denshi; JT72B3 -72B3 E0101; Moji_Joho; MJ016895 -72B4 E0100; Adobe-Japan1; CID+14781 -72B6 E0100; Adobe-Japan1; CID+2525 -72B9 E0100; Adobe-Japan1; CID+5620 -72BE E0100; Adobe-Japan1; CID+8546 -72C0 E0100; Adobe-Japan1; CID+13355 -72C1 E0100; Adobe-Japan1; CID+18058 -72C2 E0100; Adobe-Japan1; CID+1712 -72C3 E0100; Adobe-Japan1; CID+5622 -72C4 E0100; Adobe-Japan1; CID+5624 -72C6 E0100; Adobe-Japan1; CID+5623 -72C7 E0100; Adobe-Japan1; CID+14782 -72C9 E0100; Adobe-Japan1; CID+19531 -72CA E0100; Moji_Joho; MJ016916 -72CA E0101; Moji_Joho; MJ016917 -72CC E0100; Adobe-Japan1; CID+18060 -72CE E0100; Adobe-Japan1; CID+5625 -72D0 E0100; Adobe-Japan1; CID+1925 -72D0 E0101; Hanyo-Denshi; JA2449 -72D0 E0101; Moji_Joho; MJ016925 -72D0 E0102; Hanyo-Denshi; KS228420 -72D0 E0102; Moji_Joho; MJ016923 -72D0 E0103; Hanyo-Denshi; KS228690 -72D0 E0103; Moji_Joho; MJ016924 -72D2 E0100; Adobe-Japan1; CID+5626 -72D5 E0100; Adobe-Japan1; CID+21960 -72D6 E0100; Adobe-Japan1; CID+21961 -72D7 E0100; Adobe-Japan1; CID+1761 -72D8 E0100; Adobe-Japan1; CID+21962 -72D9 E0100; Adobe-Japan1; CID+2754 -72DB E0100; Adobe-Japan1; CID+2063 -72DF E0100; Adobe-Japan1; CID+21963 -72E0 E0100; Adobe-Japan1; CID+5628 -72E1 E0100; Adobe-Japan1; CID+5629 -72E1 E0101; Adobe-Japan1; CID+20278 -72E1 E0102; Moji_Joho; MJ016940 -72E1 E0103; Moji_Joho; MJ016941 -72E2 E0100; Adobe-Japan1; CID+5627 -72E5 E0100; Adobe-Japan1; CID+19532 -72E9 E0100; Adobe-Japan1; CID+2329 -72EC E0100; Adobe-Japan1; CID+3232 -72ED E0100; Adobe-Japan1; CID+1713 -72F3 E0100; Adobe-Japan1; CID+18063 -72F4 E0100; Adobe-Japan1; CID+19533 -72F7 E0100; Adobe-Japan1; CID+5631 -72F7 E0101; Hanyo-Denshi; JA6438 -72F7 E0101; Moji_Joho; MJ016958 -72F7 E0102; Hanyo-Denshi; KS229190 -72F7 E0102; Moji_Joho; MJ058029 -72F8 E0100; Adobe-Japan1; CID+2922 -72F9 E0100; Adobe-Japan1; CID+5630 -72FA E0100; Adobe-Japan1; CID+18064 -72FB E0100; Adobe-Japan1; CID+14783 -72FB E0101; Hanyo-Denshi; JB4294 -72FB E0102; Hanyo-Denshi; TK01057310 -72FC E0100; Adobe-Japan1; CID+4059 -72FD E0100; Adobe-Japan1; CID+3352 -72FE E0100; Adobe-Japan1; CID+21964 -7302 E0100; Adobe-Japan1; CID+19534 -7304 E0100; Adobe-Japan1; CID+14784 -7305 E0100; Adobe-Japan1; CID+14785 -7307 E0100; Adobe-Japan1; CID+18065 -730A E0100; Adobe-Japan1; CID+5634 -730B E0100; Adobe-Japan1; CID+19535 -730D E0100; Adobe-Japan1; CID+21965 -7312 E0100; Adobe-Japan1; CID+18066 -7313 E0100; Adobe-Japan1; CID+21966 -7316 E0100; Adobe-Japan1; CID+5636 -7317 E0100; Adobe-Japan1; CID+5633 -7318 E0100; Adobe-Japan1; CID+18067 -7319 E0100; Adobe-Japan1; CID+18068 -731B E0100; Adobe-Japan1; CID+3808 -731C E0100; Adobe-Japan1; CID+5635 -731C E0101; Adobe-Japan1; CID+14158 -731C E0102; Hanyo-Denshi; JA6442 -731C E0102; Moji_Joho; MJ016995 -731C E0103; Hanyo-Denshi; FT2328 -731C E0103; Moji_Joho; MJ016996 -731D E0100; Adobe-Japan1; CID+5637 -731E E0100; Adobe-Japan1; CID+19536 -731F E0100; Adobe-Japan1; CID+3980 -7322 E0100; Adobe-Japan1; CID+19537 -7324 E0100; Adobe-Japan1; CID+8547 -7325 E0100; Adobe-Japan1; CID+5641 -7327 E0100; Adobe-Japan1; CID+16971 -7328 E0100; Adobe-Japan1; CID+14786 -7329 E0100; Adobe-Japan1; CID+5640 -732A E0100; Adobe-Japan1; CID+8548 -732A E0101; Adobe-Japan1; CID+2996 -732A E0102; Hanyo-Denshi; JA3586 -732A E0103; Hanyo-Denshi; JC8779 -732A E0104; Hanyo-Denshi; TK01057410 -732B E0100; Adobe-Japan1; CID+3299 -732B E0101; Hanyo-Denshi; JA3913 -732B E0101; Moji_Joho; MJ017009 -732B E0102; Hanyo-Denshi; KS230510 -732B E0102; Moji_Joho; MJ017010 -732C E0100; Adobe-Japan1; CID+18071 -732E E0100; Adobe-Japan1; CID+1881 -732F E0100; Adobe-Japan1; CID+5639 -7330 E0100; Hanyo-Denshi; IP7330 -7330 E0100; Moji_Joho; MJ017015 -7330 E0101; Hanyo-Denshi; KS230870 -7330 E0101; Moji_Joho; MJ017016 -7331 E0100; Adobe-Japan1; CID+14787 -7332 E0100; Adobe-Japan1; CID+21967 -7333 E0100; Adobe-Japan1; CID+18072 -7334 E0100; Adobe-Japan1; CID+5638 -7335 E0100; Adobe-Japan1; CID+21968 -7336 E0100; Adobe-Japan1; CID+3867 -7336 E0101; Adobe-Japan1; CID+14072 -7336 E0102; Adobe-Japan1; CID+14073 -7336 E0103; Hanyo-Denshi; JA4517 -7336 E0103; Moji_Joho; MJ017023 -7336 E0104; Hanyo-Denshi; JTB585 -7336 E0104; Moji_Joho; MJ017024 -7336 E0105; Hanyo-Denshi; JTB586 -7336 E0105; Moji_Joho; MJ017022 -7336 E0106; Moji_Joho; MJ017025 -7337 E0100; Adobe-Japan1; CID+3868 -7337 E0101; Adobe-Japan1; CID+7804 -7337 E0102; Adobe-Japan1; CID+14074 -7337 E0103; Hanyo-Denshi; JA4518 -7337 E0103; Moji_Joho; MJ017026 -7337 E0104; Hanyo-Denshi; HG1667 -7337 E0104; Moji_Joho; MJ017027 -7339 E0100; Adobe-Japan1; CID+18070 -733A E0100; Adobe-Japan1; CID+19538 -733B E0100; Adobe-Japan1; CID+19539 -733D E0100; Adobe-Japan1; CID+18073 -733E E0100; Adobe-Japan1; CID+5642 -733F E0100; Adobe-Japan1; CID+1296 -7343 E0100; Adobe-Japan1; CID+14788 -7344 E0100; Adobe-Japan1; CID+2056 -7345 E0100; Adobe-Japan1; CID+2224 -7348 E0100; Hanyo-Denshi; IB2366 -7348 E0101; Hanyo-Denshi; TK01057540 -734D E0100; Adobe-Japan1; CID+19540 -734D E0101; Hanyo-Denshi; JB4325 -734D E0101; Moji_Joho; MJ017049 -734D E0102; Hanyo-Denshi; KS231920 -734D E0102; Moji_Joho; MJ017050 -734E E0100; Adobe-Japan1; CID+5643 -734F E0100; Adobe-Japan1; CID+5644 -734F E0101; Hanyo-Denshi; JA6451 -734F E0101; Moji_Joho; MJ017052 -734F E0102; Hanyo-Denshi; KS231660 -734F E0102; Moji_Joho; MJ017053 -7350 E0100; Adobe-Japan1; CID+16972 -7350 E0101; Hanyo-Denshi; JB4326 -7350 E0101; Moji_Joho; MJ017054 -7350 E0102; Hanyo-Denshi; KS231930 -7350 E0102; Moji_Joho; MJ017055 -7352 E0100; Adobe-Japan1; CID+18074 -7352 E0101; Hanyo-Denshi; JB4327 -7352 E0101; Moji_Joho; MJ017057 -7352 E0102; Hanyo-Denshi; JTB58D -7352 E0102; Moji_Joho; MJ017058 -7356 E0100; Adobe-Japan1; CID+21969 -7357 E0100; Adobe-Japan1; CID+5646 -7358 E0100; Adobe-Japan1; CID+19541 -735D E0100; Adobe-Japan1; CID+21970 -735E E0100; Adobe-Japan1; CID+21971 -735E E0101; Hanyo-Denshi; JB4331 -735E E0101; Moji_Joho; MJ017069 -735E E0102; Hanyo-Denshi; IB2368 -735E E0102; Moji_Joho; MJ017070 -735F E0100; Adobe-Japan1; CID+21972 -7360 E0100; Adobe-Japan1; CID+21973 -7363 E0100; Adobe-Japan1; CID+2381 -7363 E0101; Hanyo-Denshi; JA2935 -7363 E0101; Moji_Joho; MJ017076 -7363 E0102; Hanyo-Denshi; KS232430 -7363 E0102; Moji_Joho; MJ017075 -7366 E0100; Adobe-Japan1; CID+16973 -7366 E0101; Hanyo-Denshi; JB4334 -7366 E0101; Moji_Joho; MJ017078 -7366 E0102; Hanyo-Denshi; KS232600 -7366 E0102; Moji_Joho; MJ017079 -7367 E0100; Adobe-Japan1; CID+19542 -7368 E0100; Adobe-Japan1; CID+5648 -7369 E0100; Adobe-Japan1; CID+21974 -736A E0100; Adobe-Japan1; CID+5647 -736B E0100; Adobe-Japan1; CID+18076 -736C E0100; Adobe-Japan1; CID+14789 -736E E0100; Adobe-Japan1; CID+18078 -736F E0100; Adobe-Japan1; CID+18079 -7370 E0100; Adobe-Japan1; CID+5649 -7370 E0101; Hanyo-Denshi; JA6456 -7370 E0101; Moji_Joho; MJ017088 -7370 E0102; Hanyo-Denshi; FT2330 -7370 E0102; Moji_Joho; MJ017089 -7371 E0100; Adobe-Japan1; CID+18080 -7372 E0100; Adobe-Japan1; CID+1451 -7372 E0101; Hanyo-Denshi; JA1945 -7372 E0101; Moji_Joho; MJ017091 -7372 E0102; Hanyo-Denshi; KS232940 -7372 E0102; Moji_Joho; MJ017092 -7375 E0100; Adobe-Japan1; CID+5651 -7377 E0100; Adobe-Japan1; CID+8549 -7378 E0100; Adobe-Japan1; CID+5650 -7378 E0101; Hanyo-Denshi; JA6457 -7378 E0101; Moji_Joho; MJ017098 -7378 E0102; Hanyo-Denshi; KS232830 -7378 E0102; Moji_Joho; MJ040909 -7379 E0100; Adobe-Japan1; CID+21975 -737A E0100; Adobe-Japan1; CID+5653 -737A E0101; Hanyo-Denshi; JA6460 -737A E0101; Moji_Joho; MJ017100 -737A E0102; Hanyo-Denshi; FT2331 -737A E0102; Moji_Joho; MJ017101 -737B E0100; Adobe-Japan1; CID+5652 -737C E0100; Adobe-Japan1; CID+14790 -7380 E0100; Adobe-Japan1; CID+21976 -7381 E0100; Adobe-Japan1; CID+18081 -7381 E0101; Moji_Joho; MJ017108 -7381 E0102; Moji_Joho; MJ017109 -7383 E0100; Adobe-Japan1; CID+14791 -7384 E0100; Adobe-Japan1; CID+1904 -7385 E0100; Adobe-Japan1; CID+14792 -7386 E0100; Adobe-Japan1; CID+14793 -7387 E0100; Adobe-Japan1; CID+3952 -7387 E0101; Adobe-Japan1; CID+14085 -7387 E0102; Hanyo-Denshi; JA4608 -7387 E0102; Moji_Joho; MJ017116 -7387 E0103; Hanyo-Denshi; JTB593 -7387 E0103; Moji_Joho; MJ017115 -7388 E0100; Hanyo-Denshi; IP7388 -7388 E0100; Moji_Joho; MJ017117 -7388 E0101; Hanyo-Denshi; JTB594 -7388 E0101; Moji_Joho; MJ059891 -7389 E0100; Adobe-Japan1; CID+1732 -7389 E0101; Moji_Joho; MJ017118 -7389 E0102; Moji_Joho; MJ017121 -738A E0100; Adobe-Japan1; CID+18082 -738B E0100; Adobe-Japan1; CID+1318 -738B E0101; Adobe-Japan1; CID+13729 -738E E0100; Adobe-Japan1; CID+21977 -7390 E0100; Adobe-Japan1; CID+21978 -7393 E0100; Adobe-Japan1; CID+21979 -7393 E0101; Hanyo-Denshi; JB4352 -7393 E0101; Moji_Joho; MJ017128 -7393 E0102; Hanyo-Denshi; IB2372 -7393 E0102; Moji_Joho; MJ017129 -7394 E0100; Adobe-Japan1; CID+18083 -7395 E0100; Adobe-Japan1; CID+14794 -7396 E0100; Adobe-Japan1; CID+1762 -7397 E0100; Adobe-Japan1; CID+21980 -7398 E0100; Adobe-Japan1; CID+18084 -7398 E0101; Hanyo-Denshi; JB4355 -7398 E0102; Hanyo-Denshi; TK01057720 -739C E0100; Adobe-Japan1; CID+18085 -739E E0100; Adobe-Japan1; CID+14795 -739F E0100; Adobe-Japan1; CID+14796 -739F E0101; Moji_Joho; MJ017139 -739F E0102; Moji_Joho; MJ017140 -73A0 E0100; Adobe-Japan1; CID+14797 -73A1 E0100; Hanyo-Denshi; IP73A1S -73A1 E0101; Hanyo-Denshi; TK01058040 -73A2 E0100; Adobe-Japan1; CID+16974 -73A5 E0100; Adobe-Japan1; CID+18086 -73A6 E0100; Adobe-Japan1; CID+14798 -73A8 E0100; Adobe-Japan1; CID+15423 -73A9 E0100; Adobe-Japan1; CID+1565 -73AA E0100; Adobe-Japan1; CID+21981 -73AA E0101; Hanyo-Denshi; JB4363 -73AA E0101; Moji_Joho; MJ017152 -73AA E0102; Hanyo-Denshi; JTB59DS -73AA E0102; Moji_Joho; MJ059894 -73AA E0103; Hanyo-Denshi; TK01057970 -73AB E0100; Adobe-Japan1; CID+14799 -73AD E0100; Adobe-Japan1; CID+21982 -73AF E0100; Hanyo-Denshi; TK01057770 -73AF E0101; Hanyo-Denshi; TK01057870 -73B2 E0100; Adobe-Japan1; CID+4016 -73B2 E0101; Hanyo-Denshi; JA4672 -73B2 E0102; Hanyo-Denshi; TK01058010 -73B3 E0100; Adobe-Japan1; CID+5655 -73B5 E0100; Adobe-Japan1; CID+14800 -73B6 E0100; Hanyo-Denshi; IP73B6 -73B6 E0101; Hanyo-Denshi; TK01058030 -73B7 E0100; Adobe-Japan1; CID+14801 -73B9 E0100; Adobe-Japan1; CID+18087 -73BA E0100; Adobe-Japan1; CID+13802 -73BA E0101; Hanyo-Denshi; IP73BAS -73BA E0101; Moji_Joho; MJ017170 -73BA E0102; Hanyo-Denshi; KS235290 -73BA E0102; Moji_Joho; MJ017171 -73BB E0100; Adobe-Japan1; CID+5657 -73BC E0100; Adobe-Japan1; CID+14802 -73BD E0100; Adobe-Japan1; CID+8550 -73BF E0100; Adobe-Japan1; CID+18088 -73C0 E0100; Adobe-Japan1; CID+5658 -73C2 E0100; Adobe-Japan1; CID+1361 -73C5 E0100; Adobe-Japan1; CID+18089 -73C6 E0100; Adobe-Japan1; CID+21983 -73C8 E0100; Adobe-Japan1; CID+5654 -73C9 E0100; Adobe-Japan1; CID+8551 -73CA E0100; Adobe-Japan1; CID+2183 -73CA E0101; Adobe-Japan1; CID+7691 -73CA E0102; Adobe-Japan1; CID+20172 -73CA E0103; Hanyo-Denshi; JA2725 -73CA E0103; Moji_Joho; MJ017187 -73CA E0104; Hanyo-Denshi; IB0104 -73CA E0104; Moji_Joho; MJ017188 -73CA E0105; Hanyo-Denshi; FT1813 -73CA E0105; Moji_Joho; MJ017189 -73CA E0106; Hanyo-Denshi; KS235280 -73CA E0106; Moji_Joho; MJ058043 -73CB E0100; Adobe-Japan1; CID+18090 -73CC E0100; Adobe-Japan1; CID+21984 -73CD E0100; Adobe-Japan1; CID+3037 -73CE E0100; Adobe-Japan1; CID+5656 -73CE E0101; Adobe-Japan1; CID+7840 -73CE E0102; Hanyo-Denshi; JA6463 -73CE E0102; Moji_Joho; MJ017193 -73CE E0103; Hanyo-Denshi; FT1965 -73CE E0103; Moji_Joho; MJ017194 -73CF E0100; Adobe-Japan1; CID+14803 -73D2 E0100; Adobe-Japan1; CID+8554 -73D3 E0100; Adobe-Japan1; CID+21985 -73D6 E0100; Adobe-Japan1; CID+8552 -73D9 E0100; Adobe-Japan1; CID+14804 -73DD E0100; Adobe-Japan1; CID+21986 -73DD E0101; Hanyo-Denshi; JB4382 -73DD E0102; Hanyo-Denshi; TK01058190 -73DE E0100; Adobe-Japan1; CID+5661 -73E0 E0100; Adobe-Japan1; CID+2330 -73E1 E0100; Adobe-Japan1; CID+18091 -73E3 E0100; Adobe-Japan1; CID+8553 -73E4 E0100; Adobe-Japan1; CID+15417 -73E5 E0100; Adobe-Japan1; CID+5659 -73E5 E0101; Adobe-Japan1; CID+13563 -73E5 E0102; Moji_Joho; MJ017217 -73E5 E0103; Moji_Joho; MJ017218 -73E6 E0100; Adobe-Japan1; CID+21987 -73E6 E0101; Hanyo-Denshi; JB4385 -73E6 E0102; Hanyo-Denshi; TK01058050 -73E7 E0100; Adobe-Japan1; CID+18092 -73E9 E0100; Adobe-Japan1; CID+14805 -73EA E0100; Adobe-Japan1; CID+1812 -73EA E0101; Hanyo-Denshi; JA2330 -73EA E0102; Hanyo-Denshi; TK01058260 -73EC E0100; Hanyo-Denshi; IP73EC -73EC E0101; Hanyo-Denshi; TK01058180 -73ED E0100; Adobe-Japan1; CID+3421 -73ED E0101; Adobe-Japan1; CID+13489 -73ED E0102; Hanyo-Denshi; JA4041 -73ED E0102; Moji_Joho; MJ017227 -73ED E0103; Hanyo-Denshi; FT1659 -73ED E0103; Moji_Joho; MJ017228 -73EE E0100; Adobe-Japan1; CID+5660 -73F1 E0100; Adobe-Japan1; CID+5687 -73F3 E0100; Hanyo-Denshi; IP73F3SS -73F3 E0101; Hanyo-Denshi; TK01037370 -73F4 E0100; Adobe-Japan1; CID+14806 -73F5 E0100; Adobe-Japan1; CID+8556 -73F5 E0101; Hanyo-Denshi; JB4389 -73F5 E0101; Moji_Joho; MJ017235 -73F5 E0102; Hanyo-Denshi; JTB5A9 -73F5 E0102; Moji_Joho; MJ017236 -73F7 E0100; Adobe-Japan1; CID+21988 -73F8 E0100; Adobe-Japan1; CID+5666 -73F9 E0100; Adobe-Japan1; CID+18093 -73F9 E0101; Hanyo-Denshi; JB4391 -73F9 E0101; Moji_Joho; MJ017240 -73F9 E0102; Hanyo-Denshi; IB2387 -73F9 E0102; Moji_Joho; MJ017241 -73FA E0100; Adobe-Japan1; CID+18095 -73FB E0100; Adobe-Japan1; CID+21989 -73FB E0101; Hanyo-Denshi; JB4393 -73FB E0102; Hanyo-Denshi; TK01058080 -73FD E0100; Adobe-Japan1; CID+14807 -73FD E0101; Moji_Joho; MJ017246 -73FD E0102; Moji_Joho; MJ017247 -73FE E0100; Adobe-Japan1; CID+1905 -73FF E0100; Adobe-Japan1; CID+21990 -7400 E0100; Adobe-Japan1; CID+21991 -7401 E0100; Adobe-Japan1; CID+18096 -7403 E0100; Adobe-Japan1; CID+1663 -7404 E0100; Adobe-Japan1; CID+14808 -7405 E0100; Adobe-Japan1; CID+5663 -7406 E0100; Adobe-Japan1; CID+3943 -7407 E0100; Adobe-Japan1; CID+8555 -7408 E0100; Hanyo-Denshi; IP7408 -7408 E0101; Hanyo-Denshi; TK01058360 -7409 E0100; Adobe-Japan1; CID+3960 -740A E0100; Adobe-Japan1; CID+14809 -740A E0101; Hanyo-Denshi; JB4406 -740A E0101; Moji_Joho; MJ017262 -740A E0102; Hanyo-Denshi; JC8802S -740A E0102; Moji_Joho; MJ017261 -7411 E0100; Adobe-Japan1; CID+21992 -7413 E0100; Adobe-Japan1; CID+18094 -741A E0100; Adobe-Japan1; CID+14810 -741B E0100; Adobe-Japan1; CID+14811 -7421 E0100; Adobe-Japan1; CID+15418 -7422 E0100; Adobe-Japan1; CID+7732 -7422 E0101; Adobe-Japan1; CID+2902 -7422 E0102; Hanyo-Denshi; JA3486 -7422 E0102; Moji_Joho; MJ017282 -7422 E0103; Hanyo-Denshi; IB2407 -7422 E0103; Moji_Joho; MJ030273 -7422 E0104; Hanyo-Denshi; FT2043 -7422 E0104; Moji_Joho; MJ017283 -7422 E0105; Hanyo-Denshi; JC8805 -7422 E0105; Moji_Joho; MJ030271 -7424 E0100; Adobe-Japan1; CID+14812 -7424 E0101; Hanyo-Denshi; JB4410 -7424 E0102; Hanyo-Denshi; TK01058170 -7424 E0103; Hanyo-Denshi; TK01058460 -7425 E0100; Adobe-Japan1; CID+5665 -7425 E0101; Hanyo-Denshi; JA6472 -7425 E0102; Hanyo-Denshi; TK01058590 -7426 E0100; Adobe-Japan1; CID+8557 -7428 E0100; Adobe-Japan1; CID+14813 -7429 E0100; Adobe-Japan1; CID+8559 -742A E0100; Adobe-Japan1; CID+8558 -742A E0101; Moji_Joho; MJ017294 -742A E0102; Moji_Joho; MJ059898 -742B E0100; Adobe-Japan1; CID+16975 -742C E0100; Adobe-Japan1; CID+14814 -742C E0101; Hanyo-Denshi; JB4416 -742C E0102; Hanyo-Denshi; TK01058650 -742D E0100; Adobe-Japan1; CID+21993 -742E E0100; Adobe-Japan1; CID+8560 -742F E0100; Adobe-Japan1; CID+14815 -7430 E0100; Adobe-Japan1; CID+14816 -7431 E0100; Adobe-Japan1; CID+14817 -7431 E0101; Hanyo-Denshi; JB4421 -7431 E0102; Hanyo-Denshi; TK01058560 -7432 E0100; Adobe-Japan1; CID+5667 -7432 E0101; Adobe-Japan1; CID+13564 -7432 E0102; Moji_Joho; MJ017303 -7432 E0103; Moji_Joho; MJ017304 -7433 E0100; Adobe-Japan1; CID+3998 -7434 E0100; Adobe-Japan1; CID+1743 -7434 E0101; Hanyo-Denshi; JA2255 -7434 E0101; Moji_Joho; MJ017306 -7434 E0102; Hanyo-Denshi; IB0752 -7434 E0102; Moji_Joho; MJ017307 -7434 E0103; Hanyo-Denshi; JTB5B8 -7434 E0103; Moji_Joho; MJ017308 -7435 E0100; Adobe-Japan1; CID+3472 -7436 E0100; Adobe-Japan1; CID+3328 -7439 E0100; Adobe-Japan1; CID+14818 -743A E0100; Adobe-Japan1; CID+5668 -743D E0100; Hanyo-Denshi; IP743D -743D E0101; Hanyo-Denshi; TK01058600 -743F E0100; Adobe-Japan1; CID+5670 -7440 E0100; Adobe-Japan1; CID+18098 -7441 E0100; Adobe-Japan1; CID+5673 -7441 E0101; Hanyo-Denshi; JA6480 -7441 E0101; Moji_Joho; MJ017321 -7441 E0102; Hanyo-Denshi; JTB5AF -7441 E0102; Moji_Joho; MJ017322 -7441 E0103; Hanyo-Denshi; KS236400 -7443 E0100; Adobe-Japan1; CID+18099 -7444 E0100; Adobe-Japan1; CID+14819 -7446 E0100; Adobe-Japan1; CID+16976 -7447 E0100; Adobe-Japan1; CID+14820 -7447 E0101; Hanyo-Denshi; JB4427 -7447 E0101; Moji_Joho; MJ017329 -7447 E0102; Hanyo-Denshi; JTB5B1 -7447 E0102; Moji_Joho; MJ017328 -744A E0100; Hanyo-Denshi; IP744A -744A E0100; Moji_Joho; MJ017332 -744A E0101; Hanyo-Denshi; JTB5B4 -744A E0101; Moji_Joho; MJ059902 -744B E0100; Adobe-Japan1; CID+14821 -744B E0101; Hanyo-Denshi; JB4428 -744B E0101; Moji_Joho; MJ017334 -744B E0102; Hanyo-Denshi; JTB5B9 -744B E0102; Moji_Joho; MJ017333 -744B E0103; Moji_Joho; MJ017335 -744D E0100; Adobe-Japan1; CID+14822 -7451 E0100; Adobe-Japan1; CID+14823 -7451 E0101; Hanyo-Denshi; JB4430 -7451 E0101; Moji_Joho; MJ017341 -7451 E0102; Hanyo-Denshi; IB2416 -7451 E0102; Moji_Joho; MJ017342 -7452 E0100; Adobe-Japan1; CID+18100 -7453 E0100; Adobe-Japan1; CID+18097 -7455 E0100; Adobe-Japan1; CID+5669 -7457 E0100; Adobe-Japan1; CID+14824 -7459 E0100; Adobe-Japan1; CID+5672 -7459 E0101; Hanyo-Denshi; JA6479 -7459 E0101; Moji_Joho; MJ017350 -7459 E0102; Hanyo-Denshi; JTB5BD -7459 E0102; Moji_Joho; MJ059905 -745A E0100; Adobe-Japan1; CID+1950 -745B E0100; Adobe-Japan1; CID+1263 -745B E0101; Hanyo-Denshi; JA1745 -745B E0101; Moji_Joho; MJ017352 -745B E0102; Hanyo-Denshi; JTB5BB -745B E0102; Moji_Joho; MJ017353 -745C E0100; Adobe-Japan1; CID+5674 -745C E0101; Hanyo-Denshi; JA6481 -745C E0101; Moji_Joho; MJ017354 -745C E0102; Hanyo-Denshi; FT2333 -745C E0102; Moji_Joho; MJ017355 -745C E0103; Hanyo-Denshi; TK01058620 -745D E0100; Adobe-Japan1; CID+18101 -745E E0100; Adobe-Japan1; CID+2614 -745F E0100; Adobe-Japan1; CID+5671 -745F E0101; Adobe-Japan1; CID+13565 -745F E0102; Moji_Joho; MJ017359 -745F E0103; Moji_Joho; MJ017360 -7460 E0100; Adobe-Japan1; CID+4004 -7462 E0100; Adobe-Japan1; CID+16977 -7462 E0101; Adobe-Japan1; CID+8561 -7462 E0102; Hanyo-Denshi; JB4434 -7462 E0102; Moji_Joho; MJ017363 -7462 E0103; Hanyo-Denshi; JC8819 -7462 E0103; Moji_Joho; MJ017364 -7463 E0100; Adobe-Japan1; CID+5677 -7463 E0101; Hanyo-Denshi; JA6484 -7463 E0101; Moji_Joho; MJ017365 -7463 E0102; Hanyo-Denshi; FT2334 -7463 E0102; Moji_Joho; MJ017366 -7464 E0100; Adobe-Japan1; CID+7477 -7465 E0100; Hanyo-Denshi; IP7465 -7465 E0100; Moji_Joho; MJ017368 -7465 E0101; Hanyo-Denshi; KS237000 -7465 E0101; Moji_Joho; MJ058047 -7466 E0100; Adobe-Japan1; CID+14825 -7467 E0100; Adobe-Japan1; CID+21994 -7468 E0100; Adobe-Japan1; CID+21995 -7468 E0101; Hanyo-Denshi; JB4437 -7468 E0102; Hanyo-Denshi; TK01059040 -7469 E0100; Adobe-Japan1; CID+5675 -746A E0100; Adobe-Japan1; CID+5678 -746B E0100; Adobe-Japan1; CID+14826 -746C E0100; Hanyo-Denshi; IP746C -746C E0100; Moji_Joho; MJ017377 -746C E0101; Hanyo-Denshi; KS237350 -746C E0101; Moji_Joho; MJ017376 -746C E0102; Hanyo-Denshi; TK01058960 -746D E0100; Adobe-Japan1; CID+16978 -746E E0100; Adobe-Japan1; CID+21996 -746E E0101; Hanyo-Denshi; JB4440 -746E E0101; Moji_Joho; MJ017379 -746E E0102; Hanyo-Denshi; JTB5C9 -746E E0102; Moji_Joho; MJ017380 -746F E0100; Adobe-Japan1; CID+5664 -746F E0101; Hanyo-Denshi; JA6471 -746F E0101; Moji_Joho; MJ017381 -746F E0102; Hanyo-Denshi; FT2332 -746F E0102; Moji_Joho; MJ017382 -7470 E0100; Adobe-Japan1; CID+5676 -7471 E0100; Adobe-Japan1; CID+14827 -7471 E0101; Hanyo-Denshi; JB4441 -7471 E0101; Moji_Joho; MJ017384 -7471 E0102; Hanyo-Denshi; KS237240 -7471 E0102; Moji_Joho; MJ017385 -7471 E0103; Hanyo-Denshi; KS237400 -7471 E0103; Moji_Joho; MJ058048 -7471 E0104; Hanyo-Denshi; TK01058700 -7471 E0105; Hanyo-Denshi; TK01058880 -7472 E0100; Adobe-Japan1; CID+19543 -7473 E0100; Adobe-Japan1; CID+2092 -7474 E0100; Hanyo-Denshi; IP7474 -7474 E0100; Moji_Joho; MJ017389 -7474 E0101; Hanyo-Denshi; KS237870 -7474 E0101; Moji_Joho; MJ058049 -7476 E0100; Adobe-Japan1; CID+5679 -7476 E0101; Hanyo-Denshi; JA6486 -7476 E0102; Hanyo-Denshi; TK01059070 -7479 E0100; Hanyo-Denshi; IP7479 -7479 E0101; Hanyo-Denshi; KS237450 -747C E0100; Hanyo-Denshi; IP747C -747C E0101; Hanyo-Denshi; TK01058780 -747E E0100; Adobe-Japan1; CID+5680 -747E E0101; Hanyo-Denshi; JA6487 -747E E0101; Moji_Joho; MJ017400 -747E E0102; Hanyo-Denshi; FT2335 -747E E0102; Moji_Joho; MJ017401 -747E E0103; Hanyo-Denshi; TK01058760 -747E E0104; Hanyo-Denshi; TK01058920 -7480 E0100; Adobe-Japan1; CID+14828 -7481 E0100; Adobe-Japan1; CID+18102 -7481 E0101; Hanyo-Denshi; JB4444 -7481 E0101; Moji_Joho; MJ017404 -7481 E0102; Hanyo-Denshi; KS237860 -7481 E0102; Moji_Joho; MJ017405 -7483 E0100; Adobe-Japan1; CID+3944 -7483 E0101; Hanyo-Denshi; JA4594 -7483 E0101; Moji_Joho; MJ017408 -7483 E0102; Hanyo-Denshi; KS237880 -7483 E0102; Moji_Joho; MJ017409 -7485 E0100; Adobe-Japan1; CID+14829 -7485 E0101; Hanyo-Denshi; JB4445 -7485 E0101; Moji_Joho; MJ017411 -7485 E0102; Hanyo-Denshi; KS238790 -7485 E0102; Moji_Joho; MJ017412 -7486 E0100; Adobe-Japan1; CID+14830 -7487 E0100; Adobe-Japan1; CID+14831 -7488 E0100; Adobe-Japan1; CID+18103 -7489 E0100; Adobe-Japan1; CID+8562 -7489 E0101; Hanyo-Denshi; JB4448 -7489 E0101; Moji_Joho; MJ017417 -7489 E0102; Hanyo-Denshi; IB0753 -7489 E0102; Moji_Joho; MJ017416 -748A E0100; Hanyo-Denshi; IP748A -748A E0100; Moji_Joho; MJ017418 -748A E0101; Hanyo-Denshi; JTB5CA -748A E0101; Moji_Joho; MJ017419 -748B E0100; Adobe-Japan1; CID+5681 -748B E0101; Hanyo-Denshi; JA6488 -748B E0101; Moji_Joho; MJ017420 -748B E0102; Hanyo-Denshi; KS237850 -748B E0102; Moji_Joho; MJ017421 -748F E0100; Adobe-Japan1; CID+21997 -7490 E0100; Adobe-Japan1; CID+14832 -7491 E0100; Adobe-Japan1; CID+21998 -7492 E0100; Adobe-Japan1; CID+18105 -7497 E0100; Adobe-Japan1; CID+18106 -7498 E0100; Adobe-Japan1; CID+14833 -7498 E0101; Hanyo-Denshi; JB4453 -7498 E0101; Moji_Joho; MJ017433 -7498 E0102; Hanyo-Denshi; KS238010 -7498 E0102; Moji_Joho; MJ017432 -7499 E0100; Adobe-Japan1; CID+18107 -749A E0100; Adobe-Japan1; CID+21999 -749C E0100; Adobe-Japan1; CID+14834 -749C E0101; Hanyo-Denshi; JB4456 -749C E0102; Hanyo-Denshi; TK01059310 -749E E0100; Adobe-Japan1; CID+5682 -749F E0100; Adobe-Japan1; CID+8563 -74A0 E0100; Adobe-Japan1; CID+14835 -74A1 E0100; Adobe-Japan1; CID+18108 -74A1 E0101; Hanyo-Denshi; JB4459 -74A1 E0101; Moji_Joho; MJ017443 -74A1 E0102; Hanyo-Denshi; JTB5CE -74A1 E0102; Moji_Joho; MJ017444 -74A2 E0100; Adobe-Japan1; CID+5662 -74A2 E0101; Hanyo-Denshi; JA6469 -74A2 E0102; Hanyo-Denshi; TK01059320 -74A3 E0100; Adobe-Japan1; CID+14836 -74A3 E0101; Hanyo-Denshi; JB4460 -74A3 E0101; Moji_Joho; MJ017446 -74A3 E0102; Hanyo-Denshi; IB2433 -74A3 E0102; Moji_Joho; MJ017448 -74A3 E0103; Hanyo-Denshi; KS238310 -74A3 E0103; Moji_Joho; MJ017447 -74A5 E0100; Adobe-Japan1; CID+18109 -74A5 E0101; Hanyo-Denshi; JD8103 -74A5 E0101; Moji_Joho; MJ017449 -74A5 E0102; Hanyo-Denshi; KS238380 -74A5 E0102; Moji_Joho; MJ017450 -74A6 E0100; Adobe-Japan1; CID+16979 -74A6 E0101; Hanyo-Denshi; JB4461 -74A6 E0101; Moji_Joho; MJ017452 -74A6 E0102; Hanyo-Denshi; KS238390 -74A6 E0102; Moji_Joho; MJ017451 -74A6 E0103; Hanyo-Denshi; KS238930 -74A7 E0100; Adobe-Japan1; CID+5683 -74A8 E0100; Adobe-Japan1; CID+14837 -74A9 E0100; Adobe-Japan1; CID+16980 -74A9 E0101; Hanyo-Denshi; JB4463 -74A9 E0101; Moji_Joho; MJ017455 -74A9 E0102; Hanyo-Denshi; IB2439 -74A9 E0102; Moji_Joho; MJ017456 -74AA E0100; Adobe-Japan1; CID+18110 -74AB E0100; Adobe-Japan1; CID+14838 -74AD E0100; Hanyo-Denshi; IP74AD -74AD E0101; Hanyo-Denshi; TK01059450 -74AE E0100; Adobe-Japan1; CID+22000 -74AF E0100; Adobe-Japan1; CID+19544 -74B0 E0100; Adobe-Japan1; CID+1536 -74B0 E0101; Adobe-Japan1; CID+13689 -74B0 E0102; Hanyo-Denshi; JA2036 -74B0 E0102; Moji_Joho; MJ017465 -74B0 E0103; Hanyo-Denshi; JTB5D5 -74B0 E0103; Moji_Joho; MJ017464 -74B1 E0100; Adobe-Japan1; CID+22001 -74B2 E0100; Adobe-Japan1; CID+22002 -74B2 E0101; Hanyo-Denshi; JB4469 -74B2 E0101; Moji_Joho; MJ017468 -74B2 E0102; Hanyo-Denshi; IB0754 -74B2 E0102; Moji_Joho; MJ017467 -74B5 E0100; Adobe-Japan1; CID+14839 -74B9 E0100; Adobe-Japan1; CID+18111 -74BA E0100; Adobe-Japan1; CID+18113 -74BB E0100; Adobe-Japan1; CID+18112 -74BD E0100; Adobe-Japan1; CID+2257 -74BD E0101; Adobe-Japan1; CID+20173 -74BF E0100; Adobe-Japan1; CID+14840 -74BF E0101; Hanyo-Denshi; JB4473 -74BF E0102; Hanyo-Denshi; TK01059560 -74BF E0103; Hanyo-Denshi; TK01059690 -74BF E0104; Hanyo-Denshi; TK01059740 -74C1 E0100; Hanyo-Denshi; KS238870 -74C1 E0101; Hanyo-Denshi; TK01059670 -74C4 E0100; Hanyo-Denshi; IP74C4 -74C4 E0101; Hanyo-Denshi; TK01059850 -74C8 E0100; Adobe-Japan1; CID+14841 -74C9 E0100; Adobe-Japan1; CID+16981 -74CA E0100; Adobe-Japan1; CID+5684 -74CA E0101; Adobe-Japan1; CID+14159 -74CA E0102; Hanyo-Denshi; JA6491 -74CA E0102; Moji_Joho; MJ017495 -74CA E0103; Hanyo-Denshi; JTB5DA -74CA E0103; Moji_Joho; MJ017496 -74CA E0104; Hanyo-Denshi; JTB5DBS -74CA E0104; Moji_Joho; MJ017497 -74CB E0100; Hanyo-Denshi; IB0755 -74CB E0100; Moji_Joho; MJ017498 -74CB E0101; Hanyo-Denshi; IP74CB -74CB E0101; Moji_Joho; MJ017499 -74CB E0102; Hanyo-Denshi; KS239190 -74CB E0102; Moji_Joho; MJ017500 -74CC E0100; Adobe-Japan1; CID+22003 -74CF E0100; Adobe-Japan1; CID+5685 -74CF E0101; Hanyo-Denshi; JA6492 -74CF E0101; Moji_Joho; MJ017504 -74CF E0102; Hanyo-Denshi; KS239290 -74CF E0102; Moji_Joho; MJ017505 -74D0 E0100; Adobe-Japan1; CID+22004 -74D3 E0100; Adobe-Japan1; CID+22005 -74D3 E0101; Hanyo-Denshi; JB4478 -74D3 E0102; Hanyo-Denshi; TK01059900 -74D4 E0100; Adobe-Japan1; CID+5686 -74D6 E0100; Adobe-Japan1; CID+18114 -74D8 E0100; Adobe-Japan1; CID+18115 -74D8 E0101; Adobe-Japan1; CID+22006 -74D8 E0102; Hanyo-Denshi; JB4479 -74D8 E0102; Moji_Joho; MJ017514 -74D8 E0103; Hanyo-Denshi; JD8110 -74D8 E0103; Moji_Joho; MJ017513 -74DA E0100; Adobe-Japan1; CID+14842 -74DA E0101; Moji_Joho; MJ017516 -74DA E0102; Moji_Joho; MJ017517 -74DB E0100; Adobe-Japan1; CID+22007 -74DC E0100; Adobe-Japan1; CID+1245 -74DC E0101; Adobe-Japan1; CID+13648 -74DC E0102; Hanyo-Denshi; JA1727 -74DC E0102; Moji_Joho; MJ017521 -74DC E0103; Hanyo-Denshi; JTB5DE -74DC E0103; Moji_Joho; MJ017520 -74DC E0104; Hanyo-Denshi; KS239580 -74DC E0104; Moji_Joho; MJ017519 -74DE E0100; Adobe-Japan1; CID+14843 -74DE E0101; Hanyo-Denshi; JB4482 -74DE E0101; Moji_Joho; MJ017524 -74DE E0102; Hanyo-Denshi; KS239770 -74DF E0100; Adobe-Japan1; CID+19545 -74DF E0101; Hanyo-Denshi; JB4483 -74DF E0101; Moji_Joho; MJ017527 -74DF E0102; Hanyo-Denshi; KS239720 -74DF E0102; Moji_Joho; MJ017525 -74DF E0103; Hanyo-Denshi; KS239780 -74DF E0103; Moji_Joho; MJ017526 -74E0 E0100; Adobe-Japan1; CID+5688 -74E0 E0101; Adobe-Japan1; CID+13566 -74E0 E0102; Hanyo-Denshi; JA6501 -74E0 E0102; Moji_Joho; MJ017529 -74E0 E0103; Hanyo-Denshi; FT2909 -74E0 E0103; Moji_Joho; MJ017530 -74E0 E0104; Hanyo-Denshi; JTB5DF -74E0 E0104; Moji_Joho; MJ017528 -74E2 E0100; Adobe-Japan1; CID+3501 -74E2 E0101; Hanyo-Denshi; JA4127 -74E2 E0101; Moji_Joho; MJ017533 -74E2 E0102; Hanyo-Denshi; KS240140 -74E2 E0102; Moji_Joho; MJ017532 -74E3 E0100; Adobe-Japan1; CID+5689 -74E3 E0101; Hanyo-Denshi; JA6502 -74E3 E0101; Moji_Joho; MJ017536 -74E3 E0102; Hanyo-Denshi; KS240210 -74E3 E0102; Moji_Joho; MJ017534 -74E3 E0103; Hanyo-Denshi; KS240220 -74E3 E0103; Moji_Joho; MJ017535 -74E4 E0100; Adobe-Japan1; CID+19546 -74E4 E0101; Hanyo-Denshi; JB4484 -74E4 E0101; Moji_Joho; MJ017538 -74E4 E0102; Hanyo-Denshi; KS240270 -74E4 E0102; Moji_Joho; MJ017537 -74E6 E0100; Adobe-Japan1; CID+1504 -74E6 E0101; Hanyo-Denshi; JA2004 -74E6 E0102; Hanyo-Denshi; TK01060010 -74E7 E0100; Adobe-Japan1; CID+5690 -74E8 E0100; Adobe-Japan1; CID+22008 -74E9 E0100; Adobe-Japan1; CID+5691 -74EA E0100; Adobe-Japan1; CID+22009 -74EB E0100; Adobe-Japan1; CID+18116 -74EE E0100; Adobe-Japan1; CID+5692 -74EE E0101; Hanyo-Denshi; JA6505 -74EE E0101; Moji_Joho; MJ017548 -74EE E0102; Hanyo-Denshi; FT2336 -74EE E0102; Moji_Joho; MJ017549 -74EF E0100; Adobe-Japan1; CID+14160 -74EF E0101; Adobe-Japan1; CID+22010 -74EF E0102; Hanyo-Denshi; JB4488 -74EF E0102; Moji_Joho; MJ017550 -74EF E0103; Hanyo-Denshi; JD8112 -74EF E0103; Moji_Joho; MJ017551 -74F0 E0100; Adobe-Japan1; CID+5694 -74F0 E0101; Hanyo-Denshi; JA6507 -74F0 E0101; Moji_Joho; MJ017552 -74F0 E0102; Hanyo-Denshi; FT2337 -74F0 E0102; Moji_Joho; MJ017553 -74F1 E0100; Adobe-Japan1; CID+5695 -74F2 E0100; Adobe-Japan1; CID+5693 -74F4 E0100; Adobe-Japan1; CID+19547 -74F4 E0101; Hanyo-Denshi; JB4489 -74F4 E0101; Moji_Joho; MJ017557 -74F4 E0102; Hanyo-Denshi; JTB5E5 -74F4 E0102; Moji_Joho; MJ017558 -74F4 E0103; Hanyo-Denshi; TK01060030 -74F6 E0100; Adobe-Japan1; CID+3525 -74F7 E0100; Adobe-Japan1; CID+5697 -74F8 E0100; Adobe-Japan1; CID+5696 -74FA E0100; Adobe-Japan1; CID+18118 -74FB E0100; Adobe-Japan1; CID+19548 -74FC E0100; Adobe-Japan1; CID+22011 -74FF E0100; Adobe-Japan1; CID+16982 -7501 E0100; Adobe-Japan1; CID+8564 -7501 E0101; Moji_Joho; MJ017572 -7501 E0102; Moji_Joho; MJ017573 -7503 E0100; Adobe-Japan1; CID+5699 -7504 E0100; Adobe-Japan1; CID+5698 -7504 E0101; Adobe-Japan1; CID+7841 -7504 E0102; Hanyo-Denshi; JA6511 -7504 E0102; Moji_Joho; MJ017577 -7504 E0103; Hanyo-Denshi; FT1966 -7504 E0104; Moji_Joho; MJ017576 -7504 E0105; Moji_Joho; MJ017578 -7505 E0100; Adobe-Japan1; CID+5700 -7506 E0100; Adobe-Japan1; CID+22012 -7506 E0101; Hanyo-Denshi; JB4494 -7506 E0101; Moji_Joho; MJ017581 -7506 E0102; Hanyo-Denshi; KS241910 -7506 E0102; Moji_Joho; MJ017582 -7506 E0103; Hanyo-Denshi; KS241950 -7506 E0103; Moji_Joho; MJ017583 -750C E0100; Adobe-Japan1; CID+5701 -750C E0101; Adobe-Japan1; CID+13567 -750C E0102; Hanyo-Denshi; JA6514 -750C E0102; Moji_Joho; MJ017589 -750C E0103; Hanyo-Denshi; JTB5EDS -750C E0103; Moji_Joho; MJ017590 -750D E0100; Adobe-Japan1; CID+5703 -750D E0101; Adobe-Japan1; CID+7842 -750D E0102; Hanyo-Denshi; JA6516 -750D E0102; Moji_Joho; MJ017591 -750D E0103; Hanyo-Denshi; KS242060 -750D E0103; Moji_Joho; MJ017592 -750D E0104; Hanyo-Denshi; JTB5EB -750D E0104; Moji_Joho; MJ017593 -750D E0105; Moji_Joho; MJ017594 -750E E0100; Adobe-Japan1; CID+5702 -750E E0101; Hanyo-Denshi; JA6515 -750E E0101; Moji_Joho; MJ017595 -750E E0102; Hanyo-Denshi; JTB5EA -750E E0102; Moji_Joho; MJ017596 -7511 E0100; Adobe-Japan1; CID+2059 -7511 E0101; Adobe-Japan1; CID+7684 -7511 E0102; Adobe-Japan1; CID+13778 -7511 E0103; Adobe-Japan1; CID+20284 -7511 E0104; Hanyo-Denshi; JA2589 -7511 E0104; Moji_Joho; MJ017599 -7511 E0105; Hanyo-Denshi; HG1644 -7511 E0105; Moji_Joho; MJ017601 -7511 E0106; Hanyo-Denshi; FT1806 -7511 E0106; Moji_Joho; MJ017600 -7511 E0107; Moji_Joho; MJ017602 -7512 E0100; Adobe-Japan1; CID+22013 -7513 E0100; Adobe-Japan1; CID+5705 -7515 E0100; Adobe-Japan1; CID+5704 -7515 E0101; Adobe-Japan1; CID+7843 -7515 E0102; Adobe-Japan1; CID+20267 -7515 E0103; Hanyo-Denshi; JA6517 -7515 E0103; Moji_Joho; MJ017606 -7515 E0104; Hanyo-Denshi; JTB5F0 -7515 E0104; Moji_Joho; MJ017608 -7515 E0105; Moji_Joho; MJ017607 -7516 E0100; Adobe-Japan1; CID+19549 -7517 E0100; Adobe-Japan1; CID+16983 -7518 E0100; Adobe-Japan1; CID+1537 -7518 E0101; Hanyo-Denshi; JA2037 -7518 E0102; Hanyo-Denshi; TK01060100 -751A E0100; Adobe-Japan1; CID+2585 -751C E0100; Adobe-Japan1; CID+3126 -751E E0100; Adobe-Japan1; CID+5706 -751F E0100; Adobe-Japan1; CID+2652 -7520 E0100; Adobe-Japan1; CID+18120 -7521 E0100; Adobe-Japan1; CID+19550 -7522 E0100; Adobe-Japan1; CID+13790 -7523 E0100; Adobe-Japan1; CID+2184 -7524 E0100; Adobe-Japan1; CID+18121 -7525 E0100; Adobe-Japan1; CID+1307 -7526 E0100; Adobe-Japan1; CID+5707 -7526 E0101; Adobe-Japan1; CID+20283 -7526 E0102; Moji_Joho; MJ017625 -7526 E0103; Moji_Joho; MJ017626 -7527 E0100; Adobe-Japan1; CID+22014 -7527 E0101; Hanyo-Denshi; JB4507 -7527 E0101; Moji_Joho; MJ017627 -7527 E0102; Hanyo-Denshi; JTB8E5 -7527 E0102; Moji_Joho; MJ017628 -7528 E0100; Adobe-Japan1; CID+3899 -7529 E0100; Adobe-Japan1; CID+22015 -752A E0100; Adobe-Japan1; CID+18122 -752B E0100; Adobe-Japan1; CID+3635 -752C E0100; Adobe-Japan1; CID+5708 -752C E0101; Hanyo-Denshi; JA6521 -752C E0101; Moji_Joho; MJ017633 -752C E0102; Hanyo-Denshi; KS243430 -752C E0102; Moji_Joho; MJ058080 -752F E0100; Adobe-Japan1; CID+8434 -7530 E0100; Adobe-Japan1; CID+3134 -7531 E0100; Adobe-Japan1; CID+3869 -7532 E0100; Adobe-Japan1; CID+2005 -7533 E0100; Adobe-Japan1; CID+2563 -7536 E0100; Adobe-Japan1; CID+22016 -7537 E0100; Adobe-Japan1; CID+2953 -7538 E0100; Adobe-Japan1; CID+4297 -7539 E0100; Adobe-Japan1; CID+22017 -753A E0100; Adobe-Japan1; CID+3018 -753B E0100; Adobe-Japan1; CID+1384 -753B E0101; Hanyo-Denshi; JA1872 -753B E0101; Moji_Joho; MJ017647 -753B E0102; Hanyo-Denshi; KS243790 -753B E0102; Moji_Joho; MJ017646 -753B E0103; Hanyo-Denshi; TK01009560 -753B E0104; Hanyo-Denshi; TK01060450 -753C E0100; Adobe-Japan1; CID+5709 -753D E0100; Adobe-Japan1; CID+18125 -753E E0100; Adobe-Japan1; CID+18126 -753E E0101; Hanyo-Denshi; JB4514 -753E E0101; Moji_Joho; MJ017651 -753E E0102; Hanyo-Denshi; KS244040 -753E E0102; Moji_Joho; MJ017652 -753F E0100; Adobe-Japan1; CID+19551 -7540 E0100; Adobe-Japan1; CID+18127 -7543 E0100; Adobe-Japan1; CID+22018 -7543 E0101; Hanyo-Denshi; JB4517 -7543 E0101; Moji_Joho; MJ017657 -7543 E0102; Hanyo-Denshi; JTB5F6 -7543 E0102; Moji_Joho; MJ017658 -7544 E0100; Adobe-Japan1; CID+5710 -7546 E0100; Adobe-Japan1; CID+5715 -7547 E0100; Adobe-Japan1; CID+22019 -7547 E0101; Hanyo-Denshi; JB4518 -7547 E0101; Moji_Joho; MJ017661 -7547 E0102; Hanyo-Denshi; JTB5F7 -7547 E0102; Moji_Joho; MJ017662 -7548 E0100; Adobe-Japan1; CID+18128 -7549 E0100; Adobe-Japan1; CID+5713 -754A E0100; Adobe-Japan1; CID+5712 -754B E0100; Adobe-Japan1; CID+5063 -754C E0100; Adobe-Japan1; CID+1412 -754D E0100; Adobe-Japan1; CID+5711 -754E E0100; Adobe-Japan1; CID+14844 -754F E0100; Adobe-Japan1; CID+1182 -7550 E0100; Adobe-Japan1; CID+18129 -7551 E0100; Adobe-Japan1; CID+3390 -7552 E0100; Adobe-Japan1; CID+18130 -7554 E0100; Adobe-Japan1; CID+3422 -7554 E0101; Adobe-Japan1; CID+13988 -7554 E0102; Hanyo-Denshi; JA4042 -7554 E0102; Moji_Joho; MJ017676 -7554 E0103; Hanyo-Denshi; JTB5F8 -7554 E0103; Moji_Joho; MJ017675 -7557 E0100; Adobe-Japan1; CID+22020 -7559 E0100; Adobe-Japan1; CID+3961 -7559 E0101; Hanyo-Denshi; JA4617 -7559 E0101; Moji_Joho; MJ017681 -7559 E0102; Hanyo-Denshi; KS244780 -7559 E0102; Moji_Joho; MJ017682 -7559 E0103; Moji_Joho; MJ058087 -755A E0100; Adobe-Japan1; CID+5716 -755B E0100; Adobe-Japan1; CID+5714 -755C E0100; Adobe-Japan1; CID+2970 -755D E0100; Adobe-Japan1; CID+2634 -755D E0101; Adobe-Japan1; CID+20174 -755D E0102; Hanyo-Denshi; JA3206 -755D E0103; Hanyo-Denshi; TK01001540 -755E E0100; Adobe-Japan1; CID+19552 -755F E0100; Adobe-Japan1; CID+22021 -755F E0101; Hanyo-Denshi; JB4525 -755F E0102; Hanyo-Denshi; TK01060650 -7560 E0100; Adobe-Japan1; CID+3391 -7561 E0100; Adobe-Japan1; CID+22022 -7561 E0101; Hanyo-Denshi; JB4526 -7561 E0101; Moji_Joho; MJ017691 -7561 E0102; Hanyo-Denshi; KS245120 -7561 E0102; Moji_Joho; MJ017692 -7562 E0100; Adobe-Japan1; CID+3487 -7564 E0100; Adobe-Japan1; CID+5718 -7565 E0100; Adobe-Japan1; CID+3956 -7566 E0100; Adobe-Japan1; CID+1827 -7567 E0100; Adobe-Japan1; CID+5719 -7569 E0100; Adobe-Japan1; CID+5717 -756A E0100; Adobe-Japan1; CID+3434 -756B E0100; Adobe-Japan1; CID+5720 -756C E0100; Adobe-Japan1; CID+15419 -756D E0100; Adobe-Japan1; CID+5721 -756E E0100; Hanyo-Denshi; IP756E -756E E0101; Hanyo-Denshi; TK01060740 -756F E0100; Adobe-Japan1; CID+8565 -7570 E0100; Adobe-Japan1; CID+1183 -7570 E0101; Hanyo-Denshi; JA1659 -7570 E0101; Moji_Joho; MJ017706 -7570 E0102; Hanyo-Denshi; KS245230 -7570 E0102; Moji_Joho; MJ017707 -7570 E0103; Hanyo-Denshi; KS245140 -7570 E0103; Moji_Joho; MJ058096 -7571 E0100; Adobe-Japan1; CID+18132 -7572 E0100; Adobe-Japan1; CID+18131 -7573 E0100; Adobe-Japan1; CID+2526 -7574 E0100; Adobe-Japan1; CID+5726 -7575 E0100; Adobe-Japan1; CID+14161 -7576 E0100; Adobe-Japan1; CID+5723 -7577 E0100; Adobe-Japan1; CID+3269 -7578 E0100; Adobe-Japan1; CID+5722 -7579 E0100; Adobe-Japan1; CID+14845 -757A E0100; Adobe-Japan1; CID+18133 -757B E0100; Adobe-Japan1; CID+22023 -757C E0100; Adobe-Japan1; CID+22024 -757D E0100; Adobe-Japan1; CID+18134 -757E E0100; Adobe-Japan1; CID+18135 -757F E0100; Adobe-Japan1; CID+1600 -7581 E0100; Adobe-Japan1; CID+14846 -7582 E0100; Adobe-Japan1; CID+5729 -7583 E0100; Hanyo-Denshi; IP7583 -7583 E0100; Moji_Joho; MJ017726 -7583 E0101; Hanyo-Denshi; KS246320 -7583 E0101; Moji_Joho; MJ017727 -7585 E0100; Adobe-Japan1; CID+22025 -7586 E0100; Adobe-Japan1; CID+5724 -7587 E0100; Adobe-Japan1; CID+5725 -7589 E0100; Adobe-Japan1; CID+5728 -758A E0100; Adobe-Japan1; CID+5727 -758B E0100; Adobe-Japan1; CID+3479 -758C E0100; Adobe-Japan1; CID+18136 -758E E0100; Adobe-Japan1; CID+2756 -758F E0100; Adobe-Japan1; CID+2755 -758F E0101; Hanyo-Denshi; JA3333 -758F E0102; Hanyo-Denshi; TK01001710 -7590 E0100; Adobe-Japan1; CID+14847 -7591 E0100; Adobe-Japan1; CID+1625 -7592 E0100; Adobe-Japan1; CID+14848 -7593 E0100; Adobe-Japan1; CID+14849 -7594 E0100; Adobe-Japan1; CID+5730 -7595 E0100; Adobe-Japan1; CID+22026 -7599 E0100; Adobe-Japan1; CID+19553 -759A E0100; Adobe-Japan1; CID+5731 -759C E0100; Adobe-Japan1; CID+22027 -759D E0100; Adobe-Japan1; CID+5732 -75A2 E0100; Adobe-Japan1; CID+18138 -75A3 E0100; Adobe-Japan1; CID+5734 -75A4 E0100; Adobe-Japan1; CID+19554 -75A5 E0100; Adobe-Japan1; CID+5733 -75AB E0100; Adobe-Japan1; CID+1272 -75AB E0101; Hanyo-Denshi; JA1754 -75AB E0102; Hanyo-Denshi; TK01061080 -75B0 E0100; Adobe-Japan1; CID+18140 -75B1 E0100; Adobe-Japan1; CID+5742 -75B1 E0101; Hanyo-Denshi; JA6555 -75B1 E0101; Moji_Joho; MJ017765 -75B1 E0102; Hanyo-Denshi; FT2339S -75B1 E0102; Moji_Joho; MJ017766 -75B2 E0100; Adobe-Japan1; CID+3452 -75B3 E0100; Adobe-Japan1; CID+5736 -75B4 E0100; Adobe-Japan1; CID+14850 -75B5 E0100; Adobe-Japan1; CID+5738 -75B7 E0100; Adobe-Japan1; CID+18141 -75B8 E0100; Adobe-Japan1; CID+5740 -75B9 E0100; Adobe-Japan1; CID+2564 -75BA E0100; Adobe-Japan1; CID+22028 -75BC E0100; Adobe-Japan1; CID+5741 -75BC E0101; Adobe-Japan1; CID+20175 -75BC E0102; Hanyo-Denshi; JA6554 -75BC E0102; Moji_Joho; MJ017777 -75BC E0103; Hanyo-Denshi; HG1651 -75BC E0103; Moji_Joho; MJ017778 -75BD E0100; Adobe-Japan1; CID+5739 -75BE E0100; Adobe-Japan1; CID+2284 -75BF E0100; Adobe-Japan1; CID+18142 -75C0 E0100; Adobe-Japan1; CID+18143 -75C1 E0100; Adobe-Japan1; CID+19555 -75C2 E0100; Adobe-Japan1; CID+5735 -75C3 E0100; Adobe-Japan1; CID+5737 -75C4 E0100; Adobe-Japan1; CID+19556 -75C5 E0100; Adobe-Japan1; CID+3508 -75C5 E0101; Adobe-Japan1; CID+14001 -75C6 E0100; Adobe-Japan1; CID+18144 -75C7 E0100; Adobe-Japan1; CID+2481 -75CA E0100; Adobe-Japan1; CID+5744 -75CA E0101; Hanyo-Denshi; JA6557 -75CA E0101; Moji_Joho; MJ017790 -75CA E0102; Hanyo-Denshi; FT2340 -75CA E0102; Moji_Joho; MJ017791 -75CC E0100; Adobe-Japan1; CID+19557 -75CD E0100; Adobe-Japan1; CID+5743 -75CE E0100; Adobe-Japan1; CID+16985 -75CE E0101; Hanyo-Denshi; JB4553 -75CE E0101; Moji_Joho; MJ017795 -75CE E0102; Hanyo-Denshi; KS248700 -75CE E0102; Moji_Joho; MJ017796 -75CF E0100; Adobe-Japan1; CID+18145 -75D0 E0100; Hanyo-Denshi; IP75D0 -75D0 E0100; Moji_Joho; MJ017798 -75D0 E0101; Hanyo-Denshi; KS249350 -75D0 E0101; Moji_Joho; MJ017799 -75D2 E0100; Adobe-Japan1; CID+5745 -75D3 E0100; Adobe-Japan1; CID+18146 -75D4 E0100; Adobe-Japan1; CID+2258 -75D5 E0100; Adobe-Japan1; CID+2079 -75D7 E0100; Adobe-Japan1; CID+19558 -75D8 E0100; Adobe-Japan1; CID+3185 -75D9 E0100; Adobe-Japan1; CID+5746 -75DB E0100; Adobe-Japan1; CID+3047 -75DC E0100; Adobe-Japan1; CID+19559 -75DC E0101; Hanyo-Denshi; JB4556 -75DC E0101; Moji_Joho; MJ017810 -75DC E0102; Hanyo-Denshi; KS249360 -75DC E0102; Moji_Joho; MJ017811 -75DD E0100; Adobe-Japan1; CID+18147 -75DE E0100; Adobe-Japan1; CID+5748 -75DF E0100; Adobe-Japan1; CID+18148 -75E0 E0100; Adobe-Japan1; CID+18149 -75E1 E0100; Adobe-Japan1; CID+19560 -75E2 E0100; Adobe-Japan1; CID+3945 -75E3 E0100; Adobe-Japan1; CID+5747 -75E4 E0100; Adobe-Japan1; CID+14851 -75E7 E0100; Adobe-Japan1; CID+18150 -75E9 E0100; Adobe-Japan1; CID+2795 -75EC E0100; Adobe-Japan1; CID+14162 -75EE E0100; Adobe-Japan1; CID+18151 -75EF E0100; Adobe-Japan1; CID+19561 -75F0 E0100; Adobe-Japan1; CID+5753 -75F1 E0100; Adobe-Japan1; CID+18152 -75F2 E0100; Adobe-Japan1; CID+5755 -75F3 E0100; Adobe-Japan1; CID+5756 -75F4 E0100; Adobe-Japan1; CID+2962 -75F9 E0100; Adobe-Japan1; CID+14852 -75FA E0100; Adobe-Japan1; CID+5754 -75FB E0100; Hanyo-Denshi; IP75FB -75FB E0100; Moji_Joho; MJ017839 -75FB E0101; Hanyo-Denshi; JTB608 -75FB E0101; Moji_Joho; MJ017840 -75FC E0100; Adobe-Japan1; CID+5751 -75FE E0100; Adobe-Japan1; CID+5749 -75FF E0100; Adobe-Japan1; CID+5750 -7600 E0100; Adobe-Japan1; CID+14853 -7600 E0101; Hanyo-Denshi; JB4567 -7600 E0101; Moji_Joho; MJ017846 -7600 E0102; Hanyo-Denshi; IB2466 -7600 E0102; Moji_Joho; MJ017845 -7601 E0100; Adobe-Japan1; CID+5752 -7602 E0100; Adobe-Japan1; CID+16986 -7603 E0100; Adobe-Japan1; CID+18153 -7603 E0101; Moji_Joho; MJ017849 -7603 E0102; Moji_Joho; MJ017850 -7604 E0100; Adobe-Japan1; CID+19562 -7607 E0100; Adobe-Japan1; CID+18155 -7608 E0100; Adobe-Japan1; CID+16987 -7608 E0101; Adobe-Japan1; CID+20177 -7608 E0102; Hanyo-Denshi; JB4572 -7608 E0102; Moji_Joho; MJ017853 -7608 E0103; Hanyo-Denshi; JC8850 -7608 E0103; Moji_Joho; MJ017854 -7608 E0104; Hanyo-Denshi; KS250740 -7608 E0104; Moji_Joho; MJ058122 -7609 E0100; Adobe-Japan1; CID+5759 -7609 E0101; Hanyo-Denshi; JA6572 -7609 E0101; Moji_Joho; MJ017855 -7609 E0102; Hanyo-Denshi; FT2341 -7609 E0102; Moji_Joho; MJ017856 -760A E0100; Adobe-Japan1; CID+14854 -760B E0100; Adobe-Japan1; CID+5757 -760C E0100; Adobe-Japan1; CID+19563 -760D E0100; Adobe-Japan1; CID+5758 -760F E0100; Adobe-Japan1; CID+18156 -7612 E0100; Adobe-Japan1; CID+22029 -7613 E0100; Adobe-Japan1; CID+18159 -7615 E0100; Adobe-Japan1; CID+14855 -7616 E0100; Adobe-Japan1; CID+14856 -7616 E0101; Hanyo-Denshi; JB4579 -7616 E0101; Moji_Joho; MJ017869 -7616 E0102; Hanyo-Denshi; JTB609 -7616 E0102; Moji_Joho; MJ017870 -7618 E0100; Adobe-Japan1; CID+18154 -7619 E0100; Adobe-Japan1; CID+14857 -761B E0100; Adobe-Japan1; CID+18160 -761B E0101; Hanyo-Denshi; JB4581 -761B E0101; Moji_Joho; MJ017874 -761B E0102; Hanyo-Denshi; KS251370 -761B E0102; Moji_Joho; MJ017875 -761B E0103; Hanyo-Denshi; KS251360 -761B E0103; Moji_Joho; MJ058123 -761C E0100; Adobe-Japan1; CID+18161 -761D E0100; Adobe-Japan1; CID+19564 -761E E0100; Adobe-Japan1; CID+14858 -761F E0100; Adobe-Japan1; CID+5760 -761F E0101; Hanyo-Denshi; JA6573 -761F E0101; Moji_Joho; MJ017880 -761F E0102; Hanyo-Denshi; FT2342 -761F E0102; Moji_Joho; MJ017879 -7620 E0100; Adobe-Japan1; CID+5762 -7621 E0100; Adobe-Japan1; CID+5763 -7622 E0100; Adobe-Japan1; CID+5764 -7622 E0101; Hanyo-Denshi; JA6577 -7622 E0101; Moji_Joho; MJ017883 -7622 E0102; Hanyo-Denshi; JTB610S -7622 E0102; Moji_Joho; MJ017884 -7623 E0100; Adobe-Japan1; CID+22030 -7624 E0100; Adobe-Japan1; CID+5765 -7625 E0100; Adobe-Japan1; CID+18163 -7626 E0100; Adobe-Japan1; CID+13893 -7626 E0101; Adobe-Japan1; CID+7725 -7626 E0102; Hanyo-Denshi; JB4587 -7626 E0102; Moji_Joho; MJ017888 -7626 E0103; Hanyo-Denshi; HG1642 -7626 E0103; Moji_Joho; MJ017889 -7627 E0100; Adobe-Japan1; CID+5761 -7627 E0101; Hanyo-Denshi; JA6574 -7627 E0101; Moji_Joho; MJ017890 -7627 E0102; Hanyo-Denshi; FT2343 -7627 E0102; Moji_Joho; MJ017891 -7628 E0100; Adobe-Japan1; CID+18164 -7629 E0100; Adobe-Japan1; CID+22031 -7629 E0101; Hanyo-Denshi; JB4588 -7629 E0101; Moji_Joho; MJ017893 -7629 E0102; Hanyo-Denshi; KS251340 -7629 E0102; Moji_Joho; MJ017894 -762D E0100; Adobe-Japan1; CID+14859 -7630 E0100; Adobe-Japan1; CID+5767 -7632 E0100; Adobe-Japan1; CID+19565 -7633 E0100; Adobe-Japan1; CID+18166 -7634 E0100; Adobe-Japan1; CID+5766 -7634 E0101; Hanyo-Denshi; JA6579 -7634 E0101; Moji_Joho; MJ017903 -7634 E0102; Hanyo-Denshi; KS251910 -7634 E0102; Moji_Joho; MJ017904 -7635 E0100; Adobe-Japan1; CID+14860 -7638 E0100; Adobe-Japan1; CID+19566 -7639 E0100; Adobe-Japan1; CID+22032 -763A E0100; Adobe-Japan1; CID+22033 -763B E0100; Adobe-Japan1; CID+5768 -763C E0100; Adobe-Japan1; CID+18165 -763C E0101; Hanyo-Denshi; JB4602 -763C E0101; Moji_Joho; MJ017912 -763C E0102; Hanyo-Denshi; KS251690 -763C E0102; Moji_Joho; MJ017913 -7640 E0100; Adobe-Japan1; CID+22034 -7641 E0100; Adobe-Japan1; CID+18169 -7641 E0101; Hanyo-Denshi; JB4605 -7641 E0101; Moji_Joho; MJ017917 -7641 E0102; Hanyo-Denshi; KS251990 -7641 E0102; Moji_Joho; MJ017916 -7642 E0100; Adobe-Japan1; CID+3981 -7643 E0100; Adobe-Japan1; CID+14861 -7644 E0100; Adobe-Japan1; CID+22035 -7645 E0100; Adobe-Japan1; CID+19567 -7646 E0100; Adobe-Japan1; CID+5771 -7647 E0100; Adobe-Japan1; CID+5769 -7647 E0101; Hanyo-Denshi; JA6582 -7647 E0101; Moji_Joho; MJ017923 -7647 E0102; Hanyo-Denshi; JTB612 -7647 E0102; Moji_Joho; MJ017924 -7648 E0100; Adobe-Japan1; CID+5770 -7649 E0100; Adobe-Japan1; CID+18171 -764A E0100; Adobe-Japan1; CID+19568 -764B E0100; Adobe-Japan1; CID+14862 -764C E0100; Adobe-Japan1; CID+1566 -764E E0100; Adobe-Japan1; CID+14163 -7650 E0100; Hanyo-Denshi; IP7650 -7650 E0100; Moji_Joho; MJ017932 -7650 E0101; Hanyo-Denshi; JTB614S -7650 E0101; Moji_Joho; MJ017933 -7652 E0100; Adobe-Japan1; CID+3850 -7652 E0101; Adobe-Japan1; CID+7803 -7652 E0102; Hanyo-Denshi; JA4494 -7652 E0102; Moji_Joho; MJ017935 -7652 E0103; Hanyo-Denshi; KS252820 -7652 E0103; Moji_Joho; MJ017936 -7652 E0104; Hanyo-Denshi; FT1931 -7652 E0104; Moji_Joho; MJ017937 -7655 E0100; Adobe-Japan1; CID+18172 -7656 E0100; Adobe-Japan1; CID+3610 -7658 E0100; Adobe-Japan1; CID+5773 -7658 E0101; Hanyo-Denshi; JA6586 -7658 E0101; Moji_Joho; MJ017943 -7658 E0102; Hanyo-Denshi; KS252670 -7658 E0102; Moji_Joho; MJ017944 -7659 E0100; Adobe-Japan1; CID+22036 -765C E0100; Adobe-Japan1; CID+5772 -765F E0100; Adobe-Japan1; CID+19569 -7661 E0100; Adobe-Japan1; CID+5774 -7662 E0100; Adobe-Japan1; CID+5775 -7662 E0101; Hanyo-Denshi; JA6588 -7662 E0101; Moji_Joho; MJ017952 -7662 E0102; Hanyo-Denshi; FT2346 -7662 E0102; Moji_Joho; MJ017954 -7662 E0103; Hanyo-Denshi; KS253070 -7662 E0103; Moji_Joho; MJ058126 -7662 E0104; Moji_Joho; MJ017953 -7664 E0100; Adobe-Japan1; CID+16988 -7664 E0101; Adobe-Japan1; CID+20178 -7665 E0100; Adobe-Japan1; CID+14863 -7665 E0101; Hanyo-Denshi; JB4615 -7665 E0101; Moji_Joho; MJ017956 -7665 E0102; Hanyo-Denshi; KS253220S -7665 E0102; Moji_Joho; MJ017957 -7667 E0100; Adobe-Japan1; CID+5779 -7668 E0100; Adobe-Japan1; CID+5776 -7669 E0100; Adobe-Japan1; CID+5777 -7669 E0101; Adobe-Japan1; CID+20179 -7669 E0102; Hanyo-Denshi; JA6590 -7669 E0102; Moji_Joho; MJ017961 -7669 E0103; Hanyo-Denshi; FT2347 -7669 E0103; Moji_Joho; MJ017962 -766A E0100; Adobe-Japan1; CID+5778 -766C E0100; Adobe-Japan1; CID+5780 -766D E0100; Adobe-Japan1; CID+14864 -766E E0100; Adobe-Japan1; CID+18174 -766F E0100; Adobe-Japan1; CID+14865 -7670 E0100; Adobe-Japan1; CID+5781 -7671 E0100; Adobe-Japan1; CID+14866 -7671 E0101; Hanyo-Denshi; JB4619 -7671 E0101; Moji_Joho; MJ017969 -7671 E0102; Hanyo-Denshi; JTB61A -7671 E0102; Moji_Joho; MJ017970 -7672 E0100; Adobe-Japan1; CID+5782 -7672 E0101; Adobe-Japan1; CID+13568 -7672 E0102; Hanyo-Denshi; JA6601 -7672 E0102; Moji_Joho; MJ017971 -7672 E0103; Hanyo-Denshi; FT1714 -7672 E0103; Moji_Joho; MJ017972 -7672 E0104; Hanyo-Denshi; FT2349 -7672 E0104; Moji_Joho; MJ017973 -7672 E0105; Hanyo-Denshi; JTC0C4 -7672 E0105; Moji_Joho; MJ017974 -7674 E0100; Adobe-Japan1; CID+14867 -7676 E0100; Adobe-Japan1; CID+5783 -7678 E0100; Adobe-Japan1; CID+5784 -767A E0100; Adobe-Japan1; CID+3395 -767A E0101; Hanyo-Denshi; JA4015 -767A E0102; Hanyo-Denshi; TK01061160 -767B E0100; Adobe-Japan1; CID+3146 -767C E0100; Adobe-Japan1; CID+5785 -767D E0100; Adobe-Japan1; CID+3368 -767D E0101; Hanyo-Denshi; JA3982 -767D E0102; Hanyo-Denshi; TK01061210 -767E E0100; Adobe-Japan1; CID+3494 -7680 E0100; Adobe-Japan1; CID+5786 -7680 E0101; Hanyo-Denshi; JA6605 -7680 E0101; Moji_Joho; MJ017987 -7680 E0102; Hanyo-Denshi; JTB621 -7680 E0102; Moji_Joho; MJ017991 -7681 E0100; Adobe-Japan1; CID+16989 -7682 E0100; Adobe-Japan1; CID+8566 -7682 E0101; Moji_Joho; MJ017989 -7682 E0102; Moji_Joho; MJ017990 -7683 E0100; Adobe-Japan1; CID+5787 -7684 E0100; Adobe-Japan1; CID+3108 -7684 E0101; Adobe-Japan1; CID+13945 -7684 E0102; Hanyo-Denshi; JA3710 -7684 E0102; Moji_Joho; MJ017993 -7684 E0103; Hanyo-Denshi; KS254180 -7684 E0103; Moji_Joho; MJ017994 -7685 E0100; Adobe-Japan1; CID+22037 -7686 E0100; Adobe-Japan1; CID+1413 -7687 E0100; Adobe-Japan1; CID+2006 -7688 E0100; Adobe-Japan1; CID+5788 -768A E0100; Hanyo-Denshi; IP768A -768A E0101; Hanyo-Denshi; TK01061460 -768B E0100; Adobe-Japan1; CID+5789 -768B E0101; Hanyo-Denshi; JA6608 -768B E0102; Hanyo-Denshi; TK01061380 -768C E0100; Adobe-Japan1; CID+22038 -768D E0100; Adobe-Japan1; CID+22039 -768D E0101; Hanyo-Denshi; JB4624 -768D E0101; Moji_Joho; MJ018005 -768D E0102; Hanyo-Denshi; JTB625 -768D E0102; Moji_Joho; MJ018006 -768E E0100; Adobe-Japan1; CID+5790 -768E E0101; Moji_Joho; MJ018007 -768E E0102; Moji_Joho; MJ018008 -7690 E0100; Adobe-Japan1; CID+2167 -7693 E0100; Adobe-Japan1; CID+5792 -7693 E0101; Adobe-Japan1; CID+7844 -7693 E0102; Hanyo-Denshi; JA6611 -7693 E0102; Moji_Joho; MJ018013 -7693 E0103; Hanyo-Denshi; FT1969 -7693 E0103; Moji_Joho; MJ018012 -7695 E0100; Adobe-Japan1; CID+18175 -7696 E0100; Adobe-Japan1; CID+5791 -7697 E0100; Hanyo-Denshi; IP7697 -7697 E0101; Hanyo-Denshi; TK01061700 -7699 E0100; Adobe-Japan1; CID+5793 -769A E0100; Adobe-Japan1; CID+5794 -769B E0100; Adobe-Japan1; CID+8569 -769C E0100; Adobe-Japan1; CID+8567 -769C E0101; Hanyo-Denshi; JB4627 -769C E0102; Hanyo-Denshi; TK01061780 -769D E0100; Adobe-Japan1; CID+16990 -769E E0100; Adobe-Japan1; CID+8568 -769E E0101; Hanyo-Denshi; JC8867 -769E E0101; Moji_Joho; MJ018026 -769E E0102; Hanyo-Denshi; JTB62DS -769E E0102; Moji_Joho; MJ018027 -769F E0100; Adobe-Japan1; CID+22040 -76A0 E0100; Adobe-Japan1; CID+18177 -76A1 E0100; Adobe-Japan1; CID+18176 -76A2 E0100; Adobe-Japan1; CID+22041 -76A3 E0100; Adobe-Japan1; CID+22042 -76A3 E0101; Hanyo-Denshi; JB4632 -76A3 E0101; Moji_Joho; MJ018032 -76A3 E0102; Hanyo-Denshi; KS255110 -76A3 E0102; Moji_Joho; MJ018033 -76A3 E0103; Hanyo-Denshi; TK01061810 -76A4 E0100; Adobe-Japan1; CID+14868 -76A5 E0100; Adobe-Japan1; CID+14869 -76A6 E0100; Adobe-Japan1; CID+8570 -76A7 E0100; Adobe-Japan1; CID+18178 -76A7 E0101; Hanyo-Denshi; JB4636 -76A7 E0101; Moji_Joho; MJ018039 -76A7 E0102; Hanyo-Denshi; KS255220 -76A7 E0102; Moji_Joho; MJ018038 -76A8 E0100; Adobe-Japan1; CID+18179 -76AA E0100; Adobe-Japan1; CID+16991 -76AD E0100; Adobe-Japan1; CID+19570 -76AE E0100; Adobe-Japan1; CID+3453 -76AF E0100; Adobe-Japan1; CID+18180 -76B0 E0100; Adobe-Japan1; CID+5795 -76B0 E0101; Hanyo-Denshi; JA6614 -76B0 E0101; Moji_Joho; MJ018048 -76B0 E0102; Hanyo-Denshi; FT2351S -76B0 E0102; Moji_Joho; MJ018049 -76B4 E0100; Adobe-Japan1; CID+5796 -76B4 E0101; Moji_Joho; MJ018051 -76B4 E0102; Moji_Joho; MJ018052 -76B6 E0100; Adobe-Japan1; CID+16992 -76B6 E0101; Moji_Joho; MJ018055 -76B6 E0102; Moji_Joho; MJ018056 -76B7 E0100; Adobe-Japan1; CID+7452 -76B7 E0101; Hanyo-Denshi; JA8373 -76B7 E0101; Moji_Joho; MJ018057 -76B7 E0102; Hanyo-Denshi; JTB631 -76B7 E0102; Moji_Joho; MJ018058 -76B8 E0100; Adobe-Japan1; CID+5797 -76B9 E0100; Adobe-Japan1; CID+5798 -76BA E0100; Adobe-Japan1; CID+5799 -76BD E0100; Adobe-Japan1; CID+19571 -76BF E0100; Adobe-Japan1; CID+2172 -76C1 E0100; Adobe-Japan1; CID+22043 -76C2 E0100; Adobe-Japan1; CID+5800 -76C3 E0100; Adobe-Japan1; CID+3340 -76C5 E0100; Adobe-Japan1; CID+14870 -76C6 E0100; Adobe-Japan1; CID+3725 -76C6 E0101; Adobe-Japan1; CID+13508 -76C6 E0102; Hanyo-Denshi; JA4363 -76C6 E0102; Moji_Joho; MJ018072 -76C6 E0103; Hanyo-Denshi; FT1673 -76C6 E0103; Moji_Joho; MJ018073 -76C6 E0104; Hanyo-Denshi; TK01062070 -76C8 E0100; Adobe-Japan1; CID+1264 -76C9 E0100; Adobe-Japan1; CID+18182 -76CA E0100; Adobe-Japan1; CID+1273 -76CA E0101; Adobe-Japan1; CID+8571 -76CA E0102; Hanyo-Denshi; JA1755 -76CA E0102; Moji_Joho; MJ018079 -76CA E0103; Hanyo-Denshi; JTFA17 -76CA E0104; Hanyo-Denshi; KS386420 -76CA E0104; Moji_Joho; MJ058674 -76CA E0105; Moji_Joho; MJ059934 -76CB E0100; Adobe-Japan1; CID+22044 -76CC E0100; Adobe-Japan1; CID+14871 -76CD E0100; Adobe-Japan1; CID+5801 -76CE E0100; Adobe-Japan1; CID+16993 -76D2 E0100; Adobe-Japan1; CID+5803 -76D4 E0100; Adobe-Japan1; CID+16994 -76D4 E0101; Adobe-Japan1; CID+22045 -76D4 E0102; Hanyo-Denshi; JB4647 -76D4 E0102; Moji_Joho; MJ018086 -76D4 E0103; Hanyo-Denshi; JC8874 -76D4 E0103; Moji_Joho; MJ018087 -76D6 E0100; Adobe-Japan1; CID+5802 -76D7 E0100; Adobe-Japan1; CID+3178 -76D9 E0100; Adobe-Japan1; CID+19572 -76DB E0100; Adobe-Japan1; CID+2653 -76DB E0101; Adobe-Japan1; CID+13868 -76DB E0102; Hanyo-Denshi; JA3225 -76DB E0102; Moji_Joho; MJ018093 -76DB E0103; Hanyo-Denshi; JTB63A -76DB E0103; Moji_Joho; MJ018094 -76DC E0100; Adobe-Japan1; CID+5336 -76DE E0100; Adobe-Japan1; CID+5804 -76DF E0100; Adobe-Japan1; CID+3789 -76DF E0101; Adobe-Japan1; CID+14053 -76DF E0102; Hanyo-Denshi; JA4433 -76DF E0102; Moji_Joho; MJ018098 -76DF E0103; Hanyo-Denshi; JTB63D -76DF E0103; Moji_Joho; MJ018099 -76E0 E0100; Adobe-Japan1; CID+22046 -76E1 E0100; Adobe-Japan1; CID+5805 -76E1 E0101; Hanyo-Denshi; JA6624 -76E1 E0101; Moji_Joho; MJ018101 -76E1 E0102; Hanyo-Denshi; KS257870 -76E1 E0102; Moji_Joho; MJ058149 -76E3 E0100; Adobe-Japan1; CID+1538 -76E3 E0101; Hanyo-Denshi; JA2038 -76E3 E0101; Moji_Joho; MJ018103 -76E3 E0102; Hanyo-Denshi; IB0759 -76E3 E0102; Moji_Joho; MJ018104 -76E4 E0100; Adobe-Japan1; CID+3435 -76E5 E0100; Adobe-Japan1; CID+5806 -76E6 E0100; Adobe-Japan1; CID+16995 -76E7 E0100; Adobe-Japan1; CID+5807 -76E8 E0100; Adobe-Japan1; CID+18184 -76EA E0100; Adobe-Japan1; CID+5808 -76EB E0100; Adobe-Japan1; CID+19573 -76EC E0100; Adobe-Japan1; CID+14872 -76EE E0100; Adobe-Japan1; CID+3816 -76F0 E0100; Adobe-Japan1; CID+19574 -76F1 E0100; Adobe-Japan1; CID+16996 -76F2 E0100; Adobe-Japan1; CID+3809 -76F2 E0101; Adobe-Japan1; CID+14057 -76F2 E0102; Hanyo-Denshi; JA4453 -76F2 E0102; Moji_Joho; MJ018121 -76F2 E0103; Hanyo-Denshi; KS258810 -76F2 E0103; Moji_Joho; MJ018120 -76F4 E0100; Adobe-Japan1; CID+3034 -76F4 E0101; Adobe-Japan1; CID+13934 -76F4 E0102; Hanyo-Denshi; JA3630 -76F4 E0102; Moji_Joho; MJ018123 -76F4 E0103; Hanyo-Denshi; JTB643 -76F4 E0103; Moji_Joho; MJ018124 -76F4 E0104; Hanyo-Denshi; KS000900S -76F4 E0104; Moji_Joho; MJ056839 -76F4 E0105; Hanyo-Denshi; KS000910 -76F4 E0105; Moji_Joho; MJ056840 -76F4 E0106; Hanyo-Denshi; KS003740 -76F4 E0107; Hanyo-Denshi; TK01062370 -76F6 E0100; Adobe-Japan1; CID+22047 -76F8 E0100; Adobe-Japan1; CID+2796 -76F9 E0100; Adobe-Japan1; CID+19575 -76FB E0100; Adobe-Japan1; CID+5810 -76FB E0101; Hanyo-Denshi; JA6629 -76FB E0101; Moji_Joho; MJ018132 -76FB E0102; Hanyo-Denshi; FT2352 -76FB E0102; Moji_Joho; MJ018133 -76FC E0100; Adobe-Japan1; CID+14873 -76FE E0100; Adobe-Japan1; CID+2412 -7700 E0100; Adobe-Japan1; CID+19576 -7701 E0100; Adobe-Japan1; CID+2482 -7704 E0100; Adobe-Japan1; CID+5813 -7704 E0101; Hanyo-Denshi; JA6632 -7704 E0101; Moji_Joho; MJ018142 -7704 E0102; Hanyo-Denshi; JTB645 -7704 E0102; Moji_Joho; MJ018143 -7706 E0100; Adobe-Japan1; CID+22048 -7707 E0100; Adobe-Japan1; CID+5812 -7708 E0100; Adobe-Japan1; CID+5811 -7709 E0100; Adobe-Japan1; CID+3473 -770A E0100; Adobe-Japan1; CID+16997 -770B E0100; Adobe-Japan1; CID+1539 -770C E0100; Adobe-Japan1; CID+1885 -770E E0100; Adobe-Japan1; CID+19577 -7712 E0100; Adobe-Japan1; CID+22049 -7714 E0100; Adobe-Japan1; CID+22050 -7714 E0101; Hanyo-Denshi; JB4663 -7714 E0101; Moji_Joho; MJ018159 -7714 E0102; Hanyo-Denshi; KS260290 -7714 E0102; Moji_Joho; MJ018160 -7715 E0100; Adobe-Japan1; CID+22051 -7717 E0100; Adobe-Japan1; CID+18186 -7719 E0100; Adobe-Japan1; CID+16998 -771A E0100; Adobe-Japan1; CID+18187 -771B E0100; Adobe-Japan1; CID+5819 -771C E0100; Adobe-Japan1; CID+22052 -771E E0100; Adobe-Japan1; CID+13357 -771E E0101; Adobe-Japan1; CID+5816 -771E E0102; Hanyo-Denshi; JA6635 -771E E0102; Moji_Joho; MJ018170 -771E E0103; Hanyo-Denshi; JTB651 -771E E0103; Moji_Joho; MJ018171 -771E E0104; Hanyo-Denshi; JTB64B -771E E0105; Hanyo-Denshi; KS017440 -771E E0105; Moji_Joho; MJ056990 -771E E0106; Hanyo-Denshi; JTB652 -771E E0106; Moji_Joho; MJ018172 -771F E0100; Adobe-Japan1; CID+2565 -771F E0101; Adobe-Japan1; CID+13854 -771F E0102; Hanyo-Denshi; JA3131 -771F E0102; Moji_Joho; MJ018173 -771F E0103; Hanyo-Denshi; KS017450 -771F E0103; Moji_Joho; MJ056991 -771F E0104; Hanyo-Denshi; IB2489 -771F E0105; Hanyo-Denshi; JTB649 -771F E0105; Moji_Joho; MJ018174 -771F E0106; Hanyo-Denshi; TK01062480 -771F E0107; Moji_Joho; MJ018175 -7720 E0100; Adobe-Japan1; CID+3774 -7722 E0100; Adobe-Japan1; CID+19578 -7724 E0100; Adobe-Japan1; CID+5815 -7725 E0100; Adobe-Japan1; CID+5817 -7726 E0100; Adobe-Japan1; CID+5818 -7728 E0100; Adobe-Japan1; CID+19579 -7729 E0100; Adobe-Japan1; CID+5814 -772B E0100; Hanyo-Denshi; IP772B -772B E0100; Moji_Joho; MJ018189 -772B E0101; Hanyo-Denshi; KS260360 -772B E0101; Moji_Joho; MJ018190 -772D E0100; Adobe-Japan1; CID+18188 -772E E0100; Adobe-Japan1; CID+22053 -772F E0100; Adobe-Japan1; CID+19580 -7734 E0100; Adobe-Japan1; CID+14874 -7735 E0100; Adobe-Japan1; CID+18189 -7736 E0100; Adobe-Japan1; CID+14875 -7737 E0100; Adobe-Japan1; CID+5820 -7737 E0101; Adobe-Japan1; CID+20181 -7737 E0102; Hanyo-Denshi; JA6639 -7737 E0102; Moji_Joho; MJ018201 -7737 E0103; Hanyo-Denshi; FT2353 -7737 E0103; Moji_Joho; MJ018202 -7738 E0100; Adobe-Japan1; CID+5821 -7739 E0100; Adobe-Japan1; CID+19581 -7739 E0101; Hanyo-Denshi; JB4677 -7739 E0102; Hanyo-Denshi; TK01062700 -773A E0100; Adobe-Japan1; CID+3019 -773A E0101; Adobe-Japan1; CID+13478 -773C E0100; Adobe-Japan1; CID+1567 -773D E0100; Adobe-Japan1; CID+22054 -773E E0100; Adobe-Japan1; CID+19582 -773E E0101; Hanyo-Denshi; JB4679 -773E E0101; Moji_Joho; MJ018210 -773E E0102; Hanyo-Denshi; KS261040 -773E E0102; Moji_Joho; MJ058166 -773E E0103; Hanyo-Denshi; KS261050 -773E E0103; Moji_Joho; MJ058167 -7740 E0100; Adobe-Japan1; CID+2979 -7740 E0101; Hanyo-Denshi; JA3569 -7740 E0101; Moji_Joho; MJ018213 -7740 E0102; Hanyo-Denshi; KS260980 -7740 E0102; Moji_Joho; MJ018212 -7742 E0100; Adobe-Japan1; CID+22055 -7745 E0100; Adobe-Japan1; CID+19583 -7746 E0100; Adobe-Japan1; CID+8572 -7747 E0100; Adobe-Japan1; CID+5822 -774A E0100; Adobe-Japan1; CID+19584 -774A E0101; Hanyo-Denshi; JB4683 -774A E0101; Moji_Joho; MJ018224 -774A E0102; Hanyo-Denshi; KS260750 -774A E0102; Moji_Joho; MJ018223 -774D E0100; Adobe-Japan1; CID+16999 -774E E0100; Adobe-Japan1; CID+17000 -774F E0100; Adobe-Japan1; CID+19585 -7752 E0100; Adobe-Japan1; CID+22056 -7756 E0100; Adobe-Japan1; CID+22057 -7757 E0100; Adobe-Japan1; CID+22058 -7758 E0100; Adobe-Japan1; CID+18194 -775A E0100; Adobe-Japan1; CID+5823 -775B E0100; Adobe-Japan1; CID+5826 -775B E0101; Hanyo-Denshi; JA6645 -775B E0101; Moji_Joho; MJ018240 -775B E0102; Hanyo-Denshi; FT2354 -775B E0102; Moji_Joho; MJ018241 -775C E0100; Adobe-Japan1; CID+14876 -775E E0100; Adobe-Japan1; CID+19586 -775F E0100; Adobe-Japan1; CID+14877 -7760 E0100; Adobe-Japan1; CID+14878 -7761 E0100; Adobe-Japan1; CID+2605 -7762 E0100; Adobe-Japan1; CID+7877 -7763 E0100; Adobe-Japan1; CID+3228 -7764 E0100; Adobe-Japan1; CID+19587 -7765 E0100; Adobe-Japan1; CID+5827 -7766 E0100; Adobe-Japan1; CID+3713 -7767 E0100; Adobe-Japan1; CID+19588 -7768 E0100; Adobe-Japan1; CID+5824 -776A E0100; Adobe-Japan1; CID+14165 -776B E0100; Adobe-Japan1; CID+5825 -776C E0100; Adobe-Japan1; CID+19589 -776D E0100; Hanyo-Denshi; IP776D -776D E0100; Moji_Joho; MJ018259 -776D E0101; Hanyo-Denshi; JT776D -776D E0101; Moji_Joho; MJ018260 -7770 E0100; Adobe-Japan1; CID+22059 -7770 E0101; Hanyo-Denshi; JB4705 -7770 E0101; Moji_Joho; MJ018263 -7770 E0102; Hanyo-Denshi; KS262670 -7770 E0102; Moji_Joho; MJ018264 -7772 E0100; Adobe-Japan1; CID+14879 -7773 E0100; Adobe-Japan1; CID+22060 -7774 E0100; Adobe-Japan1; CID+22061 -7779 E0100; Adobe-Japan1; CID+5830 -7779 E0101; Hanyo-Denshi; JA6649 -7779 E0101; Moji_Joho; MJ018273 -7779 E0102; Hanyo-Denshi; FT2355 -7779 E0102; Moji_Joho; MJ018274 -777A E0100; Adobe-Japan1; CID+17001 -777C E0100; Adobe-Japan1; CID+18196 -777D E0100; Adobe-Japan1; CID+14880 -777E E0100; Adobe-Japan1; CID+5829 -777E E0101; Adobe-Japan1; CID+20182 -777F E0100; Adobe-Japan1; CID+5828 -777F E0101; Hanyo-Denshi; JA6647 -777F E0102; Hanyo-Denshi; TK01040100 -7780 E0100; Adobe-Japan1; CID+17002 -7784 E0100; Adobe-Japan1; CID+19590 -7784 E0101; Hanyo-Denshi; JB4712 -7784 E0101; Moji_Joho; MJ018285 -7784 E0102; Hanyo-Denshi; KS263260 -7784 E0102; Moji_Joho; MJ018286 -7787 E0100; Hanyo-Denshi; IP7787 -7787 E0101; Hanyo-Denshi; TK01063140 -778B E0100; Adobe-Japan1; CID+5832 -778B E0101; Hanyo-Denshi; JA6651 -778B E0101; Moji_Joho; MJ018293 -778B E0102; Hanyo-Denshi; FT2357 -778B E0102; Moji_Joho; MJ018294 -778C E0100; Adobe-Japan1; CID+19591 -778D E0100; Adobe-Japan1; CID+19592 -778D E0101; Adobe-Japan1; CID+22062 -778E E0100; Adobe-Japan1; CID+5831 -778E E0101; Hanyo-Denshi; JA6650 -778E E0101; Moji_Joho; MJ018297 -778E E0102; Hanyo-Denshi; KS263980 -778E E0102; Moji_Joho; MJ018298 -778E E0103; Hanyo-Denshi; FT2356 -778E E0103; Moji_Joho; MJ018299 -7791 E0100; Adobe-Japan1; CID+5833 -7794 E0100; Adobe-Japan1; CID+17003 -7795 E0100; Adobe-Japan1; CID+14881 -7795 E0101; Hanyo-Denshi; JB4716 -7795 E0101; Moji_Joho; MJ018304 -7795 E0102; Hanyo-Denshi; KS264610 -7795 E0102; Moji_Joho; MJ018305 -7796 E0100; Adobe-Japan1; CID+19593 -779A E0100; Adobe-Japan1; CID+18199 -779E E0100; Adobe-Japan1; CID+5835 -779F E0100; Adobe-Japan1; CID+18200 -77A0 E0100; Adobe-Japan1; CID+5834 -77A2 E0100; Adobe-Japan1; CID+18201 -77A2 E0101; Adobe-Japan1; CID+22063 -77A2 E0102; Hanyo-Denshi; JB4720 -77A2 E0102; Moji_Joho; MJ018319 -77A2 E0103; Hanyo-Denshi; JD8216 -77A2 E0103; Moji_Joho; MJ018318 -77A4 E0100; Adobe-Japan1; CID+18202 -77A5 E0100; Adobe-Japan1; CID+3613 -77A5 E0101; Adobe-Japan1; CID+7790 -77A5 E0102; Hanyo-Denshi; JA4245 -77A5 E0102; Moji_Joho; MJ018322 -77A5 E0103; Hanyo-Denshi; FT1917 -77A5 E0103; Moji_Joho; MJ018321 -77A7 E0100; Adobe-Japan1; CID+19594 -77A9 E0100; Adobe-Japan1; CID+14166 -77AA E0100; Adobe-Japan1; CID+14882 -77AC E0100; Adobe-Japan1; CID+2400 -77AC E0101; Adobe-Japan1; CID+13458 -77AC E0102; Hanyo-Denshi; JA2954 -77AC E0102; Moji_Joho; MJ018331 -77AC E0103; Hanyo-Denshi; KS264890 -77AC E0103; Moji_Joho; MJ018330 -77AC E0104; Moji_Joho; MJ018332 -77AD E0100; Adobe-Japan1; CID+3982 -77AE E0100; Adobe-Japan1; CID+22064 -77AF E0100; Adobe-Japan1; CID+19595 -77B0 E0100; Adobe-Japan1; CID+5836 -77B1 E0100; Adobe-Japan1; CID+22065 -77B1 E0101; Hanyo-Denshi; JB4725 -77B1 E0101; Moji_Joho; MJ018337 -77B1 E0102; Hanyo-Denshi; KS265210 -77B1 E0102; Moji_Joho; MJ018338 -77B3 E0100; Adobe-Japan1; CID+3215 -77B3 E0101; Hanyo-Denshi; JA3823 -77B3 E0101; Moji_Joho; MJ018340 -77B3 E0102; Hanyo-Denshi; KS265200 -77B3 E0102; Moji_Joho; MJ018341 -77B5 E0100; Adobe-Japan1; CID+22066 -77B5 E0101; Hanyo-Denshi; JB4726 -77B5 E0101; Moji_Joho; MJ018344 -77B5 E0102; Hanyo-Denshi; KS265040 -77B5 E0102; Moji_Joho; MJ018343 -77B6 E0100; Adobe-Japan1; CID+5837 -77B7 E0100; Adobe-Japan1; CID+19596 -77B9 E0100; Adobe-Japan1; CID+5838 -77BB E0100; Adobe-Japan1; CID+5842 -77BC E0100; Adobe-Japan1; CID+5840 -77BD E0100; Adobe-Japan1; CID+5841 -77BE E0100; Adobe-Japan1; CID+19597 -77BF E0100; Adobe-Japan1; CID+5839 -77C3 E0100; Adobe-Japan1; CID+22067 -77C5 E0100; Hanyo-Denshi; IP77C5 -77C5 E0101; Hanyo-Denshi; TK01063240 -77C6 E0100; Hanyo-Denshi; IP77C6 -77C6 E0101; Hanyo-Denshi; KS265750 -77C7 E0100; Adobe-Japan1; CID+5843 -77C7 E0101; Hanyo-Denshi; JA6662 -77C7 E0101; Moji_Joho; MJ018362 -77C7 E0102; Hanyo-Denshi; KS265760 -77C7 E0102; Moji_Joho; MJ018363 -77C7 E0103; Hanyo-Denshi; FT2358 -77C7 E0103; Moji_Joho; MJ018364 -77C9 E0100; Adobe-Japan1; CID+19598 -77CC E0100; Hanyo-Denshi; IP77CC -77CC E0100; Moji_Joho; MJ018367 -77CC E0101; Hanyo-Denshi; JTB667 -77CC E0101; Moji_Joho; MJ018368 -77CC E0102; Hanyo-Denshi; TK01063250 -77CD E0100; Adobe-Japan1; CID+5844 -77D1 E0100; Adobe-Japan1; CID+19599 -77D2 E0100; Adobe-Japan1; CID+22068 -77D2 E0101; Hanyo-Denshi; JB4731 -77D2 E0101; Moji_Joho; MJ018376 -77D2 E0102; Hanyo-Denshi; JTB668 -77D2 E0102; Moji_Joho; MJ018375 -77D4 E0100; Hanyo-Denshi; IP77D4 -77D4 E0101; Hanyo-Denshi; KS266380 -77D5 E0100; Adobe-Japan1; CID+22069 -77D7 E0100; Adobe-Japan1; CID+5845 -77D7 E0101; Moji_Joho; MJ018382 -77D7 E0102; Moji_Joho; MJ018383 -77D9 E0100; Adobe-Japan1; CID+19600 -77DA E0100; Adobe-Japan1; CID+5846 -77DB E0100; Adobe-Japan1; CID+3779 -77DC E0100; Adobe-Japan1; CID+5847 -77DE E0100; Adobe-Japan1; CID+18203 -77DF E0100; Adobe-Japan1; CID+18204 -77E0 E0100; Adobe-Japan1; CID+17004 -77E2 E0100; Adobe-Japan1; CID+3836 -77E3 E0100; Adobe-Japan1; CID+5848 -77E4 E0100; Adobe-Japan1; CID+18205 -77E5 E0100; Adobe-Japan1; CID+2956 -77E6 E0100; Adobe-Japan1; CID+14883 -77E7 E0100; Adobe-Japan1; CID+3360 -77E9 E0100; Adobe-Japan1; CID+1763 -77E9 E0101; Adobe-Japan1; CID+13732 -77E9 E0102; Hanyo-Denshi; JA2275 -77E9 E0102; Moji_Joho; MJ018401 -77E9 E0103; Hanyo-Denshi; JTB66B -77E9 E0103; Moji_Joho; MJ018402 -77EA E0100; Adobe-Japan1; CID+18206 -77EC E0100; Adobe-Japan1; CID+18207 -77ED E0100; Adobe-Japan1; CID+2937 -77EE E0100; Adobe-Japan1; CID+5849 -77EF E0100; Adobe-Japan1; CID+1714 -77F0 E0100; Adobe-Japan1; CID+14884 -77F1 E0100; Adobe-Japan1; CID+19601 -77F1 E0101; Hanyo-Denshi; JB4742 -77F1 E0101; Moji_Joho; MJ018409 -77F1 E0102; Hanyo-Denshi; KS268340 -77F1 E0102; Moji_Joho; MJ018410 -77F3 E0100; Adobe-Japan1; CID+2676 -77F3 E0101; Hanyo-Denshi; JA3248 -77F3 E0102; Hanyo-Denshi; TK01063470 -77F4 E0100; Adobe-Japan1; CID+14885 -77F8 E0100; Adobe-Japan1; CID+22070 -77FB E0100; Adobe-Japan1; CID+18208 -77FC E0100; Adobe-Japan1; CID+5850 -7802 E0100; Adobe-Japan1; CID+2093 -7802 E0101; Hanyo-Denshi; JA2629 -7802 E0102; Hanyo-Denshi; TK01063570 -7805 E0100; Adobe-Japan1; CID+18210 -7806 E0100; Adobe-Japan1; CID+14886 -7809 E0100; Adobe-Japan1; CID+18211 -7809 E0101; Hanyo-Denshi; JB4748 -7809 E0101; Moji_Joho; MJ018431 -7809 E0102; Hanyo-Denshi; KS268990 -7809 E0102; Moji_Joho; MJ018432 -780C E0100; Adobe-Japan1; CID+5851 -780D E0100; Adobe-Japan1; CID+18212 -780E E0100; Adobe-Japan1; CID+22071 -7810 E0100; Hanyo-Denshi; IP7810 -7810 E0101; Hanyo-Denshi; TK01063610 -7811 E0100; Adobe-Japan1; CID+22072 -7811 E0101; Hanyo-Denshi; JB4751 -7811 E0101; Moji_Joho; MJ018442 -7811 E0102; Hanyo-Denshi; JB4751S -7811 E0102; Moji_Joho; MJ018441 -7812 E0100; Adobe-Japan1; CID+5852 -7814 E0100; Adobe-Japan1; CID+1882 -7815 E0100; Adobe-Japan1; CID+2117 -7819 E0100; Adobe-Japan1; CID+18213 -781D E0100; Adobe-Japan1; CID+22073 -7820 E0100; Adobe-Japan1; CID+5854 -7821 E0100; Adobe-Japan1; CID+8574 -7822 E0100; Adobe-Japan1; CID+14887 -7823 E0100; Adobe-Japan1; CID+22074 -7825 E0100; Adobe-Japan1; CID+3152 -7826 E0100; Adobe-Japan1; CID+2118 -7827 E0100; Adobe-Japan1; CID+1640 -782C E0100; Adobe-Japan1; CID+18214 -782D E0100; Adobe-Japan1; CID+14888 -782E E0100; Adobe-Japan1; CID+14889 -7830 E0100; Adobe-Japan1; CID+14890 -7831 E0100; Hanyo-Denshi; IP7831 -7831 E0101; Hanyo-Denshi; TK01063700 -7832 E0100; Adobe-Japan1; CID+3666 -7832 E0101; Adobe-Japan1; CID+14023 -7832 E0102; Hanyo-Denshi; JA4304 -7832 E0102; Moji_Joho; MJ018471 -7832 E0103; Hanyo-Denshi; JTB672 -7832 E0103; Moji_Joho; MJ018470 -7834 E0100; Adobe-Japan1; CID+3329 -7835 E0100; Adobe-Japan1; CID+14891 -7837 E0100; Adobe-Japan1; CID+19602 -783A E0100; Adobe-Japan1; CID+3153 -783A E0101; Adobe-Japan1; CID+13951 -783F E0100; Adobe-Japan1; CID+2030 -7842 E0100; Hanyo-Denshi; IP7842 -7842 E0101; Hanyo-Denshi; TK01063790 -7843 E0100; Adobe-Japan1; CID+17006 -7844 E0100; Adobe-Japan1; CID+22075 -7845 E0100; Adobe-Japan1; CID+5856 -7847 E0100; Adobe-Japan1; CID+18215 -7848 E0100; Adobe-Japan1; CID+22076 -784C E0100; Adobe-Japan1; CID+22077 -784E E0100; Adobe-Japan1; CID+8575 -784E E0101; Hanyo-Denshi; JB4766 -784E E0101; Moji_Joho; MJ018493 -784E E0102; Hanyo-Denshi; JTB67C -784E E0102; Moji_Joho; MJ018494 -784F E0100; Adobe-Japan1; CID+13342 -784F E0101; Hanyo-Denshi; JC8903 -784F E0101; Moji_Joho; MJ018495 -784F E0102; Hanyo-Denshi; JTB674 -784F E0102; Moji_Joho; MJ018496 -7851 E0100; Adobe-Japan1; CID+15420 -7852 E0100; Adobe-Japan1; CID+22078 -785C E0100; Adobe-Japan1; CID+19603 -785D E0100; Adobe-Japan1; CID+2483 -785D E0101; Adobe-Japan1; CID+13837 -785D E0102; Hanyo-Denshi; JA3043 -785D E0102; Moji_Joho; MJ018503 -785D E0103; Hanyo-Denshi; JTB676 -785D E0103; Moji_Joho; MJ018502 -785E E0100; Adobe-Japan1; CID+22079 -785E E0101; Hanyo-Denshi; JB4769 -785E E0102; Hanyo-Denshi; TK01063860 -7860 E0100; Adobe-Japan1; CID+22080 -7861 E0100; Adobe-Japan1; CID+22081 -7863 E0100; Adobe-Japan1; CID+22082 -7864 E0100; Adobe-Japan1; CID+8576 -7868 E0100; Adobe-Japan1; CID+14892 -786A E0100; Adobe-Japan1; CID+18216 -786B E0100; Adobe-Japan1; CID+3962 -786B E0101; Hanyo-Denshi; JA4618 -786B E0101; Moji_Joho; MJ018519 -786B E0102; Hanyo-Denshi; KS270260 -786B E0102; Moji_Joho; MJ018518 -786C E0100; Adobe-Japan1; CID+2007 -786C E0101; Adobe-Japan1; CID+13443 -786C E0102; Moji_Joho; MJ018520 -786C E0103; Moji_Joho; MJ018521 -786E E0100; Adobe-Japan1; CID+17007 -786E E0101; Hanyo-Denshi; JB4776 -786E E0101; Moji_Joho; MJ018523 -786E E0102; Hanyo-Denshi; JTB678 -786E E0102; Moji_Joho; MJ018524 -786F E0100; Adobe-Japan1; CID+1883 -7872 E0100; Adobe-Japan1; CID+3383 -7874 E0100; Adobe-Japan1; CID+5858 -7874 E0101; Hanyo-Denshi; JA6677 -7874 E0101; Moji_Joho; MJ018529 -7874 E0102; Hanyo-Denshi; KS271490 -7874 E0102; Moji_Joho; MJ018530 -787A E0100; Adobe-Japan1; CID+8577 -787A E0101; Hanyo-Denshi; JB4777 -787A E0101; Moji_Joho; MJ018533 -787A E0102; Hanyo-Denshi; IB2520 -787A E0102; Moji_Joho; MJ018534 -787B E0100; Moji_Joho; MJ018535 -787B E0101; Moji_Joho; MJ018536 -787C E0100; Adobe-Japan1; CID+5860 -787C E0101; Adobe-Japan1; CID+7845 -787C E0102; Hanyo-Denshi; JA6679 -787C E0102; Moji_Joho; MJ018538 -787C E0103; Hanyo-Denshi; FT1970 -787C E0103; Moji_Joho; MJ018537 -787E E0100; Adobe-Japan1; CID+19604 -7881 E0100; Adobe-Japan1; CID+1951 -7883 E0100; Hanyo-Denshi; IP7883 -7883 E0101; Hanyo-Denshi; TK01063930 -7886 E0100; Adobe-Japan1; CID+5859 -7887 E0100; Adobe-Japan1; CID+3090 -788A E0100; Adobe-Japan1; CID+18218 -788C E0100; Adobe-Japan1; CID+5862 -788C E0101; Hanyo-Denshi; JA6681 -788C E0101; Moji_Joho; MJ018555 -788C E0102; Hanyo-Denshi; FT2360S -788C E0102; Moji_Joho; MJ018556 -788D E0100; Adobe-Japan1; CID+1429 -788E E0100; Adobe-Japan1; CID+5857 -788F E0100; Adobe-Japan1; CID+22083 -7891 E0100; Adobe-Japan1; CID+13379 -7891 E0101; Adobe-Japan1; CID+3454 -7891 E0102; Hanyo-Denshi; JA4074 -7891 E0103; Hanyo-Denshi; JC8907 -7893 E0100; Adobe-Japan1; CID+1234 -7894 E0100; Adobe-Japan1; CID+18219 -7895 E0100; Adobe-Japan1; CID+2140 -7897 E0100; Adobe-Japan1; CID+4088 -7898 E0100; Adobe-Japan1; CID+19605 -789A E0100; Adobe-Japan1; CID+5861 -789D E0100; Adobe-Japan1; CID+18221 -789E E0100; Adobe-Japan1; CID+14893 -789F E0100; Adobe-Japan1; CID+18222 -78A1 E0100; Adobe-Japan1; CID+19606 -78A3 E0100; Adobe-Japan1; CID+5863 -78A3 E0101; Hanyo-Denshi; JA6682 -78A3 E0101; Moji_Joho; MJ018577 -78A3 E0102; Hanyo-Denshi; FT2361 -78A3 E0102; Moji_Joho; MJ018578 -78A4 E0100; Adobe-Japan1; CID+18220 -78A4 E0101; Hanyo-Denshi; JB4787 -78A4 E0101; Moji_Joho; MJ018579 -78A4 E0102; Hanyo-Denshi; JTB684 -78A4 E0102; Moji_Joho; MJ018580 -78A7 E0100; Adobe-Japan1; CID+3611 -78A8 E0100; Adobe-Japan1; CID+22084 -78A9 E0100; Adobe-Japan1; CID+2685 -78AA E0100; Adobe-Japan1; CID+5865 -78AA E0101; Hanyo-Denshi; JA6684 -78AA E0102; Hanyo-Denshi; TK01063950 -78AC E0100; Adobe-Japan1; CID+22085 -78AD E0100; Adobe-Japan1; CID+17010 -78AF E0100; Adobe-Japan1; CID+5866 -78B0 E0100; Adobe-Japan1; CID+17008 -78B0 E0101; Hanyo-Denshi; JB4791 -78B0 E0101; Moji_Joho; MJ018593 -78B0 E0102; Hanyo-Denshi; IB2523 -78B0 E0102; Moji_Joho; MJ018592 -78B1 E0100; Adobe-Japan1; CID+19607 -78B2 E0100; Adobe-Japan1; CID+22086 -78B3 E0100; Adobe-Japan1; CID+19608 -78B5 E0100; Adobe-Japan1; CID+5864 -78BA E0100; Adobe-Japan1; CID+1452 -78BA E0101; Hanyo-Denshi; JA1946 -78BA E0101; Moji_Joho; MJ018598 -78BA E0102; Hanyo-Denshi; KS273100 -78BA E0102; Moji_Joho; MJ018599 -78BB E0100; Adobe-Japan1; CID+18223 -78BB E0101; Hanyo-Denshi; JB4801 -78BB E0102; Hanyo-Denshi; TK01064060 -78BC E0100; Adobe-Japan1; CID+5872 -78BD E0100; Adobe-Japan1; CID+22087 -78BE E0100; Adobe-Japan1; CID+5871 -78BF E0100; Adobe-Japan1; CID+22088 -78C1 E0100; Adobe-Japan1; CID+2259 -78C1 E0101; Hanyo-Denshi; JA2807 -78C1 E0101; Moji_Joho; MJ018607 -78C1 E0102; Hanyo-Denshi; KS272620 -78C1 E0102; Moji_Joho; MJ018608 -78C2 E0100; Hanyo-Denshi; IP78C2 -78C2 E0101; Hanyo-Denshi; TK01064050 -78C4 E0100; Hanyo-Denshi; IP78C4 -78C4 E0101; Hanyo-Denshi; TK01064040 -78C5 E0100; Adobe-Japan1; CID+5873 -78C5 E0101; Hanyo-Denshi; JA6692 -78C5 E0101; Moji_Joho; MJ018614 -78C5 E0102; Hanyo-Denshi; KS272650 -78C5 E0102; Moji_Joho; MJ018615 -78C6 E0100; Adobe-Japan1; CID+5868 -78C7 E0100; Adobe-Japan1; CID+22089 -78C8 E0100; Adobe-Japan1; CID+14894 -78C9 E0100; Adobe-Japan1; CID+19609 -78CA E0100; Adobe-Japan1; CID+5874 -78CB E0100; Adobe-Japan1; CID+5869 -78CC E0100; Adobe-Japan1; CID+14895 -78CC E0101; Hanyo-Denshi; JB4807 -78CC E0101; Moji_Joho; MJ018622 -78CC E0102; Hanyo-Denshi; IB2526 -78CC E0102; Moji_Joho; MJ018623 -78CD E0100; Hanyo-Denshi; IP78CD -78CD E0100; Moji_Joho; MJ018624 -78CD E0101; Hanyo-Denshi; KS272630 -78CD E0101; Moji_Joho; MJ018625 -78CE E0100; Adobe-Japan1; CID+14896 -78CF E0100; Hanyo-Denshi; IP78CF -78CF E0101; Hanyo-Denshi; TK01064020 -78D0 E0100; Adobe-Japan1; CID+3436 -78D1 E0100; Adobe-Japan1; CID+5867 -78D2 E0100; Adobe-Japan1; CID+22090 -78D3 E0100; Adobe-Japan1; CID+19610 -78D3 E0101; Hanyo-Denshi; JB4810 -78D3 E0101; Moji_Joho; MJ018633 -78D3 E0102; Hanyo-Denshi; IB0763 -78D3 E0102; Moji_Joho; MJ018632 -78D4 E0100; Adobe-Japan1; CID+5870 -78D4 E0101; Adobe-Japan1; CID+13570 -78D4 E0102; Hanyo-Denshi; JA6689 -78D4 E0102; Moji_Joho; MJ018635 -78D4 E0103; Hanyo-Denshi; JTB689 -78D4 E0103; Moji_Joho; MJ018634 -78D4 E0104; Moji_Joho; MJ018636 -78D4 E0105; Moji_Joho; MJ018637 -78D5 E0100; Adobe-Japan1; CID+18224 -78D6 E0100; Adobe-Japan1; CID+22091 -78DA E0100; Adobe-Japan1; CID+5877 -78DB E0100; Adobe-Japan1; CID+22092 -78DF E0100; Adobe-Japan1; CID+22093 -78E0 E0100; Adobe-Japan1; CID+14898 -78E1 E0100; Adobe-Japan1; CID+14899 -78E4 E0100; Adobe-Japan1; CID+14897 -78E6 E0100; Adobe-Japan1; CID+18225 -78E7 E0100; Adobe-Japan1; CID+5876 -78E8 E0100; Adobe-Japan1; CID+3727 -78E8 E0101; Adobe-Japan1; CID+14042 -78E8 E0102; Hanyo-Denshi; JA4365 -78E8 E0102; Moji_Joho; MJ018655 -78E8 E0103; Hanyo-Denshi; JTB68C -78E8 E0103; Moji_Joho; MJ018654 -78EA E0100; Adobe-Japan1; CID+22094 -78EC E0100; Adobe-Japan1; CID+5875 -78EF E0100; Adobe-Japan1; CID+1199 -78EF E0101; Adobe-Japan1; CID+13643 -78EF E0102; Hanyo-Denshi; JA1675 -78EF E0102; Moji_Joho; MJ018661 -78EF E0103; Hanyo-Denshi; KS273540 -78EF E0103; Moji_Joho; MJ018662 -78EF E0104; Hanyo-Denshi; JTC0ED -78EF E0104; Moji_Joho; MJ018663 -78F2 E0100; Adobe-Japan1; CID+14900 -78F3 E0100; Adobe-Japan1; CID+22095 -78F4 E0100; Adobe-Japan1; CID+5879 -78F6 E0100; Adobe-Japan1; CID+22096 -78F7 E0100; Adobe-Japan1; CID+14901 -78F7 E0101; Hanyo-Denshi; JB4824 -78F7 E0101; Moji_Joho; MJ018672 -78F7 E0102; Hanyo-Denshi; JTB691 -78F7 E0102; Moji_Joho; MJ018671 -78F9 E0100; Adobe-Japan1; CID+18226 -78F9 E0101; Hanyo-Denshi; JD8255 -78F9 E0101; Moji_Joho; MJ018675 -78F9 E0102; Hanyo-Denshi; IP78F9 -78F9 E0102; Moji_Joho; MJ018674 -78FA E0100; Adobe-Japan1; CID+18227 -78FB E0100; Adobe-Japan1; CID+14902 -78FD E0100; Adobe-Japan1; CID+5878 -78FE E0100; Adobe-Japan1; CID+18228 -78FF E0100; Adobe-Japan1; CID+22097 -7900 E0100; Adobe-Japan1; CID+17011 -7901 E0100; Adobe-Japan1; CID+2484 -7906 E0100; Adobe-Japan1; CID+22098 -7907 E0100; Adobe-Japan1; CID+5880 -7907 E0101; Hanyo-Denshi; JA6705 -7907 E0101; Moji_Joho; MJ018685 -7907 E0102; Hanyo-Denshi; FT2363 -7907 E0102; Moji_Joho; MJ018686 -790C E0100; Adobe-Japan1; CID+19611 -790E E0100; Adobe-Japan1; CID+2757 -7910 E0100; Adobe-Japan1; CID+18230 -7911 E0100; Adobe-Japan1; CID+5882 -7912 E0100; Adobe-Japan1; CID+5881 -7919 E0100; Adobe-Japan1; CID+5883 -791A E0100; Adobe-Japan1; CID+22099 -791A E0101; Hanyo-Denshi; JB4831 -791A E0101; Moji_Joho; MJ018704 -791A E0102; Hanyo-Denshi; KS274010 -791A E0102; Moji_Joho; MJ018705 -791B E0100; Adobe-Japan1; CID+18231 -791C E0100; Adobe-Japan1; CID+17012 -791E E0100; Adobe-Japan1; CID+22100 -791E E0101; Hanyo-Denshi; JB4833 -791E E0101; Moji_Joho; MJ018709 -791E E0102; Hanyo-Denshi; KS274070 -791E E0102; Moji_Joho; MJ018710 -791F E0100; Adobe-Japan1; CID+19612 -7920 E0100; Adobe-Japan1; CID+22101 -7920 E0101; Hanyo-Denshi; JB4835 -7920 E0101; Moji_Joho; MJ018712 -7920 E0102; Hanyo-Denshi; KS274110 -7920 E0102; Moji_Joho; MJ018713 -7925 E0100; Adobe-Japan1; CID+18232 -7926 E0100; Adobe-Japan1; CID+5853 -7926 E0101; Hanyo-Denshi; JA6672 -7926 E0101; Moji_Joho; MJ018717 -7926 E0102; Hanyo-Denshi; FT2359 -7926 E0102; Moji_Joho; MJ018718 -7926 E0103; Hanyo-Denshi; TK01064280 -7927 E0100; Adobe-Japan1; CID+19613 -7928 E0100; Adobe-Japan1; CID+19614 -7929 E0100; Adobe-Japan1; CID+22102 -792A E0100; Adobe-Japan1; CID+5855 -792A E0101; Adobe-Japan1; CID+13569 -792A E0102; Hanyo-Denshi; JA6674 -792A E0102; Moji_Joho; MJ018723 -792A E0103; Hanyo-Denshi; KS274310 -792A E0103; Moji_Joho; MJ018724 -792B E0100; Adobe-Japan1; CID+5885 -792C E0100; Adobe-Japan1; CID+5884 -792D E0100; Adobe-Japan1; CID+22103 -792E E0100; Adobe-Japan1; CID+17013 -792E E0101; Moji_Joho; MJ018728 -792E E0102; Moji_Joho; MJ018729 -7930 E0100; Adobe-Japan1; CID+8578 -7931 E0100; Adobe-Japan1; CID+14903 -7931 E0101; Hanyo-Denshi; JB4840 -7931 E0101; Moji_Joho; MJ018732 -7931 E0102; Hanyo-Denshi; KS274560 -7931 E0102; Moji_Joho; MJ018733 -7932 E0100; Hanyo-Denshi; IP7932 -7932 E0100; Moji_Joho; MJ018734 -7932 E0101; Hanyo-Denshi; KS274540 -7932 E0101; Moji_Joho; MJ018735 -7934 E0100; Adobe-Japan1; CID+17014 -7934 E0101; Adobe-Japan1; CID+14904 -7934 E0102; Hanyo-Denshi; JB4841 -7934 E0102; Moji_Joho; MJ018738 -7934 E0103; Hanyo-Denshi; KS274620 -7934 E0103; Moji_Joho; MJ018739 -7934 E0104; Hanyo-Denshi; JC8918 -7934 E0104; Moji_Joho; MJ018737 -7934 E0105; Hanyo-Denshi; JTB696S -7934 E0105; Moji_Joho; MJ018740 -7935 E0100; Adobe-Japan1; CID+22104 -7936 E0100; Hanyo-Denshi; IP7936 -7936 E0100; Moji_Joho; MJ018742 -7936 E0101; Hanyo-Denshi; KS274700 -7936 E0101; Moji_Joho; MJ018743 -793A E0100; Adobe-Japan1; CID+19130 -793A E0101; Adobe-Japan1; CID+2260 -793A E0102; Hanyo-Denshi; JA2808 -793A E0103; Hanyo-Denshi; TK01064350 -793B E0100; Adobe-Japan1; CID+14905 -793C E0100; Adobe-Japan1; CID+4017 -793C E0101; Adobe-Japan1; CID+8579 -793C E0102; Hanyo-Denshi; JA4673 -793C E0103; Hanyo-Denshi; IB2536 -793D E0100; Adobe-Japan1; CID+14906 -793D E0101; Hanyo-Denshi; JB4844 -793D E0101; Moji_Joho; MJ018752 -793D E0102; Hanyo-Denshi; IB0765 -793D E0102; Moji_Joho; MJ018751 -793E E0100; Adobe-Japan1; CID+2302 -793E E0101; Adobe-Japan1; CID+13348 -793E E0102; Hanyo-Denshi; JA2850 -793E E0102; Moji_Joho; MJ018753 -793E E0103; Hanyo-Denshi; JC8919 -793E E0104; Hanyo-Denshi; KS275210 -793E E0104; Moji_Joho; MJ058201 -793F E0100; Adobe-Japan1; CID+19615 -793F E0101; Hanyo-Denshi; JB4845 -793F E0101; Moji_Joho; MJ018755 -793F E0102; Hanyo-Denshi; JTB69E -793F E0102; Moji_Joho; MJ018754 -793F E0103; Hanyo-Denshi; TK01064480 -793F E0104; Hanyo-Denshi; TK01064580 -7940 E0100; Adobe-Japan1; CID+5886 -7940 E0101; Adobe-Japan1; CID+14167 -7940 E0102; Hanyo-Denshi; JA6711 -7940 E0102; Moji_Joho; MJ018759 -7940 E0103; Hanyo-Denshi; IB2541 -7940 E0103; Moji_Joho; MJ018760 -7940 E0104; Hanyo-Denshi; IB2539 -7940 E0104; Moji_Joho; MJ018761 -7940 E0105; Hanyo-Denshi; FT2365 -7940 E0105; Moji_Joho; MJ018758 -7940 E0106; Hanyo-Denshi; TK01064400 -7941 E0100; Adobe-Japan1; CID+1805 -7941 E0101; Adobe-Japan1; CID+7668 -7941 E0102; Hanyo-Denshi; JA2323 -7941 E0102; Moji_Joho; MJ018762 -7941 E0103; Hanyo-Denshi; FT1784 -7941 E0103; Moji_Joho; MJ018763 -7942 E0100; Adobe-Japan1; CID+19616 -7944 E0100; Adobe-Japan1; CID+22105 -7944 E0101; Hanyo-Denshi; JB4846 -7944 E0102; Hanyo-Denshi; TK01064490 -7945 E0100; Adobe-Japan1; CID+14907 -7945 E0101; Hanyo-Denshi; JB4847 -7945 E0101; Moji_Joho; MJ018767 -7945 E0102; Hanyo-Denshi; IB0768S -7945 E0102; Moji_Joho; MJ018766 -7946 E0100; Adobe-Japan1; CID+17015 -7946 E0101; Hanyo-Denshi; JB4848 -7946 E0101; Moji_Joho; MJ018769 -7946 E0102; Hanyo-Denshi; IB0769 -7946 E0102; Moji_Joho; MJ018768 -7947 E0100; Adobe-Japan1; CID+1626 -7947 E0101; Adobe-Japan1; CID+7659 -7947 E0102; Hanyo-Denshi; JA2132 -7947 E0102; Moji_Joho; MJ018770 -7947 E0103; Hanyo-Denshi; FT1776 -7947 E0103; Moji_Joho; MJ018771 -7947 E0104; Hanyo-Denshi; TK01064730 -7948 E0100; Adobe-Japan1; CID+13335 -7948 E0101; Adobe-Japan1; CID+1601 -7948 E0102; Hanyo-Denshi; JA2107 -7948 E0103; Hanyo-Denshi; JC8923 -7949 E0100; Adobe-Japan1; CID+2225 -7949 E0101; Adobe-Japan1; CID+13345 -7949 E0102; Hanyo-Denshi; JA2767 -7949 E0103; Hanyo-Denshi; JC8920 -794A E0100; Adobe-Japan1; CID+18233 -794A E0101; Hanyo-Denshi; JB4849 -794A E0101; Moji_Joho; MJ018775 -794A E0102; Hanyo-Denshi; IB0771S -794A E0102; Moji_Joho; MJ018774 -794B E0100; Adobe-Japan1; CID+22106 -794B E0101; Hanyo-Denshi; JB4850 -794B E0101; Moji_Joho; MJ018777 -794B E0102; Hanyo-Denshi; IB0772 -794B E0102; Moji_Joho; MJ018776 -794C E0100; Hanyo-Denshi; IB0773 -794C E0100; Moji_Joho; MJ018778 -794C E0101; Hanyo-Denshi; IP794C -794C E0101; Moji_Joho; MJ018779 -794F E0100; Adobe-Japan1; CID+22107 -794F E0101; Hanyo-Denshi; JB4851 -794F E0101; Moji_Joho; MJ018781 -794F E0102; Hanyo-Denshi; JTB6B4 -794F E0102; Moji_Joho; MJ018780 -7950 E0100; Adobe-Japan1; CID+13391 -7950 E0101; Adobe-Japan1; CID+3870 -7950 E0102; Hanyo-Denshi; JA4520 -7950 E0103; Hanyo-Denshi; JC8924 -7950 E0104; Hanyo-Denshi; TK01064920 -7951 E0100; Adobe-Japan1; CID+22108 -7951 E0101; Hanyo-Denshi; JB4852 -7951 E0102; Hanyo-Denshi; TK01064800 -7953 E0100; Adobe-Japan1; CID+5892 -7953 E0101; Adobe-Japan1; CID+14168 -7953 E0102; Adobe-Japan1; CID+14169 -7953 E0103; Hanyo-Denshi; JA6717 -7953 E0103; Moji_Joho; MJ018787 -7953 E0104; Hanyo-Denshi; FT2370 -7953 E0104; Moji_Joho; MJ018786 -7953 E0105; Hanyo-Denshi; JTB6AC -7953 E0106; Hanyo-Denshi; KS275490 -7953 E0106; Moji_Joho; MJ018785 -7953 E0107; Hanyo-Denshi; TK01064870 -7954 E0100; Adobe-Japan1; CID+19617 -7954 E0101; Hanyo-Denshi; JB4853 -7954 E0101; Moji_Joho; MJ018791 -7954 E0102; Hanyo-Denshi; IB0776 -7954 E0102; Moji_Joho; MJ018790 -7955 E0100; Adobe-Japan1; CID+5891 -7955 E0101; Hanyo-Denshi; JA6716 -7955 E0101; Moji_Joho; MJ018792 -7955 E0102; Hanyo-Denshi; FT2369 -7955 E0102; Moji_Joho; MJ018793 -7956 E0100; Adobe-Japan1; CID+2758 -7956 E0101; Adobe-Japan1; CID+13359 -7956 E0102; Hanyo-Denshi; JA3336 -7956 E0103; Hanyo-Denshi; JC8925 -7957 E0100; Adobe-Japan1; CID+5888 -7957 E0101; Hanyo-Denshi; JA6713 -7957 E0101; Moji_Joho; MJ018796 -7957 E0102; Hanyo-Denshi; FT2367 -7957 E0102; Moji_Joho; MJ018795 -7957 E0103; Hanyo-Denshi; TK01064880 -7957 E0104; Hanyo-Denshi; TK01064960 -7958 E0100; Adobe-Japan1; CID+18234 -7958 E0101; Hanyo-Denshi; JB4854 -7958 E0101; Moji_Joho; MJ018798 -7958 E0102; Hanyo-Denshi; JTB6B7 -7958 E0102; Moji_Joho; MJ018797 -7958 E0103; Hanyo-Denshi; JTB6C9 -7958 E0103; Moji_Joho; MJ018799 -7958 E0104; Hanyo-Denshi; JTC0EE -7958 E0104; Moji_Joho; MJ018800 -7959 E0100; Hanyo-Denshi; IB0778 -7959 E0100; Moji_Joho; MJ018801 -7959 E0101; Hanyo-Denshi; IP7959 -7959 E0101; Moji_Joho; MJ018802 -795A E0100; Adobe-Japan1; CID+5890 -795A E0101; Hanyo-Denshi; JA6715 -795A E0101; Moji_Joho; MJ018804 -795A E0102; Hanyo-Denshi; FT2368 -795A E0102; Moji_Joho; MJ018803 -795A E0103; Hanyo-Denshi; TK01064570 -795B E0100; Adobe-Japan1; CID+14908 -795B E0101; Hanyo-Denshi; JB4855 -795B E0101; Moji_Joho; MJ018807 -795B E0102; Hanyo-Denshi; IB0780 -795B E0102; Moji_Joho; MJ018806 -795C E0100; Adobe-Japan1; CID+14909 -795C E0101; Hanyo-Denshi; JB4856 -795C E0101; Moji_Joho; MJ018809 -795C E0102; Hanyo-Denshi; IB0781 -795C E0102; Moji_Joho; MJ018808 -795D E0100; Adobe-Japan1; CID+13351 -795D E0101; Adobe-Japan1; CID+2389 -795D E0102; Hanyo-Denshi; JA2943 -795D E0103; Hanyo-Denshi; JC8927 -795E E0100; Adobe-Japan1; CID+8580 -795E E0101; Adobe-Japan1; CID+2566 -795E E0102; Hanyo-Denshi; JA3132 -795E E0103; Hanyo-Denshi; JC8928 -795F E0100; Adobe-Japan1; CID+5889 -7960 E0100; Adobe-Japan1; CID+5887 -7960 E0101; Hanyo-Denshi; JA6712 -7960 E0101; Moji_Joho; MJ018814 -7960 E0102; Hanyo-Denshi; FT2366 -7960 E0102; Moji_Joho; MJ018813 -7961 E0100; Moji_Joho; MJ018815 -7961 E0101; Moji_Joho; MJ018816 -7962 E0100; Adobe-Japan1; CID+3296 -7962 E0101; Adobe-Japan1; CID+7977 -7962 E0102; Hanyo-Denshi; JA3910 -7962 E0102; Moji_Joho; MJ018817 -7962 E0103; Hanyo-Denshi; JTB6CA -7962 E0103; Moji_Joho; MJ018821 -7962 E0104; Hanyo-Denshi; JTB6C7 -7962 E0104; Moji_Joho; MJ018819 -7962 E0105; Hanyo-Denshi; KS276050 -7962 E0105; Moji_Joho; MJ018820 -7962 E0106; Hanyo-Denshi; FT2919 -7962 E0106; Moji_Joho; MJ018818 -7962 E0107; Hanyo-Denshi; TK01064500 -7963 E0100; Hanyo-Denshi; IB0784 -7963 E0100; Moji_Joho; MJ018822 -7963 E0101; Hanyo-Denshi; IP7963 -7963 E0101; Moji_Joho; MJ018823 -7965 E0100; Adobe-Japan1; CID+8581 -7965 E0101; Adobe-Japan1; CID+2485 -7965 E0102; Hanyo-Denshi; JA3045 -7965 E0103; Hanyo-Denshi; JC8929 -7965 E0104; Hanyo-Denshi; TK01064810 -7966 E0100; Hanyo-Denshi; KS276140 -7966 E0101; Hanyo-Denshi; TK01065340 -7967 E0100; Adobe-Japan1; CID+18236 -7967 E0101; Hanyo-Denshi; JB4857 -7967 E0101; Moji_Joho; MJ018829 -7967 E0102; Hanyo-Denshi; JTB6D0 -7967 E0102; Moji_Joho; MJ018828 -7968 E0100; Adobe-Japan1; CID+3502 -7969 E0100; Adobe-Japan1; CID+22109 -796B E0100; Adobe-Japan1; CID+19618 -796B E0101; Hanyo-Denshi; JB4859 -796B E0101; Moji_Joho; MJ018834 -796B E0102; Hanyo-Denshi; IB0787 -796B E0102; Moji_Joho; MJ018833 -796C E0100; Hanyo-Denshi; IB0788 -796C E0100; Moji_Joho; MJ018835 -796C E0101; Hanyo-Denshi; IP796C -796C E0101; Moji_Joho; MJ018836 -796D E0100; Adobe-Japan1; CID+2119 -796E E0100; Hanyo-Denshi; IP796E -796E E0100; Moji_Joho; MJ018838 -796E E0101; Hanyo-Denshi; JTB6DB -796E E0101; Moji_Joho; MJ018839 -796E E0102; Hanyo-Denshi; TK01065190 -7970 E0100; Hanyo-Denshi; IP7970 -7970 E0101; Hanyo-Denshi; TK01065140 -7970 E0102; Hanyo-Denshi; TK01065200 -7970 E0103; Hanyo-Denshi; TK01065240 -7971 E0100; Hanyo-Denshi; IP7971 -7971 E0100; Moji_Joho; MJ018845 -7971 E0101; Hanyo-Denshi; JT7971 -7971 E0101; Moji_Joho; MJ018846 -7971 E0102; Hanyo-Denshi; JTB6E5 -7971 E0102; Moji_Joho; MJ018847 -7972 E0100; Adobe-Japan1; CID+18237 -7972 E0101; Hanyo-Denshi; JB4860 -7972 E0101; Moji_Joho; MJ018849 -7972 E0102; Hanyo-Denshi; IB0789 -7972 E0102; Moji_Joho; MJ018848 -7973 E0100; Hanyo-Denshi; IB0791 -7973 E0100; Moji_Joho; MJ018850 -7973 E0101; Hanyo-Denshi; IP7973 -7973 E0101; Moji_Joho; MJ018851 -7974 E0100; Hanyo-Denshi; IP7974 -7974 E0100; Moji_Joho; MJ018853 -7974 E0101; Hanyo-Denshi; JTB6E1 -7974 E0101; Moji_Joho; MJ018852 -7977 E0100; Adobe-Japan1; CID+3186 -7979 E0100; Adobe-Japan1; CID+17016 -797A E0100; Adobe-Japan1; CID+5893 -797A E0101; Hanyo-Denshi; JA6718 -797A E0101; Moji_Joho; MJ018858 -797A E0102; Hanyo-Denshi; FT2371 -797A E0102; Moji_Joho; MJ018857 -797B E0100; Adobe-Japan1; CID+22110 -797B E0101; Hanyo-Denshi; JB4862 -797B E0101; Moji_Joho; MJ018860 -797B E0102; Hanyo-Denshi; IB0794 -797B E0102; Moji_Joho; MJ018859 -797C E0100; Adobe-Japan1; CID+19619 -797C E0101; Hanyo-Denshi; JB4863 -797C E0101; Moji_Joho; MJ018862 -797C E0102; Hanyo-Denshi; IB0802 -797C E0102; Moji_Joho; MJ018861 -797E E0100; Adobe-Japan1; CID+22111 -797E E0101; Hanyo-Denshi; JB4864 -797E E0101; Moji_Joho; MJ018865 -797E E0102; Hanyo-Denshi; KS276790 -797E E0102; Moji_Joho; MJ018864 -797E E0103; Hanyo-Denshi; TK01065480 -797F E0100; Adobe-Japan1; CID+5894 -797F E0101; Hanyo-Denshi; JA6719 -797F E0101; Moji_Joho; MJ018867 -797F E0102; Hanyo-Denshi; FT2372 -797F E0102; Moji_Joho; MJ018868 -7980 E0100; Adobe-Japan1; CID+5916 -7980 E0101; Hanyo-Denshi; JA6741 -7980 E0101; Moji_Joho; MJ018869 -7980 E0102; Hanyo-Denshi; KS277470 -7980 E0102; Moji_Joho; MJ018870 -7981 E0100; Adobe-Japan1; CID+1744 -7982 E0100; Hanyo-Denshi; IB0803 -7982 E0100; Moji_Joho; MJ018872 -7982 E0101; Hanyo-Denshi; IP7982 -7982 E0101; Moji_Joho; MJ018873 -7982 E0102; Hanyo-Denshi; TK01065610 -7983 E0100; Hanyo-Denshi; IP7983 -7983 E0101; Hanyo-Denshi; TK01065270 -7984 E0100; Adobe-Japan1; CID+4067 -7984 E0101; Hanyo-Denshi; JA4729 -7984 E0101; Moji_Joho; MJ018878 -7984 E0102; Hanyo-Denshi; KS276570 -7984 E0102; Moji_Joho; MJ018877 -7984 E0103; Hanyo-Denshi; JTB6F7 -7984 E0103; Moji_Joho; MJ018879 -7985 E0100; Adobe-Japan1; CID+2743 -7985 E0101; Hanyo-Denshi; JA3321 -7985 E0101; Moji_Joho; MJ018881 -7985 E0102; Hanyo-Denshi; KS276600 -7985 E0102; Moji_Joho; MJ018880 -7988 E0100; Hanyo-Denshi; IP7988 -7988 E0101; Hanyo-Denshi; TK01065700 -798A E0100; Adobe-Japan1; CID+5895 -798A E0101; Hanyo-Denshi; JA6720 -798A E0101; Moji_Joho; MJ018887 -798A E0102; Hanyo-Denshi; KS277400 -798A E0102; Moji_Joho; MJ018888 -798A E0103; Hanyo-Denshi; KS277120 -798A E0103; Moji_Joho; MJ018886 -798A E0104; Hanyo-Denshi; IB0804 -798A E0104; Moji_Joho; MJ018885 -798A E0105; Hanyo-Denshi; FT2373 -798A E0105; Moji_Joho; MJ018889 -798A E0106; Hanyo-Denshi; TK01065810 -798B E0100; Adobe-Japan1; CID+14910 -798B E0101; Hanyo-Denshi; JB4865 -798B E0101; Moji_Joho; MJ018891 -798B E0102; Hanyo-Denshi; IB0811 -798B E0102; Moji_Joho; MJ018890 -798C E0100; Adobe-Japan1; CID+22112 -798C E0101; Hanyo-Denshi; JB4866 -798C E0102; Hanyo-Denshi; TK01065690 -798D E0100; Adobe-Japan1; CID+13325 -798D E0101; Adobe-Japan1; CID+1362 -798D E0102; Hanyo-Denshi; JA1850 -798D E0102; Moji_Joho; MJ018894 -798D E0103; Hanyo-Denshi; JC8931 -798D E0104; Hanyo-Denshi; KS276980 -798D E0104; Moji_Joho; MJ058212 -798E E0100; Adobe-Japan1; CID+3091 -798E E0101; Adobe-Japan1; CID+13371 -798E E0102; Hanyo-Denshi; JA3687 -798E E0103; Hanyo-Denshi; JC8932 -798F E0100; Adobe-Japan1; CID+3569 -798F E0101; Adobe-Japan1; CID+8583 -798F E0102; Hanyo-Denshi; JA4201 -798F E0102; Moji_Joho; MJ018896 -798F E0103; Hanyo-Denshi; JC8933 -798F E0104; Hanyo-Denshi; KS277650 -798F E0104; Moji_Joho; MJ018897 -798F E0105; Hanyo-Denshi; TK01065860 -7991 E0100; Adobe-Japan1; CID+22113 -7991 E0101; Hanyo-Denshi; JB4867 -7991 E0101; Moji_Joho; MJ018901 -7991 E0102; Hanyo-Denshi; KS277460 -7991 E0102; Moji_Joho; MJ018900 -7992 E0100; Hanyo-Denshi; IP7992 -7992 E0100; Moji_Joho; MJ018902 -7992 E0101; Hanyo-Denshi; JTB702 -7992 E0101; Moji_Joho; MJ018903 -7992 E0102; Hanyo-Denshi; TK01065880 -7993 E0100; Adobe-Japan1; CID+22114 -7993 E0101; Hanyo-Denshi; JB4868 -7993 E0101; Moji_Joho; MJ018906 -7993 E0102; Hanyo-Denshi; IB0805 -7993 E0102; Moji_Joho; MJ018905 -7994 E0100; Adobe-Japan1; CID+8582 -7994 E0101; Hanyo-Denshi; JB4869 -7994 E0101; Moji_Joho; MJ018908 -7994 E0102; Hanyo-Denshi; IB0806 -7994 E0102; Moji_Joho; MJ018907 -7995 E0100; Adobe-Japan1; CID+18238 -7995 E0101; Hanyo-Denshi; JB4870 -7995 E0101; Moji_Joho; MJ018912 -7995 E0102; Hanyo-Denshi; KS277260 -7995 E0102; Moji_Joho; MJ018910 -7995 E0103; Hanyo-Denshi; IB0807S -7995 E0103; Moji_Joho; MJ018913 -7995 E0104; Hanyo-Denshi; TK01066020 -7995 E0105; Hanyo-Denshi; TK01066060 -7995 E0106; Hanyo-Denshi; TK01066160 -7995 E0107; Moji_Joho; MJ018909 -7995 E0108; Moji_Joho; MJ018911 -7996 E0100; Adobe-Japan1; CID+14911 -7996 E0101; Hanyo-Denshi; JB4871 -7996 E0101; Moji_Joho; MJ018915 -7996 E0102; Hanyo-Denshi; IB0808S -7996 E0102; Moji_Joho; MJ018914 -7997 E0100; Hanyo-Denshi; IB0809 -7997 E0100; Moji_Joho; MJ018916 -7997 E0101; Hanyo-Denshi; IP7997 -7997 E0101; Moji_Joho; MJ018917 -7998 E0100; Adobe-Japan1; CID+14912 -7998 E0101; Hanyo-Denshi; JB4872 -7998 E0101; Moji_Joho; MJ018919 -7998 E0102; Hanyo-Denshi; IB0810 -7998 E0102; Moji_Joho; MJ018918 -7998 E0103; Hanyo-Denshi; KS277480 -7998 E0103; Moji_Joho; MJ018920 -799A E0100; Hanyo-Denshi; IP799A -799A E0100; Moji_Joho; MJ018922 -799A E0101; Hanyo-Denshi; JTB705 -799A E0101; Moji_Joho; MJ018921 -799B E0100; Adobe-Japan1; CID+8584 -799B E0101; Hanyo-Denshi; JB4873 -799B E0102; Hanyo-Denshi; TK01065710 -799B E0103; Hanyo-Denshi; TK01065760 -799C E0100; Adobe-Japan1; CID+22115 -799D E0100; Adobe-Japan1; CID+5896 -799D E0101; Hanyo-Denshi; JA6721 -799D E0101; Moji_Joho; MJ018928 -799D E0102; Hanyo-Denshi; KS277420S -799D E0102; Moji_Joho; MJ018927 -799D E0103; Hanyo-Denshi; FT2374S -799D E0103; Moji_Joho; MJ018929 -799D E0104; Hanyo-Denshi; IB0337 -799D E0104; Moji_Joho; MJ018930 -799E E0100; Hanyo-Denshi; IP799E -799E E0101; Hanyo-Denshi; TK01065910 -799F E0100; Hanyo-Denshi; IP799F -799F E0101; Hanyo-Denshi; TK01065920 -79A0 E0100; Hanyo-Denshi; IP79A0 -79A0 E0100; Moji_Joho; MJ018936 -79A0 E0101; Hanyo-Denshi; KS277440 -79A0 E0101; Moji_Joho; MJ018935 -79A1 E0100; Adobe-Japan1; CID+18239 -79A1 E0101; Hanyo-Denshi; JB4875 -79A1 E0101; Moji_Joho; MJ018938 -79A1 E0102; Hanyo-Denshi; IB0816 -79A1 E0102; Moji_Joho; MJ018937 -79A5 E0100; Hanyo-Denshi; IP79A5 -79A5 E0101; Hanyo-Denshi; TK01066080 -79A6 E0100; Adobe-Japan1; CID+1684 -79A7 E0100; Adobe-Japan1; CID+5897 -79A7 E0101; Adobe-Japan1; CID+20183 -79A7 E0102; Hanyo-Denshi; JA6722 -79A7 E0102; Moji_Joho; MJ018945 -79A7 E0103; Hanyo-Denshi; FT2375 -79A7 E0103; Moji_Joho; MJ018944 -79A7 E0104; Hanyo-Denshi; TK01066110 -79A7 E0105; Hanyo-Denshi; TK01066220 -79A8 E0100; Adobe-Japan1; CID+22116 -79A8 E0101; Hanyo-Denshi; JB4876 -79A8 E0101; Moji_Joho; MJ018949 -79A8 E0102; Hanyo-Denshi; IB0822 -79A8 E0102; Moji_Joho; MJ018948 -79A8 E0103; Moji_Joho; MJ018950 -79A9 E0100; Adobe-Japan1; CID+18240 -79A9 E0101; Hanyo-Denshi; JB4877 -79A9 E0101; Moji_Joho; MJ018952 -79A9 E0102; Hanyo-Denshi; JTB710 -79A9 E0102; Moji_Joho; MJ018951 -79A9 E0103; Hanyo-Denshi; JTC0F1 -79A9 E0103; Moji_Joho; MJ018953 -79AA E0100; Adobe-Japan1; CID+5899 -79AA E0101; Hanyo-Denshi; JA6724 -79AA E0101; Moji_Joho; MJ018954 -79AA E0102; Hanyo-Denshi; FT2376 -79AA E0102; Moji_Joho; MJ018955 -79AA E0103; Hanyo-Denshi; JTB70C -79AA E0103; Moji_Joho; MJ059973 -79AA E0104; Hanyo-Denshi; KS277750 -79AA E0104; Moji_Joho; MJ058215 -79AB E0100; Adobe-Japan1; CID+19620 -79AB E0101; Hanyo-Denshi; JB4878 -79AB E0101; Moji_Joho; MJ018957 -79AB E0102; Hanyo-Denshi; JTB717 -79AB E0102; Moji_Joho; MJ018956 -79AB E0103; Hanyo-Denshi; KS278230 -79AB E0103; Moji_Joho; MJ018958 -79AC E0100; Hanyo-Denshi; IB0823 -79AC E0100; Moji_Joho; MJ018959 -79AC E0101; Hanyo-Denshi; IP79AC -79AC E0101; Moji_Joho; MJ018960 -79AD E0100; Hanyo-Denshi; IB0825 -79AD E0100; Moji_Joho; MJ018961 -79AD E0101; Hanyo-Denshi; IP79AD -79AD E0101; Moji_Joho; MJ018962 -79AD E0102; Moji_Joho; MJ018963 -79AE E0100; Adobe-Japan1; CID+5900 -79AE E0101; Adobe-Japan1; CID+14171 -79AE E0102; Hanyo-Denshi; JA6725 -79AE E0102; Moji_Joho; MJ018965 -79AE E0103; Hanyo-Denshi; FT2377 -79AE E0103; Moji_Joho; MJ018964 -79AF E0100; Adobe-Japan1; CID+22117 -79AF E0101; Hanyo-Denshi; JB4879 -79AF E0102; Hanyo-Denshi; TK01066280 -79B0 E0100; Adobe-Japan1; CID+3295 -79B0 E0101; Adobe-Japan1; CID+7769 -79B0 E0102; Hanyo-Denshi; JA3909 -79B0 E0102; Moji_Joho; MJ018968 -79B0 E0103; Hanyo-Denshi; FT1890 -79B0 E0103; Moji_Joho; MJ018969 -79B0 E0104; Hanyo-Denshi; JTB72C -79B0 E0104; Moji_Joho; MJ018970 -79B0 E0105; Hanyo-Denshi; JTB72E -79B1 E0100; Adobe-Japan1; CID+7758 -79B1 E0101; Adobe-Japan1; CID+20184 -79B1 E0102; Hanyo-Denshi; JB4880 -79B1 E0102; Moji_Joho; MJ018972 -79B1 E0103; Hanyo-Denshi; IB0827 -79B1 E0103; Moji_Joho; MJ018971 -79B1 E0104; Hanyo-Denshi; TK01066210 -79B3 E0100; Adobe-Japan1; CID+5901 -79B3 E0101; Hanyo-Denshi; JA6726 -79B3 E0101; Moji_Joho; MJ018975 -79B3 E0102; Hanyo-Denshi; IB0830 -79B3 E0102; Moji_Joho; MJ018974 -79B4 E0100; Adobe-Japan1; CID+18241 -79B4 E0101; Hanyo-Denshi; JB4881 -79B4 E0101; Moji_Joho; MJ018977 -79B4 E0102; Hanyo-Denshi; IB0831 -79B4 E0102; Moji_Joho; MJ018976 -79B8 E0100; Adobe-Japan1; CID+14913 -79B8 E0101; Hanyo-Denshi; JB4882 -79B8 E0101; Moji_Joho; MJ018981 -79B8 E0102; Hanyo-Denshi; KS278790 -79B8 E0102; Moji_Joho; MJ018982 -79B9 E0100; Adobe-Japan1; CID+5902 -79BA E0100; Adobe-Japan1; CID+5903 -79BA E0101; Adobe-Japan1; CID+13571 -79BB E0100; Adobe-Japan1; CID+14914 -79BB E0101; Hanyo-Denshi; JB4883 -79BB E0101; Moji_Joho; MJ018985 -79BB E0102; Hanyo-Denshi; KS278860 -79BB E0102; Moji_Joho; MJ018986 -79BD E0100; Adobe-Japan1; CID+1745 -79BD E0101; Hanyo-Denshi; JA2257 -79BD E0101; Moji_Joho; MJ018988 -79BD E0102; Hanyo-Denshi; KS278920 -79BD E0102; Moji_Joho; MJ018989 -79BE E0100; Adobe-Japan1; CID+1363 -79BF E0100; Adobe-Japan1; CID+3229 -79C0 E0100; Adobe-Japan1; CID+2354 -79C1 E0100; Adobe-Japan1; CID+2226 -79C2 E0100; Adobe-Japan1; CID+18242 -79C4 E0100; Adobe-Japan1; CID+19621 -79C7 E0100; Adobe-Japan1; CID+18243 -79C8 E0100; Adobe-Japan1; CID+17017 -79C9 E0100; Adobe-Japan1; CID+5904 -79C9 E0101; Hanyo-Denshi; JA6729 -79C9 E0102; Hanyo-Denshi; TK01066540 -79C9 E0103; Hanyo-Denshi; TK01066590 -79CA E0100; Adobe-Japan1; CID+14915 -79CB E0100; Adobe-Japan1; CID+2355 -79CC E0100; Adobe-Japan1; CID+18244 -79CD E0100; Adobe-Japan1; CID+18245 -79CF E0100; Adobe-Japan1; CID+22118 -79D1 E0100; Adobe-Japan1; CID+1354 -79D2 E0100; Adobe-Japan1; CID+3509 -79D4 E0100; Adobe-Japan1; CID+17019 -79D5 E0100; Adobe-Japan1; CID+5905 -79D6 E0100; Adobe-Japan1; CID+18246 -79D8 E0100; Adobe-Japan1; CID+3455 -79DA E0100; Adobe-Japan1; CID+14916 -79DD E0100; Adobe-Japan1; CID+22119 -79DE E0100; Adobe-Japan1; CID+17020 -79DF E0100; Adobe-Japan1; CID+2759 -79E0 E0100; Adobe-Japan1; CID+22120 -79E1 E0100; Adobe-Japan1; CID+5908 -79E1 E0101; Hanyo-Denshi; JA6733 -79E1 E0102; Hanyo-Denshi; TK01066640 -79E2 E0100; Adobe-Japan1; CID+22121 -79E3 E0100; Adobe-Japan1; CID+5909 -79E4 E0100; Adobe-Japan1; CID+3359 -79E4 E0101; Adobe-Japan1; CID+7773 -79E4 E0102; Hanyo-Denshi; JA3973 -79E4 E0102; Moji_Joho; MJ019032 -79E4 E0103; Hanyo-Denshi; FT1894 -79E4 E0103; Moji_Joho; MJ019033 -79E5 E0100; Adobe-Japan1; CID+22122 -79E6 E0100; Adobe-Japan1; CID+2567 -79E7 E0100; Adobe-Japan1; CID+5906 -79E8 E0100; Hanyo-Denshi; IP79E8 -79E8 E0101; Hanyo-Denshi; TK01066770 -79E9 E0100; Adobe-Japan1; CID+2975 -79EA E0100; Adobe-Japan1; CID+19622 -79EB E0100; Adobe-Japan1; CID+17021 -79EC E0100; Adobe-Japan1; CID+5907 -79ED E0100; Adobe-Japan1; CID+17022 -79F0 E0100; Adobe-Japan1; CID+2486 -79F0 E0101; Hanyo-Denshi; JA3046 -79F0 E0101; Moji_Joho; MJ019047 -79F0 E0102; Hanyo-Denshi; KS280110 -79F0 E0102; Moji_Joho; MJ019046 -79F1 E0100; Adobe-Japan1; CID+22123 -79F8 E0100; Adobe-Japan1; CID+22124 -79FB E0100; Adobe-Japan1; CID+1184 -79FC E0100; Adobe-Japan1; CID+22125 -7A00 E0100; Adobe-Japan1; CID+1603 -7A02 E0100; Adobe-Japan1; CID+19623 -7A03 E0100; Adobe-Japan1; CID+14917 -7A04 E0100; Hanyo-Denshi; IP7A04 -7A04 E0101; Hanyo-Denshi; KS280690 -7A05 E0100; Adobe-Japan1; CID+13875 -7A05 E0101; Hanyo-Denshi; IP7A05 -7A05 E0101; Moji_Joho; MJ019067 -7A05 E0102; Hanyo-Denshi; KS280560 -7A05 E0102; Moji_Joho; MJ058222 -7A07 E0100; Adobe-Japan1; CID+22126 -7A08 E0100; Adobe-Japan1; CID+5910 -7A09 E0100; Adobe-Japan1; CID+14918 -7A09 E0101; Moji_Joho; MJ019071 -7A09 E0102; Moji_Joho; MJ019072 -7A0A E0100; Adobe-Japan1; CID+18251 -7A0B E0100; Adobe-Japan1; CID+3092 -7A0B E0101; Adobe-Japan1; CID+13944 -7A0B E0102; Hanyo-Denshi; JA3688 -7A0B E0102; Moji_Joho; MJ019075 -7A0B E0103; Hanyo-Denshi; JTB73D -7A0B E0103; Moji_Joho; MJ019074 -7A0C E0100; Adobe-Japan1; CID+19624 -7A0D E0100; Adobe-Japan1; CID+5911 -7A0D E0101; Hanyo-Denshi; JA6736 -7A0D E0101; Moji_Joho; MJ019077 -7A0D E0102; Hanyo-Denshi; FT2379 -7A0D E0102; Moji_Joho; MJ019078 -7A0E E0100; Adobe-Japan1; CID+2667 -7A11 E0100; Adobe-Japan1; CID+14919 -7A14 E0100; Adobe-Japan1; CID+3769 -7A15 E0100; Adobe-Japan1; CID+18252 -7A17 E0100; Adobe-Japan1; CID+3477 -7A17 E0101; Adobe-Japan1; CID+7782 -7A17 E0102; Hanyo-Denshi; JA4103 -7A17 E0102; Moji_Joho; MJ019089 -7A17 E0103; Hanyo-Denshi; FT1909 -7A17 E0103; Moji_Joho; MJ019088 -7A18 E0100; Adobe-Japan1; CID+5912 -7A19 E0100; Adobe-Japan1; CID+5913 -7A19 E0101; Adobe-Japan1; CID+13572 -7A1A E0100; Adobe-Japan1; CID+2963 -7A1A E0101; Hanyo-Denshi; JA3553 -7A1A E0102; Hanyo-Denshi; TK01096450 -7A1B E0100; Adobe-Japan1; CID+18253 -7A1C E0100; Adobe-Japan1; CID+3983 -7A1C E0101; Hanyo-Denshi; JA4639 -7A1C E0101; Moji_Joho; MJ019095 -7A1C E0102; Hanyo-Denshi; KS281260 -7A1C E0102; Moji_Joho; MJ019094 -7A1E E0100; Adobe-Japan1; CID+14920 -7A1F E0100; Adobe-Japan1; CID+5915 -7A20 E0100; Adobe-Japan1; CID+5914 -7A20 E0101; Hanyo-Denshi; JA6739 -7A20 E0101; Moji_Joho; MJ019099 -7A20 E0102; Hanyo-Denshi; FT2380 -7A20 E0102; Moji_Joho; MJ019100 -7A21 E0100; Adobe-Japan1; CID+22127 -7A26 E0100; Hanyo-Denshi; KS281560 -7A26 E0101; Hanyo-Denshi; TK01068060 -7A27 E0100; Adobe-Japan1; CID+22128 -7A27 E0101; Hanyo-Denshi; JB4921 -7A27 E0101; Moji_Joho; MJ019105 -7A27 E0102; Hanyo-Denshi; JTB748 -7A27 E0102; Moji_Joho; MJ019106 -7A27 E0103; Hanyo-Denshi; JTB749 -7A27 E0103; Moji_Joho; MJ019107 -7A2B E0100; Adobe-Japan1; CID+22129 -7A2D E0100; Adobe-Japan1; CID+14921 -7A2E E0100; Adobe-Japan1; CID+2331 -7A2F E0100; Adobe-Japan1; CID+22130 -7A30 E0100; Adobe-Japan1; CID+19625 -7A31 E0100; Adobe-Japan1; CID+5917 -7A31 E0101; Adobe-Japan1; CID+7846 -7A31 E0102; Hanyo-Denshi; JA6742 -7A31 E0102; Moji_Joho; MJ019117 -7A31 E0103; Hanyo-Denshi; FT2381 -7A31 E0103; Moji_Joho; MJ019119 -7A31 E0104; Hanyo-Denshi; FT1971 -7A31 E0104; Moji_Joho; MJ019118 -7A31 E0105; Hanyo-Denshi; TK01067600 -7A32 E0100; Adobe-Japan1; CID+1204 -7A34 E0100; Adobe-Japan1; CID+22131 -7A35 E0100; Adobe-Japan1; CID+22132 -7A35 E0101; Hanyo-Denshi; JB4927 -7A35 E0101; Moji_Joho; MJ019122 -7A35 E0102; Hanyo-Denshi; KS282180 -7A35 E0102; Moji_Joho; MJ019123 -7A35 E0103; Hanyo-Denshi; TK01067720 -7A37 E0100; Adobe-Japan1; CID+5920 -7A38 E0100; Adobe-Japan1; CID+18255 -7A39 E0100; Adobe-Japan1; CID+14922 -7A3A E0100; Adobe-Japan1; CID+19626 -7A3B E0100; Adobe-Japan1; CID+5918 -7A3B E0101; Hanyo-Denshi; JA6743 -7A3B E0101; Moji_Joho; MJ019130 -7A3B E0102; Hanyo-Denshi; FT2382 -7A3B E0102; Moji_Joho; MJ019131 -7A3B E0103; Hanyo-Denshi; TK01067190 -7A3B E0104; Hanyo-Denshi; TK01068000 -7A3C E0100; Adobe-Japan1; CID+1364 -7A3C E0101; Hanyo-Denshi; JA1852 -7A3C E0101; Moji_Joho; MJ019133 -7A3C E0102; Hanyo-Denshi; FT2018 -7A3C E0102; Moji_Joho; MJ019134 -7A3D E0100; Adobe-Japan1; CID+1828 -7A3D E0101; Hanyo-Denshi; JA2346 -7A3D E0101; Moji_Joho; MJ019135 -7A3D E0102; Hanyo-Denshi; KS282540 -7A3D E0102; Moji_Joho; MJ058230 -7A3E E0100; Adobe-Japan1; CID+5919 -7A3F E0100; Adobe-Japan1; CID+2008 -7A3F E0101; Hanyo-Denshi; JA2538 -7A3F E0101; Moji_Joho; MJ019138 -7A3F E0102; Hanyo-Denshi; JTB754 -7A3F E0102; Moji_Joho; MJ019139 -7A40 E0100; Adobe-Japan1; CID+13343 -7A40 E0101; Adobe-Japan1; CID+2052 -7A40 E0102; Hanyo-Denshi; JA2582 -7A40 E0103; Hanyo-Denshi; JC8945 -7A42 E0100; Adobe-Japan1; CID+3638 -7A42 E0101; Hanyo-Denshi; JA4270 -7A42 E0101; Moji_Joho; MJ019142 -7A42 E0102; Hanyo-Denshi; JTB753 -7A42 E0102; Moji_Joho; MJ059993 -7A43 E0100; Adobe-Japan1; CID+5921 -7A44 E0100; Adobe-Japan1; CID+19627 -7A45 E0100; Adobe-Japan1; CID+14923 -7A46 E0100; Adobe-Japan1; CID+3714 -7A47 E0100; Adobe-Japan1; CID+18256 -7A48 E0100; Adobe-Japan1; CID+22133 -7A48 E0101; Hanyo-Denshi; JB4934 -7A48 E0102; Hanyo-Denshi; TK01028500 -7A49 E0100; Adobe-Japan1; CID+5923 -7A49 E0101; Hanyo-Denshi; JA6748 -7A49 E0101; Moji_Joho; MJ019151 -7A49 E0102; Hanyo-Denshi; KS283030 -7A49 E0102; Moji_Joho; MJ019150 -7A4B E0100; Moji_Joho; MJ019153 -7A4B E0101; Moji_Joho; MJ019154 -7A4C E0100; Adobe-Japan1; CID+14924 -7A4C E0101; Hanyo-Denshi; JB4935 -7A4C E0102; Hanyo-Denshi; TK01067870 -7A4D E0100; Adobe-Japan1; CID+2677 -7A4E E0100; Adobe-Japan1; CID+1265 -7A4F E0100; Adobe-Japan1; CID+1338 -7A4F E0101; Hanyo-Denshi; JA1826 -7A4F E0101; Moji_Joho; MJ019160 -7A4F E0102; Hanyo-Denshi; KS282990 -7A4F E0102; Moji_Joho; MJ019159 -7A50 E0100; Adobe-Japan1; CID+1136 -7A50 E0101; Hanyo-Denshi; JA1612 -7A50 E0101; Moji_Joho; MJ019161 -7A50 E0102; Hanyo-Denshi; JTB756 -7A50 E0102; Moji_Joho; MJ059994 -7A53 E0100; Hanyo-Denshi; IP7A53 -7A53 E0101; Hanyo-Denshi; KS283060 -7A55 E0100; Adobe-Japan1; CID+22134 -7A56 E0100; Adobe-Japan1; CID+18257 -7A57 E0100; Adobe-Japan1; CID+5922 -7A57 E0101; Hanyo-Denshi; JA6747 -7A57 E0101; Moji_Joho; MJ019167 -7A57 E0102; Hanyo-Denshi; JTB75D -7A57 E0102; Moji_Joho; MJ019168 -7A57 E0103; Hanyo-Denshi; JTB760 -7A57 E0103; Moji_Joho; MJ019169 -7A59 E0100; Adobe-Japan1; CID+18258 -7A5A E0100; Hanyo-Denshi; IP7A5A -7A5A E0101; Hanyo-Denshi; TK01068230 -7A5C E0100; Adobe-Japan1; CID+18259 -7A5C E0101; Hanyo-Denshi; JB4939 -7A5C E0101; Moji_Joho; MJ019175 -7A5C E0102; Hanyo-Denshi; KS283430 -7A5C E0102; Moji_Joho; MJ019176 -7A5D E0100; Adobe-Japan1; CID+14925 -7A5F E0100; Adobe-Japan1; CID+18260 -7A5F E0101; Hanyo-Denshi; JB4941 -7A5F E0101; Moji_Joho; MJ019179 -7A5F E0102; Hanyo-Denshi; IB0833S -7A5F E0102; Moji_Joho; MJ019178 -7A60 E0100; Adobe-Japan1; CID+20310 -7A60 E0101; Adobe-Japan1; CID+14926 -7A61 E0100; Adobe-Japan1; CID+5924 -7A61 E0101; Hanyo-Denshi; JA6749 -7A61 E0101; Moji_Joho; MJ019181 -7A61 E0102; Hanyo-Denshi; KS283930 -7A61 E0102; Moji_Joho; MJ058239 -7A62 E0100; Adobe-Japan1; CID+5925 -7A62 E0101; Hanyo-Denshi; JA6750 -7A62 E0101; Moji_Joho; MJ019182 -7A62 E0102; Hanyo-Denshi; FT2383S -7A62 E0102; Moji_Joho; MJ019184 -7A62 E0103; Moji_Joho; MJ019183 -7A63 E0100; Adobe-Japan1; CID+2527 -7A65 E0100; Adobe-Japan1; CID+22135 -7A67 E0100; Adobe-Japan1; CID+18261 -7A69 E0100; Adobe-Japan1; CID+5926 -7A69 E0101; Hanyo-Denshi; JA6751 -7A69 E0101; Moji_Joho; MJ019191 -7A69 E0102; Hanyo-Denshi; FT2384 -7A69 E0102; Moji_Joho; MJ019192 -7A6A E0100; Adobe-Japan1; CID+18262 -7A6B E0100; Adobe-Japan1; CID+1453 -7A6B E0101; Hanyo-Denshi; JA1947 -7A6B E0101; Moji_Joho; MJ019194 -7A6B E0102; Hanyo-Denshi; KS283800 -7A6B E0102; Moji_Joho; MJ019195 -7A6D E0100; Adobe-Japan1; CID+14927 -7A70 E0100; Adobe-Japan1; CID+5928 -7A70 E0101; Hanyo-Denshi; JA6753 -7A70 E0101; Moji_Joho; MJ019199 -7A70 E0102; Hanyo-Denshi; JTB767 -7A70 E0102; Moji_Joho; MJ060001 -7A74 E0100; Adobe-Japan1; CID+1856 -7A74 E0101; Adobe-Japan1; CID+13434 -7A74 E0102; Adobe-Japan1; CID+13745 -7A74 E0103; Hanyo-Denshi; JA2374 -7A74 E0103; Moji_Joho; MJ019203 -7A74 E0104; Hanyo-Denshi; FT1619 -7A74 E0104; Moji_Joho; MJ019204 -7A75 E0100; Adobe-Japan1; CID+18263 -7A76 E0100; Adobe-Japan1; CID+1664 -7A78 E0100; Adobe-Japan1; CID+14928 -7A79 E0100; Adobe-Japan1; CID+5929 -7A7A E0100; Adobe-Japan1; CID+1773 -7A7A E0101; Adobe-Japan1; CID+13735 -7A7A E0102; Hanyo-Denshi; JA2285 -7A7A E0102; Moji_Joho; MJ019210 -7A7A E0103; Hanyo-Denshi; JTB76E -7A7A E0103; Moji_Joho; MJ019211 -7A7D E0100; Adobe-Japan1; CID+5930 -7A7E E0100; Adobe-Japan1; CID+22136 -7A7F E0100; Adobe-Japan1; CID+2720 -7A7F E0101; Adobe-Japan1; CID+7973 -7A7F E0102; Hanyo-Denshi; JA3292 -7A7F E0102; Moji_Joho; MJ019217 -7A7F E0103; Hanyo-Denshi; HG1636 -7A7F E0103; Moji_Joho; MJ019216 -7A7F E0104; Moji_Joho; MJ019218 -7A7F E0105; Moji_Joho; MJ019219 -7A80 E0100; Adobe-Japan1; CID+19628 -7A81 E0100; Adobe-Japan1; CID+3237 -7A81 E0101; Adobe-Japan1; CID+13373 -7A81 E0102; Hanyo-Denshi; JA3845 -7A81 E0103; Hanyo-Denshi; JC8949 -7A81 E0104; Hanyo-Denshi; TK01068460 -7A82 E0100; Adobe-Japan1; CID+18264 -7A83 E0100; Adobe-Japan1; CID+2692 -7A84 E0100; Adobe-Japan1; CID+2149 -7A85 E0100; Adobe-Japan1; CID+17023 -7A86 E0100; Adobe-Japan1; CID+19629 -7A88 E0100; Adobe-Japan1; CID+5931 -7A8A E0100; Adobe-Japan1; CID+18265 -7A8A E0101; Hanyo-Denshi; JB4954 -7A8A E0101; Moji_Joho; MJ019231 -7A8A E0102; Hanyo-Denshi; JTB771S -7A8A E0102; Moji_Joho; MJ019230 -7A8B E0100; Adobe-Japan1; CID+22137 -7A90 E0100; Adobe-Japan1; CID+18266 -7A91 E0100; Adobe-Japan1; CID+22138 -7A92 E0100; Adobe-Japan1; CID+2976 -7A93 E0100; Adobe-Japan1; CID+2797 -7A94 E0100; Adobe-Japan1; CID+19630 -7A95 E0100; Adobe-Japan1; CID+5933 -7A95 E0101; Adobe-Japan1; CID+13573 -7A95 E0102; Moji_Joho; MJ019240 -7A95 E0103; Moji_Joho; MJ019241 -7A96 E0100; Adobe-Japan1; CID+5935 -7A96 E0101; Hanyo-Denshi; JA6760 -7A96 E0101; Moji_Joho; MJ019242 -7A96 E0102; Hanyo-Denshi; FT2385 -7A96 E0102; Moji_Joho; MJ019243 -7A97 E0100; Adobe-Japan1; CID+5932 -7A97 E0101; Adobe-Japan1; CID+7996 -7A97 E0102; Hanyo-Denshi; JA6757 -7A97 E0102; Moji_Joho; MJ019244 -7A97 E0103; Hanyo-Denshi; JTB775S -7A97 E0103; Moji_Joho; MJ019245 -7A97 E0104; Hanyo-Denshi; TK01068530 -7A98 E0100; Adobe-Japan1; CID+5934 -7A99 E0100; Moji_Joho; MJ019248 -7A99 E0101; Moji_Joho; MJ019249 -7A9A E0100; Hanyo-Denshi; KS285660 -7A9A E0101; Hanyo-Denshi; TK01068470 -7A9A E0102; Hanyo-Denshi; TK01068490 -7A9A E0103; Hanyo-Denshi; TK01068500 -7A9E E0100; Adobe-Japan1; CID+22139 -7A9F E0100; Adobe-Japan1; CID+1784 -7AA0 E0100; Adobe-Japan1; CID+14929 -7AA3 E0100; Adobe-Japan1; CID+14930 -7AA8 E0100; Hanyo-Denshi; IP7AA8 -7AA8 E0100; Moji_Joho; MJ019262 -7AA8 E0101; Hanyo-Denshi; KS286390 -7AA8 E0101; Moji_Joho; MJ019263 -7AA9 E0100; Adobe-Japan1; CID+5936 -7AAA E0100; Adobe-Japan1; CID+1788 -7AAB E0100; Hanyo-Denshi; IP7AAB -7AAB E0100; Moji_Joho; MJ019266 -7AAB E0101; Hanyo-Denshi; KS286380 -7AAB E0101; Moji_Joho; MJ019267 -7AAC E0100; Adobe-Japan1; CID+18267 -7AAC E0101; Hanyo-Denshi; JB4962 -7AAC E0101; Moji_Joho; MJ019268 -7AAC E0102; Hanyo-Denshi; JTB77BS -7AAC E0102; Moji_Joho; MJ019269 -7AAC E0103; Hanyo-Denshi; TK01068630 -7AAE E0100; Adobe-Japan1; CID+1665 -7AAE E0101; Adobe-Japan1; CID+13431 -7AAE E0102; Moji_Joho; MJ019271 -7AAE E0103; Moji_Joho; MJ019272 -7AAF E0100; Adobe-Japan1; CID+3900 -7AB0 E0100; Adobe-Japan1; CID+5938 -7AB1 E0100; Hanyo-Denshi; IP7AB1 -7AB1 E0101; Hanyo-Denshi; TK01068710 -7AB3 E0100; Adobe-Japan1; CID+14931 -7AB3 E0101; Hanyo-Denshi; JB4963 -7AB3 E0101; Moji_Joho; MJ019279 -7AB3 E0102; Hanyo-Denshi; JTB77DS -7AB3 E0102; Moji_Joho; MJ019278 -7AB4 E0100; Moji_Joho; MJ019280 -7AB4 E0101; Moji_Joho; MJ019281 -7AB5 E0100; Adobe-Japan1; CID+19631 -7AB6 E0100; Adobe-Japan1; CID+5939 -7AB9 E0100; Adobe-Japan1; CID+18270 -7ABA E0100; Adobe-Japan1; CID+1232 -7ABB E0100; Adobe-Japan1; CID+14932 -7ABB E0101; Hanyo-Denshi; JB4966 -7ABB E0101; Moji_Joho; MJ019288 -7ABB E0102; Hanyo-Denshi; IB2619 -7ABB E0102; Moji_Joho; MJ019289 -7ABB E0103; Hanyo-Denshi; KS287030 -7ABB E0103; Moji_Joho; MJ058250 -7ABC E0100; Adobe-Japan1; CID+14933 -7ABD E0100; Adobe-Japan1; CID+19632 -7ABE E0100; Adobe-Japan1; CID+18271 -7ABE E0101; Adobe-Japan1; CID+20185 -7ABF E0100; Adobe-Japan1; CID+5942 -7ABF E0101; Hanyo-Denshi; JA6767 -7ABF E0101; Moji_Joho; MJ019293 -7ABF E0102; Hanyo-Denshi; FT2386S -7ABF E0102; Moji_Joho; MJ019294 -7AC3 E0100; Adobe-Japan1; CID+1492 -7AC4 E0100; Adobe-Japan1; CID+5941 -7AC4 E0101; Hanyo-Denshi; JA6766 -7AC4 E0101; Moji_Joho; MJ019299 -7AC4 E0102; Hanyo-Denshi; JTB784S -7AC4 E0102; Moji_Joho; MJ019300 -7AC5 E0100; Adobe-Japan1; CID+5940 -7AC6 E0100; Adobe-Japan1; CID+14934 -7AC6 E0101; Adobe-Japan1; CID+15399 -7AC7 E0100; Adobe-Japan1; CID+5944 -7AC8 E0100; Adobe-Japan1; CID+5937 -7AC8 E0101; Adobe-Japan1; CID+20285 -7AC8 E0102; Moji_Joho; MJ019304 -7AC8 E0103; Moji_Joho; MJ019305 -7AC9 E0100; Adobe-Japan1; CID+22140 -7AC9 E0101; Hanyo-Denshi; JB4969 -7AC9 E0102; Hanyo-Denshi; TK01068760 -7AC9 E0103; Hanyo-Denshi; TK01068770 -7ACA E0100; Adobe-Japan1; CID+5945 -7ACB E0100; Adobe-Japan1; CID+3953 -7ACC E0100; Adobe-Japan1; CID+18273 -7ACD E0100; Adobe-Japan1; CID+5946 -7ACE E0100; Adobe-Japan1; CID+17025 -7ACF E0100; Adobe-Japan1; CID+5947 -7AD1 E0100; Adobe-Japan1; CID+8585 -7AD2 E0100; Adobe-Japan1; CID+4549 -7AD3 E0100; Adobe-Japan1; CID+5949 -7AD5 E0100; Adobe-Japan1; CID+5948 -7AD5 E0101; Hanyo-Denshi; JA6773 -7AD5 E0101; Moji_Joho; MJ019320 -7AD5 E0102; Hanyo-Denshi; FT2388 -7AD5 E0102; Moji_Joho; MJ019321 -7AD9 E0100; Adobe-Japan1; CID+5950 -7ADA E0100; Adobe-Japan1; CID+5951 -7ADB E0100; Adobe-Japan1; CID+22141 -7ADC E0100; Adobe-Japan1; CID+3965 -7ADD E0100; Adobe-Japan1; CID+5952 -7ADF E0100; Adobe-Japan1; CID+7176 -7ADF E0101; Hanyo-Denshi; JA8079 -7ADF E0101; Moji_Joho; MJ019330 -7ADF E0102; Hanyo-Denshi; KS288300 -7ADF E0102; Moji_Joho; MJ019331 -7AE0 E0100; Adobe-Japan1; CID+2487 -7AE0 E0101; Hanyo-Denshi; JA3047 -7AE0 E0101; Moji_Joho; MJ019332 -7AE0 E0102; Hanyo-Denshi; JTB78C -7AE0 E0102; Moji_Joho; MJ019333 -7AE1 E0100; Adobe-Japan1; CID+5953 -7AE2 E0100; Adobe-Japan1; CID+5954 -7AE3 E0100; Adobe-Japan1; CID+2401 -7AE3 E0101; Hanyo-Denshi; JA2955 -7AE3 E0101; Moji_Joho; MJ019337 -7AE3 E0102; Hanyo-Denshi; KS288360 -7AE3 E0102; Moji_Joho; MJ019336 -7AE5 E0100; Adobe-Japan1; CID+3216 -7AE5 E0101; Hanyo-Denshi; JA3824 -7AE5 E0101; Moji_Joho; MJ019339 -7AE5 E0102; Hanyo-Denshi; JTB78F -7AE5 E0102; Moji_Joho; MJ019340 -7AE6 E0100; Adobe-Japan1; CID+5955 -7AE7 E0100; Adobe-Japan1; CID+8586 -7AE8 E0100; Adobe-Japan1; CID+18274 -7AE9 E0100; Adobe-Japan1; CID+22142 -7AEA E0100; Adobe-Japan1; CID+2918 -7AEB E0100; Adobe-Japan1; CID+8588 -7AEB E0101; Hanyo-Denshi; JB4976 -7AEB E0101; Moji_Joho; MJ019346 -7AEB E0102; Hanyo-Denshi; JTB792 -7AEB E0102; Moji_Joho; MJ019347 -7AEC E0100; Adobe-Japan1; CID+22143 -7AED E0100; Adobe-Japan1; CID+5956 -7AED E0101; Hanyo-Denshi; JA6781 -7AED E0101; Moji_Joho; MJ019349 -7AED E0102; Hanyo-Denshi; FT2389 -7AED E0102; Moji_Joho; MJ019350 -7AEE E0100; Hanyo-Denshi; IP7AEE -7AEE E0100; Moji_Joho; MJ019351 -7AEE E0101; Hanyo-Denshi; KS288810 -7AEE E0101; Moji_Joho; MJ019352 -7AEF E0100; Adobe-Japan1; CID+2938 -7AF0 E0100; Adobe-Japan1; CID+5957 -7AF1 E0100; Adobe-Japan1; CID+22144 -7AF1 E0101; Hanyo-Denshi; JB4978 -7AF1 E0101; Moji_Joho; MJ019355 -7AF1 E0102; Hanyo-Denshi; JTB795 -7AF1 E0102; Moji_Joho; MJ019356 -7AF2 E0100; Hanyo-Denshi; IP7AF2 -7AF2 E0101; Hanyo-Denshi; TK01069140 -7AF4 E0100; Adobe-Japan1; CID+18275 -7AF4 E0101; Hanyo-Denshi; JB4979 -7AF4 E0102; Hanyo-Denshi; TK01069200 -7AF6 E0100; Adobe-Japan1; CID+1693 -7AF8 E0100; Adobe-Japan1; CID+4214 -7AF9 E0100; Adobe-Japan1; CID+2971 -7AFA E0100; Adobe-Japan1; CID+2271 -7AFB E0100; Adobe-Japan1; CID+22145 -7AFD E0100; Adobe-Japan1; CID+17026 -7AFE E0100; Adobe-Japan1; CID+19633 -7AFF E0100; Adobe-Japan1; CID+1540 -7B02 E0100; Adobe-Japan1; CID+5958 -7B04 E0100; Adobe-Japan1; CID+5971 -7B06 E0100; Adobe-Japan1; CID+5961 -7B07 E0100; Adobe-Japan1; CID+14935 -7B08 E0100; Adobe-Japan1; CID+1666 -7B08 E0101; Adobe-Japan1; CID+7967 -7B08 E0102; Adobe-Japan1; CID+20263 -7B08 E0103; Hanyo-Denshi; JA2172 -7B08 E0103; Moji_Joho; MJ019381 -7B08 E0104; Hanyo-Denshi; HG1613 -7B08 E0104; Moji_Joho; MJ019380 -7B08 E0105; Moji_Joho; MJ019382 -7B0A E0100; Adobe-Japan1; CID+5960 -7B0B E0100; Adobe-Japan1; CID+5973 -7B0F E0100; Adobe-Japan1; CID+5959 -7B11 E0100; Adobe-Japan1; CID+2488 -7B11 E0101; Hanyo-Denshi; JA3048 -7B11 E0101; Moji_Joho; MJ019391 -7B11 E0102; Hanyo-Denshi; JTB7A3 -7B11 E0102; Moji_Joho; MJ060016 -7B12 E0100; Adobe-Japan1; CID+17027 -7B14 E0100; Adobe-Japan1; CID+14936 -7B17 E0100; Hanyo-Denshi; IP7B17 -7B17 E0101; Hanyo-Denshi; TK01069470 -7B18 E0100; Adobe-Japan1; CID+5963 -7B19 E0100; Adobe-Japan1; CID+5964 -7B1B E0100; Adobe-Japan1; CID+3109 -7B1E E0100; Adobe-Japan1; CID+5965 -7B1F E0100; Adobe-Japan1; CID+22146 -7B20 E0100; Adobe-Japan1; CID+1468 -7B23 E0100; Adobe-Japan1; CID+22147 -7B25 E0100; Adobe-Japan1; CID+2592 -7B26 E0100; Adobe-Japan1; CID+3542 -7B27 E0100; Adobe-Japan1; CID+14937 -7B28 E0100; Adobe-Japan1; CID+5967 -7B29 E0100; Adobe-Japan1; CID+22148 -7B2A E0100; Adobe-Japan1; CID+18280 -7B2B E0100; Adobe-Japan1; CID+19634 -7B2C E0100; Adobe-Japan1; CID+2888 -7B2D E0100; Adobe-Japan1; CID+17028 -7B2D E0101; Hanyo-Denshi; JB4991 -7B2D E0102; Hanyo-Denshi; TK01069480 -7B2E E0100; Adobe-Japan1; CID+18281 -7B2F E0100; Adobe-Japan1; CID+18282 -7B30 E0100; Adobe-Japan1; CID+22149 -7B30 E0101; Hanyo-Denshi; JB4994 -7B30 E0102; Hanyo-Denshi; TK01069390 -7B31 E0100; Adobe-Japan1; CID+14938 -7B33 E0100; Adobe-Japan1; CID+5962 -7B34 E0100; Adobe-Japan1; CID+22150 -7B35 E0100; Adobe-Japan1; CID+5966 -7B35 E0101; Hanyo-Denshi; JA6791 -7B35 E0102; Hanyo-Denshi; TK01069490 -7B36 E0100; Adobe-Japan1; CID+5968 -7B39 E0100; Adobe-Japan1; CID+2155 -7B3B E0100; Adobe-Japan1; CID+17029 -7B3D E0100; Adobe-Japan1; CID+18279 -7B3F E0100; Adobe-Japan1; CID+22151 -7B40 E0100; Adobe-Japan1; CID+22152 -7B41 E0100; Adobe-Japan1; CID+18286 -7B45 E0100; Adobe-Japan1; CID+5975 -7B46 E0100; Adobe-Japan1; CID+3488 -7B47 E0100; Adobe-Japan1; CID+14939 -7B48 E0100; Adobe-Japan1; CID+3386 -7B49 E0100; Adobe-Japan1; CID+3187 -7B4B E0100; Adobe-Japan1; CID+1746 -7B4C E0100; Adobe-Japan1; CID+5974 -7B4C E0101; Hanyo-Denshi; JA6805 -7B4C E0101; Moji_Joho; MJ019450 -7B4C E0102; Hanyo-Denshi; FT2390 -7B4C E0102; Moji_Joho; MJ019451 -7B4D E0100; Adobe-Japan1; CID+5972 -7B4E E0100; Adobe-Japan1; CID+14940 -7B4F E0100; Adobe-Japan1; CID+3401 -7B50 E0100; Adobe-Japan1; CID+5969 -7B51 E0100; Adobe-Japan1; CID+2972 -7B51 E0101; Adobe-Japan1; CID+13923 -7B51 E0102; Hanyo-Denshi; JA3562 -7B51 E0102; Moji_Joho; MJ019457 -7B51 E0103; Hanyo-Denshi; KS291140 -7B51 E0103; Moji_Joho; MJ019458 -7B51 E0104; Hanyo-Denshi; JTB7A5 -7B51 E0104; Moji_Joho; MJ019456 -7B52 E0100; Adobe-Japan1; CID+3189 -7B53 E0100; Adobe-Japan1; CID+14173 -7B53 E0101; Hanyo-Denshi; IP7B53 -7B53 E0102; Hanyo-Denshi; TK01069510 -7B54 E0100; Adobe-Japan1; CID+3188 -7B55 E0100; Adobe-Japan1; CID+18288 -7B56 E0100; Adobe-Japan1; CID+2150 -7B5D E0100; Adobe-Japan1; CID+5993 -7B60 E0100; Adobe-Japan1; CID+14941 -7B64 E0100; Adobe-Japan1; CID+18290 -7B65 E0100; Adobe-Japan1; CID+5977 -7B66 E0100; Adobe-Japan1; CID+18291 -7B67 E0100; Adobe-Japan1; CID+5979 -7B69 E0100; Adobe-Japan1; CID+14942 -7B6A E0100; Adobe-Japan1; CID+22153 -7B6C E0100; Adobe-Japan1; CID+5982 -7B6C E0101; Hanyo-Denshi; JA6813 -7B6C E0101; Moji_Joho; MJ019482 -7B6C E0102; Hanyo-Denshi; KS291530 -7B6C E0102; Moji_Joho; MJ019483 -7B6C E0103; Hanyo-Denshi; TK01069680 -7B6D E0100; Adobe-Japan1; CID+14943 -7B6D E0101; Hanyo-Denshi; JB5015 -7B6D E0101; Moji_Joho; MJ019484 -7B6D E0102; Hanyo-Denshi; KS292770 -7B6D E0102; Moji_Joho; MJ019485 -7B6D E0103; Hanyo-Denshi; TK01069800 -7B6E E0100; Adobe-Japan1; CID+5983 -7B6F E0100; Adobe-Japan1; CID+17030 -7B70 E0100; Adobe-Japan1; CID+5980 -7B71 E0100; Adobe-Japan1; CID+5981 -7B72 E0100; Adobe-Japan1; CID+14944 -7B72 E0101; Hanyo-Denshi; JB5017 -7B72 E0101; Moji_Joho; MJ019490 -7B72 E0102; Hanyo-Denshi; JTB7AA -7B72 E0102; Moji_Joho; MJ019491 -7B73 E0100; Adobe-Japan1; CID+18292 -7B74 E0100; Adobe-Japan1; CID+5978 -7B75 E0100; Adobe-Japan1; CID+5976 -7B75 E0101; Adobe-Japan1; CID+20266 -7B75 E0102; Hanyo-Denshi; FT2391 -7B75 E0102; Moji_Joho; MJ019496 -7B75 E0103; Hanyo-Denshi; JA6807 -7B75 E0104; Moji_Joho; MJ019494 -7B75 E0105; Moji_Joho; MJ019495 -7B77 E0100; Adobe-Japan1; CID+19635 -7B79 E0100; Adobe-Japan1; CID+18289 -7B7A E0100; Adobe-Japan1; CID+5970 -7B7F E0100; Adobe-Japan1; CID+18285 -7B84 E0100; Adobe-Japan1; CID+22154 -7B86 E0100; Adobe-Japan1; CID+3615 -7B87 E0100; Adobe-Japan1; CID+1365 -7B89 E0100; Adobe-Japan1; CID+22155 -7B8B E0100; Adobe-Japan1; CID+5990 -7B8D E0100; Adobe-Japan1; CID+5987 -7B8E E0100; Adobe-Japan1; CID+22156 -7B8E E0101; Hanyo-Denshi; JB5022 -7B8E E0102; Hanyo-Denshi; TK01069850 -7B8F E0100; Adobe-Japan1; CID+5992 -7B8F E0101; Hanyo-Denshi; JA6823 -7B8F E0101; Moji_Joho; MJ019518 -7B8F E0102; Hanyo-Denshi; FT2393 -7B8F E0102; Moji_Joho; MJ019519 -7B90 E0100; Adobe-Japan1; CID+18295 -7B90 E0101; Hanyo-Denshi; JB5023 -7B90 E0101; Moji_Joho; MJ019520 -7B90 E0102; Hanyo-Denshi; IB0837 -7B90 E0102; Moji_Joho; MJ019521 -7B91 E0100; Adobe-Japan1; CID+14945 -7B92 E0100; Adobe-Japan1; CID+5991 -7B92 E0101; Hanyo-Denshi; JA6822 -7B92 E0101; Moji_Joho; MJ019523 -7B92 E0102; Hanyo-Denshi; FT2392S -7B92 E0102; Moji_Joho; MJ019524 -7B94 E0100; Adobe-Japan1; CID+3369 -7B95 E0100; Adobe-Japan1; CID+3763 -7B96 E0100; Adobe-Japan1; CID+22157 -7B97 E0100; Adobe-Japan1; CID+2185 -7B98 E0100; Adobe-Japan1; CID+5985 -7B99 E0100; Adobe-Japan1; CID+5994 -7B99 E0101; Adobe-Japan1; CID+7848 -7B99 E0102; Hanyo-Denshi; JA6825 -7B99 E0102; Moji_Joho; MJ019532 -7B99 E0103; Hanyo-Denshi; FT1973 -7B99 E0103; Moji_Joho; MJ019531 -7B9A E0100; Adobe-Japan1; CID+5989 -7B9B E0100; Adobe-Japan1; CID+18296 -7B9B E0101; Hanyo-Denshi; JB5026 -7B9B E0101; Moji_Joho; MJ019535 -7B9B E0102; Hanyo-Denshi; JTB7B0 -7B9B E0102; Moji_Joho; MJ019534 -7B9C E0100; Adobe-Japan1; CID+5988 -7B9C E0101; Hanyo-Denshi; JA6819 -7B9C E0101; Moji_Joho; MJ019536 -7B9C E0102; Hanyo-Denshi; JTB7B3 -7B9C E0102; Moji_Joho; MJ019537 -7B9D E0100; Adobe-Japan1; CID+5984 -7B9E E0100; Adobe-Japan1; CID+8589 -7B9E E0101; Hanyo-Denshi; JB5027 -7B9E E0101; Moji_Joho; MJ019539 -7B9E E0102; Hanyo-Denshi; IB2650 -7B9E E0102; Moji_Joho; MJ019540 -7B9E E0103; Hanyo-Denshi; JTB7BC -7B9E E0103; Moji_Joho; MJ019542 -7B9E E0104; Hanyo-Denshi; JTB7BD -7B9E E0104; Moji_Joho; MJ019543 -7B9F E0100; Adobe-Japan1; CID+5986 -7BA0 E0100; Adobe-Japan1; CID+19636 -7BA0 E0101; Hanyo-Denshi; JB5028 -7BA0 E0101; Moji_Joho; MJ019545 -7BA0 E0102; Hanyo-Denshi; JTB7B5 -7BA0 E0102; Moji_Joho; MJ019546 -7BA1 E0100; Adobe-Japan1; CID+1541 -7BA5 E0100; Adobe-Japan1; CID+22158 -7BAA E0100; Adobe-Japan1; CID+2939 -7BAC E0100; Adobe-Japan1; CID+19637 -7BAC E0101; Hanyo-Denshi; JB5030 -7BAC E0101; Moji_Joho; MJ019553 -7BAC E0102; Hanyo-Denshi; KS292890 -7BAC E0102; Moji_Joho; MJ019554 -7BAD E0100; Adobe-Japan1; CID+2721 -7BAD E0101; Adobe-Japan1; CID+7974 -7BAD E0102; Hanyo-Denshi; JA3293 -7BAD E0102; Moji_Joho; MJ019556 -7BAD E0103; Hanyo-Denshi; HG1639 -7BAD E0103; Moji_Joho; MJ019555 -7BAF E0100; Adobe-Japan1; CID+14946 -7BB0 E0100; Adobe-Japan1; CID+19638 -7BB1 E0100; Adobe-Japan1; CID+3382 -7BB2 E0100; Adobe-Japan1; CID+22159 -7BB4 E0100; Adobe-Japan1; CID+5999 -7BB5 E0100; Adobe-Japan1; CID+18298 -7BB6 E0100; Adobe-Japan1; CID+22160 -7BB8 E0100; Adobe-Japan1; CID+3384 -7BB8 E0101; Adobe-Japan1; CID+7775 -7BB8 E0102; Hanyo-Denshi; JA4004 -7BB8 E0102; Moji_Joho; MJ019567 -7BB8 E0103; Hanyo-Denshi; FT1902 -7BB8 E0103; Moji_Joho; MJ019568 -7BBA E0100; Adobe-Japan1; CID+22161 -7BBB E0100; Adobe-Japan1; CID+22162 -7BBC E0100; Adobe-Japan1; CID+18299 -7BBD E0100; Adobe-Japan1; CID+22163 -7BC0 E0100; Adobe-Japan1; CID+2693 -7BC0 E0101; Adobe-Japan1; CID+13358 -7BC0 E0102; Adobe-Japan1; CID+13879 -7BC0 E0103; Hanyo-Denshi; JA3265 -7BC0 E0103; Moji_Joho; MJ019576 -7BC0 E0104; Hanyo-Denshi; JTB7B6 -7BC0 E0104; Moji_Joho; MJ019577 -7BC0 E0105; Hanyo-Denshi; JC8968 -7BC0 E0106; Hanyo-Denshi; TK01069740 -7BC1 E0100; Adobe-Japan1; CID+5996 -7BC2 E0100; Adobe-Japan1; CID+22164 -7BC4 E0100; Adobe-Japan1; CID+3427 -7BC4 E0101; Hanyo-Denshi; JA4047 -7BC4 E0101; Moji_Joho; MJ019582 -7BC4 E0102; Hanyo-Denshi; IB0838 -7BC4 E0102; Moji_Joho; MJ019583 -7BC4 E0103; Hanyo-Denshi; JTB7C3 -7BC4 E0103; Moji_Joho; MJ019584 -7BC5 E0100; Adobe-Japan1; CID+18300 -7BC6 E0100; Adobe-Japan1; CID+6000 -7BC6 E0101; Hanyo-Denshi; JA6831 -7BC6 E0101; Moji_Joho; MJ019586 -7BC6 E0102; Hanyo-Denshi; FT2394 -7BC6 E0102; Moji_Joho; MJ019587 -7BC6 E0103; Hanyo-Denshi; TK01069900 -7BC7 E0100; Adobe-Japan1; CID+3619 -7BC7 E0101; Adobe-Japan1; CID+7979 -7BC7 E0102; Hanyo-Denshi; JA4251 -7BC7 E0102; Moji_Joho; MJ019590 -7BC7 E0103; Hanyo-Denshi; HG1662 -7BC7 E0103; Moji_Joho; MJ019589 -7BC8 E0100; Adobe-Japan1; CID+22165 -7BC9 E0100; Adobe-Japan1; CID+2969 -7BC9 E0101; Adobe-Japan1; CID+13921 -7BC9 E0102; Hanyo-Denshi; JA3559 -7BC9 E0102; Moji_Joho; MJ019592 -7BC9 E0103; Hanyo-Denshi; KS294020 -7BC9 E0103; Moji_Joho; MJ019593 -7BCA E0100; Adobe-Japan1; CID+18301 -7BCB E0100; Adobe-Japan1; CID+5995 -7BCC E0100; Adobe-Japan1; CID+5997 -7BCF E0100; Adobe-Japan1; CID+5998 -7BD4 E0100; Adobe-Japan1; CID+18304 -7BD6 E0100; Adobe-Japan1; CID+18305 -7BD7 E0100; Adobe-Japan1; CID+14947 -7BD9 E0100; Adobe-Japan1; CID+14948 -7BD9 E0101; Hanyo-Denshi; JB5047 -7BD9 E0102; Hanyo-Denshi; TK01070230 -7BDA E0100; Adobe-Japan1; CID+18306 -7BDB E0100; Adobe-Japan1; CID+22166 -7BDD E0100; Adobe-Japan1; CID+6001 -7BDD E0101; Adobe-Japan1; CID+7997 -7BDD E0102; Hanyo-Denshi; JA6832 -7BDD E0102; Moji_Joho; MJ019611 -7BDD E0103; Hanyo-Denshi; HG1626 -7BDD E0103; Moji_Joho; MJ019610 -7BE0 E0100; Adobe-Japan1; CID+2288 -7BE0 E0101; Adobe-Japan1; CID+20186 -7BE0 E0102; Hanyo-Denshi; JA2836 -7BE0 E0102; Moji_Joho; MJ019615 -7BE0 E0103; Hanyo-Denshi; JTC0F3 -7BE0 E0103; Moji_Joho; MJ019614 -7BE3 E0100; Hanyo-Denshi; IP7BE3 -7BE3 E0100; Moji_Joho; MJ019618 -7BE3 E0101; Hanyo-Denshi; KS295020 -7BE3 E0101; Moji_Joho; MJ019619 -7BE4 E0100; Adobe-Japan1; CID+3230 -7BE5 E0100; Adobe-Japan1; CID+6006 -7BE6 E0100; Adobe-Japan1; CID+6005 -7BE8 E0100; Adobe-Japan1; CID+19639 -7BE9 E0100; Adobe-Japan1; CID+6002 -7BEA E0100; Adobe-Japan1; CID+18307 -7BEB E0100; Hanyo-Denshi; IP7BEB -7BEB E0101; Hanyo-Denshi; TK01070220 -7BED E0100; Adobe-Japan1; CID+4060 -7BF0 E0100; Adobe-Japan1; CID+18308 -7BF2 E0100; Adobe-Japan1; CID+19640 -7BF3 E0100; Adobe-Japan1; CID+6011 -7BF3 E0101; Hanyo-Denshi; JA6842 -7BF3 E0101; Moji_Joho; MJ019635 -7BF3 E0102; Hanyo-Denshi; KS295080 -7BF3 E0102; Moji_Joho; MJ019634 -7BF4 E0100; Adobe-Japan1; CID+22167 -7BF4 E0101; Hanyo-Denshi; JB5053 -7BF4 E0101; Moji_Joho; MJ019637 -7BF4 E0102; Hanyo-Denshi; IB0839 -7BF4 E0102; Moji_Joho; MJ019636 -7BF5 E0100; Adobe-Japan1; CID+22168 -7BF6 E0100; Adobe-Japan1; CID+6015 -7BF6 E0101; Hanyo-Denshi; JA6846 -7BF6 E0102; Hanyo-Denshi; TK01070130 -7BF7 E0100; Adobe-Japan1; CID+6012 -7BF7 E0101; Hanyo-Denshi; JA6843 -7BF7 E0101; Moji_Joho; MJ019641 -7BF7 E0102; Hanyo-Denshi; FT2402 -7BF7 E0102; Moji_Joho; MJ019642 -7BF7 E0103; Moji_Joho; MJ019640 -7BF8 E0100; Adobe-Japan1; CID+19641 -7BF9 E0100; Adobe-Japan1; CID+22169 -7BFA E0100; Adobe-Japan1; CID+22170 -7BFC E0100; Adobe-Japan1; CID+19642 -7BFE E0100; Adobe-Japan1; CID+19643 -7BFE E0101; Hanyo-Denshi; JB5059 -7BFE E0101; Moji_Joho; MJ019649 -7BFE E0102; Hanyo-Denshi; IB2656 -7BFE E0102; Moji_Joho; MJ019650 -7C00 E0100; Adobe-Japan1; CID+6008 -7C01 E0100; Adobe-Japan1; CID+17031 -7C02 E0100; Adobe-Japan1; CID+22171 -7C03 E0100; Adobe-Japan1; CID+18309 -7C04 E0100; Adobe-Japan1; CID+22172 -7C06 E0100; Adobe-Japan1; CID+22173 -7C07 E0100; Adobe-Japan1; CID+6009 -7C09 E0100; Adobe-Japan1; CID+19644 -7C09 E0101; Hanyo-Denshi; JB5065 -7C09 E0101; Moji_Joho; MJ019662 -7C09 E0102; Hanyo-Denshi; IB0840 -7C09 E0102; Moji_Joho; MJ019661 -7C09 E0103; Hanyo-Denshi; JTB7D2 -7C09 E0103; Moji_Joho; MJ019663 -7C0B E0100; Adobe-Japan1; CID+14949 -7C0C E0100; Adobe-Japan1; CID+22174 -7C0D E0100; Adobe-Japan1; CID+6014 -7C0E E0100; Adobe-Japan1; CID+18310 -7C0F E0100; Adobe-Japan1; CID+14950 -7C11 E0100; Adobe-Japan1; CID+6003 -7C12 E0100; Adobe-Japan1; CID+4330 -7C13 E0100; Adobe-Japan1; CID+6010 -7C13 E0101; Hanyo-Denshi; JA6841 -7C13 E0101; Moji_Joho; MJ019673 -7C13 E0102; Hanyo-Denshi; FT2401 -7C13 E0102; Moji_Joho; MJ019675 -7C13 E0103; Moji_Joho; MJ019674 -7C14 E0100; Adobe-Japan1; CID+6004 -7C14 E0101; Adobe-Japan1; CID+14175 -7C17 E0100; Adobe-Japan1; CID+6013 -7C17 E0101; Hanyo-Denshi; JA6844 -7C17 E0102; Hanyo-Denshi; TK01070300 -7C19 E0100; Adobe-Japan1; CID+22175 -7C1B E0100; Adobe-Japan1; CID+22176 -7C1E E0100; Adobe-Japan1; CID+7739 -7C1E E0101; Hanyo-Denshi; JC8973 -7C1E E0102; Hanyo-Denshi; TK01070110 -7C1F E0100; Adobe-Japan1; CID+6019 -7C1F E0101; Hanyo-Denshi; JA6850 -7C1F E0101; Moji_Joho; MJ019686 -7C1F E0102; Hanyo-Denshi; JTB7DA -7C1F E0102; Moji_Joho; MJ019685 -7C20 E0100; Adobe-Japan1; CID+14951 -7C21 E0100; Adobe-Japan1; CID+1542 -7C23 E0100; Adobe-Japan1; CID+6016 -7C25 E0100; Adobe-Japan1; CID+22177 -7C26 E0100; Adobe-Japan1; CID+14952 -7C27 E0100; Adobe-Japan1; CID+6017 -7C27 E0101; Hanyo-Denshi; JA6848 -7C27 E0101; Moji_Joho; MJ019694 -7C27 E0102; Hanyo-Denshi; FT2403 -7C27 E0102; Moji_Joho; MJ019695 -7C28 E0100; Adobe-Japan1; CID+19645 -7C2A E0100; Adobe-Japan1; CID+6018 -7C2A E0101; Hanyo-Denshi; JA6849 -7C2A E0101; Moji_Joho; MJ019700 -7C2A E0102; Hanyo-Denshi; KS297180S -7C2A E0102; Moji_Joho; MJ019699 -7C2A E0103; Hanyo-Denshi; JTB7D8 -7C2A E0103; Moji_Joho; MJ019698 -7C2A E0104; Moji_Joho; MJ019701 -7C2B E0100; Adobe-Japan1; CID+6021 -7C2C E0100; Adobe-Japan1; CID+22178 -7C2F E0100; Adobe-Japan1; CID+19646 -7C31 E0100; Adobe-Japan1; CID+14953 -7C33 E0100; Adobe-Japan1; CID+17032 -7C34 E0100; Adobe-Japan1; CID+22179 -7C34 E0101; Hanyo-Denshi; JB5079 -7C34 E0101; Moji_Joho; MJ019707 -7C34 E0102; Hanyo-Denshi; KS298250 -7C34 E0102; Moji_Joho; MJ019708 -7C36 E0100; Adobe-Japan1; CID+14954 -7C36 E0101; Hanyo-Denshi; JB5080 -7C36 E0101; Moji_Joho; MJ019711 -7C36 E0102; Hanyo-Denshi; IB0841 -7C36 E0102; Moji_Joho; MJ019710 -7C36 E0103; Hanyo-Denshi; TK01070460 -7C37 E0100; Adobe-Japan1; CID+6020 -7C38 E0100; Adobe-Japan1; CID+3466 -7C39 E0100; Adobe-Japan1; CID+22180 -7C3A E0100; Adobe-Japan1; CID+22181 -7C3B E0100; Hanyo-Denshi; IB0842 -7C3B E0100; Moji_Joho; MJ019717 -7C3B E0101; Hanyo-Denshi; IP7C3B -7C3B E0101; Moji_Joho; MJ019718 -7C3D E0100; Adobe-Japan1; CID+6022 -7C3E E0100; Adobe-Japan1; CID+4036 -7C3E E0101; Adobe-Japan1; CID+7981 -7C3E E0102; Adobe-Japan1; CID+20265 -7C3E E0103; Hanyo-Denshi; JA4692 -7C3E E0103; Moji_Joho; MJ019722 -7C3E E0104; Hanyo-Denshi; HG1670 -7C3E E0104; Moji_Joho; MJ019721 -7C3E E0105; Hanyo-Denshi; JTB7DD -7C3E E0105; Moji_Joho; MJ019723 -7C3F E0100; Adobe-Japan1; CID+3645 -7C3F E0101; Adobe-Japan1; CID+14018 -7C3F E0102; Hanyo-Denshi; JA4277 -7C3F E0102; Moji_Joho; MJ019725 -7C3F E0103; Hanyo-Denshi; KS297500 -7C3F E0103; Moji_Joho; MJ019724 -7C40 E0100; Adobe-Japan1; CID+6027 -7C42 E0100; Adobe-Japan1; CID+19647 -7C43 E0100; Adobe-Japan1; CID+6024 -7C45 E0100; Adobe-Japan1; CID+18311 -7C46 E0100; Adobe-Japan1; CID+22182 -7C46 E0101; Hanyo-Denshi; JB5083 -7C46 E0101; Moji_Joho; MJ019730 -7C46 E0102; Hanyo-Denshi; KS297860 -7C46 E0102; Moji_Joho; MJ019731 -7C4A E0100; Adobe-Japan1; CID+18312 -7C4C E0100; Adobe-Japan1; CID+6023 -7C4D E0100; Adobe-Japan1; CID+2678 -7C4D E0101; Adobe-Japan1; CID+13878 -7C4D E0102; Hanyo-Denshi; JA3250 -7C4D E0102; Moji_Joho; MJ019739 -7C4D E0103; Hanyo-Denshi; JTB7DE -7C4D E0103; Moji_Joho; MJ019738 -7C4F E0100; Adobe-Japan1; CID+6026 -7C4F E0101; Hanyo-Denshi; JA6857 -7C4F E0101; Moji_Joho; MJ019740 -7C4F E0102; Hanyo-Denshi; JTB7DF -7C4F E0102; Moji_Joho; MJ060030 -7C50 E0100; Adobe-Japan1; CID+6028 -7C50 E0101; Adobe-Japan1; CID+14177 -7C50 E0102; Adobe-Japan1; CID+20187 -7C50 E0103; Hanyo-Denshi; JA6859 -7C50 E0103; Moji_Joho; MJ019742 -7C50 E0104; Hanyo-Denshi; JTB7E1 -7C50 E0104; Moji_Joho; MJ019741 -7C50 E0105; Hanyo-Denshi; FT2406 -7C50 E0105; Moji_Joho; MJ019743 -7C51 E0100; Adobe-Japan1; CID+14955 -7C51 E0101; Hanyo-Denshi; JB5086 -7C51 E0101; Moji_Joho; MJ019744 -7C51 E0102; Hanyo-Denshi; IA3956 -7C51 E0102; Moji_Joho; MJ019745 -7C52 E0100; Adobe-Japan1; CID+19648 -7C53 E0100; Adobe-Japan1; CID+19649 -7C54 E0100; Adobe-Japan1; CID+6025 -7C54 E0101; Hanyo-Denshi; JA6856 -7C54 E0102; Hanyo-Denshi; TK01070520 -7C55 E0100; Adobe-Japan1; CID+22183 -7C56 E0100; Adobe-Japan1; CID+6032 -7C57 E0100; Adobe-Japan1; CID+18313 -7C58 E0100; Adobe-Japan1; CID+6029 -7C58 E0101; Adobe-Japan1; CID+14178 -7C58 E0102; Hanyo-Denshi; JA6860 -7C58 E0102; Moji_Joho; MJ019753 -7C58 E0103; Hanyo-Denshi; JTB7E7 -7C58 E0103; Moji_Joho; MJ019752 -7C58 E0104; Hanyo-Denshi; FT2407 -7C58 E0104; Moji_Joho; MJ019754 -7C59 E0100; Adobe-Japan1; CID+14956 -7C59 E0101; Hanyo-Denshi; JB5089 -7C59 E0102; Hanyo-Denshi; TK01070590 -7C5A E0100; Adobe-Japan1; CID+22184 -7C5B E0100; Adobe-Japan1; CID+19650 -7C5C E0100; Adobe-Japan1; CID+19651 -7C5C E0101; Hanyo-Denshi; JB5092 -7C5C E0101; Moji_Joho; MJ019759 -7C5C E0102; Hanyo-Denshi; JTB7E6 -7C5C E0102; Moji_Joho; MJ019760 -7C5D E0100; Adobe-Japan1; CID+19652 -7C5E E0100; Adobe-Japan1; CID+18314 -7C5F E0100; Adobe-Japan1; CID+6030 -7C5F E0101; Hanyo-Denshi; JA6861 -7C5F E0101; Moji_Joho; MJ019763 -7C5F E0102; Hanyo-Denshi; FT2408 -7C5F E0102; Moji_Joho; MJ019764 -7C60 E0100; Adobe-Japan1; CID+6007 -7C60 E0101; Hanyo-Denshi; JA6838 -7C60 E0101; Moji_Joho; MJ019765 -7C60 E0102; Hanyo-Denshi; KS299180 -7C60 E0102; Moji_Joho; MJ019767 -7C60 E0103; Hanyo-Denshi; JTB7EB -7C60 E0103; Moji_Joho; MJ019768 -7C60 E0104; Hanyo-Denshi; KS299170 -7C60 E0104; Moji_Joho; MJ019766 -7C60 E0105; Hanyo-Denshi; TK01070600 -7C61 E0100; Adobe-Japan1; CID+18315 -7C63 E0100; Adobe-Japan1; CID+22185 -7C64 E0100; Adobe-Japan1; CID+6031 -7C65 E0100; Adobe-Japan1; CID+6033 -7C67 E0100; Adobe-Japan1; CID+14957 -7C67 E0101; Hanyo-Denshi; JB5103 -7C67 E0101; Moji_Joho; MJ019776 -7C67 E0102; Hanyo-Denshi; IB0843 -7C67 E0102; Moji_Joho; MJ019775 -7C67 E0103; Moji_Joho; MJ019777 -7C69 E0100; Adobe-Japan1; CID+18316 -7C69 E0101; Adobe-Japan1; CID+22186 -7C69 E0102; Hanyo-Denshi; JB5104 -7C69 E0102; Moji_Joho; MJ019778 -7C69 E0103; Hanyo-Denshi; IB0844S -7C69 E0103; Moji_Joho; MJ019779 -7C69 E0104; Hanyo-Denshi; JD8379 -7C69 E0104; Moji_Joho; MJ019780 -7C6A E0100; Hanyo-Denshi; KS299560 -7C6A E0100; Moji_Joho; MJ019781 -7C6A E0101; Hanyo-Denshi; KS299630 -7C6A E0101; Moji_Joho; MJ019782 -7C6C E0100; Adobe-Japan1; CID+6034 -7C6C E0101; Hanyo-Denshi; JA6865 -7C6C E0101; Moji_Joho; MJ019784 -7C6C E0102; Hanyo-Denshi; KS299770 -7C6C E0102; Moji_Joho; MJ019785 -7C6D E0100; Adobe-Japan1; CID+17034 -7C6E E0100; Adobe-Japan1; CID+14958 -7C6F E0100; Adobe-Japan1; CID+18317 -7C6F E0101; Hanyo-Denshi; JD8381 -7C6F E0101; Moji_Joho; MJ019788 -7C6F E0102; Hanyo-Denshi; KS299890 -7C6F E0102; Moji_Joho; MJ019789 -7C70 E0100; Adobe-Japan1; CID+14959 -7C72 E0100; Adobe-Japan1; CID+19653 -7C73 E0100; Adobe-Japan1; CID+3606 -7C73 E0101; Hanyo-Denshi; JA4238 -7C73 E0102; Hanyo-Denshi; TK01042800 -7C75 E0100; Adobe-Japan1; CID+6035 -7C79 E0100; Adobe-Japan1; CID+17035 -7C7B E0100; Adobe-Japan1; CID+14094 -7C7B E0101; Hanyo-Denshi; IP7C7B -7C7B E0101; Moji_Joho; MJ019801 -7C7B E0102; Hanyo-Denshi; KS300470 -7C7B E0102; Moji_Joho; MJ019802 -7C7C E0100; Adobe-Japan1; CID+22187 -7C7D E0100; Adobe-Japan1; CID+19654 -7C7E E0100; Adobe-Japan1; CID+3822 -7C7E E0101; Adobe-Japan1; CID+7800 -7C7E E0102; Adobe-Japan1; CID+20293 -7C7E E0103; Hanyo-Denshi; JA4466 -7C7E E0103; Moji_Joho; MJ019807 -7C7E E0104; Hanyo-Denshi; HG1665 -7C7E E0104; Moji_Joho; MJ019806 -7C7E E0105; Hanyo-Denshi; IB2666 -7C7E E0105; Moji_Joho; MJ019805 -7C81 E0100; Adobe-Japan1; CID+1734 -7C82 E0100; Adobe-Japan1; CID+1791 -7C82 E0101; Adobe-Japan1; CID+20272 -7C82 E0102; Moji_Joho; MJ019811 -7C82 E0103; Moji_Joho; MJ019812 -7C83 E0100; Adobe-Japan1; CID+6036 -7C86 E0100; Adobe-Japan1; CID+22188 -7C87 E0100; Adobe-Japan1; CID+19655 -7C89 E0100; Adobe-Japan1; CID+3588 -7C89 E0101; Adobe-Japan1; CID+13502 -7C89 E0102; Hanyo-Denshi; JA4220 -7C89 E0102; Moji_Joho; MJ019819 -7C89 E0103; Hanyo-Denshi; FT1669 -7C89 E0103; Moji_Joho; MJ019820 -7C8B E0100; Adobe-Japan1; CID+2606 -7C8D E0100; Adobe-Japan1; CID+3772 -7C8F E0100; Adobe-Japan1; CID+17036 -7C90 E0100; Adobe-Japan1; CID+6037 -7C90 E0101; Adobe-Japan1; CID+7849 -7C90 E0102; Hanyo-Denshi; JA6868 -7C90 E0102; Moji_Joho; MJ019827 -7C90 E0103; Hanyo-Denshi; FT1974 -7C90 E0103; Moji_Joho; MJ019828 -7C92 E0100; Adobe-Japan1; CID+3963 -7C94 E0100; Adobe-Japan1; CID+17037 -7C94 E0101; Hanyo-Denshi; JB5115 -7C94 E0101; Moji_Joho; MJ019832 -7C94 E0102; Hanyo-Denshi; JTB7F5 -7C94 E0102; Moji_Joho; MJ019833 -7C95 E0100; Adobe-Japan1; CID+3370 -7C97 E0100; Adobe-Japan1; CID+2760 -7C98 E0100; Adobe-Japan1; CID+3306 -7C9B E0100; Adobe-Japan1; CID+2391 -7C9E E0100; Adobe-Japan1; CID+19656 -7C9F E0100; Adobe-Japan1; CID+1156 -7CA0 E0100; Adobe-Japan1; CID+17038 -7CA1 E0100; Adobe-Japan1; CID+6042 -7CA2 E0100; Adobe-Japan1; CID+6040 -7CA4 E0100; Adobe-Japan1; CID+6038 -7CA4 E0101; Hanyo-Denshi; JA6869 -7CA4 E0101; Moji_Joho; MJ019849 -7CA4 E0102; Hanyo-Denshi; KS301250 -7CA4 E0102; Moji_Joho; MJ058289 -7CA5 E0100; Adobe-Japan1; CID+1501 -7CA6 E0100; Adobe-Japan1; CID+18321 -7CA6 E0101; Hanyo-Denshi; JB5118 -7CA6 E0101; Moji_Joho; MJ019852 -7CA6 E0102; Hanyo-Denshi; JTB90A -7CA6 E0102; Moji_Joho; MJ019851 -7CA7 E0100; Adobe-Japan1; CID+2489 -7CA8 E0100; Adobe-Japan1; CID+6043 -7CAB E0100; Adobe-Japan1; CID+6041 -7CAD E0100; Adobe-Japan1; CID+6039 -7CAE E0100; Adobe-Japan1; CID+6047 -7CAE E0101; Adobe-Japan1; CID+7850 -7CAE E0102; Hanyo-Denshi; JA6878 -7CAE E0102; Moji_Joho; MJ019857 -7CAE E0103; Hanyo-Denshi; FT1975 -7CAE E0103; Moji_Joho; MJ019858 -7CB0 E0100; Adobe-Japan1; CID+22189 -7CB0 E0101; Hanyo-Denshi; JB5119 -7CB0 E0102; Hanyo-Denshi; TK01070830 -7CB1 E0100; Adobe-Japan1; CID+6046 -7CB2 E0100; Adobe-Japan1; CID+6045 -7CB3 E0100; Adobe-Japan1; CID+6044 -7CB3 E0101; Moji_Joho; MJ019864 -7CB3 E0102; Moji_Joho; MJ019865 -7CB6 E0100; Adobe-Japan1; CID+18323 -7CB7 E0100; Adobe-Japan1; CID+18324 -7CB9 E0100; Adobe-Japan1; CID+6048 -7CBA E0100; Adobe-Japan1; CID+19657 -7CBB E0100; Adobe-Japan1; CID+22190 -7CBC E0100; Adobe-Japan1; CID+14960 -7CBD E0100; Adobe-Japan1; CID+6049 -7CBE E0100; Adobe-Japan1; CID+8590 -7CBE E0101; Adobe-Japan1; CID+2654 -7CBE E0102; Hanyo-Denshi; JA3226 -7CBE E0103; Hanyo-Denshi; JTFA1D -7CBF E0100; Adobe-Japan1; CID+14961 -7CC0 E0100; Adobe-Japan1; CID+6050 -7CC0 E0101; Hanyo-Denshi; JA6881 -7CC0 E0101; Moji_Joho; MJ019877 -7CC0 E0102; Hanyo-Denshi; KS301940 -7CC0 E0102; Moji_Joho; MJ019878 -7CC0 E0103; Moji_Joho; MJ019879 -7CC2 E0100; Adobe-Japan1; CID+6052 -7CC2 E0101; Hanyo-Denshi; JA6883 -7CC2 E0101; Moji_Joho; MJ019880 -7CC2 E0102; Hanyo-Denshi; KS302460 -7CC2 E0102; Moji_Joho; MJ019881 -7CC4 E0100; Adobe-Japan1; CID+18326 -7CC5 E0100; Adobe-Japan1; CID+6051 -7CC7 E0100; Adobe-Japan1; CID+19658 -7CC8 E0100; Adobe-Japan1; CID+14962 -7CC9 E0100; Adobe-Japan1; CID+14963 -7CCA E0100; Adobe-Japan1; CID+1926 -7CCD E0100; Adobe-Japan1; CID+18328 -7CCE E0100; Adobe-Japan1; CID+2746 -7CCF E0100; Adobe-Japan1; CID+22191 -7CD2 E0100; Adobe-Japan1; CID+6054 -7CD3 E0100; Adobe-Japan1; CID+19659 -7CD3 E0101; Hanyo-Denshi; JB5132 -7CD3 E0102; Hanyo-Denshi; TK01070930 -7CD3 E0103; Hanyo-Denshi; TK01071050 -7CD4 E0100; Adobe-Japan1; CID+22192 -7CD5 E0100; Adobe-Japan1; CID+17039 -7CD6 E0100; Adobe-Japan1; CID+13956 -7CD6 E0101; Adobe-Japan1; CID+3190 -7CD6 E0102; Hanyo-Denshi; JA3792 -7CD6 E0102; Moji_Joho; MJ019904 -7CD6 E0103; Hanyo-Denshi; JTB7FES -7CD6 E0103; Moji_Joho; MJ019903 -7CD7 E0100; Adobe-Japan1; CID+14964 -7CD8 E0100; Adobe-Japan1; CID+6053 -7CD8 E0101; Hanyo-Denshi; JA6884 -7CD8 E0101; Moji_Joho; MJ019906 -7CD8 E0102; Hanyo-Denshi; FT2411 -7CD8 E0102; Moji_Joho; MJ019907 -7CD9 E0100; Adobe-Japan1; CID+14965 -7CD9 E0101; Hanyo-Denshi; JB5136 -7CD9 E0101; Moji_Joho; MJ019909 -7CD9 E0102; Hanyo-Denshi; IB0845 -7CD9 E0102; Moji_Joho; MJ019908 -7CDA E0100; Adobe-Japan1; CID+19660 -7CDA E0101; Hanyo-Denshi; JB5137 -7CDA E0101; Moji_Joho; MJ019910 -7CDA E0102; Hanyo-Denshi; KS302840 -7CDA E0102; Moji_Joho; MJ019911 -7CDA E0103; Hanyo-Denshi; TK01070920 -7CDC E0100; Adobe-Japan1; CID+6055 -7CDC E0101; Hanyo-Denshi; JA6886 -7CDC E0101; Moji_Joho; MJ019914 -7CDC E0102; Hanyo-Denshi; FT2412 -7CDC E0102; Moji_Joho; MJ019915 -7CDD E0100; Adobe-Japan1; CID+14966 -7CDE E0100; Adobe-Japan1; CID+3589 -7CDF E0100; Adobe-Japan1; CID+2798 -7CE0 E0100; Adobe-Japan1; CID+2009 -7CE1 E0100; Hanyo-Denshi; IP7CE1 -7CE1 E0100; Moji_Joho; MJ019920 -7CE1 E0101; Hanyo-Denshi; KS303140 -7CE1 E0101; Moji_Joho; MJ019921 -7CE2 E0100; Adobe-Japan1; CID+6056 -7CE2 E0101; Hanyo-Denshi; JA6887 -7CE2 E0101; Moji_Joho; MJ019922 -7CE2 E0102; Hanyo-Denshi; KS303090 -7CE2 E0102; Moji_Joho; MJ019923 -7CE6 E0100; Adobe-Japan1; CID+18331 -7CE7 E0100; Adobe-Japan1; CID+3984 -7CE9 E0100; Adobe-Japan1; CID+22193 -7CEB E0100; Adobe-Japan1; CID+14967 -7CEF E0100; Adobe-Japan1; CID+6058 -7CF2 E0100; Adobe-Japan1; CID+6059 -7CF2 E0101; Adobe-Japan1; CID+13574 -7CF2 E0102; Hanyo-Denshi; JA6890 -7CF2 E0102; Moji_Joho; MJ019937 -7CF2 E0103; Hanyo-Denshi; KS303840 -7CF2 E0103; Moji_Joho; MJ019938 -7CF4 E0100; Adobe-Japan1; CID+6060 -7CF4 E0101; Hanyo-Denshi; JA6891 -7CF4 E0101; Moji_Joho; MJ019940 -7CF4 E0102; Hanyo-Denshi; JTB804 -7CF4 E0102; Moji_Joho; MJ019941 -7CF5 E0100; Adobe-Japan1; CID+18333 -7CF5 E0101; Hanyo-Denshi; JB5142 -7CF5 E0101; Moji_Joho; MJ019942 -7CF5 E0102; Hanyo-Denshi; KS304030 -7CF5 E0102; Moji_Joho; MJ019943 -7CF6 E0100; Adobe-Japan1; CID+6061 -7CF6 E0101; Hanyo-Denshi; JA6892 -7CF6 E0101; Moji_Joho; MJ019944 -7CF6 E0102; Hanyo-Denshi; JTB805 -7CF6 E0102; Moji_Joho; MJ019945 -7CF8 E0100; Adobe-Japan1; CID+2227 -7CFA E0100; Adobe-Japan1; CID+6062 -7CFB E0100; Adobe-Japan1; CID+1829 -7CFB E0101; Hanyo-Denshi; JA2347 -7CFB E0102; Hanyo-Denshi; TK01071180 -7CFE E0100; Adobe-Japan1; CID+1668 -7CFE E0101; Hanyo-Denshi; JA2174 -7CFE E0101; Moji_Joho; MJ019953 -7CFE E0102; Hanyo-Denshi; KS304400 -7CFE E0102; Moji_Joho; MJ019952 -7D00 E0100; Adobe-Japan1; CID+1604 -7D00 E0101; Hanyo-Denshi; JA2110 -7D00 E0101; Moji_Joho; MJ019955 -7D00 E0102; Hanyo-Denshi; JTB807 -7D00 E0102; Moji_Joho; MJ019956 -7D00 E0103; Hanyo-Denshi; JTB806 -7D00 E0103; Moji_Joho; MJ019957 -7D00 E0104; Hanyo-Denshi; JTB808 -7D00 E0104; Moji_Joho; MJ019958 -7D00 E0105; Hanyo-Denshi; TK01071280 -7D00 E0106; Hanyo-Denshi; TK01071320 -7D00 E0107; Hanyo-Denshi; TK01071340 -7D02 E0100; Adobe-Japan1; CID+6064 -7D03 E0100; Adobe-Japan1; CID+18334 -7D04 E0100; Adobe-Japan1; CID+3839 -7D04 E0101; Adobe-Japan1; CID+14062 -7D04 E0102; Hanyo-Denshi; JA4483 -7D04 E0102; Moji_Joho; MJ019965 -7D04 E0103; Hanyo-Denshi; KS304670 -7D04 E0103; Moji_Joho; MJ019966 -7D05 E0100; Adobe-Japan1; CID+2010 -7D05 E0101; Hanyo-Denshi; JA2540 -7D05 E0102; Hanyo-Denshi; TK01071330 -7D06 E0100; Adobe-Japan1; CID+6063 -7D07 E0100; Adobe-Japan1; CID+14968 -7D08 E0100; Adobe-Japan1; CID+14969 -7D08 E0101; Moji_Joho; MJ019971 -7D08 E0102; Moji_Joho; MJ019972 -7D09 E0100; Adobe-Japan1; CID+14970 -7D09 E0101; Adobe-Japan1; CID+20188 -7D09 E0102; Hanyo-Denshi; JB5146 -7D09 E0103; Hanyo-Denshi; TK01071270 -7D0A E0100; Adobe-Japan1; CID+6067 -7D0A E0101; Moji_Joho; MJ019975 -7D0A E0102; Moji_Joho; MJ019976 -7D0B E0100; Adobe-Japan1; CID+3826 -7D0B E0101; Adobe-Japan1; CID+14060 -7D0B E0102; Moji_Joho; MJ019977 -7D0B E0103; Moji_Joho; MJ019978 -7D0D E0100; Adobe-Japan1; CID+3314 -7D0D E0101; Adobe-Japan1; CID+13972 -7D0D E0102; Hanyo-Denshi; JA3928 -7D0D E0102; Moji_Joho; MJ019981 -7D0D E0103; Hanyo-Denshi; JTB80B -7D0D E0103; Moji_Joho; MJ019980 -7D0D E0104; Hanyo-Denshi; JTB80C -7D0D E0104; Moji_Joho; MJ019982 -7D0D E0105; Hanyo-Denshi; TK01071500 -7D0F E0100; Adobe-Japan1; CID+22194 -7D10 E0100; Adobe-Japan1; CID+3493 -7D11 E0100; Adobe-Japan1; CID+22195 -7D12 E0100; Adobe-Japan1; CID+18336 -7D13 E0100; Adobe-Japan1; CID+14971 -7D14 E0100; Adobe-Japan1; CID+2413 -7D14 E0101; Hanyo-Denshi; JA2967 -7D14 E0101; Moji_Joho; MJ019990 -7D14 E0102; Hanyo-Denshi; JTB811 -7D14 E0102; Moji_Joho; MJ019991 -7D14 E0103; Hanyo-Denshi; TK01071380 -7D14 E0104; Hanyo-Denshi; TK01071410 -7D15 E0100; Adobe-Japan1; CID+6066 -7D16 E0100; Adobe-Japan1; CID+22196 -7D17 E0100; Adobe-Japan1; CID+2303 -7D18 E0100; Adobe-Japan1; CID+2011 -7D19 E0100; Adobe-Japan1; CID+2228 -7D19 E0101; Hanyo-Denshi; JA2770 -7D19 E0102; Hanyo-Denshi; TK01071400 -7D1A E0100; Adobe-Japan1; CID+1667 -7D1A E0101; Adobe-Japan1; CID+13713 -7D1A E0102; Hanyo-Denshi; JA2173 -7D1A E0102; Moji_Joho; MJ020000 -7D1A E0103; Hanyo-Denshi; JTB80DS -7D1A E0103; Moji_Joho; MJ020001 -7D1B E0100; Adobe-Japan1; CID+3590 -7D1B E0101; Adobe-Japan1; CID+13503 -7D1B E0102; Hanyo-Denshi; JA4222 -7D1B E0102; Moji_Joho; MJ020002 -7D1B E0103; Hanyo-Denshi; FT1670 -7D1B E0103; Moji_Joho; MJ020003 -7D1C E0100; Adobe-Japan1; CID+6065 -7D1D E0100; Adobe-Japan1; CID+14972 -7D1E E0100; Adobe-Japan1; CID+18337 -7D20 E0100; Adobe-Japan1; CID+2761 -7D21 E0100; Adobe-Japan1; CID+3696 -7D22 E0100; Adobe-Japan1; CID+2151 -7D23 E0100; Adobe-Japan1; CID+14973 -7D26 E0100; Adobe-Japan1; CID+22197 -7D2A E0100; Adobe-Japan1; CID+22198 -7D2B E0100; Adobe-Japan1; CID+2229 -7D2C E0100; Adobe-Japan1; CID+3065 -7D2D E0100; Adobe-Japan1; CID+22199 -7D2E E0100; Adobe-Japan1; CID+6070 -7D2F E0100; Adobe-Japan1; CID+4007 -7D30 E0100; Adobe-Japan1; CID+2121 -7D30 E0101; Hanyo-Denshi; JA2657 -7D30 E0102; Hanyo-Denshi; TK01071680 -7D31 E0100; Adobe-Japan1; CID+17040 -7D31 E0101; Hanyo-Denshi; JB5158 -7D31 E0102; Hanyo-Denshi; TK01071390 -7D31 E0103; Hanyo-Denshi; TK01071460 -7D32 E0100; Adobe-Japan1; CID+6071 -7D33 E0100; Adobe-Japan1; CID+2568 -7D35 E0100; Adobe-Japan1; CID+6073 -7D39 E0100; Adobe-Japan1; CID+2490 -7D39 E0101; Hanyo-Denshi; JA3050 -7D39 E0102; Hanyo-Denshi; TK01071690 -7D3A E0100; Adobe-Japan1; CID+2080 -7D3C E0100; Adobe-Japan1; CID+19661 -7D3D E0100; Adobe-Japan1; CID+18340 -7D3E E0100; Adobe-Japan1; CID+18341 -7D3F E0100; Adobe-Japan1; CID+6072 -7D40 E0100; Adobe-Japan1; CID+18342 -7D41 E0100; Adobe-Japan1; CID+14974 -7D42 E0100; Adobe-Japan1; CID+2356 -7D42 E0101; Adobe-Japan1; CID+13816 -7D42 E0102; Hanyo-Denshi; JA2910 -7D42 E0102; Moji_Joho; MJ020047 -7D42 E0103; Hanyo-Denshi; JTB813 -7D42 E0103; Moji_Joho; MJ020046 -7D43 E0100; Adobe-Japan1; CID+1906 -7D44 E0100; Adobe-Japan1; CID+2762 -7D44 E0101; Hanyo-Denshi; JA3340 -7D44 E0102; Hanyo-Denshi; TK01071700 -7D45 E0100; Adobe-Japan1; CID+6068 -7D46 E0100; Adobe-Japan1; CID+6074 -7D46 E0101; Adobe-Japan1; CID+14179 -7D46 E0102; Hanyo-Denshi; JA6911 -7D46 E0102; Moji_Joho; MJ020052 -7D46 E0103; Hanyo-Denshi; FT2416 -7D46 E0103; Moji_Joho; MJ020053 -7D47 E0100; Adobe-Japan1; CID+18343 -7D48 E0100; Adobe-Japan1; CID+8591 -7D4A E0100; Hanyo-Denshi; IP7D4A -7D4A E0101; Hanyo-Denshi; TK01071580 -7D4B E0100; Adobe-Japan1; CID+6069 -7D4B E0101; Hanyo-Denshi; JA6906 -7D4B E0102; Hanyo-Denshi; TK01071710 -7D4C E0100; Adobe-Japan1; CID+1830 -7D4C E0101; Hanyo-Denshi; JA2348 -7D4C E0102; Hanyo-Denshi; TK01071720 -7D4D E0100; Adobe-Japan1; CID+19662 -7D4E E0100; Adobe-Japan1; CID+6077 -7D4F E0100; Adobe-Japan1; CID+6081 -7D50 E0100; Adobe-Japan1; CID+1857 -7D50 E0101; Hanyo-Denshi; JA2375 -7D50 E0102; Hanyo-Denshi; TK01071750 -7D51 E0100; Adobe-Japan1; CID+22200 -7D53 E0100; Adobe-Japan1; CID+14975 -7D55 E0100; Adobe-Japan1; CID+13882 -7D56 E0100; Adobe-Japan1; CID+6076 -7D57 E0100; Adobe-Japan1; CID+22201 -7D58 E0100; Hanyo-Denshi; IP7D58 -7D58 E0100; Moji_Joho; MJ020075 -7D58 E0101; Hanyo-Denshi; JT7D58 -7D58 E0101; Moji_Joho; MJ020076 -7D59 E0100; Adobe-Japan1; CID+14976 -7D5A E0100; Adobe-Japan1; CID+18347 -7D5A E0101; Moji_Joho; MJ020078 -7D5A E0102; Moji_Joho; MJ060044 -7D5B E0100; Adobe-Japan1; CID+6085 -7D5C E0100; Adobe-Japan1; CID+17041 -7D5C E0101; Adobe-Japan1; CID+8592 -7D5C E0102; Hanyo-Denshi; JB5172 -7D5C E0102; Moji_Joho; MJ020080 -7D5C E0103; Hanyo-Denshi; JC9004 -7D5C E0103; Moji_Joho; MJ020082 -7D5C E0104; Hanyo-Denshi; KS306820 -7D5C E0104; Moji_Joho; MJ020081 -7D5C E0105; Hanyo-Denshi; JTB818 -7D5C E0105; Moji_Joho; MJ020083 -7D5D E0100; Adobe-Japan1; CID+14977 -7D5D E0101; Hanyo-Denshi; JB5173 -7D5D E0101; Moji_Joho; MJ020084 -7D5D E0102; Hanyo-Denshi; KS306860 -7D5D E0102; Moji_Joho; MJ058304 -7D5E E0100; Adobe-Japan1; CID+2012 -7D5E E0101; Adobe-Japan1; CID+13444 -7D5E E0102; Moji_Joho; MJ020085 -7D5E E0103; Moji_Joho; MJ020086 -7D61 E0100; Adobe-Japan1; CID+3927 -7D62 E0100; Adobe-Japan1; CID+1152 -7D63 E0100; Adobe-Japan1; CID+6082 -7D63 E0101; Adobe-Japan1; CID+14180 -7D63 E0102; Hanyo-Denshi; JA6919 -7D63 E0102; Moji_Joho; MJ020091 -7D63 E0103; Hanyo-Denshi; KS308020 -7D63 E0103; Moji_Joho; MJ020092 -7D65 E0100; Adobe-Japan1; CID+22202 -7D66 E0100; Adobe-Japan1; CID+1669 -7D67 E0100; Adobe-Japan1; CID+22203 -7D68 E0100; Adobe-Japan1; CID+6079 -7D6A E0100; Adobe-Japan1; CID+18348 -7D6E E0100; Adobe-Japan1; CID+6080 -7D6F E0100; Hanyo-Denshi; IP7D6F -7D6F E0100; Moji_Joho; MJ020104 -7D6F E0101; Hanyo-Denshi; KS306840 -7D6F E0101; Moji_Joho; MJ020105 -7D70 E0100; Adobe-Japan1; CID+18349 -7D71 E0100; Adobe-Japan1; CID+3191 -7D71 E0101; Hanyo-Denshi; JA3793 -7D71 E0101; Moji_Joho; MJ020108 -7D71 E0102; Hanyo-Denshi; KS306070 -7D71 E0102; Moji_Joho; MJ020107 -7D72 E0100; Adobe-Japan1; CID+6078 -7D73 E0100; Adobe-Japan1; CID+6075 -7D73 E0101; Adobe-Japan1; CID+13575 -7D73 E0102; Hanyo-Denshi; JA6912 -7D73 E0102; Moji_Joho; MJ020110 -7D73 E0103; Hanyo-Denshi; FT2417S -7D73 E0103; Moji_Joho; MJ020111 -7D73 E0104; Moji_Joho; MJ020112 -7D75 E0100; Adobe-Japan1; CID+1414 -7D76 E0100; Adobe-Japan1; CID+2696 -7D78 E0100; Adobe-Japan1; CID+22204 -7D79 E0100; Adobe-Japan1; CID+1884 -7D79 E0101; Hanyo-Denshi; JA2408 -7D79 E0101; Moji_Joho; MJ020118 -7D79 E0102; Hanyo-Denshi; JTB81B -7D79 E0102; Moji_Joho; MJ020117 -7D79 E0103; Hanyo-Denshi; TK01072150 -7D7A E0100; Adobe-Japan1; CID+14978 -7D7B E0100; Adobe-Japan1; CID+22205 -7D7D E0100; Adobe-Japan1; CID+6087 -7D7F E0100; Adobe-Japan1; CID+18351 -7D81 E0100; Adobe-Japan1; CID+22206 -7D81 E0101; Hanyo-Denshi; JB5182 -7D81 E0101; Moji_Joho; MJ020127 -7D81 E0102; Hanyo-Denshi; JTB821 -7D81 E0102; Moji_Joho; MJ020128 -7D82 E0100; Adobe-Japan1; CID+19663 -7D83 E0100; Adobe-Japan1; CID+17042 -7D83 E0101; Hanyo-Denshi; JB5184 -7D83 E0102; Hanyo-Denshi; TK01072160 -7D85 E0100; Adobe-Japan1; CID+19664 -7D86 E0100; Adobe-Japan1; CID+14979 -7D86 E0101; Hanyo-Denshi; JB5186 -7D86 E0101; Moji_Joho; MJ020133 -7D86 E0102; Hanyo-Denshi; JTB826 -7D86 E0102; Moji_Joho; MJ020135 -7D86 E0103; Moji_Joho; MJ020134 -7D88 E0100; Adobe-Japan1; CID+18353 -7D89 E0100; Adobe-Japan1; CID+6084 -7D8B E0100; Adobe-Japan1; CID+14980 -7D8C E0100; Adobe-Japan1; CID+14981 -7D8D E0100; Adobe-Japan1; CID+19665 -7D8F E0100; Adobe-Japan1; CID+6086 -7D8F E0101; Hanyo-Denshi; JA6923 -7D8F E0101; Moji_Joho; MJ020144 -7D8F E0102; Hanyo-Denshi; FT2418 -7D8F E0102; Moji_Joho; MJ020145 -7D91 E0100; Adobe-Japan1; CID+19666 -7D92 E0100; Hanyo-Denshi; IP7D92 -7D92 E0101; Hanyo-Denshi; TK01072090 -7D93 E0100; Adobe-Japan1; CID+6083 -7D93 E0101; Hanyo-Denshi; JA6920 -7D93 E0101; Moji_Joho; MJ020150 -7D93 E0102; Hanyo-Denshi; JTB827 -7D93 E0102; Moji_Joho; MJ020151 -7D93 E0103; Hanyo-Denshi; TK01072060 -7D96 E0100; Adobe-Japan1; CID+22207 -7D97 E0100; Adobe-Japan1; CID+18354 -7D97 E0101; Hanyo-Denshi; JB5193 -7D97 E0102; Hanyo-Denshi; TK01071950 -7D99 E0100; Adobe-Japan1; CID+1831 -7D9A E0100; Adobe-Japan1; CID+2835 -7D9B E0100; Adobe-Japan1; CID+6088 -7D9B E0101; Adobe-Japan1; CID+7851 -7D9B E0102; Hanyo-Denshi; JA6925 -7D9B E0102; Moji_Joho; MJ020163 -7D9B E0103; Hanyo-Denshi; FT1976 -7D9B E0103; Moji_Joho; MJ020164 -7D9B E0104; Hanyo-Denshi; JTB822 -7D9B E0104; Moji_Joho; MJ020162 -7D9C E0100; Adobe-Japan1; CID+2800 -7D9D E0100; Adobe-Japan1; CID+18356 -7D9E E0100; Adobe-Japan1; CID+19667 -7D9E E0101; Hanyo-Denshi; JB5201 -7D9E E0101; Moji_Joho; MJ020167 -7D9E E0102; Hanyo-Denshi; JTB846 -7D9E E0102; Moji_Joho; MJ060054 -7D9F E0100; Adobe-Japan1; CID+6101 -7D9F E0101; Adobe-Japan1; CID+7853 -7D9F E0102; Hanyo-Denshi; JA6938 -7D9F E0102; Moji_Joho; MJ020168 -7D9F E0103; Hanyo-Denshi; FT1978 -7D9F E0103; Moji_Joho; MJ020169 -7DA0 E0100; Adobe-Japan1; CID+8594 -7DA0 E0101; Moji_Joho; MJ020170 -7DA0 E0102; Moji_Joho; MJ020171 -7DA2 E0100; Adobe-Japan1; CID+6097 -7DA2 E0101; Hanyo-Denshi; JA6934 -7DA2 E0101; Moji_Joho; MJ020173 -7DA2 E0102; Hanyo-Denshi; FT2421 -7DA2 E0102; Moji_Joho; MJ020174 -7DA3 E0100; Adobe-Japan1; CID+6091 -7DA3 E0101; Hanyo-Denshi; JA6928 -7DA3 E0101; Moji_Joho; MJ020175 -7DA3 E0102; Hanyo-Denshi; FT2419 -7DA3 E0102; Moji_Joho; MJ020176 -7DA6 E0100; Adobe-Japan1; CID+17043 -7DA7 E0100; Adobe-Japan1; CID+18357 -7DAA E0100; Adobe-Japan1; CID+18358 -7DAA E0101; Hanyo-Denshi; JB5204 -7DAA E0101; Moji_Joho; MJ020183 -7DAA E0102; Hanyo-Denshi; IB0846 -7DAA E0102; Moji_Joho; MJ020184 -7DAB E0100; Adobe-Japan1; CID+6095 -7DAC E0100; Adobe-Japan1; CID+2342 -7DAD E0100; Adobe-Japan1; CID+1185 -7DAD E0101; Hanyo-Denshi; JA1661 -7DAD E0102; Hanyo-Denshi; TK01072230 -7DAE E0100; Adobe-Japan1; CID+6090 -7DAE E0101; Adobe-Japan1; CID+7852 -7DAE E0102; Hanyo-Denshi; JA6927 -7DAE E0102; Moji_Joho; MJ020190 -7DAE E0103; Hanyo-Denshi; FT1977 -7DAE E0103; Moji_Joho; MJ020189 -7DAF E0100; Adobe-Japan1; CID+6098 -7DAF E0101; Hanyo-Denshi; JA6935 -7DAF E0101; Moji_Joho; MJ020191 -7DAF E0102; Hanyo-Denshi; KS308750 -7DAF E0102; Moji_Joho; MJ058312 -7DB0 E0100; Adobe-Japan1; CID+6102 -7DB1 E0100; Adobe-Japan1; CID+2013 -7DB1 E0101; Hanyo-Denshi; JA2543 -7DB1 E0101; Moji_Joho; MJ020193 -7DB1 E0102; Hanyo-Denshi; KS309880 -7DB1 E0102; Moji_Joho; MJ058319 -7DB2 E0100; Adobe-Japan1; CID+3810 -7DB2 E0101; Adobe-Japan1; CID+20189 -7DB2 E0102; Adobe-Japan1; CID+20190 -7DB2 E0103; Hanyo-Denshi; JA4454 -7DB2 E0103; Moji_Joho; MJ020195 -7DB2 E0104; Hanyo-Denshi; KS308080 -7DB2 E0104; Moji_Joho; MJ020194 -7DB2 E0105; Hanyo-Denshi; JTB833 -7DB2 E0105; Moji_Joho; MJ060050 -7DB2 E0106; Hanyo-Denshi; KS308760 -7DB2 E0106; Moji_Joho; MJ058313 -7DB3 E0100; Adobe-Japan1; CID+19668 -7DB3 E0101; Hanyo-Denshi; JB5205 -7DB3 E0102; Hanyo-Denshi; TK01072320 -7DB4 E0100; Adobe-Japan1; CID+3058 -7DB5 E0100; Adobe-Japan1; CID+6092 -7DB5 E0101; Hanyo-Denshi; JA6929 -7DB5 E0101; Moji_Joho; MJ020199 -7DB5 E0102; Hanyo-Denshi; FT2420 -7DB5 E0102; Moji_Joho; MJ020200 -7DB6 E0100; Adobe-Japan1; CID+18359 -7DB7 E0100; Adobe-Japan1; CID+8593 -7DB8 E0100; Adobe-Japan1; CID+6100 -7DB9 E0100; Adobe-Japan1; CID+19669 -7DB9 E0101; Hanyo-Denshi; JB5208 -7DB9 E0101; Moji_Joho; MJ020204 -7DB9 E0102; Hanyo-Denshi; KS308740 -7DB9 E0102; Moji_Joho; MJ020205 -7DBA E0100; Adobe-Japan1; CID+6089 -7DBB E0100; Adobe-Japan1; CID+2940 -7DBC E0100; Hanyo-Denshi; IP7DBC -7DBC E0101; Hanyo-Denshi; TK01072330 -7DBD E0100; Adobe-Japan1; CID+6094 -7DBE E0100; Adobe-Japan1; CID+1153 -7DBE E0101; Hanyo-Denshi; JA1629 -7DBE E0101; Moji_Joho; MJ020212 -7DBE E0102; Hanyo-Denshi; KS308220 -7DBE E0102; Moji_Joho; MJ020211 -7DBE E0103; Hanyo-Denshi; TK01072250 -7DBF E0100; Adobe-Japan1; CID+3798 -7DBF E0101; Hanyo-Denshi; JA4442 -7DBF E0102; Hanyo-Denshi; TK01072340 -7DC0 E0100; Adobe-Japan1; CID+18360 -7DC2 E0100; Adobe-Japan1; CID+17044 -7DC3 E0100; Adobe-Japan1; CID+22208 -7DC4 E0100; Adobe-Japan1; CID+22209 -7DC5 E0100; Adobe-Japan1; CID+22210 -7DC6 E0100; Adobe-Japan1; CID+22211 -7DC7 E0100; Adobe-Japan1; CID+6093 -7DC7 E0101; Hanyo-Denshi; JA6930 -7DC7 E0101; Moji_Joho; MJ020223 -7DC7 E0102; Hanyo-Denshi; KS309680 -7DC7 E0102; Moji_Joho; MJ020224 -7DCA E0100; Adobe-Japan1; CID+1747 -7DCB E0100; Adobe-Japan1; CID+3456 -7DCB E0101; Adobe-Japan1; CID+13494 -7DCB E0102; Hanyo-Denshi; JA4076 -7DCB E0102; Moji_Joho; MJ020228 -7DCB E0103; Hanyo-Denshi; FT1664 -7DCB E0103; Moji_Joho; MJ020229 -7DCC E0100; Adobe-Japan1; CID+14982 -7DCD E0100; Adobe-Japan1; CID+22212 -7DCE E0100; Adobe-Japan1; CID+22213 -7DCF E0100; Adobe-Japan1; CID+2799 -7DCF E0101; Adobe-Japan1; CID+13472 -7DCF E0102; Hanyo-Denshi; JA3377 -7DCF E0102; Moji_Joho; MJ020233 -7DCF E0103; Hanyo-Denshi; FT1644 -7DCF E0103; Moji_Joho; MJ020234 -7DD0 E0100; Adobe-Japan1; CID+19670 -7DD1 E0100; Adobe-Japan1; CID+3992 -7DD1 E0101; Hanyo-Denshi; JA4648 -7DD1 E0102; Hanyo-Denshi; TK01072350 -7DD2 E0100; Adobe-Japan1; CID+2425 -7DD5 E0100; Adobe-Japan1; CID+6141 -7DD6 E0100; Adobe-Japan1; CID+8595 -7DD7 E0100; Adobe-Japan1; CID+18361 -7DD8 E0100; Adobe-Japan1; CID+6103 -7DD9 E0100; Adobe-Japan1; CID+18362 -7DDA E0100; Adobe-Japan1; CID+2722 -7DDC E0100; Adobe-Japan1; CID+6099 -7DDD E0100; Adobe-Japan1; CID+6104 -7DDD E0101; Adobe-Japan1; CID+13576 -7DDD E0102; Moji_Joho; MJ020246 -7DDD E0103; Moji_Joho; MJ020247 -7DDE E0100; Adobe-Japan1; CID+6106 -7DE0 E0100; Adobe-Japan1; CID+3093 -7DE0 E0101; Hanyo-Denshi; JA3689 -7DE0 E0101; Moji_Joho; MJ020250 -7DE0 E0102; Hanyo-Denshi; JTB83C -7DE0 E0102; Moji_Joho; MJ020251 -7DE1 E0100; Adobe-Japan1; CID+6109 -7DE2 E0100; Adobe-Japan1; CID+22215 -7DE2 E0101; Hanyo-Denshi; JB5220 -7DE2 E0101; Moji_Joho; MJ020253 -7DE2 E0102; Hanyo-Denshi; KS309000 -7DE2 E0102; Moji_Joho; MJ020254 -7DE3 E0100; Adobe-Japan1; CID+13322 -7DE3 E0101; Moji_Joho; MJ020255 -7DE3 E0102; Moji_Joho; MJ020256 -7DE4 E0100; Adobe-Japan1; CID+6105 -7DE5 E0100; Adobe-Japan1; CID+19671 -7DE6 E0100; Adobe-Japan1; CID+18363 -7DE8 E0100; Adobe-Japan1; CID+3620 -7DE8 E0101; Adobe-Japan1; CID+14015 -7DE8 E0102; Hanyo-Denshi; JA4252 -7DE8 E0102; Moji_Joho; MJ020262 -7DE8 E0103; Hanyo-Denshi; JTB83F -7DE8 E0103; Moji_Joho; MJ020261 -7DE9 E0100; Adobe-Japan1; CID+1543 -7DE9 E0101; Adobe-Japan1; CID+13690 -7DE9 E0102; Hanyo-Denshi; JA2043 -7DE9 E0102; Moji_Joho; MJ020264 -7DE9 E0103; Hanyo-Denshi; JTB840 -7DE9 E0103; Moji_Joho; MJ020263 -7DEA E0100; Adobe-Japan1; CID+22216 -7DEB E0100; Adobe-Japan1; CID+14983 -7DEC E0100; Adobe-Japan1; CID+3799 -7DED E0100; Adobe-Japan1; CID+22217 -7DEF E0100; Adobe-Japan1; CID+1186 -7DEF E0101; Adobe-Japan1; CID+13410 -7DEF E0102; Hanyo-Denshi; JA1662 -7DEF E0102; Moji_Joho; MJ020270 -7DEF E0103; Hanyo-Denshi; KS309290S -7DEF E0103; Moji_Joho; MJ020269 -7DEF E0104; Moji_Joho; MJ020271 -7DF0 E0100; Hanyo-Denshi; IP7DF0 -7DF0 E0100; Moji_Joho; MJ020272 -7DF0 E0101; Hanyo-Denshi; JTB841 -7DF0 E0101; Moji_Joho; MJ020273 -7DF1 E0100; Adobe-Japan1; CID+14984 -7DF2 E0100; Adobe-Japan1; CID+6108 -7DF4 E0100; Adobe-Japan1; CID+13399 -7DF4 E0101; Adobe-Japan1; CID+4037 -7DF4 E0102; Hanyo-Denshi; JA4693 -7DF4 E0103; Hanyo-Denshi; JC9014 -7DF5 E0100; Adobe-Japan1; CID+19672 -7DF6 E0100; Adobe-Japan1; CID+19673 -7DF9 E0100; Adobe-Japan1; CID+14985 -7DFA E0100; Adobe-Japan1; CID+22218 -7DFB E0100; Adobe-Japan1; CID+6107 -7E00 E0100; Adobe-Japan1; CID+22214 -7E01 E0100; Adobe-Japan1; CID+1297 -7E01 E0101; Hanyo-Denshi; JA1779 -7E01 E0101; Moji_Joho; MJ020289 -7E01 E0102; Hanyo-Denshi; FT2015 -7E01 E0102; Moji_Joho; MJ020290 -7E02 E0100; Hanyo-Denshi; IP7E02 -7E02 E0100; Moji_Joho; MJ020291 -7E02 E0101; Hanyo-Denshi; KS309910 -7E02 E0101; Moji_Joho; MJ020292 -7E04 E0100; Adobe-Japan1; CID+3268 -7E05 E0100; Adobe-Japan1; CID+6110 -7E08 E0100; Adobe-Japan1; CID+14986 -7E09 E0100; Adobe-Japan1; CID+6117 -7E09 E0101; Adobe-Japan1; CID+18366 -7E09 E0102; Hanyo-Denshi; JA6954 -7E09 E0103; Hanyo-Denshi; JD8448 -7E0A E0100; Adobe-Japan1; CID+6111 -7E0A E0101; Hanyo-Denshi; JA6948 -7E0A E0101; Moji_Joho; MJ020298 -7E0A E0102; Hanyo-Denshi; FT2422S -7E0A E0102; Moji_Joho; MJ020299 -7E0A E0103; Hanyo-Denshi; JTB850 -7E0A E0103; Moji_Joho; MJ020300 -7E0B E0100; Adobe-Japan1; CID+6118 -7E0B E0101; Hanyo-Denshi; JA6955 -7E0B E0101; Moji_Joho; MJ020302 -7E0B E0102; Hanyo-Denshi; FT2424 -7E0B E0102; Moji_Joho; MJ020301 -7E0C E0100; Hanyo-Denshi; IB0847 -7E0C E0100; Moji_Joho; MJ020303 -7E0C E0101; Hanyo-Denshi; IP7E0C -7E0C E0101; Moji_Joho; MJ020304 -7E10 E0100; Adobe-Japan1; CID+18367 -7E11 E0100; Adobe-Japan1; CID+14987 -7E12 E0100; Adobe-Japan1; CID+6114 -7E15 E0100; Adobe-Japan1; CID+14988 -7E17 E0100; Adobe-Japan1; CID+18368 -7E1B E0100; Adobe-Japan1; CID+3377 -7E1B E0101; Adobe-Japan1; CID+13979 -7E1B E0102; Hanyo-Denshi; JA3991 -7E1B E0102; Moji_Joho; MJ020320 -7E1B E0103; Hanyo-Denshi; JTB849 -7E1B E0103; Moji_Joho; MJ020319 -7E1C E0100; Adobe-Japan1; CID+22219 -7E1D E0100; Adobe-Japan1; CID+18369 -7E1D E0101; Hanyo-Denshi; JB5237 -7E1D E0101; Moji_Joho; MJ020322 -7E1D E0102; Hanyo-Denshi; JTB84C -7E1D E0102; Moji_Joho; MJ020323 -7E1E E0100; Adobe-Japan1; CID+2294 -7E1E E0101; Hanyo-Denshi; JA2842 -7E1E E0102; Hanyo-Denshi; TK01072630 -7E1F E0100; Adobe-Japan1; CID+6116 -7E1F E0101; Hanyo-Denshi; JA6953 -7E1F E0101; Moji_Joho; MJ020326 -7E1F E0102; Hanyo-Denshi; FT2423 -7E1F E0102; Moji_Joho; MJ020327 -7E20 E0100; Adobe-Japan1; CID+14989 -7E21 E0100; Adobe-Japan1; CID+6113 -7E22 E0100; Adobe-Japan1; CID+6119 -7E22 E0101; Adobe-Japan1; CID+14181 -7E22 E0102; Adobe-Japan1; CID+14182 -7E22 E0103; Hanyo-Denshi; JA6956 -7E22 E0103; Moji_Joho; MJ020331 -7E22 E0104; Hanyo-Denshi; JTB84A -7E22 E0104; Moji_Joho; MJ020330 -7E22 E0105; Hanyo-Denshi; FT2425 -7E22 E0105; Moji_Joho; MJ020332 -7E23 E0100; Adobe-Japan1; CID+6112 -7E23 E0101; Hanyo-Denshi; JA6949 -7E23 E0102; Hanyo-Denshi; TK01072490 -7E26 E0100; Adobe-Japan1; CID+2382 -7E27 E0100; Adobe-Japan1; CID+18370 -7E27 E0101; Hanyo-Denshi; JB5239 -7E27 E0101; Moji_Joho; MJ020339 -7E27 E0102; Hanyo-Denshi; KS310770 -7E27 E0102; Moji_Joho; MJ020338 -7E28 E0100; Adobe-Japan1; CID+17045 -7E28 E0101; Hanyo-Denshi; JB5240 -7E28 E0102; Hanyo-Denshi; TK01072620 -7E2B E0100; Adobe-Japan1; CID+3667 -7E2B E0101; Adobe-Japan1; CID+14024 -7E2B E0102; Hanyo-Denshi; JA4305 -7E2B E0102; Moji_Joho; MJ020344 -7E2B E0103; Hanyo-Denshi; JTB853 -7E2B E0103; Moji_Joho; MJ020345 -7E2B E0104; Hanyo-Denshi; TK01072440 -7E2C E0100; Adobe-Japan1; CID+18371 -7E2C E0101; Moji_Joho; MJ020346 -7E2C E0102; Moji_Joho; MJ020347 -7E2D E0100; Adobe-Japan1; CID+22220 -7E2D E0101; Hanyo-Denshi; JB5242 -7E2D E0101; Moji_Joho; MJ020348 -7E2D E0102; Hanyo-Denshi; KS311590 -7E2D E0102; Moji_Joho; MJ020349 -7E2E E0100; Adobe-Japan1; CID+2390 -7E2F E0100; Adobe-Japan1; CID+19674 -7E31 E0100; Adobe-Japan1; CID+6115 -7E32 E0100; Adobe-Japan1; CID+6127 -7E33 E0100; Adobe-Japan1; CID+22221 -7E35 E0100; Adobe-Japan1; CID+6123 -7E35 E0101; Adobe-Japan1; CID+13577 -7E35 E0102; Adobe-Japan1; CID+14184 -7E35 E0103; Hanyo-Denshi; JA6960 -7E35 E0103; Moji_Joho; MJ020358 -7E35 E0104; Hanyo-Denshi; KS311030 -7E35 E0104; Moji_Joho; MJ020357 -7E35 E0105; Moji_Joho; MJ020359 -7E36 E0100; Adobe-Japan1; CID+19675 -7E36 E0101; Moji_Joho; MJ020360 -7E36 E0102; Moji_Joho; MJ020361 -7E37 E0100; Adobe-Japan1; CID+6126 -7E37 E0101; Hanyo-Denshi; JA6963 -7E37 E0101; Moji_Joho; MJ020362 -7E37 E0102; Hanyo-Denshi; KS311560 -7E37 E0102; Moji_Joho; MJ058326 -7E39 E0100; Adobe-Japan1; CID+6124 -7E3A E0100; Adobe-Japan1; CID+6128 -7E3A E0101; Hanyo-Denshi; JA6965 -7E3A E0101; Moji_Joho; MJ020366 -7E3A E0102; Hanyo-Denshi; FT2429 -7E3A E0102; Moji_Joho; MJ020365 -7E3B E0100; Adobe-Japan1; CID+6122 -7E3B E0101; Hanyo-Denshi; JA6959 -7E3B E0101; Moji_Joho; MJ020367 -7E3B E0102; Hanyo-Denshi; FT2428 -7E3B E0102; Moji_Joho; MJ020368 -7E3D E0100; Adobe-Japan1; CID+6096 -7E3D E0101; Hanyo-Denshi; JA6933 -7E3D E0101; Moji_Joho; MJ020370 -7E3D E0102; Hanyo-Denshi; JTB856 -7E3D E0102; Moji_Joho; MJ020371 -7E3E E0100; Adobe-Japan1; CID+2679 -7E3F E0100; Adobe-Japan1; CID+22222 -7E41 E0100; Adobe-Japan1; CID+3423 -7E41 E0101; Adobe-Japan1; CID+13376 -7E41 E0102; Hanyo-Denshi; JA4043 -7E41 E0103; Hanyo-Denshi; JC9019 -7E42 E0100; Hanyo-Denshi; IP7E42 -7E42 E0101; Hanyo-Denshi; TK01072640 -7E43 E0100; Adobe-Japan1; CID+6125 -7E43 E0101; Adobe-Japan1; CID+14185 -7E43 E0102; Hanyo-Denshi; JA6962 -7E43 E0102; Moji_Joho; MJ020380 -7E43 E0103; Hanyo-Denshi; JTB854 -7E43 E0103; Moji_Joho; MJ020379 -7E44 E0100; Adobe-Japan1; CID+19676 -7E44 E0101; Moji_Joho; MJ020381 -7E44 E0102; Moji_Joho; MJ020382 -7E45 E0100; Adobe-Japan1; CID+18372 -7E45 E0101; Hanyo-Denshi; JB5248 -7E45 E0101; Moji_Joho; MJ020383 -7E45 E0102; Hanyo-Denshi; KS313000 -7E45 E0102; Moji_Joho; MJ020384 -7E46 E0100; Adobe-Japan1; CID+6120 -7E46 E0101; Hanyo-Denshi; JA6957 -7E46 E0101; Moji_Joho; MJ020385 -7E46 E0102; Hanyo-Denshi; FT2426 -7E46 E0102; Moji_Joho; MJ020386 -7E47 E0100; Adobe-Japan1; CID+14990 -7E48 E0100; Adobe-Japan1; CID+14183 -7E4A E0100; Adobe-Japan1; CID+2723 -7E4A E0101; Hanyo-Denshi; JA3301 -7E4A E0102; Hanyo-Denshi; TK01072760 -7E4B E0100; Adobe-Japan1; CID+1832 -7E4D E0100; Adobe-Japan1; CID+2357 -7E4E E0100; Adobe-Japan1; CID+22223 -7E50 E0100; Adobe-Japan1; CID+22224 -7E52 E0100; Adobe-Japan1; CID+8596 -7E52 E0101; Hanyo-Denshi; JB5252 -7E52 E0101; Moji_Joho; MJ020398 -7E52 E0102; Hanyo-Denshi; JTB855 -7E52 E0102; Moji_Joho; MJ020399 -7E54 E0100; Adobe-Japan1; CID+2539 -7E54 E0101; Hanyo-Denshi; JA3105 -7E54 E0101; Moji_Joho; MJ020401 -7E54 E0102; Hanyo-Denshi; JTB85F -7E54 E0102; Moji_Joho; MJ020402 -7E55 E0100; Adobe-Japan1; CID+2744 -7E56 E0100; Adobe-Japan1; CID+6131 -7E58 E0100; Adobe-Japan1; CID+22225 -7E59 E0100; Adobe-Japan1; CID+6133 -7E5A E0100; Adobe-Japan1; CID+6134 -7E5D E0100; Adobe-Japan1; CID+6130 -7E5E E0100; Adobe-Japan1; CID+6132 -7E5F E0100; Adobe-Japan1; CID+22226 -7E61 E0100; Adobe-Japan1; CID+7697 -7E62 E0100; Adobe-Japan1; CID+14991 -7E65 E0100; Adobe-Japan1; CID+22227 -7E66 E0100; Adobe-Japan1; CID+6121 -7E67 E0100; Adobe-Japan1; CID+6129 -7E68 E0100; Hanyo-Denshi; IB0850 -7E68 E0100; Moji_Joho; MJ020423 -7E68 E0101; Hanyo-Denshi; IP7E68 -7E68 E0101; Moji_Joho; MJ020424 -7E69 E0100; Adobe-Japan1; CID+6137 -7E69 E0101; Hanyo-Denshi; JA6974 -7E69 E0101; Moji_Joho; MJ020426 -7E69 E0102; Hanyo-Denshi; JTB866 -7E69 E0102; Moji_Joho; MJ020425 -7E6A E0100; Adobe-Japan1; CID+6136 -7E6A E0101; Hanyo-Denshi; JA6973 -7E6A E0101; Moji_Joho; MJ020427 -7E6A E0102; Hanyo-Denshi; JTB860 -7E6A E0102; Moji_Joho; MJ020428 -7E6B E0100; Adobe-Japan1; CID+7671 -7E6B E0101; Hanyo-Denshi; JB5258 -7E6B E0102; Hanyo-Denshi; JTB85B -7E6B E0102; Moji_Joho; MJ058327 -7E6B E0103; Moji_Joho; MJ020429 -7E6D E0100; Adobe-Japan1; CID+3752 -7E6D E0101; Adobe-Japan1; CID+14049 -7E6D E0102; Hanyo-Denshi; JA4390 -7E6D E0102; Moji_Joho; MJ020431 -7E6D E0103; Hanyo-Denshi; KS312340 -7E6D E0103; Moji_Joho; MJ020432 -7E6D E0104; Hanyo-Denshi; JTBA85 -7E6D E0104; Moji_Joho; MJ020433 -7E6E E0100; Adobe-Japan1; CID+14992 -7E6F E0100; Adobe-Japan1; CID+19677 -7E70 E0100; Adobe-Japan1; CID+1793 -7E73 E0100; Adobe-Japan1; CID+14993 -7E75 E0100; Adobe-Japan1; CID+18373 -7E76 E0100; Hanyo-Denshi; IP7E76 -7E76 E0100; Moji_Joho; MJ020442 -7E76 E0101; Hanyo-Denshi; KS312830 -7E76 E0101; Moji_Joho; MJ020443 -7E78 E0100; Adobe-Japan1; CID+19678 -7E78 E0101; Hanyo-Denshi; JB5262 -7E78 E0101; Moji_Joho; MJ020446 -7E78 E0102; Hanyo-Denshi; IB0849 -7E78 E0102; Moji_Joho; MJ020445 -7E79 E0100; Adobe-Japan1; CID+6135 -7E79 E0101; Hanyo-Denshi; JA6972 -7E79 E0101; Moji_Joho; MJ020447 -7E79 E0102; Hanyo-Denshi; JTB865 -7E79 E0102; Moji_Joho; MJ020448 -7E7B E0100; Adobe-Japan1; CID+6139 -7E7C E0100; Adobe-Japan1; CID+6138 -7E7C E0101; Hanyo-Denshi; JA6975 -7E7C E0101; Moji_Joho; MJ020451 -7E7C E0102; Hanyo-Denshi; KS313170 -7E7C E0102; Moji_Joho; MJ020452 -7E7C E0103; Hanyo-Denshi; TK01072970 -7E7D E0100; Adobe-Japan1; CID+6142 -7E7D E0101; Hanyo-Denshi; JA6979 -7E7D E0101; Moji_Joho; MJ020453 -7E7D E0102; Hanyo-Denshi; FT2431S -7E7D E0102; Moji_Joho; MJ020455 -7E7D E0103; Moji_Joho; MJ020454 -7E7E E0100; Adobe-Japan1; CID+18374 -7E7E E0101; Hanyo-Denshi; JB5263 -7E7E E0101; Moji_Joho; MJ020457 -7E7E E0102; Hanyo-Denshi; IB0851 -7E7E E0102; Moji_Joho; MJ020456 -7E7F E0100; Adobe-Japan1; CID+6144 -7E7F E0101; Hanyo-Denshi; JA6981 -7E7F E0101; Moji_Joho; MJ020458 -7E7F E0102; Hanyo-Denshi; JTB86C -7E7F E0102; Moji_Joho; MJ060057 -7E81 E0100; Adobe-Japan1; CID+19679 -7E82 E0100; Adobe-Japan1; CID+2186 -7E83 E0100; Adobe-Japan1; CID+6140 -7E86 E0100; Adobe-Japan1; CID+18375 -7E86 E0101; Hanyo-Denshi; JB5265 -7E86 E0102; Hanyo-Denshi; TK01072990 -7E87 E0100; Adobe-Japan1; CID+18376 -7E88 E0100; Adobe-Japan1; CID+6145 -7E89 E0100; Adobe-Japan1; CID+6146 -7E8A E0100; Adobe-Japan1; CID+8359 -7E8A E0101; Hanyo-Denshi; JB5267 -7E8A E0101; Moji_Joho; MJ020469 -7E8A E0102; Hanyo-Denshi; JTB867 -7E8A E0102; Moji_Joho; MJ020470 -7E8C E0100; Adobe-Japan1; CID+6147 -7E8C E0101; Adobe-Japan1; CID+14186 -7E8D E0100; Adobe-Japan1; CID+14994 -7E8E E0100; Adobe-Japan1; CID+6153 -7E8F E0100; Adobe-Japan1; CID+3125 -7E90 E0100; Adobe-Japan1; CID+6149 -7E91 E0100; Adobe-Japan1; CID+14995 -7E92 E0100; Adobe-Japan1; CID+6148 -7E92 E0101; Hanyo-Denshi; JA6985 -7E92 E0101; Moji_Joho; MJ020478 -7E92 E0102; Hanyo-Denshi; JTB86D -7E92 E0102; Moji_Joho; MJ020480 -7E92 E0103; Hanyo-Denshi; KS313930 -7E92 E0103; Moji_Joho; MJ020479 -7E93 E0100; Adobe-Japan1; CID+6150 -7E94 E0100; Adobe-Japan1; CID+6151 -7E95 E0100; Adobe-Japan1; CID+22228 -7E96 E0100; Adobe-Japan1; CID+6152 -7E98 E0100; Adobe-Japan1; CID+14996 -7E9A E0100; Adobe-Japan1; CID+18378 -7E9B E0100; Adobe-Japan1; CID+6154 -7E9C E0100; Adobe-Japan1; CID+6155 -7E9D E0100; Adobe-Japan1; CID+22229 -7E9E E0100; Adobe-Japan1; CID+22230 -7EA2 E0100; Hanyo-Denshi; TK01071150 -7EA2 E0101; Hanyo-Denshi; TK01071200 -7F36 E0100; Adobe-Japan1; CID+1544 -7F38 E0100; Adobe-Japan1; CID+6156 -7F3A E0100; Adobe-Japan1; CID+6157 -7F3A E0101; Hanyo-Denshi; JA6994 -7F3A E0101; Moji_Joho; MJ020502 -7F3A E0102; Hanyo-Denshi; KS314460 -7F3A E0102; Moji_Joho; MJ058335 -7F3B E0100; Adobe-Japan1; CID+18381 -7F3C E0100; Adobe-Japan1; CID+18380 -7F3C E0101; Moji_Joho; MJ020504 -7F3C E0102; Moji_Joho; MJ020505 -7F3D E0100; Adobe-Japan1; CID+19680 -7F3E E0100; Adobe-Japan1; CID+18382 -7F3E E0101; Adobe-Japan1; CID+20191 -7F3E E0102; Hanyo-Denshi; JB5278 -7F3E E0102; Moji_Joho; MJ020507 -7F3E E0103; Hanyo-Denshi; KS314640 -7F3E E0103; Moji_Joho; MJ020508 -7F3F E0100; Adobe-Japan1; CID+22231 -7F43 E0100; Adobe-Japan1; CID+18383 -7F44 E0100; Adobe-Japan1; CID+14997 -7F45 E0100; Adobe-Japan1; CID+6158 -7F47 E0100; Adobe-Japan1; CID+8597 -7F47 E0101; Hanyo-Denshi; JB5282 -7F47 E0102; Hanyo-Denshi; TK01023670 -7F47 E0103; Hanyo-Denshi; TK01073130 -7F48 E0100; Hanyo-Denshi; IP7F48 -7F48 E0100; Moji_Joho; MJ020517 -7F48 E0101; Hanyo-Denshi; KS314890 -7F48 E0101; Moji_Joho; MJ020518 -7F4C E0100; Adobe-Japan1; CID+6159 -7F4D E0100; Adobe-Japan1; CID+6160 -7F4D E0101; Hanyo-Denshi; JA7003 -7F4D E0102; Hanyo-Denshi; TK01061000 -7F4E E0100; Adobe-Japan1; CID+6161 -7F4F E0100; Adobe-Japan1; CID+14998 -7F50 E0100; Adobe-Japan1; CID+6162 -7F50 E0101; Adobe-Japan1; CID+14187 -7F50 E0102; Hanyo-Denshi; JA7005 -7F50 E0102; Moji_Joho; MJ020525 -7F50 E0103; Hanyo-Denshi; JTB871 -7F50 E0103; Moji_Joho; MJ020526 -7F50 E0104; Hanyo-Denshi; TK01073160 -7F51 E0100; Adobe-Japan1; CID+6163 -7F52 E0100; Adobe-Japan1; CID+14999 -7F53 E0100; Adobe-Japan1; CID+15000 -7F54 E0100; Adobe-Japan1; CID+6165 -7F54 E0101; Hanyo-Denshi; JA7008 -7F54 E0101; Moji_Joho; MJ020530 -7F54 E0102; Hanyo-Denshi; KS315390 -7F54 E0102; Moji_Joho; MJ020531 -7F54 E0103; Hanyo-Denshi; JTB873 -7F54 E0103; Moji_Joho; MJ020532 -7F55 E0100; Adobe-Japan1; CID+6164 -7F58 E0100; Adobe-Japan1; CID+6166 -7F59 E0100; Hanyo-Denshi; IP7F59 -7F59 E0101; Hanyo-Denshi; TK01073190 -7F59 E0102; Hanyo-Denshi; TK01073210 -7F5B E0100; Adobe-Japan1; CID+19681 -7F5B E0101; Hanyo-Denshi; JB5286 -7F5B E0101; Moji_Joho; MJ020540 -7F5B E0102; Hanyo-Denshi; KS315770 -7F5B E0102; Moji_Joho; MJ020539 -7F5C E0100; Adobe-Japan1; CID+22232 -7F5D E0100; Adobe-Japan1; CID+19682 -7F5F E0100; Adobe-Japan1; CID+6167 -7F60 E0100; Adobe-Japan1; CID+6168 -7F61 E0100; Adobe-Japan1; CID+15001 -7F61 E0101; Adobe-Japan1; CID+15400 -7F63 E0100; Adobe-Japan1; CID+18387 -7F64 E0100; Adobe-Japan1; CID+18388 -7F65 E0100; Adobe-Japan1; CID+19683 -7F66 E0100; Adobe-Japan1; CID+22233 -7F67 E0100; Adobe-Japan1; CID+6171 -7F68 E0100; Adobe-Japan1; CID+6169 -7F69 E0100; Adobe-Japan1; CID+6170 -7F6A E0100; Adobe-Japan1; CID+2129 -7F6A E0101; Adobe-Japan1; CID+13449 -7F6A E0102; Moji_Joho; MJ020555 -7F6A E0103; Moji_Joho; MJ020556 -7F6B E0100; Adobe-Japan1; CID+1833 -7F6D E0100; Adobe-Japan1; CID+18389 -7F6E E0100; Adobe-Japan1; CID+2964 -7F6E E0101; Adobe-Japan1; CID+13920 -7F70 E0100; Adobe-Japan1; CID+3399 -7F71 E0100; Adobe-Japan1; CID+19684 -7F72 E0100; Adobe-Japan1; CID+13353 -7F72 E0101; Adobe-Japan1; CID+2426 -7F72 E0102; Hanyo-Denshi; JA2980 -7F72 E0103; Hanyo-Denshi; JC9026 -7F75 E0100; Adobe-Japan1; CID+3331 -7F76 E0100; Hanyo-Denshi; IP7F76 -7F76 E0100; Moji_Joho; MJ020567 -7F76 E0101; Hanyo-Denshi; KS316620 -7F76 E0101; Moji_Joho; MJ020568 -7F77 E0100; Adobe-Japan1; CID+3457 -7F78 E0100; Adobe-Japan1; CID+6172 -7F79 E0100; Adobe-Japan1; CID+4918 -7F7A E0100; Hanyo-Denshi; IP7F7A -7F7A E0100; Moji_Joho; MJ020572 -7F7A E0101; Hanyo-Denshi; KS317180 -7F7A E0101; Moji_Joho; MJ020573 -7F7D E0100; Adobe-Japan1; CID+18390 -7F7E E0100; Adobe-Japan1; CID+18391 -7F7F E0100; Adobe-Japan1; CID+19685 -7F7F E0101; Hanyo-Denshi; JB5304 -7F7F E0101; Moji_Joho; MJ020578 -7F7F E0102; Hanyo-Denshi; KS316990 -7F7F E0102; Moji_Joho; MJ020579 -7F80 E0100; Adobe-Japan1; CID+19686 -7F80 E0101; Adobe-Japan1; CID+22234 -7F82 E0100; Adobe-Japan1; CID+6173 -7F83 E0100; Adobe-Japan1; CID+6175 -7F83 E0101; Hanyo-Denshi; JA7018 -7F83 E0101; Moji_Joho; MJ020582 -7F83 E0102; Hanyo-Denshi; KS317160 -7F83 E0102; Moji_Joho; MJ020583 -7F85 E0100; Adobe-Japan1; CID+3919 -7F86 E0100; Adobe-Japan1; CID+6174 -7F87 E0100; Adobe-Japan1; CID+6177 -7F88 E0100; Adobe-Japan1; CID+6176 -7F8A E0100; Adobe-Japan1; CID+14078 -7F8A E0101; Adobe-Japan1; CID+3901 -7F8B E0100; Adobe-Japan1; CID+19687 -7F8C E0100; Adobe-Japan1; CID+6178 -7F8D E0100; Adobe-Japan1; CID+22235 -7F8E E0100; Adobe-Japan1; CID+3474 -7F8F E0100; Adobe-Japan1; CID+22236 -7F8F E0101; Hanyo-Denshi; JB5308 -7F8F E0101; Moji_Joho; MJ020595 -7F8F E0102; Hanyo-Denshi; IB2719 -7F8F E0102; Moji_Joho; MJ020596 -7F90 E0100; Adobe-Japan1; CID+18392 -7F90 E0101; Hanyo-Denshi; JB5309 -7F90 E0102; Hanyo-Denshi; TK01076940 -7F91 E0100; Adobe-Japan1; CID+15002 -7F94 E0100; Adobe-Japan1; CID+6179 -7F94 E0101; Hanyo-Denshi; JA7022 -7F94 E0102; Hanyo-Denshi; TK01054510 -7F95 E0100; Hanyo-Denshi; KS318130 -7F95 E0100; Moji_Joho; MJ020604 -7F95 E0101; Hanyo-Denshi; KS318240 -7F95 E0101; Moji_Joho; MJ020605 -7F95 E0102; Hanyo-Denshi; KS318330 -7F95 E0102; Moji_Joho; MJ020606 -7F96 E0100; Adobe-Japan1; CID+18395 -7F97 E0100; Adobe-Japan1; CID+17046 -7F9A E0100; Adobe-Japan1; CID+6182 -7F9C E0100; Adobe-Japan1; CID+18396 -7F9D E0100; Adobe-Japan1; CID+6181 -7F9E E0100; Adobe-Japan1; CID+6180 -7F9E E0101; Hanyo-Denshi; JA7023 -7F9E E0101; Moji_Joho; MJ020616 -7F9E E0102; Hanyo-Denshi; KS317830 -7F9E E0102; Moji_Joho; MJ020615 -7FA1 E0100; Adobe-Japan1; CID+8598 -7FA1 E0101; Adobe-Japan1; CID+13885 -7FA1 E0102; Hanyo-Denshi; JB5314 -7FA1 E0102; Moji_Joho; MJ020618 -7FA1 E0103; Hanyo-Denshi; JTB87E -7FA1 E0103; Moji_Joho; MJ020619 -7FA1 E0104; Hanyo-Denshi; JTB87F -7FA1 E0104; Moji_Joho; MJ020620 -7FA2 E0100; Adobe-Japan1; CID+19688 -7FA3 E0100; Adobe-Japan1; CID+6183 -7FA4 E0100; Adobe-Japan1; CID+1800 -7FA6 E0100; Adobe-Japan1; CID+22237 -7FA8 E0100; Adobe-Japan1; CID+2724 -7FA9 E0100; Adobe-Japan1; CID+1627 -7FAA E0100; Adobe-Japan1; CID+22238 -7FAD E0100; Adobe-Japan1; CID+18397 -7FAD E0101; Hanyo-Denshi; JB5318 -7FAD E0101; Moji_Joho; MJ020632 -7FAD E0102; Hanyo-Denshi; JTB884 -7FAD E0102; Moji_Joho; MJ020633 -7FAE E0100; Adobe-Japan1; CID+6187 -7FAE E0101; Adobe-Japan1; CID+13578 -7FAE E0102; Hanyo-Denshi; JA7030 -7FAE E0102; Moji_Joho; MJ020634 -7FAE E0103; Hanyo-Denshi; JTB883 -7FAE E0103; Moji_Joho; MJ020635 -7FAF E0100; Adobe-Japan1; CID+6184 -7FAF E0101; Hanyo-Denshi; JA7027 -7FAF E0101; Moji_Joho; MJ020636 -7FAF E0102; Hanyo-Denshi; JTB885 -7FAF E0102; Moji_Joho; MJ020638 -7FAF E0103; Hanyo-Denshi; FT2433 -7FAF E0103; Moji_Joho; MJ020637 -7FB2 E0100; Adobe-Japan1; CID+6185 -7FB4 E0100; Adobe-Japan1; CID+22239 -7FB5 E0100; Hanyo-Denshi; IP7FB5 -7FB5 E0100; Moji_Joho; MJ020643 -7FB5 E0101; Hanyo-Denshi; KS319290 -7FB5 E0101; Moji_Joho; MJ020644 -7FB6 E0100; Adobe-Japan1; CID+6188 -7FB8 E0100; Adobe-Japan1; CID+6189 -7FB8 E0101; Hanyo-Denshi; JA7032 -7FB8 E0101; Moji_Joho; MJ020647 -7FB8 E0102; Hanyo-Denshi; FT2434 -7FB8 E0102; Moji_Joho; MJ020648 -7FB9 E0100; Adobe-Japan1; CID+6186 -7FBB E0100; Hanyo-Denshi; IP7FBB -7FBB E0100; Moji_Joho; MJ020652 -7FBB E0101; Hanyo-Denshi; KS319370 -7FBB E0101; Moji_Joho; MJ020651 -7FBC E0100; Adobe-Japan1; CID+22240 -7FBD E0100; Adobe-Japan1; CID+8599 -7FBD E0101; Adobe-Japan1; CID+1227 -7FBD E0102; Hanyo-Denshi; JA1709 -7FBD E0102; Moji_Joho; MJ020654 -7FBD E0103; Hanyo-Denshi; IB2730 -7FBD E0104; Hanyo-Denshi; KS319620 -7FBD E0104; Moji_Joho; MJ058352 -7FBF E0100; Adobe-Japan1; CID+15003 -7FC0 E0100; Adobe-Japan1; CID+22241 -7FC0 E0101; Hanyo-Denshi; JB5322 -7FC0 E0102; Hanyo-Denshi; TK01073830 -7FC1 E0100; Adobe-Japan1; CID+1319 -7FC1 E0101; Adobe-Japan1; CID+13418 -7FC1 E0102; Adobe-Japan1; CID+13662 -7FC1 E0103; Hanyo-Denshi; JA1807 -7FC1 E0103; Moji_Joho; MJ020660 -7FC1 E0104; Hanyo-Denshi; JTB888S -7FC1 E0104; Moji_Joho; MJ020659 -7FC1 E0105; Hanyo-Denshi; JTB889 -7FC1 E0105; Moji_Joho; MJ020661 -7FC3 E0100; Adobe-Japan1; CID+18399 -7FC5 E0100; Adobe-Japan1; CID+6191 -7FC5 E0101; Adobe-Japan1; CID+14191 -7FC5 E0102; Hanyo-Denshi; JA7034 -7FC5 E0102; Moji_Joho; MJ020665 -7FC5 E0103; Hanyo-Denshi; FT2435 -7FC5 E0103; Moji_Joho; MJ020666 -7FC6 E0100; Adobe-Japan1; CID+6192 -7FC6 E0101; Adobe-Japan1; CID+14192 -7FC6 E0102; Hanyo-Denshi; JA7035 -7FC6 E0102; Moji_Joho; MJ020667 -7FC6 E0103; Hanyo-Denshi; FT2436 -7FC6 E0103; Moji_Joho; MJ020668 -7FC8 E0100; Adobe-Japan1; CID+22242 -7FCA E0100; Adobe-Japan1; CID+6193 -7FCA E0101; Hanyo-Denshi; JA7036 -7FCA E0101; Moji_Joho; MJ020672 -7FCA E0102; Hanyo-Denshi; FT2437 -7FCA E0102; Moji_Joho; MJ020673 -7FCC E0100; Adobe-Japan1; CID+3916 -7FCC E0101; Adobe-Japan1; CID+14081 -7FCC E0102; Hanyo-Denshi; JA4566 -7FCC E0102; Moji_Joho; MJ020676 -7FCC E0103; Hanyo-Denshi; JTB88D -7FCC E0103; Moji_Joho; MJ020675 -7FCE E0100; Adobe-Japan1; CID+15004 -7FCF E0100; Adobe-Japan1; CID+18400 -7FCF E0101; Hanyo-Denshi; JB5326 -7FCF E0101; Moji_Joho; MJ020679 -7FCF E0102; Hanyo-Denshi; KS320330 -7FCF E0102; Moji_Joho; MJ058355 -7FD2 E0100; Adobe-Japan1; CID+2358 -7FD2 E0101; Adobe-Japan1; CID+13817 -7FD2 E0102; Hanyo-Denshi; JA2912 -7FD2 E0102; Moji_Joho; MJ020683 -7FD2 E0103; Hanyo-Denshi; JTB88E -7FD2 E0103; Moji_Joho; MJ020682 -7FD4 E0100; Adobe-Japan1; CID+6195 -7FD4 E0101; Adobe-Japan1; CID+7854 -7FD4 E0102; Hanyo-Denshi; JA7038 -7FD4 E0102; Moji_Joho; MJ020686 -7FD4 E0103; Hanyo-Denshi; FT1979 -7FD4 E0103; Moji_Joho; MJ020685 -7FD5 E0100; Adobe-Japan1; CID+6194 -7FD5 E0101; Hanyo-Denshi; JA7037 -7FD5 E0101; Moji_Joho; MJ020687 -7FD5 E0102; Hanyo-Denshi; FT2438 -7FD5 E0102; Moji_Joho; MJ020688 -7FDB E0100; Adobe-Japan1; CID+17047 -7FDF E0100; Adobe-Japan1; CID+15005 -7FDF E0101; Hanyo-Denshi; JB5328 -7FDF E0101; Moji_Joho; MJ020695 -7FDF E0102; Hanyo-Denshi; KS321030 -7FDF E0102; Moji_Joho; MJ058358 -7FDF E0103; Hanyo-Denshi; TK01073950 -7FE0 E0100; Adobe-Japan1; CID+2607 -7FE0 E0101; Adobe-Japan1; CID+7712 -7FE0 E0102; Hanyo-Denshi; JA3173 -7FE0 E0102; Moji_Joho; MJ020697 -7FE0 E0103; Hanyo-Denshi; KS321020S -7FE0 E0103; Moji_Joho; MJ020698 -7FE0 E0104; Hanyo-Denshi; FT1833 -7FE0 E0104; Moji_Joho; MJ020696 -7FE1 E0100; Adobe-Japan1; CID+6196 -7FE1 E0101; Adobe-Japan1; CID+13579 -7FE1 E0102; Adobe-Japan1; CID+20192 -7FE1 E0103; Hanyo-Denshi; JA7039 -7FE1 E0104; Hanyo-Denshi; FT2439SS -7FE1 E0104; Moji_Joho; MJ020701 -7FE1 E0105; Moji_Joho; MJ020699 -7FE1 E0106; Moji_Joho; MJ020700 -7FE3 E0100; Adobe-Japan1; CID+18401 -7FE5 E0100; Adobe-Japan1; CID+15006 -7FE5 E0101; Hanyo-Denshi; JB5330 -7FE5 E0102; Hanyo-Denshi; TK01073940 -7FE6 E0100; Adobe-Japan1; CID+6197 -7FE6 E0101; Hanyo-Denshi; JA7040 -7FE6 E0101; Moji_Joho; MJ020707 -7FE6 E0102; Hanyo-Denshi; FT2440 -7FE6 E0102; Moji_Joho; MJ020709 -7FE6 E0103; Hanyo-Denshi; JTB898 -7FE6 E0103; Moji_Joho; MJ020708 -7FE8 E0100; Adobe-Japan1; CID+22243 -7FE9 E0100; Adobe-Japan1; CID+6198 -7FE9 E0101; Adobe-Japan1; CID+7998 -7FE9 E0102; Adobe-Japan1; CID+14193 -7FE9 E0103; Hanyo-Denshi; JA7041 -7FE9 E0103; Moji_Joho; MJ020713 -7FE9 E0104; Hanyo-Denshi; FT2441 -7FE9 E0104; Moji_Joho; MJ020714 -7FE9 E0105; Hanyo-Denshi; JTB89C -7FE9 E0105; Moji_Joho; MJ020712 -7FEB E0100; Adobe-Japan1; CID+1569 -7FEB E0101; Adobe-Japan1; CID+7657 -7FEB E0102; Hanyo-Denshi; JA2069 -7FEB E0102; Moji_Joho; MJ020717 -7FEB E0103; Hanyo-Denshi; FT1774 -7FEB E0103; Moji_Joho; MJ020716 -7FEB E0104; Moji_Joho; MJ020718 -7FEC E0100; Adobe-Japan1; CID+15007 -7FEE E0100; Adobe-Japan1; CID+15008 -7FEF E0100; Adobe-Japan1; CID+15009 -7FF0 E0100; Adobe-Japan1; CID+1545 -7FF0 E0101; Adobe-Japan1; CID+7656 -7FF0 E0102; Hanyo-Denshi; JA2045 -7FF0 E0102; Moji_Joho; MJ020724 -7FF0 E0103; Hanyo-Denshi; FT1773 -7FF0 E0103; Moji_Joho; MJ020723 -7FF0 E0104; Hanyo-Denshi; JTB8A2 -7FF0 E0104; Moji_Joho; MJ020725 -7FF0 E0105; Hanyo-Denshi; TK01074020 -7FF0 E0106; Hanyo-Denshi; TK01074040 -7FF2 E0100; Adobe-Japan1; CID+18402 -7FF3 E0100; Adobe-Japan1; CID+6199 -7FF3 E0101; Hanyo-Denshi; JA7042 -7FF3 E0101; Moji_Joho; MJ020730 -7FF3 E0102; Hanyo-Denshi; FT2442 -7FF3 E0102; Moji_Joho; MJ020731 -7FF9 E0100; Adobe-Japan1; CID+6200 -7FF9 E0101; Hanyo-Denshi; JA7043 -7FF9 E0101; Moji_Joho; MJ020736 -7FF9 E0102; Hanyo-Denshi; FT2443 -7FF9 E0102; Moji_Joho; MJ020737 -7FFA E0100; Adobe-Japan1; CID+15010 -7FFB E0100; Adobe-Japan1; CID+3723 -7FFB E0101; Adobe-Japan1; CID+14040 -7FFB E0102; Hanyo-Denshi; JA4361 -7FFB E0102; Moji_Joho; MJ020740 -7FFB E0103; Hanyo-Denshi; KS321850 -7FFB E0103; Moji_Joho; MJ020739 -7FFC E0100; Adobe-Japan1; CID+3917 -7FFC E0101; Adobe-Japan1; CID+13512 -7FFC E0102; Adobe-Japan1; CID+14082 -7FFC E0103; Hanyo-Denshi; JA4567 -7FFC E0103; Moji_Joho; MJ020741 -7FFC E0104; Hanyo-Denshi; KS321890 -7FFC E0104; Moji_Joho; MJ020743 -7FFC E0105; Hanyo-Denshi; JTB89F -7FFC E0105; Moji_Joho; MJ020742 -7FFC E0106; Moji_Joho; MJ020744 -7FFD E0100; Adobe-Japan1; CID+19689 -7FFE E0100; Adobe-Japan1; CID+19690 -7FFE E0101; Hanyo-Denshi; JB5338 -7FFE E0101; Moji_Joho; MJ020746 -7FFE E0102; Hanyo-Denshi; KS321980 -7FFE E0102; Moji_Joho; MJ020747 -7FFF E0100; Adobe-Japan1; CID+19691 -8000 E0100; Adobe-Japan1; CID+3902 -8000 E0101; Adobe-Japan1; CID+7806 -8000 E0102; Hanyo-Denshi; JA4552 -8000 E0102; Moji_Joho; MJ020750 -8000 E0103; Hanyo-Denshi; FT1934 -8000 E0103; Moji_Joho; MJ020749 -8001 E0100; Adobe-Japan1; CID+4061 -8002 E0100; Adobe-Japan1; CID+14099 -8003 E0100; Adobe-Japan1; CID+2015 -8003 E0101; Adobe-Japan1; CID+13445 -8003 E0102; Hanyo-Denshi; JA2545 -8003 E0102; Moji_Joho; MJ020753 -8003 E0103; Hanyo-Denshi; FT1628 -8003 E0103; Moji_Joho; MJ020754 -8004 E0100; Adobe-Japan1; CID+6203 -8005 E0100; Adobe-Japan1; CID+2304 -8005 E0101; Adobe-Japan1; CID+13349 -8005 E0102; Hanyo-Denshi; JA2852 -8005 E0103; Hanyo-Denshi; JC9036 -8005 E0104; Hanyo-Denshi; TK01074120 -8006 E0100; Adobe-Japan1; CID+6202 -8007 E0100; Adobe-Japan1; CID+19692 -8008 E0100; Adobe-Japan1; CID+18404 -800A E0100; Adobe-Japan1; CID+18403 -800B E0100; Adobe-Japan1; CID+6204 -800C E0100; Adobe-Japan1; CID+2261 -800D E0100; Adobe-Japan1; CID+19693 -800E E0100; Adobe-Japan1; CID+15011 -800F E0100; Adobe-Japan1; CID+22244 -8010 E0100; Adobe-Japan1; CID+2865 -8011 E0100; Adobe-Japan1; CID+15012 -8012 E0100; Adobe-Japan1; CID+6205 -8012 E0101; Adobe-Japan1; CID+20193 -8012 E0102; Hanyo-Denshi; JA7048 -8012 E0102; Moji_Joho; MJ020769 -8012 E0103; Hanyo-Denshi; FT2444 -8012 E0103; Moji_Joho; MJ020768 -8013 E0100; Adobe-Japan1; CID+22245 -8014 E0100; Adobe-Japan1; CID+15013 -8015 E0100; Adobe-Japan1; CID+2014 -8015 E0101; Adobe-Japan1; CID+13770 -8015 E0102; Hanyo-Denshi; JA2544 -8015 E0102; Moji_Joho; MJ020773 -8015 E0103; Hanyo-Denshi; JTB8AA -8015 E0103; Moji_Joho; MJ020772 -8016 E0100; Adobe-Japan1; CID+18405 -8016 E0101; Hanyo-Denshi; JB5349 -8016 E0102; Hanyo-Denshi; TK01074260 -8017 E0100; Adobe-Japan1; CID+3811 -8017 E0101; Adobe-Japan1; CID+14058 -8017 E0102; Hanyo-Denshi; JA4455 -8017 E0102; Moji_Joho; MJ020777 -8017 E0103; Hanyo-Denshi; KS322830 -8017 E0103; Moji_Joho; MJ020776 -8018 E0100; Adobe-Japan1; CID+6206 -8018 E0101; Hanyo-Denshi; JA7049 -8018 E0101; Moji_Joho; MJ020778 -8018 E0102; Hanyo-Denshi; FT2445S -8018 E0102; Moji_Joho; MJ020779 -8019 E0100; Adobe-Japan1; CID+6207 -8019 E0101; Hanyo-Denshi; JA7050 -8019 E0101; Moji_Joho; MJ020780 -8019 E0102; Hanyo-Denshi; FT2446 -8019 E0102; Moji_Joho; MJ020781 -801C E0100; Adobe-Japan1; CID+6208 -801C E0101; Hanyo-Denshi; JA7051 -801C E0101; Moji_Joho; MJ020784 -801C E0102; Hanyo-Denshi; JTB8AD -801C E0102; Moji_Joho; MJ020785 -801C E0103; Hanyo-Denshi; FT2447 -801C E0103; Moji_Joho; MJ020786 -801D E0100; Adobe-Japan1; CID+22246 -801E E0100; Adobe-Japan1; CID+19694 -801F E0100; Adobe-Japan1; CID+22247 -8020 E0100; Adobe-Japan1; CID+22248 -8021 E0100; Adobe-Japan1; CID+6209 -8021 E0101; Hanyo-Denshi; JA7052 -8021 E0101; Moji_Joho; MJ020791 -8021 E0102; Hanyo-Denshi; FT2448 -8021 E0102; Moji_Joho; MJ020792 -8024 E0100; Adobe-Japan1; CID+15014 -8026 E0100; Adobe-Japan1; CID+15015 -8028 E0100; Adobe-Japan1; CID+6210 -8028 E0101; Hanyo-Denshi; JA7053 -8028 E0101; Moji_Joho; MJ020796 -8028 E0102; Hanyo-Denshi; FT2449 -8028 E0102; Moji_Joho; MJ020798 -8028 E0103; Hanyo-Denshi; JTB8B1 -8028 E0103; Moji_Joho; MJ020797 -8029 E0100; Hanyo-Denshi; IP8029 -8029 E0101; Hanyo-Denshi; TK01074380 -8029 E0102; Hanyo-Denshi; TK01074390 -8029 E0103; Hanyo-Denshi; TK01074400 -8029 E0104; Hanyo-Denshi; TK01074410 -802C E0100; Adobe-Japan1; CID+18406 -802E E0100; Adobe-Japan1; CID+22249 -8030 E0100; Adobe-Japan1; CID+18407 -8030 E0101; Hanyo-Denshi; JB5358 -8030 E0102; Hanyo-Denshi; TK01074430 -8033 E0100; Adobe-Japan1; CID+2262 -8034 E0100; Adobe-Japan1; CID+22250 -8035 E0100; Adobe-Japan1; CID+17048 -8036 E0100; Adobe-Japan1; CID+3833 -8036 E0101; Adobe-Japan1; CID+13511 -8036 E0102; Moji_Joho; MJ020816 -8036 E0103; Moji_Joho; MJ020817 -8037 E0100; Adobe-Japan1; CID+17049 -8037 E0101; Hanyo-Denshi; JB5361 -8037 E0101; Moji_Joho; MJ020818 -8037 E0102; Hanyo-Denshi; KS323860 -8037 E0102; Moji_Joho; MJ020819 -8039 E0100; Adobe-Japan1; CID+19695 -803A E0100; Adobe-Japan1; CID+15016 -803B E0100; Adobe-Japan1; CID+6212 -803C E0100; Adobe-Japan1; CID+15017 -803D E0100; Adobe-Japan1; CID+2941 -803D E0101; Hanyo-Denshi; JA3531 -803D E0101; Moji_Joho; MJ020825 -803D E0102; Hanyo-Denshi; KS324310 -803D E0102; Moji_Joho; MJ058365 -803E E0100; Adobe-Japan1; CID+22251 -803F E0100; Adobe-Japan1; CID+6211 -8040 E0100; Adobe-Japan1; CID+22252 -8043 E0100; Adobe-Japan1; CID+18408 -8044 E0100; Adobe-Japan1; CID+22253 -8046 E0100; Adobe-Japan1; CID+6214 -804A E0100; Adobe-Japan1; CID+6213 -8052 E0100; Adobe-Japan1; CID+6215 -8055 E0100; Hanyo-Denshi; IP8055 -8055 E0101; Hanyo-Denshi; TK01074760 -8056 E0100; Adobe-Japan1; CID+2655 -8056 E0101; Adobe-Japan1; CID+13869 -8056 E0102; Hanyo-Denshi; JA3227 -8056 E0102; Moji_Joho; MJ020846 -8056 E0103; Hanyo-Denshi; JTC0CB -8056 E0103; Moji_Joho; MJ020845 -8056 E0104; Moji_Joho; MJ020847 -8058 E0100; Adobe-Japan1; CID+6216 -805A E0100; Adobe-Japan1; CID+6217 -805A E0101; Adobe-Japan1; CID+13580 -805A E0102; Hanyo-Denshi; JA7060 -805A E0103; Hanyo-Denshi; TK01074840 -805E E0100; Adobe-Japan1; CID+3593 -805F E0100; Adobe-Japan1; CID+6218 -805F E0101; Adobe-Japan1; CID+13581 -805F E0102; Moji_Joho; MJ020856 -805F E0103; Moji_Joho; MJ020857 -8060 E0100; Adobe-Japan1; CID+15018 -8060 E0101; Hanyo-Denshi; JB5368 -8060 E0101; Moji_Joho; MJ020858 -8060 E0102; Hanyo-Denshi; KS324830 -8060 E0102; Moji_Joho; MJ020859 -8061 E0100; Adobe-Japan1; CID+2801 -8061 E0101; Adobe-Japan1; CID+13473 -8062 E0100; Adobe-Japan1; CID+6219 -8064 E0100; Adobe-Japan1; CID+22254 -8066 E0100; Adobe-Japan1; CID+18409 -8068 E0100; Adobe-Japan1; CID+6220 -806D E0100; Adobe-Japan1; CID+22255 -806F E0100; Adobe-Japan1; CID+4038 -806F E0101; Adobe-Japan1; CID+13517 -8070 E0100; Adobe-Japan1; CID+6223 -8070 E0101; Adobe-Japan1; CID+13583 -8070 E0102; Hanyo-Denshi; JA7066 -8070 E0102; Moji_Joho; MJ020871 -8070 E0103; Hanyo-Denshi; JTB8BE -8070 E0103; Moji_Joho; MJ020872 -8070 E0104; Hanyo-Denshi; JTB8BF -8070 E0104; Moji_Joho; MJ020873 -8071 E0100; Adobe-Japan1; CID+15019 -8071 E0101; Adobe-Japan1; CID+15401 -8072 E0100; Adobe-Japan1; CID+6222 -8072 E0101; Moji_Joho; MJ020876 -8072 E0102; Moji_Joho; MJ020877 -8073 E0100; Adobe-Japan1; CID+6221 -8073 E0101; Adobe-Japan1; CID+13582 -8073 E0102; Moji_Joho; MJ020878 -8073 E0103; Moji_Joho; MJ020879 -8074 E0100; Adobe-Japan1; CID+3020 -8074 E0101; Adobe-Japan1; CID+13479 -8074 E0102; Moji_Joho; MJ020880 -8074 E0103; Moji_Joho; MJ020881 -8075 E0100; Adobe-Japan1; CID+15020 -8076 E0100; Adobe-Japan1; CID+6224 -8076 E0101; Adobe-Japan1; CID+13584 -8076 E0102; Moji_Joho; MJ020883 -8076 E0103; Moji_Joho; MJ020884 -8077 E0100; Adobe-Japan1; CID+2540 -8077 E0101; Adobe-Japan1; CID+13466 -8077 E0102; Hanyo-Denshi; JA3106 -8077 E0102; Moji_Joho; MJ020885 -8077 E0103; Hanyo-Denshi; JTB8C2 -8077 E0103; Moji_Joho; MJ020886 -8077 E0104; Moji_Joho; MJ020887 -8079 E0100; Adobe-Japan1; CID+6225 -8079 E0101; Hanyo-Denshi; JA7068 -8079 E0101; Moji_Joho; MJ020889 -8079 E0102; Hanyo-Denshi; FT2451 -8079 E0102; Moji_Joho; MJ020890 -807B E0100; Adobe-Japan1; CID+18410 -807C E0100; Hanyo-Denshi; IP807C -807C E0100; Moji_Joho; MJ020894 -807C E0101; Hanyo-Denshi; KS325730 -807C E0101; Moji_Joho; MJ020893 -807D E0100; Adobe-Japan1; CID+6226 -807D E0101; Hanyo-Denshi; JA7069 -807D E0101; Moji_Joho; MJ020895 -807D E0102; Hanyo-Denshi; KS326010 -807D E0102; Moji_Joho; MJ020896 -807E E0100; Adobe-Japan1; CID+4062 -807E E0101; Adobe-Japan1; CID+13518 -807E E0102; Hanyo-Denshi; JA4724 -807E E0102; Moji_Joho; MJ020897 -807E E0103; Hanyo-Denshi; JTB8C6 -807E E0103; Moji_Joho; MJ020898 -807E E0104; Moji_Joho; MJ020899 -807F E0100; Adobe-Japan1; CID+6227 -8081 E0100; Adobe-Japan1; CID+22256 -8081 E0101; Hanyo-Denshi; JB5374 -8081 E0102; Hanyo-Denshi; TK01075050 -8084 E0100; Adobe-Japan1; CID+6228 -8085 E0100; Adobe-Japan1; CID+6230 -8085 E0101; Hanyo-Denshi; JA7073 -8085 E0101; Moji_Joho; MJ020905 -8085 E0102; Hanyo-Denshi; IB0854 -8085 E0102; Moji_Joho; MJ058373 -8086 E0100; Adobe-Japan1; CID+6229 -8087 E0100; Adobe-Japan1; CID+3385 -8087 E0101; Adobe-Japan1; CID+13980 -8087 E0102; Hanyo-Denshi; JA4005 -8087 E0102; Moji_Joho; MJ020908 -8087 E0103; Hanyo-Denshi; JTB8C9S -8087 E0103; Moji_Joho; MJ020907 -8087 E0104; Hanyo-Denshi; TK01075120 -8088 E0100; Adobe-Japan1; CID+19696 -8088 E0101; Hanyo-Denshi; JB5375 -8088 E0102; Hanyo-Denshi; TK01075130 -8089 E0100; Adobe-Japan1; CID+3281 -8089 E0101; Adobe-Japan1; CID+13967 -808B E0100; Adobe-Japan1; CID+4068 -808C E0100; Adobe-Japan1; CID+3389 -808E E0100; Adobe-Japan1; CID+19697 -808E E0101; Hanyo-Denshi; JB5376 -808E E0101; Moji_Joho; MJ020917 -808E E0102; Hanyo-Denshi; KS326490 -808E E0102; Moji_Joho; MJ020918 -8093 E0100; Adobe-Japan1; CID+6232 -8093 E0101; Hanyo-Denshi; JA7075 -8093 E0101; Moji_Joho; MJ020923 -8093 E0102; Hanyo-Denshi; FT2452 -8093 E0102; Moji_Joho; MJ020924 -8096 E0100; Adobe-Japan1; CID+2491 -8096 E0101; Adobe-Japan1; CID+13838 -8096 E0102; Hanyo-Denshi; JA3051 -8096 E0102; Moji_Joho; MJ020928 -8096 E0103; Hanyo-Denshi; JTB8CA -8096 E0103; Moji_Joho; MJ020927 -8098 E0100; Adobe-Japan1; CID+3484 -8099 E0100; Adobe-Japan1; CID+18411 -809A E0100; Adobe-Japan1; CID+6233 -809B E0100; Adobe-Japan1; CID+6231 -809C E0100; Adobe-Japan1; CID+18412 -809D E0100; Adobe-Japan1; CID+1546 -809E E0100; Adobe-Japan1; CID+15021 -809E E0101; Adobe-Japan1; CID+15402 -809E E0102; Hanyo-Denshi; JB5378 -809E E0102; Moji_Joho; MJ020936 -809E E0103; Hanyo-Denshi; JTB2DD -809E E0103; Moji_Joho; MJ020937 -80A1 E0100; Adobe-Japan1; CID+1928 -80A2 E0100; Adobe-Japan1; CID+2230 -80A4 E0100; Adobe-Japan1; CID+18413 -80A5 E0100; Adobe-Japan1; CID+3458 -80A6 E0100; Adobe-Japan1; CID+15022 -80A7 E0100; Adobe-Japan1; CID+18414 -80A8 E0100; Hanyo-Denshi; IP80A8 -80A8 E0100; Moji_Joho; MJ020945 -80A8 E0101; Hanyo-Denshi; KS327450 -80A8 E0101; Moji_Joho; MJ020946 -80A9 E0100; Adobe-Japan1; CID+1886 -80A9 E0101; Adobe-Japan1; CID+13752 -80A9 E0102; Hanyo-Denshi; JA2410 -80A9 E0102; Moji_Joho; MJ020947 -80A9 E0103; Hanyo-Denshi; JTB8CC -80A9 E0103; Moji_Joho; MJ020948 -80AA E0100; Adobe-Japan1; CID+3697 -80AB E0100; Adobe-Japan1; CID+15023 -80AC E0100; Adobe-Japan1; CID+6236 -80AC E0101; Hanyo-Denshi; JA7079 -80AC E0102; Hanyo-Denshi; TK01041370 -80AD E0100; Adobe-Japan1; CID+6234 -80AD E0101; Hanyo-Denshi; JA7077 -80AD E0101; Moji_Joho; MJ020953 -80AD E0102; Hanyo-Denshi; FT2453 -80AD E0102; Moji_Joho; MJ020954 -80AD E0103; Hanyo-Denshi; KS161200S -80AD E0103; Moji_Joho; MJ020952 -80AF E0100; Adobe-Japan1; CID+2016 -80B1 E0100; Adobe-Japan1; CID+2017 -80B2 E0100; Adobe-Japan1; CID+1197 -80B2 E0101; Hanyo-Denshi; JA1673 -80B2 E0101; Moji_Joho; MJ020960 -80B2 E0102; Hanyo-Denshi; KS326700 -80B2 E0102; Moji_Joho; MJ020959 -80B4 E0100; Adobe-Japan1; CID+2136 -80B4 E0101; Hanyo-Denshi; JA2672 -80B4 E0101; Moji_Joho; MJ020962 -80B4 E0102; Hanyo-Denshi; KS327440 -80B4 E0102; Moji_Joho; MJ058380 -80B8 E0100; Adobe-Japan1; CID+18415 -80B9 E0100; Adobe-Japan1; CID+22257 -80BA E0100; Adobe-Japan1; CID+3343 -80BA E0101; Adobe-Japan1; CID+13975 -80BA E0102; Hanyo-Denshi; JA3957 -80BA E0102; Moji_Joho; MJ020969 -80BA E0103; Hanyo-Denshi; KS327260 -80BA E0103; Moji_Joho; MJ020968 -80C3 E0100; Adobe-Japan1; CID+1187 -80C4 E0100; Adobe-Japan1; CID+6241 -80C5 E0100; Adobe-Japan1; CID+18417 -80C6 E0100; Adobe-Japan1; CID+2942 -80C8 E0100; Adobe-Japan1; CID+22258 -80CA E0100; Adobe-Japan1; CID+17050 -80CC E0100; Adobe-Japan1; CID+3342 -80CD E0100; Adobe-Japan1; CID+22259 -80CD E0101; Hanyo-Denshi; JB5385 -80CD E0101; Moji_Joho; MJ020983 -80CD E0102; Hanyo-Denshi; KS327690 -80CD E0102; Moji_Joho; MJ020982 -80CE E0100; Adobe-Japan1; CID+2875 -80CF E0100; Adobe-Japan1; CID+19698 -80D2 E0100; Adobe-Japan1; CID+22260 -80D3 E0100; Hanyo-Denshi; IP80D3 -80D3 E0101; Hanyo-Denshi; TK01075210 -80D4 E0100; Adobe-Japan1; CID+19699 -80D5 E0100; Adobe-Japan1; CID+18418 -80D6 E0100; Adobe-Japan1; CID+6243 -80D6 E0101; Adobe-Japan1; CID+20195 -80D6 E0102; Hanyo-Denshi; JA7086 -80D6 E0102; Moji_Joho; MJ020993 -80D6 E0103; Hanyo-Denshi; FT2454 -80D6 E0103; Moji_Joho; MJ020994 -80D7 E0100; Adobe-Japan1; CID+15024 -80D8 E0100; Adobe-Japan1; CID+15025 -80D9 E0100; Adobe-Japan1; CID+6239 -80DA E0100; Adobe-Japan1; CID+6242 -80DB E0100; Adobe-Japan1; CID+6237 -80DD E0100; Adobe-Japan1; CID+6240 -80DE E0100; Adobe-Japan1; CID+3668 -80DE E0101; Adobe-Japan1; CID+14025 -80DE E0102; Hanyo-Denshi; JA4306 -80DE E0102; Moji_Joho; MJ021003 -80DE E0103; Hanyo-Denshi; JTB8CD -80DE E0103; Moji_Joho; MJ021002 -80E0 E0100; Adobe-Japan1; CID+17051 -80E1 E0100; Adobe-Japan1; CID+1929 -80E4 E0100; Adobe-Japan1; CID+1217 -80E5 E0100; Adobe-Japan1; CID+6238 -80E6 E0100; Adobe-Japan1; CID+18419 -80ED E0100; Adobe-Japan1; CID+19700 -80EE E0100; Adobe-Japan1; CID+22261 -80EE E0101; Hanyo-Denshi; JB5394 -80EE E0101; Moji_Joho; MJ021013 -80EE E0102; Hanyo-Denshi; KS328380 -80EE E0102; Moji_Joho; MJ021014 -80EF E0100; Adobe-Japan1; CID+6245 -80F0 E0100; Adobe-Japan1; CID+19701 -80F1 E0100; Adobe-Japan1; CID+6246 -80F2 E0100; Adobe-Japan1; CID+22262 -80F2 E0101; Hanyo-Denshi; JB5402 -80F2 E0101; Moji_Joho; MJ021018 -80F2 E0102; Hanyo-Denshi; KS328960 -80F2 E0102; Moji_Joho; MJ021019 -80F3 E0100; Adobe-Japan1; CID+17052 -80F4 E0100; Adobe-Japan1; CID+3217 -80F5 E0100; Adobe-Japan1; CID+18421 -80F6 E0100; Adobe-Japan1; CID+22263 -80F7 E0100; Adobe-Japan1; CID+19702 -80F7 E0101; Hanyo-Denshi; JT80F7 -80F7 E0102; Hanyo-Denshi; TK01041610 -80F8 E0100; Adobe-Japan1; CID+1715 -80F9 E0100; Adobe-Japan1; CID+22264 -80FA E0100; Adobe-Japan1; CID+19703 -80FB E0100; Adobe-Japan1; CID+18422 -80FC E0100; Adobe-Japan1; CID+6257 -80FD E0100; Adobe-Japan1; CID+3315 -80FE E0100; Adobe-Japan1; CID+19704 -8102 E0100; Adobe-Japan1; CID+2231 -8103 E0100; Adobe-Japan1; CID+19705 -8105 E0100; Adobe-Japan1; CID+1716 -8106 E0100; Adobe-Japan1; CID+2668 -8106 E0101; Adobe-Japan1; CID+13876 -8106 E0102; Hanyo-Denshi; JA3240 -8106 E0102; Moji_Joho; MJ021039 -8106 E0103; Hanyo-Denshi; HG1635 -8106 E0103; Moji_Joho; MJ021040 -8107 E0100; Adobe-Japan1; CID+4076 -8108 E0100; Adobe-Japan1; CID+3770 -8108 E0101; Adobe-Japan1; CID+13510 -8108 E0102; Adobe-Japan1; CID+14051 -8108 E0103; Hanyo-Denshi; JA4414 -8108 E0103; Moji_Joho; MJ021043 -8108 E0104; Hanyo-Denshi; JTB8D1 -8108 E0104; Moji_Joho; MJ021042 -8108 E0105; Moji_Joho; MJ021044 -8109 E0100; Adobe-Japan1; CID+6244 -8109 E0101; Adobe-Japan1; CID+20196 -810A E0100; Adobe-Japan1; CID+2680 -810B E0100; Adobe-Japan1; CID+22265 -810D E0100; Adobe-Japan1; CID+18420 -8116 E0100; Adobe-Japan1; CID+15026 -8117 E0100; Adobe-Japan1; CID+19706 -8118 E0100; Adobe-Japan1; CID+15027 -811A E0100; Adobe-Japan1; CID+1645 -811B E0100; Adobe-Japan1; CID+6247 -811C E0100; Adobe-Japan1; CID+22266 -811E E0100; Adobe-Japan1; CID+18425 -811F E0100; Hanyo-Denshi; IP811F -811F E0101; Hanyo-Denshi; TK01041970 -8120 E0100; Adobe-Japan1; CID+22267 -8123 E0100; Adobe-Japan1; CID+6249 -8124 E0100; Adobe-Japan1; CID+18427 -8127 E0100; Adobe-Japan1; CID+18428 -8129 E0100; Adobe-Japan1; CID+6248 -8129 E0101; Adobe-Japan1; CID+20197 -8129 E0102; Hanyo-Denshi; JA7091 -8129 E0102; Moji_Joho; MJ021073 -8129 E0103; Hanyo-Denshi; KS328970 -8129 E0103; Moji_Joho; MJ021072 -8129 E0104; Hanyo-Denshi; TK01004740 -812B E0100; Adobe-Japan1; CID+13913 -812B E0101; Moji_Joho; MJ021075 -812B E0102; Moji_Joho; MJ058383 -812C E0100; Adobe-Japan1; CID+18429 -812F E0100; Adobe-Japan1; CID+6250 -8130 E0100; Adobe-Japan1; CID+19707 -8131 E0100; Adobe-Japan1; CID+2916 -8133 E0100; Adobe-Japan1; CID+3316 -8135 E0100; Adobe-Japan1; CID+18424 -8135 E0101; Hanyo-Denshi; JB5420 -8135 E0102; Hanyo-Denshi; TK01041890 -8135 E0103; Hanyo-Denshi; TK01075240 -8139 E0100; Adobe-Japan1; CID+3021 -813A E0100; Adobe-Japan1; CID+15028 -813C E0100; Adobe-Japan1; CID+22268 -813D E0100; Adobe-Japan1; CID+18431 -813E E0100; Adobe-Japan1; CID+6254 -8141 E0100; Adobe-Japan1; CID+14194 -8143 E0100; Hanyo-Denshi; IP8143 -8143 E0101; Hanyo-Denshi; TK01026810 -8143 E0102; Hanyo-Denshi; TK01042250 -8143 E0103; Hanyo-Denshi; TK01042300 -8145 E0100; Adobe-Japan1; CID+22269 -8146 E0100; Adobe-Japan1; CID+6253 -8147 E0100; Adobe-Japan1; CID+22270 -814A E0100; Adobe-Japan1; CID+15029 -814B E0100; Adobe-Japan1; CID+6251 -814C E0100; Adobe-Japan1; CID+15030 -814E E0100; Adobe-Japan1; CID+2587 -8150 E0100; Adobe-Japan1; CID+3543 -8151 E0100; Adobe-Japan1; CID+6256 -8152 E0100; Adobe-Japan1; CID+22271 -8153 E0100; Adobe-Japan1; CID+6255 -8153 E0101; Adobe-Japan1; CID+13585 -8153 E0102; Moji_Joho; MJ021119 -8153 E0103; Moji_Joho; MJ021120 -8154 E0100; Adobe-Japan1; CID+2018 -8154 E0101; Adobe-Japan1; CID+13771 -8154 E0102; Hanyo-Denshi; JA2548 -8154 E0102; Moji_Joho; MJ021121 -8154 E0103; Hanyo-Denshi; HG1624 -8154 E0103; Moji_Joho; MJ021122 -8155 E0100; Adobe-Japan1; CID+4089 -8157 E0100; Adobe-Japan1; CID+19708 -815F E0100; Adobe-Japan1; CID+6272 -8160 E0100; Adobe-Japan1; CID+17053 -8160 E0101; Hanyo-Denshi; JB5429 -8160 E0101; Moji_Joho; MJ021132 -8160 E0102; Hanyo-Denshi; JTB8E1 -8160 E0102; Moji_Joho; MJ021133 -8161 E0100; Adobe-Japan1; CID+22272 -8162 E0100; Hanyo-Denshi; IP8162 -8162 E0101; Hanyo-Denshi; KS331060 -8164 E0100; Hanyo-Denshi; IP8164 -8164 E0100; Moji_Joho; MJ021138 -8164 E0101; Hanyo-Denshi; KS331840 -8164 E0101; Moji_Joho; MJ021139 -8165 E0100; Adobe-Japan1; CID+6260 -8166 E0100; Adobe-Japan1; CID+6261 -8166 E0101; Hanyo-Denshi; JA7110 -8166 E0101; Moji_Joho; MJ021141 -8166 E0102; Hanyo-Denshi; KS331820 -8166 E0102; Moji_Joho; MJ058390 -8167 E0100; Adobe-Japan1; CID+17054 -8168 E0100; Adobe-Japan1; CID+17055 -8169 E0100; Adobe-Japan1; CID+18433 -816B E0100; Adobe-Japan1; CID+2332 -816D E0100; Adobe-Japan1; CID+17056 -816E E0100; Adobe-Japan1; CID+6259 -816F E0100; Adobe-Japan1; CID+19709 -8170 E0100; Adobe-Japan1; CID+2058 -8170 E0101; Adobe-Japan1; CID+13777 -8170 E0102; Hanyo-Denshi; JA2588 -8170 E0102; Moji_Joho; MJ021151 -8170 E0103; Hanyo-Denshi; JTB8E2 -8170 E0103; Moji_Joho; MJ021152 -8171 E0100; Adobe-Japan1; CID+6258 -8171 E0101; Adobe-Japan1; CID+20275 -8171 E0102; Moji_Joho; MJ021153 -8171 E0103; Moji_Joho; MJ021154 -8173 E0100; Adobe-Japan1; CID+19710 -8173 E0101; Moji_Joho; MJ021156 -8173 E0102; Moji_Joho; MJ021157 -8174 E0100; Adobe-Japan1; CID+6262 -8174 E0101; Hanyo-Denshi; JA7111 -8174 E0101; Moji_Joho; MJ021158 -8174 E0102; Hanyo-Denshi; JTB8DC -8174 E0102; Moji_Joho; MJ021159 -8177 E0100; Adobe-Japan1; CID+22273 -8178 E0100; Adobe-Japan1; CID+3022 -8179 E0100; Adobe-Japan1; CID+3570 -8179 E0101; Hanyo-Denshi; JA4202 -8179 E0101; Moji_Joho; MJ021164 -8179 E0102; Hanyo-Denshi; KS331550 -8179 E0102; Moji_Joho; MJ021165 -817A E0100; Adobe-Japan1; CID+2725 -817F E0100; Adobe-Japan1; CID+2876 -817F E0101; Adobe-Japan1; CID+7728 -817F E0102; Hanyo-Denshi; JA3460 -817F E0102; Moji_Joho; MJ021168 -817F E0103; Hanyo-Denshi; FT1848 -817F E0103; Moji_Joho; MJ021169 -8180 E0100; Adobe-Japan1; CID+6266 -8180 E0101; Hanyo-Denshi; JA7115 -8180 E0101; Moji_Joho; MJ021170 -8180 E0102; Hanyo-Denshi; KS332580 -8180 E0102; Moji_Joho; MJ021171 -8181 E0100; Adobe-Japan1; CID+15031 -8182 E0100; Adobe-Japan1; CID+6267 -8183 E0100; Adobe-Japan1; CID+6263 -8184 E0100; Adobe-Japan1; CID+15032 -8184 E0101; Hanyo-Denshi; JB5439 -8184 E0101; Moji_Joho; MJ021175 -8184 E0102; Hanyo-Denshi; IB2755 -8184 E0102; Moji_Joho; MJ021177 -8184 E0103; Hanyo-Denshi; JTB8D8 -8184 E0103; Moji_Joho; MJ021176 -8185 E0100; Adobe-Japan1; CID+18436 -8186 E0100; Adobe-Japan1; CID+22274 -8187 E0100; Hanyo-Denshi; IB0856 -8187 E0100; Moji_Joho; MJ021180 -8187 E0101; Hanyo-Denshi; IP8187 -8187 E0101; Moji_Joho; MJ021181 -8188 E0100; Adobe-Japan1; CID+6264 -818A E0100; Adobe-Japan1; CID+6265 -818A E0101; Adobe-Japan1; CID+13586 -818A E0102; Hanyo-Denshi; JA7114 -818A E0102; Moji_Joho; MJ021185 -818A E0103; Hanyo-Denshi; FT2458 -818A E0103; Moji_Joho; MJ021184 -818B E0100; Adobe-Japan1; CID+19711 -818B E0101; Hanyo-Denshi; JB5442 -818B E0101; Moji_Joho; MJ021186 -818B E0102; Hanyo-Denshi; KS332610 -818B E0102; Moji_Joho; MJ021187 -818E E0100; Adobe-Japan1; CID+22275 -818F E0100; Adobe-Japan1; CID+2019 -8190 E0100; Adobe-Japan1; CID+19712 -8193 E0100; Adobe-Japan1; CID+6273 -8195 E0100; Adobe-Japan1; CID+6269 -8196 E0100; Adobe-Japan1; CID+22276 -8198 E0100; Adobe-Japan1; CID+18438 -819A E0100; Adobe-Japan1; CID+3544 -819B E0100; Adobe-Japan1; CID+19713 -819C E0100; Adobe-Japan1; CID+3738 -819C E0101; Hanyo-Denshi; JA4376 -819C E0101; Moji_Joho; MJ021203 -819C E0102; Hanyo-Denshi; KS332890 -819C E0102; Moji_Joho; MJ021204 -819D E0100; Adobe-Japan1; CID+3482 -819E E0100; Adobe-Japan1; CID+19714 -819E E0101; Hanyo-Denshi; JB5447 -819E E0101; Moji_Joho; MJ021206 -819E E0102; Hanyo-Denshi; JTB8F2 -819E E0102; Moji_Joho; MJ021207 -81A0 E0100; Adobe-Japan1; CID+6268 -81A0 E0101; Hanyo-Denshi; JA7117 -81A0 E0101; Moji_Joho; MJ021209 -81A0 E0102; Hanyo-Denshi; FT2459 -81A0 E0102; Moji_Joho; MJ021210 -81A2 E0100; Adobe-Japan1; CID+22277 -81A3 E0100; Adobe-Japan1; CID+6271 -81A4 E0100; Adobe-Japan1; CID+6270 -81A4 E0101; Hanyo-Denshi; JA7119 -81A4 E0101; Moji_Joho; MJ021214 -81A4 E0102; Hanyo-Denshi; FT2460 -81A4 E0102; Moji_Joho; MJ021215 -81A7 E0100; Hanyo-Denshi; IP81A7 -81A7 E0100; Moji_Joho; MJ021217 -81A7 E0101; Hanyo-Denshi; KS162120 -81A7 E0101; Moji_Joho; MJ058400 -81A8 E0100; Adobe-Japan1; CID+3698 -81A9 E0100; Adobe-Japan1; CID+6274 -81AE E0100; Adobe-Japan1; CID+22278 -81B0 E0100; Adobe-Japan1; CID+6275 -81B1 E0100; Hanyo-Denshi; IP81B1 -81B1 E0100; Moji_Joho; MJ021227 -81B1 E0101; Hanyo-Denshi; KS333840 -81B1 E0101; Moji_Joho; MJ021228 -81B2 E0100; Adobe-Japan1; CID+18439 -81B3 E0100; Adobe-Japan1; CID+2745 -81B4 E0100; Adobe-Japan1; CID+15033 -81B5 E0100; Adobe-Japan1; CID+6276 -81B5 E0101; Adobe-Japan1; CID+13587 -81B5 E0102; Hanyo-Denshi; JA7125 -81B5 E0102; Moji_Joho; MJ021232 -81B5 E0103; Hanyo-Denshi; KS333750 -81B5 E0103; Moji_Joho; MJ021234 -81B5 E0104; Hanyo-Denshi; FT1724 -81B5 E0104; Moji_Joho; MJ021233 -81B8 E0100; Adobe-Japan1; CID+6278 -81B8 E0101; Hanyo-Denshi; JA7127 -81B8 E0101; Moji_Joho; MJ021237 -81B8 E0102; Hanyo-Denshi; FT2461 -81B8 E0102; Moji_Joho; MJ021236 -81B9 E0100; Hanyo-Denshi; IP81B9 -81B9 E0100; Moji_Joho; MJ021238 -81B9 E0101; Hanyo-Denshi; KS333910 -81B9 E0101; Moji_Joho; MJ021239 -81BA E0100; Adobe-Japan1; CID+6282 -81BB E0100; Adobe-Japan1; CID+17057 -81BD E0100; Adobe-Japan1; CID+6279 -81BD E0101; Hanyo-Denshi; JA7128 -81BD E0102; Hanyo-Denshi; TK01075330 -81BE E0100; Adobe-Japan1; CID+6277 -81BF E0100; Adobe-Japan1; CID+3317 -81C0 E0100; Adobe-Japan1; CID+6280 -81C1 E0100; Adobe-Japan1; CID+18440 -81C2 E0100; Adobe-Japan1; CID+6281 -81C3 E0100; Adobe-Japan1; CID+18441 -81C5 E0100; Adobe-Japan1; CID+22279 -81C6 E0100; Adobe-Japan1; CID+1330 -81C6 E0101; Hanyo-Denshi; JA1818 -81C6 E0101; Moji_Joho; MJ021253 -81C6 E0102; Hanyo-Denshi; KS334290 -81C6 E0102; Moji_Joho; MJ021254 -81C8 E0100; Adobe-Japan1; CID+6288 -81C8 E0101; Hanyo-Denshi; JA7137 -81C8 E0101; Moji_Joho; MJ021256 -81C8 E0102; Hanyo-Denshi; KS334150 -81C8 E0102; Moji_Joho; MJ021257 -81C8 E0103; Hanyo-Denshi; FT2462 -81C8 E0103; Moji_Joho; MJ021258 -81C9 E0100; Adobe-Japan1; CID+6283 -81CA E0100; Adobe-Japan1; CID+17058 -81CB E0100; Adobe-Japan1; CID+19715 -81CD E0100; Adobe-Japan1; CID+6284 -81CD E0101; Adobe-Japan1; CID+13588 -81CE E0100; Adobe-Japan1; CID+22280 -81CF E0100; Adobe-Japan1; CID+15034 -81D1 E0100; Adobe-Japan1; CID+6285 -81D3 E0100; Adobe-Japan1; CID+2817 -81D5 E0100; Adobe-Japan1; CID+19716 -81D6 E0100; Adobe-Japan1; CID+18442 -81D7 E0100; Adobe-Japan1; CID+17059 -81D7 E0101; Hanyo-Denshi; JB5460 -81D7 E0101; Moji_Joho; MJ021273 -81D7 E0102; Hanyo-Denshi; KS334830 -81D7 E0102; Moji_Joho; MJ021274 -81D8 E0100; Adobe-Japan1; CID+6287 -81D9 E0100; Adobe-Japan1; CID+6286 -81DA E0100; Adobe-Japan1; CID+6289 -81DB E0100; Adobe-Japan1; CID+18443 -81DD E0100; Adobe-Japan1; CID+19717 -81DD E0101; Hanyo-Denshi; JB5462 -81DD E0102; Hanyo-Denshi; TK01075340 -81DE E0100; Adobe-Japan1; CID+19718 -81DF E0100; Adobe-Japan1; CID+6290 -81DF E0101; Hanyo-Denshi; JA7139 -81DF E0101; Moji_Joho; MJ021282 -81DF E0102; Hanyo-Denshi; KS335270 -81DF E0102; Moji_Joho; MJ021283 -81E0 E0100; Adobe-Japan1; CID+6291 -81E1 E0100; Adobe-Japan1; CID+19719 -81E3 E0100; Adobe-Japan1; CID+2569 -81E4 E0100; Adobe-Japan1; CID+18445 -81E5 E0100; Adobe-Japan1; CID+1385 -81E7 E0100; Adobe-Japan1; CID+6292 -81E7 E0101; Hanyo-Denshi; JA7141 -81E7 E0101; Moji_Joho; MJ021291 -81E7 E0102; Hanyo-Denshi; FT2463 -81E7 E0102; Moji_Joho; MJ021292 -81E7 E0103; Hanyo-Denshi; TK01009020 -81E8 E0100; Adobe-Japan1; CID+3999 -81EA E0100; Adobe-Japan1; CID+2263 -81EB E0100; Adobe-Japan1; CID+22281 -81EC E0100; Adobe-Japan1; CID+18447 -81ED E0100; Adobe-Japan1; CID+2359 -81ED E0101; Adobe-Japan1; CID+13350 -81ED E0102; Hanyo-Denshi; JA2913 -81ED E0103; Hanyo-Denshi; JC9056 -81EE E0100; Moji_Joho; MJ021300 -81EE E0101; Moji_Joho; MJ045921 -81EF E0100; Adobe-Japan1; CID+19720 -81F0 E0100; Adobe-Japan1; CID+22282 -81F1 E0100; Adobe-Japan1; CID+22283 -81F1 E0101; Hanyo-Denshi; JB5469 -81F1 E0101; Moji_Joho; MJ021303 -81F1 E0102; Hanyo-Denshi; KS254920S -81F1 E0102; Moji_Joho; MJ058139 -81F2 E0100; Adobe-Japan1; CID+22284 -81F3 E0100; Adobe-Japan1; CID+2232 -81F4 E0100; Adobe-Japan1; CID+2965 -81F4 E0101; Hanyo-Denshi; JA3555 -81F4 E0101; Moji_Joho; MJ021307 -81F4 E0102; Hanyo-Denshi; KS336410 -81F4 E0102; Moji_Joho; MJ021306 -81F5 E0100; Adobe-Japan1; CID+22285 -81F6 E0100; Adobe-Japan1; CID+19721 -81F8 E0100; Adobe-Japan1; CID+22286 -81F9 E0100; Adobe-Japan1; CID+15035 -81F9 E0101; Hanyo-Denshi; JB5474 -81F9 E0101; Moji_Joho; MJ021312 -81F9 E0102; Hanyo-Denshi; JTB8F9 -81F9 E0102; Moji_Joho; MJ021313 -81F9 E0103; Hanyo-Denshi; TK01075460 -81FA E0100; Adobe-Japan1; CID+6293 -81FB E0100; Adobe-Japan1; CID+6294 -81FC E0100; Adobe-Japan1; CID+1235 -81FD E0100; Adobe-Japan1; CID+18448 -81FD E0101; Hanyo-Denshi; JB5475 -81FD E0101; Moji_Joho; MJ021317 -81FD E0102; Hanyo-Denshi; KS336790 -81FD E0102; Moji_Joho; MJ021318 -81FE E0100; Adobe-Japan1; CID+6295 -81FE E0101; Hanyo-Denshi; JA7144 -81FE E0101; Moji_Joho; MJ021320 -81FE E0102; Hanyo-Denshi; JTB8FC -81FE E0102; Moji_Joho; MJ021319 -81FF E0100; Adobe-Japan1; CID+18449 -81FF E0101; Hanyo-Denshi; JB5476 -81FF E0101; Moji_Joho; MJ021321 -81FF E0102; Hanyo-Denshi; KS336860 -81FF E0102; Moji_Joho; MJ021322 -8200 E0100; Adobe-Japan1; CID+19722 -8200 E0101; Adobe-Japan1; CID+22287 -8200 E0102; Hanyo-Denshi; JB5477 -8200 E0102; Moji_Joho; MJ021323 -8200 E0103; Hanyo-Denshi; KS336890 -8200 E0103; Moji_Joho; MJ021324 -8200 E0104; Hanyo-Denshi; KS336980 -8200 E0104; Moji_Joho; MJ021325 -8200 E0105; Hanyo-Denshi; KS336990 -8200 E0105; Moji_Joho; MJ058416 -8201 E0100; Adobe-Japan1; CID+6296 -8201 E0101; Hanyo-Denshi; JA7145 -8201 E0101; Moji_Joho; MJ021326 -8201 E0102; Hanyo-Denshi; KS337010 -8201 E0102; Moji_Joho; MJ021328 -8201 E0103; Hanyo-Denshi; KS336910 -8201 E0103; Moji_Joho; MJ021327 -8202 E0100; Adobe-Japan1; CID+6297 -8202 E0101; Hanyo-Denshi; JA7146 -8202 E0101; Moji_Joho; MJ021329 -8202 E0102; Hanyo-Denshi; KS337110 -8202 E0102; Moji_Joho; MJ021330 -8203 E0100; Adobe-Japan1; CID+15036 -8204 E0100; Adobe-Japan1; CID+18451 -8204 E0101; Hanyo-Denshi; JD8562 -8204 E0101; Moji_Joho; MJ021332 -8204 E0102; Hanyo-Denshi; KS337180 -8204 E0102; Moji_Joho; MJ021333 -8205 E0100; Adobe-Japan1; CID+6298 -8207 E0100; Adobe-Japan1; CID+6299 -8207 E0101; Hanyo-Denshi; JA7148 -8207 E0102; Hanyo-Denshi; TK01075570 -8208 E0100; Adobe-Japan1; CID+1717 -8208 E0101; Hanyo-Denshi; JA2229 -8208 E0101; Moji_Joho; MJ021338 -8208 E0102; Hanyo-Denshi; KS337400 -8208 E0102; Moji_Joho; MJ058419 -8209 E0100; Adobe-Japan1; CID+5039 -820A E0100; Adobe-Japan1; CID+6300 -820A E0101; Hanyo-Denshi; JA7149 -820A E0101; Moji_Joho; MJ021340 -820A E0102; Hanyo-Denshi; KS337730 -820A E0102; Moji_Joho; MJ021341 -820A E0103; Hanyo-Denshi; TK01040530 -820B E0100; Adobe-Japan1; CID+19723 -820B E0101; Hanyo-Denshi; KS337780 -820B E0101; Moji_Joho; MJ021342 -820B E0102; Hanyo-Denshi; KS337790 -820B E0102; Moji_Joho; MJ058420 -820C E0100; Adobe-Japan1; CID+2697 -820C E0101; Adobe-Japan1; CID+20198 -820C E0102; Hanyo-Denshi; JA3269 -820C E0102; Moji_Joho; MJ021343 -820C E0103; Hanyo-Denshi; KS338030 -820C E0103; Moji_Joho; MJ021344 -820D E0100; Adobe-Japan1; CID+6301 -820E E0100; Adobe-Japan1; CID+2295 -820E E0101; Hanyo-Denshi; JA2843 -820E E0102; Hanyo-Denshi; TK01014060 -820E E0103; Hanyo-Denshi; TK01075660 -820F E0100; Adobe-Japan1; CID+22288 -8210 E0100; Adobe-Japan1; CID+6302 -8211 E0100; Hanyo-Denshi; IP8211 -8211 E0100; Moji_Joho; MJ021351 -8211 E0101; Hanyo-Denshi; JT8211 -8211 E0101; Moji_Joho; MJ021352 -8212 E0100; Adobe-Japan1; CID+4105 -8212 E0101; Hanyo-Denshi; JA4816 -8212 E0101; Moji_Joho; MJ021354 -8212 E0102; Hanyo-Denshi; KS011750 -8212 E0102; Moji_Joho; MJ021353 -8212 E0103; Hanyo-Denshi; TK01005210 -8212 E0104; Hanyo-Denshi; TK01075680 -8213 E0100; Adobe-Japan1; CID+19724 -8214 E0100; Adobe-Japan1; CID+19725 -8216 E0100; Adobe-Japan1; CID+6303 -8217 E0100; Adobe-Japan1; CID+3630 -8218 E0100; Adobe-Japan1; CID+1560 -8218 E0101; Adobe-Japan1; CID+13695 -8218 E0102; Hanyo-Denshi; JA2060 -8218 E0102; Moji_Joho; MJ021362 -8218 E0103; Hanyo-Denshi; IB1067 -8218 E0103; Moji_Joho; MJ030310 -8218 E0104; Hanyo-Denshi; JTB907 -8218 E0104; Moji_Joho; MJ021355 -8219 E0100; Adobe-Japan1; CID+18453 -821A E0100; Adobe-Japan1; CID+19726 -821B E0100; Adobe-Japan1; CID+2726 -821B E0101; Adobe-Japan1; CID+20199 -821B E0102; Hanyo-Denshi; JA3304 -821B E0102; Moji_Joho; MJ021365 -821B E0103; Hanyo-Denshi; IB0352 -821B E0103; Moji_Joho; MJ021367 -821B E0104; Hanyo-Denshi; TK01075750 -821B E0105; Hanyo-Denshi; TK01075760 -821B E0106; Moji_Joho; MJ021366 -821B E0107; Moji_Joho; MJ021368 -821C E0100; Adobe-Japan1; CID+2402 -821C E0101; Adobe-Japan1; CID+13459 -821C E0102; Hanyo-Denshi; JA2956 -821C E0102; Moji_Joho; MJ021371 -821C E0103; Hanyo-Denshi; KS338690 -821C E0103; Moji_Joho; MJ021370 -821C E0104; Moji_Joho; MJ021369 -821D E0100; Adobe-Japan1; CID+22289 -821D E0101; Hanyo-Denshi; JB5484 -821D E0101; Moji_Joho; MJ021373 -821D E0102; Hanyo-Denshi; JTB90C -821D E0102; Moji_Joho; MJ021372 -821E E0100; Adobe-Japan1; CID+3555 -821E E0101; Hanyo-Denshi; JA4181 -821E E0101; Moji_Joho; MJ021375 -821E E0102; Hanyo-Denshi; KS338720 -821E E0102; Moji_Joho; MJ021374 -821F E0100; Adobe-Japan1; CID+2360 -821F E0101; Adobe-Japan1; CID+13747 -821F E0102; Hanyo-Denshi; JA2914 -821F E0102; Moji_Joho; MJ021376 -821F E0103; Hanyo-Denshi; KS338850 -821F E0103; Moji_Joho; MJ058427 -8221 E0100; Adobe-Japan1; CID+15037 -8222 E0100; Adobe-Japan1; CID+18454 -8228 E0100; Adobe-Japan1; CID+22290 -8229 E0100; Adobe-Japan1; CID+6304 -8229 E0101; Hanyo-Denshi; JA7153 -8229 E0101; Moji_Joho; MJ021384 -8229 E0102; Hanyo-Denshi; FT2464 -8229 E0102; Moji_Joho; MJ021385 -822A E0100; Adobe-Japan1; CID+2020 -822B E0100; Adobe-Japan1; CID+6305 -822C E0100; Adobe-Japan1; CID+3424 -822E E0100; Adobe-Japan1; CID+6319 -822E E0101; Adobe-Japan1; CID+7855 -822E E0102; Hanyo-Denshi; JA7168 -822E E0102; Moji_Joho; MJ021390 -822E E0103; Hanyo-Denshi; FT1980 -822E E0103; Moji_Joho; MJ021391 -8232 E0100; Adobe-Japan1; CID+15038 -8233 E0100; Adobe-Japan1; CID+6307 -8234 E0100; Adobe-Japan1; CID+15039 -8235 E0100; Adobe-Japan1; CID+2857 -8236 E0100; Adobe-Japan1; CID+3371 -8237 E0100; Adobe-Japan1; CID+1907 -8238 E0100; Adobe-Japan1; CID+6306 -8238 E0101; Hanyo-Denshi; JA7155 -8238 E0101; Moji_Joho; MJ021398 -8238 E0102; Hanyo-Denshi; JTB90E -8238 E0102; Moji_Joho; MJ021399 -8239 E0100; Adobe-Japan1; CID+2727 -8239 E0101; Adobe-Japan1; CID+13471 -8239 E0102; Adobe-Japan1; CID+13886 -8239 E0103; Hanyo-Denshi; JA3305 -8239 E0103; Moji_Joho; MJ021400 -8239 E0104; Hanyo-Denshi; JTB910 -8239 E0104; Moji_Joho; MJ021401 -8239 E0105; Hanyo-Denshi; FT1643 -8239 E0105; Moji_Joho; MJ021402 -8239 E0106; Hanyo-Denshi; TK01075840 -8239 E0107; Hanyo-Denshi; TK01075870 -823A E0100; Adobe-Japan1; CID+19727 -823C E0100; Adobe-Japan1; CID+18456 -8240 E0100; Adobe-Japan1; CID+6308 -8240 E0101; Adobe-Japan1; CID+20200 -8240 E0102; Hanyo-Denshi; JA7157 -8240 E0102; Moji_Joho; MJ021407 -8240 E0103; Hanyo-Denshi; FT2465 -8240 E0103; Moji_Joho; MJ021408 -8243 E0100; Adobe-Japan1; CID+22291 -8244 E0100; Adobe-Japan1; CID+19728 -8245 E0100; Adobe-Japan1; CID+18458 -8246 E0100; Adobe-Japan1; CID+15040 -8247 E0100; Adobe-Japan1; CID+3094 -8247 E0101; Adobe-Japan1; CID+13483 -8247 E0102; Moji_Joho; MJ021415 -8247 E0103; Moji_Joho; MJ021416 -8249 E0100; Adobe-Japan1; CID+18457 -824B E0100; Adobe-Japan1; CID+15041 -824E E0100; Adobe-Japan1; CID+22292 -824F E0100; Adobe-Japan1; CID+15042 -8251 E0100; Adobe-Japan1; CID+22293 -8255 E0100; Hanyo-Denshi; IP8255 -8255 E0100; Moji_Joho; MJ021427 -8255 E0101; Hanyo-Denshi; KS340610 -8255 E0101; Moji_Joho; MJ021428 -8256 E0100; Adobe-Japan1; CID+22294 -8257 E0100; Adobe-Japan1; CID+18462 -8257 E0101; Hanyo-Denshi; JD8579 -8257 E0101; Moji_Joho; MJ021430 -8257 E0102; Hanyo-Denshi; JTB917 -8257 E0102; Moji_Joho; MJ021431 -8257 E0103; Hanyo-Denshi; TK01076000 -8258 E0100; Adobe-Japan1; CID+6310 -8258 E0101; Adobe-Japan1; CID+14196 -8258 E0102; Hanyo-Denshi; JA7159 -8258 E0102; Moji_Joho; MJ021434 -8258 E0103; Hanyo-Denshi; HG1643 -8258 E0103; Moji_Joho; MJ021435 -8258 E0104; Hanyo-Denshi; FT2466 -8258 E0104; Moji_Joho; MJ021433 -8259 E0100; Adobe-Japan1; CID+6309 -825A E0100; Adobe-Japan1; CID+6312 -825C E0100; Adobe-Japan1; CID+18464 -825D E0100; Adobe-Japan1; CID+6311 -825D E0101; Hanyo-Denshi; JA7160 -825D E0101; Moji_Joho; MJ021440 -825D E0102; Hanyo-Denshi; FT2467 -825D E0102; Moji_Joho; MJ021441 -825F E0100; Adobe-Japan1; CID+6313 -825F E0101; Hanyo-Denshi; JA7162 -825F E0101; Moji_Joho; MJ021443 -825F E0102; Hanyo-Denshi; KS341050 -825F E0102; Moji_Joho; MJ021444 -8260 E0100; Adobe-Japan1; CID+17061 -8262 E0100; Adobe-Japan1; CID+6315 -8263 E0100; Adobe-Japan1; CID+18465 -8264 E0100; Adobe-Japan1; CID+6314 -8265 E0100; Hanyo-Denshi; IP8265 -8265 E0100; Moji_Joho; MJ021450 -8265 E0101; Hanyo-Denshi; JTC0CC -8265 E0101; Moji_Joho; MJ021451 -8266 E0100; Adobe-Japan1; CID+1547 -8266 E0101; Hanyo-Denshi; JA2047 -8266 E0102; Hanyo-Denshi; TK01076020 -8267 E0100; Adobe-Japan1; CID+22295 -8267 E0101; Hanyo-Denshi; JB5509 -8267 E0101; Moji_Joho; MJ021454 -8267 E0102; Hanyo-Denshi; KS341230 -8267 E0102; Moji_Joho; MJ021455 -8268 E0100; Adobe-Japan1; CID+6316 -8268 E0101; Hanyo-Denshi; JA7165 -8268 E0101; Moji_Joho; MJ021456 -8268 E0102; Hanyo-Denshi; KS341240 -8268 E0102; Moji_Joho; MJ021457 -8268 E0103; Hanyo-Denshi; FT2468 -8268 E0103; Moji_Joho; MJ021458 -826A E0100; Adobe-Japan1; CID+6317 -826B E0100; Adobe-Japan1; CID+6318 -826D E0100; Adobe-Japan1; CID+19729 -826D E0101; Moji_Joho; MJ021463 -826D E0102; Moji_Joho; MJ021464 -826E E0100; Adobe-Japan1; CID+2081 -826E E0101; Moji_Joho; MJ021465 -826E E0102; Moji_Joho; MJ021466 -826F E0100; Adobe-Japan1; CID+3985 -8271 E0100; Adobe-Japan1; CID+6320 -8271 E0101; Hanyo-Denshi; JA7169 -8271 E0101; Moji_Joho; MJ021468 -8271 E0102; Hanyo-Denshi; FT2469 -8271 E0102; Moji_Joho; MJ021469 -8272 E0100; Adobe-Japan1; CID+2541 -8273 E0100; Hanyo-Denshi; TK01076120 -8273 E0101; Hanyo-Denshi; TK01076130 -8273 E0102; Hanyo-Denshi; TK01076140 -8273 E0103; Hanyo-Denshi; TK01076150 -8274 E0100; Adobe-Japan1; CID+17062 -8275 E0100; Hanyo-Denshi; IP8275 -8275 E0100; Moji_Joho; MJ021477 -8275 E0101; Hanyo-Denshi; KS341680 -8275 E0101; Moji_Joho; MJ021476 -8276 E0100; Adobe-Japan1; CID+1298 -8277 E0100; Adobe-Japan1; CID+6321 -8278 E0100; Adobe-Japan1; CID+6322 -8279 E0100; Adobe-Japan1; CID+14197 -8279 E0101; Adobe-Japan1; CID+14199 -8279 E0102; Adobe-Japan1; CID+14198 -8279 E0103; Hanyo-Denshi; JD8584 -8279 E0104; Hanyo-Denshi; JD8585 -8279 E0105; Hanyo-Denshi; JD8586 -827B E0100; Adobe-Japan1; CID+22296 -827B E0101; Hanyo-Denshi; JB5512 -827B E0101; Moji_Joho; MJ021483 -827B E0102; Hanyo-Denshi; KS342050 -827B E0102; Moji_Joho; MJ021484 -827C E0100; Hanyo-Denshi; IP827C -827C E0101; Hanyo-Denshi; KS342060 -827D E0100; Adobe-Japan1; CID+18468 -827D E0101; Hanyo-Denshi; JB5513 -827D E0101; Moji_Joho; MJ021487 -827D E0102; Hanyo-Denshi; KS342080 -827D E0102; Moji_Joho; MJ021488 -827E E0100; Adobe-Japan1; CID+6323 -827E E0101; Hanyo-Denshi; JA7172 -827E E0102; Hanyo-Denshi; KS342100 -827E E0102; Moji_Joho; MJ021490 -827E E0103; Moji_Joho; MJ021489 -827E E0104; Moji_Joho; MJ021491 -827F E0100; Adobe-Japan1; CID+18469 -827F E0101; Hanyo-Denshi; JB5514 -827F E0101; Moji_Joho; MJ021492 -827F E0102; Hanyo-Denshi; JTB920 -827F E0102; Moji_Joho; MJ021493 -8280 E0100; Adobe-Japan1; CID+22297 -8280 E0101; Hanyo-Denshi; JB5515 -8280 E0101; Moji_Joho; MJ021494 -8280 E0102; Hanyo-Denshi; KS342140 -8280 E0102; Moji_Joho; MJ021495 -8281 E0100; Adobe-Japan1; CID+22298 -8281 E0101; Hanyo-Denshi; JB5516 -8281 E0101; Moji_Joho; MJ021496 -8281 E0102; Hanyo-Denshi; KS342160 -8281 E0102; Moji_Joho; MJ021497 -8283 E0100; Adobe-Japan1; CID+18470 -8283 E0101; Hanyo-Denshi; JB5517 -8283 E0101; Moji_Joho; MJ021498 -8283 E0102; Hanyo-Denshi; KS342370 -8283 E0102; Moji_Joho; MJ021499 -8283 E0103; Hanyo-Denshi; JTB927 -8283 E0103; Moji_Joho; MJ021500 -8284 E0100; Adobe-Japan1; CID+19730 -8284 E0101; Hanyo-Denshi; JB5518 -8284 E0101; Moji_Joho; MJ021501 -8284 E0102; Hanyo-Denshi; KS342380 -8284 E0102; Moji_Joho; MJ021502 -8287 E0100; Adobe-Japan1; CID+22299 -8287 E0101; Hanyo-Denshi; JB5519 -8287 E0101; Moji_Joho; MJ021505 -8287 E0102; Hanyo-Denshi; KS342420 -8287 E0102; Moji_Joho; MJ021506 -8289 E0100; Adobe-Japan1; CID+19731 -8289 E0101; Hanyo-Denshi; JB5520 -8289 E0101; Moji_Joho; MJ021507 -8289 E0102; Hanyo-Denshi; KS342430 -8289 E0102; Moji_Joho; MJ021508 -828A E0100; Adobe-Japan1; CID+18471 -828A E0101; Hanyo-Denshi; JB5521 -828A E0101; Moji_Joho; MJ021509 -828A E0102; Hanyo-Denshi; JTB926S -828A E0102; Moji_Joho; MJ021510 -828B E0100; Adobe-Japan1; CID+1206 -828B E0101; Hanyo-Denshi; JA1682 -828B E0101; Moji_Joho; MJ021511 -828B E0102; Hanyo-Denshi; KS342450 -828B E0102; Moji_Joho; MJ021512 -828B E0103; Hanyo-Denshi; TK01076250 -828B E0104; Hanyo-Denshi; TK01076400 -828C E0100; Hanyo-Denshi; KS342460 -828C E0100; Moji_Joho; MJ021513 -828C E0101; Hanyo-Denshi; KS343030 -828C E0101; Moji_Joho; MJ021514 -828D E0100; Adobe-Japan1; CID+6324 -828D E0101; Adobe-Japan1; CID+7856 -828D E0102; Hanyo-Denshi; JA7173 -828D E0102; Moji_Joho; MJ021515 -828D E0103; Hanyo-Denshi; KS342490 -828D E0103; Moji_Joho; MJ021516 -828D E0104; Hanyo-Denshi; FT1981 -828D E0104; Moji_Joho; MJ021517 -828E E0100; Adobe-Japan1; CID+15043 -828E E0101; Hanyo-Denshi; JB5522 -828E E0101; Moji_Joho; MJ021518 -828E E0102; Hanyo-Denshi; JTB925 -828E E0102; Moji_Joho; MJ021519 -8291 E0100; Adobe-Japan1; CID+19732 -8291 E0101; Hanyo-Denshi; JB5523 -8291 E0101; Moji_Joho; MJ021522 -8291 E0102; Hanyo-Denshi; KS342560 -8291 E0102; Moji_Joho; MJ021524 -8292 E0100; Adobe-Japan1; CID+6325 -8292 E0101; Adobe-Japan1; CID+20292 -8292 E0102; Hanyo-Denshi; JA7174 -8292 E0102; Moji_Joho; MJ021525 -8292 E0103; Hanyo-Denshi; HG1664 -8292 E0103; Moji_Joho; MJ021527 -8292 E0104; Hanyo-Denshi; KS342570S -8292 E0104; Moji_Joho; MJ021526 -8293 E0100; Adobe-Japan1; CID+18472 -8293 E0101; Hanyo-Denshi; JD8592 -8293 E0101; Moji_Joho; MJ021528 -8293 E0102; Hanyo-Denshi; KS342590 -8293 E0102; Moji_Joho; MJ021529 -8294 E0100; Adobe-Japan1; CID+22300 -8294 E0101; Hanyo-Denshi; JB5524 -8294 E0101; Moji_Joho; MJ021530 -8294 E0102; Hanyo-Denshi; JTAE6B -8294 E0102; Moji_Joho; MJ021531 -8296 E0100; Adobe-Japan1; CID+22301 -8296 E0101; Hanyo-Denshi; JB5525 -8296 E0101; Moji_Joho; MJ021533 -8296 E0102; Hanyo-Denshi; JTB924 -8296 E0102; Moji_Joho; MJ021534 -8298 E0100; Adobe-Japan1; CID+22302 -8298 E0101; Hanyo-Denshi; JB5526 -8298 E0101; Moji_Joho; MJ021535 -8298 E0102; Hanyo-Denshi; KS343080 -8298 E0102; Moji_Joho; MJ021536 -8299 E0100; Adobe-Japan1; CID+3545 -8299 E0101; Hanyo-Denshi; JA4171 -8299 E0101; Moji_Joho; MJ021537 -8299 E0102; Hanyo-Denshi; JTB940 -8299 E0102; Moji_Joho; MJ021538 -829A E0100; Adobe-Japan1; CID+22303 -829A E0101; Hanyo-Denshi; JB5527 -829A E0101; Moji_Joho; MJ021540 -829A E0102; Hanyo-Denshi; KS343100 -829A E0102; Moji_Joho; MJ021539 -829B E0100; Adobe-Japan1; CID+22304 -829B E0101; Hanyo-Denshi; JB5528 -829B E0101; Moji_Joho; MJ021541 -829B E0102; Hanyo-Denshi; KS343110 -829B E0102; Moji_Joho; MJ021542 -829D E0100; Adobe-Japan1; CID+2291 -829D E0101; Hanyo-Denshi; JA2839 -829D E0101; Moji_Joho; MJ021544 -829D E0102; Hanyo-Denshi; JTB93B -829D E0102; Moji_Joho; MJ021545 -829F E0100; Adobe-Japan1; CID+6327 -829F E0101; Hanyo-Denshi; JA7176 -829F E0101; Moji_Joho; MJ021547 -829F E0102; Hanyo-Denshi; KS343160 -829F E0102; Moji_Joho; MJ021548 -82A0 E0100; Adobe-Japan1; CID+22305 -82A0 E0101; Hanyo-Denshi; JB5529 -82A0 E0101; Moji_Joho; MJ021550 -82A0 E0102; Hanyo-Denshi; JTB936 -82A0 E0102; Moji_Joho; MJ021549 -82A1 E0100; Adobe-Japan1; CID+17064 -82A1 E0101; Hanyo-Denshi; JB5530 -82A1 E0101; Moji_Joho; MJ021551 -82A1 E0102; Hanyo-Denshi; KS343200 -82A1 E0102; Moji_Joho; MJ021552 -82A2 E0100; Hanyo-Denshi; IP82A2 -82A2 E0101; Hanyo-Denshi; KS343210 -82A3 E0100; Adobe-Japan1; CID+17065 -82A3 E0101; Hanyo-Denshi; JB5531 -82A3 E0101; Moji_Joho; MJ021555 -82A3 E0102; Hanyo-Denshi; JTB941 -82A3 E0102; Moji_Joho; MJ021556 -82A4 E0100; Adobe-Japan1; CID+17066 -82A4 E0101; Hanyo-Denshi; JB5532 -82A4 E0101; Moji_Joho; MJ021557 -82A4 E0102; Hanyo-Denshi; KS343290 -82A4 E0102; Moji_Joho; MJ021558 -82A5 E0100; Adobe-Japan1; CID+1415 -82A5 E0101; Hanyo-Denshi; JA1909 -82A5 E0101; Moji_Joho; MJ021559 -82A5 E0102; Hanyo-Denshi; KS343300 -82A5 E0102; Moji_Joho; MJ021560 -82A6 E0100; Adobe-Japan1; CID+1142 -82A6 E0101; Adobe-Japan1; CID+7961 -82A6 E0102; Hanyo-Denshi; JA1618 -82A6 E0102; Moji_Joho; MJ021561 -82A6 E0103; Hanyo-Denshi; FT1751 -82A6 E0103; Moji_Joho; MJ021562 -82A6 E0104; Hanyo-Denshi; JTB92E -82A6 E0104; Moji_Joho; MJ021565 -82A6 E0105; Hanyo-Denshi; KS343310 -82A6 E0105; Moji_Joho; MJ021566 -82A6 E0106; Hanyo-Denshi; JTB92F -82A6 E0106; Moji_Joho; MJ021568 -82A6 E0107; Hanyo-Denshi; JTB92D -82A6 E0107; Moji_Joho; MJ021567 -82A6 E0108; Hanyo-Denshi; JTB92B -82A6 E0108; Moji_Joho; MJ021564 -82A6 E0109; Moji_Joho; MJ021563 -82A7 E0100; Adobe-Japan1; CID+18473 -82A7 E0101; Hanyo-Denshi; JB5533 -82A7 E0101; Moji_Joho; MJ021569 -82A7 E0102; Hanyo-Denshi; JTB93F -82A7 E0102; Moji_Joho; MJ021570 -82A8 E0100; Adobe-Japan1; CID+18474 -82A8 E0101; Hanyo-Denshi; JB5534 -82A8 E0101; Moji_Joho; MJ021572 -82A8 E0102; Hanyo-Denshi; JTB939 -82A8 E0102; Moji_Joho; MJ021571 -82A9 E0100; Adobe-Japan1; CID+17067 -82A9 E0101; Hanyo-Denshi; JB5535 -82A9 E0101; Moji_Joho; MJ021573 -82A9 E0102; Hanyo-Denshi; JTB93A -82A9 E0102; Moji_Joho; MJ021574 -82AA E0100; Adobe-Japan1; CID+19733 -82AA E0101; Hanyo-Denshi; JB5536 -82AA E0101; Moji_Joho; MJ021575 -82AA E0102; Hanyo-Denshi; KS343400 -82AA E0102; Moji_Joho; MJ021576 -82AB E0100; Adobe-Japan1; CID+6326 -82AB E0101; Hanyo-Denshi; JA7175 -82AB E0101; Moji_Joho; MJ021577 -82AB E0102; Hanyo-Denshi; KS343420 -82AB E0102; Moji_Joho; MJ021578 -82AC E0100; Adobe-Japan1; CID+6329 -82AC E0101; Hanyo-Denshi; JA7178 -82AC E0101; Moji_Joho; MJ021579 -82AC E0102; Hanyo-Denshi; KS343430 -82AC E0102; Moji_Joho; MJ021580 -82AC E0103; Hanyo-Denshi; FT2471 -82AC E0103; Moji_Joho; MJ021581 -82AD E0100; Adobe-Japan1; CID+3332 -82AD E0101; Hanyo-Denshi; JA3946 -82AD E0101; Moji_Joho; MJ021582 -82AD E0102; Hanyo-Denshi; KS343450 -82AD E0102; Moji_Joho; MJ021583 -82AE E0100; Adobe-Japan1; CID+15044 -82AE E0101; Hanyo-Denshi; JB5537 -82AE E0101; Moji_Joho; MJ021585 -82AE E0102; Hanyo-Denshi; JTB93D -82AE E0102; Moji_Joho; MJ021586 -82AE E0103; Hanyo-Denshi; JTB93E -82AE E0103; Moji_Joho; MJ021584 -82AF E0100; Adobe-Japan1; CID+2570 -82AF E0101; Hanyo-Denshi; JA3136 -82AF E0101; Moji_Joho; MJ021587 -82AF E0102; Hanyo-Denshi; KS343470 -82AF E0102; Moji_Joho; MJ021588 -82B0 E0100; Adobe-Japan1; CID+19734 -82B0 E0101; Hanyo-Denshi; JB5538 -82B0 E0101; Moji_Joho; MJ021590 -82B0 E0102; Hanyo-Denshi; JTB938 -82B0 E0102; Moji_Joho; MJ021589 -82B1 E0100; Adobe-Japan1; CID+1366 -82B1 E0101; Adobe-Japan1; CID+13666 -82B1 E0102; Hanyo-Denshi; JA1854 -82B1 E0102; Moji_Joho; MJ021591 -82B1 E0103; Hanyo-Denshi; JTB937S -82B1 E0103; Moji_Joho; MJ021592 -82B1 E0104; Hanyo-Denshi; JTB933 -82B1 E0104; Moji_Joho; MJ021593 -82B1 E0105; Hanyo-Denshi; TK01011530 -82B1 E0106; Moji_Joho; MJ021594 -82B2 E0100; Adobe-Japan1; CID+18475 -82B2 E0101; Hanyo-Denshi; JB5539 -82B2 E0101; Moji_Joho; MJ021597 -82B2 E0102; Hanyo-Denshi; KS343500 -82B2 E0102; Moji_Joho; MJ021596 -82B3 E0100; Adobe-Japan1; CID+3669 -82B3 E0101; Hanyo-Denshi; JA4307 -82B3 E0101; Moji_Joho; MJ021598 -82B3 E0102; Hanyo-Denshi; JTB942 -82B3 E0102; Moji_Joho; MJ021599 -82B4 E0100; Adobe-Japan1; CID+18476 -82B4 E0101; Hanyo-Denshi; JB5540 -82B4 E0101; Moji_Joho; MJ021600 -82B4 E0102; Hanyo-Denshi; KS343520 -82B4 E0102; Moji_Joho; MJ021601 -82B7 E0100; Adobe-Japan1; CID+15045 -82B7 E0101; Hanyo-Denshi; JB5541 -82B7 E0101; Moji_Joho; MJ021604 -82B7 E0102; Hanyo-Denshi; JTB93C -82B7 E0102; Moji_Joho; MJ021605 -82B8 E0100; Adobe-Japan1; CID+1843 -82B8 E0101; Hanyo-Denshi; JA2361 -82B8 E0101; Moji_Joho; MJ021606 -82B8 E0102; Hanyo-Denshi; JTB935 -82B8 E0102; Moji_Joho; MJ021607 -82B9 E0100; Adobe-Japan1; CID+1748 -82B9 E0101; Hanyo-Denshi; JA2260 -82B9 E0101; Moji_Joho; MJ021608 -82B9 E0102; Hanyo-Denshi; KS343570 -82B9 E0102; Moji_Joho; MJ021609 -82BA E0100; Adobe-Japan1; CID+18477 -82BA E0101; Hanyo-Denshi; JB5542 -82BA E0101; Moji_Joho; MJ021610 -82BA E0102; Hanyo-Denshi; KS343580 -82BA E0102; Moji_Joho; MJ021611 -82BB E0100; Adobe-Japan1; CID+6328 -82BC E0100; Adobe-Japan1; CID+18478 -82BC E0101; Hanyo-Denshi; JB5543 -82BC E0101; Moji_Joho; MJ021613 -82BC E0102; Hanyo-Denshi; JTB943S -82BC E0102; Moji_Joho; MJ021614 -82BD E0100; Adobe-Japan1; CID+13670 -82BD E0101; Adobe-Japan1; CID+1386 -82BD E0102; Adobe-Japan1; CID+13419 -82BD E0103; Hanyo-Denshi; JA1874 -82BD E0103; Moji_Joho; MJ021616 -82BD E0104; Hanyo-Denshi; KS343610 -82BD E0104; Moji_Joho; MJ021615 -82BD E0105; Hanyo-Denshi; TK01077090 -82BD E0106; Moji_Joho; MJ021617 -82BE E0100; Adobe-Japan1; CID+15046 -82BE E0101; Hanyo-Denshi; JB5544 -82BE E0101; Moji_Joho; MJ021618 -82BE E0102; Hanyo-Denshi; KS343620 -82BE E0102; Moji_Joho; MJ021619 -82BF E0100; Adobe-Japan1; CID+17068 -82BF E0101; Hanyo-Denshi; JB5545 -82BF E0101; Moji_Joho; MJ021620 -82BF E0102; Hanyo-Denshi; KS343630 -82BF E0102; Moji_Joho; MJ021621 -82C5 E0100; Adobe-Japan1; CID+1503 -82C5 E0101; Adobe-Japan1; CID+13687 -82C5 E0102; Hanyo-Denshi; JA2003 -82C5 E0102; Moji_Joho; MJ021627 -82C5 E0103; Hanyo-Denshi; JTB934 -82C5 E0103; Moji_Joho; MJ021628 -82C6 E0100; Adobe-Japan1; CID+15047 -82C6 E0101; Hanyo-Denshi; JB5546 -82C6 E0101; Moji_Joho; MJ021629 -82C6 E0102; Hanyo-Denshi; JTB944 -82C6 E0102; Moji_Joho; MJ021630 -82D0 E0100; Adobe-Japan1; CID+19735 -82D0 E0101; Hanyo-Denshi; JB5547 -82D0 E0101; Moji_Joho; MJ021632 -82D0 E0102; Hanyo-Denshi; KS344490 -82D0 E0102; Moji_Joho; MJ021633 -82D1 E0100; Adobe-Japan1; CID+1299 -82D1 E0101; Hanyo-Denshi; JA1781 -82D1 E0101; Moji_Joho; MJ021634 -82D1 E0102; Hanyo-Denshi; KS344470 -82D1 E0102; Moji_Joho; MJ021635 -82D1 E0103; Hanyo-Denshi; IB2785 -82D1 E0103; Moji_Joho; MJ021636 -82D2 E0100; Adobe-Japan1; CID+6333 -82D2 E0101; Adobe-Japan1; CID+7857 -82D2 E0102; Hanyo-Denshi; JA7182 -82D2 E0102; Moji_Joho; MJ021637 -82D2 E0103; Hanyo-Denshi; KS344520 -82D2 E0103; Moji_Joho; MJ021639 -82D2 E0104; Hanyo-Denshi; FT1982 -82D2 E0104; Moji_Joho; MJ021638 -82D3 E0100; Adobe-Japan1; CID+4018 -82D3 E0101; Hanyo-Denshi; JA4674 -82D3 E0101; Moji_Joho; MJ021640 -82D3 E0102; Hanyo-Denshi; KS344530 -82D3 E0102; Moji_Joho; MJ021641 -82D4 E0100; Adobe-Japan1; CID+2877 -82D4 E0101; Hanyo-Denshi; JA3461 -82D4 E0101; Moji_Joho; MJ021642 -82D4 E0102; Hanyo-Denshi; KS344540 -82D4 E0102; Moji_Joho; MJ021643 -82D5 E0100; Adobe-Japan1; CID+17069 -82D5 E0101; Hanyo-Denshi; JB5548 -82D5 E0101; Moji_Joho; MJ021644 -82D5 E0102; Hanyo-Denshi; KS344550 -82D5 E0102; Moji_Joho; MJ021645 -82D6 E0100; Hanyo-Denshi; IP82D6 -82D6 E0100; Moji_Joho; MJ021646 -82D6 E0101; Hanyo-Denshi; KS344560 -82D6 E0101; Moji_Joho; MJ021647 -82D7 E0100; Adobe-Japan1; CID+3510 -82D7 E0101; Hanyo-Denshi; JA4136 -82D7 E0101; Moji_Joho; MJ021648 -82D7 E0102; Hanyo-Denshi; JTB95B -82D7 E0102; Moji_Joho; MJ021649 -82D9 E0100; Adobe-Japan1; CID+6345 -82D9 E0101; Hanyo-Denshi; JA7194 -82D9 E0101; Moji_Joho; MJ021651 -82D9 E0102; Hanyo-Denshi; KS344590 -82D9 E0102; Moji_Joho; MJ021652 -82DA E0100; Adobe-Japan1; CID+22306 -82DA E0101; Hanyo-Denshi; JB5549 -82DA E0101; Moji_Joho; MJ021653 -82DA E0102; Hanyo-Denshi; KS344600 -82DA E0102; Moji_Joho; MJ021654 -82DB E0100; Adobe-Japan1; CID+1367 -82DB E0101; Hanyo-Denshi; JA1855 -82DB E0101; Moji_Joho; MJ021655 -82DB E0102; Hanyo-Denshi; KS344610 -82DB E0102; Moji_Joho; MJ021656 -82DC E0100; Adobe-Japan1; CID+6343 -82DC E0101; Hanyo-Denshi; JA7192 -82DC E0101; Moji_Joho; MJ021657 -82DC E0102; Hanyo-Denshi; KS344630 -82DC E0102; Moji_Joho; MJ021658 -82DE E0100; Adobe-Japan1; CID+6341 -82DE E0101; Hanyo-Denshi; JA7190 -82DE E0101; Moji_Joho; MJ021660 -82DE E0102; Hanyo-Denshi; KS344650 -82DE E0102; Moji_Joho; MJ021661 -82DE E0103; Hanyo-Denshi; FT2475 -82DE E0103; Moji_Joho; MJ021662 -82DF E0100; Adobe-Japan1; CID+6332 -82DF E0101; Hanyo-Denshi; JA7181 -82DF E0101; Moji_Joho; MJ021663 -82DF E0102; Hanyo-Denshi; KS344440 -82DF E0102; Moji_Joho; MJ021664 -82DF E0103; Hanyo-Denshi; KS344660 -82DF E0103; Moji_Joho; MJ021665 -82E0 E0100; Adobe-Japan1; CID+22307 -82E0 E0101; Hanyo-Denshi; JB5550 -82E0 E0101; Moji_Joho; MJ021666 -82E0 E0102; Hanyo-Denshi; KS344670 -82E0 E0102; Moji_Joho; MJ021667 -82E1 E0100; Adobe-Japan1; CID+6330 -82E1 E0101; Hanyo-Denshi; JA7179 -82E1 E0101; Moji_Joho; MJ021668 -82E1 E0102; Hanyo-Denshi; KS344680 -82E1 E0102; Moji_Joho; MJ021669 -82E2 E0100; Adobe-Japan1; CID+18479 -82E2 E0101; Hanyo-Denshi; JB5551 -82E2 E0101; Moji_Joho; MJ021670 -82E2 E0102; Hanyo-Denshi; KS344690 -82E2 E0102; Moji_Joho; MJ021671 -82E2 E0103; Hanyo-Denshi; KS346000 -82E2 E0103; Moji_Joho; MJ058449 -82E3 E0100; Adobe-Japan1; CID+6331 -82E3 E0101; Adobe-Japan1; CID+14200 -82E3 E0102; Hanyo-Denshi; JA7180 -82E3 E0102; Moji_Joho; MJ021672 -82E3 E0103; Hanyo-Denshi; KS344700 -82E3 E0103; Moji_Joho; MJ021673 -82E3 E0104; Hanyo-Denshi; JTB94DS -82E3 E0104; Moji_Joho; MJ021674 -82E4 E0100; Adobe-Japan1; CID+22308 -82E4 E0101; Hanyo-Denshi; JB5552 -82E4 E0101; Moji_Joho; MJ021675 -82E4 E0102; Hanyo-Denshi; KS344710 -82E4 E0102; Moji_Joho; MJ021676 -82E5 E0100; Adobe-Japan1; CID+2319 -82E5 E0101; Hanyo-Denshi; JA2867 -82E5 E0101; Moji_Joho; MJ021677 -82E5 E0102; Hanyo-Denshi; JTB949 -82E5 E0102; Moji_Joho; MJ021680 -82E5 E0103; Hanyo-Denshi; JTB948 -82E5 E0103; Moji_Joho; MJ021679 -82E6 E0100; Adobe-Japan1; CID+1764 -82E6 E0101; Hanyo-Denshi; JA2276 -82E6 E0101; Moji_Joho; MJ021681 -82E6 E0102; Hanyo-Denshi; KS344730 -82E6 E0102; Moji_Joho; MJ021682 -82E7 E0100; Adobe-Japan1; CID+2997 -82E7 E0101; Hanyo-Denshi; JA3587 -82E7 E0101; Moji_Joho; MJ021683 -82E7 E0102; Hanyo-Denshi; JTB954 -82E7 E0102; Moji_Joho; MJ021684 -82E8 E0100; Adobe-Japan1; CID+18480 -82E8 E0101; Hanyo-Denshi; JB5553 -82E8 E0101; Moji_Joho; MJ021685 -82E8 E0102; Hanyo-Denshi; KS344750 -82E8 E0102; Moji_Joho; MJ021686 -82EA E0100; Adobe-Japan1; CID+19736 -82EA E0101; Hanyo-Denshi; JB5554 -82EA E0101; Moji_Joho; MJ021688 -82EA E0102; Hanyo-Denshi; KS344770 -82EA E0102; Moji_Joho; MJ021689 -82EB E0100; Adobe-Japan1; CID+3241 -82EB E0101; Hanyo-Denshi; JA3849 -82EB E0101; Moji_Joho; MJ021690 -82EB E0102; Hanyo-Denshi; KS344780 -82EB E0102; Moji_Joho; MJ021691 -82ED E0100; Adobe-Japan1; CID+22309 -82ED E0101; Hanyo-Denshi; JB5555 -82ED E0101; Moji_Joho; MJ021693 -82ED E0102; Hanyo-Denshi; KS344800 -82ED E0102; Moji_Joho; MJ021694 -82EF E0100; Adobe-Japan1; CID+19737 -82EF E0101; Hanyo-Denshi; JB5556 -82EF E0101; Moji_Joho; MJ021696 -82EF E0102; Hanyo-Denshi; KS344820 -82EF E0102; Moji_Joho; MJ021697 -82EF E0103; Hanyo-Denshi; TK01076650 -82F1 E0100; Adobe-Japan1; CID+1267 -82F1 E0101; Hanyo-Denshi; JA1749 -82F1 E0101; Moji_Joho; MJ021700 -82F1 E0102; Hanyo-Denshi; JTB94E -82F1 E0102; Moji_Joho; MJ021702 -82F1 E0103; Hanyo-Denshi; JTB950 -82F1 E0103; Moji_Joho; MJ021703 -82F1 E0104; Hanyo-Denshi; IB2786 -82F1 E0104; Moji_Joho; MJ021701 -82F1 E0105; Hanyo-Denshi; TK01077010 -82F3 E0100; Adobe-Japan1; CID+6335 -82F3 E0101; Hanyo-Denshi; JA7184 -82F3 E0101; Moji_Joho; MJ021706 -82F3 E0102; Hanyo-Denshi; KS344870 -82F3 E0102; Moji_Joho; MJ021707 -82F3 E0103; Hanyo-Denshi; FT2472 -82F3 E0103; Moji_Joho; MJ021708 -82F4 E0100; Adobe-Japan1; CID+6334 -82F4 E0101; Hanyo-Denshi; JA7183 -82F4 E0101; Moji_Joho; MJ021709 -82F4 E0102; Hanyo-Denshi; KS344890 -82F4 E0102; Moji_Joho; MJ021710 -82F6 E0100; Adobe-Japan1; CID+19738 -82F6 E0101; Hanyo-Denshi; JB5557 -82F6 E0101; Moji_Joho; MJ021712 -82F6 E0102; Hanyo-Denshi; KS344940 -82F6 E0102; Moji_Joho; MJ021713 -82F7 E0100; Adobe-Japan1; CID+18481 -82F7 E0101; Hanyo-Denshi; JB5558 -82F7 E0101; Moji_Joho; MJ021714 -82F7 E0102; Hanyo-Denshi; KS344960 -82F7 E0102; Moji_Joho; MJ021715 -82F9 E0100; Adobe-Japan1; CID+6340 -82F9 E0101; Hanyo-Denshi; JA7189 -82F9 E0101; Moji_Joho; MJ021717 -82F9 E0102; Hanyo-Denshi; KS344990 -82F9 E0102; Moji_Joho; MJ021719 -82F9 E0103; Hanyo-Denshi; FT2474 -82F9 E0103; Moji_Joho; MJ021718 -82FA E0100; Adobe-Japan1; CID+6336 -82FA E0101; Hanyo-Denshi; JA7185 -82FA E0101; Moji_Joho; MJ021720 -82FA E0102; Hanyo-Denshi; KS345000 -82FA E0102; Moji_Joho; MJ021721 -82FB E0100; Adobe-Japan1; CID+6339 -82FB E0101; Hanyo-Denshi; JA7188 -82FB E0101; Moji_Joho; MJ021722 -82FB E0102; Hanyo-Denshi; KS345010 -82FB E0102; Moji_Joho; MJ021723 -82FC E0100; Hanyo-Denshi; KS345020 -82FC E0101; Hanyo-Denshi; TK01076930 -82FD E0100; Adobe-Japan1; CID+17070 -82FD E0101; Hanyo-Denshi; JB5559 -82FD E0101; Moji_Joho; MJ021727 -82FD E0102; Hanyo-Denshi; KS346070 -82FD E0102; Moji_Joho; MJ021728 -82FD E0103; Hanyo-Denshi; KS345030S -82FD E0103; Moji_Joho; MJ021726 -82FE E0100; Adobe-Japan1; CID+15048 -82FE E0101; Hanyo-Denshi; JB5560 -82FE E0101; Moji_Joho; MJ021729 -82FE E0102; Hanyo-Denshi; JTB95A -82FE E0102; Moji_Joho; MJ021730 -8300 E0100; Adobe-Japan1; CID+17071 -8300 E0101; Hanyo-Denshi; JB5561 -8300 E0101; Moji_Joho; MJ021732 -8300 E0102; Hanyo-Denshi; JTB95C -8300 E0102; Moji_Joho; MJ021733 -8301 E0100; Adobe-Japan1; CID+8600 -8301 E0101; Hanyo-Denshi; JB5562 -8301 E0101; Moji_Joho; MJ021734 -8301 E0102; Hanyo-Denshi; JTB957 -8301 E0102; Moji_Joho; MJ021735 -8302 E0100; Adobe-Japan1; CID+3804 -8302 E0101; Hanyo-Denshi; JA4448 -8302 E0101; Moji_Joho; MJ021736 -8302 E0102; Hanyo-Denshi; JTB95E -8302 E0102; Moji_Joho; MJ021738 -8302 E0103; Hanyo-Denshi; JTB95D -8302 E0103; Moji_Joho; MJ021737 -8303 E0100; Adobe-Japan1; CID+6338 -8303 E0101; Hanyo-Denshi; JA7187 -8303 E0101; Moji_Joho; MJ021739 -8303 E0102; Hanyo-Denshi; KS346060 -8303 E0102; Moji_Joho; MJ021741 -8303 E0103; Hanyo-Denshi; KS345100 -8303 E0103; Moji_Joho; MJ021740 -8303 E0104; Hanyo-Denshi; TK01076980 -8304 E0100; Adobe-Japan1; CID+1368 -8304 E0101; Hanyo-Denshi; JA1856 -8304 E0101; Moji_Joho; MJ021743 -8304 E0102; Hanyo-Denshi; KS345110 -8304 E0102; Moji_Joho; MJ021744 -8305 E0100; Adobe-Japan1; CID+1499 -8305 E0101; Hanyo-Denshi; JA1993 -8305 E0101; Moji_Joho; MJ021745 -8305 E0102; Hanyo-Denshi; KS345120 -8305 E0102; Moji_Joho; MJ021746 -8306 E0100; Adobe-Japan1; CID+6342 -8306 E0101; Hanyo-Denshi; JA7191 -8306 E0101; Moji_Joho; MJ021747 -8306 E0102; Hanyo-Denshi; KS345140 -8306 E0102; Moji_Joho; MJ021748 -8307 E0100; Adobe-Japan1; CID+18482 -8307 E0101; Hanyo-Denshi; JB5563 -8307 E0101; Moji_Joho; MJ021750 -8307 E0102; Hanyo-Denshi; JTB959 -8307 E0102; Moji_Joho; MJ021749 -8308 E0100; Adobe-Japan1; CID+18483 -8308 E0101; Hanyo-Denshi; JB5564 -8308 E0101; Moji_Joho; MJ021752 -8308 E0102; Hanyo-Denshi; JTB958 -8308 E0102; Moji_Joho; MJ021751 -8309 E0100; Adobe-Japan1; CID+6344 -8309 E0101; Hanyo-Denshi; JA7193 -8309 E0101; Moji_Joho; MJ021753 -8309 E0102; Hanyo-Denshi; KS345170 -8309 E0102; Moji_Joho; MJ021754 -830A E0100; Adobe-Japan1; CID+22310 -830A E0101; Hanyo-Denshi; JB5565 -830A E0101; Moji_Joho; MJ021756 -830A E0102; Hanyo-Denshi; KS345180 -830A E0102; Moji_Joho; MJ021755 -830B E0100; Adobe-Japan1; CID+22311 -830B E0101; Hanyo-Denshi; JB5566 -830B E0101; Moji_Joho; MJ021757 -830B E0102; Hanyo-Denshi; KS345210 -830B E0102; Moji_Joho; MJ021758 -830C E0100; Adobe-Japan1; CID+18484 -830C E0101; Hanyo-Denshi; JD8610 -830C E0101; Moji_Joho; MJ021759 -830C E0102; Hanyo-Denshi; KS345220 -830C E0102; Moji_Joho; MJ021760 -830C E0103; Hanyo-Denshi; TK01076870 -830E E0100; Adobe-Japan1; CID+1834 -8316 E0100; Adobe-Japan1; CID+6348 -8316 E0101; Hanyo-Denshi; JA7203 -8316 E0101; Moji_Joho; MJ021764 -8316 E0102; Hanyo-Denshi; KS346120 -8316 E0102; Moji_Joho; MJ021765 -8317 E0100; Adobe-Japan1; CID+6357 -8317 E0101; Hanyo-Denshi; JA7212 -8317 E0101; Moji_Joho; MJ021766 -8317 E0102; Hanyo-Denshi; KS346130 -8317 E0102; Moji_Joho; MJ021767 -8318 E0100; Adobe-Japan1; CID+6358 -8318 E0101; Hanyo-Denshi; JA7213 -8318 E0101; Moji_Joho; MJ021768 -8318 E0102; Hanyo-Denshi; KS346150 -8318 E0102; Moji_Joho; MJ021769 -831B E0100; Adobe-Japan1; CID+18486 -831B E0101; Hanyo-Denshi; JB5568 -831B E0101; Moji_Joho; MJ021772 -831B E0102; Hanyo-Denshi; JTB977 -831B E0102; Moji_Joho; MJ021773 -831C E0100; Adobe-Japan1; CID+1135 -831C E0101; Hanyo-Denshi; JA1611 -831C E0101; Moji_Joho; MJ021774 -831C E0102; Hanyo-Denshi; KS346190 -831C E0102; Moji_Joho; MJ021775 -831D E0100; Adobe-Japan1; CID+18487 -831D E0101; Hanyo-Denshi; JB5569 -831D E0101; Moji_Joho; MJ021776 -831D E0102; Hanyo-Denshi; KS346240 -831D E0102; Moji_Joho; MJ021777 -831E E0100; Adobe-Japan1; CID+22312 -831E E0101; Hanyo-Denshi; JB5570 -831E E0101; Moji_Joho; MJ021778 -831E E0102; Hanyo-Denshi; KS346250 -831E E0102; Moji_Joho; MJ021779 -831F E0100; Adobe-Japan1; CID+22313 -831F E0101; Hanyo-Denshi; JB5571 -831F E0101; Moji_Joho; MJ021780 -831F E0102; Hanyo-Denshi; KS346280 -831F E0102; Moji_Joho; MJ021781 -8321 E0100; Adobe-Japan1; CID+22314 -8321 E0101; Hanyo-Denshi; JB5572 -8321 E0101; Moji_Joho; MJ021783 -8321 E0102; Hanyo-Denshi; KS346310 -8321 E0102; Moji_Joho; MJ021784 -8322 E0100; Adobe-Japan1; CID+17072 -8322 E0101; Hanyo-Denshi; JB5573 -8322 E0101; Moji_Joho; MJ021785 -8322 E0102; Hanyo-Denshi; JTB983S -8322 E0102; Moji_Joho; MJ021786 -8323 E0100; Adobe-Japan1; CID+6365 -8323 E0101; Adobe-Japan1; CID+7858 -8323 E0102; Hanyo-Denshi; JA7220 -8323 E0102; Moji_Joho; MJ021788 -8323 E0103; Hanyo-Denshi; KS349190 -8323 E0103; Moji_Joho; MJ021790 -8323 E0104; Hanyo-Denshi; KS349080 -8323 E0104; Moji_Joho; MJ021789 -8323 E0105; Hanyo-Denshi; KS068120 -8323 E0105; Moji_Joho; MJ021787 -8323 E0106; Hanyo-Denshi; FT1983 -8323 E0106; Moji_Joho; MJ021791 -8324 E0100; Hanyo-Denshi; IP8324 -8324 E0101; Hanyo-Denshi; KS346380 -8325 E0100; Hanyo-Denshi; KS346390 -8325 E0101; Hanyo-Denshi; TK01079320 -8326 E0100; Hanyo-Denshi; IP8326 -8326 E0100; Moji_Joho; MJ021796 -8326 E0101; Hanyo-Denshi; KS346400 -8326 E0101; Moji_Joho; MJ021797 -8327 E0100; Hanyo-Denshi; IP8327 -8327 E0100; Moji_Joho; MJ021798 -8327 E0101; Hanyo-Denshi; KS346420 -8327 E0101; Moji_Joho; MJ021799 -8328 E0100; Adobe-Japan1; CID+1205 -8328 E0101; Adobe-Japan1; CID+7962 -8328 E0102; Hanyo-Denshi; JA1681 -8328 E0102; Moji_Joho; MJ021800 -8328 E0103; Hanyo-Denshi; HG1628 -8328 E0103; Moji_Joho; MJ021802 -8328 E0104; Hanyo-Denshi; KS346430 -8328 E0104; Moji_Joho; MJ021801 -8328 E0105; Hanyo-Denshi; TK01077600 -832A E0100; Hanyo-Denshi; KS346450 -832A E0101; Hanyo-Denshi; TK01079330 -832B E0100; Adobe-Japan1; CID+6356 -832B E0101; Hanyo-Denshi; JA7211 -832B E0101; Moji_Joho; MJ021808 -832B E0102; Hanyo-Denshi; KS346470 -832B E0102; Moji_Joho; MJ021809 -832B E0103; Hanyo-Denshi; FT2476 -832B E0103; Moji_Joho; MJ021810 -832C E0100; Adobe-Japan1; CID+22315 -832C E0101; Hanyo-Denshi; JB5574 -832C E0101; Moji_Joho; MJ021811 -832C E0102; Hanyo-Denshi; JTB975 -832C E0102; Moji_Joho; MJ021812 -832D E0100; Adobe-Japan1; CID+17073 -832D E0101; Hanyo-Denshi; JB5575 -832D E0101; Moji_Joho; MJ021814 -832D E0102; Hanyo-Denshi; JTB97D -832D E0102; Moji_Joho; MJ021813 -832E E0100; Adobe-Japan1; CID+22316 -832E E0101; Hanyo-Denshi; JB5576 -832E E0102; Hanyo-Denshi; KS346520 -832E E0102; Moji_Joho; MJ021816 -832E E0103; Moji_Joho; MJ021815 -832F E0100; Adobe-Japan1; CID+6355 -832F E0101; Hanyo-Denshi; JA7210 -832F E0101; Moji_Joho; MJ021817 -832F E0102; Hanyo-Denshi; KS346530 -832F E0102; Moji_Joho; MJ021818 -8330 E0100; Adobe-Japan1; CID+18488 -8330 E0101; Hanyo-Denshi; JB5577 -8330 E0101; Moji_Joho; MJ021822 -8330 E0102; Hanyo-Denshi; FT2483 -8330 E0102; Moji_Joho; MJ021823 -8330 E0103; Hanyo-Denshi; JTB968 -8330 E0103; Moji_Joho; MJ021819 -8330 E0104; Hanyo-Denshi; KS346550 -8330 E0104; Moji_Joho; MJ021821 -8330 E0105; Moji_Joho; MJ021820 -8331 E0100; Adobe-Japan1; CID+6350 -8331 E0101; Hanyo-Denshi; JA7205 -8331 E0101; Moji_Joho; MJ021824 -8331 E0102; Hanyo-Denshi; KS346570 -8331 E0102; Moji_Joho; MJ021825 -8332 E0100; Adobe-Japan1; CID+6349 -8332 E0101; Hanyo-Denshi; JA7204 -8332 E0101; Moji_Joho; MJ021826 -8332 E0102; Hanyo-Denshi; KS346580 -8332 E0102; Moji_Joho; MJ021827 -8333 E0100; Adobe-Japan1; CID+22317 -8333 E0101; Hanyo-Denshi; JB5578 -8333 E0101; Moji_Joho; MJ021828 -8333 E0102; Hanyo-Denshi; KS346590 -8333 E0102; Moji_Joho; MJ021829 -8334 E0100; Adobe-Japan1; CID+6347 -8334 E0101; Hanyo-Denshi; JA7202 -8334 E0101; Moji_Joho; MJ021830 -8334 E0102; Hanyo-Denshi; KS346600 -8334 E0102; Moji_Joho; MJ021831 -8335 E0100; Adobe-Japan1; CID+6346 -8335 E0101; Hanyo-Denshi; JA7201 -8335 E0101; Moji_Joho; MJ021832 -8335 E0102; Hanyo-Denshi; KS346610 -8335 E0102; Moji_Joho; MJ021833 -8336 E0100; Adobe-Japan1; CID+2977 -8336 E0101; Hanyo-Denshi; JA3567 -8336 E0101; Moji_Joho; MJ021834 -8336 E0102; Hanyo-Denshi; JTB980 -8336 E0102; Moji_Joho; MJ021835 -8337 E0100; Adobe-Japan1; CID+22318 -8337 E0101; Hanyo-Denshi; JB5579 -8337 E0101; Moji_Joho; MJ021836 -8337 E0102; Hanyo-Denshi; KS346630 -8337 E0102; Moji_Joho; MJ021837 -8338 E0100; Adobe-Japan1; CID+2907 -8338 E0101; Hanyo-Denshi; JA3491 -8338 E0101; Moji_Joho; MJ021838 -8338 E0102; Hanyo-Denshi; KS346650 -8338 E0102; Moji_Joho; MJ021839 -8338 E0103; Moji_Joho; MJ021840 -8339 E0100; Adobe-Japan1; CID+6352 -8339 E0101; Hanyo-Denshi; JA7207 -8339 E0101; Moji_Joho; MJ021841 -8339 E0102; Hanyo-Denshi; KS346680 -8339 E0102; Moji_Joho; MJ021842 -833A E0100; Adobe-Japan1; CID+17074 -833A E0101; Hanyo-Denshi; JB5580 -833A E0101; Moji_Joho; MJ021843 -833A E0102; Hanyo-Denshi; KS346690S -833A E0102; Moji_Joho; MJ021844 -833C E0100; Adobe-Japan1; CID+18489 -833C E0101; Hanyo-Denshi; JB5581 -833C E0101; Moji_Joho; MJ021846 -833C E0102; Hanyo-Denshi; KS346710 -833C E0102; Moji_Joho; MJ021847 -833D E0100; Adobe-Japan1; CID+22319 -833D E0101; Hanyo-Denshi; JB5582 -833D E0101; Moji_Joho; MJ021848 -833D E0102; Hanyo-Denshi; KS346720 -833D E0102; Moji_Joho; MJ021849 -8340 E0100; Adobe-Japan1; CID+6351 -8340 E0101; Hanyo-Denshi; JA7206 -8340 E0101; Moji_Joho; MJ021852 -8340 E0102; Hanyo-Denshi; KS346750 -8340 E0102; Moji_Joho; MJ021853 -8342 E0100; Adobe-Japan1; CID+22320 -8342 E0101; Hanyo-Denshi; JB5583 -8342 E0101; Moji_Joho; MJ021855 -8342 E0102; Hanyo-Denshi; KS346790 -8342 E0102; Moji_Joho; MJ021856 -8342 E0103; Hanyo-Denshi; KS347930 -8342 E0103; Moji_Joho; MJ021857 -8343 E0100; Adobe-Japan1; CID+15049 -8343 E0101; Hanyo-Denshi; JB5584 -8343 E0101; Moji_Joho; MJ021859 -8343 E0102; Hanyo-Denshi; KS346800 -8343 E0102; Moji_Joho; MJ021858 -8343 E0103; Hanyo-Denshi; JTB96E -8343 E0103; Moji_Joho; MJ021860 -8343 E0104; Hanyo-Denshi; JTB96F -8343 E0104; Moji_Joho; MJ021861 -8344 E0100; Adobe-Japan1; CID+18490 -8344 E0101; Hanyo-Denshi; JB5585 -8344 E0101; Moji_Joho; MJ021862 -8344 E0102; Hanyo-Denshi; KS347910 -8344 E0102; Moji_Joho; MJ021864 -8344 E0103; Hanyo-Denshi; KS346810 -8344 E0103; Moji_Joho; MJ021863 -8345 E0100; Adobe-Japan1; CID+6354 -8345 E0101; Hanyo-Denshi; JA7209 -8345 E0101; Moji_Joho; MJ021865 -8345 E0102; Hanyo-Denshi; KS346040 -8345 E0102; Moji_Joho; MJ021866 -8345 E0103; Hanyo-Denshi; KS346830 -8345 E0103; Moji_Joho; MJ021867 -8346 E0100; Adobe-Japan1; CID+7672 -8346 E0101; Hanyo-Denshi; FT1788 -8346 E0101; Moji_Joho; MJ021868 -8346 E0102; Hanyo-Denshi; JTAE26 -8346 E0102; Moji_Joho; MJ021870 -8346 E0103; Hanyo-Denshi; KS346850 -8346 E0103; Moji_Joho; MJ021869 -8346 E0104; Hanyo-Denshi; KS352060 -8346 E0104; Moji_Joho; MJ021871 -8347 E0100; Adobe-Japan1; CID+17075 -8347 E0101; Hanyo-Denshi; JB5586 -8347 E0101; Moji_Joho; MJ021872 -8347 E0102; Hanyo-Denshi; JTB97C -8347 E0102; Moji_Joho; MJ021873 -8349 E0100; Adobe-Japan1; CID+2802 -8349 E0101; Hanyo-Denshi; JA3380 -8349 E0101; Moji_Joho; MJ021875 -8349 E0102; Hanyo-Denshi; JTB97F -8349 E0102; Moji_Joho; MJ021876 -834A E0100; Adobe-Japan1; CID+1835 -834A E0101; Hanyo-Denshi; JA2353 -834A E0101; Moji_Joho; MJ021877 -834A E0102; Hanyo-Denshi; KS353100 -834A E0102; Moji_Joho; MJ021880 -834A E0103; Hanyo-Denshi; JTB97B -834A E0103; Moji_Joho; MJ021878 -834A E0104; Hanyo-Denshi; JTB9AB -834A E0104; Moji_Joho; MJ021879 -834B E0100; Hanyo-Denshi; IP834B -834B E0101; Hanyo-Denshi; KS346910 -834D E0100; Adobe-Japan1; CID+22321 -834D E0101; Hanyo-Denshi; JB5587 -834D E0101; Moji_Joho; MJ021885 -834D E0102; Hanyo-Denshi; KS346930 -834D E0102; Moji_Joho; MJ021886 -834E E0100; Adobe-Japan1; CID+22322 -834E E0101; Hanyo-Denshi; JB5588 -834E E0101; Moji_Joho; MJ021887 -834E E0102; Hanyo-Denshi; KS346940 -834E E0102; Moji_Joho; MJ021888 -834F E0100; Adobe-Japan1; CID+1251 -834F E0101; Hanyo-Denshi; JA1733 -834F E0101; Moji_Joho; MJ021889 -834F E0102; Hanyo-Denshi; KS346950 -834F E0102; Moji_Joho; MJ021890 -834F E0103; Hanyo-Denshi; JTB97E -834F E0103; Moji_Joho; MJ021891 -8350 E0100; Adobe-Japan1; CID+6353 -8350 E0101; Hanyo-Denshi; JA7208 -8350 E0101; Moji_Joho; MJ021892 -8350 E0102; Hanyo-Denshi; KS346960 -8350 E0102; Moji_Joho; MJ021893 -8351 E0100; Adobe-Japan1; CID+15050 -8351 E0101; Hanyo-Denshi; JB5589 -8351 E0101; Moji_Joho; MJ021894 -8351 E0102; Hanyo-Denshi; KS346970 -8351 E0102; Moji_Joho; MJ021895 -8351 E0103; Hanyo-Denshi; JTB981 -8351 E0103; Moji_Joho; MJ021896 -8352 E0100; Adobe-Japan1; CID+2021 -8352 E0101; Adobe-Japan1; CID+13772 -8352 E0102; Hanyo-Denshi; JA2551 -8352 E0102; Moji_Joho; MJ021897 -8352 E0103; Hanyo-Denshi; KS346980 -8352 E0103; Moji_Joho; MJ021898 -8352 E0104; Hanyo-Denshi; JTB964 -8352 E0104; Moji_Joho; MJ021899 -8352 E0105; Hanyo-Denshi; JTB95F -8352 E0105; Moji_Joho; MJ060100 -8352 E0106; Hanyo-Denshi; JTB985S -8352 E0106; Moji_Joho; MJ058459 -8352 E0107; Hanyo-Denshi; JTB987S -8352 E0107; Moji_Joho; MJ060106 -8352 E0108; Hanyo-Denshi; JTC0CDS -8352 E0108; Moji_Joho; MJ060384 -8353 E0100; Adobe-Japan1; CID+22332 -8353 E0101; Hanyo-Denshi; JB5630 -8353 E0101; Moji_Joho; MJ021902 -8353 E0102; Hanyo-Denshi; KS347050 -8353 E0102; Moji_Joho; MJ021900 -8353 E0103; Hanyo-Denshi; KS347940 -8353 E0103; Moji_Joho; MJ021901 -8353 E0104; Hanyo-Denshi; KS350930 -8353 E0104; Moji_Joho; MJ021903 -8354 E0100; Adobe-Japan1; CID+18485 -8354 E0101; Hanyo-Denshi; JB5567 -8354 E0101; Moji_Joho; MJ021904 -8354 E0102; Hanyo-Denshi; JTB982 -8354 E0102; Moji_Joho; MJ021905 -8355 E0100; Adobe-Japan1; CID+15051 -8355 E0101; Hanyo-Denshi; JB5590 -8355 E0101; Moji_Joho; MJ021906 -8355 E0102; Hanyo-Denshi; JTB978 -8355 E0102; Moji_Joho; MJ021907 -8356 E0100; Adobe-Japan1; CID+19739 -8356 E0101; Hanyo-Denshi; JB5591 -8356 E0101; Moji_Joho; MJ021908 -8356 E0102; Hanyo-Denshi; KS347150 -8356 E0102; Moji_Joho; MJ021909 -8357 E0100; Adobe-Japan1; CID+18491 -8357 E0101; Hanyo-Denshi; JB5592 -8357 E0101; Moji_Joho; MJ021910 -8357 E0102; Hanyo-Denshi; KS347200 -8357 E0102; Moji_Joho; MJ021911 -8357 E0103; Hanyo-Denshi; TK01077970 -8358 E0100; Adobe-Japan1; CID+2803 -8358 E0101; Hanyo-Denshi; JA3381 -8358 E0102; Hanyo-Denshi; TK01077530 -835A E0100; Adobe-Japan1; CID+14202 -8362 E0100; Adobe-Japan1; CID+8601 -8362 E0101; Hanyo-Denshi; JC9077 -8362 E0101; Moji_Joho; MJ021917 -8362 E0102; Hanyo-Denshi; JTB96A -8362 E0102; Moji_Joho; MJ021915 -8362 E0103; Hanyo-Denshi; JTB979 -8362 E0103; Moji_Joho; MJ021916 -8362 E0104; Hanyo-Denshi; TK01077630 -8363 E0100; Adobe-Japan1; CID+17775 -8370 E0100; Adobe-Japan1; CID+22323 -8370 E0101; Hanyo-Denshi; JB5593 -8370 E0101; Moji_Joho; MJ021920 -8370 E0102; Hanyo-Denshi; KS348020 -8370 E0102; Moji_Joho; MJ021921 -8370 E0103; Hanyo-Denshi; TK01078150 -8372 E0100; Hanyo-Denshi; IP8372 -8372 E0101; Hanyo-Denshi; KS348060 -8373 E0100; Adobe-Japan1; CID+6371 -8373 E0101; Hanyo-Denshi; JA7226 -8373 E0101; Moji_Joho; MJ021926 -8373 E0102; Hanyo-Denshi; KS348070 -8373 E0102; Moji_Joho; MJ021927 -8375 E0100; Adobe-Japan1; CID+6372 -8375 E0101; Adobe-Japan1; CID+7859 -8375 E0102; Hanyo-Denshi; JA7227 -8375 E0102; Moji_Joho; MJ021929 -8375 E0103; Hanyo-Denshi; KS348120 -8375 E0103; Moji_Joho; MJ021931 -8375 E0104; Hanyo-Denshi; JTB98C -8375 E0104; Moji_Joho; MJ021932 -8375 E0105; Hanyo-Denshi; FT1984 -8375 E0105; Moji_Joho; MJ021930 -8377 E0100; Adobe-Japan1; CID+1369 -8377 E0101; Hanyo-Denshi; JA1857 -8377 E0101; Moji_Joho; MJ021934 -8377 E0102; Hanyo-Denshi; KS348180 -8377 E0102; Moji_Joho; MJ021935 -8378 E0100; Adobe-Japan1; CID+19740 -8378 E0101; Hanyo-Denshi; JB5594 -8378 E0101; Moji_Joho; MJ021936 -8378 E0102; Hanyo-Denshi; KS348190 -8378 E0102; Moji_Joho; MJ021937 -837B E0100; Adobe-Japan1; CID+1326 -837B E0101; Hanyo-Denshi; JA1814 -837B E0101; Moji_Joho; MJ021940 -837B E0102; Hanyo-Denshi; JTB99D -837B E0102; Moji_Joho; MJ021942 -837B E0103; Hanyo-Denshi; JTB99C -837B E0103; Moji_Joho; MJ021941 -837C E0100; Adobe-Japan1; CID+6369 -837C E0101; Hanyo-Denshi; JA7224 -837C E0101; Moji_Joho; MJ021943 -837C E0102; Hanyo-Denshi; KS348260 -837C E0102; Moji_Joho; MJ021944 -837D E0100; Adobe-Japan1; CID+17076 -837D E0101; Hanyo-Denshi; JB5601 -837D E0101; Moji_Joho; MJ021945 -837D E0102; Hanyo-Denshi; KS348270 -837D E0102; Moji_Joho; MJ021946 -837E E0100; Hanyo-Denshi; KS348280 -837E E0100; Moji_Joho; MJ021947 -837E E0101; Hanyo-Denshi; KS350300 -837E E0101; Moji_Joho; MJ021948 -837F E0100; Adobe-Japan1; CID+8602 -837F E0101; Hanyo-Denshi; JB5602 -837F E0101; Moji_Joho; MJ021952 -837F E0102; Hanyo-Denshi; KS348290 -837F E0102; Moji_Joho; MJ021951 -837F E0103; Hanyo-Denshi; JTB96D -837F E0103; Moji_Joho; MJ021950 -837F E0104; Hanyo-Denshi; IB2791 -837F E0104; Moji_Joho; MJ021953 -837F E0105; Moji_Joho; MJ021949 -8380 E0100; Adobe-Japan1; CID+22324 -8380 E0101; Hanyo-Denshi; JB5603 -8380 E0101; Moji_Joho; MJ021954 -8380 E0102; Hanyo-Denshi; KS348300 -8380 E0102; Moji_Joho; MJ021955 -8382 E0100; Adobe-Japan1; CID+22325 -8382 E0101; Hanyo-Denshi; JB5604 -8382 E0101; Moji_Joho; MJ021957 -8382 E0102; Hanyo-Denshi; KS348350 -8382 E0102; Moji_Joho; MJ021958 -8384 E0100; Adobe-Japan1; CID+22326 -8384 E0101; Hanyo-Denshi; JB5605 -8384 E0101; Moji_Joho; MJ021960 -8384 E0102; Hanyo-Denshi; KS348410 -8384 E0102; Moji_Joho; MJ021961 -8385 E0100; Adobe-Japan1; CID+6359 -8385 E0101; Hanyo-Denshi; JA7214 -8385 E0101; Moji_Joho; MJ021962 -8385 E0102; Hanyo-Denshi; KS348420 -8385 E0102; Moji_Joho; MJ021963 -8386 E0100; Adobe-Japan1; CID+15052 -8386 E0101; Hanyo-Denshi; JB5606 -8386 E0101; Moji_Joho; MJ021964 -8386 E0102; Hanyo-Denshi; KS348430 -8386 E0102; Moji_Joho; MJ021965 -8387 E0100; Adobe-Japan1; CID+6367 -8387 E0101; Hanyo-Denshi; JA7222 -8387 E0101; Moji_Joho; MJ021966 -8387 E0102; Hanyo-Denshi; KS348440 -8387 E0102; Moji_Joho; MJ021967 -8389 E0100; Adobe-Japan1; CID+6374 -8389 E0101; Hanyo-Denshi; JA7229 -8389 E0101; Moji_Joho; MJ021969 -8389 E0102; Hanyo-Denshi; KS348520 -8389 E0102; Moji_Joho; MJ021970 -838A E0100; Adobe-Japan1; CID+6368 -838A E0101; Hanyo-Denshi; JA7223 -838A E0101; Moji_Joho; MJ021972 -838A E0102; Hanyo-Denshi; JTB99E -838A E0102; Moji_Joho; MJ021971 -838B E0100; Hanyo-Denshi; KS348540 -838B E0101; Hanyo-Denshi; TK01077950 -838D E0100; Adobe-Japan1; CID+15053 -838D E0101; Hanyo-Denshi; JB5607 -838D E0101; Moji_Joho; MJ021976 -838D E0102; Hanyo-Denshi; KS348570 -838D E0102; Moji_Joho; MJ021977 -838E E0100; Adobe-Japan1; CID+6366 -838E E0101; Hanyo-Denshi; JA7221 -838E E0101; Moji_Joho; MJ021978 -838E E0102; Hanyo-Denshi; KS348580 -838E E0102; Moji_Joho; MJ021979 -8391 E0100; Hanyo-Denshi; IP8391 -8391 E0100; Moji_Joho; MJ021982 -8391 E0101; Hanyo-Denshi; KS348630 -8391 E0101; Moji_Joho; MJ021983 -8392 E0100; Adobe-Japan1; CID+15054 -8392 E0101; Hanyo-Denshi; JB5608 -8392 E0101; Moji_Joho; MJ021984 -8392 E0102; Hanyo-Denshi; JTB9A0 -8392 E0102; Moji_Joho; MJ021985 -8393 E0100; Adobe-Japan1; CID+6337 -8393 E0101; Hanyo-Denshi; JA7186 -8393 E0101; Moji_Joho; MJ021986 -8393 E0102; Hanyo-Denshi; KS348650 -8393 E0102; Moji_Joho; MJ021987 -8393 E0103; Hanyo-Denshi; FT2473 -8393 E0103; Moji_Joho; MJ021988 -8394 E0100; Adobe-Japan1; CID+18495 -8394 E0101; Hanyo-Denshi; JB5609 -8394 E0101; Moji_Joho; MJ021989 -8394 E0102; Hanyo-Denshi; KS348660 -8394 E0102; Moji_Joho; MJ021990 -8395 E0100; Adobe-Japan1; CID+18496 -8395 E0101; Hanyo-Denshi; JB5610 -8395 E0101; Moji_Joho; MJ021991 -8395 E0102; Hanyo-Denshi; KS348680 -8395 E0102; Moji_Joho; MJ021992 -8396 E0100; Adobe-Japan1; CID+6364 -8396 E0101; Hanyo-Denshi; JA7219 -8396 E0101; Moji_Joho; MJ021993 -8396 E0102; Hanyo-Denshi; JTB999 -8396 E0102; Moji_Joho; MJ021995 -8396 E0103; Hanyo-Denshi; KS348700 -8396 E0103; Moji_Joho; MJ021994 -8398 E0100; Adobe-Japan1; CID+15055 -8398 E0101; Hanyo-Denshi; JB5611 -8398 E0101; Moji_Joho; MJ021997 -8398 E0102; Hanyo-Denshi; JTB9A2 -8398 E0102; Moji_Joho; MJ021998 -8399 E0100; Adobe-Japan1; CID+22327 -8399 E0101; Hanyo-Denshi; JB5612 -8399 E0101; Moji_Joho; MJ021999 -8399 E0102; Hanyo-Denshi; KS348750 -8399 E0102; Moji_Joho; MJ022000 -839A E0100; Adobe-Japan1; CID+6360 -839A E0101; Hanyo-Denshi; JA7215 -839A E0101; Moji_Joho; MJ022001 -839A E0102; Hanyo-Denshi; FT2477 -839A E0102; Moji_Joho; MJ022003 -839A E0103; Hanyo-Denshi; KS348770 -839A E0103; Moji_Joho; MJ022002 -839B E0100; Adobe-Japan1; CID+18497 -839B E0101; Hanyo-Denshi; JB5613 -839B E0102; Hanyo-Denshi; JTB98F -839B E0102; Moji_Joho; MJ022006 -839B E0103; Hanyo-Denshi; KS348780 -839B E0103; Moji_Joho; MJ022004 -839C E0100; Adobe-Japan1; CID+22328 -839C E0101; Hanyo-Denshi; JB5614 -839C E0101; Moji_Joho; MJ022007 -839C E0102; Hanyo-Denshi; KS348790 -839C E0102; Moji_Joho; MJ022008 -839D E0100; Adobe-Japan1; CID+18498 -839D E0101; Hanyo-Denshi; JB5615 -839D E0101; Moji_Joho; MJ022009 -839D E0102; Hanyo-Denshi; JTB9A1 -839D E0102; Moji_Joho; MJ022010 -839E E0100; Adobe-Japan1; CID+1548 -839E E0101; Hanyo-Denshi; JA2048 -839E E0101; Moji_Joho; MJ022011 -839E E0102; Hanyo-Denshi; JTB9A4 -839E E0102; Moji_Joho; MJ022012 -839F E0100; Adobe-Japan1; CID+6362 -839F E0101; Hanyo-Denshi; JA7217 -839F E0101; Moji_Joho; MJ022013 -839F E0102; Hanyo-Denshi; IB0354 -839F E0102; Moji_Joho; MJ022014 -83A0 E0100; Adobe-Japan1; CID+6373 -83A0 E0101; Hanyo-Denshi; JA7228 -83A0 E0101; Moji_Joho; MJ022015 -83A0 E0102; Hanyo-Denshi; KS348830 -83A0 E0102; Moji_Joho; MJ022016 -83A2 E0100; Adobe-Japan1; CID+6363 -83A2 E0101; Hanyo-Denshi; JA7218 -83A2 E0101; Moji_Joho; MJ022018 -83A2 E0102; Hanyo-Denshi; KS348870 -83A2 E0102; Moji_Joho; MJ022019 -83A4 E0100; Hanyo-Denshi; IP83A4 -83A4 E0100; Moji_Joho; MJ022021 -83A4 E0101; Hanyo-Denshi; KS348890 -83A4 E0101; Moji_Joho; MJ022022 -83A6 E0100; Adobe-Japan1; CID+22329 -83A6 E0101; Hanyo-Denshi; JB5616 -83A6 E0101; Moji_Joho; MJ022024 -83A6 E0102; Hanyo-Denshi; KS348910 -83A6 E0102; Moji_Joho; MJ022025 -83A7 E0100; Adobe-Japan1; CID+17077 -83A7 E0101; Hanyo-Denshi; JB5617 -83A7 E0101; Moji_Joho; MJ022026 -83A7 E0102; Hanyo-Denshi; JTB99FS -83A7 E0102; Moji_Joho; MJ022027 -83A8 E0100; Adobe-Japan1; CID+6375 -83A8 E0101; Hanyo-Denshi; JA7230 -83A8 E0101; Moji_Joho; MJ022028 -83A8 E0102; Hanyo-Denshi; KS348930 -83A8 E0102; Moji_Joho; MJ022029 -83A9 E0100; Adobe-Japan1; CID+15056 -83A9 E0101; Hanyo-Denshi; JB5618 -83A9 E0101; Moji_Joho; MJ022030 -83A9 E0102; Hanyo-Denshi; JTB9A3 -83A9 E0102; Moji_Joho; MJ022031 -83AA E0100; Adobe-Japan1; CID+6361 -83AA E0101; Hanyo-Denshi; JA7216 -83AA E0101; Moji_Joho; MJ022032 -83AA E0102; Hanyo-Denshi; KS348950 -83AA E0102; Moji_Joho; MJ022033 -83AB E0100; Adobe-Japan1; CID+3378 -83AB E0101; Hanyo-Denshi; JA3992 -83AB E0101; Moji_Joho; MJ022034 -83AB E0102; Hanyo-Denshi; KS348960S -83AB E0102; Moji_Joho; MJ022035 -83AC E0100; Adobe-Japan1; CID+22330 -83AC E0101; Hanyo-Denshi; JB5619 -83AC E0101; Moji_Joho; MJ022036 -83AC E0102; Hanyo-Denshi; KS349020 -83AC E0102; Moji_Joho; MJ022037 -83AD E0100; Adobe-Japan1; CID+22335 -83AD E0101; Hanyo-Denshi; JB5644 -83AD E0101; Moji_Joho; MJ022038 -83AD E0102; Hanyo-Denshi; JTB994 -83AD E0102; Moji_Joho; MJ022040 -83AD E0103; Hanyo-Denshi; KS353270 -83AD E0103; Moji_Joho; MJ022039 -83AD E0104; Hanyo-Denshi; TK01078020 -83B1 E0100; Adobe-Japan1; CID+3923 -83B5 E0100; Adobe-Japan1; CID+6370 -83B5 E0101; Hanyo-Denshi; JA7225 -83B5 E0101; Moji_Joho; MJ022046 -83B5 E0102; Hanyo-Denshi; KS350290 -83B5 E0102; Moji_Joho; MJ022048 -83B5 E0103; Hanyo-Denshi; KS350250 -83B5 E0103; Moji_Joho; MJ022047 -83BD E0100; Adobe-Japan1; CID+6392 -83BD E0101; Adobe-Japan1; CID+14204 -83BD E0102; Hanyo-Denshi; JA7247 -83BD E0102; Moji_Joho; MJ022050 -83BD E0103; Hanyo-Denshi; KS353220 -83BD E0103; Moji_Joho; MJ022052 -83BD E0104; Hanyo-Denshi; KS350310 -83BD E0104; Moji_Joho; MJ022051 -83BD E0105; Hanyo-Denshi; JTB9AF -83BD E0105; Moji_Joho; MJ022054 -83BD E0106; Hanyo-Denshi; JTB993 -83BD E0106; Moji_Joho; MJ022053 -83BD E0107; Hanyo-Denshi; KS347960 -83BD E0107; Moji_Joho; MJ058462 -83BE E0100; Adobe-Japan1; CID+22331 -83BE E0101; Hanyo-Denshi; JB5620 -83BE E0101; Moji_Joho; MJ022055 -83BE E0102; Hanyo-Denshi; KS350350 -83BE E0102; Moji_Joho; MJ022056 -83BF E0100; Adobe-Japan1; CID+15057 -83BF E0101; Hanyo-Denshi; JB5621 -83BF E0101; Moji_Joho; MJ022057 -83BF E0102; Hanyo-Denshi; JTB9C8 -83BF E0102; Moji_Joho; MJ022058 -83C0 E0100; Adobe-Japan1; CID+15058 -83C0 E0101; Hanyo-Denshi; JB5622 -83C0 E0101; Moji_Joho; MJ022059 -83C0 E0102; Hanyo-Denshi; KS350380 -83C0 E0102; Moji_Joho; MJ022060 -83C1 E0100; Adobe-Japan1; CID+6384 -83C1 E0101; Hanyo-Denshi; JA7239 -83C1 E0101; Moji_Joho; MJ022061 -83C1 E0102; Hanyo-Denshi; JTB9A6 -83C1 E0102; Moji_Joho; MJ022064 -83C1 E0103; Hanyo-Denshi; IB0355 -83C1 E0103; Moji_Joho; MJ022063 -83C1 E0104; Hanyo-Denshi; FT2479 -83C1 E0104; Moji_Joho; MJ022062 -83C1 E0105; Hanyo-Denshi; TK01078230 -83C2 E0100; Hanyo-Denshi; KS350410 -83C2 E0101; Hanyo-Denshi; TK01078690 -83C5 E0100; Adobe-Japan1; CID+2625 -83C5 E0101; Hanyo-Denshi; JA3191 -83C5 E0101; Moji_Joho; MJ022070 -83C5 E0102; Hanyo-Denshi; JTB9C4 -83C5 E0102; Moji_Joho; MJ022071 -83C6 E0100; Hanyo-Denshi; IP83C6 -83C6 E0100; Moji_Joho; MJ022072 -83C6 E0101; Hanyo-Denshi; JTB9D0 -83C6 E0101; Moji_Joho; MJ022074 -83C6 E0102; Hanyo-Denshi; KS350490 -83C6 E0102; Moji_Joho; MJ022073 -83C7 E0100; Adobe-Japan1; CID+8603 -83C7 E0101; Hanyo-Denshi; JB5623 -83C7 E0101; Moji_Joho; MJ022075 -83C7 E0102; Hanyo-Denshi; JTB9CF -83C7 E0102; Moji_Joho; MJ022076 -83C9 E0100; Adobe-Japan1; CID+18499 -83C9 E0101; Hanyo-Denshi; JB5624 -83C9 E0101; Moji_Joho; MJ022078 -83C9 E0102; Hanyo-Denshi; KS353200 -83C9 E0102; Moji_Joho; MJ022079 -83CA E0100; Adobe-Japan1; CID+1632 -83CA E0101; Hanyo-Denshi; JA2138 -83CA E0101; Moji_Joho; MJ022080 -83CA E0102; Hanyo-Denshi; JTB9CE -83CA E0102; Moji_Joho; MJ022081 -83CC E0100; Adobe-Japan1; CID+1749 -83CC E0101; Hanyo-Denshi; JA2261 -83CC E0101; Moji_Joho; MJ022083 -83CC E0102; Hanyo-Denshi; KS350580 -83CC E0102; Moji_Joho; MJ022084 -83CE E0100; Adobe-Japan1; CID+6379 -83CE E0101; Hanyo-Denshi; JA7234 -83CE E0101; Moji_Joho; MJ022086 -83CE E0102; Hanyo-Denshi; KS350620 -83CE E0102; Moji_Joho; MJ022087 -83CF E0100; Adobe-Japan1; CID+17078 -83CF E0101; Hanyo-Denshi; JB5625 -83CF E0101; Moji_Joho; MJ022088 -83CF E0102; Hanyo-Denshi; KS350640 -83CF E0102; Moji_Joho; MJ022089 -83D0 E0100; Adobe-Japan1; CID+18500 -83D1 E0100; Adobe-Japan1; CID+17079 -83D1 E0101; Hanyo-Denshi; JB5627 -83D1 E0101; Moji_Joho; MJ022091 -83D1 E0102; Hanyo-Denshi; KS350680 -83D1 E0102; Moji_Joho; MJ022092 -83D2 E0100; Hanyo-Denshi; IP83D2 -83D2 E0100; Moji_Joho; MJ022093 -83D2 E0101; Hanyo-Denshi; KS350690 -83D2 E0101; Moji_Joho; MJ022094 -83D3 E0100; Adobe-Japan1; CID+1371 -83D3 E0101; Adobe-Japan1; CID+13667 -83D3 E0102; Hanyo-Denshi; JA1859 -83D3 E0102; Moji_Joho; MJ022095 -83D3 E0103; Hanyo-Denshi; KS350700 -83D3 E0103; Moji_Joho; MJ022096 -83D4 E0100; Adobe-Japan1; CID+18501 -83D4 E0101; Adobe-Japan1; CID+20202 -83D4 E0102; Hanyo-Denshi; JB5628 -83D4 E0102; Moji_Joho; MJ022098 -83D4 E0103; Hanyo-Denshi; KS350720 -83D4 E0103; Moji_Joho; MJ022097 -83D6 E0100; Adobe-Japan1; CID+2492 -83D6 E0101; Hanyo-Denshi; JA3052 -83D6 E0101; Moji_Joho; MJ022100 -83D6 E0102; Hanyo-Denshi; KS350760 -83D6 E0102; Moji_Joho; MJ022101 -83D8 E0100; Adobe-Japan1; CID+6382 -83D8 E0101; Hanyo-Denshi; JA7237 -83D8 E0101; Moji_Joho; MJ022103 -83D8 E0102; Hanyo-Denshi; KS350790 -83D8 E0102; Moji_Joho; MJ022104 -83D8 E0103; Hanyo-Denshi; FT2478 -83D8 E0103; Moji_Joho; MJ022105 -83DC E0100; Adobe-Japan1; CID+2122 -83DC E0101; Adobe-Japan1; CID+13786 -83DC E0102; Hanyo-Denshi; JA2658 -83DC E0102; Moji_Joho; MJ022109 -83DC E0103; Hanyo-Denshi; KS350860 -83DC E0103; Moji_Joho; MJ022110 -83DC E0104; Hanyo-Denshi; JTB9B0 -83DC E0104; Moji_Joho; MJ022111 -83DC E0105; Hanyo-Denshi; TK01078810 -83DD E0100; Adobe-Japan1; CID+18502 -83DD E0101; Hanyo-Denshi; JB5629 -83DD E0101; Moji_Joho; MJ022113 -83DD E0102; Hanyo-Denshi; KS350870 -83DD E0102; Moji_Joho; MJ022114 -83DF E0100; Adobe-Japan1; CID+3147 -83DF E0101; Adobe-Japan1; CID+7755 -83DF E0102; Adobe-Japan1; CID+7976 -83DF E0103; Adobe-Japan1; CID+20201 -83DF E0104; Hanyo-Denshi; JA3749 -83DF E0104; Moji_Joho; MJ022116 -83DF E0105; Hanyo-Denshi; KS353180 -83DF E0105; Moji_Joho; MJ022120 -83DF E0106; Hanyo-Denshi; JTB9B3S -83DF E0106; Moji_Joho; MJ022118 -83DF E0107; Hanyo-Denshi; JTB9B2S -83DF E0107; Moji_Joho; MJ022121 -83DF E0108; Hanyo-Denshi; JTB9E4S -83DF E0108; Moji_Joho; MJ022119 -83DF E0109; Hanyo-Denshi; KS350900S -83DF E0109; Moji_Joho; MJ022117 -83DF E010A; Hanyo-Denshi; FT1875 -83DF E010A; Moji_Joho; MJ022122 -83DF E010B; Hanyo-Denshi; JTB9E0 -83DF E010B; Moji_Joho; MJ022124 -83DF E010C; Hanyo-Denshi; JTB9E1S -83DF E010C; Moji_Joho; MJ022125 -83E0 E0100; Adobe-Japan1; CID+6387 -83E0 E0101; Hanyo-Denshi; JA7242 -83E0 E0101; Moji_Joho; MJ022126 -83E0 E0102; Hanyo-Denshi; KS350910 -83E0 E0102; Moji_Joho; MJ022127 -83E1 E0100; Adobe-Japan1; CID+17080 -83E1 E0101; Hanyo-Denshi; JC9102 -83E1 E0101; Moji_Joho; MJ022128 -83E1 E0102; Hanyo-Denshi; JTB9CC -83E1 E0102; Moji_Joho; MJ022129 -83E1 E0103; Hanyo-Denshi; KS353080 -83E1 E0103; Moji_Joho; MJ058493 -83E5 E0100; Adobe-Japan1; CID+18503 -83E5 E0101; Hanyo-Denshi; JD8631 -83E5 E0101; Moji_Joho; MJ022133 -83E5 E0102; Hanyo-Denshi; KS351010 -83E5 E0102; Moji_Joho; MJ022134 -83E8 E0100; Adobe-Japan1; CID+22333 -83E8 E0101; Hanyo-Denshi; JB5631 -83E8 E0101; Moji_Joho; MJ022137 -83E8 E0102; Hanyo-Denshi; KS351050 -83E8 E0102; Moji_Joho; MJ022138 -83E9 E0100; Adobe-Japan1; CID+3646 -83E9 E0101; Hanyo-Denshi; JA4278 -83E9 E0101; Moji_Joho; MJ022139 -83E9 E0102; Hanyo-Denshi; KS351060 -83E9 E0102; Moji_Joho; MJ022140 -83EA E0100; Adobe-Japan1; CID+15059 -83EA E0101; Hanyo-Denshi; JB5632 -83EA E0101; Moji_Joho; MJ022141 -83EA E0102; Hanyo-Denshi; JTB9CA -83EA E0102; Moji_Joho; MJ022142 -83EB E0100; Adobe-Japan1; CID+6378 -83EB E0101; Hanyo-Denshi; JA7233 -83EB E0101; Moji_Joho; MJ022143 -83EB E0102; Hanyo-Denshi; KS351080 -83EB E0102; Moji_Joho; MJ022144 -83ED E0100; Hanyo-Denshi; IP83ED -83ED E0101; Hanyo-Denshi; KS351100 -83EE E0100; Hanyo-Denshi; KS351140 -83EE E0101; Hanyo-Denshi; TK01078710 -83EF E0100; Adobe-Japan1; CID+1370 -83EF E0101; Hanyo-Denshi; JA1858 -83EF E0101; Moji_Joho; MJ022150 -83EF E0102; Hanyo-Denshi; KS351150 -83EF E0102; Moji_Joho; MJ022152 -83EF E0103; Hanyo-Denshi; JTB9B1 -83EF E0103; Moji_Joho; MJ022151 -83EF E0104; Hanyo-Denshi; TK01078030 -83EF E0104; Moji_Joho; MJ068053 -83F0 E0100; Adobe-Japan1; CID+1930 -83F0 E0101; Hanyo-Denshi; JA2454 -83F0 E0101; Moji_Joho; MJ022154 -83F0 E0102; Hanyo-Denshi; JTB9C5 -83F0 E0102; Moji_Joho; MJ022156 -83F0 E0103; Hanyo-Denshi; KS353210 -83F0 E0103; Moji_Joho; MJ022155 -83F1 E0100; Adobe-Japan1; CID+3483 -83F1 E0101; Hanyo-Denshi; JA4109 -83F1 E0101; Moji_Joho; MJ022157 -83F1 E0102; Hanyo-Denshi; JTB9C7S -83F1 E0102; Moji_Joho; MJ022160 -83F1 E0103; Hanyo-Denshi; JTB9C6S -83F1 E0103; Moji_Joho; MJ022159 -83F1 E0104; Hanyo-Denshi; KS352910 -83F1 E0104; Moji_Joho; MJ022158 -83F2 E0100; Adobe-Japan1; CID+6388 -83F2 E0101; Adobe-Japan1; CID+13589 -83F2 E0102; Hanyo-Denshi; JA7243 -83F2 E0103; Hanyo-Denshi; KS351180 -83F2 E0103; Moji_Joho; MJ022162 -83F2 E0104; Moji_Joho; MJ022161 -83F2 E0105; Moji_Joho; MJ022163 -83F3 E0100; Hanyo-Denshi; IP83F3 -83F3 E0100; Moji_Joho; MJ022164 -83F3 E0101; Hanyo-Denshi; KS351240 -83F3 E0101; Moji_Joho; MJ022165 -83F4 E0100; Adobe-Japan1; CID+6376 -83F4 E0101; Hanyo-Denshi; JA7231 -83F4 E0101; Moji_Joho; MJ022166 -83F4 E0102; Hanyo-Denshi; JTC0F6 -83F4 E0102; Moji_Joho; MJ022167 -83F6 E0100; Adobe-Japan1; CID+8604 -83F6 E0101; Hanyo-Denshi; JB5633 -83F6 E0101; Moji_Joho; MJ022169 -83F6 E0102; Hanyo-Denshi; KS351300 -83F6 E0102; Moji_Joho; MJ022170 -83F7 E0100; Adobe-Japan1; CID+6385 -83F7 E0101; Hanyo-Denshi; JA7240 -83F7 E0101; Moji_Joho; MJ022171 -83F7 E0102; Hanyo-Denshi; KS351310 -83F7 E0102; Moji_Joho; MJ022172 -83F7 E0103; Hanyo-Denshi; FT2480S -83F7 E0103; Moji_Joho; MJ022173 -83F8 E0100; Adobe-Japan1; CID+19741 -83F8 E0101; Hanyo-Denshi; JB5634 -83F8 E0101; Moji_Joho; MJ022175 -83F8 E0102; Hanyo-Denshi; KS353090 -83F8 E0102; Moji_Joho; MJ022174 -83F8 E0103; Hanyo-Denshi; TK01078670 -83F9 E0100; Adobe-Japan1; CID+18504 -83F9 E0101; Hanyo-Denshi; JB5635 -83F9 E0101; Moji_Joho; MJ022177 -83F9 E0102; Hanyo-Denshi; KS351320 -83F9 E0102; Moji_Joho; MJ022178 -83FB E0100; Adobe-Japan1; CID+6395 -83FB E0101; Hanyo-Denshi; JA7250 -83FB E0101; Moji_Joho; MJ022180 -83FB E0102; Hanyo-Denshi; KS351340 -83FB E0102; Moji_Joho; MJ022181 -83FC E0100; Adobe-Japan1; CID+19742 -83FC E0101; Hanyo-Denshi; JB5636 -83FC E0101; Moji_Joho; MJ022182 -83FC E0102; Hanyo-Denshi; KS351360 -83FC E0102; Moji_Joho; MJ022183 -83FD E0100; Adobe-Japan1; CID+6380 -83FD E0101; Hanyo-Denshi; JA7235 -83FD E0101; Moji_Joho; MJ022184 -83FD E0102; Hanyo-Denshi; KS351370S -83FD E0102; Moji_Joho; MJ022185 -83FE E0100; Hanyo-Denshi; IP83FE -83FE E0101; Hanyo-Denshi; KS351380 -83FE E0102; Hanyo-Denshi; TK01078720 -8401 E0100; Adobe-Japan1; CID+17081 -8401 E0101; Hanyo-Denshi; JB5637 -8401 E0101; Moji_Joho; MJ022191 -8401 E0102; Hanyo-Denshi; JTB9CD -8401 E0102; Moji_Joho; MJ022192 -8403 E0100; Adobe-Japan1; CID+6381 -8403 E0101; Hanyo-Denshi; JA7236 -8403 E0101; Moji_Joho; MJ022194 -8403 E0102; Hanyo-Denshi; JTB996 -8403 E0102; Moji_Joho; MJ022196 -8403 E0103; Hanyo-Denshi; KS351470 -8403 E0103; Moji_Joho; MJ022195 -8403 E0104; Hanyo-Denshi; TK01077470 -8404 E0100; Adobe-Japan1; CID+3218 -8404 E0101; Hanyo-Denshi; JA3826 -8404 E0101; Moji_Joho; MJ022198 -8404 E0102; Hanyo-Denshi; KS351480 -8404 E0102; Moji_Joho; MJ022199 -8404 E0103; Hanyo-Denshi; KS353120 -8404 E0103; Moji_Joho; MJ058494 -8406 E0100; Adobe-Japan1; CID+17082 -8406 E0101; Hanyo-Denshi; JB5638 -8406 E0101; Moji_Joho; MJ022201 -8406 E0102; Hanyo-Denshi; KS351510 -8406 E0102; Moji_Joho; MJ022202 -8407 E0100; Adobe-Japan1; CID+6386 -8407 E0101; Hanyo-Denshi; JA7241 -8407 E0101; Moji_Joho; MJ022203 -8407 E0102; Hanyo-Denshi; KS351520 -8407 E0102; Moji_Joho; MJ022204 -840A E0100; Adobe-Japan1; CID+7807 -840A E0101; Hanyo-Denshi; JB5639 -840A E0101; Moji_Joho; MJ022207 -840A E0102; Hanyo-Denshi; KS351580 -840A E0102; Moji_Joho; MJ022208 -840B E0100; Adobe-Japan1; CID+6383 -840B E0101; Hanyo-Denshi; JA7238 -840B E0101; Moji_Joho; MJ022209 -840B E0102; Hanyo-Denshi; KS351600 -840B E0102; Moji_Joho; MJ022210 -840B E0103; Hanyo-Denshi; JTB995 -840B E0103; Moji_Joho; MJ022211 -840C E0100; Adobe-Japan1; CID+3670 -840C E0101; Adobe-Japan1; CID+14026 -840C E0102; Hanyo-Denshi; JA4308 -840C E0102; Moji_Joho; MJ022212 -840C E0103; Hanyo-Denshi; KS351610 -840C E0103; Moji_Joho; MJ022213 -840D E0100; Adobe-Japan1; CID+6389 -840D E0101; Hanyo-Denshi; JA7244 -840D E0101; Moji_Joho; MJ022214 -840D E0102; Hanyo-Denshi; KS351620 -840D E0102; Moji_Joho; MJ022215 -840D E0103; Hanyo-Denshi; FT2481 -840D E0103; Moji_Joho; MJ022216 -840E E0100; Adobe-Japan1; CID+1188 -840E E0101; Hanyo-Denshi; JA1664 -840E E0101; Moji_Joho; MJ022217 -840E E0102; Hanyo-Denshi; KS351650 -840E E0102; Moji_Joho; MJ022218 -840F E0100; Adobe-Japan1; CID+15060 -840F E0101; Adobe-Japan1; CID+20203 -840F E0102; Hanyo-Denshi; JB5640 -840F E0102; Moji_Joho; MJ022219 -840F E0103; Hanyo-Denshi; KS351660 -840F E0103; Moji_Joho; MJ022220 -8411 E0100; Adobe-Japan1; CID+15061 -8411 E0101; Hanyo-Denshi; JB5641 -8411 E0101; Moji_Joho; MJ022222 -8411 E0102; Hanyo-Denshi; JTB9D1 -8411 E0102; Moji_Joho; MJ022223 -8413 E0100; Adobe-Japan1; CID+6377 -8413 E0101; Hanyo-Denshi; JA7232 -8413 E0101; Moji_Joho; MJ022225 -8413 E0102; Hanyo-Denshi; JTB9AA -8413 E0102; Moji_Joho; MJ022227 -8413 E0103; Hanyo-Denshi; JTB9A9 -8413 E0103; Moji_Joho; MJ022226 -8413 E0104; Hanyo-Denshi; TK01079780 -8415 E0100; Adobe-Japan1; CID+18505 -8415 E0101; Hanyo-Denshi; JB5642 -8415 E0101; Moji_Joho; MJ022229 -8415 E0102; Hanyo-Denshi; KS351930 -8415 E0102; Moji_Joho; MJ022231 -8415 E0103; Moji_Joho; MJ022230 -8417 E0100; Adobe-Japan1; CID+18507 -8419 E0100; Adobe-Japan1; CID+22334 -8419 E0101; Hanyo-Denshi; JB5643 -8419 E0101; Moji_Joho; MJ022234 -8419 E0102; Hanyo-Denshi; KS352140 -8419 E0102; Moji_Joho; MJ022235 -841E E0100; Hanyo-Denshi; JT841E -841E E0100; Moji_Joho; MJ022236 -841E E0101; Hanyo-Denshi; JTB9C9 -841E E0101; Moji_Joho; MJ022237 -8420 E0100; Adobe-Japan1; CID+6391 -8420 E0101; Adobe-Japan1; CID+14203 -8420 E0102; Hanyo-Denshi; JA7246 -8420 E0102; Moji_Joho; MJ022239 -8420 E0103; Hanyo-Denshi; KS352890 -8420 E0103; Moji_Joho; MJ022240 -8420 E0104; Hanyo-Denshi; FT2482 -8420 E0104; Moji_Joho; MJ022241 -8420 E0105; Hanyo-Denshi; TK01079020 -8422 E0100; Adobe-Japan1; CID+6390 -8422 E0101; Adobe-Japan1; CID+7999 -8422 E0102; Hanyo-Denshi; JA7245 -8422 E0102; Moji_Joho; MJ022243 -8422 E0103; Hanyo-Denshi; KS352840 -8422 E0103; Moji_Joho; MJ022245 -8422 E0104; Hanyo-Denshi; JTB9B6 -8422 E0104; Moji_Joho; MJ022244 -8429 E0100; Adobe-Japan1; CID+3361 -8429 E0101; Hanyo-Denshi; JA3975 -8429 E0101; Moji_Joho; MJ022248 -8429 E0102; Hanyo-Denshi; JTB9F9 -8429 E0102; Moji_Joho; MJ022249 -842A E0100; Adobe-Japan1; CID+6397 -842A E0101; Hanyo-Denshi; JA7252 -842A E0101; Moji_Joho; MJ022250 -842A E0102; Hanyo-Denshi; KS353290 -842A E0102; Moji_Joho; MJ022251 -842B E0100; Hanyo-Denshi; IP842B -842B E0100; Moji_Joho; MJ022252 -842B E0101; Hanyo-Denshi; KS353320 -842B E0101; Moji_Joho; MJ022253 -842C E0100; Adobe-Japan1; CID+6408 -842C E0101; Hanyo-Denshi; JA7263 -842C E0101; Moji_Joho; MJ022254 -842C E0102; Hanyo-Denshi; JTB9E5 -842C E0102; Moji_Joho; MJ022257 -842C E0103; Hanyo-Denshi; KS355970 -842C E0103; Moji_Joho; MJ022256 -842C E0104; Hanyo-Denshi; KS353330 -842C E0104; Moji_Joho; MJ022255 -842C E0105; Hanyo-Denshi; TK01007760 -842F E0100; Adobe-Japan1; CID+22336 -842F E0101; Hanyo-Denshi; JB5645 -842F E0101; Moji_Joho; MJ022260 -842F E0102; Hanyo-Denshi; KS356050 -842F E0102; Moji_Joho; MJ022261 -8431 E0100; Adobe-Japan1; CID+1500 -8431 E0101; Hanyo-Denshi; JA1994 -8431 E0101; Moji_Joho; MJ022263 -8431 E0102; Hanyo-Denshi; JTB9ED -8431 E0102; Moji_Joho; MJ022264 -8431 E0103; Hanyo-Denshi; TK01078760 -8435 E0100; Adobe-Japan1; CID+6411 -8435 E0101; Hanyo-Denshi; JA7266 -8435 E0101; Moji_Joho; MJ022268 -8435 E0102; Hanyo-Denshi; KS353440 -8435 E0102; Moji_Joho; MJ022269 -8436 E0100; Hanyo-Denshi; IP8436 -8436 E0101; Hanyo-Denshi; KS353450 -8438 E0100; Adobe-Japan1; CID+6393 -8438 E0101; Hanyo-Denshi; JA7248 -8438 E0101; Moji_Joho; MJ022273 -8438 E0102; Hanyo-Denshi; KS353490 -8438 E0102; Moji_Joho; MJ022274 -8439 E0100; Adobe-Japan1; CID+18508 -8439 E0101; Hanyo-Denshi; JB5646 -8439 E0101; Moji_Joho; MJ022275 -8439 E0102; Hanyo-Denshi; KS353510 -8439 E0102; Moji_Joho; MJ022276 -843B E0100; Hanyo-Denshi; IP843B -843B E0100; Moji_Joho; MJ022278 -843B E0101; Hanyo-Denshi; KS353530 -843B E0101; Moji_Joho; MJ022279 -843C E0100; Adobe-Japan1; CID+6398 -843C E0101; Hanyo-Denshi; JA7253 -843C E0101; Moji_Joho; MJ022280 -843C E0102; Hanyo-Denshi; JTB9EC -843C E0102; Moji_Joho; MJ022281 -843D E0100; Adobe-Japan1; CID+3928 -843D E0101; Hanyo-Denshi; JA4578 -843D E0101; Moji_Joho; MJ022282 -843D E0102; Hanyo-Denshi; KS353550 -843D E0102; Moji_Joho; MJ022283 -843F E0100; Hanyo-Denshi; IP843F -843F E0101; Hanyo-Denshi; KS353580 -8441 E0100; Hanyo-Denshi; IP8441 -8441 E0100; Moji_Joho; MJ022288 -8441 E0101; Hanyo-Denshi; JTB9F4 -8441 E0101; Moji_Joho; MJ022289 -8445 E0100; Adobe-Japan1; CID+22337 -8445 E0101; Hanyo-Denshi; JB5647 -8445 E0101; Moji_Joho; MJ022293 -8445 E0102; Hanyo-Denshi; KS353710 -8445 E0102; Moji_Joho; MJ022294 -8446 E0100; Adobe-Japan1; CID+6407 -8446 E0101; Hanyo-Denshi; JA7262 -8446 E0101; Moji_Joho; MJ022295 -8446 E0102; Hanyo-Denshi; KS353720S -8446 E0102; Moji_Joho; MJ022296 -8447 E0100; Adobe-Japan1; CID+22338 -8447 E0101; Hanyo-Denshi; JB5648 -8447 E0101; Moji_Joho; MJ022297 -8447 E0102; Hanyo-Denshi; KS353750 -8447 E0102; Moji_Joho; MJ022298 -8448 E0100; Adobe-Japan1; CID+8605 -8448 E0101; Hanyo-Denshi; JB5649 -8448 E0101; Moji_Joho; MJ022299 -8448 E0102; Hanyo-Denshi; KS353770 -8448 E0102; Moji_Joho; MJ022300 -8449 E0100; Adobe-Japan1; CID+3903 -8449 E0101; Hanyo-Denshi; JA4553 -8449 E0101; Moji_Joho; MJ022301 -8449 E0102; Hanyo-Denshi; JTB9DB -8449 E0102; Moji_Joho; MJ022303 -8449 E0103; Hanyo-Denshi; JTB9DA -8449 E0103; Moji_Joho; MJ022302 -8449 E0104; Hanyo-Denshi; TK01079740 -844A E0100; Adobe-Japan1; CID+15062 -844A E0101; Hanyo-Denshi; JB5650 -844A E0101; Moji_Joho; MJ022305 -844A E0102; Hanyo-Denshi; JTB9F0 -844A E0102; Moji_Joho; MJ022306 -844D E0100; Adobe-Japan1; CID+22339 -844D E0101; Hanyo-Denshi; JB5651 -844D E0101; Moji_Joho; MJ022309 -844D E0102; Hanyo-Denshi; KS353860 -844D E0102; Moji_Joho; MJ022310 -844E E0100; Adobe-Japan1; CID+3954 -844E E0101; Hanyo-Denshi; JA4610 -844E E0101; Moji_Joho; MJ022311 -844E E0102; Hanyo-Denshi; KS353880 -844E E0102; Moji_Joho; MJ022312 -844F E0100; Adobe-Japan1; CID+18509 -844F E0101; Hanyo-Denshi; JB5652 -844F E0101; Moji_Joho; MJ022313 -844F E0102; Hanyo-Denshi; JTB9F2 -844F E0102; Moji_Joho; MJ022314 -8451 E0100; Adobe-Japan1; CID+18510 -8451 E0101; Hanyo-Denshi; JB5653 -8451 E0101; Moji_Joho; MJ022316 -8451 E0102; Hanyo-Denshi; KS353900 -8451 E0102; Moji_Joho; MJ022317 -8452 E0100; Adobe-Japan1; CID+18511 -8452 E0101; Hanyo-Denshi; JB5654 -8452 E0101; Moji_Joho; MJ022318 -8452 E0102; Hanyo-Denshi; KS353920 -8452 E0102; Moji_Joho; MJ022319 -8455 E0100; Hanyo-Denshi; IP8455 -8455 E0101; Hanyo-Denshi; KS353960 -8456 E0100; Adobe-Japan1; CID+22340 -8456 E0101; Hanyo-Denshi; JB5655 -8456 E0101; Moji_Joho; MJ022324 -8456 E0102; Hanyo-Denshi; KS353990 -8456 E0102; Moji_Joho; MJ022325 -8457 E0100; Adobe-Japan1; CID+2998 -8457 E0101; Adobe-Japan1; CID+13367 -8457 E0102; Hanyo-Denshi; JA3588 -8457 E0102; Moji_Joho; MJ022326 -8457 E0103; Hanyo-Denshi; KS354000 -8457 E0103; Moji_Joho; MJ022327 -8457 E0104; Hanyo-Denshi; JC9107 -8458 E0100; Adobe-Japan1; CID+19743 -8458 E0101; Hanyo-Denshi; JB5656 -8458 E0101; Moji_Joho; MJ022328 -8458 E0102; Hanyo-Denshi; KS354030 -8458 E0102; Moji_Joho; MJ022329 -8459 E0100; Adobe-Japan1; CID+18512 -8459 E0101; Hanyo-Denshi; JB5657 -8459 E0101; Moji_Joho; MJ022330 -8459 E0102; Hanyo-Denshi; KS354040 -8459 E0102; Moji_Joho; MJ022331 -845A E0100; Adobe-Japan1; CID+18513 -845A E0101; Hanyo-Denshi; JB5658 -845A E0101; Moji_Joho; MJ022332 -845A E0102; Hanyo-Denshi; KS354060 -845A E0102; Moji_Joho; MJ022333 -845A E0103; Hanyo-Denshi; KS356080S -845A E0103; Moji_Joho; MJ022334 -845B E0100; Adobe-Japan1; CID+1481 -845B E0101; Adobe-Japan1; CID+7652 -845B E0102; Hanyo-Denshi; JA1975 -845B E0102; Moji_Joho; MJ022335 -845B E0103; Hanyo-Denshi; FT1769 -845B E0103; Moji_Joho; MJ022336 -845B E0104; Hanyo-Denshi; JTB9D7 -845B E0104; Moji_Joho; MJ022340 -845B E0105; Hanyo-Denshi; JTB9D8 -845B E0105; Moji_Joho; MJ022341 -845B E0106; Hanyo-Denshi; JTB9D6 -845B E0106; Moji_Joho; MJ022338 -845B E0107; Hanyo-Denshi; KS352870 -845B E0107; Moji_Joho; MJ022337 -845B E0108; Hanyo-Denshi; JTC0F7 -845B E0108; Moji_Joho; MJ022339 -845B E0109; Hanyo-Denshi; TK01079040 -845C E0100; Adobe-Japan1; CID+18514 -845C E0101; Adobe-Japan1; CID+22341 -845C E0102; Hanyo-Denshi; JB5659 -845C E0102; Moji_Joho; MJ022342 -845C E0103; Hanyo-Denshi; KS354100 -845C E0103; Moji_Joho; MJ022343 -845C E0104; Hanyo-Denshi; JD8645 -845C E0104; Moji_Joho; MJ022344 -845F E0100; Adobe-Japan1; CID+17083 -845F E0101; Hanyo-Denshi; JC9109 -845F E0101; Moji_Joho; MJ022347 -845F E0102; Hanyo-Denshi; JTB9F3 -845F E0102; Moji_Joho; MJ022348 -8460 E0100; Adobe-Japan1; CID+22342 -8460 E0101; Hanyo-Denshi; JB5660 -8460 E0101; Moji_Joho; MJ022349 -8460 E0102; Hanyo-Denshi; KS354170 -8460 E0102; Moji_Joho; MJ022350 -8461 E0100; Adobe-Japan1; CID+3556 -8461 E0101; Hanyo-Denshi; JA4182 -8461 E0101; Moji_Joho; MJ022351 -8461 E0102; Hanyo-Denshi; KS354190 -8461 E0102; Moji_Joho; MJ022352 -8462 E0100; Adobe-Japan1; CID+6413 -8462 E0101; Hanyo-Denshi; JA7268 -8462 E0101; Moji_Joho; MJ022353 -8462 E0102; Hanyo-Denshi; KS356070 -8462 E0102; Moji_Joho; MJ022355 -8462 E0103; Hanyo-Denshi; KS354210 -8462 E0103; Moji_Joho; MJ022354 -8463 E0100; Adobe-Japan1; CID+3193 -8463 E0101; Hanyo-Denshi; JA3801 -8463 E0101; Moji_Joho; MJ022356 -8463 E0102; Hanyo-Denshi; JTB9EF -8463 E0102; Moji_Joho; MJ022357 -8463 E0103; Hanyo-Denshi; TK01080030 -8464 E0100; Adobe-Japan1; CID+22343 -8464 E0101; Hanyo-Denshi; JB5661 -8464 E0101; Moji_Joho; MJ022359 -8464 E0102; Hanyo-Denshi; KS354240 -8464 E0102; Moji_Joho; MJ022360 -8465 E0100; Adobe-Japan1; CID+18516 -8465 E0101; Hanyo-Denshi; JB5662 -8465 E0101; Moji_Joho; MJ022361 -8465 E0102; Hanyo-Denshi; KS354250 -8465 E0102; Moji_Joho; MJ022362 -8466 E0100; Adobe-Japan1; CID+1141 -8466 E0101; Hanyo-Denshi; JA1617 -8466 E0101; Moji_Joho; MJ022364 -8466 E0102; Hanyo-Denshi; KS356060 -8466 E0102; Moji_Joho; MJ022365 -8466 E0103; Hanyo-Denshi; JTBA09 -8466 E0103; Moji_Joho; MJ022368 -8466 E0104; Hanyo-Denshi; JTB9E3S -8466 E0104; Moji_Joho; MJ022366 -8466 E0105; Moji_Joho; MJ022363 -8466 E0106; Moji_Joho; MJ022367 -8467 E0100; Adobe-Japan1; CID+22344 -8467 E0101; Hanyo-Denshi; JB5663 -8467 E0101; Moji_Joho; MJ022369 -8467 E0102; Hanyo-Denshi; KS354270 -8467 E0102; Moji_Joho; MJ022370 -8469 E0100; Adobe-Japan1; CID+6406 -8469 E0101; Hanyo-Denshi; JA7261 -8469 E0101; Moji_Joho; MJ022372 -8469 E0102; Hanyo-Denshi; KS354300 -8469 E0102; Moji_Joho; MJ022373 -846A E0100; Adobe-Japan1; CID+22345 -846A E0101; Hanyo-Denshi; JB5664 -846A E0101; Moji_Joho; MJ022374 -846A E0102; Hanyo-Denshi; KS354310 -846A E0102; Moji_Joho; MJ022375 -846B E0100; Adobe-Japan1; CID+6402 -846B E0101; Hanyo-Denshi; JA7257 -846B E0101; Moji_Joho; MJ022376 -846B E0102; Hanyo-Denshi; KS354320 -846B E0102; Moji_Joho; MJ022377 -846C E0100; Adobe-Japan1; CID+2804 -846C E0101; Hanyo-Denshi; JA3382 -846C E0101; Moji_Joho; MJ022378 -846C E0102; Hanyo-Denshi; KS354370 -846C E0102; Moji_Joho; MJ022379 -846D E0100; Adobe-Japan1; CID+6396 -846D E0101; Hanyo-Denshi; JA7251 -846D E0101; Moji_Joho; MJ022380 -846D E0102; Hanyo-Denshi; JTB9EB -846D E0102; Moji_Joho; MJ022381 -846E E0100; Adobe-Japan1; CID+6404 -846E E0101; Hanyo-Denshi; JA7259 -846E E0101; Moji_Joho; MJ022382 -846E E0102; Hanyo-Denshi; KS354390 -846E E0102; Moji_Joho; MJ022383 -846F E0100; Adobe-Japan1; CID+6409 -846F E0101; Hanyo-Denshi; JA7264 -846F E0101; Moji_Joho; MJ022384 -846F E0102; Hanyo-Denshi; KS354400 -846F E0102; Moji_Joho; MJ022385 -8470 E0100; Adobe-Japan1; CID+17084 -8470 E0101; Hanyo-Denshi; JB5665 -8470 E0101; Moji_Joho; MJ022386 -8470 E0102; Hanyo-Denshi; KS354420 -8470 E0102; Moji_Joho; MJ022387 -8471 E0100; Adobe-Japan1; CID+3298 -8471 E0101; Hanyo-Denshi; JA3912 -8471 E0101; Moji_Joho; MJ022388 -8471 E0102; Hanyo-Denshi; KS354430S -8471 E0102; Moji_Joho; MJ022389 -8473 E0100; Adobe-Japan1; CID+17085 -8473 E0101; Hanyo-Denshi; JB5666 -8473 E0101; Moji_Joho; MJ022391 -8473 E0102; Hanyo-Denshi; JTB9F6 -8473 E0102; Moji_Joho; MJ022392 -8474 E0100; Adobe-Japan1; CID+22346 -8474 E0101; Hanyo-Denshi; JB5667 -8474 E0101; Moji_Joho; MJ022393 -8474 E0102; Hanyo-Denshi; KS354460 -8474 E0102; Moji_Joho; MJ022394 -8475 E0100; Adobe-Japan1; CID+1134 -8475 E0101; Hanyo-Denshi; JA1610 -8475 E0101; Moji_Joho; MJ022395 -8475 E0102; Hanyo-Denshi; JTB9F7 -8475 E0102; Moji_Joho; MJ022396 -8476 E0100; Adobe-Japan1; CID+15063 -8476 E0101; Hanyo-Denshi; JB5668 -8476 E0101; Moji_Joho; MJ022397 -8476 E0102; Hanyo-Denshi; KS354480 -8476 E0102; Moji_Joho; MJ022398 -8477 E0100; Adobe-Japan1; CID+6401 -8477 E0101; Hanyo-Denshi; JA7256 -8477 E0101; Moji_Joho; MJ022399 -8477 E0102; Hanyo-Denshi; KS354490 -8477 E0102; Moji_Joho; MJ022400 -8478 E0100; Adobe-Japan1; CID+18517 -8478 E0101; Hanyo-Denshi; JB5669 -8478 E0101; Moji_Joho; MJ022401 -8478 E0102; Hanyo-Denshi; JTB9F8 -8478 E0102; Moji_Joho; MJ022402 -8479 E0100; Adobe-Japan1; CID+6410 -8479 E0101; Hanyo-Denshi; JA7265 -8479 E0101; Moji_Joho; MJ022403 -8479 E0102; Hanyo-Denshi; KS354520S -8479 E0102; Moji_Joho; MJ022404 -847A E0100; Adobe-Japan1; CID+3562 -847A E0101; Adobe-Japan1; CID+13498 -847A E0102; Hanyo-Denshi; JA4188 -847A E0102; Moji_Joho; MJ022405 -847A E0103; Hanyo-Denshi; KS354530 -847A E0103; Moji_Joho; MJ022406 -847A E0104; Moji_Joho; MJ022407 -847B E0100; Hanyo-Denshi; IP847B -847B E0100; Moji_Joho; MJ022408 -847B E0101; Hanyo-Denshi; KS354540 -847B E0101; Moji_Joho; MJ022409 -847C E0100; Adobe-Japan1; CID+18518 -847C E0101; Hanyo-Denshi; JB5670 -847C E0101; Moji_Joho; MJ022410 -847C E0102; Hanyo-Denshi; KS356040 -847C E0102; Moji_Joho; MJ022411 -847D E0100; Adobe-Japan1; CID+22347 -847D E0101; Hanyo-Denshi; JB5671 -847D E0101; Moji_Joho; MJ022412 -847D E0102; Hanyo-Denshi; JTB9F5 -847D E0102; Moji_Joho; MJ022415 -847D E0103; Hanyo-Denshi; KS352940 -847D E0103; Moji_Joho; MJ022413 -847D E0104; Hanyo-Denshi; KS354550 -847D E0104; Moji_Joho; MJ022414 -8480 E0100; Hanyo-Denshi; IP8480 -8480 E0101; Hanyo-Denshi; KS354630 -8481 E0100; Adobe-Japan1; CID+18519 -8481 E0101; Hanyo-Denshi; JB5672 -8481 E0101; Moji_Joho; MJ022421 -8481 E0102; Hanyo-Denshi; KS356030 -8481 E0102; Moji_Joho; MJ022423 -8481 E0103; Hanyo-Denshi; IB0864 -8481 E0103; Moji_Joho; MJ022420 -8481 E0104; Hanyo-Denshi; KS354640 -8481 E0104; Moji_Joho; MJ022422 -8482 E0100; Adobe-Japan1; CID+6405 -8482 E0101; Hanyo-Denshi; JA7260 -8482 E0101; Moji_Joho; MJ022424 -8482 E0102; Hanyo-Denshi; KS355980 -8482 E0102; Moji_Joho; MJ022426 -8482 E0103; Hanyo-Denshi; KS354820S -8482 E0103; Moji_Joho; MJ022425 -8484 E0100; Adobe-Japan1; CID+6400 -8484 E0101; Hanyo-Denshi; JA7255 -8484 E0101; Moji_Joho; MJ022428 -8484 E0102; Hanyo-Denshi; JTB9F1S -8484 E0102; Moji_Joho; MJ022429 -8485 E0100; Adobe-Japan1; CID+17086 -8485 E0101; Hanyo-Denshi; JB5673 -8485 E0101; Moji_Joho; MJ022430 -8485 E0102; Hanyo-Denshi; KS355150 -8485 E0102; Moji_Joho; MJ022431 -8485 E0103; Hanyo-Denshi; JTBA0E -8485 E0103; Moji_Joho; MJ022432 -848B E0100; Adobe-Japan1; CID+2493 -848B E0101; Hanyo-Denshi; JA3053 -848B E0101; Moji_Joho; MJ022433 -848B E0102; Hanyo-Denshi; JTBA07 -848B E0102; Moji_Joho; MJ022434 -848B E0103; Hanyo-Denshi; TK01079380 -848B E0104; Hanyo-Denshi; TK01079600 -8490 E0100; Adobe-Japan1; CID+2361 -8490 E0101; Hanyo-Denshi; JA2915 -8490 E0101; Moji_Joho; MJ022437 -8490 E0102; Hanyo-Denshi; KS356210 -8490 E0102; Moji_Joho; MJ022438 -8492 E0100; Adobe-Japan1; CID+22348 -8492 E0101; Hanyo-Denshi; JB5674 -8492 E0101; Moji_Joho; MJ022440 -8492 E0102; Hanyo-Denshi; KS356260 -8492 E0102; Moji_Joho; MJ022441 -8493 E0100; Adobe-Japan1; CID+19744 -8493 E0101; Hanyo-Denshi; JB5675 -8493 E0101; Moji_Joho; MJ022442 -8493 E0102; Hanyo-Denshi; KS356270 -8493 E0102; Moji_Joho; MJ022443 -8494 E0100; Adobe-Japan1; CID+2264 -8494 E0101; Hanyo-Denshi; JA2812 -8494 E0101; Moji_Joho; MJ022444 -8494 E0102; Hanyo-Denshi; KS356280 -8494 E0102; Moji_Joho; MJ022445 -8495 E0100; Adobe-Japan1; CID+22349 -8495 E0101; Hanyo-Denshi; JB5676 -8495 E0101; Moji_Joho; MJ022446 -8495 E0102; Hanyo-Denshi; KS356290 -8495 E0102; Moji_Joho; MJ022447 -8497 E0100; Adobe-Japan1; CID+18521 -8497 E0101; Hanyo-Denshi; JD8654 -8497 E0101; Moji_Joho; MJ022449 -8497 E0102; Hanyo-Denshi; KS356330 -8497 E0102; Moji_Joho; MJ022450 -8499 E0100; Adobe-Japan1; CID+3812 -8499 E0101; Hanyo-Denshi; JA4456 -8499 E0101; Moji_Joho; MJ022452 -8499 E0102; Hanyo-Denshi; KS356360 -8499 E0102; Moji_Joho; MJ022453 -8499 E0103; Hanyo-Denshi; FT2056 -8499 E0103; Moji_Joho; MJ022454 -8499 E0104; Hanyo-Denshi; JTBBB7 -8499 E0104; Moji_Joho; MJ022455 -849C E0100; Adobe-Japan1; CID+3513 -849C E0101; Hanyo-Denshi; JA4139 -849C E0101; Moji_Joho; MJ022459 -849C E0102; Hanyo-Denshi; IB0359 -849C E0102; Moji_Joho; MJ022460 -849C E0103; Hanyo-Denshi; JTB9D4 -849C E0103; Moji_Joho; MJ022458 -849D E0100; Hanyo-Denshi; KS356450 -849D E0101; Hanyo-Denshi; TK01079880 -849E E0100; Adobe-Japan1; CID+17087 -849E E0101; Hanyo-Denshi; JB5677 -849E E0101; Moji_Joho; MJ022463 -849E E0102; Hanyo-Denshi; JTBA17 -849E E0102; Moji_Joho; MJ022464 -849F E0100; Adobe-Japan1; CID+6416 -849F E0101; Hanyo-Denshi; JA7271 -849F E0101; Moji_Joho; MJ022465 -849F E0102; Hanyo-Denshi; KS356470 -849F E0102; Moji_Joho; MJ022466 -84A1 E0100; Adobe-Japan1; CID+6425 -84A1 E0101; Hanyo-Denshi; JA7280 -84A1 E0101; Moji_Joho; MJ022468 -84A1 E0102; Hanyo-Denshi; KS358510 -84A1 E0102; Moji_Joho; MJ022470 -84A1 E0103; Hanyo-Denshi; KS356530 -84A1 E0103; Moji_Joho; MJ022469 -84A5 E0100; Hanyo-Denshi; KS356580 -84A5 E0101; Hanyo-Denshi; TK01079890 -84A6 E0100; Adobe-Japan1; CID+18522 -84A6 E0101; Hanyo-Denshi; JB5678 -84A6 E0101; Moji_Joho; MJ022475 -84A6 E0102; Hanyo-Denshi; JTBA16 -84A6 E0102; Moji_Joho; MJ022477 -84A6 E0103; Hanyo-Denshi; JTBA15 -84A6 E0103; Moji_Joho; MJ022476 -84A7 E0100; Hanyo-Denshi; KS355780 -84A7 E0100; Moji_Joho; MJ022478 -84A7 E0101; Hanyo-Denshi; KS358560 -84A7 E0101; Moji_Joho; MJ022479 -84A8 E0100; Adobe-Japan1; CID+15064 -84A8 E0101; Hanyo-Denshi; JB5679 -84A8 E0101; Moji_Joho; MJ022480 -84A8 E0102; Hanyo-Denshi; IB0358 -84A8 E0102; Moji_Joho; MJ022482 -84A8 E0103; Hanyo-Denshi; IB0865 -84A8 E0103; Moji_Joho; MJ022481 -84A8 E0104; Hanyo-Denshi; TK01080090 -84A9 E0100; Adobe-Japan1; CID+22350 -84A9 E0101; Hanyo-Denshi; JB5680 -84A9 E0101; Moji_Joho; MJ022484 -84A9 E0102; Hanyo-Denshi; KS356720 -84A9 E0102; Moji_Joho; MJ022485 -84AA E0100; Adobe-Japan1; CID+22351 -84AA E0101; Hanyo-Denshi; JB5681 -84AA E0101; Moji_Joho; MJ022486 -84AA E0102; Hanyo-Denshi; KS356730 -84AA E0102; Moji_Joho; MJ022487 -84AD E0100; Adobe-Japan1; CID+6403 -84AD E0101; Hanyo-Denshi; JA7258 -84AD E0101; Moji_Joho; MJ022490 -84AD E0102; Hanyo-Denshi; KS356770 -84AD E0102; Moji_Joho; MJ022491 -84AF E0100; Adobe-Japan1; CID+15065 -84AF E0101; Hanyo-Denshi; JB5682 -84AF E0101; Moji_Joho; MJ022493 -84AF E0102; Hanyo-Denshi; KS356800 -84AF E0102; Moji_Joho; MJ022494 -84B1 E0100; Adobe-Japan1; CID+19745 -84B1 E0101; Hanyo-Denshi; JB5683 -84B1 E0101; Moji_Joho; MJ022496 -84B1 E0102; Hanyo-Denshi; KS356890 -84B1 E0102; Moji_Joho; MJ022497 -84B2 E0100; Adobe-Japan1; CID+1493 -84B2 E0101; Hanyo-Denshi; JA1987 -84B2 E0101; Moji_Joho; MJ022498 -84B2 E0102; Hanyo-Denshi; JTBA14 -84B2 E0102; Moji_Joho; MJ022499 -84B2 E0103; Hanyo-Denshi; TK01078940 -84B4 E0100; Adobe-Japan1; CID+8606 -84B4 E0101; Hanyo-Denshi; JB5684 -84B4 E0101; Moji_Joho; MJ022501 -84B4 E0102; Hanyo-Denshi; KS356930 -84B4 E0102; Moji_Joho; MJ022502 -84B8 E0100; Adobe-Japan1; CID+2528 -84B8 E0101; Hanyo-Denshi; JA3088 -84B8 E0101; Moji_Joho; MJ022506 -84B8 E0102; Hanyo-Denshi; KS356970 -84B8 E0102; Moji_Joho; MJ022507 -84B9 E0100; Adobe-Japan1; CID+6414 -84B9 E0101; Hanyo-Denshi; JA7269 -84B9 E0101; Moji_Joho; MJ022508 -84B9 E0102; Hanyo-Denshi; KS357000 -84B9 E0102; Moji_Joho; MJ022510 -84B9 E0103; Hanyo-Denshi; FT2485 -84B9 E0103; Moji_Joho; MJ022509 -84BA E0100; Adobe-Japan1; CID+17088 -84BA E0101; Hanyo-Denshi; JB5685 -84BA E0101; Moji_Joho; MJ022511 -84BA E0102; Hanyo-Denshi; KS357010 -84BA E0102; Moji_Joho; MJ022512 -84BB E0100; Adobe-Japan1; CID+6419 -84BB E0101; Hanyo-Denshi; JA7274 -84BB E0101; Moji_Joho; MJ022513 -84BB E0102; Hanyo-Denshi; KS357020 -84BB E0102; Moji_Joho; MJ022514 -84BB E0103; Hanyo-Denshi; FT2486 -84BB E0103; Moji_Joho; MJ022515 -84BC E0100; Adobe-Japan1; CID+2805 -84BC E0101; Hanyo-Denshi; JA3383 -84BC E0101; Moji_Joho; MJ022516 -84BC E0102; Hanyo-Denshi; KS357060 -84BC E0102; Moji_Joho; MJ022517 -84BD E0100; Adobe-Japan1; CID+19746 -84BD E0101; Hanyo-Denshi; JB5686 -84BD E0101; Moji_Joho; MJ022518 -84BD E0102; Hanyo-Denshi; KS357080 -84BD E0102; Moji_Joho; MJ022519 -84BE E0100; Adobe-Japan1; CID+18523 -84BE E0101; Hanyo-Denshi; JB5687 -84BE E0101; Moji_Joho; MJ022520 -84BE E0102; Hanyo-Denshi; KS357100 -84BE E0102; Moji_Joho; MJ022521 -84BF E0100; Adobe-Japan1; CID+6415 -84BF E0101; Hanyo-Denshi; JA7270 -84BF E0101; Moji_Joho; MJ022522 -84BF E0102; Hanyo-Denshi; KS357130 -84BF E0102; Moji_Joho; MJ022523 -84BF E0103; Hanyo-Denshi; TK01080350 -84C0 E0100; Adobe-Japan1; CID+15066 -84C0 E0101; Hanyo-Denshi; JB5688 -84C0 E0101; Moji_Joho; MJ022525 -84C0 E0102; Hanyo-Denshi; JTBA1A -84C0 E0102; Moji_Joho; MJ022526 -84C1 E0100; Adobe-Japan1; CID+6422 -84C1 E0101; Hanyo-Denshi; JA7277 -84C1 E0101; Moji_Joho; MJ022527 -84C1 E0102; Hanyo-Denshi; KS357180 -84C1 E0102; Moji_Joho; MJ022528 -84C2 E0100; Adobe-Japan1; CID+15067 -84C2 E0101; Hanyo-Denshi; JB5689 -84C2 E0101; Moji_Joho; MJ022529 -84C2 E0102; Hanyo-Denshi; JTBA1B -84C2 E0102; Moji_Joho; MJ022530 -84C4 E0100; Adobe-Japan1; CID+2973 -84C4 E0101; Hanyo-Denshi; JA3563 -84C4 E0101; Moji_Joho; MJ022532 -84C4 E0102; Hanyo-Denshi; KS357210 -84C4 E0102; Moji_Joho; MJ022533 -84C5 E0100; Hanyo-Denshi; IP84C5 -84C5 E0100; Moji_Joho; MJ022534 -84C5 E0101; Hanyo-Denshi; KS357230 -84C5 E0101; Moji_Joho; MJ022535 -84C6 E0100; Adobe-Japan1; CID+6423 -84C6 E0101; Hanyo-Denshi; JA7278 -84C6 E0101; Moji_Joho; MJ022536 -84C6 E0102; Hanyo-Denshi; KS357240 -84C6 E0102; Moji_Joho; MJ022537 -84C7 E0100; Adobe-Japan1; CID+22352 -84C7 E0101; Hanyo-Denshi; JB5690 -84C7 E0101; Moji_Joho; MJ022538 -84C7 E0102; Hanyo-Denshi; KS357250 -84C7 E0102; Moji_Joho; MJ022539 -84C8 E0100; Adobe-Japan1; CID+22353 -84C8 E0101; Hanyo-Denshi; JB5691 -84C8 E0101; Moji_Joho; MJ022540 -84C8 E0102; Hanyo-Denshi; KS357260 -84C8 E0102; Moji_Joho; MJ022541 -84C8 E0103; Hanyo-Denshi; TK01079220 -84C8 E0104; Moji_Joho; MJ060115 -84C9 E0100; Adobe-Japan1; CID+3904 -84C9 E0101; Hanyo-Denshi; JA4554 -84C9 E0101; Moji_Joho; MJ022543 -84C9 E0102; Hanyo-Denshi; KS357270 -84C9 E0102; Moji_Joho; MJ022544 -84CA E0100; Adobe-Japan1; CID+6412 -84CA E0101; Hanyo-Denshi; JA7267 -84CA E0101; Moji_Joho; MJ022545 -84CA E0102; Hanyo-Denshi; KS357290S -84CA E0102; Moji_Joho; MJ022546 -84CA E0103; Hanyo-Denshi; FT2484 -84CA E0103; Moji_Joho; MJ022548 -84CA E0104; Hanyo-Denshi; JTBA0A -84CA E0104; Moji_Joho; MJ022547 -84CB E0100; Adobe-Japan1; CID+1430 -84CB E0101; Hanyo-Denshi; JA1924 -84CB E0101; Moji_Joho; MJ022549 -84CB E0102; Hanyo-Denshi; KS357310 -84CB E0102; Moji_Joho; MJ022550 -84CC E0100; Adobe-Japan1; CID+22354 -84CC E0101; Hanyo-Denshi; JB5692 -84CC E0101; Moji_Joho; MJ022551 -84CC E0102; Hanyo-Denshi; KS358570 -84CC E0102; Moji_Joho; MJ022552 -84CD E0100; Adobe-Japan1; CID+6418 -84CD E0101; Hanyo-Denshi; JA7273 -84CD E0101; Moji_Joho; MJ022553 -84CD E0102; Hanyo-Denshi; KS357330 -84CD E0102; Moji_Joho; MJ022554 -84CE E0100; Adobe-Japan1; CID+18525 -84CE E0101; Hanyo-Denshi; JD8658 -84CE E0101; Moji_Joho; MJ022555 -84CE E0102; Hanyo-Denshi; KS357340 -84CE E0102; Moji_Joho; MJ022556 -84CE E0103; Hanyo-Denshi; TK01080040 -84CF E0100; Adobe-Japan1; CID+18526 -84CF E0101; Hanyo-Denshi; JB5693 -84CF E0101; Moji_Joho; MJ022558 -84CF E0102; Hanyo-Denshi; JTBA1C -84CF E0102; Moji_Joho; MJ022560 -84CF E0103; Hanyo-Denshi; KS357360 -84CF E0103; Moji_Joho; MJ022559 -84D0 E0100; Adobe-Japan1; CID+6421 -84D0 E0101; Hanyo-Denshi; JA7276 -84D0 E0101; Moji_Joho; MJ022561 -84D0 E0102; Hanyo-Denshi; KS358590 -84D0 E0102; Moji_Joho; MJ022563 -84D0 E0103; Hanyo-Denshi; KS357380S -84D0 E0103; Moji_Joho; MJ022562 -84D1 E0100; Adobe-Japan1; CID+3768 -84D1 E0101; Hanyo-Denshi; JA4412 -84D1 E0101; Moji_Joho; MJ022564 -84D1 E0102; Hanyo-Denshi; JTBA12 -84D1 E0102; Moji_Joho; MJ022565 -84D1 E0103; Hanyo-Denshi; TK01080000 -84D3 E0100; Adobe-Japan1; CID+18527 -84D3 E0101; Hanyo-Denshi; JB5694 -84D3 E0101; Moji_Joho; MJ022568 -84D3 E0102; Hanyo-Denshi; KS357410 -84D3 E0102; Moji_Joho; MJ022569 -84D6 E0100; Adobe-Japan1; CID+6424 -84D6 E0101; Hanyo-Denshi; JA7279 -84D6 E0101; Moji_Joho; MJ022572 -84D6 E0102; Hanyo-Denshi; KS357050 -84D6 E0102; Moji_Joho; MJ022573 -84D9 E0100; Adobe-Japan1; CID+6417 -84D9 E0101; Hanyo-Denshi; JA7272 -84D9 E0101; Moji_Joho; MJ022576 -84D9 E0102; Hanyo-Denshi; KS357780 -84D9 E0102; Moji_Joho; MJ022577 -84D9 E0103; Hanyo-Denshi; JTBA06 -84D9 E0103; Moji_Joho; MJ022578 -84DA E0100; Adobe-Japan1; CID+6420 -84DA E0101; Hanyo-Denshi; JA7275 -84DA E0101; Moji_Joho; MJ022579 -84DA E0102; Hanyo-Denshi; KS357860S -84DA E0102; Moji_Joho; MJ022580 -84DC E0100; Adobe-Japan1; CID+8363 -84DC E0101; Hanyo-Denshi; JB5701 -84DC E0101; Moji_Joho; MJ022582 -84DC E0102; Hanyo-Denshi; JTBA19 -84DC E0102; Moji_Joho; MJ022581 -84DC E0103; Hanyo-Denshi; JTB9E8 -84DC E0103; Moji_Joho; MJ022583 -84DC E0104; Hanyo-Denshi; TK01079440 -84DD E0100; Hanyo-Denshi; TK01079500 -84DD E0101; Hanyo-Denshi; TK01079720 -84E7 E0100; Adobe-Japan1; CID+18529 -84E7 E0101; Hanyo-Denshi; JB5702 -84E7 E0101; Moji_Joho; MJ022590 -84E7 E0102; Hanyo-Denshi; JTBA33 -84E7 E0102; Moji_Joho; MJ022589 -84EA E0100; Adobe-Japan1; CID+18530 -84EA E0101; Adobe-Japan1; CID+20205 -84EA E0102; Hanyo-Denshi; JB5703 -84EA E0102; Moji_Joho; MJ022593 -84EA E0103; Hanyo-Denshi; KS358660 -84EA E0103; Moji_Joho; MJ022594 -84EB E0100; Hanyo-Denshi; IB0361 -84EB E0100; Moji_Joho; MJ022596 -84EB E0101; Hanyo-Denshi; IB0868 -84EB E0101; Moji_Joho; MJ022595 -84EC E0100; Adobe-Japan1; CID+3671 -84EC E0101; Adobe-Japan1; CID+7794 -84EC E0102; Hanyo-Denshi; JA4309 -84EC E0102; Moji_Joho; MJ022597 -84EC E0103; Hanyo-Denshi; FT1921 -84EC E0103; Moji_Joho; MJ022599 -84EC E0104; Hanyo-Denshi; KS358710 -84EC E0104; Moji_Joho; MJ022600 -84EC E0105; Hanyo-Denshi; JTBCF0 -84EC E0105; Moji_Joho; MJ022598 -84EC E0106; Hanyo-Denshi; JTBD11 -84EC E0106; Moji_Joho; MJ022601 -84EE E0100; Adobe-Japan1; CID+7811 -84EE E0101; Adobe-Japan1; CID+4039 -84EE E0102; Hanyo-Denshi; JA4701 -84EE E0102; Moji_Joho; MJ022603 -84EE E0103; Hanyo-Denshi; KS358730 -84EE E0103; Moji_Joho; MJ022606 -84EE E0104; Hanyo-Denshi; FT1939 -84EE E0104; Moji_Joho; MJ022605 -84EE E0105; Hanyo-Denshi; JTBCFD -84EE E0105; Moji_Joho; MJ022604 -84EE E0106; Hanyo-Denshi; JTBD10 -84EE E0106; Moji_Joho; MJ022607 -84EE E0107; Hanyo-Denshi; TK01079970 -84EF E0100; Adobe-Japan1; CID+18531 -84EF E0101; Hanyo-Denshi; JB5704 -84EF E0101; Moji_Joho; MJ022609 -84EF E0102; Hanyo-Denshi; KS358750 -84EF E0102; Moji_Joho; MJ022610 -84F0 E0100; Adobe-Japan1; CID+15068 -84F0 E0101; Hanyo-Denshi; JB5705 -84F0 E0101; Moji_Joho; MJ022612 -84F0 E0102; Hanyo-Denshi; JTBA32 -84F0 E0102; Moji_Joho; MJ022611 -84F1 E0100; Adobe-Japan1; CID+18532 -84F1 E0101; Hanyo-Denshi; JB5706 -84F1 E0101; Moji_Joho; MJ022614 -84F1 E0102; Hanyo-Denshi; KS358780 -84F1 E0102; Moji_Joho; MJ022615 -84F1 E0103; Hanyo-Denshi; KS356000 -84F1 E0103; Moji_Joho; MJ022613 -84F2 E0100; Adobe-Japan1; CID+22355 -84F2 E0101; Hanyo-Denshi; JB5707 -84F2 E0101; Moji_Joho; MJ022616 -84F2 E0102; Hanyo-Denshi; KS358810 -84F2 E0102; Moji_Joho; MJ022617 -84F4 E0100; Adobe-Japan1; CID+6428 -84F4 E0101; Adobe-Japan1; CID+14205 -84F4 E0102; Hanyo-Denshi; JA7283 -84F4 E0102; Moji_Joho; MJ022619 -84F4 E0103; Hanyo-Denshi; KS358850 -84F4 E0103; Moji_Joho; MJ022620 -84F4 E0104; Hanyo-Denshi; JTBA28 -84F4 E0104; Moji_Joho; MJ022621 -84F7 E0100; Adobe-Japan1; CID+22356 -84F7 E0101; Hanyo-Denshi; JB5708 -84F7 E0101; Moji_Joho; MJ022624 -84F7 E0102; Hanyo-Denshi; JTBA34 -84F7 E0102; Moji_Joho; MJ022625 -84FA E0100; Adobe-Japan1; CID+18533 -84FB E0100; Adobe-Japan1; CID+19747 -84FB E0101; Hanyo-Denshi; JB5711 -84FB E0101; Moji_Joho; MJ022629 -84FB E0102; Hanyo-Denshi; KS358930 -84FB E0102; Moji_Joho; MJ022630 -84FC E0100; Adobe-Japan1; CID+6435 -84FC E0101; Hanyo-Denshi; JA7290 -84FC E0101; Moji_Joho; MJ022631 -84FC E0102; Hanyo-Denshi; KS358940 -84FC E0102; Moji_Joho; MJ022632 -84FC E0103; Hanyo-Denshi; FT2488 -84FC E0103; Moji_Joho; MJ022633 -84FD E0100; Adobe-Japan1; CID+15069 -84FD E0101; Hanyo-Denshi; JB5712 -84FD E0101; Moji_Joho; MJ022634 -84FD E0102; Hanyo-Denshi; KS361110 -84FD E0102; Moji_Joho; MJ022636 -84FD E0103; Hanyo-Denshi; KS358950 -84FD E0103; Moji_Joho; MJ022635 -84FF E0100; Adobe-Japan1; CID+6427 -84FF E0101; Hanyo-Denshi; JA7282 -84FF E0101; Moji_Joho; MJ022638 -84FF E0102; Hanyo-Denshi; KS358970 -84FF E0102; Moji_Joho; MJ022639 -8500 E0100; Adobe-Japan1; CID+2287 -8500 E0101; Hanyo-Denshi; JA2835 -8500 E0101; Moji_Joho; MJ022640 -8500 E0102; Hanyo-Denshi; KS358980 -8500 E0102; Moji_Joho; MJ022641 -8501 E0100; Hanyo-Denshi; IP8501 -8501 E0101; Hanyo-Denshi; KS359010 -8502 E0100; Adobe-Japan1; CID+22357 -8502 E0101; Hanyo-Denshi; JB5713 -8502 E0101; Moji_Joho; MJ022644 -8502 E0102; Hanyo-Denshi; KS359020 -8502 E0102; Moji_Joho; MJ022645 -8503 E0100; Adobe-Japan1; CID+22358 -8503 E0101; Hanyo-Denshi; JB5714 -8503 E0101; Moji_Joho; MJ022646 -8503 E0102; Hanyo-Denshi; KS359040 -8503 E0102; Moji_Joho; MJ022647 -8506 E0100; Adobe-Japan1; CID+6394 -8506 E0101; Hanyo-Denshi; JA7249 -8506 E0101; Moji_Joho; MJ022650 -8506 E0102; Hanyo-Denshi; KS361090 -8506 E0102; Moji_Joho; MJ022651 -8507 E0100; Adobe-Japan1; CID+22359 -8507 E0101; Hanyo-Denshi; JB5715 -8507 E0101; Moji_Joho; MJ022652 -8507 E0102; Hanyo-Denshi; JTBA30 -8507 E0102; Moji_Joho; MJ022653 -8508 E0100; Hanyo-Denshi; KS359130 -8508 E0101; Hanyo-Denshi; TK01080460 -850C E0100; Adobe-Japan1; CID+15070 -850C E0101; Hanyo-Denshi; JB5716 -850C E0101; Moji_Joho; MJ022659 -850C E0102; Hanyo-Denshi; KS359200 -850C E0102; Moji_Joho; MJ022660 -850E E0100; Adobe-Japan1; CID+22360 -850E E0101; Hanyo-Denshi; JB5717 -850E E0101; Moji_Joho; MJ022662 -850E E0102; Hanyo-Denshi; KS359240 -850E E0102; Moji_Joho; MJ022663 -8510 E0100; Adobe-Japan1; CID+22361 -8510 E0101; Hanyo-Denshi; JB5718 -8510 E0101; Moji_Joho; MJ022665 -8510 E0102; Hanyo-Denshi; KS359270 -8510 E0102; Moji_Joho; MJ022666 -8511 E0100; Adobe-Japan1; CID+3614 -8511 E0101; Adobe-Japan1; CID+14013 -8511 E0102; Hanyo-Denshi; JA4246 -8511 E0102; Moji_Joho; MJ022667 -8511 E0103; Hanyo-Denshi; KS361010 -8511 E0103; Moji_Joho; MJ022669 -8511 E0104; Hanyo-Denshi; KS359280 -8511 E0104; Moji_Joho; MJ022668 -8511 E0105; Hanyo-Denshi; HG1660 -8511 E0105; Moji_Joho; MJ022670 -8512 E0100; Hanyo-Denshi; IP8512 -8512 E0100; Moji_Joho; MJ022671 -8512 E0101; Hanyo-Denshi; KS359300 -8512 E0101; Moji_Joho; MJ022672 -8513 E0100; Adobe-Japan1; CID+3758 -8513 E0101; Hanyo-Denshi; JA4402 -8513 E0101; Moji_Joho; MJ022673 -8513 E0102; Hanyo-Denshi; KS359310 -8513 E0102; Moji_Joho; MJ022674 -8513 E0103; Hanyo-Denshi; JTBA26 -8513 E0103; Moji_Joho; MJ022675 -8513 E0104; Moji_Joho; MJ022676 -8514 E0100; Adobe-Japan1; CID+6434 -8514 E0101; Hanyo-Denshi; JA7289 -8514 E0101; Moji_Joho; MJ022677 -8514 E0102; Hanyo-Denshi; KS359320 -8514 E0102; Moji_Joho; MJ022678 -8515 E0100; Adobe-Japan1; CID+6433 -8515 E0101; Hanyo-Denshi; JA7288 -8515 E0101; Moji_Joho; MJ022679 -8515 E0102; Hanyo-Denshi; KS359360S -8515 E0102; Moji_Joho; MJ022680 -8517 E0100; Adobe-Japan1; CID+6429 -8517 E0101; Adobe-Japan1; CID+7860 -8517 E0102; Hanyo-Denshi; JA7284 -8517 E0102; Moji_Joho; MJ022682 -8517 E0103; Hanyo-Denshi; FT1985 -8517 E0103; Moji_Joho; MJ022684 -8517 E0104; Hanyo-Denshi; JTBA23 -8517 E0104; Moji_Joho; MJ022683 -8517 E0105; Hanyo-Denshi; TK01080170 -8518 E0100; Adobe-Japan1; CID+6430 -8518 E0101; Hanyo-Denshi; JA7285 -8518 E0101; Moji_Joho; MJ022686 -8518 E0102; Hanyo-Denshi; KS359420 -8518 E0102; Moji_Joho; MJ022687 -851A E0100; Adobe-Japan1; CID+1240 -851A E0101; Hanyo-Denshi; JA1722 -851A E0101; Moji_Joho; MJ022689 -851A E0102; Hanyo-Denshi; KS359520 -851A E0102; Moji_Joho; MJ022690 -851B E0100; Adobe-Japan1; CID+18534 -851B E0101; Hanyo-Denshi; JD8670 -851B E0101; Moji_Joho; MJ022691 -851B E0102; Hanyo-Denshi; KS359550 -851B E0102; Moji_Joho; MJ022692 -851C E0100; Adobe-Japan1; CID+22362 -851C E0101; Hanyo-Denshi; JB5719 -851C E0101; Moji_Joho; MJ022693 -851C E0102; Hanyo-Denshi; KS359580 -851C E0102; Moji_Joho; MJ022694 -851E E0100; Adobe-Japan1; CID+17091 -851E E0101; Hanyo-Denshi; JB5720 -851E E0101; Moji_Joho; MJ022696 -851E E0102; Hanyo-Denshi; JTBA36 -851E E0102; Moji_Joho; MJ022697 -851F E0100; Adobe-Japan1; CID+6432 -851F E0101; Hanyo-Denshi; JA7287 -851F E0101; Moji_Joho; MJ022698 -851F E0102; Hanyo-Denshi; KS359620S -851F E0102; Moji_Joho; MJ022699 -8521 E0100; Adobe-Japan1; CID+6426 -8521 E0101; Hanyo-Denshi; JA7281 -8521 E0101; Moji_Joho; MJ022701 -8521 E0102; Hanyo-Denshi; KS359650 -8521 E0102; Moji_Joho; MJ022702 -8522 E0100; Adobe-Japan1; CID+22363 -8522 E0101; Hanyo-Denshi; JB5721 -8522 E0101; Moji_Joho; MJ022703 -8522 E0102; Hanyo-Denshi; KS359660 -8522 E0102; Moji_Joho; MJ022704 -8523 E0100; Adobe-Japan1; CID+7706 -8523 E0101; Hanyo-Denshi; JB5722 -8523 E0101; Moji_Joho; MJ022706 -8523 E0102; Hanyo-Denshi; JTBA24 -8523 E0102; Moji_Joho; MJ022707 -8523 E0103; Hanyo-Denshi; KS359670 -8523 E0103; Moji_Joho; MJ022705 -8524 E0100; Adobe-Japan1; CID+18535 -8524 E0101; Hanyo-Denshi; JB5723 -8524 E0101; Moji_Joho; MJ022708 -8524 E0102; Hanyo-Denshi; KS359700 -8524 E0102; Moji_Joho; MJ022709 -8525 E0100; Adobe-Japan1; CID+18536 -8525 E0101; Hanyo-Denshi; JB5724 -8525 E0101; Moji_Joho; MJ022711 -8525 E0102; Hanyo-Denshi; KS359720 -8525 E0102; Moji_Joho; MJ022710 -8525 E0103; Hanyo-Denshi; JTBA29S -8525 E0103; Moji_Joho; MJ022712 -8525 E0104; Hanyo-Denshi; KS360890 -8525 E0104; Moji_Joho; MJ058531 -8526 E0100; Adobe-Japan1; CID+3057 -8526 E0101; Hanyo-Denshi; JA3653 -8526 E0101; Moji_Joho; MJ022713 -8526 E0102; Hanyo-Denshi; JTBA35 -8526 E0102; Moji_Joho; MJ022714 -8527 E0100; Adobe-Japan1; CID+22364 -8527 E0101; Hanyo-Denshi; JB5725 -8527 E0101; Moji_Joho; MJ022715 -8527 E0102; Hanyo-Denshi; KS359770 -8527 E0102; Moji_Joho; MJ022716 -852A E0100; Adobe-Japan1; CID+22365 -852A E0101; Hanyo-Denshi; JB5726 -852A E0101; Moji_Joho; MJ022719 -852A E0102; Hanyo-Denshi; JTBA31 -852A E0102; Moji_Joho; MJ022720 -852B E0100; Adobe-Japan1; CID+18537 -852B E0101; Hanyo-Denshi; JB5727 -852B E0101; Moji_Joho; MJ022721 -852B E0102; Hanyo-Denshi; KS359840 -852B E0102; Moji_Joho; MJ022722 -852C E0100; Adobe-Japan1; CID+6431 -852C E0101; Hanyo-Denshi; JA7286 -852C E0101; Moji_Joho; MJ022723 -852C E0102; Hanyo-Denshi; KS359860 -852C E0102; Moji_Joho; MJ022724 -852D E0100; Adobe-Japan1; CID+1218 -852D E0101; Hanyo-Denshi; JA1694 -852D E0101; Moji_Joho; MJ022725 -852D E0102; Hanyo-Denshi; JTBA2E -852D E0102; Moji_Joho; MJ022726 -852F E0100; Adobe-Japan1; CID+17092 -852F E0101; Hanyo-Denshi; JB5728 -852F E0101; Moji_Joho; MJ022728 -852F E0102; Hanyo-Denshi; KS359950 -852F E0102; Moji_Joho; MJ022729 -8532 E0100; Adobe-Japan1; CID+17090 -8532 E0101; Hanyo-Denshi; JB5709 -8532 E0101; Moji_Joho; MJ022732 -8532 E0102; Hanyo-Denshi; KS358920 -8532 E0102; Moji_Joho; MJ022733 -8532 E0103; Hanyo-Denshi; JTBA03 -8532 E0103; Moji_Joho; MJ060129 -8533 E0100; Adobe-Japan1; CID+22366 -8533 E0101; Hanyo-Denshi; JB5729 -8533 E0101; Moji_Joho; MJ022734 -8533 E0102; Hanyo-Denshi; IB2845 -8533 E0102; Moji_Joho; MJ022735 -8533 E0103; Hanyo-Denshi; TK01080730 -8533 E0104; Hanyo-Denshi; TK01080830 -8534 E0100; Adobe-Japan1; CID+15071 -8534 E0101; Hanyo-Denshi; JB5730 -8534 E0101; Moji_Joho; MJ022738 -8534 E0102; Hanyo-Denshi; KS360300 -8534 E0102; Moji_Joho; MJ022739 -8535 E0100; Adobe-Japan1; CID+2818 -8535 E0101; Hanyo-Denshi; JA3402 -8535 E0102; Hanyo-Denshi; TK01081050 -8536 E0100; Adobe-Japan1; CID+22367 -8536 E0101; Hanyo-Denshi; JB5731 -8536 E0101; Moji_Joho; MJ022742 -8536 E0102; Hanyo-Denshi; KS361080 -8536 E0102; Moji_Joho; MJ022743 -853D E0100; Adobe-Japan1; CID+3603 -853D E0101; Adobe-Japan1; CID+7789 -853D E0102; Adobe-Japan1; CID+13505 -853D E0103; Hanyo-Denshi; JA4235 -853D E0103; Moji_Joho; MJ022744 -853D E0104; Hanyo-Denshi; FT1916 -853D E0104; Moji_Joho; MJ022746 -853D E0105; Hanyo-Denshi; KS361180S -853D E0105; Moji_Joho; MJ022745 -853E E0100; Adobe-Japan1; CID+7861 -853E E0101; Hanyo-Denshi; JD8679 -853E E0101; Moji_Joho; MJ022748 -853E E0102; Hanyo-Denshi; KS361220 -853E E0102; Moji_Joho; MJ022747 -853E E0103; Moji_Joho; MJ022749 -853F E0100; Adobe-Japan1; CID+22368 -853F E0101; Hanyo-Denshi; JB5732 -853F E0101; Moji_Joho; MJ022750 -853F E0102; Hanyo-Denshi; KS361250 -853F E0102; Moji_Joho; MJ022751 -8540 E0100; Adobe-Japan1; CID+6436 -8540 E0101; Hanyo-Denshi; JA7291 -8540 E0101; Moji_Joho; MJ022752 -8540 E0102; Hanyo-Denshi; KS361280 -8540 E0102; Moji_Joho; MJ022753 -8541 E0100; Adobe-Japan1; CID+6440 -8541 E0101; Hanyo-Denshi; JA7301 -8541 E0101; Moji_Joho; MJ022754 -8541 E0102; Hanyo-Denshi; KS361290 -8541 E0102; Moji_Joho; MJ022755 -8541 E0103; Hanyo-Denshi; FT2489 -8541 E0103; Moji_Joho; MJ022756 -8542 E0100; Hanyo-Denshi; KS361340 -8542 E0101; Hanyo-Denshi; TK01080750 -8542 E0102; Hanyo-Denshi; TK01080970 -8542 E0103; Hanyo-Denshi; TK01081100 -8543 E0100; Adobe-Japan1; CID+3437 -8543 E0101; Adobe-Japan1; CID+13990 -8543 E0102; Hanyo-Denshi; JA4057 -8543 E0102; Moji_Joho; MJ022760 -8543 E0103; Hanyo-Denshi; JTBA50 -8543 E0103; Moji_Joho; MJ022761 -8546 E0100; Adobe-Japan1; CID+19748 -8546 E0101; Hanyo-Denshi; JB5733 -8546 E0101; Moji_Joho; MJ022764 -8546 E0102; Hanyo-Denshi; KS361540 -8546 E0102; Moji_Joho; MJ022765 -8548 E0100; Adobe-Japan1; CID+6439 -8548 E0101; Hanyo-Denshi; JA7294 -8548 E0101; Moji_Joho; MJ022767 -8548 E0102; Hanyo-Denshi; KS361570 -8548 E0102; Moji_Joho; MJ022768 -8548 E0103; Hanyo-Denshi; KS363490 -8548 E0103; Moji_Joho; MJ022769 -8549 E0100; Adobe-Japan1; CID+2494 -8549 E0101; Hanyo-Denshi; JA3054 -8549 E0101; Moji_Joho; MJ022770 -8549 E0102; Hanyo-Denshi; KS361660 -8549 E0102; Moji_Joho; MJ022771 -854A E0100; Adobe-Japan1; CID+2293 -854A E0101; Hanyo-Denshi; JA2841 -854A E0101; Moji_Joho; MJ022772 -854A E0102; Hanyo-Denshi; KS361680 -854A E0102; Moji_Joho; MJ022773 -854B E0100; Adobe-Japan1; CID+6442 -854B E0101; Hanyo-Denshi; JA7303 -854B E0101; Moji_Joho; MJ022774 -854B E0102; Hanyo-Denshi; KS361690 -854B E0102; Moji_Joho; MJ022775 -854E E0100; Adobe-Japan1; CID+1718 -854E E0101; Hanyo-Denshi; JA2230 -854E E0101; Moji_Joho; MJ022778 -854E E0102; Hanyo-Denshi; KS361750S -854E E0102; Moji_Joho; MJ022779 -854F E0100; Adobe-Japan1; CID+18538 -854F E0101; Hanyo-Denshi; JB5734 -854F E0101; Moji_Joho; MJ022780 -854F E0102; Hanyo-Denshi; KS361780 -854F E0102; Moji_Joho; MJ022781 -8550 E0100; Adobe-Japan1; CID+22369 -8550 E0101; Hanyo-Denshi; JB5735 -8550 E0101; Moji_Joho; MJ022782 -8550 E0102; Hanyo-Denshi; KS361810 -8550 E0102; Moji_Joho; MJ022783 -8551 E0100; Adobe-Japan1; CID+18541 -8551 E0101; Adobe-Japan1; CID+20207 -8551 E0102; Hanyo-Denshi; JB5736 -8551 E0102; Moji_Joho; MJ022784 -8551 E0103; Hanyo-Denshi; JTBA4C -8551 E0103; Moji_Joho; MJ022785 -8552 E0100; Adobe-Japan1; CID+22370 -8552 E0101; Hanyo-Denshi; JB5737 -8552 E0101; Moji_Joho; MJ022786 -8552 E0102; Hanyo-Denshi; KS361840 -8552 E0102; Moji_Joho; MJ022787 -8553 E0100; Adobe-Japan1; CID+8607 -8553 E0101; Hanyo-Denshi; JB5738 -8553 E0101; Moji_Joho; MJ022788 -8553 E0102; Hanyo-Denshi; JTBA49 -8553 E0102; Moji_Joho; MJ022789 -8555 E0100; Adobe-Japan1; CID+6443 -8555 E0101; Adobe-Japan1; CID+13590 -8555 E0102; Hanyo-Denshi; JA7304 -8555 E0102; Moji_Joho; MJ022791 -8555 E0103; Hanyo-Denshi; KS361900 -8555 E0103; Moji_Joho; MJ022792 -8555 E0104; Hanyo-Denshi; FT2490 -8555 E0104; Moji_Joho; MJ022793 -8555 E0105; Hanyo-Denshi; JTBA46 -8555 E0105; Moji_Joho; MJ022794 -8556 E0100; Adobe-Japan1; CID+19749 -8556 E0101; Hanyo-Denshi; JB5739 -8556 E0101; Moji_Joho; MJ022796 -8556 E0102; Hanyo-Denshi; JTBA3E -8556 E0102; Moji_Joho; MJ022797 -8556 E0103; Hanyo-Denshi; JTBA3F -8556 E0103; Moji_Joho; MJ022798 -8556 E0104; Hanyo-Denshi; KS361910 -8556 E0104; Moji_Joho; MJ022795 -8557 E0100; Adobe-Japan1; CID+3563 -8557 E0101; Hanyo-Denshi; JA4189 -8557 E0101; Moji_Joho; MJ022800 -8557 E0102; Hanyo-Denshi; KS361930 -8557 E0102; Moji_Joho; MJ022799 -8558 E0100; Adobe-Japan1; CID+6438 -8558 E0101; Hanyo-Denshi; JA7293 -8558 E0101; Moji_Joho; MJ022801 -8558 E0102; Hanyo-Denshi; KS361940 -8558 E0102; Moji_Joho; MJ022802 -8559 E0100; Adobe-Japan1; CID+8608 -8559 E0101; Hanyo-Denshi; JB5740 -8559 E0101; Moji_Joho; MJ022803 -8559 E0102; Hanyo-Denshi; IB2839 -8559 E0102; Moji_Joho; MJ022805 -8559 E0103; Hanyo-Denshi; JTBA4E -8559 E0103; Moji_Joho; MJ022804 -8559 E0104; Hanyo-Denshi; JTBA2A -8559 E0104; Moji_Joho; MJ022806 -8559 E0105; Hanyo-Denshi; TK01080540 -855A E0100; Adobe-Japan1; CID+6399 -855A E0101; Hanyo-Denshi; JA7254 -855A E0101; Moji_Joho; MJ022807 -855A E0102; Hanyo-Denshi; KS361990 -855A E0102; Moji_Joho; MJ022808 -855C E0100; Adobe-Japan1; CID+22371 -855C E0101; Hanyo-Denshi; JB5741 -855C E0101; Moji_Joho; MJ022810 -855C E0102; Hanyo-Denshi; KS362040 -855C E0102; Moji_Joho; MJ022811 -855D E0100; Adobe-Japan1; CID+19750 -855D E0101; Adobe-Japan1; CID+22372 -855D E0102; Hanyo-Denshi; JB5742 -855D E0102; Moji_Joho; MJ022814 -855D E0103; Hanyo-Denshi; KS362050 -855D E0103; Moji_Joho; MJ022812 -855D E0104; Hanyo-Denshi; KS363430 -855D E0104; Moji_Joho; MJ022813 -855E E0100; Adobe-Japan1; CID+15072 -855E E0101; Hanyo-Denshi; JB5743 -855E E0101; Moji_Joho; MJ022815 -855E E0102; Hanyo-Denshi; KS362060 -855E E0102; Moji_Joho; MJ022816 -855F E0100; Adobe-Japan1; CID+22373 -855F E0101; Hanyo-Denshi; JB5744 -855F E0101; Moji_Joho; MJ022817 -855F E0102; Hanyo-Denshi; KS362070 -855F E0102; Moji_Joho; MJ022818 -8560 E0100; Adobe-Japan1; CID+22374 -8560 E0101; Hanyo-Denshi; JB5745 -8560 E0101; Moji_Joho; MJ022819 -8560 E0102; Hanyo-Denshi; KS362100 -8560 E0102; Moji_Joho; MJ022820 -8561 E0100; Adobe-Japan1; CID+18542 -8561 E0101; Hanyo-Denshi; JB5746 -8561 E0101; Moji_Joho; MJ022821 -8561 E0102; Hanyo-Denshi; KS362160 -8561 E0102; Moji_Joho; MJ022822 -8561 E0103; Hanyo-Denshi; KS365260 -8561 E0103; Moji_Joho; MJ058545 -8562 E0100; Adobe-Japan1; CID+18543 -8562 E0101; Hanyo-Denshi; JB5747 -8562 E0101; Moji_Joho; MJ022823 -8562 E0102; Hanyo-Denshi; JTBA4D -8562 E0102; Moji_Joho; MJ022824 -8563 E0100; Adobe-Japan1; CID+6437 -8563 E0101; Adobe-Japan1; CID+20208 -8563 E0102; Hanyo-Denshi; JA7292 -8563 E0102; Moji_Joho; MJ022825 -8563 E0103; Hanyo-Denshi; KS362200 -8563 E0103; Moji_Joho; MJ022826 -8563 E0104; Hanyo-Denshi; JTBA56 -8563 E0104; Moji_Joho; MJ022827 -8563 E0105; Hanyo-Denshi; JTBA57S -8563 E0105; Moji_Joho; MJ022828 -8563 E0106; Moji_Joho; MJ022829 -8564 E0100; Adobe-Japan1; CID+17093 -8564 E0101; Hanyo-Denshi; JB5748 -8564 E0101; Moji_Joho; MJ022830 -8564 E0102; Hanyo-Denshi; JTBA4FS -8564 E0102; Moji_Joho; MJ022831 -8565 E0100; Hanyo-Denshi; IP8565 -8565 E0101; Hanyo-Denshi; KS362240 -8568 E0100; Adobe-Japan1; CID+4085 -8568 E0101; Hanyo-Denshi; JA4747 -8568 E0101; Moji_Joho; MJ022836 -8568 E0102; Hanyo-Denshi; JTBA48 -8568 E0102; Moji_Joho; MJ022837 -8568 E0103; Hanyo-Denshi; KS358550 -8568 E0103; Moji_Joho; MJ058518 -8569 E0100; Adobe-Japan1; CID+3194 -8569 E0101; Hanyo-Denshi; JA3802 -8569 E0101; Moji_Joho; MJ022838 -8569 E0102; Hanyo-Denshi; KS362290 -8569 E0102; Moji_Joho; MJ022839 -856A E0100; Adobe-Japan1; CID+3557 -856A E0101; Hanyo-Denshi; JA4183 -856A E0101; Moji_Joho; MJ022840 -856A E0102; Hanyo-Denshi; KS362310 -856A E0102; Moji_Joho; MJ022841 -856B E0100; Adobe-Japan1; CID+8609 -856B E0101; Hanyo-Denshi; JB5749 -856B E0101; Moji_Joho; MJ022842 -856B E0102; Hanyo-Denshi; JTBA51 -856B E0102; Moji_Joho; MJ022843 -856B E0103; Hanyo-Denshi; KS363500 -856B E0103; Moji_Joho; MJ022844 -856C E0100; Hanyo-Denshi; IP856C -856C E0100; Moji_Joho; MJ022845 -856C E0101; Hanyo-Denshi; KS362370 -856C E0101; Moji_Joho; MJ022846 -856D E0100; Adobe-Japan1; CID+6450 -856D E0101; Hanyo-Denshi; JA7311 -856D E0101; Moji_Joho; MJ022847 -856D E0102; Hanyo-Denshi; KS362390 -856D E0102; Moji_Joho; MJ022848 -856F E0100; Adobe-Japan1; CID+18539 -856F E0101; Hanyo-Denshi; JB5750 -856F E0101; Moji_Joho; MJ022850 -856F E0102; Hanyo-Denshi; KS362540 -856F E0102; Moji_Joho; MJ022851 -856F E0103; Hanyo-Denshi; TK01079980 -856F E0104; Hanyo-Denshi; TK01080240 -8570 E0100; Hanyo-Denshi; FT2491 -8570 E0100; Moji_Joho; MJ022854 -8570 E0101; Hanyo-Denshi; KS362730 -8570 E0101; Moji_Joho; MJ022855 -8573 E0100; Hanyo-Denshi; JT8573 -8573 E0100; Moji_Joho; MJ022856 -8573 E0101; Hanyo-Denshi; JTBA4B -8573 E0101; Moji_Joho; MJ022857 -8577 E0100; Adobe-Japan1; CID+6456 -8577 E0101; Hanyo-Denshi; JA7317 -8577 E0101; Moji_Joho; MJ022859 -8577 E0102; Hanyo-Denshi; KS363570 -8577 E0102; Moji_Joho; MJ022860 -8578 E0100; Hanyo-Denshi; IP8578 -8578 E0100; Moji_Joho; MJ022862 -8578 E0101; Hanyo-Denshi; JTBA39 -8578 E0101; Moji_Joho; MJ022861 -8578 E0102; Hanyo-Denshi; JTBA67 -8578 E0102; Moji_Joho; MJ022863 -8579 E0100; Adobe-Japan1; CID+22375 -8579 E0101; Hanyo-Denshi; JB5751 -8579 E0101; Moji_Joho; MJ022864 -8579 E0102; Hanyo-Denshi; KS363600 -8579 E0102; Moji_Joho; MJ022865 -857A E0100; Adobe-Japan1; CID+17094 -857A E0101; Hanyo-Denshi; JB5752 -857A E0101; Moji_Joho; MJ022866 -857A E0102; Hanyo-Denshi; KS363620 -857A E0102; Moji_Joho; MJ022867 -857B E0100; Adobe-Japan1; CID+18545 -857B E0101; Hanyo-Denshi; JB5753 -857B E0101; Moji_Joho; MJ022868 -857B E0102; Hanyo-Denshi; KS363630 -857B E0102; Moji_Joho; MJ022869 -857D E0100; Adobe-Japan1; CID+18546 -857D E0101; Hanyo-Denshi; JB5754 -857D E0101; Moji_Joho; MJ022871 -857D E0102; Hanyo-Denshi; KS363670 -857D E0102; Moji_Joho; MJ022872 -857E E0100; Adobe-Japan1; CID+6457 -857E E0101; Hanyo-Denshi; JA7318 -857E E0101; Moji_Joho; MJ022873 -857E E0102; Hanyo-Denshi; KS363700 -857E E0102; Moji_Joho; MJ022874 -857F E0100; Adobe-Japan1; CID+18547 -857F E0101; Hanyo-Denshi; JB5755 -857F E0101; Moji_Joho; MJ022875 -857F E0102; Hanyo-Denshi; KS363730 -857F E0102; Moji_Joho; MJ022876 -8580 E0100; Adobe-Japan1; CID+6444 -8580 E0101; Hanyo-Denshi; JA7305 -8580 E0101; Moji_Joho; MJ022877 -8580 E0102; Hanyo-Denshi; KS363740 -8580 E0102; Moji_Joho; MJ022878 -8581 E0100; Adobe-Japan1; CID+18548 -8581 E0101; Hanyo-Denshi; JB5756 -8581 E0101; Moji_Joho; MJ022880 -8581 E0102; Hanyo-Denshi; KS363750 -8581 E0102; Moji_Joho; MJ022879 -8581 E0103; Hanyo-Denshi; TK01080850 -8581 E0104; Hanyo-Denshi; TK01081190 -8581 E0105; Moji_Joho; MJ022881 -8584 E0100; Adobe-Japan1; CID+3372 -8584 E0101; Adobe-Japan1; CID+13977 -8584 E0102; Hanyo-Denshi; JA3986 -8584 E0102; Moji_Joho; MJ022886 -8584 E0103; Hanyo-Denshi; KS365270 -8584 E0103; Moji_Joho; MJ022888 -8584 E0104; Hanyo-Denshi; JTBA52 -8584 E0104; Moji_Joho; MJ022887 -8584 E0105; Hanyo-Denshi; TK01080510 -8584 E0106; Hanyo-Denshi; TK01080940 -8584 E0107; Hanyo-Denshi; TK01081420 -8585 E0100; Adobe-Japan1; CID+19751 -8585 E0101; Hanyo-Denshi; JB5757 -8585 E0101; Moji_Joho; MJ022891 -8585 E0102; Hanyo-Denshi; KS363870 -8585 E0102; Moji_Joho; MJ022890 -8586 E0100; Adobe-Japan1; CID+18549 -8586 E0101; Hanyo-Denshi; JB5758 -8586 E0101; Moji_Joho; MJ022893 -8586 E0102; Hanyo-Denshi; JTBA6B -8586 E0102; Moji_Joho; MJ022894 -8587 E0100; Adobe-Japan1; CID+6454 -8587 E0101; Adobe-Japan1; CID+14207 -8587 E0102; Hanyo-Denshi; JA7315 -8587 E0102; Moji_Joho; MJ022896 -8587 E0103; Hanyo-Denshi; KS363930 -8587 E0103; Moji_Joho; MJ022897 -8587 E0104; Hanyo-Denshi; JTBA5DS -8587 E0104; Moji_Joho; MJ022899 -8587 E0105; Hanyo-Denshi; JTBA5CS -8587 E0105; Moji_Joho; MJ022898 -8587 E0106; Hanyo-Denshi; FT2493S -8587 E0106; Moji_Joho; MJ022895 -8588 E0100; Adobe-Japan1; CID+6446 -8588 E0101; Hanyo-Denshi; JA7307 -8588 E0101; Moji_Joho; MJ022900 -8588 E0102; Hanyo-Denshi; KS363940 -8588 E0102; Moji_Joho; MJ022901 -8589 E0100; Adobe-Japan1; CID+22376 -8589 E0101; Hanyo-Denshi; JB5759 -8589 E0101; Moji_Joho; MJ022902 -8589 E0102; Hanyo-Denshi; KS363950 -8589 E0102; Moji_Joho; MJ022903 -858A E0100; Adobe-Japan1; CID+6448 -858A E0101; Hanyo-Denshi; JA7309 -858A E0101; Moji_Joho; MJ022905 -858A E0102; Hanyo-Denshi; JTBA3D -858A E0102; Moji_Joho; MJ022904 -858A E0103; Hanyo-Denshi; JTBA68 -858A E0103; Moji_Joho; MJ022906 -858B E0100; Adobe-Japan1; CID+22377 -858B E0101; Hanyo-Denshi; JB5760 -858B E0101; Moji_Joho; MJ022907 -858B E0102; Hanyo-Denshi; KS364000 -858B E0102; Moji_Joho; MJ022908 -858C E0100; Adobe-Japan1; CID+17095 -858C E0101; Hanyo-Denshi; JB5761 -858C E0101; Moji_Joho; MJ022909 -858C E0102; Hanyo-Denshi; JTBA5B -858C E0102; Moji_Joho; MJ022911 -858C E0103; Hanyo-Denshi; IB2855 -858C E0103; Moji_Joho; MJ022912 -858C E0104; Hanyo-Denshi; JTBA5A -858C E0104; Moji_Joho; MJ022910 -858C E0105; Hanyo-Denshi; TK01080150 -858F E0100; Adobe-Japan1; CID+15073 -858F E0101; Hanyo-Denshi; JB5762 -858F E0101; Moji_Joho; MJ022916 -858F E0102; Hanyo-Denshi; KS365250 -858F E0102; Moji_Joho; MJ022918 -858F E0103; Hanyo-Denshi; JTBA6D -858F E0103; Moji_Joho; MJ022917 -8590 E0100; Adobe-Japan1; CID+6458 -8590 E0101; Hanyo-Denshi; JA7319 -8590 E0101; Moji_Joho; MJ022919 -8590 E0102; Hanyo-Denshi; KS365290 -8590 E0102; Moji_Joho; MJ022920 -8591 E0100; Adobe-Japan1; CID+6447 -8591 E0101; Hanyo-Denshi; JA7308 -8591 E0101; Moji_Joho; MJ022921 -8591 E0102; Hanyo-Denshi; KS364100 -8591 E0102; Moji_Joho; MJ022922 -8593 E0100; Adobe-Japan1; CID+18550 -8593 E0101; Hanyo-Denshi; JB5763 -8593 E0101; Moji_Joho; MJ022924 -8593 E0102; Hanyo-Denshi; KS364120S -8593 E0102; Moji_Joho; MJ022925 -8594 E0100; Adobe-Japan1; CID+6451 -8594 E0101; Hanyo-Denshi; JA7312 -8594 E0101; Moji_Joho; MJ022926 -8594 E0102; Hanyo-Denshi; KS364130 -8594 E0102; Moji_Joho; MJ022927 -8595 E0100; Hanyo-Denshi; IP8595 -8595 E0100; Moji_Joho; MJ022928 -8595 E0101; Hanyo-Denshi; JT8595 -8595 E0101; Moji_Joho; MJ022929 -8596 E0100; Hanyo-Denshi; IB0366 -8596 E0100; Moji_Joho; MJ022931 -8596 E0101; Hanyo-Denshi; IB0872 -8596 E0101; Moji_Joho; MJ022930 -8597 E0100; Adobe-Japan1; CID+1300 -8597 E0101; Hanyo-Denshi; JA1782 -8597 E0101; Moji_Joho; MJ022932 -8597 E0102; Hanyo-Denshi; JTBA66 -8597 E0102; Moji_Joho; MJ022933 -8598 E0100; Adobe-Japan1; CID+19752 -8598 E0101; Hanyo-Denshi; JB5764 -8598 E0101; Moji_Joho; MJ022935 -8598 E0102; Hanyo-Denshi; IB0367 -8598 E0102; Moji_Joho; MJ022936 -8598 E0103; Hanyo-Denshi; IB0873 -8598 E0103; Moji_Joho; MJ022934 -8599 E0100; Adobe-Japan1; CID+3261 -8599 E0101; Hanyo-Denshi; JA3869 -8599 E0101; Moji_Joho; MJ022937 -8599 E0102; Hanyo-Denshi; KS364210 -8599 E0102; Moji_Joho; MJ022938 -859B E0100; Adobe-Japan1; CID+6452 -859B E0101; Hanyo-Denshi; JA7313 -859B E0101; Moji_Joho; MJ022940 -859B E0102; Hanyo-Denshi; KS364230 -859B E0102; Moji_Joho; MJ022941 -859C E0100; Adobe-Japan1; CID+6455 -859C E0101; Hanyo-Denshi; JA7316 -859C E0101; Moji_Joho; MJ022942 -859C E0102; Hanyo-Denshi; KS364250 -859C E0102; Moji_Joho; MJ022943 -859C E0103; Hanyo-Denshi; TK01081870 -859D E0100; Adobe-Japan1; CID+18551 -859D E0101; Hanyo-Denshi; JB5765 -859D E0101; Moji_Joho; MJ022944 -859D E0102; Hanyo-Denshi; JTBA6E -859D E0102; Moji_Joho; MJ022945 -859F E0100; Adobe-Japan1; CID+18552 -859F E0101; Hanyo-Denshi; JB5766 -859F E0101; Moji_Joho; MJ022947 -859F E0102; Hanyo-Denshi; KS364310 -859F E0102; Moji_Joho; MJ022948 -85A0 E0100; Adobe-Japan1; CID+22378 -85A0 E0101; Hanyo-Denshi; JB5767 -85A0 E0101; Moji_Joho; MJ022949 -85A0 E0102; Hanyo-Denshi; KS364320 -85A0 E0102; Moji_Joho; MJ022950 -85A2 E0100; Adobe-Japan1; CID+17096 -85A2 E0101; Hanyo-Denshi; JB5768 -85A2 E0101; Moji_Joho; MJ022952 -85A2 E0102; Hanyo-Denshi; KS364390 -85A2 E0102; Moji_Joho; MJ022953 -85A4 E0100; Adobe-Japan1; CID+6445 -85A4 E0101; Hanyo-Denshi; JA7306 -85A4 E0101; Moji_Joho; MJ022955 -85A4 E0102; Hanyo-Denshi; KS364410 -85A4 E0102; Moji_Joho; MJ022956 -85A5 E0100; Adobe-Japan1; CID+22379 -85A5 E0101; Hanyo-Denshi; JB5769 -85A5 E0101; Moji_Joho; MJ022957 -85A5 E0102; Hanyo-Denshi; KS364420 -85A5 E0102; Moji_Joho; MJ022958 -85A6 E0100; Adobe-Japan1; CID+2728 -85A6 E0101; Hanyo-Denshi; JA3306 -85A6 E0101; Moji_Joho; MJ022959 -85A6 E0102; Hanyo-Denshi; KS364430 -85A6 E0102; Moji_Joho; MJ022960 -85A7 E0100; Adobe-Japan1; CID+22380 -85A7 E0101; Hanyo-Denshi; JB5770 -85A7 E0101; Moji_Joho; MJ022961 -85A7 E0102; Hanyo-Denshi; KS364460 -85A7 E0102; Moji_Joho; MJ022962 -85A8 E0100; Adobe-Japan1; CID+6449 -85A8 E0101; Hanyo-Denshi; JA7310 -85A8 E0101; Moji_Joho; MJ022963 -85A8 E0102; Hanyo-Denshi; KS364470S -85A8 E0102; Moji_Joho; MJ022964 -85A9 E0100; Adobe-Japan1; CID+2165 -85A9 E0101; Adobe-Japan1; CID+7688 -85A9 E0102; Hanyo-Denshi; JA2707 -85A9 E0102; Moji_Joho; MJ022965 -85A9 E0103; Hanyo-Denshi; FT1810 -85A9 E0103; Moji_Joho; MJ022966 -85A9 E0104; Hanyo-Denshi; KS365330 -85A9 E0104; Moji_Joho; MJ022967 -85A9 E0105; Hanyo-Denshi; JTBA71 -85A9 E0105; Moji_Joho; MJ022968 -85AA E0100; Adobe-Japan1; CID+2571 -85AA E0101; Hanyo-Denshi; JA3137 -85AA E0101; Moji_Joho; MJ022969 -85AA E0102; Hanyo-Denshi; KS364480 -85AA E0102; Moji_Joho; MJ022970 -85AB E0100; Adobe-Japan1; CID+1798 -85AB E0101; Hanyo-Denshi; JA2316 -85AB E0101; Moji_Joho; MJ022971 -85AB E0102; Hanyo-Denshi; JTBA64 -85AB E0102; Moji_Joho; MJ022973 -85AB E0103; Hanyo-Denshi; JTBA63 -85AB E0103; Moji_Joho; MJ022972 -85AC E0100; Adobe-Japan1; CID+3840 -85AC E0101; Hanyo-Denshi; JA4484 -85AC E0102; Hanyo-Denshi; TK01081320 -85AD E0100; Adobe-Japan1; CID+15076 -85AD E0101; Hanyo-Denshi; JB5784 -85AD E0101; Moji_Joho; MJ022977 -85AD E0102; Hanyo-Denshi; JTBA6F -85AD E0102; Moji_Joho; MJ022978 -85AD E0103; Hanyo-Denshi; TK01080900 -85AD E0104; Hanyo-Denshi; TK01081650 -85AD E0105; Hanyo-Denshi; TK01081880 -85AE E0100; Adobe-Japan1; CID+3845 -85AE E0101; Hanyo-Denshi; JA4489 -85AE E0102; Hanyo-Denshi; TK01081390 -85AF E0100; Adobe-Japan1; CID+2428 -85AF E0101; Adobe-Japan1; CID+7701 -85AF E0102; Hanyo-Denshi; JA2982 -85AF E0102; Moji_Joho; MJ022983 -85AF E0103; Hanyo-Denshi; FT1822 -85AF E0103; Moji_Joho; MJ022984 -85AF E0104; Hanyo-Denshi; KS365350 -85AF E0104; Moji_Joho; MJ022985 -85B0 E0100; Adobe-Japan1; CID+8611 -85B0 E0101; Hanyo-Denshi; JC9132 -85B0 E0101; Moji_Joho; MJ022986 -85B0 E0102; Hanyo-Denshi; JTBA7E -85B0 E0102; Moji_Joho; MJ022987 -85B1 E0100; Hanyo-Denshi; IP85B1 -85B1 E0101; Hanyo-Denshi; KS365370 -85B3 E0100; Hanyo-Denshi; IB0369 -85B3 E0100; Moji_Joho; MJ022993 -85B3 E0101; Hanyo-Denshi; IB0875 -85B3 E0101; Moji_Joho; MJ022992 -85B4 E0100; Adobe-Japan1; CID+22381 -85B4 E0101; Hanyo-Denshi; JB5771 -85B4 E0101; Moji_Joho; MJ022994 -85B4 E0102; Hanyo-Denshi; KS365400 -85B4 E0102; Moji_Joho; MJ022995 -85B5 E0100; Hanyo-Denshi; IP85B5 -85B5 E0100; Moji_Joho; MJ022996 -85B5 E0101; Hanyo-Denshi; KS365410 -85B5 E0101; Moji_Joho; MJ022997 -85B6 E0100; Adobe-Japan1; CID+22382 -85B6 E0101; Hanyo-Denshi; JB5772 -85B6 E0101; Moji_Joho; MJ022998 -85B6 E0102; Hanyo-Denshi; KS365420 -85B6 E0102; Moji_Joho; MJ022999 -85B7 E0100; Adobe-Japan1; CID+15074 -85B7 E0101; Hanyo-Denshi; JB5773 -85B7 E0101; Moji_Joho; MJ023000 -85B7 E0102; Hanyo-Denshi; KS365460 -85B7 E0102; Moji_Joho; MJ023001 -85B8 E0100; Adobe-Japan1; CID+22383 -85B8 E0101; Hanyo-Denshi; JB5774 -85B8 E0101; Moji_Joho; MJ023002 -85B8 E0102; Hanyo-Denshi; KS365470 -85B8 E0102; Moji_Joho; MJ023003 -85B9 E0100; Adobe-Japan1; CID+6462 -85B9 E0101; Hanyo-Denshi; JA7323 -85B9 E0101; Moji_Joho; MJ023004 -85B9 E0102; Hanyo-Denshi; KS365480S -85B9 E0102; Moji_Joho; MJ023005 -85BA E0100; Adobe-Japan1; CID+6460 -85BA E0101; Hanyo-Denshi; JA7321 -85BA E0101; Moji_Joho; MJ023006 -85BA E0102; Hanyo-Denshi; KS365520 -85BA E0102; Moji_Joho; MJ023007 -85BC E0100; Adobe-Japan1; CID+18556 -85BC E0101; Hanyo-Denshi; JB5775 -85BC E0101; Moji_Joho; MJ023009 -85BC E0102; Hanyo-Denshi; KS365560 -85BC E0102; Moji_Joho; MJ023010 -85BD E0100; Adobe-Japan1; CID+22384 -85BD E0101; Hanyo-Denshi; JB5776 -85BD E0101; Moji_Joho; MJ023011 -85BD E0102; Hanyo-Denshi; KS365580 -85BD E0102; Moji_Joho; MJ023012 -85BE E0100; Adobe-Japan1; CID+22385 -85BE E0101; Hanyo-Denshi; JB5777 -85BE E0101; Moji_Joho; MJ023013 -85BE E0102; Hanyo-Denshi; KS365620 -85BE E0102; Moji_Joho; MJ023014 -85BF E0100; Adobe-Japan1; CID+22386 -85BF E0101; Hanyo-Denshi; JB5778 -85BF E0101; Moji_Joho; MJ023015 -85BF E0102; Hanyo-Denshi; JTBA7F -85BF E0102; Moji_Joho; MJ023016 -85C1 E0100; Adobe-Japan1; CID+4084 -85C1 E0101; Hanyo-Denshi; JA4746 -85C1 E0101; Moji_Joho; MJ023018 -85C1 E0102; Hanyo-Denshi; JTBA7D -85C1 E0102; Moji_Joho; MJ023019 -85C1 E0103; Hanyo-Denshi; TK01081840 -85C1 E0104; Hanyo-Denshi; TK01082050 -85C2 E0100; Adobe-Japan1; CID+22387 -85C2 E0101; Hanyo-Denshi; JB5779 -85C2 E0101; Moji_Joho; MJ023022 -85C2 E0102; Hanyo-Denshi; KS365680 -85C2 E0102; Moji_Joho; MJ023023 -85C7 E0100; Adobe-Japan1; CID+18557 -85C7 E0101; Hanyo-Denshi; JB5780 -85C7 E0101; Moji_Joho; MJ023028 -85C7 E0102; Hanyo-Denshi; KS365770S -85C7 E0102; Moji_Joho; MJ023029 -85C9 E0100; Adobe-Japan1; CID+6459 -85C9 E0101; Hanyo-Denshi; JA7320 -85C9 E0101; Moji_Joho; MJ023031 -85C9 E0102; Hanyo-Denshi; KS365850 -85C9 E0102; Moji_Joho; MJ023032 -85C9 E0103; Hanyo-Denshi; FT2494 -85C9 E0103; Moji_Joho; MJ023033 -85CA E0100; Adobe-Japan1; CID+18558 -85CA E0101; Hanyo-Denshi; JB5781 -85CA E0101; Moji_Joho; MJ023034 -85CA E0102; Hanyo-Denshi; KS365890 -85CA E0102; Moji_Joho; MJ023035 -85CB E0100; Adobe-Japan1; CID+17097 -85CB E0101; Hanyo-Denshi; JB5782 -85CB E0101; Moji_Joho; MJ023036 -85CB E0102; Hanyo-Denshi; KS365910 -85CB E0102; Moji_Joho; MJ023037 -85CD E0100; Adobe-Japan1; CID+3935 -85CD E0101; Hanyo-Denshi; JA4585 -85CD E0101; Moji_Joho; MJ023040 -85CD E0102; Hanyo-Denshi; IB0874 -85CD E0102; Moji_Joho; MJ023041 -85CD E0103; Hanyo-Denshi; IB0368 -85CD E0103; Moji_Joho; MJ023039 -85CE E0100; Adobe-Japan1; CID+15075 -85CE E0101; Hanyo-Denshi; JB5783 -85CE E0101; Moji_Joho; MJ023042 -85CE E0102; Hanyo-Denshi; KS366050 -85CE E0102; Moji_Joho; MJ023043 -85CF E0100; Adobe-Japan1; CID+6461 -85CF E0101; Adobe-Japan1; CID+20209 -85CF E0102; Hanyo-Denshi; JA7322 -85CF E0102; Moji_Joho; MJ023044 -85CF E0103; Hanyo-Denshi; KS366070 -85CF E0103; Moji_Joho; MJ023046 -85CF E0104; Hanyo-Denshi; JTBA76 -85CF E0104; Moji_Joho; MJ023047 -85CF E0105; Hanyo-Denshi; JTBA75 -85CF E0105; Moji_Joho; MJ023045 -85D0 E0100; Adobe-Japan1; CID+6463 -85D0 E0101; Hanyo-Denshi; JA7324 -85D0 E0101; Moji_Joho; MJ023049 -85D0 E0102; Hanyo-Denshi; KS366100 -85D0 E0102; Moji_Joho; MJ023050 -85D5 E0100; Adobe-Japan1; CID+6464 -85D5 E0101; Adobe-Japan1; CID+13591 -85D5 E0102; Hanyo-Denshi; JA7325 -85D5 E0102; Moji_Joho; MJ023053 -85D5 E0103; Hanyo-Denshi; KS366790 -85D5 E0103; Moji_Joho; MJ023054 -85D5 E0104; Hanyo-Denshi; FT2501 -85D5 E0104; Moji_Joho; MJ023055 -85D8 E0100; Adobe-Japan1; CID+18559 -85D8 E0101; Hanyo-Denshi; JB5785 -85D8 E0101; Moji_Joho; MJ023058 -85D8 E0102; Hanyo-Denshi; JTBA94 -85D8 E0102; Moji_Joho; MJ023059 -85D9 E0100; Adobe-Japan1; CID+18560 -85D9 E0101; Hanyo-Denshi; JD8708 -85D9 E0101; Moji_Joho; MJ023060 -85D9 E0102; Hanyo-Denshi; KS366980 -85D9 E0102; Moji_Joho; MJ023061 -85DA E0100; Adobe-Japan1; CID+22388 -85DA E0101; Hanyo-Denshi; JB5786 -85DA E0101; Moji_Joho; MJ023063 -85DA E0102; Hanyo-Denshi; JTBA8D -85DA E0102; Moji_Joho; MJ023064 -85DA E0103; Hanyo-Denshi; KS367020 -85DA E0103; Moji_Joho; MJ023062 -85DC E0100; Adobe-Japan1; CID+6467 -85DC E0101; Hanyo-Denshi; JA7328 -85DC E0101; Moji_Joho; MJ023066 -85DC E0102; Hanyo-Denshi; JTBA95 -85DC E0102; Moji_Joho; MJ023067 -85DD E0100; Adobe-Japan1; CID+6465 -85DD E0101; Hanyo-Denshi; JA7326 -85DD E0101; Moji_Joho; MJ023068 -85DD E0102; Hanyo-Denshi; KS367110S -85DD E0102; Moji_Joho; MJ023069 -85DF E0100; Adobe-Japan1; CID+18561 -85DF E0101; Hanyo-Denshi; JB5787 -85DF E0101; Moji_Joho; MJ023070 -85DF E0102; Hanyo-Denshi; KS367140 -85DF E0102; Moji_Joho; MJ023071 -85E0 E0100; Adobe-Japan1; CID+22389 -85E0 E0101; Hanyo-Denshi; JB5788 -85E0 E0101; Moji_Joho; MJ023072 -85E0 E0102; Hanyo-Denshi; KS367150 -85E0 E0102; Moji_Joho; MJ023073 -85E1 E0100; Adobe-Japan1; CID+18562 -85E1 E0101; Hanyo-Denshi; JD8710 -85E1 E0101; Moji_Joho; MJ023075 -85E1 E0102; Hanyo-Denshi; IB0370 -85E1 E0102; Moji_Joho; MJ023076 -85E1 E0103; Hanyo-Denshi; IB0876 -85E1 E0103; Moji_Joho; MJ023074 -85E4 E0100; Adobe-Japan1; CID+3195 -85E4 E0101; Adobe-Japan1; CID+13957 -85E4 E0102; Hanyo-Denshi; JA3803 -85E4 E0102; Moji_Joho; MJ023079 -85E4 E0103; Hanyo-Denshi; JTBA8F -85E4 E0103; Moji_Joho; MJ023080 -85E4 E0104; Hanyo-Denshi; JTBA83 -85E4 E0104; Moji_Joho; MJ023081 -85E4 E0105; Hanyo-Denshi; IB2864S -85E4 E0105; Moji_Joho; MJ023082 -85E4 E0106; Hanyo-Denshi; JTBA80 -85E4 E0106; Moji_Joho; MJ060144 -85E4 E0107; Hanyo-Denshi; TK01081790 -85E4 E0108; Hanyo-Denshi; TK01082170 -85E5 E0100; Adobe-Japan1; CID+6466 -85E5 E0101; Hanyo-Denshi; JA7327 -85E5 E0101; Moji_Joho; MJ023086 -85E5 E0102; Hanyo-Denshi; KS367210 -85E5 E0102; Moji_Joho; MJ023087 -85E5 E0103; Hanyo-Denshi; JTBA93 -85E5 E0103; Moji_Joho; MJ023088 -85E5 E0104; Hanyo-Denshi; TK01081450 -85E6 E0100; Adobe-Japan1; CID+18563 -85E6 E0101; Hanyo-Denshi; JB5789 -85E6 E0101; Moji_Joho; MJ023089 -85E6 E0102; Hanyo-Denshi; KS367220 -85E6 E0102; Moji_Joho; MJ023090 -85E6 E0103; Hanyo-Denshi; TK01082080 -85E7 E0100; Hanyo-Denshi; KS367230 -85E7 E0101; Hanyo-Denshi; TK01081750 -85E8 E0100; Adobe-Japan1; CID+22390 -85E8 E0101; Hanyo-Denshi; JB5790 -85E8 E0101; Moji_Joho; MJ023094 -85E8 E0102; Hanyo-Denshi; KS367240 -85E8 E0102; Moji_Joho; MJ023095 -85E9 E0100; Adobe-Japan1; CID+3425 -85E9 E0101; Hanyo-Denshi; JA4045 -85E9 E0101; Moji_Joho; MJ023096 -85E9 E0102; Hanyo-Denshi; KS367260 -85E9 E0102; Moji_Joho; MJ023097 -85EA E0100; Adobe-Japan1; CID+6453 -85EA E0101; Hanyo-Denshi; JA7314 -85EA E0101; Moji_Joho; MJ023098 -85EA E0102; Hanyo-Denshi; JTBA91S -85EA E0102; Moji_Joho; MJ023099 -85EA E0103; Hanyo-Denshi; KS552590S -85EA E0103; Moji_Joho; MJ023100 -85EA E0104; Hanyo-Denshi; TK01081510 -85EA E0105; Hanyo-Denshi; TK01082190 -85EA E0106; Hanyo-Denshi; TK01082200 -85EB E0100; Hanyo-Denshi; KS367290 -85EB E0100; Moji_Joho; MJ023102 -85EB E0101; Hanyo-Denshi; KS368030 -85EB E0101; Moji_Joho; MJ058562 -85ED E0100; Adobe-Japan1; CID+17098 -85ED E0101; Hanyo-Denshi; JB5791 -85ED E0101; Moji_Joho; MJ023104 -85ED E0102; Hanyo-Denshi; KS367320S -85ED E0102; Moji_Joho; MJ023105 -85F0 E0100; Hanyo-Denshi; KS367350 -85F0 E0101; Hanyo-Denshi; TK01010320 -85F3 E0100; Adobe-Japan1; CID+22391 -85F3 E0101; Hanyo-Denshi; JB5792 -85F3 E0101; Moji_Joho; MJ023111 -85F3 E0102; Hanyo-Denshi; KS367580 -85F3 E0102; Moji_Joho; MJ023112 -85F4 E0100; Adobe-Japan1; CID+14208 -85F4 E0101; Hanyo-Denshi; FT2503 -85F4 E0101; Moji_Joho; MJ023113 -85F4 E0102; Hanyo-Denshi; KS367990 -85F4 E0102; Moji_Joho; MJ058559 -85F6 E0100; Adobe-Japan1; CID+18564 -85F6 E0101; Hanyo-Denshi; JB5793 -85F6 E0101; Moji_Joho; MJ023114 -85F6 E0102; Hanyo-Denshi; KS368090 -85F6 E0102; Moji_Joho; MJ023115 -85F7 E0100; Adobe-Japan1; CID+2429 -85F7 E0101; Adobe-Japan1; CID+7702 -85F7 E0102; Hanyo-Denshi; JA2983 -85F7 E0102; Moji_Joho; MJ023116 -85F7 E0103; Hanyo-Denshi; KS368150 -85F7 E0103; Moji_Joho; MJ023118 -85F7 E0104; Hanyo-Denshi; FT1823 -85F7 E0104; Moji_Joho; MJ023117 -85F9 E0100; Adobe-Japan1; CID+6468 -85F9 E0101; Hanyo-Denshi; JA7329 -85F9 E0101; Moji_Joho; MJ023120 -85F9 E0102; Hanyo-Denshi; JTBA9C -85F9 E0102; Moji_Joho; MJ023121 -85F9 E0103; Hanyo-Denshi; FT2502 -85F9 E0103; Moji_Joho; MJ023122 -85FA E0100; Adobe-Japan1; CID+6473 -85FA E0101; Hanyo-Denshi; JA7334 -85FA E0101; Moji_Joho; MJ023123 -85FA E0102; Hanyo-Denshi; KS368230 -85FA E0102; Moji_Joho; MJ023124 -85FB E0100; Adobe-Japan1; CID+2806 -85FB E0101; Hanyo-Denshi; JA3384 -85FB E0101; Moji_Joho; MJ023125 -85FB E0102; Hanyo-Denshi; KS368250 -85FB E0102; Moji_Joho; MJ023126 -85FC E0100; Adobe-Japan1; CID+22392 -85FC E0101; Hanyo-Denshi; JB5794 -85FC E0101; Moji_Joho; MJ023127 -85FC E0102; Hanyo-Denshi; KS368260 -85FC E0102; Moji_Joho; MJ023128 -85FC E0103; Hanyo-Denshi; KS369210 -85FC E0103; Moji_Joho; MJ023129 -85FC E0104; Hanyo-Denshi; TK01082320 -85FE E0100; Adobe-Japan1; CID+6472 -85FE E0101; Hanyo-Denshi; JA7333 -85FE E0101; Moji_Joho; MJ023132 -85FE E0102; Hanyo-Denshi; KS368290 -85FE E0102; Moji_Joho; MJ023133 -85FE E0103; Hanyo-Denshi; FT2505 -85FE E0103; Moji_Joho; MJ023134 -85FF E0100; Adobe-Japan1; CID+17099 -85FF E0101; Hanyo-Denshi; JB5801 -85FF E0101; Moji_Joho; MJ023135 -85FF E0102; Hanyo-Denshi; JTBAA0 -85FF E0102; Moji_Joho; MJ023136 -8600 E0100; Adobe-Japan1; CID+18565 -8600 E0101; Hanyo-Denshi; JB5802 -8600 E0101; Moji_Joho; MJ023137 -8600 E0102; Hanyo-Denshi; KS369240S -8600 E0102; Moji_Joho; MJ023138 -8602 E0100; Adobe-Japan1; CID+6441 -8602 E0101; Hanyo-Denshi; JA7302 -8602 E0101; Moji_Joho; MJ023140 -8602 E0102; Hanyo-Denshi; IB0363 -8602 E0102; Moji_Joho; MJ023141 -8604 E0100; Adobe-Japan1; CID+17100 -8604 E0101; Hanyo-Denshi; JB5803 -8604 E0101; Moji_Joho; MJ023143 -8604 E0102; Hanyo-Denshi; KS368400 -8604 E0102; Moji_Joho; MJ023144 -8605 E0100; Adobe-Japan1; CID+17101 -8605 E0101; Hanyo-Denshi; JB5804 -8605 E0101; Moji_Joho; MJ023145 -8605 E0102; Hanyo-Denshi; KS368440 -8605 E0102; Moji_Joho; MJ023146 -8606 E0100; Adobe-Japan1; CID+6474 -8606 E0101; Hanyo-Denshi; JA7335 -8606 E0101; Moji_Joho; MJ023147 -8606 E0102; Hanyo-Denshi; JTBA9FS -8606 E0102; Moji_Joho; MJ023148 -8606 E0103; Hanyo-Denshi; TK01082250 -8607 E0100; Adobe-Japan1; CID+2763 -8607 E0101; Hanyo-Denshi; JA3341 -8607 E0101; Moji_Joho; MJ023150 -8607 E0102; Hanyo-Denshi; KS368020 -8607 E0102; Moji_Joho; MJ023151 -8607 E0103; Hanyo-Denshi; KS366710 -8607 E0103; Moji_Joho; MJ023149 -8607 E0104; Hanyo-Denshi; JTBA9E -8607 E0104; Moji_Joho; MJ023152 -860A E0100; Adobe-Japan1; CID+6469 -860A E0101; Hanyo-Denshi; JA7330 -860A E0101; Moji_Joho; MJ023155 -860A E0102; Hanyo-Denshi; KS368560 -860A E0102; Moji_Joho; MJ023156 -860B E0100; Adobe-Japan1; CID+6471 -860B E0101; Hanyo-Denshi; JA7332 -860B E0101; Moji_Joho; MJ023157 -860B E0102; Hanyo-Denshi; KS368570 -860B E0102; Moji_Joho; MJ023158 -860B E0103; Hanyo-Denshi; FT2504 -860B E0103; Moji_Joho; MJ023159 -860D E0100; Adobe-Japan1; CID+22393 -860D E0101; Hanyo-Denshi; JB5805 -860D E0101; Moji_Joho; MJ023162 -860D E0102; Hanyo-Denshi; KS368760 -860D E0102; Moji_Joho; MJ023161 -860E E0100; Adobe-Japan1; CID+22394 -860E E0101; Hanyo-Denshi; JB5806 -860E E0101; Moji_Joho; MJ023165 -860E E0102; Hanyo-Denshi; KS368790 -860E E0102; Moji_Joho; MJ023166 -8610 E0100; Adobe-Japan1; CID+17102 -8610 E0101; Hanyo-Denshi; JB5807 -8610 E0101; Moji_Joho; MJ023168 -8610 E0102; Hanyo-Denshi; KS368920 -8610 E0102; Moji_Joho; MJ023169 -8611 E0100; Adobe-Japan1; CID+18566 -8611 E0101; Hanyo-Denshi; JB5808 -8611 E0101; Moji_Joho; MJ023170 -8611 E0102; Hanyo-Denshi; KS368940 -8611 E0102; Moji_Joho; MJ023171 -8612 E0100; Adobe-Japan1; CID+15077 -8612 E0101; Adobe-Japan1; CID+8612 -8612 E0102; Adobe-Japan1; CID+21073 -8612 E0103; Hanyo-Denshi; JB5809 -8612 E0103; Moji_Joho; MJ023172 -8612 E0104; Hanyo-Denshi; JTBAA1 -8612 E0104; Moji_Joho; MJ023173 -8612 E0105; Hanyo-Denshi; JD8724 -8612 E0105; Moji_Joho; MJ030224 -8612 E0106; Hanyo-Denshi; JTBA9B -8612 E0106; Moji_Joho; MJ060150 -8612 E0107; Hanyo-Denshi; JTBAAD -8612 E0107; Moji_Joho; MJ030221 -8612 E0108; Hanyo-Denshi; JTBAAE -8612 E0108; Moji_Joho; MJ030222 -8612 E0109; Moji_Joho; MJ030220 -8612 E010A; Moji_Joho; MJ030223 -8613 E0100; Adobe-Japan1; CID+6470 -8613 E0101; Hanyo-Denshi; JA7331 -8613 E0101; Moji_Joho; MJ023174 -8613 E0102; Hanyo-Denshi; KS369220 -8613 E0102; Moji_Joho; MJ023175 -8616 E0100; Adobe-Japan1; CID+5328 -8616 E0101; Hanyo-Denshi; JA6117 -8616 E0101; Moji_Joho; MJ023178 -8616 E0102; Hanyo-Denshi; KS369250 -8616 E0102; Moji_Joho; MJ023179 -8616 E0103; Hanyo-Denshi; JTBA9A -8616 E0103; Moji_Joho; MJ060149 -8617 E0100; Adobe-Japan1; CID+5313 -8617 E0101; Hanyo-Denshi; JA6102 -8617 E0101; Moji_Joho; MJ023180 -8617 E0102; Hanyo-Denshi; KS369260 -8617 E0102; Moji_Joho; MJ023181 -8618 E0100; Adobe-Japan1; CID+17104 -8618 E0101; Hanyo-Denshi; JB5810 -8618 E0101; Moji_Joho; MJ023183 -8618 E0102; Hanyo-Denshi; KS369270 -8618 E0102; Moji_Joho; MJ023182 -8618 E0103; Hanyo-Denshi; JTBAA4 -8618 E0103; Moji_Joho; MJ023184 -8619 E0100; Adobe-Japan1; CID+22395 -8619 E0101; Hanyo-Denshi; JB5811 -8619 E0101; Moji_Joho; MJ023185 -8619 E0102; Hanyo-Denshi; KS369290 -8619 E0102; Moji_Joho; MJ023186 -8619 E0103; Hanyo-Denshi; KS369960 -8619 E0103; Moji_Joho; MJ023187 -8619 E0104; Hanyo-Denshi; TK01082350 -861A E0100; Adobe-Japan1; CID+6476 -861A E0101; Hanyo-Denshi; JA7337 -861A E0101; Moji_Joho; MJ023189 -861A E0102; Hanyo-Denshi; KS369300 -861A E0102; Moji_Joho; MJ023190 -861A E0103; Hanyo-Denshi; KS368010 -861A E0103; Moji_Joho; MJ058561 -861B E0100; Adobe-Japan1; CID+22396 -861B E0101; Hanyo-Denshi; JB5812 -861B E0101; Moji_Joho; MJ023191 -861B E0102; Hanyo-Denshi; KS369320 -861B E0102; Moji_Joho; MJ023192 -861E E0100; Adobe-Japan1; CID+18567 -861E E0101; Hanyo-Denshi; JB5813 -861E E0101; Moji_Joho; MJ023194 -861E E0102; Hanyo-Denshi; JTBAA9 -861E E0102; Moji_Joho; MJ023195 -8621 E0100; Adobe-Japan1; CID+18568 -8621 E0101; Hanyo-Denshi; JB5814 -8621 E0101; Moji_Joho; MJ023198 -8621 E0102; Hanyo-Denshi; KS369410 -8621 E0102; Moji_Joho; MJ023199 -8622 E0100; Adobe-Japan1; CID+6475 -8622 E0101; Hanyo-Denshi; JA7336 -8622 E0101; Moji_Joho; MJ023200 -8622 E0102; Hanyo-Denshi; KS369200 -8622 E0102; Moji_Joho; MJ023202 -8622 E0103; Hanyo-Denshi; KS368600 -8622 E0103; Moji_Joho; MJ023201 -8624 E0100; Adobe-Japan1; CID+18569 -8624 E0101; Hanyo-Denshi; JD8717 -8624 E0101; Moji_Joho; MJ023205 -8624 E0102; Hanyo-Denshi; KS369480 -8624 E0102; Moji_Joho; MJ023206 -8624 E0103; Hanyo-Denshi; KS369170 -8624 E0103; Moji_Joho; MJ023204 -8627 E0100; Adobe-Japan1; CID+18570 -8627 E0101; Hanyo-Denshi; JB5815 -8627 E0101; Moji_Joho; MJ023210 -8627 E0102; Hanyo-Denshi; IB0372 -8627 E0102; Moji_Joho; MJ023211 -8627 E0103; Hanyo-Denshi; IB0878 -8627 E0103; Moji_Joho; MJ023209 -8628 E0100; Hanyo-Denshi; KS369560 -8628 E0101; Hanyo-Denshi; TK01082360 -8629 E0100; Adobe-Japan1; CID+15078 -8629 E0101; Hanyo-Denshi; JB5816 -8629 E0101; Moji_Joho; MJ023214 -8629 E0102; Hanyo-Denshi; KS369570S -8629 E0102; Moji_Joho; MJ023215 -8629 E0103; Hanyo-Denshi; JTBA99 -8629 E0103; Moji_Joho; MJ023216 -862B E0100; Hanyo-Denshi; KS369600 -862B E0101; Hanyo-Denshi; TK01082390 -862D E0100; Adobe-Japan1; CID+3936 -862D E0101; Adobe-Japan1; CID+14084 -862D E0102; Hanyo-Denshi; JA4586 -862D E0102; Moji_Joho; MJ023221 -862D E0103; Hanyo-Denshi; KS369630 -862D E0103; Moji_Joho; MJ023223 -862D E0104; Hanyo-Denshi; JTBAA3 -862D E0104; Moji_Joho; MJ023222 -862D E0105; Hanyo-Denshi; TK01082230 -862F E0100; Adobe-Japan1; CID+5809 -862F E0101; Hanyo-Denshi; JA6628 -862F E0101; Moji_Joho; MJ023226 -862F E0102; Hanyo-Denshi; KS369760 -862F E0102; Moji_Joho; MJ023227 -8630 E0100; Adobe-Japan1; CID+6477 -8630 E0101; Hanyo-Denshi; JA7338 -8630 E0101; Moji_Joho; MJ023228 -8630 E0102; Hanyo-Denshi; KS369830 -8630 E0102; Moji_Joho; MJ023230 -8630 E0103; Moji_Joho; MJ023229 -8636 E0100; Adobe-Japan1; CID+22397 -8636 E0101; Hanyo-Denshi; JB5817 -8636 E0101; Moji_Joho; MJ023237 -8636 E0102; Hanyo-Denshi; JTBAAA -8636 E0102; Moji_Joho; MJ023238 -8636 E0103; Hanyo-Denshi; KS370150 -8636 E0103; Moji_Joho; MJ023236 -8638 E0100; Adobe-Japan1; CID+17105 -8638 E0101; Hanyo-Denshi; JB5818 -8638 E0101; Moji_Joho; MJ023239 -8638 E0102; Hanyo-Denshi; KS370420 -8638 E0102; Moji_Joho; MJ023240 -8639 E0100; Adobe-Japan1; CID+18572 -8639 E0101; Hanyo-Denshi; JD8720 -8639 E0101; Moji_Joho; MJ023241 -8639 E0102; Hanyo-Denshi; KS370440 -8639 E0102; Moji_Joho; MJ023242 -863A E0100; Adobe-Japan1; CID+22398 -863A E0101; Hanyo-Denshi; JB5819 -863A E0101; Moji_Joho; MJ023243 -863A E0102; Hanyo-Denshi; KS370480 -863A E0102; Moji_Joho; MJ023244 -863C E0100; Adobe-Japan1; CID+18573 -863C E0101; Hanyo-Denshi; JB5820 -863C E0101; Moji_Joho; MJ023246 -863C E0102; Hanyo-Denshi; KS370510 -863C E0102; Moji_Joho; MJ023247 -863D E0100; Adobe-Japan1; CID+22399 -863D E0101; Hanyo-Denshi; JB5821 -863D E0101; Moji_Joho; MJ023248 -863D E0102; Hanyo-Denshi; JTBAAB -863D E0102; Moji_Joho; MJ023249 -863F E0100; Adobe-Japan1; CID+6478 -863F E0101; Hanyo-Denshi; JA7339 -863F E0101; Moji_Joho; MJ023251 -863F E0102; Hanyo-Denshi; KS370580 -863F E0102; Moji_Joho; MJ023252 -8640 E0100; Adobe-Japan1; CID+18575 -8640 E0101; Hanyo-Denshi; JB5822 -8640 E0101; Moji_Joho; MJ023253 -8640 E0102; Hanyo-Denshi; KS370590 -8640 E0102; Moji_Joho; MJ023254 -8641 E0100; Adobe-Japan1; CID+16824 -8641 E0101; Hanyo-Denshi; JB2470 -8641 E0101; Moji_Joho; MJ023258 -8641 E0102; Hanyo-Denshi; IB1618 -8641 E0102; Moji_Joho; MJ023257 -8641 E0103; Hanyo-Denshi; JTAFB0 -8641 E0103; Moji_Joho; MJ023255 -8641 E0104; Moji_Joho; MJ023256 -8642 E0100; Adobe-Japan1; CID+19753 -8642 E0101; Hanyo-Denshi; JB5823 -8642 E0101; Moji_Joho; MJ023259 -8642 E0102; Hanyo-Denshi; KS370840 -8642 E0102; Moji_Joho; MJ023260 -8646 E0100; Adobe-Japan1; CID+19754 -8646 E0101; Hanyo-Denshi; JB5824 -8646 E0101; Moji_Joho; MJ023263 -8646 E0102; Hanyo-Denshi; KS371040 -8646 E0102; Moji_Joho; MJ023264 -864B E0100; Hanyo-Denshi; KS371440S -864B E0100; Moji_Joho; MJ023269 -864B E0101; Hanyo-Denshi; KS371470 -864B E0101; Moji_Joho; MJ058575 -864D E0100; Adobe-Japan1; CID+6479 -864E E0100; Adobe-Japan1; CID+1931 -864E E0101; Adobe-Japan1; CID+20210 -864E E0102; Hanyo-Denshi; JA2455 -864E E0102; Moji_Joho; MJ023272 -864E E0103; Hanyo-Denshi; KS371630 -864E E0103; Moji_Joho; MJ023273 -864E E0104; Hanyo-Denshi; TK01082610 -864E E0105; Hanyo-Denshi; TK01082630 -864E E0106; Hanyo-Denshi; TK01082640 -864E E0107; Hanyo-Denshi; TK01082660 -8650 E0100; Adobe-Japan1; CID+1646 -8650 E0101; Adobe-Japan1; CID+13708 -8650 E0102; Hanyo-Denshi; JA2152 -8650 E0102; Moji_Joho; MJ023279 -8650 E0103; Hanyo-Denshi; IB2873 -8650 E0103; Moji_Joho; MJ023278 -8652 E0100; Adobe-Japan1; CID+15079 -8652 E0101; Hanyo-Denshi; JB5825 -8652 E0102; Hanyo-Denshi; TK01082820 -8653 E0100; Adobe-Japan1; CID+18576 -8653 E0101; Moji_Joho; MJ023283 -8653 E0102; Moji_Joho; MJ023284 -8654 E0100; Adobe-Japan1; CID+6481 -8654 E0101; Adobe-Japan1; CID+20274 -8654 E0102; Moji_Joho; MJ023285 -8654 E0103; Moji_Joho; MJ023286 -8655 E0100; Adobe-Japan1; CID+4244 -8656 E0100; Adobe-Japan1; CID+18577 -8657 E0100; Adobe-Japan1; CID+17106 -8658 E0100; Adobe-Japan1; CID+22400 -8659 E0100; Adobe-Japan1; CID+22401 -865A E0100; Adobe-Japan1; CID+1679 -865B E0100; Adobe-Japan1; CID+13336 -865C E0100; Adobe-Japan1; CID+13394 -865C E0101; Adobe-Japan1; CID+3970 -865C E0102; Hanyo-Denshi; JA4626 -865C E0103; Hanyo-Denshi; JC9147 -865D E0100; Adobe-Japan1; CID+22402 -865E E0100; Adobe-Japan1; CID+1771 -865E E0101; Adobe-Japan1; CID+13734 -865E E0102; Hanyo-Denshi; JA2283 -865E E0102; Moji_Joho; MJ023297 -865E E0103; Hanyo-Denshi; JTBAB6 -865E E0103; Moji_Joho; MJ023296 -865E E0104; Hanyo-Denshi; TK01082960 -865F E0100; Adobe-Japan1; CID+6482 -865F E0101; Hanyo-Denshi; JA7343 -865F E0102; Hanyo-Denshi; TK01082970 -8660 E0100; Adobe-Japan1; CID+22403 -8661 E0100; Adobe-Japan1; CID+22404 -8662 E0100; Adobe-Japan1; CID+17107 -8662 E0101; Adobe-Japan1; CID+20211 -8663 E0100; Adobe-Japan1; CID+15080 -8664 E0100; Adobe-Japan1; CID+22405 -8667 E0100; Adobe-Japan1; CID+6483 -8667 E0101; Hanyo-Denshi; JA7344 -8667 E0101; Moji_Joho; MJ023308 -8667 E0102; Hanyo-Denshi; KS372790 -8667 E0102; Moji_Joho; MJ023309 -8669 E0100; Adobe-Japan1; CID+22406 -866A E0100; Hanyo-Denshi; IP866A -866A E0100; Moji_Joho; MJ023312 -866A E0101; Hanyo-Denshi; KS373080 -866A E0101; Moji_Joho; MJ023313 -866B E0100; Adobe-Japan1; CID+2988 -866C E0100; Adobe-Japan1; CID+15081 -866F E0100; Adobe-Japan1; CID+15082 -8671 E0100; Adobe-Japan1; CID+6484 -8675 E0100; Adobe-Japan1; CID+17109 -8676 E0100; Adobe-Japan1; CID+22407 -8677 E0100; Adobe-Japan1; CID+18578 -8679 E0100; Adobe-Japan1; CID+3282 -867A E0100; Adobe-Japan1; CID+15083 -867B E0100; Adobe-Japan1; CID+1150 -867B E0101; Hanyo-Denshi; JA1626 -867B E0101; Moji_Joho; MJ023329 -867B E0102; Hanyo-Denshi; JTBABA -867B E0102; Moji_Joho; MJ023330 -867D E0100; Adobe-Japan1; CID+14214 -8687 E0100; Adobe-Japan1; CID+18579 -8688 E0100; Adobe-Japan1; CID+22425 -8688 E0101; Hanyo-Denshi; JB5877 -8688 E0101; Moji_Joho; MJ023338 -8688 E0102; Hanyo-Denshi; KS373630 -8688 E0102; Moji_Joho; MJ023337 -8689 E0100; Adobe-Japan1; CID+18580 -8689 E0101; Moji_Joho; MJ023339 -8689 E0102; Moji_Joho; MJ023340 -868A E0100; Adobe-Japan1; CID+1379 -868A E0101; Adobe-Japan1; CID+20212 -868A E0102; Moji_Joho; MJ023341 -868A E0103; Moji_Joho; MJ023342 -868B E0100; Adobe-Japan1; CID+6489 -868B E0101; Hanyo-Denshi; JA7350 -868B E0101; Moji_Joho; MJ023343 -868B E0102; Hanyo-Denshi; FT2508 -868B E0102; Moji_Joho; MJ023344 -868C E0100; Adobe-Japan1; CID+6490 -868C E0101; Hanyo-Denshi; JA7351 -868C E0101; Moji_Joho; MJ023345 -868C E0102; Hanyo-Denshi; JTBABF -868C E0102; Moji_Joho; MJ023346 -868D E0100; Adobe-Japan1; CID+15084 -8691 E0100; Adobe-Japan1; CID+15085 -8693 E0100; Adobe-Japan1; CID+6485 -8695 E0100; Adobe-Japan1; CID+2187 -8696 E0100; Adobe-Japan1; CID+22408 -8698 E0100; Adobe-Japan1; CID+15086 -869A E0100; Adobe-Japan1; CID+22409 -869C E0100; Adobe-Japan1; CID+18581 -869C E0101; Hanyo-Denshi; JB5849 -869C E0101; Moji_Joho; MJ023363 -869C E0102; Hanyo-Denshi; JD8734S -869C E0102; Moji_Joho; MJ023362 -869D E0100; Adobe-Japan1; CID+18582 -86A1 E0100; Adobe-Japan1; CID+22410 -86A3 E0100; Adobe-Japan1; CID+6486 -86A3 E0101; Hanyo-Denshi; JA7347 -86A3 E0101; Moji_Joho; MJ023370 -86A3 E0102; Hanyo-Denshi; FT2507 -86A3 E0102; Moji_Joho; MJ023371 -86A4 E0100; Adobe-Japan1; CID+3320 -86A4 E0101; Hanyo-Denshi; JA3934 -86A4 E0101; Moji_Joho; MJ023372 -86A4 E0102; Hanyo-Denshi; KS375130 -86A4 E0102; Moji_Joho; MJ058609 -86A6 E0100; Adobe-Japan1; CID+22411 -86A7 E0100; Adobe-Japan1; CID+15087 -86A8 E0100; Adobe-Japan1; CID+15088 -86A9 E0100; Adobe-Japan1; CID+6487 -86A9 E0101; Hanyo-Denshi; JA7348 -86A9 E0101; Moji_Joho; MJ023377 -86A9 E0102; Hanyo-Denshi; KS374340 -86A9 E0102; Moji_Joho; MJ058606 -86A9 E0103; Hanyo-Denshi; KS374940 -86A9 E0103; Moji_Joho; MJ023378 -86AA E0100; Adobe-Japan1; CID+6488 -86AB E0100; Adobe-Japan1; CID+6498 -86AB E0101; Hanyo-Denshi; JA7359 -86AB E0101; Moji_Joho; MJ023380 -86AB E0102; Hanyo-Denshi; FT2509 -86AB E0102; Moji_Joho; MJ023381 -86AB E0103; Hanyo-Denshi; KS374240 -86AB E0103; Moji_Joho; MJ058601 -86AD E0100; Adobe-Japan1; CID+22412 -86AF E0100; Adobe-Japan1; CID+6492 -86B0 E0100; Adobe-Japan1; CID+6495 -86B1 E0100; Adobe-Japan1; CID+18583 -86B3 E0100; Adobe-Japan1; CID+18584 -86B4 E0100; Adobe-Japan1; CID+22413 -86B5 E0100; Adobe-Japan1; CID+22414 -86B6 E0100; Adobe-Japan1; CID+6491 -86B7 E0100; Adobe-Japan1; CID+22415 -86B8 E0100; Adobe-Japan1; CID+17110 -86B9 E0100; Adobe-Japan1; CID+22416 -86BF E0100; Adobe-Japan1; CID+22417 -86C0 E0100; Adobe-Japan1; CID+19755 -86C1 E0100; Adobe-Japan1; CID+18585 -86C3 E0100; Adobe-Japan1; CID+18586 -86C4 E0100; Adobe-Japan1; CID+6493 -86C5 E0100; Adobe-Japan1; CID+22418 -86C6 E0100; Adobe-Japan1; CID+6494 -86C7 E0100; Adobe-Japan1; CID+2308 -86C9 E0100; Adobe-Japan1; CID+6496 -86CB E0100; Adobe-Japan1; CID+2943 -86CD E0100; Adobe-Japan1; CID+1836 -86CE E0100; Adobe-Japan1; CID+1440 -86D1 E0100; Adobe-Japan1; CID+18587 -86D2 E0100; Adobe-Japan1; CID+22419 -86D4 E0100; Adobe-Japan1; CID+6499 -86D5 E0100; Adobe-Japan1; CID+18588 -86D7 E0100; Adobe-Japan1; CID+18589 -86D9 E0100; Adobe-Japan1; CID+1437 -86DA E0100; Adobe-Japan1; CID+22420 -86DB E0100; Adobe-Japan1; CID+6504 -86DB E0101; Adobe-Japan1; CID+13406 -86DC E0100; Adobe-Japan1; CID+22421 -86DE E0100; Adobe-Japan1; CID+6500 -86DF E0100; Adobe-Japan1; CID+6503 -86DF E0101; Moji_Joho; MJ023431 -86DF E0102; Moji_Joho; MJ023432 -86E0 E0100; Adobe-Japan1; CID+22422 -86E2 E0100; Hanyo-Denshi; IP86E2 -86E2 E0100; Moji_Joho; MJ023435 -86E2 E0101; Hanyo-Denshi; KS377560 -86E2 E0101; Moji_Joho; MJ023436 -86E3 E0100; Adobe-Japan1; CID+18590 -86E4 E0100; Adobe-Japan1; CID+3406 -86E5 E0100; Adobe-Japan1; CID+22423 -86E6 E0100; Adobe-Japan1; CID+18591 -86E7 E0100; Adobe-Japan1; CID+22424 -86E7 E0101; Hanyo-Denshi; JB5876 -86E7 E0101; Moji_Joho; MJ023441 -86E7 E0102; Hanyo-Denshi; KS376040 -86E7 E0102; Moji_Joho; MJ023442 -86E9 E0100; Adobe-Japan1; CID+6501 -86E9 E0101; Hanyo-Denshi; JA7362 -86E9 E0101; Moji_Joho; MJ023444 -86E9 E0102; Hanyo-Denshi; KS375960 -86E9 E0102; Moji_Joho; MJ023445 -86E9 E0103; Hanyo-Denshi; JTBAC4 -86E9 E0103; Moji_Joho; MJ023446 -86EA E0100; Hanyo-Denshi; IP86EA -86EA E0100; Moji_Joho; MJ023447 -86EA E0101; Hanyo-Denshi; KS376010 -86EA E0101; Moji_Joho; MJ023448 -86EB E0100; Hanyo-Denshi; IP86EB -86EB E0100; Moji_Joho; MJ023449 -86EB E0101; Hanyo-Denshi; KS376030 -86EB E0101; Moji_Joho; MJ023450 -86EC E0100; Adobe-Japan1; CID+6502 -86ED E0100; Adobe-Japan1; CID+3514 -86EE E0100; Adobe-Japan1; CID+3438 -86EF E0100; Adobe-Japan1; CID+6505 -86F8 E0100; Adobe-Japan1; CID+2909 -86F8 E0101; Adobe-Japan1; CID+7733 -86F8 E0102; Hanyo-Denshi; JA3493 -86F8 E0102; Moji_Joho; MJ023459 -86F8 E0103; Hanyo-Denshi; FT1853 -86F8 E0103; Moji_Joho; MJ023458 -86F9 E0100; Adobe-Japan1; CID+6515 -86FA E0100; Adobe-Japan1; CID+15089 -86FB E0100; Adobe-Japan1; CID+6511 -86FB E0101; Hanyo-Denshi; JA7372 -86FB E0101; Moji_Joho; MJ023462 -86FB E0102; Hanyo-Denshi; JTBACF -86FB E0102; Moji_Joho; MJ023463 -86FC E0100; Adobe-Japan1; CID+17111 -86FD E0100; Adobe-Japan1; CID+15090 -86FE E0100; Adobe-Japan1; CID+1387 -8700 E0100; Adobe-Japan1; CID+6509 -8702 E0100; Adobe-Japan1; CID+3672 -8703 E0100; Adobe-Japan1; CID+6510 -8703 E0101; Adobe-Japan1; CID+20296 -8703 E0102; Moji_Joho; MJ023471 -8703 E0103; Moji_Joho; MJ023472 -8704 E0100; Adobe-Japan1; CID+22426 -8705 E0100; Adobe-Japan1; CID+18593 -8706 E0100; Adobe-Japan1; CID+6507 -8707 E0100; Adobe-Japan1; CID+18594 -8708 E0100; Adobe-Japan1; CID+6508 -8708 E0101; Hanyo-Denshi; JA7369 -8708 E0101; Moji_Joho; MJ023477 -8708 E0102; Hanyo-Denshi; FT2512 -8708 E0102; Moji_Joho; MJ023478 -8709 E0100; Adobe-Japan1; CID+6513 -8709 E0101; Hanyo-Denshi; JA7374 -8709 E0101; Moji_Joho; MJ023479 -8709 E0102; Hanyo-Denshi; FT2515 -8709 E0102; Moji_Joho; MJ023480 -870A E0100; Adobe-Japan1; CID+6516 -870B E0100; Adobe-Japan1; CID+15091 -870D E0100; Adobe-Japan1; CID+6514 -870E E0100; Adobe-Japan1; CID+18595 -870E E0101; Hanyo-Denshi; JB5885 -870E E0101; Moji_Joho; MJ023485 -870E E0102; Hanyo-Denshi; KS375990 -870E E0102; Moji_Joho; MJ058615 -870F E0100; Adobe-Japan1; CID+22427 -8710 E0100; Adobe-Japan1; CID+18596 -8711 E0100; Adobe-Japan1; CID+6512 -8711 E0101; Hanyo-Denshi; JA7373 -8711 E0101; Moji_Joho; MJ023488 -8711 E0102; Hanyo-Denshi; FT2514 -8711 E0102; Moji_Joho; MJ023489 -8712 E0100; Adobe-Japan1; CID+6506 -8712 E0101; Hanyo-Denshi; JA7367 -8712 E0101; Moji_Joho; MJ023490 -8712 E0102; Hanyo-Denshi; FT2511 -8712 E0102; Moji_Joho; MJ023491 -8712 E0103; Moji_Joho; MJ023492 -8713 E0100; Adobe-Japan1; CID+15092 -8714 E0100; Adobe-Japan1; CID+19756 -8718 E0100; Adobe-Japan1; CID+2966 -8719 E0100; Adobe-Japan1; CID+15093 -871A E0100; Adobe-Japan1; CID+6523 -871A E0101; Adobe-Japan1; CID+13592 -871A E0102; Moji_Joho; MJ023498 -871A E0103; Moji_Joho; MJ023499 -871C E0100; Adobe-Japan1; CID+3766 -871E E0100; Adobe-Japan1; CID+15094 -871F E0100; Adobe-Japan1; CID+18597 -8721 E0100; Adobe-Japan1; CID+18598 -8722 E0100; Adobe-Japan1; CID+19757 -8723 E0100; Adobe-Japan1; CID+18599 -8725 E0100; Adobe-Japan1; CID+6521 -8728 E0100; Adobe-Japan1; CID+15095 -8729 E0100; Adobe-Japan1; CID+6522 -8729 E0101; Hanyo-Denshi; JA7383 -8729 E0101; Moji_Joho; MJ023514 -8729 E0102; Hanyo-Denshi; FT2518 -8729 E0102; Moji_Joho; MJ023515 -872E E0100; Adobe-Japan1; CID+19758 -872F E0100; Adobe-Japan1; CID+22428 -8731 E0100; Adobe-Japan1; CID+18600 -8732 E0100; Adobe-Japan1; CID+22429 -8734 E0100; Adobe-Japan1; CID+6517 -8737 E0100; Adobe-Japan1; CID+6519 -8737 E0101; Adobe-Japan1; CID+14210 -8737 E0102; Hanyo-Denshi; JA7380 -8737 E0102; Moji_Joho; MJ023529 -8737 E0103; Hanyo-Denshi; FT2516 -8737 E0103; Moji_Joho; MJ023530 -8737 E0104; Hanyo-Denshi; TK01083200 -8739 E0100; Adobe-Japan1; CID+19759 -8739 E0101; Hanyo-Denshi; JB5906 -8739 E0101; Moji_Joho; MJ023533 -8739 E0102; Hanyo-Denshi; KS377590 -8739 E0102; Moji_Joho; MJ023534 -873A E0100; Adobe-Japan1; CID+18601 -873B E0100; Adobe-Japan1; CID+6520 -873B E0101; Adobe-Japan1; CID+14211 -873B E0102; Hanyo-Denshi; JA7381 -873B E0102; Moji_Joho; MJ023536 -873B E0103; Hanyo-Denshi; FT2517 -873B E0103; Moji_Joho; MJ023537 -873C E0100; Adobe-Japan1; CID+22430 -873D E0100; Adobe-Japan1; CID+22431 -873E E0100; Adobe-Japan1; CID+15096 -873F E0100; Adobe-Japan1; CID+6518 -8740 E0100; Adobe-Japan1; CID+18602 -8743 E0100; Adobe-Japan1; CID+18603 -8744 E0100; Hanyo-Denshi; IB2884 -8744 E0100; Moji_Joho; MJ023546 -8744 E0101; Hanyo-Denshi; KS378190 -8744 E0101; Moji_Joho; MJ058634 -8745 E0100; Adobe-Japan1; CID+22432 -8745 E0101; Moji_Joho; MJ023547 -8745 E0102; Moji_Joho; MJ023548 -8749 E0100; Adobe-Japan1; CID+2698 -874B E0100; Adobe-Japan1; CID+4063 -874C E0100; Adobe-Japan1; CID+6527 -874D E0100; Adobe-Japan1; CID+22433 -874D E0101; Hanyo-Denshi; JB5914 -874D E0101; Moji_Joho; MJ023554 -874D E0102; Hanyo-Denshi; JTBADA -874D E0102; Moji_Joho; MJ023555 -874E E0100; Adobe-Japan1; CID+6528 -874E E0101; Hanyo-Denshi; JA7389 -874E E0101; Moji_Joho; MJ023556 -874E E0102; Hanyo-Denshi; FT2519 -874E E0102; Moji_Joho; MJ023557 -8750 E0100; Hanyo-Denshi; IP8750 -8750 E0100; Moji_Joho; MJ023559 -8750 E0101; Hanyo-Denshi; KS379530 -8750 E0101; Moji_Joho; MJ023560 -8751 E0100; Adobe-Japan1; CID+18604 -8753 E0100; Adobe-Japan1; CID+6534 -8753 E0101; Hanyo-Denshi; JA7401 -8753 E0101; Moji_Joho; MJ023563 -8753 E0102; Hanyo-Denshi; FT2520 -8753 E0102; Moji_Joho; MJ023564 -8755 E0100; Adobe-Japan1; CID+2544 -8755 E0101; Adobe-Japan1; CID+7709 -8755 E0102; Hanyo-Denshi; JA3110 -8755 E0102; Moji_Joho; MJ023566 -8755 E0103; Hanyo-Denshi; FT1830 -8755 E0103; Moji_Joho; MJ023567 -8757 E0100; Adobe-Japan1; CID+6530 -8758 E0100; Adobe-Japan1; CID+18605 -8758 E0101; Hanyo-Denshi; JB5915 -8758 E0101; Moji_Joho; MJ023570 -8758 E0102; Hanyo-Denshi; KS379560 -8758 E0102; Moji_Joho; MJ023571 -8759 E0100; Adobe-Japan1; CID+6533 -8759 E0101; Adobe-Japan1; CID+8000 -8759 E0102; Hanyo-Denshi; JA7394 -8759 E0102; Moji_Joho; MJ023573 -8759 E0103; Hanyo-Denshi; JTBAD9 -8759 E0103; Moji_Joho; MJ023572 -875D E0100; Adobe-Japan1; CID+19760 -875D E0101; Hanyo-Denshi; JB5916 -875D E0101; Moji_Joho; MJ023577 -875D E0102; Hanyo-Denshi; IB2885 -875D E0102; Moji_Joho; MJ023578 -875F E0100; Adobe-Japan1; CID+6525 -8760 E0100; Adobe-Japan1; CID+6524 -8761 E0100; Adobe-Japan1; CID+22434 -8763 E0100; Adobe-Japan1; CID+6535 -8764 E0100; Adobe-Japan1; CID+18606 -8765 E0100; Adobe-Japan1; CID+18607 -8766 E0100; Adobe-Japan1; CID+1372 -8768 E0100; Adobe-Japan1; CID+6531 -876A E0100; Adobe-Japan1; CID+6536 -876B E0100; Hanyo-Denshi; IP876B -876B E0101; Hanyo-Denshi; TK01083260 -876E E0100; Adobe-Japan1; CID+6532 -876F E0100; Adobe-Japan1; CID+22435 -8771 E0100; Adobe-Japan1; CID+15097 -8771 E0101; Hanyo-Denshi; JB5921 -8771 E0101; Moji_Joho; MJ023599 -8771 E0102; Hanyo-Denshi; KS379550 -8771 E0102; Moji_Joho; MJ023600 -8772 E0100; Adobe-Japan1; CID+18608 -8773 E0100; Hanyo-Denshi; IP8773 -8773 E0100; Moji_Joho; MJ023602 -8773 E0101; Hanyo-Denshi; JT8773 -8773 E0101; Moji_Joho; MJ023603 -8773 E0102; Moji_Joho; MJ023604 -8774 E0100; Adobe-Japan1; CID+6529 -8776 E0100; Adobe-Japan1; CID+3023 -8777 E0100; Moji_Joho; MJ023608 -8777 E0101; Moji_Joho; MJ023609 -8778 E0100; Adobe-Japan1; CID+6526 -8779 E0100; Hanyo-Denshi; IP8779 -8779 E0100; Moji_Joho; MJ023612 -8779 E0101; Hanyo-Denshi; KS379180 -8779 E0101; Moji_Joho; MJ023611 -877B E0100; Adobe-Japan1; CID+19761 -877C E0100; Adobe-Japan1; CID+18609 -877F E0100; Adobe-Japan1; CID+3358 -8782 E0100; Adobe-Japan1; CID+6540 -8782 E0101; Adobe-Japan1; CID+7862 -8782 E0102; Hanyo-Denshi; JA7407 -8782 E0102; Moji_Joho; MJ023618 -8782 E0103; Hanyo-Denshi; FT1986 -8782 E0103; Moji_Joho; MJ023621 -8782 E0104; Hanyo-Denshi; FT2521 -8782 E0104; Moji_Joho; MJ023620 -8782 E0105; Hanyo-Denshi; JTBADB -8782 E0105; Moji_Joho; MJ023619 -8783 E0100; Adobe-Japan1; CID+22436 -8784 E0100; Adobe-Japan1; CID+22437 -8785 E0100; Adobe-Japan1; CID+22438 -8786 E0100; Adobe-Japan1; CID+22439 -8787 E0100; Adobe-Japan1; CID+17112 -8788 E0100; Adobe-Japan1; CID+15098 -8789 E0100; Adobe-Japan1; CID+18613 -878B E0100; Adobe-Japan1; CID+18614 -878C E0100; Adobe-Japan1; CID+19762 -878D E0100; Adobe-Japan1; CID+3877 -878E E0100; Adobe-Japan1; CID+19763 -8790 E0100; Adobe-Japan1; CID+22440 -8793 E0100; Adobe-Japan1; CID+18615 -8795 E0100; Adobe-Japan1; CID+22441 -8797 E0100; Adobe-Japan1; CID+19764 -8798 E0100; Adobe-Japan1; CID+19765 -8799 E0100; Adobe-Japan1; CID+15099 -879B E0100; Hanyo-Denshi; IP879B -879B E0100; Moji_Joho; MJ023646 -879B E0101; Hanyo-Denshi; KS380770 -879B E0101; Moji_Joho; MJ023647 -879E E0100; Adobe-Japan1; CID+19766 -879F E0100; Adobe-Japan1; CID+6539 -87A0 E0100; Adobe-Japan1; CID+18616 -87A2 E0100; Adobe-Japan1; CID+6538 -87A3 E0100; Adobe-Japan1; CID+19767 -87A3 E0101; Adobe-Japan1; CID+22442 -87A3 E0102; Hanyo-Denshi; JB5941 -87A3 E0102; Moji_Joho; MJ023656 -87A3 E0103; Hanyo-Denshi; JTBAE0 -87A3 E0103; Moji_Joho; MJ023655 -87A7 E0100; Adobe-Japan1; CID+18612 -87AB E0100; Adobe-Japan1; CID+6547 -87AC E0100; Adobe-Japan1; CID+15100 -87AD E0100; Adobe-Japan1; CID+15101 -87AD E0101; Hanyo-Denshi; JB5944 -87AD E0101; Moji_Joho; MJ023664 -87AD E0102; Hanyo-Denshi; KS381930 -87AD E0102; Moji_Joho; MJ058654 -87AE E0100; Adobe-Japan1; CID+19768 -87AF E0100; Adobe-Japan1; CID+6541 -87B1 E0100; Adobe-Japan1; CID+22443 -87B3 E0100; Adobe-Japan1; CID+6549 -87B5 E0100; Adobe-Japan1; CID+15102 -87BA E0100; Adobe-Japan1; CID+3920 -87BB E0100; Adobe-Japan1; CID+6552 -87BD E0100; Adobe-Japan1; CID+6543 -87BD E0101; Adobe-Japan1; CID+14213 -87BD E0102; Hanyo-Denshi; JA7410 -87BD E0102; Moji_Joho; MJ023680 -87BD E0103; Hanyo-Denshi; JTBAE7 -87BD E0103; Moji_Joho; MJ023681 -87BE E0100; Adobe-Japan1; CID+18619 -87BF E0100; Adobe-Japan1; CID+19769 -87C0 E0100; Adobe-Japan1; CID+6544 -87C0 E0101; Hanyo-Denshi; JA7411 -87C0 E0101; Moji_Joho; MJ023684 -87C0 E0102; Hanyo-Denshi; FT2522 -87C0 E0102; Moji_Joho; MJ023685 -87C1 E0100; Adobe-Japan1; CID+18621 -87C4 E0100; Adobe-Japan1; CID+6548 -87C4 E0101; Moji_Joho; MJ023689 -87C4 E0102; Moji_Joho; MJ023690 -87C6 E0100; Adobe-Japan1; CID+6551 -87C6 E0101; Hanyo-Denshi; JA7418 -87C6 E0101; Moji_Joho; MJ023692 -87C6 E0102; Hanyo-Denshi; KS381510S -87C6 E0102; Moji_Joho; MJ023693 -87C7 E0100; Adobe-Japan1; CID+6550 -87C7 E0101; Hanyo-Denshi; JA7417 -87C7 E0101; Moji_Joho; MJ023694 -87C7 E0102; Hanyo-Denshi; KS381520S -87C7 E0102; Moji_Joho; MJ023695 -87C8 E0100; Adobe-Japan1; CID+22444 -87C9 E0100; Adobe-Japan1; CID+19770 -87CA E0100; Adobe-Japan1; CID+22445 -87CB E0100; Adobe-Japan1; CID+6542 -87CE E0100; Adobe-Japan1; CID+18622 -87D0 E0100; Adobe-Japan1; CID+6545 -87D2 E0100; Adobe-Japan1; CID+6562 -87D2 E0101; Adobe-Japan1; CID+7863 -87D2 E0102; Adobe-Japan1; CID+8002 -87D2 E0103; Hanyo-Denshi; JA7429 -87D2 E0103; Moji_Joho; MJ023704 -87D2 E0104; Hanyo-Denshi; KS382970S -87D2 E0104; Moji_Joho; MJ023707 -87D2 E0105; Hanyo-Denshi; FT1987 -87D2 E0105; Moji_Joho; MJ023705 -87D2 E0106; Hanyo-Denshi; JTBAE6 -87D2 E0106; Moji_Joho; MJ023706 -87D5 E0100; Adobe-Japan1; CID+22446 -87D6 E0100; Adobe-Japan1; CID+15103 -87D9 E0100; Adobe-Japan1; CID+22447 -87D9 E0101; Hanyo-Denshi; JB5957 -87D9 E0101; Moji_Joho; MJ023714 -87D9 E0102; Hanyo-Denshi; KS382950 -87D9 E0102; Moji_Joho; MJ023715 -87DA E0100; Adobe-Japan1; CID+19771 -87DC E0100; Adobe-Japan1; CID+22448 -87DF E0100; Adobe-Japan1; CID+18623 -87E0 E0100; Adobe-Japan1; CID+6555 -87E2 E0100; Adobe-Japan1; CID+22449 -87E3 E0100; Adobe-Japan1; CID+18625 -87E3 E0101; Hanyo-Denshi; JB5962 -87E3 E0101; Moji_Joho; MJ023725 -87E3 E0102; Hanyo-Denshi; KS382930 -87E3 E0102; Moji_Joho; MJ023726 -87E4 E0100; Adobe-Japan1; CID+22450 -87E5 E0100; Adobe-Japan1; CID+18626 -87E6 E0100; Adobe-Japan1; CID+18627 -87EA E0100; Adobe-Japan1; CID+18628 -87EB E0100; Adobe-Japan1; CID+15104 -87EB E0101; Hanyo-Denshi; JB5965 -87EB E0101; Moji_Joho; MJ023734 -87EB E0102; Hanyo-Denshi; KS382960 -87EB E0102; Moji_Joho; MJ023735 -87EC E0100; Adobe-Japan1; CID+7715 -87ED E0100; Adobe-Japan1; CID+15105 -87EF E0100; Adobe-Japan1; CID+6553 -87F1 E0100; Adobe-Japan1; CID+22451 -87F2 E0100; Adobe-Japan1; CID+6554 -87F3 E0100; Adobe-Japan1; CID+22452 -87F5 E0100; Adobe-Japan1; CID+15421 -87F6 E0100; Adobe-Japan1; CID+6559 -87F6 E0101; Hanyo-Denshi; JA7426 -87F6 E0101; Moji_Joho; MJ023746 -87F6 E0102; Hanyo-Denshi; JTBAEF -87F6 E0102; Moji_Joho; MJ023747 -87F7 E0100; Adobe-Japan1; CID+6560 -87F8 E0100; Adobe-Japan1; CID+22453 -87F9 E0100; Adobe-Japan1; CID+1416 -87FA E0100; Adobe-Japan1; CID+22454 -87FB E0100; Adobe-Japan1; CID+1628 -87FE E0100; Adobe-Japan1; CID+6558 -87FF E0100; Adobe-Japan1; CID+22455 -8801 E0100; Adobe-Japan1; CID+15106 -8801 E0101; Hanyo-Denshi; JB5972 -8801 E0101; Moji_Joho; MJ023758 -8801 E0102; Hanyo-Denshi; IB2890 -8801 E0102; Moji_Joho; MJ023759 -8802 E0100; Hanyo-Denshi; IP8802 -8802 E0100; Moji_Joho; MJ023760 -8802 E0101; Hanyo-Denshi; KS383170 -8802 E0101; Moji_Joho; MJ023761 -8803 E0100; Adobe-Japan1; CID+20312 -8803 E0101; Adobe-Japan1; CID+15107 -8803 E0102; Hanyo-Denshi; JB5973 -8803 E0102; Moji_Joho; MJ023762 -8803 E0103; Hanyo-Denshi; KS383660 -8803 E0103; Moji_Joho; MJ023763 -8803 E0104; Hanyo-Denshi; TK01083440 -8805 E0100; Adobe-Japan1; CID+6537 -8805 E0101; Adobe-Japan1; CID+14212 -8805 E0102; Adobe-Japan1; CID+20295 -8805 E0103; Hanyo-Denshi; JA7404 -8805 E0103; Moji_Joho; MJ023766 -8805 E0104; Hanyo-Denshi; HG1668 -8805 E0104; Moji_Joho; MJ023767 -8806 E0100; Adobe-Japan1; CID+15108 -8806 E0101; Hanyo-Denshi; JB5974 -8806 E0101; Moji_Joho; MJ023768 -8806 E0102; Hanyo-Denshi; JTBAED -8806 E0102; Moji_Joho; MJ023769 -8807 E0100; Adobe-Japan1; CID+8614 -8807 E0101; Hanyo-Denshi; IP8807 -8807 E0101; Moji_Joho; MJ023770 -8807 E0102; Hanyo-Denshi; KS383280 -8807 E0102; Moji_Joho; MJ023771 -8809 E0100; Adobe-Japan1; CID+22456 -880A E0100; Adobe-Japan1; CID+17114 -880B E0100; Adobe-Japan1; CID+15109 -880D E0100; Adobe-Japan1; CID+6557 -880D E0101; Hanyo-Denshi; JA7424 -880D E0101; Moji_Joho; MJ023777 -880D E0102; Hanyo-Denshi; JTBAF0 -880D E0102; Moji_Joho; MJ023779 -880D E0103; Hanyo-Denshi; FT2523 -880D E0103; Moji_Joho; MJ023778 -880E E0100; Adobe-Japan1; CID+6561 -880E E0101; Adobe-Japan1; CID+8001 -880E E0102; Hanyo-Denshi; JA7428 -880E E0102; Moji_Joho; MJ023780 -880E E0103; Hanyo-Denshi; KS383550S -880E E0103; Moji_Joho; MJ023781 -880E E0104; Hanyo-Denshi; JTBAE9 -880E E0104; Moji_Joho; MJ023782 -880E E0105; Hanyo-Denshi; JTC0D1 -880E E0105; Moji_Joho; MJ023783 -880F E0100; Adobe-Japan1; CID+6556 -8810 E0100; Adobe-Japan1; CID+17115 -8811 E0100; Adobe-Japan1; CID+6563 -8812 E0100; Adobe-Japan1; CID+22458 -8813 E0100; Adobe-Japan1; CID+18629 -8813 E0101; Hanyo-Denshi; JB5981 -8813 E0101; Moji_Joho; MJ023788 -8813 E0102; Hanyo-Denshi; KS383810 -8813 E0102; Moji_Joho; MJ023789 -8814 E0100; Adobe-Japan1; CID+15110 -8815 E0100; Adobe-Japan1; CID+6565 -8816 E0100; Adobe-Japan1; CID+6564 -8816 E0101; Hanyo-Denshi; JA7431 -8816 E0101; Moji_Joho; MJ023792 -8816 E0102; Hanyo-Denshi; KS383880 -8816 E0102; Moji_Joho; MJ023793 -8818 E0100; Adobe-Japan1; CID+19772 -8819 E0100; Adobe-Japan1; CID+22457 -881A E0100; Adobe-Japan1; CID+22459 -881A E0101; Hanyo-Denshi; JB5984 -881A E0101; Moji_Joho; MJ023797 -881A E0102; Hanyo-Denshi; KS384200 -881A E0102; Moji_Joho; MJ023798 -881B E0100; Adobe-Japan1; CID+19773 -881B E0101; Hanyo-Denshi; JB5985 -881B E0101; Moji_Joho; MJ023800 -881B E0102; Hanyo-Denshi; KS384120 -881B E0102; Moji_Joho; MJ023799 -881B E0103; Hanyo-Denshi; KS384260 -881B E0103; Moji_Joho; MJ023801 -881C E0100; Adobe-Japan1; CID+15111 -881E E0100; Adobe-Japan1; CID+22460 -881F E0100; Adobe-Japan1; CID+7813 -881F E0101; Hanyo-Denshi; JB5988 -881F E0101; Moji_Joho; MJ023805 -881F E0102; Hanyo-Denshi; KS384180 -881F E0102; Moji_Joho; MJ058666 -8821 E0100; Adobe-Japan1; CID+6567 -8821 E0101; Hanyo-Denshi; JA7434 -8821 E0101; Moji_Joho; MJ023807 -8821 E0102; Hanyo-Denshi; FT2524 -8821 E0102; Moji_Joho; MJ023808 -8821 E0103; Moji_Joho; MJ023809 -8822 E0100; Adobe-Japan1; CID+6566 -8823 E0100; Adobe-Japan1; CID+6497 -8823 E0101; Hanyo-Denshi; JA7358 -8823 E0101; Moji_Joho; MJ023811 -8823 E0102; Hanyo-Denshi; JTBAF2 -8823 E0102; Moji_Joho; MJ023812 -8827 E0100; Adobe-Japan1; CID+6571 -8828 E0100; Adobe-Japan1; CID+18630 -8828 E0101; Hanyo-Denshi; JB5989 -8828 E0101; Moji_Joho; MJ023816 -8828 E0102; Hanyo-Denshi; KS384800 -8828 E0102; Moji_Joho; MJ023817 -882A E0100; Hanyo-Denshi; IP882A -882A E0100; Moji_Joho; MJ023819 -882A E0101; Hanyo-Denshi; KS385080 -882A E0101; Moji_Joho; MJ023820 -882B E0100; Hanyo-Denshi; IP882B -882B E0100; Moji_Joho; MJ023821 -882B E0101; Hanyo-Denshi; KS385010 -882B E0101; Moji_Joho; MJ023822 -882D E0100; Adobe-Japan1; CID+19774 -882D E0101; Hanyo-Denshi; JB5990 -882D E0101; Moji_Joho; MJ023825 -882D E0102; Hanyo-Denshi; IB0882 -882D E0102; Moji_Joho; MJ023824 -882E E0100; Adobe-Japan1; CID+18631 -8830 E0100; Adobe-Japan1; CID+22461 -8831 E0100; Adobe-Japan1; CID+6568 -8832 E0100; Adobe-Japan1; CID+18632 -8835 E0100; Adobe-Japan1; CID+22462 -8836 E0100; Adobe-Japan1; CID+6569 -8836 E0101; Adobe-Japan1; CID+13593 -8836 E0102; Adobe-Japan1; CID+14215 -8836 E0103; Hanyo-Denshi; JA7436 -8836 E0103; Moji_Joho; MJ023834 -8836 E0104; Hanyo-Denshi; KS385410 -8836 E0104; Moji_Joho; MJ023833 -8836 E0105; Moji_Joho; MJ023835 -8839 E0100; Adobe-Japan1; CID+6570 -883A E0100; Adobe-Japan1; CID+19775 -883B E0100; Adobe-Japan1; CID+6572 -883C E0100; Adobe-Japan1; CID+18633 -8840 E0100; Adobe-Japan1; CID+1858 -8841 E0100; Adobe-Japan1; CID+22463 -8841 E0101; Hanyo-Denshi; JB6003 -8841 E0101; Moji_Joho; MJ023846 -8841 E0102; Hanyo-Denshi; KS386300 -8841 E0102; Moji_Joho; MJ023847 -8842 E0100; Adobe-Japan1; CID+6574 -8842 E0101; Adobe-Japan1; CID+20213 -8842 E0102; Hanyo-Denshi; JA7441 -8842 E0103; Hanyo-Denshi; KS386280 -8842 E0103; Moji_Joho; MJ023848 -8842 E0104; Moji_Joho; MJ023849 -8842 E0105; Moji_Joho; MJ023850 -8843 E0100; Adobe-Japan1; CID+22464 -8844 E0100; Adobe-Japan1; CID+6573 -8845 E0100; Adobe-Japan1; CID+19776 -8846 E0100; Adobe-Japan1; CID+2362 -8846 E0101; Adobe-Japan1; CID+13818 -8846 E0102; Hanyo-Denshi; JA2916 -8846 E0102; Moji_Joho; MJ023854 -8846 E0103; Hanyo-Denshi; KS386410 -8846 E0103; Moji_Joho; MJ058673 -8846 E0104; Hanyo-Denshi; KS386430 -8846 E0104; Moji_Joho; MJ058675 -8846 E0105; Hanyo-Denshi; KS386520 -8846 E0105; Moji_Joho; MJ058677 -8846 E0106; Hanyo-Denshi; TK01083450 -8848 E0100; Adobe-Japan1; CID+22465 -8849 E0100; Adobe-Japan1; CID+22466 -884A E0100; Adobe-Japan1; CID+18635 -884A E0101; Hanyo-Denshi; JB6008 -884A E0101; Moji_Joho; MJ023860 -884A E0102; Hanyo-Denshi; KS386960 -884A E0102; Moji_Joho; MJ023859 -884A E0103; Hanyo-Denshi; KS386930 -884A E0103; Moji_Joho; MJ023858 -884B E0100; Adobe-Japan1; CID+19777 -884B E0101; Adobe-Japan1; CID+22467 -884B E0102; Hanyo-Denshi; JB6009 -884B E0102; Moji_Joho; MJ023861 -884B E0103; Hanyo-Denshi; KS387030 -884B E0103; Moji_Joho; MJ023862 -884C E0100; Adobe-Japan1; CID+2022 -884D E0100; Adobe-Japan1; CID+5412 -884E E0100; Adobe-Japan1; CID+19778 -8851 E0100; Adobe-Japan1; CID+22468 -8851 E0101; Hanyo-Denshi; JB6011 -8851 E0102; Hanyo-Denshi; TK01083520 -8852 E0100; Adobe-Japan1; CID+6575 -8853 E0100; Adobe-Japan1; CID+2395 -8853 E0101; Adobe-Japan1; CID+13821 -8853 E0102; Hanyo-Denshi; JA2949 -8853 E0102; Moji_Joho; MJ023871 -8853 E0103; Hanyo-Denshi; JTBAFA -8853 E0103; Moji_Joho; MJ023870 -8853 E0104; Hanyo-Denshi; KS387180 -8853 E0104; Moji_Joho; MJ058680 -8855 E0100; Adobe-Japan1; CID+19779 -8856 E0100; Adobe-Japan1; CID+15112 -8857 E0100; Adobe-Japan1; CID+1431 -8858 E0100; Adobe-Japan1; CID+18636 -8859 E0100; Adobe-Japan1; CID+6576 -885A E0100; Adobe-Japan1; CID+19780 -885B E0100; Adobe-Japan1; CID+1268 -885B E0101; Adobe-Japan1; CID+13414 -885B E0102; Hanyo-Denshi; JA1750 -885B E0102; Moji_Joho; MJ023879 -885B E0103; Hanyo-Denshi; KS387490S -885B E0103; Moji_Joho; MJ023878 -885B E0104; Hanyo-Denshi; JTBAFF -885B E0104; Moji_Joho; MJ058685 -885B E0105; Moji_Joho; MJ023880 -885C E0100; Adobe-Japan1; CID+22469 -885D E0100; Adobe-Japan1; CID+2495 -885E E0100; Adobe-Japan1; CID+6577 -885E E0101; Adobe-Japan1; CID+13651 -885F E0100; Adobe-Japan1; CID+15113 -8860 E0100; Adobe-Japan1; CID+22470 -8861 E0100; Adobe-Japan1; CID+2023 -8862 E0100; Adobe-Japan1; CID+6578 -8863 E0100; Adobe-Japan1; CID+1189 -8863 E0101; Adobe-Japan1; CID+13640 -8863 E0102; Hanyo-Denshi; JA1665 -8863 E0102; Moji_Joho; MJ023889 -8863 E0103; Hanyo-Denshi; JTBB00 -8863 E0103; Moji_Joho; MJ060165 -8864 E0100; Adobe-Japan1; CID+15114 -8868 E0100; Adobe-Japan1; CID+3503 -8869 E0100; Adobe-Japan1; CID+18639 -886B E0100; Adobe-Japan1; CID+6579 -886E E0100; Adobe-Japan1; CID+19781 -886E E0101; Moji_Joho; MJ023898 -886E E0102; Moji_Joho; MJ023899 -886F E0100; Adobe-Japan1; CID+18641 -8870 E0100; Adobe-Japan1; CID+2608 -8870 E0101; Adobe-Japan1; CID+13863 -8870 E0102; Hanyo-Denshi; JA3174 -8870 E0102; Moji_Joho; MJ023901 -8870 E0103; Hanyo-Denshi; KS389040 -8870 E0104; Hanyo-Denshi; KS389650 -8870 E0104; Moji_Joho; MJ058692 -8871 E0100; Adobe-Japan1; CID+22471 -8871 E0101; Hanyo-Denshi; JB6021 -8871 E0101; Moji_Joho; MJ023903 -8871 E0102; Hanyo-Denshi; KS387980 -8871 E0102; Moji_Joho; MJ023902 -8872 E0100; Adobe-Japan1; CID+6586 -8872 E0101; Hanyo-Denshi; JA7453 -8872 E0101; Moji_Joho; MJ023904 -8872 E0102; Hanyo-Denshi; FT2526 -8872 E0102; Moji_Joho; MJ023905 -8875 E0100; Adobe-Japan1; CID+6583 -8877 E0100; Adobe-Japan1; CID+2989 -8877 E0101; Adobe-Japan1; CID+20214 -8879 E0100; Adobe-Japan1; CID+22472 -8879 E0101; Hanyo-Denshi; JB6022 -8879 E0102; Hanyo-Denshi; TK01083680 -887B E0100; Adobe-Japan1; CID+22473 -887D E0100; Adobe-Japan1; CID+6584 -887E E0100; Adobe-Japan1; CID+6581 -887F E0100; Adobe-Japan1; CID+1750 -8880 E0100; Adobe-Japan1; CID+22474 -8881 E0100; Adobe-Japan1; CID+6580 -8882 E0100; Adobe-Japan1; CID+6587 -8888 E0100; Adobe-Japan1; CID+1804 -888B E0100; Adobe-Japan1; CID+2878 -888D E0100; Adobe-Japan1; CID+6593 -888D E0101; Hanyo-Denshi; JA7460 -888D E0101; Moji_Joho; MJ023929 -888D E0102; Hanyo-Denshi; FT2528 -888D E0102; Moji_Joho; MJ023930 -8892 E0100; Adobe-Japan1; CID+6589 -8896 E0100; Adobe-Japan1; CID+2837 -8897 E0100; Adobe-Japan1; CID+6588 -8898 E0100; Adobe-Japan1; CID+15115 -8899 E0100; Adobe-Japan1; CID+6591 -889A E0100; Adobe-Japan1; CID+19782 -889A E0101; Hanyo-Denshi; JB6026 -889A E0101; Moji_Joho; MJ023943 -889A E0102; Hanyo-Denshi; JTBB0A -889A E0102; Moji_Joho; MJ023944 -889B E0100; Adobe-Japan1; CID+19783 -889C E0100; Adobe-Japan1; CID+19784 -889E E0100; Adobe-Japan1; CID+6582 -889E E0101; Adobe-Japan1; CID+13594 -889E E0102; Hanyo-Denshi; JA7449 -889E E0102; Moji_Joho; MJ023948 -889E E0103; Hanyo-Denshi; FT1728 -889E E0103; Moji_Joho; MJ023949 -889F E0100; Adobe-Japan1; CID+22475 -88A0 E0100; Adobe-Japan1; CID+18642 -88A2 E0100; Adobe-Japan1; CID+6592 -88A2 E0101; Hanyo-Denshi; JA7459 -88A2 E0101; Moji_Joho; MJ023953 -88A2 E0102; Hanyo-Denshi; FT2527 -88A2 E0102; Moji_Joho; MJ023954 -88A3 E0100; Moji_Joho; MJ023955 -88A3 E0101; Moji_Joho; MJ023956 -88A4 E0100; Adobe-Japan1; CID+6594 -88A8 E0100; Adobe-Japan1; CID+22476 -88AA E0100; Adobe-Japan1; CID+15116 -88AB E0100; Adobe-Japan1; CID+3459 -88AE E0100; Adobe-Japan1; CID+6590 -88B0 E0100; Adobe-Japan1; CID+6595 -88B1 E0100; Adobe-Japan1; CID+6597 -88B4 E0100; Adobe-Japan1; CID+1927 -88B4 E0101; Hanyo-Denshi; JA2451 -88B4 E0101; Moji_Joho; MJ023971 -88B4 E0102; Hanyo-Denshi; KS390170 -88B4 E0102; Moji_Joho; MJ058694 -88B5 E0100; Adobe-Japan1; CID+6585 -88B7 E0100; Adobe-Japan1; CID+1157 -88BA E0100; Adobe-Japan1; CID+22477 -88BC E0100; Adobe-Japan1; CID+18643 -88BD E0100; Adobe-Japan1; CID+15117 -88BE E0100; Adobe-Japan1; CID+15118 -88BF E0100; Adobe-Japan1; CID+6596 -88C0 E0100; Adobe-Japan1; CID+18644 -88C1 E0100; Adobe-Japan1; CID+2123 -88C2 E0100; Adobe-Japan1; CID+4030 -88C3 E0100; Adobe-Japan1; CID+6598 -88C4 E0100; Adobe-Japan1; CID+6599 -88C5 E0100; Adobe-Japan1; CID+2807 -88C6 E0100; Adobe-Japan1; CID+14217 -88CA E0100; Adobe-Japan1; CID+15119 -88CB E0100; Adobe-Japan1; CID+22478 -88CC E0100; Adobe-Japan1; CID+22479 -88CD E0100; Adobe-Japan1; CID+19785 -88CE E0100; Adobe-Japan1; CID+17116 -88CF E0100; Adobe-Japan1; CID+3946 -88D1 E0100; Adobe-Japan1; CID+18646 -88D2 E0100; Adobe-Japan1; CID+15120 -88D2 E0101; Hanyo-Denshi; JB6043 -88D2 E0101; Moji_Joho; MJ023997 -88D2 E0102; Hanyo-Denshi; JTBB0B -88D2 E0102; Moji_Joho; MJ023998 -88D3 E0100; Adobe-Japan1; CID+18647 -88D4 E0100; Adobe-Japan1; CID+6600 -88D5 E0100; Adobe-Japan1; CID+3871 -88D7 E0100; Hanyo-Denshi; IP88D7 -88D7 E0100; Moji_Joho; MJ024005 -88D7 E0101; Hanyo-Denshi; KS389530 -88D7 E0101; Moji_Joho; MJ024004 -88D8 E0100; Adobe-Japan1; CID+6601 -88D8 E0101; Adobe-Japan1; CID+13595 -88D9 E0100; Adobe-Japan1; CID+6602 -88DB E0100; Adobe-Japan1; CID+15121 -88DC E0100; Adobe-Japan1; CID+3636 -88DD E0100; Adobe-Japan1; CID+6603 -88DE E0100; Adobe-Japan1; CID+22480 -88DF E0100; Adobe-Japan1; CID+2096 -88E0 E0100; Adobe-Japan1; CID+19786 -88E1 E0100; Adobe-Japan1; CID+3947 -88E7 E0100; Adobe-Japan1; CID+22481 -88E8 E0100; Adobe-Japan1; CID+6608 -88EF E0100; Adobe-Japan1; CID+19787 -88F0 E0100; Adobe-Japan1; CID+15122 -88F1 E0100; Adobe-Japan1; CID+15123 -88F2 E0100; Adobe-Japan1; CID+6609 -88F3 E0100; Adobe-Japan1; CID+2496 -88F4 E0100; Adobe-Japan1; CID+6607 -88F4 E0101; Adobe-Japan1; CID+13596 -88F4 E0102; Moji_Joho; MJ024029 -88F4 E0103; Moji_Joho; MJ024030 -88F5 E0100; Adobe-Japan1; CID+8615 -88F7 E0100; Adobe-Japan1; CID+22482 -88F8 E0100; Adobe-Japan1; CID+3921 -88F9 E0100; Adobe-Japan1; CID+6604 -88FA E0100; Hanyo-Denshi; IP88FA -88FA E0100; Moji_Joho; MJ024037 -88FA E0101; Hanyo-Denshi; KS392810 -88FA E0101; Moji_Joho; MJ024038 -88FC E0100; Adobe-Japan1; CID+6606 -88FD E0100; Adobe-Japan1; CID+2657 -88FE E0100; Adobe-Japan1; CID+2628 -8901 E0100; Adobe-Japan1; CID+18649 -8902 E0100; Adobe-Japan1; CID+6605 -8904 E0100; Adobe-Japan1; CID+6610 -8906 E0100; Adobe-Japan1; CID+15124 -8907 E0100; Adobe-Japan1; CID+3571 -8907 E0101; Hanyo-Denshi; JA4203 -8907 E0101; Moji_Joho; MJ024052 -8907 E0102; Hanyo-Denshi; KS391180 -8907 E0102; Moji_Joho; MJ024051 -890A E0100; Adobe-Japan1; CID+6612 -890A E0101; Adobe-Japan1; CID+7864 -890A E0102; Hanyo-Denshi; JA7479 -890A E0102; Moji_Joho; MJ024056 -890A E0103; Hanyo-Denshi; FT1988 -890A E0103; Moji_Joho; MJ024055 -890C E0100; Adobe-Japan1; CID+6611 -890D E0100; Adobe-Japan1; CID+22483 -890E E0100; Adobe-Japan1; CID+19788 -890F E0100; Adobe-Japan1; CID+19789 -8910 E0100; Adobe-Japan1; CID+1482 -8910 E0101; Adobe-Japan1; CID+13331 -8910 E0102; Hanyo-Denshi; JA1976 -8910 E0103; Hanyo-Denshi; JC9179 -8912 E0100; Adobe-Japan1; CID+3673 -8912 E0101; Hanyo-Denshi; JA4311 -8912 E0101; Moji_Joho; MJ024064 -8912 E0102; Hanyo-Denshi; JTBB14 -8912 E0102; Moji_Joho; MJ024065 -8913 E0100; Adobe-Japan1; CID+6613 -8915 E0100; Adobe-Japan1; CID+22484 -8916 E0100; Adobe-Japan1; CID+22485 -8918 E0100; Adobe-Japan1; CID+15125 -8918 E0101; Hanyo-Denshi; JB6060 -8918 E0101; Moji_Joho; MJ024072 -8918 E0102; Hanyo-Denshi; KS391480 -8918 E0102; Moji_Joho; MJ024071 -8919 E0100; Adobe-Japan1; CID+15126 -891A E0100; Adobe-Japan1; CID+15127 -891C E0100; Adobe-Japan1; CID+8360 -891C E0101; Adobe-Japan1; CID+14283 -891C E0102; Hanyo-Denshi; JB6063 -891C E0102; Moji_Joho; MJ024076 -891C E0103; Hanyo-Denshi; JTBB11 -891C E0103; Moji_Joho; MJ024077 -891D E0100; Adobe-Japan1; CID+6625 -891E E0100; Adobe-Japan1; CID+6615 -891E E0101; Hanyo-Denshi; JA7482 -891E E0101; Moji_Joho; MJ024080 -891E E0102; Hanyo-Denshi; FT2529S -891E E0102; Moji_Joho; MJ024079 -8920 E0100; Adobe-Japan1; CID+22486 -8925 E0100; Adobe-Japan1; CID+6616 -8926 E0100; Adobe-Japan1; CID+19790 -8927 E0100; Adobe-Japan1; CID+15128 -8927 E0101; Moji_Joho; MJ024089 -8927 E0102; Moji_Joho; MJ024090 -8928 E0100; Adobe-Japan1; CID+22487 -892A E0100; Adobe-Japan1; CID+6617 -892A E0101; Hanyo-Denshi; JA7484 -892A E0101; Moji_Joho; MJ024094 -892A E0102; Hanyo-Denshi; FT2530 -892A E0102; Moji_Joho; MJ024093 -892B E0100; Adobe-Japan1; CID+6618 -892B E0101; Adobe-Japan1; CID+13597 -892B E0102; Hanyo-Denshi; JA7485 -892B E0102; Moji_Joho; MJ024095 -892B E0103; Hanyo-Denshi; FT1730 -892B E0103; Moji_Joho; MJ024096 -8930 E0100; Adobe-Japan1; CID+15129 -8931 E0100; Adobe-Japan1; CID+22488 -8932 E0100; Adobe-Japan1; CID+17118 -8933 E0100; Hanyo-Denshi; IB0886 -8933 E0100; Moji_Joho; MJ024104 -8933 E0101; Hanyo-Denshi; IP8933 -8933 E0101; Moji_Joho; MJ024105 -8935 E0100; Adobe-Japan1; CID+19791 -8935 E0101; Hanyo-Denshi; JB6071 -8935 E0101; Moji_Joho; MJ024108 -8935 E0102; Hanyo-Denshi; KS392230 -8935 E0102; Moji_Joho; MJ024106 -8935 E0103; Hanyo-Denshi; KS392820 -8935 E0103; Moji_Joho; MJ024107 -8936 E0100; Adobe-Japan1; CID+6622 -8936 E0101; Hanyo-Denshi; JA7489 -8936 E0101; Moji_Joho; MJ024109 -8936 E0102; Hanyo-Denshi; FT2532 -8936 E0102; Moji_Joho; MJ024110 -8937 E0100; Adobe-Japan1; CID+18651 -8938 E0100; Adobe-Japan1; CID+6623 -8939 E0100; Adobe-Japan1; CID+17119 -893A E0100; Adobe-Japan1; CID+22489 -893B E0100; Adobe-Japan1; CID+6621 -893B E0101; Adobe-Japan1; CID+13598 -893B E0102; Hanyo-Denshi; JA7488 -893B E0102; Moji_Joho; MJ024115 -893B E0103; Hanyo-Denshi; FT1731 -893B E0103; Moji_Joho; MJ024116 -893C E0100; Hanyo-Denshi; IP893C -893C E0100; Moji_Joho; MJ024117 -893C E0101; Hanyo-Denshi; KS392850 -893C E0101; Moji_Joho; MJ024118 -893E E0100; Adobe-Japan1; CID+15130 -8940 E0100; Adobe-Japan1; CID+17120 -8941 E0100; Adobe-Japan1; CID+6619 -8941 E0101; Adobe-Japan1; CID+20215 -8941 E0102; Hanyo-Denshi; JA7486 -8941 E0102; Moji_Joho; MJ024123 -8941 E0103; Hanyo-Denshi; JTBB24 -8941 E0103; Moji_Joho; MJ024124 -8942 E0100; Adobe-Japan1; CID+18653 -8943 E0100; Adobe-Japan1; CID+6614 -8943 E0101; Hanyo-Denshi; JA7481 -8943 E0101; Moji_Joho; MJ024126 -8943 E0102; Hanyo-Denshi; JTBB20 -8943 E0102; Moji_Joho; MJ024127 -8944 E0100; Adobe-Japan1; CID+6620 -8944 E0101; Hanyo-Denshi; JA7487 -8944 E0101; Moji_Joho; MJ024128 -8944 E0102; Hanyo-Denshi; JTAD33 -8944 E0102; Moji_Joho; MJ059302 -8944 E0103; Hanyo-Denshi; KS392260 -8944 E0104; Hanyo-Denshi; TK01001970 -8945 E0100; Adobe-Japan1; CID+18654 -8946 E0100; Adobe-Japan1; CID+22490 -8949 E0100; Adobe-Japan1; CID+18655 -894A E0100; Hanyo-Denshi; IP894A -894A E0100; Moji_Joho; MJ024134 -894A E0101; Hanyo-Denshi; KS393440 -894A E0101; Moji_Joho; MJ024135 -894C E0100; Adobe-Japan1; CID+6624 -894C E0101; Hanyo-Denshi; JA7491 -894C E0102; Hanyo-Denshi; TK01084110 -894D E0100; Adobe-Japan1; CID+7120 -894F E0100; Adobe-Japan1; CID+22491 -8952 E0100; Adobe-Japan1; CID+22492 -8956 E0100; Adobe-Japan1; CID+1320 -8956 E0101; Adobe-Japan1; CID+7645 -8956 E0102; Hanyo-Denshi; JA1808 -8956 E0102; Moji_Joho; MJ024145 -8956 E0103; Hanyo-Denshi; FT1762 -8956 E0103; Moji_Joho; MJ024146 -8957 E0100; Adobe-Japan1; CID+22493 -895A E0100; Adobe-Japan1; CID+19792 -895A E0101; Hanyo-Denshi; JB6083 -895A E0101; Moji_Joho; MJ024151 -895A E0102; Hanyo-Denshi; IB0887 -895A E0102; Moji_Joho; MJ024150 -895B E0100; Adobe-Japan1; CID+22494 -895C E0100; Adobe-Japan1; CID+19793 -895E E0100; Adobe-Japan1; CID+6627 -895F E0100; Adobe-Japan1; CID+1751 -8960 E0100; Adobe-Japan1; CID+6626 -8961 E0100; Adobe-Japan1; CID+22495 -8962 E0100; Adobe-Japan1; CID+18657 -8963 E0100; Adobe-Japan1; CID+22496 -8964 E0100; Adobe-Japan1; CID+6629 -8966 E0100; Adobe-Japan1; CID+6628 -896A E0100; Adobe-Japan1; CID+6631 -896A E0101; Adobe-Japan1; CID+13599 -896A E0102; Hanyo-Denshi; JA7504 -896A E0102; Moji_Joho; MJ024165 -896A E0103; Hanyo-Denshi; KS394380 -896A E0103; Moji_Joho; MJ024167 -896A E0104; Hanyo-Denshi; KS394240 -896A E0104; Moji_Joho; MJ024166 -896A E0105; Hanyo-Denshi; FT1732 -896A E0105; Moji_Joho; MJ024168 -896B E0100; Adobe-Japan1; CID+19794 -896D E0100; Adobe-Japan1; CID+6630 -896E E0100; Adobe-Japan1; CID+22497 -896F E0100; Adobe-Japan1; CID+6632 -896F E0101; Adobe-Japan1; CID+13600 -896F E0102; Hanyo-Denshi; JA7505 -896F E0102; Moji_Joho; MJ024173 -896F E0103; Hanyo-Denshi; FT1733 -896F E0103; Moji_Joho; MJ024174 -8970 E0100; Adobe-Japan1; CID+19795 -8971 E0100; Hanyo-Denshi; IP8971 -8971 E0100; Moji_Joho; MJ024176 -8971 E0101; Hanyo-Denshi; KS394520 -8971 E0101; Moji_Joho; MJ024177 -8972 E0100; Adobe-Japan1; CID+2363 -8972 E0101; Hanyo-Denshi; JA2917 -8972 E0101; Moji_Joho; MJ024178 -8972 E0102; Hanyo-Denshi; JTBB2C -8972 E0102; Moji_Joho; MJ024179 -8973 E0100; Adobe-Japan1; CID+22498 -8974 E0100; Adobe-Japan1; CID+6633 -8974 E0101; Hanyo-Denshi; JA7506 -8974 E0101; Moji_Joho; MJ024181 -8974 E0102; Hanyo-Denshi; FT2533 -8974 E0102; Moji_Joho; MJ024182 -8975 E0100; Adobe-Japan1; CID+22499 -8977 E0100; Adobe-Japan1; CID+6634 -897A E0100; Adobe-Japan1; CID+22500 -897A E0101; Hanyo-Denshi; JB6094 -897A E0101; Moji_Joho; MJ024188 -897A E0102; Hanyo-Denshi; KS394760 -897A E0102; Moji_Joho; MJ024189 -897B E0100; Adobe-Japan1; CID+15131 -897C E0100; Adobe-Japan1; CID+19796 -897C E0101; Hanyo-Denshi; JB6102 -897C E0101; Moji_Joho; MJ024191 -897C E0102; Hanyo-Denshi; KS394800 -897C E0102; Moji_Joho; MJ024192 -897D E0100; Adobe-Japan1; CID+22501 -897D E0101; Hanyo-Denshi; JB6103 -897D E0101; Moji_Joho; MJ024193 -897D E0102; Hanyo-Denshi; KS394930 -897D E0102; Moji_Joho; MJ024194 -897E E0100; Adobe-Japan1; CID+6635 -897F E0100; Adobe-Japan1; CID+2658 -897F E0101; Hanyo-Denshi; JA3230 -897F E0101; Moji_Joho; MJ024196 -897F E0102; Hanyo-Denshi; IB0889 -897F E0102; Moji_Joho; MJ024197 -897F E0103; Hanyo-Denshi; TK01084270 -8980 E0100; Adobe-Japan1; CID+13870 -8981 E0100; Adobe-Japan1; CID+3905 -8981 E0101; Adobe-Japan1; CID+14079 -8981 E0102; Hanyo-Denshi; JA4555 -8981 E0102; Moji_Joho; MJ024201 -8981 E0103; Hanyo-Denshi; JTBB30 -8981 E0103; Moji_Joho; MJ024200 -8983 E0100; Adobe-Japan1; CID+6636 -8983 E0101; Hanyo-Denshi; JA7509 -8983 E0101; Moji_Joho; MJ024203 -8983 E0102; Hanyo-Denshi; FT2535 -8983 E0102; Moji_Joho; MJ024204 -8983 E0103; Hanyo-Denshi; KS395300 -8983 E0103; Moji_Joho; MJ058715 -8986 E0100; Adobe-Japan1; CID+3572 -8986 E0101; Adobe-Japan1; CID+14008 -8986 E0102; Hanyo-Denshi; JA4204 -8986 E0102; Moji_Joho; MJ024207 -8986 E0103; Hanyo-Denshi; KS395460 -8986 E0103; Moji_Joho; MJ024206 -8986 E0104; Hanyo-Denshi; JTBB32S -8986 E0104; Moji_Joho; MJ024208 -8987 E0100; Adobe-Japan1; CID+3324 -8987 E0101; Adobe-Japan1; CID+13973 -8987 E0102; Hanyo-Denshi; JA3938 -8987 E0102; Moji_Joho; MJ024210 -8987 E0103; Hanyo-Denshi; IB0273 -8987 E0103; Moji_Joho; MJ024209 -8988 E0100; Adobe-Japan1; CID+6637 -8988 E0101; Hanyo-Denshi; JA7510 -8988 E0101; Moji_Joho; MJ024211 -8988 E0102; Hanyo-Denshi; FT2536S -8988 E0102; Moji_Joho; MJ024212 -8989 E0100; Adobe-Japan1; CID+18658 -8989 E0101; Hanyo-Denshi; JB6104 -8989 E0101; Moji_Joho; MJ024213 -8989 E0102; Hanyo-Denshi; JTBB36 -8989 E0102; Moji_Joho; MJ024214 -898A E0100; Adobe-Japan1; CID+6638 -898A E0101; Hanyo-Denshi; JA7511 -898A E0101; Moji_Joho; MJ024215 -898A E0102; Hanyo-Denshi; FT2537 -898A E0102; Moji_Joho; MJ024216 -898B E0100; Adobe-Japan1; CID+1887 -898D E0100; Adobe-Japan1; CID+22502 -898F E0100; Adobe-Japan1; CID+1606 -8990 E0100; Adobe-Japan1; CID+18659 -8990 E0101; Moji_Joho; MJ024223 -8990 E0102; Moji_Joho; MJ024224 -8993 E0100; Adobe-Japan1; CID+6639 -8994 E0100; Adobe-Japan1; CID+17121 -8995 E0100; Adobe-Japan1; CID+22503 -8996 E0100; Adobe-Japan1; CID+2233 -8996 E0101; Adobe-Japan1; CID+13346 -8996 E0102; Hanyo-Denshi; JA2775 -8996 E0103; Hanyo-Denshi; JC9189 -8997 E0100; Adobe-Japan1; CID+3319 -8998 E0100; Adobe-Japan1; CID+6640 -899A E0100; Adobe-Japan1; CID+1454 -899B E0100; Adobe-Japan1; CID+22504 -899C E0100; Adobe-Japan1; CID+22505 -899F E0100; Adobe-Japan1; CID+18660 -89A0 E0100; Adobe-Japan1; CID+22506 -89A1 E0100; Adobe-Japan1; CID+6641 -89A5 E0100; Adobe-Japan1; CID+19797 -89A6 E0100; Adobe-Japan1; CID+6643 -89A6 E0101; Hanyo-Denshi; JA7516 -89A6 E0101; Moji_Joho; MJ024246 -89A6 E0102; Hanyo-Denshi; FT2539 -89A6 E0102; Moji_Joho; MJ024247 -89A7 E0100; Adobe-Japan1; CID+3937 -89A7 E0101; Hanyo-Denshi; JA4587 -89A7 E0102; Hanyo-Denshi; TK01084610 -89A9 E0100; Adobe-Japan1; CID+6642 -89A9 E0101; Hanyo-Denshi; JA7515 -89A9 E0101; Moji_Joho; MJ024250 -89A9 E0102; Hanyo-Denshi; FT2538 -89A9 E0102; Moji_Joho; MJ024251 -89AA E0100; Adobe-Japan1; CID+2572 -89AA E0101; Adobe-Japan1; CID+13467 -89AC E0100; Adobe-Japan1; CID+6644 -89AF E0100; Adobe-Japan1; CID+6645 -89AF E0101; Adobe-Japan1; CID+7865 -89AF E0102; Hanyo-Denshi; JA7518 -89AF E0102; Moji_Joho; MJ024258 -89AF E0103; Hanyo-Denshi; FT1989 -89AF E0103; Moji_Joho; MJ024257 -89B0 E0100; Adobe-Japan1; CID+18661 -89B2 E0100; Adobe-Japan1; CID+6646 -89B2 E0101; Hanyo-Denshi; JA7519 -89B2 E0101; Moji_Joho; MJ024261 -89B2 E0102; Hanyo-Denshi; FT2540 -89B2 E0102; Moji_Joho; MJ024262 -89B3 E0100; Adobe-Japan1; CID+1549 -89B4 E0100; Adobe-Japan1; CID+22507 -89B5 E0100; Adobe-Japan1; CID+19798 -89B6 E0100; Adobe-Japan1; CID+22508 -89B6 E0101; Hanyo-Denshi; JB6117 -89B6 E0101; Moji_Joho; MJ024266 -89B6 E0102; Hanyo-Denshi; KS397340 -89B6 E0102; Moji_Joho; MJ024267 -89B6 E0103; Hanyo-Denshi; TK01084740 -89B7 E0100; Adobe-Japan1; CID+18662 -89BA E0100; Adobe-Japan1; CID+6647 -89BC E0100; Adobe-Japan1; CID+19799 -89BD E0100; Adobe-Japan1; CID+6648 -89BD E0101; Adobe-Japan1; CID+14218 -89BD E0102; Hanyo-Denshi; JA7521 -89BD E0102; Moji_Joho; MJ024275 -89BD E0103; Hanyo-Denshi; JTBB41 -89BD E0103; Moji_Joho; MJ060178 -89BD E0104; Hanyo-Denshi; TK01084820 -89BF E0100; Adobe-Japan1; CID+6649 -89C0 E0100; Adobe-Japan1; CID+6650 -89C0 E0101; Hanyo-Denshi; JA7523 -89C0 E0101; Moji_Joho; MJ024278 -89C0 E0102; Hanyo-Denshi; KS397640 -89C0 E0102; Moji_Joho; MJ024279 -89C0 E0103; Hanyo-Denshi; JTBB43 -89C0 E0103; Moji_Joho; MJ024280 -89D2 E0100; Adobe-Japan1; CID+13682 -89D2 E0101; Adobe-Japan1; CID+1455 -89D2 E0102; Hanyo-Denshi; JA1949 -89D2 E0102; Moji_Joho; MJ024281 -89D2 E0103; Hanyo-Denshi; JTBB45 -89D2 E0103; Moji_Joho; MJ024283 -89D2 E0104; Hanyo-Denshi; IB0890 -89D2 E0104; Moji_Joho; MJ024282 -89D3 E0100; Moji_Joho; MJ024284 -89D3 E0101; Moji_Joho; MJ024285 -89D4 E0100; Adobe-Japan1; CID+15132 -89D5 E0100; Adobe-Japan1; CID+19800 -89D6 E0100; Adobe-Japan1; CID+15133 -89D7 E0100; Adobe-Japan1; CID+22509 -89D8 E0100; Adobe-Japan1; CID+18663 -89DA E0100; Adobe-Japan1; CID+6651 -89DA E0101; Hanyo-Denshi; JA7524 -89DA E0101; Moji_Joho; MJ024293 -89DA E0102; Hanyo-Denshi; JTBB46 -89DA E0102; Moji_Joho; MJ024292 -89DC E0100; Adobe-Japan1; CID+6652 -89DD E0100; Adobe-Japan1; CID+6653 -89E2 E0100; Hanyo-Denshi; IP89E2 -89E2 E0101; Hanyo-Denshi; TK01084890 -89E3 E0100; Adobe-Japan1; CID+1394 -89E3 E0101; Hanyo-Denshi; JA1882 -89E3 E0102; Hanyo-Denshi; TK01084900 -89E5 E0100; Adobe-Japan1; CID+15134 -89E6 E0100; Adobe-Japan1; CID+2542 -89E7 E0100; Adobe-Japan1; CID+6654 -89E7 E0101; Hanyo-Denshi; JA7527 -89E7 E0101; Moji_Joho; MJ024307 -89E7 E0102; Hanyo-Denshi; KS398530 -89E7 E0102; Moji_Joho; MJ058736 -89E9 E0100; Adobe-Japan1; CID+22510 -89EB E0100; Adobe-Japan1; CID+18664 -89ED E0100; Adobe-Japan1; CID+22511 -89F1 E0100; Adobe-Japan1; CID+15135 -89F3 E0100; Adobe-Japan1; CID+18666 -89F4 E0100; Adobe-Japan1; CID+6655 -89F4 E0101; Hanyo-Denshi; JA7528 -89F4 E0101; Moji_Joho; MJ024319 -89F4 E0102; Hanyo-Denshi; JTBB4C -89F4 E0102; Moji_Joho; MJ024320 -89F6 E0100; Adobe-Japan1; CID+17122 -89F8 E0100; Adobe-Japan1; CID+6656 -89F9 E0100; Adobe-Japan1; CID+22512 -89FD E0100; Adobe-Japan1; CID+18667 -89FF E0100; Adobe-Japan1; CID+18668 -8A00 E0100; Adobe-Japan1; CID+1908 -8A01 E0100; Adobe-Japan1; CID+13756 -8A02 E0100; Adobe-Japan1; CID+3095 -8A03 E0100; Adobe-Japan1; CID+6657 -8A04 E0100; Adobe-Japan1; CID+22513 -8A05 E0100; Adobe-Japan1; CID+22514 -8A07 E0100; Adobe-Japan1; CID+15136 -8A08 E0100; Adobe-Japan1; CID+1837 -8A0A E0100; Adobe-Japan1; CID+2588 -8A0A E0101; Adobe-Japan1; CID+13860 -8A0A E0102; Adobe-Japan1; CID+13861 -8A0A E0103; Hanyo-Denshi; JA3154 -8A0A E0103; Moji_Joho; MJ024340 -8A0A E0104; Hanyo-Denshi; HG1632 -8A0A E0104; Moji_Joho; MJ024341 -8A0C E0100; Adobe-Japan1; CID+6660 -8A0E E0100; Adobe-Japan1; CID+3196 -8A0F E0100; Adobe-Japan1; CID+15137 -8A10 E0100; Adobe-Japan1; CID+6659 -8A11 E0100; Adobe-Japan1; CID+18670 -8A12 E0100; Adobe-Japan1; CID+8616 -8A12 E0101; Adobe-Japan1; CID+14295 -8A12 E0102; Hanyo-Denshi; JB6140 -8A12 E0102; Moji_Joho; MJ024349 -8A12 E0103; Hanyo-Denshi; JTBB4F -8A12 E0103; Moji_Joho; MJ024350 -8A12 E0104; Hanyo-Denshi; TK01084960 -8A13 E0100; Adobe-Japan1; CID+1799 -8A14 E0100; Adobe-Japan1; CID+18671 -8A15 E0100; Adobe-Japan1; CID+15138 -8A16 E0100; Adobe-Japan1; CID+6658 -8A17 E0100; Adobe-Japan1; CID+2903 -8A18 E0100; Adobe-Japan1; CID+1607 -8A18 E0101; Hanyo-Denshi; JA2113 -8A18 E0101; Moji_Joho; MJ024357 -8A18 E0102; Hanyo-Denshi; JTBB4D -8A18 E0102; Moji_Joho; MJ024358 -8A1B E0100; Adobe-Japan1; CID+6661 -8A1B E0101; Moji_Joho; MJ024360 -8A1B E0102; Moji_Joho; MJ024361 -8A1D E0100; Adobe-Japan1; CID+6662 -8A1D E0101; Adobe-Japan1; CID+13601 -8A1D E0102; Adobe-Japan1; CID+20268 -8A1D E0103; Hanyo-Denshi; JA7535 -8A1D E0103; Moji_Joho; MJ024364 -8A1D E0104; Hanyo-Denshi; HG1607 -8A1D E0104; Moji_Joho; MJ024363 -8A1D E0105; Moji_Joho; MJ024365 -8A1D E0106; Moji_Joho; MJ024366 -8A1E E0100; Adobe-Japan1; CID+22515 -8A1F E0100; Adobe-Japan1; CID+2497 -8A1F E0101; Adobe-Japan1; CID+13462 -8A1F E0102; Hanyo-Denshi; JA3057 -8A1F E0102; Moji_Joho; MJ024368 -8A1F E0103; Hanyo-Denshi; FT1639 -8A1F E0103; Moji_Joho; MJ024369 -8A20 E0100; Adobe-Japan1; CID+22516 -8A21 E0100; Adobe-Japan1; CID+18673 -8A22 E0100; Adobe-Japan1; CID+15139 -8A23 E0100; Adobe-Japan1; CID+1859 -8A24 E0100; Adobe-Japan1; CID+22517 -8A25 E0100; Adobe-Japan1; CID+6663 -8A25 E0101; Hanyo-Denshi; JA7536 -8A25 E0101; Moji_Joho; MJ024375 -8A25 E0102; Hanyo-Denshi; FT2542 -8A25 E0102; Moji_Joho; MJ024376 -8A26 E0100; Adobe-Japan1; CID+22518 -8A2A E0100; Adobe-Japan1; CID+3674 -8A2B E0100; Adobe-Japan1; CID+22519 -8A2C E0100; Adobe-Japan1; CID+22520 -8A2D E0100; Adobe-Japan1; CID+2691 -8A2F E0100; Adobe-Japan1; CID+22521 -8A30 E0100; Hanyo-Denshi; IP8A30 -8A30 E0101; Hanyo-Denshi; TK01084970 -8A31 E0100; Adobe-Japan1; CID+1680 -8A33 E0100; Adobe-Japan1; CID+3841 -8A34 E0100; Adobe-Japan1; CID+2764 -8A35 E0100; Adobe-Japan1; CID+18674 -8A36 E0100; Adobe-Japan1; CID+6664 -8A37 E0100; Adobe-Japan1; CID+8617 -8A3A E0100; Adobe-Japan1; CID+2573 -8A3B E0100; Adobe-Japan1; CID+2990 -8A3B E0101; Adobe-Japan1; CID+7740 -8A3B E0102; Hanyo-Denshi; JA3580 -8A3B E0102; Moji_Joho; MJ024399 -8A3B E0103; Hanyo-Denshi; FT2927 -8A3B E0104; Hanyo-Denshi; JTBB57 -8A3B E0104; Moji_Joho; MJ024401 -8A3C E0100; Adobe-Japan1; CID+2498 -8A3D E0100; Adobe-Japan1; CID+22522 -8A3E E0100; Adobe-Japan1; CID+18675 -8A40 E0100; Adobe-Japan1; CID+22523 -8A41 E0100; Adobe-Japan1; CID+6665 -8A43 E0100; Adobe-Japan1; CID+22524 -8A45 E0100; Adobe-Japan1; CID+18676 -8A46 E0100; Adobe-Japan1; CID+6668 -8A47 E0100; Adobe-Japan1; CID+17123 -8A48 E0100; Adobe-Japan1; CID+6669 -8A49 E0100; Adobe-Japan1; CID+19801 -8A4A E0100; Hanyo-Denshi; IP8A4A -8A4A E0101; Hanyo-Denshi; TK01085060 -8A4D E0100; Adobe-Japan1; CID+18677 -8A4E E0100; Adobe-Japan1; CID+15140 -8A4E E0101; Hanyo-Denshi; JB6161 -8A4E E0101; Moji_Joho; MJ024421 -8A4E E0102; Hanyo-Denshi; IB2927 -8A4E E0102; Moji_Joho; MJ024422 -8A50 E0100; Adobe-Japan1; CID+2094 -8A51 E0100; Adobe-Japan1; CID+2850 -8A52 E0100; Adobe-Japan1; CID+6667 -8A53 E0100; Adobe-Japan1; CID+22525 -8A54 E0100; Adobe-Japan1; CID+2499 -8A55 E0100; Adobe-Japan1; CID+3504 -8A55 E0101; Adobe-Japan1; CID+13999 -8A55 E0102; Hanyo-Denshi; JA4130 -8A55 E0102; Moji_Joho; MJ024430 -8A55 E0103; Hanyo-Denshi; JTBB58 -8A55 E0103; Moji_Joho; MJ024429 -8A56 E0100; Adobe-Japan1; CID+22526 -8A57 E0100; Adobe-Japan1; CID+19802 -8A58 E0100; Adobe-Japan1; CID+18678 -8A5B E0100; Adobe-Japan1; CID+6666 -8A5C E0100; Adobe-Japan1; CID+22527 -8A5D E0100; Adobe-Japan1; CID+17124 -8A5E E0100; Adobe-Japan1; CID+2234 -8A60 E0100; Adobe-Japan1; CID+1269 -8A60 E0101; Hanyo-Denshi; JA1751 -8A60 E0101; Moji_Joho; MJ024440 -8A60 E0102; Hanyo-Denshi; KS402940 -8A60 E0102; Moji_Joho; MJ024441 -8A61 E0100; Adobe-Japan1; CID+17125 -8A62 E0100; Adobe-Japan1; CID+6673 -8A63 E0100; Adobe-Japan1; CID+1838 -8A64 E0100; Hanyo-Denshi; IP8A64 -8A64 E0100; Moji_Joho; MJ024445 -8A64 E0101; Hanyo-Denshi; KS402980 -8A64 E0101; Moji_Joho; MJ024446 -8A64 E0102; Moji_Joho; MJ024447 -8A65 E0100; Adobe-Japan1; CID+22528 -8A66 E0100; Adobe-Japan1; CID+2236 -8A67 E0100; Adobe-Japan1; CID+19803 -8A69 E0100; Adobe-Japan1; CID+2235 -8A6B E0100; Adobe-Japan1; CID+4083 -8A6C E0100; Adobe-Japan1; CID+6672 -8A6D E0100; Adobe-Japan1; CID+6671 -8A6D E0101; Hanyo-Denshi; JA7544 -8A6D E0101; Moji_Joho; MJ024456 -8A6D E0102; Hanyo-Denshi; JTBB5E -8A6D E0102; Moji_Joho; MJ024457 -8A6E E0100; Adobe-Japan1; CID+2729 -8A6E E0101; Adobe-Japan1; CID+7720 -8A6E E0102; Hanyo-Denshi; JA3307 -8A6E E0102; Moji_Joho; MJ024458 -8A6E E0103; Hanyo-Denshi; FT1841 -8A6E E0103; Moji_Joho; MJ024459 -8A70 E0100; Adobe-Japan1; CID+1639 -8A71 E0100; Adobe-Japan1; CID+4073 -8A72 E0100; Adobe-Japan1; CID+1432 -8A72 E0101; Hanyo-Denshi; JA1926 -8A72 E0101; Moji_Joho; MJ024463 -8A72 E0102; Hanyo-Denshi; JTBB5D -8A72 E0102; Moji_Joho; MJ024464 -8A73 E0100; Adobe-Japan1; CID+2500 -8A75 E0100; Adobe-Japan1; CID+17126 -8A76 E0100; Adobe-Japan1; CID+22529 -8A77 E0100; Adobe-Japan1; CID+22530 -8A79 E0100; Adobe-Japan1; CID+8618 -8A7A E0100; Adobe-Japan1; CID+22531 -8A7B E0100; Adobe-Japan1; CID+22532 -8A7C E0100; Adobe-Japan1; CID+6670 -8A7C E0101; Hanyo-Denshi; JA7543 -8A7C E0101; Moji_Joho; MJ024474 -8A7C E0102; Hanyo-Denshi; FT2543 -8A7C E0102; Moji_Joho; MJ024475 -8A7E E0100; Adobe-Japan1; CID+19804 -8A7F E0100; Adobe-Japan1; CID+15141 -8A80 E0100; Adobe-Japan1; CID+22533 -8A82 E0100; Adobe-Japan1; CID+6675 -8A83 E0100; Adobe-Japan1; CID+22534 -8A84 E0100; Adobe-Japan1; CID+6676 -8A84 E0101; Hanyo-Denshi; JA7549 -8A84 E0101; Moji_Joho; MJ024483 -8A84 E0102; Hanyo-Denshi; FT2544 -8A84 E0102; Moji_Joho; MJ024484 -8A85 E0100; Adobe-Japan1; CID+6674 -8A86 E0100; Adobe-Japan1; CID+19805 -8A86 E0101; Moji_Joho; MJ024486 -8A86 E0102; Moji_Joho; MJ024487 -8A87 E0100; Adobe-Japan1; CID+1932 -8A89 E0100; Adobe-Japan1; CID+3882 -8A8B E0100; Adobe-Japan1; CID+22535 -8A8C E0100; Adobe-Japan1; CID+2237 -8A8D E0100; Adobe-Japan1; CID+3293 -8A8D E0101; Adobe-Japan1; CID+13970 -8A8D E0102; Hanyo-Denshi; JA3907 -8A8D E0102; Moji_Joho; MJ024494 -8A8D E0103; Hanyo-Denshi; KS403040 -8A8D E0103; Moji_Joho; MJ024493 -8A8F E0100; Adobe-Japan1; CID+22536 -8A90 E0100; Adobe-Japan1; CID+18680 -8A91 E0100; Adobe-Japan1; CID+6679 -8A92 E0100; Adobe-Japan1; CID+22537 -8A93 E0100; Adobe-Japan1; CID+2660 -8A95 E0100; Adobe-Japan1; CID+2944 -8A95 E0101; Adobe-Japan1; CID+13475 -8A95 E0102; Adobe-Japan1; CID+13917 -8A95 E0103; Hanyo-Denshi; JA3534 -8A95 E0103; Moji_Joho; MJ024503 -8A95 E0104; Hanyo-Denshi; JTBB67S -8A95 E0104; Moji_Joho; MJ024502 -8A95 E0105; Moji_Joho; MJ024504 -8A96 E0100; Adobe-Japan1; CID+19806 -8A97 E0100; Adobe-Japan1; CID+22538 -8A98 E0100; Adobe-Japan1; CID+3872 -8A99 E0100; Adobe-Japan1; CID+22539 -8A99 E0101; Hanyo-Denshi; JB6188 -8A99 E0102; Hanyo-Denshi; TK01085240 -8A9A E0100; Adobe-Japan1; CID+6682 -8A9A E0101; Hanyo-Denshi; JA7555 -8A9A E0101; Moji_Joho; MJ024510 -8A9A E0102; Hanyo-Denshi; FT2547 -8A9A E0102; Moji_Joho; MJ024511 -8A9E E0100; Adobe-Japan1; CID+1952 -8A9F E0100; Adobe-Japan1; CID+22540 -8AA0 E0100; Adobe-Japan1; CID+2659 -8AA0 E0101; Adobe-Japan1; CID+13871 -8AA0 E0102; Hanyo-Denshi; JA3231 -8AA0 E0102; Moji_Joho; MJ024517 -8AA0 E0103; Hanyo-Denshi; JTBB64 -8AA0 E0103; Moji_Joho; MJ024518 -8AA1 E0100; Adobe-Japan1; CID+6678 -8AA3 E0100; Adobe-Japan1; CID+6683 -8AA4 E0100; Adobe-Japan1; CID+1953 -8AA4 E0101; Adobe-Japan1; CID+13762 -8AA4 E0102; Hanyo-Denshi; JA2477 -8AA4 E0102; Moji_Joho; MJ024523 -8AA4 E0103; Hanyo-Denshi; KS403880 -8AA4 E0103; Moji_Joho; MJ024524 -8AA4 E0104; Hanyo-Denshi; JTBB68 -8AA4 E0104; Moji_Joho; MJ024522 -8AA5 E0100; Adobe-Japan1; CID+6680 -8AA5 E0101; Hanyo-Denshi; JA7553 -8AA5 E0101; Moji_Joho; MJ024525 -8AA5 E0102; Hanyo-Denshi; JTBB65 -8AA5 E0102; Moji_Joho; MJ024527 -8AA5 E0103; Moji_Joho; MJ024526 -8AA6 E0100; Adobe-Japan1; CID+6681 -8AA7 E0100; Adobe-Japan1; CID+8619 -8AA8 E0100; Adobe-Japan1; CID+6677 -8AA8 E0101; Hanyo-Denshi; JA7550 -8AA8 E0101; Moji_Joho; MJ024530 -8AA8 E0102; Hanyo-Denshi; FT2545 -8AA8 E0102; Moji_Joho; MJ024531 -8AA9 E0100; Adobe-Japan1; CID+22541 -8AAA E0100; Adobe-Japan1; CID+13880 -8AAA E0101; Hanyo-Denshi; JT8AAA -8AAA E0102; Hanyo-Denshi; KS402930 -8AAC E0100; Adobe-Japan1; CID+2694 -8AAD E0100; Adobe-Japan1; CID+3233 -8AAE E0100; Adobe-Japan1; CID+18679 -8AAE E0101; Hanyo-Denshi; JB6192 -8AAE E0101; Moji_Joho; MJ024537 -8AAE E0102; Hanyo-Denshi; KS405050 -8AAE E0102; Moji_Joho; MJ024538 -8AAF E0100; Adobe-Japan1; CID+22542 -8AB0 E0100; Adobe-Japan1; CID+2925 -8AB2 E0100; Adobe-Japan1; CID+1373 -8AB3 E0100; Adobe-Japan1; CID+22543 -8AB6 E0100; Adobe-Japan1; CID+19807 -8AB7 E0100; Adobe-Japan1; CID+18681 -8AB7 E0101; Hanyo-Denshi; JB6202 -8AB7 E0101; Moji_Joho; MJ024547 -8AB7 E0102; Hanyo-Denshi; KS405080 -8AB7 E0102; Moji_Joho; MJ024548 -8AB9 E0100; Adobe-Japan1; CID+3460 -8AB9 E0101; Adobe-Japan1; CID+13495 -8AB9 E0102; Moji_Joho; MJ024550 -8AB9 E0103; Moji_Joho; MJ024551 -8ABB E0100; Adobe-Japan1; CID+22544 -8ABC E0100; Adobe-Japan1; CID+1629 -8ABE E0100; Adobe-Japan1; CID+8620 -8ABE E0101; Hanyo-Denshi; JB6204 -8ABE E0101; Moji_Joho; MJ024556 -8ABE E0102; Hanyo-Denshi; JTBE5E -8ABE E0102; Moji_Joho; MJ024557 -8ABF E0100; Adobe-Japan1; CID+3024 -8ABF E0101; Adobe-Japan1; CID+13933 -8ABF E0102; Hanyo-Denshi; JA3620 -8ABF E0102; Moji_Joho; MJ024559 -8ABF E0103; Hanyo-Denshi; JTBB6B -8ABF E0103; Moji_Joho; MJ024558 -8AC2 E0100; Adobe-Japan1; CID+6686 -8AC3 E0100; Adobe-Japan1; CID+22545 -8AC4 E0100; Adobe-Japan1; CID+6684 -8AC6 E0100; Adobe-Japan1; CID+22546 -8AC7 E0100; Adobe-Japan1; CID+2954 -8AC8 E0100; Adobe-Japan1; CID+22547 -8AC9 E0100; Adobe-Japan1; CID+19808 -8ACA E0100; Adobe-Japan1; CID+22548 -8ACB E0100; Adobe-Japan1; CID+2661 -8ACB E0101; Adobe-Japan1; CID+13872 -8ACB E0102; Hanyo-Denshi; JA3233 -8ACB E0102; Moji_Joho; MJ024572 -8ACB E0103; Hanyo-Denshi; JTBB6C -8ACB E0103; Moji_Joho; MJ024571 -8ACC E0100; Adobe-Japan1; CID+1550 -8ACD E0100; Adobe-Japan1; CID+6685 -8ACD E0101; Hanyo-Denshi; JA7558 -8ACD E0101; Moji_Joho; MJ024574 -8ACD E0102; Hanyo-Denshi; FT2548 -8ACD E0102; Moji_Joho; MJ024575 -8ACD E0103; Hanyo-Denshi; TK01085150 -8ACF E0100; Adobe-Japan1; CID+2593 -8AD0 E0100; Adobe-Japan1; CID+17127 -8AD1 E0100; Adobe-Japan1; CID+19809 -8AD2 E0100; Adobe-Japan1; CID+3986 -8AD3 E0100; Adobe-Japan1; CID+22549 -8AD4 E0100; Adobe-Japan1; CID+22550 -8AD5 E0100; Adobe-Japan1; CID+22551 -8AD5 E0101; Hanyo-Denshi; JB6213 -8AD5 E0102; Hanyo-Denshi; TK01085320 -8AD6 E0100; Adobe-Japan1; CID+4070 -8AD6 E0101; Hanyo-Denshi; JA4732 -8AD6 E0102; Hanyo-Denshi; TK01085300 -8AD7 E0100; Adobe-Japan1; CID+18682 -8ADA E0100; Adobe-Japan1; CID+6687 -8ADB E0100; Adobe-Japan1; CID+6698 -8ADB E0101; Adobe-Japan1; CID+14219 -8ADB E0102; Hanyo-Denshi; JA7571 -8ADB E0102; Moji_Joho; MJ024593 -8ADB E0103; Hanyo-Denshi; FT2551 -8ADB E0103; Moji_Joho; MJ024595 -8ADB E0104; Hanyo-Denshi; KS405120 -8ADB E0104; Moji_Joho; MJ024594 -8ADC E0100; Adobe-Japan1; CID+3025 -8ADD E0100; Adobe-Japan1; CID+19810 -8ADE E0100; Adobe-Japan1; CID+6697 -8ADE E0101; Adobe-Japan1; CID+7866 -8ADE E0102; Hanyo-Denshi; JA7570 -8ADE E0102; Moji_Joho; MJ024599 -8ADE E0103; Hanyo-Denshi; FT1990 -8ADE E0103; Moji_Joho; MJ024598 -8ADF E0100; Adobe-Japan1; CID+8621 -8AE0 E0100; Adobe-Japan1; CID+6694 -8AE0 E0101; Hanyo-Denshi; JA7567 -8AE0 E0102; Hanyo-Denshi; TK01085310 -8AE1 E0100; Adobe-Japan1; CID+6702 -8AE1 E0101; Hanyo-Denshi; JA7575 -8AE1 E0101; Moji_Joho; MJ024603 -8AE1 E0102; Hanyo-Denshi; FT2553 -8AE1 E0102; Moji_Joho; MJ024604 -8AE2 E0100; Adobe-Japan1; CID+6695 -8AE4 E0100; Adobe-Japan1; CID+6691 -8AE4 E0101; Hanyo-Denshi; JA7564 -8AE4 E0101; Moji_Joho; MJ024607 -8AE4 E0102; Hanyo-Denshi; KS406110 -8AE4 E0102; Moji_Joho; MJ024608 -8AE6 E0100; Adobe-Japan1; CID+3096 -8AE6 E0101; Hanyo-Denshi; JA3692 -8AE6 E0101; Moji_Joho; MJ024610 -8AE6 E0102; Hanyo-Denshi; KS406080 -8AE6 E0102; Moji_Joho; MJ024611 -8AE7 E0100; Adobe-Japan1; CID+6690 -8AEA E0100; Hanyo-Denshi; IP8AEA -8AEA E0101; Hanyo-Denshi; TK01085600 -8AEB E0100; Adobe-Japan1; CID+6688 -8AEC E0100; Adobe-Japan1; CID+19811 -8AED E0100; Adobe-Japan1; CID+14068 -8AED E0101; Adobe-Japan1; CID+3851 -8AED E0102; Hanyo-Denshi; JA4501 -8AED E0102; Moji_Joho; MJ024620 -8AED E0103; Hanyo-Denshi; JTBB72 -8AED E0103; Moji_Joho; MJ024621 -8AED E0104; Hanyo-Denshi; IB2932 -8AED E0104; Moji_Joho; MJ024619 -8AEE E0100; Adobe-Japan1; CID+2238 -8AEE E0101; Adobe-Japan1; CID+13795 -8AEE E0102; Adobe-Japan1; CID+13796 -8AEE E0103; Hanyo-Denshi; JA2780 -8AEE E0103; Moji_Joho; MJ024623 -8AEE E0104; Hanyo-Denshi; JTBB74 -8AEE E0104; Moji_Joho; MJ024622 -8AF0 E0100; Adobe-Japan1; CID+22552 -8AF1 E0100; Adobe-Japan1; CID+6692 -8AF1 E0101; Hanyo-Denshi; JA7565 -8AF1 E0101; Moji_Joho; MJ024627 -8AF1 E0102; Hanyo-Denshi; KS405500 -8AF1 E0102; Moji_Joho; MJ024626 -8AF1 E0103; Moji_Joho; MJ024628 -8AF2 E0100; Hanyo-Denshi; IP8AF2 -8AF2 E0101; Hanyo-Denshi; TK01085550 -8AF3 E0100; Adobe-Japan1; CID+6689 -8AF3 E0101; Hanyo-Denshi; JA7562 -8AF3 E0101; Moji_Joho; MJ024631 -8AF3 E0102; Hanyo-Denshi; KS406090 -8AF3 E0102; Moji_Joho; MJ024632 -8AF4 E0100; Adobe-Japan1; CID+15142 -8AF5 E0100; Adobe-Japan1; CID+19812 -8AF6 E0100; Adobe-Japan1; CID+8623 -8AF6 E0101; Hanyo-Denshi; JB6221 -8AF6 E0101; Moji_Joho; MJ024635 -8AF6 E0102; Hanyo-Denshi; JTBB76 -8AF6 E0102; Moji_Joho; MJ024636 -8AF7 E0100; Adobe-Japan1; CID+6696 -8AF8 E0100; Adobe-Japan1; CID+8622 -8AF8 E0101; Adobe-Japan1; CID+2430 -8AF8 E0102; Hanyo-Denshi; JA2984 -8AF8 E0103; Hanyo-Denshi; JC9214 -8AFA E0100; Adobe-Japan1; CID+1909 -8AFA E0101; Adobe-Japan1; CID+7678 -8AFA E0102; Hanyo-Denshi; JA2433 -8AFA E0102; Moji_Joho; MJ024641 -8AFA E0103; Hanyo-Denshi; FT1794 -8AFA E0103; Moji_Joho; MJ024640 -8AFC E0100; Adobe-Japan1; CID+18683 -8AFC E0101; Hanyo-Denshi; JB6222 -8AFC E0101; Moji_Joho; MJ024643 -8AFC E0102; Hanyo-Denshi; JTBB79 -8AFC E0102; Moji_Joho; MJ024644 -8AFE E0100; Adobe-Japan1; CID+2906 -8AFE E0101; Hanyo-Denshi; JA3490 -8AFE E0101; Moji_Joho; MJ024646 -8AFE E0102; Hanyo-Denshi; KS405700 -8AFE E0102; Moji_Joho; MJ024647 -8AFF E0100; Adobe-Japan1; CID+22553 -8AFF E0101; Moji_Joho; MJ024648 -8AFF E0102; Moji_Joho; MJ024649 -8B00 E0100; Adobe-Japan1; CID+3699 -8B01 E0100; Adobe-Japan1; CID+13321 -8B01 E0101; Adobe-Japan1; CID+1276 -8B01 E0102; Hanyo-Denshi; JA1758 -8B01 E0103; Hanyo-Denshi; JC9215 -8B02 E0100; Adobe-Japan1; CID+1190 -8B04 E0100; Adobe-Japan1; CID+3197 -8B04 E0101; Adobe-Japan1; CID+13958 -8B04 E0102; Hanyo-Denshi; JA3805 -8B04 E0102; Moji_Joho; MJ024654 -8B04 E0103; Hanyo-Denshi; KS406160 -8B04 E0103; Moji_Joho; MJ024653 -8B04 E0104; Hanyo-Denshi; JTBB82 -8B04 E0104; Moji_Joho; MJ024655 -8B05 E0100; Adobe-Japan1; CID+18686 -8B06 E0100; Adobe-Japan1; CID+19813 -8B07 E0100; Adobe-Japan1; CID+6700 -8B0A E0100; Adobe-Japan1; CID+18685 -8B0A E0101; Hanyo-Denshi; JB6231 -8B0A E0101; Moji_Joho; MJ024661 -8B0A E0102; Hanyo-Denshi; KS406860 -8B0A E0102; Moji_Joho; MJ024662 -8B0A E0103; Hanyo-Denshi; JTBB78 -8B0A E0103; Moji_Joho; MJ024664 -8B0A E0104; Hanyo-Denshi; JTBB84 -8B0A E0104; Moji_Joho; MJ024663 -8B0B E0100; Adobe-Japan1; CID+22554 -8B0B E0101; Hanyo-Denshi; JB6226 -8B0B E0101; Moji_Joho; MJ024666 -8B0B E0102; Hanyo-Denshi; KS406330 -8B0B E0102; Moji_Joho; MJ024665 -8B0C E0100; Adobe-Japan1; CID+6699 -8B0D E0100; Adobe-Japan1; CID+18687 -8B0E E0100; Adobe-Japan1; CID+3262 -8B0E E0101; Adobe-Japan1; CID+7766 -8B0E E0102; Hanyo-Denshi; JA3870 -8B0E E0102; Moji_Joho; MJ024669 -8B0E E0103; Hanyo-Denshi; FT1886 -8B0E E0103; Moji_Joho; MJ024670 -8B0F E0100; Adobe-Japan1; CID+19814 -8B0F E0101; Hanyo-Denshi; IP8B0F -8B0F E0102; Hanyo-Denshi; TK01085750 -8B10 E0100; Adobe-Japan1; CID+6704 -8B11 E0100; Adobe-Japan1; CID+19815 -8B13 E0100; Hanyo-Denshi; IP8B13 -8B13 E0101; Hanyo-Denshi; TK01085570 -8B13 E0102; Hanyo-Denshi; TK01085690 -8B14 E0100; Adobe-Japan1; CID+6693 -8B14 E0101; Hanyo-Denshi; JA7566 -8B14 E0101; Moji_Joho; MJ024679 -8B14 E0102; Hanyo-Denshi; FT2550 -8B14 E0102; Moji_Joho; MJ024680 -8B16 E0100; Adobe-Japan1; CID+6703 -8B17 E0100; Adobe-Japan1; CID+6705 -8B17 E0101; Hanyo-Denshi; JA7578 -8B17 E0101; Moji_Joho; MJ024683 -8B17 E0102; Hanyo-Denshi; KS406990 -8B17 E0102; Moji_Joho; MJ024684 -8B19 E0100; Adobe-Japan1; CID+1888 -8B19 E0101; Adobe-Japan1; CID+13753 -8B19 E0102; Hanyo-Denshi; JA2412 -8B19 E0102; Moji_Joho; MJ024687 -8B19 E0103; Hanyo-Denshi; JTBB7FS -8B19 E0103; Moji_Joho; MJ024686 -8B19 E0104; Hanyo-Denshi; TK01085460 -8B19 E0105; Hanyo-Denshi; TK01085560 -8B19 E0106; Hanyo-Denshi; TK01085640 -8B1A E0100; Adobe-Japan1; CID+6701 -8B1A E0101; Hanyo-Denshi; JA7574 -8B1A E0101; Moji_Joho; MJ024690 -8B1A E0102; Hanyo-Denshi; JTBB86 -8B1A E0102; Moji_Joho; MJ024692 -8B1A E0103; Hanyo-Denshi; FT2552S -8B1A E0103; Moji_Joho; MJ024691 -8B1B E0100; Adobe-Japan1; CID+2024 -8B1B E0101; Adobe-Japan1; CID+13773 -8B1B E0102; Hanyo-Denshi; JA2554 -8B1B E0102; Moji_Joho; MJ024694 -8B1B E0103; Hanyo-Denshi; JTBB83 -8B1B E0103; Moji_Joho; MJ024693 -8B1C E0100; Adobe-Japan1; CID+18688 -8B1D E0100; Adobe-Japan1; CID+2305 -8B1D E0101; Adobe-Japan1; CID+13453 -8B1D E0102; Moji_Joho; MJ024696 -8B1D E0103; Moji_Joho; MJ024697 -8B1E E0100; Adobe-Japan1; CID+22555 -8B1F E0100; Adobe-Japan1; CID+15143 -8B20 E0100; Adobe-Japan1; CID+6706 -8B21 E0100; Adobe-Japan1; CID+3906 -8B22 E0100; Hanyo-Denshi; TK01085500 -8B22 E0101; Hanyo-Denshi; TK01085760 -8B23 E0100; Hanyo-Denshi; IP8B23 -8B23 E0100; Moji_Joho; MJ024703 -8B23 E0101; Hanyo-Denshi; KS407780 -8B23 E0101; Moji_Joho; MJ058760 -8B26 E0100; Adobe-Japan1; CID+6709 -8B28 E0100; Adobe-Japan1; CID+6712 -8B28 E0101; Hanyo-Denshi; JA7585 -8B28 E0101; Moji_Joho; MJ024708 -8B28 E0102; Hanyo-Denshi; JTBB8CS -8B28 E0102; Moji_Joho; MJ024709 -8B2B E0100; Adobe-Japan1; CID+6710 -8B2B E0101; Hanyo-Denshi; JA7583 -8B2B E0101; Moji_Joho; MJ024712 -8B2B E0102; Hanyo-Denshi; KS407770 -8B2B E0102; Moji_Joho; MJ024713 -8B2C E0100; Adobe-Japan1; CID+3495 -8B2C E0101; Adobe-Japan1; CID+7785 -8B2C E0102; Hanyo-Denshi; JA4121 -8B2C E0102; Moji_Joho; MJ024715 -8B2C E0103; Hanyo-Denshi; HG1657 -8B2C E0103; Moji_Joho; MJ024714 -8B2D E0100; Adobe-Japan1; CID+18689 -8B30 E0100; Adobe-Japan1; CID+22556 -8B33 E0100; Adobe-Japan1; CID+6707 -8B33 E0101; Hanyo-Denshi; JA7580 -8B33 E0101; Moji_Joho; MJ024722 -8B33 E0102; Hanyo-Denshi; KS407820 -8B33 E0102; Moji_Joho; MJ024723 -8B33 E0103; Hanyo-Denshi; KS406120 -8B33 E0103; Moji_Joho; MJ058752 -8B37 E0100; Adobe-Japan1; CID+15144 -8B37 E0101; Hanyo-Denshi; JB6234 -8B37 E0101; Moji_Joho; MJ024727 -8B37 E0102; Hanyo-Denshi; JTBB8A -8B37 E0102; Moji_Joho; MJ024728 -8B39 E0100; Adobe-Japan1; CID+13339 -8B39 E0101; Adobe-Japan1; CID+1752 -8B39 E0102; Hanyo-Denshi; JA2264 -8B39 E0102; Moji_Joho; MJ024730 -8B39 E0103; Hanyo-Denshi; JTBB91 -8B39 E0103; Moji_Joho; MJ024731 -8B39 E0104; Hanyo-Denshi; JC9216 -8B39 E0105; Hanyo-Denshi; JTBB77 -8B39 E0105; Moji_Joho; MJ060186 -8B39 E0106; Hanyo-Denshi; TK01085610 -8B39 E0107; Hanyo-Denshi; TK01085770 -8B39 E0108; Hanyo-Denshi; TK01085820 -8B3C E0100; Adobe-Japan1; CID+22557 -8B3E E0100; Adobe-Japan1; CID+6711 -8B3E E0101; Adobe-Japan1; CID+14220 -8B3E E0102; Hanyo-Denshi; JA7584 -8B3E E0102; Moji_Joho; MJ024737 -8B3E E0103; Hanyo-Denshi; KS407590 -8B3E E0103; Moji_Joho; MJ024736 -8B41 E0100; Adobe-Japan1; CID+6713 -8B41 E0101; Adobe-Japan1; CID+7867 -8B41 E0102; Hanyo-Denshi; JA7586 -8B41 E0102; Moji_Joho; MJ024740 -8B41 E0103; Hanyo-Denshi; KS408570 -8B41 E0103; Moji_Joho; MJ024742 -8B41 E0104; Hanyo-Denshi; JTBB8D -8B41 E0104; Moji_Joho; MJ024741 -8B42 E0100; Adobe-Japan1; CID+22558 -8B42 E0101; Hanyo-Denshi; JB6236 -8B42 E0102; Hanyo-Denshi; TK01085580 -8B43 E0100; Adobe-Japan1; CID+15145 -8B44 E0100; Adobe-Japan1; CID+15146 -8B44 E0101; Hanyo-Denshi; JB6238 -8B44 E0101; Moji_Joho; MJ024745 -8B44 E0102; Hanyo-Denshi; JTBB8F -8B44 E0102; Moji_Joho; MJ024746 -8B44 E0103; Hanyo-Denshi; JTBB90 -8B44 E0103; Moji_Joho; MJ024747 -8B44 E0104; Hanyo-Denshi; TK01085790 -8B44 E0105; Hanyo-Denshi; TK01086040 -8B45 E0100; Adobe-Japan1; CID+19816 -8B45 E0101; Hanyo-Denshi; JB6239 -8B45 E0101; Moji_Joho; MJ024750 -8B45 E0102; Hanyo-Denshi; JTBB9E -8B45 E0102; Moji_Joho; MJ024751 -8B46 E0100; Adobe-Japan1; CID+17128 -8B48 E0100; Adobe-Japan1; CID+22559 -8B49 E0100; Adobe-Japan1; CID+6717 -8B4C E0100; Adobe-Japan1; CID+6714 -8B4C E0101; Hanyo-Denshi; JA7587 -8B4C E0101; Moji_Joho; MJ024758 -8B4C E0102; Hanyo-Denshi; FT2554 -8B4C E0102; Moji_Joho; MJ024760 -8B4C E0103; Hanyo-Denshi; JTBB94 -8B4C E0103; Moji_Joho; MJ024759 -8B4D E0100; Adobe-Japan1; CID+22560 -8B4E E0100; Adobe-Japan1; CID+6716 -8B4F E0100; Adobe-Japan1; CID+6715 -8B4F E0101; Hanyo-Denshi; JA7588 -8B4F E0101; Moji_Joho; MJ024765 -8B4F E0102; Hanyo-Denshi; KS408530 -8B4F E0102; Moji_Joho; MJ024763 -8B4F E0103; Hanyo-Denshi; JA7588S -8B4F E0103; Moji_Joho; MJ024764 -8B51 E0100; Adobe-Japan1; CID+18691 -8B52 E0100; Adobe-Japan1; CID+19817 -8B53 E0100; Adobe-Japan1; CID+8624 -8B53 E0101; Hanyo-Denshi; JB6243 -8B53 E0101; Moji_Joho; MJ024769 -8B53 E0102; Hanyo-Denshi; IB2937 -8B53 E0102; Moji_Joho; MJ024770 -8B53 E0103; Hanyo-Denshi; JTBB92 -8B53 E0103; Moji_Joho; MJ060190 -8B54 E0100; Adobe-Japan1; CID+15147 -8B56 E0100; Adobe-Japan1; CID+6718 -8B56 E0101; Adobe-Japan1; CID+20216 -8B56 E0102; Adobe-Japan1; CID+20217 -8B56 E0103; Hanyo-Denshi; JA7591 -8B56 E0103; Moji_Joho; MJ024773 -8B56 E0104; Hanyo-Denshi; JTBBA1S -8B56 E0104; Moji_Joho; MJ024774 -8B58 E0100; Adobe-Japan1; CID+2269 -8B58 E0101; Hanyo-Denshi; JA2817 -8B58 E0101; Moji_Joho; MJ024776 -8B58 E0102; Hanyo-Denshi; JTBB93 -8B58 E0102; Moji_Joho; MJ024777 -8B59 E0100; Adobe-Japan1; CID+17129 -8B5A E0100; Adobe-Japan1; CID+6720 -8B5A E0101; Adobe-Japan1; CID+14221 -8B5A E0102; Hanyo-Denshi; JA7593 -8B5A E0102; Moji_Joho; MJ024780 -8B5A E0103; Hanyo-Denshi; KS408330 -8B5A E0103; Moji_Joho; MJ024779 -8B5B E0100; Adobe-Japan1; CID+6719 -8B5C E0100; Adobe-Japan1; CID+3546 -8B5C E0101; Adobe-Japan1; CID+20218 -8B5C E0102; Hanyo-Denshi; JA4172 -8B5C E0102; Moji_Joho; MJ024782 -8B5C E0103; Hanyo-Denshi; JTBB9B -8B5C E0103; Moji_Joho; MJ024783 -8B5E E0100; Adobe-Japan1; CID+18692 -8B5F E0100; Adobe-Japan1; CID+6722 -8B61 E0100; Hanyo-Denshi; IP8B61 -8B61 E0100; Moji_Joho; MJ024788 -8B61 E0101; Hanyo-Denshi; KS409580 -8B61 E0101; Moji_Joho; MJ024789 -8B62 E0100; Hanyo-Denshi; IP8B62 -8B62 E0101; Hanyo-Denshi; TK01085930 -8B63 E0100; Adobe-Japan1; CID+22561 -8B66 E0100; Adobe-Japan1; CID+1839 -8B66 E0101; Hanyo-Denshi; JA2357 -8B66 E0101; Moji_Joho; MJ024795 -8B66 E0102; Hanyo-Denshi; KS408750S -8B66 E0102; Moji_Joho; MJ024796 -8B69 E0100; Adobe-Japan1; CID+17130 -8B69 E0101; Hanyo-Denshi; JC9220 -8B69 E0101; Moji_Joho; MJ024799 -8B69 E0102; Hanyo-Denshi; KS409100 -8B69 E0102; Moji_Joho; MJ024800 -8B6A E0100; Hanyo-Denshi; IP8B6A -8B6A E0100; Moji_Joho; MJ024801 -8B6A E0101; Hanyo-Denshi; KS408810 -8B6A E0101; Moji_Joho; MJ024802 -8B6A E0102; Moji_Joho; MJ024803 -8B6B E0100; Adobe-Japan1; CID+6721 -8B6C E0100; Adobe-Japan1; CID+6723 -8B6D E0100; Adobe-Japan1; CID+19818 -8B6D E0101; Hanyo-Denshi; JB6249 -8B6D E0101; Moji_Joho; MJ024806 -8B6D E0102; Hanyo-Denshi; KS409130 -8B6D E0102; Moji_Joho; MJ058766 -8B6E E0100; Hanyo-Denshi; IP8B6E -8B6E E0101; Hanyo-Denshi; TK01086070 -8B6F E0100; Adobe-Japan1; CID+6724 -8B70 E0100; Adobe-Japan1; CID+1630 -8B71 E0100; Adobe-Japan1; CID+6190 -8B71 E0101; Hanyo-Denshi; JA7033 -8B71 E0101; Moji_Joho; MJ024811 -8B71 E0102; Hanyo-Denshi; JTAF2D -8B71 E0102; Moji_Joho; MJ024812 -8B72 E0100; Adobe-Japan1; CID+2529 -8B74 E0100; Adobe-Japan1; CID+6725 -8B74 E0101; Hanyo-Denshi; JA7604 -8B74 E0101; Moji_Joho; MJ024816 -8B74 E0102; Hanyo-Denshi; FT2555 -8B74 E0102; Moji_Joho; MJ024815 -8B76 E0100; Adobe-Japan1; CID+18693 -8B77 E0100; Adobe-Japan1; CID+1954 -8B77 E0101; Hanyo-Denshi; JA2478 -8B77 E0101; Moji_Joho; MJ024819 -8B77 E0102; Hanyo-Denshi; KS409240 -8B77 E0102; Moji_Joho; MJ024820 -8B78 E0100; Adobe-Japan1; CID+19819 -8B79 E0100; Adobe-Japan1; CID+22562 -8B7C E0100; Adobe-Japan1; CID+19820 -8B7D E0100; Adobe-Japan1; CID+6726 -8B7E E0100; Adobe-Japan1; CID+19821 -8B7F E0100; Adobe-Japan1; CID+8625 -8B7F E0101; Adobe-Japan1; CID+21074 -8B80 E0100; Adobe-Japan1; CID+6727 -8B81 E0100; Adobe-Japan1; CID+18694 -8B81 E0101; Hanyo-Denshi; JB6255 -8B81 E0101; Moji_Joho; MJ024831 -8B81 E0102; Hanyo-Denshi; KS410000 -8B81 E0102; Moji_Joho; MJ024832 -8B81 E0103; Hanyo-Denshi; IB0893 -8B81 E0103; Moji_Joho; MJ024830 -8B83 E0100; Adobe-Japan1; CID+2188 -8B84 E0100; Adobe-Japan1; CID+22563 -8B85 E0100; Adobe-Japan1; CID+19822 -8B89 E0100; Hanyo-Denshi; IB0894 -8B89 E0100; Moji_Joho; MJ024838 -8B89 E0101; Hanyo-Denshi; IP8B89 -8B89 E0101; Moji_Joho; MJ024839 -8B8A E0100; Adobe-Japan1; CID+5075 -8B8A E0101; Hanyo-Denshi; JA5846 -8B8A E0101; Moji_Joho; MJ024841 -8B8A E0102; Hanyo-Denshi; KS409940 -8B8A E0102; Moji_Joho; MJ024840 -8B8B E0100; Adobe-Japan1; CID+18695 -8B8B E0101; Hanyo-Denshi; JB6258 -8B8B E0101; Moji_Joho; MJ024842 -8B8B E0102; Hanyo-Denshi; KS410250 -8B8B E0102; Moji_Joho; MJ024843 -8B8C E0100; Adobe-Japan1; CID+6728 -8B8C E0101; Hanyo-Denshi; JA7607 -8B8C E0101; Moji_Joho; MJ024844 -8B8C E0102; Hanyo-Denshi; JTBBA5S -8B8C E0102; Moji_Joho; MJ024845 -8B8D E0100; Adobe-Japan1; CID+22564 -8B8E E0100; Adobe-Japan1; CID+6729 -8B8F E0100; Adobe-Japan1; CID+22565 -8B90 E0100; Adobe-Japan1; CID+2364 -8B92 E0100; Adobe-Japan1; CID+6730 -8B93 E0100; Adobe-Japan1; CID+6731 -8B94 E0100; Adobe-Japan1; CID+18696 -8B95 E0100; Adobe-Japan1; CID+18697 -8B96 E0100; Adobe-Japan1; CID+6732 -8B99 E0100; Adobe-Japan1; CID+6733 -8B99 E0101; Hanyo-Denshi; JA7612 -8B99 E0101; Moji_Joho; MJ024858 -8B99 E0102; Hanyo-Denshi; KS410480 -8B99 E0102; Moji_Joho; MJ024859 -8B9A E0100; Adobe-Japan1; CID+6734 -8B9C E0100; Adobe-Japan1; CID+15148 -8B9D E0100; Adobe-Japan1; CID+17131 -8B9E E0100; Adobe-Japan1; CID+15149 -8B9F E0100; Adobe-Japan1; CID+19823 -8C37 E0100; Adobe-Japan1; CID+2921 -8C38 E0100; Adobe-Japan1; CID+22566 -8C39 E0100; Adobe-Japan1; CID+18698 -8C3A E0100; Adobe-Japan1; CID+6735 -8C3A E0101; Hanyo-Denshi; JA7614 -8C3A E0101; Moji_Joho; MJ024870 -8C3A E0102; Hanyo-Denshi; JTBBA8 -8C3A E0102; Moji_Joho; MJ024869 -8C3A E0103; Moji_Joho; MJ024871 -8C3A E0104; Moji_Joho; MJ024872 -8C3D E0100; Adobe-Japan1; CID+18700 -8C3E E0100; Adobe-Japan1; CID+22567 -8C3E E0101; Hanyo-Denshi; JB6269 -8C3E E0101; Moji_Joho; MJ024876 -8C3E E0102; Hanyo-Denshi; KS411100 -8C3E E0102; Moji_Joho; MJ024877 -8C3F E0100; Adobe-Japan1; CID+6737 -8C3F E0101; Hanyo-Denshi; JA7616 -8C3F E0101; Moji_Joho; MJ024878 -8C3F E0102; Hanyo-Denshi; FT2558 -8C3F E0102; Moji_Joho; MJ024879 -8C41 E0100; Adobe-Japan1; CID+6736 -8C41 E0101; Hanyo-Denshi; JA7615 -8C41 E0101; Moji_Joho; MJ024882 -8C41 E0102; Hanyo-Denshi; KS411170S -8C41 E0102; Moji_Joho; MJ024881 -8C41 E0103; Hanyo-Denshi; JTBBABS -8C41 E0103; Moji_Joho; MJ024883 -8C41 E0104; Hanyo-Denshi; FT2557 -8C41 E0104; Moji_Joho; MJ024884 -8C45 E0100; Adobe-Japan1; CID+18703 -8C45 E0101; Hanyo-Denshi; JB6270 -8C45 E0101; Moji_Joho; MJ024888 -8C45 E0102; Hanyo-Denshi; KS411430 -8C45 E0102; Moji_Joho; MJ024889 -8C46 E0100; Adobe-Japan1; CID+3198 -8C47 E0100; Adobe-Japan1; CID+15150 -8C48 E0100; Adobe-Japan1; CID+6738 -8C49 E0100; Adobe-Japan1; CID+17132 -8C4A E0100; Adobe-Japan1; CID+3675 -8C4B E0100; Adobe-Japan1; CID+19824 -8C4C E0100; Adobe-Japan1; CID+6739 -8C4E E0100; Adobe-Japan1; CID+6740 -8C4F E0100; Adobe-Japan1; CID+18704 -8C50 E0100; Adobe-Japan1; CID+6741 -8C51 E0100; Adobe-Japan1; CID+22568 -8C53 E0100; Adobe-Japan1; CID+19825 -8C53 E0101; Moji_Joho; MJ024902 -8C53 E0102; Moji_Joho; MJ024903 -8C54 E0100; Adobe-Japan1; CID+15151 -8C55 E0100; Adobe-Japan1; CID+6742 -8C55 E0101; Hanyo-Denshi; JA7621 -8C55 E0101; Moji_Joho; MJ024906 -8C55 E0102; Hanyo-Denshi; KS412370 -8C55 E0102; Moji_Joho; MJ024905 -8C55 E0103; Hanyo-Denshi; FT2559 -8C55 E0103; Moji_Joho; MJ024907 -8C57 E0100; Adobe-Japan1; CID+18705 -8C57 E0101; Hanyo-Denshi; JB6278 -8C57 E0101; Moji_Joho; MJ024909 -8C57 E0102; Hanyo-Denshi; KS412480 -8C57 E0102; Moji_Joho; MJ024910 -8C58 E0100; Adobe-Japan1; CID+22569 -8C59 E0100; Adobe-Japan1; CID+22572 -8C59 E0101; Hanyo-Denshi; JB6282 -8C59 E0101; Moji_Joho; MJ024912 -8C59 E0102; Hanyo-Denshi; IB2958 -8C59 E0102; Moji_Joho; MJ024913 -8C5A E0100; Adobe-Japan1; CID+3250 -8C5A E0101; Hanyo-Denshi; JA3858 -8C5A E0101; Moji_Joho; MJ024914 -8C5A E0102; Hanyo-Denshi; FT2048 -8C5A E0102; Moji_Joho; MJ024915 -8C5B E0100; Adobe-Japan1; CID+22570 -8C5D E0100; Adobe-Japan1; CID+22571 -8C61 E0100; Adobe-Japan1; CID+2501 -8C61 E0101; Hanyo-Denshi; JA3061 -8C61 E0101; Moji_Joho; MJ024924 -8C61 E0102; Hanyo-Denshi; KS412680 -8C61 E0102; Moji_Joho; MJ024923 -8C61 E0103; Hanyo-Denshi; FT2036 -8C61 E0103; Moji_Joho; MJ024922 -8C62 E0100; Adobe-Japan1; CID+6743 -8C62 E0101; Hanyo-Denshi; JA7622 -8C62 E0101; Moji_Joho; MJ024926 -8C62 E0102; Hanyo-Denshi; FT2560S -8C62 E0102; Moji_Joho; MJ024927 -8C63 E0100; Adobe-Japan1; CID+22573 -8C64 E0100; Adobe-Japan1; CID+22574 -8C66 E0100; Adobe-Japan1; CID+22575 -8C66 E0101; Hanyo-Denshi; JB6285 -8C66 E0101; Moji_Joho; MJ024931 -8C66 E0102; Hanyo-Denshi; JTBBB4 -8C66 E0102; Moji_Joho; MJ024932 -8C68 E0100; Adobe-Japan1; CID+17133 -8C69 E0100; Adobe-Japan1; CID+18706 -8C6A E0100; Adobe-Japan1; CID+2045 -8C6A E0101; Adobe-Japan1; CID+20221 -8C6A E0102; Hanyo-Denshi; JA2575 -8C6A E0102; Moji_Joho; MJ024936 -8C6A E0103; Hanyo-Denshi; JTBBB9S -8C6A E0103; Moji_Joho; MJ024937 -8C6A E0104; Hanyo-Denshi; FT2031 -8C6A E0104; Moji_Joho; MJ024938 -8C6B E0100; Adobe-Japan1; CID+4103 -8C6B E0101; Hanyo-Denshi; JA4814 -8C6B E0101; Moji_Joho; MJ024939 -8C6B E0102; Hanyo-Denshi; FT2063 -8C6B E0102; Moji_Joho; MJ024940 -8C6C E0100; Adobe-Japan1; CID+6744 -8C6C E0101; Hanyo-Denshi; JA7623 -8C6C E0101; Moji_Joho; MJ024941 -8C6C E0102; Hanyo-Denshi; FT2561S -8C6C E0102; Moji_Joho; MJ024942 -8C6D E0100; Adobe-Japan1; CID+18707 -8C73 E0100; Adobe-Japan1; CID+15152 -8C75 E0100; Adobe-Japan1; CID+22576 -8C76 E0100; Adobe-Japan1; CID+22577 -8C76 E0101; Hanyo-Denshi; JB6291 -8C76 E0101; Moji_Joho; MJ024951 -8C76 E0102; Hanyo-Denshi; KS413790 -8C76 E0102; Moji_Joho; MJ024952 -8C78 E0100; Adobe-Japan1; CID+6745 -8C79 E0100; Adobe-Japan1; CID+3505 -8C79 E0101; Adobe-Japan1; CID+20222 -8C79 E0102; Hanyo-Denshi; JA4131 -8C79 E0102; Moji_Joho; MJ024956 -8C79 E0103; Hanyo-Denshi; HG1658 -8C79 E0103; Moji_Joho; MJ024955 -8C7A E0100; Adobe-Japan1; CID+6746 -8C7B E0100; Adobe-Japan1; CID+19826 -8C7C E0100; Adobe-Japan1; CID+6754 -8C7E E0100; Adobe-Japan1; CID+22578 -8C82 E0100; Adobe-Japan1; CID+6747 -8C85 E0100; Adobe-Japan1; CID+6749 -8C86 E0100; Adobe-Japan1; CID+22579 -8C87 E0100; Adobe-Japan1; CID+22580 -8C89 E0100; Adobe-Japan1; CID+6748 -8C8A E0100; Adobe-Japan1; CID+6750 -8C8B E0100; Adobe-Japan1; CID+22581 -8C8C E0100; Adobe-Japan1; CID+3700 -8C8D E0100; Adobe-Japan1; CID+6751 -8C8E E0100; Adobe-Japan1; CID+6752 -8C90 E0100; Adobe-Japan1; CID+22582 -8C92 E0100; Adobe-Japan1; CID+18710 -8C93 E0100; Adobe-Japan1; CID+18709 -8C93 E0101; Hanyo-Denshi; JB6305 -8C93 E0101; Moji_Joho; MJ024982 -8C93 E0102; Hanyo-Denshi; KS415100 -8C93 E0102; Moji_Joho; MJ024983 -8C94 E0100; Adobe-Japan1; CID+6753 -8C98 E0100; Adobe-Japan1; CID+6755 -8C98 E0101; Hanyo-Denshi; JA7634 -8C98 E0101; Moji_Joho; MJ024988 -8C98 E0102; Hanyo-Denshi; KS415380 -8C98 E0102; Moji_Joho; MJ024989 -8C99 E0100; Adobe-Japan1; CID+18711 -8C9B E0100; Adobe-Japan1; CID+18713 -8C9B E0101; Adobe-Japan1; CID+22583 -8C9B E0102; Hanyo-Denshi; JB6307 -8C9B E0102; Moji_Joho; MJ024992 -8C9B E0103; Hanyo-Denshi; JD8910 -8C9B E0103; Moji_Joho; MJ024993 -8C9C E0100; Adobe-Japan1; CID+22584 -8C9D E0100; Adobe-Japan1; CID+1419 -8C9E E0100; Adobe-Japan1; CID+3075 -8C9F E0100; Adobe-Japan1; CID+13644 -8CA0 E0100; Adobe-Japan1; CID+3547 -8CA0 E0101; Adobe-Japan1; CID+14005 -8CA0 E0102; Adobe-Japan1; CID+14006 -8CA0 E0103; Hanyo-Denshi; JA4173 -8CA0 E0103; Moji_Joho; MJ024999 -8CA0 E0104; Hanyo-Denshi; JTBBC0 -8CA0 E0104; Moji_Joho; MJ024998 -8CA0 E0105; Hanyo-Denshi; IB0903 -8CA0 E0105; Moji_Joho; MJ025000 -8CA1 E0100; Adobe-Japan1; CID+2130 -8CA1 E0101; Hanyo-Denshi; JA2666 -8CA1 E0102; Hanyo-Denshi; TK01086700 -8CA1 E0103; Hanyo-Denshi; TK01086740 -8CA2 E0100; Adobe-Japan1; CID+2025 -8CA4 E0100; Adobe-Japan1; CID+15153 -8CA7 E0100; Adobe-Japan1; CID+3521 -8CA7 E0101; Adobe-Japan1; CID+13496 -8CA7 E0102; Hanyo-Denshi; JA4147 -8CA7 E0102; Moji_Joho; MJ025007 -8CA7 E0103; Hanyo-Denshi; FT1666 -8CA7 E0103; Moji_Joho; MJ025008 -8CA8 E0100; Adobe-Japan1; CID+1375 -8CA8 E0101; Adobe-Japan1; CID+13668 -8CA8 E0102; Hanyo-Denshi; JA1863 -8CA8 E0102; Moji_Joho; MJ025009 -8CA8 E0103; Hanyo-Denshi; KS416190 -8CA8 E0103; Moji_Joho; MJ025010 -8CA9 E0100; Adobe-Japan1; CID+3426 -8CAA E0100; Adobe-Japan1; CID+6758 -8CAB E0100; Adobe-Japan1; CID+1551 -8CAB E0101; Adobe-Japan1; CID+13426 -8CAB E0102; Hanyo-Denshi; JA2051 -8CAB E0102; Moji_Joho; MJ025013 -8CAB E0103; Hanyo-Denshi; KS416650 -8CAB E0103; Moji_Joho; MJ025014 -8CAB E0104; Moji_Joho; MJ025015 -8CAC E0100; Adobe-Japan1; CID+2681 -8CAD E0100; Adobe-Japan1; CID+6757 -8CAE E0100; Adobe-Japan1; CID+6762 -8CAF E0100; Adobe-Japan1; CID+2999 -8CB0 E0100; Adobe-Japan1; CID+3823 -8CB2 E0100; Adobe-Japan1; CID+6760 -8CB3 E0100; Adobe-Japan1; CID+6761 -8CB4 E0100; Adobe-Japan1; CID+1608 -8CB6 E0100; Adobe-Japan1; CID+6763 -8CB7 E0100; Adobe-Japan1; CID+3353 -8CB8 E0100; Adobe-Japan1; CID+2879 -8CB9 E0100; Adobe-Japan1; CID+22585 -8CBA E0100; Adobe-Japan1; CID+19827 -8CBB E0100; Adobe-Japan1; CID+3461 -8CBC E0100; Adobe-Japan1; CID+3127 -8CBD E0100; Adobe-Japan1; CID+6759 -8CBF E0100; Adobe-Japan1; CID+3701 -8CBF E0101; Hanyo-Denshi; JA4339 -8CBF E0101; Moji_Joho; MJ025035 -8CBF E0102; Hanyo-Denshi; KS416200 -8CBF E0102; Moji_Joho; MJ058784 -8CC0 E0100; Adobe-Japan1; CID+1388 -8CC1 E0100; Adobe-Japan1; CID+6765 -8CC1 E0101; Hanyo-Denshi; JA7644 -8CC1 E0101; Moji_Joho; MJ025037 -8CC1 E0102; Hanyo-Denshi; KS416670 -8CC1 E0102; Moji_Joho; MJ025038 -8CC2 E0100; Adobe-Japan1; CID+4046 -8CC3 E0100; Adobe-Japan1; CID+3038 -8CC4 E0100; Adobe-Japan1; CID+4075 -8CC5 E0100; Adobe-Japan1; CID+19828 -8CC5 E0101; Hanyo-Denshi; JB6312 -8CC5 E0101; Moji_Joho; MJ025042 -8CC5 E0102; Hanyo-Denshi; KS417080 -8CC5 E0102; Moji_Joho; MJ025043 -8CC6 E0100; Adobe-Japan1; CID+22586 -8CC6 E0101; Hanyo-Denshi; JB6313 -8CC6 E0102; Hanyo-Denshi; TK01086860 -8CC7 E0100; Adobe-Japan1; CID+2239 -8CC7 E0101; Adobe-Japan1; CID+13797 -8CC7 E0102; Adobe-Japan1; CID+13798 -8CC7 E0103; Hanyo-Denshi; JA2781 -8CC7 E0103; Moji_Joho; MJ025047 -8CC7 E0104; Hanyo-Denshi; JTBBC5 -8CC7 E0104; Moji_Joho; MJ025046 -8CC8 E0100; Adobe-Japan1; CID+6764 -8CC9 E0100; Adobe-Japan1; CID+19829 -8CCA E0100; Adobe-Japan1; CID+2833 -8CCA E0101; Adobe-Japan1; CID+13900 -8CCA E0102; Adobe-Japan1; CID+20223 -8CCA E0103; Hanyo-Denshi; JA3417 -8CCA E0103; Moji_Joho; MJ025051 -8CCA E0104; Hanyo-Denshi; JTBBC6 -8CCA E0104; Moji_Joho; MJ025050 -8CCB E0100; Adobe-Japan1; CID+22587 -8CCB E0101; Moji_Joho; MJ025052 -8CCB E0102; Moji_Joho; MJ025053 -8CCD E0100; Adobe-Japan1; CID+6781 -8CCE E0100; Adobe-Japan1; CID+2730 -8CCF E0100; Adobe-Japan1; CID+22588 -8CD1 E0100; Adobe-Japan1; CID+3280 -8CD2 E0100; Adobe-Japan1; CID+19830 -8CD3 E0100; Adobe-Japan1; CID+13380 -8CD3 E0101; Adobe-Japan1; CID+3522 -8CD3 E0102; Hanyo-Denshi; JA4148 -8CD3 E0102; Moji_Joho; MJ025062 -8CD3 E0103; Hanyo-Denshi; JC9224 -8CD3 E0103; Moji_Joho; MJ030299 -8CD3 E0104; Moji_Joho; MJ030300 -8CD4 E0100; Hanyo-Denshi; IP8CD4 -8CD4 E0100; Moji_Joho; MJ025063 -8CD4 E0101; Hanyo-Denshi; KS417120 -8CD4 E0101; Moji_Joho; MJ058790 -8CD5 E0100; Adobe-Japan1; CID+18715 -8CD6 E0100; Adobe-Japan1; CID+18714 -8CD9 E0100; Adobe-Japan1; CID+15154 -8CDA E0100; Adobe-Japan1; CID+6768 -8CDB E0100; Adobe-Japan1; CID+2189 -8CDC E0100; Adobe-Japan1; CID+2240 -8CDD E0100; Adobe-Japan1; CID+22589 -8CDE E0100; Adobe-Japan1; CID+2502 -8CE0 E0100; Adobe-Japan1; CID+3355 -8CE1 E0100; Adobe-Japan1; CID+15155 -8CE2 E0100; Adobe-Japan1; CID+1889 -8CE3 E0100; Adobe-Japan1; CID+6767 -8CE4 E0100; Adobe-Japan1; CID+6766 -8CE6 E0100; Adobe-Japan1; CID+3548 -8CE8 E0100; Adobe-Japan1; CID+22590 -8CEA E0100; Adobe-Japan1; CID+2285 -8CEC E0100; Adobe-Japan1; CID+19831 -8CED E0100; Adobe-Japan1; CID+3148 -8CED E0101; Adobe-Japan1; CID+7756 -8CED E0102; Hanyo-Denshi; JA3750 -8CED E0102; Moji_Joho; MJ025087 -8CED E0103; Hanyo-Denshi; FT1876 -8CED E0103; Moji_Joho; MJ025088 -8CEE E0100; Hanyo-Denshi; IP8CEE -8CEE E0101; Hanyo-Denshi; TK01087100 -8CEF E0100; Adobe-Japan1; CID+22591 -8CF0 E0100; Adobe-Japan1; CID+8626 -8CF1 E0100; Adobe-Japan1; CID+18717 -8CF2 E0100; Adobe-Japan1; CID+22592 -8CF2 E0101; Hanyo-Denshi; JB6326 -8CF2 E0101; Moji_Joho; MJ025093 -8CF2 E0102; Hanyo-Denshi; IB2965 -8CF2 E0102; Moji_Joho; MJ025094 -8CF4 E0100; Adobe-Japan1; CID+8627 -8CF5 E0100; Adobe-Japan1; CID+19832 -8CF7 E0100; Adobe-Japan1; CID+19833 -8CF8 E0100; Adobe-Japan1; CID+15156 -8CFA E0100; Adobe-Japan1; CID+6770 -8CFA E0101; Hanyo-Denshi; JA7649 -8CFA E0101; Moji_Joho; MJ025102 -8CFA E0102; Hanyo-Denshi; FT2562 -8CFA E0102; Moji_Joho; MJ025103 -8CFB E0100; Adobe-Japan1; CID+6771 -8CFB E0101; Hanyo-Denshi; JA7650 -8CFB E0101; Moji_Joho; MJ025104 -8CFB E0102; Hanyo-Denshi; FT2563 -8CFB E0102; Moji_Joho; MJ025105 -8CFC E0100; Adobe-Japan1; CID+2026 -8CFC E0101; Adobe-Japan1; CID+13446 -8CFC E0102; Adobe-Japan1; CID+13774 -8CFC E0103; Hanyo-Denshi; JA2556 -8CFC E0103; Moji_Joho; MJ025107 -8CFC E0104; Hanyo-Denshi; JTBBCE -8CFC E0104; Moji_Joho; MJ025106 -8CFC E0105; Moji_Joho; MJ025108 -8CFD E0100; Adobe-Japan1; CID+6769 -8CFE E0100; Adobe-Japan1; CID+15157 -8CFE E0101; Hanyo-Denshi; JB6330 -8CFE E0102; Hanyo-Denshi; TK01087200 -8CFF E0100; Adobe-Japan1; CID+22593 -8D01 E0100; Adobe-Japan1; CID+19834 -8D03 E0100; Adobe-Japan1; CID+19835 -8D04 E0100; Adobe-Japan1; CID+6772 -8D05 E0100; Adobe-Japan1; CID+6773 -8D05 E0101; Adobe-Japan1; CID+13602 -8D05 E0102; Hanyo-Denshi; JA7652 -8D05 E0102; Moji_Joho; MJ025118 -8D05 E0103; Hanyo-Denshi; FT1735 -8D05 E0103; Moji_Joho; MJ025119 -8D07 E0100; Adobe-Japan1; CID+6775 -8D08 E0100; Adobe-Japan1; CID+2819 -8D08 E0101; Adobe-Japan1; CID+13364 -8D08 E0102; Hanyo-Denshi; JA3403 -8D08 E0103; Hanyo-Denshi; JC9229 -8D09 E0100; Adobe-Japan1; CID+18719 -8D09 E0101; Hanyo-Denshi; JB6334 -8D09 E0101; Moji_Joho; MJ025123 -8D09 E0102; Hanyo-Denshi; KS418990 -8D09 E0102; Moji_Joho; MJ025124 -8D0A E0100; Adobe-Japan1; CID+6774 -8D0A E0101; Moji_Joho; MJ025125 -8D0A E0102; Moji_Joho; MJ025126 -8D0B E0100; Adobe-Japan1; CID+1570 -8D0D E0100; Adobe-Japan1; CID+6777 -8D0E E0100; Adobe-Japan1; CID+18720 -8D0E E0101; Hanyo-Denshi; JD8920 -8D0E E0101; Moji_Joho; MJ025129 -8D0E E0102; Hanyo-Denshi; KS419020 -8D0E E0102; Moji_Joho; MJ025130 -8D0F E0100; Adobe-Japan1; CID+6776 -8D0F E0101; Adobe-Japan1; CID+13603 -8D0F E0102; Hanyo-Denshi; JA7655 -8D0F E0102; Moji_Joho; MJ025132 -8D0F E0103; Hanyo-Denshi; KS419050 -8D0F E0103; Moji_Joho; MJ025131 -8D0F E0104; Hanyo-Denshi; JTBBD9 -8D0F E0104; Moji_Joho; MJ025134 -8D0F E0105; Hanyo-Denshi; FT1736 -8D0F E0105; Moji_Joho; MJ025133 -8D10 E0100; Adobe-Japan1; CID+6778 -8D10 E0101; Hanyo-Denshi; JA7657 -8D10 E0101; Moji_Joho; MJ025135 -8D10 E0102; Hanyo-Denshi; JTBBDD -8D10 E0102; Moji_Joho; MJ025136 -8D11 E0100; Hanyo-Denshi; IP8D11 -8D11 E0100; Moji_Joho; MJ025137 -8D11 E0101; Hanyo-Denshi; KS419240 -8D11 E0101; Moji_Joho; MJ025138 -8D12 E0100; Adobe-Japan1; CID+8628 -8D13 E0100; Adobe-Japan1; CID+6780 -8D13 E0101; Moji_Joho; MJ025140 -8D13 E0102; Moji_Joho; MJ025141 -8D14 E0100; Adobe-Japan1; CID+6782 -8D16 E0100; Adobe-Japan1; CID+6783 -8D17 E0100; Adobe-Japan1; CID+19836 -8D1B E0100; Adobe-Japan1; CID+15158 -8D1B E0101; Hanyo-Denshi; JB6337 -8D1B E0101; Moji_Joho; MJ025149 -8D1B E0102; Hanyo-Denshi; JTBBDF -8D1B E0102; Moji_Joho; MJ025150 -8D1B E0103; Hanyo-Denshi; TK01087340 -8D1C E0100; Adobe-Japan1; CID+19837 -8D1C E0101; Hanyo-Denshi; IP8D1C -8D1C E0101; Moji_Joho; MJ025152 -8D1C E0102; Hanyo-Denshi; JTBBE0 -8D1C E0102; Moji_Joho; MJ025153 -8D1C E0103; Hanyo-Denshi; KS419540 -8D1C E0103; Moji_Joho; MJ025154 -8D64 E0100; Adobe-Japan1; CID+2682 -8D65 E0100; Adobe-Japan1; CID+22594 -8D66 E0100; Adobe-Japan1; CID+2299 -8D67 E0100; Adobe-Japan1; CID+6784 -8D67 E0101; Adobe-Japan1; CID+20224 -8D69 E0100; Adobe-Japan1; CID+15159 -8D6B E0100; Adobe-Japan1; CID+1456 -8D6B E0101; Hanyo-Denshi; JA1950 -8D6B E0102; Hanyo-Denshi; TK01087360 -8D6C E0100; Adobe-Japan1; CID+15160 -8D6D E0100; Adobe-Japan1; CID+6785 -8D6D E0101; Hanyo-Denshi; JA7664 -8D6D E0101; Moji_Joho; MJ025165 -8D6D E0102; Hanyo-Denshi; FT2564 -8D6D E0102; Moji_Joho; MJ025166 -8D6E E0100; Adobe-Japan1; CID+19838 -8D70 E0100; Adobe-Japan1; CID+2808 -8D70 E0101; Adobe-Japan1; CID+13894 -8D71 E0100; Adobe-Japan1; CID+6786 -8D73 E0100; Adobe-Japan1; CID+6787 -8D73 E0101; Adobe-Japan1; CID+14222 -8D73 E0102; Hanyo-Denshi; JA7666 -8D73 E0102; Moji_Joho; MJ025174 -8D73 E0103; Hanyo-Denshi; KS420070 -8D73 E0103; Moji_Joho; MJ025172 -8D73 E0104; Moji_Joho; MJ025173 -8D74 E0100; Adobe-Japan1; CID+3549 -8D76 E0100; Adobe-Japan1; CID+8629 -8D77 E0100; Adobe-Japan1; CID+1609 -8D77 E0101; Adobe-Japan1; CID+13704 -8D77 E0102; Hanyo-Denshi; JA2115 -8D77 E0102; Moji_Joho; MJ025178 -8D77 E0103; Hanyo-Denshi; JTBBE3S -8D77 E0103; Moji_Joho; MJ025179 -8D7F E0100; Adobe-Japan1; CID+22595 -8D81 E0100; Adobe-Japan1; CID+6788 -8D82 E0100; Adobe-Japan1; CID+22596 -8D82 E0101; Hanyo-Denshi; JB6343 -8D82 E0101; Moji_Joho; MJ025190 -8D82 E0102; Hanyo-Denshi; KS420850 -8D82 E0102; Moji_Joho; MJ025191 -8D84 E0100; Adobe-Japan1; CID+15161 -8D85 E0100; Adobe-Japan1; CID+3026 -8D88 E0100; Adobe-Japan1; CID+22597 -8D8A E0100; Adobe-Japan1; CID+1277 -8D8D E0100; Adobe-Japan1; CID+15162 -8D90 E0100; Adobe-Japan1; CID+22598 -8D91 E0100; Adobe-Japan1; CID+19839 -8D95 E0100; Adobe-Japan1; CID+15163 -8D99 E0100; Adobe-Japan1; CID+6789 -8D99 E0101; Adobe-Japan1; CID+14223 -8D99 E0102; Hanyo-Denshi; JA7668 -8D99 E0102; Moji_Joho; MJ025213 -8D99 E0103; Hanyo-Denshi; FT2565S -8D99 E0103; Moji_Joho; MJ025214 -8D9E E0100; Adobe-Japan1; CID+22599 -8D9F E0100; Adobe-Japan1; CID+19840 -8DA0 E0100; Adobe-Japan1; CID+22600 -8DA3 E0100; Adobe-Japan1; CID+2333 -8DA6 E0100; Adobe-Japan1; CID+15164 -8DA8 E0100; Adobe-Japan1; CID+2620 -8DA9 E0100; Hanyo-Denshi; KS422630 -8DA9 E0100; Moji_Joho; MJ025230 -8DA9 E0101; Hanyo-Denshi; KS422650 -8DA9 E0101; Moji_Joho; MJ025231 -8DAB E0100; Adobe-Japan1; CID+19841 -8DAC E0100; Adobe-Japan1; CID+22601 -8DAF E0100; Adobe-Japan1; CID+17134 -8DAF E0101; Hanyo-Denshi; JB6356 -8DAF E0101; Moji_Joho; MJ025237 -8DAF E0102; Hanyo-Denshi; JTBBE9 -8DAF E0102; Moji_Joho; MJ025238 -8DB2 E0100; Adobe-Japan1; CID+19842 -8DB3 E0100; Adobe-Japan1; CID+2829 -8DB5 E0100; Adobe-Japan1; CID+22602 -8DB7 E0100; Adobe-Japan1; CID+22603 -8DB9 E0100; Adobe-Japan1; CID+22604 -8DB9 E0101; Moji_Joho; MJ025245 -8DB9 E0102; Moji_Joho; MJ025246 -8DBA E0100; Adobe-Japan1; CID+6792 -8DBB E0100; Adobe-Japan1; CID+22605 -8DBC E0100; Adobe-Japan1; CID+22613 -8DBC E0101; Hanyo-Denshi; JB6379 -8DBC E0101; Moji_Joho; MJ025250 -8DBC E0102; Hanyo-Denshi; KS423700 -8DBC E0102; Moji_Joho; MJ025249 -8DBE E0100; Adobe-Japan1; CID+6791 -8DC0 E0100; Adobe-Japan1; CID+22606 -8DC2 E0100; Adobe-Japan1; CID+6790 -8DC5 E0100; Adobe-Japan1; CID+22607 -8DC6 E0100; Adobe-Japan1; CID+15165 -8DC7 E0100; Adobe-Japan1; CID+22608 -8DC7 E0101; Moji_Joho; MJ025260 -8DC7 E0102; Moji_Joho; MJ025261 -8DC8 E0100; Adobe-Japan1; CID+18721 -8DCA E0100; Adobe-Japan1; CID+22609 -8DCB E0100; Adobe-Japan1; CID+6798 -8DCB E0101; Hanyo-Denshi; JA7677 -8DCB E0101; Moji_Joho; MJ025265 -8DCB E0102; Hanyo-Denshi; JTBBEA -8DCB E0102; Moji_Joho; MJ025266 -8DCC E0100; Adobe-Japan1; CID+6796 -8DCE E0100; Adobe-Japan1; CID+15166 -8DCF E0100; Adobe-Japan1; CID+6793 -8DD1 E0100; Adobe-Japan1; CID+17135 -8DD1 E0101; Hanyo-Denshi; JB6369 -8DD1 E0102; Hanyo-Denshi; TK01087660 -8DD4 E0100; Adobe-Japan1; CID+22610 -8DD5 E0100; Adobe-Japan1; CID+19843 -8DD6 E0100; Adobe-Japan1; CID+6795 -8DD7 E0100; Adobe-Japan1; CID+17136 -8DD9 E0100; Adobe-Japan1; CID+18722 -8DDA E0100; Adobe-Japan1; CID+6794 -8DDA E0101; Adobe-Japan1; CID+7868 -8DDA E0102; Hanyo-Denshi; JA7673 -8DDA E0102; Moji_Joho; MJ025283 -8DDA E0103; Hanyo-Denshi; FT1991 -8DDA E0103; Moji_Joho; MJ025282 -8DDA E0104; Hanyo-Denshi; JTBBEB -8DDA E0104; Moji_Joho; MJ025284 -8DDA E0105; Moji_Joho; MJ025285 -8DDB E0100; Adobe-Japan1; CID+6797 -8DDD E0100; Adobe-Japan1; CID+1681 -8DDD E0101; Adobe-Japan1; CID+13716 -8DDD E0102; Hanyo-Denshi; JA2187 -8DDD E0102; Moji_Joho; MJ025289 -8DDD E0103; Hanyo-Denshi; KS424550 -8DDD E0103; Moji_Joho; MJ025288 -8DDF E0100; Adobe-Japan1; CID+6801 -8DE1 E0100; Adobe-Japan1; CID+2683 -8DE3 E0100; Adobe-Japan1; CID+6802 -8DE4 E0100; Adobe-Japan1; CID+15167 -8DE4 E0101; Moji_Joho; MJ025295 -8DE4 E0102; Moji_Joho; MJ025296 -8DE5 E0100; Adobe-Japan1; CID+22611 -8DE7 E0100; Adobe-Japan1; CID+19844 -8DE8 E0100; Adobe-Japan1; CID+1933 -8DE8 E0101; Hanyo-Denshi; JA2457 -8DE8 E0101; Moji_Joho; MJ025300 -8DE8 E0102; Hanyo-Denshi; KS425330 -8DE8 E0102; Moji_Joho; MJ025301 -8DEA E0100; Adobe-Japan1; CID+6799 -8DEB E0100; Adobe-Japan1; CID+6800 -8DEB E0101; Hanyo-Denshi; JA7679 -8DEB E0101; Moji_Joho; MJ025304 -8DEB E0102; Hanyo-Denshi; JTBBEF -8DEB E0102; Moji_Joho; MJ025305 -8DEC E0100; Adobe-Japan1; CID+15168 -8DEF E0100; Adobe-Japan1; CID+4047 -8DF0 E0100; Adobe-Japan1; CID+22612 -8DF0 E0101; Hanyo-Denshi; JB6378 -8DF0 E0101; Moji_Joho; MJ025310 -8DF0 E0102; Hanyo-Denshi; KS426260 -8DF0 E0102; Moji_Joho; MJ025311 -8DF1 E0100; Adobe-Japan1; CID+19845 -8DF2 E0100; Adobe-Japan1; CID+19846 -8DF3 E0100; Adobe-Japan1; CID+3027 -8DF3 E0101; Adobe-Japan1; CID+13480 -8DF3 E0102; Moji_Joho; MJ025314 -8DF3 E0103; Moji_Joho; MJ025315 -8DF4 E0100; Adobe-Japan1; CID+19847 -8DF5 E0100; Adobe-Japan1; CID+2731 -8DFC E0100; Adobe-Japan1; CID+6803 -8DFD E0100; Adobe-Japan1; CID+18725 -8DFF E0100; Adobe-Japan1; CID+6806 -8E01 E0100; Adobe-Japan1; CID+19848 -8E04 E0100; Adobe-Japan1; CID+22614 -8E05 E0100; Adobe-Japan1; CID+22615 -8E06 E0100; Adobe-Japan1; CID+18726 -8E08 E0100; Adobe-Japan1; CID+6804 -8E09 E0100; Adobe-Japan1; CID+6805 -8E09 E0101; Adobe-Japan1; CID+7869 -8E09 E0102; Hanyo-Denshi; JA7684 -8E09 E0102; Moji_Joho; MJ025331 -8E09 E0103; Hanyo-Denshi; FT1992 -8E09 E0103; Moji_Joho; MJ025332 -8E0A E0100; Adobe-Japan1; CID+3907 -8E0B E0100; Adobe-Japan1; CID+19849 -8E0C E0100; Adobe-Japan1; CID+18723 -8E0F E0100; Adobe-Japan1; CID+3199 -8E10 E0100; Adobe-Japan1; CID+6809 -8E11 E0100; Adobe-Japan1; CID+22616 -8E14 E0100; Adobe-Japan1; CID+18728 -8E16 E0100; Adobe-Japan1; CID+18729 -8E1D E0100; Adobe-Japan1; CID+6807 -8E1E E0100; Adobe-Japan1; CID+6808 -8E1F E0100; Adobe-Japan1; CID+6810 -8E20 E0100; Adobe-Japan1; CID+15169 -8E21 E0100; Adobe-Japan1; CID+18730 -8E22 E0100; Adobe-Japan1; CID+18731 -8E23 E0100; Adobe-Japan1; CID+17137 -8E26 E0100; Adobe-Japan1; CID+19850 -8E27 E0100; Adobe-Japan1; CID+18732 -8E2A E0100; Adobe-Japan1; CID+6824 -8E30 E0100; Adobe-Japan1; CID+6813 -8E30 E0101; Hanyo-Denshi; JA7692 -8E30 E0101; Moji_Joho; MJ025364 -8E30 E0102; Hanyo-Denshi; FT2566 -8E30 E0102; Moji_Joho; MJ025365 -8E31 E0100; Adobe-Japan1; CID+19851 -8E33 E0100; Adobe-Japan1; CID+22617 -8E34 E0100; Adobe-Japan1; CID+6814 -8E34 E0101; Adobe-Japan1; CID+14225 -8E35 E0100; Adobe-Japan1; CID+6812 -8E36 E0100; Adobe-Japan1; CID+18735 -8E37 E0100; Adobe-Japan1; CID+22618 -8E38 E0100; Adobe-Japan1; CID+22619 -8E38 E0101; Moji_Joho; MJ025373 -8E38 E0102; Moji_Joho; MJ025374 -8E39 E0100; Adobe-Japan1; CID+18736 -8E3D E0100; Adobe-Japan1; CID+17138 -8E40 E0100; Adobe-Japan1; CID+19852 -8E41 E0100; Adobe-Japan1; CID+19853 -8E42 E0100; Adobe-Japan1; CID+6811 -8E43 E0100; Hanyo-Denshi; IP8E43 -8E43 E0100; Moji_Joho; MJ025385 -8E43 E0101; Hanyo-Denshi; KS427120 -8E43 E0101; Moji_Joho; MJ025386 -8E44 E0100; Adobe-Japan1; CID+3097 -8E44 E0101; Hanyo-Denshi; JA3693 -8E44 E0101; Moji_Joho; MJ025387 -8E44 E0102; Hanyo-Denshi; KS427260 -8E44 E0102; Moji_Joho; MJ025388 -8E46 E0100; Hanyo-Denshi; IB0908 -8E46 E0100; Moji_Joho; MJ025390 -8E46 E0101; Hanyo-Denshi; IP8E46 -8E46 E0101; Moji_Joho; MJ025391 -8E47 E0100; Adobe-Japan1; CID+6816 -8E48 E0100; Adobe-Japan1; CID+6820 -8E48 E0101; Hanyo-Denshi; JA7705 -8E48 E0101; Moji_Joho; MJ025393 -8E48 E0102; Hanyo-Denshi; FT2568 -8E48 E0102; Moji_Joho; MJ025394 -8E49 E0100; Adobe-Japan1; CID+6817 -8E4A E0100; Adobe-Japan1; CID+6815 -8E4A E0101; Adobe-Japan1; CID+14226 -8E4A E0102; Hanyo-Denshi; JA7694 -8E4A E0102; Moji_Joho; MJ025396 -8E4A E0103; Hanyo-Denshi; FT2567 -8E4A E0103; Moji_Joho; MJ025397 -8E4B E0100; Adobe-Japan1; CID+15170 -8E4B E0101; Hanyo-Denshi; JB6413 -8E4B E0101; Moji_Joho; MJ025398 -8E4B E0102; Hanyo-Denshi; KS427760 -8E4B E0102; Moji_Joho; MJ025399 -8E4C E0100; Adobe-Japan1; CID+6818 -8E4D E0100; Adobe-Japan1; CID+19854 -8E4E E0100; Adobe-Japan1; CID+22620 -8E4F E0100; Adobe-Japan1; CID+19855 -8E50 E0100; Adobe-Japan1; CID+6819 -8E54 E0100; Adobe-Japan1; CID+18737 -8E55 E0100; Adobe-Japan1; CID+6826 -8E55 E0101; Hanyo-Denshi; JA7711 -8E55 E0101; Moji_Joho; MJ025407 -8E55 E0102; Hanyo-Denshi; JTBBFDS -8E55 E0102; Moji_Joho; MJ025408 -8E59 E0100; Adobe-Japan1; CID+6821 -8E5B E0100; Adobe-Japan1; CID+22621 -8E5C E0100; Adobe-Japan1; CID+19856 -8E5D E0100; Adobe-Japan1; CID+22622 -8E5E E0100; Adobe-Japan1; CID+22623 -8E5E E0101; Hanyo-Denshi; JB6421 -8E5E E0101; Moji_Joho; MJ025417 -8E5E E0102; Hanyo-Denshi; KS428430 -8E5E E0102; Moji_Joho; MJ025418 -8E5F E0100; Adobe-Japan1; CID+2684 -8E60 E0100; Adobe-Japan1; CID+6823 -8E61 E0100; Adobe-Japan1; CID+19857 -8E62 E0100; Adobe-Japan1; CID+18738 -8E62 E0101; Hanyo-Denshi; JB6423 -8E62 E0101; Moji_Joho; MJ025422 -8E62 E0102; Hanyo-Denshi; KS428410 -8E62 E0102; Moji_Joho; MJ025423 -8E63 E0100; Adobe-Japan1; CID+6825 -8E64 E0100; Adobe-Japan1; CID+6822 -8E69 E0100; Adobe-Japan1; CID+19858 -8E6C E0100; Adobe-Japan1; CID+15171 -8E6D E0100; Adobe-Japan1; CID+18739 -8E6E E0100; Hanyo-Denshi; IP8E6E -8E6E E0100; Moji_Joho; MJ025436 -8E6E E0101; Hanyo-Denshi; KS428400 -8E6E E0101; Moji_Joho; MJ058816 -8E6E E0102; Hanyo-Denshi; KS428420 -8E6E E0102; Moji_Joho; MJ025435 -8E6F E0100; Adobe-Japan1; CID+18740 -8E70 E0100; Adobe-Japan1; CID+15172 -8E71 E0100; Adobe-Japan1; CID+19859 -8E71 E0101; Hanyo-Denshi; JB6429 -8E71 E0101; Moji_Joho; MJ025439 -8E71 E0102; Hanyo-Denshi; KS429120 -8E71 E0102; Moji_Joho; MJ025440 -8E72 E0100; Adobe-Japan1; CID+6828 -8E72 E0101; Hanyo-Denshi; JA7713 -8E72 E0101; Moji_Joho; MJ025441 -8E72 E0102; Hanyo-Denshi; FT2570 -8E72 E0102; Moji_Joho; MJ025442 -8E72 E0103; Hanyo-Denshi; JTBC02 -8E72 E0103; Moji_Joho; MJ025443 -8E74 E0100; Adobe-Japan1; CID+2365 -8E75 E0100; Adobe-Japan1; CID+19860 -8E76 E0100; Adobe-Japan1; CID+6827 -8E77 E0100; Adobe-Japan1; CID+19861 -8E77 E0101; Moji_Joho; MJ025448 -8E77 E0102; Moji_Joho; MJ025449 -8E79 E0100; Adobe-Japan1; CID+22624 -8E7A E0100; Adobe-Japan1; CID+15173 -8E7B E0100; Adobe-Japan1; CID+17139 -8E7C E0100; Adobe-Japan1; CID+6829 -8E81 E0100; Adobe-Japan1; CID+6830 -8E82 E0100; Adobe-Japan1; CID+22625 -8E83 E0100; Adobe-Japan1; CID+22626 -8E84 E0100; Adobe-Japan1; CID+6833 -8E85 E0100; Adobe-Japan1; CID+6832 -8E87 E0100; Adobe-Japan1; CID+6831 -8E87 E0101; Hanyo-Denshi; JA7716 -8E87 E0101; Moji_Joho; MJ025461 -8E87 E0102; Hanyo-Denshi; KS429320 -8E87 E0102; Moji_Joho; MJ025462 -8E87 E0103; Hanyo-Denshi; FT2571 -8E87 E0103; Moji_Joho; MJ025463 -8E89 E0100; Adobe-Japan1; CID+19862 -8E89 E0101; Hanyo-Denshi; JB6435 -8E89 E0101; Moji_Joho; MJ025465 -8E89 E0102; Hanyo-Denshi; KS429380 -8E89 E0102; Moji_Joho; MJ025466 -8E8A E0100; Adobe-Japan1; CID+6835 -8E8B E0100; Adobe-Japan1; CID+6834 -8E8D E0100; Adobe-Japan1; CID+3842 -8E8D E0101; Adobe-Japan1; CID+14063 -8E8D E0102; Hanyo-Denshi; JA4486 -8E8D E0102; Moji_Joho; MJ025471 -8E8D E0103; Hanyo-Denshi; JTBC03 -8E8D E0103; Moji_Joho; MJ025470 -8E90 E0100; Adobe-Japan1; CID+19863 -8E91 E0100; Adobe-Japan1; CID+6837 -8E91 E0101; Adobe-Japan1; CID+13605 -8E91 E0102; Hanyo-Denshi; JA7722 -8E91 E0102; Moji_Joho; MJ025474 -8E91 E0103; Hanyo-Denshi; FT2572 -8E91 E0103; Moji_Joho; MJ025475 -8E91 E0104; Hanyo-Denshi; FT1737 -8E91 E0104; Moji_Joho; MJ025476 -8E91 E0105; Moji_Joho; MJ025477 -8E92 E0100; Adobe-Japan1; CID+15174 -8E93 E0100; Adobe-Japan1; CID+6836 -8E94 E0100; Adobe-Japan1; CID+6838 -8E95 E0100; Adobe-Japan1; CID+19864 -8E98 E0100; Adobe-Japan1; CID+18741 -8E99 E0100; Adobe-Japan1; CID+6839 -8E9A E0100; Adobe-Japan1; CID+19865 -8E9A E0101; Hanyo-Denshi; JB6439 -8E9A E0101; Moji_Joho; MJ025485 -8E9A E0102; Hanyo-Denshi; KS429920 -8E9A E0102; Moji_Joho; MJ058819 -8E9A E0103; Hanyo-Denshi; KS429970 -8E9A E0103; Moji_Joho; MJ025486 -8E9B E0100; Adobe-Japan1; CID+22627 -8E9D E0100; Adobe-Japan1; CID+22628 -8E9E E0100; Adobe-Japan1; CID+18742 -8EA1 E0100; Adobe-Japan1; CID+6841 -8EA1 E0101; Adobe-Japan1; CID+13606 -8EA1 E0102; Moji_Joho; MJ025492 -8EA1 E0103; Moji_Joho; MJ025493 -8EA1 E0104; Moji_Joho; MJ025494 -8EA2 E0100; Adobe-Japan1; CID+22629 -8EA7 E0100; Adobe-Japan1; CID+19866 -8EA9 E0100; Adobe-Japan1; CID+19867 -8EAA E0100; Adobe-Japan1; CID+6840 -8EAA E0101; Hanyo-Denshi; JA7725 -8EAA E0101; Moji_Joho; MJ025503 -8EAA E0102; Hanyo-Denshi; KS430420 -8EAA E0102; Moji_Joho; MJ025504 -8EAB E0100; Adobe-Japan1; CID+2574 -8EAB E0101; Hanyo-Denshi; JA3140 -8EAB E0102; Hanyo-Denshi; TK01087860 -8EAC E0100; Adobe-Japan1; CID+6842 -8EAC E0101; Moji_Joho; MJ025506 -8EAC E0102; Moji_Joho; MJ025507 -8EAD E0100; Adobe-Japan1; CID+19868 -8EAE E0100; Adobe-Japan1; CID+15175 -8EAF E0100; Adobe-Japan1; CID+1765 -8EAF E0101; Moji_Joho; MJ025510 -8EAF E0102; Moji_Joho; MJ025511 -8EB0 E0100; Adobe-Japan1; CID+6843 -8EB0 E0101; Moji_Joho; MJ025512 -8EB0 E0102; Moji_Joho; MJ025513 -8EB1 E0100; Adobe-Japan1; CID+6845 -8EB3 E0100; Adobe-Japan1; CID+15176 -8EB5 E0100; Adobe-Japan1; CID+18743 -8EB5 E0101; Hanyo-Denshi; JB6449 -8EB5 E0102; Hanyo-Denshi; TK01087950 -8EB6 E0100; Adobe-Japan1; CID+14083 -8EBA E0100; Adobe-Japan1; CID+22630 -8EBB E0100; Adobe-Japan1; CID+18744 -8EBD E0100; Moji_Joho; MJ025526 -8EBD E0101; Moji_Joho; MJ025527 -8EBE E0100; Adobe-Japan1; CID+6846 -8EBE E0101; Moji_Joho; MJ025528 -8EBE E0102; Moji_Joho; MJ025529 -8EC0 E0100; Adobe-Japan1; CID+7663 -8EC0 E0101; Hanyo-Denshi; JB6452 -8EC0 E0101; Moji_Joho; MJ025531 -8EC0 E0102; Hanyo-Denshi; KS431630 -8EC0 E0102; Moji_Joho; MJ025532 -8EC1 E0100; Adobe-Japan1; CID+22631 -8EC3 E0100; Adobe-Japan1; CID+22632 -8EC4 E0100; Adobe-Japan1; CID+22633 -8EC4 E0101; Hanyo-Denshi; JB6455 -8EC4 E0101; Moji_Joho; MJ025536 -8EC4 E0102; Hanyo-Denshi; KS431760 -8EC4 E0102; Moji_Joho; MJ025537 -8EC5 E0100; Adobe-Japan1; CID+6847 -8EC5 E0101; Moji_Joho; MJ025538 -8EC5 E0102; Moji_Joho; MJ025539 -8EC6 E0100; Adobe-Japan1; CID+6844 -8EC6 E0101; Moji_Joho; MJ025540 -8EC6 E0102; Moji_Joho; MJ025541 -8EC7 E0100; Adobe-Japan1; CID+22634 -8EC8 E0100; Adobe-Japan1; CID+6848 -8EC8 E0101; Moji_Joho; MJ025543 -8EC8 E0102; Moji_Joho; MJ025544 -8ECA E0100; Adobe-Japan1; CID+2306 -8ECB E0100; Adobe-Japan1; CID+6849 -8ECC E0100; Adobe-Japan1; CID+1610 -8ECC E0101; Adobe-Japan1; CID+13430 -8ECD E0100; Adobe-Japan1; CID+1801 -8ECF E0100; Adobe-Japan1; CID+8631 -8ED1 E0100; Adobe-Japan1; CID+15177 -8ED2 E0100; Adobe-Japan1; CID+1890 -8ED4 E0100; Adobe-Japan1; CID+20066 -8ED4 E0101; Adobe-Japan1; CID+15178 -8ED4 E0102; Hanyo-Denshi; JB6459 -8ED4 E0102; Moji_Joho; MJ025557 -8ED4 E0103; Hanyo-Denshi; KS432190 -8ED4 E0103; Moji_Joho; MJ025558 -8EDB E0100; Adobe-Japan1; CID+6850 -8EDC E0100; Adobe-Japan1; CID+22635 -8EDC E0101; Hanyo-Denshi; JB6460 -8EDC E0102; Hanyo-Denshi; TK01088110 -8EDF E0100; Adobe-Japan1; CID+3272 -8EE2 E0100; Adobe-Japan1; CID+3128 -8EE3 E0100; Adobe-Japan1; CID+6851 -8EE8 E0100; Adobe-Japan1; CID+19869 -8EEB E0100; Adobe-Japan1; CID+6854 -8EED E0100; Adobe-Japan1; CID+22639 -8EEE E0100; Adobe-Japan1; CID+22636 -8EF0 E0100; Adobe-Japan1; CID+19870 -8EF1 E0100; Adobe-Japan1; CID+22637 -8EF1 E0101; Hanyo-Denshi; JB6464 -8EF1 E0101; Moji_Joho; MJ025587 -8EF1 E0102; Hanyo-Denshi; KS433130 -8EF1 E0102; Moji_Joho; MJ025586 -8EF7 E0100; Adobe-Japan1; CID+22638 -8EF8 E0100; Adobe-Japan1; CID+2272 -8EF9 E0100; Adobe-Japan1; CID+15179 -8EFA E0100; Adobe-Japan1; CID+17142 -8EFB E0100; Adobe-Japan1; CID+6853 -8EFC E0100; Adobe-Japan1; CID+6852 -8EFD E0100; Adobe-Japan1; CID+1840 -8EFE E0100; Adobe-Japan1; CID+6855 -8F00 E0100; Adobe-Japan1; CID+18748 -8F02 E0100; Adobe-Japan1; CID+22640 -8F03 E0100; Adobe-Japan1; CID+1457 -8F03 E0101; Adobe-Japan1; CID+20226 -8F03 E0102; Moji_Joho; MJ025605 -8F03 E0103; Moji_Joho; MJ025606 -8F05 E0100; Adobe-Japan1; CID+6857 -8F07 E0100; Adobe-Japan1; CID+19871 -8F08 E0100; Adobe-Japan1; CID+18749 -8F09 E0100; Adobe-Japan1; CID+2124 -8F0A E0100; Adobe-Japan1; CID+6856 -8F0C E0100; Adobe-Japan1; CID+6865 -8F0E E0100; Hanyo-Denshi; IP8F0E -8F0E E0101; Hanyo-Denshi; TK01088190 -8F0F E0100; Adobe-Japan1; CID+22641 -8F10 E0100; Adobe-Japan1; CID+22642 -8F12 E0100; Adobe-Japan1; CID+6859 -8F13 E0100; Adobe-Japan1; CID+6861 -8F13 E0101; Adobe-Japan1; CID+7870 -8F13 E0102; Hanyo-Denshi; JA7746 -8F13 E0102; Moji_Joho; MJ025623 -8F13 E0103; Hanyo-Denshi; FT1993S -8F13 E0103; Moji_Joho; MJ025624 -8F14 E0100; Adobe-Japan1; CID+3637 -8F15 E0100; Adobe-Japan1; CID+6858 -8F16 E0100; Adobe-Japan1; CID+22643 -8F16 E0101; Hanyo-Denshi; JB6475 -8F16 E0102; Hanyo-Denshi; TK01088270 -8F17 E0100; Adobe-Japan1; CID+15180 -8F18 E0100; Adobe-Japan1; CID+19872 -8F19 E0100; Adobe-Japan1; CID+6860 -8F1B E0100; Adobe-Japan1; CID+6864 -8F1C E0100; Adobe-Japan1; CID+6862 -8F1D E0100; Adobe-Japan1; CID+1611 -8F1D E0101; Hanyo-Denshi; JA2117 -8F1D E0101; Moji_Joho; MJ025635 -8F1D E0102; Hanyo-Denshi; JTBC1D -8F1D E0102; Moji_Joho; MJ025636 -8F1D E0103; Hanyo-Denshi; TK01088350 -8F1E E0100; Adobe-Japan1; CID+17143 -8F1E E0101; Hanyo-Denshi; JB6478 -8F1E E0101; Moji_Joho; MJ025637 -8F1E E0102; Hanyo-Denshi; IB2993 -8F1E E0102; Moji_Joho; MJ025638 -8F1F E0100; Adobe-Japan1; CID+6863 -8F20 E0100; Adobe-Japan1; CID+22644 -8F21 E0100; Adobe-Japan1; CID+22645 -8F23 E0100; Adobe-Japan1; CID+22646 -8F24 E0100; Hanyo-Denshi; IB0909 -8F24 E0100; Moji_Joho; MJ025645 -8F24 E0101; Hanyo-Denshi; IP8F24 -8F24 E0101; Moji_Joho; MJ025644 -8F25 E0100; Adobe-Japan1; CID+19873 -8F26 E0100; Adobe-Japan1; CID+6866 -8F27 E0100; Adobe-Japan1; CID+19874 -8F28 E0100; Adobe-Japan1; CID+22647 -8F29 E0100; Adobe-Japan1; CID+3344 -8F29 E0101; Adobe-Japan1; CID+13488 -8F29 E0102; Moji_Joho; MJ025650 -8F29 E0103; Moji_Joho; MJ025651 -8F2A E0100; Adobe-Japan1; CID+4000 -8F2A E0101; Hanyo-Denshi; JA4656 -8F2A E0102; Hanyo-Denshi; TK01088210 -8F2B E0100; Adobe-Japan1; CID+18750 -8F2C E0100; Adobe-Japan1; CID+19875 -8F2D E0100; Adobe-Japan1; CID+17144 -8F2E E0100; Adobe-Japan1; CID+22648 -8F2F E0100; Adobe-Japan1; CID+2366 -8F2F E0101; Adobe-Japan1; CID+13456 -8F33 E0100; Adobe-Japan1; CID+6867 -8F34 E0100; Adobe-Japan1; CID+22649 -8F35 E0100; Adobe-Japan1; CID+19876 -8F35 E0101; Hanyo-Denshi; JB6489 -8F35 E0102; Hanyo-Denshi; TK01088280 -8F36 E0100; Adobe-Japan1; CID+15181 -8F37 E0100; Adobe-Japan1; CID+22650 -8F38 E0100; Adobe-Japan1; CID+3852 -8F38 E0101; Adobe-Japan1; CID+14069 -8F38 E0102; Hanyo-Denshi; JA4502 -8F38 E0102; Moji_Joho; MJ025669 -8F38 E0103; Hanyo-Denshi; JTBC1F -8F38 E0103; Moji_Joho; MJ025668 -8F38 E0104; Hanyo-Denshi; TK01088290 -8F39 E0100; Adobe-Japan1; CID+6869 -8F3A E0100; Adobe-Japan1; CID+19877 -8F3B E0100; Adobe-Japan1; CID+6868 -8F3E E0100; Adobe-Japan1; CID+6872 -8F3F E0100; Adobe-Japan1; CID+3883 -8F40 E0100; Adobe-Japan1; CID+18751 -8F41 E0100; Adobe-Japan1; CID+22651 -8F42 E0100; Adobe-Japan1; CID+6871 -8F43 E0100; Adobe-Japan1; CID+19878 -8F44 E0100; Adobe-Japan1; CID+1483 -8F44 E0101; Adobe-Japan1; CID+13685 -8F44 E0102; Adobe-Japan1; CID+20227 -8F44 E0103; Hanyo-Denshi; JA1977 -8F44 E0103; Moji_Joho; MJ025683 -8F44 E0104; Hanyo-Denshi; KS435180 -8F44 E0104; Moji_Joho; MJ025682 -8F44 E0105; Hanyo-Denshi; JTBC22 -8F44 E0105; Moji_Joho; MJ025684 -8F45 E0100; Adobe-Japan1; CID+6870 -8F46 E0100; Adobe-Japan1; CID+6875 -8F47 E0100; Adobe-Japan1; CID+19879 -8F49 E0100; Adobe-Japan1; CID+6874 -8F49 E0101; Hanyo-Denshi; JA7759 -8F49 E0102; Hanyo-Denshi; TK01088340 -8F49 E0103; Hanyo-Denshi; TK01088360 -8F49 E0104; Hanyo-Denshi; TK01088370 -8F4A E0100; Adobe-Japan1; CID+18752 -8F4C E0100; Adobe-Japan1; CID+6873 -8F4C E0101; Hanyo-Denshi; JA7758 -8F4C E0101; Moji_Joho; MJ025692 -8F4C E0102; Hanyo-Denshi; FT2580 -8F4C E0102; Moji_Joho; MJ025693 -8F4D E0100; Adobe-Japan1; CID+3116 -8F4E E0100; Adobe-Japan1; CID+6876 -8F4F E0100; Adobe-Japan1; CID+22652 -8F51 E0100; Adobe-Japan1; CID+19880 -8F52 E0100; Adobe-Japan1; CID+22653 -8F52 E0101; Hanyo-Denshi; JB6505 -8F52 E0101; Moji_Joho; MJ025699 -8F52 E0102; Hanyo-Denshi; KS436110 -8F52 E0102; Moji_Joho; MJ025700 -8F53 E0100; Adobe-Japan1; CID+22654 -8F54 E0100; Adobe-Japan1; CID+17145 -8F54 E0101; Hanyo-Denshi; JB6507 -8F54 E0101; Moji_Joho; MJ025703 -8F54 E0102; Hanyo-Denshi; JTBC25S -8F54 E0102; Moji_Joho; MJ025702 -8F55 E0100; Adobe-Japan1; CID+19881 -8F55 E0101; Hanyo-Denshi; JB6508 -8F55 E0101; Moji_Joho; MJ025704 -8F55 E0102; Hanyo-Denshi; KS435920 -8F55 E0102; Moji_Joho; MJ025705 -8F57 E0100; Adobe-Japan1; CID+6877 -8F58 E0100; Adobe-Japan1; CID+18753 -8F5C E0100; Adobe-Japan1; CID+6878 -8F5D E0100; Adobe-Japan1; CID+22655 -8F5E E0100; Adobe-Japan1; CID+22656 -8F5F E0100; Adobe-Japan1; CID+2046 -8F61 E0100; Adobe-Japan1; CID+1787 -8F62 E0100; Adobe-Japan1; CID+6879 -8F63 E0100; Adobe-Japan1; CID+6880 -8F64 E0100; Adobe-Japan1; CID+6881 -8F65 E0100; Adobe-Japan1; CID+22657 -8F65 E0101; Hanyo-Denshi; JB6512 -8F65 E0101; Moji_Joho; MJ025722 -8F65 E0102; Hanyo-Denshi; KS436710 -8F65 E0102; Moji_Joho; MJ025723 -8F89 E0100; Hanyo-Denshi; TK01008430 -8F89 E0101; Hanyo-Denshi; TK01088160 -8F9B E0100; Adobe-Japan1; CID+2575 -8F9B E0101; Hanyo-Denshi; JA3141 -8F9B E0101; Moji_Joho; MJ025725 -8F9B E0102; Hanyo-Denshi; KS436800 -8F9B E0102; Moji_Joho; MJ025726 -8F9C E0100; Adobe-Japan1; CID+6882 -8F9D E0100; Adobe-Japan1; CID+22658 -8F9E E0100; Adobe-Japan1; CID+2265 -8F9F E0100; Adobe-Japan1; CID+6883 -8FA0 E0100; Adobe-Japan1; CID+19882 -8FA1 E0100; Adobe-Japan1; CID+19883 -8FA2 E0100; Adobe-Japan1; CID+19884 -8FA3 E0100; Adobe-Japan1; CID+6884 -8FA4 E0100; Adobe-Japan1; CID+18755 -8FA5 E0100; Adobe-Japan1; CID+19885 -8FA5 E0101; Hanyo-Denshi; JB6517 -8FA5 E0101; Moji_Joho; MJ025736 -8FA5 E0102; Hanyo-Denshi; KS437060 -8FA5 E0102; Moji_Joho; MJ058832 -8FA6 E0100; Adobe-Japan1; CID+15182 -8FA7 E0100; Adobe-Japan1; CID+4278 -8FA8 E0100; Adobe-Japan1; CID+4277 -8FA8 E0101; Hanyo-Denshi; JA4994 -8FA8 E0101; Moji_Joho; MJ025739 -8FA8 E0102; Hanyo-Denshi; JTAE2DS -8FA8 E0102; Moji_Joho; MJ059380 -8FA8 E0103; Hanyo-Denshi; JTAE2CS -8FA8 E0103; Moji_Joho; MJ058833 -8FAC E0100; Moji_Joho; MJ025740 -8FAC E0101; Moji_Joho; MJ025741 -8FAD E0100; Adobe-Japan1; CID+6885 -8FAD E0101; Hanyo-Denshi; JA7770 -8FAD E0101; Moji_Joho; MJ025742 -8FAD E0102; Hanyo-Denshi; FT2583 -8FAD E0102; Moji_Joho; MJ025743 -8FAE E0100; Adobe-Japan1; CID+6143 -8FAF E0100; Adobe-Japan1; CID+6886 -8FB0 E0100; Adobe-Japan1; CID+2914 -8FB1 E0100; Adobe-Japan1; CID+2545 -8FB1 E0101; Hanyo-Denshi; JA3111 -8FB1 E0101; Moji_Joho; MJ025747 -8FB1 E0102; Hanyo-Denshi; KS084610 -8FB1 E0102; Moji_Joho; MJ057352 -8FB1 E0103; Hanyo-Denshi; KS437430 -8FB1 E0103; Moji_Joho; MJ025748 -8FB2 E0100; Adobe-Japan1; CID+3318 -8FB4 E0100; Adobe-Japan1; CID+18756 -8FB4 E0101; Hanyo-Denshi; JD8972 -8FB4 E0102; Hanyo-Denshi; TK01088540 -8FB5 E0100; Adobe-Japan1; CID+15183 -8FB6 E0100; Adobe-Japan1; CID+15184 -8FB6 E0101; Adobe-Japan1; CID+15403 -8FB6 E0102; Hanyo-Denshi; JD8973 -8FB6 E0103; Hanyo-Denshi; JB6520 -8FB6 E0103; Moji_Joho; MJ025753 -8FB6 E0104; Hanyo-Denshi; KS437600 -8FB6 E0104; Moji_Joho; MJ058837 -8FB7 E0100; Adobe-Japan1; CID+6887 -8FB7 E0101; Hanyo-Denshi; JA7772 -8FB7 E0101; Moji_Joho; MJ025755 -8FB7 E0102; Hanyo-Denshi; FT2584 -8FB7 E0102; Moji_Joho; MJ025754 -8FB8 E0100; Adobe-Japan1; CID+22659 -8FBA E0100; Adobe-Japan1; CID+3621 -8FBA E0101; Hanyo-Denshi; JA4253 -8FBA E0101; Moji_Joho; MJ025758 -8FBA E0102; Hanyo-Denshi; KS437740 -8FBA E0102; Moji_Joho; MJ025759 -8FBB E0100; Adobe-Japan1; CID+3056 -8FBB E0101; Adobe-Japan1; CID+8267 -8FBB E0102; Hanyo-Denshi; JA3652 -8FBB E0102; Moji_Joho; MJ025760 -8FBB E0103; Hanyo-Denshi; FT1867 -8FBB E0103; Moji_Joho; MJ025761 -8FBB E0104; Hanyo-Denshi; TK01088560 -8FBB E0105; Hanyo-Denshi; TK01088690 -8FBC E0100; Adobe-Japan1; CID+2064 -8FBC E0101; Adobe-Japan1; CID+13779 -8FBC E0102; Hanyo-Denshi; JA2594 -8FBC E0102; Moji_Joho; MJ025762 -8FBC E0103; Hanyo-Denshi; JTBC2E -8FBC E0103; Moji_Joho; MJ025763 -8FBE E0100; Adobe-Japan1; CID+22660 -8FBE E0101; Hanyo-Denshi; JB6522 -8FBE E0101; Moji_Joho; MJ025766 -8FBE E0102; Hanyo-Denshi; IB0914 -8FBE E0102; Moji_Joho; MJ025765 -8FBF E0100; Adobe-Japan1; CID+2919 -8FBF E0101; Adobe-Japan1; CID+7735 -8FBF E0102; Hanyo-Denshi; JA3509 -8FBF E0102; Moji_Joho; MJ025767 -8FBF E0103; Hanyo-Denshi; FT1855 -8FBF E0103; Moji_Joho; MJ025768 -8FC0 E0100; Adobe-Japan1; CID+22661 -8FC1 E0100; Adobe-Japan1; CID+18758 -8FC1 E0101; Hanyo-Denshi; JB6524 -8FC1 E0102; Hanyo-Denshi; TK01088630 -8FC2 E0100; Adobe-Japan1; CID+1228 -8FC2 E0101; Adobe-Japan1; CID+7638 -8FC2 E0102; Hanyo-Denshi; JA1710 -8FC2 E0102; Moji_Joho; MJ025772 -8FC2 E0103; Hanyo-Denshi; FT1756 -8FC2 E0103; Moji_Joho; MJ025773 -8FC3 E0100; Hanyo-Denshi; IB0915 -8FC3 E0100; Moji_Joho; MJ025774 -8FC3 E0101; Hanyo-Denshi; IP8FC3 -8FC3 E0101; Moji_Joho; MJ025775 -8FC3 E0102; Hanyo-Denshi; KS438220 -8FC3 E0102; Moji_Joho; MJ025776 -8FC4 E0100; Adobe-Japan1; CID+3750 -8FC4 E0101; Adobe-Japan1; CID+7980 -8FC4 E0102; Hanyo-Denshi; JA4388 -8FC4 E0102; Moji_Joho; MJ025777 -8FC4 E0103; Hanyo-Denshi; FT1924 -8FC4 E0103; Moji_Joho; MJ025778 -8FC5 E0100; Adobe-Japan1; CID+2589 -8FC5 E0101; Adobe-Japan1; CID+13862 -8FC5 E0102; Adobe-Japan1; CID+20228 -8FC5 E0103; Hanyo-Denshi; JA3155 -8FC5 E0103; Moji_Joho; MJ025779 -8FC5 E0104; Hanyo-Denshi; JTBC39 -8FC5 E0104; Moji_Joho; MJ025780 -8FC6 E0100; Adobe-Japan1; CID+18759 -8FC6 E0101; Adobe-Japan1; CID+15185 -8FC6 E0102; Hanyo-Denshi; JB6525 -8FC6 E0102; Moji_Joho; MJ025782 -8FC6 E0103; Hanyo-Denshi; IB0916 -8FC6 E0103; Moji_Joho; MJ025781 -8FC7 E0100; Hanyo-Denshi; IP8FC7 -8FC7 E0101; Hanyo-Denshi; TK01088640 -8FC8 E0100; Adobe-Japan1; CID+14233 -8FCA E0100; Adobe-Japan1; CID+18761 -8FCA E0101; Hanyo-Denshi; JB6526 -8FCA E0101; Moji_Joho; MJ025787 -8FCA E0102; Hanyo-Denshi; IB0917 -8FCA E0102; Moji_Joho; MJ025786 -8FCB E0100; Adobe-Japan1; CID+22662 -8FCB E0101; Hanyo-Denshi; JB6527 -8FCB E0101; Moji_Joho; MJ025789 -8FCB E0102; Hanyo-Denshi; IB0919 -8FCB E0102; Moji_Joho; MJ025788 -8FCD E0100; Adobe-Japan1; CID+18762 -8FCD E0101; Hanyo-Denshi; JB6528 -8FCD E0101; Moji_Joho; MJ025792 -8FCD E0102; Hanyo-Denshi; IB0920 -8FCD E0102; Moji_Joho; MJ025791 -8FCE E0100; Adobe-Japan1; CID+1844 -8FCE E0101; Adobe-Japan1; CID+13742 -8FCE E0102; Hanyo-Denshi; JA2362 -8FCE E0102; Moji_Joho; MJ025793 -8FCE E0103; Hanyo-Denshi; JTBC4C -8FCE E0103; Moji_Joho; MJ025794 -8FD0 E0100; Adobe-Japan1; CID+22663 -8FD0 E0101; Hanyo-Denshi; JB6529 -8FD0 E0102; Hanyo-Denshi; TK01088740 -8FD1 E0100; Adobe-Japan1; CID+1753 -8FD1 E0101; Adobe-Japan1; CID+13730 -8FD1 E0102; Hanyo-Denshi; JA2265 -8FD1 E0102; Moji_Joho; MJ025798 -8FD1 E0103; Hanyo-Denshi; JTBC4B -8FD1 E0103; Moji_Joho; MJ025799 -8FD1 E0104; Hanyo-Denshi; TK01088870 -8FD2 E0100; Adobe-Japan1; CID+22664 -8FD2 E0101; Hanyo-Denshi; JB6530 -8FD2 E0101; Moji_Joho; MJ025801 -8FD2 E0102; Hanyo-Denshi; IB0921 -8FD2 E0102; Moji_Joho; MJ025800 -8FD3 E0100; Adobe-Japan1; CID+18763 -8FD3 E0101; Hanyo-Denshi; JB6531 -8FD3 E0101; Moji_Joho; MJ025804 -8FD3 E0102; Hanyo-Denshi; IB0386 -8FD3 E0102; Moji_Joho; MJ025803 -8FD3 E0103; Hanyo-Denshi; IB0922 -8FD3 E0103; Moji_Joho; MJ025802 -8FD4 E0100; Adobe-Japan1; CID+3622 -8FD4 E0101; Adobe-Japan1; CID+14016 -8FD4 E0102; Adobe-Japan1; CID+20229 -8FD4 E0103; Hanyo-Denshi; JA4254 -8FD4 E0103; Moji_Joho; MJ025805 -8FD4 E0104; Hanyo-Denshi; JTBC4D -8FD4 E0104; Moji_Joho; MJ025806 -8FD5 E0100; Adobe-Japan1; CID+18764 -8FD5 E0101; Hanyo-Denshi; JB6532 -8FD5 E0101; Moji_Joho; MJ025808 -8FD5 E0102; Hanyo-Denshi; IB0924 -8FD5 E0102; Moji_Joho; MJ025807 -8FDA E0100; Adobe-Japan1; CID+6888 -8FDA E0101; Hanyo-Denshi; JA7773 -8FDA E0101; Moji_Joho; MJ025813 -8FDA E0102; Hanyo-Denshi; FT2585 -8FDA E0102; Moji_Joho; MJ025812 -8FE0 E0100; Adobe-Japan1; CID+15186 -8FE0 E0101; Hanyo-Denshi; JB6533 -8FE0 E0101; Moji_Joho; MJ025818 -8FE0 E0102; Hanyo-Denshi; IB0926 -8FE0 E0102; Moji_Joho; MJ025817 -8FE1 E0100; Hanyo-Denshi; IB0927 -8FE1 E0100; Moji_Joho; MJ025819 -8FE1 E0101; Hanyo-Denshi; IP8FE1 -8FE1 E0101; Moji_Joho; MJ025820 -8FE2 E0100; Adobe-Japan1; CID+6890 -8FE2 E0101; Hanyo-Denshi; JA7775 -8FE2 E0101; Moji_Joho; MJ025822 -8FE2 E0102; Hanyo-Denshi; FT2587 -8FE2 E0102; Moji_Joho; MJ025821 -8FE3 E0100; Adobe-Japan1; CID+22665 -8FE3 E0101; Hanyo-Denshi; JB6534 -8FE3 E0101; Moji_Joho; MJ025824 -8FE3 E0102; Hanyo-Denshi; IB0928 -8FE3 E0102; Moji_Joho; MJ025823 -8FE4 E0100; Adobe-Japan1; CID+15187 -8FE4 E0101; Hanyo-Denshi; JB6535 -8FE4 E0101; Moji_Joho; MJ025826 -8FE4 E0102; Hanyo-Denshi; IB0929 -8FE4 E0102; Moji_Joho; MJ025825 -8FE5 E0100; Adobe-Japan1; CID+6889 -8FE5 E0101; Hanyo-Denshi; JA7774 -8FE5 E0101; Moji_Joho; MJ025828 -8FE5 E0102; Hanyo-Denshi; FT2586 -8FE5 E0102; Moji_Joho; MJ025827 -8FE6 E0100; Adobe-Japan1; CID+1376 -8FE6 E0101; Adobe-Japan1; CID+7647 -8FE6 E0102; Hanyo-Denshi; JA1864 -8FE6 E0102; Moji_Joho; MJ025829 -8FE6 E0103; Hanyo-Denshi; FT1764 -8FE6 E0103; Moji_Joho; MJ025830 -8FE7 E0100; Hanyo-Denshi; IP8FE7 -8FE7 E0101; Hanyo-Denshi; TK01088900 -8FE8 E0100; Adobe-Japan1; CID+17147 -8FE8 E0101; Hanyo-Denshi; JB6536 -8FE8 E0101; Moji_Joho; MJ025834 -8FE8 E0102; Hanyo-Denshi; IB0931 -8FE8 E0102; Moji_Joho; MJ025833 -8FE9 E0100; Adobe-Japan1; CID+3278 -8FE9 E0101; Adobe-Japan1; CID+7872 -8FE9 E0102; Hanyo-Denshi; JA3886 -8FE9 E0102; Moji_Joho; MJ025835 -8FE9 E0103; Hanyo-Denshi; KS439040S -8FE9 E0103; Moji_Joho; MJ025836 -8FE9 E0104; Hanyo-Denshi; FT2001S -8FE9 E0104; Moji_Joho; MJ025837 -8FEA E0100; Adobe-Japan1; CID+6891 -8FEA E0101; Adobe-Japan1; CID+7871 -8FEA E0102; Hanyo-Denshi; JA7776 -8FEA E0102; Moji_Joho; MJ025838 -8FEA E0103; Hanyo-Denshi; FT1994 -8FEA E0103; Moji_Joho; MJ025839 -8FEB E0100; Adobe-Japan1; CID+3373 -8FEB E0101; Adobe-Japan1; CID+13978 -8FEB E0102; Hanyo-Denshi; JA3987 -8FEB E0102; Moji_Joho; MJ025840 -8FEB E0103; Hanyo-Denshi; JTBC60 -8FEB E0103; Moji_Joho; MJ025841 -8FEC E0100; Hanyo-Denshi; IP8FEC -8FEC E0100; Moji_Joho; MJ025843 -8FEC E0101; Hanyo-Denshi; KS438840 -8FEC E0101; Moji_Joho; MJ025842 -8FED E0100; Adobe-Japan1; CID+3117 -8FED E0101; Adobe-Japan1; CID+13947 -8FED E0102; Hanyo-Denshi; JA3719 -8FED E0102; Moji_Joho; MJ025844 -8FED E0103; Hanyo-Denshi; JTBC62 -8FED E0103; Moji_Joho; MJ025845 -8FEE E0100; Adobe-Japan1; CID+17148 -8FEE E0101; Hanyo-Denshi; JB6537 -8FEE E0101; Moji_Joho; MJ025847 -8FEE E0102; Hanyo-Denshi; IB0933 -8FEE E0102; Moji_Joho; MJ025846 -8FEF E0100; Adobe-Japan1; CID+6892 -8FEF E0101; Adobe-Japan1; CID+14227 -8FEF E0102; Hanyo-Denshi; JA7777 -8FEF E0102; Moji_Joho; MJ025848 -8FEF E0103; Hanyo-Denshi; JTBC5E -8FEF E0103; Moji_Joho; MJ025850 -8FEF E0104; Hanyo-Denshi; KS439500 -8FEF E0104; Moji_Joho; MJ025849 -8FF0 E0100; Adobe-Japan1; CID+2396 -8FF0 E0101; Adobe-Japan1; CID+13822 -8FF0 E0102; Hanyo-Denshi; JA2950 -8FF0 E0102; Moji_Joho; MJ025851 -8FF0 E0103; Hanyo-Denshi; JTBC63 -8FF0 E0103; Moji_Joho; MJ025852 -8FF0 E0104; Hanyo-Denshi; KS438820 -8FF0 E0104; Moji_Joho; MJ058845 -8FF1 E0100; Adobe-Japan1; CID+18765 -8FF1 E0101; Hanyo-Denshi; JB6538 -8FF1 E0101; Moji_Joho; MJ025854 -8FF1 E0102; Hanyo-Denshi; IB0934 -8FF1 E0102; Moji_Joho; MJ025853 -8FF4 E0100; Adobe-Japan1; CID+6894 -8FF4 E0101; Hanyo-Denshi; JA7779 -8FF4 E0101; Moji_Joho; MJ025857 -8FF4 E0102; Hanyo-Denshi; FT2590 -8FF4 E0102; Moji_Joho; MJ025856 -8FF5 E0100; Adobe-Japan1; CID+18766 -8FF5 E0101; Hanyo-Denshi; JB6539 -8FF5 E0101; Moji_Joho; MJ025859 -8FF5 E0102; Hanyo-Denshi; JTBC69 -8FF5 E0102; Moji_Joho; MJ025858 -8FF6 E0100; Adobe-Japan1; CID+15188 -8FF6 E0101; Adobe-Japan1; CID+20230 -8FF6 E0102; Hanyo-Denshi; JB6540 -8FF6 E0103; Hanyo-Denshi; TK01041340 -8FF7 E0100; Adobe-Japan1; CID+3790 -8FF7 E0101; Adobe-Japan1; CID+14054 -8FF7 E0102; Hanyo-Denshi; JA4434 -8FF7 E0102; Moji_Joho; MJ025861 -8FF7 E0103; Hanyo-Denshi; JTBC79 -8FF7 E0103; Moji_Joho; MJ025862 -8FF8 E0100; Adobe-Japan1; CID+6909 -8FF8 E0101; Hanyo-Denshi; JA7794 -8FF8 E0101; Moji_Joho; MJ025863 -8FF8 E0102; Hanyo-Denshi; FT2611 -8FF8 E0102; Moji_Joho; MJ025864 -8FF9 E0100; Adobe-Japan1; CID+6896 -8FF9 E0101; Hanyo-Denshi; JA7781 -8FF9 E0101; Moji_Joho; MJ025866 -8FF9 E0102; Hanyo-Denshi; FT2592 -8FF9 E0102; Moji_Joho; MJ025865 -8FFA E0100; Adobe-Japan1; CID+6897 -8FFA E0101; Adobe-Japan1; CID+14229 -8FFA E0102; Hanyo-Denshi; JA7782 -8FFA E0102; Moji_Joho; MJ025868 -8FFA E0103; Hanyo-Denshi; FT2593 -8FFA E0103; Moji_Joho; MJ025867 -8FFA E0104; Hanyo-Denshi; TK01089160 -8FFB E0100; Adobe-Japan1; CID+18767 -8FFB E0101; Hanyo-Denshi; JB6541 -8FFB E0101; Moji_Joho; MJ025870 -8FFB E0102; Hanyo-Denshi; IB0935 -8FFB E0102; Moji_Joho; MJ025869 -8FFD E0100; Adobe-Japan1; CID+3045 -8FFD E0101; Adobe-Japan1; CID+13938 -8FFD E0102; Hanyo-Denshi; JA3641 -8FFD E0102; Moji_Joho; MJ025871 -8FFD E0103; Hanyo-Denshi; JTBC7A -8FFD E0103; Moji_Joho; MJ025872 -8FFE E0100; Adobe-Japan1; CID+22666 -8FFE E0101; Hanyo-Denshi; JB6542 -8FFE E0101; Moji_Joho; MJ025875 -8FFE E0102; Hanyo-Denshi; IB0937 -8FFE E0102; Moji_Joho; MJ025874 -8FFF E0100; Hanyo-Denshi; IB0938 -8FFF E0100; Moji_Joho; MJ025876 -8FFF E0101; Hanyo-Denshi; IP8FFF -8FFF E0101; Moji_Joho; MJ025877 -9000 E0100; Adobe-Japan1; CID+2880 -9000 E0101; Adobe-Japan1; CID+13905 -9000 E0102; Hanyo-Denshi; JA3464 -9000 E0102; Moji_Joho; MJ025878 -9000 E0103; Hanyo-Denshi; JTBC7B -9000 E0103; Moji_Joho; MJ025879 -9001 E0100; Adobe-Japan1; CID+2809 -9001 E0101; Adobe-Japan1; CID+13895 -9001 E0102; Hanyo-Denshi; JA3387 -9001 E0102; Moji_Joho; MJ025880 -9001 E0103; Hanyo-Denshi; JTBC7C -9001 E0103; Moji_Joho; MJ025881 -9002 E0100; Adobe-Japan1; CID+15189 -9002 E0101; Hanyo-Denshi; JB6543 -9002 E0101; Moji_Joho; MJ025883 -9002 E0102; Hanyo-Denshi; IB0939 -9002 E0102; Moji_Joho; MJ025882 -9003 E0100; Adobe-Japan1; CID+3200 -9003 E0101; Adobe-Japan1; CID+13485 -9003 E0102; Adobe-Japan1; CID+13959 -9003 E0103; Hanyo-Denshi; JA3808 -9003 E0103; Moji_Joho; MJ025884 -9003 E0104; Hanyo-Denshi; JTBC7D -9003 E0104; Moji_Joho; MJ025885 -9004 E0100; Adobe-Japan1; CID+19886 -9004 E0101; Hanyo-Denshi; JB6544 -9004 E0101; Moji_Joho; MJ025888 -9004 E0102; Hanyo-Denshi; JTBC70 -9004 E0102; Moji_Joho; MJ025886 -9004 E0103; Hanyo-Denshi; KS439810 -9004 E0103; Moji_Joho; MJ025887 -9005 E0100; Adobe-Japan1; CID+6895 -9005 E0101; Hanyo-Denshi; JA7780 -9005 E0101; Moji_Joho; MJ025890 -9005 E0102; Hanyo-Denshi; FT2591 -9005 E0102; Moji_Joho; MJ025889 -9006 E0100; Adobe-Japan1; CID+1647 -9006 E0101; Adobe-Japan1; CID+13709 -9006 E0102; Hanyo-Denshi; JA2153 -9006 E0102; Moji_Joho; MJ025891 -9006 E0103; Hanyo-Denshi; JTBC78 -9006 E0103; Moji_Joho; MJ025892 -9008 E0100; Adobe-Japan1; CID+17149 -9008 E0101; Hanyo-Denshi; JB6545 -9008 E0101; Moji_Joho; MJ025894 -9008 E0102; Hanyo-Denshi; JTBC75 -9008 E0102; Moji_Joho; MJ025895 -900B E0100; Adobe-Japan1; CID+6904 -900B E0101; Hanyo-Denshi; JA7789 -900B E0101; Moji_Joho; MJ025898 -900B E0102; Hanyo-Denshi; FT2606 -900B E0102; Moji_Joho; MJ025897 -900C E0100; Adobe-Japan1; CID+18768 -900C E0101; Hanyo-Denshi; JB6546 -900C E0101; Moji_Joho; MJ025900 -900C E0102; Hanyo-Denshi; IB0945 -900C E0102; Moji_Joho; MJ025899 -900D E0100; Adobe-Japan1; CID+6901 -900D E0101; Hanyo-Denshi; JA7786 -900D E0101; Moji_Joho; MJ025902 -900D E0102; Hanyo-Denshi; IB0943 -900D E0102; Moji_Joho; MJ025901 -900D E0103; Hanyo-Denshi; FT2603 -900D E0103; Moji_Joho; MJ025903 -900E E0100; Adobe-Japan1; CID+6914 -900E E0101; Adobe-Japan1; CID+13608 -900E E0102; Hanyo-Denshi; JA7805 -900E E0102; Moji_Joho; MJ025905 -900E E0103; Hanyo-Denshi; KS440220 -900E E0103; Moji_Joho; MJ025904 -900E E0104; Hanyo-Denshi; FT2616 -900E E0104; Moji_Joho; MJ025907 -900E E0105; Hanyo-Denshi; KS441030 -900E E0105; Moji_Joho; MJ025906 -900F E0100; Adobe-Japan1; CID+3201 -900F E0101; Adobe-Japan1; CID+13960 -900F E0102; Hanyo-Denshi; JA3809 -900F E0102; Moji_Joho; MJ025908 -900F E0103; Hanyo-Denshi; JTBC94 -900F E0103; Moji_Joho; MJ025909 -9010 E0100; Adobe-Japan1; CID+2974 -9010 E0101; Adobe-Japan1; CID+13924 -9010 E0102; Hanyo-Denshi; JA3564 -9010 E0102; Moji_Joho; MJ025910 -9010 E0103; Hanyo-Denshi; JTBC99 -9010 E0103; Moji_Joho; MJ025911 -9010 E0104; Hanyo-Denshi; KS441940 -9010 E0104; Moji_Joho; MJ025912 -9011 E0100; Adobe-Japan1; CID+6898 -9011 E0101; Hanyo-Denshi; JA7783 -9011 E0101; Moji_Joho; MJ025914 -9011 E0102; Hanyo-Denshi; FT2594 -9011 E0102; Moji_Joho; MJ025913 -9011 E0103; Moji_Joho; MJ025915 -9013 E0100; Adobe-Japan1; CID+3098 -9013 E0101; Hanyo-Denshi; JA3694 -9013 E0101; Moji_Joho; MJ025917 -9013 E0102; Hanyo-Denshi; KS440460 -9013 E0102; Moji_Joho; MJ025918 -9014 E0100; Adobe-Japan1; CID+3149 -9014 E0101; Adobe-Japan1; CID+13950 -9014 E0102; Hanyo-Denshi; JA3751 -9014 E0102; Moji_Joho; MJ025919 -9014 E0103; Hanyo-Denshi; JTBC9A -9014 E0103; Moji_Joho; MJ025920 -9015 E0100; Adobe-Japan1; CID+6899 -9015 E0101; Hanyo-Denshi; JA7784 -9015 E0101; Moji_Joho; MJ025922 -9015 E0102; Hanyo-Denshi; FT2601 -9015 E0102; Moji_Joho; MJ025921 -9016 E0100; Adobe-Japan1; CID+6903 -9016 E0101; Hanyo-Denshi; JA7788 -9016 E0101; Moji_Joho; MJ025924 -9016 E0102; Hanyo-Denshi; KS440200 -9016 E0102; Moji_Joho; MJ025923 -9016 E0103; Moji_Joho; MJ025925 -9017 E0100; Adobe-Japan1; CID+2598 -9017 E0101; Adobe-Japan1; CID+7711 -9017 E0102; Hanyo-Denshi; JA3164 -9017 E0102; Moji_Joho; MJ025926 -9017 E0103; Hanyo-Denshi; FT1832 -9017 E0103; Moji_Joho; MJ025927 -9018 E0100; Adobe-Japan1; CID+22667 -9018 E0101; Hanyo-Denshi; JB6547 -9018 E0101; Moji_Joho; MJ025928 -9018 E0102; Hanyo-Denshi; IB3013 -9018 E0102; Moji_Joho; MJ025929 -9019 E0100; Adobe-Japan1; CID+3357 -9019 E0101; Adobe-Japan1; CID+7772 -9019 E0102; Hanyo-Denshi; JA3971 -9019 E0102; Moji_Joho; MJ025930 -9019 E0103; Hanyo-Denshi; FT1893 -9019 E0103; Moji_Joho; MJ025931 -901A E0100; Adobe-Japan1; CID+3048 -901A E0101; Adobe-Japan1; CID+13939 -901A E0102; Hanyo-Denshi; JA3644 -901A E0102; Moji_Joho; MJ025932 -901A E0103; Hanyo-Denshi; JTBC9B -901A E0103; Moji_Joho; MJ025933 -901B E0100; Adobe-Japan1; CID+19887 -901B E0101; Hanyo-Denshi; JB6548 -901B E0101; Moji_Joho; MJ025935 -901B E0102; Hanyo-Denshi; IB0947 -901B E0102; Moji_Joho; MJ025934 -901D E0100; Adobe-Japan1; CID+2662 -901D E0101; Adobe-Japan1; CID+7714 -901D E0102; Hanyo-Denshi; JA3234 -901D E0102; Moji_Joho; MJ025937 -901D E0103; Hanyo-Denshi; FT1835 -901D E0103; Moji_Joho; MJ025938 -901E E0100; Adobe-Japan1; CID+6902 -901E E0101; Adobe-Japan1; CID+14230 -901E E0102; Hanyo-Denshi; JA7787 -901E E0102; Moji_Joho; MJ025941 -901E E0103; Hanyo-Denshi; IB0948 -901E E0103; Moji_Joho; MJ025939 -901E E0104; Hanyo-Denshi; IB0402 -901E E0104; Moji_Joho; MJ025940 -901E E0105; Hanyo-Denshi; FT2604 -901E E0105; Moji_Joho; MJ025942 -901E E0106; Hanyo-Denshi; TK01089070 -901F E0100; Adobe-Japan1; CID+2830 -901F E0101; Adobe-Japan1; CID+13899 -901F E0102; Hanyo-Denshi; JA3414 -901F E0102; Moji_Joho; MJ025944 -901F E0103; Hanyo-Denshi; JTBC9C -901F E0103; Moji_Joho; MJ025945 -9020 E0100; Adobe-Japan1; CID+2820 -9020 E0101; Adobe-Japan1; CID+13897 -9020 E0102; Hanyo-Denshi; JA3404 -9020 E0102; Moji_Joho; MJ025946 -9020 E0103; Hanyo-Denshi; JTBC93 -9020 E0103; Moji_Joho; MJ025947 -9020 E0104; Hanyo-Denshi; TK01089340 -9021 E0100; Adobe-Japan1; CID+6900 -9021 E0101; Hanyo-Denshi; JA7785 -9021 E0101; Moji_Joho; MJ025950 -9021 E0102; Hanyo-Denshi; FT2602 -9021 E0102; Moji_Joho; MJ025949 -9022 E0100; Adobe-Japan1; CID+1133 -9022 E0101; Adobe-Japan1; CID+8266 -9022 E0102; Adobe-Japan1; CID+13408 -9022 E0103; Hanyo-Denshi; JA1609 -9022 E0103; Moji_Joho; MJ025951 -9022 E0104; Hanyo-Denshi; FT1750 -9022 E0104; Moji_Joho; MJ025952 -9023 E0100; Adobe-Japan1; CID+14097 -9023 E0101; Adobe-Japan1; CID+4040 -9023 E0102; Hanyo-Denshi; JA4702 -9023 E0102; Moji_Joho; MJ025953 -9023 E0103; Hanyo-Denshi; JTBC9D -9023 E0103; Moji_Joho; MJ025954 -9024 E0100; Hanyo-Denshi; IB0949 -9024 E0100; Moji_Joho; MJ025955 -9024 E0101; Hanyo-Denshi; IP9024 -9024 E0101; Moji_Joho; MJ025956 -9027 E0100; Adobe-Japan1; CID+6905 -9027 E0101; Hanyo-Denshi; JA7790 -9027 E0101; Moji_Joho; MJ025958 -9027 E0102; Hanyo-Denshi; FT2607 -9027 E0102; Moji_Joho; MJ025959 -9028 E0100; Adobe-Japan1; CID+22668 -9028 E0101; Hanyo-Denshi; JB6549 -9028 E0101; Moji_Joho; MJ025960 -9028 E0102; Hanyo-Denshi; JTBCB5 -9028 E0102; Moji_Joho; MJ025961 -9029 E0100; Adobe-Japan1; CID+22669 -9029 E0101; Hanyo-Denshi; JB6550 -9029 E0101; Moji_Joho; MJ025963 -9029 E0102; Hanyo-Denshi; IB0950 -9029 E0102; Moji_Joho; MJ025962 -902A E0100; Adobe-Japan1; CID+22670 -902A E0101; Hanyo-Denshi; JB6552 -902A E0101; Moji_Joho; MJ025965 -902A E0102; Hanyo-Denshi; IB0952 -902A E0102; Moji_Joho; MJ025964 -902B E0100; Hanyo-Denshi; IB0953 -902B E0100; Moji_Joho; MJ025966 -902B E0101; Hanyo-Denshi; IP902B -902B E0101; Moji_Joho; MJ025967 -902C E0100; Adobe-Japan1; CID+15190 -902C E0101; Hanyo-Denshi; JB6553 -902C E0101; Moji_Joho; MJ025969 -902C E0102; Hanyo-Denshi; IB0954 -902C E0102; Moji_Joho; MJ025968 -902D E0100; Adobe-Japan1; CID+17150 -902D E0101; Hanyo-Denshi; JB6554 -902D E0101; Moji_Joho; MJ025971 -902D E0102; Hanyo-Denshi; IB0955 -902D E0102; Moji_Joho; MJ025970 -902E E0100; Adobe-Japan1; CID+2881 -902E E0101; Adobe-Japan1; CID+13906 -902E E0102; Hanyo-Denshi; JA3465 -902E E0102; Moji_Joho; MJ025972 -902E E0103; Hanyo-Denshi; JTBCB7 -902E E0103; Moji_Joho; MJ025973 -902F E0100; Adobe-Japan1; CID+19888 -902F E0101; Hanyo-Denshi; JB6551 -902F E0101; Moji_Joho; MJ025975 -902F E0102; Hanyo-Denshi; IB0951 -902F E0102; Moji_Joho; MJ025974 -9031 E0100; Adobe-Japan1; CID+2367 -9031 E0101; Adobe-Japan1; CID+13819 -9031 E0102; Hanyo-Denshi; JA2921 -9031 E0102; Moji_Joho; MJ025977 -9031 E0103; Hanyo-Denshi; JTBCB8 -9031 E0103; Moji_Joho; MJ025978 -9032 E0100; Adobe-Japan1; CID+2576 -9032 E0101; Adobe-Japan1; CID+13855 -9032 E0102; Hanyo-Denshi; JA3142 -9032 E0102; Moji_Joho; MJ025979 -9032 E0103; Hanyo-Denshi; JTBCB6 -9032 E0103; Moji_Joho; MJ025980 -9033 E0100; Adobe-Japan1; CID+22671 -9034 E0100; Adobe-Japan1; CID+22672 -9034 E0101; Hanyo-Denshi; JB6556 -9034 E0101; Moji_Joho; MJ025983 -9034 E0102; Hanyo-Denshi; IB0957 -9034 E0102; Moji_Joho; MJ025982 -9035 E0100; Adobe-Japan1; CID+6907 -9035 E0101; Adobe-Japan1; CID+14231 -9035 E0102; Hanyo-Denshi; JA7792 -9035 E0102; Moji_Joho; MJ025985 -9035 E0103; Hanyo-Denshi; KS440920S -9035 E0103; Moji_Joho; MJ025984 -9035 E0104; Hanyo-Denshi; FT2609S -9035 E0104; Moji_Joho; MJ025986 -9035 E0105; Hanyo-Denshi; TK01089320 -9035 E0106; Hanyo-Denshi; TK01089330 -9035 E0107; Hanyo-Denshi; TK01089490 -9036 E0100; Adobe-Japan1; CID+6906 -9036 E0101; Hanyo-Denshi; JA7791 -9036 E0101; Moji_Joho; MJ025990 -9036 E0102; Hanyo-Denshi; FT2608 -9036 E0102; Moji_Joho; MJ025989 -9037 E0100; Adobe-Japan1; CID+18769 -9037 E0101; Hanyo-Denshi; JB6557 -9037 E0101; Moji_Joho; MJ025992 -9037 E0102; Hanyo-Denshi; IB0958 -9037 E0102; Moji_Joho; MJ025991 -9038 E0100; Adobe-Japan1; CID+1203 -9038 E0101; Adobe-Japan1; CID+13320 -9038 E0102; Adobe-Japan1; CID+8633 -9038 E0103; Hanyo-Denshi; JA1679 -9038 E0103; Moji_Joho; MJ025993 -9038 E0104; Hanyo-Denshi; JTBCE7S -9038 E0104; Moji_Joho; MJ025996 -9038 E0105; Hanyo-Denshi; JTBCB3S -9038 E0105; Moji_Joho; MJ025995 -9038 E0106; Hanyo-Denshi; JTBC9FS -9038 E0106; Moji_Joho; MJ025994 -9038 E0107; Hanyo-Denshi; JC9257 -9038 E0108; Hanyo-Denshi; JTFA25S -9038 E0109; Hanyo-Denshi; TK01089600 -9039 E0100; Adobe-Japan1; CID+6908 -9039 E0101; Adobe-Japan1; CID+13912 -9039 E0102; Hanyo-Denshi; JA7793 -9039 E0102; Moji_Joho; MJ025999 -9039 E0103; Hanyo-Denshi; FT2610 -9039 E0103; Moji_Joho; MJ025998 -9039 E0104; Hanyo-Denshi; JTBCA2 -9039 E0104; Moji_Joho; MJ026000 -9039 E0105; Hanyo-Denshi; TK01089350 -9039 E0106; Moji_Joho; MJ026001 -903A E0100; Hanyo-Denshi; KS441960 -903A E0101; Hanyo-Denshi; TK01089470 -903A E0102; Hanyo-Denshi; TK01089500 -903C E0100; Adobe-Japan1; CID+3489 -903C E0101; Adobe-Japan1; CID+7783 -903C E0102; Hanyo-Denshi; JA4115 -903C E0102; Moji_Joho; MJ026002 -903C E0103; Hanyo-Denshi; HG1656 -903C E0103; Moji_Joho; MJ026003 -903E E0100; Adobe-Japan1; CID+6916 -903E E0101; Hanyo-Denshi; JA7807 -903E E0101; Moji_Joho; MJ026006 -903E E0102; Hanyo-Denshi; IB0962 -903E E0102; Moji_Joho; MJ026005 -903E E0103; Hanyo-Denshi; FT2618 -903E E0103; Moji_Joho; MJ026007 -903F E0100; Adobe-Japan1; CID+22673 -903F E0101; Hanyo-Denshi; JB6558 -903F E0101; Moji_Joho; MJ026009 -903F E0102; Hanyo-Denshi; IB0964 -903F E0102; Moji_Joho; MJ026008 -9040 E0100; Hanyo-Denshi; IB0965 -9040 E0100; Moji_Joho; MJ026010 -9040 E0101; Hanyo-Denshi; IP9040 -9040 E0101; Moji_Joho; MJ026011 -9041 E0100; Adobe-Japan1; CID+3251 -9041 E0101; Adobe-Japan1; CID+7763 -9041 E0102; Adobe-Japan1; CID+20287 -9041 E0103; Hanyo-Denshi; JA3859 -9041 E0103; Moji_Joho; MJ026012 -9041 E0104; Hanyo-Denshi; HG1653 -9041 E0104; Moji_Joho; MJ026013 -9041 E0105; Moji_Joho; MJ026014 -9042 E0100; Adobe-Japan1; CID+2609 -9042 E0101; Adobe-Japan1; CID+13468 -9042 E0102; Adobe-Japan1; CID+13864 -9042 E0103; Hanyo-Denshi; JA3175 -9042 E0103; Moji_Joho; MJ026015 -9042 E0104; Hanyo-Denshi; IB0967 -9042 E0104; Moji_Joho; MJ026016 -9042 E0105; Hanyo-Denshi; IB0408 -9042 E0105; Moji_Joho; MJ026017 -9042 E0106; Moji_Joho; MJ026018 -9043 E0100; Adobe-Japan1; CID+18771 -9043 E0101; Hanyo-Denshi; JB6559 -9043 E0102; Hanyo-Denshi; TK01089670 -9044 E0100; Adobe-Japan1; CID+15191 -9044 E0101; Hanyo-Denshi; JB6560 -9044 E0101; Moji_Joho; MJ026022 -9044 E0102; Hanyo-Denshi; IB0968 -9044 E0102; Moji_Joho; MJ026021 -9045 E0100; Adobe-Japan1; CID+2967 -9045 E0101; Hanyo-Denshi; JA3557 -9045 E0101; Moji_Joho; MJ026023 -9045 E0102; Hanyo-Denshi; KS442160 -9045 E0102; Moji_Joho; MJ026024 -9047 E0100; Adobe-Japan1; CID+1776 -9047 E0101; Adobe-Japan1; CID+13736 -9047 E0102; Hanyo-Denshi; JA2288 -9047 E0102; Moji_Joho; MJ026026 -9047 E0103; Hanyo-Denshi; KS442770 -9047 E0103; Moji_Joho; MJ026028 -9047 E0104; Hanyo-Denshi; JTBCE3 -9047 E0104; Moji_Joho; MJ026027 -9049 E0100; Adobe-Japan1; CID+6915 -9049 E0101; Hanyo-Denshi; JA7806 -9049 E0101; Moji_Joho; MJ026031 -9049 E0102; Hanyo-Denshi; FT2617 -9049 E0102; Moji_Joho; MJ026030 -904A E0100; Adobe-Japan1; CID+3873 -904A E0101; Adobe-Japan1; CID+14076 -904A E0102; Hanyo-Denshi; JA4523 -904A E0102; Moji_Joho; MJ026032 -904A E0103; Hanyo-Denshi; JTBCDBS -904A E0103; Moji_Joho; MJ026033 -904B E0100; Adobe-Japan1; CID+1249 -904B E0101; Adobe-Japan1; CID+13649 -904B E0102; Hanyo-Denshi; JA1731 -904B E0102; Moji_Joho; MJ026034 -904B E0103; Hanyo-Denshi; JTBCE4 -904B E0103; Moji_Joho; MJ026035 -904C E0100; Adobe-Japan1; CID+19889 -904C E0101; Hanyo-Denshi; JB6561 -904C E0101; Moji_Joho; MJ026037 -904C E0102; Hanyo-Denshi; IB0969 -904C E0102; Moji_Joho; MJ026036 -904C E0103; Hanyo-Denshi; KS442790 -904C E0103; Moji_Joho; MJ026038 -904D E0100; Adobe-Japan1; CID+3623 -904D E0101; Adobe-Japan1; CID+14017 -904D E0102; Hanyo-Denshi; JA4255 -904D E0102; Moji_Joho; MJ026039 -904D E0103; Hanyo-Denshi; JTBCE5 -904D E0103; Moji_Joho; MJ026040 -904E E0100; Adobe-Japan1; CID+1377 -904E E0101; Adobe-Japan1; CID+13669 -904E E0102; Hanyo-Denshi; JA1865 -904E E0102; Moji_Joho; MJ026041 -904E E0103; Hanyo-Denshi; JTBCE6 -904E E0103; Moji_Joho; MJ026042 -904E E0104; Hanyo-Denshi; KS441950 -904E E0104; Moji_Joho; MJ058856 -904F E0100; Adobe-Japan1; CID+6910 -904F E0101; Hanyo-Denshi; JA7801 -904F E0101; Moji_Joho; MJ026045 -904F E0102; Hanyo-Denshi; IB0960 -904F E0102; Moji_Joho; MJ026044 -904F E0103; Hanyo-Denshi; FT2612 -904F E0103; Moji_Joho; MJ026046 -904F E0104; Hanyo-Denshi; JTBCB9 -904F E0104; Moji_Joho; MJ026043 -9050 E0100; Adobe-Japan1; CID+6911 -9050 E0101; Adobe-Japan1; CID+14232 -9050 E0102; Hanyo-Denshi; JA7802 -9050 E0102; Moji_Joho; MJ026048 -9050 E0103; Hanyo-Denshi; FT2613 -9050 E0103; Moji_Joho; MJ026049 -9050 E0104; Moji_Joho; MJ026047 -9051 E0100; Adobe-Japan1; CID+6912 -9051 E0101; Hanyo-Denshi; JA7803 -9051 E0101; Moji_Joho; MJ026051 -9051 E0102; Hanyo-Denshi; FT2614 -9051 E0102; Moji_Joho; MJ026050 -9052 E0100; Adobe-Japan1; CID+6913 -9052 E0101; Adobe-Japan1; CID+13607 -9052 E0102; Hanyo-Denshi; JA7804 -9052 E0102; Moji_Joho; MJ026053 -9052 E0103; Hanyo-Denshi; JTBCD5 -9052 E0103; Moji_Joho; MJ026055 -9052 E0104; Hanyo-Denshi; IB0961 -9052 E0104; Moji_Joho; MJ026052 -9052 E0105; Hanyo-Denshi; FT2615 -9052 E0105; Moji_Joho; MJ026056 -9052 E0106; Hanyo-Denshi; JTBCD7 -9052 E0106; Moji_Joho; MJ026057 -9052 E0107; Hanyo-Denshi; KS442660 -9052 E0107; Moji_Joho; MJ026054 -9053 E0100; Adobe-Japan1; CID+3219 -9053 E0101; Adobe-Japan1; CID+13963 -9053 E0102; Hanyo-Denshi; JA3827 -9053 E0102; Moji_Joho; MJ026058 -9053 E0103; Hanyo-Denshi; JTBCDA -9053 E0103; Moji_Joho; MJ026059 -9054 E0100; Adobe-Japan1; CID+2913 -9054 E0101; Adobe-Japan1; CID+13912 -9054 E0102; Hanyo-Denshi; JA3503 -9054 E0102; Moji_Joho; MJ026060 -9054 E0103; Hanyo-Denshi; JTBCD9 -9054 E0103; Moji_Joho; MJ026061 -9054 E0104; Hanyo-Denshi; TK01089890 -9055 E0100; Adobe-Japan1; CID+1191 -9055 E0101; Adobe-Japan1; CID+13411 -9055 E0102; Adobe-Japan1; CID+13641 -9055 E0103; Hanyo-Denshi; JA1667 -9055 E0103; Moji_Joho; MJ026064 -9055 E0104; Hanyo-Denshi; IB0405S -9055 E0104; Moji_Joho; MJ026066 -9055 E0105; Hanyo-Denshi; JTBCDC -9055 E0105; Moji_Joho; MJ026062 -9055 E0106; Moji_Joho; MJ026063 -9055 E0107; Moji_Joho; MJ026065 -9056 E0100; Adobe-Japan1; CID+6917 -9056 E0101; Hanyo-Denshi; JA7808 -9056 E0101; Moji_Joho; MJ026068 -9056 E0102; Hanyo-Denshi; FT2619 -9056 E0102; Moji_Joho; MJ026067 -9058 E0100; Adobe-Japan1; CID+6918 -9058 E0101; Adobe-Japan1; CID+7873 -9058 E0102; Hanyo-Denshi; JA7809 -9058 E0102; Moji_Joho; MJ026071 -9058 E0103; Hanyo-Denshi; FT2002 -9058 E0103; Moji_Joho; MJ026070 -9058 E0104; Hanyo-Denshi; FT2620 -9058 E0104; Moji_Joho; MJ026072 -9058 E0105; Hanyo-Denshi; IB0972 -9058 E0105; Moji_Joho; MJ026069 -9059 E0100; Adobe-Japan1; CID+7476 -9059 E0101; Hanyo-Denshi; JA8403 -9059 E0101; Moji_Joho; MJ026074 -9059 E0102; Hanyo-Denshi; JTBCFA -9059 E0102; Moji_Joho; MJ026073 -905B E0100; Adobe-Japan1; CID+19890 -905B E0101; Hanyo-Denshi; JB6562 -905B E0101; Moji_Joho; MJ026077 -905B E0102; Hanyo-Denshi; IB0973 -905B E0102; Moji_Joho; MJ026076 -905C E0100; Adobe-Japan1; CID+2845 -905C E0101; Adobe-Japan1; CID+7726 -905C E0102; Hanyo-Denshi; JA3429 -905C E0102; Moji_Joho; MJ026078 -905C E0103; Hanyo-Denshi; FT1846 -905C E0103; Moji_Joho; MJ026079 -905D E0100; Adobe-Japan1; CID+18772 -905D E0101; Hanyo-Denshi; JB6563 -905D E0101; Moji_Joho; MJ026081 -905D E0102; Hanyo-Denshi; IB0976 -905D E0102; Moji_Joho; MJ026080 -905E E0100; Adobe-Japan1; CID+6919 -905E E0101; Hanyo-Denshi; JA7810 -905E E0101; Moji_Joho; MJ026083 -905E E0102; Hanyo-Denshi; FT2621S -905E E0102; Moji_Joho; MJ026082 -905F E0100; Hanyo-Denshi; IB0977 -905F E0100; Moji_Joho; MJ026084 -905F E0101; Hanyo-Denshi; IP905F -905F E0101; Moji_Joho; MJ026085 -9060 E0100; Adobe-Japan1; CID+1301 -9060 E0101; Adobe-Japan1; CID+13658 -9060 E0102; Hanyo-Denshi; JA1783 -9060 E0102; Moji_Joho; MJ026086 -9060 E0103; Hanyo-Denshi; JTBD02 -9060 E0103; Moji_Joho; MJ026088 -9060 E0104; Hanyo-Denshi; JTBCFE -9060 E0104; Moji_Joho; MJ026087 -9061 E0100; Adobe-Japan1; CID+2766 -9061 E0101; Adobe-Japan1; CID+7722 -9061 E0102; Hanyo-Denshi; JA3344 -9061 E0102; Moji_Joho; MJ026089 -9061 E0103; Hanyo-Denshi; FT1843 -9061 E0103; Moji_Joho; MJ026090 -9062 E0100; Adobe-Japan1; CID+22674 -9062 E0101; Hanyo-Denshi; JB6564 -9062 E0101; Moji_Joho; MJ026092 -9062 E0102; Hanyo-Denshi; IB0414 -9062 E0102; Moji_Joho; MJ026093 -9062 E0103; Hanyo-Denshi; IB0978 -9062 E0103; Moji_Joho; MJ026091 -9063 E0100; Adobe-Japan1; CID+1891 -9063 E0101; Adobe-Japan1; CID+13754 -9063 E0102; Hanyo-Denshi; JA2415 -9063 E0102; Moji_Joho; MJ026094 -9063 E0103; Hanyo-Denshi; JTBD01 -9063 E0103; Moji_Joho; MJ026095 -9065 E0100; Adobe-Japan1; CID+3908 -9065 E0101; Hanyo-Denshi; JA4558 -9065 E0101; Moji_Joho; MJ026096 -9065 E0102; Hanyo-Denshi; JTBCE9 -9065 E0102; Moji_Joho; MJ026097 -9066 E0100; Adobe-Japan1; CID+22675 -9066 E0101; Hanyo-Denshi; JB6565 -9066 E0101; Moji_Joho; MJ026098 -9066 E0102; Hanyo-Denshi; JTBD0F -9066 E0102; Moji_Joho; MJ026099 -9067 E0100; Adobe-Japan1; CID+8634 -9067 E0101; Hanyo-Denshi; JB6566 -9067 E0101; Moji_Joho; MJ026101 -9067 E0102; Hanyo-Denshi; IB0981 -9067 E0102; Moji_Joho; MJ026100 -9068 E0100; Adobe-Japan1; CID+6920 -9068 E0101; Hanyo-Denshi; JA7811 -9068 E0101; Moji_Joho; MJ026103 -9068 E0102; Hanyo-Denshi; FT2622S -9068 E0102; Moji_Joho; MJ026102 -9068 E0103; Moji_Joho; MJ026104 -9069 E0100; Adobe-Japan1; CID+3110 -9069 E0101; Adobe-Japan1; CID+13946 -9069 E0102; Hanyo-Denshi; JA3712 -9069 E0102; Moji_Joho; MJ026105 -9069 E0103; Hanyo-Denshi; KS443450 -9069 E0103; Moji_Joho; MJ026106 -9069 E0104; Hanyo-Denshi; JTBD17 -9069 E0104; Moji_Joho; MJ026107 -906C E0100; Adobe-Japan1; CID+22676 -906C E0101; Hanyo-Denshi; JB6567 -906C E0101; Moji_Joho; MJ026111 -906C E0102; Hanyo-Denshi; IB0983 -906C E0102; Moji_Joho; MJ026110 -906D E0100; Adobe-Japan1; CID+2810 -906D E0101; Adobe-Japan1; CID+13896 -906D E0102; Hanyo-Denshi; JA3388 -906D E0102; Moji_Joho; MJ026112 -906D E0103; Hanyo-Denshi; JTBD18 -906D E0103; Moji_Joho; MJ026113 -906E E0100; Adobe-Japan1; CID+2307 -906E E0101; Adobe-Japan1; CID+7694 -906E E0102; Hanyo-Denshi; JA2855 -906E E0102; Moji_Joho; MJ026114 -906E E0103; Hanyo-Denshi; JTBD28 -906E E0103; Moji_Joho; MJ026117 -906E E0104; Hanyo-Denshi; FT1815 -906E E0104; Moji_Joho; MJ026116 -906E E0105; Hanyo-Denshi; KS443330 -906E E0105; Moji_Joho; MJ026115 -906F E0100; Adobe-Japan1; CID+6921 -906F E0101; Hanyo-Denshi; JA7812 -906F E0101; Moji_Joho; MJ026119 -906F E0102; Hanyo-Denshi; KS443250S -906F E0102; Moji_Joho; MJ026118 -906F E0103; Hanyo-Denshi; IB0416 -906F E0103; Moji_Joho; MJ026121 -906F E0104; Moji_Joho; MJ026120 -906F E0105; Moji_Joho; MJ026122 -9070 E0100; Adobe-Japan1; CID+19891 -9070 E0101; Hanyo-Denshi; JB6568 -9070 E0101; Moji_Joho; MJ026124 -9070 E0102; Hanyo-Denshi; IB0985 -9070 E0102; Moji_Joho; MJ026123 -9072 E0100; Adobe-Japan1; CID+6924 -9072 E0101; Hanyo-Denshi; JA7815 -9072 E0101; Moji_Joho; MJ026127 -9072 E0102; Hanyo-Denshi; FT2626 -9072 E0102; Moji_Joho; MJ026126 -9072 E0103; Hanyo-Denshi; KS444040 -9072 E0103; Moji_Joho; MJ058867 -9072 E0104; Hanyo-Denshi; TK01090190 -9073 E0100; Hanyo-Denshi; IB0986 -9073 E0100; Moji_Joho; MJ026128 -9073 E0101; Hanyo-Denshi; IP9073 -9073 E0101; Moji_Joho; MJ026129 -9073 E0102; Hanyo-Denshi; KS444030 -9073 E0102; Moji_Joho; MJ026130 -9074 E0100; Adobe-Japan1; CID+19892 -9074 E0101; Hanyo-Denshi; JB6569 -9074 E0101; Moji_Joho; MJ026133 -9074 E0102; Hanyo-Denshi; JTBD37 -9074 E0102; Moji_Joho; MJ026134 -9074 E0103; Hanyo-Denshi; JTBD39 -9074 E0103; Moji_Joho; MJ026131 -9074 E0104; Moji_Joho; MJ026132 -9075 E0100; Adobe-Japan1; CID+2415 -9075 E0101; Adobe-Japan1; CID+13824 -9075 E0102; Adobe-Japan1; CID+13825 -9075 E0103; Hanyo-Denshi; JA2969 -9075 E0103; Moji_Joho; MJ026135 -9075 E0104; Hanyo-Denshi; IB0988 -9075 E0104; Moji_Joho; MJ026136 -9075 E0105; Hanyo-Denshi; IB0419 -9075 E0105; Moji_Joho; MJ026137 -9076 E0100; Adobe-Japan1; CID+6922 -9076 E0101; Hanyo-Denshi; JA7813 -9076 E0101; Moji_Joho; MJ026139 -9076 E0102; Hanyo-Denshi; FT2624 -9076 E0102; Moji_Joho; MJ026138 -9077 E0100; Adobe-Japan1; CID+2733 -9077 E0101; Adobe-Japan1; CID+13888 -9077 E0102; Adobe-Japan1; CID+20231 -9077 E0103; Adobe-Japan1; CID+20232 -9077 E0104; Hanyo-Denshi; JA3311 -9077 E0104; Moji_Joho; MJ026140 -9077 E0105; Hanyo-Denshi; KS444060 -9077 E0105; Moji_Joho; MJ026142 -9077 E0106; Hanyo-Denshi; JTBD34 -9077 E0106; Moji_Joho; MJ026144 -9077 E0107; Hanyo-Denshi; IB0420 -9077 E0107; Moji_Joho; MJ026143 -9077 E0108; Hanyo-Denshi; IB0989 -9077 E0108; Moji_Joho; MJ026141 -9077 E0109; Hanyo-Denshi; KS443850 -9077 E0109; Moji_Joho; MJ058865 -9077 E010A; Moji_Joho; MJ026145 -9078 E0100; Adobe-Japan1; CID+2732 -9078 E0101; Adobe-Japan1; CID+13887 -9078 E0102; Hanyo-Denshi; JA3310 -9078 E0102; Moji_Joho; MJ026146 -9078 E0103; Hanyo-Denshi; IB0992 -9078 E0103; Moji_Joho; MJ026147 -9078 E0104; Hanyo-Denshi; IB0423 -9078 E0104; Moji_Joho; MJ026148 -9079 E0100; Adobe-Japan1; CID+19893 -9079 E0101; Hanyo-Denshi; JB6570 -9079 E0101; Moji_Joho; MJ026150 -9079 E0102; Hanyo-Denshi; JTBD22 -9079 E0102; Moji_Joho; MJ026149 -907A E0100; Adobe-Japan1; CID+1192 -907A E0101; Adobe-Japan1; CID+13642 -907A E0102; Hanyo-Denshi; JA1668 -907A E0102; Moji_Joho; MJ026151 -907A E0103; Hanyo-Denshi; JTBD35 -907A E0103; Moji_Joho; MJ026152 -907B E0100; Hanyo-Denshi; IB0994 -907B E0100; Moji_Joho; MJ026153 -907B E0101; Hanyo-Denshi; IP907B -907B E0101; Moji_Joho; MJ026154 -907C E0100; Adobe-Japan1; CID+3987 -907C E0101; Adobe-Japan1; CID+7808 -907C E0102; Hanyo-Denshi; JA4643 -907C E0102; Moji_Joho; MJ026155 -907C E0103; Hanyo-Denshi; FT1936 -907C E0103; Moji_Joho; MJ026156 -907D E0100; Adobe-Japan1; CID+6926 -907D E0101; Hanyo-Denshi; JA7817 -907D E0101; Moji_Joho; MJ026158 -907D E0102; Hanyo-Denshi; KS444600 -907D E0102; Moji_Joho; MJ026157 -907D E0103; Hanyo-Denshi; IB0426 -907D E0103; Moji_Joho; MJ026159 -907D E0104; Moji_Joho; MJ026160 -907D E0105; Moji_Joho; MJ026161 -907F E0100; Adobe-Japan1; CID+3462 -907F E0101; Adobe-Japan1; CID+13991 -907F E0102; Hanyo-Denshi; JA4082 -907F E0102; Moji_Joho; MJ026163 -907F E0103; Hanyo-Denshi; JTBD56 -907F E0103; Moji_Joho; MJ026164 -9080 E0100; Adobe-Japan1; CID+6928 -9080 E0101; Hanyo-Denshi; JA7819 -9080 E0101; Moji_Joho; MJ026166 -9080 E0102; Hanyo-Denshi; FT2630S -9080 E0102; Moji_Joho; MJ026165 -9080 E0103; Moji_Joho; MJ026167 -9081 E0100; Adobe-Japan1; CID+6927 -9081 E0101; Adobe-Japan1; CID+14234 -9081 E0102; Hanyo-Denshi; JA7818 -9081 E0102; Moji_Joho; MJ026169 -9081 E0103; Hanyo-Denshi; KS445060 -9081 E0103; Moji_Joho; MJ026171 -9081 E0104; Hanyo-Denshi; JTBD53 -9081 E0104; Moji_Joho; MJ026170 -9081 E0105; Hanyo-Denshi; FT2629 -9081 E0105; Moji_Joho; MJ026168 -9082 E0100; Adobe-Japan1; CID+6925 -9082 E0101; Hanyo-Denshi; JA7816 -9082 E0101; Moji_Joho; MJ026173 -9082 E0102; Hanyo-Denshi; FT2627 -9082 E0102; Moji_Joho; MJ026172 -9083 E0100; Adobe-Japan1; CID+5943 -9083 E0101; Adobe-Japan1; CID+14172 -9083 E0102; Hanyo-Denshi; JA6768 -9083 E0102; Moji_Joho; MJ026176 -9083 E0103; Hanyo-Denshi; IB1005S -9083 E0103; Moji_Joho; MJ026174 -9083 E0104; Hanyo-Denshi; IB0428S -9083 E0104; Moji_Joho; MJ026179 -9083 E0105; Hanyo-Denshi; FT2387S -9083 E0105; Moji_Joho; MJ026178 -9083 E0106; Hanyo-Denshi; KS287330 -9083 E0107; Moji_Joho; MJ026175 -9083 E0108; Moji_Joho; MJ026177 -9084 E0100; Adobe-Japan1; CID+1552 -9084 E0101; Adobe-Japan1; CID+13692 -9084 E0102; Hanyo-Denshi; JA2052 -9084 E0102; Moji_Joho; MJ026180 -9084 E0103; Hanyo-Denshi; JTBD57 -9084 E0103; Moji_Joho; MJ026181 -9084 E0104; Hanyo-Denshi; KS444050 -9084 E0104; Moji_Joho; MJ058868 -9085 E0100; Adobe-Japan1; CID+18775 -9085 E0101; Hanyo-Denshi; JB6571 -9085 E0101; Moji_Joho; MJ026183 -9085 E0102; Hanyo-Denshi; IB1004 -9085 E0102; Moji_Joho; MJ026182 -9087 E0100; Adobe-Japan1; CID+6893 -9087 E0101; Adobe-Japan1; CID+14228 -9087 E0102; Hanyo-Denshi; JA7778 -9087 E0102; Moji_Joho; MJ026186 -9087 E0103; Hanyo-Denshi; FT2589 -9087 E0103; Moji_Joho; MJ026187 -9087 E0104; Moji_Joho; MJ026185 -9088 E0100; Adobe-Japan1; CID+15192 -9088 E0101; Hanyo-Denshi; JB6572 -9088 E0101; Moji_Joho; MJ026189 -9088 E0102; Hanyo-Denshi; IB1007 -9088 E0102; Moji_Joho; MJ026188 -9089 E0100; Adobe-Japan1; CID+6930 -9089 E0101; Adobe-Japan1; CID+13407 -9089 E0102; Adobe-Japan1; CID+14241 -9089 E0103; Adobe-Japan1; CID+14242 -9089 E0104; Adobe-Japan1; CID+14243 -9089 E0105; Adobe-Japan1; CID+14244 -9089 E0106; Adobe-Japan1; CID+14245 -9089 E0107; Adobe-Japan1; CID+14246 -9089 E0108; Adobe-Japan1; CID+14247 -9089 E0109; Adobe-Japan1; CID+14248 -9089 E010A; Adobe-Japan1; CID+14249 -9089 E010B; Adobe-Japan1; CID+14250 -9089 E010C; Adobe-Japan1; CID+14251 -9089 E010D; Adobe-Japan1; CID+14252 -9089 E010E; Adobe-Japan1; CID+20233 -9089 E010F; Hanyo-Denshi; JA7821 -9089 E010F; Moji_Joho; MJ026190 -9089 E0110; Hanyo-Denshi; JTBD69 -9089 E0110; Moji_Joho; MJ060248 -9089 E0111; Hanyo-Denshi; JTBD38 -9089 E0111; Moji_Joho; MJ060239 -9089 E0112; Hanyo-Denshi; JTBD2D -9089 E0112; Moji_Joho; MJ060238 -9089 E0113; Hanyo-Denshi; JTBD2C -9089 E0113; Moji_Joho; MJ060237 -9089 E0114; Hanyo-Denshi; JTBD2A -9089 E0114; Moji_Joho; MJ060235 -9089 E0115; Hanyo-Denshi; JTBD29 -9089 E0115; Moji_Joho; MJ060234 -9089 E0116; Hanyo-Denshi; JTBD27 -9089 E0116; Moji_Joho; MJ058866 -9089 E0117; Hanyo-Denshi; JTBD65 -9089 E0117; Moji_Joho; MJ026197 -9089 E0118; Hanyo-Denshi; JTBD2BS -9089 E0118; Moji_Joho; MJ060236 -9089 E0119; Hanyo-Denshi; JTBD47 -9089 E0119; Moji_Joho; MJ026191 -9089 E011A; Hanyo-Denshi; FT2632 -9089 E011A; Moji_Joho; MJ026194 -9089 E011B; Hanyo-Denshi; JTBD49 -9089 E011B; Moji_Joho; MJ026192 -9089 E011C; Hanyo-Denshi; JTBD4CS -9089 E011C; Moji_Joho; MJ026195 -9089 E011D; Hanyo-Denshi; JTBD64 -9089 E011D; Moji_Joho; MJ026196 -9089 E011E; Hanyo-Denshi; TK01090330 -9089 E011F; Moji_Joho; MJ026193 -908A E0100; Adobe-Japan1; CID+6929 -908A E0101; Adobe-Japan1; CID+14235 -908A E0102; Adobe-Japan1; CID+14236 -908A E0103; Adobe-Japan1; CID+14237 -908A E0104; Adobe-Japan1; CID+14238 -908A E0105; Adobe-Japan1; CID+14239 -908A E0106; Adobe-Japan1; CID+14240 -908A E0107; Adobe-Japan1; CID+20234 -908A E0108; Hanyo-Denshi; JA7820 -908A E0108; Moji_Joho; MJ026200 -908A E0109; Hanyo-Denshi; JTBD45 -908A E0109; Moji_Joho; MJ060240 -908A E010A; Hanyo-Denshi; JTBD62 -908A E010A; Moji_Joho; MJ026205 -908A E010B; Hanyo-Denshi; JTBD61 -908A E010B; Moji_Joho; MJ026204 -908A E010C; Hanyo-Denshi; JTBD60 -908A E010C; Moji_Joho; MJ026203 -908A E010D; Hanyo-Denshi; JTBD5F -908A E010D; Moji_Joho; MJ026202 -908A E010E; Hanyo-Denshi; JTBD5E -908A E010E; Moji_Joho; MJ026201 -908A E010F; Hanyo-Denshi; KS445320S -908A E010F; Moji_Joho; MJ026199 -908A E0110; Hanyo-Denshi; JTBD6A -908A E0110; Moji_Joho; MJ026206 -908A E0111; Hanyo-Denshi; JTBD46 -908A E0111; Moji_Joho; MJ058870 -908A E0112; Hanyo-Denshi; JTC0D6 -908A E0112; Moji_Joho; MJ026207 -908A E0113; Hanyo-Denshi; TK01090290 -908A E0114; Hanyo-Denshi; TK01090430 -908B E0100; Adobe-Japan1; CID+19894 -908B E0101; Hanyo-Denshi; JB6573 -908B E0101; Moji_Joho; MJ026210 -908B E0102; Hanyo-Denshi; IB1009 -908B E0102; Moji_Joho; MJ026209 -908C E0100; Adobe-Japan1; CID+18776 -908C E0101; Hanyo-Denshi; JB6574 -908C E0101; Moji_Joho; MJ026212 -908C E0102; Hanyo-Denshi; IB1010 -908C E0102; Moji_Joho; MJ026211 -908D E0100; Hanyo-Denshi; IB1011 -908D E0100; Moji_Joho; MJ026213 -908D E0101; Hanyo-Denshi; IP908D -908D E0101; Moji_Joho; MJ026214 -908D E0102; Moji_Joho; MJ058874 -908E E0100; Adobe-Japan1; CID+22677 -908E E0101; Hanyo-Denshi; JB6575 -908E E0101; Moji_Joho; MJ026216 -908E E0102; Hanyo-Denshi; IB1014 -908E E0102; Moji_Joho; MJ026215 -908F E0100; Adobe-Japan1; CID+6931 -908F E0101; Hanyo-Denshi; JA7822 -908F E0101; Moji_Joho; MJ026218 -908F E0102; Hanyo-Denshi; FT2633 -908F E0102; Moji_Joho; MJ026217 -9090 E0100; Adobe-Japan1; CID+18777 -9090 E0101; Hanyo-Denshi; JB6576 -9090 E0101; Moji_Joho; MJ026220 -9090 E0102; Hanyo-Denshi; IB1018 -9090 E0102; Moji_Joho; MJ026219 -9091 E0100; Adobe-Japan1; CID+3874 -9095 E0100; Adobe-Japan1; CID+15193 -9097 E0100; Adobe-Japan1; CID+17151 -9098 E0100; Adobe-Japan1; CID+19895 -9099 E0100; Adobe-Japan1; CID+15194 -9099 E0101; Hanyo-Denshi; JB6580 -9099 E0101; Moji_Joho; MJ026229 -9099 E0102; Hanyo-Denshi; IB3033 -9099 E0102; Moji_Joho; MJ026230 -909B E0100; Adobe-Japan1; CID+15195 -90A0 E0100; Adobe-Japan1; CID+19896 -90A1 E0100; Adobe-Japan1; CID+18778 -90A2 E0100; Adobe-Japan1; CID+15196 -90A3 E0100; Adobe-Japan1; CID+3257 -90A3 E0101; Adobe-Japan1; CID+7765 -90A3 E0102; Hanyo-Denshi; JA3865 -90A3 E0102; Moji_Joho; MJ026239 -90A3 E0103; Hanyo-Denshi; FT1885 -90A3 E0103; Moji_Joho; MJ026238 -90A5 E0100; Adobe-Japan1; CID+22678 -90A6 E0100; Adobe-Japan1; CID+3676 -90A6 E0101; Adobe-Japan1; CID+14027 -90A6 E0102; Adobe-Japan1; CID+14028 -90A6 E0103; Hanyo-Denshi; JA4314 -90A6 E0103; Moji_Joho; MJ026242 -90A6 E0104; Hanyo-Denshi; JTBD85 -90A6 E0104; Moji_Joho; MJ026246 -90A6 E0105; Hanyo-Denshi; JTBD86 -90A6 E0105; Moji_Joho; MJ026244 -90A6 E0106; Hanyo-Denshi; JTBD83 -90A6 E0106; Moji_Joho; MJ026243 -90A6 E0107; Hanyo-Denshi; TK01090640 -90A6 E0108; Moji_Joho; MJ026245 -90A8 E0100; Adobe-Japan1; CID+6932 -90A8 E0101; Adobe-Japan1; CID+20235 -90A8 E0102; Hanyo-Denshi; JA7823 -90A8 E0102; Moji_Joho; MJ026249 -90A8 E0103; Hanyo-Denshi; FT2634 -90A8 E0103; Moji_Joho; MJ026250 -90A8 E0104; Hanyo-Denshi; TK01090660 -90A8 E0105; Hanyo-Denshi; TK01090690 -90AA E0100; Adobe-Japan1; CID+2309 -90AA E0101; Adobe-Japan1; CID+13454 -90AA E0102; Adobe-Japan1; CID+13806 -90AA E0103; Hanyo-Denshi; JA2857 -90AA E0103; Moji_Joho; MJ026255 -90AA E0104; Hanyo-Denshi; KS446560 -90AA E0104; Moji_Joho; MJ026254 -90AA E0105; Moji_Joho; MJ026256 -90AB E0100; Hanyo-Denshi; IP90AB -90AB E0100; Moji_Joho; MJ026257 -90AB E0101; Hanyo-Denshi; JTBD87 -90AB E0101; Moji_Joho; MJ026258 -90AB E0102; Hanyo-Denshi; TK01090980 -90AB E0103; Hanyo-Denshi; TK01091000 -90AF E0100; Adobe-Japan1; CID+6933 -90B0 E0100; Adobe-Japan1; CID+18780 -90B1 E0100; Adobe-Japan1; CID+6934 -90B2 E0100; Adobe-Japan1; CID+19897 -90B3 E0100; Adobe-Japan1; CID+17152 -90B4 E0100; Adobe-Japan1; CID+15197 -90B4 E0101; Moji_Joho; MJ026268 -90B4 E0102; Moji_Joho; MJ026269 -90B5 E0100; Adobe-Japan1; CID+6935 -90B6 E0100; Adobe-Japan1; CID+18781 -90B8 E0100; Adobe-Japan1; CID+3099 -90B8 E0101; Hanyo-Denshi; JA3701 -90B8 E0102; Hanyo-Denshi; TK01090760 -90BD E0100; Adobe-Japan1; CID+19898 -90BE E0100; Adobe-Japan1; CID+17153 -90C1 E0100; Adobe-Japan1; CID+1198 -90C3 E0100; Adobe-Japan1; CID+18782 -90C4 E0100; Adobe-Japan1; CID+17154 -90C5 E0100; Adobe-Japan1; CID+17155 -90C7 E0100; Adobe-Japan1; CID+17156 -90C8 E0100; Adobe-Japan1; CID+18783 -90C9 E0100; Adobe-Japan1; CID+19899 -90CA E0100; Adobe-Japan1; CID+2027 -90CC E0100; Adobe-Japan1; CID+22679 -90CE E0100; Adobe-Japan1; CID+4064 -90D2 E0100; Adobe-Japan1; CID+22684 -90D2 E0101; Hanyo-Denshi; JB6613 -90D2 E0101; Moji_Joho; MJ026296 -90D2 E0102; Hanyo-Denshi; IB3038 -90D2 E0102; Moji_Joho; MJ026297 -90D5 E0100; Adobe-Japan1; CID+22680 -90D7 E0100; Adobe-Japan1; CID+15198 -90D8 E0100; Adobe-Japan1; CID+22681 -90D9 E0100; Adobe-Japan1; CID+22682 -90DB E0100; Adobe-Japan1; CID+6939 -90DB E0101; Hanyo-Denshi; JA7830 -90DB E0101; Moji_Joho; MJ026305 -90DB E0102; Hanyo-Denshi; FT2636 -90DB E0102; Moji_Joho; MJ026306 -90DC E0100; Adobe-Japan1; CID+18785 -90DD E0100; Adobe-Japan1; CID+15199 -90DE E0100; Adobe-Japan1; CID+8635 -90DF E0100; Adobe-Japan1; CID+18786 -90E1 E0100; Adobe-Japan1; CID+1802 -90E2 E0100; Adobe-Japan1; CID+6936 -90E2 E0101; Hanyo-Denshi; JA7827 -90E2 E0101; Moji_Joho; MJ026313 -90E2 E0102; Hanyo-Denshi; FT2635 -90E2 E0102; Moji_Joho; MJ026314 -90E2 E0103; Moji_Joho; MJ026315 -90E4 E0100; Adobe-Japan1; CID+6937 -90E4 E0101; Hanyo-Denshi; JA7828 -90E4 E0101; Moji_Joho; MJ026317 -90E4 E0102; Hanyo-Denshi; JTBD92 -90E4 E0102; Moji_Joho; MJ026318 -90E5 E0100; Adobe-Japan1; CID+22683 -90E8 E0100; Adobe-Japan1; CID+3558 -90EB E0100; Adobe-Japan1; CID+18791 -90ED E0100; Adobe-Japan1; CID+1458 -90EF E0100; Adobe-Japan1; CID+17157 -90F0 E0100; Adobe-Japan1; CID+19900 -90F1 E0100; Hanyo-Denshi; IP90F1 -90F1 E0100; Moji_Joho; MJ026330 -90F1 E0101; Hanyo-Denshi; KS447420 -90F1 E0101; Moji_Joho; MJ026329 -90F2 E0100; Adobe-Japan1; CID+18789 -90F4 E0100; Adobe-Japan1; CID+15200 -90F5 E0100; Adobe-Japan1; CID+3875 -90F6 E0100; Adobe-Japan1; CID+18788 -90F7 E0100; Adobe-Japan1; CID+1719 -90F7 E0101; Adobe-Japan1; CID+13725 -90FD E0100; Adobe-Japan1; CID+8636 -90FD E0101; Adobe-Japan1; CID+3150 -90FD E0102; Hanyo-Denshi; JA3752 -90FD E0103; Hanyo-Denshi; JC9274 -90FE E0100; Adobe-Japan1; CID+18792 -90FF E0100; Adobe-Japan1; CID+18793 -9100 E0100; Adobe-Japan1; CID+18790 -9100 E0101; Hanyo-Denshi; JB6621 -9100 E0101; Moji_Joho; MJ026344 -9100 E0102; Hanyo-Denshi; KS448550 -9100 E0102; Moji_Joho; MJ026345 -9102 E0100; Adobe-Japan1; CID+6940 -9102 E0101; Hanyo-Denshi; JA7831 -9102 E0101; Moji_Joho; MJ026347 -9102 E0102; Hanyo-Denshi; KS448800 -9102 E0102; Moji_Joho; MJ026348 -9104 E0100; Adobe-Japan1; CID+18794 -9105 E0100; Adobe-Japan1; CID+19901 -9106 E0100; Adobe-Japan1; CID+18795 -9108 E0100; Adobe-Japan1; CID+22685 -910D E0100; Adobe-Japan1; CID+22686 -9110 E0100; Adobe-Japan1; CID+22687 -9112 E0100; Adobe-Japan1; CID+6941 -9114 E0100; Adobe-Japan1; CID+17158 -9115 E0100; Adobe-Japan1; CID+8637 -9115 E0101; Hanyo-Denshi; JC9276 -9115 E0101; Moji_Joho; MJ026367 -9115 E0102; Hanyo-Denshi; IP9115 -9115 E0102; Moji_Joho; MJ026366 -9115 E0103; Hanyo-Denshi; JTBD9A -9115 E0103; Moji_Joho; MJ026369 -9115 E0104; Hanyo-Denshi; TK01091140 -9115 E0105; Moji_Joho; MJ026368 -9116 E0100; Adobe-Japan1; CID+17159 -9117 E0100; Adobe-Japan1; CID+15201 -9118 E0100; Adobe-Japan1; CID+18796 -9119 E0100; Adobe-Japan1; CID+6942 -9119 E0101; Hanyo-Denshi; JA7833 -9119 E0101; Moji_Joho; MJ026374 -9119 E0102; Hanyo-Denshi; KS450220 -9119 E0102; Moji_Joho; MJ058878 -911A E0100; Adobe-Japan1; CID+22688 -911A E0101; Hanyo-Denshi; JB6632 -911A E0101; Moji_Joho; MJ026375 -911A E0102; Hanyo-Denshi; KS449460 -911A E0102; Moji_Joho; MJ026376 -911B E0100; Hanyo-Denshi; IP911B -911B E0100; Moji_Joho; MJ026377 -911B E0101; Hanyo-Denshi; KS450560 -911B E0101; Moji_Joho; MJ026378 -911C E0100; Adobe-Japan1; CID+15202 -911E E0100; Adobe-Japan1; CID+18797 -911E E0101; Hanyo-Denshi; JB6634 -911E E0102; Hanyo-Denshi; TK01091200 -9120 E0100; Adobe-Japan1; CID+22689 -9122 E0100; Adobe-Japan1; CID+17160 -9123 E0100; Adobe-Japan1; CID+17161 -9123 E0101; Hanyo-Denshi; JB6638 -9123 E0101; Moji_Joho; MJ026387 -9123 E0102; Hanyo-Denshi; IB3047 -9123 E0102; Moji_Joho; MJ026388 -9125 E0100; Adobe-Japan1; CID+19902 -9127 E0100; Adobe-Japan1; CID+8638 -9129 E0100; Adobe-Japan1; CID+22690 -912D E0100; Adobe-Japan1; CID+3100 -912D E0101; Adobe-Japan1; CID+7748 -912D E0102; Hanyo-Denshi; JA3702 -912D E0102; Moji_Joho; MJ026399 -912D E0103; Hanyo-Denshi; FT1868 -912D E0103; Moji_Joho; MJ026398 -912E E0100; Adobe-Japan1; CID+22691 -912E E0101; Hanyo-Denshi; JB6641 -912E E0101; Moji_Joho; MJ026400 -912E E0102; Hanyo-Denshi; KS450230 -912E E0102; Moji_Joho; MJ026401 -912F E0100; Adobe-Japan1; CID+17162 -9130 E0100; Adobe-Japan1; CID+6944 -9130 E0101; Adobe-Japan1; CID+13609 -9130 E0102; Hanyo-Denshi; JA7835 -9130 E0102; Moji_Joho; MJ026403 -9130 E0103; Hanyo-Denshi; FT2637S -9130 E0103; Moji_Joho; MJ026404 -9130 E0104; Moji_Joho; MJ026405 -9131 E0100; Adobe-Japan1; CID+15203 -9132 E0100; Adobe-Japan1; CID+6943 -9134 E0100; Adobe-Japan1; CID+17163 -9136 E0100; Adobe-Japan1; CID+22692 -9137 E0100; Adobe-Japan1; CID+18798 -9137 E0101; Hanyo-Denshi; JB6646 -9137 E0102; Hanyo-Denshi; JTBDA0 -9139 E0100; Adobe-Japan1; CID+18799 -913A E0100; Adobe-Japan1; CID+15204 -913C E0100; Adobe-Japan1; CID+22693 -913D E0100; Adobe-Japan1; CID+15205 -913D E0101; Hanyo-Denshi; JB6650 -913D E0101; Moji_Joho; MJ026419 -913D E0102; Hanyo-Denshi; JTBDA1 -913D E0102; Moji_Joho; MJ026420 -9143 E0100; Adobe-Japan1; CID+22694 -9145 E0100; Hanyo-Denshi; IP9145 -9145 E0100; Moji_Joho; MJ026427 -9145 E0101; Hanyo-Denshi; KS451220 -9145 E0101; Moji_Joho; MJ026428 -9146 E0100; Adobe-Japan1; CID+18800 -9147 E0100; Adobe-Japan1; CID+18801 -9148 E0100; Adobe-Japan1; CID+15206 -9149 E0100; Adobe-Japan1; CID+3243 -914A E0100; Adobe-Japan1; CID+6945 -914B E0100; Adobe-Japan1; CID+2368 -914B E0101; Adobe-Japan1; CID+7698 -914B E0102; Hanyo-Denshi; JA2922 -914B E0102; Moji_Joho; MJ026435 -914B E0103; Hanyo-Denshi; FT1819 -914B E0103; Moji_Joho; MJ026434 -914B E0104; Hanyo-Denshi; TK01091280 -914C E0100; Adobe-Japan1; CID+2316 -914C E0101; Adobe-Japan1; CID+13810 -914C E0102; Hanyo-Denshi; JA2864 -914C E0102; Moji_Joho; MJ026438 -914C E0103; Hanyo-Denshi; JTBDA3 -914C E0103; Moji_Joho; MJ026437 -914D E0100; Adobe-Japan1; CID+3345 -914D E0101; Adobe-Japan1; CID+20236 -914D E0102; Hanyo-Denshi; JA3959 -914D E0103; Hanyo-Denshi; KS451590 -914D E0103; Moji_Joho; MJ026440 -914D E0104; Hanyo-Denshi; JTBDA4 -914D E0104; Moji_Joho; MJ026442 -914D E0105; Moji_Joho; MJ026439 -914D E0106; Moji_Joho; MJ026441 -914E E0100; Adobe-Japan1; CID+2991 -914F E0100; Adobe-Japan1; CID+22695 -9152 E0100; Adobe-Japan1; CID+2334 -9152 E0101; Hanyo-Denshi; JA2882 -9152 E0101; Moji_Joho; MJ026447 -9152 E0102; Hanyo-Denshi; JTB431 -9152 E0102; Moji_Joho; MJ026448 -9152 E0103; Hanyo-Denshi; TK01049410 -9153 E0100; Adobe-Japan1; CID+22696 -9154 E0100; Adobe-Japan1; CID+2610 -9156 E0100; Adobe-Japan1; CID+6946 -9156 E0101; Adobe-Japan1; CID+13610 -9157 E0100; Adobe-Japan1; CID+18802 -9158 E0100; Adobe-Japan1; CID+6947 -9158 E0101; Adobe-Japan1; CID+13611 -9159 E0100; Adobe-Japan1; CID+18803 -915A E0100; Adobe-Japan1; CID+19903 -915B E0100; Adobe-Japan1; CID+15207 -9161 E0100; Adobe-Japan1; CID+15208 -9162 E0100; Adobe-Japan1; CID+2595 -9162 E0101; Hanyo-Denshi; JA3161 -9162 E0101; Moji_Joho; MJ026462 -9162 E0102; Hanyo-Denshi; JTBDA6 -9162 E0102; Moji_Joho; MJ026463 -9163 E0100; Adobe-Japan1; CID+6948 -9164 E0100; Adobe-Japan1; CID+15209 -9165 E0100; Adobe-Japan1; CID+6949 -9165 E0101; Adobe-Japan1; CID+13612 -9167 E0100; Adobe-Japan1; CID+19904 -9169 E0100; Adobe-Japan1; CID+6950 -916A E0100; Adobe-Japan1; CID+3929 -916A E0101; Hanyo-Denshi; JA4579 -916A E0101; Moji_Joho; MJ026470 -916A E0102; Hanyo-Denshi; JTBDA7 -916A E0102; Moji_Joho; MJ026471 -916C E0100; Adobe-Japan1; CID+2369 -916C E0101; Hanyo-Denshi; JA2923 -916C E0101; Moji_Joho; MJ026473 -916C E0102; Hanyo-Denshi; JTBDA8 -916C E0102; Moji_Joho; MJ026474 -916D E0100; Adobe-Japan1; CID+22697 -9172 E0100; Adobe-Japan1; CID+6952 -9172 E0101; Adobe-Japan1; CID+13614 -9172 E0102; Hanyo-Denshi; JA7843 -9172 E0102; Moji_Joho; MJ026478 -9172 E0103; Hanyo-Denshi; FT2638 -9172 E0103; Moji_Joho; MJ026479 -9173 E0100; Adobe-Japan1; CID+6951 -9173 E0101; Adobe-Japan1; CID+13613 -9174 E0100; Adobe-Japan1; CID+18804 -9175 E0100; Adobe-Japan1; CID+2028 -9175 E0101; Hanyo-Denshi; JA2558 -9175 E0101; Moji_Joho; MJ026482 -9175 E0102; Hanyo-Denshi; JTBDA9 -9175 E0102; Moji_Joho; MJ026483 -9177 E0100; Adobe-Japan1; CID+2053 -9177 E0101; Adobe-Japan1; CID+13776 -9177 E0102; Hanyo-Denshi; JA2583 -9177 E0102; Moji_Joho; MJ026486 -9177 E0103; Hanyo-Denshi; JTBDAA -9177 E0103; Moji_Joho; MJ026485 -9178 E0100; Adobe-Japan1; CID+2190 -9178 E0101; Hanyo-Denshi; JA2732 -9178 E0101; Moji_Joho; MJ026488 -9178 E0102; Hanyo-Denshi; KS452620 -9178 E0102; Moji_Joho; MJ026487 -9178 E0103; Hanyo-Denshi; JTBDAB -9178 E0103; Moji_Joho; MJ026489 -9179 E0100; Adobe-Japan1; CID+18805 -917A E0100; Adobe-Japan1; CID+19905 -917B E0100; Adobe-Japan1; CID+22698 -917B E0101; Hanyo-Denshi; JB6667 -917B E0102; Hanyo-Denshi; TK01091330 -9181 E0100; Adobe-Japan1; CID+22699 -9181 E0101; Hanyo-Denshi; JB6668 -9181 E0102; Hanyo-Denshi; TK01030100 -9181 E0103; Hanyo-Denshi; TK01091360 -9182 E0100; Adobe-Japan1; CID+6955 -9183 E0100; Adobe-Japan1; CID+17164 -9185 E0100; Adobe-Japan1; CID+18806 -9186 E0100; Adobe-Japan1; CID+22700 -9187 E0100; Adobe-Japan1; CID+2416 -9189 E0100; Adobe-Japan1; CID+6954 -918A E0100; Adobe-Japan1; CID+19906 -918B E0100; Adobe-Japan1; CID+6953 -918D E0100; Adobe-Japan1; CID+2889 -918E E0100; Adobe-Japan1; CID+15210 -9190 E0100; Adobe-Japan1; CID+1955 -9191 E0100; Adobe-Japan1; CID+19907 -9192 E0100; Adobe-Japan1; CID+2663 -9193 E0100; Adobe-Japan1; CID+22701 -9194 E0100; Adobe-Japan1; CID+22702 -9195 E0100; Adobe-Japan1; CID+19908 -9195 E0101; Hanyo-Denshi; JB6677 -9195 E0102; Hanyo-Denshi; TK01091370 -9197 E0100; Adobe-Japan1; CID+3396 -9198 E0100; Adobe-Japan1; CID+22703 -919A E0100; Hanyo-Denshi; IB1021 -919A E0100; Moji_Joho; MJ026523 -919A E0101; Hanyo-Denshi; IP919A -919A E0101; Moji_Joho; MJ026524 -919C E0100; Adobe-Japan1; CID+2371 -919C E0101; Hanyo-Denshi; JA2925 -919C E0101; Moji_Joho; MJ026527 -919C E0102; Hanyo-Denshi; JTBDB2 -919C E0102; Moji_Joho; MJ026526 -919E E0100; Adobe-Japan1; CID+15211 -91A1 E0100; Adobe-Japan1; CID+22704 -91A2 E0100; Adobe-Japan1; CID+6956 -91A2 E0101; Adobe-Japan1; CID+13615 -91A4 E0100; Adobe-Japan1; CID+2503 -91A4 E0101; Hanyo-Denshi; JA3063 -91A4 E0101; Moji_Joho; MJ026535 -91A4 E0102; Hanyo-Denshi; JTBDB0 -91A4 E0102; Moji_Joho; MJ026536 -91A4 E0103; Hanyo-Denshi; TK01091380 -91A6 E0100; Adobe-Japan1; CID+22705 -91A7 E0100; Hanyo-Denshi; IP91A7 -91A7 E0101; Hanyo-Denshi; KS453940 -91A7 E0101; Moji_Joho; MJ026540 -91A7 E0102; Moji_Joho; MJ026541 -91A8 E0100; Adobe-Japan1; CID+15212 -91A8 E0101; Hanyo-Denshi; JB6682 -91A8 E0101; Moji_Joho; MJ026542 -91A8 E0102; Hanyo-Denshi; KS454160 -91A8 E0102; Moji_Joho; MJ026543 -91AA E0100; Adobe-Japan1; CID+6959 -91AA E0101; Adobe-Japan1; CID+13617 -91AA E0102; Hanyo-Denshi; JA7850 -91AA E0102; Moji_Joho; MJ026545 -91AA E0103; Hanyo-Denshi; FT2639 -91AA E0103; Moji_Joho; MJ026546 -91AB E0100; Adobe-Japan1; CID+6957 -91AB E0101; Hanyo-Denshi; JA7848 -91AB E0101; Moji_Joho; MJ026547 -91AB E0102; Hanyo-Denshi; KS454140 -91AB E0102; Moji_Joho; MJ026548 -91AC E0100; Adobe-Japan1; CID+7707 -91AC E0101; Hanyo-Denshi; JB6683 -91AC E0101; Moji_Joho; MJ026549 -91AC E0102; Hanyo-Denshi; JTBDB1 -91AC E0102; Moji_Joho; MJ026550 -91AD E0100; Adobe-Japan1; CID+15213 -91AE E0100; Adobe-Japan1; CID+15214 -91AF E0100; Adobe-Japan1; CID+6958 -91AF E0101; Adobe-Japan1; CID+13616 -91B0 E0100; Adobe-Japan1; CID+19909 -91B0 E0101; Hanyo-Denshi; JB6686 -91B0 E0101; Moji_Joho; MJ026554 -91B0 E0102; Hanyo-Denshi; KS454460 -91B0 E0102; Moji_Joho; MJ026555 -91B1 E0100; Adobe-Japan1; CID+7777 -91B1 E0101; Adobe-Japan1; CID+13983 -91B2 E0100; Adobe-Japan1; CID+15215 -91B3 E0100; Adobe-Japan1; CID+18807 -91B4 E0100; Adobe-Japan1; CID+6961 -91B4 E0101; Adobe-Japan1; CID+13618 -91B5 E0100; Adobe-Japan1; CID+6960 -91B5 E0101; Hanyo-Denshi; JA7851 -91B5 E0101; Moji_Joho; MJ026560 -91B5 E0102; Hanyo-Denshi; FT2640 -91B5 E0102; Moji_Joho; MJ026561 -91B5 E0103; Moji_Joho; MJ026562 -91B6 E0100; Adobe-Japan1; CID+18808 -91B7 E0100; Hanyo-Denshi; IP91B7 -91B7 E0100; Moji_Joho; MJ026564 -91B7 E0101; Hanyo-Denshi; KS454660 -91B7 E0101; Moji_Joho; MJ026565 -91B8 E0100; Adobe-Japan1; CID+2530 -91BA E0100; Adobe-Japan1; CID+6962 -91BA E0101; Adobe-Japan1; CID+13619 -91BA E0102; Hanyo-Denshi; JA7853 -91BA E0102; Moji_Joho; MJ026568 -91BA E0103; Hanyo-Denshi; FT2641 -91BA E0103; Moji_Joho; MJ026569 -91BB E0100; Adobe-Japan1; CID+19910 -91BC E0100; Adobe-Japan1; CID+15216 -91BD E0100; Adobe-Japan1; CID+19911 -91BF E0100; Adobe-Japan1; CID+22706 -91C0 E0100; Adobe-Japan1; CID+6963 -91C0 E0101; Hanyo-Denshi; JA7854 -91C0 E0102; Hanyo-Denshi; TK01091450 -91C1 E0100; Adobe-Japan1; CID+6964 -91C1 E0101; Adobe-Japan1; CID+7875 -91C1 E0102; Hanyo-Denshi; JA7855 -91C1 E0102; Moji_Joho; MJ026577 -91C1 E0103; Hanyo-Denshi; FT2004 -91C1 E0103; Moji_Joho; MJ026579 -91C1 E0104; Hanyo-Denshi; JTBDB9 -91C1 E0104; Moji_Joho; MJ026580 -91C1 E0105; Moji_Joho; MJ026576 -91C1 E0106; Moji_Joho; MJ026578 -91C2 E0100; Adobe-Japan1; CID+19912 -91C3 E0100; Adobe-Japan1; CID+18809 -91C4 E0100; Adobe-Japan1; CID+18810 -91C5 E0100; Adobe-Japan1; CID+19913 -91C6 E0100; Adobe-Japan1; CID+3428 -91C7 E0100; Adobe-Japan1; CID+2115 -91C7 E0101; Adobe-Japan1; CID+7685 -91C7 E0102; Hanyo-Denshi; JA2651 -91C7 E0102; Moji_Joho; MJ026586 -91C7 E0103; Hanyo-Denshi; FT1807 -91C7 E0103; Moji_Joho; MJ026587 -91C8 E0100; Adobe-Japan1; CID+2317 -91C8 E0101; Hanyo-Denshi; JA2865 -91C8 E0101; Moji_Joho; MJ026588 -91C8 E0102; Hanyo-Denshi; KS455280 -91C8 E0102; Moji_Joho; MJ058893 -91C9 E0100; Adobe-Japan1; CID+6965 -91CB E0100; Adobe-Japan1; CID+6966 -91CB E0101; Hanyo-Denshi; JA7857 -91CB E0101; Moji_Joho; MJ026590 -91CB E0102; Hanyo-Denshi; JTB3D1 -91CB E0102; Moji_Joho; MJ026591 -91CC E0100; Adobe-Japan1; CID+3948 -91CD E0100; Adobe-Japan1; CID+2383 -91CD E0101; Hanyo-Denshi; JA2937 -91CD E0101; Moji_Joho; MJ026593 -91CD E0102; Hanyo-Denshi; JTBDBE -91CD E0102; Moji_Joho; MJ060258 -91CD E0103; Hanyo-Denshi; TK01091480 -91CE E0100; Adobe-Japan1; CID+3834 -91CF E0100; Adobe-Japan1; CID+3988 -91D0 E0100; Adobe-Japan1; CID+6967 -91D1 E0100; Adobe-Japan1; CID+1754 -91D3 E0100; Adobe-Japan1; CID+22707 -91D4 E0100; Adobe-Japan1; CID+22708 -91D6 E0100; Adobe-Japan1; CID+6968 -91D7 E0100; Adobe-Japan1; CID+8640 -91D8 E0100; Adobe-Japan1; CID+3101 -91D9 E0100; Adobe-Japan1; CID+22709 -91DA E0100; Adobe-Japan1; CID+8639 -91DB E0100; Adobe-Japan1; CID+6971 -91DC E0100; Adobe-Japan1; CID+1494 -91DC E0101; Adobe-Japan1; CID+20290 -91DC E0102; Moji_Joho; MJ026607 -91DC E0103; Moji_Joho; MJ026608 -91DD E0100; Adobe-Japan1; CID+2577 -91DE E0100; Adobe-Japan1; CID+8641 -91DF E0100; Adobe-Japan1; CID+6969 -91DF E0101; Hanyo-Denshi; JA7860 -91DF E0101; Moji_Joho; MJ026611 -91DF E0102; Hanyo-Denshi; FT2642 -91DF E0102; Moji_Joho; MJ026612 -91E1 E0100; Adobe-Japan1; CID+6970 -91E3 E0100; Adobe-Japan1; CID+3068 -91E3 E0101; Adobe-Japan1; CID+13941 -91E3 E0102; Hanyo-Denshi; JA3664 -91E3 E0102; Moji_Joho; MJ026617 -91E3 E0103; Hanyo-Denshi; KS455910 -91E3 E0103; Moji_Joho; MJ026616 -91E4 E0100; Adobe-Japan1; CID+8644 -91E5 E0100; Adobe-Japan1; CID+8645 -91E6 E0100; Adobe-Japan1; CID+3715 -91E7 E0100; Adobe-Japan1; CID+1780 -91E9 E0100; Adobe-Japan1; CID+22710 -91E9 E0101; Hanyo-Denshi; JB6712 -91E9 E0101; Moji_Joho; MJ026623 -91E9 E0102; Hanyo-Denshi; JTBDC4 -91E9 E0102; Moji_Joho; MJ026624 -91EA E0100; Adobe-Japan1; CID+22711 -91EB E0100; Hanyo-Denshi; IP91EB -91EB E0100; Moji_Joho; MJ026626 -91EB E0101; Hanyo-Denshi; KS456280 -91EB E0101; Moji_Joho; MJ026627 -91EC E0100; Adobe-Japan1; CID+18813 -91ED E0100; Adobe-Japan1; CID+8642 -91EE E0100; Adobe-Japan1; CID+8643 -91EE E0101; Hanyo-Denshi; JB6716 -91EE E0101; Moji_Joho; MJ026630 -91EE E0102; Hanyo-Denshi; JTBDC6 -91EE E0102; Moji_Joho; MJ026631 -91EE E0103; Hanyo-Denshi; TK01091760 -91EF E0100; Adobe-Japan1; CID+22712 -91EF E0101; Hanyo-Denshi; JB6717 -91EF E0101; Moji_Joho; MJ026632 -91EF E0102; Hanyo-Denshi; KS456290 -91EF E0102; Moji_Joho; MJ026633 -91F0 E0100; Adobe-Japan1; CID+15217 -91F1 E0100; Adobe-Japan1; CID+17165 -91F5 E0100; Adobe-Japan1; CID+6973 -91F5 E0101; Moji_Joho; MJ026639 -91F5 E0102; Moji_Joho; MJ026640 -91F6 E0100; Adobe-Japan1; CID+6974 -91F7 E0100; Adobe-Japan1; CID+15218 -91F9 E0100; Adobe-Japan1; CID+22713 -91FB E0100; Adobe-Japan1; CID+15219 -91FC E0100; Adobe-Japan1; CID+6972 -91FC E0101; Adobe-Japan1; CID+15404 -91FC E0102; Hanyo-Denshi; JA7863 -91FC E0103; Hanyo-Denshi; IB3058 -91FC E0103; Moji_Joho; MJ026648 -91FC E0104; Moji_Joho; MJ026647 -91FC E0105; Moji_Joho; MJ026649 -91FD E0100; Adobe-Japan1; CID+22714 -91FE E0100; Hanyo-Denshi; JT91FE -91FE E0101; Hanyo-Denshi; TK01092180 -91FF E0100; Adobe-Japan1; CID+6976 -9200 E0100; Adobe-Japan1; CID+19914 -9201 E0100; Adobe-Japan1; CID+18814 -9204 E0100; Adobe-Japan1; CID+22715 -9205 E0100; Adobe-Japan1; CID+22716 -9206 E0100; Adobe-Japan1; CID+8646 -9207 E0100; Adobe-Japan1; CID+15220 -9209 E0100; Adobe-Japan1; CID+19915 -9209 E0101; Hanyo-Denshi; JB6730 -9209 E0102; Hanyo-Denshi; TK01092010 -920A E0100; Adobe-Japan1; CID+8648 -920C E0100; Adobe-Japan1; CID+22717 -920D E0100; Adobe-Japan1; CID+3255 -920D E0101; Hanyo-Denshi; JA3863 -920D E0102; Hanyo-Denshi; TK01091910 -920E E0100; Adobe-Japan1; CID+1441 -9210 E0100; Adobe-Japan1; CID+8647 -9210 E0101; Hanyo-Denshi; JB6733 -9210 E0101; Moji_Joho; MJ026672 -9210 E0102; Hanyo-Denshi; JTBDCE -9210 E0102; Moji_Joho; MJ026673 -9211 E0100; Adobe-Japan1; CID+6980 -9212 E0100; Adobe-Japan1; CID+22718 -9212 E0101; Hanyo-Denshi; JB6734 -9212 E0102; Hanyo-Denshi; TK01092000 -9213 E0100; Adobe-Japan1; CID+22719 -9213 E0101; Hanyo-Denshi; JB6735 -9213 E0101; Moji_Joho; MJ026677 -9213 E0102; Hanyo-Denshi; JTBDCC -9213 E0102; Moji_Joho; MJ026678 -9213 E0103; Hanyo-Denshi; TK01091880 -9214 E0100; Adobe-Japan1; CID+6977 -9215 E0100; Adobe-Japan1; CID+6979 -9216 E0100; Adobe-Japan1; CID+18815 -9217 E0100; Adobe-Japan1; CID+18816 -9218 E0100; Adobe-Japan1; CID+22720 -921C E0100; Adobe-Japan1; CID+22721 -921D E0100; Adobe-Japan1; CID+22722 -921E E0100; Adobe-Japan1; CID+6975 -9223 E0100; Adobe-Japan1; CID+19916 -9224 E0100; Adobe-Japan1; CID+22723 -9225 E0100; Adobe-Japan1; CID+22724 -9226 E0100; Adobe-Japan1; CID+22725 -9227 E0100; Hanyo-Denshi; IP9227 -9227 E0101; Hanyo-Denshi; TK01091920 -9228 E0100; Adobe-Japan1; CID+15221 -9229 E0100; Adobe-Japan1; CID+7050 -9229 E0101; Hanyo-Denshi; JA7947 -9229 E0101; Moji_Joho; MJ026701 -9229 E0102; Hanyo-Denshi; JTBDCF -9229 E0102; Moji_Joho; MJ026702 -922C E0100; Adobe-Japan1; CID+6978 -922E E0100; Adobe-Japan1; CID+22726 -922F E0100; Adobe-Japan1; CID+22727 -9230 E0100; Adobe-Japan1; CID+22728 -9233 E0100; Adobe-Japan1; CID+15222 -9234 E0100; Adobe-Japan1; CID+4019 -9234 E0101; Hanyo-Denshi; JA4675 -9234 E0102; Hanyo-Denshi; TK01092150 -9235 E0100; Adobe-Japan1; CID+22729 -9236 E0100; Adobe-Japan1; CID+22730 -9237 E0100; Adobe-Japan1; CID+1934 -9237 E0101; Adobe-Japan1; CID+13437 -9238 E0100; Adobe-Japan1; CID+15223 -9238 E0101; Hanyo-Denshi; JB6751 -9238 E0101; Moji_Joho; MJ026717 -9238 E0102; Hanyo-Denshi; IB3064 -9238 E0102; Moji_Joho; MJ026718 -9239 E0100; Adobe-Japan1; CID+8655 -923A E0100; Adobe-Japan1; CID+8649 -923C E0100; Adobe-Japan1; CID+8651 -923E E0100; Adobe-Japan1; CID+22731 -923F E0100; Adobe-Japan1; CID+6988 -9240 E0100; Adobe-Japan1; CID+8650 -9242 E0100; Adobe-Japan1; CID+18818 -9242 E0101; Moji_Joho; MJ026728 -9242 E0102; Moji_Joho; MJ026729 -9243 E0100; Adobe-Japan1; CID+15224 -9244 E0100; Adobe-Japan1; CID+3118 -9245 E0100; Adobe-Japan1; CID+6983 -9245 E0101; Hanyo-Denshi; JA7874 -9245 E0101; Moji_Joho; MJ026732 -9245 E0102; Hanyo-Denshi; FT2645 -9245 E0102; Moji_Joho; MJ026733 -9246 E0100; Adobe-Japan1; CID+22732 -9247 E0100; Adobe-Japan1; CID+15225 -9248 E0100; Adobe-Japan1; CID+6986 -9249 E0100; Adobe-Japan1; CID+6984 -924A E0100; Adobe-Japan1; CID+18819 -924B E0100; Adobe-Japan1; CID+6989 -924B E0101; Hanyo-Denshi; JA7880 -924B E0101; Moji_Joho; MJ026739 -924B E0102; Hanyo-Denshi; FT2646 -924B E0102; Moji_Joho; MJ026740 -924D E0100; Adobe-Japan1; CID+22733 -924E E0100; Adobe-Japan1; CID+8652 -924F E0100; Adobe-Japan1; CID+15226 -9250 E0100; Adobe-Japan1; CID+6990 -9251 E0100; Adobe-Japan1; CID+8654 -9252 E0100; Moji_Joho; MJ026747 -9252 E0101; Moji_Joho; MJ026748 -9256 E0100; Adobe-Japan1; CID+18820 -9257 E0100; Adobe-Japan1; CID+6982 -9258 E0100; Adobe-Japan1; CID+22734 -9259 E0100; Adobe-Japan1; CID+8653 -925A E0100; Adobe-Japan1; CID+6995 -925B E0100; Adobe-Japan1; CID+1302 -925B E0101; Adobe-Japan1; CID+13417 -925B E0102; Adobe-Japan1; CID+13659 -925B E0103; Hanyo-Denshi; JA1784 -925B E0103; Moji_Joho; MJ026757 -925B E0104; Hanyo-Denshi; KS457800 -925B E0104; Moji_Joho; MJ026758 -925B E0105; Hanyo-Denshi; FT1608 -925B E0105; Moji_Joho; MJ026759 -925C E0100; Adobe-Japan1; CID+22735 -925D E0100; Adobe-Japan1; CID+22736 -925E E0100; Adobe-Japan1; CID+6981 -9260 E0100; Adobe-Japan1; CID+15227 -9261 E0100; Adobe-Japan1; CID+18821 -9261 E0101; Hanyo-Denshi; JB6771 -9261 E0101; Moji_Joho; MJ026765 -9261 E0102; Hanyo-Denshi; JTBDD8 -9261 E0102; Moji_Joho; MJ026766 -9262 E0100; Adobe-Japan1; CID+3393 -9264 E0100; Adobe-Japan1; CID+6985 -9265 E0100; Adobe-Japan1; CID+18822 -9266 E0100; Adobe-Japan1; CID+2504 -9267 E0100; Adobe-Japan1; CID+8656 -9268 E0100; Adobe-Japan1; CID+18823 -9268 E0101; Hanyo-Denshi; JB6774 -9268 E0101; Moji_Joho; MJ026773 -9268 E0102; Hanyo-Denshi; KS457810 -9268 E0102; Moji_Joho; MJ026774 -9269 E0100; Adobe-Japan1; CID+22737 -926E E0100; Adobe-Japan1; CID+22738 -926F E0100; Adobe-Japan1; CID+22739 -9270 E0100; Adobe-Japan1; CID+22740 -9271 E0100; Adobe-Japan1; CID+2029 -9275 E0100; Adobe-Japan1; CID+22741 -9276 E0100; Adobe-Japan1; CID+19917 -9277 E0100; Adobe-Japan1; CID+8658 -9278 E0100; Adobe-Japan1; CID+8659 -9278 E0101; Moji_Joho; MJ026788 -9278 E0102; Moji_Joho; MJ026789 -9279 E0100; Adobe-Japan1; CID+22742 -927B E0100; Adobe-Japan1; CID+22743 -927C E0100; Adobe-Japan1; CID+18825 -927C E0101; Hanyo-Denshi; JB6785 -927C E0101; Moji_Joho; MJ026793 -927C E0102; Hanyo-Denshi; JTBE03 -927C E0102; Moji_Joho; MJ026794 -927D E0100; Adobe-Japan1; CID+18826 -927E E0100; Adobe-Japan1; CID+3702 -927F E0100; Adobe-Japan1; CID+18827 -9280 E0100; Adobe-Japan1; CID+1756 -9283 E0100; Adobe-Japan1; CID+2384 -9283 E0101; Hanyo-Denshi; JA2938 -9283 E0101; Moji_Joho; MJ026802 -9283 E0102; Hanyo-Denshi; KS457760 -9283 E0102; Moji_Joho; MJ026801 -9285 E0100; Adobe-Japan1; CID+3220 -9287 E0100; Hanyo-Denshi; IP9287 -9287 E0101; Hanyo-Denshi; TK01092310 -9288 E0100; Adobe-Japan1; CID+8362 -9289 E0100; Adobe-Japan1; CID+18828 -928A E0100; Adobe-Japan1; CID+22744 -928A E0101; Hanyo-Denshi; JB6790 -928A E0102; Hanyo-Denshi; TK01092200 -928D E0100; Adobe-Japan1; CID+18829 -928E E0100; Adobe-Japan1; CID+19918 -928E E0101; Hanyo-Denshi; JB6792 -928E E0101; Moji_Joho; MJ026815 -928E E0102; Hanyo-Denshi; KS458660 -928E E0102; Moji_Joho; MJ026816 -9291 E0100; Adobe-Japan1; CID+2735 -9292 E0100; Adobe-Japan1; CID+22745 -9293 E0100; Adobe-Japan1; CID+6993 -9293 E0101; Hanyo-Denshi; JA7884 -9293 E0101; Moji_Joho; MJ026821 -9293 E0102; Hanyo-Denshi; FT2647 -9293 E0102; Moji_Joho; MJ026822 -9295 E0100; Adobe-Japan1; CID+6987 -9295 E0101; Hanyo-Denshi; JA7878 -9295 E0102; Hanyo-Denshi; TK01092550 -9296 E0100; Adobe-Japan1; CID+6992 -9297 E0100; Adobe-Japan1; CID+18830 -9298 E0100; Adobe-Japan1; CID+3791 -9299 E0100; Adobe-Japan1; CID+18831 -929A E0100; Adobe-Japan1; CID+3028 -929B E0100; Adobe-Japan1; CID+6994 -929C E0100; Adobe-Japan1; CID+6991 -929F E0100; Adobe-Japan1; CID+18832 -92A0 E0100; Adobe-Japan1; CID+22746 -92A2 E0100; Moji_Joho; MJ026837 -92A2 E0101; Moji_Joho; MJ026838 -92A4 E0100; Adobe-Japan1; CID+22747 -92A5 E0100; Adobe-Japan1; CID+22748 -92A7 E0100; Adobe-Japan1; CID+8657 -92A8 E0100; Adobe-Japan1; CID+22749 -92AB E0100; Adobe-Japan1; CID+18833 -92AD E0100; Adobe-Japan1; CID+2734 -92AF E0100; Adobe-Japan1; CID+19919 -92B2 E0100; Adobe-Japan1; CID+18836 -92B3 E0100; Adobe-Japan1; CID+13652 -92B6 E0100; Adobe-Japan1; CID+22750 -92B7 E0100; Adobe-Japan1; CID+6998 -92B7 E0101; Hanyo-Denshi; JA7889 -92B7 E0101; Moji_Joho; MJ026857 -92B7 E0102; Hanyo-Denshi; FT2648 -92B7 E0102; Moji_Joho; MJ026858 -92B8 E0100; Adobe-Japan1; CID+22751 -92B9 E0100; Adobe-Japan1; CID+6997 -92BA E0100; Adobe-Japan1; CID+22752 -92BB E0100; Adobe-Japan1; CID+19920 -92BC E0100; Adobe-Japan1; CID+19921 -92BD E0100; Adobe-Japan1; CID+22753 -92BF E0100; Adobe-Japan1; CID+18837 -92C0 E0100; Adobe-Japan1; CID+18838 -92C1 E0100; Adobe-Japan1; CID+19922 -92C2 E0100; Adobe-Japan1; CID+15228 -92C3 E0100; Adobe-Japan1; CID+19923 -92C5 E0100; Adobe-Japan1; CID+19924 -92C6 E0100; Adobe-Japan1; CID+18839 -92C6 E0101; Hanyo-Denshi; JB6823 -92C6 E0101; Moji_Joho; MJ026873 -92C6 E0102; Hanyo-Denshi; JTBDE7 -92C6 E0102; Moji_Joho; MJ026874 -92C7 E0100; Adobe-Japan1; CID+22754 -92C8 E0100; Adobe-Japan1; CID+19925 -92CB E0100; Adobe-Japan1; CID+15229 -92CB E0101; Hanyo-Denshi; JB6826 -92CB E0101; Moji_Joho; MJ026879 -92CB E0102; Hanyo-Denshi; JTBDF7 -92CB E0102; Moji_Joho; MJ026880 -92CC E0100; Adobe-Japan1; CID+15230 -92CC E0101; Hanyo-Denshi; JB6827 -92CC E0101; Moji_Joho; MJ026881 -92CC E0102; Hanyo-Denshi; JTBDE9 -92CC E0102; Moji_Joho; MJ026883 -92CC E0103; Moji_Joho; MJ026882 -92CD E0100; Adobe-Japan1; CID+22755 -92CE E0100; Adobe-Japan1; CID+18840 -92CF E0100; Adobe-Japan1; CID+6996 -92D0 E0100; Adobe-Japan1; CID+8663 -92D2 E0100; Adobe-Japan1; CID+3677 -92D3 E0100; Adobe-Japan1; CID+8667 -92D5 E0100; Adobe-Japan1; CID+8665 -92D5 E0101; Hanyo-Denshi; JB6832 -92D5 E0101; Moji_Joho; MJ026892 -92D5 E0102; Hanyo-Denshi; JTBDED -92D5 E0102; Moji_Joho; MJ026893 -92D7 E0100; Adobe-Japan1; CID+8661 -92D7 E0101; Hanyo-Denshi; JB6833 -92D7 E0101; Moji_Joho; MJ026896 -92D7 E0102; Hanyo-Denshi; KS458350 -92D7 E0102; Moji_Joho; MJ026895 -92D8 E0100; Adobe-Japan1; CID+22756 -92D8 E0101; Hanyo-Denshi; JB6834 -92D8 E0101; Moji_Joho; MJ026898 -92D8 E0102; Hanyo-Denshi; KS458550 -92D8 E0102; Moji_Joho; MJ026897 -92D9 E0100; Adobe-Japan1; CID+8662 -92DC E0100; Adobe-Japan1; CID+22757 -92DD E0100; Adobe-Japan1; CID+22758 -92DD E0101; Hanyo-Denshi; JB6837 -92DD E0101; Moji_Joho; MJ026903 -92DD E0102; Hanyo-Denshi; JTBDF0 -92DD E0102; Moji_Joho; MJ026904 -92DF E0100; Adobe-Japan1; CID+15231 -92E0 E0100; Adobe-Japan1; CID+8666 -92E1 E0100; Adobe-Japan1; CID+22759 -92E3 E0100; Adobe-Japan1; CID+22760 -92E3 E0101; Hanyo-Denshi; JB6841 -92E3 E0101; Moji_Joho; MJ026910 -92E3 E0102; Hanyo-Denshi; KS459290 -92E3 E0102; Moji_Joho; MJ026909 -92E4 E0100; Adobe-Japan1; CID+2437 -92E5 E0100; Adobe-Japan1; CID+18841 -92E7 E0100; Adobe-Japan1; CID+8660 -92E8 E0100; Adobe-Japan1; CID+22761 -92E9 E0100; Adobe-Japan1; CID+6999 -92E9 E0101; Adobe-Japan1; CID+20237 -92E9 E0102; Hanyo-Denshi; JA7890 -92E9 E0102; Moji_Joho; MJ026916 -92E9 E0103; Hanyo-Denshi; KS459700 -92E9 E0103; Moji_Joho; MJ026918 -92E9 E0104; Hanyo-Denshi; KS459400 -92E9 E0104; Moji_Joho; MJ026917 -92EA E0100; Adobe-Japan1; CID+3631 -92EC E0100; Adobe-Japan1; CID+22762 -92ED E0100; Adobe-Japan1; CID+1270 -92EE E0100; Adobe-Japan1; CID+22763 -92EE E0101; Hanyo-Denshi; JB6846 -92EE E0101; Moji_Joho; MJ026923 -92EE E0102; Hanyo-Denshi; IB3077 -92EE E0102; Moji_Joho; MJ026924 -92EF E0100; Hanyo-Denshi; IP92EF -92EF E0101; Hanyo-Denshi; TK01092700 -92F0 E0100; Adobe-Japan1; CID+22764 -92F2 E0100; Adobe-Japan1; CID+3512 -92F3 E0100; Adobe-Japan1; CID+2992 -92F7 E0100; Adobe-Japan1; CID+18845 -92F8 E0100; Adobe-Japan1; CID+1682 -92F9 E0100; Adobe-Japan1; CID+8368 -92FA E0100; Adobe-Japan1; CID+7001 -92FB E0100; Adobe-Japan1; CID+8670 -92FB E0101; Hanyo-Denshi; JB6849 -92FB E0101; Moji_Joho; MJ026936 -92FB E0102; Hanyo-Denshi; KS460780 -92FB E0102; Moji_Joho; MJ026937 -92FC E0100; Adobe-Japan1; CID+2031 -92FF E0100; Adobe-Japan1; CID+8673 -9300 E0100; Adobe-Japan1; CID+22765 -9300 E0101; Hanyo-Denshi; JB6851 -9300 E0101; Moji_Joho; MJ026942 -9300 E0102; Hanyo-Denshi; JTBDF8 -9300 E0102; Moji_Joho; MJ026943 -9302 E0100; Adobe-Japan1; CID+8675 -9302 E0101; Hanyo-Denshi; JB6852 -9302 E0101; Moji_Joho; MJ026946 -9302 E0102; Hanyo-Denshi; KS459820 -9302 E0102; Moji_Joho; MJ026945 -9304 E0100; Adobe-Japan1; CID+13402 -9304 E0101; Hanyo-Denshi; JC9321 -9304 E0102; Hanyo-Denshi; TK01093020 -9306 E0100; Adobe-Japan1; CID+2170 -9306 E0101; Adobe-Japan1; CID+7690 -9306 E0102; Hanyo-Denshi; JA2712 -9306 E0102; Moji_Joho; MJ026951 -9306 E0103; Hanyo-Denshi; FT1812 -9306 E0103; Moji_Joho; MJ026950 -9308 E0100; Adobe-Japan1; CID+22766 -9308 E0101; Hanyo-Denshi; JB6853 -9308 E0102; Hanyo-Denshi; TK01093180 -930B E0100; Hanyo-Denshi; IP930B -930B E0101; Hanyo-Denshi; TK01093110 -930D E0100; Adobe-Japan1; CID+15232 -930F E0100; Adobe-Japan1; CID+7000 -9310 E0100; Adobe-Japan1; CID+2611 -9311 E0100; Adobe-Japan1; CID+18842 -9314 E0100; Adobe-Japan1; CID+19926 -9315 E0100; Adobe-Japan1; CID+15233 -9318 E0100; Adobe-Japan1; CID+2612 -9319 E0100; Adobe-Japan1; CID+7004 -931A E0100; Adobe-Japan1; CID+7006 -931A E0101; Hanyo-Denshi; JA7903 -931A E0101; Moji_Joho; MJ026973 -931A E0102; Hanyo-Denshi; IB3078 -931A E0102; Moji_Joho; MJ026974 -931A E0103; Hanyo-Denshi; FT2649 -931A E0103; Moji_Joho; MJ026975 -931C E0100; Adobe-Japan1; CID+22767 -931D E0100; Adobe-Japan1; CID+8674 -931E E0100; Adobe-Japan1; CID+8672 -931F E0100; Adobe-Japan1; CID+15234 -9320 E0100; Adobe-Japan1; CID+2531 -9321 E0100; Adobe-Japan1; CID+8669 -9322 E0100; Adobe-Japan1; CID+7005 -9323 E0100; Adobe-Japan1; CID+7007 -9324 E0100; Adobe-Japan1; CID+22768 -9325 E0100; Adobe-Japan1; CID+8668 -9326 E0100; Adobe-Japan1; CID+1739 -9327 E0100; Adobe-Japan1; CID+15235 -9328 E0100; Adobe-Japan1; CID+3511 -9328 E0101; Hanyo-Denshi; JA4137 -9328 E0101; Moji_Joho; MJ026989 -9328 E0102; Hanyo-Denshi; KS460790 -9328 E0102; Moji_Joho; MJ026990 -9329 E0100; Adobe-Japan1; CID+18846 -932A E0100; Adobe-Japan1; CID+22769 -932B E0100; Adobe-Japan1; CID+2318 -932C E0100; Adobe-Japan1; CID+4041 -932E E0100; Adobe-Japan1; CID+7003 -932F E0100; Adobe-Japan1; CID+2152 -9332 E0100; Adobe-Japan1; CID+4069 -9333 E0100; Adobe-Japan1; CID+19927 -9334 E0100; Adobe-Japan1; CID+22770 -9335 E0100; Adobe-Japan1; CID+7009 -9335 E0101; Adobe-Japan1; CID+20238 -9335 E0102; Hanyo-Denshi; JA7906 -9335 E0102; Moji_Joho; MJ027002 -9335 E0103; Hanyo-Denshi; KS460560S -9335 E0103; Moji_Joho; MJ027003 -9336 E0100; Adobe-Japan1; CID+19928 -9337 E0100; Adobe-Japan1; CID+22771 -933A E0100; Adobe-Japan1; CID+7008 -933A E0101; Hanyo-Denshi; JA7905 -933A E0101; Moji_Joho; MJ027008 -933A E0102; Hanyo-Denshi; KS460610 -933A E0102; Moji_Joho; MJ027009 -933B E0100; Adobe-Japan1; CID+7010 -933F E0100; Hanyo-Denshi; TK01092730 -933F E0101; Hanyo-Denshi; TK01092960 -9344 E0100; Adobe-Japan1; CID+7002 -9347 E0100; Adobe-Japan1; CID+15236 -9348 E0100; Adobe-Japan1; CID+8361 -9348 E0101; Hanyo-Denshi; JB6873 -9348 E0101; Moji_Joho; MJ027016 -9348 E0102; Hanyo-Denshi; JTBE0D -9348 E0102; Moji_Joho; MJ027017 -9349 E0100; Adobe-Japan1; CID+17166 -934A E0100; Adobe-Japan1; CID+13400 -934B E0100; Adobe-Japan1; CID+3265 -934D E0100; Adobe-Japan1; CID+3151 -934F E0100; Hanyo-Denshi; KS460910 -934F E0101; Hanyo-Denshi; TK01093590 -9350 E0100; Adobe-Japan1; CID+22772 -9351 E0100; Adobe-Japan1; CID+18849 -9351 E0101; Hanyo-Denshi; JB6876 -9351 E0101; Moji_Joho; MJ027028 -9351 E0102; Hanyo-Denshi; KS460930 -9351 E0102; Moji_Joho; MJ027027 -9352 E0100; Adobe-Japan1; CID+15237 -9354 E0100; Adobe-Japan1; CID+3059 -9354 E0101; Hanyo-Denshi; JA3655 -9354 E0102; Hanyo-Denshi; TK01093350 -9355 E0100; Adobe-Japan1; CID+22773 -9356 E0100; Adobe-Japan1; CID+7015 -9357 E0100; Adobe-Japan1; CID+8677 -9358 E0100; Adobe-Japan1; CID+19929 -935A E0100; Adobe-Japan1; CID+18850 -935B E0100; Adobe-Japan1; CID+2945 -935C E0100; Adobe-Japan1; CID+7011 -935E E0100; Adobe-Japan1; CID+22774 -9360 E0100; Adobe-Japan1; CID+7012 -9364 E0100; Adobe-Japan1; CID+17167 -9365 E0100; Adobe-Japan1; CID+17168 -9365 E0101; Adobe-Japan1; CID+15238 -9365 E0102; Hanyo-Denshi; JB6884 -9365 E0102; Moji_Joho; MJ027049 -9365 E0103; Hanyo-Denshi; KS461850 -9365 E0103; Moji_Joho; MJ027050 -9365 E0104; Hanyo-Denshi; JC9329 -9365 E0104; Moji_Joho; MJ027051 -9367 E0100; Adobe-Japan1; CID+22775 -9369 E0100; Adobe-Japan1; CID+22776 -9369 E0101; Hanyo-Denshi; JB6886 -9369 E0101; Moji_Joho; MJ027055 -9369 E0102; Hanyo-Denshi; KS461170 -9369 E0102; Moji_Joho; MJ027056 -936A E0100; Adobe-Japan1; CID+15239 -936B E0100; Adobe-Japan1; CID+18851 -936C E0100; Adobe-Japan1; CID+1795 -936D E0100; Adobe-Japan1; CID+15240 -936E E0100; Adobe-Japan1; CID+7014 -936E E0101; Hanyo-Denshi; JA7911 -936E E0101; Moji_Joho; MJ027061 -936E E0102; Hanyo-Denshi; FT2650 -936E E0102; Moji_Joho; MJ027062 -936F E0100; Adobe-Japan1; CID+22777 -9370 E0100; Adobe-Japan1; CID+8676 -9371 E0100; Adobe-Japan1; CID+18852 -9373 E0100; Adobe-Japan1; CID+18853 -9373 E0101; Hanyo-Denshi; JB6892 -9373 E0101; Moji_Joho; MJ027067 -9373 E0102; Hanyo-Denshi; KS461880 -9373 E0102; Moji_Joho; MJ027068 -9373 E0103; Hanyo-Denshi; TK01093150 -9374 E0100; Adobe-Japan1; CID+22778 -9375 E0100; Adobe-Japan1; CID+1892 -9375 E0101; Adobe-Japan1; CID+20276 -9375 E0102; Moji_Joho; MJ027070 -9375 E0103; Moji_Joho; MJ027071 -9376 E0100; Adobe-Japan1; CID+22779 -9379 E0100; Hanyo-Denshi; IP9379 -9379 E0101; Hanyo-Denshi; TK01092790 -937A E0100; Adobe-Japan1; CID+22780 -937C E0100; Adobe-Japan1; CID+7013 -937D E0100; Adobe-Japan1; CID+22781 -937E E0100; Adobe-Japan1; CID+2505 -937F E0100; Adobe-Japan1; CID+19930 -9380 E0100; Adobe-Japan1; CID+22782 -9381 E0100; Adobe-Japan1; CID+22783 -9382 E0100; Adobe-Japan1; CID+19931 -9388 E0100; Adobe-Japan1; CID+18857 -938A E0100; Adobe-Japan1; CID+19932 -938B E0100; Adobe-Japan1; CID+18858 -938B E0101; Adobe-Japan1; CID+20239 -938B E0102; Hanyo-Denshi; JB6909 -938B E0102; Moji_Joho; MJ027090 -938B E0103; Hanyo-Denshi; JD9125 -938B E0103; Moji_Joho; MJ027091 -938C E0100; Adobe-Japan1; CID+1495 -938C E0101; Adobe-Japan1; CID+13686 -938C E0102; Hanyo-Denshi; JA1989 -938C E0102; Moji_Joho; MJ027093 -938C E0103; Hanyo-Denshi; JTBE1DS -938C E0103; Moji_Joho; MJ027092 -938D E0100; Adobe-Japan1; CID+22784 -938F E0100; Adobe-Japan1; CID+18859 -9392 E0100; Adobe-Japan1; CID+22785 -9394 E0100; Adobe-Japan1; CID+7019 -9395 E0100; Adobe-Japan1; CID+22786 -9396 E0100; Adobe-Japan1; CID+2095 -9396 E0101; Adobe-Japan1; CID+13781 -9396 E0102; Hanyo-Denshi; JA2631 -9396 E0102; Moji_Joho; MJ027104 -9396 E0103; Hanyo-Denshi; JTBE1A -9396 E0103; Moji_Joho; MJ027103 -9397 E0100; Adobe-Japan1; CID+2811 -9398 E0100; Adobe-Japan1; CID+22787 -939A E0100; Adobe-Japan1; CID+3046 -939A E0101; Adobe-Japan1; CID+7745 -939A E0102; Hanyo-Denshi; JA3642 -939A E0102; Moji_Joho; MJ027108 -939A E0103; Hanyo-Denshi; FT1864 -939A E0103; Moji_Joho; MJ027109 -939B E0100; Adobe-Japan1; CID+15241 -939E E0100; Adobe-Japan1; CID+18860 -93A1 E0100; Adobe-Japan1; CID+18854 -93A1 E0101; Adobe-Japan1; CID+22788 -93A1 E0102; Hanyo-Denshi; JB6917 -93A1 E0102; Moji_Joho; MJ027116 -93A1 E0103; Hanyo-Denshi; KS462290 -93A1 E0103; Moji_Joho; MJ027118 -93A1 E0104; Hanyo-Denshi; JD9121 -93A1 E0104; Moji_Joho; MJ027117 -93A1 E0105; Hanyo-Denshi; KS462840 -93A1 E0105; Moji_Joho; MJ058932 -93A3 E0100; Adobe-Japan1; CID+17169 -93A4 E0100; Adobe-Japan1; CID+8678 -93A6 E0100; Adobe-Japan1; CID+22789 -93A6 E0101; Hanyo-Denshi; JB6920 -93A6 E0101; Moji_Joho; MJ027123 -93A6 E0102; Hanyo-Denshi; JTBE22 -93A6 E0102; Moji_Joho; MJ027124 -93A7 E0100; Adobe-Japan1; CID+1433 -93A8 E0100; Adobe-Japan1; CID+22790 -93A9 E0100; Adobe-Japan1; CID+15243 -93AB E0100; Adobe-Japan1; CID+22791 -93AC E0100; Adobe-Japan1; CID+7017 -93AC E0101; Hanyo-Denshi; JA7914 -93AC E0102; Hanyo-Denshi; TK01093880 -93AD E0100; Adobe-Japan1; CID+7018 -93AD E0101; Hanyo-Denshi; JA7915 -93AD E0101; Moji_Joho; MJ027132 -93AD E0102; Hanyo-Denshi; JTBE25 -93AD E0102; Moji_Joho; MJ060292 -93AE E0100; Adobe-Japan1; CID+3039 -93AE E0101; Adobe-Japan1; CID+13370 -93AF E0100; Hanyo-Denshi; IP93AF -93AF E0101; Hanyo-Denshi; TK01093530 -93B0 E0100; Adobe-Japan1; CID+7016 -93B0 E0101; Hanyo-Denshi; JA7913 -93B0 E0101; Moji_Joho; MJ027136 -93B0 E0102; Hanyo-Denshi; FT2651S -93B0 E0102; Moji_Joho; MJ027137 -93B0 E0103; Hanyo-Denshi; JTBE28 -93B0 E0103; Moji_Joho; MJ027138 -93B4 E0100; Adobe-Japan1; CID+22792 -93B5 E0100; Adobe-Japan1; CID+22793 -93B6 E0100; Adobe-Japan1; CID+22794 -93B9 E0100; Adobe-Japan1; CID+7020 -93B9 E0101; Hanyo-Denshi; JA7917 -93B9 E0101; Moji_Joho; MJ027148 -93B9 E0102; Hanyo-Denshi; KS461830 -93B9 E0102; Moji_Joho; MJ027149 -93B9 E0103; Hanyo-Denshi; FT2652 -93B9 E0103; Moji_Joho; MJ027150 -93B9 E0104; Hanyo-Denshi; JTBE29 -93B9 E0104; Moji_Joho; MJ027151 -93B9 E0105; Moji_Joho; MJ027147 -93BA E0100; Adobe-Japan1; CID+15242 -93BA E0101; Hanyo-Denshi; JB6926 -93BA E0101; Moji_Joho; MJ027153 -93BA E0102; Hanyo-Denshi; JTBE0B -93BA E0102; Moji_Joho; MJ027152 -93BB E0100; Adobe-Japan1; CID+19933 -93C1 E0100; Adobe-Japan1; CID+15244 -93C3 E0100; Adobe-Japan1; CID+7026 -93C4 E0100; Adobe-Japan1; CID+22795 -93C5 E0100; Adobe-Japan1; CID+22796 -93C5 E0101; Hanyo-Denshi; JB6930 -93C5 E0102; Hanyo-Denshi; TK01093900 -93C6 E0100; Adobe-Japan1; CID+8679 -93C7 E0100; Adobe-Japan1; CID+18865 -93C8 E0100; Adobe-Japan1; CID+7029 -93C8 E0101; Hanyo-Denshi; JA7926 -93C8 E0101; Moji_Joho; MJ027166 -93C8 E0102; Hanyo-Denshi; FT2654 -93C8 E0102; Moji_Joho; MJ027165 -93C9 E0100; Adobe-Japan1; CID+22797 -93CA E0100; Adobe-Japan1; CID+15245 -93CB E0100; Adobe-Japan1; CID+22798 -93CC E0100; Adobe-Japan1; CID+19934 -93CC E0101; Hanyo-Denshi; JB6936 -93CC E0101; Moji_Joho; MJ027170 -93CC E0102; Hanyo-Denshi; KS463020 -93CC E0102; Moji_Joho; MJ027171 -93CD E0100; Adobe-Japan1; CID+22799 -93D0 E0100; Adobe-Japan1; CID+7028 -93D0 E0101; Hanyo-Denshi; JA7925 -93D0 E0101; Moji_Joho; MJ027175 -93D0 E0102; Hanyo-Denshi; FT2653 -93D0 E0102; Moji_Joho; MJ027176 -93D1 E0100; Adobe-Japan1; CID+3111 -93D1 E0101; Hanyo-Denshi; JA3713 -93D1 E0101; Moji_Joho; MJ027177 -93D1 E0102; Hanyo-Denshi; KS463690 -93D1 E0102; Moji_Joho; MJ027178 -93D3 E0100; Adobe-Japan1; CID+22800 -93D3 E0101; Hanyo-Denshi; JB6938 -93D3 E0101; Moji_Joho; MJ027180 -93D3 E0102; Hanyo-Denshi; JTBE2B -93D3 E0102; Moji_Joho; MJ027181 -93D6 E0100; Adobe-Japan1; CID+7021 -93D7 E0100; Adobe-Japan1; CID+7022 -93D8 E0100; Adobe-Japan1; CID+7025 -93D9 E0100; Adobe-Japan1; CID+22801 -93DC E0100; Adobe-Japan1; CID+18866 -93DD E0100; Adobe-Japan1; CID+7027 -93DD E0101; Adobe-Japan1; CID+14254 -93DE E0100; Adobe-Japan1; CID+8680 -93DE E0101; Hanyo-Denshi; JB6941 -93DE E0101; Moji_Joho; MJ027193 -93DE E0102; Hanyo-Denshi; JTBE39 -93DE E0102; Moji_Joho; MJ027194 -93DE E0103; Hanyo-Denshi; TK01093860 -93DE E0104; Hanyo-Denshi; TK01094160 -93DF E0100; Adobe-Japan1; CID+17170 -93E0 E0100; Hanyo-Denshi; IB1025 -93E0 E0100; Moji_Joho; MJ027196 -93E0 E0101; Hanyo-Denshi; IP93E0 -93E0 E0101; Moji_Joho; MJ027197 -93E1 E0100; Adobe-Japan1; CID+1720 -93E1 E0101; Hanyo-Denshi; JA2232 -93E1 E0101; Moji_Joho; MJ027198 -93E1 E0102; Hanyo-Denshi; JTBE2A -93E1 E0102; Moji_Joho; MJ027199 -93E2 E0100; Adobe-Japan1; CID+15246 -93E4 E0100; Adobe-Japan1; CID+7030 -93E5 E0100; Adobe-Japan1; CID+7024 -93E6 E0100; Adobe-Japan1; CID+19935 -93E7 E0100; Adobe-Japan1; CID+18867 -93E8 E0100; Adobe-Japan1; CID+7023 -93F1 E0100; Adobe-Japan1; CID+18864 -93F3 E0100; Hanyo-Denshi; IP93F3 -93F3 E0100; Moji_Joho; MJ027214 -93F3 E0101; Hanyo-Denshi; JTBE2F -93F3 E0101; Moji_Joho; MJ027215 -93F3 E0102; Hanyo-Denshi; TK01094360 -93F5 E0100; Adobe-Japan1; CID+18861 -93F5 E0101; Hanyo-Denshi; JD9128 -93F5 E0101; Moji_Joho; MJ027218 -93F5 E0102; Hanyo-Denshi; KS463720S -93F5 E0102; Moji_Joho; MJ027219 -93F7 E0100; Adobe-Japan1; CID+22802 -93F8 E0100; Adobe-Japan1; CID+8681 -93F9 E0100; Adobe-Japan1; CID+19936 -93F9 E0101; Hanyo-Denshi; JB6946 -93F9 E0102; Hanyo-Denshi; TK01094370 -93FA E0100; Adobe-Japan1; CID+15247 -93FB E0100; Adobe-Japan1; CID+18871 -93FB E0101; Hanyo-Denshi; JB6950 -93FB E0101; Moji_Joho; MJ027227 -93FB E0102; Hanyo-Denshi; JTBE37S -93FB E0102; Moji_Joho; MJ027226 -93FD E0100; Adobe-Japan1; CID+15248 -9401 E0100; Adobe-Japan1; CID+22803 -9402 E0100; Adobe-Japan1; CID+19937 -9403 E0100; Adobe-Japan1; CID+7034 -9404 E0100; Adobe-Japan1; CID+17171 -9404 E0101; Hanyo-Denshi; JB6954 -9404 E0101; Moji_Joho; MJ027236 -9404 E0102; Hanyo-Denshi; IB3134 -9404 E0102; Moji_Joho; MJ027237 -9407 E0100; Adobe-Japan1; CID+7035 -9408 E0100; Adobe-Japan1; CID+22804 -9409 E0100; Adobe-Japan1; CID+18868 -940D E0100; Adobe-Japan1; CID+19938 -940E E0100; Adobe-Japan1; CID+19939 -940F E0100; Adobe-Japan1; CID+15249 -9410 E0100; Adobe-Japan1; CID+7036 -9413 E0100; Adobe-Japan1; CID+7033 -9414 E0100; Adobe-Japan1; CID+7032 -9414 E0101; Hanyo-Denshi; JA7929 -9414 E0101; Moji_Joho; MJ027254 -9414 E0102; Hanyo-Denshi; JTBE34 -9414 E0102; Moji_Joho; MJ027253 -9415 E0100; Adobe-Japan1; CID+22805 -9415 E0101; Hanyo-Denshi; JB6960 -9415 E0101; Moji_Joho; MJ027256 -9415 E0102; Hanyo-Denshi; KS464370 -9415 E0102; Moji_Joho; MJ027255 -9415 E0103; Hanyo-Denshi; TK01094560 -9416 E0100; Adobe-Japan1; CID+18869 -9416 E0101; Hanyo-Denshi; JB6961 -9416 E0102; Hanyo-Denshi; KS464570 -9416 E0102; Moji_Joho; MJ027259 -9416 E0103; Hanyo-Denshi; TK01094350 -9417 E0100; Adobe-Japan1; CID+18870 -9418 E0100; Adobe-Japan1; CID+2506 -9418 E0101; Hanyo-Denshi; JA3066 -9418 E0101; Moji_Joho; MJ027262 -9418 E0102; Hanyo-Denshi; JTBE35 -9418 E0102; Moji_Joho; MJ027263 -9419 E0100; Adobe-Japan1; CID+3202 -941A E0100; Adobe-Japan1; CID+7031 -941F E0100; Adobe-Japan1; CID+22806 -9421 E0100; Adobe-Japan1; CID+7040 -9429 E0100; Hanyo-Denshi; IB1026 -9429 E0100; Moji_Joho; MJ027274 -9429 E0101; Hanyo-Denshi; IP9429 -9429 E0101; Moji_Joho; MJ027275 -9429 E0102; Hanyo-Denshi; JTBE3E -9429 E0102; Moji_Joho; MJ027276 -942A E0100; Hanyo-Denshi; IP942A -942A E0100; Moji_Joho; MJ027277 -942A E0101; Hanyo-Denshi; JTBE40 -942A E0101; Moji_Joho; MJ027278 -942B E0100; Adobe-Japan1; CID+7038 -942E E0100; Adobe-Japan1; CID+19940 -942E E0101; Hanyo-Denshi; JB6964 -942E E0102; Hanyo-Denshi; TK01094510 -942F E0100; Adobe-Japan1; CID+22807 -942F E0101; Hanyo-Denshi; JB6965 -942F E0101; Moji_Joho; MJ027283 -942F E0102; Hanyo-Denshi; KS464660 -942F E0102; Moji_Joho; MJ027284 -9431 E0100; Adobe-Japan1; CID+8682 -9432 E0100; Adobe-Japan1; CID+18872 -9433 E0100; Adobe-Japan1; CID+17172 -9434 E0100; Adobe-Japan1; CID+15250 -9435 E0100; Adobe-Japan1; CID+7039 -9435 E0101; Hanyo-Denshi; JA7936 -9435 E0101; Moji_Joho; MJ027290 -9435 E0102; Hanyo-Denshi; KS465170 -9435 E0102; Moji_Joho; MJ027291 -9435 E0103; Hanyo-Denshi; TK01094280 -9436 E0100; Adobe-Japan1; CID+7037 -9438 E0100; Adobe-Japan1; CID+2904 -9439 E0100; Hanyo-Denshi; IB1027 -9439 E0100; Moji_Joho; MJ027295 -9439 E0101; Hanyo-Denshi; IP9439 -9439 E0101; Moji_Joho; MJ027296 -943A E0100; Adobe-Japan1; CID+7041 -943A E0101; Adobe-Japan1; CID+20240 -943B E0100; Adobe-Japan1; CID+18873 -943B E0101; Hanyo-Denshi; JB6970 -943B E0101; Moji_Joho; MJ027298 -943B E0102; Hanyo-Denshi; IB3149 -943B E0102; Moji_Joho; MJ027299 -943D E0100; Adobe-Japan1; CID+22808 -943F E0100; Adobe-Japan1; CID+15251 -9441 E0100; Adobe-Japan1; CID+7042 -9441 E0101; Hanyo-Denshi; JA7939 -9441 E0101; Moji_Joho; MJ027305 -9441 E0102; Hanyo-Denshi; KS465110S -9441 E0102; Moji_Joho; MJ058945 -9443 E0100; Adobe-Japan1; CID+22809 -9444 E0100; Adobe-Japan1; CID+7044 -9445 E0100; Adobe-Japan1; CID+8683 -9448 E0100; Adobe-Japan1; CID+8684 -944A E0100; Adobe-Japan1; CID+17173 -944A E0101; Hanyo-Denshi; JB6976 -944A E0101; Moji_Joho; MJ027314 -944A E0102; Hanyo-Denshi; KS465320 -944A E0102; Moji_Joho; MJ027315 -944C E0100; Adobe-Japan1; CID+19941 -944C E0101; Hanyo-Denshi; JB6977 -944C E0102; Hanyo-Denshi; TK01094660 -9451 E0100; Adobe-Japan1; CID+1553 -9452 E0100; Adobe-Japan1; CID+7043 -9452 E0101; Hanyo-Denshi; JA7940 -9452 E0101; Moji_Joho; MJ027324 -9452 E0102; Hanyo-Denshi; KS465550 -9452 E0102; Moji_Joho; MJ027325 -9453 E0100; Adobe-Japan1; CID+3846 -9453 E0101; Adobe-Japan1; CID+7801 -9453 E0102; Hanyo-Denshi; JA4490 -9453 E0102; Moji_Joho; MJ027326 -9453 E0103; Hanyo-Denshi; FT1929 -9453 E0103; Moji_Joho; MJ027327 -9455 E0100; Adobe-Japan1; CID+15252 -9457 E0100; Hanyo-Denshi; IP9457 -9457 E0101; Hanyo-Denshi; TK01094720 -9459 E0100; Adobe-Japan1; CID+22810 -945A E0100; Adobe-Japan1; CID+7055 -945B E0100; Adobe-Japan1; CID+7045 -945B E0101; Hanyo-Denshi; JA7942 -945B E0101; Moji_Joho; MJ027334 -945B E0102; Hanyo-Denshi; FT2655 -945B E0102; Moji_Joho; MJ027335 -945B E0103; Hanyo-Denshi; TK01094550 -945B E0104; Hanyo-Denshi; TK01094580 -945B E0105; Hanyo-Denshi; TK01094620 -945C E0100; Adobe-Japan1; CID+22811 -945E E0100; Adobe-Japan1; CID+7048 -945F E0100; Adobe-Japan1; CID+22812 -945F E0101; Hanyo-Denshi; JB6981 -945F E0101; Moji_Joho; MJ027342 -945F E0102; Hanyo-Denshi; JTBE4C -945F E0102; Moji_Joho; MJ027343 -9460 E0100; Adobe-Japan1; CID+7046 -9461 E0100; Adobe-Japan1; CID+22813 -9462 E0100; Adobe-Japan1; CID+7047 -9463 E0100; Adobe-Japan1; CID+17174 -9468 E0100; Adobe-Japan1; CID+22814 -946A E0100; Adobe-Japan1; CID+7049 -946B E0100; Adobe-Japan1; CID+15253 -946D E0100; Adobe-Japan1; CID+18876 -946E E0100; Adobe-Japan1; CID+22815 -946E E0101; Hanyo-Denshi; JB6987 -946E E0101; Moji_Joho; MJ027358 -946E E0102; Hanyo-Denshi; KS466080 -946E E0102; Moji_Joho; MJ027359 -946E E0103; Hanyo-Denshi; TK01094730 -946F E0100; Adobe-Japan1; CID+18877 -9470 E0100; Adobe-Japan1; CID+7051 -9470 E0101; Hanyo-Denshi; JA7948 -9470 E0102; Hanyo-Denshi; TK01094490 -9471 E0100; Adobe-Japan1; CID+17175 -9471 E0101; Hanyo-Denshi; JB6989 -9471 E0101; Moji_Joho; MJ027363 -9471 E0102; Hanyo-Denshi; JTBE56S -9471 E0102; Moji_Joho; MJ027364 -9472 E0100; Adobe-Japan1; CID+15254 -9474 E0100; Hanyo-Denshi; IP9474 -9474 E0101; Hanyo-Denshi; TK01094820 -9475 E0100; Adobe-Japan1; CID+7052 -9475 E0101; Hanyo-Denshi; JA7949 -9475 E0101; Moji_Joho; MJ027369 -9475 E0102; Hanyo-Denshi; KS466230 -9475 E0102; Moji_Joho; MJ027370 -9476 E0100; Hanyo-Denshi; IP9476 -9476 E0100; Moji_Joho; MJ027372 -9476 E0101; Hanyo-Denshi; JTBE52 -9476 E0101; Moji_Joho; MJ027373 -9476 E0102; Hanyo-Denshi; KS466260 -9476 E0102; Moji_Joho; MJ027371 -9477 E0100; Adobe-Japan1; CID+7053 -9477 E0101; Adobe-Japan1; CID+13620 -9477 E0102; Moji_Joho; MJ027374 -9477 E0103; Moji_Joho; MJ027375 -9477 E0104; Moji_Joho; MJ027376 -947C E0100; Adobe-Japan1; CID+7056 -947D E0100; Adobe-Japan1; CID+7054 -947E E0100; Adobe-Japan1; CID+7057 -947F E0100; Adobe-Japan1; CID+7059 -9481 E0100; Adobe-Japan1; CID+7058 -9483 E0100; Adobe-Japan1; CID+22817 -9484 E0100; Adobe-Japan1; CID+22816 -9484 E0101; Hanyo-Denshi; JB6991 -9484 E0101; Moji_Joho; MJ027389 -9484 E0102; Hanyo-Denshi; KS466610 -9484 E0102; Moji_Joho; MJ027390 -9577 E0100; Adobe-Japan1; CID+3029 -9578 E0100; Adobe-Japan1; CID+15255 -9579 E0100; Adobe-Japan1; CID+18878 -957E E0100; Adobe-Japan1; CID+22818 -9580 E0100; Adobe-Japan1; CID+3827 -9582 E0100; Adobe-Japan1; CID+7060 -9583 E0100; Adobe-Japan1; CID+2736 -9584 E0100; Adobe-Japan1; CID+22819 -9586 E0100; Adobe-Japan1; CID+18879 -9587 E0100; Adobe-Japan1; CID+7061 -9588 E0100; Adobe-Japan1; CID+19942 -9589 E0100; Adobe-Japan1; CID+3604 -958A E0100; Adobe-Japan1; CID+7062 -958B E0100; Adobe-Japan1; CID+1417 -958B E0101; Hanyo-Denshi; JA1911 -958B E0101; Moji_Joho; MJ027420 -958B E0102; Hanyo-Denshi; KS468710 -958B E0102; Moji_Joho; MJ027421 -958B E0103; Hanyo-Denshi; TK01094980 -958C E0100; Adobe-Japan1; CID+18880 -958D E0100; Adobe-Japan1; CID+18881 -958E E0100; Adobe-Japan1; CID+17176 -958F E0100; Adobe-Japan1; CID+1246 -9591 E0100; Adobe-Japan1; CID+1555 -9592 E0100; Adobe-Japan1; CID+8685 -9592 E0101; Adobe-Japan1; CID+13693 -9592 E0102; Hanyo-Denshi; IP9592 -9592 E0102; Moji_Joho; MJ027430 -9592 E0103; Hanyo-Denshi; JTBE5A -9592 E0103; Moji_Joho; MJ027431 -9593 E0100; Adobe-Japan1; CID+1554 -9594 E0100; Adobe-Japan1; CID+7063 -9594 E0101; Moji_Joho; MJ027433 -9594 E0102; Moji_Joho; MJ027434 -9596 E0100; Adobe-Japan1; CID+7064 -9598 E0100; Adobe-Japan1; CID+7065 -9599 E0100; Adobe-Japan1; CID+7066 -959D E0100; Adobe-Japan1; CID+22820 -959E E0100; Adobe-Japan1; CID+22821 -959F E0100; Adobe-Japan1; CID+17177 -95A0 E0100; Adobe-Japan1; CID+7067 -95A1 E0100; Adobe-Japan1; CID+19943 -95A1 E0101; Hanyo-Denshi; JB7010 -95A1 E0101; Moji_Joho; MJ027446 -95A1 E0102; Hanyo-Denshi; KS469000 -95A1 E0102; Moji_Joho; MJ027447 -95A2 E0100; Adobe-Japan1; CID+1556 -95A2 E0101; Hanyo-Denshi; JA2056 -95A2 E0102; Hanyo-Denshi; TK01095050 -95A3 E0100; Adobe-Japan1; CID+1459 -95A4 E0100; Adobe-Japan1; CID+2032 -95A5 E0100; Adobe-Japan1; CID+3402 -95A6 E0100; Adobe-Japan1; CID+15256 -95A7 E0100; Adobe-Japan1; CID+7069 -95A8 E0100; Adobe-Japan1; CID+7068 -95A9 E0100; Adobe-Japan1; CID+15257 -95AB E0100; Adobe-Japan1; CID+20313 -95AB E0101; Adobe-Japan1; CID+15258 -95AB E0102; Moji_Joho; MJ027457 -95AB E0103; Moji_Joho; MJ027458 -95AC E0100; Adobe-Japan1; CID+17178 -95AD E0100; Adobe-Japan1; CID+7070 -95AD E0101; Hanyo-Denshi; JA7967 -95AD E0101; Moji_Joho; MJ027460 -95AD E0102; Hanyo-Denshi; JTBE5D -95AD E0102; Moji_Joho; MJ027461 -95B1 E0100; Adobe-Japan1; CID+13653 -95B2 E0100; Adobe-Japan1; CID+1278 -95B4 E0100; Adobe-Japan1; CID+15259 -95B6 E0100; Adobe-Japan1; CID+17179 -95B9 E0100; Adobe-Japan1; CID+7073 -95BA E0100; Adobe-Japan1; CID+22822 -95BB E0100; Adobe-Japan1; CID+7072 -95BB E0101; Adobe-Japan1; CID+7876 -95BB E0102; Hanyo-Denshi; JA7969 -95BB E0102; Moji_Joho; MJ027475 -95BB E0103; Hanyo-Denshi; JTBE5F -95BB E0103; Moji_Joho; MJ027476 -95BC E0100; Adobe-Japan1; CID+7071 -95BC E0101; Adobe-Japan1; CID+14255 -95BC E0102; Hanyo-Denshi; JA7968 -95BC E0102; Moji_Joho; MJ027477 -95BC E0103; Hanyo-Denshi; JTBE60 -95BC E0103; Moji_Joho; MJ027478 -95BD E0100; Adobe-Japan1; CID+15260 -95BE E0100; Adobe-Japan1; CID+7074 -95BF E0100; Adobe-Japan1; CID+19944 -95C3 E0100; Adobe-Japan1; CID+7077 -95C6 E0100; Adobe-Japan1; CID+19945 -95C7 E0100; Adobe-Japan1; CID+1163 -95C7 E0101; Hanyo-Denshi; JA1639 -95C7 E0101; Moji_Joho; MJ027489 -95C7 E0102; Hanyo-Denshi; KS470140 -95C7 E0102; Moji_Joho; MJ027490 -95C8 E0100; Adobe-Japan1; CID+18884 -95C8 E0101; Hanyo-Denshi; JB7021 -95C8 E0101; Moji_Joho; MJ027492 -95C8 E0102; Hanyo-Denshi; KS469960S -95C8 E0102; Moji_Joho; MJ027491 -95C9 E0100; Adobe-Japan1; CID+19946 -95C9 E0101; Hanyo-Denshi; JB7022 -95C9 E0101; Moji_Joho; MJ027493 -95C9 E0102; Hanyo-Denshi; KS470150 -95C9 E0102; Moji_Joho; MJ027494 -95CA E0100; Adobe-Japan1; CID+7075 -95CB E0100; Adobe-Japan1; CID+17180 -95CC E0100; Adobe-Japan1; CID+7079 -95CD E0100; Adobe-Japan1; CID+7078 -95CD E0101; Adobe-Japan1; CID+20241 -95CD E0102; Hanyo-Denshi; JA7975 -95CD E0102; Moji_Joho; MJ027498 -95CD E0103; Hanyo-Denshi; FT2659 -95CD E0103; Moji_Joho; MJ027499 -95D0 E0100; Adobe-Japan1; CID+17181 -95D0 E0101; Hanyo-Denshi; JB7024 -95D0 E0101; Moji_Joho; MJ027500 -95D0 E0102; Hanyo-Denshi; TK01095290 -95D0 E0103; Moji_Joho; MJ027501 -95D1 E0100; Adobe-Japan1; CID+19947 -95D2 E0100; Adobe-Japan1; CID+19948 -95D2 E0101; Hanyo-Denshi; JB7026 -95D2 E0101; Moji_Joho; MJ027504 -95D2 E0102; Hanyo-Denshi; IB3166 -95D2 E0102; Moji_Joho; MJ027505 -95D3 E0100; Adobe-Japan1; CID+17182 -95D4 E0100; Adobe-Japan1; CID+7081 -95D5 E0100; Adobe-Japan1; CID+7080 -95D6 E0100; Adobe-Japan1; CID+7082 -95D8 E0100; Adobe-Japan1; CID+3206 -95D9 E0100; Adobe-Japan1; CID+22823 -95DA E0100; Adobe-Japan1; CID+15261 -95DC E0100; Adobe-Japan1; CID+7083 -95DD E0100; Adobe-Japan1; CID+22824 -95DE E0100; Adobe-Japan1; CID+17184 -95DF E0100; Adobe-Japan1; CID+22825 -95E0 E0100; Adobe-Japan1; CID+19949 -95E1 E0100; Adobe-Japan1; CID+7084 -95E2 E0100; Adobe-Japan1; CID+7086 -95E4 E0100; Adobe-Japan1; CID+19950 -95E4 E0101; Hanyo-Denshi; JB7034 -95E4 E0101; Moji_Joho; MJ027523 -95E4 E0102; Hanyo-Denshi; KS470970 -95E4 E0102; Moji_Joho; MJ027524 -95E5 E0100; Adobe-Japan1; CID+7085 -95E5 E0101; Hanyo-Denshi; JA7982 -95E5 E0101; Moji_Joho; MJ027526 -95E5 E0102; Hanyo-Denshi; FT2661 -95E5 E0102; Moji_Joho; MJ027525 -95E6 E0100; Adobe-Japan1; CID+19951 -95E8 E0100; Adobe-Japan1; CID+14061 -95E8 E0101; Hanyo-Denshi; TK01007960 -95E8 E0102; Hanyo-Denshi; TK01094940 -961C E0100; Adobe-Japan1; CID+3550 -961D E0100; Adobe-Japan1; CID+15262 -961E E0100; Adobe-Japan1; CID+22826 -9621 E0100; Adobe-Japan1; CID+7087 -9622 E0100; Adobe-Japan1; CID+22827 -9624 E0100; Adobe-Japan1; CID+19952 -9625 E0100; Adobe-Japan1; CID+22828 -9626 E0100; Adobe-Japan1; CID+22829 -9628 E0100; Adobe-Japan1; CID+7088 -962A E0100; Adobe-Japan1; CID+2133 -962A E0101; Adobe-Japan1; CID+20242 -962C E0100; Adobe-Japan1; CID+18887 -962E E0100; Adobe-Japan1; CID+7089 -962F E0100; Adobe-Japan1; CID+7090 -9631 E0100; Adobe-Japan1; CID+19953 -9632 E0100; Adobe-Japan1; CID+3703 -9633 E0100; Adobe-Japan1; CID+18888 -9634 E0100; Adobe-Japan1; CID+18889 -9637 E0100; Adobe-Japan1; CID+22830 -9638 E0100; Adobe-Japan1; CID+19954 -9639 E0100; Adobe-Japan1; CID+22831 -963A E0100; Adobe-Japan1; CID+22832 -963B E0100; Adobe-Japan1; CID+2765 -963C E0100; Adobe-Japan1; CID+18891 -963D E0100; Adobe-Japan1; CID+19955 -963F E0100; Adobe-Japan1; CID+1128 -9640 E0100; Adobe-Japan1; CID+2859 -9641 E0100; Adobe-Japan1; CID+15263 -9642 E0100; Adobe-Japan1; CID+7091 -9644 E0100; Adobe-Japan1; CID+3551 -9646 E0100; Hanyo-Denshi; TK01095450 -9646 E0101; Hanyo-Denshi; TK01095530 -964B E0100; Adobe-Japan1; CID+7094 -964C E0100; Adobe-Japan1; CID+7092 -964D E0100; Adobe-Japan1; CID+2033 -964D E0101; Adobe-Japan1; CID+13447 -964D E0102; Hanyo-Denshi; JA2563 -964D E0102; Moji_Joho; MJ027575 -964D E0103; Hanyo-Denshi; KS472040 -964D E0103; Moji_Joho; MJ027574 -964D E0104; Moji_Joho; MJ027576 -964F E0100; Adobe-Japan1; CID+7093 -9650 E0100; Adobe-Japan1; CID+1910 -9652 E0100; Adobe-Japan1; CID+22833 -9654 E0100; Adobe-Japan1; CID+19956 -9654 E0101; Hanyo-Denshi; JB7053 -9654 E0101; Moji_Joho; MJ027583 -9654 E0102; Hanyo-Denshi; JTBE6E -9654 E0102; Moji_Joho; MJ027584 -9656 E0100; Adobe-Japan1; CID+22834 -9657 E0100; Adobe-Japan1; CID+22835 -9657 E0101; Hanyo-Denshi; JB7055 -9657 E0102; Hanyo-Denshi; TK01095650 -9658 E0100; Adobe-Japan1; CID+15264 -965B E0100; Adobe-Japan1; CID+3605 -965C E0100; Adobe-Japan1; CID+7096 -965D E0100; Adobe-Japan1; CID+7098 -965E E0100; Adobe-Japan1; CID+7097 -965F E0100; Adobe-Japan1; CID+7099 -965F E0101; Hanyo-Denshi; JA8002 -965F E0101; Moji_Joho; MJ027596 -965F E0102; Hanyo-Denshi; FT2662 -965F E0102; Moji_Joho; MJ027597 -9661 E0100; Adobe-Japan1; CID+18892 -9662 E0100; Adobe-Japan1; CID+1219 -9663 E0100; Adobe-Japan1; CID+2590 -9664 E0100; Adobe-Japan1; CID+2438 -9665 E0100; Adobe-Japan1; CID+1557 -9666 E0100; Adobe-Japan1; CID+7100 -966A E0100; Adobe-Japan1; CID+3356 -966C E0100; Adobe-Japan1; CID+7102 -966E E0100; Adobe-Japan1; CID+22836 -9670 E0100; Adobe-Japan1; CID+1220 -9672 E0100; Adobe-Japan1; CID+7101 -9673 E0100; Adobe-Japan1; CID+3040 -9674 E0100; Adobe-Japan1; CID+19957 -9675 E0100; Adobe-Japan1; CID+3989 -9675 E0101; Hanyo-Denshi; JA4645 -9675 E0101; Moji_Joho; MJ027617 -9675 E0102; Hanyo-Denshi; KS472960 -9675 E0102; Moji_Joho; MJ027616 -9676 E0100; Adobe-Japan1; CID+3203 -9676 E0101; Hanyo-Denshi; JA3811 -9676 E0102; Hanyo-Denshi; TK01095960 -9677 E0100; Adobe-Japan1; CID+7095 -9677 E0101; Hanyo-Denshi; JA7992 -9677 E0102; Hanyo-Denshi; TK01095520 -9678 E0100; Adobe-Japan1; CID+3950 -967A E0100; Adobe-Japan1; CID+1893 -967B E0100; Adobe-Japan1; CID+19958 -967B E0101; Hanyo-Denshi; JB7060 -967B E0101; Moji_Joho; MJ027623 -967B E0102; Hanyo-Denshi; KS473640 -967B E0102; Moji_Joho; MJ027624 -967C E0100; Adobe-Japan1; CID+22837 -967D E0100; Adobe-Japan1; CID+3909 -967E E0100; Adobe-Japan1; CID+22838 -967F E0100; Adobe-Japan1; CID+19959 -967F E0101; Moji_Joho; MJ027628 -967F E0102; Moji_Joho; MJ027629 -9681 E0100; Adobe-Japan1; CID+19960 -9681 E0101; Moji_Joho; MJ027631 -9681 E0102; Moji_Joho; MJ027632 -9682 E0100; Adobe-Japan1; CID+18894 -9682 E0101; Hanyo-Denshi; JB7065 -9682 E0101; Moji_Joho; MJ027633 -9682 E0102; Hanyo-Denshi; JTBE7C -9682 E0102; Moji_Joho; MJ027634 -9683 E0100; Adobe-Japan1; CID+19961 -9683 E0101; Hanyo-Denshi; JB7066 -9683 E0102; Hanyo-Denshi; TK01095860 -9684 E0100; Adobe-Japan1; CID+15265 -9685 E0100; Adobe-Japan1; CID+1777 -9686 E0100; Adobe-Japan1; CID+3964 -9686 E0101; Adobe-Japan1; CID+13393 -9686 E0102; Adobe-Japan1; CID+8686 -9686 E0103; Hanyo-Denshi; JA4620 -9686 E0103; Moji_Joho; MJ027639 -9686 E0104; Hanyo-Denshi; IB1029 -9686 E0104; Moji_Joho; MJ027640 -9686 E0105; Hanyo-Denshi; JTBE75 -9686 E0105; Moji_Joho; MJ030190 -9686 E0106; Hanyo-Denshi; JC9361 -9688 E0100; Adobe-Japan1; CID+1790 -9689 E0100; Adobe-Japan1; CID+19962 -968A E0100; Adobe-Japan1; CID+2882 -968A E0101; Adobe-Japan1; CID+13907 -968A E0102; Hanyo-Denshi; JA3466 -968A E0102; Moji_Joho; MJ027645 -968A E0103; Hanyo-Denshi; FT2041 -968A E0103; Moji_Joho; MJ027646 -968A E0104; Hanyo-Denshi; JTBE79S -968A E0104; Moji_Joho; MJ027644 -968B E0100; Adobe-Japan1; CID+6252 -968D E0100; Adobe-Japan1; CID+7103 -968E E0100; Adobe-Japan1; CID+1418 -968F E0100; Adobe-Japan1; CID+2613 -9691 E0100; Adobe-Japan1; CID+22839 -9692 E0100; Hanyo-Denshi; IP9692 -9692 E0101; Hanyo-Denshi; TK01096030 -9694 E0100; Adobe-Japan1; CID+1460 -9694 E0101; Adobe-Japan1; CID+13683 -9694 E0102; Hanyo-Denshi; JA1954 -9694 E0102; Moji_Joho; MJ027657 -9694 E0103; Hanyo-Denshi; JTBE7B -9694 E0103; Moji_Joho; MJ027656 -9695 E0100; Adobe-Japan1; CID+7105 -9696 E0100; Adobe-Japan1; CID+19963 -9697 E0100; Adobe-Japan1; CID+7106 -9698 E0100; Adobe-Japan1; CID+7104 -9698 E0101; Adobe-Japan1; CID+13621 -9698 E0102; Adobe-Japan1; CID+20243 -9698 E0103; Hanyo-Denshi; JA8007 -9698 E0103; Moji_Joho; MJ027661 -9698 E0104; Hanyo-Denshi; FT2663S -9698 E0104; Moji_Joho; MJ027662 -9698 E0105; Hanyo-Denshi; JTBE7F -9698 E0105; Moji_Joho; MJ027664 -9698 E0106; Hanyo-Denshi; JTBE7E -9698 E0106; Moji_Joho; MJ027663 -9699 E0100; Adobe-Japan1; CID+1850 -9699 E0101; Adobe-Japan1; CID+20273 -9699 E0102; Moji_Joho; MJ027665 -9699 E0103; Moji_Joho; MJ027666 -969A E0100; Adobe-Japan1; CID+18896 -969B E0100; Adobe-Japan1; CID+2125 -969C E0100; Adobe-Japan1; CID+2507 -969C E0101; Hanyo-Denshi; JA3067 -969C E0101; Moji_Joho; MJ027669 -969C E0102; Hanyo-Denshi; JTBE81 -969C E0102; Moji_Joho; MJ027670 -969D E0100; Adobe-Japan1; CID+8688 -969F E0100; Adobe-Japan1; CID+22840 -96A0 E0100; Adobe-Japan1; CID+1221 -96A0 E0101; Hanyo-Denshi; JA1703 -96A0 E0101; Moji_Joho; MJ027675 -96A0 E0102; Hanyo-Denshi; KS474430 -96A0 E0102; Moji_Joho; MJ027674 -96A3 E0100; Adobe-Japan1; CID+4001 -96A3 E0101; Adobe-Japan1; CID+13514 -96A3 E0102; Adobe-Japan1; CID+14091 -96A3 E0103; Hanyo-Denshi; JA4657 -96A3 E0103; Moji_Joho; MJ027679 -96A3 E0104; Hanyo-Denshi; KS474580 -96A3 E0104; Moji_Joho; MJ027678 -96A3 E0105; Moji_Joho; MJ027680 -96A4 E0100; Adobe-Japan1; CID+15266 -96A5 E0100; Adobe-Japan1; CID+17185 -96A6 E0100; Adobe-Japan1; CID+22841 -96A7 E0100; Adobe-Japan1; CID+7108 -96A7 E0101; Adobe-Japan1; CID+20244 -96A7 E0102; Hanyo-Denshi; JA8011 -96A7 E0102; Moji_Joho; MJ027685 -96A7 E0103; Hanyo-Denshi; FT2664 -96A7 E0103; Moji_Joho; MJ027686 -96A7 E0104; Hanyo-Denshi; IB1028 -96A7 E0104; Moji_Joho; MJ027684 -96A7 E0105; Hanyo-Denshi; JTBE87 -96A7 E0105; Moji_Joho; MJ027687 -96A8 E0100; Adobe-Japan1; CID+6923 -96A8 E0101; Hanyo-Denshi; JA7814 -96A8 E0101; Moji_Joho; MJ027689 -96A8 E0102; Hanyo-Denshi; FT2625 -96A8 E0102; Moji_Joho; MJ027688 -96A9 E0100; Adobe-Japan1; CID+15267 -96AA E0100; Adobe-Japan1; CID+7107 -96AA E0101; Hanyo-Denshi; JA8010 -96AA E0101; Moji_Joho; MJ027691 -96AA E0102; Hanyo-Denshi; KS474460 -96AA E0102; Moji_Joho; MJ058977 -96AE E0100; Adobe-Japan1; CID+19964 -96AF E0100; Adobe-Japan1; CID+8689 -96B0 E0100; Adobe-Japan1; CID+7111 -96B1 E0100; Adobe-Japan1; CID+7109 -96B1 E0101; Hanyo-Denshi; JA8012 -96B1 E0101; Moji_Joho; MJ027698 -96B1 E0102; Hanyo-Denshi; FT2665 -96B1 E0102; Moji_Joho; MJ027699 -96B2 E0100; Adobe-Japan1; CID+7110 -96B2 E0101; Adobe-Japan1; CID+14257 -96B3 E0100; Adobe-Japan1; CID+18899 -96B4 E0100; Adobe-Japan1; CID+7112 -96B4 E0101; Hanyo-Denshi; JA8015 -96B4 E0101; Moji_Joho; MJ027702 -96B4 E0102; Hanyo-Denshi; KS475300 -96B4 E0102; Moji_Joho; MJ027703 -96B6 E0100; Adobe-Japan1; CID+7113 -96B6 E0101; Hanyo-Denshi; JA8016 -96B6 E0101; Moji_Joho; MJ027706 -96B6 E0102; Hanyo-Denshi; KS475490 -96B6 E0102; Moji_Joho; MJ027705 -96B7 E0100; Adobe-Japan1; CID+4020 -96B8 E0100; Adobe-Japan1; CID+7114 -96B9 E0100; Adobe-Japan1; CID+7115 -96BA E0100; Adobe-Japan1; CID+18900 -96BB E0100; Adobe-Japan1; CID+2669 -96BB E0101; Adobe-Japan1; CID+13877 -96BB E0102; Moji_Joho; MJ027711 -96BB E0103; Moji_Joho; MJ027712 -96BC E0100; Adobe-Japan1; CID+3407 -96BD E0100; Adobe-Japan1; CID+18901 -96C0 E0100; Adobe-Japan1; CID+2627 -96C1 E0100; Adobe-Japan1; CID+1571 -96C4 E0100; Adobe-Japan1; CID+3876 -96C5 E0100; Adobe-Japan1; CID+1389 -96C5 E0101; Adobe-Japan1; CID+13420 -96C5 E0102; Adobe-Japan1; CID+13671 -96C5 E0103; Hanyo-Denshi; JA1877 -96C5 E0103; Moji_Joho; MJ027722 -96C5 E0104; Hanyo-Denshi; KS475980 -96C5 E0104; Moji_Joho; MJ027721 -96C5 E0105; Moji_Joho; MJ027723 -96C6 E0100; Adobe-Japan1; CID+2370 -96C7 E0100; Adobe-Japan1; CID+1935 -96C7 E0101; Adobe-Japan1; CID+13758 -96C7 E0102; Hanyo-Denshi; JA2459 -96C7 E0102; Moji_Joho; MJ027726 -96C7 E0103; Hanyo-Denshi; JTBE8C -96C7 E0103; Moji_Joho; MJ027725 -96C9 E0100; Adobe-Japan1; CID+7118 -96CA E0100; Adobe-Japan1; CID+22842 -96CB E0100; Adobe-Japan1; CID+7117 -96CC E0100; Adobe-Japan1; CID+2241 -96CD E0100; Adobe-Japan1; CID+7119 -96CD E0101; Hanyo-Denshi; JA8022 -96CD E0102; Hanyo-Denshi; TK01096410 -96CE E0100; Adobe-Japan1; CID+7116 -96D1 E0100; Adobe-Japan1; CID+2166 -96D2 E0100; Adobe-Japan1; CID+15268 -96D5 E0100; Adobe-Japan1; CID+7123 -96D5 E0101; Hanyo-Denshi; JA8026 -96D5 E0101; Moji_Joho; MJ027741 -96D5 E0102; Hanyo-Denshi; FT2666 -96D5 E0102; Moji_Joho; MJ027742 -96D6 E0100; Adobe-Japan1; CID+6546 -96D8 E0100; Adobe-Japan1; CID+18904 -96D8 E0101; Hanyo-Denshi; JB7085 -96D8 E0101; Moji_Joho; MJ027747 -96D8 E0102; Hanyo-Denshi; KS477730 -96D8 E0102; Moji_Joho; MJ027746 -96D8 E0103; Hanyo-Denshi; KS477510 -96D8 E0103; Moji_Joho; MJ027745 -96D8 E0104; Moji_Joho; MJ027748 -96D9 E0100; Adobe-Japan1; CID+4331 -96D9 E0101; Adobe-Japan1; CID+13525 -96D9 E0102; Moji_Joho; MJ027749 -96D9 E0103; Moji_Joho; MJ027750 -96DA E0100; Adobe-Japan1; CID+18905 -96DA E0101; Adobe-Japan1; CID+22843 -96DA E0102; Hanyo-Denshi; JB7086 -96DA E0102; Moji_Joho; MJ027752 -96DA E0103; Hanyo-Denshi; KS477710 -96DA E0103; Moji_Joho; MJ027753 -96DA E0104; Hanyo-Denshi; JD9183 -96DA E0104; Moji_Joho; MJ027751 -96DB E0100; Adobe-Japan1; CID+2621 -96DC E0100; Adobe-Japan1; CID+7121 -96DD E0100; Adobe-Japan1; CID+18906 -96DE E0100; Adobe-Japan1; CID+15270 -96DF E0100; Adobe-Japan1; CID+22844 -96E2 E0100; Adobe-Japan1; CID+3949 -96E2 E0101; Hanyo-Denshi; JA4605 -96E2 E0101; Moji_Joho; MJ027760 -96E2 E0102; Hanyo-Denshi; KS477960 -96E2 E0102; Moji_Joho; MJ027761 -96E3 E0100; Adobe-Japan1; CID+13374 -96E3 E0101; Adobe-Japan1; CID+3273 -96E3 E0102; Hanyo-Denshi; JA3881 -96E3 E0102; Moji_Joho; MJ027762 -96E3 E0103; Hanyo-Denshi; IB1030 -96E3 E0103; Moji_Joho; MJ058984 -96E3 E0104; Hanyo-Denshi; JC9367 -96E3 E0105; Hanyo-Denshi; TK01096670 -96E3 E0106; Hanyo-Denshi; TK01096700 -96E3 E0107; Hanyo-Denshi; TK01096710 -96E3 E0108; Moji_Joho; MJ058983 -96E8 E0100; Adobe-Japan1; CID+1229 -96E8 E0101; Adobe-Japan1; CID+13645 -96E8 E0102; Hanyo-Denshi; JA1711 -96E8 E0102; Moji_Joho; MJ027770 -96E8 E0103; Hanyo-Denshi; IB1031 -96E8 E0103; Moji_Joho; MJ027771 -96E9 E0100; Adobe-Japan1; CID+15271 -96E9 E0101; Hanyo-Denshi; JB7090 -96E9 E0101; Moji_Joho; MJ027772 -96E9 E0102; Hanyo-Denshi; KS478810 -96E9 E0102; Moji_Joho; MJ027773 -96EA E0100; Adobe-Japan1; CID+2695 -96EA E0101; Adobe-Japan1; CID+13881 -96EA E0102; Hanyo-Denshi; JA3267 -96EA E0102; Moji_Joho; MJ027775 -96EA E0103; Hanyo-Denshi; JTBE98 -96EA E0103; Moji_Joho; MJ027774 -96EA E0104; Hanyo-Denshi; TK01096830 -96EA E0105; Hanyo-Denshi; TK01096840 -96EB E0100; Adobe-Japan1; CID+2274 -96EF E0100; Adobe-Japan1; CID+17186 -96EF E0101; Moji_Joho; MJ027781 -96EF E0102; Moji_Joho; MJ027782 -96F0 E0100; Adobe-Japan1; CID+3591 -96F0 E0101; Adobe-Japan1; CID+13504 -96F0 E0102; Hanyo-Denshi; JA4223 -96F0 E0102; Moji_Joho; MJ027783 -96F0 E0103; Hanyo-Denshi; FT1671 -96F0 E0103; Moji_Joho; MJ027784 -96F1 E0100; Adobe-Japan1; CID+15272 -96F2 E0100; Adobe-Japan1; CID+1250 -96F6 E0100; Adobe-Japan1; CID+4021 -96F7 E0100; Adobe-Japan1; CID+3925 -96F7 E0101; Hanyo-Denshi; JA4575 -96F7 E0102; Hanyo-Denshi; TK01096890 -96F9 E0100; Adobe-Japan1; CID+7124 -96F9 E0101; Hanyo-Denshi; JA8027 -96F9 E0101; Moji_Joho; MJ027793 -96F9 E0102; Hanyo-Denshi; FT2667S -96F9 E0102; Moji_Joho; MJ027794 -96FA E0100; Adobe-Japan1; CID+22845 -96FB E0100; Adobe-Japan1; CID+3135 -9700 E0100; Adobe-Japan1; CID+2343 -9702 E0100; Adobe-Japan1; CID+15273 -9703 E0100; Adobe-Japan1; CID+19965 -9704 E0100; Adobe-Japan1; CID+7125 -9704 E0101; Hanyo-Denshi; JA8028 -9704 E0101; Moji_Joho; MJ027803 -9704 E0102; Hanyo-Denshi; FT2668 -9704 E0102; Moji_Joho; MJ027804 -9705 E0100; Adobe-Japan1; CID+22846 -9706 E0100; Adobe-Japan1; CID+7126 -9706 E0101; Hanyo-Denshi; JA8029 -9706 E0102; Hanyo-Denshi; JTBE9F -9706 E0102; Moji_Joho; MJ027807 -9706 E0103; Moji_Joho; MJ027806 -9706 E0104; Moji_Joho; MJ027808 -9707 E0100; Adobe-Japan1; CID+2578 -9708 E0100; Adobe-Japan1; CID+7127 -9709 E0100; Adobe-Japan1; CID+15274 -970A E0100; Adobe-Japan1; CID+4022 -970C E0100; Hanyo-Denshi; IP970C -970C E0101; Hanyo-Denshi; TK01097050 -970D E0100; Adobe-Japan1; CID+7122 -970E E0100; Adobe-Japan1; CID+7129 -970F E0100; Adobe-Japan1; CID+7131 -9711 E0100; Adobe-Japan1; CID+7130 -9713 E0100; Adobe-Japan1; CID+7128 -9713 E0101; Moji_Joho; MJ027822 -9713 E0102; Moji_Joho; MJ027823 -9714 E0100; Adobe-Japan1; CID+18908 -9716 E0100; Adobe-Japan1; CID+7132 -9719 E0100; Adobe-Japan1; CID+7133 -9719 E0101; Hanyo-Denshi; JA8036 -9719 E0101; Moji_Joho; MJ027829 -9719 E0102; Hanyo-Denshi; KS480190 -9719 E0102; Moji_Joho; MJ027830 -971A E0100; Adobe-Japan1; CID+22847 -971B E0100; Adobe-Japan1; CID+19966 -971C E0100; Adobe-Japan1; CID+2812 -971D E0100; Adobe-Japan1; CID+22848 -971E E0100; Adobe-Japan1; CID+1378 -9721 E0100; Adobe-Japan1; CID+19967 -9721 E0101; Adobe-Japan1; CID+22849 -9721 E0102; Hanyo-Denshi; JB7107 -9721 E0102; Moji_Joho; MJ027839 -9721 E0103; Hanyo-Denshi; JTBEA6 -9721 E0103; Moji_Joho; MJ027838 -9721 E0104; Hanyo-Denshi; KS480850 -9721 E0104; Moji_Joho; MJ027840 -9722 E0100; Adobe-Japan1; CID+19968 -9723 E0100; Adobe-Japan1; CID+18909 -9724 E0100; Adobe-Japan1; CID+7134 -9724 E0101; Adobe-Japan1; CID+7878 -9724 E0102; Hanyo-Denshi; JA8037 -9724 E0102; Moji_Joho; MJ027844 -9724 E0103; Hanyo-Denshi; FT2005 -9724 E0103; Moji_Joho; MJ027843 -9727 E0100; Adobe-Japan1; CID+3780 -9728 E0100; Adobe-Japan1; CID+19969 -972A E0100; Adobe-Japan1; CID+7135 -972A E0101; Hanyo-Denshi; JA8038 -972A E0101; Moji_Joho; MJ027850 -972A E0102; Hanyo-Denshi; FT2670 -972A E0102; Moji_Joho; MJ027851 -972E E0100; Moji_Joho; MJ027854 -972E E0101; Moji_Joho; MJ027855 -9730 E0100; Adobe-Japan1; CID+7136 -9731 E0100; Adobe-Japan1; CID+19970 -9732 E0100; Adobe-Japan1; CID+4048 -9733 E0100; Adobe-Japan1; CID+8690 -9736 E0100; Adobe-Japan1; CID+18911 -9736 E0101; Hanyo-Denshi; JD9189 -9736 E0101; Moji_Joho; MJ027863 -9736 E0102; Hanyo-Denshi; KS481730 -9736 E0102; Moji_Joho; MJ027864 -9738 E0100; Adobe-Japan1; CID+5140 -9739 E0100; Adobe-Japan1; CID+7137 -973B E0100; Adobe-Japan1; CID+8691 -973D E0100; Adobe-Japan1; CID+7138 -973D E0101; Adobe-Japan1; CID+13622 -973E E0100; Adobe-Japan1; CID+7139 -9741 E0100; Adobe-Japan1; CID+18912 -9742 E0100; Adobe-Japan1; CID+7143 -9743 E0100; Adobe-Japan1; CID+8692 -9744 E0100; Adobe-Japan1; CID+7140 -9744 E0101; Hanyo-Denshi; FT2671 -9744 E0101; Moji_Joho; MJ027880 -9744 E0102; Hanyo-Denshi; JA8043 -9744 E0103; Moji_Joho; MJ027879 -9746 E0100; Adobe-Japan1; CID+7141 -9746 E0101; Hanyo-Denshi; JA8044 -9746 E0101; Moji_Joho; MJ027883 -9746 E0102; Hanyo-Denshi; FT2672 -9746 E0102; Moji_Joho; MJ027882 -9747 E0100; Adobe-Japan1; CID+18913 -9747 E0101; Hanyo-Denshi; JD9191 -9747 E0102; Hanyo-Denshi; TK01097250 -9747 E0103; Hanyo-Denshi; TK01097260 -9748 E0100; Adobe-Japan1; CID+7142 -9748 E0101; Hanyo-Denshi; JA8045 -9748 E0102; Hanyo-Denshi; TK01097100 -9748 E0103; Hanyo-Denshi; TK01097180 -9749 E0100; Adobe-Japan1; CID+7144 -9749 E0101; Hanyo-Denshi; JA8047 -9749 E0101; Moji_Joho; MJ027887 -9749 E0102; Hanyo-Denshi; JTBEAD -9749 E0102; Moji_Joho; MJ027888 -974A E0100; Adobe-Japan1; CID+22850 -974D E0100; Adobe-Japan1; CID+8693 -974E E0100; Adobe-Japan1; CID+17187 -974F E0100; Adobe-Japan1; CID+8694 -9751 E0100; Adobe-Japan1; CID+8695 -9752 E0100; Adobe-Japan1; CID+2664 -9755 E0100; Adobe-Japan1; CID+20314 -9755 E0101; Adobe-Japan1; CID+8696 -9755 E0102; Hanyo-Denshi; JB7118 -9755 E0102; Moji_Joho; MJ027900 -9755 E0103; Hanyo-Denshi; JD9192 -9755 E0103; Moji_Joho; MJ027898 -9755 E0104; Hanyo-Denshi; IB3207 -9755 E0104; Moji_Joho; MJ027899 -9755 E0105; Hanyo-Denshi; TK01097390 -9756 E0100; Adobe-Japan1; CID+3843 -9756 E0101; Adobe-Japan1; CID+8587 -9756 E0102; Hanyo-Denshi; JA4487 -9756 E0103; Hanyo-Denshi; IB3208 -9757 E0100; Adobe-Japan1; CID+18914 -9757 E0101; Hanyo-Denshi; JB7119 -9757 E0101; Moji_Joho; MJ027902 -9757 E0102; Hanyo-Denshi; IB3209 -9757 E0102; Moji_Joho; MJ027903 -9758 E0100; Adobe-Japan1; CID+22851 -9758 E0101; Hanyo-Denshi; JB7120 -9758 E0101; Moji_Joho; MJ027904 -9758 E0102; Hanyo-Denshi; IB1036 -9758 E0102; Moji_Joho; MJ027905 -9759 E0100; Adobe-Japan1; CID+2665 -9759 E0101; Adobe-Japan1; CID+14258 -9759 E0102; Hanyo-Denshi; JA3237 -9759 E0103; Hanyo-Denshi; TK01097430 -9759 E0104; Hanyo-Denshi; TK01097490 -975A E0100; Adobe-Japan1; CID+15275 -975A E0101; Hanyo-Denshi; JB7121 -975A E0101; Moji_Joho; MJ027909 -975A E0102; Hanyo-Denshi; IB1037 -975A E0102; Moji_Joho; MJ027910 -975A E0103; Hanyo-Denshi; TK01084520 -975B E0100; Adobe-Japan1; CID+18915 -975B E0101; Hanyo-Denshi; JB7122 -975B E0101; Moji_Joho; MJ027911 -975B E0102; Hanyo-Denshi; IB1038 -975B E0102; Moji_Joho; MJ027912 -975C E0100; Adobe-Japan1; CID+7145 -975C E0101; Adobe-Japan1; CID+13873 -975C E0102; Adobe-Japan1; CID+13874 -975C E0103; Hanyo-Denshi; JA8048 -975C E0103; Moji_Joho; MJ027913 -975C E0104; Hanyo-Denshi; IB1039 -975C E0104; Moji_Joho; MJ027914 -975C E0105; Hanyo-Denshi; FT2674 -975C E0105; Moji_Joho; MJ027915 -975C E0106; Hanyo-Denshi; TK01097530 -975C E0107; Hanyo-Denshi; TK01097550 -975D E0100; Hanyo-Denshi; IB1040 -975D E0100; Moji_Joho; MJ027919 -975D E0101; Hanyo-Denshi; IP975D -975D E0101; Moji_Joho; MJ027918 -975E E0100; Adobe-Japan1; CID+3463 -975E E0101; Moji_Joho; MJ027920 -975E E0102; Moji_Joho; MJ027921 -9760 E0100; Adobe-Japan1; CID+7146 -9760 E0101; Adobe-Japan1; CID+7879 -9760 E0102; Adobe-Japan1; CID+13623 -9760 E0103; Hanyo-Denshi; JA8049 -9760 E0104; Hanyo-Denshi; FT2006 -9760 E0104; Moji_Joho; MJ027925 -9760 E0105; Moji_Joho; MJ027923 -9760 E0106; Moji_Joho; MJ027924 -9760 E0107; Moji_Joho; MJ027926 -9761 E0100; Adobe-Japan1; CID+7430 -9761 E0101; Hanyo-Denshi; JA8351 -9761 E0101; Moji_Joho; MJ027927 -9761 E0102; Hanyo-Denshi; FT2742SS -9761 E0102; Moji_Joho; MJ027928 -9762 E0100; Adobe-Japan1; CID+3800 -9763 E0100; Adobe-Japan1; CID+15276 -9764 E0100; Adobe-Japan1; CID+7147 -9764 E0101; Hanyo-Denshi; JA8050 -9764 E0101; Moji_Joho; MJ027931 -9764 E0102; Hanyo-Denshi; FT2676S -9764 E0102; Moji_Joho; MJ027932 -9766 E0100; Adobe-Japan1; CID+7148 -9767 E0100; Adobe-Japan1; CID+19971 -9768 E0100; Adobe-Japan1; CID+7149 -9769 E0100; Adobe-Japan1; CID+1461 -9769 E0101; Hanyo-Denshi; JA1955 -9769 E0101; Moji_Joho; MJ027936 -9769 E0102; Hanyo-Denshi; KS484070 -9769 E0102; Moji_Joho; MJ059006 -976A E0100; Adobe-Japan1; CID+18916 -976B E0100; Adobe-Japan1; CID+7151 -976B E0101; Moji_Joho; MJ027938 -976B E0102; Moji_Joho; MJ027939 -976D E0100; Adobe-Japan1; CID+2591 -976D E0101; Adobe-Japan1; CID+7880 -976D E0102; Adobe-Japan1; CID+7971 -976D E0103; Hanyo-Denshi; JA3157 -976D E0103; Moji_Joho; MJ027942 -976D E0104; Hanyo-Denshi; HG1633 -976D E0104; Moji_Joho; MJ027941 -976E E0100; Adobe-Japan1; CID+15277 -9771 E0100; Adobe-Japan1; CID+7152 -9771 E0101; Adobe-Japan1; CID+7710 -9771 E0102; Adobe-Japan1; CID+13624 -9771 E0103; Hanyo-Denshi; JA8055 -9771 E0104; Hanyo-Denshi; FT1831 -9771 E0104; Moji_Joho; MJ027947 -9771 E0105; Moji_Joho; MJ027945 -9771 E0106; Moji_Joho; MJ027946 -9773 E0100; Adobe-Japan1; CID+15278 -9774 E0100; Adobe-Japan1; CID+1786 -9774 E0101; Adobe-Japan1; CID+7667 -9774 E0102; Hanyo-Denshi; JA2304 -9774 E0102; Moji_Joho; MJ027950 -9774 E0103; Hanyo-Denshi; FT1783 -9774 E0103; Moji_Joho; MJ027951 -9776 E0100; Adobe-Japan1; CID+19972 -9777 E0100; Adobe-Japan1; CID+22852 -9778 E0100; Adobe-Japan1; CID+22853 -9778 E0101; Hanyo-Denshi; JB7130 -9778 E0102; Hanyo-Denshi; TK01097670 -9779 E0100; Adobe-Japan1; CID+7153 -9779 E0101; Hanyo-Denshi; JA8056 -9779 E0101; Moji_Joho; MJ027957 -9779 E0102; Hanyo-Denshi; FT2678 -9779 E0102; Moji_Joho; MJ027958 -977A E0100; Adobe-Japan1; CID+7157 -977B E0100; Adobe-Japan1; CID+22854 -977C E0100; Adobe-Japan1; CID+7155 -977D E0100; Adobe-Japan1; CID+19973 -977E E0100; Moji_Joho; MJ027963 -977E E0101; Moji_Joho; MJ027964 -977F E0100; Adobe-Japan1; CID+19974 -9780 E0100; Adobe-Japan1; CID+22855 -9781 E0100; Adobe-Japan1; CID+7156 -9784 E0100; Adobe-Japan1; CID+1489 -9784 E0101; Adobe-Japan1; CID+7653 -9784 E0102; Hanyo-Denshi; JA1983 -9784 E0102; Moji_Joho; MJ027971 -9784 E0103; Hanyo-Denshi; FT1770 -9784 E0103; Moji_Joho; MJ027970 -9785 E0100; Adobe-Japan1; CID+7154 -9786 E0100; Adobe-Japan1; CID+7158 -9786 E0101; Hanyo-Denshi; JA8061 -9786 E0101; Moji_Joho; MJ027973 -9786 E0102; Hanyo-Denshi; JTBECC -9786 E0102; Moji_Joho; MJ027974 -9789 E0100; Adobe-Japan1; CID+22856 -978B E0100; Adobe-Japan1; CID+7159 -978D E0100; Adobe-Japan1; CID+1164 -978F E0100; Adobe-Japan1; CID+7160 -978F E0101; Hanyo-Denshi; JA8063 -978F E0101; Moji_Joho; MJ027983 -978F E0102; Hanyo-Denshi; KS485330 -978F E0102; Moji_Joho; MJ027984 -9790 E0100; Adobe-Japan1; CID+7161 -9795 E0100; Adobe-Japan1; CID+17188 -9796 E0100; Adobe-Japan1; CID+18919 -9797 E0100; Adobe-Japan1; CID+22857 -9798 E0100; Adobe-Japan1; CID+2508 -9798 E0101; Adobe-Japan1; CID+7708 -9798 E0102; Hanyo-Denshi; JA3068 -9798 E0102; Moji_Joho; MJ027992 -9798 E0103; Hanyo-Denshi; FT1829 -9798 E0103; Moji_Joho; MJ027991 -9799 E0100; Adobe-Japan1; CID+19975 -979A E0100; Adobe-Japan1; CID+15279 -979A E0101; Hanyo-Denshi; JB7140 -979A E0101; Moji_Joho; MJ027994 -979A E0102; Hanyo-Denshi; JTBECF -979A E0102; Moji_Joho; MJ027995 -979C E0100; Adobe-Japan1; CID+7162 -979E E0100; Adobe-Japan1; CID+18920 -979F E0100; Adobe-Japan1; CID+19976 -97A0 E0100; Adobe-Japan1; CID+1633 -97A2 E0100; Adobe-Japan1; CID+15280 -97A3 E0100; Adobe-Japan1; CID+7165 -97A6 E0100; Adobe-Japan1; CID+7164 -97A8 E0100; Adobe-Japan1; CID+7163 -97A8 E0101; Hanyo-Denshi; JA8066 -97A8 E0101; Moji_Joho; MJ028008 -97A8 E0102; Hanyo-Denshi; FT2679 -97A8 E0102; Moji_Joho; MJ028009 -97A8 E0103; Hanyo-Denshi; JTBED2 -97A8 E0103; Moji_Joho; MJ028010 -97AB E0100; Adobe-Japan1; CID+6708 -97AC E0100; Adobe-Japan1; CID+19977 -97AD E0100; Adobe-Japan1; CID+3628 -97AD E0101; Adobe-Japan1; CID+20291 -97AD E0102; Moji_Joho; MJ028015 -97AD E0103; Moji_Joho; MJ028016 -97AE E0100; Adobe-Japan1; CID+17189 -97B1 E0100; Adobe-Japan1; CID+18921 -97B2 E0100; Adobe-Japan1; CID+18922 -97B3 E0100; Adobe-Japan1; CID+7166 -97B3 E0101; Hanyo-Denshi; JA8069 -97B3 E0101; Moji_Joho; MJ028021 -97B3 E0102; Hanyo-Denshi; KS486760 -97B3 E0102; Moji_Joho; MJ028022 -97B4 E0100; Adobe-Japan1; CID+7167 -97B5 E0100; Adobe-Japan1; CID+15281 -97B6 E0100; Adobe-Japan1; CID+15282 -97B8 E0100; Adobe-Japan1; CID+22858 -97B8 E0101; Hanyo-Denshi; JB7150 -97B8 E0102; Hanyo-Denshi; KS487040 -97B9 E0100; Adobe-Japan1; CID+19978 -97BA E0100; Adobe-Japan1; CID+17190 -97BC E0100; Adobe-Japan1; CID+22859 -97BE E0100; Adobe-Japan1; CID+18923 -97BE E0101; Hanyo-Denshi; JB7154 -97BE E0101; Moji_Joho; MJ028033 -97BE E0102; Hanyo-Denshi; KS487430 -97BE E0102; Moji_Joho; MJ028034 -97BF E0100; Adobe-Japan1; CID+22860 -97BF E0101; Hanyo-Denshi; JB7155 -97BF E0101; Moji_Joho; MJ028035 -97BF E0102; Hanyo-Denshi; KS487570 -97BF E0102; Moji_Joho; MJ028036 -97C1 E0100; Adobe-Japan1; CID+17191 -97C3 E0100; Adobe-Japan1; CID+7168 -97C3 E0101; Hanyo-Denshi; JA8071 -97C3 E0101; Moji_Joho; MJ028041 -97C3 E0102; Hanyo-Denshi; FT2680 -97C3 E0102; Moji_Joho; MJ028040 -97C4 E0100; Adobe-Japan1; CID+22861 -97C4 E0101; Hanyo-Denshi; JB7157 -97C4 E0101; Moji_Joho; MJ028042 -97C4 E0102; Hanyo-Denshi; KS487880 -97C4 E0102; Moji_Joho; MJ028043 -97C5 E0100; Adobe-Japan1; CID+22862 -97C6 E0100; Adobe-Japan1; CID+7169 -97C6 E0101; Hanyo-Denshi; JA8072 -97C6 E0101; Moji_Joho; MJ028047 -97C6 E0102; Hanyo-Denshi; FT2681 -97C6 E0102; Moji_Joho; MJ028049 -97C6 E0103; Hanyo-Denshi; IB1042S -97C6 E0103; Moji_Joho; MJ028045 -97C6 E0104; Hanyo-Denshi; JTBED6S -97C6 E0104; Moji_Joho; MJ028048 -97C6 E0105; Hanyo-Denshi; JTBED8 -97C6 E0105; Moji_Joho; MJ028046 -97C7 E0100; Adobe-Japan1; CID+22863 -97C8 E0100; Adobe-Japan1; CID+7170 -97C8 E0101; Hanyo-Denshi; JA8073 -97C8 E0101; Moji_Joho; MJ028051 -97C8 E0102; Hanyo-Denshi; KS488060 -97C8 E0102; Moji_Joho; MJ028053 -97C8 E0103; Hanyo-Denshi; KS488000 -97C8 E0103; Moji_Joho; MJ028052 -97C8 E0104; Hanyo-Denshi; FT2682 -97C8 E0104; Moji_Joho; MJ028054 -97C9 E0100; Adobe-Japan1; CID+17192 -97C9 E0101; Hanyo-Denshi; JB7160 -97C9 E0101; Moji_Joho; MJ028055 -97C9 E0102; Hanyo-Denshi; KS488160 -97C9 E0102; Moji_Joho; MJ028056 -97CA E0100; Adobe-Japan1; CID+22864 -97CA E0101; Hanyo-Denshi; JB7161 -97CA E0101; Moji_Joho; MJ028057 -97CA E0102; Hanyo-Denshi; KS488290 -97CA E0102; Moji_Joho; MJ028058 -97CB E0100; Adobe-Japan1; CID+7171 -97CB E0101; Hanyo-Denshi; JA8074 -97CB E0101; Moji_Joho; MJ028060 -97CB E0102; Hanyo-Denshi; JTBEDA -97CB E0102; Moji_Joho; MJ028059 -97CB E0103; Moji_Joho; MJ028061 -97CC E0100; Adobe-Japan1; CID+18924 -97CC E0101; Hanyo-Denshi; JB7162 -97CC E0101; Moji_Joho; MJ028064 -97CC E0102; Hanyo-Denshi; JTBEDCS -97CC E0102; Moji_Joho; MJ028062 -97CC E0103; Hanyo-Denshi; KS488450 -97CC E0103; Moji_Joho; MJ028063 -97CC E0104; Hanyo-Denshi; TK01097770 -97CD E0100; Adobe-Japan1; CID+19979 -97CD E0101; Hanyo-Denshi; JB7163 -97CD E0101; Moji_Joho; MJ028067 -97CD E0102; Hanyo-Denshi; KS488560 -97CD E0102; Moji_Joho; MJ028066 -97CE E0100; Adobe-Japan1; CID+22865 -97CE E0101; Hanyo-Denshi; JB7164 -97CE E0101; Moji_Joho; MJ028069 -97CE E0102; Hanyo-Denshi; KS488610 -97CE E0102; Moji_Joho; MJ028068 -97D0 E0100; Adobe-Japan1; CID+22866 -97D0 E0101; Hanyo-Denshi; JB7165 -97D0 E0101; Moji_Joho; MJ028072 -97D0 E0102; Hanyo-Denshi; KS488710 -97D0 E0102; Moji_Joho; MJ028071 -97D1 E0100; Adobe-Japan1; CID+18925 -97D1 E0101; Hanyo-Denshi; JB7166 -97D1 E0101; Moji_Joho; MJ028074 -97D1 E0102; Hanyo-Denshi; JTBEDDS -97D1 E0102; Moji_Joho; MJ028073 -97D1 E0103; Hanyo-Denshi; IB3216 -97D1 E0103; Moji_Joho; MJ028075 -97D1 E0104; Hanyo-Denshi; TK01097820 -97D3 E0100; Adobe-Japan1; CID+1558 -97D3 E0101; Adobe-Japan1; CID+13694 -97D3 E0102; Hanyo-Denshi; JA2058 -97D3 E0102; Moji_Joho; MJ028078 -97D3 E0103; Hanyo-Denshi; KS488950S -97D3 E0103; Moji_Joho; MJ028077 -97D3 E0104; Hanyo-Denshi; TK01097840 -97D3 E0105; Moji_Joho; MJ028079 -97D4 E0100; Adobe-Japan1; CID+18926 -97D4 E0101; Hanyo-Denshi; JB7167 -97D4 E0101; Moji_Joho; MJ028081 -97D4 E0102; Hanyo-Denshi; KS488960 -97D4 E0102; Moji_Joho; MJ028080 -97D7 E0100; Adobe-Japan1; CID+22867 -97D7 E0101; Hanyo-Denshi; JB7168 -97D7 E0101; Moji_Joho; MJ028085 -97D7 E0102; Hanyo-Denshi; KS489090 -97D7 E0102; Moji_Joho; MJ028084 -97D8 E0100; Adobe-Japan1; CID+18927 -97D8 E0101; Hanyo-Denshi; JB7169 -97D8 E0101; Moji_Joho; MJ028087 -97D8 E0102; Hanyo-Denshi; KS489100S -97D8 E0102; Moji_Joho; MJ028086 -97D9 E0100; Adobe-Japan1; CID+15283 -97D9 E0101; Hanyo-Denshi; JB7170 -97D9 E0101; Moji_Joho; MJ028089 -97D9 E0102; Hanyo-Denshi; JTBEE0S -97D9 E0102; Moji_Joho; MJ028088 -97DB E0100; Adobe-Japan1; CID+17193 -97DB E0101; Hanyo-Denshi; JB7174 -97DB E0101; Moji_Joho; MJ028092 -97DB E0102; Hanyo-Denshi; KS489340 -97DB E0102; Moji_Joho; MJ028091 -97DC E0100; Adobe-Japan1; CID+7172 -97DC E0101; Hanyo-Denshi; JA8075 -97DC E0101; Moji_Joho; MJ028094 -97DC E0102; Hanyo-Denshi; KS489250S -97DC E0102; Moji_Joho; MJ028093 -97DC E0103; Hanyo-Denshi; FT2684S -97DC E0103; Moji_Joho; MJ028096 -97DC E0104; Moji_Joho; MJ028095 -97DD E0100; Adobe-Japan1; CID+22868 -97DD E0101; Hanyo-Denshi; JB7171 -97DD E0101; Moji_Joho; MJ028098 -97DD E0102; Hanyo-Denshi; KS489260 -97DD E0102; Moji_Joho; MJ028097 -97DE E0100; Adobe-Japan1; CID+15284 -97DE E0101; Adobe-Japan1; CID+15406 -97DE E0102; Hanyo-Denshi; JB7172 -97DE E0102; Moji_Joho; MJ028101 -97DE E0103; Hanyo-Denshi; KS489270 -97DE E0103; Moji_Joho; MJ028100 -97DE E0104; Hanyo-Denshi; KS489180S -97DE E0104; Moji_Joho; MJ028099 -97DE E0105; Moji_Joho; MJ028102 -97E0 E0100; Adobe-Japan1; CID+19980 -97E0 E0101; Hanyo-Denshi; JB7173 -97E0 E0101; Moji_Joho; MJ028104 -97E0 E0102; Hanyo-Denshi; KS489330 -97E0 E0102; Moji_Joho; MJ028103 -97E1 E0100; Adobe-Japan1; CID+18928 -97E1 E0101; Hanyo-Denshi; JB7175 -97E1 E0101; Moji_Joho; MJ028105 -97E1 E0102; Hanyo-Denshi; KS489490S -97E1 E0102; Moji_Joho; MJ028106 -97E1 E0103; Hanyo-Denshi; TK01097880 -97E4 E0100; Adobe-Japan1; CID+22869 -97E4 E0101; Hanyo-Denshi; JB7176 -97E4 E0101; Moji_Joho; MJ028111 -97E4 E0102; Hanyo-Denshi; KS489680 -97E4 E0102; Moji_Joho; MJ028110 -97E4 E0103; Hanyo-Denshi; KS489720 -97E4 E0103; Moji_Joho; MJ028112 -97ED E0100; Adobe-Japan1; CID+7173 -97EE E0100; Adobe-Japan1; CID+3289 -97EE E0101; Hanyo-Denshi; JA3903 -97EE E0101; Moji_Joho; MJ028116 -97EE E0102; Hanyo-Denshi; KS489820 -97EE E0102; Moji_Joho; MJ028117 -97EF E0100; Adobe-Japan1; CID+19981 -97F0 E0100; Hanyo-Denshi; IP97F0 -97F0 E0100; Moji_Joho; MJ028119 -97F0 E0101; Hanyo-Denshi; KS489870 -97F0 E0101; Moji_Joho; MJ059020 -97F1 E0100; Adobe-Japan1; CID+18929 -97F1 E0101; Hanyo-Denshi; JB7178 -97F1 E0101; Moji_Joho; MJ028120 -97F1 E0102; Hanyo-Denshi; KS489940 -97F1 E0102; Moji_Joho; MJ059021 -97F2 E0100; Adobe-Japan1; CID+7175 -97F3 E0100; Adobe-Japan1; CID+1339 -97F3 E0101; Adobe-Japan1; CID+13664 -97F3 E0102; Hanyo-Denshi; JA1827 -97F3 E0102; Moji_Joho; MJ028122 -97F3 E0103; Hanyo-Denshi; JTBEE6 -97F3 E0103; Moji_Joho; MJ028123 -97F4 E0100; Adobe-Japan1; CID+15285 -97F5 E0100; Adobe-Japan1; CID+7178 -97F5 E0101; Hanyo-Denshi; JA8081 -97F5 E0101; Moji_Joho; MJ028125 -97F5 E0102; Hanyo-Denshi; KS490220 -97F5 E0102; Moji_Joho; MJ028126 -97F6 E0100; Adobe-Japan1; CID+7177 -97F6 E0101; Hanyo-Denshi; JA8080 -97F6 E0101; Moji_Joho; MJ028127 -97F6 E0102; Hanyo-Denshi; KS490280 -97F6 E0102; Moji_Joho; MJ028128 -97F7 E0100; Adobe-Japan1; CID+22870 -97F8 E0100; Adobe-Japan1; CID+22871 -97F9 E0100; Hanyo-Denshi; IP97F9 -97F9 E0100; Moji_Joho; MJ028131 -97F9 E0101; Hanyo-Denshi; KS490610 -97F9 E0101; Moji_Joho; MJ028132 -97FA E0100; Adobe-Japan1; CID+22872 -97FA E0101; Hanyo-Denshi; JB7182 -97FA E0101; Moji_Joho; MJ028133 -97FA E0102; Hanyo-Denshi; KS490560 -97FA E0102; Moji_Joho; MJ028134 -97FA E0103; Hanyo-Denshi; KS490620 -97FA E0103; Moji_Joho; MJ028135 -97FA E0104; Hanyo-Denshi; TK01097950 -97FB E0100; Adobe-Japan1; CID+1222 -97FB E0101; Hanyo-Denshi; JA1704 -97FB E0101; Moji_Joho; MJ028138 -97FB E0102; Hanyo-Denshi; KS490600 -97FB E0102; Moji_Joho; MJ028137 -97FB E0103; Hanyo-Denshi; JTBEE7 -97FB E0103; Moji_Joho; MJ028139 -97FF E0100; Adobe-Japan1; CID+1721 -97FF E0101; Adobe-Japan1; CID+13337 -97FF E0102; Adobe-Japan1; CID+13726 -97FF E0103; Adobe-Japan1; CID+20245 -97FF E0104; Adobe-Japan1; CID+20246 -97FF E0105; Hanyo-Denshi; JA2233 -97FF E0105; Moji_Joho; MJ028143 -97FF E0106; Hanyo-Denshi; KS490900 -97FF E0106; Moji_Joho; MJ028145 -97FF E0107; Hanyo-Denshi; JTBEE9 -97FF E0107; Moji_Joho; MJ028144 -97FF E0108; Hanyo-Denshi; JC9386 -97FF E0108; Moji_Joho; MJ030305 -97FF E0109; Hanyo-Denshi; JTBEE8 -97FF E0109; Moji_Joho; MJ030306 -9800 E0100; Hanyo-Denshi; IP9800 -9800 E0101; Hanyo-Denshi; KS490910 -9800 E0101; Moji_Joho; MJ028146 -9800 E0102; Hanyo-Denshi; KS490930 -9800 E0102; Moji_Joho; MJ028147 -9800 E0103; Moji_Joho; MJ068047 -9801 E0100; Adobe-Japan1; CID+3607 -9802 E0100; Adobe-Japan1; CID+3030 -9803 E0100; Adobe-Japan1; CID+2066 -9803 E0101; Hanyo-Denshi; JA2602 -9803 E0101; Moji_Joho; MJ028151 -9803 E0102; Hanyo-Denshi; KS491210 -9803 E0102; Moji_Joho; MJ028152 -9804 E0100; Adobe-Japan1; CID+18930 -9804 E0101; Moji_Joho; MJ028153 -9804 E0102; Moji_Joho; MJ028154 -9805 E0100; Adobe-Japan1; CID+2034 -9806 E0100; Adobe-Japan1; CID+2417 -9807 E0100; Adobe-Japan1; CID+19982 -9808 E0100; Adobe-Japan1; CID+2594 -980A E0100; Adobe-Japan1; CID+15286 -980B E0100; Hanyo-Denshi; IP980B -980B E0100; Moji_Joho; MJ028161 -980B E0101; Hanyo-Denshi; KS492000 -980B E0101; Moji_Joho; MJ028162 -980C E0100; Adobe-Japan1; CID+7180 -980C E0101; Adobe-Japan1; CID+13625 -980C E0102; Hanyo-Denshi; JA8083 -980C E0102; Moji_Joho; MJ028163 -980C E0103; Hanyo-Denshi; JA8083S -980C E0103; Moji_Joho; MJ028164 -980D E0100; Adobe-Japan1; CID+18931 -980E E0100; Adobe-Japan1; CID+15287 -980F E0100; Adobe-Japan1; CID+7179 -9810 E0100; Adobe-Japan1; CID+3884 -9811 E0100; Adobe-Japan1; CID+1572 -9811 E0101; Adobe-Japan1; CID+13428 -9811 E0102; Moji_Joho; MJ028169 -9811 E0103; Moji_Joho; MJ028170 -9812 E0100; Adobe-Japan1; CID+3430 -9812 E0101; Adobe-Japan1; CID+13490 -9812 E0102; Hanyo-Denshi; JA4050 -9812 E0102; Moji_Joho; MJ028171 -9812 E0103; Hanyo-Denshi; FT1660 -9812 E0103; Moji_Joho; MJ028172 -9813 E0100; Adobe-Japan1; CID+3252 -9813 E0101; Adobe-Japan1; CID+7764 -9813 E0102; Hanyo-Denshi; JA3860 -9813 E0102; Moji_Joho; MJ028174 -9813 E0103; Hanyo-Denshi; FT1884 -9813 E0103; Moji_Joho; MJ028173 -9813 E0104; Hanyo-Denshi; TK01098020 -9814 E0100; Adobe-Japan1; CID+18932 -9816 E0100; Adobe-Japan1; CID+18933 -9816 E0101; Hanyo-Denshi; JB7189 -9816 E0102; Hanyo-Denshi; TK01098050 -9817 E0100; Adobe-Japan1; CID+2626 -9818 E0100; Adobe-Japan1; CID+3990 -9819 E0100; Adobe-Japan1; CID+22873 -9819 E0101; Hanyo-Denshi; JB7185 -9819 E0101; Moji_Joho; MJ028182 -9819 E0102; Hanyo-Denshi; IB3220 -9819 E0102; Moji_Joho; MJ028183 -981A E0100; Adobe-Japan1; CID+1841 -981C E0100; Adobe-Japan1; CID+22874 -981E E0100; Adobe-Japan1; CID+15288 -9820 E0100; Adobe-Japan1; CID+22875 -9820 E0101; Hanyo-Denshi; JB7192 -9820 E0101; Moji_Joho; MJ028190 -9820 E0102; Hanyo-Denshi; KS492480 -9820 E0102; Moji_Joho; MJ028191 -9821 E0100; Adobe-Japan1; CID+7183 -9823 E0100; Adobe-Japan1; CID+15289 -9824 E0100; Adobe-Japan1; CID+7182 -9824 E0101; Adobe-Japan1; CID+7881 -9824 E0102; Hanyo-Denshi; JA8085 -9824 E0102; Moji_Joho; MJ028195 -9824 E0103; Hanyo-Denshi; FT2008 -9824 E0103; Moji_Joho; MJ028196 -9825 E0100; Adobe-Japan1; CID+18938 -9826 E0100; Adobe-Japan1; CID+19983 -9829 E0100; Hanyo-Denshi; IP9829 -9829 E0100; Moji_Joho; MJ028201 -9829 E0101; Hanyo-Denshi; KS493340 -9829 E0101; Moji_Joho; MJ028202 -982B E0100; Adobe-Japan1; CID+15290 -982C E0100; Adobe-Japan1; CID+3705 -982D E0100; Adobe-Japan1; CID+3204 -982E E0100; Adobe-Japan1; CID+19984 -982F E0100; Adobe-Japan1; CID+22876 -9830 E0100; Adobe-Japan1; CID+7795 -9832 E0100; Adobe-Japan1; CID+18936 -9832 E0101; Hanyo-Denshi; JB7205 -9832 E0101; Moji_Joho; MJ028211 -9832 E0102; Hanyo-Denshi; JTBEEF -9832 E0102; Moji_Joho; MJ028212 -9832 E0103; Hanyo-Denshi; JTBEF0 -9832 E0103; Moji_Joho; MJ028213 -9833 E0100; Adobe-Japan1; CID+18937 -9834 E0100; Adobe-Japan1; CID+1266 -9835 E0100; Adobe-Japan1; CID+22877 -9837 E0100; Adobe-Japan1; CID+7184 -9838 E0100; Adobe-Japan1; CID+7181 -9839 E0100; Adobe-Japan1; CID+14259 -983B E0100; Adobe-Japan1; CID+7788 -983B E0101; Adobe-Japan1; CID+3523 -983B E0102; Hanyo-Denshi; JA4149 -983B E0103; Hanyo-Denshi; JC9391 -983C E0100; Adobe-Japan1; CID+3924 -983D E0100; Adobe-Japan1; CID+7185 -983E E0100; Adobe-Japan1; CID+15291 -9841 E0100; Hanyo-Denshi; IP9841 -9841 E0101; Hanyo-Denshi; TK01098140 -9844 E0100; Adobe-Japan1; CID+22878 -9844 E0101; Hanyo-Denshi; JB7210 -9844 E0101; Moji_Joho; MJ028232 -9844 E0102; Hanyo-Denshi; KS493510 -9844 E0102; Moji_Joho; MJ028233 -9846 E0100; Adobe-Japan1; CID+7186 -9847 E0100; Adobe-Japan1; CID+18939 -9848 E0100; Hanyo-Denshi; IP9848 -9848 E0101; Hanyo-Denshi; TK01072690 -984A E0100; Adobe-Japan1; CID+22879 -984B E0100; Adobe-Japan1; CID+7188 -984C E0100; Adobe-Japan1; CID+2890 -984D E0100; Adobe-Japan1; CID+1465 -984E E0100; Adobe-Japan1; CID+1466 -984E E0101; Hanyo-Denshi; JA1960 -984E E0101; Moji_Joho; MJ028244 -984E E0102; Hanyo-Denshi; KS493940 -984E E0102; Moji_Joho; MJ028245 -984F E0100; Adobe-Japan1; CID+7187 -9851 E0100; Adobe-Japan1; CID+22880 -9852 E0100; Adobe-Japan1; CID+15292 -9852 E0101; Hanyo-Denshi; JB7214 -9852 E0102; Hanyo-Denshi; TK01098240 -9853 E0100; Adobe-Japan1; CID+15293 -9854 E0100; Adobe-Japan1; CID+1573 -9855 E0100; Adobe-Japan1; CID+1894 -9856 E0100; Adobe-Japan1; CID+17194 -9857 E0100; Adobe-Japan1; CID+8697 -9858 E0100; Adobe-Japan1; CID+1574 -9858 E0101; Hanyo-Denshi; JA2074 -9858 E0102; Hanyo-Denshi; TK01098230 -9859 E0100; Adobe-Japan1; CID+15294 -985A E0100; Adobe-Japan1; CID+7752 -985B E0100; Adobe-Japan1; CID+3129 -985B E0101; Hanyo-Denshi; JA3731 -985B E0101; Moji_Joho; MJ028260 -985B E0102; Hanyo-Denshi; KS494150 -985B E0102; Moji_Joho; MJ028259 -985E E0100; Adobe-Japan1; CID+13396 -985E E0101; Adobe-Japan1; CID+4008 -985E E0102; Hanyo-Denshi; JA4664 -985E E0103; Hanyo-Denshi; JC9404 -9862 E0100; Adobe-Japan1; CID+19985 -9863 E0100; Adobe-Japan1; CID+19986 -9865 E0100; Adobe-Japan1; CID+8698 -9866 E0100; Adobe-Japan1; CID+18940 -9867 E0100; Adobe-Japan1; CID+1936 -9867 E0101; Adobe-Japan1; CID+13759 -9867 E0102; Hanyo-Denshi; JA2460 -9867 E0102; Moji_Joho; MJ028273 -9867 E0103; Hanyo-Denshi; JTBEF7 -9867 E0103; Moji_Joho; MJ028272 -986A E0100; Adobe-Japan1; CID+22881 -986B E0100; Adobe-Japan1; CID+7189 -986C E0100; Adobe-Japan1; CID+15295 -986F E0100; Adobe-Japan1; CID+7190 -9870 E0100; Adobe-Japan1; CID+7191 -9870 E0101; Hanyo-Denshi; JA8094 -9870 E0101; Moji_Joho; MJ028282 -9870 E0102; Hanyo-Denshi; FT2685S -9870 E0102; Moji_Joho; MJ028283 -9871 E0100; Adobe-Japan1; CID+7192 -9873 E0100; Adobe-Japan1; CID+7194 -9873 E0101; Adobe-Japan1; CID+13626 -9873 E0102; Moji_Joho; MJ028286 -9873 E0103; Moji_Joho; MJ028287 -9873 E0104; Moji_Joho; MJ028288 -9874 E0100; Adobe-Japan1; CID+7193 -9874 E0101; Hanyo-Denshi; JA8102 -9874 E0101; Moji_Joho; MJ028289 -9874 E0102; Hanyo-Denshi; KS495400 -9874 E0102; Moji_Joho; MJ028290 -98A8 E0100; Adobe-Japan1; CID+3561 -98AA E0100; Adobe-Japan1; CID+7195 -98AB E0100; Adobe-Japan1; CID+18941 -98AD E0100; Adobe-Japan1; CID+18942 -98AE E0100; Adobe-Japan1; CID+22882 -98AF E0100; Adobe-Japan1; CID+7196 -98B0 E0100; Adobe-Japan1; CID+18943 -98B1 E0100; Adobe-Japan1; CID+7197 -98B4 E0100; Adobe-Japan1; CID+19987 -98B6 E0100; Adobe-Japan1; CID+7198 -98B6 E0101; Hanyo-Denshi; JA8107 -98B6 E0101; Moji_Joho; MJ028308 -98B6 E0102; Hanyo-Denshi; FT2687 -98B6 E0102; Moji_Joho; MJ028309 -98B7 E0100; Adobe-Japan1; CID+18945 -98B8 E0100; Adobe-Japan1; CID+15296 -98BA E0100; Adobe-Japan1; CID+15297 -98BB E0100; Adobe-Japan1; CID+18946 -98BC E0100; Adobe-Japan1; CID+18947 -98BE E0100; Hanyo-Denshi; IP98BE -98BE E0100; Moji_Joho; MJ028317 -98BE E0101; Hanyo-Denshi; JTBEFC -98BE E0101; Moji_Joho; MJ028318 -98BF E0100; Adobe-Japan1; CID+15298 -98C2 E0100; Adobe-Japan1; CID+18948 -98C3 E0100; Adobe-Japan1; CID+7200 -98C3 E0101; Adobe-Japan1; CID+13627 -98C4 E0100; Adobe-Japan1; CID+7199 -98C5 E0100; Adobe-Japan1; CID+19988 -98C6 E0100; Adobe-Japan1; CID+7201 -98C7 E0100; Adobe-Japan1; CID+18949 -98C8 E0100; Adobe-Japan1; CID+15299 -98CB E0100; Adobe-Japan1; CID+18950 -98CC E0100; Adobe-Japan1; CID+22883 -98DB E0100; Adobe-Japan1; CID+3464 -98DC E0100; Adobe-Japan1; CID+6201 -98DE E0100; Hanyo-Denshi; TK01000850 -98DE E0101; Hanyo-Denshi; TK01098390 -98DF E0100; Adobe-Japan1; CID+2543 -98DF E0101; Adobe-Japan1; CID+13847 -98DF E0102; Hanyo-Denshi; JA3109 -98DF E0102; Moji_Joho; MJ028338 -98DF E0103; Hanyo-Denshi; JTBEFD -98DF E0103; Moji_Joho; MJ028339 -98DF E0104; Hanyo-Denshi; TK01098400 -98E0 E0100; Adobe-Japan1; CID+13848 -98E1 E0100; Adobe-Japan1; CID+18951 -98E2 E0100; Adobe-Japan1; CID+1612 -98E2 E0101; Adobe-Japan1; CID+13705 -98E2 E0102; Hanyo-Denshi; JA2118 -98E2 E0102; Moji_Joho; MJ028343 -98E2 E0103; Hanyo-Denshi; KS498300 -98E2 E0103; Moji_Joho; MJ028344 -98E2 E0104; Hanyo-Denshi; JTBF05 -98E2 E0104; Moji_Joho; MJ028342 -98E3 E0100; Adobe-Japan1; CID+18952 -98E3 E0101; Hanyo-Denshi; JB7241 -98E3 E0101; Moji_Joho; MJ028346 -98E3 E0102; Hanyo-Denshi; IB1045 -98E3 E0102; Moji_Joho; MJ028345 -98E4 E0100; Hanyo-Denshi; IB1046 -98E4 E0100; Moji_Joho; MJ028347 -98E4 E0101; Hanyo-Denshi; IP98E4 -98E4 E0101; Moji_Joho; MJ028348 -98E5 E0100; Adobe-Japan1; CID+15300 -98E6 E0100; Adobe-Japan1; CID+22884 -98E6 E0101; Hanyo-Denshi; JB7243 -98E6 E0101; Moji_Joho; MJ028351 -98E6 E0102; Hanyo-Denshi; IB1049 -98E6 E0102; Moji_Joho; MJ028350 -98E6 E0103; Hanyo-Denshi; KS498410S -98E6 E0103; Moji_Joho; MJ028352 -98E7 E0100; Adobe-Japan1; CID+17195 -98E9 E0100; Adobe-Japan1; CID+7202 -98E9 E0101; Hanyo-Denshi; JA8111 -98E9 E0101; Moji_Joho; MJ028355 -98E9 E0102; Hanyo-Denshi; FT2688 -98E9 E0102; Moji_Joho; MJ028354 -98EA E0100; Adobe-Japan1; CID+18953 -98EA E0101; Hanyo-Denshi; JB7245 -98EA E0101; Moji_Joho; MJ028357 -98EA E0102; Hanyo-Denshi; IB1051S -98EA E0102; Moji_Joho; MJ028356 -98EB E0100; Adobe-Japan1; CID+7203 -98EB E0101; Adobe-Japan1; CID+14260 -98EB E0102; Hanyo-Denshi; JA8112 -98EB E0102; Moji_Joho; MJ028359 -98EB E0103; Hanyo-Denshi; FT2689 -98EB E0103; Moji_Joho; MJ028358 -98ED E0100; Adobe-Japan1; CID+4289 -98ED E0101; Hanyo-Denshi; JA5012 -98ED E0101; Moji_Joho; MJ028362 -98ED E0102; Hanyo-Denshi; FT2091 -98ED E0102; Moji_Joho; MJ028361 -98EE E0100; Adobe-Japan1; CID+5338 -98EF E0100; Adobe-Japan1; CID+8699 -98EF E0101; Adobe-Japan1; CID+3431 -98EF E0102; Adobe-Japan1; CID+20261 -98EF E0103; Hanyo-Denshi; JA4051 -98EF E0104; Hanyo-Denshi; JTFA2A -98F0 E0100; Adobe-Japan1; CID+18954 -98F1 E0100; Adobe-Japan1; CID+18955 -98F2 E0100; Adobe-Japan1; CID+1215 -98F3 E0100; Adobe-Japan1; CID+18956 -98F4 E0100; Adobe-Japan1; CID+1151 -98F4 E0101; Adobe-Japan1; CID+7634 -98F4 E0102; Hanyo-Denshi; JA1627 -98F4 E0102; Moji_Joho; MJ028369 -98F4 E0103; Hanyo-Denshi; FT1752 -98F4 E0103; Moji_Joho; MJ028370 -98F5 E0100; Hanyo-Denshi; IB1055 -98F5 E0100; Moji_Joho; MJ028371 -98F5 E0101; Hanyo-Denshi; IP98F5 -98F5 E0101; Moji_Joho; MJ028372 -98F6 E0100; Adobe-Japan1; CID+22885 -98F6 E0101; Hanyo-Denshi; JB7247 -98F6 E0101; Moji_Joho; MJ028374 -98F6 E0102; Hanyo-Denshi; IB1056 -98F6 E0102; Moji_Joho; MJ028373 -98FB E0100; Hanyo-Denshi; IB1058 -98FB E0100; Moji_Joho; MJ028379 -98FB E0101; Hanyo-Denshi; IP98FB -98FB E0101; Moji_Joho; MJ028380 -98FC E0100; Adobe-Japan1; CID+2242 -98FC E0101; Adobe-Japan1; CID+8700 -98FC E0102; Hanyo-Denshi; JA2784 -98FC E0103; Hanyo-Denshi; JTFA2B -98FD E0100; Adobe-Japan1; CID+3678 -98FD E0101; Adobe-Japan1; CID+14029 -98FD E0102; Hanyo-Denshi; JA4316 -98FD E0102; Moji_Joho; MJ028382 -98FD E0103; Hanyo-Denshi; KS552570 -98FD E0103; Moji_Joho; MJ028384 -98FD E0104; Hanyo-Denshi; JTBF20 -98FD E0104; Moji_Joho; MJ028383 -98FE E0100; Adobe-Japan1; CID+2534 -98FE E0101; Adobe-Japan1; CID+13844 -98FE E0102; Hanyo-Denshi; JA3094 -98FE E0102; Moji_Joho; MJ028385 -98FE E0103; Hanyo-Denshi; JTBF21 -98FE E0103; Moji_Joho; MJ028386 -9901 E0100; Hanyo-Denshi; IB0455 -9901 E0100; Moji_Joho; MJ028390 -9901 E0101; Hanyo-Denshi; IB1064 -9901 E0101; Moji_Joho; MJ028389 -9902 E0100; Adobe-Japan1; CID+19989 -9902 E0101; Hanyo-Denshi; JB7248 -9902 E0101; Moji_Joho; MJ028392 -9902 E0102; Hanyo-Denshi; IB1065 -9902 E0102; Moji_Joho; MJ028391 -9903 E0100; Adobe-Japan1; CID+7204 -9903 E0101; Adobe-Japan1; CID+14261 -9903 E0102; Hanyo-Denshi; JA8113 -9903 E0102; Moji_Joho; MJ028394 -9903 E0103; Hanyo-Denshi; FT2690 -9903 E0103; Moji_Joho; MJ028393 -9903 E0104; Moji_Joho; MJ028395 -9905 E0100; Adobe-Japan1; CID+3819 -9905 E0101; Adobe-Japan1; CID+7799 -9905 E0102; Hanyo-Denshi; JA4463 -9905 E0102; Moji_Joho; MJ028397 -9905 E0103; Hanyo-Denshi; FT1927 -9905 E0103; Moji_Joho; MJ028398 -9905 E0104; Hanyo-Denshi; TK01098500 -9907 E0100; Adobe-Japan1; CID+22886 -9908 E0100; Adobe-Japan1; CID+18957 -9908 E0101; Hanyo-Denshi; JB7250 -9908 E0102; Hanyo-Denshi; TK01098510 -9909 E0100; Adobe-Japan1; CID+7205 -9909 E0101; Adobe-Japan1; CID+14262 -9909 E0102; Hanyo-Denshi; JA8114 -9909 E0102; Moji_Joho; MJ028404 -9909 E0103; Hanyo-Denshi; FT2691 -9909 E0103; Moji_Joho; MJ028403 -990A E0100; Adobe-Japan1; CID+3910 -990A E0101; Adobe-Japan1; CID+14080 -990A E0102; Hanyo-Denshi; JA4560 -990A E0102; Moji_Joho; MJ028405 -990A E0103; Hanyo-Denshi; JTBF1F -990A E0103; Moji_Joho; MJ059042 -990A E0104; Hanyo-Denshi; JTBF22 -990A E0104; Moji_Joho; MJ028406 -990C E0100; Adobe-Japan1; CID+1252 -990C E0101; Adobe-Japan1; CID+7643 -990C E0102; Adobe-Japan1; CID+13413 -990C E0103; Adobe-Japan1; CID+13650 -990C E0104; Hanyo-Denshi; JA1734 -990C E0104; Moji_Joho; MJ028409 -990C E0105; Hanyo-Denshi; FT1760 -990C E0105; Moji_Joho; MJ028411 -990C E0106; Hanyo-Denshi; JTBF29 -990C E0106; Moji_Joho; MJ028410 -990C E0107; Hanyo-Denshi; JTC100 -990C E0107; Moji_Joho; MJ028413 -990C E0108; Moji_Joho; MJ028408 -990C E0109; Moji_Joho; MJ028412 -9910 E0100; Adobe-Japan1; CID+2191 -9910 E0101; Adobe-Japan1; CID+7970 -9910 E0102; Hanyo-Denshi; JA2733 -9910 E0102; Moji_Joho; MJ028414 -9910 E0103; Hanyo-Denshi; HG1627 -9910 E0103; Moji_Joho; MJ028415 -9911 E0100; Adobe-Japan1; CID+19990 -9911 E0101; Hanyo-Denshi; JB7251 -9911 E0101; Moji_Joho; MJ028417 -9911 E0102; Hanyo-Denshi; IB1070 -9911 E0102; Moji_Joho; MJ028416 -9912 E0100; Adobe-Japan1; CID+7206 -9912 E0101; Hanyo-Denshi; JA8115 -9912 E0101; Moji_Joho; MJ028419 -9912 E0102; Hanyo-Denshi; FT2692 -9912 E0102; Moji_Joho; MJ028420 -9912 E0103; Hanyo-Denshi; IB1071 -9912 E0103; Moji_Joho; MJ028418 -9913 E0100; Adobe-Japan1; CID+1390 -9913 E0101; Adobe-Japan1; CID+13672 -9913 E0102; Hanyo-Denshi; JA1878 -9913 E0102; Moji_Joho; MJ028421 -9913 E0103; Hanyo-Denshi; JTBF40 -9913 E0103; Moji_Joho; MJ028422 -9914 E0100; Adobe-Japan1; CID+7207 -9914 E0101; Hanyo-Denshi; JA8116 -9914 E0101; Moji_Joho; MJ028424 -9914 E0102; Hanyo-Denshi; FT2693 -9914 E0102; Moji_Joho; MJ028423 -9915 E0100; Adobe-Japan1; CID+19991 -9915 E0101; Hanyo-Denshi; JB7252 -9915 E0101; Moji_Joho; MJ028426 -9915 E0102; Hanyo-Denshi; IB0461 -9915 E0102; Moji_Joho; MJ028427 -9915 E0103; Hanyo-Denshi; IB1073 -9915 E0103; Moji_Joho; MJ028425 -9916 E0100; Adobe-Japan1; CID+18960 -9916 E0101; Hanyo-Denshi; JB7253 -9916 E0101; Moji_Joho; MJ028429 -9916 E0102; Hanyo-Denshi; IB1075 -9916 E0102; Moji_Joho; MJ028428 -9917 E0100; Adobe-Japan1; CID+18961 -9917 E0101; Hanyo-Denshi; JB7254 -9917 E0101; Moji_Joho; MJ028431 -9917 E0102; Hanyo-Denshi; IB1076 -9917 E0102; Moji_Joho; MJ028430 -9918 E0100; Adobe-Japan1; CID+7208 -9918 E0101; Hanyo-Denshi; JA8117 -9918 E0101; Moji_Joho; MJ028433 -9918 E0102; Hanyo-Denshi; FT2694 -9918 E0102; Moji_Joho; MJ028432 -991A E0100; Adobe-Japan1; CID+18963 -991A E0101; Hanyo-Denshi; JB7255 -991A E0101; Moji_Joho; MJ028435 -991A E0102; Hanyo-Denshi; IB1078 -991A E0102; Moji_Joho; MJ028434 -991B E0100; Adobe-Japan1; CID+18964 -991B E0101; Hanyo-Denshi; JB7256 -991B E0101; Moji_Joho; MJ028437 -991B E0102; Hanyo-Denshi; IB1079 -991B E0102; Moji_Joho; MJ028436 -991C E0100; Adobe-Japan1; CID+18965 -991C E0101; Hanyo-Denshi; JB7257 -991C E0101; Moji_Joho; MJ028439 -991C E0102; Hanyo-Denshi; IB1081 -991C E0102; Moji_Joho; MJ028438 -991D E0100; Adobe-Japan1; CID+7210 -991D E0101; Hanyo-Denshi; JA8119 -991D E0101; Moji_Joho; MJ028441 -991D E0102; Hanyo-Denshi; FT2702 -991D E0102; Moji_Joho; MJ028440 -991D E0103; Hanyo-Denshi; IB0466 -991D E0103; Moji_Joho; MJ028442 -991E E0100; Adobe-Japan1; CID+7211 -991E E0101; Hanyo-Denshi; JA8120 -991E E0101; Moji_Joho; MJ028444 -991E E0102; Hanyo-Denshi; FT2703 -991E E0102; Moji_Joho; MJ028443 -991F E0100; Adobe-Japan1; CID+22887 -991F E0101; Hanyo-Denshi; JB7258 -991F E0101; Moji_Joho; MJ028446 -991F E0102; Hanyo-Denshi; IB1083 -991F E0102; Moji_Joho; MJ028445 -9920 E0100; Adobe-Japan1; CID+7213 -9920 E0101; Hanyo-Denshi; JA8122 -9920 E0101; Moji_Joho; MJ028448 -9920 E0102; Hanyo-Denshi; FT2705 -9920 E0102; Moji_Joho; MJ028447 -9921 E0100; Adobe-Japan1; CID+7209 -9921 E0101; Adobe-Japan1; CID+20248 -9921 E0102; Hanyo-Denshi; JA8118 -9921 E0102; Moji_Joho; MJ028450 -9921 E0103; Hanyo-Denshi; FT2701 -9921 E0103; Moji_Joho; MJ028449 -9921 E0104; Hanyo-Denshi; TK01098560 -9922 E0100; Adobe-Japan1; CID+22888 -9922 E0101; Hanyo-Denshi; JB7259 -9922 E0101; Moji_Joho; MJ028453 -9922 E0102; Hanyo-Denshi; IB1087 -9922 E0102; Moji_Joho; MJ028452 -9923 E0100; Hanyo-Denshi; IB1088 -9923 E0100; Moji_Joho; MJ028454 -9923 E0101; Hanyo-Denshi; IP9923 -9923 E0101; Moji_Joho; MJ028455 -9924 E0100; Adobe-Japan1; CID+7212 -9924 E0101; Hanyo-Denshi; JA8121 -9924 E0101; Moji_Joho; MJ028457 -9924 E0102; Hanyo-Denshi; FT2704 -9924 E0102; Moji_Joho; MJ028456 -9926 E0100; Adobe-Japan1; CID+22889 -9926 E0101; Hanyo-Denshi; JB7260 -9926 E0101; Moji_Joho; MJ028460 -9926 E0102; Hanyo-Denshi; IB1089 -9926 E0102; Moji_Joho; MJ028459 -9927 E0100; Adobe-Japan1; CID+8701 -9927 E0101; Hanyo-Denshi; JB7261 -9927 E0101; Moji_Joho; MJ028462 -9927 E0102; Hanyo-Denshi; IB1091 -9927 E0102; Moji_Joho; MJ028461 -9927 E0103; Hanyo-Denshi; JTBF5B -9927 E0103; Moji_Joho; MJ028463 -9928 E0100; Adobe-Japan1; CID+1559 -9928 E0101; Adobe-Japan1; CID+8702 -9928 E0102; Hanyo-Denshi; JA2059 -9928 E0103; Hanyo-Denshi; IB0457 -9929 E0100; Hanyo-Denshi; IB1093 -9929 E0100; Moji_Joho; MJ028465 -9929 E0101; Hanyo-Denshi; IP9929 -9929 E0101; Moji_Joho; MJ028466 -9929 E0102; Hanyo-Denshi; KS501480 -9929 E0102; Moji_Joho; MJ028467 -992A E0100; Hanyo-Denshi; IB1101 -992A E0100; Moji_Joho; MJ028468 -992A E0101; Hanyo-Denshi; IP992A -992A E0101; Moji_Joho; MJ028469 -992B E0100; Adobe-Japan1; CID+22890 -992B E0101; Hanyo-Denshi; JB7262 -992B E0101; Moji_Joho; MJ028471 -992B E0102; Hanyo-Denshi; IB1102 -992B E0102; Moji_Joho; MJ028470 -992C E0100; Adobe-Japan1; CID+7214 -992C E0101; Hanyo-Denshi; JA8123 -992C E0101; Moji_Joho; MJ028473 -992C E0102; Hanyo-Denshi; FT2706 -992C E0102; Moji_Joho; MJ028472 -992D E0100; Hanyo-Denshi; IB1103 -992D E0100; Moji_Joho; MJ028474 -992D E0101; Hanyo-Denshi; IP992D -992D E0101; Moji_Joho; MJ028475 -992E E0100; Adobe-Japan1; CID+7215 -992E E0101; Hanyo-Denshi; JA8124 -992E E0101; Moji_Joho; MJ028476 -992E E0102; Hanyo-Denshi; FT2707 -992E E0102; Moji_Joho; MJ028477 -9930 E0100; Hanyo-Denshi; IB1107 -9930 E0100; Moji_Joho; MJ028479 -9930 E0101; Hanyo-Denshi; IP9930 -9930 E0101; Moji_Joho; MJ028480 -9931 E0100; Adobe-Japan1; CID+18967 -9931 E0101; Hanyo-Denshi; JB7263 -9931 E0101; Moji_Joho; MJ028482 -9931 E0102; Hanyo-Denshi; JTBF6D -9931 E0102; Moji_Joho; MJ028481 -9932 E0100; Adobe-Japan1; CID+15301 -9932 E0101; Hanyo-Denshi; JB7264 -9932 E0101; Moji_Joho; MJ028484 -9932 E0102; Hanyo-Denshi; IB1109 -9932 E0102; Moji_Joho; MJ028483 -9933 E0100; Adobe-Japan1; CID+15302 -9933 E0101; Hanyo-Denshi; JB7265 -9933 E0101; Moji_Joho; MJ028486 -9933 E0102; Hanyo-Denshi; IB1111 -9933 E0102; Moji_Joho; MJ028485 -9934 E0100; Adobe-Japan1; CID+22891 -9934 E0101; Hanyo-Denshi; JB7266 -9934 E0101; Moji_Joho; MJ028487 -9934 E0102; Hanyo-Denshi; JTBF73 -9934 E0102; Moji_Joho; MJ028488 -9934 E0103; Hanyo-Denshi; JTC101 -9934 E0103; Moji_Joho; MJ028489 -9935 E0100; Adobe-Japan1; CID+19992 -9936 E0100; Hanyo-Denshi; IB1128 -9936 E0100; Moji_Joho; MJ028491 -9936 E0101; Hanyo-Denshi; IP9936 -9936 E0101; Moji_Joho; MJ028492 -9939 E0100; Adobe-Japan1; CID+22892 -9939 E0101; Hanyo-Denshi; JB7268 -9939 E0101; Moji_Joho; MJ028494 -9939 E0102; Hanyo-Denshi; JTBF7D -9939 E0102; Moji_Joho; MJ028495 -9939 E0103; Hanyo-Denshi; JTBF7E -9939 E0103; Moji_Joho; MJ028493 -993A E0100; Adobe-Japan1; CID+18968 -993A E0101; Hanyo-Denshi; JB7269 -993A E0101; Moji_Joho; MJ028497 -993A E0102; Hanyo-Denshi; JTBF82 -993A E0102; Moji_Joho; MJ028496 -993B E0100; Adobe-Japan1; CID+18969 -993B E0101; Hanyo-Denshi; JB7270 -993B E0101; Moji_Joho; MJ028499 -993B E0102; Hanyo-Denshi; IB1120 -993B E0102; Moji_Joho; MJ028498 -993C E0100; Adobe-Japan1; CID+18970 -993C E0101; Hanyo-Denshi; JB7271 -993C E0101; Moji_Joho; MJ028501 -993C E0102; Hanyo-Denshi; IB1123 -993C E0102; Moji_Joho; MJ028500 -993D E0100; Adobe-Japan1; CID+7216 -993D E0101; Hanyo-Denshi; JA8125 -993D E0101; Moji_Joho; MJ028503 -993D E0102; Hanyo-Denshi; FT2708 -993D E0102; Moji_Joho; MJ028502 -993E E0100; Adobe-Japan1; CID+7217 -993E E0101; Hanyo-Denshi; JA8126 -993E E0101; Moji_Joho; MJ028505 -993E E0102; Hanyo-Denshi; FT2709 -993E E0102; Moji_Joho; MJ028504 -993F E0100; Hanyo-Denshi; IP993F -993F E0100; Moji_Joho; MJ028507 -993F E0101; Hanyo-Denshi; JTBF78 -993F E0101; Moji_Joho; MJ028506 -9940 E0100; Adobe-Japan1; CID+15303 -9940 E0101; Hanyo-Denshi; JB7272 -9940 E0101; Moji_Joho; MJ028509 -9940 E0102; Hanyo-Denshi; IB1126 -9940 E0102; Moji_Joho; MJ028508 -9940 E0103; Hanyo-Denshi; TK01098710 -9940 E0104; Hanyo-Denshi; TK01098730 -9940 E0105; Hanyo-Denshi; TK01098740 -9941 E0100; Adobe-Japan1; CID+18971 -9941 E0101; Hanyo-Denshi; JB7273 -9941 E0101; Moji_Joho; MJ028515 -9941 E0102; Hanyo-Denshi; IB1127 -9941 E0102; Moji_Joho; MJ028514 -9942 E0100; Adobe-Japan1; CID+7218 -9942 E0101; Hanyo-Denshi; JA8127 -9942 E0101; Moji_Joho; MJ028519 -9942 E0102; Hanyo-Denshi; FT2710 -9942 E0102; Moji_Joho; MJ028516 -9942 E0103; Hanyo-Denshi; IB0479 -9942 E0103; Moji_Joho; MJ028517 -9942 E0104; Hanyo-Denshi; IB1129 -9942 E0104; Moji_Joho; MJ028518 -9944 E0100; Hanyo-Denshi; IB1130 -9944 E0100; Moji_Joho; MJ028520 -9944 E0101; Hanyo-Denshi; IP9944 -9944 E0101; Moji_Joho; MJ028521 -9945 E0100; Adobe-Japan1; CID+7220 -9945 E0101; Adobe-Japan1; CID+14263 -9945 E0102; Adobe-Japan1; CID+14264 -9945 E0103; Hanyo-Denshi; JA8129 -9945 E0103; Moji_Joho; MJ028524 -9945 E0104; Hanyo-Denshi; KS502730 -9945 E0104; Moji_Joho; MJ028523 -9945 E0105; Hanyo-Denshi; FT2712 -9945 E0105; Moji_Joho; MJ028522 -9945 E0106; Hanyo-Denshi; TK01098760 -9946 E0100; Adobe-Japan1; CID+18972 -9946 E0101; Hanyo-Denshi; JB7274 -9946 E0101; Moji_Joho; MJ028527 -9946 E0102; Hanyo-Denshi; JTBF97 -9946 E0102; Moji_Joho; MJ028526 -9946 E0103; Hanyo-Denshi; JTC102 -9946 E0103; Moji_Joho; MJ028528 -9947 E0100; Adobe-Japan1; CID+22893 -9947 E0101; Hanyo-Denshi; JB7275 -9947 E0101; Moji_Joho; MJ028530 -9947 E0102; Hanyo-Denshi; IB1134 -9947 E0102; Moji_Joho; MJ028529 -9947 E0103; Moji_Joho; MJ028531 -9948 E0100; Adobe-Japan1; CID+19993 -9948 E0101; Hanyo-Denshi; JB7276 -9948 E0101; Moji_Joho; MJ028533 -9948 E0102; Hanyo-Denshi; IB1136 -9948 E0102; Moji_Joho; MJ028532 -9949 E0100; Adobe-Japan1; CID+7219 -9949 E0101; Hanyo-Denshi; JA8128 -9949 E0101; Moji_Joho; MJ028535 -9949 E0102; Hanyo-Denshi; IB1137 -9949 E0102; Moji_Joho; MJ028534 -9949 E0103; Hanyo-Denshi; FT2711 -9949 E0103; Moji_Joho; MJ028536 -994A E0100; Hanyo-Denshi; IB1143 -994A E0100; Moji_Joho; MJ028537 -994A E0101; Hanyo-Denshi; IP994A -994A E0101; Moji_Joho; MJ028538 -994B E0100; Adobe-Japan1; CID+7222 -994B E0101; Adobe-Japan1; CID+14265 -994B E0102; Hanyo-Denshi; JA8131 -994B E0102; Moji_Joho; MJ028540 -994B E0103; Hanyo-Denshi; FT2714 -994B E0103; Moji_Joho; MJ028539 -994C E0100; Adobe-Japan1; CID+7225 -994C E0101; Hanyo-Denshi; JA8134 -994C E0101; Moji_Joho; MJ028542 -994C E0102; Hanyo-Denshi; IB1146 -994C E0102; Moji_Joho; MJ028541 -994C E0103; Hanyo-Denshi; FT2717 -994C E0103; Moji_Joho; MJ028543 -994D E0100; Adobe-Japan1; CID+15304 -994D E0101; Hanyo-Denshi; JB7277 -994D E0101; Moji_Joho; MJ028545 -994D E0102; Hanyo-Denshi; IB1147 -994D E0102; Moji_Joho; MJ028544 -994E E0100; Adobe-Japan1; CID+18973 -994E E0101; Hanyo-Denshi; JB7278 -994E E0101; Moji_Joho; MJ028547 -994E E0102; Hanyo-Denshi; IB1148 -994E E0102; Moji_Joho; MJ028546 -9950 E0100; Adobe-Japan1; CID+7221 -9950 E0101; Hanyo-Denshi; JA8130 -9950 E0101; Moji_Joho; MJ028550 -9950 E0102; Hanyo-Denshi; FT2713 -9950 E0102; Moji_Joho; MJ028549 -9951 E0100; Adobe-Japan1; CID+7223 -9951 E0101; Hanyo-Denshi; JA8132 -9951 E0101; Moji_Joho; MJ028552 -9951 E0102; Hanyo-Denshi; FT2715 -9951 E0102; Moji_Joho; MJ028551 -9951 E0103; Hanyo-Denshi; JTBFB0 -9951 E0103; Moji_Joho; MJ028553 -9951 E0104; Hanyo-Denshi; JTBFB6 -9951 E0104; Moji_Joho; MJ028554 -9952 E0100; Adobe-Japan1; CID+7224 -9952 E0101; Hanyo-Denshi; JA8133 -9952 E0101; Moji_Joho; MJ028556 -9952 E0102; Hanyo-Denshi; FT2716 -9952 E0102; Moji_Joho; MJ028555 -9952 E0103; Hanyo-Denshi; TK01098750 -9954 E0100; Adobe-Japan1; CID+19994 -9955 E0100; Adobe-Japan1; CID+7226 -9955 E0101; Hanyo-Denshi; JA8135 -9955 E0101; Moji_Joho; MJ028560 -9955 E0102; Hanyo-Denshi; FT2718 -9955 E0102; Moji_Joho; MJ028561 -9956 E0100; Hanyo-Denshi; IB1151 -9956 E0100; Moji_Joho; MJ028562 -9956 E0101; Hanyo-Denshi; IP9956 -9956 E0101; Moji_Joho; MJ028563 -9957 E0100; Adobe-Japan1; CID+1722 -9957 E0101; Adobe-Japan1; CID+7968 -9957 E0102; Adobe-Japan1; CID+13727 -9957 E0103; Adobe-Japan1; CID+20249 -9957 E0104; Hanyo-Denshi; JA2234 -9957 E0104; Moji_Joho; MJ028564 -9957 E0105; Hanyo-Denshi; FT2912 -9957 E0105; Moji_Joho; MJ028567 -9957 E0106; Hanyo-Denshi; JTC0DA -9957 E0106; Moji_Joho; MJ028566 -9957 E0107; Hanyo-Denshi; JTBFB8 -9957 E0107; Moji_Joho; MJ028568 -9957 E0108; Hanyo-Denshi; JTBFBA -9957 E0108; Moji_Joho; MJ028569 -9957 E0109; Hanyo-Denshi; KS503190 -9957 E0109; Moji_Joho; MJ028565 -9957 E010A; Moji_Joho; MJ028570 -9958 E0100; Adobe-Japan1; CID+17196 -9958 E0101; Hanyo-Denshi; JB7280 -9958 E0101; Moji_Joho; MJ028572 -9958 E0102; Hanyo-Denshi; JTBFC0 -9958 E0102; Moji_Joho; MJ028571 -9959 E0100; Adobe-Japan1; CID+22894 -9959 E0101; Hanyo-Denshi; JB7281 -9959 E0101; Moji_Joho; MJ028574 -9959 E0102; Hanyo-Denshi; IB1154 -9959 E0102; Moji_Joho; MJ028573 -9959 E0103; Hanyo-Denshi; KS503870 -9959 E0103; Moji_Joho; MJ028575 -995B E0100; Adobe-Japan1; CID+22895 -995B E0101; Hanyo-Denshi; JB7282 -995B E0101; Moji_Joho; MJ028577 -995B E0102; Hanyo-Denshi; IB0509 -995B E0102; Moji_Joho; MJ028580 -995B E0103; Hanyo-Denshi; IB1157 -995B E0103; Moji_Joho; MJ028578 -995B E0104; Hanyo-Denshi; KS504080 -995B E0104; Moji_Joho; MJ028579 -995C E0100; Adobe-Japan1; CID+15305 -995C E0101; Hanyo-Denshi; JB7283 -995C E0101; Moji_Joho; MJ028582 -995C E0102; Hanyo-Denshi; JTBFC7S -995C E0102; Moji_Joho; MJ028583 -995C E0103; Hanyo-Denshi; KS504100 -995C E0103; Moji_Joho; MJ028581 -995D E0100; Hanyo-Denshi; IB1159 -995D E0100; Moji_Joho; MJ028584 -995D E0101; Hanyo-Denshi; IP995D -995D E0101; Moji_Joho; MJ028585 -995E E0100; Adobe-Japan1; CID+19995 -995E E0101; Hanyo-Denshi; JB7284 -995E E0101; Moji_Joho; MJ028587 -995E E0102; Hanyo-Denshi; IB1160 -995E E0102; Moji_Joho; MJ028586 -995F E0100; Adobe-Japan1; CID+15306 -995F E0101; Hanyo-Denshi; JB7285 -995F E0101; Moji_Joho; MJ028588 -995F E0102; Hanyo-Denshi; IB1161 -995F E0102; Moji_Joho; MJ028589 -9960 E0100; Adobe-Japan1; CID+18974 -9960 E0101; Hanyo-Denshi; JB7286 -9960 E0101; Moji_Joho; MJ028591 -9960 E0102; Hanyo-Denshi; IB1163 -9960 E0102; Moji_Joho; MJ028590 -9961 E0100; Hanyo-Denshi; IB1164 -9961 E0100; Moji_Joho; MJ028592 -9961 E0101; Hanyo-Denshi; IP9961 -9961 E0101; Moji_Joho; MJ028593 -9996 E0100; Adobe-Japan1; CID+2335 -9997 E0100; Adobe-Japan1; CID+7227 -9997 E0101; Hanyo-Denshi; JA8136 -9997 E0102; Hanyo-Denshi; TK01098790 -9998 E0100; Adobe-Japan1; CID+7228 -9999 E0100; Adobe-Japan1; CID+2035 -999B E0100; Adobe-Japan1; CID+22896 -999D E0100; Adobe-Japan1; CID+22897 -999E E0100; Adobe-Japan1; CID+8703 -999F E0100; Adobe-Japan1; CID+22898 -99A3 E0100; Adobe-Japan1; CID+18975 -99A4 E0100; Hanyo-Denshi; IP99A4 -99A4 E0101; Hanyo-Denshi; TK01098870 -99A5 E0100; Adobe-Japan1; CID+7229 -99A6 E0100; Adobe-Japan1; CID+18976 -99A7 E0100; Hanyo-Denshi; IP99A7 -99A7 E0100; Moji_Joho; MJ028614 -99A7 E0101; Hanyo-Denshi; KS505220 -99A7 E0101; Moji_Joho; MJ028613 -99A8 E0100; Adobe-Japan1; CID+1436 -99A8 E0101; Hanyo-Denshi; JA1930 -99A8 E0102; Hanyo-Denshi; TK01098920 -99AC E0100; Adobe-Japan1; CID+3333 -99AD E0100; Adobe-Japan1; CID+7230 -99AE E0100; Adobe-Japan1; CID+7231 -99B0 E0100; Adobe-Japan1; CID+22899 -99B0 E0101; Hanyo-Denshi; JB7291 -99B0 E0101; Moji_Joho; MJ028623 -99B0 E0102; Hanyo-Denshi; JTBFD5 -99B0 E0102; Moji_Joho; MJ028624 -99B1 E0100; Adobe-Japan1; CID+15307 -99B2 E0100; Adobe-Japan1; CID+22900 -99B3 E0100; Adobe-Japan1; CID+2968 -99B4 E0100; Adobe-Japan1; CID+3267 -99B5 E0100; Adobe-Japan1; CID+22901 -99B7 E0100; Hanyo-Denshi; IP99B7 -99B7 E0100; Moji_Joho; MJ028631 -99B7 E0101; Hanyo-Denshi; JT99B7 -99B7 E0101; Moji_Joho; MJ028632 -99B9 E0100; Adobe-Japan1; CID+15308 -99BA E0100; Adobe-Japan1; CID+15309 -99BA E0101; Hanyo-Denshi; JB7302 -99BA E0101; Moji_Joho; MJ028635 -99BA E0102; Hanyo-Denshi; JTBFD8 -99BA E0102; Moji_Joho; MJ028636 -99BC E0100; Adobe-Japan1; CID+7232 -99BC E0101; Moji_Joho; MJ028638 -99BC E0102; Moji_Joho; MJ028639 -99BD E0100; Adobe-Japan1; CID+18977 -99BF E0100; Adobe-Japan1; CID+18978 -99C1 E0100; Adobe-Japan1; CID+3379 -99C1 E0101; Adobe-Japan1; CID+20288 -99C1 E0102; Moji_Joho; MJ028644 -99C1 E0103; Moji_Joho; MJ028645 -99C3 E0100; Adobe-Japan1; CID+18979 -99C4 E0100; Adobe-Japan1; CID+2860 -99C5 E0100; Adobe-Japan1; CID+1274 -99C6 E0100; Adobe-Japan1; CID+1766 -99C8 E0100; Adobe-Japan1; CID+1767 -99C9 E0100; Adobe-Japan1; CID+15310 -99D0 E0100; Adobe-Japan1; CID+2993 -99D0 E0101; Adobe-Japan1; CID+13927 -99D0 E0102; Hanyo-Denshi; JA3583 -99D0 E0102; Moji_Joho; MJ028659 -99D0 E0103; Hanyo-Denshi; JTBFDB -99D0 E0103; Moji_Joho; MJ028660 -99D1 E0100; Adobe-Japan1; CID+7237 -99D2 E0100; Adobe-Japan1; CID+1768 -99D3 E0100; Adobe-Japan1; CID+22902 -99D4 E0100; Adobe-Japan1; CID+18980 -99D5 E0100; Adobe-Japan1; CID+1391 -99D8 E0100; Adobe-Japan1; CID+7236 -99D9 E0100; Adobe-Japan1; CID+18981 -99DA E0100; Adobe-Japan1; CID+22903 -99DB E0100; Adobe-Japan1; CID+7234 -99DB E0101; Moji_Joho; MJ028671 -99DB E0102; Moji_Joho; MJ028672 -99DC E0100; Adobe-Japan1; CID+22904 -99DD E0100; Adobe-Japan1; CID+7235 -99DE E0100; Adobe-Japan1; CID+18982 -99DF E0100; Adobe-Japan1; CID+7233 -99E1 E0100; Adobe-Japan1; CID+19996 -99E2 E0100; Adobe-Japan1; CID+7247 -99E6 E0100; Hanyo-Denshi; IP99E6 -99E6 E0101; Hanyo-Denshi; TK01099170 -99E7 E0100; Adobe-Japan1; CID+22905 -99E9 E0100; Hanyo-Denshi; IP99E9 -99E9 E0101; Hanyo-Denshi; TK01099210 -99EA E0100; Adobe-Japan1; CID+22906 -99EB E0100; Adobe-Japan1; CID+22907 -99EC E0100; Adobe-Japan1; CID+22908 -99ED E0100; Adobe-Japan1; CID+7238 -99ED E0101; Hanyo-Denshi; JA8147 -99ED E0101; Moji_Joho; MJ028692 -99ED E0102; Hanyo-Denshi; KS507250 -99ED E0102; Moji_Joho; MJ028693 -99EE E0100; Adobe-Japan1; CID+7239 -99EE E0101; Moji_Joho; MJ028694 -99EE E0102; Moji_Joho; MJ028695 -99F0 E0100; Adobe-Japan1; CID+18984 -99F1 E0100; Adobe-Japan1; CID+7240 -99F2 E0100; Adobe-Japan1; CID+7241 -99F4 E0100; Adobe-Japan1; CID+22909 -99F5 E0100; Adobe-Japan1; CID+22910 -99F8 E0100; Adobe-Japan1; CID+7243 -99F8 E0101; Hanyo-Denshi; JA8152 -99F8 E0101; Moji_Joho; MJ028705 -99F8 E0102; Hanyo-Denshi; FT2722 -99F8 E0102; Moji_Joho; MJ028706 -99F9 E0100; Adobe-Japan1; CID+18985 -99FB E0100; Adobe-Japan1; CID+7242 -99FC E0100; Adobe-Japan1; CID+18986 -99FD E0100; Adobe-Japan1; CID+22911 -99FE E0100; Adobe-Japan1; CID+22912 -99FF E0100; Adobe-Japan1; CID+2403 -99FF E0101; Hanyo-Denshi; JA2957 -99FF E0101; Moji_Joho; MJ028714 -99FF E0102; Hanyo-Denshi; KS507540 -99FF E0102; Moji_Joho; MJ028713 -9A01 E0100; Adobe-Japan1; CID+7244 -9A02 E0100; Adobe-Japan1; CID+15311 -9A03 E0100; Adobe-Japan1; CID+17197 -9A04 E0100; Adobe-Japan1; CID+22913 -9A05 E0100; Adobe-Japan1; CID+7246 -9A08 E0100; Adobe-Japan1; CID+14266 -9A0A E0100; Adobe-Japan1; CID+18987 -9A0B E0100; Adobe-Japan1; CID+22914 -9A0C E0100; Adobe-Japan1; CID+19997 -9A0E E0100; Adobe-Japan1; CID+1613 -9A0F E0100; Adobe-Japan1; CID+7245 -9A10 E0100; Adobe-Japan1; CID+19998 -9A11 E0100; Adobe-Japan1; CID+18988 -9A12 E0100; Adobe-Japan1; CID+2813 -9A13 E0100; Adobe-Japan1; CID+1895 -9A15 E0100; Hanyo-Denshi; IP9A15 -9A15 E0100; Moji_Joho; MJ028736 -9A15 E0101; Hanyo-Denshi; KS508760 -9A15 E0101; Moji_Joho; MJ028737 -9A16 E0100; Adobe-Japan1; CID+15312 -9A19 E0100; Adobe-Japan1; CID+7248 -9A19 E0101; Adobe-Japan1; CID+8003 -9A19 E0102; Hanyo-Denshi; JA8157 -9A19 E0102; Moji_Joho; MJ028742 -9A19 E0103; Hanyo-Denshi; HG1663 -9A19 E0103; Moji_Joho; MJ028741 -9A1A E0100; Adobe-Japan1; CID+18989 -9A1A E0101; Hanyo-Denshi; JD9293 -9A1A E0102; Hanyo-Denshi; TK01099350 -9A1E E0100; Adobe-Japan1; CID+22915 -9A1E E0101; Hanyo-Denshi; JB7331 -9A1E E0101; Moji_Joho; MJ028748 -9A1E E0102; Hanyo-Denshi; KS508740 -9A1E E0102; Moji_Joho; MJ028749 -9A20 E0100; Adobe-Japan1; CID+18990 -9A22 E0100; Adobe-Japan1; CID+22916 -9A23 E0100; Adobe-Japan1; CID+19999 -9A24 E0100; Adobe-Japan1; CID+15313 -9A27 E0100; Adobe-Japan1; CID+15314 -9A28 E0100; Adobe-Japan1; CID+2861 -9A2B E0100; Adobe-Japan1; CID+7249 -9A2D E0100; Adobe-Japan1; CID+15315 -9A2D E0101; Hanyo-Denshi; JB7337 -9A2D E0102; Hanyo-Denshi; TK01099370 -9A2E E0100; Adobe-Japan1; CID+15316 -9A2F E0100; Hanyo-Denshi; IP9A2F -9A2F E0100; Moji_Joho; MJ028767 -9A2F E0101; Hanyo-Denshi; KS509360 -9A2F E0101; Moji_Joho; MJ028768 -9A30 E0100; Adobe-Japan1; CID+3205 -9A30 E0101; Adobe-Japan1; CID+13961 -9A30 E0102; Hanyo-Denshi; JA3813 -9A30 E0102; Moji_Joho; MJ028770 -9A30 E0103; Hanyo-Denshi; JTBFE4 -9A30 E0103; Moji_Joho; MJ028769 -9A31 E0100; Adobe-Japan1; CID+18991 -9A33 E0100; Adobe-Japan1; CID+22917 -9A35 E0100; Adobe-Japan1; CID+22918 -9A36 E0100; Adobe-Japan1; CID+15317 -9A37 E0100; Adobe-Japan1; CID+7250 -9A38 E0100; Adobe-Japan1; CID+15318 -9A3E E0100; Adobe-Japan1; CID+7255 -9A40 E0100; Adobe-Japan1; CID+7253 -9A40 E0101; Hanyo-Denshi; JA8162 -9A40 E0101; Moji_Joho; MJ028786 -9A40 E0102; Hanyo-Denshi; KS509430 -9A40 E0102; Moji_Joho; MJ028787 -9A41 E0100; Adobe-Japan1; CID+20000 -9A41 E0101; Hanyo-Denshi; JB7344 -9A41 E0101; Moji_Joho; MJ028788 -9A41 E0102; Hanyo-Denshi; JTBFE5 -9A41 E0102; Moji_Joho; MJ028789 -9A42 E0100; Adobe-Japan1; CID+7252 -9A43 E0100; Adobe-Japan1; CID+7254 -9A44 E0100; Adobe-Japan1; CID+18992 -9A44 E0101; Hanyo-Denshi; JB7345 -9A44 E0101; Moji_Joho; MJ028792 -9A44 E0102; Hanyo-Denshi; KS509740 -9A44 E0102; Moji_Joho; MJ028793 -9A45 E0100; Adobe-Japan1; CID+7251 -9A45 E0101; Adobe-Japan1; CID+13628 -9A47 E0100; Adobe-Japan1; CID+22919 -9A4A E0100; Adobe-Japan1; CID+15319 -9A4A E0101; Adobe-Japan1; CID+22920 -9A4A E0102; Hanyo-Denshi; JB7346 -9A4A E0102; Moji_Joho; MJ028800 -9A4A E0103; Hanyo-Denshi; JTBFE9S -9A4A E0103; Moji_Joho; MJ028801 -9A4B E0100; Adobe-Japan1; CID+22921 -9A4C E0100; Adobe-Japan1; CID+18993 -9A4D E0100; Adobe-Japan1; CID+7257 -9A4E E0100; Adobe-Japan1; CID+8704 -9A4E E0101; Hanyo-Denshi; JB7349 -9A4E E0101; Moji_Joho; MJ028805 -9A4E E0102; Hanyo-Denshi; IB3253 -9A4E E0102; Moji_Joho; MJ028806 -9A51 E0100; Adobe-Japan1; CID+20001 -9A52 E0100; Adobe-Japan1; CID+7727 -9A54 E0100; Adobe-Japan1; CID+22922 -9A54 E0101; Hanyo-Denshi; JB7351 -9A54 E0101; Moji_Joho; MJ028812 -9A54 E0102; Hanyo-Denshi; JTBFEA -9A54 E0102; Moji_Joho; MJ028813 -9A55 E0100; Adobe-Japan1; CID+7256 -9A56 E0100; Adobe-Japan1; CID+15320 -9A56 E0101; Hanyo-Denshi; JB7352 -9A56 E0101; Moji_Joho; MJ028815 -9A56 E0102; Hanyo-Denshi; JTBFEB -9A56 E0102; Moji_Joho; MJ028817 -9A56 E0103; Hanyo-Denshi; KS510360 -9A56 E0103; Moji_Joho; MJ028816 -9A57 E0100; Adobe-Japan1; CID+7259 -9A58 E0100; Adobe-Japan1; CID+18994 -9A58 E0101; Hanyo-Denshi; JD9305 -9A58 E0101; Moji_Joho; MJ028819 -9A58 E0102; Hanyo-Denshi; KS510370 -9A58 E0102; Moji_Joho; MJ028820 -9A58 E0103; Hanyo-Denshi; TK01099490 -9A5A E0100; Adobe-Japan1; CID+1723 -9A5A E0101; Hanyo-Denshi; JA2235 -9A5A E0101; Moji_Joho; MJ028823 -9A5A E0102; Hanyo-Denshi; KS510270 -9A5A E0102; Moji_Joho; MJ028824 -9A5B E0100; Adobe-Japan1; CID+7258 -9A5B E0101; Hanyo-Denshi; JA8167 -9A5B E0101; Moji_Joho; MJ028825 -9A5B E0102; Hanyo-Denshi; JTBFED -9A5B E0102; Moji_Joho; MJ028826 -9A5D E0100; Adobe-Japan1; CID+22923 -9A5F E0100; Adobe-Japan1; CID+7260 -9A5F E0101; Adobe-Japan1; CID+14267 -9A5F E0102; Hanyo-Denshi; JA8169 -9A5F E0102; Moji_Joho; MJ028830 -9A5F E0103; Hanyo-Denshi; KS510550 -9A5F E0103; Moji_Joho; MJ028831 -9A62 E0100; Adobe-Japan1; CID+7261 -9A64 E0100; Adobe-Japan1; CID+7263 -9A65 E0100; Adobe-Japan1; CID+7262 -9A65 E0101; Adobe-Japan1; CID+14268 -9A65 E0102; Hanyo-Denshi; JA8171 -9A65 E0102; Moji_Joho; MJ028837 -9A65 E0103; Hanyo-Denshi; JTBFEF -9A65 E0103; Moji_Joho; MJ028838 -9A69 E0100; Adobe-Japan1; CID+7264 -9A69 E0101; Hanyo-Denshi; JA8173 -9A69 E0101; Moji_Joho; MJ028842 -9A69 E0102; Hanyo-Denshi; KS510910 -9A69 E0102; Moji_Joho; MJ028843 -9A6A E0100; Adobe-Japan1; CID+7266 -9A6B E0100; Adobe-Japan1; CID+7265 -9AA8 E0100; Adobe-Japan1; CID+2062 -9AA8 E0101; Hanyo-Denshi; JA2592 -9AA8 E0101; Moji_Joho; MJ028848 -9AA8 E0102; Hanyo-Denshi; KS511070 -9AA8 E0102; Moji_Joho; MJ059058 -9AA8 E0103; Hanyo-Denshi; KS511080 -9AA8 E0103; Moji_Joho; MJ059059 -9AAA E0100; Adobe-Japan1; CID+22924 -9AAC E0100; Adobe-Japan1; CID+22925 -9AAD E0100; Adobe-Japan1; CID+7267 -9AAE E0100; Adobe-Japan1; CID+22926 -9AAF E0100; Adobe-Japan1; CID+18996 -9AB0 E0100; Adobe-Japan1; CID+7268 -9AB2 E0100; Adobe-Japan1; CID+22927 -9AB4 E0100; Adobe-Japan1; CID+22928 -9AB5 E0100; Adobe-Japan1; CID+15321 -9AB6 E0100; Adobe-Japan1; CID+15322 -9AB7 E0100; Adobe-Japan1; CID+18998 -9AB8 E0100; Adobe-Japan1; CID+1434 -9AB8 E0101; Hanyo-Denshi; JA1928 -9AB8 E0101; Moji_Joho; MJ028864 -9AB8 E0102; Hanyo-Denshi; KS511860 -9AB8 E0102; Moji_Joho; MJ028865 -9AB9 E0100; Adobe-Japan1; CID+19000 -9ABB E0100; Adobe-Japan1; CID+22929 -9ABC E0100; Adobe-Japan1; CID+7269 -9ABD E0100; Adobe-Japan1; CID+20002 -9ABE E0100; Adobe-Japan1; CID+20003 -9ABE E0101; Moji_Joho; MJ028871 -9ABE E0102; Moji_Joho; MJ028872 -9ABF E0100; Adobe-Japan1; CID+22930 -9ABF E0101; Hanyo-Denshi; JB7365 -9ABF E0101; Moji_Joho; MJ028874 -9ABF E0102; Hanyo-Denshi; KS511870 -9ABF E0102; Moji_Joho; MJ028873 -9AC0 E0100; Adobe-Japan1; CID+7270 -9AC1 E0100; Adobe-Japan1; CID+17198 -9AC3 E0100; Adobe-Japan1; CID+17199 -9AC4 E0100; Adobe-Japan1; CID+2615 -9AC6 E0100; Adobe-Japan1; CID+19002 -9AC8 E0100; Adobe-Japan1; CID+22931 -9AC8 E0101; Hanyo-Denshi; JB7369 -9AC8 E0101; Moji_Joho; MJ028882 -9AC8 E0102; Hanyo-Denshi; KS512640 -9AC8 E0102; Moji_Joho; MJ028883 -9ACE E0100; Adobe-Japan1; CID+17200 -9ACF E0100; Adobe-Japan1; CID+7271 -9AD0 E0100; Adobe-Japan1; CID+19003 -9AD1 E0100; Adobe-Japan1; CID+7272 -9AD2 E0100; Adobe-Japan1; CID+19004 -9AD2 E0101; Hanyo-Denshi; JB7372 -9AD2 E0101; Moji_Joho; MJ028891 -9AD2 E0102; Hanyo-Denshi; KS512960S -9AD2 E0102; Moji_Joho; MJ028892 -9AD3 E0100; Adobe-Japan1; CID+7273 -9AD3 E0101; Hanyo-Denshi; JA8182 -9AD3 E0101; Moji_Joho; MJ028893 -9AD3 E0102; Hanyo-Denshi; FT2725 -9AD3 E0102; Moji_Joho; MJ028894 -9AD4 E0100; Adobe-Japan1; CID+7274 -9AD5 E0100; Adobe-Japan1; CID+19005 -9AD6 E0100; Adobe-Japan1; CID+17201 -9AD6 E0101; Hanyo-Denshi; JB7374 -9AD6 E0101; Moji_Joho; MJ028898 -9AD6 E0102; Hanyo-Denshi; KS513150 -9AD6 E0102; Moji_Joho; MJ028899 -9AD6 E0103; Hanyo-Denshi; JTBFF1S -9AD6 E0103; Moji_Joho; MJ028897 -9AD7 E0100; Adobe-Japan1; CID+22932 -9AD8 E0100; Adobe-Japan1; CID+2036 -9AD9 E0100; Adobe-Japan1; CID+8705 -9ADB E0100; Adobe-Japan1; CID+22933 -9ADC E0100; Adobe-Japan1; CID+8706 -9ADC E0101; Hanyo-Denshi; JB7377 -9ADC E0102; Hanyo-Denshi; TK01099620 -9ADE E0100; Adobe-Japan1; CID+7275 -9ADE E0101; Hanyo-Denshi; JA8184 -9ADE E0102; Hanyo-Denshi; TK01099680 -9ADF E0100; Adobe-Japan1; CID+7276 -9AE0 E0100; Adobe-Japan1; CID+19006 -9AE2 E0100; Adobe-Japan1; CID+7277 -9AE3 E0100; Adobe-Japan1; CID+7278 -9AE4 E0100; Adobe-Japan1; CID+22934 -9AE5 E0100; Adobe-Japan1; CID+19007 -9AE6 E0100; Adobe-Japan1; CID+7279 -9AE7 E0100; Adobe-Japan1; CID+22935 -9AE9 E0100; Adobe-Japan1; CID+19008 -9AEA E0100; Adobe-Japan1; CID+3397 -9AEB E0100; Adobe-Japan1; CID+7281 -9AEC E0100; Adobe-Japan1; CID+22936 -9AED E0100; Adobe-Japan1; CID+3480 -9AEE E0100; Adobe-Japan1; CID+7282 -9AEF E0100; Adobe-Japan1; CID+7280 -9AEF E0101; Adobe-Japan1; CID+14269 -9AEF E0102; Hanyo-Denshi; JA8189 -9AEF E0102; Moji_Joho; MJ028926 -9AEF E0103; Hanyo-Denshi; JTBFF8 -9AEF E0103; Moji_Joho; MJ028927 -9AF1 E0100; Adobe-Japan1; CID+7284 -9AF1 E0101; Hanyo-Denshi; JA8193 -9AF1 E0101; Moji_Joho; MJ028929 -9AF1 E0102; Hanyo-Denshi; FT2726S -9AF1 E0102; Moji_Joho; MJ028930 -9AF2 E0100; Adobe-Japan1; CID+22937 -9AF3 E0100; Adobe-Japan1; CID+22938 -9AF4 E0100; Adobe-Japan1; CID+7283 -9AF5 E0100; Adobe-Japan1; CID+22939 -9AF7 E0100; Adobe-Japan1; CID+7285 -9AF9 E0100; Adobe-Japan1; CID+15323 -9AFA E0100; Adobe-Japan1; CID+22940 -9AFB E0100; Adobe-Japan1; CID+7286 -9AFD E0100; Adobe-Japan1; CID+22941 -9AFF E0100; Adobe-Japan1; CID+22942 -9B00 E0100; Adobe-Japan1; CID+22943 -9B01 E0100; Adobe-Japan1; CID+20004 -9B02 E0100; Adobe-Japan1; CID+17202 -9B03 E0100; Adobe-Japan1; CID+15324 -9B04 E0100; Adobe-Japan1; CID+22944 -9B05 E0100; Adobe-Japan1; CID+22945 -9B06 E0100; Adobe-Japan1; CID+7287 -9B06 E0101; Hanyo-Denshi; JA8202 -9B06 E0101; Moji_Joho; MJ028951 -9B06 E0102; Hanyo-Denshi; FT2727 -9B06 E0102; Moji_Joho; MJ028952 -9B08 E0100; Adobe-Japan1; CID+17203 -9B09 E0100; Adobe-Japan1; CID+20005 -9B0B E0100; Adobe-Japan1; CID+20006 -9B0C E0100; Adobe-Japan1; CID+19009 -9B0D E0100; Adobe-Japan1; CID+20007 -9B0E E0100; Adobe-Japan1; CID+20008 -9B10 E0100; Adobe-Japan1; CID+19010 -9B12 E0100; Adobe-Japan1; CID+19011 -9B12 E0101; Hanyo-Denshi; JB7410 -9B12 E0101; Moji_Joho; MJ028963 -9B12 E0102; Hanyo-Denshi; KS515540 -9B12 E0102; Moji_Joho; MJ028964 -9B16 E0100; Adobe-Japan1; CID+19012 -9B18 E0100; Adobe-Japan1; CID+7288 -9B18 E0101; Adobe-Japan1; CID+14270 -9B18 E0102; Hanyo-Denshi; JA8203 -9B18 E0102; Moji_Joho; MJ028970 -9B18 E0103; Hanyo-Denshi; KS515780 -9B18 E0103; Moji_Joho; MJ028969 -9B19 E0100; Adobe-Japan1; CID+20009 -9B1A E0100; Adobe-Japan1; CID+7289 -9B1B E0100; Adobe-Japan1; CID+22946 -9B1B E0101; Hanyo-Denshi; JB7413 -9B1B E0101; Moji_Joho; MJ028973 -9B1B E0102; Hanyo-Denshi; JTBFFC -9B1B E0102; Moji_Joho; MJ028974 -9B1C E0100; Adobe-Japan1; CID+19013 -9B1D E0100; Adobe-Japan1; CID+20297 -9B1F E0100; Adobe-Japan1; CID+7290 -9B20 E0100; Adobe-Japan1; CID+15325 -9B22 E0100; Adobe-Japan1; CID+7291 -9B23 E0100; Adobe-Japan1; CID+7292 -9B23 E0101; Hanyo-Denshi; JA8207 -9B23 E0101; Moji_Joho; MJ028982 -9B23 E0102; Hanyo-Denshi; JTBFFD -9B23 E0102; Moji_Joho; MJ028981 -9B25 E0100; Adobe-Japan1; CID+7293 -9B26 E0100; Adobe-Japan1; CID+22947 -9B27 E0100; Adobe-Japan1; CID+7294 -9B28 E0100; Adobe-Japan1; CID+7295 -9B29 E0100; Adobe-Japan1; CID+7296 -9B2A E0100; Adobe-Japan1; CID+7297 -9B2B E0100; Adobe-Japan1; CID+19014 -9B2C E0100; Adobe-Japan1; CID+20298 -9B2C E0101; Hanyo-Denshi; JT9B2C -9B2C E0102; Hanyo-Denshi; TK01099780 -9B2D E0100; Adobe-Japan1; CID+17205 -9B2D E0101; Adobe-Japan1; CID+13372 -9B2D E0102; Hanyo-Denshi; JB7418 -9B2D E0102; Moji_Joho; MJ028993 -9B2D E0103; Hanyo-Denshi; KS516740 -9B2D E0103; Moji_Joho; MJ028994 -9B2D E0104; Hanyo-Denshi; JC9431 -9B2D E0104; Moji_Joho; MJ028995 -9B2E E0100; Adobe-Japan1; CID+7298 -9B2E E0101; Adobe-Japan1; CID+7882 -9B2E E0102; Hanyo-Denshi; JA8213 -9B2E E0102; Moji_Joho; MJ028996 -9B2E E0103; Hanyo-Denshi; FT2009S -9B2E E0103; Moji_Joho; MJ028999 -9B2E E0104; Hanyo-Denshi; JTC002 -9B2E E0104; Moji_Joho; MJ028998 -9B2E E0105; Moji_Joho; MJ028997 -9B2E E0106; Moji_Joho; MJ029000 -9B2F E0100; Adobe-Japan1; CID+7299 -9B31 E0100; Adobe-Japan1; CID+5332 -9B32 E0100; Adobe-Japan1; CID+7300 -9B32 E0101; Hanyo-Denshi; JA8215 -9B32 E0101; Moji_Joho; MJ029004 -9B32 E0102; Hanyo-Denshi; KS516930 -9B32 E0102; Moji_Joho; MJ059076 -9B33 E0100; Adobe-Japan1; CID+15326 -9B34 E0100; Adobe-Japan1; CID+15327 -9B35 E0100; Adobe-Japan1; CID+20010 -9B35 E0101; Adobe-Japan1; CID+22948 -9B37 E0100; Adobe-Japan1; CID+22949 -9B39 E0100; Adobe-Japan1; CID+22950 -9B3A E0100; Adobe-Japan1; CID+22951 -9B3B E0100; Adobe-Japan1; CID+6057 -9B3C E0100; Adobe-Japan1; CID+1614 -9B3C E0101; Hanyo-Denshi; JA2120 -9B3C E0101; Moji_Joho; MJ029013 -9B3C E0102; Hanyo-Denshi; KS517760 -9B3C E0102; Moji_Joho; MJ059079 -9B3D E0100; Adobe-Japan1; CID+19015 -9B41 E0100; Adobe-Japan1; CID+1407 -9B42 E0100; Adobe-Japan1; CID+2082 -9B43 E0100; Adobe-Japan1; CID+7302 -9B44 E0100; Adobe-Japan1; CID+7301 -9B45 E0100; Adobe-Japan1; CID+3761 -9B48 E0100; Adobe-Japan1; CID+20011 -9B4B E0100; Adobe-Japan1; CID+19017 -9B4B E0101; Hanyo-Denshi; JB7427 -9B4B E0102; Hanyo-Denshi; TK01099970 -9B4C E0100; Adobe-Japan1; CID+22952 -9B4D E0100; Adobe-Japan1; CID+7304 -9B4D E0101; Adobe-Japan1; CID+13629 -9B4D E0102; Hanyo-Denshi; JA8219 -9B4D E0102; Moji_Joho; MJ029029 -9B4D E0103; Hanyo-Denshi; FT1745 -9B4D E0103; Moji_Joho; MJ029030 -9B4E E0100; Adobe-Japan1; CID+7305 -9B4F E0100; Adobe-Japan1; CID+7303 -9B51 E0100; Adobe-Japan1; CID+7306 -9B51 E0101; Hanyo-Denshi; JA8221 -9B51 E0101; Moji_Joho; MJ029035 -9B51 E0102; Hanyo-Denshi; KS519350S -9B51 E0102; Moji_Joho; MJ029036 -9B54 E0100; Adobe-Japan1; CID+3728 -9B54 E0101; Adobe-Japan1; CID+14043 -9B54 E0102; Hanyo-Denshi; JA4366 -9B54 E0102; Moji_Joho; MJ029040 -9B54 E0103; Hanyo-Denshi; JTC006S -9B54 E0103; Moji_Joho; MJ029039 -9B55 E0100; Adobe-Japan1; CID+20012 -9B56 E0100; Adobe-Japan1; CID+22953 -9B57 E0100; Adobe-Japan1; CID+22954 -9B58 E0100; Adobe-Japan1; CID+7307 -9B58 E0101; Adobe-Japan1; CID+13630 -9B5A E0100; Adobe-Japan1; CID+1685 -9B5B E0100; Adobe-Japan1; CID+22955 -9B5E E0100; Adobe-Japan1; CID+17206 -9B61 E0100; Adobe-Japan1; CID+22956 -9B63 E0100; Adobe-Japan1; CID+19018 -9B65 E0100; Adobe-Japan1; CID+19019 -9B65 E0101; Hanyo-Denshi; JB7436 -9B65 E0102; Hanyo-Denshi; TK01100060 -9B66 E0100; Adobe-Japan1; CID+17207 -9B68 E0100; Adobe-Japan1; CID+20013 -9B6A E0100; Adobe-Japan1; CID+22957 -9B6B E0100; Adobe-Japan1; CID+19020 -9B6C E0100; Adobe-Japan1; CID+19021 -9B6D E0100; Adobe-Japan1; CID+22958 -9B6E E0100; Adobe-Japan1; CID+22959 -9B6F E0100; Adobe-Japan1; CID+4043 -9B72 E0100; Adobe-Japan1; CID+8708 -9B73 E0100; Adobe-Japan1; CID+15328 -9B74 E0100; Adobe-Japan1; CID+7308 -9B75 E0100; Adobe-Japan1; CID+8707 -9B75 E0101; Hanyo-Denshi; JB7445 -9B75 E0101; Moji_Joho; MJ029073 -9B75 E0102; Hanyo-Denshi; JTC008 -9B75 E0102; Moji_Joho; MJ029074 -9B75 E0103; Hanyo-Denshi; TK01100040 -9B76 E0100; Adobe-Japan1; CID+19022 -9B77 E0100; Adobe-Japan1; CID+19023 -9B78 E0100; Adobe-Japan1; CID+22960 -9B79 E0100; Adobe-Japan1; CID+15329 -9B79 E0101; Hanyo-Denshi; JB7448 -9B79 E0102; Hanyo-Denshi; TK01100070 -9B7F E0100; Adobe-Japan1; CID+22961 -9B80 E0100; Adobe-Japan1; CID+20014 -9B83 E0100; Adobe-Japan1; CID+7310 -9B83 E0101; Hanyo-Denshi; JA8225 -9B83 E0101; Moji_Joho; MJ029090 -9B83 E0102; Hanyo-Denshi; FT2728 -9B83 E0102; Moji_Joho; MJ029091 -9B84 E0100; Adobe-Japan1; CID+17208 -9B84 E0101; Hanyo-Denshi; JB7451 -9B84 E0102; Hanyo-Denshi; TK01100120 -9B85 E0100; Adobe-Japan1; CID+22962 -9B86 E0100; Adobe-Japan1; CID+20015 -9B87 E0100; Adobe-Japan1; CID+22963 -9B89 E0100; Adobe-Japan1; CID+22964 -9B8A E0100; Adobe-Japan1; CID+17209 -9B8B E0100; Adobe-Japan1; CID+22965 -9B8D E0100; Adobe-Japan1; CID+22966 -9B8E E0100; Adobe-Japan1; CID+1154 -9B8E E0101; Hanyo-Denshi; JA1630 -9B8E E0101; Moji_Joho; MJ029104 -9B8E E0102; Hanyo-Denshi; JTC00B -9B8E E0102; Moji_Joho; MJ029103 -9B8E E0103; Hanyo-Denshi; JTC00A -9B8E E0103; Moji_Joho; MJ059095 -9B8F E0100; Adobe-Japan1; CID+8709 -9B8F E0101; Hanyo-Denshi; JB7459 -9B8F E0102; Hanyo-Denshi; TK01100100 -9B90 E0100; Adobe-Japan1; CID+20016 -9B91 E0100; Adobe-Japan1; CID+7311 -9B91 E0101; Hanyo-Denshi; JA8226 -9B91 E0101; Moji_Joho; MJ029108 -9B91 E0102; Hanyo-Denshi; FT2729S -9B91 E0102; Moji_Joho; MJ029109 -9B91 E0103; Hanyo-Denshi; TK01100080 -9B92 E0100; Adobe-Japan1; CID+3579 -9B92 E0101; Hanyo-Denshi; JA4211 -9B92 E0101; Moji_Joho; MJ029111 -9B92 E0102; Hanyo-Denshi; JTC00D -9B92 E0102; Moji_Joho; MJ029112 -9B93 E0100; Adobe-Japan1; CID+7309 -9B93 E0101; Hanyo-Denshi; JA8224 -9B93 E0102; Hanyo-Denshi; TK01100110 -9B93 E0103; Hanyo-Denshi; TK01100140 -9B94 E0100; Adobe-Japan1; CID+22967 -9B96 E0100; Adobe-Japan1; CID+7312 -9B97 E0100; Adobe-Japan1; CID+7313 -9B97 E0101; Adobe-Japan1; CID+7883 -9B97 E0102; Hanyo-Denshi; JA8228 -9B97 E0102; Moji_Joho; MJ029119 -9B97 E0103; Hanyo-Denshi; FT2010 -9B97 E0103; Moji_Joho; MJ029120 -9B9A E0100; Adobe-Japan1; CID+22968 -9B9D E0100; Adobe-Japan1; CID+20017 -9B9E E0100; Adobe-Japan1; CID+17210 -9B9F E0100; Adobe-Japan1; CID+7314 -9BA0 E0100; Adobe-Japan1; CID+7315 -9BA0 E0101; Hanyo-Denshi; JA8230 -9BA0 E0101; Moji_Joho; MJ029128 -9BA0 E0102; Hanyo-Denshi; JTC013 -9BA0 E0102; Moji_Joho; MJ029129 -9BA6 E0100; Adobe-Japan1; CID+19024 -9BA7 E0100; Adobe-Japan1; CID+15330 -9BA8 E0100; Adobe-Japan1; CID+7316 -9BA8 E0101; Adobe-Japan1; CID+20250 -9BA8 E0102; Hanyo-Denshi; JA8231 -9BA8 E0103; Hanyo-Denshi; TK01100160 -9BA9 E0100; Adobe-Japan1; CID+22969 -9BAA E0100; Adobe-Japan1; CID+3740 -9BAB E0100; Adobe-Japan1; CID+2171 -9BAB E0101; Adobe-Japan1; CID+20280 -9BAB E0102; Hanyo-Denshi; JA2713 -9BAB E0103; Hanyo-Denshi; JTC011 -9BAB E0103; Moji_Joho; MJ029143 -9BAB E0104; Moji_Joho; MJ029141 -9BAB E0105; Moji_Joho; MJ029142 -9BAC E0100; Adobe-Japan1; CID+19025 -9BAC E0101; Hanyo-Denshi; JB7468 -9BAC E0101; Moji_Joho; MJ029144 -9BAC E0102; Hanyo-Denshi; KS522050 -9BAC E0102; Moji_Joho; MJ029145 -9BAD E0100; Adobe-Japan1; CID+2154 -9BAD E0101; Hanyo-Denshi; JA2690 -9BAD E0102; Hanyo-Denshi; TK01100210 -9BAE E0100; Adobe-Japan1; CID+2737 -9BAE E0101; Adobe-Japan1; CID+20251 -9BAE E0102; Hanyo-Denshi; JA3315 -9BAE E0103; Hanyo-Denshi; TK01100170 -9BB0 E0100; Adobe-Japan1; CID+20018 -9BB1 E0100; Adobe-Japan1; CID+8710 -9BB1 E0101; Hanyo-Denshi; JB7470 -9BB1 E0101; Moji_Joho; MJ029152 -9BB1 E0102; Hanyo-Denshi; JTC012S -9BB1 E0102; Moji_Joho; MJ029153 -9BB1 E0103; Moji_Joho; MJ029154 -9BB2 E0100; Adobe-Japan1; CID+19027 -9BB4 E0100; Adobe-Japan1; CID+7317 -9BB7 E0100; Adobe-Japan1; CID+22970 -9BB8 E0100; Adobe-Japan1; CID+19028 -9BB9 E0100; Adobe-Japan1; CID+7320 -9BB9 E0101; Adobe-Japan1; CID+20252 -9BB9 E0102; Hanyo-Denshi; JA8235 -9BB9 E0102; Moji_Joho; MJ029161 -9BB9 E0103; Hanyo-Denshi; FT2730 -9BB9 E0103; Moji_Joho; MJ029162 -9BBB E0100; Adobe-Japan1; CID+8711 -9BBC E0100; Adobe-Japan1; CID+22971 -9BBC E0101; Hanyo-Denshi; JB7475 -9BBC E0101; Moji_Joho; MJ029165 -9BBC E0102; Hanyo-Denshi; JTC01B -9BBC E0102; Moji_Joho; MJ029166 -9BBE E0100; Adobe-Japan1; CID+19029 -9BBF E0100; Adobe-Japan1; CID+20019 -9BC0 E0100; Adobe-Japan1; CID+7318 -9BC1 E0100; Adobe-Japan1; CID+15331 -9BC1 E0101; Moji_Joho; MJ029171 -9BC1 E0102; Moji_Joho; MJ029172 -9BC6 E0100; Adobe-Japan1; CID+7321 -9BC6 E0101; Adobe-Japan1; CID+13631 -9BC7 E0100; Adobe-Japan1; CID+15332 -9BC8 E0100; Adobe-Japan1; CID+20020 -9BC9 E0100; Adobe-Japan1; CID+1957 -9BC9 E0101; Hanyo-Denshi; JA2481 -9BC9 E0101; Moji_Joho; MJ029180 -9BC9 E0102; Hanyo-Denshi; JTC016 -9BC9 E0102; Moji_Joho; MJ029181 -9BCA E0100; Adobe-Japan1; CID+7319 -9BCE E0100; Adobe-Japan1; CID+17211 -9BCE E0101; Hanyo-Denshi; JB7481 -9BCE E0101; Moji_Joho; MJ029185 -9BCE E0102; Hanyo-Denshi; IB3270 -9BCE E0102; Moji_Joho; MJ029186 -9BCF E0100; Adobe-Japan1; CID+7322 -9BD0 E0100; Adobe-Japan1; CID+22972 -9BD1 E0100; Adobe-Japan1; CID+7323 -9BD2 E0100; Adobe-Japan1; CID+7324 -9BD4 E0100; Adobe-Japan1; CID+7328 -9BD4 E0101; Hanyo-Denshi; JA8243 -9BD4 E0101; Moji_Joho; MJ029191 -9BD4 E0102; Hanyo-Denshi; KS524590 -9BD4 E0102; Moji_Joho; MJ029192 -9BD6 E0100; Adobe-Japan1; CID+2168 -9BD6 E0101; Adobe-Japan1; CID+7689 -9BD6 E0102; Hanyo-Denshi; JA2710 -9BD6 E0102; Moji_Joho; MJ029195 -9BD6 E0103; Hanyo-Denshi; FT1811 -9BD6 E0103; Moji_Joho; MJ029194 -9BD6 E0104; Hanyo-Denshi; TK01100360 -9BD7 E0100; Adobe-Japan1; CID+15333 -9BD8 E0100; Adobe-Japan1; CID+19031 -9BDB E0100; Adobe-Japan1; CID+2884 -9BDB E0101; Adobe-Japan1; CID+13908 -9BDB E0102; Hanyo-Denshi; JA3468 -9BDB E0102; Moji_Joho; MJ029202 -9BDB E0103; Hanyo-Denshi; JTC021 -9BDB E0103; Moji_Joho; MJ029203 -9BDB E0104; Hanyo-Denshi; JTC020 -9BDB E0104; Moji_Joho; MJ029201 -9BDD E0100; Adobe-Japan1; CID+19032 -9BDF E0100; Adobe-Japan1; CID+14271 -9BE1 E0100; Adobe-Japan1; CID+7329 -9BE1 E0101; Adobe-Japan1; CID+13632 -9BE1 E0102; Moji_Joho; MJ029209 -9BE1 E0103; Moji_Joho; MJ029210 -9BE2 E0100; Adobe-Japan1; CID+7326 -9BE3 E0100; Adobe-Japan1; CID+7325 -9BE4 E0100; Adobe-Japan1; CID+7327 -9BE5 E0100; Adobe-Japan1; CID+17212 -9BE7 E0100; Adobe-Japan1; CID+15334 -9BE8 E0100; Adobe-Japan1; CID+1845 -9BE8 E0101; Hanyo-Denshi; JA2363 -9BE8 E0101; Moji_Joho; MJ029217 -9BE8 E0102; Hanyo-Denshi; JTC01E -9BE8 E0102; Moji_Joho; MJ029218 -9BEA E0100; Adobe-Japan1; CID+19033 -9BEB E0100; Adobe-Japan1; CID+15335 -9BEB E0101; Moji_Joho; MJ029221 -9BEB E0102; Moji_Joho; MJ029222 -9BEE E0100; Adobe-Japan1; CID+19035 -9BEF E0100; Adobe-Japan1; CID+19034 -9BF0 E0100; Adobe-Japan1; CID+7333 -9BF0 E0101; Hanyo-Denshi; JA8248 -9BF0 E0101; Moji_Joho; MJ029228 -9BF0 E0102; Hanyo-Denshi; JTC01D -9BF0 E0102; Moji_Joho; MJ029227 -9BF1 E0100; Adobe-Japan1; CID+7332 -9BF1 E0101; Adobe-Japan1; CID+13633 -9BF1 E0102; Hanyo-Denshi; JA8247 -9BF1 E0102; Moji_Joho; MJ029229 -9BF1 E0103; Hanyo-Denshi; FT1747 -9BF1 E0103; Moji_Joho; MJ029230 -9BF1 E0104; Hanyo-Denshi; TK01100270 -9BF1 E0105; Hanyo-Denshi; TK01100290 -9BF2 E0100; Adobe-Japan1; CID+7331 -9BF2 E0101; Adobe-Japan1; CID+7884 -9BF2 E0102; Hanyo-Denshi; JA8246 -9BF2 E0102; Moji_Joho; MJ029234 -9BF2 E0103; Hanyo-Denshi; FT2011S -9BF2 E0103; Moji_Joho; MJ029233 -9BF3 E0100; Adobe-Japan1; CID+19030 -9BF5 E0100; Adobe-Japan1; CID+1143 -9BF5 E0101; Hanyo-Denshi; JA1619 -9BF5 E0101; Moji_Joho; MJ029236 -9BF5 E0102; Hanyo-Denshi; JTC01F -9BF5 E0102; Moji_Joho; MJ029237 -9BF7 E0100; Adobe-Japan1; CID+15336 -9BF8 E0100; Adobe-Japan1; CID+17213 -9BF9 E0100; Adobe-Japan1; CID+22973 -9BFA E0100; Adobe-Japan1; CID+15337 -9BFD E0100; Adobe-Japan1; CID+15338 -9BFD E0101; Hanyo-Denshi; JB7503 -9BFD E0101; Moji_Joho; MJ029245 -9BFD E0102; Hanyo-Denshi; IB3275 -9BFD E0102; Moji_Joho; MJ029246 -9BFF E0100; Adobe-Japan1; CID+20021 -9C00 E0100; Adobe-Japan1; CID+8712 -9C00 E0101; Hanyo-Denshi; JB7505 -9C00 E0101; Moji_Joho; MJ029249 -9C00 E0102; Hanyo-Denshi; JTC029 -9C00 E0102; Moji_Joho; MJ029250 -9C00 E0103; Hanyo-Denshi; TK01100410 -9C02 E0100; Adobe-Japan1; CID+20022 -9C04 E0100; Adobe-Japan1; CID+7343 -9C06 E0100; Adobe-Japan1; CID+7339 -9C08 E0100; Adobe-Japan1; CID+7340 -9C08 E0101; Adobe-Japan1; CID+20253 -9C09 E0100; Adobe-Japan1; CID+7336 -9C0A E0100; Adobe-Japan1; CID+7342 -9C0B E0100; Adobe-Japan1; CID+15339 -9C0B E0101; Moji_Joho; MJ029263 -9C0B E0102; Moji_Joho; MJ029264 -9C0C E0100; Adobe-Japan1; CID+7338 -9C0C E0101; Hanyo-Denshi; JA8253 -9C0C E0101; Moji_Joho; MJ029265 -9C0C E0102; Hanyo-Denshi; JTC030 -9C0C E0102; Moji_Joho; MJ029267 -9C0C E0103; Hanyo-Denshi; FT2731 -9C0C E0103; Moji_Joho; MJ029266 -9C0D E0100; Adobe-Japan1; CID+1472 -9C0F E0100; Adobe-Japan1; CID+22974 -9C10 E0100; Adobe-Japan1; CID+4082 -9C10 E0101; Hanyo-Denshi; JA4744 -9C10 E0101; Moji_Joho; MJ029272 -9C10 E0102; Hanyo-Denshi; KS524580 -9C10 E0102; Moji_Joho; MJ029273 -9C10 E0103; Hanyo-Denshi; JTC027 -9C10 E0103; Moji_Joho; MJ029271 -9C11 E0100; Adobe-Japan1; CID+22975 -9C12 E0100; Adobe-Japan1; CID+7341 -9C13 E0100; Adobe-Japan1; CID+7337 -9C14 E0100; Adobe-Japan1; CID+7335 -9C15 E0100; Adobe-Japan1; CID+7334 -9C16 E0100; Adobe-Japan1; CID+19039 -9C18 E0100; Adobe-Japan1; CID+19040 -9C19 E0100; Adobe-Japan1; CID+19041 -9C19 E0101; Hanyo-Denshi; JB7512 -9C19 E0101; Moji_Joho; MJ029282 -9C19 E0102; Hanyo-Denshi; KS524380 -9C19 E0102; Moji_Joho; MJ029283 -9C1A E0100; Adobe-Japan1; CID+19042 -9C1B E0100; Adobe-Japan1; CID+7345 -9C1C E0100; Adobe-Japan1; CID+20023 -9C1D E0100; Adobe-Japan1; CID+19043 -9C1D E0101; Hanyo-Denshi; JD9366 -9C1D E0102; Hanyo-Denshi; TK01100440 -9C1E E0100; Adobe-Japan1; CID+22976 -9C1F E0100; Hanyo-Denshi; IP9C1F -9C1F E0100; Moji_Joho; MJ029290 -9C1F E0101; Hanyo-Denshi; KS525370 -9C1F E0101; Moji_Joho; MJ029291 -9C21 E0100; Adobe-Japan1; CID+7348 -9C21 E0101; Hanyo-Denshi; JA8263 -9C21 E0101; Moji_Joho; MJ029293 -9C21 E0102; Hanyo-Denshi; JTC037 -9C21 E0102; Moji_Joho; MJ029294 -9C22 E0100; Adobe-Japan1; CID+19044 -9C22 E0101; Hanyo-Denshi; JB7516 -9C22 E0101; Moji_Joho; MJ029296 -9C22 E0102; Hanyo-Denshi; IB0285 -9C22 E0102; Moji_Joho; MJ029295 -9C23 E0100; Adobe-Japan1; CID+17214 -9C24 E0100; Adobe-Japan1; CID+7347 -9C24 E0101; Adobe-Japan1; CID+20254 -9C25 E0100; Adobe-Japan1; CID+7346 -9C26 E0100; Adobe-Japan1; CID+22977 -9C26 E0101; Hanyo-Denshi; JB7518 -9C26 E0101; Moji_Joho; MJ029300 -9C26 E0102; Hanyo-Denshi; KS524860 -9C26 E0102; Moji_Joho; MJ029301 -9C27 E0100; Adobe-Japan1; CID+15340 -9C27 E0101; Hanyo-Denshi; JB7519 -9C27 E0101; Moji_Joho; MJ029302 -9C27 E0102; Hanyo-Denshi; JTC036 -9C27 E0102; Moji_Joho; MJ029303 -9C28 E0100; Adobe-Japan1; CID+22978 -9C29 E0100; Adobe-Japan1; CID+19045 -9C2A E0100; Adobe-Japan1; CID+15341 -9C2D E0100; Adobe-Japan1; CID+3515 -9C2D E0101; Hanyo-Denshi; JA4141 -9C2D E0101; Moji_Joho; MJ029309 -9C2D E0102; Hanyo-Denshi; JTC032 -9C2D E0102; Moji_Joho; MJ029310 -9C2E E0100; Adobe-Japan1; CID+7344 -9C2F E0100; Adobe-Japan1; CID+1207 -9C2F E0101; Adobe-Japan1; CID+7636 -9C2F E0102; Hanyo-Denshi; JA1683 -9C2F E0102; Moji_Joho; MJ029313 -9C2F E0103; Hanyo-Denshi; FT1754 -9C2F E0103; Moji_Joho; MJ029312 -9C2F E0104; Hanyo-Denshi; TK01100460 -9C30 E0100; Adobe-Japan1; CID+7349 -9C30 E0101; Hanyo-Denshi; JA8264 -9C30 E0101; Moji_Joho; MJ029316 -9C30 E0102; Hanyo-Denshi; FT2732 -9C30 E0102; Moji_Joho; MJ029315 -9C31 E0100; Adobe-Japan1; CID+19047 -9C31 E0101; Hanyo-Denshi; JB7523 -9C31 E0101; Moji_Joho; MJ029318 -9C31 E0102; Hanyo-Denshi; IB1169 -9C31 E0102; Moji_Joho; MJ029317 -9C32 E0100; Adobe-Japan1; CID+7351 -9C35 E0100; Adobe-Japan1; CID+20024 -9C36 E0100; Adobe-Japan1; CID+15342 -9C37 E0100; Adobe-Japan1; CID+19048 -9C39 E0100; Adobe-Japan1; CID+1485 -9C39 E0101; Hanyo-Denshi; JA1979 -9C39 E0101; Moji_Joho; MJ029327 -9C39 E0102; Hanyo-Denshi; JTC03C -9C39 E0102; Moji_Joho; MJ029326 -9C3A E0100; Adobe-Japan1; CID+7330 -9C3A E0101; Hanyo-Denshi; JA8245 -9C3A E0101; Moji_Joho; MJ029329 -9C3A E0102; Hanyo-Denshi; JTC039 -9C3A E0102; Moji_Joho; MJ029328 -9C3B E0100; Adobe-Japan1; CID+1241 -9C3B E0101; Adobe-Japan1; CID+20255 -9C3B E0102; Hanyo-Denshi; JA1723 -9C3B E0102; Moji_Joho; MJ029331 -9C3B E0103; Hanyo-Denshi; JTC03B -9C3B E0103; Moji_Joho; MJ029330 -9C3B E0104; Hanyo-Denshi; TK01100510 -9C3D E0100; Adobe-Japan1; CID+22979 -9C3E E0100; Adobe-Japan1; CID+7353 -9C41 E0100; Adobe-Japan1; CID+15343 -9C41 E0101; Hanyo-Denshi; JB7528 -9C41 E0101; Moji_Joho; MJ029339 -9C41 E0102; Hanyo-Denshi; JC9449S -9C41 E0102; Moji_Joho; MJ029340 -9C41 E0103; Hanyo-Denshi; IB1170 -9C41 E0103; Moji_Joho; MJ029338 -9C43 E0100; Adobe-Japan1; CID+22980 -9C44 E0100; Adobe-Japan1; CID+20025 -9C45 E0100; Adobe-Japan1; CID+19049 -9C46 E0100; Adobe-Japan1; CID+7352 -9C47 E0100; Adobe-Japan1; CID+7350 -9C48 E0100; Adobe-Japan1; CID+2923 -9C48 E0101; Adobe-Japan1; CID+7737 -9C48 E0102; Hanyo-Denshi; JA3513 -9C48 E0102; Moji_Joho; MJ029348 -9C48 E0103; Hanyo-Denshi; FT1857 -9C48 E0103; Moji_Joho; MJ029347 -9C49 E0100; Adobe-Japan1; CID+19052 -9C4A E0100; Adobe-Japan1; CID+19053 -9C4E E0100; Adobe-Japan1; CID+22981 -9C4F E0100; Adobe-Japan1; CID+17215 -9C4F E0101; Hanyo-Denshi; JB7535 -9C4F E0101; Moji_Joho; MJ029355 -9C4F E0102; Hanyo-Denshi; JTC03F -9C4F E0102; Moji_Joho; MJ029356 -9C50 E0100; Adobe-Japan1; CID+17216 -9C52 E0100; Adobe-Japan1; CID+3742 -9C52 E0101; Adobe-Japan1; CID+7796 -9C52 E0102; Hanyo-Denshi; JA4380 -9C52 E0102; Moji_Joho; MJ029361 -9C52 E0103; Hanyo-Denshi; HG1648 -9C52 E0103; Moji_Joho; MJ029360 -9C52 E0104; Hanyo-Denshi; JTC03D -9C52 E0104; Moji_Joho; MJ029359 -9C53 E0100; Adobe-Japan1; CID+15344 -9C54 E0100; Adobe-Japan1; CID+19055 -9C56 E0100; Adobe-Japan1; CID+20026 -9C57 E0100; Adobe-Japan1; CID+4002 -9C57 E0101; Adobe-Japan1; CID+14092 -9C57 E0102; Hanyo-Denshi; JA4658 -9C57 E0102; Moji_Joho; MJ029367 -9C57 E0103; Hanyo-Denshi; KS526410 -9C57 E0103; Moji_Joho; MJ029366 -9C57 E0104; Hanyo-Denshi; TK01100560 -9C57 E0105; Moji_Joho; MJ029368 -9C58 E0100; Adobe-Japan1; CID+19056 -9C5A E0100; Adobe-Japan1; CID+7354 -9C5B E0100; Adobe-Japan1; CID+19057 -9C5C E0100; Adobe-Japan1; CID+19050 -9C5D E0100; Adobe-Japan1; CID+19058 -9C5D E0101; Hanyo-Denshi; JB7542 -9C5D E0101; Moji_Joho; MJ029375 -9C5D E0102; Hanyo-Denshi; KS526740 -9C5D E0102; Moji_Joho; MJ029376 -9C5E E0100; Adobe-Japan1; CID+22982 -9C5F E0100; Adobe-Japan1; CID+19059 -9C60 E0100; Adobe-Japan1; CID+7355 -9C60 E0101; Hanyo-Denshi; JA8270 -9C60 E0102; Hanyo-Denshi; TK01100550 -9C61 E0100; Adobe-Japan1; CID+20027 -9C63 E0100; Adobe-Japan1; CID+15345 -9C65 E0100; Adobe-Japan1; CID+17217 -9C67 E0100; Adobe-Japan1; CID+7356 -9C68 E0100; Adobe-Japan1; CID+20028 -9C69 E0100; Adobe-Japan1; CID+19060 -9C6A E0100; Adobe-Japan1; CID+19061 -9C6B E0100; Adobe-Japan1; CID+19062 -9C6D E0100; Adobe-Japan1; CID+19063 -9C6E E0100; Adobe-Japan1; CID+19064 -9C70 E0100; Adobe-Japan1; CID+15346 -9C72 E0100; Adobe-Japan1; CID+19065 -9C74 E0100; Hanyo-Denshi; KS527590 -9C74 E0100; Moji_Joho; MJ029400 -9C74 E0101; Hanyo-Denshi; KS527670 -9C74 E0101; Moji_Joho; MJ029401 -9C75 E0100; Adobe-Japan1; CID+19066 -9C76 E0100; Adobe-Japan1; CID+7357 -9C76 E0101; Hanyo-Denshi; JA8272 -9C76 E0101; Moji_Joho; MJ029403 -9C76 E0102; Hanyo-Denshi; FT2733 -9C76 E0102; Moji_Joho; MJ029404 -9C76 E0103; Moji_Joho; MJ029405 -9C77 E0100; Adobe-Japan1; CID+15347 -9C78 E0100; Adobe-Japan1; CID+7358 -9C7A E0100; Adobe-Japan1; CID+19067 -9C7B E0100; Adobe-Japan1; CID+22983 -9CE5 E0100; Adobe-Japan1; CID+3031 -9CE5 E0101; Hanyo-Denshi; JA3627 -9CE5 E0102; Hanyo-Denshi; TK01100660 -9CE6 E0100; Adobe-Japan1; CID+19068 -9CE6 E0101; Adobe-Japan1; CID+20257 -9CE6 E0102; Hanyo-Denshi; JB7557 -9CE6 E0102; Moji_Joho; MJ029412 -9CE6 E0103; Hanyo-Denshi; JD9401 -9CE6 E0103; Moji_Joho; MJ029413 -9CE7 E0100; Adobe-Japan1; CID+7359 -9CE9 E0100; Adobe-Japan1; CID+3403 -9CEB E0100; Adobe-Japan1; CID+7364 -9CEC E0100; Adobe-Japan1; CID+7360 -9CF0 E0100; Adobe-Japan1; CID+7361 -9CF2 E0100; Adobe-Japan1; CID+19069 -9CF3 E0100; Adobe-Japan1; CID+3679 -9CF4 E0100; Adobe-Japan1; CID+3792 -9CF6 E0100; Adobe-Japan1; CID+3240 -9CF7 E0100; Adobe-Japan1; CID+22984 -9CF9 E0100; Adobe-Japan1; CID+22985 -9CFD E0100; Hanyo-Denshi; IP9CFD -9CFD E0100; Moji_Joho; MJ029436 -9CFD E0101; Hanyo-Denshi; KS530570 -9CFD E0101; Moji_Joho; MJ029437 -9D02 E0100; Adobe-Japan1; CID+15348 -9D03 E0100; Adobe-Japan1; CID+7365 -9D06 E0100; Adobe-Japan1; CID+7366 -9D07 E0100; Adobe-Japan1; CID+3222 -9D07 E0101; Adobe-Japan1; CID+7759 -9D07 E0102; Hanyo-Denshi; JA3830 -9D07 E0102; Moji_Joho; MJ029447 -9D07 E0103; Hanyo-Denshi; FT1879 -9D07 E0103; Moji_Joho; MJ029448 -9D08 E0100; Adobe-Japan1; CID+7363 -9D08 E0101; Adobe-Japan1; CID+14273 -9D08 E0102; Moji_Joho; MJ029449 -9D08 E0103; Moji_Joho; MJ029450 -9D09 E0100; Adobe-Japan1; CID+7362 -9D09 E0101; Adobe-Japan1; CID+14272 -9D09 E0102; Hanyo-Denshi; JA8277 -9D09 E0102; Moji_Joho; MJ029452 -9D09 E0103; Hanyo-Denshi; HG1601 -9D09 E0103; Moji_Joho; MJ029451 -9D09 E0104; Moji_Joho; MJ029453 -9D0B E0100; Adobe-Japan1; CID+19070 -9D0E E0100; Adobe-Japan1; CID+1322 -9D11 E0100; Adobe-Japan1; CID+19072 -9D11 E0101; Hanyo-Denshi; JB7563 -9D11 E0102; Hanyo-Denshi; TK01100770 -9D12 E0100; Adobe-Japan1; CID+7374 -9D15 E0100; Adobe-Japan1; CID+7373 -9D17 E0100; Adobe-Japan1; CID+19073 -9D18 E0100; Adobe-Japan1; CID+19074 -9D1B E0100; Adobe-Japan1; CID+1303 -9D1C E0100; Adobe-Japan1; CID+22986 -9D1D E0100; Adobe-Japan1; CID+17218 -9D1E E0100; Adobe-Japan1; CID+17219 -9D1F E0100; Adobe-Japan1; CID+7371 -9D23 E0100; Adobe-Japan1; CID+7370 -9D26 E0100; Adobe-Japan1; CID+7368 -9D28 E0100; Adobe-Japan1; CID+1497 -9D2A E0100; Adobe-Japan1; CID+7367 -9D2A E0101; Hanyo-Denshi; JA8282 -9D2A E0101; Moji_Joho; MJ029486 -9D2A E0102; Hanyo-Denshi; FT2735 -9D2A E0102; Moji_Joho; MJ029487 -9D2B E0100; Adobe-Japan1; CID+2270 -9D2C E0100; Adobe-Japan1; CID+1321 -9D2E E0100; Hanyo-Denshi; IP9D2E -9D2E E0100; Moji_Joho; MJ029491 -9D2E E0101; Hanyo-Denshi; KS531020 -9D2E E0101; Moji_Joho; MJ029492 -9D2F E0100; Adobe-Japan1; CID+22987 -9D30 E0100; Adobe-Japan1; CID+20029 -9D32 E0100; Adobe-Japan1; CID+19078 -9D33 E0100; Adobe-Japan1; CID+22988 -9D34 E0100; Adobe-Japan1; CID+22989 -9D3A E0100; Adobe-Japan1; CID+22990 -9D3B E0100; Adobe-Japan1; CID+2037 -9D3C E0100; Adobe-Japan1; CID+22991 -9D3D E0100; Adobe-Japan1; CID+20030 -9D3E E0100; Adobe-Japan1; CID+7377 -9D3F E0100; Adobe-Japan1; CID+7376 -9D41 E0100; Adobe-Japan1; CID+7375 -9D42 E0100; Adobe-Japan1; CID+15349 -9D43 E0100; Adobe-Japan1; CID+17220 -9D43 E0101; Moji_Joho; MJ029513 -9D43 E0102; Moji_Joho; MJ029514 -9D44 E0100; Adobe-Japan1; CID+7372 -9D45 E0100; Adobe-Japan1; CID+22992 -9D46 E0100; Adobe-Japan1; CID+7378 -9D47 E0100; Adobe-Japan1; CID+15350 -9D47 E0101; Hanyo-Denshi; JB7580 -9D47 E0101; Moji_Joho; MJ029518 -9D47 E0102; Hanyo-Denshi; JTC04E -9D47 E0102; Moji_Joho; MJ029519 -9D48 E0100; Adobe-Japan1; CID+7379 -9D48 E0101; Adobe-Japan1; CID+13634 -9D48 E0102; Moji_Joho; MJ029520 -9D48 E0103; Moji_Joho; MJ029521 -9D4A E0100; Adobe-Japan1; CID+19080 -9D50 E0100; Adobe-Japan1; CID+7384 -9D51 E0100; Adobe-Japan1; CID+7383 -9D52 E0100; Adobe-Japan1; CID+17221 -9D53 E0100; Adobe-Japan1; CID+22993 -9D54 E0100; Adobe-Japan1; CID+22994 -9D55 E0100; Hanyo-Denshi; IP9D55 -9D55 E0100; Moji_Joho; MJ029534 -9D55 E0101; Hanyo-Denshi; KS531900 -9D55 E0101; Moji_Joho; MJ029535 -9D59 E0100; Adobe-Japan1; CID+7385 -9D5C E0100; Adobe-Japan1; CID+1231 -9D5C E0101; Hanyo-Denshi; JA1713 -9D5C E0102; Hanyo-Denshi; TK01100880 -9D5D E0100; Adobe-Japan1; CID+7380 -9D5E E0100; Adobe-Japan1; CID+7381 -9D5F E0100; Adobe-Japan1; CID+19081 -9D60 E0100; Adobe-Japan1; CID+2054 -9D60 E0101; Adobe-Japan1; CID+7683 -9D60 E0102; Hanyo-Denshi; JA2584 -9D60 E0102; Moji_Joho; MJ029548 -9D60 E0103; Hanyo-Denshi; FT1805 -9D60 E0103; Moji_Joho; MJ029547 -9D61 E0100; Adobe-Japan1; CID+3781 -9D62 E0100; Adobe-Japan1; CID+19082 -9D63 E0100; Adobe-Japan1; CID+15351 -9D64 E0100; Adobe-Japan1; CID+7382 -9D65 E0100; Adobe-Japan1; CID+22995 -9D65 E0101; Hanyo-Denshi; JB7587 -9D65 E0101; Moji_Joho; MJ029553 -9D65 E0102; Hanyo-Denshi; KS531830 -9D65 E0102; Moji_Joho; MJ029554 -9D69 E0100; Adobe-Japan1; CID+15352 -9D69 E0101; Hanyo-Denshi; JB7588 -9D69 E0102; Hanyo-Denshi; TK01100920 -9D6A E0100; Adobe-Japan1; CID+20031 -9D6B E0100; Adobe-Japan1; CID+8714 -9D6C E0100; Adobe-Japan1; CID+3680 -9D6C E0101; Adobe-Japan1; CID+14030 -9D6C E0102; Hanyo-Denshi; JA4318 -9D6C E0102; Moji_Joho; MJ029563 -9D6C E0103; Hanyo-Denshi; JTC054 -9D6C E0103; Moji_Joho; MJ029562 -9D6F E0100; Adobe-Japan1; CID+7390 -9D70 E0100; Adobe-Japan1; CID+8713 -9D70 E0101; Hanyo-Denshi; JB7591 -9D70 E0101; Moji_Joho; MJ029567 -9D70 E0102; Hanyo-Denshi; JTC053 -9D70 E0102; Moji_Joho; MJ029568 -9D72 E0100; Adobe-Japan1; CID+7386 -9D73 E0100; Adobe-Japan1; CID+19085 -9D76 E0100; Adobe-Japan1; CID+19086 -9D77 E0100; Adobe-Japan1; CID+19087 -9D7A E0100; Adobe-Japan1; CID+7391 -9D7B E0100; Adobe-Japan1; CID+20032 -9D7C E0100; Adobe-Japan1; CID+15353 -9D7C E0101; Hanyo-Denshi; JB7601 -9D7C E0101; Moji_Joho; MJ029580 -9D7C E0102; Hanyo-Denshi; KS532950 -9D7C E0102; Moji_Joho; MJ029581 -9D7E E0100; Adobe-Japan1; CID+15354 -9D83 E0100; Adobe-Japan1; CID+22996 -9D84 E0100; Adobe-Japan1; CID+19088 -9D84 E0101; Hanyo-Denshi; JB7604 -9D84 E0101; Moji_Joho; MJ029589 -9D84 E0102; Hanyo-Denshi; IB1172 -9D84 E0102; Moji_Joho; MJ029590 -9D86 E0100; Adobe-Japan1; CID+22997 -9D87 E0100; Adobe-Japan1; CID+7388 -9D89 E0100; Adobe-Japan1; CID+7387 -9D8A E0100; Adobe-Japan1; CID+17222 -9D8D E0100; Adobe-Japan1; CID+15355 -9D8E E0100; Adobe-Japan1; CID+22998 -9D8F E0100; Adobe-Japan1; CID+1842 -9D92 E0100; Adobe-Japan1; CID+22999 -9D93 E0100; Adobe-Japan1; CID+23000 -9D93 E0101; Hanyo-Denshi; JB7610 -9D93 E0101; Moji_Joho; MJ029604 -9D93 E0102; Hanyo-Denshi; KS533060 -9D93 E0102; Moji_Joho; MJ029605 -9D95 E0100; Adobe-Japan1; CID+23001 -9D96 E0100; Adobe-Japan1; CID+17223 -9D97 E0100; Adobe-Japan1; CID+23002 -9D98 E0100; Adobe-Japan1; CID+23003 -9D99 E0100; Adobe-Japan1; CID+19089 -9D9A E0100; Adobe-Japan1; CID+7392 -9DA1 E0100; Adobe-Japan1; CID+19090 -9DA1 E0101; Hanyo-Denshi; JB7615 -9DA1 E0102; Hanyo-Denshi; JTC057 -9DA4 E0100; Adobe-Japan1; CID+7393 -9DA9 E0100; Adobe-Japan1; CID+7394 -9DAA E0100; Adobe-Japan1; CID+23004 -9DAB E0100; Adobe-Japan1; CID+7389 -9DAC E0100; Adobe-Japan1; CID+17225 -9DAE E0100; Adobe-Japan1; CID+23005 -9DAF E0100; Adobe-Japan1; CID+7369 -9DB1 E0100; Adobe-Japan1; CID+15356 -9DB2 E0100; Adobe-Japan1; CID+7395 -9DB2 E0101; Hanyo-Denshi; JA8316 -9DB2 E0101; Moji_Joho; MJ029636 -9DB2 E0102; Hanyo-Denshi; FT2736 -9DB2 E0102; Moji_Joho; MJ029637 -9DB2 E0103; Hanyo-Denshi; JTC05B -9DB2 E0103; Moji_Joho; MJ029638 -9DB4 E0100; Adobe-Japan1; CID+8715 -9DB4 E0101; Adobe-Japan1; CID+3069 -9DB4 E0102; Hanyo-Denshi; JA3665 -9DB4 E0103; Hanyo-Denshi; IB1173 -9DB5 E0100; Adobe-Japan1; CID+19092 -9DB7 E0100; Hanyo-Denshi; IP9DB7 -9DB7 E0100; Moji_Joho; MJ029643 -9DB7 E0101; Hanyo-Denshi; KS534750 -9DB7 E0101; Moji_Joho; MJ029644 -9DB8 E0100; Adobe-Japan1; CID+7399 -9DB8 E0101; Hanyo-Denshi; JA8320 -9DB8 E0101; Moji_Joho; MJ029645 -9DB8 E0102; Hanyo-Denshi; FT2739 -9DB8 E0102; Moji_Joho; MJ029646 -9DB9 E0100; Adobe-Japan1; CID+19093 -9DB9 E0101; Hanyo-Denshi; JB7621 -9DB9 E0101; Moji_Joho; MJ029647 -9DB9 E0102; Hanyo-Denshi; KS534730 -9DB9 E0102; Moji_Joho; MJ029648 -9DBA E0100; Adobe-Japan1; CID+7400 -9DBB E0100; Adobe-Japan1; CID+7398 -9DBC E0100; Adobe-Japan1; CID+17226 -9DBD E0100; Adobe-Japan1; CID+19094 -9DBF E0100; Adobe-Japan1; CID+19091 -9DBF E0101; Adobe-Japan1; CID+23006 -9DBF E0102; Hanyo-Denshi; JB7623 -9DBF E0102; Moji_Joho; MJ029654 -9DBF E0103; Hanyo-Denshi; KS534330 -9DBF E0103; Moji_Joho; MJ029656 -9DBF E0104; Hanyo-Denshi; JD9430 -9DBF E0104; Moji_Joho; MJ029655 -9DBF E0105; Hanyo-Denshi; KS534720 -9DBF E0105; Moji_Joho; MJ029657 -9DC0 E0100; Adobe-Japan1; CID+17224 -9DC0 E0101; Adobe-Japan1; CID+20258 -9DC0 E0102; Hanyo-Denshi; JC9466 -9DC0 E0102; Moji_Joho; MJ029661 -9DC0 E0103; Hanyo-Denshi; KS534710 -9DC0 E0103; Moji_Joho; MJ029660 -9DC0 E0104; Hanyo-Denshi; KS534340 -9DC0 E0104; Moji_Joho; MJ029659 -9DC0 E0105; Hanyo-Denshi; IP9DC0 -9DC0 E0105; Moji_Joho; MJ029658 -9DC0 E0106; Hanyo-Denshi; TK01100940 -9DC1 E0100; Adobe-Japan1; CID+7397 -9DC1 E0101; Hanyo-Denshi; JA8318 -9DC1 E0101; Moji_Joho; MJ029663 -9DC1 E0102; Hanyo-Denshi; JTC05C -9DC1 E0102; Moji_Joho; MJ029664 -9DC1 E0103; Hanyo-Denshi; JTC05D -9DC1 E0103; Moji_Joho; MJ029665 -9DC2 E0100; Adobe-Japan1; CID+7403 -9DC2 E0101; Adobe-Japan1; CID+20259 -9DC3 E0100; Adobe-Japan1; CID+15357 -9DC4 E0100; Adobe-Japan1; CID+7396 -9DC4 E0101; Hanyo-Denshi; JA8317 -9DC4 E0101; Moji_Joho; MJ029668 -9DC4 E0102; Hanyo-Denshi; JTC058 -9DC4 E0102; Moji_Joho; MJ029669 -9DC6 E0100; Adobe-Japan1; CID+7401 -9DC7 E0100; Adobe-Japan1; CID+15358 -9DC9 E0100; Adobe-Japan1; CID+19095 -9DCA E0100; Adobe-Japan1; CID+23007 -9DCA E0101; Hanyo-Denshi; JB7627 -9DCA E0101; Moji_Joho; MJ029675 -9DCA E0102; Hanyo-Denshi; KS534740 -9DCA E0102; Moji_Joho; MJ029676 -9DCF E0100; Adobe-Japan1; CID+7402 -9DCF E0101; Adobe-Japan1; CID+13635 -9DD3 E0100; Adobe-Japan1; CID+7405 -9DD4 E0100; Adobe-Japan1; CID+23008 -9DD5 E0100; Adobe-Japan1; CID+23009 -9DD6 E0100; Adobe-Japan1; CID+15359 -9DD6 E0101; Hanyo-Denshi; JB7630 -9DD6 E0101; Moji_Joho; MJ029688 -9DD6 E0102; Hanyo-Denshi; KS535430 -9DD6 E0102; Moji_Joho; MJ029689 -9DD7 E0100; Adobe-Japan1; CID+7646 -9DD7 E0101; Hanyo-Denshi; JB7631 -9DD7 E0101; Moji_Joho; MJ029690 -9DD7 E0102; Hanyo-Denshi; KS535440 -9DD7 E0102; Moji_Joho; MJ029691 -9DD9 E0100; Adobe-Japan1; CID+7404 -9DDA E0100; Adobe-Japan1; CID+19096 -9DDE E0100; Adobe-Japan1; CID+23010 -9DDF E0100; Adobe-Japan1; CID+15360 -9DE0 E0100; Adobe-Japan1; CID+19097 -9DE0 E0101; Hanyo-Denshi; JB7635 -9DE0 E0102; Hanyo-Denshi; TK01100970 -9DE3 E0100; Adobe-Japan1; CID+19098 -9DE3 E0101; Hanyo-Denshi; JD9441 -9DE3 E0101; Moji_Joho; MJ029705 -9DE3 E0102; Hanyo-Denshi; IP9DE3 -9DE3 E0102; Moji_Joho; MJ029704 -9DE5 E0100; Adobe-Japan1; CID+20033 -9DE6 E0100; Adobe-Japan1; CID+7407 -9DE7 E0100; Adobe-Japan1; CID+17228 -9DE9 E0100; Adobe-Japan1; CID+20034 -9DEB E0100; Adobe-Japan1; CID+15361 -9DED E0100; Adobe-Japan1; CID+7408 -9DEE E0100; Adobe-Japan1; CID+23011 -9DEF E0100; Adobe-Japan1; CID+7409 -9DF0 E0100; Adobe-Japan1; CID+23012 -9DF0 E0101; Hanyo-Denshi; JB7641 -9DF0 E0102; Hanyo-Denshi; TK01082470 -9DF2 E0100; Adobe-Japan1; CID+4079 -9DF3 E0100; Adobe-Japan1; CID+20035 -9DF4 E0100; Adobe-Japan1; CID+15362 -9DF8 E0100; Adobe-Japan1; CID+7406 -9DF9 E0100; Adobe-Japan1; CID+2891 -9DFA E0100; Adobe-Japan1; CID+2141 -9DFD E0100; Adobe-Japan1; CID+7410 -9DFE E0100; Adobe-Japan1; CID+23013 -9DFE E0101; Hanyo-Denshi; JB7644 -9DFE E0101; Moji_Joho; MJ029732 -9DFE E0102; Hanyo-Denshi; KS536770 -9DFE E0102; Moji_Joho; MJ029733 -9E02 E0100; Adobe-Japan1; CID+19101 -9E07 E0100; Adobe-Japan1; CID+17229 -9E0A E0100; Adobe-Japan1; CID+19100 -9E0D E0100; Adobe-Japan1; CID+19102 -9E0E E0100; Adobe-Japan1; CID+23014 -9E10 E0100; Adobe-Japan1; CID+23015 -9E11 E0100; Adobe-Japan1; CID+23016 -9E12 E0100; Adobe-Japan1; CID+23017 -9E15 E0100; Adobe-Japan1; CID+15363 -9E16 E0100; Adobe-Japan1; CID+23018 -9E16 E0101; Hanyo-Denshi; JB7653 -9E16 E0102; Hanyo-Denshi; TK01101130 -9E17 E0100; Hanyo-Denshi; IP9E17 -9E17 E0100; Moji_Joho; MJ029759 -9E17 E0101; Hanyo-Denshi; KS537510 -9E17 E0101; Moji_Joho; MJ029760 -9E19 E0100; Adobe-Japan1; CID+8716 -9E1A E0100; Adobe-Japan1; CID+7411 -9E1B E0100; Adobe-Japan1; CID+7412 -9E1B E0101; Hanyo-Denshi; JA8333 -9E1B E0101; Moji_Joho; MJ029764 -9E1B E0102; Hanyo-Denshi; JTC062 -9E1B E0102; Moji_Joho; MJ029765 -9E1C E0100; Adobe-Japan1; CID+19103 -9E1D E0100; Adobe-Japan1; CID+15364 -9E1E E0100; Adobe-Japan1; CID+7413 -9E75 E0100; Adobe-Japan1; CID+7414 -9E78 E0100; Adobe-Japan1; CID+1896 -9E79 E0100; Adobe-Japan1; CID+7415 -9E7A E0100; Adobe-Japan1; CID+20036 -9E7B E0100; Adobe-Japan1; CID+19104 -9E7C E0100; Adobe-Japan1; CID+7677 -9E7D E0100; Adobe-Japan1; CID+7416 -9E7F E0100; Adobe-Japan1; CID+2267 -9E80 E0100; Adobe-Japan1; CID+19106 -9E80 E0101; Hanyo-Denshi; JB7660 -9E80 E0101; Moji_Joho; MJ029779 -9E80 E0102; Hanyo-Denshi; KS538670 -9E80 E0102; Moji_Joho; MJ029780 -9E81 E0100; Adobe-Japan1; CID+7417 -9E81 E0101; Hanyo-Denshi; JA8338 -9E81 E0101; Moji_Joho; MJ029781 -9E81 E0102; Hanyo-Denshi; JTC065 -9E81 E0102; Moji_Joho; MJ029782 -9E81 E0103; Moji_Joho; MJ060364 -9E82 E0100; Adobe-Japan1; CID+20037 -9E83 E0100; Adobe-Japan1; CID+20038 -9E84 E0100; Adobe-Japan1; CID+20039 -9E85 E0100; Adobe-Japan1; CID+19107 -9E87 E0100; Adobe-Japan1; CID+23019 -9E88 E0100; Adobe-Japan1; CID+7418 -9E8B E0100; Adobe-Japan1; CID+7419 -9E8C E0100; Adobe-Japan1; CID+7420 -9E8E E0100; Adobe-Japan1; CID+23020 -9E8E E0101; Hanyo-Denshi; JB7666 -9E8E E0102; Hanyo-Denshi; JTC067S -9E8E E0102; Moji_Joho; MJ029796 -9E8E E0103; Moji_Joho; MJ029797 -9E8F E0100; Adobe-Japan1; CID+23021 -9E91 E0100; Adobe-Japan1; CID+7423 -9E92 E0100; Adobe-Japan1; CID+7421 -9E93 E0100; Adobe-Japan1; CID+4066 -9E95 E0100; Adobe-Japan1; CID+7422 -9E96 E0100; Adobe-Japan1; CID+23022 -9E97 E0100; Adobe-Japan1; CID+4023 -9E97 E0101; Adobe-Japan1; CID+13516 -9E97 E0102; Hanyo-Denshi; JA4679 -9E97 E0102; Moji_Joho; MJ029806 -9E97 E0103; Hanyo-Denshi; JTC068 -9E97 E0103; Moji_Joho; MJ029807 -9E98 E0100; Adobe-Japan1; CID+23023 -9E9B E0100; Adobe-Japan1; CID+19108 -9E9D E0100; Adobe-Japan1; CID+7424 -9E9E E0100; Adobe-Japan1; CID+17230 -9E9E E0101; Hanyo-Denshi; JB7671 -9E9E E0101; Moji_Joho; MJ029814 -9E9E E0102; Hanyo-Denshi; KS539740 -9E9E E0102; Moji_Joho; MJ029815 -9E9F E0100; Adobe-Japan1; CID+4003 -9E9F E0101; Adobe-Japan1; CID+13515 -9E9F E0102; Adobe-Japan1; CID+14093 -9E9F E0103; Hanyo-Denshi; JA4659 -9E9F E0103; Moji_Joho; MJ029817 -9E9F E0104; Hanyo-Denshi; KS539750S -9E9F E0104; Moji_Joho; MJ029816 -9E9F E0105; Moji_Joho; MJ029818 -9EA4 E0100; Adobe-Japan1; CID+15365 -9EA5 E0100; Adobe-Japan1; CID+7425 -9EA5 E0101; Adobe-Japan1; CID+14274 -9EA6 E0100; Adobe-Japan1; CID+3380 -9EA8 E0100; Adobe-Japan1; CID+15366 -9EA8 E0101; Hanyo-Denshi; JB7673 -9EA8 E0101; Moji_Joho; MJ029828 -9EA8 E0102; Hanyo-Denshi; KS540410 -9EA8 E0102; Moji_Joho; MJ029829 -9EA9 E0100; Adobe-Japan1; CID+7426 -9EA9 E0101; Hanyo-Denshi; JA8347 -9EA9 E0101; Moji_Joho; MJ029830 -9EA9 E0102; Hanyo-Denshi; JTC06D -9EA9 E0102; Moji_Joho; MJ029831 -9EAA E0100; Adobe-Japan1; CID+7428 -9EAA E0101; Adobe-Japan1; CID+7885 -9EAA E0102; Hanyo-Denshi; JA8349 -9EAA E0102; Moji_Joho; MJ029833 -9EAA E0103; Hanyo-Denshi; FT2012 -9EAA E0103; Moji_Joho; MJ029832 -9EAC E0100; Adobe-Japan1; CID+15367 -9EAC E0101; Hanyo-Denshi; JB7674 -9EAC E0101; Moji_Joho; MJ029835 -9EAC E0102; Hanyo-Denshi; JTC071 -9EAC E0102; Moji_Joho; MJ029836 -9EAD E0100; Adobe-Japan1; CID+7429 -9EAD E0101; Adobe-Japan1; CID+8004 -9EAD E0102; Hanyo-Denshi; JA8350 -9EAD E0102; Moji_Joho; MJ029837 -9EAD E0103; Hanyo-Denshi; JTC06F -9EAD E0103; Moji_Joho; MJ029838 -9EAD E0104; Moji_Joho; MJ029839 -9EAE E0100; Adobe-Japan1; CID+23024 -9EAE E0101; Hanyo-Denshi; JB7675 -9EAE E0101; Moji_Joho; MJ029840 -9EAE E0102; Hanyo-Denshi; KS540600 -9EAE E0102; Moji_Joho; MJ059258 -9EAF E0100; Adobe-Japan1; CID+17231 -9EAF E0101; Hanyo-Denshi; JB7676 -9EAF E0102; Hanyo-Denshi; TK01101290 -9EB0 E0100; Adobe-Japan1; CID+20040 -9EB0 E0101; Hanyo-Denshi; JB7677 -9EB0 E0101; Moji_Joho; MJ029843 -9EB0 E0102; Hanyo-Denshi; IB3293 -9EB0 E0102; Moji_Joho; MJ029844 -9EB3 E0100; Adobe-Japan1; CID+23025 -9EB4 E0100; Adobe-Japan1; CID+7682 -9EB5 E0100; Adobe-Japan1; CID+7797 -9EB8 E0100; Adobe-Japan1; CID+7427 -9EB9 E0100; Adobe-Japan1; CID+2047 -9EBA E0100; Adobe-Japan1; CID+3801 -9EBA E0101; Hanyo-Denshi; JA4445 -9EBA E0102; Hanyo-Denshi; TK01101280 -9EBB E0100; Adobe-Japan1; CID+3729 -9EBB E0101; Adobe-Japan1; CID+14044 -9EBB E0102; Hanyo-Denshi; JA4367 -9EBB E0102; Moji_Joho; MJ029855 -9EBB E0103; Hanyo-Denshi; JTC074 -9EBB E0103; Moji_Joho; MJ029854 -9EBC E0100; Adobe-Japan1; CID+4740 -9EBC E0101; Hanyo-Denshi; JA5487 -9EBC E0101; Moji_Joho; MJ029856 -9EBC E0102; Hanyo-Denshi; FT2168 -9EBC E0102; Moji_Joho; MJ029857 -9EBD E0100; Adobe-Japan1; CID+19110 -9EBD E0101; Hanyo-Denshi; JD9457 -9EBD E0101; Moji_Joho; MJ029858 -9EBD E0102; Hanyo-Denshi; JTB0E5 -9EBD E0102; Moji_Joho; MJ029859 -9EBE E0100; Adobe-Japan1; CID+5375 -9EBE E0101; Hanyo-Denshi; JA6164 -9EBE E0101; Moji_Joho; MJ029860 -9EBE E0102; Hanyo-Denshi; FT2274S -9EBE E0102; Moji_Joho; MJ029861 -9EBF E0100; Adobe-Japan1; CID+3753 -9EBF E0101; Adobe-Japan1; CID+14050 -9EBF E0102; Hanyo-Denshi; JA4391 -9EBF E0102; Moji_Joho; MJ029863 -9EBF E0103; Hanyo-Denshi; JTC075 -9EBF E0103; Moji_Joho; MJ029862 -9EC2 E0100; Hanyo-Denshi; IP9EC2 -9EC2 E0100; Moji_Joho; MJ029866 -9EC2 E0101; Hanyo-Denshi; KS542210 -9EC2 E0101; Moji_Joho; MJ029867 -9EC3 E0100; Adobe-Japan1; CID+13323 -9EC3 E0101; Hanyo-Denshi; JC9481 -9EC3 E0102; Hanyo-Denshi; TK01101320 -9EC4 E0100; Adobe-Japan1; CID+1323 -9EC4 E0101; Hanyo-Denshi; JA1811 -9EC4 E0101; Moji_Joho; MJ029870 -9EC4 E0102; Hanyo-Denshi; KS542250 -9EC4 E0102; Moji_Joho; MJ059263 -9EC4 E0103; Hanyo-Denshi; TK01078270 -9EC6 E0100; Adobe-Japan1; CID+23026 -9EC6 E0101; Hanyo-Denshi; JB7681 -9EC6 E0102; Hanyo-Denshi; TK01101330 -9EC6 E0103; Hanyo-Denshi; TK01101340 -9EC6 E0104; Hanyo-Denshi; TK01101350 -9EC8 E0100; Adobe-Japan1; CID+23027 -9EC8 E0101; Hanyo-Denshi; JB7682 -9EC8 E0101; Moji_Joho; MJ029878 -9EC8 E0102; Hanyo-Denshi; JTC078 -9EC8 E0102; Moji_Joho; MJ029879 -9ECB E0100; Adobe-Japan1; CID+23028 -9ECB E0101; Hanyo-Denshi; JB7683 -9ECB E0101; Moji_Joho; MJ029882 -9ECB E0102; Hanyo-Denshi; JTC079 -9ECB E0102; Moji_Joho; MJ029883 -9ECB E0103; Hanyo-Denshi; TK01101380 -9ECC E0100; Adobe-Japan1; CID+7431 -9ECC E0101; Adobe-Japan1; CID+14275 -9ECC E0102; Hanyo-Denshi; JA8352 -9ECC E0102; Moji_Joho; MJ029885 -9ECC E0103; Hanyo-Denshi; FT2743 -9ECC E0103; Moji_Joho; MJ029886 -9ECD E0100; Adobe-Japan1; CID+1642 -9ECE E0100; Adobe-Japan1; CID+7432 -9ECE E0101; Hanyo-Denshi; JA8353 -9ECE E0101; Moji_Joho; MJ029888 -9ECE E0102; Hanyo-Denshi; IB2266 -9ECE E0102; Moji_Joho; MJ029889 -9ECF E0100; Adobe-Japan1; CID+7433 -9ED0 E0100; Adobe-Japan1; CID+7434 -9ED0 E0101; Hanyo-Denshi; JA8355 -9ED0 E0101; Moji_Joho; MJ029891 -9ED0 E0102; Hanyo-Denshi; KS543300 -9ED0 E0102; Moji_Joho; MJ059266 -9ED1 E0100; Adobe-Japan1; CID+8717 -9ED2 E0100; Adobe-Japan1; CID+2055 -9ED4 E0100; Adobe-Japan1; CID+7435 -9ED4 E0101; Hanyo-Denshi; JA8356 -9ED4 E0101; Moji_Joho; MJ029896 -9ED4 E0102; Hanyo-Denshi; FT2744 -9ED4 E0102; Moji_Joho; MJ029897 -9ED5 E0100; Adobe-Japan1; CID+23029 -9ED8 E0100; Adobe-Japan1; CID+5645 -9ED8 E0101; Hanyo-Denshi; JA6452 -9ED8 E0101; Moji_Joho; MJ029901 -9ED8 E0102; Hanyo-Denshi; FT2329 -9ED8 E0102; Moji_Joho; MJ029902 -9ED9 E0100; Adobe-Japan1; CID+3815 -9EDB E0100; Adobe-Japan1; CID+2883 -9EDB E0101; Adobe-Japan1; CID+7729 -9EDB E0102; Hanyo-Denshi; JA3467 -9EDB E0102; Moji_Joho; MJ029905 -9EDB E0103; Hanyo-Denshi; FT1849 -9EDB E0103; Moji_Joho; MJ029906 -9EDC E0100; Adobe-Japan1; CID+7436 -9EDC E0101; Hanyo-Denshi; JA8357 -9EDC E0101; Moji_Joho; MJ029907 -9EDC E0102; Hanyo-Denshi; FT2745 -9EDC E0102; Moji_Joho; MJ029908 -9EDD E0100; Adobe-Japan1; CID+7438 -9EDD E0101; Hanyo-Denshi; JA8359 -9EDD E0101; Moji_Joho; MJ029909 -9EDD E0102; Hanyo-Denshi; FT2747 -9EDD E0102; Moji_Joho; MJ029910 -9EDE E0100; Adobe-Japan1; CID+7437 -9EDE E0101; Hanyo-Denshi; JA8358 -9EDE E0101; Moji_Joho; MJ029911 -9EDE E0102; Hanyo-Denshi; FT2746 -9EDE E0102; Moji_Joho; MJ029912 -9EDF E0100; Adobe-Japan1; CID+19112 -9EE0 E0100; Adobe-Japan1; CID+7439 -9EE0 E0101; Hanyo-Denshi; JA8360 -9EE0 E0101; Moji_Joho; MJ029914 -9EE0 E0102; Hanyo-Denshi; FT2748 -9EE0 E0102; Moji_Joho; MJ029915 -9EE4 E0100; Adobe-Japan1; CID+20041 -9EE5 E0100; Adobe-Japan1; CID+7440 -9EE5 E0101; Hanyo-Denshi; JA8361 -9EE5 E0101; Moji_Joho; MJ029919 -9EE5 E0102; Hanyo-Denshi; FT2749 -9EE5 E0102; Moji_Joho; MJ029920 -9EE7 E0100; Adobe-Japan1; CID+15368 -9EE8 E0100; Adobe-Japan1; CID+7441 -9EE8 E0101; Hanyo-Denshi; JA8362 -9EE8 E0101; Moji_Joho; MJ029923 -9EE8 E0102; Hanyo-Denshi; FT2750 -9EE8 E0102; Moji_Joho; MJ029924 -9EEC E0100; Adobe-Japan1; CID+23030 -9EED E0100; Adobe-Japan1; CID+23031 -9EEE E0100; Adobe-Japan1; CID+15369 -9EEF E0100; Adobe-Japan1; CID+7442 -9EEF E0101; Hanyo-Denshi; JA8363 -9EEF E0101; Moji_Joho; MJ029929 -9EEF E0102; Hanyo-Denshi; KS544750 -9EEF E0102; Moji_Joho; MJ029930 -9EEF E0103; Hanyo-Denshi; FT2751 -9EEF E0103; Moji_Joho; MJ029931 -9EF0 E0100; Adobe-Japan1; CID+20042 -9EF1 E0100; Adobe-Japan1; CID+23032 -9EF2 E0100; Adobe-Japan1; CID+20043 -9EF3 E0100; Hanyo-Denshi; KS544990 -9EF3 E0100; Moji_Joho; MJ029935 -9EF3 E0101; Hanyo-Denshi; KS545080 -9EF3 E0101; Moji_Joho; MJ029936 -9EF4 E0100; Adobe-Japan1; CID+7443 -9EF4 E0101; Hanyo-Denshi; JA8364 -9EF4 E0101; Moji_Joho; MJ029937 -9EF4 E0102; Hanyo-Denshi; FT2752S -9EF4 E0102; Moji_Joho; MJ029938 -9EF5 E0100; Adobe-Japan1; CID+23033 -9EF6 E0100; Adobe-Japan1; CID+7444 -9EF7 E0100; Adobe-Japan1; CID+7445 -9EF7 E0101; Hanyo-Denshi; JA8366 -9EF7 E0101; Moji_Joho; MJ029941 -9EF7 E0102; Hanyo-Denshi; FT2753 -9EF7 E0102; Moji_Joho; MJ029942 -9EF8 E0100; Adobe-Japan1; CID+23034 -9EF9 E0100; Adobe-Japan1; CID+7446 -9EF9 E0101; Hanyo-Denshi; JA8367 -9EF9 E0101; Moji_Joho; MJ029944 -9EF9 E0102; Hanyo-Denshi; JTC089 -9EF9 E0102; Moji_Joho; MJ029945 -9EF9 E0103; Hanyo-Denshi; KS386530 -9EF9 E0103; Moji_Joho; MJ058678 -9EFB E0100; Adobe-Japan1; CID+7447 -9EFB E0101; Hanyo-Denshi; JA8368 -9EFB E0101; Moji_Joho; MJ029947 -9EFB E0102; Hanyo-Denshi; JTC08A -9EFB E0102; Moji_Joho; MJ029948 -9EFC E0100; Adobe-Japan1; CID+7448 -9EFC E0101; Hanyo-Denshi; JA8369 -9EFC E0101; Moji_Joho; MJ029949 -9EFC E0102; Hanyo-Denshi; JTC08B -9EFC E0102; Moji_Joho; MJ029950 -9EFD E0100; Adobe-Japan1; CID+7449 -9EFD E0101; Hanyo-Denshi; JA8370 -9EFD E0101; Moji_Joho; MJ029951 -9EFD E0102; Hanyo-Denshi; JTC08C -9EFD E0102; Moji_Joho; MJ029952 -9EFF E0100; Adobe-Japan1; CID+19113 -9F02 E0100; Adobe-Japan1; CID+19114 -9F02 E0101; Hanyo-Denshi; JB7703 -9F02 E0101; Moji_Joho; MJ029957 -9F02 E0102; Hanyo-Denshi; KS545760 -9F02 E0102; Moji_Joho; MJ029958 -9F03 E0100; Adobe-Japan1; CID+19116 -9F03 E0101; Hanyo-Denshi; JB7704 -9F03 E0101; Moji_Joho; MJ029959 -9F03 E0102; Hanyo-Denshi; KS545830 -9F03 E0102; Moji_Joho; MJ029960 -9F05 E0100; Moji_Joho; MJ029962 -9F05 E0101; Moji_Joho; MJ029963 -9F07 E0100; Adobe-Japan1; CID+7450 -9F07 E0101; Hanyo-Denshi; JA8371 -9F07 E0101; Moji_Joho; MJ029965 -9F07 E0102; Hanyo-Denshi; JTC08D -9F07 E0102; Moji_Joho; MJ029967 -9F07 E0103; Moji_Joho; MJ029966 -9F08 E0100; Adobe-Japan1; CID+7451 -9F08 E0101; Adobe-Japan1; CID+13636 -9F08 E0102; Adobe-Japan1; CID+14276 -9F08 E0103; Hanyo-Denshi; JA8372 -9F08 E0103; Moji_Joho; MJ029968 -9F08 E0104; Hanyo-Denshi; JTC091 -9F08 E0104; Moji_Joho; MJ029972 -9F08 E0105; Hanyo-Denshi; JTC08E -9F08 E0105; Moji_Joho; MJ029969 -9F08 E0106; Hanyo-Denshi; FT2754SS -9F08 E0106; Moji_Joho; MJ029971 -9F08 E0107; Moji_Joho; MJ029970 -9F09 E0100; Adobe-Japan1; CID+20044 -9F0E E0100; Adobe-Japan1; CID+3102 -9F0F E0100; Adobe-Japan1; CID+20045 -9F0F E0101; Hanyo-Denshi; JB7706 -9F0F E0101; Moji_Joho; MJ029976 -9F0F E0102; Hanyo-Denshi; KS546270 -9F0F E0102; Moji_Joho; MJ029978 -9F10 E0100; Adobe-Japan1; CID+15370 -9F10 E0101; Hanyo-Denshi; JB7707 -9F10 E0101; Moji_Joho; MJ029979 -9F10 E0102; Hanyo-Denshi; KS546250 -9F10 E0102; Moji_Joho; MJ029980 -9F11 E0100; Adobe-Japan1; CID+23035 -9F12 E0100; Adobe-Japan1; CID+15371 -9F12 E0101; Hanyo-Denshi; JB7709 -9F12 E0101; Moji_Joho; MJ029982 -9F12 E0102; Hanyo-Denshi; KS546310 -9F12 E0102; Moji_Joho; MJ029983 -9F13 E0100; Adobe-Japan1; CID+1937 -9F14 E0100; Adobe-Japan1; CID+20046 -9F15 E0100; Adobe-Japan1; CID+7453 -9F15 E0101; Hanyo-Denshi; JA8374 -9F15 E0101; Moji_Joho; MJ029986 -9F15 E0102; Hanyo-Denshi; FT2755 -9F15 E0102; Moji_Joho; MJ029987 -9F16 E0100; Adobe-Japan1; CID+23036 -9F16 E0101; Hanyo-Denshi; JB7711 -9F16 E0101; Moji_Joho; MJ029988 -9F16 E0102; Hanyo-Denshi; KS546570 -9F16 E0102; Moji_Joho; MJ029989 -9F17 E0100; Adobe-Japan1; CID+15372 -9F19 E0100; Adobe-Japan1; CID+15373 -9F1A E0100; Adobe-Japan1; CID+23037 -9F1B E0100; Adobe-Japan1; CID+20047 -9F1B E0101; Hanyo-Denshi; JB7715 -9F1B E0101; Moji_Joho; MJ029994 -9F1B E0102; Hanyo-Denshi; IB3308 -9F1B E0102; Moji_Joho; MJ029996 -9F1B E0103; Hanyo-Denshi; KS546730 -9F1B E0103; Moji_Joho; MJ029995 -9F1F E0100; Adobe-Japan1; CID+23038 -9F20 E0100; Adobe-Japan1; CID+2767 -9F21 E0100; Adobe-Japan1; CID+7454 -9F22 E0100; Adobe-Japan1; CID+20048 -9F22 E0101; Hanyo-Denshi; JB7717 -9F22 E0101; Moji_Joho; MJ030004 -9F22 E0102; Hanyo-Denshi; KS547220 -9F22 E0102; Moji_Joho; MJ030005 -9F25 E0100; Hanyo-Denshi; IP9F25 -9F25 E0100; Moji_Joho; MJ030008 -9F25 E0101; Hanyo-Denshi; KS547430 -9F25 E0101; Moji_Joho; MJ030009 -9F26 E0100; Adobe-Japan1; CID+20049 -9F28 E0100; Hanyo-Denshi; IP9F28 -9F28 E0100; Moji_Joho; MJ030012 -9F28 E0101; Hanyo-Denshi; KS547450 -9F28 E0101; Moji_Joho; MJ030013 -9F29 E0100; Hanyo-Denshi; IP9F29 -9F29 E0100; Moji_Joho; MJ030014 -9F29 E0101; Hanyo-Denshi; KS547420 -9F29 E0101; Moji_Joho; MJ030015 -9F2A E0100; Adobe-Japan1; CID+20050 -9F2B E0100; Adobe-Japan1; CID+20051 -9F2C E0100; Adobe-Japan1; CID+7455 -9F2C E0101; Hanyo-Denshi; JA8376 -9F2C E0101; Moji_Joho; MJ030018 -9F2C E0102; Hanyo-Denshi; JTC098 -9F2C E0102; Moji_Joho; MJ030019 -9F2E E0100; Hanyo-Denshi; IP9F2ES -9F2E E0100; Moji_Joho; MJ030021 -9F2E E0101; Hanyo-Denshi; KS547660 -9F2E E0101; Moji_Joho; MJ030022 -9F2F E0100; Adobe-Japan1; CID+15374 -9F31 E0100; Adobe-Japan1; CID+23039 -9F31 E0101; Hanyo-Denshi; JB7722 -9F31 E0101; Moji_Joho; MJ030025 -9F31 E0102; Hanyo-Denshi; IB1177 -9F31 E0102; Moji_Joho; MJ030026 -9F31 E0103; Hanyo-Denshi; IB3309 -9F31 E0103; Moji_Joho; MJ030027 -9F32 E0100; Adobe-Japan1; CID+23040 -9F32 E0101; Hanyo-Denshi; JB7723 -9F32 E0101; Moji_Joho; MJ030028 -9F32 E0102; Hanyo-Denshi; KS547870 -9F32 E0102; Moji_Joho; MJ030029 -9F34 E0100; Adobe-Japan1; CID+20052 -9F34 E0101; Moji_Joho; MJ030031 -9F34 E0102; Moji_Joho; MJ030032 -9F37 E0100; Adobe-Japan1; CID+15375 -9F39 E0100; Adobe-Japan1; CID+15376 -9F39 E0101; Hanyo-Denshi; JB7726 -9F39 E0101; Moji_Joho; MJ030037 -9F39 E0102; Hanyo-Denshi; JTC09A -9F39 E0102; Moji_Joho; MJ030038 -9F3A E0100; Adobe-Japan1; CID+19117 -9F3A E0101; Hanyo-Denshi; JB7727 -9F3A E0101; Moji_Joho; MJ030039 -9F3A E0102; Hanyo-Denshi; KS548160 -9F3A E0102; Moji_Joho; MJ030040 -9F3B E0100; Adobe-Japan1; CID+3475 -9F3B E0101; Adobe-Japan1; CID+13993 -9F3B E0102; Hanyo-Denshi; JA4101 -9F3B E0102; Moji_Joho; MJ030042 -9F3B E0103; Hanyo-Denshi; JTC09B -9F3B E0103; Moji_Joho; MJ030041 -9F3C E0100; Adobe-Japan1; CID+23041 -9F3D E0100; Adobe-Japan1; CID+19118 -9F3E E0100; Adobe-Japan1; CID+7456 -9F3E E0101; Hanyo-Denshi; JA8377 -9F3E E0101; Moji_Joho; MJ030045 -9F3E E0102; Hanyo-Denshi; FT2756 -9F3E E0102; Moji_Joho; MJ030046 -9F3F E0100; Adobe-Japan1; CID+23042 -9F41 E0100; Adobe-Japan1; CID+15377 -9F43 E0100; Adobe-Japan1; CID+23043 -9F44 E0100; Adobe-Japan1; CID+23044 -9F45 E0100; Adobe-Japan1; CID+15378 -9F46 E0100; Adobe-Japan1; CID+19119 -9F47 E0100; Adobe-Japan1; CID+23045 -9F4A E0100; Adobe-Japan1; CID+7457 -9F4A E0101; Adobe-Japan1; CID+14277 -9F4A E0102; Hanyo-Denshi; JA8378 -9F4A E0102; Moji_Joho; MJ030059 -9F4A E0103; Hanyo-Denshi; IB1323 -9F4A E0103; Moji_Joho; MJ030058 -9F4B E0100; Adobe-Japan1; CID+5898 -9F4B E0101; Adobe-Japan1; CID+14170 -9F4B E0102; Hanyo-Denshi; JA6723 -9F4B E0102; Moji_Joho; MJ030060 -9F4B E0103; Hanyo-Denshi; JTAD38 -9F4B E0103; Moji_Joho; MJ030062 -9F4B E0104; Hanyo-Denshi; JTAD37 -9F4B E0104; Moji_Joho; MJ030061 -9F4B E0105; Hanyo-Denshi; JTAD39S -9F4B E0106; Moji_Joho; MJ030063 -9F4D E0100; Hanyo-Denshi; IP9F4D -9F4D E0100; Moji_Joho; MJ030065 -9F4D E0101; Hanyo-Denshi; KS549020 -9F4D E0101; Moji_Joho; MJ030066 -9F4E E0100; Adobe-Japan1; CID+6779 -9F4E E0101; Adobe-Japan1; CID+13604 -9F4E E0102; Moji_Joho; MJ030067 -9F4E E0103; Moji_Joho; MJ030068 -9F4F E0100; Adobe-Japan1; CID+7174 -9F4F E0101; Moji_Joho; MJ030069 -9F4F E0102; Moji_Joho; MJ030070 -9F52 E0100; Adobe-Japan1; CID+7458 -9F53 E0100; Adobe-Japan1; CID+19120 -9F54 E0100; Adobe-Japan1; CID+7459 -9F55 E0100; Adobe-Japan1; CID+19121 -9F56 E0100; Adobe-Japan1; CID+23046 -9F56 E0101; Hanyo-Denshi; JB7739 -9F56 E0101; Moji_Joho; MJ030077 -9F56 E0102; Hanyo-Denshi; JB7739S -9F56 E0102; Moji_Joho; MJ030076 -9F57 E0100; Adobe-Japan1; CID+15379 -9F58 E0100; Adobe-Japan1; CID+19122 -9F5A E0100; Adobe-Japan1; CID+20053 -9F5D E0100; Adobe-Japan1; CID+19124 -9F5E E0100; Adobe-Japan1; CID+23047 -9F5F E0100; Adobe-Japan1; CID+7461 -9F60 E0100; Adobe-Japan1; CID+7462 -9F60 E0101; Hanyo-Denshi; JA8383 -9F60 E0101; Moji_Joho; MJ030088 -9F60 E0102; Hanyo-Denshi; KS549650 -9F60 E0102; Moji_Joho; MJ030087 -9F61 E0100; Adobe-Japan1; CID+7463 -9F61 E0101; Hanyo-Denshi; JA8384 -9F61 E0102; Hanyo-Denshi; TK01101690 -9F62 E0100; Adobe-Japan1; CID+4024 -9F63 E0100; Adobe-Japan1; CID+7460 -9F64 E0100; Hanyo-Denshi; IP9F64 -9F64 E0101; Hanyo-Denshi; TK01101720 -9F66 E0100; Adobe-Japan1; CID+7464 -9F67 E0100; Adobe-Japan1; CID+7465 -9F67 E0101; Adobe-Japan1; CID+14279 -9F67 E0102; Hanyo-Denshi; JA8386 -9F67 E0102; Moji_Joho; MJ030096 -9F67 E0103; Hanyo-Denshi; KS550000 -9F67 E0103; Moji_Joho; MJ030098 -9F67 E0104; Hanyo-Denshi; KS549990S -9F67 E0104; Moji_Joho; MJ030097 -9F68 E0100; Adobe-Japan1; CID+15380 -9F69 E0100; Adobe-Japan1; CID+19126 -9F6A E0100; Adobe-Japan1; CID+7467 -9F6C E0100; Adobe-Japan1; CID+7466 -9F6D E0100; Adobe-Japan1; CID+19127 -9F6E E0100; Adobe-Japan1; CID+23048 -9F6F E0100; Adobe-Japan1; CID+20054 -9F70 E0100; Adobe-Japan1; CID+19128 -9F71 E0100; Adobe-Japan1; CID+15381 -9F72 E0100; Adobe-Japan1; CID+7469 -9F73 E0100; Adobe-Japan1; CID+23049 -9F75 E0100; Adobe-Japan1; CID+15382 -9F76 E0100; Adobe-Japan1; CID+7470 -9F76 E0101; Hanyo-Denshi; JA8391 -9F76 E0101; Moji_Joho; MJ030113 -9F76 E0102; Hanyo-Denshi; KS550740 -9F76 E0102; Moji_Joho; MJ030114 -9F77 E0100; Adobe-Japan1; CID+7468 -9F7A E0100; Adobe-Japan1; CID+23050 -9F7D E0100; Adobe-Japan1; CID+23051 -9F8D E0100; Adobe-Japan1; CID+3966 -9F8D E0101; Adobe-Japan1; CID+14086 -9F8D E0102; Adobe-Japan1; CID+14087 -9F8D E0103; Hanyo-Denshi; JA4622 -9F8D E0103; Moji_Joho; MJ030123 -9F8D E0104; Hanyo-Denshi; JTC0A9 -9F8D E0104; Moji_Joho; MJ030125 -9F8D E0105; Hanyo-Denshi; IB3312 -9F8D E0105; Moji_Joho; MJ030127 -9F8D E0106; Hanyo-Denshi; JTC0A8 -9F8D E0106; Moji_Joho; MJ030126 -9F8D E0107; Hanyo-Denshi; FT2861 -9F8D E0107; Moji_Joho; MJ030124 -9F8D E0108; Hanyo-Denshi; TK01101760 -9F8D E0109; Hanyo-Denshi; TK01101790 -9F8D E010A; Hanyo-Denshi; TK01101810 -9F8D E010B; Hanyo-Denshi; TK01101820 -9F8D E010C; Hanyo-Denshi; TK01101830 -9F8D E010D; Hanyo-Denshi; TK01101840 -9F8E E0100; Hanyo-Denshi; IP9F8E -9F8E E0101; Hanyo-Denshi; TK01013040 -9F8F E0100; Adobe-Japan1; CID+23052 -9F8F E0101; Hanyo-Denshi; JB7756 -9F8F E0101; Moji_Joho; MJ030132 -9F8F E0102; Hanyo-Denshi; TK01101890 -9F8F E0103; Hanyo-Denshi; TK01101910 -9F8F E0104; Moji_Joho; MJ060378 -9F90 E0100; Adobe-Japan1; CID+15383 -9F90 E0101; Hanyo-Denshi; JB7757 -9F90 E0101; Moji_Joho; MJ030135 -9F90 E0102; Hanyo-Denshi; KS551620 -9F90 E0102; Moji_Joho; MJ030136 -9F90 E0103; Hanyo-Denshi; TK01028600 -9F91 E0100; Adobe-Japan1; CID+23053 -9F91 E0101; Hanyo-Denshi; JB7758 -9F91 E0101; Moji_Joho; MJ030138 -9F91 E0102; Hanyo-Denshi; KS551700 -9F91 E0102; Moji_Joho; MJ030139 -9F92 E0100; Adobe-Japan1; CID+23054 -9F93 E0100; Hanyo-Denshi; IP9F93 -9F93 E0100; Moji_Joho; MJ030141 -9F93 E0101; Hanyo-Denshi; KS551840 -9F93 E0101; Moji_Joho; MJ030142 -9F93 E0102; Hanyo-Denshi; TK01101920 -9F94 E0100; Adobe-Japan1; CID+15384 -9F94 E0101; Hanyo-Denshi; JB7760 -9F94 E0101; Moji_Joho; MJ030143 -9F94 E0102; Hanyo-Denshi; KS551820 -9F94 E0102; Moji_Joho; MJ030144 -9F95 E0100; Adobe-Japan1; CID+7471 -9F95 E0101; Hanyo-Denshi; JA8392 -9F95 E0101; Moji_Joho; MJ030145 -9F95 E0102; Hanyo-Denshi; KS551830 -9F95 E0102; Moji_Joho; MJ030146 -9F96 E0100; Adobe-Japan1; CID+23055 -9F97 E0100; Adobe-Japan1; CID+17232 -9F97 E0101; Hanyo-Denshi; JB7762 -9F97 E0102; Hanyo-Denshi; TK01097310 -9F97 E0103; Hanyo-Denshi; TK01097320 -9F97 E0104; Hanyo-Denshi; TK01097330 -9F97 E0105; Hanyo-Denshi; TK01097350 -9F98 E0100; Hanyo-Denshi; IP9F98 -9F98 E0100; Moji_Joho; MJ030150 -9F98 E0101; Hanyo-Denshi; KS551900 -9F98 E0101; Moji_Joho; MJ030151 -9F9A E0100; Hanyo-Denshi; TK01007670 -9F9A E0101; Hanyo-Denshi; TK01007720 -9F9C E0100; Adobe-Japan1; CID+7472 -9F9C E0101; Adobe-Japan1; CID+7886 -9F9C E0102; Hanyo-Denshi; JA8393 -9F9C E0102; Moji_Joho; MJ030155 -9F9C E0103; Hanyo-Denshi; KS551980S -9F9C E0103; Moji_Joho; MJ030157 -9F9C E0104; Hanyo-Denshi; KS551930 -9F9C E0104; Moji_Joho; MJ030154 -9F9C E0105; Hanyo-Denshi; FT2013S -9F9C E0105; Moji_Joho; MJ030158 -9F9C E0106; Hanyo-Denshi; JTC0AE -9F9C E0106; Moji_Joho; MJ030156 -9F9D E0100; Adobe-Japan1; CID+5927 -9F9D E0101; Adobe-Japan1; CID+7847 -9F9D E0102; Hanyo-Denshi; JA6752 -9F9D E0102; Moji_Joho; MJ030160 -9F9D E0103; Hanyo-Denshi; JTB769 -9F9D E0103; Moji_Joho; MJ030159 -9F9D E0104; Moji_Joho; MJ030161 -9F9E E0100; Adobe-Japan1; CID+20055 -9FA0 E0100; Adobe-Japan1; CID+7473 -9FA1 E0100; Adobe-Japan1; CID+23056 -9FA2 E0100; Adobe-Japan1; CID+15385 -9FA2 E0101; Hanyo-Denshi; JB7765 -9FA2 E0102; Hanyo-Denshi; TK01102080 -9FA3 E0100; Adobe-Japan1; CID+23057 -9FA5 E0100; Adobe-Japan1; CID+20056 -9FAC E0100; Hanyo-Denshi; JTBDF9 -9FAC E0100; Moji_Joho; MJ030171 -9FAC E0101; Hanyo-Denshi; JTBDFA -9FAC E0101; Moji_Joho; MJ030172 -9FB4 E0100; Adobe-Japan1; CID+14048 -9FBC E0100; Adobe-Japan1; CID+15431 -9FBD E0100; Adobe-Japan1; CID+15429 -9FBD E0101; Hanyo-Denshi; JTB541 -9FBD E0102; Hanyo-Denshi; TK01055620 -9FBE E0100; Adobe-Japan1; CID+15434 -9FBF E0100; Adobe-Japan1; CID+20068 -9FC0 E0100; Adobe-Japan1; CID+20069 -9FC1 E0100; Adobe-Japan1; CID+20070 -9FC2 E0100; Adobe-Japan1; CID+20071 -9FC4 E0100; Adobe-Japan1; CID+14089 -9FC4 E0101; Hanyo-Denshi; AR0001 -9FC4 E0102; Hanyo-Denshi; TK01043280 -9FC6 E0100; Adobe-Japan1; CID+14168 -9FC6 E0101; Moji_Joho; MJ018788 -9FC6 E0102; Moji_Joho; MJ030182 -9FCC E0100; Adobe-Japan1; CID+20156 -FA0E E0100; Adobe-Japan1; CID+8410 -FA0E E0101; Moji_Joho; MJ030191 -FA0E E0102; Moji_Joho; MJ030192 -FA0F E0100; Adobe-Japan1; CID+8421 -FA11 E0100; Adobe-Japan1; CID+14290 -FA11 E0101; Adobe-Japan1; CID+8443 -FA11 E0102; Hanyo-Denshi; JC4782 -FA11 E0102; Moji_Joho; MJ030196 -FA11 E0103; Hanyo-Denshi; JTB07A -FA11 E0103; Moji_Joho; MJ030197 -FA11 E0104; Hanyo-Denshi; TK01025180 -FA13 E0100; Adobe-Japan1; CID+8497 -FA13 E0101; Hanyo-Denshi; JD1489 -FA13 E0101; Moji_Joho; MJ030200 -FA13 E0102; Hanyo-Denshi; KS171810 -FA13 E0102; Moji_Joho; MJ030201 -FA14 E0100; Adobe-Japan1; CID+8499 -FA1F E0100; Adobe-Japan1; CID+8610 -FA1F E0101; Hanyo-Denshi; JC9126 -FA1F E0101; Moji_Joho; MJ030217 -FA1F E0102; Hanyo-Denshi; JTBA41 -FA1F E0102; Moji_Joho; MJ030219 -FA1F E0103; Hanyo-Denshi; JTBA6C -FA1F E0103; Moji_Joho; MJ030218 -FA21 E0100; Adobe-Japan1; CID+8613 -FA23 E0100; Adobe-Japan1; CID+8630 -FA24 E0100; Adobe-Japan1; CID+18760 -FA24 E0101; Adobe-Japan1; CID+8632 -FA24 E0102; Hanyo-Denshi; JD8978 -FA24 E0102; Moji_Joho; MJ030233 -FA24 E0103; Hanyo-Denshi; IB3004 -FA24 E0103; Moji_Joho; MJ030229 -FA24 E0104; Hanyo-Denshi; JTBC47 -FA24 E0104; Moji_Joho; MJ030230 -FA24 E0105; Hanyo-Denshi; JTBC48 -FA24 E0105; Moji_Joho; MJ030231 -FA24 E0106; Hanyo-Denshi; JTBC49 -FA24 E0106; Moji_Joho; MJ030232 -FA24 E0107; Moji_Joho; MJ030228 -FA27 E0100; Adobe-Japan1; CID+8664 -FA27 E0101; Moji_Joho; MJ030236 -FA27 E0102; Moji_Joho; MJ030237 -FA28 E0100; Adobe-Japan1; CID+8671 -FA29 E0100; Adobe-Japan1; CID+8687 -20000 E0100; Moji_Joho; MJ030312 -20000 E0101; Moji_Joho; MJ030313 -2000B E0100; Adobe-Japan1; CID+13839 -2000B E0101; Hanyo-Denshi; JC1402 -2000B E0101; Moji_Joho; MJ030320 -2000B E0102; Hanyo-Denshi; TK01000070 -2000B E0103; Moji_Joho; MJ030319 -20041 E0100; Hanyo-Denshi; KS000990 -20041 E0100; Moji_Joho; MJ030345 -20041 E0101; Hanyo-Denshi; KS001000 -20041 E0102; Hanyo-Denshi; KS001010 -20041 E0102; Moji_Joho; MJ030346 -20041 E0103; Hanyo-Denshi; KS001020 -20041 E0103; Moji_Joho; MJ056847 -20045 E0100; Hanyo-Denshi; KS372080 -20045 E0100; Moji_Joho; MJ058590 -20045 E0101; Hanyo-Denshi; KS372100 -20045 E0101; Moji_Joho; MJ058592 -20045 E0102; Hanyo-Denshi; TK01082840 -2004A E0100; Hanyo-Denshi; KS017640 -2004A E0100; Moji_Joho; MJ056998 -2004A E0101; Hanyo-Denshi; KS068620 -2004A E0101; Moji_Joho; MJ057285 -20089 E0100; Adobe-Japan1; CID+17233 -2008A E0100; Adobe-Japan1; CID+14108 -200A2 E0100; Adobe-Japan1; CID+17240 -200A2 E0101; Hanyo-Denshi; JD0111 -200A2 E0101; Moji_Joho; MJ030387 -200A2 E0102; Hanyo-Denshi; KS001650 -200A2 E0102; Moji_Joho; MJ030386 -200A4 E0100; Adobe-Japan1; CID+17243 -200B0 E0100; Adobe-Japan1; CID+14209 -200B9 E0100; Hanyo-Denshi; KS001860 -200B9 E0101; Hanyo-Denshi; TK01000770 -200E4 E0100; Hanyo-Denshi; KS002230 -200E4 E0100; Moji_Joho; MJ030427 -200E4 E0101; Hanyo-Denshi; KS098160 -200E4 E0101; Moji_Joho; MJ057398 -200F5 E0100; Adobe-Japan1; CID+20057 -2010C E0100; Hanyo-Denshi; KS002670 -2010C E0101; Hanyo-Denshi; KS002680 -20122 E0100; Hanyo-Denshi; KS003180 -20122 E0100; Moji_Joho; MJ030466 -20122 E0101; Hanyo-Denshi; KS003250 -20122 E0101; Moji_Joho; MJ030467 -2012C E0100; Hanyo-Denshi; KS003320 -2012C E0101; Hanyo-Denshi; KS164260 -2012C E0102; Hanyo-Denshi; TK01001260 -20158 E0100; Adobe-Japan1; CID+20075 -2015E E0100; Moji_Joho; MJ030496 -2015E E0101; Moji_Joho; MJ030497 -201A2 E0100; Adobe-Japan1; CID+13857 -201BB E0100; Hanyo-Denshi; JTB06D -201BB E0100; Moji_Joho; MJ030551 -201BB E0101; Hanyo-Denshi; KS005380 -201BB E0101; Moji_Joho; MJ030550 -201C3 E0100; Hanyo-Denshi; TK01002670 -201C3 E0101; Hanyo-Denshi; TK01007170 -201D9 E0100; Hanyo-Denshi; KS006240 -201D9 E0101; Hanyo-Denshi; TK01002970 -201FE E0100; Hanyo-Denshi; KS006290 -201FE E0100; Moji_Joho; MJ030573 -201FE E0101; Hanyo-Denshi; KS007510 -201FE E0101; Moji_Joho; MJ056920 -20213 E0100; Adobe-Japan1; CID+17259 -20237 E0100; Hanyo-Denshi; KS008060 -20237 E0100; Moji_Joho; MJ030613 -20237 E0101; Hanyo-Denshi; KS008550 -20237 E0101; Moji_Joho; MJ030614 -2024C E0100; Hanyo-Denshi; JTAD61 -2024C E0101; Hanyo-Denshi; TK01003880 -20255 E0100; Moji_Joho; MJ030629 -20255 E0101; Moji_Joho; MJ030630 -2025B E0100; Hanyo-Denshi; TK01003650 -2025B E0101; Hanyo-Denshi; TK01003810 -20265 E0100; Hanyo-Denshi; KS008810 -20265 E0101; Hanyo-Denshi; TK01004290 -2026E E0100; Hanyo-Denshi; KS009400 -2026E E0101; Hanyo-Denshi; TK01004090 -2027D E0100; Hanyo-Denshi; TK01004160 -2027D E0101; Hanyo-Denshi; TK01007190 -202A2 E0100; Hanyo-Denshi; KS009430 -202A2 E0101; Hanyo-Denshi; TK01004150 -202A7 E0100; Hanyo-Denshi; KS009730 -202A7 E0101; Hanyo-Denshi; TK01004140 -202EC E0100; Hanyo-Denshi; JTAD76 -202EC E0100; Moji_Joho; MJ030707 -202EC E0101; Hanyo-Denshi; KS010560 -202EC E0101; Moji_Joho; MJ030706 -20318 E0100; Hanyo-Denshi; JTAD87 -20318 E0100; Moji_Joho; MJ030732 -20318 E0101; Hanyo-Denshi; KS011500 -20318 E0101; Moji_Joho; MJ030731 -2032B E0100; Adobe-Japan1; CID+17282 -2032B E0101; Hanyo-Denshi; JD0180 -2032B E0101; Moji_Joho; MJ030742 -2032B E0102; Hanyo-Denshi; KS011790 -2032B E0102; Moji_Joho; MJ030741 -20371 E0100; Adobe-Japan1; CID+17291 -20381 E0100; Adobe-Japan1; CID+17289 -203A7 E0100; Hanyo-Denshi; JTADA1 -203A7 E0101; Hanyo-Denshi; TK01005990 -203B9 E0100; Hanyo-Denshi; KS013470 -203B9 E0100; Moji_Joho; MJ030811 -203B9 E0101; Hanyo-Denshi; KS013480 -203B9 E0101; Moji_Joho; MJ030812 -203B9 E0102; Hanyo-Denshi; TK01006100 -203BF E0100; Hanyo-Denshi; KS013810 -203BF E0101; Hanyo-Denshi; TK01006170 -203E8 E0100; Hanyo-Denshi; KS014130 -203E8 E0101; Hanyo-Denshi; TK01006240 -203F9 E0100; Adobe-Japan1; CID+17295 -203F9 E0101; Hanyo-Denshi; JD0302 -203F9 E0101; Moji_Joho; MJ030848 -203F9 E0102; Hanyo-Denshi; KS014410 -203F9 E0102; Moji_Joho; MJ056954 -203FC E0100; Hanyo-Denshi; TK01006260 -203FC E0101; Hanyo-Denshi; TK01006310 -20409 E0100; Hanyo-Denshi; KS014500 -20409 E0101; Hanyo-Denshi; TK01006090 -20409 E0102; Hanyo-Denshi; TK01006290 -20409 E0103; Hanyo-Denshi; TK01006340 -2044A E0100; Adobe-Japan1; CID+17297 -20457 E0100; Hanyo-Denshi; IA0981 -20457 E0100; Moji_Joho; MJ030887 -20457 E0101; Hanyo-Denshi; KS015160 -20457 E0101; Moji_Joho; MJ056959 -2048C E0100; Hanyo-Denshi; KS016070 -2048C E0101; Hanyo-Denshi; TK01076830 -20496 E0100; Moji_Joho; MJ030926 -20496 E0101; Moji_Joho; MJ030927 -204CA E0100; Hanyo-Denshi; KS016460 -204CA E0101; Hanyo-Denshi; TK01007110 -204ED E0100; Hanyo-Denshi; KS016810 -204ED E0101; Hanyo-Denshi; TK01004530 -20509 E0100; Adobe-Japan1; CID+17299 -20509 E0101; Hanyo-Denshi; JD0307 -20509 E0101; Moji_Joho; MJ030984 -20509 E0102; Hanyo-Denshi; KS016680 -20509 E0102; Moji_Joho; MJ030983 -20523 E0100; Hanyo-Denshi; KS098910 -20523 E0101; Hanyo-Denshi; TK01026490 -20525 E0100; Hanyo-Denshi; IB0614 -20525 E0100; Moji_Joho; MJ031010 -20525 E0101; Hanyo-Denshi; IB0615 -20525 E0101; Moji_Joho; MJ056992 -20525 E0102; Hanyo-Denshi; IB0617 -20525 E0102; Moji_Joho; MJ056997 -20525 E0103; Hanyo-Denshi; KS017520 -20525 E0103; Moji_Joho; MJ031009 -20525 E0104; Hanyo-Denshi; KS017600 -20525 E0104; Moji_Joho; MJ031011 -20525 E0105; Hanyo-Denshi; KS215800 -20525 E0105; Moji_Joho; MJ031012 -20525 E0106; Hanyo-Denshi; TK01007750 -20525 E0107; Hanyo-Denshi; TK01007790 -20525 E0108; Hanyo-Denshi; TK01007810 -20525 E0108; Moji_Joho; MJ059329 -2053F E0100; Adobe-Japan1; CID+14188 -20540 E0100; Hanyo-Denshi; KS315150 -20540 E0100; Moji_Joho; MJ031028 -20540 E0101; Hanyo-Denshi; KS315180 -20540 E0101; Moji_Joho; MJ031029 -2054B E0100; Hanyo-Denshi; KS017960 -2054B E0100; Moji_Joho; MJ031035 -2054B E0101; Hanyo-Denshi; KS018020 -2054B E0101; Moji_Joho; MJ057002 -2054B E0102; Moji_Joho; MJ057003 -205B1 E0100; Adobe-Japan1; CID+20080 -205D6 E0100; Adobe-Japan1; CID+17308 -205EE E0100; Hanyo-Denshi; TK01008860 -205EE E0101; Hanyo-Denshi; TK01008900 -20611 E0100; Adobe-Japan1; CID+14294 -20628 E0100; Adobe-Japan1; CID+14105 -2062F E0100; Moji_Joho; MJ031160 -2062F E0101; Moji_Joho; MJ031965 -2065A E0100; Hanyo-Denshi; KS021110 -2065A E0101; Hanyo-Denshi; TK01009430 -2065A E0102; Hanyo-Denshi; TK01082830 -206A3 E0100; Hanyo-Denshi; KS021810 -206A3 E0100; Moji_Joho; MJ031235 -206A3 E0101; Hanyo-Denshi; KS021820 -206A3 E0101; Moji_Joho; MJ031236 -206C9 E0100; Moji_Joho; MJ031264 -206C9 E0101; Moji_Joho; MJ031265 -206E8 E0100; Hanyo-Denshi; KS023200 -206E8 E0101; Hanyo-Denshi; TK01009850 -206EC E0100; Adobe-Japan1; CID+20083 -206EE E0100; Moji_Joho; MJ031291 -206EE E0101; Moji_Joho; MJ031295 -206F9 E0100; Moji_Joho; MJ031302 -206F9 E0101; Moji_Joho; MJ031303 -2071B E0100; Hanyo-Denshi; KS023680 -2071B E0101; Hanyo-Denshi; TK01009920 -2074F E0100; Adobe-Japan1; CID+17312 -2075F E0100; Hanyo-Denshi; KS024400 -2075F E0101; Hanyo-Denshi; TK01010030 -207C8 E0100; Adobe-Japan1; CID+20128 -20807 E0100; Adobe-Japan1; CID+17319 -20807 E0101; Hanyo-Denshi; JD0331 -20807 E0101; Moji_Joho; MJ031473 -20807 E0102; Hanyo-Denshi; KS026240 -20807 E0102; Moji_Joho; MJ031474 -2083A E0100; Adobe-Japan1; CID+17321 -2083A E0101; Hanyo-Denshi; JD0333 -2083A E0102; Hanyo-Denshi; TK01010400 -2085E E0100; Hanyo-Denshi; KS027320 -2085E E0101; Hanyo-Denshi; TK01010670 -2085F E0100; Hanyo-Denshi; IB1473 -2085F E0101; Hanyo-Denshi; TK01010570 -20876 E0100; Hanyo-Denshi; KS027660 -20876 E0101; Hanyo-Denshi; TK01010800 -20886 E0100; Hanyo-Denshi; KS027920 -20886 E0101; Hanyo-Denshi; TK01011020 -20886 E0102; Hanyo-Denshi; TK01011090 -20889 E0100; Hanyo-Denshi; KS028000 -20889 E0101; Hanyo-Denshi; TK01011030 -20895 E0100; Hanyo-Denshi; KS028140 -20895 E0101; Hanyo-Denshi; TK01011000 -208A7 E0100; Hanyo-Denshi; KS028480 -208A7 E0101; Hanyo-Denshi; TK01075990 -208B9 E0100; Adobe-Japan1; CID+17327 -208B9 E0101; Hanyo-Denshi; JD0342 -208B9 E0102; Hanyo-Denshi; TK01011310 -208E5 E0100; Hanyo-Denshi; KS029430 -208E5 E0100; Moji_Joho; MJ031618 -208E5 E0101; Hanyo-Denshi; KS029500 -208E5 E0101; Moji_Joho; MJ031619 -2090E E0100; Adobe-Japan1; CID+13523 -2097C E0100; Adobe-Japan1; CID+17331 -20984 E0100; Adobe-Japan1; CID+14109 -20984 E0101; Hanyo-Denshi; HG1610 -20984 E0101; Moji_Joho; MJ031728 -20984 E0102; Hanyo-Denshi; JTAE64 -20984 E0102; Moji_Joho; MJ031729 -20985 E0100; Hanyo-Denshi; KS031550 -20985 E0101; Hanyo-Denshi; TK01011830 -2099D E0100; Adobe-Japan1; CID+17332 -209E9 E0100; Hanyo-Denshi; KS032540 -209E9 E0101; Hanyo-Denshi; TK01012310 -209EF E0100; Hanyo-Denshi; TK01012320 -209EF E0101; Hanyo-Denshi; TK01012330 -209EF E0102; Hanyo-Denshi; TK01012340 -20A10 E0100; Hanyo-Denshi; KS032890 -20A10 E0101; Hanyo-Denshi; TK01012400 -20A27 E0100; Hanyo-Denshi; KS033500 -20A27 E0100; Moji_Joho; MJ031841 -20A27 E0101; Hanyo-Denshi; KS099420 -20A27 E0101; Moji_Joho; MJ057416 -20A41 E0100; Hanyo-Denshi; KS033830 -20A41 E0101; Hanyo-Denshi; TK01012680 -20A4A E0100; Hanyo-Denshi; KS033930 -20A4A E0101; Hanyo-Denshi; TK01012770 -20A64 E0100; Adobe-Japan1; CID+13755 -20AD3 E0100; Adobe-Japan1; CID+17337 -20AD3 E0101; Hanyo-Denshi; JD0357 -20AD3 E0101; Moji_Joho; MJ031960 -20AD3 E0102; Hanyo-Denshi; KS035360 -20AD3 E0102; Moji_Joho; MJ031959 -20AE4 E0100; Hanyo-Denshi; KS035630 -20AE4 E0100; Moji_Joho; MJ031974 -20AE4 E0101; Hanyo-Denshi; KS035640 -20AE4 E0101; Moji_Joho; MJ057125 -20B1D E0100; Adobe-Japan1; CID+17340 -20B4D E0100; Hanyo-Denshi; KS036870 -20B4D E0101; Hanyo-Denshi; TK01096810 -20B63 E0100; Hanyo-Denshi; KS037010 -20B63 E0100; Moji_Joho; MJ032063 -20B63 E0101; Hanyo-Denshi; KS037020 -20B63 E0101; Moji_Joho; MJ032064 -20B6F E0100; Hanyo-Denshi; KS037120 -20B6F E0100; Moji_Joho; MJ032069 -20B6F E0101; Hanyo-Denshi; KS037220 -20B6F E0101; Moji_Joho; MJ032070 -20B93 E0100; Moji_Joho; MJ032097 -20B93 E0101; Moji_Joho; MJ032098 -20B9F E0100; Adobe-Japan1; CID+13803 -20BB1 E0100; Hanyo-Denshi; KS038020 -20BB1 E0100; Moji_Joho; MJ032123 -20BB1 E0101; Hanyo-Denshi; KS038450 -20BB1 E0101; Moji_Joho; MJ032124 -20BB7 E0100; Adobe-Japan1; CID+13706 -20BCC E0100; Hanyo-Denshi; KS038560 -20BCC E0100; Moji_Joho; MJ032141 -20BCC E0101; Hanyo-Denshi; KS039600 -20BCC E0101; Moji_Joho; MJ057146 -20C50 E0100; Hanyo-Denshi; KS040720 -20C50 E0100; Moji_Joho; MJ032210 -20C50 E0101; Hanyo-Denshi; KS043070 -20C50 E0101; Moji_Joho; MJ057161 -20C74 E0100; Hanyo-Denshi; KS041540 -20C74 E0101; Hanyo-Denshi; TK01014200 -20C9C E0100; Hanyo-Denshi; TK01014280 -20C9C E0101; Hanyo-Denshi; TK01014620 -20D45 E0100; Adobe-Japan1; CID+17359 -20D45 E0101; Hanyo-Denshi; JD0387 -20D45 E0101; Moji_Joho; MJ032336 -20D45 E0102; Hanyo-Denshi; KS044470 -20D45 E0102; Moji_Joho; MJ032335 -20D4A E0100; Hanyo-Denshi; JTAECC -20D4A E0100; Moji_Joho; MJ032338 -20D4A E0101; Hanyo-Denshi; KS044330 -20D4A E0101; Moji_Joho; MJ032337 -20D58 E0100; Adobe-Japan1; CID+20090 -20DAE E0100; Hanyo-Denshi; JTAED0 -20DAE E0100; Moji_Joho; MJ032368 -20DAE E0101; Hanyo-Denshi; JTAED1 -20DAE E0101; Moji_Joho; MJ032369 -20DB7 E0100; Hanyo-Denshi; KS044670 -20DB7 E0100; Moji_Joho; MJ032376 -20DB7 E0101; Hanyo-Denshi; KS046320 -20DB7 E0101; Moji_Joho; MJ032377 -20DB8 E0100; Hanyo-Denshi; KS044680 -20DB8 E0100; Moji_Joho; MJ032378 -20DB8 E0101; Hanyo-Denshi; KS046330 -20DB8 E0101; Moji_Joho; MJ032379 -20DD4 E0100; Hanyo-Denshi; KS045600 -20DD4 E0100; Moji_Joho; MJ032407 -20DD4 E0101; Hanyo-Denshi; KS047530 -20DD4 E0101; Moji_Joho; MJ057185 -20DE1 E0100; Adobe-Japan1; CID+17373 -20DE1 E0101; Hanyo-Denshi; JD0410 -20DE1 E0102; Hanyo-Denshi; TK01014840 -20E49 E0100; Hanyo-Denshi; KS046590 -20E49 E0101; Hanyo-Denshi; TK01039950 -20E64 E0100; Adobe-Japan1; CID+17388 -20E6D E0100; Adobe-Japan1; CID+17380 -20E95 E0100; Adobe-Japan1; CID+17379 -20EDB E0100; Hanyo-Denshi; IB0305 -20EDB E0100; Moji_Joho; MJ032504 -20EDB E0101; Hanyo-Denshi; IB0633 -20EDB E0101; Moji_Joho; MJ032503 -20F5F E0100; Adobe-Japan1; CID+17391 -20FCB E0100; Hanyo-Denshi; KS049840 -20FCB E0100; Moji_Joho; MJ032603 -20FCB E0101; Hanyo-Denshi; KS050000 -20FCB E0101; Moji_Joho; MJ032604 -20FD5 E0100; Hanyo-Denshi; KS050190 -20FD5 E0100; Moji_Joho; MJ032671 -20FD5 E0101; Hanyo-Denshi; KS050820 -20FD5 E0101; Moji_Joho; MJ032672 -20FE0 E0100; Hanyo-Denshi; KS050380 -20FE0 E0101; Hanyo-Denshi; TK01015490 -2113B E0100; Hanyo-Denshi; JTAFAB -2113B E0100; Moji_Joho; MJ032763 -2113B E0101; Hanyo-Denshi; KS052780 -2113B E0101; Moji_Joho; MJ032762 -21201 E0100; Adobe-Japan1; CID+17414 -21202 E0100; Hanyo-Denshi; TK01016000 -21202 E0101; Hanyo-Denshi; TK01016120 -2123D E0100; Adobe-Japan1; CID+13953 -21255 E0100; Adobe-Japan1; CID+17415 -21274 E0100; Adobe-Japan1; CID+17421 -21274 E0101; Hanyo-Denshi; JD0467 -21274 E0101; Moji_Joho; MJ032959 -21274 E0102; Hanyo-Denshi; JTAF4A -21274 E0102; Moji_Joho; MJ032960 -21275 E0100; Hanyo-Denshi; KS055980 -21275 E0100; Moji_Joho; MJ057209 -21275 E0101; Hanyo-Denshi; KS056610 -21275 E0101; Moji_Joho; MJ032961 -2127B E0100; Adobe-Japan1; CID+17417 -2128F E0100; Hanyo-Denshi; KS035670 -2128F E0100; Moji_Joho; MJ032980 -2128F E0101; Hanyo-Denshi; KS057210 -2128F E0101; Moji_Joho; MJ032981 -21299 E0100; Hanyo-Denshi; IB0642 -21299 E0100; Moji_Joho; MJ057214 -21299 E0101; Hanyo-Denshi; JTAF50 -21299 E0101; Moji_Joho; MJ057215 -212A5 E0100; Hanyo-Denshi; KS056660 -212A5 E0100; Moji_Joho; MJ057212 -212A5 E0101; Hanyo-Denshi; KS057290 -212A5 E0101; Moji_Joho; MJ032991 -212D7 E0100; Adobe-Japan1; CID+17429 -212E4 E0100; Adobe-Japan1; CID+17428 -212F3 E0100; Hanyo-Denshi; KS058490 -212F3 E0100; Moji_Joho; MJ033026 -212F3 E0101; Hanyo-Denshi; KS058890 -212F3 E0101; Moji_Joho; MJ033027 -212FD E0100; Adobe-Japan1; CID+17435 -2131B E0100; Adobe-Japan1; CID+16816 -2131B E0101; Moji_Joho; MJ033042 -2131B E0102; Moji_Joho; MJ033043 -21328 E0100; Hanyo-Denshi; KS058840 -21328 E0100; Moji_Joho; MJ057222 -21328 E0101; Hanyo-Denshi; KS059030 -21328 E0101; Moji_Joho; MJ033052 -21336 E0100; Adobe-Japan1; CID+17437 -21344 E0100; Adobe-Japan1; CID+17438 -21369 E0100; Hanyo-Denshi; KS059920 -21369 E0100; Moji_Joho; MJ033083 -21369 E0101; Hanyo-Denshi; KS060790 -21369 E0101; Moji_Joho; MJ057235 -2136E E0100; Hanyo-Denshi; KS060160 -2136E E0100; Moji_Joho; MJ033088 -2136E E0101; Hanyo-Denshi; KS060760 -2136E E0101; Moji_Joho; MJ033089 -21375 E0100; Hanyo-Denshi; KS060810 -21375 E0101; Hanyo-Denshi; TK01017500 -213C4 E0100; Adobe-Japan1; CID+17449 -213C4 E0101; Hanyo-Denshi; JD0505 -213C4 E0102; Hanyo-Denshi; TK01017260 -21424 E0100; Hanyo-Denshi; KS062590 -21424 E0101; Hanyo-Denshi; TK01017900 -2145E E0100; Hanyo-Denshi; IB0309 -2145E E0100; Moji_Joho; MJ033195 -2145E E0101; Hanyo-Denshi; IB0650 -2145E E0101; Moji_Joho; MJ033194 -2145F E0100; Hanyo-Denshi; IB0308 -2145F E0100; Moji_Joho; MJ033197 -2145F E0101; Hanyo-Denshi; IB0649 -2145F E0101; Moji_Joho; MJ033196 -2146D E0100; Adobe-Japan1; CID+17462 -2146D E0101; Hanyo-Denshi; JD0518 -2146D E0101; Moji_Joho; MJ033205 -2146D E0102; Hanyo-Denshi; JTAF86 -2146D E0102; Moji_Joho; MJ033204 -2146E E0100; Adobe-Japan1; CID+16821 -214E4 E0100; Hanyo-Denshi; KS063930 -214E4 E0100; Moji_Joho; MJ033254 -214E4 E0101; Hanyo-Denshi; KS064120 -214E4 E0101; Moji_Joho; MJ033255 -21552 E0100; Hanyo-Denshi; KS065140 -21552 E0100; Moji_Joho; MJ033317 -21552 E0101; Hanyo-Denshi; KS065150 -21552 E0101; Moji_Joho; MJ033318 -21569 E0100; Hanyo-Denshi; KS065600 -21569 E0101; Hanyo-Denshi; KS065610 -215B6 E0100; Hanyo-Denshi; KS066560 -215B6 E0101; Hanyo-Denshi; TK01018930 -215D2 E0100; Hanyo-Denshi; KS066900 -215D2 E0100; Moji_Joho; MJ033409 -215D2 E0101; Hanyo-Denshi; KS066930 -215D2 E0101; Moji_Joho; MJ057270 -215D7 E0100; Adobe-Japan1; CID+17472 -21606 E0100; Hanyo-Denshi; KS067640 -21606 E0100; Moji_Joho; MJ033440 -21606 E0101; Hanyo-Denshi; KS067690 -21606 E0101; Moji_Joho; MJ033441 -21624 E0100; Hanyo-Denshi; KS068090 -21624 E0101; Hanyo-Denshi; TK01019450 -21641 E0100; Hanyo-Denshi; KS068330 -21641 E0101; Hanyo-Denshi; TK01019570S -21647 E0100; Adobe-Japan1; CID+17480 -21691 E0100; Hanyo-Denshi; KS069070 -21691 E0101; Hanyo-Denshi; TK01019930 -216B4 E0100; Adobe-Japan1; CID+16838 -216B9 E0100; Hanyo-Denshi; KS069530 -216B9 E0101; Hanyo-Denshi; TK01020110 -216CC E0100; Hanyo-Denshi; KS070080 -216CC E0101; Hanyo-Denshi; TK01020120 -21706 E0100; Adobe-Japan1; CID+17492 -21706 E0101; Hanyo-Denshi; JD0553 -21706 E0101; Moji_Joho; MJ033579 -21706 E0102; Hanyo-Denshi; KS071330 -21706 E0102; Moji_Joho; MJ033578 -21742 E0100; Adobe-Japan1; CID+17493 -21764 E0100; Hanyo-Denshi; KS072920 -21764 E0100; Moji_Joho; MJ033638 -21764 E0101; Hanyo-Denshi; KS073700 -21764 E0101; Moji_Joho; MJ057303 -21800 E0100; Hanyo-Denshi; TK01020690 -21800 E0101; Hanyo-Denshi; TK01020760 -21898 E0100; Hanyo-Denshi; KS077190 -21898 E0100; Moji_Joho; MJ033773 -21898 E0101; Hanyo-Denshi; KS077520 -21898 E0101; Moji_Joho; MJ033774 -218BD E0100; Adobe-Japan1; CID+16833 -218EA E0100; Hanyo-Denshi; IB0310 -218EA E0100; Moji_Joho; MJ033818 -218EA E0101; Hanyo-Denshi; IB0656 -218EA E0101; Moji_Joho; MJ033817 -21969 E0100; Hanyo-Denshi; KS079430 -21969 E0101; Hanyo-Denshi; TK01021190 -21969 E0102; Hanyo-Denshi; TK01021200 -2198C E0100; Hanyo-Denshi; KS079820 -2198C E0101; Hanyo-Denshi; TK01021380 -219C3 E0100; Adobe-Japan1; CID+17525 -219C8 E0100; Hanyo-Denshi; KS080360 -219C8 E0100; Moji_Joho; MJ033942 -219C8 E0101; Hanyo-Denshi; KS080370 -219C8 E0101; Moji_Joho; MJ033943 -219EC E0100; Hanyo-Denshi; KS081040 -219EC E0101; Hanyo-Denshi; TK01021770 -219F1 E0100; Moji_Joho; MJ033973 -219F1 E0101; Moji_Joho; MJ057330 -219FD E0100; Hanyo-Denshi; IB1663S -219FD E0101; Hanyo-Denshi; TK01021690 -21A1A E0100; Adobe-Japan1; CID+7825 -21A41 E0100; Hanyo-Denshi; KS082200 -21A41 E0101; Hanyo-Denshi; TK01022390 -21A62 E0100; Hanyo-Denshi; KS082510 -21A62 E0101; Hanyo-Denshi; TK01022590 -21AA2 E0100; Moji_Joho; MJ034079 -21AA2 E0101; Moji_Joho; MJ034080 -21B33 E0100; Hanyo-Denshi; KS084630 -21B33 E0101; Hanyo-Denshi; TK01023570 -21B4E E0100; Hanyo-Denshi; IB0311 -21B4E E0100; Moji_Joho; MJ034187 -21B4E E0101; Hanyo-Denshi; IB0661 -21B4E E0101; Moji_Joho; MJ034186 -21B8E E0100; Hanyo-Denshi; KS085470 -21B8E E0101; Hanyo-Denshi; TK01009500 -21BCE E0100; Hanyo-Denshi; JTB04F -21BCE E0101; Hanyo-Denshi; TK01023860 -21BED E0100; Hanyo-Denshi; KS086180 -21BED E0100; Moji_Joho; MJ034265 -21BED E0101; Hanyo-Denshi; KS086200 -21BED E0101; Moji_Joho; MJ034267 -21C12 E0100; Hanyo-Denshi; KS086560 -21C12 E0100; Moji_Joho; MJ034292 -21C12 E0101; Hanyo-Denshi; KS086590 -21C12 E0101; Moji_Joho; MJ034293 -21C31 E0100; Hanyo-Denshi; KS086810 -21C31 E0100; Moji_Joho; MJ057366 -21C31 E0101; Hanyo-Denshi; KS086940 -21C31 E0101; Moji_Joho; MJ034313 -21C52 E0100; Hanyo-Denshi; KS087440 -21C52 E0101; Hanyo-Denshi; TK01024040 -21C56 E0100; Adobe-Japan1; CID+17539 -21D15 E0100; Hanyo-Denshi; KS089090 -21D15 E0101; Hanyo-Denshi; TK01024780 -21D15 E0102; Hanyo-Denshi; TK01025120 -21D2D E0100; Adobe-Japan1; CID+17544 -21D43 E0100; Hanyo-Denshi; TK01024420 -21D43 E0101; Hanyo-Denshi; TK01024430 -21D45 E0100; Adobe-Japan1; CID+17545 -21D58 E0100; Hanyo-Denshi; KS089870 -21D58 E0101; Hanyo-Denshi; TK01024500 -21D62 E0100; Adobe-Japan1; CID+17547 -21D78 E0100; Adobe-Japan1; CID+17546 -21D92 E0100; Adobe-Japan1; CID+17556 -21D9C E0100; Adobe-Japan1; CID+17552 -21D9C E0101; Hanyo-Denshi; JD0832 -21D9C E0102; Hanyo-Denshi; TK01024640 -21DA1 E0100; Adobe-Japan1; CID+17551 -21DA1 E0101; Hanyo-Denshi; JD0831 -21DA1 E0101; Moji_Joho; MJ034543 -21DA1 E0102; Hanyo-Denshi; JTB069 -21DA1 E0102; Moji_Joho; MJ034542 -21DB7 E0100; Adobe-Japan1; CID+17559 -21DE0 E0100; Adobe-Japan1; CID+17561 -21DE4 E0100; Hanyo-Denshi; KS091410 -21DE4 E0100; Moji_Joho; MJ034584 -21DE4 E0101; Hanyo-Denshi; KS091950 -21DE4 E0101; Moji_Joho; MJ034585 -21DE5 E0100; Hanyo-Denshi; KS091980 -21DE5 E0101; Hanyo-Denshi; TK01025100 -21DE6 E0100; Hanyo-Denshi; KS092000 -21DE6 E0100; Moji_Joho; MJ034588 -21DE6 E0101; Hanyo-Denshi; KS094130 -21DE6 E0101; Moji_Joho; MJ034589 -21DEB E0100; Hanyo-Denshi; KS092110 -21DEB E0101; Hanyo-Denshi; TK01024960 -21E33 E0100; Adobe-Japan1; CID+17562 -21E34 E0100; Adobe-Japan1; CID+16845 -21E62 E0100; Hanyo-Denshi; KS093110 -21E62 E0101; Hanyo-Denshi; TK01025030 -21E99 E0100; Hanyo-Denshi; KS093930 -21E99 E0101; Hanyo-Denshi; TK01025580 -21EAC E0100; Hanyo-Denshi; KS094280 -21EAC E0101; Hanyo-Denshi; TK01025540 -21EDF E0100; Hanyo-Denshi; KS095010 -21EDF E0101; Hanyo-Denshi; TK01025630 -21EE4 E0100; Hanyo-Denshi; KS095090 -21EE4 E0101; Hanyo-Denshi; TK01025760 -21F0E E0100; Hanyo-Denshi; KS095630 -21F0E E0101; Hanyo-Denshi; TK01025880 -21F19 E0100; Moji_Joho; MJ034773 -21F19 E0101; Moji_Joho; MJ034774 -21F1E E0100; Adobe-Japan1; CID+17575 -21F44 E0100; Hanyo-Denshi; KS096350 -21F44 E0101; Hanyo-Denshi; TK01025920 -21F76 E0100; Adobe-Japan1; CID+17582 -21F76 E0101; Hanyo-Denshi; JD0870 -21F76 E0101; Moji_Joho; MJ034827 -21F76 E0102; Hanyo-Denshi; KS096970 -21F76 E0102; Moji_Joho; MJ034826 -21FD6 E0100; Hanyo-Denshi; KS097840 -21FD6 E0100; Moji_Joho; MJ034886 -21FD6 E0101; Hanyo-Denshi; KS097880 -21FD6 E0101; Moji_Joho; MJ034887 -21FE7 E0100; Hanyo-Denshi; KS098030 -21FE7 E0100; Moji_Joho; MJ034900 -21FE7 E0101; Hanyo-Denshi; KS098040 -21FE7 E0101; Moji_Joho; MJ034901 -21FE9 E0100; Hanyo-Denshi; KS098060 -21FE9 E0100; Moji_Joho; MJ034903 -21FE9 E0101; Hanyo-Denshi; KS098190 -21FE9 E0101; Moji_Joho; MJ034904 -21FEB E0100; Hanyo-Denshi; KS098130 -21FEB E0101; Hanyo-Denshi; KS098200 -21FEE E0100; Hanyo-Denshi; KS035620 -21FEE E0100; Moji_Joho; MJ034910 -21FEE E0101; Hanyo-Denshi; KS098230 -21FEE E0101; Moji_Joho; MJ034912 -21FFA E0100; Adobe-Japan1; CID+17585 -22029 E0100; Hanyo-Denshi; KS098950 -22029 E0100; Moji_Joho; MJ034953 -22029 E0101; Hanyo-Denshi; KS098980 -22029 E0101; Moji_Joho; MJ034954 -22034 E0100; Hanyo-Denshi; KS033640 -22034 E0100; Moji_Joho; MJ007920 -22034 E0101; Hanyo-Denshi; KS099070 -22034 E0101; Moji_Joho; MJ034957 -22037 E0100; Hanyo-Denshi; IB1758 -22037 E0100; Moji_Joho; MJ034961 -22037 E0101; Hanyo-Denshi; JTB096 -22037 E0101; Moji_Joho; MJ034960 -2217B E0100; Adobe-Japan1; CID+17599 -2219F E0100; Hanyo-Denshi; KS103940 -2219F E0100; Moji_Joho; MJ035226 -2219F E0101; Hanyo-Denshi; KS245440 -2219F E0101; Moji_Joho; MJ035227 -221D4 E0100; Hanyo-Denshi; KS085630 -221D4 E0101; Hanyo-Denshi; TK01023850 -22214 E0100; Hanyo-Denshi; TK01027820 -22214 E0101; Hanyo-Denshi; TK01027840 -22218 E0100; Adobe-Japan1; CID+19105 -22218 E0101; Hanyo-Denshi; JD9451 -22218 E0102; Hanyo-Denshi; TK01027760 -22218 E0103; Hanyo-Denshi; TK01027930 -22218 E0104; Hanyo-Denshi; TK01101190 -2221C E0100; Hanyo-Denshi; KS105490 -2221C E0101; Hanyo-Denshi; TK01027860 -2228A E0100; Hanyo-Denshi; IB0675 -2228A E0101; Hanyo-Denshi; TK01028150 -222AC E0100; Hanyo-Denshi; TK01028290 -222AC E0101; Hanyo-Denshi; TK01028350 -222E3 E0100; Hanyo-Denshi; KS107760 -222E3 E0101; Hanyo-Denshi; TK01028510 -222EE E0100; Hanyo-Denshi; KS107790 -222EE E0101; Hanyo-Denshi; TK01028650 -222F1 E0100; Hanyo-Denshi; KS107840 -222F1 E0100; Moji_Joho; MJ035446 -222F1 E0101; Hanyo-Denshi; KS220030 -222F1 E0101; Moji_Joho; MJ058011 -222FF E0100; Hanyo-Denshi; KS107940 -222FF E0100; Moji_Joho; MJ035453 -222FF E0101; Hanyo-Denshi; KS549030 -222FF E0101; Moji_Joho; MJ035454 -2231B E0100; Hanyo-Denshi; KS108160 -2231B E0100; Moji_Joho; MJ035470 -2231B E0101; Hanyo-Denshi; KS108270 -2231B E0101; Moji_Joho; MJ035471 -2231E E0100; Adobe-Japan1; CID+17605 -22325 E0100; Hanyo-Denshi; TK01028810 -22325 E0101; Hanyo-Denshi; TK01028840 -22331 E0100; Hanyo-Denshi; KS108490 -22331 E0100; Moji_Joho; MJ035483 -22331 E0101; Hanyo-Denshi; KS108500 -22331 E0101; Moji_Joho; MJ035484 -22331 E0102; Hanyo-Denshi; KS108620 -22331 E0102; Moji_Joho; MJ035485 -22341 E0100; Hanyo-Denshi; KS243920 -22341 E0100; Moji_Joho; MJ035497 -22341 E0101; Hanyo-Denshi; KS244410 -22341 E0101; Moji_Joho; MJ035498 -223A6 E0100; Hanyo-Denshi; KS109810 -223A6 E0101; Hanyo-Denshi; TK01007160 -223AD E0100; Adobe-Japan1; CID+17608 -223E4 E0100; Hanyo-Denshi; KS110620 -223E4 E0101; Hanyo-Denshi; TK01029620 -22427 E0100; Hanyo-Denshi; KS111590 -22427 E0101; Hanyo-Denshi; TK01029900 -22437 E0100; Hanyo-Denshi; KS111710 -22437 E0101; Hanyo-Denshi; TK01029930 -22440 E0100; Hanyo-Denshi; KS111830 -22440 E0101; Hanyo-Denshi; TK01030000 -224ED E0100; Hanyo-Denshi; JTB132 -224ED E0100; Moji_Joho; MJ035829 -224ED E0101; Hanyo-Denshi; KS114510 -224ED E0101; Moji_Joho; MJ035828 -22501 E0100; Hanyo-Denshi; KS114530 -22501 E0101; Hanyo-Denshi; TK01030940 -2254D E0100; Hanyo-Denshi; KS115170 -2254D E0101; Hanyo-Denshi; TK01031060 -22552 E0100; Hanyo-Denshi; KS115410 -22552 E0100; Moji_Joho; MJ035901 -22552 E0101; Hanyo-Denshi; KS115650 -22552 E0101; Moji_Joho; MJ035902 -2258F E0100; Hanyo-Denshi; KS116020 -2258F E0101; Hanyo-Denshi; TK01031330 -225F2 E0100; Hanyo-Denshi; KS117240 -225F2 E0101; Hanyo-Denshi; TK01031480 -22607 E0100; Hanyo-Denshi; KS118390 -22607 E0101; Hanyo-Denshi; TK01031610 -22609 E0100; Adobe-Japan1; CID+15443 -2264A E0100; Hanyo-Denshi; KS119270 -2264A E0101; Hanyo-Denshi; TK01031710 -2264E E0100; Hanyo-Denshi; KS119710 -2264E E0101; Hanyo-Denshi; TK01031620 -22672 E0100; Hanyo-Denshi; KS119850 -22672 E0101; Hanyo-Denshi; TK01031590 -22683 E0100; Hanyo-Denshi; KS120240 -22683 E0101; Hanyo-Denshi; TK01031910 -226D4 E0100; Hanyo-Denshi; KS121300 -226D4 E0100; Moji_Joho; MJ036142 -226D4 E0101; Hanyo-Denshi; KS122800 -226D4 E0101; Moji_Joho; MJ036143 -226F3 E0100; Adobe-Japan1; CID+17632 -226F3 E0101; Hanyo-Denshi; JD1248 -226F3 E0102; Hanyo-Denshi; TK01032130 -2276C E0100; Hanyo-Denshi; KS123570 -2276C E0101; Hanyo-Denshi; TK01032620 -22790 E0100; Hanyo-Denshi; KS123810 -22790 E0101; Hanyo-Denshi; TK01032980 -227A1 E0100; Hanyo-Denshi; KS124180 -227A1 E0101; Hanyo-Denshi; TK01032950 -227FA E0100; Hanyo-Denshi; KS125380 -227FA E0100; Moji_Joho; MJ036311 -227FA E0101; Hanyo-Denshi; KS125620 -227FA E0101; Moji_Joho; MJ057520 -22835 E0100; Hanyo-Denshi; JTB1A4 -22835 E0100; Moji_Joho; MJ036335 -22835 E0101; Hanyo-Denshi; KS126180 -22835 E0101; Moji_Joho; MJ036334 -22841 E0100; Hanyo-Denshi; KS126460 -22841 E0101; Hanyo-Denshi; TK01033390 -22843 E0100; Hanyo-Denshi; KS127150 -22843 E0100; Moji_Joho; MJ036350 -22843 E0101; Hanyo-Denshi; KS127800 -22843 E0101; Moji_Joho; MJ036351 -2285A E0100; Moji_Joho; MJ036372 -2285A E0101; Moji_Joho; MJ036373 -2285B E0100; Adobe-Japan1; CID+17647 -22886 E0100; Hanyo-Denshi; TK01033370 -22886 E0101; Hanyo-Denshi; TK01033690 -22894 E0100; Hanyo-Denshi; KS127380 -22894 E0100; Moji_Joho; MJ036395 -22894 E0101; Hanyo-Denshi; KS127820 -22894 E0101; Moji_Joho; MJ036396 -228AB E0100; Adobe-Japan1; CID+17653 -22904 E0100; Hanyo-Denshi; KS128650 -22904 E0101; Hanyo-Denshi; TK01033890 -22904 E0102; Hanyo-Denshi; TK01034180 -22926 E0100; Hanyo-Denshi; KS128960 -22926 E0100; Moji_Joho; MJ036476 -22926 E0101; Hanyo-Denshi; KS129170 -22926 E0101; Moji_Joho; MJ036477 -2295A E0100; Hanyo-Denshi; IB1907 -2295A E0101; Hanyo-Denshi; TK01034390 -2295A E0102; Hanyo-Denshi; TK01034470 -22985 E0100; Hanyo-Denshi; KS129890 -22985 E0100; Moji_Joho; MJ036532 -22985 E0101; Hanyo-Denshi; KS129900 -22985 E0101; Moji_Joho; MJ036533 -2298F E0100; Adobe-Japan1; CID+17657 -229CC E0100; Hanyo-Denshi; KS130840 -229CC E0101; Hanyo-Denshi; TK01034840 -22A25 E0100; Hanyo-Denshi; IB1910 -22A25 E0101; Hanyo-Denshi; TK01034950 -22A37 E0100; Hanyo-Denshi; KS132120 -22A37 E0101; Hanyo-Denshi; TK01034980 -22A38 E0100; Hanyo-Denshi; KS132140 -22A38 E0101; Hanyo-Denshi; TK01034970 -22AB8 E0100; Adobe-Japan1; CID+17667 -22B46 E0100; Adobe-Japan1; CID+17680 -22B4F E0100; Adobe-Japan1; CID+17671 -22B50 E0100; Adobe-Japan1; CID+17672 -22BA6 E0100; Adobe-Japan1; CID+17683 -22BF1 E0100; Hanyo-Denshi; KS138800 -22BF1 E0100; Moji_Joho; MJ036872 -22BF1 E0101; Hanyo-Denshi; KS139680 -22BF1 E0101; Moji_Joho; MJ057562 -22C1D E0100; Adobe-Japan1; CID+17682 -22C1D E0101; Hanyo-Denshi; JD1320 -22C1D E0101; Moji_Joho; MJ036909 -22C1D E0102; Hanyo-Denshi; KS139610 -22C1D E0102; Moji_Joho; MJ036910 -22C24 E0100; Adobe-Japan1; CID+17686 -22C72 E0100; Moji_Joho; MJ036938 -22C72 E0101; Moji_Joho; MJ057566 -22D23 E0100; Hanyo-Denshi; KS142450 -22D23 E0101; Hanyo-Denshi; TK01036020 -22D3C E0100; Hanyo-Denshi; KS143120 -22D3C E0100; Moji_Joho; MJ037021 -22D3C E0101; Hanyo-Denshi; KS143380 -22D3C E0101; Moji_Joho; MJ037022 -22D57 E0100; Hanyo-Denshi; KS143270 -22D57 E0101; Hanyo-Denshi; TK01036010 -22D8A E0100; Hanyo-Denshi; KS143360 -22D8A E0100; Moji_Joho; MJ057573 -22D8A E0101; Hanyo-Denshi; KS143770 -22D8A E0101; Moji_Joho; MJ037047 -22DE1 E0100; Adobe-Japan1; CID+17710 -22E09 E0100; Hanyo-Denshi; KS145270 -22E09 E0100; Moji_Joho; MJ037116 -22E09 E0101; Hanyo-Denshi; KS145330 -22E09 E0101; Moji_Joho; MJ057578 -22E2D E0100; Hanyo-Denshi; KS145680 -22E2D E0100; Moji_Joho; MJ037127 -22E2D E0101; Hanyo-Denshi; KS145920 -22E2D E0101; Moji_Joho; MJ037128 -22E42 E0100; Adobe-Japan1; CID+20124 -22EE0 E0100; Hanyo-Denshi; KS149980 -22EE0 E0101; Hanyo-Denshi; TK01036460 -22EEC E0100; Hanyo-Denshi; KS146710 -22EEC E0100; Moji_Joho; MJ037219 -22EEC E0101; Hanyo-Denshi; KS146820 -22EEC E0101; Moji_Joho; MJ037220 -22F22 E0100; Hanyo-Denshi; KS147790 -22F22 E0100; Moji_Joho; MJ037262 -22F22 E0101; Hanyo-Denshi; KS148270 -22F22 E0101; Moji_Joho; MJ057595 -22F3B E0100; Hanyo-Denshi; KS147960 -22F3B E0101; Hanyo-Denshi; TK01036700 -22FCC E0100; Hanyo-Denshi; KS149690 -22FCC E0100; Moji_Joho; MJ037369 -22FCC E0101; Hanyo-Denshi; KS149920 -22FCC E0101; Moji_Joho; MJ057615 -22FD8 E0100; Hanyo-Denshi; KS149780 -22FD8 E0100; Moji_Joho; MJ057612 -22FD8 E0101; Hanyo-Denshi; KS149960 -22FD8 E0101; Moji_Joho; MJ037377 -22FD9 E0100; Moji_Joho; MJ037378 -22FD9 E0101; Moji_Joho; MJ037379 -22FE0 E0100; Hanyo-Denshi; KS150050 -22FE0 E0100; Moji_Joho; MJ037384 -22FE0 E0101; Hanyo-Denshi; KS150450 -22FE0 E0101; Moji_Joho; MJ057618 -22FEB E0100; Adobe-Japan1; CID+20130 -2305D E0100; Moji_Joho; MJ037452 -2305D E0101; Moji_Joho; MJ037453 -230B0 E0100; Hanyo-Denshi; KS152160 -230B0 E0101; Hanyo-Denshi; KS152230 -230D4 E0100; Hanyo-Denshi; KS152600 -230D4 E0100; Moji_Joho; MJ037540 -230D4 E0101; Hanyo-Denshi; KS152610 -230D4 E0101; Moji_Joho; MJ037541 -230E0 E0100; Hanyo-Denshi; JTB270S -230E0 E0101; Hanyo-Denshi; TK01037870 -2311E E0100; Hanyo-Denshi; KS153910 -2311E E0100; Moji_Joho; MJ037586 -2311E E0101; Hanyo-Denshi; KS153980 -2311E E0101; Moji_Joho; MJ037587 -23122 E0100; Hanyo-Denshi; KS153960 -23122 E0100; Moji_Joho; MJ037591 -23122 E0101; Hanyo-Denshi; KS153990 -23122 E0101; Moji_Joho; MJ037592 -23196 E0100; Hanyo-Denshi; KS156480 -23196 E0101; Hanyo-Denshi; TK01039150 -231B2 E0100; Hanyo-Denshi; KS156830 -231B2 E0101; Hanyo-Denshi; TK01041120 -231B3 E0100; Hanyo-Denshi; KS156840 -231B3 E0101; Hanyo-Denshi; TK01039370 -231B6 E0100; Adobe-Japan1; CID+17744 -231B6 E0101; Hanyo-Denshi; JD1404 -231B6 E0102; Hanyo-Denshi; TK01039360 -231BB E0100; Hanyo-Denshi; KS157150 -231BB E0101; Hanyo-Denshi; TK01039550 -231C3 E0100; Adobe-Japan1; CID+17742 -231C3 E0101; Hanyo-Denshi; JD1393 -231C3 E0102; Hanyo-Denshi; TK01039190 -231C4 E0100; Adobe-Japan1; CID+16888 -231F5 E0100; Adobe-Japan1; CID+17743 -231F8 E0100; Hanyo-Denshi; TK01039350 -231F8 E0101; Hanyo-Denshi; TK01039540 -23211 E0100; Hanyo-Denshi; JTB2AE -23211 E0101; Hanyo-Denshi; TK01040110 -23211 E0102; Hanyo-Denshi; TK01041170 -2325E E0100; Hanyo-Denshi; TK01040270 -2325E E0101; Hanyo-Denshi; TK01099590 -232B8 E0100; Hanyo-Denshi; KS112530 -232B8 E0100; Moji_Joho; MJ037805 -232B8 E0101; Hanyo-Denshi; KS112540 -232B8 E0101; Moji_Joho; MJ037806 -232DE E0100; Hanyo-Denshi; KS160340 -232DE E0101; Hanyo-Denshi; TK01040770 -2335F E0100; Hanyo-Denshi; KS161110 -2335F E0100; Moji_Joho; MJ037876 -2335F E0101; Hanyo-Denshi; KS326540 -2335F E0101; Moji_Joho; MJ037877 -2336E E0100; Moji_Joho; MJ037888 -2336E E0101; Moji_Joho; MJ037889 -23372 E0100; Adobe-Japan1; CID+17761 -233B2 E0100; Hanyo-Denshi; KS162280 -233B2 E0101; Hanyo-Denshi; TK01042750 -233BE E0100; Hanyo-Denshi; KS162600 -233BE E0101; Hanyo-Denshi; TK01008250 -233C3 E0100; Hanyo-Denshi; KS162980 -233C3 E0101; Hanyo-Denshi; TK01042860 -233CC E0100; Adobe-Japan1; CID+14140 -233D0 E0100; Adobe-Japan1; CID+17768 -233D2 E0100; Adobe-Japan1; CID+17764 -233D2 E0101; Hanyo-Denshi; JD1429 -233D2 E0101; Moji_Joho; MJ037939 -233D2 E0102; Hanyo-Denshi; KS163070 -233D2 E0102; Moji_Joho; MJ037938 -233D3 E0100; Adobe-Japan1; CID+17763 -233D5 E0100; Adobe-Japan1; CID+17770 -233DA E0100; Adobe-Japan1; CID+17772 -233DF E0100; Adobe-Japan1; CID+17774 -233E0 E0100; Moji_Joho; MJ037953 -233E0 E0101; Moji_Joho; MJ037954 -233E4 E0100; Adobe-Japan1; CID+17769 -233FE E0100; Adobe-Japan1; CID+15422 -23408 E0100; Hanyo-Denshi; KS165280 -23408 E0101; Hanyo-Denshi; TK01043350 -23440 E0100; Hanyo-Denshi; KS166480 -23440 E0101; Hanyo-Denshi; TK01044380 -2344A E0100; Adobe-Japan1; CID+17782 -2344B E0100; Adobe-Japan1; CID+17784 -23451 E0100; Adobe-Japan1; CID+17783 -23465 E0100; Adobe-Japan1; CID+17788 -2346D E0100; Hanyo-Denshi; KS166610 -2346D E0100; Moji_Joho; MJ038010 -2346D E0101; Hanyo-Denshi; KS166620 -2346D E0101; Moji_Joho; MJ038011 -234AB E0100; Hanyo-Denshi; KS167980 -234AB E0101; Hanyo-Denshi; TK01043770 -234B0 E0100; Hanyo-Denshi; KS168300 -234B0 E0101; Hanyo-Denshi; TK01044340 -234C9 E0100; Hanyo-Denshi; JTB339 -234C9 E0100; Moji_Joho; MJ038053 -234C9 E0101; Hanyo-Denshi; KS168710 -234C9 E0101; Moji_Joho; MJ038052 -234CE E0100; Hanyo-Denshi; KS168940 -234CE E0101; Hanyo-Denshi; TK01044220 -234CE E0102; Hanyo-Denshi; TK01044230 -234D6 E0100; Hanyo-Denshi; KS169200 -234D6 E0101; Hanyo-Denshi; TK01044620 -234D6 E0102; Hanyo-Denshi; TK01044860 -234E4 E0100; Adobe-Japan1; CID+17814 -23531 E0100; Hanyo-Denshi; KS170240 -23531 E0100; Moji_Joho; MJ038099 -23531 E0101; Hanyo-Denshi; KS172050 -23531 E0101; Moji_Joho; MJ057773 -2355A E0100; Adobe-Japan1; CID+17815 -2355A E0101; Hanyo-Denshi; JD1488 -2355A E0101; Moji_Joho; MJ038132 -2355A E0102; Hanyo-Denshi; KS171990 -2355A E0102; Moji_Joho; MJ038133 -23594 E0100; Adobe-Japan1; CID+17827 -235AD E0100; Hanyo-Denshi; KS172250 -235AD E0101; Hanyo-Denshi; TK01046210 -235C4 E0100; Adobe-Japan1; CID+16905 -235C4 E0101; Adobe-Japan1; CID+15428 -235C4 E0102; Hanyo-Denshi; JC8582 -235C4 E0102; Moji_Joho; MJ038173 -235C4 E0103; Hanyo-Denshi; KS173590 -235C4 E0103; Moji_Joho; MJ038174 -235C4 E0104; Hanyo-Denshi; JTB350 -235C4 E0104; Moji_Joho; MJ038175 -23617 E0100; Hanyo-Denshi; KS173970 -23617 E0101; Hanyo-Denshi; TK01045390 -23626 E0100; Hanyo-Denshi; KS174550 -23626 E0100; Moji_Joho; MJ038207 -23626 E0101; Hanyo-Denshi; KS175490 -23626 E0101; Moji_Joho; MJ038208 -23638 E0100; Adobe-Japan1; CID+17843 -23638 E0101; Hanyo-Denshi; JD1534 -23638 E0101; Moji_Joho; MJ038223 -23638 E0102; Hanyo-Denshi; JTB3A3 -23638 E0102; Moji_Joho; MJ038222 -23639 E0100; Adobe-Japan1; CID+17841 -2363A E0100; Adobe-Japan1; CID+15393 -2363A E0101; Adobe-Japan1; CID+13723 -2363A E0102; Adobe-Japan1; CID+13724 -2363A E0103; Hanyo-Denshi; JD1535 -2363A E0104; Hanyo-Denshi; TK01045900 -2363A E0105; Hanyo-Denshi; TK01046270 -2363A E0106; Hanyo-Denshi; TK01046420 -23647 E0100; Adobe-Japan1; CID+17842 -236A3 E0100; Hanyo-Denshi; KS175460 -236A3 E0100; Moji_Joho; MJ057817 -236A3 E0101; Hanyo-Denshi; KS176670 -236A3 E0101; Moji_Joho; MJ038279 -236AD E0100; Hanyo-Denshi; KS176830 -236AD E0101; Hanyo-Denshi; TK01046260 -2370C E0100; Adobe-Japan1; CID+17863 -2371C E0100; Adobe-Japan1; CID+17854 -2371C E0101; Hanyo-Denshi; JD1546 -2371C E0101; Moji_Joho; MJ038318 -2371C E0102; Hanyo-Denshi; KS178130 -2371C E0102; Moji_Joho; MJ038319 -2371C E0103; Hanyo-Denshi; TK01046490 -23726 E0100; Hanyo-Denshi; KS178000 -23726 E0101; Hanyo-Denshi; TK01046510 -2373F E0100; Adobe-Japan1; CID+16914 -2373F E0101; Hanyo-Denshi; JC8609 -2373F E0101; Moji_Joho; MJ038332 -2373F E0102; Hanyo-Denshi; JTB3AC -2373F E0102; Moji_Joho; MJ038333 -2374B E0100; Hanyo-Denshi; IB0318 -2374B E0100; Moji_Joho; MJ038345 -2374B E0101; Hanyo-Denshi; IB0722 -2374B E0101; Moji_Joho; MJ038344 -23763 E0100; Adobe-Japan1; CID+16916 -23763 E0101; Hanyo-Denshi; JC8618 -23763 E0102; Hanyo-Denshi; TK01046710 -23764 E0100; Adobe-Japan1; CID+17867 -23764 E0101; Hanyo-Denshi; JD1565 -23764 E0101; Moji_Joho; MJ038365 -23764 E0102; Hanyo-Denshi; KS179770 -23764 E0102; Moji_Joho; MJ057856 -23764 E0103; Hanyo-Denshi; TK01047010 -23780 E0100; Hanyo-Denshi; JTB3B2 -23780 E0100; Moji_Joho; MJ057852 -23780 E0101; Hanyo-Denshi; JTB3B8 -23780 E0101; Moji_Joho; MJ038377 -23780 E0102; Hanyo-Denshi; TK01046760 -237E7 E0100; Adobe-Japan1; CID+17875 -237E7 E0101; Hanyo-Denshi; JD1574 -237E7 E0101; Moji_Joho; MJ038420 -237E7 E0102; Hanyo-Denshi; JTB3C0 -237E7 E0102; Moji_Joho; MJ038419 -237F1 E0100; Adobe-Japan1; CID+20152 -237F3 E0100; Hanyo-Denshi; IB0321 -237F3 E0100; Moji_Joho; MJ038426 -237F3 E0101; Hanyo-Denshi; IB0725 -237F3 E0101; Moji_Joho; MJ038425 -237FF E0100; Adobe-Japan1; CID+17874 -23824 E0100; Adobe-Japan1; CID+17880 -2383D E0100; Adobe-Japan1; CID+17885 -2383D E0101; Adobe-Japan1; CID+20262 -238A7 E0100; Hanyo-Denshi; KS182260 -238A7 E0100; Moji_Joho; MJ038532 -238A7 E0101; Hanyo-Denshi; KS183360 -238A7 E0101; Moji_Joho; MJ038533 -238AE E0100; Hanyo-Denshi; KS182360 -238AE E0101; Hanyo-Denshi; TK01047340 -238BE E0100; Hanyo-Denshi; TK01047330 -238BE E0101; Hanyo-Denshi; TK01065010 -23A63 E0100; Hanyo-Denshi; KS187940 -23A63 E0100; Moji_Joho; MJ038875 -23A63 E0101; Hanyo-Denshi; KS188010 -23A63 E0101; Moji_Joho; MJ038876 -23A74 E0100; Hanyo-Denshi; KS188120 -23A74 E0100; Moji_Joho; MJ057912 -23A74 E0101; Hanyo-Denshi; KS188180 -23A74 E0101; Moji_Joho; MJ038889 -23A8D E0100; Hanyo-Denshi; KS188610 -23A8D E0100; Moji_Joho; MJ038908 -23A8D E0101; Hanyo-Denshi; KS188810 -23A8D E0101; Moji_Joho; MJ038909 -23A98 E0100; Adobe-Japan1; CID+17897 -23AFA E0100; Hanyo-Denshi; KS189750 -23AFA E0101; Hanyo-Denshi; TK01048070 -23BAC E0100; Hanyo-Denshi; KS191200 -23BAC E0100; Moji_Joho; MJ039067 -23BAC E0101; Hanyo-Denshi; KS191390 -23BAC E0101; Moji_Joho; MJ057931 -23BAF E0100; Hanyo-Denshi; KS191280 -23BAF E0101; Hanyo-Denshi; KS191400 -23C47 E0100; Hanyo-Denshi; IB2190 -23C47 E0101; Hanyo-Denshi; TK01048240 -23C75 E0100; Hanyo-Denshi; KS193460 -23C75 E0100; Moji_Joho; MJ039189 -23C75 E0101; Hanyo-Denshi; KS193880 -23C75 E0101; Moji_Joho; MJ057939 -23C75 E0102; Hanyo-Denshi; KS193890 -23C75 E0102; Moji_Joho; MJ039190 -23C7F E0100; Adobe-Japan1; CID+17910 -23CA8 E0100; Hanyo-Denshi; JTB413 -23CA8 E0100; Moji_Joho; MJ039217 -23CA8 E0101; Hanyo-Denshi; JTB41FS -23CA8 E0101; Moji_Joho; MJ039218 -23CBE E0100; Adobe-Japan1; CID+14293 -23CEE E0100; Hanyo-Denshi; KS196790 -23CEE E0101; Hanyo-Denshi; TK01049530 -23CF1 E0100; Hanyo-Denshi; KS196820 -23CF1 E0101; Hanyo-Denshi; TK01048890 -23CFE E0100; Adobe-Japan1; CID+13904 -23CFE E0101; Hanyo-Denshi; JC8664 -23CFE E0101; Moji_Joho; MJ039272 -23CFE E0102; Hanyo-Denshi; JTB429 -23CFE E0102; Moji_Joho; MJ059775 -23CFE E0103; Hanyo-Denshi; JTB42A -23CFE E0103; Moji_Joho; MJ059776 -23D00 E0100; Adobe-Japan1; CID+17925 -23D0E E0100; Adobe-Japan1; CID+18394 -23D0E E0101; Hanyo-Denshi; JD8485 -23D0E E0102; Hanyo-Denshi; TK01050220 -23D0E E0103; Hanyo-Denshi; TK01073370 -23D34 E0100; Hanyo-Denshi; KS198430 -23D34 E0101; Hanyo-Denshi; TK01049220 -23D34 E0102; Hanyo-Denshi; TK01049690 -23D40 E0100; Adobe-Japan1; CID+17942 -23D7D E0100; Hanyo-Denshi; KS198660 -23D7D E0100; Moji_Joho; MJ039336 -23D7D E0101; Hanyo-Denshi; KS200300 -23D7D E0101; Moji_Joho; MJ057954 -23DBA E0100; Hanyo-Denshi; TK01049750 -23DBA E0101; Hanyo-Denshi; TK01050200 -23DD3 E0100; Adobe-Japan1; CID+17945 -23DD3 E0101; Hanyo-Denshi; JD7864 -23DD3 E0102; Hanyo-Denshi; TK01049600 -23DD3 E0103; Hanyo-Denshi; TK01050210 -23DF9 E0100; Adobe-Japan1; CID+17944 -23DF9 E0101; Hanyo-Denshi; JD7863 -23DF9 E0101; Moji_Joho; MJ039398 -23DF9 E0102; Hanyo-Denshi; JTB451S -23DF9 E0102; Moji_Joho; MJ039399 -23DF9 E0103; Hanyo-Denshi; KS202180 -23DFA E0100; Adobe-Japan1; CID+17943 -23DFA E0101; Hanyo-Denshi; JD7862 -23DFA E0102; Hanyo-Denshi; TK01049840 -23E06 E0100; Hanyo-Denshi; KS201210 -23E06 E0101; Hanyo-Denshi; TK01051650 -23E32 E0100; Hanyo-Denshi; JTB45F -23E32 E0100; Moji_Joho; MJ039441 -23E32 E0101; Hanyo-Denshi; JTB460 -23E32 E0101; Moji_Joho; MJ039442 -23E32 E0102; Hanyo-Denshi; TK01050420 -23E32 E0103; Hanyo-Denshi; TK01050850 -23E32 E0104; Hanyo-Denshi; TK01051480 -23E32 E0105; Hanyo-Denshi; TK01052260 -23E35 E0100; Hanyo-Denshi; TK01049770 -23E35 E0101; Hanyo-Denshi; TK01050400 -23E65 E0100; Hanyo-Denshi; KS202710 -23E65 E0101; Hanyo-Denshi; TK01051260 -23EAC E0100; Hanyo-Denshi; KS203580 -23EAC E0101; Hanyo-Denshi; TK01050430 -23ECC E0100; Hanyo-Denshi; JTB473 -23ECC E0101; Hanyo-Denshi; TK01052240 -23F1B E0100; Hanyo-Denshi; JTB49C -23F1B E0100; Moji_Joho; MJ059815 -23F1B E0101; Hanyo-Denshi; JTB49D -23F1B E0101; Moji_Joho; MJ059816 -23F1B E0102; Hanyo-Denshi; JTB49ES -23F1B E0102; Moji_Joho; MJ059817 -23F1B E0103; Hanyo-Denshi; JTB49F -23F1B E0103; Moji_Joho; MJ059818 -23F1B E0104; Hanyo-Denshi; JTB4A0S -23F1B E0104; Moji_Joho; MJ059819 -23F1B E0105; Hanyo-Denshi; KS205230 -23F1B E0105; Moji_Joho; MJ039540 -23F61 E0100; Hanyo-Denshi; KS206540 -23F61 E0101; Hanyo-Denshi; TK01052870 -23F7E E0100; Adobe-Japan1; CID+17983 -24020 E0100; Hanyo-Denshi; TK01053060 -24020 E0101; Hanyo-Denshi; TK01056040 -2404B E0100; Adobe-Japan1; CID+20168 -24080 E0100; Hanyo-Denshi; KS209800 -24080 E0101; Hanyo-Denshi; TK01053630 -24096 E0100; Adobe-Japan1; CID+17998 -240A3 E0100; Hanyo-Denshi; FT2313 -240A3 E0100; Moji_Joho; MJ039728 -240A3 E0101; Hanyo-Denshi; KS209930 -240A3 E0101; Moji_Joho; MJ039727 -24103 E0100; Adobe-Japan1; CID+18003 -24103 E0101; Hanyo-Denshi; JD7945 -24103 E0102; Hanyo-Denshi; TK01053960 -241C6 E0100; Adobe-Japan1; CID+18015 -241FE E0100; Adobe-Japan1; CID+18018 -24263 E0100; Hanyo-Denshi; KS215370 -24263 E0100; Moji_Joho; MJ039931 -24263 E0101; Hanyo-Denshi; KS216670 -24263 E0101; Moji_Joho; MJ039932 -24285 E0100; Hanyo-Denshi; IB2320 -24285 E0100; Moji_Joho; MJ059861 -24285 E0101; Hanyo-Denshi; JTB51F -24285 E0101; Moji_Joho; MJ039947 -242EE E0100; Adobe-Japan1; CID+14282 -242EE E0101; Adobe-Japan1; CID+14281 -242EE E0102; Hanyo-Denshi; JTB537 -242EE E0103; Hanyo-Denshi; JTB538 -242F1 E0100; Hanyo-Denshi; FT2317S -242F1 E0101; Hanyo-Denshi; TK01055180 -243BC E0100; Adobe-Japan1; CID+18039 -243C1 E0100; Hanyo-Denshi; JTB550 -243C1 E0100; Moji_Joho; MJ040070 -243C1 E0101; Hanyo-Denshi; JTB554 -243C1 E0101; Moji_Joho; MJ059876 -243C1 E0102; Moji_Joho; MJ059875 -243D0 E0100; Adobe-Japan1; CID+7838 -244BC E0100; Hanyo-Denshi; KS221060 -244BC E0101; Hanyo-Denshi; TK01056460 -24510 E0100; Hanyo-Denshi; KS037040 -24510 E0100; Moji_Joho; MJ040229 -24510 E0101; Hanyo-Denshi; KS221680 -24510 E0101; Moji_Joho; MJ040230 -24514 E0100; Hanyo-Denshi; KS221720 -24514 E0100; Moji_Joho; MJ040233 -24514 E0101; Hanyo-Denshi; KS221780 -24514 E0101; Moji_Joho; MJ040234 -24564 E0100; Hanyo-Denshi; KS222390 -24564 E0100; Moji_Joho; MJ058019 -24564 E0101; Hanyo-Denshi; KS222400 -24564 E0101; Moji_Joho; MJ040284 -24568 E0100; Hanyo-Denshi; KS222460 -24568 E0100; Moji_Joho; MJ040288 -24568 E0101; Hanyo-Denshi; KS222480 -24568 E0101; Moji_Joho; MJ058021 -2459B E0100; Hanyo-Denshi; KS222970 -2459B E0101; Hanyo-Denshi; TK01056860 -2459B E0102; Hanyo-Denshi; TK01056870 -2459B E0103; Hanyo-Denshi; TK01056880 -24629 E0100; Adobe-Japan1; CID+18049 -246A5 E0100; Adobe-Japan1; CID+18055 -24735 E0100; Hanyo-Denshi; KS227760 -24735 E0100; Moji_Joho; MJ040623 -24735 E0101; Hanyo-Denshi; KS228970 -24735 E0101; Moji_Joho; MJ040624 -24736 E0100; Hanyo-Denshi; JTB57D -24736 E0101; Hanyo-Denshi; TK01057200 -24772 E0100; Hanyo-Denshi; KS229220 -24772 E0101; Hanyo-Denshi; TK01057340 -247F1 E0100; Adobe-Japan1; CID+16970 -24811 E0100; Hanyo-Denshi; KS231020 -24811 E0101; Hanyo-Denshi; TK01057530 -24813 E0100; Hanyo-Denshi; KS231070 -24813 E0101; Hanyo-Denshi; TK01057520 -24816 E0100; Hanyo-Denshi; IB2365 -24816 E0101; Hanyo-Denshi; TK01057560 -24896 E0100; Adobe-Japan1; CID+18077 -2492F E0100; Hanyo-Denshi; JTB59E -2492F E0101; Hanyo-Denshi; TK01058100 -2497B E0100; Hanyo-Denshi; TK01058230 -2497B E0101; Hanyo-Denshi; TK01058580 -249BA E0100; Hanyo-Denshi; TK01058690 -249BA E0101; Hanyo-Denshi; TK01058710 -249EB E0100; Hanyo-Denshi; IB2422 -249EB E0101; Hanyo-Denshi; KS237100 -24A4D E0100; Adobe-Japan1; CID+18104 -24B56 E0100; Adobe-Japan1; CID+18117 -24B6F E0100; Adobe-Japan1; CID+18119 -24BC5 E0100; Hanyo-Denshi; KS242830 -24BC5 E0101; Hanyo-Denshi; TK01047510 -24C16 E0100; Adobe-Japan1; CID+18124 -24C1E E0100; Hanyo-Denshi; KS031690 -24C1E E0100; Moji_Joho; MJ057093 -24C1E E0101; Hanyo-Denshi; KS031760 -24C1E E0101; Moji_Joho; MJ057095 -24C1E E0102; Hanyo-Denshi; KS031790 -24C1E E0102; Moji_Joho; MJ041343 -24C1E E0103; Hanyo-Denshi; KS243860 -24C1E E0103; Moji_Joho; MJ041344 -24C83 E0100; Hanyo-Denshi; KS245330 -24C83 E0100; Moji_Joho; MJ041408 -24C83 E0101; Hanyo-Denshi; KS245350 -24C83 E0101; Moji_Joho; MJ041409 -24C83 E0102; Hanyo-Denshi; KS245400 -24C83 E0102; Moji_Joho; MJ058099 -24D14 E0100; Adobe-Japan1; CID+13995 -24D38 E0100; Hanyo-Denshi; KS247350 -24D38 E0100; Moji_Joho; MJ041531 -24D38 E0101; Hanyo-Denshi; KS247670 -24D38 E0101; Moji_Joho; MJ017747 -24E04 E0100; Adobe-Japan1; CID+20058 -24E0E E0100; Adobe-Japan1; CID+18158 -24E37 E0100; Adobe-Japan1; CID+18162 -24E6A E0100; Adobe-Japan1; CID+18167 -24E84 E0100; Hanyo-Denshi; KS251930 -24E84 E0100; Moji_Joho; MJ041755 -24E84 E0101; Hanyo-Denshi; KS252430 -24E84 E0101; Moji_Joho; MJ041756 -24E8B E0100; Adobe-Japan1; CID+18170 -24F31 E0100; Hanyo-Denshi; KS253870 -24F31 E0101; Hanyo-Denshi; TK01079120 -24F4C E0100; Hanyo-Denshi; IB2479 -24F4C E0101; Hanyo-Denshi; KS254270 -24FA1 E0100; Hanyo-Denshi; KS255120 -24FA1 E0101; Hanyo-Denshi; TK01061730 -24FB4 E0100; Hanyo-Denshi; KS255330 -24FB4 E0101; Hanyo-Denshi; TK01061870 -24FF2 E0100; Adobe-Japan1; CID+20059 -25044 E0100; Hanyo-Denshi; KS256830 -25044 E0100; Moji_Joho; MJ042063 -25044 E0101; Hanyo-Denshi; KS256840 -25044 E0101; Moji_Joho; MJ042064 -2504A E0100; Adobe-Japan1; CID+18181 -25055 E0100; Adobe-Japan1; CID+18183 -250F2 E0100; Hanyo-Denshi; KS258720 -250F2 E0100; Moji_Joho; MJ042170 -250F2 E0101; Hanyo-Denshi; KS259580 -250F2 E0101; Moji_Joho; MJ042171 -250F3 E0100; Hanyo-Denshi; KS258750 -250F3 E0100; Moji_Joho; MJ042172 -250F3 E0101; Hanyo-Denshi; KS258760 -250F3 E0101; Moji_Joho; MJ042173 -25102 E0100; Hanyo-Denshi; IB0761 -25102 E0100; Moji_Joho; MJ042189 -25102 E0101; Hanyo-Denshi; JTB640 -25102 E0101; Moji_Joho; MJ042187 -25102 E0102; Moji_Joho; MJ042188 -25122 E0100; Adobe-Japan1; CID+18185 -25158 E0100; Hanyo-Denshi; KS260180 -25158 E0101; Hanyo-Denshi; TK01062490 -25185 E0100; Hanyo-Denshi; KS260860 -25185 E0101; Hanyo-Denshi; TK01062650 -25192 E0100; Hanyo-Denshi; JTB654 -25192 E0100; Moji_Joho; MJ042288 -25192 E0101; Hanyo-Denshi; JTC0C5 -25192 E0101; Moji_Joho; MJ042289 -251A9 E0100; Adobe-Japan1; CID+18190 -251CD E0100; Adobe-Japan1; CID+18193 -251E5 E0100; Adobe-Japan1; CID+18192 -2521E E0100; Adobe-Japan1; CID+18195 -25220 E0100; Hanyo-Denshi; KS263330 -25220 E0101; Hanyo-Denshi; TK01040160 -25220 E0102; Hanyo-Denshi; TK01062840 -25220 E0103; Hanyo-Denshi; TK01062850 -25220 E0104; Hanyo-Denshi; TK01063040 -2524C E0100; Adobe-Japan1; CID+18197 -2524C E0101; Hanyo-Denshi; JD8212 -2524C E0101; Moji_Joho; MJ042408 -2524C E0102; Hanyo-Denshi; KS263610 -2524C E0102; Moji_Joho; MJ042409 -2524F E0100; Hanyo-Denshi; KS263630 -2524F E0100; Moji_Joho; MJ042411 -2524F E0101; Hanyo-Denshi; KS264020 -2524F E0101; Moji_Joho; MJ058180 -2542E E0100; Adobe-Japan1; CID+18209 -2548E E0100; Adobe-Japan1; CID+17005 -254C9 E0100; Hanyo-Denshi; JTB675 -254C9 E0101; Hanyo-Denshi; TK01063840 -254D9 E0100; Adobe-Japan1; CID+18217 -2550E E0100; Adobe-Japan1; CID+17009 -255A7 E0100; Adobe-Japan1; CID+18229 -25607 E0100; Hanyo-Denshi; IB0328 -25607 E0100; Moji_Joho; MJ042965 -25607 E0101; Hanyo-Denshi; IB0764 -25607 E0101; Moji_Joho; MJ042964 -25626 E0100; Hanyo-Denshi; IB0316 -25626 E0100; Moji_Joho; MJ042971 -25626 E0101; Hanyo-Denshi; JTB246 -25626 E0101; Moji_Joho; MJ042970 -2562B E0100; Hanyo-Denshi; KS275700 -2562B E0101; Hanyo-Denshi; TK01064620 -2562C E0100; Hanyo-Denshi; IB0330 -2562C E0100; Moji_Joho; MJ042976 -2562C E0101; Hanyo-Denshi; JTB6B5 -2562C E0101; Moji_Joho; MJ042975 -2562E E0100; Hanyo-Denshi; KS275750 -2562E E0101; Hanyo-Denshi; TK01064650 -25630 E0100; Hanyo-Denshi; IB0331 -25630 E0100; Moji_Joho; MJ042981 -25630 E0101; Hanyo-Denshi; JTB6BC -25630 E0101; Moji_Joho; MJ042980 -2563D E0100; Hanyo-Denshi; TK01064710 -2563D E0101; Hanyo-Denshi; TK01064890 -25649 E0100; Hanyo-Denshi; KS275950 -25649 E0101; Hanyo-Denshi; TK01064700 -2564A E0100; Hanyo-Denshi; KS275960 -2564A E0101; Hanyo-Denshi; TK01065000 -2564B E0100; Hanyo-Denshi; KS275890 -2564B E0101; Hanyo-Denshi; TK01064680 -25651 E0100; Hanyo-Denshi; TK01064940 -25651 E0101; Hanyo-Denshi; TK01065090 -2566B E0100; Hanyo-Denshi; KS276380 -2566B E0101; Hanyo-Denshi; TK01065120 -2566E E0100; Hanyo-Denshi; IB0334 -2566E E0100; Moji_Joho; MJ043008 -2566E E0101; Hanyo-Denshi; JTB6DF -2566E E0101; Moji_Joho; MJ043007 -2566E E0102; Moji_Joho; MJ043009 -25677 E0100; Hanyo-Denshi; TK01064930 -25677 E0101; Hanyo-Denshi; TK01065080 -25677 E0102; Hanyo-Denshi; TK01065210 -2567F E0100; Adobe-Japan1; CID+14075 -2567F E0101; Hanyo-Denshi; IB2562 -2567F E0102; Hanyo-Denshi; TK01065370 -25683 E0100; Hanyo-Denshi; JTB6EB -25683 E0101; Hanyo-Denshi; TK01065070 -2568A E0100; Hanyo-Denshi; KS276860 -2568A E0101; Hanyo-Denshi; TK01065360 -25691 E0100; Hanyo-Denshi; TK01065490 -25691 E0101; Hanyo-Denshi; TK01065580 -256A7 E0100; Hanyo-Denshi; KS277140 -256A7 E0101; Hanyo-Denshi; TK01065670 -256B3 E0100; Hanyo-Denshi; TK01065560 -256B3 E0101; Hanyo-Denshi; TK01065790 -256C6 E0100; Hanyo-Denshi; IB0338 -256C6 E0100; Moji_Joho; MJ043036 -256C6 E0101; Hanyo-Denshi; JTB708 -256C6 E0101; Moji_Joho; MJ043035 -256C6 E0102; Moji_Joho; MJ043037 -256D9 E0100; Hanyo-Denshi; IB0339 -256D9 E0100; Moji_Joho; MJ043048 -256D9 E0101; Hanyo-Denshi; JTB70E -256D9 E0101; Moji_Joho; MJ043047 -256DC E0100; Hanyo-Denshi; IB0340 -256DC E0100; Moji_Joho; MJ043052 -256DC E0101; Hanyo-Denshi; JTB70F -256DC E0101; Moji_Joho; MJ043051 -256DF E0100; Hanyo-Denshi; KS277910 -256DF E0101; Hanyo-Denshi; TK01065960 -256F2 E0100; Hanyo-Denshi; IB0341 -256F2 E0100; Moji_Joho; MJ043064 -256F2 E0101; Hanyo-Denshi; JTB716 -256F2 E0101; Moji_Joho; MJ043063 -256F6 E0100; Hanyo-Denshi; IB2576 -256F6 E0101; Hanyo-Denshi; TK01066140 -256F6 E0102; Hanyo-Denshi; TK01066250 -25705 E0100; Hanyo-Denshi; IB0344 -25705 E0100; Moji_Joho; MJ043076 -25705 E0101; Hanyo-Denshi; JTB724 -25705 E0101; Moji_Joho; MJ043075 -25712 E0100; Hanyo-Denshi; IB0345 -25712 E0100; Moji_Joho; MJ043080 -25712 E0101; Hanyo-Denshi; JTB72B -25712 E0101; Moji_Joho; MJ043079 -2571A E0100; Hanyo-Denshi; KS278490 -2571A E0101; Hanyo-Denshi; TK01066330 -2571A E0102; Hanyo-Denshi; TK01066350 -25726 E0100; Hanyo-Denshi; IB0346 -25726 E0100; Moji_Joho; MJ043093 -25726 E0101; Hanyo-Denshi; JTB730 -25726 E0101; Moji_Joho; MJ043092 -25727 E0100; Hanyo-Denshi; KS278600 -25727 E0101; Hanyo-Denshi; TK01066370 -25727 E0102; Hanyo-Denshi; TK01066380 -25755 E0100; Hanyo-Denshi; KS279200 -25755 E0101; Hanyo-Denshi; TK01066560 -25771 E0100; Adobe-Japan1; CID+17018 -25778 E0100; Hanyo-Denshi; KS279700 -25778 E0101; Hanyo-Denshi; TK01049470 -257A9 E0100; Adobe-Japan1; CID+18248 -257A9 E0101; Hanyo-Denshi; JD8285 -257A9 E0101; Moji_Joho; MJ043175 -257A9 E0102; Hanyo-Denshi; KS281380 -257A9 E0102; Moji_Joho; MJ043174 -257A9 E0103; Hanyo-Denshi; TK01067110 -257B4 E0100; Adobe-Japan1; CID+18249 -257B4 E0101; Hanyo-Denshi; JD8286 -257B4 E0101; Moji_Joho; MJ043184 -257B4 E0102; Hanyo-Denshi; KS280640 -257B4 E0102; Moji_Joho; MJ043183 -257CE E0100; Hanyo-Denshi; KS280990 -257CE E0101; Hanyo-Denshi; TK01067240 -25808 E0100; Hanyo-Denshi; KS281810 -25808 E0101; Hanyo-Denshi; TK01067150 -25835 E0100; Hanyo-Denshi; JTB74E -25835 E0100; Moji_Joho; MJ043244 -25835 E0101; Hanyo-Denshi; KS282150 -25835 E0101; Moji_Joho; MJ043243 -25835 E0102; Hanyo-Denshi; TK01067860 -25846 E0100; Hanyo-Denshi; KS282470 -25846 E0101; Hanyo-Denshi; TK01067780 -2585E E0100; Hanyo-Denshi; KS282530 -2585E E0101; Hanyo-Denshi; TK01040730 -25865 E0100; Hanyo-Denshi; KS282680 -25865 E0101; Hanyo-Denshi; TK01068050 -2586A E0100; Hanyo-Denshi; IB2610 -2586A E0101; Hanyo-Denshi; TK01067990 -25874 E0100; Adobe-Japan1; CID+7670 -25875 E0100; Hanyo-Denshi; TK01067570 -25875 E0101; Hanyo-Denshi; TK01067580 -25877 E0100; Hanyo-Denshi; TK01068080 -25877 E0101; Hanyo-Denshi; TK01068120 -25877 E0102; Hanyo-Denshi; TK01068130 -258B8 E0100; Hanyo-Denshi; KS283500 -258B8 E0101; Hanyo-Denshi; TK01068160 -258B8 E0102; Hanyo-Denshi; TK01068180 -258EB E0100; Hanyo-Denshi; KS283990 -258EB E0101; Hanyo-Denshi; TK01068340 -259AD E0100; Hanyo-Denshi; JTB779S -259AD E0101; Hanyo-Denshi; TK01068560 -259AD E0102; Hanyo-Denshi; TK01068620 -259C4 E0100; Adobe-Japan1; CID+17024 -259C4 E0101; Hanyo-Denshi; JC8952 -259C4 E0102; Hanyo-Denshi; TK01022650 -259C4 E0103; Hanyo-Denshi; TK01068650 -259CC E0100; Adobe-Japan1; CID+20112 -259D4 E0100; Adobe-Japan1; CID+18268 -25A2B E0100; Hanyo-Denshi; KS287450 -25A2B E0100; Moji_Joho; MJ043546 -25A2B E0101; Hanyo-Denshi; KS287490 -25A2B E0101; Moji_Joho; MJ043547 -25AA7 E0100; Hanyo-Denshi; KS288760 -25AA7 E0100; Moji_Joho; MJ043613 -25AA7 E0101; Hanyo-Denshi; KS288780 -25AA7 E0101; Moji_Joho; MJ043614 -25AD4 E0100; Hanyo-Denshi; KS419450 -25AD4 E0100; Moji_Joho; MJ043638 -25AD4 E0101; Hanyo-Denshi; KS419500 -25AD4 E0101; Moji_Joho; MJ043639 -25AD7 E0100; Adobe-Japan1; CID+13922 -25AE1 E0100; Hanyo-Denshi; KS289280 -25AE1 E0100; Moji_Joho; MJ043650 -25AE1 E0101; Hanyo-Denshi; KS289340 -25AE1 E0101; Moji_Joho; MJ058258 -25AE3 E0100; Adobe-Japan1; CID+18277 -25AE4 E0100; Adobe-Japan1; CID+18276 -25AF1 E0100; Adobe-Japan1; CID+18278 -25B15 E0100; Hanyo-Denshi; KS290120 -25B15 E0101; Hanyo-Denshi; TK01069400 -25B5F E0100; Hanyo-Denshi; KS291580 -25B5F E0100; Moji_Joho; MJ043731 -25B5F E0101; Hanyo-Denshi; KS291920 -25B5F E0101; Moji_Joho; MJ043732 -25BAB E0100; Hanyo-Denshi; KS292670 -25BAB E0100; Moji_Joho; MJ043779 -25BAB E0101; Hanyo-Denshi; KS292680 -25BAB E0101; Moji_Joho; MJ043780 -25BB2 E0100; Adobe-Japan1; CID+18293 -25C4B E0100; Adobe-Japan1; CID+18302 -25C4B E0101; Hanyo-Denshi; JD8361 -25C4B E0101; Moji_Joho; MJ043882 -25C4B E0102; Hanyo-Denshi; JTB7C0 -25C4B E0102; Moji_Joho; MJ060022 -25C64 E0100; Adobe-Japan1; CID+18303 -25C7A E0100; Hanyo-Denshi; KS295200 -25C7A E0101; Hanyo-Denshi; TK01070410 -25C80 E0100; Hanyo-Denshi; KS295440 -25C80 E0100; Moji_Joho; MJ043899 -25C80 E0101; Hanyo-Denshi; KS298040 -25C80 E0101; Moji_Joho; MJ043900 -25CC9 E0100; Hanyo-Denshi; KS296250 -25CC9 E0101; Hanyo-Denshi; TK01070330 -25CCC E0100; Hanyo-Denshi; KS296320 -25CCC E0101; Hanyo-Denshi; TK01070390 -25CCD E0100; Hanyo-Denshi; KS296330 -25CCD E0101; Hanyo-Denshi; TK01070430 -25CCF E0100; Hanyo-Denshi; KS296360 -25CCF E0101; Hanyo-Denshi; TK01070400 -25DA1 E0100; Adobe-Japan1; CID+17033 -25DA1 E0101; Hanyo-Denshi; JC8978 -25DA1 E0102; Hanyo-Denshi; TK01070500 -25E2E E0100; Adobe-Japan1; CID+18318 -25E56 E0100; Adobe-Japan1; CID+18319 -25E62 E0100; Adobe-Japan1; CID+18322 -25E65 E0100; Adobe-Japan1; CID+18320 -25E9B E0100; Hanyo-Denshi; KS301590 -25E9B E0100; Moji_Joho; MJ058292 -25E9B E0101; Hanyo-Denshi; KS301700 -25E9B E0101; Moji_Joho; MJ044247 -25E9D E0100; Hanyo-Denshi; KS301760 -25E9D E0101; Hanyo-Denshi; TK01070880 -25EB4 E0100; Hanyo-Denshi; TK01070870 -25EB4 E0101; Hanyo-Denshi; TK01070940 -25EC2 E0100; Adobe-Japan1; CID+18327 -25EC2 E0101; Hanyo-Denshi; JD8393 -25EC2 E0102; Hanyo-Denshi; TK01070900 -25ED8 E0100; Adobe-Japan1; CID+18325 -25ED8 E0101; Hanyo-Denshi; JD8391 -25ED8 E0102; Hanyo-Denshi; TK01070970 -25EE7 E0100; Hanyo-Denshi; KS302540 -25EE7 E0101; Hanyo-Denshi; TK01071030 -25EE8 E0100; Adobe-Japan1; CID+18329 -25F23 E0100; Adobe-Japan1; CID+18330 -25F5C E0100; Adobe-Japan1; CID+18332 -25F6C E0100; Hanyo-Denshi; KS303990 -25F6C E0101; Hanyo-Denshi; TK01071140 -25F86 E0100; Hanyo-Denshi; KS304350 -25F86 E0100; Moji_Joho; MJ044396 -25F86 E0101; Hanyo-Denshi; KS304620 -25F86 E0101; Moji_Joho; MJ044397 -25F9E E0100; Hanyo-Denshi; KS304890 -25F9E E0100; Moji_Joho; MJ058300 -25F9E E0101; Hanyo-Denshi; KS305310 -25F9E E0101; Moji_Joho; MJ044414 -25FD4 E0100; Adobe-Japan1; CID+18339 -25FDC E0100; Hanyo-Denshi; KS306000 -25FDC E0101; Hanyo-Denshi; TK01071550 -25FE0 E0100; Adobe-Japan1; CID+18338 -25FE9 E0100; Hanyo-Denshi; KS306270 -25FE9 E0101; Hanyo-Denshi; TK01071860 -25FFB E0100; Adobe-Japan1; CID+18345 -26008 E0100; Hanyo-Denshi; KS306800S -26008 E0101; Hanyo-Denshi; TK01071910 -2600C E0100; Adobe-Japan1; CID+18344 -26017 E0100; Adobe-Japan1; CID+18352 -26060 E0100; Adobe-Japan1; CID+18355 -260A7 E0100; Hanyo-Denshi; TK01091230 -260A7 E0101; Hanyo-Denshi; TK01091250 -260C8 E0100; Moji_Joho; MJ044581 -260C8 E0101; Moji_Joho; MJ044582 -260ED E0100; Adobe-Japan1; CID+18365 -26140 E0100; Hanyo-Denshi; KS311740 -26140 E0101; Hanyo-Denshi; TK01072900 -2617B E0100; Hanyo-Denshi; KS312390 -2617B E0101; Hanyo-Denshi; TK01072940 -261A2 E0100; Hanyo-Denshi; KS312980 -261A2 E0100; Moji_Joho; MJ044706 -261A2 E0101; Hanyo-Denshi; KS313190 -261A2 E0101; Moji_Joho; MJ058330 -261D7 E0100; Hanyo-Denshi; IB0350 -261D7 E0100; Moji_Joho; MJ044739 -261D7 E0101; Hanyo-Denshi; IB0852 -261D7 E0101; Moji_Joho; MJ044738 -261DA E0100; Hanyo-Denshi; KS112680 -261DA E0100; Moji_Joho; MJ044742 -261DA E0101; Hanyo-Denshi; KS313620 -261DA E0101; Moji_Joho; MJ044743 -26222 E0100; Adobe-Japan1; CID+13691 -26222 E0101; Hanyo-Denshi; KS184650 -26222 E0101; Moji_Joho; MJ057891 -26222 E0102; Hanyo-Denshi; KS314180 -26222 E0102; Moji_Joho; MJ044772 -26222 E0103; Hanyo-Denshi; KS314190 -26222 E0103; Moji_Joho; MJ058334 -26222 E0104; Hanyo-Denshi; TK01073060 -26228 E0100; Hanyo-Denshi; KS314270 -26228 E0100; Moji_Joho; MJ044778 -26228 E0101; Hanyo-Denshi; KS314490 -26228 E0101; Moji_Joho; MJ044779 -26247 E0100; Hanyo-Denshi; KS314720 -26247 E0100; Moji_Joho; MJ044801 -26247 E0101; Hanyo-Denshi; KS314830 -26247 E0101; Moji_Joho; MJ044802 -2626A E0100; Adobe-Japan1; CID+14189 -26270 E0100; Adobe-Japan1; CID+18385 -26270 E0101; Adobe-Japan1; CID+14190 -26273 E0100; Hanyo-Denshi; KS315220 -26273 E0100; Moji_Joho; MJ044829 -26273 E0101; Hanyo-Denshi; KS315250 -26273 E0101; Moji_Joho; MJ044830 -26286 E0100; Adobe-Japan1; CID+18386 -262D9 E0100; Hanyo-Denshi; KS316300 -262D9 E0100; Moji_Joho; MJ044887 -262D9 E0101; Hanyo-Denshi; KS316790 -262D9 E0101; Moji_Joho; MJ044888 -2634C E0100; Adobe-Japan1; CID+20311 -263B1 E0100; Hanyo-Denshi; KS318870 -263B1 E0100; Moji_Joho; MJ045039 -263B1 E0101; Hanyo-Denshi; KS318930 -263B1 E0101; Moji_Joho; MJ045040 -263C1 E0100; Hanyo-Denshi; JTC0C9 -263C1 E0100; Moji_Joho; MJ045052 -263C1 E0101; Hanyo-Denshi; JTC0CA -263C1 E0101; Moji_Joho; MJ045051 -263C1 E0102; Moji_Joho; MJ045050 -26402 E0100; Adobe-Japan1; CID+18398 -26405 E0100; Hanyo-Denshi; KS319810 -26405 E0101; Hanyo-Denshi; TK01073730 -26407 E0100; Hanyo-Denshi; KS319840 -26407 E0100; Moji_Joho; MJ045109 -26407 E0101; Hanyo-Denshi; KS319990S -26407 E0101; Moji_Joho; MJ045110 -26408 E0100; Hanyo-Denshi; JTB88A -26408 E0100; Moji_Joho; MJ045112 -26408 E0101; Hanyo-Denshi; KS319880 -26408 E0101; Moji_Joho; MJ045111 -26408 E0102; Hanyo-Denshi; TK01073790 -26409 E0100; Hanyo-Denshi; KS319910 -26409 E0101; Hanyo-Denshi; TK01073770 -26462 E0100; Hanyo-Denshi; KS321040 -26462 E0100; Moji_Joho; MJ045176 -26462 E0101; Hanyo-Denshi; KS321270 -26462 E0101; Moji_Joho; MJ045177 -26489 E0100; Hanyo-Denshi; TK01007100 -26489 E0101; Hanyo-Denshi; TK01074030 -264B3 E0100; Hanyo-Denshi; KS322190 -264B3 E0100; Moji_Joho; MJ058361 -264B3 E0101; Hanyo-Denshi; KS322200S -264B3 E0101; Moji_Joho; MJ045235 -264EF E0100; Hanyo-Denshi; IB2736 -264EF E0101; Hanyo-Denshi; TK01074310 -26503 E0100; Hanyo-Denshi; KS323240 -26503 E0101; Hanyo-Denshi; TK01074360 -26518 E0100; Hanyo-Denshi; KS323460 -26518 E0100; Moji_Joho; MJ045303 -26518 E0101; Hanyo-Denshi; KS323560 -26518 E0101; Moji_Joho; MJ045304 -26530 E0100; Hanyo-Denshi; KS323780 -26530 E0101; Hanyo-Denshi; TK01074470 -265A2 E0100; Hanyo-Denshi; KS324910 -265A2 E0100; Moji_Joho; MJ045380 -265A2 E0101; Hanyo-Denshi; KS325120 -265A2 E0101; Moji_Joho; MJ045381 -26626 E0100; Hanyo-Denshi; TK01075150 -26626 E0101; Hanyo-Denshi; TK01075160 -26646 E0100; Hanyo-Denshi; KS327090 -26646 E0101; Hanyo-Denshi; TK01041640 -2667E E0100; Adobe-Japan1; CID+18416 -266A8 E0100; Hanyo-Denshi; KS329870 -266A8 E0100; Moji_Joho; MJ045549 -266A8 E0101; Hanyo-Denshi; KS330830 -266A8 E0101; Moji_Joho; MJ045550 -266AF E0100; Hanyo-Denshi; JTB8D4 -266AF E0100; Moji_Joho; MJ045557 -266AF E0101; Hanyo-Denshi; JTB8D5 -266AF E0101; Moji_Joho; MJ045558 -266B0 E0100; Adobe-Japan1; CID+14100 -2671D E0100; Adobe-Japan1; CID+18430 -2676B E0100; Hanyo-Denshi; KS331390 -2676B E0100; Moji_Joho; MJ045672 -2676B E0101; Hanyo-Denshi; KS331850 -2676B E0101; Moji_Joho; MJ045673 -267A7 E0100; Hanyo-Denshi; KS332290 -267A7 E0101; Hanyo-Denshi; TK01042370 -26873 E0100; Moji_Joho; MJ045787 -26873 E0101; Moji_Joho; MJ058403 -2688E E0100; Hanyo-Denshi; KS334770 -2688E E0101; Hanyo-Denshi; TK01042650 -268AA E0100; Hanyo-Denshi; JTB8F4 -268AA E0100; Moji_Joho; MJ045850 -268AA E0101; Hanyo-Denshi; JTB8F5 -268AA E0101; Moji_Joho; MJ045851 -268AB E0100; Hanyo-Denshi; JA5916 -268AB E0100; Moji_Joho; MJ045853 -268AB E0101; Hanyo-Denshi; KS162210 -268AB E0101; Moji_Joho; MJ045854 -268BC E0100; Hanyo-Denshi; KS419230 -268BC E0100; Moji_Joho; MJ045862 -268BC E0101; Hanyo-Denshi; KS419250 -268BC E0101; Moji_Joho; MJ045863 -268DD E0100; Adobe-Japan1; CID+18444 -268EA E0100; Adobe-Japan1; CID+18446 -268FD E0100; Hanyo-Denshi; KS335910 -268FD E0101; Hanyo-Denshi; TK01075420 -2691D E0100; Hanyo-Denshi; KS336220 -2691D E0100; Moji_Joho; MJ045932 -2691D E0101; Hanyo-Denshi; KS336240 -2691D E0101; Moji_Joho; MJ045933 -26951 E0100; Adobe-Japan1; CID+13646 -2695B E0100; Hanyo-Denshi; KS336850 -2695B E0100; Moji_Joho; MJ058415 -2695B E0101; Hanyo-Denshi; KS336870 -2695B E0101; Moji_Joho; MJ045973 -2696F E0100; Adobe-Japan1; CID+18450 -26973 E0100; Hanyo-Denshi; KS337270 -26973 E0100; Moji_Joho; MJ045991 -26973 E0101; Hanyo-Denshi; KS337390 -26973 E0101; Moji_Joho; MJ058418 -26977 E0100; Hanyo-Denshi; KS017680 -26977 E0100; Moji_Joho; MJ045995 -26977 E0101; Hanyo-Denshi; KS337310 -26977 E0101; Moji_Joho; MJ045996 -26999 E0100; Adobe-Japan1; CID+14134 -269DD E0100; Adobe-Japan1; CID+18452 -26A01 E0100; Hanyo-Denshi; KS338790 -26A01 E0101; Hanyo-Denshi; TK01075790 -26A1E E0100; Adobe-Japan1; CID+18455 -26A58 E0100; Adobe-Japan1; CID+18459 -26A8C E0100; Adobe-Japan1; CID+18463 -26AAD E0100; Hanyo-Denshi; IB0353 -26AAD E0100; Moji_Joho; MJ046225 -26AAD E0101; Hanyo-Denshi; IB0859 -26AAD E0101; Moji_Joho; MJ046224 -26AB7 E0100; Adobe-Japan1; CID+18466 -26AF8 E0100; Hanyo-Denshi; KS342150 -26AF8 E0101; Hanyo-Denshi; TK01076300 -26AFF E0100; Adobe-Japan1; CID+17063 -26B0A E0100; Hanyo-Denshi; JTB923 -26B0A E0100; Moji_Joho; MJ021523 -26B0A E0101; Hanyo-Denshi; KS343040 -26B0A E0101; Moji_Joho; MJ046292 -26B14 E0100; Hanyo-Denshi; KS343220 -26B14 E0101; Hanyo-Denshi; TK01076480 -26B14 E0102; Hanyo-Denshi; TK01076490 -26B19 E0100; Hanyo-Denshi; KS343350 -26B19 E0101; Hanyo-Denshi; TK01076460 -26B1E E0100; Hanyo-Denshi; JTB928 -26B1E E0100; Moji_Joho; MJ046308 -26B1E E0101; Hanyo-Denshi; JTB929 -26B1E E0101; Moji_Joho; MJ046309 -26B20 E0100; Hanyo-Denshi; KS108520 -26B20 E0100; Moji_Joho; MJ046312 -26B20 E0101; Hanyo-Denshi; KS108570 -26B20 E0101; Moji_Joho; MJ046313 -26B20 E0102; Hanyo-Denshi; KS343700 -26B20 E0102; Moji_Joho; MJ046314 -26B21 E0100; Hanyo-Denshi; KS343730 -26B21 E0101; Hanyo-Denshi; TK01076570 -26B22 E0100; Hanyo-Denshi; KS343740 -26B22 E0101; Hanyo-Denshi; TK01076450 -26B3A E0100; Hanyo-Denshi; KS344900 -26B3A E0101; Hanyo-Denshi; TK01076680 -26B73 E0100; Hanyo-Denshi; KS346330 -26B73 E0101; Hanyo-Denshi; TK01077280 -26B74 E0100; Hanyo-Denshi; KS346340 -26B74 E0101; Hanyo-Denshi; TK01077120 -26B75 E0100; Hanyo-Denshi; KS346350 -26B75 E0101; Hanyo-Denshi; TK01077200 -26B8E E0100; Hanyo-Denshi; IB2790 -26B8E E0101; Hanyo-Denshi; KS347160 -26BA0 E0100; Hanyo-Denshi; JTB96B -26BA0 E0100; Moji_Joho; MJ021912 -26BA0 E0101; Hanyo-Denshi; KS347990 -26BA0 E0101; Moji_Joho; MJ058465 -26BD5 E0100; Hanyo-Denshi; KS349060 -26BD5 E0101; Hanyo-Denshi; TK01077930 -26BDC E0100; Hanyo-Denshi; KS349140 -26BDC E0101; Hanyo-Denshi; TK01077860 -26C29 E0100; Adobe-Japan1; CID+17478 -26C29 E0101; Hanyo-Denshi; JD0536 -26C29 E0101; Moji_Joho; MJ046464 -26C29 E0102; Hanyo-Denshi; KS068340 -26C29 E0102; Moji_Joho; MJ057282 -26C29 E0103; Hanyo-Denshi; TK01077580 -26C29 E0104; Hanyo-Denshi; TK01077590 -26C45 E0100; Hanyo-Denshi; KS351190 -26C45 E0101; Hanyo-Denshi; TK01078510 -26C47 E0100; Hanyo-Denshi; KS351210 -26C47 E0101; Hanyo-Denshi; TK01078480 -26C5A E0100; Hanyo-Denshi; KS351760 -26C5A E0101; Hanyo-Denshi; TK01078330 -26C64 E0100; Hanyo-Denshi; KS351820 -26C64 E0100; Moji_Joho; MJ046522 -26C64 E0101; Hanyo-Denshi; KS352170 -26C64 E0101; Moji_Joho; MJ046523 -26C73 E0100; Adobe-Japan1; CID+18506 -26C73 E0101; Hanyo-Denshi; JD8636 -26C73 E0101; Moji_Joho; MJ046537 -26C73 E0102; Hanyo-Denshi; KS351980 -26C73 E0102; Moji_Joho; MJ046536 -26C73 E0103; Hanyo-Denshi; JTB9C2 -26C73 E0103; Moji_Joho; MJ046538 -26C8F E0100; Hanyo-Denshi; TK01078180 -26C8F E0101; Hanyo-Denshi; TK01078220 -26C8F E0102; Hanyo-Denshi; TK01078730 -26C8F E0103; Hanyo-Denshi; TK01079080 -26C9E E0100; Adobe-Japan1; CID+20206 -26CDD E0100; Adobe-Japan1; CID+18515 -26CDD E0101; Hanyo-Denshi; JD8646 -26CDD E0101; Moji_Joho; MJ046585 -26CDD E0102; Hanyo-Denshi; KS354120 -26CDD E0102; Moji_Joho; MJ046586 -26D09 E0100; Hanyo-Denshi; KS354920 -26D09 E0101; Hanyo-Denshi; TK01080290 -26D61 E0100; Hanyo-Denshi; KS356180 -26D61 E0101; Hanyo-Denshi; TK01079470 -26D65 E0100; Hanyo-Denshi; KS356300 -26D65 E0101; Hanyo-Denshi; TK01079480 -26D80 E0100; Hanyo-Denshi; KS356990 -26D80 E0101; Hanyo-Denshi; TK01079450 -26D85 E0100; Hanyo-Denshi; KS357110 -26D85 E0101; Hanyo-Denshi; TK01078930 -26DE5 E0100; Hanyo-Denshi; TK01079680 -26DE5 E0101; Hanyo-Denshi; TK01080100 -26E11 E0100; Hanyo-Denshi; KS358540 -26E11 E0100; Moji_Joho; MJ046772 -26E11 E0101; Hanyo-Denshi; KS359290 -26E11 E0101; Moji_Joho; MJ046773 -26E40 E0100; Adobe-Japan1; CID+17089 -26E40 E0101; Hanyo-Denshi; JC9119 -26E40 E0101; Moji_Joho; MJ046814 -26E40 E0102; Hanyo-Denshi; KS360770 -26E40 E0102; Moji_Joho; MJ046815 -26E40 E0103; Hanyo-Denshi; TK01080330 -26E47 E0100; Hanyo-Denshi; JTBA00 -26E47 E0100; Moji_Joho; MJ046818 -26E47 E0101; Hanyo-Denshi; JTBA2F -26E47 E0101; Moji_Joho; MJ046819 -26E65 E0100; Adobe-Japan1; CID+18528 -26E65 E0101; Hanyo-Denshi; JD8661 -26E65 E0102; Hanyo-Denshi; TK01096110 -26E7E E0100; Hanyo-Denshi; KS360160 -26E7E E0101; Hanyo-Denshi; TK01080180 -26ECA E0100; Hanyo-Denshi; KS362550 -26ECA E0101; Hanyo-Denshi; TK01080500 -26F2C E0100; Hanyo-Denshi; KS363590 -26F2C E0100; Moji_Joho; MJ046950 -26F2C E0101; Hanyo-Denshi; KS364900 -26F2C E0101; Moji_Joho; MJ046951 -26F2F E0100; Hanyo-Denshi; IB0365 -26F2F E0100; Moji_Joho; MJ046955 -26F2F E0101; Hanyo-Denshi; IB0871 -26F2F E0101; Moji_Joho; MJ046954 -26F2F E0102; Moji_Joho; MJ046956 -26F61 E0100; Hanyo-Denshi; KS364660 -26F61 E0101; Hanyo-Denshi; TK01081200 -26F73 E0100; Hanyo-Denshi; KS365130 -26F73 E0101; Hanyo-Denshi; TK01034060 -26F73 E0102; Hanyo-Denshi; TK01080920 -26F8F E0100; Hanyo-Denshi; KS363440 -26F8F E0100; Moji_Joho; MJ047027 -26F8F E0101; Hanyo-Denshi; KS363510 -26F8F E0101; Moji_Joho; MJ047028 -26F94 E0100; Adobe-Japan1; CID+18544 -26F94 E0101; Hanyo-Denshi; JD8685 -26F94 E0101; Moji_Joho; MJ047032 -26F94 E0102; Hanyo-Denshi; KS362740 -26F94 E0102; Moji_Joho; MJ047031 -26FB1 E0100; Hanyo-Denshi; KS365550 -26FB1 E0100; Moji_Joho; MJ047041 -26FB1 E0101; Hanyo-Denshi; KS369670 -26FB1 E0101; Moji_Joho; MJ047042 -26FC1 E0100; Hanyo-Denshi; KS365880 -26FC1 E0101; Hanyo-Denshi; TK01081600 -26FC4 E0100; Hanyo-Denshi; KS365950 -26FC4 E0101; Hanyo-Denshi; TK01081520 -26FC5 E0100; Hanyo-Denshi; KS365970 -26FC5 E0101; Hanyo-Denshi; TK01081550 -26FD4 E0100; Hanyo-Denshi; KS366170 -26FD4 E0100; Moji_Joho; MJ047079 -26FD4 E0101; Hanyo-Denshi; KS369000S -26FD4 E0101; Moji_Joho; MJ047080 -26FF6 E0100; Adobe-Japan1; CID+18554 -26FF6 E0101; Hanyo-Denshi; JD8701 -26FF6 E0102; Hanyo-Denshi; TK01081300 -26FF7 E0100; Adobe-Japan1; CID+18555 -26FF8 E0100; Adobe-Japan1; CID+18553 -2702E E0100; Hanyo-Denshi; KS366970 -2702E E0101; Hanyo-Denshi; TK01081500 -2702F E0100; Hanyo-Denshi; KS366990 -2702F E0101; Hanyo-Denshi; TK01081820 -27037 E0100; Hanyo-Denshi; KS367130 -27037 E0101; Hanyo-Denshi; TK01081860 -27039 E0100; Hanyo-Denshi; IB0371 -27039 E0100; Moji_Joho; MJ047142 -27039 E0101; Hanyo-Denshi; IB0877 -27039 E0101; Moji_Joho; MJ047141 -27088 E0100; Hanyo-Denshi; KS368410 -27088 E0101; Hanyo-Denshi; TK01082110 -270F0 E0100; Hanyo-Denshi; KS369820 -270F0 E0101; Hanyo-Denshi; TK01082380 -270F4 E0100; Adobe-Japan1; CID+17103 -270F4 E0101; Hanyo-Denshi; JC9141 -270F4 E0101; Moji_Joho; MJ047259 -270F4 E0102; Hanyo-Denshi; KS369890 -270F4 E0102; Moji_Joho; MJ047258 -2710D E0100; Adobe-Japan1; CID+18571 -2710D E0101; Hanyo-Denshi; JD8719 -2710D E0101; Moji_Joho; MJ047264 -2710D E0102; Hanyo-Denshi; KS369990 -2710D E0102; Moji_Joho; MJ047265 -27112 E0100; Hanyo-Denshi; KS370090 -27112 E0101; Hanyo-Denshi; TK01082450 -27139 E0100; Adobe-Japan1; CID+18574 -27139 E0101; Hanyo-Denshi; JD8722 -27139 E0101; Moji_Joho; MJ047295 -27139 E0102; Hanyo-Denshi; KS370530 -27139 E0102; Moji_Joho; MJ047296 -27170 E0100; Hanyo-Denshi; KS371110 -27170 E0101; Hanyo-Denshi; TK01082550 -27170 E0102; Hanyo-Denshi; TK01086190 -27171 E0100; Hanyo-Denshi; KS371120 -27171 E0100; Moji_Joho; MJ047340 -27171 E0101; Hanyo-Denshi; KS371180 -27171 E0101; Moji_Joho; MJ058573 -27199 E0100; Hanyo-Denshi; KS371530 -27199 E0101; Hanyo-Denshi; TK01082590 -271D3 E0100; Hanyo-Denshi; IB2875 -271D3 E0101; Hanyo-Denshi; KS372560 -271D3 E0102; Hanyo-Denshi; TK01082990 -271D6 E0100; Hanyo-Denshi; TK01063120 -271D6 E0101; Hanyo-Denshi; TK01083000 -271DC E0100; Hanyo-Denshi; KS372590 -271DC E0101; Hanyo-Denshi; TK01083020 -271FD E0100; Hanyo-Denshi; KS372800 -271FD E0100; Moji_Joho; MJ047433 -271FD E0101; Hanyo-Denshi; KS372850 -271FD E0101; Moji_Joho; MJ047434 -2722A E0100; Hanyo-Denshi; KS373390 -2722A E0100; Moji_Joho; MJ047463 -2722A E0101; Hanyo-Denshi; KS373560 -2722A E0101; Moji_Joho; MJ047464 -2729C E0100; Moji_Joho; MJ047541 -2729C E0101; Moji_Joho; MJ047542 -272B7 E0100; Hanyo-Denshi; KS375880 -272B7 E0100; Moji_Joho; MJ047564 -272B7 E0101; Hanyo-Denshi; KS376020 -272B7 E0101; Moji_Joho; MJ047565 -2730A E0100; Moji_Joho; MJ047613 -2730A E0101; Moji_Joho; MJ047614 -27354 E0100; Hanyo-Denshi; KS378360 -27354 E0101; Hanyo-Denshi; TK01083270 -27357 E0100; Hanyo-Denshi; KS378490 -27357 E0101; Hanyo-Denshi; TK01083190 -27369 E0100; Moji_Joho; MJ047684 -27369 E0101; Moji_Joho; MJ047772 -273CA E0100; Hanyo-Denshi; KS361550 -273CA E0100; Moji_Joho; MJ047757 -273CA E0101; Hanyo-Denshi; KS380420 -273CA E0101; Moji_Joho; MJ047758 -273DA E0100; Adobe-Japan1; CID+18611 -273DB E0100; Adobe-Japan1; CID+18610 -273FE E0100; Adobe-Japan1; CID+18617 -273FE E0101; Hanyo-Denshi; JD8775 -273FE E0101; Moji_Joho; MJ047790 -273FE E0102; Hanyo-Denshi; KS380880 -273FE E0102; Moji_Joho; MJ047791 -27410 E0100; Adobe-Japan1; CID+18620 -27449 E0100; Adobe-Japan1; CID+18624 -27525 E0100; Hanyo-Denshi; IB0374 -27525 E0100; Moji_Joho; MJ047987 -27525 E0101; Hanyo-Denshi; IB0881 -27525 E0101; Moji_Joho; MJ047986 -27602 E0100; Hanyo-Denshi; KS387660 -27602 E0100; Moji_Joho; MJ048161 -27602 E0101; Hanyo-Denshi; KS387680 -27602 E0101; Moji_Joho; MJ048162 -2760E E0100; Hanyo-Denshi; KS387990 -2760E E0100; Moji_Joho; MJ048172 -2760E E0101; Hanyo-Denshi; KS388350 -2760E E0101; Moji_Joho; MJ058686 -27611 E0100; Hanyo-Denshi; KS387930 -27611 E0101; Hanyo-Denshi; TK01083640 -27614 E0100; Adobe-Japan1; CID+18638 -27615 E0100; Adobe-Japan1; CID+18637 -27619 E0100; Hanyo-Denshi; KS388000 -27619 E0100; Moji_Joho; MJ048181 -27619 E0101; Hanyo-Denshi; KS388330 -27619 E0101; Moji_Joho; MJ048182 -27631 E0100; Adobe-Japan1; CID+18640 -27667 E0100; Hanyo-Denshi; KS388290 -27667 E0100; Moji_Joho; MJ048245 -27667 E0101; Hanyo-Denshi; KS389540 -27667 E0101; Moji_Joho; MJ048246 -27684 E0100; Adobe-Japan1; CID+17117 -27689 E0100; Hanyo-Denshi; KS390030 -27689 E0101; Hanyo-Denshi; TK01083840 -27693 E0100; Adobe-Japan1; CID+18645 -276D4 E0100; Hanyo-Denshi; KS390890 -276D4 E0100; Moji_Joho; MJ048321 -276D4 E0101; Hanyo-Denshi; KS392240 -276D4 E0101; Moji_Joho; MJ048322 -27701 E0100; Hanyo-Denshi; KS391980 -27701 E0100; Moji_Joho; MJ048358 -27701 E0101; Hanyo-Denshi; KS392770 -27701 E0101; Moji_Joho; MJ048359 -27705 E0100; Hanyo-Denshi; KS392080S -27705 E0100; Moji_Joho; MJ048363 -27705 E0101; Hanyo-Denshi; KS392270 -27705 E0101; Moji_Joho; MJ058705 -2770E E0100; Adobe-Japan1; CID+18650 -2770F E0100; Moji_Joho; MJ048373 -2770F E0101; Moji_Joho; MJ048374 -27723 E0100; Adobe-Japan1; CID+18652 -27752 E0100; Adobe-Japan1; CID+18656 -27753 E0100; Hanyo-Denshi; KS393290 -27753 E0100; Moji_Joho; MJ048418 -27753 E0101; Hanyo-Denshi; KS393450 -27753 E0101; Moji_Joho; MJ058708 -27771 E0100; Hanyo-Denshi; KS393540 -27771 E0100; Moji_Joho; MJ048434 -27771 E0101; Hanyo-Denshi; KS393840 -27771 E0101; Moji_Joho; MJ058710 -277B8 E0100; Hanyo-Denshi; IB0376 -277B8 E0100; Moji_Joho; MJ048487 -277B8 E0101; Hanyo-Denshi; IB0888 -277B8 E0101; Moji_Joho; MJ048486 -277E4 E0100; Hanyo-Denshi; KS395110 -277E4 E0101; Hanyo-Denshi; KS395130 -277E8 E0100; Hanyo-Denshi; IB2914 -277E8 E0100; Moji_Joho; MJ048523 -277E8 E0101; Hanyo-Denshi; KS395150 -277E8 E0101; Moji_Joho; MJ048522 -27807 E0100; Hanyo-Denshi; KS395590 -27807 E0101; Hanyo-Denshi; TK01006840 -27807 E0102; Hanyo-Denshi; TK01084370 -2783C E0100; Hanyo-Denshi; KS396270 -2783C E0101; Hanyo-Denshi; TK01084490 -2789D E0100; Hanyo-Denshi; KS397500 -2789D E0101; Hanyo-Denshi; TK01084830 -278BD E0100; Hanyo-Denshi; IB2923 -278BD E0101; Hanyo-Denshi; TK01084860 -27966 E0100; Hanyo-Denshi; KS400140 -27966 E0100; Moji_Joho; MJ048809 -27966 E0101; Hanyo-Denshi; KS400280 -27966 E0101; Moji_Joho; MJ048810 -27985 E0100; Adobe-Japan1; CID+18672 -279B4 E0100; Adobe-Japan1; CID+20133 -279DA E0100; Hanyo-Denshi; KS402020 -279DA E0100; Moji_Joho; MJ058741 -279DA E0101; Hanyo-Denshi; KS402710 -279DA E0101; Moji_Joho; MJ048895 -279FC E0100; Hanyo-Denshi; KS403310 -279FC E0101; Hanyo-Denshi; TK01085130 -27A0F E0100; Hanyo-Denshi; KS403870 -27A0F E0101; Hanyo-Denshi; TK01085250 -27A6E E0100; Hanyo-Denshi; KS405270 -27A6E E0100; Moji_Joho; MJ049014 -27A6E E0101; Hanyo-Denshi; KS406060 -27A6E E0101; Moji_Joho; MJ058750 -27A76 E0100; Hanyo-Denshi; KS405610 -27A76 E0101; Hanyo-Denshi; TK01085440 -27A7B E0100; Hanyo-Denshi; KS405750 -27A7B E0100; Moji_Joho; MJ049028 -27A7B E0101; Hanyo-Denshi; KS406140 -27A7B E0101; Moji_Joho; MJ049029 -27A7E E0100; Hanyo-Denshi; KS405780 -27A7E E0101; Hanyo-Denshi; TK01085510 -27A81 E0100; Hanyo-Denshi; KS405810 -27A81 E0101; Hanyo-Denshi; TK01085330 -27A84 E0100; Adobe-Japan1; CID+18684 -27AAE E0100; Hanyo-Denshi; KS406720 -27AAE E0100; Moji_Joho; MJ049070 -27AAE E0101; Hanyo-Denshi; KS407000 -27AAE E0101; Moji_Joho; MJ058758 -27AE2 E0100; Hanyo-Denshi; KS407430 -27AE2 E0100; Moji_Joho; MJ049104 -27AE2 E0101; Hanyo-Denshi; KS407810 -27AE2 E0101; Moji_Joho; MJ049105 -27B27 E0100; Hanyo-Denshi; KS408650 -27B27 E0101; Hanyo-Denshi; TK01086000 -27B2F E0100; Hanyo-Denshi; KS408540 -27B2F E0100; Moji_Joho; MJ058763 -27B2F E0101; Hanyo-Denshi; KS408910 -27B2F E0101; Moji_Joho; MJ049169 -27B6E E0100; Hanyo-Denshi; KS409270 -27B6E E0101; Hanyo-Denshi; TK01086120 -27B87 E0100; Hanyo-Denshi; IB0378 -27B87 E0100; Moji_Joho; MJ049240 -27B87 E0101; Hanyo-Denshi; IB0902 -27B87 E0101; Moji_Joho; MJ049239 -27BB3 E0100; Adobe-Japan1; CID+18699 -27BBE E0100; Adobe-Japan1; CID+18701 -27BBE E0101; Hanyo-Denshi; JD8889 -27BBE E0102; Hanyo-Denshi; TK01086280 -27BC6 E0100; Hanyo-Denshi; IB2956 -27BC6 E0100; Moji_Joho; MJ049295 -27BC6 E0101; Hanyo-Denshi; KS411180 -27BC6 E0101; Moji_Joho; MJ049294 -27BC7 E0100; Adobe-Japan1; CID+18702 -27BCC E0100; Hanyo-Denshi; KS411270 -27BCC E0100; Moji_Joho; MJ049300 -27BCC E0101; Hanyo-Denshi; KS411360 -27BCC E0101; Moji_Joho; MJ049301 -27BEE E0100; Hanyo-Denshi; KS411780 -27BEE E0101; Hanyo-Denshi; TK01086360 -27BFE E0100; Hanyo-Denshi; JTAF9B -27BFE E0100; Moji_Joho; MJ049344 -27BFE E0101; Hanyo-Denshi; JTAF9BS -27BFE E0101; Moji_Joho; MJ049345 -27C3C E0100; Adobe-Japan1; CID+20220 -27CA8 E0100; Hanyo-Denshi; KS414230 -27CA8 E0100; Moji_Joho; MJ049485 -27CA8 E0101; Hanyo-Denshi; KS414510 -27CA8 E0101; Moji_Joho; MJ049486 -27CB8 E0100; Adobe-Japan1; CID+18708 -27D24 E0100; Hanyo-Denshi; KS415740 -27D24 E0101; Hanyo-Denshi; TK01086650 -27D2A E0100; Hanyo-Denshi; KS415820 -27D2A E0100; Moji_Joho; MJ049589 -27D2A E0101; Hanyo-Denshi; KS415910 -27D2A E0101; Moji_Joho; MJ049590 -27D4D E0100; Hanyo-Denshi; KS416590 -27D4D E0100; Moji_Joho; MJ049613 -27D4D E0101; Hanyo-Denshi; KS417110 -27D4D E0101; Moji_Joho; MJ049614 -27D6D E0100; Hanyo-Denshi; KS416930 -27D6D E0101; Hanyo-Denshi; TK01086920 -27D73 E0100; Adobe-Japan1; CID+20060 -27DA0 E0100; Adobe-Japan1; CID+18716 -27DCE E0100; Hanyo-Denshi; KS063760 -27DCE E0101; Hanyo-Denshi; TK01017980 -27E10 E0100; Adobe-Japan1; CID+18718 -27E19 E0100; Hanyo-Denshi; IB0380 -27E19 E0100; Moji_Joho; MJ049743 -27E19 E0101; Hanyo-Denshi; IB0906 -27E19 E0101; Moji_Joho; MJ049742 -27E3C E0100; Hanyo-Denshi; TK01087290 -27E3C E0101; Hanyo-Denshi; TK01087310 -27E3D E0100; Hanyo-Denshi; IB0381 -27E3D E0100; Moji_Joho; MJ049759 -27E3D E0101; Hanyo-Denshi; IB0907 -27E3D E0101; Moji_Joho; MJ049758 -27E79 E0100; Hanyo-Denshi; KS419940 -27E79 E0100; Moji_Joho; MJ049791 -27E79 E0101; Hanyo-Denshi; KS419960 -27E79 E0101; Moji_Joho; MJ049792 -27FA8 E0100; Hanyo-Denshi; KS423200 -27FA8 E0100; Moji_Joho; MJ049992 -27FA8 E0101; Hanyo-Denshi; KS423250 -27FA8 E0101; Moji_Joho; MJ049993 -27FB7 E0100; Adobe-Japan1; CID+13898 -2802E E0100; Hanyo-Denshi; KS425200 -2802E E0101; Hanyo-Denshi; TK01087710 -2808A E0100; Adobe-Japan1; CID+18727 -280BB E0100; Adobe-Japan1; CID+18733 -2818B E0100; Hanyo-Denshi; KS429300 -2818B E0101; Hanyo-Denshi; TK01087840 -28277 E0100; Adobe-Japan1; CID+17140 -28282 E0100; Adobe-Japan1; CID+18745 -282F3 E0100; Adobe-Japan1; CID+18747 -2836D E0100; Hanyo-Denshi; KS434970 -2836D E0101; Hanyo-Denshi; TK01088310 -2838A E0100; Hanyo-Denshi; KS435340S -2838A E0100; Moji_Joho; MJ050631 -2838A E0101; Hanyo-Denshi; KS435610 -2838A E0101; Moji_Joho; MJ050632 -283CA E0100; Hanyo-Denshi; KS436180 -283CA E0101; Hanyo-Denshi; TK01088430 -283CD E0100; Adobe-Japan1; CID+17146 -283F3 E0100; Hanyo-Denshi; KS436600 -283F3 E0101; Hanyo-Denshi; TK01088450 -2840C E0100; Adobe-Japan1; CID+18754 -28432 E0100; Hanyo-Denshi; KS437230 -28432 E0100; Moji_Joho; MJ050748 -28432 E0101; Hanyo-Denshi; KS437240 -28432 E0101; Moji_Joho; MJ050749 -2844D E0100; Hanyo-Denshi; IB0383 -2844D E0100; Moji_Joho; MJ050769 -2844D E0101; Hanyo-Denshi; IB0912 -2844D E0101; Moji_Joho; MJ050768 -28452 E0100; Hanyo-Denshi; IB0384 -28452 E0100; Moji_Joho; MJ050775 -28452 E0101; Hanyo-Denshi; IB0913 -28452 E0101; Moji_Joho; MJ050774 -28453 E0100; Hanyo-Denshi; KS438000 -28453 E0101; Hanyo-Denshi; TK01088610 -28455 E0100; Adobe-Japan1; CID+18757 -28455 E0101; Hanyo-Denshi; JD8975 -28455 E0101; Moji_Joho; MJ050780 -28455 E0102; Hanyo-Denshi; KS438120 -28455 E0102; Moji_Joho; MJ050779 -28464 E0100; Hanyo-Denshi; KS438320 -28464 E0101; Hanyo-Denshi; TK01088670 -28468 E0100; Hanyo-Denshi; KS438370 -28468 E0101; Hanyo-Denshi; TK01088660 -2846D E0100; Hanyo-Denshi; IB0387 -2846D E0100; Moji_Joho; MJ050801 -2846D E0101; Hanyo-Denshi; IB0923 -2846D E0101; Moji_Joho; MJ050800 -28482 E0100; Hanyo-Denshi; IB0678 -28482 E0100; Moji_Joho; MJ057455 -28482 E0101; Hanyo-Denshi; KS438250 -28482 E0101; Moji_Joho; MJ058843 -28484 E0100; Hanyo-Denshi; KS438860 -28484 E0101; Hanyo-Denshi; TK01088770 -28489 E0100; Hanyo-Denshi; IB0389 -28489 E0100; Moji_Joho; MJ050819 -28489 E0101; Hanyo-Denshi; IB0930 -28489 E0101; Moji_Joho; MJ050818 -2848C E0100; Hanyo-Denshi; IB0390 -2848C E0100; Moji_Joho; MJ050823 -2848C E0101; Hanyo-Denshi; IB0932 -2848C E0101; Moji_Joho; MJ050822 -284A6 E0100; Hanyo-Denshi; KS439560 -284A6 E0101; Hanyo-Denshi; TK01088840 -284AB E0100; Hanyo-Denshi; KS439670 -284AB E0101; Hanyo-Denshi; TK01088890 -284AD E0100; Hanyo-Denshi; IB0392 -284AD E0100; Moji_Joho; MJ050849 -284AD E0101; Hanyo-Denshi; IB0941 -284AD E0101; Moji_Joho; MJ050848 -284B0 E0100; Hanyo-Denshi; IB0393 -284B0 E0100; Moji_Joho; MJ050853 -284B0 E0101; Hanyo-Denshi; IB0942 -284B0 E0101; Moji_Joho; MJ050852 -284C5 E0100; Hanyo-Denshi; IB0394 -284C5 E0100; Moji_Joho; MJ050869 -284C5 E0101; Hanyo-Denshi; IB0944 -284C5 E0101; Moji_Joho; MJ050868 -284C9 E0100; Hanyo-Denshi; KS440550 -284C9 E0101; Hanyo-Denshi; TK01089110 -284CD E0100; Hanyo-Denshi; KS440300 -284CD E0100; Moji_Joho; MJ058849 -284CD E0101; Hanyo-Denshi; KS440680 -284CD E0101; Moji_Joho; MJ050877 -284E4 E0100; Hanyo-Denshi; JTBC87 -284E4 E0100; Moji_Joho; MJ050889 -284E4 E0101; Hanyo-Denshi; JTBC88 -284E4 E0101; Moji_Joho; MJ050888 -284E4 E0102; Hanyo-Denshi; KS441050 -284E4 E0102; Moji_Joho; MJ050890 -284F1 E0100; Hanyo-Denshi; KS440310 -284F1 E0100; Moji_Joho; MJ050902 -284F1 E0101; Hanyo-Denshi; KS441230 -284F1 E0101; Moji_Joho; MJ050903 -284F5 E0100; Hanyo-Denshi; IB0404 -284F5 E0100; Moji_Joho; MJ050908 -284F5 E0101; Hanyo-Denshi; IB0956 -284F5 E0101; Moji_Joho; MJ050907 -284FD E0100; Hanyo-Denshi; KS441520 -284FD E0101; Hanyo-Denshi; TK01089370 -28505 E0100; Hanyo-Denshi; KS441540 -28505 E0101; Hanyo-Denshi; TK01089400 -2851D E0100; Hanyo-Denshi; IB0406 -2851D E0100; Moji_Joho; MJ050934 -2851D E0101; Hanyo-Denshi; IB0963 -2851D E0101; Moji_Joho; MJ050933 -2851F E0100; Hanyo-Denshi; IB0407 -2851F E0100; Moji_Joho; MJ050937 -2851F E0101; Hanyo-Denshi; IB0966 -2851F E0101; Moji_Joho; MJ050936 -28527 E0100; Hanyo-Denshi; IB0409 -28527 E0100; Moji_Joho; MJ050945 -28527 E0101; Hanyo-Denshi; IB0970 -28527 E0101; Moji_Joho; MJ050944 -2852B E0100; Hanyo-Denshi; JTBCCF -2852B E0100; Moji_Joho; MJ050950 -2852B E0101; Hanyo-Denshi; JTBCD0 -2852B E0101; Moji_Joho; MJ050949 -2852C E0100; Hanyo-Denshi; KS442380 -2852C E0101; Hanyo-Denshi; TK01089660 -2852F E0100; Hanyo-Denshi; JTBCBB -2852F E0100; Moji_Joho; MJ060228 -2852F E0101; Hanyo-Denshi; KS442420 -2852F E0101; Moji_Joho; MJ050956 -28530 E0100; Hanyo-Denshi; KS442430 -28530 E0100; Moji_Joho; MJ050957 -28530 E0101; Hanyo-Denshi; KS442810 -28530 E0101; Moji_Joho; MJ050958 -28546 E0100; Hanyo-Denshi; TK01089570 -28546 E0101; Hanyo-Denshi; TK01089820 -28560 E0100; Hanyo-Denshi; IB0411 -28560 E0100; Moji_Joho; MJ050977 -28560 E0101; Hanyo-Denshi; IB0974 -28560 E0101; Moji_Joho; MJ050976 -28563 E0100; Hanyo-Denshi; IB0412 -28563 E0100; Moji_Joho; MJ050981 -28563 E0101; Hanyo-Denshi; IB0975 -28563 E0101; Moji_Joho; MJ050980 -28565 E0100; Hanyo-Denshi; IB0415 -28565 E0100; Moji_Joho; MJ050984 -28565 E0101; Hanyo-Denshi; IB0979 -28565 E0101; Moji_Joho; MJ050983 -2856B E0100; Adobe-Japan1; CID+18770 -2856B E0101; Hanyo-Denshi; JD8990 -2856B E0101; Moji_Joho; MJ050991 -2856B E0102; Hanyo-Denshi; KS443220 -2856B E0102; Moji_Joho; MJ050990 -2856B E0103; Hanyo-Denshi; JTBCEA -2856B E0103; Moji_Joho; MJ050992 -28582 E0100; Hanyo-Denshi; TK01089870 -28582 E0101; Hanyo-Denshi; TK01089880 -28587 E0100; Hanyo-Denshi; KS443410 -28587 E0101; Hanyo-Denshi; TK01090110 -28588 E0100; Hanyo-Denshi; IB0982 -28588 E0100; Moji_Joho; MJ051008 -28588 E0101; Hanyo-Denshi; JTBD08 -28588 E0101; Moji_Joho; MJ051009 -2858A E0100; Hanyo-Denshi; IB0418 -2858A E0100; Moji_Joho; MJ051012 -2858A E0101; Hanyo-Denshi; IB0984 -2858A E0101; Moji_Joho; MJ051011 -285A3 E0100; Hanyo-Denshi; KS443760 -285A3 E0101; Hanyo-Denshi; TK01090360 -285B6 E0100; Hanyo-Denshi; KS444100 -285B6 E0101; Hanyo-Denshi; TK01090230 -285B9 E0100; Hanyo-Denshi; IB0421 -285B9 E0100; Moji_Joho; MJ051045 -285B9 E0101; Hanyo-Denshi; IB0990 -285B9 E0101; Moji_Joho; MJ051044 -285BB E0100; Hanyo-Denshi; IB0422 -285BB E0100; Moji_Joho; MJ051047 -285BB E0101; Hanyo-Denshi; IB0991 -285BB E0101; Moji_Joho; MJ051046 -285BE E0100; Hanyo-Denshi; KS444270 -285BE E0101; Hanyo-Denshi; TK01090180 -285BF E0100; Hanyo-Denshi; IB0424 -285BF E0100; Moji_Joho; MJ051052 -285BF E0101; Hanyo-Denshi; IB1001 -285BF E0101; Moji_Joho; MJ051051 -285C8 E0100; Adobe-Japan1; CID+18773 -285C8 E0101; Hanyo-Denshi; JD8994 -285C8 E0102; Hanyo-Denshi; TK01090210 -285C9 E0100; Adobe-Japan1; CID+18774 -285C9 E0101; Hanyo-Denshi; JD9001 -285C9 E0101; Moji_Joho; MJ051061 -285C9 E0102; Hanyo-Denshi; KS444640 -285C9 E0102; Moji_Joho; MJ051060 -285C9 E0103; Hanyo-Denshi; TK01090160 -285C9 E0104; Hanyo-Denshi; TK01090270 -285E1 E0100; Hanyo-Denshi; KS444400 -285E1 E0101; Hanyo-Denshi; TK01090250 -285EA E0100; Hanyo-Denshi; KS444800 -285EA E0101; Hanyo-Denshi; TK01090130 -285ED E0100; Hanyo-Denshi; KS444240 -285ED E0100; Moji_Joho; MJ051088 -285ED E0101; Hanyo-Denshi; KS444870 -285ED E0101; Moji_Joho; MJ051089 -285F1 E0100; Hanyo-Denshi; IB0427 -285F1 E0100; Moji_Joho; MJ051094 -285F1 E0101; Hanyo-Denshi; IB1003 -285F1 E0101; Moji_Joho; MJ051093 -285F2 E0100; Hanyo-Denshi; TK01081110 -285F2 E0101; Hanyo-Denshi; TK01081560 -285F4 E0100; Hanyo-Denshi; TK01090310 -285F4 E0101; Hanyo-Denshi; TK01090480 -28622 E0100; Hanyo-Denshi; JTBD6C -28622 E0100; Moji_Joho; MJ051124 -28622 E0101; Hanyo-Denshi; JTBD6D -28622 E0101; Moji_Joho; MJ051123 -28637 E0100; Hanyo-Denshi; IB0431 -28637 E0100; Moji_Joho; MJ051138 -28637 E0101; Hanyo-Denshi; IB1012 -28637 E0101; Moji_Joho; MJ051137 -28642 E0100; Hanyo-Denshi; IB0432 -28642 E0100; Moji_Joho; MJ051147 -28642 E0101; Hanyo-Denshi; IB1013 -28642 E0101; Moji_Joho; MJ051146 -28644 E0100; Hanyo-Denshi; KS445720 -28644 E0101; Hanyo-Denshi; TK01090300 -28644 E0102; Hanyo-Denshi; TK01090600 -2864E E0100; Hanyo-Denshi; KS445750 -2864E E0101; Hanyo-Denshi; TK01090570 -28655 E0100; Hanyo-Denshi; IB0433 -28655 E0100; Moji_Joho; MJ051162 -28655 E0101; Hanyo-Denshi; IB1015 -28655 E0101; Moji_Joho; MJ051161 -28659 E0100; Hanyo-Denshi; IB0434 -28659 E0100; Moji_Joho; MJ051166 -28659 E0101; Hanyo-Denshi; IB1016 -28659 E0101; Moji_Joho; MJ051165 -28659 E0102; Hanyo-Denshi; KS445930 -28659 E0102; Moji_Joho; MJ058876 -2865A E0100; Hanyo-Denshi; IB0435 -2865A E0100; Moji_Joho; MJ051168 -2865A E0101; Hanyo-Denshi; IB1017 -2865A E0101; Moji_Joho; MJ051167 -2865A E0102; Hanyo-Denshi; KS446000 -2865A E0102; Moji_Joho; MJ051169 -2865F E0100; Hanyo-Denshi; IB0436 -2865F E0100; Moji_Joho; MJ051173 -2865F E0101; Hanyo-Denshi; IB1019 -2865F E0101; Moji_Joho; MJ051172 -2865F E0102; Hanyo-Denshi; KS446060 -2865F E0102; Moji_Joho; MJ051174 -286D7 E0100; Adobe-Japan1; CID+18784 -286FA E0100; Adobe-Japan1; CID+18787 -2874A E0100; Hanyo-Denshi; KS449200 -2874A E0101; Hanyo-Denshi; TK01091130 -28763 E0100; Hanyo-Denshi; KS449440 -28763 E0100; Moji_Joho; MJ051374 -28763 E0101; Hanyo-Denshi; KS449720 -28763 E0101; Moji_Joho; MJ058877 -2880B E0100; Moji_Joho; MJ051498 -2880B E0101; Moji_Joho; MJ051499 -28945 E0100; Hanyo-Denshi; JTBDCAS -28945 E0100; Moji_Joho; MJ051702 -28945 E0101; Hanyo-Denshi; JTBDCD -28945 E0101; Moji_Joho; MJ060262 -28946 E0100; Adobe-Japan1; CID+18812 -28949 E0100; Adobe-Japan1; CID+18811 -2896B E0100; Adobe-Japan1; CID+18817 -28987 E0100; Adobe-Japan1; CID+14253 -28988 E0100; Adobe-Japan1; CID+18824 -2898D E0100; Hanyo-Denshi; TK01092240 -2898D E0101; Hanyo-Denshi; TK01092500 -289BA E0100; Adobe-Japan1; CID+18834 -289BB E0100; Adobe-Japan1; CID+18835 -289DC E0100; Hanyo-Denshi; TK01092450 -289DC E0101; Hanyo-Denshi; TK01092460 -289EE E0100; Hanyo-Denshi; KS460180 -289EE E0101; Hanyo-Denshi; TK01092870 -28A1E E0100; Adobe-Japan1; CID+18843 -28A29 E0100; Adobe-Japan1; CID+18844 -28A43 E0100; Adobe-Japan1; CID+18848 -28A71 E0100; Adobe-Japan1; CID+18847 -28A71 E0101; Hanyo-Denshi; JD9112 -28A71 E0101; Moji_Joho; MJ051827 -28A71 E0102; Hanyo-Denshi; JTBE15 -28A71 E0102; Moji_Joho; MJ051828 -28A71 E0103; Hanyo-Denshi; TK01093310 -28A8B E0100; Hanyo-Denshi; KS462170 -28A8B E0101; Hanyo-Denshi; TK01093790 -28A99 E0100; Adobe-Japan1; CID+18855 -28ACD E0100; Adobe-Japan1; CID+18856 -28ADD E0100; Adobe-Japan1; CID+18863 -28AE4 E0100; Adobe-Japan1; CID+18862 -28B4E E0100; Hanyo-Denshi; IB3141 -28B4E E0101; Hanyo-Denshi; TK01094170 -28B6A E0100; Hanyo-Denshi; KS465100 -28B6A E0101; Hanyo-Denshi; TK01094270 -28B92 E0100; Hanyo-Denshi; KS465180 -28B92 E0101; Hanyo-Denshi; TK01094470 -28BC1 E0100; Adobe-Japan1; CID+18874 -28BEF E0100; Adobe-Japan1; CID+18875 -28BEF E0101; Hanyo-Denshi; JD9147 -28BEF E0101; Moji_Joho; MJ051959 -28BEF E0102; Hanyo-Denshi; JTBE4F -28BEF E0102; Moji_Joho; MJ051960 -28C0F E0100; Hanyo-Denshi; KS466300 -28C0F E0101; Hanyo-Denshi; TK01094810 -28C67 E0100; Hanyo-Denshi; KS466850 -28C67 E0101; Hanyo-Denshi; TK01094870 -28CC1 E0100; Hanyo-Denshi; KS467690 -28CC1 E0101; Hanyo-Denshi; TK01094930 -28CDB E0100; Hanyo-Denshi; KS468030 -28CDB E0101; Hanyo-Denshi; TK01094960 -28CDD E0100; Adobe-Japan1; CID+7641 -28CDD E0101; Moji_Joho; MJ027427 -28CDD E0102; Moji_Joho; MJ052103 -28D02 E0100; Hanyo-Denshi; KS468570 -28D02 E0101; Hanyo-Denshi; TK01095020 -28D10 E0100; Adobe-Japan1; CID+18882 -28D71 E0100; Adobe-Japan1; CID+18883 -28D7F E0100; Hanyo-Denshi; JTBE65 -28D7F E0101; Hanyo-Denshi; TK01095250 -28D84 E0100; Hanyo-Denshi; KS470210 -28D84 E0100; Moji_Joho; MJ052218 -28D84 E0101; Hanyo-Denshi; KS470420 -28D84 E0101; Moji_Joho; MJ052219 -28DAE E0100; Hanyo-Denshi; IB3167 -28DAE E0101; Hanyo-Denshi; TK01095350 -28DFB E0100; Adobe-Japan1; CID+18885 -28E17 E0100; Adobe-Japan1; CID+14256 -28E1F E0100; Adobe-Japan1; CID+18886 -28E36 E0100; Adobe-Japan1; CID+18890 -28E89 E0100; Adobe-Japan1; CID+18893 -28E89 E0101; Hanyo-Denshi; JD9169 -28E89 E0102; Hanyo-Denshi; TK01095660 -28EEB E0100; Adobe-Japan1; CID+18895 -28EF6 E0100; Adobe-Japan1; CID+7673 -28F06 E0100; Hanyo-Denshi; KS474420 -28F06 E0101; Hanyo-Denshi; TK01096080 -28F06 E0102; Hanyo-Denshi; TK01096160 -28F12 E0100; Hanyo-Denshi; KS474630 -28F12 E0101; Hanyo-Denshi; TK01096000 -28F32 E0100; Adobe-Japan1; CID+18897 -28F41 E0100; Hanyo-Denshi; KS475030 -28F41 E0100; Moji_Joho; MJ052468 -28F41 E0101; Hanyo-Denshi; KS475100 -28F41 E0101; Moji_Joho; MJ052469 -28FBA E0100; Hanyo-Denshi; KS476540 -28FBA E0101; Hanyo-Denshi; TK01096460 -28FE4 E0100; Hanyo-Denshi; KS476950 -28FE4 E0100; Moji_Joho; MJ052596 -28FE4 E0101; Hanyo-Denshi; KS477210 -28FE4 E0101; Moji_Joho; MJ052597 -28FF8 E0100; Adobe-Japan1; CID+18903 -29031 E0100; Hanyo-Denshi; KS477940 -29031 E0100; Moji_Joho; MJ058985 -29031 E0101; Hanyo-Denshi; KS477950 -29031 E0101; Moji_Joho; MJ052666 -29093 E0100; Hanyo-Denshi; KS479070 -29093 E0101; Hanyo-Denshi; TK01096900 -2915E E0100; Hanyo-Denshi; KS481210 -2915E E0100; Moji_Joho; MJ052866 -2915E E0101; Hanyo-Denshi; KS481490 -2915E E0101; Moji_Joho; MJ052867 -2917E E0100; Hanyo-Denshi; KS481550 -2917E E0100; Moji_Joho; MJ052888 -2917E E0101; Hanyo-Denshi; KS481740 -2917E E0101; Moji_Joho; MJ052889 -291D5 E0100; Hanyo-Denshi; IB0440 -291D5 E0100; Moji_Joho; MJ052943 -291D5 E0101; Hanyo-Denshi; IB1034 -291D5 E0101; Moji_Joho; MJ052944 -291DC E0100; Hanyo-Denshi; KS482570 -291DC E0101; Hanyo-Denshi; TK01097450 -291E3 E0100; Hanyo-Denshi; KS482750 -291E3 E0101; Hanyo-Denshi; TK01097580 -2921A E0100; Hanyo-Denshi; KS483390 -2921A E0100; Moji_Joho; MJ052996 -2921A E0101; Hanyo-Denshi; KS483620 -2921A E0101; Moji_Joho; MJ052997 -2925E E0100; Hanyo-Denshi; KS484200 -2925E E0100; Moji_Joho; MJ053053 -2925E E0101; Hanyo-Denshi; KS484240 -2925E E0101; Moji_Joho; MJ053054 -29293 E0100; Hanyo-Denshi; KS485020 -29293 E0100; Moji_Joho; MJ053098 -29293 E0101; Hanyo-Denshi; KS485340 -29293 E0101; Moji_Joho; MJ059008 -292A0 E0100; Adobe-Japan1; CID+18917 -292B1 E0100; Adobe-Japan1; CID+18918 -29356 E0100; Hanyo-Denshi; KS487620 -29356 E0100; Moji_Joho; MJ053254 -29356 E0101; Hanyo-Denshi; KS487800 -29356 E0101; Moji_Joho; MJ053255 -29379 E0100; Hanyo-Denshi; KS488080 -29379 E0100; Moji_Joho; MJ053281 -29379 E0101; Hanyo-Denshi; KS488130 -29379 E0101; Moji_Joho; MJ053282 -2941A E0100; Hanyo-Denshi; KS490230 -2941A E0100; Moji_Joho; MJ053402 -2941A E0101; Hanyo-Denshi; KS490290 -2941A E0101; Moji_Joho; MJ053403 -2941F E0100; Hanyo-Denshi; KS490310 -2941F E0100; Moji_Joho; MJ053407 -2941F E0101; Hanyo-Denshi; KS490400 -2941F E0101; Moji_Joho; MJ053408 -29420 E0100; Hanyo-Denshi; KS490320 -29420 E0100; Moji_Joho; MJ053409 -29420 E0101; Hanyo-Denshi; KS490410 -29420 E0101; Moji_Joho; MJ053410 -29422 E0100; Hanyo-Denshi; KS490350 -29422 E0100; Moji_Joho; MJ053412 -29422 E0101; Hanyo-Denshi; KS490420 -29422 E0101; Moji_Joho; MJ053413 -29427 E0100; Hanyo-Denshi; KS490430 -29427 E0100; Moji_Joho; MJ053418 -29427 E0101; Hanyo-Denshi; KS490480 -29427 E0101; Moji_Joho; MJ053419 -2943F E0100; Hanyo-Denshi; KS490800 -2943F E0100; Moji_Joho; MJ053437 -2943F E0101; Hanyo-Denshi; KS490830 -2943F E0101; Moji_Joho; MJ053438 -2944E E0100; Hanyo-Denshi; TK01097990 -2944E E0101; Hanyo-Denshi; TK01098000 -29490 E0100; Adobe-Japan1; CID+18935 -294E8 E0100; Hanyo-Denshi; KS493320 -294E8 E0101; Hanyo-Denshi; TK01098170 -29524 E0100; Moji_Joho; MJ053608 -29524 E0101; Moji_Joho; MJ059031 -2953A E0100; Hanyo-Denshi; KS494490 -2953A E0100; Moji_Joho; MJ053621 -2953A E0101; Hanyo-Denshi; KS494580 -2953A E0101; Moji_Joho; MJ059032 -295B6 E0100; Hanyo-Denshi; KS495840 -295B6 E0100; Moji_Joho; MJ053709 -295B6 E0101; Hanyo-Denshi; KS495850 -295B6 E0101; Moji_Joho; MJ053710 -295CF E0100; Adobe-Japan1; CID+18944 -29638 E0100; Hanyo-Denshi; KS497410 -29638 E0100; Moji_Joho; MJ059038 -29638 E0101; Hanyo-Denshi; KS497420 -29638 E0101; Moji_Joho; MJ053809 -2965E E0100; Hanyo-Denshi; KS497860 -2965E E0100; Moji_Joho; MJ053840 -2965E E0101; Hanyo-Denshi; KS497870 -2965E E0101; Moji_Joho; MJ053841 -2967A E0100; Hanyo-Denshi; KS498010 -2967A E0100; Moji_Joho; MJ053853 -2967A E0101; Hanyo-Denshi; KS498030 -2967A E0101; Moji_Joho; MJ053854 -2967F E0100; Adobe-Japan1; CID+13849 -29682 E0100; Hanyo-Denshi; IB0443 -29682 E0100; Moji_Joho; MJ053862 -29682 E0101; Hanyo-Denshi; IB1043 -29682 E0101; Moji_Joho; MJ053861 -29685 E0100; Hanyo-Denshi; IB0444 -29685 E0100; Moji_Joho; MJ053866 -29685 E0101; Hanyo-Denshi; IB1047 -29685 E0101; Moji_Joho; MJ053865 -29688 E0100; Hanyo-Denshi; IB0445 -29688 E0100; Moji_Joho; MJ053869 -29688 E0101; Hanyo-Denshi; IB1048 -29688 E0101; Moji_Joho; MJ053868 -29695 E0100; Hanyo-Denshi; IB0447 -29695 E0100; Moji_Joho; MJ053880 -29695 E0101; Hanyo-Denshi; IB1052 -29695 E0101; Moji_Joho; MJ053879 -29696 E0100; Hanyo-Denshi; IB0446 -29696 E0100; Moji_Joho; MJ053882 -29696 E0101; Hanyo-Denshi; IB1050 -29696 E0101; Moji_Joho; MJ053881 -296A9 E0100; Hanyo-Denshi; IB0449 -296A9 E0100; Moji_Joho; MJ053895 -296A9 E0101; Hanyo-Denshi; IB1054 -296A9 E0101; Moji_Joho; MJ053894 -296B9 E0100; Hanyo-Denshi; IB0452 -296B9 E0100; Moji_Joho; MJ053912 -296B9 E0101; Hanyo-Denshi; IB1060 -296B9 E0101; Moji_Joho; MJ053911 -296C6 E0100; Hanyo-Denshi; IB0453 -296C6 E0100; Moji_Joho; MJ053921 -296C6 E0101; Hanyo-Denshi; IB1061 -296C6 E0101; Moji_Joho; MJ053920 -296DE E0100; Hanyo-Denshi; IB0459 -296DE E0100; Moji_Joho; MJ053939 -296DE E0101; Hanyo-Denshi; IB1069 -296DE E0101; Moji_Joho; MJ053938 -296E5 E0100; Hanyo-Denshi; IB0462 -296E5 E0100; Moji_Joho; MJ053947 -296E5 E0101; Hanyo-Denshi; IB1074 -296E5 E0101; Moji_Joho; MJ053946 -296E5 E0102; Hanyo-Denshi; TK01098600 -296F0 E0100; Adobe-Japan1; CID+18959 -296FA E0100; Hanyo-Denshi; IB0463 -296FA E0100; Moji_Joho; MJ053964 -296FA E0101; Hanyo-Denshi; IB1077 -296FA E0101; Moji_Joho; MJ053963 -29701 E0100; Hanyo-Denshi; KS500870 -29701 E0101; Hanyo-Denshi; TK01098590 -29706 E0100; Hanyo-Denshi; IB0467 -29706 E0100; Moji_Joho; MJ053978 -29706 E0101; Hanyo-Denshi; IB1084 -29706 E0101; Moji_Joho; MJ053977 -29708 E0100; Hanyo-Denshi; IB0468 -29708 E0100; Moji_Joho; MJ053981 -29708 E0101; Hanyo-Denshi; IB1085 -29708 E0101; Moji_Joho; MJ053980 -2970B E0100; Hanyo-Denshi; IB0469 -2970B E0100; Moji_Joho; MJ053985 -2970B E0101; Hanyo-Denshi; IB1086 -2970B E0101; Moji_Joho; MJ053984 -2970F E0100; Hanyo-Denshi; IB0471 -2970F E0100; Moji_Joho; MJ053991 -2970F E0101; Hanyo-Denshi; IB1092 -2970F E0101; Moji_Joho; MJ053989 -2970F E0102; Hanyo-Denshi; KS501470 -2970F E0102; Moji_Joho; MJ053990 -29715 E0100; Hanyo-Denshi; KS500430 -29715 E0100; Moji_Joho; MJ053996 -29715 E0101; Hanyo-Denshi; KS501200 -29715 E0101; Moji_Joho; MJ053997 -29717 E0100; Hanyo-Denshi; IB0472 -29717 E0100; Moji_Joho; MJ054000 -29717 E0101; Hanyo-Denshi; JTBF5A -29717 E0101; Moji_Joho; MJ053999 -29719 E0100; Adobe-Japan1; CID+18962 -29719 E0101; Hanyo-Denshi; JD9257 -29719 E0101; Moji_Joho; MJ054001 -29719 E0102; Hanyo-Denshi; JTBF5F -29719 E0102; Moji_Joho; MJ054002 -29719 E0103; Hanyo-Denshi; TK01098660 -2972F E0100; Hanyo-Denshi; IB0473 -2972F E0100; Moji_Joho; MJ054010 -2972F E0101; Hanyo-Denshi; IB1104 -2972F E0101; Moji_Joho; MJ054009 -2972F E0102; Hanyo-Denshi; KS502140 -2972F E0102; Moji_Joho; MJ059044 -29734 E0100; Hanyo-Denshi; IB0475 -29734 E0100; Moji_Joho; MJ054017 -29734 E0101; Hanyo-Denshi; IB1106 -29734 E0101; Moji_Joho; MJ054015 -29734 E0102; Hanyo-Denshi; KS502150 -29734 E0102; Moji_Joho; MJ054016 -29739 E0100; Hanyo-Denshi; IB0476 -29739 E0100; Moji_Joho; MJ054023 -29739 E0101; Hanyo-Denshi; IB1110 -29739 E0101; Moji_Joho; MJ054022 -2973F E0100; Hanyo-Denshi; IB0478 -2973F E0100; Moji_Joho; MJ054028 -2973F E0101; Hanyo-Denshi; IB1114 -2973F E0101; Moji_Joho; MJ054062 -29750 E0100; Adobe-Japan1; CID+18966 -29759 E0100; Hanyo-Denshi; IB0481 -29759 E0100; Moji_Joho; MJ054041 -29759 E0101; Hanyo-Denshi; IB1116 -29759 E0101; Moji_Joho; MJ054040 -2975D E0100; Hanyo-Denshi; IB0484 -2975D E0100; Moji_Joho; MJ054045 -2975D E0101; Hanyo-Denshi; IB1121 -2975D E0101; Moji_Joho; MJ054044 -29780 E0100; Hanyo-Denshi; IB0488 -29780 E0100; Moji_Joho; MJ054075 -29780 E0101; Hanyo-Denshi; IB1131 -29780 E0101; Moji_Joho; MJ054074 -29783 E0100; Hanyo-Denshi; IB0489 -29783 E0100; Moji_Joho; MJ054079 -29783 E0101; Hanyo-Denshi; IB1132 -29783 E0101; Moji_Joho; MJ054078 -2978D E0100; Hanyo-Denshi; IB0491 -2978D E0100; Moji_Joho; MJ054090 -2978D E0101; Hanyo-Denshi; IB1138 -2978D E0101; Moji_Joho; MJ054089 -2978F E0100; Hanyo-Denshi; IB0490 -2978F E0100; Moji_Joho; MJ054093 -2978F E0101; Hanyo-Denshi; IB1135 -2978F E0101; Moji_Joho; MJ054092 -29791 E0100; Hanyo-Denshi; IB0492 -29791 E0100; Moji_Joho; MJ054096 -29791 E0101; Hanyo-Denshi; IB1139 -29791 E0101; Moji_Joho; MJ054095 -297A1 E0100; Hanyo-Denshi; IB0501 -297A1 E0100; Moji_Joho; MJ054100 -297A1 E0101; Hanyo-Denshi; IB1142 -297A1 E0101; Moji_Joho; MJ054099 -297A5 E0100; Hanyo-Denshi; IB0502 -297A5 E0100; Moji_Joho; MJ054105 -297A5 E0101; Hanyo-Denshi; JTBFA8 -297A5 E0101; Moji_Joho; MJ054104 -297A7 E0100; Hanyo-Denshi; IB0503 -297A7 E0100; Moji_Joho; MJ054108 -297A7 E0101; Hanyo-Denshi; IB1145 -297A7 E0101; Moji_Joho; MJ054107 -297AB E0100; Hanyo-Denshi; IB0493 -297AB E0100; Moji_Joho; MJ054113 -297AB E0101; Hanyo-Denshi; IB1140 -297AB E0101; Moji_Joho; MJ054112 -297AB E0102; Hanyo-Denshi; KS503640 -297AB E0102; Moji_Joho; MJ054114 -297AD E0100; Hanyo-Denshi; IB0494 -297AD E0100; Moji_Joho; MJ054117 -297AD E0101; Hanyo-Denshi; IB1141 -297AD E0101; Moji_Joho; MJ054116 -297AD E0102; Hanyo-Denshi; KS503460 -297AD E0102; Moji_Joho; MJ054118 -297B7 E0100; Hanyo-Denshi; IB0504 -297B7 E0100; Moji_Joho; MJ054125 -297B7 E0101; Hanyo-Denshi; IB1149 -297B7 E0101; Moji_Joho; MJ054124 -297C4 E0100; Hanyo-Denshi; IB0505 -297C4 E0100; Moji_Joho; MJ054137 -297C4 E0101; Hanyo-Denshi; IB1150 -297C4 E0101; Moji_Joho; MJ054136 -297CB E0100; Hanyo-Denshi; IB0506 -297CB E0100; Moji_Joho; MJ054144 -297CB E0101; Hanyo-Denshi; IB1153 -297CB E0101; Moji_Joho; MJ054143 -297F1 E0100; Hanyo-Denshi; IB0510 -297F1 E0100; Moji_Joho; MJ054174 -297F1 E0101; Hanyo-Denshi; IB1158 -297F1 E0101; Moji_Joho; MJ054173 -297FD E0100; Hanyo-Denshi; IB1166 -297FD E0100; Moji_Joho; MJ054181 -297FD E0101; Hanyo-Denshi; IP9962 -297FD E0101; Moji_Joho; MJ054182 -29854 E0100; Hanyo-Denshi; KS505260 -29854 E0101; Hanyo-Denshi; TK01098940 -29858 E0100; Hanyo-Denshi; KS505290 -29858 E0101; Hanyo-Denshi; TK01098930 -2985D E0100; Hanyo-Denshi; KS505330 -2985D E0101; Hanyo-Denshi; TK01098970 -29879 E0100; Hanyo-Denshi; KS505740 -29879 E0101; Hanyo-Denshi; TK01099110 -29894 E0100; Hanyo-Denshi; JTBFDA -29894 E0100; Moji_Joho; MJ054275 -29894 E0101; Hanyo-Denshi; KS506250 -29894 E0101; Moji_Joho; MJ054274 -2989D E0100; Hanyo-Denshi; KS506090 -2989D E0100; Moji_Joho; MJ054284 -2989D E0101; Hanyo-Denshi; KS506590 -2989D E0101; Moji_Joho; MJ054285 -298C6 E0100; Adobe-Japan1; CID+18983 -29900 E0100; Hanyo-Denshi; KS508090 -29900 E0100; Moji_Joho; MJ054361 -29900 E0101; Hanyo-Denshi; KS508750 -29900 E0101; Moji_Joho; MJ059053 -2994A E0100; Hanyo-Denshi; KS509100 -2994A E0101; Hanyo-Denshi; TK01099330 -2998B E0100; Hanyo-Denshi; KS510010 -2998B E0101; Hanyo-Denshi; TK01099450 -29A59 E0100; Hanyo-Denshi; KS512050 -29A59 E0100; Moji_Joho; MJ059062 -29A59 E0101; Hanyo-Denshi; KS512120 -29A59 E0101; Moji_Joho; MJ054564 -29A72 E0100; Adobe-Japan1; CID+19001 -29AB7 E0100; Hanyo-Denshi; JTBFF2 -29AB7 E0100; Moji_Joho; MJ054636 -29AB7 E0101; Hanyo-Denshi; JTBFF3 -29AB7 E0101; Moji_Joho; MJ054637 -29AEF E0100; Hanyo-Denshi; KS513620 -29AEF E0101; Hanyo-Denshi; TK01099690 -29BBA E0100; Hanyo-Denshi; KS515790 -29BBA E0100; Moji_Joho; MJ054792 -29BBA E0101; Hanyo-Denshi; KS515820 -29BBA E0101; Moji_Joho; MJ054793 -29C13 E0100; Hanyo-Denshi; KS516590 -29C13 E0100; Moji_Joho; MJ054845 -29C13 E0101; Hanyo-Denshi; KS516620 -29C13 E0101; Moji_Joho; MJ054846 -29C7F E0100; Hanyo-Denshi; KS517880 -29C7F E0100; Moji_Joho; MJ054933 -29C7F E0101; Hanyo-Denshi; KS517940 -29C7F E0101; Moji_Joho; MJ054934 -29D34 E0100; Hanyo-Denshi; KS519670 -29D34 E0100; Moji_Joho; MJ055064 -29D34 E0101; Hanyo-Denshi; KS519680 -29D34 E0101; Moji_Joho; MJ055065 -29D49 E0100; Hanyo-Denshi; KS519790 -29D49 E0100; Moji_Joho; MJ059085 -29D49 E0101; Hanyo-Denshi; KS519800 -29D49 E0101; Moji_Joho; MJ055079 -29D4B E0100; Adobe-Japan1; CID+13717 -29D4B E0101; Adobe-Japan1; CID+13718 -29D87 E0100; Hanyo-Denshi; KS520980 -29D87 E0101; Hanyo-Denshi; TK01100130 -29DDB E0100; Adobe-Japan1; CID+19026 -29DF8 E0100; Hanyo-Denshi; KS522770 -29DF8 E0100; Moji_Joho; MJ055180 -29DF8 E0101; Hanyo-Denshi; KS523730 -29DF8 E0101; Moji_Joho; MJ059133 -29E15 E0100; Adobe-Japan1; CID+19036 -29E3D E0100; Adobe-Japan1; CID+20315 -29E3D E0101; Adobe-Japan1; CID+15437 -29E3D E0102; Hanyo-Denshi; JD9344 -29E3D E0102; Moji_Joho; MJ055217 -29E3D E0103; Hanyo-Denshi; KS523690 -29E3D E0103; Moji_Joho; MJ055216 -29E3D E0104; Moji_Joho; MJ055218 -29E49 E0100; Adobe-Japan1; CID+19038 -29E7A E0100; Hanyo-Denshi; KS524790 -29E7A E0100; Moji_Joho; MJ055250 -29E7A E0101; Hanyo-Denshi; KS525390 -29E7A E0101; Moji_Joho; MJ055251 -29E8A E0100; Adobe-Japan1; CID+19037 -29E8A E0101; Hanyo-Denshi; JD9359 -29E8A E0101; Moji_Joho; MJ055265 -29E8A E0102; Hanyo-Denshi; KS525210 -29E8A E0102; Moji_Joho; MJ055264 -29E8A E0103; Hanyo-Denshi; JTC02C -29E8A E0103; Moji_Joho; MJ055266 -29EC4 E0100; Adobe-Japan1; CID+19046 -29EDB E0100; Adobe-Japan1; CID+19054 -29EDB E0101; Hanyo-Denshi; JD9380 -29EDB E0101; Moji_Joho; MJ055301 -29EDB E0102; Hanyo-Denshi; KS526200 -29EDB E0102; Moji_Joho; MJ055300 -29EE0 E0100; Hanyo-Denshi; KS526810 -29EE0 E0100; Moji_Joho; MJ055306 -29EE0 E0101; Hanyo-Denshi; KS527260 -29EE0 E0101; Moji_Joho; MJ055307 -29EE1 E0100; Hanyo-Denshi; KS526330 -29EE1 E0100; Moji_Joho; MJ055308 -29EE1 E0101; Hanyo-Denshi; KS526730 -29EE1 E0101; Moji_Joho; MJ055309 -29EE4 E0100; Hanyo-Denshi; KS526440 -29EE4 E0101; Hanyo-Denshi; TK01100540 -29EE9 E0100; Adobe-Japan1; CID+19051 -29FC7 E0100; Hanyo-Denshi; KS528730 -29FC7 E0101; Hanyo-Denshi; TK01100760 -29FCE E0100; Adobe-Japan1; CID+19071 -29FD7 E0100; Adobe-Japan1; CID+19071 -2A01A E0100; Adobe-Japan1; CID+19077 -2A02F E0100; Adobe-Japan1; CID+19075 -2A02F E0101; Moji_Joho; MJ055513 -2A02F E0102; Moji_Joho; MJ055514 -2A061 E0100; Hanyo-Denshi; KS531650 -2A061 E0100; Moji_Joho; MJ055546 -2A061 E0101; Hanyo-Denshi; KS531810 -2A061 E0101; Moji_Joho; MJ055547 -2A067 E0100; Hanyo-Denshi; KS531720 -2A067 E0101; Hanyo-Denshi; TK01100860 -2A082 E0100; Adobe-Japan1; CID+19084 -2A0C8 E0100; Hanyo-Denshi; KS533380 -2A0C8 E0100; Moji_Joho; MJ055624 -2A0C8 E0101; Hanyo-Denshi; KS533910 -2A0C8 E0101; Moji_Joho; MJ055625 -2A0C8 E0102; Hanyo-Denshi; TK01100950 -2A0F9 E0100; Adobe-Japan1; CID+19083 -2A0F9 E0101; Hanyo-Denshi; JD9418 -2A0F9 E0101; Moji_Joho; MJ055658 -2A0F9 E0102; Hanyo-Denshi; KS533900 -2A0F9 E0102; Moji_Joho; MJ055659 -2A190 E0100; Adobe-Japan1; CID+17227 -2A1F4 E0100; Hanyo-Denshi; KS537170 -2A1F4 E0100; Moji_Joho; MJ055824 -2A1F4 E0101; Hanyo-Denshi; KS537290 -2A1F4 E0101; Moji_Joho; MJ055825 -2A291 E0100; Hanyo-Denshi; KS538740 -2A291 E0100; Moji_Joho; MJ055927 -2A291 E0101; Hanyo-Denshi; KS539000 -2A291 E0101; Moji_Joho; MJ055928 -2A296 E0100; Hanyo-Denshi; KS538700S -2A296 E0100; Moji_Joho; MJ055933 -2A296 E0101; Hanyo-Denshi; KS538790 -2A296 E0101; Moji_Joho; MJ055934 -2A2A8 E0100; Hanyo-Denshi; KS538990 -2A2A8 E0100; Moji_Joho; MJ055944 -2A2A8 E0101; Hanyo-Denshi; KS539120 -2A2A8 E0101; Moji_Joho; MJ055945 -2A2B2 E0100; Adobe-Japan1; CID+20072 -2A301 E0100; Hanyo-Denshi; KS540100 -2A301 E0100; Moji_Joho; MJ056012 -2A301 E0101; Hanyo-Denshi; KS540180 -2A301 E0101; Moji_Joho; MJ056013 -2A308 E0100; Hanyo-Denshi; KS540240 -2A308 E0100; Moji_Joho; MJ056020 -2A308 E0101; Hanyo-Denshi; KS540420 -2A308 E0101; Moji_Joho; MJ059257 -2A333 E0100; Hanyo-Denshi; KS540840 -2A333 E0100; Moji_Joho; MJ056052 -2A333 E0101; Hanyo-Denshi; KS540910 -2A333 E0101; Moji_Joho; MJ059259 -2A347 E0100; Hanyo-Denshi; KS477740 -2A347 E0100; Moji_Joho; MJ056070 -2A347 E0101; Hanyo-Denshi; KS541100 -2A347 E0101; Moji_Joho; MJ056071 -2A352 E0100; Hanyo-Denshi; KS541250 -2A352 E0100; Moji_Joho; MJ056081 -2A352 E0101; Hanyo-Denshi; KS541290 -2A352 E0101; Moji_Joho; MJ059260 -2A36A E0100; Hanyo-Denshi; KS541500S -2A36A E0100; Moji_Joho; MJ056102 -2A36A E0101; Hanyo-Denshi; KS541560 -2A36A E0101; Moji_Joho; MJ059262 -2A38C E0100; Adobe-Japan1; CID+19109 -2A392 E0100; Hanyo-Denshi; KS107110 -2A392 E0100; Moji_Joho; MJ056129 -2A392 E0101; Hanyo-Denshi; KS541850 -2A392 E0101; Moji_Joho; MJ056130 -2A3B0 E0100; Hanyo-Denshi; KS542200 -2A3B0 E0100; Moji_Joho; MJ056155 -2A3B0 E0101; Hanyo-Denshi; KS542220 -2A3B0 E0101; Moji_Joho; MJ056156 -2A437 E0100; Adobe-Japan1; CID+19111 -2A472 E0100; Hanyo-Denshi; KS544940 -2A472 E0100; Moji_Joho; MJ056316 -2A472 E0101; Hanyo-Denshi; KS544950 -2A472 E0101; Moji_Joho; MJ056317 -2A502 E0100; Moji_Joho; MJ056429 -2A502 E0101; Moji_Joho; MJ056430 -2A502 E0102; Moji_Joho; MJ056431 -2A504 E0100; Hanyo-Denshi; KS546290 -2A504 E0100; Moji_Joho; MJ056432 -2A504 E0101; Hanyo-Denshi; KS546300 -2A504 E0101; Moji_Joho; MJ056433 -2A508 E0100; Hanyo-Denshi; KS078300 -2A508 E0100; Moji_Joho; MJ056436 -2A508 E0101; Hanyo-Denshi; KS546320 -2A508 E0101; Moji_Joho; MJ056437 -2A50D E0100; Hanyo-Denshi; KS144710 -2A50D E0100; Moji_Joho; MJ057575 -2A50D E0101; Hanyo-Denshi; KS546420 -2A50D E0101; Moji_Joho; MJ056440 -2A54D E0100; Hanyo-Denshi; KS547320 -2A54D E0100; Moji_Joho; MJ056492 -2A54D E0101; Hanyo-Denshi; KS547440 -2A54D E0101; Moji_Joho; MJ056493 -2A564 E0100; Hanyo-Denshi; KS547630 -2A564 E0100; Moji_Joho; MJ056510 -2A564 E0101; Hanyo-Denshi; KS547670 -2A564 E0101; Moji_Joho; MJ056511 -2A585 E0100; Hanyo-Denshi; KS548080 -2A585 E0100; Moji_Joho; MJ056539 -2A585 E0101; Hanyo-Denshi; KS548130 -2A585 E0101; Moji_Joho; MJ056540 -2A5C7 E0100; Hanyo-Denshi; KS334620 -2A5C7 E0100; Moji_Joho; MJ056585 -2A5C7 E0101; Hanyo-Denshi; KS548980 -2A5C7 E0101; Moji_Joho; MJ056586 -2A5CD E0100; Hanyo-Denshi; KS549060 -2A5CD E0101; Hanyo-Denshi; TK01101650 -2A5F1 E0100; Adobe-Japan1; CID+19123 -2A600 E0100; Hanyo-Denshi; KS549880 -2A600 E0100; Moji_Joho; MJ056635 -2A600 E0101; Hanyo-Denshi; KS550500 -2A600 E0101; Moji_Joho; MJ056636 -2A602 E0100; Adobe-Japan1; CID+19125 -2A61A E0100; Adobe-Japan1; CID+20316 -2A61A E0101; Adobe-Japan1; CID+14280 -2A691 E0100; Hanyo-Denshi; KS551570 -2A691 E0101; Hanyo-Denshi; TK01101900 -2A695 E0100; Hanyo-Denshi; KS551630 -2A695 E0100; Moji_Joho; MJ056762 -2A695 E0101; Hanyo-Denshi; KS551680 -2A695 E0101; Moji_Joho; MJ056763 -2A696 E0100; Hanyo-Denshi; KS551640 -2A696 E0100; Moji_Joho; MJ056764 -2A696 E0101; Hanyo-Denshi; KS551690 -2A696 E0101; Moji_Joho; MJ056765 -2A699 E0100; Hanyo-Denshi; KS551720 -2A699 E0100; Moji_Joho; MJ056768 -2A699 E0101; Hanyo-Denshi; KS551730 -2A699 E0101; Moji_Joho; MJ056769 -2A6A5 E0100; Hanyo-Denshi; KS551910 -2A6A5 E0101; Hanyo-Denshi; TK01101940 -2A6AC E0100; Hanyo-Denshi; KS552090 -2A6AC E0101; Hanyo-Denshi; TK01102020 -2A6B2 E0100; Adobe-Japan1; CID+19129 -2A746 E0100; Hanyo-Denshi; JTAD6C -2A746 E0100; Moji_Joho; MJ056923 -2A746 E0101; Hanyo-Denshi; KS009630S -2A746 E0101; Moji_Joho; MJ056928 -2A813 E0100; Hanyo-Denshi; TK01012960 -2A813 E0101; Hanyo-Denshi; TK01012980 -2A9E6 E0100; Adobe-Japan1; CID+14145 -2AB03 E0100; Hanyo-Denshi; IB1867 -2AB03 E0101; Hanyo-Denshi; TK01032200 -2AB87 E0100; Hanyo-Denshi; KS138200 -2AB87 E0101; Hanyo-Denshi; TK01035430 -2AB87 E0102; Hanyo-Denshi; TK01035600 -2AC68 E0100; Hanyo-Denshi; IB0223 -2AC68 E0101; Hanyo-Denshi; TK01042360 -2AD03 E0100; Hanyo-Denshi; JTB3A0 -2AD03 E0100; Moji_Joho; MJ059743 -2AD03 E0101; Hanyo-Denshi; JTB3B0 -2AD03 E0101; Moji_Joho; MJ059747 -2AD81 E0100; Hanyo-Denshi; TK01049280 -2AD81 E0101; Hanyo-Denshi; TK01049360 -2AD89 E0100; Hanyo-Denshi; IB2224 -2AD89 E0100; Moji_Joho; MJ059779 -2AD89 E0101; Hanyo-Denshi; KS197090 -2AD89 E0101; Moji_Joho; MJ057949 -2AD89 E0102; Hanyo-Denshi; TK01049290 -2ADC2 E0100; Hanyo-Denshi; JTBA38 -2ADC2 E0100; Moji_Joho; MJ057522 -2ADC2 E0101; Hanyo-Denshi; KS207150 -2ADC2 E0101; Moji_Joho; MJ057969 -2AF19 E0100; Hanyo-Denshi; TK01059350 -2AF19 E0101; Hanyo-Denshi; TK01059480 -2AFB2 E0100; Hanyo-Denshi; JTB65C -2AFB2 E0100; Moji_Joho; MJ059939 -2AFB2 E0101; Hanyo-Denshi; KS263280 -2AFB2 E0101; Moji_Joho; MJ058172 -2B003 E0100; Hanyo-Denshi; IB2543 -2B003 E0100; Moji_Joho; MJ058200 -2B003 E0101; Hanyo-Denshi; KS275480 -2B003 E0101; Moji_Joho; MJ058203 -2B003 E0102; Hanyo-Denshi; TK01064560 -2B048 E0100; Hanyo-Denshi; JTB761 -2B048 E0100; Moji_Joho; MJ059999 -2B048 E0101; Hanyo-Denshi; KS283670 -2B048 E0101; Moji_Joho; MJ058236 -2B0E0 E0100; Hanyo-Denshi; TK01071520 -2B0E0 E0101; Hanyo-Denshi; TK01071600 -2B0EF E0100; Hanyo-Denshi; TK01072190 -2B0EF E0101; Hanyo-Denshi; TK01072410 -2B1FF E0100; Hanyo-Denshi; KS350010 -2B1FF E0101; Hanyo-Denshi; TK01077610 -2B20C E0100; Hanyo-Denshi; TK01077770 -2B20C E0101; Hanyo-Denshi; TK01078740 -2B234 E0100; Hanyo-Denshi; JTB9FA -2B234 E0101; Hanyo-Denshi; TK01078850 -2B2FE E0100; Hanyo-Denshi; KS391670 -2B2FE E0101; Hanyo-Denshi; TK01083990 -2B30F E0100; Hanyo-Denshi; TK01084160 -2B30F E0101; Hanyo-Denshi; TK01084210 -2B344 E0100; Hanyo-Denshi; KS406030 -2B344 E0101; Hanyo-Denshi; TK01085410 -2B3CF E0100; Hanyo-Denshi; KS426590 -2B3CF E0101; Hanyo-Denshi; TK01087750 -2B468 E0100; Hanyo-Denshi; JTBD9B -2B468 E0100; Moji_Joho; MJ060252 -2B468 E0101; Hanyo-Denshi; JTBD9C -2B468 E0101; Moji_Joho; MJ060253 -2B4BC E0100; Hanyo-Denshi; IB0437 -2B4BC E0100; Moji_Joho; MJ058929 -2B4BC E0101; Hanyo-Denshi; IB1023 -2B4BC E0101; Moji_Joho; MJ058928 -2B4C6 E0100; Hanyo-Denshi; JTBE3C -2B4C6 E0101; Hanyo-Denshi; TK01094240 -2B52D E0100; Hanyo-Denshi; TK01008020 -2B52D E0101; Hanyo-Denshi; TK01008030 -2B667 E0100; Hanyo-Denshi; KS523680 -2B667 E0101; Hanyo-Denshi; TK01100300 -2B741 E0100; Hanyo-Denshi; IB1305 -2B741 E0100; Moji_Joho; MJ059299 -2B741 E0101; Hanyo-Denshi; JTAD0F -2B741 E0101; Moji_Joho; MJ056830 -2B741 E0102; Hanyo-Denshi; TK01000220 -2B742 E0100; Hanyo-Denshi; IB0687 -2B742 E0100; Moji_Joho; MJ057546 -2B742 E0101; Hanyo-Denshi; KS000800 -2B742 E0101; Moji_Joho; MJ056835 -2B742 E0102; Hanyo-Denshi; KS000810 -2B742 E0102; Moji_Joho; MJ056836 -2B743 E0100; Hanyo-Denshi; JTADA4 -2B743 E0101; Hanyo-Denshi; TK01056730 -2B746 E0100; Adobe-Japan1; CID+13780 -2B746 E0101; Hanyo-Denshi; IB0610S -2B746 E0101; Moji_Joho; MJ059309 -2B746 E0102; Hanyo-Denshi; JTADCBS -2B746 E0102; Moji_Joho; MJ059340 -2B746 E0103; Hanyo-Denshi; KS004890S -2B746 E0103; Moji_Joho; MJ056904 -2B746 E0104; Hanyo-Denshi; TK01002330 -2B74C E0100; Hanyo-Denshi; JTADD5 -2B74C E0100; Moji_Joho; MJ056984 -2B74C E0101; Hanyo-Denshi; JTADD6 -2B74C E0101; Moji_Joho; MJ059345 -2B751 E0100; Adobe-Japan1; CID+13866 -2B753 E0100; Adobe-Japan1; CID+20088 -2B754 E0100; Hanyo-Denshi; IB0646 -2B754 E0101; Hanyo-Denshi; TK01006880 -2B755 E0100; Hanyo-Denshi; IB0911 -2B755 E0100; Moji_Joho; MJ058834 -2B755 E0101; Hanyo-Denshi; JTAE81 -2B755 E0101; Moji_Joho; MJ059406 -2B75A E0100; Adobe-Japan1; CID+20096 -2B75C E0100; Adobe-Japan1; CID+20097 -2B75D E0100; Hanyo-Denshi; IB0637S -2B75D E0100; Moji_Joho; MJ057394 -2B75D E0101; Hanyo-Denshi; KS051430 -2B75D E0101; Moji_Joho; MJ057200 -2B762 E0100; Hanyo-Denshi; JTAFB9 -2B762 E0100; Moji_Joho; MJ057091 -2B762 E0101; Hanyo-Denshi; JTAFBA -2B762 E0101; Moji_Joho; MJ058424 -2B762 E0102; Hanyo-Denshi; KS065970 -2B762 E0102; Moji_Joho; MJ057262 -2B762 E0103; Hanyo-Denshi; KS066060 -2B762 E0104; Moji_Joho; MJ059474 -2B763 E0100; Hanyo-Denshi; JTAFBDS -2B763 E0100; Moji_Joho; MJ058425 -2B763 E0101; Hanyo-Denshi; KS066050 -2B763 E0101; Moji_Joho; MJ057264 -2B763 E0102; Moji_Joho; MJ057266 -2B764 E0100; Hanyo-Denshi; JTAFC9 -2B764 E0101; Hanyo-Denshi; TK01019410 -2B765 E0100; Adobe-Japan1; CID+20247 -2B765 E0101; Hanyo-Denshi; TK01073620 -2B765 E0102; Hanyo-Denshi; TK01073640 -2B765 E0103; Hanyo-Denshi; TK01073660 -2B76F E0100; Moji_Joho; MJ057326 -2B76F E0101; Moji_Joho; MJ059501 -2B776 E0100; Adobe-Japan1; CID+20114 -2B776 E0101; Hanyo-Denshi; IB1783 -2B776 E0101; Moji_Joho; MJ057446 -2B776 E0102; Hanyo-Denshi; JTB0CF -2B776 E0102; Moji_Joho; MJ059555 -2B777 E0100; Adobe-Japan1; CID+13782 -2B777 E0101; Hanyo-Denshi; IB0673 -2B777 E0101; Moji_Joho; MJ057447 -2B777 E0102; Hanyo-Denshi; KS106220 -2B777 E0102; Moji_Joho; MJ057445 -2B777 E0103; Moji_Joho; MJ059556 -2B778 E0100; Hanyo-Denshi; JTB128S -2B778 E0100; Moji_Joho; MJ059587 -2B778 E0101; Hanyo-Denshi; JTB789S -2B778 E0101; Moji_Joho; MJ057482 -2B778 E0102; Hanyo-Denshi; TK01001520 -2B77C E0100; Adobe-Japan1; CID+20125 -2B782 E0100; Adobe-Japan1; CID+20141 -2B789 E0100; Adobe-Japan1; CID+14064 -2B789 E0101; Hanyo-Denshi; JTB314 -2B789 E0101; Moji_Joho; MJ057724 -2B789 E0102; Hanyo-Denshi; JTB32C -2B789 E0102; Moji_Joho; MJ059715 -2B789 E0103; Hanyo-Denshi; TK01043680 -2B789 E0104; Hanyo-Denshi; TK01044300 -2B78B E0100; Adobe-Japan1; CID+20149 -2B78E E0100; Adobe-Japan1; CID+13724 -2B78E E0101; Hanyo-Denshi; IB2148 -2B78E E0101; Moji_Joho; MJ057812 -2B78E E0102; Hanyo-Denshi; JTB37F -2B78E E0102; Moji_Joho; MJ059735 -2B78E E0103; Hanyo-Denshi; TK01045480 -2B78E E0104; Hanyo-Denshi; TK01045950 -2B78E E0105; Moji_Joho; MJ059736 -2B793 E0100; Hanyo-Denshi; JTB3E2 -2B793 E0100; Moji_Joho; MJ057896 -2B793 E0101; Hanyo-Denshi; JTB3E3 -2B793 E0101; Moji_Joho; MJ059758 -2B793 E0102; Hanyo-Denshi; JTB3E4 -2B793 E0102; Moji_Joho; MJ059759 -2B793 E0103; Hanyo-Denshi; TK01047540 -2B793 E0104; Hanyo-Denshi; TK01047560 -2B793 E0105; Hanyo-Denshi; TK01047570 -2B793 E0106; Hanyo-Denshi; TK01047580 -2B794 E0100; Adobe-Japan1; CID+20153 -2B79C E0100; Hanyo-Denshi; JTB4BCS -2B79C E0100; Moji_Joho; MJ057968 -2B79C E0101; Hanyo-Denshi; JTB4BD -2B79C E0101; Moji_Joho; MJ059829 -2B79F E0100; Hanyo-Denshi; JTB515 -2B79F E0101; Hanyo-Denshi; TK01054480 -2B7AA E0100; Hanyo-Denshi; IB0757 -2B7AA E0101; Hanyo-Denshi; TK01060130 -2B7AC E0100; Adobe-Japan1; CID+20176 -2B7AF E0100; Adobe-Japan1; CID+20180 -2B7B4 E0100; Hanyo-Denshi; JTB6D8 -2B7B4 E0101; Hanyo-Denshi; KS276070 -2B7B4 E0102; Hanyo-Denshi; KS276370 -2B7B9 E0100; Hanyo-Denshi; JTB76B -2B7B9 E0100; Moji_Joho; MJ060003 -2B7B9 E0101; Hanyo-Denshi; JTB76C -2B7B9 E0101; Moji_Joho; MJ058240 -2B7B9 E0102; Hanyo-Denshi; KS284520 -2B7B9 E0102; Moji_Joho; MJ058241 -2B7BD E0100; Adobe-Japan1; CID+14174 -2B7C0 E0100; Hanyo-Denshi; JTC0F4 -2B7C0 E0101; Hanyo-Denshi; TK01071070 -2B7C8 E0100; Hanyo-Denshi; IB0853 -2B7C8 E0100; Moji_Joho; MJ058345 -2B7C8 E0101; Hanyo-Denshi; JTB87C -2B7C8 E0101; Moji_Joho; MJ060062 -2B7C8 E0102; Hanyo-Denshi; TK01073420 -2B7C9 E0100; Adobe-Japan1; CID+20194 -2B7CB E0100; Hanyo-Denshi; JTB8FF -2B7CB E0100; Moji_Joho; MJ060089 -2B7CB E0101; Hanyo-Denshi; JTB900 -2B7CB E0101; Moji_Joho; MJ060090 -2B7CB E0102; Hanyo-Denshi; KS337260 -2B7CB E0102; Moji_Joho; MJ021335 -2B7CC E0100; Hanyo-Denshi; JTB94A -2B7CC E0101; Hanyo-Denshi; TK01076780 -2B7CD E0100; Hanyo-Denshi; JTB945 -2B7CD E0100; Moji_Joho; MJ058443 -2B7CD E0101; Hanyo-Denshi; JTB947 -2B7CD E0101; Moji_Joho; MJ060099 -2B7CF E0100; Adobe-Japan1; CID+20201 -2B7CF E0101; Hanyo-Denshi; JTB989 -2B7CF E0101; Moji_Joho; MJ058460 -2B7CF E0102; Hanyo-Denshi; JTB9B5 -2B7CF E0102; Moji_Joho; MJ022123 -2B7D0 E0100; Hanyo-Denshi; JTB98A -2B7D0 E0101; Hanyo-Denshi; TK01078320 -2B7D2 E0100; Adobe-Japan1; CID+20204 -2B7D2 E0101; Hanyo-Denshi; JTB9D9 -2B7D2 E0101; Moji_Joho; MJ058491 -2B7D2 E0102; Hanyo-Denshi; KS353130 -2B7D2 E0102; Moji_Joho; MJ058495 -2B7D2 E0103; Hanyo-Denshi; TK01044160 -2B7D2 E0104; Hanyo-Denshi; TK01078950 -2B7D2 E0105; Hanyo-Denshi; TK01079760 -2B7D6 E0100; Hanyo-Denshi; JTBA55 -2B7D6 E0101; Hanyo-Denshi; TK01080560 -2B7D6 E0102; Hanyo-Denshi; TK01080910 -2B7D8 E0100; Adobe-Japan1; CID+13651 -2B7D8 E0101; Moji_Joho; MJ058683 -2B7D8 E0102; Moji_Joho; MJ060164 -2B7D9 E0100; Hanyo-Denshi; IB0883 -2B7D9 E0101; Hanyo-Denshi; JTBAFE -2B7E8 E0100; Hanyo-Denshi; JTBCD1 -2B7E8 E0101; Hanyo-Denshi; TK01089270 -2B7EA E0100; Hanyo-Denshi; JTBD4F -2B7EA E0100; Moji_Joho; MJ060241 -2B7EA E0101; Hanyo-Denshi; JTBD50S -2B7EA E0101; Moji_Joho; MJ060242 -2B7EA E0102; Hanyo-Denshi; KS444550 -2B7EA E0102; Moji_Joho; MJ058869 -2B7EF E0100; Hanyo-Denshi; IB1022 -2B7EF E0101; Hanyo-Denshi; TK01001570 -2B7F0 E0100; Adobe-Japan1; CID+20240 -2B80D E0100; Adobe-Japan1; CID+20256 -2B817 E0100; Adobe-Japan1; CID+20260 -2B81A E0100; Adobe-Japan1; CID+14278 -2B81D E0100; Hanyo-Denshi; JTC0B0 -2B81D E0101; Hanyo-Denshi; TK01102050 -# EOF diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog deleted file mode 100644 index 1dfda079bf2..00000000000 --- a/doc/emacs/ChangeLog +++ /dev/null @@ -1,10693 +0,0 @@ -2014-10-20 Glenn Morris - - * Version 24.4 released. - -2014-10-13 Glenn Morris - - * Makefile.in (dist): Update for new output variables. - -2014-10-06 Glenn Morris - - * package.texi (Package Menu): The package list was changed to not - say "unsigned" any more. - -2014-10-04 Glenn Morris - - * misc.texi (Sorting): - * search.texi (Query Replace): Markup fixes. - - * cmdargs.texi (Misc X): - * display.texi (Optional Mode Line): - * misc.texi (emacsclient Options): - * vc1-xtra.texi (VC Delete/Rename): Small fixes re @var usage. - - * killing.texi (Rectangles): Copyedits re rectangle-mark-mode. - (CUA Bindings): Mention rectangle-mark-mode. - -2014-10-03 Martin Rudalics - - * frames.texi (Frame Commands): - * cmdargs.texi (Window Size X): Mention the use of - `frame-resize-pixelwise' to make frames truly fullscreen or - maximized. - -2014-10-01 Glenn Morris - - * package.texi (Package Installation): Mention etc/package-keyring.gpg. - -2014-07-21 Glenn Morris - - * emacs.texi (Intro): Workaround makeinfo 4 @acronym bug. (Bug#18040) - -2014-07-03 Juri Linkov - - * search.texi (Regexp Search): Update lax space matching that is - not active in regexp search by default now. (Bug#17901) - -2014-06-29 Glenn Morris - - * help.texi (Misc Help): - * trouble.texi (Checklist): "Online" help doesn't mean what it - used to any more. - -2014-06-08 Glenn Morris - - * entering.texi (Entering Emacs): Small fix re initial-buffer-choice. - * misc.texi (emacsclient Options): Copyedit. - - * buffers.texi (Uniquify): Copyedits. - * files.texi (Visiting): Update for uniquify changes. - - * dired.texi (Marks vs Flags): - * rmail.texi (Rmail Scrolling): Markup fixes re SPC. - - * help.texi (Help, Misc Help): Copyedits. - - * screen.texi (Menu Bar): Copyedits. - * msdog.texi (Windows Keyboard): F10 menus are now a general feature. - - * frames.texi (Frame Commands): Copyedits re M-F10, F11. - * cmdargs.texi (Window Size X): Copyedits. - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Updates. - -2014-06-07 Glenn Morris - - * programs.texi (Prettifying Symbols): Remove node. - (Misc for Programs): Mention more briefly here. - * emacs.texi (Top): Update menu. - -2014-06-05 Glenn Morris - - * package.texi (Package Menu, Package Installation): - Mention signed packages. - -2014-06-03 Glenn Morris - - * package.texi (Package Installation): Mention package-pinned-packages. - -2014-06-02 Glenn Morris - - * misc.texi [iftex]: Update chapter summary. - (Emulation): Remove ludicrously outdated claim. - -2014-05-29 Glenn Morris - - * macos.texi (Mac / GNUstep Customization): Mention ns custom group. - (Customization options specific to Mac OS / GNUstep): Remove section. - -2014-05-28 Glenn Morris - - * macos.texi (Mac / GNUstep Customization): Mention some new features. - -2014-05-27 Glenn Morris - - * abbrevs.texi (Expanding Abbrevs): Update re abbrev-expand-function. - -2014-05-21 Eli Zaretskii - - * frames.texi (Fonts): Clarify which frames are affected by - setting font from the menu and in default-frame-alist. - (Bug#17532) - -2014-05-12 Eli Zaretskii - - * mule.texi (Language Environments): Remove unused @anchor. - (Bug#17479) - -2014-05-02 Eli Zaretskii - - * trouble.texi (Lossage, DEL Does Not Delete, Stuck Recursive) - (Screen Garbled, Text Garbled, After a Crash, Emergency Escape) - (Bug Criteria, Understanding Bug Reporting, Checklist, Service): - Improve indexing. - -2014-04-29 Eli Zaretskii - - * trouble.texi (Quitting, DEL Does Not Delete, Emergency Escape) - (Bug Criteria): Fix usage of @kbd and @key. (Bug#17362) - - * text.texi (Words, Pages, Foldout, HTML Mode): Fix usage of @kbd - and @key. - - * search.texi (Special Isearch, Regexp Search): Fix usage of @kbd - and @key. - - * screen.texi (Echo Area, Menu Bar): Fix usage of @kbd and @key. - - * rmail.texi (Rmail Scrolling): Fix usage of @kbd and @key. - - * programs.texi (Hungry Delete, Other C Commands): Fix usage of - @kbd and @key. - - * picture-xtra.texi (Insert in Picture): Fix usage of @kbd and - @key. - - * mule.texi (Unibyte Mode, Bidirectional Editing): Fix usage of - @kbd and @key. - - * msdog.texi (Windows Keyboard, Windows Processes): Fix usage of - @kbd and @key. - - * msdog-xtra.texi (MS-DOS Keyboard, MS-DOS Printing) - (MS-DOS Processes): Fix usage of @kbd and @key. - - * misc.texi (Shell Ring, Printing Package): Fix usage of @kbd and - @key. - - * mini.texi (Completion Commands, Minibuffer History): Fix usage - of @kbd and @key. - - * kmacro.texi (Keyboard Macro Step-Edit): Fix usage of @kbd and - @key. - - * killing.texi (Deletion, Rectangles, CUA Bindings): Fix usage of - @kbd and @key. - - * indent.texi (Indentation Commands): Fix usage of @kbd and @key. - - * help.texi (Help Mode, Misc Help): Fix usage of @kbd and @key. - - * glossary.texi (Glossary): Fix usage of @kbd and @key. - - * frames.texi (Speedbar): Fix usage of @kbd and @key. - - * files.texi (Misc File Ops, File Name Cache, File Conveniences) - (Filesets): Fix usage of @kbd and @key. - - * display.texi (View Mode): Fix usage of @kbd and @key. - - * dired.texi (Image-Dired): Fix usage of @kbd and @key. - - * custom.texi (Modifier Keys, Function Keys, Named ASCII Chars) - (Init Syntax): Fix usage of @kbd and @key. - - * commands.texi (User Input): Fix usage of @kbd and @key. - - * calendar.texi (Counting Days, General Calendar): Fix usage of - @kbd and @key. - - * building.texi (Threads Buffer): Fix usage of @kbd and @key. - - * buffers.texi (Select Buffer, Icomplete): Fix usage of @kbd and - @key. - - * basic.texi (Inserting Text, Erasing, Arguments): Fix usage of - @kbd and @key. - - * anti.texi (Antinews): Fix usage of @kbd and @key. - -2014-04-26 Eli Zaretskii - - * sending.texi (Mail Signature): Document signature variables used - by Message mode. (Bug#17308) - -2014-04-21 Eli Zaretskii - - * buffers.texi (Uniquify): Clarify the default uniquification. - - * indent.texi (Tab Stops): Improve wording. - - * cmdargs.texi (General Variables): Improve docs of - EMACSLOADPATH. Index all the environment variables. - (Misc Variables): Index all the environment variables. - -2014-04-13 Eli Zaretskii - - * display.texi (Cursor Display): Explain better how to customize - 'blink-cursor-blinks'. - -2014-04-05 Glenn Morris - - * trouble.texi (Checklist): Dribble files may contain passwords. - -2014-04-04 Glenn Morris - - * files.texi (Backup Names): - * arevert-xtra.texi (Supporting additional buffers): - Update for default values of some -function vars no longer being nil. - (Supporting additional buffers): - Update for buffer-stale-function also applying to file-buffers. - -2014-03-16 Dmitry Gutov - - * programs.texi (Matching): Update the missed spot. (Bug#17008) - -2014-03-15 Dmitry Gutov - - * programs.texi (Matching): Update WRT to the new - `blink-matching-paren' behavior. - -2014-03-13 Paul Eggert - - * mule.texi (International, Language Environments): Update - the list of language environments to what Emacs currently - supports. Add the full list to the index. Suggest C-h L for - details rather than trying to give very brief details here. - -2014-03-12 Glenn Morris - - * cmdargs.texi (General Variables): Don't mention INCPATH, - from the obsolete complete.el. - -2014-03-12 Paul Eggert - - * mule.texi (International Chars): Adjust C-u C-x = description. - Change it to match Emacs's current behavior. Also, change the - example to use ê instead of À, as the isolated grave accent in the - latter's decomposition listing was confusingly transliterated to - left single quote in the PDF version of the manual. - -2014-03-12 Glenn Morris - - * misc.texi (Saving Emacs Sessions): Be briefer about desktop's - handling of frames. - - * indent.texi (Indent Convenience): Mention electric-indent-local-mode. - -2014-03-02 Xue Fuqiao - - * mark.texi (Mark): - * killing.texi (Rectangles): Document `rectangle-mark-mode'. - -2014-03-01 Glenn Morris - - * search.texi (Query Replace): Mention search-invisible. - * text.texi (Outline Visibility): Mention search-invisible - also affects query-replace. - -2014-02-28 Xue Fuqiao - - * emacs.texi (Top): - * programs.texi (Programs, Prettifying Symbols): - Document `prettify-symbols-mode' and `global-prettify-symbols-mode'. - - * misc.texi (Saving Emacs Sessions): - Document some new desktop user options. - -2014-02-27 Xue Fuqiao - - * programs.texi (Basic Indent, Other C Commands): - Fix the description of RET and `C-j'. - - * indent.texi (Indentation Commands): Move the description of - `C-j' from here... - * basic.texi (Inserting Text): ... to here. - -2014-02-25 Glenn Morris - - * custom.texi (Terminal Init): - Replace term-setup-hook with tty-setup-hook. - -2014-02-23 Glenn Morris - - * rmail.texi (Rmail Inbox): Mention rmail-mbox-format. - -2014-02-20 Glenn Morris - - * search.texi (Special Isearch): Mention invisible text. - * text.texi (Outline Visibility): Mention `M-s i' in isearch. - -2014-02-18 Glenn Morris - - * trouble.texi (Contributing) [WWW_GNU_ORG]: Link to - gnu.org version of etc/CONTRIBUTE in html output. - - * misc.texi (Saving Emacs Sessions): Mention desktop-auto-save-timeout. - -2014-02-17 Stefan Monnier - - * programs.texi (Matching): Fix typo. - - * killing.texi (CUA Bindings): Document the new relationship between - cua-mode and delete-selection mode. - (CUA Bindings): Mention that rectangle mode can be used on its own. - -2014-02-14 Glenn Morris - - * regs.texi (Configuration Registers): Update C-x r f binding. - -2014-02-12 Glenn Morris - - * mini.texi (Completion Options): No longer mention icomplete, - which has its own section now. - * modes.texi (Minor Modes): Update Icomplete xref. - - * help.texi (Package Keywords): Mention describe-package buttons. - - * package.texi (Package Menu): Mention package-menu-filter. - -2014-02-11 Lars Ingebrigtsen - - * text.texi (Editing Format Info): Use @samp for menus (bug#13736). - -2014-02-09 Lars Ingebrigtsen - - * dired.texi (Hiding Subdirectories): Mention the node for - deleting subdirectories (bug#11743). - -2014-02-09 Glenn Morris - - * programs.texi (MixedCase Words): Rename node from "Glasses". - Move Subword mode here from "Other C Commands" node. - (Misc for Programs): Mention Superword mode. - * emacs.texi: Update menu. - -2014-02-08 Lars Ingebrigtsen - - * regs.texi (File Registers): Clarify metasyntactical variables - (bug#13565). - - * search.texi (Search Case): Rearrange text slightly to make it - obvious that `M-c' also toggles sensitivity if `case-fold-search' - is nil (bug#14726). - - * frames.texi (Mouse Commands): Clarify `mouse-yank-at-click' - (bug#16376). - -2014-02-07 Glenn Morris - - * display.texi (Highlight Interactively): - Mention hi-lock-auto-select-face. - - * anti.texi (Antinews): Fix typo. - - * ack.texi (Acknowledgments): No longer mention obsolete files. - -2014-02-02 Glenn Morris - - * regs.texi (Registers): Mention previewing. - -2014-01-29 Glenn Morris - - * killing.texi (Deletion): Mention cycle-spacing. - -2014-01-28 Glenn Morris - - * text.texi (Fill Commands): Mention fill-single-char-nobreak-p. - - * indent.texi (Tab Stops): Updates for new tab-stop behavior. - -2014-01-27 Glenn Morris - - * dired.texi (Misc Dired Features): Copyedits for hide-details. - - * buffers.texi (List Buffers): Tiny edit. - - * calendar.texi (Time Intervals): Update for files in ~/.emacs.d/. - -2014-01-26 Glenn Morris - - * ack.texi (Acknowledgments): - * programs.texi (Program Modes): - Update for delphi.el -> opascal.el renaming. - - * misc.texi (Sorting): Add findex for reverse-region. - - * killing.texi (Deletion): Mention delete-duplicate-lines. - -2014-01-24 Glenn Morris - - * ack.texi (Acknowledgments): No longer mention obsolete xesam.el, - terminal.el. - - * files.texi (Interlocking): Copyedit. - -2014-01-23 Glenn Morris - - * building.texi (Lisp Eval): Update prefix argument behavior - of eval-expression, eval-last-sexp. - -2014-01-17 Bastien Guerry - - * building.texi (Commands of GUD): Fix keybinding for `gud-break'. - -2014-01-15 Glenn Morris - - * files.texi (File Conveniences): - * misc.texi (EWW): Copyedits. - -2014-01-10 Glenn Morris - - * emacs.texi (Distrib): Add donate URL. Add anchor. - -2014-01-10 Rüdiger Sonderfeld - - * dired.texi (Misc Dired Features): Document `dired-hide-details-mode', - `dired-hide-details-hide-symlink-targets', and - `dired-hide-details-hide-information-lines'. - -2014-01-09 Rüdiger Sonderfeld - - * emacs.texi: Add EWW. - * misc.texi (EWW): Document EWW. - -2014-01-09 Glenn Morris - - * trouble.texi (Service): Refer to online service directory - rather than etc/SERVICE. - -2014-01-09 Rüdiger Sonderfeld - - * building.texi (Lisp Libraries): Document `load-prefer-newer'. - - * files.texi (File Conveniences): Document `image-next-frame', - `image-previous-frame', `image-goto-frame', - `image-increase-speed', `image-decrease-speed', - `image-reverse-speed', and `image-reset-speed'. - -2014-01-07 Bastien Guerry - - * buffers.texi (Buffers): Fix display of @math content by using - nested braces. (Bug#16389) - -2014-01-07 Chong Yidong - - * search.texi (Special Isearch): Document C-x 8 RET in isearch. - (Word Search): Document incremental word search changes. - (Isearch Yank): Document M-s C-e with a prefix argument. - -2014-01-07 Glenn Morris - - * cal-xtra.texi (Calendar Customizing): - Mention calendar-day-header-array. - -2013-12-28 Glenn Morris - - * trouble.texi (Understanding Bug Reporting): Brevity. - -2013-12-27 Jarek Czekalski - - * mini.texi (Completion Options): Add a link to Shell Options. - * misc.texi (Shell Mode): Move documentation of - shell-completion-fignore from Shell Mode to Shell Options. - -2013-12-26 João Távora - - * emacs.texi (Matching): Describe new features of Electric Pair mode. - -2013-12-25 Chong Yidong - - * glossary.texi (Glossary): Define MULE in modern terms. - -2013-12-25 Xue Fuqiao - - * files.texi (Diff Mode): Add an index. - -2013-12-24 Xue Fuqiao - - * trouble.texi (Understanding Bug Reporting): Minor update. - (Checklist): Fix a cross-reference. - -2013-12-23 Xue Fuqiao - - * regs.texi (Bookmarks): Document `bookmark-default-file'. - - * misc.texi (Shell Mode): Add a cross-reference. - - * building.texi (Lisp Eval): Add an index. - -2013-12-22 Glenn Morris - - * entering.texi (Entering Emacs): Typo fix. - - * calendar.texi (General Calendar): - * rmail.texi (Rmail Scrolling): Use itemx where appropriate. - -2013-12-22 Eli Zaretskii - - * regs.texi (Keyboard Macro Registers): Fix last change. - -2013-12-22 Xue Fuqiao - - * search.texi (Special Isearch, Query Replace): Document negative - argument of replacement commands. - (Symbol Search): Document `isearch-forward-symbol-at-point'. - - * files.texi (File Conveniences): Document `image-next-file' and - `image-previous-file'. - - * display.texi (Optional Mode Line): Fix an index. - - * regs.texi (File Registers): Document `kmacro-to-register'. - - * indent.texi (Tab Stops): Mention recent changes about `tab-stop-list'. - - * frames.texi (Scroll Bars): Document - `scroll-bar-adjust-thumb-portion'. - -2013-12-21 Chong Yidong - - * indent.texi (Indentation Commands): Document C-x TAB changes. - -2013-12-20 Tassilo Horn - - * calendar.texi, display.texi, help.texi, rmail.texi: - Document `S-SPC' as alternative to scrolling down with `DEL'. - - * frames.texi: Document `toggle-frame-maximized' and - `toggle-frame-fullscreen' with their respective keys. - - * buffers.texi: Document buffer name uniquification changes. - - * indent.texi: Document that `electric-indent-mode' is enabled by - default. - - * display.texi (Cursor Display): Document `blink-cursor-blinks'. - - * buffers.texi: Update list-buffers "screenshot" to show Messages - as major-mode. - - * entering.texi: Document `initial-buffer-choice' changes. - - * misc.texi (emacsclient Options): Document - `initial-buffer-choice' changes. - - * help.texi: Document that `?' now also shows subcommands of - prefix keys. - -2013-12-17 Chong Yidong - - * killing.texi (Appending Kills): Note that append-next-kill can - prepend the kill. - -2013-12-12 Eli Zaretskii - - * mule.texi (File Name Coding): Document file-name encoding - peculiarities on MS-Windows. - -2013-12-12 Glenn Morris - - * emacs.texi: Sync direntry with info/dir version. - -2013-12-08 Juanma Barranquero - - * msdog.texi (Windows Keyboard): Fix typo. - -2013-11-30 Glenn Morris - - * Makefile.in (distclean): Remove Makefile. - -2013-11-29 Stefan Monnier - - * buffers.texi (Icomplete): Rename from Iswitchb and - rewrite accordingly. - -2013-11-23 Glenn Morris - - * cmdargs.texi (General Variables): - Empty elements in EMACSLOADPATH now mean the default load-path. - -2013-11-21 Glenn Morris - - * cmdargs.texi (Action Arguments): Use path-separator with -L. - -2013-11-04 Glenn Morris - - * cmdargs.texi (Action Arguments): Mention that `-L :...' appends. - -2013-11-02 Glenn Morris - - * cmdargs.texi (Action Arguments): Clarify `-L' a bit. - -2013-10-23 Glenn Morris - - * files.texi, glossary.texi, killing.texi, search.texi, sending.texi: - Nuke @refill. - - * Makefile.in (install-dvi, install-html, install-pdf) - (install-ps, uninstall-dvi, uninstall-html, uninstall-ps) - (uninstall-pdf): Quote entities that might contain whitespace. - -2013-10-20 Xue Fuqiao - - * custom.texi (Init Syntax, Terminal Init, Terminal Init): - Remove @refill. - -2013-10-13 Glenn Morris - - * ack.texi (Acknowledgments): Comment out old alpha stuff. - -2013-10-13 Xue Fuqiao - - * calendar.texi (Special Diary Entries): Remove @refill. - -2013-10-13 Glenn Morris - - * display.texi (Text Scale): Update text-scale-adjust details. - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Use accented form of some names. - -2013-10-08 Eli Zaretskii - - * ack.texi (Acknowledgments): Fix spelling of Hrvoje Nikšić's - name. (Bug#15557) - - Support menus on text-mode terminals. - * screen.texi (Menu Bar): Adapt to TTY menus. - - * frames.texi (Frames): Mention menu support on text terminals. - - * files.texi (Visiting): Mention the "File" menu-bar menu. - - * display.texi (Standard Faces): Mention TTY faces for menus. - -2013-10-06 Xue Fuqiao - - * cal-xtra.texi (Calendar Customizing, Diary Display): Remove @refill. - -2013-09-29 Xue Fuqiao - - * fortran-xtra.texi (Fortran Abbrev): Remove @refill. - -2013-09-26 Xue Fuqiao - - * dired.texi (Flagging Many Files): Use @emph instead of @strong. - - * emacs.texi (Intro): Minor cleanup. - -2013-09-22 Xue Fuqiao - - * fixit.texi (Transpose, Fixing Case): Remove @refill. - -2013-09-21 Xue Fuqiao - - * maintaining.texi (VC Directory Commands): Add keybinding for - vc-log-incoming in vc-dir. - (Log Buffer): Use @emph instead of @strong. - -2013-09-12 Xue Fuqiao - - * text.texi (Enriched Justification): Explain values of default-justification. - -2013-09-04 Xue Fuqiao - - * maintaining.texi (VC Ignore): Mention `vc-ignore' with prefix argument. - -2013-08-31 Ulrich Müller - - * xresources.texi (Motif Resources): - Rename from LessTif Resources. Update xrefs. (Bug#15145) - * emacs.texi: Update menu. - -2013-08-28 Paul Eggert - - * Makefile.in (SHELL): Now @SHELL@, not /bin/sh, - for portability to hosts where /bin/sh has problems. - -2013-08-17 Xue Fuqiao - - * text.texi (Enriched Justification): Minor fixes. - -2013-08-14 Xue Fuqiao - - * files.texi (Filesets): Add an index. - -2013-08-12 Glenn Morris - - * macos.texi (GNUstep Support): - * trouble.texi (Checklist, Contributing, Service): - Avoid mailto: in html output. - - * Makefile.in (prefix, datarootdir, datadir, PACKAGE_TARNAME) - (docdir, dvidir, htmldir, pdfdir, psdir, GZIP_PROG, INSTALL) - (INSTALL_DATA): New, set by configure. - (HTML_OPTS, DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS): - New variables. - (.SUFFIXES): Add .ps and .dvi. - (.dvi.ps): New suffix rule. - (dvi, html, pdf, ps): Use *_TARGETS variables. - (emacs.ps, emacs-xtra.ps): Remove explicit rules. - (emacs.html): Use HTML_OPTS. - (clean): Use DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS. - (.PHONY): install-dvi, install-html, install-pdf, install-ps, - install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, - uninstall-ps, and uninstall-doc. - (install-dvi, install-html, install-pdf, install-ps, install-doc) - (uninstall-dvi, uninstall-html, uninstall-ps, uninstall-pdf) - (uninstall-doc): New rules. - -2013-07-31 Eli Zaretskii - - * emacs.texi (Top): Remove menu item for the removed "Disabling - Multibyte" node. - -2013-07-31 Xue Fuqiao - - * rmail.texi (Rmail Coding): Move here from mule.texi. - - * custom.texi (Specifying File Variables): Fix cross-references. - - * mule.texi (Unibyte Mode): Fix cross-references. - (Disabling Multibyte): Remove. - - * macos.texi (Mac / GNUstep Basics): Mention `ns-alternate-modifier'. - - * cal-xtra.texi (Advanced Calendar/Diary Usage): Update menu. - (Mayan Calendar): Move here from calendar.texi. - * emacs.texi (Top): Update menu. - -2013-07-30 Xue Fuqiao - - * emacs.texi (Top): Add menu entry. - - * maintaining.texi (VC Ignore): New node. Document vc-ignore. - (VC Directory Commands): Add vc-dir-ignore. - -2013-07-28 Xue Fuqiao - - * glossary.texi (Glossary): Add some entries. - -2013-07-27 Xue Fuqiao - - * maintaining.texi (VC Directory Commands): Mention `D' and `L' in - vc-dir. (Bug#14948) - -2013-07-26 Eli Zaretskii - - * display.texi (Fringes): Document the variable fringe-mode. - (Bug#14946) - -2013-07-03 Glenn Morris - - * maintaining.texi (EDE): Fix cross-reference. - - * programs.texi (Program Modes): Fix emacs-xtra reference. - - * help.texi (Misc Help): Index describe-syntax. - -2013-06-29 Eli Zaretskii - - * basic.texi (Moving Point): Document visual-order-cursor-movement - and its effect on right-char and left-char. - -2013-06-28 Glenn Morris - - * ack.texi (Acknowledgments): Small update. - -2013-06-19 Glenn Morris - - * Makefile.in (dist): Edit more configure variables. - Try to check that we do not miss any in future. - -2013-06-12 Xue Fuqiao - - * vc1-xtra.texi (Revision Tags): Add a cross reference. - (CVS Options): Fix the default value of `vc-cvs-stay-local'. - -2013-06-11 Glenn Morris - - * maintaining.texi (VC Directory Commands): Copyedit. - (Branches): Put back milder version of pre 2013-06-07 text. - -2013-06-07 Xue Fuqiao - - * maintaining.texi (Branches): Remove text copied from other sources. - -2013-06-05 Alan Mackenzie - - * search.texi (Isearch Scroll): Rename to "Not Exiting Isearch". - (Not Exiting Isearch): Document new user option - `isearch-allow-prefix'. (Bug#9706) - -2013-06-03 Juri Linkov - - * display.texi (Highlight Interactively): Add global keybindings - with the key prefix `M-s h'. Document old command `highlight-phrase'. - Document new command `highlight-symbol-at-point'. - -2013-06-02 Xue Fuqiao - - * maintaining.texi (Branches): Add motivations for branching. - (VC Mode Line): Fix typo. - (VC Directory Commands): Mention `vc-dir-hide-up-to-date' with - prefix argument. - -2013-06-02 Michael Albinus - - * cmdargs.texi (General Variables): Use "unix:path=/dev/null" as - dummy value for $DBUS_SESSION_BUS_ADDRESS. It also suppresses - autolaunching of the D-Bus session bus. - -2013-06-01 Glenn Morris - - * programs.texi (Semantic): Fix typo. - -2013-05-30 Xue Fuqiao - - * maintaining.texi (Types of Log File): Supplement some - information of change log files. - -2013-05-15 Juri Linkov - - * search.texi (Repeat Isearch): Mention key `RET' to finish - editing the string. (Bug#13348) - -2013-05-14 Glenn Morris - - * ack.texi (Acknowledgments): Don't mention obsolete sup-mouse.el. - -2013-05-09 Glenn Morris - - * sending.texi (Mail Sending): Fix typo. - - * windows.texi (Change Window): Fix typo. - - * custom.texi (Changing a Variable): Fix typo. - - * trouble.texi (Contributing): Remove obsolete info re pretesters. - -2013-05-05 Paul Eggert - - `write-region-inhibit-fsync' defaults to noninteractive (Bug#14273). - * cmdargs.texi (Initial Options): - * files.texi (Customize Save): Document this. - -2013-05-04 Glenn Morris - - * calendar.texi (Importing Diary): Mention diary-from-outlook-function. - -2013-03-17 Paul Eggert - - doc: convert some TeX accents to UTF-8 - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): - Convert some TeX accents (e.g., '@l{}') to UTF-8 (e.g., 'ł'). - Apparently the TeX accents cause problems when generating gnu.org - web pages, e.g., @l{} is rendered as '/l' on - . - -2013-03-16 Glenn Morris - - * emacs.texi (Top): Add some stuff specific to www.gnu.org. - -2013-03-04 Paul Eggert - - Prefer UTF-8 for documentation. - With GNU Texinfo 5.0, this generates nicer-looking info files, - since they can use curly quotes. With older Texinfo it doesn't matter. - * ack.texi, cal-xtra.texi, calendar.texi, emacs-xtra.texi, emacs.texi: - Switch from Latin-1 to UTF-8. - -2013-02-28 Bastien Guerry - - * xresources.texi (GTK resources): Fix broken link. - -2013-02-25 Eli Zaretskii - - * files.texi (Interlocking): Don't refer to symlinks as the - exclusive means of locking files. - -2013-02-22 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Small updates. - -2013-02-21 Glenn Morris - - * files.texi (File Conveniences): Not just GIFs can be animated. - -2013-02-13 Glenn Morris - - * ack.texi (Acknowledgments): Don't mention yow any more. - -2013-02-13 Paul Eggert - - * cmdargs.texi (General Variables): - Fix TMPDIR documentation to match the code's behavior. - -2013-02-10 Glenn Morris - - * trouble.texi (Checklist): Update bug keybinding. - -2013-02-09 Eli Zaretskii - - * msdog.texi (Text and Binary): Delete the description of - file-name-buffer-file-type-alist. - -2013-01-19 Paul Eggert - - * trouble.texi (Crashing): Suggest -p for newer addr2line. (Bug#13445) - Without it, I don't see function names. Older addr2line - implementations will die out sooner or later, so tailor the - first suggestion to recent addr2line, with a followup about - older ones. - -2013-01-19 Glenn Morris - - * custom.texi (Directory Variables): Fix paren typo. - - * trouble.texi (Crashing): Not all addr2line have -p. (Bug#13445) - - * custom.texi (Custom Themes): Fix typo. - -2013-01-07 Bastien Guerry - - * help.texi (Apropos): Document `apropos-user-option' and update - the doc for `apropos-variable'. - -2013-01-05 Glenn Morris - - * text.texi (HTML Mode): Remove deleted nxml C-RET binding. - -2012-12-21 Glenn Morris - - * emacs-xtra.texi (copying): The FSF does not sell copies of this. - Simply include doclicense. - -2012-12-21 Chong Yidong - - * frames.texi (Mouse Commands): Fix description of the effect of - mouse dragging (Bug#13049). - -2012-12-15 Juri Linkov - - * misc.texi (Recursive Edit): Add a link to "Query Replace". - (Bug#13181) - -2012-12-10 Dani Moncayo - - * killing.texi (Deletion): Doc fix (Bug#12748). - -2012-12-06 Paul Eggert - - * doclicense.texi, gpl.texi: Update to latest version from FSF. - These are just minor editorial changes. - -2012-12-06 Juanma Barranquero - - * vc1-xtra.texi (General VC Options): Remove obsolete reference - to `vc-path'. - -2012-12-03 Chong Yidong - - * custom.texi (Init Rebinding): kbd is now a function (Bug#13052). - -2012-12-02 Kevin Ryde - - * maintaining.texi (Tag Syntax): Mention (defvar foo) handling. - -2012-12-01 Kevin Ryde - - * maintaining.texi (Tag Syntax): Mention Perl's "use constant". - -2012-11-24 Paul Eggert - - * doclicense.texi, gpl.texi: Update to latest version from FSF. - These are just minor editorial changes. - -2012-11-21 Dani Moncayo - - * display.texi (Auto Scrolling): Fix some inaccuracies, plus - clarifications (Bug#12865). - (Horizontal Scrolling): Clarifications. - -2012-11-18 Dani Moncayo - - * mark.texi (Disabled Transient Mark): Doc fixes (Bug#12746). - -2012-11-16 Eli Zaretskii - - * trouble.texi (Crashing): Add information about MS-Windows and - the emacs_backtrace.txt file. (Bug#12908) - -2012-11-13 Chong Yidong - - * building.texi (Multithreaded Debugging): gdb-stopped-hooks is - actually named gdb-stopped-functions. - -2012-11-13 Glenn Morris - - * misc.texi (Single Shell): Mention async-shell-command-buffer. - -2012-11-10 Glenn Morris - - * misc.texi (Terminal emulator): Rename `term-face' to `term'. - - * emacs.texi (Acknowledgments): Add profiler author. - * ack.texi (Acknowledgments): Add some recent contributions. - -2012-11-10 Chong Yidong - - * files.texi (Diff Mode): Doc fixes for - diff-delete-trailing-whitespace (Bug#12831). - - * trouble.texi (Crashing): Copyedits. - -2012-11-10 Glenn Morris - - * files.texi (Diff Mode): Trailing whitespace updates. - -2012-11-10 Chong Yidong - - * misc.texi (Terminal emulator): Document Term mode faces. - - * mini.texi (Basic Minibuffer): New node. Document - minibuffer-electric-default-mode. - - * display.texi (Visual Line Mode): Fix index entry. - - * buffers.texi (Several Buffers): List Buffer Menu command anmes, - and index the keybindings. Document tabulated-list-sort. - (Kill Buffer): Capitalize Buffer Menu. - - * trouble.texi (Memory Full): Capitalize Buffer Menu. - -2012-11-10 Eli Zaretskii - - * display.texi (Auto Scrolling): Clarify that scroll-step is - ignored when scroll-conservatively is set to a non-zero value. - (Bug#12801) - -2012-11-10 Chong Yidong - - * dired.texi (Dired Updating): Doc fix (Bug#11744). - -2012-10-30 Michael Albinus - - * trouble.texi (Known Problems): Mention command `debbugs-gnu-usertags'. - -2012-10-29 Chong Yidong - - * dired.texi (Shell Commands in Dired): Document changes to the - dired-do-async-shell-command. - -2012-10-28 Glenn Morris - - * ack.texi (Acknowledgments): Mention gv.el. - -2012-10-27 Bastien Guerry - - * screen.texi (Menu Bar): Fix typo. - -2012-10-27 Chong Yidong - - * frames.texi (Mouse Avoidance): Mention new variable - mouse-avoidance-banish-position. - - * programs.texi (Which Function): Which Function mode now works in - all major modes by default. - - * mule.texi (Recognize Coding): Remove an unreferenced vindex. - - * files.texi (Misc File Ops): Symbolic links on Windows only work - on Vista and later. - - * building.texi (Compilation): Document compilation-always-kill. - - * search.texi (Symbol Search): New node. - - * package.texi (Package Menu): Document the "new" status. - - * windows.texi (Window Choice): Don't refer to the obsolete - special-display feature. - -2012-10-24 Chong Yidong - - * mule.texi (Text Coding): set-buffer-file-coding-system can now - be invoked from the mode line. - - * dired.texi (Dired Deletion, Marks vs Flags): Document Emacs 24.3 - changes to the mark and unmark commands. - (Comparison in Dired): Document chages to dired-diff. Remove M-=, - which is no longer bound to dired-backup-diff. - -2012-10-23 Bastien Guerry - - * text.texi (Org Authoring): Use a comma after @ref to avoid the - insertion of a period in the Info output. - -2012-10-23 Stefan Monnier - - * custom.texi (Hooks): Clarify that -hooks is deprecated. - -2012-10-23 Chong Yidong - - * kmacro.texi (Edit Keyboard Macro): Fix typo. - -2012-10-18 Dani Moncayo - - * mini.texi (Completion Options): Fix off-by-one error. (Bug#12644) - -2012-10-17 Glenn Morris - - * mini.texi (Repetition): Further copyedit. - -2012-10-17 Dani Moncayo - - * mini.texi (Repetition): Copyedit. - -2012-10-16 Juri Linkov - - * search.texi (Query Replace): Document multi-buffer replacement - keys. (Bug#12655) - - * maintaining.texi (Tags Search): Change link "Replace" to - "Query Replace". - -2012-10-13 Chong Yidong - - * files.texi (File Conveniences): ImageMagick enabled by default. - -2012-10-10 Dani Moncayo - - * basic.texi (Arguments): Fix typos. - -2012-10-08 Glenn Morris - - * cal-xtra.texi (Calendar Customizing): Mention calendar-month-header. - - * calendar.texi (Writing Calendar Files): Mention cal-html-holidays. - -2012-10-06 Glenn Morris - - * calendar.texi (Writing Calendar Files): Tweak week descriptions. - Mention cal-tex-cursor-week2-summary. - -2012-10-06 Chong Yidong - - * mini.texi (Passwords): Fix typo. - -2012-10-02 Glenn Morris - - * maintaining.texi (VC Directory Commands): - Remove duplicate `q' entry. (Bug#12553) - -2012-09-30 Chong Yidong - - * killing.texi (Rectangles): Document copy-rectangle-as-kill. - - * search.texi (Special Isearch): Document the lax space search - feature and M-s SPC. - (Regexp Search): Move main search-whitespace-regexp description to - Special Isearch. - (Replace): Document replace-lax-whitespace. - - * basic.texi (Position Info): Document C-u M-=. - (Moving Point): Document move-to-column. - - * display.texi (Useless Whitespace): Add delete-trailing-lines. - - * misc.texi (emacsclient Options): Document the effect of - initial-buffer-choice on client frames. Document server-auth-dir. - Do not document server-host, which is bad security practice. - - * building.texi (Lisp Libraries): Docstring lookups can trigger - autoloading. Document help-enable-auto-load. - - * mini.texi (Yes or No Prompts): New node. - - * ack.texi (Acknowledgments): Remove obsolete packages. - -2012-09-27 Glenn Morris - - * cal-xtra.texi (Advanced Calendar/Diary Usage): - Rename the section to be more general. - * emacs.texi: Update menu. - -2012-09-23 Chong Yidong - - * buffers.texi (Misc Buffer): Replace toggle-read-only with - read-only-mode. - - * files.texi (Visiting): Likewise. - -2012-09-22 Paul Eggert - - * trouble.texi (Crashing): Document ulimit -c. - -2012-09-21 Paul Eggert - - * trouble.texi (Crashing): Document addr2line. - -2012-09-19 Tassilo Horn - - * misc.texi (DocView Slicing): Document new slice from - BoundingBox feature. - -2012-09-19 Chong Yidong - - * killing.texi (Yanking): Minor clarification (Bug#12469). - -2012-09-17 Chong Yidong - - * building.texi (GDB User Interface Layout): Remove reference to - removed variable gdb-use-separate-io-buffer (Bug#12454). - -2012-09-08 Jambunathan K - - * regs.texi (Text Registers): `C-x r +' can now be used instead of - M-x append-to-register. New option `register-separator'. - (Number Registers): Mention that `C-x r +' is polymorphic. - -2012-09-07 Chong Yidong - - * windows.texi (Window Choice): Don't mention obsolete - display-buffer-reuse-frames. - -2012-09-04 Paul Eggert - - Give more-useful info on a fatal error (Bug#12328). - * trouble.texi (Crashing): New section, documenting this. - -2012-08-24 Michael Albinus - - * cmdargs.texi (General Variables): - Setting $DBUS_SESSION_BUS_ADDRESS to a dummy value suppresses - connections to the D-Bus session bus. (Bug#12112) - -2012-08-14 Eli Zaretskii - - * building.texi (Debugger Operation): Correct and improve - documentation of the GUD Tooltip mode. - -2012-07-31 Chong Yidong - - * emacs.texi: Fix ISBN (Bug#12080). - -2012-08-05 Chong Yidong - - * display.texi (Faces): Document frame-background-mode (Bug#7774). - - * custom.texi (Face Customization): Move discussion of face - inheritance here, from Faces section. - -2012-07-28 Eli Zaretskii - - * frames.texi (Mouse Commands): Fix the description of mouse-2. - (Bug#11958) - -2012-07-19 Chong Yidong - - * emacs.texi: Update ISBN. - -2012-07-17 Chong Yidong - - * basic.texi (Inserting Text): Replace ucs-insert with - insert-char. Provide more details of input. - - * mule.texi (International Chars, Input Methods): Likewise. - -2012-07-13 Chong Yidong - - * custom.texi (Examining): Update C-h v message. - - * buffers.texi (Misc Buffer): Document view-read-only. - -2012-07-07 Chong Yidong - - * custom.texi (Init File): Index site-lisp (Bug#11435). - -2012-07-06 Chong Yidong - - * emacs.texi: Re-order top-level menu to correspond to logical - order, to avoid makeinfo warnings. - - * ack.texi (Acknowledgments): Note new python.el. - -2012-06-29 Chong Yidong - - * maintaining.texi (Basic VC Editing, VC Pull, Merging): - * basic.texi (Erasing, Basic Undo): Fix markup. - -2012-06-29 Glenn Morris - - * fixit.texi (Undo): Grammar fixes. (Bug#11779) - -2012-06-29 Michael Witten (tiny change) - - * fixit.texi (Undo): Fix typo. (Bug#11775) - -2012-06-27 Glenn Morris - - * ack.texi (Acknowledgments): Tiny update. - -2012-06-21 Glenn Morris - - * Makefile.in: Rename infodir to buildinfodir throughout. (Bug#11737) - -2012-06-17 Chong Yidong - - * emacs.texi: Remove urlcolor setting. Update ISBN and edition number. - - * anti.texi: - * building.texi: - * cmdargs.texi: - * custom.texi: - * display.texi: - * files.texi: - * frames.texi: - * glossary.texi: - * misc.texi: - * mule.texi: - * programs.texi: - * sending.texi: - * text.texi: Copyedits to avoid underfull/overfull in 7x9 manual. - -2012-06-06 Michael Albinus - - * custom.texi (Directory Variables): Mention enable-remote-dir-locals. - -2012-05-28 Glenn Morris - - * ack.texi, building.texi, calendar.texi, custom.texi: - * maintaining.texi, text.texi: Use @LaTeX rather than La@TeX. - -2012-05-27 Glenn Morris - - * emacs.texi: Simplify following removal of node pointers. - - * ack.texi, anti.texi, basic.texi, buffers.texi, building.texi: - * cmdargs.texi, commands.texi, display.texi, emacs.texi: - * entering.texi, files.texi, fixit.texi, frames.texi, glossary.texi: - * gnu.texi, help.texi, indent.texi, killing.texi, kmacro.texi: - * m-x.texi, macos.texi, maintaining.texi, mark.texi, mini.texi: - * misc.texi, modes.texi, msdog.texi, mule.texi, programs.texi: - * regs.texi, screen.texi, search.texi, text.texi, trouble.texi: - * windows.texi, xresources.texi: Nuke hand-written node pointers. - -2012-05-22 Glenn Morris - - * emacs.texi (Acknowledgments): Add another contributor. - -2012-05-12 Glenn Morris - - * Makefile.in (MKDIR_P): New, set by configure. - (mkinfodir): Use $MKDIR_P. - -2012-05-10 Glenn Morris - - * mule.texi (Disabling Multibyte): Replace the obsolete "unibyte: t" - with "coding: raw-text". - - * files.texi (Interlocking): Mention create-lockfiles option. - -2012-05-09 Chong Yidong - - * frames.texi (Mouse References, Mouse Commands): Fix index - entries (Bug#11362). - -2012-05-05 Glenn Morris - - * custom.texi (Customization Groups, Custom Themes, Examining): - Improve page breaks. - - * rmail.texi (Rmail Display): Use example rather than smallexample. - - * calendar.texi: Convert inforefs to refs. - - * dired.texi (Dired Enter): Improve page break. - - * abbrevs.texi (Abbrev Concepts): Copyedits. - - * maintaining.texi (Registering, Tag Syntax): - Tweak line and page breaks. - - * programs.texi (Programs, Electric C): Copyedits. - (Program Modes): Add xref to Fortran. - (Left Margin Paren): Remove what was (oddly enough) the only use - of defvar in the entire Emacs manual. - (Hungry Delete): Remove footnote about ancient Emacs version. - (Other C Commands): Use example rather than smallexample. - - * text.texi (Pages, Filling, Foldout, Org Mode, HTML Mode) - (Nroff Mode, Enriched Indentation, Table Rows and Columns): - Tweak line and page breaks. - - * modes.texi (Major Modes, Minor Modes): Reword to improve page-breaks. - (Major Modes): Use example rather than smallexample. - - * mule.texi (Output Coding): Reword to improve page-breaks. - - * frames.texi (Fonts): Tweak line and page breaks. - Use example rather than smallexample. Change cross-reference. - (Text-Only Mouse): Fix xref. - - * buffers.texi (Buffers, Kill Buffer, Several Buffers) - (Indirect Buffers): Tweak line- and page-breaks. - - * fixit.texi (Fixit, Undo): Reword to improve page-breaks. - -2012-05-04 Glenn Morris - - * Makefile.in (INFO_EXT, INFO_OPTS): New, set by configure. - (info, infoclean): Use $INFO_EXT. - ($(infodir)/emacs$(INFO_EXT)): Use $INFO_EXT and $INFO_OPT. - * makefile.w32-in (INFO_EXT, INFO_OPTS): New. - (INFO_TARGETS): Use $INFO_EXT. - ($(infodir)/emacs$(INFO_EXT)): Use $INFO_EXT and $INFO_OPT, and -o. - -2012-05-02 Glenn Morris - - * emacs.texi (@copying): Only print EDITION in the TeX version. - - * search.texi (Regexp Search): Just say "Emacs". - - * display.texi (Auto Scrolling): - Reword to avoid repetition and improve page break. - - * xresources.texi (Resources): - * mule.texi (Language Environments): - * misc.texi (Amusements): - * maintaining.texi (VC Change Log): - * frames.texi (Fonts): - * custom.texi (Specifying File Variables, Minibuffer Maps): - * cmdargs.texi (Initial Options): - * building.texi (Flymake): - Reword to remove/reduce some overly long/short lines. - -2012-04-27 Glenn Morris - - * emacs.texi: Some fixes for detailed menu. - - * emacs.texi: Add "et al." to authors. - - * ack.texi, basic.texi, buffers.texi, building.texi: - * calendar.texi, cmdargs.texi, commands.texi, custom.texi: - * dired.texi, display.texi, emerge-xtra.texi, files.texi: - * fortran-xtra.texi, help.texi, kmacro.texi, mini.texi, misc.texi: - * msdog-xtra.texi, picture-xtra.texi, programs.texi, rmail.texi: - * search.texi, trouble.texi, windows.texi: - Use Texinfo recommended convention for quotes+punctuation. - -2012-04-27 Eli Zaretskii - - * mule.texi (Bidirectional Editing): Improve indexing. - Minor wording tweaks. - -2012-04-15 Chong Yidong - - * misc.texi (emacsclient Options): More clarifications. - -2012-04-15 Glenn Morris - - * msdog.texi (Windows Printing): It doesn't set printer-name. - - * mule.texi (Language Environments): Move font info to "Fontsets". - (Fontsets): Move intlfonts etc here from "Language Environments". - Copyedits. - (Defining Fontsets, Modifying Fontsets, Undisplayable Characters) - (Unibyte Mode, Charsets, Bidirectional Editing): Copyedits. - -2012-04-15 Chong Yidong - - * glossary.texi (Glossary): Standardize on "text terminal" - terminology. All callers changed. - - * misc.texi (emacsclient Options): Document "client frame" concept - and its effect on C-x C-c more carefully. - -2012-04-15 Glenn Morris - - * frames.texi (Scroll Bars): - * glossary.texi (Glossary): Use consistent case for "X Window System". - - * mule.texi (Select Input Method, Coding Systems): - State command names in kbd tables. - (Recognize Coding): Add cross-ref. - (Output Coding): Don't mention message mode in particular. - (Text Coding, Communication Coding, File Name Coding, Terminal Coding): - Copyedits. - -2012-04-14 Glenn Morris - - * mule.texi (Select Input Method, Coding Systems, Recognize Coding): - Copyedits. - (Coding Systems): Mac OS X apparently uses newlines for EOL. - (Recognize Coding): Remove old auto-coding-regexp-alist example. - auto-coding-functions does not override coding: tags. - Remove rmail-decode-mime-charset; it no longer has any effect. - -2012-04-14 Chong Yidong - - * custom.texi (Creating Custom Themes): Add reference to Custom - Themes node in Lisp manual. - -2012-04-14 Glenn Morris - - * mule.texi (International): Copyedits. - (International Chars): Update C-x = example output. - (Disabling Multibyte): Rename from "Enabling Multibyte". - Clarify what "unibyte: t" does, and mode-line description. - (Unibyte Mode): Update for "Disabling Multibyte" node name change. - Use Texinfo recommended convention for quotes+punctuation. - (Language Environments): Copyedits. - (Input Methods): Copyedits. Use "^" for the postfix example, - because it is less confusing inside Info's `quotes'. - - * custom.texi (Specifying File Variables): Fix "unibyte" description. - Update for "Disabling Multibyte" node name change. - * emacs.texi: Update for "Disabling Multibyte" node name change. - - * abbrevs.texi, arevert-xtra.texi, buffers.texi, building.texi: - * cmdargs.texi, custom.texi, entering.texi, files.texi, frames.texi: - * glossary.texi, help.texi, macos.texi, maintaining.texi, mini.texi: - * misc.texi, package.texi, programs.texi, screen.texi, search.texi: - * sending.texi, text.texi, trouble.texi: - Use @file for buffers, per the Texinfo manual. - - * entering.texi (Entering Emacs): - Do not mention initial-buffer-choice = t. - - * misc.texi (Gnus Startup): Use @env for environment variables. - - * Makefile.in: Replace non-portable use of $< in ordinary rules. - -2012-04-12 Glenn Morris - - * ack.texi (Acknowledgments): Don't mention obsolete mailpost.el. - -2012-04-07 Glenn Morris - - * emacsver.texi (EMACSVER): Bump version to 24.1.50. - -2012-04-05 Glenn Morris - - * glossary.texi (Glossary): Use anchors for internal cross-references. - -2012-04-04 Glenn Morris - - * glossary.texi (Glossary): Copyedits. - Use Texinfo-recommended convention for quotes and punctuation. - Comment out a few specialized (Rmail) items. - New items: Bidirectional Text, Client, Directory Local Variable, - File Local Variable, Package, Server, Theme, Trash Can. - -2012-04-03 Chong Yidong - - * sending.texi (Mail Misc): Fix an index entry. - -2012-04-02 Eli Zaretskii - - * msdog.texi (Windows Startup): Add description of emacsclient - operation under -c and -t on MS-Windows. - - * misc.texi (emacsclient Options): Add cross-reference to "Windows - Startup". (Bug#11091) - -2012-04-02 Dani Moncayo - - * custom.texi (Changing a Variable): Fix example. - -2012-04-01 Eli Zaretskii - - * misc.texi (emacsclient Options): More clarifications about -t - and -c on MS-Windows. (Bug#11091) - -2012-03-31 Eli Zaretskii - - * misc.texi (emacsclient Options): Document peculiarities of new - frame creation on MS-Windows under -c or -t options. (Bug#11091) - -2012-03-30 Chong Yidong - - * files.texi (File Conveniences): Clarify Imagemagick discussion. - -2012-03-22 Glenn Morris - - * dired.texi (Operating on Files): Fix dired-recursive-copies default. - -2012-03-17 Chong Yidong - - * package.texi (Package Installation): Document use of - package-initialize in init file. - -2012-03-16 Glenn Morris - - * help.texi (Language Help): - * mule.texi (International Chars): - etc/HELLO is for character demonstration. - -2012-03-15 Dani Moncayo - - * dired.texi (Shell Commands in Dired): Fix typo. - -2012-03-04 Chong Yidong - - * killing.texi (Clipboard): Document clipboard manager. - -2012-02-29 Glenn Morris - - * ack.texi (Acknowledgments): Use @Tex{} in more places. - - * emacs.texi, help.texi, text.texi: Use "" quotes in menus. - - * dired.texi, emacs.texi: Use @code{} in menus when appropriate. - -2012-02-28 Glenn Morris - - * custom.texi, display.texi, emacs.texi, files.texi: - * msdog-xtra.texi, msdog.texi, vc-xtra.texi: - Standardize possessive apostrophe usage. - -2012-02-25 Jan Djärv - - * macos.texi (Mac / GNUstep Customization): Remove text about - ns-find-file and ns-drag-file (Bug#5855, Bug#10050). - -2012-02-25 Dani Moncayo - - * buffers.texi (Select Buffer): Mention that saving in a new file - name can switch to a different major mode. - -2012-02-23 Glenn Morris - - * mini.texi (Minibuffer File, Completion Options, Repetition): - Copyedits. - (Completion Example): Other M-x au* commands may be defined. - (Completion Styles): Mention emacs21 and completion-category-overrides. - - * msdog.texi (Text and Binary, ls in Lisp, Windows HOME) - (Windows Keyboard, Windows Mouse, Windows Processes) - (Windows Printing, Windows Misc): Copyedits. - (ls in Lisp): Update switches list. - - * msdog-xtra.texi (MS-DOS Display): Update list-colors-display xref. - Update dos-mode* function names. - (MS-DOS Printing, MS-DOS and MULE): Copyedits. - (MS-DOS Processes): Add xref to main ls-lisp section. - - * ack.texi (Acknowledgments): Mention smie. - -2012-02-22 Glenn Morris - - * macos.texi: Copyedits. Fix @key/@kbd usage. - (Mac / GNUstep Basics): Don't mention the panels, since the next - section covers them. - (Mac / GNUstep Customization): Merge some panel info from previous. - -2012-02-21 Glenn Morris - - * emerge-xtra.texi (Emerge, Submodes of Emerge, Combining in Emerge): - Small fixes. - - * emacs-xtra.texi: Picture mode is no longer a chapter. - - * picture-xtra.texi (Basic Picture): C-a does get remapped. - - * ack.texi (Acknowledgments): Small changes, including resorting, - and removal of things no longer distributed. - -2012-02-20 Glenn Morris - - * emacs.texi (Top, Preface): Small rephrasings. - (menu, detailmenu): Update entries, and reformat some descriptions. - * building.texi, display.texi, emacs-xtra.texi, files.texi: - * frames.texi, kmacro.texi, msdog.texi, programs.texi, text.texi: - Reformat some menu descriptions. - - * ack.texi (Acknowledgments): More updates. - - * emacs.texi (Acknowledgments): Add several names from ack.texi, - and from Author: headers. - (Distrib): Small updates. - -2012-02-18 Glenn Morris - - * ack.texi (Acknowledgments): Add xref to Org manual. - - * rmail.texi: Copyedits. Use 'mail composition buffer' in place - of '*mail*', since Message does not call it that. - (Rmail Reply): Rename rmail-dont-reply-to-names. - \\`info- no longer handled specially. - Update for rmail-enable-mime-composing. - Don't mention 'm' for replies. - Don't mention rmail-mail-new-frame and canceling, since it does - not work for Message at the moment. - - * cal-xtra.texi: Copyedits. - - * emacs-xtra.texi: Set encoding to ISO-8859-1. - -2012-02-17 Glenn Morris - - * maintaining.texi (Old Revisions): Fix cross-refs to Ediff manual. - - * ack.texi (Acknowledgments): Mention Gnulib. - - * ack.texi, calendar.texi, cal-xtra.texi: Use "Bahá'í". - - * calendar.texi: Misc small changes, including updating the dates - of examples. - -2012-02-16 Glenn Morris - - * calendar.texi: Misc small changes. - - * vc1-xtra.texi (VC Delete/Rename, CVS Options): - * cal-xtra.texi (Diary Display): Fix TeX cross-refs to other manuals. - - * dired-xtra.texi (Subdir Switches): Small fixes. - - * fortran-xtra.texi: Tiny changes and some adjustments to line breaks. - -2012-02-15 Glenn Morris - - * sending.texi (Mail Sending): smtpmail-auth-credentials was removed. - -2012-02-12 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Updates for new files in 24.1. - -2012-02-10 Glenn Morris - - * mini.texi (Minibuffer Edit): Mention minibuffer-inactive-mode. - - * programs.texi (Misc for Programs): Mention electric-layout-mode. - -2012-02-09 Glenn Morris - - * buffers.texi (Misc Buffer): M-x info does not seem to require a - buffer switch after M-x rename-uniquely. - - * trouble.texi (Checklist): Mention C-c m in report-emacs-bug. - -2012-02-09 Jay Belanger - - * text.texi (Org Mode): Fix typo. - -2012-02-08 Glenn Morris - - * ack.texi (Acknowledgments): Update emacs-lock info. - - * rmail.texi (Rmail Display): Mention rmail-epa-decrypt. - - * text.texi (LaTeX Editing): Mention latex-electric-env-pair-mode. - -2012-02-07 Glenn Morris - - * files.texi (File Conveniences): Mention ImageMagick images. - -2012-02-05 Glenn Morris - - * trouble.texi (Checklist): Mention debug-on-event. - - * maintaining.texi (Maintaining): Add cross-ref to ERT. - -2012-02-04 Glenn Morris - - * macos.texi (Customization options specific to Mac OS / GNUstep): - New subsection. - - * display.texi (Colors): Mention list-colors-sort. - - * files.texi (File Conveniences): Mention image animation. - -2012-01-31 Chong Yidong - - * windows.texi (Split Window): C-mouse-2 doesn't work on GTK+ - scroll bars (Bug#10666). - -2012-01-28 Chong Yidong - - * files.texi (Filesets): Fix typos. - - * display.texi (Faces): Add xref to Colors node. - -2012-01-27 Dani Moncayo - - * buffers.texi (Select Buffer): Clarify explanation of switching - to new buffers. Fix description of next-buffer and - previous-buffer (Bug#10334). - (Misc Buffer): Add xref to View Mode. - - * text.texi (Fill Commands): Fix description of - sentence-end-double-space. - -2012-01-23 Chong Yidong - - * anti.texi (Antinews): Add Emacs 23 antinews. - -2012-01-16 Volker Sobek (tiny change) - - * programs.texi (Comment Commands): Typo (bug#10514). - -2012-01-15 Chong Yidong - - * xresources.texi (X Resources): Describe GTK+ case first. - (Resources): Don't use borderWidth as an example, since it doesn't - work with GTK+. - (Table of Resources): Clarify role of several resources, including - the Emacs 24 behavior of cursorBlink etc. - (Face Resources): Node deleted. Recommend using Customize - instead. Add paragraph to `Table of Resources' node summarizing - how to use X resources for changing faces. - (Lucid Resources): Rewrite, omitting description of font names, - referring to the Fonts node instead. - (LessTif Resources): Copyedits. - (GTK resources): Rewrite, describing the difference between gtk2 - and gtk3. - (GTK Resource Basics): New node. - (GTK Widget Names, GTK Names in Emacs): Rewrite. - (GTK styles): Just refer to Fonts node for GTK font format. - - * display.texi (Faces): Document the cursor face. - -2012-01-14 Chong Yidong - - * cmdargs.texi (Action Arguments): No need to mention EMACSLOADPATH. - (General Variables): Add xref to Lisp Libraries. - (Initial Options): Copyedits. - (Resume Arguments): Node deleted; emacs.bash/csh are obsolete. - (Environment): Clarify what getenv does. - (General Variables): Clarify EMACSPATH etc. Emacs does not assume - light backgrounds on xterms. - (Misc Variables): TEMP and TMP are not Windows-specific. - (Display X): Copyedits. - (Colors X): -bd does nothing for GTK. - (Icons X): Gnome 3 doesn't use taskbars. - - * misc.texi (Shell): Document exec-path here. - - * rmail.texi (Movemail): Add xref for exec-path. - -2012-01-13 Glenn Morris - - * dired.texi (Dired and Find): Clarify find-ls-options. - -2012-01-09 Chong Yidong - - * custom.texi (Custom Themes): Switch custom-safe-themes to use - SHA-256. - -2012-01-07 Chong Yidong - - * display.texi (Useless Whitespace): Add Whitespace mode. - - * custom.texi (Hooks): Discuss how to disable minor modes. - - * files.texi (Diff Mode): Discuss diff-auto-refine-mode - (Bug#10309). Discuss use of Whitespace mode (Bug#10300). - - * trouble.texi (Lossage): Refer to Bugs node for problems. - (DEL Does Not Delete): Don't use "usual erasure key" teminology. - (Screen Garbled): Don't refer to terminal "manufacturers". - (Total Frustration): Node deleted. Eliza is documented in - Amusements now. - (Known Problems): More info about using the bug tracker. - Mention debbugs package. - (Bug Criteria): Copyedits. - (Understanding Bug Reporting): Mention emacs -Q. - -2012-01-06 Chong Yidong - - * custom.texi (Specifying File Variables): The mode: keyword - doesn't have to be first anymore. Add example of specifying minor - modes. - (Directory Variables): Simplify example. Mention application to - non-file buffers. - (Disabling): Use "initialization file" terminology. - (Init Examples): Fix hook example. - -2012-01-06 Eli Zaretskii - - * cmdargs.texi (MS-Windows Registry): Shorten the index entry. - (Bug#10422) - Move the stuff about resources to xresources.texi. - - * xresources.texi (Resources): Move information about setting X - resources in the Registry from cmdargs.texi. Make the index entry - be similar to the one in cmdargs.texi. - -2012-01-05 Chong Yidong - - * custom.texi (Customization Groups): Update example. - (Browsing Custom): Document the new search field. - (Changing a Variable): Update example for Emacs 24 changes. - Document Custom-set and Custom-save commands. - (Face Customization): Document Emacs 24 changes. De-document - modify-face. - (Specific Customization): Mention customize-variable. - (Custom Themes): Add customize-themes, custom-theme-load-path, - custom-theme-directory, and describe-theme. - (Creating Custom Themes): New node. - (Examining): Mention M-:. - - * package.texi (Packages): Fix typo. - -2012-01-03 Chong Yidong - - * misc.texi (Single Shell): Don't document Lisp usage of - shell-command. Tidy up discussion of synchronicity. Add index - entries for async-shell-command. - (Interactive Shell): Note that M-x shell uses shell-file-name. - Note change in behavior in Emacs 24. - (Shell Mode): Shell mode now uses completion-at-point. - (Shell Prompts): Emphasize that comint-use-prompt-regexp isn't the - default method for recognizing prompts nowadays. - (Shell Ring): Add xref to Minibuffer History. - (Directory Tracking): Explain Dirtrack mode in more detail. - (Term Mode): Fix index entries. - (Paging in Term): Merge into Term Mode. - (Serial Terminal, Emacs Server, emacsclient Options): Copyedits. - (Printing): Fix xref. State default of lpr-switches. - (PostScript): Remove obsolete sentence. Omit description of - non-interactive behaviors. - (Hyperlinking): Improve description. - (Browse-URL): Using compose-mail for mailto URLs is the default. - Document browse-url-mailto-function. - (Goto Address mode): Add index entries. Add xref to Browse-URL. - (FFAP): FFAP is not a minor mode. - (Amusements): M-x lm was renamed to M-x landmark. - Document nato-region. - -2012-01-01 Chong Yidong - - * misc.texi (Gnus, Buffers of Gnus): Copyedits. - (Gnus Startup): Note that the system might not be set up for news. - Describe group levels more clearly. - (Gnus Group Buffer, Gnus Summary Buffer): New nodes, split from - Summary of Gnus. - (Document View): Copyedits. Move zoom commads to DocView - Navigation node. - (DocView Navigation, DocView Searching, DocView Slicing) - (DocView Conversion): Nodes renamed from Navigation, etc. - - * sending.texi (Mail Sending): Add message-kill-buffer-on-exit. - -2011-12-31 Eli Zaretskii - - * basic.texi (Moving Point): Fix the description of C-n and C-p. - (Bug#10380) - -2011-12-30 Chong Yidong - - * sending.texi (Sending Mail): Document initial mail buffer name, - and changed multiple mail buffer behavior. - (Mail Format): Put the example at the top of the section. - (Mail Headers): Move discussion of "From" to the top. - (Mail Sending): Document sendmail-query-once. - (Citing Mail): Make it less Rmail-specific. - -2011-12-29 Chong Yidong - - * text.texi (Org Mode): Copyedits. Refer to Outline Format for - example. Add index entries. - (Org Organizer, Org Authoring): Nodes renamed. Copyedits. - -2011-12-26 Chong Yidong - - * dired.texi (Dired Enter, Misc Dired Features): - Document dired-use-ls-dired changes. Mention quit-window. - (Dired Navigation): Add index entries. - (Dired Visiting): Fix View Mode xref. - (Marks vs Flags): Prefer C-/ binding for undo. - (Subdirectories in Dired): Add xrefs. - (Misc Dired Features): Document some Emacs 24 changes. Add index - entries. - - * abbrevs.texi (Abbrev Concepts): No need to mention abbrev-mode - variable, since it is explained in Minor Modes node. - (Defining Abbrevs): Copyedits. - (Expanding Abbrevs): State default of abbrev-all-caps. Prefer the - C-/ binding for undo. - (Dabbrev Customization): Add xrefs for case-fold-search and - case-replace. - - * dired-xtra.texi (Subdir Switches): Add xref. - - * maintaining.texi (VC Directory Commands): Mention quit-window. - -2011-12-25 Chong Yidong - - * maintaining.texi (Tags): Mention Semantic. - (Create Tags Table, Etags Regexps): Copyedits. - (Find Tag): Mention minibuffer completion. - (List Tags): Mention completion-at-point. Completion is actually - available in M-x list-tags. - - * vc1-xtra.texi (VC Delete/Rename): Rename from Renaming and VC. - Document vc-delete-file. - - * files.texi (Misc File Ops): Mention vc-delete-file. - - * programs.texi (Symbol Completion): Mention completion-at-point - explicitly. - -2011-12-22 Chong Yidong - - * maintaining.texi (Change Log Commands): Don't specially mention - vc-update-change-log which is CVS-only. - - * vc1-xtra.texi (Version Headers): Note that these are for - Subversion, CVS, etc. only. - (General VC Options): De-document vc-keep-workfiles. - Fix RCS-isms. - -2011-12-22 Eli Zaretskii - - * building.texi (Debugger Operation): Fix a typo: "@end iftext" - should be @end iftex". - -2011-12-21 Chong Yidong - - * maintaining.texi (Advanced C-x v v): Use fileset terminology. - (VC With A Merging VCS, VC Change Log): Add xref to VC Pull node. - (VC Pull): Mention vc-log-incoming. - (Log Buffer): Add CVS/RCS only disclaimer. - - * vc1-xtra.texi (Remote Repositories): Update introduction. - (Local Version Control): Node deleted (obsolete with DVCSes). - (Remote Repositories, Version Backups): Node deleted. - Move documentation of vc-cvs-stay-local to CVS Options. - (CVS Options): Reduce verbosity of description of obscure CVS - locking feature. - (Making Revision Tags, Revision Tag Caveats): Merge into Revision - Tags node. - (Revision Tags): Move under Miscellaneous VC subsection. - (Change Logs and VC): Note that this is wrong for DVCSs. - De-document log entry manipulating features. - (Renaming and VC): Describe how it works on modern VCSes. - - * files.texi (Misc File Ops): Mention vc-rename-file. - - * programs.texi (Custom C Indent): Add index entries. - -2011-12-20 Alan Mackenzie - - * programs.texi (Motion in C): Update the description of C-M-a and - C-M-e, they now DTRT in enclosing scopes. - (Custom C Indent): Add @dfn{guessing} of the indentation style. - -2011-12-20 Chong Yidong - - * maintaining.texi (VCS Concepts): Add "working tree" terminology. - (Old Revisions): Use it. - (VCS Repositories): Add "distributed" terminology. - (Log Buffer): Remove duplicate description - about changesets. Fix "current VC fileset" ambiguity. - (Multi-User Branching): Node deleted. - (Branches, Switching Branches): Discuss decentralized version - control systems. - (VC Pull): New node. - (Merging): Document merging on decentralized systems. - (Creating Branches): Note that this is specific to CVS and related - systems. - -2011-12-19 Chong Yidong - - * maintaining.texi (VCS Merging, VCS Changesets): Index entries. - (VC Mode Line): Add index entry for "version control status". - (VC Undo): Use vc-revert instead of its vc-revert-buffer alias. - Document vc-revert-show-diff. De-document vc-rollback. - (VC Directory Mode): Rewrite introduction. Move prefix arg - documentation here from VC Directory Buffer node. - (VC Directory Buffer): Use a decentralized VCS example. - (VC Directory Commands): Use a table. Remove material duplicated - in previous nodes on multi-file VC filsets. - -2011-12-17 Chong Yidong - - * maintaining.texi (VCS Concepts): Make "revision" terminology - less CVS-specific. - (VC With A Merging VCS, VC With A Locking VCS): Add xref to - Registering node. - (Secondary VC Commands): Delete. Promote subnodes. - (Log Buffer): Add command name for C-c C-c. Fix the name of the - log buffer. Add index entries. - (VCS Changesets, Types of Log File, VC With A Merging VCS): - Use "commit" terminology. - (Old Revisions): Move it to just before VC Change Log. "Tag" here - doesn't refer to tags tables. Note other possible forms of the - revision ID. C-x v = does not save. - (Registering): Note similarity to C-x v v action. Fix description - of how backends are chosen. De-document vc-default-init-revision. - (VC Change Log): Document C-x v l in VC-Dir buffer. Document RET - in root log buffers. - -2011-12-16 Chong Yidong - - * maintaining.texi (Version Control Systems): Drop Meta-CVS. - (Basic VC Editing): Remove redundant descriptions. - (VC With A Merging VCS): Make description more general instead of - CVS-specific. - (VC With A Locking VCS): Use VC fileset terminology. - -2011-12-12 Chong Yidong - - * building.texi (Executing Lisp): Fix xref for C-M-x. - (Lisp Libraries): Add xref to node explaining `load' in Lisp - manual. Note that load-path is not customizable. - (Lisp Eval): Note that listed commands are available globally. - Explain the meaning of "defun" in the C-M-x context. - (Lisp Interaction): Copyedits. - (External Lisp): Fix name of inferior Lisp buffer. - Mention Scheme. - (Compilation): Define "inferior process". - -2011-12-10 Eli Zaretskii - - * msdog.texi (Windows Fonts): Document how to force GDI font - backend on MS-Windows. - -2011-12-10 Chong Yidong - - * building.texi (Compilation): Say what the -k flag to make does. - Move subprocess discussion to Compilation Shell. - (Compilation Mode): Add xref for grep, occur, and mouse - references. Define "locus". - (Grep Searching): Use @command. - (Debuggers, Commands of GUD, GDB Graphical Interface): - Clarify intro. - (Starting GUD): Clarify how arguments are specified. - (Debugger Operation): Index entry for "GUD interaction buffer", - and move basic description here from Commands of GUD node. - (GDB User Interface Layout): Copyedits. - (Source Buffers): Remove gdb-find-source-frame, which is not in - gdb-mi.el. - (Other GDB Buffers): Remove gdb-use-separate-io-buffer and - toggle-gdb-all-registers, which are not in gdb-mi.el. - Don't re-document GUD interaction buffers. - - * programs.texi (Symbol Completion): M-TAB can now use Semantic. - (Semantic): Add cindex entries for Semantic. - -2011-12-06 Chong Yidong - - * programs.texi (Man Page): Clarify how to use Man-switches. - Don't bother documenting Man-fontify-manpage-flag. - (Lisp Doc): Add xref to Name Help node. - (Hideshow): Add cindex. Mention role of ellipses, and default - value of hs-isearch-open. Don't bother documenting - hs-special-modes-alist. - (Symbol Completion): Add kindex for C-M-i. Don't recommend - changing the window manager binding of M-TAB. - -2011-12-05 Chong Yidong - - * programs.texi (Comment Commands): Fix description of for M-; on - blank lines. Move documentation of comment-region here. - (Multi-Line Comments): Clarify the role of comment-multi-line. - Refer to Comment Commands for comment-region doc. - (Options for Comments): Refer to Multi-Line Comments for - comment-multi-line doc, instead of duplicating it. Fix default - values of comment-padding and comment-start-skip. - -2011-12-04 Chong Yidong - - * programs.texi (Program Modes): Mention modes that are not - included with Emacs. Fix references to other manuals for tex. - Add index entry for backward-delete-char-untabify. - Mention prog-mode-hook. - (Which Function): Use "global minor mode" terminology. - (Basic Indent, Multi-line Indent): Refer to previous descriptions - in Indentation chapter to avoid duplication. - (Expressions): Copyedit. - (Matching): Document Electric Pair mode. - - * ack.texi (Acknowledgments): - * rmail.texi (Movemail, Other Mailbox Formats): - * frames.texi (Frames): Don't capitalize "Unix". - -2011-12-04 Chong Yidong - - * text.texi (Nroff Mode): Mention what nroff is. - (Text Based Tables, Table Recognition): Don't say "Table mode" - since it's not a major or minor mode. - (Text Based Tables): Reduce the size of the example. - (Table Definition): Clarify definitions. - (Table Creation): Add key table. - (Cell Commands): Use kbd for commands. - (Table Rows and Columns): Combine nodes Row Commands and Column - Commands. - (Fixed Width Mode): Node deleted; contents moved to parent. - (Table Conversion): Shorten example. - (Measuring Tables): Merge into Table Misc. - -2011-12-03 Chong Yidong - - * text.texi (TeX Mode): Mention AUCTeX package. - (TeX Editing): Add xref to documentation for Occur. - (LaTeX Editing): Add xref to Completion node. - (TeX Print): Fix description of tex-directory. - (Enriched Text): Rename from Formatted Text. Make this node and - its subnodes less verbose, since text/enriched files are - practically unused. - (Enriched Mode): Rename from Requesting Formatted Text. - (Format Colors): Node deleted. - (Enriched Faces): Rename from Format Faces. Describe commands - for applying colors too. - (Forcing Enriched Mode): Node deleted; merged into Enriched Mode. - - * frames.texi (Menu Mouse Clicks): Tweak description of C-Mouse-2. - - * display.texi (Colors): New node. - - * cmdargs.texi (Colors X): - * xresources.texi (GTK styles): - * custom.texi (Face Customization): Reference it. - - * glossary.texi (Glossary): Remove "formatted text" and "WYSIWYG". - Link to Fill Commands for Justification entry. - -2011-12-03 Eli Zaretskii - - * display.texi (Auto Scrolling): More accurate description of what - scroll-*-aggressively does, including the effect of non-zero - margin. Fix "i.e." markup. - -2011-12-02 Chong Yidong - - * text.texi (Pages): Mention how formfeed chars are displayed. - (Auto Fill): Note convention for calling auto-fill-mode from Lisp. - Describe adaptive filling more precisely. - (Fill Commands): Note that filling removes excess whitespace. - (Text Mode): Note auto-mode-alist entries for Text mode. TAB is - now bound to indent-for-tab-command in Text mode. - (Outline Mode): Copyedits. - (Outline Visibility): Note that Reveal mode is a buffer-local - minor mode. - - * modes.texi (Major Modes): Move note about checking major-mode in - a hook function here, from Text mode. - -2011-11-28 Chong Yidong - - * text.texi (Words): Add xref to Position Info. - (Paragraphs): Add xref to Regexps. - - * indent.texi (Indentation): Rewrite introduction. Move table to - Indentation Commands node. - (Indentation Commands): Add index entries to table. Copyedits. - (Tab Stops, Just Spaces): Copyedits. - (Indent Convenience): New node. Document electric-indent-mode. - - * programs.texi (Basic Indent): - * windows.texi (Pop Up Window): Fix kindex entry. - -2011-11-28 Chong Yidong - - * modes.texi (Major Modes): Move major-mode variable doc here from - Choosing Modes. Document describe-mode. Document prog-mode-hook - and text-mode-hook. Add example of using hooks. - (Minor Modes): Document behavior of mode command calls from Lisp. - Note that setting the mode variable using Customize will DTRT. - (Choosing Modes): Add example of setting a minor mode using a - local variable. - -2011-11-27 Chong Yidong - - * frames.texi (Creating Frames): Move frame parameter example to - Frame Parameters node. - (Frame Commands): C-x 5 o does not warp the mouse by default. - (Fonts): Add more GTK-style properties; also, they should be - capitalized. - (Special Buffer Frames): Node deleted; special-display is on the - way out. - (Frame Parameters): Example moved here from Creating Frames. - Clarify that default-frame-alist affects the initial frame too. - Delete auto-raise-mode and auto-lower-mode. - (Wheeled Mice): Node deleted. Content moved to Mouse Commands. - (Dialog Boxes): Delete x-gtk-use-old-file-dialog. - - * windows.texi (Window Choice): Add xref to Lisp manual for - special-display-*. - -2011-11-26 Eli Zaretskii - - * display.texi (Text Display): Update the description, - cross-references, and indexing related to display of control - characters and raw bytes. - -2011-11-25 Chong Yidong - - * frames.texi (Frames): Rewrite introduction. - (Mouse Commands): Default for mouse-drag-copy-region is now t. - Mouse-3 does not copy to kill ring by default. DEL does not - behave specially for mouse commands any more. - (Mouse References): Document mouse-1-click-follows-link more - thoroughly. - (Menu Mouse Clicks): Move footnote to the main text and add xref - to Init Rebinding node. - (Mode Line Mouse): Mouse-3 on the mode-line does not bury buffer. - - * files.texi (Visiting): `C-x 5 f' works on ttys too. - -2011-11-24 Juanma Barranquero - - * display.texi (Font Lock): Fix typo. - -2011-11-24 Glenn Morris - - * rmail.texi (Rmail Output): - Mention rmail-automatic-folder-directives. (Bug#9657) - -2011-11-21 Chong Yidong - - * mark.texi (Global Mark Ring): Fix description of global mark - ring (Bug#10032). - -2011-11-20 Juanma Barranquero - - * msdog.texi (Windows Fonts): Fix typo. - -2011-11-17 Glenn Morris - - * regs.texi (Bookmarks): Small fixes related to saving. (Bug#10058) - -2011-11-16 Juanma Barranquero - - * killing.texi (Rectangles): - * misc.texi (Document View): - * modes.texi (Choosing Modes): - * msdog.texi (Windows Fonts): - * regs.texi (Rectangle Registers): - * search.texi (Isearch Yank): Fix typos. - -2011-11-06 Chong Yidong - - * windows.texi (Basic Window): Add xref to Cursor Display. - (Split Window): Document negative arg for splitting commands. - (Other Window): Document mouse-1 in text area of window. - (Change Window): Don't mention window attributes, since they - aren't defined. C-x 1 can't be used with minibuffer windows. - Windows are no longer auto-deleted. - (Window Choice): Add xref to Choosing Window in Lisp manual. - (Window Convenience): Note that windmove disables shift-selection. - Move M-x compare-windows here from Other Window node. - - * custom.texi (Mouse Buttons): - * search.texi (Isearch Scroll): - * windows.texi (Split Window): Use new names split-window-below - and split-window-right. - -2011-10-26 Juanma Barranquero - - * emacs.texi (Top): Fix typo. - -2011-10-25 Glenn Morris - - * abbrevs.texi (Saving Abbrevs): - quietly-read-abbrev-file is not a command. (Bug#9866) - -2011-10-24 Chong Yidong - - * display.texi (Scrolling): Document scroll-up-line and - scroll-down-line. Document scroll-command property. - (Recentering): New node, split off from Scrolling. - -2011-10-23 Chong Yidong - - * frames.texi (Scroll Bars): GTK uses right scroll bars now. - (Tool Bars): Copyedits. - - * buffers.texi (Misc Buffer): Don't mention vc-toggle-read-only. - -2011-10-22 Chong Yidong - - * windows.texi (Displaying Buffers): Fix broken lispref link. - -2011-10-22 Chong Yidong - - * mini.texi (Minibuffer Exit): Rename from Strict Completion. - Move confirm-nonexistent-file-or-buffer discussion here. - - * files.texi (File Names, Visiting): Move detailed discussion of - minibuffer confirmation to Minibuffer Exit. - - * buffers.texi (Buffers): Tweak mention of mail buffer name. - (Select Buffer): Move confirmation discussion to Minibuffer Exit. - -2011-10-21 Chong Yidong - - * files.texi (File Names, Visiting, Interlocking): Copyedits. - (Backup Copying): backup-by-copying-when-mismatch is now t. - (Customize Save): Fix description of require-final-newline. - (Reverting): Note that revert-buffer can't be undone. Mention VC. - (Auto Save Control): Clarify. - (File Archives): Add 7z. - (Remote Files): ange-ftp-make-backup-files defaults to nil. - - * arevert-xtra.texi (Autorevert): Copyedits. - -2011-10-20 Chong Yidong - - * custom.texi (Hooks, Init Examples): - * display.texi (Font Lock): - * fixit.texi (Spelling): - * rmail.texi (Rmail Display): Minor mode function with no arg now - enables it. - - * fixit.texi (Spelling): Fix description of inline completion. - -2011-10-19 Chong Yidong - - * search.texi (Repeat Isearch, Error in Isearch): Add kindex - entries. - (Isearch Yank): Document isearch-yank-pop. - (Isearch Scroll): Refer to C-l instead of unbound `recenter'. - (Other Repeating Search): Document Occur Edit mode. - -2011-10-18 Chong Yidong - - * display.texi (Fringes): Move overflow-newline-into-fringe here, - from Line Truncation node. - (Standard Faces): Note that only the background of the cursor face - has an effect. - (Cursor Display): Fix descriptions of cursor face - and bar cursor blinking. - (Text Display): Document nobreak-char-display more clearly. - (Line Truncation): Add xref to Split Window node. - (Display Custom): Don't bother documenting baud-rate or - no-redraw-on-reenter. - - * search.texi (Slow Isearch): Node removed. - -2011-10-18 Glenn Morris - - * maintaining.texi (Registering): Remove vc-initial-comment. (Bug#9745) - -2011-10-18 Chong Yidong - - * display.texi (Faces): Simplify discussion. Move documentation - of list-faces-display here, from Standard Faces node. - Note special role of `default' background. - (Standard Faces): Note special role of `default' background. - Note that region face may be taken fom GTK. Add xref to Text Display. - (Text Scale): Rename from "Temporary Face Changes". - Callers changed. Don't bother documenting variable-pitch-mode. - (Font Lock): Copyedits. Remove font-lock-maximum-size. - (Useless Whitespace): Simplify description of - delete-trailing-whitespace. Note active region case. - (Text Display): Fix description of escape-glyph face assignment. - Remove unibye mode discussion. Update some parts for Unicode. - Move glyphless chars documentation to Lisp manual. - - * frames.texi (Tooltips): Document x-gtk-use-system-tooltips. - -2011-10-15 Chong Yidong - - * display.texi (Scrolling): Tweak explanation of scroll direction. - (View Mode): Add index entries. - - * killing.texi (Deletion): Document negative prefix arg to M-SPC. - - * regs.texi (Text Registers): C-x r i does not activate the mark. - (Bookmarks): Document new default bookmark location. - -2011-10-13 Chong Yidong - - * killing.texi (Deletion): Add xref to Using Region. - Document delete-forward-char. - (Yanking): Move yank-excluded-properties to Lisp manual. Move C-y - description here. Recommend C-u C-SPC for jumping to mark. - (Kill Ring): Move kill ring variable documentation here. - (Primary Selection): Copyedits. - (Rectangles): Document new command rectangle-number-lines. - (CUA Bindings): Note that this disables the mark-even-if-inactive - behavior for C-x and C-c. - - * mark.texi (Mark): Mention "active region" terminology. - (Using Region): Document delete-active-region. - -2011-10-12 Chong Yidong - - * mark.texi (Mark): Clarify description of disabled Transient Mark - mode (Bug#9689). - (Setting Mark): Document prefix arg for C-x C-x. Document primary - selection changes. Mention that commands like C-y set the mark. - (Marking Objects): Add xref to Words node. Note that mark-word - and mark-sexp also have the "extend region" behavior. - (Using Region): Mention M-$ in the table. - Document mark-even-if-inactive here instead of in Mark Ring. - (Mark Ring): Move mark-even-if-inactive to Using Region. - Take note of the "Mark Set" behavior. - (Disabled Transient Mark): Rename from "Persistent Mark" - (Bug#9688). Callers changed. - - * programs.texi (Expressions): - * text.texi (Words): Defer to Marking Objects for mark-word doc. - -2011-10-09 Chong Yidong - - * help.texi (Help, Help Summary): Eliminate the unnecessary "help - option" terminology. - (Key Help): Add command names. Define "documentation string". - (Name Help): Remove an over-long joke. - (Apropos): Document prefix args. Remove duplicated descriptions. - (Help Mode): Add C-c C-b to table. Update TAB binding. - (Package Keywords): Rename from "Library by Keyword". - Describe new package menu interface. - (Help Files, Help Echo): Tweak description. - - * mini.texi (Completion Options): Add completion-cycle-threshold. - (Minibuffer History): Document numeric args to history commands. - -2011-10-08 Eli Zaretskii - - * mule.texi (Bidirectional Editing): Correct some inaccuracies. - -2011-10-08 Chong Yidong - - * basic.texi (Position Info): Omit page commands. - Document count-words-region and count-words. - - * text.texi (Pages): Move what-page documentation here. - -2011-10-08 Chong Yidong - - * mini.texi (Minibuffer File): Minor copyedits. Use xref to - Remote Files node instead of linking directly to the Tramp manual. - (Minibuffer Edit): Add xref to Blank Lines. - (Completion): Add xref to Symbol Completion. Remove redundant - example, which is repeated in the next node. - (Completion Commands): Minor clarifications. - (Completion Styles): New node, split from Completion Commands. - Document substring and initials styles. - (Strict Completion): Remove information duplicated in other nodes. - (Completion Options): Consolidate case difference discussion here. - - * help.texi (Help Mode): Fix kindex entries. - - * files.texi (File Names): Add index entries. - -2011-10-07 Chong Yidong - - * basic.texi (Inserting Text): Add xref to Completion. - Add ucs-insert example, and document prefix argument. - (Moving Point): Fix introduction; C-f/C-b are no longer equivalent - to left/right. Tweak left-char and right-char descriptions. - M-left and M-right are now bound to left-word/right-word. - (Erasing): Document delete-forward-char. - - * screen.texi (Screen, Menu Bar): Copyedits. - (Point): Remove duplicate paragraph on cursors, also in Screen. - (Mode Line): Trailing dashes no longer shown on X displays. - - * frames.texi (Non-Window Terminals): Index just "text-only - terminal", which is used throughout the manual now. - - * entering.texi (Entering Emacs): Define "startup screen". - Document window-splitting behavior with command-line inputs. - (Exiting): Remove obsolete paragraph about shells without suspend - functionality. - - * commands.texi (User Input): Define "input event" more clearly. - (Keys): Add xref to Echo Area. - (Commands): Clarify relation between commands and functions. - -2011-10-06 Chong Yidong - - * misc.texi (emacsclient Options): Document how emacsclient runs - the Emacs daemon (Bug#9674). - -2011-10-01 Chong Yidong - - * basic.texi (Moving Point): - * custom.texi (Mouse Buttons): - * rmail.texi (Rmail Scrolling): - * search.texi (Isearch Scroll): - * display.texi (Scrolling): Replace scroll-up/down with - scroll-up/down-command. Fix scroll-preserve-screen-position - description. Document scroll-error-top-bottom. - -2011-09-30 Glenn Morris - - * commands.texi (Keys): Whitespace fix. (Bug#9635) - -2011-09-24 Chong Yidong - - * windows.texi (Pop Up Window): Defer discussion of window - splitting to the Window Choice node. Add index entries. - (Force Same Window): Node deleted. - (Displaying Buffers, Window Choice): New nodes. - - * buffers.texi (Select Buffer): Clarify description of - buffer-switching commands. Add xref to Window Display node. - Don't repeat confirm-nonexistent-file-or-buffer description from - Visiting node. Remove even-window-heights. - - * frames.texi (Special Buffer Frames): Add xref to Window Choice. - -2011-09-18 Chong Yidong - - * cmdargs.texi (Icons X): Fix description of Emacs icon. - - * xresources.texi (Table of Resources): Fix documentation of - bitmapIcon. - -2011-09-15 Chong Yidong - - * package.texi (Package Menu): Add package-menu-mark-upgrades. - -2011-09-12 Eric Hanchrow - - * frames.texi (Frame Commands): Note that delete-other-frames only - deletes frames on current terminal. - -2011-09-10 Eli Zaretskii - - * sending.texi (Mail Misc): Document mail-add-attachment. - -2011-09-04 Eli Zaretskii - - * basic.texi (Inserting Text): Add index entries. (Bug#9433) - -2011-08-29 Chong Yidong - - * modes.texi (Choosing Modes): auto-mode-case-fold is now t. - -2011-08-28 Chong Yidong - - * files.texi (File Archives): - * cal-xtra.texi (Diary Display): - * help.texi (Help Mode): Add xref to View Mode. - -2011-08-28 Chong Yidong - - * display.texi (View Mode): New node. Move view-file here from - Misc File Ops. Move view-buffer here from Misc Buffer. - - * buffers.texi (Misc Buffer): Move view-buffer to View Mode. - - * files.texi (Misc File Ops): Document new - delete-by-moving-to-trash behavior. Remove view-file. - - * dired.texi (Dired Deletion): Shorten description of Trash. - - * misc.texi (emacsclient Options): Document server-port. - -2011-08-27 Eli Zaretskii - - * frames.texi (Frame Commands): Advise setting focus-follows-mouse - even on MS-Windows. Fix a typo. - -2011-08-26 Chong Yidong - - * package.texi: New file, documenting the package manager. - - * emacs.texi: Include it. - - * help.texi (Help Summary): Add describe-package. - -2011-08-25 Chong Yidong - - * misc.texi (Printing): Convert subnodes into subsections. - - * text.texi (Two-Column): Move into Text chapter. - - * picture-xtra.texi (Picture Mode): Group with Editing Binary - Files section. Convert from chapter into section. - - * display.texi (Narrowing): Move into display chapter. - - * sending.texi (Sending Mail): - * rmail.texi (Rmail): - * misc.texi (Gnus, Document View): - * dired.texi (Dired): - * emacs.texi: Group the mail, rmail, and gnus chapters together. - -2011-08-07 Juri Linkov - - * dired.texi (Operating on Files): Rewrite according to the fact - that `dired-do-chmod' doesn't use the `chmod' program anymore. - -2011-07-30 Michael Albinus - - * mini.texi (Minibuffer File): Insert a reference to Tramp for - remote file name completion. (Bug#9197) - -2011-07-28 Eli Zaretskii - - * mule.texi (Bidirectional Editing): Document the fact that - bidi-display-reordering is t by default. - -2011-07-15 Lars Magne Ingebrigtsen - - * help.texi (Misc Help): Mention `describe-prefix-bindings' - explicitly (bug#8904). - -2011-07-14 Lars Magne Ingebrigtsen - - * trouble.texi (Checklist): Use an `M-x' example instead of an - Emacs Lisp form to switch on the dribble file (bug#8056). - -2011-07-13 Lars Magne Ingebrigtsen - - * custom.texi (Hooks): Mention buffer-local hooks (bug#6218). - -2011-07-13 Glenn Morris - - * dired.texi (Dired Enter): Mention --dired. (Bug#9039) - -2011-07-13 Lars Magne Ingebrigtsen - - * mark.texi (Mark Ring): Clarify how many locations are saved - (bug#5770). - (Global Mark Ring): Ditto. - -2011-07-12 Lars Magne Ingebrigtsen - - * text.texi (Table Recognition): Use "at point" instead of "under - point" (bug#4345). - - * display.texi (Cursor Display): Mention `cursor-type'. - - * screen.texi (Point): Clarify that it's only if you use a block - cursor that it appears to be on a character (bug#4345). - -2011-07-12 Chong Yidong - - * misc.texi (Amusements): Move dissociated press here, from its - own section. - - * emacs.texi (Top): Update node listing. - -2011-07-12 Lars Magne Ingebrigtsen - - * emacs.texi (Top): Change "inferiors" to "subnodes" for greater - clarity (bug#3523). - -2011-07-12 Chong Yidong - - * cmdargs.texi (Initial Options): Document --no-site-lisp. - (Misc X): Document --parent-id. - - * frames.texi (Frame Commands): Note that focus-follows-mouse now - defaults to nil. - - * misc.texi (emacsclient Options): Document --parent-id. - - * msdog.texi (Windows HOME): Document _emacs as obsolete. - -2011-07-11 Lars Magne Ingebrigtsen - - * emacs.texi: Use "..." instead of ``...'' in the menus - (bug#3503). - -2011-07-11 Chong Yidong - - * killing.texi (Primary Selection): Document `only' setting for - select-active-regions. - - * mark.texi (Setting Mark): Reference Shift Selection node. - - * frames.texi (Mouse Commands): Document mouse-yank-primary. - -2011-07-11 Lars Magne Ingebrigtsen - - * mark.texi (Setting Mark): Clarify what's meant by "Shifted - motion keys" (bug#3503). - - * emacs.texi: Change all the register node names from "RegPos" - (etc.) to "Positional Registers" (etc.) (bug#3314). - -2011-07-11 Chong Yidong - - * killing.texi (Killing, Deletion and Killing, Killing by Lines) - (Other Kill Commands, Kill Options): Copyedits. - (Deletion and Killing, Kill Ring): Kill/yank now use clipboard. - (Yanking): Move yank-excluded properties discussion here. - (Cut and Paste): Move from frames.texi. Update subnodes to - describe x-select-enable-clipboard case. - - * frames.texi: Move Cut and Paste node and subnodes into - killing.texi, except Mouse Commands and Word and Line Mouse. - -2011-07-10 Andy Moreton (tiny change) - - * makefile.w32-in (EMACSSOURCES): Replace major.texi with modes.texi. - -2011-07-10 Lars Magne Ingebrigtsen - - * screen.texi (Mode Line): Clarify that coding systems are - characters, not letters (bug#1749). - - * cmdargs.texi (Environment): Mention removing variables - (bug#1615). Text suggested by Kevin Rodgers. - -2011-07-10 Chong Yidong - - * misc.texi (Amusements): Don't mention Yow; it's crippled. - - * modes.texi: Rename from major.texi. - (Modes): New node. Make Major Modes and Minor Modes subsections - of this. All callers changed. - - * custom.texi (Minor Modes): Move to modes.texi. - -2011-07-10 Chong Yidong - - * custom.texi (Syntax): Node deleted. - - * help.texi (Help Summary): - * major.texi (Major Modes): - * programs.texi (Parentheses): - * search.texi (Regexp Backslash, Regexp Backslash) - (Regexp Backslash): - * text.texi (Words): Callers changed. - - * text.texi (Refill, Longlines): Delete nodes. - - * ack.texi (Acknowledgments): Longlines removed from manual. - - * emacs.texi (Top): Update node listing. - -2011-07-09 Glenn Morris - - * fortran-xtra.texi (Fortran): Update handled extensions. - -2011-07-03 Lars Magne Ingebrigtsen - - * display.texi (Scrolling): `C-v' (etc) are now bound to - `scroll-*-command' (bug#8349). - -2011-07-02 Lars Magne Ingebrigtsen - - * dired.texi (Subdirectories in Dired): Clarify that `C-u k' - doesn't actually delete any files (bug#7125). - - * picture-xtra.texi (Rectangles in Picture): Clarify the prefix - argument for `C-c C-k' (bug#7391). - - * frames.texi (Fonts): Mention "C-u C-x =" to find out what font - you're currently using (bug#8489). - -2011-07-01 Eli Zaretskii - - * mule.texi (Coding Systems): Move index entries from the previous - change into their proper places. - -2011-07-01 Lars Magne Ingebrigtsen - - * help.texi (Help Files): Document view-external-packages (bug#8902). - - * mule.texi (Coding Systems): Put a few more of the coding systems - into the index (bug#8900). - -2011-06-26 Glenn Morris - - * fortran-xtra.texi (Fortran): F90 mode is also for F2008. - -2011-06-25 Andreas Rottmann - - * misc.texi (emacsclient Options): Mention --frame-parameters. - -2011-06-09 Glenn Morris - - * custom.texi (Specifying File Variables): - Recommend explicit arguments for minor modes. - -2011-06-02 Paul Eggert - - Document wide integers better. - * buffers.texi (Buffers): - * files.texi (Visiting): Document maxima for 64-bit machines, - and mention virtual memory limits. - -2011-05-28 Chong Yidong - - * custom.texi (Hooks): Reorganize. Mention Prog mode. - - * fixit.texi (Spelling): Mention using prog-mode-hook for flypsell - prog mode (Bug#8240). - -2011-05-27 Glenn Morris - - * custom.texi (Specifying File Variables): - Major modes no longer need come first. - -2011-05-22 Chong Yidong - - * mule.texi (Specify Coding, Text Coding, Communication Coding) - (File Name Coding, Terminal Coding): Add command names (Bug#8312). - -2011-05-18 Glenn Morris - - * ack.texi (Acknowledgments): Remove fakemail.c. - -2011-05-17 Chong Yidong - - Fixes for fitting text into 7x9 printed manual. - * building.texi (Flymake, Breakpoints Buffer): - * calendar.texi (Appointments): - * cmdargs.texi (General Variables, Display X): - * custom.texi (Saving Customizations, Face Customization) - (Directory Variables, Minibuffer Maps, Init Rebinding): - * display.texi (Font Lock, Font Lock, Useless Whitespace): - * fixit.texi (Spelling): - * frames.texi (Creating Frames, Fonts): - * help.texi (Help Files): - * mini.texi (Minibuffer File): - * misc.texi (emacsclient Options, Emulation): - * msdog.texi (Windows Startup, Windows HOME, Windows Fonts): - * mule.texi (International Chars, Language Environments) - (Select Input Method, Modifying Fontsets, Charsets): - * programs.texi (Custom C Indent): - * rmail.texi (Rmail Labels): - * text.texi (Table Conversion): - * trouble.texi (Known Problems, Known Problems): - * windows.texi (Change Window): - * xresources.texi (GTK resources): Reflow text and re-indent code - examples to avoid TeX overflows and underflows on 7x9 paper. - - * emacs.texi: Fix the (commented out) smallbook command. - - * macos.texi (Mac / GNUstep Events): - * xresources.texi (Lucid Resources): Remove extraneous examples. - -2011-05-10 Glenn Morris - - * custom.texi (Specifying File Variables): - Deprecate using mode: for minor modes. - -2011-05-07 Glenn Morris - - * cal-xtra.texi (Sexp Diary Entries): Mention diary-hebrew-birthday. - -2011-05-06 Glenn Morris - - * calendar.texi (Appointments): Mention appt-warning-time-regexp. - - * cal-xtra.texi (Fancy Diary Display): Mention diary comments. - -2011-05-02 Lars Magne Ingebrigtsen - - * misc.texi (Emacs Server): Document `server-eval-at'. - -2011-04-24 Chong Yidong - - * maintaining.texi (List Tags): Document next-file. - Suggested by Uday S Reddy. - -2011-04-23 Juanma Barranquero - - * mini.texi (Minibuffer Edit): - * screen.texi (Mode Line): Fix typo. - -2011-04-20 Christoph Scholtes - - * maintaining.texi (Old Revisions): Mention new function vc-ediff. - -2011-03-26 Chong Yidong - - * display.texi (Auto Scrolling): Fix scroll-up/scroll-down confusion. - -2011-03-30 Eli Zaretskii - - * display.texi (Auto Scrolling): Document the limit of 100 lines - for never-recentering scrolling with `scroll-conservatively'. - (Bug#6671) - -2011-03-12 Eli Zaretskii - - * msdog.texi (Windows HOME): Fix the wording to clarify how Emacs sets - HOME on Windows and where it looks for init files. (Bug#8221) - -2011-03-10 Eli Zaretskii - - * search.texi (Regexp Example): - * mule.texi (International Chars): - * building.texi (External Lisp): Don't use characters outside - ISO-8859-1. - -2011-03-09 Eli Zaretskii - - * ack.texi (Acknowledgments): Convert to ISO-8859-1 encoding. - Use Texinfo @-commands for non Latin-1 characters. - - * makefile.w32-in (MAKEINFO_OPTS): Add --enable-encoding. - - * custom.texi (Init File): Add index entries for ".emacs". - (Bug#8210) - -2011-03-08 Jan Djärv - - * xresources.texi (GTK resources): ~/.emacs.d/gtkrc does not work - for Gtk+ 3. - -2011-03-08 Glenn Morris - - * Makefile.in (MAKEINFO_OPTS): Add --enable-encoding. - * emacs.texi (Acknowledgments): - * ack.texi (Acknowledgments): Names to UTF-8. - * emacs.texi: Set documentencoding. - - * display.texi (Optional Mode Line): Don't mention exactly where - display-time appears. (Bug#8193) - -2011-03-07 Chong Yidong - - * Version 23.3 released. - -2011-03-06 Chong Yidong - - * search.texi (Isearch Yank): C-y now bound to isearch-yank-kill. - -2011-03-03 Drake Wilson (tiny change) - - * misc.texi (emacsclient Options): Add q/quiet. - -2011-03-02 Glenn Morris - - * mule.texi (Communication Coding) : - Remove duplicate (essentially) paragraph. (Bug#8148) - -2011-03-01 Christoph Scholtes - - * maintaining.texi (Format of ChangeLog): Add reference to - add-log-full-name. - (Change Log Commands): Add documentation for combining multiple - symbols in one change. - -2011-03-01 Glenn Morris - - * custom.texi (Directory Variables): - Give an example of excluding subdirectories. - -2011-02-28 Eli Zaretskii - - * search.texi (Regexp Search): Move index entries about regexps to the - "Regexps" node. Add index entries for regexp search. (Bug#8096) - -2011-02-19 Glenn Morris - - * dired.texi (Dired): Dired-X version number was dropped. - -2011-02-14 Jan Djärv - - * xresources.texi (X Resources): Remove *faceName and replace it with - *font for Lucid. - -2011-02-05 Chong Yidong - - * rmail.texi (Rmail Display): Document Rmail MIME support more - accurately. - - * maintaining.texi (VC Change Log): Document vc-log-incoming and - vc-log-outgoing. - (Merging): Document vc-find-conflicted-file. - -2011-02-05 Glenn Morris - - * custom.texi (Variables): Fix typo. - -2011-01-31 Chong Yidong - - * search.texi (Regexps): Copyedits. Mention character classes - (Bug#7809). - - * files.texi (File Aliases): Restore explanatory text from Eli - Zaretskii, accidentally removed in 2011-01-08 commit. - -2011-01-29 Eli Zaretskii - - * makefile.w32-in (MAKEINFO): Remove options, leave only program name. - (MAKEINFO_OPTS): New variable. - (ENVADD, $(infodir)/emacs): Use $(MAKEINFO_OPTS). - (emacs.html): New target. - (clean): Remove emacs.html. - -2011-01-23 Werner Lemberg - - * Makefile.in (MAKEINFO): Now controlled by `configure'. - (MAKEINFO_OPTS): New variable. Use it where appropriate. - (ENVADD): Updated. - -2011-01-18 Glenn Morris - - * ack.texi, emacs.texi (Acknowledgments): Update for ERT addition. - - * ack.texi (Acknowledgments): Remove mention of replaced prolog.el. - -2011-01-15 Chong Yidong - - * building.texi (Compilation): Improve instructions for running two - compilations (Bug#7573). - - * files.texi (Backup Names): Document the new location of the - last-resort backup file. - - * files.texi (File Aliases): Move directory-abbrev-alist doc from Lisp - manual. Explain why directory-abbrev-alist elements should be anchored - (Bug#7777). - -2011-01-15 Eli Zaretskii - - * msdog.texi (Windows Startup): Correct inaccurate description of - differences between emacsclient.exe and emacsclientw.exe. - -2011-01-02 Chong Yidong - - * rmail.texi (Rmail Display): Edit for grammar and conciseness. - -2011-01-02 Kenichi Handa - - * rmail.texi (Rmail Display): Describe new features of Rmail in Info. - -2011-01-02 Eli Zaretskii - - * frames.texi (Cut and Paste): Modify the section's name and text: - don't mix "cut/paste" with "kill/yank". - (Cut/Paste Other App): Describe the per-session emulation of PRIMARY. - (Bug#7702) - - * trouble.texi (Checklist): Mention debug-on-quit. (Bug#7667) - -2011-01-02 Glenn Morris - - * maintaining.texi: Move inclusion of emerge after EDE, so that it - matches its position in the menu. (Bug#7674) - -2011-01-02 Glenn Morris - - * trouble.texi (Checklist): Mention not replying via news either. - -2010-12-30 Tassilo Horn - - * misc.texi (Document View): Update DocView section with newly - supported document formats. - -2010-12-21 Chong Yidong - - * killing.texi: Resection the Info version to conform to the - printed manual, to avoid making sections on Accumulating Text, CUA - and Rectangles into full chapters. - -2010-12-13 Eli Zaretskii - - * custom.texi (Init Syntax): Add index entries for "character syntax". - (Bug#7576) - -2010-12-13 Karel Klíč - - * text.texi (HTML Mode): Small fixes. (Bug#7607) - -2010-12-13 Glenn Morris - - * trouble.texi (Checklist): Fix typo in newsgroup name. - -2010-12-13 Chong Yidong - - * search.texi (Word Search): Note that the lazy highlight always - matches to whole words (Bug#7470). - -2010-12-13 Eli Zaretskii - - * display.texi (Optional Mode Line): Make the description of - load-average more accurate. - - * msdog.texi (Windows HOME): Mention that HOME can also be set in the - registry, with a cross-reference. - (Windows Startup): New node. Move the stuff about the current - directory from "Windows HOME". - -2010-11-27 Bob Rogers - - * maintaining.texi (VC With A Locking VCS, VC Directory Commands): - * vc1-xtra.texi (Customizing VC, General VC Options): Small fixes. - -2010-11-27 Chong Yidong - - * maintaining.texi (Version Control Systems): Fix repeated sentence. - Suggested by Štěpán Němec. - -2010-11-27 Chong Yidong - - * maintaining.texi (Version Control): Say "commit", not "check in". - (Version Control Systems): Simplify descriptions. - (VCS Merging, VCS Changesets, VCS Repositories): New nodes, split from - VCS Concepts. - (VC Mode Line): Update example. - (Old Revisions): Document revert-buffer for vc-diff. - (Log Buffer): Promote to a subsection. Document header lines. - - * macos.texi (Mac / GNUstep Basics): - Document ns-right-alternate-modifier. - - * emacs.texi (Top): Update node listing. - -2010-11-13 Eli Zaretskii - - * rmail.texi (Rmail Coding): Characters with no fonts are not - necessarily displayed as empty boxes. - - * mule.texi (Language Environments, Fontsets): Characters with no - fonts are not necessarily displayed as empty boxes. - - * display.texi (Text Display): Document display of glyphless - characters. - -2010-11-13 Glenn Morris - - * basic.texi (Position Info): Add M-x count-words-region. - -2010-11-11 Glenn Morris - - * msdog.texi (ls in Lisp): Update for ls-lisp changes. - -2010-11-09 Eli Zaretskii - - * msdog.texi (Windows HOME): Add information regarding startup - directory when invoking Emacs from a desktop shortcut. (bug#7300) - -2010-10-11 Glenn Morris - - * Makefile.in (MAKEINFO): Add explicit -I$srcdir. - - * Makefile.in (.texi.dvi): Remove unnecessary suffix rule. - (DVIPS): New variable. - (.PHONY): Add html, ps. - (html, emacs.html, ps, emacs.ps, emacs-xtra.ps): New targets. - (clean): Delete html, ps files. - -2010-10-09 Eli Zaretskii - - * makefile.w32-in (EMACSSOURCES): Add emacsver.texi. - -2010-10-09 Glenn Morris - - * Makefile.in (VPATH): Remove. - (infodir): Make it absolute. - (mkinfodir, $(infodir)/emacs, infoclean): No need to cd $srcdir. - - * Makefile.in (dist): Anchor regexps. - - * Makefile.in (EMACSSOURCES): Put emacs.texi first. - ($(infodir)/emacs, emacs.dvi, emacs.pdf, emacs-xtra.dvi) - (emacs-xtra.pdf): Use $<. - - * Makefile.in (infoclean): Remove harmless, long-standing error. - - * Makefile.in ($(infodir)): Delete rule. - (mkinfodir): New. - ($(infodir)/emacs): Use $mkinfodir instead of infodir. - - * Makefile.in (distclean): Do not delete emacsver.texi. - (dist): Remove reference to emacsver.texi.in. - * emacsver.texi: New file, replacing emacsver.texi.in. - -2010-10-09 Glenn Morris - - * emacsver.texi.in: New file. - * emacs.texi: Set EMACSVER by including emacsver.texi. - * Makefile.in (distclean): Delete emacsver.texi. - (dist): Copy emacsver.texi. - (EMACSSOURCES): Add emacsver.texi. - - * ack.texi (Acknowledgments): No more b2m.c. - - * Makefile.in (.PHONY): Declare info, dvi, pdf, dist. - (emacs): Remove rule. - (dist): No need to deal with the emacs rule any more. - -2010-10-07 Glenn Morris - - * Makefile.in (version): New, set by configure. - (clean): Delete dist tar file. - (dist): Use version in tar name. - -2010-10-06 Glenn Morris - - * Makefile.in (EMACS_XTRA): Add the main source file. - (emacs-xtra.dvi, emacs-xtra.pdf): Remove explicit emacs-xtra.texi. - (mostlyclean): No core files, reorder other files. - (clean): Delete specific dvi and pdf files. - (infoclean, dist): New rules. - (maintainer-clean): Use infoclean. - ($(infodir)): Add parallel build workaround. - -2010-10-04 Glenn Morris - - * Makefile.in (SHELL): Set it. - (INFO_TARGETS, DVI_TARGETS): Remove variables. - (info, dvi): Replace above variables with their expansions. - (info): Move mkdir from here... - ($(infodir)/emacs): ... to here (for parallel builds). - (pdf): New target. - ($(infodir)/emacs): Pass -o option to makeinfo. - (.PHONY): Declare clean rules. - (maintainer-clean): Delete dvi and pdf files. - Guard against cd failures. Use a more restrictive delete. - -2010-10-02 Glenn Morris - - * misc.texi (Shell Mode): Remove reference to old function name. - -2010-09-30 Eli Zaretskii - - * maintaining.texi (VC Mode Line): Mention all the possible VC status - indicator characters. - -2010-09-29 Glenn Morris - - * Makefile.in (top_srcdir): Remove unused variable. - -2010-09-14 Glenn Morris - - * cal-xtra.texi (Fancy Diary Display): Emphasize that sort should be - the last hook item. - - * calendar.texi (Appointments): Also updated when a diary include file - is saved. - -2010-09-14 Glenn Morris - - * trouble.texi (Bugs): Update the section intro. - (Known Problems): New section. - (Checklist): Misc updates. Prefer M-x report-emacs-bug. - (Sending Patches): Bug fixes are best as responses to existing bugs. - * emacs.texi (Known Problems): Add menu entry for new section. - -2010-09-09 Glenn Morris - - * xresources.texi: Untabify. - -2010-09-06 Chong Yidong - - * dired.texi (Dired Enter): Minor doc fix (Bug#6982). - -2010-09-06 Glenn Morris - - * misc.texi (Saving Emacs Sessions): Mention desktop-path. (Bug#6948) - -2010-09-02 Jan Djärv - - * frames.texi (Cut/Paste Other App): Remove vut-buffer text. - -2010-08-21 Glenn Morris - - * misc.texi (Amusements): Mention bubbles and animate. - -2010-07-31 Eli Zaretskii - - * files.texi (Visiting): Add more index entries for - large-file-warning-threshold. - -2010-07-29 Jan Djärv - - * frames.texi (Tool Bars): Add doc for tool-bar-position. - -2010-06-23 Glenn Morris - - * abbrevs.texi, basic.texi, buffers.texi, building.texi, calendar.texi: - * custom.texi, dired.texi, display.texi, emacs.texi, emerge-xtra.texi: - * files.texi, fortran-xtra.texi, frames.texi, help.texi, killing.texi: - * maintaining.texi, mark.texi, mini.texi, misc.texi, msdog.texi: - * mule.texi, programs.texi, rmail.texi, screen.texi, search.texi: - * sending.texi, text.texi, trouble.texi, vc1-xtra.texi, xresources.texi: - Untabify Texinfo files. - -2010-06-10 Glenn Morris - - * basic.texi (Inserting Text): Minor clarification. (Bug#6374) - - * basic.texi (Inserting Text): Fix typo. - -2010-06-10 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Update for notifications.el. - -2010-05-31 Daiki Ueno - - * dired.texi (Operating on Files): Mention encryption commands - (Bug#6315). - -2010-05-29 Eli Zaretskii - - * basic.texi (Moving Point): Update due to renaming of commands bound - to arrows. Document bidi-aware behavior of C- and C-. - -2010-05-18 Eli Zaretskii - - * display.texi (Fringes): Document reversal of fringe arrows for R2L - paragraphs. - (Line Truncation): Fix wording for bidi display. - - * basic.texi (Moving Point): Document bidi-aware behavior of the arrow - keys. - -2010-05-08 Chong Yidong - - * building.texi (GDB Graphical Interface): Remove misleading comparison - to an IDE (Bug#6128). - -2010-05-08 Štěpán Němec (tiny change) - - * programs.texi (Man Page): - * misc.texi (Invoking emacsclient): - * mini.texi (Repetition): - * mark.texi (Setting Mark): Fix typos. - -2010-05-08 Chong Yidong - - * misc.texi (Printing): Document htmlfontify-buffer. - -2010-05-08 Glenn Morris - - * calendar.texi (Displaying the Diary, Format of Diary File): - Fix external cross-references for TeX format output. - -2010-05-07 Chong Yidong - - * Version 23.2 released. - -2010-05-02 Jan Djärv - - * cmdargs.texi (Initial Options): Mention --chdir. - -2010-04-21 Jan Djärv - - * frames.texi (Tool Bars): Add tool-bar-style. - -2010-04-21 Glenn Morris - - * ack.texi, emacs.texi (Acknowledgments): Add SELinux support. - -2010-04-18 Chong Yidong - - * programs.texi (Semantic): New node. - - * maintaining.texi (EDE): New node. - - * emacs.texi: Update node listing. - - * misc.texi (Gnus): Use the `C-h i' keybinding for info. - -2010-04-18 Glenn Morris - - * emacs.texi (Acknowledgments): Remove duplicate. - - * maintaining.texi (VC Directory Commands): Mention stashes and shelves. - -2010-04-18 Glenn Morris - - * dired.texi (Misc Dired Features): Mention VC diff and log. - * maintaining.texi (Old Revisions, VC Change Log): - Mention that diff and log work in Dired buffers. - - * help.texi (Help Summary): Mention M-x info-finder. - - * ack.texi (Acknowledgments): Add mpc.el. - - * custom.texi (Specifying File Variables, Directory Variables): - Document new commands for manipulating local variable lists. - -2010-04-18 Glenn Morris - - * trouble.texi (Contributing): Add cindex entry. - Mention etc/CONTRIBUTE. - -2010-04-18 Chong Yidong - - * mark.texi (Persistent Mark): Copyedits. Replace undo example with - query-replace (Bug#5774). - -2010-04-16 Glenn Morris - - * ack.texi, emacs.texi (Acknowledgments): Update for Org changes. - -2010-04-11 Jan Djärv - - * xresources.texi (Lucid Resources): Mention faceName for dialogs. - -2010-04-08 Jan Djärv - - * xresources.texi (Lucid Resources): Mention faceName to set Xft fonts. - -2010-03-30 Eli Zaretskii - - * mule.texi (Input Methods): Mention "C-x 8 RET" and add a - cross-reference to "Inserting Text". - - * basic.texi (Inserting Text): Add an index entry for "C-x 8 RET". - Mention completion provided by `ucs-insert'. - -2010-03-30 Chong Yidong - - * sending.texi (Sending Mail): Note variables that may need - customizing. - (Mail Sending): Expand discussion of send-mail-function. - -2010-03-30 Chong Yidong - - Document Message mode as the default mail mode. - - * sending.texi (Sending Mail): Copyedits. - (Mail Format, Mail Headers): Document mail-from-style changes. - (Mail Commands): Rename from Mail mode. Document Message mode. - (Mail Misc): Rename from Mail mode Misc. - (Mail Sending, Header Editing, Mail Misc): Switch to Message mode - command names and update keybindings. - (Header Editing): Document message-tab. De-document - mail-self-blind, mail-default-reply-to, and mail-archive-file-name in - favor of mail-default-headers. Ad index entries for user-full-name and - user-mail-address. - (Citing Mail): Update changes in Message mode behavior. - Document mail-yank-prefix. - (Mail Signature): New node, moved from Mail Misc. - (Mail Aliases): Mail abbrevs are the default with Message mode. - (Mail Methods): Note that Message mode is now the default. - - * rmail.texi (Rmail Reply): - * text.texi (Text Mode): - * major.texi (Major Modes): - * mule.texi (Output Coding): Refer to Message mode. - - * custom.texi (Init Examples): Add xref to Mail Header. - - * emacs.texi (Top): Fix xrefs. - -2010-03-30 Chong Yidong - - * maintaining.texi (VC With A Merging VCS): C-x v v now creates a - repository if there is none. - (VC Change Log): Rename from VC Status. Document vc-log-show-limit and - vc-print-root-log. - (Old Revisions): Copyedits. Document vc-root-diff. - - * programs.texi (Program Modes): Mention Javascript mode. - - * text.texi (HTML Mode): Note that nXML is now the default XML mode. - * emacs.texi: Update node description. - - * misc.texi (Navigation): Document doc-view-continuous. - (Shell Ring): Document new M-r binding. M-s is no longer bound. - -2010-03-30 Juri Linkov - - * search.texi (Other Repeating Search): Remove line that `occur' - can not handle multiline matches. - -2010-03-30 Eli Zaretskii - - * mule.texi (International): Mention support of bidirectional editing. - (Bidirectional Editing): New section. - -2010-03-28 Nick Roberts - - * emacs.texi (Top): Update node names to those in building.texi. - -2010-03-27 Nick Roberts - - * building.texi: Describe restored GDB/MI functionality - removed by 2009-12-29T07:15:34Z!nickrob@snap.net.nz. - * emacs.texi: Update node names for building.texi. - -2010-03-24 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Fix ispell attribution. (Bug#5759) - -2010-03-20 Jan Djärv - - * xresources.texi (Table of Resources): Clarify toolBar number - for Gtk+. - - * frames.texi (Menu Bars): menuBarLines => menuBar (bug#5736). - -2010-03-21 Chong Yidong - - * dired.texi (Dired Updating): Document dired-auto-revert-buffer. - - * search.texi (Other Repeating Search): Document multi-isearch-buffers - and multi-isearch-buffers-regexp. - - * indent.texi (Indentation): Clarify description of - indent-for-tab-command. Document tab-always-indent. - -2010-03-20 Chong Yidong - - * cmdargs.texi (Font X): Move most content to Fonts. - - * frames.texi (Fonts): New node. Document font-use-system-font. - - * emacs.texi (Top): - * xresources.texi (Table of Resources): - * mule.texi (Defining Fontsets, Charsets): Update xrefs. - -2010-03-10 Chong Yidong - - * Branch for 23.2. - -2010-03-06 Chong Yidong - - * custom.texi (Init Examples): Add xref to Locals. - - * major.texi (Choosing Modes): Mention usage of setq-default for - setting the default value of major-mode (Bug#5688). - -2010-03-02 Chong Yidong - - * frames.texi (Mouse Avoidance): Mention make-pointer-invisible. - - * display.texi (Display Custom): Document make-pointer-invisible and - underline-minimum-offset. Remove inverse-video. - -2010-02-21 Chong Yidong - - * frames.texi (Frame Commands): Note that the last ordinary frame can - be deleted in daemon mode (Bug#5616). - -2010-02-18 Glenn Morris - - * trouble.texi (Contributing): Repository is no longer CVS. - -2010-02-08 Glenn Morris - - * buffers.texi (Uniquify): Must explicitly load library. (Bug#5529) - -2010-02-01 Stefan Monnier - - * display.texi (Useless Whitespace, Text Display): - * custom.texi (Init Examples): Avoid obsolete special default variables - like default-major-mode. - -2010-01-24 Mark A. Hershberger - - * programs.texi (Other C Commands): Replace reference to obsolete - c-subword-mode. - -2010-01-21 Glenn Morris - - * trouble.texi (Bugs): Fix PROBLEMS keybinding. - -2010-01-12 Glenn Morris - - * trouble.texi (Checklist): Use bug-gnu-emacs rather than - emacs-pretest-bug for bug reports for development versions. - -2010-01-11 Glenn Morris - - * display.texi (Highlight Interactively): `t' does not mean highlight - all patterns. (Bug#5335) - -2009-12-29 Chong Yidong - - * misc.texi (Shell): Document async-shell-command. - - * building.texi (Grep Searching): Document zrgrep. - - * mini.texi (Completion Options): Mention `initials' completion style. - -2009-12-29 Nick Roberts - - * building.texi: Import GDB Graphical Interface description from - EMACS_23_1_RC. - -2009-12-24 Chong Yidong - - * emacs.texi (Top): Update node listing. - - * abbrevs.texi (Saving Abbrevs): Abbrev file should be in .emacs.d. - - * basic.texi (Moving Point): M-r is now move-to-window-line-top-bottom. - - * cmdargs.texi (Initial Options): - * xresources.texi (Resources): Document inhibit-x-resources. - - * custom.texi (Specifying File Variables): Note that minor modes are - enabled unconditionally. - - * display.texi (Scrolling): Briefly document the old recenter command, - and document recenter-positions. - - * files.texi (Visiting): - * buffers.texi (Buffers): Max buffer size is now 512 MB. - - * frames.texi (Cut/Paste Other App): - Document save-interprogram-paste-before-kill. - - * killing.texi (Kill Options): New node. - -2009-12-05 Chong Yidong - - * misc.texi (Shell Options): ansi-color is now default. - -2009-12-05 Glenn Morris - - * emacs.texi (Top): Update menu for cal-xtra node changes. - * calendar.texi (Displaying the Diary): Holidays may be in the buffer - or mode line. Don't mention invisible text or the details of - diary-print-entries here, only in cal-xtra. - (Format of Diary File): Mention that the "date on first line" format - only really affects the simple display. - * cal-xtra.texi (Advanced Calendar/Diary Usage): Update menu. - (Diary Customizing): Holidays may be in the buffer or mode line. - Move diary-print-entries to the "Diary Display" section. - (Diary Display): New section, split out from "Fancy Diary Display". - Explain the limitations of simple display, and how to print it. - - * calendar.texi (Displaying the Diary): Mention keys apply to calendar. - - * cal-xtra.texi (Diary Display): Mention View mode. - -2009-11-29 Juri Linkov - - * display.texi (Highlight Interactively): Actually a list of - default faces is pre-loaded into a list of default values - instead of the history. - -2009-11-20 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Add htmlfontify. - -2009-11-14 Glenn Morris - - * cal-xtra.texi (Holiday Customizing): Replace obsolete alias. - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Update for recent Org changes. - -2009-10-31 Chong Yidong - - * mule.texi (Charsets): Numerous copyedits. Don't discuss the - `charset' property, which is irrelevant to the user manual (Bug#3526). - -2009-10-14 Juanma Barranquero - - * trouble.texi (DEL Does Not Delete): Fix typo. - -2009-10-05 Michael Albinus - - * files.texi (Misc File Ops): Mention copy-directory. - -2009-10-04 Eli Zaretskii - - * mule.texi (Unibyte Mode): Emphasize that - unibyte-display-via-language-environment affects only the display. - - * display.texi (Horizontal Scrolling): Document cursor behavior under - horizontal scrolling when point moves off the screen (Bug#4564). - Improve wording. - -2009-10-01 Michael Albinus - - * files.texi (Directories): delete-directory prompts for recursive - deletion. - -2009-09-30 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): CEDET updates. Fix Hungarian accent. - -2009-09-25 Tassilo Horn - - * dired.texi (Dired Navigation): Use @code instead of @var for - dired-isearch-filenames, so that it's not capitalized. - -2009-09-19 Chong Yidong - - * frames.texi (Frame Commands): C-z is now bound to suspend-frame. - - * entering.texi (Exiting): C-z is now bound to suspend-frame. - - * custom.texi (Init Examples): Replace Rumseld with Cheny (Bug#3519). - (Key Bindings): Reference Init Rebinding in introductory text. - Shift some of the introduction to Keymaps node. - (Keymaps): Simplify. - (Local Keymaps): Simplify. Move binding example to Init Rebinding. - (Minibuffer Maps): Remove mention of Mocklisp. - (Init Rebinding): Move mode-local rebinding example here from Local - Keymaps. - (Modifier Keys): Clarify. - (Rebinding): Add cindex for "binding keys". - -2009-09-13 Chong Yidong - - * misc.texi (Invoking emacsclient): Minor clarifications (Bug#4419). - -2009-08-31 Nick Roberts - - * building.texi (Threads Buffer, Multithreaded Debugging): - Reorganize these two sections. - -2009-08-29 Eli Zaretskii - - * cmdargs.texi (Initial Options): Fix last change. - -2009-08-29 Stefan Monnier - - * mule.texi (Enabling Multibyte): - * cmdargs.texi (General Variables): Remove EMACS_UNIBYTE. - (Initial Options): Remove --(no-)multibyte, --(no-)unibyte. - -2009-08-20 Glenn Morris - - * cal-xtra.texi (Non-Gregorian Diary): Mention ``Adar I'' special case. - -2009-08-19 Glenn Morris - - * ack.texi (Acknowledgments): Remove cvtmail. Mention info-finder. - -2009-08-18 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Update for js.el replacing js2-mode.el. - - * ack.texi (Acknowledgments): Add ucs-normalize.el and files-x.el. - -2009-08-09 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): Add gdb-mi entry. - -2009-08-08 Dmitry Dzhus - - * emacs.texi (Top): Add new menu items for GDB-UI. - - * building.texi (GDB Graphical Interface): Add Multithreaded debugging - section. Threads buffer is in separate section now. - -2009-08-08 Glenn Morris - - * ack.texi (Acknowledgments): - * emacs.texi (Acknowledgments): - Update for js2-mode and org changes. - -2009-08-02 Michael Albinus - - * files.texi (Reverting): Auto-Revert Tail mode works also for remote - files. - -2009-07-28 Chong Yidong - - * building.texi (Lisp Libraries): Clarify meaning of autoloading. - -2009-07-23 Glenn Morris - - * programs.texi (Matching): Update blink-matching-paren-distance. - -2009-07-21 Chong Yidong - - * frames.texi (Cut/Paste Other App): For select-active-regions, - selection is now updated on moving point. - -2009-07-21 Richard Stallman - - * glossary.texi (GNU, Daemon): Update information. - -2009-07-19 Juri Linkov - - * custom.texi (Specifying File Variables, Safe File Variables): - "variables/value pairs" -> "variable/value pairs". - -2009-07-15 Glenn Morris - - * misc.texi (Gnus): Remove widow. - -2009-07-11 Glenn Morris - - * Makefile.in (TEXI2PDF): New. - (emacs.pdf, emacs-xtra.pdf): New targets. - - * arevert-xtra.texi (Autorevert): Add menu descriptions. - - * display.texi (Horizontal Scrolling): Re-word to remove widow. - - * emacs.texi (Top): Info can be read from other places than Emacs. - Don't print the copying notice twice in the printed version. - Update the menu and detailmenu. - (Preface): The meaning of "on-line" has changed. - Correct name for "Common Problems" chapter. - (Distrib): Update FSF shop URL. - (Intro): Showing two files at once is not so exciting. - - * macos.texi (Mac OS / GNUstep): Fix spelling and cross-reference. - (Mac / GNUstep Basics): Minor grammar changes. - (Mac / GNUstep Events): Fix typo. - (GNUstep Support): CANNOT_DUMP no longer applies. - - * misc.texi (Document View): Fix typos. - - * dired.texi (Dired): - * help.texi (Help): - * macos.texi (Mac OS / GNUstep): - * maintaining.texi (Version Control, Introduction to VC): - End menu descriptions with a period. - -2009-07-09 Eli Zaretskii - - * msdog.texi (Windows Files) : Don't be - so categorical in saying that the option is only useful on NTFS. - -2009-07-09 Glenn Morris - - * Makefile.in (texinfodir): New variable, with location of texinfo.tex. - (ENVADD): Add texinfodir to TEXINPUTS. - - * emacs.texi (Top): Fix cross-reference. - - * maintaining.texi (VC Directory Buffer): Fix cross-reference. - - * vc1-xtra.texi (Revision Tags): Fix typo. - -2009-07-03 Glenn Morris - - * emerge-xtra.texi (Emerge): Tweak Misc menu description. - (Submodes of Emerge): Skip Prefers is only relevant with an ancestor. - (Merge Commands): `.' does not seem to work in A or B buffer. - `l' can recreate the 3-window display. - - * glossary.texi (Glossary): Minor phrasing changes throughout. - Add more internal cross-references. - : You can't really autoload a variable. - : Move details here from `M-C-' item. - : Refer to `Truncation.' - : - : New entries. - : Mention recycle bins. - : Mention ``folders.'' - : Don't mention ``type-ahead.'' - : Refer to the manual node. - : Can be global or local. - : There are other checkers besides Ispell. - -2009-07-02 Glenn Morris - - * anti.texi (Antinews): Minor changes in phrasing. - - * cal-xtra.texi, fortran-xtra.texi: Re-order a few things to reduce - some underfull lines in dvi output. - - * emacs-xtra.texi (Introduction): Mention included in info Emacs manual. - - * sending.texi (Mail Sending): Add a tiny bit on mailclient. - - * vc-xtra.texi (Advanced VC Usage): End all menu items with a period. - -2009-07-01 Jan Djärv - - * xresources.texi (Table of Resources): Mention maximized for - fullscreen. - - * cmdargs.texi (Window Size X): -mm/--maximized is new. - -2009-07-01 Chong Yidong - - * anti.texi (Antinews): Correct the list of removed platforms. - -2009-06-28 Glenn Morris - - * arevert-xtra.texi: Minor language tweaks. - - * dired-xtra.texi: Minor revisions. - -2009-06-23 Miles Bader - - * display.texi (Scrolling): Document `recenter-redisplay'. - (Temporary Face Changes): Document `text-scale-set'. - -2009-06-21 Chong Yidong - - * Branch for 23.1. - -2009-06-17 Kenichi Handa - - * mule.texi (Charsets): Update the description for the new charset. - (list-character-sets): New findex. - (Language Environments): Add @anchor{Describe Language Environment}. - -2009-06-10 Chong Yidong - - * basic.texi (Moving Point): Fix tag. - - * picture-xtra.texi (Insert in Picture): Use and . - - * mini.texi (Completion Commands): Decapitalize and , and - use camel-case for PageUp and PageDown. - - * display.texi (Scrolling): Decapitalize and , and use - camel-case for PageUp and PageDown. - - * calendar.texi (Scroll Calendar): Decapitalize and . - - * search.texi (Isearch Scroll): Add isearch-allow-scroll to index. - (Isearch Scroll): Decapitalize and . - -2009-06-09 Agustín Martín - - * fixit.texi (Spelling): Set default dictionary. - Improve descriptions (Bug#2554) - -2009-06-08 David Reitter - - * macos.texi (Color panel, Font panel): Remove mention of Save Options, - since saving colors and faces set this way is not implemented. - (Environment variables): Remove mention of mac-fix-env, which is - scheduled to be removed. - -2009-06-04 Chong Yidong - - * custom.texi (Init Examples): Add example of changing load-path. - - * building.texi (Lisp Libraries): Add example of changing - load-path (Bug#3446). - -2009-05-28 Chong Yidong - - * mark.texi (Mark): Further clarifications. - (Setting Mark): Emphasize that C-SPC activates the mark. - -2009-05-28 Chong Yidong - - * mark.texi (Mark): Clarify introduction. Mention disabling Transient - Mark mode. - (Using Region, Persistent Mark): Use "active mark" instead of "active - region". - -2009-05-16 Ari Roponen (tiny change) - - * mule.texi (Select Input Method): Fix typo. - -2009-05-13 Chong Yidong - - * anti.texi (Antinews): Document completion changes. Some additional - copyedits and rearrangement of entries. - -2009-05-12 Chong Yidong - - * misc.texi (Interactive Shell, Saving Emacs Sessions) - (Shell History Copying, Terminal emulator): Copyedits. - - * xresources.texi (Resources): Simplify descriptions. - Shorten description of editres, which is not very useful these days. - (Table of Resources): Document fontBackend resource. - - * trouble.texi (Quitting): Add other undo bindings to table. - (DEL Does Not Delete): Note that the erasure key is usually labeled - "Backspace". Remove discussion of obscure Xmodmap issue. - -2009-05-07 Chong Yidong - - * files.texi (Visiting): Copyedits. - -2009-05-06 Chong Yidong - - * basic.texi (Inserting Text): Document ucs-insert. - - * mule.texi (International Chars): Define "multibyte". Note that - internal representation is unicode-based. Simplify definition of raw - bytes. Mention ucs-insert. - (Enabling Multibyte): Remove obsolete discussion. Copyedits. - (Language Environments): Add language environments new to Emacs 23. - (Multibyte Conversion): Node deleted. - (Coding Systems): Remove obsolete unify-8859-on-decoding-mode. - Don't mention obsolete emacs-mule coding system. - (Output Coding): Copyedits. - - * emacs.texi (Top): Update node listing. - -2009-05-05 Per Starbäck (tiny change) - - * trouble.texi (Lossage): Use new binding of view-emacs-problems. - -2009-04-28 Stefan Monnier - - * building.texi (Lisp Libraries): `load-library' does offer completion. - -2009-04-28 Chong Yidong - - * frames.texi (Text-Only Mouse): Mention gpm-mouse-mode instead of - t-mouse-mode. Suggested by Per Starbäck (Bug#3126). - -2009-04-25 Eli Zaretskii - - * maintaining.texi (Tags): Clarify text. (Bug#3101) - -2009-04-22 Chong Yidong - - * entering.texi (Entering Emacs): Document initial-buffer-choice. - - * building.texi (Lisp Interaction): Document initial-scratch-message. - -2009-04-18 Juanma Barranquero - - * msdog.texi (Windows Fonts): Fix typos. - - * files.texi (Save Commands): Fix pxref. - -2009-04-18 Chong Yidong - - * files.texi (Save Commands): Mention diff-buffer-with-file. - (Comparing Files): Document diff-buffer-with-file. Suggested by Magnus - Henoch (Bug#3036). - -2009-03-15 Glenn Morris - - * sending.texi (Mail Format): Replace "Sender" with "Message-Id", since - the former is not always used. - (Mail Headers): Use active voice. Add "Mail-reply-to". - Change case of "Id". Avoid repeated "appropriate". - (Mail Aliases): Fix previous change - use an example with a ".", so it - does actually get quoted when expanded. - (Mail Sending): Mailclient is the default on some systems. - (Citing Mail): Mention mail-indentation-spaces. - (Mail Mode Misc): Add an @dfn for "mail signature". - -2009-03-15 Chong Yidong - - * mini.texi (Completion Commands): Describe Emacs 23 completion rules. - (Completion Options): Document read-file-name-completion-ignore-case, - read-buffer-completion-ignore-case, and completion-styles. - Remove description of partial-completion-mode. - -2009-03-14 Glenn Morris - - * sending.texi (Mail Format): Fix typo. Add index entry for - mail-header-separator. - (Mail Headers): Put info about initialization and changing in one place - at the start. Update FCC section for mbox Rmail. Clarify From - section, mention mail-setup-with-from. Clarify Reply-to section. - Add Mail-followup-to and mail-mailing-lists. Clarify References - section. - (Mail Aliases): Update example, make less contentious. - Update for name change of mail-interactive-insert-alias. - (Mail Mode): Remove mention of `%' as a word separator. - (Mail Sending): Mention mail-send-hook. Mention Mailclient. - (Header Editing): Add reply-to, mail-reply-to, and mail-followup-to - commands. Clarify FCC handling. In mail-complete, add reference to - Mail Aliases section, and mention mail-complete-function. - (Citing Mail): Mention mail-yank-ignored-headers and mail-citation-hook. - (Mail Mode Misc): Clarify the mail-signature function. Add basic - signature netiquette. Explain how the mail hooks work when continuing - a composition. - (Mail Amusements): Internationalize the spook section a bit. - Remove the spook mail-setup-hook example, since it doesn't work well. - Mention fortune-file. - (Mail Methods): Mention read-mail-command. - -2009-03-14 David Reitter - - * macos.texi (Mac / GNUstep Basics): Remove references to Prefs panel - and NS resources following recent changes. - -2009-03-10 Jason Rumney - - * msdog.texi (Windows Misc): Remove doc for obsolete variable. Modify - w32-use-visible-system-caret doc to indicate that it should get set - automatically. - (Windows Fonts): Add doc for the uniscribe backend. - -2009-03-08 Dan Nicolaescu - - * maintaining.texi (VC Directory Commands): Fix doc for the x key in - vc-dir. (Bug#2598) - -2009-03-05 Reiner Steib - - * fixit.texi (Spelling): Add turn-on-flyspell. (Bug#2517) - -2009-03-05 Glenn Morris - - * rmail.texi (Rmail Basics): Add reference to sorting. - (Rmail Scrolling, Rmail Motion, Rmail Reply, Rmail Display): - Minor re-wordings. - (Rmail Motion): Mention rmail-next-same-subject. - (Rmail Deletion): Expunging is not the only way to change the numbers. - (Rmail Labels): Labels can also be used in sorting. - (Rmail Summary Edit): Mention rmail-summary-next-same-subject. - (Rmail Display): Mention rmail-mime. - -2009-03-04 Glenn Morris - - * rmail.texi (Rmail Sorting): Add the keybindings associated with each - sort command. Fix `rmail-sort-by-labels' name. Mention sorting from - summary. Mention sorts cannot be undone. - (Rmail Display): Give an example of how to use goto-address-mode. - (Rmail Editing): It's keybindings that are redefined, not commands. - Fix some typos. - (Movemail): Some minor rewording. - (Remote Mailboxes): Emacs movemail supports pop by default. - Fix some minor grammatical issues. The "two alternative ways" to - specify a POP mailbox are really just one. Remove all reference to the - variables rmail-pop-password and rmail-pop-password-required, obsolete - since Emacs 22.1. Clarify the four password steps. Emacs movemail - can support Kerberos. - -2009-03-03 Glenn Morris - - * rmail.texi (Rmail Deletion): Revert previous change, which was - describing the Rmail summary versions. - (Rmail Reply): Give more details of rmail-dont-reply-to-names. - Minor re-wording for rmail-resend. - (Rmail Make Summary): Summaries apply to buffers rather than files. - : Headers includes the subject. - : Give more - details, including prefix arguments. - Mention rmail-summary-by-senders on C-M-f. - Not counting lines might be faster. - (Rmail Summary Edit): More details on the delete commands. - Mention rmail-summary-undelete-many, rmail-summary-bury, and C-M-n/p. - Name the commands bound to the various keys. Mention prefix argument - for searching. - (Rmail Display): Mention rmail-displayed-headers. Fix typo. - Simplify rmail-highlighted-headers description. Update face name. - -2009-03-02 Juanma Barranquero - - * mark.texi (Marking Objects): Fix typo. - -2009-03-01 Chong Yidong - - * abbrevs.texi (Expanding Abbrevs): Mention abbrev-expand-functions - instead of obsolete pre-abbrev-expand-hook. Link to elisp manual. - -2009-03-01 Glenn Morris - - * rmail.texi (Rmail): Fix some typos. Use consistent case in menu. - (Rmail Motion): - M-s searches from the end of messages. - (Rmail Deletion): Minor clarification. Fix numeric argument - description. - (Rmail Inbox): Fix default inbox description. Mention `mbox' by name. - newmail and RMAILOSE files need not be in home-directory. - (Rmail Files): Mention I/O menus are unselectable if no files match. - Mention `MAIL' env-var. - -2009-02-24 Jason Rumney - - * mule.texi (Fontsets): Mention fontset-default, font specs and - fallback fontsets. - (Defining Fontsets): Mention ns and w32 variants of - standard-fontset-spec. Update description of startup fontset to match - Emacs 23 behavior. - (Modifying Fontsets): New section. (Bug#656) - (International): Link to Modifying Fontsets. - -2009-02-23 Adrian Robert - - * macos.texi (Mac / GNUstep Basics, Mac / GNUstep Customization): - Mention ns-extended-platform-support-mode. - -2009-02-22 Karl Berry - - * macos.texi (Mac / GNUstep Customization): One more duplicate "the". - -2009-02-19 Juanma Barranquero - - * basic.texi (Moving Point, Position Info): - * files.texi (Visiting): - * mini.texi (Completion Options): - * text.texi (HTML Mode): Remove duplicate words. - -2009-02-20 Glenn Morris - - * rmail.texi: Minor updates for mbox rather than Babyl. - -2009-02-17 Karl Berry - - * emacs.texi (Top): Add @insertcopying before master menu. (Bug#1988) - -2009-02-17 Richard M Stallman - - * anti.texi (Antinews): Mention Babyl format. - - * emacs.texi (Top): Delete `Out of Rmail' from subnode menu. - - * rmail.texi: Update for mbox format. - Various small fixes, as well as the following. - (Out of Rmail): Node deleted. - (Rmail): Update menu. - (Rmail Files): Comment out set-rmail-inbox-list. - Document rmail-inbox-list instead. - (Rmail Output): Substantial changes since C-o is now - rmail-output-as-seen and o is rmail-output. - (Rmail Attributes): Delete `stored', add `retried'. - (Rmail Display): Editing headers works in all cases. - -2009-02-17 Glenn Morris - - * basic.texi (Position Info): M-x count-lines-region is not always on - M-=. (Bug#2269) - -2009-02-09 Glenn Morris - - * calendar.texi (Holidays, Displaying the Diary): Update for new marker - defaults. - -2009-02-07 Eli Zaretskii - - * rmail.texi (Rmail Coding) : Remove stale - documentation of possible problems with redecoding. - -2009-02-03 Glenn Morris - - * rmail.texi (Out of Rmail): Mention b2m.pl. - -2009-01-31 Glenn Morris - - * rmail.texi (Out of Rmail): Correct b2m location. - -2009-01-27 Chong Yidong - - * fixit.texi (Undo): Update undo limit values. - -2009-01-27 Glenn Morris - - * emacs.texi (Top): Fix Antinews menu entry. - -2009-01-25 Karl Berry - - * text.texi (Foldout): Use @itemize @w{} to make an itemize - item with no marker, instead of the syntactically incorrect - @itemize @asis. - -2009-01-25 Juri Linkov - - * building.texi (Grep Searching): Fix index entry for lgrep. - -2009-01-24 Eli Zaretskii - - * msdog.texi (Windows Printing): Add an index entry for Ghostscript. - -2009-01-21 Adrian Robert - - * macos.texi (Preferences Panel): Update description of font setting to - reflect that prior frame selection is no longer needed. - -2009-01-20 Nick Roberts - - * building.texi (Debuggers): Revert some of 2008-10-31 change to - raise GUD subsections. - -2009-01-15 Glenn Morris - - * ack.texi (Acknowledgments): Another update based mainly on AUTHORS. - -2009-01-10 Glenn Morris - - * ack.texi (Acknowledgments): Some more updates based on AUTHORS. - -2009-01-04 Chong Yidong - - * display.texi (Visual Line Mode): M-] and M-[ no longer move by - logical lines. - -2008-12-29 Juri Linkov - - * mini.texi (Minibuffer History): Add a link to `Isearch Minibuffer'. - - * text.texi (Fill Commands): Replace `M-s' with `M-o M-s'. - -2008-12-28 Chong Yidong - - * misc.texi (Goto Address mode): Rename from Goto-address. Refer to - goto-address-mode instead of goto-address. - - * rmail.texi (Rmail Display): Goto-address renamed to Goto Address - mode. - - * emacs.texi (Top): Update node listing. - -2008-12-26 Eli Zaretskii - - * custom.texi (Directory Variables): Explain what is a "project". - Add indexing. Improve wording. Add a footnote about using - _dir-locals.el on MS-DOS. - -2008-12-24 Dan Nicolaescu - - * files.texi (Misc File Ops): Mention chmod as an alias for - set-file-modes. - -2008-12-24 Martin Rudalics - - * help.texi (Help): Fix typos and reword. - (Help Summary): Add entries for C-h n and C-h r, reorder - entries, and do some minor fixes. - (Name Help): Say that C-h F works for commands only. - (Misc Help): Say that view-lossage displays 300 keystrokes. - -2008-12-20 Glenn Morris - - * ack.texi (Acknowledgments): General update based on AUTHORS, - including removal of some stuff no longer distributed. - -2008-12-19 Agustín Martín - - * fixit.texi: Mention hunspell. - -2008-12-19 Glenn Morris - - * ack.texi (Acknowledgments): Small grammar fix. - Consolidate explanatory text at start. - - * display.texi (Text Display): - * indent.texi (Indentation): Use @acronym with ASCII. - -2008-12-18 Glenn Morris - - * ack.texi: Various small updates and fixes. - -2008-12-18 Juri Linkov - - * search.texi (Word Search): Replace `C-s RET C-w' with `M-s w RET' - as a key binding to start a forward nonincremental word search. - Replace `C-r RET C-w' with `M-s w C-r RET' as a key binding to start - a backward nonincremental word search. Add index for `M-s w' - `isearch-forward-word'. - (Regexp Search): Add a short summary of regexp key commands like - in the node "Basic Isearch". - (Other Repeating Search): Fix typo. - -2008-12-14 Vinicius Jose Latorre - - * misc.texi (PostScript Variables): Fix doc. - -2008-12-10 Chong Yidong - - * programs.texi (Program Modes): Mention Ruby mode. - -2008-12-10 Dan Nicolaescu - - * misc.texi (emacsclient Options): Describe what an empty string - argument does for --alternate-editor. - -2008-12-09 Frank Schmitt - - * cmdargs.texi (Font X): Distinguish between client-side and - server-side fonts. List valid Fontconfig properties. Add reference to - Fontconfig manual. List valid GTK font properties. Explain use of - fc-list. - -2008-12-09 Chong Yidong - - * cmdargs.texi (Font X): Move discussion of quoting to top. - -2008-12-06 Glenn Morris - - * maintaining.texi (Old Revisions): Improve previous change. - -2008-12-05 Richard M Stallman - - * anti.texi (Antinews): Minor fixes. - -2008-12-03 Glenn Morris - - * maintaining.texi (Old Revisions): Fix diff-switches description. - -2008-12-01 Martin Rudalics - - * emacs.texi (Top): Fix typo. - -2008-11-30 Chong Yidong - - * misc.texi (Document View): Explain dependence on gs at the top. - Copyedits. - - * emacs.texi (Top): Add DocView nodes to detailed node listing. - - * programs.texi (Other C Commands): Document hide-ifdef-shadow. - (Comment Commands): Discuss region-active behavior of M-; first. - -2008-11-29 Martin Rudalics - - * display.texi (Line Truncation): Add reference to Continuation - Lines. - - * windows.texi (Pop Up Window): Mention split-height-threshold - and split-width-threshold. - (Split Window): Add reference to Continuation Lines. - -2008-11-28 Adrian Robert - - * macos.texi: Change references to "Mac" to "Mac / GNUstep". - (GNUstep Support): New node. - * anti.texi: - * emacs.texi: - * msdog.texi: Change reference to Mac OS node to Mac OS / GNUstep. - -2008-11-28 Richard M Stallman - - * misc.texi (Dissociated Press): Minor cleanups. - - * dired.texi (Image-Dired): Avoid passive. - -2008-11-28 Eli Zaretskii - - * anti.texi (Antinews): Add stuff about Unicode vs emacs-mule - representation. - -2008-11-26 Richard M. Stallman - - * files.texi (Visiting): Rewrite paragraph for clarity. - - * buffers.texi (Select Buffer): Rewrite paragraphs using active voice. - -2008-11-25 Alan Mackenzie - - * programs.texi (Moving by Parens): Clarify that parens inside strings - and comments are ignored, and that the commands assume the starting - point isn't in a string or comment. - -2008-11-26 Adrian Robert - - * macos.texi: Add Prev/Next/Top pointers to all nodes. - (Mac Basics): Merge in Grabbing Environment Variables from earlier - version. - (Mac Customization): Rewrite Preferences Panel section and merge in to - this node, add Open files by dragging to an Emacs window. - - * emacs.texi: Remove TOC reference to Mac Preferences Panel section. - -2008-11-26 Chong Yidong - - * files.texi (Misc File Ops): Document set-file-modes. - - * windows.texi (Split Window): Document integer values of - truncate-partial-width-windows. - - * text.texi (Text): Simplify description of markup languages. - (TeX Mode): Simplify introduction. Mention BibTeX mode. - (TeX Editing): Note that `""' inserts one `"' character. - (HTML Mode): Note in the introduction that XML mode is an alias for - SGML mode. Mention nXML mode. - -2008-11-25 Chong Yidong - - * building.texi (Watch Expressions): Fix typo. - -2008-11-24 Chong Yidong - - * files.texi (Visiting): Document new behavior of - confirm-nonexistent-file-or-buffer. - - * buffers.texi (Select Buffer): - Document confirm-nonexistent-file-or-buffer. - - * picture-xtra.texi (Picture Mode): Use picture-mode instead of - edit-picture. - - * text.texi (Text): Simplify introduction. Discard mention of `M-x - edit-picture', since that is just an alias for picture-mode. - (Sentences): Note that repeated M-@ extends the region. - (Pages): Make terminology more consistent. Link to Regexps node. - (Longlines): Discuss relationship with Visual Line mode. - (Text Mode): Remove extraneous discussion of other modes, since they - were already introduced in the parent node. - -2008-11-23 Chong Yidong - - * anti.texi (Antinews): Rewrite. - - * entering.texi (Exiting): Mention "minimize" terminology. - - * frames.texi (Frame Commands): Mention "minimize" terminology. - - * cmdargs.texi (Font X): Document Fontconfig and GTK font specification - formats. - (Icons X): Mention "minimize" terminology and use of icons in taskbar. - (Misc X): Don't document useless -hb option. - -2008-11-22 Juri Linkov - - * dired.texi (Dired Navigation): Change normal file name search option - from `non-nil' to `t'. Add `dwim' option. - -2008-11-22 Juri Linkov - - * custom.texi (Directory Variables): Rename ".dir-settings.el" to - ".dir-locals.el". Rename `define-project-bindings' to - `dir-locals-set-class-variables'. Rename `set-directory-project' to - `dir-locals-set-directory-class'. - -2008-11-22 Lute Kamstra - - * buffers.texi (Select Buffer): Index goto-line. - * basic.texi (Moving Point): Mention the use of a numeric prefix - argument with goto-line and refer to Select Buffer for the use of a - plain prefix argument. - -2008-11-19 Glenn Morris - - * doclicense.texi: Update to FDL 1.3. - * emacs.texi, emacs-xtra.texi: Relicense under FDL 1.3 or later. - -2008-11-17 Chong Yidong - - * custom.texi (Minor Modes): Define mode commands and mode variables - more precisely. Recommend using mode commands instead of setting - variables directly. Put minor modes in a list, and add more modes. - (Easy Customization): Use "init file" instead of .emacs. - (Customization Groups): Update to new Custom buffer appearance. - (Saving Customizations): Copyedits. Update example. - (Variables): Give example of variable type-sensitivity. - (Examining): Update example. - (Hooks): Copyedits. - (Specifying File Variables): Use C comments instead of an artificial - Lisp for the example. - (Keymaps): Move internals discussion to Prefix Keymaps. - (Rebinding): Remove redundant paragraph (stated in Key Binding). - (Init Rebinding): Document kbd macro. - (Init File): Link to Find Init. - - * mark.texi (Using Region): Document Delete Selection Mode more - thoroughly. - - * frames.texi (Mouse Commands): Move most of the description of Delete - Selection Mode to Using Region, and link to it. - (Clipboard): Note that paste is bound to clipboard-yank. - - * building.texi (Compilation): Document first-error value of - compilation-scroll-output. - (Compilation Mode): Note that compilation-auto-jump-to-first-error - works as soon as an error is available. Suggested by Juri Linkov. - - * mini.texi (Passwords): New node. - - * files.texi (Remote Files): Link to Passwords node. - - * emacs.texi (Top): Update node listings. - -2008-11-16 Chong Yidong - - * ack.texi (Acknowledgments): Some updating of credits. - - * emacs.texi (Acknowledgments): Add a couple more names. - - * dired.texi (Dired Deletion): Document delete-by-moving-to-trash. - - * files.texi (Directories): Describe delete-directory in text. - (Misc File Ops): Document use of trash. - -2008-11-16 Juanma Barranquero - - * macos.texi (Mac Customization): Fix typos. - -2008-11-14 Chong Yidong - - * macos.texi (Mac OS): Move Cocoa manual from ns-emacs.texi to here, - replacing previous contents. Numerous copyedits to adapt ns-emacs to - the conventions of the main Emacs manual. - - * emacs.texi (Top): Update node listings. - -2008-11-12 Chong Yidong - - * cmdargs.texi (Emacs Invocation): Link to Emacs Server. Note that - command-line-args is processed during startup. - (Action Arguments): Correctly describe how file arguments interact with - the startup screen. Link to Lisp Interaction for scratch buffer. - (Initial Options): Link to Command Example for -batch option. - (Environment): Document initial-environment. - - * entering.texi (Entering Emacs): Note that inhibit-startup-screen - can't be changed in the site-start file. - -2008-11-07 Chong Yidong - - * dired.texi (Dired): Mention C-x C-d too. - (Dired Enter): Document M-n in the Dired minibuffer. - (Dired Navigation): Explain dired-goto-file more clearly. - Document dired-isearch-filenames. - (Dired Deletion): Remove unnecessary "expunged" terminology. - (Flagging Many Files): & is now rebound to `% &'. - (Shell Commands in Dired): Document dired-do-async-shell-command. - Clarify how multi-file arguments are passed. - (Misc Dired Features): Document dired-do-isearch. - -2008-11-06 Chong Yidong - - * entering.texi (Entering Emacs): Document inhibit-startup-screen. - -2008-11-03 Chong Yidong - - * search.texi (Other Repeating Search): Remove obsolete findex entries. - -2008-11-01 Chong Yidong - - * programs.texi (Program Modes): Link to Program Indent node. - (Left Margin Paren): Explain consequences of changing - open-paren-in-column-0-is-defun-start more concisely. - (Which Function, Program Indent, Info Lookup): Minor edits. - (Basic Indent): If region is active, TAB indents the region. - (Multi-line Indent): If region is active, TAB indents the region. - Note that indent-region is useful when Transient Mark mode is off. - (Matching): The delimiter at the cursor is highlighted---the character - changes color. - (Symbol Completion): Link to Completion node. - - * misc.texi (Invoking emacsclient): Describe how to use Emacs server in - a strictly text-only system. - - * abbrevs.texi (Saving Abbrevs): Note that abbrev file is not loaded in - batch mode. - -2008-11-01 Richard M. Stallman - - * misc.texi (Document View): Major rewrite. - - * maintaining.texi (Types of Log File): Change logs are older than - version control. - (VCS Concepts): Simplify and rearrange. - (Version Control Systems): Make it clear that Linux is only the kernel. - (VC Mode Line): Shorten reference to menu item. - (Basic VC Editing): Clarify VC fileset. Shorten and simplify. - (VC Directory Mode): Minor cleanup. - Unchanged files are hidden, not omitted. - (VC Directory Commands): Shorten and simplify. - (Change Log Commands): New node, split from Change Logs. - (VC Directory Buffer): New node, split from VC Directory Mode. - -2008-10-31 Chong Yidong - - * misc.texi (Document View): Rename from Document Files, moved here - from files.texi. - - * files.texi (Version Control): Move to maintaining.texi. - Subnodes moved as well. - (Document Files): Move to misc.texi. - - * maintaining.texi (Change Log): Document log-edit-insert-changelog and - vc-update-change-log. - (Version Control): Move here from files.texi. - (Format of ChangeLog): Make it a subnode of Change Log. - - * emacs.texi (Top): Update node listing. - -2008-10-31 Tassilo Horn - - * files.texi (Files): Add a section about document - files (doc-view-mode). - -2008-10-31 Chong Yidong - - * building.texi (Compilation Mode): - Document compilation-auto-jump-to-first-error. - (Debuggers): Lower GUD subsections to subsubsections. - (Starting GUD): Add cindex. - (Lisp Interaction): Note that scratch is no longer the initial buffer. - -2008-10-30 Chong Yidong - - * indent.texi (Indentation): Link to Program Indent. - - * misc.texi (Invoking emacsclient): If Emacs has no available frame, it - now uses emacsclient's terminal. - -2008-10-29 Chong Yidong - - * mark.texi (Using Region): Document use-empty-active-region. - - * emacs.texi (Top): Update node listings. - - * misc.texi (Emacs Server): Rewrite. Document daemon-mode. - Don't mention obsolete emacs.bash script. - (Invoking emacsclient): Rewrite, moving optional arguments to - emacsclient Options. - (emacsclient Options): New node. Document server-use-tcp and - server-host. - -2008-10-28 Chong Yidong - - * indent.texi (Indentation): Replace list with paragraphed text, - putting description of syntax-driven indentation first. Document new - effect of active regions on tab. - (Tab Stops): Note that editable tab stops affect indentation commands. - -2008-10-27 Dan Nicolaescu - - * cmdargs.texi (Initial Options): Document -daemon=SERVER_NAME. - -2008-10-23 Chong Yidong - - * custom.texi (Function Keys): Note that modified keypad keys are not - translated. - - * basic.texi (Arguments): Explain how to insert multiple digits. - -2008-10-22 Michael Albinus - - * files.texi (Remote Files): Precise selection of default method. - Rewrite paragraph about disabling remote file names. - -2008-10-22 Chong Yidong - - * search.texi (Special Isearch): Document M-TAB is isearch. - - * files.texi (VC Mode Line): Use @kbd instead of @key for mouse - command. - - * frames.texi: Use @kbd instead of @key for mouse commands throughout. - -2008-10-22 Tassilo Horn - - * emacs.texi (Acknowledgments): Add myself to Acknowledgments - section. - -2008-10-21 Chong Yidong - - * vc1-xtra.texi: Move nodes VC Directory Mode and VC Directory Commands - to files.texi. Move contents of vc2-xtra.texi here. - - * vc2-xtra.texi: File removed. - - * vc-xtra.texi (Advanced VC Usage): Remove VC Directory Mode and VC - Directory Commands from the submenu. Don't include deleted file - vc2-xtra.texi. - - * files.texi (Visiting): Document find-file-confirm-nonexistent-file. - (Version Control): Add VC Directory Mode and VC Directory Commands to - the submenu. - (Why Version Control?): Use table format. - (Version Control Systems): Note that Meta-CVS support is gone. - (VCS Concepts): Note precisely when VC started supporting filesets. - Remove bogus xref to CVS Options node. - (Types of Log File): Copyedits. - (VC Mode Line): Document tooltips and mouse-1 on VC indicator. - (Basic VC Editing): Content moved from Selecting A Fileset and Doing - The Right Thing. - (Selecting A Fileset, Doing The Right Thing): Nodes deleted. - (Log Buffer): Reorganize node, putting C-c C-c description first. - (Old Revisions): Use CVS for example, not RCS. - (Secondary VC Commands): Remove VC Directory Mode and VC Directory - Commands from the submenu, putting them under Version Control. - (VC Directory Mode): Move node contents here from vc1-xtra.texi; we - need to include it in the manual unconditionally, since it is now - crucial to using distributed version control systems. - (Comparing Files): Note that diff uses the minibuffer, and that the - output is shown using Diff mode. - (Diff Mode): Explain what "patch" and "hunk" mean. - Document diff-update-on-the-fly, diff-refine-hunk, and - diff-show-trailing-whitespaces. - (File Archives): Add rar support. - - * major.texi (Choosing Modes): Make mode selection sequence more - obvious by describing the steps in order of priority. Note that - magic-mode-alist is nil by default. - Document magic-fallback-mode-alist. - -2008-10-20 Chong Yidong - - * frames.texi (Mouse References): Copyedits. - -2008-10-20 Tassilo Horn - - * ack.texi (Acknowledgments): Add myself as doc-view author. - -2008-10-20 Eli Zaretskii - - * frames.texi (Dialog Boxes): Add @cindex entries. - -2008-10-20 Chong Yidong - - * frames.texi (Dialog Boxes): Clarify description of GTK+ file chooser. - (Text-Only Mouse): Copyedit. - -2008-10-19 Chong Yidong - - * frames.texi: Use @key throughout for mouse clicks. - (Cut/Paste Other App): Document yank-pop-change-selection. - (Secondary Selection): Fix modified mouse click syntax. - (Clipboard): Describe Cut, Copy and Paste commands. - (Mouse References): Not all references are in read-only buffers. - Copyedits. - (Creating Frames): Add xref to Init File. - (Frame Commands): Add xref to Exiting. - (Scroll Bars): Document GTK vs toolkit behavior. - -2008-10-15 Chong Yidong - - * files.texi (Version Control): Copyedits. Add Bazaar. - (Version Control Systems): List different VCS's using an itemized list. - Add Bazaar. - (VCS Concepts): Copyedits. Tweak description of file merging. - - * frames.texi (Mouse Commands, Cut/Paste Other App): Rewrite. - (Cut/Paste Other App): Document select-active-regions and - x-select-enable-primary. - -2008-10-13 Chong Yidong - - * mark.texi (Shift Selection): Correct case in node name. - - * emacs.texi (Top): Update node order in Mark chapter. - -2008-10-12 Eli Zaretskii - - * msdog-xtra.texi (MS-DOS): Fix bad pxref. - - * mini.texi (Minibuffer File): Fix markup in last change. Refer to - elsewhere in the manual instead of describing yet again the intricacies - of $HOME on MS-Windows and MS-DOS. - -2008-10-12 Chong Yidong - - * mini.texi (Minibuffer File): Add xref to File Names. - (Minibuffer File): Add discussion of `~' in file names. - Add insert-default-directory index reference. - - * files.texi (File Names): Reorganize description. - (Visiting): Add xref to Mode Line. Copyedits. - (Save Commands): Mention prefix behavior of C-x C-s. - (Numbered Backups): Node deleted. - (Backup Names): Contents of Numbered Backups moved here. State default - of version-control variable. - (Reverting): Copyedits. - (Version Control): Add additional version control systems. - - * emacs.texi (Top): Delete Numbered Backups node. - - * cmdargs.texi (General Variables): Change Numbered Backups xref to - Backup Names. - (Initial Options): Document renamed variable inhibit-startup-screen. - -2008-10-11 Romain Francoise - - * kmacro.texi (Edit Keyboard Macro): Lossage is now 300 keys. - -2008-10-11 Chong Yidong - - * buffers.texi (Buffers): Add xrefs to Mode Line and Lisp Interaction. - (Select Buffer): Mention use of minibuffer history. Describe default - value of default-major-mode. Mention that C-x 4 b selects the other - window. - (List Buffers): Document CRM indicators in the order they appear. - (Kill Buffer): Document new command kill-matching buffers. - (Several Buffers): Move explanation of the relationship between buffer - list and buffer menu to the top. - (Indirect Buffers): Document new variable clone-indirect-buffer-hook. - -2008-10-10 Chong Yidong - - * entering.texi (Exiting): Document change of C-x C-c to - save-buffers-kill-terminal. Document kill-emacs. - -2008-09-30 Eli Zaretskii - - * mule.texi (Coding Systems): Don't mention codepage-setup. - - * msdog-xtra.texi (MS-DOS Printing, MS-DOS and MULE): No need to create - cpNNN coding systems anymore. - (MS-DOS and MULE): Don't mention code-pages.el. Don't mention support - for unibyte mode. Don't mention line-drawing characters. - Don't mention dos-unsupported-char-glyph. - -2008-09-25 Chong Yidong - - * search.texi (Search): Shorten introduction. - (Basic Isearch): Add command table. Discuss reverse isearch and - isearch highlighting. - (Repeat Isearch): Move lazy highlighting discussion here. Add search - ring to cindex. - (Special Isearch): Move input methods discussion here. - (Non-ASCII Isearch): Node deleted, merged with Special Isearch. - (Isearch Yank): Node deleted, and contents moved into Basic Isearch and - Repeat Isearch. - (Isearch Minibuffer): New node. - (Word Search): Document new word search commands. - (Regexp Example): Simplify example using sentence-end-base variable. - (Replace): Reword introduction. - (Unconditional Replace): Remove unnecessary example. - (Other Repeating Search): Document new `M-s o' binding. - - * emacs.texi (Top): Update node listings. - -2008-09-22 Juanma Barranquero - - * emacs.texi (Top): Remove Kill Errors from menu. - -2008-09-22 Chong Yidong - - * kmacro.texi (Basic Keyboard Macro): Make F3 and F4 the preferred - interface for defining macros. Simplify examples. Note that C-g quits - macro definitions. - (Keyboard Macro Counter): Document using F3 to insert counter. - Give usage example. - (Keyboard Macro Query): Organize query responses in a table. - - * fixit.texi (Fixit): Favor C-/ keybinding for undo throughout. - Link to Erasing node. - (Undo): Reorganize paragraphs for logical flow. Move keybinding - rationale to a footnote. - (Kill Errors): Remove node, due to redundancy with Erasing. - (Spelling): Move discussion of flyspell to end. Note new behavior of - M-$ in active region. Remove non-ispell-specific keybindings from - table. - -2008-09-21 Dan Nicolaescu - - * cmdargs.texi (Initial Options): Document --daemon. - -2008-09-20 Glenn Morris - - * files.texi (Numbered Backups): Mention that some modes set - version-control. - -2008-09-20 Jim Blandy - - * files.texi (Numbered Backups): Reference File Variables, as well. - Remove discussion of Rmail's implementation. - -2008-09-06 Chong Yidong - - * misc.texi (Recursive Edit): Note that top-level exits active - minibuffers. - - * trouble.texi (Quitting): Likewise. - -2008-08-31 Chong Yidong - - * emacs.texi (Top): Add Temporary Face Changes xref. - - * display.texi (Display): Move Temporary Face Changes node to just - after Standard Faces. - (Scrolling): Document recenter-top-bottom instead of recenter. - (Horizontal Scrolling): Move auto hscroll discussion to the top. - (Faces, Standard Faces, Temporary Face Changes, Useless Whitespace) - (Display Custom): Copyedits. - (Optional Mode Line): Document display-battery-mode. - -2008-08-27 Romain Francoise - - * custom.texi (Directory Variables): Minor fix. - -2008-08-27 Glenn Morris - - * cal-xtra.texi (Advanced Calendar/Diary Usage): Tweak some menu - descriptions. - (Calendar Customizing): Tweak layout description. - Move calendar-today-marker and calendar-today face to the other - markers. Condense calendar-star-date and calendar-mark-today - description. - (Holiday Customizing): Add oriental and solar holidays. - Add index entries for Baha'i, Christian, Hebrew and Islamic holidays. - Fix holiday-float description. Use zerop in examples. Be less verbose. - (Date Display Format): Change ISO format. Be less verbose. - (Diary Customizing): Mention day and month abbrev arrays. - Mention the date-form variables by name. Update European example. - (Non-Gregorian Diary): Change node name. Mention Baha'i functions. - Condense examples. Mention diary-entry-symbols by name. - Condense table for insertion commands. - (Fancy Diary Display): Mention diary-include-string and - diary-sexp-entry-symbol. Condense example. Add Chinese, Coptic, - Ethiopic, Persian date functions. Condense descriptions. - - * calendar.texi (Format of Diary File): Mention diary-nonmarking-symbol. - (Adding to Diary): Adapt for changed node name. - -2008-08-26 Glenn Morris - - * cal-xtra.texi (Non-Gregorian Diary Entries): New name for - node "Hebrew/Islamic Entries". - - * calendar.texi (Specified Dates): Fix names of iso functions. - (General Calendar): There may not be another window. - (Writing Calendar Files, Holidays): Tweak intro. - (Holidays): Mention Baha'i and Chinese holidays. - (Sunrise/Sunset): Add M-x calendar-sunrise-sunset-month. - (Lunar Phases): Remove incorrect reference to calendar-time-zone. - (To Other Calendar): Add calendar-print-other-dates. - Refer to "graphic display" rather than "X. - (From Other Calendar): Add calendar-bahai-goto-date. Fix reference. - (Displaying the Diary): Fix whitespace after reference. - Fix `diary-number-of-entries' reference. - (Date Formats): Explicitly mention that day names can be abbreviated. - (Adding to Diary): Add some references to other sections. - (Special Diary Entries): Fix reference. - (Appointments): Simplify appt-message-warning-time entry. - Clarify where times must be. - (Importing Diary): Comment out icalendar paragraph that does not apply. - (Time Intervals): Simplify entry for timeclock-ask-before-exiting. - -2008-08-23 Glenn Morris - - * fortran-xtra.texi (Fortran): Change description of free form and - fixed form a bit. Mention hideshow and imenu. - (Fortran Motion): Mention fortran-end-of-subprogram, - fortran-beginning-of-subprogram, fortran-mark-do, fortran-mark-if. - (Fortran Indent): Minor re-word. - (ForIndent Commands): Mention fortran-fill-paragraph and - fortran-fill-statement. - (ForIndent Cont): Mention fortran-tab-mode-string. - (Fortran Comments): Mention fortran-comment-line-start-skip. - (Fortran Columns): Mention font-locking. - (Fortran Abbrev): Word syntax not relevant with new-style abbrev. - -2008-08-23 Johan Bockgård - - * basic.texi (Moving Point): Fix / confusion. - -2008-08-22 Chong Yidong - - * mini.texi (Minibuffer): Simplify introduction. - (Minibuffer File): Document tilde in minibuffer filenames. - (Minibuffer Edit): Mention that the prompt is read-only. Describe how - to enter tabs, spaces, and question marks. Describe behavior of C-a. - (Completion Example): Update example to current command list. - (Completion Options): Document `lazy' value of completion-auto-help. - Update contents of completion-ignored-extensions. - (Minibuffer History): Describe "future history" list. State default - value of history-delete-duplicates. - -2008-08-21 Glenn Morris - - * fortran-xtra.texi (Fortran Columns): Document `fortran-line-length'. - (Fortran Comments): Replace fortran-indent-comment with comment-dwim. - -2008-08-17 Chong Yidong - - * regs.texi (Registers): Clarify valid register names. - (RegPos): Note that buffer is saved and restored too. - (RegText): Note that mark is reactivated/deactivated. - (RegConfig): Xref to Windows node. - -2008-08-16 Chong Yidong - - * basic.texi (Inserting Text): Provide command name for C-q. - - * killing.texi (Killing): Copyedit. Define read-only text. - (Deletion): DEL and C-d were already explained in Erasing; xref there. - (Killing by Lines): Copyedit. - (Other Kill Commands): Move M-w description here. - (Yanking): Move M-w to Other Kill Commands. - (Kill Ring): Also mention saving text in registers. Link to Text - Properties in elisp manual. - (Accumulating Text): Copyedit. - (CUA Bindings): Shift selection is now the default. - -2008-08-12 Teodor Zlatanov - - * maintaining.texi (Change Log): Mention next-error is available. - -2008-08-10 Glenn Morris - - * cal-xtra.texi (Calendar Customizing): Mention whitespace variables - and intermonth text. - (Holiday Customizing): Add holiday-chinese. - -2008-08-08 Eli Zaretskii - - * files.texi (Log Buffer, Diff Mode): Fix last changes. Add indexing. - -2008-08-07 Dan Nicolaescu - - * files.texi (Log Buffer): Describe C-c C-d. - (Diff Mode): Describe C-x 4 A. - -2008-08-06 Eli Zaretskii - - * vc1-xtra.texi (VC Directory Mode): Fix last change. - -2008-08-06 Dan Nicolaescu - - * files.texi (Old Revisions): Update the keys used by vc-annotate and - describe the new bindings to show the changeset diff, toggle annotation - visibility, show revisions. - (VC Status): Describe key bindings for modifying the change comments, - displaying changeset diffs and annotations. - - * vc1-xtra.texi (VC Directory Mode): Talk about multiple VC systems. - -2008-08-05 Nick Roberts - - * vc1-xtra.texi (VC Directory Mode): Fix typo. - -2008-08-02 Eli Zaretskii - - * vc1-xtra.texi (VC Directory Mode, VC Directory Commands): Fix English - and wording. - -2008-08-02 Dan Nicolaescu - - * vc1-xtra.texi (VC Directory Mode): Fix and improve the info about - marking/unmarking. Add descriptions for the multiple file search - commands. Improve some old info. - -2008-07-31 Chong Yidong - - * display.texi (Visual Line Mode): New node. - - * basic.texi (Inserting Text): Move DEL to deletion node. - (Moving Point): Add additional alternative key bindings. - Describe line-move-visual. - (Erasing): Describe DEL. - (Basic Undo, Blank Lines, Arguments): Copyedit. - (Continuation Lines): Mention Visual Line mode. - (Position Info): Move extended discussion to mule.texi. - - * mule.texi (International Chars): Describe C-x =. - - * emacs.texi (Top): Add Visual Line Mode node. - -2008-07-31 Dan Nicolaescu - - * emacs.texi: Remove VMS support. - -2008-07-30 Dan Nicolaescu - - * vc1-xtra.texi (VC Directory Mode): Update the display format and fix - the vc-dir command name. - -2008-07-27 Dan Nicolaescu - - * xresources.texi: Remove mentions of Mac Carbon. - -2008-07-19 Andreas Schwab - - * ns-emacs.texi: Move to ../misc. - -2008-07-15 Chong Yidong - - * entering.texi (Exiting): Don't describe text-only terminals as the - default. Describe the new startup screen. - (Exiting): Describe how to kill Emacs first. Change description of - iconification to handle modern window systems. - -2008-07-15 Adrian Robert - - * ns-emacs.texi: New file, documents features of Emacs port under - NeXTstep windowing. - -2008-07-15 Chong Yidong - - * entering.texi (Entering Emacs): Update prev node. - - * glossary.texi (Glossary): Remove xref to Text Characters. - - * commands.texi (User Input): Rewrite. Describe Emacs' behavior - directly, rather than in the context of ASCII. Move description of - special properties of modifier key to new Modifier Keys node. - (Keys): Copyedit. - (Text Characters): Delete node. Multibyte is the default nowadays, and - the node contents are obsolete. - - * custom.texi (Modifier Keys): New node. - - * emacs.texi (Top): Update node list. - -2008-07-13 Chong Yidong - - * emacs.texi (Intro): Increase conciseness slightly. Remove paragraph - saying that Emacs provides menus and mouse support (which is par for - the course). - - * screen.texi (Screen): Copyedit. Define "buffer" and "current buffer" - early on. - (Point): Copyedit. Relegate historical trivia to a footnote. - (Mode Line): Explain mode-line format more consistently. - (Menu Bar): Copyedit. - -2008-06-27 Glenn Morris - - * cal-xtra.texi (Sexp Diary Entries): - * calendar.texi (Lunar Phases): Update for lunar.el name changes. - -2008-06-26 Chong Yidong - - * mark.texi (Shift selection): New node. - (Mark): Copyedits. - (Persistent Mark): Move to the end of the chapter. - -2008-06-20 Eli Zaretskii - - * makefile.w32-in (distclean): Remove makefile. - -2008-06-17 Nick Roberts - - * building.texi (Starting GUD): Add an entry for gud-gdb. - (GDB Graphical Interface): Explain that gud-gdb is now needed for text - command mode. - -2008-06-17 Glenn Morris - - * calendar.texi: Fix references to mouse-2 and mouse-3 in calendar. - -2008-06-17 Nick Roberts - - * building.texi (Starting GUD): Expand on remote debugging. - (Other GDB-UI Buffers): Mention new keyboard bindings. - -2008-06-15 Glenn Morris - - * gnu.texi: Use a verbatim license for this invariant section, - as per etc/GNU. - -2008-06-13 Daniel Engeler - - * emacs.texi, misc.texi: Add documentation about serial port access. - -2008-06-13 Glenn Morris - - * emacs-xtra.texi, emacs.texi: Update Back-Cover text per - maintain.info. - -2008-06-05 Miles Bader - - * display.texi (Temporary Face Changes): Update to reflect function - renamings in face-remap.el. - -2008-06-04 Miles Bader - - * display.texi (Temporary Face Changes): - Add `adjust-buffer-face-height'. Rewrite description of - `increase-buffer-face-height' and `decrease-default-face-height' now - that they aren't bound by default. - -2008-06-03 Miles Bader - - * display.texi (Temporary Face Changes): New node. - -2008-05-31 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Fix text added on 2008-05-29. - -2008-05-31 Glenn Morris - - * cal-xtra.texi (Fancy Diary Display): Simplify. - -2008-05-30 Glenn Morris - - * cal-xtra.texi (Fancy Diary Display): Update for - diary-display-function replacing diary-display-hook. - -2008-05-29 Drew Adams - - * msdog.texi (Windows Keyboard): Add descriptions of - w32-register-hot-key and w32-unregister-hot-key. - -2008-05-21 Tom Tromey - - * custom.texi (Directory Variables): Grammar fix. Link to Safe File - Variables node. - -2008-05-19 Tom Tromey - - * custom.texi (Variables): Add Directory Variables to menu. - (Directory Variables): New node. - -2008-05-16 Eric S. Raymond - - * vc2-xtra.texi: Modify an example so it reflects what vc.el now does. - -2008-05-15 Eric S. Raymond - - * vc2-xtra.texi, emacs.texi, files.texi: Snapshots node renamed to - Revision Tags and rewritten. Section now uses modern terminology, - (tags rather than snapshots) and describes post-SCCS systems more - accurately. - -2008-05-10 Eli Zaretskii - - * msdog.texi (Windows Files): Update documentation of - w32-get-true-file-attributes. - -2008-05-09 Eric S. Raymond - - * files.texi, vc-xtra.texi, vc1-xtra.texi: Document the new VC - directory mode. - -2008-05-08 Chong Yidong - - * killing.texi (Appending Kills): Remove a strangely off-topic index - entry "television". - -2008-05-07 Eric S. Raymond - - * ack.texi, files.texi, vc2-xtra.texi: Meta-CVS is no longer supported. - -2008-05-02 Eric S. Raymond - - * buffers.texi, files.texi (Version-control): - vc-toggle-read-only is no longer a good idea... - -2008-04-29 Glenn Morris - - * cal-xtra.texi (Sexp Diary Entries): Clarify diary-float. - -2008-04-22 Juri Linkov - - * dired.texi (Subdirectories in Dired): Describe using `^' - to return to the parent directory. - -2008-04-22 Nick Roberts - - * building.texi (GDB-UI Layout, Other GDB-UI Buffers): Update for - recent changes. - -2008-04-19 Nick Roberts - - * building.texi (GDB-UI Layout, Breakpoints Buffer) - (Other GDB-UI Buffers): Update for recent thread related changes. - -2008-04-11 Mirko Vukovic (tiny change) - - * maintaining.texi (Maintaining): - * emacs.texi (Top): Typo. - -2008-04-08 Stefan Monnier - - * display.texi (Font Lock): Prefer add-hook to using a non-nil `mode' - arg in `font-lock-add-keywords'. - -2008-04-08 Glenn Morris - - * cal-xtra.texi, calendar.texi: Update for calendar name changes. - Also add Baha'i calendar references where appropriate. - -2008-04-05 Glenn Morris - - * custom.texi (Init File): Byte-compiling .emacs is bad. - -2008-04-04 Stefan Monnier - - * mini.texi (Minibuffer Edit) : Adjust default. - -2008-03-29 Glenn Morris - - * calendar.texi: Update for `calendar-date-style' replacing - `european-calendar'. - -2008-03-28 Jason Rumney - - * display.texi (Display Custom): Mention overlay-margin in text. - -2008-03-12 Reiner Steib - - * custom.texi, dired.texi, mini.texi, mule.texi: Add `referenced in the - tutorial' comments. - -2008-03-28 Chong Yidong - - * mark.texi (Mark): Rearrange nodes. - (Persistent Mark): Rename from Transient Mark. - (Mark, Setting Mark, Marking Objects, Persistent Mark, Mark Ring): - Describe Transient Mark mode as the default. - - * basic.texi (Basic Undo): Don't mention setting the mark, which isn't - the default behavior with Transient Mark mode off. - (Position Info): Fix typo. - - * display.texi (Standard Faces): Reference the Mark node. - Remove discussion of the region face, which is discussed there. - - * emacs.texi (Top): Update node listings. - - * files.texi (Diff Mode, Misc File Ops): Describe Transient Mark mode - as the default. - - * fixit.texi (Undo): Standardize choice of undo key sequence. - (Undo, Spelling): Describe Transient Mark mode as the default. - - * frames.texi (Mouse Commands): Treat Transient Mark mode as the - default. - - * glossary.texi (Glossary): Treat Transient Mark mode as the default. - - * killing.texi (Kill Ring, Accumulating Text): Assume Transient Mark - mode is the default, and note that the mark is not activated when set. - - * programs.texi (Moving by Defuns, Expressions, Comment Commands): - Describe Transient Mark mode as the default. - - * search.texi (Basic Isearch): Reference the Mark Ring node. - (Replace, Unconditional Replace, Other Repeating Search): - Describe Transient Mark mode as the default. - - * text.texi (Words, Pages, Fill Commands, HTML Mode): - Describe Transient Mark mode as the default. - (Paragraphs): Describe how M-h behaves when region is active. - - * trouble.texi (Quitting): Clarify effects of C-g. - -2008-03-13 Glenn Morris - - * emacs.texi (EMACSVER): Set to 23.0.60. - -2008-03-05 Glenn Morris - - * dired.texi (Hiding Subdirectories): Fix previous change. - -2008-03-05 Drew Adams - - * dired.texi (Hiding Subdirectories): Document `dired-hide-subdir'. - -2008-02-28 Kim F. Storm - - * help.texi (Help Files): Move describe-gnu-project to C-h g. - Move describe-distribution to C-h C-o. - Move view-emacs-problems to C-h C-p. - Add view-emacs-debugging on C-h C-d. - Add view-external-packages on C-h C-e. - Add view-order-manuals on C-h C-m. - -2008-02-17 Ulrich Mueller - - * msdog-xtra.texi (MS-DOS): Docstring fix. - -2008-02-09 Eli Zaretskii - - * msdog.texi (Windows Fonts): Use a @table for describing font - properties. - -2008-02-07 Jason Rumney - - * msdog.texi (Windows Files): w32-get-true-file-attributes default - value has changed. - (Windows HOME): Clarify what is meant by "if that fails as well". - (Windows Fonts): New section. - -2008-02-07 D. E. Evans (tiny change) - - * basic.texi (Basic Undo): Remove duplicate "you can". - -2008-02-02 Eli Zaretskii - - * maintaining.texi (Tags): Fix last change. - -2008-01-31 Nick Roberts - - * trouble.texi (Checklist): Direct users to emacs-devel@gnu.org. - -2008-01-26 Richard Stallman - - * maintaining.texi (Tags): Delete redundant index entry. - -2008-01-26 Eli Zaretskii - - * programs.texi (Imenu): Move "@cindex tags" from here... - * maintaining.texi (Tags): ...to here. - -2008-01-23 Kevin Ryde - - * custom.texi (Mouse Buttons): Update elisp xref to "Click Events" on - click count. - -2008-01-21 Juanma Barranquero - - * entering.texi (Exiting): Fix typo. - Reported by D. E. Evans . - -2007-12-31 Martin Rudalics - - * glossary.texi (Glossary): Fix typo. - -2007-12-27 Richard Stallman - - * text.texi (Formatted Text): Improve menu tag. - (Editing Format Info): In Info, add duplicate menu of nodes - about the submenus. - (Format Faces): Say where Faces menu is found. Mention Other. - (Format Colors): Say where these submenus are found. - (Format Indentation, Format Justification): Likewise. - (Format Properties): Likewise. - -2007-12-22 Richard Stallman - - * search.texi (Query Replace): Make exp of query-replace more - self-contained, and clarify. - -2007-12-15 Richard Stallman - - * files.texi (Auto Save): Clarify definition of auto-saving. - -2007-11-26 Richard Stallman - - * help.texi (Help Echo): Cleanups. - -2007-11-23 Thien-Thi Nguyen - - * files.texi (Why Version Control?): Fix typo. - (VCS Concepts): Fix typos; small tense fix. - (Selecting a Fileset): Fix typos; small rewording. - (Log Buffer): Likewise. - (Old Revisions): Likewise. - -2007-11-17 Eli Zaretskii - - * mule.texi (Communication Coding): Fix wording of last change. - -2007-11-16 Werner Lemberg - - * custom.texi (Specifying File Variables): - * major.texi (Choosing Modes): Mention '\" in man pages. - -2007-11-16 Kenichi Handa - - * mule.texi (Communication Coding): Document x-select-request-type. - - * frames.texi (Cut/Paste Other App): Mention x-select-request-type. - -2007-11-15 Francesco Potortì - - * maintaining.texi (TEXTAGS): Note that you can use "-" for stdout with - --output=file. - -2007-11-13 Martin Rudalics - - * help.texi (Help Summary, Apropos, Misc Help): Fix typos. - (Help Echo): Avoid mentioning the term "region" here and - consistently use the term "active text". - -2007-11-11 Glenn Morris - - * calendar.texi (Special Diary Entries): Fix Thanksgiving example. - -2007-11-10 Paul Pogonyshev - - * search.texi (Query Replace): - Mention `query-replace-show-replacement'. - -2007-11-09 Nick Roberts - - * building.texi (Watch Expressions): Remove obscure sentence. - -2007-11-06 Kenichi Handa - - * mule.texi (Select Input Method): Describe how to activate an input - method in the text mode. - -2007-11-01 Dan Nicolaescu - - * cmdargs.texi (Misc Variables): Remove Sun windows info. - -2007-10-30 Nick Roberts - - * building.texi (Watch Expressions): Describe gdb-delete-out-of-scope. - -2007-10-30 Glenn Morris - - * misc.texi (Directory Tracking): Explain a bit more about - dirtrack-mode. - -2007-10-25 Glenn Morris - - * fortran-xtra.texi (Fortran): F90 mode handles F2003. - -2007-10-24 Richard Stallman - - * misc.texi (Interactive Shell): Cleanup last change. - -2007-10-22 Juri Linkov - - * mini.texi (Minibuffer History): Add text about a list of minibuffer - default values. - -2007-10-20 Eric S. Raymond - - * files.texi: Disambiguate two slightly different uses of the term - 'filesets'. - -2007-10-18 Martin Rudalics - - * trouble.texi (Quitting): Fix typo. - -2007-10-18 Glenn Morris - - * frames.texi (Mode Line Mouse): Mention minor mode names. - -2007-10-17 Juri Linkov - - * text.texi (Fill Commands): Undocument fill-paragraph-or-region. - fill-paragraph operates on the active region in Transient Mark mode. - (Fill Prefix, Format Indentation): Replace fill-paragraph-or-region - with fill-paragraph. - - * basic.texi (Arguments): Replace fill-paragraph-or-region with - fill-paragraph. - - * fixit.texi (Spelling): ispell-word operates on the active region - in Transient Mark mode. - -2007-10-17 Aaron S. Hawley - - * building.texi (Source Buffers): - * custom.texi (Init Non-ASCII): - * glossary.texi (Glossary): Use "key binding" consistently. - -2007-10-17 Juanma Barranquero - - * calendar.texi (Diary): Fix directive. - -2007-10-16 Richard Stallman - - * calendar.texi (Diary): Clarify text about diary file example. - -2007-10-13 Eric S. Raymond - - * files.texi: Capitalize node names according to convention. - -2007-10-13 Glenn Morris - - * misc.texi (Interactive Shell): Correct INSIDE_EMACS reference. - -2007-10-11 Eric S. Raymond - - * emacs.texi: - * files.texi (Version Systems): Minor fixes to version-control material - suggested by RMS and Robert J. Chassell. - -2007-10-10 Eric S. Raymond - - * files.texi (Version Systems): - * vc-xtra.texi: - * vc1-xtra.texi: - * vc2-xtra.texi: Merge in changes for new VC with fileset-oriented - operations. Change of terminology from `version' to `revision'. - Revise text for adequate description of VCSes with monotonic IDs. - * emacs.texi: Change of terminology from `version' to `revision'. - -2007-10-09 Eric S. Raymond - - * files.texi (Version Systems): Describe newer VCses. - Reorder the descriptions to be chronological. - -2007-10-09 Richard Stallman - - * display.texi (Cursor Display): Correct how cursor appears - in nonselected windows. - -2007-10-04 Nick Roberts - - * building.texi (GDB Graphical Interface): Remove references to gdba - and mention gud-gdb. - -2007-08-31 Eli Zaretskii - - * rmail.texi (Rmail Sorting): Improve indexing. - -2007-10-06 Juri Linkov - - * text.texi (Fill Commands): Document fill-paragraph-or-region. - (Fill Prefix, Format Indentation): Replace fill-paragraph with - fill-paragraph-or-region. - - * basic.texi (Arguments): Replace fill-paragraph with - fill-paragraph-or-region. - -2007-10-06 Eric S. Raymond - - * files.texi: Update the section on version control for 2007 - conditions. None of these changes are new-VC-specific; that - will come later. - -2007-09-15 Glenn Morris - - * calendar.texi (Holidays): Change all instances of `holiday-list' back - to `list-holidays'. - -2007-09-14 Glenn Morris - - * calendar.texi: Update all instances of mark-calendar-holidays, - list-calendar-holidays, list-holidays with the new names. - -2007-09-06 Glenn Morris - - Move manual sources from man/ to subdirectories of doc/. - Split into the Emacs manual in emacs/, and other manuals in misc/. - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs - manual. - (infodir): New variable. - (info): Use $infodir. - (emacsman): Delete target, not needed any more. - Move all targets that are not the Emacs manual to misc/Makefile.in. - (mostlyclean): Remove `gnustmp'. - * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs - manual. - (MULTI_INSTALL_INFO, ENVADD, infodir): Go up one more level. - (emacsman): Delete target, not needed any more. - (clean): Remove all info files but Emacs manual. - Move all targets that are not the Emacs manual to misc/Makefile.in. - * emacs-xtra.texi, emacs.texi (setfilename): Go up one more level. - - * Makefile.in (INFOSOURCES): Delete. - (.SUFFIXES): Use $(TEXI2DVI) rather than texi2dvi. - (mostlyclean): Add *.op, *.ops. Move *.aux *.cps *.fns *.kys *.pgs - *.vrs *.toc here... - (maintainer-clean): ...from here. - -2007-09-05 Glenn Morris - - * custom.texi (Safe File Variables): Clarify `!' and risky variables. - -2007-08-29 Glenn Morris - - * emacs.texi (EMACSVER): Increase to 23.0.50. - -2007-08-27 Richard Stallman - - * emacs.texi (Top): Clarify menu item for Glossary. - - * display.texi (Faces): Change secn title. - Clarify not all fonts come from Font Lock. - -2007-08-17 Eli Zaretskii - - * basic.texi (Position Info): Add index entry for face at point. - Mention that character faces are also displayed by "C-u C-x =". - -2007-08-08 Glenn Morris - - * glossary.texi (Glossary): Deprecate `iff'. - -2007-08-07 Chong Yidong - - * files.texi (File Conveniences): Document point motion keys in Image - mode. - -2007-07-27 Glenn Morris - - * emacs.texi (Copying): Include license text from gpl.texi, rather than - in-line. - - * gpl.texi: New file with text of GPL. - * Makefile.in (EMACSSOURCES): Add gpl.texi. - -2007-07-26 Dan Nicolaescu - - * vc2-xtra.texi (Customizing VC): Add GIT and HG. - - * dired.texi (Wdired): Mention C-x C-q key binding. - -2007-07-28 Nick Roberts - - * building.texi (GDB Graphical Interface): Qualify use of "M-x gdba". - -2007-07-25 Glenn Morris - - * emacs.texi (Copying): Replace license with GPLv3. - - * Relicense all FSF files to GPLv3 or later. - -2007-07-24 Glenn Morris - - * calendar.texi (Writing Calendar Files): cal-tex-diary etc only work - for some calendars. - -2007-07-23 Nick Roberts - - * screen.texi (Mode Line): Describe new mode-line flag that shows if - default-directory for the current buffer is on a remote machine. - -2007-07-21 Eli Zaretskii - - * vc2-xtra.texi (Customizing VC) : Update the - default value. - -2007-07-21 Richard Stallman - - * files.texi (Why Version Control?): Improve previous change. - -2007-07-18 Eric S. Raymond - - * files.texi (Why Version Control?): New node. - -2007-07-12 Nick Roberts - - * building.texi (Starting GUD): Add xref to this anchor. - -2007-06-24 Karl Berry - - * emacs.texi: New Back-Cover Text. - -2007-06-07 Alan Mackenzie - - * display.texi (Optional Mode Line): Document the new form of - line+column numbers, "(561,2)". - -2007-06-06 Juanma Barranquero - - * maintaining.texi (Create Tags Table): Fix typos. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-05-07 Karl Berry - - * emacs.texi (EMACSVER): Back to 22. - -2007-05-06 Richard Stallman - - * maintaining.texi (Create Tags Table): Clean up previous change. - -2007-05-05 Francesco Potortì - - * maintaining.texi (Create Tags Table): Add text about the dangers of - making symbolic links to tags files. - -2007-05-04 Karl Berry - - * emacs.texi (EMACSVER) [smallbook]: 22.1 for printed version, not 22. - -2007-05-03 Karl Berry - - * emacs.texi (EMACSVER) [smallbook]: 22 for printed version. - - * .cvsignore (*.pdf): New entry. - - * emacs.texi (\urlcolor, \linkcolor) [smallbook]: \let to \Black - for printing. - -2007-05-01 Richard Stallman - - * cmdargs.texi (Initial Options): Under --batch, mention --eval. - -2007-04-28 Glenn Morris - - * ack.texi (Acknowledgments): - * anti.texi (Antinews): - * programs.texi (Program Modes): Restore mention of python.el pending - consideration of legal status. - -2007-04-28 Richard Stallman - - * files.texi (File Names): Fixes to ~ description on MS systems. - -2007-04-26 Glenn Morris - - * emacs.texi (EMACSVER): Increase to 22.1.50. - -2007-04-25 Karl Berry - - * emacs.texi: Improve line breaks on copyright page, - similar layout to lispref, 8.5x11 by default. - - * dired.texi (Image-Dired): Improve line break, fix typo. - -2007-04-24 Chong Yidong - - * programs.texi (Program Modes): - * anti.texi (Antinews): - * ack.texi (Acknowledgments): python.el removed. - -2007-04-23 Chong Yidong - - * display.texi (Highlight Interactively): Correct description of - hi-lock-file-patterns-policy. - - * files.texi (File Archives): Mention self-extracting executables. - -2007-04-23 Eli Zaretskii - - * search.texi (Unconditional Replace, Query Replace): Add xref to - "Replacement and Case". - -2007-04-22 Chong Yidong - - * dired.texi (Image-Dired): Move from Thumbnails node. - * misc.texi (Thumbnails): Node deleted. - * emacs.texi (Top): Update node listing. - - * files.texi (File Conveniences): - * ack.texi (Acknowledgments): Rename "tumme" to "image-dired". - -2007-04-21 Richard Stallman - - * display.texi (Highlight Interactively): Correct previous change. - Clarify doc of hi-lock-find-patterns, and move new features into it. - -2007-04-20 David Koppelman - - * display.texi (Highlight Interactively): - Document hi-lock-file-patterns-policy. - -2007-04-20 Martin Rudalics - - * display.texi (Scrolling): Fix typo. - -2007-04-15 Chong Yidong - - * doclicense.texi: Remove node heading, so that it can be included by - other files. - - * emacs.texi: Insert node heading for GFDL. - -2007-04-14 Eli Zaretskii - - * cmdargs.texi (Colors): Qualify "color of window" index entry by - "command line". - - * display.texi (Faces): Refer to "Creating Frames" for face - and other frame customizations in .emacs. - - * frames.texi (Creating Frames): Mention that face customizations can - be put in .emacs. Add index entries. - -2007-04-12 Richard Stallman - - * glossary.texi (Glossary): Explain `iff'. - -2007-04-11 Karl Berry - - * gnu.texi (Top), - * macos.texi (Mac Font Specs), - * anti.texi (Antinews), - * xresources.texi (Resources), - * misc.texi (Emulation), - * calendar.texi (Daylight Saving), - * dired.texi (Dired and Find), - * rmail.texi (Remote Mailboxes), - * sending.texi (Mail Headers), - * programs.texi (Which Function), - * files.texi (Recover), - * buffers.texi (Uniquify), - * frames.texi (Wheeled Mice), - * killing.texi (Rectangles): Wording to improve breaks in - 8.5x11 format. - * mule.texi (Language Environments): \hbadness=10000 since there's - no way to reword. - * emacs.texi (smallbook): New @set to more easily switch between - smallbook and 8.5x11. - -2007-04-11 Richard Stallman - - * files.texi (File Conveniences): Add xref to Tumme. - Delete text about Thumbnail mode. - -2007-04-09 Alan Mackenzie - - * cmdargs.texi (Initial Options): Call "inhibit-splash-screen" by its - new name. Insert concept index entries. - -2007-04-08 Chong Yidong - - * display.texi (Standard Faces): Document prefix arg for - list-faces-display. - - * rmail.texi (Rmail Scrolling): Document rmail-end-of-message. - -2007-04-07 Chong Yidong - - * killing.texi (Deletion): Rewrite description of M-\ prefix argument. - - * files.texi (Misc File Ops): Rewrite description of - insert-file-literally. - -2007-03-31 Eli Zaretskii - - * misc.texi (Printing): Postscript -> PostScript. - - * ack.texi (Acknowledgments): Postscript -> PostScript. - - * custom.texi (Init File, Init Non-ASCII): Fix last change. - - * emacs.texi (Top): Fix the menu due to the change in custom.texi - below. - -2007-03-30 Chong Yidong - - * custom.texi (Non-ASCII Rebinding): Node deleted. Material moved to - Init Non-ASCII. - (Init Rebinding, Init Syntax): Link to Init Non-ASCII instead. - (Init Non-ASCII): New node. - -2007-03-28 YAMAMOTO Mitsuharu - - * macos.texi (Mac Font Specs): Mention AppleAntiAliasingThreshold. - -2007-03-12 Glenn Morris - - * calendar.texi, emacs.texi (Daylight Saving): Rename node from - "Daylight Savings". - - * calendar.texi: Replace "daylight savings" with "daylight - saving" in text throughout. - -2007-03-04 Richard Stallman - - * custom.texi (Safe File Variables): Minor correction. - -2007-02-28 Thien-Thi Nguyen - - * rmail.texi (Movemail): Add internal ref. - Don't indent the intro for the PROTO table. - Format PROTO table items with @code. - -2007-02-26 Nick Roberts - - * building.texi: Remove references to bashdb. - -2007-02-19 Juanma Barranquero - - * mule.texi (Language Environments): Update list of supported language - environments. - -2007-02-14 Kim F. Storm - - * building.texi (Grep Searching): Fix lgrep doc. - -2007-02-12 Chong Yidong - - * back.texi: Remove unused file. - -2007-02-05 Francesco Potortì - - * maintaining.texi (Tag Syntax): Now --members is the default for - etags, not for ctags yet. - -2007-02-03 Eli Zaretskii - - * emacs.texi (Top): Update the top-level menus. Make the detailed menu - headers compliant with Texinfo guidelines and with what texnfo-upd.el - expects. Add comments to prevent people from inadvertently modifying - the key parts needed by `texinfo-multiple-files-update'. - -2007-01-29 Chong Yidong - - * frames.texi (Secondary Selection): Window clicked does not matter - when mouse-yank-at-point is non-nil. - -2007-01-27 Eli Zaretskii - - * msdog.texi (ls in Lisp): Document ls-lisp-format-time-list and - ls-lisp-use-localized-time-format. - -2007-01-16 Glenn Morris - - * abbrevs.texi (Editing Abbrevs): Describe how to disable a - system abbrev. - -2007-01-11 Richard Stallman - - * msdog.texi (Windows Keyboard): Another small cleanup. - -2007-01-10 Richard Stallman - - * msdog.texi (Windows Keyboard): Yet another try to make - everyone happy with that passage. - -2007-01-05 Richard Stallman - - * anti.texi (Antinews): Mention M-x shell scrolling. - -2007-01-05 Nick Roberts - - * building.texi (Watch Expressions): Describe gdb-max-children. - -2007-01-04 Richard Stallman - - * msdog.texi (Windows Keyboard): Clarify previous change. - -2007-01-02 Richard Stallman - - * custom.texi (Changing a Variable): Minor clarification. - (Specific Customization): customize-customized => customize-unsaved. - - * entering.texi (Entering Emacs): Clean up text about restarting - Emacs for each file. - - * misc.texi (Shell Options): Minor cleanup. - - * msdog.texi (Windows Keyboard): Explain that Windows was incompatible - with Emacs, not vice versa. - - * programs.texi (Symbol Completion): Recommend customizing - window manager. - - * xresources.texi (Resources): Minor fix. - -2007-01-01 Jan Djärv - - * xresources.texi (Table of Resources): Add scrollBarWidth resource. - -2007-01-01 Richard Stallman - - * commands.texi (User Input): Document keys stolen by window mangers. - -2006-12-31 Richard Stallman - - * custom.texi (Specific Customization): Document customize-option - instead of customize-variable. - -2006-12-31 Kim F. Storm - - * major.texi (Choosing Modes): Document auto-mode-case-fold. - -2006-12-30 Kim F. Storm - - * killing.texi (CUA Bindings): Fix typo. - - * xresources.texi (Table of Resources): Mention grow-only value for - auto-resize-tool-bars. - -2006-12-27 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Mention widespread Windows bindings, - and how to get them back. - -2006-12-26 Richard Stallman - - * calendar.texi (Holidays): Holiday listing is based on current - practice, but DST is not. - -2006-12-25 Richard Stallman - - * emacs.texi (Top): Update subnode menus. - - * mark.texi (Transient Mark): Fix xref. - - * killing.texi (Graphical Kill): Node deleted. - (Killing): Add xref to Cut and Paste. - (CUA Bindings): Update xref. - - * frames.texi (Cut and Paste): New section to hold other nodes. - (Mouse Commands): Node demoted. - (Cut/Paste Other App): Split out from Mouse Commands. - (Word and Line Mouse): Likewise. - (Secondary Selection, Clipboard): Nodes demoted. - -2006-12-24 Kevin Ryde - - * calendar.texi (Holidays): US daylight saving begins second Sunday - in March for 2007 onwards. - (Daylight Savings): Show new US default daylight saving rules, 2nd - Sun in Mar to 1st Sun in Nov, now in cal-dst.el. - -2006-12-23 Chong Yidong - - * calendar.texi (Scroll Calendar): < and > are switched. - -2006-12-23 Kevin Rodgers - - * killing.texi (Deletion): Describe M-\ prefix argument. - -2006-12-23 Richard Stallman - - * search.texi (Regexp Search): Explain why forward and reverse regexp - search are not mirror images. - -2006-12-19 Kim F. Storm - - * major.texi (Choosing Modes): Describe match-function elements for - magic-mode-alist. - -2006-12-18 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Add a footnote about "Windows" keys - peculiarities. - -2006-12-18 Richard Stallman - - * abbrevs.texi (Editing Abbrevs): Fix previous change. - -2006-12-17 Alan Mackenzie - - * programs.texi (Left Margin Paren): Remove the bit which says - that CC Mode sets open-paren-in-column-0-is-defun-start to nil. - Discuss some of the issues of setting this option to nil. - -2006-12-17 Glenn Morris - - * abbrevs.texi (Editing Abbrevs): Mention system abbrevs. - -2006-12-16 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Clarify `w32-recognize-altgr' effect. - (Windows Files): `w32-get-true-file-attributes' is only relevant for - NTFS volumes. - (ls in Lisp): `links' in `ls-lisp-verbosity' is only relevant to NTFS - volumes. - -2006-12-15 Eli Zaretskii - - * text.texi (HTML Mode): Fix "C-c TAB". - -2006-12-09 Richard Stallman - - * misc.texi (Invoking emacsclient): Simplify TCP file text. - -2006-12-08 Kevin Rodgers - - * files.texi (Misc File Ops): Document insert-file-literally. - -2006-12-08 Eli Zaretskii - - * cmdargs.texi (Colors): Note that --color is intended for overriding - the terminal defaults, not for normal invocation. - - * misc.texi (Emacs Server): Improve wording. Don't mention the - ``server program''. Add a cross-reference to "Init File" node. - (Invoking emacsclient): Add index entries. Document both short and - long versions of command-line options. Document the -f option. - -2006-12-06 Richard Stallman - - * text.texi (Outline Format): Say to set outline-regexp - and outline-level with major modes and file local variables. - -2006-12-05 Michaël Cadilhac - - * anti.texi (Antinews): Mention the alternative to - `~/.emacs_SHELLNAME', which is `~/.emacs.d/init_SHELLNAME.sh'. - - * misc.texi (Interactive Shell): Ditto. - -2006-12-04 Eli Zaretskii - - * emacs.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. - - * ack.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. - -2006-12-01 Eli Zaretskii - - * mule.texi (Enabling Multibyte): Rephrase the confusing reference to a - colon in the mode line. - - * msdog.texi (Windows Processes) [@ifnottex]: Mention w32-shell-execute. - -2006-11-26 Nick Roberts - - * building.texi (Watch Expressions): Mention SPC for expanding/ - contracting watch expressions. - -2006-11-26 Kim F. Storm - - * kmacro.texi (Basic Keyboard Macro): Mention F3/F4 more. - -2006-11-26 Nick Roberts - - * building.texi (Debugger Operation): Define text command mode. - Clarify how tooltips work. - (GDB Graphical Interface): Explain how to run in text command mode - more clearly. - -2006-11-25 Juanma Barranquero - - * mule.texi (Defining Fontsets): Fix use of `charset' and `font'. - -2006-11-22 Juanma Barranquero - - * anti.texi (Antinews): Mention --server-file and TCP sockets. - -2006-11-18 Chong Yidong - - * misc.texi (Interactive Shell): INSIDE_EMACS is set to t, - and EMACS is deprecated. - -2006-11-18 Juanma Barranquero - - * makefile.w32-in (emacs.dvi): Remove xresmini.texi. - -2006-11-18 Jan Djärv - - * Makefile.in (emacs.dvi): Remove xresmini.texi. - - * emacs.texi: Include xresources.texi both for info and dvi. - - * xresources.texi: Merge text from xresmini.texi. - -2006-11-12 Roberto Rodríguez (tiny change) - - * glossary.texi: Fix typos. - -2006-11-06 Richard Stallman - - * emacs.texi (Acknowledgments): Fix name spelling, add Anna Bigatti. - - * ack.texi (Acknowledgments): Fix name spelling. - -2006-11-01 Juri Linkov - - * search.texi (Word Search): Document incremental word search. - -2006-10-28 Glenn Morris - - * ack.texi (Acknowledgments): Add cal-html author. - - * calendar.texi (Writing Calendar Files): Rename section (was "LaTeX - Calendar"). Describe new package cal-html. - * emacs.texi (Top): Rename old node "LaTeX Calendar" to "Writing - Calendar Files." - -2006-10-23 Richard Stallman - - * abbrevs.texi (Expanding Abbrevs): Expansion happens only when - Abbrev mode is enabled. - -2006-10-16 Richard Stallman - - * emacs.texi: Update ISBN. - -2006-10-11 Kim F. Storm - - * emacs.texi (Acknowledgments): Use @dotless{i}. - -2006-10-08 Nick Roberts - - * building.texi (Breakpoints Buffer): Mention catchpoints. - -2006-10-08 Kim F. Storm - - * ack.texi (Acknowledgments): Update. - - * emacs.texi (Acknowledgments): Fix bad @/ form. - -2006-10-05 Kim F. Storm - - * emacs.texi (Acknowledgments): Add more contributors. - -2006-10-03 Richard Stallman - - * emacs.texi (Acknowledgments): Update version and edition. - -2006-10-01 Karl Berry - - * custom.texi (Customization Groups): Page break to keep example buffer - on one page. - -2006-09-30 Karl Berry - - * programs.texi (Basic Indent): @need to improve page break. - * text.texi: Rewording to improve page breaks, and use @LaTeX{}. - -2006-09-29 Glenn Morris - - * calendar.texi (Date Formats): Doc fix for european-calendar-style. - -2006-09-29 Karl Berry - - * windows.texi (Basic Window): Remove forced @break, no longer - desirable. - * frames.texi (Frame Commands), - * mark.texi (Marking Objects): Reword to avoid bad page break. - * display.texi (Auto Scrolling): Use @tie{} to avoid bad line break. - -2006-09-19 Richard Stallman - - * frames.texi (Dialog Boxes): Clean up wording: avoid passive, - stick to present tense. - -2006-09-18 Jan Djärv - - * frames.texi (Dialog Boxes): Rename x-use-old-gtk-file-dialog - to x-gtk-use-old-file-dialog. - (Dialog Boxes): Document x-gtk-file-dialog-help-text. - -2006-09-15 Jay Belanger - - * emacs.texi (GNU GENERAL PUBLIC LICENSE): - Change "Library Public License" to "Lesser Public License" - throughout. Use "yyyy" to represent year. - -2006-09-12 Paul Eggert - - * misc.texi (Interactive Shell): EMACS is now set - to Emacs's absolute file name, not to "t". - -2006-09-12 Reiner Steib - - * files.texi (Visiting): Add index entry "open file". - -2006-09-11 Richard Stallman - - * building.texi (Compilation Mode): Clarification. - (Grep Searching): Add xref to Compilation Mode. - -2006-09-08 Richard Stallman - - * search.texi (Search): Ref multi-file search commands here. - (Other Repeating Search): Not here. - -2006-08-28 Richard Stallman - - * windows.texi (Split Window): Update xref. - - * basic.texi (Continuation Lines): Update xref. - - * indent.texi (Tab Stops): Update xref. - - * emacs.texi (Top): Update subnode menu. - - * display.texi (Line Truncation, Displaying Boundaries): New nodes, - split out of Display Custom. - -2006-08-25 Kim F. Storm - - * display.texi (Display Custom): Add variables overline-margin - and x-underline-at-descent-line. - -2006-08-25 Richard Stallman - - * entering.texi (Exiting): Rewrite to give graphical displays - priority over text terminals. - - * search.texi (Incremental Search): Move index entries. - -2006-08-23 Chong Yidong - - * custom.texi (Init File): Reference Find Init to avoid "home - directory" confusion. - -2006-08-22 Nick Roberts - - * building.texi (Other GDB-UI Buffers): Describe how to edit - a value in the locals buffer. - -2006-08-21 Richard Stallman - - * search.texi (Basic Isearch): Add `isearch' index entry. - -2006-08-16 Richard Stallman - - * misc.texi (Saving Emacs Sessions): Clean up wording. - - * mark.texi (Marking Objects): Mention term "select all". - - * emacs.texi (Top): Update subnode menu. - - * help.texi (Help Mode): Move node up in file. - -2006-08-15 Nick Roberts - - * building.texi (Stack Buffer): Explain fringe arrow. - -2006-08-12 Eli Zaretskii - - * misc.texi (Saving Emacs Sessions): Clarify when desktop is restored - on startup. - -2006-08-11 Romain Francoise - - * ack.texi (Acknowledgments): Delete mention to zone-mode.el. - -2006-08-10 Sven Joachim (tiny change) - - * mule.texi (Recognize Coding, Text Coding): Fix typos. - -2006-08-10 Richard Stallman - - * text.texi (Format Faces): Substantial rewrites to deal - with face merging. Empty regions don't count. - Clarify face property inheritance. - -2006-08-08 Romain Francoise - - * dired.texi (Marks vs Flags): Fix typo reported by Ari Roponen - . - -2006-08-04 Eli Zaretskii - - * cmdargs.texi (Window Size X) <--geometry>: Only width and height - apply to all frames. - -2006-08-01 Richard Stallman - - * help.texi (Name Help): Add index entries for describe-variable. - -2006-08-01 Nick Roberts - - * building.texi (GDB Graphical Interface): Shorten node names. - (GDB-UI Layout): Use GDB-related. - (Other GDB-UI Buffers): Simplify English. - -2006-07-31 Richard Stallman - - * search.texi (Query Replace): Add xref for Dired's Q command. - -2006-07-31 Nick Roberts - - * building.texi (GDB commands in Fringe): Rename to... - (Source Buffers): ..this and move forward. Describe hollow arrow and - new option gdb-find-source-frame. - -2006-07-29 Richard Stallman - - * dired.texi (Operating on Files): Simplify previous change - and fix Texinfo usage. - -2006-07-29 Eli Zaretskii - - * dired.texi (Operating on Files): Add cross-references. State the - Unix commands that do similar things. - -2006-07-28 Richard Stallman - - * mark.texi (Transient Mark): Clarify that region never disappears - when Transient Mark mode is off, and not when it is on. - -2006-07-27 Richard Stallman - - * search.texi (Non-ASCII Isearch): Clarify. Mention C-q. - -2006-07-24 Richard Stallman - - * xresources.texi (GTK styles): Fix texinfo usage. - - * commands.texi (User Input): Explain why we teach keyboard cmds. - - * xresources.texi, xresmini.texi, search.texi, programs.texi: - * misc.texi, kmacro.texi, killing.texi, glossary.texi: - * fortran-xtra.texi, files.texi, emacs.texi, emacs-xtra.texi: - * doclicense.texi, display.texi, dired.texi, basic.texi: - * anti.texi, ack.texi: Move periods and commas inside quotes. - -2006-07-22 Eli Zaretskii - - * cmdargs.texi (General Variables): Document EMAIL. - -2006-07-21 Eli Zaretskii - - * frames.texi (Frame Commands): Mention that focus-follows-mouse - doesn't have effect on MS-Windows. - -2006-07-17 Richard Stallman - - * building.texi (Grep Searching): Explain about chaining grep commands. - -2006-07-10 Nick Roberts - - * killing.texi, mini.texi: Fix typos. - -2006-07-09 Chong Yidong - - * misc.texi (Invoking emacsclient): Document behavior when emacsclient - is invoked for multiple files. - -2006-07-08 Eli Zaretskii - - * msdog.texi (Windows Keyboard) [@iftex]: Add an @inforef to the - on-line manual for the rest of this node. - (Windows Mouse) : Include - unconditionally. - (Windows Processes) : Include unconditionally. - Improve wording. - (Windows Printing): Improve wording. - (Windows Misc) [@iftex]: Add an @inforef to the on-line manual for the - rest of this node. - -2006-07-05 Thien-Thi Nguyen - - * building.texi (Lisp Eval): Throughout, replace eval-current-buffer - with eval-buffer. - -2006-07-05 Nick Roberts - - * mule.texi (Coding Systems, Specify Coding): Link descriptions - of character translation. - -2006-07-04 Nick Roberts - - * rmail.texi (Remote Mailboxes): Add missing @code keyword. - -2006-07-03 Karl Berry - - * emacs.texi (\hbadness): Set to 6000 so we aren't bothered by - not-too-underfull hboxes in the TeX output. - * abbrevs.texi, buffers.texi, building.texi, calendar.texi, - * cmdargs.texi, custom.texi, dired.texi, macos.texi, - * maintaining.texi, misc.texi, mule.texi, programs.texi, rmail.texi, - * sending.texi, text.texi: Fix overfull/underfull boxes. - -2006-07-03 Romain Francoise - - * m-x.texi (M-x): Fix. - -2006-07-03 Richard Stallman - - * search.texi (Other Repeating Search): filename -> file name. - - * misc.texi (Narrowing): Minor cleanups. - - * files.texi (Visiting): filename -> file name. - - * emacs.texi (Top): Update subnode menus. - - * mule.texi (Coding Systems): Move char translation stuff here. - (Specify Coding, Output Coding): New nodes, out of Recognize Coding. - (Recognize Coding): Substantial local rewrites. - (International): Update menu. - - * display.texi (Auto Scrolling): New node, broken out of Scrolling. - (Scrolling): Substantial local rewrites. - (Display): Update menu and intro. - - * dired.texi: filename -> file name. - - * custom.texi (Safe File Variables): Texinfo usage fix. - -2006-07-03 Teodor Zlatanov - - * help.texi, m-x.texi: Lots of cleanups. - -2006-06-30 Eli Zaretskii - - * msdog.texi (ls in Lisp, Windows Keyboard, Windows Mouse) - (Windows Processes, Windows Misc): Shorten the printed version by - selectively conditioning less important portions by @ifnottex. - -2006-06-27 Richard Stallman - - * mini.texi (Minibuffer File): Minor cleanup. - -2006-06-25 Nick Roberts - - * frames.texi (XTerm Mouse): Rename to... - (Text-Only Mouse): ...this. Mention t-mouse-mode. - - * emacs.texi (Top): Use new node name. - -2006-06-24 Eli Zaretskii - - * emacs.texi (Top): Update the detailed menu according to changes in - msdog.texi. - - * msdog.texi (Windows Keyboard): New section. - (Windows Mouse): New section. - (Windows System Menu): Remove section (text merged with "Windows - Keyboard"). - (Windows Misc): New section. - - * dired.texi (Dired Enter): Refer to msdog.texi for ls-lisp emulation. - - * msdog.texi (ls in Lisp): New section. - - * files.texi (Visiting): Document case-insensitive wildcard matching - under find-file-wildcards. - -2006-06-16 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Add description of mac-function-modifier. - Now Unicode keyboard layouts work. - -2006-06-10 Richard Stallman - - * mule.texi (Recognize Coding): Clarify previous change. - -2006-06-09 Kenichi Handa - - * mule.texi (Recognize Coding): Describe the convention of "CODING!" - notation. - -2006-06-07 Kevin Ryde - - * mule.texi (Coding Systems): Footnote xref "MS-DOS and MULE" in main - manual for @ifnottex, but in emacs-extra for @iftex. - - * cmdargs.texi (General Variables): Fix smtpmail xref. - -2006-05-29 Stefan Monnier - - * programs.texi (Comment Commands): - * custom.texi (Specifying File Variables): - Use ;; instead of ;;; to better follow coding conventions. - -2006-06-07 Nick Roberts - - * building.texi (Watch Expressions): Move node to end. - (GDB Graphical Interface): Move description of clicks in fringe... - (GDB commands in the Fringe): ...to here. New node. - -2006-06-05 Romain Francoise - - * xresmini.texi (GTK resources): Fix various typos. - -2006-06-05 Nick Roberts - - * building.texi (GDB Graphical Interface): Update bindings. - (Commands of GUD): Add gud-print. Remove gud-run. - Restate availability more generally. - -2006-06-03 Teodor Zlatanov - - * mini.texi: Lots of cleanups. - -2006-06-01 Luc Teirlinck - - * misc.texi (Shell History Copying): Update descriptions of `C-c RET' - and Mouse-2. - -2006-06-01 Jan Djärv - - * screen.texi (Menu Bar): Change menu-bar-start to menu-bar-open. - -2006-05-31 Richard Stallman - - * basic.texi (Moving Point): Fix previous change. - -2006-05-29 Jan Djärv - - * screen.texi (Menu Bar): F10 for Gtk+/Lesstif/Lucid menus. - -2006-05-28 Teodor Zlatanov - - * basic.texi: Many simplifications and improvements in wording. - -2006-05-26 Nick Roberts - - * anti.texi (Antinews): Create a node for gdb-ui. - -2006-05-22 Reiner Steib - - * frames.texi (Menu Bars, Tool Bars): Add index entries. - -2006-05-20 Richard Stallman - - * dired.texi (Dired Navigation): dired-goto-file is now j. - -2006-05-20 Eli Zaretskii - - * mule.texi (Coding Systems): Mention the undecided-* coding systems - and their aliases. - - * msdog.texi (Windows Printing): Mention non-support of plain text - printing with some el-cheapo printers, and suggest a workaround. - -2006-05-20 Kevin Ryde - - * text.texi (TeX Print): tex-dvi-view-command has a default value, - remove the bit saying you must set it. - -2006-05-19 Luc Teirlinck - - * trouble.texi (Checklist): - * text.texi (Text, Auto Fill, Text Mode): - * search.texi (Nonincremental Search): - * rmail.texi (Rmail Labels): - * mule.texi (Input Methods, Multibyte Conversion): - * misc.texi (Gnus, Where to Look, PostScript): - * maintaining.texi (Create Tags Table): - * indent.texi (Indentation Commands): - * fixit.texi (Spelling): - * emacs.texi (Copying): - * custom.texi (Init File): ifinfo -> ifnottex. - -2006-05-17 Richard Stallman - - * files.texi (Diff Mode): Mention C-x `. - -2006-05-08 Richard Stallman - - * custom.texi (Disabling): Textual cleanups. - -2006-05-12 Glenn Morris - - * calendar.texi (Displaying the Diary, Format of Diary File): - Refer to diary-view-entries, diary-list-entries, - diary-show-all-entries rather than obsolete aliases. - -2006-05-12 Eli Zaretskii - - * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) - (Displaying the Diary, Special Diary Entries, Importing Diary): - * building.texi (Compilation Shell): - * buffers.texi (Several Buffers) [iftex]: Replace @xref's to - emacs-xtra with @inforef's. - - * files.texi (Visiting): Fix wording. - - * mule.texi (Coding Systems, Text Coding): More indexing. - Mention that C-x RET f can set eol conversion. - -2006-05-07 Jan Djärv - - * xresmini.texi (GTK resources): Insert GTK description. - - * xresources.texi (GTK resources): metafont should be menufont. - -2006-05-06 Michael Albinus - - * mini.texi (Completion Options): Completion of remote files' - method, user name and host name is active only in partial - completion mode. - -2006-05-06 Eli Zaretskii - - * makefile.w32-in (emacs.dvi): - * Makefile.in (emacs.dvi): Add xresmini.texi. - - * xresmini.texi (Table of Resources): Remove xref to non-existent - node "LessTif Resources". - - * msdog.texi (Microsoft Windows): - * calendar.texi (Calendar/Diary, Displaying the Diary) - (Special Diary Entries, Importing Diary, Holidays): - * programs.texi (Program Modes): - * text.texi (Text): - * buffers.texi (Several Buffers): - * files.texi (Comparing Files): Fix cross-references to emacs-xtra. - -2006-05-06 Eli Zaretskii - - The following changes merge the emacs-xtra manual into the main - manual, but only for on-line version of the manual. - - * vc2-xtra.texi (Version Backups, Local Version Control) - (Making Snapshots, Change Logs and VC, Version Headers) - (Customizing VC, CVS Options) [ifnottex]: Conditional xref's for - on-line manual. - - * vc1-xtra.texi (VC Dired Mode) [ifnottex]: Conditional xref's - for on-line manual. - - * msdog-xtra.texi (MS-DOS, MS-DOS Keyboard, MS-DOS Mouse) - (MS-DOS Display, MS-DOS File Names, MS-DOS Printing) - (MS-DOS and MULE, MS-DOS Processes) [ifnottex]: Conditional xref's - for on-line manual. - - * fortran-xtra.texi (Fortran, Fortran Autofill) - (Fortran Autofill, Fortran Abbrev) [ifnottex]: Conditional xref's - for on-line manual. - - * picture-xtra.texi (Basic Picture, Rectangles in Picture) [ifnottex]: - Conditional xref's for on-line manual. - - * emerge-xtra.texi (Emerge, Overview of Emerge) - (Fine Points of Emerge) [ifnottex]: Conditional xref's for on-line - manual. - - * Makefile.in (INFO_TARGETS): Remove ../info/emacs-xtra. - (EMACS_XTRA): New variable, lists the new *-xtra.texi files. - (EMACSSOURCES): Use EMACS_XTRA. - (../info/emacs-xtra): Remove. - (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. - - * makefile.w32-in (INFO_TARGETS): Remove $(infodir)/emacs-xtra. - (EMACS_XTRA): New variable, lists the new *-xtra.texi files. - (EMACSSOURCES): Use EMACS_XTRA. - ($(infodir)/emacs-xtra): Remove. - (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. - - * trouble.texi (Quitting): - * text.texi (Text): - * programs.texi (Program Modes): - * msdog.texi (Microsoft Windows): - * frames.texi (Frames): - * files.texi (Backup, Version Control, VC Concepts) - (Types of Log File, Advanced C-x v v, Log Buffer, Old Versions) - (Registering, VC Status, VC Undo, Multi-User Branching) - (Comparing Files): - * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) - (Displaying the Diary, Special Diary Entries, Importing Diary): - * buffers.texi (Several Buffers): Replace inforef to emacs-xtra by - conditional xref's, depending on @iftex/@ifnottex. - - * msdog.texi (Microsoft Windows) [ifnottex]: Add menu entry for - "MS-DOS". @include msdog-xtra.texi. - - * programs.texi (Programs) [ifnottex]: Add menu entry for "Fortran". - [ifnottex]: @include fortran-xtra.texi. - - * files.texi (Secondary VC Commands) [ifnottex]: Add menu entries - for vc-xtra.texi subsections. - (VC Undo) [ifnottex]: @include vc1-xtra.texi and @lowersections it. - (Multi-User Branching) [ifnottex]: @include vc2-xtra.texi. - - * sending.texi (Sending Mail): A @node line without explicit Prev, - Next, and Up links. - - * abbrevs.texi (Abbrevs): A @node line without explicit Prev, - Next, and Up links. - - * emacs.texi (Top) [ifnottex]: Add menu entries for "Picture Mode" - and its sections. @include picture-xtra.texi. - - * maintaining.texi (Maintaining) [ifnottex]: Add menu entry for - "Emerge". - (List Tags) [ifnottex]: @include emerge-xtra.texi. - - * cal-xtra.texi (Daylight Savings): Remove this node: it is an - exact duplicate of its name-sake in calendar.texi. - - * calendar.texi (Calendar/Diary) [ifnottex]: Add menu item for - "Advanced Calendar/Diary Usage". - (Time Intervals) [ifnottex]: @include cal-xtra.texi. - - * dired.texi (Subdirectories in Dired) [ifnottex]: @include - dired-xtra.texi. - (Dired) [ifnottex]: Add menu entry for "Subdir Switches". - - * files.texi (Reverting) [ifnottex]: @include arevert-xtra.texi. - (Files) [ifnottex]: Add menu entry for Autorevert. - - * emacs-xtra.texi (Introduction): Reword to make consistent with - printed version only. - : Remove the body of all chapters and move them to the - new *-xtra.texi files. Use @raisesections and @lowersections to - convert sections to chapters etc. - - * msdog-xtra.texi: - * fortran-xtra.texi: - * vc-xtra.texi: - * vc1-xtra.texi: - * vc2-xtra.texi: - * emerge-xtra.texi: - * cal-xtra.texi: - * dired-xtra.texi: - * arevert-xtra.texi: New files, with text from respective chapters - of emacs-xtra.texi. Convert each @chapter into @section, @section - into @subsection, etc. - - * emacs-xtra.texi (MS-DOS): Rename from "MS-DOG". All references - updated. - - * msdog.texi (Microsoft Windows): Rename from "Emacs and Microsoft - Windows". All references updated. - -2006-05-06 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Mention input from Character Palette. - (Mac Font Specs): Fix typo. - -2006-05-05 Richard Stallman - - * files.texi (Diff Mode): Minor cleanup. - -2006-05-05 Karl Berry - - * emacs.texi: Call @fonttextsize 10, inside @tex to avoid - errors from the current release of makeinfo (4.8). - * help.texi (Library Keywords): Change widest word in multitable - template from `emulations' to `convenience'. (Not sure if this is - related to the font change.) - -2006-05-05 Eli Zaretskii - - * files.texi (File Names): Add a footnote about limited support of - ~USER on MS-Windows. - - * cmdargs.texi (Initial Options): Add a footnote about limited - support of ~USER on MS-Windows. - -2006-05-03 Richard Stallman - - * files.texi (Diff Mode): Node moved here. - (Comparing Files): Delete what duplicates new node. - (Files): Put Diff Mode in menu. - - * misc.texi (Diff Mode): Move to files.texi. - - * emacs.texi (Top): Update menu for Diff Mode. - - * trouble.texi (Emergency Escape): Simplify. - - * emacs.texi (Top): Minor clarification. - -2006-05-03 Teodor Zlatanov - - * commands.texi, entering.texi, screen.texi: Many simplifications. - -2006-05-03 Richard Stallman - - * commands.texi (Text Characters): Delete paragraph about unibyte - non-ASCII printing chars. - - * killing.texi (Killing): Say "graphical displays". - * display.texi: Say "graphical displays". - - * cmdargs.texi (Misc X): Say "graphical displays". - -2006-05-01 Richard Stallman - - * emacs.texi (Top): Add Diff Mode to menu. - -2006-05-01 Aaron S. Hawley - - * misc.texi (Diff Mode): New node. - -2006-05-01 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Now Carbon Emacs has ATSUI support. - (Mac Environment Variables): Shorten example line. - (Mac Font Specs): Shorten lisp lines. Add descriptions for ATSUI. - -2006-05-01 Nick Roberts - - * building.texi (GUD Customization): Describe cases %d and %c. - Update description for %e. - -2006-04-30 Glenn Morris - - * calendar.texi (LaTeX Calendar): Mention cal-tex-preamble-extra. - -2006-04-29 Dan Nicolaescu - - * custom.texi (Examining): Update C-h v output example. - -2006-04-29 Kim F. Storm - - * building.texi (Grep Searching): Add lgrep and rgrep. - -2006-04-23 Richard Stallman - - * emacs.texi [TeX]: Use xresmini.texi instead of xresources.texi. - - * xresmini.texi: New file. - - * xresources.texi (Face Resources): Split table into font resources - and the rest. Combine similar attributes for brevity. - -2006-04-21 Eli Zaretskii - - * emacs-xtra.texi (MS-DOS File Names): Remove section about - backslashes and case-insensitivity in file names (moved to the - main manual). - (MS-DOS Printing): Move most of the text to the main manual. - - * msdog.texi (Windows Files, Windows HOME, MS-Windows Printing): - New nodes. - (Windows Processes, Windows System Menu): Add index entries and - fix wording. - -2006-04-18 J.D. Smith - - * misc.texi (Shell Ring): Add notes on saved input when - navigating off the end of the history list. - -2006-04-18 Chong Yidong - - * misc.texi (Shell Options): Correct default value of - comint-scroll-show-maximum-output. - -2006-04-18 Nick Roberts - - * building.texi (Watch Expressions): Update. - -2006-04-12 Richard Stallman - - * search.texi: Clean up previous change. - -2006-04-12 Eli Zaretskii - - * search.texi (Regexp Backslash, Regexp Replace): Add index - entries for ``back reference'' and mention the term itself in the - text. - -2006-04-11 Richard Stallman - - * custom.texi (Safe File Variables): - Document enable-local-variables = :safe. - -2006-04-11 Karl Berry - - * emacs-xtra.texi, emacs.texi (Dired under VC, VC Dired Commands) - (Remote Repositories, Version Backups, Local Version Control) - (Snapshots, Making and Using Snapshots, Snapshot Caveats) - (Miscellaneous Commands and Features of VC, Change Logs and VC) - (Renaming VC Work Files and Master Files) - (Inserting Version Control Headers, Customizing VC, General Options) - (Options for RCS and SCCS, Options specific for CVS): Move all - these nodes to emacs-xtra.texi, for brevity. - * cmdargs.texi, files.texi: Change cross-references. - -2006-04-11 J.D. Smith - - * files.texi (Old Versions): Update description of vc-annotate's - use of color to indicate date ranges. - -2006-04-09 Kevin Ryde - - * sending.texi (Mail Sending): In send-mail-function @pxref smtpmail, - put info and printed manual names the right way around. - -2006-04-09 Karl Berry - - * msdog.texi, emacs-xtra.texi: Move all the MS-DOS material to - emacs-xtra.texi, leaving only MS Windows information. - * building.texi, emacs.texi, frames.texi, gnu.texi, macos.texi, - * msdog.texi, mule.texi, trouble.texi: Change cross-references and - node names. - - * emacs.texi: Move @summarycontents and @contents to the beginning - of the file. - -2006-04-08 Kevin Ryde - - * text.texi (Fill Commands): fill-nobreak-predicate is now a hook. - -2006-04-07 Richard Stallman - - * programs.texi (Comments, Comment Commands, Options for Comments) - (Multi-Line Comments): "Align", not "indent". - (Basic Indent): C-j deletes trailing whitespace before the newline. - -2006-04-06 Richard Stallman - - * programs.texi (Basic Indent): Clarify relationship of C-j to TAB. - -2006-04-06 Eli Zaretskii - - * killing.texi (Rectangles): Add index entry for marking a rectangle. - -2006-04-05 Richard Stallman - - * emacs.texi (Top): Update subnode menu. - - * trouble.texi (Unasked-for Search): Node deleted. - (Lossage): Delete from menu. - -2006-04-04 Richard Stallman - - * trouble.texi: Various cleanups. - (Checklist): Don't bother saying how to snail a bug report. - (Emergency Escape): Much rewriting. - (After a Crash): Rename the core dump immediately. - (Total Frustration): Call it a psychotherapist. - (Bug Criteria): Avoid "illegal instruction". - (Sending Patches): We always put the contributor's name in. - - * misc.texi (Thumbnails): Minor correction. - -2006-04-03 Richard Stallman - - * misc.texi (Thumbnails): Minor cleanup. - -2006-04-02 Karl Berry - - * sending.texi (Mail Sending): pxref to Top needs five args. - -2006-03-31 Richard Stallman - - * emacs.texi (Top): Update subnode menu. - - * help.texi (Help Mode): Cleanup. - - * dired.texi: Many cleanups. - (Dired Deletion): Describe dired-recursive-deletes. - (Operating on Files): dired-create-directory moved. - (Misc Dired Features): Move to here. - (Tumme): Node moved to misc.texi. - - * custom.texi: Many cleanups. - (Minor Modes): Don't mention ISO Accents Mode. - (Examining): Update C-h v output example. - (Hooks): Add index and xref for add-hook. - (Locals): Delete list of vars that are always per-buffer. Rearrange. - (Local Keymaps): Don't mention lisp-mode-map, c-mode-map. - - * misc.texi: Many cleanups. - (beginning): Add to summary of topics. - (Shell): Put eshell xref at the end. Remove eshell from table. - (Thumbnails): New node. - -2006-03-28 Eli Zaretskii - - * files.texi (File Name Cache): Make it clear that the cache is - not persistent. - -2006-03-25 Karl Berry - - * emacs-xtra.texi, emacs.texi, gnu.texi: - (1) use @copyright{} instead of (C) in typeset text; - (2) do not indent copyright year list (or anything else). - -2006-03-21 Juanma Barranquero - - * files.texi (VC Dired Mode): Remove misplaced brackets. - -2006-03-21 Andre Spiegel - - * files.texi: Various updates and clarifications in the VC chapter. - -2006-03-19 Luc Teirlinck - - * help.texi (Help Mode): Document "C-c C-c". - -2006-03-16 Luc Teirlinck - - * emacs-xtra.texi (Top): Avoid ugly continuation line in - menu in the standalone Info reader. - -2006-03-15 Chong Yidong - - * emacs-xtra.texi (Emerge, Picture Mode, Fortran): New chapters, - moved here from Emacs manual. - - * programs.texi (Fortran): Section moved to emacs-xtra. - (Program Modes): Xref to Fortran in emacs-xtra. - - * maintaining.texi (Emerge): Move to emacs-xtra. - * files.texi (Comparing Files): Xref to Emerge in emacs-xtra. - - * picture.texi: File deleted. - * Makefile.in: - * makefile.w32-in: Remove picture.texi. - - * text.texi (Text): Xref to Picture Mode in emacs-xtra. - * abbrevs.texi (Abbrevs): - * sending.texi (Sending Mail): Picture node removed. - - * emacs.texi (Top): Update node listings. - -2006-03-12 Richard Stallman - - * calendar.texi: Various cleanups. - -2006-03-11 Luc Teirlinck - - * search.texi (Regexps): Use @samp for regexp that is not in Lisp - syntax. - -2006-03-08 Luc Teirlinck - - * search.texi (Regexps): More accurately describe which characters - are special in which situations. Recommend _not_ to quote `]' or - `-' when they are not special. - -2006-02-28 Andre Spiegel - - * files.texi (Old Versions): Clarify operation of C-x v =. - -2006-02-21 Nick Roberts - - * building.texi (Watch Expressions): Update and describe - gdb-speedbar-auto-raise. - -2006-02-19 Richard M. Stallman - - * emacs.texi: Use @smallbook. - (Top): Update ref to Emacs paper, delete ref to Cookbook. - Update subnode menu. - - * building.texi (Lisp Interaction): Minor addition. - -2006-02-18 Nick Roberts - - * building.texi (Watch Expressions): Update and be more precise. - -2006-02-15 Francesco Potortì - - * maintaining.texi (Create Tags Table): Explain why the - exception when etags writes to files under the /dev tree. - -2006-02-14 Richard M. Stallman - - * custom.texi (Safe File Variables): Lots of clarification. - Renamed from Unsafe File Variables. - -2006-02-14 Chong Yidong - - * custom.texi (Unsafe File Variables): File variable confirmation - assumed denied in batch mode. - -2006-02-14 Richard M. Stallman - - * building.texi (GDB User Interface Layout): Don't say `inferior' - for program being debugged. - -2006-02-15 Nick Roberts - - * building.texi (GDB Graphical Interface): - Replace gdb-use-inferior-io-buffer with gdb-use-separate-io-buffer. - -2006-02-13 Chong Yidong - - * custom.texi (Specifying File Variables, Unsafe File Variables): - New nodes, split from File Variables. Document new file local - variable behavior. - -2006-02-13 YAMAMOTO Mitsuharu - - * display.texi (Standard Faces): - * files.texi (Visiting): - * frames.texi (Clipboard): - * glossary.texi (Glossary) : - * xresources.texi (X Resources): Mention Mac OS port. - -2006-02-12 Richard M. Stallman - - * building.texi (Building): Clarify topic in intro. - - * maintaining.texi (Maintaining): Change title; clarify topic. - Delete duplicate index entries. - - * building.texi (Other GDB User Interface Buffers): Clarifications. - - * text.texi (Cell Commands): Clarifications. - - * programs.texi (Defuns): Delete duplicate explanation of - left-margin paren convention. - (Hungry Delete): Minor cleanup. - -2006-02-11 Mathias Dahl - - * dired.texi (Tumme): More tumme documentation. - -2006-02-11 Alan Mackenzie - - * programs.texi ("Hungry Delete"): Correct the appellation of the - backspace and delete keys to @kbd{DEL} and @kbd{DELETE}. - -2006-02-11 Mathias Dahl - - * dired.texi (Tumme): Fix small bug. - -2006-02-10 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Rename "fontset-mac" to - "fontset-standard". - -2006-02-09 Mathias Dahl - - * dired.texi (Tumme): Basic documentation for Tumme added. - -2006-02-07 Luc Teirlinck - - * mule.texi (International): - * programs.texi (Basic Indent): Fix typos. - - * custom.texi (Minor Modes): - * display.texi (Text Display): - * commands.texi (Text Characters): Update xrefs. - -2006-02-07 Richard M. Stallman - - * emacs.texi (Top): Update subnode menu. - Update info on old Emacs papers. - (Intro): "Graphical display", not window system. - - * xresources.texi (GTK styles): Minor clarifications. - - * trouble.texi: "Graphical display", not window system. - (Stuck Recursive): Minor clarification. - - * text.texi: Minor clarifications. - (Sentences): Explain why two-space convention is better. - Explain sentence-end-without-period here. - (Fill Commands): Not here. - (Refill): Node moved down. - (Filling): Update menu. - (Table Creation, Cell Justification, Column Commands): Clarify. - - * sending.texi: Minor clarifications. - - * search.texi (Regexp Backslash): Clarification. - - * rmail.texi: Minor cleanups. - (Rmail): Delete digression about `rmail-mode'. - (Rmail Inbox): Delete false advice wrt rmail-primary-inbox-list. - (Rmail Files): Mention C-u M-x rmail. - (Rmail Reply): Mention References. - (Rmail Display): Mention rmail-nonignored-headers. - - * programs.texi: Minor cleanups. - (Comment Commands): Mention momentary Transient Mark mode. - (Matching): Be more specific about customizing show-paren-mode. - (Info Lookup): Don't list the modes that support C-h S. - Just say what it does in an unsupported mode. - (Man Page): Delete excessive info on customizing woman. - (Motion in C): Don't mention c-for/backward-into-nomenclature. - - * abbrevs.texi: Minor clarifications. - (Dabbrev Customization): Talk about "dynamic abbrev expansion", - not "dynamic abbrevs" as if they were a kind of abbrev. - - * picture.texi (Picture): Minor cleanup. - - * mule.texi (Communication Coding): Say "other applications". - (Fontsets): Not specific to X. Add xref to X Resources. - (Unibyte Mode): Rename from Single-Byte Character Support. - "Graphical display", not window system. - (International): Update menu. - - * maintaining.texi (Format of ChangeLog): - New node, split out from ChangeLog. - (ChangeLog): Clarifications in the remaining text. - (Create Tags Table, Etags Regexps, Select Tags Table): Cleanups. - (Find Tag): Add @w. - (Tags Search): Explain tag table order here. Simplify grep ref. - (List Tags): tags-tag-face is a variable, not a face. - (Emerge): Cleanups. - - * kmacro.texi (Keyboard Macro Counter): Rewrite for clarity. - (Keyboard Macros): Avoid "the user". - - * killing.texi: "Graphical display", not window system. - - * help.texi (Help Echo): "Graphical display", not window system. - - * glossary.texi: Say "you", not "the user". Say "graphical display". - - * frames.texi: Minor cleanups. "Graphical display", not window system. - - * files.texi (Visiting): Make drag-and-drop not X-specific. - - * custom.texi: Minor cleanups. "Graphical display", not window system. - - * cmdargs.texi: Minor cleanups. - - * building.texi (Compilation): Move and split kill-compilation para. - Add para about multiple compilers. - (Compilation Mode): Commands also available in grep mode and others. - Mention C-u C-x ` more tutorially. Clarify C-x `. - (Compilation Shell): Clarify. Put Bash example first. - (Grep Searching): Minor cleanups; add @w. - (Debuggers): Minor cleanups. - (Starting GUD): Make GDB xgraphical mode issue clearer. - (Debugger Operation): Lots of clarifications including - GDB tooltip side-effect issue. - (Commands of GUD): Clarify. - (GUD Customization): Add bashdb-mode-hook. - (GDB Graphical Interface): Rewrite for clarity. - (GDB User Interface Layout): Rewrite for clarity. - (Stack Buffer, Watch Expressions): Likewise. - (Other GDB User Interface Buffers): Cleanups. - (Lisp Libraries, External Lisp): Cleanup. - - * basic.texi (Position Info): "Graphical displays", rather than - window systems. - - * anti.texi: Minor cleanup. - -2006-02-03 Eli Zaretskii - - * custom.texi (Init File, Find Init): Add cross-references to - where $HOME is described. - -2006-02-01 Luc Teirlinck - - * frames.texi (Frame Parameters): Remove @item for S-Mouse-1; it - is not inside the @table. - - * emacs.texi (Top): Correct node name. - - * files.texi (File Names): Fix @xref. - (Reverting): Fix typo. - - * mule.texi (International): Correct node name. - - * kmacro.texi (Save Keyboard Macro): Add missing @kbd to @table. - -2006-02-01 Richard M. Stallman - - * emacs.texi (Top): Update subnode menu. - - * mule.texi: Minor clarifications. - Reduce the specific references to X Windows. - Refer to "graphical" terminals, rather than window systems. - (Text Coding): Rename from Specify Coding. - (Communication Coding, File Name Coding, Terminal Coding): - New nodes split out from Text Coding. - - * kmacro.texi: Minor clarifications. - (Keyboard Macro Ring): Comment out some excessive commands. - (Basic Keyboard Macro): Split up the table, putting part in each node. - - * major.texi: Minor clarifications. - - * misc.texi (Single Shell, Interactive Shell): Fix xrefs. - - * windows.texi: Minor clarifications. - (Change Window): Don't describe mode-line mouse cmds here. - Add xref to Mode Line Mouse. - - * msdog.texi (Text and Binary, MS-DOS and MULE): Fix xrefs. - - * macos.texi (Mac International): Fix xref. - - * indent.texi: Minor clarifications. - - * frames.texi: Minor clarifications. - Reduce the specific references to X Windows. - Refer to "graphical" terminals, rather than window systems. - (Frame Parameters): Don't mention commands like - set-foreground-color. Just say to customize a face. - (Drag and Drop): Lisp-level stuff moved to Emacs Lisp manual. - - * files.texi: Minor clarifications. - (Numbered Backups): New node, split out from Backup Names. - - * display.texi (Font Lock): C mode no longer depends on (-in-col-0. - - * cmdargs.texi (General Variables): Fix xref. - - * buffers.texi: Minor clarifications. - -2006-01-31 Richard M. Stallman - - * display.texi (Scrolling, Horizontal Scrolling, Follow Mode): - Nodes moved to top. - - * display.texi: Minor clarifications. - (Display): Rearrange menu. - (Standard Faces): Mention query-replace face. - (Faces): Simplify. - (Font Lock): Simplify face customization info. - (Highlight Changes): Node merged into Highlight Interactively. - (Highlight Interactively): Much rewriting and cleanup. - (Optional Mode Line): Narrowed line number not good for goto-line. - Simplify face customization advice. - (Text Display): Mention use of escape-glyph face. - Move ctl-arrow and tab-width here. - (Display Custom): Move no-redraw-on-reenter to end of node. - - * search.texi: Minor clarifications. - (Isearch Scroll): Simplify. - (Other Repeating Search): Document multi-occur-in-matching-buffers. - - * regs.texi (Registers): Mention bookmarks here. - - * mark.texi: Minor clarifications. - (Selective Undo): Node deleted. - - * m-x.texi: Minor clarifications. - - * killing.texi: Minor clarifications. - Refer to "graphical" terminals, rather than window systems. - - * help.texi: Clarifications. - (Help): Don't describe C-h F and C-h K here. - (Key Help): Describe C-h K here. - (Name Help): Mention Emacs Lisp Intro. - Describe C-h F here. - (Misc Help): Mention C-h F and C-h K only briefly. - - * fixit.texi (Undo): New node, mostly copied from basic.texi. - Selective undo text merged in. - (Spelling): Mention Aspell along with Ispell. - - * emacs.texi (Top): Update subnode menus. - - * basic.texi (Basic Undo): Rename from Undo. Most of text - moved to new Undo node. - -2006-01-29 Chong Yidong - - * basic.texi (Continuation Lines, Inserting Text): - Mention longlines mode. - -2006-01-29 Richard M. Stallman - - * screen.texi: Minor cleanups. - (Screen): Clean up the intro paragraphs. - (Mode Line): Lots of rewriting. Handle frame-name better. - eol-mnemonic-... vars moved out. - - * emacs.texi (Top): Change menu item for MS-DOS node. - Update subnode menu. - - * msdog.texi (MS-DOS): Rewrite intro to explain how this - chapter relates to Windows. Title changed. - - * mini.texi: Minor cleanups. - - * mark.texi (Selective Undo): New node, text moved from basic.texi. - (Mark): Put it in the menu. - - * entering.texi: Minor cleanups. - - * emacs.texi (Top): Add xref to Mac chapter; explain Windows better. - (Intro): Refer to "graphical" terminals, rather than X. - - * display.texi (Display Custom): Add xref to Variables. - (Optional Mode Line): eol-mnemonic-... vars moved here. - - * commands.texi: Minor cleanups. Refer to "graphical" terminals, - rather than X. - - * basic.texi: Minor cleanups. - (Undo): selective-undo moved. - -2006-01-25 Luc Teirlinck - - * anti.texi (Antinews): Various corrections and additions. - -2006-01-23 Juri Linkov - - * custom.texi (Easy Customization, Customization Groups) - (Browsing Custom): Mention links along with buttons. - -2006-01-21 Eli Zaretskii - - * text.texi (TeX Print): Use @key for TAB. - - * kmacro.texi (Keyboard Macro Step-Edit): Use @key for TAB. - -2006-01-15 Sven Joachim (tiny change) - - * files.texi (File Aliases): Don't claim that usually separate - buffers are created for two file names that name the same data. - Mention additional situations where different names mean the same - file on disk. - -2006-01-19 Richard M. Stallman - - * killing.texi (Deletion): Upcase @key argument. - - * custom.texi (Custom Themes): Minor cleanup. - - * programs.texi (Hungry Delete): Upcase @key argument. - -2006-01-16 Juri Linkov - - * display.texi (Standard Faces): Add `mode-line-buffer-id'. - Move `mode-line-highlight' before `mode-line-buffer-id'. - -2006-01-14 Richard M. Stallman - - * basic.texi (Inserting Text): Minor cleanup. - -2006-01-11 Luc Teirlinck - - * custom.texi (Changing a Variable, Face Customization): - Update for changes in Custom menus. - -2006-01-05 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Undo last change. - -2006-01-02 Chong Yidong - - * custom.texi (Custom Themes): Describe the new - customize-create-theme interface. - -2005-12-30 Juri Linkov - - * basic.texi (Position Info): Update example. - -2005-12-27 Jan Djärv - - * frames.texi (Dialog Boxes): Add x-gtk-show-hidden-files. - -2005-12-24 Chong Yidong - - * custom.texi (Custom Themes): `load-theme' always loads. - -2005-12-23 Juri Linkov - - * display.texi (Highlight Interactively): Use double space to - separate sentences. Replace C-p with M-p, and C-n with M-n. - -2005-12-22 Richard M. Stallman - - * custom.texi (Easy Customization and subnodes): - Replace "active field" with "button". - Use "user option" only for variables. - Use "setting" for variable-or-face. - -2005-12-22 Luc Teirlinck - - * buffers.texi (Select Buffer): Change order in table to make - "Similar" refer to the correct item. - (Indirect Buffers): Minor rewording. - -2005-12-20 Juri Linkov - - * files.texi (VC Status): Put P and N near p and n. - -2005-12-19 Richard M. Stallman - - * programs.texi (Electric C): Delete the info about newline control. - (Other C Commands): Minor cleanup. - (Left Margin Paren): Minor cleanup. - -2005-12-19 Luc Teirlinck - - * custom.texi (Easy Customization): Add "Browsing Custom" to menu. - (Customization Groups): Delete text moved to "Browsing Custom". - (Browsing Custom): New node. - (Specific Customization): Clarify which commands only work for - loaded options. - -2005-12-18 Bill Wohler - - * frames.texi (Tool Bars): Shorten text of previous change. - -2005-12-18 Aaron S. Hawley - - * files.texi (VC Status): Document log-view mode. - -2005-12-18 Bill Wohler - - * frames.texi (Tool Bars): Mention that you can turn off tool bars - permanently via the customize interface. - -2005-12-16 Ralf Angeli - - * killing.texi (Killing by Lines): Document `kill-whole-line' - function. - -2005-12-16 Lőrentey Károly - - * buffers.texi (Select Buffer): Change `prev-buffer' to - `previous-buffer'. Indicate that these functions use a frame - local buffer list. - -2005-12-12 Richard M. Stallman - - * custom.texi (Easy Customization): Change menu comment. - (Prefix Keymaps): Fix spelling of Control-X-prefix. - - * help.texi (Apropos): Rewrite. Talk about "apropos patterns". - (Help): Among the Apropos commands, describe only C-h a here. - -2005-12-11 Richard M. Stallman - - * programs.texi (Options for Comments): Comment-end starts with space. - - * glossary.texi (Glossary): Minor cleanup. - - * files.texi (Old Versions): Use @table. - -2005-12-10 David Koppelman - - * display.texi (Highlight Interactively): Include - global-hi-lock-mode. Add miscellaneous details and elaborations. - -2005-12-09 Richard M. Stallman - - * display.texi (Font Lock): Delete the Global FL menu item. - -2005-12-09 Luc Teirlinck - - * custom.texi (Minibuffer Maps): Mention the maps for file name - completion. - -2005-12-09 Kim F. Storm - - * killing.texi (CUA Bindings): Describe how to use C-x and C-c as - prefix keys even when mark is active. Describe that RET moves - cursor to next corner in rectangle; clarify insert around rectangle. - -2005-12-08 Luc Teirlinck - - * custom.texi (Customization): Use xref to elisp manual for - non-TeX output. - (Minor Modes): Update. - (Customization Groups, Changing a Variable, Face Customization): - Update for new appearance of Custom buffers. - (Changing a Variable): `custom-buffer-done-function' has been - replaced by `custom-buffer-done-kill'. - (Specific Customization): In the `customize-group' buffer, a - subgroup's contents are not "hidden". They are not included at - all. They have no [Show] button. - (Mouse Buttons): Add pxref to description of mouse event lists in - Elisp manual. Add `menu-bar' and `header-line' dummy prefix keys. - (Find Init): Emacs now looks for ~/.emacs.d/init.el instead of - ~/.emacs.d/.emacs, if it can not find ~/.emacs(.el). - -2005-12-08 Richard M. Stallman - - * mini.texi (Completion Commands, Completion): - In file name input, SPC does not do completion. - -2005-12-08 Nick Roberts - - * building.texi (GDB Graphical Interface): Explain screen size - setting. - (Other GDB User Interface Buffers): Describe features specific to - GDB 6.4. - -2005-12-01 Nick Roberts - - * building.texi (GDB User Interface Layout): Describe how to - kill associated buffers. - (Breakpoints Buffer): Use D instead of d for gdb-delete-breakpoint. - (Watch Expressions): Be more precise. - (Other GDB User Interface Buffers): Describe how to change a - register value. - -2005-11-24 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Remove description of - mac-command-key-is-meta. Add descriptions of - mac-control-modifier, mac-command-modifier, and - mac-option-modifier. - (Mac International): Fix description of conversion of clipboard data. - (Mac Font Specs): Add example of font customization by face attributes. - -2005-11-22 Nick Roberts - - * building.texi (Watch Expressions): Expand description. - (Other GDB User Interface Buffers): Describe local map for - gud-watch. - -2005-11-21 Chong Yidong - - * display.texi (Font Lock): Font lock is enabled by default now. - -2005-11-20 Juri Linkov - - * basic.texi (Position Info): Update examples of the output. - Remove the fact that examples are produced in the TeXinfo buffer, - because in the Info reader users will get a different output from - `C-x ='. - - * building.texi (Compilation Mode): Remove paragraph duplicated - from the node `Compilation'. Add `compilation-skip-threshold'. - - * display.texi (Font Lock): Suggest more user-friendly method of - finding all Font Lock faces (M-x customize-group RET font-lock-faces). - -2005-11-18 Richard M. Stallman - - * files.texi (Registering): Mention @@ in mode line. - - * mini.texi (Minibuffer File): Clarify previous change. Add @findex. - -2005-11-08 Aaron S. Hawley - - * files.texi (Renaming and VC): Some back-ends don't - handle renaming. - -2005-11-17 Juri Linkov - - * emacs.texi (Top): - * display.texi (Highlight Interactively): Put this font-lock based - mode near Font Lock node. - -2005-11-16 Chong Yidong - - * ack.texi (Acknowledgments): Acknowledge Andrew Zhilin for Emacs - icons. - -2005-11-12 Kim F. Storm - - * help.texi (Help): Fix C-h a entry. Add C-h d entry. - (Help Summary): Add C-h d and C-h e. - (Apropos): Clarify that all apropos commands may search for either - list of words or a regexp. Add C-h d for apropos-documentation. - Describe apropos-documentation-sort-by-scores user option. - -2005-11-09 Luc Teirlinck - - * killing.texi (CUA Bindings): Add @section. - -2005-11-10 Kim F. Storm - - * emacs.texi (Top): Add CUA Bindings entry to menu. - - * killing.texi (CUA Bindings): New node. Moved here from - misc.texi and extended with info on rectangle commands and - rectangle highlighting, interface to registers, and the global - mark feature. - - * misc.texi (Emulation): Move CUA bindings item to killing.texi. - - * regs.texi: Prev link points to CUA Bindings node. - -2005-11-07 Luc Teirlinck - - * help.texi (Help Echo): By default, help echos are only shown on - mouse-over, not on point-over. - -2005-11-04 Jérôme Marant - - * misc.texi (Shell Mode): Describe how to activate password echoing. - -2005-11-04 Romain Francoise - - * mark.texi (Mark Ring): Fix typo. - -2005-11-03 Richard M. Stallman - - * mark.texi (Mark Ring): Mention set-mark-command-repeat-pop. - -2005-11-01 Bill Wohler - - * help.texi (Help Mode): Fix typo. - -2005-11-01 Nick Roberts - - * building.texi (Other GDB User Interface Buffers): - Describe the command gdb-use-inferior-io-buffer. - -2005-10-31 Romain Francoise - - * files.texi (Compressed Files): Fix typo. - - * buffers.texi (Misc Buffer): Downcase `*shell*'. - - * windows.texi (Force Same Window): Likewise. - -2005-10-30 Bill Wohler - - * help.texi (Help Mode): URLs viewed with browse-url. - -2005-10-31 Nick Roberts - - * building.texi (GDB Graphical Interface): Don't reference - gdb-mouse-set-clear-breakpoint. Explain gdb-mouse-until - must stay in same frame. - -2005-10-29 Chong Yidong - - * custom.texi (Init File): Document ~/.emacs.d/init.el. - - * anti.texi (Antinews): Likewise. - -2005-10-28 Bill Wohler - - * help.texi (Help): Help mode now creates hyperlinks for URLs. - -2005-10-28 Richard M. Stallman - - * files.texi (Visiting): Explain how to enter ? in a file name. - - * trouble.texi (Memory Full): Mention !MEM FULL! in mode line. - -2005-10-25 Nick Roberts - - * building.texi (GDB Graphical Interface): - Describe gdb-mouse-until. - -2005-10-23 Richard M. Stallman - - * custom.texi (Init File): Recommend when to use site-start.el. - -2005-10-21 Juri Linkov - - * custom.texi (Examining): Mention accessing the old variable - value via M-n in set-variable. - -2005-10-18 Romain Francoise - - * files.texi (Version Systems): Capitalize GNU. - -2005-10-18 Nick Roberts - - * building.texi (Compilation Mode): Remove redundant paragraph. - (Watch Expressions): Remove paragraph to reflect code change. - -2005-10-16 Richard M. Stallman - - * building.texi (Compilation Mode, Compilation): Clarified. - -2005-10-15 Richard M. Stallman - - * misc.texi (Saving Emacs Sessions): Mention savehist library. - -2005-10-13 Kenichi Handa - - * basic.texi (Position Info): Fix previous change. - -2005-10-12 Jan Djärv - - * cmdargs.texi (Icons X): Fix typo. - -2005-10-12 Kenichi Handa - - * basic.texi (Position Info): Describe the case that Emacs shows - "part of display ...". - -2005-10-10 Jan Djärv - - * cmdargs.texi (Icons X): -nb => -nbi. - -2005-10-10 Chong Yidong - - * frames.texi (Speedbar): A couple more clarifications. - -2005-10-11 Nick Roberts - - * building.texi (GDB User Interface Layout): Improve diagram. - (Watch Expressions): Explain how to make speedbar global. - (Other GDB User Interface Buffers): Make references more precise. - -2005-10-09 Richard M. Stallman - - * frames.texi (Speedbar): Clarify the text. - -2005-10-09 Chong Yidong - - * frames.texi (Speedbar): Add information on keybindings, - dismissing the speedbar, and buffer display mode. Link to - speedbar manual. - -2005-10-09 Jan Djärv - - * cmdargs.texi (Icons X): Remove options -i, -itype, --icon-type, - added -nb, --no-bitmap-icon. - -2005-10-07 Nick Roberts - - * building.texi (GDB Graphical Interface): Add variables and - functions to indices. Be more precise. - -2005-10-03 Jan Djärv - - * frames.texi (Drag and Drop): Remove the x- from - x-dnd-open-file-other-window and xdnd-protocol-alist. - -2005-09-30 Romain Francoise - - * mini.texi (Minibuffer): The default value now appears before the - colon in minibuffer prompts. - -2005-09-25 Richard M. Stallman - - * search.texi (Regexp Search): Doc search-whitespace-regexp. - -2005-09-20 Emanuele Giaquinta (tiny change) - - * text.texi (Paragraphs): Correction about Paragraph-Indent Text mode. - -2005-09-21 YAMAMOTO Mitsuharu - - * emacs.texi (Top): Update submenus from macos.texi. - - * macos.texi: Change `Mac OS 8 or 9' to `Mac OS Classic'. - (Mac OS): Update feature support status. - (Mac Input): List supported input scripts. Remove description - about `mac-keyboard-text-encoding'. Mention mouse button - emulation and related variables. - (Mac International): Mention Central European and Cyrillic - support. Now `keyboard-coding-system' is dynamically changed. - Add description about coding system for selection. - Add description about language environment. - (Mac Environment Variables): - Mention `~/.MacOSX/environment.plist'. Give example of command line - arguments. Add Preferences support. - (Mac Directories): Explicitly state that this node is for Mac OS - Classic only. - (Mac Font Specs): Mention specification for scalable fonts. - List supported charsets. Add preferred way of creating fontsets. - Add description about `mac-allow-anti-aliasing'. - (Mac Functions): Add descriptions about `mac-set-file-creator', - `mac-get-file-creator', `mac-set-file-type', `mac-get-file-type', - and `mac-get-preference'. - -2005-09-16 Romain Francoise - - Update all files to specify GFDL version 1.2. - - * doclicense.texi (GNU Free Documentation License): Update to - version 1.2. - -2005-09-15 Richard M. Stallman - - * buffers.texi (List Buffers): Fix xref. - - * rmail.texi (Rmail Basics): Fix xref. - - * emacs.texi (Top): Update subnode menus. - - * files.texi (Saving Commands): New node, broken out of Saving. - (Customize Save): New node, broken out of Saving. - Clarify effect of write-region-inhibit-fsync. - (Misc File Ops): Say write-region-inhibit-fsync affects write-region. - -2005-09-14 Romain Francoise - - * files.texi (Saving): Mention write-region-inhibit-fsync. - -2005-09-05 Chong Yidong - - * custom.texi (Custom Themes): New node. - -2005-09-03 Richard M. Stallman - - * search.texi (Search Case): Mention vars that control - case-fold-search for various operations. - -2005-08-22 Juri Linkov - - * display.texi (Standard Faces): Merge the text from - `(elisp)Standard Faces' into this node. - -2005-08-18 Luc Teirlinck - - * emacs.texi (Top): Delete menu item for deleted node - Keyboard Translations. - -2005-08-18 Richard M. Stallman - - * trouble.texi (Unasked-for Search): - Delete xref to Keyboard Translations. - - * glossary.texi (Glossary): Delete xref. - - * custom.texi (Minor Modes): Say that the list here is not complete. - (Keyboard Translations): Node deleted. - (Disabling): Delete xref to it. - (Customization Groups): Fix Custom buffer example. - (Hooks): Mention remove-hooks. - -2005-08-17 Luc Teirlinck - - * building.texi (GDB Graphical Interface): Improve filling of menu - item. - -2005-08-18 Nick Roberts - - * building.texi (GDB Graphical Interface): Use better node names. - -2005-08-14 Richard M. Stallman - - * text.texi (Sentences): Fix xref. - -2005-08-14 Juri Linkov - - * building.texi (Compilation, Grep Searching): Move grep command - headings from `Compilation' to `Grep Searching'. - - * dired.texi (Dired and Find): - * maintaining.texi (Tags Search): Replace grep xref to - `Compilation' node with `Grep Searching'. - - * files.texi (Comparing Files): Replace xref to `Compilation' with - `Compilation Mode'. - -2005-08-13 Alan Mackenzie - - * search.texi (Non-ASCII Isearch): Correct a typo. - (Replacement Commands): Mention query-replace key binding. - -2005-08-11 Richard M. Stallman - - * programs.texi (Options for Comments): Fix xref. - - * search.texi (Regexp Backslash, Regexp Example): New nodes split - out of Regexps. - -2005-08-09 Juri Linkov - - * building.texi (Compilation): Use `itemx' instead of `item'. - (Grep Searching): Simplify phrase. - - * display.texi (Standard Faces): Describe vertical-border on - window systems. - - * windows.texi (Split Window): Simplify phrase and mention - vertical-border face. - -2005-08-09 Richard M. Stallman - - * files.texi (Comparing Files): Clarify compare-windows. - - * calendar.texi (Scroll Calendar): Document < and > in calendar. - -2005-08-06 Eli Zaretskii - - * mule.texi (Coding Systems): Rephrase the paragraph about - codepages: no need for "M-x codepage-setup" anymore, except on - MS-DOS. - - * msdog.texi (MS-DOS and MULE): Clarify that this section is for - the MS-DOS port only. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run multi-install-info.bat. - ($(infodir)/dir): New target, produced by running - multi-install-info.bat. - -2005-07-22 Eli Zaretskii - - * files.texi (Quoted File Names): Add index entry. - -2005-07-19 Juri Linkov - - * files.texi (Comparing Files): Mention resync for `compare-windows'. - -2005-07-18 Juri Linkov - - * custom.texi (Easy Customization): - * files.texi (Old Versions): - * frames.texi (Wheeled Mice): - * mule.texi (Specify Coding): - * text.texi (Cell Justification): - * trouble.texi (After a Crash): - * xresources.texi (GTK styles): - Delete duplicate duplicate words. - -2005-07-17 Richard M. Stallman - - * frames.texi (Creating Frames): Fix foreground color example. - - * custom.texi (Init Examples): Clean up text about conditionals. - -2005-07-16 Richard M. Stallman - - * mini.texi (Completion Commands): Fix command name for ?. - -2005-07-16 Eli Zaretskii - - * display.texi (Standard Faces): Explain that customization of - `menu' face has no effect on w32 and with GTK. - Add cross-references. - - * cmdargs.texi (General Variables): Clarify the default location - of $HOME on w32 systems. - -2005-07-15 Jason Rumney - - * cmdargs.texi (General Variables): Default HOME on MS Windows has - changed. - -2005-07-08 Kenichi Handa - - * mule.texi (Recognize Coding): - Recommend revert-buffer-with-coding-system instead of revert-buffer. - -2005-07-07 Richard M. Stallman - - * anti.texi (Antinews): Mention mode-line-inverse-video. - - * files.texi (Saving): Minor correction about C-x C-w. - - * display.texi (Display Custom): Don't mention mode-line-inverse-video. - -2005-07-07 Luc Teirlinck - - * search.texi (Isearch Scroll): Add example of using the - `isearch-scroll' property. - (Slow Isearch): Reference anchor for `baud-rate' instead of entire - `Display Custom' node. - (Regexp Replace): Put text that requires Emacs Lisp knowledge last - and de-emphasize it. - (Other Repeating Search): `occur' currently can not correctly - handle multiline matches. Correct, clarify and update description - of `flush-lines' and `keep-lines'. - - * display.texi (Display Custom): Add anchor for `baud-rate'. - -2005-07-07 Richard M. Stallman - - * gnu.texi: Update where to get GNU status; add refs for how to help. - Add footnotes 6 and 7. - -2005-07-04 Lute Kamstra - - Update FSF's address in GPL notices. - - * doclicense.texi (GNU Free Documentation License): - * trouble.texi (Checklist): Update FSF's address. - -2005-06-24 Richard M. Stallman - - * display.texi (Text Display): Change index entries. - -2005-06-24 Eli Zaretskii - - * makefile.w32-in (MAKEINFO): Use --force. - (INFO_TARGETS, DVI_TARGETS): Make identical to the lists in - Makefile.in. - -2005-06-23 Richard M. Stallman - - * anti.texi (Antinews): Rename show-nonbreak-escape to - nobreak-char-display. - - * emacs.texi (Top): Update detailed node listing. - - * display.texi (Text Display): Rename show-nonbreak-escape - to nobreak-char-display and no-break-space to nobreak-space. - (Standard Faces): Split up the list of standard faces - and put it in a separate node. Add nobreak-space and - escape-glyph. - -2005-06-23 Lute Kamstra - - * mule.texi (Select Input Method): Fix typo. - -2005-06-23 Kenichi Handa - - * mule.texi (International): List all supported scripts. - Adjust text for that leim is now included in the normal Emacs - distribution. - (Language Environments): List all language environments. - Intlfonts contains fonts for most supported scripts, not all.. - (Select Input Method): Refer to C-u C-x = to see how to type to - input a specific character. - (Recognize Coding): Fix typo, china-iso-8bit -> chinese-iso-8bit. - -2005-06-23 Juanma Barranquero - - * building.texi (Grep Searching): Texinfo usage fix. - -2005-06-22 Miles Bader - - * display.texi (Faces): Change `vertical-divider' to `vertical-border'. - -2005-06-20 Miles Bader - - * display.texi (Faces): Add `vertical-divider'. - -2005-06-17 Richard M. Stallman - - * text.texi (Adaptive Fill): Minor clarification. - -2005-06-10 Lute Kamstra - - * emacs.texi (Top): Correct version number. - * anti.texi (Antinews): Correct version number. Use EMACSVER to - refer to the current version of Emacs. - -2005-06-08 Luc Teirlinck - - * files.texi (Log Buffer): Document when there can be more than - one file to be committed. - -2005-06-08 Juri Linkov - - * display.texi (Faces): Add `shadow' face. - -2005-06-07 Masatake YAMATO - - * display.texi (Faces): Write about mode-line-highlight. - -2005-06-06 Richard M. Stallman - - * misc.texi (Printing Package): Explain how to initialize - printing package. - - * cmdargs.texi (Action Arguments): Clarify directory default for -l. - -2005-06-05 Chong Yidong - - * emacs.texi: Rename Hardcopy to Printing. - Make PostScript and PostScript Variables subnodes of it. - - * misc.texi (Printing): Rename node from Hardcopy. - Mention menu bar options. - Move PostScript and PostScript Variables to submenu. - (Printing package): New node. - - * mark.texi (Using Region): Change Hardcopy xref to Printing. - - * dired.texi (Operating on Files): Likewise. - - * calendar.texi (Displaying the Diary): Likewise. - - * msdog.texi (MS-DOS Printing, MS-DOS Processes): Likewise. - - * glossary.texi (Glossary): Likewise. - - * frames.texi (Mode Line Mouse): Mention mode-line-highlight - effect. - -2005-06-04 Richard M. Stallman - - * trouble.texi (After a Crash): Polish previous change. - -2005-05-30 Noah Friedman - - * trouble.texi (After a Crash): Mention emacs-buffer.gdb as a - recovery mechanism. - -2005-05-28 Nick Roberts - - * building.texi (Other Buffers): SPC toggles display of - floating point registers. - -2005-05-27 Nick Roberts - - * files.texi (Log Buffer): Merge in description of Log Edit - mode from pcl-cvs.texi. - -2005-05-26 Richard M. Stallman - - * building.texi (Lisp Eval): C-M-x with arg runs Edebug. - -2005-05-24 Luc Teirlinck - - * fixit.texi (Spelling): Delete confusing sentence; flyspell is - not enabled by default. - When not on a word, `ispell-word' by default checks the word - before point. - -2005-05-24 Nick Roberts - - * building.texi (Debugger Operation): Simplify last sentence. - -2005-05-23 Lute Kamstra - - * emacs.texi: Update FSF's address throughout. - (Preface): Use @cite. - (Distrib): Add cross reference to the node "Copying". Mention the - FDL. Don't refer to etc/{FTP,ORDERS}. Mention the sale of - printed manuals. - (Intro): Use @xref for the Emacs Lisp Intro. - -2005-05-18 Luc Teirlinck - - * buffers.texi (Select Buffer): Document `C-u M-g M-g'. - - * basic.texi (Moving Point): Mention default for `goto-line'. - - * programs.texi (Lisp Doc): Eldoc mode shows only the first line - of a variable's docstring. - -2005-05-18 Lute Kamstra - - * maintaining.texi (Overview of Emerge): Add cross reference. - Remove duplication. - - * emacs.texi (Top): Update to the current structure of the manual. - * misc.texi (Emacs Server): Add menu description. - * files.texi (Saving): Fix menu. - * custom.texi (Customization): Fix menu. - * mule.texi (International): Fix menu. - * kmacro.texi (Keyboard Macros): Fix menu. - -2005-05-16 Luc Teirlinck - - * display.texi: Various minor changes. - (Faces): Delete text that is repeated in the next section. - -2005-05-16 Nick Roberts - - * building.texi (Debugger Operation): Mention GUD tooltips are - disabled with GDB in text command mode. - -2005-05-16 Nick Roberts - - * building.texi: Replace toolbar with "tool bar" for consistency. - (Compilation Mode): Describe compilation-context-lines - and use of arrow in compilation buffer. - (Debugger Operation): Replace help text with variable's value. - - * frames.texi (Tooltips): Replace toolbar with "tool bar" for - consistency. - -2005-05-15 Luc Teirlinck - - * major.texi (Choosing Modes): normal-mode processes the -*- line. - Add xref. - -2005-05-14 Luc Teirlinck - - * basic.texi (Moving Point): Mention `M-g g' binding for `goto-line'. - (Position Info): Delete discussion of `goto-line'. It is already - described in `Moving point'. - - * mini.texi (Completion Commands): Correct reference. - (Completion Options): Fix typo. - - * killing.texi (Deletion): Complete description of `C-x C-o'. - -2005-05-10 Richard M. Stallman - - * building.texi (Compilation): Clarify recompile's directory choice. - - * frames.texi (Tooltips): Cleanups. - - * basic.texi (Arguments): Fix punctuation. - -2005-05-09 Luc Teirlinck - - * screen.texi (Menu Bar): The up and down (not left and right) - arrow keys move through a keyboard menu. - -2005-05-08 Luc Teirlinck - - * basic.texi: Various typo and grammar fixes. - (Moving Point): C-a now runs move-beginning-of-line. - -2005-05-08 Nick Roberts - - * building.texi (Debugger Operation): Describe gud-tooltip-echo-area. - - * frames.texi (Tooltips): Describe help tooltips and GUD tooltips - as different animals. - -2005-05-07 Luc Teirlinck - - * frames.texi (Mouse References): Clarify `mouse-1-click-follows-link'. - Correct index entry. - -2005-05-07 Nick Roberts - - * building.texi (Debugger Operation): Update to reflect changes - in GUD tooltips. - -2005-04-30 Richard M. Stallman - - * files.texi (Compressed Files): Auto Compression normally enabled. - - * building.texi (Debugger Operation): Clarify previous change. - -2005-04-28 Nick Roberts - - * building.texi (Debugger Operation): Add description for - GUD tooltips when program is not running. - -2005-04-26 Luc Teirlinck - - * misc.texi (Shell): Add `Shell Prompts' to menu. - (Shell Mode): Add xref to `Shell Prompts'. Clarify `C-c C-u' - description. Delete remarks moved to new node. - (Shell Prompts): New node. - (History References): Replace remarks moved to `Shell Prompts' - with xref to that node. - (Remote Host): Clarify how to specify the terminal type when - logging in to a different machine. - -2005-04-26 Richard M. Stallman - - * emacs.texi (Top): Update submenus from files.texi. - - * files.texi (Filesets): Clarify previous change. - - * dired.texi (Misc Dired Features): Clarify previous change. - -2005-04-25 Chong Yidong - - * ack.texi (Acknowledgments): Delete info about iso-acc.el. - - * dired.texi (Misc Dired Features): - Document dired-compare-directories. - - * files.texi (Filesets): New node. - (File Conveniences): Document Image mode. - - * text.texi (TeX Print): Document tex-compile. - -2005-04-25 Luc Teirlinck - - * frames.texi (Tooltips): Tooltip mode is enabled by default. - Delete redundant reference to tooltip Custom group. It is - referred too again in the next paragraph. - -2005-04-24 Richard M. Stallman - - * ack.texi: Delete info about lazy-lock.el and fast-lock.el. - -2005-04-19 Kim F. Storm - - * building.texi (Compilation Mode): Add M-g M-n and M-g M-p bindings. - -2005-04-18 Lars Hansen - - * misc.texi (Saving Emacs Sessions): Add that "--no-desktop" now - turns off desktop-save-mode. - -2005-04-17 Luc Teirlinck - - * frames.texi (XTerm Mouse): Xterm Mouse mode is no longer enabled - by default in terminals compatible with xterm. Mention that - xterm-mouse-mode is a minor mode and put in pxref to Minor Modes - node. - -2005-04-12 Luc Teirlinck - - * frames.texi (XTerm Mouse): Xterm Mouse mode is now enabled by default. - -2005-04-12 Jan Djärv - - * xresources.texi (Table of Resources): Add cursorBlink. - -2005-04-11 Luc Teirlinck - - * rmail.texi (Rmail Summary Edit): Explain numeric arguments to - `d', `C-d' and `u'. - -2005-04-11 Richard M. Stallman - - * cmdargs.texi (Initial Options): -Q is now --quick, and does less. - (Misc X): Add -D, --basic-display. - - * maintaining.texi (Change Log): Correct the description of - the example. - - * major.texi (Choosing Modes): Document magic-mode-alist. - -2005-04-10 Luc Teirlinck - - * rmail.texi (Rmail Basics): Clarify description of `q' and `b'. - (Rmail Deletion): `C-d' in RMAIL buffer does not accept a numeric arg. - (Rmail Inbox): Give full name of `rmail-primary-inbox-list'. - (Rmail Output): Clarify which statements apply to `o', `C-o' and - `w', respectively. - (Rmail Labels): Mention `l'. - (Rmail Attributes): Correct pxref. Mention `stored' attribute. - (Rmail Summary Edit): Describe `j' and RET. - -2005-04-10 Jan Djärv - - * xresources.texi (Lucid Resources): Add fontSet resource. - -2005-04-09 Luc Teirlinck - - * display.texi (Useless Whitespace): `indicate-unused-lines' is - now called `indicate-empty-lines'. - -2005-04-06 Kim F. Storm - - * cmdargs.texi (Initial Options): Add --bare-bones alias for -Q. - -2005-04-04 Luc Teirlinck - - * dired.texi (Dired Visiting): `dired-view-command-alist' has been - deleted. - (Marks vs Flags): Add some convenient key bindings. - (Hiding Subdirectories): Delete redundant and inaccurate sentence. - (Misc Dired Features): Correct and expand description of `w' command. - - * frames.texi (XTerm Mouse): Delete apparently false info. - The GNU/Linux console currently does not appear to support - `xterm-mouse-mode'. - -2005-04-03 Glenn Morris - - * calendar.texi (Diary): Mention shell utility `calendar'. - -2005-04-01 Richard M. Stallman - - * cmdargs.texi (Misc X): Explain horizontal scroll bars don't exist. - -2005-04-01 Lute Kamstra - - * maintaining.texi (Change Log): add-change-log-entry uses - add-log-mailing-address. - -2005-03-31 Luc Teirlinck - - * files.texi (Reverting): Move `auto-revert-check-vc-info' to - `VC Mode Line' and put in an xref to that node. - (VC Mode Line): Move `auto-revert-check-vc-info' here and clarify - its description. - -2005-03-31 Paul Eggert - - * calendar.texi (Calendar Systems): Say that the Persian calendar - implemented here is the arithmetical one championed by Birashk. - -2005-03-30 Glenn Morris - - * programs.texi (Fortran Motion): Fix previous change. - -2005-03-29 Richard M. Stallman - - * mule.texi (Single-Byte Character Support): Reinstall the C-x 8 info. - -2005-03-29 Chong Yidong - - * text.texi (Refill): Refer to Long Lines Mode. - (Longlines): New node. - (Auto Fill): Don't index "word wrap" here. - (Filling): Add Longlines to menu. - -2005-03-29 Richard M. Stallman - - * xresources.texi: Minor fixes. - - * misc.texi (Emacs Server): Fix Texinfo usage. - - * emacs.texi (Top): Don't use a real section heading for - "Detailed Node Listing". Fake it instead. - - * basic.texi (Position Info): Minor cleanup. - - * mule.texi (Input Methods): Minor cleanup. - -2005-03-29 Glenn Morris - - * programs.texi (ForIndent Vars): `fortran-if-indent' does other - constructs as well. - (Fortran Motion): Add fortran-end-of-block, fortran-beginning-of-block. - -2005-03-29 Kenichi Handa - - * mule.texi (Input Methods): Refer to the command C-u C-x =. - - * basic.texi (Position Info): Update the description about the - command C-u C-x =. - -2005-03-28 Richard M. Stallman - - * emacs.texi (Top): Use @section for the detailed node listing. - - * calendar.texi: Minor fixes to previous change. - - * programs.texi (Fortran): Small fixes to previous changes. - - * emacs.texi (Top): Update list of subnodes of Dired. - Likewise for building.texi. - - * files.texi (File Conveniences): Delete Auto Image File mode. - -2005-03-28 Chong Yidong - - * building.texi (Flymake): New node. - - * custom.texi (Function Keys): Document kp- event types and - keypad-setup package. - - * dired.texi (Wdired): New node. - - * files.texi (File Conveniences): Reorder entries. - Explain how to turn on Auto-image-file mode. - Document Thumbs mode. - - * mule.texi (Specify Coding): Document recode-region and - recode-file-name. - - * programs.texi (Program Modes): Add Conf mode and DNS mode. - -2005-03-27 Luc Teirlinck - - * commands.texi (Keys): M-o is now a prefix key. - -2005-03-27 Glenn Morris - - * programs.texi: Reformat and update copyright years. - (Fortran): Update section. - -2005-03-26 Luc Teirlinck - - * files.texi: Several small changes in addition to: - (Visiting): Change xref for Dialog Boxes to ref. - (Version Headers): Replace references to obsolete var - `vc-header-alist' with `vc-BACKEND-header'. - (Customizing VC): Update value of `vc-handled-backends'. - -2005-03-26 Glenn Morris - - * emacs-xtra.texi (Advanced Calendar/Diary Usage): New section; - move here from Emacs Lisp Reference Manual. - * calendar.texi (Calendar/Diary, Diary Commands) - (Special Diary Entries, Importing Diary): Change some xrefs to - point to emacs-xtra rather than elisp. - - * emacs-xtra.texi (Calendar Customizing): - Move view-diary-entries-initially, view-calendar-holidays-initially, - mark-diary-entries-in-calendar, mark-holidays-in-calendar to main - Emacs Manual. - (Appt Customizing): Merge entire section into main Emacs Manual. - * calendar.texi (Holidays): Move view-calendar-holidays-initially, - mark-holidays-in-calendar here from emacs-xtra. - (Displaying the Diary): Move view-diary-entries-initially, - mark-diary-entries-in-calendar here from emacs-xtra. - (Appointments): Move appt-display-mode-line, - appt-display-duration, appt-disp-window-function, - appt-delete-window-function here from emacs-xtra. - - * calendar.texi: Update and reformat copyright. - Change all @xrefs to the non-printing emacs-xtra to @inforefs. - (Calendar/Diary): Menu now only on Mouse-3, not C-Mouse-3. - (Diary): Refer to `diary-file' rather than ~/diary. - (Diary Commands): Rename node to "Displaying the Diary". - * emacs.texi (Top): Rename "Diary Commands" section. - * misc.texi (Hardcopy): Rename "Diary Commands" xref. - -2005-03-26 Eli Zaretskii - - * misc.texi (Emacs Server): Fix the command for setting - server-name. Add an xref to Invoking emacsclient. - - * help.texi (Help Summary): Clarify when "C-h ." will do something - nontrivial. - (Apropos): Add cindex entry for apropos-sort-by-scores. - - * display.texi (Text Display): Add index entries for how no-break - characters are displayed. - -2005-03-26 Eli Zaretskii - - * files.texi (Visiting): Fix cross-references introduced with the - last change. - - * xresources.texi (GTK resources): Fix last change. - -2005-03-25 Chong Yidong - - * xresources.texi (X Resources): GTK options documented too. - (Resources): Clarify meaning of program name. - (Table of Resources): Add visualClass. - (GTK resources): Rewrite. - (GTK widget names, GTK Names in Emacs, GTK styles): Cleanups. - - * display.texi (Text Display): Mention non-breaking spaces. - - * files.texi (Reverting): Document auto-revert-check-vc-info. - - * frames.texi (Mouse Commands): Document - x-mouse-click-focus-ignore-position and mouse-drag-copy-region. - - * help.texi (Help Summary): Add `C-h .'. - (Apropos): Apropos accepts a list of search terms. - Document apropos-sort-by-scores. - (Help Echo): Document display-local-help. - - * misc.texi (Emacs Server): Document server-name. - (Invoking emacsclient): Document -s option for server names. - - * text.texi (Outline Visibility): Introduce "current heading - line" (commands can be called with point on a body line). - Re-order table to follow the sequence of discussion. - hide-body won't hide lines before first header line. - (TeX Mode): Add DocTeX mode. - -2005-03-24 Richard M. Stallman - - * mule.texi (Single-Byte Character Support): Delete mention - of iso-acc.el and iso-transl.el. - -2005-03-23 Lute Kamstra - - * search.texi (Non-ASCII Isearch): Rename from Non-Ascii Isearch. - -2005-03-23 Richard M. Stallman - - * search.texi: Delete explicit node pointers. - (Incremental Search): New menu. - (Basic Isearch, Repeat Isearch, Error in Isearch) - (Non-Ascii Isearch, Isearch Yank, Highlight Isearch, Isearch Scroll) - (Slow Isearch): New subnodes. - (Configuring Scrolling): Node deleted. - (Search Case): Doc default-case-fold-search. - (Regexp Replace): Move replace-regexp doc here. - - * rmail.texi (Movemail): Put commas inside closequotes. - - * picture.texi (Insert in Picture): Document C-c arrow combos. - (Basic Picture): Clarify erasure. - - * display.texi (Font Lock): Put commas inside closequotes. - - * cmdargs.texi (General Variables): Put commas inside closequotes. - -2005-03-23 Nick Roberts - - * building.texi (Stack Buffer): Mention reverse contrast for - *selected* frame (might not be current frame). - -2005-03-21 Richard M. Stallman - - * building.texi (Starting GUD): Add bashdb. - -2005-03-20 Chong Yidong - - * basic.texi (Moving Point): Add M-g M-g binding. - (Undo): Document undo-only. - (Position Info): Document M-g M-g and C-u M-g M-g. - - * building.texi (Building): Put Grep Searching after Compilation - Shell. - (Compilation Mode): Document M-n, M-p, M-}, M-{, and C-c C-f bindings. - Document next-error-highlight. - (Grep Searching): Document grep-highlight-matches. - (Lisp Eval): Typing C-x C-e twice prints integers specially. - - * calendar.texi (Importing Diary): Rename node from iCalendar. - Document diary-from-outlook. - - * dired.texi (Misc Dired Features): Rename node from Misc Dired - Commands. - Mention effect of X drag and drop on Dired buffers. - - * files.texi (Visiting): Document large-file-warning-threshold. - Move paragraph on file-selection dialog. - Mention visiting files using X drag and drop. - (Reverting): Mention using Auto-Revert mode to tail files. - Document auto-revert-tail-mode. - (Version Systems): Minor correction. - (Comparing Files): Diff-mode is no longer based on Compilation - mode. - Document compare-ignore-whitespace. - (Misc File Ops): Explain passing a directory to rename-file. - Likewise for copy-file and make-symbolic-link. - - * frames.texi (Wheeled Mice): Mouse wheel support on by default. - Document mouse-wheel-progressive speed. - - * help.texi (Misc Help): Document numeric argument for C-h i. - Correctly explain the effect of just C-u as argument. - - * killing.texi (Deletion): Document numeric argument for - just-one-space. - - * mini.texi (Completion): Completion acts on text before point. - - * misc.texi (Saving Emacs Sessions): Document desktop-restore-eager. - (Emulation): CUA mode replaces pc-bindings-mode, - pc-selection-mode, and s-region. - - * mule.texi (Input Methods): Leim is now built-in. - (Select Input Method): Document quail-show-key. - (Specify Coding): Document revert-buffer-with-coding-system. - - * programs.texi (Fortran Motion): Document f90-next-statement, - f90-previous-statement, f90-next-block, f90-previous-block, - f90-end-of-block, and f90-beginning-of-block. - - * text.texi (Format Faces): Replace old M-g key prefix with M-o. - - * emacs.texi (Acknowledgments): Updated. - - * anti.texi: Total rewrite. - -2005-03-19 Chong Yidong - - * ack.texi (Acknowledgments): Update. - -2005-03-19 Eli Zaretskii - - * anti.texi (Antinews): Refer to Emacs 21.4, not 21.3. - Update copyright years. - -2005-03-14 Nick Roberts - - * building.texi (Commands of GUD): Move paragraph on setting - breakpoints with mouse to the GDB Graphical Interface node. - -2005-03-07 Richard M. Stallman - - * misc.texi (Single Shell, Shell Options): Fix previous change. - - * building.texi (Debugger Operation): Update GUD tooltip enable info. - -2005-03-06 Richard M. Stallman - - * building.texi (Starting GUD): Don't explain text vs graphical - GDB here. Just mention it and xref. - Delete "just one debugger process". - (Debugger Operation): Move GUD tooltip info here. - (GUD Tooltips): Node deleted. - (GDB Graphical Interface): Explain the two GDB modes here. - - * sending.texi (Sending Mail): Minor cleanup. - (Mail Aliases): Explain quoting conventions. - Update key rebinding example. - (Header Editing): C-M-i is like M-TAB. - (Mail Mode Misc): mail-attach-file does not do MIME. - - * rmail.texi (Rmail Inbox): Move text from Remote Mailboxes - that really belongs here. - (Remote Mailboxes): Text moved to Rmail Inbox. - (Rmail Display): Mention Mouse-1. - (Movemail): Clarify two movemail versions. - Clarify rmail-movemail-program. - - * misc.texi (Single Shell): Replace uudecode example with gpg example. - Document async shell commands. - (Shell History): Clarify. - (Shell Ring): Mention C-UP an C-DOWN. - (Shell Options): Add comint-prompt-read-only. - (Invoking emacsclient): Set EDITOR to run Emacs. - (Sorting): No need to explain what region is. - (Saving Emacs Sessions): Fix typo. - (Recursive Edit): Fix punctuation. - (Emulation): Don't mention "PC bindings" which are standard. - (Hyperlinking): Explain Mouse-1 convention here. - (Find Func): Node deleted. - - * help.texi (Name Help): Xref to Hyperlinking. - - * glossary.texi (Glossary): - Rename "Balance Parentheses" to "Balancing...". - Add "Byte Compilation". Correct "Copyleft". - New xref in "Customization". - Clarify "Current Line", "Echoing", "Fringe", "Frame", "Speedbar". - Add "Graphical Terminal" "Keybinding", "Margin", "Window System". - Rename "Registers" to "Register". - Replace "Selecting" with "Selected Frame", - "Selected Window", and "Selecting a Buffer". - - * files.texi (Types of Log File): Explain how projects' - methods can vary. - - * display.texi (Faces): Delete "Emacs 21". - - * custom.texi (Changing a Variable): C-M-i like M-TAB. - * fixit.texi (Spelling): C-M-i like M-TAB. - * mini.texi (Completion Options): C-M-i like M-TAB. - * programs.texi (Symbol Completion): C-M-i like M-TAB. - * text.texi (Text Mode): C-M-i like M-TAB. - - * commands.texi (Keys): Mention F1 and F2 in list of prefixes. - - * calendar.texi (Specified Dates): Mention `g w'. - (Appointments): appt-activate toggles with no arg. - -2005-03-05 Juri Linkov - - * cmdargs.texi (Emacs Invocation): Add cindex - "invocation (command line arguments)". - (Misc X): Add -nbc, --no-blinking-cursor. - -2005-03-04 Ulf Jasper - - * calendar.texi (iCalendar): No need to require it now. - -2005-03-03 Nick Roberts - - * trouble.texi (Contributing): Mention Savannah. Direct users to - emacs-devel. - -2005-03-01 Glenn Morris - - * calendar.texi (Adding to Diary): Mention redrawing of calendar - window. - -2005-02-27 Richard M. Stallman - - * building.texi (Compilation): Update mode line status info. - -2005-02-27 Matt Hodges - - * calendar.texi (General Calendar): Document binding of - scroll-other-window-down. - (Mayan Calendar): Fix earliest date. - (Time Intervals): Document timeclock-change. - Fix timeclock-ask-before-exiting documentation. - -2005-02-26 Kim F. Storm - - * frames.texi (Mouse References): - Add mouse-1-click-in-non-selected-windows. - -2005-02-25 Richard M. Stallman - - * screen.texi (Screen): Explain better about cursors and mode lines; - don't presuppose text terminals. - (Point): Don't assume just one cursor. - Clarify explanation of cursors. - (Echo Area, Menu Bar): Cleanups. - - * mini.texi (Minibuffer): Prompts are highlighted. - (Minibuffer Edit): Newline = C-j only on text terminals. - Clarify resize-mini-windows values. - Mention M-PAGEUP and M-PAGEDOWN. - (Completion Commands): Mouse-1 like Mouse-2. - (Minibuffer History): Explain history commands better. - (Repetition): Add xref to Incremental Search. - - * mark.texi (Setting Mark): Clarify info about displaying mark. - Clarify explanation of C-@ and C-SPC. - (Transient Mark): Mention Delete Selection mode. - (Marking Objects): Clean up text about extending the region. - - * m-x.texi (M-x): One C-g doesn't always go to top level. - No delay before suggest-key-bindings output. - - * fixit.texi (Fixit): Mention C-/ for undo. - (Spelling): Mention ESC TAB like M-TAB. - Replacement words with r and R are rechecked. - Say where C-g leaves point. Mention ? as input. - -2005-02-23 Lute Kamstra - - * cmdargs.texi (Initial Options): Add cross reference. - -2005-02-16 Luc Teirlinck - - * emacs.texi (Top): Update menu for splitting of node in - msdog.texi. - * frames.texi (Frames): Update xref for splitting of node in - msdog.texi. - * trouble.texi (Quitting): Ditto. - -2005-02-16 Richard M. Stallman - - * windows.texi (Split Window): Simplify line truncation info - and xref to Display Custom. - - * trouble.texi (Quitting): Emergency escape only for text terminal. - (Screen Garbled): C-l for ungarbling is only for text terminal. - - * text.texi (Text Mode): ESC TAB alternative for M-TAB. - - * sending.texi (Header Editing): ESC TAB alternative for M-TAB. - - * programs.texi (Program Modes): Mention Python mode. - (Moving by Defuns): Repeating C-M-h extends region. - (Basic Indent): Clarify. - (Custom C Indent): Clarify. - (Expressions): Repeating C-M-@ extends region. - (Info Lookup): Clarify for C-h S. - (Symbol Completion): ESC TAB alternative for M-TAB. - (Electric C): Clarify. - - * emacs.texi (Top): Update display.texi and frames.texi submenu data. - - * msdog.texi (MS-DOS Keyboard, MS-DOS Mouse): Split from - MS-DOS Input node. - (MS-DOS Keyboard): Start with explaining DEL and BREAK. - (MS-DOS and MULE): Clarify. - (MS-DOS Processes, Windows Processes): Fix typos. - - * major.texi (Choosing Modes): Clarify. - - * kmacro.texi (Basic Keyboard Macro): Doc F3, F4. - (Keyboard Macro Step-Edit): Clarify. - - * indent.texi (Indentation): Clarifications. - - * help.texi (Help): Correct error about C-h in query-replace. - Clarify apropos vs C-h a. Fix how to search in FAQ. - (Key Help): Describe C-h w here. - (Name Help): Minor cleanup. C-h w moved to Key Help. - Clarify the "object" joke. - (Apropos): Clarify. Mouse-1 like Mouse-2. - (Help Mode): Mouse-1 like Mouse-2. - - * fixit.texi (Spelling): Mention ESC TAB as alt. for M-TAB. - - * display.texi (Display): Reorder menu. - (Faces): Cleanup. - (Font Lock): Cleanup. Mention Options menu. - Delete obsolete text. - (Scrolling): For C-l, don't presume text terminal. - (Horizontal Scrolling): Simplify intro. - (Follow Mode): Clarify. - (Cursor Display): Move before Display Custom. - (Display Custom): Explain no-redraw-on-reenter is for text terminals. - Doc default-tab-width. Doc line truncation more thoroughly. - - * dired.texi (Dired Enter): C-x C-f can run Dired. - (Dired Visiting): Comment out `a' command. - Mouse-1 is like Mouse-2. - (Shell Commands in Dired): ? can be used more than once. - - * basic.texi (Continuation Lines): Simplify description of truncation, - and refer to Display Custom for the rest of it. - -2005-02-06 Lute Kamstra - - * basic.texi (Undo): Fix typo. - - * cmdargs.texi (Emacs Invocation): Fix typo. - - * custom.texi (Init Examples): Fix typo. - - * abbrevs.texi (Expanding Abbrevs): Fix typo. - -2005-02-06 Richard M. Stallman - - * regs.texi (Registers): Registers can hold numbers, too. - - * killing.texi (Other Kill Commands): Cleanup. - Delete redundant explanation of kill in read-only buffer. - (Yanking): Mention term "copying". - (Accumulating Text): Fix typo. - - * entering.texi (Entering Emacs): Update rationale at start. - (Exiting): Treat iconifying on a par with suspension. - - * custom.texi (Minor Modes): Fix typo. - (Easy Customization): Fix menu style. - (Variables): Add xref. - (Examining): Setting for future sessions works through .emacs. - (Keymaps): "Text terminals", not "Many". - (Init Rebinding): Explain \C-. Show example of \M-. - Fix minor wording errors. - (Function Keys): Explain vector syntax just once. - (Named ASCII Chars): Clarify history of TAB/C-i connection. - (Init File): Mention .emacs.d directory. - (Init Examples): Add xref. - (Find Init): Mention .emacs.d directory. - - * cmdargs.texi (Emacs Invocation): +LINENUM is also an option. - (Action Arguments): Explain which kinds of -l args are found how. - (Initial Options): --batch does not inhibit site-start. - Add xrefs. - (Command Example): Use --batch, not -batch. - - * basic.texi (Inserting Text): Cleanup wording. - (Moving Point): Doc PRIOR, PAGEUP, NEXT, PAGEDOWN more systematically. - C-n is not error at end of buffer. - (Undo): Doc C-/ like C-_. Add xrefs. - (Arguments): META key may be labeled ALT. - Peculiar arg meanings are explained in doc strings. - - * abbrevs.texi (Expanding Abbrevs): Clarify. - -2005-02-05 Eli Zaretskii - - * frames.texi (Frame Parameters): Add an xref to the description - of list-colors-display. Add a pointer to the X docs about colors. - - * cmdargs.texi (Colors): Mention 16-, 88- and 256-color modes. - Improve docs of list-colors-display. - -2005-02-03 Lute Kamstra - - * frames.texi (Frames, Drag and Drop): Fix typos. - -2005-02-03 Richard M. Stallman - - * windows.texi (Basic Window): Mention color-change in mode line. - (Change Window): Explain dragging vertical boundaries. - - * text.texi (Sentences): Clarify. - (Paragraphs): Explain M-a and blank lines. - (Outline Mode): Clarify text and menu. - (Hard and Soft Newlines): Mention use-hard-newlines. - - * frames.texi (Frames): Delete unnecessary mention of Windows. - (Mouse Commands): Likewise. Mention xterm mouse support. - (Clipboard): Clarify. - (Mouse References): Mention use of Mouse-1 for following links. - (Menu Mouse Clicks): Clarify. - (Mode Line Mouse): Clarify. - (Drag and Drop): Rewrite. - - * fixit.texi (Spelling): Fix typo. - - * files.texi (File Names): Clarify. - (Visiting): Update conditions for use of file dialog. Clarify. - (Saving): Doc d as answer in save-some-buffers. - (Remote Files): Clean up the text. - - * dired.texi (Misc Dired Commands): Delete dired-marked-files. - - * buffers.texi (Select Buffer): Doc next-buffer and prev-buffer. - (List Buffers): Clarify. - (Several Buffers): Doc T command. - (Buffer Convenience): Clarify menu. - - * basic.texi (Undo): Clarify last change. - -2005-02-02 Matt Hodges - - * fixit.texi (Spelling): Fix typo. - -2005-02-01 Luc Teirlinck - - * basic.texi (Undo): Update description of `undo-outer-limit'. - -2005-02-01 Nick Roberts - - * building.texi: Update documentation relating to GDB Graphical - Interface. - -2005-01-30 Luc Teirlinck - - * custom.texi (Easy Customization): Adapt menu to node name change. - -2005-01-30 Richard M. Stallman - - * custom.texi (Easy Customization): Defn of "User Option" now - includes faces. Don't say just "option" when talking about variables. - Do say just "options" to mean "anything customizable". - (Specific Customization): Describe `customize-variable', - not `customize-option'. - - * glossary.texi (Glossary) : Add xref. - : Change definition--include faces. Change xref. - - * picture.texi (Picture): Mention artist.el. - - * sending.texi, screen.texi, programs.texi, misc.texi: - * mini.texi, major.texi, maintaining.texi, macos.texi: - * help.texi, frames.texi, files.texi: - Don't say just "option" when talking about variables. - - * display.texi, mule.texi: Don't say just "option" when talking - about variables. Other minor cleanups. - -2005-01-26 Lute Kamstra - - * cmdargs.texi (Initial Options): Add a cross reference to `Init - File'. Mention the `-Q' option at the `--no-site-file' option. - -2005-01-22 David Kastrup - - * building.texi (Grep Searching): Mention alias `find-grep' for - `grep-find'. - -2005-01-20 Richard M. Stallman - - * calendar.texi (Time Intervals): Delete special stuff for MS-DOS. - -2005-01-15 Sergey Poznyakoff - - * rmail.texi (Movemail): Explain differences - between standard and mailutils versions of movemail. - Describe command line and configuration options introduced - with the latter. - Explain the notion of mailbox URL, provide examples and - cross-references to mailutils documentation. - Describe various methods of specifying mailbox names, - user names and user passwords for rmail. - (Remote Mailboxes): New section. - Describe how movemail handles remote mailboxes. Describe configuration - options used to control its behavior. - (Other Mailbox Formats): Explain handling of various mailbox - formats. - -2005-01-13 Richard M. Stallman - - * commands.texi (Commands): Clarification. - -2005-01-11 Richard M. Stallman - - * programs.texi (Multi-line Indent): Fix previous change. - (Fortran Autofill): Simplify description of fortran-auto-fill-mode. - -2005-01-08 Richard M. Stallman - - * display.texi (Faces): isearch-lazy-highlight-face renamed to - lazy-highlight. - - * search.texi (Query Replace): Mention faces query-replace - and lazy-highlight. - (Incremental Search): Update isearch highlighting info. - -2005-01-04 Richard M. Stallman - - * custom.texi (Saving Customizations): Minor improvement. - -2005-01-03 Luc Teirlinck - - * custom.texi (Saving Customizations): Emacs no longer loads - `custom-file' after .emacs. No longer mention customizing through - Custom. - -2005-01-01 Andreas Schwab - - * killing.texi (Graphical Kill): Move up under node Killing, - change @section to @subsection. - -2005-01-01 Richard M. Stallman - - * custom.texi (Face Customization): Mention hex color specs. - - * emacs.texi (Top): Update Killing submenu. - - * killing.texi (Killing): Reorganize section. - No more TeX-only text; put the node command at start of chapter. - But the first section heading is used only in TeX. - Rewrite the text to read better in this mode. - (Graphical Kill): New subnode gets some of the text that - used to be in the first section. - -2004-12-31 Richard M. Stallman - - * dired.texi (Shell Commands in Dired): Delete the ? example. - - * display.texi (Scrolling): Correct scroll-preserve-screen-position. - - * files.texi (Saving): Describe new require-final-newline features - and mode-require-final-newline. - -2004-12-29 Richard M. Stallman - - * custom.texi (File Variables): Clarify previous change. - -2004-12-27 Jan Djärv - - * frames.texi (Dialog Boxes): Mention Gtk+ 2.6 also, as that version is - out now. - -2004-12-27 Richard M. Stallman - - * Makefile.in (MAKEINFO): Specify --force. - - * basic.texi (Moving Point): C-e now runs move-end-of-line. - (Undo): Doc undo-outer-limit. - -2004-12-15 Juri Linkov - - * mark.texi (Transient Mark, Mark Ring): M-< and other - movement commands don't set mark in Transient Mark mode - if mark is active. - -2004-12-12 Juri Linkov - - * misc.texi (FFAP): Add C-x C-r, C-x C-v, C-x C-d, - C-x 4 r, C-x 4 d, C-x 5 r, C-x 5 d. - - * dired.texi (Dired Navigation): Add @r{(Dired)} to M-g. - (Misc Dired Commands): Add @r{(Dired)} to w. - -2004-12-12 Juri Linkov - - * mark.texi (Marking Objects): Marking commands also extend the - region when mark is active in Transient Mark mode. - -2004-12-08 Luc Teirlinck - - * custom.texi (Saving Customizations): Emacs only loads the custom - file automatically after the init file in version 22.1 or later. - Adapt text and examples to this fact. - -2004-12-07 Luc Teirlinck - - * frames.texi (Scroll Bars): The option `scroll-bar-mode' has to - be set through Custom. Otherwise, it has no effect. - -2004-12-05 Richard M. Stallman - - * cmdargs.texi, doclicense.texi, xresources.texi, emacs.texi: - * entering.texi: Rename Command Line to Emacs Invocation. - - * misc.texi (Term Mode): Correctly describe C-c. - - * custom.texi (Easy Customization): Move up to section level, - before Variables. Avoid using the term "variable"; say "option". - New initial explanation. - (Variables): In initial explanation, connect "variable" to the - already-explained "user option". - - * emacs.texi (Top): Fix ref to Command Line. - Move reference to Easy Customization. - - * xresources.texi (X Resources): Fix From link. - - * doclicense.texi (GNU Free Documentation License): Fix To link. - - * entering.texi (Entering Emacs): Fix xref, now to Command Line. - - * cmdargs.texi (Command Line): Node renamed from Command Arguments. - -2004-12-03 Richard M. Stallman - - * cmdargs.texi (Initial Options): Clarify batch mode i/o. - -2004-12-01 Luc Teirlinck - - * kmacro.texi: Several small changes in addition to the following. - (Keyboard Macro Ring): Describe behavior of `C-x C-k C-k' when - defining a keyboard macro. - Mention `kmacro-ring-max'. - (Keyboard Macro Counter): Clarify description of - `kmacro-insert-counter', `kmacro-set-counter', - `kmacro-add-counter' and `kmacro-set-format'. - -2004-11-29 Reiner Steib - - * custom.texi (File Variables): Add `unibyte' and make it more - clear that `unibyte' and `coding' are special. Suggested by Simon - Krahnke . - - * mule.texi (Enabling Multibyte): Refer to File Variables. - Suggested by Simon Krahnke . - -2004-11-26 Jan Djärv - - * frames.texi (Dialog Boxes): Rename use-old-gtk-file-dialog to - x-use-old-gtk-file-dialog. - -2004-11-20 Richard M. Stallman - - * text.texi (Fill Prefix): M-q doesn't apply fill prefix to first line. - -2004-11-09 Lars Brinkhoff - - * building.texi (Lisp Eval): Delete hyphen in section name. - -2004-11-19 Thien-Thi Nguyen - - * files.texi (Old Versions): - No longer document annotation as "CVS only". - -2004-11-10 Andre Spiegel - - * files.texi (Version Control): Rewrite the introduction about - version systems, mentioning the new ones that we support. - Thanks to Alex Ott, Karl Fogel, Stefan Monnier, and David Kastrup for - suggestions. - -2004-11-03 Jan Djärv - - * frames.texi (Dialog Boxes): Replace non-nil with non-@code{nil}. - -2004-11-02 Jan Djärv - - * frames.texi (Dialog Boxes): Document use-old-gtk-file-dialog. - -2004-10-23 Eli Zaretskii - - * text.texi (Text Based Tables, Table Definition) - (Table Creation, Table Recognition, Cell Commands) - (Cell Justification, Row Commands, Column Commands) - (Fixed Width Mode, Table Conversion, Measuring Tables) - (Table Misc): New nodes, documenting the Table Mode. - -2004-10-19 Jason Rumney - - * makefile.w32-in (info): Change order of arguments to makeinfo. - -2004-10-19 Ulf Jasper - - * calendar.texi (iCalendar): Update for package changes. - -2004-10-09 Luc Teirlinck - - * files.texi (Misc File Ops): View mode is a minor mode. - -2004-10-08 Glenn Morris - - * calendar.texi (iCalendar): Style changes. - -2004-10-07 Luc Teirlinck - - * search.texi (Regexps): The regexp described in the example is no - longer stored in the variable `sentence-end'. - -2004-10-06 Nick Roberts - - * building.texi (Starting GUD): Note that multiple debugging - sessions requires `gdb --fullname'. - -2004-10-05 Ulf Jasper - - * calendar.texi (iCalendar): New section for a new package. - -2004-10-05 Luc Teirlinck - - * text.texi: Various small changes in addition to the following. - (Text): Replace xref for autotype with inforef. - (Sentences): Explain nil value for `sentence-end'. - (Paragraphs): Update default values for `paragraph-start' and - `paragraph-separate'. - (Text Mode): Correct description of Text mode's effect on the - syntax table. - (Outline Visibility): `hide-other' does not hide top level headings. - `selective-display-ellipses' no longer has an effect on Outline mode. - (TeX Misc): Add missing @cindex. - Replace xref for RefTeX with inforef. - (Requesting Formatted Text): The variable - `enriched-fill-after-visiting' no longer exists. - (Editing Format Info): Update names of menu items and commands. - (Format Faces): Mention special effect of specifying the default face. - Describe inheritance of text properties. - Correct description of `fixed' face. - (Format Indentation): Correct description of effect of setting - margins. Mention `set-left-margin' and `set-right-margin'. - (Format Justification): Update names of menu items. - `set-justification-full' is now bound to `M-j b'. - Mention that `default-justification' is a per buffer variable. - (Format Properties): Update name of menu item. - (Forcing Enriched Mode): `format-decode-buffer' automatically - turns on Enriched mode if the buffer is in text/enriched format. - -2004-10-05 Emilio C. Lopes - - * calendar.texi (From Other Calendar): Add calendar-goto-iso-week. - -2004-09-28 Kim F. Storm - - * display.texi (Display Custom) : - Align with new functionality. - -2004-09-22 Luc Teirlinck - - * display.texi (Display Custom): Remove stray `@end defvar'. - -2004-09-23 Kim F. Storm - - * display.texi (Display Custom): Add `overflow-newline-into-fringe', - `indicate-buffer-boundaries' and `default-indicate-buffer-boundaries'. - -2004-09-20 Richard M. Stallman - - * custom.texi (Hooks): Explain using setq to clear out a hook. - (File Variables): Explain multiline string constants. - (Non-ASCII Rebinding): Explain when you need to update - non-ASCII char codes in .emacs. - - * building.texi (Compilation): Explain how to make a silent - subprocess that won't be terminated. Explain compilation-environment. - -2004-09-13 Kim F. Storm - - * mini.texi (Repetition): Rename isearch-resume-enabled to - isearch-resume-in-command-history and change default to disabled. - -2004-09-09 Kim F. Storm - - * kmacro.texi (Save Keyboard Macro): Replace `name-last-kbd-macro' - with new `kmacro-name-last-macro'. - -2004-09-08 Juri Linkov - - * mini.texi (Minibuffer History): Add `history-delete-duplicates'. - -2004-09-03 Juri Linkov - - * search.texi (Incremental Search): Update wording for M-%. - -2004-09-02 Luc Teirlinck - - * killing.texi (Killing): Correct description of kill commands in - read-only buffer. - -2004-09-02 Teodor Zlatanov - - * building.texi (Compilation Mode): Add a paragraph about rules - for finding the compilation buffer for `next-error'. - - * search.texi (Other Repeating Search): Mention that Occur mode - supports the next-error functionality. - -2004-09-02 Juri Linkov - - * search.texi (Regexp Replace): Add missing backslash to \footnote. - -2004-08-31 Luc Teirlinck - - * kmacro.texi (Basic Keyboard Macro): - `apply-macro-to-region-lines' now operates on all lines that begin - in the region, rather than on all complete lines in the region. - -2004-08-31 Jan Djärv - - * frames.texi (Drag and drop): Add documentation about - x-dnd-test-function and x-dnd-known-types. - -2004-08-30 Luc Teirlinck - - * indent.texi: Various minor changes in addition to: - (Indentation Commands): Correct description of `indent-relative'. - (Tab Stops): is no longer bound to `tab-to-tab-stop' in Text - mode. The *Tab Stops* buffer uses Overwrite Mode. - (Just Spaces): `tabify' converts sequences of at least two spaces - to tabs. - -2004-08-27 Luc Teirlinck - - * frames.texi (Secondary Selection): Setting the secondary - selection with M-Drag-Mouse-1 does not alter the kill ring, - setting it with M-Mouse-1 and M-Mouse-3 does. - (Mode Line Mouse): C-Mouse-2 on scroll bar now also works for - toolkit scroll bars. - (Scroll Bars): Ditto. - - * windows.texi (Basic Window): When using a window system, the value - of point in a non-selected window is indicated by a hollow box. - (Split Window): Side by side windows are separated by a scroll bar, - if scroll bars are used. - C-Mouse-2 on scroll bar now also works for toolkit scroll bars. - (Change Window): Correct Mouse-2 vs Mouse-3 mess-up. - (Window Convenience): Update bindings for `winner-undo' and - `winner-redo'. - - * ack.texi (Acknowledgments): Use `@unnumbered'. - * misc.texi: Adapt sectioning in Info to the node structure. - (Invoking emacsclient): Make "Invoking emacsclient" a subsection - of "Using Emacs as a Server". - * building.texi (Building): Interchange nodes (for correct numbering). - * programs.texi (Programs): Interchange nodes (for correct numbering). - * killing.texi, entering.texi, commands.texi: Adapt sectioning in - Info to the node structure. - * emacs.texi: Make "GNU GENERAL PUBLIC LICENSE" an appendix. - Rearrange order of nodes and sections such that both "GNU GENERAL - PUBLIC LICENSE" and "GNU Free Documentation License" appear at the - end, as appropriate for appendices. - (Acknowledgments): Put inside @iftex instead of @ifnotinfo. - Use `@unnumberedsec'. - * trouble.texi: Adapt sectioning in Info to the node structure. - Adapt node pointers to change in emacs.texi. - * cmdargs.texi, doclicense.texi: Adapt node pointers. - -2004-08-25 Kenichi Handa - - * custom.texi (Non-ASCII Rebinding): Fix and simplify the - description for unibyte mode. - -2004-08-23 Luc Teirlinck - - * display.texi (Font Lock): Correct invalid (for hardcopy) @xref. - - * search.texi (Regexps): Correct cryptic (in hardcopy) @ref. - (Configuring Scrolling): Correct invalid (for hardcopy) @xref. - (Regexp Replace): Standardize reference to hardcopy Elisp Manual - in @pxref. - -2004-08-22 Luc Teirlinck - - * kmacro.texi (Keyboard Macro Counter, Keyboard Macro Step-Edit): - Change section names. - -2004-08-21 Luc Teirlinck - - * kmacro.texi (Keyboard Macro Ring): Rename section. - Emacs treats the head of the macro ring as the `last keyboard macro'. - (Keyboard Macro Counter): Minor change. - (Save Keyboard Macro): Some clarifications. - (Edit Keyboard Macro): Rename section. - - * buffers.texi (Buffers): Maximum buffer size is now 256M on - 32-bit machines. - (Several Buffers): Clarify which buffer is selected if `2' is - pressed in the Buffer Menu. - Auto Revert mode can be used to update the Buffer Menu - automatically. - -2004-08-21 Eli Zaretskii - - * help.texi (Misc Help): Add an index entry for finding an Info - manual by its file name. - -2004-08-20 Luc Teirlinck - - * files.texi (Backup Deletion): Correct description of - `delete-old-versions'. - (Time Stamps): `time-stamp' needs to be added to `before-save-hook'. - (Auto Save Files): Recommend `auto-save-mode' to reenable - auto-saving, rather than the abbreviation `auto-save'. - -2004-08-17 Luc Teirlinck - - * emacs.texi (Top): Mention "cutting" and "pasting" as synonyms - for "killing" and "yanking" in main menu. - -2004-08-16 Richard M. Stallman - - * killing.texi (Yanking, Killing): Minor cleanups. - - * mark.texi (Momentary Mark): Minor cleanups. - -2004-08-15 Kenichi Handa - - * custom.texi (Non-ASCII Rebinding): - C-q always inserts the right code to pass to global-set-key. - -2004-08-13 Luc Teirlinck - - * regs.texi (RegNumbers): Mention `C-x r i' binding for - `insert-register', instead of `C-x r g' binding, for consistency. - -2004-08-12 Luc Teirlinck - - * fixit.texi (Spelling): Fix typo. - -2004-08-11 Luc Teirlinck - - * help.texi (Help): Fix Texinfo usage. - -2004-07-24 Richard M. Stallman - - * text.texi (Paragraphs): Update how paragraphs are separated - and the default for paragraph-separate. - - * search.texi (Regexp Replace): Further update text for new - replacement operators. - -2004-07-18 Luc Teirlinck - - * emacs-xtra.texi (Subdir switches): Dired does not remember the - `R' switch. - - * dired.texi (Dired Updating): `k' only deletes inserted - subdirectories from the Dired buffer if a prefix argument was given. - - * search.texi (Regexps): Delete redundant definition of `symbol' in - description of `\_>'. It already occurs in the description of `\_<'. - -2004-07-01 Juri Linkov - - * search.texi (Incremental Search): Add C-M-w, C-M-y, M-%, C-M-%, M-e. - (Regexp Search): Add M-r. - -2004-06-30 Luc Teirlinck - - * makefile.w32-in (EMACSSOURCES): Remove emacs-xtra. - -2004-06-29 Jesper Harder - - * search.texi, calendar.texi: Markup fixes. - -2004-06-25 Richard M. Stallman - - * search.texi (Regexp Replace): Rewrite description of \# \, and \?. - -2004-06-25 David Kastrup - - * search.texi (Regexp Replace): Some typo corrections and - rearrangement. - -2004-06-24 David Kastrup - - * search.texi (Unconditional Replace): Use replace-string instead - of query-replace in example. - (Regexp Replace): Add explanations for `\,', `\#' and `\?' - sequences. - (Query Replace): Correct explanation of `^' which does not use - the mark stack. - -2004-06-21 Nick Roberts - - * misc.texi (Shell History Copying): Document comint-insert-input. - (Shell Ring): Describe comint-dynamic-list-input-ring here. - -2004-06-20 Jesper Harder - - * msdog.texi (Text and Binary, MS-DOS Printing): Use m-dash. - * custom.texi (Customization): Do. - * anti.texi (Antinews): Do. - * abbrevs.texi (Defining Abbrevs): Do. - - * programs.texi (Info Lookup): Fix keybinding for - info-lookup-symbol. - -2004-06-16 Juanma Barranquero - - * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, EMACSSOURCES): - Add emacs-xtra. - ($(infodir)/emacs-xtra, emacs-xtra.dvi): New dependencies. - (clean): Add emacs-xtra and flymake. Remove redundancies. - -2004-06-15 Luc Teirlinck - - * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/emacs-xtra): - Add emacs-xtra. - * emacs-xtra.texi: New file. - -2004-06-14 Luc Teirlinck - - * dired.texi (Dired Enter): Mention conditions on `ls' switches. - (Dired and Find): Mention differences with ordinary Dired buffers. - -2004-06-13 Richard M. Stallman - - * custom.texi (Init Syntax): Explain about vars that do special - things when set with setq or with Custom. - (Init Examples): Add line-number-mode example. - -2004-06-12 Juri Linkov - - * dired.texi (Operating on Files): Add dired-do-touch. - -2004-06-10 Juri Linkov - - * building.texi (Lisp Eval): Add C-M-x on defface. - -2004-06-08 Luc Teirlinck - - * files.texi (Reverting): Auto-Revert mode and - Global Auto-Revert mode no longer revert remote files. - -2004-05-29 Richard M. Stallman - - * custom.texi (Init File): Two dashes start --no-site-file. - -2004-05-29 Alan Mackenzie - - * programs.texi: Update for CC Mode 5.30 and incidental amendments. - ("AWK"): Is consistently thus spelled throughout. - (AWK, Pike): Document as "C-like modes". - (@kbd{M-j}): Document as alternative to @kbd{C-M-j}. - (M-x man): Supersedes M-x manual-entry. - Add numerous index entries. Correct "ESC a/e" to "M-a/e". - - ("Comments in C"): Delete node; the info is in CC Mode manual. - (c-comment-only-line-offset): Remove description. - - (C-c ., C-c C-c): Describe new C Mode bindings. - - (C-u TAB, indent-code-rigidly, c-indent-exp, c-tab-always-indent) - (@dfn{Style}, c-default-style, comment-column, comment-padding) - (c-up-conditional, c-beginning-of-statement, c-end-of-statement): - Amend definitions. - - (c-beginning-of-defun, c-end-of-defun, c-context-line-break): - Describe functions. - - (c-comment-start-regexp, c-hanging-comment-ender-p) - (c-hanging-comment-starter-p): Remove obsolete definitions. - - * emacs.texi: Remove the menu entry "Comments in C". - -2004-05-27 Luc Teirlinck - - * dired.texi (Dired and Find): `find-ls-option' does not apply to - `M-x locate'. - -2004-05-16 Karl Berry - - * emacs.texi (ack.texi) [@ifnottex]: Change condition; with @ifinfo, - makeinfo --html fails. - * help.texi (Help Summary) [@ifnottex]: Likewise. - -2004-05-13 Nick Roberts - - * building.texi (GDB Graphical Interface): Update and describe - layout first. - -2004-05-04 Jason Rumney - - * makefile.w32-in: Revert last change. - -2004-05-03 Jason Rumney - - * makefile.w32-in (MULTI_INSTALL_INFO, ENVADD): Use forward slashes. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-04-18 Juri Linkov - - * fixit.texi (Spelling): Remove file extension from ispell xref. - -2004-04-15 Kim F. Storm - - * cmdargs.texi (Initial Options): Add -Q. - -2004-04-05 Kim F. Storm - - * custom.texi (File Variables): Add safe-local-eval-forms. - -2004-04-02 Luc Teirlinck - - * files.texi (Reverting): Correct description of revert-buffer's - handling of point. - -2004-03-22 Juri Linkov - - * emacs.texi (Top): Add `Misc X'. - - * trouble.texi: Fix help key bindings. - - * glossary.texi: Improve references. - - * help.texi: Sync keywords with finder.el. - - * mini.texi (Completion): Add description for menu items. - - * misc.texi (Browse-URL, FFAP): Add information about keywords. - - * sending.texi (Mail Methods): Fix xref to Message manual. - -2004-03-12 Richard M. Stallman - - * buffers.texi (Misc Buffer): Add index entry for rename-uniquely. - -2004-03-04 Richard M. Stallman - - * search.texi (Regexps): Explain that ^ and $ have their - special meanings only in certain contexts. - - * programs.texi (Expressions): Doc C-M-SPC as alias for C-M-@. - - * mule.texi (Specify Coding): Doc C-x RET F. - - * buffers.texi (Misc Buffer): Explain use of M-x rename-uniquely - for multiple compile and grep buffers. - (Indirect Buffers): Don't recommand clone-indirect-buffer - for multiple compile and grep buffers. - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (mostlyclean, clean, maintainer-clean): - Use $(DEL) instead of rm, and ignore exit code. - -2004-02-23 Nick Roberts - - * building.texi (Watch Expressions): Update. - -2004-02-21 Juri Linkov - - * cmdargs.texi (Action Arguments): Add alias --find-file. - Add --directory, --help, --version. Move text about command-line-args - to Command Arguments. - (Initial Options): Add @cindex for --script. Fix @cindex for -q. - Add --no-desktop. Add alias --no-multibyte, --no-unibyte. - (Window Size X): Join -g and --geometry. Add @cindex. - (Borders X): Fix @cindex for -ib. Add @cindex for -bw. - (Title X): Remove alias -title. - (Misc X): New node. - -2004-02-15 Jan Djärv - - * frames.texi (Drag and drop): Add Motif to list of supported - protocols. - -2004-02-03 Jan Djärv - - * frames.texi (Drag and drop): New section. - -2004-01-24 Richard M. Stallman - - * emacs.texi (Acknowledgments): Rename from Acknowledgements. - Include it only @ifnotinfo. Patch the preceding and following - node headers to point to each other. - -2004-01-11 Glenn Morris - - * calendar.texi (Appointments): Update section. - -2003-12-29 Kevin Ryde - - * programs.texi (C Modes): Fix the xref. - -2003-12-23 Nick Roberts - - * building.texi (Watch Expressions): Update. - (Commands of GUD): Include use of toolbar + breakpoints set from - fringe/margin. - -2003-12-03 Andre Spiegel - - * files.texi: Say how to disable VC. Suggested by Alan Mackenzie - . - -2003-11-29 Jan Djärv - - * frames.texi (Dialog Boxes): Add use-file-dialog. - -2003-11-22 Martin Stjernholm - - * ack.texi: Note that Alan Mackenzie contributed the AWK support - in CC Mode. - -2003-11-02 Jesper Harder (tiny change) - - * ack.texi, basic.texi, cmdargs.texi: - * commands.texi, custom.texi, display.texi: - * emacs.texi, files.texi: - * frames.texi, glossary.texi, killing.texi: - * macos.texi, mark.texi, misc.texi, msdog.texi: - * mule.texi, rmail.texi, search.texi: - * sending.texi, text.texi, trouble.texi: - Replace @sc{ascii} and ASCII with @acronym{ASCII}. - -2003-11-01 Alan Mackenzie - - * search.texi (Scrolling During Incremental Search): Document a - new scrolling facility in isearch mode. - -2003-10-22 Miles Bader - - * Makefile.in (info): Move before $(top_srcdir)/info. - -2003-10-22 Nick Roberts - - * building.texi (Watch Expressions): Update section on data display - to reflect code changes (GDB Graphical Interface). - -2003-10-13 Richard M. Stallman - - * xresources.texi (GTK resources): Clean up previous change. - -2003-10-12 Jan Djärv - - * xresources.texi (GTK resources): Add a note that some themes - disallow customizations. Add scroll theme example. - -2003-09-30 Richard M. Stallman - - * cmdargs.texi (General Variables): Remove MAILRC envvar. - - * misc.texi (Saving Emacs Sessions): Shorten the section, - collapsing back into one node. - -2003-09-30 Lars Hansen - - * misc.texi: Section "Saving Emacs Sessions" rewritten. - -2003-09-29 Jan Djärv - - * xresources.texi (GTK names in Emacs): Correct typo. - -2003-09-24 Luc Teirlinck - - * cmdargs.texi (Font X): Mention new default font. - More fully describe long font names, wildcard patterns and the - problems involved. (Result of discussion on emacs-devel.) - -2003-09-22 Luc Teirlinck - - * emacs.texi (Acknowledgements): Correct typo. - -2003-09-22 Richard M. Stallman - - * dired.texi (Misc Dired Commands): New node. - (Dired Navigation): Add dired-goto-file. - - * files.texi (File Aliases, Misc File Ops): Add @cindex entries. - - * emacs.texi (Acknowledgements): New node, split from Distribution. - - * cmdargs.texi (Action Arguments): -f reads interactive args. - -2003-09-08 Lute Kamstra - - * screen.texi (Mode Line): Say that POS comes before LINE. - Mention `size-indication-mode'. - * display.texi (Optional Mode Line): - Document `size-indication-mode'. - * basic.texi (Position Info): Mention `size-indication-mode'. - -2003-09-07 Luc Teirlinck - - * xresources.texi (Resources): Refer to `editres' man page. - (Lucid Resources): Update defaults. Expand description of - `shadowThickness'. - -2003-09-04 Miles Bader - - * Makefile.in (top_srcdir): New variable. - ($(top_srcdir)/info): New rule. - (info): Depend on it. - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2003-08-29 Richard M. Stallman - - * misc.texi (Saving Emacs Sessions): Correct previous change. - -2003-08-19 Luc Teirlinck - - * emacs.texi (Top): Update menu to reflect new Keyboard Macros chapter. - (Intro): Include kmacro.texi after fixit.texi instead of after - custom.texi. (As suggested by Kim Storm.) - -2003-08-18 Luc Teirlinck - - * fixit.texi (Fixit): Update `Next' pointer. - * files.texi (Files): Update `Previous' pointer. - * kmacro.texi (Keyboard Macros): Remove redundant node and section. - * emacs.texi (Intro): Include kmacro.texi after custom.texi. - (Suggested by Kim Storm.) - * Makefile (EMACSSOURCES): Add kmacro.texi. (Suggested by Kim Storm.) - -2003-08-18 Kim F. Storm - - * kmacro.texi: New file describing enhanced keyboard macro - functionality. Replaces old description in custom.texi. - - * custom.texi (Customization): Add xref to Keyboard Macros chapter. - (Keyboard Macros): Move to new kmacro.texi file. - - * emacs.texi (Keyboard Macros): Reference new keyboard macro topics. - -2003-08-17 Edward M. Reingold - - * calendar.texi (Specified Dates): Add `calendar-goto-day-of-year'. - -2003-08-17 Alex Schroeder - - * misc.texi (Saving Emacs Sessions): Manual M-x desktop-save not - required. - -2003-08-05 Richard M. Stallman - - * programs.texi (Lisp Indent): Don't describe - lisp-indent-function property here. Use xref to Lisp Manual. - -2003-08-03 Glenn Morris - - * calendar.texi (Date Formats): Document changed behavior of - abbreviations. - -2003-07-24 Markus Rost - - * buffers.texi (List Buffers): Fix previous change. - -2003-07-13 Markus Rost - - * buffers.texi (List Buffers): Adjust to new format of *Buffer - List*. - -2003-07-07 Luc Teirlinck - - * display.texi (Font Lock): Fix typo. - -2003-07-07 Richard M. Stallman - - * display.texi (Font Lock): Add xref for format info on - font-lock-remove-keywords. - - * building.texi (Compilation): Document what happens with asynch - children of compiler process. - - * help.texi (Library Keywords): Use @multitable. - -2003-06-04 Richard M. Stallman - - * programs.texi (Expressions): Delete C-M-DEL. - - * misc.texi (Shell Options): Clarify comint-scroll-show-maximum-output. - comint-move-point-for-output renamed from - comint-scroll-to-bottom-on-output. - - * custom.texi (Init Rebinding): Replace previous change with xref. - (Non-ASCII Rebinding): Explain that issue more briefly here. - -2003-05-28 Richard M. Stallman - - * indent.texi (Indentation): Condense, simplify, clarify prev change. - -2003-05-28 Nick Roberts - - * building.texi (GDB Graphical Interface): New node. - (Rewritten somewhat by RMS.) - -2003-05-28 Kai Großjohann - - * custom.texi (Init Rebinding): Xref Non-ASCII Rebinding, for - non-English letters. Explain how to set coding systems correctly - and how to include the right coding cookie in the file. - -2003-05-22 Kai Großjohann - - * indent.texi (Indentation): Explain the concepts. - (Just Spaces): Explain why preventing tabs for indentation might - be useful. - -2003-04-16 Richard M. Stallman - - * search.texi (Regexps): Ref to Lisp manual for more regexp features. - -2003-02-22 Alex Schroeder - - * cmdargs.texi (General Variables): Document SMTPSERVER. - - * sending.texi: Remove SMTP node. - (Mail Sending): Describe `send-mail-function'. Link to SMTP - library. - -2003-02-22 Alex Schroeder - - * sending.texi (Sending via SMTP): Explain MTA/MUA. - -2003-02-22 Simon Josefsson - - * sending.texi (Mail Methods): Add node about SMTP. - -2003-02-17 Jan Djärv - - * xresources.texi (GTK names in Emacs): Add emacs-toolbar - GtkToolbar. - -2003-02-01 Kevin Ryde - - * glossary.texi (Glossary): Correction to cl cross reference. - -2003-01-20 Richard M. Stallman - - * killing.texi (Rectangles): Document C-x c r. - -2003-01-19 Jan Djärv - - * xresources.texi (GTK resources): New node. - (GTK widget names): New node. - (GTK names in Emacs): New node. - (GTK styles): New node. - -2003-01-09 Francesco Potortì - - * maintaining.texi (Create Tags Table): Add reference to the new - `etags --help --lang=LANG' option. - -2002-10-02 Karl Berry - - * emacs.texi: Per rms, update all manuals to use @copying instead of - @ifinfo. Also use @ifnottex instead of @ifinfo around the top node, - where needed for the sake of the HTML output. - -2001-12-20 Eli Zaretskii - - * Makefile.in (EMACSSOURCES): Update the list of Emacs manual - source files. - -2001-11-16 Eli Zaretskii - - * Makefile.in (emacsman): New target. - -2001-10-20 Gerd Moellmann - - * (Version 21.1 released.) - -2001-10-05 Gerd Moellmann - - * Branch for 21.1. - -2001-03-05 Gerd Moellmann - - * Makefile.in (mostlyclean, maintainer-clean): Delete more files. - -2000-05-31 Stefan Monnier - - * .cvsignore (*.tmp): New entry. Seems to be used for @macro. - -1999-07-12 Richard Stallman - - * Version 20.4 released. - -1998-12-04 Markus Rost - - * Makefile.in (INFO_TARGETS): Delete customize.info. - (DVI_TARGETS): Delete customize.dvi. - (../info/customize, customize.dvi): Targets deleted. - -1998-08-19 Richard Stallman - - * Version 20.3 released. - -1998-05-06 Richard Stallman - - * Makefile.in (EMACSSOURCES): Add mule.texi. - Add msdog.texi, ack.texi. Remove gnu1.texi. - -1998-04-06 Andreas Schwab - - * Makefile.in (ENVADD): Environment vars to pass to texi2dvi. - Use it in dvi targets. - -1997-09-23 Paul Eggert - - * Makefile.in: Merge changes mistakenly made to `Makefile'. - (INFO_TARGETS): Change ../info/custom to ../info/customize. - (../info/customize): Rename from ../info/custom. - -1997-09-19 Richard Stallman - - * Version 20.2 released. - -1997-09-15 Richard Stallman - - * Version 20.1 released. - -1997-08-24 Richard Stallman - - * Makefile (../info/customize, customize.dvi): New targets. - (INFO_TARGETS): Add ../info/customize. - (DVI_TARGETS): Add customize.dvi. - -1996-08-11 Richard Stallman - - * Version 19.33 released. - -1996-07-31 Richard Stallman - - * Version 19.32 released. - -1996-06-20 Richard Stallman - - * Makefile.in (All info targets): cd $(srcdir) to do the work. - -1996-06-19 Richard Stallman - - * Makefile.in (All info targets): Specify $(srcdir) in input files. - Specify -I option. - (All dvi targets): Set the TEXINPUTS variable. - -1996-05-25 Karl Heuer - - * Version 19.31 released. - -1995-11-24 Richard Stallman - - * Version 19.30 released. - -1995-02-07 Richard Stallman - - * Makefile.in (maintainer-clean): Rename from realclean. - -1994-11-23 Richard Stallman - - * Makefile.in: New file. - * Makefile: File deleted. - -1994-11-19 Richard Stallman - - * Makefile (TEXINDEX_OBJS): Variable deleted. - (texindex, texindex.o, getopt.o): Rules deleted. - All deps on texindex deleted. - (distclean): Don't delete texindex. - (mostlyclean): Don't delete *.o. - * texindex.c, getopt.c: Files deleted. - -1994-09-07 Richard Stallman - - * Version 19.26 released. - -1994-07-02 Richard Stallman (rms@gnu.ai.mit.edu) - - * Makefile (EMACSSOURCES): Exclude undo.texi. - -1994-05-30 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.25 released. - -1994-05-23 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.24 released. - -1994-05-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.23 released. - -1994-04-17 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile: Delete spurious tab. - -1994-02-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (.SUFFIXES): New rule. - -1993-12-04 Richard Stallman (rms@srarc2) - - * getopt.c: New file. - * Makefile (TEXINDEX_OBJS): Use getopt.o in this dir, not ../lib-src. - (getopt.o): New rule. - (dvi): Don't depend on texindex. - (emacs.dvi): Depend on texindex. - -1993-12-03 Richard Stallman (rms@srarc2) - - * Makefile (TEXI2DVI): New variable. - (emacs.dvi): Add explicit command. - (TEXINDEX_OBJS): Delete duplicate getopt.o. - -1993-11-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.22 released. - -1993-11-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (TEXINDEX_OBJS): Delete spurious period. - -1993-11-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.21 released. - -1993-11-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (realclean): Don't delete the Info files. - -1993-10-25 Brian J. Fox (bfox@albert.gnu.ai.mit.edu) - - * frames.texi (Creating Frames): Mention `C-x 5' instead of `C-x - 4' where appropriate. - -1993-10-20 Brian J. Fox (bfox@ai.mit.edu) - - * Makefile: Fix targets for texindex. - - * texindex.c: Include "../src/config.h" if building in emacs. - - * Makefile: Change all files to FILENAME.texi, force all targets - to be FILENAME, not FILENAME.info. - Add target to build texindex.c, defining `emacs'. - -1993-08-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.19 released. - -1993-08-08 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.18 released. - -1993-07-20 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile: Fix source file names of the separate manuals. - -1993-07-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.17 released. - -1993-07-10 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * split-man: Fix typos in last change. - -1993-07-06 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.16 released. - -1993-06-19 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * version 19.15 released. - -1993-06-18 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Makefile (distclean): It's rm, not rf. - -1993-06-17 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.14 released. - -1993-06-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile: New file. - -1993-06-08 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.13 released. - -1993-05-27 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.9 released. - -1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.8 released. - -1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * cmdargs.texi: Document the -i, -itype, and -iconic options. - - * trouble.texi: It's `enable-flow-control-on', not - `evade-flow-control-on'. - -1993-05-24 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * display.texi: Document standard-display-european. - -1993-05-22 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.7 released. - - * emacs.texi: Add a sentence to the top menu mentioning the - specific version of Emacs this manual applies to. - -1993-04-25 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * basic.texi: Document next-line-add-lines variable used to - implement down-arrow. - - * killing.texi: Document kill-whole-line. - -1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) - - * text.texi: Update unix TeX ordering information. - -1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) - - * news.texi: Mention fill-rectangle in keybinding list. - - * killing.texi: Document fill-rectangle. - -1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * vc.texi: Bring the docs up to date with VC 5.2. - -1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * emacs.tex: Mention blackbox and gomoku under Amusements. - Assembler mode is now mentioned and appropriately indexed - under Programming Modes. - -1991-02-15 Robert J. Chassell (bob@wookumz.ai.mit.edu) - - * emacs.tex: Update TeX ordering information. - -1990-06-26 David Lawrence (tale@geech) - - * emacs.tex: Note that completion-ignored-extensions is not used - to filter out names when all completions are displayed in - *Completions*. - -1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * texindex.c: If USG, include sys/types.h and sys/fcntl.h. - -1990-03-21 Jim Kingdon (kingdon@pogo.ai.mit.edu) - - * emacs.tex: Add @findex grep. - -1988-08-16 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) - - * emacs.tex: Correct two typos. No other changes before - Version 19 will be made. - -1988-05-23 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) - - * emacs.tex: Update information for obtaining TeX distribution from the - University of Washington. - -;; Local Variables: -;; coding: utf-8 -;; End: - - Copyright (C) 1993-1999, 2001-2014 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in deleted file mode 100644 index 1d686959934..00000000000 --- a/doc/emacs/Makefile.in +++ /dev/null @@ -1,291 +0,0 @@ -### @configure_input@ - -# Copyright (C) 1994, 1996-2014 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -SHELL = @SHELL@ - -# NB If you add any more configure variables, -# update the sed rules in the dist target below. - -# Where to find the source code. $(srcdir) will be the doc/emacs subdirectory -# of the source tree. This is set by configure's `--srcdir' option. -srcdir=@srcdir@ - -# Only for make dist. -version=@version@ - -## Where the output files go. -## Note that the setfilename command in the .texi files assumes this. -## This is a bit funny. Because the info files are in the -## distribution tarfiles, they are always made in $scrdir/../../info, -## even for out-of-tree builds. -buildinfodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -prefix = @prefix@ -datarootdir = @datarootdir@ -datadir = @datadir@ -PACKAGE_TARNAME = @PACKAGE_TARNAME@ -docdir = @docdir@ -dvidir = @dvidir@ -htmldir = @htmldir@ -pdfdir = @pdfdir@ -psdir = @psdir@ - -MKDIR_P = @MKDIR_P@ - -GZIP_PROG = @GZIP_PROG@ - -HTML_OPTS = --no-split --html - -INFO_EXT=@INFO_EXT@ -# Options used only when making info output. -# --no-split is only needed because of MS-DOS. -# For a possible alternative, see -# http://lists.gnu.org/archive/html/emacs-devel/2011-01/msg01182.html -INFO_OPTS=@INFO_OPTS@ - -INSTALL = @INSTALL@ -INSTALL_DATA = @INSTALL_DATA@ - -# The makeinfo program is part of the Texinfo distribution. -# Use --force so that it generates output even if there are errors. -MAKEINFO = @MAKEINFO@ -MAKEINFO_OPTS = --force --enable-encoding -I $(srcdir) - -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips - - -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" - -DVI_TARGETS = emacs.dvi emacs-xtra.dvi -HTML_TARGETS = emacs.html -PDF_TARGETS = emacs.pdf emacs-xtra.pdf -PS_TARGETS = emacs.ps emacs-xtra.ps - -EMACS_XTRA= \ - ${srcdir}/emacs-xtra.texi \ - $(srcdir)/arevert-xtra.texi \ - $(srcdir)/cal-xtra.texi \ - $(srcdir)/dired-xtra.texi \ - $(srcdir)/picture-xtra.texi \ - $(srcdir)/emerge-xtra.texi \ - $(srcdir)/vc-xtra.texi \ - $(srcdir)/vc1-xtra.texi \ - $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi - -EMACSSOURCES= \ - ${srcdir}/emacs.texi \ - ${srcdir}/emacsver.texi \ - ${srcdir}/doclicense.texi \ - ${srcdir}/gpl.texi \ - ${srcdir}/screen.texi \ - ${srcdir}/commands.texi \ - ${srcdir}/entering.texi \ - ${srcdir}/basic.texi \ - ${srcdir}/mini.texi \ - ${srcdir}/m-x.texi \ - ${srcdir}/help.texi \ - ${srcdir}/mark.texi \ - ${srcdir}/killing.texi \ - ${srcdir}/regs.texi \ - ${srcdir}/display.texi \ - ${srcdir}/search.texi \ - ${srcdir}/fixit.texi \ - ${srcdir}/files.texi \ - ${srcdir}/buffers.texi \ - ${srcdir}/windows.texi \ - ${srcdir}/frames.texi \ - ${srcdir}/mule.texi \ - ${srcdir}/modes.texi \ - ${srcdir}/indent.texi \ - ${srcdir}/text.texi \ - ${srcdir}/programs.texi \ - ${srcdir}/building.texi \ - ${srcdir}/maintaining.texi \ - ${srcdir}/abbrevs.texi \ - ${srcdir}/sending.texi \ - ${srcdir}/rmail.texi \ - ${srcdir}/dired.texi \ - ${srcdir}/calendar.texi \ - ${srcdir}/misc.texi \ - ${srcdir}/package.texi \ - ${srcdir}/custom.texi \ - ${srcdir}/trouble.texi \ - ${srcdir}/cmdargs.texi \ - ${srcdir}/xresources.texi \ - ${srcdir}/anti.texi \ - ${srcdir}/macos.texi \ - ${srcdir}/msdog.texi \ - ${srcdir}/gnu.texi \ - ${srcdir}/glossary.texi \ - ${srcdir}/ack.texi \ - ${srcdir}/kmacro.texi \ - $(EMACS_XTRA) - -## The info/ directory exists in release tarfiles but not the repository. -mkinfodir = @${MKDIR_P} ${buildinfodir} - -.PHONY: info dvi html pdf ps - -.SUFFIXES: .ps .dvi - -.dvi.ps: - $(DVIPS) -o $@ $< - -info: $(buildinfodir)/emacs$(INFO_EXT) -dvi: $(DVI_TARGETS) -html: $(HTML_TARGETS) -pdf: $(PDF_TARGETS) -ps: $(PS_TARGETS) - -# Note that all the Info targets build the Info files in srcdir. -# There is no provision for Info files to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. -# Note: "<" is not portable in ordinary make rules. -$(buildinfodir)/emacs$(INFO_EXT): ${EMACSSOURCES} - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/emacs.texi - -emacs.dvi: ${EMACSSOURCES} - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi - -emacs.pdf: ${EMACSSOURCES} - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs.texi - -emacs.html: ${EMACSSOURCES} - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/emacs.texi - -emacs-xtra.dvi: $(EMACS_XTRA) - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi - -emacs-xtra.pdf: $(EMACS_XTRA) - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-xtra.texi - -.PHONY: mostlyclean clean distclean maintainer-clean infoclean - -## Temp files. -mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs - -## Products not in the release tarfiles. -clean: mostlyclean - rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) - rm -f emacs-manual-${version}.tar* - -distclean: clean - rm -f Makefile - -## In the standalone tarfile, the clean rule runs this. -infoclean: - -cd $(buildinfodir) && rm -f emacs$(INFO_EXT) emacs$(INFO_EXT)-[1-9] emacs$(INFO_EXT)-[1-9][0-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -## Make a standalone tarfile of the Emacs manual sources. -## The [c] is a dumb way to prevent configure expanding it. -## TODO this is getting increasingly lengthy; not sure it is worth keeping. -dist: - rm -rf emacs-manual-${version} - mkdir emacs-manual-${version} - cp ${srcdir}/*.texi ${texinfodir}/texinfo.tex \ - ${srcdir}/ChangeLog* emacs-manual-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(buildinfodir *=\).*/\1 ./' \ - -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \ - -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \ - -e 's|@SH[E]LL@|/bin/bash|' \ - -e 's|@[p]refix@|/usr/local|' \ - -e 's|@[d]atarootdir@|$${prefix}/share|' \ - -e 's|@[d]atadir@|$${datarootdir}|' \ - -e 's|@[P]ACKAGE_TARNAME@|emacs|' \ - -e 's|@[d]ocdir@|$${datarootdir}/doc/$${PACKAGE_TARNAME}|' \ - -e 's|@[d]vidir@|$${docdir}|' \ - -e 's|@[h]tmldir@|$${docdir}|' \ - -e 's|@[p]dfdir@|$${docdir}|' \ - -e 's|@[p]sdir@|$${docdir}|' \ - -e 's|@[G]ZIP_PROG@|gzip|' \ - -e 's|@IN[S]TALL@|install -c|' \ - -e 's|@IN[S]TALL_DATA@|$${INSTALL} -m 644|' \ - -e '/@[c]onfigure_input@/d' \ - ${srcdir}/Makefile.in > emacs-manual-${version}/Makefile - @if grep '@[a-zA-Z_]*@' emacs-manual-${version}/Makefile; then \ - echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \ - fi - tar -cf emacs-manual-${version}.tar emacs-manual-${version} - rm -rf emacs-manual-${version} - - -.PHONY: install-dvi install-html install-pdf install-ps install-doc - -install-dvi: dvi - umask 022; $(MKDIR_P) "$(DESTDIR)$(dvidir)" - $(INSTALL_DATA) $(DVI_TARGETS) "$(DESTDIR)$(dvidir)" -install-html: html - umask 022; $(MKDIR_P) "$(DESTDIR)$(htmldir)" - $(INSTALL_DATA) $(HTML_TARGETS) "$(DESTDIR)$(htmldir)" -install-pdf: pdf - umask 022;$(MKDIR_P) "$(DESTDIR)$(pdfdir)" - $(INSTALL_DATA) $(PDF_TARGETS) "$(DESTDIR)$(pdfdir)" -install-ps: ps - umask 022; $(MKDIR_P) "$(DESTDIR)$(psdir)" - for file in $(PS_TARGETS); do \ - $(INSTALL_DATA) $${file} "$(DESTDIR)$(psdir)"; \ - [ -n "${GZIP_PROG}" ] || continue; \ - rm -f "$(DESTDIR)$(psdir)/$${file}.gz"; \ - ${GZIP_PROG} -9n "$(DESTDIR)$(psdir)/$${file}"; \ - done - -## Top-level Makefile installs the info pages. -install-doc: install-dvi install-html install-pdf install-ps - - -.PHONY: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps uninstall-doc - -uninstall-dvi: - for file in $(DVI_TARGETS); do \ - rm -f "$(DESTDIR)$(dvidir)/$${file}"; \ - done -uninstall-html: - for file in $(HTML_TARGETS); do \ - rm -f "$(DESTDIR)$(htmldir)/$${file}"; \ - done -uninstall-ps: - ext= ; [ -n "${GZIP_PROG}" ] && ext=.gz; \ - for file in $(PS_TARGETS); do \ - rm -f "$(DESTDIR)$(psdir)/$${file}$${ext}"; \ - done -uninstall-pdf: - for file in $(PDF_TARGETS); do \ - rm -f "$(DESTDIR)$(pdfdir)/$${file}"; \ - done - -uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps - - -### Makefile ends here diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi deleted file mode 100644 index 4d46a5d8f57..00000000000 --- a/doc/emacs/abbrevs.texi +++ /dev/null @@ -1,448 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Abbrevs -@chapter Abbrevs -@cindex abbrevs -@cindex expansion (of abbrevs) - - A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert -it, into some different text. Abbrevs are defined by the user to expand -in specific ways. For example, you might define @samp{foo} as an abbrev -expanding to @samp{find outer otter}. Then you could insert -@samp{find outer otter } into the buffer by typing @kbd{f o o -@key{SPC}}. - - A second kind of abbreviation facility is called @dfn{dynamic abbrev -expansion}. You use dynamic abbrev expansion with an explicit command -to expand the letters in the buffer before point by looking for other -words in the buffer that start with those letters. @xref{Dynamic -Abbrevs}. - - ``Hippie'' expansion generalizes abbreviation expansion. -@xref{Hippie Expand, , Hippie Expansion, autotype, Features for -Automatic Typing}. - -@menu -* Abbrev Concepts:: Fundamentals of defined abbrevs. -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. -* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. -@end menu - -@node Abbrev Concepts -@section Abbrev Concepts - - An @dfn{abbrev} is a word that has been defined to @dfn{expand} into -a specified @dfn{expansion}. When you insert a word-separator character -following the abbrev, that expands the abbrev---replacing the abbrev -with its expansion. For example, if @samp{foo} is defined as an abbrev -expanding to @samp{find outer otter}, then typing @kbd{f o o .} will -insert @samp{find outer otter.}. - -@findex abbrev-mode -@cindex Abbrev mode -@cindex mode, Abbrev - Abbrevs expand only when Abbrev mode, a buffer-local minor mode, is -enabled. Disabling Abbrev mode does not cause abbrev definitions to -be forgotten, but they do not expand until Abbrev mode is enabled -again. The command @kbd{M-x abbrev-mode} toggles Abbrev mode; with a -numeric argument, it turns Abbrev mode on if the argument is positive, -off otherwise. @xref{Minor Modes}. - - Abbrevs can have @dfn{mode-specific} definitions, active only in one major -mode. Abbrevs can also have @dfn{global} definitions that are active in -all major modes. The same abbrev can have a global definition and various -mode-specific definitions for different major modes. A mode-specific -definition for the current major mode overrides a global definition. - - You can define abbrevs interactively during the editing session, -irrespective of whether Abbrev mode is enabled. You can also save -lists of abbrev definitions in files, which you can the reload for use -in later sessions. - -@node Defining Abbrevs -@section Defining Abbrevs - -@table @kbd -@item C-x a g -Define an abbrev, using one or more words before point as its expansion -(@code{add-global-abbrev}). -@item C-x a l -Similar, but define an abbrev specific to the current major mode -(@code{add-mode-abbrev}). -@item C-x a i g -Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}). -@item C-x a i l -Define a word in the buffer as a mode-specific abbrev -(@code{inverse-add-mode-abbrev}). -@item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as an abbrev expanding into @var{exp}. -@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}. -@item M-x kill-all-abbrevs -Discard all abbrev definitions, leaving a blank slate. -@end table - -@kindex C-x a g -@findex add-global-abbrev - The usual way to define an abbrev is to enter the text you want the -abbrev to expand to, position point after it, and type @kbd{C-x a g} -(@code{add-global-abbrev}). This reads the abbrev itself using the -minibuffer, and then defines it as an abbrev for one or more words before -point. Use a numeric argument to say how many words before point should be -taken as the expansion. For example, to define the abbrev @samp{foo} as -mentioned above, insert the text @samp{find outer otter} and then type -@kbd{C-u 3 C-x a g f o o @key{RET}}. - - An argument of zero to @kbd{C-x a g} means to use the contents of the -region as the expansion of the abbrev being defined. - -@kindex C-x a l -@findex add-mode-abbrev - The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but -defines a mode-specific abbrev for the current major mode. The -arguments work the same as for @kbd{C-x a g}. - -@kindex C-x a i g -@findex inverse-add-global-abbrev -@kindex C-x a i l -@findex inverse-add-mode-abbrev - @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and @kbd{C-x a i -l} (@code{inverse-add-mode-abbrev}) perform the opposite task: if the -abbrev text is already in the buffer, you use these commands to define -an abbrev by specifying the expansion in the minibuffer. These -commands will expand the abbrev text used for the definition. - -@findex define-mode-abbrev -@findex define-global-abbrev - You can define an abbrev without inserting either the abbrev or its -expansion in the buffer using the command @code{define-global-abbrev}. -It reads two arguments---the abbrev, and its expansion. The command -@code{define-mode-abbrev} does likewise for a mode-specific abbrev. - - To change the definition of an abbrev, just make a new definition. -When an abbrev has a prior definition, the abbrev definition commands -ask for confirmation before replacing it. - -@findex kill-all-abbrevs - To remove an abbrev definition, give a negative argument to the -abbrev definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. -The former removes a global definition, while the latter removes a -mode-specific definition. @kbd{M-x kill-all-abbrevs} removes all -abbrev definitions, both global and local. - -@node Expanding Abbrevs -@section Controlling Abbrev Expansion - - When Abbrev mode is enabled, an abbrev expands whenever it is -present in the buffer just before point and you type a self-inserting -whitespace or punctuation character (@key{SPC}, comma, etc.). More -precisely, any character that is not a word constituent expands an -abbrev, and any word-constituent character can be part of an abbrev. -The most common way to use an abbrev is to insert it and then insert a -punctuation or whitespace character to expand it. - -@vindex abbrev-all-caps - Abbrev expansion preserves case: @samp{foo} expands to @samp{find -outer otter}, and @samp{Foo} to @samp{Find outer otter}. @samp{FOO} -expands to @samp{Find Outer Otter} by default, but if you change the -variable @code{abbrev-all-caps} to a non-@code{nil} value, it expands -to @samp{FIND OUTER OTTER}. - - These commands are used to control abbrev expansion: - -@table @kbd -@item M-' -Separate a prefix from a following abbrev to be expanded -(@code{abbrev-prefix-mark}). -@item C-x a e -@findex expand-abbrev -Expand the abbrev before point (@code{expand-abbrev}). -This is effective even when Abbrev mode is not enabled. -@item M-x expand-region-abbrevs -Expand some or all abbrevs found in the region. -@end table - -@kindex M-' -@findex abbrev-prefix-mark - You may wish to expand an abbrev and attach a prefix to the expansion; -for example, if @samp{cnst} expands into @samp{construction}, you might want -to use it to enter @samp{reconstruction}. It does not work to type -@kbd{recnst}, because that is not necessarily a defined abbrev. What -you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in -between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert -@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to -indicate that it has done its work. Then insert the abbrev @samp{cnst}; -the buffer now contains @samp{re-cnst}. Now insert a non-word character -to expand the abbrev @samp{cnst} into @samp{construction}. This -expansion step also deletes the hyphen that indicated @kbd{M-'} had been -used. The result is the desired @samp{reconstruction}. - - If you actually want the text of the abbrev in the buffer, rather than -its expansion, you can accomplish this by inserting the following -punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in -the buffer, not expanding it. - -@findex unexpand-abbrev - If you expand an abbrev by mistake, you can undo the expansion by -typing @kbd{C-/} (@code{undo}). @xref{Undo}. This undoes the -insertion of the abbrev expansion and brings back the abbrev text. If -the result you want is the terminating non-word character plus the -unexpanded abbrev, you must reinsert the terminating character, -quoting it with @kbd{C-q}. You can also use the command @kbd{M-x -unexpand-abbrev} to cancel the last expansion without deleting the -terminating character. - -@findex expand-region-abbrevs - @kbd{M-x expand-region-abbrevs} searches through the region for defined -abbrevs, and for each one found offers to replace it with its expansion. -This command is useful if you have typed in text using abbrevs but forgot -to turn on Abbrev mode first. It may also be useful together with a -special set of abbrev definitions for making several global replacements at -once. This command is effective even if Abbrev mode is not enabled. - - The function @code{expand-abbrev} performs the expansion by calling -the function that @code{abbrev-expand-function} specifies. By -changing this function you can make arbitrary changes to -the abbrev expansion. @xref{Abbrev Expansion,,, elisp, The Emacs Lisp -Reference Manual}. - -@node Editing Abbrevs -@section Examining and Editing Abbrevs - -@table @kbd -@item M-x list-abbrevs -Display a list of all abbrev definitions. With a numeric argument, list -only local abbrevs. -@item M-x edit-abbrevs -Edit a list of abbrevs; you can add, alter or remove definitions. -@end table - -@findex list-abbrevs - The output from @kbd{M-x list-abbrevs} looks like this: - -@example -@var{various other tables@dots{}} -(lisp-mode-abbrev-table) -"dk" 0 "define-key" -(global-abbrev-table) -"dfn" 0 "definition" -@end example - -@noindent -(Some blank lines of no semantic significance, and some other abbrev -tables, have been omitted.) - - A line containing a name in parentheses is the header for abbrevs in a -particular abbrev table; @code{global-abbrev-table} contains all the global -abbrevs, and the other abbrev tables that are named after major modes -contain the mode-specific abbrevs. - - Within each abbrev table, each nonblank line defines one abbrev. The -word at the beginning of the line is the abbrev. The number that -follows is the number of times the abbrev has been expanded. Emacs -keeps track of this to help you see which abbrevs you actually use, so -that you can eliminate those that you don't use often. The string at -the end of the line is the expansion. - - Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs -(@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) are -pre-defined by various modes, and are not saved to your abbrev file. -To disable a ``system'' abbrev, define an abbrev of the same name that -expands to itself, and save it to your abbrev file. - -@findex edit-abbrevs -@kindex C-c C-c @r{(Edit Abbrevs)} - @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev -definitions by editing a list of them in an Emacs buffer. The list has -the same format described above. The buffer of abbrevs is called -@file{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in -this buffer to install the abbrev definitions as specified in the -buffer---and delete any abbrev definitions not listed. - - The command @code{edit-abbrevs} is actually the same as -@code{list-abbrevs} except that it selects the buffer @file{*Abbrevs*} -whereas @code{list-abbrevs} merely displays it in another window. - -@node Saving Abbrevs -@section Saving Abbrevs - - These commands allow you to keep abbrev definitions between editing -sessions. - -@table @kbd -@item M-x write-abbrev-file @key{RET} @var{file} @key{RET} -Write a file @var{file} describing all defined abbrevs. -@item M-x read-abbrev-file @key{RET} @var{file} @key{RET} -Read the file @var{file} and define abbrevs as specified therein. -@item M-x define-abbrevs -Define abbrevs from definitions in current buffer. -@item M-x insert-abbrevs -Insert all abbrevs and their expansions into current buffer. -@end table - -@findex write-abbrev-file - @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and -then writes a description of all current abbrev definitions into that -file. This is used to save abbrev definitions for use in a later -session. The text stored in the file is a series of Lisp expressions -that, when executed, define the same abbrevs that you currently have. - -@findex read-abbrev-file -@findex quietly-read-abbrev-file -@vindex abbrev-file-name -@cindex abbrev file - @kbd{M-x read-abbrev-file} reads a file name using the minibuffer -and then reads the file, defining abbrevs according to the contents of -the file. The function @code{quietly-read-abbrev-file} is similar -except that it does not display a message in the echo area; you cannot -invoke it interactively, and it is used primarily in your init file -(@pxref{Init File}). If either of these functions is called with -@code{nil} as the argument, it uses the file given by the variable -@code{abbrev-file-name}, which is @file{~/.emacs.d/abbrev_defs} by -default. This is your standard abbrev definition file, and Emacs -loads abbrevs from it automatically when it starts up. (As an -exception, Emacs does not load the abbrev file when it is started in -batch mode. @xref{Initial Options}, for a description of batch mode.) - -@vindex save-abbrevs - Emacs will offer to save abbrevs automatically if you have changed -any of them, whenever it offers to save all files (for @kbd{C-x s} or -@kbd{C-x C-c}). It saves them in the file specified by -@code{abbrev-file-name}. This feature can be inhibited by setting the -variable @code{save-abbrevs} to @code{nil}. - -@findex insert-abbrevs -@findex define-abbrevs - The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are -similar to the previous commands but work on text in an Emacs buffer. -@kbd{M-x insert-abbrevs} inserts text into the current buffer after point, -describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses -the entire current buffer and defines abbrevs accordingly. - -@node Dynamic Abbrevs -@section Dynamic Abbrev Expansion - - The abbrev facility described above operates automatically as you -insert text, but all abbrevs must be defined explicitly. By contrast, -@dfn{dynamic abbrevs} allow the meanings of abbreviations to be -determined automatically from the contents of the buffer, but dynamic -abbrev expansion happens only when you request it explicitly. - -@kindex M-/ -@kindex C-M-/ -@findex dabbrev-expand -@findex dabbrev-completion -@table @kbd -@item M-/ -Expand the word in the buffer before point as a @dfn{dynamic abbrev}, -by searching in the buffer for words starting with that abbreviation -(@code{dabbrev-expand}). - -@item C-M-/ -Complete the word before point as a dynamic abbrev -(@code{dabbrev-completion}). -@end table - -@vindex dabbrev-limit - For example, if the buffer contains @samp{does this follow } and you -type @kbd{f o M-/}, the effect is to insert @samp{follow} because that -is the last word in the buffer that starts with @samp{fo}. A numeric -argument to @kbd{M-/} says to take the second, third, etc.@: distinct -expansion found looking backward from point. Repeating @kbd{M-/} -searches for an alternative expansion by looking farther back. After -scanning all the text before point, it searches the text after point. -The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far -away in the buffer to search for an expansion. - -@vindex dabbrev-check-all-buffers - After scanning the current buffer, @kbd{M-/} normally searches other -buffers, unless you have set @code{dabbrev-check-all-buffers} to -@code{nil}. - -@vindex dabbrev-ignored-buffer-regexps - For finer control over which buffers to scan, customize the variable -@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regular -expressions. If a buffer's name matches any of these regular -expressions, dynamic abbrev expansion skips that buffer. - - A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to -search first for expansions after point, then other buffers, and -consider expansions before point only as a last resort. If you repeat -the @kbd{M-/} to look for another expansion, do not specify an -argument. Repeating @kbd{M-/} cycles through all the expansions after -point and then the expansions before point. - - After you have expanded a dynamic abbrev, you can copy additional -words that follow the expansion in its original context. Simply type -@kbd{@key{SPC} M-/} for each additional word you want to copy. The -spacing and punctuation between words is copied along with the words. - - The command @kbd{C-M-/} (@code{dabbrev-completion}) performs -completion of a dynamic abbrev. Instead of trying the possible -expansions one by one, it finds all of them, then inserts the text -that they have in common. If they have nothing in common, @kbd{C-M-/} -displays a list of completions, from which you can select a choice in -the usual manner. @xref{Completion}. - - Dynamic abbrev expansion is completely independent of Abbrev mode; the -expansion of a word with @kbd{M-/} is completely independent of whether -it has a definition as an ordinary abbrev. - -@node Dabbrev Customization -@section Customizing Dynamic Abbreviation - - Normally, dynamic abbrev expansion ignores case when searching for -expansions. That is, the expansion need not agree in case with the word -you are expanding. - -@vindex dabbrev-case-fold-search - This feature is controlled by the variable -@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored -in this search; if it is @code{nil}, the word and the expansion must -match in case. If the value is @code{case-fold-search} (the default), -then the variable @code{case-fold-search} controls whether to ignore -case while searching for expansions (@pxref{Search Case}). - -@vindex dabbrev-case-replace - Normally, dynamic abbrev expansion preserves the case pattern -@emph{of the dynamic abbrev you are expanding}, by converting the -expansion to that case pattern. - -@vindex dabbrev-case-fold-search - The variable @code{dabbrev-case-replace} controls whether to -preserve the case pattern of the dynamic abbrev. If it is @code{t}, -the dynamic abbrev's case pattern is preserved in most cases; if it is -@code{nil}, the expansion is always copied verbatim. If the value is -@code{case-replace} (the default), then the variable -@code{case-replace} controls whether to copy the expansion verbatim -(@pxref{Replacement and Case}). - - However, if the expansion contains a complex mixed case pattern, and -the dynamic abbrev matches this pattern as far as it goes, then the -expansion is always copied verbatim, regardless of those variables. -Thus, for example, if the buffer contains -@code{variableWithSillyCasePattern}, and you type @kbd{v a M-/}, it -copies the expansion verbatim including its case pattern. - -@vindex dabbrev-abbrev-char-regexp - The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil}, -controls which characters are considered part of a word, for dynamic expansion -purposes. The regular expression must match just one character, never -two or more. The same regular expression also determines which -characters are part of an expansion. The value @code{nil} has a special -meaning: dynamic abbrevs are made of word characters, but expansions are -made of word and symbol characters. - -@vindex dabbrev-abbrev-skip-leading-regexp - In shell scripts and makefiles, a variable name is sometimes prefixed -with @samp{$} and sometimes not. Major modes for this kind of text can -customize dynamic abbrev expansion to handle optional prefixes by setting -the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value -should be a regular expression that matches the optional prefix that -dynamic abbrev expression should ignore. diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi deleted file mode 100644 index ccd58b7aece..00000000000 --- a/doc/emacs/ack.texi +++ /dev/null @@ -1,1457 +0,0 @@ -@c -*- coding: utf-8 -*- -@c This is part of the Emacs manual. -@c Copyright (C) 1994-1997, 1999-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@node Acknowledgments -@unnumbered Acknowledgments - -Many people have contributed code included in the Free Software -Foundation's distribution of GNU Emacs. To show our appreciation for -their public spirit, we list here in alphabetical order those who have -written substantial portions. Others too numerous to mention have -reported and fixed bugs, and added features to many parts of Emacs. -We thank them for their generosity as well. - -This list is intended to mention every contributor of a major package or -feature we currently distribute; if you know of someone we have omitted, -please make a bug report. More comprehensive information is -available in the @file{ChangeLog} files, summarized in the file -@file{etc/AUTHORS} in the distribution. - -@c We should list here anyone who has contributed a new package, -@c and anyone who has made major enhancements in Emacs -@c that many users would notice and consider important. -@c Remove things that are no longer distributed. -@c Note this file is only used ifnottex; otherwise a shorter version in -@c emacs.texi is used. - -@itemize @bullet -@item -Per Abrahamsen wrote the customization facilities, as well as -@file{double.el}, for typing accented characters not normally available -from the keyboard; @file{xt-mouse.el}, which allows mouse commands -through Xterm; @file{gnus-cus.el}, which implements customization -commands for Gnus; @file{gnus-cite.el}, a citation-parsing facility for -news articles; @file{gnus-score.el}, scoring for Gnus; @file{cpp.el}, -which hides or highlights parts of C programs according to preprocessor -conditionals; and the widget library files @file{wid-browse.el}, -@file{wid-edit.el}, @file{widget.el}. He also co-wrote -@file{gnus-soup.el}. - -@item -Tomas Abrahamsson wrote @file{artist.el}, a package for producing -@acronym{ASCII} art with a mouse or with keyboard keys. - -@item -Jay K. Adams wrote @file{jka-compr.el} and @file{jka-cmpr-hook.el}, -providing automatic decompression and recompression for compressed -files. - -@item -Michael Albinus wrote @file{dbus.el}, a package that implements the -D-Bus message bus protocol; @file{zeroconf.el}, a mode for browsing -Avahi services; @file{secrets.el}, an interface to keyring daemons for -storing confidential data; and @file{filenotify.el} and the associated -low-level interface routines, for watching file status changes. -He and Kai Großjohann wrote the Tramp package, which provides -transparent remote file editing using ssh, ftp, and other network -protocols. He and Daniel Pittman wrote @file{tramp-cache.el}. - -@item -Ralf Angeli wrote @file{scroll-lock.el}, a minor mode which keeps the -point vertically fixed by scrolling the window when moving up and down -in the buffer. - -@item -Joe Arceneaux wrote the original text property implementation, and -implemented support for X11. - -@item -Emil Åström, Milan Zamaza, and Stefan Bruda wrote @file{prolog.el}, -a mode for editing Prolog (and Mercury) code. - -@item -Miles Bader wrote @file{image-file.el}, support code for visiting image -files; @file{minibuf-eldef.el}, a minor mode that hides the minibuffer -default value when appropriate; @file{rfn-eshadow.el}, shadowing of -@code{read-file-name} input; @file{mb-depth.el}, display of minibuffer -depth; @file{button.el}, the library that implements clickable buttons; -@file{face-remap.el}, a package for changing the default face in -individual buffers; and @file{macroexp.el} for macro-expansion. He -also worked on an early version of the lexical binding code. - -@item -David Bakhash wrote @file{strokes.el}, a mode for controlling Emacs by -moving the mouse in particular patterns. - -@item -Juanma Barranquero wrote @file{emacs-lock.el} (based on the original -version by Tom Wurgler), which makes it harder to exit with valuable -buffers unsaved; and @file{frameset.el}, for saving and restoring the -frame/window setup. He also made many other contributions to other -areas, including MS Windows support. - -@item -Eli Barzilay wrote @file{calculator.el}, a desktop calculator for -Emacs. - -@item -Steven L. Baur wrote @file{footnote.el} which lets you include -footnotes in email messages; and @file{gnus-audio.el} and -@file{earcon.el}, which provide sound effects for Gnus. He also wrote -@file{gnus-setup.el}. - -@item -Alexander L. Belikoff, Sergey Berezin, Sacha Chua, David Edmondson, -Noah Friedman, Andreas Fuchs, Mario Lang, Ben Mesander, Lawrence -Mitchell, Gergely Nagy, Michael Olson, Per Persson, Jorgen Schäfer, -Alex Schroeder, and Tom Tromey wrote ERC, an advanced Internet Relay -Chat client (for more information, see the file @file{CREDITS} in the -ERC distribution). - -@item -Scott Bender, Michael Brouwer, Christophe de Dinechin, Carl Edman, -Christian Limpach and Adrian Robert developed and maintained the -NeXTstep port of Emacs. - -@item -Stephen Berman wrote @file{todo-mode.el} (based on the original version -by Oliver Seidel), a package for maintaining @file{TODO} list files. - -@item -Anna M. Bigatti wrote @file{cal-html.el}, which produces HTML calendars. - -@item -Ray Blaak and Simon South wrote @file{opascal.el}, a mode for editing -Object Pascal source code. - -@item -Martin Blais, Stefan Merten, and David Goodger wrote @file{rst.el}, a -mode for editing reStructuredText documents. - -@item -Jim Blandy wrote Emacs 19's input system, brought its configuration and -build process up to the GNU coding standards, and contributed to the -frame support and multi-face support. Jim also wrote @file{tvi970.el}, -terminal support for the TeleVideo 970 terminals; and co-wrote -@file{wyse50.el} (q.v.). - -@item -Per Bothner wrote @file{term.el}, a terminal emulator in an Emacs -buffer. - -@item -Terrence M. Brannon wrote @file{landmark.el}, a neural-network robot -that learns landmarks. - -@item -Frank Bresz wrote @file{diff.el}, a program to display @code{diff} -output. - -@item -Peter Breton implemented @file{dirtrack.el}, a library for tracking -directory changes in shell buffers; @file{filecache.el}, which records -which directories your files are in; @file{locate.el}, which -interfaces to the @code{locate} command; @file{find-lisp.el}, an Emacs -Lisp emulation of the @command{find} program; @file{net-utils.el}; and -the ``generic mode'' feature. - -@item -Emmanuel Briot wrote @file{xml.el}, an XML parser for Emacs; and -@file{ada-prj.el}, editing of Ada mode project files, as well as -co-authoring @file{ada-mode.el} and @file{ada-xref.el}. - -@item -Kevin Broadey wrote @file{foldout.el}, providing folding extensions to -Emacs's outline modes. - -@item -David M. Brown wrote @file{array.el}, for editing arrays and other -tabular data. - -@item -Włodek Bzyl and Ryszard Kubiak wrote @file{ogonek.el}, a package for -changing the encoding of Polish characters. - -@item -Bill Carpenter provided @file{feedmail.el}, a package for massaging -outgoing mail messages and sending them through various popular mailers. - -@item -Per Cederqvist and Inge Wallin wrote @file{ewoc.el}, an Emacs widget for -manipulating object collections. Per Cederqvist, Inge Wallin, and -Thomas Bellman wrote @file{avl-tree.el}, for balanced binary trees. - -@item -Hans Chalupsky wrote @file{advice.el}, an overloading mechanism for -Emacs Lisp functions; and @file{trace.el}, a tracing facility for Emacs -Lisp. - -@item -Chris Chase, Carsten Dominik, and J. D. Smith wrote IDLWAVE mode, -for editing IDL and WAVE CL. - -@item -Bob Chassell wrote @file{texnfo-upd.el}, @file{texinfo.el}, and -@file{makeinfo.el}, modes and utilities for working with Texinfo files; -and @file{page-ext.el}, commands for extended page handling. He also -wrote the ``Introduction to programming in Emacs Lisp'' manual. - -@item -Jihyun Cho wrote @file{hanja-util.el} and @file{hangul.el}, utilities -for Korean Hanja. - -@item -Andrew Choi and Yamamoto Mitsuharu wrote the Carbon support, used -prior to Emacs 23 for Mac OS. Yamamoto Mitsuharu continued to -contribute to Mac OS support in the newer Nextstep port; and also -improved support for multi-monitor displays. - -@item -Chong Yidong was the Emacs co-maintainer from Emacs 23 to 24.3. He made many -improvements to the Emacs display engine. He also wrote -@file{tabulated-list.el}, a generic major mode for lists of data; -and improved support for themes and packages. - -@item -James Clark wrote SGML mode, a mode for editing SGML documents; and -nXML mode, a mode for editing XML documents. He also contributed to -Emacs's dumping procedures. - -@item -Mike Clarkson wrote @file{edt.el}, an emulation of DEC's EDT editor. - -@item -Glynn Clements provided @file{gamegrid.el} and a couple of games that -use it, Snake and Tetris. - -@item -Andrew Cohen wrote @file{spam-wash.el}, to decode and clean email before -it is analyzed for spam. - -@item -Edward O'Connor wrote @file{json.el}, a file for parsing and -generating JSON files. - -@item -Georges Brun-Cottan and Stefan Monnier wrote @file{easy-mmode.el}, a -package for easy definition of major and minor modes. - -@item -Andrew Csillag wrote M4 mode (@file{m4-mode.el}). - -@item -Doug Cutting and Jamie Zawinski wrote @file{disass.el}, a disassembler -for compiled Emacs Lisp code. - -@item -Mathias Dahl wrote @file{image-dired.el}, a package for viewing image -files as ``thumbnails''. - -@item -Julien Danjou wrote an implementation of ``Desktop Notifications'' -(@file{notifications.el}, and related packages for ERC and Gnus); -and @file{color.el}, a library for general color manipulation. -He also made various contributions to Gnus. - -@item -Vivek Dasmohapatra wrote @file{htmlfontify.el}, to convert a buffer or -source tree to HTML. - -@item -Matthieu Devin wrote @file{delsel.el}, a package to make newly-typed -text replace the current selection. - -@item -Eric Ding wrote @file{goto-addr.el}, - -@item -Jan Djärv added support for the GTK+ toolkit and X drag-and-drop. -He also wrote @file{dynamic-setting.el}. - -@item -Carsten Dominik wrote Ref@TeX{}, a package for setting up labels and -cross-references in @LaTeX{} documents; and co-wrote IDLWAVE mode -(q.v.). He was the original author of Org mode, for maintaining notes, -todo lists, and project planning. Bastien Guerry subsequently took -over maintainership. Benjamin Andresen, Thomas Baumann, Joel Boehland, Jan Böcker, Lennart -Borgman, Baoqiu Cui, Dan Davison, Christian Egli, Eric S. Fraga, Daniel German, Chris Gray, Konrad Hinsen, Tassilo Horn, Philip -Jackson, Martyn Jago, Thorsten Jolitz, Jambunathan K, Tokuya Kameshima, Sergey Litvinov, David Maus, Ross Patterson, Juan Pechiar, Sebastian Rose, Eric Schulte, -Paul Sexton, Ulf Stegemann, Andy Stewart, Christopher Suckling, David O'Toole, John Wiegley, Zhang Weize, -Piotr Zieliński, and others also wrote various Org mode components. -For more information, @pxref{History and Acknowledgments,,, org, The Org Manual}. - -@item -Scott Draves wrote @file{tq.el}, help functions for maintaining -transaction queues between Emacs and its subprocesses. - -@item -Benjamin Drieu wrote @file{pong.el}, an implementation of the classical -pong game. - -@item -Viktor Dukhovni wrote support for dumping under SunOS version 4. - -@item -John Eaton and Kurt Hornik wrote Octave mode. - -@item -Rolf Ebert, Markus Heritsch, and Emmanuel Briot wrote Ada mode. - -@item -Paul Eggert integrated the Gnulib portability library, and made many -other portability fixes to the C code; as well as his contributions -to VC and the calendar. - -@item -Stephen Eglen wrote @file{mspools.el}, which tells you which Procmail -folders have mail waiting in them. - -@item -Torbjörn Einarsson wrote @file{f90.el}, a mode for Fortran 90 files. - -@item -Tsugutomo Enami co-wrote the support for international character sets. - -@item -David Engster wrote @file{mairix.el} and @file{nnmairix.el}, an -interface to the Mairix indexing tool. - -@item -Hans Henrik Eriksen wrote @file{simula.el}, a mode for editing SIMULA 87 -code. - -@item -Michael Ernst wrote @file{reposition.el}, a command for recentering a -function's source code and preceding comment on the screen. - -@item -Ata Etemadi wrote @file{cdl.el}, functions for working with Common Data -Language source code. - -@item -Frederick Farnbach implemented @file{morse.el}, which converts text to -Morse code. - -@item -Oscar Figueiredo wrote EUDC, the Emacs Unified Directory Client, which -is an interface to directory servers via LDAP, CCSO PH/QI, or BBDB; and -@file{ldap.el}, the LDAP client interface. - -@item -Fred Fish wrote the support for dumping COFF executable files. - -@item -Karl Fogel wrote @file{bookmark.el}, which implements named -placeholders; @file{mail-hist.el}, a history mechanism for outgoing -mail messages; and @file{saveplace.el}, for preserving point's -location in files between editing sessions. - -@item -Gary Foster wrote @file{crisp.el}, the emulation for CRiSP and Brief -editors; and @file{scroll-all.el}, a mode for scrolling several buffers -together. - -@item -Romain Francoise contributed ACL (Access Control List) support, -for preserving extended file attributes on backup and copy. - -@item -Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin, -@file{type-break.el}, which reminds you to take periodic breaks from -typing, and @code{eldoc-mode}, a mode to show the defined parameters or -the doc string for the Lisp function near point. - -@item -Shigeru Fukaya wrote a testsuite for the byte-compiler. - -@item -Keith Gabryelski wrote @file{hexl.el}, a mode for editing binary files. - -@item -Kevin Gallagher rewrote and enhanced the EDT emulation, and wrote -@file{flow-ctrl.el}, a package for coping with unsuppressible XON/XOFF -flow control. - -@item -Fabián E. Gallina rewrote @file{python.el}, the major mode for the -Python programming language used in Emacs 24.3 onwards. - -@item -Kevin Gallo added multiple-frame support for Windows NT and wrote -@file{w32-win.el}, support functions for the MS-Windows window system. - -@item -Juan León Lahoz García wrote @file{wdired.el}, a package for -performing file operations by directly editing Dired buffers. - -@item -Howard Gayle wrote much of the C and Lisp code for display tables and -case tables. He also wrote @file{rot13.el}, a command to display the -plain-text form of a buffer encoded with the Caesar cipher; -@file{vt100-led.el}, a package for controlling the LEDs on -VT100-compatible terminals; and much of the support for ISO-8859 -European character sets (which includes @file{iso-ascii.el}, -@file{iso-insert.el}, @file{iso-swed.el}, -@file{iso-syntax.el}, @file{iso-transl.el}, and @file{swedish.el}). - -@item -Stephen Gildea made the Emacs quick reference card, and made many -contributions for @file{time-stamp.el}, a package for maintaining -last-change time stamps in files. - -@item -Julien Gilles wrote @file{gnus-ml.el}, a mailing list minor mode for -Gnus. - -@item -David Gillespie wrote the Common Lisp compatibility packages; -@code{Calc}, an advanced calculator and mathematical tool, since -maintained and developed by Jay Belanger; @file{complete.el}, a partial -completion mechanism; and @file{edmacro.el}, a package for editing -keyboard macros. - -@item -Bob Glickstein wrote @file{sregex.el}, a facility for writing regexps -using a Lisp-like syntax. - -@item -Boris Goldowsky wrote @file{avoid.el}, a package to keep the mouse -cursor out of the way of the text cursor; @file{shadowfile.el}, a -package for keeping identical copies of files in more than one place; -@file{format.el}, a package for reading and writing files in various -formats; @file{enriched.el}, a package for saving text properties in -files; @file{facemenu.el}, a package for specifying faces; and -@file{descr-text.el}, describing text and character properties. - -@item -Michelangelo Grigni wrote @file{ffap.el} which visits a file, -taking the file name from the buffer. - -@item -Odd Gripenstam wrote @file{dcl-mode.el} for editing DCL command files. - -@item -Michael Gschwind wrote @file{iso-cvt.el}, a package to convert between -the ISO 8859-1 character set and the notations for non-@acronym{ASCII} -characters used by @TeX{} and net tradition. - -@item -Bastien Guerry wrote @file{gnus-bookmark.el}, bookmark support for Gnus; -as well as helping to maintain Org mode (q.v.). - -@item -Henry Guillaume wrote @file{find-file.el}, a package to visit files -related to the currently visited file. - -@item -Doug Gwyn wrote the portable @code{alloca} implementation. - -@item -Ken'ichi Handa implemented most of the support for international -character sets, and wrote most of the Emacs 23 font handling code. He -also wrote @file{composite.el}, which provides a minor mode that -composes characters automatically when they are displayed; -@file{isearch-x.el}, a facility for searching non-@acronym{ASCII} -text; and @file{ps-bdf.el}, a BDF font support for printing -non-@acronym{ASCII} text on a PostScript printer. Together with Naoto -Takahashi, he wrote @file{quail.el}, an input facility for typing -non-@acronym{ASCII} text from an @acronym{ASCII} keyboard. - -@item -Jesper Harder wrote @file{yenc.el}, for decoding yenc encoded messages. - -@item -Alexandru Harsanyi wrote a library for accessing SOAP web services. - -@item -K. Shane Hartman wrote @file{chistory.el} and @file{echistory.el}, -packages for browsing command history lists; @file{electric.el} and -@file{helper.el}, which provide an alternative command loop and -appropriate help facilities; @file{emacsbug.el}, a package for -reporting Emacs bugs; @file{picture.el}, a mode for editing -@acronym{ASCII} pictures; and @file{view.el}, a package for perusing -files and buffers without editing them. - -@item -John Heidemann wrote @file{mouse-copy.el} and @file{mouse-drag.el}, -which provide alternative mouse-based editing and scrolling features. - -@item -Jon K Hellan wrote @file{utf7.el}, support for mail-safe transformation -format of Unicode. - -@item -Karl Heuer wrote the original blessmail script, implemented the -@code{intangible} text property, and rearranged the structure of the -@code{Lisp_Object} type to allow for more data bits. - -@item -Manabu Higashida ported Emacs to MS-DOS. - -@item -Anders Holst wrote @file{hippie-exp.el}, a versatile completion and -expansion package. - -@item -Tassilo Horn wrote DocView mode, allowing viewing of PDF, PostScript and -DVI documents. - -@item -Tom Houlder wrote @file{mantemp.el}, which generates manual C@t{++} -template instantiations. - -@item -Joakim Hove wrote @file{html2text.el}, a html to plain text converter. - -@item -Denis Howe wrote @file{browse-url.el}, a package for invoking a WWW -browser to display a URL. - -@item -Lars Magne Ingebrigtsen did a major redesign of the Gnus news-reader and -wrote many of its parts. Several of these are now general components of -Emacs, including: @file{dns.el} for Domain Name Service lookups; -@file{format-spec.el} for formatting arbitrary format strings; -@file{netrc.el} for parsing of @file{.netrc} files; and -@file{time-date.el} for general date and time handling. -He also wrote @file{network-stream.el}, for opening network processes; -@file{url-queue.el}, for controlling parallel downloads of URLs; -and implemented libxml2 support. He also wrote @file{eww.el}, -an Emacs Lisp web browser; and implemented native zlib decompression. -Components of Gnus have also been written by: Nagy Andras, David -Blacka, Scott Byer, Ludovic Courtès, Julien Danjou, Kevin Greiner, Kai -Großjohann, Joe Hildebrand, Paul Jarc, Simon Josefsson, Sascha -Lüdecke, David Moore, Jim Radford, Benjamin Rutt, Raymond Scholz, -Thomas Steffen, Reiner Steib, Jan Tatarik, Didier Verna, Ilja Weis, -Katsumi Yamaoka, Teodor Zlatanov, and others (@pxref{Contributors,,,gnus, the -Gnus Manual}). - -@item -Andrew Innes contributed extensively to the MS-Windows support. - -@item -Seiichiro Inoue improved Emacs's XIM support. - -@item -Philip Jackson wrote @file{find-cmd.el}, to build a @code{find} -command-line. - -@item -Ulf Jasper wrote @file{icalendar.el}, a package for converting Emacs -diary entries to and from the iCalendar format; -@file{newsticker.el}, an RSS and Atom based Newsticker; and -@file{bubbles.el}, a puzzle game. - -@item -Kyle Jones wrote @file{life.el}, a package to play Conway's ``life'' game. - -@item -Terry Jones wrote @file{shadow.el}, a package for finding potential -load-path problems when some Lisp file ``shadows'' another. - -@item -Simon Josefsson wrote @file{dns-mode.el}, an editing mode for Domain -Name System master files; @file{dig.el}, a Domain Name System interface; -@file{flow-fill.el}, a package for interpreting RFC2646 formatted text -in messages; @file{fringe.el}, a package for customizing the fringe; -@file{imap.el}, an Emacs Lisp library for talking to IMAP servers; -@file{password-cache.el}, a password reader; @file{nnimap.el}, the IMAP -back-end for Gnus; @file{url-imap.el} for the URL library; -@file{rfc2104.el}, a hashed message authentication facility; the Gnus -S/MIME and Sieve components; and @file{tls.el} and @file{starttls.el} -for the Transport Layer Security protocol. - -@item -Arne Jørgensen wrote @file{latexenc.el}, a package to -automatically guess the correct coding system in @LaTeX{} files. - -@item -Alexandre Julliard wrote @file{vc-git.el}, support for the Git version -control system. - -@item -Tomoji Kagatani implemented @file{smtpmail.el}, used for sending out -mail with SMTP. - -@item -Ivan Kanis wrote @file{vc-hg.el}, support for the Mercurial version -control system. - -@item -Henry Kautz wrote @file{bib-mode.el}, a mode for maintaining -bibliography databases compatible with @code{refer} (the @code{troff} -version) and @code{lookbib}, and @file{refbib.el}, a package to convert -those databases to the format used by the @LaTeX{} text formatting package. - -@item -Taichi Kawabata added support for Devanagari script and the Indian -languages, and wrote @file{ucs-normalize.el} for Unicode normalization. - -@item -Taro Kawagishi implemented the MD4 Message Digest Algorithm in Lisp; and -wrote @file{ntlm.el} and @file{sasl-ntlm.el} for NT LanManager -authentication support. - -@item -Howard Kaye wrote @file{sort.el}, commands to sort text in Emacs -buffers. - -@item -Michael Kifer wrote @code{ediff}, an interactive interface to the -@command{diff}, @command{patch}, and @command{merge} programs; and -Viper, another emulator of the VI editor. - -@item -Richard King wrote the first version of @file{userlock.el} and -@file{filelock.c}, which provide simple support for multiple users -editing the same file. He also wrote the initial version of -@file{uniquify.el}, a facility to make buffer names unique by adding -parts of the file's name to the buffer name. - -@item -Peter Kleiweg wrote @file{ps-mode.el}, a mode for editing PostScript -files and running a PostScript interpreter interactively from within -Emacs. - -@item -Karel Klíč contributed SELinux support, for preserving the -Security-Enhanced Linux context of files on backup and copy. - -@item -Shuhei Kobayashi wrote @file{hex-util.el}, for operating on hexadecimal -strings; and support for HMAC (Keyed-Hashing for Message Authentication). - -@item -Pavel Kobyakov wrote @file{flymake.el}, a minor mode for performing -on-the-fly syntax checking. - -@item -David M. Koppelman wrote @file{hi-lock.el}, a minor mode for -interactive automatic highlighting of parts of the buffer text. - -@item -Koseki Yoshinori wrote @file{iimage.el}, a minor mode for displaying -inline images. - -@item -Robert Krawitz wrote the original @file{xmenu.c}, part of Emacs's pop-up -menu support. - -@item -Sebastian Kremer wrote @code{dired-mode}, with contributions by Lawrence -R. Dodd. He also wrote @file{ls-lisp.el}, a Lisp emulation of the -@code{ls} command for platforms that don't have @code{ls} as a standard -program. - -@item -David Kågedal wrote @file{tempo.el}, providing support for -easy insertion of boilerplate text and other common constructions. - -@item -Igor Kuzmin wrote @file{cconv.el}, providing closure conversion for -statically scoped Emacs lisp. - -@item -Daniel LaLiberte wrote @file{edebug.el}, a source-level debugger for -Emacs Lisp; @file{cl-specs.el}, specifications to help @code{edebug} -debug code written using David Gillespie's Common Lisp support; and -@file{isearch.el}, Emacs's incremental search minor mode. He also -co-wrote @file{hideif.el} (q.v.). - -@item -Karl Landstrom and Daniel Colascione wrote @file{js.el}, a mode for -editing JavaScript. - -@item -Vinicius Jose Latorre wrote the Emacs printing facilities, as well as -@code{ps-print} (with Jim Thompson, Jacques Duthen, and Kenichi Handa), -a package for pretty-printing Emacs buffers to PostScript printers; -@file{delim-col.el}, a package to arrange text into columns; -@file{ebnf2ps.el}, a package that translates EBNF grammar to a syntactic -chart that can be printed to a PostScript printer; and -@file{whitespace.el}, a package that detects and cleans up excess -whitespace in a file (building on an earlier version by Rajesh Vaidheeswarran). - -@item -Frederic Lepied wrote @file{expand.el}, which uses the abbrev -mechanism for inserting programming constructs. - -@item -Peter Liljenberg wrote @file{elint.el}, a Lint-style code checker for -Emacs Lisp programs. - -@item -Lars Lindberg wrote @file{msb.el}, which provides more flexible menus -for buffer selection; co-wrote @file{imenu.el} (q.v.); and rewrote -@file{dabbrev.el}, originally written by Don Morrison. - -@item -Anders Lindgren wrote @file{autorevert.el}, a package for automatically -reverting files visited by Emacs that were changed on disk; -@file{cwarn.el}, a package to highlight suspicious C and C@t{++} -constructs; and @file{follow.el}, a minor mode to synchronize windows -that show the same buffer. - -@item -Thomas Link wrote @file{filesets.el}, a package for handling sets of -files. - -@item -Juri Linkov wrote @file{misearch.el}, extending isearch to multi-buffer -searches; the code in @file{files-x.el} for handling file- and -directory-local variables; and the @code{info-finder} feature that -creates a virtual Info manual of package keywords. - -@item -Leo Liu wrote @file{pcmpl-x.el}, providing completion for -miscellaneous external tools; and revamped support for Octave in Emacs 24.4. - -@item -Károly Lőrentey wrote the ``multi-terminal'' code, which allows -Emacs to run on graphical and text terminals simultaneously. - -@item -Martin Lorentzon wrote @file{vc-annotate.el}, support for version -control annotation. - -@item -Dave Love wrote much of the code dealing with Unicode support and -Latin-N unification. He added support for many coding systems, -including the various UTF-7 and UTF-16 coding systems. He also wrote -@code{autoarg-mode}, a global minor mode whereby digit keys supply -prefix arguments; @code{autoarg-kp-mode}, which redefines the keypad -numeric keys to digit arguments; @file{autoconf.el}, a mode for editing -Autoconf files; @file{cfengine.el}, a mode for editing Cfengine files; -@file{elide-head.el}, a package for eliding boilerplate text from file -headers; @file{hl-line.el}, a minor mode for highlighting the line in -the current window on which point is; @file{cap-words.el}, a minor mode -for motion in ``CapitalizedWordIdentifiers''; @file{latin1-disp.el}, a -package that lets you display ISO 8859 characters on Latin-1 terminals -by setting up appropriate display tables; the version of -@file{python.el} used prior to Emacs 24.3; @file{smiley.el}, a -facility for displaying smiley faces; @file{sym-comp.el}, a library -for performing mode-dependent symbol completion; @file{benchmark.el} -for timing code execution; and @file{tool-bar.el}, a mode to control -the display of the Emacs tool bar. With Riccardo Murri he wrote -@file{vc-bzr.el}, support for the Bazaar version control system. - -@item -Eric Ludlam wrote the Speedbar package; @file{checkdoc.el}, for checking -doc strings in Emacs Lisp programs; @file{dframe.el}, providing -dedicated frame support modes; @file{ezimage.el}, a generalized way to -place images over text; @file{chart.el} for drawing bar charts etc.; and -the EIEIO (Enhanced Implementation of Emacs Interpreted Objects) -package. He was also the main author of the CEDET (Collection of Emacs -Development Environment Tools) package. Portions were also written by -Jan Moringen, David Ponce, and Joakim Verona. - -@item -Roland McGrath wrote @file{compile.el} (since updated by Daniel -Pfeiffer), a package for running compilations in a buffer, and then -visiting the locations reported in error messages; @file{etags.el}, a -package for jumping to function definitions and searching or replacing -in all the files mentioned in a @file{TAGS} file; with Sebastian -Kremer @file{find-dired.el}, for using @code{dired} commands on output -from the @code{find} program; @file{grep.el} for running the -@code{grep} command; @file{map-ynp.el}, a general purpose boolean -question-asker; @file{autoload.el}, providing semi-automatic -maintenance of autoload files. - -@item -Alan Mackenzie wrote the integrated AWK support in CC Mode, and -maintained CC Mode from Emacs 22 onwards. - -@item -Michael McNamara and Wilson Snyder wrote Verilog mode. - -@item -Christopher J. Madsen wrote @file{decipher.el}, a package for cracking -simple substitution ciphers. - -@item -Neil M. Mager wrote @file{appt.el}, functions to notify users of their -appointments. It finds appointments recorded in the diary files -used by the @code{calendar} package. - -@item -Ken Manheimer wrote @file{allout.el}, a mode for manipulating and -formatting outlines, and @file{icomplete.el}, which provides incremental -completion feedback in the minibuffer. - -@item -Bill Mann wrote @file{perl-mode.el}, a mode for editing Perl code. - -@item -Brian Marick and Daniel LaLiberte wrote @file{hideif.el}, support for -hiding selected code within C @code{#ifdef} clauses. - -@item -Simon Marshall wrote @file{regexp-opt.el}, which generates a regular -expression from a list of strings; and the fast-lock and lazy-lock -font-lock support modes. He also extended @file{comint.el} and -@file{shell.el}, originally written by Olin Shivers. - -@item -Bengt Martensson, Dirk Herrmann, Marc Shapiro, Mike Newton, Aaron Larson, -and Stefan Schoef, wrote @file{bibtex.el}, a mode for editing Bib@TeX{} -bibliography files. - -@item -Charlie Martin wrote @file{autoinsert.el}, which provides automatic -mode-sensitive insertion of text into new files. - -@item -Yukihiro Matsumoto and Nobuyoshi Nakada wrote Ruby-mode. - -@item -Tomohiro Matsuyama wrote the native Elisp profiler. - -@item -Thomas May wrote @file{blackbox.el}, a version of the traditional -blackbox game. - -@item -David Megginson wrote @file{derived.el}, which allows one to define new -major modes by inheriting key bindings and commands from existing major -modes. - -@item -Will Mengarini wrote @file{repeat.el}, a command to repeat the preceding -command with its arguments. - -@item -Richard Mlynarik wrote @file{cl-indent.el}, a package for indenting -Common Lisp code; @file{ebuff-menu.el}, an ``electric'' browser for -buffer listings; @file{ehelp.el}, bindings for browsing help screens; -and @file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format, -used in mail messages and news articles. - -@item -Gerd Möllmann was the Emacs maintainer from the beginning of Emacs 21 -development until the release of 21.1. He wrote the new display -engine used from Emacs 21 onwards, and the asynchronous timers -facility. He also wrote @code{ebrowse}, the C@t{++} browser; -@file{jit-lock.el}, the Just-In-Time font-lock support mode; -@file{tooltip.el}, a package for displaying tooltips; -@file{authors.el}, a package for maintaining the @file{AUTHORS} file; -and @file{rx.el}, a regular expression constructor. - -@item -Stefan Monnier was the Emacs (co-)maintainer from Emacs 23 onwards. He added -support for Arch and Subversion to VC, re-wrote much of the Emacs server -to use the built-in networking primitives, and re-wrote the abbrev and -minibuffer completion code for Emacs 23. He also wrote @code{PCL-CVS}, -a directory-level front end to the CVS version control system; -@file{reveal.el}, a minor mode for automatically revealing invisible -text; @file{smerge-mode.el}, a minor mode for resolving @code{diff3} -conflicts; @file{diff-mode.el}, a mode for viewing and editing context -diffs; @file{css-mode.el} for Cascading Style Sheets; -@file{bibtex-style.el} for Bib@TeX{} Style files; @file{mpc.el}, a -client for the ``Music Player Daemon''; @file{smie.el}, a generic -indentation engine; and @file{pcase.el}, implementing ML-style pattern -matching. In Emacs 24, he integrated the lexical binding code, -cleaned up the CL namespace (making it acceptable to use CL -functions at runtime), added generalized variables to core Emacs -Lisp, and implemented a new lightweight advice mechanism. - -@item -Morioka Tomohiko wrote several packages for MIME support in Gnus and -elsewhere. - -@item -Sen Nagata wrote @file{crm.el}, a package for reading multiple strings -with completion, and @file{rfc2368.el}, support for @code{mailto:} -URLs. - -@item -Erik Naggum wrote the time-conversion functions. He also wrote -@file{disp-table.el}, for dealing with display tables; -@file{mailheader.el}, for parsing email headers; and -@file{parse-time.el}, for parsing time strings. - -@item -Takahashi Naoto co-wrote @file{quail.el} (q.v.), and wrote -@file{robin.el}, another input method. - -@item -Thomas Neumann and Eric Raymond wrote @file{make-mode.el}, -a mode for editing makefiles. - -@item -Thien-Thi Nguyen and Dan Nicolaescu wrote @file{hideshow.el}, a minor -mode for selectively displaying blocks of text. - -@item -Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation. - -@item -Dan Nicolaescu added support for running Emacs as a daemon. He also -wrote @file{romanian.el}, support for editing Romanian text; -@file{iris-ansi.el}, support for running Emacs on SGI's @code{xwsh} -and @code{winterm} terminal emulators; and @file{vc-dir.el}, displaying -the status of version-controlled directories. - -@item -Hrvoje Nikšić wrote @file{savehist.el}, for saving the minibuffer -history between Emacs sessions. - -@item -Jeff Norden wrote @file{kermit.el}, a package to help the Kermit -dialup communications program run comfortably in an Emacs shell buffer. - -@item -Andrew Norman wrote @file{ange-ftp.el}, providing transparent FTP -support. - -@item -Kentaro Ohkouchi created the Emacs icons used beginning with Emacs 23. - -@item -Christian Ohler wrote @file{ert.el}, a library for automated regression -testing. - -@item -Alexandre Oliva wrote @file{gnus-mlspl.el}, a group params-based mail -splitting mechanism. - -@item -Takaaki Ota wrote @file{table.el}, a package for creating and editing -embedded text-based tables. - -@item -Pieter E. J. Pareit wrote @file{mixal-mode.el}, an editing mode for -the MIX assembly language. - -@item -David Pearson wrote @file{quickurl.el}, a simple method of inserting a -URL into the current buffer based on text at point; @file{5x5.el}, a -game to fill all squares on the field. - -@item -Jeff Peck wrote @file{sun.el}, key bindings for sunterm keys. - -@item -Damon Anton Permezel wrote @file{hanoi.el}, an animated demonstration of -the ``Towers of Hanoi'' puzzle. - -@item -William M. Perry wrote @file{mailcap.el} (with Lars Magne -Ingebrigtsen), a MIME media types configuration facility; -@file{mwheel.el}, a package for supporting mouse wheels; co-wrote (with -Dave Love) @file{socks.el}, a Socks v5 client; and developed the URL -package. - -@item -Per Persson wrote @file{gnus-vm.el}, the VM interface for Gnus. - -@item -Jens Petersen wrote @file{find-func.el}, which makes it easy to find -the source code for an Emacs Lisp function or variable. - -@item -Daniel Pfeiffer wrote @file{conf-mode.el}, a mode for editing -configuration files; @file{copyright.el}, a package for updating -copyright notices in files; @file{executable.el}, a package for -executing interpreter scripts; @file{sh-script.el}, a mode for editing -shell scripts; @file{skeleton.el}, implementing a concise language for -writing statement skeletons; and @file{two-column.el}, a minor mode -for simultaneous two-column editing. - -Daniel also rewrote @file{apropos.el} (originally written by Joe Wells), -for finding commands, functions, and variables matching a regular -expression; and, together with Jim Blandy, co-authored @file{wyse50.el}, -support for Wyse 50 terminals. He also co-wrote @file{compile.el} -(q.v.@:) and @file{ada-stmt.el}. - -@item -Richard L. Pieri wrote @file{pop3.el}, a Post Office Protocol (RFC -1460) interface for Emacs. - -@item -Fred Pierresteguy and Paul Reilly made Emacs work with X Toolkit -widgets. - -@item -François Pinard, Greg McGary, and Bruno Haible wrote @file{po.el}, -support for PO translation files. - -@item -Christian Plaunt wrote @file{soundex.el}, an implementation of the -Soundex algorithm for comparing English words by their pronunciation. - -@item -David Ponce wrote @file{recentf.el}, a package that puts a menu of -recently visited files in the Emacs menu bar; @file{ruler-mode.el}, a -minor mode for displaying a ruler in the header line; and -@file{tree-widget.el}, a package to display hierarchical data -structures. - -@item -Francesco A. Potortì wrote @file{cmacexp.el}, providing a command which -runs the C preprocessor on a region of a file and displays the results. -He also expanded and redesigned the @code{etags} program. - -@item -Michael D. Prange and Steven A. Wood wrote @file{fortran.el}, a mode -for editing Fortran code. - -@item -Ashwin Ram wrote @file{refer.el}, commands to look up references in -bibliography files by keyword. - -@item -Eric S. Raymond wrote @file{vc.el}, an interface to the RCS and SCCS -source code version control systems, with Paul Eggert; @file{gud.el}, -a package for running source-level debuggers like GDB and SDB in -Emacs; @file{asm-mode.el}, a mode for editing assembly language code; -@file{AT386.el}, terminal support package for IBM's AT keyboards; -@file{cookie1.el}, support for ``fortune-cookie'' programs like -@file{yow.el} and @file{spook.el}; @file{finder.el}, a package for -finding Emacs Lisp packages by keyword and topic; @file{keyswap.el}, -code to swap the @key{BS} and @key{DEL} keys; @file{loadhist.el}, -functions for loading and unloading Emacs features; -@file{lisp-mnt.el}, functions for working with the special headers -used in Emacs Lisp library files; and code to set and make use of the -@code{load-history} lisp variable, which records the source file from -which each lisp function loaded into Emacs came. - -@item -Edward M. Reingold wrote the calendar and diary support, -with contributions from Stewart Clamen (@file{cal-mayan.el}), Nachum -Dershowitz (@file{cal-hebrew.el}), Paul Eggert (@file{cal-dst.el}), -Steve Fisk (@file{cal-tex.el}), Michael Kifer (@file{cal-x.el}), Lara -Rios (@file{cal-menu.el}), and Denis B. Roegel (@file{solar.el}). -Andy Oram contributed to its documentation. Reingold also contributed -to @file{tex-mode.el}, a mode for editing @TeX{} files, as did William -F. Schelter, Dick King, Stephen Gildea, Michael Prange, and Jacob -Gore. - -@item -David Reitter wrote @file{mailclient.el} which can send mail via the -system's designated mail client. - -@item -Alex Rezinsky wrote @file{which-func.el}, a mode that shows the name -of the current function in the mode line. - -@item -Rob Riepel wrote @file{tpu-edt.el} and its associated files, providing -an emulation of the VMS TPU text editor emulating the VMS EDT editor, -and @file{vt-control.el}, providing some control functions for the DEC -VT line of terminals. - -@item -Nick Roberts wrote @file{t-mouse.el}, for mouse support in text -terminals; and @file{gdb-ui.el}, a graphical user interface to GDB@. -Together with Dmitry Dzhus, he wrote @file{gdb-mi.el}, the successor to -@file{gdb-ui.el}. - -@item -Danny Roozendaal implemented @file{handwrite.el}, which converts text -into ``handwriting''. - -@item -Markus Rost wrote @file{cus-test.el}, a testing framework for customize. - -@item -Guillermo J. Rozas wrote @file{scheme.el}, a mode for editing Scheme and -DSSSL code. - -@item -Martin Rudalics implemented improved display-buffer handling in Emacs 24; -and implemented ``pixel-wise'' resizing of windows and frames. - -@item -Ivar Rummelhoff wrote @file{winner.el}, which records recent window -configurations so you can move back to them. - -@item -Jason Rumney ported the Emacs 21 display engine to MS-Windows, and has -contributed extensively to the MS-Windows port of Emacs. - -@item -Wolfgang Rupprecht wrote Emacs 19's floating-point support (including -@file{float-sup.el} and @file{floatfns.c}). - -@item -Kevin Ryde wrote @file{info-xref.el}, a library for checking -references in Info files. - -@item -James B. Salem and Brewster Kahle wrote @file{completion.el}, providing -dynamic word completion. - -@item -Masahiko Sato wrote @file{vip.el}, an emulation of the VI editor. - -@item -Holger Schauer wrote @file{fortune.el}, a package for using fortune in -message signatures. - -@item -William Schelter wrote @file{telnet.el}, support for @code{telnet} -sessions within Emacs. - -@item -Ralph Schleicher wrote @file{battery.el}, a package for displaying -laptop computer battery status, and @file{info-look.el}, a package for -looking up Info documentation for symbols in the buffer. - -@item -Michael Schmidt and Tom Perrine wrote @file{modula2.el}, a mode for -editing Modula-2 code, based on work by Mick Jordan and Peter Robinson. - -@item -Ronald S. Schnell wrote @file{dunnet.el}, a text adventure game. - -@item -Philippe Schnoebelen wrote @file{gomoku.el}, a Go Moku game played -against Emacs; and @file{mpuz.el}, a multiplication puzzle. - -@item -Jan Schormann wrote @file{solitaire.el}, an implementation of the -Solitaire game. - -@item -Alex Schroeder wrote @file{ansi-color.el}, a package for translating -ANSI color escape sequences to Emacs faces; @file{sql.el}, a package -for interactively running an SQL interpreter in an Emacs buffer; -@file{cus-theme.el}, an interface for custom themes; @file{master.el}, a -package for making a buffer @samp{master} over another; and -@file{spam-stat.el}, for statistical detection of junk email. He also -wrote parts of the IRC client ERC (q.v.). - -@item -Randal Schwartz wrote @file{pp.el}, a pretty-printer for lisp objects. - -@item -Manuel Serrano wrote the Flyspell package, which does spell checking -as you type. - -@item -Hovav Shacham wrote @file{windmove.el}, a set of commands for selecting -windows based on their geometrical position on the frame. - -@item -Stanislav Shalunov wrote @file{uce.el}, for responding to unsolicited -commercial email. - -@item -Richard Sharman wrote @file{hilit-chg.el}, which uses colors to show -recent editing changes. - -@item -Olin Shivers wrote @file{comint.el}, a library for modes running -interactive command-line-oriented subprocesses, and @file{shell.el}, for -running inferior shells (both since extended by Simon Marshall); -@file{cmuscheme.el}, for running inferior Scheme processes; -@file{inf-lisp.el}, for running inferior Lisp process. - -@item -Espen Skoglund wrote @file{pascal.el}, a mode for editing Pascal code. - -@item -Rick Sladkey wrote @file{backquote.el}, a lisp macro for creating -mostly-constant data. - -@item -Lynn Slater wrote @file{help-macro.el}, a macro for writing interactive -help for key bindings. - -@item -Chris Smith wrote @file{icon.el}, a mode for editing Icon code. - -@item -David Smith wrote @file{ielm.el}, a mode for interacting with the Emacs -Lisp interpreter as a subprocess. - -@item -Paul D. Smith wrote @file{snmp-mode.el}. - -@item -William Sommerfeld wrote @file{scribe.el}, a mode for editing Scribe -files, and @file{server.el}, a package allowing programs to send files -to an extant Emacs job to be edited. - -@item -Andre Spiegel made many contributions to the Emacs Version Control -package, and in particular made it support multiple back ends. - -@item -Michael Staats wrote @file{pc-select.el}, which rebinds keys for -selecting regions to follow many other systems. - -@item -Richard Stallman invented Emacs. He is the original author of GNU -Emacs, and has been Emacs maintainer over several non-contiguous -periods. In addition to much of the ``core'' Emacs code, he has -written @file{easymenu.el}, a facility for defining Emacs menus; -@file{image-mode.el}, support for visiting image files; -@file{menu-bar.el}, the Emacs menu bar support code; -@file{paren.el}, a package to make matching parentheses stand out in -color; and also co-authored portions of CC mode. - -@item -Sam Steingold wrote @file{gulp.el}, a facility for asking package -maintainers for updated versions of their packages via e-mail, and -@file{midnight.el}, a package for running a command every midnight. - -@item -Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for -browsing indices made from buffer contents. - -@item -Peter Stephenson wrote @file{vcursor.el}, which implements a ``virtual -cursor'' that you can move with the keyboard and use for copying text. - -@item -Ken Stevens wrote @file{ispell.el}, a spell-checker interface. - -@item -Kim F. Storm made many improvements to the Emacs display engine, -process support, and networking support. He also wrote -@file{bindat.el}, a package for encoding and decoding binary data; -CUA mode, which allows Emacs to emulate the standard CUA key -bindings; @file{ido.el}, a package for selecting buffers and files -quickly; @file{keypad.el} for simplified keypad bindings; and -@file{kmacro.el}, the keyboard macro facility. - -@item -Martin Stjernholm co-authored CC Mode, a major editing mode for C, -C@t{++}, Objective-C, Java, Pike, CORBA IDL, and AWK code. - -@item -Steve Strassmann did not write @file{spook.el}, and even if he did, he -really didn't mean for you to use it in an anarchistic way. - -@item -Olaf Sylvester wrote @file{bs.el}, a package for manipulating Emacs -buffers. - -@item -Tibor Šimko and Milan Zamazal wrote @file{slovak.el}, support for -editing text in Slovak language. - -@item -Luc Teirlinck wrote @file{help-at-pt.el}, providing local help through -the keyboard. - -@item -Jean-Philippe Theberge wrote @file{thumbs.el}, a package for viewing -image files as ``thumbnails''. - -@item -Spencer Thomas wrote the original @file{dabbrev.el}, providing a command -which completes the partial word before point, based on other nearby -words for which it is a prefix. He also wrote the original dumping -support. - -@item -Toru Tomabechi contributed to Tibetan support. - -@item -Markus Triska wrote @file{linum.el}, a minor mode that displays line -numbers in the left margin. - -@item -Tom Tromey and Chris Lindblad wrote @file{tcl.el}, a mode for editing -Tcl/Tk source files and running a Tcl interpreter as an Emacs -subprocess. Tom Tromey also wrote @file{bug-reference.el}, providing -clickable links to bug reports; and the first version of the Emacs -package system. - -@item -Eli Tziperman wrote @file{rmail-spam-filter.el}, a spam filter for RMAIL. - -@item -Daiki Ueno wrote @file{starttls.el}, support for Transport Layer -Security protocol; @file{sasl-cram.el} and @file{sasl-digest.el} (with -Kenichi Okada), and @file{sasl.el}, support for Simple Authentication -and Security Layer (SASL); @file{plstore.el} for secure storage of -property lists; and the EasyPG (and its predecessor PGG) -package, for GnuPG and PGP support. - -@item -Masanobu Umeda wrote GNUS, a feature-rich reader for Usenet news that -was the ancestor of the current Gnus package. He also wrote -@file{rmailsort.el}, a package for sorting messages in RMAIL folders; -@file{metamail.el}, an interface to the Metamail program; -@file{gnus-kill.el}, the Kill File mode for Gnus; @file{gnus-mh.el}, an -mh-e interface for Gnus; @file{gnus-msg.el}, a mail and post interface -for Gnus; and @file{timezone.el}, providing functions for dealing with -time zones. - -@item -Neil W. Van Dyke wrote @file{webjump.el}, a ``hot links'' package. - -@item -Didier Verna wrote @file{rect.el}, a package of functions for -operations on rectangle regions of text. He also contributed to Gnus -(q.v.). - -@item -Joakim Verona implemented ImageMagick support. - -@item -Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code. - -@item -Geoffrey Voelker wrote the Windows NT support. He also wrote -@file{dos-w32.el}, functions shared by the MS-DOS and MS-Windows ports -of Emacs, and @file{w32-fns.el}, MS-Windows specific support functions. - -@item -Johan Vromans wrote @file{forms.el} and its associated files, a mode for -filling in forms. He also wrote @file{iso-acc.el}, a minor mode -providing electric accent keys. - -@item -Colin Walters wrote Ibuffer, an enhanced buffer menu. - -@item -Barry Warsaw wrote @file{cc-mode.el}, a mode for editing C, C@t{++}, -and Java code, based on earlier work by Dave Detlefs, Stewart Clamen, -and Richard Stallman; @file{elp.el}, a profiler for Emacs Lisp -programs; @file{man.el}, a mode for reading Unix manual pages; -@file{regi.el}, providing an AWK-like functionality for use in lisp -programs; @file{reporter.el}, providing customizable bug reporting for -lisp packages; and @file{supercite.el}, a minor mode for quoting -sections of mail messages and news articles. - -@item -Christoph Wedler wrote @file{antlr-mode.el}, a major mode for ANTLR -grammar files. - -@item -Morten Welinder helped port Emacs to MS-DOS, and introduced face -support into the MS-DOS port of Emacs. He also wrote -@file{desktop.el}, facilities for saving some of Emacs's state between -sessions; @file{timer.el}, the Emacs facility to run commands at a -given time or frequency, or when Emacs is idle, and its C-level -support code; @file{pc-win.el}, the MS-DOS ``window-system'' support; -@file{internal.el}, an ``internal terminal'' emulator for the MS-DOS -port of Emacs; @file{arc-mode.el}, the mode for editing compressed -archives; @file{s-region.el}, commands for setting the region using -the shift key and motion commands; and @file{dos-fns.el}, functions -for use under MS-DOS. - -@item -Joe Wells wrote the original version of @file{apropos.el} (q.v.); -@file{resume.el}, support for processing command-line arguments after -resuming a suspended Emacs job; and @file{mail-extr.el}, a package for -extracting names and addresses from mail headers, with contributions -from Jamie Zawinski. - -@item -Rodney Whitby and Reto Zimmermann wrote @file{vhdl-mode.el}, a major -mode for editing VHDL source code. - -@item -John Wiegley wrote @file{align.el}, a set of commands for aligning text -according to regular-expression based rules; @file{isearchb.el} for fast -buffer switching; @file{timeclock.el}, a package for keeping track of -time spent on projects; the Bahá'í calendar support; -@file{pcomplete.el}, a programmable completion facility; -@file{remember.el}, a mode for jotting down things to remember; -@file{eudcb-mab.el}, an address book backend for the Emacs Unified -Directory Client; and @code{eshell}, a command shell implemented -entirely in Emacs Lisp. He also contributed to Org mode (q.v.). - -@item -Mike Williams wrote @file{thingatpt.el}, a library of functions for -finding the ``thing'' (word, line, s-expression) at point. - -@item -Roland Winkler wrote @file{proced.el}, a system process editor. - -@item -Bill Wohler wrote MH-E, the Emacs interface to the MH mail system; -making use of earlier work by James R. Larus. Satyaki Das, Peter S. -Galbraith, Stephen Gildea, and Jeffrey C. Honig also wrote various -MH-E components. - -@item -Dale R. Worley wrote @file{emerge.el}, a package for interactively -merging two versions of a file. - -@item -Francis J. Wright wrote @file{woman.el}, a package for browsing -manual pages without the @code{man} command. - -@item -Masatake Yamato wrote @file{ld-script.el}, an editing mode for GNU -linker scripts, and contributed subword handling and style -``guessing'' in CC mode. - -@item -Jonathan Yavner wrote @file{testcover.el}, a package for keeping track -of the testing status of Emacs Lisp code; @file{unsafep.el} to determine -if a Lisp form is safe; and the SES spreadsheet package. - -@item -Ryan Yeske wrote @file{rcirc.el} a simple Internet Relay Chat client. - -@item -Ilya Zakharevich and Bob Olson wrote @file{cperl-mode.el}, a major -mode for editing Perl code. Ilya Zakharevich also wrote -@file{tmm.el}, a mode for accessing the Emacs menu bar on a text-mode -terminal. - -@item -Milan Zamazal wrote @file{czech.el}, support for editing Czech text; -@file{glasses.el}, a package for easier reading of source code that -uses illegible identifier names; and @file{tildify.el}, commands for -adding hard spaces to text, @TeX{}, and SGML/HTML files. - -@item -Victor Zandy wrote @file{zone.el}, a package for people who like to -zone out in front of Emacs. - -@item -Eli Zaretskii made many standard Emacs features work on MS-DOS and -Microsoft Windows. He also wrote @file{tty-colors.el}, which -implements transparent mapping of X colors to tty colors; and -@file{rxvt.el}. He implemented support for bidirectional text, -and also menus on text-mode terminals. - -@item -Jamie Zawinski wrote much of the support for faces and X selections. -With Hallvard Furuseth, he wrote the optimizing byte compiler used -from Emacs 19 onwards. He also wrote @file{mailabbrev.el}, a package -that provides automatic expansion of mail aliases, and -@file{tar-mode.el}, which provides simple viewing and editing commands -for tar files. - -@item -Andrew Zhilin created the Emacs 22 icons. - -@item -Shenghuo Zhu wrote @file{binhex.el}, a package for reading and writing -binhex files; @file{mm-partial.el}, message/partial support for MIME -messages; @file{rfc1843.el}, an HZ decoding package; -@file{uudecode.el}, an Emacs Lisp decoder for uuencoded data; and -@file{webmail.el}, an interface to Web mail. He also wrote several -other Gnus components. - -@item -Ian T. Zimmerman wrote @file{gametree.el}. - -@item -Reto Zimmermann wrote @file{vera-mode.el}. - -@item -Neal Ziring and Felix S. T. Wu wrote @file{vi.el}, an emulation of the -VI text editor. - -@item -Ted Zlatanov (as well as his contributions to the Gnus newsreader) -wrote an interface to the GnuTLS library, for secure network -connections; and a futures facility for the URL library. - -@item -Detlev Zundel wrote @file{re-builder.el}, a package for building regexps -with visual feedback. - -@end itemize diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi deleted file mode 100644 index d0de90690a7..00000000000 --- a/doc/emacs/anti.texi +++ /dev/null @@ -1,113 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2005-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. - -@node Antinews -@appendix Emacs 23 Antinews -@c Update the emacs.texi Antinews menu entry with the above version number. - - For those users who live backwards in time, here is information -about downgrading to Emacs version 23.4. We hope you will enjoy the -greater simplicity that results from the absence of many Emacs -@value{EMACSVER} features. - -@itemize @bullet -@item -Support for displaying and editing ``bidirectional'' text has been -removed. Text is now always displayed on the screen in a single -consistent direction---left to right---regardless of the underlying -script. Similarly, @kbd{C-f} and @kbd{C-b} always move the text -cursor to the right and left respectively. Also, @key{RIGHT} and -@key{LEFT} are now equivalent to @kbd{C-f} and @kbd{C-b}, as you might -expect, rather than moving forward or backward based on the underlying -``paragraph direction''. - -Users of ``right-to-left'' languages, like Arabic and Hebrew, may -adapt by reading and/or editing text in left-to-right order. - -@item -The Emacs Lisp package manager has been removed. Instead of using a -``user interface'' (@kbd{M-x list-packages}), additional Lisp packages -must now be installed by hand, which is the most flexible and -``Lispy'' method anyway. Typically, this just involves editing your -init file to add the package installation directory to the load path -and defining some autoloads; see each package's commentary section -and/or README file for details. - -@item -The option @code{delete-active-region} has been deleted. When the -region is active, typing @key{DEL} or @key{Delete} no longer deletes -the text in the region; it deletes a single character instead. - -@item -We have reworked how Emacs handles the clipboard and the X primary -selection. Commands for killing and yanking, like @kbd{C-w} and -@kbd{C-y}, use the primary selection and not the clipboard, so you can -use these commands without interfering with ``cutting'' or ``pasting'' -in other programs. The @samp{Cut}/@samp{Copy}/@samp{Paste} menu items -are bound to separate clipboard commands, not to the same commands as -@kbd{C-w}/@kbd{M-w}/@kbd{C-y}. - -Selecting text by dragging with the mouse now puts the text in the -kill ring, in addition to the primary selection. But note that -selecting an active region with @kbd{C-@key{SPC}} does @emph{not} -alter the kill ring nor the primary selection, even though the text -highlighting is visually identical. - -@item -In Isearch, @kbd{C-y} and @kbd{M-y} are no longer bound to -@code{isearch-yank-kill} and @code{isearch-yank-pop} respectively. -Instead, @kbd{C-y} yanks the rest of the current line into the search -string (@code{isearch-yank-line}), whereas @kbd{M-y} does -@code{isearch-yank-kill}. The mismatch with the usual meanings of -@kbd{C-y} and @kbd{M-y} is unintended. - -@item -Various completion features have been simplified. The option -@code{completion-category-overrides} has been removed, so Emacs uses a -single consistent scheme to generate completions, instead of using a -separate scheme for (say) buffer name completion. Several major -modes, such as Shell mode, now implement their own inline completion -commands instead of using @code{completion-at-point}. - -@item -We have removed several options for controlling how windows are used, -such as @code{display-buffer-base-action}, -@code{display-buffer-alist}, @code{window-combination-limit}, and -@code{window-combination-resize}. - -@item -The command @kbd{M-x customize-themes} has been removed. Emacs no -longer comes with pre-defined themes (you can write your own). - -@item -Emacs no longer adapts various aspects of its display to GTK+ -settings, opting instead for a uniform toolkit-independent look. GTK+ -scroll bars are placed on the left, the same position as non-GTK+ X -scroll bars. Emacs no longer refers to GTK+ to set the default -@code{region} face, nor for drawing tooltips. - -@item -Setting the option @code{delete-by-moving-to-trash} to a -non-@code{nil} value now causes all file deletions to use the system trash, -even temporary files created by Lisp programs; furthermore, the -@kbd{M-x delete-file} and @kbd{M-x delete-directory} commands no -longer accept prefix arguments to force true deletion. - -@item -On GNU/Linux and Unix, the default method for sending mail (as -specified by @code{send-mail-function}) is to use the -@command{sendmail} program. Emacs no longer asks for a delivery -method the first time you try to send mail, trusting instead that the -system is configured for mail delivery, as it ought to be. - -@item -Several VC features have been removed, including the @kbd{C-x v +} and -@kbd{C-x v m} commands for pulling and merging on distributed version -control systems, and the ability to view inline log entries in the log -buffers made by @kbd{C-x v L}. - -@item -To keep up with decreasing computer memory capacity and disk space, many -other functions and files have been eliminated in Emacs 23.4. -@end itemize diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi deleted file mode 100644 index dcb73bc96de..00000000000 --- a/doc/emacs/arevert-xtra.texi +++ /dev/null @@ -1,189 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Autorevert -@section Auto Reverting Non-File Buffers - -Global Auto Revert Mode normally only reverts file buffers. There are -two ways to auto-revert certain non-file buffers: by enabling Auto -Revert Mode in those buffers (using @kbd{M-x auto-revert-mode}); and -by setting @code{global-auto-revert-non-file-buffers} to a -non-@code{nil} value. The latter enables Auto Reverting for all types -of buffers for which it is implemented (listed in the menu below). - -Like file buffers, non-file buffers should normally not revert while -you are working on them, or while they contain information that might -get lost after reverting. Therefore, they do not revert if they are -``modified''. This can get tricky, because deciding when a non-file -buffer should be marked modified is usually more difficult than for -file buffers. - -Another tricky detail is that, for efficiency reasons, Auto Revert -often does not try to detect all possible changes in the buffer, only -changes that are ``major'' or easy to detect. Hence, enabling -auto-reverting for a non-file buffer does not always guarantee that -all information in the buffer is up-to-date, and does not necessarily -make manual reverts useless. - -At the other extreme, certain buffers automatically revert every -@code{auto-revert-interval} seconds. (This currently only applies to -the Buffer Menu.) In this case, Auto Revert does not print any -messages while reverting, even when @code{auto-revert-verbose} is -non-@code{nil}. - -The details depend on the particular types of buffers and are -explained in the corresponding sections. - -@menu -* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. -* Auto Reverting Dired:: Auto Revert of Dired buffers. -* Supporting additional buffers:: How to add more Auto Revert support. -@end menu - -@node Auto Reverting the Buffer Menu -@subsection Auto Reverting the Buffer Menu - -If auto-reverting of non-file buffers is enabled, the Buffer Menu -automatically reverts every @code{auto-revert-interval} seconds, -whether there is a need for it or not. (It would probably take longer -to check whether there is a need than to actually revert.) - -If the Buffer Menu inappropriately gets marked modified, just revert -it manually using @kbd{g} and auto-reverting will resume. However, if -you marked certain buffers to get deleted or to be displayed, you have -to be careful, because reverting erases all marks. The fact that -adding marks sets the buffer's modified flag prevents Auto Revert from -automatically erasing the marks. - -@node Auto Reverting Dired -@subsection Auto Reverting Dired buffers - -Auto-reverting Dired buffers currently works on GNU or Unix style -operating systems. It may not work satisfactorily on some other -systems. - -Dired buffers only auto-revert when the file list of the buffer's main -directory changes (e.g., when a new file is added). They do not -auto-revert when information about a particular file changes -(e.g., when the size changes) or when inserted subdirectories change. -To be sure that @emph{all} listed information is up to date, you have -to manually revert using @kbd{g}, @emph{even} if auto-reverting is -enabled in the Dired buffer. Sometimes, you might get the impression -that modifying or saving files listed in the main directory actually -does cause auto-reverting. This is because making changes to a file, -or saving it, very often causes changes in the directory itself; for -instance, through backup files or auto-save files. However, this is -not guaranteed. - -If the Dired buffer is marked modified and there are no changes you -want to protect, then most of the time you can make auto-reverting -resume by manually reverting the buffer using @kbd{g}. There is one -exception. If you flag or mark files, you can safely revert the -buffer. This will not erase the flags or marks (unless the marked -file has been deleted, of course). However, the buffer will stay -modified, even after reverting, and auto-reverting will not resume. -This is because, if you flag or mark files, you may be working on the -buffer and you might not want the buffer to change without warning. -If you want auto-reverting to resume in the presence of marks and -flags, mark the buffer non-modified using @kbd{M-~}. However, adding, -deleting or changing marks or flags will mark it modified again. - -Remote Dired buffers are not auto-reverted (because it may be slow). -Neither are Dired buffers for which you used shell wildcards or file -arguments to list only some of the files. @file{*Find*} and -@file{*Locate*} buffers do not auto-revert either. - -@c FIXME? This should be in the elisp manual? -@node Supporting additional buffers -@subsection Adding Support for Auto-Reverting additional Buffers. - -This section is intended for Elisp programmers who would like to add -support for auto-reverting new types of buffers. - -To support auto-reverting the buffer must first of all have a suitable -@code{revert-buffer-function}. @xref{Definition of -revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. - -In addition, it must have a suitable @code{buffer-stale-function}. - -@c FIXME only defvar in all of doc/emacs! -@defvar buffer-stale-function -The value of this variable is a function to check whether a -buffer needs reverting. This should be a function with one optional -argument @var{noconfirm}. The function should return non-@code{nil} -if the buffer should be reverted. The buffer is current when this -function is called. - -While this function is mainly intended for use in auto-reverting, it -could be used for other purposes as well. For instance, if -auto-reverting is not enabled, it could be used to warn the user that -the buffer needs reverting. The idea behind the @var{noconfirm} -argument is that it should be @code{t} if the buffer is going to be -reverted without asking the user and @code{nil} if the function is -just going to be used to warn the user that the buffer is out of date. -In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. -If the function is only going to be used for auto-reverting, you can -ignore the @var{noconfirm} argument. - -If you just want to automatically auto-revert every -@code{auto-revert-interval} seconds (like the Buffer Menu), use: - -@example -(setq-local buffer-stale-function - #'(lambda (&optional noconfirm) 'fast)) -@end example - -@noindent -in the buffer's mode function. - -The special return value @samp{fast} tells the caller that the need -for reverting was not checked, but that reverting the buffer is fast. -It also tells Auto Revert not to print any revert messages, even if -@code{auto-revert-verbose} is non-@code{nil}. This is important, as -getting revert messages every @code{auto-revert-interval} seconds can -be very annoying. The information provided by this return value could -also be useful if the function is consulted for purposes other than -auto-reverting. -@end defvar - -Once the buffer has a suitable @code{revert-buffer-function} and -@code{buffer-stale-function}, several problems usually remain. - -The buffer will only auto-revert if it is marked unmodified. Hence, -you will have to make sure that various functions mark the buffer -modified if and only if either the buffer contains information that -might be lost by reverting, or there is reason to believe that the user -might be inconvenienced by auto-reverting, because he is actively -working on the buffer. The user can always override this by manually -adjusting the modified status of the buffer. To support this, calling -the @code{revert-buffer-function} on a buffer that is marked -unmodified should always keep the buffer marked unmodified. - -It is important to assure that point does not continuously jump around -as a consequence of auto-reverting. Of course, moving point might be -inevitable if the buffer radically changes. - -You should make sure that the @code{revert-buffer-function} does not -print messages that unnecessarily duplicate Auto Revert's own messages, -displayed if @code{auto-revert-verbose} is @code{t}, and effectively -override a @code{nil} value for @code{auto-revert-verbose}. Hence, -adapting a mode for auto-reverting often involves getting rid of such -messages. This is especially important for buffers that automatically -revert every @code{auto-revert-interval} seconds. - -If the new auto-reverting is part of Emacs, you should mention it -in the documentation string of @code{global-auto-revert-non-file-buffers}. - -@ifinfo -Similarly, you should add a node to this chapter's menu. This node -@end ifinfo -@ifnotinfo -Similarly, you should add a section to this chapter. This section -@end ifnotinfo -should at the very least make clear whether enabling auto-reverting -for the buffer reliably assures that all information in the buffer is -completely up to date (or will be after @code{auto-revert-interval} -seconds). diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi deleted file mode 100644 index bec7774f2a9..00000000000 --- a/doc/emacs/basic.texi +++ /dev/null @@ -1,827 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Basic -@chapter Basic Editing Commands - -@kindex C-h t -@findex help-with-tutorial - Here we explain the basics of how to enter text, make corrections, -and save the text in a file. If this material is new to you, we -suggest you first run the Emacs learn-by-doing tutorial, by typing -@kbd{C-h t} (@code{help-with-tutorial}). - -@menu - -* Inserting Text:: Inserting text by simply typing it. -* Moving Point:: Moving the cursor to the place where you want to - change something. -* Erasing:: Deleting and killing text. -* Basic Undo:: Undoing recent changes in the text. -* Files: Basic Files. Visiting, creating, and saving files. -* Help: Basic Help. Asking what a character does. -* Blank Lines:: Making and deleting blank lines. -* Continuation Lines:: How Emacs displays lines too wide for the screen. -* Position Info:: What line, row, or column is point on? -* Arguments:: Numeric arguments for repeating a command N times. -* Repeating:: Repeating the previous command quickly. -@end menu - -@node Inserting Text -@section Inserting Text - -@cindex insertion -@cindex graphic characters - You can insert an ordinary @dfn{graphic character} (e.g., @samp{a}, -@samp{B}, @samp{3}, and @samp{=}) by typing the associated key. This -adds the character to the buffer at point. Insertion moves point -forward, so that point remains just after the inserted text. -@xref{Point}. - -@kindex RET -@kindex C-j -@cindex newline -@c @findex electric-indent-just-newline - To end a line and start a new one, type @key{RET} (@code{newline}). -(The @key{RET} key may be labeled @key{Return} or @key{Enter} on your -keyboard, but we refer to it as @key{RET} in this manual.) This -command inserts a newline character into the buffer, then indents -(@pxref{Indentation}) according to the major mode. If point is at the end -of the line, the effect is to create a new blank line after it and -indent the new line; if point is in the middle of a line, the line is -split at that position. To turn off the auto-indentation, you can -either disable Electric Indent mode (@pxref{Indent Convenience}) or -type @kbd{C-j}, which inserts just a newline, without any -auto-indentation. - - As we explain later in this manual, you can change the way Emacs -handles text insertion by turning on @dfn{minor modes}. For instance, -the minor mode called Auto Fill mode splits lines automatically when -they get too long (@pxref{Filling}). The minor mode called Overwrite -mode causes inserted characters to replace (overwrite) existing text, -instead of shoving it to the right. @xref{Minor Modes}. - -@cindex quoting -@kindex C-q -@findex quoted-insert - Only graphic characters can be inserted by typing the associated -key; other keys act as editing commands and do not insert themselves. -For instance, @key{DEL} runs the command @code{delete-backward-char} -by default (some modes bind it to a different command); it does not -insert a literal @samp{DEL} character (@acronym{ASCII} character code -127). - - To insert a non-graphic character, or a character that your keyboard -does not support, first @dfn{quote} it by typing @kbd{C-q} -(@code{quoted-insert}). There are two ways to use @kbd{C-q}: - -@itemize @bullet -@item -@kbd{C-q} followed by any non-graphic character (even @kbd{C-g}) -inserts that character. For instance, @kbd{C-q @key{DEL}} inserts a -literal @samp{DEL} character. - -@item -@kbd{C-q} followed by a sequence of octal digits inserts the character -with the specified octal character code. You can use any number of -octal digits; any non-digit terminates the sequence. If the -terminating character is @key{RET}, that @key{RET} serves only to -terminate the sequence. Any other non-digit terminates the sequence -and then acts as normal input---thus, @kbd{C-q 1 0 1 B} inserts -@samp{AB}. - -The use of octal sequences is disabled in ordinary non-binary -Overwrite mode, to give you a convenient way to insert a digit instead -of overwriting with it. -@end itemize - -@vindex read-quoted-char-radix -@noindent -To use decimal or hexadecimal instead of octal, set the variable -@code{read-quoted-char-radix} to 10 or 16. If the radix is 16, -the letters @kbd{a} to @kbd{f} serve as part of a character code, -just like digits. Case is ignored. - -@findex insert-char -@kindex C-x 8 RET -@cindex Unicode characters, inserting -@cindex insert Unicode character -@cindex characters, inserting by name or code-point - Alternatively, you can use the command @kbd{C-x 8 @key{RET}} -(@code{insert-char}). This prompts for the Unicode name or code-point -of a character, using the minibuffer. If you enter a name, the -command provides completion (@pxref{Completion}). If you enter a -code-point, it should be as a hexadecimal number (the convention for -Unicode), or a number with a specified radix, e.g., @code{#o23072} -(octal); @xref{Integer Basics,,, elisp, The Emacs Lisp Reference -Manual}. The command then inserts the corresponding character into -the buffer. For example, both of the following insert the infinity -sign (Unicode code-point @code{U+221E}): - -@example -@kbd{C-x 8 @key{RET} infinity @key{RET}} -@kbd{C-x 8 @key{RET} 221e @key{RET}} -@end example - - A numeric argument to @kbd{C-q} or @kbd{C-x 8 @key{RET}} specifies -how many copies of the character to insert (@pxref{Arguments}). - -@node Moving Point -@section Changing the Location of Point - -@cindex arrow keys -@cindex moving point -@cindex movement -@cindex cursor motion -@cindex moving the cursor - To do more than insert characters, you have to know how to move -point (@pxref{Point}). The keyboard commands @kbd{C-f}, @kbd{C-b}, -@kbd{C-n}, and @kbd{C-p} move point to the right, left, down, and up, -respectively. You can also move point using the @dfn{arrow keys} -present on most keyboards: @key{RIGHT}, @key{LEFT}, -@key{DOWN}, and @key{UP}; however, many Emacs users find -that it is slower to use the arrow keys than the control keys, because -you need to move your hand to the area of the keyboard where those -keys are located. - - You can also click the left mouse button to move point to the -position clicked. Emacs also provides a variety of additional -keyboard commands that move point in more sophisticated ways. - -@table @kbd - -@item C-f -@kindex C-f -@findex forward-char -Move forward one character (@code{forward-char}). - -@item @key{RIGHT} -@kindex RIGHT -@findex right-char -@vindex visual-order-cursor-movement -@cindex cursor, visual-order motion -This command (@code{right-char}) behaves like @kbd{C-f}, with one -exception: when editing right-to-left scripts such as Arabic, it -instead moves @emph{backward} if the current paragraph is a -right-to-left paragraph. @xref{Bidirectional Editing}. If -@code{visual-order-cursor-movement} is non-@code{nil}, this command -moves to the character that is to the right of the current screen -position, moving to the next or previous screen line as appropriate. -Note that this might potentially move point many buffer positions -away, depending on the surrounding bidirectional context. - -@item C-b -@kindex C-b -@findex backward-char -Move backward one character (@code{backward-char}). - -@item @key{LEFT} -@kindex LEFT -@findex left-char -This command (@code{left-char}) behaves like @kbd{C-b}, except it -moves @emph{forward} if the current paragraph is right-to-left. -@xref{Bidirectional Editing}. If @code{visual-order-cursor-movement} -is non-@code{nil}, this command moves to the character that is to the -left of the current screen position, moving to the previous or next -screen line as appropriate. - -@item C-n -@itemx @key{DOWN} -@kindex C-n -@kindex DOWN -@findex next-line -Move down one screen line (@code{next-line}). This command attempts -to keep the horizontal position unchanged, so if you start in the -middle of one line, you move to the middle of the next. - -@item C-p -@itemx @key{UP} -@kindex C-p -@kindex UP -@findex previous-line -Move up one screen line (@code{previous-line}). This command -preserves position within the line, like @kbd{C-n}. - -@item C-a -@itemx @key{Home} -@kindex C-a -@kindex HOME -@findex move-beginning-of-line -Move to the beginning of the line (@code{move-beginning-of-line}). - -@item C-e -@itemx @key{End} -@kindex C-e -@kindex END -@findex move-end-of-line -Move to the end of the line (@code{move-end-of-line}). - -@item M-f -@kindex M-f -@findex forward-word -Move forward one word (@code{forward-word}). - -@item C-@key{RIGHT} -@itemx M-@key{RIGHT} -@kindex C-RIGHT -@kindex M-RIGHT -@findex right-word -This command (@code{right-word}) behaves like @kbd{M-f}, except it -moves @emph{backward} by one word if the current paragraph is -right-to-left. @xref{Bidirectional Editing}. - -@item M-b -@kindex M-b -@findex backward-word -Move backward one word (@code{backward-word}). - -@item C-@key{LEFT} -@itemx M-@key{LEFT} -@kindex C-LEFT -@kindex M-LEFT -@findex left-word -This command (@code{left-word}) behaves like @kbd{M-b}, except it -moves @emph{forward} by one word if the current paragraph is -right-to-left. @xref{Bidirectional Editing}. - -@item M-r -@kindex M-r -@findex move-to-window-line-top-bottom -Without moving the text on the screen, reposition point on the left -margin of the center-most text line of the window; on subsequent -consecutive invocations, move point to the left margin of the top-most -line, the bottom-most line, and so forth, in cyclic order -(@code{move-to-window-line-top-bottom}). - -A numeric argument says which screen line to place point on, counting -downward from the top of the window (zero means the top line). A -negative argument counts lines up from the bottom (@minus{}1 means the -bottom line). @xref{Arguments}, for more information on numeric -arguments. - -@item M-< -@kindex M-< -@findex beginning-of-buffer -Move to the top of the buffer (@code{beginning-of-buffer}). With -numeric argument @var{n}, move to @var{n}/10 of the way from the top. - -@item M-> -@kindex M-> -@findex end-of-buffer -Move to the end of the buffer (@code{end-of-buffer}). - -@item C-v -@itemx @key{PageDown} -@itemx @key{next} -Scroll the display one screen forward, and move point onscreen if -necessary (@code{scroll-up-command}). @xref{Scrolling}. - -@item M-v -@itemx @key{PageUp} -@itemx @key{prior} -Scroll one screen backward, and move point onscreen if necessary -(@code{scroll-down-command}). @xref{Scrolling}. - -@item M-g c -@kindex M-g c -@findex goto-char -Read a number @var{n} and move point to buffer position @var{n}. -Position 1 is the beginning of the buffer. - -@item M-g M-g -@itemx M-g g -@kindex M-g M-g -@kindex M-g g -@findex goto-line -Read a number @var{n} and move point to the beginning of line number -@var{n} (@code{goto-line}). Line 1 is the beginning of the buffer. If -point is on or just after a number in the buffer, that is the default -for @var{n}. Just type @key{RET} in the minibuffer to use it. You can -also specify @var{n} by giving @kbd{M-g M-g} a numeric prefix argument. -@xref{Select Buffer}, for the behavior of @kbd{M-g M-g} when you give it -a plain prefix argument. - -@item M-g @key{TAB} -@kindex M-g TAB -@findex move-to-column -Read a number @var{n} and move to column @var{n} in the current line. -Column 0 is the leftmost column. If called with a prefix argument, -move to the column number specified by the argument's numeric value. - -@item C-x C-n -@kindex C-x C-n -@findex set-goal-column -Use the current column of point as the @dfn{semipermanent goal column} -for @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). When a -semipermanent goal column is in effect, those commands always try to -move to this column, or as close as possible to it, after moving -vertically. The goal column remains in effect until canceled. - -@item C-u C-x C-n -Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} try to -preserve the horizontal position, as usual. -@end table - -@vindex line-move-visual - When a line of text in the buffer is longer than the width of the -window, Emacs usually displays it on two or more @dfn{screen lines}. -For convenience, @kbd{C-n} and @kbd{C-p} move point by screen lines, -as do the equivalent keys @kbd{@key{down}} and @kbd{@key{up}}. You -can force these commands to move according to @dfn{logical lines} -(i.e., according to the text lines in the buffer) by setting the -variable @code{line-move-visual} to @code{nil}; if a logical line -occupies multiple screen lines, the cursor then skips over the -additional screen lines. For details, see @ref{Continuation Lines}. -@xref{Variables}, for how to set variables such as -@code{line-move-visual}. - - Unlike @kbd{C-n} and @kbd{C-p}, most of the Emacs commands that work -on lines work on @emph{logical} lines. For instance, @kbd{C-a} -(@code{move-beginning-of-line}) and @kbd{C-e} -(@code{move-end-of-line}) respectively move to the beginning and end -of the logical line. Whenever we encounter commands that work on -screen lines, such as @kbd{C-n} and @kbd{C-p}, we will point these -out. - -@vindex track-eol - When @code{line-move-visual} is @code{nil}, you can also set the -variable @code{track-eol} to a non-@code{nil} value. Then @kbd{C-n} -and @kbd{C-p}, when starting at the end of the logical line, move to -the end of the next logical line. Normally, @code{track-eol} is -@code{nil}. - -@vindex next-line-add-newlines - @kbd{C-n} normally stops at the end of the buffer when you use it on -the last line in the buffer. However, if you set the variable -@code{next-line-add-newlines} to a non-@code{nil} value, @kbd{C-n} on -the last line of a buffer creates an additional line at the end and -moves down into it. - -@node Erasing -@section Erasing Text -@cindex killing characters and lines -@cindex deleting characters and lines -@cindex erasing characters and lines - -@table @kbd -@item @key{DEL} -@itemx @key{BACKSPACE} -Delete the character before point, or the region if it is active -(@code{delete-backward-char}). - -@item @key{Delete} -Delete the character after point, or the region if it is active -(@code{delete-forward-char}). - -@item C-d -Delete the character after point (@code{delete-char}). - -@item C-k -Kill to the end of the line (@code{kill-line}). -@item M-d -Kill forward to the end of the next word (@code{kill-word}). -@item M-@key{DEL} -Kill back to the beginning of the previous word -(@code{backward-kill-word}). -@end table - - The @kbd{@key{DEL}} (@code{delete-backward-char}) command removes -the character before point, moving the cursor and the characters after -it backwards. If point was at the beginning of a line, this deletes -the preceding newline, joining this line to the previous one. - - If, however, the region is active, @kbd{@key{DEL}} instead deletes -the text in the region. @xref{Mark}, for a description of the region. - - On most keyboards, @key{DEL} is labeled @key{BACKSPACE}, but we -refer to it as @key{DEL} in this manual. (Do not confuse @key{DEL} -with the @key{Delete} key; we will discuss @key{Delete} momentarily.) -On some text terminals, Emacs may not recognize the @key{DEL} key -properly. @xref{DEL Does Not Delete}, if you encounter this problem. - - The @key{Delete} (@code{delete-forward-char}) command deletes in the -``opposite direction'': it deletes the character after point, i.e., the -character under the cursor. If point was at the end of a line, this -joins the following line onto this one. Like @kbd{@key{DEL}}, it -deletes the text in the region if the region is active (@pxref{Mark}). - - @kbd{C-d} (@code{delete-char}) deletes the character after point, -similar to @key{Delete}, but regardless of whether the region is -active. - - @xref{Deletion}, for more detailed information about the above -deletion commands. - - @kbd{C-k} (@code{kill-line}) erases (kills) a line at a time. If -you type @kbd{C-k} at the beginning or middle of a line, it kills all -the text up to the end of the line. If you type @kbd{C-k} at the end -of a line, it joins that line with the following line. - - @xref{Killing}, for more information about @kbd{C-k} and related -commands. - -@node Basic Undo -@section Undoing Changes - -@table @kbd -@item C-/ -Undo one entry of the undo records---usually, one command worth -(@code{undo}). - -@item C-x u -@itemx C-_ -The same. -@end table - - Emacs records a list of changes made in the buffer text, so you can -undo recent changes. This is done using the @code{undo} command, -which is bound to @kbd{C-/} (as well as @kbd{C-x u} and @kbd{C-_}). -Normally, this command undoes the last change, moving point back to -where it was before the change. The undo command applies only to -changes in the buffer; you can't use it to undo cursor motion. - - Although each editing command usually makes a separate entry in the -undo records, very simple commands may be grouped together. -Sometimes, an entry may cover just part of a complex command. - - If you repeat @kbd{C-/} (or its aliases), each repetition undoes -another, earlier change, back to the limit of the undo information -available. If all recorded changes have already been undone, the undo -command displays an error message and does nothing. - - To learn more about the @code{undo} command, see @ref{Undo}. - -@node Basic Files -@section Files - - Text that you insert in an Emacs buffer lasts only as long as the -Emacs session. To keep any text permanently, you must put it in a -@dfn{file}. - - Suppose there is a file named @file{test.emacs} in your home -directory. To begin editing this file in Emacs, type - -@example -C-x C-f test.emacs @key{RET} -@end example - -@noindent -Here the file name is given as an @dfn{argument} to the command @kbd{C-x -C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to -read the argument, and you type @key{RET} to terminate the argument -(@pxref{Minibuffer}). - - Emacs obeys this command by @dfn{visiting} the file: it creates a -buffer, copies the contents of the file into the buffer, and then -displays the buffer for editing. If you alter the text, you can -@dfn{save} the new text in the file by typing @kbd{C-x C-s} -(@code{save-buffer}). This copies the altered buffer contents back -into the file @file{test.emacs}, making them permanent. Until you -save, the changed text exists only inside Emacs, and the file -@file{test.emacs} is unaltered. - - To create a file, just visit it with @kbd{C-x C-f} as if it already -existed. This creates an empty buffer, in which you can insert the -text you want to put in the file. Emacs actually creates the file the -first time you save this buffer with @kbd{C-x C-s}. - - To learn more about using files in Emacs, see @ref{Files}. - -@node Basic Help -@section Help - -@cindex getting help with keys - If you forget what a key does, you can find out by typing @kbd{C-h -k} (@code{describe-key}), followed by the key of interest; for -example, @kbd{C-h k C-n} tells you what @kbd{C-n} does. - - The prefix key @kbd{C-h} stands for ``help''. The key @key{F1} -serves as an alias for @kbd{C-h}. Apart from @kbd{C-h k}, there are -many other help commands providing different kinds of help. - - @xref{Help}, for details. - -@node Blank Lines -@section Blank Lines - -@cindex inserting blank lines -@cindex deleting blank lines - Here are special commands and techniques for inserting and deleting -blank lines. - -@table @kbd -@item C-o -Insert a blank line after the cursor (@code{open-line}). -@item C-x C-o -Delete all but one of many consecutive blank lines -(@code{delete-blank-lines}). -@end table - -@kindex C-o -@kindex C-x C-o -@cindex blank lines -@findex open-line -@findex delete-blank-lines - We have seen how @kbd{@key{RET}} (@code{newline}) starts a new line -of text. However, it may be easier to see what you are doing if you -first make a blank line and then insert the desired text into it. -This is easy to do using the key @kbd{C-o} (@code{open-line}), which -inserts a newline after point but leaves point in front of the -newline. After @kbd{C-o}, type the text for the new line. - - You can make several blank lines by typing @kbd{C-o} several times, or -by giving it a numeric argument specifying how many blank lines to make. -@xref{Arguments}, for how. If you have a fill prefix, the @kbd{C-o} -command inserts the fill prefix on the new line, if typed at the -beginning of a line. @xref{Fill Prefix}. - - The easy way to get rid of extra blank lines is with the command -@kbd{C-x C-o} (@code{delete-blank-lines}). If point lies within a run -of several blank lines, @kbd{C-x C-o} deletes all but one of them. If -point is on a single blank line, @kbd{C-x C-o} deletes it. If point -is on a nonblank line, @kbd{C-x C-o} deletes all following blank -lines, if any exists. - -@node Continuation Lines -@section Continuation Lines - -@cindex continuation line -@cindex wrapping -@cindex line wrapping -@cindex fringes, and continuation lines - Sometimes, a line of text in the buffer---a @dfn{logical line}---is -too long to fit in the window, and Emacs displays it as two or more -@dfn{screen lines}. This is called @dfn{line wrapping} or -@dfn{continuation}, and the long logical line is called a -@dfn{continued line}. On a graphical display, Emacs indicates line -wrapping with small bent arrows in the left and right window fringes. -On a text terminal, Emacs indicates line wrapping by displaying a -@samp{\} character at the right margin. - - Most commands that act on lines act on logical lines, not screen -lines. For instance, @kbd{C-k} kills a logical line. As described -earlier, @kbd{C-n} (@code{next-line}) and @kbd{C-p} -(@code{previous-line}) are special exceptions: they move point down -and up, respectively, by one screen line (@pxref{Moving Point}). - -@cindex truncation -@cindex line truncation, and fringes - Emacs can optionally @dfn{truncate} long logical lines instead of -continuing them. This means that every logical line occupies a single -screen line; if it is longer than the width of the window, the rest of -the line is not displayed. On a graphical display, a truncated line -is indicated by a small straight arrow in the right fringe; on a text -terminal, it is indicated by a @samp{$} character in the right margin. -@xref{Line Truncation}. - - By default, continued lines are wrapped at the right window edge. -Since the wrapping may occur in the middle of a word, continued lines -can be difficult to read. The usual solution is to break your lines -before they get too long, by inserting newlines. If you prefer, you -can make Emacs insert a newline automatically when a line gets too -long, by using Auto Fill mode. @xref{Filling}. - -@cindex word wrap - Sometimes, you may need to edit files containing many long logical -lines, and it may not be practical to break them all up by adding -newlines. In that case, you can use Visual Line mode, which enables -@dfn{word wrapping}: instead of wrapping long lines exactly at the -right window edge, Emacs wraps them at the word boundaries (i.e., -space or tab characters) nearest to the right window edge. Visual -Line mode also redefines editing commands such as @code{C-a}, -@code{C-n}, and @code{C-k} to operate on screen lines rather than -logical lines. @xref{Visual Line Mode}. - -@node Position Info -@section Cursor Position Information - - Here are commands to get information about the size and position of -parts of the buffer, and to count words and lines. - -@table @kbd -@item M-x what-line -Display the line number of point. -@item M-x line-number-mode -@itemx M-x column-number-mode -Toggle automatic display of the current line number or column number. -@xref{Optional Mode Line}. - -@item M-= -Display the number of lines, words, and characters that are present in -the region (@code{count-words-region}). @xref{Mark}, for information -about the region. - -@item M-x count-words -Display the number of lines, words, and characters that are present in -the buffer. If the region is active (@pxref{Mark}), display the -numbers for the region instead. - -@item C-x = -Display the character code of character after point, character position of -point, and column of point (@code{what-cursor-position}). -@item M-x hl-line-mode -Enable or disable highlighting of the current line. @xref{Cursor -Display}. -@item M-x size-indication-mode -Toggle automatic display of the size of the buffer. -@xref{Optional Mode Line}. -@end table - -@findex what-line -@cindex line number commands -@cindex location of point -@cindex cursor location -@cindex point location - @kbd{M-x what-line} displays the current line number in the echo -area. This command is usually redundant, because the current line -number is shown in the mode line (@pxref{Mode Line}). However, if you -narrow the buffer, the mode line shows the line number relative to -the accessible portion (@pxref{Narrowing}). By contrast, -@code{what-line} displays both the line number relative to the -narrowed region and the line number relative to the whole buffer. - -@kindex M-= -@findex count-words-region - @kbd{M-=} (@code{count-words-region}) displays a message reporting -the number of lines, words, and characters in the region -(@pxref{Mark}, for an explanation of the region). With a prefix -argument, @kbd{C-u M-=}, the command displays a count for the entire -buffer. - -@findex count-words - The command @kbd{M-x count-words} does the same job, but with a -different calling convention. It displays a count for the region if -the region is active, and for the buffer otherwise. - -@kindex C-x = -@findex what-cursor-position - The command @kbd{C-x =} (@code{what-cursor-position}) shows -information about the current cursor position and the buffer contents -at that position. It displays a line in the echo area that looks like -this: - -@smallexample -Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 -@end smallexample - - After @samp{Char:}, this shows the character in the buffer at point. -The text inside the parenthesis shows the corresponding decimal, octal -and hex character codes; for more information about how @kbd{C-x =} -displays character information, see @ref{International Chars}. After -@samp{point=} is the position of point as a character count (the first -character in the buffer is position 1, the second character is -position 2, and so on). The number after that is the total number of -characters in the buffer, and the number in parenthesis expresses the -position as a percentage of the total. After @samp{column=} is the -horizontal position of point, in columns counting from the left edge -of the window. - - If the buffer has been narrowed, making some of the text at the -beginning and the end temporarily inaccessible, @kbd{C-x =} displays -additional text describing the currently accessible range. For -example, it might display this: - -@smallexample -Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0 -@end smallexample - -@noindent -where the two extra numbers give the smallest and largest character -position that point is allowed to assume. The characters between -those two positions are the accessible ones. @xref{Narrowing}. - -@node Arguments -@section Numeric Arguments -@cindex numeric arguments -@cindex prefix arguments -@cindex arguments to commands - - In the terminology of mathematics and computing, @dfn{argument} -means ``data provided to a function or operation''. You can give any -Emacs command a @dfn{numeric argument} (also called a @dfn{prefix -argument}). Some commands interpret the argument as a repetition -count. For example, giving @kbd{C-f} an argument of ten causes it to -move point forward by ten characters instead of one. With these -commands, no argument is equivalent to an argument of one, and -negative arguments cause them to move or act in the opposite -direction. - -@kindex M-1 -@kindex M-@t{-} -@findex digit-argument -@findex negative-argument - The easiest way to specify a numeric argument is to type a digit -and/or a minus sign while holding down the @key{META} key. For -example, - -@example -M-5 C-n -@end example - -@noindent -moves down five lines. The keys @kbd{M-1}, @kbd{M-2}, and so on, as -well as @kbd{M--}, are bound to commands (@code{digit-argument} and -@code{negative-argument}) that set up an argument for the next -command. @kbd{M--} without digits normally means @minus{}1. - -If you enter more than one digit, you need not hold down the -@key{META} key for the second and subsequent digits. Thus, to move -down fifty lines, type - -@example -M-5 0 C-n -@end example - -@noindent -Note that this @emph{does not} insert five copies of @samp{0} and move -down one line, as you might expect---the @samp{0} is treated as part -of the prefix argument. - -(What if you do want to insert five copies of @samp{0}? Type @kbd{M-5 -C-u 0}. Here, @kbd{C-u} ``terminates'' the prefix argument, so that -the next keystroke begins the command that you want to execute. Note -that this meaning of @kbd{C-u} applies only to this case. For the -usual role of @kbd{C-u}, see below.) - -@kindex C-u -@findex universal-argument - Instead of typing @kbd{M-1}, @kbd{M-2}, and so on, another way to -specify a numeric argument is to type @kbd{C-u} -(@code{universal-argument}) followed by some digits, or (for a -negative argument) a minus sign followed by digits. A minus sign -without digits normally means @minus{}1. - - @kbd{C-u} alone has the special meaning of ``four times'': it -multiplies the argument for the next command by four. @kbd{C-u C-u} -multiplies it by sixteen. Thus, @kbd{C-u C-u C-f} moves forward -sixteen characters. Other useful combinations are @kbd{C-u C-n}, -@kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u -C-u C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four -lines). - - You can use a numeric argument before a self-inserting character to -insert multiple copies of it. This is straightforward when the -character is not a digit; for example, @kbd{C-u 6 4 a} inserts 64 -copies of the character @samp{a}. But this does not work for -inserting digits; @kbd{C-u 6 4 1} specifies an argument of 641. You -can separate the argument from the digit to insert with another -@kbd{C-u}; for example, @kbd{C-u 6 4 C-u 1} does insert 64 copies of -the character @samp{1}. - - Some commands care whether there is an argument, but ignore its -value. For example, the command @kbd{M-q} (@code{fill-paragraph}) -fills text; with an argument, it justifies the text as well. -(@xref{Filling}, for more information on @kbd{M-q}.) For these -commands, it is enough to specify the argument with a single -@kbd{C-u}. - - Some commands use the value of the argument as a repeat count, but -do something special when there is no argument. For example, the -command @kbd{C-k} (@code{kill-line}) with argument @var{n} kills -@var{n} lines, including their terminating newlines. But @kbd{C-k} -with no argument is special: it kills the text up to the next newline, -or, if point is right at the end of the line, it kills the newline -itself. Thus, two @kbd{C-k} commands with no arguments can kill a -nonblank line, just like @kbd{C-k} with an argument of one. -(@xref{Killing}, for more information on @kbd{C-k}.) - - A few commands treat a plain @kbd{C-u} differently from an ordinary -argument. A few others may treat an argument of just a minus sign -differently from an argument of @minus{}1. These unusual cases are -described when they come up; they exist to make an individual command -more convenient, and they are documented in that command's -documentation string. - - We use the term @dfn{prefix argument} to emphasize that you type -such arguments before the command, and to distinguish them from -minibuffer arguments (@pxref{Minibuffer}), which are entered after -invoking the command. - -@node Repeating -@section Repeating a Command -@cindex repeating a command - - Many simple commands, such as those invoked with a single key or -with @kbd{M-x @var{command-name} @key{RET}}, can be repeated by -invoking them with a numeric argument that serves as a repeat count -(@pxref{Arguments}). However, if the command you want to repeat -prompts for input, or uses a numeric argument in another way, that -method won't work. - -@kindex C-x z -@findex repeat - The command @kbd{C-x z} (@code{repeat}) provides another way to repeat -an Emacs command many times. This command repeats the previous Emacs -command, whatever that was. Repeating a command uses the same arguments -that were used before; it does not read new arguments each time. - - To repeat the command more than once, type additional @kbd{z}'s: each -@kbd{z} repeats the command one more time. Repetition ends when you -type a character other than @kbd{z}, or press a mouse button. - - For example, suppose you type @kbd{C-u 2 0 C-d} to delete 20 -characters. You can repeat that command (including its argument) three -additional times, to delete a total of 80 characters, by typing @kbd{C-x -z z z}. The first @kbd{C-x z} repeats the command once, and each -subsequent @kbd{z} repeats it once again. diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi deleted file mode 100644 index 54a84989e2e..00000000000 --- a/doc/emacs/buffers.texi +++ /dev/null @@ -1,702 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Buffers -@chapter Using Multiple Buffers - -@cindex buffers - The text you are editing in Emacs resides in an object called a -@dfn{buffer}. Each time you visit a file, a buffer is used to hold -the file's text. Each time you invoke Dired, a buffer is used to hold -the directory listing. If you send a message with @kbd{C-x m}, a -buffer is used to hold the text of the message. When you ask for a -command's documentation, that appears in a buffer named @file{*Help*}. - - Each buffer has a unique name, which can be of any length. When a -buffer is displayed in a window, its name is shown in the mode line -(@pxref{Mode Line}). The distinction between upper and lower case -matters in buffer names. Most buffers are made by visiting files, and -their names are derived from the files' names; however, you can also -create an empty buffer with any name you want. A newly started Emacs -has several buffers, including one named @file{*scratch*}, which can -be used for evaluating Lisp expressions and is not associated with any -file (@pxref{Lisp Interaction}). - -@cindex selected buffer -@cindex current buffer - At any time, one and only one buffer is @dfn{selected}; we call it -the @dfn{current buffer}. We sometimes say that a command operates on -``the buffer''; this really means that it operates on the current -buffer. When there is only one Emacs window, the buffer displayed in -that window is current. When there are multiple windows, the buffer -displayed in the @dfn{selected window} is current. @xref{Windows}. - - Aside from its textual contents, each buffer records several pieces -of information, such as what file it is visiting (if any), whether it -is modified, and what major mode and minor modes are in effect -(@pxref{Modes}). These are stored in @dfn{buffer-local -variables}---variables that can have a different value in each buffer. -@xref{Locals}. - -@cindex buffer size, maximum - A buffer's size cannot be larger than some maximum, which is defined -by the largest buffer position representable by @dfn{Emacs integers}. -This is because Emacs tracks buffer positions using that data type. -For typical 64-bit machines, this maximum buffer size is @math{2^{61} - 2} -bytes, or about 2 EiB@. For typical 32-bit machines, the maximum is -usually @math{2^{29} - 2} bytes, or about 512 MiB@. Buffer sizes are -also limited by the amount of memory in the system. - -@menu -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-only status; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. -* Indirect Buffers:: An indirect buffer shares the text of another buffer. -* Buffer Convenience:: Convenience and customization features for - buffer handling. -@end menu - -@node Select Buffer -@section Creating and Selecting Buffers -@cindex change buffers -@cindex switch buffers - -@table @kbd -@item C-x b @var{buffer} @key{RET} -Select or create a buffer named @var{buffer} (@code{switch-to-buffer}). -@item C-x 4 b @var{buffer} @key{RET} -Similar, but select @var{buffer} in another window -(@code{switch-to-buffer-other-window}). -@item C-x 5 b @var{buffer} @key{RET} -Similar, but select @var{buffer} in a separate frame -(@code{switch-to-buffer-other-frame}). -@item C-x @key{LEFT} -Select the previous buffer in the buffer list (@code{previous-buffer}). -@item C-x @key{RIGHT} -Select the next buffer in the buffer list (@code{next-buffer}). -@item C-u M-g M-g -@itemx C-u M-g g -Read a number @var{n} and move to line @var{n} in the most recently -selected buffer other than the current buffer. -@end table - -@kindex C-x b -@findex switch-to-buffer - The @kbd{C-x b} (@code{switch-to-buffer}) command reads a buffer -name using the minibuffer. Then it makes that buffer current, and -displays it in the currently-selected window. An empty input -specifies the buffer that was current most recently among those not -now displayed in any window. - - While entering the buffer name, you can use the usual completion and -history commands (@pxref{Minibuffer}). Note that @kbd{C-x b}, and -related commands, use ``permissive completion with confirmation'' for -minibuffer completion: if you type @key{RET} immediately after -completing up to a nonexistent buffer name, Emacs prints -@samp{[Confirm]} and you must type a second @key{RET} to submit that -buffer name. @xref{Completion Exit}, for details. - - If you specify a buffer that does not exist, @kbd{C-x b} creates a -new, empty buffer that is not visiting any file, and selects it for -editing. The default value of the variable @code{major-mode} -determines the new buffer's major mode; the default value is -Fundamental mode. @xref{Major Modes}. One reason to create a new -buffer is to use it for making temporary notes. If you try to save -it, Emacs asks for the file name to use, and the buffer's major mode -is re-established taking that file name into account (@pxref{Choosing -Modes}). - -@kindex C-x @key{LEFT} -@kindex C-x @key{RIGHT} -@findex next-buffer -@findex previous-buffer - For conveniently switching between a few buffers, use the commands -@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}. @kbd{C-x @key{LEFT}} -(@code{previous-buffer}) selects the previous buffer (following the -order of most recent selection in the current frame), while @kbd{C-x -@key{RIGHT}} (@code{next-buffer}) moves through buffers in the reverse -direction. - -@kindex C-x 4 b -@findex switch-to-buffer-other-window - To select a buffer in a window other than the current one, type -@kbd{C-x 4 b} (@code{switch-to-buffer-other-window}). This prompts -for a buffer name using the minibuffer, displays that buffer in -another window, and selects that window. - -@kindex C-x 5 b -@findex switch-to-buffer-other-frame - Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame}) -prompts for a buffer name, displays that buffer in another frame, and -selects that frame. If the buffer is already being shown in a window -on another frame, Emacs selects that window and frame instead of -creating a new frame. - - @xref{Displaying Buffers}, for how the @kbd{C-x 4 b} and @kbd{C-x 5 -b} commands get the window and/or frame to display in. - - In addition, @kbd{C-x C-f}, and any other command for visiting a -file, can also be used to switch to an existing file-visiting buffer. -@xref{Visiting}. - -@findex goto-line - @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix -argument, reads a number @var{n} using the minibuffer, selects the -most recently selected buffer other than the current buffer in another -window, and then moves point to the beginning of line number @var{n} -in that buffer. This is mainly useful in a buffer that refers to line -numbers in another buffer: if point is on or just after a number, -@code{goto-line} uses that number as the default for @var{n}. Note -that prefix arguments other than just @kbd{C-u} behave differently. -@kbd{C-u 4 M-g M-g} goes to line 4 in the @emph{current} buffer, -without reading a number from the minibuffer. (Remember that @kbd{M-g -M-g} without prefix argument reads a number @var{n} and then moves to -line number @var{n} in the current buffer. @xref{Moving Point}.) - - Emacs uses buffer names that start with a space for internal purposes. -It treats these buffers specially in minor ways---for example, by -default they do not record undo information. It is best to avoid using -such buffer names yourself. - -@node List Buffers -@section Listing Existing Buffers - -@table @kbd -@item C-x C-b -List the existing buffers (@code{list-buffers}). -@end table - -@cindex listing current buffers -@kindex C-x C-b -@findex list-buffers - To display a list of existing buffers, type @kbd{C-x C-b}. Each -line in the list shows one buffer's name, size, major mode and visited file. -The buffers are listed in the order that they were current; the -buffers that were current most recently come first. - - @samp{.} in the first field of a line indicates that the buffer is -current. @samp{%} indicates a read-only buffer. @samp{*} indicates -that the buffer is ``modified''. If several buffers are modified, it -may be time to save some with @kbd{C-x s} (@pxref{Save Commands}). -Here is an example of a buffer list: - -@smallexample -CRM Buffer Size Mode File -. * .emacs 3294 Emacs-Lisp ~/.emacs - % *Help* 101 Help - search.c 86055 C ~/cvs/emacs/src/search.c - % src 20959 Dired by name ~/cvs/emacs/src/ - * *mail* 42 Mail - % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO - % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS - *scratch* 191 Lisp Interaction - * *Messages* 1554 Messages -@end smallexample - -@noindent -The buffer @file{*Help*} was made by a help request (@pxref{Help}); it -is not visiting any file. The buffer @code{src} was made by Dired on -the directory @file{~/cvs/emacs/src/}. You can list only buffers that -are visiting files by giving the command a prefix argument, as in -@kbd{C-u C-x C-b}. - - @code{list-buffers} omits buffers whose names begin with a space, -unless they visit files: such buffers are used internally by Emacs. - -@node Misc Buffer -@section Miscellaneous Buffer Operations - -@table @kbd -@item C-x C-q -Toggle read-only status of buffer (@code{read-only-mode}). -@item M-x rename-buffer @key{RET} @var{name} @key{RET} -Change the name of the current buffer. -@item M-x rename-uniquely -Rename the current buffer by adding @samp{<@var{number}>} to the end. -@item M-x view-buffer @key{RET} @var{buffer} @key{RET} -Scroll through buffer @var{buffer}. @xref{View Mode}. -@end table - -@kindex C-x C-q -@vindex buffer-read-only -@cindex read-only buffer - A buffer can be @dfn{read-only}, which means that commands to change -its contents are not allowed. The mode line indicates read-only -buffers with @samp{%%} or @samp{%*} near the left margin. Read-only -buffers are usually made by subsystems such as Dired and Rmail that -have special commands to operate on the text; also by visiting a file -whose access control says you cannot write it. - -@findex read-only-mode -@vindex view-read-only - The command @kbd{C-x C-q} (@code{read-only-mode}) makes a read-only -buffer writable, and makes a writable buffer read-only. This works by -setting the variable @code{buffer-read-only}, which has a local value -in each buffer and makes the buffer read-only if its value is -non-@code{nil}. If you change the option @code{view-read-only} to a -non-@code{nil} value, making the buffer read-only with @kbd{C-x C-q} -also enables View mode in the buffer (@pxref{View Mode}). - -@findex rename-buffer - @kbd{M-x rename-buffer} changes the name of the current buffer. You -specify the new name as a minibuffer argument; there is no default. -If you specify a name that is in use for some other buffer, an error -happens and no renaming is done. - -@findex rename-uniquely - @kbd{M-x rename-uniquely} renames the current buffer to a similar -name with a numeric suffix added to make it both different and unique. -This command does not need an argument. It is useful for creating -multiple shell buffers: if you rename the @file{*shell*} buffer, then -do @kbd{M-x shell} again, it makes a new shell buffer named -@file{*shell*}; meanwhile, the old shell buffer continues to exist -under its new name. This method is also good for mail buffers, -compilation buffers, and most Emacs features that create special -buffers with particular names. (With some of these features, such as -@kbd{M-x compile}, @kbd{M-x grep}, you need to switch to some other -buffer before using the command again, otherwise it will reuse the -current buffer despite the name change.) - - The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer} -can also be used to copy text from one buffer to another. -@xref{Accumulating Text}. - -@node Kill Buffer -@section Killing Buffers - -@cindex killing buffers - If you continue an Emacs session for a while, you may accumulate a -large number of buffers. You may then find it convenient to @dfn{kill} -the buffers you no longer need. On most operating systems, killing a -buffer releases its space back to the operating system so that other -programs can use it. Here are some commands for killing buffers: - -@table @kbd -@item C-x k @var{bufname} @key{RET} -Kill buffer @var{bufname} (@code{kill-buffer}). -@item M-x kill-some-buffers -Offer to kill each buffer, one by one. -@item M-x kill-matching-buffers -Offer to kill all buffers matching a regular expression. -@end table - -@findex kill-buffer -@kindex C-x k - @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you -specify in the minibuffer. The default, used if you type just -@key{RET} in the minibuffer, is to kill the current buffer. If you -kill the current buffer, another buffer becomes current: one that was -current in the recent past but is not displayed in any window now. If -you ask to kill a file-visiting buffer that is modified, then you must -confirm with @kbd{yes} before the buffer is killed. - -@findex kill-some-buffers - The command @kbd{M-x kill-some-buffers} asks about each buffer, one -by one. An answer of @kbd{y} means to kill the buffer, just like -@code{kill-buffer}. This command ignores buffers whose names begin -with a space, which are used internally by Emacs. - -@findex kill-matching-buffers - The command @kbd{M-x kill-matching-buffers} prompts for a regular -expression and kills all buffers whose names match that expression. -@xref{Regexps}. Like @code{kill-some-buffers}, it asks for -confirmation before each kill. This command normally ignores buffers -whose names begin with a space, which are used internally by Emacs. -To kill internal buffers as well, call @code{kill-matching-buffers} -with a prefix argument. - - The Buffer Menu feature is also convenient for killing various -buffers. @xref{Several Buffers}. - -@vindex kill-buffer-hook - If you want to do something special every time a buffer is killed, you -can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}). - -@findex clean-buffer-list - If you run one Emacs session for a period of days, as many people do, -it can fill up with buffers that you used several days ago. The command -@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills -all the unmodified buffers that you have not used for a long time. An -ordinary buffer is killed if it has not been displayed for three days; -however, you can specify certain buffers that should never be killed -automatically, and others that should be killed if they have been unused -for a mere hour. - -@cindex Midnight mode -@vindex midnight-mode -@vindex midnight-hook - You can also have this buffer purging done for you, once a day, -by enabling Midnight mode. Midnight mode operates each day -at midnight; at that time, it runs @code{clean-buffer-list}, or -whichever functions you have placed in the normal hook -@code{midnight-hook} (@pxref{Hooks}). To enable Midnight mode, use -the Customization buffer to set the variable @code{midnight-mode} to -@code{t}. @xref{Easy Customization}. - -@node Several Buffers -@section Operating on Several Buffers -@cindex Buffer Menu - -@table @kbd -@item M-x buffer-menu -Begin editing a buffer listing all Emacs buffers. -@item M-x buffer-menu-other-window. -Similar, but do it in another window. -@end table - - The @dfn{Buffer Menu} opened by @kbd{C-x C-b} (@pxref{List Buffers}) -does not merely list buffers. It also allows you to perform various -operations on buffers, through an interface similar to Dired -(@pxref{Dired}). You can save buffers, kill them (here called -@dfn{deleting} them, for consistency with Dired), or display them. - -@findex buffer-menu -@findex buffer-menu-other-window - To use the Buffer Menu, type @kbd{C-x C-b} and switch to the window -displaying the @file{*Buffer List*} buffer. You can also type -@kbd{M-x buffer-menu} to open the Buffer Menu in the selected window. -Alternatively, the command @kbd{M-x buffer-menu-other-window} opens -the Buffer Menu in another window, and selects that window. - - The Buffer Menu is a read-only buffer, and can be changed only -through the special commands described in this section. The usual -cursor motion commands can be used in this buffer. The following -commands apply to the buffer described on the current line: - -@table @kbd -@item d -@findex Buffer-menu-delete -@kindex d @r{(Buffer Menu)} -Flag the buffer for deletion (killing), then move point to the next -line (@code{Buffer-menu-delete}). The deletion flag is indicated by -the character @samp{D} on the line, before the buffer name. The -deletion occurs only when you type the @kbd{x} command (see below). - -@item C-d -@findex Buffer-menu-delete-backwards -@kindex C-d @r{(Buffer Menu)} -Like @kbd{d}, but move point up instead of down -(@code{Buffer-menu-delete-backwards}). - -@item s -@findex Buffer-menu-save -@kindex s @r{(Buffer Menu)} -Flag the buffer for saving (@code{Buffer-menu-save}). The save flag -is indicated by the character @samp{S} on the line, before the buffer -name. The saving occurs only when you type @kbd{x}. You may request -both saving and deletion for the same buffer. - -@item x -@findex Buffer-menu-execute -@kindex x @r{(Buffer Menu)} -Perform all flagged deletions and saves (@code{Buffer-menu-execute}). - -@item u -@findex Buffer-menu-unmark -@kindex u @r{(Buffer Menu)} -Remove all flags from the current line, and move down -(@code{Buffer-menu-unmark}). - -@item @key{DEL} -@findex Buffer-menu-backup-unmark -@kindex DEL @r{(Buffer Menu)} -Move to the previous line and remove all flags on that line -(@code{Buffer-menu-backup-unmark}). -@end table - -@noindent -The commands for adding or removing flags, @kbd{d}, @kbd{C-d}, @kbd{s} -and @kbd{u}, all accept a numeric argument as a repeat count. - - The following commands operate immediately on the buffer listed on -the current line. They also accept a numeric argument as a repeat -count. - -@table @kbd -@item ~ -@findex Buffer-menu-not-modified -@kindex ~ @r{(Buffer Menu)} -Mark the buffer as unmodified (@code{Buffer-menu-not-modified}). -@xref{Save Commands}. - -@item % -@findex Buffer-menu-toggle-read-only -@kindex % @r{(Buffer Menu)} -Toggle the buffer's read-only status -(@code{Buffer-menu-toggle-read-only}). @xref{Misc Buffer}. - -@item t -@findex Buffer-menu-visit-tags-table -@kindex % @r{(Buffer Menu)} -Visit the buffer as a tags table -(@code{Buffer-menu-visit-tags-table}). @xref{Select Tags Table}. -@end table - - The following commands are used to select another buffer or buffers: - -@table @kbd -@item q -@findex quit-window -@kindex q @r{(Buffer Menu)} -Quit the Buffer Menu (@code{quit-window}). The most recent formerly -visible buffer is displayed in its place. - -@item @key{RET} -@itemx f -@findex Buffer-menu-this-window -@kindex f @r{(Buffer Menu)} -@kindex RET @r{(Buffer Menu)} -Select this line's buffer, replacing the @file{*Buffer List*} buffer -in its window (@code{Buffer-menu-this-window}). - -@item o -@findex Buffer-menu-other-window -@kindex o @r{(Buffer Menu)} -Select this line's buffer in another window, as if by @kbd{C-x 4 b}, -leaving @file{*Buffer List*} visible -(@code{Buffer-menu-other-window}). - -@item C-o -@findex Buffer-menu-switch-other-window -@kindex C-o @r{(Buffer Menu)} -Display this line's buffer in another window, without selecting it -(@code{Buffer-menu-switch-other-window}). - -@item 1 -@findex Buffer-menu-1-window -@kindex 1 @r{(Buffer Menu)} -Select this line's buffer in a full-frame window -(@code{Buffer-menu-1-window}). - -@item 2 -@findex Buffer-menu-2-window -@kindex 2 @r{(Buffer Menu)} -Set up two windows on the current frame, with this line's buffer -selected in one, and a previously current buffer (aside from -@file{*Buffer List*}) in the other (@code{Buffer-menu-2-window}). - -@item b -@findex Buffer-menu-bury -@kindex b @r{(Buffer Menu)} -Bury this line's buffer (@code{Buffer-menu-bury}). - -@item m -@findex Buffer-menu-mark -@kindex m @r{(Buffer Menu)} -Mark this line's buffer to be displayed in another window if you exit -with the @kbd{v} command (@code{Buffer-menu-mark}). The display flag -is indicated by the character @samp{>} at the beginning of the line. -(A single buffer may not have both deletion and display flags.) - -@item v -@findex Buffer-menu-select -@kindex v @r{(Buffer Menu)} -Select this line's buffer, and also display in other windows any -buffers flagged with the @kbd{m} command (@code{Buffer-menu-select}). -If you have not flagged any buffers, this command is equivalent to -@kbd{1}. -@end table - - The following commands affect the entire buffer list: - -@table @kbd -@item S -@findex tabulated-list-sort -@kindex S @r{(Buffer Menu)} -Sort the Buffer Menu entries according to their values in the column -at point. With a numeric prefix argument @var{n}, sort according to -the @var{n}-th column (@code{tabulated-list-sort}). - -@item T -@findex Buffer-menu-toggle-files-only -@kindex T @r{(Buffer Menu)} -Delete, or reinsert, lines for non-file buffers -@code{Buffer-menu-toggle-files-only}). This command toggles the -inclusion of such buffers in the buffer list. -@end table - - Normally, the buffer @file{*Buffer List*} is not updated -automatically when buffers are created and killed; its contents are -just text. If you have created, deleted or renamed buffers, the way -to update @file{*Buffer List*} to show what you have done is to type -@kbd{g} (@code{revert-buffer}). You can make this happen regularly -every @code{auto-revert-interval} seconds if you enable Auto Revert -mode in this buffer, as long as it is not marked modified. Global -Auto Revert mode applies to the @file{*Buffer List*} buffer only if -@code{global-auto-revert-non-file-buffers} is non-@code{nil}. -@iftex -@inforef{Autorevert,, emacs-xtra}, for details. -@end iftex -@ifnottex -@xref{Autorevert, global-auto-revert-non-file-buffers}, for details. -@end ifnottex - -@node Indirect Buffers -@section Indirect Buffers -@cindex indirect buffer -@cindex base buffer - - An @dfn{indirect buffer} shares the text of some other buffer, which -is called the @dfn{base buffer} of the indirect buffer. In some ways it -is a buffer analogue of a symbolic link between files. - -@table @kbd -@findex make-indirect-buffer -@item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET} -Create an indirect buffer named @var{indirect-name} with base buffer -@var{base-buffer}. -@findex clone-indirect-buffer -@item M-x clone-indirect-buffer @key{RET} -Create an indirect buffer that is a twin copy of the current buffer. -@item C-x 4 c -@kindex C-x 4 c -@findex clone-indirect-buffer-other-window -Create an indirect buffer that is a twin copy of the current buffer, and -select it in another window (@code{clone-indirect-buffer-other-window}). -@end table - - The text of the indirect buffer is always identical to the text of its -base buffer; changes made by editing either one are visible immediately -in the other. But in all other respects, the indirect buffer and its -base buffer are completely separate. They can have different names, -different values of point, different narrowing, different markers, -different major modes, and different local variables. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually works by saving the -base buffer. Killing the base buffer effectively kills the indirect -buffer, but killing an indirect buffer has no effect on its base buffer. - - One way to use indirect buffers is to display multiple views of an -outline. @xref{Outline Views}. - -@vindex clone-indirect-buffer-hook - A quick and handy way to make an indirect buffer is with the command -@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect -buffer whose base buffer is the current buffer. With a numeric -argument, it prompts for the name of the indirect buffer; otherwise it -uses the name of the current buffer, with a @samp{<@var{n}>} suffix -added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window}) -works like @kbd{M-x clone-indirect-buffer}, but it selects the new -buffer in another window. These functions run the hook -@code{clone-indirect-buffer-hook} after creating the indirect buffer. - - The more general way to make an indirect buffer is with the command -@kbd{M-x make-indirect-buffer}. It creates an indirect buffer -named @var{indirect-name} from a buffer @var{base-buffer}, prompting for -both using the minibuffer. - -@node Buffer Convenience -@section Convenience Features and Customization of Buffer Handling - - This section describes several modes and features that make it more -convenient to switch between buffers. - -@menu -* Uniquify:: Making buffer names unique with directory parts. -* Icomplete:: Fast minibuffer selection. -* Buffer Menus:: Configurable buffer menu. -@end menu - -@node Uniquify -@subsection Making Buffer Names Unique - -@cindex unique buffer names -@cindex directories in buffer names - When several buffers visit identically-named files, Emacs must give -the buffers distinct names. The default method adds a suffix based on -the names of the directories that contain the files. For example, if -you visit files @file{/foo/bar/mumble/name} and -@file{/baz/quux/mumble/name} at the same time, their buffers will be -named @samp{name} and @samp{name}, respectively. -Emacs adds as many directory parts as are needed to make a unique name. - -@vindex uniquify-buffer-name-style - You can choose from several different styles for constructing unique -buffer names, by customizing the option @code{uniquify-buffer-name-style}. - - The @code{forward} naming method includes part of the file's -directory name at the beginning of the buffer name; using this method, -buffers visiting the files @file{/u/rms/tmp/Makefile} and -@file{/usr/projects/zaphod/Makefile} would be named -@samp{tmp/Makefile} and @samp{zaphod/Makefile}. - - In contrast, the @code{post-forward} naming method would call the -buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}. The default -method @code{post-forward-angle-brackets} is like @code{post-forward}, -except that it encloses the unique path in angle brackets. The -@code{reverse} naming method would call them @samp{Makefile\tmp} and -@samp{Makefile\zaphod}. The nontrivial difference between -@code{post-forward} and @code{reverse} occurs when just one directory -name is not enough to distinguish two files; then @code{reverse} puts -the directory names in reverse order, so that @file{/top/middle/file} -becomes @samp{file\middle\top}, while @code{post-forward} puts them in -forward order after the file name, as in @samp{file|top/middle}. If -@code{uniquify-buffer-name-style} is set to @code{nil}, the buffer -names simply get @samp{<2>}, @samp{<3>}, etc. appended. - - Which rule to follow for putting the directory names in the buffer -name is not very important if you are going to @emph{look} at the -buffer names before you type one. But as an experienced user, if you -know the rule, you won't have to look. And then you may find that one -rule or another is easier for you to remember and apply quickly. - -@node Icomplete -@subsection Fast minibuffer selection - -@findex icomplete-mode -@cindex Icomplete mode - - Icomplete global minor mode provides a convenient way to quickly select an -element among the possible completions in a minibuffer. When enabled, typing -in the minibuffer continuously displays a list of possible completions that -match the string you have typed. - - At any time, you can type @kbd{C-j} to select the first completion in -the list. So the way to select a particular completion is to make it the -first in the list. There are two ways to do this. You can type more -of the completion name and thus narrow down the list, excluding unwanted -completions above the desired one. Alternatively, you can use @kbd{C-.} -and @kbd{C-,} to rotate the list until the desired buffer is first. - - @kbd{M-@key{TAB}} will select the first completion in the list, like -@kbd{C-j} but without exiting the minibuffer, so you can edit it -further. This is typically used when entering a file name, where -@kbd{M-@key{TAB}} can be used a few times to descend in the hierarchy -of directories. - - To enable Icomplete mode, type @kbd{M-x icomplete-mode}, or customize -the variable @code{icomplete-mode} to @code{t} (@pxref{Easy -Customization}). - -@node Buffer Menus -@subsection Customizing Buffer Menus - -@findex bs-show -@cindex buffer list, customizable -@table @kbd -@item M-x bs-show -Make a list of buffers similarly to @kbd{M-x list-buffers} but -customizable. -@end table - - @kbd{M-x bs-show} pops up a buffer list similar to the one normally -displayed by @kbd{C-x C-b} but which you can customize. If you prefer -this to the usual buffer list, you can bind this command to @kbd{C-x -C-b}. To customize this buffer list, use the @code{bs} Custom group -(@pxref{Easy Customization}). - -@findex msb-mode -@cindex mode, MSB -@cindex MSB mode -@findex mouse-buffer-menu -@kindex C-Down-Mouse-1 - MSB global minor mode (``MSB'' stands for ``mouse select buffer'') -provides a different and customizable mouse buffer menu which you may -prefer. It replaces the bindings of @code{mouse-buffer-menu}, -normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You -can customize the menu in the @code{msb} Custom group. diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi deleted file mode 100644 index e0ed11ff862..00000000000 --- a/doc/emacs/building.texi +++ /dev/null @@ -1,1614 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Building -@chapter Compiling and Testing Programs -@cindex building programs -@cindex program building -@cindex running Lisp functions - - The previous chapter discusses the Emacs commands that are useful -for making changes in programs. This chapter deals with commands that -assist in the process of compiling and testing programs. - -@menu -* Compilation:: Compiling programs in languages other - than Lisp (C, Pascal, etc.). -* Compilation Mode:: The mode for visiting compiler errors. -* Compilation Shell:: Customizing your shell properly - for use in the compilation buffer. -* Grep Searching:: Searching with grep. -* Flymake:: Finding syntax errors on the fly. -* Debuggers:: Running symbolic debuggers for non-Lisp programs. -* Executing Lisp:: Various modes for editing Lisp programs, - with different facilities for running - the Lisp programs. -* Libraries: Lisp Libraries. How Lisp programs are loaded into Emacs. -* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. -* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. -* External Lisp:: Communicating through Emacs with a separate Lisp. -@end menu - -@node Compilation -@section Running Compilations under Emacs -@cindex inferior process -@cindex make -@cindex compilation errors -@cindex error log - - Emacs can run compilers for languages such as C and Fortran, feeding -the compilation log into an Emacs buffer. It can also parse the error -messages and show you where the errors occurred. - -@table @kbd -@item M-x compile -Run a compiler asynchronously under Emacs, with error messages going to -the @file{*compilation*} buffer. -@item M-x recompile -Invoke a compiler with the same command as in the last invocation of -@kbd{M-x compile}. -@item M-x kill-compilation -Kill the running compilation subprocess. -@end table - -@findex compile - To run @code{make} or another compilation command, type @kbd{M-x -compile}. This reads a shell command line using the minibuffer, and -then executes the command by running a shell as a subprocess (or -@dfn{inferior process}) of Emacs. The output is inserted in a buffer -named @file{*compilation*}. The current buffer's default directory is -used as the working directory for the execution of the command; -normally, therefore, compilation takes place in this directory. - -@vindex compile-command - The default compilation command is @samp{make -k}, which is usually -correct for programs compiled using the @command{make} utility (the -@samp{-k} flag tells @command{make} to continue compiling as much as -possible after an error). @xref{Top,, Make, make, GNU Make Manual}. -If you have done @kbd{M-x compile} before, the command that you -specified is automatically stored in the variable -@code{compile-command}; this is used as the default the next time you -type @kbd{M-x compile}. A file can also specify a file-local value -for @code{compile-command} (@pxref{File Variables}). - - Starting a compilation displays the @file{*compilation*} buffer in -another window but does not select it. While the compilation is -running, the word @samp{run} is shown in the major mode indicator for -the @file{*compilation*} buffer, and the word @samp{Compiling} appears -in all mode lines. You do not have to keep the @file{*compilation*} -buffer visible while compilation is running; it continues in any case. -When the compilation ends, for whatever reason, the mode line of the -@file{*compilation*} buffer changes to say @samp{exit} (followed by -the exit code: @samp{[0]} for a normal exit), or @samp{signal} (if a -signal terminated the process). - - If you want to watch the compilation transcript as it appears, -switch to the @file{*compilation*} buffer and move point to the end of -the buffer. When point is at the end, new compilation output is -inserted above point, which remains at the end. Otherwise, point -remains fixed while compilation output is added at the end of the -buffer. - -@cindex compilation buffer, keeping point at end -@vindex compilation-scroll-output - If you change the variable @code{compilation-scroll-output} to a -non-@code{nil} value, the @file{*compilation*} buffer scrolls -automatically to follow the output. If the value is -@code{first-error}, scrolling stops when the first error appears, -leaving point at that error. For any other non-@code{nil} value, -scrolling continues until there is no more output. - -@findex recompile - To rerun the last compilation with the same command, type @kbd{M-x -recompile}. This reuses the compilation command from the last -invocation of @kbd{M-x compile}. It also reuses the -@file{*compilation*} buffer and starts the compilation in its default -directory, which is the directory in which the previous compilation -was started. - -@findex kill-compilation -@vindex compilation-always-kill - Starting a new compilation also kills any compilation already -running in @file{*compilation*}, as the buffer can only handle one -compilation at any time. However, @kbd{M-x compile} asks for -confirmation before actually killing a compilation that is running; to -always automatically kill the compilation without asking, change the -variable @code{compilation-always-kill} to @code{t}. You can also -kill a compilation process with the command @kbd{M-x -kill-compilation}. - - To run two compilations at once, start the first one, then rename -the @file{*compilation*} buffer (perhaps using @code{rename-uniquely}; -@pxref{Misc Buffer}), then switch buffers and start the other -compilation. This will create a new @file{*compilation*} buffer. - -@vindex compilation-environment - You can control the environment passed to the compilation command -with the variable @code{compilation-environment}. Its value is a list -of environment variable settings; each element should be a string of -the form @code{"@var{envvarname}=@var{value}"}. These environment -variable settings override the usual ones. - -@node Compilation Mode -@section Compilation Mode - -@cindex Compilation mode -@cindex mode, Compilation -@cindex locus - The @file{*compilation*} buffer uses a major mode called Compilation -mode. Compilation mode turns each error message in the buffer into a -hyperlink; you can move point to it and type @key{RET}, or click on it -with the mouse (@pxref{Mouse References}), to visit the @dfn{locus} of -the error message in a separate window. The locus is the specific -position in a file where that error occurred. - -@findex compile-goto-error -@vindex compilation-auto-jump-to-first-error - If you change the variable -@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value, -Emacs automatically visits the locus of the first error message that -appears in the @file{*compilation*} buffer. - - Compilation mode provides the following additional commands. These -commands can also be used in @file{*grep*} buffers, where the -hyperlinks are search matches rather than error messages (@pxref{Grep -Searching}). - -@table @kbd -@item M-g M-n -@itemx M-g n -@itemx C-x ` -Visit the locus of the next error message or match (@code{next-error}). -@item M-g M-p -@itemx M-g p -Visit the locus of the previous error message or match -(@code{previous-error}). -@item M-n -Move point to the next error message or match, without visiting its -locus (@code{compilation-next-error}). -@item M-p -Move point to the previous error message or match, without visiting -its locus (@code{compilation-previous-error}). -@item M-@} -Move point to the next error message or match occurring in a different -file (@code{compilation-next-file}). -@item M-@{ -Move point to the previous error message or match occurring in a -different file (@code{compilation-previous-file}). -@item C-c C-f -Toggle Next Error Follow minor mode, which makes cursor motion in the -compilation buffer produce automatic source display. -@end table - -@kindex M-g M-n -@kindex M-g n -@kindex C-x ` -@findex next-error -@vindex next-error-highlight - To visit errors sequentially, type @w{@kbd{C-x `}} -(@code{next-error}), or equivalently @kbd{M-g M-n} or @kbd{M-g n}. -This command can be invoked from any buffer, not just a Compilation -mode buffer. The first time you invoke it after a compilation, it -visits the locus of the first error message. Each subsequent -@w{@kbd{C-x `}} visits the next error, in a similar fashion. If you -visit a specific error with @key{RET} or a mouse click in the -@file{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands -advance from there. When @w{@kbd{C-x `}} finds no more error messages -to visit, it signals an error. @w{@kbd{C-u C-x `}} starts again from -the beginning of the compilation buffer, and visits the first locus. - - @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates -through errors in the opposite direction. - - The @code{next-error} and @code{previous-error} commands don't just -act on the errors or matches listed in @file{*compilation*} and -@file{*grep*} buffers; they also know how to iterate through error or -match lists produced by other commands, such as @kbd{M-x occur} -(@pxref{Other Repeating Search}). If you are already in a buffer -containing error messages or matches, those are the ones that are -iterated through; otherwise, Emacs looks for a buffer containing error -messages or matches amongst the windows of the selected frame, then -for one that @code{next-error} or @code{previous-error} previously -iterated through, and finally amongst all other buffers. If the -buffer chosen for iterating through is not currently displayed in a -window, it will be displayed. - -@vindex compilation-skip-threshold - By default, the @code{next-error} and @code{previous-error} commands -skip less important messages. The variable -@code{compilation-skip-threshold} controls this. The default value, -1, means to skip anything less important than a warning. A value of 2 -means to skip anything less important than an error, while 0 means not -to skip any messages. - - When Emacs visits the locus of an error message, it momentarily -highlights the relevant source line. The duration of this highlight -is determined by the variable @code{next-error-highlight}. - -@vindex compilation-context-lines - If the @file{*compilation*} buffer is shown in a window with a left -fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in -the fringe, pointing to the current error message. If the window has -no left fringe, such as on a text terminal, these commands scroll the -window so that the current message is at the top of the window. If -you change the variable @code{compilation-context-lines} to an integer -value @var{n}, these commands scroll the window so that the current -error message is @var{n} lines from the top, whether or not there is a -fringe; the default value, @code{nil}, gives the behavior described -above. - -@vindex compilation-error-regexp-alist -@vindex grep-regexp-alist - To parse messages from the compiler, Compilation mode uses the -variable @code{compilation-error-regexp-alist} which lists various -error message formats and tells Emacs how to extract the locus from -each. A similar variable, @code{grep-regexp-alist}, tells Emacs how -to parse output from a @code{grep} command (@pxref{Grep Searching}). - -@findex compilation-next-error -@findex compilation-previous-error -@findex compilation-next-file -@findex compilation-previous-file - Compilation mode also defines the keys @key{SPC} and @key{DEL} to -scroll by screenfuls; @kbd{M-n} (@code{compilation-next-error}) and -@kbd{M-p} (@code{compilation-previous-error}) to move to the next or -previous error message; and @kbd{M-@{} (@code{compilation-next-file}) -and @kbd{M-@}} (@code{compilation-previous-file}) to move to the next -or previous error message for a different source file. - -@cindex Next Error Follow mode -@findex next-error-follow-minor-mode - You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In -this minor mode, ordinary cursor motion in the compilation buffer -automatically updates the source buffer, i.e., moving the cursor over -an error message causes the locus of that error to be displayed. - - The features of Compilation mode are also available in a minor mode -called Compilation Minor mode. This lets you parse error messages in -any buffer, not just a normal compilation output buffer. Type -@kbd{M-x compilation-minor-mode} to enable the minor mode. For -instance, in an Rlogin buffer (@pxref{Remote Host}), Compilation minor -mode automatically accesses remote source files by FTP (@pxref{File -Names}). - -@node Compilation Shell -@section Subshells for Compilation - - The @kbd{M-x compile} command uses a shell to run the compilation -command, but specifies the option for a noninteractive shell. This -means, in particular, that the shell should start with no prompt. If -you find your usual shell prompt making an unsightly appearance in the -@file{*compilation*} buffer, it means you have made a mistake in your -shell's init file by setting the prompt unconditionally. (This init -file may be named @file{.bashrc}, @file{.profile}, @file{.cshrc}, -@file{.shrc}, etc., depending on what shell you use.) The shell init -file should set the prompt only if there already is a prompt. Here's -how to do it in bash: - -@example -if [ "$@{PS1+set@}" = set ] -then PS1=@dots{} -fi -@end example - -@noindent -And here's how to do it in csh: - -@example -if ($?prompt) set prompt = @dots{} -@end example - - Emacs does not expect a compiler process to launch asynchronous -subprocesses; if it does, and they keep running after the main -compiler process has terminated, Emacs may kill them or their output -may not arrive in Emacs. To avoid this problem, make the main -compilation process wait for its subprocesses to finish. In a shell -script, you can do this using @samp{$!} and @samp{wait}, like this: - -@example -(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess} -echo first message -wait $pid # @r{Wait for subprocess} -@end example - -@noindent -If the background process does not output to the compilation buffer, -so you only need to prevent it from being killed when the main -compilation process terminates, this is sufficient: - -@example -nohup @var{command}; sleep 1 -@end example - -@ifnottex - On the MS-DOS ``operating system'', asynchronous subprocesses are -not supported, so @kbd{M-x compile} runs the compilation command -synchronously (i.e., you must wait until the command finishes before -you can do anything else in Emacs). @xref{MS-DOS}. -@end ifnottex - -@node Grep Searching -@section Searching with Grep under Emacs - - Just as you can run a compiler from Emacs and then visit the lines -with compilation errors, you can also run @command{grep} and then -visit the lines on which matches were found. This works by treating -the matches reported by @command{grep} as if they were ``errors''. -The output buffer uses Grep mode, which is a variant of Compilation -mode (@pxref{Compilation Mode}). - -@table @kbd -@item M-x grep -@itemx M-x lgrep -Run @command{grep} asynchronously under Emacs, listing matching lines in -the buffer named @file{*grep*}. -@item M-x grep-find -@itemx M-x find-grep -@itemx M-x rgrep -Run @command{grep} via @code{find}, and collect output in the -@file{*grep*} buffer. -@item M-x zrgrep -Run @code{zgrep} and collect output in the @file{*grep*} buffer. -@item M-x kill-grep -Kill the running @command{grep} subprocess. -@end table - -@findex grep - To run @command{grep}, type @kbd{M-x grep}, then enter a command line -that specifies how to run @command{grep}. Use the same arguments you -would give @command{grep} when running it normally: a @command{grep}-style -regexp (usually in single-quotes to quote the shell's special -characters) followed by file names, which may use wildcards. If you -specify a prefix argument for @kbd{M-x grep}, it finds the tag -(@pxref{Tags}) in the buffer around point, and puts that into the -default @command{grep} command. - - Your command need not simply run @command{grep}; you can use any shell -command that produces output in the same format. For instance, you -can chain @command{grep} commands, like this: - -@example -grep -nH -e foo *.el | grep bar | grep toto -@end example - - The output from @command{grep} goes in the @file{*grep*} buffer. You -can find the corresponding lines in the original files using @w{@kbd{C-x -`}}, @key{RET}, and so forth, just like compilation errors. - - Some grep programs accept a @samp{--color} option to output special -markers around matches for the purpose of highlighting. You can make -use of this feature by setting @code{grep-highlight-matches} to -@code{t}. When displaying a match in the source buffer, the exact -match will be highlighted, instead of the entire source line. - -@findex grep-find -@findex find-grep - The command @kbd{M-x grep-find} (also available as @kbd{M-x -find-grep}) is similar to @kbd{M-x grep}, but it supplies a different -initial default for the command---one that runs both @code{find} and -@command{grep}, so as to search every file in a directory tree. See also -the @code{find-grep-dired} command, in @ref{Dired and Find}. - -@findex lgrep -@findex rgrep -@findex zrgrep - The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep} -(recursive grep) are more user-friendly versions of @command{grep} and -@code{grep-find}, which prompt separately for the regular expression -to match, the files to search, and the base directory for the search. -Case sensitivity of the search is controlled by the current value of -@code{case-fold-search}. The command @kbd{M-x zrgrep} is similar to -@kbd{M-x rgrep}, but it calls @command{zgrep} instead of -@command{grep} to search the contents of gzipped files. - - These commands build the shell commands based on the variables -@code{grep-template} (for @code{lgrep}) and @code{grep-find-template} -(for @code{rgrep}). The files to search can use aliases defined in -the variable @code{grep-files-aliases}. - -@vindex grep-find-ignored-directories - Directories listed in the variable -@code{grep-find-ignored-directories} are automatically skipped by -@kbd{M-x rgrep}. The default value includes the data directories used -by various version control systems. - -@node Flymake -@section Finding Syntax Errors On The Fly -@cindex checking syntax - - Flymake mode is a minor mode that performs on-the-fly syntax -checking for many programming and markup languages, including C, C++, -Perl, HTML, and @TeX{}/@LaTeX{}. It is somewhat analogous to Flyspell -mode, which performs spell checking for ordinary human languages in a -similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode -runs an appropriate syntax checking tool in the background, using a -temporary copy of the buffer. It then parses the error and warning -messages, and highlights the erroneous lines in the buffer. The -syntax checking tool used depends on the language; for example, for -C/C++ files this is usually the C compiler. Flymake can also use -build tools such as @code{make} for checking complicated projects. - - To enable Flymake mode, type @kbd{M-x flymake-mode}. You can jump -to the errors that it finds by using @kbd{M-x flymake-goto-next-error} -and @kbd{M-x flymake-goto-prev-error}. To display any error messages -associated with the current line, type @kbd{M-x -flymake-display-err-menu-for-current-line}. - - For more details about using Flymake, -@ifnottex -see @ref{Top, Flymake, Flymake, flymake, The Flymake Manual}. -@end ifnottex -@iftex -see the Flymake Info manual, which is distributed with Emacs. -@end iftex - -@node Debuggers -@section Running Debuggers Under Emacs -@cindex debuggers -@cindex GUD library -@cindex GDB -@cindex DBX -@cindex SDB -@cindex XDB -@cindex Perldb -@cindex JDB -@cindex PDB - -The GUD (Grand Unified Debugger) library provides an Emacs interface -to a wide variety of symbolic debuggers. It can run the GNU Debugger -(GDB), as well as DBX, SDB, XDB, Perl's debugging mode, the Python -debugger PDB, and the Java Debugger JDB. - - Emacs provides a special interface to GDB, which uses extra Emacs -windows to display the state of the debugged program. @xref{GDB -Graphical Interface}. - - Emacs also has a built-in debugger for Emacs Lisp programs. -@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference -Manual}. - -@menu -* Starting GUD:: How to start a debugger subprocess. -* Debugger Operation:: Connection between the debugger and source buffers. -* Commands of GUD:: Key bindings for common commands. -* GUD Customization:: Defining your own commands for GUD. -* GDB Graphical Interface:: An enhanced mode that uses GDB features to - implement a graphical debugging environment. -@end menu - -@node Starting GUD -@subsection Starting GUD - - There are several commands for starting a debugger subprocess, each -corresponding to a particular debugger program. - -@table @kbd -@item M-x gdb -@findex gdb -Run GDB as a subprocess, and interact with it via an IDE-like Emacs -interface. @xref{GDB Graphical Interface}, for more information about -this command. - -@item M-x gud-gdb -@findex gud-gdb -Run GDB, using a GUD interaction buffer for input and output to the -GDB subprocess (@pxref{Debugger Operation}). If such a buffer already -exists, switch to it; otherwise, create the buffer and switch to it. - -The other commands in this list do the same, for other debugger -programs. - -@item M-x perldb -@findex perldb -Run the Perl interpreter in debug mode. - -@item M-x jdb -@findex jdb -Run the Java debugger. - -@item M-x pdb -@findex pdb -Run the Python debugger. - -@item M-x dbx -@findex dbx -Run the DBX debugger. - -@item M-x xdb -@findex xdb -@vindex gud-xdb-directories -Run the XDB debugger. - -@item M-x sdb -@findex sdb -Run the SDB debugger. -@end table - - Each of these commands reads a command line to invoke the debugger, -using the minibuffer. The minibuffer's initial contents contain the -standard executable name and options for the debugger, and sometimes -also a guess for the name of the executable file you want to debug. -Shell wildcards and variables are not allowed in this command line. -Emacs assumes that the first command argument which does not start -with a @samp{-} is the executable file name. - -@cindex remote host, debugging on - Tramp provides a facility for remote debugging, whereby both the -debugger and the program being debugged are on the same remote host. -@xref{Running a debugger on a remote host,,, tramp, The Tramp Manual}, -for details. This is separate from GDB's remote debugging feature, -where the program and the debugger run on different machines -(@pxref{Remote Debugging,, Debugging Remote Programs, gdb, The GNU -debugger}). - -@node Debugger Operation -@subsection Debugger Operation -@cindex GUD interaction buffer - - The @dfn{GUD interaction buffer} is an Emacs buffer which is used to -send text commands to a debugger subprocess, and record its output. -This is the basic interface for interacting with a debugger, used by -@kbd{M-x gud-gdb} and other commands listed in -@iftex -the preceding section. -@end iftex -@ifnottex -@ref{Starting GUD}. -@end ifnottex -The @kbd{M-x gdb} command extends this interface with additional -specialized buffers for controlling breakpoints, stack frames, and -other aspects of the debugger state (@pxref{GDB Graphical Interface}). - - The GUD interaction buffer uses a variant of Shell mode, so the -Emacs commands defined by Shell mode are available (@pxref{Shell -Mode}). Completion is available for most debugger commands -(@pxref{Completion}), and you can use the usual Shell mode history -commands to repeat them. -@iftex -See the next section -@end iftex -@ifnottex -@xref{Commands of GUD}, -@end ifnottex -for special commands that can be used in the GUD interaction buffer. - - As you debug a program, Emacs displays the relevant source files by -visiting them in Emacs buffers, with an arrow in the left fringe -indicating the current execution line. (On a text terminal, the arrow -appears as @samp{=>}, overlaid on the first two text columns.) Moving -point in such a buffer does not move the arrow. You are free to edit -these source files, but note that inserting or deleting lines will -throw off the arrow's positioning, as Emacs has no way to figure out -which edited source line corresponds to the line reported by the -debugger subprocess. To update this information, you typically have -to recompile and restart the program. - -@cindex GUD Tooltip mode -@cindex mode, GUD Tooltip -@findex gud-tooltip-mode -@vindex gud-tooltip-echo-area - GUD Tooltip mode is a global minor mode that adds tooltip support to -GUD@. To toggle this mode, type @kbd{M-x gud-tooltip-mode}. It is -disabled by default. If enabled, you can move the mouse cursor over a -variable, a function, or a macro (collectively called -@dfn{identifiers}) to show their values in tooltips -(@pxref{Tooltips}). Alternatively, mark an identifier or an -expression by dragging the mouse over it, then leave the mouse in the -marked area to have the value of the expression displayed in a -tooltip. The GUD Tooltip mode takes effect in the GUD interaction -buffer, and in all source buffers with major modes listed in the -variable @code{gud-tooltip-modes}. If the variable -@code{gud-tooltip-echo-area} is non-@code{nil}, or if you turned off -the tooltip mode, values are shown in the echo area instead of a -tooltip. - - When using GUD Tooltip mode with @kbd{M-x gud-gdb}, displaying an -expression's value in GDB can sometimes expand a macro, potentially -causing side effects in the debugged program. For that reason, using -tooltips in @code{gud-gdb} is disabled. If you use the @kbd{M-x gdb} -interface, this problem does not occur, as there is special code to -avoid side-effects; furthermore, you can display macro definitions -associated with an identifier when the program is not executing. - -@node Commands of GUD -@subsection Commands of GUD - - GUD provides commands for setting and clearing breakpoints, -selecting stack frames, and stepping through the program. - -@table @kbd -@item C-x C-a C-b -@kindex C-x C-a C-b -Set a breakpoint on the source line that point is on. -@end table - - @kbd{C-x C-a C-b} (@code{gud-break}), when called in a source -buffer, sets a debugger breakpoint on the current source line. This -command is available only after starting GUD@. If you call it in a -buffer that is not associated with any debugger subprocess, it signals -a error. - -@kindex C-x C-a @r{(GUD)} - The following commands are available both in the GUD interaction -buffer and globally, but with different key bindings. The keys -starting with @kbd{C-c} are available only in the GUD interaction -buffer, while those starting with @kbd{C-x C-a} are available -globally. Some of these commands are also available via the tool bar; -some are not supported by certain debuggers. - -@table @kbd -@item C-c C-l -@kindex C-c C-l @r{(GUD)} -@itemx C-x C-a C-l -@findex gud-refresh -Display, in another window, the last source line referred to in the -GUD interaction buffer (@code{gud-refresh}). - -@item C-c C-s -@kindex C-c C-s @r{(GUD)} -@itemx C-x C-a C-s -@findex gud-step -Execute the next single line of code (@code{gud-step}). If the line -contains a function call, execution stops after entering the called -function. - -@item C-c C-n -@kindex C-c C-n @r{(GUD)} -@itemx C-x C-a C-n -@findex gud-next -Execute the next single line of code, stepping across function calls -without stopping inside the functions (@code{gud-next}). - -@item C-c C-i -@kindex C-c C-i @r{(GUD)} -@itemx C-x C-a C-i -@findex gud-stepi -Execute a single machine instruction (@code{gud-stepi}). - -@item C-c C-p -@kindex C-c C-p @r{(GUD)} -@itemx C-x C-a C-p -@findex gud-print -Evaluate the expression at point (@code{gud-print}). If Emacs -does not print the exact expression that you want, mark it as a region -first. - -@need 3000 -@item C-c C-r -@kindex C-c C-r @r{(GUD)} -@itemx C-x C-a C-r -@findex gud-cont -Continue execution without specifying any stopping point. The program -will run until it hits a breakpoint, terminates, or gets a signal that -the debugger is checking for (@code{gud-cont}). - -@need 1000 -@item C-c C-d -@kindex C-c C-d @r{(GUD)} -@itemx C-x C-a C-d -@findex gud-remove -Delete the breakpoint(s) on the current source line, if any -(@code{gud-remove}). If you use this command in the GUD interaction -buffer, it applies to the line where the program last stopped. - -@item C-c C-t -@kindex C-c C-t @r{(GUD)} -@itemx C-x C-a C-t -@findex gud-tbreak -Set a temporary breakpoint on the current source line, if any -(@code{gud-tbreak}). If you use this command in the GUD interaction -buffer, it applies to the line where the program last stopped. - -@item C-c < -@kindex C-c < @r{(GUD)} -@itemx C-x C-a < -@findex gud-up -Select the next enclosing stack frame (@code{gud-up}). This is -equivalent to the GDB command @samp{up}. - -@item C-c > -@kindex C-c > @r{(GUD)} -@itemx C-x C-a > -@findex gud-down -Select the next inner stack frame (@code{gud-down}). This is -equivalent to the GDB command @samp{down}. - -@item C-c C-u -@kindex C-c C-u @r{(GUD)} -@itemx C-x C-a C-u -@findex gud-until -Continue execution to the current line (@code{gud-until}). The -program will run until it hits a breakpoint, terminates, gets a signal -that the debugger is checking for, or reaches the line on which the -cursor currently sits. - -@item C-c C-f -@kindex C-c C-f @r{(GUD)} -@itemx C-x C-a C-f -@findex gud-finish -Run the program until the selected stack frame returns or -stops for some other reason (@code{gud-finish}). -@end table - - If you are using GDB, these additional key bindings are available: - -@table @kbd -@item C-x C-a C-j -@kindex C-x C-a C-j @r{(GUD)} -@findex gud-jump -Only useful in a source buffer, @code{gud-jump} transfers the -program's execution point to the current line. In other words, the -next line that the program executes will be the one where you gave the -command. If the new execution line is in a different function from -the previously one, GDB prompts for confirmation since the results may -be bizarre. See the GDB manual entry regarding @code{jump} for -details. - -@item @key{TAB} -@kindex TAB @r{(GUD)} -@findex gud-gdb-complete-command -With GDB, complete a symbol name (@code{gud-gdb-complete-command}). -This key is available only in the GUD interaction buffer. -@end table - - These commands interpret a numeric argument as a repeat count, when -that makes sense. - - Because @key{TAB} serves as a completion command, you can't use it to -enter a tab as input to the program you are debugging with GDB@. -Instead, type @kbd{C-q @key{TAB}} to enter a tab. - -@node GUD Customization -@subsection GUD Customization - -@vindex gdb-mode-hook -@vindex dbx-mode-hook -@vindex sdb-mode-hook -@vindex xdb-mode-hook -@vindex perldb-mode-hook -@vindex pdb-mode-hook -@vindex jdb-mode-hook - On startup, GUD runs one of the following hooks: -@code{gdb-mode-hook}, if you are using GDB; @code{dbx-mode-hook}, if -you are using DBX; @code{sdb-mode-hook}, if you are using SDB; -@code{xdb-mode-hook}, if you are using XDB; @code{perldb-mode-hook}, -for Perl debugging mode; @code{pdb-mode-hook}, for PDB; -@code{jdb-mode-hook}, for JDB@. @xref{Hooks}. - - The @code{gud-def} Lisp macro (@pxref{Defining Macros,,, elisp, the -Emacs Lisp Reference Manual}) provides a convenient way to define an -Emacs command that sends a particular command string to the debugger, -and set up a key binding for in the GUD interaction buffer: - -@findex gud-def -@example -(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring}) -@end example - - This defines a command named @var{function} which sends -@var{cmdstring} to the debugger process, and gives it the documentation -string @var{docstring}. You can then use the command @var{function} in any -buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds -the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to -@kbd{C-x C-a @var{binding}} generally. - - The command string @var{cmdstring} may contain certain -@samp{%}-sequences that stand for data to be filled in at the time -@var{function} is called: - -@table @samp -@item %f -The name of the current source file. If the current buffer is the GUD -buffer, then the ``current source file'' is the file that the program -stopped in. - -@item %l -The number of the current source line. If the current buffer is the GUD -buffer, then the ``current source line'' is the line that the program -stopped in. - -@item %e -In transient-mark-mode the text in the region, if it is active. -Otherwise the text of the C lvalue or function-call expression at or -adjacent to point. - -@item %a -The text of the hexadecimal address at or adjacent to point. - -@item %p -The numeric argument of the called function, as a decimal number. If -the command is used without a numeric argument, @samp{%p} stands for the -empty string. - -If you don't use @samp{%p} in the command string, the command you define -ignores any numeric argument. - -@item %d -The name of the directory of the current source file. - -@item %c -Fully qualified class name derived from the expression surrounding point -(jdb only). -@end table - -@node GDB Graphical Interface -@subsection GDB Graphical Interface - - The command @kbd{M-x gdb} starts GDB in an IDE-like interface, with -specialized buffers for controlling breakpoints, stack frames, and -other aspects of the debugger state. It also provides additional ways -to control the debugging session with the mouse, such as clicking in -the fringe of a source buffer to set a breakpoint there. - -@vindex gud-gdb-command-name - To run GDB using just the GUD interaction buffer interface, without -these additional features, use @kbd{M-x gud-gdb} (@pxref{Starting -GUD}). You must use this if you want to debug multiple programs -within one Emacs session, as that is currently unsupported by @kbd{M-x -gdb}. - - Internally, @kbd{M-x gdb} informs GDB that its ``screen size'' is -unlimited; for correct operation, you must not change GDB's screen -height and width values during the debugging session. - -@menu -* GDB User Interface Layout:: Control the number of displayed buffers. -* Source Buffers:: Use the mouse in the fringe/margin to - control your program. -* Breakpoints Buffer:: A breakpoint control panel. -* Threads Buffer:: Displays your threads. -* Stack Buffer:: Select a frame from the call stack. -* Other GDB Buffers:: Other buffers for controlling the GDB state. -* Watch Expressions:: Monitor variable values in the speedbar. -* Multithreaded Debugging:: Debugging programs with several threads. -@end menu - -@node GDB User Interface Layout -@subsubsection GDB User Interface Layout -@cindex GDB User Interface layout - -@vindex gdb-many-windows - If the variable @code{gdb-many-windows} is @code{nil} (the default), -@kbd{M-x gdb} normally displays only the GUD interaction buffer. -However, if the variable @code{gdb-show-main} is also non-@code{nil}, -it starts with two windows: one displaying the GUD interaction buffer, -and the other showing the source for the @code{main} function of the -program you are debugging. - - If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} -displays the following frame layout: - -@smallexample -@group -+--------------------------------+--------------------------------+ -| GUD interaction buffer | Locals/Registers buffer | -|--------------------------------+--------------------------------+ -| Primary Source buffer | I/O buffer for debugged pgm | -|--------------------------------+--------------------------------+ -| Stack buffer | Breakpoints/Threads buffer | -+--------------------------------+--------------------------------+ -@end group -@end smallexample - -@findex gdb-restore-windows -@findex gdb-many-windows - If you ever change the window layout, you can restore the ``many -windows'' layout by typing @kbd{M-x gdb-restore-windows}. To toggle -between the many windows layout and a simple layout with just the GUD -interaction buffer and a source file, type @kbd{M-x gdb-many-windows}. - - You may also specify additional GDB-related buffers to display, -either in the same frame or a different one. Select the buffers you -want by typing @code{M-x gdb-display-@var{buffertype}-buffer} or -@code{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype} -is the relevant buffer type, such as @samp{breakpoints}. You can do -the same with the menu bar, with the @samp{GDB-Windows} and -@samp{GDB-Frames} sub-menus of the @samp{GUD} menu. - - When you finish debugging, kill the GUD interaction buffer with -@kbd{C-x k}, which will also kill all the buffers associated with the -session. However you need not do this if, after editing and -re-compiling your source code within Emacs, you wish to continue -debugging. When you restart execution, GDB automatically finds the -new executable. Keeping the GUD interaction buffer has the advantage -of keeping the shell history as well as GDB's breakpoints. You do -need to check that the breakpoints in recently edited source files are -still in the right places. - -@node Source Buffers -@subsubsection Source Buffers -@cindex fringes, for debugging - -@table @asis -@item @kbd{Mouse-1} (in fringe) -Set or clear a breakpoint on that line. - -@item @kbd{C-Mouse-1} (in fringe) -Enable or disable a breakpoint on that line. - -@item @kbd{Mouse-3} (in fringe) -Continue execution to that line. - -@item @kbd{C-Mouse-3} (in fringe) -Jump to that line. -@end table - - On a graphical display, you can click @kbd{Mouse-1} in the fringe of -a source buffer, to set a breakpoint on that line (@pxref{Fringes}). -A red dot appears in the fringe, where you clicked. If a breakpoint -already exists there, the click removes it. A @kbd{C-Mouse-1} click -enables or disables an existing breakpoint; a breakpoint that is -disabled, but not unset, is indicated by a gray dot. - - On a text terminal, or when fringes are disabled, enabled -breakpoints are indicated with a @samp{B} character in the left margin -of the window. Disabled breakpoints are indicated with @samp{b}. -(The margin is only displayed if a breakpoint is present.) - - A solid arrow in the left fringe of a source buffer indicates the -line of the innermost frame where the debugged program has stopped. A -hollow arrow indicates the current execution line of a higher-level -frame. If you drag the arrow in the fringe with @kbd{Mouse-1}, that -causes execution to advance to the line where you release the button. -Alternatively, you can click @kbd{Mouse-3} in the fringe to advance to -that line. You can click @kbd{C-Mouse-3} in the fringe to jump to -that line without executing the intermediate lines. This command -allows you to go backwards, which can be useful for running through -code that has already executed, in order to examine its execution in -more detail. - -@node Breakpoints Buffer -@subsubsection Breakpoints Buffer - - The GDB Breakpoints buffer shows the breakpoints, watchpoints and -catchpoints in the debugger session. @xref{Breakpoints,,, gdb, The -GNU debugger}. It provides the following commands, which mostly apply -to the @dfn{current breakpoint} (the breakpoint which point is on): - -@table @kbd -@item @key{SPC} -@kindex SPC @r{(GDB Breakpoints buffer)} -@findex gdb-toggle-breakpoint -Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}). On -a graphical display, this changes the color of the dot in the fringe -of the source buffer at that line. The dot is red when the breakpoint -is enabled, and gray when it is disabled. - -@item D -@kindex D @r{(GDB Breakpoints buffer)} -@findex gdb-delete-breakpoint -Delete the current breakpoint (@code{gdb-delete-breakpoint}). - -@item @key{RET} -@kindex RET @r{(GDB Breakpoints buffer)} -@findex gdb-goto-breakpoint -Visit the source line for the current breakpoint -(@code{gdb-goto-breakpoint}). - -@item Mouse-2 -@kindex Mouse-2 @r{(GDB Breakpoints buffer)} -Visit the source line for the breakpoint you click on. -@end table - -@vindex gdb-show-threads-by-default - When @code{gdb-many-windows} is non-@code{nil}, the GDB Breakpoints -buffer shares its window with the GDB Threads buffer. To switch from -one to the other click with @kbd{Mouse-1} on the relevant button in -the header line. If @code{gdb-show-threads-by-default} is -non-@code{nil}, the GDB Threads buffer is the one shown by default. - -@node Threads Buffer -@subsubsection Threads Buffer - -@findex gdb-select-thread - The GDB Threads buffer displays a summary of the threads in the -debugged program. @xref{Threads, Threads, Debugging programs with -multiple threads, gdb, The GNU debugger}. To select a thread, move -point there and press @key{RET} (@code{gdb-select-thread}), or click on -it with @kbd{Mouse-2}. This also displays the associated source -buffer, and updates the contents of the other GDB buffers. - - You can customize variables under @code{gdb-buffers} group to select -fields included in GDB Threads buffer. - -@table @code -@item gdb-thread-buffer-verbose-names -@vindex gdb-thread-buffer-verbose-names -Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}. - -@item gdb-thread-buffer-arguments -@vindex gdb-thread-buffer-arguments -Show arguments of thread top frames. - -@item gdb-thread-buffer-locations -@vindex gdb-thread-buffer-locations -Show file information or library names. - -@item gdb-thread-buffer-addresses -@vindex gdb-thread-buffer-addresses -Show addresses for thread frames in threads buffer. -@end table - - To view information for several threads simultaneously, use the -following commands from the GDB Threads buffer. - -@table @kbd -@item d -@kindex d @r{(GDB threads buffer)} -@findex gdb-display-disassembly-for-thread -Display disassembly buffer for the thread at current line -(@code{gdb-display-disassembly-for-thread}). - -@item f -@kindex f @r{(GDB threads buffer)} -@findex gdb-display-stack-for-thread -Display the GDB Stack buffer for the thread at current line -(@code{gdb-display-stack-for-thread}). - -@item l -@kindex l @r{(GDB threads buffer)} -@findex gdb-display-locals-for-thread -Display the GDB Locals buffer for the thread at current line -(@code{gdb-display-locals-for-thread}). - -@item r -@kindex r @r{(GDB threads buffer)} -@findex gdb-display-registers-for-thread -Display the GDB Registers buffer for the thread at current line -(@code{gdb-display-registers-for-thread}). -@end table - -@noindent -Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R}, -display the corresponding buffer in a new frame. - - When you create a buffer showing information about some specific -thread, it becomes bound to that thread and keeps showing actual -information while you debug your program. The mode indicator for each -GDB buffer shows the number of thread it is showing information about. -The thread number is also included in the buffer name of bound -buffers. - - Further commands are available in the GDB Threads buffer which -depend on the mode of GDB that is used for controlling execution of -your program. @xref{Multithreaded Debugging}. - -@node Stack Buffer -@subsubsection Stack Buffer - - The GDB Stack buffer displays a @dfn{call stack}, with one line for -each of the nested subroutine calls (@dfn{stack frames}) in the -debugger session. @xref{Backtrace,, Backtraces, gdb, The GNU -debugger}. - -@findex gdb-frames-select - On graphical displays, the selected stack frame is indicated by an -arrow in the fringe. On text terminals, or when fringes are disabled, -the selected stack frame is displayed in reverse contrast. To select -a stack frame, move point in its line and type @key{RET} -(@code{gdb-frames-select}), or click @kbd{Mouse-2} on it. Doing so -also updates the Locals buffer -@ifnottex -(@pxref{Other GDB Buffers}). -@end ifnottex -@iftex -(described in the next section). -@end iftex - -@node Other GDB Buffers -@subsubsection Other GDB Buffers - -@table @asis -@item Locals Buffer -This buffer displays the values of local variables of the current -frame for simple data types (@pxref{Frame Info, Frame Info, -Information on a frame, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on the value if you want to edit it. - -Arrays and structures display their type only. With GDB 6.4 or later, -you can examine the value of the local variable at point by typing -@key{RET}, or with a @kbd{Mouse-2} click. With earlier versions of -GDB, use @key{RET} or @kbd{Mouse-2} on the type description -(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}. - -@item Registers Buffer -@findex toggle-gdb-all-registers -This buffer displays the values held by the registers -(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on a register if you want to edit its value. With -GDB 6.4 or later, recently changed register values display with -@code{font-lock-warning-face}. - -@item Assembler Buffer -The assembler buffer displays the current frame as machine code. An -arrow points to the current instruction, and you can set and remove -breakpoints as in a source buffer. Breakpoint icons also appear in -the fringe or margin. - -@item Memory Buffer -The memory buffer lets you examine sections of program memory -(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). -Click @kbd{Mouse-1} on the appropriate part of the header line to -change the starting address or number of data items that the buffer -displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click -@kbd{Mouse-3} on the header line to select the display format or unit -size for these data items. -@end table - -When @code{gdb-many-windows} is non-@code{nil}, the locals buffer -shares its window with the registers buffer, just like breakpoints and -threads buffers. To switch from one to the other, click with -@kbd{Mouse-1} on the relevant button in the header line. - -@node Watch Expressions -@subsubsection Watch Expressions -@cindex Watching expressions in GDB - -@findex gud-watch -@kindex C-x C-a C-w @r{(GUD)} - If you want to see how a variable changes each time your program -stops, move point into the variable name and click on the watch icon -in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you -specify a prefix argument, you can enter the variable name in the -minibuffer. - - Each watch expression is displayed in the speedbar -(@pxref{Speedbar}). Complex data types, such as arrays, structures -and unions are represented in a tree format. Leaves and simple data -types show the name of the expression and its value and, when the -speedbar frame is selected, display the type as a tooltip. Higher -levels show the name, type and address value for pointers and just the -name and type otherwise. Root expressions also display the frame -address as a tooltip to help identify the frame in which they were -defined. - - To expand or contract a complex data type, click @kbd{Mouse-2} or -press @key{SPC} on the tag to the left of the expression. Emacs asks -for confirmation before expanding the expression if its number of -immediate children exceeds the value of the variable -@code{gdb-max-children}. - -@kindex D @r{(GDB speedbar)} -@findex gdb-var-delete - To delete a complex watch expression, move point to the root -expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}). - -@kindex RET @r{(GDB speedbar)} -@findex gdb-edit-value - To edit a variable with a simple data type, or a simple element of a -complex data type, move point there in the speedbar and type @key{RET} -(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to -edit it. Either way, this reads the new value using the minibuffer. - -@vindex gdb-show-changed-values - If you set the variable @code{gdb-show-changed-values} to -non-@code{nil} (the default value), Emacs uses -@code{font-lock-warning-face} to highlight values that have recently -changed and @code{shadow} face to make variables which have gone out of -scope less noticeable. When a variable goes out of scope you can't -edit its value. - -@vindex gdb-delete-out-of-scope - If the variable @code{gdb-delete-out-of-scope} is non-@code{nil} -(the default value), Emacs automatically deletes watch expressions -which go out of scope. Sometimes, when re-entering the same function, -it may be useful to set this value to @code{nil} so that you don't -need to recreate the watch expression. - -@vindex gdb-use-colon-colon-notation - If the variable @code{gdb-use-colon-colon-notation} is -non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}} -format. This allows the user to display watch expressions which share -the same variable name. The default value is @code{nil}. - -@vindex gdb-speedbar-auto-raise -To automatically raise the speedbar every time the display of watch -expressions updates, set @code{gdb-speedbar-auto-raise} to -non-@code{nil}. This can be useful if you are debugging with a full -screen Emacs frame. - -@node Multithreaded Debugging -@subsubsection Multithreaded Debugging -@cindex Multithreaded debugging in GDB -@cindex Non-stop debugging in GDB - - In GDB's @dfn{all-stop mode}, whenever your program stops, all -execution threads stop. Likewise, whenever you restart the program, -all threads start executing. @xref{All-Stop Mode, , All-Stop Mode, -gdb, The GNU debugger}. For some multi-threaded targets, GDB supports -a further mode of operation, called @dfn{non-stop mode}, in which you -can examine stopped program threads in the debugger while other -threads continue to execute freely. @xref{Non-Stop Mode, , Non-Stop -Mode, gdb, The GNU debugger}. Versions of GDB prior to 7.0 do not -support non-stop mode, and it does not work on all targets. - -@vindex gdb-non-stop-setting - The variable @code{gdb-non-stop-setting} determines whether Emacs -runs GDB in all-stop mode or non-stop mode. The default is @code{t}, -which means it tries to use non-stop mode if that is available. If -you change the value to @code{nil}, or if non-stop mode is -unavailable, Emacs runs GDB in all-stop mode. The variable takes -effect when Emacs begins a debugging session; if you change its value, -you should restart any active debugging session. - -@vindex gdb-switch-when-another-stopped - When a thread stops in non-stop mode, Emacs usually switches to that -thread. If you don't want Emacs to do this switch if another stopped -thread is already selected, change the variable -@code{gdb-switch-when-another-stopped} to @code{nil}. - -@vindex gdb-switch-reasons - Emacs can decide whether or not to switch to the stopped thread -depending on the reason which caused the stop. Customize the variable -@code{gdb-switch-reasons} to select the stop reasons which will cause -a thread switch. - -@vindex gdb-stopped-functions - The variable @code{gdb-stopped-functions} allows you to execute your -functions whenever some thread stops. - - In non-stop mode, you can switch between different modes for GUD -execution control commands. - -@vindex gdb-gud-control-all-threads -@table @dfn -@item Non-stop/A - - When @code{gdb-gud-control-all-threads} is @code{t} (the default -value), interruption and continuation commands apply to all threads, -so you can halt or continue all your threads with one command using -@code{gud-stop-subjob} and @code{gud-cont}, respectively. The -@samp{Go} button is shown on the toolbar when at least one thread is -stopped, whereas @samp{Stop} button is shown when at least one thread -is running. - -@item Non-stop/T - -When @code{gdb-gud-control-all-threads} is @code{nil}, only the -current thread is stopped/continued. @samp{Go} and @samp{Stop} -buttons on the GUD toolbar are shown depending on the state of current -thread. -@end table - -You can change the current value of @code{gdb-gud-control-all-threads} -from the tool bar or from @samp{GUD->GDB-MI} menu. - - Stepping commands always apply to the current thread. - - In non-stop mode, you can interrupt/continue your threads without -selecting them. Hitting @kbd{i} in threads buffer interrupts thread -under point, @kbd{c} continues it, @kbd{s} steps through. More such -commands may be added in the future. - - Note that when you interrupt a thread, it stops with the -@samp{signal received} reason. If that reason is included in your -@code{gdb-switch-reasons} (it is by default), Emacs will switch to -that thread. - -@node Executing Lisp -@section Executing Lisp Expressions - - Emacs has major modes for several variants of Lisp. They use the -same editing commands as other programming language modes -(@pxref{Programs}). In addition, they provide special commands for -executing Lisp expressions. - -@table @asis -@item Emacs Lisp mode -The mode for editing Emacs Lisp source files. It defines @kbd{C-M-x} -to evaluate the current top-level Lisp expression. @xref{Lisp Eval}. - -@item Lisp Interaction mode -The mode for an interactive Emacs Lisp session. It defines @kbd{C-j} -to evaluate the expression before point and insert its value in the -buffer. @xref{Lisp Interaction}. - -@item Lisp mode -The mode for editing source files of programs that run in Lisps other -than Emacs Lisp. It defines @kbd{C-M-x} to evaluate the current -top-level expression in an external Lisp. @xref{External Lisp}. - -@item Inferior Lisp mode -The mode for an interactive session with an external Lisp which is -being run as a subprocess (or @dfn{inferior process}) of Emacs. -@ifnottex -@xref{External Lisp}. -@end ifnottex - -@item Scheme mode -Like Lisp mode, but for Scheme programs. - -@item Inferior Scheme mode -Like Inferior Lisp mode, but for Scheme. -@end table - -@node Lisp Libraries -@section Libraries of Lisp Code for Emacs -@cindex libraries -@cindex loading Lisp code - - Emacs Lisp code is stored in files whose names conventionally end in -@file{.el}. Such files are automatically visited in Emacs Lisp mode. - -@cindex byte code - Emacs Lisp code can be compiled into byte-code, which loads faster, -takes up less space, and executes faster. By convention, compiled -Emacs Lisp code goes in a separate file whose name ends in -@samp{.elc}. For example, the compiled code for @file{foo.el} goes in -@file{foo.elc}. @xref{Byte Compilation,, Byte Compilation, elisp, the -Emacs Lisp Reference Manual}. - -@findex load-file - To @dfn{load} an Emacs Lisp file, type @kbd{M-x load-file}. This -command reads a file name using the minibuffer, and executes the -contents of that file as Emacs Lisp code. It is not necessary to -visit the file first; this command reads the file directly from disk, -not from an existing Emacs buffer. - -@findex load -@findex load-library -@vindex load-prefer-newer -@cindex load path for Emacs Lisp - If an Emacs Lisp file is installed in the Emacs Lisp @dfn{load path} -(defined below), you can load it by typing @kbd{M-x load-library}, -instead of using @kbd{M-x load-file}. The @kbd{M-x load-library} -command prompts for a @dfn{library name} rather than a file name; it -searches through each directory in the Emacs Lisp load path, trying to -find a file matching that library name. If the library name is -@samp{@var{foo}}, it tries looking for files named -@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}. The -default behaviour is to load the first file found. This command -prefers @file{.elc} files over @file{.el} files because compiled files -load and run faster. If it finds that @file{@var{lib}.el} is newer -than @file{@var{lib}.elc}, it issues a warning, in case someone made -changes to the @file{.el} file and forgot to recompile it, but loads -the @file{.elc} file anyway. (Due to this behavior, you can save -unfinished edits to Emacs Lisp source files, and not recompile until -your changes are ready for use.) If you set the option -@code{load-prefer-newer} to a non-@code{nil} value, however, then -rather than the procedure described above, Emacs loads whichever -version of the file is newest. - - Emacs Lisp programs usually load Emacs Lisp files using the -@code{load} function. This is similar to @code{load-library}, but is -lower-level and accepts additional arguments. @xref{How Programs Do -Loading,,, elisp, the Emacs Lisp Reference Manual}. - -@vindex load-path - The Emacs Lisp load path is specified by the variable -@code{load-path}. Its value should be a list of directory names -(strings). These directories are searched, in the specified order, by -the @kbd{M-x load-library} command, the lower-level @code{load} -function, and other Emacs functions that find Emacs Lisp libraries. A -list entry in @code{load-path} can also have the special value -@code{nil}, which stands for the current default directory, but it is -almost always a bad idea to use this. (If you find yourself wishing -that @code{nil} were in the list, most likely what you really want is -to use @kbd{M-x load-file}.) - - The default value of @code{load-path} is a list of directories where -the Lisp code for Emacs itself is stored. If you have libraries of -your own in another directory, you can add that directory to the load -path. Unlike most other variables described in this manual, -@code{load-path} cannot be changed via the Customize interface -(@pxref{Easy Customization}), but you can add a directory to it by -putting a line like this in your init file (@pxref{Init File}): - -@example -(add-to-list 'load-path "/path/to/my/lisp/library") -@end example - -@cindex autoload - Some commands are @dfn{autoloaded}; when you run them, Emacs -automatically loads the associated library first. For instance, the -@kbd{M-x compile} command (@pxref{Compilation}) is autoloaded; if you -call it, Emacs automatically loads the @code{compile} library first. -In contrast, the command @kbd{M-x recompile} is not autoloaded, so it -is unavailable until you load the @code{compile} library. - -@vindex help-enable-auto-load - Automatic loading can also occur when you look up the documentation -of an autoloaded command (@pxref{Name Help}), if the documentation -refers to other functions and variables in its library (loading the -library lets Emacs properly set up the hyperlinks in the @file{*Help*} -buffer). To disable this feature, change the variable -@code{help-enable-auto-load} to @code{nil}. - -@vindex load-dangerous-libraries -@cindex Lisp files byte-compiled by XEmacs - By default, Emacs refuses to load compiled Lisp files which were -compiled with XEmacs, a modified versions of Emacs---they can cause -Emacs to crash. Set the variable @code{load-dangerous-libraries} to -@code{t} if you want to try loading them. - -@node Lisp Eval -@section Evaluating Emacs Lisp Expressions -@cindex Emacs Lisp mode -@cindex mode, Emacs Lisp -@cindex evaluation, Emacs Lisp - -@findex emacs-lisp-mode - Emacs Lisp mode is the major mode for editing Emacs Lisp. Its mode -command is @kbd{M-x emacs-lisp-mode}. - - Emacs provides several commands for evaluating Emacs Lisp -expressions. You can use these commands in Emacs Lisp mode, to test -your Emacs Lisp code as it is being written. For example, after -re-writing a function, you can evaluate the function definition to -make it take effect for subsequent function calls. These commands are -also available globally, and can be used outside Emacs Lisp mode. - -@table @asis -@item @kbd{M-:} -Read a single Emacs Lisp expression in the minibuffer, evaluate it, -and print the value in the echo area (@code{eval-expression}). -@item @kbd{C-x C-e} -Evaluate the Emacs Lisp expression before point, and print the value -in the echo area (@code{eval-last-sexp}). -@item @kbd{C-M-x} @r{(in Emacs Lisp mode)} -@itemx @kbd{M-x eval-defun} -Evaluate the defun containing or after point, and print the value in -the echo area (@code{eval-defun}). -@item @kbd{M-x eval-region} -Evaluate all the Emacs Lisp expressions in the region. -@item @kbd{M-x eval-buffer} -Evaluate all the Emacs Lisp expressions in the buffer. -@end table - -@ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu -@kindex M-@key{colon} -@end ifinfo -@ifnotinfo -@kindex M-: -@end ifnotinfo -@findex eval-expression - @kbd{M-:} (@code{eval-expression}) reads an expression using the -minibuffer, and evaluates it. (Before evaluating the expression, the -current buffer switches back to the buffer that was current when you -typed @kbd{M-:}, not the minibuffer into which you typed the -expression.) - -@kindex C-x C-e -@findex eval-last-sexp - The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the -Emacs Lisp expression preceding point in the buffer, and displays the -value in the echo area. When the result of an evaluation is an -integer, it is displayed together with the value in other formats -(octal, hexadecimal, and character). - - If @kbd{M-:} or @kbd{C-x C-e} is given a prefix argument, it inserts -the value into the current buffer at point, rather than displaying it -in the echo area. If the prefix argument is zero, any integer output -is inserted together with its value in other formats (octal, -hexadecimal, and character). Such a prefix argument also prevents -abbreviation of the output according to the variables -@code{eval-expression-print-level} and @code{eval-expression-print-length} -(see below). - -@kindex C-M-x @r{(Emacs Lisp mode)} -@findex eval-defun - The @code{eval-defun} command is bound to @kbd{C-M-x} in Emacs Lisp -mode. It evaluates the top-level Lisp expression containing or -following point, and prints the value in the echo area. In this -context, a top-level expression is referred to as a ``defun'', but it -need not be an actual @code{defun} (function definition). In -particular, this command treats @code{defvar} expressions specially. -Normally, evaluating a @code{defvar} expression does nothing if the -variable it defines already has a value. But this command -unconditionally resets the variable to the initial value specified by -the @code{defvar}; this is convenient for debugging Emacs Lisp -programs. @code{defcustom} and @code{defface} expressions are treated -similarly. Note that the other commands documented in this section do -not have this special feature. - - With a prefix argument, @kbd{C-M-x} instruments the function -definition for Edebug, the Emacs Lisp Debugger. @xref{Instrumenting, -Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}. - -@findex eval-region -@findex eval-buffer - The command @kbd{M-x eval-region} parses the text of the region as -one or more Lisp expressions, evaluating them one by one. @kbd{M-x -eval-buffer} is similar but evaluates the entire buffer. - -@vindex eval-expression-print-level -@vindex eval-expression-print-length -@vindex eval-expression-debug-on-error - The options @code{eval-expression-print-level} and -@code{eval-expression-print-length} control the maximum depth and -length of lists to print in the result of the evaluation commands -before abbreviating them. Supplying a zero prefix argument to -@code{eval-expression} or @code{eval-last-sexp} causes lists to be -printed in full. @code{eval-expression-debug-on-error} controls -whether evaluation errors invoke the debugger when these commands are -used; its default is @code{t}. - -@node Lisp Interaction -@section Lisp Interaction Buffers - -@findex lisp-interaction-mode - When Emacs starts up, it contains a buffer named @file{*scratch*}, -which is provided for evaluating Emacs Lisp expressions interactively. -Its major mode is Lisp Interaction mode. You can also enable Lisp -Interaction mode by typing @kbd{M-x lisp-interaction-mode}. - -@findex eval-print-last-sexp -@kindex C-j @r{(Lisp Interaction mode)} - In the @file{*scratch*} buffer, and other Lisp Interaction mode -buffers, @kbd{C-j} (@code{eval-print-last-sexp}) evaluates the Lisp -expression before point, and inserts the value at point. Thus, as you -type expressions into the buffer followed by @kbd{C-j} after each -expression, the buffer records a transcript of the evaluated -expressions and their values. All other commands in Lisp Interaction -mode are the same as in Emacs Lisp mode. - -@vindex initial-scratch-message - At startup, the @file{*scratch*} buffer contains a short message, in -the form of a Lisp comment, that explains what it is for. This -message is controlled by the variable @code{initial-scratch-message}, -which should be either a string, or @code{nil} (which means to -suppress the message). - -@findex ielm - An alternative way of evaluating Emacs Lisp expressions -interactively is to use Inferior Emacs Lisp mode, which provides an -interface rather like Shell mode (@pxref{Shell Mode}) for evaluating -Emacs Lisp expressions. Type @kbd{M-x ielm} to create an -@file{*ielm*} buffer which uses this mode. For more information, see -that command's documentation. - -@node External Lisp -@section Running an External Lisp -@cindex Lisp mode -@cindex mode, Lisp -@cindex Common Lisp - - Lisp mode is the major mode for editing programs written in -general-purpose Lisp dialects, such as Common Lisp. Its mode command -is @kbd{M-x lisp-mode}. Emacs uses Lisp mode automatically for files -whose names end in @file{.l}, @file{.lsp}, or @file{.lisp}. - -@findex run-lisp -@vindex inferior-lisp-program -@kindex C-x C-z - You can run an external Lisp session as a subprocess or -@dfn{inferior process} of Emacs, and pass expressions to it to be -evaluated. To begin an external Lisp session, type @kbd{M-x -run-lisp}. This runs the program named @command{lisp}, and sets it up -so that both input and output go through an Emacs buffer named -@file{*inferior-lisp*}. To change the name of the Lisp program run by -@kbd{M-x run-lisp}, change the variable @code{inferior-lisp-program}. - - The major mode for the @file{*lisp*} buffer is Inferior Lisp mode, -which combines the characteristics of Lisp mode and Shell mode -(@pxref{Shell Mode}). To send input to the Lisp session, go to the -end of the @file{*lisp*} buffer and type the input, followed by -@key{RET}. Terminal output from the Lisp session is automatically -inserted in the buffer. - -@kindex C-M-x @r{(Lisp mode)} -@findex lisp-eval-defun - When you edit a Lisp program in Lisp mode, you can type @kbd{C-M-x} -(@code{lisp-eval-defun}) to send an expression from the Lisp mode -buffer to a Lisp session that you had started with @kbd{M-x run-lisp}. -The expression sent is the top-level Lisp expression at or following -point. The resulting value goes as usual into the -@file{*inferior-lisp*} buffer. Note that the effect of @kbd{C-M-x} in -Lisp mode is thus very similar to its effect in Emacs Lisp mode -(@pxref{Lisp Eval}), except that the expression is sent to a different -Lisp environment instead of being evaluated in Emacs. - -@findex scheme-mode -@findex run-scheme -@cindex Scheme mode -@cindex mode, Scheme -@kindex C-M-x @r{(Scheme mode)} - The facilities for editing Scheme code, and for sending expressions -to a Scheme subprocess, are very similar. Scheme source files are -edited in Scheme mode, which can be explicitly enabled with @kbd{M-x -scheme-mode}. You can initiate a Scheme session by typing @kbd{M-x -run-scheme} (the buffer for interacting with Scheme is named -@file{*scheme*}), and send expressions to it by typing @kbd{C-M-x}. diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi deleted file mode 100644 index 82864859473..00000000000 --- a/doc/emacs/cal-xtra.texi +++ /dev/null @@ -1,1022 +0,0 @@ -@c This is part of the Emacs manual. -*- coding: utf-8 -*- -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). - -@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. -@node Advanced Calendar/Diary Usage -@section More advanced features of the Calendar and Diary - - This section describes some of the more advanced/specialized -features of the calendar and diary. It starts with some of the -many ways in which you can customize the calendar and diary to suit -your personal tastes. - -@menu -* Calendar Customizing:: Calendar layout and hooks. -* Holiday Customizing:: Defining your own holidays. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Diary Customizing:: Defaults you can set. -* Non-Gregorian Diary:: Diary entries based on other calendars. -* Diary Display:: A choice of ways to display the diary. -* Fancy Diary Display:: Sorting diary entries, using included diary files. -* Sexp Diary Entries:: More flexible diary entries. -@end menu - -@node Calendar Customizing -@subsection Customizing the Calendar - -@vindex calendar-intermonth-text -@cindex calendar layout -@cindex calendar week numbers - The calendar display unfortunately cannot be changed from three -months, but you can customize the whitespace used by setting the -variables: @code{calendar-left-margin}, -@code{calendar-day-header-width}, @code{calendar-day-digit-width}, -@code{calendar-column-width}, and @code{calendar-intermonth-spacing}. -To display text @emph{between} the months, for example week numbers, -customize the variables @code{calendar-intermonth-header} and -@code{calendar-intermonth-text} as described in their documentation. - -@vindex calendar-month-header -@vindex calendar-day-header-array - The variable @code{calendar-month-header} controls the text that -appears above each month in the calendar. By default, it shows the -month and year. The variable @code{calendar-day-header-array} -controls the text that appears above each day's column in every month. -By default, it shows the first two letters of each day's name. - -@vindex calendar-holiday-marker -@vindex diary-entry-marker -@vindex calendar-today-marker - The variable @code{calendar-holiday-marker} specifies how to mark a -date that is a holiday. Its value may be a single-character string to -insert next to the date, or a face name to use for displaying the date. -Likewise, the variable @code{diary-entry-marker} specifies how to mark a -date that has diary entries. The function @code{calendar-mark-today} -uses @code{calendar-today-marker} to mark today's date. By default, -the calendar uses faces named @code{holiday}, @code{diary}, and -@code{calendar-today} for these purposes. - -@vindex calendar-load-hook - The variable @code{calendar-load-hook} is a normal hook run when the -calendar package is first loaded (before actually starting to display -the calendar). - -@vindex calendar-initial-window-hook - Starting the calendar runs the normal hook -@code{calendar-initial-window-hook}. Recomputation of the calendar -display does not run this hook. But if you leave the calendar with the -@kbd{q} command and reenter it, the hook runs again. - -@vindex calendar-today-visible-hook -@findex calendar-star-date - The variable @code{calendar-today-visible-hook} is a normal hook run -after the calendar buffer has been prepared with the calendar, when the -current date is visible in the window. One use of this hook is to -mark today's date; to do that use either of the functions -@code{calendar-mark-today} or @code{calendar-star-date}: - -@findex calendar-mark-today -@smallexample -(add-hook 'calendar-today-visible-hook 'calendar-mark-today) -@end smallexample - -@vindex calendar-today-invisible-hook -@noindent - A similar normal hook, @code{calendar-today-invisible-hook} is run if -the current date is @emph{not} visible in the window. - -@vindex calendar-move-hook - Each of the calendar cursor motion commands runs the hook -@code{calendar-move-hook} after it moves the cursor. - -@node Holiday Customizing -@subsection Customizing the Holidays - -@vindex calendar-holidays -@vindex holiday-oriental-holidays -@vindex holiday-solar-holidays - There are several variables listing the default holidays that Emacs -knows about. These are: @code{holiday-general-holidays}, -@code{holiday-local-holidays}, @code{holiday-solar-holidays}, -@code{holiday-bahai-holidays}, @code{holiday-christian-holidays}, -@code{holiday-hebrew-holidays}, @code{holiday-islamic-holidays}, -@code{holiday-oriental-holidays}, and @code{holiday-other-holidays}. -The names should be self-explanatory; e.g., @code{holiday-solar-holidays} -lists sun- and moon-related holidays. - -You can customize these lists of holidays to your own needs, deleting or -adding holidays as described below. Set any of them to @code{nil} to -not show the associated holidays. - -@vindex holiday-general-holidays -@vindex holiday-local-holidays -@vindex holiday-other-holidays - The general holidays are, by default, holidays common throughout the -United States. In contrast, @code{holiday-local-holidays} and -@code{holiday-other-holidays} are both empty by default. These are -intended for system-wide settings and your individual use, -respectively. - -@vindex holiday-bahai-holidays -@vindex holiday-christian-holidays -@vindex holiday-hebrew-holidays -@vindex holiday-islamic-holidays -@vindex calendar-bahai-all-holidays-flag -@vindex calendar-christian-all-holidays-flag -@vindex calendar-hebrew-all-holidays-flag -@vindex calendar-islamic-all-holidays-flag - By default, Emacs does not include all the holidays of the religions -that it knows, only those commonly found in secular calendars. For a -more extensive collection of religious holidays, you can set any (or -all) of the variables @code{calendar-bahai-all-holidays-flag}, -@code{calendar-christian-all-holidays-flag}, -@code{calendar-hebrew-all-holidays-flag}, or -@code{calendar-islamic-all-holidays-flag} to @code{t}. - -@cindex holiday forms - Each of the holiday variables is a list of @dfn{holiday forms}, each -form describing a holiday (or sometimes a list of holidays). Here is -a table of the possible kinds of holiday form. Day numbers and month -numbers count starting from 1, but ``dayname'' numbers count Sunday as -0. The argument @var{string} is always the description of the -holiday, as a string. - -@table @code -@item (holiday-fixed @var{month} @var{day} @var{string}) -A fixed date on the Gregorian calendar. - -@item (holiday-float @var{month} @var{dayname} @var{k} @var{string} - &optional @var{day}) -The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on) -after or before Gregorian date @var{month}, @var{day}. Negative @var{k} -means count back from the end of the month. Optional @var{day} defaults -to 1 if @var{k} is positive, and the last day of @var{month} otherwise. - -@item (holiday-chinese @var{month} @var{day} @var{string}) -A fixed date on the Chinese calendar. - -@item (holiday-hebrew @var{month} @var{day} @var{string}) -A fixed date on the Hebrew calendar. - -@item (holiday-islamic @var{month} @var{day} @var{string}) -A fixed date on the Islamic calendar. - -@item (holiday-julian @var{month} @var{day} @var{string}) -A fixed date on the Julian calendar. - -@item (holiday-sexp @var{sexp} @var{string}) -A date calculated by the Lisp expression @var{sexp}. The expression -should use the variable @code{year} to compute and return the date of a -holiday in the form of a list @code{(@var{month} @var{day} @var{year})}, -or @code{nil} if the holiday doesn't happen this year. - -@item (if @var{condition} @var{holiday-form}) -A holiday that happens only if @var{condition} is true. - -@item (@var{function} @r{[}@var{args}@r{]}) -A list of dates calculated by the function @var{function}, called with -arguments @var{args}. -@end table - - For example, suppose you want to add Bastille Day, celebrated in -France on July 14 (i.e., the fourteenth day of the seventh month). You -can do this as follows: - -@smallexample -(setq holiday-other-holidays '((holiday-fixed 7 14 "Bastille Day"))) -@end smallexample - - Many holidays occur on a specific day of the week, at a specific time -of month. Here is a holiday form describing Hurricane Supplication Day, -celebrated in the Virgin Islands on the fourth Monday in August: - -@smallexample -(holiday-float 8 1 4 "Hurricane Supplication Day") -@end smallexample - -@noindent -Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, -Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in -the month (1 specifies the first occurrence, 2 the second occurrence, -@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and -so on). - - You can specify holidays that occur on fixed days of the Bahá'í, -Chinese, Hebrew, Islamic, and Julian calendars too. For example, - -@smallexample -(setq holiday-other-holidays - '((holiday-hebrew 10 2 "Last day of Hanukkah") - (holiday-islamic 3 12 "Mohammed's Birthday") - (holiday-julian 4 2 "Jefferson's Birthday"))) -@end smallexample - -@noindent -adds the last day of Hanukkah (since the Hebrew months are numbered with -1 starting from Nisan), the Islamic feast celebrating Mohammed's -birthday (since the Islamic months are numbered from 1 starting with -Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the -Julian calendar. - - To include a holiday conditionally, use either Emacs Lisp's @code{if} -or the @code{holiday-sexp} form. For example, American presidential -elections occur on the first Tuesday after the first Monday in November -of years divisible by 4: - -@smallexample -(holiday-sexp '(if (zerop (% year 4)) - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 year))))))) - "US Presidential Election") -@end smallexample - -@noindent -or - -@smallexample -(if (zerop (% displayed-year 4)) - (holiday-fixed 11 - (calendar-extract-day - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 displayed-year))))))) - "US Presidential Election")) -@end smallexample - - Some holidays just don't fit into any of these forms because special -calculations are involved in their determination. In such cases you -must write a Lisp function to do the calculation. To include eclipses, -for example, add @code{(eclipses)} to @code{holiday-other-holidays} -and write an Emacs Lisp function @code{eclipses} that returns a -(possibly empty) list of the relevant Gregorian dates among the range -visible in the calendar window, with descriptive strings, like this: - -@smallexample -(((6 4 2012) "Lunar Eclipse") ((11 13 2012) "Solar Eclipse") ... ) -@end smallexample - -@node Mayan Calendar -@subsection Converting from the Mayan Calendar -@cindex Mayan calendar - - Here are the commands to select dates based on the Mayan calendar: - -@table @kbd -@item g m l -Move to a date specified by the long count calendar -(@code{calendar-mayan-goto-long-count-date}). -@item g m n t -Move to the next occurrence of a place in the -tzolkin calendar (@code{calendar-mayan-next-tzolkin-date}). -@item g m p t -Move to the previous occurrence of a place in the -tzolkin calendar (@code{calendar-mayan-previous-tzolkin-date}). -@item g m n h -Move to the next occurrence of a place in the -haab calendar (@code{calendar-mayan-next-haab-date}). -@item g m p h -Move to the previous occurrence of a place in the -haab calendar (@code{calendar-mayan-previous-haab-date}). -@item g m n c -Move to the next occurrence of a place in the -calendar round (@code{calendar-mayan-next-calendar-round-date}). -@item g m p c -Move to the previous occurrence of a place in the -calendar round (@code{calendar-mayan-previous-calendar-round-date}). -@end table - -@cindex Mayan long count - To understand these commands, you need to understand the Mayan calendars. -The @dfn{long count} is a counting of days with these units: - -@display -1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal -1 katun = 20 tun@ @ @ 1 baktun = 20 katun -@end display - -@kindex g m @r{(Calendar mode)} -@findex calendar-mayan-goto-long-count-date -@noindent -Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 -tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long -count dates as early as 7.17.18.13.3, but no earlier. When you use the -@kbd{g m l} command, type the Mayan long count date with the baktun, -katun, tun, uinal, and kin separated by periods. - -@findex calendar-mayan-previous-tzolkin-date -@findex calendar-mayan-next-tzolkin-date -@cindex Mayan tzolkin calendar - The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of -independent cycles of 13 and 20 days. Since this cycle repeats -endlessly, Emacs provides commands to move backward and forward to the -previous or next point in the cycle. Type @kbd{g m p t} to go to the -previous tzolkin date; Emacs asks you for a tzolkin date and moves point -to the previous occurrence of that date. Similarly, type @kbd{g m n t} -to go to the next occurrence of a tzolkin date. - -@findex calendar-mayan-previous-haab-date -@findex calendar-mayan-next-haab-date -@cindex Mayan haab calendar - The Mayan haab calendar is a cycle of 365 days arranged as 18 months -of 20 days each, followed by a 5-day monthless period. Like the tzolkin -cycle, this cycle repeats endlessly, and there are commands to move -backward and forward to the previous or next point in the cycle. Type -@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab -date and moves point to the previous occurrence of that date. -Similarly, type @kbd{g m n h} to go to the next occurrence of a haab -date. - -@c This is omitted because it is too long for smallbook format. -@c @findex calendar-mayan-previous-calendar-round-date -@findex calendar-mayan-next-calendar-round-date -@cindex Mayan calendar round - The Maya also used the combination of the tzolkin date and the haab -date. This combination is a cycle of about 52 years called a -@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for -both a haab and a tzolkin date and then moves point to the previous -occurrence of that combination. Use @kbd{g m n c} to move point to the -next occurrence of a combination. These commands signal an error if the -haab/tzolkin date combination you have typed is impossible. - - Emacs uses strict completion -@iftex -(@pxref{Completion Exit,,, emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Completion Exit}) -@end ifnottex -whenever it asks you to type a Mayan name, so you don't have to worry -about spelling. - -@node Date Display Format -@subsection Date Display Format -@vindex calendar-date-display-form - - You can customize the way dates are displayed in the diary, mode -lines, and messages by setting @code{calendar-date-display-form}. -This variable holds a list of expressions that can involve the variables -@code{month}, @code{day}, and @code{year}, which are all numbers in -string form, and @code{monthname} and @code{dayname}, which are both -alphabetic strings. In the American style, the default value of this -list is as follows: - -@smallexample -((if dayname (concat dayname ", ")) monthname " " day ", " year) -@end smallexample - -@noindent -while in the European style this value is the default: - -@smallexample -((if dayname (concat dayname ", ")) day " " monthname " " year) -@end smallexample - -@noindent -The default ISO date representation is: - -@smallexample -((format "%s-%.2d-%.2d" year (string-to-number month) - (string-to-number day))) -@end smallexample - -@noindent -Another typical American format is: - -@smallexample -(month "/" day "/" (substring year -2)) -@end smallexample - -@node Time Display Format -@subsection Time Display Format -@vindex calendar-time-display-form - - The calendar and diary by default display times of day in the -conventional American style with the hours from 1 through 12, minutes, -and either @samp{am} or @samp{pm}. If you prefer the European style, -also known in the US as military, in which the hours go from 00 to 23, -you can alter the variable @code{calendar-time-display-form}. This -variable is a list of expressions that can involve the variables -@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all -numbers in string form, and @code{am-pm} and @code{time-zone}, which are -both alphabetic strings. The default value is: - -@smallexample -(12-hours ":" minutes am-pm - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -@noindent -Here is a value that provides European style times: - -@smallexample -(24-hours ":" minutes - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -Note that few calendar functions return a time of day (at present, only -solar functions). - -@node Diary Customizing -@subsection Customizing the Diary - -@vindex diary-show-holidays-flag - Ordinarily, the diary window indicates any holidays that fall on the -date of the diary entries, either in the mode line or the buffer itself. -The process of checking for holidays can be slow, depending on the -defined holidays. In that case, setting @code{diary-show-holidays-flag} -to @code{nil} will speed up the diary display. - -@vindex diary-number-of-entries - The variable @code{diary-number-of-entries} controls the number of -days of diary entries to be displayed at one time. It affects the -initial display when @code{calendar-view-diary-initially-flag} is -@code{t}, as well as the command @kbd{M-x diary}. For example, a value -of 1 (the default) displays only the current day's diary entries, -whereas a value of 2 will also show the next day's entries. The value -can also be a vector of seven integers: for example, if the value is -@code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday, the -current date's and the next day's diary entries appear Monday through -Thursday, Friday through Monday's entries appear on Friday, while on -Saturday only that day's entries appear. - -@vindex diary-date-forms - You can customize the form of dates in your diary file by setting the -variable @code{diary-date-forms}. This variable is a list of patterns -for recognizing a date. Each date pattern is a list whose elements may -be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs -Lisp Reference Manual}) or the symbols @code{month}, @code{day}, -@code{year}, @code{monthname}, and @code{dayname}. All these elements -serve as patterns that match certain kinds of text in the diary file. -In order for the date pattern as a whole to match, all of its elements -must match consecutively. - - A regular expression in a date pattern matches in its usual fashion, -using the standard syntax table altered so that @samp{*} is a word -constituent. - - The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, -and @code{dayname} match the month number, day number, year number, -month name, and day name of the date being considered. The symbols that -match numbers allow leading zeros; those that match names allow -capitalization and abbreviation (as specified by -@code{calendar-month-abbrev-array} and -@code{calendar-day-abbrev-array}). All the symbols can match @samp{*}; -since @samp{*} in a diary entry means ``any day'', ``any month'', and so -on, it should match regardless of the date being considered. - - The default value of @code{diary-date-forms} in the American style is -provided by @code{diary-american-date-forms}: - -@example -((month "/" day "[^/0-9]") - (month "/" day "/" year "[^0-9]") - (monthname " *" day "[^,0-9]") - (monthname " *" day ", *" year "[^0-9]") - (dayname "\\W")) -@end example - -@noindent -The variables @code{diary-european-date-forms} and -@code{diary-iso-date-forms} provide other default styles. - - The date patterns in the list must be @emph{mutually exclusive} and -must not match any portion of the diary entry itself, just the date and -one character of whitespace. If, to be mutually exclusive, the pattern -must match a portion of the diary entry text---beyond the whitespace -that ends the date---then the first element of the date pattern -@emph{must} be @code{backup}. This causes the date recognizer to back -up to the beginning of the current word of the diary entry, after -finishing the match. Even if you use @code{backup}, the date pattern -must absolutely not match more than a portion of the first word of the -diary entry. For example, the default value of -@code{diary-european-date-forms} is: - -@example -((day "/" month "[^/0-9]") - (day "/" month "/" year "[^0-9]") - (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)") - (day " *" monthname " *" year "[^0-9]") - (dayname "\\W")) -@end example - -@noindent -Notice the use of @code{backup} in the third pattern, because it needs -to match part of a word beyond the date itself to distinguish it from -the fourth pattern. - -@node Non-Gregorian Diary -@subsection Diary Entries Using non-Gregorian Calendars - - As well as entries based on the standard Gregorian calendar, your -diary can have entries based on Bahá'í, Hebrew, or Islamic dates. -Recognition of such entries can be time-consuming, however, and since -most people don't use them, you must explicitly enable their use. If -you want the diary to recognize Hebrew-date diary entries, for example, -you must do this: - -@vindex diary-nongregorian-listing-hook -@vindex diary-nongregorian-marking-hook -@findex diary-hebrew-list-entries -@findex diary-hebrew-mark-entries -@findex diary-islamic-list-entries -@findex diary-islamic-mark-entries -@findex diary-bahai-list-entries -@findex diary-bahai-mark-entries -@smallexample -(add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries) -(add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries) -@end smallexample - -@noindent -Similarly, for Islamic and Bahá'í entries, add -@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or -@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}. - -@vindex diary-bahai-entry-symbol -@vindex diary-hebrew-entry-symbol -@vindex diary-islamic-entry-symbol - These diary entries have the same formats as Gregorian-date diary -entries; except that @code{diary-bahai-entry-symbol} (default @samp{B}) -must precede a Bahá'í date, @code{diary-hebrew-entry-symbol} (default -@samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default -@samp{I}) an Islamic date. Moreover, non-Gregorian month names may not -be abbreviated (because the first three letters are often not unique). -(Note also that you must use ``Adar I'' if you want Adar of a common -Hebrew year.) For example, a diary entry for the Hebrew date Heshvan 25 -could look like this: - -@smallexample -HHeshvan 25 Happy Hebrew birthday! -@end smallexample - -@noindent -and would appear in the diary for any date that corresponds to Heshvan 25 -on the Hebrew calendar. And here is an Islamic-date diary entry that matches -Dhu al-Qada 25: - -@smallexample -IDhu al-Qada 25 Happy Islamic birthday! -@end smallexample - - As with Gregorian-date diary entries, non-Gregorian entries are -nonmarking if preceded by @code{diary-nonmarking-symbol} (default -@samp{&}). - - Here is a table of commands used in the calendar to create diary -entries that match the selected date and other dates that are similar in -the Bahá'í, Hebrew, or Islamic calendars: - -@table @kbd -@item i h d -@code{diary-hebrew-insert-entry} -@item i h m -@code{diary-hebrew-insert-monthly-entry} -@item i h y -@code{diary-hebrew-insert-yearly-entry} -@item i i d -@code{diary-islamic-insert-entry} -@item i i m -@code{diary-islamic-insert-monthly-entry} -@item i i y -@code{diary-islamic-insert-yearly-entry} -@item i B d -@code{diary-bahai-insert-entry} -@item i B m -@code{diary-bahai-insert-monthly-entry} -@item i B y -@code{diary-bahai-insert-yearly-entry} -@end table - -@findex diary-hebrew-insert-entry -@findex diary-hebrew-insert-monthly-entry -@findex diary-hebrew-insert-yearly-entry -@findex diary-islamic-insert-entry -@findex diary-islamic-insert-monthly-entry -@findex diary-islamic-insert-yearly-entry -@findex diary-bahai-insert-entry -@findex diary-bahai-insert-monthly-entry -@findex diary-bahai-insert-yearly-entry - These commands work much like the corresponding commands for ordinary -diary entries: they apply to the date that point is on in the calendar -window, and what they do is insert just the date portion of a diary -entry at the end of your diary file. You must then insert the rest of -the diary entry. The basic commands add an entry for the specific -non-Gregorian date, the @samp{monthly} commands for the given -non-Gregorian day-within-month in every month, and the @samp{yearly} -commands for the given non-Gregorian day and month in every year. - -@node Diary Display -@subsection Diary Display -@vindex diary-display-function -@findex diary-simple-display -@findex diary-fancy-display -@cindex diary buffer - - Diary display works by preparing the list of diary entries and then -running the function specified by the variable -@code{diary-display-function}. The default value -@code{diary-fancy-display} displays diary entries and holidays by -copying them into a special buffer that exists only for the sake of -display. Copying diary entries to a separate buffer provides an -opportunity to change the displayed text to make it prettier---for -example, to sort the entries by the dates they apply to. - -@vindex diary-list-include-blanks - Ordinarily, the fancy diary buffer does not show days for which there -are no diary entries, even if that day is a holiday. If you want such -days to be shown in the fancy diary buffer, set the variable -@code{diary-list-include-blanks} to @code{t}. - - The fancy diary buffer enables View mode -@iftex -(@pxref{View Mode,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{View Mode}). -@end ifnottex - - The alternative display method @code{diary-simple-display} shows the -actual diary buffer, and uses invisible text to hide entries that don't -apply. Holidays are shown in the mode line. The advantage of this -method is that you can edit the buffer and save your changes directly to -the diary file. This method is not as flexible as the fancy method, -however. For example, it cannot sort entries. Another disadvantage is -that invisible text can be confusing. For example, if you copy a region -of text in order to paste it elsewhere, invisible text may be included. -Similarly, since the diary buffer as you see it is an illusion, simply -printing the buffer may not print what you see on your screen. - -@vindex diary-print-entries-hook -@findex diary-print-entries - For this reason, there is a special command to print hard copy of the -diary buffer @emph{as it appears}; this command is @kbd{M-x -diary-print-entries}. It works with either display method, although -with the fancy display you can also print the buffer like any other. To -print a hard copy of a day-by-day diary for a week, position point on -the first day of the week, type @kbd{7 d}, and then do @kbd{M-x -diary-print-entries}. As usual, the inclusion of the holidays slows -down the display slightly; you can speed things up by setting the -variable @code{diary-show-holidays-flag} to @code{nil}. - - This command prepares a temporary buffer that contains only the diary -entries currently visible in the diary buffer. Unlike with the simple -display, the other irrelevant entries are really absent, not just -hidden. After preparing the buffer, it runs the hook -@code{diary-print-entries-hook}. The default value of this hook sends -the data directly to the printer with the command @code{lpr-buffer} -@iftex -(@pxref{Printing,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Printing}). -@end ifnottex -If you want to use a different command to do the -printing, just change the value of this hook. Other uses might include, -for example, rearranging the lines into order by day and time. - - You can edit the diary entries as they appear in the simple diary -window, but it is important to remember that the buffer displayed -contains the @emph{entire} diary file, with portions of it concealed -from view. This means, for instance, that the @kbd{C-f} -(@code{forward-char}) command can put point at what appears to be the -end of the line, but what is in reality the middle of some concealed -line. - - @emph{Be careful when editing the diary entries in the simple display!} -Inserting additional lines or adding/deleting characters in the middle -of a visible line cannot cause problems, but editing at the end of a -line may not do what you expect. Deleting a line may delete other -invisible entries that follow it. Before editing the simple diary -buffer, it is best to display the entire file with @kbd{s} -(@code{diary-show-all-entries}). - -@node Fancy Diary Display -@subsection Fancy Diary Display - -The following features only work with the fancy diary display. - -@cindex sorting diary entries - You can use the normal hook @code{diary-list-entries-hook} to sort -each day's diary entries by their time of day. Here's how: - -@findex diary-sort-entries -@example -(add-hook 'diary-list-entries-hook 'diary-sort-entries t) -@end example - -@noindent -For each day, this sorts diary entries that begin with a recognizable -time of day according to their times. Diary entries without times come -first within each day. Note how the sort command is placed at the end -of the hook list, in case earlier members of the list change the order -of the diary entries, or add items. - -@vindex diary-comment-start - You can write @samp{comments} in diary entries, by setting the -variables @code{diary-comment-start} and @code{diary-comment-end} to -strings that delimit comments. The fancy display does not print -comments. You might want to put meta-data for the use of other packages -(e.g., the appointment package, -@iftex -@pxref{Appointments,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -@pxref{Appointments}) -@end ifnottex -inside comments. - -@vindex diary-include-string - Your main diary file can include other files. This permits a group of -people to share a diary file for events that apply to all of them. -Lines in the diary file starting with @code{diary-include-string}: - -@smallexample -#include "@var{filename}" -@end smallexample - -@noindent -include the diary entries from the file @var{filename} in the fancy -diary buffer. The include mechanism is recursive, so that included -files can include other files, and so on (you must be careful not to -have a cycle of inclusions, of course). Here is how to enable the -include facility: - -@vindex diary-list-entries-hook -@vindex diary-mark-entries-hook -@findex diary-include-other-diary-files -@findex diary-mark-included-diary-files -@smallexample -(add-hook 'diary-list-entries-hook 'diary-include-other-diary-files) -(add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files) -@end smallexample - -The include mechanism works only with the fancy diary display, because -simple diary display shows the entries directly from your diary file. - -@node Sexp Diary Entries -@subsection Sexp Entries and the Fancy Diary Display -@cindex sexp diary entries - -@vindex diary-sexp-entry-symbol - Sexp diary entries allow you to do more than just have complicated -conditions under which a diary entry applies. Sexp entries should be -preceded by @code{diary-sexp-entry-symbol} (default @samp{%%}) in the -diary file. With the fancy diary display, sexp entries can generate the -text of the entry depending on the date itself. - -For example, an anniversary diary entry can insert -the number of years since the anniversary date into the text of the -diary entry. Thus the @samp{%d} in this diary entry: - -@findex diary-anniversary -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) -@end smallexample - -@noindent -gets replaced by the age, so on October 31, 1990 the entry appears in -the fancy diary buffer like this: - -@smallexample -Arthur's birthday (42 years old) -@end smallexample - -@noindent -If the diary file instead contains this entry: - -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday -@end smallexample - -@noindent -the entry in the fancy diary buffer for October 31, 1990 appears like this: - -@smallexample -Arthur's 42nd birthday -@end smallexample - - Similarly, cyclic diary entries can interpolate the number of repetitions -that have occurred: - -@findex diary-cyclic -@smallexample -%%(diary-cyclic 50 1 1 2012) Renew medication (%d%s time) -@end smallexample - -@noindent -looks like this: - -@smallexample -Renew medication (5th time) -@end smallexample - -@noindent -in the fancy diary display on September 7, 2012. - - There is an ``early reminder'' diary sexp that includes its entry in the -diary not only on the date of occurrence, but also on earlier dates. -For example, if you want a reminder a week before your anniversary, you -can use - -@findex diary-remind -@smallexample -%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary -@end smallexample - -@noindent -and the fancy diary will show @samp{Ed's anniversary} both on December -15 and on December 22. - -@findex diary-date - The function @code{diary-date} applies to dates described by a month, -day, year combination, each of which can be an integer, a list of -integers, or @code{t} (meaning all values). For example, - -@smallexample -%%(diary-date '(10 11 12) 22 t) Rake leaves -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Rake leaves -@end smallexample - -@noindent -on October 22, November 22, and December 22 of every year. - -@findex diary-float - The function @code{diary-float} allows you to describe diary entries -that apply to dates like the third Friday of November, or the last -Tuesday in April. The parameters are the @var{month}, @var{dayname}, -and an index @var{n}. The entry appears on the @var{n}th @var{dayname} -after the first day of @var{month}, where @var{dayname}=0 means Sunday, -1 means Monday, and so on. If @var{n} is negative it counts backward -from the end of @var{month}. The value of @var{month} can be a list of -months, a single month, or @code{t} to specify all months. You can also -use an optional parameter @var{day} to specify the @var{n}th -@var{dayname} on or after/before @var{day} of @var{month}; the value of -@var{day} defaults to 1 if @var{n} is positive and to the last day of -@var{month} if @var{n} is negative. For example, - -@smallexample -%%(diary-float t 1 -1) Pay rent -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Pay rent -@end smallexample - -@noindent -on the last Monday of every month. - - The generality of sexp diary entries lets you specify any diary -entry that you can describe algorithmically. A sexp diary entry -contains an expression that computes whether the entry applies to any -given date. If its value is non-@code{nil}, the entry applies to that -date; otherwise, it does not. The expression can use the variable -@code{date} to find the date being considered; its value is a list -(@var{month} @var{day} @var{year}) that refers to the Gregorian -calendar. - - The sexp diary entry applies to a date when the expression's value -is non-@code{nil}, but some values have more specific meanings. If -the value is a string, that string is a description of the event which -occurs on that date. The value can also have the form -@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to -mark the date in the calendar, and @var{string} is the description of -the event. If @var{mark} is a single-character string, that character -appears next to the date in the calendar. If @var{mark} is a face -name, the date is displayed in that face. If @var{mark} is -@code{nil}, that specifies no particular highlighting for the date. - - Suppose you get paid on the 21st of the month if it is a weekday, and -on the Friday before if the 21st is on a weekend. Here is how to write -a sexp diary entry that matches those dates: - -@smallexample -&%%(let ((dayname (calendar-day-of-week date)) - (day (cadr date))) - (or (and (= day 21) (memq dayname '(1 2 3 4 5))) - (and (memq day '(19 20)) (= dayname 5))) - ) Pay check deposited -@end smallexample - - The following sexp diary entries take advantage of the ability (in the fancy -diary display) to concoct diary entries whose text varies based on the date: - -@findex diary-sunrise-sunset -@findex diary-lunar-phases -@findex diary-day-of-year -@findex diary-iso-date -@findex diary-julian-date -@findex diary-astro-day-number -@findex diary-bahai-date -@findex diary-chinese-date -@findex diary-coptic-date -@findex diary-ethiopic-date -@findex diary-hebrew-date -@findex diary-islamic-date -@findex diary-french-date -@findex diary-mayan-date -@findex diary-persian-date -@table @code -@item %%(diary-sunrise-sunset) -Make a diary entry for today's local times of sunrise and sunset. -@item %%(diary-lunar-phases) -Make a diary entry for the phases (quarters) of the moon. -@item %%(diary-day-of-year) -Make a diary entry with today's day number in the current year and the number -of days remaining in the current year. -@item %%(diary-iso-date) -Make a diary entry with today's equivalent ISO commercial date. -@item %%(diary-julian-date) -Make a diary entry with today's equivalent Julian calendar date. -@item %%(diary-astro-day-number) -Make a diary entry with today's equivalent astronomical (Julian) day number. -@item %%(diary-bahai-date) -Make a diary entry with today's equivalent Bahá'í calendar date. -@item %%(diary-chinese-date) -Make a diary entry with today's equivalent Chinese calendar date. -@item %%(diary-coptic-date) -Make a diary entry with today's equivalent Coptic calendar date. -@item %%(diary-ethiopic-date) -Make a diary entry with today's equivalent Ethiopic calendar date. -@item %%(diary-french-date) -Make a diary entry with today's equivalent date on the French Revolutionary -calendar. -@item %%(diary-hebrew-date) -Make a diary entry with today's equivalent Hebrew calendar date. -@item %%(diary-islamic-date) -Make a diary entry with today's equivalent Islamic calendar date. -@item %%(diary-mayan-date) -Make a diary entry with today's equivalent Mayan calendar date. -@item %%(diary-persian-date) -Make a diary entry with today's equivalent Persian calendar date. -@end table - -@noindent -For example, including the diary entry - -@smallexample -&%%(diary-hebrew-date) -@end smallexample - -@noindent -causes every day's diary display to contain the equivalent date on the -Hebrew calendar, if you are using the fancy diary display. (With simple -diary display, the literal line @samp{&%%(diary-hebrew-date)} appears in -the diary for any date.) - - This function has been used to construct certain standard Hebrew sexp -diary entries: - -@cindex rosh hodesh -@findex diary-hebrew-rosh-hodesh -@cindex parasha, weekly -@findex diary-hebrew-parasha -@cindex candle lighting times -@findex diary-hebrew-sabbath-candles -@cindex omer count -@findex diary-hebrew-omer -@cindex yahrzeits -@findex diary-hebrew-yahrzeit -@findex diary-hebrew-birthday -@table @code -@item %%(diary-hebrew-rosh-hodesh) -Make a diary entry that tells the occurrence and ritual announcement of each -new Hebrew month. -@item %%(diary-hebrew-parasha) -Make a Saturday diary entry that tells the weekly synagogue scripture reading. -@item %%(diary-hebrew-sabbath-candles) -Make a Friday diary entry that tells the @emph{local time} of Sabbath -candle lighting. -@item %%(diary-hebrew-omer) -Make a diary entry that gives the omer count, when appropriate. -@item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name} -Make a diary entry marking the anniversary of a date of death. The date -is the @emph{Gregorian} (civil) date of death. The diary entry appears -on the proper Hebrew calendar anniversary and on the day before. (The -order of the parameters changes according to the calendar date style; -for example in the European style to @var{day}, @var{month}, @var{year}.) -@item %%(diary-hebrew-birthday @var{month} @var{day} @var{year}) -Make a diary entry for a birthday on the Hebrew calendar. -@end table - - All the functions documented above take an optional argument -@var{mark} which specifies how to mark the date in the calendar display. -If one of these functions decides that it applies to a certain date, -it returns a value that contains @var{mark}, as described above. diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi deleted file mode 100644 index 07226883c99..00000000000 --- a/doc/emacs/calendar.texi +++ /dev/null @@ -1,1632 +0,0 @@ -@c This is part of the Emacs manual. -*- coding: utf-8 -*- -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Calendar/Diary -@chapter The Calendar and the Diary -@cindex calendar -@findex calendar - - Emacs provides the functions of a desk calendar, with a diary of -planned or past events. It also has facilities for managing your -appointments, and keeping track of how much time you spend working on -certain projects. - - To enter the calendar, type @kbd{M-x calendar}; this displays a -three-month calendar centered on the current month, with point on the -current date. With a numeric argument, as in @kbd{C-u M-x calendar}, it -prompts you for the month and year to be the center of the three-month -calendar. The calendar uses its own buffer, whose major mode is -Calendar mode. - - @kbd{Mouse-3} in the calendar brings up a menu of operations on a -particular date; @kbd{Mouse-2} brings up a menu of commonly used -calendar features that are independent of any particular date. To exit -the calendar, type @kbd{q}. - -@iftex - This chapter describes the basic calendar features. -For more advanced topics, -@pxref{Advanced Calendar/Diary Usage,,, emacs-xtra, Specialized Emacs Features}. -@end iftex - -@menu -* Calendar Motion:: Moving through the calendar; selecting a date. -* Scroll Calendar:: Bringing earlier or later months onto the screen. -* Counting Days:: How many days are there between two dates? -* General Calendar:: Exiting or recomputing the calendar. -* Writing Calendar Files:: Writing calendars to files of various formats. -* Holidays:: Displaying dates of holidays. -* Sunrise/Sunset:: Displaying local times of sunrise and sunset. -* Lunar Phases:: Displaying phases of the moon. -* Other Calendars:: Converting dates to other calendar systems. -* Diary:: Displaying events from your diary. -* Appointments:: Reminders when it's time to do something. -* Importing Diary:: Converting diary events to/from other formats. -* Daylight Saving:: How to specify when daylight saving time is active. -* Time Intervals:: Keeping track of time intervals. -@ifnottex -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -@end ifnottex -@end menu - -@node Calendar Motion -@section Movement in the Calendar - -@cindex moving inside the calendar - Calendar mode provides commands to move through the calendar in -logical units of time such as days, weeks, months, and years. If you -move outside the three months originally displayed, the calendar -display ``scrolls'' automatically through time to make the selected -date visible. Moving to a date lets you view its holidays or diary -entries, or convert it to other calendars; moving by long time periods -is also useful simply to scroll the calendar. - -@menu -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. -@end menu - -@node Calendar Unit Motion -@subsection Motion by Standard Lengths of Time - - The commands for movement in the calendar buffer parallel the -commands for movement in text. You can move forward and backward by -days, weeks, months, and years. - -@table @kbd -@item C-f -Move point one day forward (@code{calendar-forward-day}). -@item C-b -Move point one day backward (@code{calendar-backward-day}). -@item C-n -Move point one week forward (@code{calendar-forward-week}). -@item C-p -Move point one week backward (@code{calendar-backward-week}). -@item M-@} -Move point one month forward (@code{calendar-forward-month}). -@item M-@{ -Move point one month backward (@code{calendar-backward-month}). -@item C-x ] -Move point one year forward (@code{calendar-forward-year}). -@item C-x [ -Move point one year backward (@code{calendar-backward-year}). -@end table - -@kindex C-f @r{(Calendar mode)} -@findex calendar-forward-day -@kindex C-b @r{(Calendar mode)} -@findex calendar-backward-day -@kindex C-n @r{(Calendar mode)} -@findex calendar-forward-week -@kindex C-p @r{(Calendar mode)} -@findex calendar-backward-week - The day and week commands are natural analogues of the usual Emacs -commands for moving by characters and by lines. Just as @kbd{C-n} -usually moves to the same column in the following line, in Calendar -mode it moves to the same day in the following week. And @kbd{C-p} -moves to the same day in the previous week. - - The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and -@kbd{C-p}, just as they normally are in other modes. - -@kindex M-@} @r{(Calendar mode)} -@findex calendar-forward-month -@kindex M-@{ @r{(Calendar mode)} -@findex calendar-backward-month -@kindex C-x ] @r{(Calendar mode)} -@findex calendar-forward-year -@kindex C-x [ @r{(Calendar mode)} -@findex calendar-forward-year - The commands for motion by months and years work like those for -weeks, but move a larger distance. The month commands @kbd{M-@}} and -@kbd{M-@{} move forward or backward by an entire month. The year -commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a -whole year. - - The easiest way to remember these commands is to consider months and -years analogous to paragraphs and pages of text, respectively. But -the commands themselves are not quite analogous. The ordinary Emacs -paragraph commands move to the beginning or end of a paragraph, -whereas these month and year commands move by an entire month or an -entire year, keeping the same date within the month or year. - - All these commands accept a numeric argument as a repeat count. -For convenience, the digit keys and the minus sign specify numeric -arguments in Calendar mode even without the Meta modifier. For example, -@kbd{100 C-f} moves point 100 days forward from its present location. - -@node Move to Beginning or End -@subsection Beginning or End of Week, Month or Year - - A week (or month, or year) is not just a quantity of days; we think of -weeks (months, years) as starting on particular dates. So Calendar mode -provides commands to move to the start or end of a week, month or year: - -@table @kbd -@kindex C-a @r{(Calendar mode)} -@findex calendar-beginning-of-week -@item C-a -Move point to start of week (@code{calendar-beginning-of-week}). -@kindex C-e @r{(Calendar mode)} -@findex calendar-end-of-week -@item C-e -Move point to end of week (@code{calendar-end-of-week}). -@kindex M-a @r{(Calendar mode)} -@findex calendar-beginning-of-month -@item M-a -Move point to start of month (@code{calendar-beginning-of-month}). -@kindex M-e @r{(Calendar mode)} -@findex calendar-end-of-month -@item M-e -Move point to end of month (@code{calendar-end-of-month}). -@kindex M-< @r{(Calendar mode)} -@findex calendar-beginning-of-year -@item M-< -Move point to start of year (@code{calendar-beginning-of-year}). -@kindex M-> @r{(Calendar mode)} -@findex calendar-end-of-year -@item M-> -Move point to end of year (@code{calendar-end-of-year}). -@end table - - These commands also take numeric arguments as repeat counts, with the -repeat count indicating how many weeks, months, or years to move -backward or forward. - -@vindex calendar-week-start-day -@cindex weeks, which day they start on -@cindex calendar, first day of week - By default, weeks begin on Sunday. To make them begin on Monday -instead, set the variable @code{calendar-week-start-day} to 1. - -@node Specified Dates -@subsection Specified Dates - - Calendar mode provides commands for moving to a particular date -specified in various ways. - -@table @kbd -@item g d -Move point to specified date (@code{calendar-goto-date}). -@item g D -Move point to specified day of year (@code{calendar-goto-day-of-year}). -@item g w -Move point to specified week of year (@code{calendar-iso-goto-week}). -@item o -Center calendar around specified month (@code{calendar-other-month}). -@item . -Move point to today's date (@code{calendar-goto-today}). -@end table - -@kindex g d @r{(Calendar mode)} -@findex calendar-goto-date - @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day -of the month, and then moves to that date. Because the calendar includes all -dates from the beginning of the current era, you must type the year in its -entirety; that is, type @samp{1990}, not @samp{90}. - -@kindex g D @r{(Calendar mode)} -@findex calendar-goto-day-of-year -@kindex g w @r{(Calendar mode)} -@findex calendar-iso-goto-week - @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and -day number, and moves to that date. Negative day numbers count -backward from the end of the year. @kbd{g w} -(@code{calendar-iso-goto-week}) prompts for a year and week number, -and moves to that week. - -@kindex o @r{(Calendar mode)} -@findex calendar-other-month - @kbd{o} (@code{calendar-other-month}) prompts for a month and year, -then centers the three-month calendar around that month. - -@kindex . @r{(Calendar mode)} -@findex calendar-goto-today - You can return to today's date with @kbd{.}@: -(@code{calendar-goto-today}). - -@node Scroll Calendar -@section Scrolling in the Calendar - -@cindex scrolling in the calendar - The calendar display scrolls automatically through time when you -move out of the visible portion. You can also scroll it manually. -Imagine that the calendar window contains a long strip of paper with -the months on it. Scrolling the calendar means moving the strip -horizontally, so that new months become visible in the window. - -@table @kbd -@item > -Scroll calendar one month forward (@code{calendar-scroll-left}). -@item < -Scroll calendar one month backward (@code{calendar-scroll-right}). -@item C-v -@itemx @key{next} -Scroll forward by three months (@code{calendar-scroll-left-three-months}). -@item M-v -@itemx @key{prior} -Scroll backward by three months (@code{calendar-scroll-right-three-months}). -@end table - -@kindex > @r{(Calendar mode)} -@findex calendar-scroll-left -@kindex < @r{(Calendar mode)} -@findex calendar-scroll-right - The most basic calendar scroll commands scroll by one month at a -time. This means that there are two months of overlap between the -display before the command and the display after. @kbd{>} scrolls the -calendar contents one month forward in time. @kbd{<} scrolls the -contents one month backwards in time. - -@kindex C-v @r{(Calendar mode)} -@findex calendar-scroll-left-three-months -@kindex M-v @r{(Calendar mode)} -@findex calendar-scroll-right-three-months - The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire -``screenful''---three months---in analogy with the usual meaning of -these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes -earlier dates visible. These commands take a numeric argument as a -repeat count; in particular, since @kbd{C-u} multiplies the next command -by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and -typing @kbd{C-u M-v} scrolls the calendar backward by a year. - - The function keys @key{next} and @key{prior} are equivalent to -@kbd{C-v} and @kbd{M-v}, just as they are in other modes. - -@node Counting Days -@section Counting Days - -@table @kbd -@item M-= -Display the number of days in the current region -(@code{calendar-count-days-region}). -@end table - -@kindex M-= @r{(Calendar mode)} -@findex calendar-count-days-region - To determine the number of days in a range, set the mark on one -date using @kbd{C-@key{SPC}}, move point to another date, and type @kbd{M-=} -(@code{calendar-count-days-region}). The numbers of days shown is -@emph{inclusive}; that is, it includes the days specified by mark and -point. - -@node General Calendar -@section Miscellaneous Calendar Commands - -@table @kbd -@item p d -Display day-in-year (@code{calendar-print-day-of-year}). -@item C-c C-l -Regenerate the calendar window (@code{calendar-redraw}). -@item @key{SPC} -Scroll the next window up (@code{scroll-other-window}). -@item @key{DEL} -@itemx S-@key{SPC} -Scroll the next window down (@code{scroll-other-window-down}). -@item q -Exit from calendar (@code{calendar-exit}). -@end table - -@kindex p d @r{(Calendar mode)} -@cindex day of year -@findex calendar-print-day-of-year - To display the number of days elapsed since the start of the year, or -the number of days remaining in the year, type the @kbd{p d} command -(@code{calendar-print-day-of-year}). This displays both of those -numbers in the echo area. The count of days elapsed includes the -selected date. The count of days remaining does not include that -date. - -@kindex C-c C-l @r{(Calendar mode)} -@findex calendar-redraw - If the calendar window text gets corrupted, type @kbd{C-c C-l} -(@code{calendar-redraw}) to redraw it. (This can only happen if you use -non-Calendar-mode editing commands.) - -@kindex SPC @r{(Calendar mode)} - In Calendar mode, you can use @key{SPC} (@code{scroll-other-window}) -and @key{DEL} (@code{scroll-other-window-down}) to scroll the other -window (if there is one) up or down, respectively. This is handy when -you display a list of holidays or diary entries in another window. - -@kindex q @r{(Calendar mode)} -@findex exit-calendar -@vindex calendar-remove-frame-by-deleting - To exit from the calendar, type @kbd{q} (@code{calendar-exit}). This -buries all buffers related to the calendar, selecting other buffers. -(If a frame contains a dedicated calendar window, exiting from the -calendar deletes or iconifies that frame depending on the value of -@code{calendar-remove-frame-by-deleting}.) - -@c FIXME this mentions holidays and diary entries, albeit briefly, so -@c should it be moved after those sections? Or at least xref them. -@node Writing Calendar Files -@section Writing Calendar Files - - You can write calendars and diary entries to HTML and @LaTeX{} files. - -@cindex calendar and HTML - The Calendar HTML commands produce files of HTML code that contain -calendar, holiday, and diary entries. Each file applies to one month, -and has a name of the format @file{@var{yyyy}-@var{mm}.html}, where -@var{yyyy} and @var{mm} are the four-digit year and two-digit month, -respectively. The variable @code{cal-html-directory} specifies the -default output directory for the HTML files. To prevent holidays -from being shown, customize @code{cal-html-holidays}. - -@vindex cal-html-css-default - Diary entries enclosed by @code{<} and @code{>} are interpreted as -HTML tags (for example: this is a diary entry with some red text). You can change the overall -appearance of the displayed HTML pages (for example, the color of -various page elements, header styles) via a stylesheet @file{cal.css} in -the directory containing the HTML files (see the value of the variable -@code{cal-html-css-default} for relevant style settings). - -@kindex t @r{(Calendar mode)} -@table @kbd -@item H m -Generate a one-month calendar (@code{cal-html-cursor-month}). -@item H y -Generate a calendar file for each month of a year, as well as an index -page (@code{cal-html-cursor-year}). By default, this command writes -files to a @var{yyyy} subdirectory---if this is altered some hyperlinks -between years will not work. -@end table - - If the variable @code{cal-html-print-day-number-flag} is -non-@code{nil}, then the monthly calendars show the day-of-the-year -number. The variable @code{cal-html-year-index-cols} specifies the -number of columns in the yearly index page. - -@cindex calendar and @LaTeX{} - The Calendar @LaTeX{} commands produce a buffer of @LaTeX{} code that -prints as a calendar. Depending on the command you use, the printed -calendar covers the day, week, month or year that point is in. - -@kindex t @r{(Calendar mode)} -@table @kbd -@item t m -Generate a one-month calendar (@code{cal-tex-cursor-month}). -@item t M -Generate a sideways-printing one-month calendar -(@code{cal-tex-cursor-month-landscape}). -@item t d -Generate a one-day calendar -(@code{cal-tex-cursor-day}). -@item t w 1 -Generate a one-page calendar for one week, with hours -(@code{cal-tex-cursor-week}). -@item t w 2 -Generate a two-page calendar for one week, with hours -(@code{cal-tex-cursor-week2}). -@item t w 3 -Generate an ISO-style calendar for one week, without hours -(@code{cal-tex-cursor-week-iso}). -@item t w 4 -Generate a calendar for one Monday-starting week, with hours -(@code{cal-tex-cursor-week-monday}). -@item t w W -Generate a two-page calendar for one week, without hours -(@code{cal-tex-cursor-week2-summary}). -@item t f w -Generate a Filofax-style two-weeks-at-a-glance calendar -(@code{cal-tex-cursor-filofax-2week}). -@item t f W -Generate a Filofax-style one-week-at-a-glance calendar -(@code{cal-tex-cursor-filofax-week}). -@item t y -Generate a calendar for one year -(@code{cal-tex-cursor-year}). -@item t Y -Generate a sideways-printing calendar for one year -(@code{cal-tex-cursor-year-landscape}). -@item t f y -Generate a Filofax-style calendar for one year -(@code{cal-tex-cursor-filofax-year}). -@end table - - Some of these commands print the calendar sideways (in ``landscape -mode''), so it can be wider than it is long. Some of them use Filofax -paper size (3.75in x 6.75in). All of these commands accept a prefix -argument, which specifies how many days, weeks, months or years to print -(starting always with the selected one). - - If the variable @code{cal-tex-holidays} is non-@code{nil} (the default), -then the printed calendars show the holidays in @code{calendar-holidays}. -If the variable @code{cal-tex-diary} is non-@code{nil} (the default is -@code{nil}), diary entries are included also (in monthly, filofax, and -iso-week calendars only). If the variable @code{cal-tex-rules} is -non-@code{nil} (the default is @code{nil}), the calendar displays ruled -pages in styles that have sufficient room. Consult the documentation of -the individual cal-tex functions to see which calendars support which -features. - - You can use the variable @code{cal-tex-preamble-extra} to insert extra -@LaTeX{} commands in the preamble of the generated document if you need -to. - -@node Holidays -@section Holidays -@cindex holidays - - The Emacs calendar knows about many major and minor holidays, -and can display them. You can add your own holidays to the default list. - -@table @kbd -@item Mouse-3 Holidays -@itemx h -Display holidays for the selected date -(@code{calendar-cursor-holidays}). -@item x -Mark holidays in the calendar window (@code{calendar-mark-holidays}). -@item u -Unmark calendar window (@code{calendar-unmark}). -@item a -List all holidays for the displayed three months in another window -(@code{calendar-list-holidays}). -@item M-x holidays -List all holidays for three months around today's date in another -window. -@item M-x list-holidays -List holidays in another window for a specified range of years. -@end table - -@kindex h @r{(Calendar mode)} -@findex calendar-cursor-holidays -@vindex calendar-view-holidays-initially-flag - To see if any holidays fall on a given date, position point on that -date in the calendar window and use the @kbd{h} command. Alternatively, -click on that date with @kbd{Mouse-3} and then choose @kbd{Holidays} -from the menu that appears. Either way, this displays the holidays for -that date, in the echo area if they fit there, otherwise in a separate -window. - -@kindex x @r{(Calendar mode)} -@findex calendar-mark-holidays -@kindex u @r{(Calendar mode)} -@findex calendar-unmark -@vindex calendar-mark-holidays-flag - To view the distribution of holidays for all the dates shown in the -calendar, use the @kbd{x} command. This displays the dates that are -holidays in a different face. -@iftex -@xref{Calendar Customizing,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Calendar Customizing, calendar-holiday-marker}. -@end ifnottex - The command applies both to the currently visible months and to -other months that subsequently become visible by scrolling. To turn -marking off and erase the current marks, type @kbd{u}, which also -erases any diary marks (@pxref{Diary}). If the variable -@code{calendar-mark-holidays-flag} is non-@code{nil}, creating or -updating the calendar marks holidays automatically. - -@kindex a @r{(Calendar mode)} -@findex calendar-list-holidays - To get even more detailed information, use the @kbd{a} command, which -displays a separate buffer containing a list of all holidays in the -current three-month range. You can use @key{SPC} and @key{DEL} in the -calendar window to scroll that list up and down, respectively. - -@findex holidays - The command @kbd{M-x holidays} displays the list of holidays for the -current month and the preceding and succeeding months; this works even -if you don't have a calendar window. If the variable -@code{calendar-view-holidays-initially-flag} is non-@code{nil}, creating -the calendar displays holidays in this way. If you want the list of -holidays centered around a different month, use @kbd{C-u M-x -holidays}, which prompts for the month and year. - - The holidays known to Emacs include United States holidays and the -major Bahá'í, Chinese, Christian, Islamic, and Jewish holidays; also the -solstices and equinoxes. - -@findex list-holidays - The command @kbd{M-x holiday-list} displays the list of holidays for -a range of years. This function asks you for the starting and stopping -years, and allows you to choose all the holidays or one of several -categories of holidays. You can use this command even if you don't have -a calendar window. - - The dates used by Emacs for holidays are based on @emph{current -practice}, not historical fact. For example Veteran's Day began in -1919, but is shown in earlier years. - -@node Sunrise/Sunset -@section Times of Sunrise and Sunset -@cindex sunrise and sunset - - Special calendar commands can tell you, to within a minute or two, the -times of sunrise and sunset for any date. - -@table @kbd -@item Mouse-3 Sunrise/sunset -@itemx S -Display times of sunrise and sunset for the selected date -(@code{calendar-sunrise-sunset}). -@item M-x sunrise-sunset -Display times of sunrise and sunset for today's date. -@item C-u M-x sunrise-sunset -Display times of sunrise and sunset for a specified date. -@item M-x calendar-sunrise-sunset-month -Display times of sunrise and sunset for the selected month. -@end table - -@kindex S @r{(Calendar mode)} -@findex calendar-sunrise-sunset -@findex sunrise-sunset - Within the calendar, to display the @emph{local times} of sunrise and -sunset in the echo area, move point to the date you want, and type -@kbd{S}. Alternatively, click @kbd{Mouse-3} on the date, then choose -@samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x -sunrise-sunset} is available outside the calendar to display this -information for today's date or a specified date. To specify a date -other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for -the year, month, and day. - - You can display the times of sunrise and sunset for any location and -any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a -longitude, latitude, number of minutes difference from Coordinated -Universal Time, and date, and then tells you the times of sunrise and -sunset for that location on that date. - - Because the times of sunrise and sunset depend on the location on -earth, you need to tell Emacs your latitude, longitude, and location -name before using these commands. Here is an example of what to set: - -@vindex calendar-location-name -@vindex calendar-longitude -@vindex calendar-latitude -@example -(setq calendar-latitude 40.1) -(setq calendar-longitude -88.2) -(setq calendar-location-name "Urbana, IL") -@end example - -@noindent -Use one decimal place in the values of @code{calendar-latitude} and -@code{calendar-longitude}. - - Your time zone also affects the local time of sunrise and sunset. -Emacs usually gets time zone information from the operating system, but -if these values are not what you want (or if the operating system does -not supply them), you must set them yourself. Here is an example: - -@vindex calendar-time-zone -@vindex calendar-standard-time-zone-name -@vindex calendar-daylight-time-zone-name -@example -(setq calendar-time-zone -360) -(setq calendar-standard-time-zone-name "CST") -(setq calendar-daylight-time-zone-name "CDT") -@end example - -@noindent -The value of @code{calendar-time-zone} is the number of minutes -difference between your local standard time and Coordinated Universal -Time (Greenwich time). The values of -@code{calendar-standard-time-zone-name} and -@code{calendar-daylight-time-zone-name} are the abbreviations used in -your time zone. Emacs displays the times of sunrise and sunset -@emph{corrected for daylight saving time}. @xref{Daylight Saving}, -for how daylight saving time is determined. - - As a user, you might find it convenient to set the calendar location -variables for your usual physical location in your @file{.emacs} file. -If you are a system administrator, you may want to set these variables -for all users in a @file{default.el} file. @xref{Init File}. - -@node Lunar Phases -@section Phases of the Moon -@cindex phases of the moon -@cindex moon, phases of - - These calendar commands display the dates and times of the phases of -the moon (new moon, first quarter, full moon, last quarter). This -feature is useful for debugging problems that ``depend on the phase of -the moon''. - -@table @kbd -@item M -Display the dates and times for all the quarters of the moon for the -three-month period shown (@code{calendar-lunar-phases}). -@item M-x lunar-phases -Display dates and times of the quarters of the moon for three months around -today's date. -@end table - -@kindex M @r{(Calendar mode)} -@findex calendar-lunar-phases - Within the calendar, use the @kbd{M} command to display a separate -buffer of the phases of the moon for the current three-month range. The -dates and times listed are accurate to within a few minutes. - -@findex lunar-phases - Outside the calendar, use the command @kbd{M-x lunar-phases} to -display the list of the phases of the moon for the current month and the -preceding and succeeding months. For information about a different -month, use @kbd{C-u M-x lunar-phases}, which prompts for the month and -year. - - The dates and times given for the phases of the moon are given in -local time (corrected for daylight saving, when appropriate). -See the discussion in the previous section. @xref{Sunrise/Sunset}. - -@node Other Calendars -@section Conversion To and From Other Calendars - -@cindex Gregorian calendar - The Emacs calendar displayed is @emph{always} the Gregorian calendar, -sometimes called the ``new style'' calendar, which is used in most of -the world today. However, this calendar did not exist before the -sixteenth century and was not widely used before the eighteenth century; -it did not fully displace the Julian calendar and gain universal -acceptance until the early twentieth century. The Emacs calendar can -display any month since January, year 1 of the current era, but the -calendar displayed is always the Gregorian, even for a date at which -the Gregorian calendar did not exist. - - While Emacs cannot display other calendars, it can convert dates to -and from several other calendars. - -@menu -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. -@end menu - -@c FIXME perhaps most of the details should be moved to cal-xtra. -@c Just list the major supported systems here? -@node Calendar Systems -@subsection Supported Calendar Systems - -@cindex ISO commercial calendar - The ISO commercial calendar is often used in business. - -@cindex Julian calendar - The Julian calendar, named after Julius Caesar, was the one used in Europe -throughout medieval times, and in many countries up until the nineteenth -century. - -@cindex Julian day numbers -@cindex astronomical day numbers - Astronomers use a simple counting of days elapsed since noon, Monday, -January 1, 4713 B.C. on the Julian calendar. The number of days elapsed -is called the @dfn{Julian day number} or the @dfn{Astronomical day number}. - -@cindex Hebrew calendar - The Hebrew calendar is used by tradition in the Jewish religion. The -Emacs calendar program uses the Hebrew calendar to determine the dates -of Jewish holidays. Hebrew calendar dates begin and end at sunset. - -@cindex Islamic calendar - The Islamic calendar is used in many predominantly Islamic countries. -Emacs uses it to determine the dates of Islamic holidays. There is no -universal agreement in the Islamic world about the calendar; Emacs uses -a widely accepted version, but the precise dates of Islamic holidays -often depend on proclamation by religious authorities, not on -calculations. As a consequence, the actual dates of observance can vary -slightly from the dates computed by Emacs. Islamic calendar dates begin -and end at sunset. - -@cindex French Revolutionary calendar - The French Revolutionary calendar was created by the Jacobins after the 1789 -revolution, to represent a more secular and nature-based view of the annual -cycle, and to install a 10-day week in a rationalization measure similar to -the metric system. The French government officially abandoned this -calendar at the end of 1805. - -@cindex Mayan calendar - The Maya of Central America used three separate, overlapping calendar -systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}. -Emacs knows about all three of these calendars. Experts dispute the -exact correlation between the Mayan calendar and our calendar; Emacs uses the -Goodman-Martinez-Thompson correlation in its calculations. - -@cindex Coptic calendar -@cindex Ethiopic calendar - The Copts use a calendar based on the ancient Egyptian solar calendar. -Their calendar consists of twelve 30-day months followed by an extra -five-day period. Once every fourth year they add a leap day to this -extra period to make it six days. The Ethiopic calendar is identical in -structure, but has different year numbers and month names. - -@cindex Persian calendar - The Persians use a solar calendar based on a design of Omar Khayyam. -Their calendar consists of twelve months of which the first six have 31 -days, the next five have 30 days, and the last has 29 in ordinary years -and 30 in leap years. Leap years occur in a complicated pattern every -four or five years. -The calendar implemented here is the arithmetical Persian calendar -championed by Birashk, based on a 2,820-year cycle. It differs from -the astronomical Persian calendar, which is based on astronomical -events. As of this writing the first future discrepancy is projected -to occur on March 20, 2025. It is currently not clear what the -official calendar of Iran will be at that time. -@c FIXME not so far in the future now. - -@cindex Chinese calendar - The Chinese calendar is a complicated system of lunar months arranged -into solar years. The years go in cycles of sixty, each year containing -either twelve months in an ordinary year or thirteen months in a leap -year; each month has either 29 or 30 days. Years, ordinary months, and -days are named by combining one of ten ``celestial stems'' with one of -twelve ``terrestrial branches'' for a total of sixty names that are -repeated in a cycle of sixty. - -@cindex Bahá'í calendar - The Bahá'í calendar system is based on a solar cycle of 19 months with -19 days each. The four remaining ``intercalary'' days are placed -between the 18th and 19th months. - -@node To Other Calendar -@subsection Converting To Other Calendars - - The following commands describe the selected date (the date at point) -in various other calendar systems: - -@table @kbd -@kindex p @r{(Calendar mode)} -@findex calendar-print-other-dates -@item Mouse-3 Other calendars -@itemx p o -Display the selected date in various other calendars. -(@code{calendar-print-other-dates}). -@findex calendar-iso-print-date -@item p c -Display ISO commercial calendar equivalent for selected day -(@code{calendar-iso-print-date}). -@findex calendar-julian-print-date -@item p j -Display Julian date for selected day (@code{calendar-julian-print-date}). -@findex calendar-astro-print-day-number -@item p a -Display astronomical (Julian) day number for selected day -(@code{calendar-astro-print-day-number}). -@findex calendar-hebrew-print-date -@item p h -Display Hebrew date for selected day (@code{calendar-hebrew-print-date}). -@findex calendar-islamic-print-date -@item p i -Display Islamic date for selected day (@code{calendar-islamic-print-date}). -@findex calendar-french-print-date -@item p f -Display French Revolutionary date for selected day -(@code{calendar-french-print-date}). -@findex calendar-bahai-print-date -@item p b -Display Bahá'í date for selected day -(@code{calendar-bahai-print-date}). -@findex calendar-chinese-print-date -@item p C -Display Chinese date for selected day -(@code{calendar-chinese-print-date}). -@findex calendar-coptic-print-date -@item p k -Display Coptic date for selected day -(@code{calendar-coptic-print-date}). -@findex calendar-ethiopic-print-date -@item p e -Display Ethiopic date for selected day -(@code{calendar-ethiopic-print-date}). -@findex calendar-persian-print-date -@item p p -Display Persian date for selected day -(@code{calendar-persian-print-date}). -@findex calendar-mayan-print-date -@item p m -Display Mayan date for selected day (@code{calendar-mayan-print-date}). -@end table - - Otherwise, move point to the date you want to convert, then type the -appropriate command starting with @kbd{p} from the table above. The -prefix @kbd{p} is a mnemonic for ``print'', since Emacs ``prints'' the -equivalent date in the echo area. @kbd{p o} displays the -date in all forms known to Emacs. You can also use @kbd{Mouse-3} and -then choose @kbd{Other calendars} from the menu that appears. This -displays the equivalent forms of the date in all the calendars Emacs -understands, in the form of a menu. (Choosing an alternative from -this menu doesn't actually do anything---the menu is used only for -display.) - -@node From Other Calendar -@subsection Converting From Other Calendars - - You can use the other supported calendars to specify a date to move -to. This section describes the commands for doing this using calendars -other than Mayan; for the Mayan calendar, see the following section. - -@kindex g @var{char} @r{(Calendar mode)} -@findex calendar-iso-goto-date -@findex calendar-iso-goto-week -@findex calendar-julian-goto-date -@findex calendar-astro-goto-day-number -@findex calendar-bahai-goto-date -@findex calendar-hebrew-goto-date -@findex calendar-islamic-goto-date -@findex calendar-french-goto-date -@findex calendar-chinese-goto-date -@findex calendar-persian-goto-date -@findex calendar-coptic-goto-date -@findex calendar-ethiopic-goto-date -@table @kbd -@item g c -Move to a date specified in the ISO commercial calendar -(@code{calendar-iso-goto-date}). -@item g w -Move to a week specified in the ISO commercial calendar -(@code{calendar-iso-goto-week}). -@item g j -Move to a date specified in the Julian calendar -(@code{calendar-julian-goto-date}). -@item g a -Move to a date specified with an astronomical (Julian) day number -(@code{calendar-astro-goto-day-number}). -@item g b -Move to a date specified in the Bahá'í calendar -(@code{calendar-bahai-goto-date}). -@item g h -Move to a date specified in the Hebrew calendar -(@code{calendar-hebrew-goto-date}). -@item g i -Move to a date specified in the Islamic calendar -(@code{calendar-islamic-goto-date}). -@item g f -Move to a date specified in the French Revolutionary calendar -(@code{calendar-french-goto-date}). -@item g C -Move to a date specified in the Chinese calendar -(@code{calendar-chinese-goto-date}). -@item g p -Move to a date specified in the Persian calendar -(@code{calendar-persian-goto-date}). -@item g k -Move to a date specified in the Coptic calendar -(@code{calendar-coptic-goto-date}). -@item g e -Move to a date specified in the Ethiopic calendar -(@code{calendar-ethiopic-goto-date}). -@end table - - These commands ask you for a date on the other calendar, move point -to the Gregorian calendar date equivalent to that date, and display -the other calendar's date in the echo area. Emacs uses strict -completion (@pxref{Completion Exit}) whenever it asks you to type a -month name, so you don't have to worry about the spelling of Hebrew, -Islamic, or French names. - -@c FIXME move? -@findex calendar-hebrew-list-yahrzeits -@cindex yahrzeits - One common issue concerning the Hebrew calendar is the computation -of the anniversary of a date of death, called a ``yahrzeit''. The Emacs -calendar includes a facility for such calculations. If you are in the -calendar, the command @kbd{M-x calendar-hebrew-list-yahrzeits} asks you for -a range of years and then displays a list of the yahrzeit dates for those -years for the date given by point. If you are not in the calendar, -this command first asks you for the date of death and the range of -years, and then displays the list of yahrzeit dates. - -@node Diary -@section The Diary -@cindex diary - - The Emacs diary keeps track of appointments or other events on a daily -basis, in conjunction with the calendar. To use the diary feature, you -must first create a @dfn{diary file} containing a list of events and -their dates. Then Emacs can automatically pick out and display the -events for today, for the immediate future, or for any specified -date. - - The name of the diary file is specified by the variable -@code{diary-file}; @file{~/diary} is the default. Here's an example -showing what that file looks like: - -@example -12/22/2012 Twentieth wedding anniversary!! -&1/1. Happy New Year! -10/22 Ruth's birthday. -* 21, *: Payday -Tuesday--weekly meeting with grad students at 10am - Supowit, Shen, Bitner, and Kapoor to attend. -1/13/89 Friday the thirteenth!! -&thu 4pm squash game with Lloyd. -mar 16 Dad's birthday -April 15, 2013 Income tax due. -&* 15 time cards due. -@end example - -@noindent -This format is essentially the same as the one used by the separate -@command{calendar} utility that is present on some Unix systems. This -example uses extra spaces to align the event descriptions of most of -the entries. Such formatting is purely a matter of taste. - - Although you probably will start by creating a diary manually, Emacs -provides a number of commands to let you view, add, and change diary -entries. - -@menu -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. -@end menu - -@node Displaying the Diary -@subsection Displaying the Diary - - Once you have created a diary file, you can use the calendar to view -it. You can also view today's events outside of Calendar mode. In the -following, key bindings refer to the Calendar buffer. - -@table @kbd -@item Mouse-3 Diary -@itemx d -Display all diary entries for the selected date -(@code{diary-view-entries}). -@item s -Display the entire diary file (@code{diary-show-all-entries}). -@item m -Mark all visible dates that have diary entries -(@code{diary-mark-entries}). -@item u -Unmark the calendar window (@code{calendar-unmark}). -@item M-x diary-print-entries -Print hard copy of the diary display as it appears. -@item M-x diary -Display all diary entries for today's date. -@item M-x diary-mail-entries -Mail yourself email reminders about upcoming diary entries. -@end table - -@kindex d @r{(Calendar mode)} -@findex diary-view-entries -@vindex calendar-view-diary-initially-flag - Displaying the diary entries with @kbd{d} shows in a separate window -the diary entries for the selected date in the calendar. The mode line -of the new window shows the date of the diary entries. Holidays are -shown either in the buffer or in the mode line, depending on the display -method you choose -@iftex -(@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Diary Display}). -@end ifnottex -If you specify a numeric argument with @kbd{d}, it shows all the diary -entries for that many successive days. Thus, @kbd{2 d} displays all the -entries for the selected date and for the following day. - - Another way to display the diary entries for a date is to click -@kbd{Mouse-3} on the date, and then choose @kbd{Diary entries} from -the menu that appears. If the variable -@code{calendar-view-diary-initially-flag} is non-@code{nil}, creating the -calendar lists the diary entries for the current date (provided the -current date is visible). - -@kindex m @r{(Calendar mode)} -@findex diary-mark-entries -@vindex calendar-mark-diary-entries-flag - To get a broader view of which days are mentioned in the diary, use -the @kbd{m} command. This marks the dates that have diary entries in -a different face. -@iftex -@xref{Calendar Customizing,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Calendar Customizing, diary-entry-marker}. -@end ifnottex - - This command applies both to the months that are currently visible -and to those that subsequently become visible after scrolling. To turn -marking off and erase the current marks, type @kbd{u}, which also -turns off holiday marks (@pxref{Holidays}). If the variable -@code{calendar-mark-diary-entries-flag} is non-@code{nil}, creating or -updating the calendar marks diary dates automatically. - -@kindex s @r{(Calendar mode)} -@findex diary-show-all-entries - To see the full diary file, rather than just some of the entries, use -the @kbd{s} command. - -@findex diary - The command @kbd{M-x diary} displays the diary entries for the current -date, independently of the calendar display, and optionally for the next -few days as well; the variable @code{diary-number-of-entries} specifies -how many days to include. -@iftex -@xref{Diary Customizing,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Diary Customizing, diary-number-of-entries}. -@end ifnottex - - If you put @code{(diary)} in your @file{.emacs} file, this -automatically displays a window with the day's diary entries when you -start Emacs. - -@findex diary-mail-entries -@vindex diary-mail-days - Some people like to receive email notifications of events in their -diary. To send such mail to yourself, use the command @kbd{M-x -diary-mail-entries}. A prefix argument specifies how many days -(starting with today) to check; otherwise, the variable -@code{diary-mail-days} says how many days. - -@node Format of Diary File -@subsection The Diary File -@cindex diary file - -@vindex diary-file - Your @dfn{diary file} is a file that records events associated with -particular dates. The name of the diary file is specified by the -variable @code{diary-file}; @file{~/diary} is the default. The -@code{calendar} utility program supports a subset of the format allowed -by the Emacs diary facilities, so you can use that utility to view the -diary file, with reasonable results aside from the entries it cannot -understand. - - Each entry in the diary file describes one event and consists of one -or more lines. An entry always begins with a date specification at the -left margin. The rest of the entry is simply text to describe the -event. If the entry has more than one line, then the lines after the -first must begin with whitespace to indicate they continue a previous -entry. Lines that do not begin with valid dates and do not continue a -preceding entry are ignored. - - You can also use a format where the first line of a diary entry -consists only of the date or day name (with no following blanks or -punctuation). For example: - -@example -02/11/2012 - Bill B. visits Princeton today - 2pm Cognitive Studies Committee meeting - 2:30-5:30 Liz at Lawrenceville - 4:00pm Dentist appt - 7:30pm Dinner at George's - 8:00-10:00pm concert -@end example - -@noindent -This entry will have a different appearance if you use the simple diary -display -@iftex -(@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Diary Display}). -@end ifnottex -The simple diary display omits the date line at the beginning; only the -continuation lines appear. This style of entry looks neater when you -display just a single day's entries, but can cause confusion if you ask -for more than one day's entries. - -@vindex diary-nonmarking-symbol - You can inhibit the marking of certain diary entries in the calendar -window; to do this, insert the string that -@code{diary-nonmarking-symbol} specifies (default @samp{&}) at the -beginning of the entry, before the date. This -has no effect on display of the entry in the diary window; it only -affects marks on dates in the calendar window. Nonmarking entries are -especially useful for generic entries that would otherwise mark many -different dates. - -@node Date Formats -@subsection Date Formats - - Here are some sample diary entries, illustrating different ways of -formatting a date. The examples all show dates in American order -(month, day, year), but Calendar mode supports European order (day, -month, year) and ISO order (year, month, day) as options. - -@example -4/20/12 Switch-over to new tabulation system -apr. 25 Start tabulating annual results -4/30 Results for April are due -*/25 Monthly cycle finishes -Friday Don't leave without backing up files -@end example - - The first entry appears only once, on April 20, 2012. The second and -third appear every year on the specified dates, and the fourth uses a -wildcard (asterisk) for the month, so it appears on the 25th of every -month. The final entry appears every week on Friday. - - You can use just numbers to express a date, as in -@samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}. -This must be followed by a nondigit. In the date itself, @var{month} -and @var{day} are numbers of one or two digits. The optional @var{year} -is also a number, and may be abbreviated to the last two digits; that -is, you can use @samp{11/12/2012} or @samp{11/12/12}. - - Dates can also have the form @samp{@var{monthname} @var{day}} or -@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can -be spelled in full or abbreviated (with or without a period). The -preferred abbreviations for month and day names can be set using -the variables @code{calendar-abbrev-length}, -@code{calendar-month-abbrev-array}, and -@code{calendar-day-abbrev-array}. The default is to use the first three -letters of a name as its abbreviation. Case is not significant. - - A date may be @dfn{generic}; that is, partially unspecified. Then the -entry applies to all dates that match the specification. If the date -does not contain a year, it is generic and applies to any year. -Alternatively, @var{month}, @var{day}, or @var{year} can be @samp{*}; -this matches any month, day, or year, respectively. Thus, a diary entry -@samp{3/*/*} matches any day in March of any year; so does @samp{march -*}. - -@vindex calendar-date-style -@findex calendar-set-date-style - If you prefer the European style of writing dates (in which the day -comes before the month), or the ISO style (in which the order is year, -month, day), type @kbd{M-x calendar-set-date-style} while in the -calendar, or customize the variable @code{calendar-date-style}. This -affects how diary dates are interpreted, date display, and the order in -which some commands expect their arguments to be given. - - You can use the name of a day of the week as a generic date which -applies to any date falling on that day of the week. You can abbreviate -the day of the week as described above, or spell it in full; case is not -significant. - -@node Adding to Diary -@subsection Commands to Add to the Diary - - While in the calendar, there are several commands to create diary -entries. The basic commands are listed here; more sophisticated -commands are in the next section (@pxref{Special Diary Entries}). -Entries can also be based on non-Gregorian calendars. -@iftex -@xref{Non-Gregorian Diary,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Non-Gregorian Diary}. -@end ifnottex - -@table @kbd -@item i d -Add a diary entry for the selected date (@code{diary-insert-entry}). -@item i w -Add a diary entry for the selected day of the week (@code{diary-insert-weekly-entry}). -@item i m -Add a diary entry for the selected day of the month (@code{diary-insert-monthly-entry}). -@item i y -Add a diary entry for the selected day of the year (@code{diary-insert-yearly-entry}). -@end table - -@kindex i d @r{(Calendar mode)} -@findex diary-insert-entry - You can make a diary entry for a specific date by selecting that date -in the calendar window and typing the @kbd{i d} command. This command -displays the end of your diary file in another window and inserts the -date; you can then type the rest of the diary entry. - -@kindex i w @r{(Calendar mode)} -@findex diary-insert-weekly-entry -@kindex i m @r{(Calendar mode)} -@findex diary-insert-monthly-entry -@kindex i y @r{(Calendar mode)} -@findex diary-insert-yearly-entry - If you want to make a diary entry that applies to a specific day of -the week, select that day of the week (any occurrence will do) and type -@kbd{i w}. This inserts the day-of-week as a generic date; you can then -type the rest of the diary entry. You can make a monthly diary entry in -the same fashion: select the day of the month, use the @kbd{i m} -command, and type the rest of the entry. Similarly, you can insert a -yearly diary entry with the @kbd{i y} command. - - All of the above commands make marking diary entries by default. To -make a nonmarking diary entry, give a prefix argument to the command. -For example, @kbd{C-u i w} makes a nonmarking weekly diary entry. - - When you modify the diary file, be sure to save the file before -exiting Emacs. Saving the diary file after using any of the above -insertion commands will automatically update the diary marks in the -calendar window, if appropriate. You can use the command -@code{calendar-redraw} to force an update at any time. - -@node Special Diary Entries -@subsection Special Diary Entries - - In addition to entries based on calendar dates, the diary file can -contain @dfn{sexp entries} for regular events such as anniversaries. -These entries are based on Lisp expressions (sexps) that Emacs evaluates -as it scans the diary file. Instead of a date, a sexp entry contains -@samp{%%} followed by a Lisp expression which must begin and end with -parentheses. The Lisp expression determines which dates the entry -applies to. - - Calendar mode provides commands to insert certain commonly used -sexp entries: - -@table @kbd -@item i a -Add an anniversary diary entry for the selected date -(@code{diary-insert-anniversary-entry}). -@item i b -Add a block diary entry for the current region -(@code{diary-insert-block-entry}). -@item i c -Add a cyclic diary entry starting at the date -(@code{diary-insert-cyclic-entry}). -@end table - -@kindex i a @r{(Calendar mode)} -@findex diary-insert-anniversary-entry - If you want to make a diary entry that applies to the anniversary of a -specific date, move point to that date and use the @kbd{i a} command. -This displays the end of your diary file in another window and inserts -the anniversary description; you can then type the rest of the diary -entry. The entry looks like this: - -@findex diary-anniversary -@example -%%(diary-anniversary 10 31 1948) Arthur's birthday -@end example - -@noindent -This entry applies to October 31 in any year after 1948; @samp{10 31 -1948} specifies the date. (If you are using the European or ISO -calendar style, the input order of month, day and year is different.) -The reason this expression requires a beginning year is that advanced -diary functions can use it to calculate the number of elapsed years. - - A @dfn{block} diary entry applies to a specified range of consecutive -dates. Here is a block diary entry that applies to all dates from June -24, 2012 through July 10, 2012: - -@findex diary-block -@example -%%(diary-block 6 24 2012 7 10 2012) Vacation -@end example - -@noindent -The @samp{6 24 2012} indicates the starting date and the @samp{7 10 2012} -indicates the stopping date. (Again, if you are using the European or ISO -calendar style, the input order of month, day and year is different.) - -@kindex i b @r{(Calendar mode)} -@findex diary-insert-block-entry - To insert a block entry, place point and the mark on the two -dates that begin and end the range, and type @kbd{i b}. This command -displays the end of your diary file in another window and inserts the -block description; you can then type the diary entry. - -@kindex i c @r{(Calendar mode)} -@findex diary-insert-cyclic-entry - @dfn{Cyclic} diary entries repeat after a fixed interval of days. To -create one, select the starting date and use the @kbd{i c} command. The -command prompts for the length of interval, then inserts the entry, -which looks like this: - -@findex diary-cyclic -@example -%%(diary-cyclic 50 3 1 2012) Renew medication -@end example - -@noindent -This entry applies to March 1, 2012 and every 50th day following; -@samp{3 1 2012} specifies the starting date. (If you are using the -European or ISO calendar style, the input order of month, day and year -is different.) - - All three of these commands make marking diary entries. To insert a -nonmarking entry, give a prefix argument to the command. For example, -@kbd{C-u i a} makes a nonmarking anniversary diary entry. - - Marking sexp diary entries in the calendar can be time-consuming, -since every date visible in the calendar window must be individually -checked. So it's a good idea to make sexp diary entries nonmarking -(with @samp{&}) when possible. - - Another sophisticated kind of sexp entry, a @dfn{floating} diary entry, -specifies a regularly occurring event by offsets specified in days, -weeks, and months. It is comparable to a crontab entry interpreted by -the @code{cron} utility. Here is a nonmarking, floating diary entry -that applies to the fourth Thursday in November: - -@findex diary-float -@example -&%%(diary-float 11 4 4) American Thanksgiving -@end example - -@noindent -The 11 specifies November (the eleventh month), the 4 specifies Thursday -(the fourth day of the week, where Sunday is numbered zero), and the -second 4 specifies the fourth Thursday (1 would mean ``first'', 2 would -mean ``second'', @minus{}2 would mean ``second-to-last'', and so on). -The month can be a single month or a list of months. Thus you could change -the 11 above to @samp{'(1 2 3)} and have the entry apply to the last -Thursday of January, February, and March. If the month is @code{t}, the -entry applies to all months of the year. - - Each of the standard sexp diary entries takes an optional parameter -specifying the name of a face or a single-character string to use when -marking the entry in the calendar. Most generally, sexp diary entries -can perform arbitrary computations to determine when they apply. -@iftex -@xref{Sexp Diary Entries,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Sexp Diary Entries}. -@end ifnottex - -@node Appointments -@section Appointments -@cindex appointment notification - -@vindex appt-display-format -@vindex appt-audible -@vindex appt-display-mode-line - If you have a diary entry for an appointment, and that diary entry -begins with a recognizable time of day, Emacs can warn you in advance -that an appointment is pending. Emacs alerts you -to the appointment by displaying a message in your chosen format, as -specified by the variable @code{appt-display-format}. If the value of -@code{appt-audible} is non-@code{nil}, the warning includes an audible -reminder. In addition, if @code{appt-display-mode-line} is -non-@code{nil}, Emacs displays the number of minutes to the -appointment on the mode line. - -@vindex appt-display-duration -@vindex appt-disp-window-function -@vindex appt-delete-window-function - If @code{appt-display-format} has the value @code{window}, then the -variable @code{appt-display-duration} controls how long the reminder -window is visible for; and the variables -@code{appt-disp-window-function} and @code{appt-delete-window-function} -give the names of functions used to create and destroy the window, -respectively. - -@findex appt-activate - To enable appointment notification, type @kbd{M-x appt-activate}. -With a positive argument, it enables notification; with a negative -argument, it disables notification; with no argument, it toggles. -Enabling notification also sets up an appointment list for today from -the diary file, giving all diary entries found with recognizable times -of day, and reminds you just before each of them. - - For example, suppose the diary file contains these lines: - -@example -Monday - 9:30am Coffee break - 12:00pm Lunch -@end example - -@vindex appt-message-warning-time -@vindex appt-warning-time-regexp -@noindent -Then on Mondays, you will be reminded at around 9:20am about your -coffee break and at around 11:50am about lunch. The variable -@code{appt-message-warning-time} specifies how many minutes (default 12) -in advance to warn you. This is a default warning time. Each -appointment can specify a different warning time by adding a piece -matching @code{appt-warning-time-regexp} (see that variable's -documentation for details). - - You can write times in am/pm style (with @samp{12:00am} standing -for midnight and @samp{12:00pm} standing for noon), or 24-hour -European/military style. You need not be consistent; your diary file -can have a mixture of the two styles. Times must be at the beginning of -diary entries if they are to be recognized. - -@vindex appt-display-diary - Emacs updates the appointments list from the diary file -automatically just after midnight. You can force an update at any -time by re-enabling appointment notification. Both these actions also -display the day's diary buffer, unless you set -@code{appt-display-diary} to @code{nil}. The appointments list is -also updated whenever the diary file (or a file it includes; see -@iftex -@ref{Fancy Diary Display,,, emacs-xtra, Specialized Emacs Features}) -@end iftex -@ifnottex -@ref{Fancy Diary Display}) -@end ifnottex -is saved. - -@findex appt-add -@findex appt-delete -@cindex alarm clock - You can also use the appointment notification facility like an alarm -clock. The command @kbd{M-x appt-add} adds entries to the appointment -list without affecting your diary file. You delete entries from the -appointment list with @kbd{M-x appt-delete}. - -@node Importing Diary -@section Importing and Exporting Diary Entries - - You can transfer diary entries between Emacs diary files and a -variety of other formats. - -@vindex diary-outlook-formats - You can import diary entries from Outlook-generated appointment -messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x -diary-from-outlook} to import the entry. You can make this command -recognize additional appointment message formats by customizing the -variable @code{diary-outlook-formats}. Other mail clients can set -@code{diary-from-outlook-function} to an appropriate value. - -@c FIXME the name of the RFC is hardly very relevant. -@cindex iCalendar support - The icalendar package allows you to transfer data between your Emacs -diary file and iCalendar files, which are defined in ``RFC -2445---Internet Calendaring and Scheduling Core Object Specification -(iCalendar)'' (as well as the earlier vCalendar format). - -@c Importing works for ``ordinary'' (i.e., non-recurring) events, but -@c (at present) may not work correctly (if at all) for recurring events. -@c Exporting of diary files into iCalendar files should work correctly -@c for most diary entries. This feature is a work in progress, so the -@c commands may evolve in future. - -@findex icalendar-import-buffer - The command @code{icalendar-import-buffer} extracts -iCalendar data from the current buffer and adds it to your -diary file. This function is also suitable for automatic extraction of -iCalendar data; for example with the Rmail mail client one could use: - -@example -(add-hook 'rmail-show-message-hook 'icalendar-import-buffer) -@end example - -@findex icalendar-import-file - The command @code{icalendar-import-file} imports an iCalendar file -and adds the results to an Emacs diary file. For example: - -@example -(icalendar-import-file "/here/is/calendar.ics" - "/there/goes/ical-diary") -@end example - -@noindent -You can use an @code{#include} directive to add the import file contents -to the main diary file, if these are different files. -@iftex -@xref{Fancy Diary Display,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Fancy Diary Display}. -@end ifnottex - - -@findex icalendar-export-file, icalendar-export-region - Use @code{icalendar-export-file} to interactively export an entire -Emacs diary file to iCalendar format. To export only a part of a diary -file, mark the relevant area, and call @code{icalendar-export-region}. -In both cases, Emacs appends the result to the target file. - -@node Daylight Saving -@section Daylight Saving Time -@cindex daylight saving time - - Emacs understands the difference between standard time and daylight -saving time---the times given for sunrise, sunset, solstices, -equinoxes, and the phases of the moon take that into account. The rules -for daylight saving time vary from place to place and have also varied -historically from year to year. To do the job properly, Emacs needs to -know which rules to use. - -@vindex calendar-daylight-savings-starts -@vindex calendar-daylight-savings-ends - Some operating systems keep track of the rules that apply to the place -where you are; on these systems, Emacs gets the information it needs -from the system automatically. If some or all of this information is -missing, Emacs fills in the gaps with the rules currently used in -Cambridge, Massachusetts. If the resulting rules are not what you want, -you can tell Emacs the rules to use by setting certain variables: -@code{calendar-daylight-savings-starts} and -@code{calendar-daylight-savings-ends}. - - These values should be Lisp expressions that refer to the variable -@code{year}, and evaluate to the Gregorian date on which daylight -saving time starts or (respectively) ends, in the form of a list -@code{(@var{month} @var{day} @var{year})}. The values should be -@code{nil} if your area does not use daylight saving time. - - Emacs uses these expressions to determine the starting date of -daylight saving time for the holiday list and for correcting times of -day in the solar and lunar calculations. - - The values for Cambridge, Massachusetts are as follows: - -@example -(calendar-nth-named-day 2 0 3 year) -(calendar-nth-named-day 1 0 11 year) -@end example - -@noindent -That is, the second 0th day (Sunday) of the third month (March) in -the year specified by @code{year}, and the first Sunday of the eleventh month -(November) of that year. If daylight saving time were -changed to start on October 1, you would set -@code{calendar-daylight-savings-starts} to this: - -@example -(list 10 1 year) -@end example - - If there is no daylight saving time at your location, or if you want -all times in standard time, set @code{calendar-daylight-savings-starts} -and @code{calendar-daylight-savings-ends} to @code{nil}. - -@vindex calendar-daylight-time-offset - The variable @code{calendar-daylight-time-offset} specifies the -difference between daylight saving time and standard time, measured in -minutes. The value for Cambridge, Massachusetts is 60. - -@c @vindex calendar-daylight-savings-starts-time too long! -@vindex calendar-daylight-savings-ends-time - Finally, the two variables -@code{calendar-daylight-savings-starts-time} and -@code{calendar-daylight-savings-ends-time} specify the number of -minutes after midnight local time when the transition to and from -daylight saving time should occur. For Cambridge, Massachusetts both -variables' values are 120. - -@node Time Intervals -@section Summing Time Intervals -@cindex time intervals, summing -@cindex summing time intervals -@cindex timeclock - - The timeclock package adds up time intervals, so you can (for -instance) keep track of how much time you spend working on particular -projects. - -@findex timeclock-in -@findex timeclock-out -@findex timeclock-change -@findex timeclock-workday-remaining -@findex timeclock-when-to-leave - Use the @kbd{M-x timeclock-in} command when you start working on a -project, and @kbd{M-x timeclock-out} command when you're done. Each -time you do this, it adds one time interval to the record of the -project. You can change to working on a different project with @kbd{M-x -timeclock-change}. - - Once you've collected data from a number of time intervals, you can use -@kbd{M-x timeclock-workday-remaining} to see how much time is left to -work today (assuming a typical average of 8 hours a day), and @kbd{M-x -timeclock-when-to-leave} which will calculate when you're ``done''. - -@vindex timeclock-modeline-display -@findex timeclock-modeline-display - If you want Emacs to display the amount of time ``left'' of your -workday in the mode line, either customize the -@code{timeclock-modeline-display} variable and set its value to -@code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command. - -@vindex timeclock-ask-before-exiting - Terminating the current Emacs session might or might not mean that -you have stopped working on the project and, by default, Emacs asks -you. You can, however, customize the value of the variable -@code{timeclock-ask-before-exiting} to @code{nil} to avoid the question; -then, only an explicit @kbd{M-x timeclock-out} or @kbd{M-x -timeclock-change} will tell Emacs that the current interval is over. - -@cindex @file{timelog} file -@vindex timeclock-file -@findex timeclock-reread-log - The timeclock functions work by accumulating the data in a file -called @file{~/.emacs.d/timelog}. You can specify a -different name for this file by customizing the variable -@code{timeclock-file}. If you edit the timeclock file manually, or if -you change the value of any of timeclock's customizable variables, you -should run the command @kbd{M-x timeclock-reread-log} to update the -data in Emacs from the file. - -@ifnottex -@include cal-xtra.texi -@end ifnottex diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi deleted file mode 100644 index b438281b2a2..00000000000 --- a/doc/emacs/cmdargs.texi +++ /dev/null @@ -1,1145 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Emacs Invocation -@appendix Command Line Arguments for Emacs Invocation -@cindex command line arguments -@cindex arguments (command line) -@cindex options (command line) -@cindex switches (command line) -@cindex startup (command line arguments) -@cindex invocation (command line arguments) -@c FIXME: Document `--smid'? --xfq - - Emacs supports command line arguments to request various actions -when invoking Emacs. These are for compatibility with other editors -and for sophisticated activities. We don't recommend using them for -ordinary editing (@xref{Emacs Server}, for a way to access an existing -Emacs job from the command line). - - Arguments starting with @samp{-} are @dfn{options}, and so is -@samp{+@var{linenum}}. All other arguments specify files to visit. -Emacs visits the specified files while it starts up. The last file -specified on the command line becomes the current buffer; the other -files are also visited in other buffers. As with most programs, the -special argument @samp{--} says that all subsequent arguments are file -names, not options, even if they start with @samp{-}. - - Emacs command options can specify many things, such as the size and -position of the X window Emacs uses, its colors, and so on. A few -options support advanced usage, such as running Lisp functions on files -in batch mode. The sections of this chapter describe the available -options, arranged according to their purpose. - - There are two ways of writing options: the short forms that start with -a single @samp{-}, and the long forms that start with @samp{--}. For -example, @samp{-d} is a short form and @samp{--display} is the -corresponding long form. - - The long forms with @samp{--} are easier to remember, but longer to -type. However, you don't have to spell out the whole option name; any -unambiguous abbreviation is enough. When a long option takes an -argument, you can use either a space or an equal sign to separate the -option name and the argument. Thus, you can write either -@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}. -We recommend an equal sign because it makes the relationship clearer, -and the tables below always show an equal sign. - -@cindex initial options (command line) -@cindex action options (command line) -@vindex command-line-args - Most options specify how to initialize Emacs, or set parameters for -the Emacs session. We call them @dfn{initial options}. A few options -specify things to do, such as loading libraries or calling Lisp -functions. These are called @dfn{action options}. These and file -names together are called @dfn{action arguments}. The action -arguments are stored as a list of strings in the variable -@code{command-line-args}. (Actually, when Emacs starts up, -@code{command-line-args} contains all the arguments passed from the -command line; during initialization, the initial arguments are removed -from this list when they are processed, leaving only the action -arguments.) - -@menu -* Action Arguments:: Arguments to visit files, load libraries, - and call functions. -* Initial Options:: Arguments that take effect while starting Emacs. -* Command Example:: Examples of using command line arguments. -* Environment:: Environment variables that Emacs uses. -* Display X:: Changing the default display and using remote login. -* Font X:: Choosing a font for text, under X. -* Colors X:: Choosing display colors. -* Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. -* Title X:: Specifying the initial frame's title. -* Icons X:: Choosing what sort of icon to use, under X. -* Misc X:: Other display options. -@end menu - -@node Action Arguments -@appendixsec Action Arguments - - Here is a table of action arguments: - -@table @samp -@item @var{file} -@opindex --file -@itemx --file=@var{file} -@opindex --find-file -@itemx --find-file=@var{file} -@opindex --visit -@itemx --visit=@var{file} -@cindex visiting files, command-line argument -@vindex inhibit-startup-buffer-menu -Visit @var{file} using @code{find-file}. @xref{Visiting}. - -When Emacs starts up, it displays the startup buffer in one window, -and the buffer visiting @var{file} in another window -(@pxref{Windows}). If you supply more than one file argument, the -displayed file is the last one specified on the command line; the -other files are visited but their buffers are not shown. - -If the startup buffer is disabled (@pxref{Entering Emacs}), then -@var{file} is visited in a single window if one file argument was -supplied; with two file arguments, Emacs displays the files in two -different windows; with more than two file argument, Emacs displays -the last file specified in one window, plus a Buffer Menu in a -different window (@pxref{Several Buffers}). To inhibit using the -Buffer Menu for this, change the variable -@code{inhibit-startup-buffer-menu} to @code{t}. - -@item +@var{linenum} @var{file} -@opindex +@var{linenum} -Visit @var{file} using @code{find-file}, then go to line number -@var{linenum} in it. - -@item +@var{linenum}:@var{columnnum} @var{file} -Visit @var{file} using @code{find-file}, then go to line number -@var{linenum} and put point at column number @var{columnnum}. - -@item -l @var{file} -@opindex -l -@itemx --load=@var{file} -@opindex --load -@cindex loading Lisp libraries, command-line argument -Load a Lisp library named @var{file} with the function @code{load}. -If @var{file} is not an absolute file name, Emacs first looks for it -in the current directory, then in the directories listed in -@code{load-path} (@pxref{Lisp Libraries}). - -@strong{Warning:} If previous command-line arguments have visited -files, the current directory is the directory of the last file -visited. - -@item -L @var{dir} -@opindex -L -@itemx --directory=@var{dir} -@opindex --directory -Prepend directory @var{dir} to the variable @code{load-path}. -If you specify multiple @samp{-L} options, Emacs preserves the -relative order; i.e., using @samp{-L /foo -L /bar} results in -a @code{load-path} of the form @code{("/foo" "/bar" @dots{})}. -If @var{dir} begins with @samp{:}, Emacs removes the @samp{:} and -appends (rather than prepends) the remainder to @code{load-path}. -(On MS Windows, use @samp{;} instead of @samp{:}; i.e., use -the value of @code{path-separator}.) - -@item -f @var{function} -@opindex -f -@itemx --funcall=@var{function} -@opindex --funcall -@cindex call Lisp functions, command-line argument -Call Lisp function @var{function}. If it is an interactive function -(a command), it reads the arguments interactively just as if you had -called the same function with a key sequence. Otherwise, it calls the -function with no arguments. - -@item --eval=@var{expression} -@opindex --eval -@itemx --execute=@var{expression} -@opindex --execute -@cindex evaluate expression, command-line argument -Evaluate Lisp expression @var{expression}. - -@item --insert=@var{file} -@opindex --insert -@cindex insert file contents, command-line argument -Insert the contents of @var{file} into the @file{*scratch*} buffer -(@pxref{Lisp Interaction}). This is like what @kbd{M-x insert-file} -does (@pxref{Misc File Ops}). - -@item --kill -@opindex --kill -Exit from Emacs without asking for confirmation. - -@item --help -@opindex --help -Print a usage message listing all available options, then exit -successfully. - -@item --version -@opindex --version -Print Emacs version, then exit successfully. -@end table - -@node Initial Options -@appendixsec Initial Options - - The initial options specify parameters for the Emacs session. This -section describes the more general initial options; some other options -specifically related to the X Window System appear in the following -sections. - - Some initial options affect the loading of the initialization file. -Normally, Emacs first loads @file{site-start.el} if it exists, then -your own initialization file if it exists, and finally the default -initialization file @file{default.el} if it exists (@pxref{Init -File}). Certain options prevent loading of some of these files or -substitute other files for them. - -@table @samp -@item -chdir @var{directory} -@opindex -chdir -@itemx --chdir=@var{directory} -@opindex --chdir -@cindex change Emacs directory -Change to @var{directory} before doing anything else. This is mainly used -by session management in X so that Emacs starts in the same directory as it -stopped. This makes desktop saving and restoring easier. - -@item -t @var{device} -@opindex -t -@itemx --terminal=@var{device} -@opindex --terminal -@cindex device for Emacs terminal I/O -Use @var{device} as the device for terminal input and output. This -option implies @samp{--no-window-system}. - -@item -d @var{display} -@opindex -d -@itemx --display=@var{display} -@opindex --display -@cindex display for Emacs frame -Use the X Window System and use the display named @var{display} to open -the initial Emacs frame. @xref{Display X}, for more details. - -@item -nw -@opindex -nw -@itemx --no-window-system -@opindex --no-window-system -@cindex disable window system -Don't communicate directly with the window system, disregarding the -@env{DISPLAY} environment variable even if it is set. This means that -Emacs uses the terminal from which it was launched for all its display -and input. - -@cindex batch mode -@item -batch -@opindex --batch -@itemx --batch -Run Emacs in @dfn{batch mode}. Batch mode is used for running -programs written in Emacs Lisp from shell scripts, makefiles, and so -on. To invoke a Lisp program, use the @samp{-batch} option in -conjunction with one or more of @samp{-l}, @samp{-f} or @samp{--eval} -(@pxref{Action Arguments}). @xref{Command Example}, for an example. - -In batch mode, Emacs does not display the text being edited, and the -standard terminal interrupt characters such as @kbd{C-z} and @kbd{C-c} -have their usual effect. Emacs functions that normally print a -message in the echo area will print to either the standard output -stream (@code{stdout}) or the standard error stream (@code{stderr}) -instead. (To be precise, functions like @code{prin1}, @code{princ} -and @code{print} print to @code{stdout}, while @code{message} and -@code{error} print to @code{stderr}.) Functions that normally read -keyboard input from the minibuffer take their input from the -terminal's standard input stream (@code{stdin}) instead. - -@samp{--batch} implies @samp{-q} (do not load an initialization file), -but @file{site-start.el} is loaded nonetheless. It also causes Emacs -to exit after processing all the command options. In addition, it -disables auto-saving except in buffers for which auto-saving is -explicitly requested, and when saving files it omits the @code{fsync} -system call unless otherwise requested. - -@item --script @var{file} -@opindex --script -@cindex script mode -Run Emacs in batch mode, like @samp{--batch}, and then read and -execute the Lisp code in @var{file}. - -The normal use of this option is in executable script files that run -Emacs. They can start with this text on the first line - -@example -#!/usr/bin/emacs --script -@end example - -@noindent -which will invoke Emacs with @samp{--script} and supply the name of -the script file as @var{file}. Emacs Lisp then treats the @samp{#!} -on this first line as a comment delimiter. - -@item -q -@opindex -q -@itemx --no-init-file -@opindex --no-init-file -@cindex bypassing init and @file{default.el} file -@cindex init file, not loading -@cindex @file{default.el} file, not loading -Do not load any initialization file (@pxref{Init File}). When Emacs -is invoked with this option, the Customize facility does not allow -options to be saved (@pxref{Easy Customization}). This option does -not disable loading @file{site-start.el}. - -@item --no-site-file -@opindex --no-site-file -@cindex @file{site-start.el} file, not loading -Do not load @file{site-start.el} (@pxref{Init File}). The @samp{-Q} -option does this too, but other options like @samp{-q} do not. - -@item --no-site-lisp -@opindex --no-site-lisp -@cindex @file{site-start.el} file, not loading -Do not include the @file{site-lisp} directories in @code{load-path} -(@pxref{Init File}). The @samp{-Q} option does this too. - -@item --no-splash -@opindex --no-splash -@vindex inhibit-startup-screen -@cindex splash screen -@cindex startup message -Do not display a startup screen. You can also achieve this effect by -setting the variable @code{inhibit-startup-screen} to non-@code{nil} -in your initialization file (@pxref{Entering Emacs}). - -@item -Q -@opindex -Q -@itemx --quick -@opindex --quick -Start emacs with minimum customizations. This is similar to using @samp{-q}, -@samp{--no-site-file}, @samp{--no-site-lisp}, and @samp{--no-splash} -together. This also stops Emacs from processing X resources by -setting @code{inhibit-x-resources} to @code{t} (@pxref{Resources}). - -@item -daemon -@opindex -daemon -@itemx --daemon -@opindex --daemon -Start Emacs as a daemon---after Emacs starts up, it starts the Emacs -server and disconnects from the terminal without opening any frames. -You can then use the @command{emacsclient} command to connect to Emacs -for editing. @xref{Emacs Server}, for information about using Emacs -as a daemon. - -@item -daemon=@var{SERVER-NAME} -Start emacs in background as a daemon, and use @var{SERVER-NAME} as -the server name. - -@item --no-desktop -@opindex --no-desktop -Do not reload any saved desktop. @xref{Saving Emacs Sessions}. - -@item -u @var{user} -@opindex -u -@itemx --user=@var{user} -@opindex --user -@cindex load init file of another user -Load @var{user}'s initialization file instead of your -own@footnote{This option has no effect on MS-Windows.}. - -@item --debug-init -@opindex --debug-init -@cindex errors in init file -Enable the Emacs Lisp debugger for errors in the init file. -@xref{Error Debugging,, Entering the Debugger on an Error, elisp, The -GNU Emacs Lisp Reference Manual}. -@end table - -@node Command Example -@appendixsec Command Argument Example - - Here is an example of using Emacs with arguments and options. It -assumes you have a Lisp program file called @file{hack-c.el} which, when -loaded, performs some useful operation on the current buffer, expected -to be a C program. - -@example -emacs --batch foo.c -l hack-c -f save-buffer >& log -@end example - -@noindent -This says to visit @file{foo.c}, load @file{hack-c.el} (which makes -changes in the visited file), save @file{foo.c} (note that -@code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and -then exit back to the shell (because of @samp{--batch}). @samp{--batch} -also guarantees there will be no problem redirecting output to -@file{log}, because Emacs will not assume that it has a display terminal -to work with. - -@node Environment -@appendixsec Environment Variables -@cindex environment variables - - The @dfn{environment} is a feature of the operating system; it -consists of a collection of variables with names and values. Each -variable is called an @dfn{environment variable}; environment variable -names are case-sensitive, and it is conventional to use upper case -letters only. The values are all text strings. - - What makes the environment useful is that subprocesses inherit the -environment automatically from their parent process. This means you -can set up an environment variable in your login shell, and all the -programs you run (including Emacs) will automatically see it. -Subprocesses of Emacs (such as shells, compilers, and version control -programs) inherit the environment from Emacs, too. - -@findex setenv -@findex getenv -@vindex initial-environment - Inside Emacs, the command @kbd{M-x getenv} reads the name of an -environment variable, and prints its value in the echo area. @kbd{M-x -setenv} sets a variable in the Emacs environment, and @kbd{C-u M-x -setenv} removes a variable. (Environment variable substitutions with -@samp{$} work in the value just as in file names; see @ref{File Names -with $}.) The variable @code{initial-environment} stores the initial -environment inherited by Emacs. - - The way to set environment variables outside of Emacs depends on the -operating system, and especially the shell that you are using. For -example, here's how to set the environment variable @env{ORGANIZATION} -to @samp{not very much} using Bash: - -@example -export ORGANIZATION="not very much" -@end example - -@noindent -and here's how to do it in csh or tcsh: - -@example -setenv ORGANIZATION "not very much" -@end example - - When Emacs is using the X Window System, various environment -variables that control X work for Emacs as well. See the X -documentation for more information. - -@menu -* General Variables:: Environment variables that all versions of Emacs use. -* Misc Variables:: Certain system-specific variables. -* MS-Windows Registry:: An alternative to the environment on MS-Windows. -@end menu - -@node General Variables -@appendixsubsec General Variables - - Here is an alphabetical list of environment variables that have -special meanings in Emacs. Most of these variables are also used by -some other programs. Emacs does not require any of these environment -variables to be set, but it uses their values if they are set. - -@vtable @env -@item CDPATH -Used by the @code{cd} command to search for the directory you specify, -when you specify a relative directory name. -@item DBUS_SESSION_BUS_ADDRESS -Used by D-Bus when Emacs is compiled with it. Usually, there is no -need to change it. Setting it to a dummy address, like -@samp{unix:path=/dev/null}, suppresses connections to the D-Bus session -bus as well as autolaunching the D-Bus session bus if not running yet. -@item EMACSDATA -Directory for the architecture-independent files that come with Emacs. -This is used to initialize the variable @code{data-directory}. -@item EMACSDOC -Directory for the documentation string file, which is used to -initialize the Lisp variable @code{doc-directory}. -@item EMACSLOADPATH -A colon-separated list of directories@footnote{Here and below, -whenever we say ``colon-separated list of directories'', it pertains -to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, the -directories are separated by semi-colons instead, since DOS/Windows -file names might include a colon after a drive letter.} to search for -Emacs Lisp files. If set, it modifies the usual initial value of the -@code{load-path} variable (@pxref{Lisp Libraries}). An empty element -stands for the default value of @code{load-path}; e.g., using -@samp{EMACSLOADPATH="/tmp:"} adds @file{/tmp} to the front of -the default @code{load-path}. To specify an empty element in the -middle of the list, use 2 colons in a row, as in -@samp{EMACSLOADPATH="/tmp::/foo"}. -@item EMACSPATH -A colon-separated list of directories to search for executable files. -If set, Emacs uses this in addition to @env{PATH} (see below) when -initializing the variable @code{exec-path} (@pxref{Shell}). -@item EMAIL -@vindex user-mail-address@r{, initialization} -Your email address; used to initialize the Lisp variable -@code{user-mail-address}, which the Emacs mail interface puts into the -@samp{From} header of outgoing messages (@pxref{Mail Headers}). -@item ESHELL -Used for shell-mode to override the @env{SHELL} environment variable -(@pxref{Interactive Shell}). -@item HISTFILE -The name of the file that shell commands are saved in between logins. -This variable defaults to @file{~/.bash_history} if you use Bash, to -@file{~/.sh_history} if you use ksh, and to @file{~/.history} -otherwise. -@item HOME -The location of your files in the directory tree; used for -expansion of file names starting with a tilde (@file{~}). On MS-DOS, -it defaults to the directory from which Emacs was started, with -@samp{/bin} removed from the end if it was present. On Windows, the -default value of @env{HOME} is the @file{Application Data} -subdirectory of the user profile directory (normally, this is -@file{C:/Documents and Settings/@var{username}/Application Data}, -where @var{username} is your user name), though for backwards -compatibility @file{C:/} will be used instead if a @file{.emacs} file -is found there. -@item HOSTNAME -The name of the machine that Emacs is running on. -@c complete.el is obsolete since 24.1. -@ignore -@item INCPATH -A colon-separated list of directories. Used by the @code{complete} package -to search for files. -@end ignore -@item INFOPATH -A colon-separated list of directories in which to search for Info files. -@item LC_ALL -@itemx LC_COLLATE -@itemx LC_CTYPE -@itemx LC_MESSAGES -@itemx LC_MONETARY -@itemx LC_NUMERIC -@itemx LC_TIME -@itemx LANG -The user's preferred locale. The locale has six categories, specified -by the environment variables @env{LC_COLLATE} for sorting, -@env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system -messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for -numbers, and @env{LC_TIME} for dates and times. If one of these -variables is not set, the category defaults to the value of the -@env{LANG} environment variable, or to the default @samp{C} locale if -@env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides -the settings of all the other locale environment variables. - -On MS-Windows, if @env{LANG} is not already set in the environment -when Emacs starts, Emacs sets it based on the system-wide default -language, which you can set in the @samp{Regional Settings} Control Panel -on some versions of MS-Windows. - -The value of the @env{LC_CTYPE} category is -matched against entries in @code{locale-language-names}, -@code{locale-charset-language-names}, and -@code{locale-preferred-coding-systems}, to select a default language -environment and coding system. @xref{Language Environments}. -@item LOGNAME -The user's login name. See also @env{USER}. -@item MAIL -The name of your system mail inbox. -@ifnottex -@item MH -Name of setup file for the mh system. @xref{Top,,MH-E,mh-e, The Emacs -Interface to MH}. -@end ifnottex -@item NAME -Your real-world name. This is used to initialize the variable -@code{user-full-name} (@pxref{Mail Headers}). -@item NNTPSERVER -The name of the news server. Used by the mh and Gnus packages. -@item ORGANIZATION -The name of the organization to which you belong. Used for setting the -`Organization:' header in your posts from the Gnus package. -@item PATH -A colon-separated list of directories containing executable files. -This is used to initialize the variable @code{exec-path} -(@pxref{Shell}). -@item PWD -If set, this should be the default directory when Emacs was started. -@item REPLYTO -If set, this specifies an initial value for the variable -@code{mail-default-reply-to} (@pxref{Mail Headers}). -@item SAVEDIR -The name of a directory in which news articles are saved by default. -Used by the Gnus package. -@item SHELL -The name of an interpreter used to parse and execute programs run from -inside Emacs. -@item SMTPSERVER -The name of the outgoing mail server. This is used to initialize the -variable @code{smtpmail-smtp-server} (@pxref{Mail Sending}). -@cindex background mode, on @command{xterm} -@item TERM -The type of the terminal that Emacs is using. This variable must be -set unless Emacs is run in batch mode. On MS-DOS, it defaults to -@samp{internal}, which specifies a built-in terminal emulation that -handles the machine's own display. -@item TERMCAP -The name of the termcap library file describing how to program the -terminal specified by @env{TERM}. This defaults to -@file{/etc/termcap}. -@item TMPDIR -@itemx TMP -@itemx TEMP -These environment variables are used to initialize the variable -@code{temporary-file-directory}, which specifies a directory in which -to put temporary files (@pxref{Backup}). Emacs tries to use -@env{TMPDIR} first. If that is unset, Emacs normally falls back on -@file{/tmp}, but on MS-Windows and MS-DOS it instead falls back on -@env{TMP}, then @env{TEMP}, and finally @file{c:/temp}. - -@item TZ -This specifies the current time zone and possibly also daylight -saving time information. On MS-DOS, if @env{TZ} is not set in the -environment when Emacs starts, Emacs defines a default value as -appropriate for the country code returned by DOS@. On MS-Windows, Emacs -does not use @env{TZ} at all. -@item USER -The user's login name. See also @env{LOGNAME}. On MS-DOS, this -defaults to @samp{root}. -@item VERSION_CONTROL -Used to initialize the @code{version-control} variable (@pxref{Backup -Names}). -@end vtable - -@node Misc Variables -@appendixsubsec Miscellaneous Variables - -These variables are used only on particular configurations: - -@vtable @env -@item COMSPEC -On MS-DOS and MS-Windows, the name of the command interpreter to use -when invoking batch files and commands internal to the shell. On MS-DOS -this is also used to make a default value for the @env{SHELL} environment -variable. - -@item NAME -On MS-DOS, this variable defaults to the value of the @env{USER} -variable. - -@item EMACSTEST -On MS-DOS, this specifies a file to use to log the operation of the -internal terminal emulator. This feature is useful for submitting bug -reports. - -@item EMACSCOLORS -On MS-DOS, this specifies the screen colors. It is useful to set them -this way, since otherwise Emacs would display the default colors -momentarily when it starts up. - -The value of this variable should be the two-character encoding of the -foreground (the first character) and the background (the second -character) colors of the default face. Each character should be the -hexadecimal code for the desired color on a standard PC text-mode -display. For example, to get blue text on a light gray background, -specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and -7 is the code of the light gray color. - -The PC display usually supports only eight background colors. However, -Emacs switches the DOS display to a mode where all 16 colors can be used -for the background, so all four bits of the background color are -actually used. - -@item PRELOAD_WINSOCK -On MS-Windows, if you set this variable, Emacs will load and initialize -the network library at startup, instead of waiting until the first -time it is required. - -@item emacs_dir -On MS-Windows, @env{emacs_dir} is a special environment variable, which -indicates the full path of the directory in which Emacs is installed. -If Emacs is installed in the standard directory structure, it -calculates this value automatically. It is not much use setting this -variable yourself unless your installation is non-standard, since -unlike other environment variables, it will be overridden by Emacs at -startup. When setting other environment variables, such as -@env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir} -rather than hard-coding an absolute path. This allows multiple -versions of Emacs to share the same environment variable settings, and -it allows you to move the Emacs installation directory, without -changing any environment or registry settings. -@end vtable - -@node MS-Windows Registry -@appendixsubsec The MS-Windows System Registry -@pindex addpm, MS-Windows installation program -@cindex registry, setting environment variables (MS-Windows) - -On MS-Windows, the installation program @command{addpm.exe} adds -values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA}, -@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the -@file{HKEY_LOCAL_MACHINE} section of the system registry, under -@file{/Software/GNU/Emacs}. It does this because there is no standard -place to set environment variables across different versions of -Windows. Running @command{addpm.exe} is no longer strictly necessary -in recent versions of Emacs, but if you are upgrading from an older -version, running @command{addpm.exe} ensures that you do not have -older registry entries from a previous installation, which may not be -compatible with the latest version of Emacs. - -When Emacs starts, as well as checking the environment, it also checks -the System Registry for those variables and for @env{HOME}, @env{LANG} -and @env{PRELOAD_WINSOCK}. - -To determine the value of those variables, Emacs goes through the -following procedure. First, the environment is checked. If the -variable is not found there, Emacs looks for registry keys by that -name under @file{/Software/GNU/Emacs}; first in the -@file{HKEY_CURRENT_USER} section of the registry, and if not found -there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs -still cannot determine the values, compiled-in defaults are used. - -In addition to the environment variables above, you can also add many -of the settings which on X belong in the @file{.Xdefaults} file -(@pxref{X Resources}) to the @file{/Software/GNU/Emacs} registry key. - -@node Display X -@appendixsec Specifying the Display Name -@cindex display name (X Window System) -@cindex @env{DISPLAY} environment variable - - The environment variable @env{DISPLAY} tells all X clients, -including Emacs, where to display their windows. Its value is set by -default in ordinary circumstances, when you start an X server and run -jobs locally. You can specify the display yourself; one reason to do -this is if you want to log into another system and run Emacs there, -and have the window displayed at your local terminal. - - @env{DISPLAY} has the syntax -@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the -host name of the X Window System server machine, @var{display} is an -arbitrarily-assigned number that distinguishes your server (X -terminal) from other servers on the same machine, and @var{screen} is -a field that allows an X server to control multiple terminal screens. -The period and the @var{screen} field are optional. If included, -@var{screen} is usually zero. - - For example, if your host is named @samp{glasperle} and your server is -the first (or perhaps the only) server listed in the configuration, your -@env{DISPLAY} is @samp{glasperle:0.0}. - - You can specify the display name explicitly when you run Emacs, either -by changing the @env{DISPLAY} variable, or with the option @samp{-d -@var{display}} or @samp{--display=@var{display}}. Here is an example: - -@smallexample -emacs --display=glasperle:0 & -@end smallexample - - You can inhibit the use of the X window system with the @samp{-nw} -option. Then Emacs uses its controlling text terminal for display. -@xref{Initial Options}. - - Sometimes, security arrangements prevent a program on a remote system -from displaying on your local system. In this case, trying to run Emacs -produces messages like this: - -@smallexample -Xlib: connection to "glasperle:0.0" refused by server -@end smallexample - -@noindent -You might be able to overcome this problem by using the @command{xhost} -command on the local system to give permission for access from your -remote machine. - -@node Font X -@appendixsec Font Specification Options -@cindex font name (X Window System) - -You can use the command line option @samp{-fn @var{font}} (or -@samp{--font}, which is an alias for @samp{-fn}) to specify a default -font: - -@table @samp -@item -fn @var{font} -@opindex -fn -@itemx --font=@var{font} -@opindex --font -@cindex specify default font from the command line -Use @var{font} as the default font. -@end table - -When passing a font name to Emacs on the command line, you may need to -``quote'' it, by enclosing it in quotation marks, if it contains -characters that the shell treats specially (e.g., spaces). For -example: - -@smallexample -emacs -fn "DejaVu Sans Mono-12" -@end smallexample - -@xref{Fonts}, for details about font names and other ways to specify -the default font. - -@node Colors X -@appendixsec Window Color Options -@cindex color of window, from command line -@cindex text colors, from command line - - You can use the following command-line options to specify the colors -to use for various parts of the Emacs display. Colors may be -specified using either color names or RGB triplets (@pxref{Colors}). - -@table @samp -@item -fg @var{color} -@opindex -fg -@itemx --foreground-color=@var{color} -@opindex --foreground-color -@cindex foreground color, command-line argument -Specify the foreground color, overriding the color specified by the -@code{default} face (@pxref{Faces}). -@item -bg @var{color} -@opindex -bg -@itemx --background-color=@var{color} -@opindex --background-color -@cindex background color, command-line argument -Specify the background color, overriding the color specified by the -@code{default} face. -@item -bd @var{color} -@opindex -bd -@itemx --border-color=@var{color} -@opindex --border-color -@cindex border color, command-line argument -Specify the color of the border of the X window. This has no effect -if Emacs is compiled with GTK+ support. -@item -cr @var{color} -@opindex -cr -@itemx --cursor-color=@var{color} -@opindex --cursor-color -@cindex cursor color, command-line argument -Specify the color of the Emacs cursor which indicates where point is. -@item -ms @var{color} -@opindex -ms -@itemx --mouse-color=@var{color} -@opindex --mouse-color -@cindex mouse pointer color, command-line argument -Specify the color for the mouse cursor when the mouse is in the Emacs window. -@item -r -@opindex -r -@itemx -rv -@opindex -rv -@itemx --reverse-video -@opindex --reverse-video -@cindex reverse video, command-line argument -Reverse video---swap the foreground and background colors. -@item --color=@var{mode} -@opindex --color -@cindex standard colors on a character terminal -@cindex override character terminal color support -Set the @dfn{color support mode} when Emacs is run on a text terminal. -This option overrides the number of supported colors that the -character terminal advertises in its @code{termcap} or @code{terminfo} -database. The parameter @var{mode} can be one of the following: -@table @samp -@item never -@itemx no -Don't use colors even if the terminal's capabilities specify color -support. -@item default -@itemx auto -Same as when @option{--color} is not used at all: Emacs detects at -startup whether the terminal supports colors, and if it does, turns on -colored display. -@item always -@itemx yes -@itemx ansi8 -Turn on the color support unconditionally, and use color commands -specified by the ANSI escape sequences for the 8 standard colors. -@item @var{num} -Use color mode for @var{num} colors. If @var{num} is -1, turn off -color support (equivalent to @samp{never}); if it is 0, use the -default color support for this terminal (equivalent to @samp{auto}); -otherwise use an appropriate standard mode for @var{num} colors. -Depending on your terminal's capabilities, Emacs might be able to turn -on a color mode for 8, 16, 88, or 256 as the value of @var{num}. If -there is no mode that supports @var{num} colors, Emacs acts as if -@var{num} were 0, i.e., it uses the terminal's default color support -mode. -@end table -If @var{mode} is omitted, it defaults to @var{ansi8}. -@end table - - For example, to use a coral mouse cursor and a slate blue text cursor, -enter: - -@example -emacs -ms coral -cr 'slate blue' & -@end example - - You can reverse the foreground and background colors through the -@samp{-rv} option or with the X resource @samp{reverseVideo}. - - The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on text -terminals as well as on graphical displays. - -@node Window Size X -@appendixsec Options for Window Size and Position -@cindex geometry of Emacs window -@cindex position and size of Emacs frame -@cindex width and height of Emacs frame -@cindex specifying fullscreen for Emacs frame - - Here is a list of the command-line options for specifying size and -position of the initial Emacs frame: - -@table @samp -@item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex -g -@itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex --geometry -@cindex geometry, command-line argument -Specify the size @var{width} and @var{height} (measured in character -columns and lines), and positions @var{xoffset} and @var{yoffset} -(measured in pixels). The @var{width} and @var{height} parameters -apply to all frames, whereas @var{xoffset} and @var{yoffset} only to -the initial frame. - -@item -fs -@opindex -fs -@itemx --fullscreen -@opindex --fullscreen -@cindex fullscreen, command-line argument -Specify that width and height should be that of the screen. Normally -no window manager decorations are shown. (After starting Emacs, -you can toggle this state using @key{F11}, @code{toggle-frame-fullscreen}.) - -@item -mm -@opindex -mm -@itemx --maximized -@opindex --maximized -@cindex maximized, command-line argument -Specify that the Emacs frame should be maximized. This normally -means that the frame has window manager decorations. -(After starting Emacs, you can toggle this state using @kbd{M-F10}, -@code{toggle-frame-maximized}.) - -@item -fh -@opindex -fh -@itemx --fullheight -@opindex --fullheight -@cindex fullheight, command-line argument -Specify that the height should be the height of the screen. - -@item -fw -@opindex -fw -@itemx --fullwidth -@opindex --fullwidth -@cindex fullwidth, command-line argument -Specify that the width should be the width of the screen. -@end table - -@noindent -In the @samp{--geometry} option, @code{@r{@{}+-@r{@}}} means either a plus - sign or a minus sign. A plus -sign before @var{xoffset} means it is the distance from the left side of -the screen; a minus sign means it counts from the right side. A plus -sign before @var{yoffset} means it is the distance from the top of the -screen, and a minus sign there indicates the distance from the bottom. -The values @var{xoffset} and @var{yoffset} may themselves be positive or -negative, but that doesn't change their meaning, only their direction. - - Emacs uses the same units as @command{xterm} does to interpret the geometry. -The @var{width} and @var{height} are measured in characters, so a large font -creates a larger frame than a small font. (If you specify a proportional -font, Emacs uses its maximum bounds width as the width unit.) The -@var{xoffset} and @var{yoffset} are measured in pixels. - - You do not have to specify all of the fields in the geometry -specification. If you omit both @var{xoffset} and @var{yoffset}, the -window manager decides where to put the Emacs frame, possibly by -letting you place it with the mouse. For example, @samp{164x55} -specifies a window 164 columns wide, enough for two ordinary width -windows side by side, and 55 lines tall. - - The default frame width is 80 characters and the default height is -40 lines. You can omit either the width or the height or both. If -you start the geometry with an integer, Emacs interprets it as the -width. If you start with an @samp{x} followed by an integer, Emacs -interprets it as the height. Thus, @samp{81} specifies just the -width; @samp{x45} specifies just the height. - - If you start with @samp{+} or @samp{-}, that introduces an offset, -which means both sizes are omitted. Thus, @samp{-3} specifies the -@var{xoffset} only. (If you give just one offset, it is always -@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the -@var{yoffset}, placing the frame near the bottom left of the screen. - - You can specify a default for any or all of the fields in your X -resource file (@pxref{Resources}), and then override selected fields -with a @samp{--geometry} option. - - Since the mode line and the echo area occupy the last 2 lines of the -frame, the height of the initial text window is 2 less than the height -specified in your geometry. In non-X-toolkit versions of Emacs, the -menu bar also takes one line of the specified number. But in the X -toolkit version, the menu bar is additional and does not count against -the specified height. The tool bar, if present, is also additional. - - Enabling or disabling the menu bar or tool bar alters the amount of -space available for ordinary text. Therefore, if Emacs starts up with -a tool bar (which is the default), and handles the geometry -specification assuming there is a tool bar, and then your -initialization file disables the tool bar, you will end up with a -frame geometry different from what you asked for. To get the intended -size with no tool bar, use an X resource to specify ``no tool bar'' -(@pxref{Table of Resources}); then Emacs will already know there's no -tool bar when it processes the specified geometry. - - When using one of @samp{--fullscreen}, @samp{--maximized}, -@samp{--fullwidth} or @samp{--fullheight}, some window managers require -you to set the variable @code{frame-resize-pixelwise} to a non-@code{nil} -value to make a frame appear truly ``maximized'' or ``fullscreen''. - - Some window managers have options that can make them ignore both -program-specified and user-specified positions. If these are set, -Emacs fails to position the window correctly. - -@node Borders X -@appendixsec Internal and External Borders -@cindex borders (X Window System) - - An Emacs frame has an internal border and an external border. The -internal border is an extra strip of the background color around the -text portion of the frame. Emacs itself draws the internal border. -The external border is added by the window manager outside the frame; -depending on the window manager you use, it may contain various boxes -you can click on to move or iconify the window. - -@table @samp -@item -ib @var{width} -@opindex -ib -@itemx --internal-border=@var{width} -@opindex --internal-border -@cindex internal border width, command-line argument -Specify @var{width} as the width of the internal border (between the text -and the main border), in pixels. - -@item -bw @var{width} -@opindex -bw -@itemx --border-width=@var{width} -@opindex --border-width -@cindex main border width, command-line argument -Specify @var{width} as the width of the main border, in pixels. -@end table - - When you specify the size of the frame, that does not count the -borders. The frame's position is measured from the outside edge of the -external border. - - Use the @samp{-ib @var{n}} option to specify an internal border -@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to -specify the width of the external border (though the window manager may -not pay attention to what you specify). The default width of the -external border is 2. - -@node Title X -@appendixsec Frame Titles - - An Emacs frame may or may not have a specified title. The frame -title, if specified, appears in window decorations and icons as the -name of the frame. If an Emacs frame has no specified title, the -default title has the form @samp{@var{invocation-name}@@@var{machine}} -(if there is only one frame) or the selected window's buffer name (if -there is more than one frame). - - You can specify a title for the initial Emacs frame with a command -line option: - -@table @samp -@item -T @var{title} -@opindex -T -@itemx --title=@var{title} -@opindex --title -@cindex frame title, command-line argument -Specify @var{title} as the title for the initial Emacs frame. -@end table - - The @samp{--name} option (@pxref{Resources}) also specifies the title -for the initial Emacs frame. - -@node Icons X -@appendixsec Icons -@cindex icons (X Window System) -@cindex minimizing a frame at startup - -@table @samp -@item -iconic -@opindex --iconic -@itemx --iconic -@cindex start iconified, command-line argument -Start Emacs in an iconified (``minimized'') state. - -@item -nbi -@opindex -nbi -@itemx --no-bitmap-icon -@opindex --no-bitmap-icon -@cindex Emacs icon, a gnu -Disable the use of the Emacs icon. -@end table - - Most window managers allow you to ``iconify'' (or ``minimize'') an -Emacs frame, hiding it from sight. Some window managers replace -iconified windows with tiny ``icons'', while others remove them -entirely from sight. The @samp{-iconic} option tells Emacs to begin -running in an iconified state, rather than showing a frame right away. -The text frame doesn't appear until you deiconify (or ``un-minimize'') -it. - - By default, Emacs uses an icon containing the Emacs logo. On -desktop environments such as Gnome, this icon is also displayed in -other contexts, e.g., when switching into an Emacs frame. The -@samp{-nbi} or @samp{--no-bitmap-icon} option tells Emacs to let the -window manager choose what sort of icon to use---usually just a small -rectangle containing the frame's title. - -@node Misc X -@appendixsec Other Display Options - -@table @samp -@c @item -hb -@c @opindex -hb -@c @itemx --horizontal-scroll-bars -@c @opindex --horizontal-scroll-bars -@c @c @cindex horizontal scroll bars, command-line argument -@c Enable horizontal scroll bars. Since horizontal scroll bars -@c are not yet implemented, this actually does nothing. - -@item --parent-id @var{id} -Open Emacs as a client X window via the XEmbed protocol, with @var{id} -as the parent X window id. Currently, this option is mainly useful -for developers. - -@item -vb -@opindex -vb -@itemx --vertical-scroll-bars -@opindex --vertical-scroll-bars -@cindex vertical scroll bars, command-line argument -Enable vertical scroll bars. - -@item -lsp @var{pixels} -@opindex -lsp -@itemx --line-spacing=@var{pixels} -@opindex --line-spacing -@cindex line spacing, command-line argument -Specify @var{pixels} as additional space to put between lines, in pixels. - -@item -nbc -@opindex -nbc -@itemx --no-blinking-cursor -@opindex --no-blinking-cursor -@cindex blinking cursor disable, command-line argument -Disable the blinking cursor on graphical displays. - -@item -D -@opindex -D -@itemx --basic-display -@opindex --basic-display -Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips, -and turn off the blinking cursor. This can be useful for making a -test case that simplifies debugging of display problems. -@end table - - The @samp{--xrm} option (@pxref{Resources}) specifies additional -X resource values. diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi deleted file mode 100644 index d9eba2d5a00..00000000000 --- a/doc/emacs/commands.texi +++ /dev/null @@ -1,185 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Characters, Keys and Commands - - This chapter explains the character sets used by Emacs for input -commands, and the fundamental concepts of @dfn{keys} and -@dfn{commands}, whereby Emacs interprets your keyboard and mouse -input. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node User Input -@section Kinds of User Input -@cindex input with the keyboard -@cindex keyboard input -@cindex character set (keyboard) -@cindex @acronym{ASCII} -@cindex C- -@cindex Control - - GNU Emacs is primarily designed for use with the keyboard. While it -is possible to use the mouse to issue editing commands through the -menu bar and tool bar, that is not as efficient as using the keyboard. -Therefore, this manual mainly documents how to edit with the keyboard. - -@cindex control character - Keyboard input into Emacs is based on a heavily-extended version of -@acronym{ASCII}. Simple characters, like @samp{a}, @samp{B}, -@samp{3}, @samp{=}, and the space character (denoted as @key{SPC}), -are entered by typing the corresponding key. @dfn{Control -characters}, such as @key{RET}, @key{TAB}, @key{DEL}, @key{ESC}, -@key{F1}, @key{Home}, and @key{LEFT}, are also entered this way, as -are certain characters found on non-English keyboards -(@pxref{International}). - -@cindex modifier keys -@cindex Control -@cindex C- -@cindex META -@cindex M- - Emacs also recognizes control characters that are entered using -@dfn{modifier keys}. Two commonly-used modifier keys are -@key{Control} (usually labeled @key{Ctrl}), and @key{META} (usually -labeled @key{Alt})@footnote{We refer to @key{Alt} as @key{META} for -historical reasons.}. For example, @kbd{Control-a} is entered by -holding down the @key{Ctrl} key while pressing @kbd{a}; we will refer -to this as @kbd{C-a} for short. Similarly @kbd{@key{META}-a}, or @kbd{M-a} -for short, is entered by holding down the @key{Alt} key and pressing -@kbd{a}. Modifier keys can also be applied to non-alphanumerical -characters, e.g., @kbd{C-@key{F1}} or @kbd{M-@key{LEFT}}. - -@cindex @key{ESC} replacing @key{META} key - You can also type Meta characters using two-character sequences -starting with @key{ESC}. Thus, you can enter @kbd{M-a} by typing -@kbd{@key{ESC} a}. You can enter @kbd{C-M-a} by typing @kbd{@key{ESC} -C-a}. Unlike @key{META}, @key{ESC} is entered as a separate -character. You don't hold down @key{ESC} while typing the next -character; instead, press @key{ESC} and release it, then enter the -next character. This feature is useful on certain text terminals -where the @key{META} key does not function reliably. - -@cindex keys stolen by window manager -@cindex window manager, keys stolen by - On graphical displays, the window manager might block some keyboard -inputs, including @kbd{M-@key{TAB}}, @kbd{M-@key{SPC}}, @kbd{C-M-d} -and @kbd{C-M-l}. If you have this problem, you can either customize -your window manager to not block those keys, or ``rebind'' the -affected Emacs commands (@pxref{Customization}). - -@cindex input event - Simple characters and control characters, as well as certain -non-keyboard inputs such as mouse clicks, are collectively referred to -as @dfn{input events}. For details about how Emacs internally handles -input events, see @ref{Input Events,,, elisp, The Emacs Lisp Reference -Manual}. - -@node Keys -@section Keys - - Some Emacs commands are invoked by just one input event; for -example, @kbd{C-f} moves forward one character in the buffer. Other -commands take two or more input events to invoke, such as @kbd{C-x -C-f} and @kbd{C-x 4 C-f}. - -@cindex key -@cindex key sequence -@cindex complete key -@cindex prefix key - A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one -or more input events that is meaningful as a unit. If a key sequence -invokes a command, we call it a @dfn{complete key}; for example, -@kbd{C-f}, @kbd{C-x C-f} and @kbd{C-x 4 C-f} are all complete keys. -If a key sequence isn't long enough to invoke a command, we call it a -@dfn{prefix key}; from the preceding example, we see that @kbd{C-x} -and @kbd{C-x 4} are prefix keys. Every key sequence is either a -complete key or a prefix key. - - A prefix key combines with the following input event to make a -longer key sequence. For example, @kbd{C-x} is a prefix key, so -typing @kbd{C-x} alone does not invoke a command; instead, Emacs waits -for further input (if you pause for longer than a second, it echoes -the @kbd{C-x} key to prompt for that input; @pxref{Echo Area}). -@kbd{C-x} combines with the next input event to make a two-event key -sequence, which could itself be a prefix key (such as @kbd{C-x 4}), or -a complete key (such as @kbd{C-x C-f}). There is no limit to the -length of key sequences, but in practice they are seldom longer than -three or four input events. - - You can't add input events onto a complete key. For example, -because @kbd{C-f} is a complete key, the two-event sequence @kbd{C-f -C-k} is two key sequences, not one. - - By default, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h}, -@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x -n}, @kbd{C-x r}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x 6}, -@key{ESC}, @kbd{M-g}, and @kbd{M-o}. (@key{F1} and @key{F2} are -aliases for @kbd{C-h} and @kbd{C-x 6}.) This list is not cast in -stone; if you customize Emacs, you can make new prefix keys. You -could even eliminate some of the standard ones, though this is not -recommended for most users; for example, if you remove the prefix -definition of @kbd{C-x 4}, then @kbd{C-x 4 C-f} becomes an invalid key -sequence. @xref{Key Bindings}. - - Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key -displays a list of the commands starting with that prefix. The sole -exception to this rule is @key{ESC}: @kbd{@key{ESC} C-h} is equivalent -to @kbd{C-M-h}, which does something else entirely. You can, however, -use @key{F1} to display a list of commands starting with @key{ESC}. - -@node Commands -@section Keys and Commands - -@cindex binding -@cindex command - This manual is full of passages that tell you what particular keys -do. But Emacs does not assign meanings to keys directly. Instead, -Emacs assigns meanings to named @dfn{commands}, and then gives keys -their meanings by @dfn{binding} them to commands. - - Every command has a name chosen by a programmer. The name is -usually made of a few English words separated by dashes; for example, -@code{next-line} or @code{forward-word}. Internally, each command is -a special type of Lisp @dfn{function}, and the actions associated with -the command are performed by running the function. @xref{What Is a -Function,, What Is a Function, elisp, The Emacs Lisp Reference -Manual}. - - The bindings between keys and commands are recorded in tables called -@dfn{keymaps}. @xref{Keymaps}. - - When we say that ``@kbd{C-n} moves down vertically one line'' we are -glossing over a subtle distinction that is irrelevant in ordinary use, -but vital for Emacs customization. The command @code{next-line} does -a vertical move downward. @kbd{C-n} has this effect @emph{because} it -is bound to @code{next-line}. If you rebind @kbd{C-n} to the command -@code{forward-word}, @kbd{C-n} will move forward one word instead. - - In this manual, we will often speak of keys like @kbd{C-n} as -commands, even though strictly speaking the key is bound to a command. -Usually we state the name of the command which really does the work in -parentheses after mentioning the key that runs it. For example, we -will say that ``The command @kbd{C-n} (@code{next-line}) moves point -vertically down'', meaning that the command @code{next-line} moves -vertically down, and the key @kbd{C-n} is normally bound to it. - - Since we are discussing customization, we should tell you about -@dfn{variables}. Often the description of a command will say, ``To -change this, set the variable @code{mumble-foo}.'' A variable is a -name used to store a value. Most of the variables documented in this -manual are meant for customization: some command or other part of -Emacs examines the variable and behaves differently according to the -value that you set. You can ignore the information about variables -until you are interested in customizing them. Then read the basic -information on variables (@pxref{Variables}) and the information about -specific variables will make sense. - -@ifnottex -@lowersections -@end ifnottex diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi deleted file mode 100644 index 9b78128d323..00000000000 --- a/doc/emacs/custom.texi +++ /dev/null @@ -1,2548 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Customization -@chapter Customization -@cindex customization - - This chapter describes some simple methods to customize the behavior -of Emacs. - - Apart from the methods described here, see @ref{X Resources} for -information about using X resources to customize Emacs, and see -@ref{Keyboard Macros} for information about recording and replaying -keyboard macros. Making more far-reaching and open-ended changes -involves writing Emacs Lisp code; see -@iftex -@cite{The Emacs Lisp Reference Manual}. -@end iftex -@ifnottex -@ref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp -Reference Manual}. -@end ifnottex - -@menu -* Easy Customization:: Convenient way to browse and change settings. -* Variables:: Many Emacs commands examine Emacs variables - to decide what to do; by setting variables, - you can control their functioning. -* Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine keys". -* Init File:: How to write common customizations in the - initialization file. -@end menu - -@node Easy Customization -@section Easy Customization Interface - -@cindex settings -@cindex user option -@cindex customizable variable - Emacs has many @dfn{settings} which you can change. Most settings -are @dfn{customizable variables} (@pxref{Variables}), which are also -called @dfn{user options}. There is a huge number of customizable -variables, controlling numerous aspects of Emacs behavior; the -variables documented in this manual are listed in @ref{Variable -Index}. A separate class of settings are the @dfn{faces}, which -determine the fonts, colors, and other attributes of text -(@pxref{Faces}). - -@findex customize -@cindex customization buffer - To browse and alter settings (both variables and faces), type -@kbd{M-x customize}. This creates a @dfn{customization buffer}, which -lets you navigate through a logically organized list of settings, edit -and set their values, and save them permanently. - -@menu -* Customization Groups:: How settings are classified. -* Browsing Custom:: Browsing and searching for settings. -* Changing a Variable:: How to edit an option's value and set the option. -* Saving Customizations:: Saving customizations for future Emacs sessions. -* Face Customization:: How to edit the attributes of a face. -* Specific Customization:: Customizing specific settings or groups. -* Custom Themes:: Collections of customization settings. -* Creating Custom Themes:: How to create a new custom theme. -@end menu - -@node Customization Groups -@subsection Customization Groups -@cindex customization groups - - Customization settings are organized into @dfn{customization -groups}. These groups are collected into bigger groups, all the way -up to a master group called @code{Emacs}. - - @kbd{M-x customize} creates a customization buffer that shows the -top-level @code{Emacs} group. It looks like this, in part: - -@c we want the buffer example to all be on one page, but unfortunately -@c that's quite a bit of text, so force all space to the bottom. -@c @page -@smallexample -@group -To apply changes, use the Save or Set buttons. -For details, see [Saving Customizations] in the [Emacs manual]. - -________________________________________ [ Search ] - - Operate on all settings in this buffer: - [ Set for current session ] [ Save for future sessions ] - [ Undo edits ] [ Reset to saved ] [ Erase customizations ] [ Exit ] - - -Emacs group: Customization of the One True Editor. - [State]: visible group members are all at standard values. - See also [Manual]. - -[Editing] : Basic text editing facilities. - -[Convenience] : Convenience features for faster editing. - -@var{more second-level groups} -@end group -@end smallexample - -@noindent -The main part of this buffer shows the @samp{Emacs} customization -group, which contains several other groups (@samp{Editing}, -@samp{Convenience}, etc.). The contents of those groups are not -listed here, only one line of documentation each. - - The @dfn{state} of the group indicates whether setting in that group -has been edited, set or saved. @xref{Changing a Variable}. - -@cindex editable fields (customization buffer) -@cindex buttons (customization buffer) -@cindex links (customization buffer) - Most of the customization buffer is read-only, but it includes some -@dfn{editable fields} that you can edit. For example, at the top of -the customization buffer is an editable field for searching for -settings (@pxref{Browsing Custom}). There are also @dfn{buttons} and -@dfn{links}, which you can activate by either clicking with the mouse, -or moving point there and typing @key{RET}. For example, the group -names like @samp{[Editing]} are links; activating one of these links -brings up the customization buffer for that group. - -@kindex TAB @r{(customization buffer)} -@kindex S-TAB @r{(customization buffer)} -@findex widget-forward -@findex widget-backward - In the customizable buffer, you can type @key{TAB} -(@code{widget-forward}) to move forward to the next button or editable -field. @kbd{S-@key{TAB}} (@code{widget-backward}) moves back to the -previous button or editable field. - -@node Browsing Custom -@subsection Browsing and Searching for Settings -@findex customize-browse - - From the top-level customization buffer created by @kbd{M-x -customize}, you can follow the links to the subgroups of the -@samp{Emacs} customization group. These subgroups may contain -settings for you to customize; they may also contain further subgroups, -dealing with yet more specialized subsystems of Emacs. As you -navigate the hierarchy of customization groups, you should find some -settings that you want to customize. - - If you are interested in customizing a particular setting or -customization group, you can go straight there with the commands -@kbd{M-x customize-option}, @kbd{M-x customize-face}, or @kbd{M-x -customize-group}. @xref{Specific Customization}. - -@vindex custom-search-field - If you don't know exactly what groups or settings you want to -customize, you can search for them using the editable search field at -the top of each customization buffer. Here, you can type in a search -term---either one or more words separated by spaces, or a regular -expression (@pxref{Regexps}). Then type @key{RET} in the field, or -activate the @samp{Search} button next to it, to switch to a -customization buffer containing groups and settings that match those -terms. Note, however, that this feature only finds groups and -settings that are loaded in the current Emacs session. - - If you don't want customization buffers to show the search field, -change the variable @code{custom-search-field} to @code{nil}. - - The command @kbd{M-x customize-apropos} is similar to using the -search field, except that it reads the search term(s) using the -minibuffer. @xref{Specific Customization}. - - @kbd{M-x customize-browse} is another way to browse the available -settings. This command creates a special customization buffer which -shows only the names of groups and settings, in a structured layout. -You can show the contents of a group, in the same buffer, by invoking -the @samp{[+]} button next to the group name. When the group contents -are shown, the button changes to @samp{[-]}; invoking that hides the -group contents again. Each group or setting in this buffer has a link -which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking -this link creates an ordinary customization buffer showing just that -group, option, or face; this is the way to change settings that you -find with @kbd{M-x customize-browse}. - -@node Changing a Variable -@subsection Changing a Variable - - Here is an example of what a variable, or user option, looks like in -the customization buffer: - -@smallexample -[Hide] Kill Ring Max: 60 - [State]: STANDARD. - Maximum length of kill ring before oldest elements are thrown away. -@end smallexample - - The first line shows that the variable is named -@code{kill-ring-max}, formatted as @samp{Kill Ring Max} for easier -viewing. Its value is @samp{60}. The button labeled @samp{[Hide]}, -if activated, hides the variable's value and state; this is useful to -avoid cluttering up the customization buffer with very long values -(for this reason, variables that have very long values may start out -hidden). If you use the @samp{[Hide]} button, it changes to -@samp{[Show Value]}, which you can activate to reveal the value and -state. On a graphical display, the @samp{[Hide]} and @samp{[Show -Value]} buttons are replaced with graphical triangles pointing -downwards and rightwards respectively. - - The line after the variable name indicates the @dfn{customization -state} of the variable: in this example, @samp{STANDARD} means you -have not changed the variable, so its value is the default one. The -@samp{[State]} button gives a menu of operations for customizing the -variable. - - Below the customization state is the documentation for the variable. -This is the same documentation that would be shown by the @kbd{C-h v} -command (@pxref{Examining}). If the documentation is more than one -line long, only one line may be shown. If so, that line ends with a -@samp{[More]} button; activate this to see the full documentation. - -@cindex user options, changing -@cindex customizing variables -@cindex variables, changing - To enter a new value for @samp{Kill Ring Max}, just move point to -the value and edit it. For example, type @kbd{M-d} to delete the -@samp{60} and type in another number. As you begin to alter the text, -the @samp{[State]} line will change: - -@smallexample -[State]: EDITED, shown value does not take effect until you - set or save it. -@end smallexample - -@noindent -Editing the value does not make it take effect right away. To do -that, you must @dfn{set} the variable by activating the @samp{[State]} -button and choosing @samp{Set for Current Session}. Then the -variable's state becomes: - -@smallexample -[State]: SET for current session only. -@end smallexample - -@noindent -You don't have to worry about specifying a value that is not valid; -the @samp{Set for Current Session} operation checks for validity and -will not install an unacceptable value. - -@kindex M-TAB @r{(customization buffer)} -@kindex C-M-i @r{(customization buffer)} -@findex widget-complete - While editing certain kinds of values, such as file names, directory -names, and Emacs command names, you can perform completion with -@kbd{C-M-i} (@code{widget-complete}), or the equivalent keys -@kbd{M-@key{TAB}} or @kbd{@key{ESC} @key{TAB}}. This behaves much -like minibuffer completion (@pxref{Completion}). - - Typing @key{RET} on an editable value field moves point forward to -the next field or button, like @key{TAB}. You can thus type @key{RET} -when you are finished editing a field, to move on to the next button -or field. To insert a newline within an editable field, use @kbd{C-o} -or @kbd{C-q C-j}. - - For some variables, there is only a fixed set of legitimate values, -and you are not allowed to edit the value directly. Instead, a -@samp{[Value Menu]} button appears before the value; activating this -button presents a choice of values. For a boolean ``on or off'' -value, the button says @samp{[Toggle]}, and flips the value. After -using the @samp{[Value Menu]} or @samp{[Toggle]} button, you must -again set the variable to make the chosen value take effect. - - Some variables have values with complex structure. For example, the -value of @code{minibuffer-frame-alist} is an association list. Here -is how it appears in the customization buffer: - -@smallexample -[Hide] Minibuffer Frame Alist: -[INS] [DEL] Parameter: width - Value: 80 -[INS] [DEL] Parameter: height - Value: 2 -[INS] - [ State ]: STANDARD. - Alist of parameters for the initial minibuffer frame. [Hide] - @r{[@dots{}more lines of documentation@dots{}]} -@end smallexample - -@noindent -In this case, each association in the list consists of two items, one -labeled @samp{Parameter} and one labeled @samp{Value}; both are -editable fields. You can delete an association from the list with the -@samp{[DEL]} button next to it. To add an association, use the -@samp{[INS]} button at the position where you want to insert it; the -very last @samp{[INS]} button inserts at the end of the list. - -@cindex saving a setting -@cindex settings, how to save - When you set a variable, the new value takes effect only in the -current Emacs session. To @dfn{save} the value for future sessions, -use the @samp{[State]} button and select the @samp{Save for Future -Sessions} operation. @xref{Saving Customizations}. - - You can also restore the variable to its standard value by using the -@samp{[State]} button and selecting the @samp{Erase Customization} -operation. There are actually four reset operations: - -@table @samp -@item Undo Edits -If you have modified but not yet set the variable, this restores the -text in the customization buffer to match the actual value. - -@item Reset to Saved -This restores the value of the variable to the last saved value, -and updates the text accordingly. - -@item Erase Customization -This sets the variable to its standard value. Any saved value that -you have is also eliminated. - -@item Set to Backup Value -This sets the variable to a previous value that was set in the -customization buffer in this session. If you customize a variable -and then reset it, which discards the customized value, -you can get the discarded value back again with this operation. -@end table - -@cindex comments on customized settings - Sometimes it is useful to record a comment about a specific -customization. Use the @samp{Add Comment} item from the -@samp{[State]} menu to create a field for entering the comment. - - Near the top of the customization buffer are two lines of buttons: - -@smallexample - [Set for Current Session] [Save for Future Sessions] - [Undo Edits] [Reset to Saved] [Erase Customization] [Exit] -@end smallexample - -@noindent -Each of the first five buttons performs the stated operation---set, -save, reset, etc.---on all the settings in the buffer that could -meaningfully be affected. They do not operate on settings that are -hidden, nor on subgroups that are hidden or not visible in the buffer. - -@kindex C-c C-c @r{(customization buffer)} -@kindex C-x C-c @r{(customization buffer)} -@findex Custom-set -@findex Custom-save - The command @kbd{C-c C-c} (@code{Custom-set}) is equivalent to using -the @samp{[Set for Current Session]} button. The command @kbd{C-x -C-s} (@code{Custom-save}) is like using the @samp{[Save for Future -Sessions]} button. - -@vindex custom-buffer-done-kill - The @samp{[Exit]} button switches out of the customization buffer, -and buries the buffer at the bottom of the buffer list. To make it -kill the customization buffer instead, change the variable -@code{custom-buffer-done-kill} to @code{t}. - -@node Saving Customizations -@subsection Saving Customizations - - In the customization buffer, you can @dfn{save} a customization -setting by choosing the @samp{Save for Future Sessions} choice from -its @samp{[State]} button. The @kbd{C-x C-s} (@code{Custom-save}) -command, or the @samp{[Save for Future Sessions]} button at the top of -the customization buffer, saves all applicable settings in the buffer. - - Saving works by writing code to a file, usually your initialization -file (@pxref{Init File}). Future Emacs sessions automatically read -this file at startup, which sets up the customizations again. - -@vindex custom-file - You can choose to save customizations somewhere other than your -initialization file. To make this work, you must add a couple of -lines of code to your initialization file, to set the variable -@code{custom-file} to the name of the desired file, and to load that -file. For example: - -@example -(setq custom-file "~/.emacs-custom.el") -(load custom-file) -@end example - - You can even specify different customization files for different -Emacs versions, like this: - -@example -(cond ((< emacs-major-version 22) - ;; @r{Emacs 21 customization.} - (setq custom-file "~/.custom-21.el")) - ((and (= emacs-major-version 22) - (< emacs-minor-version 3)) - ;; @r{Emacs 22 customization, before version 22.3.} - (setq custom-file "~/.custom-22.el")) - (t - ;; @r{Emacs version 22.3 or later.} - (setq custom-file "~/.emacs-custom.el"))) - -(load custom-file) -@end example - - If Emacs was invoked with the @option{-q} or @option{--no-init-file} -options (@pxref{Initial Options}), it will not let you save your -customizations in your initialization file. This is because saving -customizations from such a session would wipe out all the other -customizations you might have on your initialization file. - -@node Face Customization -@subsection Customizing Faces -@cindex customizing faces -@cindex faces, customizing -@cindex fonts and faces - - You can customize faces (@pxref{Faces}), which determine how Emacs -displays different types of text. Customization groups can contain -both variables and faces. - - For example, in programming language modes, source code comments are -shown with @code{font-lock-comment-face} (@pxref{Font Lock}). In a -customization buffer, that face appears like this: - -@smallexample -[Hide] Font Lock Comment Face:[sample] - [State] : STANDARD. - Font Lock mode face used to highlight comments. - [ ] Font Family: -- - [ ] Font Foundry: -- - [ ] Width: -- - [ ] Height: -- - [ ] Weight: -- - [ ] Slant: -- - [ ] Underline: -- - [ ] Overline: -- - [ ] Strike-through: -- - [ ] Box around text: -- - [ ] Inverse-video: -- - [X] Foreground: Firebrick [Choose] (sample) - [ ] Background: -- - [ ] Stipple: -- - [ ] Inherit: -- - [Hide Unused Attributes] -@end smallexample - -@noindent -The first three lines show the name, @samp{[State]} button, and -documentation for the face. Below that is a list of @dfn{face -attributes}. In front of each attribute is a checkbox. A filled -checkbox, @samp{[X]}, means that the face specifies a value for this -attribute; an empty checkbox, @samp{[ ]}, means that the face does not -specify any special value for the attribute. You can activate a -checkbox to specify or unspecify its attribute. - - A face does not have to specify every single attribute; in fact, -most faces only specify a few attributes. In the above example, -@code{font-lock-comment-face} only specifies the foreground color. -Any unspecified attribute is taken from the special face named -@code{default}, whose attributes are all specified. The -@code{default} face is the face used to display any text that does not -have an explicitly-assigned face; furthermore, its background color -attribute serves as the background color of the frame. - - The @samp{Hide Unused Attributes} button, at the end of the -attribute list, hides the unspecified attributes of the face. When -attributes are being hidden, the button changes to @samp{[Show All -Attributes]}, which reveals the entire attribute list. The -customization buffer may start out with unspecified attributes hidden, -to avoid cluttering the interface. - - When an attribute is specified, you can change its value in the -usual ways. - - Foreground and background colors can be specified using either color -names or RGB triplets (@pxref{Colors}). You can also use the -@samp{[Choose]} button to switch to a list of color names; select a -color with @key{RET} in that buffer to put the color name in the value -field. - - Setting, saving and resetting a face work like the same operations for -variables (@pxref{Changing a Variable}). - - A face can specify different appearances for different types of -displays. For example, a face can make text red on a color display, -but use a bold font on a monochrome display. To specify multiple -appearances for a face, select @samp{For All Kinds of Displays} in the -menu you get from invoking @samp{[State]}. - -@node Specific Customization -@subsection Customizing Specific Items - -@table @kbd -@item M-x customize-option @key{RET} @var{option} @key{RET} -@itemx M-x customize-variable @key{RET} @var{option} @key{RET} -Set up a customization buffer for just one user option, @var{option}. -@item M-x customize-face @key{RET} @var{face} @key{RET} -Set up a customization buffer for just one face, @var{face}. -@item M-x customize-group @key{RET} @var{group} @key{RET} -Set up a customization buffer for just one group, @var{group}. -@item M-x customize-apropos @key{RET} @var{regexp} @key{RET} -Set up a customization buffer for all the settings and groups that -match @var{regexp}. -@item M-x customize-changed @key{RET} @var{version} @key{RET} -Set up a customization buffer with all the settings and groups -whose meaning has changed since Emacs version @var{version}. -@item M-x customize-saved -Set up a customization buffer containing all settings that you -have saved with customization buffers. -@item M-x customize-unsaved -Set up a customization buffer containing all settings that you have -set but not saved. -@end table - -@findex customize-option - If you want to customize a particular user option, type @kbd{M-x -customize-option}. This reads the variable name, and sets up the -customization buffer with just that one user option. When entering -the variable name into the minibuffer, completion is available, but -only for the names of variables that have been loaded into Emacs. - -@findex customize-face -@findex customize-group - Likewise, you can customize a specific face using @kbd{M-x -customize-face}. You can set up a customization buffer for a specific -customization group using @kbd{M-x customize-group}. - -@findex customize-apropos - @kbd{M-x customize-apropos} prompts for a search term---either one -or more words separated by spaces, or a regular expression---and sets -up a customization buffer for all @emph{loaded} settings and groups -with matching names. This is like using the search field at the top -of the customization buffer (@pxref{Customization Groups}). - -@findex customize-changed - When you upgrade to a new Emacs version, you might want to consider -customizing new settings, and settings whose meanings or default -values have changed. To do this, use @kbd{M-x customize-changed} and -specify a previous Emacs version number using the minibuffer. It -creates a customization buffer which shows all the settings and groups -whose definitions have been changed since the specified version, -loading them if necessary. - -@findex customize-saved -@findex customize-unsaved - If you change settings and then decide the change was a mistake, you -can use two commands to revisit your changes. Use @kbd{M-x -customize-saved} to customize settings that you have saved. Use -@kbd{M-x customize-unsaved} to customize settings that you have set -but not saved. - -@node Custom Themes -@subsection Custom Themes -@cindex custom themes - - @dfn{Custom themes} are collections of settings that can be enabled -or disabled as a unit. You can use Custom themes to switch easily -between various collections of settings, and to transfer such -collections from one computer to another. - - A Custom theme is stored as an Emacs Lisp source file. If the name of -the Custom theme is @var{name}, the theme file is named -@file{@var{name}-theme.el}. @xref{Creating Custom Themes}, for the -format of a theme file and how to make one. - -@findex customize-themes -@vindex custom-theme-directory -@cindex color scheme - Type @kbd{M-x customize-themes} to switch to a buffer named -@file{*Custom Themes*}, which lists the Custom themes that Emacs knows -about. By default, Emacs looks for theme files in two locations: the -directory specified by the variable @code{custom-theme-directory} -(which defaults to @file{~/.emacs.d/}), and a directory named -@file{etc/themes} in your Emacs installation (see the variable -@code{data-directory}). The latter contains several Custom themes -which are distributed with Emacs, which customize Emacs's faces to fit -various color schemes. (Note, however, that Custom themes need not be -restricted to this purpose; they can be used to customize variables -too.) - -@vindex custom-theme-load-path - If you want Emacs to look for Custom themes in some other directory, -add the directory name to the list variable -@code{custom-theme-load-path}. Its default value is -@code{(custom-theme-directory t)}; here, the symbol -@code{custom-theme-directory} has the special meaning of the value of -the variable @code{custom-theme-directory}, while @code{t} stands for -the built-in theme directory @file{etc/themes}. The themes listed in -the @file{*Custom Themes*} buffer are those found in the directories -specified by @code{custom-theme-load-path}. - -@kindex C-x C-s @r{(Custom Themes buffer)} - In the @file{*Custom Themes*} buffer, you can activate the checkbox -next to a Custom theme to enable or disable the theme for the current -Emacs session. When a Custom theme is enabled, all of its settings -(variables and faces) take effect in the Emacs session. To apply the -choice of theme(s) to future Emacs sessions, type @kbd{C-x C-s} -(@code{custom-theme-save}) or use the @samp{[Save Theme Settings]} -button. - -@vindex custom-safe-themes - When you first enable a Custom theme, Emacs displays the contents of -the theme file and asks if you really want to load it. Because -loading a Custom theme can execute arbitrary Lisp code, you should -only say yes if you know that the theme is safe; in that case, Emacs -offers to remember in the future that the theme is safe (this is done -by saving the theme file's SHA-256 hash to the variable -@code{custom-safe-themes}; if you want to treat all themes as safe, -change its value to @code{t}). Themes that come with Emacs (in the -@file{etc/themes} directory) are exempt from this check, and are -always considered safe. - -@vindex custom-enabled-themes - Setting or saving Custom themes actually works by customizing the -variable @code{custom-enabled-themes}. The value of this variable is -a list of Custom theme names (as Lisp symbols, e.g., @code{tango}). -Instead of using the @file{*Custom Themes*} buffer to set -@code{custom-enabled-themes}, you can customize the variable using the -usual customization interface, e.g., with @kbd{M-x customize-option}. -Note that Custom themes are not allowed to set -@code{custom-enabled-themes} themselves. - - Any customizations that you make through the customization buffer -take precedence over theme settings. This lets you easily override -individual theme settings that you disagree with. If settings from -two different themes overlap, the theme occurring earlier in -@code{custom-enabled-themes} takes precedence. In the customization -buffer, if a setting has been changed from its default by a Custom -theme, its @samp{State} display shows @samp{THEMED} instead of -@samp{STANDARD}. - -@findex load-theme -@findex enable-theme -@findex disable-theme - You can enable a specific Custom theme in the current Emacs session -by typing @kbd{M-x load-theme}. This prompts for a theme name, loads -the theme from the theme file, and enables it. If a theme file -has been loaded before, you can enable the theme without loading its -file by typing @kbd{M-x enable-theme}. To disable a Custom theme, -type @kbd{M-x disable-theme}. - -@findex describe-theme - To see a description of a Custom theme, type @kbd{?} on its line in -the @file{*Custom Themes*} buffer; or type @kbd{M-x describe-theme} -anywhere in Emacs and enter the theme name. - -@node Creating Custom Themes -@subsection Creating Custom Themes -@cindex custom themes, creating - -@findex customize-create-theme - You can define a Custom theme using an interface similar to the -customization buffer, by typing @kbd{M-x customize-create-theme}. -This switches to a buffer named @file{*Custom Theme*}. It also offers -to insert some common Emacs faces into the theme (a convenience, since -Custom themes are often used to customize faces). If you answer no, -the theme will initially contain no settings. - - Near the top of the @file{*Custom Theme*} buffer are editable fields -where you can enter the theme's name and description. The name can be -anything except @samp{user}. The description is the one that will be -shown when you invoke @kbd{M-x describe-theme} for the theme. Its -first line should be a brief one-sentence summary; in the buffer made -by @kbd{M-x customize-themes}, this sentence is displayed next to the -theme name. - - To add a new setting to the theme, use the @samp{[Insert Additional -Face]} or @samp{[Insert Additional Variable]} buttons. Each button -reads a face or variable name using the minibuffer, with completion, -and inserts a customization entry for the face or variable. You can -edit the variable values or face attributes in the same way as in a -normal customization buffer. To remove a face or variable from the -theme, uncheck the checkbox next to its name. - -@vindex custom-theme-directory - After specifying the Custom theme's faces and variables, type -@kbd{C-x C-s} (@code{custom-theme-write}) or use the buffer's -@samp{[Save Theme]} button. This saves the theme file, named -@file{@var{name}-theme.el} where @var{name} is the theme name, in the -directory named by @code{custom-theme-directory}. - - From the @file{*Custom Theme*} buffer, you can view and edit an -existing Custom theme by activating the @samp{[Visit Theme]} button -and specifying the theme name. You can also add the settings of -another theme into the buffer, using the @samp{[Merge Theme]} button. -You can import your non-theme settings into a Custom theme by using -the @samp{[Merge Theme]} button and specifying the special theme named -@samp{user}. - - A theme file is simply an Emacs Lisp source file, and loading the -Custom theme works by loading the Lisp file. Therefore, you can edit -a theme file directly instead of using the @file{*Custom Theme*} -buffer. @xref{Custom Themes,,, elisp, The Emacs Lisp Reference -Manual}, for details. - -@node Variables -@section Variables -@cindex variable - - A @dfn{variable} is a Lisp symbol which has a value. The symbol's -name is also called the @dfn{variable name}. A variable name can -contain any characters that can appear in a file, but most variable -names consist of ordinary words separated by hyphens. - - The name of the variable serves as a compact description of its -role. Most variables also have a @dfn{documentation string}, which -describes what the variable's purpose is, what kind of value it should -have, and how the value will be used. You can view this documentation -using the help command @kbd{C-h v} (@code{describe-variable}). -@xref{Examining}. - - Emacs uses many Lisp variables for internal record keeping, but the -most interesting variables for a non-programmer user are those meant -for users to change---these are called @dfn{customizable variables} or -@dfn{user options} (@pxref{Easy Customization}). In the following -sections, we will describe other aspects of Emacs variables, such as -how to set them outside Customize. - - Emacs Lisp allows any variable (with a few exceptions) to have any -kind of value. However, many variables are meaningful only if -assigned values of a certain type. For example, only numbers are -meaningful values for @code{kill-ring-max}, which specifies the -maximum length of the kill ring (@pxref{Earlier Kills}); if you give -@code{kill-ring-max} a string value, commands such as @kbd{C-y} -(@code{yank}) will signal an error. On the other hand, some variables -don't care about type; for instance, if a variable has one effect for -@code{nil} values and another effect for ``non-@code{nil}'' values, -then any value that is not the symbol @code{nil} induces the second -effect, regardless of its type (by convention, we usually use the -value @code{t}---a symbol which stands for ``true''---to specify a -non-@code{nil} value). If you set a variable using the customization -buffer, you need not worry about giving it an invalid type: the -customization buffer usually only allows you to enter meaningful -values. When in doubt, use @kbd{C-h v} (@code{describe-variable}) to -check the variable's documentation string to see kind of value it -expects (@pxref{Examining}). - -@menu -* Examining:: Examining or setting one variable's value. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. -* Directory Variables:: How variable values can be specified by directory. -@end menu - -@node Examining -@subsection Examining and Setting Variables -@cindex setting variables - -@table @kbd -@item C-h v @var{var} @key{RET} -Display the value and documentation of variable @var{var} -(@code{describe-variable}). -@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} -Change the value of variable @var{var} to @var{value}. -@end table - - To examine the value of a variable, use @kbd{C-h v} -(@code{describe-variable}). This reads a variable name using the -minibuffer, with completion, and displays both the value and the -documentation of the variable. For example, - -@example -C-h v fill-column @key{RET} -@end example - -@noindent -displays something like this: - -@example -fill-column is a variable defined in `C source code'. -fill-column's value is 70 - -Automatically becomes buffer-local when set. -This variable is safe as a file local variable if its value -satisfies the predicate `integerp'. - -Documentation: -Column beyond which automatic line-wrapping should happen. -Interactively, you can set the local value with C-x f. - -You can customize this variable. -@end example - -@noindent -The line that says ``You can customize the variable'' indicates that -this variable is a user option. @kbd{C-h v} is not restricted to user -options; it allows non-customizable variables too. - -@findex set-variable - The most convenient way to set a specific customizable variable is -with @kbd{M-x set-variable}. This reads the variable name with the -minibuffer (with completion), and then reads a Lisp expression for the -new value using the minibuffer a second time (you can insert the old -value into the minibuffer for editing via @kbd{M-n}). For example, - -@example -M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} -@end example - -@noindent -sets @code{fill-column} to 75. - - @kbd{M-x set-variable} is limited to customizable variables, but you -can set any variable with a Lisp expression like this: - -@example -(setq fill-column 75) -@end example - -@noindent -To execute such an expression, type @kbd{M-:} (@code{eval-expression}) -and enter the expression in the minibuffer (@pxref{Lisp Eval}). -Alternatively, go to the @file{*scratch*} buffer, type in the -expression, and then type @kbd{C-j} (@pxref{Lisp Interaction}). - - Setting variables, like all means of customizing Emacs except where -otherwise stated, affects only the current Emacs session. The only -way to alter the variable in future sessions is to put something in -your initialization file (@pxref{Init File}). - -@node Hooks -@subsection Hooks -@cindex hook -@cindex running a hook - - @dfn{Hooks} are an important mechanism for customizing Emacs. A -hook is a Lisp variable which holds a list of functions, to be called -on some well-defined occasion. (This is called @dfn{running the -hook}.) The individual functions in the list are called the @dfn{hook -functions} of the hook. For example, the hook @code{kill-emacs-hook} -runs just before exiting Emacs (@pxref{Exiting}). - -@cindex normal hook - Most hooks are @dfn{normal hooks}. This means that when Emacs runs -the hook, it calls each hook function in turn, with no arguments. We -have made an effort to keep most hooks normal, so that you can use -them in a uniform way. Every variable whose name ends in @samp{-hook} -is a normal hook. - -@cindex abnormal hook - A few hooks are @dfn{abnormal hooks}. Their names end in -@samp{-functions}, instead of @samp{-hook} (some old code may also use -the deprecated suffix @samp{-hooks}). What -makes these hooks abnormal is the way its functions are -called---perhaps they are given arguments, or perhaps the values they -return are used in some way. For example, -@code{find-file-not-found-functions} is abnormal because as soon as -one hook function returns a non-@code{nil} value, the rest are not -called at all (@pxref{Visiting}). The documentation of each abnormal -hook variable explains how its functions are used. - -@findex add-hook - You can set a hook variable with @code{setq} like any other Lisp -variable, but the recommended way to add a function to a hook (either -normal or abnormal) is to use @code{add-hook}, as shown by the -following examples. @xref{Hooks,,, elisp, The Emacs Lisp Reference -Manual}, for details. - - Most major modes run one or more @dfn{mode hooks} as the last step -of initialization. Mode hooks are a convenient way to customize the -behavior of individual modes; they are always normal. For example, -here's how to set up a hook to turn on Auto Fill mode in Text mode and -other modes based on Text mode: - -@example -(add-hook 'text-mode-hook 'auto-fill-mode) -@end example - -@noindent -This works by calling @code{auto-fill-mode}, which enables the minor -mode when no argument is supplied (@pxref{Minor Modes}). Next, -suppose you don't want Auto Fill mode turned on in @LaTeX{} mode, -which is one of the modes based on Text mode. You can do this with -the following additional line: - -@example -(add-hook 'latex-mode-hook (lambda () (auto-fill-mode -1))) -@end example - -@noindent -Here we have used the special macro @code{lambda} to construct an -anonymous function (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp -Reference Manual}), which calls @code{auto-fill-mode} with an argument -of @code{-1} to disable the minor mode. Because @LaTeX{} mode runs -@code{latex-mode-hook} after running @code{text-mode-hook}, the result -leaves Auto Fill mode disabled. - - Here is a more complex example, showing how to use a hook to -customize the indentation of C code: - -@example -@group -(setq my-c-style - '((c-comment-only-line-offset . 4) -@end group -@group - (c-cleanup-list . (scope-operator - empty-defun-braces - defun-close-semi)))) -@end group - -@group -(add-hook 'c-mode-common-hook - (lambda () (c-add-style "my-style" my-c-style t))) -@end group -@end example - -@cindex Prog mode -@cindex program editing - Major mode hooks also apply to other major modes @dfn{derived} from -the original mode (@pxref{Derived Modes,,, elisp, The Emacs Lisp -Reference Manual}). For instance, HTML mode is derived from Text mode -(@pxref{HTML Mode}); when HTML mode is enabled, it runs -@code{text-mode-hook} before running @code{html-mode-hook}. This -provides a convenient way to use a single hook to affect several -related modes. In particular, if you want to apply a hook function to -any programming language mode, add it to @code{prog-mode-hook}; Prog -mode is a major mode that does little else than to let other major -modes inherit from it, exactly for this purpose. - - It is best to design your hook functions so that the order in which -they are executed does not matter. Any dependence on the order is -asking for trouble. However, the order is predictable: the hook -functions are executed in the order they appear in the hook. - -@findex remove-hook - If you play with adding various different versions of a hook -function by calling @code{add-hook} over and over, remember that all -the versions you added will remain in the hook variable together. You -can clear out individual functions by calling @code{remove-hook}, or -do @code{(setq @var{hook-variable} nil)} to remove everything. - -@cindex buffer-local hooks - If the hook variable is buffer-local, the buffer-local variable will -be used instead of the global variable. However, if the buffer-local -variable contains the element @code{t}, the global hook variable will -be run as well. - -@node Locals -@subsection Local Variables - -@table @kbd -@item M-x make-local-variable @key{RET} @var{var} @key{RET} -Make variable @var{var} have a local value in the current buffer. -@item M-x kill-local-variable @key{RET} @var{var} @key{RET} -Make variable @var{var} use its global value in the current buffer. -@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET} -Mark variable @var{var} so that setting it will make it local to the -buffer that is current at that time. -@end table - -@cindex local variables - Almost any variable can be made @dfn{local} to a specific Emacs -buffer. This means that its value in that buffer is independent of its -value in other buffers. A few variables are always local in every -buffer. Every other Emacs variable has a @dfn{global} value which is in -effect in all buffers that have not made the variable local. - -@findex make-local-variable - @kbd{M-x make-local-variable} reads the name of a variable and makes -it local to the current buffer. Changing its value subsequently in -this buffer will not affect others, and changes in its global value -will not affect this buffer. - -@findex make-variable-buffer-local -@cindex per-buffer variables - @kbd{M-x make-variable-buffer-local} marks a variable so it will -become local automatically whenever it is set. More precisely, once a -variable has been marked in this way, the usual ways of setting the -variable automatically do @code{make-local-variable} first. We call -such variables @dfn{per-buffer} variables. Many variables in Emacs -are normally per-buffer; the variable's document string tells you when -this is so. A per-buffer variable's global value is normally never -effective in any buffer, but it still has a meaning: it is the initial -value of the variable for each new buffer. - - Major modes (@pxref{Major Modes}) always make variables local to the -buffer before setting the variables. This is why changing major modes -in one buffer has no effect on other buffers. Minor modes also work -by setting variables---normally, each minor mode has one controlling -variable which is non-@code{nil} when the mode is enabled -(@pxref{Minor Modes}). For many minor modes, the controlling variable -is per buffer, and thus always buffer-local. Otherwise, you can make -it local in a specific buffer like any other variable. - - A few variables cannot be local to a buffer because they are always -local to each display instead (@pxref{Multiple Displays}). If you try to -make one of these variables buffer-local, you'll get an error message. - -@findex kill-local-variable - @kbd{M-x kill-local-variable} makes a specified variable cease to be -local to the current buffer. The global value of the variable -henceforth is in effect in this buffer. Setting the major mode kills -all the local variables of the buffer except for a few variables -specially marked as @dfn{permanent locals}. - -@findex setq-default - To set the global value of a variable, regardless of whether the -variable has a local value in the current buffer, you can use the Lisp -construct @code{setq-default}. This construct is used just like -@code{setq}, but it sets variables' global values instead of their local -values (if any). When the current buffer does have a local value, the -new global value may not be visible until you switch to another buffer. -Here is an example: - -@example -(setq-default fill-column 75) -@end example - -@noindent -@code{setq-default} is the only way to set the global value of a variable -that has been marked with @code{make-variable-buffer-local}. - -@findex default-value - Lisp programs can use @code{default-value} to look at a variable's -default value. This function takes a symbol as argument and returns its -default value. The argument is evaluated; usually you must quote it -explicitly. For example, here's how to obtain the default value of -@code{fill-column}: - -@example -(default-value 'fill-column) -@end example - -@node File Variables -@subsection Local Variables in Files -@cindex local variables in files -@cindex file local variables - - A file can specify local variable values to use when editing the -file with Emacs. Visiting the file checks for local variable -specifications; it automatically makes these variables local to the -buffer, and sets them to the values specified in the file. - -@menu -* Specifying File Variables:: Specifying file local variables. -* Safe File Variables:: Making sure file local variables are safe. -@end menu - -@node Specifying File Variables -@subsubsection Specifying File Variables - - There are two ways to specify file local variable values: in the first -line, or with a local variables list. Here's how to specify them in the -first line: - -@example --*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- -@end example - -@noindent -You can specify any number of variable/value pairs in this way, each -pair with a colon and semicolon. The special variable/value pair -@code{mode: @var{modename};}, if present, specifies a major mode. The -@var{value}s are used literally, and not evaluated. - -@findex add-file-local-variable-prop-line -@findex delete-file-local-variable-prop-line -@findex copy-dir-locals-to-file-locals-prop-line - You can use @kbd{M-x add-file-local-variable-prop-line} instead of -adding entries by hand. This command prompts for a variable and -value, and adds them to the first line in the appropriate way. -@kbd{M-x delete-file-local-variable-prop-line} prompts for a variable, -and deletes its entry from the line. The command @kbd{M-x -copy-dir-locals-to-file-locals-prop-line} copies the current -directory-local variables to the first line (@pxref{Directory -Variables}). - - Here is an example first line that specifies Lisp mode and sets two -variables with numeric values: - -@smallexample -;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*- -@end smallexample - -@noindent -Aside from @code{mode}, other keywords that have special meanings as -file variables are @code{coding}, @code{unibyte}, and @code{eval}. -These are described below. - -@cindex shell scripts, and local file variables -@cindex man pages, and local file variables - In shell scripts, the first line is used to identify the script -interpreter, so you cannot put any local variables there. To -accommodate this, Emacs looks for local variable specifications in the -@emph{second} line if the first line specifies an interpreter. The -same is true for man pages which start with the magic string -@samp{'\"} to specify a list of troff preprocessors (not all do, -however). - - Apart from using a @samp{-*-} line, you can define file local -variables using a @dfn{local variables list} near the end of the file. -The start of the local variables list should be no more than 3000 -characters from the end of the file, and must be on the last page if -the file is divided into pages. - - If a file has both a local variables list and a @samp{-*-} line, -Emacs processes @emph{everything} in the @samp{-*-} line first, and -@emph{everything} in the local variables list afterward. The exception -to this is a major mode specification. Emacs applies this first, -wherever it appears, since most major modes kill all local variables as -part of their initialization. - - A local variables list starts with a line containing the string -@samp{Local Variables:}, and ends with a line containing the string -@samp{End:}. In between come the variable names and values, one set -per line, like this: - -@example -/* Local Variables: */ -/* mode: c */ -/* comment-column: 0 */ -/* End: */ -@end example - -@noindent -In this example, each line starts with the prefix @samp{/*} and ends -with the suffix @samp{*/}. Emacs recognizes the prefix and suffix by -finding them surrounding the magic string @samp{Local Variables:}, on -the first line of the list; it then automatically discards them from -the other lines of the list. The usual reason for using a prefix -and/or suffix is to embed the local variables list in a comment, so it -won't confuse other programs that the file is intended for. The -example above is for the C programming language, where comments start -with @samp{/*} and end with @samp{*/}. - -@findex add-file-local-variable -@findex delete-file-local-variable -@findex copy-dir-locals-to-file-locals - Instead of typing in the local variables list directly, you can use -the command @kbd{M-x add-file-local-variable}. This prompts for a -variable and value, and adds them to the list, adding the @samp{Local -Variables:} string and start and end markers as necessary. The -command @kbd{M-x delete-file-local-variable} deletes a variable from -the list. @kbd{M-x copy-dir-locals-to-file-locals} copies -directory-local variables to the list (@pxref{Directory Variables}). - - As with the @samp{-*-} line, the variables in a local variables list -are used literally, and are not evaluated first. If you want to split -a long string value across multiple lines of the file, you can use -backslash-newline, which is ignored in Lisp string constants; you -should put the prefix and suffix on each line, even lines that start -or end within the string, as they will be stripped off when processing -the list. Here is an example: - -@example -# Local Variables: -# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ -# -Dmumble=blaah" -# End: -@end example - - Some ``variable names'' have special meanings in a local variables -list: - -@itemize -@item -@code{mode} enables the specified major mode. - -@item -@code{eval} evaluates the specified Lisp expression (the value -returned by that expression is ignored). - -@item -@code{coding} specifies the coding system for character code -conversion of this file. @xref{Coding Systems}. - -@item -@code{unibyte} says to load or compile a file of Emacs Lisp in unibyte -mode, if the value is @code{t}. @xref{Disabling Multibyte, , -Disabling Multibyte Characters, elisp, GNU Emacs Lisp Reference -Manual}. - -@end itemize - -@noindent -These four keywords are not really variables; setting them in any -other context has no special meaning. - - Do not use the @code{mode} keyword for minor modes. To enable or -disable a minor mode in a local variables list, use the @code{eval} -keyword with a Lisp expression that runs the mode command -(@pxref{Minor Modes}). For example, the following local variables -list enables Eldoc mode (@pxref{Lisp Doc}) by calling -@code{eldoc-mode} with no argument (calling it with an argument of 1 -would do the same), and disables Font Lock mode (@pxref{Font Lock}) by -calling @code{font-lock-mode} with an argument of -1. - -@example -;; Local Variables: -;; eval: (eldoc-mode) -;; eval: (font-lock-mode -1) -;; End: -@end example - -@noindent -Note, however, that it is often a mistake to specify minor modes this -way. Minor modes represent individual user preferences, and it may be -inappropriate to impose your preferences on another user who might -edit the file. If you wish to automatically enable or disable a minor -mode in a situation-dependent way, it is often better to do it in a -major mode hook (@pxref{Hooks}). - - Use the command @kbd{M-x normal-mode} to reset the local variables -and major mode of a buffer according to the file name and contents, -including the local variables list if any. @xref{Choosing Modes}. - -@node Safe File Variables -@subsubsection Safety of File Variables - - File-local variables can be dangerous; when you visit someone else's -file, there's no telling what its local variables list could do to -your Emacs. Improper values of the @code{eval} ``variable'', and -other variables such as @code{load-path}, could execute Lisp code you -didn't intend to run. - - Therefore, whenever Emacs encounters file local variable values that -are not known to be safe, it displays the file's entire local -variables list, and asks you for confirmation before setting them. -You can type @kbd{y} or @key{SPC} to put the local variables list into -effect, or @kbd{n} to ignore it. When Emacs is run in batch mode -(@pxref{Initial Options}), it can't really ask you, so it assumes the -answer @kbd{n}. - - Emacs normally recognizes certain variable/value pairs as safe. -For instance, it is safe to give @code{comment-column} or -@code{fill-column} any integer value. If a file specifies only -known-safe variable/value pairs, Emacs does not ask for confirmation -before setting them. Otherwise, you can tell Emacs to record all the -variable/value pairs in this file as safe, by typing @kbd{!} at the -confirmation prompt. When Emacs encounters these variable/value pairs -subsequently, in the same file or others, it will assume they are -safe. - -@vindex safe-local-variable-values -@cindex risky variable - Some variables, such as @code{load-path}, are considered -particularly @dfn{risky}: there is seldom any reason to specify them -as local variables, and changing them can be dangerous. If a file -contains only risky local variables, Emacs neither offers nor accepts -@kbd{!} as input at the confirmation prompt. If some of the local -variables in a file are risky, and some are only potentially unsafe, you -can enter @kbd{!} at the prompt. It applies all the variables, but only -marks the non-risky ones as safe for the future. If you really want to -record safe values for risky variables, do it directly by customizing -@samp{safe-local-variable-values} (@pxref{Easy Customization}). - -@vindex enable-local-variables - The variable @code{enable-local-variables} allows you to change the -way Emacs processes local variables. Its default value is @code{t}, -which specifies the behavior described above. If it is @code{nil}, -Emacs simply ignores all file local variables. @code{:safe} means use -only the safe values and ignore the rest. Any other value says to -query you about each file that has local variables, without trying to -determine whether the values are known to be safe. - -@vindex enable-local-eval -@vindex safe-local-eval-forms - The variable @code{enable-local-eval} controls whether Emacs -processes @code{eval} variables. The three possibilities for the -variable's value are @code{t}, @code{nil}, and anything else, just as -for @code{enable-local-variables}. The default is @code{maybe}, which -is neither @code{t} nor @code{nil}, so normally Emacs does ask for -confirmation about processing @code{eval} variables. - - As an exception, Emacs never asks for confirmation to evaluate any -@code{eval} form if that form occurs within the variable -@code{safe-local-eval-forms}. - -@node Directory Variables -@subsection Per-Directory Local Variables -@cindex local variables, for all files in a directory -@cindex directory-local variables -@cindex per-directory local variables - - Sometimes, you may wish to define the same set of local variables to -all the files in a certain directory and its subdirectories, such as -the directory tree of a large software project. This can be -accomplished with @dfn{directory-local variables}. - -@cindex @file{.dir-locals.el} file - The usual way to define directory-local variables is to put a file -named @file{.dir-locals.el}@footnote{ On MS-DOS, the name of this file -should be @file{_dir-locals.el}, due to limitations of the DOS -filesystems. If the filesystem is limited to 8+3 file names, the name -of the file will be truncated by the OS to @file{_dir-loc.el}. } in a -directory. Whenever Emacs visits any file in that directory or any of -its subdirectories, it will apply the directory-local variables -specified in @file{.dir-locals.el}, as though they had been defined as -file-local variables for that file (@pxref{File Variables}). Emacs -searches for @file{.dir-locals.el} starting in the directory of the -visited file, and moving up the directory tree. To avoid slowdown, -this search is skipped for remote files. If needed, the search can be -extended for remote files by setting the variable -@code{enable-remote-dir-locals} to @code{t}. - - The @file{.dir-locals.el} file should hold a specially-constructed -list, which maps major mode names (symbols) to alists -(@pxref{Association Lists,,, elisp, The Emacs Lisp Reference Manual}). -Each alist entry consists of a variable name and the directory-local -value to assign to that variable, when the specified major mode is -enabled. Instead of a mode name, you can specify @samp{nil}, which -means that the alist applies to any mode; or you can specify a -subdirectory name (a string), in which case the alist applies to all -files in that subdirectory. - - Here's an example of a @file{.dir-locals.el} file: - -@example -((nil . ((indent-tabs-mode . t) - (fill-column . 80))) - (c-mode . ((c-file-style . "BSD") - (subdirs . nil))) - ("src/imported" - . ((nil . ((change-log-default-name - . "ChangeLog.local")))))) -@end example - -@noindent -This sets @samp{indent-tabs-mode} and @code{fill-column} for any file -in the directory tree, and the indentation style for any C source -file. The special @code{subdirs} element is not a variable, but a -special keyword which indicates that the C mode settings are only to -be applied in the current directory, not in any subdirectories. -Finally, it specifies a different @file{ChangeLog} file name for any -file in the @file{src/imported} subdirectory. - -@findex add-dir-local-variable -@findex delete-dir-local-variable -@findex copy-file-locals-to-dir-locals - Instead of editing the @file{.dir-locals.el} file by hand, you can -use the command @kbd{M-x add-dir-local-variable}. This prompts for a -mode or subdirectory name, and for variable and value, and adds the -entry defining the directory-local variable. @kbd{M-x -delete-dir-local-variable} deletes an entry. @kbd{M-x -copy-file-locals-to-dir-locals} copies the file-local variables in the -current file into @file{.dir-locals.el}. - -@findex dir-locals-set-class-variables -@findex dir-locals-set-directory-class - Another method of specifying directory-local variables is to define -a group of variables/value pairs in a @dfn{directory class}, using the -@code{dir-locals-set-class-variables} function; then, tell Emacs which -directories correspond to the class by using the -@code{dir-locals-set-directory-class} function. These function calls -normally go in your initialization file (@pxref{Init File}). This -method is useful when you can't put @file{.dir-locals.el} in a -directory for some reason. For example, you could apply settings to -an unwritable directory this way: - -@example -(dir-locals-set-class-variables 'unwritable-directory - '((nil . ((some-useful-setting . value))))) - -(dir-locals-set-directory-class - "/usr/include/" 'unwritable-directory) -@end example - - If a variable has both a directory-local and file-local value -specified, the file-local value takes effect. Unsafe directory-local -variables are handled in the same way as unsafe file-local variables -(@pxref{Safe File Variables}). - - Directory-local variables also take effect in certain buffers that -do not visit a file directly but perform work within a directory, such -as Dired buffers (@pxref{Dired}). - -@node Key Bindings -@section Customizing Key Bindings -@cindex key bindings - - This section describes @dfn{key bindings}, which map keys to -commands, and @dfn{keymaps}, which record key bindings. It also -explains how to customize key bindings, which is done by editing your -init file (@pxref{Init Rebinding}). - -@menu -* Keymaps:: Generalities. The global keymap. -* Prefix Keymaps:: Keymaps for prefix keys. -* Local Keymaps:: Major and minor modes have their own keymaps. -* Minibuffer Maps:: The minibuffer uses its own local keymaps. -* Rebinding:: How to redefine one key's meaning conveniently. -* Init Rebinding:: Rebinding keys with your initialization file. -* Modifier Keys:: Using modifier keys in key bindings. -* Function Keys:: Rebinding terminal function keys. -* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. -* Mouse Buttons:: Rebinding mouse buttons in Emacs. -* Disabling:: Disabling a command means confirmation is required - before it can be executed. This is done to protect - beginners from surprises. -@end menu - -@node Keymaps -@subsection Keymaps -@cindex keymap - - As described in @ref{Commands}, each Emacs command is a Lisp -function whose definition provides for interactive use. Like every -Lisp function, a command has a function name, which usually consists -of lower-case letters and hyphens. - - A @dfn{key sequence} (@dfn{key}, for short) is a sequence of -@dfn{input events} that have a meaning as a unit. Input events -include characters, function keys and mouse buttons---all the inputs -that you can send to the computer. A key sequence gets its meaning -from its @dfn{binding}, which says what command it runs. - - The bindings between key sequences and command functions are -recorded in data structures called @dfn{keymaps}. Emacs has many of -these, each used on particular occasions. - -@cindex global keymap - The @dfn{global} keymap is the most important keymap because it is -always in effect. The global keymap defines keys for Fundamental mode -(@pxref{Major Modes}); most of these definitions are common to most or -all major modes. Each major or minor mode can have its own keymap -which overrides the global definitions of some keys. - - For example, a self-inserting character such as @kbd{g} is -self-inserting because the global keymap binds it to the command -@code{self-insert-command}. The standard Emacs editing characters -such as @kbd{C-a} also get their standard meanings from the global -keymap. Commands to rebind keys, such as @kbd{M-x global-set-key}, -work by storing the new binding in the proper place in the global map -(@pxref{Rebinding}). - -@cindex function key - Most modern keyboards have function keys as well as character keys. -Function keys send input events just as character keys do, and keymaps -can have bindings for them. Key sequences can mix function keys and -characters. For example, if your keyboard has a @key{Home} function -key, Emacs can recognize key sequences like @kbd{C-x @key{Home}}. You -can even mix mouse events with keyboard events, such as -@kbd{S-down-mouse-1}. - - On text terminals, typing a function key actually sends the computer -a sequence of characters; the precise details of the sequence depends -on the function key and on the terminal type. (Often the sequence -starts with @kbd{@key{ESC} [}.) If Emacs understands your terminal -type properly, it automatically handles such sequences as single input -events. - -@node Prefix Keymaps -@subsection Prefix Keymaps - - Internally, Emacs records only single events in each keymap. -Interpreting a key sequence of multiple events involves a chain of -keymaps: the first keymap gives a definition for the first event, -which is another keymap, which is used to look up the second event in -the sequence, and so on. Thus, a prefix key such as @kbd{C-x} or -@key{ESC} has its own keymap, which holds the definition for the event -that immediately follows that prefix. - - The definition of a prefix key is usually the keymap to use for -looking up the following event. The definition can also be a Lisp -symbol whose function definition is the following keymap; the effect is -the same, but it provides a command name for the prefix key that can be -used as a description of what the prefix key is for. Thus, the binding -of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function -definition is the keymap for @kbd{C-x} commands. The definitions of -@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in -the global map, so these prefix keys are always available. - - Aside from ordinary prefix keys, there is a fictitious ``prefix key'' -which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp -Reference Manual}, for special information about menu bar key bindings. -Mouse button events that invoke pop-up menus are also prefix keys; see -@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more -details. - - Some prefix keymaps are stored in variables with names: - -@itemize @bullet -@item -@vindex ctl-x-map -@code{ctl-x-map} is the variable name for the map used for characters that -follow @kbd{C-x}. -@item -@vindex help-map -@code{help-map} is for characters that follow @kbd{C-h}. -@item -@vindex esc-map -@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta -characters are actually defined by this map. -@item -@vindex ctl-x-4-map -@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. -@item -@vindex mode-specific-map -@code{mode-specific-map} is for characters that follow @kbd{C-c}. -@end itemize - -@node Local Keymaps -@subsection Local Keymaps - -@cindex local keymap -@cindex minor mode keymap - So far, we have explained the ins and outs of the global map. Major -modes customize Emacs by providing their own key bindings in -@dfn{local keymaps}. For example, C mode overrides @key{TAB} to make -it indent the current line for C code. Minor modes can also have -local keymaps; whenever a minor mode is in effect, the definitions in -its keymap override both the major mode's local keymap and the global -keymap. In addition, portions of text in the buffer can specify their -own keymaps, which override all other keymaps. - - A local keymap can redefine a key as a prefix key by defining it as -a prefix keymap. If the key is also defined globally as a prefix, its -local and global definitions (both keymaps) effectively combine: both -definitions are used to look up the event that follows the prefix key. -For example, if a local keymap defines @kbd{C-c} as a prefix keymap, -and that keymap defines @kbd{C-z} as a command, this provides a local -meaning for @kbd{C-c C-z}. This does not affect other sequences that -start with @kbd{C-c}; if those sequences don't have their own local -bindings, their global bindings remain in effect. - - Another way to think of this is that Emacs handles a multi-event key -sequence by looking in several keymaps, one by one, for a binding of the -whole key sequence. First it checks the minor mode keymaps for minor -modes that are enabled, then it checks the major mode's keymap, and then -it checks the global keymap. This is not precisely how key lookup -works, but it's good enough for understanding the results in ordinary -circumstances. - -@node Minibuffer Maps -@subsection Minibuffer Keymaps - -@cindex minibuffer keymaps -@vindex minibuffer-local-map -@vindex minibuffer-local-ns-map -@vindex minibuffer-local-completion-map -@vindex minibuffer-local-must-match-map -@vindex minibuffer-local-filename-completion-map -@vindex minibuffer-local-filename-must-match-map - The minibuffer has its own set of local keymaps; they contain various -completion and exit commands. - -@itemize @bullet -@item -@code{minibuffer-local-map} is used for ordinary input (no completion). -@item -@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits -just like @key{RET}. -@item -@code{minibuffer-local-completion-map} is for permissive completion. -@item -@code{minibuffer-local-must-match-map} is for strict completion and -for cautious completion. -@item -@code{minibuffer-local-filename-completion-map} and -@code{minibuffer-local-filename-must-match-map} are like the two -previous ones, but they are specifically for file name completion. -They do not bind @key{SPC}. -@end itemize - -@node Rebinding -@subsection Changing Key Bindings Interactively -@cindex key rebinding, this session -@cindex redefining keys, this session -@cindex binding keys - - The way to redefine an Emacs key is to change its entry in a keymap. -You can change the global keymap, in which case the change is -effective in all major modes (except those that have their own -overriding local bindings for the same key). Or you can change a -local keymap, which affects all buffers using the same major mode. - - In this section, we describe how to rebind keys for the present -Emacs session. @xref{Init Rebinding}, for a description of how to -make key rebindings affect future Emacs sessions. - -@findex global-set-key -@findex local-set-key -@findex global-unset-key -@findex local-unset-key -@table @kbd -@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} -Define @var{key} globally to run @var{cmd}. -@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} -Define @var{key} locally (in the major mode now in effect) to run -@var{cmd}. -@item M-x global-unset-key @key{RET} @var{key} -Make @var{key} undefined in the global map. -@item M-x local-unset-key @key{RET} @var{key} -Make @var{key} undefined locally (in the major mode now in effect). -@end table - - For example, the following binds @kbd{C-z} to the @code{shell} -command (@pxref{Interactive Shell}), replacing the normal global -definition of @kbd{C-z}: - -@example -M-x global-set-key @key{RET} C-z shell @key{RET} -@end example - -@noindent -The @code{global-set-key} command reads the command name after the -key. After you press the key, a message like this appears so that you -can confirm that you are binding the key you want: - -@example -Set key C-z to command: -@end example - - You can redefine function keys and mouse events in the same way; just -type the function key or click the mouse when it's time to specify the -key to rebind. - - You can rebind a key that contains more than one event in the same -way. Emacs keeps reading the key to rebind until it is a complete key -(that is, not a prefix key). Thus, if you type @kbd{C-f} for -@var{key}, that's the end; it enters the minibuffer immediately to -read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it -reads another character; if that is @kbd{4}, another prefix character, -it reads one more character, and so on. For example, - -@example -M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} -@end example - -@noindent -redefines @kbd{C-x 4 $} to run the (fictitious) command -@code{spell-other-window}. - - You can remove the global definition of a key with -@code{global-unset-key}. This makes the key @dfn{undefined}; if you -type it, Emacs will just beep. Similarly, @code{local-unset-key} makes -a key undefined in the current major mode keymap, which makes the global -definition (or lack of one) come back into effect in that major mode. - - If you have redefined (or undefined) a key and you subsequently wish -to retract the change, undefining the key will not do the job---you need -to redefine the key with its standard definition. To find the name of -the standard definition of a key, go to a Fundamental mode buffer in a -fresh Emacs and use @kbd{C-h c}. The documentation of keys in this -manual also lists their command names. - - If you want to prevent yourself from invoking a command by mistake, it -is better to disable the command than to undefine the key. A disabled -command is less work to invoke when you really want to. -@xref{Disabling}. - -@node Init Rebinding -@subsection Rebinding Keys in Your Init File -@cindex rebinding major mode keys -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. (TUTORIAL.de) - - If you have a set of key bindings that you like to use all the time, -you can specify them in your initialization file by writing Lisp code. -@xref{Init File}, for a description of the initialization file. - -@findex kbd - There are several ways to write a key binding using Lisp. The -simplest is to use the @code{kbd} function, which converts a textual -representation of a key sequence---similar to how we have written key -sequences in this manual---into a form that can be passed as an -argument to @code{global-set-key}. For example, here's how to bind -@kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}): - -@example -(global-set-key (kbd "C-z") 'shell) -@end example - -@noindent -The single-quote before the command name, @code{shell}, marks it as a -constant symbol rather than a variable. If you omit the quote, Emacs -would try to evaluate @code{shell} as a variable. This probably -causes an error; it certainly isn't what you want. - - Here are some additional examples, including binding function keys -and mouse events: - -@example -(global-set-key (kbd "C-c y") 'clipboard-yank) -(global-set-key (kbd "C-M-q") 'query-replace) -(global-set-key (kbd "") 'flyspell-mode) -(global-set-key (kbd "C-") 'linum-mode) -(global-set-key (kbd "C-") 'forward-sentence) -(global-set-key (kbd "") 'mouse-save-then-kill) -@end example - - Instead of using @code{kbd}, you can use a Lisp string or vector to -specify the key sequence. Using a string is simpler, but only works -for @acronym{ASCII} characters and Meta-modified @acronym{ASCII} -characters. For example, here's how to bind @kbd{C-x M-l} to -@code{make-symbolic-link} (@pxref{Misc File Ops}): - -@example -(global-set-key "\C-x\M-l" 'make-symbolic-link) -@end example - - To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the string, -use the Emacs Lisp escape sequences @samp{\t}, @samp{\r}, @samp{\e}, -and @samp{\d} respectively. Here is an example which binds @kbd{C-x -@key{TAB}} to @code{indent-rigidly} (@pxref{Indentation}): - -@example -(global-set-key "\C-x\t" 'indent-rigidly) -@end example - - When the key sequence includes function keys or mouse button events, -or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, -you can use a vector to specify the key sequence. Each element in the -vector stands for an input event; the elements are separated by spaces -and surrounded by a pair of square brackets. If a vector element is a -character, write it as a Lisp character constant: @samp{?} followed by -the character as it would appear in a string. Function keys are -represented by symbols (@pxref{Function Keys}); simply write the -symbol's name, with no other delimiters or punctuation. Here are some -examples: - -@example -(global-set-key [?\C-=] 'make-symbolic-link) -(global-set-key [?\M-\C-=] 'make-symbolic-link) -(global-set-key [?\H-a] 'make-symbolic-link) -(global-set-key [f7] 'make-symbolic-link) -(global-set-key [C-mouse-1] 'make-symbolic-link) -@end example - -@noindent -You can use a vector for the simple cases too: - -@example -(global-set-key [?\C-z ?\M-l] 'make-symbolic-link) -@end example - - Language and coding systems may cause problems with key bindings for -non-@acronym{ASCII} characters. @xref{Init Non-ASCII}. - - As described in @ref{Local Keymaps}, major modes and minor modes can -define local keymaps. These keymaps are constructed when the mode is -used for the first time in a session. If you wish to change one of -these keymaps, you must use the @dfn{mode hook} (@pxref{Hooks}). - -@findex define-key - For example, Texinfo mode runs the hook @code{texinfo-mode-hook}. -Here's how you can use the hook to add local bindings for @kbd{C-c n} -and @kbd{C-c p} in Texinfo mode: - -@example -(add-hook 'texinfo-mode-hook - (lambda () - (define-key texinfo-mode-map "\C-cp" - 'backward-paragraph) - (define-key texinfo-mode-map "\C-cn" - 'forward-paragraph))) -@end example - -@node Modifier Keys -@subsection Modifier Keys -@cindex modifier keys - - The default key bindings in Emacs are set up so that modified -alphabetical characters are case-insensitive. In other words, -@kbd{C-A} does the same thing as @kbd{C-a}, and @kbd{M-A} does the -same thing as @kbd{M-a}. This concerns only alphabetical characters, -and does not apply to ``shifted'' versions of other keys; for -instance, @kbd{C-@@} is not the same as @kbd{C-2}. - - A @key{Control}-modified alphabetical character is always considered -case-insensitive: Emacs always treats @kbd{C-A} as @kbd{C-a}, -@kbd{C-B} as @kbd{C-b}, and so forth. The reason for this is -historical. - - For all other modifiers, you can make the modified alphabetical -characters case-sensitive when you customize Emacs. For instance, you -could make @kbd{M-a} and @kbd{M-A} run different commands. - - Although only the @key{Control} and @key{META} modifier keys are -commonly used, Emacs supports three other modifier keys. These are -called @key{Super}, @key{Hyper} and @key{Alt}. Few terminals provide -ways to use these modifiers; the key labeled @key{Alt} on most -keyboards usually issues the @key{META} modifier, not @key{Alt}. The -standard key bindings in Emacs do not include any characters with -these modifiers. However, you can customize Emacs to assign meanings -to them. The modifier bits are labeled as @samp{s-}, @samp{H-} and -@samp{A-} respectively. - - Even if your keyboard lacks these additional modifier keys, you can -enter it using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to -the next character, @kbd{C-x @@ s} adds the ``super'' flag, and -@kbd{C-x @@ a} adds the ``alt'' flag. For instance, @kbd{C-x @@ h -C-a} is a way to enter @kbd{Hyper-Control-a}. (Unfortunately, there -is no way to add two modifiers by using @kbd{C-x @@} twice for the -same character, because the first one goes to work on the @kbd{C-x}.) - -@node Function Keys -@subsection Rebinding Function Keys - - Key sequences can contain function keys as well as ordinary -characters. Just as Lisp characters (actually integers) represent -keyboard characters, Lisp symbols represent function keys. If the -function key has a word as its label, then that word is also the name of -the corresponding Lisp symbol. Here are the conventional Lisp names for -common function keys: - -@table @asis -@item @code{LEFT}, @code{UP}, @code{RIGHT}, @code{DOWN} -Cursor arrow keys. - -@item @code{Begin}, @code{End}, @code{Home}, @code{next}, @code{prior} -Other cursor repositioning keys. - -@item @code{select}, @code{print}, @code{execute}, @code{backtab} -@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline} -@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar} -Miscellaneous function keys. - -@item @code{f1}, @code{f2}, @dots{} @code{f35} -Numbered function keys (across the top of the keyboard). - -@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide} -@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter} -@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal} -Keypad keys (to the right of the regular keyboard), with names or punctuation. - -@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9} -Keypad keys with digits. - -@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} -Keypad PF keys. -@end table - - These names are conventional, but some systems (especially when using -X) may use different names. To make certain what symbol is used for a -given function key on your terminal, type @kbd{C-h c} followed by that -key. - - @xref{Init Rebinding}, for examples of binding function keys. - -@cindex keypad - Many keyboards have a ``numeric keypad'' on the right hand side. -The numeric keys in the keypad double up as cursor motion keys, -toggled by a key labeled @samp{Num Lock}. By default, Emacs -translates these keys to the corresponding keys in the main keyboard. -For example, when @samp{Num Lock} is on, the key labeled @samp{8} on -the numeric keypad produces @code{kp-8}, which is translated to -@kbd{8}; when @samp{Num Lock} is off, the same key produces -@code{kp-up}, which is translated to @key{UP}. If you rebind a key -such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too. -However, if you rebind a @samp{kp-} key directly, that won't affect -its non-keypad equivalent. Note that the modified keys are not -translated: for instance, if you hold down the @key{META} key while -pressing the @samp{8} key on the numeric keypad, that generates -@kbd{M-@key{kp-8}}. - - Emacs provides a convenient method for binding the numeric keypad -keys, using the variables @code{keypad-setup}, -@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and -@code{keypad-numlock-shifted-setup}. These can be found in the -@samp{keyboard} customization group (@pxref{Easy Customization}). You -can rebind the keys to perform other tasks, such as issuing numeric -prefix arguments. - -@node Named ASCII Chars -@subsection Named @acronym{ASCII} Control Characters - - @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} -started out as names for certain @acronym{ASCII} control characters, -used so often that they have special keys of their own. For instance, -@key{TAB} was another name for @kbd{C-i}. Later, users found it -convenient to distinguish in Emacs between these keys and the ``same'' -control characters typed with the @key{Ctrl} key. Therefore, on most -modern terminals, they are no longer the same: @key{TAB} is different -from @kbd{C-i}. - - Emacs can distinguish these two kinds of input if the keyboard does. -It treats the ``special'' keys as function keys named @code{tab}, -@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and -@code{delete}. These function keys translate automatically into the -corresponding @acronym{ASCII} characters @emph{if} they have no -bindings of their own. As a result, neither users nor Lisp programs -need to pay attention to the distinction unless they care to. - - If you do not want to distinguish between (for example) @key{TAB} and -@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB} -(octal code 011). If you do want to distinguish, make one binding for -this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. - - With an ordinary @acronym{ASCII} terminal, there is no way to distinguish -between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), -because the terminal sends the same character in both cases. - -@node Mouse Buttons -@subsection Rebinding Mouse Buttons -@cindex mouse button events -@cindex rebinding mouse buttons -@cindex click events -@cindex drag events -@cindex down events -@cindex button down events - - Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary -mouse events in Emacs are @dfn{click} events; these happen when you -press a button and release it without moving the mouse. You can also -get @dfn{drag} events, when you move the mouse while holding the button -down. Drag events happen when you finally let go of the button. - - The symbols for basic click events are @code{mouse-1} for the leftmost -button, @code{mouse-2} for the next, and so on. Here is how you can -redefine the second mouse button to split the current window: - -@example -(global-set-key [mouse-2] 'split-window-below) -@end example - - The symbols for drag events are similar, but have the prefix -@samp{drag-} before the word @samp{mouse}. For example, dragging the -first button generates a @code{drag-mouse-1} event. - - You can also define bindings for events that occur when a mouse button -is pressed down. These events start with @samp{down-} instead of -@samp{drag-}. Such events are generated only if they have key bindings. -When you get a button-down event, a corresponding click or drag event -will always follow. - -@cindex double clicks -@cindex triple clicks - If you wish, you can distinguish single, double, and triple clicks. A -double click means clicking a mouse button twice in approximately the -same place. The first click generates an ordinary click event. The -second click, if it comes soon enough, generates a double-click event -instead. The event type for a double-click event starts with -@samp{double-}: for example, @code{double-mouse-3}. - - This means that you can give a special meaning to the second click at -the same place, but it must act on the assumption that the ordinary -single click definition has run when the first click was received. - - This constrains what you can do with double clicks, but user interface -designers say that this constraint ought to be followed in any case. A -double click should do something similar to the single click, only -``more so''. The command for the double-click event should perform the -extra work for the double click. - - If a double-click event has no binding, it changes to the -corresponding single-click event. Thus, if you don't define a -particular double click specially, it executes the single-click command -twice. - - Emacs also supports triple-click events whose names start with -@samp{triple-}. Emacs does not distinguish quadruple clicks as event -types; clicks beyond the third generate additional triple-click events. -However, the full number of clicks is recorded in the event list, so -if you know Emacs Lisp you can distinguish if you really want to -(@pxref{Click Events,,, elisp, The Emacs Lisp Reference Manual}). -We don't recommend distinct meanings for more than three clicks, but -sometimes it is useful for subsequent clicks to cycle through the same -set of three meanings, so that four clicks are equivalent to one -click, five are equivalent to two, and six are equivalent to three. - - Emacs also records multiple presses in drag and button-down events. -For example, when you press a button twice, then move the mouse while -holding the button, Emacs gets a @samp{double-drag-} event. And at the -moment when you press it down for the second time, Emacs gets a -@samp{double-down-} event (which is ignored, like all button-down -events, if it has no binding). - -@vindex double-click-time - The variable @code{double-click-time} specifies how much time can -elapse between clicks and still allow them to be grouped as a multiple -click. Its value is in units of milliseconds. If the value is -@code{nil}, double clicks are not detected at all. If the value is -@code{t}, then there is no time limit. The default is 500. - -@vindex double-click-fuzz - The variable @code{double-click-fuzz} specifies how much the mouse -can move between clicks and still allow them to be grouped as a multiple -click. Its value is in units of pixels on windowed displays and in -units of 1/8 of a character cell on text-mode terminals; the default is -3. - - The symbols for mouse events also indicate the status of the modifier -keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-}, -@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-} -or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}. - - A frame includes areas that don't show text from the buffer, such as -the mode line and the scroll bar. You can tell whether a mouse button -comes from a special area of the screen by means of dummy ``prefix -keys''. For example, if you click the mouse in the mode line, you get -the prefix key @code{mode-line} before the ordinary mouse-button symbol. -Thus, here is how to define the command for clicking the first button in -a mode line to run @code{scroll-up-command}: - -@example -(global-set-key [mode-line mouse-1] 'scroll-up-command) -@end example - - Here is the complete list of these dummy prefix keys and their -meanings: - -@table @code -@item mode-line -The mouse was in the mode line of a window. -@item vertical-line -The mouse was in the vertical line separating side-by-side windows. (If -you use scroll bars, they appear in place of these vertical lines.) -@item vertical-scroll-bar -The mouse was in a vertical scroll bar. (This is the only kind of -scroll bar Emacs currently supports.) -@item menu-bar -The mouse was in the menu bar. -@item header-line -The mouse was in a header line. -@ignore -@item horizontal-scroll-bar -The mouse was in a horizontal scroll bar. Horizontal scroll bars do -horizontal scrolling, and people don't use them often. -@end ignore -@end table - - You can put more than one mouse button in a key sequence, but it isn't -usual to do so. - -@node Disabling -@subsection Disabling Commands -@cindex disabled command - - Disabling a command means that invoking it interactively asks for -confirmation from the user. The purpose of disabling a command is to -prevent users from executing it by accident; we do this for commands -that might be confusing to the uninitiated. - - Attempting to invoke a disabled command interactively in Emacs -displays a window containing the command's name, its documentation, -and some instructions on what to do immediately; then Emacs asks for -input saying whether to execute the command as requested, enable it -and execute it, or cancel. If you decide to enable the command, you -must then answer another question---whether to do this permanently, or -just for the current session. (Enabling permanently works by -automatically editing your initialization file.) You can also type -@kbd{!} to enable @emph{all} commands, for the current session only. - - The direct mechanism for disabling a command is to put a -non-@code{nil} @code{disabled} property on the Lisp symbol for the -command. Here is the Lisp program to do this: - -@example -(put 'delete-region 'disabled t) -@end example - - If the value of the @code{disabled} property is a string, that string -is included in the message displayed when the command is used: - -@example -(put 'delete-region 'disabled - "It's better to use `kill-region' instead.\n") -@end example - -@findex disable-command -@findex enable-command - You can make a command disabled either by editing the initialization -file directly, or with the command @kbd{M-x disable-command}, which -edits the initialization file for you. Likewise, @kbd{M-x -enable-command} edits the initialization file to enable a command -permanently. @xref{Init File}. - - If Emacs was invoked with the @option{-q} or @option{--no-init-file} -options (@pxref{Initial Options}), it will not edit your -initialization file. Doing so could lose information because Emacs -has not read your initialization file. - - Whether a command is disabled is independent of what key is used to -invoke it; disabling also applies if the command is invoked using -@kbd{M-x}. However, disabling a command has no effect on calling it -as a function from Lisp programs. - -@node Init File -@section The Emacs Initialization File -@cindex init file -@cindex .emacs file -@cindex ~/.emacs file -@cindex Emacs initialization file -@cindex key rebinding, permanent -@cindex rebinding keys, permanently -@cindex startup (init file) - - When Emacs is started, it normally tries to load a Lisp program from -an @dfn{initialization file}, or @dfn{init file} for short. This -file, if it exists, specifies how to initialize Emacs for you. Emacs -looks for your init file using the filenames @file{~/.emacs}, -@file{~/.emacs.el}, or @file{~/.emacs.d/init.el}; you can choose to -use any one of these three names (@pxref{Find Init}). Here, @file{~/} -stands for your home directory. - - You can use the command line switch @samp{-q} to prevent loading -your init file, and @samp{-u} (or @samp{--user}) to specify a -different user's init file (@pxref{Initial Options}). - -@cindex @file{default.el}, the default init file - There can also be a @dfn{default init file}, which is the library -named @file{default.el}, found via the standard search path for -libraries. The Emacs distribution contains no such library; your site -may create one for local customizations. If this library exists, it is -loaded whenever you start Emacs (except when you specify @samp{-q}). -But your init file, if any, is loaded first; if it sets -@code{inhibit-default-init} non-@code{nil}, then @file{default} is not -loaded. - -@cindex site init file -@cindex @file{site-start.el}, the site startup file - Your site may also have a @dfn{site startup file}; this is named -@file{site-start.el}, if it exists. Like @file{default.el}, Emacs -finds this file via the standard search path for Lisp libraries. -Emacs loads this library before it loads your init file. To inhibit -loading of this library, use the option @samp{--no-site-file}. -@xref{Initial Options}. We recommend against using -@file{site-start.el} for changes that some users may not like. It is -better to put them in @file{default.el}, so that users can more easily -override them. - -@cindex site-lisp directories - You can place @file{default.el} and @file{site-start.el} in any of -the directories which Emacs searches for Lisp libraries. The variable -@code{load-path} (@pxref{Lisp Libraries}) specifies these directories. -Many sites put these files in a subdirectory named @file{site-lisp} in -the Emacs installation directory, such as -@file{/usr/local/share/emacs/site-lisp}. - - Byte-compiling your init file is not recommended (@pxref{Byte -Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference -Manual}). It generally does not speed up startup very much, and often -leads to problems when you forget to recompile the file. A better -solution is to use the Emacs server to reduce the number of times you -have to start Emacs (@pxref{Emacs Server}). If your init file defines -many functions, consider moving them to a separate (byte-compiled) -file that you load in your init file. - - If you are going to write actual Emacs Lisp programs that go beyond -minor customization, you should read the @cite{Emacs Lisp Reference Manual}. -@ifnottex -@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference -Manual}. -@end ifnottex - -@menu -* Init Syntax:: Syntax of constants in Emacs Lisp. -* Init Examples:: How to do some things with an init file. -* Terminal Init:: Each terminal type can have an init file. -* Find Init:: How Emacs finds the init file. -* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. -@end menu - -@node Init Syntax -@subsection Init File Syntax - - The init file contains one or more Lisp expressions. Each of these -consists of a function name followed by arguments, all surrounded by -parentheses. For example, @code{(setq fill-column 60)} calls the -function @code{setq} to set the variable @code{fill-column} -(@pxref{Filling}) to 60. - - You can set any Lisp variable with @code{setq}, but with certain -variables @code{setq} won't do what you probably want in the -@file{.emacs} file. Some variables automatically become buffer-local -when set with @code{setq}; what you want in @file{.emacs} is to set -the default value, using @code{setq-default}. Some customizable minor -mode variables do special things to enable the mode when you set them -with Customize, but ordinary @code{setq} won't do that; to enable the -mode in your @file{.emacs} file, call the minor mode command. The -following section has examples of both of these methods. - - The second argument to @code{setq} is an expression for the new -value of the variable. This can be a constant, a variable, or a -function call expression. In @file{.emacs}, constants are used most -of the time. They can be: - -@table @asis -@item Numbers: -Numbers are written in decimal, with an optional initial minus sign. - -@item Strings: -@cindex Lisp string syntax -@cindex string syntax -Lisp string syntax is the same as C string syntax with a few extra -features. Use a double-quote character to begin and end a string constant. - -In a string, you can include newlines and special characters literally. -But often it is cleaner to use backslash sequences for them: @samp{\n} -for newline, @samp{\b} for backspace, @samp{\r} for carriage return, -@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for -escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or -@samp{\@var{ooo}} for the character whose octal code is @var{ooo}. -Backslash and double-quote are the only characters for which backslash -sequences are mandatory. - -@samp{\C-} can be used as a prefix for a control character, as in -@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for -a Meta character, as in @samp{\M-a} for @kbd{@key{META}-A} or -@samp{\M-\C-a} for @kbd{@key{Ctrl}-@key{META}-A}. - -@xref{Init Non-ASCII}, for information about including -non-@acronym{ASCII} in your init file. - -@item Characters: -@cindex Lisp character syntax -@cindex character syntax -Lisp character constant syntax consists of a @samp{?} followed by -either a character or an escape sequence starting with @samp{\}. -Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that -strings and characters are not interchangeable in Lisp; some contexts -require one and some contexts require the other. - -@xref{Init Non-ASCII}, for information about binding commands to -keys which send non-@acronym{ASCII} characters. - -@item True: -@code{t} stands for `true'. - -@item False: -@code{nil} stands for `false'. - -@item Other Lisp objects: -@cindex Lisp object syntax -Write a single-quote (@code{'}) followed by the Lisp object you want. -@end table - -@node Init Examples -@subsection Init File Examples - - Here are some examples of doing certain commonly desired things with -Lisp expressions: - -@itemize @bullet -@item -Add a directory to the variable @code{load-path}. You can then put -Lisp libraries that are not included with Emacs in this directory, and -load them with @kbd{M-x load-library}. @xref{Lisp Libraries}. - -@example -(add-to-list 'load-path "/path/to/lisp/libraries") -@end example - -@item -Make @key{TAB} in C mode just insert a tab if point is in the middle of a -line. - -@example -(setq c-tab-always-indent nil) -@end example - -Here we have a variable whose value is normally @code{t} for `true' -and the alternative is @code{nil} for `false'. - -@item -Make searches case sensitive by default (in all buffers that do not -override this). - -@example -(setq-default case-fold-search nil) -@end example - -This sets the default value, which is effective in all buffers that do -not have local values for the variable (@pxref{Locals}). Setting -@code{case-fold-search} with @code{setq} affects only the current -buffer's local value, which is probably not what you want to do in an -init file. - -@item -@vindex user-mail-address -Specify your own email address, if Emacs can't figure it out correctly. - -@example -(setq user-mail-address "cheney@@torture.gov") -@end example - -Various Emacs packages, such as Message mode, consult -@code{user-mail-address} when they need to know your email address. -@xref{Mail Headers}. - -@item -Make Text mode the default mode for new buffers. - -@example -(setq-default major-mode 'text-mode) -@end example - -Note that @code{text-mode} is used because it is the command for -entering Text mode. The single-quote before it makes the symbol a -constant; otherwise, @code{text-mode} would be treated as a variable -name. - -@need 1500 -@item -Set up defaults for the Latin-1 character set -which supports most of the languages of Western Europe. - -@example -(set-language-environment "Latin-1") -@end example - -@need 1500 -@item -Turn off Line Number mode, a global minor mode. - -@example -(line-number-mode 0) -@end example - -@need 1500 -@item -Turn on Auto Fill mode automatically in Text mode and related modes -(@pxref{Hooks}). - -@example -(add-hook 'text-mode-hook 'auto-fill-mode) -@end example - -@item -Load the installed Lisp library named @file{foo} (actually a file -@file{foo.elc} or @file{foo.el} in a standard Emacs directory). - -@example -(load "foo") -@end example - -When the argument to @code{load} is a relative file name, not starting -with @samp{/} or @samp{~}, @code{load} searches the directories in -@code{load-path} (@pxref{Lisp Libraries}). - -@item -Load the compiled Lisp file @file{foo.elc} from your home directory. - -@example -(load "~/foo.elc") -@end example - -Here a full file name is used, so no searching is done. - -@item -@cindex loading Lisp libraries automatically -@cindex autoload Lisp libraries -Tell Emacs to find the definition for the function @code{myfunction} -by loading a Lisp library named @file{mypackage} (i.e., a file -@file{mypackage.elc} or @file{mypackage.el}): - -@example -(autoload 'myfunction "mypackage" "Do what I say." t) -@end example - -@noindent -Here the string @code{"Do what I say."} is the function's -documentation string. You specify it in the @code{autoload} -definition so it will be available for help commands even when the -package is not loaded. The last argument, @code{t}, indicates that -this function is interactive; that is, it can be invoked interactively -by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. -If the function is not interactive, omit the @code{t} or use -@code{nil}. - -@item -Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link} -(@pxref{Init Rebinding}). - -@example -(global-set-key "\C-xl" 'make-symbolic-link) -@end example - -or - -@example -(define-key global-map "\C-xl" 'make-symbolic-link) -@end example - -Note once again the single-quote used to refer to the symbol -@code{make-symbolic-link} instead of its value as a variable. - -@item -Do the same thing for Lisp mode only. - -@example -(define-key lisp-mode-map "\C-xl" 'make-symbolic-link) -@end example - -@item -Redefine all keys which now run @code{next-line} in Fundamental mode -so that they run @code{forward-line} instead. - -@findex substitute-key-definition -@example -(substitute-key-definition 'next-line 'forward-line - global-map) -@end example - -@item -Make @kbd{C-x C-v} undefined. - -@example -(global-unset-key "\C-x\C-v") -@end example - -One reason to undefine a key is so that you can make it a prefix. -Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a -prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix -definition. - -@item -Make @samp{$} have the syntax of punctuation in Text mode. -Note the use of a character constant for @samp{$}. - -@example -(modify-syntax-entry ?\$ "." text-mode-syntax-table) -@end example - -@item -Enable the use of the command @code{narrow-to-region} without confirmation. - -@example -(put 'narrow-to-region 'disabled nil) -@end example - -@item -Adjusting the configuration to various platforms and Emacs versions. - -Users typically want Emacs to behave the same on all systems, so the -same init file is right for all platforms. However, sometimes it -happens that a function you use for customizing Emacs is not available -on some platforms or in older Emacs versions. To deal with that -situation, put the customization inside a conditional that tests whether -the function or facility is available, like this: - -@example -(if (fboundp 'blink-cursor-mode) - (blink-cursor-mode 0)) - -(if (boundp 'coding-category-utf-8) - (set-coding-priority '(coding-category-utf-8))) -@end example - -@noindent -You can also simply disregard the errors that occur if the -function is not defined. - -@example -(condition case () - (set-face-background 'region "grey75") - (error nil)) -@end example - -A @code{setq} on a variable which does not exist is generally -harmless, so those do not need a conditional. -@end itemize - -@node Terminal Init -@subsection Terminal-specific Initialization - - Each terminal type can have a Lisp library to be loaded into Emacs when -it is run on that type of terminal. For a terminal type named -@var{termtype}, the library is called @file{term/@var{termtype}} and it is -found by searching the directories @code{load-path} as usual and trying the -suffixes @samp{.elc} and @samp{.el}. Normally it appears in the -subdirectory @file{term} of the directory where most Emacs libraries are -kept. - - The usual purpose of the terminal-specific library is to map the -escape sequences used by the terminal's function keys onto more -meaningful names, using @code{input-decode-map} (or -@code{function-key-map} before it). See the file -@file{term/lk201.el} for an example of how this is done. Many function -keys are mapped automatically according to the information in the -Termcap data base; the terminal-specific library needs to map only the -function keys that Termcap does not specify. - - When the terminal type contains a hyphen, only the part of the name -before the first hyphen is significant in choosing the library name. -Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use -the library @file{term/aaa}. The code in the library can use -@code{(getenv "TERM")} to find the full terminal type name. - -@vindex term-file-prefix - The library's name is constructed by concatenating the value of the -variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} -file can prevent the loading of the terminal-specific library by setting -@code{term-file-prefix} to @code{nil}. - -@vindex tty-setup-hook - Emacs runs the hook @code{tty-setup-hook} at the end of -initialization, after both your @file{.emacs} file and any -terminal-specific library have been read in. Add hook functions to this -hook if you wish to override part of any of the terminal-specific -libraries and to define initializations for terminals that do not have a -library. @xref{Hooks}. - -@node Find Init -@subsection How Emacs Finds Your Init File - - Normally Emacs uses the environment variable @env{HOME} -(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what -@samp{~} means in a file name. If @file{.emacs} is not found inside -@file{~/} (nor @file{.emacs.el}), Emacs looks for -@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be -byte-compiled). - - However, if you run Emacs from a shell started by @code{su}, Emacs -tries to find your own @file{.emacs}, not that of the user you are -currently pretending to be. The idea is that you should get your own -editor customizations even if you are running as the super user. - - More precisely, Emacs first determines which user's init file to use. -It gets your user name from the environment variables @env{LOGNAME} and -@env{USER}; if neither of those exists, it uses effective user-ID@. -If that user name matches the real user-ID, then Emacs uses @env{HOME}; -otherwise, it looks up the home directory corresponding to that user -name in the system's data base of users. -@c LocalWords: backtab - -@node Init Non-ASCII -@subsection Non-@acronym{ASCII} Characters in Init Files -@cindex international characters in @file{.emacs} -@cindex non-@acronym{ASCII} characters in @file{.emacs} -@cindex non-@acronym{ASCII} keys, binding -@cindex rebinding non-@acronym{ASCII} keys - - Language and coding systems may cause problems if your init file -contains non-@acronym{ASCII} characters, such as accented letters, in -strings or key bindings. - - If you want to use non-@acronym{ASCII} characters in your init file, -you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on -the first line of the init file, and specify a coding system that -supports the character(s) in question. @xref{Recognize Coding}. This -is because the defaults for decoding non-@acronym{ASCII} text might -not yet be set up by the time Emacs reads those parts of your init -file which use such strings, possibly leading Emacs to decode those -strings incorrectly. You should then avoid adding Emacs Lisp code -that modifies the coding system in other ways, such as calls to -@code{set-language-environment}. - - To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init -Rebinding}). The string syntax cannot be used, since the -non-@acronym{ASCII} characters will be interpreted as meta keys. For -instance: - -@example -(global-set-key [?@var{char}] 'some-function) -@end example - -@noindent -Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. - - @strong{Warning:} if you change the keyboard encoding, or change -between multibyte and unibyte mode, or anything that would alter which -code @kbd{C-q} would insert for that character, this key binding may -stop working. It is therefore advisable to use one and only one -coding system, for your init file as well as the files you edit. For -example, don't mix the @samp{latin-1} and @samp{latin-9} coding -systems. diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi deleted file mode 100644 index f8719e84de0..00000000000 --- a/doc/emacs/dired-xtra.texi +++ /dev/null @@ -1,50 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Subdir Switches -@section Subdirectory Switches in Dired - -You can insert subdirectories with specified @command{ls} switches in -Dired buffers using @kbd{C-u i}. You can change the @command{ls} -switches of an already inserted subdirectory at point using @kbd{C-u l}. - -Dired preserves the switches if you revert the buffer. Deleting a -subdirectory forgets about its switches. - -Using @code{dired-undo} -@iftex -(@pxref{Marks vs Flags,,, emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Marks vs Flags}) -@end ifnottex -to reinsert or delete -subdirectories that were inserted with explicit switches can bypass -Dired's machinery for remembering (or forgetting) switches. Deleting -a subdirectory using @code{dired-undo} does not forget its switches. -When later reinserted using @kbd{i}, it will be reinserted using its -old switches. Using @code{dired-undo} to reinsert a subdirectory that -was deleted using the regular Dired commands (not @code{dired-undo}) -will originally insert it with its old switches. Reverting the -buffer, however, will relist it using the buffer's default switches. -If any of this yields problems, you can easily correct the situation -using @kbd{C-u i} or @kbd{C-u l}. - -Dired does not remember the @code{R} switch. Inserting a subdirectory -with switches that include the @code{R} switch is equivalent to -inserting each of its subdirectories using all remaining switches. -For instance, updating or killing a subdirectory that was inserted -with the @code{R} switch will not update or kill its subdirectories. - -The buffer's default switches do not affect subdirectories that were -inserted using explicitly specified switches. In particular, -commands such as @kbd{s} that change the buffer's switches do not -affect such subdirectories. (They do, however, affect subdirectories -without explicitly assigned switches.) - -You can make Dired forget about all subdirectory switches and relist -all subdirectories with the buffer's default switches using -@kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi deleted file mode 100644 index c7dace619e9..00000000000 --- a/doc/emacs/dired.texi +++ /dev/null @@ -1,1456 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Dired -@chapter Dired, the Directory Editor -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. -@cindex Dired -@cindex file management - - Dired makes an Emacs buffer containing a listing of a directory, and -optionally some of its subdirectories as well. You can use the normal -Emacs commands to move around in this buffer, and special Dired -commands to operate on the listed files. - - The Dired buffer is ``read-only'', and inserting text in it is not -allowed. Ordinary printing characters such as @kbd{d} and @kbd{x} are -redefined for special Dired commands. Some Dired commands @dfn{mark} -or @dfn{flag} the @dfn{current file} (that is, the file on the current -line); other commands operate on the marked files or on the flagged -files. You first mark certain files in order to operate on all of -them with one command. - - The Dired-X package provides various extra features for Dired mode. -@xref{Top, Dired-X,,dired-x, Dired Extra User's Manual}. - - You can also view a list of files in a directory with @kbd{C-x C-d} -(@code{list-directory}). Unlike Dired, this command does not allow -you to operate on the listed files. @xref{Directories}. - -@menu -* Enter: Dired Enter. How to invoke Dired. -* Navigation: Dired Navigation. Special motion commands in the Dired buffer. -* Deletion: Dired Deletion. Deleting files with Dired. -* Flagging Many Files:: Flagging files based on their names. -* Visit: Dired Visiting. Other file operations through Dired. -* Marks vs Flags:: Flagging for deletion vs marking. -* Operating on Files:: How to copy, rename, print, compress, etc. - either one file or several files. -* Shell Commands in Dired:: Running a shell command on the marked files. -* Transforming File Names:: Using patterns to rename multiple files. -* Comparison in Dired:: Running @code{diff} by way of Dired. -* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. -@ifnottex -* Subdir Switches:: Subdirectory switches in Dired. -@end ifnottex -* Subdirectory Motion:: Moving across subdirectories, and up and down. -* Hiding Subdirectories:: Making subdirectories visible or invisible. -* Updating: Dired Updating. Discarding lines for files of no interest. -* Find: Dired and Find. Using @code{find} to choose the files for Dired. -* Wdired:: Operating on files by editing the Dired buffer. -* Image-Dired:: Viewing image thumbnails in Dired. -* Misc: Misc Dired Features. Various other features. -@end menu - -@node Dired Enter -@section Entering Dired - -@findex dired -@kindex C-x d -@vindex dired-listing-switches - To invoke Dired, type @kbd{C-x d} (@code{dired}). This reads a -directory name using the minibuffer, and opens a @dfn{Dired buffer} -listing the files in that directory. You can also supply a wildcard -file name pattern as the minibuffer argument, in which case the Dired -buffer lists all files matching that pattern. The usual history and -completion commands can be used in the minibuffer; in particular, -@kbd{M-n} puts the name of the visited file (if any) in the minibuffer -(@pxref{Minibuffer History}). - - You can also invoke Dired by giving @kbd{C-x C-f} (@code{find-file}) -a directory name. - - The variable @code{dired-listing-switches} specifies the options to -give to @command{ls} for listing the directory; this string -@emph{must} contain @samp{-l}. If you use a prefix argument with the -@code{dired} command, you can specify the @command{ls} switches with the -minibuffer before you enter the directory specification. No matter -how they are specified, the @command{ls} switches can include short -options (that is, single characters) requiring no arguments, and long -options (starting with @samp{--}) whose arguments are specified with -@samp{=}. - -@vindex dired-use-ls-dired - If your @command{ls} program supports the @samp{--dired} option, -Dired automatically passes it that option; this causes @command{ls} to -emit special escape sequences for certain unusual file names, without -which Dired will not be able to parse those names. The first time you -run Dired in an Emacs session, it checks whether @command{ls} supports -the @samp{--dired} option by calling it once with that option. If the -exit code is 0, Dired will subsequently use the @samp{--dired} option; -otherwise it will not. You can inhibit this check by customizing the -variable @code{dired-use-ls-dired}. The value @code{unspecified} (the -default) means to perform the check; any other non-@code{nil} value -means to use the @samp{--dired} option; and @code{nil} means not to -use the @samp{--dired} option. - - On MS-Windows and MS-DOS systems, Emacs emulates @command{ls}. -@xref{ls in Lisp}, for options and peculiarities of this emulation. - -@findex dired-other-window -@kindex C-x 4 d -@findex dired-other-frame -@kindex C-x 5 d - To display the Dired buffer in another window, use @kbd{C-x 4 d} -(@code{dired-other-window}). @kbd{C-x 5 d} -(@code{dired-other-frame}) displays the Dired buffer in a separate -frame. - -@kindex q @r{(Dired)} -@findex quit-window - Typing @kbd{q} (@code{quit-window}) buries the Dired buffer, and -deletes its window if the window was created just for that buffer. - -@node Dired Navigation -@section Navigation in the Dired Buffer - -@kindex C-n @r{(Dired)} -@kindex C-p @r{(Dired)} - All the usual Emacs cursor motion commands are available in Dired -buffers. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the -cursor at the beginning of the file name on the line, rather than at -the beginning of the line. - -@kindex SPC @r{(Dired)} - For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent -to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines -is so common in Dired that it deserves to be easy to type.) @key{DEL} -(move up and unflag) is also often useful simply for moving up -(@pxref{Dired Deletion}). - -@findex dired-goto-file -@kindex j @r{(Dired)} - @kbd{j} (@code{dired-goto-file}) prompts for a file name using the -minibuffer, and moves point to the line in the Dired buffer describing -that file. - -@cindex searching Dired buffers -@findex dired-isearch-filenames -@vindex dired-isearch-filenames -@findex dired-isearch-filenames-regexp -@kindex M-s f C-s @r{(Dired)} -@kindex M-s f M-C-s @r{(Dired)} - @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward -incremental search in the Dired buffer, looking for matches only -amongst the file names and ignoring the rest of the text in the -buffer. @kbd{M-s f M-C-s} (@code{dired-isearch-filenames-regexp}) -does the same, using a regular expression search. If you change the -variable @code{dired-isearch-filenames} to @code{t}, then the -usual search commands also limit themselves to the file names; for -instance, @kbd{C-s} behaves like @kbd{M-s f C-s}. If the value is -@code{dwim}, then search commands match the file names only when point -was on a file name initially. @xref{Search}, for information about -incremental search. - - Some additional navigation commands are available when the Dired -buffer includes several directories. @xref{Subdirectory Motion}. - -@node Dired Deletion -@section Deleting Files with Dired -@cindex flagging files (in Dired) -@cindex deleting files (in Dired) - - One of the most frequent uses of Dired is to first @dfn{flag} files for -deletion, then delete the files that were flagged. - -@table @kbd -@item d -Flag this file for deletion (@code{dired-flag-file-deletion}). -@item u -Remove the deletion flag (@code{dired-unmark}). -@item @key{DEL} -Move point to previous line and remove the deletion flag on that line -(@code{dired-unmark-backward}). -@item x -Delete files flagged for deletion (@code{dired-do-flagged-delete}). -@end table - -@kindex d @r{(Dired)} -@findex dired-flag-file-deletion - You can flag a file for deletion by moving to the line describing -the file and typing @kbd{d} (@code{dired-flag-file-deletion}). The -deletion flag is visible as a @samp{D} at the beginning of the line. -This command moves point to the next line, so that repeated @kbd{d} -commands flag successive files. A numeric prefix argument serves as a -repeat count; a negative count means to flag preceding files. - - If the region is active, the @kbd{d} command flags all files in the -region for deletion; in this case, the command does not move point, -and ignores any prefix argument. - -@kindex u @r{(Dired deletion)} -@kindex DEL @r{(Dired)} - The reason for flagging files for deletion, rather than deleting -files immediately, is to reduce the danger of deleting a file -accidentally. Until you direct Dired to delete the flagged files, you -can remove deletion flags using the commands @kbd{u} and @key{DEL}. -@kbd{u} (@code{dired-unmark}) works just like @kbd{d}, but removes -flags rather than making flags. @key{DEL} -(@code{dired-unmark-backward}) moves upward, removing flags; it is -like @kbd{u} with argument @minus{}1. A numeric prefix argument to -either command serves as a repeat count, with a negative count meaning -to unflag in the opposite direction. If the region is active, these -commands instead unflag all files in the region, without moving point. - -@kindex x @r{(Dired)} -@findex dired-do-flagged-delete - To delete flagged files, type @kbd{x} -(@code{dired-do-flagged-delete}). This command displays a list of all -the file names flagged for deletion, and requests confirmation with -@kbd{yes}. If you confirm, Dired deletes the flagged files, then -deletes their lines from the text of the Dired buffer. The Dired -buffer, with somewhat fewer lines, remains selected. - - If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you -return immediately to Dired, with the deletion flags still present in -the buffer, and no files actually deleted. - -@cindex recursive deletion -@vindex dired-recursive-deletes - You can delete empty directories just like other files, but normally -Dired cannot delete directories that are nonempty. If the variable -@code{dired-recursive-deletes} is non-@code{nil}, then Dired can -delete nonempty directories including all their contents. That can -be somewhat risky. - -@vindex delete-by-moving-to-trash - If you change the variable @code{delete-by-moving-to-trash} to -@code{t}, the above deletion commands will move the affected files or -directories into the operating system's Trash, instead of deleting -them outright. @xref{Misc File Ops}. - -@node Flagging Many Files -@section Flagging Many Files at Once -@cindex flagging many files for deletion (in Dired) - - The @kbd{#}, @kbd{~}, @kbd{.}, @kbd{% &}, and @kbd{% d} commands -flag many files for deletion, based on their file names: - -@table @kbd -@item # -Flag all auto-save files (files whose names start and end with @samp{#}) -for deletion (@pxref{Auto Save}). - -@item ~ -Flag all backup files (files whose names end with @samp{~}) for deletion -(@pxref{Backup}). - -@item .@: @r{(Period)} -Flag excess numeric backup files for deletion. The oldest and newest -few backup files of any one file are exempt; the middle ones are -flagged. - -@item % & -Flag for deletion all files with certain kinds of names which suggest -you could easily create those files again. - -@item % d @var{regexp} @key{RET} -Flag for deletion all files whose names match the regular expression -@var{regexp}. -@end table - -@kindex # @r{(Dired)} -@findex dired-flag-auto-save-files -@cindex deleting auto-save files - @kbd{#} (@code{dired-flag-auto-save-files}) flags all files whose -names look like auto-save files---that is, files whose names begin and -end with @samp{#}. @xref{Auto Save}. - -@kindex ~ @r{(Dired)} -@findex dired-flag-backup-files - @kbd{~} (@code{dired-flag-backup-files}) flags all files whose names -say they are backup files---that is, files whose names end in -@samp{~}. @xref{Backup}. - -@kindex . @r{(Dired)} -@vindex dired-kept-versions -@findex dired-clean-directory - @kbd{.} (period, @code{dired-clean-directory}) flags just some of -the backup files for deletion: all but the oldest few and newest few -backups of any one file. Normally, the number of newest versions kept -for each file is given by the variable @code{dired-kept-versions} -(@emph{not} @code{kept-new-versions}; that applies only when saving). -The number of oldest versions to keep is given by the variable -@code{kept-old-versions}. - - Period with a positive numeric argument, as in @kbd{C-u 3 .}, -specifies the number of newest versions to keep, overriding -@code{dired-kept-versions}. A negative numeric argument overrides -@code{kept-old-versions}, using minus the value of the argument to -specify the number of oldest versions of each file to keep. - -@kindex % & @r{(Dired)} -@findex dired-flag-garbage-files -@vindex dired-garbage-files-regexp -@cindex deleting some backup files - @kbd{% &} (@code{dired-flag-garbage-files}) flags files whose names -match the regular expression specified by the variable -@code{dired-garbage-files-regexp}. By default, this matches certain -files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and -@samp{.rej} files produced by @code{patch}. - -@findex dired-flag-files-regexp -@kindex % d @r{(Dired)} - @kbd{% d} flags all files whose names match a specified regular -expression (@code{dired-flag-files-regexp}). Only the non-directory -part of the file name is used in matching. You can use @samp{^} and -@samp{$} to anchor matches. You can exclude certain subdirectories -from marking by hiding them while you use @kbd{% d}. @xref{Hiding -Subdirectories}. - -@node Dired Visiting -@section Visiting Files in Dired - - There are several Dired commands for visiting or examining the files -listed in the Dired buffer. All of them apply to the current line's -file; if that file is really a directory, these commands invoke Dired on -that subdirectory (making a separate Dired buffer). - -@table @kbd -@item f -@kindex f @r{(Dired)} -@findex dired-find-file -Visit the file described on the current line, like typing @kbd{C-x C-f} -and supplying that file name (@code{dired-find-file}). @xref{Visiting}. - -@item @key{RET} -@itemx e -@kindex RET @r{(Dired)} -@kindex e @r{(Dired)} -Equivalent to @kbd{f}. - -@ignore @c This command seems too risky to document at all. -@item a -@kindex a @r{(Dired)} -@findex dired-find-alternate-file -Like @kbd{f}, but replaces the contents of the Dired buffer with -that of an alternate file or directory (@code{dired-find-alternate-file}). -@end ignore - -@item o -@kindex o @r{(Dired)} -@findex dired-find-file-other-window -Like @kbd{f}, but uses another window to display the file's buffer -(@code{dired-find-file-other-window}). The Dired buffer remains visible -in the first window. This is like using @kbd{C-x 4 C-f} to visit the -file. @xref{Windows}. - -@item C-o -@kindex C-o @r{(Dired)} -@findex dired-display-file -Visit the file described on the current line, and display the buffer in -another window, but do not select that window (@code{dired-display-file}). - -@item Mouse-1 -@itemx Mouse-2 -@findex dired-mouse-find-file-other-window -Visit the file whose name you clicked on -(@code{dired-mouse-find-file-other-window}). This uses another window -to display the file, like the @kbd{o} command. - -@item v -@kindex v @r{(Dired)} -@findex dired-view-file -View the file described on the current line, with View mode -(@code{dired-view-file}). View mode provides convenient commands to -navigate the buffer but forbids changing it; @xref{View Mode}. - -@item ^ -@kindex ^ @r{(Dired)} -@findex dired-up-directory -Visit the parent directory of the current directory -(@code{dired-up-directory}). This is equivalent to moving to the line -for @file{..} and typing @kbd{f} there. -@end table - -@node Marks vs Flags -@section Dired Marks vs. Flags - -@cindex marking many files (in Dired) - Instead of flagging a file with @samp{D}, you can @dfn{mark} the -file with some other character (usually @samp{*}). Most Dired -commands to operate on files use the files marked with @samp{*}. The -only command that operates on flagged files is @kbd{x}, which deletes -them. - - Here are some commands for marking with @samp{*}, for unmarking, and -for operating on marks. (@xref{Dired Deletion}, for commands to flag -and unflag files.) - -@table @kbd -@item m -@itemx * m -@kindex m @r{(Dired)} -@kindex * m @r{(Dired)} -@findex dired-mark -Mark the current file with @samp{*} (@code{dired-mark}). If the -region is active, mark all files in the region instead; otherwise, if -a numeric argument @var{n} is supplied, mark the next @var{n} files -instead, starting with the current file (if @var{n} is negative, mark -the previous @minus{}@var{n} files). - -@item * * -@kindex * * @r{(Dired)} -@findex dired-mark-executables -@cindex marking executable files (in Dired) -Mark all executable files with @samp{*} -(@code{dired-mark-executables}). With a numeric argument, unmark all -those files. - -@item * @@ -@kindex * @@ @r{(Dired)} -@findex dired-mark-symlinks -@cindex marking symbolic links (in Dired) -Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}). -With a numeric argument, unmark all those files. - -@item * / -@kindex * / @r{(Dired)} -@findex dired-mark-directories -@cindex marking subdirectories (in Dired) -Mark with @samp{*} all files which are directories, except for -@file{.} and @file{..} (@code{dired-mark-directories}). With a numeric -argument, unmark all those files. - -@item * s -@kindex * s @r{(Dired)} -@findex dired-mark-subdir-files -Mark all the files in the current subdirectory, aside from @file{.} -and @file{..} (@code{dired-mark-subdir-files}). - -@item u -@itemx * u -@kindex u @r{(Dired)} -@kindex * u @r{(Dired)} -@findex dired-unmark -Remove any mark on this line (@code{dired-unmark}). If the region is -active, unmark all files in the region instead; otherwise, if a -numeric argument @var{n} is supplied, unmark the next @var{n} files -instead, starting with the current file (if @var{n} is negative, -unmark the previous @minus{}@var{n} files). - -@item @key{DEL} -@itemx * @key{DEL} -@kindex * DEL @r{(Dired)} -@findex dired-unmark-backward -@cindex unmarking files (in Dired) -Move point to previous line and remove any mark on that line -(@code{dired-unmark-backward}). If the region is active, unmark all -files in the region instead; otherwise, if a numeric argument @var{n} -is supplied, unmark the @var{n} preceding files instead, starting with -the current file (if @var{n} is negative, unmark the next -@minus{}@var{n} files). - -@item * ! -@itemx U -@kindex * ! @r{(Dired)} -@kindex U @r{(Dired)} -@findex dired-unmark-all-marks -Remove all marks from all the files in this Dired buffer -(@code{dired-unmark-all-marks}). - -@item * ? @var{markchar} -@itemx M-@key{DEL} -@kindex * ? @r{(Dired)} -@kindex M-DEL @r{(Dired)} -@findex dired-unmark-all-files -Remove all marks that use the character @var{markchar} -(@code{dired-unmark-all-files}). The argument is a single -character---do not use @key{RET} to terminate it. See the description -of the @kbd{* c} command below, which lets you replace one mark -character with another. - -With a numeric argument, this command queries about each marked file, -asking whether to remove its mark. You can answer @kbd{y} meaning yes, -@kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining -files without asking about them. - -@item * C-n -@itemx M-@} -@findex dired-next-marked-file -@kindex * C-n @r{(Dired)} -@kindex M-@} @r{(Dired)} -Move down to the next marked file (@code{dired-next-marked-file}) -A file is ``marked'' if it has any kind of mark. - -@item * C-p -@itemx M-@{ -@findex dired-prev-marked-file -@kindex * C-p @r{(Dired)} -@kindex M-@{ @r{(Dired)} -Move up to the previous marked file (@code{dired-prev-marked-file}) - -@item t -@itemx * t -@kindex t @r{(Dired)} -@kindex * t @r{(Dired)} -@findex dired-toggle-marks -@cindex toggling marks (in Dired) -Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*} -become unmarked, and unmarked files are marked with @samp{*}. Files -marked in any other way are not affected. - -@item * c @var{old-markchar} @var{new-markchar} -@kindex * c @r{(Dired)} -@findex dired-change-marks -Replace all marks that use the character @var{old-markchar} with marks -that use the character @var{new-markchar} (@code{dired-change-marks}). -This command is the primary way to create or use marks other than -@samp{*} or @samp{D}. The arguments are single characters---do not use -@key{RET} to terminate them. - -You can use almost any character as a mark character by means of this -command, to distinguish various classes of files. If @var{old-markchar} -is a space (@samp{ }), then the command operates on all unmarked files; -if @var{new-markchar} is a space, then the command unmarks the files it -acts on. - -To illustrate the power of this command, here is how to put @samp{D} -flags on all the files that have no marks, while unflagging all those -that already have @samp{D} flags: - -@example -* c D t * c @key{SPC} D * c t @key{SPC} -@end example - -This assumes that no files were already marked with @samp{t}. - -@item % m @var{regexp} @key{RET} -@itemx * % @var{regexp} @key{RET} -@findex dired-mark-files-regexp -@kindex % m @r{(Dired)} -@kindex * % @r{(Dired)} -Mark (with @samp{*}) all files whose names match the regular expression -@var{regexp} (@code{dired-mark-files-regexp}). This command is like -@kbd{% d}, except that it marks files with @samp{*} instead of flagging -with @samp{D}. - -Only the non-directory part of the file name is used in matching. Use -@samp{^} and @samp{$} to anchor matches. You can exclude -subdirectories by temporarily hiding them (@pxref{Hiding -Subdirectories}). - -@item % g @var{regexp} @key{RET} -@findex dired-mark-files-containing-regexp -@kindex % g @r{(Dired)} -@cindex finding files containing regexp matches (in Dired) -Mark (with @samp{*}) all files whose @emph{contents} contain a match for -the regular expression @var{regexp} -(@code{dired-mark-files-containing-regexp}). This command is like -@kbd{% m}, except that it searches the file contents instead of the file -name. - -@item C-/ -@itemx C-x u -@itemx C-_ -@kindex C-_ @r{(Dired)} -@findex dired-undo -Undo changes in the Dired buffer, such as adding or removing -marks (@code{dired-undo}). @emph{This command does not revert the -actual file operations, nor recover lost files!} It just undoes -changes in the buffer itself. - -In some cases, using this after commands that operate on files can -cause trouble. For example, after renaming one or more files, -@code{dired-undo} restores the original names in the Dired buffer, -which gets the Dired buffer out of sync with the actual contents of -the directory. -@end table - -@node Operating on Files -@section Operating on Files -@cindex operating on files in Dired - - This section describes the basic Dired commands to operate on one file -or several files. All of these commands are capital letters; all of -them use the minibuffer, either to read an argument or to ask for -confirmation, before they act. All of them let you specify the -files to manipulate in these ways: - -@itemize @bullet -@item -If you give the command a numeric prefix argument @var{n}, it operates -on the next @var{n} files, starting with the current file. (If @var{n} -is negative, the command operates on the @minus{}@var{n} files preceding -the current line.) - -@item -Otherwise, if some files are marked with @samp{*}, the command operates -on all those files. - -@item -Otherwise, the command operates on the current file only. -@end itemize - -@noindent -Certain other Dired commands, such as @kbd{!} and the @samp{%} -commands, use the same conventions to decide which files to work on. - -@vindex dired-dwim-target -@cindex two directories (in Dired) - Commands which ask for a destination directory, such as those which -copy and rename files or create links for them, try to guess the default -target directory for the operation. Normally, they suggest the Dired -buffer's default directory, but if the variable @code{dired-dwim-target} -is non-@code{nil}, and if there is another Dired buffer displayed in the -next window, that other buffer's directory is suggested instead. - - Here are the file-manipulating Dired commands that operate on files. - -@table @kbd -@findex dired-do-copy -@kindex C @r{(Dired)} -@cindex copying files (in Dired) -@item C @var{new} @key{RET} -Copy the specified files (@code{dired-do-copy}). The argument @var{new} -is the directory to copy into, or (if copying a single file) the new -name. This is like the shell command @code{cp}. - -@vindex dired-copy-preserve-time -If @code{dired-copy-preserve-time} is non-@code{nil}, then copying -with this command preserves the modification time of the old file in -the copy, like @samp{cp -p}. - -@vindex dired-recursive-copies -@cindex recursive copying -The variable @code{dired-recursive-copies} controls whether to copy -directories recursively (like @samp{cp -r}). The default is -@code{top}, which means to ask before recursively copying a directory. - -@item D -@findex dired-do-delete -@kindex D @r{(Dired)} -Delete the specified files (@code{dired-do-delete}). This is like the -shell command @code{rm}. - -Like the other commands in this section, this command operates on the -@emph{marked} files, or the next @var{n} files. By contrast, @kbd{x} -(@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files. - -@findex dired-do-rename -@kindex R @r{(Dired)} -@cindex renaming files (in Dired) -@cindex moving files (in Dired) -@item R @var{new} @key{RET} -Rename the specified files (@code{dired-do-rename}). If you rename a -single file, the argument @var{new} is the new name of the file. If -you rename several files, the argument @var{new} is the directory into -which to move the files (this is like the shell command @command{mv}). - -Dired automatically changes the visited file name of buffers associated -with renamed files so that they refer to the new names. - -@findex dired-do-hardlink -@kindex H @r{(Dired)} -@cindex hard links (in Dired) -@item H @var{new} @key{RET} -Make hard links to the specified files (@code{dired-do-hardlink}). -This is like the shell command @command{ln}. The argument @var{new} is -the directory to make the links in, or (if making just one link) the -name to give the link. - -@findex dired-do-symlink -@kindex S @r{(Dired)} -@cindex symbolic links (creation in Dired) -@item S @var{new} @key{RET} -Make symbolic links to the specified files (@code{dired-do-symlink}). -This is like @samp{ln -s}. The argument @var{new} is the directory to -make the links in, or (if making just one link) the name to give the -link. - -@findex dired-do-chmod -@kindex M @r{(Dired)} -@cindex changing file permissions (in Dired) -@item M @var{modespec} @key{RET} -Change the mode (also called @dfn{permission bits}) of the specified -files (@code{dired-do-chmod}). @var{modespec} can be in octal or -symbolic notation, like arguments handled by the @command{chmod} -program. - -@findex dired-do-chgrp -@kindex G @r{(Dired)} -@cindex changing file group (in Dired) -@item G @var{newgroup} @key{RET} -Change the group of the specified files to @var{newgroup} -(@code{dired-do-chgrp}). - -@findex dired-do-chown -@kindex O @r{(Dired)} -@cindex changing file owner (in Dired) -@item O @var{newowner} @key{RET} -Change the owner of the specified files to @var{newowner} -(@code{dired-do-chown}). (On most systems, only the superuser can do -this.) - -@vindex dired-chown-program -The variable @code{dired-chown-program} specifies the name of the -program to use to do the work (different systems put @command{chown} -in different places). - -@findex dired-do-touch -@kindex T @r{(Dired)} -@cindex changing file time (in Dired) -@item T @var{timestamp} @key{RET} -Touch the specified files (@code{dired-do-touch}). This means -updating their modification times to the present time. This is like -the shell command @code{touch}. - -@findex dired-do-print -@kindex P @r{(Dired)} -@cindex printing files (in Dired) -@item P @var{command} @key{RET} -Print the specified files (@code{dired-do-print}). You must specify the -command to print them with, but the minibuffer starts out with a -suitable guess made using the variables @code{lpr-command} and -@code{lpr-switches} (the same variables that @code{lpr-buffer} uses; -@pxref{Printing}). - -@findex dired-do-compress -@kindex Z @r{(Dired)} -@cindex compressing files (in Dired) -@item Z -Compress the specified files (@code{dired-do-compress}). If the file -appears to be a compressed file already, uncompress it instead. - -@findex epa-dired-do-decrypt -@kindex :d @r{(Dired)} -@cindex decrypting files (in Dired) -@item :d -Decrypt the specified files (@code{epa-dired-do-decrypt}). -@xref{Dired integration,,, epa, EasyPG Assistant User's Manual}. - -@findex epa-dired-do-verify -@kindex :v @r{(Dired)} -@cindex verifying digital signatures on files (in Dired) -@item :v -Verify digital signatures on the specified files (@code{epa-dired-do-verify}). -@xref{Dired integration,,, epa, EasyPG Assistant User's Manual}. - -@findex epa-dired-do-sign -@kindex :s @r{(Dired)} -@cindex signing files (in Dired) -@item :s -Digitally sign the specified files (@code{epa-dired-do-sign}). -@xref{Dired integration,,, epa, EasyPG Assistant User's Manual}. - -@findex epa-dired-do-encrypt -@kindex :e @r{(Dired)} -@cindex encrypting files (in Dired) -@item :e -Encrypt the specified files (@code{epa-dired-do-encrypt}). -@xref{Dired integration,,, epa, EasyPG Assistant User's Manual}. - -@findex dired-do-load -@kindex L @r{(Dired)} -@cindex loading several files (in Dired) -@item L -Load the specified Emacs Lisp files (@code{dired-do-load}). -@xref{Lisp Libraries}. - -@findex dired-do-byte-compile -@kindex B @r{(Dired)} -@cindex byte-compiling several files (in Dired) -@item B -Byte compile the specified Emacs Lisp files -(@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte -Compilation, elisp, The Emacs Lisp Reference Manual}. - -@kindex A @r{(Dired)} -@findex dired-do-search -@cindex search multiple files (in Dired) -@item A @var{regexp} @key{RET} -Search all the specified files for the regular expression @var{regexp} -(@code{dired-do-search}). - -This command is a variant of @code{tags-search}. The search stops at -the first match it finds; use @kbd{M-,} to resume the search and find -the next match. @xref{Tags Search}. - -@kindex Q @r{(Dired)} -@findex dired-do-query-replace-regexp -@cindex search and replace in multiple files (in Dired) -@item Q @var{regexp} @key{RET} @var{to} @key{RET} -Perform @code{query-replace-regexp} on each of the specified files, -replacing matches for @var{regexp} with the string -@var{to} (@code{dired-do-query-replace-regexp}). - -This command is a variant of @code{tags-query-replace}. If you exit the -query replace loop, you can use @kbd{M-,} to resume the scan and replace -more matches. @xref{Tags Search}. -@end table - -@node Shell Commands in Dired -@section Shell Commands in Dired -@cindex shell commands, Dired - -@findex dired-do-shell-command -@kindex ! @r{(Dired)} -@kindex X @r{(Dired)} -The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a -shell command string in the minibuffer, and runs that shell command on -one or more files. The files that the shell command operates on are -determined in the usual way for Dired commands (@pxref{Operating on -Files}). The command @kbd{X} is a synonym for @kbd{!}. - - The command @kbd{&} (@code{dired-do-async-shell-command}) does the -same, except that it runs the shell command asynchronously. (You can -also do this with @kbd{!}, by appending a @samp{&} character to the -end of the shell command.) When the command operates on more than one -file, it runs multiple parallel copies of the specified shell command, -one for each file. As an exception, if the specified shell command -ends in @samp{;} or @samp{;&}, the shell command is run in the -background on each file sequentially; Emacs waits for each invoked -shell command to terminate before running the next one. - - For both @kbd{!} and @kbd{&}, the working directory for the shell -command is the top-level directory of the Dired buffer. - - If you tell @kbd{!} or @kbd{&} to operate on more than one file, the -shell command string determines how those files are passed to the -shell command: - -@itemize @bullet -@item -If you use @samp{*} surrounded by whitespace in the command string, -then the command runs just once, with the list of file names -substituted for the @samp{*}. The order of file names is the order of -appearance in the Dired buffer. - -Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire -list of file names, putting them into one tar file @file{foo.tar}. - -If you want to use @samp{*} as a shell wildcard with whitespace around -it, write @samp{*""}. In the shell, this is equivalent to @samp{*}; -but since the @samp{*} is not surrounded by whitespace, Dired does not -treat it specially. - -@item -Otherwise, if the command string contains @samp{?} surrounded by -whitespace, Emacs runs the shell command once @emph{for each file}, -substituting the current file name for @samp{?} each time. You can -use @samp{?} more than once in the command; the same file name -replaces each occurrence. - -@item -If the command string contains neither @samp{*} nor @samp{?}, Emacs -runs the shell command once for each file, adding the file name at the -end. For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on -each file. -@end itemize - - To iterate over the file names in a more complicated fashion, use an -explicit shell loop. For example, here is how to uuencode each file, -making the output file name by appending @samp{.uu} to the input file -name: - -@example -for file in * ; do uuencode "$file" "$file" >"$file".uu; done -@end example - - The @kbd{!} and @kbd{&} commands do not attempt to update the Dired -buffer to show new or modified files, because they don't know what -files will be changed. Use the @kbd{g} command to update the Dired -buffer (@pxref{Dired Updating}). - - @xref{Single Shell}, for information about running shell commands -outside Dired. - -@node Transforming File Names -@section Transforming File Names in Dired - - This section describes Dired commands which alter file names in a -systematic way. Each command operates on some or all of the marked -files, using a new name made by transforming the existing name. - - Like the basic Dired file-manipulation commands (@pxref{Operating on -Files}), the commands described here operate either on the next -@var{n} files, or on all files marked with @samp{*}, or on the current -file. (To mark files, use the commands described in @ref{Marks vs -Flags}.) - - All of the commands described in this section work -@emph{interactively}: they ask you to confirm the operation for each -candidate file. Thus, you can select more files than you actually -need to operate on (e.g., with a regexp that matches many files), and -then filter the selected names by typing @kbd{y} or @kbd{n} when the -command prompts for confirmation. - -@table @kbd -@findex dired-upcase -@kindex % u @r{(Dired)} -@cindex upcase file names -@item % u -Rename each of the selected files to an upper-case name -(@code{dired-upcase}). If the old file names are @file{Foo} -and @file{bar}, the new names are @file{FOO} and @file{BAR}. - -@item % l -@findex dired-downcase -@kindex % l @r{(Dired)} -@cindex downcase file names -Rename each of the selected files to a lower-case name -(@code{dired-downcase}). If the old file names are @file{Foo} and -@file{bar}, the new names are @file{foo} and @file{bar}. - -@item % R @var{from} @key{RET} @var{to} @key{RET} -@kindex % R @r{(Dired)} -@findex dired-do-rename-regexp -@itemx % C @var{from} @key{RET} @var{to} @key{RET} -@kindex % C @r{(Dired)} -@findex dired-do-copy-regexp -@itemx % H @var{from} @key{RET} @var{to} @key{RET} -@kindex % H @r{(Dired)} -@findex dired-do-hardlink-regexp -@itemx % S @var{from} @key{RET} @var{to} @key{RET} -@kindex % S @r{(Dired)} -@findex dired-do-symlink-regexp -These four commands rename, copy, make hard links and make soft links, -in each case computing the new name by regular-expression substitution -from the name of the old file. -@end table - - The four regular-expression substitution commands effectively -perform a search-and-replace on the selected file names. They read -two arguments: a regular expression @var{from}, and a substitution -pattern @var{to}; they match each ``old'' file name against -@var{from}, and then replace the matching part with @var{to}. You can -use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or -part of what the pattern matched in the old file name, as in -@code{replace-regexp} (@pxref{Regexp Replace}). If the regular -expression matches more than once in a file name, only the first match -is replaced. - - For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each -selected file by prepending @samp{x-} to its name. The inverse of this, -removing @samp{x-} from the front of each file name, is also possible: -one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is -@kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor -matches that should span the whole file name.) - - Normally, the replacement process does not consider the files' -directory names; it operates on the file name within the directory. If -you specify a numeric argument of zero, then replacement affects the -entire absolute file name including directory name. (A non-zero -argument specifies the number of files to operate on.) - - You may want to select the set of files to operate on using the same -regexp @var{from} that you will use to operate on them. To do this, -mark those files with @kbd{% m @var{from} @key{RET}}, then use the -same regular expression in the command to operate on the files. To -make this more convenient, the @kbd{%} commands to operate on files -use the last regular expression specified in any @kbd{%} command as a -default. - -@node Comparison in Dired -@section File Comparison with Dired -@cindex file comparison (in Dired) -@cindex compare files (in Dired) - -@findex dired-diff -@kindex = @r{(Dired)} - The @kbd{=} (@code{dired-diff}) command compares the current file -(the file at point) with another file (read using the minibuffer) -using the @command{diff} program. The file specified with the -minibuffer is the first argument of @command{diff}, and file at point -is the second argument. The output of the @command{diff} program is -shown in a buffer using Diff mode (@pxref{Comparing Files}). - - If the region is active, the default for the file read using the -minibuffer is the file at the mark (i.e., the ordinary Emacs mark, -not a Dired mark; @pxref{Setting Mark}). Otherwise, if the file at -point has a backup file (@pxref{Backup}), that is the default. - -@node Subdirectories in Dired -@section Subdirectories in Dired -@cindex subdirectories in Dired -@cindex expanding subdirectories in Dired - - A Dired buffer usually displays just one directory, but you can -optionally include its subdirectories as well. - - The simplest way to include multiple directories in one Dired buffer is -to specify the options @samp{-lR} for running @command{ls}. (If you give a -numeric argument when you run Dired, then you can specify these options -in the minibuffer.) That produces a recursive directory listing showing -all subdirectories at all levels. - - More often, you will want to show only specific subdirectories. You -can do this with @kbd{i} (@code{dired-maybe-insert-subdir}): - -@table @kbd -@findex dired-maybe-insert-subdir -@kindex i @r{(Dired)} -@item i -@cindex inserted subdirectory (Dired) -@cindex in-situ subdirectory (Dired) -Insert the contents of a subdirectory later in the buffer. -@end table - -@noindent -If you use this command on a line that describes a file which is a -directory, it inserts the contents of that directory into the same -Dired buffer, and moves there. Inserted subdirectory contents follow -the top-level directory of the Dired buffer, just as they do in -@samp{ls -lR} output. - - If the subdirectory's contents are already present in the buffer, -the @kbd{i} command just moves to it. - - In either case, @kbd{i} sets the Emacs mark before moving, so -@kbd{C-u C-@key{SPC}} returns to your previous position in the Dired -buffer (@pxref{Setting Mark}). You can also use @samp{^} to return to -the parent directory in the same Dired buffer (@pxref{Dired -Visiting}). - - Use the @kbd{l} command (@code{dired-do-redisplay}) to update the -subdirectory's contents, and use @kbd{C-u k} on the subdirectory -header line to remove the subdirectory listing (@pxref{Dired -Updating}). You can also hide and show inserted subdirectories -(@pxref{Hiding Subdirectories}). - -@ifnottex -@include dired-xtra.texi -@end ifnottex - -@node Subdirectory Motion -@section Moving Over Subdirectories - - When a Dired buffer lists subdirectories, you can use the page motion -commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories -(@pxref{Pages}). - -@cindex header line (Dired) -@cindex directory header lines - The following commands move across, up and down in the tree of -directories within one Dired buffer. They move to @dfn{directory header -lines}, which are the lines that give a directory's name, at the -beginning of the directory's contents. - -@table @kbd -@findex dired-next-subdir -@kindex C-M-n @r{(Dired)} -@item C-M-n -Go to next subdirectory header line, regardless of level -(@code{dired-next-subdir}). - -@findex dired-prev-subdir -@kindex C-M-p @r{(Dired)} -@item C-M-p -Go to previous subdirectory header line, regardless of level -(@code{dired-prev-subdir}). - -@findex dired-tree-up -@kindex C-M-u @r{(Dired)} -@item C-M-u -Go up to the parent directory's header line (@code{dired-tree-up}). - -@findex dired-tree-down -@kindex C-M-d @r{(Dired)} -@item C-M-d -Go down in the directory tree, to the first subdirectory's header line -(@code{dired-tree-down}). - -@findex dired-prev-dirline -@kindex < @r{(Dired)} -@item < -Move up to the previous directory-file line (@code{dired-prev-dirline}). -These lines are the ones that describe a directory as a file in its -parent directory. - -@findex dired-next-dirline -@kindex > @r{(Dired)} -@item > -Move down to the next directory-file line (@code{dired-prev-dirline}). -@end table - -@node Hiding Subdirectories -@section Hiding Subdirectories -@cindex hiding subdirectories (Dired) -@cindex showing hidden subdirectories (Dired) - - @dfn{Hiding} a subdirectory means to make it invisible, except for its -header line. - -@table @kbd -@item $ -@findex dired-hide-subdir -@kindex $ @r{(Dired)} -Hide or show the subdirectory that point is in, and move point to the -next subdirectory (@code{dired-hide-subdir}). This is a toggle. A -numeric argument serves as a repeat count. - -@item M-$ -@findex dired-hide-all -@kindex M-$ @r{(Dired)} -Hide all subdirectories in this Dired buffer, leaving only their header -lines (@code{dired-hide-all}). Or, if any subdirectory is currently -hidden, make all subdirectories visible again. You can use this command -to get an overview in very deep directory trees or to move quickly to -subdirectories far away. -@end table - - Ordinary Dired commands never consider files inside a hidden -subdirectory. For example, the commands to operate on marked files -ignore files in hidden directories even if they are marked. Thus you -can use hiding to temporarily exclude subdirectories from operations -without having to remove the Dired marks on files in those -subdirectories. - -@xref{Subdirectories in Dired}, for how to insert a subdirectory -listing, and @pxref{Dired Updating} for how delete it. - -@node Dired Updating -@section Updating the Dired Buffer -@cindex updating Dired buffer -@cindex refreshing displayed files - - This section describes commands to update the Dired buffer to reflect -outside (non-Dired) changes in the directories and files, and to delete -part of the Dired buffer. - -@table @kbd -@item g -Update the entire contents of the Dired buffer (@code{revert-buffer}). - -@item l -Update the specified files (@code{dired-do-redisplay}). You specify the -files for @kbd{l} in the same way as for file operations. - -@item k -Delete the specified @emph{file lines}---not the files, just the lines -(@code{dired-do-kill-lines}). - -@item s -Toggle between alphabetical order and date/time order -(@code{dired-sort-toggle-or-edit}). - -@item C-u s @var{switches} @key{RET} -Refresh the Dired buffer using @var{switches} as -@code{dired-listing-switches}. -@end table - -@kindex g @r{(Dired)} -@findex revert-buffer @r{(Dired)} - Type @kbd{g} (@code{revert-buffer}) to update the contents of the -Dired buffer, based on changes in the files and directories listed. -This preserves all marks except for those on files that have vanished. -Hidden subdirectories are updated but remain hidden. - -@kindex l @r{(Dired)} -@findex dired-do-redisplay - To update only some of the files, type @kbd{l} -(@code{dired-do-redisplay}). Like the Dired file-operating commands, -this command operates on the next @var{n} files (or previous -@minus{}@var{n} files), or on the marked files if any, or on the -current file. Updating the files means reading their current status, -then updating their lines in the buffer to indicate that status. - - If you use @kbd{l} on a subdirectory header line, it updates the -contents of the corresponding subdirectory. - -@vindex dired-auto-revert-buffer - If you use @kbd{C-x d} or some other Dired command to visit a -directory that is already being shown in a Dired buffer, Dired -switches to that buffer but does not update it. If the buffer is not -up-to-date, Dired displays a warning telling you to type @key{g} to -update it. You can also tell Emacs to revert each Dired buffer -automatically when you revisit it, by setting the variable -@code{dired-auto-revert-buffer} to a non-@code{nil} value. - -@kindex k @r{(Dired)} -@findex dired-do-kill-lines - To delete @emph{file lines} from the buffer---without actually -deleting the files---type @kbd{k} (@code{dired-do-kill-lines}). Like -the file-operating commands, this command operates on the next @var{n} -files, or on the marked files if any. However, it does not operate on -the current file, since otherwise mistyping @kbd{k} could be annoying. - - If you use @kbd{k} to kill the line for a directory file which you -had inserted in the Dired buffer as a subdirectory -(@pxref{Subdirectories in Dired}), it removes the subdirectory listing -as well. Typing @kbd{C-u k} on the header line for a subdirectory -also removes the subdirectory line from the Dired buffer. - - The @kbd{g} command brings back any individual lines that you have -killed in this way, but not subdirectories---you must use @kbd{i} to -reinsert a subdirectory. - -@cindex Dired sorting -@cindex sorting Dired buffer -@kindex s @r{(Dired)} -@findex dired-sort-toggle-or-edit - The files in a Dired buffers are normally listed in alphabetical order -by file names. Alternatively Dired can sort them by date/time. The -Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches -between these two sorting modes. The mode line in a Dired buffer -indicates which way it is currently sorted---by name, or by date. - - @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for -@code{dired-listing-switches}. - -@node Dired and Find -@section Dired and @code{find} -@cindex @code{find} and Dired - - You can select a set of files for display in a Dired buffer more -flexibly by using the @command{find} utility to choose the files. - -@findex find-name-dired - To search for files with names matching a wildcard pattern use -@kbd{M-x find-name-dired}. It reads arguments @var{directory} and -@var{pattern}, and chooses all the files in @var{directory} or its -subdirectories whose individual names match @var{pattern}. - - The files thus chosen are displayed in a Dired buffer, in which the -ordinary Dired commands are available. - -@findex find-grep-dired - If you want to test the contents of files, rather than their names, -use @kbd{M-x find-grep-dired}. This command reads two minibuffer -arguments, @var{directory} and @var{regexp}; it chooses all the files -in @var{directory} or its subdirectories that contain a match for -@var{regexp}. It works by running the programs @command{find} and -@command{grep}. See also @kbd{M-x grep-find}, in @ref{Grep -Searching}. Remember to write the regular expression for -@command{grep}, not for Emacs. (An alternative method of showing -files whose contents match a given regexp is the @kbd{% g -@var{regexp}} command, see @ref{Marks vs Flags}.) - -@findex find-dired - The most general command in this series is @kbd{M-x find-dired}, -which lets you specify any condition that @command{find} can test. It -takes two minibuffer arguments, @var{directory} and @var{find-args}; -it runs @command{find} in @var{directory}, passing @var{find-args} to -tell @command{find} what condition to test. To use this command, you -need to know how to use @command{find}. - -@vindex find-ls-option - The format of listing produced by these commands is controlled by -the variable @code{find-ls-option}. This is a pair of options; the -first specifying how to call @command{find} to produce the file listing, -and the second telling Dired to parse the output. - -@findex locate -@findex locate-with-filter -@cindex file database (locate) -@vindex locate-command - The command @kbd{M-x locate} provides a similar interface to the -@command{locate} program. @kbd{M-x locate-with-filter} is similar, but -keeps only files whose names match a given regular expression. - - These buffers don't work entirely like ordinary Dired buffers: file -operations work, but do not always automatically update the buffer. -Reverting the buffer with @kbd{g} deletes all inserted subdirectories, -and erases all flags and marks. - -@node Wdired -@section Editing the Dired Buffer - -@cindex wdired mode -@findex wdired-change-to-wdired-mode - Wdired is a special mode that allows you to perform file operations -by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands -for ``writable''.) To enter Wdired mode, type @kbd{C-x C-q} -(@code{dired-toggle-read-only}) while in a Dired buffer. -Alternatively, use the @samp{Immediate / Edit File Names} menu item. - -@findex wdired-finish-edit - While in Wdired mode, you can rename files by editing the file names -displayed in the Dired buffer. All the ordinary Emacs editing -commands, including rectangle operations and @code{query-replace}, are -available for this. Once you are done editing, type @kbd{C-c C-c} -(@code{wdired-finish-edit}). This applies your changes and switches -back to ordinary Dired mode. - - Apart from simply renaming files, you can move a file to another -directory by typing in the new file name (either absolute or -relative). To mark a file for deletion, delete the entire file name. -To change the target of a symbolic link, edit the link target name -which appears next to the link name. - - The rest of the text in the buffer, such as the file sizes and -modification dates, is marked read-only, so you can't edit it. -However, if you set @code{wdired-allow-to-change-permissions} to -@code{t}, you can edit the file permissions. For example, you can -change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file -world-writable. These changes also take effect when you type @kbd{C-c -C-c}. - -@node Image-Dired -@section Viewing Image Thumbnails in Dired -@cindex image-dired mode -@cindex image-dired - - Image-Dired is a facility for browsing image files. It provides viewing -the images either as thumbnails or in full size, either inside Emacs -or through an external viewer. - -@kindex C-t d @r{(Image-Dired)} -@findex image-dired-display-thumbs - To enter Image-Dired, mark the image files you want to look at in -the Dired buffer, using @kbd{m} as usual. Then type @kbd{C-t d} -(@code{image-dired-display-thumbs}). This creates and switches to a -buffer containing image-dired, corresponding to the marked files. - - You can also enter Image-Dired directly by typing @kbd{M-x -image-dired}. This prompts for a directory; specify one that has -image files. This creates thumbnails for all the images in that -directory, and displays them all in the ``thumbnail buffer''. This -takes a long time if the directory contains many image files, and it -asks for confirmation if the number of image files exceeds -@code{image-dired-show-all-from-dir-max-files}. - - With point in the thumbnail buffer, you can type @key{RET} -(@code{image-dired-display-thumbnail-original-image}) to display a -sized version of it in another window. This sizes the image to fit -the window. Use the arrow keys to move around in the buffer. For -easy browsing, use @key{SPC} -(@code{image-dired-display-next-thumbnail-original}) to advance and -display the next image. Typing @key{DEL} -(@code{image-dired-display-previous-thumbnail-original}) backs up to -the previous thumbnail and displays that instead. - -@vindex image-dired-external-viewer - To view and the image in its original size, either provide a prefix -argument (@kbd{C-u}) before pressing @key{RET}, or type -@kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to -display the image in an external viewer. You must first configure -@code{image-dired-external-viewer}. - - You can delete images through Image-Dired also. Type @kbd{d} -(@code{image-dired-flag-thumb-original-file}) to flag the image file -for deletion in the Dired buffer. You can also delete the thumbnail -image from the thumbnail buffer with @kbd{C-d} -(@code{image-dired-delete-char}). - - More advanced features include @dfn{image tags}, which are metadata -used to categorize image files. The tags are stored in a plain text -file configured by @code{image-dired-db-file}. - - To tag image files, mark them in the dired buffer (you can also mark -files in Dired from the thumbnail buffer by typing @kbd{m}) and type -@kbd{C-t t} (@code{image-dired-tag-files}). This reads the tag name -in the minibuffer. To mark files having a certain tag, type @kbd{C-t f} -(@code{image-dired-mark-tagged-files}). After marking image files -with a certain tag, you can use @kbd{C-t d} to view them. - - You can also tag a file directly from the thumbnail buffer by typing -@kbd{t t} and you can remove a tag by typing @kbd{t r}. There is also -a special ``tag'' called ``comment'' for each file (it is not a tag in -the exact same sense as the other tags, it is handled slightly -different). That is used to enter a comment or description about the -image. You comment a file from the thumbnail buffer by typing -@kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add -a comment from Dired (@code{image-dired-dired-comment-files}). - - Image-Dired also provides simple image manipulation. In the -thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees -anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This -rotation is lossless, and uses an external utility called JpegTRAN. - -@node Misc Dired Features -@section Other Dired Features - -@kindex + @r{(Dired)} -@findex dired-create-directory - The command @kbd{+} (@code{dired-create-directory}) reads a -directory name, and creates that directory. It signals an error if -the directory already exists. - -@cindex searching multiple files via Dired -@kindex M-s a C-s @r{(Dired)} -@kindex M-s a M-C-s @r{(Dired)} -@findex dired-do-isearch -@findex dired-do-isearch-regexp - The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a -``multi-file'' incremental search on the marked files. If a search -fails at the end of a file, typing @kbd{C-s} advances to the next -marked file and repeats the search; at the end of the last marked -file, the search wraps around to the first marked file. The command -@kbd{M-s a M-C-s} (@code{dired-do-isearch-regexp}) does the same with -a regular expression search. @xref{Repeat Isearch}, for information -about search repetition. - -@cindex adding to the kill ring in Dired -@kindex w @r{(Dired)} -@findex dired-copy-filename-as-kill - The command @kbd{w} (@code{dired-copy-filename-as-kill}) puts the -names of the marked (or next @var{n}) files into the kill ring, as if -you had killed them with @kbd{C-w}. The names are separated by a -space. - - With a zero prefix argument, this uses the absolute file name of -each marked file. With just @kbd{C-u} as the prefix argument, it uses -file names relative to the Dired buffer's default directory. (This -can still contain slashes if in a subdirectory.) As a special case, -if point is on a directory headerline, @kbd{w} gives you the absolute -name of that directory. Any prefix argument or marked files are -ignored in this case. - - The main purpose of this command is so that you can yank the file -names into arguments for other Emacs commands. It also displays what -it added to the kill ring, so you can use it to display the list of -currently marked files in the echo area. - -@kindex ( @r{(Dired)} -@findex dired-hide-details-mode -@vindex dired-hide-details-hide-symlink-targets -@vindex dired-hide-details-hide-information-lines -@cindex hiding details in Dired - The command @kbd{(} (@code{dired-hide-details-mode}) toggles whether -details, such as ownership or file permissions, are visible in the -current Dired buffer. By default, it also hides the targets of -symbolic links, and all lines other than the header line and -file/directory listings. To change this, customize the options -@code{dired-hide-details-hide-symlink-targets} and -@code{dired-hide-details-hide-information-lines}, respectively. - -@cindex Dired and version control - If the directory you are visiting is under version control -(@pxref{Version Control}), then the normal VC diff and log commands -will operate on the selected files. - -@findex dired-compare-directories - The command @kbd{M-x dired-compare-directories} is used to compare -the current Dired buffer with another directory. It marks all the files -that are ``different'' between the two directories. It puts these marks -in all Dired buffers where these files are listed, which of course includes -the current buffer. - - The default comparison method (used if you type @key{RET} at the -prompt) is to compare just the file names---each file name that does -not appear in the other directory is ``different''. You can specify -more stringent comparisons by entering a Lisp expression, which can -refer to the variables @code{size1} and @code{size2}, the respective -file sizes; @code{mtime1} and @code{mtime2}, the last modification -times in seconds, as floating point numbers; and @code{fa1} and -@code{fa2}, the respective file attribute lists (as returned by the -function @code{file-attributes}). This expression is evaluated for -each pair of like-named files, and if the expression's value is -non-@code{nil}, those files are considered ``different''. - - For instance, the sequence @code{M-x dired-compare-directories -@key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this -directory than in the other, and marks files older in the other -directory than in this one. It also marks files with no counterpart, -in both directories, as always. - -@cindex drag and drop, Dired - On the X Window System, Emacs supports the ``drag and drop'' -protocol. You can drag a file object from another program, and drop -it onto a Dired buffer; this either moves, copies, or creates a link -to the file in that directory. Precisely which action is taken is -determined by the originating program. Dragging files out of a Dired -buffer is currently not supported. diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi deleted file mode 100644 index 0a77e722d32..00000000000 --- a/doc/emacs/display.texi +++ /dev/null @@ -1,1667 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. - -@c See file emacs.texi for copying conditions. -@node Display -@chapter Controlling the Display - - Since only part of a large buffer fits in the window, Emacs has to -show only a part of it. This chapter describes commands and variables -that let you specify which part of the text you want to see, and how -the text is displayed. - -@menu -* Scrolling:: Commands to move text up and down in a window. -* Recentering:: A scroll command that centers the current line. -* Auto Scrolling:: Redisplay scrolls text automatically when needed. -* Horizontal Scrolling:: Moving text left and right in a window. -* Narrowing:: Restricting display and editing to a portion - of the buffer. -* View Mode:: Viewing read-only buffers. -* Follow Mode:: Follow mode lets two windows scroll as one. -* Faces:: How to change the display style using faces. -* Colors:: Specifying colors for faces. -* Standard Faces:: The main predefined faces. -* Text Scale:: Increasing or decreasing text size in a buffer. -* Font Lock:: Minor mode for syntactic highlighting using faces. -* Highlight Interactively:: Tell Emacs what text to highlight. -* Fringes:: Enabling or disabling window fringes. -* Displaying Boundaries:: Displaying top and bottom of the buffer. -* Useless Whitespace:: Showing possibly spurious trailing whitespace. -* Selective Display:: Hiding lines with lots of indentation. -* Optional Mode Line:: Optional mode line display features. -* Text Display:: How text characters are normally displayed. -* Cursor Display:: Features for displaying the cursor. -* Line Truncation:: Truncating lines to fit the screen width instead - of continuing them to multiple screen lines. -* Visual Line Mode:: Word wrap and screen line-based editing. -* Display Custom:: Information on variables for customizing display. -@end menu - -@node Scrolling -@section Scrolling -@cindex scrolling - - If a window is too small to display all the text in its buffer, it -displays only a portion of it. @dfn{Scrolling} commands change which -portion of the buffer is displayed. - - Scrolling ``forward'' or ``up'' advances the portion of the buffer -displayed in the window; equivalently, it moves the buffer text -upwards relative to the window. Scrolling ``backward'' or ``down'' -displays an earlier portion of the buffer, and moves the text -downwards relative to the window. - - In Emacs, scrolling ``up'' or ``down'' refers to the direction that -the text moves in the window, @emph{not} the direction that the window -moves relative to the text. This terminology was adopted by Emacs -before the modern meaning of ``scrolling up'' and ``scrolling down'' -became widespread. Hence, the strange result that @key{PageDown} -scrolls ``up'' in the Emacs sense. - - The portion of a buffer displayed in a window always contains point. -If you move point past the bottom or top of the window, scrolling -occurs automatically to bring it back onscreen (@pxref{Auto -Scrolling}). You can also scroll explicitly with these commands: - -@table @kbd -@item C-v -@itemx @key{next} -@itemx @key{PageDown} -Scroll forward by nearly a full window (@code{scroll-up-command}). -@item M-v -@itemx @key{prior} -@itemx @key{PageUp} -Scroll backward (@code{scroll-down-command}). -@end table - -@kindex C-v -@kindex M-v -@kindex next -@kindex prior -@kindex PageDown -@kindex PageUp -@findex scroll-up-command -@findex scroll-down-command - @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the -whole window height. The effect is to take the two lines at the -bottom of the window and put them at the top, followed by lines that -were not previously visible. If point was in the text that scrolled -off the top, it ends up on the window's new topmost line. The -@key{next} (or @key{PageDown}) key is equivalent to @kbd{C-v}. - - @kbd{M-v} (@code{scroll-down-command}) scrolls backward in a similar -way. The @key{prior} (or @key{PageUp}) key is equivalent to -@kbd{M-v}. - -@vindex next-screen-context-lines - The number of lines of overlap left by these scroll commands is -controlled by the variable @code{next-screen-context-lines}, whose -default value is 2. You can supply the commands with a numeric prefix -argument, @var{n}, to scroll by @var{n} lines; Emacs attempts to leave -point unchanged, so that the text and point move up or down together. -@kbd{C-v} with a negative argument is like @kbd{M-v} and vice versa. - -@vindex scroll-error-top-bottom - By default, these commands signal an error (by beeping or flashing -the screen) if no more scrolling is possible, because the window has -reached the beginning or end of the buffer. If you change the -variable @code{scroll-error-top-bottom} to @code{t}, the command moves -point to the farthest possible position. If point is already there, -the command signals an error. - -@vindex scroll-preserve-screen-position -@cindex @code{scroll-command} property - Some users like scroll commands to keep point at the same screen -position, so that scrolling back to the same screen conveniently -returns point to its original position. You can enable this behavior -via the variable @code{scroll-preserve-screen-position}. If the value -is @code{t}, Emacs adjusts point to keep the cursor at the same screen -position whenever a scroll command moves it off-window, rather than -moving it to the topmost or bottommost line. With any other -non-@code{nil} value, Emacs adjusts point this way even if the scroll -command leaves point in the window. This variable affects all the -scroll commands documented in this section, as well as scrolling with -the mouse wheel (@pxref{Mouse Commands}); in general, it affects any -command that has a non-@code{nil} @code{scroll-command} property. -@xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}. - -@vindex scroll-up -@vindex scroll-down -@findex scroll-up-line -@findex scroll-down-line - The commands @kbd{M-x scroll-up} and @kbd{M-x scroll-down} behave -similarly to @code{scroll-up-command} and @code{scroll-down-command}, -except they do not obey @code{scroll-error-top-bottom}. Prior to -Emacs 24, these were the default commands for scrolling up and down. -The commands @kbd{M-x scroll-up-line} and @kbd{M-x scroll-down-line} -scroll the current window by one line at a time. If you intend to use -any of these commands, you might want to give them key bindings -(@pxref{Init Rebinding}). - -@node Recentering -@section Recentering - -@table @kbd -@item C-l -Scroll the selected window so the current line is the center-most text -line; on subsequent consecutive invocations, make the current line the -top line, the bottom line, and so on in cyclic order. Possibly -redisplay the screen too (@code{recenter-top-bottom}). - -@item M-x recenter -Scroll the selected window so the current line is the center-most text -line. Possibly redisplay the screen too. - -@item C-M-l -Scroll heuristically to bring useful information onto the screen -(@code{reposition-window}). -@end table - -@kindex C-l -@findex recenter-top-bottom - The @kbd{C-l} (@code{recenter-top-bottom}) command @dfn{recenters} -the selected window, scrolling it so that the current screen line is -exactly in the center of the window, or as close to the center as -possible. - - Typing @kbd{C-l} twice in a row (@kbd{C-l C-l}) scrolls the window -so that point is on the topmost screen line. Typing a third @kbd{C-l} -scrolls the window so that point is on the bottom-most screen line. -Each successive @kbd{C-l} cycles through these three positions. - -@vindex recenter-positions - You can change the cycling order by customizing the list variable -@code{recenter-positions}. Each list element should be the symbol -@code{top}, @code{middle}, or @code{bottom}, or a number; an integer -means to move the line to the specified screen line, while a -floating-point number between 0.0 and 1.0 specifies a percentage of -the screen space from the top of the window. The default, -@code{(middle top bottom)}, is the cycling order described above. -Furthermore, if you change the variable @code{scroll-margin} to a -non-zero value @var{n}, @kbd{C-l} always leaves at least @var{n} -screen lines between point and the top or bottom of the window -(@pxref{Auto Scrolling}). - - You can also give @kbd{C-l} a prefix argument. A plain prefix -argument, @kbd{C-u C-l}, simply recenters point. A positive argument -@var{n} puts point @var{n} lines down from the top of the window. An -argument of zero puts point on the topmost line. A negative argument -@var{-n} puts point @var{n} lines from the bottom of the window. When -given an argument, @kbd{C-l} does not clear the screen or cycle -through different screen positions. - -@vindex recenter-redisplay - If the variable @code{recenter-redisplay} has a non-@code{nil} -value, each invocation of @kbd{C-l} also clears and redisplays the -screen; the special value @code{tty} (the default) says to do this on -text-terminal frames only. Redisplaying is useful in case the screen -becomes garbled for any reason (@pxref{Screen Garbled}). - -@findex recenter - The more primitive command @kbd{M-x recenter} behaves like -@code{recenter-top-bottom}, but does not cycle among screen positions. - -@kindex C-M-l -@findex reposition-window - @kbd{C-M-l} (@code{reposition-window}) scrolls the current window -heuristically in a way designed to get useful information onto the -screen. For example, in a Lisp file, this command tries to get the -entire current defun onto the screen if possible. - -@node Auto Scrolling -@section Automatic Scrolling - -@cindex automatic scrolling - Emacs performs @dfn{automatic scrolling} when point moves out of the -visible portion of the text. Normally, automatic scrolling centers -point vertically in the window, but there are several ways to alter -this behavior. - -@vindex scroll-conservatively - If you set @code{scroll-conservatively} to a small number @var{n}, -then moving point just a little off the screen (no more than @var{n} -lines) causes Emacs to scroll just enough to bring point back on -screen; if doing so fails to make point visible, Emacs scrolls just -far enough to center point in the window. If you set -@code{scroll-conservatively} to a large number (larger than 100), -automatic scrolling never centers point, no matter how far point -moves; Emacs always scrolls text just enough to bring point into view, -either at the top or bottom of the window depending on the scroll -direction. By default, @code{scroll-conservatively} is@tie{}0, which -means to always center point in the window. - -@vindex scroll-step - Another way to control automatic scrolling is to customize the -variable @code{scroll-step}. Its value determines the number of lines -by which to automatically scroll, when point moves off the screen. If -scrolling by that number of lines fails to bring point back into view, -point is centered instead. The default value is zero, which (by -default) causes point to always be centered after scrolling. - -@cindex aggressive scrolling -@vindex scroll-up-aggressively -@vindex scroll-down-aggressively - A third way to control automatic scrolling is to customize the -variables @code{scroll-up-aggressively} and -@code{scroll-down-aggressively}, which directly specify the vertical -position of point after scrolling. The value of -@code{scroll-up-aggressively} should be either @code{nil} (the -default), or a floating point number @var{f} between 0 and 1. The -latter means that when point goes below the bottom window edge (i.e., -scrolling forward), Emacs scrolls the window so that point is @var{f} -parts of the window height from the bottom window edge. Thus, larger -@var{f} means more aggressive scrolling: more new text is brought into -view. The default value, @code{nil}, is equivalent to 0.5. - - Likewise, @code{scroll-down-aggressively} is used when point goes -above the bottom window edge (i.e., scrolling backward). The value -specifies how far point should be from the top margin of the window -after scrolling. Thus, as with @code{scroll-up-aggressively}, a -larger value is more aggressive. - - Note that the variables @code{scroll-conservatively}, -@code{scroll-step}, and @code{scroll-up-aggressively} / -@code{scroll-down-aggressively} control automatic scrolling in -contradictory ways. Therefore, you should pick no more than one of -these methods to customize automatic scrolling. In case you customize -multiple variables, the order of priority is: -@code{scroll-conservatively}, then @code{scroll-step}, and finally -@code{scroll-up-aggressively} / @code{scroll-down-aggressively}. - -@vindex scroll-margin - The variable @code{scroll-margin} restricts how close point can come -to the top or bottom of a window (even if aggressive scrolling -specifies a fraction @var{f} that is larger than the window portion -between the top and the bottom margins). Its value is a number of screen -lines; if point comes within that many lines of the top or bottom of -the window, Emacs performs automatic scrolling. By default, -@code{scroll-margin} is 0. - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - -@vindex auto-hscroll-mode - @dfn{Horizontal scrolling} means shifting all the lines sideways -within a window, so that some of the text near the left margin is not -displayed. When the text in a window is scrolled horizontally, text -lines are truncated rather than continued (@pxref{Line Truncation}). -If a window shows truncated lines, Emacs performs automatic horizontal -scrolling whenever point moves off the left or right edge of the -screen. To disable automatic horizontal scrolling, set the variable -@code{auto-hscroll-mode} to @code{nil}. Note that when the automatic -horizontal scrolling is turned off, if point moves off the edge of the -screen, the cursor disappears to indicate that. (On text terminals, -the cursor is left at the edge instead.) - -@vindex hscroll-margin - The variable @code{hscroll-margin} controls how close point can get -to the window's left and right edges before automatic scrolling -occurs. It is measured in columns. For example, if the value is 5, -then moving point within 5 columns of an edge causes horizontal -scrolling away from that edge. - -@vindex hscroll-step - The variable @code{hscroll-step} determines how many columns to -scroll the window when point gets too close to the edge. Zero, the -default value, means to center point horizontally within the window. -A positive integer value specifies the number of columns to scroll by. -A floating-point number specifies the fraction of the window's width -to scroll by. - - You can also perform explicit horizontal scrolling with the -following commands: - -@table @kbd -@item C-x < -Scroll text in current window to the left (@code{scroll-left}). -@item C-x > -Scroll to the right (@code{scroll-right}). -@end table - -@kindex C-x < -@kindex C-x > -@findex scroll-left -@findex scroll-right - @kbd{C-x <} (@code{scroll-left}) scrolls text in the selected window -to the left by the full width of the window, less two columns. (In -other words, the text in the window moves left relative to the -window.) With a numeric argument @var{n}, it scrolls by @var{n} -columns. - - If the text is scrolled to the left, and point moves off the left -edge of the window, the cursor will freeze at the left edge of the -window, until point moves back to the displayed portion of the text. -This is independent of the current setting of -@code{auto-hscroll-mode}, which, for text scrolled to the left, only -affects the behavior at the right edge of the window. - - @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. -The window cannot be scrolled any farther to the right once it is -displayed normally, with each line starting at the window's left -margin; attempting to do so has no effect. This means that you don't -have to calculate the argument precisely for @w{@kbd{C-x >}}; any -sufficiently large argument will restore the normal display. - - If you use those commands to scroll a window horizontally, that sets -a lower bound for automatic horizontal scrolling. Automatic scrolling -will continue to scroll the window, but never farther to the right -than the amount you previously set by @code{scroll-left}. - -@node Narrowing -@section Narrowing -@cindex widening -@cindex restriction -@cindex narrowing -@cindex accessible portion - - @dfn{Narrowing} means focusing in on some portion of the buffer, -making the rest temporarily inaccessible. The portion which you can -still get to is called the @dfn{accessible portion}. Canceling the -narrowing, which makes the entire buffer once again accessible, is -called @dfn{widening}. The bounds of narrowing in effect in a buffer -are called the buffer's @dfn{restriction}. - - Narrowing can make it easier to concentrate on a single subroutine or -paragraph by eliminating clutter. It can also be used to limit the -range of operation of a replace command or repeating keyboard macro. - -@table @kbd -@item C-x n n -Narrow down to between point and mark (@code{narrow-to-region}). -@item C-x n w -Widen to make the entire buffer accessible again (@code{widen}). -@item C-x n p -Narrow down to the current page (@code{narrow-to-page}). -@item C-x n d -Narrow down to the current defun (@code{narrow-to-defun}). -@end table - - When you have narrowed down to a part of the buffer, that part appears -to be all there is. You can't see the rest, you can't move into it -(motion commands won't go outside the accessible part), you can't change -it in any way. However, it is not gone, and if you save the file all -the inaccessible text will be saved. The word @samp{Narrow} appears in -the mode line whenever narrowing is in effect. - -@kindex C-x n n -@findex narrow-to-region - The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}). -It sets the current buffer's restrictions so that the text in the current -region remains accessible, but all text before the region or after the -region is inaccessible. Point and mark do not change. - -@kindex C-x n p -@findex narrow-to-page -@kindex C-x n d -@findex narrow-to-defun - Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow -down to the current page. @xref{Pages}, for the definition of a page. -@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun -containing point (@pxref{Defuns}). - -@kindex C-x n w -@findex widen - The way to cancel narrowing is to widen with @kbd{C-x n w} -(@code{widen}). This makes all text in the buffer accessible again. - - You can get information on what part of the buffer you are narrowed down -to using the @kbd{C-x =} command. @xref{Position Info}. - - Because narrowing can easily confuse users who do not understand it, -@code{narrow-to-region} is normally a disabled command. Attempting to use -this command asks for confirmation and gives you the option of enabling it; -if you enable the command, confirmation will no longer be required for -it. @xref{Disabling}. - -@node View Mode -@section View Mode -@cindex View mode -@cindex mode, View - -@kindex s @r{(View mode)} -@kindex SPC @r{(View mode)} -@kindex DEL @r{(View mode)} - View mode is a minor mode that lets you scan a buffer by sequential -screenfuls. It provides commands for scrolling through the buffer -conveniently but not for changing it. Apart from the usual Emacs -cursor motion commands, you can type @key{SPC} to scroll forward one -windowful, @key{S-@key{SPC}} or @key{DEL} to scroll backward, and @kbd{s} to -start an incremental search. - -@kindex q @r{(View mode)} -@kindex e @r{(View mode)} -@findex View-quit -@findex View-exit - Typing @kbd{q} (@code{View-quit}) disables View mode, and switches -back to the buffer and position before View mode was enabled. Typing -@kbd{e} (@code{View-exit}) disables View mode, keeping the current -buffer and position. - -@findex view-buffer -@findex view-file - @kbd{M-x view-buffer} prompts for an existing Emacs buffer, switches -to it, and enables View mode. @kbd{M-x view-file} prompts for a file -and visits it with View mode enabled. - -@node Follow Mode -@section Follow Mode -@cindex Follow mode -@cindex mode, Follow -@findex follow-mode -@cindex windows, synchronizing -@cindex synchronizing windows - - @dfn{Follow mode} is a minor mode that makes two windows, both -showing the same buffer, scroll as a single tall ``virtual window''. -To use Follow mode, go to a frame with just one window, split it into -two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x -follow-mode}. From then on, you can edit the buffer in either of the -two windows, or scroll either one; the other window follows it. - - In Follow mode, if you move point outside the portion visible in one -window and into the portion visible in the other window, that selects -the other window---again, treating the two as if they were parts of -one large window. - - To turn off Follow mode, type @kbd{M-x follow-mode} a second time. - -@node Faces -@section Text Faces -@cindex faces - - Emacs can display text in several different styles, called -@dfn{faces}. Each face can specify various @dfn{face attributes}, -such as the font, height, weight, slant, foreground and background -color, and underlining or overlining. Most major modes assign faces -to the text automatically, via Font Lock mode. @xref{Font Lock}, for -more information about how these faces are assigned. - -@findex list-faces-display - To see what faces are currently defined, and what they look like, -type @kbd{M-x list-faces-display}. With a prefix argument, this -prompts for a regular expression, and displays only faces with names -matching that regular expression (@pxref{Regexps}). - -@vindex frame-background-mode - It's possible for a given face to look different in different -frames. For instance, some text terminals do not support all face -attributes, particularly font, height, and width, and some support a -limited range of colors. In addition, most Emacs faces are defined so -that their attributes are different on light and dark frame -backgrounds, for reasons of legibility. By default, Emacs -automatically chooses which set of face attributes to display on each -frame, based on the frame's current background color. However, you -can override this by giving the variable @code{frame-background-mode} -a non-@code{nil} value. A value of @code{dark} makes Emacs treat all -frames as if they have a dark background, whereas a value of -@code{light} makes it treat all frames as if they have a light -background. - -@cindex background color -@cindex default face - You can customize a face to alter its attributes, and save those -customizations for future Emacs sessions. @xref{Face Customization}, -for details. - - The @code{default} face is the default for displaying text, and all -of its attributes are specified. Its background color is also used as -the frame's background color. @xref{Colors}. - -@cindex cursor face - Another special face is the @code{cursor} face. On graphical -displays, the background color of this face is used to draw the text -cursor. None of the other attributes of this face have any effect; -the foreground color for text under the cursor is taken from the -background color of the underlying text. On text terminals, the -appearance of the text cursor is determined by the terminal, not by -the @code{cursor} face. - - You can also use X resources to specify attributes of any particular -face. @xref{Resources}. - - Emacs can display variable-width fonts, but some Emacs commands, -particularly indentation commands, do not account for variable -character display widths. Therefore, we recommend not using -variable-width fonts for most faces, particularly those assigned by -Font Lock mode. - -@node Colors -@section Colors for Faces -@cindex color name -@cindex RGB triplet - - Faces can have various foreground and background colors. When you -specify a color for a face---for instance, when customizing the face -(@pxref{Face Customization})---you can use either a @dfn{color name} -or an @dfn{RGB triplet}. - -@findex list-colors-display -@vindex list-colors-sort - A color name is a pre-defined name, such as @samp{dark orange} or -@samp{medium sea green}. To view a list of color names, type @kbd{M-x -list-colors-display}. To control the order in which colors are shown, -customize @code{list-colors-sort}. If you run this command on a -graphical display, it shows the full range of color names known to -Emacs (these are the standard X11 color names, defined in X's -@file{rgb.txt} file). If you run the command on a text terminal, it -shows only a small subset of colors that can be safely displayed on -such terminals. However, Emacs understands X11 color names even on -text terminals; if a face is given a color specified by an X11 color -name, it is displayed using the closest-matching terminal color. - - An RGB triplet is a string of the form @samp{#RRGGBB}. Each of the -R, G, and B components is a hexadecimal number specifying the -component's relative intensity, one to four digits long (usually two -digits are used). The components must have the same number of digits. -For hexadecimal values A to F, either upper or lower case are -acceptable. - - The @kbd{M-x list-colors-display} command also shows the equivalent -RGB triplet for each named color. For instance, @samp{medium sea -green} is equivalent to @samp{#3CB371}. - -@cindex face colors, setting -@findex set-face-foreground -@findex set-face-background - You can change the foreground and background colors of a face with -@kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}. -These commands prompt in the minibuffer for a face name and a color, -with completion, and then set that face to use the specified color. -They affect the face colors on all frames, but their effects do not -persist for future Emacs sessions, unlike using the customization -buffer or X resources. You can also use frame parameters to set -foreground and background colors for a specific frame; @xref{Frame -Parameters}. - -@node Standard Faces -@section Standard Faces - - Here are the standard faces for specifying text appearance. You can -apply them to specific text when you want the effects they produce. - -@table @code -@item default -This face is used for ordinary text that doesn't specify any face. -Its background color is used as the frame's background color. -@item bold -This face uses a bold variant of the default font. -@item italic -This face uses an italic variant of the default font. -@item bold-italic -This face uses a bold italic variant of the default font. -@item underline -This face underlines text. -@item fixed-pitch -This face forces use of a fixed-width font. It's reasonable to -customize this face to use a different fixed-width font, if you like, -but you should not make it a variable-width font. -@item variable-pitch -This face forces use of a variable-width font. -@item shadow -This face is used for making the text less noticeable than the surrounding -ordinary text. Usually this can be achieved by using shades of gray in -contrast with either black or white default foreground color. -@end table - - Here's an incomplete list of faces used to highlight parts of the -text temporarily for specific purposes. (Many other modes define -their own faces for this purpose.) - -@table @code -@item highlight -This face is used for text highlighting in various contexts, such as -when the mouse cursor is moved over a hyperlink. -@item isearch -This face is used to highlight the current Isearch match -(@pxref{Incremental Search}). -@item query-replace -This face is used to highlight the current Query Replace match -(@pxref{Replace}). -@item lazy-highlight -This face is used to highlight ``lazy matches'' for Isearch and Query -Replace (matches other than the current one). -@item region -This face is used for displaying an active region (@pxref{Mark}). -When Emacs is built with GTK support, its colors are taken from the -current GTK theme. -@item secondary-selection -This face is used for displaying a secondary X selection (@pxref{Secondary -Selection}). -@item trailing-whitespace -The face for highlighting excess spaces and tabs at the end of a line -when @code{show-trailing-whitespace} is non-@code{nil} (@pxref{Useless -Whitespace}). -@item escape-glyph -The face for displaying control characters and escape sequences -(@pxref{Text Display}). -@item nobreak-space -The face for displaying ``no-break'' space characters (@pxref{Text -Display}). -@end table - - The following faces control the appearance of parts of the Emacs -frame: - -@table @code -@item mode-line -This face is used for the mode line of the currently selected window, -and for menu bars when toolkit menus are not used. By default, it's -drawn with shadows for a ``raised'' effect on graphical displays, and -drawn as the inverse of the default face on non-windowed terminals. -@item mode-line-inactive -Like @code{mode-line}, but used for mode lines of the windows other -than the selected one (if @code{mode-line-in-non-selected-windows} is -non-@code{nil}). This face inherits from @code{mode-line}, so changes -in that face affect mode lines in all windows. -@item mode-line-highlight -Like @code{highlight}, but used for portions of text on mode lines. -@item mode-line-buffer-id -This face is used for buffer identification parts in the mode line. -@item header-line -Similar to @code{mode-line} for a window's header line, which appears -at the top of a window just as the mode line appears at the bottom. -Most windows do not have a header line---only some special modes, such -Info mode, create one. -@item vertical-border -This face is used for the vertical divider between windows on text -terminals. -@item minibuffer-prompt -@cindex @code{minibuffer-prompt} face -@vindex minibuffer-prompt-properties -This face is used for the prompt strings displayed in the minibuffer. -By default, Emacs automatically adds this face to the value of -@code{minibuffer-prompt-properties}, which is a list of text -properties used to display the prompt text. (This variable takes -effect when you enter the minibuffer.) -@item fringe -@cindex @code{fringe} face -The face for the fringes to the left and right of windows on graphic -displays. (The fringes are the narrow portions of the Emacs frame -between the text area and the window's right and left borders.) -@xref{Fringes}. -@item cursor -The @code{:background} attribute of this face specifies the color of -the text cursor. @xref{Cursor Display}. -@item tooltip -This face is used for tooltip text. By default, if Emacs is built -with GTK support, tooltips are drawn via GTK and this face has no -effect. @xref{Tooltips}. -@item mouse -This face determines the color of the mouse pointer. -@end table - - The following faces likewise control the appearance of parts of the -Emacs frame, but only on text terminals, or when Emacs is built on X -with no toolkit support. (For all other cases, the appearance of the -respective frame elements is determined by system-wide settings.) - -@table @code -@item scroll-bar -This face determines the visual appearance of the scroll bar. -@xref{Scroll Bars}. -@item tool-bar -This face determines the color of tool bar icons. @xref{Tool Bars}. -@item menu -@cindex menu bar appearance -@cindex @code{menu} face, no effect if customized -@cindex customization of @code{menu} face -This face determines the colors and font of Emacs's menus. @xref{Menu -Bars}. -@item tty-menu-enabled-face -@cindex faces for text-mode menus -@cindex TTY menu faces -This face is used to display enabled menu items on text-mode -terminals. -@item tty-menu-disabled-face -This face is used to display disabled menu items on text-mode -terminals. -@item tty-menu-selected-face -This face is used to display on text-mode terminals the menu item that -would be selected if you click a mouse or press @key{RET}. -@end table - -@node Text Scale -@section Text Scale - -@cindex adjust buffer face height -@findex text-scale-adjust -@kindex C-x C-+ -@kindex C-x C-- -@kindex C-x C-= -@kindex C-x C-0 - To increase the height of the default face in the current buffer, -type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type @kbd{C-x -C--}. To restore the default (global) face height, type @kbd{C-x -C-0}. These keys are all bound to the same command, -@code{text-scale-adjust}, which looks at the last key typed to -determine which action to take. - - The final key of these commands may be repeated without the leading -@kbd{C-x}. For instance, @kbd{C-x C-= C-= C-=} increases the face -height by three steps. Each step scales the text height by a factor -of 1.2; to change this factor, customize the variable -@code{text-scale-mode-step}. A numeric argument of 0 -to the @code{text-scale-adjust} command restores the default height, -the same as typing @kbd{C-x C-0}. - -@cindex increase buffer face height -@findex text-scale-increase -@cindex decrease buffer face height -@findex text-scale-decrease - The commands @code{text-scale-increase} and -@code{text-scale-decrease} increase or decrease the height of the -default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively. -You may find it convenient to bind to these commands, rather than -@code{text-scale-adjust}. - -@cindex set buffer face height -@findex text-scale-set - The command @code{text-scale-set} scales the height of the default -face in the current buffer to an absolute level specified by its -prefix argument. - -@findex text-scale-mode - The above commands automatically enable the minor mode -@code{text-scale-mode} if the current font scaling is other than 1, -and disable it otherwise. - -@node Font Lock -@section Font Lock mode -@cindex Font Lock mode -@cindex mode, Font Lock -@cindex syntax highlighting and coloring - - Font Lock mode is a minor mode, always local to a particular buffer, -which assigns faces to (or @dfn{fontifies}) the text in the buffer. -Each buffer's major mode tells Font Lock mode which text to fontify; -for instance, programming language modes fontify syntactically -relevant constructs like comments, strings, and function names. - -@findex font-lock-mode - Font Lock mode is enabled by default. To toggle it in the current -buffer, type @kbd{M-x font-lock-mode}. A positive numeric argument -unconditionally enables Font Lock mode, and a negative or zero -argument disables it. - -@findex global-font-lock-mode -@vindex global-font-lock-mode - Type @kbd{M-x global-font-lock-mode} to toggle Font Lock mode in all -buffers. To impose this setting for future Emacs sessions, customize -the variable @code{global-font-lock-mode} (@pxref{Easy -Customization}), or add the following line to your init file: - -@example -(global-font-lock-mode 0) -@end example - -@noindent -If you have disabled Global Font Lock mode, you can still enable Font -Lock for specific major modes by adding the function -@code{font-lock-mode} to the mode hooks (@pxref{Hooks}). For example, -to enable Font Lock mode for editing C files, you can do this: - -@example -(add-hook 'c-mode-hook 'font-lock-mode) -@end example - - Font Lock mode uses several specifically named faces to do its job, -including @code{font-lock-string-face}, @code{font-lock-comment-face}, -and others. The easiest way to find them all is to use @kbd{M-x -customize-group @key{RET} font-lock-faces @key{RET}}. You can then -use that customization buffer to customize the appearance of these -faces. @xref{Face Customization}. - -@vindex font-lock-maximum-decoration - You can customize the variable @code{font-lock-maximum-decoration} -to alter the amount of fontification applied by Font Lock mode, for -major modes that support this feature. The value should be a number -(with 1 representing a minimal amount of fontification; some modes -support levels as high as 3); or @code{t}, meaning ``as high as -possible'' (the default). You can also specify different numbers for -particular major modes; for example, to use level 1 for C/C++ modes, -and the default level otherwise, use the value - -@example -'((c-mode . 1) (c++-mode . 1))) -@end example - -@vindex font-lock-beginning-of-syntax-function -@cindex incorrect fontification -@cindex parenthesis in column zero and fontification -@cindex brace in column zero and fontification - Comment and string fontification (or ``syntactic'' fontification) -relies on analysis of the syntactic structure of the buffer text. For -the sake of speed, some modes, including Lisp mode, rely on a special -convention: an open-parenthesis or open-brace in the leftmost column -always defines the beginning of a defun, and is thus always outside -any string or comment. Therefore, you should avoid placing an -open-parenthesis or open-brace in the leftmost column, if it is inside -a string or comment. @xref{Left Margin Paren}, for details. - -@cindex slow display during scrolling - The variable @code{font-lock-beginning-of-syntax-function}, which is -always buffer-local, specifies how Font Lock mode can find a position -guaranteed to be outside any comment or string. In modes which use -the leftmost column parenthesis convention, the default value of the -variable is @code{beginning-of-defun}---that tells Font Lock mode to -use the convention. If you set this variable to @code{nil}, Font Lock -no longer relies on the convention. This avoids incorrect results, -but the price is that, in some cases, fontification for a changed text -must rescan buffer text from the beginning of the buffer. This can -considerably slow down redisplay while scrolling, particularly if you -are close to the end of a large buffer. - -@findex font-lock-add-keywords - Font Lock highlighting patterns already exist for most modes, but -you may want to fontify additional patterns. You can use the function -@code{font-lock-add-keywords}, to add your own highlighting patterns -for a particular mode. For example, to highlight @samp{FIXME:} words -in C comments, use this: - -@example -(add-hook 'c-mode-hook - (lambda () - (font-lock-add-keywords nil - '(("\\<\\(FIXME\\):" 1 - font-lock-warning-face t))))) -@end example - -@findex font-lock-remove-keywords -@noindent -To remove keywords from the font-lock highlighting patterns, use the -function @code{font-lock-remove-keywords}. @xref{Search-based -Fontification,,, elisp, The Emacs Lisp Reference Manual}. - -@cindex just-in-time (JIT) font-lock -@cindex background syntax highlighting - Fontifying large buffers can take a long time. To avoid large -delays when a file is visited, Emacs initially fontifies only the -visible portion of a buffer. As you scroll through the buffer, each -portion that becomes visible is fontified as soon as it is displayed; -this type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT}) -Lock. You can control how JIT Lock behaves, including telling it to -perform fontification while idle, by customizing variables in the -customization group @samp{jit-lock}. @xref{Specific Customization}. - -@node Highlight Interactively -@section Interactive Highlighting -@cindex highlighting by matching -@cindex interactive highlighting -@cindex Highlight Changes mode - -@findex highlight-changes-mode -Highlight Changes mode is a minor mode that @dfn{highlights} the parts -of the buffer that were changed most recently, by giving that text a -different face. To enable or disable Highlight Changes mode, use -@kbd{M-x highlight-changes-mode}. - -@cindex Hi Lock mode -@findex hi-lock-mode - Hi Lock mode is a minor mode that highlights text that matches -regular expressions you specify. For example, you can use it to -highlight all the references to a certain variable in a program source -file, highlight certain parts in a voluminous output of some program, -or highlight certain names in an article. To enable or disable Hi -Lock mode, use the command @kbd{M-x hi-lock-mode}. To enable Hi Lock -mode for all buffers, use @kbd{M-x global-hi-lock-mode} or place -@code{(global-hi-lock-mode 1)} in your @file{.emacs} file. - - Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except -that you specify explicitly the regular expressions to highlight. You -control them with these commands: - -@table @kbd -@item M-s h r @var{regexp} @key{RET} @var{face} @key{RET} -@itemx C-x w h @var{regexp} @key{RET} @var{face} @key{RET} -@kindex M-s h r -@kindex C-x w h -@findex highlight-regexp -Highlight text that matches @var{regexp} using face @var{face} -(@code{highlight-regexp}). The highlighting will remain as long as -the buffer is loaded. For example, to highlight all occurrences of -the word ``whim'' using the default face (a yellow background) -@kbd{M-s h r whim @key{RET} @key{RET}}. Any face can be used for -highlighting, Hi Lock provides several of its own and these are -pre-loaded into a list of default values. While being prompted -for a face use @kbd{M-n} and @kbd{M-p} to cycle through them. - -@vindex hi-lock-auto-select-face -Setting the option @code{hi-lock-auto-select-face} to a non-@code{nil} -value causes this command (and other Hi Lock commands that read faces) -to automatically choose the next face from the default list without -prompting. - -You can use this command multiple times, specifying various regular -expressions to highlight in different ways. - -@item M-s h u @var{regexp} @key{RET} -@itemx C-x w r @var{regexp} @key{RET} -@kindex M-s h u -@kindex C-x w r -@findex unhighlight-regexp -Unhighlight @var{regexp} (@code{unhighlight-regexp}). - -If you invoke this from the menu, you select the expression to -unhighlight from a list. If you invoke this from the keyboard, you -use the minibuffer. It will show the most recently added regular -expression; use @kbd{M-n} to show the next older expression and -@kbd{M-p} to select the next newer expression. (You can also type the -expression by hand, with completion.) When the expression you want to -unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit -the minibuffer and unhighlight it. - -@item M-s h l @var{regexp} @key{RET} @var{face} @key{RET} -@itemx C-x w l @var{regexp} @key{RET} @var{face} @key{RET} -@kindex M-s h l -@kindex C-x w l -@findex highlight-lines-matching-regexp -@cindex lines, highlighting -@cindex highlighting lines of text -Highlight entire lines containing a match for @var{regexp}, using face -@var{face} (@code{highlight-lines-matching-regexp}). - -@item M-s h p @var{phrase} @key{RET} @var{face} @key{RET} -@itemx C-x w p @var{phrase} @key{RET} @var{face} @key{RET} -@kindex M-s h p -@kindex C-x w p -@findex highlight-phrase -@cindex phrase, highlighting -@cindex highlighting phrase -Highlight matches of @var{phrase}, using face @var{face} -(@code{highlight-phrase}). @var{phrase} can be any regexp, -but spaces will be replaced by matches to whitespace and -initial lower-case letters will become case insensitive. - -@item M-s h . -@itemx C-x w . -@kindex M-s h . -@kindex C-x w . -@findex highlight-symbol-at-point -@cindex symbol, highlighting -@cindex highlighting symbol at point -Highlight the symbol found near point, using the next available face -(@code{highlight-symbol-at-point}). - -@item M-s h w -@itemx C-x w b -@kindex M-s h w -@kindex C-x w b -@findex hi-lock-write-interactive-patterns -Insert all the current highlighting regexp/face pairs into the buffer -at point, with comment delimiters to prevent them from changing your -program. (This key binding runs the -@code{hi-lock-write-interactive-patterns} command.) - -These patterns are extracted from the comments, if appropriate, if you -invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while -Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}). - -@item M-s h f -@itemx C-x w i -@kindex M-s h f -@kindex C-x w i -@findex hi-lock-find-patterns -Extract regexp/face pairs from comments in the current buffer -(@code{hi-lock-find-patterns}). Thus, you can enter patterns -interactively with @code{highlight-regexp}, store them into the file -with @code{hi-lock-write-interactive-patterns}, edit them (perhaps -including different faces for different parenthesized parts of the -match), and finally use this command (@code{hi-lock-find-patterns}) to -have Hi Lock highlight the edited patterns. - -@vindex hi-lock-file-patterns-policy -The variable @code{hi-lock-file-patterns-policy} controls whether Hi -Lock mode should automatically extract and highlight patterns found in a -file when it is visited. Its value can be @code{nil} (never highlight), -@code{ask} (query the user), or a function. If it is a function, -@code{hi-lock-find-patterns} calls it with the patterns as argument; if -the function returns non-@code{nil}, the patterns are used. The default -is @code{ask}. Note that patterns are always highlighted if you call -@code{hi-lock-find-patterns} directly, regardless of the value of this -variable. - -@vindex hi-lock-exclude-modes -Also, @code{hi-lock-find-patterns} does nothing if the current major -mode's symbol is a member of the list @code{hi-lock-exclude-modes}. -@end table - -@node Fringes -@section Window Fringes -@cindex fringes - -@findex set-fringe-style -@findex fringe-mode -@vindex fringe-mode @r{(variable)} - On graphical displays, each Emacs window normally has narrow -@dfn{fringes} on the left and right edges. The fringes are used to -display symbols that provide information about the text in the window. -You can type @kbd{M-x fringe-mode} to disable the fringes, or modify -their width. This command affects fringes in all frames; to modify -fringes on the selected frame only, use @kbd{M-x set-fringe-style}. -You can make your changes to the fringes permanent by customizing the -variable @code{fringe-mode}. - - The most common use of the fringes is to indicate a continuation -line (@pxref{Continuation Lines}). When one line of text is split -into multiple screen lines, the left fringe shows a curving arrow for -each screen line except the first, indicating that ``this is not the -real beginning''. The right fringe shows a curving arrow for each -screen line except the last, indicating that ``this is not the real -end''. If the line's direction is right-to-left (@pxref{Bidirectional -Editing}), the meanings of the curving arrows in the fringes are -swapped. - - The fringes indicate line truncation with short horizontal arrows -meaning ``there's more text on this line which is scrolled -horizontally out of view''. Clicking the mouse on one of the arrows -scrolls the display horizontally in the direction of the arrow. - - The fringes can also indicate other things, such as buffer -boundaries (@pxref{Displaying Boundaries}), and where a program you -are debugging is executing (@pxref{Debuggers}). - -@vindex overflow-newline-into-fringe - The fringe is also used for drawing the cursor, if the current line -is exactly as wide as the window and point is at the end of the line. -To disable this, change the variable -@code{overflow-newline-into-fringe} to @code{nil}; this causes Emacs -to continue or truncate lines that are exactly as wide as the window. - -@node Displaying Boundaries -@section Displaying Boundaries - -@vindex indicate-buffer-boundaries - On graphical displays, Emacs can indicate the buffer boundaries in -the fringes. If you enable this feature, the first line and the last -line are marked with angle images in the fringes. This can be -combined with up and down arrow images which say whether it is -possible to scroll the window. - - The buffer-local variable @code{indicate-buffer-boundaries} controls -how the buffer boundaries and window scrolling is indicated in the -fringes. If the value is @code{left} or @code{right}, both angle and -arrow bitmaps are displayed in the left or right fringe, respectively. - - If value is an alist, each element @code{(@var{indicator} . -@var{position})} specifies the position of one of the indicators. -The @var{indicator} must be one of @code{top}, @code{bottom}, -@code{up}, @code{down}, or @code{t} which specifies the default -position for the indicators not present in the alist. -The @var{position} is one of @code{left}, @code{right}, or @code{nil} -which specifies not to show this indicator. - - For example, @code{((top . left) (t . right))} places the top angle -bitmap in left fringe, the bottom angle bitmap in right fringe, and -both arrow bitmaps in right fringe. To show just the angle bitmaps in -the left fringe, but no arrow bitmaps, use @code{((top . left) -(bottom . left))}. - -@node Useless Whitespace -@section Useless Whitespace - -@cindex trailing whitespace -@cindex whitespace, trailing -@vindex show-trailing-whitespace - It is easy to leave unnecessary spaces at the end of a line, or -empty lines at the end of a buffer, without realizing it. In most -cases, this @dfn{trailing whitespace} has no effect, but sometimes it -can be a nuisance. - - You can make trailing whitespace at the end of a line visible by -setting the buffer-local variable @code{show-trailing-whitespace} to -@code{t}. Then Emacs displays trailing whitespace, using the face -@code{trailing-whitespace}. - - This feature does not apply when point is at the end of the line -containing the whitespace. Strictly speaking, that is ``trailing -whitespace'' nonetheless, but displaying it specially in that case -looks ugly while you are typing in new text. In this special case, -the location of point is enough to show you that the spaces are -present. - -@findex delete-trailing-whitespace -@vindex delete-trailing-lines - Type @kbd{M-x delete-trailing-whitespace} to delete all trailing -whitespace. This command deletes all extra spaces at the end of each -line in the buffer, and all empty lines at the end of the buffer; to -ignore the latter, change the variable @code{delete-trailing-lines} to -@code{nil}. If the region is active, the command instead deletes -extra spaces at the end of each line in the region. - -@vindex indicate-empty-lines -@cindex unused lines -@cindex fringes, and unused line indication - On graphical displays, Emacs can indicate unused lines at the end of -the window with a small image in the left fringe (@pxref{Fringes}). -The image appears for screen lines that do not correspond to any -buffer text, so blank lines at the end of the buffer stand out because -they lack this image. To enable this feature, set the buffer-local -variable @code{indicate-empty-lines} to a non-@code{nil} value. You -can enable or disable this feature for all new buffers by setting the -default value of this variable, e.g., @code{(setq-default -indicate-empty-lines t)}. - -@cindex Whitespace mode -@cindex mode, Whitespace -@findex whitespace-mode -@vindex whitespace-style - Whitespace mode is a buffer-local minor mode that lets you -``visualize'' many kinds of whitespace in the buffer, by either -drawing the whitespace characters with a special face or displaying -them as special glyphs. To toggle this mode, type @kbd{M-x -whitespace-mode}. The kinds of whitespace visualized are determined -by the list variable @code{whitespace-style}. Here is a partial list -of possible elements (see the variable's documentation for the full -list): - -@table @code -@item face -Enable all visualizations which use special faces. This element has a -special meaning: if it is absent from the list, none of the other -visualizations take effect except @code{space-mark}, @code{tab-mark}, -and @code{newline-mark}. - -@item trailing -Highlight trailing whitespace. - -@item tabs -Highlight tab characters. - -@item spaces -Highlight space and non-breaking space characters. - -@item lines -@vindex whitespace-line-column -Highlight lines longer than 80 lines. To change the column limit, -customize the variable @code{whitespace-line-column}. - -@item newline -Highlight newlines. - -@item empty -Highlight empty lines. - -@item space-mark -Draw space and non-breaking characters with a special glyph. - -@item tab-mark -Draw tab characters with a special glyph. - -@item newline-mark -Draw newline characters with a special glyph. -@end table - -@node Selective Display -@section Selective Display -@cindex selective display -@findex set-selective-display -@kindex C-x $ - - Emacs has the ability to hide lines indented more than a given -number of columns. You can use this to get an overview of a part of a -program. - - To hide lines in the current buffer, type @kbd{C-x $} -(@code{set-selective-display}) with a numeric argument @var{n}. Then -lines with at least @var{n} columns of indentation disappear from the -screen. The only indication of their presence is that three dots -(@samp{@dots{}}) appear at the end of each visible line that is -followed by one or more hidden ones. - - The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as -if they were not there. - - The hidden lines are still present in the buffer, and most editing -commands see them as usual, so you may find point in the middle of the -hidden text. When this happens, the cursor appears at the end of the -previous line, after the three dots. If point is at the end of the -visible line, before the newline that ends it, the cursor appears before -the three dots. - - To make all lines visible again, type @kbd{C-x $} with no argument. - -@vindex selective-display-ellipses - If you set the variable @code{selective-display-ellipses} to -@code{nil}, the three dots do not appear at the end of a line that -precedes hidden lines. Then there is no visible indication of the -hidden lines. This variable becomes local automatically when set. - - See also @ref{Outline Mode} for another way to hide part of -the text in a buffer. - -@node Optional Mode Line -@section Optional Mode Line Features - -@cindex buffer size display -@cindex display of buffer size -@findex size-indication-mode - The buffer percentage @var{pos} indicates the percentage of the -buffer above the top of the window. You can additionally display the -size of the buffer by typing @kbd{M-x size-indication-mode} to turn on -Size Indication mode. The size will be displayed immediately -following the buffer percentage like this: - -@example -@var{pos} of @var{size} -@end example - -@noindent -Here @var{size} is the human readable representation of the number of -characters in the buffer, which means that @samp{k} for 10^3, @samp{M} -for 10^6, @samp{G} for 10^9, etc., are used to abbreviate. - -@cindex line number display -@cindex display of line number -@findex line-number-mode - The current line number of point appears in the mode line when Line -Number mode is enabled. Use the command @kbd{M-x line-number-mode} to -turn this mode on and off; normally it is on. The line number appears -after the buffer percentage @var{pos}, with the letter @samp{L} to -indicate what it is. - -@cindex Column Number mode -@cindex mode, Column Number -@findex column-number-mode - Similarly, you can display the current column number by turning on -Column number mode with @kbd{M-x column-number-mode}. The column -number is indicated by the letter @samp{C}. However, when both of -these modes are enabled, the line and column numbers are displayed in -parentheses, the line number first, rather than with @samp{L} and -@samp{C}. For example: @samp{(561,2)}. @xref{Minor Modes}, for more -information about minor modes and about how to use these commands. - -@cindex narrowing, and line number display - If you have narrowed the buffer (@pxref{Narrowing}), the displayed -line number is relative to the accessible portion of the buffer. -Thus, it isn't suitable as an argument to @code{goto-line}. (Use -@code{what-line} command to see the line number relative to the whole -file.) - -@vindex line-number-display-limit - If the buffer is very large (larger than the value of -@code{line-number-display-limit}), Emacs won't compute the line -number, because that would be too slow; therefore, the line number -won't appear on the mode-line. To remove this limit, set -@code{line-number-display-limit} to @code{nil}. - -@vindex line-number-display-limit-width - Line-number computation can also be slow if the lines in the buffer -are too long. For this reason, Emacs doesn't display line numbers if -the average width, in characters, of lines near point is larger than -the value of @code{line-number-display-limit-width}. The default -value is 200 characters. - -@findex display-time -@cindex time (on mode line) - Emacs can optionally display the time and system load in all mode -lines. To enable this feature, type @kbd{M-x display-time} or customize -the option @code{display-time-mode}. The information added to the mode -line looks like this: - -@example -@var{hh}:@var{mm}pm @var{l.ll} -@end example - -@noindent -@vindex display-time-24hr-format -Here @var{hh} and @var{mm} are the hour and minute, followed always by -@samp{am} or @samp{pm}. @var{l.ll} is the average number, collected -for the last few minutes, of processes in the whole system that were -either running or ready to run (i.e., were waiting for an available -processor). (Some fields may be missing if your operating system -cannot support them.) If you prefer time display in 24-hour format, -set the variable @code{display-time-24hr-format} to @code{t}. - -@cindex mail (on mode line) -@vindex display-time-use-mail-icon -@vindex display-time-mail-face -@vindex display-time-mail-file -@vindex display-time-mail-directory - The word @samp{Mail} appears after the load level if there is mail -for you that you have not read yet. On graphical displays, you can -use an icon instead of @samp{Mail} by customizing -@code{display-time-use-mail-icon}; this may save some space on the -mode line. You can customize @code{display-time-mail-face} to make -the mail indicator prominent. Use @code{display-time-mail-file} to -specify the mail file to check, or set -@code{display-time-mail-directory} to specify the directory to check -for incoming mail (any nonempty regular file in the directory is -considered as ``newly arrived mail''). - -@cindex battery status (on mode line) -@findex display-battery-mode -@vindex display-battery-mode -@vindex battery-mode-line-format - When running Emacs on a laptop computer, you can display the battery -charge on the mode-line, by using the command -@code{display-battery-mode} or customizing the variable -@code{display-battery-mode}. The variable -@code{battery-mode-line-format} determines the way the battery charge -is displayed; the exact mode-line message depends on the operating -system, and it usually shows the current battery charge as a -percentage of the total charge. - -@cindex mode line, 3D appearance -@cindex attributes of mode line, changing -@cindex non-integral number of lines in a window - On graphical displays, the mode line is drawn as a 3D box. If you -don't like this effect, you can disable it by customizing the -@code{mode-line} face and setting its @code{box} attribute to -@code{nil}. @xref{Face Customization}. - -@cindex non-selected windows, mode line appearance - By default, the mode line of nonselected windows is displayed in a -different face, called @code{mode-line-inactive}. Only the selected -window is displayed in the @code{mode-line} face. This helps show -which window is selected. When the minibuffer is selected, since -it has no mode line, the window from which you activated the minibuffer -has its mode line displayed using @code{mode-line}; as a result, -ordinary entry to the minibuffer does not change any mode lines. - -@vindex mode-line-in-non-selected-windows - You can disable use of @code{mode-line-inactive} by setting variable -@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode -lines are displayed in the @code{mode-line} face. - -@vindex eol-mnemonic-unix -@vindex eol-mnemonic-dos -@vindex eol-mnemonic-mac -@vindex eol-mnemonic-undecided - You can customize the mode line display for each of the end-of-line -formats by setting each of the variables @code{eol-mnemonic-unix}, -@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and -@code{eol-mnemonic-undecided} to the strings you prefer. - -@node Text Display -@section How Text Is Displayed -@cindex characters (in text) -@cindex printing character - - Most characters are @dfn{printing characters}: when they appear in a -buffer, they are displayed literally on the screen. Printing -characters include @acronym{ASCII} numbers, letters, and punctuation -characters, as well as many non-@acronym{ASCII} characters. - -@vindex tab-width -@cindex control characters on display - The @acronym{ASCII} character set contains non-printing @dfn{control -characters}. Two of these are displayed specially: the newline -character (Unicode code point @code{U+000A}) is displayed by starting -a new line, while the tab character (@code{U+0009}) is displayed as a -space that extends to the next tab stop column (normally every 8 -columns). The number of spaces per tab is controlled by the -buffer-local variable @code{tab-width}, which must have an integer -value between 1 and 1000, inclusive. Note that how the tab character -in the buffer is displayed has nothing to do with the definition of -@key{TAB} as a command. - - Other @acronym{ASCII} control characters, whose codes are below -@code{U+0020} (octal 40, decimal 32), are displayed as a caret -(@samp{^}) followed by the non-control version of the character, with -the @code{escape-glyph} face. For instance, the @samp{control-A} -character, @code{U+0001}, is displayed as @samp{^A}. - -@cindex octal escapes -@vindex ctl-arrow - The raw bytes with codes @code{U+0080} (octal 200) through -@code{U+009F} (octal 237) are displayed as @dfn{octal escape -sequences}, with the @code{escape-glyph} face. For instance, -character code @code{U+0098} (octal 230) is displayed as @samp{\230}. -If you change the buffer-local variable @code{ctl-arrow} to -@code{nil}, the @acronym{ASCII} control characters are also displayed -as octal escape sequences instead of caret escape sequences. - -@vindex nobreak-char-display -@cindex non-breaking space -@cindex non-breaking hyphen -@cindex soft hyphen - Some non-@acronym{ASCII} characters have the same appearance as an -@acronym{ASCII} space or hyphen (minus) character. Such characters -can cause problems if they are entered into a buffer without your -realization, e.g., by yanking; for instance, source code compilers -typically do not treat non-@acronym{ASCII} spaces as whitespace -characters. To deal with this problem, Emacs displays such characters -specially: it displays @code{U+00A0} (no-break space) with the -@code{nobreak-space} face, and it displays @code{U+00AD} (soft -hyphen), @code{U+2010} (hyphen), and @code{U+2011} (non-breaking -hyphen) with the @code{escape-glyph} face. To disable this, change -the variable @code{nobreak-char-display} to @code{nil}. If you give -this variable a non-@code{nil} and non-@code{t} value, Emacs instead -displays such characters as a highlighted backslash followed by a -space or hyphen. - - You can customize the way any particular character code is displayed -by means of a display table. @xref{Display Tables,, Display Tables, -elisp, The Emacs Lisp Reference Manual}. - -@cindex glyphless characters -@cindex characters with no font glyphs - On graphical displays, some characters may have no glyphs in any of -the fonts available to Emacs. These @dfn{glyphless characters} are -normally displayed as boxes containing the hexadecimal character code. -Similarly, on text terminals, characters that cannot be displayed -using the terminal encoding (@pxref{Terminal Coding}) are normally -displayed as question signs. You can control the display method by -customizing the variable @code{glyphless-char-display-control}. -@xref{Glyphless Chars,, Glyphless Character Display, elisp, The Emacs -Lisp Reference Manual}, for details. - -@node Cursor Display -@section Displaying the Cursor -@cindex text cursor - -@vindex visible-cursor - On a text terminal, the cursor's appearance is controlled by the -terminal, largely out of the control of Emacs. Some terminals offer -two different cursors: a ``visible'' static cursor, and a ``very -visible'' blinking cursor. By default, Emacs uses the very visible -cursor, and switches to it when you start or resume Emacs. If the -variable @code{visible-cursor} is @code{nil} when Emacs starts or -resumes, it uses the normal cursor. - -@cindex cursor face -@vindex cursor-type - On a graphical display, many more properties of the text cursor can -be altered. To customize its color, change the @code{:background} -attribute of the face named @code{cursor} (@pxref{Face -Customization}). (The other attributes of this face have no effect; -the text shown under the cursor is drawn using the frame's background -color.) To change its shape, customize the buffer-local variable -@code{cursor-type}; possible values are @code{box} (the default), -@code{hollow} (a hollow box), @code{bar} (a vertical bar), @code{(bar -. @var{n})} (a vertical bar @var{n} pixels wide), @code{hbar} (a -horizontal bar), @code{(hbar . @var{n})} (a horizontal bar @var{n} -pixels tall), or @code{nil} (no cursor at all). - -@findex blink-cursor-mode -@cindex cursor, blinking -@cindex blinking cursor -@vindex blink-cursor-mode -@vindex blink-cursor-blinks -@vindex blink-cursor-alist - By default, the cursor stops blinking after 10 blinks, if Emacs does -not get any input during that time; any input event restarts the -count. You can customize the variable @code{blink-cursor-blinks} to -control that: its value says how many times to blink without input -before stopping. Setting that variable to a zero or negative value -will make the cursor blink forever. To disable cursor blinking -altogether, change the variable @code{blink-cursor-mode} to @code{nil} -(@pxref{Easy Customization}), or add the line - -@lisp - (blink-cursor-mode 0) -@end lisp - -@noindent -to your init file. Alternatively, you can change how the cursor -looks when it ``blinks off'' by customizing the list variable -@code{blink-cursor-alist}. Each element in the list should have the -form @code{(@var{on-type} . @var{off-type})}; this means that if the -cursor is displayed as @var{on-type} when it blinks on (where -@var{on-type} is one of the cursor types described above), then it is -displayed as @var{off-type} when it blinks off. - -@vindex x-stretch-cursor -@cindex wide block cursor - Some characters, such as tab characters, are ``extra wide''. When -the cursor is positioned over such a character, it is normally drawn -with the default character width. You can make the cursor stretch to -cover wide characters, by changing the variable -@code{x-stretch-cursor} to a non-@code{nil} value. - -@cindex cursor in non-selected windows -@vindex cursor-in-non-selected-windows - The cursor normally appears in non-selected windows as a -non-blinking hollow box. (For a bar cursor, it instead appears as a -thinner bar.) To turn off cursors in non-selected windows, change the -variable @code{cursor-in-non-selected-windows} to @code{nil}. - -@findex hl-line-mode -@findex global-hl-line-mode -@cindex highlight current line - To make the cursor even more visible, you can use HL Line mode, a -minor mode that highlights the line containing point. Use @kbd{M-x -hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x -global-hl-line-mode} enables or disables the same mode globally. - -@node Line Truncation -@section Line Truncation - -@cindex truncation -@cindex line truncation, and fringes - As an alternative to continuation (@pxref{Continuation Lines}), -Emacs can display long lines by @dfn{truncation}. This means that all -the characters that do not fit in the width of the screen or window do -not appear at all. On graphical displays, a small straight arrow in -the fringe indicates truncation at either end of the line. On text -terminals, this is indicated with @samp{$} signs in the leftmost -and/or rightmost columns. - -@vindex truncate-lines -@findex toggle-truncate-lines - Horizontal scrolling automatically causes line truncation -(@pxref{Horizontal Scrolling}). You can explicitly enable line -truncation for a particular buffer with the command @kbd{M-x -toggle-truncate-lines}. This works by locally changing the variable -@code{truncate-lines}. If that variable is non-@code{nil}, long lines -are truncated; if it is @code{nil}, they are continued onto multiple -screen lines. Setting the variable @code{truncate-lines} in any way -makes it local to the current buffer; until that time, the default -value, which is normally @code{nil}, is in effect. - -@vindex truncate-partial-width-windows - If a split window becomes too narrow, Emacs may automatically enable -line truncation. @xref{Split Window}, for the variable -@code{truncate-partial-width-windows} which controls this. - -@node Visual Line Mode -@section Visual Line Mode - -@cindex word wrap - Another alternative to ordinary line continuation is to use -@dfn{word wrap}. Here, each long logical line is divided into two or -more screen lines, like in ordinary line continuation. However, Emacs -attempts to wrap the line at word boundaries near the right window -edge. This makes the text easier to read, as wrapping does not occur -in the middle of words. - -@cindex mode, Visual Line -@cindex Visual Line mode -@findex visual-line-mode -@findex global-visual-line-mode - Word wrap is enabled by Visual Line mode, an optional minor mode. -To turn on Visual Line mode in the current buffer, type @kbd{M-x -visual-line-mode}; repeating this command turns it off. You can also -turn on Visual Line mode using the menu bar: in the Options menu, -select the @samp{Line Wrapping in this Buffer} submenu, followed by -the @samp{Word Wrap (Visual Line Mode)} menu item. While Visual Line -mode is enabled, the mode-line shows the string @samp{wrap} in the -mode display. The command @kbd{M-x global-visual-line-mode} toggles -Visual Line mode in all buffers. - -@findex beginning-of-visual-line -@findex end-of-visual-line -@findex next-logical-line -@findex previous-logical-line - In Visual Line mode, some editing commands work on screen lines -instead of logical lines: @kbd{C-a} (@code{beginning-of-visual-line}) -moves to the beginning of the screen line, @kbd{C-e} -(@code{end-of-visual-line}) moves to the end of the screen line, and -@kbd{C-k} (@code{kill-visual-line}) kills text to the end of the -screen line. - - To move by logical lines, use the commands @kbd{M-x -next-logical-line} and @kbd{M-x previous-logical-line}. These move -point to the next logical line and the previous logical line -respectively, regardless of whether Visual Line mode is enabled. If -you use these commands frequently, it may be convenient to assign key -bindings to them. @xref{Init Rebinding}. - - By default, word-wrapped lines do not display fringe indicators. -Visual Line mode is often used to edit files that contain many long -logical lines, so having a fringe indicator for each wrapped line -would be visually distracting. You can change this by customizing the -variable @code{visual-line-fringe-indicators}. - -@node Display Custom -@section Customization of Display - - This section describes variables that control miscellaneous aspects -of the appearance of the Emacs screen. Beginning users can skip it. - -@vindex visible-bell - If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts -to make the whole screen blink when it would normally make an audible bell -sound. This variable has no effect if your terminal does not have a way -to make the screen blink. - -@vindex echo-keystrokes - The variable @code{echo-keystrokes} controls the echoing of multi-character -keys; its value is the number of seconds of pause required to cause echoing -to start, or zero, meaning don't echo at all. The value takes effect when -there is something to echo. @xref{Echo Area}. - -@cindex mouse pointer -@cindex hourglass pointer display -@vindex display-hourglass -@vindex hourglass-delay - On graphical displays, Emacs displays the mouse pointer as an -hourglass if Emacs is busy. To disable this feature, set the variable -@code{display-hourglass} to @code{nil}. The variable -@code{hourglass-delay} determines the number of seconds of ``busy -time'' before the hourglass is shown; the default is 1. - -@vindex make-pointer-invisible - If the mouse pointer lies inside an Emacs frame, Emacs makes it -invisible each time you type a character to insert text, to prevent it -from obscuring the text. (To be precise, the hiding occurs when you -type a ``self-inserting'' character. @xref{Inserting Text}.) Moving -the mouse pointer makes it visible again. To disable this feature, -set the variable @code{make-pointer-invisible} to @code{nil}. - -@vindex underline-minimum-offset -@vindex x-underline-at-descent-line - On graphical displays, the variable @code{underline-minimum-offset} -determines the minimum distance between the baseline and underline, in -pixels, for underlined text. By default, the value is 1; increasing -it may improve the legibility of underlined text for certain fonts. -(However, Emacs will never draw the underline below the current line -area.) The variable @code{x-underline-at-descent-line} determines how -to draw underlined text. The default is @code{nil}, which means to -draw it at the baseline level of the font; if you change it to -@code{nil}, Emacs draws the underline at the same height as the font's -descent line. - -@vindex overline-margin - The variable @code{overline-margin} specifies the vertical position -of an overline above the text, including the height of the overline -itself, in pixels; the default is 2. - -@findex tty-suppress-bold-inverse-default-colors - On some text terminals, bold face and inverse video together result -in text that is hard to read. Call the function -@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil} -argument to suppress the effect of bold-face in this case. diff --git a/doc/emacs/doclicense.texi b/doc/emacs/doclicense.texi deleted file mode 100644 index 9c3bbe56e91..00000000000 --- a/doc/emacs/doclicense.texi +++ /dev/null @@ -1,505 +0,0 @@ -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, La@TeX{} input -format, SGML or XML using a publicly available -DTD, and standard-conforming simple HTML, -PostScript or PDF designed for human modification. Examples -of transparent image formats include PNG, XCF and -JPG@. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, SGML or -XML for which the DTD and/or processing tools are -not generally available, and the machine-generated HTML, -PostScript or PDF produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.''@: line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi deleted file mode 100644 index 817d1c6fd05..00000000000 --- a/doc/emacs/emacs-xtra.texi +++ /dev/null @@ -1,137 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../../info/emacs-xtra -@settitle Specialized Emacs Features -@c Merge all functions, variables, and keys into the concept index. -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@comment %**end of header - -@copying -This manual describes specialized features of Emacs. - -Copyright @copyright{} 2004--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@documentencoding UTF-8 - -@dircategory Emacs -@direntry -* Emacs-Xtra: (emacs-xtra). Specialized Emacs features. -@end direntry - -@titlepage -@title Specialized Emacs Features -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Specialized Emacs Features - -@insertcopying - -@end ifnottex - -@menu -* Introduction:: What documentation belongs here? -@iftex -* Picture Mode:: Editing pictures made up of characters using - the quarter-plane screen model. - -* Autorevert:: Auto Reverting non-file buffers. -* Subdir Switches:: Subdirectory switches in Dired. -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -* Emerge:: A convenient way of merging two versions of a program. -* Advanced VC Usage:: Advanced VC (version control) features. -* Fortran:: Fortran mode and its special features. -* MS-DOS:: Using Emacs on MS-DOS. -@end iftex -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - -@node Introduction -@unnumbered Introduction - -This manual contains detailed information about various features that -are too specialized to be included in the printed Emacs manual. It is -intended to be readable by anyone having a basic knowledge of Emacs. -However, certain sections may be intended for a more specialized -audience, such as Elisp authors. This should be clearly pointed out -at the beginning of these sections. - -@c Note to authors - you need to be careful about cross-references to -@c topics in the Emacs manual. As a printed document, the xtra files -@c are separate from the Emacs manual; but as an info document, they -@c are part of the Emacs manual. Hence you need to use something like: -@c @iftex -@c @ref{Comparing Files,,, emacs, the Emacs Manual}, -@c @end iftex -@c @ifnottex -@c @ref{Comparing Files}, -@c @end ifnottex - -Certain packages (or collections of related features) have their own -manuals, separate from the main Emacs manual. This manual is -intended as a complement, rather than an alternative, to reading those -additional manuals. In a nutshell, it is a collection of smaller -specialized features (or extra detail about standard features), too -small or too obscure to justify their own manual, or inclusion in the -printed Emacs manual. The chapters in this manual are, however, -included (at the relevant places) in the main Emacs manual when it is -formatted as an Info document. - -Sections intended specifically for Elisp programmers can follow the -style of the Elisp manual. Other sections should follow the style of -the Emacs manual. - -@iftex - -@raisesections -@include picture-xtra.texi - -@include arevert-xtra.texi - -@include dired-xtra.texi - -@include cal-xtra.texi - -@include emerge-xtra.texi - -@include vc-xtra.texi - -@include fortran-xtra.texi - -@include msdog-xtra.texi - -@lowersections -@end iftex - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index - -@printindex cp - -@bye diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi deleted file mode 100644 index 81a75807511..00000000000 --- a/doc/emacs/emacs.texi +++ /dev/null @@ -1,1612 +0,0 @@ -\input texinfo @c -*- coding: utf-8 -*- - -@setfilename ../../info/emacs -@settitle GNU Emacs Manual - -@c The edition number appears in more than one place in this file -@c I don't really know what it means... -@c For example, it has said "Sixteenth" since sometime in the Emacs 22 -@c series, all through 23, and into 24. So it is not very useful IMO, -@c and offers nothing that EMACSVER does not. I guess it relates -@c mainly to the published book sold by the FSF. Hence no longer -@c bother including it except iftex. Really, I think it should not be -@c here at all (since anyone can make a pdf version), but should just -@c be something added by the FSF during the publishing process. -@c Also, the lispref uses a float (3.0), whereas this uses an ordinal, -@c so the format is not even consistent. -@set EDITION Seventeenth -@include emacsver.texi - -@copying -@iftex -This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@* -@end iftex -@ifnottex -This is the @cite{GNU Emacs Manual}, -@end ifnottex -updated for Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1985--1987, 1993--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``The GNU Manifesto,'' ``Distribution'' and -``GNU GENERAL PUBLIC LICENSE,'' with the Front-Cover Texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@documentencoding UTF-8 - -@dircategory Emacs -@direntry -* Emacs: (emacs). The extensible self-documenting text editor. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. The manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@c @set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@defcodeindex op -@synindex pg cp - -@iftex -@kbdinputstyle code - -@shorttitlepage GNU Emacs Manual -@end iftex - -@titlepage -@sp 6 -@center @titlefont{GNU Emacs Manual} -@sp 4 -@center @value{EDITION} Edition, Updated for Emacs Version @value{EMACSVER}. -@sp 5 -@center Richard Stallman et al. -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin Street, Fifth Floor @* -Boston, MA 02110-1301 USA @* -ISBN 978-0-9831592-4-7 - -@sp 2 -Cover art by Etienne Suvasa; cover design by Matt Lee. - -@end titlepage - - -@summarycontents -@contents - - -@ifnottex -@node Top -@top The Emacs Editor - -Emacs is the extensible, customizable, self-documenting real-time -display editor. This manual describes how to edit with Emacs and -some of the ways to customize it; it corresponds to GNU Emacs version -@value{EMACSVER}. - -@c See `manual-html-mono' and `manual-html-node' in admin/admin.el. -@ifset WWW_GNU_ORG -@html -The homepage for GNU Emacs is at -http://www.gnu.org/software/emacs/.
-To view this manual in other formats, click -here.
-You can also purchase a printed copy from the -FSF store. -@end html -@end ifset - -@ifinfo -If you are reading this in Emacs, type @kbd{h} to read a basic -introduction to the Info documentation system. -@end ifinfo - -For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The -Emacs Lisp Reference Manual}. - -@insertcopying -@end ifnottex - -@c Note that the TeX version generates its own TOC, so the ifnottex's -@c here are not really necessary. -@menu -* Distrib:: How to get the latest Emacs distribution. -* Intro:: An introduction to Emacs concepts. - -Important General Concepts -* Screen:: How to interpret what you see on the screen. -* User Input:: Kinds of input events (characters, buttons, - function keys). -* Keys:: Key sequences: what you type to request one - editing action. -* Commands:: Named functions run by key sequences to do editing. -* Entering Emacs:: Starting Emacs from the shell. -* Exiting:: Stopping or killing Emacs. - -Fundamental Editing Commands -* Basic:: The most basic editing commands. -* Minibuffer:: Entering arguments that are prompted for. -* M-x:: Invoking commands by their names. -* Help:: Commands for asking Emacs about its commands. - -Important Text-Changing Commands -* Mark:: The mark: how to delimit a "region" of text. -* Killing:: Killing (cutting) and yanking (copying) text. -* Registers:: Saving a text string or a location in the buffer. -* Display:: Controlling what text is displayed. -* Search:: Finding or replacing occurrences of a string. -* Fixit:: Commands especially useful for fixing typos. -* Keyboard Macros:: Recording a sequence of keystrokes to be replayed. - -Major Structures of Emacs -* Files:: All about handling files. -* Buffers:: Multiple buffers; editing several files at once. -* Windows:: Viewing multiple pieces of text in one frame. -* Frames:: Using multiple "windows" on your display. -* International:: Using non-@acronym{ASCII} character sets. - -Advanced Features -* Modes:: Major and minor modes alter Emacs's basic behavior. -* Indentation:: Editing the white space at the beginnings of lines. -* Text:: Commands and modes for editing human languages. -* Programs:: Commands and modes for editing programs. -* Building:: Compiling, running and debugging programs. -* Maintaining:: Features for maintaining large programs. -* Abbrevs:: Defining text abbreviations to reduce typing. -* Dired:: Directory and file manager. -* Calendar/Diary:: Calendar and diary facilities. -* Sending Mail:: Sending mail in Emacs. -* Rmail:: Reading mail in Emacs. -* Gnus:: A flexible mail and news reader. -* Document View:: Viewing PDF, PS and DVI files. -* EWW:: A web browser in Emacs. -* Shell:: Executing shell commands from Emacs. -* Emacs Server:: Using Emacs as an editing server. -* Printing:: Printing hardcopies of buffers or regions. -* Sorting:: Sorting lines, paragraphs or pages within Emacs. -@ifnottex -* Picture Mode:: Editing pictures made up of text characters. -@end ifnottex -* Editing Binary Files:: Editing binary files with Hexl mode. -* Saving Emacs Sessions:: Saving Emacs state from one session to the next. -* Recursive Edit:: Performing edits while "within another command". -* Emulation:: Emulating some other editors with Emacs. -* Hyperlinking:: Following links in buffers. -* Amusements:: Various games and hacks. -* Packages:: Installing additional features. -* Customization:: Modifying the behavior of Emacs. - -Recovery from Problems -* Quitting:: Quitting and aborting. -* Lossage:: What to do if Emacs is hung or malfunctioning. -* Bugs:: How and when to report a bug. -* Contributing:: How to contribute improvements to Emacs. -* Service:: How to get help for your own Emacs needs. - -Appendices -* Copying:: The GNU General Public License gives you permission - to redistribute GNU Emacs on certain terms; - it also explains that there is no warranty. -* GNU Free Documentation License:: The license for this documentation. -* Emacs Invocation:: Hairy startup options. -* X Resources:: X resources for customizing Emacs. -* Antinews:: Information about Emacs version 23. -* Mac OS / GNUstep:: Using Emacs under Mac OS and GNUstep. -* Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS. -* Manifesto:: What's GNU? Gnu's Not Unix! - -* Glossary:: Terms used in this manual. -@ifnottex -* Acknowledgments:: Major contributors to GNU Emacs. -@end ifnottex - -Indexes (each index contains a large menu) -* Key Index:: An item for each standard Emacs key sequence. -* Option Index:: An item for every command-line option. -* Command Index:: An item for each command name. -* Variable Index:: An item for each documented variable. -* Concept Index:: An item for each concept. - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are some other nodes which are really subnodes of the ones -already listed, mentioned here so you can get to them in one step: - -The Organization of the Screen - -* Point:: The place in the text where editing commands operate. -* Echo Area:: Short messages appear at the bottom of the screen. -* Mode Line:: Interpreting the mode line. -* Menu Bar:: How to use the menu bar. - -Basic Editing Commands - -* Inserting Text:: Inserting text by simply typing it. -* Moving Point:: Moving the cursor to the place where you want to - change something. -* Erasing:: Deleting and killing text. -* Basic Undo:: Undoing recent changes in the text. -* Basic Files:: Visiting, creating, and saving files. -* Basic Help:: Asking what a character does. -* Blank Lines:: Making and deleting blank lines. -* Continuation Lines:: How Emacs displays lines too wide for the screen. -* Position Info:: What line, row, or column is point on? -* Arguments:: Numeric arguments for repeating a command N times. -* Repeating:: Repeating the previous command quickly. - -The Minibuffer - -* Basic Minibuffer:: Basic usage of the minibuffer. -* Minibuffer File:: Entering file names with the minibuffer. -* Minibuffer Edit:: How to edit in the minibuffer. -* Completion:: An abbreviation facility for minibuffer input. -* Minibuffer History:: Reusing recent minibuffer arguments. -* Repetition:: Re-executing commands that used the minibuffer. -* Passwords:: Entering passwords in the echo area. -* Yes or No Prompts:: Replying yes or no in the echo area. - -Completion - -* Completion Example:: Examples of using completion. -* Completion Commands:: A list of completion commands. -* Completion Exit:: Completion and minibuffer text submission. -* Completion Styles:: How completion matches are chosen. -* Completion Options:: Options for completion. - -Help - -* Help Summary:: Brief list of all Help commands. -* Key Help:: Asking what a key does in Emacs. -* Name Help:: Asking about a command, variable or function name. -* Apropos:: Asking what pertains to a given topic. -* Help Mode:: Special features of Help mode and Help buffers. -* Package Keywords:: Finding Lisp libraries by keywords (topics). -* Language Help:: Help relating to international language support. -* Misc Help:: Other help commands. -* Help Files:: Commands to display auxiliary help files. -* Help Echo:: Help on active text and tooltips ("balloon help"). - -The Mark and the Region - -* Setting Mark:: Commands to set the mark. -* Marking Objects:: Commands to put region around textual units. -* Using Region:: Summary of ways to operate on contents of the region. -* Mark Ring:: Previous mark positions saved so you can go back there. -* Global Mark Ring:: Previous mark positions in various buffers. -* Shift Selection:: Using shifted cursor motion keys. -* Disabled Transient Mark:: Leaving regions unhighlighted by default. - -Killing and Moving Text - -* Deletion and Killing:: Commands that remove text. -* Yanking:: Commands that insert text. -* Cut and Paste:: Clipboard and selections on graphical displays. -* Accumulating Text:: Other methods to add text to the buffer. -* Rectangles:: Operating on text in rectangular areas. -* CUA Bindings:: Using @kbd{C-x}/@kbd{C-c}/@kbd{C-v} to kill and yank. - -Deletion and Killing - -* Deletion:: Commands for deleting small amounts of text and - blank areas. -* Killing by Lines:: How to kill entire lines of text at one time. -* Other Kill Commands:: Commands to kill large regions of text and - syntactic units such as words and sentences. -* Kill Options:: Options that affect killing. - -Yanking - -* Kill Ring:: Where killed text is stored. -* Earlier Kills:: Yanking something killed some time ago. -* Appending Kills:: Several kills in a row all yank together. - -"Cut and Paste" Operations on Graphical Displays - -* Clipboard:: How Emacs uses the system clipboard. -* Primary Selection:: The temporarily selected text selection. -* Secondary Selection:: Cutting without altering point and mark. - -Registers - -* Position Registers:: Saving positions in registers. -* Text Registers:: Saving text in registers. -* Rectangle Registers:: Saving rectangles in registers. -* Configuration Registers:: Saving window configurations in registers. -* Number Registers:: Numbers in registers. -* File Registers:: File names in registers. -* Keyboard Macro Registers:: Keyboard macros in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. - -Controlling the Display - -* Scrolling:: Commands to move text up and down in a window. -* Recentering:: A scroll command that centers the current line. -* Auto Scrolling:: Redisplay scrolls text automatically when needed. -* Horizontal Scrolling:: Moving text left and right in a window. -* Narrowing:: Restricting display and editing to a portion - of the buffer. -* View Mode:: Viewing read-only buffers. -* Follow Mode:: Follow mode lets two windows scroll as one. -* Faces:: How to change the display style using faces. -* Colors:: Specifying colors for faces. -* Standard Faces:: The main predefined faces. -* Text Scale:: Increasing or decreasing text size in a buffer. -* Font Lock:: Minor mode for syntactic highlighting using faces. -* Highlight Interactively:: Tell Emacs what text to highlight. -* Fringes:: Enabling or disabling window fringes. -* Displaying Boundaries:: Displaying top and bottom of the buffer. -* Useless Whitespace:: Showing possibly spurious trailing whitespace. -* Selective Display:: Hiding lines with lots of indentation. -* Optional Mode Line:: Optional mode line display features. -* Text Display:: How text characters are normally displayed. -* Cursor Display:: Features for displaying the cursor. -* Line Truncation:: Truncating lines to fit the screen width instead - of continuing them to multiple screen lines. -* Visual Line Mode:: Word wrap and screen line-based editing. -* Display Custom:: Information on variables for customizing display. - -Searching and Replacement - -* Incremental Search:: Search happens as you type the string. -* Nonincremental Search:: Specify entire string and then search. -* Word Search:: Search for sequence of words. -* Symbol Search:: Search for a source code symbol. -* Regexp Search:: Search for match for a regexp. -* Regexps:: Syntax of regular expressions. -* Regexp Backslash:: Regular expression constructs starting with `\'. -* Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. -* Replace:: Search, and replace some or all matches. -* Other Repeating Search:: Operating on all matches for some regexp. - -Incremental Search - -* Basic Isearch:: Basic incremental search commands. -* Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. -* Isearch Yank:: Commands that grab text into the search string - or else edit the search string. -* Not Exiting Isearch:: Prefix argument and scrolling commands. -* Isearch Minibuffer:: Incremental search of the minibuffer history. - -Replacement Commands - -* Unconditional Replace:: Replacing all matches for a string. -* Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. -* Query Replace:: How to use querying. - -Commands for Fixing Typos - -* Undo:: The Undo commands. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word, or a whole file. - -Keyboard Macros - -* Basic Keyboard Macro:: Defining and running keyboard macros. -* Keyboard Macro Ring:: Where previous keyboard macros are saved. -* Keyboard Macro Counter:: Inserting incrementing numbers in macros. -* Keyboard Macro Query:: Making keyboard macros do different things each - time. -* Save Keyboard Macro:: Giving keyboard macros names; saving them in - files. -* Edit Keyboard Macro:: Editing keyboard macros. -* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard - macro. - -File Handling - -* File Names:: How to type and edit file-name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -@ifnottex -* Autorevert:: Auto Reverting non-file buffers. -@end ifnottex -* Auto Save:: Auto Save periodically protects against loss of data. -* File Aliases:: Handling multiple names for one file. -* Directories:: Creating, deleting, and listing file directories. -* Comparing Files:: Finding where two files differ. -* Diff Mode:: Mode for editing file differences. -* Misc File Ops:: Other things you can do on files. -* Compressed Files:: Accessing compressed files. -* File Archives:: Operating on tar, zip, jar etc. archive files. -* Remote Files:: Accessing files on other machines. -* Quoted File Names:: Quoting special characters in file names. -* File Name Cache:: Completion against a list of files you often use. -* File Conveniences:: Convenience Features for Finding Files. -* Filesets:: Handling sets of files. - -Saving Files - -* Save Commands:: Commands for saving files. -* Backup:: How Emacs saves the old version of your file. -* Customize Save:: Customizing the saving of files. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. -* File Shadowing:: Copying files to "shadows" automatically. -* Time Stamps:: Emacs can update time stamps on saved files. - -Backup Files - -* Backup Names:: How backup files are named. -* Backup Deletion:: Emacs deletes excess numbered backups. -* Backup Copying:: Backups can be made by copying or renaming. - -@ifnottex -Auto Reverting Non-File Buffers - -* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. -* Auto Reverting Dired:: Auto Revert of Dired buffers. -* Supporting additional buffers:: How to add more Auto Revert support. -@end ifnottex - -Auto-Saving: Protection Against Disasters - -* Auto Save Files:: The file where auto-saved changes are - actually made until you save the file. -* Auto Save Control:: Controlling when and how often to auto-save. -* Recover:: Recovering text from auto-save files. - -Using Multiple Buffers - -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-only status; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. -* Indirect Buffers:: An indirect buffer shares the text of another buffer. -* Buffer Convenience:: Convenience and customization features for - buffer handling. - -Convenience Features and Customization of Buffer Handling - -* Uniquify:: Making buffer names unique with directory parts. -* Icomplete:: Fast minibuffer selection. -* Buffer Menus:: Configurable buffer menu. - -Multiple Windows - -* Basic Window:: Introduction to Emacs windows. -* Split Window:: New windows are made by splitting existing windows. -* Other Window:: Moving to another window or doing something to it. -* Pop Up Window:: Finding a file or buffer in another window. -* Change Window:: Deleting windows and changing their sizes. -* Displaying Buffers:: How Emacs picks a window for displaying a buffer. -* Window Convenience:: Convenience functions for window handling. - -Displaying a Buffer in a Window - -* Window Choice:: How @code{display-buffer} works. - -Frames and Graphical Displays - -* Mouse Commands:: Moving, cutting, and pasting, with the mouse. -* Word and Line Mouse:: Mouse commands for selecting whole words or lines. -* Mouse References:: Using the mouse to select an item from a list. -* Menu Mouse Clicks:: Mouse clicks that bring up menus. -* Mode Line Mouse:: Mouse clicks on the mode line. -* Creating Frames:: Creating additional Emacs frames with various contents. -* Frame Commands:: Iconifying, deleting, and switching frames. -* Fonts:: Changing the frame font. -* Speedbar:: How to make and use a speedbar frame. -* Multiple Displays:: How one Emacs instance can talk to several displays. -* Frame Parameters:: Changing the colors and other modes of frames. -* Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Drag and Drop:: Using drag and drop to open files and insert text. -* Menu Bars:: Enabling and disabling the menu bar. -* Tool Bars:: Enabling and disabling the tool bar. -* Dialog Boxes:: Controlling use of dialog boxes. -* Tooltips:: Displaying information at the current mouse position. -* Mouse Avoidance:: Preventing the mouse pointer from obscuring text. -* Non-Window Terminals:: Multiple frames on terminals that show only one. -* Text-Only Mouse:: Using the mouse in text terminals. - -International Character Set Support - -* International Chars:: Basic concepts of multibyte characters. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How Emacs figures out which conversion to use. -* Specify Coding:: Specifying a file's coding system explicitly. -* Output Coding:: Choosing coding systems for output. -* Text Coding:: Choosing conversion to use for file text. -* Communication Coding:: Coding systems for interprocess communication. -* File Name Coding:: Coding systems for file @emph{names}. -* Terminal Coding:: Specifying coding systems for converting - terminal input and output. -* Fontsets:: Fontsets are collections of fonts - that cover the whole spectrum of characters. -* Defining Fontsets:: Defining a new fontset. -* Modifying Fontsets:: Modifying an existing fontset. -* Undisplayable Characters::When characters don't display. -* Unibyte Mode:: You can pick one European character set - to use without multibyte characters. -* Charsets:: How Emacs groups its internal character codes. -* Bidirectional Editing:: Support for right-to-left scripts. - -Major and Minor Modes - -* Major Modes:: Text mode vs. Lisp mode vs. C mode... -* Minor Modes:: Each minor mode is a feature you can turn on - independently of any others. -* Choosing Modes:: How modes are chosen when visiting files. - -Indentation - -* Indentation Commands:: More commands for performing indentation. -* Tab Stops:: Stop points for indentation in Text modes. -* Just Spaces:: Using only space characters for indentation. -* Indent Convenience:: Optional indentation features. - -Commands for Human Languages - -* Words:: Moving over and killing words. -* Sentences:: Moving over and killing sentences. -* Paragraphs:: Moving over paragraphs. -* Pages:: Moving over pages. -* Filling:: Filling or justifying text. -* Case:: Changing the case of text. -* Text Mode:: The major modes for editing text files. -* Outline Mode:: Editing outlines. -* Org Mode:: The Emacs organizer. -* TeX Mode:: Editing TeX and LaTeX files. -* HTML Mode:: Editing HTML and SGML files. -* Nroff Mode:: Editing input to the nroff formatter. -* Enriched Text:: Editing text "enriched" with fonts, colors, etc. -* Text Based Tables:: Commands for editing text-based tables. -* Two-Column:: Splitting text columns into separate windows. - -Filling Text - -* Auto Fill:: Auto Fill mode breaks long lines automatically. -* Fill Commands:: Commands to refill paragraphs and center lines. -* Fill Prefix:: Filling paragraphs that are indented - or in a comment, etc. -* Adaptive Fill:: How Emacs can determine the fill prefix automatically. - -Outline Mode - -* Outline Format:: What the text of an outline looks like. -* Outline Motion:: Special commands for moving through outlines. -* Outline Visibility:: Commands to control what is visible. -* Outline Views:: Outlines and multiple views. -* Foldout:: Folding means zooming in on outlines. - -Org Mode - -* Org Organizer:: Managing TODO lists and agendas. -* Org Authoring:: Exporting Org buffers to various formats. - -@TeX{} Mode - -* TeX Editing:: Special commands for editing in TeX mode. -* LaTeX Editing:: Additional commands for LaTeX input files. -* TeX Print:: Commands for printing part of a file with TeX. -* TeX Misc:: Customization of TeX mode, and related features. - -Enriched Text - -* Enriched Mode:: Entering and exiting Enriched mode. -* Hard and Soft Newlines:: There are two different kinds of newlines. -* Editing Format Info:: How to edit text properties. -* Enriched Faces:: Bold, italic, underline, etc. -* Enriched Indentation:: Changing the left and right margins. -* Enriched Justification:: Centering, setting text flush with the - left or right margin, etc. -* Enriched Properties:: The "special" text properties submenu. - -@c The automatic texinfo menu update inserts some duplicate items here -@c (faces, colors, indentation, justification, properties), because -@c they are listed in two menus. But we already have them above, no -@c need to list them twice. - -Editing Text-based Tables - -* Table Definition:: What is a text based table. -* Table Creation:: How to create a table. -* Table Recognition:: How to activate and deactivate tables. -* Cell Commands:: Cell-oriented commands in a table. -* Cell Justification:: Justifying cell contents. -* Table Rows and Columns:: Inserting and deleting rows and columns. -* Table Conversion:: Converting between plain text and tables. -* Table Misc:: Table miscellany. - -Editing Programs - -* Program Modes:: Major modes for editing programs. -* Defuns:: Commands to operate on major top-level parts - of a program. -* Program Indent:: Adjusting indentation to show the nesting. -* Parentheses:: Commands that operate on parentheses. -* Comments:: Inserting, killing, and aligning comments. -* Documentation:: Getting documentation of functions you plan to call. -* Hideshow:: Displaying blocks selectively. -* Symbol Completion:: Completion on symbol names of your program or language. -* MixedCase Words:: Dealing with identifiersLikeThis. -* Semantic:: Suite of editing tools based on source code parsing. -* Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, - Java, IDL, Pike and AWK modes. -* Asm Mode:: Asm mode and its special features. -@ifnottex -* Fortran:: Fortran mode and its special features. -@end ifnottex - -Top-Level Definitions, or Defuns - -* Left Margin Paren:: An open-paren or similar opening delimiter - starts a defun if it is at the left margin. -* Moving by Defuns:: Commands to move over or mark a major definition. -* Imenu:: Making buffer indexes as menus. -* Which Function:: Which Function mode shows which function you are in. - -Indentation for Programs - -* Basic Indent:: Indenting a single line. -* Multi-line Indent:: Commands to reindent many lines at once. -* Lisp Indent:: Specifying how each Lisp function should be indented. -* C Indent:: Extra features for indenting C and related modes. -* Custom C Indent:: Controlling indentation style for C and related modes. - -Commands for Editing with Parentheses - -* Expressions:: Expressions with balanced parentheses. -* Moving by Parens:: Commands for moving up, down and across - in the structure of parentheses. -* Matching:: Insertion of a close-delimiter flashes matching open. - -Manipulating Comments - -* Comment Commands:: Inserting, killing, and aligning comments. -* Multi-Line Comments:: Commands for adding and editing multi-line comments. -* Options for Comments::Customizing the comment features. - -Documentation Lookup - -* Info Lookup:: Looking up library functions and commands in Info files. -* Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. - -C and Related Modes - -* Motion in C:: Commands to move by C statements, etc. -* Electric C:: Colon and other chars can automatically reindent. -* Hungry Delete:: A more powerful DEL command. -* Other C Commands:: Filling comments, viewing expansion of macros, - and other neat features. - -@ifnottex -Fortran Mode - -* Fortran Motion:: Moving point by statements or subprograms. -* Fortran Indent:: Indentation commands for Fortran. -* Fortran Comments:: Inserting and aligning comments. -* Fortran Autofill:: Auto fill support for Fortran. -* Fortran Columns:: Measuring columns for valid Fortran. -* Fortran Abbrev:: Built-in abbrevs for Fortran keywords. - -Fortran Indentation - -* ForIndent Commands:: Commands for indenting and filling Fortran. -* ForIndent Cont:: How continuation lines indent. -* ForIndent Num:: How line numbers auto-indent. -* ForIndent Conv:: Conventions you must obey to avoid trouble. -* ForIndent Vars:: Variables controlling Fortran indent style. -@end ifnottex - -Compiling and Testing Programs - -* Compilation:: Compiling programs in languages other - than Lisp (C, Pascal, etc.). -* Compilation Mode:: The mode for visiting compiler errors. -* Compilation Shell:: Customizing your shell properly - for use in the compilation buffer. -* Grep Searching:: Searching with grep. -* Flymake:: Finding syntax errors on the fly. -* Debuggers:: Running symbolic debuggers for non-Lisp programs. -* Executing Lisp:: Various modes for editing Lisp programs, - with different facilities for running - the Lisp programs. -* Lisp Libraries:: How Lisp programs are loaded into Emacs. -* Lisp Eval:: Executing a single Lisp expression in Emacs. -* Lisp Interaction:: Executing Lisp in an Emacs buffer. -* External Lisp:: Communicating through Emacs with a separate Lisp. - -Running Debuggers Under Emacs - -* Starting GUD:: How to start a debugger subprocess. -* Debugger Operation:: Connection between the debugger and source buffers. -* Commands of GUD:: Key bindings for common commands. -* GUD Customization:: Defining your own commands for GUD. -* GDB Graphical Interface:: An enhanced mode that uses GDB features to - implement a graphical debugging environment. - -GDB Graphical Interface - -* GDB User Interface Layout:: Control the number of displayed buffers. -* Source Buffers:: Use the mouse in the fringe/margin to - control your program. -* Breakpoints Buffer:: A breakpoint control panel. -* Threads Buffer:: Displays your threads. -* Stack Buffer:: Select a frame from the call stack. -* Other GDB Buffers:: Other buffers for controlling the GDB state. -* Watch Expressions:: Monitor variable values in the speedbar. -* Multithreaded Debugging:: Debugging programs with several threads. - -Maintaining Large Programs - -* Version Control:: Using version control systems. -* Change Log:: Maintaining a change history for your program. -* Tags:: Go directly to any function in your program in one - command. Tags remembers which file it is in. -* EDE:: An integrated development environment for Emacs. -@ifnottex -* Emerge:: A convenient way of merging two versions of a program. -@end ifnottex - -Version Control - -* Introduction to VC:: How version control works in general. -* VC Mode Line:: How the mode line shows version control status. -* Basic VC Editing:: How to edit a file under version control. -* Log Buffer:: Features available in log entry buffers. -* Registering:: Putting a file under version control. -* Old Revisions:: Examining and comparing old versions. -* VC Change Log:: Viewing the VC Change Log. -* VC Undo:: Canceling changes before or after committing. -* VC Ignore:: Ignore files under version control system. -* VC Directory Mode:: Listing files managed by version control. -* Branches:: Multiple lines of development. -@ifnottex -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end ifnottex - -Introduction to Version Control - -* Why Version Control?:: Understanding the problems it addresses. -* Version Control Systems:: Supported version control back-end systems. -* VCS Concepts:: Words and concepts related to version control. -* VCS Merging:: How file conflicts are handled. -* VCS Changesets:: How changes are grouped. -* VCS Repositories:: Where version control repositories are stored. -* Types of Log File:: The VCS log in contrast to the ChangeLog. - -Basic Editing under Version Control - -* VC With A Merging VCS:: Without locking: default mode for CVS. -* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. -* Advanced C-x v v:: Advanced features available with a prefix argument. - -VC Directory Mode - -* VC Directory Buffer:: What the buffer looks like and means. -* VC Directory Commands:: Commands to use in a VC directory buffer. - -Version Control Branches - -* Switching Branches:: How to get to another existing branch. -* VC Pull:: Updating the contents of a branch. -* Merging:: Transferring changes between branches. -* Creating Branches:: How to start a new branch. - -@ifnottex -Miscellaneous Commands and Features of VC - -* Change Logs and VC:: Generating a change log file from log entries. -* VC Delete/Rename:: Deleting and renaming version-controlled files. -* Revision Tags:: Symbolic names for revisions. -* Version Headers:: Inserting version control headers into working files. - -Customizing VC - -* General VC Options:: Options that apply to multiple back ends. -* RCS and SCCS:: Options for RCS and SCCS. -* CVS Options:: Options for CVS. -@end ifnottex - -Change Logs - -* Change Log Commands:: Commands for editing change log files. -* Format of ChangeLog:: What the change log file looks like. - -Tags Tables - -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @command{etags}. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Using tags for completion, and listing them. - -@ifnottex -Merging Files with Emerge - -* Overview of Emerge:: How to start Emerge. Basic concepts. -* Submodes of Emerge:: Fast mode vs. Edit mode. - Skip Prefers mode and Auto Advance mode. -* State of Difference:: You do the merge by specifying state A or B - for each difference. -* Merge Commands:: Commands for selecting a difference, - changing states of differences, etc. -* Exiting Emerge:: What to do when you've finished the merge. -* Combining in Emerge:: How to keep both alternatives for a difference. -* Fine Points of Emerge:: Miscellaneous issues. -@end ifnottex - -Abbrevs - -* Abbrev Concepts:: Fundamentals of defined abbrevs. -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. -* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. - -@ifnottex -Editing Pictures - -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. -@end ifnottex - -Dired, the Directory Editor - -* Dired Enter:: How to invoke Dired. -* Dired Navigation:: Special motion commands in the Dired buffer. -* Dired Deletion:: Deleting files with Dired. -* Flagging Many Files:: Flagging files based on their names. -* Dired Visiting:: Other file operations through Dired. -* Marks vs Flags:: Flagging for deletion vs marking. -* Operating on Files:: How to copy, rename, print, compress, etc. - either one file or several files. -* Shell Commands in Dired:: Running a shell command on the marked files. -* Transforming File Names:: Using patterns to rename multiple files. -* Comparison in Dired:: Running @code{diff} by way of Dired. -* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. -@ifnottex -* Subdir Switches:: Subdirectory switches in Dired. -@end ifnottex -* Subdirectory Motion:: Moving across subdirectories, and up and down. -* Hiding Subdirectories:: Making subdirectories visible or invisible. -* Dired Updating:: Discarding lines for files of no interest. -* Dired and Find:: Using @code{find} to choose the files for Dired. -* Wdired:: Operating on files by editing the Dired buffer. -* Image-Dired:: Viewing image thumbnails in Dired. -* Misc Dired Features:: Various other features. - -The Calendar and the Diary - -* Calendar Motion:: Moving through the calendar; selecting a date. -* Scroll Calendar:: Bringing earlier or later months onto the screen. -* Counting Days:: How many days are there between two dates? -* General Calendar:: Exiting or recomputing the calendar. -* Writing Calendar Files:: Writing calendars to files of various formats. -* Holidays:: Displaying dates of holidays. -* Sunrise/Sunset:: Displaying local times of sunrise and sunset. -* Lunar Phases:: Displaying phases of the moon. -* Other Calendars:: Converting dates to other calendar systems. -* Diary:: Displaying events from your diary. -* Appointments:: Reminders when it's time to do something. -* Importing Diary:: Converting diary events to/from other formats. -* Daylight Saving:: How to specify when daylight saving time is active. -* Time Intervals:: Keeping track of time intervals. -@ifnottex -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -@end ifnottex - -Movement in the Calendar - -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. - -Conversion To and From Other Calendars - -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. - -The Diary - -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. - -@ifnottex -More advanced features of the Calendar and Diary - -* Calendar Customizing:: Calendar layout and hooks. -* Holiday Customizing:: Defining your own holidays. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Diary Customizing:: Defaults you can set. -* Non-Gregorian Diary:: Diary entries based on other calendars. -* Diary Display:: A choice of ways to display the diary. -* Fancy Diary Display:: Sorting diary entries, using included diary files. -* Sexp Diary Entries:: More flexible diary entries. -@end ifnottex - -Sending Mail - -* Mail Format:: Format of a mail message. -* Mail Headers:: Details of some standard mail header fields. -* Mail Aliases:: Abbreviating and grouping mail addresses. -* Mail Commands:: Special commands for editing mail being composed. -* Mail Signature:: Adding a signature to every message. -* Mail Amusements:: Distracting the NSA; adding fortune messages. -* Mail Methods:: Using alternative mail-composition methods. - -Mail Commands - -* Mail Sending:: Commands to send the message. -* Header Editing:: Commands to move to header fields and edit them. -* Citing Mail:: Quoting a message you are replying to. -* Mail Misc:: Attachments, spell checking, etc. - -Reading Mail with Rmail - -* Rmail Basics:: Basic concepts of Rmail, and simple use. -* Rmail Scrolling:: Scrolling through a message. -* Rmail Motion:: Moving to another message. -* Rmail Deletion:: Deleting and expunging messages. -* Rmail Inbox:: How mail gets into the Rmail file. -* Rmail Files:: Using multiple Rmail files. -* Rmail Output:: Copying message out to files. -* Rmail Labels:: Classifying messages by labeling them. -* Rmail Attributes:: Certain standard labels, called attributes. -* Rmail Reply:: Sending replies to messages you are viewing. -* Rmail Summary:: Summaries show brief info on many messages. -* Rmail Sorting:: Sorting messages in Rmail. -* Rmail Display:: How Rmail displays a message; customization. -* Rmail Coding:: How Rmail handles decoding character sets. -* Rmail Editing:: Editing message text and headers in Rmail. -* Rmail Digest:: Extracting the messages from a digest message. -* Rmail Rot13:: Reading messages encoded in the rot13 code. -* Movemail:: More details of fetching new mail. -* Remote Mailboxes:: Retrieving mail from remote mailboxes. -* Other Mailbox Formats:: Retrieving mail from local mailboxes in - various formats. - -Rmail Summaries - -* Rmail Make Summary:: Making various sorts of summaries. -* Rmail Summary Edit:: Manipulating messages from the summary. - -Gnus - -* Buffers of Gnus:: The group, summary, and article buffers. -* Gnus Startup:: What you should know about starting Gnus. -* Gnus Group Buffer:: A short description of Gnus group commands. -* Gnus Summary Buffer:: A short description of Gnus summary commands. - -Document Viewing - -* DocView Navigation:: Navigating DocView buffers. -* DocView Searching:: Searching inside documents. -* DocView Slicing:: Specifying which part of a page is displayed. -* DocView Conversion:: Influencing and triggering conversion. - -Running Shell Commands from Emacs - -* Single Shell:: How to run one shell command and return. -* Interactive Shell:: Permanent shell taking input via Emacs. -* Shell Mode:: Special Emacs commands used with permanent shell. -* Shell Prompts:: Two ways to recognize shell prompts. -* Shell History:: Repeating previous commands in a shell buffer. -* Directory Tracking:: Keeping track when the subshell changes directory. -* Shell Options:: Options for customizing Shell mode. -* Terminal emulator:: An Emacs window as a terminal emulator. -* Term Mode:: Special Emacs commands used in Term mode. -* Remote Host:: Connecting to another computer. -* Serial Terminal:: Connecting to a serial port. - -Shell Command History - -* Shell Ring:: Fetching commands from the history list. -* Shell History Copying::Moving to a command and then copying it. -* History References:: Expanding @samp{!}-style history references. - -Using Emacs as a Server - -* Invoking emacsclient:: Connecting to the Emacs server. -* emacsclient Options:: Emacs client startup options. - -Printing Hard Copies - -* PostScript:: Printing buffers or regions as PostScript. -* PostScript Variables:: Customizing the PostScript printing commands. -* Printing Package:: An optional advanced printing interface. - -Hyperlinking and Navigation Features - -* Browse-URL:: Following URLs. -* Goto Address mode:: Activating URLs. -* FFAP:: Finding files etc. at point. - -Emacs Lisp Packages - -* Package Menu:: Buffer for viewing and managing packages. -* Package Installation:: Options for package installation. -* Package Files:: Where packages are installed. - -Customization - -* Easy Customization:: Convenient way to browse and change settings. -* Variables:: Many Emacs commands examine Emacs variables - to decide what to do; by setting variables, - you can control their functioning. -* Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine" keys. -* Init File:: How to write common customizations in the - initialization file. - -Easy Customization Interface - -* Customization Groups:: How settings are classified. -* Browsing Custom:: Browsing and searching for settings. -* Changing a Variable:: How to edit an option's value and set the option. -* Saving Customizations:: Saving customizations for future Emacs sessions. -* Face Customization:: How to edit the attributes of a face. -* Specific Customization:: Customizing specific settings or groups. -* Custom Themes:: Collections of customization settings. -* Creating Custom Themes:: How to create a new custom theme. - -Variables - -* Examining:: Examining or setting one variable's value. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. -* Directory Variables:: How variable values can be specified by directory. - -Local Variables in Files - -* Specifying File Variables:: Specifying file local variables. -* Safe File Variables:: Making sure file local variables are safe. - -Customizing Key Bindings - -* Keymaps:: Generalities. The global keymap. -* Prefix Keymaps:: Keymaps for prefix keys. -* Local Keymaps:: Major and minor modes have their own keymaps. -* Minibuffer Maps:: The minibuffer uses its own local keymaps. -* Rebinding:: How to redefine one key's meaning conveniently. -* Init Rebinding:: Rebinding keys with your initialization file. -* Modifier Keys:: Using modifier keys in key bindings. -* Function Keys:: Rebinding terminal function keys. -* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. -* Mouse Buttons:: Rebinding mouse buttons in Emacs. -* Disabling:: Disabling a command means confirmation is required - before it can be executed. This is done to protect - beginners from surprises. - -The Emacs Initialization File - -* Init Syntax:: Syntax of constants in Emacs Lisp. -* Init Examples:: How to do some things with an init file. -* Terminal Init:: Each terminal type can have an init file. -* Find Init:: How Emacs finds the init file. -* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. - -Dealing with Emacs Trouble - -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. -* Screen Garbled:: Garbage on the screen. -* Text Garbled:: Garbage in the text. -* Memory Full:: How to cope when you run out of memory. -* Crashing:: What Emacs does when it crashes. -* After a Crash:: Recovering editing in an Emacs session that crashed. -* Emergency Escape:: What to do if Emacs stops responding. - -Reporting Bugs - -* Known Problems:: How to read about known problems and bugs. -* Bug Criteria:: Have you really found a bug? -* Understanding Bug Reporting:: How to report a bug effectively. -* Checklist:: Steps to follow for a good bug report. -* Sending Patches:: How to send a patch for GNU Emacs. - -Command Line Arguments for Emacs Invocation - -* Action Arguments:: Arguments to visit files, load libraries, - and call functions. -* Initial Options:: Arguments that take effect while starting Emacs. -* Command Example:: Examples of using command line arguments. -* Environment:: Environment variables that Emacs uses. -* Display X:: Changing the default display and using remote login. -* Font X:: Choosing a font for text, under X. -* Colors X:: Choosing display colors. -* Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. -* Title X:: Specifying the initial frame's title. -* Icons X:: Choosing what sort of icon to use, under X. -* Misc X:: Other display options. - -Environment Variables - -* General Variables:: Environment variables that all versions of Emacs use. -* Misc Variables:: Certain system-specific variables. -* MS-Windows Registry:: An alternative to the environment on MS-Windows. - -X Options and Resources - -* Resources:: Using X resources with Emacs (in general). -* Table of Resources:: Table of specific X resources that affect Emacs. -* Lucid Resources:: X resources for Lucid menus. -* Motif Resources:: X resources for Motif and LessTif menus. -* GTK resources:: Resources for GTK widgets. - -GTK resources - -* GTK Resource Basics:: Basic usage of GTK+ resources. -* GTK Widget Names:: How GTK+ widgets are named. -* GTK Names in Emacs:: GTK widgets used by Emacs. -* GTK styles:: What can be customized in a GTK widget. - -Emacs and Mac OS / GNUstep - -* Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or Mac OS. -* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS. -* Mac / GNUstep Events:: How window system events are handled. -* GNUstep Support:: Details on status of GNUstep support. - -Emacs and Microsoft Windows/MS-DOS - -* Windows Startup:: How to start Emacs on Windows. -* Text and Binary:: Text files use CRLF to terminate lines. -* Windows Files:: File-name conventions on Windows. -* ls in Lisp:: Emulation of @code{ls} for Dired. -* Windows HOME:: Where Emacs looks for your @file{.emacs} and - where it starts up. -* Windows Keyboard:: Windows-specific keyboard features. -* Windows Mouse:: Windows-specific mouse features. -* Windows Processes:: Running subprocesses on Windows. -* Windows Printing:: How to specify the printer on MS-Windows. -* Windows Fonts:: Specifying fonts on MS-Windows. -* Windows Misc:: Miscellaneous Windows features. -@ifnottex -* MS-DOS:: Using Emacs on MS-DOS. - -Emacs and MS-DOS - -* MS-DOS Keyboard:: Keyboard conventions on MS-DOS. -* MS-DOS Mouse:: Mouse conventions on MS-DOS. -* MS-DOS Display:: Fonts, frames and display size on MS-DOS. -* MS-DOS File Names:: File name conventions on MS-DOS. -* MS-DOS Printing:: Printing specifics on MS-DOS. -* MS-DOS and MULE:: Support for internationalization on MS-DOS. -* MS-DOS Processes:: Running subprocesses on MS-DOS. -@end ifnottex - -@end detailmenu -@end menu - -@iftex -@unnumbered Preface - - This manual documents the use and simple customization of the Emacs -editor. Simple Emacs customizations do not require you to be a -programmer, but if you are not interested in customizing, you can -ignore the customization hints. - - This is primarily a reference manual, but can also be used as a -primer. If you are new to Emacs, we recommend you start with -the integrated, learn-by-doing tutorial, before reading the manual. To -run the tutorial, start Emacs and type @kbd{C-h t}. The tutorial -describes commands, tells you when to try them, and explains the -results. The tutorial is available in several languages. - - On first reading, just skim chapters 1 and 2, which describe the -notational conventions of the manual and the general appearance of the -Emacs display screen. Note which questions are answered in these -chapters, so you can refer back later. After reading chapter 4, you -should practice the commands shown there. The next few chapters -describe fundamental techniques and concepts that are used constantly. -You need to understand them thoroughly, so experiment with them -until you are fluent. - - Chapters 14 through 19 describe intermediate-level features that are -useful for many kinds of editing. Chapter 20 and following chapters -describe optional but useful features; read those chapters when you -need them. - - Read the Common Problems chapter if Emacs does not seem to be -working properly. It explains how to cope with several common -problems (@pxref{Lossage,, Dealing with Emacs Trouble}), as well as -when and how to report Emacs bugs (@pxref{Bugs}). - - To find the documentation of a particular command, look in the index. -Keys (character commands) and command names have separate indexes. -There is also a glossary, with a cross reference for each term. - - This manual is available as a printed book and also as an Info file. -The Info file is for reading from Emacs itself, or with the Info program. -Info is the principal format for documentation in the GNU system. -The Info file and the printed book contain substantially the same text -and are generated from the same source files, which are also -distributed with GNU Emacs. - - GNU Emacs is a member of the Emacs editor family. There are many -Emacs editors, all sharing common principles of organization. For -information on the underlying philosophy of Emacs and the lessons -learned from its development, see @cite{Emacs, the Extensible, -Customizable Self-Documenting Display Editor}, available from -@url{ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-519A.pdf}. - -This version of the manual is mainly intended for use with GNU Emacs -installed on GNU and Unix systems. GNU Emacs can also be used on -MS-DOS, Microsoft Windows, and Macintosh systems. The Info file -version of this manual contains some more information about using -Emacs on those systems. Those systems use different file name syntax; -in addition MS-DOS does not support all GNU Emacs features. -@xref{Microsoft Windows}, for information about using Emacs on -Windows. @xref{Mac OS / GNUstep}, for information about using Emacs -on Macintosh (and GNUstep). -@end iftex - -@node Distrib -@unnumbered Distribution - -GNU Emacs is @dfn{free software}; this means that everyone is free to -use it and free to redistribute it under certain conditions. GNU Emacs -is not in the public domain; it is copyrighted and there are -restrictions on its distribution, but these restrictions are designed -to permit everything that a good cooperating citizen would want to do. -What is not allowed is to try to prevent others from further sharing -any version of GNU Emacs that they might get from you. The precise -conditions are found in the GNU General Public License that comes with -Emacs and also appears in this manual@footnote{This manual is itself -covered by the GNU Free Documentation License. This license is -similar in spirit to the General Public License, but is more suitable -for documentation. @xref{GNU Free Documentation License}.}. -@xref{Copying}. - -One way to get a copy of GNU Emacs is from someone else who has it. -You need not ask for our permission to do so, or tell any one else; -just copy it. If you have access to the Internet, you can get the -latest distribution version of GNU Emacs by anonymous FTP; see -@url{http://www.gnu.org/software/emacs} on our website for more -information. - -You may also receive GNU Emacs when you buy a computer. Computer -manufacturers are free to distribute copies on the same terms that apply to -everyone else. These terms require them to give you the full sources, -including whatever changes they may have made, and to permit you to -redistribute the GNU Emacs received from them under the usual terms of the -General Public License. In other words, the program must be free for you -when you get it, not just free for the manufacturer. - -If you find GNU Emacs useful, please @strong{send a donation} to the -Free Software Foundation to support our work. Donations to the Free -Software Foundation are tax deductible in the US@. If you use GNU Emacs -at your workplace, please suggest that the company make a donation. -To donate, see @url{https://my.fsf.org/donate/}. -For other ways in which you can help, see -@url{http://www.gnu.org/help/help.html}. - -@c The command view-order-manuals uses this anchor. -@anchor{Printed Books} -We also sell hardcopy versions of this manual and @cite{An -Introduction to Programming in Emacs Lisp}, by Robert J. Chassell. -You can visit our online store at @url{http://shop.fsf.org/}. -The income from sales goes to support the foundation's purpose: the -development of new free software, and improvements to our existing -programs including GNU Emacs. - -If you need to contact the Free Software Foundation, see -@url{http://www.fsf.org/about/contact/}, or write to - -@display -Free Software Foundation -51 Franklin Street, Fifth Floor -Boston, MA 02110-1301 -USA -@end display - -@iftex -@node Acknowledgments -@unnumberedsec Acknowledgments - -@c It's hard to update this fairly. -@c I wonder if it would be better to drop it in favor of AUTHORS? -Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas -Abrahamsson, Jay K. Adams, Alon Albert, Michael Albinus, Nagy -Andras, Benjamin Andresen, Ralf Angeli, Dmitry Antipov, Joe Arceneaux, Emil Åström, -Miles Bader, David Bakhash, Juanma Barranquero, Eli Barzilay, Thomas -Baumann, Steven L. Baur, Jay Belanger, Alexander L. Belikoff, -Thomas Bellman, Scott Bender, Boaz Ben-Zvi, Sergey Berezin, Stephen Berman, Karl -Berry, Anna M. Bigatti, Ray Blaak, Martin Blais, Jim Blandy, Johan -Bockgård, Jan Böcker, Joel Boehland, Lennart Borgman, Per Bothner, -Terrence Brannon, Frank Bresz, Peter Breton, Emmanuel Briot, Kevin -Broadey, Vincent Broman, Michael Brouwer, David M. Brown, Stefan Bruda, -Georges Brun-Cottan, Joe Buehler, Scott Byer, Włodek Bzyl, -Bill Carpenter, Per Cederqvist, Hans Chalupsky, Chris Chase, Bob -Chassell, Andrew Choi, Chong Yidong, Sacha Chua, Stewart Clamen, James -Clark, Mike Clarkson, Glynn Clements, Andrew Cohen, Daniel Colascione, -Christoph Conrad, Ludovic Courtès, Andrew Csillag, -Toby Cubitt, Baoqiu Cui, Doug Cutting, Mathias Dahl, Julien Danjou, Satyaki -Das, Vivek Dasmohapatra, Dan Davison, Michael DeCorte, Gary Delp, Nachum -Dershowitz, Dave Detlefs, Matthieu Devin, Christophe de Dinechin, Eri -Ding, Jan Djärv, Lawrence R. Dodd, Carsten Dominik, Scott Draves, -Benjamin Drieu, Viktor Dukhovni, Jacques Duthen, Dmitry Dzhus, John -Eaton, Rolf Ebert, Carl Edman, David Edmondson, Paul Eggert, Stephen -Eglen, Christian Egli, Torbjörn Einarsson, Tsugutomo Enami, David -Engster, Hans Henrik Eriksen, Michael Ernst, Ata Etemadi, Frederick -Farnbach, Oscar Figueiredo, Fred Fish, Steve Fisk, Karl Fogel, Gary -Foster, Eric S. Fraga, Romain Francoise, Noah Friedman, Andreas -Fuchs, Shigeru Fukaya, Xue Fuqiao, Hallvard Furuseth, Keith Gabryelski, Peter S. -Galbraith, Kevin Gallagher, Fabián E. Gallina, Kevin Gallo, Juan León Lahoz García, -Howard Gayle, Daniel German, Stephen Gildea, Julien Gilles, David -Gillespie, Bob Glickstein, Deepak Goel, David De La Harpe Golden, Boris -Goldowsky, David Goodger, Chris Gray, Kevin Greiner, Michelangelo Grigni, Odd -Gripenstam, Kai Großjohann, Michael Gschwind, Bastien Guerry, Henry -Guillaume, Dmitry Gutov, Doug Gwyn, Bruno Haible, Ken'ichi Handa, Lars Hansen, Chris -Hanson, Jesper Harder, Alexandru Harsanyi, K. Shane Hartman, John -Heidemann, Jon K. Hellan, Magnus Henoch, Markus Heritsch, Dirk -Herrmann, Karl Heuer, Manabu Higashida, Konrad Hinsen, Anders Holst, -Jeffrey C. Honig, Tassilo Horn, Kurt Hornik, Tom Houlder, Joakim -Hove, Denis Howe, Lars Ingebrigtsen, Andrew Innes, Seiichiro Inoue, -Philip Jackson, Martyn Jago, Pavel Janik, Paul Jarc, Ulf Jasper, -Thorsten Jolitz, Michael K. Johnson, Kyle Jones, Terry Jones, Simon -Josefsson, Alexandre Julliard, Arne Jørgensen, Tomoji Kagatani, -Brewster Kahle, Tokuya Kameshima, Lute Kamstra, Ivan Kanis, David -Kastrup, David Kaufman, Henry Kautz, Taichi Kawabata, Taro Kawagishi, -Howard Kaye, Michael Kifer, Richard King, Peter Kleiweg, Karel -Klíč, Shuhei Kobayashi, Pavel Kobyakov, Larry K. Kolodney, David -M. Koppelman, Koseki Yoshinori, Robert Krawitz, Sebastian Kremer, -Ryszard Kubiak, Igor Kuzmin, David Kågedal, Daniel LaLiberte, Karl -Landstrom, Mario Lang, Aaron Larson, James R. Larus, Vinicius Jose -Latorre, Werner Lemberg, Frederic Lepied, Peter Liljenberg, Christian -Limpach, Lars Lindberg, Chris Lindblad, Anders Lindgren, Thomas Link, -Juri Linkov, Francis Litterio, Sergey Litvinov, Leo Liu, Emilio C. Lopes, -Martin Lorentzon, Dave Love, Eric Ludlam, Károly Lőrentey, Sascha -Lüdecke, Greg McGary, Roland McGrath, Michael McNamara, Alan Mackenzie, -Christopher J. Madsen, Neil M. Mager, Ken Manheimer, Bill Mann, -Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin, -Yukihiro Matsumoto, Tomohiro Matsuyama, David Maus, Thomas May, Will Mengarini, David -Megginson, Stefan Merten, Ben A. Mesander, Wayne Mesard, Brad -Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Möllmann, Dani Moncayo, Stefan -Monnier, Keith Moore, Jan Moringen, Morioka Tomohiko, Glenn Morris, -Don Morrison, Diane Murray, Riccardo Murri, Sen Nagata, Erik Naggum, -Gergely Nagy, Nobuyoshi Nakada, Thomas Neumann, Mike Newton, Thien-Thi Nguyen, -Jurgen Nickelsen, Dan Nicolaescu, Hrvoje Nikšić, Jeff Norden, -Andrew Norman, Edward O'Connor, Kentaro Ohkouchi, Christian Ohler, -Kenichi Okada, Alexandre Oliva, Bob Olson, Michael Olson, Takaaki Ota, -Pieter E. J. Pareit, Ross Patterson, David Pearson, Juan Pechiar, -Jeff Peck, Damon Anton Permezel, Tom Perrine, William M. Perry, Per -Persson, Jens Petersen, Daniel Pfeiffer, Justus Piater, Richard L. -Pieri, Fred Pierresteguy, François Pinard, Daniel Pittman, Christian -Plaunt, Alexander Pohoyda, David Ponce, Francesco A. Potortì, -Michael D. Prange, Mukesh Prasad, Ken Raeburn, Marko Rahamaa, Ashwin -Ram, Eric S. Raymond, Paul Reilly, Edward M. Reingold, David -Reitter, Alex Rezinsky, Rob Riepel, Lara Rios, Adrian Robert, Nick -Roberts, Roland B. Roberts, John Robinson, Denis B. Roegel, Danny -Roozendaal, Sebastian Rose, William Rosenblatt, Markus Rost, Guillermo -J. Rozas, Martin Rudalics, Ivar Rummelhoff, Jason Rumney, Wolfgang -Rupprecht, Benjamin Rutt, Kevin Ryde, James B. Salem, Masahiko Sato, -Timo Savola, Jorgen Schäfer, Holger Schauer, William Schelter, Ralph -Schleicher, Gregor Schmid, Michael Schmidt, Ronald S. Schnell, -Philippe Schnoebelen, Jan Schormann, Alex Schroeder, Stefan Schoef, -Rainer Schöpf, Raymond Scholz, Eric Schulte, Andreas Schwab, Randal -Schwartz, Oliver Seidel, Manuel Serrano, Paul Sexton, Hovav Shacham, -Stanislav Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Tibor -Šimko, Espen Skoglund, Rick Sladkey, Lynn Slater, Chris Smith, -David Smith, Paul D. Smith, Wilson Snyder, William Sommerfeld, Simon -South, Andre Spiegel, Michael Staats, Thomas Steffen, Ulf Stegemann, -Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, Ken -Stevens, Andy Stewart, Jonathan Stigelman, Martin Stjernholm, Kim F. -Storm, Steve Strassmann, Christopher Suckling, Olaf Sylvester, Naoto -Takahashi, Steven Tamm, Jan Tatarik, Luc Teirlinck, Jean-Philippe Theberge, Jens -T. Berger Thielemann, Spencer Thomas, Jim Thompson, Toru Tomabechi, -David O'Toole, Markus Triska, Tom Tromey, Enami Tsugutomo, Eli -Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh Vaidheeswarran, Neil -W. Van Dyke, Didier Verna, Joakim Verona, Ulrik Vieth, Geoffrey -Voelker, Johan Vromans, Inge Wallin, John Paul Wallington, Colin -Walters, Barry Warsaw, Christoph Wedler, Ilja Weis, Zhang Weize, -Morten Welinder, Joseph Brian Wells, Rodney Whitby, John Wiegley, -Sascha Wilde, Ed Wilkinson, Mike Williams, Roland Winkler, Bill -Wohler, Steven A. Wood, Dale R. Worley, Francis J. Wright, Felix -S. T. Wu, Tom Wurgler, Yamamoto Mitsuharu, Katsumi Yamaoka, -Masatake Yamato, Jonathan Yavner, Ryan Yeske, Ilya Zakharevich, Milan -Zamazal, Victor Zandy, Eli Zaretskii, Jamie Zawinski, Andrew Zhilin, -Shenghuo Zhu, Piotr Zieliński, Ian T. Zimmermann, Reto Zimmermann, -Neal Ziring, Teodor Zlatanov, and Detlev Zundel. -@end iftex - -@node Intro -@unnumbered Introduction - - You are reading about GNU Emacs, the GNU incarnation of the -advanced, self-documenting, customizable, extensible editor Emacs. -(The @samp{G} in -@c Workaround makeinfo 4 bug. -@c http://lists.gnu.org/archive/html/bug-texinfo/2004-08/msg00009.html -@iftex -@acronym{GNU, @acronym{GNU}'s Not Unix} -@end iftex -@ifnottex -@acronym{GNU, GNU's Not Unix} -@end ifnottex -is not silent.) - - We call Emacs @dfn{advanced} because it can do much more than simple -insertion and deletion of text. It can control subprocesses, indent -programs automatically, show multiple files at once, and more. -Emacs editing commands operate in terms of characters, words, lines, -sentences, paragraphs, and pages, as well as expressions and comments -in various programming languages. - - @dfn{Self-documenting} means that at any time you can use special -commands, known as @dfn{help commands}, to find out what your options -are, or to find out what any command does, or to find all the -commands that pertain to a given topic. @xref{Help}. - - @dfn{Customizable} means that you can easily alter the behavior of -Emacs commands in simple ways. For instance, if you use a programming -language in which comments start with @samp{<**} and end with -@samp{**>}, you can tell the Emacs comment manipulation commands to -use those strings (@pxref{Comments}). To take another example, you -can rebind the basic cursor motion commands (up, down, left and right) -to any keys on the keyboard that you find comfortable. -@xref{Customization}. - - @dfn{Extensible} means that you can go beyond simple customization -and create entirely new commands. New commands are simply programs -written in the Lisp language, which are run by Emacs's own Lisp -interpreter. Existing commands can even be redefined in the middle of -an editing session, without having to restart Emacs. Most of the -editing commands in Emacs are written in Lisp; the few exceptions -could have been written in Lisp but use C instead for efficiency. -Writing an extension is programming, but non-programmers can use it -afterwards. @xref{Top, Emacs Lisp Intro, Preface, eintr, An -Introduction to Programming in Emacs Lisp}, if you want to learn Emacs -Lisp programming. - -@include screen.texi -@include commands.texi -@include entering.texi -@include basic.texi -@include mini.texi -@include m-x.texi -@include help.texi -@include mark.texi -@include killing.texi -@include regs.texi -@include display.texi -@include search.texi -@include fixit.texi -@include kmacro.texi -@c Includes arevert-xtra. -@include files.texi -@include buffers.texi -@include windows.texi -@include frames.texi -@include mule.texi -@include modes.texi -@include indent.texi -@include text.texi -@c Includes fortran-xtra. -@include programs.texi -@include building.texi -@c Includes vc1-xtra, emerge-xtra. -@include maintaining.texi -@include abbrevs.texi -@c Includes dired-xtra. -@include dired.texi -@c Includes cal-xtra. -@include calendar.texi -@include sending.texi -@include rmail.texi -@c Includes picture-xtra.texi -@include misc.texi -@include package.texi -@include custom.texi -@include trouble.texi - -@node Copying -@appendix GNU GENERAL PUBLIC LICENSE -@include gpl.texi - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@include cmdargs.texi -@include xresources.texi - -@include anti.texi -@include macos.texi -@c Includes msdog-xtra. -@include msdog.texi -@include gnu.texi -@include glossary.texi -@ifnottex -@include ack.texi -@end ifnottex - -@c The Option Index is produced only in the on-line version, -@c because the index entries related to command-line options -@c tend to point to the same pages and all begin with a dash. - -@node Key Index -@unnumbered Key (Character) Index -@printindex ky - -@ifnottex -@node Option Index -@unnumbered Command-Line Options Index -@printindex op -@end ifnottex - -@node Command Index -@unnumbered Command and Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@bye diff --git a/doc/emacs/emerge-xtra.texi b/doc/emacs/emerge-xtra.texi deleted file mode 100644 index bb39136d067..00000000000 --- a/doc/emacs/emerge-xtra.texi +++ /dev/null @@ -1,413 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Emerge -@section Merging Files with Emerge -@cindex Emerge -@cindex merging files - - It's not unusual for programmers to get their signals crossed and -modify the same program in two different directions. To recover from -this confusion, you need to merge the two versions. Emerge makes this -easier. For other ways to compare files, see -@iftex -@ref{Comparing Files,,, emacs, the Emacs Manual}, -@end iftex -@ifnottex -@ref{Comparing Files}, -@end ifnottex -and @ref{Top,, Ediff, ediff, The Ediff Manual}. - -@menu -* Overview of Emerge:: How to start Emerge. Basic concepts. -* Submodes of Emerge:: Fast mode vs. Edit mode. - Skip Prefers mode and Auto Advance mode. -* State of Difference:: You do the merge by specifying state A or B - for each difference. -* Merge Commands:: Commands for selecting a difference, - changing states of differences, etc. -* Exiting Emerge:: What to do when you've finished the merge. -* Combining in Emerge:: How to keep both alternatives for a difference. -* Fine Points of Emerge:: Miscellaneous issues. -@end menu - -@node Overview of Emerge -@subsection Overview of Emerge - - To start Emerge, run one of these four commands: - -@table @kbd -@item M-x emerge-files -@findex emerge-files -Merge two specified files. - -@item M-x emerge-files-with-ancestor -@findex emerge-files-with-ancestor -Merge two specified files, with reference to a common ancestor. - -@item M-x emerge-buffers -@findex emerge-buffers -Merge two buffers. - -@item M-x emerge-buffers-with-ancestor -@findex emerge-buffers-with-ancestor -Merge two buffers with reference to a common ancestor in a third -buffer. -@end table - -@cindex merge buffer (Emerge) -@cindex A and B buffers (Emerge) - The Emerge commands compare two files or buffers, and display the -comparison in three buffers: one for each input text (the @dfn{A buffer} -and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging -takes place. The merge buffer shows the full merged text, not just the -differences. Wherever the two input texts differ, you can choose which -one of them to include in the merge buffer. - - The Emerge commands that take input from existing buffers use only -the accessible portions of those buffers, if they are narrowed. -@iftex -@xref{Narrowing,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Narrowing}. -@end ifnottex - - - If a common ancestor version is available, from which the two texts to -be merged were both derived, Emerge can use it to guess which -alternative is right. Wherever one current version agrees with the -ancestor, Emerge presumes that the other current version is a deliberate -change which should be kept in the merged version. Use the -@samp{with-ancestor} commands if you want to specify a common ancestor -text. These commands read three file or buffer names---variant A, -variant B, and the common ancestor. - - After the comparison is done and the buffers are prepared, the -interactive merging starts. You control the merging by typing special -@dfn{merge commands} in the merge buffer (@pxref{Merge Commands}). -For each run of differences between the input texts, you can choose -which one of them to keep, or edit them both together. - - The merge buffer uses a special major mode, Emerge mode, with commands -for making these choices. But you can also edit the buffer with -ordinary Emacs commands. - - At any given time, the attention of Emerge is focused on one -particular difference, called the @dfn{selected} difference. This -difference is marked off in the three buffers like this: - -@example -vvvvvvvvvvvvvvvvvvvv -@var{text that differs} -^^^^^^^^^^^^^^^^^^^^ -@end example - -@noindent -Emerge numbers all the differences sequentially and the mode -line always shows the number of the selected difference. - - Normally, the merge buffer starts out with the A version of the text. -But when the A version of a difference agrees with the common ancestor, -then the B version is initially preferred for that difference. - - Emerge leaves the merged text in the merge buffer when you exit. At -that point, you can save it in a file with @kbd{C-x C-w}. If you give a -numeric argument to @code{emerge-files} or -@code{emerge-files-with-ancestor}, it reads the name of the output file -using the minibuffer. (This is the last file name those commands read.) -Then exiting from Emerge saves the merged text in the output file. - - Normally, Emerge commands save the output buffer in its file when you -exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not -save the output buffer, but you can save it yourself if you wish. - -@node Submodes of Emerge -@subsection Submodes of Emerge - - You can choose between two modes for giving merge commands: Fast mode -and Edit mode. In Fast mode, basic merge commands are single -characters, but ordinary Emacs commands are disabled. This is -convenient if you use only merge commands. In Edit mode, all merge -commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs -commands are also available. This allows editing the merge buffer, but -slows down Emerge operations. - - Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to -Fast mode. The mode line indicates Edit and Fast modes with @samp{E} -and @samp{F}. - - Emerge has two additional submodes that affect how particular merge -commands work: Auto Advance mode and Skip Prefers mode. - - If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands -advance to the next difference. This lets you go through the merge -faster as long as you simply choose one of the alternatives from the -input. The mode line indicates Auto Advance mode with @samp{A}. - - If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands -skip over differences in states ``prefer-A'' and ``prefer-B'' -(@pxref{State of Difference}). Thus you see only differences for -which neither version is presumed ``correct''. The mode line -indicates Skip Prefers mode with @samp{S}. This mode is only relevant -when there is an ancestor. - -@findex emerge-auto-advance -@findex emerge-skip-prefers - Use the command @kbd{s a} (@code{emerge-auto-advance}) to set or clear -Auto Advance mode. Use @kbd{s s} (@code{emerge-skip-prefers}) to set or -clear Skip Prefers mode. These commands turn on the mode with a -positive argument, turn it off with a negative or zero argument, and -toggle the mode with no argument. - -@node State of Difference -@subsection State of a Difference - - In the merge buffer, a difference is marked with lines of @samp{v} and -@samp{^} characters. Each difference has one of these seven states: - -@table @asis -@item A -The difference is showing the A version. The @kbd{a} command always -produces this state; the mode line indicates it with @samp{A}. - -@item B -The difference is showing the B version. The @kbd{b} command always -produces this state; the mode line indicates it with @samp{B}. - -@item default-A -@itemx default-B -The difference is showing the A or the B state by default, because you -haven't made a choice. All differences start in the default-A state -(and thus the merge buffer is a copy of the A buffer), except those for -which one alternative is ``preferred'' (see below). - -When you select a difference, its state changes from default-A or -default-B to plain A or B@. Thus, the selected difference never has -state default-A or default-B, and these states are never displayed in -the mode line. - -The command @kbd{d a} chooses default-A as the default state, and @kbd{d -b} chooses default-B@. This chosen default applies to all differences -that you have never selected and for which no alternative is preferred. -If you are moving through the merge sequentially, the differences you -haven't selected are those following the selected one. Thus, while -moving sequentially, you can effectively make the A version the default -for some sections of the merge buffer and the B version the default for -others by using @kbd{d a} and @kbd{d b} between sections. - -@item prefer-A -@itemx prefer-B -The difference is showing the A or B state because it is -@dfn{preferred}. This means that you haven't made an explicit choice, -but one alternative seems likely to be right because the other -alternative agrees with the common ancestor. Thus, where the A buffer -agrees with the common ancestor, the B version is preferred, because -chances are it is the one that was actually changed. - -These two states are displayed in the mode line as @samp{A*} and @samp{B*}. - -@item combined -The difference is showing a combination of the A and B states, as a -result of the @kbd{x c} or @kbd{x C} commands. - -Once a difference is in this state, the @kbd{a} and @kbd{b} commands -don't do anything to it unless you give them a numeric argument. - -The mode line displays this state as @samp{comb}. -@end table - -@node Merge Commands -@subsection Merge Commands - - Here are the Merge commands for Fast mode; in Edit mode, precede them -with @kbd{C-c C-c}: - -@table @kbd -@item p -Select the previous difference. - -@item n -Select the next difference. - -@item a -Choose the A version of this difference. - -@item b -Choose the B version of this difference. - -@item C-u @var{n} j -Select difference number @var{n}. - -@item . -Select the difference containing point. -@c [Does not work in the A or B buffer?] -@c You can use this command in the merge buffer or in the A or B buffer. - -@item q -Quit---finish the merge. - -@item C-] -Abort---exit merging and do not save the output. - -@item f -Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) - -@item e -Go into Edit mode. - -@item l -Recenter (like @kbd{C-l}) all three windows. With an argument, -reestablish the default three-window display. - -@item - -Specify part of a prefix numeric argument. - -@item @var{digit} -Also specify part of a prefix numeric argument. - -@item d a -Choose the A version as the default from here down in -the merge buffer. - -@item d b -Choose the B version as the default from here down in -the merge buffer. - -@item c a -Copy the A version of this difference into the kill ring. - -@item c b -Copy the B version of this difference into the kill ring. - -@item i a -Insert the A version of this difference at point. - -@item i b -Insert the B version of this difference at point. - -@item m -Put point and mark around the difference. - -@item ^ -Scroll all three windows down (like @kbd{M-v}). - -@item v -Scroll all three windows up (like @kbd{C-v}). - -@item < -Scroll all three windows left (like @kbd{C-x <}). - -@item > -Scroll all three windows right (like @kbd{C-x >}). - -@item | -Reset horizontal scroll on all three windows. - -@item x 1 -Shrink the merge window to one line. (Use @kbd{C-u l} to restore it -to full size.) - -@item x c -Combine the two versions of this difference (@pxref{Combining in -Emerge}). - -@item x f -Show the names of the files/buffers Emerge is operating on, in a Help -window. (Use @kbd{C-u l} to restore windows.) - -@item x j -Join this difference with the following one. -(@kbd{C-u x j} joins this difference with the previous one.) - -@item x s -Split this difference into two differences. Before you use this -command, position point in each of the three buffers at the place where -you want to split the difference. - -@item x t -Trim identical lines off the top and bottom of the difference. -Such lines occur when the A and B versions are -identical but differ from the ancestor version. -@end table - -@node Exiting Emerge -@subsection Exiting Emerge - - The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing -the results into the output file if you specified one. It restores the -A and B buffers to their proper contents, or kills them if they were -created by Emerge and you haven't changed them. It also disables the -Emerge commands in the merge buffer, since executing them later could -damage the contents of the various buffers. - - @kbd{C-]} aborts the merge. This means exiting without writing the -output file. If you didn't specify an output file, then there is no -real difference between aborting and finishing the merge. - - If the Emerge command was called from another Lisp program, then its -return value is @code{t} for successful completion, or @code{nil} if you -abort. - -@node Combining in Emerge -@subsection Combining the Two Versions - - Sometimes you want to keep @emph{both} alternatives for a particular -difference. To do this, use @kbd{x c}, which edits the merge buffer -like this: - -@example -@group -#ifdef NEW -@var{version from B buffer} -#else /* not NEW */ -@var{version from A buffer} -#endif /* not NEW */ -@end group -@end example - -@noindent -@vindex emerge-combine-versions-template -While this example shows C preprocessor conditionals delimiting the two -alternative versions, you can specify the strings to use by setting -the variable @code{emerge-combine-versions-template} to a string of your -choice. In the string, @samp{%a} says where to put version A, and -@samp{%b} says where to put version B@. The default setting, which -produces the results shown above, looks like this: - -@example -@group -"#ifdef NEW\n%b#else /* not NEW */\n%a#endif /* not NEW */\n" -@end group -@end example - -@node Fine Points of Emerge -@subsection Fine Points of Emerge - - During the merge, you mustn't try to edit the A and B buffers yourself. -Emerge modifies them temporarily, but ultimately puts them back the way -they were. - - You can have any number of merges going at once---just don't use any one -buffer as input to more than one merge at once, since the temporary -changes made in these buffers would get in each other's way. - - Starting Emerge can take a long time because it needs to compare the -files fully. Emacs can't do anything else until @code{diff} finishes. -Perhaps in the future someone will change Emerge to do the comparison in -the background when the input files are large---then you could keep on -doing other things with Emacs until Emerge is ready to accept -commands. - -@vindex emerge-startup-hook - After setting up the merge, Emerge runs the hook -@code{emerge-startup-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi deleted file mode 100644 index f8ab4eb971a..00000000000 --- a/doc/emacs/entering.texi +++ /dev/null @@ -1,165 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Entering and Exiting Emacs - - This chapter explains how to enter Emacs, and how to exit it. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Entering Emacs -@section Entering Emacs -@cindex entering Emacs -@cindex starting Emacs - - The usual way to invoke Emacs is with the shell command -@command{emacs}. From a terminal window running in the X Window -System, you can run Emacs in the background with @command{emacs &}; -this way, Emacs won't tie up the terminal window, so you can use it to -run other shell commands. - -@cindex startup screen - When Emacs starts up, the initial frame displays a special buffer -named @samp{*GNU Emacs*}. This @dfn{startup screen} contains -information about Emacs and @dfn{links} to common tasks that are -useful for beginning users. For instance, activating the @samp{Emacs -Tutorial} link opens the Emacs tutorial; this does the same thing as -the command @kbd{C-h t} (@code{help-with-tutorial}). To activate a -link, either move point onto it and type @kbd{@key{RET}}, or click on -it with @kbd{mouse-1} (the left mouse button). - - Using a command line argument, you can tell Emacs to visit one or -more files as soon as it starts up. For example, @command{emacs -foo.txt} starts Emacs with a buffer displaying the contents of the -file @samp{foo.txt}. This feature exists mainly for compatibility -with other editors, which are designed to be launched from the shell -for short editing sessions. If you call Emacs this way, the initial -frame is split into two windows---one showing the specified file, and -the other showing the startup screen. @xref{Windows}. - - Generally, it is unnecessary and wasteful to start Emacs afresh each -time you want to edit a file. The recommended way to use Emacs is to -start it just once, just after you log in, and do all your editing in -the same Emacs session. @xref{Files}, for information on visiting -more than one file. If you use Emacs this way, the Emacs session -accumulates valuable context, such as the kill ring, registers, undo -history, and mark ring data, which together make editing more -convenient. These features are described later in the manual. - - To edit a file from another program while Emacs is running, you can -use the @command{emacsclient} helper program to open a file in the -existing Emacs session. @xref{Emacs Server}. - - Emacs accepts other command line arguments that tell it to load -certain Lisp files, where to put the initial frame, and so forth. -@xref{Emacs Invocation}. - -@vindex inhibit-startup-screen - If the variable @code{inhibit-startup-screen} is non-@code{nil}, -Emacs does not display the startup screen. In that case, if one or -more files were specified on the command line, Emacs simply displays -those files; otherwise, it displays a buffer named @file{*scratch*}, -which can be used to evaluate Emacs Lisp expressions interactively. -@xref{Lisp Interaction}. You can set the variable -@code{inhibit-startup-screen} using the Customize facility -(@pxref{Easy Customization}), or by editing your initialization file -(@pxref{Init File}).@footnote{Setting @code{inhibit-startup-screen} in -@file{site-start.el} doesn't work, because the startup screen is set -up before reading @file{site-start.el}. @xref{Init File}, for -information about @file{site-start.el}.} - - You can also force Emacs to display a file or directory at startup -by setting the variable @code{initial-buffer-choice} to a string -naming that file or directory. The value of -@code{initial-buffer-choice} may also be a function (of no arguments) -that should return a buffer which is then displayed. -@ignore -@c I do not think this should be mentioned. AFAICS it is just a dodge -@c around inhibit-startup-screen not being settable on a site-wide basis. -@code{initial-buffer-choice} may also be @code{t} in which case the -@file{*scratch*} buffer will be shown. -@end ignore -If @code{initial-buffer-choice} is non-@code{nil}, then if you specify -any files on the command line, Emacs still visits them, but does not -display them initially. - -@node Exiting -@section Exiting Emacs -@cindex exiting -@cindex killing Emacs -@cindex leaving Emacs -@cindex quitting Emacs - -@table @kbd -@item C-x C-c -Kill Emacs (@code{save-buffers-kill-terminal}). -@item C-z -On a text terminal, suspend Emacs; on a graphical display, -``minimize'' the selected frame (@code{suspend-emacs}). -@end table - -@kindex C-x C-c -@findex save-buffers-kill-terminal - @dfn{Killing} Emacs means terminating the Emacs program. To do -this, type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}). A -two-character key sequence is used to make it harder to type by -accident. If there are any modified file-visiting buffers when you -type @kbd{C-x C-c}, Emacs first offers to save these buffers. If you -do not save them all, it asks for confirmation again, since the -unsaved changes will be lost. Emacs also asks for confirmation if any -subprocesses are still running, since killing Emacs will also kill the -subprocesses (@pxref{Shell}). - - @kbd{C-x C-c} behaves specially if you are using Emacs as a server. -If you type it from a ``client frame'', it closes the client -connection. @xref{Emacs Server}. - - Emacs can, optionally, record certain session information when you -kill it, such as the files you were visiting at the time. This -information is then available the next time you start Emacs. -@xref{Saving Emacs Sessions}. - -@vindex confirm-kill-emacs - If the value of the variable @code{confirm-kill-emacs} is -non-@code{nil}, @kbd{C-x C-c} assumes that its value is a predicate -function, and calls that function. If the result of the function call -is non-@code{nil}, the session is killed, otherwise Emacs continues to -run. One convenient function to use as the value of -@code{confirm-kill-emacs} is the function @code{yes-or-no-p}. The -default value of @code{confirm-kill-emacs} is @code{nil}. - -@findex kill-emacs - To kill Emacs without being prompted about saving, type @kbd{M-x -kill-emacs}. - -@kindex C-z -@findex suspend-frame -@cindex minimizing -@cindex iconifying -@cindex suspending - @kbd{C-z} runs the command @code{suspend-frame}. On a graphical -display, this command @dfn{minimizes} (or @dfn{iconifies}) the -selected Emacs frame, hiding it in a way that lets you bring it back -later (exactly how this hiding occurs depends on the window system). -On a text terminal, the @kbd{C-z} command @dfn{suspends} Emacs, -stopping the program temporarily and returning control to the parent -process (usually a shell); in most shells, you can resume Emacs after -suspending it with the shell command @command{%emacs}. - - Text terminals usually listen for certain special characters whose -meaning is to kill or suspend the program you are running. @b{This -terminal feature is turned off while you are in Emacs.} The meanings -of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were inspired by the -use of @kbd{C-z} and @kbd{C-c} on several operating systems as the -characters for stopping or killing a program, but that is their only -relationship with the operating system. You can customize these keys -to run any commands of your choice (@pxref{Keymaps}). - -@ifnottex -@lowersections -@end ifnottex diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi deleted file mode 100644 index ee80c49af0b..00000000000 --- a/doc/emacs/files.texi +++ /dev/null @@ -1,2052 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Files -@chapter File Handling -@cindex files - - The operating system stores data permanently in named @dfn{files}, so -most of the text you edit with Emacs comes from a file and is ultimately -stored in a file. - - To edit a file, you must tell Emacs to read the file and prepare a -buffer containing a copy of the file's text. This is called -@dfn{visiting} the file. Editing commands apply directly to text in the -buffer; that is, to the copy inside Emacs. Your changes appear in the -file itself only when you @dfn{save} the buffer back into the file. - - In addition to visiting and saving files, Emacs can delete, copy, -rename, and append to files, keep multiple versions of them, and operate -on file directories. - -@menu -* File Names:: How to type and edit file-name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -@ifnottex -* Autorevert:: Auto Reverting non-file buffers. -@end ifnottex -* Auto Save:: Auto Save periodically protects against loss of data. -* File Aliases:: Handling multiple names for one file. -* Directories:: Creating, deleting, and listing file directories. -* Comparing Files:: Finding where two files differ. -* Diff Mode:: Mode for editing file differences. -* Misc File Ops:: Other things you can do on files. -* Compressed Files:: Accessing compressed files. -* File Archives:: Operating on tar, zip, jar etc. archive files. -* Remote Files:: Accessing files on other machines. -* Quoted File Names:: Quoting special characters in file names. -* File Name Cache:: Completion against a list of files you often use. -* File Conveniences:: Convenience Features for Finding Files. -* Filesets:: Handling sets of files. -@end menu - -@node File Names -@section File Names -@cindex file names - -@cindex default file name - Many Emacs commands that operate on a file require you to specify -the file name, using the minibuffer (@pxref{Minibuffer File}). - - While in the minibuffer, you can use the usual completion and -history commands (@pxref{Minibuffer}). Note that file name completion -ignores file names whose extensions appear in the variable -@code{completion-ignored-extensions} (@pxref{Completion Options}). -Note also that most commands use ``permissive completion with -confirmation'' for reading file names: you are allowed to submit a -nonexistent file name, but if you type @key{RET} immediately after -completing up to a nonexistent file name, Emacs prints -@samp{[Confirm]} and you must type a second @key{RET} to confirm. -@xref{Completion Exit}, for details. - -@cindex default directory -@vindex default-directory -@vindex insert-default-directory - Each buffer has a @dfn{default directory}, stored in the -buffer-local variable @code{default-directory}. Whenever Emacs reads -a file name using the minibuffer, it usually inserts the default -directory into the minibuffer as the initial contents. You can -inhibit this insertion by changing the variable -@code{insert-default-directory} to @code{nil} (@pxref{Minibuffer -File}). Regardless, Emacs always assumes that any relative file name -is relative to the default directory, e.g., entering a file name -without a directory specifies a file in the default directory. - -@findex cd -@findex pwd - When you visit a file, Emacs sets @code{default-directory} in the -visiting buffer to the directory of its file. When you create a new -buffer that is not visiting a file, via a command like @kbd{C-x b}, -its default directory is usually copied from the buffer that was -current at the time (@pxref{Select Buffer}). You can use the command -@kbd{M-x pwd} to see the value of @code{default-directory} in the -current buffer. The command @kbd{M-x cd} prompts for a directory -name, and sets the buffer's @code{default-directory} to that directory -(doing this does not change the buffer's file name, if any). - - As an example, when you visit the file @file{/u/rms/gnu/gnu.tasks}, -the default directory is set to @file{/u/rms/gnu/}. If you invoke a -command that reads a file name, entering just @samp{foo} in the -minibuffer, with a directory omitted, specifies the file -@file{/u/rms/gnu/foo}; entering @samp{../.login} specifies -@file{/u/rms/.login}; and entering @samp{new/foo} specifies -@file{/u/rms/gnu/new/foo}. - - When typing a file name into the minibuffer, you can make use of a -couple of shortcuts: a double slash is interpreted as ``ignore -everything before the second slash in the pair'', and @samp{~/} is -interpreted as your home directory. @xref{Minibuffer File}. - -@cindex environment variables in file names -@cindex expansion of environment variables -@cindex @code{$} in file names - @anchor{File Names with $}The character @samp{$} is used to -substitute an environment variable into a file name. The name of the -environment variable consists of all the alphanumeric characters after -the @samp{$}; alternatively, it can be enclosed in braces after the -@samp{$}. For example, if you have used the shell command -@command{export FOO=rms/hacks} to set up an environment variable named -@env{FOO}, then both @file{/u/$FOO/test.c} and -@file{/u/$@{FOO@}/test.c} are abbreviations for -@file{/u/rms/hacks/test.c}. If the environment variable is not -defined, no substitution occurs, so that the character @samp{$} stands -for itself. Note that environment variables affect Emacs only if they -are applied before Emacs is started. - - To access a file with @samp{$} in its name, if the @samp{$} causes -expansion, type @samp{$$}. This pair is converted to a single -@samp{$} at the same time that variable substitution is performed for -a single @samp{$}. Alternatively, quote the whole file name with -@samp{/:} (@pxref{Quoted File Names}). File names which begin with a -literal @samp{~} should also be quoted with @samp{/:}. - - You can include non-@acronym{ASCII} characters in file names. -@xref{File Name Coding}. - -@node Visiting -@section Visiting Files -@cindex visiting files -@cindex open file - -@table @kbd -@item C-x C-f -Visit a file (@code{find-file}). -@item C-x C-r -Visit a file for viewing, without allowing changes to it -(@code{find-file-read-only}). -@item C-x C-v -Visit a different file instead of the one visited last -(@code{find-alternate-file}). -@item C-x 4 f -Visit a file, in another window (@code{find-file-other-window}). Don't -alter what is displayed in the selected window. -@item C-x 5 f -Visit a file, in a new frame (@code{find-file-other-frame}). Don't -alter what is displayed in the selected frame. -@item M-x find-file-literally -Visit a file with no conversion of the contents. -@end table - -@cindex files, visiting and saving -@cindex saving files - @dfn{Visiting} a file means reading its contents into an Emacs -buffer so you can edit them. Emacs makes a new buffer for each file -that you visit. - -@kindex C-x C-f -@findex find-file - To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the -minibuffer to enter the name of the desired file. While in the -minibuffer, you can abort the command by typing @kbd{C-g}. @xref{File -Names}, for details about entering file names into minibuffers. - - If the specified file exists but the system does not allow you to -read it, an error message is displayed in the echo area. Otherwise, -you can tell that @kbd{C-x C-f} has completed successfully by the -appearance of new text on the screen, and by the buffer name shown in -the mode line (@pxref{Mode Line}). Emacs normally constructs the -buffer name from the file name, omitting the directory name. For -example, a file named @file{/usr/rms/emacs.tex} is visited in a buffer -named @samp{emacs.tex}. If there is already a buffer with that name, -Emacs constructs a unique name; the normal method is to add a suffix -based on the directory name (e.g., @samp{}, @samp{}, -and so on), but you can select other methods. @xref{Uniquify}. - -@cindex creating files - To create a new file, just visit it using the same command, @kbd{C-x -C-f}. Emacs displays @samp{(New file)} in the echo area, but in other -respects behaves as if you had visited an existing empty file. - -@cindex modified (buffer) - After visiting a file, the changes you make with editing commands are -made in the Emacs buffer. They do not take effect in the visited -file, until you @dfn{save} the buffer (@pxref{Saving}). If a buffer -contains changes that have not been saved, we say the buffer is -@dfn{modified}. This implies that some changes will be lost if the -buffer is not saved. The mode line displays two stars near the left -margin to indicate that the buffer is modified. - - If you visit a file that is already in Emacs, @kbd{C-x C-f} switches -to the existing buffer instead of making another copy. Before doing -so, it checks whether the file has changed since you last visited or -saved it. If the file has changed, Emacs offers to reread it. - -@vindex large-file-warning-threshold -@cindex file, warning when size is large -@cindex size of file, warning when visiting -@cindex maximum buffer size exceeded, error message - If you try to visit a file larger than -@code{large-file-warning-threshold} (the default is 10000000, which is -about 10 megabytes), Emacs asks you for confirmation first. You can -answer @kbd{y} to proceed with visiting the file. Note, however, that -Emacs cannot visit files that are larger than the maximum Emacs buffer -size, which is limited by the amount of memory Emacs can allocate and -by the integers that Emacs can represent (@pxref{Buffers}). If you -try, Emacs displays an error message saying that the maximum buffer -size has been exceeded. - -@cindex wildcard characters in file names -@vindex find-file-wildcards - If the file name you specify contains shell-style wildcard -characters, Emacs visits all the files that match it. (On -case-insensitive filesystems, Emacs matches the wildcards disregarding -the letter case.) Wildcards include @samp{?}, @samp{*}, and -@samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file -name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted -File Names}, for information on how to visit a file whose name -actually contains wildcard characters. You can disable the wildcard -feature by customizing @code{find-file-wildcards}. - -@kindex C-x C-v -@findex find-alternate-file - If you visit the wrong file unintentionally by typing its name -incorrectly, type @kbd{C-x C-v} (@code{find-alternate-file}) to visit -the file you really wanted. @kbd{C-x C-v} is similar to @kbd{C-x -C-f}, but it kills the current buffer (after first offering to save it -if it is modified). When @kbd{C-x C-v} reads the file name to visit, -it inserts the entire default file name in the buffer, with point just -after the directory part; this is convenient if you made a slight -error in typing the name. - -@vindex find-file-run-dired - If you ``visit'' a file that is actually a directory, Emacs invokes -Dired, the Emacs directory browser. @xref{Dired}. You can disable -this behavior by setting the variable @code{find-file-run-dired} to -@code{nil}; in that case, it is an error to try to visit a directory. - - Files which are actually collections of other files, or @dfn{file -archives}, are visited in special modes which invoke a Dired-like -environment to allow operations on archive members. @xref{File -Archives}, for more about these features. - - If you visit a file that the operating system won't let you modify, -or that is marked read-only, Emacs makes the buffer read-only too, so -that you won't go ahead and make changes that you'll have trouble -saving afterward. You can make the buffer writable with @kbd{C-x C-q} -(@code{read-only-mode}). @xref{Misc Buffer}. - -@kindex C-x C-r -@findex find-file-read-only - If you want to visit a file as read-only in order to protect -yourself from entering changes accidentally, visit it with the command -@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. - -@kindex C-x 4 f -@findex find-file-other-window - @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} -except that the buffer containing the specified file is selected in another -window. The window that was selected before @kbd{C-x 4 f} continues to -show the same buffer it was already showing. If this command is used when -only one window is being displayed, that window is split in two, with one -window showing the same buffer as before, and the other one showing the -newly requested file. @xref{Windows}. - -@kindex C-x 5 f -@findex find-file-other-frame - @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a -new frame, or selects any existing frame showing the specified file. -@xref{Frames}. - -@cindex file selection dialog - On graphical displays, there are two additional methods for visiting -files. Firstly, when Emacs is built with a suitable GUI toolkit, -commands invoked with the mouse (by clicking on the menu bar or tool -bar) use the toolkit's standard ``File Selection'' dialog instead of -prompting for the file name in the minibuffer. On GNU/Linux and Unix -platforms, Emacs does this when built with GTK, LessTif, and Motif -toolkits; on MS-Windows and Mac, the GUI version does that by default. -For information on how to customize this, see @ref{Dialog Boxes}. - - Secondly, Emacs supports ``drag and drop'': dropping a file into an -ordinary Emacs window visits the file using that window. As an -exception, dropping a file into a window displaying a Dired buffer -moves or copies the file into the displayed directory. For details, -see @ref{Drag and Drop}, and @ref{Misc Dired Features}. - - On text-mode terminals and on graphical displays when Emacs was -built without a GUI toolkit, you can visit files via the menu-bar -``File'' menu, which has a ``Visit New File'' item. - - Each time you visit a file, Emacs automatically scans its contents -to detect what character encoding and end-of-line convention it uses, -and converts these to Emacs's internal encoding and end-of-line -convention within the buffer. When you save the buffer, Emacs -performs the inverse conversion, writing the file to disk with its -original encoding and end-of-line convention. @xref{Coding Systems}. - -@findex find-file-literally - If you wish to edit a file as a sequence of @acronym{ASCII} -characters with no special encoding or conversion, use the @kbd{M-x -find-file-literally} command. This visits a file, like @kbd{C-x C-f}, -but does not do format conversion (@pxref{Format Conversion,, Format -Conversion, elisp, the Emacs Lisp Reference Manual}), character code -conversion (@pxref{Coding Systems}), or automatic uncompression -(@pxref{Compressed Files}), and does not add a final newline because -of @code{require-final-newline} (@pxref{Customize Save}). If you have -already visited the same file in the usual (non-literal) manner, this -command asks you whether to visit it literally instead. - -@vindex find-file-hook -@vindex find-file-not-found-functions - Two special hook variables allow extensions to modify the operation -of visiting files. Visiting a file that does not exist runs the -functions in @code{find-file-not-found-functions}; this variable holds -a list of functions, which are called one by one (with no arguments) -until one of them returns non-@code{nil}. This is not a normal hook, -and the name ends in @samp{-functions} rather than @samp{-hook} to -indicate that fact. - - Successful visiting of any file, whether existing or not, calls the -functions in @code{find-file-hook}, with no arguments. This variable -is a normal hook. In the case of a nonexistent file, the -@code{find-file-not-found-functions} are run first. @xref{Hooks}. - - There are several ways to specify automatically the major mode for -editing the file (@pxref{Choosing Modes}), and to specify local -variables defined for that file (@pxref{File Variables}). - -@node Saving -@section Saving Files - - @dfn{Saving} a buffer in Emacs means writing its contents back into the file -that was visited in the buffer. - -@menu -* Save Commands:: Commands for saving files. -* Backup:: How Emacs saves the old version of your file. -* Customize Save:: Customizing the saving of files. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. -* Shadowing: File Shadowing. Copying files to "shadows" automatically. -* Time Stamps:: Emacs can update time stamps on saved files. -@end menu - -@node Save Commands -@subsection Commands for Saving Files - - These are the commands that relate to saving and writing files. - -@table @kbd -@item C-x C-s -Save the current buffer to its file (@code{save-buffer}). -@item C-x s -Save any or all buffers to their files (@code{save-some-buffers}). -@item M-~ -Forget that the current buffer has been changed (@code{not-modified}). -With prefix argument (@kbd{C-u}), mark the current buffer as changed. -@item C-x C-w -Save the current buffer with a specified file name (@code{write-file}). -@item M-x set-visited-file-name -Change the file name under which the current buffer will be saved. -@end table - -@kindex C-x C-s -@findex save-buffer - When you wish to save the file and make your changes permanent, type -@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} -displays a message like this: - -@example -Wrote /u/rms/gnu/gnu.tasks -@end example - -@noindent -If the current buffer is not modified (no changes have been made in it -since the buffer was created or last saved), saving is not really -done, because it would have no effect. Instead, @kbd{C-x C-s} -displays a message like this in the echo area: - -@example -(No changes need to be saved) -@end example - -With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer -to be backed up when the next save is done. @xref{Backup}. - -@kindex C-x s -@findex save-some-buffers - The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any -or all modified buffers. It asks you what to do with each buffer. The -possible responses are analogous to those of @code{query-replace}: - -@table @kbd -@item y -Save this buffer and ask about the rest of the buffers. -@item n -Don't save this buffer, but ask about the rest of the buffers. -@item ! -Save this buffer and all the rest with no more questions. -@c following generates acceptable underfull hbox -@item @key{RET} -Terminate @code{save-some-buffers} without any more saving. -@item . -Save this buffer, then exit @code{save-some-buffers} without even asking -about other buffers. -@item C-r -View the buffer that you are currently being asked about. When you exit -View mode, you get back to @code{save-some-buffers}, which asks the -question again. -@item d -Diff the buffer against its corresponding file, so you can see what -changes you would be saving. This calls the command -@code{diff-buffer-with-file} (@pxref{Comparing Files}). -@item C-h -Display a help message about these options. -@end table - - @kbd{C-x C-c}, the key sequence to exit Emacs, invokes -@code{save-some-buffers} and therefore asks the same questions. - -@kindex M-~ -@findex not-modified - If you have changed a buffer but do not wish to save the changes, -you should take some action to prevent it. Otherwise, each time you -use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer -by mistake. One thing you can do is type @kbd{M-~} -(@code{not-modified}), which clears out the indication that the buffer -is modified. If you do this, none of the save commands will believe -that the buffer needs to be saved. (@samp{~} is often used as a -mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.) -Alternatively, you can cancel all the changes made since the file was -visited or saved, by reading the text from the file again. This is -called @dfn{reverting}. @xref{Reverting}. (You could also undo all -the changes by repeating the undo command @kbd{C-x u} until you have -undone all the changes; but reverting is easier.) - -@findex set-visited-file-name - @kbd{M-x set-visited-file-name} alters the name of the file that the -current buffer is visiting. It reads the new file name using the -minibuffer. Then it marks the buffer as visiting that file name, and -changes the buffer name correspondingly. @code{set-visited-file-name} -does not save the buffer in the newly visited file; it just alters the -records inside Emacs in case you do save later. It also marks the -buffer as ``modified'' so that @kbd{C-x C-s} in that buffer -@emph{will} save. - -@kindex C-x C-w -@findex write-file - If you wish to mark the buffer as visiting a different file and save -it right away, use @kbd{C-x C-w} (@code{write-file}). This is -equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}, -except that @kbd{C-x C-w} asks for confirmation if the file exists. -@kbd{C-x C-s} used on a buffer that is not visiting a file has the -same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the -buffer as visiting that file, and saves it there. The default file -name in a buffer that is not visiting a file is made by combining the -buffer name with the buffer's default directory (@pxref{File Names}). - - If the new file name implies a major mode, then @kbd{C-x C-w} switches -to that major mode, in most cases. The command -@code{set-visited-file-name} also does this. @xref{Choosing Modes}. - - If Emacs is about to save a file and sees that the date of the latest -version on disk does not match what Emacs last read or wrote, Emacs -notifies you of this fact, because it probably indicates a problem caused -by simultaneous editing and requires your immediate attention. -@xref{Interlocking,, Simultaneous Editing}. - -@node Backup -@subsection Backup Files -@cindex backup file -@vindex make-backup-files -@vindex vc-make-backup-files - - On most operating systems, rewriting a file automatically destroys all -record of what the file used to contain. Thus, saving a file from Emacs -throws away the old contents of the file---or it would, except that -Emacs carefully copies the old contents to another file, called the -@dfn{backup} file, before actually saving. - - Emacs makes a backup for a file only the first time the file is -saved from a buffer. No matter how many times you subsequently save -the file, its backup remains unchanged. However, if you kill the -buffer and then visit the file again, a new backup file will be made. - - For most files, the variable @code{make-backup-files} determines -whether to make backup files. On most operating systems, its default -value is @code{t}, so that Emacs does write backup files. - - For files managed by a version control system (@pxref{Version -Control}), the variable @code{vc-make-backup-files} determines whether -to make backup files. By default it is @code{nil}, since backup files -are redundant when you store all the previous versions in a version -control system. -@iftex -@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{General VC Options}. -@end ifnottex - - At your option, Emacs can keep either a single backup for each file, -or make a series of numbered backup files for each file that you edit. -@xref{Backup Names}. - -@vindex backup-enable-predicate -@vindex temporary-file-directory -@vindex small-temporary-file-directory - The default value of the @code{backup-enable-predicate} variable -prevents backup files being written for files in the directories used -for temporary files, specified by @code{temporary-file-directory} or -@code{small-temporary-file-directory}. - - You can explicitly tell Emacs to make another backup file from a -buffer, even though that buffer has been saved before. If you save -the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made -into a backup file if you save the buffer again. @kbd{C-u C-u C-x -C-s} saves the buffer, but first makes the previous file contents into -a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it -makes a backup from the previous contents, and arranges to make -another from the newly saved contents if you save again. - -@menu -* Names: Backup Names. How backup files are named. -* Deletion: Backup Deletion. Emacs deletes excess numbered backups. -* Copying: Backup Copying. Backups can be made by copying or renaming. -@end menu - -@node Backup Names -@subsubsection Single or Numbered Backups - - When Emacs makes a backup file, its name is normally constructed by -appending @samp{~} to the file name being edited; thus, the backup -file for @file{eval.c} would be @file{eval.c~}. - - If access control stops Emacs from writing backup files under the -usual names, it writes the backup file as @file{~/.emacs.d/%backup%~}. -Only one such file can exist, so only the most recently made such -backup is available. - - Emacs can also make @dfn{numbered backup files}. Numbered backup -file names contain @samp{.~}, the number, and another @samp{~} after -the original file name. Thus, the backup files of @file{eval.c} would -be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way -through names like @file{eval.c.~259~} and beyond. - -@vindex version-control - The variable @code{version-control} determines whether to make -single backup files or multiple numbered backup files. Its possible -values are: - -@table @code -@item nil -Make numbered backups for files that have numbered backups already. -Otherwise, make single backups. This is the default. -@item t -Make numbered backups. -@item never -Never make numbered backups; always make single backups. -@end table - -@noindent -The usual way to set this variable is globally, through your init file -or the customization buffer. However, you can set -@code{version-control} locally in an individual buffer to control the -making of backups for that buffer's file (@pxref{Locals}). You can -have Emacs set @code{version-control} locally whenever you visit a -given file (@pxref{File Variables}). Some modes, such as Rmail mode, -set this variable. - -@cindex @env{VERSION_CONTROL} environment variable - If you set the environment variable @env{VERSION_CONTROL}, to tell -various GNU utilities what to do with backup files, Emacs also obeys the -environment variable by setting the Lisp variable @code{version-control} -accordingly at startup. If the environment variable's value is @samp{t} -or @samp{numbered}, then @code{version-control} becomes @code{t}; if the -value is @samp{nil} or @samp{existing}, then @code{version-control} -becomes @code{nil}; if it is @samp{never} or @samp{simple}, then -@code{version-control} becomes @code{never}. - -@vindex backup-directory-alist - You can customize the variable @code{backup-directory-alist} to -specify that files matching certain patterns should be backed up in -specific directories. This variable applies to both single and -numbered backups. A typical use is to add an element @code{("." -. @var{dir})} to make all backups in the directory with absolute name -@var{dir}; Emacs modifies the backup file names to avoid clashes -between files with the same names originating in different -directories. Alternatively, adding, @code{("." . ".~")} would make -backups in the invisible subdirectory @file{.~} of the original file's -directory. Emacs creates the directory, if necessary, to make the -backup. - -@vindex make-backup-file-name-function - If you set the variable @code{make-backup-file-name-function} to -a suitable Lisp function, you can override the usual way Emacs -constructs backup file names. - -@node Backup Deletion -@subsubsection Automatic Deletion of Backups - - To prevent excessive consumption of disk space, Emacs can delete numbered -backup versions automatically. Generally Emacs keeps the first few backups -and the latest few backups, deleting any in between. This happens every -time a new backup is made. - -@vindex kept-old-versions -@vindex kept-new-versions - The two variables @code{kept-old-versions} and -@code{kept-new-versions} control this deletion. Their values are, -respectively, the number of oldest (lowest-numbered) backups to keep -and the number of newest (highest-numbered) ones to keep, each time a -new backup is made. The backups in the middle (excluding those oldest -and newest) are the excess middle versions---those backups are -deleted. These variables' values are used when it is time to delete -excess versions, just after a new backup version is made; the newly -made backup is included in the count in @code{kept-new-versions}. By -default, both variables are 2. - -@vindex delete-old-versions - If @code{delete-old-versions} is @code{t}, Emacs deletes the excess -backup files silently. If it is @code{nil}, the default, Emacs asks -you whether it should delete the excess backup versions. If it has -any other value, then Emacs never automatically deletes backups. - - Dired's @kbd{.} (Period) command can also be used to delete old versions. -@xref{Dired Deletion}. - -@node Backup Copying -@subsubsection Copying vs.@: Renaming - - Backup files can be made by copying the old file or by renaming it. -This makes a difference when the old file has multiple names (hard -links). If the old file is renamed into the backup file, then the -alternate names become names for the backup file. If the old file is -copied instead, then the alternate names remain names for the file -that you are editing, and the contents accessed by those names will be -the new contents. - - The method of making a backup file may also affect the file's owner -and group. If copying is used, these do not change. If renaming is used, -you become the file's owner, and the file's group becomes the default -(different operating systems have different defaults for the group). - -@vindex backup-by-copying -@vindex backup-by-copying-when-linked -@vindex backup-by-copying-when-mismatch -@vindex backup-by-copying-when-privileged-mismatch -@cindex file ownership, and backup -@cindex backup, and user-id - The choice of renaming or copying is made as follows: - -@itemize -@item -If the variable @code{backup-by-copying} is non-@code{nil} (the -default is @code{nil}), use copying. - -@item -Otherwise, if the variable @code{backup-by-copying-when-linked} is -non-@code{nil} (the default is @code{nil}), and the file has multiple -names, use copying. - -@item -Otherwise, if the variable @code{backup-by-copying-when-mismatch} is -non-@code{nil} (the default is @code{t}), and renaming would change -the file's owner or group, use copying. - -If you change @code{backup-by-copying-when-mismatch} to @code{nil}, -Emacs checks the numeric user-id of the file's owner. If this is -higher than @code{backup-by-copying-when-privileged-mismatch}, then it -behaves as though @code{backup-by-copying-when-mismatch} is -non-@code{nil} anyway. - -@item -Otherwise, renaming is the default choice. -@end itemize - - When a file is managed with a version control system (@pxref{Version -Control}), Emacs does not normally make backups in the usual way for -that file. But check-in and check-out are similar in some ways to -making backups. One unfortunate similarity is that these operations -typically break hard links, disconnecting the file name you visited from -any alternate names for the same file. This has nothing to do with -Emacs---the version control system does it. - -@node Customize Save -@subsection Customizing Saving of Files - -@vindex require-final-newline - If the value of the variable @code{require-final-newline} is -@code{t}, saving or writing a file silently puts a newline at the end -if there isn't already one there. If the value is @code{visit}, Emacs -adds a newline at the end of any file that doesn't have one, just -after it visits the file. (This marks the buffer as modified, and you -can undo it.) If the value is @code{visit-save}, Emacs adds such -newlines both on visiting and on saving. If the value is @code{nil}, -Emacs leaves the end of the file unchanged; any other non-@code{nil} -value means to asks you whether to add a newline. The default is -@code{nil}. - -@vindex mode-require-final-newline - Some major modes are designed for specific kinds of files that are -always supposed to end in newlines. Such major modes set the variable -@code{require-final-newline} to the value of -@code{mode-require-final-newline}, which defaults to @code{t}. By -setting the latter variable, you can control how these modes handle -final newlines. - -@vindex write-region-inhibit-fsync - Normally, when a program writes a file, the operating system briefly -caches the file's data in main memory before committing the data to -disk. This can greatly improve performance; for example, when running -on laptops, it can avoid a disk spin-up each time a file is written. -However, it risks data loss if the operating system crashes before -committing the cache to disk. - - To lessen this risk, Emacs can invoke the @code{fsync} system call -after saving a file. Using @code{fsync} does not eliminate the risk -of data loss, partly because many systems do not implement -@code{fsync} properly, and partly because Emacs's file-saving -procedure typically relies also on directory updates that might not -survive a crash even if @code{fsync} works properly. - - The @code{write-region-inhibit-fsync} variable controls whether -Emacs invokes @code{fsync} after saving a file. The variable's -default value is @code{nil} when Emacs is interactive, and @code{t} -when Emacs runs in batch mode. - - Emacs never uses @code{fsync} when writing auto-save files, as these -files might lose data anyway. - -@node Interlocking -@subsection Protection against Simultaneous Editing - -@cindex file dates -@cindex simultaneous editing - Simultaneous editing occurs when two users visit the same file, both -make changes, and then both save them. If nobody is informed that -this is happening, whichever user saves first would later find that -his changes were lost. - - On some systems, Emacs notices immediately when the second user starts -to change the file, and issues an immediate warning. On all systems, -Emacs checks when you save the file, and warns if you are about to -overwrite another user's changes. You can prevent loss of the other -user's work by taking the proper corrective action instead of saving the -file. - -@findex ask-user-about-lock -@cindex locking files - When you make the first modification in an Emacs buffer that is -visiting a file, Emacs records that the file is @dfn{locked} by you. -(It does this by creating a specially-named symbolic link@footnote{If -your file system does not support symbolic links, a regular file is -used.} with special contents in the same directory.) Emacs removes the lock -when you save the changes. The idea is that the file is locked -whenever an Emacs buffer visiting it has unsaved changes. - -@vindex create-lockfiles - You can prevent the creation of lock files by setting the variable -@code{create-lockfiles} to @code{nil}. @strong{Caution:} by -doing so you will lose the benefits that this feature provides. - -@cindex collision - If you begin to modify the buffer while the visited file is locked by -someone else, this constitutes a @dfn{collision}. When Emacs detects a -collision, it asks you what to do, by calling the Lisp function -@code{ask-user-about-lock}. You can redefine this function for the sake -of customization. The standard definition of this function asks you a -question and accepts three possible answers: - -@table @kbd -@item s -Steal the lock. Whoever was already changing the file loses the lock, -and you gain the lock. -@item p -Proceed. Go ahead and edit the file despite its being locked by someone else. -@item q -Quit. This causes an error (@code{file-locked}), and the buffer -contents remain unchanged---the modification you were trying to make -does not actually take place. -@end table - - If Emacs or the operating system crashes, this may leave behind lock -files which are stale, so you may occasionally get warnings about -spurious collisions. When you determine that the collision is -spurious, just use @kbd{p} to tell Emacs to go ahead anyway. - - Note that locking works on the basis of a file name; if a file has -multiple names, Emacs does not prevent two users from editing it -simultaneously under different names. - - A lock file cannot be written in some circumstances, e.g., if Emacs -lacks the system permissions or cannot create lock files for some -other reason. In these cases, Emacs can still detect the collision -when you try to save a file, by checking the file's last-modification -date. If the file has changed since the last time Emacs visited or -saved it, that implies that changes have been made in some other way, -and will be lost if Emacs proceeds with saving. Emacs then displays a -warning message and asks for confirmation before saving; answer -@kbd{yes} to save, and @kbd{no} or @kbd{C-g} cancel the save. - - If you are notified that simultaneous editing has already taken -place, one way to compare the buffer to its file is the @kbd{M-x -diff-buffer-with-file} command. @xref{Comparing Files}. - -@node File Shadowing -@subsection Shadowing Files -@cindex shadow files -@cindex file shadows -@findex shadow-initialize - -@table @kbd -@item M-x shadow-initialize -Set up file shadowing. -@item M-x shadow-define-literal-group -Declare a single file to be shared between sites. -@item M-x shadow-define-regexp-group -Make all files that match each of a group of files be shared between hosts. -@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} -Define a shadow file cluster @var{name}. -@item M-x shadow-copy-files -Copy all pending shadow files. -@item M-x shadow-cancel -Cancel the instruction to shadow some files. -@end table - -You can arrange to keep identical @dfn{shadow} copies of certain files -in more than one place---possibly on different machines. To do this, -first you must set up a @dfn{shadow file group}, which is a set of -identically-named files shared between a list of sites. The file -group is permanent and applies to further Emacs sessions as well as -the current one. Once the group is set up, every time you exit Emacs, -it will copy the file you edited to the other files in its group. You -can also do the copying without exiting Emacs, by typing @kbd{M-x -shadow-copy-files}. - -To set up a shadow file group, use @kbd{M-x -shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. -See their documentation strings for further information. - -Before copying a file to its shadows, Emacs asks for confirmation. -You can answer ``no'' to bypass copying of this file, this time. If -you want to cancel the shadowing permanently for a certain file, use -@kbd{M-x shadow-cancel} to eliminate or change the shadow file group. - -A @dfn{shadow cluster} is a group of hosts that share directories, so -that copying to or from one of them is sufficient to update the file -on all of them. Each shadow cluster has a name, and specifies the -network address of a primary host (the one we copy files to), and a -regular expression that matches the host names of all the other hosts -in the cluster. You can define a shadow cluster with @kbd{M-x -shadow-define-cluster}. - -@node Time Stamps -@subsection Updating Time Stamps Automatically -@cindex time stamps -@cindex modification dates -@cindex locale, date format - -You can arrange to put a time stamp in a file, so that it is updated -automatically each time you edit and save the file. The time stamp -must be in the first eight lines of the file, and you should insert it -like this: - -@example -Time-stamp: <> -@end example - -@noindent -or like this: - -@example -Time-stamp: " " -@end example - -@findex time-stamp - Then add the function @code{time-stamp} to the hook -@code{before-save-hook} (@pxref{Hooks}). When you save the file, this -function then automatically updates the time stamp with the current -date and time. You can also use the command @kbd{M-x time-stamp} to -update the time stamp manually. For other customizations, see the -Custom group @code{time-stamp}. Note that the time stamp is formatted -according to your locale setting (@pxref{Environment}). - -@node Reverting -@section Reverting a Buffer -@findex revert-buffer -@cindex drastic changes -@cindex reread a file - - If you have made extensive changes to a file-visiting buffer and -then change your mind, you can @dfn{revert} the changes and go back to -the saved version of the file. To do this, type @kbd{M-x -revert-buffer}. Since reverting unintentionally could lose a lot of -work, Emacs asks for confirmation first. - - The @code{revert-buffer} command tries to position point in such a -way that, if the file was edited only slightly, you will be at -approximately the same part of the text as before. But if you have -made major changes, point may end up in a totally different location. - - Reverting marks the buffer as ``not modified''. It also clears the -buffer's undo history (@pxref{Undo}). Thus, the reversion cannot be -undone---if you change your mind yet again, you can't use the undo -commands to bring the reverted changes back. - - Some kinds of buffers that are not associated with files, such as -Dired buffers, can also be reverted. For them, reverting means -recalculating their contents. Buffers created explicitly with -@kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error -if you try. - -@vindex revert-without-query - When you edit a file that changes automatically and frequently---for -example, a log of output from a process that continues to run---it may -be useful for Emacs to revert the file without querying you. To -request this behavior, set the variable @code{revert-without-query} to -a list of regular expressions. When a file name matches one of these -regular expressions, @code{find-file} and @code{revert-buffer} will -revert it automatically if it has changed---provided the buffer itself -is not modified. (If you have edited the text, it would be wrong to -discard your changes.) - -@cindex Global Auto-Revert mode -@cindex mode, Global Auto-Revert -@cindex Auto-Revert mode -@cindex mode, Auto-Revert -@findex global-auto-revert-mode -@findex auto-revert-mode -@findex auto-revert-tail-mode -@vindex auto-revert-interval - You can also tell Emacs to revert buffers periodically. To do this -for a specific buffer, enable the minor mode Auto-Revert mode by -typing @kbd{M-x auto-revert-mode}. This automatically reverts the -current buffer every five seconds; you can change the interval through -the variable @code{auto-revert-interval}. To do the same for all file -buffers, type @kbd{M-x global-auto-revert-mode} to enable Global -Auto-Revert mode. These minor modes do not check or revert remote -files, because that is usually too slow. - - One use of Auto-Revert mode is to ``tail'' a file such as a system -log, so that changes made to that file by other programs are -continuously displayed. To do this, just move the point to the end of -the buffer, and it will stay there as the file contents change. -However, if you are sure that the file will only change by growing at -the end, use Auto-Revert Tail mode instead -(@code{auto-revert-tail-mode}). It is more efficient for this. -Auto-Revert Tail mode works also for remote files. - - @xref{VC Undo}, for commands to revert to earlier versions of files -under version control. @xref{VC Mode Line}, for Auto Revert -peculiarities when visiting files under version control. - -@ifnottex -@include arevert-xtra.texi -@end ifnottex - -@node Auto Save -@section Auto-Saving: Protection Against Disasters -@cindex Auto Save mode -@cindex mode, Auto Save -@cindex crashes - - From time to time, Emacs automatically saves each visited file in a -separate file, without altering the file you actually use. This is -called @dfn{auto-saving}. It prevents you from losing more than a -limited amount of work if the system crashes. - - When Emacs determines that it is time for auto-saving, it considers -each buffer, and each is auto-saved if auto-saving is enabled for it -and it has been changed since the last time it was auto-saved. The -message @samp{Auto-saving...} is displayed in the echo area during -auto-saving, if any files are actually auto-saved. Errors occurring -during auto-saving are caught so that they do not interfere with the -execution of commands you have been typing. - -@menu -* Files: Auto Save Files. The file where auto-saved changes are - actually made until you save the file. -* Control: Auto Save Control. Controlling when and how often to auto-save. -* Recover:: Recovering text from auto-save files. -@end menu - -@node Auto Save Files -@subsection Auto-Save Files - - Auto-saving does not normally save in the files that you visited, -because it can be very undesirable to save a change that you did not -want to make permanent. Instead, auto-saving is done in a different -file called the @dfn{auto-save file}, and the visited file is changed -only when you request saving explicitly (such as with @kbd{C-x C-s}). - - Normally, the auto-save file name is made by appending @samp{#} to the -front and rear of the visited file name. Thus, a buffer visiting file -@file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that -are not visiting files are auto-saved only if you request it explicitly; -when they are auto-saved, the auto-save file name is made by appending -@samp{#} to the front and rear of buffer name, then -adding digits and letters at the end for uniqueness. For -example, the @file{*mail*} buffer in which you compose messages to be -sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file -names are made this way unless you reprogram parts of Emacs to do -something different (the functions @code{make-auto-save-file-name} and -@code{auto-save-file-name-p}). The file name to be used for auto-saving -in a buffer is calculated when auto-saving is turned on in that buffer. - -@cindex auto-save for remote files -@vindex auto-save-file-name-transforms - The variable @code{auto-save-file-name-transforms} allows a degree -of control over the auto-save file name. It lets you specify a series -of regular expressions and replacements to transform the auto save -file name. The default value puts the auto-save files for remote -files (@pxref{Remote Files}) into the temporary file directory on the -local machine. - - When you delete a substantial part of the text in a large buffer, auto -save turns off temporarily in that buffer. This is because if you -deleted the text unintentionally, you might find the auto-save file more -useful if it contains the deleted text. To reenable auto-saving after -this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x -auto-save-mode}. - -@vindex auto-save-visited-file-name - If you want auto-saving to be done in the visited file rather than -in a separate auto-save file, set the variable -@code{auto-save-visited-file-name} to a non-@code{nil} value. In this -mode, there is no real difference between auto-saving and explicit -saving. - -@vindex delete-auto-save-files - A buffer's auto-save file is deleted when you save the buffer in its -visited file. (You can inhibit this by setting the variable -@code{delete-auto-save-files} to @code{nil}.) Changing the visited -file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames -any auto-save file to go with the new visited name. - -@node Auto Save Control -@subsection Controlling Auto-Saving - -@vindex auto-save-default -@findex auto-save-mode - Each time you visit a file, auto-saving is turned on for that file's -buffer if the variable @code{auto-save-default} is non-@code{nil} (but -not in batch mode; @pxref{Initial Options}). The default for this -variable is @code{t}, so auto-saving is the usual practice for -file-visiting buffers. To toggle auto-saving in the current buffer, -type @kbd{M-x auto-save-mode}. Auto Save mode acts as a buffer-local -minor mode (@pxref{Minor Modes}). - -@vindex auto-save-interval - Emacs auto-saves periodically based on how many characters you have -typed since the last auto-save. The variable -@code{auto-save-interval} specifies how many characters there are -between auto-saves. By default, it is 300. Emacs doesn't accept -values that are too small: if you customize @code{auto-save-interval} -to a value less than 20, Emacs will behave as if the value is 20. - -@vindex auto-save-timeout - Auto-saving also takes place when you stop typing for a while. By -default, it does this after 30 seconds of idleness (at this time, -Emacs may also perform garbage collection; @pxref{Garbage -Collection,,, elisp, The Emacs Lisp Reference Manual}). To change -this interval, customize the variable @code{auto-save-timeout}. The -actual time period is longer if the current buffer is long; this is a -heuristic which aims to keep out of your way when you are editing long -buffers, in which auto-save takes an appreciable amount of time. -Auto-saving during idle periods accomplishes two things: first, it -makes sure all your work is saved if you go away from the terminal for -a while; second, it may avoid some auto-saving while you are actually -typing. - - Emacs also does auto-saving whenever it gets a fatal error. This -includes killing the Emacs job with a shell command such as @samp{kill -%emacs}, or disconnecting a phone line or network connection. - -@findex do-auto-save - You can perform an auto-save explicitly with the command @kbd{M-x -do-auto-save}. - -@node Recover -@subsection Recovering Data from Auto-Saves - -@findex recover-file - You can use the contents of an auto-save file to recover from a loss -of data with the command @kbd{M-x recover-file @key{RET} @var{file} -@key{RET}}. This visits @var{file} and then (after your confirmation) -restores the contents from its auto-save file @file{#@var{file}#}. -You can then save with @kbd{C-x C-s} to put the recovered text into -@var{file} itself. For example, to recover file @file{foo.c} from its -auto-save file @file{#foo.c#}, do: - -@example -M-x recover-file @key{RET} foo.c @key{RET} -yes @key{RET} -C-x C-s -@end example - - Before asking for confirmation, @kbd{M-x recover-file} displays a -directory listing describing the specified file and the auto-save file, -so you can compare their sizes and dates. If the auto-save file -is older, @kbd{M-x recover-file} does not offer to read it. - -@findex recover-session - If Emacs or the computer crashes, you can recover all the files you -were editing from their auto save files with the command @kbd{M-x -recover-session}. This first shows you a list of recorded interrupted -sessions. Move point to the one you choose, and type @kbd{C-c C-c}. - - Then @code{recover-session} asks about each of the files that were -being edited during that session, asking whether to recover that file. -If you answer @kbd{y}, it calls @code{recover-file}, which works in its -normal fashion. It shows the dates of the original file and its -auto-save file, and asks once again whether to recover that file. - - When @code{recover-session} is done, the files you've chosen to -recover are present in Emacs buffers. You should then save them. Only -this---saving them---updates the files themselves. - -@vindex auto-save-list-file-prefix - Emacs records information about interrupted sessions in files named -@file{.saves-@var{pid}-@var{hostname}} in the directory -@file{~/.emacs.d/auto-save-list/}. This directory is determined by -the variable @code{auto-save-list-file-prefix}. If you set -@code{auto-save-list-file-prefix} to @code{nil}, sessions are not -recorded for recovery. - -@node File Aliases -@section File Name Aliases -@cindex symbolic links (visiting) -@cindex hard links (visiting) - - Symbolic links and hard links both make it possible for several file -names to refer to the same file. Hard links are alternate names that -refer directly to the file; all the names are equally valid, and no one -of them is preferred. By contrast, a symbolic link is a kind of defined -alias: when @file{foo} is a symbolic link to @file{bar}, you can use -either name to refer to the file, but @file{bar} is the real name, while -@file{foo} is just an alias. More complex cases occur when symbolic -links point to directories. - -@vindex find-file-existing-other-name -@vindex find-file-suppress-same-file-warnings - Normally, if you visit a file which Emacs is already visiting under -a different name, Emacs displays a message in the echo area and uses -the existing buffer visiting that file. This can happen on systems -that support hard or symbolic links, or if you use a long file name on -a system that truncates long file names, or on a case-insensitive file -system. You can suppress the message by setting the variable -@code{find-file-suppress-same-file-warnings} to a non-@code{nil} -value. You can disable this feature entirely by setting the variable -@code{find-file-existing-other-name} to @code{nil}: then if you visit -the same file under two different names, you get a separate buffer for -each file name. - -@vindex find-file-visit-truename -@cindex truenames of files -@cindex file truenames - If the variable @code{find-file-visit-truename} is non-@code{nil}, -then the file name recorded for a buffer is the file's @dfn{truename} -(made by replacing all symbolic links with their target names), rather -than the name you specify. Setting @code{find-file-visit-truename} also -implies the effect of @code{find-file-existing-other-name}. - -@cindex directory name abbreviation -@vindex directory-abbrev-alist - Sometimes, a directory is ordinarily accessed through a symbolic -link, and you may want Emacs to preferentially show its ``linked'' -name. To do this, customize @code{directory-abbrev-alist}. Each -element in this list should have the form @code{(@var{from} -. @var{to})}, which means to replace @var{from} with @var{to} whenever -@var{from} appears in a directory name. The @var{from} string is a -regular expression (@pxref{Regexps}). It is matched against directory -names anchored at the first character, and should start with @samp{\`} -(to support directory names with embedded newlines, which would defeat -@samp{^}). The @var{to} string should be an ordinary absolute -directory name pointing to the same directory. Do not use @samp{~} to -stand for a home directory in the @var{to} string; Emacs performs -these substitutions separately. Here's an example, from a system on -which @file{/home/fsf} is normally accessed through a symbolic link -named @file{/fsf}: - -@example -(("\\`/home/fsf" . "/fsf")) -@end example - -@node Directories -@section File Directories - -@cindex file directory -@cindex directory listing - The file system groups files into @dfn{directories}. A @dfn{directory -listing} is a list of all the files in a directory. Emacs provides -commands to create and delete directories, and to make directory -listings in brief format (file names only) and verbose format (sizes, -dates, and authors included). Emacs also includes a directory browser -feature called Dired; see @ref{Dired}. - -@table @kbd -@item C-x C-d @var{dir-or-pattern} @key{RET} -Display a brief directory listing (@code{list-directory}). -@item C-u C-x C-d @var{dir-or-pattern} @key{RET} -Display a verbose directory listing. -@item M-x make-directory @key{RET} @var{dirname} @key{RET} -Create a new directory named @var{dirname}. -@item M-x delete-directory @key{RET} @var{dirname} @key{RET} -Delete the directory named @var{dirname}. If it isn't empty, -you will be asked whether you want to delete it recursively. -@end table - -@findex list-directory -@kindex C-x C-d - The command to display a directory listing is @kbd{C-x C-d} -(@code{list-directory}). It reads using the minibuffer a file name -which is either a directory to be listed or a wildcard-containing -pattern for the files to be listed. For example, - -@example -C-x C-d /u2/emacs/etc @key{RET} -@end example - -@noindent -lists all the files in directory @file{/u2/emacs/etc}. Here is an -example of specifying a file name pattern: - -@example -C-x C-d /u2/emacs/src/*.c @key{RET} -@end example - - Normally, @kbd{C-x C-d} displays a brief directory listing containing -just file names. A numeric argument (regardless of value) tells it to -make a verbose listing including sizes, dates, and owners (like -@samp{ls -l}). - -@vindex list-directory-brief-switches -@vindex list-directory-verbose-switches - The text of a directory listing is mostly obtained by running -@code{ls} in an inferior process. Two Emacs variables control the -switches passed to @code{ls}: @code{list-directory-brief-switches} is -a string giving the switches to use in brief listings (@code{"-CF"} by -default), and @code{list-directory-verbose-switches} is a string -giving the switches to use in a verbose listing (@code{"-l"} by -default). - -@vindex directory-free-space-program -@vindex directory-free-space-args - In verbose directory listings, Emacs adds information about the -amount of free space on the disk that contains the directory. To do -this, it runs the program specified by -@code{directory-free-space-program} with arguments -@code{directory-free-space-args}. - - The command @kbd{M-x delete-directory} prompts for a directory name -using the minibuffer, and deletes the directory if it is empty. If -the directory is not empty, you will be asked whether you want to -delete it recursively. On systems that have a ``Trash'' (or ``Recycle -Bin'') feature, you can make this command move the specified directory -to the Trash instead of deleting it outright, by changing the variable -@code{delete-by-moving-to-trash} to @code{t}. @xref{Misc File Ops}, -for more information about using the Trash. - -@node Comparing Files -@section Comparing Files -@cindex comparing files - -@findex diff -@vindex diff-switches - The command @kbd{M-x diff} prompts for two file names, using the -minibuffer, and displays the differences between the two files in a -buffer named @file{*diff*}. This works by running the @command{diff} -program, using options taken from the variable @code{diff-switches}. -The value of @code{diff-switches} should be a string; the default is -@code{"-c"} to specify a context diff. -@c Note that the actual name of the info file is diffutils.info, -@c but it adds a dir entry for diff too. -@c On older systems, only "info diff" works, not "info diffutils". -@xref{Top,, Diff, diff, Comparing and Merging Files}, for more -information about the @command{diff} program. - - The output of the @code{diff} command is shown using a major mode -called Diff mode. @xref{Diff Mode}. - -@findex diff-backup - The command @kbd{M-x diff-backup} compares a specified file with its -most recent backup. If you specify the name of a backup file, -@code{diff-backup} compares it with the source file that it is a -backup of. In all other respects, this behaves like @kbd{M-x diff}. - -@findex diff-buffer-with-file - The command @kbd{M-x diff-buffer-with-file} compares a specified -buffer with its corresponding file. This shows you what changes you -would make to the file if you save the buffer. - -@findex compare-windows - The command @kbd{M-x compare-windows} compares the text in the -current window with that in the next window. (For more information -about windows in Emacs, @ref{Windows}.) Comparison starts at point in -each window, after pushing each initial point value on the mark ring -in its respective buffer. Then it moves point forward in each window, -one character at a time, until it reaches characters that don't match. -Then the command exits. - - If point in the two windows is followed by non-matching text when -the command starts, @kbd{M-x compare-windows} tries heuristically to -advance up to matching text in the two windows, and then exits. So if -you use @kbd{M-x compare-windows} repeatedly, each time it either -skips one matching range or finds the start of another. - -@vindex compare-ignore-case -@vindex compare-ignore-whitespace - With a numeric argument, @code{compare-windows} ignores changes in -whitespace. If the variable @code{compare-ignore-case} is -non-@code{nil}, the comparison ignores differences in case as well. -If the variable @code{compare-ignore-whitespace} is non-@code{nil}, -@code{compare-windows} normally ignores changes in whitespace, and a -prefix argument turns that off. - -@cindex Smerge mode -@findex smerge-mode -@cindex failed merges -@cindex merges, failed -@cindex comparing 3 files (@code{diff3}) - You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor -mode for editing output from the @command{diff3} program. This is -typically the result of a failed merge from a version control system -``update'' outside VC, due to conflicting changes to a file. Smerge -mode provides commands to resolve conflicts by selecting specific -changes. - -@iftex -@xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{Emerge}, -@end ifnottex -for the Emerge facility, which provides a powerful interface for -merging files. - -@node Diff Mode -@section Diff Mode -@cindex Diff mode -@findex diff-mode -@cindex patches, editing - - Diff mode is a major mode used for the output of @kbd{M-x diff} and -other similar commands. This kind of output is called a @dfn{patch}, -because it can be passed to the @command{patch} command to -automatically apply the specified changes. To select Diff mode -manually, type @kbd{M-x diff-mode}. - -@cindex hunk, diff - The changes specified in a patch are grouped into @dfn{hunks}, which -are contiguous chunks of text that contain one or more changed lines. -Hunks can also include unchanged lines to provide context for the -changes. Each hunk is preceded by a @dfn{hunk header}, which -specifies the old and new line numbers at which the hunk occurs. Diff -mode highlights each hunk header, to distinguish it from the actual -contents of the hunk. - -@vindex diff-update-on-the-fly - You can edit a Diff mode buffer like any other buffer. (If it is -read-only, you need to make it writable first. @xref{Misc Buffer}.) -Whenever you change a hunk, Diff mode attempts to automatically -correct the line numbers in the hunk headers, to ensure that the patch -remains ``correct''. To disable automatic line number correction, -change the variable @code{diff-update-on-the-fly} to @code{nil}. - - Diff mode treats each hunk as an ``error message'', similar to -Compilation mode. Thus, you can use commands such as @kbd{C-x '} to -visit the corresponding source locations. @xref{Compilation Mode}. - - In addition, Diff mode provides the following commands to navigate, -manipulate and apply parts of patches: - -@table @kbd -@item M-n -@findex diff-hunk-next -Move to the next hunk-start (@code{diff-hunk-next}). - -@findex diff-auto-refine-mode -@cindex mode, Diff Auto-Refine -@cindex Diff Auto-Refine mode -This command has a side effect: it @dfn{refines} the hunk you move to, -highlighting its changes with better granularity. To disable this -feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor -mode Diff Auto-Refine mode. To disable Diff Auto Refine mode by -default, add this to your init file (@pxref{Hooks}): - -@example -(add-hook 'diff-mode-hook - (lambda () (diff-auto-refine-mode -1))) -@end example - -@item M-p -@findex diff-hunk-prev -Move to the previous hunk-start (@code{diff-hunk-prev}). Like -@kbd{M-n}, this has the side-effect of refining the hunk you move to, -unless you disable Diff Auto-Refine mode. - -@item M-@} -@findex diff-file-next -Move to the next file-start, in a multi-file patch -(@code{diff-file-next}). - -@item M-@{ -@findex diff-file-prev -Move to the previous file-start, in a multi-file patch -(@code{diff-file-prev}). - -@item M-k -@findex diff-hunk-kill -Kill the hunk at point (@code{diff-hunk-kill}). - -@item M-K -@findex diff-file-kill -In a multi-file patch, kill the current file part. -(@code{diff-file-kill}). - -@item C-c C-a -@findex diff-apply-hunk -@cindex patches, applying -Apply this hunk to its target file (@code{diff-apply-hunk}). With a -prefix argument of @kbd{C-u}, revert this hunk. - -@item C-c C-b -@findex diff-refine-hunk -Highlight the changes of the hunk at point with a finer granularity -(@code{diff-refine-hunk}). This allows you to see exactly which parts -of each changed line were actually changed. - -@item C-c C-c -@findex diff-goto-source -Go to the source file and line corresponding to this hunk -(@code{diff-goto-source}). - -@item C-c C-e -@findex diff-ediff-patch -Start an Ediff session with the patch (@code{diff-ediff-patch}). -@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. - -@item C-c C-n -@findex diff-restrict-view -Restrict the view to the current hunk (@code{diff-restrict-view}). -@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the -view to the current file of a multiple-file patch. To widen again, -use @kbd{C-x n w} (@code{widen}). - -@item C-c C-r -@findex diff-reverse-direction -Reverse the direction of comparison for the entire buffer -(@code{diff-reverse-direction}). - -@item C-c C-s -@findex diff-split-hunk -Split the hunk at point (@code{diff-split-hunk}). This is for -manually editing patches, and only works with the @dfn{unified diff -format} produced by the @option{-u} or @option{--unified} options to -the @command{diff} program. If you need to split a hunk in the -@dfn{context diff format} produced by the @option{-c} or -@option{--context} options to @command{diff}, first convert the buffer -to the unified diff format with @kbd{C-c C-u}. - -@item C-c C-d -@findex diff-unified->context -Convert the entire buffer to the @dfn{context diff format} -(@code{diff-unified->context}). With a prefix argument, convert only -the text within the region. - -@item C-c C-u -@findex diff-context->unified -Convert the entire buffer to unified diff format -(@code{diff-context->unified}). With a prefix argument, convert -unified format to context format. When the mark is active, convert -only the text within the region. - -@item C-c C-w -@findex diff-refine-hunk -Refine the current hunk so that it disregards changes in whitespace -(@code{diff-refine-hunk}). - -@item C-x 4 A -@findex diff-add-change-log-entries-other-window -@findex add-change-log-entry-other-window@r{, in Diff mode} -Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change -Log}), for each one of the hunks -(@code{diff-add-change-log-entries-other-window}). This creates a -skeleton of the log of changes that you can later fill with the actual -descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode -operates on behalf of the current hunk's file, but gets the function -name from the patch itself. This is useful for making log entries for -functions that are deleted by the patch. -@end table - -@c Trailing whitespace is NOT shown by default. -@c Emacs's dir-locals file enables this (for some reason). -@cindex trailing whitespace, in patches -@findex diff-delete-trailing-whitespace - Patches sometimes include trailing whitespace on modified lines, as -an unintentional and undesired change. There are two ways to deal -with this problem. Firstly, if you enable Whitespace mode in a Diff -buffer (@pxref{Useless Whitespace}), it automatically highlights -trailing whitespace in modified lines. Secondly, you can use the -command @kbd{M-x diff-delete-trailing-whitespace}, which searches for -trailing whitespace in the lines modified by the patch, and removes -that whitespace in both the patch and the patched source file(s). -This command does not save the modifications that it makes, so you can -decide whether to save the changes (the list of modified files is -displayed in the echo area). With a prefix argument, it tries to -modify the original source files rather than the patched source files. - -@node Misc File Ops -@section Miscellaneous File Operations - - Emacs has commands for performing many other operations on files. -All operate on one file; they do not accept wildcard file names. - -@findex delete-file -@cindex deletion (of files) - @kbd{M-x delete-file} prompts for a file and deletes it. If you are -deleting many files in one directory, it may be more convenient to use -Dired rather than @code{delete-file}. @xref{Dired Deletion}. - -@cindex trash -@cindex recycle bin - @kbd{M-x move-file-to-trash} moves a file into the system -@dfn{Trash} (or @dfn{Recycle Bin}). This is a facility available on -most operating systems; files that are moved into the Trash can be -brought back later if you change your mind. - -@vindex delete-by-moving-to-trash - By default, Emacs deletion commands do @emph{not} use the Trash. To -use the Trash (when it is available) for common deletion commands, -change the variable @code{delete-by-moving-to-trash} to @code{t}. -This affects the commands @kbd{M-x delete-file} and @kbd{M-x -delete-directory} (@pxref{Directories}), as well as the deletion -commands in Dired (@pxref{Dired Deletion}). Supplying a prefix -argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes -them delete outright, instead of using the Trash, regardless of -@code{delete-by-moving-to-trash}. - -@ifnottex - If a file is under version control (@pxref{Version Control}), you -should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x -delete-file}. @xref{VC Delete/Rename}. -@end ifnottex - -@findex copy-file -@cindex copying files - @kbd{M-x copy-file} reads the file @var{old} and writes a new file -named @var{new} with the same contents. - -@findex copy-directory - @kbd{M-x copy-directory} copies directories, similar to the -@command{cp -r} shell command. It prompts for a directory @var{old} -and a destination @var{new}. If @var{new} is an existing directory, -it creates a copy of the @var{old} directory and puts it in @var{new}. -If @var{new} is not an existing directory, it copies all the contents -of @var{old} into a new directory named @var{new}. - -@cindex renaming files -@findex rename-file - @kbd{M-x rename-file} reads two file names @var{old} and @var{new} -using the minibuffer, then renames file @var{old} as @var{new}. If -the file name @var{new} already exists, you must confirm with -@kbd{yes} or renaming is not done; this is because renaming causes the -old meaning of the name @var{new} to be lost. If @var{old} and -@var{new} are on different file systems, the file @var{old} is copied -and deleted. If the argument @var{new} is just a directory name, the -real new name is in that directory, with the same non-directory -component as @var{old}. For example, @kbd{M-x rename-file @key{RET} -~/foo @key{RET} /tmp @key{RET}} renames @file{~/foo} to -@file{/tmp/foo}. The same rule applies to all the remaining commands -in this section. All of them ask for confirmation when the new file -name already exists, too. - -@ifnottex - If a file is under version control (@pxref{Version Control}), you -should rename it using @kbd{M-x vc-rename-file} instead of @kbd{M-x -rename-file}. @xref{VC Delete/Rename}. -@end ifnottex - -@findex add-name-to-file -@cindex hard links (creation) - @kbd{M-x add-name-to-file} adds an additional name to an existing -file without removing its old name. The new name is created as a -``hard link'' to the existing file. The new name must belong on the -same file system that the file is on. On MS-Windows, this command -works only if the file resides in an NTFS file system. On MS-DOS, it -works by copying the file. - -@findex make-symbolic-link -@cindex symbolic links (creation) - @kbd{M-x make-symbolic-link} reads two file names @var{target} and -@var{linkname}, then creates a symbolic link named @var{linkname}, -which points at @var{target}. The effect is that future attempts to -open file @var{linkname} will refer to whatever file is named -@var{target} at the time the opening is done, or will get an error if -the name @var{target} is nonexistent at that time. This command does -not expand the argument @var{target}, so that it allows you to specify -a relative name as the target of the link. On MS-Windows, this -command works only on MS Windows Vista and later. - -@kindex C-x i -@findex insert-file - @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the -contents of the specified file into the current buffer at point, -leaving point unchanged before the contents. The position after the -inserted contents is added to the mark ring, without activating the -mark (@pxref{Mark Ring}). - -@findex insert-file-literally - @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, -except the file is inserted ``literally'': it is treated as a sequence -of @acronym{ASCII} characters with no special encoding or conversion, -similar to the @kbd{M-x find-file-literally} command -(@pxref{Visiting}). - -@findex write-region - @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it -copies the contents of the region into the specified file. @kbd{M-x -append-to-file} adds the text of the region to the end of the -specified file. @xref{Accumulating Text}. The variable -@code{write-region-inhibit-fsync} applies to these commands, as well -as saving files; see @ref{Customize Save}. - -@findex set-file-modes -@cindex file modes -@cindex file permissions - @kbd{M-x set-file-modes} reads a file name followed by a @dfn{file -mode}, and applies that file mode to the specified file. File modes, -also called @dfn{file permissions}, determine whether a file can be -read, written to, or executed, and by whom. This command reads file -modes using the same symbolic or octal format accepted by the -@command{chmod} command; for instance, @samp{u+x} means to add -execution permission for the user who owns the file. It has no effect -on operating systems that do not support file modes. @code{chmod} is a -convenience alias for this function. - -@node Compressed Files -@section Accessing Compressed Files -@cindex compression -@cindex uncompression -@cindex Auto Compression mode -@cindex mode, Auto Compression -@pindex gzip - - Emacs automatically uncompresses compressed files when you visit -them, and automatically recompresses them if you alter them and save -them. Emacs recognizes compressed files by their file names. File -names ending in @samp{.gz} indicate a file compressed with -@code{gzip}. Other endings indicate other compression programs. - - Automatic uncompression and compression apply to all the operations in -which Emacs uses the contents of a file. This includes visiting it, -saving it, inserting its contents into a buffer, loading it, and byte -compiling it. - -@findex auto-compression-mode -@vindex auto-compression-mode - To disable this feature, type the command @kbd{M-x -auto-compression-mode}. You can disable it permanently by -customizing the variable @code{auto-compression-mode}. - -@node File Archives -@section File Archives -@cindex mode, tar -@cindex Tar mode -@cindex file archives - - A file whose name ends in @samp{.tar} is normally an @dfn{archive} -made by the @code{tar} program. Emacs views these files in a special -mode called Tar mode which provides a Dired-like list of the contents -(@pxref{Dired}). You can move around through the list just as you -would in Dired, and visit the subfiles contained in the archive. -However, not all Dired commands are available in Tar mode. - - If Auto Compression mode is enabled (@pxref{Compressed Files}), then -Tar mode is used also for compressed archives---files with extensions -@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. - - The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file -into its own buffer. You can edit it there, and if you save the -buffer, the edited version will replace the version in the Tar buffer. -Clicking with the mouse on the file name in the Tar buffer does -likewise. @kbd{v} extracts a file into a buffer in View mode -(@pxref{View Mode}). @kbd{o} extracts the file and displays it in -another window, so you could edit the file and operate on the archive -simultaneously. - - @kbd{d} marks a file for deletion when you later use @kbd{x}, and -@kbd{u} unmarks a file, as in Dired. @kbd{C} copies a file from the -archive to disk and @kbd{R} renames a file within the archive. -@kbd{g} reverts the buffer from the archive on disk. The keys -@kbd{M}, @kbd{G}, and @kbd{O} change the file's permission bits, -group, and owner, respectively. - - Saving the Tar buffer writes a new version of the archive to disk with -the changes you made to the components. - - You don't need the @code{tar} program to use Tar mode---Emacs reads -the archives directly. However, accessing compressed archives -requires the appropriate uncompression program. - -@cindex Archive mode -@cindex mode, archive -@cindex @code{arc} -@cindex @code{jar} -@cindex @code{rar} -@cindex @code{zip} -@cindex @code{lzh} -@cindex @code{zoo} -@cindex @code{7z} -@pindex arc -@pindex jar -@pindex zip -@pindex rar -@pindex lzh -@pindex zoo -@pindex 7z -@cindex Java class archives -@cindex unzip archives - A separate but similar Archive mode is used for @code{arc}, -@code{jar}, @code{lzh}, @code{zip}, @code{rar}, @code{7z}, and -@code{zoo} archives, as well as @code{exe} files that are -self-extracting executables. - - The key bindings of Archive mode are similar to those in Tar mode, -with the addition of the @kbd{m} key which marks a file for subsequent -operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. -Also, the @kbd{a} key toggles the display of detailed file -information, for those archive types where it won't fit in a single -line. Operations such as renaming a subfile, or changing its mode or -owner, are supported only for some of the archive formats. - - Unlike Tar mode, Archive mode runs the archiving programs to unpack -and repack archives. However, you don't need these programs to look -at the archive table of contents, only to extract or manipulate the -subfiles in the archive. Details of the program names and their -options can be set in the @samp{Archive} Customize group. - -@node Remote Files -@section Remote Files - -@cindex Tramp -@cindex FTP -@cindex remote file access - You can refer to files on other machines using a special file name -syntax: - -@example -@group -/@var{host}:@var{filename} -/@var{user}@@@var{host}:@var{filename} -/@var{user}@@@var{host}#@var{port}:@var{filename} -/@var{method}:@var{user}@@@var{host}:@var{filename} -/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} -@end group -@end example - -@noindent -To carry out this request, Emacs uses a remote-login program such as -@command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}. -You can always specify in the file name which method to use---for -example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, -whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses -@command{ssh}. When you don't specify a method in the file name, -Emacs chooses the method as follows: - -@enumerate -@item -If the host name starts with @samp{ftp.} (with dot), Emacs uses FTP. -@item -If the user name is @samp{ftp} or @samp{anonymous}, Emacs uses FTP. -@item -If the variable @code{tramp-default-method} is set to @samp{ftp}, -Emacs uses FTP. -@item -If @command{ssh-agent} is running, Emacs uses @command{scp}. -@item -Otherwise, Emacs uses @command{ssh}. -@end enumerate - -@cindex disabling remote files -@noindent -You can entirely turn off the remote file name feature by setting the -variable @code{tramp-mode} to @code{nil}. You can turn off the -feature in individual cases by quoting the file name with @samp{/:} -(@pxref{Quoted File Names}). - -@cindex ange-ftp - Remote file access through FTP is handled by the Ange-FTP package, which -is documented in the following. Remote file access through the other -methods is handled by the Tramp package, which has its own manual. -@xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. - -@vindex ange-ftp-default-user -@cindex user name for remote file access - When the Ange-FTP package is used, Emacs logs in through FTP using -the name @var{user}, if that is specified in the remote file name. If -@var{user} is unspecified, Emacs logs in using your user name on the -local system; but if you set the variable @code{ange-ftp-default-user} -to a string, that string is used instead. When logging in, Emacs may -also ask for a password. - -@cindex backups for remote files -@vindex ange-ftp-make-backup-files - For performance reasons, Emacs does not make backup files for files -accessed via FTP by default. To make it do so, change the variable -@code{ange-ftp-make-backup-files} to a non-@code{nil} value. - - By default, auto-save files for remote files are made in the -temporary file directory on the local machine, as specified by the -variable @code{auto-save-file-name-transforms}. @xref{Auto Save -Files}. - -@cindex anonymous FTP -@vindex ange-ftp-generate-anonymous-password - To visit files accessible by anonymous FTP, you use special user -names @samp{anonymous} or @samp{ftp}. Passwords for these user names -are handled specially. The variable -@code{ange-ftp-generate-anonymous-password} controls what happens: if -the value of this variable is a string, then that string is used as -the password; if non-@code{nil} (the default), then the value of -@code{user-mail-address} is used; if @code{nil}, then Emacs prompts -you for a password as usual (@pxref{Passwords}). - -@cindex firewall, and accessing remote files -@cindex gateway, and remote file access with @code{ange-ftp} -@vindex ange-ftp-smart-gateway -@vindex ange-ftp-gateway-host - Sometimes you may be unable to access files on a remote machine -because a @dfn{firewall} in between blocks the connection for security -reasons. If you can log in on a @dfn{gateway} machine from which the -target files @emph{are} accessible, and whose FTP server supports -gatewaying features, you can still use remote file names; all you have -to do is specify the name of the gateway machine by setting the -variable @code{ange-ftp-gateway-host}, and set -@code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able -to make remote file names work, but the procedure is complex. You can -read the instructions by typing @kbd{M-x finder-commentary @key{RET} -ange-ftp @key{RET}}. - -@node Quoted File Names -@section Quoted File Names - -@cindex quoting file names -@cindex file names, quote special characters - You can @dfn{quote} an absolute file name to prevent special -characters and syntax in it from having their special effects. -The way to do this is to add @samp{/:} at the beginning. - - For example, you can quote a local file name which appears remote, to -prevent it from being treated as a remote file name. Thus, if you have -a directory named @file{/foo:} and a file named @file{bar} in it, you -can refer to that file in Emacs as @samp{/:/foo:/bar}. - - @samp{/:} can also prevent @samp{~} from being treated as a special -character for a user's home directory. For example, @file{/:/tmp/~hack} -refers to a file whose name is @file{~hack} in directory @file{/tmp}. - - Quoting with @samp{/:} is also a way to enter in the minibuffer a -file name that contains @samp{$}. In order for this to work, the -@samp{/:} must be at the beginning of the minibuffer contents. (You -can also double each @samp{$}; see @ref{File Names with $}.) - - You can also quote wildcard characters with @samp{/:}, for visiting. -For example, @file{/:/tmp/foo*bar} visits the file -@file{/tmp/foo*bar}. - - Another method of getting the same result is to enter -@file{/tmp/foo[*]bar}, which is a wildcard specification that matches -only @file{/tmp/foo*bar}. However, in many cases there is no need to -quote the wildcard characters because even unquoted they give the -right result. For example, if the only file name in @file{/tmp} that -starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, -then specifying @file{/tmp/foo*bar} will visit only -@file{/tmp/foo*bar}. - -@node File Name Cache -@section File Name Cache - -@cindex file name caching -@cindex cache of file names -@pindex find -@kindex C-TAB -@findex file-cache-minibuffer-complete - You can use the @dfn{file name cache} to make it easy to locate a -file by name, without having to remember exactly where it is located. -When typing a file name in the minibuffer, @kbd{C-@key{TAB}} -(@code{file-cache-minibuffer-complete}) completes it using the file -name cache. If you repeat @kbd{C-@key{TAB}}, that cycles through the -possible completions of what you had originally typed. (However, note -that the @kbd{C-@key{TAB}} character cannot be typed on most text -terminals.) - - The file name cache does not fill up automatically. Instead, you -load file names into the cache using these commands: - -@findex file-cache-add-directory -@table @kbd -@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} to the file name cache. -@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache. -@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache, using @command{locate} to find -them all. -@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} -Add each file name in each directory listed in @var{variable} to the -file name cache. @var{variable} should be a Lisp variable whose value -is a list of directory names, like @code{load-path}. -@item M-x file-cache-clear-cache @key{RET} -Clear the cache; that is, remove all file names from it. -@end table - - The file name cache is not persistent: it is kept and maintained -only for the duration of the Emacs session. You can view the contents -of the cache with the @code{file-cache-display} command. - -@node File Conveniences -@section Convenience Features for Finding Files - - In this section, we introduce some convenient facilities for finding -recently-opened files, reading file names from a buffer, and viewing -image files. - -@findex recentf-mode -@vindex recentf-mode -@findex recentf-save-list -@findex recentf-edit-list - If you enable Recentf mode, with @kbd{M-x recentf-mode}, the -@samp{File} menu includes a submenu containing a list of recently -opened files. @kbd{M-x recentf-save-list} saves the current -@code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} -edits it. - - The @kbd{M-x ffap} command generalizes @code{find-file} with more -powerful heuristic defaults (@pxref{FFAP}), often based on the text at -point. Partial Completion mode offers other features extending -@code{find-file}, which can be used with @code{ffap}. -@xref{Completion Options}. - -@findex image-mode -@findex image-toggle-display -@findex image-next-file -@findex image-previous-file -@cindex images, viewing - Visiting image files automatically selects Image mode. In this -major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display}) -to toggle between displaying the file as an image in the Emacs buffer, -and displaying its underlying text (or raw byte) representation. -Displaying the file as an image works only if Emacs is compiled with -support for displaying such images. If the displayed image is wider -or taller than the frame, the usual point motion keys (@kbd{C-f}, -@kbd{C-p}, and so forth) cause different parts of the image to be -displayed. You can press @kbd{n} (@code{image-next-file}) and @kbd{p} -(@code{image-previous-file}) to visit the next image file and the -previous image file in the same directory, respectively. - -@findex image-toggle-animation -@findex image-next-frame -@findex image-previous-frame -@findex image-goto-frame -@findex image-increase-speed -@findex image-decrease-speed -@findex image-reset-speed -@findex image-reverse-speed -@vindex image-animate-loop -@cindex image animation -@cindex animated images - If the image can be animated, the command @key{RET} -(@code{image-toggle-animation}) starts or stops the animation. -Animation plays once, unless the option @code{image-animate-loop} is -non-@code{nil}. With @kbd{f} (@code{image-next-frame}) and @kbd{b} -(@code{image-previous-frame}) you can step through the individual -frames. Both commands accept a numeric prefix to step through several -frames at once. You can go to a specific frame with @kbd{F} -(@code{image-goto-frame}). Typing @kbd{a +} -(@code{image-increase-speed}) increases the speed of the animation, -@kbd{a -} (@code{image-decrease-speed}) decreases it, and @kbd{a r} -(@code{image-reverse-speed}) reverses it. The command @kbd{a 0} -(@code{image-reset-speed}) resets the speed to the original value. - -@cindex ImageMagick support -@vindex imagemagick-enabled-types -@vindex imagemagick-types-inhibit - If Emacs was compiled with support for the ImageMagick library, it -can use ImageMagick to render a wide variety of images. The variable -@code{imagemagick-enabled-types} lists the image types that Emacs may -render using ImageMagick; each element in the list should be an -internal ImageMagick name for an image type, as a symbol or an -equivalent string (e.g., @code{BMP} for @file{.bmp} images). To -enable ImageMagick for all possible image types, change -@code{imagemagick-enabled-types} to @code{t}. The variable -@code{imagemagick-types-inhibit} lists the image types which should -never be rendered using ImageMagick, regardless of the value of -@code{imagemagick-enabled-types} (the default list includes types like -@code{C} and @code{HTML}, which ImageMagick can render as an ``image'' -but Emacs should not). To disable ImageMagick entirely, change -@code{imagemagick-types-inhibit} to @code{t}. - -@findex thumbs-mode -@findex mode, thumbs - The Image-Dired package can also be used to view images as -thumbnails. @xref{Image-Dired}. - -@node Filesets -@section Filesets -@cindex filesets -@cindex sets of files - -@findex filesets-init - If you regularly edit a certain group of files, you can define them -as a @dfn{fileset}. This lets you perform certain operations, such as -visiting, @code{query-replace}, and shell commands on all the files at -once. To make use of filesets, you must first add the expression -@code{(filesets-init)} to your init file (@pxref{Init File}). This -adds a @samp{Filesets} menu to the menu bar. - -@findex filesets-add-buffer -@findex filesets-remove-buffer - The simplest way to define a fileset is by adding files to it one at -a time. To add a file to fileset @var{name}, visit the file and type -@kbd{M-x filesets-add-buffer @key{RET} @var{name} @key{RET}}. If -there is no fileset @var{name}, this creates a new one, which -initially contains only the current file. The command @kbd{M-x -filesets-remove-buffer} removes the current file from a fileset. - - You can also edit the list of filesets directly, with @kbd{M-x -filesets-edit} (or by choosing @samp{Edit Filesets} from the -@samp{Filesets} menu). The editing is performed in a Customize buffer -(@pxref{Easy Customization}). Normally, a fileset is a simple list of -files, but you can also define a fileset as a regular expression -matching file names. Some examples of these more complicated filesets -are shown in the Customize buffer. Remember to select @samp{Save for -future sessions} if you want to use the same filesets in future Emacs -sessions. - - You can use the command @kbd{M-x filesets-open} to visit all the -files in a fileset, and @kbd{M-x filesets-close} to close them. Use -@kbd{M-x filesets-run-cmd} to run a shell command on all the files in -a fileset. These commands are also available from the @samp{Filesets} -menu, where each existing fileset is represented by a submenu. - - @xref{Version Control}, for a different concept of ``filesets'': -groups of files bundled together for version control operations. -Filesets of that type are unnamed, and do not persist across Emacs -sessions. diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi deleted file mode 100644 index a5b571d2088..00000000000 --- a/doc/emacs/fixit.texi +++ /dev/null @@ -1,417 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Fixit -@chapter Commands for Fixing Typos -@cindex typos, fixing -@cindex mistakes, correcting - - In this chapter we describe commands that are useful when you catch -a mistake while editing. The most fundamental of these commands is -the undo command @kbd{C-/} (also bound to @kbd{C-x u} and @kbd{C-_}). -This undoes a single command, or a -part of a command (as in the case of @code{query-replace}), or several -consecutive character insertions. Consecutive repetitions of -@kbd{C-/} undo earlier and earlier changes, back to the limit of the -undo information available. - - Aside from the commands described here, you can erase text using -deletion commands such as @key{DEL} (@code{delete-backward-char}). -These were described earlier in this manual. @xref{Erasing}. - -@menu -* Undo:: The Undo commands. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word, or a whole file. -@end menu - -@node Undo -@section Undo -@cindex undo -@cindex changes, undoing - - The @dfn{undo} command reverses recent changes in the buffer's text. -Each buffer records changes individually, and the undo command always -applies to the current buffer. You can undo all the changes in a -buffer for as far back as the buffer's records go. Usually, each editing -command makes a separate entry in the undo records, but some commands -such as @code{query-replace} divide their changes into multiple -entries for flexibility in undoing. Consecutive character insertion -commands are usually grouped together into a single undo record, to -make undoing less tedious. - -@table @kbd -@item C-/ -@itemx C-x u -@itemx C-_ -Undo one entry in the current buffer's undo records (@code{undo}). -@end table - -@kindex C-x u -@kindex C-_ -@kindex C-/ -@findex undo - To begin to undo, type @kbd{C-/} (or its aliases, @kbd{C-_} or -@kbd{C-x u})@footnote{Aside from @kbd{C-/}, the @code{undo} command is -also bound to @kbd{C-x u} because that is more straightforward for -beginners to remember: @samp{u} stands for ``undo''. It is also bound -to @kbd{C-_} because typing @kbd{C-/} on some text terminals actually -enters @kbd{C-_}.}. This undoes the most recent change in the buffer, -and moves point back to where it was before that change. - Consecutive repetitions of @kbd{C-/} (or its aliases) undo earlier -and earlier changes in the current buffer. If all the recorded -changes have already been undone, the undo command signals an error. - -@cindex redo -@findex undo-only - Any command other than an undo command breaks the sequence of undo -commands. Starting from that moment, the entire sequence of undo -commands that you have just performed are themselves placed into the -undo record, as a single set of changes. Therefore, to re-apply -changes you have undone, type @kbd{C-f} or any other command that -harmlessly breaks the sequence of undoing; then type @kbd{C-/} to undo -the undo command. - - Alternatively, if you want to resume undoing, without redoing -previous undo commands, use @kbd{M-x undo-only}. This is like -@code{undo}, but will not redo changes you have just undone. - - If you notice that a buffer has been modified accidentally, the -easiest way to recover is to type @kbd{C-/} repeatedly until the stars -disappear from the front of the mode line (@pxref{Mode Line}). -Whenever an undo command makes the stars disappear from the mode line, -it means that the buffer contents are the same as they were when the -file was last read in or saved. If you do not remember whether you -changed the buffer deliberately, type @kbd{C-/} once. When you see -the last change you made undone, you will see whether it was an -intentional change. If it was an accident, leave it undone. If it -was deliberate, redo the change as described above. - -@cindex selective undo -@kindex C-u C-/ - When there is an active region, any use of @code{undo} performs -@dfn{selective undo}: it undoes the most recent change within the -region, instead of the entire buffer. However, when Transient Mark -mode is off (@pxref{Disabled Transient Mark}), @kbd{C-/} always -operates on the entire buffer, ignoring the region. In this case, you -can perform selective undo by supplying a prefix argument to the -@code{undo} command: @kbd{C-u C-/}. To undo further changes in the -same region, repeat the @code{undo} command (no prefix argument is -needed). - - Some specialized buffers do not make undo records. Buffers whose -names start with spaces never do; these buffers are used internally by -Emacs to hold text that users don't normally look at or edit. - -@vindex undo-limit -@vindex undo-strong-limit -@vindex undo-outer-limit -@cindex undo limit - When the undo information for a buffer becomes too large, Emacs discards -the oldest records from time to time (during @dfn{garbage -collection}). You can specify how much undo information to keep by -setting the variables @code{undo-limit}, @code{undo-strong-limit}, and -@code{undo-outer-limit}. Their values are expressed in bytes. - - The variable @code{undo-limit} sets a soft limit: Emacs keeps undo -data for enough commands to reach this size, and perhaps exceed it, -but does not keep data for any earlier commands beyond that. Its -default value is 80000. The variable @code{undo-strong-limit} sets a -stricter limit: any previous command (though not the most recent one) -that pushes the size past this amount is forgotten. The default value -of @code{undo-strong-limit} is 120000. - - Regardless of the values of those variables, the most recent change -is never discarded unless it gets bigger than @code{undo-outer-limit} -(normally 12,000,000). At that point, Emacs discards the undo data and -warns you about it. This is the only situation in which you cannot -undo the last command. If this happens, you can increase the value of -@code{undo-outer-limit} to make it even less likely to happen in the -future. But if you didn't expect the command to create such large -undo data, then it is probably a bug and you should report it. -@xref{Bugs,, Reporting Bugs}. - -@node Transpose -@section Transposing Text - -@table @kbd -@item C-t -Transpose two characters (@code{transpose-chars}). -@item M-t -Transpose two words (@code{transpose-words}). -@item C-M-t -Transpose two balanced expressions (@code{transpose-sexps}). -@item C-x C-t -Transpose two lines (@code{transpose-lines}). -@end table - -@kindex C-t -@findex transpose-chars - The common error of transposing two characters can be fixed, when they -are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally, -@kbd{C-t} transposes the two characters on either side of point. When -given at the end of a line, rather than transposing the last character of -the line with the newline, which would be useless, @kbd{C-t} transposes the -last two characters on the line. So, if you catch your transposition error -right away, you can fix it with just a @kbd{C-t}. If you don't catch it so -fast, you must move the cursor back between the two transposed -characters before you type @kbd{C-t}. If you transposed a space with -the last character of the word before it, the word motion commands are -a good way of getting there. Otherwise, a reverse search (@kbd{C-r}) -is often the best way. @xref{Search}. - -@kindex C-x C-t -@findex transpose-lines -@kindex M-t -@findex transpose-words -@c Don't index C-M-t and transpose-sexps here, they are indexed in -@c programs.texi, in the "List Commands" node. -@c @kindex C-M-t -@c @findex transpose-sexps - @kbd{M-t} transposes the word before point with the word after point -(@code{transpose-words}). It moves point forward over a word, -dragging the word preceding or containing point forward as well. The -punctuation characters between the words do not move. For example, -@w{@samp{FOO, BAR}} transposes into @w{@samp{BAR, FOO}} rather than -@samp{@w{BAR FOO,}}. - - @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for -transposing two expressions (@pxref{Expressions}), and @kbd{C-x C-t} -(@code{transpose-lines}) exchanges lines. They work like @kbd{M-t} -except as regards what units of text they transpose. - - A numeric argument to a transpose command serves as a repeat count: it -tells the transpose command to move the character (word, expression, line) -before or containing point across several other characters (words, -expressions, lines). For example, @kbd{C-u 3 C-t} moves the character before -point forward across three other characters. It would change -@samp{f@point{}oobar} into @samp{oobf@point{}ar}. This is equivalent to -repeating @kbd{C-t} three times. @kbd{C-u - 4 M-t} moves the word -before point backward across four words. @kbd{C-u - C-M-t} would cancel -the effect of plain @kbd{C-M-t}. - - A numeric argument of zero is assigned a special meaning (because -otherwise a command with a repeat count of zero would do nothing): to -transpose the character (word, expression, line) ending after point -with the one ending after the mark. - -@node Fixing Case -@section Case Conversion - -@table @kbd -@item M-- M-l -Convert last word to lower case. Note @kbd{Meta--} is Meta-minus. -@item M-- M-u -Convert last word to all upper case. -@item M-- M-c -Convert last word to lower case with capital initial. -@end table - -@kindex M-@t{-} M-l -@kindex M-@t{-} M-u -@kindex M-@t{-} M-c - A very common error is to type words in the wrong case. Because of this, -the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a -special feature when used with a negative argument: they do not move the -cursor. As soon as you see you have mistyped the last word, you can simply -case-convert it and go on typing. @xref{Case}. - -@node Spelling -@section Checking and Correcting Spelling -@cindex spelling, checking and correcting -@cindex checking spelling -@cindex correcting spelling - - This section describes the commands to check the spelling of a -single word or of a portion of a buffer. These commands only work if -the spelling checker program Aspell, Ispell or Hunspell is installed. -These programs are not part of Emacs, but one of them is usually -installed in GNU/Linux and other free operating systems. -@ifnottex -@xref{Top, Aspell,, aspell, The Aspell Manual}. -@end ifnottex - -@table @kbd -@item M-$ -Check and correct spelling of the word at point (@code{ispell-word}). -If the region is active, do it for all words in the region instead. -@item M-x ispell -Check and correct spelling of all words in the buffer. If the region -is active, do it for all words in the region instead. -@item M-x ispell-buffer -Check and correct spelling in the buffer. -@item M-x ispell-region -Check and correct spelling in the region. -@item M-x ispell-message -Check and correct spelling in a draft mail message, excluding cited -material. -@item M-x ispell-change-dictionary @key{RET} @var{dict} @key{RET} -Restart the Aspell/Ispell/Hunspell process, using @var{dict} as the dictionary. -@item M-x ispell-kill-ispell -Kill the Aspell/Ispell/Hunspell subprocess. -@item M-@key{TAB} -@itemx @key{ESC} @key{TAB} -Complete the word before point based on the spelling dictionary -(@code{ispell-complete-word}). -@item M-x flyspell-mode -Enable Flyspell mode, which highlights all misspelled words. -@item M-x flyspell-prog-mode -Enable Flyspell mode for comments and strings only. -@end table - -@kindex M-$ -@findex ispell-word - To check the spelling of the word around or before point, and -optionally correct it as well, type @kbd{M-$} (@code{ispell-word}). -If a region is active, @kbd{M-$} checks the spelling of all words -within the region. @xref{Mark}. (When Transient Mark mode is off, -@kbd{M-$} always acts on the word around or before point, ignoring the -region; @pxref{Disabled Transient Mark}.) - -@findex ispell -@findex ispell-buffer -@findex ispell-region -@cindex spell-checking the active region - Similarly, the command @kbd{M-x ispell} performs spell-checking in -the region if one is active, or in the entire buffer otherwise. The -commands @kbd{M-x ispell-buffer} and @kbd{M-x ispell-region} -explicitly perform spell-checking on the entire buffer or the region -respectively. To check spelling in an email message you are writing, -use @kbd{M-x ispell-message}; that command checks the whole buffer, -except for material that is indented or appears to be cited from other -messages. @xref{Sending Mail}. - - When one of these commands encounters what appears to be an -incorrect word, it asks you what to do. It usually displays a list of -numbered ``near-misses''---words that are close to the incorrect word. -Then you must type a single-character response. Here are the valid -responses: - -@table @kbd -@item @var{digit} -Replace the word, just this time, with one of the displayed -near-misses. Each near-miss is listed with a digit; type that digit -to select it. - -@item @key{SPC} -Skip this word---continue to consider it incorrect, but don't change it -here. - -@item r @var{new} @key{RET} -Replace the word, just this time, with @var{new}. (The replacement -string will be rescanned for more spelling errors.) - -@item R @var{new} @key{RET} -Replace the word with @var{new}, and do a @code{query-replace} so you -can replace it elsewhere in the buffer if you wish. (The replacements -will be rescanned for more spelling errors.) - -@item a -Accept the incorrect word---treat it as correct, but only in this -editing session. - -@item A -Accept the incorrect word---treat it as correct, but only in this -editing session and for this buffer. - -@item i -Insert this word in your private dictionary file so that Aspell or Ispell -or Hunspell will consider it correct from now on, even in future sessions. - -@item m -Like @kbd{i}, but you can also specify dictionary completion -information. - -@item u -Insert the lower-case version of this word in your private dic@-tion@-ary -file. - -@item l @var{word} @key{RET} -Look in the dictionary for words that match @var{word}. These words -become the new list of ``near-misses''; you can select one of them as -the replacement by typing a digit. You can use @samp{*} in @var{word} as a -wildcard. - -@item C-g -@itemx X -Quit interactive spell checking, leaving point at the word that was -being checked. You can restart checking again afterward with @kbd{C-u -M-$}. - -@item x -Quit interactive spell checking and move point back to where it was -when you started spell checking. - -@item q -Quit interactive spell checking and kill the spell-checker subprocess. - -@item ? -Show the list of options. -@end table - -@findex ispell-complete-word - In Text mode and related modes, @kbd{M-@key{TAB}} -(@code{ispell-complete-word}) performs in-buffer completion based on -spelling correction. Insert the beginning of a word, and then type -@kbd{M-@key{TAB}}; this shows a list of completions. (If your -window manager intercepts @kbd{M-@key{TAB}}, type @kbd{@key{ESC} -@key{TAB}} or @kbd{C-M-i}.) Each completion is listed with a digit or -character; type that digit or character to choose it. - -@cindex @code{ispell} program -@findex ispell-kill-ispell - Once started, the Aspell or Ispell or Hunspell subprocess continues -to run, waiting for something to do, so that subsequent spell checking -commands complete more quickly. If you want to get rid of the -process, use @kbd{M-x ispell-kill-ispell}. This is not usually -necessary, since the process uses no processor time except when you do -spelling correction. - -@vindex ispell-dictionary -@vindex ispell-local-dictionary -@vindex ispell-personal-dictionary -@findex ispell-change-dictionary - Ispell, Aspell and Hunspell look up spelling in two dictionaries: -the standard dictionary and your personal dictionary. The standard -dictionary is specified by the variable @code{ispell-local-dictionary} -or, if that is @code{nil}, by the variable @code{ispell-dictionary}. -If both are @code{nil}, the spelling program's default dictionary is -used. The command @kbd{M-x ispell-change-dictionary} sets the -standard dictionary for the buffer and then restarts the subprocess, -so that it will use a different standard dictionary. Your personal -dictionary is specified by the variable -@code{ispell-personal-dictionary}. If that is @code{nil}, the -spelling program looks for a personal dictionary in a default -location. - -@vindex ispell-complete-word-dict - A separate dictionary is used for word completion. The variable -@code{ispell-complete-word-dict} specifies the file name of this -dictionary. The completion dictionary must be different because it -cannot use root and affix information. For some languages, there -is a spell checking dictionary but no word completion dictionary. - -@cindex Flyspell mode -@cindex mode, Flyspell -@findex flyspell-mode - Flyspell mode is a minor mode that performs automatic spell checking -as you type. When it finds a word that it does not recognize, it -highlights that word. Type @kbd{M-x flyspell-mode} to toggle Flyspell -mode in the current buffer. To enable Flyspell mode in all text mode -buffers, add @code{flyspell-mode} to @code{text-mode-hook}. -@xref{Hooks}. - - When Flyspell mode highlights a word as misspelled, you can click on -it with @kbd{Mouse-2} to display a menu of possible corrections and -actions. You can also correct the word by editing it manually in any -way you like. - -@findex flyspell-prog-mode - Flyspell Prog mode works just like ordinary Flyspell mode, except -that it only checks words in comments and string constants. This -feature is useful for editing programs. Type @kbd{M-x -flyspell-prog-mode} to enable or disable this mode in the current -buffer. To enable this mode in all programming mode buffers, add -@code{flyspell-prog-mode} to @code{prog-mode-hook} (@pxref{Hooks}). diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi deleted file mode 100644 index 79ea410038a..00000000000 --- a/doc/emacs/fortran-xtra.texi +++ /dev/null @@ -1,581 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Fortran -@section Fortran Mode -@cindex Fortran mode -@cindex mode, Fortran - -@cindex Fortran fixed form and free form -@cindex Fortran 77 and Fortran 90, 95, 2003, 2008 -@findex f90-mode -@findex fortran-mode - Fortran mode is meant for editing ``fixed form'' (and also ``tab -format'') source code (normally Fortran 77). For editing more modern -``free form'' source code (Fortran 90, 95, 2003, 2008), use F90 mode -(@code{f90-mode}). Emacs normally uses Fortran mode for files with -extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode for the -extensions @samp{.f90}, @samp{.f95}, @samp{.f03} and @samp{.f08}. -Customize @code{auto-mode-alist} to add more extensions. GNU Fortran -supports both free and fixed form. This manual mainly documents Fortran -mode, but the corresponding F90 mode features are mentioned when -relevant. - - Fortran mode provides special motion commands for Fortran statements -and subprograms, and indentation commands that understand Fortran -conventions of nesting, line numbers and continuation statements. -Fortran mode has support for Auto Fill mode that breaks long lines into -proper Fortran continuation lines. Fortran mode also supports Hideshow -minor mode -@iftex -(@pxref{Hideshow,,, emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Hideshow}), -@end ifnottex -and Imenu -@iftex -(@pxref{Imenu,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Imenu}). -@end ifnottex - - Special commands for comments are provided because Fortran comments -are unlike those of other languages. Built-in abbrevs optionally save -typing when you insert Fortran keywords. - - Use @kbd{M-x fortran-mode} to switch to this major mode. This -command runs the hook @code{fortran-mode-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@menu -* Motion: Fortran Motion. Moving point by statements or subprograms. -* Indent: Fortran Indent. Indentation commands for Fortran. -* Comments: Fortran Comments. Inserting and aligning comments. -* Autofill: Fortran Autofill. Auto fill support for Fortran. -* Columns: Fortran Columns. Measuring columns for valid Fortran. -* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. -@end menu - -@node Fortran Motion -@subsection Motion Commands - - In addition to the normal commands for moving by and operating on -``defuns'' (Fortran subprograms---functions and subroutines, as well -as modules for F90 mode, using the commands @code{fortran-end-of-subprogram} -and @code{fortran-beginning-of-subprogram}), Fortran mode provides -special commands to move by statements and other program units. - -@table @kbd -@kindex C-c C-n @r{(Fortran mode)} -@findex fortran-next-statement -@findex f90-next-statement -@item C-c C-n -Move to the beginning of the next statement -(@code{fortran-next-statement}/@code{f90-next-statement}). - -@kindex C-c C-p @r{(Fortran mode)} -@findex fortran-previous-statement -@findex f90-previous-statement -@item C-c C-p -Move to the beginning of the previous statement -(@code{fortran-previous-statement}/@code{f90-previous-statement}). -If there is no previous statement (i.e., if called from the first -statement in the buffer), move to the start of the buffer. - -@kindex C-c C-e @r{(F90 mode)} -@findex f90-next-block -@item C-c C-e -Move point forward to the start of the next code block, or the end of -the current one, whichever comes first (@code{f90-next-block}). -A code block is a subroutine, @code{if}--@code{endif} statement, and -so forth. This command exists for F90 mode only, not Fortran mode. -With a numeric argument, it moves forward that many blocks. - -@kindex C-c C-a @r{(F90 mode)} -@findex f90-previous-block -@item C-c C-a -Move point backward to the previous block -(@code{f90-previous-block}). This is like @code{f90-next-block}, but -moves backwards. - -@kindex C-M-n @r{(Fortran mode)} -@findex fortran-end-of-block -@findex f90-end-of-block -@item C-M-n -Move to the end of the current code block -(@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric -argument, move forward that number of blocks. The mark is set before -moving point. The F90 mode version of this command checks for -consistency of block types and labels (if present), but it does not -check the outermost block since that may be incomplete. - -@kindex C-M-p @r{(Fortran mode)} -@findex fortran-beginning-of-block -@findex f90-beginning-of-block -@item C-M-p -Move to the start of the current code block -(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This -is like @code{fortran-end-of-block}, but moves backwards. -@end table - -The commands @code{fortran-beginning-of-subprogram} and -@code{fortran-end-of-subprogram} move to the start or end of the -current subprogram, respectively. The commands @code{fortran-mark-do} -and @code{fortran-mark-if} mark the end of the current @code{do} or -@code{if} block, and move point to the start. - - -@node Fortran Indent -@subsection Fortran Indentation - - Special commands and features are needed for indenting fixed (or tab) -form Fortran code in order to make sure various syntactic entities (line -numbers, comment line indicators and continuation line flags) appear in -the required columns. - -@menu -* Commands: ForIndent Commands. Commands for indenting and filling Fortran. -* Contline: ForIndent Cont. How continuation lines indent. -* Numbers: ForIndent Num. How line numbers auto-indent. -* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. -* Vars: ForIndent Vars. Variables controlling Fortran indent style. -@end menu - -@node ForIndent Commands -@subsubsection Fortran Indentation and Filling Commands - -@table @kbd -@item C-M-j -Break the current line at point and set up a continuation line -(@code{fortran-split-line}). -@item M-^ -Join this line to the previous line (@code{fortran-join-line}). -@item C-M-q -Indent all the lines of the subprogram that point is in -(@code{fortran-indent-subprogram}). -@item M-q -Fill a comment block or statement (using @code{fortran-fill-paragraph} -or @code{fortran-fill-statement}). -@end table - -@kindex C-M-q @r{(Fortran mode)} -@findex fortran-indent-subprogram - The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command -to reindent all the lines of the Fortran subprogram (function or -subroutine) containing point. - -@kindex C-M-j @r{(Fortran mode)} -@findex fortran-split-line - The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits -a line in the appropriate fashion for Fortran. In a non-comment line, -the second half becomes a continuation line and is indented -accordingly. In a comment line, both halves become separate comment -lines. - -@kindex M-^ @r{(Fortran mode)} -@kindex C-c C-d @r{(Fortran mode)} -@findex fortran-join-line - @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, -which joins a continuation line back to the previous line, roughly as -the inverse of @code{fortran-split-line}. The point must be on a -continuation line when this command is invoked. - -@kindex M-q @r{(Fortran mode)} -@kbd{M-q} in Fortran mode fills the comment block or statement that -point is in. This removes any excess statement continuations. - -@node ForIndent Cont -@subsubsection Continuation Lines -@cindex Fortran continuation lines - -@vindex fortran-continuation-string - Most Fortran 77 compilers allow two ways of writing continuation lines. -If the first non-space character on a line is in column 5, then that -line is a continuation of the previous line. We call this @dfn{fixed -form}. (In GNU Emacs we always count columns from 0; but note that -the Fortran standard counts from 1.) The variable -@code{fortran-continuation-string} specifies what character to put in -column 5. A line that starts with a tab character followed by any digit -except @samp{0} is also a continuation line. We call this style of -continuation @dfn{tab format}. (Fortran 90 introduced ``free form'', -with another style of continuation lines). - -@vindex indent-tabs-mode @r{(Fortran mode)} -@vindex fortran-analyze-depth -@vindex fortran-tab-mode-default - Fortran mode can use either style of continuation line. When you -enter Fortran mode, it tries to deduce the proper continuation style -automatically from the buffer contents. It does this by scanning up to -@code{fortran-analyze-depth} (default 100) lines from the start of the -buffer. The first line that begins with either a tab character or six -spaces determines the choice. If the scan fails (for example, if the -buffer is new and therefore empty), the value of -@code{fortran-tab-mode-default} (@code{nil} for fixed form, and -non-@code{nil} for tab format) is used. @samp{/t} -(@code{fortran-tab-mode-string}) in the mode line indicates tab format -is selected. Fortran mode sets the value of @code{indent-tabs-mode} -accordingly. - - If the text on a line starts with the Fortran continuation marker -@samp{$}, or if it begins with any non-whitespace character in column -5, Fortran mode treats it as a continuation line. When you indent a -continuation line with @key{TAB}, it converts the line to the current -continuation style. When you split a Fortran statement with -@kbd{C-M-j}, the continuation marker on the newline is created according -to the continuation style. - - The setting of continuation style affects several other aspects of -editing in Fortran mode. In fixed form mode, the minimum column -number for the body of a statement is 6. Lines inside of Fortran -blocks that are indented to larger column numbers must use only the -space character for whitespace. In tab format mode, the minimum -column number for the statement body is 8, and the whitespace before -column 8 must consist of one tab character. - -@node ForIndent Num -@subsubsection Line Numbers - - If a number is the first non-whitespace in the line, Fortran -indentation assumes it is a line number and moves it to columns 0 -through 4. (Columns always count from 0 in Emacs.) - -@vindex fortran-line-number-indent - Line numbers of four digits or less are normally indented one space. -The variable @code{fortran-line-number-indent} controls this; it -specifies the maximum indentation a line number can have. The default -value of the variable is 1. Fortran mode tries to prevent line number -digits passing column 4, reducing the indentation below the specified -maximum if necessary. If @code{fortran-line-number-indent} has the -value 5, line numbers are right-justified to end in column 4. - -@vindex fortran-electric-line-number - Simply inserting a line number is enough to indent it according to -these rules. As each digit is inserted, the indentation is recomputed. -To turn off this feature, set the variable -@code{fortran-electric-line-number} to @code{nil}. - - -@node ForIndent Conv -@subsubsection Syntactic Conventions - - Fortran mode assumes that you follow certain conventions that simplify -the task of understanding a Fortran program well enough to indent it -properly: - -@itemize @bullet -@item -Two nested @samp{do} loops never share a @samp{continue} statement. - -@item -Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} -and others are written without embedded whitespace or line breaks. - -Fortran compilers generally ignore whitespace outside of string -constants, but Fortran mode does not recognize these keywords if they -are not contiguous. Constructs such as @samp{else if} or @samp{end do} -are acceptable, but the second word should be on the same line as the -first and not on a continuation line. -@end itemize - -@noindent -If you fail to follow these conventions, the indentation commands may -indent some lines unaesthetically. However, a correct Fortran program -retains its meaning when reindented even if the conventions are not -followed. - -@node ForIndent Vars -@subsubsection Variables for Fortran Indentation - -@vindex fortran-do-indent -@vindex fortran-if-indent -@vindex fortran-structure-indent -@vindex fortran-continuation-indent -@vindex fortran-check-all-num@dots{} -@vindex fortran-minimum-statement-indent@dots{} - Several additional variables control how Fortran indentation works: - -@table @code -@item fortran-do-indent -Extra indentation within each level of @samp{do} statement (default 3). - -@item fortran-if-indent -Extra indentation within each level of @samp{if}, @samp{select case}, or -@samp{where} statements (default 3). - -@item fortran-structure-indent -Extra indentation within each level of @samp{structure}, @samp{union}, -@samp{map}, or @samp{interface} statements (default 3). - -@item fortran-continuation-indent -Extra indentation for bodies of continuation lines (default 5). - -@item fortran-check-all-num-for-matching-do -In Fortran 77, a numbered @samp{do} statement is ended by any statement -with a matching line number. It is common (but not compulsory) to use a -@samp{continue} statement for this purpose. If this variable has a -non-@code{nil} value, indenting any numbered statement must check for a -@samp{do} that ends there. If you always end @samp{do} statements with -a @samp{continue} line (or if you use the more modern @samp{enddo}), -then you can speed up indentation by setting this variable to -@code{nil} (the default). - -@item fortran-blink-matching-if -If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} -statement moves the cursor momentarily to the matching @samp{if} (or -@samp{do}) statement to show where it is. The default is @code{nil}. - -@item fortran-minimum-statement-indent-fixed -Minimum indentation for Fortran statements when using fixed form -continuation line style. Statement bodies are never indented by less than -this. The default is 6. - -@item fortran-minimum-statement-indent-tab -Minimum indentation for Fortran statements for tab format continuation line -style. Statement bodies are never indented by less than this. The -default is 8. -@end table - -The following section describes the variables controlling the -indentation of comments. - -@node Fortran Comments -@subsection Fortran Comments - - The usual Emacs comment commands assume that a comment can follow a -line of code. In Fortran 77, the standard comment syntax requires an -entire line to be just a comment. Therefore, Fortran mode replaces the -standard Emacs comment commands and defines some new variables. - -@vindex fortran-comment-line-start - Fortran mode can also handle the Fortran 90 comment syntax where -comments start with @samp{!} and can follow other text. Because only -some Fortran 77 compilers accept this syntax, Fortran mode will not -insert such comments unless you have said in advance to do so. To do -this, set the variable @code{fortran-comment-line-start} to @samp{"!"}. -If you use an unusual value, you may need to change -@code{fortran-comment-line-start-skip}. - - -@table @kbd -@item M-; -Align comment or insert new comment (@code{comment-dwim}). - -@item C-x ; -Applies to nonstandard @samp{!} comments only (@code{comment-set-column}). - -@item C-c ; -Turn all lines of the region into comments, or (with argument) turn them back -into real code (@code{fortran-comment-region}). -@end table - - @kbd{M-;} in Fortran mode runs the standard @code{comment-dwim}. -This recognizes any kind of existing comment and aligns its text -appropriately; if there is no existing comment, a comment is inserted -and aligned. Inserting and aligning comments are not the same in -Fortran mode as in other modes. - - When a new comment must be inserted, if the current line is blank, a -full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} -comment is inserted if you have said you want to use them. Otherwise a -full-line comment is inserted on a new line before the current line. - - Nonstandard @samp{!} comments are aligned like comments in other -languages, but full-line comments are different. In a standard full-line -comment, the comment delimiter itself must always appear in column zero. -What can be aligned is the text within the comment. You can choose from -three styles of alignment by setting the variable -@code{fortran-comment-indent-style} to one of these values: - -@vindex fortran-comment-indent-style -@vindex fortran-comment-line-extra-indent -@table @code -@item fixed -Align the text at a fixed column, which is the sum of -@code{fortran-comment-line-extra-indent} and the minimum statement -indentation. This is the default. - -The minimum indentation is -@code{fortran-minimum-statement-indent-tab} for tab format -continuation line style and @code{fortran-minimum-statement-indent-fixed} -for fixed form style. - -@item relative -Align the text as if it were a line of code, but with an additional -@code{fortran-comment-line-extra-indent} columns of indentation. - -@item nil -Don't move text in full-line comments automatically. -@end table - -@vindex fortran-comment-indent-char - In addition, you can specify the character to be used to indent within -full-line comments by setting the variable -@code{fortran-comment-indent-char} to the single-character string you want -to use. - -@vindex fortran-directive-re - Compiler directive lines, or preprocessor lines, have much the same -appearance as comment lines. It is important, though, that such lines -never be indented at all, no matter what the value of -@code{fortran-comment-indent-style}. The variable -@code{fortran-directive-re} is a regular expression that specifies which -lines are directives. Matching lines are never indented, and receive -distinctive font-locking. - - The normal Emacs comment command @kbd{C-x ;} (@code{comment-set-column}) -has not been redefined. If you use @samp{!} comments, this command -can be used with them. Otherwise it is useless in Fortran mode. - -@kindex C-c ; @r{(Fortran mode)} -@findex fortran-comment-region -@vindex fortran-comment-region - The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the -lines of the region into comments by inserting the string @samp{c$$$} at -the front of each one. With a numeric argument, it turns the region -back into live code by deleting @samp{c$$$} from the front of each line -in it. The string used for these comments can be controlled by setting -the variable @code{fortran-comment-region}. Note that here we have an -example of a command and a variable with the same name; these two uses -of the name never conflict because in Lisp and in Emacs it is always -clear from the context which one is meant. - -@node Fortran Autofill -@subsection Auto Fill in Fortran Mode - - Fortran mode has specialized support for Auto Fill mode, which is a -minor mode that automatically splits statements as you insert them -when they become too wide. Splitting a statement involves making -continuation lines using @code{fortran-continuation-string} -(@pxref{ForIndent Cont}). This splitting happens when you type -@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran -indentation commands. You activate Auto Fill in Fortran mode in the -normal way. -@iftex -@xref{Auto Fill,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Auto Fill}. -@end ifnottex - -@vindex fortran-break-before-delimiters - Auto Fill breaks lines at spaces or delimiters when the lines get -longer than the desired width (the value of @code{fill-column}). The -delimiters (besides whitespace) that Auto Fill can break at are -@samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>}, -and @samp{,}. The line break comes after the delimiter if the -variable @code{fortran-break-before-delimiters} is @code{nil}. -Otherwise (and by default), the break comes before the delimiter. - - To enable Auto Fill in all Fortran buffers, add -@code{auto-fill-mode} to @code{fortran-mode-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@node Fortran Columns -@subsection Checking Columns in Fortran - -@vindex fortran-line-length -In standard Fortran 77, anything beyond column 72 is ignored. -Most compilers provide an option to change this (for example, -@samp{-ffixed-line-length-N} in gfortran). Customize the variable -@code{fortran-line-length} to change the line length in Fortran mode. -Anything beyond this point is font-locked as a comment. (Unless it is -inside a string: strings that extend beyond @code{fortran-line-length} -will confuse font-lock.) - -@table @kbd -@item C-c C-r -Display a ``column ruler'' momentarily above the current line -(@code{fortran-column-ruler}). -@item C-c C-w -Split the current window horizontally temporarily so that it is -@code{fortran-line-length} columns wide -(@code{fortran-window-create-momentarily}). This may help you avoid -making lines longer than the limit imposed by your Fortran compiler. -@item C-u C-c C-w -Split the current window horizontally so that it is -@code{fortran-line-length} columns wide (@code{fortran-window-create}). -You can then continue editing. -@item M-x fortran-strip-sequence-nos -Delete all text in column @code{fortran-line-length} and beyond. -@end table - -@kindex C-c C-r @r{(Fortran mode)} -@findex fortran-column-ruler - The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column -ruler momentarily above the current line. The comment ruler is two lines -of text that show you the locations of columns with special significance in -Fortran programs. Square brackets show the limits of the columns for line -numbers, and curly brackets show the limits of the columns for the -statement body. Column numbers appear above them. - - Note that the column numbers count from zero, as always in GNU Emacs. -As a result, the numbers may be one less than those you are familiar -with; but the positions they indicate in the line are standard for -Fortran. - -@vindex fortran-column-ruler-fixed -@vindex fortran-column-ruler-tabs - The text used to display the column ruler depends on the value of the -variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is -@code{nil}, then the value of the variable -@code{fortran-column-ruler-fixed} is used as the column ruler. -Otherwise, the value of the variable @code{fortran-column-ruler-tab} is -displayed. By changing these variables, you can change the column ruler -display. - -@kindex C-c C-w @r{(Fortran mode)} -@findex fortran-window-create-momentarily - @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily -splits the current window horizontally, making a window -@code{fortran-line-length} columns wide, so you can see any lines that -are too long. Type a space to restore the normal width. - -@kindex C-u C-c C-w @r{(Fortran mode)} -@findex fortran-window-create - You can also split the window horizontally and continue editing with -the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x -fortran-window-create}). By editing in this window you can -immediately see when you make a line too wide to be correct Fortran. - -@findex fortran-strip-sequence-nos - The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in -column @code{fortran-line-length} and beyond, on all lines in the -current buffer. This is the easiest way to get rid of old sequence -numbers. - -@node Fortran Abbrev -@subsection Fortran Keyword Abbrevs - - Fortran mode provides many built-in abbrevs for common keywords and -declarations. These are the same sort of abbrev that you can define -yourself. To use them, you must turn on Abbrev mode. -@iftex -@xref{Abbrevs,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Abbrevs}. -@end ifnottex - - The built-in abbrevs are unusual in one way: they all start with a -semicolon. For example, one built-in Fortran abbrev is @samp{;c} for -@samp{continue}. If you insert @samp{;c} and then insert a punctuation -character such as a space or a newline, the @samp{;c} expands automatically -to @samp{continue}, provided Abbrev mode is enabled. - - Type @samp{;?} or @samp{;C-h} to display a list of all the built-in -Fortran abbrevs and what they stand for. diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi deleted file mode 100644 index 8c2289b83de..00000000000 --- a/doc/emacs/frames.texi +++ /dev/null @@ -1,1207 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Frames -@chapter Frames and Graphical Displays -@cindex frames - - When Emacs is started on a graphical display, e.g., on the X Window -System, it occupies a graphical system-level ``window''. In this -manual, we call this a @dfn{frame}, reserving the word ``window'' for -the part of the frame used for displaying a buffer. A frame initially -contains one window, but it can be subdivided into multiple windows -(@pxref{Windows}). A frame normally also contains a menu bar, tool -bar, and echo area. - - You can also create additional frames (@pxref{Creating Frames}). -All frames created in the same Emacs session have access to the same -underlying buffers and other data. For instance, if a buffer is being -shown in more than one frame, any changes made to it in one frame show -up immediately in the other frames too. - - Typing @kbd{C-x C-c} closes all the frames on the current display, -and ends the Emacs session if it has no frames open on any other -displays (@pxref{Exiting}). To close just the selected frame, type -@kbd{C-x 5 0} (that is zero, not @kbd{o}). - - This chapter describes Emacs features specific to graphical displays -(particularly mouse commands), and features for managing multiple -frames. On text terminals, many of these features are unavailable. -However, it is still possible to create multiple ``frames'' on text -terminals; such frames are displayed one at a time, filling the entire -terminal screen (@pxref{Non-Window Terminals}). It is also possible -to use the mouse on some text terminals (@pxref{Text-Only Mouse}, for -doing so on GNU and Unix systems; and -@iftex -@pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}, -@end iftex -@ifnottex -@pxref{MS-DOS Mouse}, -@end ifnottex -for doing so on MS-DOS). Menus are supported on all text terminals. - -@menu -* Mouse Commands:: Moving, cutting, and pasting, with the mouse. -* Word and Line Mouse:: Mouse commands for selecting whole words or lines. -* Mouse References:: Using the mouse to select an item from a list. -* Menu Mouse Clicks:: Mouse clicks that bring up menus. -* Mode Line Mouse:: Mouse clicks on the mode line. -* Creating Frames:: Creating additional Emacs frames with various contents. -* Frame Commands:: Iconifying, deleting, and switching frames. -* Fonts:: Changing the frame font. -* Speedbar:: How to make and use a speedbar frame. -* Multiple Displays:: How one Emacs instance can talk to several displays. -* Frame Parameters:: Changing the colors and other modes of frames. -* Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Drag and Drop:: Using drag and drop to open files and insert text. -* Menu Bars:: Enabling and disabling the menu bar. -* Tool Bars:: Enabling and disabling the tool bar. -* Dialog Boxes:: Controlling use of dialog boxes. -* Tooltips:: Displaying information at the current mouse position. -* Mouse Avoidance:: Preventing the mouse pointer from obscuring text. -* Non-Window Terminals:: Multiple frames on terminals that show only one. -* Text-Only Mouse:: Using the mouse in text terminals. -@end menu - -@node Mouse Commands -@section Mouse Commands for Editing -@cindex mouse buttons (what they do) -@cindex mouse, selecting text using - -@kindex Mouse-1 -@kindex Mouse-2 -@kindex Mouse-3 -@table @kbd -@item Mouse-1 -Move point to where you click (@code{mouse-set-point}). - -@item Drag-Mouse-1 -Activate the region around the text selected by dragging, and put the -text in the primary selection (@code{mouse-set-region}). - -@item Mouse-2 -Move point to where you click, and insert the contents of the primary -selection there (@code{mouse-yank-primary}). - -@item Mouse-3 -If the region is active, move the nearer end of the region to the -click position; otherwise, set mark at the current value of point and -point at the click position. Save the resulting region in the kill -ring; on a second click, kill it (@code{mouse-save-then-kill}). -@end table - -@findex mouse-set-point - The most basic mouse command is @code{mouse-set-point}, which is -invoked by clicking with the left mouse button, @kbd{Mouse-1}, in the -text area of a window. This moves point to the position where you -clicked. If that window was not the selected window, it becomes the -selected window. - -@vindex x-mouse-click-focus-ignore-position - Normally, if the frame you clicked in was not the selected frame, it -is made the selected frame, in addition to selecting the window and -setting the cursor. On the X Window System, you can change this by -setting the variable @code{x-mouse-click-focus-ignore-position} to -@code{t}. In that case, the initial click on an unselected frame just -selects the frame, without doing anything else; clicking again selects -the window and sets the cursor position. - -@cindex mouse, dragging -@findex mouse-set-region - Holding down @kbd{Mouse-1} and ``dragging'' the mouse over a stretch -of text activates the region around that text -(@code{mouse-set-region}), placing the mark where you started holding -down the mouse button, and point where you release it (@pxref{Mark}). -In addition, the text in the region becomes the primary selection -(@pxref{Primary Selection}). - -@vindex mouse-drag-copy-region - If you change the variable @code{mouse-drag-copy-region} to a -non-@code{nil} value, dragging the mouse over a stretch of text also -adds the text to the kill ring. The default is @code{nil}. - -@vindex mouse-scroll-min-lines - If you move the mouse off the top or bottom of the window while -dragging, the window scrolls at a steady rate until you move the mouse -back into the window. This way, you can select regions that don't fit -entirely on the screen. The number of lines scrolled per step depends -on how far away from the window edge the mouse has gone; the variable -@code{mouse-scroll-min-lines} specifies a minimum step size. - -@findex mouse-yank-primary -@findex mouse-yank-at-click - Clicking with the middle mouse button, @kbd{Mouse-2}, moves point to -the position where you clicked and inserts the contents of the primary -selection (@code{mouse-yank-primary}). @xref{Primary Selection}. -This behavior is consistent with other X applications. Alternatively, -you can rebind @kbd{Mouse-2} to @code{mouse-yank-at-click}, which -performs a yank at the position you click. - -@vindex mouse-yank-at-point - If you change the variable @code{mouse-yank-at-point} to a -non-@code{nil} value, @kbd{Mouse-2} does not move point; it inserts -the text at point, regardless of where you clicked or even which of -the frame's windows you clicked on. This variable affects both -@code{mouse-yank-primary} and @code{mouse-yank-at-click}. - -@findex mouse-save-then-kill - Clicking with the right mouse button, @kbd{Mouse-3}, runs the -command @code{mouse-save-then-kill}. This performs several actions -depending on where you click and the status of the region: - -@itemize @bullet -@item -If no region is active, clicking @kbd{Mouse-3} activates the region, -placing the mark where point was and point at the clicked position. - -@item -If a region is active, clicking @kbd{Mouse-3} adjusts the nearer end -of the region by moving it to the clicked position. The adjusted -region's text is copied to the kill ring; if the text in the original -region was already on the kill ring, it replaces it there. - -@item -If you originally specified the region using a double or triple -@kbd{Mouse-1}, so that the region is defined to consist of entire -words or lines (@pxref{Word and Line Mouse}), then adjusting the -region with @kbd{Mouse-3} also proceeds by entire words or lines. - -@item -If you use @kbd{Mouse-3} a second time consecutively, at the same -place, that kills the region already selected. Thus, the simplest way -to kill text with the mouse is to click @kbd{Mouse-1} at one end, then -click @kbd{Mouse-3} twice at the other end. To copy the text into the -kill ring without deleting it from the buffer, press @kbd{Mouse-3} -just once---or just drag across the text with @kbd{Mouse-1}. Then you -can copy it elsewhere by yanking it. -@end itemize - - The @code{mouse-save-then-kill} command also obeys the variable -@code{mouse-drag-copy-region} (described above). If the value is -non-@code{nil}, then whenever the command sets or adjusts the active -region, the text in the region is also added to the kill ring. If the -latest kill ring entry had been added the same way, that entry is -replaced rather than making a new entry. - - Whenever you set the region using any of the mouse commands -described above, the mark will be deactivated by any subsequent -unshifted cursor motion command, in addition to the usual ways of -deactivating the mark. @xref{Shift Selection}. - -@cindex mouse wheel -@findex mouse-wheel-mode -@cindex Mouse Wheel minor mode -@cindex mode, Mouse Wheel -@vindex mouse-wheel-follow-mouse -@vindex mouse-wheel-scroll-amount -@vindex mouse-wheel-progressive-speed - Some mice have a ``wheel'' which can be used for scrolling. Emacs -supports scrolling windows with the mouse wheel, by default, on most -graphical displays. To toggle this feature, use @kbd{M-x -mouse-wheel-mode}. The variables @code{mouse-wheel-follow-mouse} and -@code{mouse-wheel-scroll-amount} determine where and by how much -buffers are scrolled. The variable -@code{mouse-wheel-progressive-speed} determines whether the scroll -speed is linked to how fast you move the wheel. - -@node Word and Line Mouse -@section Mouse Commands for Words and Lines - - These variants of @kbd{Mouse-1} select entire words or lines at a -time. Emacs activates the region around the selected text, which is -also copied to the kill ring. - -@table @kbd -@item Double-Mouse-1 -Select the text around the word which you click on. - -Double-clicking on a character with ``symbol'' syntax (such as -underscore, in C mode) selects the symbol surrounding that character. -Double-clicking on a character with open- or close-parenthesis syntax -selects the parenthetical grouping which that character starts or -ends. Double-clicking on a character with string-delimiter syntax -(such as a single-quote or double-quote in C) selects the string -constant (Emacs uses heuristics to figure out whether that character -is the beginning or the end of it). - -@item Double-Drag-Mouse-1 -Select the text you drag across, in the form of whole words. - -@item Triple-Mouse-1 -Select the line you click on. - -@item Triple-Drag-Mouse-1 -Select the text you drag across, in the form of whole lines. -@end table - -@node Mouse References -@section Following References with the Mouse -@kindex Mouse-1 @r{(on buttons)} -@kindex Mouse-2 @r{(on buttons)} -@cindex hyperlinks -@cindex links -@cindex text buttons -@cindex buttons - -@vindex mouse-highlight - Some Emacs buffers include @dfn{buttons}, or @dfn{hyperlinks}: -pieces of text that perform some action (e.g., following a reference) -when activated (e.g., by clicking on them). Usually, a button's text -is visually highlighted: it is underlined, or a box is drawn around -it. If you move the mouse over a button, the shape of the mouse -cursor changes and the button lights up. If you change the variable -@code{mouse-highlight} to @code{nil}, Emacs disables this -highlighting. - - You can activate a button by moving point to it and typing -@key{RET}, or by clicking either @kbd{Mouse-1} or @kbd{Mouse-2} on the -button. For example, in a Dired buffer, each file name is a button; -activating it causes Emacs to visit that file (@pxref{Dired}). In a -@file{*Compilation*} buffer, each error message is a button, and -activating it visits the source code for that error -(@pxref{Compilation}). - - Although clicking @kbd{Mouse-1} on a button usually activates the -button, if you hold the mouse button down for a period of time before -releasing it (specifically, for more than 450 milliseconds), then -Emacs moves point where you clicked, without activating the button. -In this way, you can use the mouse to move point over a button without -activating it. Dragging the mouse over or onto a button has its usual -behavior of setting the region, and does not activate the button. - - You can change how @kbd{Mouse-1} applies to buttons by customizing -the variable @code{mouse-1-click-follows-link}. If the value is a -positive integer, that determines how long you need to hold the mouse -button down for, in milliseconds, to cancel button activation; the -default is 450, as described in the previous paragraph. If the value -is @code{nil}, @kbd{Mouse-1} just sets point where you clicked, and -does not activate buttons. If the value is @code{double}, double -clicks activate buttons but single clicks just set point. - -@vindex mouse-1-click-in-non-selected-windows - Normally, @kbd{Mouse-1} on a button activates the button even if it -is in a non-selected window. If you change the variable -@code{mouse-1-click-in-non-selected-windows} to @code{nil}, -@kbd{Mouse-1} on a button in an unselected window moves point to the -clicked position and selects that window, without activating the -button. - -@node Menu Mouse Clicks -@section Mouse Clicks for Menus - - Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers -bring up menus. - -@table @kbd -@item C-Mouse-1 -@kindex C-Mouse-1 -This menu is for selecting a buffer. - -The MSB (``mouse select buffer'') global minor mode makes this -menu smarter and more customizable. @xref{Buffer Menus}. - -@item C-Mouse-2 -@kindex C-Mouse-2 -This menu contains entries for examining faces and other text -properties, and well as for setting them (the latter is mainly useful -when editing enriched text; @pxref{Enriched Text}). - -@item C-Mouse-3 -@kindex C-Mouse-3 -This menu is mode-specific. For most modes if Menu-bar mode is on, -this menu has the same items as all the mode-specific menu-bar menus -put together. Some modes may specify a different menu for this -button. If Menu Bar mode is off, this menu contains all the items -which would be present in the menu bar---not just the mode-specific -ones---so that you can access them without having to display the menu -bar. - -@item S-Mouse-1 -This menu is for changing the default face within the window's buffer. -@xref{Text Scale}. -@end table - - Some graphical applications use @kbd{Mouse-3} for a mode-specific -menu. If you prefer @kbd{Mouse-3} in Emacs to bring up such a menu -instead of running the @code{mouse-save-then-kill} command, rebind -@kbd{Mouse-3} by adding the following line to your init file -(@pxref{Init Rebinding}): - -@smallexample -(global-set-key [mouse-3] 'mouse-popup-menubar-stuff) -@end smallexample - -@node Mode Line Mouse -@section Mode Line Mouse Commands -@cindex mode line, mouse -@cindex mouse on mode line - - You can use mouse clicks on window mode lines to select and manipulate -windows. - - Some areas of the mode line, such as the buffer name, and major and minor -mode names, have their own special mouse bindings. These areas are -highlighted when you hold the mouse over them, and information about -the special bindings will be displayed (@pxref{Tooltips}). This -section's commands do not apply in those areas. - -@table @kbd -@item Mouse-1 -@kindex Mouse-1 @r{(mode line)} -@kbd{Mouse-1} on a mode line selects the window it belongs to. By -dragging @kbd{Mouse-1} on the mode line, you can move it, thus -changing the height of the windows above and below. Changing heights -with the mouse in this way never deletes windows, it just refuses to -make any window smaller than the minimum height. - -@item Mouse-2 -@kindex Mouse-2 @r{(mode line)} -@kbd{Mouse-2} on a mode line expands that window to fill its frame. - -@item Mouse-3 -@kindex Mouse-3 @r{(mode line)} -@kbd{Mouse-3} on a mode line deletes the window it belongs to. If the -frame has only one window, it does nothing. - -@item C-Mouse-2 -@kindex C-mouse-2 @r{(mode line)} -@kbd{C-Mouse-2} on a mode line splits that window, producing two -side-by-side windows with the boundary running through the click -position (@pxref{Split Window}). -@end table - -@kindex Mouse-1 @r{(scroll bar)} - Furthermore, by clicking and dragging @kbd{Mouse-1} on the divider -between two side-by-side mode lines, you can move the vertical -boundary to the left or right. - -@node Creating Frames -@section Creating Frames -@cindex creating frames - -@kindex C-x 5 - The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}. Whereas -each @kbd{C-x 4} command pops up a buffer in a different window in the -selected frame (@pxref{Pop Up Window}), the @kbd{C-x 5} commands use a -different frame. If an existing visible or iconified (``minimized'') -frame already displays the requested buffer, that frame is raised and -deiconified (``un-minimized''); otherwise, a new frame is created on -the current display terminal. - - The various @kbd{C-x 5} commands differ in how they find or create the -buffer to select: - -@table @kbd -@item C-x 5 2 -@kindex C-x 5 2 -@findex make-frame-command -Create a new frame (@code{make-frame-command}). -@item C-x 5 b @var{bufname} @key{RET} -Select buffer @var{bufname} in another frame. This runs -@code{switch-to-buffer-other-frame}. -@item C-x 5 f @var{filename} @key{RET} -Visit file @var{filename} and select its buffer in another frame. This -runs @code{find-file-other-frame}. @xref{Visiting}. -@item C-x 5 d @var{directory} @key{RET} -Select a Dired buffer for directory @var{directory} in another frame. -This runs @code{dired-other-frame}. @xref{Dired}. -@item C-x 5 m -Start composing a mail message in another frame. This runs -@code{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. -@xref{Sending Mail}. -@item C-x 5 . -Find a tag in the current tag table in another frame. This runs -@code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}. -@xref{Tags}. -@item C-x 5 r @var{filename} @key{RET} -@kindex C-x 5 r -@findex find-file-read-only-other-frame -Visit file @var{filename} read-only, and select its buffer in another -frame. This runs @code{find-file-read-only-other-frame}. -@xref{Visiting}. -@end table - - You can control the appearance and behavior of the newly-created -frames by specifying @dfn{frame parameters}. @xref{Frame Parameters}. - -@node Frame Commands -@section Frame Commands - - The following commands are used to delete and operate on frames: - -@table @kbd -@item C-x 5 0 -@kindex C-x 5 0 -@findex delete-frame -Delete the selected frame (@code{delete-frame}). This signals an -error if there is only one frame. - -@item C-z -@kindex C-z @r{(X windows)} -@findex suspend-frame -Minimize (or ``iconify) the selected Emacs frame -(@code{suspend-frame}). @xref{Exiting}. - -@item C-x 5 o -@kindex C-x 5 o -@findex other-frame -Select another frame, and raise it. If you repeat this command, it -cycles through all the frames on your terminal. - -@item C-x 5 1 -@kindex C-x 5 1 -@findex delete-other-frames -Delete all frames on the current terminal, except the selected one. - -@item M- -@kindex M- -@findex toggle-frame-maximized -Toggle the maximization state of the current frame. When a frame is -maximized, it fills the screen. - -@item -@kindex -@findex toggle-frame-fullscreen -Toggle fullscreen mode for the current frame. (The difference -between ``fullscreen'' and ``maximized'' is normally that the former -hides window manager decorations, giving slightly more screen space to -Emacs itself.) -@end table - - Note that with some window managers you may have to customize the -variable @code{frame-resize-pixelwise} to a non-@code{nil} value in -order to make a frame truly ``maximized'' or ``fullscreen''. - - The @kbd{C-x 5 0} (@code{delete-frame}) command deletes the selected -frame. However, it will refuse to delete the last frame in an Emacs -session, to prevent you from losing the ability to interact with the -Emacs session. Note that when Emacs is run as a daemon (@pxref{Emacs -Server}), there is always a ``virtual frame'' that remains after all -the ordinary, interactive frames are deleted. In this case, @kbd{C-x -5 0} can delete the last interactive frame; you can use -@command{emacsclient} to reconnect to the Emacs session. - - The @kbd{C-x 5 1} (@code{delete-other-frames}) command deletes all -other frames on the current terminal (this terminal refers to either a -graphical display, or a text terminal; @pxref{Non-Window Terminals}). -If the Emacs session has frames open on other graphical displays or -text terminals, those are not deleted. - -@vindex focus-follows-mouse - The @kbd{C-x 5 o} (@code{other-frame}) command selects the next -frame on the current terminal. If you are using Emacs on the X Window -System with a window manager that selects (or @dfn{gives focus to}) -whatever frame the mouse cursor is over, you have to change the -variable @code{focus-follows-mouse} to @code{t} in order for this -command to work properly. Then invoking @kbd{C-x 5 o} will also warp -the mouse cursor to the chosen frame. - -@node Fonts -@section Fonts -@cindex fonts - - By default, Emacs displays text on graphical displays using a -10-point monospace font. There are several different ways to specify -a different font: - -@itemize -@item -Click on @samp{Set Default Font} in the @samp{Options} menu. This -makes the selected font the default on all existing graphical frames. -To save this for future sessions, click on @samp{Save Options} in the -@samp{Options} menu. - -@item -Add a line to your init file, modifying the variable -@code{default-frame-alist} to specify the @code{font} parameter -(@pxref{Frame Parameters}), like this: - -@example -(add-to-list 'default-frame-alist - '(font . "DejaVu Sans Mono-10")) -@end example - -@noindent -This makes the font the default on all graphical frames created after -restarting Emacs with that init file. - -@cindex X defaults file -@cindex X resources file -@item -Add an @samp{emacs.font} X resource setting to your X resource file, -like this: - -@example -emacs.font: DejaVu Sans Mono-12 -@end example - -@noindent -You must restart X, or use the @command{xrdb} command, for the X -resources file to take effect. @xref{Resources}. Do not quote -font names in X resource files. - -@item -If you are running Emacs on the GNOME desktop, you can tell Emacs to -use the default system font by setting the variable -@code{font-use-system-font} to @code{t} (the default is @code{nil}). -For this to work, Emacs must have been compiled with Gconf support. - -@item -Use the command line option @samp{-fn} (or @samp{--font}). @xref{Font -X}. -@end itemize - - To check what font you're currently using, the @kbd{C-u C-x =} -command can be helpful. It describes the character at point, and -names the font that it's rendered in. - -@cindex fontconfig - On X, there are four different ways to express a ``font name''. The -first is to use a @dfn{Fontconfig pattern}. Fontconfig patterns have -the following form: - -@example -@var{fontname}[-@var{fontsize}][:@var{name1}=@var{values1}][:@var{name2}=@var{values2}]... -@end example - -@noindent -Within this format, any of the elements in braces may be omitted. -Here, @var{fontname} is the @dfn{family name} of the font, such as -@samp{Monospace} or @samp{DejaVu Sans Mono}; @var{fontsize} is the -@dfn{point size} of the font (one @dfn{printer's point} is about 1/72 -of an inch); and the @samp{@var{name}=@var{values}} entries specify -settings such as the slant and weight of the font. Each @var{values} -may be a single value, or a list of values separated by commas. In -addition, some property values are valid with only one kind of -property name, in which case the @samp{@var{name}=} part may be -omitted. - -Here is a list of common font properties: - -@table @samp -@item slant -One of @samp{italic}, @samp{oblique}, or @samp{roman}. - -@item weight -One of @samp{light}, @samp{medium}, @samp{demibold}, @samp{bold} or -@samp{black}. - -@item style -Some fonts define special styles which are a combination of slant and -weight. For instance, @samp{Dejavu Sans} defines the @samp{book} -style, which overrides the slant and weight properties. - -@item width -One of @samp{condensed}, @samp{normal}, or @samp{expanded}. - -@item spacing -One of @samp{monospace}, @samp{proportional}, @samp{dual-width}, or -@samp{charcell}. -@end table - -@noindent -Here are some examples of Fontconfig patterns: - -@example -Monospace -Monospace-12 -Monospace-12:bold -DejaVu Sans Mono:bold:italic -Monospace-12:weight=bold:slant=italic -@end example - -For a more detailed description of Fontconfig patterns, see the -Fontconfig manual, which is distributed with Fontconfig and available -online at @url{http://fontconfig.org/fontconfig-user.html}. - -@cindex GTK font pattern - The second way to specify a font is to use a @dfn{GTK font pattern}. -These have the syntax - -@example -@var{fontname} [@var{properties}] [@var{fontsize}] -@end example - -@noindent -where @var{fontname} is the family name, @var{properties} is a list of -property values separated by spaces, and @var{fontsize} is the point -size. The properties that you may specify for GTK font patterns are -as follows: - -@itemize -@item -Slant properties: @samp{Italic} or @samp{Oblique}. If omitted, the -default (roman) slant is implied. -@item -Weight properties: @samp{Bold}, @samp{Book}, @samp{Light}, -@samp{Medium}, @samp{Semi-bold}, or @samp{Ultra-light}. If omitted, -@samp{Medium} weight is implied. -@item -Width properties: @samp{Semi-Condensed} or @samp{Condensed}. If -omitted, a default width is used. -@end itemize - -@noindent -Here are some examples of GTK font patterns: - -@example -Monospace 12 -Monospace Bold Italic 12 -@end example - -@cindex XLFD -@cindex X Logical Font Description - The third way to specify a font is to use an @dfn{XLFD} (@dfn{X -Logical Font Description}). This is the traditional method for -specifying fonts under X@. Each XLFD consists of fourteen words or -numbers, separated by dashes, like this: - -@example --misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 -@end example - -@noindent -A wildcard character (@samp{*}) in an XLFD matches any sequence of -characters (including none), and @samp{?} matches any single -character. However, matching is implementation-dependent, and can be -inaccurate when wildcards match dashes in a long name. For reliable -results, supply all 14 dashes and use wildcards only within a field. -Case is insignificant in an XLFD@. The syntax for an XLFD is as -follows: - -@example --@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} -@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{registry}-@var{encoding} -@end example - -@noindent -The entries have the following meanings: - -@table @var -@item maker -The name of the font manufacturer. -@item family -The name of the font family (e.g., @samp{courier}). -@item weight -The font weight---normally either @samp{bold}, @samp{medium} or -@samp{light}. Some font names support other values. -@item slant -The font slant---normally @samp{r} (roman), @samp{i} (italic), -@samp{o} (oblique), @samp{ri} (reverse italic), or @samp{ot} (other). -Some font names support other values. -@item widthtype -The font width---normally @samp{normal}, @samp{condensed}, -@samp{semicondensed}, or @samp{extended}. Some font names support -other values. -@item style -An optional additional style name. Usually it is empty---most XLFDs -have two hyphens in a row at this point. -@item pixels -The font height, in pixels. -@item height -The font height on the screen, measured in tenths of a printer's -point. This is the point size of the font, times ten. For a given -vertical resolution, @var{height} and @var{pixels} are proportional; -therefore, it is common to specify just one of them and use @samp{*} -for the other. -@item horiz -The horizontal resolution, in pixels per inch, of the screen for which -the font is intended. -@item vert -The vertical resolution, in pixels per inch, of the screen for which -the font is intended. Normally the resolution of the fonts on your -system is the right value for your screen; therefore, you normally -specify @samp{*} for this and @var{horiz}. -@item spacing -This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c} -(character cell). -@item width -The average character width, in pixels, multiplied by ten. -@item registry -@itemx encoding -The X font character set that the font depicts. (X font character -sets are not the same as Emacs character sets, but they are similar.) -You can use the @command{xfontsel} program to check which choices you -have. Normally you should use @samp{iso8859} for @var{registry} and -@samp{1} for @var{encoding}. -@end table - - The fourth and final method of specifying a font is to use a ``font -nickname''. Certain fonts have shorter nicknames, which you can use -instead of a normal font specification. For instance, @samp{6x13} is -equivalent to - -@example --misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 -@end example - -@cindex client-side fonts -@cindex server-side fonts - On X, Emacs recognizes two types of fonts: @dfn{client-side} fonts, -which are provided by the Xft and Fontconfig libraries, and -@dfn{server-side} fonts, which are provided by the X server itself. -Most client-side fonts support advanced font features such as -antialiasing and subpixel hinting, while server-side fonts do not. -Fontconfig and GTK patterns match only client-side fonts. - -@cindex listing system fonts - You will probably want to use a fixed-width default font---that is, -a font in which all characters have the same width. For Xft and -Fontconfig fonts, you can use the @command{fc-list} command to list -the available fixed-width fonts, like this: - -@example -fc-list :spacing=mono fc-list :spacing=charcell -@end example - -@noindent -For server-side X fonts, you can use the @command{xlsfonts} program to -list the available fixed-width fonts, like this: - -@example -xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+" -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' -@end example - -@noindent -Any font with @samp{m} or @samp{c} in the @var{spacing} field of the -XLFD is a fixed-width font. To see what a particular font looks like, -use the @command{xfd} command. For example: - -@example -xfd -fn 6x13 -@end example - -@noindent -displays the entire font @samp{6x13}. - - While running Emacs, you can also set the font of a specific kind of -text (@pxref{Faces}), or a particular frame (@pxref{Frame -Parameters}). - -@node Speedbar -@section Speedbar Frames -@cindex speedbar - -@cindex attached frame (of speedbar) - The @dfn{speedbar} is a special frame for conveniently navigating in -or operating on another frame. The speedbar, when it exists, is -always associated with a specific frame, called its @dfn{attached -frame}; all speedbar operations act on that frame. - - Type @kbd{M-x speedbar} to create the speedbar and associate it with -the current frame. To dismiss the speedbar, type @kbd{M-x speedbar} -again, or select the speedbar and type @kbd{q}. (You can also delete -the speedbar frame like any other Emacs frame.) If you wish to -associate the speedbar with a different frame, dismiss it and call -@kbd{M-x speedbar} from that frame. - - The speedbar can operate in various modes. Its default mode is -@dfn{File Display} mode, which shows the files in the current -directory of the selected window of the attached frame, one file per -line. Clicking on a file name visits that file in the selected window -of the attached frame, and clicking on a directory name shows that -directory in the speedbar (@pxref{Mouse References}). Each line also -has a box, @samp{[+]} or @samp{<+>}, that you can click on to -@dfn{expand} the contents of that item. Expanding a directory adds -the contents of that directory to the speedbar display, underneath the -directory's own line. Expanding an ordinary file adds a list of the -tags in that file to the speedbar display; you can click on a tag name -to jump to that tag in the selected window of the attached frame. -When a file or directory is expanded, the @samp{[+]} changes to -@samp{[-]}; you can click on that box to @dfn{contract} the item, -hiding its contents. - - You navigate through the speedbar using the keyboard, too. Typing -@key{RET} while point is on a line in the speedbar is equivalent to -clicking the item on the current line, and @key{SPC} expands or -contracts the item. @kbd{U} displays the parent directory of the -current directory. To copy, delete, or rename the file on the current -line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a -new directory, type @kbd{M}. - - Another general-purpose speedbar mode is @dfn{Buffer Display} mode; -in this mode, the speedbar displays a list of Emacs buffers. To -switch to this mode, type @kbd{b} in the speedbar. To return to File -Display mode, type @kbd{f}. You can also change the display mode by -clicking @kbd{mouse-3} anywhere in the speedbar window (or -@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the -pop-up menu. - - Some major modes, including Rmail mode, Info, and GUD, have -specialized ways of putting useful items into the speedbar for you to -select. For example, in Rmail mode, the speedbar shows a list of Rmail -files, and lets you move the current message to another Rmail file by -clicking on its @samp{} box. - - For more details on using and programming the speedbar, @xref{Top, -Speedbar,,speedbar, Speedbar Manual}. - -@node Multiple Displays -@section Multiple Displays -@cindex multiple displays - - A single Emacs can talk to more than one X display. Initially, Emacs -uses just one display---the one specified with the @env{DISPLAY} -environment variable or with the @samp{--display} option (@pxref{Initial -Options}). To connect to another display, use the command -@code{make-frame-on-display}: - -@findex make-frame-on-display -@table @kbd -@item M-x make-frame-on-display @key{RET} @var{display} @key{RET} -Create a new frame on display @var{display}. -@end table - - A single X server can handle more than one screen. When you open -frames on two screens belonging to one server, Emacs knows they share a -single keyboard, and it treats all the commands arriving from these -screens as a single stream of input. - - When you open frames on different X servers, Emacs makes a separate -input stream for each server. Each server also has its own selected -frame. The commands you enter with a particular X server apply to -that server's selected frame. - -@node Frame Parameters -@section Frame Parameters -@cindex default-frame-alist - - You can control the default appearance and behavior of all frames by -specifying a default list of @dfn{frame parameters} in the variable -@code{default-frame-alist}. Its value should be a list of entries, -each specifying a parameter name and a value for that parameter. -These entries take effect whenever Emacs creates a new frame, -including the initial frame. - -@cindex frame size, specifying default - For example, you can add the following lines to your init file -(@pxref{Init File}) to set the default frame width to 90 character -columns, the default frame height to 40 character rows, and the -default font to @samp{Monospace-10}: - -@example -(add-to-list 'default-frame-alist '(width . 90)) -(add-to-list 'default-frame-alist '(height . 40)) -(add-to-list 'default-frame-alist '(font . "Monospace-10")) -@end example - - For a list of frame parameters and their effects, see @ref{Frame -Parameters,,, elisp, The Emacs Lisp Reference Manual}. - -@cindex initial-frame-alist - You can also specify a list of frame parameters which apply to just -the initial frame, by customizing the variable -@code{initial-frame-alist}. - - If Emacs is compiled to use an X toolkit, frame parameters that -specify colors and fonts don't affect menus and the menu bar, since -those are drawn by the toolkit and not directly by Emacs. - -@node Scroll Bars -@section Scroll Bars -@cindex Scroll Bar mode -@cindex mode, Scroll Bar - - On graphical displays, there is a @dfn{scroll bar} on the side of -each Emacs window. Clicking @kbd{Mouse-1} on the scroll bar's up and -down buttons scrolls the window by one line at a time. Clicking -@kbd{Mouse-1} above or below the scroll bar's inner box scrolls the -window by nearly the entire height of the window, like @kbd{M-v} and -@kbd{C-v} respectively (@pxref{Moving Point}). Dragging the inner box -scrolls continuously. - - If Emacs is compiled on the X Window System without X toolkit -support, the scroll bar behaves differently. Clicking @kbd{Mouse-1} -anywhere on the scroll bar scrolls forward like @kbd{C-v}, while -@kbd{Mouse-3} scrolls backward like @kbd{M-v}. Clicking @kbd{Mouse-2} -in the scroll bar lets you drag the inner box up and down. - -@findex scroll-bar-mode -@findex toggle-scroll-bar - To toggle the use of scroll bars, type @kbd{M-x scroll-bar-mode}. -This command applies to all frames, including frames yet to be -created. To toggle scroll bars for just the selected frame, use the -command @kbd{M-x toggle-scroll-bar}. - -@vindex scroll-bar-mode - To control the use of scroll bars at startup, customize the variable -@code{scroll-bar-mode}. Its value should be either @code{right} (put -scroll bars on the right side of windows), @code{left} (put them on -the left), or @code{nil} (disable scroll bars). By default, Emacs -puts scroll bars on the right if it was compiled with GTK+ support on -the X Window System, and on MS-Windows or Mac OS; Emacs puts scroll -bars on the left if compiled on the X Window System without GTK+ -support (following the old convention for X applications). - -@vindex scroll-bar-width -@cindex width of the scroll bar - You can also use the X resource @samp{verticalScrollBars} to enable -or disable the scroll bars (@pxref{Resources}). To control the scroll -bar width, change the @code{scroll-bar-width} frame parameter -(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). - -@vindex scroll-bar-adjust-thumb-portion -@cindex overscrolling -If you're using Emacs on X (with GTK+ or Motif), you can customize the -variable @code{scroll-bar-adjust-thumb-portion} to control -@dfn{overscrolling} of the scroll bar, i.e. dragging the thumb down even -when the end of the buffer is visible. If its value is -non-@code{nil}, the scroll bar can be dragged downwards even if the -end of the buffer is shown; if @code{nil}, the thumb will be at the -bottom when the end of the buffer is shown. You can not over-scroll -when the entire buffer is visible. - -@node Drag and Drop -@section Drag and Drop -@cindex drag and drop - - In most graphical desktop environments, Emacs has basic support for -@dfn{drag and drop} operations. For instance, dropping text onto an -Emacs frame inserts the text where it is dropped. Dropping a file -onto an Emacs frame visits that file. As a special case, dropping the -file on a Dired buffer moves or copies the file (according to the -conventions of the application it came from) into the directory -displayed in that buffer. - -@vindex dnd-open-file-other-window - Dropping a file normally visits it in the window you drop it on. If -you prefer to visit the file in a new window in such cases, customize -the variable @code{dnd-open-file-other-window}. - - The XDND and Motif drag and drop protocols, and the old KDE 1.x -protocol, are currently supported. - -@node Menu Bars -@section Menu Bars -@cindex Menu Bar mode -@cindex mode, Menu Bar -@findex menu-bar-mode -@vindex menu-bar-mode - - You can toggle the use of menu bars with @kbd{M-x menu-bar-mode}. -With no argument, this command toggles Menu Bar mode, a global minor -mode. With an argument, the command turns Menu Bar mode on if the -argument is positive, off if the argument is not positive. To control -the use of menu bars at startup, customize the variable -@code{menu-bar-mode}. - -@kindex C-Mouse-3 @r{(when menu bar is disabled)} - Expert users often turn off the menu bar, especially on text -terminals, where this makes one additional line available for text. -If the menu bar is off, you can still pop up a menu of its contents -with @kbd{C-Mouse-3} on a display which supports pop-up menus. -@xref{Menu Mouse Clicks}. - - @xref{Menu Bar}, for information on how to invoke commands with the -menu bar. @xref{X Resources}, for how to customize the menu bar -menus' visual appearance. - -@node Tool Bars -@section Tool Bars -@cindex Tool Bar mode -@cindex mode, Tool Bar -@cindex icons, toolbar - - On graphical displays, Emacs puts a @dfn{tool bar} at the top of -each frame, just below the menu bar. This is a row of icons which you -can click on with the mouse to invoke various commands. - - The global (default) tool bar contains general commands. Some major -modes define their own tool bars; whenever a buffer with such a major -mode is current, the mode's tool bar replaces the global tool bar. - -@findex tool-bar-mode -@vindex tool-bar-mode - To toggle the use of tool bars, type @kbd{M-x tool-bar-mode}. This -command applies to all frames, including frames yet to be created. To -control the use of tool bars at startup, customize the variable -@code{tool-bar-mode}. - -@vindex tool-bar-style -@cindex Tool Bar style - When Emacs is compiled with GTK+ support, each tool bar item can -consist of an image, or a text label, or both. By default, Emacs -follows the Gnome desktop's tool bar style setting; if none is -defined, it displays tool bar items as just images. To impose a -specific tool bar style, customize the variable @code{tool-bar-style}. - -@cindex Tool Bar position - You can also control the placement of the tool bar for the GTK+ tool -bar with the frame parameter @code{tool-bar-position}. @xref{Frame -Parameters,,, elisp, The Emacs Lisp Reference Manual}. - -@node Dialog Boxes -@section Using Dialog Boxes -@cindex dialog boxes - -@vindex use-dialog-box - A dialog box is a special kind of menu for asking you a yes-or-no -question or some other special question. Many Emacs commands use a -dialog box to ask a yes-or-no question, if you used the mouse to -invoke the command that led to the question. - - To disable the use of dialog boxes, change the variable -@code{use-dialog-box} to @code{nil}. In that case, Emacs always -performs yes-or-no prompts using the echo area and keyboard input. -This variable also controls whether to use file selection windows (but -those are not supported on all platforms). - -@vindex use-file-dialog -@cindex file selection dialog, how to disable - A file selection window is a special kind of dialog box for asking -for file names. You can customize the variable @code{use-file-dialog} -to suppress the use of file selection windows, even if you still want -other kinds of dialogs. This variable has no effect if you have -suppressed all dialog boxes with the variable @code{use-dialog-box}. - -@vindex x-gtk-show-hidden-files -@vindex x-gtk-file-dialog-help-text -@cindex hidden files, in GTK+ file chooser -@cindex help text, in GTK+ file chooser - When Emacs is compiled with GTK+ support, it uses the GTK+ ``file -chooser'' dialog. Emacs adds an additional toggle button to this -dialog, which you can use to enable or disable the display of hidden -files (files starting with a dot) in that dialog. If you want this -toggle to be activated by default, change the variable -@code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds -help text to the GTK+ file chooser dialog; to disable this help text, -change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. - -@node Tooltips -@section Tooltips -@cindex tooltips - - @dfn{Tooltips} are small windows that display text information at -the current mouse position. They activate when there is a pause in -mouse movement over some significant piece of text in a window, or the -mode line, or some other part of the Emacs frame such as a tool bar -button or menu item. - -@findex tooltip-mode - You can toggle the use of tooltips with the command @kbd{M-x -tooltip-mode}. When Tooltip mode is disabled, the help text is -displayed in the echo area instead. To control the use of tooltips at -startup, customize the variable @code{tooltip-mode}. - -@vindex tooltip-delay - The variables @code{tooltip-delay} specifies how long Emacs should -wait before displaying a tooltip. For additional customization -options for displaying tooltips, use @kbd{M-x customize-group -@key{RET} tooltip @key{RET}}. - -@vindex x-gtk-use-system-tooltips - If Emacs is built with GTK+ support, it displays tooltips via GTK+, -using the default appearance of GTK+ tooltips. To disable this, -change the variable @code{x-gtk-use-system-tooltips} to @code{nil}. -If you do this, or if Emacs is built without GTK+ support, most -attributes of the tooltip text are specified by the @code{tooltip} -face, and by X resources (@pxref{X Resources}). - - @dfn{GUD tooltips} are special tooltips that show the values of -variables when debugging a program with GUD@. @xref{Debugger -Operation}. - -@node Mouse Avoidance -@section Mouse Avoidance -@cindex avoiding mouse in the way of your typing -@cindex mouse avoidance - - On graphical terminals, the mouse pointer may obscure the text in -the Emacs frame. Emacs provides two methods to avoid this problem. - -@vindex make-pointer-invisible - Firstly, Emacs hides the mouse pointer each time you type a -self-inserting character, if the pointer lies inside an Emacs frame; -moving the mouse pointer makes it visible again. To disable this -feature, set the variable @code{make-pointer-invisible} to @code{nil}. - -@vindex mouse-avoidance-mode - Secondly, you can use Mouse Avoidance mode, a minor mode, to keep -the mouse pointer away from point. To use Mouse Avoidance mode, -customize the variable @code{mouse-avoidance-mode}. You can set this -to various values to move the mouse in several ways: - -@table @code -@item banish -Move the pointer to a corner of the frame on any key-press. You can -customize the variable @code{mouse-avoidance-banish-position} to -specify where the pointer goes when it is banished. -@item exile -Banish the pointer only if the cursor gets too close, and allow it to -return once the cursor is out of the way. -@item jump -If the cursor gets too close to the pointer, displace the pointer by a -random distance and direction. -@item animate -As @code{jump}, but shows steps along the way for illusion of motion. -@item cat-and-mouse -The same as @code{animate}. -@item proteus -As @code{animate}, but changes the shape of the mouse pointer too. -@end table - -@findex mouse-avoidance-mode -You can also use the command @kbd{M-x mouse-avoidance-mode} to enable -the mode. Whenever Mouse Avoidance mode moves the mouse, it also -raises the frame. - -@node Non-Window Terminals -@section Non-Window Terminals -@cindex text terminal - - On a text terminal, Emacs can display only one Emacs frame at a -time. However, you can still create multiple Emacs frames, and switch -between them. Switching frames on these terminals is much like -switching between different window configurations. - - Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x -5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete -the current frame. - - Each frame has a number to distinguish it. If your terminal can -display only one frame at a time, the selected frame's number @var{n} -appears near the beginning of the mode line, in the form -@samp{F@var{n}}. - -@findex set-frame-name -@findex select-frame-by-name - @samp{F@var{n}} is in fact the frame's initial name. You can give -frames more meaningful names if you wish, and you can select a frame -by its name. Use the command @kbd{M-x set-frame-name @key{RET} -@var{name} @key{RET}} to specify a new name for the selected frame, -and use @kbd{M-x select-frame-by-name @key{RET} @var{name} @key{RET}} -to select a frame according to its name. The name you specify appears -in the mode line when the frame is selected. - -@node Text-Only Mouse -@section Using a Mouse in Text Terminals -@cindex mouse support -@cindex terminal emulators, mouse support - -Some text terminals support mouse clicks in the terminal window. - -@cindex xterm - In a terminal emulator which is compatible with @command{xterm}, you -can use @kbd{M-x xterm-mouse-mode} to give Emacs control over simple -uses of the mouse---basically, only non-modified single clicks are -supported. The normal @command{xterm} mouse functionality for such -clicks is still available by holding down the @kbd{SHIFT} key when you -press the mouse button. Xterm Mouse mode is a global minor mode -(@pxref{Minor Modes}). Repeating the command turns the mode off -again. - -@findex gpm-mouse-mode - In the console on GNU/Linux, you can use @kbd{M-x gpm-mouse-mode} to -enable mouse support. You must have the gpm server installed and -running on your system in order for this to work. - -@iftex -@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{MS-DOS Mouse}, -@end ifnottex -for information about mouse support on MS-DOS. diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi deleted file mode 100644 index 9da83bb1f74..00000000000 --- a/doc/emacs/glossary.texi +++ /dev/null @@ -1,1472 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Glossary -@unnumbered Glossary -@cindex glossary - -@table @asis -@anchor{Glossary---Abbrev} -@item Abbrev -An abbrev is a text string that expands into a different text string -when present in the buffer. For example, you might define a few letters -as an abbrev for a long phrase that you want to insert frequently. -@xref{Abbrevs}. - -@item Aborting -Aborting means getting out of a recursive edit (q.v.). The -commands @kbd{C-]} and @kbd{M-x top-level} are used for this. -@xref{Quitting}. - -@item Active Region -Setting the mark (q.v.@:) at a position in the text also activates it. -When the mark is active, we call the region an active region. -@xref{Mark}. - -@item Alt -Alt is the name of a modifier bit that a keyboard input character may -have. To make a character Alt, type it while holding down the @key{Alt} -key. Such characters are given names that start with @kbd{@key{Alt}-} -(usually written @kbd{A-} for short). (Note that many terminals have a -key labeled @key{Alt} that is really a @key{META} key.) @xref{User -Input, Alt}. - -@item Argument -@xref{Glossary---Numeric Argument}. - -@item @acronym{ASCII} character -An @acronym{ASCII} character is either an @acronym{ASCII} control -character or an @acronym{ASCII} printing character. @xref{User Input}. - -@item @acronym{ASCII} control character -An @acronym{ASCII} control character is the Control version of an upper-case -letter, or the Control version of one of the characters @samp{@@[\]^_?}. - -@item @acronym{ASCII} printing character -@acronym{ASCII} letters, digits, space, and the following punctuation -characters: @samp{!@@#$%^&*()_-+=|\~`@{@}[]:;"'<>,.?/}. - -@item Auto Fill Mode -Auto Fill mode is a minor mode (q.v.@:) in which text that you insert is -automatically broken into lines of a given maximum width. -@xref{Filling}. - -@item Auto Saving -Auto saving is the practice of periodically saving the contents of an -Emacs buffer in a specially-named file, so that the information will -be preserved if the buffer is lost due to a system error or user error. -@xref{Auto Save}. - -@item Autoloading -Emacs can automatically load Lisp libraries when a Lisp program requests a -function from those libraries. This is called `autoloading'. -@xref{Lisp Libraries}. - -@item Backtrace -A backtrace is a trace of a series of function calls showing how a -program arrived at a certain point. It is used mainly for finding and -correcting bugs (q.v.). Emacs can display a backtrace when it signals -an error or when you type @kbd{C-g} (@pxref{Glossary---Quitting}). -@xref{Checklist}. - -@item Backup File -A backup file records the contents that a file had before the current -editing session. Emacs makes backup files automatically to help you -track down or cancel changes you later regret making. @xref{Backup}. - -@item Balancing Parentheses -Emacs can balance parentheses (or other matching delimiters) either -manually or automatically. You do manual balancing with the commands -to move over parenthetical groupings (@pxref{Moving by Parens}). -Automatic balancing works by blinking or highlighting the delimiter -that matches the one you just inserted, or inserting the matching -delimiter for you (@pxref{Matching,,Matching Parens}). - -@anchor{Glossary---Balanced Expression} -@item Balanced Expressions -A balanced expression is a syntactically recognizable expression, such -as a symbol, number, string constant, block, or parenthesized expression -in C@. @xref{Expressions,Balanced Expressions}. - -@item Balloon Help -@xref{Glossary---Tooltips}. - -@item Base Buffer -A base buffer is a buffer whose text is shared by an indirect buffer -(q.v.). - -@item Bidirectional Text -Some human languages, such as English, are written from left to right. -Others, such as Arabic, are written from right to left. Emacs -supports both of these forms, as well as any mixture of them---this -is `bidirectional text'. @xref{Bidirectional Editing}. - -@item Bind -To bind a key sequence means to give it a binding (q.v.). -@xref{Rebinding}. - -@anchor{Glossary---Binding} -@item Binding -A key sequence gets its meaning in Emacs by having a binding, which is a -command (q.v.), a Lisp function that is run when you type that -sequence. @xref{Commands,Binding}. Customization often involves -rebinding a character to a different command function. The bindings of -all key sequences are recorded in the keymaps (q.v.). @xref{Keymaps}. - -@item Blank Lines -Blank lines are lines that contain only whitespace. Emacs has several -commands for operating on the blank lines in the buffer. @xref{Blank Lines}. - -@item Bookmark -Bookmarks are akin to registers (q.v.@:) in that they record positions -in buffers to which you can return later. Unlike registers, bookmarks -persist between Emacs sessions. @xref{Bookmarks}. - -@item Border -A border is a thin space along the edge of the frame, used just for -spacing, not for displaying anything. An Emacs frame has an ordinary -external border, outside of everything including the menu bar, plus an -internal border that surrounds the text windows, their scroll bars -and fringes, and separates them from the menu bar and tool bar. You -can customize both borders with options and resources (@pxref{Borders -X}). Borders are not the same as fringes (q.v.). - -@item Buffer -The buffer is the basic editing unit; one buffer corresponds to one text -being edited. You normally have several buffers, but at any time you are -editing only one, the `current buffer', though several can be visible -when you are using multiple windows or frames (q.v.). Most buffers -are visiting (q.v.@:) some file. @xref{Buffers}. - -@item Buffer Selection History -Emacs keeps a buffer selection history that records how recently each -Emacs buffer has been selected. This is used for choosing a buffer to -select. @xref{Buffers}. - -@item Bug -A bug is an incorrect or unreasonable behavior of a program, or -inaccurate or confusing documentation. Emacs developers treat bug -reports, both in Emacs code and its documentation, very seriously and -ask you to report any bugs you find. @xref{Bugs}. - -@item Button Down Event -A button down event is the kind of input event (q.v.@:) generated -right away when you press down on a mouse button. @xref{Mouse Buttons}. - -@item By Default -@xref{Glossary---Default}. - -@item Byte Compilation -@xref{Glossary---Compilation}. - -@anchor{Glossary---C-} -@item @kbd{C-} -@kbd{C-} in the name of a character is an abbreviation for Control. -@xref{User Input,C-}. - -@item @kbd{C-M-} -@kbd{C-M-} in the name of a character is an abbreviation for -Control-Meta. If your terminal lacks a real @key{META} key, you type -a Control-Meta character by typing @key{ESC} and then typing the -corresponding Control character. @xref{User Input,C-M-}. - -@item Case Conversion -Case conversion means changing text from upper case to lower case or -vice versa. @xref{Case}. - -@item Character -Characters form the contents of an Emacs buffer. Also, key sequences -(q.v.@:) are usually made up of characters (though they may include -other input events as well). @xref{User Input}. - -@item Character Set -Emacs supports a number of character sets, each of which represents a -particular alphabet or script. @xref{International}. - -@item Character Terminal -@xref{Glossary---Text Terminal}. - -@item Click Event -A click event is the kind of input event (q.v.@:) generated when you -press a mouse button and release it without moving the mouse. -@xref{Mouse Buttons}. - -@item Client -@xref{Glossary---Server}. - -@item Clipboard -A clipboard is a buffer provided by the window system for transferring -text between applications. On the X Window System, the clipboard is -provided in addition to the primary selection (q.v.); on MS-Windows and Mac, -the clipboard is used @emph{instead} of the primary selection. -@xref{Clipboard}. - -@item Coding System -A coding system is an encoding for representing text characters in a -file or in a stream of information. Emacs has the ability to convert -text to or from a variety of coding systems when reading or writing it. -@xref{Coding Systems}. - -@item Command -A command is a Lisp function specially defined to be able to serve as a -key binding in Emacs. When you type a key sequence (q.v.), its -binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find -the command to run. @xref{Commands}. - -@item Command History -@xref{Glossary---Minibuffer History}. - -@item Command Name -A command name is the name of a Lisp symbol that is a command -(@pxref{Commands}). You can invoke any command by its name using -@kbd{M-x} (@pxref{M-x,M-x,Running Commands by Name}). - -@item Comment -A comment is text in a program which is intended only for humans reading -the program, and which is specially marked so that it will be ignored -when the program is loaded or compiled. Emacs offers special commands -for creating, aligning and killing comments. @xref{Comments}. - -@item Common Lisp -Common Lisp is a dialect of Lisp (q.v.@:) much larger and more powerful -than Emacs Lisp. Emacs provides a subset of Common Lisp in the CL -package. @xref{Top, Common Lisp, Overview, cl, Common Lisp Extensions}. - -@anchor{Glossary---Compilation} -@item Compilation -Compilation is the process of creating an executable program from source -code. Emacs has commands for compiling files of Emacs Lisp code -(@pxref{Byte Compilation,,, elisp, the Emacs Lisp -Reference Manual}) and programs in C and other languages -(@pxref{Compilation}). - -@item Complete Key -A complete key is a key sequence that fully specifies one action to be -performed by Emacs. For example, @kbd{X} and @kbd{C-f} and @kbd{C-x m} -are complete keys. Complete keys derive their meanings from being bound -(q.v.@:) to commands (q.v.). Thus, @kbd{X} is conventionally bound to -a command to insert @samp{X} in the buffer; @kbd{C-x m} is -conventionally bound to a command to begin composing a mail message. -@xref{Keys}. - -@item Completion -Completion is what Emacs does when it automatically expands an -abbreviation for a name into the entire name. Completion is done for -minibuffer (q.v.@:) arguments when the set of possible valid inputs -is known; for example, on command names, buffer names, and -file names. Completion usually occurs when @key{TAB}, @key{SPC} or -@key{RET} is typed. @xref{Completion}. - -@anchor{Glossary---Continuation Line} -@item Continuation Line -When a line of text is longer than the width of the window, it -normally (but see @ref{Glossary---Truncation}) takes up more than one -screen line when displayed. We say that the text line is continued, and all -screen lines used for it after the first are called continuation -lines. @xref{Continuation Lines}. A related Emacs feature is -`filling' (q.v.). - -@item Control Character -A control character is a character that you type by holding down the -@key{Ctrl} key. Some control characters also have their own keys, so -that you can type them without using @key{Ctrl}. For example, -@key{RET}, @key{TAB}, @key{ESC} and @key{DEL} are all control -characters. @xref{User Input}. - -@item Copyleft -A copyleft is a notice giving the public legal permission to -redistribute and modify a program or other work of art, but requiring -modified versions to carry similar permission. Copyright is normally -used to keep users divided and helpless; with copyleft we turn that -around to empower users and encourage them to cooperate. - -The particular form of copyleft used by the GNU project is called the -GNU General Public License. @xref{Copying}. - -@item @key{Ctrl} -The @key{Ctrl} or ``control'' key is what you hold down -in order to enter a control character (q.v.). @xref{Glossary---C-}. - -@item Current Buffer -The current buffer in Emacs is the Emacs buffer on which most editing -commands operate. You can select any Emacs buffer as the current one. -@xref{Buffers}. - -@item Current Line -The current line is the line that point is on (@pxref{Point}). - -@item Current Paragraph -The current paragraph is the paragraph that point is in. If point is -between two paragraphs, the current paragraph is the one that follows -point. @xref{Paragraphs}. - -@item Current Defun -The current defun is the defun (q.v.@:) that point is in. If point is -between defuns, the current defun is the one that follows point. -@xref{Defuns}. - -@item Cursor -The cursor is the rectangle on the screen which indicates the position -(called point; q.v.@:) at which insertion and deletion takes place. -The cursor is on or under the character that follows point. Often -people speak of `the cursor' when, strictly speaking, they mean -`point'. @xref{Point,Cursor}. - -@item Customization -Customization is making minor changes in the way Emacs works, to -reflect your preferences or needs. It is often done by setting -variables (@pxref{Variables}) or faces (@pxref{Face Customization}), -or by rebinding key sequences (@pxref{Keymaps}). - -@cindex cut and paste -@item Cut and Paste -@xref{Glossary---Killing}, and @ref{Glossary---Yanking}. - -@anchor{Glossary---Daemon} -@item Daemon -A daemon is a standard term for a system-level process that runs in the -background. Daemons are often started when the system first starts up. -When Emacs runs in daemon-mode, it runs in the background and does not -open a display. You can then connect to it with the -@command{emacsclient} program. @xref{Emacs Server}. - -@item Default Argument -The default for an argument is the value that will be assumed if you -do not specify one. When the minibuffer is used to read an argument, -the default argument is used if you just type @key{RET}. -@xref{Minibuffer}. - -@anchor{Glossary---Default} -@item Default -A default is the value that is used for a certain purpose when -you do not explicitly specify a value to use. - -@item Default Directory -When you specify a file name that does not start with @samp{/} or @samp{~}, -it is interpreted relative to the current buffer's default directory. -(On MS systems, file names that start with a drive letter -@samp{@var{x}:} are treated as absolute, not relative.) -@xref{Minibuffer File,Default Directory}. - -@item Defun -A defun is a major definition at the top level in a program. The name -`defun' comes from Lisp, where most such definitions use the construct -@code{defun}. @xref{Defuns}. - -@item @key{DEL} -@key{DEL} is a character that runs the command to delete one character -of text before the cursor. It is typically either the @key{Delete} -key or the @key{BACKSPACE} key, whichever one is easy to type. -@xref{Erasing,DEL}. - -@item Deletion -Deletion means erasing text without copying it into the kill ring -(q.v.). The alternative is killing (q.v.). @xref{Killing,Deletion}. - -@anchor{Glossary---Deletion of Files} -@item Deletion of Files -Deleting a file means erasing it from the file system. -(Note that some systems use the concept of a ``trash can'', or ``recycle -bin'', to allow you to ``undelete'' files.) -@xref{Misc File Ops,Misc File Ops,Miscellaneous File Operations}. - -@item Deletion of Messages -Deleting a message (in Rmail, and other mail clients) means flagging -it to be eliminated from your mail file. Until you expunge (q.v.@:) -the Rmail file, you can still undelete the messages you have deleted. -@xref{Rmail Deletion}. - -@item Deletion of Windows -Deleting a window means eliminating it from the screen. Other windows -expand to use up the space. The text that was in the window is not -lost, and you can create a new window with the same dimensions as the -old if you wish. @xref{Windows}. - -@item Directory -File directories are named collections in the file system, within which -you can place individual files or subdirectories. They are sometimes -referred to as ``folders''. @xref{Directories}. - -@anchor{Glossary---Directory Local Variable} -@item Directory Local Variable -A directory local variable is a local variable (q.v.@:) that applies -to all the files within a certain directory. @xref{Directory -Variables}. - -@item Dired -Dired is the Emacs facility that displays the contents of a file -directory and allows you to ``edit the directory'', performing -operations on the files in the directory. @xref{Dired}. - -@item Disabled Command -A disabled command is one that you may not run without special -confirmation. The usual reason for disabling a command is that it is -confusing for beginning users. @xref{Disabling}. - -@item Down Event -Short for `button down event' (q.v.). - -@item Drag Event -A drag event is the kind of input event (q.v.@:) generated when you -press a mouse button, move the mouse, and then release the button. -@xref{Mouse Buttons}. - -@item Dribble File -A dribble file is a file into which Emacs writes all the characters that -you type on the keyboard. Dribble files can be used to make a record -for debugging Emacs bugs. Emacs does not make a dribble file unless you -tell it to. @xref{Bugs}. - -@c TODO? Not really appropriate for the user manual I think. -@c Dynamic Binding - -@item Echo Area -The echo area is the bottom line of the screen, used for echoing the -arguments to commands, for asking questions, and showing brief messages -(including error messages). The messages are stored in the buffer -@file{*Messages*} so you can review them later. @xref{Echo Area}. - -@item Echoing -Echoing is acknowledging the receipt of input events by displaying -them (in the echo area). Emacs never echoes single-character key -sequences; longer key sequences echo only if you pause while typing -them. - -@item Electric -We say that a character is electric if it is normally self-inserting -(q.v.), but the current major mode (q.v.@:) redefines it to do something -else as well. For example, some programming language major modes define -particular delimiter characters to reindent the line, or insert one or -more newlines in addition to self-insertion. - -@anchor{Glossary---End Of Line} -@item End Of Line -End of line is a character or a sequence of characters that indicate -the end of a text line. On GNU and Unix systems, this is a newline -(q.v.), but other systems have other conventions. @xref{Coding -Systems,end-of-line}. Emacs can recognize several end-of-line -conventions in files and convert between them. - -@item Environment Variable -An environment variable is one of a collection of variables stored by -the operating system, each one having a name and a value. Emacs can -access environment variables set by its parent shell, and it can set -variables in the environment it passes to programs it invokes. -@xref{Environment}. - -@item EOL -@xref{Glossary---End Of Line}. - -@item Error -An error occurs when an Emacs command cannot execute in the current -circumstances. When an error occurs, execution of the command stops -(unless the command has been programmed to do otherwise) and Emacs -reports the error by displaying an error message (q.v.). -@c Not helpful? -@c Type-ahead is discarded. Then Emacs is ready to read another -@c editing command. - -@item Error Message -An error message is output displayed by Emacs when you ask it to do -something impossible (such as, killing text forward when point is at -the end of the buffer), or when a command malfunctions in some way. -Such messages appear in the echo area, accompanied by a beep. - -@item @key{ESC} -@key{ESC} is a character used as a prefix for typing Meta characters on -keyboards lacking a @key{META} key. Unlike the @key{META} key (which, -like the @key{SHIFT} key, is held down while another character is -typed), you press the @key{ESC} key as you would press a letter key, and -it applies to the next character you type. - -@item Expression -@xref{Glossary---Balanced Expression}. - -@item Expunging -Expunging an Rmail, Gnus newsgroup, or Dired buffer is an operation -that truly discards the messages or files you have previously flagged -for deletion. - -@item Face -A face is a style of displaying characters. It specifies attributes -such as font family and size, foreground and background colors, -underline and strike-through, background stipple, etc. Emacs provides -features to associate specific faces with portions of buffer text, in -order to display that text as specified by the face attributes. -@xref{Faces}. - -@item File Local Variable -A file local variable is a local variable (q.v.@:) specified in a -given file. @xref{File Variables}, and @ref{Glossary---Directory -Local Variable}. - -@anchor{Glossary---File Locking} -@item File Locking -Emacs uses file locking to notice when two different users -start to edit one file at the same time. @xref{Interlocking}. - -@item File Name -@c This is fairly tautological... -A file name is a name that refers to a file. File names may be relative -or absolute; the meaning of a relative file name depends on the current -directory, but an absolute file name refers to the same file regardless -of which directory is current. On GNU and Unix systems, an absolute -file name starts with a slash (the root directory) or with @samp{~/} or -@samp{~@var{user}/} (a home directory). On MS-Windows/MS-DOS, an -absolute file name can also start with a drive letter and a colon, e.g., -@samp{@var{d}:}. - -Some people use the term ``pathname'' for file names, but we do not; -we use the word ``path'' only in the term ``search path'' (q.v.). - -@item File-Name Component -A file-name component names a file directly within a particular -directory. On GNU and Unix systems, a file name is a sequence of -file-name components, separated by slashes. For example, @file{foo/bar} -is a file name containing two components, @samp{foo} and @samp{bar}; it -refers to the file named @samp{bar} in the directory named @samp{foo} in -the current directory. MS-DOS/MS-Windows file names can also use -backslashes to separate components, as in @file{foo\bar}. - -@item Fill Prefix -The fill prefix is a string that should be expected at the beginning -of each line when filling is done. It is not regarded as part of the -text to be filled. @xref{Filling}. - -@anchor{Glossary---Filling} -@item Filling -Filling text means adjusting the position of line-breaks to shift text -between consecutive lines, so that all the lines are approximately the -same length. @xref{Filling}. Some other editors call this feature -``line wrapping''. - -@anchor{Glossary---Font Lock} -@item Font Lock -Font Lock is a mode that highlights parts of buffer text in different -faces, according to the syntax. Some other editors refer to this as -``syntax highlighting''. For example, all comments (q.v.@:) -might be colored red. @xref{Font Lock}. - -@item Fontset -A fontset is a named collection of fonts. A fontset specification lists -character sets and which font to use to display each of them. Fontsets -make it easy to change several fonts at once by specifying the name of a -fontset, rather than changing each font separately. @xref{Fontsets}. - -@item Formfeed Character -@xref{Glossary---Page}. - -@item Frame -A frame is a rectangular cluster of Emacs windows. Emacs starts out -with one frame, but you can create more. You can subdivide each frame -into Emacs windows (q.v.). When you are using a window system -(q.v.), more than one frame can be visible at the same time. -@xref{Frames}. Some other editors use the term ``window'' for this, -but in Emacs a window means something else. - -@item Free Software -Free software is software that gives you the freedom to share, study -and modify it. Emacs is free software, part of the GNU project -(q.v.), and distributed under a copyleft (q.v.@:) license called the -GNU General Public License. @xref{Copying}. - -@anchor{Glossary---Free Software Foundation} -@item Free Software Foundation -The Free Software Foundation (FSF) is a charitable foundation -dedicated to promoting the development of free software (q.v.). -For more information, see @uref{http://fsf.org/, the FSF website}. - -@item Fringe -On a graphical display (q.v.), there's a narrow portion of the frame -(q.v.@:) between the text area and the window's border. These -``fringes'' are used to display symbols that provide information about -the buffer text (@pxref{Fringes}). Emacs displays the fringe using a -special face (q.v.@:) called @code{fringe}. @xref{Faces,fringe}. - -@item FSF -@xref{Glossary---Free Software Foundation}. - -@item FTP -FTP is an acronym for File Transfer Protocol. This is one standard -method for retrieving remote files (q.v.). - -@item Function Key -A function key is a key on the keyboard that sends input but does not -correspond to any character. @xref{Function Keys}. - -@item Global -Global means ``independent of the current environment; in effect -throughout Emacs''. It is the opposite of local (q.v.). Particular -examples of the use of `global' appear below. - -@item Global Abbrev -A global definition of an abbrev (q.v.@:) is effective in all major -modes that do not have local (q.v.@:) definitions for the same abbrev. -@xref{Abbrevs}. - -@item Global Keymap -The global keymap (q.v.@:) contains key bindings that are in effect -everywhere, except when overridden by local key bindings in a major -mode's local keymap (q.v.). @xref{Keymaps}. - -@item Global Mark Ring -The global mark ring records the series of buffers you have recently -set a mark (q.v.@:) in. In many cases you can use this to backtrack -through buffers you have been editing, or in which you have found -tags (@pxref{Glossary---Tags Table}). @xref{Global Mark Ring}. - -@anchor{Glossary---Global Substitution} -@item Global Substitution -Global substitution means replacing each occurrence of one string by -another string throughout a large amount of text. @xref{Replace}. - -@item Global Variable -The global value of a variable (q.v.@:) takes effect in all buffers -that do not have their own local (q.v.@:) values for the variable. -@xref{Variables}. - -@item GNU -GNU is a recursive acronym for GNU's Not Unix, and it refers to a -Unix-compatible operating system which is free software (q.v.). -@xref{Manifesto}. GNU is normally used with Linux as the kernel since -Linux works better than the GNU kernel. For more information, see -@uref{http://www.gnu.org/, the GNU website}. - -@item Graphic Character -Graphic characters are those assigned pictorial images rather than -just names. All the non-Meta (q.v.@:) characters except for the -Control (q.v.@:) characters are graphic characters. These include -letters, digits, punctuation, and spaces; they do not include -@key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts -that character (in ordinary editing modes). @xref{Inserting Text}. - -@item Graphical Display -A graphical display is one that can display images and multiple fonts. -Usually it also has a window system (q.v.). - -@item Highlighting -Highlighting text means displaying it with a different foreground and/or -background color to make it stand out from the rest of the text in the -buffer. - -Emacs uses highlighting in several ways. It highlights the region -whenever it is active (@pxref{Mark}). Incremental search also -highlights matches (@pxref{Incremental Search}). @xref{Glossary---Font Lock}. - -@item Hardcopy -Hardcopy means printed output. Emacs has various commands for -printing the contents of Emacs buffers. @xref{Printing}. - -@item @key{HELP} -@key{HELP} is the Emacs name for @kbd{C-h} or @key{F1}. You can type -@key{HELP} at any time to ask what options you have, or to ask what a -command does. @xref{Help}. - -@item Help Echo -Help echo is a short message displayed in the echo area (q.v.@:) when -the mouse pointer is located on portions of display that require some -explanations. Emacs displays help echo for menu items, parts of the -mode line, tool-bar buttons, etc. On graphical displays, the messages -can be displayed as tooltips (q.v.). @xref{Tooltips}. - -@item Home Directory -Your home directory contains your personal files. On a multi-user GNU -or Unix system, each user has his or her own home directory. When you -start a new login session, your home directory is the default -directory in which to start. A standard shorthand for your home -directory is @samp{~}. Similarly, @samp{~@var{user}} represents the -home directory of some other user. - -@item Hook -A hook is a list of functions to be called on specific occasions, such -as saving a buffer in a file, major mode activation, etc. By -customizing the various hooks, you can modify Emacs's behavior without -changing any of its code. @xref{Hooks}. - -@item Hyper -Hyper is the name of a modifier bit that a keyboard input character may -have. To make a character Hyper, type it while holding down the -@key{Hyper} key. Such characters are given names that start with -@kbd{Hyper-} (usually written @kbd{H-} for short). @xref{User Input}. - -@item Iff -``Iff'' means ``if and only if''. This terminology comes from -mathematics. Try to avoid using this term in documentation, since -many are unfamiliar with it and mistake it for a typo. - -@item Inbox -An inbox is a file in which mail is delivered by the operating system. -Rmail transfers mail from inboxes to Rmail files in which the -mail is then stored permanently or until explicitly deleted. -@xref{Rmail Inbox}. - -@anchor{Glossary---Incremental Search} -@item Incremental Search -Emacs provides an incremental search facility, whereby Emacs begins -searching for a string as soon as you type the first character. -As you type more characters, it refines the search. @xref{Incremental Search}. - -@item Indentation -Indentation means blank space at the beginning of a line. Most -programming languages have conventions for using indentation to -illuminate the structure of the program, and Emacs has special -commands to adjust indentation. -@xref{Indentation}. - -@item Indirect Buffer -An indirect buffer is a buffer that shares the text of another buffer, -called its base buffer (q.v.). @xref{Indirect Buffers}. - -@item Info -Info is the hypertext format used by the GNU project for writing -documentation. - -@item Input Event -An input event represents, within Emacs, one action taken by the user on -the terminal. Input events include typing characters, typing function -keys, pressing or releasing mouse buttons, and switching between Emacs -frames. @xref{User Input}. - -@item Input Method -An input method is a system for entering non-@acronym{ASCII} text characters by -typing sequences of @acronym{ASCII} characters (q.v.). @xref{Input Methods}. - -@item Insertion -Insertion means adding text into the buffer, either from the keyboard -or from some other place in Emacs. - -@item Interlocking -@xref{Glossary---File Locking}. - -@item Isearch -@xref{Glossary---Incremental Search}. - -@item Justification -Justification means adding extra spaces within lines of text in order -to adjust the position of the text edges. @xref{Fill Commands}. - -@item Key Binding -@xref{Glossary---Binding}. - -@item Keyboard Macro -Keyboard macros are a way of defining new Emacs commands from -sequences of existing ones, with no need to write a Lisp program. -You can use a macro to record a sequence of commands, then -play them back as many times as you like. -@xref{Keyboard Macros}. - -@cindex keyboard shortcuts -@item Keyboard Shortcut -A keyboard shortcut is a key sequence (q.v.@:) that invokes a -command. What some programs call ``assigning a keyboard shortcut'', -Emacs calls ``binding a key sequence''. @xref{Glossary---Binding}. - -@item Key Sequence -A key sequence (key, for short) is a sequence of input events (q.v.@:) -that are meaningful as a single unit. If the key sequence is enough to -specify one action, it is a complete key (q.v.); if it is not enough, -it is a prefix key (q.v.). @xref{Keys}. - -@item Keymap -The keymap is the data structure that records the bindings (q.v.@:) of -key sequences to the commands that they run. For example, the global -keymap binds the character @kbd{C-n} to the command function -@code{next-line}. @xref{Keymaps}. - -@item Keyboard Translation Table -The keyboard translation table is an array that translates the character -codes that come from the terminal into the character codes that make up -key sequences. - -@item Kill Ring -The kill ring is where all text you have killed (@pxref{Glossary---Killing}) -recently is saved. You can reinsert any of the killed text still in -the ring; this is called yanking (q.v.). @xref{Yanking}. - -@anchor{Glossary---Killing} -@item Killing -Killing means erasing text and saving it on the kill ring so it can be -yanked (q.v.@:) later. Some other systems call this ``cutting''. -Most Emacs commands that erase text perform killing, as opposed to -deletion (q.v.). @xref{Killing}. - -@item Killing a Job -Killing a job (such as, an invocation of Emacs) means making it cease -to exist. Any data within it, if not saved in a file, is lost. -@xref{Exiting}. - -@item Language Environment -Your choice of language environment specifies defaults for the input -method (q.v.@:) and coding system (q.v.). @xref{Language -Environments}. These defaults are relevant if you edit -non-@acronym{ASCII} text (@pxref{International}). - -@c TODO? Not really appropriate for the user manual I think. -@c Lexical Binding - -@item Line Wrapping -@xref{Glossary---Filling}. - -@item Lisp -Lisp is a programming language. Most of Emacs is written in a dialect -of Lisp, called Emacs Lisp, which is extended with special features that -make it especially suitable for text editing tasks. - -@item List -A list is, approximately, a text string beginning with an open -parenthesis and ending with the matching close parenthesis. In C mode -and other non-Lisp modes, groupings surrounded by other kinds of matched -delimiters appropriate to the language, such as braces, are also -considered lists. Emacs has special commands for many operations on -lists. @xref{Moving by Parens}. - -@item Local -Local means ``in effect only in a particular context''; the relevant -kind of context is a particular function execution, a particular -buffer, or a particular major mode. It is the opposite of `global' -(q.v.). Specific uses of `local' in Emacs terminology appear below. - -@item Local Abbrev -A local abbrev definition is effective only if a particular major mode -is selected. In that major mode, it overrides any global definition -for the same abbrev. @xref{Abbrevs}. - -@item Local Keymap -A local keymap is used in a particular major mode; the key bindings -(q.v.@:) in the current local keymap override global bindings of the -same key sequences. @xref{Keymaps}. - -@item Local Variable -A local value of a variable (q.v.@:) applies to only one buffer. -@xref{Locals}. - -@item @kbd{M-} -@kbd{M-} in the name of a character is an abbreviation for @key{Meta}, -one of the modifier keys that can accompany any character. -@xref{User Input,M-}. - -@item @kbd{M-C-} -@kbd{M-C-} in the name of a character is an abbreviation for -Control-Meta; it means the same thing as `@kbd{C-M-}' (q.v.). - -@item @kbd{M-x} -@kbd{M-x} is the key sequence that is used to call an Emacs command by -name. This is how you run commands that are not bound to key sequences. -@xref{M-x,M-x,Running Commands by Name}. - -@anchor{Glossary---Mail} -@item Mail -Mail means messages sent from one user to another through the computer -system, to be read at the recipient's convenience. Emacs has commands for -composing and sending mail, and for reading and editing the mail you have -received. @xref{Sending Mail}. @xref{Rmail}, for one way to read -mail with Emacs. - -@item Mail Composition Method -A mail composition method is a program runnable within Emacs for editing -and sending a mail message. Emacs lets you select from several -alternative mail composition methods. @xref{Mail Methods}. - -@item Major Mode -The Emacs major modes are a mutually exclusive set of options, each of -which configures Emacs for editing a certain sort of text. Ideally, -each programming language has its own major mode. @xref{Major Modes}. - -@c FIXME: Mention margins for filling? -@item Margin -The space between the usable part of a window (including the -fringe) and the window edge. - -@item Mark -The mark points to a position in the text. It specifies one end of the -region (q.v.), point being the other end. Many commands operate on -all the text from point to the mark. Each buffer has its own mark. -@xref{Mark}. - -@item Mark Ring -The mark ring is used to hold several recent previous locations of the -mark, in case you want to move back to them. Each buffer has its -own mark ring; in addition, there is a single global mark ring (q.v.). -@xref{Mark Ring}. - -@item Menu Bar -The menu bar is a line at the top of an Emacs frame. It contains -words you can click on with the mouse to bring up menus, or you can use -a keyboard interface to navigate it. @xref{Menu Bars}. - -@item Message -@xref{Glossary---Mail}. - -@item Meta -Meta is the name of a modifier bit which you can use in a command -character. To enter a meta character, you hold down the @key{Meta} -key while typing the character. We refer to such characters with -names that start with @kbd{Meta-} (usually written @kbd{M-} for -short). For example, @kbd{M-<} is typed by holding down @key{Meta} -and at the same time typing @kbd{<} (which itself is done, on most -terminals, by holding down @key{SHIFT} and typing @kbd{,}). -@xref{User Input,Meta}. - -On some terminals, the @key{Meta} key is actually labeled @key{Alt} -or @key{Edit}. - -@item Meta Character -A Meta character is one whose character code includes the Meta bit. - -@item Minibuffer -The minibuffer is the window that appears when necessary inside the -echo area (q.v.), used for reading arguments to commands. -@xref{Minibuffer}. - -@anchor{Glossary---Minibuffer History} -@item Minibuffer History -The minibuffer history records the text you have specified in the past -for minibuffer arguments, so you can conveniently use the same text -again. @xref{Minibuffer History}. - -@item Minor Mode -A minor mode is an optional feature of Emacs, which can be switched on -or off independently of all other features. Each minor mode has a -command to turn it on or off. Some minor modes are global (q.v.), -and some are local (q.v.). @xref{Minor Modes}. - -@item Minor Mode Keymap -A minor mode keymap is a keymap that belongs to a minor mode and is -active when that mode is enabled. Minor mode keymaps take precedence -over the buffer's local keymap, just as the local keymap takes -precedence over the global keymap. @xref{Keymaps}. - -@item Mode Line -The mode line is the line at the bottom of each window (q.v.), giving -status information on the buffer displayed in that window. @xref{Mode -Line}. - -@item Modified Buffer -A buffer (q.v.@:) is modified if its text has been changed since the -last time the buffer was saved (or since it was created, if it -has never been saved). @xref{Saving}. - -@item Moving Text -Moving text means erasing it from one place and inserting it in -another. The usual way to move text is by killing (q.v.@:) it and then -yanking (q.v.@:) it. @xref{Killing}. - -@item MULE -@cindex MULE -Prior to Emacs 23, @acronym{MULE} was the name of a software package -which provided a @dfn{MULtilingual Enhancement} to Emacs, by adding -support for multiple character sets (q.v.). @acronym{MULE} was later -integrated into Emacs, and much of it was replaced when Emacs gained -internal Unicode support in version 23. - -Some parts of Emacs that deal with character set support still use the -@acronym{MULE} name. @xref{International}. - -@item Multibyte Character -A multibyte character is a character that takes up several bytes in a -buffer. Emacs uses multibyte characters to represent non-@acronym{ASCII} text, -since the number of non-@acronym{ASCII} characters is much more than 256. -@xref{International Chars, International Characters}. - -@item Named Mark -A named mark is a register (q.v.), in its role of recording a -location in text so that you can move point to that location. -@xref{Registers}. - -@item Narrowing -Narrowing means creating a restriction (q.v.@:) that limits editing in -the current buffer to only a part of the text. Text outside that part -is inaccessible for editing (or viewing) until the boundaries are -widened again, but it is still there, and saving the file saves it -all. @xref{Narrowing}. - -@item Newline -Control-J characters in the buffer terminate lines of text and are -therefore also called newlines. @xref{Glossary---End Of Line}. - -@cindex nil -@cindex t -@item @code{nil} -@code{nil} is a value usually interpreted as a logical ``false''. Its -opposite is @code{t}, interpreted as ``true''. - -@anchor{Glossary---Numeric Argument} -@item Numeric Argument -A numeric argument is a number, specified before a command, to change -the effect of the command. Often the numeric argument serves as a -repeat count. @xref{Arguments}. - -@item Overwrite Mode -Overwrite mode is a minor mode. When it is enabled, ordinary text -characters replace the existing text after point rather than pushing -it to one side. @xref{Minor Modes}. - -@item Package -A package is a collection of Lisp code that you download and -automatically install from within Emacs. Packages provide a -convenient way to add new features. @xref{Packages}. - -@anchor{Glossary---Page} -@item Page -A page is a unit of text, delimited by formfeed characters (@acronym{ASCII} -control-L, code 014) at the beginning of a line. Some Emacs -commands are provided for moving over and operating on pages. -@xref{Pages}. - -@item Paragraph -Paragraphs are the medium-size unit of human-language text. There are -special Emacs commands for moving over and operating on paragraphs. -@xref{Paragraphs}. - -@item Parsing -We say that certain Emacs commands parse words or expressions in the -text being edited. Really, all they know how to do is find the other -end of a word or expression. - -@item Point -Point is the place in the buffer at which insertion and deletion -occur. Point is considered to be between two characters, not at one -character. The terminal's cursor (q.v.@:) indicates the location of -point. @xref{Point}. - -@item Prefix Argument -@xref{Glossary---Numeric Argument}. - -@item Prefix Key -A prefix key is a key sequence (q.v.@:) whose sole function is to -introduce a set of longer key sequences. @kbd{C-x} is an example of -prefix key; any two-character sequence starting with @kbd{C-x} is -therefore a legitimate key sequence. @xref{Keys}. - -@c I don't think this kind of thing needs to be here. -@ignore -@item Primary Rmail File -Your primary Rmail file is the file named @samp{RMAIL} in your home -directory. That's where Rmail stores your incoming mail, unless you -specify a different file name. @xref{Rmail}. -@end ignore - -@item Primary Selection -The primary selection is one particular X selection (q.v.); it is the -selection that most X applications use for transferring text to and from -other applications. - -The Emacs kill commands set the primary selection and the yank command -uses the primary selection when appropriate. @xref{Killing}. - -@item Prompt -A prompt is text used to ask you for input. Displaying a prompt -is called prompting. Emacs prompts always appear in the echo area -(q.v.). One kind of prompting happens when the minibuffer is used to -read an argument (@pxref{Minibuffer}); the echoing that happens when -you pause in the middle of typing a multi-character key sequence is also -a kind of prompting (@pxref{Echo Area}). - -@item Query-Replace -Query-replace is an interactive string replacement feature provided by -Emacs. @xref{Query Replace}. - -@anchor{Glossary---Quitting} -@item Quitting -Quitting means canceling a partially typed command or a running -command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}. - -@item Quoting -Quoting means depriving a character of its usual special significance. -The most common kind of quoting in Emacs is with @kbd{C-q}. What -constitutes special significance depends on the context and on -convention. For example, an ``ordinary'' character as an Emacs command -inserts itself; so in this context, a special character is any character -that does not normally insert itself (such as @key{DEL}, for example), -and quoting it makes it insert itself as if it were not special. Not -all contexts allow quoting. @xref{Inserting Text,Quoting}. - -@item Quoting File Names -Quoting a file name turns off the special significance of constructs -such as @samp{$}, @samp{~} and @samp{:}. @xref{Quoted File Names}. - -@item Read-Only Buffer -A read-only buffer is one whose text you are not allowed to change. -Normally Emacs makes buffers read-only when they contain text which -has a special significance to Emacs; for example, Dired buffers. -Visiting a file that is write-protected also makes a read-only buffer. -@xref{Buffers}. - -@item Rectangle -A rectangle consists of the text in a given range of columns on a given -range of lines. Normally you specify a rectangle by putting point at -one corner and putting the mark at the diagonally opposite corner. -@xref{Rectangles}. - -@item Recursive Editing Level -A recursive editing level is a state in which part of the execution of -a command involves asking you to edit some text. This text may -or may not be the same as the text to which the command was applied. -The mode line indicates recursive editing levels with square brackets -(@samp{[} and @samp{]}). @xref{Recursive Edit}. - -@item Redisplay -Redisplay is the process of correcting the image on the screen to -correspond to changes that have been made in the text being edited. -@xref{Screen,Redisplay}. - -@item Regexp -@xref{Glossary---Regular Expression}. - -@item Region -The region is the text between point (q.v.@:) and the mark (q.v.). -Many commands operate on the text of the region. @xref{Mark,Region}. - -@item Register -Registers are named slots in which text, buffer positions, or -rectangles can be saved for later use. @xref{Registers}. A related -Emacs feature is `bookmarks' (q.v.). - -@anchor{Glossary---Regular Expression} -@item Regular Expression -A regular expression is a pattern that can match various text strings; -for example, @samp{a[0-9]+} matches @samp{a} followed by one or more -digits. @xref{Regexps}. - -@item Remote File -A remote file is a file that is stored on a system other than your own. -Emacs can access files on other computers provided that they are -connected to the same network as your machine, and (obviously) that -you have a supported method to gain access to those files. -@xref{Remote Files}. - -@item Repeat Count -@xref{Glossary---Numeric Argument}. - -@item Replacement -@xref{Glossary---Global Substitution}. - -@item Restriction -A buffer's restriction is the amount of text, at the beginning or the -end of the buffer, that is temporarily inaccessible. Giving a buffer a -nonzero amount of restriction is called narrowing (q.v.); removing -a restriction is called widening (q.v.). @xref{Narrowing}. - -@item @key{RET} -@key{RET} is a character that in Emacs runs the command to insert a -newline into the text. It is also used to terminate most arguments -read in the minibuffer (q.v.). @xref{User Input,Return}. - -@item Reverting -Reverting means returning to the original state. Emacs lets you -revert a buffer by re-reading its file from disk. @xref{Reverting}. - -@c Seems too obvious, also there is nothing special about the format -@c these days. -@ignore -@item Rmail File -An Rmail file is a file containing text in the format used by -Rmail for storing mail. @xref{Rmail}. -@end ignore - -@item Saving -Saving a buffer means copying its text into the file that was visited -(q.v.@:) in that buffer. This is the way text in files actually gets -changed by your Emacs editing. @xref{Saving}. - -@item Scroll Bar -A scroll bar is a tall thin hollow box that appears at the side of a -window. You can use mouse commands in the scroll bar to scroll the -window. The scroll bar feature is supported only under windowing -systems. @xref{Scroll Bars}. - -@item Scrolling -Scrolling means shifting the text in the Emacs window so as to see a -different part of the buffer. @xref{Scrolling}. - -@item Searching -Searching means moving point to the next occurrence of a specified -string or the next match for a specified regular expression. -@xref{Search}. - -@item Search Path -A search path is a list of directory names, to be used for searching for -files for certain purposes. For example, the variable @code{load-path} -holds a search path for finding Lisp library files. @xref{Lisp Libraries}. - -@item Secondary Selection -The secondary selection is one particular X selection (q.v.); some X -applications can use it for transferring text to and from other -applications. Emacs has special mouse commands for transferring text -using the secondary selection. @xref{Secondary Selection}. - -@item Selected Frame -The selected frame is the one your input currently operates on. -@xref{Frames}. - -@item Selected Window -The selected window is the one your input currently operates on. -@xref{Basic Window}. - -@item Selecting a Buffer -Selecting a buffer means making it the current (q.v.@:) buffer. -@xref{Select Buffer}. - -@item Selection -Windowing systems allow an application program to specify -selections whose values are text. A program can also read the -selections that other programs have set up. This is the principal way -of transferring text between window applications. Emacs has commands to -work with the primary (q.v.@:) selection and the secondary (q.v.@:) -selection, and also with the clipboard (q.v.). - -@item Self-Documentation -Self-documentation is the feature of Emacs that can tell you what any -command does, or give you a list of all commands related to a topic -you specify. You ask for self-documentation with the help character, -@kbd{C-h}. @xref{Help}. - -@item Self-Inserting Character -A character is self-inserting if typing that character inserts that -character in the buffer. Ordinary printing and whitespace characters -are self-inserting in Emacs, except in certain special major modes. - -@item Sentences -Emacs has commands for moving by or killing by sentences. -@xref{Sentences}. - -@anchor{Glossary---Server} -@item Server -Within Emacs, you can start a `server' process, which listens for -connections from `clients'. This offers a faster alternative to -starting several Emacs instances. @xref{Emacs Server}, and -@ref{Glossary---Daemon}. - -@c This is only covered in the lispref, not the user manual. -@ignore -@item Session Manager -Some window systems (q.v.@:) provide a tool called a `session manager'. -This offers the ability to save your windows when you log off, -and restore them after you log in again. -@end ignore - -@item Sexp -A sexp (short for ``s-expression'') is the basic syntactic unit of -Lisp in its textual form: either a list, or Lisp atom. Sexps are also -the balanced expressions (q.v.@:) of the Lisp language; this is why -the commands for editing balanced expressions have `sexp' in their -name. @xref{Expressions,Sexps}. - -@item Simultaneous Editing -Simultaneous editing means two users modifying the same file at once. -Simultaneous editing, if not detected, can cause one user to lose his -or her work. Emacs detects all cases of simultaneous editing, and -warns one of the users to investigate. -@xref{Interlocking,Interlocking,Simultaneous Editing}. - -@item @key{SPC} -@key{SPC} is the space character, which you enter by pressing the -space bar. - -@item Speedbar -The speedbar is a special tall frame that provides fast access to Emacs -buffers, functions within those buffers, Info nodes, and other -interesting parts of text within Emacs. @xref{Speedbar}. - -@item Spell Checking -Spell checking means checking correctness of the written form of each -one of the words in a text. Emacs can use various external -spelling-checker programs to check the spelling of parts of a buffer -via a convenient user interface. @xref{Spelling}. - -@item String -A string is a kind of Lisp data object that contains a sequence of -characters. Many Emacs variables are intended to have strings as -values. The Lisp syntax for a string consists of the characters in the -string with a @samp{"} before and another @samp{"} after. A @samp{"} -that is part of the string must be written as @samp{\"} and a @samp{\} -that is part of the string must be written as @samp{\\}. All other -characters, including newline, can be included just by writing them -inside the string; however, backslash sequences as in C, such as -@samp{\n} for newline or @samp{\241} using an octal character code, are -allowed as well. - -@item String Substitution -@xref{Glossary---Global Substitution}. - -@item Syntax Highlighting -@xref{Glossary---Font Lock}. - -@item Syntax Table -The syntax table tells Emacs which characters are part of a word, -which characters balance each other like parentheses, etc. -@xref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp Reference -Manual}. - -@item Super -Super is the name of a modifier bit that a keyboard input character may -have. To make a character Super, type it while holding down the -@key{SUPER} key. Such characters are given names that start with -@kbd{Super-} (usually written @kbd{s-} for short). @xref{User Input}. - -@item Suspending -Suspending Emacs means stopping it temporarily and returning control -to its parent process, which is usually a shell. Unlike killing a job -(q.v.), you can later resume the suspended Emacs job without losing -your buffers, unsaved edits, undo history, etc. @xref{Exiting}. - -@item @key{TAB} -@key{TAB} is the tab character. In Emacs it is typically used for -indentation or completion. - -@anchor{Glossary---Tags Table} -@item Tags Table -A tags table is a file that serves as an index to the function -definitions in one or more other files. @xref{Tags}. - -@item Termscript File -A termscript file contains a record of all characters sent by Emacs to -the terminal. It is used for tracking down bugs in Emacs redisplay. -Emacs does not make a termscript file unless you tell it to. -@xref{Bugs}. - -@item Text -`Text' has two meanings (@pxref{Text}): - -@itemize @bullet -@item -Data consisting of a sequence of characters, as opposed to binary -numbers, executable programs, and the like. The basic contents of an -Emacs buffer (aside from the text properties, q.v.@:) are always text -in this sense. -@item -Data consisting of written human language (as opposed to programs), -or following the stylistic conventions of human language. -@end itemize - -@anchor{Glossary---Text Terminal} -@item Text Terminal -A text terminal, or character terminal, is a display that is limited -to displaying text in character units. Such a terminal cannot control -individual pixels it displays. Emacs supports a subset of display -features on text terminals. - -@item Text Properties -Text properties are annotations recorded for particular characters in -the buffer. Images in the buffer are recorded as text properties; -they also specify formatting information. @xref{Editing Format Info}. - -@item Theme -A theme is a set of customizations (q.v.@:) that give Emacs a -particular appearance or behavior. For example, you might use a theme -for your favorite set of faces (q.v.). - -@item Tool Bar -The tool bar is a line (sometimes multiple lines) of icons at the top -of an Emacs frame. Clicking on one of these icons executes a command. -You can think of this as a graphical relative of the menu bar (q.v.). -@xref{Tool Bars}. - -@anchor{Glossary---Tooltips} -@item Tooltips -Tooltips are small windows displaying a help echo (q.v.@:) text, which -explains parts of the display, lists useful options available via mouse -clicks, etc. @xref{Tooltips}. - -@item Top Level -Top level is the normal state of Emacs, in which you are editing the -text of the file you have visited. You are at top level whenever you -are not in a recursive editing level (q.v.@:) or the minibuffer -(q.v.), and not in the middle of a command. You can get back to top -level by aborting (q.v.@:) and quitting (q.v.). @xref{Quitting}. - -@item Transient Mark Mode -The default behavior of the mark (q.v.@:) and region (q.v.), in which -setting the mark activates it and highlights the region, is called -Transient Mark mode. In GNU Emacs 23 and onwards, it is enabled by -default. @xref{Disabled Transient Mark}. - -@item Transposition -Transposing two units of text means putting each one into the place -formerly occupied by the other. There are Emacs commands to transpose -two adjacent characters, words, balanced expressions (q.v.@:) or lines -(@pxref{Transpose}). - -@item Trash Can -@xref{Glossary---Deletion of Files}. - -@anchor{Glossary---Truncation} -@item Truncation -Truncating text lines in the display means leaving out any text on a -line that does not fit within the right margin of the window -displaying it. @xref{Continuation Lines,Truncation}, and -@ref{Glossary---Continuation Line}. - -@item TTY -@xref{Glossary---Text Terminal}. - -@item Undoing -Undoing means making your previous editing go in reverse, bringing -back the text that existed earlier in the editing session. -@xref{Undo}. - -@item Unix -Unix is a class of multi-user computer operating systems with a long -history. There are several implementations today. The GNU project -(q.v.@:) aims to develop a complete Unix-like operating system that -is free software (q.v.). - -@item User Option -A user option is a face (q.v.@:) or a variable (q.v.@:) that exists so -that you can customize Emacs by setting it to a new value. -@xref{Easy Customization}. - -@item Variable -A variable is an object in Lisp that can store an arbitrary value. -Emacs uses some variables for internal purposes, and has others (known -as `user options'; q.v.@:) just so that you can set their values to -control the behavior of Emacs. The variables used in Emacs that you -are likely to be interested in are listed in the Variables Index in -this manual (@pxref{Variable Index}). @xref{Variables}, for -information on variables. - -@item Version Control -Version control systems keep track of multiple versions of a source file. -They provide a more powerful alternative to keeping backup files (q.v.). -@xref{Version Control}. - -@item Visiting -Visiting a file means loading its contents into a buffer (q.v.@:) -where they can be edited. @xref{Visiting}. - -@item Whitespace -Whitespace is any run of consecutive formatting characters (space, -tab, newline, and backspace). - -@item Widening -Widening is removing any restriction (q.v.@:) on the current buffer; -it is the opposite of narrowing (q.v.). @xref{Narrowing}. - -@item Window -Emacs divides a frame (q.v.@:) into one or more windows, each of which -can display the contents of one buffer (q.v.@:) at any time. -@xref{Screen}, for basic information on how Emacs uses the screen. -@xref{Windows}, for commands to control the use of windows. Some -other editors use the term ``window'' for what we call a `frame' -(q.v.@:) in Emacs. - -@item Window System -A window system is software that operates on a graphical display -(q.v.), to subdivide the screen so that multiple applications can -have their] own windows at the same time. All modern operating systems -include a window system. - -@item Word Abbrev -@xref{Glossary---Abbrev}. - -@item Word Search -Word search is searching for a sequence of words, considering the -punctuation between them as insignificant. @xref{Word Search}. - -@anchor{Glossary---Yanking} -@item Yanking -Yanking means reinserting text previously killed (q.v.). It can be -used to undo a mistaken kill, or for copying or moving text. Some -other systems call this ``pasting''. @xref{Yanking}. -@end table diff --git a/doc/emacs/gnu.texi b/doc/emacs/gnu.texi deleted file mode 100644 index 4eb3672bfde..00000000000 --- a/doc/emacs/gnu.texi +++ /dev/null @@ -1,551 +0,0 @@ -@c Copyright (C) 1985-1987, 1993, 1995, 2001-2014 Free Software -@c Foundation, Inc. -@c -@c Permission is granted to anyone to make or distribute verbatim copies -@c of this document, in any medium, provided that the copyright notice and -@c permission notice are preserved, and that the distributor grants the -@c recipient permission for further redistribution as permitted by this -@c notice. -@c -@c Modified versions may not be made. - -@ifclear justgnu -@node Manifesto -@unnumbered The GNU Manifesto -@end ifclear -@ifset justgnu -@node Top -@top The GNU Manifesto -@end ifset - -@quotation -The GNU Manifesto which appears below was written by Richard Stallman at -the beginning of the GNU project, to ask for participation and support. -For the first few years, it was updated in minor ways to account for -developments, but now it seems best to leave it unchanged as most people -have seen it. - -Since that time, we have learned about certain common misunderstandings -that different wording could help avoid. Footnotes added in 1993 help -clarify these points. - -For up-to-date information about available GNU software, please see -our web site, @uref{http://www.gnu.org}. For software tasks and other -ways to contribute, see @uref{http://www.gnu.org/help}. -@end quotation - -@unnumberedsec What's GNU@? Gnu's Not Unix! - -GNU, which stands for Gnu's Not Unix, is the name for the complete -Unix-compatible software system which I am writing so that I can give it -away free to everyone who can use it.@footnote{The wording here was -careless. The intention was that nobody would have to pay for -@emph{permission} to use the GNU system. But the words don't make this -clear, and people often interpret them as saying that copies of GNU -should always be distributed at little or no charge. That was never the -intent; later on, the manifesto mentions the possibility of companies -providing the service of distribution for a profit. Subsequently I have -learned to distinguish carefully between ``free'' in the sense of -freedom and ``free'' in the sense of price. Free software is software -that users have the freedom to distribute and change. Some users may -obtain copies at no charge, while others pay to obtain copies---and if -the funds help support improving the software, so much the better. The -important thing is that everyone who has a copy has the freedom to -cooperate with others in using it.} Several other volunteers are helping -me. Contributions of time, money, programs and equipment are greatly -needed. - -So far we have an Emacs text editor with Lisp for writing editor commands, -a source level debugger, a yacc-compatible parser generator, a linker, and -around 35 utilities. A shell (command interpreter) is nearly completed. A -new portable optimizing C compiler has compiled itself and may be released -this year. An initial kernel exists but many more features are needed to -emulate Unix. When the kernel and compiler are finished, it will be -possible to distribute a GNU system suitable for program development. We -will use @TeX{} as our text formatter, but an nroff is being worked on. We -will use the free, portable X window system as well. After this we will -add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of -other things, plus on-line documentation. We hope to supply, eventually, -everything useful that normally comes with a Unix system, and more. - -GNU will be able to run Unix programs, but will not be identical to Unix. -We will make all improvements that are convenient, based on our experience -with other operating systems. In particular, we plan to have longer -file names, file version numbers, a crashproof file system, file name -completion perhaps, terminal-independent display support, and perhaps -eventually a Lisp-based window system through which several Lisp programs -and ordinary Unix programs can share a screen. Both C and Lisp will be -available as system programming languages. We will try to support UUCP, -MIT Chaosnet, and Internet protocols for communication. - -GNU is aimed initially at machines in the 68000/16000 class with virtual -memory, because they are the easiest machines to make it run on. The extra -effort to make it run on smaller machines will be left to someone who wants -to use it on them. - -To avoid horrible confusion, please pronounce the `G' in the word `GNU' -when it is the name of this project. - -@unnumberedsec Why I Must Write GNU - -I consider that the golden rule requires that if I like a program I must -share it with other people who like it. Software sellers want to divide -the users and conquer them, making each user agree not to share with -others. I refuse to break solidarity with other users in this way. I -cannot in good conscience sign a nondisclosure agreement or a software -license agreement. For years I worked within the Artificial Intelligence -Lab to resist such tendencies and other inhospitalities, but eventually -they had gone too far: I could not remain in an institution where such -things are done for me against my will. - -So that I can continue to use computers without dishonor, I have decided to -put together a sufficient body of free software so that I will be able to -get along without any software that is not free. I have resigned from the -AI lab to deny MIT any legal excuse to prevent me from giving GNU away. - -@unnumberedsec Why GNU Will Be Compatible with Unix - -Unix is not my ideal system, but it is not too bad. The essential features -of Unix seem to be good ones, and I think I can fill in what Unix lacks -without spoiling them. And a system compatible with Unix would be -convenient for many other people to adopt. - -@unnumberedsec How GNU Will Be Available - -GNU is not in the public domain. Everyone will be permitted to modify and -redistribute GNU, but no distributor will be allowed to restrict its -further redistribution. That is to say, proprietary modifications will not -be allowed. I want to make sure that all versions of GNU remain free. - -@unnumberedsec Why Many Other Programmers Want to Help - -I have found many other programmers who are excited about GNU and want to -help. - -Many programmers are unhappy about the commercialization of system -software. It may enable them to make more money, but it requires them to -feel in conflict with other programmers in general rather than feel as -comrades. The fundamental act of friendship among programmers is the -sharing of programs; marketing arrangements now typically used essentially -forbid programmers to treat others as friends. The purchaser of software -must choose between friendship and obeying the law. Naturally, many decide -that friendship is more important. But those who believe in law often do -not feel at ease with either choice. They become cynical and think that -programming is just a way of making money. - -By working on and using GNU rather than proprietary programs, we can be -hospitable to everyone and obey the law. In addition, GNU serves as an -example to inspire and a banner to rally others to join us in sharing. -This can give us a feeling of harmony which is impossible if we use -software that is not free. For about half the programmers I talk to, this -is an important happiness that money cannot replace. - -@unnumberedsec How You Can Contribute - -I am asking computer manufacturers for donations of machines and money. -I'm asking individuals for donations of programs and work. - -One consequence you can expect if you donate machines is that GNU will run -on them at an early date. The machines should be complete, ready to use -systems, approved for use in a residential area, and not in need of -sophisticated cooling or power. - -I have found very many programmers eager to contribute part-time work for -GNU@. For most projects, such part-time distributed work would be very hard -to coordinate; the independently-written parts would not work together. -But for the particular task of replacing Unix, this problem is absent. A -complete Unix system contains hundreds of utility programs, each of which -is documented separately. Most interface specifications are fixed by Unix -compatibility. If each contributor can write a compatible replacement for -a single Unix utility, and make it work properly in place of the original -on a Unix system, then these utilities will work right when put together. -Even allowing for Murphy to create a few unexpected problems, assembling -these components will be a feasible task. (The kernel will require closer -communication and will be worked on by a small, tight group.) - -If I get donations of money, I may be able to hire a few people full or -part time. The salary won't be high by programmers' standards, but I'm -looking for people for whom building community spirit is as important as -making money. I view this as a way of enabling dedicated people to devote -their full energies to working on GNU by sparing them the need to make a -living in another way. - -@unnumberedsec Why All Computer Users Will Benefit - -Once GNU is written, everyone will be able to obtain good system -software free, just like air.@footnote{This is another place I failed to -distinguish carefully between the two different meanings of ``free.'' -The statement as it stands is not false---you can get copies of GNU -software at no charge, from your friends or over the net. But it does -suggest the wrong idea.} - -This means much more than just saving everyone the price of a Unix license. -It means that much wasteful duplication of system programming effort will -be avoided. This effort can go instead into advancing the state of the -art. - -Complete system sources will be available to everyone. As a result, a user -who needs changes in the system will always be free to make them himself, -or hire any available programmer or company to make them for him. Users -will no longer be at the mercy of one programmer or company which owns the -sources and is in sole position to make changes. - -Schools will be able to provide a much more educational environment by -encouraging all students to study and improve the system code. Harvard's -computer lab used to have the policy that no program could be installed on -the system if its sources were not on public display, and upheld it by -actually refusing to install certain programs. I was very much inspired by -this. - -Finally, the overhead of considering who owns the system software and what -one is or is not entitled to do with it will be lifted. - -Arrangements to make people pay for using a program, including licensing of -copies, always incur a tremendous cost to society through the cumbersome -mechanisms necessary to figure out how much (that is, which programs) a -person must pay for. And only a police state can force everyone to obey -them. Consider a space station where air must be manufactured at great -cost: charging each breather per liter of air may be fair, but wearing the -metered gas mask all day and all night is intolerable even if everyone can -afford to pay the air bill. And the TV cameras everywhere to see if you -ever take the mask off are outrageous. It's better to support the air -plant with a head tax and chuck the masks. - -Copying all or parts of a program is as natural to a programmer as -breathing, and as productive. It ought to be as free. - -@unnumberedsec Some Easily Rebutted Objections to GNU's Goals - -@quotation -``Nobody will use it if it is free, because that means they can't rely -on any support.'' - -``You have to charge for the program to pay for providing the -support.'' -@end quotation - -If people would rather pay for GNU plus service than get GNU free without -service, a company to provide just service to people who have obtained GNU -free ought to be profitable.@footnote{Several such companies now exist.} - -We must distinguish between support in the form of real programming work -and mere handholding. The former is something one cannot rely on from a -software vendor. If your problem is not shared by enough people, the -vendor will tell you to get lost. - -If your business needs to be able to rely on support, the only way is to -have all the necessary sources and tools. Then you can hire any available -person to fix your problem; you are not at the mercy of any individual. -With Unix, the price of sources puts this out of consideration for most -businesses. With GNU this will be easy. It is still possible for there to -be no available competent person, but this problem cannot be blamed on -distribution arrangements. GNU does not eliminate all the world's problems, -only some of them. - -Meanwhile, the users who know nothing about computers need handholding: -doing things for them which they could easily do themselves but don't know -how. - -Such services could be provided by companies that sell just hand-holding -and repair service. If it is true that users would rather spend money and -get a product with service, they will also be willing to buy the service -having got the product free. The service companies will compete in quality -and price; users will not be tied to any particular one. Meanwhile, those -of us who don't need the service should be able to use the program without -paying for the service. - -@quotation -``You cannot reach many people without advertising, -and you must charge for the program to support that.'' - -``It's no use advertising a program people can get free.'' -@end quotation - -There are various forms of free or very cheap publicity that can be used to -inform numbers of computer users about something like GNU@. But it may be -true that one can reach more microcomputer users with advertising. If this -is really so, a business which advertises the service of copying and -mailing GNU for a fee ought to be successful enough to pay for its -advertising and more. This way, only the users who benefit from the -advertising pay for it. - -On the other hand, if many people get GNU from their friends, and such -companies don't succeed, this will show that advertising was not really -necessary to spread GNU@. Why is it that free market advocates don't -want to let the free market decide this?@footnote{The Free Software -Foundation raises most of its funds from a distribution service, -although it is a charity rather than a company. If @emph{no one} -chooses to obtain copies by ordering from the FSF, it will be unable -to do its work. But this does not mean that proprietary restrictions -are justified to force every user to pay. If a small fraction of all -the users order copies from the FSF, that is sufficient to keep the FSF -afloat. So we ask users to choose to support us in this way. Have you -done your part?} - -@quotation -``My company needs a proprietary operating system -to get a competitive edge.'' -@end quotation - -GNU will remove operating system software from the realm of competition. -You will not be able to get an edge in this area, but neither will your -competitors be able to get an edge over you. You and they will compete in -other areas, while benefiting mutually in this one. If your business is -selling an operating system, you will not like GNU, but that's tough on -you. If your business is something else, GNU can save you from being -pushed into the expensive business of selling operating systems. - -I would like to see GNU development supported by gifts from many -manufacturers and users, reducing the cost to each.@footnote{A group of -computer companies recently pooled funds to support maintenance of the -GNU C Compiler.} - -@quotation -``Don't programmers deserve a reward for their creativity?'' -@end quotation - -If anything deserves a reward, it is social contribution. Creativity can -be a social contribution, but only in so far as society is free to use the -results. If programmers deserve to be rewarded for creating innovative -programs, by the same token they deserve to be punished if they restrict -the use of these programs. - -@quotation -``Shouldn't a programmer be able to ask for a reward for his creativity?'' -@end quotation - -There is nothing wrong with wanting pay for work, or seeking to maximize -one's income, as long as one does not use means that are destructive. But -the means customary in the field of software today are based on -destruction. - -Extracting money from users of a program by restricting their use of it is -destructive because the restrictions reduce the amount and the ways that -the program can be used. This reduces the amount of wealth that humanity -derives from the program. When there is a deliberate choice to restrict, -the harmful consequences are deliberate destruction. - -The reason a good citizen does not use such destructive means to become -wealthier is that, if everyone did so, we would all become poorer from the -mutual destructiveness. This is Kantian ethics; or, the Golden Rule. -Since I do not like the consequences that result if everyone hoards -information, I am required to consider it wrong for one to do so. -Specifically, the desire to be rewarded for one's creativity does not -justify depriving the world in general of all or part of that creativity. - -@quotation -``Won't programmers starve?'' -@end quotation - -I could answer that nobody is forced to be a programmer. Most of us cannot -manage to get any money for standing on the street and making faces. But -we are not, as a result, condemned to spend our lives standing on the -street making faces, and starving. We do something else. - -But that is the wrong answer because it accepts the questioner's implicit -assumption: that without ownership of software, programmers cannot possibly -be paid a cent. Supposedly it is all or nothing. - -The real reason programmers will not starve is that it will still be -possible for them to get paid for programming; just not paid as much as -now. - -Restricting copying is not the only basis for business in software. It is -the most common basis because it brings in the most money. If it were -prohibited, or rejected by the customer, software business would move to -other bases of organization which are now used less often. There are -always numerous ways to organize any kind of business. - -Probably programming will not be as lucrative on the new basis as it is -now. But that is not an argument against the change. It is not considered -an injustice that sales clerks make the salaries that they now do. If -programmers made the same, that would not be an injustice either. (In -practice they would still make considerably more than that.) - -@quotation -``Don't people have a right to control how their creativity is used?'' -@end quotation - -``Control over the use of one's ideas'' really constitutes control over -other people's lives; and it is usually used to make their lives more -difficult. - -People who have studied the issue of intellectual property -rights@footnote{In the 80s I had not yet realized how confusing it was -to speak of ``the issue'' of ``intellectual property.'' That term is -obviously biased; more subtle is the fact that it lumps together -various disparate laws which raise very different issues. Nowadays I -urge people to reject the term ``intellectual property'' entirely, -lest it lead others to suppose that those laws form one coherent -issue. The way to be clear is to discuss patents, copyrights, and -trademarks separately. See -@uref{http://www.gnu.org/philosophy/not-ipr.xhtml} for more -explanation of how this term spreads confusion and bias.} carefully -(such as lawyers) say that there is no intrinsic right to intellectual -property. The kinds of supposed intellectual property rights that the -government recognizes were created by specific acts of legislation for -specific purposes. - -For example, the patent system was established to encourage inventors to -disclose the details of their inventions. Its purpose was to help society -rather than to help inventors. At the time, the life span of 17 years for -a patent was short compared with the rate of advance of the state of the -art. Since patents are an issue only among manufacturers, for whom the -cost and effort of a license agreement are small compared with setting up -production, the patents often do not do much harm. They do not obstruct -most individuals who use patented products. - -The idea of copyright did not exist in ancient times, when authors -frequently copied other authors at length in works of non-fiction. This -practice was useful, and is the only way many authors' works have survived -even in part. The copyright system was created expressly for the purpose -of encouraging authorship. In the domain for which it was -invented---books, which could be copied economically only on a printing -press---it did little harm, and did not obstruct most of the individuals -who read the books. - -All intellectual property rights are just licenses granted by society -because it was thought, rightly or wrongly, that society as a whole would -benefit by granting them. But in any particular situation, we have to ask: -are we really better off granting such license? What kind of act are we -licensing a person to do? - -The case of programs today is very different from that of books a hundred -years ago. The fact that the easiest way to copy a program is from one -neighbor to another, the fact that a program has both source code and -object code which are distinct, and the fact that a program is used rather -than read and enjoyed, combine to create a situation in which a person who -enforces a copyright is harming society as a whole both materially and -spiritually; in which a person should not do so regardless of whether the -law enables him to. - -@quotation -``Competition makes things get done better.'' -@end quotation - -The paradigm of competition is a race: by rewarding the winner, we -encourage everyone to run faster. When capitalism really works this way, -it does a good job; but its defenders are wrong in assuming it always works -this way. If the runners forget why the reward is offered and become -intent on winning, no matter how, they may find other strategies---such as, -attacking other runners. If the runners get into a fist fight, they will -all finish late. - -Proprietary and secret software is the moral equivalent of runners in a -fist fight. Sad to say, the only referee we've got does not seem to -object to fights; he just regulates them (``For every ten yards you run, -you can fire one shot''). He really ought to break them up, and penalize -runners for even trying to fight. - -@quotation -``Won't everyone stop programming without a monetary incentive?'' -@end quotation - -Actually, many people will program with absolutely no monetary incentive. -Programming has an irresistible fascination for some people, usually the -people who are best at it. There is no shortage of professional musicians -who keep at it even though they have no hope of making a living that way. - -But really this question, though commonly asked, is not appropriate to the -situation. Pay for programmers will not disappear, only become less. So -the right question is, will anyone program with a reduced monetary -incentive? My experience shows that they will. - -For more than ten years, many of the world's best programmers worked at the -Artificial Intelligence Lab for far less money than they could have had -anywhere else. They got many kinds of non-monetary rewards: fame and -appreciation, for example. And creativity is also fun, a reward in itself. - -Then most of them left when offered a chance to do the same interesting -work for a lot of money. - -What the facts show is that people will program for reasons other than -riches; but if given a chance to make a lot of money as well, they will -come to expect and demand it. Low-paying organizations do poorly in -competition with high-paying ones, but they do not have to do badly if the -high-paying ones are banned. - -@quotation -``We need the programmers desperately. If they demand that we -stop helping our neighbors, we have to obey.'' -@end quotation - -You're never so desperate that you have to obey this sort of demand. -Remember: millions for defense, but not a cent for tribute! - -@quotation -``Programmers need to make a living somehow.'' -@end quotation - -In the short run, this is true. However, there are plenty of ways that -programmers could make a living without selling the right to use a program. -This way is customary now because it brings programmers and businessmen the -most money, not because it is the only way to make a living. It is easy to -find other ways if you want to find them. Here are a number of examples. - -A manufacturer introducing a new computer will pay for the porting of -operating systems onto the new hardware. - -The sale of teaching, hand-holding and maintenance services could also -employ programmers. - -People with new ideas could distribute programs as -freeware@footnote{Subsequently we have discovered the need to -distinguish between ``free software'' and ``freeware''. The term -``freeware'' means software you are free to redistribute, but usually -you are not free to study and change the source code, so most of it is -not free software. See -@uref{http://www.gnu.org/philosophy/words-to-avoid.html} for more -explanation.}, asking for donations from satisfied users, or selling -hand-holding services. I have met people who are already working this -way successfully. - -Users with related needs can form users' groups, and pay dues. A group -would contract with programming companies to write programs that the -group's members would like to use. - -All sorts of development can be funded with a Software Tax: - -@quotation -Suppose everyone who buys a computer has to pay x percent of -the price as a software tax. The government gives this to -an agency like the NSF to spend on software development. - -But if the computer buyer makes a donation to software development -himself, he can take a credit against the tax. He can donate to -the project of his own choosing---often, chosen because he hopes to -use the results when it is done. He can take a credit for any amount -of donation up to the total tax he had to pay. - -The total tax rate could be decided by a vote of the payers of -the tax, weighted according to the amount they will be taxed on. - -The consequences: - -@itemize @bullet -@item -The computer-using community supports software development. -@item -This community decides what level of support is needed. -@item -Users who care which projects their share is spent on -can choose this for themselves. -@end itemize -@end quotation - -In the long run, making programs free is a step toward the post-scarcity -world, where nobody will have to work very hard just to make a living. -People will be free to devote themselves to activities that are fun, such -as programming, after spending the necessary ten hours a week on required -tasks such as legislation, family counseling, robot repair and asteroid -prospecting. There will be no need to be able to make a living from -programming. - -We have already greatly reduced the amount of work that the whole society -must do for its actual productivity, but only a little of this has -translated itself into leisure for workers because much nonproductive -activity is required to accompany productive activity. The main causes of -this are bureaucracy and isometric struggles against competition. Free -software will greatly reduce these drains in the area of software -production. We must do this, in order for technical gains in productivity -to translate into less work for us. diff --git a/doc/emacs/gpl.texi b/doc/emacs/gpl.texi deleted file mode 100644 index 0e2e212acb1..00000000000 --- a/doc/emacs/gpl.texi +++ /dev/null @@ -1,717 +0,0 @@ -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW@. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE@. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi deleted file mode 100644 index c2857331988..00000000000 --- a/doc/emacs/help.texi +++ /dev/null @@ -1,648 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Help -@chapter Help -@kindex Help -@cindex help -@cindex self-documentation -@findex help-command -@kindex C-h -@kindex F1 - -@kindex C-h C-h -@findex help-for-help - Emacs provides a wide variety of help commands, all accessible -through the prefix key @kbd{C-h} (or, equivalently, the function key -@key{F1}). These help commands are described in the following -sections. You can also type @kbd{C-h C-h} to view a list of help -commands (@code{help-for-help}). You can scroll the list with -@key{SPC} and @key{DEL}, then type the help command you want. To -cancel, type @kbd{C-g}. - - Many help commands display their information in a special @dfn{help -buffer}. In this buffer, you can type @key{SPC} and @key{DEL} to -scroll and type @key{RET} to follow hyperlinks. @xref{Help Mode}. - -@cindex searching documentation efficiently -@cindex looking for a subject in documentation - If you are looking for a certain feature, but don't know what it is -called or where to look, we recommend three methods. First, try an -apropos command, then try searching the manual index, then look in the -FAQ and the package keywords. - -@table @kbd -@item C-h a @var{topics} @key{RET} -This searches for commands whose names match the argument -@var{topics}. The argument can be a keyword, a list of keywords, or a -regular expression (@pxref{Regexps}). @xref{Apropos}. - -@item C-h i d m emacs @key{RET} i @var{topic} @key{RET} -This searches for @var{topic} in the indices of the Emacs Info manual, -displaying the first match found. Press @kbd{,} to see subsequent -matches. You can use a regular expression as @var{topic}. - -@item C-h i d m emacs @key{RET} s @var{topic} @key{RET} -Similar, but searches the @emph{text} of the manual rather than the -indices. - -@item C-h C-f -This displays the Emacs FAQ, using Info. - -@item C-h p -This displays the available Emacs packages based on keywords. -@xref{Package Keywords}. -@end table - - @kbd{C-h} or @key{F1} mean ``help'' in various other contexts as -well. For instance, you can type them after a prefix key to view a -list of the keys that can follow the prefix key. (You can also use -@kbd{?} in this context. A few prefix keys don't support @kbd{C-h} -or @kbd{?} in this way, because they define other meanings for those -inputs, but they all support @key{F1}.) - -@menu -* Help Summary:: Brief list of all Help commands. -* Key Help:: Asking what a key does in Emacs. -* Name Help:: Asking about a command, variable or function name. -* Apropos:: Asking what pertains to a given topic. -* Help Mode:: Special features of Help mode and Help buffers. -* Package Keywords:: Finding Lisp libraries by keywords (topics). -* Language Help:: Help relating to international language support. -* Misc Help:: Other help commands. -* Help Files:: Commands to display auxiliary help files. -* Help Echo:: Help on active text and tooltips ("balloon help"). -@end menu - -@iftex -@node Help Summary -@end iftex -@ifnottex -@node Help Summary -@section Help Summary -@end ifnottex - - Here is a summary of help commands for accessing the built-in -documentation. Most of these are described in more detail in the -following sections. - -@table @kbd -@item C-h a @var{topics} @key{RET} -Display a list of commands whose names match @var{topics} -(@code{apropos-command}). -@item C-h b -Display all active key bindings; minor mode bindings first, then those -of the major mode, then global bindings (@code{describe-bindings}). -@item C-h c @var{key} -Show the name of the command that the key sequence @var{key} is bound -to (@code{describe-key-briefly}). Here @kbd{c} stands for -``character''. For more extensive information on @var{key}, use -@kbd{C-h k}. -@item C-h d @var{topics} @key{RET} -Display the commands and variables whose documentation matches -@var{topics} (@code{apropos-documentation}). -@item C-h e -Display the @file{*Messages*} buffer -(@code{view-echo-area-messages}). -@item C-h f @var{function} @key{RET} -Display documentation on the Lisp function named @var{function} -(@code{describe-function}). Since commands are Lisp functions, -this works for commands too. -@item C-h h -Display the @file{HELLO} file, which shows examples of various character -sets. -@item C-h i -Run Info, the GNU documentation browser (@code{info}). The Emacs -manual is available in Info. -@item C-h k @var{key} -Display the name and documentation of the command that @var{key} runs -(@code{describe-key}). -@item C-h l -Display a description of your last 300 keystrokes -(@code{view-lossage}). -@item C-h m -Display documentation of the current major mode (@code{describe-mode}). -@item C-h n -Display news of recent Emacs changes (@code{view-emacs-news}). -@item C-h p -Find packages by topic keyword (@code{finder-by-keyword}). This lists -packages using a package menu buffer. @xref{Packages}. -@item C-h P @var{package} @key{RET} -Display documentation about the specified package -(@code{describe-package}). -@item C-h r -Display the Emacs manual in Info (@code{info-emacs-manual}). -@item C-h s -Display the contents of the current @dfn{syntax table} -(@code{describe-syntax}). The syntax table says which characters are -opening delimiters, which are parts of words, and so on. @xref{Syntax -Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}, for -details. -@item C-h t -Enter the Emacs interactive tutorial (@code{help-with-tutorial}). -@item C-h v @var{var} @key{RET} -Display the documentation of the Lisp variable @var{var} -(@code{describe-variable}). -@item C-h w @var{command} @key{RET} -Show which keys run the command named @var{command} (@code{where-is}). -@item C-h C @var{coding} @key{RET} -Describe the coding system @var{coding} -(@code{describe-coding-system}). -@item C-h C @key{RET} -Describe the coding systems currently in use. -@item C-h F @var{command} @key{RET} -Enter Info and go to the node that documents the Emacs command -@var{command} (@code{Info-goto-emacs-command-node}). -@item C-h I @var{method} @key{RET} -Describe the input method @var{method} (@code{describe-input-method}). -@item C-h K @var{key} -Enter Info and go to the node that documents the key sequence -@var{key} (@code{Info-goto-emacs-key-command-node}). -@item C-h L @var{language-env} @key{RET} -Display information on the character sets, coding systems, and input -methods used in language environment @var{language-env} -(@code{describe-language-environment}). -@item C-h S @var{symbol} @key{RET} -Display the Info documentation on symbol @var{symbol} according to the -programming language you are editing (@code{info-lookup-symbol}). -@item C-h . -Display the help message for a special text area, if point is in one -(@code{display-local-help}). (These include, for example, links in -@file{*Help*} buffers.) -@end table - -@node Key Help -@section Documentation for a Key - -@findex describe-key-briefly -@findex describe-key - The help commands to get information about a key sequence are -@kbd{C-h c} (@code{describe-key-briefly}) and @kbd{C-h k} -(@code{describe-key}). - -@kindex C-h c - @kbd{C-h c @var{key}} displays in the echo area the name of the -command that @var{key} is bound to. For example, @kbd{C-h c C-f} -displays @samp{forward-char}. - -@cindex documentation string -@kindex C-h k - @kbd{C-h k @var{key}} is similar but gives more information: it -displays a help buffer containing the command's @dfn{documentation -string}, which describes exactly what the command does. - -@kindex C-h K -@findex Info-goto-emacs-key-command-node - @kbd{C-h K @var{key}} displays the section of the Emacs manual that -describes the command corresponding to @var{key}. - - @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key -sequences, including function keys, menus, and mouse events. For -instance, after @kbd{C-h k} you can select a menu item from the menu -bar, to view the documentation string of the command it runs. - -@kindex C-h w -@findex where-is - @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to -@var{command}. It displays the list in the echo area. If it says the -command is not on any key, that means you must use @kbd{M-x} to run -it. @kbd{C-h w} runs the command @code{where-is}. - -@node Name Help -@section Help by Command or Variable Name - -@kindex C-h f -@findex describe-function - @kbd{C-h f @var{function} @key{RET}} (@code{describe-function}) -displays the documentation of Lisp function @var{function}, in a -window. Since commands are Lisp functions, you can use this method to -view the documentation of any command whose name you know. For -example, - -@example -C-h f auto-fill-mode @key{RET} -@end example - -@noindent -displays the documentation of @code{auto-fill-mode}. This is the only -way to get the documentation of a command that is not bound to any key -(one which you would normally run using @kbd{M-x}). - - @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp -program. For example, if you have just written the expression -@code{(make-vector len)} and want to check that you are using -@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. -Because @kbd{C-h f} allows all function names, not just command names, -you may find that some of your favorite completion abbreviations that -work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is -unique among command names may not be unique among all function names. - - If you type @kbd{C-h f @key{RET}}, it describes the function called -by the innermost Lisp expression in the buffer around point, -@emph{provided} that function name is a valid, defined Lisp function. -(That name appears as the default while you enter the argument.) For -example, if point is located following the text @samp{(make-vector -(car x)}, the innermost list containing point is the one that starts -with @samp{(make-vector}, so @kbd{C-h f @key{RET}} describes the -function @code{make-vector}. - - @kbd{C-h f} is also useful just to verify that you spelled a -function name correctly. If the minibuffer prompt for @kbd{C-h f} -shows the function name from the buffer as the default, it means that -name is defined as a Lisp function. Type @kbd{C-g} to cancel the -@kbd{C-h f} command if you don't really want to view the -documentation. - -@kindex C-h v -@findex describe-variable - @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but -describes Lisp variables instead of Lisp functions. Its default is -the Lisp symbol around or before point, if that is the name of a -defined Lisp variable. @xref{Variables}. - - Help buffers that describe Emacs variables and functions normally -have hyperlinks to the corresponding source code, if you have the -source files installed (@pxref{Hyperlinking}). - -@kindex C-h F -@findex Info-goto-emacs-command-node - To find a command's documentation in a manual, use @kbd{C-h F} -(@code{Info-goto-emacs-command-node}). This knows about various -manuals, not just the Emacs manual, and finds the right one. - -@node Apropos -@section Apropos -@cindex apropos - - The @dfn{apropos} commands answer questions like, ``What are the -commands for working with files?'' More precisely, you specify an -@dfn{apropos pattern}, which means either a word, a list of words, or -a regular expression. - - Each of the following apropos commands reads an apropos pattern in -the minibuffer, searches for items that match the pattern, and -displays the results in a different window. - -@table @kbd -@item C-h a -@kindex C-h a -@findex apropos-command -Search for commands (@code{apropos-command}). With a prefix argument, -search for noninteractive functions too. - -@item M-x apropos -@findex apropos -Search for functions and variables. Both interactive functions -(commands) and noninteractive functions can be found by this. - -@item M-x apropos-user-option -@findex apropos-user-option -Search for user-customizable variables. With a prefix argument, -search for non-customizable variables too. - -@item M-x apropos-variable -@findex apropos-variable -Search for variables. With a prefix argument, search for -customizable variables only. - -@item M-x apropos-value -@findex apropos-value -Search for variables whose values match the specified pattern. With a -prefix argument, search also for functions with definitions matching -the pattern, and Lisp symbols with properties matching the pattern. - -@item C-h d -@kindex C-h d -@findex apropos-documentation -Search for functions and variables whose documentation strings match -the specified pattern (@code{apropos-documentation}). -@end table - - The simplest kind of apropos pattern is one word. Anything -containing that word matches the pattern. Thus, to find commands that -work on files, type @kbd{C-h a file @key{RET}}. This displays a list -of all command names that contain @samp{file}, including -@code{copy-file}, @code{find-file}, and so on. Each command name -comes with a brief description and a list of keys you can currently -invoke it with. In our example, it would say that you can invoke -@code{find-file} by typing @kbd{C-x C-f}. - - For more information about a function definition, variable or symbol -property listed in an apropos buffer, you can click on it with -@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}. - - When you specify more than one word in the apropos pattern, a name -must contain at least two of the words in order to match. Thus, if -you are looking for commands to kill a chunk of text before point, you -could try @kbd{C-h a kill back backward behind before @key{RET}}. The -real command name @code{kill-backward} will match that; if there were -a command @code{kill-text-before}, it would also match, since it -contains two of the specified words. - - For even greater flexibility, you can specify a regular expression -(@pxref{Regexps}). An apropos pattern is interpreted as a regular -expression if it contains any of the regular expression special -characters, @samp{^$*+?.\[}. - - Following the conventions for naming Emacs commands, here are some -words that you'll find useful in apropos patterns. By using them in -@kbd{C-h a}, you will also get a feel for the naming conventions. - -@quotation -char, line, word, sentence, paragraph, region, page, sexp, list, defun, -rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, -forward, backward, next, previous, up, down, search, goto, kill, delete, -mark, insert, yank, fill, indent, case, change, set, what, list, find, -view, describe, default. -@end quotation - -@vindex apropos-do-all - If the variable @code{apropos-do-all} is non-@code{nil}, the apropos -commands always behave as if they had been given a prefix argument. - -@vindex apropos-sort-by-scores -@cindex apropos search results, order by score -@vindex apropos-documentation-sort-by-scores - By default, all apropos commands except @code{apropos-documentation} -list their results in alphabetical order. If the variable -@code{apropos-sort-by-scores} is non-@code{nil}, these commands -instead try to guess the relevance of each result, and display the -most relevant ones first. The @code{apropos-documentation} command -lists its results in order of relevance by default; to list them in -alphabetical order, change the variable -@code{apropos-documentation-sort-by-scores} to @code{nil}. - -@node Help Mode -@section Help Mode Commands - - Help buffers provide the same commands as View mode (@pxref{View -Mode}); for instance, @key{SPC} scrolls forward, and @key{DEL} or -@kbd{S-@key{SPC}} scrolls backward. A few special commands are also -provided: - -@table @kbd -@item @key{RET} -Follow a cross reference at point (@code{help-follow}). -@item @key{TAB} -Move point forward to the next hyperlink (@code{forward-button}). -@item S-@key{TAB} -Move point back to the previous hyperlink (@code{backward-button}). -@item Mouse-1 -@itemx Mouse-2 -Follow a hyperlink that you click on. -@item C-c C-c -Show all documentation about the symbol at point -(@code{help-follow-symbol}). -@item C-c C-b -Go back to the previous help topic (@code{help-go-back}). -@end table - -@cindex hyperlink -@findex help-follow -@findex help-go-back -@kindex RET @r{(Help mode)} -@kindex C-c C-b @r{(Help mode)} - When a function name, variable name, or face name (@pxref{Faces}) -appears in the documentation in the help buffer, it is normally an -underlined @dfn{hyperlink}. To view the associated documentation, -move point there and type @key{RET} (@code{help-follow}), or click on -the hyperlink with @kbd{Mouse-1} or @kbd{Mouse-2}. Doing so replaces -the contents of the help buffer; to retrace your steps, type @kbd{C-c -C-b} (@code{help-go-back}). - -@cindex URL, viewing in help -@cindex help, viewing web pages -@cindex viewing web pages in help -@cindex web pages, viewing in help -@findex browse-url - A help buffer can also contain hyperlinks to Info manuals, source -code definitions, and URLs (web pages). The first two are opened in -Emacs, and the third using a web browser via the @code{browse-url} -command (@pxref{Browse-URL}). - -@kindex TAB @r{(Help mode)} -@findex forward-button -@kindex S-TAB @r{(Help mode)} -@findex backward-button - In a help buffer, @key{TAB} (@code{forward-button}) moves point -forward to the next hyperlink, while @kbd{S-@key{TAB}} -(@code{backward-button}) point back to the previous hyperlink. These -commands act cyclically; for instance, typing @key{TAB} at the last -hyperlink moves back to the first hyperlink. - - To view all documentation about any symbol in the text, move point -to there and type @kbd{C-c C-c} (@code{help-follow-symbol}). This -shows all available documentation about the symbol---as a variable, -function and/or face. - -@node Package Keywords -@section Keyword Search for Packages -@cindex finder - -Most optional features in Emacs are grouped into @dfn{packages}. -Emacs contains several hundred built-in packages, and more can be -installed over the network (@pxref{Packages}). - -@kindex C-h p -@findex finder-by-keyword - To make it easier to find packages related to a topic, most packages -are associated with one or more @dfn{keywords} based on what they do. -Type @kbd{C-h p} (@code{finder-by-keyword}) to bring up a list of -package keywords, together with a description of what the keywords -mean. To view a list of packages for a given keyword, type @key{RET} -on that line; this displays the list of packages in a Package Menu -buffer (@pxref{Package Menu}). - -@findex describe-package -@kindex C-h P - @kbd{C-h P} (@code{describe-package}) prompts for the name of a -package, and displays a help buffer describing the attributes of the -package and the features that it implements. The buffer lists the -keywords that relate to the package in the form of buttons. Click on -a button to see other packages related to that keyword. - -@node Language Help -@section Help for International Language Support - - For information on a specific language environment (@pxref{Language -Environments}), type @kbd{C-h L} -(@code{describe-language-environment}). This displays a help buffer -describing the languages supported by the language environment, and -listing the associated character sets, coding systems, and input -methods, as well as some sample text for that language environment. - - The command @kbd{C-h h} (@code{view-hello-file}) displays the file -@file{etc/HELLO}, which demonstrates various character sets by showing -how to say ``hello'' in many languages. - - The command @kbd{C-h I} (@code{describe-input-method}) describes an -input method---either a specified input method, or by default the -input method currently in use. @xref{Input Methods}. - - The command @kbd{C-h C} (@code{describe-coding-system}) describes -coding systems---either a specified coding system, or the ones -currently in use. @xref{Coding Systems}. - -@node Misc Help -@section Other Help Commands - -@kindex C-h i -@findex info -@cindex Info -@cindex manuals, included - @kbd{C-h i} (@code{info}) runs the Info program, which browses -structured documentation files. The entire Emacs manual is available -within Info, along with many other manuals for the GNU system. Type -@kbd{h} after entering Info to run a tutorial on using Info. - -@cindex find Info manual by its file name - With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer -@samp{*info*<@var{n}>}. This is useful if you want to browse multiple -Info manuals simultaneously. If you specify just @kbd{C-u} as the -prefix argument, @kbd{C-h i} prompts for the name of a documentation -file, so you can browse a file which doesn't have an entry in the -top-level Info menu. - - The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h -K @var{key}}, described above, enter Info and go straight to the -documentation of @var{function} or @var{key}. - -@kindex C-h S -@findex info-lookup-symbol - When editing a program, if you have an Info version of the manual -for the programming language, you can use @kbd{C-h S} -(@code{info-lookup-symbol}) to find an entry for a symbol (keyword, -function or variable) in the proper manual. The details of how this -command works depend on the major mode. - -@kindex C-h l -@findex view-lossage - If something surprising happens, and you are not sure what you typed, -use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays your last -300 input keystrokes. If you see commands that you don't know, you can -use @kbd{C-h c} to find out what they do. - -@kindex C-h e -@findex view-echo-area-messages - To review recent echo area messages, use @kbd{C-h e} -(@code{view-echo-area-messages}). This displays the buffer -@file{*Messages*}, where those messages are kept. - -@kindex C-h m -@findex describe-mode - Each Emacs major mode typically redefines a few keys and makes other -changes in how editing works. @kbd{C-h m} (@code{describe-mode}) -displays documentation on the current major mode, which normally -describes the commands and features that are changed in this mode. - -@kindex C-h b -@findex describe-bindings -@kindex C-h s -@findex describe-syntax - @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s} -(@code{describe-syntax}) show other information about the current -environment within Emacs. @kbd{C-h b} displays a list of all the key -bindings now in effect: first the local bindings of the current minor -modes, then the local bindings defined by the current major mode, and -finally the global bindings (@pxref{Key Bindings}). @kbd{C-h s} -displays the contents of the syntax table, with explanations of each -character's syntax (@pxref{Syntax Tables,, Syntax Tables, elisp, The -Emacs Lisp Reference Manual}). - -@findex describe-prefix-bindings - You can get a list of subcommands for a particular prefix key by -typing @kbd{C-h}, @kbd{?}, or @key{F1} -(@code{describe-prefix-bindings}) after the prefix key. (There are a -few prefix keys for which not all of these keys work---those that -provide their own bindings for that key. One of these prefix keys -is @key{ESC}, because @kbd{@key{ESC} C-h} is actually @kbd{C-M-h}, -which marks a defun. However, @kbd{@key{ESC} @key{F1}} and -@kbd{@key{ESC} ?} work fine.) - -@node Help Files -@section Help Files - - Apart from the built-in documentation and manuals, Emacs contains -several other files describing topics like copying conditions, release -notes, instructions for debugging and reporting bugs, and so forth. -You can use the following commands to view these files. Apart from -@kbd{C-h g}, they all have the form @kbd{C-h C-@var{char}}. - -@kindex C-h C-c -@findex describe-copying -@kindex C-h C-d -@findex view-emacs-debugging -@kindex C-h C-e -@findex view-external-packages -@kindex C-h C-f -@findex view-emacs-FAQ -@kindex C-h g -@findex describe-gnu-project -@kindex C-h C-m -@findex view-order-manuals -@kindex C-h C-n -@findex view-emacs-news -@kindex C-h C-o -@findex describe-distribution -@kindex C-h C-p -@findex view-emacs-problems -@kindex C-h C-t -@findex view-emacs-todo -@kindex C-h C-w -@findex describe-no-warranty - -@table @kbd -@item C-h C-c -Display the rules under which you can copy and redistribute Emacs -(@code{describe-copying}). -@item C-h C-d -Display help for debugging Emacs (@code{view-emacs-debugging}). -@item C-h C-e -Display information about where to get external packages -(@code{view-external-packages}). -@item C-h C-f -Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). -@item C-h g -Display information about the GNU Project (@code{describe-gnu-project}). -@item C-h C-m -Display information about ordering printed copies of Emacs manuals -(@code{view-order-manuals}). -@item C-h C-n -Display the ``news'' file, which lists the new features in this -version of Emacs (@code{view-emacs-news}). -@item C-h C-o -Display how to order or download the latest version of -Emacs and other GNU software (@code{describe-distribution}). -@item C-h C-p -Display the list of known Emacs problems, sometimes with suggested -workarounds (@code{view-emacs-problems}). -@item C-h C-t -Display the Emacs to-do list (@code{view-emacs-todo}). -@item C-h C-w -Display the full details on the complete absence of warranty for GNU -Emacs (@code{describe-no-warranty}). -@end table - -@node Help Echo -@section Help on Active Text and Tooltips - -@cindex tooltips -@cindex balloon help - In Emacs, stretches of ``active text'' (text that does something -special in response to mouse clicks or @key{RET}) often have -associated help text. This includes hyperlinks in Emacs buffers, as -well as parts of the mode line. On graphical displays, as well as -some text terminals which support mouse tracking, moving the mouse -over the active text displays the help text as a @dfn{tooltip}. -@xref{Tooltips}. - -@kindex C-h . -@findex display-local-help -@vindex help-at-pt-display-when-idle - On terminals that don't support mouse-tracking, you can display the -help text for active buffer text at point by typing @kbd{C-h .} -(@code{display-local-help}). This shows the help text in the echo -area. To display help text automatically whenever it is available at -point, set the variable @code{help-at-pt-display-when-idle} to -@code{t}. diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi deleted file mode 100644 index b254cfca43e..00000000000 --- a/doc/emacs/indent.texi +++ /dev/null @@ -1,255 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Indentation -@chapter Indentation -@cindex indentation -@cindex tabs -@cindex columns (indentation) - -@cindex whitespace character - @dfn{Indentation} refers to inserting or adjusting @dfn{whitespace -characters} (space and/or tab characters) at the beginning of a line -of text. This chapter documents indentation commands and options -which are common to Text mode and related modes, as well as -programming language modes. @xref{Program Indent}, for additional -documentation about indenting in programming modes. - -@findex indent-for-tab-command -@kindex TAB @r{(indentation)} - The simplest way to perform indentation is the @key{TAB} key. In -most major modes, this runs the command @code{indent-for-tab-command}. -(In C and related modes, @key{TAB} runs the command -@code{c-indent-line-or-region}, which behaves similarly). - -@table @key -@item TAB -Insert whitespace, or indent the current line, in a mode-appropriate -way (@code{indent-for-tab-command}). If the region is active, indent -all the lines within it. -@end table - - The exact behavior of @key{TAB} depends on the major mode. In Text -mode and related major modes, @key{TAB} normally inserts some -combination of space and tab characters to advance point to the next -tab stop (@pxref{Tab Stops}). For this purpose, the position of the -first non-whitespace character on the preceding line is treated as an -additional tab stop, so you can use @key{TAB} to ``align'' point with -the preceding line. If the region is active (@pxref{Using Region}), -@key{TAB} acts specially: it indents each line in the region so that -its first non-whitespace character is aligned with the preceding line. - - In programming modes, @key{TAB} indents the current line of code in -a way that makes sense given the code in the preceding lines. If the -region is active, all the lines in the region are indented this way. -If point was initially within the current line's indentation, it is -repositioned to the first non-whitespace character on the line. - - If you just want to insert a tab character in the buffer, type -@kbd{C-q @key{TAB}} (@pxref{Inserting Text}). - -@menu -* Indentation Commands:: More commands for performing indentation. -* Tab Stops:: Stop points for indentation in Text modes. -* Just Spaces:: Using only space characters for indentation. -* Indent Convenience:: Optional indentation features. -@end menu - -@node Indentation Commands -@section Indentation Commands - -Apart from the @key{TAB} (@code{indent-for-tab-command}) command, -Emacs provides a variety of commands to perform indentation in other -ways. - -@table @kbd -@item C-M-o -@kindex C-M-o -@findex split-line -Split the current line at point (@code{split-line}). The text on the -line after point becomes a new line, indented to the same column where -point is located. This command first moves point forward over any -spaces and tabs. Afterward, point is positioned before the inserted -newline. - -@kindex M-m -@findex back-to-indentation -@item M-m -Move (forward or back) to the first non-whitespace character on the -current line (@code{back-to-indentation}). If there are no -non-whitespace characters on the line, move to the end of the line. - -@item M-i -@kindex M-i -@findex tab-to-tab-stop -Indent whitespace at point, up to the next tab stop -(@code{tab-to-tab-stop}). @xref{Tab Stops}. - -@findex indent-relative -@item M-x indent-relative -Insert whitespace at point, until point is aligned with the first -non-whitespace character on the previous line (actually, the last -non-blank line). If point is already farther right than that, run -@code{tab-to-tab-stop} instead---unless called with a numeric -argument, in which case do nothing. - -@item M-^ -@kindex M-^ -@findex delete-indentation -Merge the previous and the current line (@code{delete-indentation}). -This ``joins'' the two lines cleanly, by replacing any indentation at -the front of the current line, together with the line boundary, with a -single space. - -As a special case (useful for Lisp code), the single space is omitted -if the characters to be joined are consecutive opening and closing -parentheses, or if the junction follows another newline. - -If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it -appears after the newline that is deleted. @xref{Fill Prefix}. - -@item C-M-\ -@kindex C-M-\ -@findex indent-region -Indent all the lines in the region, as though you had typed @key{TAB} -at the beginning of each line (@code{indent-region}). - -If a numeric argument is supplied, indent every line in the region to -that column number. - -@item C-x @key{TAB} -@kindex C-x TAB -@findex indent-rigidly -@cindex remove indentation -This command is used to change the indentation of all lines that begin -in the region, moving the affected lines as a ``rigid'' unit. - -If called with no argument, the command activates a transient mode for -adjusting the indentation of the affected lines interactively. While -this transient mode is active, typing @key{LEFT} or @key{RIGHT} -indents leftward and rightward, respectively, by one space. You can -also type @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to indent leftward -or rightward to the next tab stop (@pxref{Tab Stops}). Typing any -other key disables the transient mode, and resumes normal editing. - -If called with a prefix argument @var{n}, this command indents the -lines forward by @var{n} spaces (without enabling the transient mode). -Negative values of @var{n} indent backward, so you can remove all -indentation from the lines in the region using a large negative -argument, like this: - -@smallexample -C-u -999 C-x @key{TAB} -@end smallexample -@end table - -@node Tab Stops -@section Tab Stops -@cindex tab stops - -@vindex tab-stop-list - Emacs defines certain column numbers to be @dfn{tab stops}. These -are used as stopping points by @key{TAB} when inserting whitespace in -Text mode and related modes (@pxref{Indentation}), and by commands -like @kbd{M-i} (@pxref{Indentation Commands}). The variable -@code{tab-stop-list} controls these positions. The default value is -@code{nil}, which means a tab stop every 8 columns. The value can -also be a list of zero-based column numbers (in increasing order) at -which to place tab stops. Emacs extends the list forever by repeating -the difference between the last and next-to-last elements. - -@findex edit-tab-stops -@kindex C-c C-c @r{(Edit Tab Stops)} - Instead of customizing the variable @code{tab-stop-list} directly, a -convenient way to view and set tab stops is via the command @kbd{M-x -edit-tab-stops}. This switches to a buffer containing a description -of the tab stop settings, which looks like this: - -@example - : : : : : : -0 1 2 3 4 -0123456789012345678901234567890123456789012345678 -To install changes, type C-c C-c -@end example - -@noindent -The first line contains a colon at each tab stop. The numbers on the -next two lines are present just to indicate where the colons are. -If the value of @code{tab-stop-list} is @code{nil}, as it is by default, -no colons are displayed initially. - - You can edit this buffer to specify different tab stops by placing -colons on the desired columns. The buffer uses Overwrite mode -(@pxref{Minor Modes}). Remember that Emacs will extend the list of -tab stops forever by repeating the difference between the last two -explicit stops that you place. When you are done, type @kbd{C-c C-c} to make -the new tab stops take effect. Normally, the new tab stop settings -apply to all buffers. However, if you have made the -@code{tab-stop-list} variable local to the buffer where you called -@kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop -settings apply only to that buffer. To save the tab stop settings for -future Emacs sessions, use the Customize interface to save the value -of @code{tab-stop-list} (@pxref{Easy Customization}). - - Note that the tab stops discussed in this section have nothing to do -with how tab characters are displayed in the buffer. Tab characters -are always displayed as empty spaces extending to the next -@dfn{display tab stop}. @xref{Text Display}. - -@node Just Spaces -@section Tabs vs. Spaces - -@vindex tab-width - Normally, indentation commands insert (or remove) an optimal mix of -space characters and tab characters to align to the desired column. -Tab characters are displayed as a stretch of empty space extending to -the next @dfn{display tab stop}. By default, there is one display tab -stop every @code{tab-width} columns (the default is 8). @xref{Text -Display}. - -@vindex indent-tabs-mode - If you prefer, all indentation can be made from spaces only. To -request this, set the buffer-local variable @code{indent-tabs-mode} to -@code{nil}. @xref{Locals}, for information about setting buffer-local -variables. Note, however, that @kbd{C-q @key{TAB}} always inserts a -tab character, regardless of the value of @code{indent-tabs-mode}. - - One reason to set @code{indent-tabs-mode} to @code{nil} is that not -all editors display tab characters in the same way. Emacs users, too, -may have different customized values of @code{tab-width}. By using -spaces only, you can make sure that your file always looks the same. -If you only care about how it looks within Emacs, another way to -tackle this problem is to set the @code{tab-width} variable in a -file-local variable (@pxref{File Variables}). - -@findex tabify -@findex untabify - There are also commands to convert tabs to spaces or vice versa, always -preserving the columns of all non-whitespace text. @kbd{M-x tabify} scans the -region for sequences of spaces, and converts sequences of at least two -spaces to tabs if that can be done without changing indentation. @kbd{M-x -untabify} changes all tabs in the region to appropriate numbers of spaces. - -@node Indent Convenience -@section Convenience Features for Indentation - -@vindex tab-always-indent - The variable @code{tab-always-indent} tweaks the behavior of the -@key{TAB} (@code{indent-for-tab-command}) command. The default value, -@code{t}, gives the behavior described in @ref{Indentation}. If you -change the value to the symbol @code{complete}, then @key{TAB} first -tries to indent the current line, and if the line was already -indented, it tries to complete the text at point (@pxref{Symbol -Completion}). If the value is @code{nil}, then @key{TAB} indents the -current line only if point is at the left margin or in the line's -indentation; otherwise, it inserts a tab character. - -@cindex Electric Indent mode -@cindex mode, Electric Indent -@findex electric-indent-mode - Electric Indent mode is a global minor mode that automatically -indents the line after every @key{RET} you type. This mode is enabled -by default. To toggle this minor mode, type @kbd{M-x -electric-indent-mode}. To toggle the mode in a single buffer, -use @kbd{M-x electric-indent-local-mode}. diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi deleted file mode 100644 index f4b1752643d..00000000000 --- a/doc/emacs/killing.texi +++ /dev/null @@ -1,917 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. - -@node Killing -@chapter Killing and Moving Text - - In Emacs, @dfn{killing} means erasing text and copying it into the -@dfn{kill ring}. @dfn{Yanking} means bringing text from the kill ring -back into the buffer. (Some applications use the terms ``cutting'' -and ``pasting'' for similar operations.) The kill ring is so-named -because it can be visualized as a set of blocks of text arranged in a -ring, which you can access in cyclic order. @xref{Kill Ring}. - - Killing and yanking are the most common way to move or copy text -within Emacs. It is very versatile, because there are commands for -killing many different types of syntactic units. - -@menu -* Deletion and Killing:: Commands that remove text. -* Yanking:: Commands that insert text. -* Cut and Paste:: Clipboard and selections on graphical displays. -* Accumulating Text:: Other methods to add text to the buffer. -* Rectangles:: Operating on text in rectangular areas. -* CUA Bindings:: Using @kbd{C-x}/@kbd{C-c}/@kbd{C-v} to kill and yank. -@end menu - -@node Deletion and Killing -@section Deletion and Killing - -@cindex killing text -@cindex cutting text -@cindex deletion - Most commands which erase text from the buffer save it in the kill -ring. These are known as @dfn{kill} commands, and their names -normally contain the word @samp{kill} (e.g., @code{kill-line}). The -kill ring stores several recent kills, not just the last one, so -killing is a very safe operation: you don't have to worry much about -losing text that you previously killed. The kill ring is shared by -all buffers, so text that is killed in one buffer can be yanked into -another buffer. - - When you use @kbd{C-/} (@code{undo}) to undo a kill command -(@pxref{Undo}), that brings the killed text back into the buffer, but -does not remove it from the kill ring. - - On graphical displays, killing text also copies it to the system -clipboard. @xref{Cut and Paste}. - - Commands that erase text but do not save it in the kill ring are -known as @dfn{delete} commands; their names usually contain the word -@samp{delete}. These include @kbd{C-d} (@code{delete-char}) and -@key{DEL} (@code{delete-backward-char}), which delete only one -character at a time, and those commands that delete only spaces or -newlines. Commands that can erase significant amounts of nontrivial -data generally do a kill operation instead. - - You can also use the mouse to kill and yank. @xref{Cut and Paste}. - -@menu -* Deletion:: Commands for deleting small amounts of text and - blank areas. -* Killing by Lines:: How to kill entire lines of text at one time. -* Other Kill Commands:: Commands to kill large regions of text and - syntactic units such as words and sentences. -* Kill Options:: Options that affect killing. -@end menu - -@node Deletion -@subsection Deletion -@findex delete-backward-char -@findex delete-char - - Deletion means erasing text and not saving it in the kill ring. For -the most part, the Emacs commands that delete text are those that -erase just one character or only whitespace. - -@table @kbd -@item @key{DEL} -@itemx @key{BACKSPACE} -Delete the previous character, or the text in the region if it is -active (@code{delete-backward-char}). - -@item @key{Delete} -Delete the next character, or the text in the region if it is active -(@code{delete-forward-char}). - -@item C-d -Delete the next character (@code{delete-char}). - -@item M-\ -Delete spaces and tabs around point (@code{delete-horizontal-space}). -@item M-@key{SPC} -Delete spaces and tabs around point, leaving one space -(@code{just-one-space}). -@item C-x C-o -Delete blank lines around the current line (@code{delete-blank-lines}). -@item M-^ -Join two lines by deleting the intervening newline, along with any -indentation following it (@code{delete-indentation}). -@end table - - We have already described the basic deletion commands @key{DEL} -(@code{delete-backward-char}), @key{delete} -(@code{delete-forward-char}), and @kbd{C-d} (@code{delete-char}). -@xref{Erasing}. With a numeric argument, they delete the specified -number of characters. If the numeric argument is omitted or one, they -delete all the text in the region if it is active (@pxref{Using -Region}). - -@kindex M-\ -@findex delete-horizontal-space -@kindex M-SPC -@findex just-one-space -@findex cycle-spacing - The other delete commands are those that delete only whitespace -characters: spaces, tabs and newlines. @kbd{M-\} -(@code{delete-horizontal-space}) deletes all the spaces and tab -characters before and after point. With a prefix argument, this only -deletes spaces and tab characters before point. @kbd{M-@key{SPC}} -(@code{just-one-space}) does likewise but leaves a single space before -point, regardless of the number of spaces that existed previously -(even if there were none before). With a numeric argument @var{n}, it -leaves @var{n} spaces before point if @var{n} is positive; if @var{n} -is negative, it deletes newlines in addition to spaces and tabs, -leaving @var{-n} spaces before point. The command @code{cycle-spacing} -acts like a more flexible version of @code{just-one-space}. It -does different things if you call it repeatedly in succession. -The first call acts like @code{just-one-space}, the next removes -all whitespace, and a third call restores the original whitespace. - - @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines -after the current line. If the current line is blank, it deletes all -blank lines preceding the current line as well (leaving one blank line, -the current line). On a solitary blank line, it deletes that line. - - @kbd{M-^} (@code{delete-indentation}) joins the current line and the -previous line, by deleting a newline and all surrounding spaces, usually -leaving a single space. @xref{Indentation,M-^}. - -@c Not really sure where to put this... -@findex delete-duplicate-lines - The command @code{delete-duplicate-lines} searches the region for -identical lines, and removes all but one copy of each. Normally it -keeps the first instance of each repeated line, but with a @kbd{C-u} -prefix argument it keeps the last. With a @kbd{C-u C-u} prefix -argument, it only searches for adjacent identical lines. This is a -more efficient mode of operation, useful when the lines have already -been sorted. With a @kbd{C-u C-u C-u} prefix argument, it retains -repeated blank lines. - -@node Killing by Lines -@subsection Killing by Lines - -@table @kbd -@item C-k -Kill rest of line or one or more lines (@code{kill-line}). -@item C-S-backspace -Kill an entire line at once (@code{kill-whole-line}) -@end table - -@kindex C-k -@findex kill-line - The simplest kill command is @kbd{C-k} (@code{kill-line}). If used -at the end of a line, it kills the line-ending newline character, -merging the next line into the current one (thus, a blank line is -entirely removed). Otherwise, @kbd{C-k} kills all the text from point -up to the end of the line; if point was originally at the beginning of -the line, this leaves the line blank. - - Spaces and tabs at the end of the line are ignored when deciding -which case applies. As long as point is after the last visible -character in the line, you can be sure that @kbd{C-k} will kill the -newline. To kill an entire non-blank line, go to the beginning and -type @kbd{C-k} twice. - - In this context, ``line'' means a logical text line, not a screen -line (@pxref{Continuation Lines}). - - When @kbd{C-k} is given a positive argument @var{n}, it kills -@var{n} lines and the newlines that follow them (text on the current -line before point is not killed). With a negative argument -@minus{}@var{n}, it kills @var{n} lines preceding the current line, -together with the text on the current line before point. @kbd{C-k} -with an argument of zero kills the text before point on the current -line. - -@vindex kill-whole-line - If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at -the very beginning of a line kills the entire line including the -following newline. This variable is normally @code{nil}. - -@kindex C-S-backspace -@findex kill-whole-line - @kbd{C-S-backspace} (@code{kill-whole-line}) kills a whole line -including its newline, regardless of the position of point within the -line. Note that many text terminals will prevent you from typing the -key sequence @kbd{C-S-backspace}. - -@node Other Kill Commands -@subsection Other Kill Commands -@findex kill-region -@kindex C-w - -@table @kbd -@item C-w -Kill the region (@code{kill-region}). -@item M-w -Copy the region into the kill ring (@code{kill-ring-save}). -@item M-d -Kill the next word (@code{kill-word}). @xref{Words}. -@item M-@key{DEL} -Kill one word backwards (@code{backward-kill-word}). -@item C-x @key{DEL} -Kill back to beginning of sentence (@code{backward-kill-sentence}). -@xref{Sentences}. -@item M-k -Kill to the end of the sentence (@code{kill-sentence}). -@item C-M-k -Kill the following balanced expression (@code{kill-sexp}). @xref{Expressions}. -@item M-z @var{char} -Kill through the next occurrence of @var{char} (@code{zap-to-char}). -@end table - -@kindex C-w -@findex kill-region -@kindex M-w -@findex kill-ring-save - One of the commonly-used kill commands is @kbd{C-w} -(@code{kill-region}), which kills the text in the region -(@pxref{Mark}). Similarly, @kbd{M-w} (@code{kill-ring-save}) copies -the text in the region into the kill ring without removing it from the -buffer. If the mark is inactive when you type @kbd{C-w} or @kbd{M-w}, -the command acts on the text between point and where you last set the -mark (@pxref{Using Region}). - - Emacs also provides commands to kill specific syntactic units: -words, with @kbd{M-@key{DEL}} and @kbd{M-d} (@pxref{Words}); balanced -expressions, with @kbd{C-M-k} (@pxref{Expressions}); and sentences, -with @kbd{C-x @key{DEL}} and @kbd{M-k} (@pxref{Sentences}). - -@kindex M-z -@findex zap-to-char - The command @kbd{M-z} (@code{zap-to-char}) combines killing with -searching: it reads a character and kills from point up to (and -including) the next occurrence of that character in the buffer. A -numeric argument acts as a repeat count; a negative argument means to -search backward and kill text before point. - -@node Kill Options -@subsection Options for Killing - -@vindex kill-read-only-ok -@cindex read-only text, killing - Some specialized buffers contain @dfn{read-only text}, which cannot -be modified and therefore cannot be killed. The kill commands work -specially in a read-only buffer: they move over text and copy it to -the kill ring, without actually deleting it from the buffer. -Normally, they also beep and display an error message when this -happens. But if you set the variable @code{kill-read-only-ok} to a -non-@code{nil} value, they just print a message in the echo area to -explain why the text has not been erased. - -@vindex kill-do-not-save-duplicates - If you change the variable @code{kill-do-not-save-duplicates} to a -non-@code{nil} value, identical subsequent kills yield a single -kill-ring entry, without duplication. - -@node Yanking -@section Yanking -@cindex moving text -@cindex copying text -@cindex kill ring -@cindex yanking -@cindex pasting - - @dfn{Yanking} means reinserting text previously killed. The usual -way to move or copy text is to kill it and then yank it elsewhere. - -@table @kbd -@item C-y -Yank the last kill into the buffer, at point (@code{yank}). -@item M-y -Replace the text just yanked with an earlier batch of killed text -(@code{yank-pop}). @xref{Earlier Kills}. -@item C-M-w -Cause the following command, if it is a kill command, to append to the -previous kill (@code{append-next-kill}). @xref{Appending Kills}. -@end table - -@kindex C-y -@findex yank - The basic yanking command is @kbd{C-y} (@code{yank}). It inserts -the most recent kill, leaving the cursor at the end of the inserted -text. It also sets the mark at the beginning of the inserted text, -without activating the mark; this lets you jump easily to that -position, if you wish, with @kbd{C-u C-@key{SPC}} (@pxref{Mark Ring}). - - With a plain prefix argument (@kbd{C-u C-y}), the command instead -leaves the cursor in front of the inserted text, and sets the mark at -the end. Using any other prefix argument specifies an earlier kill; -e.g., @kbd{C-u 4 C-y} reinserts the fourth most recent kill. -@xref{Earlier Kills}. - - On graphical displays, @kbd{C-y} first checks if another application -has placed any text in the system clipboard more recently than the -last Emacs kill. If so, it inserts the clipboard's text instead. -Thus, Emacs effectively treats ``cut'' or ``copy'' clipboard -operations performed in other applications like Emacs kills, except -that they are not recorded in the kill ring. @xref{Cut and Paste}, -for details. - -@menu -* Kill Ring:: Where killed text is stored. -* Earlier Kills:: Yanking something killed some time ago. -* Appending Kills:: Several kills in a row all yank together. -@end menu - -@node Kill Ring -@subsection The Kill Ring - - The @dfn{kill ring} is a list of blocks of text that were previously -killed. There is only one kill ring, shared by all buffers, so you -can kill text in one buffer and yank it in another buffer. This is -the usual way to move text from one buffer to another. (There are -several other methods: for instance, you could store the text in a -register; see @ref{Registers}. @xref{Accumulating Text}, for some -other ways to move text around.) - -@vindex kill-ring-max - The maximum number of entries in the kill ring is controlled by the -variable @code{kill-ring-max}. The default is 60. If you make a new -kill when this limit has been reached, Emacs makes room by deleting -the oldest entry in the kill ring. - -@vindex kill-ring - The actual contents of the kill ring are stored in a variable named -@code{kill-ring}; you can view the entire contents of the kill ring -with @kbd{C-h v kill-ring}. - -@node Earlier Kills -@subsection Yanking Earlier Kills -@cindex yanking previous kills - - As explained in @ref{Yanking}, you can use a numeric argument to -@kbd{C-y} to yank text that is no longer the most recent kill. This -is useful if you remember which kill ring entry you want. If you -don't, you can use the @kbd{M-y} (@code{yank-pop}) command to cycle -through the possibilities. - -@kindex M-y -@findex yank-pop - If the previous command was a yank command, @kbd{M-y} takes the text -that was yanked and replaces it with the text from an earlier kill. -So, to recover the text of the next-to-the-last kill, first use -@kbd{C-y} to yank the last kill, and then use @kbd{M-y} to replace it -with the previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} -or another @kbd{M-y}. - - You can understand @kbd{M-y} in terms of a ``last yank'' pointer which -points at an entry in the kill ring. Each time you kill, the ``last -yank'' pointer moves to the newly made entry at the front of the ring. -@kbd{C-y} yanks the entry which the ``last yank'' pointer points to. -@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the -text in the buffer changes to match. Enough @kbd{M-y} commands can move -the pointer to any entry in the ring, so you can get any entry into the -buffer. Eventually the pointer reaches the end of the ring; the next -@kbd{M-y} loops back around to the first entry again. - - @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does -not change the order of the entries in the ring, which always runs from -the most recent kill at the front to the oldest one still remembered. - - @kbd{M-y} can take a numeric argument, which tells it how many entries -to advance the ``last yank'' pointer by. A negative argument moves the -pointer toward the front of the ring; from the front of the ring, it -moves ``around'' to the last entry and continues forward from there. - - Once the text you are looking for is brought into the buffer, you can -stop doing @kbd{M-y} commands and it will stay there. It's just a copy -of the kill ring entry, so editing it in the buffer does not change -what's in the ring. As long as no new killing is done, the ``last -yank'' pointer remains at the same place in the kill ring, so repeating -@kbd{C-y} will yank another copy of the same previous kill. - - When you call @kbd{C-y} with a numeric argument, that also sets the -``last yank'' pointer to the entry that it yanks. - -@node Appending Kills -@subsection Appending Kills - -@cindex appending kills in the ring - Normally, each kill command pushes a new entry onto the kill ring. -However, two or more kill commands in a row combine their text into a -single entry, so that a single @kbd{C-y} yanks all the text as a unit, -just as it was before it was killed. - - Thus, if you want to yank text as a unit, you need not kill all of it -with one command; you can keep killing line after line, or word after -word, until you have killed it all, and you can still get it all back at -once. - - Commands that kill forward from point add onto the end of the previous -killed text. Commands that kill backward from point add text onto the -beginning. This way, any sequence of mixed forward and backward kill -commands puts all the killed text into one entry without rearrangement. -Numeric arguments do not break the sequence of appending kills. For -example, suppose the buffer contains this text: - -@example -This is a line @point{}of sample text. -@end example - -@noindent -with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d -M-@key{DEL}}, killing alternately forward and backward, you end up with -@samp{a line of sample} as one entry in the kill ring, and @samp{This -is@ @ text.} in the buffer. (Note the double space between @samp{is} -and @samp{text}, which you can clean up with @kbd{M-@key{SPC}} or -@kbd{M-q}.) - - Another way to kill the same text is to move back two words with -@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}. -This produces exactly the same results in the buffer and in the kill -ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going -backward; once again, the result is the same. The text in the kill ring -entry always has the same order that it had in the buffer before you -killed it. - -@kindex C-M-w -@findex append-next-kill - If a kill command is separated from the last kill command by other -commands (not just numeric arguments), it starts a new entry on the -kill ring. But you can force it to combine with the last killed text, -by typing @kbd{C-M-w} (@code{append-next-kill}) right beforehand. The -@kbd{C-M-w} tells its following command, if it is a kill command, to -treat the kill as part of the sequence of previous kills. As usual, -the kill is appended to the previous killed text if the command kills -forward, and prepended if the command kills backward. In this way, -you can kill several separated pieces of text and accumulate them to -be yanked back in one place. - - A kill command following @kbd{M-w} (@code{kill-ring-save}) does not -append to the text that @kbd{M-w} copied into the kill ring. - -@node Cut and Paste -@section ``Cut and Paste'' Operations on Graphical Displays -@cindex cut -@cindex copy -@cindex paste - - In most graphical desktop environments, you can transfer data -(usually text) between different applications using a system facility -called the @dfn{clipboard}. On X, two other similar facilities are -available: the primary selection and the secondary selection. When -Emacs is run on a graphical display, its kill and yank commands -integrate with these facilities, so that you can easily transfer text -between Emacs and other graphical applications. - - By default, Emacs uses UTF-8 as the coding system for inter-program -text transfers. If you find that the pasted text is not what you -expected, you can specify another coding system by typing @kbd{C-x -@key{RET} x} or @kbd{C-x @key{RET} X}. You can also request a -different data type by customizing @code{x-select-request-type}. -@xref{Communication Coding}. - -@menu -* Clipboard:: How Emacs uses the system clipboard. -* Primary Selection:: The temporarily selected text selection. -* Secondary Selection:: Cutting without altering point and mark. -@end menu - -@node Clipboard -@subsection Using the Clipboard -@cindex clipboard - - The @dfn{clipboard} is the facility that most graphical applications -use for ``cutting and pasting''. When the clipboard exists, the kill -and yank commands in Emacs make use of it. - - When you kill some text with a command such as @kbd{C-w} -(@code{kill-region}), or copy it to the kill ring with a command such -as @kbd{M-w} (@code{kill-ring-save}), that text is also put in the -clipboard. - -@vindex save-interprogram-paste-before-kill - When an Emacs kill command puts text in the clipboard, the existing -clipboard contents are normally lost. Optionally, you can change -@code{save-interprogram-paste-before-kill} to @code{t}. Then Emacs -will first save the clipboard to its kill ring, preventing you from -losing the old clipboard data---at the risk of high memory consumption -if that data turns out to be large. - - Yank commands, such as @kbd{C-y} (@code{yank}), also use the -clipboard. If another application ``owns'' the clipboard---i.e., if -you cut or copied text there more recently than your last kill command -in Emacs---then Emacs yanks from the clipboard instead of the kill -ring. - -@vindex yank-pop-change-selection - Normally, rotating the kill ring with @kbd{M-y} (@code{yank-pop}) -does not alter the clipboard. However, if you change -@code{yank-pop-change-selection} to @code{t}, then @kbd{M-y} saves the -new yank to the clipboard. - -@vindex x-select-enable-clipboard - To prevent kill and yank commands from accessing the clipboard, -change the variable @code{x-select-enable-clipboard} to @code{nil}. - -@cindex clipboard manager -@vindex x-select-enable-clipboard-manager - Many X desktop environments support a feature called the -@dfn{clipboard manager}. If you exit Emacs while it is the current -``owner'' of the clipboard data, and there is a clipboard manager -running, Emacs transfers the clipboard data to the clipboard manager -so that it is not lost. In some circumstances, this may cause a delay -when exiting Emacs; if you wish to prevent Emacs from transferring -data to the clipboard manager, change the variable -@code{x-select-enable-clipboard-manager} to @code{nil}. - -@vindex x-select-enable-primary -@findex clipboard-kill-region -@findex clipboard-kill-ring-save -@findex clipboard-yank - Prior to Emacs 24, the kill and yank commands used the primary -selection (@pxref{Primary Selection}), not the clipboard. If you -prefer this behavior, change @code{x-select-enable-clipboard} to -@code{nil}, @code{x-select-enable-primary} to @code{t}, and -@code{mouse-drag-copy-region} to @code{t}. In this case, you can use -the following commands to act explicitly on the clipboard: -@code{clipboard-kill-region} kills the region and saves it to the -clipboard; @code{clipboard-kill-ring-save} copies the region to the -kill ring and saves it to the clipboard; and @code{clipboard-yank} -yanks the contents of the clipboard at point. - -@node Primary Selection -@subsection Cut and Paste with Other Window Applications -@cindex X cutting and pasting -@cindex X selection -@cindex primary selection -@cindex selection, primary - - Under the X Window System, there exists a @dfn{primary selection} -containing the last stretch of text selected in an X application -(usually by dragging the mouse). Typically, this text can be inserted -into other X applications by @kbd{mouse-2} clicks. The primary -selection is separate from the clipboard. Its contents are more -``fragile''; they are overwritten each time you select text with the -mouse, whereas the clipboard is only overwritten by explicit ``cut'' -or ``copy'' commands. - - Under X, whenever the region is active (@pxref{Mark}), the text in -the region is saved in the primary selection. This applies regardless -of whether the region was made by dragging or clicking the mouse -(@pxref{Mouse Commands}), or by keyboard commands (e.g., by typing -@kbd{C-@key{SPC}} and moving point; @pxref{Setting Mark}). - -@vindex select-active-regions - If you change the variable @code{select-active-regions} to -@code{only}, Emacs saves only temporarily active regions to the -primary selection, i.e., those made with the mouse or with shift -selection (@pxref{Shift Selection}). If you change -@code{select-active-regions} to @code{nil}, Emacs avoids saving active -regions to the primary selection entirely. - - To insert the primary selection into an Emacs buffer, click -@kbd{mouse-2} (@code{mouse-yank-primary}) where you want to insert it. -@xref{Mouse Commands}. - -@cindex MS-Windows, and primary selection - MS-Windows provides no primary selection, but Emacs emulates it -within a single Emacs session by storing the selected text internally. -Therefore, all the features and commands related to the primary -selection work on Windows as they do on X, for cutting and pasting -within the same session, but not across Emacs sessions or with other -applications. - -@node Secondary Selection -@subsection Secondary Selection -@cindex secondary selection - - In addition to the primary selection, the X Window System provides a -second similar facility known as the @dfn{secondary selection}. -Nowadays, few X applications make use of the secondary selection, but -you can access it using the following Emacs commands: - -@table @kbd -@findex mouse-set-secondary -@kindex M-Drag-Mouse-1 -@item M-Drag-Mouse-1 -Set the secondary selection, with one end at the place where you press -down the button, and the other end at the place where you release it -(@code{mouse-set-secondary}). The selected text is highlighted, using -the @code{secondary-selection} face, as you drag. The window scrolls -automatically if you drag the mouse off the top or bottom of the -window, just like @code{mouse-set-region} (@pxref{Mouse Commands}). - -This command does not alter the kill ring. - -@findex mouse-start-secondary -@kindex M-Mouse-1 -@item M-Mouse-1 -Set one endpoint for the @dfn{secondary selection} -(@code{mouse-start-secondary}). - -@findex mouse-secondary-save-then-kill -@kindex M-Mouse-3 -@item M-Mouse-3 -Set the secondary selection, with one end at the position clicked and -the other at the position specified with @kbd{M-Mouse-1} -(@code{mouse-secondary-save-then-kill}). This also puts the selected -text in the kill ring. A second @kbd{M-Mouse-3} at the same place -kills the secondary selection just made. - -@findex mouse-yank-secondary -@kindex M-Mouse-2 -@item M-Mouse-2 -Insert the secondary selection where you click, placing point at the -end of the yanked text (@code{mouse-yank-secondary}). -@end table - -Double or triple clicking of @kbd{M-Mouse-1} operates on words and -lines, much like @kbd{Mouse-1}. - -If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2} yanks -at point. Then it does not matter precisely where you click, or even -which of the frame's windows you click on. @xref{Mouse Commands}. - -@node Accumulating Text -@section Accumulating Text -@findex append-to-buffer -@findex prepend-to-buffer -@findex copy-to-buffer -@findex append-to-file - -@cindex accumulating scattered text - Usually we copy or move text by killing it and yanking it, but there -are other convenient methods for copying one block of text in many -places, or for copying many scattered blocks of text into one place. -Here we describe the commands to accumulate scattered pieces of text -into a buffer or into a file. - -@table @kbd -@item M-x append-to-buffer -Append region to the contents of a specified buffer. -@item M-x prepend-to-buffer -Prepend region to the contents of a specified buffer. -@item M-x copy-to-buffer -Copy region into a specified buffer, deleting that buffer's old contents. -@item M-x insert-buffer -Insert the contents of a specified buffer into current buffer at point. -@item M-x append-to-file -Append region to the contents of a specified file, at the end. -@end table - - To accumulate text into a buffer, use @kbd{M-x append-to-buffer}. -This reads a buffer name, then inserts a copy of the region into the -buffer specified. If you specify a nonexistent buffer, -@code{append-to-buffer} creates the buffer. The text is inserted -wherever point is in that buffer. If you have been using the buffer for -editing, the copied text goes into the middle of the text of the buffer, -starting from wherever point happens to be at that moment. - - Point in that buffer is left at the end of the copied text, so -successive uses of @code{append-to-buffer} accumulate the text in the -specified buffer in the same order as they were copied. Strictly -speaking, @code{append-to-buffer} does not always append to the text -already in the buffer---it appends only if point in that buffer is at -the end. However, if @code{append-to-buffer} is the only command you -use to alter a buffer, then point is always at the end. - - @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer} -except that point in the other buffer is left before the copied text, so -successive prependings add text in reverse order. @kbd{M-x -copy-to-buffer} is similar, except that any existing text in the other -buffer is deleted, so the buffer is left containing just the text newly -copied into it. - - The command @kbd{M-x insert-buffer} can be used to retrieve the -accumulated text from another buffer. This prompts for the name of a -buffer, and inserts a copy of all the text in that buffer into the -current buffer at point, leaving point at the beginning of the -inserted text. It also adds the position of the end of the inserted -text to the mark ring, without activating the mark. @xref{Buffers}, -for background information on buffers. - - Instead of accumulating text in a buffer, you can append text -directly into a file with @kbd{M-x append-to-file}. This prompts for -a filename, and adds the text of the region to the end of the -specified file. The file is changed immediately on disk. - - You should use @code{append-to-file} only with files that are -@emph{not} being visited in Emacs. Using it on a file that you are -editing in Emacs would change the file behind Emacs's back, which -can lead to losing some of your editing. - - Another way to move text around is to store it in a register. -@xref{Registers}. - -@node Rectangles -@section Rectangles -@cindex rectangle -@cindex columns (and rectangles) -@cindex killing rectangular areas of text - - @dfn{Rectangle} commands operate on rectangular areas of the text: -all the characters between a certain pair of columns, in a certain -range of lines. Emacs has commands to kill rectangles, yank killed -rectangles, clear them out, fill them with blanks or text, or delete -them. Rectangle commands are useful with text in multicolumn formats, -and for changing text into or out of such formats. - -@cindex mark rectangle - To specify a rectangle for a command to work on, set the mark at one -corner and point at the opposite corner. The rectangle thus specified -is called the @dfn{region-rectangle}. If point and the mark are in -the same column, the region-rectangle is empty. If they are in the -same line, the region-rectangle is one line high. - - The region-rectangle is controlled in much the same way as the -region is controlled. But remember that a given combination of point -and mark values can be interpreted either as a region or as a -rectangle, depending on the command that uses them. - -@table @kbd -@item C-x r k -Kill the text of the region-rectangle, saving its contents as the -``last killed rectangle'' (@code{kill-rectangle}). -@item C-x r M-w -Save the text of the region-rectangle as the ``last killed rectangle'' -(@code{copy-rectangle-as-kill}). -@item C-x r d -Delete the text of the region-rectangle (@code{delete-rectangle}). -@item C-x r y -Yank the last killed rectangle with its upper left corner at point -(@code{yank-rectangle}). -@item C-x r o -Insert blank space to fill the space of the region-rectangle -(@code{open-rectangle}). This pushes the previous contents of the -region-rectangle to the right. -@item C-x r N -Insert line numbers along the left edge of the region-rectangle -(@code{rectangle-number-lines}). This pushes the previous contents of -the region-rectangle to the right. -@item C-x r c -Clear the region-rectangle by replacing all of its contents with spaces -(@code{clear-rectangle}). -@item M-x delete-whitespace-rectangle -Delete whitespace in each of the lines on the specified rectangle, -starting from the left edge column of the rectangle. -@item C-x r t @var{string} @key{RET} -Replace rectangle contents with @var{string} on each line -(@code{string-rectangle}). -@item M-x string-insert-rectangle @key{RET} @var{string} @key{RET} -Insert @var{string} on each line of the rectangle. -@item C-x @key{SPC} -Toggle Rectangle Mark mode (@code{rectangle-mark-mode}). -When this mode is active, the region-rectangle is highlighted and can -be shrunk/grown, and the standard kill and yank commands operate on it. -@end table - - The rectangle operations fall into two classes: commands to erase or -insert rectangles, and commands to make blank rectangles. - -@kindex C-x r k -@kindex C-x r d -@findex kill-rectangle -@findex delete-rectangle - There are two ways to erase the text in a rectangle: @kbd{C-x r d} -(@code{delete-rectangle}) to delete the text outright, or @kbd{C-x r -k} (@code{kill-rectangle}) to remove the text and save it as the -@dfn{last killed rectangle}. In both cases, erasing the -region-rectangle is like erasing the specified text on each line of -the rectangle; if there is any following text on the line, it moves -backwards to fill the gap. - - ``Killing'' a rectangle is not killing in the usual sense; the -rectangle is not stored in the kill ring, but in a special place that -only records the most recent rectangle killed. This is because -yanking a rectangle is so different from yanking linear text that -different yank commands have to be used. Yank-popping is not defined -for rectangles. - -@kindex C-x r M-w -@findex copy-rectangle-as-kill - @kbd{C-x r M-w} (@code{copy-rectangle-as-kill}) is the equivalent of -@kbd{M-w} for rectangles: it records the rectangle as the ``last -killed rectangle'', without deleting the text from the buffer. - -@kindex C-x r y -@findex yank-rectangle - To yank the last killed rectangle, type @kbd{C-x r y} -(@code{yank-rectangle}). The rectangle's first line is inserted at -point, the rectangle's second line is inserted at the same horizontal -position one line vertically below, and so on. The number of lines -affected is determined by the height of the saved rectangle. - - For example, you can convert two single-column lists into a -double-column list by killing one of the single-column lists as a -rectangle, and then yanking it beside the other list. - - You can also copy rectangles into and out of registers with @kbd{C-x r -r @var{r}} and @kbd{C-x r i @var{r}}. @xref{Rectangle Registers}. - -@kindex C-x r o -@findex open-rectangle -@kindex C-x r c -@findex clear-rectangle - There are two commands you can use for making blank rectangles: -@kbd{C-x r c} (@code{clear-rectangle}) blanks out existing text in the -region-rectangle, and @kbd{C-x r o} (@code{open-rectangle}) inserts a -blank rectangle. - -@findex delete-whitespace-rectangle - @kbd{M-x delete-whitespace-rectangle} deletes horizontal whitespace -starting from a particular column. This applies to each of the lines -in the rectangle, and the column is specified by the left edge of the -rectangle. The right edge of the rectangle does not make any -difference to this command. - -@kindex C-x r N -@findex rectangle - The command @kbd{C-x r N} (@code{rectangle-number-lines}) inserts -line numbers along the left edge of the region-rectangle. Normally, -the numbering begins from 1 (for the first line of the rectangle). -With a prefix argument, the command prompts for a number to begin -from, and for a format string with which to print the numbers -(@pxref{Formatting Strings,,, elisp, The Emacs Lisp Reference -Manual}). - -@kindex C-x r t -@findex string-rectangle - The command @kbd{C-x r t} (@code{string-rectangle}) replaces the -contents of a region-rectangle with a string on each line. The -string's width need not be the same as the width of the rectangle. If -the string's width is less, the text after the rectangle shifts left; -if the string is wider than the rectangle, the text after the -rectangle shifts right. - -@findex string-insert-rectangle - The command @kbd{M-x string-insert-rectangle} is similar to -@code{string-rectangle}, but inserts the string on each line, -shifting the original text to the right. - -@findex rectangle-mark-mode - The command @kbd{C-x @key{SPC}} (@code{rectangle-mark-mode}) toggles -whether the region-rectangle or the standard region is highlighted -(first activating the region if necessary). When this mode is enabled, -commands that resize the region (@kbd{C-f}, @kbd{C-n} etc.) do -so in a rectangular fashion, and killing and yanking operate on the -rectangle. @xref{Killing}. The mode persists only as long as the -region is active. - -@node CUA Bindings -@section CUA Bindings -@findex cua-mode -@vindex cua-mode -@cindex CUA key bindings -@vindex cua-enable-cua-keys - The command @kbd{M-x cua-mode} sets up key bindings that are -compatible with the Common User Access (CUA) system used in many other -applications. - - When CUA mode is enabled, the keys @kbd{C-x}, @kbd{C-c}, @kbd{C-v}, -and @kbd{C-z} invoke commands that cut (kill), copy, paste (yank), and -undo respectively. The @kbd{C-x} and @kbd{C-c} keys perform cut and -copy only if the region is active. Otherwise, they still act as -prefix keys, so that standard Emacs commands like @kbd{C-x C-c} still -work. Note that this means the variable @code{mark-even-if-inactive} -has no effect for @kbd{C-x} and @kbd{C-c} (@pxref{Using Region}). - - To enter an Emacs command like @kbd{C-x C-f} while the mark is -active, use one of the following methods: either hold @kbd{Shift} -together with the prefix key, e.g., @kbd{S-C-x C-f}, or quickly type -the prefix key twice, e.g., @kbd{C-x C-x C-f}. - - To disable the overriding of standard Emacs binding by CUA mode, -while retaining the other features of CUA mode described below, set -the variable @code{cua-enable-cua-keys} to @code{nil}. - - CUA mode by default activates Delete-Selection mode (@pxref{Mouse Commands}) -so that typed text replaces the active region. To use CUA without this -behavior, set the variable @code{cua-delete-selection} to @code{nil}. - -@cindex rectangle highlighting - CUA mode provides enhanced rectangle support with visible -rectangle highlighting. Use @kbd{C-@key{RET}} to start a rectangle, -extend it using the movement commands, and cut or copy it using -@kbd{C-x} or @kbd{C-c}. @key{RET} moves the cursor to the next -(clockwise) corner of the rectangle, so you can easily expand it in -any direction. Normal text you type is inserted to the left or right -of each line in the rectangle (on the same side as the cursor). - - You can use this rectangle support without activating CUA by calling the -@code{cua-rectangle-mark-mode} command. But see also the standard -@code{rectangle-mark-mode}. @xref{Rectangles}. - - With CUA you can easily copy text and rectangles into and out of -registers by providing a one-digit numeric prefix to the kill, copy, -and yank commands, e.g., @kbd{C-1 C-c} copies the region into register -@code{1}, and @kbd{C-2 C-v} yanks the contents of register @code{2}. - -@cindex global mark - CUA mode also has a global mark feature which allows easy moving and -copying of text between buffers. Use @kbd{C-S-@key{SPC}} to toggle the -global mark on and off. When the global mark is on, all text that you -kill or copy is automatically inserted at the global mark, and text -you type is inserted at the global mark rather than at the current -position. - - For example, to copy words from various buffers into a word list in -a given buffer, set the global mark in the target buffer, then -navigate to each of the words you want in the list, mark it (e.g., with -@kbd{S-M-f}), copy it to the list with @kbd{C-c} or @kbd{M-w}, and -insert a newline after the word in the target list by pressing -@key{RET}. diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi deleted file mode 100644 index 881c7ead933..00000000000 --- a/doc/emacs/kmacro.texi +++ /dev/null @@ -1,574 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Keyboard Macros -@chapter Keyboard Macros -@cindex defining keyboard macros -@cindex keyboard macro - - In this chapter we describe how to record a sequence of editing -commands so you can repeat it conveniently later. - - A @dfn{keyboard macro} is a command defined by an Emacs user to stand for -another sequence of keys. For example, if you discover that you are -about to type @kbd{C-n M-d C-d} forty times, you can speed your work by -defining a keyboard macro to do @kbd{C-n M-d C-d}, and then executing -it 39 more times. - - You define a keyboard macro by executing and recording the commands -which are its definition. Put differently, as you define a keyboard -macro, the definition is being executed for the first time. This way, -you can see the effects of your commands, so that you don't have to -figure them out in your head. When you close the definition, the -keyboard macro is defined and also has been, in effect, executed once. -You can then do the whole thing over again by invoking the macro. - - Keyboard macros differ from ordinary Emacs commands in that they are -written in the Emacs command language rather than in Lisp. This makes it -easier for the novice to write them, and makes them more convenient as -temporary hacks. However, the Emacs command language is not powerful -enough as a programming language to be useful for writing anything -intelligent or general. For such things, Lisp must be used. - -@menu -* Basic Keyboard Macro:: Defining and running keyboard macros. -* Keyboard Macro Ring:: Where previous keyboard macros are saved. -* Keyboard Macro Counter:: Inserting incrementing numbers in macros. -* Keyboard Macro Query:: Making keyboard macros do different things each - time. -* Save Keyboard Macro:: Giving keyboard macros names; saving them in - files. -* Edit Keyboard Macro:: Editing keyboard macros. -* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard - macro. -@end menu - -@node Basic Keyboard Macro -@section Basic Use - -@table @kbd -@item @key{F3} -Start defining a keyboard macro -(@code{kmacro-start-macro-or-insert-counter}). -@item @key{F4} -If a keyboard macro is being defined, end the definition; otherwise, -execute the most recent keyboard macro -(@code{kmacro-end-or-call-macro}). -@item C-u @key{F3} -Re-execute last keyboard macro, then append keys to its definition. -@item C-u C-u @key{F3} -Append keys to the last keyboard macro without re-executing it. -@item C-x C-k r -Run the last keyboard macro on each line that begins in the region -(@code{apply-macro-to-region-lines}). -@end table - -@kindex F3 -@kindex F4 -@findex kmacro-start-macro-or-insert-counter -@findex kmacro-end-or-call-macro -@findex kmacro-end-and-call-macro - To start defining a keyboard macro, type @key{F3}. From then on, -your keys continue to be executed, but also become part of the -definition of the macro. @samp{Def} appears in the mode line to -remind you of what is going on. When you are finished, type @key{F4} -(@code{kmacro-end-or-call-macro}) to terminate the definition. For -example, - -@example -@key{F3} M-f foo @key{F4} -@end example - -@noindent -defines a macro to move forward a word and then insert @samp{foo}. -Note that @key{F3} and @key{F4} do not become part of the macro. - - After defining the macro, you can call it with @key{F4}. For the -above example, this has the same effect as typing @kbd{M-f foo} again. -(Note the two roles of the @key{F4} command: it ends the macro if you -are in the process of defining one, or calls the last macro -otherwise.) You can also supply @key{F4} with a numeric prefix -argument @samp{n}, which means to invoke the macro @samp{n} times. An -argument of zero repeats the macro indefinitely, until it gets an -error or you type @kbd{C-g} (or, on MS-DOS, @kbd{C-@key{BREAK}}). - - The above example demonstrates a handy trick that you can employ -with keyboard macros: if you wish to repeat an operation at regularly -spaced places in the text, include a motion command as part of the -macro. In this case, repeating the macro inserts the string -@samp{foo} after each successive word. - - After terminating the definition of a keyboard macro, you can append -more keystrokes to its definition by typing @kbd{C-u @key{F3}}. This -is equivalent to plain @key{F3} followed by retyping the whole -definition so far. As a consequence, it re-executes the macro as -previously defined. If you change the variable -@code{kmacro-execute-before-append} to @code{nil}, the existing macro -will not be re-executed before appending to it (the default is -@code{t}). You can also add to the end of the definition of the last -keyboard macro without re-executing it by typing @kbd{C-u C-u -@key{F3}}. - - When a command reads an argument with the minibuffer, your -minibuffer input becomes part of the macro along with the command. So -when you replay the macro, the command gets the same argument as when -you entered the macro. For example, - -@example -@key{F3} C-a C-k C-x b foo @key{RET} C-y C-x b @key{RET} @key{F4} -@end example - -@noindent -defines a macro that kills the current line, yanks it into the buffer -@samp{foo}, then returns to the original buffer. - - Most keyboard commands work as usual in a keyboard macro definition, -with some exceptions. Typing @kbd{C-g} (@code{keyboard-quit}) quits -the keyboard macro definition. Typing @kbd{C-M-c} -(@code{exit-recursive-edit}) can be unreliable: it works as you'd -expect if exiting a recursive edit that started within the macro, but -if it exits a recursive edit that started before you invoked the -keyboard macro, it also necessarily exits the keyboard macro too. -Mouse events are also unreliable, even though you can use them in a -keyboard macro: when the macro replays the mouse event, it uses the -original mouse position of that event, the position that the mouse had -while you were defining the macro. The effect of this may be hard to -predict. - -@findex apply-macro-to-region-lines -@kindex C-x C-k r - The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines}) -repeats the last defined keyboard macro on each line that begins in -the region. It does this line by line, by moving point to the -beginning of the line and then executing the macro. - -@kindex C-x ( -@kindex C-x ) -@kindex C-x e -@findex kmacro-start-macro -@findex kmacro-end-macro - In addition to the @key{F3} and @key{F4} commands described above, -Emacs also supports an older set of key bindings for defining and -executing keyboard macros. To begin a macro definition, type @kbd{C-x -(} (@code{kmacro-start-macro}); as with @key{F3}, a prefix argument -appends this definition to the last keyboard macro. To end a macro -definition, type @kbd{C-x )} (@code{kmacro-end-macro}). To execute -the most recent macro, type @kbd{C-x e} -(@code{kmacro-end-and-call-macro}). If you enter @kbd{C-x e} while -defining a macro, the macro is terminated and executed immediately. -Immediately after typing @kbd{C-x e}, you can type @key{e} repeatedly -to immediately repeat the macro one or more times. You can also give -@kbd{C-x e} a repeat argument, just like @key{F4}. - - @kbd{C-x )} can be given a repeat count as an argument. This means -to repeat the macro right after defining it. The macro definition -itself counts as the first repetition, since it is executed as you -define it, so @kbd{C-u 4 C-x )} executes the macro immediately 3 -additional times. - -@node Keyboard Macro Ring -@section The Keyboard Macro Ring - - All defined keyboard macros are recorded in the @dfn{keyboard macro -ring}. There is only one keyboard macro ring, shared by all buffers. - -@table @kbd -@item C-x C-k C-k -Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}). -@item C-x C-k C-n -Rotate the keyboard macro ring to the next macro (defined earlier) -(@code{kmacro-cycle-ring-next}). -@item C-x C-k C-p -Rotate the keyboard macro ring to the previous macro (defined later) -(@code{kmacro-cycle-ring-previous}). -@end table - - All commands which operate on the keyboard macro ring use the -same @kbd{C-x C-k} prefix. Most of these commands can be executed and -repeated immediately after each other without repeating the @kbd{C-x -C-k} prefix. For example, - -@example -C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d -@end example - -@noindent -will rotate the keyboard macro ring to the ``second previous'' macro, -execute the resulting head macro three times, rotate back to the -original head macro, execute that once, rotate to the ``previous'' -macro, execute that, and finally delete it from the macro ring. - -@findex kmacro-end-or-call-macro-repeat -@kindex C-x C-k C-k - The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat}) -executes the keyboard macro at the head of the macro ring. You can -repeat the macro immediately by typing another @kbd{C-k}, or you can -rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}. - - When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves -like @key{F4} except that, immediately afterward, you can use most key -bindings of this section without the @kbd{C-x C-k} prefix. For -instance, another @kbd{C-k} will re-execute the macro. - -@findex kmacro-cycle-ring-next -@kindex C-x C-k C-n -@findex kmacro-cycle-ring-previous -@kindex C-x C-k C-p - The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and -@kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotate the -macro ring, bringing the next or previous keyboard macro to the head -of the macro ring. The definition of the new head macro is displayed -in the echo area. You can continue to rotate the macro ring -immediately by repeating just @kbd{C-n} and @kbd{C-p} until the -desired macro is at the head of the ring. To execute the new macro -ring head immediately, just type @kbd{C-k}. - - Note that Emacs treats the head of the macro ring as the ``last -defined keyboard macro''. For instance, @key{F4} will execute that -macro, and @kbd{C-x C-k n} will give it a name. - -@vindex kmacro-ring-max - The maximum number of macros stored in the keyboard macro ring is -determined by the customizable variable @code{kmacro-ring-max}. - -@node Keyboard Macro Counter -@section The Keyboard Macro Counter - - Each keyboard macro has an associated counter, which is initialized -to 0 when you start defining the macro. This counter allows you to -insert a number into the buffer that depends on the number of times -the macro has been called. The counter is incremented each time its -value is inserted into the buffer. - -@table @kbd -@item @key{F3} -In a keyboard macro definition, insert the keyboard macro counter -value in the buffer (@code{kmacro-start-macro-or-insert-counter}). -@item C-x C-k C-i -Insert the keyboard macro counter value in the buffer -(@code{kmacro-insert-counter}). -@item C-x C-k C-c -Set the keyboard macro counter (@code{kmacro-set-counter}). -@item C-x C-k C-a -Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}). -@item C-x C-k C-f -Specify the format for inserting the keyboard macro counter -(@code{kmacro-set-format}). -@end table - -@findex kmacro-insert-counter -@kindex C-x C-k C-i - When you are defining a keyboard macro, the command @key{F3} -(@code{kmacro-start-macro-or-insert-counter}) inserts the current -value of the keyboard macro's counter into the buffer, and increments -the counter by 1. (If you are not defining a macro, @key{F3} begins a -macro definition instead. @xref{Basic Keyboard Macro}.) You can use -a numeric prefix argument to specify a different increment. If you -just specify a @kbd{C-u} prefix, that is the same as an increment of -zero: it inserts the current counter value without changing it. - - As an example, let us show how the keyboard macro counter can be -used to build a numbered list. Consider the following key sequence: - -@example -@key{F3} C-a @key{F3} . @key{SPC} @key{F4} -@end example - -@noindent -As part of this keyboard macro definition, the string @samp{0. } was -inserted into the beginning of the current line. If you now move -somewhere else in the buffer and type @key{F4} to invoke the macro, -the string @samp{1. } is inserted at the beginning of that line. -Subsequent invocations insert @samp{2. }, @samp{3. }, and so forth. - - The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) does -the same thing as @key{F3}, but it can be used outside a keyboard -macro definition. When no keyboard macro is being defined or -executed, it inserts and increments the counter of the macro at the -head of the keyboard macro ring. - -@findex kmacro-set-counter -@kindex C-x C-k C-c - The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) sets the -current macro counter to the value of the numeric argument. If you use -it inside the macro, it operates on each repetition of the macro. If -you specify just @kbd{C-u} as the prefix, while executing the macro, -that resets the counter to the value it had at the beginning of the -current repetition of the macro (undoing any increments so far in this -repetition). - -@findex kmacro-add-counter -@kindex C-x C-k C-a - The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the -prefix argument to the current macro counter. With just @kbd{C-u} as -argument, it resets the counter to the last value inserted by any -keyboard macro. (Normally, when you use this, the last insertion -will be in the same macro and it will be the same counter.) - -@findex kmacro-set-format -@kindex C-x C-k C-f - The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts for -the format to use when inserting the macro counter. The default -format is @samp{%d}, which means to insert the number in decimal -without any padding. You can exit with empty minibuffer to reset the -format to this default. You can specify any format string that the -@code{format} function accepts and that makes sense with a single -integer extra argument (@pxref{Formatting Strings,,, elisp, The Emacs -Lisp Reference Manual}). Do not put the format string inside double -quotes when you insert it in the minibuffer. - - If you use this command while no keyboard macro is being defined or -executed, the new format affects all subsequent macro definitions. -Existing macros continue to use the format in effect when they were -defined. If you set the format while defining a keyboard macro, this -affects the macro being defined from that point on, but it does not -affect subsequent macros. Execution of the macro will, at each step, -use the format in effect at that step during its definition. Changes -to the macro format during execution of a macro, like the -corresponding changes during its definition, have no effect on -subsequent macros. - - The format set by @kbd{C-x C-k C-f} does not affect insertion of -numbers stored in registers. - - If you use a register as a counter, incrementing it on each -repetition of the macro, that accomplishes the same thing as a -keyboard macro counter. @xref{Number Registers}. For most purposes, -it is simpler to use a keyboard macro counter. - -@node Keyboard Macro Query -@section Executing Macros with Variations - - In a keyboard macro, you can create an effect similar to that of -@code{query-replace}, in that the macro asks you each time around -whether to make a change. - -@table @kbd -@item C-x q -When this point is reached during macro execution, ask for confirmation -(@code{kbd-macro-query}). -@end table - -@kindex C-x q -@findex kbd-macro-query - While defining the macro, type @kbd{C-x q} at the point where you -want the query to occur. During macro definition, the @kbd{C-x q} -does nothing, but when you run the macro later, @kbd{C-x q} asks you -interactively whether to continue. - - The valid responses when @kbd{C-x q} asks are: - -@table @asis -@item @key{SPC} (or @kbd{y}) -Continue executing the keyboard macro. - -@item @key{DEL} (or @kbd{n}) -Skip the remainder of this repetition of the macro, and start right -away with the next repetition. - -@item @key{RET} (or @kbd{q}) -Skip the remainder of this repetition and cancel further repetitions. - -@item @kbd{C-r} -Enter a recursive editing level, in which you can perform editing -which is not part of the macro. When you exit the recursive edit -using @kbd{C-M-c}, you are asked again how to continue with the -keyboard macro. If you type a @key{SPC} at this time, the rest of the -macro definition is executed. It is up to you to leave point and the -text in a state such that the rest of the macro will do what you want. -@end table - - @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, -performs a completely different function. It enters a recursive edit -reading input from the keyboard, both when you type it during the -definition of the macro, and when it is executed from the macro. During -definition, the editing you do inside the recursive edit does not become -part of the macro. During macro execution, the recursive edit gives you -a chance to do some particularized editing on each repetition. -@xref{Recursive Edit}. - -@node Save Keyboard Macro -@section Naming and Saving Keyboard Macros - -@table @kbd -@item C-x C-k n -Give a command name (for the duration of the Emacs session) to the most -recently defined keyboard macro (@code{kmacro-name-last-macro}). -@item C-x C-k b -Bind the most recently defined keyboard macro to a key sequence (for -the duration of the session) (@code{kmacro-bind-to-key}). -@item M-x insert-kbd-macro -Insert in the buffer a keyboard macro's definition, as Lisp code. -@end table - -@cindex saving keyboard macros -@findex kmacro-name-last-macro -@kindex C-x C-k n - If you wish to save a keyboard macro for later use, you can give it -a name using @kbd{C-x C-k n} (@code{kmacro-name-last-macro}). -This reads a name as an argument using the minibuffer and defines that -name to execute the last keyboard macro, in its current form. (If you -later add to the definition of this macro, that does not alter the -name's definition as a macro.) The macro name is a Lisp symbol, and -defining it in this way makes it a valid command name for calling with -@kbd{M-x} or for binding a key to with @code{global-set-key} -(@pxref{Keymaps}). If you specify a name that has a prior definition -other than a keyboard macro, an error message is shown and nothing is -changed. - -@cindex binding keyboard macros -@findex kmacro-bind-to-key -@kindex C-x C-k b - You can also bind the last keyboard macro (in its current form) to a -key, using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the -key sequence you want to bind. You can bind to any key sequence in -the global keymap, but since most key sequences already have other -bindings, you should select the key sequence carefully. If you try to -bind to a key sequence with an existing binding (in any keymap), this -command asks you for confirmation before replacing the existing binding. - - To avoid problems caused by overriding existing bindings, the key -sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A} -through @kbd{C-x C-k Z} are reserved for your own keyboard macro -bindings. In fact, to bind to one of these key sequences, you only -need to type the digit or letter rather than the whole key sequences. -For example, - -@example -C-x C-k b 4 -@end example - -@noindent -will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}. - -@findex insert-kbd-macro - Once a macro has a command name, you can save its definition in a file. -Then it can be used in another editing session. First, visit the file -you want to save the definition in. Then use this command: - -@example -M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} -@end example - -@noindent -This inserts some Lisp code that, when executed later, will define the -same macro with the same definition it has now. (You need not -understand Lisp code to do this, because @code{insert-kbd-macro} writes -the Lisp code for you.) Then save the file. You can load the file -later with @code{load-file} (@pxref{Lisp Libraries}). If the file you -save in is your init file @file{~/.emacs} (@pxref{Init File}) then the -macro will be defined each time you run Emacs. - - If you give @code{insert-kbd-macro} a numeric argument, it makes -additional Lisp code to record the keys (if any) that you have bound -to @var{macroname}, so that the macro will be reassigned the same keys -when you load the file. - -@node Edit Keyboard Macro -@section Editing a Keyboard Macro - -@table @kbd -@item C-x C-k C-e -Edit the last defined keyboard macro (@code{kmacro-edit-macro}). -@item C-x C-k e @var{name} @key{RET} -Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}). -@item C-x C-k l -Edit the last 300 keystrokes as a keyboard macro -(@code{kmacro-edit-lossage}). -@end table - -@findex kmacro-edit-macro -@kindex C-x C-k C-e -@kindex C-x C-k RET - You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or -@kbd{C-x C-k @key{RET}} (@code{kmacro-edit-macro}). This formats the -macro definition in a buffer and enters a specialized major mode for -editing it. Type @kbd{C-h m} once in that buffer to display details -of how to edit the macro. When you are finished editing, type -@kbd{C-c C-c}. - -@findex edit-kbd-macro -@kindex C-x C-k e - You can edit a named keyboard macro or a macro bound to a key by typing -@kbd{C-x C-k e} (@code{edit-kbd-macro}). Follow that with the -keyboard input that you would use to invoke the macro---@kbd{C-x e} or -@kbd{M-x @var{name}} or some other key sequence. - -@findex kmacro-edit-lossage -@kindex C-x C-k l - You can edit the last 300 keystrokes as a macro by typing -@kbd{C-x C-k l} (@code{kmacro-edit-lossage}). - -@node Keyboard Macro Step-Edit -@section Stepwise Editing a Keyboard Macro - -@findex kmacro-step-edit-macro -@kindex C-x C-k SPC - You can interactively replay and edit the last keyboard -macro, one command at a time, by typing @kbd{C-x C-k @key{SPC}} -(@code{kmacro-step-edit-macro}). Unless you quit the macro using -@kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the -macro ring. - - This macro editing feature shows the last macro in the minibuffer -together with the first (or next) command to be executed, and prompts -you for an action. You can enter @kbd{?} to get a summary of your -options. These actions are available: - -@itemize @bullet{} -@item -@key{SPC} and @kbd{y} execute the current command, and advance to the -next command in the keyboard macro. -@item -@kbd{n}, @kbd{d}, and @key{DEL} skip and delete the current command. -@item -@kbd{f} skips the current command in this execution of the keyboard -macro, but doesn't delete it from the macro. -@item -@key{TAB} executes the current command, as well as all similar -commands immediately following the current command; for example, @key{TAB} -may be used to insert a sequence of characters (corresponding to a -sequence of @code{self-insert-command} commands). -@item -@kbd{c} continues execution (without further editing) until the end of -the keyboard macro. If execution terminates normally, the edited -macro replaces the original keyboard macro. -@item -@kbd{C-k} skips and deletes the rest of the keyboard macro, -terminates step-editing, and replaces the original keyboard macro -with the edited macro. -@item -@kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro; -discarding any changes made to the keyboard macro. -@item -@kbd{i @var{key}@dots{} C-j} reads and executes a series of key sequences (not -including the final @kbd{C-j}), and inserts them before the current -command in the keyboard macro, without advancing over the current -command. -@item -@kbd{I @var{key}@dots{}} reads one key sequence, executes it, and inserts it -before the current command in the keyboard macro, without advancing -over the current command. -@item -@kbd{r @var{key}@dots{} C-j} reads and executes a series of key sequences (not -including the final @kbd{C-j}), and replaces the current command in -the keyboard macro with them, advancing over the inserted key -sequences. -@item -@kbd{R @var{key}@dots{}} reads one key sequence, executes it, and replaces the -current command in the keyboard macro with that key sequence, -advancing over the inserted key sequence. -@item -@kbd{a @var{key}@dots{} C-j} executes the current command, then reads and -executes a series of key sequences (not including the final -@kbd{C-j}), and inserts them after the current command in the keyboard -macro; it then advances over the current command and the inserted key -sequences. -@item -@kbd{A @var{key}@dots{} C-j} executes the rest of the commands in the keyboard -macro, then reads and executes a series of key sequences (not -including the final @kbd{C-j}), and appends them at the end of the -keyboard macro; it then terminates the step-editing and replaces the -original keyboard macro with the edited macro. -@end itemize diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi deleted file mode 100644 index b4385cb61bc..00000000000 --- a/doc/emacs/m-x.texi +++ /dev/null @@ -1,71 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node M-x -@chapter Running Commands by Name - - Every Emacs command has a name that you can use to run it. For -convenience, many commands also have key bindings. You can run those -commands by typing the keys, or run them by name. Most Emacs commands -have no key bindings, so the only way to run them is by name. -(@xref{Key Bindings}, for how to set up key bindings.) - - By convention, a command name consists of one or more words, -separated by hyphens; for example, @code{auto-fill-mode} or -@code{manual-entry}. Command names mostly use complete English words -to make them easier to remember. - -@kindex M-x - To run a command by name, start with @kbd{M-x}, type the command -name, then terminate it with @key{RET}. @kbd{M-x} uses the minibuffer -to read the command name. The string @samp{M-x} appears at the -beginning of the minibuffer as a @dfn{prompt} to remind you to enter a -command name to be run. @key{RET} exits the minibuffer and runs the -command. @xref{Minibuffer}, for more information on the minibuffer. - - You can use completion to enter the command name. For example, -to invoke the command @code{forward-char}, you can type - -@example -M-x forward-char @key{RET} -@end example - -@noindent -or - -@example -M-x forw @key{TAB} c @key{RET} -@end example - -@noindent -Note that @code{forward-char} is the same command that you invoke with -the key @kbd{C-f}. The existence of a key binding does not stop you -from running the command by name. - - To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead -of entering the command name. This takes you back to command level. - - To pass a numeric argument to the command you are invoking with -@kbd{M-x}, specify the numeric argument before @kbd{M-x}. The -argument value appears in the prompt while the command name is being -read, and finally @kbd{M-x} passes the argument to that command. - -@vindex suggest-key-bindings - When the command you run with @kbd{M-x} has a key binding, Emacs -mentions this in the echo area after running the command. For -example, if you type @kbd{M-x forward-word}, the message says that you -can run the same command by typing @kbd{M-f}. You can turn off these -messages by setting the variable @code{suggest-key-bindings} to -@code{nil}. - - In this manual, when we speak of running a command by name, we often -omit the @key{RET} that terminates the name. Thus we might say -@kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode -@key{RET}}. We mention the @key{RET} only for emphasis, such as when -the command is followed by arguments. - -@findex execute-extended-command - @kbd{M-x} works by running the command -@code{execute-extended-command}, which is responsible for reading the -name of another command and invoking it. diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi deleted file mode 100644 index 2177ad4e210..00000000000 --- a/doc/emacs/macos.texi +++ /dev/null @@ -1,218 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2000-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Mac OS / GNUstep -@appendix Emacs and Mac OS / GNUstep -@cindex Mac OS X -@cindex Macintosh -@cindex GNUstep - - This section describes the peculiarities of using Emacs built with -the GNUstep libraries on GNU/Linux or other operating systems, or on -Mac OS X with native window system support. On Mac OS X, Emacs can be -built either without window system support, with X11, or with the -Cocoa interface; this section only applies to the Cocoa build. This -does not support versions of Mac OS X earlier than 10.4. - - For various historical and technical reasons, Emacs uses the term -@samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for -instance, most of the commands and variables described in this section -begin with @samp{ns-}, which is short for @samp{Nextstep}. NeXTstep -was an application interface released by NeXT Inc during the 1980s, of -which Cocoa is a direct descendant. Apart from Cocoa, there is -another NeXTstep-style system: GNUstep, which is free software. As of -this writing, Emacs GNUstep support is alpha status (@pxref{GNUstep -Support}), but we hope to improve it in the future. - -@menu -* Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or Mac OS. -* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS. -* Mac / GNUstep Events:: How window system events are handled. -* GNUstep Support:: Details on status of GNUstep support. -@end menu - -@node Mac / GNUstep Basics -@section Basic Emacs usage under Mac OS and GNUstep - - By default, the @key{alt} and @key{option} keys are the same as -@key{Meta}. The Mac @key{Cmd} key is the same as @key{Super}, and -Emacs provides a set of key bindings using this modifier key that mimic -other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}). You -can change these bindings in the usual way (@pxref{Key Bindings}). - -@vindex ns-alternate-modifier -@vindex ns-right-alternate-modifier - The variable @code{ns-right-alternate-modifier} controls the -behavior of the right @key{alt} and @key{option} keys. These keys -behave like the left-hand keys if the value is @code{left} (the -default). A value of @code{control}, @code{meta}, @code{alt}, -@code{super}, or @code{hyper} makes them behave like the corresponding -modifier keys; a value to @code{left} means be the same key as -@code{ns-alternate-modifier}; a value of @code{none} tells Emacs to -ignore them. - - @kbd{S-Mouse-1} adjusts the region to the click position, -just like @kbd{Mouse-3} (@code{mouse-save-then-kill}); it does not pop -up a menu for changing the default face, as @kbd{S-Mouse-1} normally -does (@pxref{Text Scale}). This change makes Emacs behave more like -other Mac / GNUstep applications. - - When you open or save files using the menus, or using the -@kbd{Cmd-o} and @kbd{Cmd-S} bindings, Emacs uses graphical file -dialogs to read file names. However, if you use the regular Emacs key -sequences, such as @kbd{C-x C-f}, Emacs uses the minibuffer to read -file names. - - On GNUstep, in an X-windows environment you need to use @kbd{Cmd-c} -instead of one of the @kbd{C-w} or @kbd{M-w} commands to transfer text -to the X primary selection; otherwise, Emacs will use the -``clipboard'' selection. Likewise, @kbd{Cmd-y} (instead of @kbd{C-y}) -yanks from the X primary selection instead of the kill-ring or -clipboard. - - -@subsection Grabbing environment variables - -@c How is this any different to launching from a window manager menu -@c in GNU/Linux? These are sometimes not login shells either. -Many programs which may run under Emacs, like latex or man, depend on the -settings of environment variables. If Emacs is launched from the shell, it -will automatically inherit these environment variables and its subprocesses -will inherit them from it. But if Emacs is launched from the Finder it -is not a descendant of any shell, so its environment variables haven't been -set, which often causes the subprocesses it launches to behave differently than -they would when launched from the shell. - -For the PATH and MANPATH variables, a system-wide method -of setting PATH is recommended on Mac OS X 10.5 and later, using the -@file{/etc/paths} files and the @file{/etc/paths.d} directory. - -@node Mac / GNUstep Customization -@section Mac / GNUstep Customization - -There are a few customization options that are specific to the -Nextstep port. For example, they affect things such as the modifier -keys and the fullscreen behavior. To see all such options, use -@kbd{M-x customize-group @key{RET} ns @key{RET}}. - -@subsection Font and Color Panels - -The standard Mac / GNUstep font and color panels are accessible via -Lisp commands. The Font Panel may be accessed with @kbd{M-x -ns-popup-font-panel}. It will set the default font in the frame most -recently used or clicked on. - -@c To make the setting permanent, use @samp{Save Options} in the -@c Options menu, or run @code{menu-bar-options-save}. - -You can bring up a color panel with @kbd{M-x ns-popup-color-panel} and -drag the color you want over the Emacs face you want to change. Normal -dragging will alter the foreground color. Shift dragging will alter the -background color. To discard the settings, create a new frame and -close the altered one. - -@c To make the changes permanent select the "Save Options" -@c item in the "Options" menu, or run @code{menu-bar-options-save}. - -Useful in this context is the listing of all faces obtained by -@kbd{M-x list-faces-display}. - -@cindex Core Text, on Mac OS X -In Mac OS X 10.5 and later, Emacs uses a Core Text based font backend -by default. If you prefer the older font style, enter the following -at the command-line before starting Emacs: - -@example -% defaults write org.gnu.Emacs FontBackend ns -@end example - - -@node Mac / GNUstep Events -@section Windowing System Events under Mac OS / GNUstep - - Nextstep applications receive a number of special events which have -no X equivalent. These are sent as specially defined ``keys'', which -do not correspond to any sequence of keystrokes. Under Emacs, these -``key'' events can be bound to functions just like ordinary -keystrokes. Here is a list of these events. - -@table @key -@item ns-open-file -@vindex ns-pop-up-frames -This event occurs when another Nextstep application requests that -Emacs open a file. A typical reason for this would be a user -double-clicking a file in the Finder application. By default, Emacs -responds to this event by opening a new frame and visiting the file in -that frame (@code{ns-find-file}). As an exception, if the selected -buffer is the @file{*scratch*} buffer, Emacs visits the file in the -selected frame. - -You can change how Emacs responds to a @code{ns-open-file} event by -changing the variable @code{ns-pop-up-frames}. Its default value, -@samp{fresh}, is what we have just described. A value of @code{t} -means to always visit the file in a new frame. A value of @code{nil} -means to always visit the file in an existing frame. - -@item ns-open-temp-file -This event occurs when another application requests that Emacs open a -temporary file. By default, this is handled by just generating a -@code{ns-open-file} event, the results of which are described above. - -@item ns-open-file-line -Some applications, such as ProjectBuilder and gdb, request not only a -particular file, but also a particular line or sequence of lines in -the file. Emacs handles this by visiting that file and highlighting -the requested line (@code{ns-open-file-select-line}). - -@item ns-drag-file -This event occurs when a user drags files from another application -into an Emacs frame. The default behavior is to insert the contents -of all the dragged files into the current buffer -(@code{ns-insert-files}). The list of dragged files is stored in the -variable @code{ns-input-file}. - -@item ns-drag-color -This event occurs when a user drags a color from the color well (or -some other source) into an Emacs frame. The default behavior is to -alter the foreground color of the area the color was dragged onto -(@code{ns-set-foreground-at-mouse}). If this event is issued with a -@key{Shift} modifier, Emacs changes the background color instead -(@code{ns-set-background-at-mouse}). The name of the dragged color is -stored in the variable @code{ns-input-color}. - -@item ns-change-font -This event occurs when the user selects a font in a Nextstep font -panel (which can be opened with @kbd{Cmd-t}). The default behavior is -to adjust the font of the selected frame -(@code{ns-respond-to-changefont}). The name and size of the selected -font are stored in the variables @code{ns-input-font} and -@code{ns-input-fontsize}, respectively. - -@item ns-power-off -This event occurs when the user logs out and Emacs is still running, or when -`Quit Emacs' is chosen from the application menu. -The default behavior is to save all file-visiting buffers. -@end table - - Emacs also allows users to make use of Nextstep services, via a set -of commands whose names begin with @samp{ns-service-} and end with the -name of the service. Type @kbd{M-x ns-service-@key{TAB}} to -see a list of these commands. These functions either operate on -marked text (replacing it with the result) or take a string argument -and return the result as a string. You can also use the Lisp function -@code{ns-perform-service} to pass arbitrary strings to arbitrary -services and receive the results back. Note that you may need to -restart Emacs to access newly-available services. - -@node GNUstep Support -@section GNUstep Support - -Emacs can be built and run under GNUstep, but there are still -issues to be addressed. Interested developers should contact -@ifnothtml -@email{emacs-devel@@gnu.org}. -@end ifnothtml -@ifhtml -@url{http://lists.gnu.org/mailman/listinfo/emacs-devel, the -emacs-devel mailing list}. -@end ifhtml diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi deleted file mode 100644 index e066c491ac5..00000000000 --- a/doc/emacs/maintaining.texi +++ /dev/null @@ -1,2395 +0,0 @@ -@c This is part of the Emacs manual., Abbrevs, This is part of the Emacs manual., Top -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Maintaining -@chapter Maintaining Large Programs - - This chapter describes Emacs features for maintaining large -programs. If you are maintaining a large Lisp program, then in -addition to the features described here, you may find -the @file{ERT} (``Emacs Lisp Regression Testing'') library useful -(@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}). - -@menu -* Version Control:: Using version control systems. -* Change Log:: Maintaining a change history for your program. -* Tags:: Go directly to any function in your program in one - command. Tags remembers which file it is in. -* EDE:: An integrated development environment for Emacs. -@ifnottex -* Emerge:: A convenient way of merging two versions of a program. -@end ifnottex -@end menu - -@node Version Control -@section Version Control -@cindex version control - - A @dfn{version control system} is a program that can record multiple -versions of a source file, storing information such as the creation -time of each version, who made it, and a description of what was -changed. - - The Emacs version control interface is called @dfn{VC}@. VC commands -work with several different version control systems; currently, it -supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, -SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS, -Arch, RCS, and Bazaar. - - VC is enabled automatically whenever you visit a file governed by a -version control system. To disable VC entirely, set the customizable -variable @code{vc-handled-backends} to @code{nil} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex - -@menu -* Introduction to VC:: How version control works in general. -* VC Mode Line:: How the mode line shows version control status. -* Basic VC Editing:: How to edit a file under version control. -* Log Buffer:: Features available in log entry buffers. -* Registering:: Putting a file under version control. -* Old Revisions:: Examining and comparing old versions. -* VC Change Log:: Viewing the VC Change Log. -* VC Undo:: Canceling changes before or after committing. -* VC Ignore:: Ignore files under version control system. -* VC Directory Mode:: Listing files managed by version control. -* Branches:: Multiple lines of development. -@ifnottex -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end ifnottex -@end menu - -@node Introduction to VC -@subsection Introduction to Version Control - - VC allows you to use a version control system from within Emacs, -integrating the version control operations smoothly with editing. It -provides a uniform interface for common operations in many version -control operations. - - Some uncommon or intricate version control operations, such as -altering repository settings, are not supported in VC@. You should -perform such tasks outside Emacs, e.g., via the command line. - - This section provides a general overview of version control, and -describes the version control systems that VC supports. You can skip -this section if you are already familiar with the version control system -you want to use. - -@menu -* Why Version Control?:: Understanding the problems it addresses. -* Version Control Systems:: Supported version control back-end systems. -* VCS Concepts:: Words and concepts related to version control. -* VCS Merging:: How file conflicts are handled. -* VCS Changesets:: How changes are grouped. -* VCS Repositories:: Where version control repositories are stored. -* Types of Log File:: The VCS log in contrast to the ChangeLog. -@end menu - -@node Why Version Control? -@subsubsection Understanding the problems it addresses - - Version control systems provide you with three important -capabilities: - -@itemize @bullet -@item -@dfn{Reversibility}: the ability to back up to a previous state if you -discover that some modification you did was a mistake or a bad idea. - -@item -@dfn{Concurrency}: the ability to have many people modifying the same -collection of files knowing that conflicting modifications can be -detected and resolved. - -@item -@dfn{History}: the ability to attach historical data to your data, -such as explanatory comments about the intention behind each change to -it. Even for a programmer working solo, change histories are an -important aid to memory; for a multi-person project, they are a -vitally important form of communication among developers. -@end itemize - -@node Version Control Systems -@subsubsection Supported Version Control Systems - -@cindex back end (version control) - VC currently works with many different version control systems, -which it refers to as @dfn{back ends}: - -@itemize @bullet - -@cindex SCCS -@item -SCCS was the first version control system ever built, and was long ago -superseded by more advanced ones. VC compensates for certain features -missing in SCCS (e.g., tag names for releases) by implementing them -itself. Other VC features, such as multiple branches, are simply -unavailable. Since SCCS is non-free, we recommend avoiding it. - -@cindex CSSC -@item -CSSC is a free replacement for SCCS@. You should use CSSC only if, for -some reason, you cannot use a more recent and better-designed version -control system. - -@cindex RCS -@item -RCS is the free version control system around which VC was initially -built. It is relatively primitive: it cannot be used over the -network, and works at the level of individual files. Almost -everything you can do with RCS can be done through VC. - -@cindex CVS -@item -CVS is the free version control system that was, until recently (circa -2008), used by the majority of free software projects. Nowadays, it -is slowly being superseded by newer systems. CVS allows concurrent -multi-user development either locally or over the network. Unlike -newer systems, it lacks support for atomic commits and file -moving/renaming. VC supports all basic editing operations under CVS. - -@cindex SVN -@cindex Subversion -@item -Subversion (svn) is a free version control system designed to be -similar to CVS but without its problems (e.g., it supports atomic -commits of filesets, and versioning of directories, symbolic links, -meta-data, renames, copies, and deletes). - -@cindex GNU Arch -@cindex Arch -@item -GNU Arch is one of the earliest @dfn{decentralized} version control -systems (the other being Monotone). @xref{VCS Concepts}, for a -description of decentralized version control systems. It is no longer -under active development, and has been deprecated in favor of Bazaar. - -@cindex git -@item -Git is a decentralized version control system originally invented by -Linus Torvalds to support development of Linux (his kernel). VC -supports many common Git operations, but others, such as repository -syncing, must be done from the command line. - -@cindex hg -@cindex Mercurial -@item -Mercurial (hg) is a decentralized version control system broadly -resembling Git. VC supports most Mercurial commands, with the -exception of repository sync operations. - -@cindex bzr -@cindex Bazaar -@item -Bazaar (bzr) is a decentralized version control system that supports -both repository-based and decentralized versioning. VC supports most -basic editing operations under Bazaar. -@end itemize - -@node VCS Concepts -@subsubsection Concepts of Version Control - -@cindex repository -@cindex registered file - When a file is under version control, we say that it is -@dfn{registered} in the version control system. The system has a -@dfn{repository} which stores both the file's present state and its -change history---enough to reconstruct the current version or any -earlier version. The repository also contains other information, such -as @dfn{log entries} that describe the changes made to each file. - -@cindex work file -@cindex checking out files - The copy of a version-controlled file that you actually edit is -called the @dfn{work file}. You can change each work file as you -would an ordinary file. After you are done with a set of changes, you -may @dfn{commit} (or @dfn{check in}) the changes; this records the -changes in the repository, along with a descriptive log entry. - -@cindex working tree - A directory tree of work files is called a @dfn{working tree}. - -@cindex revision -@cindex revision ID - Each commit creates a new @dfn{revision} in the repository. The -version control system keeps track of all past revisions and the -changes that were made in each revision. Each revision is named by a -@dfn{revision ID}, whose format depends on the version control system; -in the simplest case, it is just an integer. - - To go beyond these basic concepts, you will need to understand three -aspects in which version control systems differ. As explained in the -next three sections, they can be lock-based or merge-based; file-based -or changeset-based; and centralized or decentralized. VC handles all -these modes of operation, but it cannot hide the differences. - -@node VCS Merging -@subsubsection Merge-based vs lock-based Version Control - - A version control system typically has some mechanism to coordinate -between users who want to change the same file. There are two ways to -do this: merging and locking. - -@cindex merging-based version - In a version control system that uses merging, each user may modify -a work file at any time. The system lets you @dfn{merge} your work -file, which may contain changes that have not been committed, with the -latest changes that others have committed. - -@cindex locking-based version - Older version control systems use a @dfn{locking} scheme instead. -Here, work files are normally read-only. To edit a file, you ask the -version control system to make it writable for you by @dfn{locking} -it; only one user can lock a given file at any given time. This -procedure is analogous to, but different from, the locking that Emacs -uses to detect simultaneous editing of ordinary files -(@pxref{Interlocking}). When you commit your changes, that unlocks -the file, and the work file becomes read-only again. Other users may -then lock the file to make their own changes. - - Both locking and merging systems can have problems when multiple -users try to modify the same file at the same time. Locking systems -have @dfn{lock conflicts}; a user may try to check a file out and be -unable to because it is locked. In merging systems, @dfn{merge -conflicts} happen when you commit a change to a file that conflicts -with a change committed by someone else after your checkout. Both -kinds of conflict have to be resolved by human judgment and -communication. Experience has shown that merging is superior to -locking, both in convenience to developers and in minimizing the -number and severity of conflicts that actually occur. - - SCCS always uses locking. RCS is lock-based by default but can be -told to operate in a merging style. CVS and Subversion are -merge-based by default but can be told to operate in a locking mode. -Decentralized version control systems, such as GNU Arch, Git, and -Mercurial, are exclusively merging-based. - - VC mode supports both locking and merging version control. The -terms ``commit'' and ``update'' are used in newer version control -systems; older lock-based systems use the terms ``check in'' and -``check out''. VC hides the differences between them as much as -possible. - -@node VCS Changesets -@subsubsection Changeset-based vs File-based Version Control - -@cindex file-based version control - On SCCS, RCS, CVS, and other early version control systems, version -control operations are @dfn{file-based}: each file has its own comment -and revision history separate from that of all other files. Newer -systems, beginning with Subversion, are @dfn{changeset-based}: a -commit may include changes to several files, and the entire set of -changes is handled as a unit. Any comment associated with the change -does not belong to a single file, but to the changeset itself. - -@cindex changeset-based version control - Changeset-based version control is more flexible and powerful than -file-based version control; usually, when a change to multiple files -has to be reversed, it's good to be able to easily identify and remove -all of it. - -@node VCS Repositories -@subsubsection Decentralized vs Centralized Repositories - -@cindex centralized version control -@cindex decentralized version control -@cindex distributed version control - Early version control systems were designed around a -@dfn{centralized} model in which each project has only one repository -used by all developers. SCCS, RCS, CVS, and Subversion share this -kind of model. One of its drawbacks is that the repository is a choke -point for reliability and efficiency. - - GNU Arch pioneered the concept of @dfn{distributed} or -@dfn{decentralized} version control, later implemented in Git, -Mercurial, and Bazaar. A project may have several different -repositories, and these systems support a sort of super-merge between -repositories that tries to reconcile their change histories. In -effect, there is one repository for each developer, and repository -merges take the place of commit operations. - - VC helps you manage the traffic between your personal workfiles and -a repository. Whether the repository is a single master, or one of a -network of peer repositories, is not something VC has to care about. - -@node Types of Log File -@subsubsection Types of Log File -@cindex types of log file -@cindex log File, types of -@cindex version control log - - Projects that use a version control system can have two types of log -for changes. One is the log maintained by the version control system: -each time you commit a change, you fill out a @dfn{log entry} for the -change (@pxref{Log Buffer}). This is called the @dfn{version control -log}. - - The other kind of log is the file @file{ChangeLog} (@pxref{Change -Log}). It provides a chronological record of all changes to a large -portion of a program---typically one directory and its subdirectories. -A small program would use one @file{ChangeLog} file; a large program -may have a @file{ChangeLog} file in each major directory. -@xref{Change Log}. Programmers have used change logs since long -before version control systems. - - Changeset-based version systems typically maintain a changeset-based -modification log for the entire system, which makes change log files -somewhat redundant. One advantage that they retain is that it is -sometimes useful to be able to view the transaction history of a -single directory separately from those of other directories. Another -advantage is that commit logs can't be fixed in many version control -systems. - - A project maintained with version control can use just the version -control log, or it can use both kinds of logs. It can handle some -files one way and some files the other way. Each project has its -policy, which you should follow. - - When the policy is to use both, you typically want to write an entry -for each change just once, then put it into both logs. You can write -the entry in @file{ChangeLog}, then copy it to the log buffer with -@kbd{C-c C-a} when committing the change (@pxref{Log Buffer}). Or you -can write the entry in the log buffer while committing the change, and -later use the @kbd{C-x v a} command to copy it to @file{ChangeLog} -@iftex -(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Change Logs and VC}). -@end ifnottex - -@node VC Mode Line -@subsection Version Control and the Mode Line -@cindex VC mode line indicator - - When you visit a file that is under version control, Emacs indicates -this on the mode line. For example, @samp{Bzr-1223} says that Bazaar -is used for that file, and the current revision ID is 1223. - -@cindex version control status - The character between the back-end name and the revision ID -indicates the @dfn{version control status} of the work file. In a -merge-based version control system, a @samp{-} character indicates -that the work file is unmodified, and @samp{:} indicates that it has -been modified. @samp{!} indicates that the file contains conflicts as -result of a recent merge operation (@pxref{Merging}), or that the file -was removed from the version control. Finally, @samp{?} means that -the file is under version control, but is missing from the working -tree. - - In a lock-based system, @samp{-} indicates an unlocked file, and -@samp{:} a locked file; if the file is locked by another user (for -instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. -@samp{@@} means that the file was locally added, but not yet committed -to the master repository. - - On a graphical display, you can move the mouse over this mode line -indicator to pop up a ``tool-tip'', which displays a more verbose -description of the version control status. Pressing @kbd{Mouse-1} -over the indicator pops up a menu of VC commands, identical to -@samp{Tools / Version Control} on the menu bar. - -@vindex auto-revert-check-vc-info - When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is -under version control, it updates the version control information in -the mode line. However, Auto Revert mode may not properly update this -information if the version control status changes without changes to -the work file, from outside the current Emacs session. If you set -@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates -the version control status information every -@code{auto-revert-interval} seconds, even if the work file itself is -unchanged. The resulting CPU usage depends on the version control -system, but is usually not excessive. - -@node Basic VC Editing -@subsection Basic Editing under Version Control - -@cindex filesets, VC -@cindex VC filesets - Most VC commands operate on @dfn{VC filesets}. A VC fileset is a -collection of one or more files that a VC operation acts on. When you -type VC commands in a buffer visiting a version-controlled file, the -VC fileset is simply that one file. When you type them in a VC -Directory buffer, and some files in it are marked, the VC fileset -consists of the marked files (@pxref{VC Directory Mode}). - - On modern changeset-based version control systems (@pxref{VCS -Changesets}), VC commands handle multi-file VC filesets as a group. -For example, committing a multi-file VC fileset generates a single -revision, containing the changes to all those files. On older -file-based version control systems like CVS, each file in a multi-file -VC fileset is handled individually; for example, a commit generates -one revision for each changed file. - -@table @kbd -@item C-x v v -Perform the next appropriate version control operation on the current -VC fileset. -@end table - -@findex vc-next-action -@kindex C-x v v - The principal VC command is a multi-purpose command, @kbd{C-x v v} -(@code{vc-next-action}), which performs the ``most appropriate'' -action on the current VC fileset: either registering it with a version -control system, or committing it, or unlocking it, or merging changes -into it. The precise actions are described in detail in the following -subsections. You can use @kbd{C-x v v} either in a file-visiting -buffer or in a VC Directory buffer. - - Note that VC filesets are distinct from the ``named filesets'' used -for viewing and visiting files in functional groups -(@pxref{Filesets}). Unlike named filesets, VC filesets are not named -and don't persist across sessions. - -@menu -* VC With A Merging VCS:: Without locking: default mode for CVS. -* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. -* Advanced C-x v v:: Advanced features available with a prefix argument. -@end menu - -@node VC With A Merging VCS -@subsubsection Basic Version Control with Merging - - On a merging-based version control system (i.e., most modern ones; -@pxref{VCS Merging}), @kbd{C-x v v} does the following: - -@itemize @bullet -@item -If there is more than one file in the VC fileset and the files have -inconsistent version control statuses, signal an error. (Note, -however, that a fileset is allowed to include both ``newly-added'' -files and ``modified'' files; @pxref{Registering}.) - -@item -If none of the files in the VC fileset are registered with a version -control system, register the VC fileset, i.e., place it under version -control. @xref{Registering}. If Emacs cannot find a system to -register under, it prompts for a repository type, creates a new -repository, and registers the VC fileset with it. - -@item -If every work file in the VC fileset is unchanged, do nothing. - -@item -If every work file in the VC fileset has been modified, commit the -changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the -desired log entry for the new revision, followed by @kbd{C-c C-c} to -commit. @xref{Log Buffer}. - -If committing to a shared repository, the commit may fail if the -repository that has been changed since your last update. In that -case, you must perform an update before trying again. On a -decentralized version control system, use @kbd{C-x v +} (@pxref{VC -Pull}) or @kbd{C-x v m} (@pxref{Merging}). On a centralized version -control system, type @kbd{C-x v v} again to merge in the repository -changes. - -@item -Finally, if you are using a centralized version control system, check -if each work file in the VC fileset is up-to-date. If any file has -been changed in the repository, offer to update it. -@end itemize - - These rules also apply when you use RCS in its ``non-locking'' mode, -except that changes are not automatically merged from the repository. -Nothing informs you if another user has committed changes in the same -file since you began editing it; when you commit your revision, his -changes are removed (however, they remain in the repository and are -thus not irrevocably lost). Therefore, you must verify that the -current revision is unchanged before committing your changes. In -addition, locking is possible with RCS even in this mode: @kbd{C-x v -v} with an unmodified file locks the file, just as it does with RCS in -its normal locking mode (@pxref{VC With A Locking VCS}). - -@node VC With A Locking VCS -@subsubsection Basic Version Control with Locking - - On a locking-based version control system (such as SCCS, and RCS in -its default mode), @kbd{C-x v v} does the following: - -@itemize @bullet -@item -If there is more than one file in the VC fileset and the files have -inconsistent version control statuses, signal an error. - -@item -If each file in the VC fileset is not registered with a version -control system, register the VC fileset. @xref{Registering}. If -Emacs cannot find a system to register under, it prompts for a -repository type, creates a new repository, and registers the VC -fileset with it. - -@item -If each file is registered and unlocked, lock it and make it writable, -so that you can begin to edit it. - -@item -If each file is locked by you and contains changes, commit the -changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the -desired log entry for the new revision, followed by @kbd{C-c C-c} to -commit (@pxref{Log Buffer}). - -@item -If each file is locked by you, but you have not changed it, release -the lock and make the file read-only again. - -@item -If each file is locked by another user, ask whether you want to -``steal the lock''. If you say yes, the file becomes locked by you, -and a warning message is sent to the user who had formerly locked the -file. -@end itemize - - These rules also apply when you use CVS in locking mode, except -that CVS does not support stealing locks. - -@node Advanced C-x v v -@subsubsection Advanced Control in @kbd{C-x v v} - -@cindex revision ID in version control - When you give a prefix argument to @code{vc-next-action} (@kbd{C-u -C-x v v}), it still performs the next logical version control -operation, but accepts additional arguments to specify precisely how -to do the operation. - -@itemize @bullet -@item -@cindex specific version control system -You can specify the name of a version control system. This is useful -if the fileset can be managed by more than one version control system, -and Emacs fails to detect the correct one. - -@item -Otherwise, if using CVS or RCS, you can specify a revision ID. - -If the fileset is modified (or locked), this makes Emacs commit with -that revision ID@. You can create a new branch by supplying an -appropriate revision ID (@pxref{Branches}). - -If the fileset is unmodified (and unlocked), this checks the specified -revision into the working tree. You can also specify a revision on -another branch by giving its revision or branch ID (@pxref{Switching -Branches}). An empty argument (i.e., @kbd{C-u C-x v v @key{RET}}) -checks out the latest (``head'') revision on the current branch. - -This signals an error on a decentralized version control system. -Those systems do not let you specify your own revision IDs, nor do -they use the concept of ``checking out'' individual files. -@end itemize - -@node Log Buffer -@subsection Features of the Log Entry Buffer - -@cindex C-c C-c @r{(Log Edit mode)} -@findex log-edit-done - When you tell VC to commit a change, it pops up a buffer named -@file{*vc-log*}. In this buffer, you should write a @dfn{log entry} -describing the changes you have made (@pxref{Why Version Control?}). -After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit -the buffer and commit the change, together with your log entry. - -@cindex Log Edit mode -@cindex mode, Log Edit -@vindex vc-log-mode-hook -@c FIXME: Mention log-edit-mode-hook here? --xfq - The major mode for the @file{*vc-log*} buffer is Log Edit mode, a -variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode, -Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook} -(@pxref{Hooks}). - - In the @file{*vc-log*} buffer, you can write one or more @dfn{header -lines}, specifying additional information to be supplied to the -version control system. Each header line must occupy a single line at -the top of the buffer; the first line that is not a header line is -treated as the start of the log entry. For example, the following -header line states that the present change was not written by you, but -by another developer: - -@smallexample -Author: J. R. Hacker -@end smallexample - -@noindent -Apart from the @samp{Author} header, Emacs recognizes the headers -@samp{Date} (a manually-specified commit time) and @samp{Fixes} (a -reference to a bug fixed by the change). Not all version control -systems recognize all headers: Bazaar recognizes all three headers, -while Git, Mercurial, and Monotone recognize only @samp{Author} and -@samp{Date}. If you specify a header for a system that does not -support it, the header is treated as part of the log entry. - -@kindex C-c C-f @r{(Log Edit mode)} -@findex log-edit-show-files -@kindex C-c C-d @r{(Log Edit mode)} -@findex log-edit-show-diff - While in the @file{*vc-log*} buffer, the ``current VC fileset'' is -considered to be the fileset that will be committed if you type -@w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset, -type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff -of changes between the VC fileset and the version from which you -started editing (@pxref{Old Revisions}), type @kbd{C-c C-d} -(@code{log-edit-show-diff}). - -@kindex C-c C-a @r{(Log Edit mode)} -@findex log-edit-insert-changelog - If the VC fileset includes one or more @file{ChangeLog} files -(@pxref{Change Log}), type @kbd{C-c C-a} -(@code{log-edit-insert-changelog}) to pull the relevant entries into -the @file{*vc-log*} buffer. If the topmost item in each -@file{ChangeLog} was made under your user name on the current date, -this command searches that item for entries matching the file(s) to be -committed, and inserts them. -@ifnottex -If you are using CVS or RCS, see @ref{Change Logs and VC}, for the -opposite way of working---generating ChangeLog entries from the Log -Edit buffer. -@end ifnottex - - To abort a commit, just @emph{don't} type @kbd{C-c C-c} in that -buffer. You can switch buffers and do other editing. As long as you -don't try to make another commit, the entry you were editing remains -in the @file{*vc-log*} buffer, and you can go back to that buffer at -any time to complete the commit. - -@kindex M-n @r{(Log Edit mode)} -@kindex M-p @r{(Log Edit mode)} -@kindex M-s @r{(Log Edit mode)} -@kindex M-r @r{(Log Edit mode)} - You can also browse the history of previous log entries to duplicate -a commit comment. This can be useful when you want to make several -commits with similar comments. The commands @kbd{M-n}, @kbd{M-p}, -@kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer -history commands (@pxref{Minibuffer History}), except that they are -used outside the minibuffer. - -@node Registering -@subsection Registering a File for Version Control - -@table @kbd -@item C-x v i -Register the visited file for version control. -@end table - -@kindex C-x v i -@findex vc-register - The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each -file in the current VC fileset, placing it under version control. -This is essentially equivalent to the action of @kbd{C-x v v} on an -unregistered VC fileset (@pxref{Basic VC Editing}), except that if the -VC fileset is already registered, @kbd{C-x v i} signals an error -whereas @kbd{C-x v v} performs some other action. - - To register a file, Emacs must choose a version control system. For -a multi-file VC fileset, the VC Directory buffer specifies the system -to use (@pxref{VC Directory Mode}). For a single-file VC fileset, if -the file's directory already contains files registered in a version -control system, or if the directory is part of a directory tree -controlled by a version control system, Emacs chooses that system. In -the event that more than one version control system is applicable, -Emacs uses the one that appears first in the variable -@iftex -@code{vc-handled-backends}. -@end iftex -@ifnottex -@code{vc-handled-backends} (@pxref{Customizing VC}). -@end ifnottex -If Emacs cannot find a version control system to register the file -under, it prompts for a repository type, creates a new repository, and -registers the file into that repository. - - On most version control systems, registering a file with @kbd{C-x v -i} or @kbd{C-x v v} adds it to the ``working tree'' but not to the -repository. Such files are labeled as @samp{added} in the VC -Directory buffer, and show a revision ID of @samp{@@@@} in the mode -line. To make the registration take effect in the repository, you -must perform a commit (@pxref{Basic VC Editing}). Note that a single -commit can include both file additions and edits to existing files. - - On a locking-based version control system (@pxref{VCS Merging}), -registering a file leaves it unlocked and read-only. Type @kbd{C-x v -v} to start editing it. - -@node Old Revisions -@subsection Examining And Comparing Old Revisions - -@table @kbd -@item C-x v = -Compare the work files in the current VC fileset with the versions you -started from (@code{vc-diff}). With a prefix argument, prompt for two -revisions of the current VC fileset and compare them. You can also -call this command from a Dired buffer (@pxref{Dired}). - -@ifnottex -@item M-x vc-ediff -Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The -Ediff Manual}. -@end ifnottex - -@item C-x v D -Compare the entire working tree to the revision you started from -(@code{vc-root-diff}). With a prefix argument, prompt for two -revisions and compare their trees. - -@item C-x v ~ -Prompt for a revision of the current file, and visit it in a separate -buffer (@code{vc-revision-other-window}). - -@item C-x v g -Display an annotated version of the current file: for each line, show -the latest revision in which it was modified (@code{vc-annotate}). -@end table - -@findex vc-diff -@kindex C-x v = - @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares -each work file in the current VC fileset to the version(s) from which -you started editing. The diff is displayed in another window, in a -Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}. The -usual Diff mode commands are available in this buffer. In particular, -the @kbd{g} (@code{revert-buffer}) command performs the file -comparison again, generating a new diff. - -@kindex C-u C-x v = - To compare two arbitrary revisions of the current VC fileset, call -@code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This -prompts for two revision IDs (@pxref{VCS Concepts}), and displays a -diff between those versions of the fileset. This will not work -reliably for multi-file VC filesets, if the version control system is -file-based rather than changeset-based (e.g., CVS), since then -revision IDs for different files would not be related in any -meaningful way. - - Instead of the revision ID, some version control systems let you -specify revisions in other formats. For instance, under Bazaar you -can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =} -(and related commands) to specify the first revision committed after -yesterday. See the documentation of the version control system for -details. - - If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer -(@pxref{Dired}), the file listed on the current line is treated as the -current VC fileset. - -@ifnottex -@findex vc-ediff - @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an -Ediff session. @xref{Top,, Ediff, ediff, The Ediff Manual}. -@end ifnottex - -@findex vc-root-diff -@kindex C-x v D - @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but -it displays the changes in the entire current working tree (i.e., the -working tree containing the current VC fileset). If you invoke this -command from a Dired buffer, it applies to the working tree containing -the directory. - -@vindex vc-diff-switches - You can customize the @command{diff} options that @kbd{C-x v =} and -@kbd{C-x v D} use for generating diffs. The options used are taken -from the first non-@code{nil} value amongst the variables -@code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and -@code{diff-switches} (@pxref{Comparing Files}), in that order. Here, -@var{backend} stands for the relevant version control system, -e.g., @code{bzr} for Bazaar. Since @code{nil} means to check the -next variable in the sequence, either of the first two may use the -value @code{t} to mean no switches at all. Most of the -@code{vc-@var{backend}-diff-switches} variables default to @code{nil}, -but some default to @code{t}; these are for version control systems -whose @code{diff} implementations do not accept common diff options, -such as Subversion. - -@findex vc-revision-other-window -@kindex C-x v ~ - To directly examine an older version of a file, visit the work file -and type @kbd{C-x v ~ @var{revision} @key{RET}} -(@code{vc-revision-other-window}). This retrieves the file version -corresponding to @var{revision}, saves it to -@file{@var{filename}.~@var{revision}~}, and visits it in a separate -window. - -@findex vc-annotate -@kindex C-x v g - Many version control systems allow you to view files @dfn{annotated} -with per-line revision information, by typing @kbd{C-x v g} -(@code{vc-annotate}). This creates a new buffer (the ``annotate -buffer'') displaying the file's text, with each line colored to show -how old it is. Red text is new, blue is old, and intermediate colors -indicate intermediate ages. By default, the color is scaled over the -full range of ages, such that the oldest changes are blue, and the -newest changes are red. - - When you give a prefix argument to this command, Emacs reads two -arguments using the minibuffer: the revision to display and annotate -(instead of the current file contents), and the time span in days the -color range should cover. - - From the annotate buffer, these and other color scaling options are -available from the @samp{VC-Annotate} menu. In this buffer, you can -also use the following keys to browse the annotations of past revisions, -view diffs, or view log entries: - -@table @kbd -@item p -Annotate the previous revision, i.e., the revision before the one -currently annotated. A numeric prefix argument is a repeat count, so -@kbd{C-u 10 p} would take you back 10 revisions. - -@item n -Annotate the next revision, i.e., the revision after the one -currently annotated. A numeric prefix argument is a repeat count. - -@item j -Annotate the revision indicated by the current line. - -@item a -Annotate the revision before the one indicated by the current line. -This is useful to see the state the file was in before the change on -the current line was made. - -@item f -Show in a buffer the file revision indicated by the current line. - -@item d -Display the diff between the current line's revision and the previous -revision. This is useful to see what the current line's revision -actually changed in the file. - -@item D -Display the diff between the current line's revision and the previous -revision for all files in the changeset (for VC systems that support -changesets). This is useful to see what the current line's revision -actually changed in the tree. - -@item l -Show the log of the current line's revision. This is useful to see -the author's description of the changes in the revision on the current -line. - -@item w -Annotate the working revision--the one you are editing. If you used -@kbd{p} and @kbd{n} to browse to other revisions, use this key to -return to your working revision. - -@item v -Toggle the annotation visibility. This is useful for looking just at -the file contents without distraction from the annotations. -@end table - -@node VC Change Log -@subsection VC Change Log - -@table @kbd -@item C-x v l -Display the change history for the current fileset -(@code{vc-print-log}). - -@item C-x v L -Display the change history for the current repository -(@code{vc-print-root-log}). - -@item C-x v I -Display the changes that a pull operation will retrieve -(@code{vc-log-incoming}). - -@item C-x v O -Display the changes that will be sent by the next push operation -(@code{vc-log-outgoing}). -@end table - -@kindex C-x v l -@findex vc-print-log - @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named -@file{*vc-change-log*}, showing the history of changes made to the -current file, including who made the changes, the dates, and the log -entry for each change (these are the same log entries you would enter -via the @file{*vc-log*} buffer; @pxref{Log Buffer}). Point is -centered at the revision of the file currently being visited. With a -prefix argument, the command prompts for the revision to center on, -and the maximum number of revisions to display. - - If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC -Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the -file listed on the current line. - -@findex vc-print-root-log -@findex log-view-toggle-entry-display - @kbd{C-x v L} (@code{vc-print-root-log}) displays a -@file{*vc-change-log*} buffer showing the history of the entire -version-controlled directory tree (RCS, SCCS, and CVS do not support -this feature). With a prefix argument, the command prompts for the -maximum number of revisions to display. - - The @kbd{C-x v L} history is shown in a compact form, usually -showing only the first line of each log entry. However, you can type -@key{RET} (@code{log-view-toggle-entry-display}) in the -@file{*vc-change-log*} buffer to reveal the entire log entry for the -revision at point. A second @key{RET} hides it again. - - On a decentralized version control system, the @kbd{C-x v I} -(@code{vc-log-incoming}) command displays a log buffer showing the -changes that will be applied, the next time you run the version -control system's ``pull'' command to get new revisions from another -repository (@pxref{VC Pull}). This other repository is the default -one from which changes are pulled, as defined by the version control -system; with a prefix argument, @code{vc-log-incoming} prompts for a -specific repository. Similarly, @kbd{C-x v O} -(@code{vc-log-outgoing}) shows the changes that will be sent to -another repository, the next time you run the ``push'' command; with a -prefix argument, it prompts for a specific destination repository. - - In the @file{*vc-change-log*} buffer, you can use the following keys -to move between the logs of revisions and of files, and to examine and -compare past revisions (@pxref{Old Revisions}): - -@table @kbd -@item p -Move to the previous revision entry. (Revision entries in the log -buffer are usually in reverse-chronological order, so the previous -revision-item usually corresponds to a newer revision.) A numeric -prefix argument is a repeat count. - -@item n -Move to the next revision entry. A numeric prefix argument is a -repeat count. - -@item P -Move to the log of the previous file, if showing logs for a multi-file -VC fileset. Otherwise, just move to the beginning of the log. A -numeric prefix argument is a repeat count. - -@item N -Move to the log of the next file, if showing logs for a multi-file VC -fileset. A numeric prefix argument is a repeat count. - -@item a -Annotate the revision on the current line (@pxref{Old Revisions}). - -@item e -Modify the change comment displayed at point. Note that not all VC -systems support modifying change comments. - -@item f -Visit the revision indicated at the current line. - -@item d -Display a diff between the revision at point and the next earlier -revision, for the specific file. - -@item D -Display the changeset diff between the revision at point and the next -earlier revision. This shows the changes to all files made in that -revision. - -@item @key{RET} -In a compact-style log buffer (e.g., the one created by @kbd{C-x v -L}), toggle between showing and hiding the full log entry for the -revision at point. -@end table - -@vindex vc-log-show-limit -Because fetching many log entries can be slow, the -@file{*vc-change-log*} buffer displays no more than 2000 revisions by -default. The variable @code{vc-log-show-limit} specifies this limit; -if you set the value to zero, that removes the limit. You can also -increase the number of revisions shown in an existing -@file{*vc-change-log*} buffer by clicking on the @samp{Show 2X -entries} or @samp{Show unlimited entries} buttons at the end of the -buffer. However, RCS, SCCS, and CVS do not support this feature. - -@node VC Undo -@subsection Undoing Version Control Actions - -@table @kbd -@item C-x v u -Revert the work file(s) in the current VC fileset to the last revision -(@code{vc-revert}). -@end table - -@c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific. - -@kindex C-x v u -@findex vc-revert -@vindex vc-revert-show-diff - If you want to discard all the changes you have made to the current -VC fileset, type @kbd{C-x v u} (@code{vc-revert-buffer}). This shows -you a diff between the work file(s) and the revision from which you -started editing, and asks for confirmation for discarding the changes. -If you agree, the fileset is reverted. If you don't want @kbd{C-x v -u} to show a diff, set the variable @code{vc-revert-show-diff} to -@code{nil} (you can still view the diff directly with @kbd{C-x v =}; -@pxref{Old Revisions}). Note that @kbd{C-x v u} cannot be reversed -with the usual undo commands (@pxref{Undo}), so use it with care. - - On locking-based version control systems, @kbd{C-x v u} leaves files -unlocked; you must lock again to resume editing. You can also use -@kbd{C-x v u} to unlock a file if you lock it and then decide not to -change it. - -@node VC Ignore -@subsection Ignore Version Control Files - -@table @kbd -@item C-x v G -Ignore a file under current version control system. (@code{vc-ignore}). -@end table - -@kindex C-x v G -@findex vc-ignore - Many source trees contain some files that do not need to be -versioned, such as editor backups, object or bytecode files, and built -programs. You can simply not add them, but then they'll always crop -up as unknown files. You can also tell the version control system to -ignore these files by adding them to the ignore file at the top of the -tree. @kbd{C-x v G} (@code{vc-ignore}) can help you do this. When -called with a prefix argument, you can remove a file from the ignored -file list. - -@node VC Directory Mode -@subsection VC Directory Mode - -@cindex VC Directory buffer - The @dfn{VC Directory buffer} is a specialized buffer for viewing -the version control statuses of the files in a directory tree, and -performing version control operations on those files. In particular, -it is used to specify multi-file VC filesets for commands like -@w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}). - -@kindex C-x v d -@findex vc-dir - To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}). -This reads a directory name using the minibuffer, and switches to a VC -Directory buffer for that directory. By default, the buffer is named -@file{*vc-dir*}. Its contents are described -@iftex -below. -@end iftex -@ifnottex -in @ref{VC Directory Buffer}. -@end ifnottex - - The @code{vc-dir} command automatically detects the version control -system to be used in the specified directory. In the event that more -than one system is being used in the directory, you should invoke the -command with a prefix argument, @kbd{C-u C-x v d}; this prompts for -the version control system which the VC Directory buffer should use. - -@ifnottex -@cindex PCL-CVS -@pindex cvs -@cindex CVS directory mode - In addition to the VC Directory buffer, Emacs has a similar facility -called PCL-CVS which is specialized for CVS@. @xref{Top, , About -PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}. -@end ifnottex - -@menu -* Buffer: VC Directory Buffer. What the buffer looks like and means. -* Commands: VC Directory Commands. Commands to use in a VC directory buffer. -@end menu - -@node VC Directory Buffer -@subsubsection The VC Directory Buffer - - The VC Directory buffer contains a list of version-controlled files -and their version control statuses. It lists files in the current -directory (the one specified when you called @kbd{C-x v d}) and its -subdirectories, but only those with a ``noteworthy'' status. Files -that are up-to-date (i.e., the same as in the repository) are -omitted. If all the files in a subdirectory are up-to-date, the -subdirectory is not listed either. As an exception, if a file has -become up-to-date as a direct result of a VC command, it is listed. - - Here is an example of a VC Directory buffer listing: - -@smallexample -@group - ./ - edited configure.ac -* added README - unregistered temp.txt - src/ -* edited src/main.c -@end group -@end smallexample - -@noindent -Two work files have been modified but not committed: -@file{configure.ac} in the current directory, and @file{foo.c} in the -@file{src/} subdirectory. The file named @file{README} has been added -but is not yet committed, while @file{temp.txt} is not under version -control (@pxref{Registering}). - -The @samp{*} characters next to the entries for @file{README} and -@file{src/main.c} indicate that the user has marked out these files as -the current VC fileset -@iftex -(see below). -@end iftex -@ifnottex -(@pxref{VC Directory Commands}). -@end ifnottex - - The above example is typical for a decentralized version control -system like Bazaar, Git, or Mercurial. Other systems can show other -statuses. For instance, CVS shows the @samp{needs-update} status if -the repository has changes that have not been applied to the work -file. RCS and SCCS show the name of the user locking a file as its -status. - -@ifnottex -@vindex vc-stay-local -@vindex vc-cvs-stay-local - On CVS and Subversion, the @code{vc-dir} command normally contacts -the repository, which may be on a remote machine, to check for -updates. If you change the variable @code{vc-stay-local} or -@code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS -Options}), then Emacs avoids contacting a remote repository when -generating the VC Directory buffer (it will still contact it when -necessary, e.g., when doing a commit). This may be desirable if you -are working offline or the network is slow. -@end ifnottex - -@vindex vc-directory-exclusion-list - The VC Directory buffer omits subdirectories listed in the variable -@code{vc-directory-exclusion-list}. Its default value contains -directories that are used internally by version control systems. - -@node VC Directory Commands -@subsubsection VC Directory Commands - - Emacs provides several commands for navigating the VC Directory -buffer, and for ``marking'' files as belonging to the current VC -fileset. - -@table @kbd -@item n -@itemx @key{SPC} -Move point to the next entry (@code{vc-dir-next-line}). - -@item p -Move point to the previous entry (@code{vc-dir-previous-line}). - -@item @key{TAB} -Move to the next directory entry (@code{vc-dir-next-directory}). - -@item S-@key{TAB} -Move to the previous directory entry -(@code{vc-dir-previous-directory}). - -@item @key{RET} -@itemx f -Visit the file or directory listed on the current line -(@code{vc-dir-find-file}). - -@item o -Visit the file or directory on the current line, in a separate window -(@code{vc-dir-find-file-other-window}). - -@item m -Mark the file or directory on the current line (@code{vc-dir-mark}), -putting it in the current VC fileset. If the region is active, mark -all files in the region. - -A file cannot be marked with this command if it is already in a marked -directory, or one of its subdirectories. Similarly, a directory -cannot be marked with this command if any file in its tree is marked. - -@item M -If point is on a file entry, mark all files with the same status; if -point is on a directory entry, mark all files in that directory tree -(@code{vc-dir-mark-all-files}). With a prefix argument, mark all -listed files and directories. - -@item q -Quit the VC Directory buffer, and bury it (@code{quit-window}). - -@item u -Unmark the file or directory on the current line. If the region is -active, unmark all the files in the region (@code{vc-dir-unmark}). - -@item U -If point is on a file entry, unmark all files with the same status; if -point is on a directory entry, unmark all files in that directory tree -(@code{vc-dir-unmark-all-files}). With a prefix argument, unmark all -files and directories. - -@item x -Hide files with @samp{up-to-date} status -(@code{vc-dir-hide-up-to-date}). With a prefix argument, hide items -whose state is that of the item at point. -@end table - -@findex vc-dir-mark -@findex vc-dir-mark-all-files - While in the VC Directory buffer, all the files that you mark with -@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in -the current VC fileset. If you mark a directory entry with @kbd{m}, -all the listed files in that directory tree are in the current VC -fileset. The files and directories that belong to the current VC -fileset are indicated with a @samp{*} character in the VC Directory -buffer, next to their VC status. In this way, you can set up a -multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v -v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old -Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}). - - The VC Directory buffer also defines some single-key shortcuts for -VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l}, -@kbd{i}, @kbd{D}, @kbd{L}, @kbd{G}, @kbd{I} and @kbd{v}. - - For example, you can commit a set of edited files by opening a VC -Directory buffer, where the files are listed with the @samp{edited} -status; marking the files; and typing @kbd{v} or @kbd{C-x v v} -(@code{vc-next-action}). If the version control system is -changeset-based, Emacs will commit the files in a single revision. - - While in the VC Directory buffer, you can also perform search and -replace on the current VC fileset, with the following commands: - -@table @kbd -@item S -Search the fileset (@code{vc-dir-search}). - -@item Q -Do a regular expression query replace on the fileset -(@code{vc-dir-query-replace-regexp}). - -@item M-s a C-s -Do an incremental search on the fileset (@code{vc-dir-isearch}). - -@item M-s a C-M-s -Do an incremental regular expression search on the fileset -(@code{vc-dir-isearch-regexp}). -@end table - -@noindent -Apart from acting on multiple files, these commands behave much like -their single-buffer counterparts (@pxref{Search}). - -@cindex stashes in version control -@cindex shelves in version control - The above commands are also available via the menu bar, and via a -context menu invoked by @kbd{Mouse-2}. Furthermore, some VC backends -use the menu to provide extra backend-specific commands. For example, -Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves} -(where are a way to temporarily put aside uncommitted changes, and -bring them back at a later time). - -@node Branches -@subsection Version Control Branches -@cindex branch (version control) - - One use of version control is to support multiple independent lines -of development, which are called @dfn{branches}. Amongst other -things, branches can be used for maintaining separate ``stable'' and -``development'' versions of a program, and for developing unrelated -features in isolation from one another. - - VC's support for branch operations is currently fairly limited. For -decentralized version control systems, it provides commands for -@dfn{updating} one branch with the contents of another, and for -@dfn{merging} the changes made to two different branches -(@pxref{Merging}). For centralized version control systems, it -supports checking out different branches and committing into new or -different branches. - -@menu -* Switching Branches:: How to get to another existing branch. -* VC Pull:: Updating the contents of a branch. -* Merging:: Transferring changes between branches. -* Creating Branches:: How to start a new branch. -@end menu - -@node Switching Branches -@subsubsection Switching between Branches - - The various version control systems differ in how branches are -implemented, and these differences cannot be entirely concealed by VC. - - On some decentralized version control systems, including Bazaar and -Mercurial in its normal mode of operation, each branch has its own -working directory tree, so switching between branches just involves -switching directories. On Git, switching between branches is done -using the @command{git branch} command, which changes the contents of -the working tree itself. - - On centralized version control systems, you can switch between -branches by typing @kbd{C-u C-x v v} in an up-to-date work file -(@pxref{Advanced C-x v v}), and entering the revision ID for a -revision on another branch. On CVS, for instance, revisions on the -@dfn{trunk} (the main line of development) normally have IDs of the -form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say) -revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second -branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2, -@dots{}, and so forth. You can also specify the @dfn{branch ID}, -which is a branch revision ID omitting its final component -(e.g., 1.2.1), to switch to the latest revision on that branch. - - On a locking-based system, switching to a different branch also -unlocks (write-protects) the working tree. - - Once you have switched to a branch, VC commands will apply to that -branch until you switch away; for instance, any VC filesets that you -commit will be committed to that specific branch. - -@node VC Pull -@subsubsection Pulling Changes into a Branch - -@table @kbd -@item C-x v + -On a decentralized version control system, update the current branch -by ``pulling in'' changes from another location. - -On a centralized version control system, update the current VC -fileset. -@end table - -@kindex C-x v + -@findex vc-pull - On a decentralized version control system, the command @kbd{C-x v +} -(@code{vc-pull}) updates the current branch and working tree. It is -typically used to update a copy of a remote branch. If you supply a -prefix argument, the command prompts for the exact version control -command to use, which lets you specify where to pull changes from. -Otherwise, it pulls from a default location determined by the version -control system. - - Amongst decentralized version control systems, @kbd{C-x v +} is -currently supported only by Bazaar, Git, and Mercurial. On Bazaar, it -calls @command{bzr pull} for ordinary branches (to pull from a master -branch into a mirroring branch), and @command{bzr update} for a bound -branch (to pull from a central repository). On Git, it calls -@command{git pull} to fetch changes from a remote repository and merge -it into the current branch. On Mercurial, it calls @command{hg pull --u} to fetch changesets from the default remote repository and update -the working directory. - - Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming}) -to view a log buffer of the changes to be applied. @xref{VC Change -Log}. - - On a centralized version control system like CVS, @kbd{C-x v +} -updates the current VC fileset from the repository. - -@node Merging -@subsubsection Merging Branches -@cindex merging changes - -@table @kbd -@item C-x v m -On a decentralized version control system, merge changes from another -branch into the current one. - -On a centralized version control system, merge changes from another -branch into the current VC fileset. -@end table - - While developing a branch, you may sometimes need to @dfn{merge} in -changes that have already been made in another branch. This is not a -trivial operation, as overlapping changes may have been made to the -two branches. - - On a decentralized version control system, merging is done with the -command @kbd{C-x v m} (@code{vc-merge}). On Bazaar, this prompts for -the exact arguments to pass to @command{bzr merge}, offering a -sensible default if possible. On Git, this prompts for the name of a -branch to merge from, with completion (based on the branch names known -to the current repository). The output from running the merge command -is shown in a separate buffer. - - On a centralized version control system like CVS, @kbd{C-x v m} -prompts for a branch ID, or a pair of revision IDs (@pxref{Switching -Branches}); then it finds the changes from that branch, or the changes -between the two revisions you specified, and merges those changes into -the current VC fileset. If you just type @key{RET}, Emacs simply -merges any changes that were made on the same branch since you checked -the file out. - -@cindex conflicts -@cindex resolving conflicts - Immediately after performing a merge, only the working tree is -modified, and you can review the changes produced by the merge with -@kbd{C-x v D} and related commands (@pxref{Old Revisions}). If the -two branches contained overlapping changes, merging produces a -@dfn{conflict}; a warning appears in the output of the merge command, -and @dfn{conflict markers} are inserted into each affected work file, -surrounding the two sets of conflicting changes. You must then -resolve the conflict by editing the conflicted files. Once you are -done, the modified files must be committed in the usual way for the -merge to take effect (@pxref{Basic VC Editing}). - -@node Creating Branches -@subsubsection Creating New Branches - - On centralized version control systems like CVS, Emacs supports -creating new branches as part of a commit operation. When committing -a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action} -with a prefix argument; @pxref{Advanced C-x v v}). Then Emacs prompts -for a revision ID for the new revision. You should specify a suitable -branch ID for a branch starting at the current revision. For example, -if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2, -and so on, depending on the number of existing branches at that point. - - To create a new branch at an older revision (one that is no longer -the head of a branch), first select that revision (@pxref{Switching -Branches}). Your procedure will then differ depending on whether you -are using a locking or merging-based VCS. - - On a locking VCS, you will need to lock the old revision branch with -@kbd{C-x v v}. You'll be asked to confirm, when you lock the old -revision, that you really mean to create a new branch---if you say no, -you'll be offered a chance to lock the latest revision instead. On a -merging-based VCS you will skip this step. - - Then make your changes and type @kbd{C-x v v} again to commit a new -revision. This creates a new branch starting from the selected -revision. - - After the branch is created, subsequent commits create new revisions -on that branch. To leave the branch, you must explicitly select a -different revision with @kbd{C-u C-x v v}. - -@ifnottex -@include vc1-xtra.texi -@end ifnottex - -@node Change Log -@section Change Logs - -@cindex change log - Many software projects keep a @dfn{change log}. This is a file, -normally named @file{ChangeLog}, containing a chronological record of -when and how the program was changed. Sometimes, there are several -change log files, each recording the changes in one directory or -directory tree. - -@menu -* Change Log Commands:: Commands for editing change log files. -* Format of ChangeLog:: What the change log file looks like. -@end menu - -@node Change Log Commands -@subsection Change Log Commands - -@kindex C-x 4 a -@findex add-change-log-entry-other-window - The Emacs command @kbd{C-x 4 a} adds a new entry to the change log -file for the file you are editing -(@code{add-change-log-entry-other-window}). If that file is actually -a backup file, it makes an entry appropriate for the file's -parent---that is useful for making log entries for functions that -have been deleted in the current version. - - @kbd{C-x 4 a} visits the change log file and creates a new entry -unless the most recent entry is for today's date and your name. It -also creates a new item for the current file. For many languages, it -can even guess the name of the function or other object that was -changed. - -@vindex add-log-keep-changes-together - When the variable @code{add-log-keep-changes-together} is -non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file -rather than starting a new item. - -You can combine multiple changes of the same nature. If you don't -enter any text after the initial @kbd{C-x 4 a}, any subsequent -@kbd{C-x 4 a} adds another symbol to the change log entry. - -@vindex add-log-always-start-new-record - If @code{add-log-always-start-new-record} is non-@code{nil}, -@kbd{C-x 4 a} always makes a new entry, even if the last entry -was made by you and on the same date. - -@vindex change-log-version-info-enabled -@vindex change-log-version-number-regexp-list -@cindex file version in change log entries - If the value of the variable @code{change-log-version-info-enabled} -is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the -change log entry. It finds the version number by searching the first -ten percent of the file, using regular expressions from the variable -@code{change-log-version-number-regexp-list}. - -@cindex Change Log mode -@findex change-log-mode - The change log file is visited in Change Log mode. In this major -mode, each bunch of grouped items counts as one paragraph, and each -entry is considered a page. This facilitates editing the entries. -@kbd{C-j} and auto-fill indent each new line like the previous line; -this is convenient for entering the contents of an entry. - -You can use the @code{next-error} command (by default bound to -@kbd{C-x `}) to move between entries in the Change Log, when Change -Log mode is on. You will jump to the actual site in the file that was -changed, not just to the next Change Log entry. You can also use -@code{previous-error} to move back in the same list. - -@findex change-log-merge - You can use the command @kbd{M-x change-log-merge} to merge other -log files into a buffer in Change Log Mode, preserving the date -ordering of entries. - - Version control systems are another way to keep track of changes in -your program and keep a change log. In the VC log buffer, typing -@kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant -Change Log entry, if one exists. @xref{Log Buffer}. - -@node Format of ChangeLog -@subsection Format of ChangeLog - - A change log entry starts with a header line that contains the -current date, your name (taken from the variable -@code{add-log-full-name}), and your email address (taken from the -variable @code{add-log-mailing-address}). Aside from these header -lines, every line in the change log starts with a space or a tab. The -bulk of the entry consists of @dfn{items}, each of which starts with a -line starting with whitespace and a star. Here are two entries, both -dated in May 1993, with two items and one item respectively. - -@iftex -@medbreak -@end iftex -@smallexample -1993-05-25 Richard Stallman - - * man.el: Rename symbols `man-*' to `Man-*'. - (manual-entry): Make prompt string clearer. - - * simple.el (blink-matching-paren-distance): - Change default to 12,000. - -1993-05-24 Richard Stallman - - * vc.el (minor-mode-map-alist): Don't use it if it's void. - (vc-cancel-version): Doc fix. -@end smallexample - - One entry can describe several changes; each change should have its -own item, or its own line in an item. Normally there should be a -blank line between items. When items are related (parts of the same -change, in different places), group them by leaving no blank line -between them. - - You should put a copyright notice and permission notice at the -end of the change log file. Here is an example: - -@smallexample -Copyright 1997, 1998 Free Software Foundation, Inc. -Copying and distribution of this file, with or without modification, are -permitted provided the copyright notice and this notice are preserved. -@end smallexample - -@noindent -Of course, you should substitute the proper years and copyright holder. - -@node Tags -@section Tags Tables -@cindex tags and tag tables - - A @dfn{tag} is a reference to a subunit in a program or in a -document. In source code, tags reference syntactic elements of the -program: functions, subroutines, data types, macros, etc. In a -document, tags reference chapters, sections, appendices, etc. Each -tag specifies the name of the file where the corresponding subunit is -defined, and the position of the subunit's definition in that file. - - A @dfn{tags table} records the tags extracted by scanning the source -code of a certain program or a certain document. Tags extracted from -generated files reference the original files, rather than the -generated files that were scanned during tag extraction. Examples of -generated files include C files generated from Cweb source files, from -a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed -C files; and Fortran files produced by preprocessing @file{.fpp} -source files. - -@cindex etags - To produce a tags table, you run the @command{etags} shell command -on a document or the source code file. The @samp{etags} program -writes the tags to a @dfn{tags table file}, or @dfn{tags file} in -short. The conventional name for a tags file is @file{TAGS}@. -@xref{Create Tags Table}. - - Emacs provides many commands for searching and replacing using the -information recorded in tags tables. For instance, the @kbd{M-.} -(@code{find-tag}) jumps to the location of a specified function -definition in its source file. @xref{Find Tag}. - -@cindex C++ class browser, tags -@cindex tags, C++ -@cindex class browser, C++ -@cindex Ebrowse - The Ebrowse facility is similar to @command{etags} but specifically -tailored for C++. @xref{Top,, Ebrowse, ebrowse, Ebrowse User's -Manual}. The Semantic package provides another way to generate and -use tags, separate from the @command{etags} facility. -@xref{Semantic}. - -@menu -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @command{etags}. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Using tags for completion, and listing them. -@end menu - -@node Tag Syntax -@subsection Source File Tag Syntax - - Here is how tag syntax is defined for the most popular languages: - -@itemize @bullet -@item -In C code, any C function or typedef is a tag, and so are definitions of -@code{struct}, @code{union} and @code{enum}. -@code{#define} macro definitions, @code{#undef} and @code{enum} -constants are also -tags, unless you specify @samp{--no-defines} when making the tags table. -Similarly, global variables are tags, unless you specify -@samp{--no-globals}, and so are struct members, unless you specify -@samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines} -and @samp{--no-members} can make the tags table file much smaller. - -You can tag function declarations and external variables in addition -to function definitions by giving the @samp{--declarations} option to -@command{etags}. - -@item -In C++ code, in addition to all the tag constructs of C code, member -functions are also recognized; member variables are also recognized, -unless you use the @samp{--no-members} option. Tags for variables and -functions in classes are named @samp{@var{class}::@var{variable}} and -@samp{@var{class}::@var{function}}. @code{operator} definitions have -tag names like @samp{operator+}. - -@item -In Java code, tags include all the constructs recognized in C++, plus -the @code{interface}, @code{extends} and @code{implements} constructs. -Tags for variables and functions in classes are named -@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. - -@item -In @LaTeX{} documents, the arguments for @code{\chapter}, -@code{\section}, @code{\subsection}, @code{\subsubsection}, -@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, -@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry}, -@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand}, -@code{\newenvironment} and @code{\renewenvironment} are tags. - -Other commands can make tags as well, if you specify them in the -environment variable @env{TEXTAGS} before invoking @command{etags}. The -value of this environment variable should be a colon-separated list of -command names. For example, - -@example -TEXTAGS="mycommand:myothercommand" -export TEXTAGS -@end example - -@noindent -specifies (using Bourne shell syntax) that the commands -@samp{\mycommand} and @samp{\myothercommand} also define tags. - -@item -In Lisp code, any function defined with @code{defun}, any variable -defined with @code{defvar} or @code{defconst}, and in general the -first argument of any expression that starts with @samp{(def} in -column zero is a tag. As an exception, expressions of the form -@code{(defvar @var{foo})} are treated as declarations, and are only -tagged if the @samp{--declarations} option is given. - -@item -In Scheme code, tags include anything defined with @code{def} or with a -construct whose name starts with @samp{def}. They also include variables -set with @code{set!} at top level in the file. -@end itemize - - Several other languages are also supported: - -@itemize @bullet - -@item -In Ada code, functions, procedures, packages, tasks and types are -tags. Use the @samp{--packages-only} option to create tags for -packages only. - -In Ada, the same name can be used for different kinds of entity -(e.g., for a procedure and for a function). Also, for things like -packages, procedures and functions, there is the spec (i.e., the -interface) and the body (i.e., the implementation). To make it -easier to pick the definition you want, Ada tag name have suffixes -indicating the type of entity: - -@table @samp -@item /b -package body. -@item /f -function. -@item /k -task. -@item /p -procedure. -@item /s -package spec. -@item /t -type. -@end table - - Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go -directly to the body of the package @code{bidule}, while @kbd{M-x -find-tag @key{RET} bidule @key{RET}} will just search for any tag -@code{bidule}. - -@item -In assembler code, labels appearing at the start of a line, -followed by a colon, are tags. - -@item -In Bison or Yacc input files, each rule defines as a tag the nonterminal -it constructs. The portions of the file that contain C code are parsed -as C code. - -@item -In Cobol code, tags are paragraph names; that is, any word starting in -column 8 and followed by a period. - -@item -In Erlang code, the tags are the functions, records and macros defined -in the file. - -@item -In Fortran code, functions, subroutines and block data are tags. - -@item -In HTML input files, the tags are the @code{title} and the @code{h1}, -@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors -and all occurrences of @code{id=}. - -@item -In Lua input files, all functions are tags. - -@item -In makefiles, targets are tags; additionally, variables are tags -unless you specify @samp{--no-globals}. - -@item -In Objective C code, tags include Objective C definitions for classes, -class categories, methods and protocols. Tags for variables and -functions in classes are named @samp{@var{class}::@var{variable}} and -@samp{@var{class}::@var{function}}. - -@item -In Pascal code, the tags are the functions and procedures defined in -the file. - -@item -In Perl code, the tags are the packages, subroutines and variables -defined by the @code{package}, @code{sub}, @code{use constant}, -@code{my}, and @code{local} keywords. Use @samp{--globals} if you -want to tag global variables. Tags for subroutines are named -@samp{@var{package}::@var{sub}}. The name for subroutines defined in -the default package is @samp{main::@var{sub}}. - -@item -In PHP code, tags are functions, classes and defines. Vars are tags -too, unless you use the @samp{--no-members} option. - -@item -In PostScript code, the tags are the functions. - -@item -In Prolog code, tags are predicates and rules at the beginning of -line. - -@item -In Python code, @code{def} or @code{class} at the beginning of a line -generate a tag. -@end itemize - - You can also generate tags based on regexp matching (@pxref{Etags -Regexps}) to handle other formats and languages. - -@node Create Tags Table -@subsection Creating Tags Tables -@cindex @command{etags} program - - The @command{etags} program is used to create a tags table file. It knows -the syntax of several languages, as described in -@iftex -the previous section. -@end iftex -@ifnottex -@ref{Tag Syntax}. -@end ifnottex -Here is how to run @command{etags}: - -@example -etags @var{inputfiles}@dots{} -@end example - -@noindent -The @command{etags} program reads the specified files, and writes a tags -table named @file{TAGS} in the current working directory. You can -optionally specify a different file name for the tags table by using the -@samp{--output=@var{file}} option; specifying @file{-} as a file name -prints the tags table to standard output. - - If the specified files don't exist, @command{etags} looks for -compressed versions of them and uncompresses them to read them. Under -MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz} -if it is given @samp{mycode.c} on the command line and @file{mycode.c} -does not exist. - - If the tags table becomes outdated due to changes in the files -described in it, you can update it by running the @command{etags} -program again. If the tags table does not record a tag, or records it -for the wrong file, then Emacs will not be able to find that -definition until you update the tags table. But if the position -recorded in the tags table becomes a little bit wrong (due to other -editing), Emacs will still be able to find the right position, with a -slight delay. - - Thus, there is no need to update the tags table after each edit. -You should update a tags table when you define new tags that you want -to have listed, or when you move tag definitions from one file to -another, or when changes become substantial. - - You can make a tags table @dfn{include} another tags table, by -passing the @samp{--include=@var{file}} option to @command{etags}. It -then covers all the files covered by the included tags file, as well -as its own. - - If you specify the source files with relative file names when you run -@command{etags}, the tags file will contain file names relative to the -directory where the tags file was initially written. This way, you can -move an entire directory tree containing both the tags file and the -source files, and the tags file will still refer correctly to the source -files. If the tags file is @file{-} or is in the @file{/dev} directory, -however, the file names are -made relative to the current working directory. This is useful, for -example, when writing the tags to @file{/dev/stdout}. - - When using a relative file name, it should not be a symbolic link -pointing to a tags file in a different directory, because this would -generally render the file names invalid. - - If you specify absolute file names as arguments to @command{etags}, then -the tags file will contain absolute file names. This way, the tags file -will still refer to the same files even if you move it, as long as the -source files remain in the same place. Absolute file names start with -@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. - - When you want to make a tags table from a great number of files, -you may have problems listing them on the command line, because some -systems have a limit on its length. You can circumvent this limit by -telling @command{etags} to read the file names from its standard -input, by typing a dash in place of the file names, like this: - -@smallexample -find . -name "*.[chCH]" -print | etags - -@end smallexample - - @command{etags} recognizes the language used in an input file based -on its file name and contents. You can specify the language -explicitly with the @samp{--language=@var{name}} option. You can -intermix these options with file names; each one applies to the file -names that follow it. Specify @samp{--language=auto} to tell -@command{etags} to resume guessing the language from the file names -and file contents. Specify @samp{--language=none} to turn off -language-specific processing entirely; then @command{etags} recognizes -tags by regexp matching alone (@pxref{Etags Regexps}). - - The option @samp{--parse-stdin=@var{file}} is mostly useful when -calling @command{etags} from programs. It can be used (only once) in -place of a file name on the command line. @command{etags} will read from -standard input and mark the produced tags as belonging to the file -@var{file}. - - @samp{etags --help} outputs the list of the languages @command{etags} -knows, and the file name rules for guessing the language. It also prints -a list of all the available @command{etags} options, together with a short -explanation. If followed by one or more @samp{--language=@var{lang}} -options, it outputs detailed information about how tags are generated for -@var{lang}. - -@node Etags Regexps -@subsection Etags Regexps - - The @samp{--regex} option to @command{etags} allows tags to be -recognized by regular expression matching. You can intermix this -option with file names; each one applies to the source files that -follow it. If you specify multiple @samp{--regex} options, all of -them are used in parallel. The syntax is: - -@smallexample ---regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers} -@end smallexample - -@noindent -The essential part of the option value is @var{tagregexp}, the regexp -for matching tags. It is always used anchored, that is, it only -matches at the beginning of a line. If you want to allow indented -tags, use a regexp that matches initial whitespace; start it with -@samp{[ \t]*}. - - In these regular expressions, @samp{\} quotes the next character, and -all the GCC character escape sequences are supported (@samp{\a} for -bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for -escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for -carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab). - - Ideally, @var{tagregexp} should not match more characters than are -needed to recognize what you want to tag. If the syntax requires you -to write @var{tagregexp} so it matches more characters beyond the tag -itself, you should add a @var{nameregexp}, to pick out just the tag. -This will enable Emacs to find tags more accurately and to do -completion on tag names more reliably. You can find some examples -below. - - The @var{modifiers} are a sequence of zero or more characters that -modify the way @command{etags} does the matching. A regexp with no -modifiers is applied sequentially to each line of the input file, in a -case-sensitive way. The modifiers and their meanings are: - -@table @samp -@item i -Ignore case when matching this regexp. -@item m -Match this regular expression against the whole file, so that -multi-line matches are possible. -@item s -Match this regular expression against the whole file, and allow -@samp{.} in @var{tagregexp} to match newlines. -@end table - - The @samp{-R} option cancels all the regexps defined by preceding -@samp{--regex} options. It too applies to the file names following -it. Here's an example: - -@smallexample -etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ - bar.ber -R --lang=lisp los.er -@end smallexample - -@noindent -Here @command{etags} chooses the parsing language for @file{voo.doo} and -@file{bar.ber} according to their contents. @command{etags} also uses -@var{reg1} to recognize additional tags in @file{voo.doo}, and both -@var{reg1} and @var{reg2} to recognize additional tags in -@file{bar.ber}. @var{reg1} is checked against each line of -@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while -@var{reg2} is checked against the whole @file{bar.ber} file, -permitting multi-line matches, in a case-sensitive way. @command{etags} -uses only the Lisp tags rules, with no user-specified regexp matching, -to recognize tags in @file{los.er}. - - You can restrict a @samp{--regex} option to match only files of a -given language by using the optional prefix @var{@{language@}}. -(@samp{etags --help} prints the list of languages recognized by -@command{etags}.) This is particularly useful when storing many -predefined regular expressions for @command{etags} in a file. The -following example tags the @code{DEFVAR} macros in the Emacs source -files, for the C language only: - -@smallexample ---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' -@end smallexample - -@noindent -When you have complex regular expressions, you can store the list of -them in a file. The following option syntax instructs @command{etags} to -read two files of regular expressions. The regular expressions -contained in the second file are matched without regard to case. - -@smallexample ---regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file} -@end smallexample - -@noindent -A regex file for @command{etags} contains one regular expression per -line. Empty lines, and lines beginning with space or tab are ignored. -When the first character in a line is @samp{@@}, @command{etags} assumes -that the rest of the line is the name of another file of regular -expressions; thus, one such file can include another file. All the -other lines are taken to be regular expressions. If the first -non-whitespace text on the line is @samp{--}, that line is a comment. - - For example, we can create a file called @samp{emacs.tags} with the -following contents: - -@smallexample - -- This is for GNU Emacs C source files -@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ -@end smallexample - -@noindent -and then use it like this: - -@smallexample -etags --regex=@@emacs.tags *.[ch] */*.[ch] -@end smallexample - - Here are some more examples. The regexps are quoted to protect them -from shell interpretation. - -@itemize @bullet - -@item -Tag Octave files: - -@smallexample -etags --language=none \ - --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ - --regex='/###key \(.*\)/\1/' \ - --regex='/[ \t]*global[ \t].*/' \ - *.m -@end smallexample - -@noindent -Note that tags are not generated for scripts, so that you have to add -a line by yourself of the form @samp{###key @var{scriptname}} if you -want to jump to it. - -@item -Tag Tcl files: - -@smallexample -etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl -@end smallexample - -@item -Tag VHDL files: - -@smallexample -etags --language=none \ - --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ - --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ - \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' -@end smallexample -@end itemize - -@node Select Tags Table -@subsection Selecting a Tags Table - -@findex visit-tags-table - Emacs has at any time one @dfn{selected} tags table. All the -commands for working with tags tables use the selected one. To select -a tags table, type @kbd{M-x visit-tags-table}, which reads the tags -table file name as an argument, with @file{TAGS} in the default -directory as the default. - -@vindex tags-file-name - Emacs does not actually read in the tags table contents until you -try to use them; all @code{visit-tags-table} does is store the file -name in the variable @code{tags-file-name}, and setting the variable -yourself is just as good. The variable's initial value is @code{nil}; -that value tells all the commands for working with tags tables that -they must ask for a tags table file name to use. - - Using @code{visit-tags-table} when a tags table is already loaded -gives you a choice: you can add the new tags table to the current list -of tags tables, or start a new list. The tags commands use all the tags -tables in the current list. If you start a new list, the new tags table -is used @emph{instead} of others. If you add the new table to the -current list, it is used @emph{as well as} the others. - -@vindex tags-table-list - You can specify a precise list of tags tables by setting the variable -@code{tags-table-list} to a list of strings, like this: - -@c keep this on two lines for formatting in smallbook -@example -@group -(setq tags-table-list - '("~/emacs" "/usr/local/lib/emacs/src")) -@end group -@end example - -@noindent -This tells the tags commands to look at the @file{TAGS} files in your -@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} -directory. The order depends on which file you are in and which tags -table mentions that file, as explained above. - - Do not set both @code{tags-file-name} and @code{tags-table-list}. - -@node Find Tag -@subsection Finding a Tag - - The most important thing that a tags table enables you to do is to find -the definition of a specific tag. - -@table @kbd -@item M-.@: @var{tag} @key{RET} -Find first definition of @var{tag} (@code{find-tag}). -@item C-u M-. -Find next alternate definition of last tag specified. -@item C-u - M-. -Go back to previous tag found. -@item C-M-. @var{pattern} @key{RET} -Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). -@item C-u C-M-. -Find the next tag whose name matches the last pattern used. -@item C-x 4 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, but display it in another window -(@code{find-tag-other-window}). -@item C-x 5 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, and create a new frame to select the -buffer (@code{find-tag-other-frame}). -@item M-* -Pop back to where you previously invoked @kbd{M-.} and friends. -@end table - -@kindex M-. -@findex find-tag - @kbd{M-.}@: (@code{find-tag}) prompts for a tag name and jumps to -its source definition. It works by searching through the tags table -for that tag's file and approximate character position, visiting that -file, and searching for the tag definition at ever-increasing -distances away from the recorded approximate position. - - When entering the tag argument to @kbd{M-.}, the usual minibuffer -completion commands can be used (@pxref{Completion}), with the tag -names in the selected tags table as completion candidates. If you -specify an empty argument, the balanced expression in the buffer -before or around point is the default argument. @xref{Expressions}. - - You don't need to give @kbd{M-.} the full name of the tag; a part -will do. @kbd{M-.} finds tags which contain that argument as a -substring. However, it prefers an exact match to a substring match. -To find other tags that match the same substring, give @code{find-tag} -a numeric argument, as in @kbd{C-u M-.} or @kbd{M-0 M-.}; this does -not read a tag name, but continues searching the tags table's text for -another tag containing the same substring last used. - -@kindex C-x 4 . -@findex find-tag-other-window -@kindex C-x 5 . -@findex find-tag-other-frame - Like most commands that can switch buffers, @code{find-tag} has a -variant that displays the new buffer in another window, and one that -makes a new frame for it. The former is @w{@kbd{C-x 4 .}} -(@code{find-tag-other-window}), and the latter is @w{@kbd{C-x 5 .}} -(@code{find-tag-other-frame}). - - To move back to previous tag definitions, use @kbd{C-u - M-.}; more -generally, @kbd{M-.} with a negative numeric argument. Similarly, -@w{@kbd{C-x 4 .}} with a negative argument finds the previous tag -location in another window. - -@kindex M-* -@findex pop-tag-mark -@vindex find-tag-marker-ring-length - As well as going back to places you've found tags recently, you can -go back to places @emph{from where} you found them, using @kbd{M-*} -(@code{pop-tag-mark}). Thus you can find and examine the definition -of something with @kbd{M-.} and then return to where you were with -@kbd{M-*}. - - Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to -a depth determined by the variable @code{find-tag-marker-ring-length}. - -@findex find-tag-regexp -@kindex C-M-. - The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that -match a specified regular expression. It is just like @kbd{M-.} except -that it does regexp matching instead of substring matching. - -@node Tags Search -@subsection Searching and Replacing with Tags Tables -@cindex search and replace in multiple files -@cindex multiple-file search and replace - - The commands in this section visit and search all the files listed -in the selected tags table, one by one. For these commands, the tags -table serves only to specify a sequence of files to search. These -commands scan the list of tags tables starting with the first tags -table (if any) that describes the current file, proceed from there to -the end of the list, and then scan from the beginning of the list -until they have covered all the tables in the list. - -@table @kbd -@item M-x tags-search @key{RET} @var{regexp} @key{RET} -Search for @var{regexp} through the files in the selected tags -table. -@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} -Perform a @code{query-replace-regexp} on each file in the selected tags table. -@item M-, -Restart one of the commands above, from the current location of point -(@code{tags-loop-continue}). -@end table - -@findex tags-search - @kbd{M-x tags-search} reads a regexp using the minibuffer, then -searches for matches in all the files in the selected tags table, one -file at a time. It displays the name of the file being searched so you -can follow its progress. As soon as it finds an occurrence, -@code{tags-search} returns. - -@kindex M-, -@findex tags-loop-continue - Having found one match, you probably want to find all the rest. -Type @kbd{M-,} (@code{tags-loop-continue}) to resume the -@code{tags-search}, finding one more match. This searches the rest of -the current buffer, followed by the remaining files of the tags table. - -@findex tags-query-replace - @kbd{M-x tags-query-replace} performs a single -@code{query-replace-regexp} through all the files in the tags table. It -reads a regexp to search for and a string to replace with, just like -ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x -tags-search}, but repeatedly, processing matches according to your -input. @xref{Query Replace}, for more information on query replace. - -@vindex tags-case-fold-search -@cindex case-sensitivity and tags search - You can control the case-sensitivity of tags search commands by -customizing the value of the variable @code{tags-case-fold-search}. The -default is to use the same setting as the value of -@code{case-fold-search} (@pxref{Search Case}). - - It is possible to get through all the files in the tags table with a -single invocation of @kbd{M-x tags-query-replace}. But often it is -useful to exit temporarily, which you can do with any input event that -has no special query replace meaning. You can resume the query -replace subsequently by typing @kbd{M-,}; this command resumes the -last tags search or replace command that you did. For instance, to -skip the rest of the current file, you can type @kbd{M-> M-,}. - - The commands in this section carry out much broader searches than the -@code{find-tag} family. The @code{find-tag} commands search only for -definitions of tags that match your substring or regexp. The commands -@code{tags-search} and @code{tags-query-replace} find every occurrence -of the regexp, as ordinary search commands and replace commands do in -the current buffer. - - These commands create buffers only temporarily for the files that they -have to search (those which are not already visited in Emacs buffers). -Buffers in which no match is found are quickly killed; the others -continue to exist. - - As an alternative to @code{tags-search}, you can run @command{grep} -as a subprocess and have Emacs show you the matching lines one by one. -@xref{Grep Searching}. - -@node List Tags -@subsection Tags Table Inquiries - -@table @kbd -@item C-M-i -@itemx M-@key{TAB} -Perform completion on the text around point, using the selected tags -table if one is loaded (@code{completion-at-point}). -@item M-x list-tags @key{RET} @var{file} @key{RET} -Display a list of the tags defined in the program file @var{file}. -@item M-x tags-apropos @key{RET} @var{regexp} @key{RET} -Display a list of all tags matching @var{regexp}. -@end table - -@cindex completion (symbol names) - In most programming language modes, you can type @kbd{C-M-i} or -@kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol -at point. If there is a selected tags table, this command can use it -to generate completion candidates. @xref{Symbol Completion}. - -@findex list-tags - @kbd{M-x list-tags} reads the name of one of the files covered by -the selected tags table, and displays a list of tags defined in that -file. Do not include a directory as part of the file name unless the -file name recorded in the tags table includes a directory. - -@findex tags-apropos -@vindex tags-apropos-verbose -@vindex tags-tag-face -@vindex tags-apropos-additional-actions - @kbd{M-x tags-apropos} is like @code{apropos} for tags -(@pxref{Apropos}). It displays a list of tags in the selected tags -table whose entries match @var{regexp}. If the variable -@code{tags-apropos-verbose} is non-@code{nil}, it displays the names -of the tags files together with the tag names. You can customize the -appearance of the output by setting the variable @code{tags-tag-face} -to a face. You can display additional output by customizing the -variable @code{tags-apropos-additional-actions}; see its documentation -for details. - -@findex next-file - @kbd{M-x next-file} visits files covered by the selected tags table. -The first time it is called, it visits the first file covered by the -table. Each subsequent call visits the next covered file, unless a -prefix argument is supplied, in which case it returns to the first -file. - -@node EDE -@section Emacs Development Environment -@cindex EDE (Emacs Development Environment) -@cindex Emacs Development Environment -@cindex Integrated development environment - -EDE (@dfn{Emacs Development Environment}) is a package that simplifies -the task of creating, building, and debugging large programs with -Emacs. It provides some of the features of an IDE, or @dfn{Integrated -Development Environment}, in Emacs. - -This section provides a brief description of EDE usage. -@ifnottex -For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}. -@end ifnottex -@iftex -For full details on Ede, type @kbd{C-h i} and then select the EDE -manual. -@end iftex - - EDE is implemented as a global minor mode (@pxref{Minor Modes}). To -enable it, type @kbd{M-x global-ede-mode} or click on the -@samp{Project Support (EDE)} item in the @samp{Tools} menu. You can -also enable EDE each time you start Emacs, by adding the following -line to your initialization file: - -@smallexample -(global-ede-mode t) -@end smallexample - -@noindent -Activating EDE adds a menu named @samp{Development} to the menu bar. -Many EDE commands, including the ones described below, can be invoked -from this menu. - - EDE organizes files into @dfn{projects}, which correspond to -directory trees. The @dfn{project root} is the topmost directory of a -project. To define a new project, visit a file in the desired project -root and type @kbd{M-x ede-new}. This command prompts for a -@dfn{project type}, which refers to the underlying method that EDE -will use to manage the project (@pxref{Creating a project, EDE,, ede, -Emacs Development Environment}). The most common project types are -@samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU -Automake (@pxref{Top, Automake,, automake, Automake}). In both cases, -EDE also creates a file named @file{Project.ede}, which stores -information about the project. - - A project may contain one or more @dfn{targets}. A target can be an -object file, executable program, or some other type of file, which is -``built'' from one or more of the files in the project. - - To add a new @dfn{target} to a project, type @kbd{C-c . t} -(@code{M-x ede-new-target}). This command also asks if you wish to -``add'' the current file to that target, which means that the target -is to be built from that file. After you have defined a target, you -can add more files to it by typing @kbd{C-c . a} -(@code{ede-add-file}). - - To build a target, type @kbd{C-c . c} (@code{ede-compile-target}). -To build all the targets in the project, type @kbd{C-c . C} -(@code{ede-compile-project}). EDE uses the file types to guess how -the target should be built. - -@ifnottex -@include emerge-xtra.texi -@end ifnottex diff --git a/doc/emacs/makefile.w32-in b/doc/emacs/makefile.w32-in deleted file mode 100644 index 297ec496fe6..00000000000 --- a/doc/emacs/makefile.w32-in +++ /dev/null @@ -1,153 +0,0 @@ -#### -*- Makefile -*- for the Emacs Manual - -# Copyright (C) 2003-2014 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -# Where to find the source code. The source code for Emacs's C kernel is -# expected to be in $(srcdir)/src, and the source code for Emacs's -# utility programs is expected to be in $(srcdir)/lib-src. This is -# set by the configure script's `--srcdir' option. -srcdir=. - -infodir = $(srcdir)/../../info - -# The makeinfo program is part of the Texinfo distribution. -MAKEINFO = makeinfo -MAKEINFO_OPTS = --force --enable-encoding -I$(srcdir) -MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat -INFO_EXT=.info -INFO_OPTS=--no-split -INFO_TARGETS = $(infodir)/emacs$(INFO_EXT) -DVI_TARGETS = emacs.dvi -INFOSOURCES = info.texi - -# The following rule does not work with all versions of `make'. -.SUFFIXES: .texi .dvi -.texi.dvi: - texi2dvi $< - -TEXI2DVI = texi2dvi -ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C - -EMACS_XTRA=\ - $(srcdir)/arevert-xtra.texi \ - $(srcdir)/cal-xtra.texi \ - $(srcdir)/dired-xtra.texi \ - $(srcdir)/picture-xtra.texi \ - $(srcdir)/emerge-xtra.texi \ - $(srcdir)/vc-xtra.texi \ - $(srcdir)/vc1-xtra.texi \ - $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi - -EMACSSOURCES= \ - $(srcdir)/emacs.texi \ - $(srcdir)/emacsver.texi \ - $(srcdir)/doclicense.texi \ - $(srcdir)/screen.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/entering.texi \ - $(srcdir)/basic.texi \ - $(srcdir)/mini.texi \ - $(srcdir)/m-x.texi \ - $(srcdir)/help.texi \ - $(srcdir)/mark.texi \ - $(srcdir)/killing.texi \ - $(srcdir)/regs.texi \ - $(srcdir)/display.texi \ - $(srcdir)/search.texi \ - $(srcdir)/fixit.texi \ - $(srcdir)/files.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/mule.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/indent.texi \ - $(srcdir)/text.texi \ - $(srcdir)/programs.texi \ - $(srcdir)/building.texi \ - $(srcdir)/maintaining.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/sending.texi \ - $(srcdir)/rmail.texi \ - $(srcdir)/dired.texi \ - $(srcdir)/calendar.texi \ - $(srcdir)/misc.texi \ - $(srcdir)/package.texi \ - $(srcdir)/custom.texi \ - $(srcdir)/trouble.texi \ - $(srcdir)/cmdargs.texi \ - $(srcdir)/xresources.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/macos.texi \ - $(srcdir)/msdog.texi \ - $(srcdir)/gnu.texi \ - $(srcdir)/glossary.texi \ - $(srcdir)/ack.texi \ - $(srcdir)/kmacro.texi \ - $(EMACS_XTRA) - -info: $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -# Note that all the Info targets build the Info files -# in srcdir. There is no provision for Info files -# to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. - -$(infodir)/dir: - $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -$(infodir)/emacs$(INFO_EXT): $(EMACSSOURCES) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ emacs.texi - -emacs.dvi: $(EMACSSOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs.texi - -emacs.html: $(EMACSSOURCES) - $(MAKEINFO) $(MAKEINFO_OPTS) --html -o $@ emacs.texi - -emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-xtra.texi - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* - -## FIXME $(infodir)/emacs* deletes too much, eg emacs-mime. -clean: mostlyclean - - $(DEL) *.dvi - - $(DEL) $(infodir)/emacs* - - $(DEL_TREE) emacs.html - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc -# Don't delete these, because they are outside the current directory. -# for file in $(INFO_TARGETS); do rm -f $${file}*; done - - -# Formerly this directory had texindex.c and getopt.c in it -# and this makefile built them to make texindex. -# That caused trouble because this is run entirely in the source directory. -# Since we expect to get texi2dvi from elsewhere, -# it is ok to expect texindex from elsewhere also. diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi deleted file mode 100644 index e3cda04ce51..00000000000 --- a/doc/emacs/mark.texi +++ /dev/null @@ -1,471 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Mark -@chapter The Mark and the Region -@cindex mark -@cindex setting a mark -@cindex region - - Many Emacs commands operate on an arbitrary contiguous part of the -current buffer. To specify the text for such a command to operate on, -you set @dfn{the mark} at one end of it, and move point to the other -end. The text between point and the mark is called @dfn{the region}. -The region always extends between point and the mark, no matter which -one comes earlier in the text; each time you move point, the region -changes. - -@cindex active region - Setting the mark at a position in the text also @dfn{activates} it. -When the mark is active, we say also that the region is active; Emacs -indicates its extent by highlighting the text within it, using the -@code{region} face (@pxref{Face Customization}). - - After certain non-motion commands, including any command that -changes the text in the buffer, Emacs automatically @dfn{deactivates} -the mark; this turns off the highlighting. You can also explicitly -deactivate the mark at any time, by typing @kbd{C-g} -(@pxref{Quitting}). - - The above default behavior is known as Transient Mark mode. -Disabling Transient Mark mode switches Emacs to an alternative -behavior, in which the region is usually not highlighted. -@xref{Disabled Transient Mark}. - -@vindex highlight-nonselected-windows - Setting the mark in one buffer has no effect on the marks in other -buffers. When you return to a buffer with an active mark, the mark is -at the same place as before. When multiple windows show the same -buffer, they can have different values of point, and thus different -regions, but they all share one common mark position. @xref{Windows}. -Ordinarily, only the selected window highlights its region; however, -if the variable @code{highlight-nonselected-windows} is -non-@code{nil}, each window highlights its own region. - - There is another kind of region: the ``rectangular region''. -@xref{Rectangles}. - -@menu -* Setting Mark:: Commands to set the mark. -* Marking Objects:: Commands to put region around textual units. -* Using Region:: Summary of ways to operate on contents of the region. -* Mark Ring:: Previous mark positions saved so you can go back there. -* Global Mark Ring:: Previous mark positions in various buffers. -* Shift Selection:: Using shifted cursor motion keys. -* Disabled Transient Mark:: Leaving regions unhighlighted by default. -@end menu - -@node Setting Mark -@section Setting the Mark - - Here are some commands for setting the mark: - -@table @kbd -@item C-@key{SPC} -Set the mark at point, and activate it (@code{set-mark-command}). -@item C-@@ -The same. -@item C-x C-x -Set the mark at point, and activate it; then move point where the mark -used to be (@code{exchange-point-and-mark}). -@item Drag-Mouse-1 -Set point and the mark around the text you drag across. -@item Mouse-3 -Set the mark at point, then move point to where you click -(@code{mouse-save-then-kill}). -@item @samp{Shifted cursor motion keys} -Set the mark at point if the mark is inactive, then move point. -@xref{Shift Selection}. -@end table - -@kindex C-SPC -@kindex C-@@ -@findex set-mark-command - The most common way to set the mark is with @kbd{C-@key{SPC}} -(@code{set-mark-command})@footnote{There is no @kbd{C-@key{SPC}} -character in @acronym{ASCII}; usually, typing @kbd{C-@key{SPC}} on a -text terminal gives the character @kbd{C-@@}. This key is also bound -to @code{set-mark-command}, so unless you are unlucky enough to have -a text terminal that behaves differently, you might as well think of -@kbd{C-@@} as @kbd{C-@key{SPC}}.}. This sets the mark where point is, -and activates it. You can then move point away, leaving the mark -behind. - - For example, suppose you wish to convert part of the buffer to upper -case. To accomplish this, go to one end of the desired text, type -@kbd{C-@key{SPC}}, and move point until the desired portion of text is -highlighted. Now type @kbd{C-x C-u} (@code{upcase-region}). This -converts the text in the region to upper case, and then deactivates -the mark. - - Whenever the mark is active, you can deactivate it by typing -@kbd{C-g} (@pxref{Quitting}). Most commands that operate on the -region also automatically deactivate the mark, like @kbd{C-x C-u} in -the above example. - - Instead of setting the mark in order to operate on a region, you can -also use it to ``remember'' a position in the buffer (by typing -@kbd{C-@key{SPC} C-@key{SPC}}), and later jump back there (by typing -@kbd{C-u C-@key{SPC}}). @xref{Mark Ring}, for details. - -@kindex C-x C-x -@findex exchange-point-and-mark - The command @kbd{C-x C-x} (@code{exchange-point-and-mark}) exchanges -the positions of point and the mark. @kbd{C-x C-x} is useful when you -are satisfied with the position of point but want to move the other -end of the region (where the mark is). Using @kbd{C-x C-x} a second -time, if necessary, puts the mark at the new position with point back -at its original position. Normally, if the mark is inactive, this -command first reactivates the mark wherever it was last set, to ensure -that the region is left highlighted. However, if you call it with a -prefix argument, it leaves the mark inactive and the region -unhighlighted; you can use this to jump to the mark in a manner -similar to @kbd{C-u C-@key{SPC}}. - - You can also set the mark with the mouse. If you press the left -mouse button (@kbd{down-mouse-1}) and drag the mouse across a range of -text, this sets the mark where you first pressed the mouse button and -puts point where you release it. Alternatively, clicking the right -mouse button (@kbd{mouse-3}) sets the mark at point and then moves -point to where you clicked. @xref{Mouse Commands}, for a more -detailed description of these mouse commands. - -@cindex shift-selection - Finally, you can set the mark by holding down the shift key while -typing certain cursor motion commands (such as @kbd{S-@key{RIGHT}}, -@kbd{S-C-f}, @kbd{S-C-n}, etc.). This is called @dfn{shift-selection}. -It sets the mark at point before moving point, but only if there is no -active mark set via shift-selection. The mark set by mouse commands -and by shift-selection behaves slightly differently from the usual -mark: any subsequent unshifted cursor motion command deactivates it -automatically. For details, @xref{Shift Selection}. - - Many commands that insert text, such as @kbd{C-y} (@code{yank}), set -the mark at the other end of the inserted text, without activating it. -This lets you easily return to that position (@pxref{Mark Ring}). You -can tell that a command does this when it shows @samp{Mark set} in the -echo area. - -@cindex primary selection - Under X, every time the active region changes, Emacs saves the text -in the region to the @dfn{primary selection}. This lets you insert -that text into other X applications with @kbd{mouse-2} clicks. -@xref{Primary Selection}. - -@node Marking Objects -@section Commands to Mark Textual Objects - -@cindex marking sections of text - Here are commands for placing point and the mark around a textual -object such as a word, list, paragraph or page: - -@table @kbd -@item M-@@ -Set mark after end of next word (@code{mark-word}). This does not -move point. -@item C-M-@@ -Set mark after end of following balanced expression -(@code{mark-sexp}). This does not move point. -@item M-h -Move point to the beginning of the current paragraph, and set mark at -the end (@code{mark-paragraph}). -@item C-M-h -Move point to the beginning of the current defun, and set mark at the -end (@code{mark-defun}). -@item C-x C-p -Move point to the beginning of the current page, and set mark at the -end (@code{mark-page}). -@item C-x h -Move point to the beginning of the buffer, and set mark at the end -(@code{mark-whole-buffer}). -@end table - -@kindex M-@@ -@findex mark-word - @kbd{M-@@} (@code{mark-word}) sets the mark at the end of the next -word (@pxref{Words}, for information about words). Repeated -invocations of this command extend the region by advancing the mark -one word at a time. As an exception, if the mark is active and -located before point, @kbd{M-@@} moves the mark backwards from its -current position one word at a time. - - This command also accepts a numeric argument @var{n}, which tells it -to advance the mark by @var{n} words. A negative argument moves the -mark back by @var{n} words. - -@kindex C-M-@@ -@findex mark-sexp - Similarly, @kbd{C-M-@@} (@code{mark-sexp}) puts the mark at the end -of the next balanced expression (@pxref{Expressions}). Repeated -invocations extend the region to subsequent expressions, while -positive or negative numeric arguments move the mark forward or -backward by the specified number of expressions. - - The other commands in the above list set both point and mark, so as -to delimit an object in the buffer. @kbd{M-h} (@code{mark-paragraph}) -marks paragraphs (@pxref{Paragraphs}), @kbd{C-M-h} (@code{mark-defun}) -marks top-level definitions (@pxref{Moving by Defuns}), and @kbd{C-x -C-p} (@code{mark-page}) marks pages (@pxref{Pages}). Repeated -invocations again play the same role, extending the region to -consecutive objects; similarly, numeric arguments specify how many -objects to move the mark by. - -@kindex C-x h -@findex mark-whole-buffer -@cindex select all - @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire buffer as -the region, by putting point at the beginning and the mark at the end. - -@node Using Region -@section Operating on the Region - -@cindex operations on a marked region - Once you have a region, here are some of the ways you can operate on -it: - -@itemize @bullet -@item -Kill it with @kbd{C-w} (@pxref{Killing}). -@item -Copy it to the kill ring with @kbd{M-w} (@pxref{Yanking}). -@item -Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}). -@item -Undo changes within it using @kbd{C-u C-/} (@pxref{Undo}). -@item -Replace text within it using @kbd{M-%} (@pxref{Query Replace}). -@item -Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}). -@item -Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}). -@item -Check the spelling of words within it with @kbd{M-$} (@pxref{Spelling}). -@item -Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). -@item -Save it in a register with @kbd{C-x r s} (@pxref{Registers}). -@item -Save it in a buffer or a file (@pxref{Accumulating Text}). -@end itemize - - Some commands have a default behavior when the mark is inactive, but -operate on the region if the mark is active. For example, @kbd{M-$} -(@code{ispell-word}) normally checks the spelling of the word at -point, but it checks the text in the region if the mark is active -(@pxref{Spelling}). Normally, such commands use their default -behavior if the region is empty (i.e., if mark and point are at the -same position). If you want them to operate on the empty region, -change the variable @code{use-empty-active-region} to @code{t}. - -@vindex delete-active-region - As described in @ref{Erasing}, the @key{DEL} -(@code{backward-delete-char}) and @key{delete} -(@code{delete-forward-char}) commands also act this way. If the mark -is active, they delete the text in the region. (As an exception, if -you supply a numeric argument @var{n}, where @var{n} is not one, these -commands delete @var{n} characters regardless of whether the mark is -active). If you change the variable @code{delete-active-region} to -@code{nil}, then these commands don't act differently when the mark is -active. If you change the value to @code{kill}, these commands -@dfn{kill} the region instead of deleting it (@pxref{Killing}). - -@vindex mark-even-if-inactive - Other commands always operate on the region, and have no default -behavior. Such commands usually have the word @code{region} in their -names, like @kbd{C-w} (@code{kill-region}) and @code{C-x C-u} -(@code{upcase-region}). If the mark is inactive, they operate on the -``inactive region''---that is, on the text between point and the -position at which the mark was last set (@pxref{Mark Ring}). To -disable this behavior, change the variable -@code{mark-even-if-inactive} to @code{nil}. Then these commands will -instead signal an error if the mark is inactive. - -@cindex Delete Selection mode -@cindex mode, Delete Selection -@findex delete-selection-mode - By default, text insertion occurs normally even if the mark is -active---for example, typing @kbd{a} inserts the character @samp{a}, -then deactivates the mark. If you enable Delete Selection mode, a -minor mode, then inserting text while the mark is active causes the -text in the region to be deleted first. To toggle Delete Selection -mode on or off, type @kbd{M-x delete-selection-mode}. - -@node Mark Ring -@section The Mark Ring - -@cindex mark ring - Each buffer remembers previous locations of the mark, in the -@dfn{mark ring}. Commands that set the mark also push the old mark -onto this ring. One of the uses of the mark ring is to remember spots -that you may want to go back to. - -@table @kbd -@item C-@key{SPC} C-@key{SPC} -Set the mark, pushing it onto the mark ring, without activating it. -@item C-u C-@key{SPC} -Move point to where the mark was, and restore the mark from the ring -of former marks. -@end table - -@kindex C-SPC C-SPC - The command @kbd{C-@key{SPC} C-@key{SPC}} is handy when you want to -use the mark to remember a position to which you may wish to return. -It pushes the current point onto the mark ring, without activating the -mark (which would cause Emacs to highlight the region). This is -actually two consecutive invocations of @kbd{C-@key{SPC}} -(@code{set-mark-command}); the first @kbd{C-@key{SPC}} sets the mark, -and the second @kbd{C-@key{SPC}} deactivates it. (When Transient Mark -mode is off, @kbd{C-@key{SPC} C-@key{SPC}} instead activates Transient -Mark mode temporarily; @pxref{Disabled Transient Mark}.) - -@kindex C-u C-SPC - To return to a marked position, use @code{set-mark-command} with a -prefix argument: @kbd{C-u C-@key{SPC}}. This moves point to where the -mark was, and deactivates the mark if it was active. Each subsequent -@kbd{C-u C-@key{SPC}} jumps to a prior position stored in the mark -ring. The positions you move through in this way are not lost; they -go to the end of the ring. - -@vindex set-mark-command-repeat-pop - If you set @code{set-mark-command-repeat-pop} to non-@code{nil}, -then immediately after you type @kbd{C-u C-@key{SPC}}, you can type -@kbd{C-@key{SPC}} instead of @kbd{C-u C-@key{SPC}} to cycle through -the mark ring. By default, @code{set-mark-command-repeat-pop} is -@code{nil}. - - Each buffer has its own mark ring. All editing commands use the -current buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} -always stays in the same buffer. - -@vindex mark-ring-max - The variable @code{mark-ring-max} specifies the maximum number of -entries to keep in the mark ring. This defaults to 16 entries. If -that many entries exist and another one is pushed, the earliest one in -the list is discarded. Repeating @kbd{C-u C-@key{SPC}} cycles through -the positions currently in the ring. - - If you want to move back to the same place over and over, the mark -ring may not be convenient enough. If so, you can record the position -in a register for later retrieval (@pxref{Position Registers,, Saving -Positions in Registers}). - -@node Global Mark Ring -@section The Global Mark Ring -@cindex global mark ring - -@vindex global-mark-ring-max - In addition to the ordinary mark ring that belongs to each buffer, -Emacs has a single @dfn{global mark ring}. Each time you set a mark, -this is recorded in the global mark ring in addition to the current -buffer's own mark ring, if you have switched buffers since the -previous mark setting. Hence, the global mark ring records a sequence -of buffers that you have been in, and, for each buffer, a place where -you set the mark. The length of the global mark ring is controlled by -@code{global-mark-ring-max}, and is 16 by default. - -@kindex C-x C-@key{SPC} -@findex pop-global-mark - The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to -the buffer and position of the latest entry in the global ring. It also -rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take -you to earlier buffers and mark positions. - -@node Shift Selection -@section Shift Selection -@cindex shift-selection - - If you hold down the shift key while typing a cursor motion command, -this sets the mark before moving point, so that the region extends -from the original position of point to its new position. This feature -is referred to as @dfn{shift-selection}. It is similar to the way -text is selected in other editors. - - The mark set via shift-selection behaves a little differently from -what we have described above. Firstly, in addition to the usual ways -of deactivating the mark (such as changing the buffer text or typing -@kbd{C-g}), the mark is deactivated by any @emph{unshifted} cursor -motion command. Secondly, any subsequent @emph{shifted} cursor motion -command avoids setting the mark anew. Therefore, a series of shifted -cursor motion commands will continuously adjust the region. - - Shift-selection only works if the shifted cursor motion key is not -already bound to a separate command (@pxref{Customization}). For -example, if you bind @kbd{S-C-f} to another command, typing -@kbd{S-C-f} runs that command instead of performing a shift-selected -version of @kbd{C-f} (@code{forward-char}). - - A mark set via mouse commands behaves the same as a mark set via -shift-selection (@pxref{Setting Mark}). For example, if you specify a -region by dragging the mouse, you can continue to extend the region -using shifted cursor motion commands. In either case, any unshifted -cursor motion command deactivates the mark. - - To turn off shift-selection, set @code{shift-select-mode} to -@code{nil}. Doing so does not disable setting the mark via mouse -commands. - -@node Disabled Transient Mark -@section Disabling Transient Mark Mode -@cindex mode, Transient Mark -@cindex Transient Mark mode -@cindex highlighting region -@cindex region highlighting -@cindex Zmacs mode -@findex transient-mark-mode - - The default behavior of the mark and region, in which setting the -mark activates it and highlights the region, is called Transient Mark -mode. This is a minor mode that is enabled by default. It can be -toggled with @kbd{M-x transient-mark-mode}, or with the @samp{Active -Region Highlighting} menu item in the @samp{Options} menu. Turning it -off switches Emacs to an alternative mode of operation: - -@itemize @bullet -@item -Setting the mark, with commands like @kbd{C-@key{SPC}} or @kbd{C-x -C-x}, does not highlight the region. Therefore, you can't tell by -looking where the mark is located; you have to remember. - -The usual solution to this problem is to set the mark and then use it -soon, before you forget where it is. You can also check where the -mark is by using @kbd{C-x C-x}, which exchanges the positions of the -point and the mark (@pxref{Setting Mark}). - -@item -Some commands, which ordinarily act on the region when the mark is -active, no longer do so. For example, normally @kbd{M-%} -(@code{query-replace}) performs replacements within the region, if the -mark is active. When Transient Mark mode is off, it always operates -from point to the end of the buffer. Commands that act this way are -identified in their own documentation. -@end itemize - - While Transient Mark mode is off, you can activate it temporarily -using @kbd{C-@key{SPC} C-@key{SPC}} or @kbd{C-u C-x C-x}. - -@table @kbd -@item C-@key{SPC} C-@key{SPC} -@kindex C-@key{SPC} C-@key{SPC} -Set the mark at point (like plain @kbd{C-@key{SPC}}) and enable -Transient Mark mode just once, until the mark is deactivated. (This -is not really a separate command; you are using the @kbd{C-@key{SPC}} -command twice.) - -@item C-u C-x C-x -@kindex C-u C-x C-x -Exchange point and mark, activate the mark and enable Transient Mark -mode temporarily, until the mark is next deactivated. (This is the -@kbd{C-x C-x} command, @code{exchange-point-and-mark}, with a prefix -argument.) -@end table - - These commands set or activate the mark, and enable Transient Mark -mode only until the mark is deactivated. One reason you may want to -use them is that some commands operate on the entire buffer instead of -the region when Transient Mark mode is off. Enabling Transient Mark -mode momentarily gives you a way to use these commands on the region. - - When you specify a region with the mouse (@pxref{Setting Mark}), or -with shift-selection (@pxref{Shift Selection}), this likewise -activates Transient Mark mode temporarily and highlights the region. diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi deleted file mode 100644 index a87aff0e135..00000000000 --- a/doc/emacs/mini.texi +++ /dev/null @@ -1,802 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Minibuffer -@chapter The Minibuffer -@cindex minibuffer - - The @dfn{minibuffer} is where Emacs commands read complicated -arguments, such as file names, buffer names, Emacs command names, or -Lisp expressions. We call it the ``minibuffer'' because it's a -special-purpose buffer with a small amount of screen space. You can -use the usual Emacs editing commands in the minibuffer to edit the -argument text. - -@menu -* Basic Minibuffer:: Basic usage of the minibuffer. -* Minibuffer File:: Entering file names with the minibuffer. -* Minibuffer Edit:: How to edit in the minibuffer. -* Completion:: An abbreviation facility for minibuffer input. -* Minibuffer History:: Reusing recent minibuffer arguments. -* Repetition:: Re-executing commands that used the minibuffer. -* Passwords:: Entering passwords in the echo area. -* Yes or No Prompts:: Replying yes or no in the echo area. -@end menu - -@node Basic Minibuffer -@section Using the Minibuffer - -@cindex prompt - When the minibuffer is in use, it appears in the echo area, with a -cursor. The minibuffer starts with a @dfn{prompt}, usually ending -with a colon. The prompt states what kind of input is expected, and -how it will be used. The prompt is highlighted using the -@code{minibuffer-prompt} face (@pxref{Faces}). - - The simplest way to enter a minibuffer argument is to type the text, -then @key{RET} to submit the argument and exit the minibuffer. -Alternatively, you can type @kbd{C-g} to exit the minibuffer by -canceling the command asking for the argument (@pxref{Quitting}). - -@cindex default argument - Sometimes, the prompt shows a @dfn{default argument}, inside -parentheses before the colon. This default will be used as the -argument if you just type @key{RET}. For example, commands that read -buffer names usually show a buffer name as the default; you can type -@key{RET} to operate on that default buffer. - -@cindex Minibuffer Electric Default mode -@cindex mode, Minibuffer Electric Default -@findex minibuffer-electric-default-mode -@vindex minibuffer-eldef-shorten-default - If you enable Minibuffer Electric Default mode, a global minor mode, -Emacs hides the default argument as soon as you modify the contents of -the minibuffer (since typing @key{RET} would no longer submit that -default). If you ever bring back the original minibuffer text, the -prompt again shows the default. Furthermore, if you change the -variable @code{minibuffer-eldef-shorten-default} to a non-@code{nil} -value, the default argument is displayed as @samp{[@var{default}]} -instead of @samp{(default @var{default})}, saving some screen space. -To enable this minor mode, type @kbd{M-x -minibuffer-electric-default-mode}. - - Since the minibuffer appears in the echo area, it can conflict with -other uses of the echo area. If an error message or an informative -message is emitted while the minibuffer is active, the message hides -the minibuffer for a few seconds, or until you type something; then -the minibuffer comes back. While the minibuffer is in use, keystrokes -do not echo. - -@node Minibuffer File -@section Minibuffers for File Names - -@cindex default directory - Commands such as @kbd{C-x C-f} (@code{find-file}) use the minibuffer -to read a file name argument (@pxref{Basic Files}). When the -minibuffer is used to read a file name, it typically starts out with -some initial text ending in a slash. This is the @dfn{default -directory}. For example, it may start out like this: - -@example -Find file: /u2/emacs/src/ -@end example - -@noindent -Here, @samp{Find file:@: } is the prompt and @samp{/u2/emacs/src/} is -the default directory. If you now type @kbd{buffer.c} as input, that -specifies the file @file{/u2/emacs/src/buffer.c}. @xref{File Names}, -for information about the default directory. - - You can specify the parent directory with @file{..}: -@file{/a/b/../foo.el} is equivalent to @file{/a/foo.el}. -Alternatively, you can use @kbd{M-@key{DEL}} to kill directory names -backwards (@pxref{Words}). - - To specify a file in a completely different directory, you can kill -the entire default with @kbd{C-a C-k} (@pxref{Minibuffer Edit}). -Alternatively, you can ignore the default, and enter an absolute file -name starting with a slash or a tilde after the default directory. -For example, you can specify @file{/etc/termcap} as follows: - -@example -Find file: /u2/emacs/src//etc/termcap -@end example - -@noindent -@cindex // in file name -@cindex double slash in file name -@cindex slashes repeated in file name -@findex file-name-shadow-mode -Emacs interprets a double slash as ``ignore everything before the -second slash in the pair''. In the example above, -@file{/u2/emacs/src/} is ignored, so the argument you supplied is -@file{/etc/termcap}. The ignored part of the file name is dimmed if -the terminal allows it. (To disable this dimming, turn off File Name -Shadow mode with the command @kbd{M-x file-name-shadow-mode}.) - -@cindex home directory shorthand - Emacs interprets @file{~/} as your home directory. Thus, -@file{~/foo/bar.txt} specifies a file named @file{bar.txt}, inside a -directory named @file{foo}, which is in turn located in your home -directory. In addition, @file{~@var{user-id}/} means the home -directory of a user whose login name is @var{user-id}. Any leading -directory name in front of the @file{~} is ignored: thus, -@file{/u2/emacs/~/foo/bar.txt} is equivalent to @file{~/foo/bar.txt}. - - On MS-Windows and MS-DOS systems, where a user doesn't always have a -home directory, Emacs uses several alternatives. For MS-Windows, see -@ref{Windows HOME}; for MS-DOS, see -@ifnottex -@ref{MS-DOS File Names}. -@end ifnottex -@iftex -@ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the digital version of -the Emacs Manual}. -@end iftex -On these systems, the @file{~@var{user-id}/} construct is supported -only for the current user, i.e., only if @var{user-id} is the current -user's login name. - -@vindex insert-default-directory - To prevent Emacs from inserting the default directory when reading -file names, change the variable @code{insert-default-directory} to -@code{nil}. In that case, the minibuffer starts out empty. -Nonetheless, relative file name arguments are still interpreted based -on the same default directory. - - You can also enter remote file names in the minibuffer. -@xref{Remote Files}. - -@node Minibuffer Edit -@section Editing in the Minibuffer - - The minibuffer is an Emacs buffer, albeit a peculiar one, and the -usual Emacs commands are available for editing the argument text. -(The prompt, however, is @dfn{read-only}, and cannot be changed.) - - Since @key{RET} in the minibuffer submits the argument, you can't -use it to insert a newline. You can do that with @kbd{C-q C-j}, which -inserts a @kbd{C-j} control character, which is formally equivalent to -a newline character (@pxref{Inserting Text}). Alternatively, you can -use the @kbd{C-o} (@code{open-line}) command (@pxref{Blank Lines}). - - Inside a minibuffer, the keys @key{TAB}, @key{SPC}, and @kbd{?} are -often bound to @dfn{completion commands}, which allow you to easily -fill in the desired text without typing all of it. @xref{Completion}. -As with @key{RET}, you can use @kbd{C-q} to insert a @key{TAB}, -@key{SPC}, or @samp{?} character. - - For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a -minibuffer moves point to the beginning of the argument text, not the -beginning of the prompt. For example, this allows you to erase the -entire argument with @kbd{C-a C-k}. - -@cindex height of minibuffer -@cindex size of minibuffer -@cindex growing minibuffer -@cindex resizing minibuffer - When the minibuffer is active, the echo area is treated much like an -ordinary Emacs window. For instance, you can switch to another window -(with @kbd{C-x o}), edit text there, then return to the minibuffer -window to finish the argument. You can even kill text in another -window, return to the minibuffer window, and yank the text into the -argument. There are some restrictions on the minibuffer window, -however: for instance, you cannot split it. @xref{Windows}. - -@vindex resize-mini-windows - Normally, the minibuffer window occupies a single screen line. -However, if you add two or more lines' worth of text into the -minibuffer, it expands automatically to accommodate the text. The -variable @code{resize-mini-windows} controls the resizing of the -minibuffer. The default value is @code{grow-only}, which means the -behavior we have just described. If the value is @code{t}, the -minibuffer window will also shrink automatically if you remove some -lines of text from the minibuffer, down to a minimum of one screen -line. If the value is @code{nil}, the minibuffer window never changes -size automatically, but you can use the usual window-resizing commands -on it (@pxref{Windows}). - -@vindex max-mini-window-height - The variable @code{max-mini-window-height} controls the maximum -height for resizing the minibuffer window. A floating-point number -specifies a fraction of the frame's height; an integer specifies the -maximum number of lines; @code{nil} means do not resize the minibuffer -window automatically. The default value is 0.25. - - The @kbd{C-M-v} command in the minibuffer scrolls the help text from -commands that display help text of any sort in another window. You -can also scroll the help text with @kbd{M-@key{prior}} and -@kbd{M-@key{next}} (or, equivalently, @kbd{M-@key{PageUp}} and -@kbd{M-@key{PageDown}}). This is especially useful with long lists of -possible completions. @xref{Other Window}. - -@vindex enable-recursive-minibuffers - Emacs normally disallows most commands that use the minibuffer while -the minibuffer is active. To allow such commands in the minibuffer, -set the variable @code{enable-recursive-minibuffers} to @code{t}. - -@findex minibuffer-inactive-mode - When not active, the minibuffer is in @code{minibuffer-inactive-mode}, -and clicking @kbd{Mouse-1} there shows the @file{*Messages*} buffer. -If you use a dedicated frame for minibuffers, Emacs also recognizes -certain keys there, for example @kbd{n} to make a new frame. - -@node Completion -@section Completion -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. -@cindex completion - - You can often use a feature called @dfn{completion} to help enter -arguments. This means that after you type part of the argument, Emacs -can fill in the rest, or some of it, based on what was typed so far. - -@cindex completion alternative - When completion is available, certain keys (usually @key{TAB}, -@key{RET}, and @key{SPC}) are rebound in the minibuffer to special -completion commands (@pxref{Completion Commands}). These commands -attempt to complete the text in the minibuffer, based on a set of -@dfn{completion alternatives} provided by the command that requested -the argument. You can usually type @kbd{?} to see a list of -completion alternatives. - - Although completion is usually done in the minibuffer, the feature -is sometimes available in ordinary buffers too. @xref{Symbol -Completion}. - -@menu -* Completion Example:: Examples of using completion. -* Completion Commands:: A list of completion commands. -* Completion Exit:: Completion and minibuffer text submission. -* Completion Styles:: How completion matches are chosen. -* Completion Options:: Options for completion. -@end menu - -@node Completion Example -@subsection Completion Example - -@kindex TAB @r{(completion)} - A simple example may help here. @kbd{M-x} uses the minibuffer to -read the name of a command, so completion works by matching the -minibuffer text against the names of existing Emacs commands. Suppose -you wish to run the command @code{auto-fill-mode}. You can do that by -typing @kbd{M-x auto-fill-mode @key{RET}}, but it is easier to use -completion. - - If you type @kbd{M-x a u @key{TAB}}, the @key{TAB} looks for -completion alternatives (in this case, command names) that start with -@samp{au}. There are several, including @code{auto-fill-mode} and -@code{autoconf-mode}, but they all begin with @code{auto}, so the -@samp{au} in the minibuffer completes to @samp{auto}. (More commands -may be defined in your Emacs session. For example, if a command -called @code{authorize-me} was defined, Emacs could only complete -as far as @samp{aut}.) - - If you type @key{TAB} again immediately, it cannot determine the -next character; it could be @samp{-}, @samp{a}, or @samp{c}. So it -does not add any characters; instead, @key{TAB} displays a list of all -possible completions in another window. - - Next, type @kbd{-f}. The minibuffer now contains @samp{auto-f}, and -the only command name that starts with this is @code{auto-fill-mode}. -If you now type @key{TAB}, completion fills in the rest of the -argument @samp{auto-fill-mode} into the minibuffer. - - Hence, typing just @kbd{a u @key{TAB} - f @key{TAB}} allows you to -enter @samp{auto-fill-mode}. - -@node Completion Commands -@subsection Completion Commands - - Here is a list of the completion commands defined in the minibuffer -when completion is allowed. - -@table @kbd -@item @key{TAB} -@findex minibuffer-complete -Complete the text in the minibuffer as much as possible; if unable to -complete, display a list of possible completions -(@code{minibuffer-complete}). -@item @key{SPC} -Complete up to one word from the minibuffer text before point -(@code{minibuffer-complete-word}). This command is not available for -arguments that often include spaces, such as file names. -@item @key{RET} -Submit the text in the minibuffer as the argument, possibly completing -first (@code{minibuffer-complete-and-exit}). @xref{Completion Exit}. -@item ? -Display a list of completions (@code{minibuffer-completion-help}). -@end table - -@kindex TAB @r{(completion)} -@findex minibuffer-complete - @key{TAB} (@code{minibuffer-complete}) is the most fundamental -completion command. It searches for all possible completions that -match the existing minibuffer text, and attempts to complete as much -as it can. @xref{Completion Styles}, for how completion alternatives -are chosen. - -@kindex SPC @r{(completion)} -@findex minibuffer-complete-word - @key{SPC} (@code{minibuffer-complete-word}) completes like -@key{TAB}, but only up to the next hyphen or space. If you have -@samp{auto-f} in the minibuffer and type @key{SPC}, it finds that the -completion is @samp{auto-fill-mode}, but it only inserts @samp{ill-}, -giving @samp{auto-fill-}. Another @key{SPC} at this point completes -all the way to @samp{auto-fill-mode}. - -@kindex ? @r{(completion)} -@cindex completion list - If @key{TAB} or @key{SPC} is unable to complete, it displays a list -of matching completion alternatives (if there are any) in another -window. You can display the same list with @kbd{?} -(@code{minibuffer-completion-help}). The following commands can be -used with the completion list: - -@table @kbd -@findex mouse-choose-completion -@item Mouse-1 -@itemx Mouse-2 -Clicking mouse button 1 or 2 on a completion alternative chooses it -(@code{mouse-choose-completion}). - -@findex switch-to-completions -@item M-v -@itemx @key{PageUp} -@itemx @key{prior} -Typing @kbd{M-v}, while in the minibuffer, selects the window showing -the completion list (@code{switch-to-completions}). This paves the -way for using the commands below. @key{PageUp} or @key{prior} does -the same. You can also select the window in other ways -(@pxref{Windows}). - -@findex choose-completion -@item @key{RET} -While in the completion list buffer, this chooses the completion at -point (@code{choose-completion}). - -@findex next-completion -@item @key{RIGHT} -While in the completion list buffer, this moves point to the following -completion alternative (@code{next-completion}). - -@findex previous-completion -@item @key{LEFT} -While in the completion list buffer, this moves point to the previous -completion alternative (@code{previous-completion}). -@end table - -@node Completion Exit -@subsection Completion Exit - -@kindex RET @r{(completion in minibuffer)} -@findex minibuffer-complete-and-exit - When a command reads an argument using the minibuffer with -completion, it also controls what happens when you type @key{RET} -(@code{minibuffer-complete-and-exit}) to submit the argument. There -are four types of behavior: - -@itemize @bullet -@item -@dfn{Strict completion} accepts only exact completion matches. Typing -@key{RET} exits the minibuffer only if the minibuffer text is an exact -match, or completes to one. Otherwise, Emacs refuses to exit the -minibuffer; instead it tries to complete, and if no completion can be -done it momentarily displays @samp{[No match]} after the minibuffer -text. (You can still leave the minibuffer by typing @kbd{C-g} to -cancel the command.) - -An example of a command that uses this behavior is @kbd{M-x}, since it -is meaningless for it to accept a non-existent command name. - -@item -@dfn{Cautious completion} is like strict completion, except @key{RET} -exits only if the text is already an exact match. If the text -completes to an exact match, @key{RET} performs that completion but -does not exit yet; you must type a second @key{RET} to exit. - -Cautious completion is used for reading file names for files that must -already exist, for example. - -@item -@dfn{Permissive completion} allows any input; the completion -candidates are just suggestions. Typing @key{RET} does not complete, -it just submits the argument as you have entered it. - -@cindex minibuffer confirmation -@cindex confirming in the minibuffer -@item -@dfn{Permissive completion with confirmation} is like permissive -completion, with an exception: if you typed @key{TAB} and this -completed the text up to some intermediate state (i.e., one that is not -yet an exact completion match), typing @key{RET} right afterward does -not submit the argument. Instead, Emacs asks for confirmation by -momentarily displaying @samp{[Confirm]} after the text; type @key{RET} -again to confirm and submit the text. This catches a common mistake, -in which one types @key{RET} before realizing that @key{TAB} did not -complete as far as desired. - -@vindex confirm-nonexistent-file-or-buffer -You can tweak the confirmation behavior by customizing the variable -@code{confirm-nonexistent-file-or-buffer}. The default value, -@code{after-completion}, gives the behavior we have just described. -If you change it to @code{nil}, Emacs does not ask for confirmation, -falling back on permissive completion. If you change it to any other -non-@code{nil} value, Emacs asks for confirmation whether or not the -preceding command was @key{TAB}. - -This behavior is used by most commands that read file names, like -@kbd{C-x C-f}, and commands that read buffer names, like @kbd{C-x b}. -@end itemize - -@node Completion Styles -@subsection How Completion Alternatives Are Chosen -@cindex completion style - - Completion commands work by narrowing a large list of possible -completion alternatives to a smaller subset that ``matches'' what you -have typed in the minibuffer. In @ref{Completion Example}, we gave a -simple example of such matching. The procedure of determining what -constitutes a ``match'' is quite intricate. Emacs attempts to offer -plausible completions under most circumstances. - - Emacs performs completion using one or more @dfn{completion -styles}---sets of criteria for matching minibuffer text to completion -alternatives. During completion, Emacs tries each completion style in -turn. If a style yields one or more matches, that is used as the list -of completion alternatives. If a style produces no matches, Emacs -falls back on the next style. - -@vindex completion-styles - The list variable @code{completion-styles} specifies the completion -styles to use. Each list element is the name of a completion style (a -Lisp symbol). The default completion styles are (in order): - -@table @code -@item basic -A matching completion alternative must have the same beginning as the -text in the minibuffer before point. Furthermore, if there is any -text in the minibuffer after point, the rest of the completion -alternative must contain that text as a substring. - -@findex partial completion -@item partial-completion -This aggressive completion style divides the minibuffer text into -words separated by hyphens or spaces, and completes each word -separately. (For example, when completing command names, -@samp{em-l-m} completes to @samp{emacs-lisp-mode}.) - -Furthermore, a @samp{*} in the minibuffer text is treated as a -@dfn{wildcard}---it matches any character at the corresponding -position in the completion alternative. - -@item emacs22 -This completion style is similar to @code{basic}, except that it -ignores the text in the minibuffer after point. It is so-named -because it corresponds to the completion behavior in Emacs 22. -@end table - -@noindent -The following additional completion styles are also defined, and you -can add them to @code{completion-styles} if you wish -(@pxref{Customization}): - -@table @code -@item substring -A matching completion alternative must contain the text in the -minibuffer before point, and the text in the minibuffer after point, -as substrings (in that same order). - -Thus, if the text in the minibuffer is @samp{foobar}, with point -between @samp{foo} and @samp{bar}, that matches -@samp{@var{a}foo@var{b}bar@var{c}}, where @var{a}, @var{b}, and -@var{c} can be any string including the empty string. - -@item initials -This very aggressive completion style attempts to complete acronyms -and initialisms. For example, when completing command names, it -matches @samp{lch} to @samp{list-command-history}. -@end table - -@noindent -There is also a very simple completion style called @code{emacs21}. -In this style, if the text in the minibuffer is @samp{foobar}, -only matches starting with @samp{foobar} are considered. - -@vindex completion-category-overrides -You can use different completion styles in different situations, -by setting the variable @code{completion-category-overrides}. -For example, the default setting says to use only @code{basic} -and @code{substring} completion for buffer names. - - -@node Completion Options -@subsection Completion Options - -@cindex case-sensitivity and completion -@cindex case in completion - Case is significant when completing case-sensitive arguments, such -as command names. For example, when completing command names, -@samp{AU} does not complete to @samp{auto-fill-mode}. Case -differences are ignored when completing arguments in which case does -not matter. - -@vindex read-file-name-completion-ignore-case -@vindex read-buffer-completion-ignore-case - When completing file names, case differences are ignored if the -variable @code{read-file-name-completion-ignore-case} is -non-@code{nil}. The default value is @code{nil} on systems that have -case-sensitive file-names, such as GNU/Linux; it is non-@code{nil} on -systems that have case-insensitive file-names, such as Microsoft -Windows. When completing buffer names, case differences are ignored -if the variable @code{read-buffer-completion-ignore-case} is -non-@code{nil}; the default is @code{nil}. - -@vindex completion-ignored-extensions -@cindex ignored file names, in completion - When completing file names, Emacs usually omits certain alternatives -that are considered unlikely to be chosen, as determined by the list -variable @code{completion-ignored-extensions}. Each element in the -list should be a string; any file name ending in such a string is -ignored as a completion alternative. Any element ending in a slash -(@file{/}) represents a subdirectory name. The standard value of -@code{completion-ignored-extensions} has several elements including -@code{".o"}, @code{".elc"}, and @code{"~"}. For example, if a -directory contains @samp{foo.c} and @samp{foo.elc}, @samp{foo} -completes to @samp{foo.c}. However, if @emph{all} possible -completions end in ``ignored'' strings, they are not ignored: in the -previous example, @samp{foo.e} completes to @samp{foo.elc}. Emacs -disregards @code{completion-ignored-extensions} when showing -completion alternatives in the completion list. - - Shell completion is an extended version of filename completion, -@pxref{Shell Options}. - -@vindex completion-auto-help - If @code{completion-auto-help} is set to @code{nil}, the completion -commands never display the completion list buffer; you must type -@kbd{?} to display the list. If the value is @code{lazy}, Emacs only -shows the completion list buffer on the second attempt to complete. -In other words, if there is nothing to complete, the first @key{TAB} -echoes @samp{Next char not unique}; the second @key{TAB} shows the -completion list buffer. - -@vindex completion-cycle-threshold - If @code{completion-cycle-threshold} is non-@code{nil}, completion -commands can ``cycle'' through completion alternatives. Normally, if -there is more than one completion alternative for the text in the -minibuffer, a completion command completes up to the longest common -substring. If you change @code{completion-cycle-threshold} to -@code{t}, the completion command instead completes to the first of -those completion alternatives; each subsequent invocation of the -completion command replaces that with the next completion alternative, -in a cyclic manner. If you give @code{completion-cycle-threshold} a -numeric value @var{n}, completion commands switch to this cycling -behavior only when there are @var{n} or fewer alternatives. - -@node Minibuffer History -@section Minibuffer History -@cindex minibuffer history -@cindex history of minibuffer input - - Every argument that you enter with the minibuffer is saved in a -@dfn{minibuffer history list} so you can easily use it again later. -You can use the following arguments to quickly fetch an earlier -argument into the minibuffer: - -@table @kbd -@item M-p -@itemx @key{UP} -Move to the previous item in the minibuffer history, an earlier -argument (@code{previous-history-element}). -@item M-n -@itemx @key{DOWN} -Move to the next item in the minibuffer history -(@code{next-history-element}). -@item M-r @var{regexp} @key{RET} -Move to an earlier item in the minibuffer history that -matches @var{regexp} (@code{previous-matching-history-element}). -@item M-s @var{regexp} @key{RET} -Move to a later item in the minibuffer history that matches -@var{regexp} (@code{next-matching-history-element}). -@end table - -@kindex M-p @r{(minibuffer history)} -@kindex M-n @r{(minibuffer history)} -@kindex UP @r{(minibuffer history)} -@kindex DOWN @r{(minibuffer history)} -@findex next-history-element -@findex previous-history-element - While in the minibuffer, @kbd{M-p} or @key{UP} -(@code{previous-history-element}) moves through the minibuffer history -list, one item at a time. Each @kbd{M-p} fetches an earlier item from -the history list into the minibuffer, replacing its existing contents. -Typing @kbd{M-n} or @key{DOWN} (@code{next-history-element}) moves -through the minibuffer history list in the opposite direction, -fetching later entries into the minibuffer. - - If you type @kbd{M-n} in the minibuffer when there are no later -entries in the minibuffer history (e.g., if you haven't previously -typed @kbd{M-p}), Emacs tries fetching from a list of default -arguments: values that you are likely to enter. You can think of this -as moving through the ``future history'' list. - - If you edit the text inserted by the @kbd{M-p} or @key{M-n} -minibuffer history commands, this does not change its entry in the -history list. However, the edited argument does go at the end of the -history list when you submit it. - -@findex previous-matching-history-element -@findex next-matching-history-element -@kindex M-r @r{(minibuffer history)} -@kindex M-s @r{(minibuffer history)} - You can use @kbd{M-r} (@code{previous-matching-history-element}) to -search through older elements in the history list, and @kbd{M-s} -(@code{next-matching-history-element}) to search through newer -entries. Each of these commands asks for a @dfn{regular expression} -as an argument, and fetches the first matching entry into the -minibuffer. @xref{Regexps}, for an explanation of regular -expressions. A numeric prefix argument @var{n} means to fetch the -@var{n}th matching entry. These commands are unusual, in that they -use the minibuffer to read the regular expression argument, even -though they are invoked from the minibuffer. An upper-case letter in -the regular expression makes the search case-sensitive (@pxref{Search -Case}). - - You can also search through the history using an incremental search. -@xref{Isearch Minibuffer}. - - Emacs keeps separate history lists for several different kinds of -arguments. For example, there is a list for file names, used by all -the commands that read file names. Other history lists include buffer -names, command names (used by @kbd{M-x}), and command arguments (used -by commands like @code{query-replace}). - -@vindex history-length - The variable @code{history-length} specifies the maximum length of a -minibuffer history list; adding a new element deletes the oldest -element if the list gets too long. If the value is @code{t}, there is -no maximum length. - -@vindex history-delete-duplicates - The variable @code{history-delete-duplicates} specifies whether to -delete duplicates in history. If it is non-@code{nil}, adding a new -element deletes from the list all other elements that are equal to it. -The default is @code{nil}. - -@node Repetition -@section Repeating Minibuffer Commands -@cindex command history -@cindex history of commands - - Every command that uses the minibuffer once is recorded on a special -history list, the @dfn{command history}, together with the values of -its arguments, so that you can repeat the entire command. In -particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} -uses the minibuffer to read the command name. - -@findex list-command-history -@table @kbd -@item C-x @key{ESC} @key{ESC} -Re-execute a recent minibuffer command from the command history - (@code{repeat-complex-command}). -@item M-x list-command-history -Display the entire command history, showing all the commands -@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. -@end table - -@kindex C-x ESC ESC -@findex repeat-complex-command - @kbd{C-x @key{ESC} @key{ESC}} re-executes a recent command that used -the minibuffer. With no argument, it repeats the last such command. -A numeric argument specifies which command to repeat; 1 means the last -one, 2 the previous, and so on. - - @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command -into a Lisp expression and then entering a minibuffer initialized with -the text for that expression. Even if you don't know Lisp, it will -probably be obvious which command is displayed for repetition. If you -type just @key{RET}, that repeats the command unchanged. You can also -change the command by editing the Lisp expression before you execute -it. The executed command is added to the front of the command history -unless it is identical to the most recent item. - - Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you -can use the usual minibuffer history commands (@pxref{Minibuffer -History}) to move through the history list. After finding the desired -previous command, you can edit its expression as usual and then execute -it by typing @key{RET}. - -@vindex isearch-resume-in-command-history - Incremental search does not, strictly speaking, use the minibuffer. -Therefore, although it behaves like a complex command, it normally -does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. -You can make incremental search commands appear in the history by -setting @code{isearch-resume-in-command-history} to a non-@code{nil} -value. @xref{Incremental Search}. - -@vindex command-history - The list of previous minibuffer-using commands is stored as a Lisp -list in the variable @code{command-history}. Each element is a Lisp -expression that describes one command and its arguments. Lisp programs -can re-execute a command by calling @code{eval} with the -@code{command-history} element. - -@node Passwords -@section Entering passwords - -Sometimes, you may need to enter a password into Emacs. For instance, -when you tell Emacs to visit a file on another machine via a network -protocol such as FTP, you often need to supply a password to gain -access to the machine (@pxref{Remote Files}). - - Entering a password is similar to using a minibuffer. Emacs -displays a prompt in the echo area (such as @samp{Password: }); after -you type the required password, press @key{RET} to submit it. To -prevent others from seeing your password, every character you type is -displayed as a dot (@samp{.}) instead of its usual form. - - Most of the features and commands associated with the minibuffer can -@emph{not} be used when entering a password. There is no history or -completion, and you cannot change windows or perform any other action -with Emacs until you have submitted the password. - - While you are typing the password, you may press @key{DEL} to delete -backwards, removing the last character entered. @kbd{C-u} deletes -everything you have typed so far. @kbd{C-g} quits the password prompt -(@pxref{Quitting}). @kbd{C-y} inserts the current kill into the -password (@pxref{Killing}). You may type either @key{RET} or -@key{ESC} to submit the password. Any other self-inserting character -key inserts the associated character into the password, and all other -input is ignored. - -@node Yes or No Prompts -@section Yes or No Prompts - - An Emacs command may require you to answer a ``yes or no'' question -during the course of its execution. Such queries come in two main -varieties. - -@cindex y or n prompt - For the first type of ``yes or no'' query, the prompt ends with -@samp{(y or n)}. Such a query does not actually use the minibuffer; -the prompt appears in the echo area, and you answer by typing either -@samp{y} or @samp{n}, which immediately delivers the response. For -example, if you type @kbd{C-x C-w} (@kbd{write-file}) to save a -buffer, and enter the name of an existing file, Emacs issues a prompt -like this: - -@smallexample -File `foo.el' exists; overwrite? (y or n) -@end smallexample - -@noindent -Because this query does not actually use the minibuffer, the usual -minibuffer editing commands cannot be used. However, you can perform -some window scrolling operations while the query is active: @kbd{C-l} -recenters the selected window; @kbd{M-v} (or @key{PageDown} or -@key{next}) scrolls forward; @kbd{C-v} (or @key{PageUp}, or -@key{prior}) scrolls backward; @kbd{C-M-v} scrolls forward in the next -window; and @kbd{C-M-S-v} scrolls backward in the next window. Typing -@kbd{C-g} dismisses the query, and quits the command that issued it -(@pxref{Quitting}). - -@cindex yes or no prompt - The second type of ``yes or no'' query is typically employed if -giving the wrong answer would have serious consequences; it uses the -minibuffer, and features a prompt ending with @samp{(yes or no)}. For -example, if you invoke @kbd{C-x k} (@code{kill-buffer}) on a -file-visiting buffer with unsaved changes, Emacs activates the -minibuffer with a prompt like this: - -@smallexample -Buffer foo.el modified; kill anyway? (yes or no) -@end smallexample - -@noindent -To answer, you must type @samp{yes} or @samp{no} into the minibuffer, -followed by @key{RET}. The minibuffer behaves as described in the -previous sections; you can switch to another window with @kbd{C-x o}, -use the history commands @kbd{M-p} and @kbd{M-f}, etc. Type @kbd{C-g} -to quit the minibuffer and the querying command. diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi deleted file mode 100644 index 9d660f16e19..00000000000 --- a/doc/emacs/misc.texi +++ /dev/null @@ -1,2619 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Miscellaneous Commands - - This chapter contains several brief topics that do not fit anywhere -else: viewing ``document files'', reading Usenet news, running shell -commands and shell subprocesses, using a single shared Emacs for -utilities that expect to run an editor as a subprocess, printing -hardcopy, sorting text, editing binary files, saving an Emacs session -for later resumption, following hyperlinks, emulating other editors, -and various diversions and amusements. - -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Gnus -@section Gnus -@cindex Gnus -@cindex Usenet news -@cindex newsreader - - Gnus is an Emacs package primarily designed for reading and posting -Usenet news. It can also be used to read and respond to messages from -a number of other sources---email, remote directories, digests, and so -on. Here we introduce Gnus and describe several basic features. -@ifnottex -For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. -@end ifnottex -@iftex -For full details on Gnus, type @kbd{C-h i} and then select the Gnus -manual. -@end iftex - -@menu -* Buffers of Gnus:: The group, summary, and article buffers. -* Gnus Startup:: What you should know about starting Gnus. -* Gnus Group Buffer:: A short description of Gnus group commands. -* Gnus Summary Buffer:: A short description of Gnus summary commands. -@end menu - -@node Buffers of Gnus -@subsection Gnus Buffers - - Gnus uses several buffers to display information and to receive -commands. The three most commonly-used Gnus buffers are the -@dfn{group buffer}, the @dfn{summary buffer} and the @dfn{article -buffer}. - - The @dfn{group buffer} contains a list of article sources (e.g., -newsgroups and email inboxes), which are collectively referred to as -@dfn{groups}. This is the first buffer Gnus displays when it starts -up. It normally displays only the groups to which you subscribe and -that contain unread articles. From this buffer, you can select a -group to read. - - The @dfn{summary buffer} lists the articles in a single group, -showing one article per line. By default, it displays each article's -author, subject, and line -@iftex -number. -@end iftex -@ifnottex -number, but this is customizable; @xref{Summary Buffer Format,,, gnus, -The Gnus Manual}. -@end ifnottex -The summary buffer is created when you select a group in the group -buffer, and is killed when you exit the group. - - From the summary buffer, you can choose an article to view. The -article is displayed in the @dfn{article buffer}. In normal Gnus -usage, you view this buffer but do not select it---all useful Gnus -commands can be invoked from the summary buffer. But you can select -the article buffer, and execute Gnus commands from it, if you wish. - -@node Gnus Startup -@subsection When Gnus Starts Up - -@findex gnus -@cindex @file{.newsrc} file - If your system has been set up for reading Usenet news, getting -started with Gnus is easy---just type @kbd{M-x gnus}. - - On starting up, Gnus reads your @dfn{news initialization file}: a -file named @file{.newsrc} in your home directory which lists your -Usenet newsgroups and subscriptions (this file is not unique to Gnus; -it is used by many other newsreader programs). It then tries to -contact the system's default news server, which is typically specified -by the @env{NNTPSERVER} environment variable. - - If your system does not have a default news server, or if you wish -to use Gnus for reading email, then before invoking @kbd{M-x gnus} you -need to tell Gnus where to get news and/or mail. To do this, -customize the variables @code{gnus-select-method} and/or -@code{gnus-secondary-select-methods}. -@iftex -See the Gnus manual for details. -@end iftex -@ifnottex -@xref{Finding the News,,, gnus, The Gnus Manual}. -@end ifnottex - - Once Gnus has started up, it displays the group buffer. By default, -the group buffer shows only a small number of @dfn{subscribed groups}. -Groups with other statuses---@dfn{unsubscribed}, @dfn{killed}, or -@dfn{zombie}---are hidden. The first time you start Gnus, any group -to which you are not subscribed is made into a killed group; any group -that subsequently appears on the news server becomes a zombie group. - - To proceed, you must select a group in the group buffer to open the -summary buffer for that group; then, select an article in the summary -buffer to view its article buffer in a separate window. The following -sections explain how to use the group and summary buffers to do this. - - To quit Gnus, type @kbd{q} in the group buffer. This automatically -records your group statuses in the files @file{.newsrc} and -@file{.newsrc.eld}, so that they take effect in subsequent Gnus -sessions. - -@node Gnus Group Buffer -@subsection Using the Gnus Group Buffer - - The following commands are available in the Gnus group buffer: - -@table @kbd -@kindex SPC @r{(Gnus Group mode)} -@findex gnus-group-read-group -@item @key{SPC} -Switch to the summary buffer for the group on the current line. - -@kindex l @r{(Gnus Group mode)} -@kindex A s @r{(Gnus Group mode)} -@findex gnus-group-list-groups -@item l -@itemx A s -In the group buffer, list only the groups to which you subscribe and -which contain unread articles (this is the default listing). - -@kindex L @r{(Gnus Group mode)} -@kindex A u @r{(Gnus Group mode)} -@findex gnus-group-list-all-groups -@item L -@itemx A u -List all subscribed and unsubscribed groups, but not killed or zombie -groups. - -@kindex A k @r{(Gnus Group mode)} -@findex gnus-group-list-all-groups -@item A k -List killed groups. - -@kindex A z @r{(Gnus Group mode)} -@findex gnus-group-list-all-groups -@item A z -List zombie groups. - -@kindex u @r{(Gnus Group mode)} -@findex gnus-group-unsubscribe-current-group -@cindex subscribe groups -@cindex unsubscribe groups -@item u -Toggle the subscription status of the group on the current line -(i.e., turn a subscribed group into an unsubscribed group, or vice -versa). Invoking this on a killed or zombie group turns it into an -unsubscribed group. - -@kindex C-k @r{(Gnus Group mode)} -@findex gnus-group-kill-group -@item C-k -Kill the group on the current line. Killed groups are not recorded in -the @file{.newsrc} file, and they are not shown in the @kbd{l} or -@kbd{L} listings. - -@kindex DEL @r{(Gnus Group mode)} -@item @key{DEL} -Move point to the previous group containing unread articles. - -@kindex n @r{(Gnus Group mode)} -@findex gnus-group-next-unread-group -@findex gnus-summary-next-unread-article -@item n -Move point to the next unread group. - -@kindex p @r{(Gnus Group mode)} -@findex gnus-group-prev-unread-group -@findex gnus-summary-prev-unread-article -@item p -Move point to the previous unread group. - -@kindex q @r{(Gnus Group mode)} -@findex gnus-group-exit -@item q -Update your Gnus settings, and quit Gnus. -@end table - -@node Gnus Summary Buffer -@subsection Using the Gnus Summary Buffer - - The following commands are available in the Gnus summary buffer: - -@table @kbd -@kindex SPC @r{(Gnus Summary mode)} -@findex gnus-group-read-group -@item @key{SPC} -If there is no article selected, select the article on the current -line and display its article buffer. Otherwise, try scrolling the -selected article buffer in its window; on reaching the end of the -buffer, select the next unread article. - -Thus, you can read through all articles by repeatedly typing -@key{SPC}. - -@kindex DEL @r{(Gnus Summary mode)} -@findex gnus-summary-prev-page -@item @key{DEL} -Scroll the text of the article backwards. - -@kindex n @r{(Gnus Summary mode)} -@findex gnus-group-next-unread-group -@findex gnus-summary-next-unread-article -@item n -Select the next unread article. - -@kindex p @r{(Gnus Summary mode)} -@findex gnus-group-prev-unread-group -@findex gnus-summary-prev-unread-article -@item p -Select the previous unread article. - -@kindex s @r{(Gnus Summary mode)} -@findex gnus-summary-isearch-article -@item s -Do an incremental search on the selected article buffer, as if you -switched to the buffer and typed @kbd{C-s} (@pxref{Incremental -Search}). - -@kindex M-s @r{(Gnus Summary mode)} -@findex gnus-summary-search-article-forward -@item M-s @var{regexp} @key{RET} -Search forward for articles containing a match for @var{regexp}. - -@kindex q @r{(Gnus Summary mode)} -@item q -Exit the summary buffer and return to the group buffer. -@end table - -@node Document View -@section Document Viewing -@cindex DVI file -@cindex PDF file -@cindex PS file -@cindex PostScript file -@cindex OpenDocument file -@cindex Microsoft Office file -@cindex DocView mode -@cindex mode, DocView -@cindex document viewer (DocView) -@findex doc-view-mode - - DocView mode is a major mode for viewing DVI, PostScript (PS), PDF, -OpenDocument, and Microsoft Office documents. It provides features -such as slicing, zooming, and searching inside documents. It works by -converting the document to a set of images using the @command{gs} -(GhostScript) command and other external tools @footnote{@code{gs} is -a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm} is -needed. For OpenDocument and Microsoft Office documents, the -@code{unoconv} tool is needed.}, and displaying those images. - -@findex doc-view-toggle-display -@findex doc-view-toggle-display -@cindex doc-view-minor-mode - When you visit a document file that can be displayed with DocView -mode, Emacs automatically uses DocView mode @footnote{The needed -external tools for the document type must be available, and Emacs must -be running in a graphical frame and have PNG image support. If any of -these requirements is not fulfilled, Emacs falls back to another major -mode.}. As an exception, when you visit a PostScript file, Emacs -switches to PS mode, a major mode for editing PostScript files as -text; however, it also enables DocView minor mode, so you can type -@kbd{C-c C-c} to view the document with DocView. In either DocView -mode or DocView minor mode, repeating @kbd{C-c C-c} -(@code{doc-view-toggle-display}) toggles between DocView and the -underlying file contents. - - You can explicitly enable DocView mode with the command @code{M-x -doc-view-mode}. You can toggle DocView minor mode with @code{M-x -doc-view-minor-mode}. - - When DocView mode starts, it displays a welcome screen and begins -formatting the file, page by page. It displays the first page once -that has been formatted. - - To kill the DocView buffer, type @kbd{k} -(@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q} -(@code{quit-window}). - -@menu -* Navigation: DocView Navigation. Navigating DocView buffers. -* Searching: DocView Searching. Searching inside documents. -* Slicing: DocView Slicing. Specifying which part of a page is displayed. -* Conversion: DocView Conversion. Influencing and triggering conversion. -@end menu - -@node DocView Navigation -@subsection DocView Navigation - - In DocView mode, you can scroll the current page using the usual -Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and -the arrow keys. - -@vindex doc-view-continuous - By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop -scrolling at the beginning and end of the current page, respectively. -However, if you change the variable @code{doc-view-continuous} to a -non-@code{nil} value, then @kbd{C-p} displays the previous page if you -are already at the beginning of the current page, and @kbd{C-n} -displays the next page if you are at the end of the current page. - -@findex doc-view-next-page -@findex doc-view-previous-page -@kindex n @r{(DocView mode)} -@kindex p @r{(DocView mode)} -@kindex C-x ] @r{(DocView mode)} -@kindex C-x [ @r{(DocView mode)} - You can also display the next page by typing @kbd{n}, @key{next} or -@kbd{C-x ]} (@code{doc-view-next-page}). To display the previous -page, type @kbd{p}, @key{prior} or @kbd{C-x [} -(@code{doc-view-previous-page}). - -@findex doc-view-scroll-up-or-next-page -@findex doc-view-scroll-down-or-previous-page -@kindex SPC @r{(DocView mode)} -@kindex DEL @r{(DocView mode)} - @key{SPC} (@code{doc-view-scroll-up-or-next-page}) is a convenient -way to advance through the document. It scrolls within the current -page or advances to the next. @key{DEL} moves backwards in a similar -way (@code{doc-view-scroll-down-or-previous-page}). - -@findex doc-view-first-page -@findex doc-view-last-page -@findex doc-view-goto-page -@kindex M-< @r{(DocView mode)} -@kindex M-> @r{(DocView mode)} - To go to the first page, type @kbd{M-<} -(@code{doc-view-first-page}); to go to the last one, type @kbd{M->} -(@code{doc-view-last-page}). To jump to a page by its number, type -@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}). - -@findex doc-view-enlarge -@findex doc-view-shrink -@vindex doc-view-resolution -@kindex + @r{(DocView mode)} -@kindex - @r{(DocView mode)} - You can enlarge or shrink the document with @kbd{+} -(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}). These -commands work by reconverting the document at the new size. To -specify the default size for DocView, customize the variable -@code{doc-view-resolution}. - -@node DocView Searching -@subsection DocView Searching - - In DocView mode, you can search the file's text for a regular -expression (@pxref{Regexps}). The interface for searching is inspired -by @code{isearch} (@pxref{Incremental Search}). - -@findex doc-view-search -@findex doc-view-search-backward -@findex doc-view-show-tooltip - To begin a search, type @kbd{C-s} (@code{doc-view-search}) or -@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular -expression using a minibuffer, then echoes the number of matches found -within the document. You can move forward and back among the matches -by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show -the match inside the page image; instead, it displays a tooltip (at -the mouse position) listing all matching lines in the current page. -To force display of this tooltip, type @kbd{C-t} -(@code{doc-view-show-tooltip}). - - To start a new search, use the search command with a prefix -argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r} -for a backward search. - -@node DocView Slicing -@subsection DocView Slicing - -Documents often have wide margins for printing. They are annoying -when reading the document on the screen, because they use up screen -space and can cause inconvenient scrolling. - -@findex doc-view-set-slice -@findex doc-view-set-slice-using-mouse - With DocView you can hide these margins by selecting a @dfn{slice} -of pages to display. A slice is a rectangle within the page area; -once you specify a slice in DocView, it applies to whichever page you -look at. - - To specify the slice numerically, type @kbd{s s} -(@code{doc-view-set-slice}); then enter the top left pixel position -and the slice's width and height. -@c ??? how does this work? - - A more convenient graphical way to specify the slice is with @kbd{s -m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to -select the slice. -@c ??? How does this work? - - The most convenient way is to set the optimal slice by using -BoundingBox information automatically determined from the document by -typing @kbd{s b} (@code{doc-view-set-slice-using-mouse}). - -@findex doc-view-reset-slice - To cancel the selected slice, type @kbd{s r} -(@code{doc-view-reset-slice}). Then DocView shows the entire page -including its entire margins. - -@node DocView Conversion -@subsection DocView Conversion - -@vindex doc-view-cache-directory -@findex doc-view-clear-cache - For efficiency, DocView caches the images produced by @command{gs}. -The name of this directory is given by the variable -@code{doc-view-cache-directory}. You can clear the cache directory by -typing @code{M-x doc-view-clear-cache}. - -@findex doc-view-kill-proc -@findex doc-view-kill-proc-and-buffer - To force reconversion of the currently viewed document, type @kbd{r} -or @kbd{g} (@code{revert-buffer}). To kill the converter process -associated with the current buffer, type @kbd{K} -(@code{doc-view-kill-proc}). The command @kbd{k} -(@code{doc-view-kill-proc-and-buffer}) kills the converter process and -the DocView buffer. - -@node EWW -@section Web Browsing with EWW - -@findex eww -@findex eww-open-file - @dfn{EWW}, the Emacs Web Wowser, is a web browser package for Emacs. -It allows browsing URLs within an Emacs buffer. The command @kbd{M-x -eww} will open a URL or search the web. You can open a file -using the command @kbd{M-x eww-open-file}. You can use EWW as the -web browser for @code{browse-url}, @pxref{Browse-URL}. For full -details, @pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}. - -@node Shell -@section Running Shell Commands from Emacs -@cindex subshell -@cindex shell commands - - Emacs has commands for passing single command lines to shell -subprocesses, and for running a shell interactively with input and -output to an Emacs buffer, and for running a shell in a terminal -emulator window. - -@table @kbd -@item M-! @var{cmd} @key{RET} -Run the shell command @var{cmd} and display the output -(@code{shell-command}). -@item M-| @var{cmd} @key{RET} -Run the shell command @var{cmd} with region contents as input; -optionally replace the region with the output -(@code{shell-command-on-region}). -@item M-& @var{cmd} @key{RET} -Run the shell command @var{cmd} asynchronously, and display the output -(@code{async-shell-command}). -@item M-x shell -Run a subshell with input and output through an Emacs buffer. You can -then give commands interactively. -@item M-x term -Run a subshell with input and output through an Emacs buffer. You can -then give commands interactively. Full terminal emulation is -available. -@end table - -@vindex exec-path - Whenever you specify a relative file name for an executable program -(either in the @var{cmd} argument to one of the above commands, or in -other contexts), Emacs searches for the program in the directories -specified by the variable @code{exec-path}. The value of this -variable must be a list of directory names; the default value is -initialized from the environment variable @env{PATH} when Emacs is -started (@pxref{General Variables}). - - @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It -is documented in its own manual. -@ifnottex -@xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}. -@end ifnottex -@iftex -See the Eshell Info manual, which is distributed with Emacs. -@end iftex - -@menu -* Single Shell:: How to run one shell command and return. -* Interactive Shell:: Permanent shell taking input via Emacs. -* Shell Mode:: Special Emacs commands used with permanent shell. -* Shell Prompts:: Two ways to recognize shell prompts. -* History: Shell History. Repeating previous commands in a shell buffer. -* Directory Tracking:: Keeping track when the subshell changes directory. -* Options: Shell Options. Options for customizing Shell mode. -* Terminal emulator:: An Emacs window as a terminal emulator. -* Term Mode:: Special Emacs commands used in Term mode. -* Remote Host:: Connecting to another computer. -* Serial Terminal:: Connecting to a serial port. -@end menu - -@node Single Shell -@subsection Single Shell Commands - -@kindex M-! -@findex shell-command - @kbd{M-!} (@code{shell-command}) reads a line of text using the -minibuffer and executes it as a shell command, in a subshell made just -for that command. Standard input for the command comes from the null -device. If the shell command produces any output, the output appears -either in the echo area (if it is short), or in an Emacs buffer named -@file{*Shell Command Output*}, displayed in another window (if the -output is long). - - For instance, one way to decompress a file named @file{foo.gz} is to -type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command normally -creates the file @file{foo} and produces no terminal output. - - A numeric argument to @code{shell-command}, e.g., @kbd{M-1 M-!}, -causes it to insert terminal output into the current buffer instead of -a separate buffer. It puts point before the output, and sets the mark -after the output. For instance, @kbd{M-1 M-! gunzip < foo.gz -@key{RET}} would insert the uncompressed form of the file -@file{foo.gz} into the current buffer. - - Provided the specified shell command does not end with @samp{&}, it -runs @dfn{synchronously}, and you must wait for it to exit before -continuing to use Emacs. To stop waiting, type @kbd{C-g} to quit; -this sends a @code{SIGINT} signal to terminate the shell command (this -is the same signal that @kbd{C-c} normally generates in the shell). -Emacs then waits until the command actually terminates. If the shell -command doesn't stop (because it ignores the @code{SIGINT} signal), -type @kbd{C-g} again; this sends the command a @code{SIGKILL} signal, -which is impossible to ignore. - -@kindex M-& -@findex async-shell-command - A shell command that ends in @samp{&} is executed -@dfn{asynchronously}, and you can continue to use Emacs as it runs. -You can also type @kbd{M-&} (@code{async-shell-command}) to execute a -shell command asynchronously; this is exactly like calling @kbd{M-!} -with a trailing @samp{&}, except that you do not need the @samp{&}. -The default output buffer for asynchronous shell commands is named -@samp{*Async Shell Command*}. Emacs inserts the output into this -buffer as it comes in, whether or not the buffer is visible in a -window. - -@vindex async-shell-command-buffer - If you want to run more than one asynchronous shell command at the -same time, they could end up competing for the output buffer. The -option @code{async-shell-command-buffer} specifies what to do about -this; e.g., whether to rename the pre-existing output buffer, or to -use a different buffer for the new command. Consult the variable's -documentation for more possibilities. - -@kindex M-| -@findex shell-command-on-region - @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but -passes the contents of the region as the standard input to the shell -command, instead of no input. With a numeric argument, it deletes the -old region and replaces it with the output from the shell command. - - For example, you can use @kbd{M-|} with the @command{gpg} program to -see what keys are in the buffer. If the buffer contains a GnuPG key, -type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents -to @command{gpg}. This will output the list of keys to the -@file{*Shell Command Output*} buffer. - -@vindex shell-file-name - The above commands use the shell specified by the variable -@code{shell-file-name}. Its default value is determined by the -@env{SHELL} environment variable when Emacs is started. If the file -name is relative, Emacs searches the directories listed in -@code{exec-path} (@pxref{Shell}). - - To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command -@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}. - -@vindex shell-command-default-error-buffer - By default, error output is intermixed with the regular output in -the output buffer. But if you change the value of the variable -@code{shell-command-default-error-buffer} to a string, error output is -inserted into a buffer of that name. - -@node Interactive Shell -@subsection Interactive Subshell - -@findex shell - To run a subshell interactively, type @kbd{M-x shell}. This creates -(or reuses) a buffer named @file{*shell*}, and runs a shell subprocess -with input coming from and output going to that buffer. That is to -say, any terminal output from the subshell goes into the buffer, -advancing point, and any terminal input for the subshell comes from -text in the buffer. To give input to the subshell, go to the end of -the buffer and type the input, terminated by @key{RET}. - - While the subshell is waiting or running a command, you can switch -windows or buffers and perform other editing in Emacs. Emacs inserts -the output from the subshell into the Shell buffer whenever it has -time to process it (e.g., while waiting for keyboard input). - -@cindex @code{comint-highlight-input} face -@cindex @code{comint-highlight-prompt} face - In the Shell buffer, prompts are displayed with the face -@code{comint-highlight-prompt}, and submitted input lines are -displayed with the face @code{comint-highlight-input}. This makes it -easier to distinguish input lines from the shell output. -@xref{Faces}. - - To make multiple subshells, invoke @kbd{M-x shell} with a prefix -argument (e.g., @kbd{C-u M-x shell}). Then the command will read a -buffer name, and create (or reuse) a subshell in that buffer. You can -also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely}, -then create a new @file{*shell*} buffer using plain @kbd{M-x shell}. -Subshells in different buffers run independently and in parallel. - -@vindex explicit-shell-file-name -@cindex environment variables for subshells -@cindex @env{ESHELL} environment variable -@cindex @env{SHELL} environment variable - To specify the shell file name used by @kbd{M-x shell}, customize -the variable @code{explicit-shell-file-name}. If this is @code{nil} -(the default), Emacs uses the environment variable @env{ESHELL} if it -exists. Otherwise, it usually uses the variable -@code{shell-file-name} (@pxref{Single Shell}); but if the default -directory is remote (@pxref{Remote Files}), it prompts you for the -shell file name. - - Emacs sends the new shell the contents of the file -@file{~/.emacs_@var{shellname}} as input, if it exists, where -@var{shellname} is the name of the file that the shell was loaded -from. For example, if you use bash, the file sent to it is -@file{~/.emacs_bash}. If this file is not found, Emacs tries with -@file{~/.emacs.d/init_@var{shellname}.sh}. - - To specify a coding system for the shell, you can use the command -@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can -also change the coding system for a running subshell by typing -@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication -Coding}. - -@cindex @env{INSIDE_EMACS} environment variable -@cindex @env{EMACS} environment variable - Emacs sets the environment variable @env{INSIDE_EMACS} in the -subshell to @samp{@var{version},comint}, where @var{version} is the -Emacs version (e.g., @samp{24.1}). Programs can check this variable -to determine whether they are running inside an Emacs subshell. (It -also sets the @env{EMACS} environment variable to @code{t}, if that -environment variable is not already defined. However, this -environment variable is deprecated; programs that use it should switch -to using @env{INSIDE_EMACS} instead.) - -@node Shell Mode -@subsection Shell Mode -@cindex Shell mode -@cindex mode, Shell - - The major mode for Shell buffers is Shell mode. Many of its special -commands are bound to the @kbd{C-c} prefix, and resemble the usual -editing and job control characters present in ordinary shells, except -that you must type @kbd{C-c} first. Here is a list of Shell mode -commands: - -@table @kbd -@item @key{RET} -@kindex RET @r{(Shell mode)} -@findex comint-send-input -Send the current line as input to the subshell -(@code{comint-send-input}). Any shell prompt at the beginning of the -line is omitted (@pxref{Shell Prompts}). If point is at the end of -buffer, this is like submitting the command line in an ordinary -interactive shell. However, you can also invoke @key{RET} elsewhere -in the shell buffer to submit the current line as input. - -@item @key{TAB} -@kindex TAB @r{(Shell mode)} -@findex completion-at-point -@cindex shell completion -Complete the command name or file name before point in the shell -buffer (@code{completion-at-point}). This uses the usual Emacs -completion rules (@pxref{Completion}), with the completion -alternatives being file names, environment variable names, the shell -command history, and history references (@pxref{History References}). -For options controlling the completion, @pxref{Shell Options}. - -@item M-? -@kindex M-? @r{(Shell mode)} -@findex comint-dynamic-list-filename@dots{} -Display temporarily a list of the possible completions of the file -name before point (@code{comint-dynamic-list-filename-completions}). - -@item C-d -@kindex C-d @r{(Shell mode)} -@findex comint-delchar-or-maybe-eof -Either delete a character or send @acronym{EOF} -(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell -buffer, this sends @acronym{EOF} to the subshell. Typed at any other -position in the buffer, this deletes a character as usual. - -@item C-c C-a -@kindex C-c C-a @r{(Shell mode)} -@findex comint-bol-or-process-mark -Move to the beginning of the line, but after the prompt if any -(@code{comint-bol-or-process-mark}). If you repeat this command twice -in a row, the second time it moves back to the process mark, which is -the beginning of the input that you have not yet sent to the subshell. -(Normally that is the same place---the end of the prompt on this -line---but after @kbd{C-c @key{SPC}} the process mark may be in a -previous line.) - -@item C-c @key{SPC} -Accumulate multiple lines of input, then send them together. This -command inserts a newline before point, but does not send the preceding -text as input to the subshell---at least, not yet. Both lines, the one -before this newline and the one after, will be sent together (along with -the newline that separates them), when you type @key{RET}. - -@item C-c C-u -@kindex C-c C-u @r{(Shell mode)} -@findex comint-kill-input -Kill all text pending at end of buffer to be sent as input -(@code{comint-kill-input}). If point is not at end of buffer, -this only kills the part of this text that precedes point. - -@item C-c C-w -@kindex C-c C-w @r{(Shell mode)} -Kill a word before point (@code{backward-kill-word}). - -@item C-c C-c -@kindex C-c C-c @r{(Shell mode)} -@findex comint-interrupt-subjob -Interrupt the shell or its current subjob if any -(@code{comint-interrupt-subjob}). This command also kills -any shell input pending in the shell buffer and not yet sent. - -@item C-c C-z -@kindex C-c C-z @r{(Shell mode)} -@findex comint-stop-subjob -Stop the shell or its current subjob if any (@code{comint-stop-subjob}). -This command also kills any shell input pending in the shell buffer and -not yet sent. - -@item C-c C-\ -@findex comint-quit-subjob -@kindex C-c C-\ @r{(Shell mode)} -Send quit signal to the shell or its current subjob if any -(@code{comint-quit-subjob}). This command also kills any shell input -pending in the shell buffer and not yet sent. - -@item C-c C-o -@kindex C-c C-o @r{(Shell mode)} -@findex comint-delete-output -Delete the last batch of output from a shell command -(@code{comint-delete-output}). This is useful if a shell command spews -out lots of output that just gets in the way. - -@item C-c C-s -@kindex C-c C-s @r{(Shell mode)} -@findex comint-write-output -Write the last batch of output from a shell command to a file -(@code{comint-write-output}). With a prefix argument, the file is -appended to instead. Any prompt at the end of the output is not -written. - -@item C-c C-r -@itemx C-M-l -@kindex C-c C-r @r{(Shell mode)} -@kindex C-M-l @r{(Shell mode)} -@findex comint-show-output -Scroll to display the beginning of the last batch of output at the top -of the window; also move the cursor there (@code{comint-show-output}). - -@item C-c C-e -@kindex C-c C-e @r{(Shell mode)} -@findex comint-show-maximum-output -Scroll to put the end of the buffer at the bottom of the window -(@code{comint-show-maximum-output}). - -@item C-c C-f -@kindex C-c C-f @r{(Shell mode)} -@findex shell-forward-command -@vindex shell-command-regexp -Move forward across one shell command, but not beyond the current line -(@code{shell-forward-command}). The variable @code{shell-command-regexp} -specifies how to recognize the end of a command. - -@item C-c C-b -@kindex C-c C-b @r{(Shell mode)} -@findex shell-backward-command -Move backward across one shell command, but not beyond the current line -(@code{shell-backward-command}). - -@item M-x dirs -Ask the shell for its working directory, and update the Shell buffer's -default directory. @xref{Directory Tracking}. - -@item M-x send-invisible @key{RET} @var{text} @key{RET} -@findex send-invisible -Send @var{text} as input to the shell, after reading it without -echoing. This is useful when a shell command runs a program that asks -for a password. - -Please note that Emacs will not echo passwords by default. If you -really want them to be echoed, evaluate (@pxref{Lisp Eval}) the -following Lisp expression: - -@example -(remove-hook 'comint-output-filter-functions - 'comint-watch-for-password-prompt) -@end example - -@item M-x comint-continue-subjob -@findex comint-continue-subjob -Continue the shell process. This is useful if you accidentally suspend -the shell process.@footnote{You should not suspend the shell process. -Suspending a subjob of the shell is a completely different matter---that -is normal practice, but you must use the shell to continue the subjob; -this command won't do it.} - -@item M-x comint-strip-ctrl-m -@findex comint-strip-ctrl-m -Discard all control-M characters from the current group of shell output. -The most convenient way to use this command is to make it run -automatically when you get output from the subshell. To do that, -evaluate this Lisp expression: - -@example -(add-hook 'comint-output-filter-functions - 'comint-strip-ctrl-m) -@end example - -@item M-x comint-truncate-buffer -@findex comint-truncate-buffer -This command truncates the shell buffer to a certain maximum number of -lines, specified by the variable @code{comint-buffer-maximum-size}. -Here's how to do this automatically each time you get output from the -subshell: - -@example -(add-hook 'comint-output-filter-functions - 'comint-truncate-buffer) -@end example -@end table - -@cindex Comint mode -@cindex mode, Comint - Shell mode is a derivative of Comint mode, a general-purpose mode for -communicating with interactive subprocesses. Most of the features of -Shell mode actually come from Comint mode, as you can see from the -command names listed above. The special features of Shell mode include -the directory tracking feature, and a few user commands. - - Other Emacs features that use variants of Comint mode include GUD -(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}). - -@findex comint-run - You can use @kbd{M-x comint-run} to execute any program of your choice -in a subprocess using unmodified Comint mode---without the -specializations of Shell mode. - -@node Shell Prompts -@subsection Shell Prompts - -@cindex prompt, shell - A prompt is text output by a program to show that it is ready to -accept new user input. Normally, Comint mode (and thus Shell mode) -automatically figures out part of the buffer is a prompt, based on the -output of the subprocess. (Specifically, it assumes that any received -output line which doesn't end with a newline is a prompt.) - - Comint mode divides the buffer into two types of @dfn{fields}: input -fields (where user input is typed) and output fields (everywhere -else). Prompts are part of the output fields. Most Emacs motion -commands do not cross field boundaries, unless they move over multiple -lines. For instance, when point is in the input field on a shell -command line, @kbd{C-a} puts point at the beginning of the input -field, after the prompt. Internally, the fields are implemented using -the @code{field} text property (@pxref{Text Properties,,, elisp, the -Emacs Lisp Reference Manual}). - -@vindex comint-use-prompt-regexp -@vindex shell-prompt-pattern - If you change the variable @code{comint-use-prompt-regexp} to a -non-@code{nil} value, then Comint mode recognize prompts using a -regular expression (@pxref{Regexps}). In Shell mode, the regular -expression is specified by the variable @code{shell-prompt-pattern}. -The default value of @code{comint-use-prompt-regexp} is @code{nil}, -because this method for recognizing prompts is unreliable, but you may -want to set it to a non-@code{nil} value in unusual circumstances. In -that case, Emacs does not divide the Comint buffer into fields, so the -general motion commands behave as they normally do in buffers without -special text properties. However, you can use the paragraph motion -commands to conveniently navigate the buffer (@pxref{Paragraphs}); in -Shell mode, Emacs uses @code{shell-prompt-pattern} as paragraph -boundaries. - -@node Shell History -@subsection Shell Command History - - Shell buffers support three ways of repeating earlier commands. You -can use keys like those used for the minibuffer history; these work -much as they do in the minibuffer, inserting text from prior commands -while point remains always at the end of the buffer. You can move -through the buffer to previous inputs in their original place, then -resubmit them or copy them to the end. Or you can use a -@samp{!}-style history reference. - -@menu -* Ring: Shell Ring. Fetching commands from the history list. -* Copy: Shell History Copying. Moving to a command and then copying it. -* History References:: Expanding @samp{!}-style history references. -@end menu - -@node Shell Ring -@subsubsection Shell History Ring - -@table @kbd -@findex comint-previous-input -@kindex M-p @r{(Shell mode)} -@item M-p -@itemx C-@key{UP} -Fetch the next earlier old shell command. - -@kindex M-n @r{(Shell mode)} -@findex comint-next-input -@item M-n -@itemx C-@key{DOWN} -Fetch the next later old shell command. - -@kindex M-r @r{(Shell mode)} -@findex comint-history-isearch-backward-regexp -@item M-r -Begin an incremental regexp search of old shell commands. - -@item C-c C-x -@kindex C-c C-x @r{(Shell mode)} -@findex comint-get-next-from-history -Fetch the next subsequent command from the history. - -@item C-c . -@kindex C-c . @r{(Shell mode)} -@findex comint-input-previous-argument -Fetch one argument from an old shell command. - -@item C-c C-l -@kindex C-c C-l @r{(Shell mode)} -@findex comint-dynamic-list-input-ring -Display the buffer's history of shell commands in another window -(@code{comint-dynamic-list-input-ring}). -@end table - - Shell buffers provide a history of previously entered shell -commands. To reuse shell commands from the history, use the editing -commands @kbd{M-p}, @kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work -just like the minibuffer history commands (@pxref{Minibuffer -History}), except that they operate within the Shell buffer rather -than the minibuffer. - - @kbd{M-p} fetches an earlier shell command to the end of the shell -buffer. Successive use of @kbd{M-p} fetches successively earlier -shell commands, each replacing any text that was already present as -potential shell input. @kbd{M-n} does likewise except that it finds -successively more recent shell commands from the buffer. -@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like -@kbd{M-n}. - - The history search command @kbd{M-r} begins an incremental regular -expression search of previous shell commands. After typing @kbd{M-r}, -start typing the desired string or regular expression; the last -matching shell command will be displayed in the current line. -Incremental search commands have their usual effects---for instance, -@kbd{C-s} and @kbd{C-r} search forward and backward for the next match -(@pxref{Incremental Search}). When you find the desired input, type -@key{RET} to terminate the search. This puts the input in the command -line. Any partial input you were composing before navigating the -history list is restored when you go to the beginning or end of the -history ring. - - Often it is useful to reexecute several successive shell commands that -were previously executed in sequence. To do this, first find and -reexecute the first command of the sequence. Then type @kbd{C-c C-x}; -that will fetch the following command---the one that follows the command -you just repeated. Then type @key{RET} to reexecute this command. You -can reexecute several successive commands by typing @kbd{C-c C-x -@key{RET}} over and over. - - The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) -copies an individual argument from a previous command, like -@kbd{@key{ESC} .} in Bash. The simplest use copies the last argument from the -previous shell command. With a prefix argument @var{n}, it copies the -@var{n}th argument instead. Repeating @kbd{C-c .} copies from an -earlier shell command instead, always using the same value of @var{n} -(don't give a prefix argument when you repeat the @kbd{C-c .} -command). - - These commands get the text of previous shell commands from a special -history list, not from the shell buffer itself. Thus, editing the shell -buffer, or even killing large parts of it, does not affect the history -that these commands access. - -@vindex shell-input-ring-file-name - Some shells store their command histories in files so that you can -refer to commands from previous shell sessions. Emacs reads -the command history file for your chosen shell, to initialize its own -command history. The file name is @file{~/.bash_history} for bash, -@file{~/.sh_history} for ksh, and @file{~/.history} for other shells. - -@node Shell History Copying -@subsubsection Shell History Copying - -@table @kbd -@kindex C-c C-p @r{(Shell mode)} -@findex comint-previous-prompt -@item C-c C-p -Move point to the previous prompt (@code{comint-previous-prompt}). - -@kindex C-c C-n @r{(Shell mode)} -@findex comint-next-prompt -@item C-c C-n -Move point to the following prompt (@code{comint-next-prompt}). - -@kindex C-c RET @r{(Shell mode)} -@findex comint-copy-old-input -@item C-c @key{RET} -Copy the input command at point, inserting the copy at the end of the -buffer (@code{comint-copy-old-input}). This is useful if you move -point back to a previous command. After you copy the command, you can -submit the copy as input with @key{RET}. If you wish, you can edit -the copy before resubmitting it. If you use this command on an output -line, it copies that line to the end of the buffer. - -@item Mouse-2 -If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy -the old input command that you click on, inserting the copy at the end -of the buffer (@code{comint-insert-input}). If -@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is -not over old input, just yank as usual. -@end table - - Moving to a previous input and then copying it with @kbd{C-c -@key{RET}} or @kbd{Mouse-2} produces the same results---the same -buffer contents---that you would get by using @kbd{M-p} enough times -to fetch that previous input from the history list. However, @kbd{C-c -@key{RET}} copies the text from the buffer, which can be different -from what is in the history list if you edit the input text in the -buffer after it has been sent. - -@node History References -@subsubsection Shell History References -@cindex history reference - - Various shells including csh and bash support @dfn{history -references} that begin with @samp{!} and @samp{^}. Shell mode -recognizes these constructs, and can perform the history substitution -for you. - - If you insert a history reference and type @key{TAB}, this searches -the input history for a matching command, performs substitution if -necessary, and places the result in the buffer in place of the history -reference. For example, you can fetch the most recent command -beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the -command if you wish, and then resubmit the command to the shell by -typing @key{RET}. - -@vindex comint-input-autoexpand -@findex comint-magic-space - Shell mode can optionally expand history references in the buffer -when you send them to the shell. To request this, set the variable -@code{comint-input-autoexpand} to @code{input}. You can make -@key{SPC} perform history expansion by binding @key{SPC} to the -command @code{comint-magic-space}. - - Shell mode recognizes history references when they follow a prompt. -@xref{Shell Prompts}, for how Shell mode recognizes prompts. - -@node Directory Tracking -@subsection Directory Tracking -@cindex directory tracking - -@vindex shell-pushd-regexp -@vindex shell-popd-regexp -@vindex shell-cd-regexp - Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd} -commands given to the subshell, in order to keep the Shell buffer's -default directory (@pxref{File Names}) the same as the shell's working -directory. It recognizes these commands by examining lines of input -that you send. - - If you use aliases for these commands, you can tell Emacs to -recognize them also, by setting the variables -@code{shell-pushd-regexp}, @code{shell-popd-regexp}, and -@code{shell-cd-regexp} to the appropriate regular expressions -(@pxref{Regexps}). For example, if @code{shell-pushd-regexp} matches -the beginning of a shell command line, that line is regarded as a -@code{pushd} command. These commands are recognized only at the -beginning of a shell command line. - -@findex dirs - If Emacs gets confused about changes in the working directory of the -subshell, type @kbd{M-x dirs}. This command asks the shell for its -working directory and updates the default directory accordingly. It -works for shells that support the most common command syntax, but may -not work for unusual shells. - -@findex dirtrack-mode -@cindex Dirtrack mode -@cindex mode, Dirtrack -@vindex dirtrack-list - You can also use Dirtrack mode, a buffer-local minor mode that -implements an alternative method of tracking the shell's working -directory. To use this method, your shell prompt must contain the -working directory at all times, and you must supply a regular -expression for recognizing which part of the prompt contains the -working directory; see the documentation of the variable -@code{dirtrack-list} for details. To use Dirtrack mode, type @kbd{M-x -dirtrack-mode} in the Shell buffer, or add @code{dirtrack-mode} to -@code{shell-mode-hook} (@pxref{Hooks}). - -@node Shell Options -@subsection Shell Mode Options - -@vindex comint-scroll-to-bottom-on-input - If the variable @code{comint-scroll-to-bottom-on-input} is -non-@code{nil}, insertion and yank commands scroll the selected window -to the bottom before inserting. The default is @code{nil}. - -@vindex comint-scroll-show-maximum-output - If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then -arrival of output when point is at the end tries to scroll the last -line of text to the bottom line of the window, showing as much useful -text as possible. (This mimics the scrolling behavior of most -terminals.) The default is @code{t}. - -@vindex comint-move-point-for-output - By setting @code{comint-move-point-for-output}, you can opt for -having point jump to the end of the buffer whenever output arrives---no -matter where in the buffer point was before. If the value is -@code{this}, point jumps in the selected window. If the value is -@code{all}, point jumps in each window that shows the Comint buffer. If -the value is @code{other}, point jumps in all nonselected windows that -show the current buffer. The default value is @code{nil}, which means -point does not jump to the end. - -@vindex comint-prompt-read-only - If you set @code{comint-prompt-read-only}, the prompts in the Comint -buffer are read-only. - -@vindex comint-input-ignoredups - The variable @code{comint-input-ignoredups} controls whether successive -identical inputs are stored in the input history. A non-@code{nil} -value means to omit an input that is the same as the previous input. -The default is @code{nil}, which means to store each input even if it is -equal to the previous input. - -@vindex comint-completion-addsuffix -@vindex comint-completion-recexact -@vindex comint-completion-autolist - Three variables customize file name completion. The variable -@code{comint-completion-addsuffix} controls whether completion inserts a -space or a slash to indicate a fully completed file or directory name -(non-@code{nil} means do insert a space or slash). -@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB} -to choose the shortest possible completion if the usual Emacs completion -algorithm cannot add even a single character. -@code{comint-completion-autolist}, if non-@code{nil}, says to list all -the possible completions whenever completion is not exact. - -@vindex shell-completion-execonly - Command completion normally considers only executable files. -If you set @code{shell-completion-execonly} to @code{nil}, -it considers nonexecutable files as well. - -@vindex shell-completion-fignore -@vindex comint-completion-fignore -The variable @code{shell-completion-fignore} specifies a list of file -name extensions to ignore in Shell mode completion. The default -setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to -ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other -related Comint modes use the variable @code{comint-completion-fignore} -instead. - -@findex shell-dynamic-complete-command -Some implementation details of the shell command completion may also be found -in the lisp documentation of the @code{shell-dynamic-complete-command} -function. - -@findex shell-pushd-tohome -@findex shell-pushd-dextract -@findex shell-pushd-dunique - You can configure the behavior of @samp{pushd}. Variables control -whether @samp{pushd} behaves like @samp{cd} if no argument is given -(@code{shell-pushd-tohome}), pop rather than rotate with a numeric -argument (@code{shell-pushd-dextract}), and only add directories to the -directory stack if they are not already on it -(@code{shell-pushd-dunique}). The values you choose should match the -underlying shell, of course. - -@node Terminal emulator -@subsection Emacs Terminal Emulator -@findex term - - To run a subshell in a text terminal emulator, use @kbd{M-x term}. -This creates (or reuses) a buffer named @file{*terminal*}, and runs a -subshell with input coming from your keyboard, and output going to -that buffer. - -@cindex line mode @r{(terminal emulator)} -@cindex char mode @r{(terminal emulator)} - The terminal emulator uses Term mode, which has two input modes. In -@dfn{line mode}, Term basically acts like Shell mode (@pxref{Shell -Mode}). In @dfn{char mode}, each character is sent directly to the -subshell, as terminal input; the sole exception is the terminal escape -character, which by default is @kbd{C-c} (@pxref{Term Mode}). Any -echoing of your input is the responsibility of the subshell; any -terminal output from the subshell goes into the buffer, advancing -point. - - Some programs (such as Emacs itself) need to control the appearance -of the terminal screen in detail. They do this by emitting special -control codes. Term mode recognizes and handles ANSI-standard -VT100-style escape sequences, which are accepted by most modern -terminals, including @command{xterm}. (Hence, you can actually run -Emacs inside an Emacs Term window.) - - The @code{term} face specifies the default appearance of text -in the terminal emulator (the default is the same appearance as the -@code{default} face). When terminal control codes are used to change -the appearance of text, these are represented in the terminal emulator -by the faces @code{term-color-black}, @code{term-color-red}, -@code{term-color-green}, @code{term-color-yellow} -@code{term-color-blue}, @code{term-color-magenta}, -@code{term-color-cyan}, @code{term-color-white}, -@code{term-color-underline}, and @code{term-color-bold}. -@xref{Faces}. - - You can also Term mode to communicate with a device connected to a -serial port. @xref{Serial Terminal}. - - The file name used to load the subshell is determined the same way -as for Shell mode. To make multiple terminal emulators, rename the -buffer @file{*terminal*} to something different using @kbd{M-x -rename-uniquely}, just as with Shell mode. - - Unlike Shell mode, Term mode does not track the current directory by -examining your input. But some shells can tell Term what the current -directory is. This is done automatically by @code{bash} version 1.15 -and later. - - - - -@node Term Mode -@subsection Term Mode -@cindex Term mode -@cindex mode, Term - - The terminal emulator uses Term mode, which has two input modes. In -line mode, Term basically acts like Shell mode (@pxref{Shell Mode}). -In char mode, each character is sent directly to the subshell, except -for the Term escape character, normally @kbd{C-c}. - - To switch between line and char mode, use these commands: - -@table @kbd -@kindex C-c C-j @r{(Term mode)} -@findex term-line-mode -@item C-c C-j -Switch to line mode (@code{term-line-mode}). Do nothing if already in -line mode. - -@kindex C-c C-k @r{(Term mode)} -@findex term-char-mode -@item C-c C-k -Switch to char mode (@code{term-char-mode}). Do nothing if already in -char mode. -@end table - - The following commands are only available in char mode: - -@table @kbd -@item C-c C-c -Send a literal @key{C-c} to the sub-shell. - -@item C-c @var{char} -This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For -example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which -is normally @samp{other-window}. -@end table - -@cindex paging in Term mode - Term mode has a page-at-a-time feature. When enabled, it makes -output pause at the end of each screenful: - -@table @kbd -@kindex C-c C-q @r{(Term mode)} -@findex term-pager-toggle -@item C-c C-q -Toggle the page-at-a-time feature. This command works in both line -and char modes. When the feature is enabled, the mode-line displays -the word @samp{page}, and each time Term receives more than a -screenful of output, it pauses and displays @samp{**MORE**} in the -mode-line. Type @key{SPC} to display the next screenful of output, or -@kbd{?} to see your other options. The interface is similar to the -@code{more} program. -@end table - -@node Remote Host -@subsection Remote Host Shell -@cindex remote host -@cindex connecting to remote host -@cindex Telnet -@cindex Rlogin - - You can login to a remote computer, using whatever commands you -would from a regular terminal (e.g., using the @code{telnet} or -@code{rlogin} commands), from a Term window. - - A program that asks you for a password will normally suppress -echoing of the password, so the password will not show up in the -buffer. This will happen just as if you were using a real terminal, -if the buffer is in char mode. If it is in line mode, the password is -temporarily visible, but will be erased when you hit return. (This -happens automatically; there is no special password processing.) - - When you log in to a different machine, you need to specify the type -of terminal you're using, by setting the @env{TERM} environment -variable in the environment for the remote login command. (If you use -bash, you do that by writing the variable assignment before the remote -login command, without a separating comma.) Terminal types -@samp{ansi} or @samp{vt100} will work on most systems. - -@node Serial Terminal -@subsection Serial Terminal -@cindex terminal, serial -@findex serial-term - - If you have a device connected to a serial port of your computer, -you can communicate with it by typing @kbd{M-x serial-term}. This -command asks for a serial port name and speed, and switches to a new -Term mode buffer. Emacs communicates with the serial device through -this buffer just like it does with a terminal in ordinary Term mode. - - The speed of the serial port is measured in bits per second. The -most common speed is 9600 bits per second. You can change the speed -interactively by clicking on the mode line. - - A serial port can be configured even more by clicking on ``8N1'' in -the mode line. By default, a serial port is configured as ``8N1'', -which means that each byte consists of 8 data bits, No parity check -bit, and 1 stopbit. - - If the speed or the configuration is wrong, you cannot communicate -with your device and will probably only see garbage output in the -window. - -@node Emacs Server -@section Using Emacs as a Server -@pindex emacsclient -@cindex Emacs as a server -@cindex server, using Emacs as -@cindex @env{EDITOR} environment variable - - Various programs can invoke your choice of editor to edit a -particular piece of text. For instance, version control programs -invoke an editor to enter version control logs (@pxref{Version -Control}), and the Unix @command{mail} utility invokes an editor to -enter a message to send. By convention, your choice of editor is -specified by the environment variable @env{EDITOR}. If you set -@env{EDITOR} to @samp{emacs}, Emacs would be invoked, but in an -inconvenient way---by starting a new Emacs process. This is -inconvenient because the new Emacs process doesn't share buffers, a -command history, or other kinds of information with any existing Emacs -process. - - You can solve this problem by setting up Emacs as an @dfn{edit -server}, so that it ``listens'' for external edit requests and acts -accordingly. There are two ways to start an Emacs server: - -@itemize -@findex server-start -@item -Run the command @code{server-start} in an existing Emacs process: -either type @kbd{M-x server-start}, or put the expression -@code{(server-start)} in your init file (@pxref{Init File}). The -existing Emacs process is the server; when you exit Emacs, the server -dies with the Emacs process. - -@cindex daemon, Emacs -@item -Run Emacs as a @dfn{daemon}, using the @samp{--daemon} command-line -option. @xref{Initial Options}. When Emacs is started this way, it -calls @code{server-start} after initialization, and returns control to -the calling terminal instead of opening an initial frame; it then -waits in the background, listening for edit requests. -@end itemize - -@cindex @env{TEXEDIT} environment variable - Either way, once an Emacs server is started, you can use a shell -command called @command{emacsclient} to connect to the Emacs process -and tell it to visit a file. You can then set the @env{EDITOR} -environment variable to @samp{emacsclient}, so that external programs -will use the existing Emacs process for editing.@footnote{Some -programs use a different environment variable; for example, to make -@TeX{} use @samp{emacsclient}, set the @env{TEXEDIT} environment -variable to @samp{emacsclient +%d %s}.} - -@vindex server-name - You can run multiple Emacs servers on the same machine by giving -each one a unique ``server name'', using the variable -@code{server-name}. For example, @kbd{M-x set-variable @key{RET} -server-name @key{RET} foo @key{RET}} sets the server name to -@samp{foo}. The @code{emacsclient} program can specify a server by -name, using the @samp{-s} option (@pxref{emacsclient Options}). - -@findex server-eval-at - If you have defined a server by a unique server name, it is possible -to connect to the server from another Emacs instance and evaluate Lisp -expressions on the server, using the @code{server-eval-at} function. -For instance, @code{(server-eval-at "foo" '(+ 1 2))} evaluates the -expression @code{(+ 1 2)} on the @samp{foo} server, and returns -@code{3}. (If there is no server with that name, an error is -signaled.) Currently, this feature is mainly useful for developers. - -@menu -* Invoking emacsclient:: Connecting to the Emacs server. -* emacsclient Options:: Emacs client startup options. -@end menu - -@node Invoking emacsclient -@subsection Invoking @code{emacsclient} -@cindex @code{emacsclient} invocation - - The simplest way to use the @command{emacsclient} program is to run -the shell command @samp{emacsclient @var{file}}, where @var{file} is a -file name. This connects to an Emacs server, and tells that Emacs -process to visit @var{file} in one of its existing frames---either a -graphical frame, or one in a text terminal (@pxref{Frames}). You -can then select that frame to begin editing. - - If there is no Emacs server, the @command{emacsclient} program halts -with an error message. If the Emacs process has no existing -frame---which can happen if it was started as a daemon (@pxref{Emacs -Server})---then Emacs opens a frame on the terminal in which you -called @command{emacsclient}. - - You can also force @command{emacsclient} to open a new frame on a -graphical display, or on a text terminal, using the @samp{-c} and -@samp{-t} options. @xref{emacsclient Options}. - - If you are running on a single text terminal, you can switch between -@command{emacsclient}'s shell and the Emacs server using one of two -methods: (i) run the Emacs server and @command{emacsclient} on -different virtual terminals, and switch to the Emacs server's virtual -terminal after calling @command{emacsclient}; or (ii) call -@command{emacsclient} from within the Emacs server itself, using Shell -mode (@pxref{Interactive Shell}) or Term mode (@pxref{Term Mode}); -@code{emacsclient} blocks only the subshell under Emacs, and you can -still use Emacs to edit the file. - -@kindex C-x # -@findex server-edit - When you finish editing @var{file} in the Emacs server, type -@kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file -and sends a message back to the @command{emacsclient} program, telling -it to exit. Programs that use @env{EDITOR} usually wait for the -``editor''---in this case @command{emacsclient}---to exit before doing -something else. - - You can also call @command{emacsclient} with multiple file name -arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the -Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs -selects the buffer visiting @var{file1}, and buries the other buffers -at the bottom of the buffer list (@pxref{Buffers}). The -@command{emacsclient} program exits once all the specified files are -finished (i.e., once you have typed @kbd{C-x #} in each server -buffer). - -@vindex server-kill-new-buffers -@vindex server-temp-file-regexp - Finishing with a server buffer also kills the buffer, unless it -already existed in the Emacs session before the server was asked to -create it. However, if you set @code{server-kill-new-buffers} to -@code{nil}, then a different criterion is used: finishing with a -server buffer kills it if the file name matches the regular expression -@code{server-temp-file-regexp}. This is set up to distinguish certain -``temporary'' files. - - Each @kbd{C-x #} checks for other pending external requests to edit -various files, and selects the next such file. You can switch to a -server buffer manually if you wish; you don't have to arrive at it -with @kbd{C-x #}. But @kbd{C-x #} is the way to tell -@command{emacsclient} that you are finished. - -@vindex server-window - If you set the value of the variable @code{server-window} to a -window or a frame, @kbd{C-x #} always displays the next server buffer -in that window or in that frame. - -@node emacsclient Options -@subsection @code{emacsclient} Options -@cindex @code{emacsclient} options - - You can pass some optional arguments to the @command{emacsclient} -program, such as: - -@example -emacsclient -c +12 @var{file1} +4:3 @var{file2} -@end example - -@noindent -The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments -specify line numbers, or line and column numbers, for the next file -argument. These behave like the command line arguments for Emacs -itself. @xref{Action Arguments}. - - The other optional arguments recognized by @command{emacsclient} are -listed below: - -@table @samp -@item -a @var{command} -@itemx --alternate-editor=@var{command} -Specify a command to run if @code{emacsclient} fails to contact Emacs. -This is useful when running @code{emacsclient} in a script. - -As a special exception, if @var{command} is the empty string, then -@code{emacsclient} starts Emacs in daemon mode (as @command{emacs ---daemon}) and then tries connecting again. - -@cindex @env{ALTERNATE_EDITOR} environment variable -The environment variable @env{ALTERNATE_EDITOR} has the same effect as -the @samp{-a} option. If both are present, the latter takes -precedence. - -@cindex client frame -@item -c -Create a new graphical @dfn{client frame}, instead of using an -existing Emacs frame. See below for the special behavior of @kbd{C-x -C-c} in a client frame. If Emacs cannot create a new graphical frame -(e.g., if it cannot connect to the X server), it tries to create a -text terminal client frame, as though you had supplied the @samp{-t} -option instead. - -On MS-Windows, a single Emacs session cannot display frames on both -graphical and text terminals, nor on multiple text terminals. Thus, -if the Emacs server is running on a text terminal, the @samp{-c} -option, like the @samp{-t} option, creates a new frame in the server's -current text terminal. @xref{Windows Startup}. - -If you omit a filename argument while supplying the @samp{-c} option, -the new frame displays the @file{*scratch*} buffer by default. You -can customize this behavior with the variable @code{initial-buffer-choice} -(@pxref{Entering Emacs}). - -@item -F @var{alist} -@itemx --frame-parameters=@var{alist} -Set the parameters for a newly-created graphical frame -(@pxref{Frame Parameters}). - -@item -d @var{display} -@itemx --display=@var{display} -Tell Emacs to open the given files on the X display @var{display} -(assuming there is more than one X display available). - -@item -e -@itemx --eval -Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some -files. When this option is given, the arguments to -@command{emacsclient} are interpreted as a list of expressions to -evaluate, @emph{not} as a list of files to visit. - -@item -f @var{server-file} -@itemx --server-file=@var{server-file} -@cindex @env{EMACS_SERVER_FILE} environment variable -Specify a @dfn{server file} for connecting to an Emacs server via TCP. - -An Emacs server usually uses an operating system feature called a -``local socket'' to listen for connections. Some operating systems, -such as Microsoft Windows, do not support local sockets; in that case, -the server communicates with @command{emacsclient} via TCP. - -@vindex server-auth-dir -@cindex server file -@vindex server-port -When you start a TCP Emacs server, Emacs creates a @dfn{server file} -containing the TCP information to be used by @command{emacsclient} to -connect to the server. The variable @code{server-auth-dir} specifies -the directory containing the server file; by default, this is -@file{~/.emacs.d/server/}. To tell @command{emacsclient} to connect -to the server over TCP with a specific server file, use the @samp{-f} -or @samp{--server-file} option, or set the @env{EMACS_SERVER_FILE} -environment variable. - -@item -n -@itemx --no-wait -Let @command{emacsclient} exit immediately, instead of waiting until -all server buffers are finished. You can take as long as you like to -edit the server buffers within Emacs, and they are @emph{not} killed -when you type @kbd{C-x #} in them. - -@item --parent-id @var{id} -Open an @command{emacsclient} frame as a client frame in the parent X -window with id @var{id}, via the XEmbed protocol. Currently, this -option is mainly useful for developers. - -@item -q -@itemx --quiet -Do not let @command{emacsclient} display messages about waiting for -Emacs or connecting to remote server sockets. - -@item -s @var{server-name} -@itemx --socket-name=@var{server-name} -Connect to the Emacs server named @var{server-name}. The server name -is given by the variable @code{server-name} on the Emacs server. If -this option is omitted, @command{emacsclient} connects to the first -server it finds. (This option is not supported on MS-Windows.) - -@item -t -@itemx --tty -@itemx -nw -Create a new client frame on the current text terminal, instead of -using an existing Emacs frame. This behaves just like the @samp{-c} -option, described above, except that it creates a text terminal frame -(@pxref{Non-Window Terminals}). - -On MS-Windows, @samp{-t} behaves just like @samp{-c} if the Emacs -server is using the graphical display, but if the Emacs server is -running on a text terminal, it creates a new frame in the current text -terminal. -@end table - - The new graphical or text terminal frames created by the @samp{-c} -or @samp{-t} options are considered @dfn{client frames}. Any new -frame that you create from a client frame is also considered a client -frame. If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) -in a client frame, that command does not kill the Emacs session as it -normally does (@pxref{Exiting}). Instead, Emacs deletes the client -frame; furthermore, if the client frame has an @command{emacsclient} -waiting to regain control (i.e., if you did not supply the @samp{-n} -option), Emacs deletes all other frames of the same client, and marks -the client's server buffers as finished, as though you had typed -@kbd{C-x #} in all of them. If it so happens that there are no -remaining frames after the client frame(s) are deleted, the Emacs -session exits. - - As an exception, when Emacs is started as a daemon, all frames are -considered client frames, and @kbd{C-x C-c} never kills Emacs. To -kill a daemon session, type @kbd{M-x kill-emacs}. - - Note that the @samp{-t} and @samp{-n} options are contradictory: -@samp{-t} says to take control of the current text terminal to create -a new client frame, while @samp{-n} says not to take control of the -text terminal. If you supply both options, Emacs visits the specified -files(s) in an existing frame rather than a new client frame, negating -the effect of @samp{-t}. - -@node Printing -@section Printing Hard Copies -@cindex hardcopy -@cindex printing - - Emacs provides commands for printing hardcopies of either an entire -buffer or part of one. You can invoke the printing commands directly, -as detailed below, or using the @samp{File} menu on the menu bar. - -@findex htmlfontify-buffer - Aside from the commands described in this section, you can also -print hardcopies from Dired (@pxref{Operating on Files}) and the diary -(@pxref{Displaying the Diary}). You can also ``print'' an Emacs -buffer to HTML with the command @kbd{M-x htmlfontify-buffer}, which -converts the current buffer to a HTML file, replacing Emacs faces with -CSS-based markup. Furthermore, Org mode allows you to ``print'' Org -files to a variety of formats, such as PDF (@pxref{Org Mode}). - -@table @kbd -@item M-x print-buffer -Print hardcopy of current buffer with page headings containing the -file name and page number. -@item M-x lpr-buffer -Print hardcopy of current buffer without page headings. -@item M-x print-region -Like @code{print-buffer} but print only the current region. -@item M-x lpr-region -Like @code{lpr-buffer} but print only the current region. -@end table - -@findex print-buffer -@findex print-region -@findex lpr-buffer -@findex lpr-region -@vindex lpr-switches -@vindex lpr-commands - On most operating system, the above hardcopy commands submit files -for printing by calling the @command{lpr} program. To change the -printer program, customize the variable @code{lpr-command}. To -specify extra switches to give the printer program, customize the list -variable @code{lpr-switches}. Its value should be a list of option -strings, each of which should start with @samp{-} (e.g., the option -string @code{"-w80"} specifies a line width of 80 columns). The -default is the empty list, @code{nil}. - -@vindex printer-name -@vindex lpr-printer-switch - To specify the printer to use, set the variable @code{printer-name}. -The default, @code{nil}, specifies the default printer. If you set it -to a printer name (a string), that name is passed to @command{lpr} -with the @samp{-P} switch; if you are not using @command{lpr}, you -should specify the switch with @code{lpr-printer-switch}. - -@vindex lpr-headers-switches -@vindex lpr-add-switches - The variable @code{lpr-headers-switches} similarly specifies the -extra switches to use to make page headers. The variable -@code{lpr-add-switches} controls whether to supply @samp{-T} and -@samp{-J} options (suitable for @command{lpr}) to the printer program: -@code{nil} means don't add them (this should be the value if your -printer program is not compatible with @command{lpr}). - -@menu -* PostScript:: Printing buffers or regions as PostScript. -* PostScript Variables:: Customizing the PostScript printing commands. -* Printing Package:: An optional advanced printing interface. -@end menu - -@node PostScript -@subsection PostScript Hardcopy - - These commands convert buffer contents to PostScript, -either printing it or leaving it in another Emacs buffer. - -@table @kbd -@item M-x ps-print-buffer -Print hardcopy of the current buffer in PostScript form. -@item M-x ps-print-region -Print hardcopy of the current region in PostScript form. -@item M-x ps-print-buffer-with-faces -Print hardcopy of the current buffer in PostScript form, showing the -faces used in the text by means of PostScript features. -@item M-x ps-print-region-with-faces -Print hardcopy of the current region in PostScript form, showing the -faces used in the text. -@item M-x ps-spool-buffer -Generate and spool a PostScript image for the current buffer text. -@item M-x ps-spool-region -Generate and spool a PostScript image for the current region. -@item M-x ps-spool-buffer-with-faces -Generate and spool a PostScript image for the current buffer, showing the faces used. -@item M-x ps-spool-region-with-faces -Generate and spool a PostScript image for the current region, showing the faces used. -@item M-x ps-despool -Send the spooled PostScript to the printer. -@item M-x handwrite -Generate/print PostScript for the current buffer as if handwritten. -@end table - -@findex ps-print-region -@findex ps-print-buffer -@findex ps-print-region-with-faces -@findex ps-print-buffer-with-faces - The @code{ps-print-buffer} and @code{ps-print-region} commands print -buffer contents in PostScript form. One command prints the entire -buffer; the other, just the region. The commands -@code{ps-print-buffer-with-faces} and -@code{ps-print-region-with-faces} behave similarly, but use PostScript -features to show the faces (fonts and colors) of the buffer text. - - Interactively, when you use a prefix argument (@kbd{C-u}), the command -prompts the user for a file name, and saves the PostScript image in that file -instead of sending it to the printer. - -@findex ps-spool-region -@findex ps-spool-buffer -@findex ps-spool-region-with-faces -@findex ps-spool-buffer-with-faces - The commands whose names have @samp{spool} instead of @samp{print}, -generate the PostScript output in an Emacs buffer instead of sending -it to the printer. - -@findex ps-despool - Use the command @code{ps-despool} to send the spooled images to the -printer. This command sends the PostScript generated by -@samp{-spool-} commands (see commands above) to the printer. With a -prefix argument (@kbd{C-u}), it prompts for a file name, and saves the -spooled PostScript image in that file instead of sending it to the -printer. - -@findex handwrite -@cindex handwriting - @kbd{M-x handwrite} is more frivolous. It generates a PostScript -rendition of the current buffer as a cursive handwritten document. It -can be customized in group @code{handwrite}. This function only -supports ISO 8859-1 characters. - -@node PostScript Variables -@subsection Variables for PostScript Hardcopy - -@vindex ps-lpr-command -@vindex ps-lpr-switches -@vindex ps-printer-name - All the PostScript hardcopy commands use the variables -@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print -the output. @code{ps-lpr-command} specifies the command name to run, -@code{ps-lpr-switches} specifies command line options to use, and -@code{ps-printer-name} specifies the printer. If you don't set the -first two variables yourself, they take their initial values from -@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name} -is @code{nil}, @code{printer-name} is used. - -@vindex ps-print-header - The variable @code{ps-print-header} controls whether these commands -add header lines to each page---set it to @code{nil} to turn headers -off. - -@cindex color emulation on black-and-white printers -@vindex ps-print-color-p - If your printer doesn't support colors, you should turn off color -processing by setting @code{ps-print-color-p} to @code{nil}. By -default, if the display supports colors, Emacs produces hardcopy output -with color information; on black-and-white printers, colors are emulated -with shades of gray. This might produce illegible output, even if your -screen colors only use shades of gray. - - Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to -print colors on black/white printers. - -@vindex ps-use-face-background - By default, PostScript printing ignores the background colors of the -faces, unless the variable @code{ps-use-face-background} is -non-@code{nil}. This is to avoid unwanted interference with the zebra -stripes and background image/text. - -@vindex ps-paper-type -@vindex ps-page-dimensions-database - The variable @code{ps-paper-type} specifies which size of paper to -format for; legitimate values include @code{a4}, @code{a3}, -@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger}, -@code{legal}, @code{letter}, @code{letter-small}, @code{statement}, -@code{tabloid}. The default is @code{letter}. You can define -additional paper sizes by changing the variable -@code{ps-page-dimensions-database}. - -@vindex ps-landscape-mode - The variable @code{ps-landscape-mode} specifies the orientation of -printing on the page. The default is @code{nil}, which stands for -``portrait'' mode. Any non-@code{nil} value specifies ``landscape'' -mode. - -@vindex ps-number-of-columns - The variable @code{ps-number-of-columns} specifies the number of -columns; it takes effect in both landscape and portrait mode. The -default is 1. - -@vindex ps-font-family -@vindex ps-font-size -@vindex ps-font-info-database - The variable @code{ps-font-family} specifies which font family to use -for printing ordinary text. Legitimate values include @code{Courier}, -@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and -@code{Times}. The variable @code{ps-font-size} specifies the size of -the font for ordinary text. It defaults to 8.5 points. - -@vindex ps-multibyte-buffer -@cindex Intlfonts for PostScript printing -@cindex fonts for PostScript printing - Emacs supports more scripts and characters than a typical PostScript -printer. Thus, some of the characters in your buffer might not be -printable using the fonts built into your printer. You can augment -the fonts supplied with the printer with those from the GNU Intlfonts -package, or you can instruct Emacs to use Intlfonts exclusively. The -variable @code{ps-multibyte-buffer} controls this: the default value, -@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1 -characters; a value of @code{non-latin-printer} is for printers which -have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean -characters built into them. A value of @code{bdf-font} arranges for -the BDF fonts from the Intlfonts package to be used for @emph{all} -characters. Finally, a value of @code{bdf-font-except-latin} -instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1 -characters, and Intlfonts BDF fonts for the rest. - -@vindex bdf-directory-list - To be able to use the BDF fonts, Emacs needs to know where to find -them. The variable @code{bdf-directory-list} holds the list of -directories where Emacs should look for the fonts; the default value -includes a single directory @file{/usr/local/share/emacs/fonts/bdf}. - - Many other customization variables for these commands are defined and -described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}. - -@node Printing Package -@subsection Printing Package -@cindex Printing package - - The basic Emacs facilities for printing hardcopy can be extended -using the Printing package. This provides an easy-to-use interface -for choosing what to print, previewing PostScript files before -printing, and setting various printing options such as print headers, -landscape or portrait modes, duplex modes, and so forth. On GNU/Linux -or Unix systems, the Printing package relies on the @file{gs} and -@file{gv} utilities, which are distributed as part of the GhostScript -program. On MS-Windows, the @file{gstools} port of Ghostscript can be -used. - -@findex pr-interface - To use the Printing package, add @code{(require 'printing)} to your -init file (@pxref{Init File}), followed by @code{(pr-update-menus)}. -This function replaces the usual printing commands in the menu bar -with a @samp{Printing} submenu that contains various printing options. -You can also type @kbd{M-x pr-interface @key{RET}}; this creates a -@file{*Printing Interface*} buffer, similar to a customization buffer, -where you can set the printing options. After selecting what and how -to print, you start the print job using the @samp{Print} button (click -@kbd{Mouse-2} on it, or move point over it and type @key{RET}). For -further information on the various options, use the @samp{Interface -Help} button. - -@node Sorting -@section Sorting Text -@cindex sorting - - Emacs provides several commands for sorting text in the buffer. All -operate on the contents of the region. -They divide the text of the region into many @dfn{sort records}, -identify a @dfn{sort key} for each record, and then reorder the records -into the order determined by the sort keys. The records are ordered so -that their keys are in alphabetical order, or, for numeric sorting, in -numeric order. In alphabetic sorting, all upper-case letters @samp{A} -through @samp{Z} come before lower-case @samp{a}, in accordance with the -@acronym{ASCII} character sequence. - - The various sort commands differ in how they divide the text into sort -records and in which part of each record is used as the sort key. Most of -the commands make each line a separate sort record, but some commands use -paragraphs or pages as sort records. Most of the sort commands use each -entire sort record as its own sort key, but some use only a portion of the -record as the sort key. - -@findex sort-lines -@findex sort-paragraphs -@findex sort-pages -@findex sort-fields -@findex sort-numeric-fields -@vindex sort-numeric-base -@table @kbd -@item M-x sort-lines -Divide the region into lines, and sort by comparing the entire -text of a line. A numeric argument means sort into descending order. - -@item M-x sort-paragraphs -Divide the region into paragraphs, and sort by comparing the entire -text of a paragraph (except for leading blank lines). A numeric -argument means sort into descending order. - -@item M-x sort-pages -Divide the region into pages, and sort by comparing the entire -text of a page (except for leading blank lines). A numeric -argument means sort into descending order. - -@item M-x sort-fields -Divide the region into lines, and sort by comparing the contents of -one field in each line. Fields are defined as separated by -whitespace, so the first run of consecutive non-whitespace characters -in a line constitutes field 1, the second such run constitutes field -2, etc. - -Specify which field to sort by with a numeric argument: 1 to sort by -field 1, etc. A negative argument means count fields from the right -instead of from the left; thus, minus 1 means sort by the last field. -If several lines have identical contents in the field being sorted, they -keep the same relative order that they had in the original buffer. - -@item M-x sort-numeric-fields -Like @kbd{M-x sort-fields} except the specified field is converted -to an integer for each line, and the numbers are compared. @samp{10} -comes before @samp{2} when considered as text, but after it when -considered as a number. By default, numbers are interpreted according -to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or -@samp{0} are interpreted as hexadecimal and octal, respectively. - -@item M-x sort-columns -Like @kbd{M-x sort-fields} except that the text within each line -used for comparison comes from a fixed range of columns. See below -for an explanation. - -@findex reverse-region -@item M-x reverse-region -Reverse the order of the lines in the region. This is useful for -sorting into descending order by fields or columns, since those sort -commands do not have a feature for doing that. -@end table - - For example, if the buffer contains this: - -@smallexample -On systems where clash detection (locking of files being edited) is -implemented, Emacs also checks the first time you modify a buffer -whether the file has changed on disk since it was last visited or -saved. If it has, you are asked to confirm that you want to change -the buffer. -@end smallexample - -@noindent -applying @kbd{M-x sort-lines} to the entire buffer produces this: - -@smallexample -On systems where clash detection (locking of files being edited) is -implemented, Emacs also checks the first time you modify a buffer -saved. If it has, you are asked to confirm that you want to change -the buffer. -whether the file has changed on disk since it was last visited or -@end smallexample - -@noindent -where the upper-case @samp{O} sorts before all lower-case letters. If -you use @kbd{C-u 2 M-x sort-fields} instead, you get this: - -@smallexample -implemented, Emacs also checks the first time you modify a buffer -saved. If it has, you are asked to confirm that you want to change -the buffer. -On systems where clash detection (locking of files being edited) is -whether the file has changed on disk since it was last visited or -@end smallexample - -@noindent -where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, -@samp{systems} and @samp{the}. - -@findex sort-columns - @kbd{M-x sort-columns} requires more explanation. You specify the -columns by putting point at one of the columns and the mark at the other -column. Because this means you cannot put point or the mark at the -beginning of the first line of the text you want to sort, this command -uses an unusual definition of ``region'': all of the line point is in is -considered part of the region, and so is all of the line the mark is in, -as well as all the lines in between. - - For example, to sort a table by information found in columns 10 to 15, -you could put the mark on column 10 in the first line of the table, and -point on column 15 in the last line of the table, and then run -@code{sort-columns}. Equivalently, you could run it with the mark on -column 15 in the first line and point on column 10 in the last line. - - This can be thought of as sorting the rectangle specified by point and -the mark, except that the text on each line to the left or right of the -rectangle moves along with the text inside the rectangle. -@xref{Rectangles}. - -@vindex sort-fold-case - Many of the sort commands ignore case differences when comparing, if -@code{sort-fold-case} is non-@code{nil}. - -@c Picture Mode documentation -@ifnottex -@include picture-xtra.texi -@end ifnottex - - -@node Editing Binary Files -@section Editing Binary Files - -@cindex Hexl mode -@cindex mode, Hexl -@cindex editing binary files -@cindex hex editing - There is a special major mode for editing binary files: Hexl mode. To -use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit -the file. This command converts the file's contents to hexadecimal and -lets you edit the translation. When you save the file, it is converted -automatically back to binary. - - You can also use @kbd{M-x hexl-mode} to translate an existing buffer -into hex. This is useful if you visit a file normally and then discover -it is a binary file. - - Ordinary text characters overwrite in Hexl mode. This is to reduce -the risk of accidentally spoiling the alignment of data in the file. -There are special commands for insertion. Here is a list of the -commands of Hexl mode: - -@c I don't think individual index entries for these commands are useful--RMS. -@table @kbd -@item C-M-d -Insert a byte with a code typed in decimal. - -@item C-M-o -Insert a byte with a code typed in octal. - -@item C-M-x -Insert a byte with a code typed in hex. - -@item C-x [ -Move to the beginning of a 1k-byte ``page''. - -@item C-x ] -Move to the end of a 1k-byte ``page''. - -@item M-g -Move to an address specified in hex. - -@item M-j -Move to an address specified in decimal. - -@item C-c C-c -Leave Hexl mode, going back to the major mode this buffer had before you -invoked @code{hexl-mode}. -@end table - -@noindent -Other Hexl commands let you insert strings (sequences) of binary -bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a -hexl-@key{RET}} for details. - - -@node Saving Emacs Sessions -@section Saving Emacs Sessions -@cindex saving sessions -@cindex restore session -@cindex remember editing session -@cindex reload files -@cindex desktop - -@vindex desktop-restore-frames - Use the desktop library to save the state of Emacs from one session -to another. Once you save the Emacs @dfn{desktop}---the buffers, -their file names, major modes, buffer positions, and so on---then -subsequent Emacs sessions reload the saved desktop. By default, -the desktop also tries to save the frame and window configuration. -To disable this, set @code{desktop-restore-frames} to @code{nil}. -(See that variable's documentation for some related options -that you can customize to fine-tune this behavior.) - -@findex desktop-save -@vindex desktop-save-mode - You can save the desktop manually with the command @kbd{M-x -desktop-save}. You can also enable automatic saving of the desktop -when you exit Emacs, and automatic restoration of the last saved -desktop when Emacs starts: use the Customization buffer (@pxref{Easy -Customization}) to set @code{desktop-save-mode} to @code{t} for future -sessions, or add this line in your init file (@pxref{Init File}): - -@example -(desktop-save-mode 1) -@end example - -@vindex desktop-auto-save-timeout -@noindent -When @code{desktop-save-mode} is active and the desktop file exists, -Emacs auto-saves it every @code{desktop-auto-save-timeout} -seconds, if that is non-@code{nil} and non-zero. - -@findex desktop-change-dir -@findex desktop-revert -@vindex desktop-path - If you turn on @code{desktop-save-mode} in your init file, then when -Emacs starts, it looks for a saved desktop in the current directory. -(More precisely, it looks in the directories specified by -@var{desktop-path}, and uses the first desktop it finds.) -Thus, you can have separate saved desktops in different directories, -and the starting directory determines which one Emacs reloads. You -can save the current desktop and reload one saved in another directory -by typing @kbd{M-x desktop-change-dir}. Typing @kbd{M-x -desktop-revert} reverts to the desktop previously reloaded. - - Specify the option @samp{--no-desktop} on the command line when you -don't want it to reload any saved desktop. This turns off -@code{desktop-save-mode} for the current session. Starting Emacs with -the @samp{--no-init-file} option also disables desktop reloading, -since it bypasses the init file, where @code{desktop-save-mode} is -usually turned on. - -@vindex desktop-restore-eager - By default, all the buffers in the desktop are restored at one go. -However, this may be slow if there are a lot of buffers in the -desktop. You can specify the maximum number of buffers to restore -immediately with the variable @code{desktop-restore-eager}; the -remaining buffers are restored ``lazily'', when Emacs is idle. - -@findex desktop-clear -@vindex desktop-globals-to-clear -@vindex desktop-clear-preserve-buffers-regexp - Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills -all buffers except for internal ones, and clears the global variables -listed in @code{desktop-globals-to-clear}. If you want this to -preserve certain buffers, customize the variable -@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular -expression matching the names of buffers not to kill. - - If you want to save minibuffer history from one session to -another, use the @code{savehist} library. - -@node Recursive Edit -@section Recursive Editing Levels -@cindex recursive editing level -@cindex editing level, recursive - - A @dfn{recursive edit} is a situation in which you are using Emacs -commands to perform arbitrary editing while in the middle of another -Emacs command. For example, when you type @kbd{C-r} inside of a -@code{query-replace}, you enter a recursive edit in which you can change -the current buffer. On exiting from the recursive edit, you go back to -the @code{query-replace}. @xref{Query Replace}. - -@kindex C-M-c -@findex exit-recursive-edit -@cindex exiting recursive edit - @dfn{Exiting} the recursive edit means returning to the unfinished -command, which continues execution. The command to exit is @kbd{C-M-c} -(@code{exit-recursive-edit}). - - You can also @dfn{abort} the recursive edit. This is like exiting, -but also quits the unfinished command immediately. Use the command -@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}. - - The mode line shows you when you are in a recursive edit by displaying -square brackets around the parentheses that always surround the major and -minor mode names. Every window's mode line shows this in the same way, -since being in a recursive edit is true of Emacs as a whole rather than -any particular window or buffer. - - It is possible to be in recursive edits within recursive edits. For -example, after typing @kbd{C-r} in a @code{query-replace}, you may type a -command that enters the debugger. This begins a recursive editing level -for the debugger, within the recursive editing level for @kbd{C-r}. -Mode lines display a pair of square brackets for each recursive editing -level currently in progress. - - Exiting the inner recursive edit (such as with the debugger @kbd{c} -command) resumes the command running in the next level up. When that -command finishes, you can then use @kbd{C-M-c} to exit another recursive -editing level, and so on. Exiting applies to the innermost level only. -Aborting also gets out of only one level of recursive edit; it returns -immediately to the command level of the previous recursive edit. If you -wish, you can then abort the next recursive editing level. - - Alternatively, the command @kbd{M-x top-level} aborts all levels of -recursive edits, returning immediately to the top-level command -reader. It also exits the minibuffer, if it is active. - - The text being edited inside the recursive edit need not be the same text -that you were editing at top level. It depends on what the recursive edit -is for. If the command that invokes the recursive edit selects a different -buffer first, that is the buffer you will edit recursively. In any case, -you can switch buffers within the recursive edit in the normal manner (as -long as the buffer-switching keys have not been rebound). You could -probably do all the rest of your editing inside the recursive edit, -visiting files and all. But this could have surprising effects (such as -stack overflow) from time to time. So remember to exit or abort the -recursive edit when you no longer need it. - - In general, we try to minimize the use of recursive editing levels in -GNU Emacs. This is because they constrain you to ``go back'' in a -particular order---from the innermost level toward the top level. When -possible, we present different activities in separate buffers so that -you can switch between them as you please. Some commands switch to a -new major mode which provides a command to switch back. These -approaches give you more flexibility to go back to unfinished tasks in -the order you choose. - -@node Emulation -@section Emulation -@cindex emulating other editors -@cindex other editors -@cindex EDT -@cindex vi -@cindex PC key bindings -@cindex scrolling all windows -@cindex PC selection -@cindex Motif key bindings -@cindex Macintosh key bindings -@cindex WordStar - - GNU Emacs can be programmed to emulate (more or less) some other -editors. Standard facilities can emulate these: - -@table @asis -@item CRiSP/Brief (PC editor) -@findex crisp-mode -@vindex crisp-override-meta-x -@findex scroll-all-mode -@cindex CRiSP mode -@cindex Brief emulation -@cindex emulation of Brief -@cindex mode, CRiSP -@kbd{M-x crisp-mode} enables key bindings to emulate the CRiSP/Brief -editor. Note that this rebinds @kbd{M-x} to exit Emacs unless you set -the variable @code{crisp-override-meta-x}. You can also use the -command @kbd{M-x scroll-all-mode} or set the variable -@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature -(scrolling all windows together). - -@item EDT (DEC VMS editor) -@findex edt-emulation-on -@findex edt-emulation-off -Turn on EDT emulation with @kbd{M-x edt-emulation-on}; restore normal -command bindings with @kbd{M-x edt-emulation-off}. - -Most of the EDT emulation commands are keypad keys, and most standard -Emacs key bindings are still available. The EDT emulation rebindings -are done in the global keymap, so there is no problem switching -buffers or major modes while in EDT emulation. - -@item TPU (DEC VMS editor) -@findex tpu-edt-on -@cindex TPU -@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT. - -@item vi (Berkeley editor) -@findex viper-mode -Viper is the newest emulator for vi. It implements several levels of -emulation; level 1 is closest to vi itself, while level 5 departs -somewhat from strict emulation to take advantage of the capabilities of -Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you -the rest of the way and ask for the emulation level. @inforef{Top, -Viper, viper}. - -@item vi (another emulator) -@findex vi-mode -@kbd{M-x vi-mode} enters a major mode that replaces the previously -established major mode. All of the vi commands that, in real vi, enter -``input'' mode are programmed instead to return to the previous major -mode. Thus, ordinary Emacs serves as vi's ``input'' mode. - -Because vi emulation works through major modes, it does not work -to switch buffers during emulation. Return to normal Emacs first. - -If you plan to use vi emulation much, you probably want to bind a key -to the @code{vi-mode} command. - -@item vi (alternate emulator) -@findex vip-mode -@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi -more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator -is changed from ordinary Emacs so you can use @key{ESC} to go back to -emulated vi command mode. To get from emulated vi command mode back to -ordinary Emacs, type @kbd{C-z}. - -This emulation does not work through major modes, and it is possible -to switch buffers in various ways within the emulator. It is not -so necessary to assign a key to the command @code{vip-mode} as -it is with @code{vi-mode} because terminating insert mode does -not use it. - -@inforef{Top, VIP, vip}, for full information. - -@item WordStar (old wordprocessor) -@findex wordstar-mode -@kbd{M-x wordstar-mode} provides a major mode with WordStar-like -key bindings. -@end table - -@node Hyperlinking -@section Hyperlinking and Navigation Features - - The following subsections describe convenience features for handling -URLs and other types of links occurring in Emacs buffer text. - -@menu -* Browse-URL:: Following URLs. -* Goto Address mode:: Activating URLs. -* FFAP:: Finding files etc. at point. -@end menu - -@node Browse-URL -@subsection Following URLs -@cindex World Wide Web -@cindex Web -@findex browse-url -@findex browse-url-at-point -@findex browse-url-at-mouse -@cindex Browse-URL -@cindex URLs - -@table @kbd -@item M-x browse-url @key{RET} @var{url} @key{RET} -Load a URL into a Web browser. -@end table - - The Browse-URL package allows you to easily follow URLs from within -Emacs. Most URLs are followed by invoking a web browser; -@samp{mailto:} URLs are followed by invoking the @code{compose-mail} -Emacs command to send mail to the specified address (@pxref{Sending -Mail}). - - The command @kbd{M-x browse-url} prompts for a URL, and follows it. -If point is located near a plausible URL, that URL is offered as the -default. The Browse-URL package also provides other commands which -you might like to bind to keys, such as @code{browse-url-at-point} and -@code{browse-url-at-mouse}. - -@vindex browse-url-mailto-function -@vindex browse-url-browser-function - You can customize Browse-URL's behavior via various options in the -@code{browse-url} Customize group. In particular, the option -@code{browse-url-mailto-function} lets you define how to follow -@samp{mailto:} URLs, while @code{browse-url-browser-function} lets you -define how to follow other types of URLs. For more information, view -the package commentary by typing @kbd{C-h P browse-url @key{RET}}. - -@node Goto Address mode -@subsection Activating URLs -@findex goto-address-mode -@cindex mode, Goto Address -@cindex Goto Address mode -@cindex URLs, activating - -@table @kbd -@item M-x goto-address-mode -Activate URLs and e-mail addresses in the current buffer. -@end table - -@kindex C-c RET @r{(Goto Address mode)} -@findex goto-address-at-point - You can make Emacs mark out URLs specially in the current buffer, by -typing @kbd{M-x goto-address-mode}. When this buffer-local minor mode -is enabled, it finds all the URLs in the buffer, highlights them, and -turns them into clickable buttons. You can follow the URL by typing -@kbd{C-c @key{RET}} (@code{goto-address-at-point}) while point is on -its text; or by clicking with @kbd{Mouse-2}, or by clicking -@kbd{Mouse-1} quickly (@pxref{Mouse References}). Following a URL is -done by calling @code{browse-url} as a subroutine -(@pxref{Browse-URL}). - - It can be useful to add @code{goto-address-mode} to mode hooks and -hooks for displaying an incoming message -(e.g., @code{rmail-show-message-hook} for Rmail, and -@code{mh-show-mode-hook} for MH-E). This is not needed for Gnus, -which has a similar feature of its own. - -@node FFAP -@subsection Finding Files and URLs at Point -@findex find-file-at-point -@findex ffap -@findex dired-at-point -@findex ffap-next -@findex ffap-menu -@cindex finding file at point - - The FFAP package replaces certain key bindings for finding files, -such as @kbd{C-x C-f}, with commands that provide more sensitive -defaults. These commands behave like the ordinary ones when given a -prefix argument. Otherwise, they get the default file name or URL -from the text around point. If what is found in the buffer has the -form of a URL rather than a file name, the commands use -@code{browse-url} to view it (@pxref{Browse-URL}). - - This feature is useful for following references in mail or news -buffers, @file{README} files, @file{MANIFEST} files, and so on. For -more information, view the package commentary by typing @kbd{C-h P -ffap @key{RET}}. - -@cindex FFAP minor mode -@findex ffap-mode - To enable FFAP, type @kbd{M-x ffap-bindings}. This makes the -following key bindings, and also installs hooks for additional FFAP -functionality in Rmail, Gnus and VM article buffers. - -@table @kbd -@item C-x C-f @var{filename} @key{RET} -@kindex C-x C-f @r{(FFAP)} -Find @var{filename}, guessing a default from text around point -(@code{find-file-at-point}). -@item C-x C-r -@kindex C-x C-r @r{(FFAP)} -@code{ffap-read-only}, analogous to @code{find-file-read-only}. -@item C-x C-v -@kindex C-x C-v @r{(FFAP)} -@code{ffap-alternate-file}, analogous to @code{find-alternate-file}. -@item C-x d @var{directory} @key{RET} -@kindex C-x d @r{(FFAP)} -Start Dired on @var{directory}, defaulting to the directory name at -point (@code{dired-at-point}). -@item C-x C-d -@code{ffap-list-directory}, analogous to @code{list-directory}. -@item C-x 4 f -@kindex C-x 4 f @r{(FFAP)} -@code{ffap-other-window}, analogous to @code{find-file-other-window}. -@item C-x 4 r -@code{ffap-read-only-other-window}, analogous to -@code{find-file-read-only-other-window}. -@item C-x 4 d -@code{ffap-dired-other-window}, like @code{dired-other-window}. -@item C-x 5 f -@kindex C-x 5 f @r{(FFAP)} -@code{ffap-other-frame}, analogous to @code{find-file-other-frame}. -@item C-x 5 r -@code{ffap-read-only-other-frame}, analogous to -@code{find-file-read-only-other-frame}. -@item C-x 5 d -@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}. -@item M-x ffap-next -Search buffer for next file name or URL, then find that file or URL. -@item S-Mouse-3 -@kindex S-Mouse-3 @r{(FFAP)} -@code{ffap-at-mouse} finds the file guessed from text around the position -of a mouse click. -@item C-S-Mouse-3 -@kindex C-S-Mouse-3 @r{(FFAP)} -Display a menu of files and URLs mentioned in current buffer, then -find the one you select (@code{ffap-menu}). -@end table - -@node Amusements -@section Other Amusements -@cindex boredom - -@findex animate-birthday-present -@cindex animate - The @code{animate} package makes text dance (e.g., @kbd{M-x -animate-birthday-present}). - -@findex blackbox -@findex mpuz -@findex 5x5 -@cindex puzzles - @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles. -@code{blackbox} challenges you to determine the location of objects -inside a box by tomography. @code{mpuz} displays a multiplication -puzzle with letters standing for digits in a code that you must -guess---to guess a value, type a letter and then the digit you think it -stands for. The aim of @code{5x5} is to fill in all the squares. - -@findex bubbles - @kbd{M-x bubbles} is a game in which the object is to remove as many -bubbles as you can in the smallest number of moves. - -@findex decipher -@cindex ciphers -@cindex cryptanalysis - @kbd{M-x decipher} helps you to cryptanalyze a buffer which is -encrypted in a simple monoalphabetic substitution cipher. - -@findex dissociated-press - @kbd{M-x dissociated-press} scrambles the text in the current Emacs -buffer, word by word or character by character, writing its output to -a buffer named @file{*Dissociation*}. A positive argument tells it to -operate character by character, and specifies the number of overlap -characters. A negative argument tells it to operate word by word, and -specifies the number of overlap words. Dissociated Press produces -results fairly like those of a Markov chain, but is however, an -independent, ignoriginal invention; it techniquitously copies several -consecutive characters from the sample text between random jumps, -unlike a Markov chain which would jump randomly after each word or -character. Keep dissociwords out of your documentation, if you want -it to be well userenced and properbose. - -@findex dunnet - @kbd{M-x dunnet} runs an text-based adventure game. - -@findex gomoku -@cindex Go Moku - If you want a little more personal involvement, try @kbd{M-x gomoku}, -which plays the game Go Moku with you. - -@cindex tower of Hanoi -@findex hanoi - If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are -considerably bored, give it a numeric argument. If you are very, very -bored, try an argument of 9. Sit back and watch. - -@findex life -@cindex Life - @kbd{M-x life} runs Conway's ``Life'' cellular automaton. - -@findex landmark -@cindex landmark game - @kbd{M-x landmark} runs a relatively non-participatory game in which -a robot attempts to maneuver towards a tree at the center of the -window based on unique olfactory cues from each of the four -directions. - -@findex morse-region -@findex unmorse-region -@findex nato-region -@cindex Morse code -@cindex --/---/.-./.../. - @kbd{M-x morse-region} converts the text in the region to Morse -code; @kbd{M-x unmorse-region} converts it back. @kbd{M-x -nato-region} converts the text in the region to NATO phonetic -alphabet; @kbd{M-x denato-region} converts it back. - -@findex pong -@cindex Pong game -@findex tetris -@cindex Tetris -@findex snake -@cindex Snake - @kbd{M-x pong}, @kbd{M-x snake} and @kbd{M-x tetris} are -implementations of the well-known Pong, Snake and Tetris games. - -@findex solitaire -@cindex solitaire - @kbd{M-x solitaire} plays a game of solitaire in which you jump pegs -across other pegs. - -@findex zone - The command @kbd{M-x zone} plays games with the display when Emacs -is idle. - -@findex doctor -@cindex Eliza - Finally, if you find yourself frustrated, try describing your -problems to the famous psychotherapist Eliza. Just do @kbd{M-x -doctor}. End each input by typing @key{RET} twice. - -@ifnottex -@lowersections -@end ifnottex diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi deleted file mode 100644 index b21be99e16c..00000000000 --- a/doc/emacs/modes.texi +++ /dev/null @@ -1,449 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Modes -@chapter Major and Minor Modes - - Emacs contains many @dfn{editing modes} that alter its basic -behavior in useful ways. These are divided into @dfn{major modes} and -@dfn{minor modes}. - - Major modes provide specialized facilities for working on a -particular file type, such as a C source file (@pxref{Programs}), or a -particular type of non-file buffer, such as a shell buffer -(@pxref{Shell}). Major modes are mutually exclusive; each buffer has -one and only one major mode at any time. - - Minor modes are optional features which you can turn on or off, not -necessarily specific to a type of file or buffer. For example, Auto -Fill mode is a minor mode in which @key{SPC} breaks lines between -words as you type (@pxref{Auto Fill}). Minor modes are independent of -one another, and of the selected major mode. - -@menu -* Major Modes:: Text mode vs. Lisp mode vs. C mode... -* Minor Modes:: Each minor mode is a feature you can turn on - independently of any others. -* Choosing Modes:: How modes are chosen when visiting files. -@end menu - -@node Major Modes -@section Major Modes -@cindex major modes -@cindex mode, major -@kindex TAB @r{(and major modes)} -@kindex DEL @r{(and major modes)} -@kindex C-j @r{(and major modes)} - - Every buffer possesses a major mode, which determines the editing -behavior of Emacs while that buffer is current. The mode line -normally shows the name of the current major mode, in parentheses -(@pxref{Mode Line}). - - The least specialized major mode is called @dfn{Fundamental mode}. -This mode has no mode-specific redefinitions or variable settings, so -that each Emacs command behaves in its most general manner, and each -user option variable is in its default state. - - For editing text of a specific type that Emacs knows about, such as -Lisp code or English text, you typically use a more specialized major -mode, such as Lisp mode or Text mode. Most major modes fall into -three major groups. The first group contains modes for normal text, -either plain or with mark-up. It includes Text mode, HTML mode, SGML -mode, @TeX{} mode and Outline mode. The second group contains modes -for specific programming languages. These include Lisp mode (which -has several variants), C mode, Fortran mode, and others. The third -group consists of major modes that are not associated directly with -files; they are used in buffers created for specific purposes by -Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), -Message mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), -and Shell mode for buffers used to communicate with an inferior shell -process (@pxref{Interactive Shell}). - - Usually, the major mode is automatically set by Emacs, when you -first visit a file or create a buffer (@pxref{Choosing Modes}). You -can explicitly select a new major mode by using an @kbd{M-x} command. -Take the name of the mode and add @code{-mode} to get the name of the -command to select that mode (e.g., @kbd{M-x lisp-mode} enters Lisp mode). - -@vindex major-mode - The value of the buffer-local variable @code{major-mode} is a symbol -with the same name as the major mode command (e.g., @code{lisp-mode}). -This variable is set automatically; you should not change it yourself. - - The default value of @code{major-mode} determines the major mode to -use for files that do not specify a major mode, and for new buffers -created with @kbd{C-x b}. Normally, this default value is the symbol -@code{fundamental-mode}, which specifies Fundamental mode. You can -change this default value via the Customization interface (@pxref{Easy -Customization}), or by adding a line like this to your init file -(@pxref{Init File}): - -@example -(setq-default major-mode 'text-mode) -@end example - -@noindent -If the default value of @code{major-mode} is @code{nil}, the major -mode is taken from the previously current buffer. - - Specialized major modes often change the meanings of certain keys to -do something more suitable for the mode. For instance, programming -language modes bind @key{TAB} to indent the current line according to -the rules of the language (@pxref{Indentation}). The keys that are -commonly changed are @key{TAB}, @key{DEL}, and @kbd{C-j}. Many modes -also define special commands of their own, usually bound in the prefix -key @kbd{C-c}. Major modes can also alter user options and variables; -for instance, programming language modes typically set a buffer-local -value for the variable @code{comment-start}, which determines how -source code comments are delimited (@pxref{Comments}). - -@findex describe-mode -@kindex C-h m - To view the documentation for the current major mode, including a -list of its key bindings, type @code{C-h m} (@code{describe-mode}). - -@cindex mode hook -@vindex text-mode-hook -@vindex prog-mode-hook - Every major mode, apart from Fundamental mode, defines a @dfn{mode -hook}, a customizable list of Lisp functions to run each time the mode -is enabled in a buffer. @xref{Hooks}, for more information about -hooks. Each mode hook is named after its major mode, e.g., Fortran -mode has @code{fortran-mode-hook}. Furthermore, all text-based major -modes run @code{text-mode-hook}, and all programming language modes -run @code{prog-mode-hook}, prior to running their own mode hooks. -Hook functions can look at the value of the variable @code{major-mode} -to see which mode is actually being entered. - - Mode hooks are commonly used to enable minor modes (@pxref{Minor -Modes}). For example, you can put the following lines in your init -file to enable Flyspell minor mode in all text-based major modes -(@pxref{Spelling}), and Eldoc minor mode in Emacs Lisp mode -(@pxref{Lisp Doc}): - -@example -(add-hook 'text-mode-hook 'flyspell-mode) -(add-hook 'emacs-lisp-mode-hook 'eldoc-mode) -@end example - -@node Minor Modes -@section Minor Modes -@cindex minor modes -@cindex mode, minor - - A minor mode is an optional editing mode that alters the behavior of -Emacs in some well-defined way. Unlike major modes, any number of -minor modes can be in effect at any time. Some minor modes are -@dfn{buffer-local}, and can be turned on (enabled) in certain buffers -and off (disabled) in others. Other minor modes are @dfn{global}: -while enabled, they affect everything you do in the Emacs session, in -all buffers. Most minor modes are disabled by default, but a few are -enabled by default. - - Most buffer-local minor modes say in the mode line when they are -enabled, just after the major mode indicator. For example, -@samp{Fill} in the mode line means that Auto Fill mode is enabled. -@xref{Mode Line}. - -@cindex mode commands for minor modes - Like major modes, each minor mode is associated with a @dfn{mode -command}, whose name consists of the mode name followed by -@samp{-mode}. For instance, the mode command for Auto Fill mode is -@code{auto-fill-mode}. But unlike a major mode command, which simply -enables the mode, the mode command for a minor mode can either enable -or disable it: - -@itemize -@item -If you invoke the mode command directly with no prefix argument -(either via @kbd{M-x}, or by binding it to a key and typing that key; -@pxref{Key Bindings}), that @dfn{toggles} the minor mode. The minor -mode is turned on if it was off, and turned off if it was on. - -@item -If you invoke the mode command with a prefix argument, the minor mode -is unconditionally turned off if that argument is zero or negative; -otherwise, it is unconditionally turned on. - -@item -If the mode command is called via Lisp, the minor mode is -unconditionally turned on if the argument is omitted or @code{nil}. -This makes it easy to turn on a minor mode from a major mode's mode -hook (@pxref{Major Modes}). A non-@code{nil} argument is handled like -an interactive prefix argument, as described above. -@end itemize - - Most minor modes also have a @dfn{mode variable}, with the same name -as the mode command. Its value is non-@code{nil} if the mode is -enabled, and @code{nil} if it is disabled. In general, you should not -try to enable or disable the mode by changing the value of the mode -variable directly in Lisp; you should run the mode command instead. -However, setting the mode variable through the Customize interface -(@pxref{Easy Customization}) will always properly enable or disable -the mode, since Customize automatically runs the mode command for you. - - The following is a list of some buffer-local minor modes: - -@itemize @bullet -@item -Abbrev mode automatically expands text based on pre-defined -abbreviation definitions. @xref{Abbrevs}. - -@item -Auto Fill mode inserts newlines as you type to prevent lines from -becoming too long. @xref{Filling}. - -@item -Auto Save mode saves the buffer contents periodically to reduce the -amount of work you can lose in case of a crash. @xref{Auto Save}. - -@item -Enriched mode enables editing and saving of formatted text. -@xref{Enriched Text}. - -@item -Flyspell mode automatically highlights misspelled words. -@xref{Spelling}. - -@item -Font-Lock mode automatically highlights certain textual units found in -programs. It is enabled globally by default, but you can disable it -in individual buffers. @xref{Faces}. - -@findex linum-mode -@cindex Linum mode -@item -Linum mode displays each line's line number in the window's left margin. - -@item -Outline minor mode provides similar facilities to the major mode -called Outline mode. @xref{Outline Mode}. - -@cindex Overwrite mode -@cindex mode, Overwrite -@findex overwrite-mode -@kindex INSERT -@item -Overwrite mode causes ordinary printing characters to replace existing -text instead of shoving it to the right. For example, if point is in -front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing -a @kbd{G} changes it to @samp{FOOGAR}, instead of producing -@samp{FOOGBAR} as usual. In Overwrite mode, the command @kbd{C-q} -inserts the next character whatever it may be, even if it is a -digit---this gives you a way to insert a character instead of -replacing an existing character. The mode command, -@code{overwrite-mode}, is bound to the @key{Insert} key. - -@findex binary-overwrite-mode -@item -Binary Overwrite mode is a variant of Overwrite mode for editing -binary files; it treats newlines and tabs like other characters, so -that they overwrite other characters and can be overwritten by them. -In Binary Overwrite mode, digits after @kbd{C-q} specify an octal -character code, as usual. - -@item -Visual Line mode performs ``word wrapping'', causing long lines to be -wrapped at word boundaries. @xref{Visual Line Mode}. -@end itemize - -@noindent -And here are some useful global minor modes: - -@itemize @bullet -@item -Column Number mode enables display of the current column number in the -mode line. @xref{Mode Line}. - -@item -Delete Selection mode causes text insertion to first delete the text -in the region, if the region is active. @xref{Using Region}. - -@item -Icomplete mode displays an indication of available completions when -you are in the minibuffer and completion is active. @xref{Icomplete}. - -@item -Line Number mode enables display of the current line number in the -mode line. It is enabled by default. @xref{Mode Line}. - -@item -Menu Bar mode gives each frame a menu bar. It is enabled by default. -@xref{Menu Bars}. - -@item -Scroll Bar mode gives each window a scroll bar. It is enabled by -default, but the scroll bar is only displayed on graphical terminals. -@xref{Scroll Bars}. - -@item -Tool Bar mode gives each frame a tool bar. It is enabled by default, -but the tool bar is only displayed on graphical terminals. @xref{Tool -Bars}. - -@item -Transient Mark mode highlights the region, and makes many Emacs -commands operate on the region when the mark is active. It is enabled -by default. @xref{Mark}. -@end itemize - -@node Choosing Modes -@section Choosing File Modes - -@cindex choosing a major mode -@cindex choosing a minor mode -@vindex auto-mode-alist - When you visit a file, Emacs chooses a major mode automatically. -Normally, it makes the choice based on the file name---for example, -files whose names end in @samp{.c} are normally edited in C mode---but -sometimes it chooses the major mode based on special text in the file. -This special text can also be used to enable buffer-local minor modes. - - Here is the exact procedure: - - First, Emacs checks whether the file contains file-local mode -variables. @xref{File Variables}. If there is a file-local variable -that specifies a major mode, then Emacs uses that major mode, ignoring -all other criteria. There are several methods to specify a major mode -using a file-local variable; the simplest is to put the mode name in -the first nonblank line, preceded and followed by @samp{-*-}. Other -text may appear on the line as well. For example, - -@example -; -*-Lisp-*- -@end example - -@noindent -tells Emacs to use Lisp mode. Note how the semicolon is used to make -Lisp treat this line as a comment. You could equivalently write - -@example -; -*- mode: Lisp;-*- -@end example - -@noindent -You can also use file-local variables to specify buffer-local minor -modes, by using @code{eval} specifications. For example, this first -nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode: - -@example -; -*- mode: Lisp; eval: (auto-fill-mode 1); -*- -@end example - -@noindent -Note, however, that it is usually inappropriate to enable minor modes -this way, since most minor modes represent individual user -preferences. If you personally want to use a minor mode for a -particular file type, it is better to enable the minor mode via a -major mode hook (@pxref{Major Modes}). - -@vindex interpreter-mode-alist - Second, if there is no file variable specifying a major mode, Emacs -checks whether the file's contents begin with @samp{#!}. If so, that -indicates that the file can serve as an executable shell command, -which works by running an interpreter named on the file's first line -(the rest of the file is used as input to the interpreter). -Therefore, Emacs tries to use the interpreter name to choose a mode. -For instance, a file that begins with @samp{#!/usr/bin/perl} is opened -in Perl mode. The variable @code{interpreter-mode-alist} specifies -the correspondence between interpreter program names and major modes. - - When the first line starts with @samp{#!}, you usually cannot use -the @samp{-*-} feature on the first line, because the system would get -confused when running the interpreter. So Emacs looks for @samp{-*-} -on the second line in such files as well as on the first line. The -same is true for man pages which start with the magic string -@samp{'\"} to specify a list of troff preprocessors. - -@vindex magic-mode-alist - Third, Emacs tries to determine the major mode by looking at the -text at the start of the buffer, based on the variable -@code{magic-mode-alist}. By default, this variable is @code{nil} (an -empty list), so Emacs skips this step; however, you can customize it -in your init file (@pxref{Init File}). The value should be a list of -elements of the form - -@example -(@var{regexp} . @var{mode-function}) -@end example - -@noindent -where @var{regexp} is a regular expression (@pxref{Regexps}), and -@var{mode-function} is a major mode command. If the text at the -beginning of the file matches @var{regexp}, Emacs chooses the major -mode specified by @var{mode-function}. - -Alternatively, an element of @code{magic-mode-alist} may have the form - -@example -(@var{match-function} . @var{mode-function}) -@end example - -@noindent -where @var{match-function} is a Lisp function that is called at the -beginning of the buffer; if the function returns non-@code{nil}, Emacs -set the major mode with @var{mode-function}. - - Fourth---if Emacs still hasn't found a suitable major mode---it -looks at the file's name. The correspondence between file names and -major modes is controlled by the variable @code{auto-mode-alist}. Its -value is a list in which each element has this form, - -@example -(@var{regexp} . @var{mode-function}) -@end example - -@noindent -or this form, - -@example -(@var{regexp} @var{mode-function} @var{flag}) -@end example - -@noindent -For example, one element normally found in the list has the form -@code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C -mode for files whose names end in @file{.c}. (Note that @samp{\\} is -needed in Lisp syntax to include a @samp{\} in the string, which must -be used to suppress the special meaning of @samp{.} in regexps.) If -the element has the form @code{(@var{regexp} @var{mode-function} -@var{flag})} and @var{flag} is non-@code{nil}, then after calling -@var{mode-function}, Emacs discards the suffix that matched -@var{regexp} and searches the list again for another match. - -@vindex auto-mode-case-fold - On GNU/Linux and other systems with case-sensitive file names, Emacs -performs a case-sensitive search through @code{auto-mode-alist}; if -this search fails, it performs a second case-insensitive search -through the alist. To suppress the second search, change the variable -@code{auto-mode-case-fold} to @code{nil}. On systems with -case-insensitive file names, such as Microsoft Windows, Emacs performs -a single case-insensitive search through @code{auto-mode-alist}. - -@vindex magic-fallback-mode-alist - Finally, if Emacs @emph{still} hasn't found a major mode to use, it -compares the text at the start of the buffer to the variable -@code{magic-fallback-mode-alist}. This variable works like -@code{magic-mode-alist}, described above, except that is consulted -only after @code{auto-mode-alist}. By default, -@code{magic-fallback-mode-alist} contains forms that check for image -files, HTML/XML/SGML files, and PostScript files. - -@findex normal-mode - If you have changed the major mode of a buffer, you can return to -the major mode Emacs would have chosen automatically, by typing -@kbd{M-x normal-mode}. This is the same function that -@code{find-file} calls to choose the major mode. It also processes -the file's @samp{-*-} line or local variables list (if any). -@xref{File Variables}. - -@vindex change-major-mode-with-file-name - The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to -a new major mode if the new file name implies a mode (@pxref{Saving}). -(@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) -However, this does not happen if the buffer contents specify a major -mode, and certain ``special'' major modes do not allow the mode to -change. You can turn off this mode-changing feature by setting -@code{change-major-mode-with-file-name} to @code{nil}. diff --git a/doc/emacs/msdog-xtra.texi b/doc/emacs/msdog-xtra.texi deleted file mode 100644 index 876be52282a..00000000000 --- a/doc/emacs/msdog-xtra.texi +++ /dev/null @@ -1,620 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node MS-DOS -@section Emacs and MS-DOS -@cindex MS-DOG -@cindex MS-DOS peculiarities - - This section briefly describes the peculiarities of using Emacs on -the MS-DOS ``operating system'' (also known as ``MS-DOG''). -@iftex -Information about Emacs and Microsoft's current operating system -Windows (also known as ``Losedows'') is in the main Emacs manual -(@pxref{Microsoft Windows,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -Information about peculiarities common to MS-DOS and Microsoft's -current operating systems Windows (also known as ``Losedows'') is in -@ref{Microsoft Windows}. -@end ifnottex - - If you build Emacs for MS-DOS, the binary will also run on Windows -3.X, Windows NT, Windows 9X/ME, Windows 2000/XP, or OS/2 as a DOS -application; all of this chapter applies for all of those systems, if -you use an Emacs that was built for MS-DOS. - -@iftex - @xref{Text and Binary,,,emacs, the Emacs Manual}, for information -@end iftex -@ifnottex - @xref{Text and Binary}, for information -@end ifnottex -about Emacs's special handling of text files under MS-DOS (and Windows). - -@menu -* Keyboard: MS-DOS Keyboard. Keyboard conventions on MS-DOS. -* Mouse: MS-DOS Mouse. Mouse conventions on MS-DOS. -* Display: MS-DOS Display. Fonts, frames and display size on MS-DOS. -* Files: MS-DOS File Names. File name conventions on MS-DOS. -* Printing: MS-DOS Printing. Printing specifics on MS-DOS. -* I18N: MS-DOS and MULE. Support for internationalization on MS-DOS. -* Processes: MS-DOS Processes. Running subprocesses on MS-DOS. -@end menu - -@node MS-DOS Keyboard -@subsection Keyboard Usage on MS-DOS - -@kindex DEL @r{(MS-DOS)} -@kindex BS @r{(MS-DOS)} - The key that is called @key{DEL} in Emacs (because that's how it is -designated on most workstations) is known as @key{BS} (backspace) on a -PC@. That is why the PC-specific terminal initialization remaps the -@key{BS} key to act as @key{DEL}; the @key{Delete} key is remapped to act -as @kbd{C-d} for the same reasons. - -@kindex C-g @r{(MS-DOS)} -@kindex C-Break @r{(MS-DOS)} -@cindex quitting on MS-DOS - Emacs built for MS-DOS recognizes @kbd{C-@key{Break}} as a quit -character, just like @kbd{C-g}. This is because Emacs cannot detect -that you have typed @kbd{C-g} until it is ready for more input. As a -consequence, you cannot use @kbd{C-g} to stop a running command -@iftex -(@pxref{Quitting,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Quitting}). -@end ifnottex -By contrast, @kbd{C-@key{Break}} @emph{is} detected as soon as you -type it (as @kbd{C-g} is on other systems), so it can be used to stop -a running command and for emergency escape -@iftex -(@pxref{Emergency Escape,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Emergency Escape}). -@end ifnottex - -@cindex Meta (under MS-DOS) -@cindex Hyper (under MS-DOS) -@cindex Super (under MS-DOS) -@vindex dos-super-key -@vindex dos-hyper-key - The PC keyboard maps use the left @key{Alt} key as the @key{META} key. -You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: -choose either the right @key{Ctrl} key or the right @key{Alt} key by -setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 -or 2 respectively. If neither @code{dos-super-key} nor -@code{dos-hyper-key} is 1, then by default the right @key{Alt} key is -also mapped to the @key{META} key. However, if the MS-DOS international -keyboard support program @file{KEYB.COM} is installed, Emacs will -@emph{not} map the right @key{Alt} to @key{META}, since it is used for -accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard -layouts; in this case, you may only use the left @key{Alt} as @key{META} -key. - -@kindex C-j @r{(MS-DOS)} -@vindex dos-keypad-mode - The variable @code{dos-keypad-mode} is a flag variable that controls -what key codes are returned by keys in the numeric keypad. You can also -define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the -following line into your @file{_emacs} file: - -@smallexample -;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.} -(define-key function-key-map [kp-enter] [?\C-j]) -@end smallexample - -@node MS-DOS Mouse -@subsection Mouse Usage on MS-DOS - -@cindex mouse support under MS-DOS - Emacs on MS-DOS supports a mouse (on the default terminal only). -The mouse commands work as documented, including those that use menus -and the menu bar -@iftex -(@pxref{Menu Bar,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Menu Bar}). -@end ifnottex - Scroll bars don't work in MS-DOS Emacs. PC mice usually have only -two buttons; these act as @kbd{Mouse-1} and @kbd{Mouse-2}, but if you -press both of them together, that has the effect of @kbd{Mouse-3}. If -the mouse does have 3 buttons, Emacs detects that at startup, and all -the 3 buttons function normally, as on X. - - Help strings for menu-bar and pop-up menus are displayed in the echo -area when the mouse pointer moves across the menu items. Highlighting -of mouse-sensitive text -@iftex -(@pxref{Mouse References,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Mouse References}) -@end ifnottex -is also supported. - -@cindex mouse, set number of buttons -@findex msdos-set-mouse-buttons - Some versions of mouse drivers don't report the number of mouse -buttons correctly. For example, mice with a wheel report that they -have 3 buttons, but only 2 of them are passed to Emacs; the clicks on -the wheel, which serves as the middle button, are not passed. In -these cases, you can use the @kbd{M-x msdos-set-mouse-buttons} command -to tell Emacs how many mouse buttons to expect. You could make such a -setting permanent by adding this fragment to your @file{_emacs} init -file: - -@example -;; @r{Treat the mouse like a 2-button mouse.} -(msdos-set-mouse-buttons 2) -@end example - -@cindex Windows clipboard support - Emacs built for MS-DOS supports clipboard operations when it runs on -Windows. Commands that put text on the kill ring, or yank text from -the ring, check the Windows clipboard first, just as Emacs does on the -X Window System -@iftex -(@pxref{Mouse Commands,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Mouse Commands}). -@end ifnottex -Only the primary selection and the cut buffer are supported by MS-DOS -Emacs on Windows; the secondary selection always appears as empty. - - Due to the way clipboard access is implemented by Windows, the -length of text you can put into the clipboard is limited by the amount -of free DOS memory that is available to Emacs. Usually, up to 620KB of -text can be put into the clipboard, but this limit depends on the system -configuration and is lower if you run Emacs as a subprocess of -another program. If the killed text does not fit, Emacs outputs a -message saying so, and does not put the text into the clipboard. - - Null characters also cannot be put into the Windows clipboard. If the -killed text includes null characters, Emacs does not put such text into -the clipboard, and displays in the echo area a message to that effect. - -@vindex dos-display-scancodes - The variable @code{dos-display-scancodes}, when non-@code{nil}, -directs Emacs to display the @acronym{ASCII} value and the keyboard scan code of -each keystroke; this feature serves as a complement to the -@code{view-lossage} command, for debugging. - -@node MS-DOS Display -@subsection Display on MS-DOS -@cindex faces under MS-DOS -@cindex fonts, emulating under MS-DOS - - Display on MS-DOS cannot use font variants, like bold or italic, but -it does support multiple faces, each of which can specify a foreground -and a background color. Therefore, you can get the full functionality -of Emacs packages that use fonts (such as @code{font-lock}, Enriched -Text mode, and others) by defining the relevant faces to use different -colors. Use the @code{list-colors-display} command -@iftex -(@pxref{Colors,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Colors}) -@end ifnottex -and the @code{list-faces-display} command -@iftex -(@pxref{Faces,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Faces}) -@end ifnottex -to see what colors and faces are available and what they look like. - - @xref{MS-DOS and MULE}, later in this chapter, for information on -how Emacs displays glyphs and characters that aren't supported by the -native font built into the DOS display. - -@cindex cursor shape on MS-DOS - When Emacs starts, it changes the cursor shape to a solid box. This -is for compatibility with other systems, where the box cursor is the -default in Emacs. This default shape can be changed to a bar by -specifying the @code{cursor-type} parameter in the variable -@code{default-frame-alist} -@iftex -(@pxref{Creating Frames,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Creating Frames}). -@end ifnottex -The MS-DOS terminal doesn't support a vertical-bar cursor, -so the bar cursor is horizontal, and the @code{@var{width}} parameter, -if specified by the frame parameters, actually determines its height. -For this reason, the @code{bar} and @code{hbar} cursor types produce -the same effect on MS-DOS@. As an extension, the bar cursor -specification can include the starting scan line of the cursor as well -as its width, like this: - -@example - '(cursor-type bar @var{width} . @var{start}) -@end example - -@noindent -In addition, if the @var{width} parameter is negative, the cursor bar -begins at the top of the character cell. - -@cindex frames on MS-DOS - The MS-DOS terminal can only display a single frame at a time. The -Emacs frame facilities work on MS-DOS much as they do on text -terminals -@iftex -(@pxref{Frames,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Frames}). -@end ifnottex -When you run Emacs from a DOS window on MS-Windows, you can make the -visible frame smaller than the full screen, but Emacs still cannot -display more than a single frame at a time. - -@cindex frame size under MS-DOS -@findex dos-mode4350 -@findex dos-mode25 - The @code{dos-mode4350} command switches the display to 43 or 50 -lines, depending on your hardware; the @code{dos-mode25} command switches -to the default 80x25 screen size. - - By default, Emacs only knows how to set screen sizes of 80 columns by -25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has -special video modes that will switch the display to other sizes, you can -have Emacs support those too. When you ask Emacs to switch the frame to -@var{n} rows by @var{m} columns dimensions, it checks if there is a -variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so, -uses its value (which must be an integer) as the video mode to switch -to. (Emacs switches to that video mode by calling the BIOS @code{Set -Video Mode} function with the value of -@code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.) -For example, suppose your adapter will switch to 66x80 dimensions when -put into video mode 85. Then you can make Emacs support this screen -size by putting the following into your @file{_emacs} file: - -@example -(setq screen-dimensions-66x80 85) -@end example - - Since Emacs on MS-DOS can only set the frame size to specific -supported dimensions, it cannot honor every possible frame resizing -request. When an unsupported size is requested, Emacs chooses the next -larger supported size beyond the specified size. For example, if you -ask for 36x80 frame, you will get 40x80 instead. - - The variables @code{screen-dimensions-@var{n}x@var{m}} are used only -when they exactly match the specified size; the search for the next -larger supported size ignores them. In the above example, even if your -VGA supports 38x80 dimensions and you define a variable -@code{screen-dimensions-38x80} with a suitable value, you will still get -40x80 screen when you ask for a 36x80 frame. If you want to get the -38x80 size in this case, you can do it by setting the variable named -@code{screen-dimensions-36x80} with the same video mode value as -@code{screen-dimensions-38x80}. - - Changing frame dimensions on MS-DOS has the effect of changing all the -other frames to the new dimensions. - -@node MS-DOS File Names -@subsection File Names on MS-DOS -@cindex file names under MS-DOS -@cindex init file, default name under MS-DOS - - On MS-DOS, file names are case-insensitive and limited to eight -characters, plus optionally a period and three more characters. Emacs -knows enough about these limitations to handle file names that were -meant for other operating systems. For instance, leading dots -@samp{.} in file names are invalid in MS-DOS, so Emacs transparently -converts them to underscores @samp{_}; thus your default init file -@iftex -(@pxref{Init File,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Init File}) -@end ifnottex -is called @file{_emacs} on MS-DOS@. Excess characters before or after -the period are generally ignored by MS-DOS itself; thus, if you visit -the file @file{LongFileName.EvenLongerExtension}, you will silently -get @file{longfile.eve}, but Emacs will still display the long file -name on the mode line. Other than that, it's up to you to specify -file names which are valid under MS-DOS; the transparent conversion as -described above only works on file names built into Emacs. - -@cindex backup file names on MS-DOS - The above restrictions on the file names on MS-DOS make it almost -impossible to construct the name of a backup file -@iftex -(@pxref{Backup Names,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Backup Names}) -@end ifnottex -without losing some of the original file name characters. For -example, the name of a backup file for @file{docs.txt} is -@file{docs.tx~} even if single backup is used. - -@cindex file names under Windows 95/NT -@cindex long file names in DOS box under Windows 95/NT - If you run Emacs as a DOS application under Windows 9X, Windows ME, or -Windows 2000/XP, you can turn on support for long file names. If you do -that, Emacs doesn't truncate file names or convert them to lower case; -instead, it uses the file names that you specify, verbatim. To enable -long file name support, set the environment variable @env{LFN} to -@samp{y} before starting Emacs. Unfortunately, Windows NT doesn't allow -DOS programs to access long file names, so Emacs built for MS-DOS will -only see their short 8+3 aliases. - -@cindex @env{HOME} directory under MS-DOS - MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends -that the directory where it is installed is the value of the @env{HOME} -environment variable. That is, if your Emacs binary, -@file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then -Emacs acts as if @env{HOME} were set to @samp{c:/utils/emacs}. In -particular, that is where Emacs looks for the init file @file{_emacs}. -With this in mind, you can use @samp{~} in file names as an alias for -the home directory, as you would on GNU or Unix. You can also set -@env{HOME} variable in the environment before starting Emacs; its -value will then override the above default behavior. - - Emacs on MS-DOS handles the directory name @file{/dev} specially, -because of a feature in the emulator libraries of DJGPP that pretends -I/O devices have names in that directory. We recommend that you avoid -using an actual directory named @file{/dev} on any disk. - -@node MS-DOS Printing -@subsection Printing and MS-DOS - - Printing commands, such as @code{lpr-buffer} -@iftex -(@pxref{Printing,,,emacs, the Emacs Manual}) and @code{ps-print-buffer} -(@pxref{PostScript,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}) -@end ifnottex -can work on MS-DOS by sending the output to one of the printer ports, -if a Posix-style @code{lpr} program is unavailable. The same Emacs -variables control printing on all systems, but in some cases they have -different default values on MS-DOS. - -@iftex -@xref{Windows Printing,,,emacs, the Emacs Manual}, -@end iftex -@ifnottex -@xref{Windows Printing}, -@end ifnottex -for details about setting up printing to a networked printer. - - Some printers expect DOS codepage encoding of non-@acronym{ASCII} text, even -though they are connected to a Windows machine that uses a different -encoding for the same locale. For example, in the Latin-1 locale, DOS -uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and -MULE}. When you print to such printers from Windows, you can use the -@kbd{C-x @key{RET} c} (@code{universal-coding-system-argument}) command -before @kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS -codepage that you specify. For example, -@kbd{C-x @key{RET} c cp850-dos @key{RET} M-x lpr-region @key{RET}} -will print the region while converting it to the codepage 850 encoding. - -@vindex dos-printer -@vindex dos-ps-printer - For backwards compatibility, the value of @code{dos-printer} -(@code{dos-ps-printer}), if it has a value, overrides the value of -@code{printer-name} (@code{ps-printer-name}), on MS-DOS. - - -@node MS-DOS and MULE -@subsection International Support on MS-DOS -@cindex international support @r{(MS-DOS)} - - Emacs on MS-DOS supports the same international character sets as it -does on GNU, Unix and other platforms -@iftex -(@pxref{International,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{International}), -@end ifnottex -including coding systems for converting between the different -character sets. However, due to incompatibilities between -MS-DOS/MS-Windows and other systems, there are several DOS-specific -aspects of this support that you should be aware of. This section -describes these aspects. - - The description below is largely specific to the MS-DOS port of -Emacs, especially where it talks about practical implications for -Emacs users. - -@table @kbd -@item M-x dos-codepage-setup -Set up Emacs display and coding systems as appropriate for the current -DOS codepage. -@end table - -@cindex codepage, MS-DOS -@cindex DOS codepages - MS-DOS is designed to support one character set of 256 characters at -any given time, but gives you a variety of character sets to choose -from. The alternative character sets are known as @dfn{DOS codepages}. -Each codepage includes all 128 @acronym{ASCII} characters, but the other 128 -characters (codes 128 through 255) vary from one codepage to another. -Each DOS codepage is identified by a 3-digit number, such as 850, 862, -etc. - - In contrast to X, which lets you use several fonts at the same time, -MS-DOS normally doesn't allow use of several codepages in a single -session. MS-DOS was designed to load a single codepage at system -startup, and require you to reboot in order to change -it@footnote{Normally, one particular codepage is burnt into the -display memory, while other codepages can be installed by modifying -system configuration files, such as @file{CONFIG.SYS}, and rebooting. -While there is third-party software that allows changing the codepage -without rebooting, we describe here how a stock MS-DOS system -behaves.}. Much the same limitation applies when you run DOS -executables on other systems such as MS-Windows. - -@vindex dos-codepage - For multibyte operation on MS-DOS, Emacs needs to know which -characters the chosen DOS codepage can display. So it queries the -system shortly after startup to get the chosen codepage number, and -stores the number in the variable @code{dos-codepage}. Some systems -return the default value 437 for the current codepage, even though the -actual codepage is different. (This typically happens when you use the -codepage built into the display hardware.) You can specify a different -codepage for Emacs to use by setting the variable @code{dos-codepage} in -your init file. - -@cindex language environment, automatic selection on @r{MS-DOS} - Multibyte Emacs supports only certain DOS codepages: those which can -display Far-Eastern scripts, like the Japanese codepage 932, and those -that encode a single ISO 8859 character set. - - The Far-Eastern codepages can directly display one of the MULE -character sets for these countries, so Emacs simply sets up to use the -appropriate terminal coding system that is supported by the codepage. -The special features described in the rest of this section mostly -pertain to codepages that encode ISO 8859 character sets. - - For the codepages that correspond to one of the ISO character sets, -Emacs knows the character set based on the codepage number. Emacs -automatically creates a coding system to support reading and writing -files that use the current codepage, and uses this coding system by -default. The name of this coding system is @code{cp@var{nnn}}, where -@var{nnn} is the codepage number.@footnote{The standard Emacs coding -systems for ISO 8859 are not quite right for the purpose, because -typically the DOS codepage does not match the standard ISO character -codes. For example, the letter @samp{@,{c}} (@samp{c} with cedilla) has -code 231 in the standard Latin-1 character set, but the corresponding -DOS codepage 850 uses code 135 for this glyph.} - -@cindex mode line @r{(MS-DOS)} - All the @code{cp@var{nnn}} coding systems use the letter @samp{D} -(for ``DOS'') as their mode-line mnemonic. Since both the terminal -coding system and the default coding system for file I/O are set to -the proper @code{cp@var{nnn}} coding system at startup, it is normal -for the mode line on MS-DOS to begin with @samp{-DD\-}. -@iftex -@xref{Mode Line,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Mode Line}. -@end ifnottex -Far-Eastern DOS terminals do not use the @code{cp@var{nnn}} coding -systems, and thus their initial mode line looks like the Emacs -default. - - Since the codepage number also indicates which script you are using, -Emacs automatically runs @code{set-language-environment} to select the -language environment for that script -@iftex -(@pxref{Language Environments,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Language Environments}). -@end ifnottex - - If a buffer contains a character belonging to some other ISO 8859 -character set, not the one that the chosen DOS codepage supports, Emacs -displays it using a sequence of @acronym{ASCII} characters. For example, if the -current codepage doesn't have a glyph for the letter @samp{@`o} (small -@samp{o} with a grave accent), it is displayed as @samp{@{`o@}}, where -the braces serve as a visual indication that this is a single character. -(This may look awkward for some non-Latin characters, such as those from -Greek or Hebrew alphabets, but it is still readable by a person who -knows the language.) Even though the character may occupy several -columns on the screen, it is really still just a single character, and -all Emacs commands treat it as one. - -@cindex MS-Windows codepages - MS-Windows provides its own codepages, which are different from the -DOS codepages for the same locale. For example, DOS codepage 850 -supports the same character set as Windows codepage 1252; DOS codepage -855 supports the same character set as Windows codepage 1251, etc. -The MS-Windows version of Emacs uses the current codepage for display -when invoked with the @samp{-nw} option. - -@node MS-DOS Processes -@subsection Subprocesses on MS-DOS - -@cindex compilation under MS-DOS -@cindex inferior processes under MS-DOS -@findex compile @r{(MS-DOS)} -@findex grep @r{(MS-DOS)} - Because MS-DOS is a single-process ``operating system'', -asynchronous subprocesses are not available. In particular, Shell -mode and its variants do not work. Most Emacs features that use -asynchronous subprocesses also don't work on MS-DOS, including -Shell mode and GUD@. When in doubt, try and see; commands that -don't work output an error message saying that asynchronous processes -aren't supported. - - Compilation under Emacs with @kbd{M-x compile}, searching files with -@kbd{M-x grep} and displaying differences between files with @kbd{M-x -diff} do work, by running the inferior processes synchronously. This -means you cannot do any more editing until the inferior process -finishes. - - Spell checking also works, by means of special support for synchronous -invocation of the @code{ispell} program. This is slower than the -asynchronous invocation on other platforms - - Instead of the Shell mode, which doesn't work on MS-DOS, you can use -the @kbd{M-x eshell} command. This invokes the Eshell package that -implements a Posix-like shell entirely in Emacs Lisp. - - By contrast, Emacs compiled as a native Windows application -@strong{does} support asynchronous subprocesses. -@iftex -@xref{Windows Processes,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Windows Processes}. -@end ifnottex - -@cindex printing under MS-DOS - Printing commands, such as @code{lpr-buffer} -@iftex -(@pxref{Printing,,,emacs, the Emacs Manual}) and -@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}), -work in MS-DOS by sending the output to one of the printer ports. -@xref{MS-DOS Printing,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}), -work in MS-DOS by sending the output to one of the printer ports. -@xref{MS-DOS Printing}. -@end ifnottex - - When you run a subprocess synchronously on MS-DOS, make sure the -program terminates and does not try to read keyboard input. If the -program does not terminate on its own, you will be unable to terminate -it, because MS-DOS provides no general way to terminate a process. -Pressing @kbd{C-c} or @kbd{C-@key{Break}} might sometimes help in these -cases. - - Accessing files on other machines is not supported on MS-DOS@. Other -network-oriented commands such as sending mail, Web browsing, remote -login, etc., don't work either, unless network access is built into -MS-DOS with some network redirector. - -@cindex directory listing on MS-DOS -@vindex dired-listing-switches @r{(MS-DOS)} - Dired on MS-DOS uses the @code{ls-lisp} package -@iftex -(@pxref{ls in Lisp,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{ls in Lisp}). -@end ifnottex -Therefore, Dired on MS-DOS supports only some of the possible options -you can mention in the @code{dired-listing-switches} variable. The -options that work are @samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, -@samp{-r}, @samp{-S}, @samp{-s}, @samp{-t}, and @samp{-u}. diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdog.texi deleted file mode 100644 index 7c5b3600728..00000000000 --- a/doc/emacs/msdog.texi +++ /dev/null @@ -1,990 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Microsoft Windows -@appendix Emacs and Microsoft Windows/MS-DOS -@cindex Microsoft Windows -@cindex MS-Windows, Emacs peculiarities - - This section describes peculiarities of using Emacs on Microsoft -Windows. Some of these peculiarities are also relevant to Microsoft's -older MS-DOS ``operating system'' (also known as ``MS-DOG''). -However, Emacs features that are relevant @emph{only} to MS-DOS are -described in a separate -@iftex -manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -section (@pxref{MS-DOS}). -@end ifnottex - - - The behavior of Emacs on MS-Windows is reasonably similar to what is -documented in the rest of the manual, including support for long file -names, multiple frames, scroll bars, mouse menus, and subprocesses. -However, a few special considerations apply, and they are described -here. - -@menu -* Windows Startup:: How to start Emacs on Windows. -* Text and Binary:: Text files use CRLF to terminate lines. -* Windows Files:: File-name conventions on Windows. -* ls in Lisp:: Emulation of @code{ls} for Dired. -* Windows HOME:: Where Emacs looks for your @file{.emacs} and - where it starts up. -* Windows Keyboard:: Windows-specific keyboard features. -* Windows Mouse:: Windows-specific mouse features. -* Windows Processes:: Running subprocesses on Windows. -* Windows Printing:: How to specify the printer on MS-Windows. -* Windows Fonts:: Specifying fonts on MS-Windows. -* Windows Misc:: Miscellaneous Windows features. -@ifnottex -* MS-DOS:: Using Emacs on MS-DOS. -@end ifnottex -@end menu - -@node Windows Startup -@section How to Start Emacs on MS-Windows -@cindex starting Emacs on MS-Windows - - There are several ways of starting Emacs on MS-Windows: - -@enumerate -@item -@pindex runemacs.exe -@cindex desktop shortcut, MS-Windows -@cindex start directory, MS-Windows -@cindex directory where Emacs starts on MS-Windows -From the desktop shortcut icon: either double-click the left mouse -button on the icon, or click once, then press @key{RET}. The desktop -shortcut should specify as its ``Target'' (in the ``Properties'' of -the shortcut) the full absolute file name of @file{runemacs.exe}, -@emph{not} of @file{emacs.exe}. This is because @file{runemacs.exe} -hides the console window that would have been created if the target of -the shortcut were @file{emacs.exe} (which is a console program, as far -as Windows is concerned). If you use this method, Emacs starts in the -directory specified by the shortcut. To control where that is, -right-click on the shortcut, select ``Properties'', and in the -``Shortcut'' tab modify the ``Start in'' field to your liking. - -@item -From the Command Prompt window, by typing @kbd{emacs @key{RET}} at the -prompt. The Command Prompt window where you did that will not be -available for invoking other commands until Emacs exits. In this -case, Emacs will start in the current directory of the Windows shell. - -@item -From the Command Prompt window, by typing @kbd{runemacs @key{RET}} at -the prompt. The Command Prompt window where you did that will be -immediately available for invoking other commands. In this case, -Emacs will start in the current directory of the Windows shell. - -@item -@cindex invoking Emacs from Windows Explorer -@pindex emacsclient.exe -@pindex emacsclientw.exe -Via @file{emacsclient.exe} or @file{emacsclientw.exe}, which allow you -to invoke Emacs from other programs, and to reuse a running Emacs -process for serving editing jobs required by other programs. -@xref{Emacs Server}. The difference between @file{emacsclient.exe} -and @file{emacsclientw.exe} is that the former is a console program, -while the latter is a Windows GUI program. Both programs wait for -Emacs to signal that the editing job is finished, before they exit and -return control to the program that invoked them. Which one of them to -use in each case depends on the expectations of the program that needs -editing services. If that program is itself a console (text-mode) -program, you should use @file{emacsclient.exe}, so that any of its -messages and prompts appear in the same command window as those of the -invoking program. By contrast, if the invoking program is a GUI -program, you will be better off using @file{emacsclientw.exe}, because -@file{emacsclient.exe} will pop up a command window if it is invoked -from a GUI program. A notable situation where you would want -@file{emacsclientw.exe} is when you right-click on a file in the -Windows Explorer and select ``Open With'' from the pop-up menu. Use -the @samp{--alternate-editor=} or @samp{-a} options if Emacs might not -be running (or not running as a server) when @command{emacsclient} is -invoked---that will always give you an editor. When invoked via -@command{emacsclient}, Emacs will start in the current directory of -the program that invoked @command{emacsclient}. -@end enumerate - -@cindex emacsclient, on MS-Windows -Note that, due to limitations of MS-Windows, Emacs cannot have both -GUI and text-mode frames in the same session. It also cannot open -text-mode frames on more than a single @dfn{Command Prompt} window, -because each Windows program can have only one console at any given -time. For these reasons, if you invoke @command{emacsclient} with the -@option{-c} option, and the Emacs server runs in a text-mode session, -Emacs will always create a new text-mode frame in the same -@dfn{Command Prompt} window where it was started; a GUI frame will be -created only if the server runs in a GUI session. Similarly, if you -invoke @command{emacsclient} with the @option{-t} option, Emacs will -create a GUI frame if the server runs in a GUI session, or a text-mode -frame when the session runs in text mode in a @dfn{Command Prompt} -window. @xref{emacsclient Options}. - -@node Text and Binary -@section Text Files and Binary Files -@cindex text and binary files on MS-DOS/MS-Windows - - GNU Emacs uses newline characters to separate text lines. This is the -convention used on GNU, Unix, and other Posix-compliant systems. - -@cindex end-of-line conversion on MS-DOS/MS-Windows - By contrast, MS-DOS and MS-Windows normally use carriage-return linefeed, -a two-character sequence, to separate text lines. (Linefeed is the same -character as newline.) Therefore, convenient editing of typical files -with Emacs requires conversion of these end-of-line (EOL) sequences. -And that is what Emacs normally does: it converts carriage-return -linefeed into newline when reading files, and converts newline into -carriage-return linefeed when writing files. The same mechanism that -handles conversion of international character codes does this conversion -also (@pxref{Coding Systems}). - -@cindex cursor location, on MS-DOS -@cindex point location, on MS-DOS - One consequence of this special format-conversion of most files is -that character positions as reported by Emacs (@pxref{Position Info}) do -not agree with the file size information known to the operating system. - - In addition, if Emacs recognizes from a file's contents that it uses -newline rather than carriage-return linefeed as its line separator, it -does not perform EOL conversion when reading or writing that file. -Thus, you can read and edit files from GNU and Unix systems on MS-DOS -with no special effort, and they will retain their Unix-style -end-of-line convention after you edit them. - - The mode line indicates whether end-of-line translation was used for -the current buffer. If MS-DOS end-of-line translation is in use for the -buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after -the coding system mnemonic near the beginning of the mode line -(@pxref{Mode Line}). If no EOL translation was performed, the string -@samp{(Unix)} is displayed instead of the backslash, to alert you that the -file's EOL format is not the usual carriage-return linefeed. - -@cindex DOS-to-Unix conversion of files - To visit a file and specify whether it uses DOS-style or Unix-style -end-of-line, specify a coding system (@pxref{Text Coding}). For -example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt} -visits the file @file{foobar.txt} without converting the EOLs; if some -line ends with a carriage-return linefeed pair, Emacs will display -@samp{^M} at the end of that line. Similarly, you can direct Emacs to -save a buffer in a specified EOL format with the @kbd{C-x @key{RET} f} -command. For example, to save a buffer with Unix EOL format, type -@kbd{C-x @key{RET} f unix @key{RET} C-x C-s}. If you visit a file -with DOS EOL conversion, then save it with Unix EOL format, that -effectively converts the file to Unix EOL style, like the -@code{dos2unix} program. - -@cindex untranslated file system -@findex add-untranslated-filesystem - When you use NFS, Samba, or some other similar method to access file -systems that reside on computers using GNU or Unix systems, Emacs -should not perform end-of-line translation on any files in these file -systems---not even when you create a new file. To request this, -designate these file systems as @dfn{untranslated} file systems by -calling the function @code{add-untranslated-filesystem}. It takes one -argument: the file system name, including a drive letter and -optionally a directory. For example, - -@example -(add-untranslated-filesystem "Z:") -@end example - -@noindent -designates drive Z as an untranslated file system, and - -@example -(add-untranslated-filesystem "Z:\\foo") -@end example - -@noindent -designates directory @file{\foo} on drive Z as an untranslated file -system. - - Most often you would use @code{add-untranslated-filesystem} in your -@file{.emacs} file, or in @file{site-start.el} so that all the users at -your site get the benefit of it. - -@findex remove-untranslated-filesystem - To countermand the effect of @code{add-untranslated-filesystem}, use -the function @code{remove-untranslated-filesystem}. This function takes -one argument, which should be a string just like the one that was used -previously with @code{add-untranslated-filesystem}. - - Designating a file system as untranslated does not affect character -set conversion, only end-of-line conversion. Essentially, it directs -Emacs to create new files with the Unix-style convention of using -newline at the end of a line. @xref{Coding Systems}. - -@node Windows Files -@section File Names on MS-Windows -@cindex file names on MS-Windows - - MS-Windows and MS-DOS normally use a backslash, @samp{\}, to -separate name units within a file name, instead of the slash used on -other systems. Emacs on MS-DOS/MS-Windows permits use of either slash or -backslash, and also knows about drive letters in file names. - -@cindex file-name completion, on MS-Windows - On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by -default ignores letter-case in file names during completion. - -@vindex w32-get-true-file-attributes - The variable @code{w32-get-true-file-attributes} controls whether -Emacs should issue additional system calls to determine more -accurately file attributes in primitives like @code{file-attributes} -and @code{directory-files-and-attributes}. These additional calls are -needed to report correct file ownership, link counts and file types -for special files such as pipes. Without these system calls, file -ownership will be attributed to the current user, link counts will be -always reported as 1, and special files will be reported as regular -files. - - If the value of this variable is @code{local} (the default), Emacs -will issue these additional system calls only for files on local fixed -drives. Any other non-@code{nil} value means do this even for -removable and remote volumes, where this could potentially slow down -Dired and other related features. The value of @code{nil} means never -issue those system calls. Non-@code{nil} values are more useful on -NTFS volumes, which support hard links and file security, than on FAT, -FAT32, and XFAT volumes. - -@node ls in Lisp -@section Emulation of @code{ls} on MS-Windows -@cindex Dired, and MS-Windows/MS-DOS -@cindex @code{ls} emulation - - Dired normally uses the external program @code{ls} -to produce the directory listing displayed in Dired -buffers (@pxref{Dired}). However, MS-Windows and MS-DOS systems don't -come with such a program, although several ports of @sc{gnu} @code{ls} -are available. Therefore, Emacs on those systems @emph{emulates} -@code{ls} in Lisp, by using the @file{ls-lisp.el} package. While -@file{ls-lisp.el} provides a reasonably full emulation of @code{ls}, -there are some options and features peculiar to that emulation; -@iftex -for more details, see the documentation of the variables whose names -begin with @code{ls-lisp}. -@end iftex -@ifnottex -they are described in this section. - - The @code{ls} emulation supports many of the @code{ls} switches, but -it doesn't support all of them. Here's the list of the switches it -does support: @option{-A}, @option{-a}, @option{-B}, @option{-C}, -@option{-c}, @option{-G}, @option{-g}, @option{-h}, @option{-i}, @option{-n}, -@option{-R}, @option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U}, -@option{-u}, and @option{-X}. The @option{-F} switch is partially -supported (it appends the character that classifies the file, but does -not prevent symlink following). - -@vindex ls-lisp-use-insert-directory-program - On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs -is built, so the Lisp emulation of @code{ls} is always used on those -platforms. If you have a ported @code{ls}, setting -@code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value -will revert to using an external program named by the variable -@code{insert-directory-program}. - -@vindex ls-lisp-ignore-case - By default, @file{ls-lisp.el} uses a case-sensitive sort order for -the directory listing it produces; this is so the listing looks the -same as on other platforms. If you wish that the files be sorted in -case-insensitive order, set the variable @code{ls-lisp-ignore-case} to -a non-@code{nil} value. - -@vindex ls-lisp-dirs-first - By default, files and subdirectories are sorted together, to emulate -the behavior of @code{ls}. However, native MS-Windows/MS-DOS file -managers list the directories before the files; if you want that -behavior, customize the option @code{ls-lisp-dirs-first} to a -non-@code{nil} value. - -@vindex ls-lisp-verbosity - The variable @code{ls-lisp-verbosity} controls the file attributes -that @file{ls-lisp.el} displays. The value should be a list that -contains one or more of the symbols @code{links}, @code{uid}, and -@code{gid}. @code{links} means display the count of different file -names that are associated with (a.k.a.@: @dfn{links to}) the file's -data; this is only useful on NTFS volumes. @code{uid} means display -the numerical identifier of the user who owns the file. @code{gid} -means display the numerical identifier of the file owner's group. The -default value is @code{(links uid gid)} i.e., all the 3 optional -attributes are displayed. - -@vindex ls-lisp-emulation - The variable @code{ls-lisp-emulation} controls the flavor of the -@code{ls} emulation by setting the defaults for the 3 options -described above: @code{ls-lisp-ignore-case}, -@code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}. The value of -this option can be one of the following symbols: - -@table @code -@item GNU -@itemx nil -Emulate @sc{gnu} systems; this is the default. This sets -@code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to -@code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}. -@item UNIX -Emulate Unix systems. Like @code{GNU}, but sets -@code{ls-lisp-verbosity} to @code{(links uid)}. -@item MacOS -Emulate MacOS@. Sets @code{ls-lisp-ignore-case} to @code{t}, and -@code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}. -@item MS-Windows -Emulate MS-Windows. Sets @code{ls-lisp-ignore-case} and -@code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to -@code{(links)} on Windows NT/2K/XP/2K3 and to @code{nil} on Windows 9X@. -Note that the default emulation is @emph{not} @code{MS-Windows}, even -on Windows, since many users of Emacs on those platforms prefer the -@sc{gnu} defaults. -@end table - -@noindent -Any other value of @code{ls-lisp-emulation} means the same as @code{GNU}. -Customizing this option calls the function @code{ls-lisp-set-options} to -update the 3 dependent options as needed. If you change the value of -this variable without using customize after @file{ls-lisp.el} is loaded -(note that it is preloaded on MS-Windows and MS-DOS), you can call that -function manually for the same result. - -@vindex ls-lisp-support-shell-wildcards - The variable @code{ls-lisp-support-shell-wildcards} controls how -file-name patterns are supported: if it is non-@code{nil} (the -default), they are treated as shell-style wildcards; otherwise they -are treated as Emacs regular expressions. - -@vindex ls-lisp-format-time-list - The variable @code{ls-lisp-format-time-list} defines how to format -the date and time of files. @emph{The value of this variable is -ignored}, unless Emacs cannot determine the current locale. (However, -if the value of @code{ls-lisp-use-localized-time-format} is -non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if -the current locale is available; see below.) - -The value of @code{ls-lisp-format-time-list} is a list of 2 strings. -The first string is used if the file was modified within the current -year, while the second string is used for older files. In each of -these two strings you can use @samp{%}-sequences to substitute parts -of the time. For example: -@lisp -("%b %e %H:%M" "%b %e %Y") -@end lisp - -@noindent -Note that the strings substituted for these @samp{%}-sequences depend -on the current locale. @xref{Time Parsing,,, elisp, The Emacs Lisp -Reference Manual}, for more about format time specs. - -@vindex ls-lisp-use-localized-time-format - Normally, Emacs formats the file time stamps in either traditional -or ISO-style time format. However, if the value of the variable -@code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs -formats file time stamps according to what -@code{ls-lisp-format-time-list} specifies. The @samp{%}-sequences in -@code{ls-lisp-format-time-list} produce locale-dependent month and day -names, which might cause misalignment of columns in Dired display. -@end ifnottex - -@node Windows HOME -@section HOME and Startup Directories on MS-Windows -@cindex @code{HOME} directory on MS-Windows - - The Windows equivalent of @code{HOME} is the @dfn{user-specific -application data directory}. The actual location depends on the -Windows version; typical values are @file{C:\Documents and -Settings\@var{username}\Application Data} on Windows 2000/XP/2K3, -@file{C:\Users\@var{username}\AppData\Roaming} on Windows -Vista/7/2008, and either @file{C:\WINDOWS\Application Data} or -@file{C:\WINDOWS\Profiles\@var{username}\Application Data} on Windows -9X/ME@. If this directory does not exist or cannot be accessed, Emacs -falls back to @file{C:\} as the default value of @code{HOME}. - - You can override this default value of @code{HOME} by explicitly -setting the environment variable @env{HOME} to point to any directory -on your system. @env{HOME} can be set either from the command shell -prompt or from @samp{Properties} dialog of @samp{My Computer}. -@code{HOME} can also be set in the system registry, -@pxref{MS-Windows Registry}. - - For compatibility with older versions of Emacs@footnote{ -Older versions of Emacs didn't check the application data directory. -}, if there is a file named @file{.emacs} in @file{C:\}, the root -directory of drive @file{C:}, and @env{HOME} is set neither in the -environment nor in the Registry, Emacs will treat @file{C:\} as the -default @code{HOME} location, and will not look in the application -data directory, even if it exists. Note that only @file{.emacs} is -looked for in @file{C:\}; the older name @file{_emacs} (see below) is -not. This use of @file{C:\.emacs} to define @code{HOME} is -deprecated. - - Whatever the final place is, Emacs sets the internal value of the -@env{HOME} environment variable to point to it, and it will use that -location for other files and directories it normally looks for or -creates in your home directory. - - You can always find out what Emacs thinks is your home directory's -location by typing @kbd{C-x d ~/ @key{RET}}. This should present the -list of files in the home directory, and show its full name on the -first line. Likewise, to visit your init file, type @kbd{C-x C-f -~/.emacs @key{RET}} (assuming the file's name is @file{.emacs}). - -@cindex init file @file{.emacs} on MS-Windows - The home directory is where your init file is stored. It can have -any name mentioned in @ref{Init File}. - -@cindex @file{_emacs} init file, MS-Windows - Because MS-DOS does not allow file names with leading dots, and -older Windows systems made it hard to create files with such names, -the Windows port of Emacs supports an init file name @file{_emacs}, if -such a file exists in the home directory and @file{.emacs} does not. -This name is considered obsolete. - -@node Windows Keyboard -@section Keyboard Usage on MS-Windows -@cindex keyboard, MS-Windows - - This section describes the Windows-specific features related to -keyboard input in Emacs. - -@cindex MS-Windows keyboard shortcuts - Many key combinations (known as ``keyboard shortcuts'') that have -conventional uses in MS-Windows programs conflict with traditional -Emacs key bindings. (These Emacs key bindings were established years -before Microsoft was founded.) Examples of conflicts include -@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}. -You can redefine some of them with meanings more like the MS-Windows -meanings by enabling CUA Mode (@pxref{CUA Bindings}). - -@iftex -@inforef{Windows Keyboard, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex -@ifnottex -@vindex w32-alt-is-meta -@cindex @code{Alt} key (MS-Windows) - By default, the key labeled @key{Alt} is mapped as the @key{META} -key. If you wish it to produce the @code{Alt} modifier instead, set -the variable @code{w32-alt-is-meta} to a @code{nil} value. - -@findex w32-register-hot-key -@findex w32-unregister-hot-key - MS-Windows reserves certain key combinations, such as -@kbd{@key{Alt}-@key{TAB}}, for its own use. These key combinations are -intercepted by the system before Emacs can see them. You can use the -@code{w32-register-hot-key} function to allow a key sequence to be -seen by Emacs instead of being grabbed by Windows. This function -registers a key sequence as a @dfn{hot key}, overriding the special -meaning of that key sequence for Windows. (MS-Windows is told that -the key sequence is a hot key only when one of the Emacs windows has -focus, so that the special keys still have their usual meaning for -other Windows applications.) - - The argument to @code{w32-register-hot-key} must be a single key, -with or without modifiers, in vector form that would be acceptable to -@code{define-key}. The meta modifier is interpreted as the @key{Alt} -key if @code{w32-alt-is-meta} is @code{t} (the default), and the hyper -modifier is always interpreted as the Windows key (usually labeled -with @key{start} and the Windows logo). If the function succeeds in -registering the key sequence, it returns the hotkey ID, a number; -otherwise it returns @code{nil}. - -@kindex M-TAB@r{, (MS-Windows)} -@cindex @kbd{M-@key{TAB}} vs @kbd{@key{Alt}-@key{TAB}} (MS-Windows) -@cindex @kbd{@key{Alt}-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows) - For example, @code{(w32-register-hot-key [M-tab])} lets you use -@kbd{M-@key{TAB}} normally in Emacs; for instance, to complete the word or -symbol at point at top level, or to complete the current search string -against previously sought strings during incremental search. - - The function @code{w32-unregister-hot-key} reverses the effect of -@code{w32-register-hot-key} for its argument key sequence. - -@vindex w32-capslock-is-shiftlock - By default, the @key{CapsLock} key only affects normal character -keys (it converts lower-case characters to their upper-case -variants). However, if you set the variable -@code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the -@key{CapsLock} key will affect non-character keys as well, as if you -pressed the @key{Shift} key while typing the non-character key. - -@vindex w32-enable-caps-lock - If the variable @code{w32-enable-caps-lock} is set to a @code{nil} -value, the @key{CapsLock} key produces the symbol @code{capslock} -instead of the shifted version of they keys. The default value is -@code{t}. - -@vindex w32-enable-num-lock -@cindex keypad keys (MS-Windows) - Similarly, if @code{w32-enable-num-lock} is @code{nil}, the -@key{NumLock} key will produce the symbol @code{kp-numlock}. The -default is @code{t}, which causes @key{NumLock} to work as expected: -toggle the meaning of the keys on the numeric keypad. -@end ifnottex - -@vindex w32-apps-modifier - The variable @code{w32-apps-modifier} controls the effect of the -@key{Apps} key (usually located between the right @key{Alt} and the -right @key{Ctrl} keys). Its value can be one of the symbols -@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, -or @code{shift} for the respective modifier, or @code{nil} to appear -as the key @code{apps}. The default is @code{nil}. - -@vindex w32-lwindow-modifier -@vindex w32-rwindow-modifier -@vindex w32-scroll-lock-modifier - The variable @code{w32-lwindow-modifier} determines the effect of -the left Windows key (usually labeled with @key{start} and the Windows -logo). If its value is @code{nil} (the default), the key will produce -the symbol @code{lwindow}. Setting it to one of the symbols -@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, -or @code{shift} will produce the respective modifier. A similar -variable @code{w32-rwindow-modifier} controls the effect of the right -Windows key, and @code{w32-scroll-lock-modifier} does the same for the -@key{ScrLock} key. If these variables are set to @code{nil}, the -right Windows key produces the symbol @code{rwindow} and @key{ScrLock} -produces the symbol @code{scroll}. - -@vindex w32-pass-alt-to-system -@cindex Windows system menu -@cindex @code{Alt} key invokes menu (Windows) - Emacs compiled as a native Windows application normally turns off -the Windows feature that tapping the @key{Alt} key invokes the Windows -menu. The reason is that the @key{Alt} serves as @key{META} in Emacs. -When using Emacs, users often press the @key{META} key temporarily and -then change their minds; if this has the effect of bringing up the -Windows menu, it alters the meaning of subsequent commands. Many -users find this frustrating. - - You can re-enable Windows's default handling of tapping the @key{Alt} -key by setting @code{w32-pass-alt-to-system} to a non-@code{nil} -value. - -@ifnottex -@vindex w32-pass-lwindow-to-system -@vindex w32-pass-rwindow-to-system - The variables @code{w32-pass-lwindow-to-system} and -@code{w32-pass-rwindow-to-system} determine whether the respective -keys are passed to Windows or swallowed by Emacs. If the value is -@code{nil}, the respective key is silently swallowed by Emacs, -otherwise it is passed to Windows. The default is @code{t} for both -of these variables. Passing each of these keys to Windows produces -its normal effect: for example, @kbd{@key{Lwindow}} opens the -@code{Start} menu, etc.@footnote{ -Some combinations of the ``Windows'' keys with other keys are caught -by Windows at a low level in a way that Emacs currently cannot prevent. -For example, @kbd{@key{Lwindow} r} always pops up the Windows -@samp{Run} dialog. Customizing the value of -@code{w32-phantom-key-code} might help in some cases, though.} - -@vindex w32-recognize-altgr -@kindex AltGr @r{(MS-Windows)} -@cindex AltGr key (MS-Windows) - The variable @code{w32-recognize-altgr} controls whether the -@key{AltGr} key (if it exists on your keyboard), or its equivalent, -the combination of the right @key{Alt} and left @key{Ctrl} keys -pressed together, is recognized as the @key{AltGr} key. The default -is @code{t}, which means these keys produce @code{AltGr}; setting it -to @code{nil} causes @key{AltGr} or the equivalent key combination to -be interpreted as the combination of @key{Ctrl} and @key{META} -modifiers. -@end ifnottex - -@node Windows Mouse -@section Mouse Usage on MS-Windows -@cindex mouse, and MS-Windows - - This section describes the Windows-specific variables related to -the mouse. - -@vindex w32-mouse-button-tolerance -@cindex simulation of middle mouse button - The variable @code{w32-mouse-button-tolerance} specifies the -time interval, in milliseconds, for faking middle mouse button press -on 2-button mice. If both mouse buttons are depressed within this -time interval, Emacs generates a middle mouse button click event -instead of a double click on one of the buttons. - -@vindex w32-pass-extra-mouse-buttons-to-system - If the variable @code{w32-pass-extra-mouse-buttons-to-system} is -non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to -Windows. - -@vindex w32-swap-mouse-buttons - The variable @code{w32-swap-mouse-buttons} controls which of the 3 -mouse buttons generates the @kbd{mouse-2} events. When it is -@code{nil} (the default), the middle button generates @kbd{mouse-2} -and the right button generates @kbd{mouse-3} events. If this variable -is non-@code{nil}, the roles of these two buttons are reversed. - -@node Windows Processes -@section Subprocesses on Windows 9X/ME and Windows NT/2K/XP -@cindex subprocesses on MS-Windows - -@cindex DOS applications, running from Emacs - Emacs compiled as a native Windows application (as opposed to the DOS -version) includes full support for asynchronous subprocesses. -In the Windows version, synchronous and asynchronous subprocesses work -fine on both -Windows 9X/ME and Windows NT/2K/XP as long as you run only 32-bit Windows -applications. However, when you run a DOS application in a subprocess, -you may encounter problems or be unable to run the application at all; -and if you run two DOS applications at the same time in two -subprocesses, you may have to reboot your system. - -Since the standard command interpreter (and most command line utilities) -on Windows 9X are DOS applications, these problems are significant when -using that system. But there's nothing we can do about them; only -Microsoft can fix them. - -If you run just one DOS application subprocess, the subprocess should -work as expected as long as it is ``well-behaved'' and does not perform -direct screen access or other unusual actions. If you have a CPU -monitor application, your machine will appear to be 100% busy even when -the DOS application is idle, but this is only an artifact of the way CPU -monitors measure processor load. - -You must terminate the DOS application before you start any other DOS -application in a different subprocess. Emacs is unable to interrupt or -terminate a DOS subprocess. The only way you can terminate such a -subprocess is by giving it a command that tells its program to exit. - -If you attempt to run two DOS applications at the same time in separate -subprocesses, the second one that is started will be suspended until the -first one finishes, even if either or both of them are asynchronous. - -@cindex kill DOS application -If you can go to the first subprocess, and tell it to exit, the second -subprocess should continue normally. However, if the second subprocess -is synchronous, Emacs itself will be hung until the first subprocess -finishes. If it will not finish without user input, then you have no -choice but to reboot if you are running on Windows 9X@. If you are -running on Windows NT/2K/XP, you can use a process viewer application to kill -the appropriate instance of NTVDM instead (this will terminate both DOS -subprocesses). - -If you have to reboot Windows 9X in this situation, do not use the -@code{Shutdown} command on the @code{Start} menu; that usually hangs the -system. Instead, type @kbd{@key{Ctrl}-@key{Alt}-@key{DEL}} and then choose -@code{Shutdown}. That usually works, although it may take a few minutes -to do its job. - -@vindex w32-quote-process-args - The variable @code{w32-quote-process-args} controls how Emacs quotes -the process arguments. Non-@code{nil} means quote with the @code{"} -character. If the value is a character, Emacs uses that character to escape -any quote characters that appear; otherwise it chooses a suitable escape -character based on the type of the program. - -@ifnottex -@findex w32-shell-execute - The function @code{w32-shell-execute} can be useful for writing -customized commands that run MS-Windows applications registered to -handle a certain standard Windows operation for a specific type of -document or file. This function is a wrapper around the Windows -@code{ShellExecute} API@. See the MS-Windows API documentation for -more details. -@end ifnottex - -@node Windows Printing -@section Printing and MS-Windows - - Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and -@code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and -MS-Windows by sending the output to one of the printer ports, if a -Posix-style @code{lpr} program is unavailable. The same Emacs -variables control printing on all systems, but in some cases they have -different default values on MS-DOS and MS-Windows. - - Emacs on MS Windows attempts to determine your default printer -automatically (using the function @code{default-printer-name}). -But in some rare cases this can fail, or you may wish to use a different -printer from within Emacs. The rest of this section explains how to -tell Emacs which printer to use. - -@vindex printer-name@r{, (MS-DOS/MS-Windows)} - If you want to use your local printer, then set the Lisp variable -@code{lpr-command} to @code{""} (its default value on Windows) and -@code{printer-name} to the name of the printer port---for example, -@code{"PRN"}, the usual local printer port, or @code{"LPT2"}, or -@code{"COM1"} for a serial printer. You can also set -@code{printer-name} to a file name, in which case ``printed'' output -is actually appended to that file. If you set @code{printer-name} to -@code{"NUL"}, printed output is silently discarded (sent to the system -null device). - - You can also use a printer shared by another machine by setting -@code{printer-name} to the UNC share name for that printer---for -example, @code{"//joes_pc/hp4si"}. (It doesn't matter whether you use -forward slashes or backslashes here.) To find out the names of shared -printers, run the command @samp{net view} from the command prompt to -obtain a list of servers, and @samp{net view @var{server-name}} to see -the names of printers (and directories) shared by that server. -Alternatively, click the @samp{Network Neighborhood} icon on your -desktop, and look for machines that share their printers via the -network. - -@cindex @samp{net use}, and printing on MS-Windows -@cindex networked printers (MS-Windows) - If the printer doesn't appear in the output of @samp{net view}, or -if setting @code{printer-name} to the UNC share name doesn't produce a -hardcopy on that printer, you can use the @samp{net use} command to -connect a local print port such as @code{"LPT2"} to the networked -printer. For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{ -Note that the @samp{net use} command requires the UNC share name to be -typed with the Windows-style backslashes, while the value of -@code{printer-name} can be set with either forward- or backslashes.} -causes Windows to @dfn{capture} the @code{LPT2} port and redirect the -printed material to the printer connected to the machine @code{joes_pc}. -After this command, setting @code{printer-name} to @code{"LPT2"} -should produce the hardcopy on the networked printer. - - With some varieties of Windows network software, you can instruct -Windows to capture a specific printer port such as @code{"LPT2"}, and -redirect it to a networked printer via the @w{@code{Control -Panel->Printers}} applet instead of @samp{net use}. - - If you set @code{printer-name} to a file name, it's best to use an -absolute file name. Emacs changes the working directory according to -the default directory of the current buffer, so if the file name in -@code{printer-name} is relative, you will end up with several such -files, each one in the directory of the buffer from which the printing -was done. - - If the value of @code{printer-name} is correct, but printing does -not produce the hardcopy on your printer, it is possible that your -printer does not support printing plain text (some cheap printers omit -this functionality). In that case, try the PostScript print commands, -described below. - -@findex print-buffer @r{(MS-DOS)} -@findex print-region @r{(MS-DOS)} -@vindex lpr-headers-switches @r{(MS-DOS)} - The commands @code{print-buffer} and @code{print-region} call the -@code{pr} program, or use special switches to the @code{lpr} program, to -produce headers on each printed page. MS-DOS and MS-Windows don't -normally have these programs, so by default, the variable -@code{lpr-headers-switches} is set so that the requests to print page -headers are silently ignored. Thus, @code{print-buffer} and -@code{print-region} produce the same output as @code{lpr-buffer} and -@code{lpr-region}, respectively. If you do have a suitable @code{pr} -program (for example, from GNU Coreutils), set -@code{lpr-headers-switches} to @code{nil}; Emacs will then call -@code{pr} to produce the page headers, and print the resulting output as -specified by @code{printer-name}. - -@vindex print-region-function @r{(MS-DOS)} -@cindex lpr usage under MS-DOS -@vindex lpr-command @r{(MS-DOS)} -@vindex lpr-switches @r{(MS-DOS)} - Finally, if you do have an @code{lpr} work-alike, you can set the -variable @code{lpr-command} to @code{"lpr"}. Then Emacs will use -@code{lpr} for printing, as on other systems. (If the name of the -program isn't @code{lpr}, set @code{lpr-command} to the appropriate value.) -The variable @code{lpr-switches} has its standard meaning -when @code{lpr-command} is not @code{""}. If the variable -@code{printer-name} has a string value, it is used as the value for the -@code{-P} option to @code{lpr}, as on Unix. - -@findex ps-print-buffer @r{(MS-DOS)} -@findex ps-spool-buffer @r{(MS-DOS)} -@vindex ps-printer-name @r{(MS-DOS)} -@vindex ps-lpr-command @r{(MS-DOS)} -@vindex ps-lpr-switches @r{(MS-DOS)} - A parallel set of variables, @code{ps-lpr-command}, -@code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript -Variables}), defines how PostScript files should be printed. These -variables are used in the same way as the corresponding variables -described above for non-PostScript printing. Thus, the value of -@code{ps-printer-name} is used as the name of the device (or file) to -which PostScript output is sent, just as @code{printer-name} is used -for non-PostScript printing. (There are two distinct sets of -variables in case you have two printers attached to two different -ports, and only one of them is a PostScript printer.) - -@cindex Ghostscript, use for PostScript printing - The default value of the variable @code{ps-lpr-command} is @code{""}, -which causes PostScript output to be sent to the printer port specified -by @code{ps-printer-name}; but @code{ps-lpr-command} can also be set to -the name of a program which will accept PostScript files. Thus, if you -have a non-PostScript printer, you can set this variable to the name of -a PostScript interpreter program (such as Ghostscript). Any switches -that need to be passed to the interpreter program are specified using -@code{ps-lpr-switches}. (If the value of @code{ps-printer-name} is a -string, it will be added to the list of switches as the value for the -@code{-P} option. This is probably only useful if you are using -@code{lpr}, so when using an interpreter typically you would set -@code{ps-printer-name} to something other than a string so it is -ignored.) - - For example, to use Ghostscript for printing on the system's default -printer, put this in your @file{.emacs} file: - -@example -(setq ps-printer-name t) -(setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe") -(setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH" - "-sDEVICE=mswinpr2" - "-sPAPERSIZE=a4")) -@end example - -@noindent -(This assumes that Ghostscript is installed in the -@file{D:/gs6.01} directory.) - -@node Windows Fonts -@section Specifying Fonts on MS-Windows -@cindex font specification (MS Windows) - - Starting with Emacs 23, fonts are specified by their name, size -and optional properties. The format for specifying fonts comes from the -fontconfig library used in modern Free desktops: - -@example - [Family[-PointSize]][:Option1=Value1[:Option2=Value2[...]]] -@end example - - The old XLFD based format is also supported for backwards compatibility. - -@cindex font backend selection (MS-Windows) - Emacs 23 and later supports a number of font backends. Currently, -the @code{gdi} and @code{uniscribe} backends are supported on Windows. -The @code{gdi} font backend is available on all versions of Windows, -and supports all fonts that are natively supported by Windows. The -@code{uniscribe} font backend is available on Windows 2000 and later, -and supports TrueType and OpenType fonts. Some languages requiring -complex layout can only be properly supported by the Uniscribe -backend. By default, both backends are enabled if supported, with -@code{uniscribe} taking priority over @code{gdi}. To override that -and use the GDI backend even if Uniscribe is available, invoke Emacs -with the @kbd{-xrm Emacs.fontBackend:gdi} command-line argument, or -add a @code{Emacs.fontBackend} resource with the value @code{gdi} in -the Registry under either the -@samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} or the -@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs} key (@pxref{Resources}). - -@cindex font properties (MS Windows) -@noindent -Optional properties common to all font backends on MS-Windows are: - -@table @code - -@vindex font-weight-table @r{(MS-Windows)} -@item weight -Specifies the weight of the font. Special values @code{light}, -@code{medium}, @code{demibold}, @code{bold}, and @code{black} can be specified -without @code{weight=} (e.g., @kbd{Courier New-12:bold}). Otherwise, -the weight should be a numeric value between 100 and 900, or one of the -named weights in @code{font-weight-table}. If unspecified, a regular font -is assumed. - -@vindex font-slant-table @r{(MS-Windows)} -@item slant -Specifies whether the font is italic. Special values -@code{roman}, @code{italic} and @code{oblique} can be specified -without @code{slant=} (e.g., @kbd{Courier New-12:italic}). -Otherwise, the slant should be a numeric value, or one of the named -slants in @code{font-slant-table}. On Windows, any slant above 150 is -treated as italics, and anything below as roman. - -@item family -Specifies the font family, but normally this will be specified -at the start of the font name. - -@item pixelsize -Specifies the font size in pixels. This can be used instead -of the point size specified after the family name. - -@item adstyle -Specifies additional style information for the font. -On MS-Windows, the values @code{mono}, @code{sans}, @code{serif}, -@code{script} and @code{decorative} are recognized. These are most useful -as a fallback with the font family left unspecified. - -@vindex w32-charset-info-alist -@item registry -Specifies the character set registry that the font is -expected to cover. Most TrueType and OpenType fonts will be Unicode fonts -that cover several national character sets, but you can narrow down the -selection of fonts to those that support a particular character set by -using a specific registry from @code{w32-charset-info-alist} here. - -@item spacing -Specifies how the font is spaced. The @code{p} spacing specifies -a proportional font, and @code{m} or @code{c} specify a monospaced font. - -@item foundry -Not used on Windows, but for informational purposes and to -prevent problems with code that expects it to be set, is set internally to -@code{raster} for bitmapped fonts, @code{outline} for scalable fonts, -or @code{unknown} if the type cannot be determined as one of those. -@end table - -@cindex font properties (MS Windows gdi backend) -Options specific to @code{GDI} fonts: - -@table @code - -@cindex font scripts (MS Windows) -@cindex font Unicode subranges (MS Windows) -@item script -Specifies a Unicode subrange the font should support. - -The following scripts are recognized on Windows: @code{latin}, @code{greek}, -@code{coptic}, @code{cyrillic}, @code{armenian}, @code{hebrew}, @code{arabic}, -@code{syriac}, @code{nko}, @code{thaana}, @code{devanagari}, @code{bengali}, -@code{gurmukhi}, @code{gujarati}, @code{oriya}, @code{tamil}, @code{telugu}, -@code{kannada}, @code{malayam}, @code{sinhala}, @code{thai}, @code{lao}, -@code{tibetan}, @code{myanmar}, @code{georgian}, @code{hangul}, -@code{ethiopic}, @code{cherokee}, @code{canadian-aboriginal}, @code{ogham}, -@code{runic}, @code{khmer}, @code{mongolian}, @code{symbol}, @code{braille}, -@code{han}, @code{ideographic-description}, @code{cjk-misc}, @code{kana}, -@code{bopomofo}, @code{kanbun}, @code{yi}, @code{byzantine-musical-symbol}, -@code{musical-symbol}, and @code{mathematical}. - -@cindex font antialiasing (MS Windows) -@item antialias -Specifies the antialiasing method. The value @code{none} means no -antialiasing, @code{standard} means use standard antialiasing, -@code{subpixel} means use subpixel antialiasing (known as Cleartype on -Windows), and @code{natural} means use subpixel antialiasing with -adjusted spacing between letters. If unspecified, the font will use -the system default antialiasing. -@end table - -@node Windows Misc -@section Miscellaneous Windows-specific features - - This section describes miscellaneous Windows-specific features. - -@vindex w32-use-visible-system-caret -@cindex screen reader software, MS-Windows - The variable @code{w32-use-visible-system-caret} is a flag that -determines whether to make the system caret visible. The default when -no screen reader software is in use is @code{nil}, which means Emacs -draws its own cursor to indicate the position of point. A -non-@code{nil} value means Emacs will indicate point location with the -system caret; this facilitates use of screen reader software, and is -the default when such software is detected when running Emacs. -When this variable is non-@code{nil}, other variables affecting the -cursor display have no effect. - -@iftex -@inforef{Windows Misc, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex - -@ifnottex -@vindex w32-grab-focus-on-raise -@cindex frame focus policy, MS-Windows - The variable @code{w32-grab-focus-on-raise}, if set to a -non-@code{nil} value causes a frame to grab focus when it is raised. -The default is @code{t}, which fits well with the Windows default -click-to-focus policy. -@end ifnottex - -@ifnottex -@include msdog-xtra.texi -@end ifnottex diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi deleted file mode 100644 index 27c10c9f60a..00000000000 --- a/doc/emacs/mule.texi +++ /dev/null @@ -1,1831 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1997, 1999-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node International -@chapter International Character Set Support -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. (TUTORIAL.de) -@cindex international scripts -@cindex multibyte characters -@cindex encoding of characters - -@cindex Arabic -@cindex Bengali -@cindex Chinese -@cindex Cyrillic -@cindex Han -@cindex Hindi -@cindex Ethiopic -@cindex Georgian -@cindex Greek -@cindex Hangul -@cindex Hebrew -@cindex Hindi -@cindex IPA -@cindex Japanese -@cindex Korean -@cindex Latin -@cindex Thai -@cindex Vietnamese - Emacs supports a wide variety of international character sets, -including European and Vietnamese variants of the Latin alphabet, as -well as Arabic scripts, Brahmic scripts (for languages such as -Bengali, Hindi, and Thai), Cyrillic, Ethiopic, Georgian, Greek, Han -(for Chinese and Japanese), Hangul (for Korean), Hebrew and IPA@. -Emacs also supports various encodings of these characters that are used by -other internationalized software, such as word processors and mailers. - - Emacs allows editing text with international characters by supporting -all the related activities: - -@itemize @bullet -@item -You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and -pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as -compilers, spell-checkers, and mailers). Setting your language -environment (@pxref{Language Environments}) takes care of setting up the -coding systems and other options for a specific language or culture. -Alternatively, you can specify how Emacs should encode or decode text -for each command; see @ref{Text Coding}. - -@item -You can display non-@acronym{ASCII} characters encoded by the various -scripts. This works by using appropriate fonts on graphics displays -(@pxref{Defining Fontsets}), and by sending special codes to text -displays (@pxref{Terminal Coding}). If some characters are displayed -incorrectly, refer to @ref{Undisplayable Characters}, which describes -possible problems and explains how to solve them. - -@item -Characters from scripts whose natural ordering of text is from right -to left are reordered for display (@pxref{Bidirectional Editing}). -These scripts include Arabic, Hebrew, Syriac, Thaana, and a few -others. - -@item -You can insert non-@acronym{ASCII} characters or search for them. To do that, -you can specify an input method (@pxref{Select Input Method}) suitable -for your language, or use the default input method set up when you chose -your language environment. If -your keyboard can produce non-@acronym{ASCII} characters, you can select an -appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs -will accept those characters. Latin-1 characters can also be input by -using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}. - -With the X Window System, your locale should be set to an appropriate -value to make sure Emacs interprets keyboard input correctly; see -@ref{Language Environments, locales}. -@end itemize - - The rest of this chapter describes these issues in detail. - -@menu -* International Chars:: Basic concepts of multibyte characters. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How Emacs figures out which conversion to use. -* Specify Coding:: Specifying a file's coding system explicitly. -* Output Coding:: Choosing coding systems for output. -* Text Coding:: Choosing conversion to use for file text. -* Communication Coding:: Coding systems for interprocess communication. -* File Name Coding:: Coding systems for file @emph{names}. -* Terminal Coding:: Specifying coding systems for converting - terminal input and output. -* Fontsets:: Fontsets are collections of fonts - that cover the whole spectrum of characters. -* Defining Fontsets:: Defining a new fontset. -* Modifying Fontsets:: Modifying an existing fontset. -* Undisplayable Characters:: When characters don't display. -* Unibyte Mode:: You can pick one European character set - to use without multibyte characters. -* Charsets:: How Emacs groups its internal character codes. -* Bidirectional Editing:: Support for right-to-left scripts. -@end menu - -@node International Chars -@section Introduction to International Character Sets - - The users of international character sets and scripts have -established many more-or-less standard coding systems for storing -files. These coding systems are typically @dfn{multibyte}, meaning -that sequences of two or more bytes are used to represent individual -non-@acronym{ASCII} characters. - -@cindex Unicode - Internally, Emacs uses its own multibyte character encoding, which -is a superset of the @dfn{Unicode} standard. This internal encoding -allows characters from almost every known script to be intermixed in a -single buffer or string. Emacs translates between the multibyte -character encoding and various other coding systems when reading and -writing files, and when exchanging data with subprocesses. - -@kindex C-h h -@findex view-hello-file -@cindex undisplayable characters -@cindex @samp{?} in display - The command @kbd{C-h h} (@code{view-hello-file}) displays the file -@file{etc/HELLO}, which illustrates various scripts by showing -how to say ``hello'' in many languages. If some characters can't be -displayed on your terminal, they appear as @samp{?} or as hollow boxes -(@pxref{Undisplayable Characters}). - - Keyboards, even in the countries where these character sets are -used, generally don't have keys for all the characters in them. You -can insert characters that your keyboard does not support, using -@kbd{C-q} (@code{quoted-insert}) or @kbd{C-x 8 @key{RET}} -(@code{insert-char}). @xref{Inserting Text}. Emacs also supports -various @dfn{input methods}, typically one for each script or -language, which make it easier to type characters in the script. -@xref{Input Methods}. - -@kindex C-x RET - The prefix key @kbd{C-x @key{RET}} is used for commands that pertain -to multibyte characters, coding systems, and input methods. - -@kindex C-x = -@findex what-cursor-position - The command @kbd{C-x =} (@code{what-cursor-position}) shows -information about the character at point. In addition to the -character position, which was described in @ref{Position Info}, this -command displays how the character is encoded. For instance, it -displays the following line in the echo area for the character -@samp{c}: - -@smallexample -Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 -@end smallexample - - The four values after @samp{Char:} describe the character that -follows point, first by showing it and then by giving its character -code in decimal, octal and hex. For a non-@acronym{ASCII} multibyte -character, these are followed by @samp{file} and the character's -representation, in hex, in the buffer's coding system, if that coding -system encodes the character safely and with a single byte -(@pxref{Coding Systems}). If the character's encoding is longer than -one byte, Emacs shows @samp{file ...}. - - As a special case, if the character lies in the range 128 (0200 -octal) through 159 (0237 octal), it stands for a ``raw'' byte that -does not correspond to any specific displayable character. Such a -``character'' lies within the @code{eight-bit-control} character set, -and is displayed as an escaped octal character code. In this case, -@kbd{C-x =} shows @samp{part of display ...} instead of @samp{file}. - -@cindex character set of character at point -@cindex font of character at point -@cindex text properties at point -@cindex face at point - With a prefix argument (@kbd{C-u C-x =}), this command displays a -detailed description of the character in a window: - -@itemize @bullet -@item -The character set name, and the codes that identify the character -within that character set; @acronym{ASCII} characters are identified -as belonging to the @code{ascii} character set. - -@item -The character's script, syntax and categories. - -@item -What keys to type to input the character in the current input method -(if it supports the character). - -@item -The character's encodings, both internally in the buffer, and externally -if you were to save the file. - -@item -If you are running Emacs on a graphical display, the font name and -glyph code for the character. If you are running Emacs on a text -terminal, the code(s) sent to the terminal. - -@item -The character's text properties (@pxref{Text Properties,,, -elisp, the Emacs Lisp Reference Manual}), including any non-default -faces used to display the character, and any overlays containing it -(@pxref{Overlays,,, elisp, the same manual}). -@end itemize - - Here's an example, with some lines folded to fit into this manual: - -@smallexample - position: 1 of 1 (0%), column: 0 - character: @^e (displayed as @^e) (codepoint 234, #o352, #xea) - preferred charset: unicode (Unicode (ISO10646)) -code point in charset: 0xEA - script: latin - syntax: w which means: word - category: .:Base, L:Left-to-right (strong), c:Chinese, - j:Japanese, l:Latin, v:Viet - to input: type "C-x 8 RET HEX-CODEPOINT" or "C-x 8 RET NAME" - buffer code: #xC3 #xAA - file code: #xC3 #xAA (encoded by coding system utf-8-unix) - display: by this font (glyph code) - xft:-unknown-DejaVu Sans Mono-normal-normal- - normal-*-15-*-*-*-m-0-iso10646-1 (#xAC) - -Character code properties: customize what to show - name: LATIN SMALL LETTER E WITH CIRCUMFLEX - old-name: LATIN SMALL LETTER E CIRCUMFLEX - general-category: Ll (Letter, Lowercase) - decomposition: (101 770) ('e' '^') -@end smallexample - -@node Language Environments -@section Language Environments -@cindex language environments - - All supported character sets are supported in Emacs buffers whenever -multibyte characters are enabled; there is no need to select a -particular language in order to display its characters. -However, it is important to select a @dfn{language -environment} in order to set various defaults. Roughly speaking, the -language environment represents a choice of preferred script rather -than a choice of language. - - The language environment controls which coding systems to recognize -when reading text (@pxref{Recognize Coding}). This applies to files, -incoming mail, and any other text you read into Emacs. It may also -specify the default coding system to use when you create a file. Each -language environment also specifies a default input method. - -@findex set-language-environment -@vindex current-language-environment - To select a language environment, customize -@code{current-language-environment} or use the command @kbd{M-x -set-language-environment}. It makes no difference which buffer is -current when you use this command, because the effects apply globally -to the Emacs session. See the variable @code{language-info-alist} for -the list of supported language environments, and use the command -@kbd{C-h L @var{lang-env} @key{RET}} (@code{describe-language-environment}) -for more information about the language environment @var{lang-env}. -Supported language environments include: - -@quotation -@cindex ASCII -ASCII, -@cindex Arabic -Arabic, -@cindex Belarusian -Belarusian, -@cindex Bengali -Bengali, -@cindex Brazilian Portuguese -Brazilian Portuguese, -@cindex Bulgarian -Bulgarian, -@cindex Burmese -Burmese, -@cindex Cham -Cham, -@cindex Chinese -Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, -Chinese-GB18030, Chinese-GBK, -@cindex Croatian -Croatian, -@cindex Cyrillic -Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8, -@cindex Czech -Czech, -@cindex Devanagari -Devanagari, -@cindex Dutch -Dutch, -@cindex English -English, -@cindex Esperanto -Esperanto, -@cindex Ethiopic -Ethiopic, -@cindex French -French, -@cindex Georgian -Georgian, -@cindex German -German, -@cindex Greek -Greek, -@cindex Gujarati -Gujarati, -@cindex Hebrew -Hebrew, -@cindex IPA -IPA, -@cindex Italian -Italian, -@cindex Japanese -Japanese, -@cindex Kannada -Kannada, -@cindex Khmer -Khmer, -@cindex Korean -Korean, -@cindex Lao -Lao, -@cindex Latin -Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Latin-6, Latin-7, -Latin-8, Latin-9, -@cindex Latvian -Latvian, -@cindex Lithuanian -Lithuanian, -@cindex Malayalam -Malayalam, -@cindex Oriya -Oriya, -@cindex Persian -Persian, -@cindex Polish -Polish, -@cindex Punjabi -Punjabi, -@cindex Romanian -Romanian, -@cindex Russian -Russian, -@cindex Sinhala -Sinhala, -@cindex Slovak -Slovak, -@cindex Slovenian -Slovenian, -@cindex Spanish -Spanish, -@cindex Swedish -Swedish, -@cindex TaiViet -TaiViet, -@cindex Tajik -Tajik, -@cindex Tamil -Tamil, -@cindex Telugu -Telugu, -@cindex Thai -Thai, -@cindex Tibetan -Tibetan, -@cindex Turkish -Turkish, -@cindex UTF-8 -UTF-8, -@cindex Ukrainian -Ukrainian, -@cindex Vietnamese -Vietnamese, -@cindex Welsh -Welsh, and -@cindex Windows-1255 -Windows-1255. -@end quotation - - To display the script(s) used by your language environment on a -graphical display, you need to have suitable fonts. -@xref{Fontsets}, for more details about setting up your fonts. - -@findex set-locale-environment -@vindex locale-language-names -@vindex locale-charset-language-names -@cindex locales - Some operating systems let you specify the character-set locale you -are using by setting the locale environment variables @env{LC_ALL}, -@env{LC_CTYPE}, or @env{LANG}. (If more than one of these is -set, the first one that is nonempty specifies your locale for this -purpose.) During startup, Emacs looks up your character-set locale's -name in the system locale alias table, matches its canonical name -against entries in the value of the variables -@code{locale-charset-language-names} and @code{locale-language-names} -(the former overrides the latter), -and selects the corresponding language environment if a match is found. -It also adjusts the display -table and terminal coding system, the locale coding system, the -preferred coding system as needed for the locale, and---last but not -least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard. - -@c This seems unlikely, doesn't it? - If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG} -environment variables while running Emacs (by using @kbd{M-x setenv}), -you may want to invoke the @code{set-locale-environment} -function afterwards to readjust the language environment from the new -locale. - -@vindex locale-preferred-coding-systems - The @code{set-locale-environment} function normally uses the preferred -coding system established by the language environment to decode system -messages. But if your locale matches an entry in the variable -@code{locale-preferred-coding-systems}, Emacs uses the corresponding -coding system instead. For example, if the locale @samp{ja_JP.PCK} -matches @code{japanese-shift-jis} in -@code{locale-preferred-coding-systems}, Emacs uses that encoding even -though it might normally use @code{japanese-iso-8bit}. - - You can override the language environment chosen at startup with -explicit use of the command @code{set-language-environment}, or with -customization of @code{current-language-environment} in your init -file. - -@kindex C-h L -@findex describe-language-environment - To display information about the effects of a certain language -environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env} -@key{RET}} (@code{describe-language-environment}). This tells you -which languages this language environment is useful for, and lists the -character sets, coding systems, and input methods that go with it. It -also shows some sample text to illustrate scripts used in this -language environment. If you give an empty input for @var{lang-env}, -this command describes the chosen language environment. - -@vindex set-language-environment-hook - You can customize any language environment with the normal hook -@code{set-language-environment-hook}. The command -@code{set-language-environment} runs that hook after setting up the new -language environment. The hook functions can test for a specific -language environment by checking the variable -@code{current-language-environment}. This hook is where you should -put non-default settings for specific language environments, such as -coding systems for keyboard input and terminal output, the default -input method, etc. - -@vindex exit-language-environment-hook - Before it starts to set up the new language environment, -@code{set-language-environment} first runs the hook -@code{exit-language-environment-hook}. This hook is useful for undoing -customizations that were made with @code{set-language-environment-hook}. -For instance, if you set up a special key binding in a specific language -environment using @code{set-language-environment-hook}, you should set -up @code{exit-language-environment-hook} to restore the normal binding -for that key. - -@node Input Methods -@section Input Methods - -@cindex input methods - An @dfn{input method} is a kind of character conversion designed -specifically for interactive input. In Emacs, typically each language -has its own input method; sometimes several languages that use the same -characters can share one input method. A few languages support several -input methods. - - The simplest kind of input method works by mapping @acronym{ASCII} letters -into another alphabet; this allows you to use one other alphabet -instead of @acronym{ASCII}. The Greek and Russian input methods -work this way. - - A more powerful technique is composition: converting sequences of -characters into one letter. Many European input methods use composition -to produce a single non-@acronym{ASCII} letter from a sequence that consists of a -letter followed by accent characters (or vice versa). For example, some -methods convert the sequence @kbd{o ^} into a single accented letter. -These input methods have no special commands of their own; all they do -is compose sequences of printing characters. - - The input methods for syllabic scripts typically use mapping followed -by composition. The input methods for Thai and Korean work this way. -First, letters are mapped into symbols for particular sounds or tone -marks; then, sequences of these that make up a whole syllable are -mapped into one syllable sign. - - Chinese and Japanese require more complex methods. In Chinese input -methods, first you enter the phonetic spelling of a Chinese word (in -input method @code{chinese-py}, among others), or a sequence of -portions of the character (input methods @code{chinese-4corner} and -@code{chinese-sw}, and others). One input sequence typically -corresponds to many possible Chinese characters. You select the one -you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n}, -@kbd{C-p} (or the arrow keys), and digits, which have special meanings -in this situation. - - The possible characters are conceptually arranged in several rows, -with each row holding up to 10 alternatives. Normally, Emacs displays -just one row at a time, in the echo area; @code{(@var{i}/@var{j})} -appears at the beginning, to indicate that this is the @var{i}th row -out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to -display the next row or the previous row. - - Type @kbd{C-f} and @kbd{C-b} to move forward and backward among -the alternatives in the current row. As you do this, Emacs highlights -the current alternative with a special color; type @code{C-@key{SPC}} -to select the current alternative and use it as input. The -alternatives in the row are also numbered; the number appears before -the alternative. Typing a number selects the associated alternative -of the current row and uses it as input. - - @key{TAB} in these Chinese input methods displays a buffer showing -all the possible characters at once; then clicking @kbd{Mouse-2} on -one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b}, -@kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they -do the highlighting in the buffer showing the possible characters, -rather than in the echo area. - - In Japanese input methods, first you input a whole word using -phonetic spelling; then, after the word is in the buffer, Emacs -converts it into one or more characters using a large dictionary. One -phonetic spelling corresponds to a number of different Japanese words; -to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through -the alternatives. - - Sometimes it is useful to cut off input method processing so that the -characters you have just entered will not combine with subsequent -characters. For example, in input method @code{latin-1-postfix}, the -sequence @kbd{o ^} combines to form an @samp{o} with an accent. What if -you want to enter them as separate characters? - - One way is to type the accent twice; this is a special feature for -entering the separate letter and accent. For example, @kbd{o ^ ^} gives -you the two characters @samp{o^}. Another way is to type another letter -after the @kbd{o}---something that won't combine with that---and -immediately delete it. For example, you could type @kbd{o o @key{DEL} -^} to get separate @samp{o} and @samp{^}. - - Another method, more general but not quite as easy to type, is to use -@kbd{C-\ C-\} between two characters to stop them from combining. This -is the command @kbd{C-\} (@code{toggle-input-method}) used twice. -@ifnottex -@xref{Select Input Method}. -@end ifnottex - -@cindex incremental search, input method interference - @kbd{C-\ C-\} is especially useful inside an incremental search, -because it stops waiting for more characters to combine, and starts -searching for what you have already entered. - - To find out how to input the character after point using the current -input method, type @kbd{C-u C-x =}. @xref{Position Info}. - -@vindex input-method-verbose-flag -@vindex input-method-highlight-flag - The variables @code{input-method-highlight-flag} and -@code{input-method-verbose-flag} control how input methods explain -what is happening. If @code{input-method-highlight-flag} is -non-@code{nil}, the partial sequence is highlighted in the buffer (for -most input methods---some disable this feature). If -@code{input-method-verbose-flag} is non-@code{nil}, the list of -possible characters to type next is displayed in the echo area (but -not when you are in the minibuffer). - - Another facility for typing characters not on your keyboard is by -using @kbd{C-x 8 @key{RET}} (@code{insert-char}) to insert a single -character based on its Unicode name or code-point; see @ref{Inserting -Text}. - -@node Select Input Method -@section Selecting an Input Method - -@table @kbd -@item C-\ -Enable or disable use of the selected input method (@code{toggle-input-method}). - -@item C-x @key{RET} C-\ @var{method} @key{RET} -Select a new input method for the current buffer (@code{set-input-method}). - -@item C-h I @var{method} @key{RET} -@itemx C-h C-\ @var{method} @key{RET} -@findex describe-input-method -@kindex C-h I -@kindex C-h C-\ -Describe the input method @var{method} (@code{describe-input-method}). -By default, it describes the current input method (if any). This -description should give you the full details of how to use any -particular input method. - -@item M-x list-input-methods -Display a list of all the supported input methods. -@end table - -@findex set-input-method -@vindex current-input-method -@kindex C-x RET C-\ - To choose an input method for the current buffer, use @kbd{C-x -@key{RET} C-\} (@code{set-input-method}). This command reads the -input method name from the minibuffer; the name normally starts with the -language environment that it is meant to be used with. The variable -@code{current-input-method} records which input method is selected. - -@findex toggle-input-method -@kindex C-\ - Input methods use various sequences of @acronym{ASCII} characters to -stand for non-@acronym{ASCII} characters. Sometimes it is useful to -turn off the input method temporarily. To do this, type @kbd{C-\} -(@code{toggle-input-method}). To reenable the input method, type -@kbd{C-\} again. - - If you type @kbd{C-\} and you have not yet selected an input method, -it prompts you to specify one. This has the same effect as using -@kbd{C-x @key{RET} C-\} to specify an input method. - - When invoked with a numeric argument, as in @kbd{C-u C-\}, -@code{toggle-input-method} always prompts you for an input method, -suggesting the most recently selected one as the default. - -@vindex default-input-method - Selecting a language environment specifies a default input method for -use in various buffers. When you have a default input method, you can -select it in the current buffer by typing @kbd{C-\}. The variable -@code{default-input-method} specifies the default input method -(@code{nil} means there is none). - - In some language environments, which support several different input -methods, you might want to use an input method different from the -default chosen by @code{set-language-environment}. You can instruct -Emacs to select a different default input method for a certain -language environment, if you wish, by using -@code{set-language-environment-hook} (@pxref{Language Environments, -set-language-environment-hook}). For example: - -@lisp -(defun my-chinese-setup () - "Set up my private Chinese environment." - (if (equal current-language-environment "Chinese-GB") - (setq default-input-method "chinese-tonepy"))) -(add-hook 'set-language-environment-hook 'my-chinese-setup) -@end lisp - -@noindent -This sets the default input method to be @code{chinese-tonepy} -whenever you choose a Chinese-GB language environment. - -You can instruct Emacs to activate a certain input method -automatically. For example: - -@lisp -(add-hook 'text-mode-hook - (lambda () (set-input-method "german-prefix"))) -@end lisp - -@noindent -This automatically activates the input method ``german-prefix'' in -Text mode. - -@findex quail-set-keyboard-layout - Some input methods for alphabetic scripts work by (in effect) -remapping the keyboard to emulate various keyboard layouts commonly used -for those scripts. How to do this remapping properly depends on your -actual keyboard layout. To specify which layout your keyboard has, use -the command @kbd{M-x quail-set-keyboard-layout}. - -@findex quail-show-key - You can use the command @kbd{M-x quail-show-key} to show what key (or -key sequence) to type in order to input the character following point, -using the selected keyboard layout. The command @kbd{C-u C-x =} also -shows that information, in addition to other information about the -character. - -@findex list-input-methods - @kbd{M-x list-input-methods} displays a list of all the supported -input methods. The list gives information about each input method, -including the string that stands for it in the mode line. - -@node Coding Systems -@section Coding Systems -@cindex coding systems - - Users of various languages have established many more-or-less standard -coding systems for representing them. Emacs does not use these coding -systems internally; instead, it converts from various coding systems to -its own system when reading data, and converts the internal coding -system to other coding systems when writing data. Conversion is -possible in reading or writing files, in sending or receiving from the -terminal, and in exchanging data with subprocesses. - - Emacs assigns a name to each coding system. Most coding systems are -used for one language, and the name of the coding system starts with -the language name. Some coding systems are used for several -languages; their names usually start with @samp{iso}. There are also -special coding systems, such as @code{no-conversion}, @code{raw-text}, -and @code{emacs-internal}. - -@cindex international files from DOS/Windows systems - A special class of coding systems, collectively known as -@dfn{codepages}, is designed to support text encoded by MS-Windows and -MS-DOS software. The names of these coding systems are -@code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the -codepage. You can use these encodings just like any other coding -system; for example, to visit a file encoded in codepage 850, type -@kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename} -@key{RET}}. - - In addition to converting various representations of non-@acronym{ASCII} -characters, a coding system can perform end-of-line conversion. Emacs -handles three different conventions for how to separate lines in a file: -newline (``unix''), carriage-return linefeed (``dos''), and just -carriage-return (``mac''). - -@table @kbd -@item C-h C @var{coding} @key{RET} -Describe coding system @var{coding} (@code{describe-coding-system}). - -@item C-h C @key{RET} -Describe the coding systems currently in use. - -@item M-x list-coding-systems -Display a list of all the supported coding systems. -@end table - -@kindex C-h C -@findex describe-coding-system - The command @kbd{C-h C} (@code{describe-coding-system}) displays -information about particular coding systems, including the end-of-line -conversion specified by those coding systems. You can specify a coding -system name as the argument; alternatively, with an empty argument, it -describes the coding systems currently selected for various purposes, -both in the current buffer and as the defaults, and the priority list -for recognizing coding systems (@pxref{Recognize Coding}). - -@findex list-coding-systems - To display a list of all the supported coding systems, type @kbd{M-x -list-coding-systems}. The list gives information about each coding -system, including the letter that stands for it in the mode line -(@pxref{Mode Line}). - -@cindex end-of-line conversion -@cindex line endings -@cindex MS-DOS end-of-line conversion -@cindex Macintosh end-of-line conversion - Each of the coding systems that appear in this list---except for -@code{no-conversion}, which means no conversion of any kind---specifies -how and whether to convert printing characters, but leaves the choice of -end-of-line conversion to be decided based on the contents of each file. -For example, if the file appears to use the sequence carriage-return -linefeed to separate lines, DOS end-of-line conversion will be used. - - Each of the listed coding systems has three variants, which specify -exactly what to do for end-of-line conversion: - -@table @code -@item @dots{}-unix -Don't do any end-of-line conversion; assume the file uses -newline to separate lines. (This is the convention normally used -on Unix and GNU systems, and Mac OS X.) - -@item @dots{}-dos -Assume the file uses carriage-return linefeed to separate lines, and do -the appropriate conversion. (This is the convention normally used on -Microsoft systems.@footnote{It is also specified for MIME @samp{text/*} -bodies and in other network transport contexts. It is different -from the SGML reference syntax record-start/record-end format, which -Emacs doesn't support directly.}) - -@item @dots{}-mac -Assume the file uses carriage-return to separate lines, and do the -appropriate conversion. (This was the convention used on the -Macintosh system prior to OS X.) -@end table - - These variant coding systems are omitted from the -@code{list-coding-systems} display for brevity, since they are entirely -predictable. For example, the coding system @code{iso-latin-1} has -variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and -@code{iso-latin-1-mac}. - -@cindex @code{undecided}, coding system - The coding systems @code{unix}, @code{dos}, and @code{mac} are -aliases for @code{undecided-unix}, @code{undecided-dos}, and -@code{undecided-mac}, respectively. These coding systems specify only -the end-of-line conversion, and leave the character code conversion to -be deduced from the text itself. - -@cindex @code{raw-text}, coding system - The coding system @code{raw-text} is good for a file which is mainly -@acronym{ASCII} text, but may contain byte values above 127 that are -not meant to encode non-@acronym{ASCII} characters. With -@code{raw-text}, Emacs copies those byte values unchanged, and sets -@code{enable-multibyte-characters} to @code{nil} in the current buffer -so that they will be interpreted properly. @code{raw-text} handles -end-of-line conversion in the usual way, based on the data -encountered, and has the usual three variants to specify the kind of -end-of-line conversion to use. - -@cindex @code{no-conversion}, coding system - In contrast, the coding system @code{no-conversion} specifies no -character code conversion at all---none for non-@acronym{ASCII} byte values and -none for end of line. This is useful for reading or writing binary -files, tar files, and other files that must be examined verbatim. It, -too, sets @code{enable-multibyte-characters} to @code{nil}. - - The easiest way to edit a file with no conversion of any kind is with -the @kbd{M-x find-file-literally} command. This uses -@code{no-conversion}, and also suppresses other Emacs features that -might convert the file contents before you see them. @xref{Visiting}. - -@cindex @code{emacs-internal}, coding system - The coding system @code{emacs-internal} (or @code{utf-8-emacs}, -which is equivalent) means that the file contains non-@acronym{ASCII} -characters stored with the internal Emacs encoding. This coding -system handles end-of-line conversion based on the data encountered, -and has the usual three variants to specify the kind of end-of-line -conversion. - -@node Recognize Coding -@section Recognizing Coding Systems - - Whenever Emacs reads a given piece of text, it tries to recognize -which coding system to use. This applies to files being read, output -from subprocesses, text from X selections, etc. Emacs can select the -right coding system automatically most of the time---once you have -specified your preferences. - - Some coding systems can be recognized or distinguished by which byte -sequences appear in the data. However, there are coding systems that -cannot be distinguished, not even potentially. For example, there is no -way to distinguish between Latin-1 and Latin-2; they use the same byte -values with different meanings. - - Emacs handles this situation by means of a priority list of coding -systems. Whenever Emacs reads a file, if you do not specify the coding -system to use, Emacs checks the data against each coding system, -starting with the first in priority and working down the list, until it -finds a coding system that fits the data. Then it converts the file -contents assuming that they are represented in this coding system. - - The priority list of coding systems depends on the selected language -environment (@pxref{Language Environments}). For example, if you use -French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use -Czech, you probably want Latin-2 to be preferred. This is one of the -reasons to specify a language environment. - -@findex prefer-coding-system - However, you can alter the coding system priority list in detail -with the command @kbd{M-x prefer-coding-system}. This command reads -the name of a coding system from the minibuffer, and adds it to the -front of the priority list, so that it is preferred to all others. If -you use this command several times, each use adds one element to the -front of the priority list. - - If you use a coding system that specifies the end-of-line conversion -type, such as @code{iso-8859-1-dos}, what this means is that Emacs -should attempt to recognize @code{iso-8859-1} with priority, and should -use DOS end-of-line conversion when it does recognize @code{iso-8859-1}. - -@vindex file-coding-system-alist - Sometimes a file name indicates which coding system to use for the -file. The variable @code{file-coding-system-alist} specifies this -correspondence. There is a special function -@code{modify-coding-system-alist} for adding elements to this list. For -example, to read and write all @samp{.txt} files using the coding system -@code{chinese-iso-8bit}, you can execute this Lisp expression: - -@smallexample -(modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit) -@end smallexample - -@noindent -The first argument should be @code{file}, the second argument should be -a regular expression that determines which files this applies to, and -the third argument says which coding system to use for these files. - -@vindex inhibit-eol-conversion -@cindex DOS-style end-of-line display - Emacs recognizes which kind of end-of-line conversion to use based on -the contents of the file: if it sees only carriage-returns, or only -carriage-return linefeed sequences, then it chooses the end-of-line -conversion accordingly. You can inhibit the automatic use of -end-of-line conversion by setting the variable @code{inhibit-eol-conversion} -to non-@code{nil}. If you do that, DOS-style files will be displayed -with the @samp{^M} characters visible in the buffer; some people -prefer this to the more subtle @samp{(DOS)} end-of-line type -indication near the left edge of the mode line (@pxref{Mode Line, -eol-mnemonic}). - -@vindex inhibit-iso-escape-detection -@cindex escape sequences in files - By default, the automatic detection of coding system is sensitive to -escape sequences. If Emacs sees a sequence of characters that begin -with an escape character, and the sequence is valid as an ISO-2022 -code, that tells Emacs to use one of the ISO-2022 encodings to decode -the file. - - However, there may be cases that you want to read escape sequences -in a file as is. In such a case, you can set the variable -@code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code -detection ignores any escape sequences, and never uses an ISO-2022 -encoding. The result is that all escape sequences become visible in -the buffer. - - The default value of @code{inhibit-iso-escape-detection} is -@code{nil}. We recommend that you not change it permanently, only for -one specific operation. That's because some Emacs Lisp source files -in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the -coding system @code{iso-2022-7bit}, and they won't be -decoded correctly when you visit those files if you suppress the -escape sequence detection. -@c I count a grand total of 3 such files, so is the above really true? - -@vindex auto-coding-alist -@vindex auto-coding-regexp-alist - The variables @code{auto-coding-alist} and -@code{auto-coding-regexp-alist} are -the strongest way to specify the coding system for certain patterns of -file names, or for files containing certain patterns, respectively. -These variables even override @samp{-*-coding:-*-} tags in the file -itself (@pxref{Specify Coding}). For example, Emacs -uses @code{auto-coding-alist} for tar and archive files, to prevent it -from being confused by a @samp{-*-coding:-*-} tag in a member of the -archive and thinking it applies to the archive file as a whole. -@ignore -@c This describes old-style BABYL files, which are no longer relevant. -Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that -RMAIL files, whose names in general don't match any particular -pattern, are decoded correctly. -@end ignore - -@vindex auto-coding-functions - Another way to specify a coding system is with the variable -@code{auto-coding-functions}. For example, one of the builtin -@code{auto-coding-functions} detects the encoding for XML files. -Unlike the previous two, this variable does not override any -@samp{-*-coding:-*-} tag. - -@node Specify Coding -@section Specifying a File's Coding System - - If Emacs recognizes the encoding of a file incorrectly, you can -reread the file using the correct coding system with @kbd{C-x -@key{RET} r} (@code{revert-buffer-with-coding-system}). This command -prompts for the coding system to use. To see what coding system Emacs -actually used to decode the file, look at the coding system mnemonic -letter near the left edge of the mode line (@pxref{Mode Line}), or -type @kbd{C-h C} (@code{describe-coding-system}). - -@vindex coding - You can specify the coding system for a particular file in the file -itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning, -or a local variables list at the end (@pxref{File Variables}). You do -this by defining a value for the ``variable'' named @code{coding}. -Emacs does not really have a variable @code{coding}; instead of -setting a variable, this uses the specified coding system for the -file. For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies -use of the Latin-1 coding system, as well as C mode. When you specify -the coding explicitly in the file, that overrides -@code{file-coding-system-alist}. - -@node Output Coding -@section Choosing Coding Systems for Output - -@vindex buffer-file-coding-system - Once Emacs has chosen a coding system for a buffer, it stores that -coding system in @code{buffer-file-coding-system}. That makes it the -default for operations that write from this buffer into a file, such -as @code{save-buffer} and @code{write-region}. You can specify a -different coding system for further file output from the buffer using -@code{set-buffer-file-coding-system} (@pxref{Text Coding}). - - You can insert any character Emacs supports into any Emacs buffer, -but most coding systems can only handle a subset of these characters. -Therefore, it's possible that the characters you insert cannot be -encoded with the coding system that will be used to save the buffer. -For example, you could visit a text file in Polish, encoded in -@code{iso-8859-2}, and add some Russian words to it. When you save -that buffer, Emacs cannot use the current value of -@code{buffer-file-coding-system}, because the characters you added -cannot be encoded by that coding system. - - When that happens, Emacs tries the most-preferred coding system (set -by @kbd{M-x prefer-coding-system} or @kbd{M-x -set-language-environment}). If that coding system can safely encode -all of the characters in the buffer, Emacs uses it, and stores its -value in @code{buffer-file-coding-system}. Otherwise, Emacs displays -a list of coding systems suitable for encoding the buffer's contents, -and asks you to choose one of those coding systems. - - If you insert the unsuitable characters in a mail message, Emacs -behaves a bit differently. It additionally checks whether the -@c What determines this? -most-preferred coding system is recommended for use in MIME messages; -if not, it informs you of this fact and prompts you for another coding -system. This is so you won't inadvertently send a message encoded in -a way that your recipient's mail software will have difficulty -decoding. (You can still use an unsuitable coding system if you enter -its name at the prompt.) - -@c It seems that select-message-coding-system does this. -@c Both sendmail.el and smptmail.el call it; i.e., smtpmail.el still -@c obeys sendmail-coding-system. -@vindex sendmail-coding-system - When you send a mail message (@pxref{Sending Mail}), -Emacs has four different ways to determine the coding system to use -for encoding the message text. It tries the buffer's own value of -@code{buffer-file-coding-system}, if that is non-@code{nil}. -Otherwise, it uses the value of @code{sendmail-coding-system}, if that -is non-@code{nil}. The third way is to use the default coding system -for new files, which is controlled by your choice of language -@c i.e., default-sendmail-coding-system -environment, if that is non-@code{nil}. If all of these three values -are @code{nil}, Emacs encodes outgoing mail using the Latin-1 coding -system. -@c FIXME? Where does the Latin-1 default come in? - -@node Text Coding -@section Specifying a Coding System for File Text - - In cases where Emacs does not automatically choose the right coding -system for a file's contents, you can use these commands to specify -one: - -@table @kbd -@item C-x @key{RET} f @var{coding} @key{RET} -Use coding system @var{coding} to save or revisit the file in -the current buffer (@code{set-buffer-file-coding-system}). - -@item C-x @key{RET} c @var{coding} @key{RET} -Specify coding system @var{coding} for the immediately following -command (@code{universal-coding-system-argument}). - -@item C-x @key{RET} r @var{coding} @key{RET} -Revisit the current file using the coding system @var{coding} -(@code{revert-buffer-with-coding-system}). - -@item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET} -Convert a region that was decoded using coding system @var{wrong}, -decoding it using coding system @var{right} instead. -@end table - -@kindex C-x RET f -@findex set-buffer-file-coding-system - The command @kbd{C-x @key{RET} f} -(@code{set-buffer-file-coding-system}) sets the file coding system for -the current buffer (i.e., the coding system to use when saving or -reverting the file). You specify which coding system using the -minibuffer. You can also invoke this command by clicking with -@kbd{Mouse-3} on the coding system indicator in the mode line -(@pxref{Mode Line}). - - If you specify a coding system that cannot handle all the characters -in the buffer, Emacs will warn you about the troublesome characters, -and ask you to choose another coding system, when you try to save the -buffer (@pxref{Output Coding}). - -@cindex specify end-of-line conversion - You can also use this command to specify the end-of-line conversion -(@pxref{Coding Systems, end-of-line conversion}) for encoding the -current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will -cause Emacs to save the current buffer's text with DOS-style -carriage-return linefeed line endings. - -@kindex C-x RET c -@findex universal-coding-system-argument - Another way to specify the coding system for a file is when you visit -the file. First use the command @kbd{C-x @key{RET} c} -(@code{universal-coding-system-argument}); this command uses the -minibuffer to read a coding system name. After you exit the minibuffer, -the specified coding system is used for @emph{the immediately following -command}. - - So if the immediately following command is @kbd{C-x C-f}, for example, -it reads the file using that coding system (and records the coding -system for when you later save the file). Or if the immediately following -command is @kbd{C-x C-w}, it writes the file using that coding system. -When you specify the coding system for saving in this way, instead -of with @kbd{C-x @key{RET} f}, there is no warning if the buffer -contains characters that the coding system cannot handle. - - Other file commands affected by a specified coding system include -@kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants -of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that -start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the -immediately following command does not use the coding system, then -@kbd{C-x @key{RET} c} ultimately has no effect. - - An easy way to visit a file with no conversion is with the @kbd{M-x -find-file-literally} command. @xref{Visiting}. - - The default value of the variable @code{buffer-file-coding-system} -specifies the choice of coding system to use when you create a new file. -It applies when you find a new file, and when you create a buffer and -then save it in a file. Selecting a language environment typically sets -this variable to a good choice of default coding system for that language -environment. - -@kindex C-x RET r -@findex revert-buffer-with-coding-system - If you visit a file with a wrong coding system, you can correct this -with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}). -This visits the current file again, using a coding system you specify. - -@findex recode-region - If a piece of text has already been inserted into a buffer using the -wrong coding system, you can redo the decoding of it using @kbd{M-x -recode-region}. This prompts you for the proper coding system, then -for the wrong coding system that was actually used, and does the -conversion. It first encodes the region using the wrong coding system, -then decodes it again using the proper coding system. - -@node Communication Coding -@section Coding Systems for Interprocess Communication - - This section explains how to specify coding systems for use -in communication with other processes. - -@table @kbd -@item C-x @key{RET} x @var{coding} @key{RET} -Use coding system @var{coding} for transferring selections to and from -other graphical applications (@code{set-selection-coding-system}). - -@item C-x @key{RET} X @var{coding} @key{RET} -Use coding system @var{coding} for transferring @emph{one} -selection---the next one---to or from another graphical application -(@code{set-next-selection-coding-system}). - -@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET} -Use coding systems @var{input-coding} and @var{output-coding} for -subprocess input and output in the current buffer -(@code{set-buffer-process-coding-system}). -@end table - -@kindex C-x RET x -@kindex C-x RET X -@findex set-selection-coding-system -@findex set-next-selection-coding-system - The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system}) -specifies the coding system for sending selected text to other windowing -applications, and for receiving the text of selections made in other -applications. This command applies to all subsequent selections, until -you override it by using the command again. The command @kbd{C-x -@key{RET} X} (@code{set-next-selection-coding-system}) specifies the -coding system for the next selection made in Emacs or read by Emacs. - -@vindex x-select-request-type - The variable @code{x-select-request-type} specifies the data type to -request from the X Window System for receiving text selections from -other applications. If the value is @code{nil} (the default), Emacs -tries @code{UTF8_STRING} and @code{COMPOUND_TEXT}, in this order, and -uses various heuristics to choose the more appropriate of the two -results; if none of these succeed, Emacs falls back on @code{STRING}. -If the value of @code{x-select-request-type} is one of the symbols -@code{COMPOUND_TEXT}, @code{UTF8_STRING}, @code{STRING}, or -@code{TEXT}, Emacs uses only that request type. If the value is a -list of some of these symbols, Emacs tries only the request types in -the list, in order, until one of them succeeds, or until the list is -exhausted. - -@kindex C-x RET p -@findex set-buffer-process-coding-system - The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system}) -specifies the coding system for input and output to a subprocess. This -command applies to the current buffer; normally, each subprocess has its -own buffer, and thus you can use this command to specify translation to -and from a particular subprocess by giving the command in the -corresponding buffer. - - You can also use @kbd{C-x @key{RET} c} -(@code{universal-coding-system-argument}) just before the command that -runs or starts a subprocess, to specify the coding system for -communicating with that subprocess. @xref{Text Coding}. - - The default for translation of process input and output depends on the -current language environment. - -@vindex locale-coding-system -@cindex decoding non-@acronym{ASCII} keyboard input on X - The variable @code{locale-coding-system} specifies a coding system -to use when encoding and decoding system strings such as system error -messages and @code{format-time-string} formats and time stamps. That -coding system is also used for decoding non-@acronym{ASCII} keyboard -input on the X Window System. You should choose a coding system that is compatible -with the underlying system's text representation, which is normally -specified by one of the environment variables @env{LC_ALL}, -@env{LC_CTYPE}, and @env{LANG}. (The first one, in the order -specified above, whose value is nonempty is the one that determines -the text representation.) - -@node File Name Coding -@section Coding Systems for File Names - -@table @kbd -@item C-x @key{RET} F @var{coding} @key{RET} -Use coding system @var{coding} for encoding and decoding file -names (@code{set-file-name-coding-system}). -@end table - -@findex set-file-name-coding-system -@kindex C-x @key{RET} F -@cindex file names with non-@acronym{ASCII} characters - The command @kbd{C-x @key{RET} F} (@code{set-file-name-coding-system}) -specifies a coding system to use for encoding file @emph{names}. It -has no effect on reading and writing the @emph{contents} of files. - -@vindex file-name-coding-system - In fact, all this command does is set the value of the variable -@code{file-name-coding-system}. If you set the variable to a coding -system name (as a Lisp symbol or a string), Emacs encodes file names -using that coding system for all file operations. This makes it -possible to use non-@acronym{ASCII} characters in file names---or, at -least, those non-@acronym{ASCII} characters that the specified coding -system can encode. - - If @code{file-name-coding-system} is @code{nil}, Emacs uses a -default coding system determined by the selected language environment, -and stored in the @code{default-file-name-coding-system} variable. -@c FIXME? Is this correct? What is the "default language environment"? -In the default language environment, non-@acronym{ASCII} characters in -file names are not encoded specially; they appear in the file system -using the internal Emacs representation. - -@cindex file-name encoding, MS-Windows -@vindex w32-unicode-filenames - When Emacs runs on MS-Windows versions that are descendants of the -NT family (Windows 2000, XP, Vista, Windows 7, and Windows 8), the -value of @code{file-name-coding-system} is largely ignored, as Emacs -by default uses APIs that allow to pass Unicode file names directly. -By contrast, on Windows 9X, file names are encoded using -@code{file-name-coding-system}, which should be set to the codepage -(@pxref{Coding Systems, codepage}) pertinent for the current system -locale. The value of the variable @code{w32-unicode-filenames} -controls whether Emacs uses the Unicode APIs when it calls OS -functions that accept file names. This variable is set by the startup -code to @code{nil} on Windows 9X, and to @code{t} on newer versions of -MS-Windows. - - @strong{Warning:} if you change @code{file-name-coding-system} (or the -language environment) in the middle of an Emacs session, problems can -result if you have already visited files whose names were encoded using -the earlier coding system and cannot be encoded (or are encoded -differently) under the new coding system. If you try to save one of -these buffers under the visited file name, saving may use the wrong file -name, or it may encounter an error. If such a problem happens, use @kbd{C-x -C-w} to specify a new file name for that buffer. - -@findex recode-file-name - If a mistake occurs when encoding a file name, use the command -@kbd{M-x recode-file-name} to change the file name's coding -system. This prompts for an existing file name, its old coding -system, and the coding system to which you wish to convert. - -@node Terminal Coding -@section Coding Systems for Terminal I/O - -@table @kbd -@item C-x @key{RET} t @var{coding} @key{RET} -Use coding system @var{coding} for terminal output -(@code{set-terminal-coding-system}). - -@item C-x @key{RET} k @var{coding} @key{RET} -Use coding system @var{coding} for keyboard input -(@code{set-keyboard-coding-system}). -@end table - -@kindex C-x RET t -@findex set-terminal-coding-system - The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system}) -specifies the coding system for terminal output. If you specify a -character code for terminal output, all characters output to the -terminal are translated into that coding system. - - This feature is useful for certain character-only terminals built to -support specific languages or character sets---for example, European -terminals that support one of the ISO Latin character sets. You need to -specify the terminal coding system when using multibyte text, so that -Emacs knows which characters the terminal can actually handle. - - By default, output to the terminal is not translated at all, unless -Emacs can deduce the proper coding system from your terminal type or -your locale specification (@pxref{Language Environments}). - -@kindex C-x RET k -@findex set-keyboard-coding-system -@vindex keyboard-coding-system - The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}), -or the variable @code{keyboard-coding-system}, specifies the coding -system for keyboard input. Character-code translation of keyboard -input is useful for terminals with keys that send non-@acronym{ASCII} -graphic characters---for example, some terminals designed for ISO -Latin-1 or subsets of it. - - By default, keyboard input is translated based on your system locale -setting. If your terminal does not really support the encoding -implied by your locale (for example, if you find it inserts a -non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set -@code{keyboard-coding-system} to @code{nil} to turn off encoding. -You can do this by putting - -@lisp -(set-keyboard-coding-system nil) -@end lisp - -@noindent -in your init file. - - There is a similarity between using a coding system translation for -keyboard input, and using an input method: both define sequences of -keyboard input that translate into single characters. However, input -methods are designed to be convenient for interactive use by humans, and -the sequences that are translated are typically sequences of @acronym{ASCII} -printing characters. Coding systems typically translate sequences of -non-graphic characters. - -@node Fontsets -@section Fontsets -@cindex fontsets - - A font typically defines shapes for a single alphabet or script. -Therefore, displaying the entire range of scripts that Emacs supports -requires a collection of many fonts. In Emacs, such a collection is -called a @dfn{fontset}. A fontset is defined by a list of font specifications, -each assigned to handle a range of character codes, and may fall back -on another fontset for characters that are not covered by the fonts -it specifies. - -@cindex fonts for various scripts -@cindex Intlfonts package, installation - Each fontset has a name, like a font. However, while fonts are -stored in the system and the available font names are defined by the -system, fontsets are defined within Emacs itself. Once you have -defined a fontset, you can use it within Emacs by specifying its name, -anywhere that you could use a single font. Of course, Emacs fontsets -can use only the fonts that the system supports. If some characters -appear on the screen as empty boxes or hex codes, this means that the -fontset in use for them has no font for those characters. In this -case, or if the characters are shown, but not as well as you would -like, you may need to install extra fonts. Your operating system may -have optional fonts that you can install; or you can install the GNU -Intlfonts package, which includes fonts for most supported -scripts.@footnote{If you run Emacs on X, you may need to inform the X -server about the location of the newly installed fonts with commands -such as: -@c FIXME? I feel like this may be out of date. -@c E.g., the intlfonts tarfile is ~ 10 years old. - -@example - xset fp+ /usr/local/share/emacs/fonts - xset fp rehash -@end example -} - - Emacs creates three fontsets automatically: the @dfn{standard -fontset}, the @dfn{startup fontset} and the @dfn{default fontset}. -@c FIXME? The doc of *standard*-fontset-spec says: -@c "You have the biggest chance to display international characters -@c with correct glyphs by using the *standard* fontset." (my emphasis) -@c See http://lists.gnu.org/archive/html/emacs-devel/2012-04/msg00430.html -The default fontset is most likely to have fonts for a wide variety of -non-@acronym{ASCII} characters, and is the default fallback for the -other two fontsets, and if you set a default font rather than fontset. -However, it does not specify font family names, so results can be -somewhat random if you use it directly. You can specify use of a -particular fontset by starting Emacs with the @samp{-fn} option. -For example, - -@example -emacs -fn fontset-standard -@end example - -@noindent -You can also specify a fontset with the @samp{Font} resource (@pxref{X -Resources}). - - If no fontset is specified for use, then Emacs uses an -@acronym{ASCII} font, with @samp{fontset-default} as a fallback for -characters the font does not cover. The standard fontset is only used if -explicitly requested, despite its name. - - A fontset does not necessarily specify a font for every character -code. If a fontset specifies no font for a certain character, or if -it specifies a font that does not exist on your system, then it cannot -display that character properly. It will display that character as a -hex code or thin space or an empty box instead. (@xref{Text Display, , -glyphless characters}, for details.) - -@node Defining Fontsets -@section Defining fontsets - -@vindex standard-fontset-spec -@vindex w32-standard-fontset-spec -@vindex ns-standard-fontset-spec -@cindex standard fontset - When running on X, Emacs creates a standard fontset automatically according to the value -of @code{standard-fontset-spec}. This fontset's name is - -@example --*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard -@end example - -@noindent -or just @samp{fontset-standard} for short. - - On GNUstep and Mac OS X, the standard fontset is created using the value of -@code{ns-standard-fontset-spec}, and on MS Windows it is -created using the value of @code{w32-standard-fontset-spec}. - -@c FIXME? How does one access these, or do anything with them? -@c Does it matter? - Bold, italic, and bold-italic variants of the standard fontset are -created automatically. Their names have @samp{bold} instead of -@samp{medium}, or @samp{i} instead of @samp{r}, or both. - -@cindex startup fontset - Emacs generates a fontset automatically, based on any default -@acronym{ASCII} font that you specify with the @samp{Font} resource or -the @samp{-fn} argument, or the default font that Emacs found when it -started. This is the @dfn{startup fontset} and its name is -@code{fontset-startup}. It does this by replacing the -@var{charset_registry} field with @samp{fontset}, and replacing -@var{charset_encoding} field with @samp{startup}, then using the -resulting string to specify a fontset. - - For instance, if you start Emacs with a font of this form, - -@c FIXME? I think this is a little misleading, because you cannot (?) -@c actually specify a font with wildcards, it has to be a complete spec. -@c Also, an X font specification of this form hasn't (?) been -@c mentioned before now, and is somewhat obsolete these days. -@c People are more likely to use a form like -@c emacs -fn "DejaVu Sans Mono-12" -@c How does any of this apply in that case? -@example -emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1" -@end example - -@noindent -Emacs generates the following fontset and uses it for the initial X -window frame: - -@example --*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup -@end example - - The startup fontset will use the font that you specify, or a variant -with a different registry and encoding, for all the characters that -are supported by that font, and fallback on @samp{fontset-default} for -other characters. - - With the X resource @samp{Emacs.Font}, you can specify a fontset name -just like an actual font name. But be careful not to specify a fontset -name in a wildcard resource like @samp{Emacs*Font}---that wildcard -specification matches various other resources, such as for menus, and -@c FIXME is this still true? -menus cannot handle fontsets. @xref{X Resources}. - - You can specify additional fontsets using X resources named -@samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0. -The resource value should have this form: - -@smallexample -@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}} -@end smallexample - -@noindent -@var{fontpattern} should have the form of a standard X font name (see -the previous fontset-startup example), except -for the last two fields. They should have the form -@samp{fontset-@var{alias}}. - - The fontset has two names, one long and one short. The long name is -@var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You -can refer to the fontset by either name. - - The construct @samp{@var{charset}:@var{font}} specifies which font to -use (in this fontset) for one particular character set. Here, -@var{charset} is the name of a character set, and @var{font} is the -font to use for that character set. You can use this construct any -number of times in defining one fontset. - - For the other character sets, Emacs chooses a font based on -@var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values -that describe the character set. For the @acronym{ASCII} character font, -@samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}. - - In addition, when several consecutive fields are wildcards, Emacs -collapses them into a single wildcard. This is to prevent use of -auto-scaled fonts. Fonts made by scaling larger fonts are not usable -for editing, and scaling a smaller font is not also useful, because it is -better to use the smaller font in its own size, which is what Emacs -does. - - Thus if @var{fontpattern} is this, - -@example --*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 -@end example - -@noindent -the font specification for @acronym{ASCII} characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-ISO8859-1 -@end example - -@noindent -and the font specification for Chinese GB2312 characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-gb2312*-* -@end example - - You may not have any Chinese font matching the above font -specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In -such a case, @samp{Fontset-@var{n}} can be specified as: - -@smallexample -Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ - chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* -@end smallexample - -@noindent -Then, the font specifications for all but Chinese GB2312 characters have -@samp{fixed} in the @var{family} field, and the font specification for -Chinese GB2312 characters has a wild card @samp{*} in the @var{family} -field. - -@findex create-fontset-from-fontset-spec - The function that processes the fontset resource value to create the -fontset is called @code{create-fontset-from-fontset-spec}. You can also -call this function explicitly to create a fontset. - - @xref{Fonts}, for more information about font naming. - -@node Modifying Fontsets -@section Modifying Fontsets -@cindex fontsets, modifying -@findex set-fontset-font - - Fontsets do not always have to be created from scratch. If only -minor changes are required it may be easier to modify an existing -fontset. Modifying @samp{fontset-default} will also affect other -fontsets that use it as a fallback, so can be an effective way of -fixing problems with the fonts that Emacs chooses for a particular -script. - -Fontsets can be modified using the function @code{set-fontset-font}, -specifying a character, a charset, a script, or a range of characters -to modify the font for, and a font specification for the font to be -used. Some examples are: - -@example -;; Use Liberation Mono for latin-3 charset. -(set-fontset-font "fontset-default" 'iso-8859-3 - "Liberation Mono") - -;; Prefer a big5 font for han characters -(set-fontset-font "fontset-default" - 'han (font-spec :registry "big5") - nil 'prepend) - -;; Use DejaVu Sans Mono as a fallback in fontset-startup -;; before resorting to fontset-default. -(set-fontset-font "fontset-startup" nil "DejaVu Sans Mono" - nil 'append) - -;; Use MyPrivateFont for the Unicode private use area. -(set-fontset-font "fontset-default" '(#xe000 . #xf8ff) - "MyPrivateFont") - -@end example - - -@node Undisplayable Characters -@section Undisplayable Characters - - There may be some non-@acronym{ASCII} characters that your -terminal cannot display. Most text terminals support just a single -character set (use the variable @code{default-terminal-coding-system} -to tell Emacs which one, @ref{Terminal Coding}); characters that -can't be encoded in that coding system are displayed as @samp{?} by -default. - - Graphical displays can display a broader range of characters, but -you may not have fonts installed for all of them; characters that have -no font appear as a hollow box. - - If you use Latin-1 characters but your terminal can't display -Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences -instead, e.g., @samp{"o} for o-umlaut. Load the library -@file{iso-ascii} to do this. - -@vindex latin1-display - If your terminal can display Latin-1, you can display characters -from other European character sets using a mixture of equivalent -Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable -@code{latin1-display} to enable this. The mnemonic @acronym{ASCII} -sequences mostly correspond to those of the prefix input methods. - -@node Unibyte Mode -@section Unibyte Editing Mode - -@cindex European character sets -@cindex accented characters -@cindex ISO Latin character sets -@cindex Unibyte operation - The ISO 8859 Latin-@var{n} character sets define character codes in -the range 0240 to 0377 octal (160 to 255 decimal) to handle the -accented letters and punctuation needed by various European languages -(and some non-European ones). Note that Emacs considers bytes with -codes in this range as raw bytes, not as characters, even in a unibyte -buffer, i.e., if you disable multibyte characters. However, Emacs can -still handle these character codes as if they belonged to @emph{one} -of the single-byte character sets at a time. To specify @emph{which} -of these codes to use, invoke @kbd{M-x set-language-environment} and -specify a suitable language environment such as @samp{Latin-@var{n}}. -@xref{Disabling Multibyte, , Disabling Multibyte Characters, elisp, -GNU Emacs Lisp Reference Manual}. - -@vindex unibyte-display-via-language-environment - Emacs can also display bytes in the range 160 to 255 as readable -characters, provided the terminal or font in use supports them. This -works automatically. On a graphical display, Emacs can also display -single-byte characters through fontsets, in effect by displaying the -equivalent multibyte characters according to the current language -environment. To request this, set the variable -@code{unibyte-display-via-language-environment} to a non-@code{nil} -value. Note that setting this only affects how these bytes are -displayed, but does not change the fundamental fact that Emacs treats -them as raw bytes, not as characters. - -@cindex @code{iso-ascii} library - If your terminal does not support display of the Latin-1 character -set, Emacs can display these characters as @acronym{ASCII} sequences which at -least give you a clear idea of what the characters are. To do this, -load the library @code{iso-ascii}. Similar libraries for other -Latin-@var{n} character sets could be implemented, but have not been -so far. - -@findex standard-display-8bit -@cindex 8-bit display - Normally non-ISO-8859 characters (decimal codes between 128 and 159 -inclusive) are displayed as octal escapes. You can change this for -non-standard ``extended'' versions of ISO-8859 character sets by using the -function @code{standard-display-8bit} in the @code{disp-table} library. - - There are two ways to input single-byte non-@acronym{ASCII} -characters: - -@itemize @bullet -@cindex 8-bit input -@item -You can use an input method for the selected language environment. -@xref{Input Methods}. When you use an input method in a unibyte buffer, -the non-@acronym{ASCII} character you specify with it is converted to unibyte. - -@item -If your keyboard can generate character codes 128 (decimal) and up, -representing non-@acronym{ASCII} characters, you can type those character codes -directly. - -On a graphical display, you should not need to do anything special to -use these keys; they should simply work. On a text terminal, you -should use the command @code{M-x set-keyboard-coding-system} or customize the -variable @code{keyboard-coding-system} to specify which coding system -your keyboard uses (@pxref{Terminal Coding}). Enabling this feature -will probably require you to use @key{ESC} to type Meta characters; -however, on a console terminal or in @code{xterm}, you can arrange for -Meta to be converted to @key{ESC} and still be able type 8-bit -characters present directly on the keyboard or using @key{Compose} or -@key{AltGr} keys. @xref{User Input}. - -@kindex C-x 8 -@cindex @code{iso-transl} library -@cindex compose character -@cindex dead character -@item -For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose -character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing -characters. @kbd{C-x 8} is good for insertion (in the minibuffer as -well as other buffers), for searching, and in any other context where -a key sequence is allowed. - -@kbd{C-x 8} works by loading the @code{iso-transl} library. Once that -library is loaded, the @key{Alt} modifier key, if the keyboard has -one, serves the same purpose as @kbd{C-x 8}: use @key{Alt} together -with an accent character to modify the following letter. In addition, -if the keyboard has keys for the Latin-1 ``dead accent characters'', -they too are defined to compose with the following character, once -@code{iso-transl} is loaded. - -Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations. -@end itemize - -@node Charsets -@section Charsets -@cindex charsets - - In Emacs, @dfn{charset} is short for ``character set''. Emacs -supports most popular charsets (such as @code{ascii}, -@code{iso-8859-1}, @code{cp1250}, @code{big5}, and @code{unicode}), in -addition to some charsets of its own (such as @code{emacs}, -@code{unicode-bmp}, and @code{eight-bit}). All supported characters -belong to one or more charsets. - - Emacs normally ``does the right thing'' with respect to charsets, so -that you don't have to worry about them. However, it is sometimes -helpful to know some of the underlying details about charsets. - - One example is font selection (@pxref{Fonts}). Each language -environment (@pxref{Language Environments}) defines a ``priority -list'' for the various charsets. When searching for a font, Emacs -initially attempts to find one that can display the highest-priority -charsets. For instance, in the Japanese language environment, the -charset @code{japanese-jisx0208} has the highest priority, so Emacs -tries to use a font whose @code{registry} property is -@samp{JISX0208.1983-0}. - -@findex list-charset-chars -@cindex characters in a certain charset -@findex describe-character-set - There are two commands that can be used to obtain information about -charsets. The command @kbd{M-x list-charset-chars} prompts for a -charset name, and displays all the characters in that character set. -The command @kbd{M-x describe-character-set} prompts for a charset -name, and displays information about that charset, including its -internal representation within Emacs. - -@findex list-character-sets - @kbd{M-x list-character-sets} displays a list of all supported -charsets. The list gives the names of charsets and additional -information to identity each charset; see the -@url{http://www.itscj.ipsj.or.jp/ISO-IR/, International Register of -Coded Character Sets} for more details. In this list, -charsets are divided into two categories: @dfn{normal charsets} are -listed first, followed by @dfn{supplementary charsets}. A -supplementary charset is one that is used to define another charset -(as a parent or a subset), or to provide backward-compatibility for -older Emacs versions. - - To find out which charset a character in the buffer belongs to, put -point before it and type @kbd{C-u C-x =} (@pxref{International -Chars}). - -@node Bidirectional Editing -@section Bidirectional Editing -@cindex bidirectional editing -@cindex right-to-left text - - Emacs supports editing text written in scripts, such as Arabic and -Hebrew, whose natural ordering of horizontal text for display is from -right to left. However, digits and Latin text embedded in these -scripts are still displayed left to right. It is also not uncommon to -have small portions of text in Arabic or Hebrew embedded in an otherwise -Latin document; e.g., as comments and strings in a program source -file. For these reasons, text that uses these scripts is actually -@dfn{bidirectional}: a mixture of runs of left-to-right and -right-to-left characters. - - This section describes the facilities and options provided by Emacs -for editing bidirectional text. - -@cindex logical order -@cindex visual order - Emacs stores right-to-left and bidirectional text in the so-called -@dfn{logical} (or @dfn{reading}) order: the buffer or string position -of the first character you read precedes that of the next character. -Reordering of bidirectional text into the @dfn{visual} order happens -at display time. As result, character positions no longer increase -monotonically with their positions on display. Emacs implements the -Unicode Bidirectional Algorithm described in the Unicode Standard -Annex #9, for reordering of bidirectional text for display. - -@vindex bidi-display-reordering - The buffer-local variable @code{bidi-display-reordering} controls -whether text in the buffer is reordered for display. If its value is -non-@code{nil}, Emacs reorders characters that have right-to-left -directionality when they are displayed. The default value is -@code{t}. - -@cindex base direction of paragraphs -@cindex paragraph, base direction - Each paragraph of bidirectional text can have its own @dfn{base -direction}, either right-to-left or left-to-right. (Paragraph -@c paragraph-separate etc have no influence on this? -boundaries are empty lines, i.e., lines consisting entirely of -whitespace characters.) Text in left-to-right paragraphs begins on -the screen at the left margin of the window and is truncated or -continued when it reaches the right margin. By contrast, text in -right-to-left paragraphs is displayed starting at the right margin and -is continued or truncated at the left margin. - -@vindex bidi-paragraph-direction - Emacs determines the base direction of each paragraph dynamically, -based on the text at the beginning of the paragraph. However, -sometimes a buffer may need to force a certain base direction for its -paragraphs. The variable @code{bidi-paragraph-direction}, if -non-@code{nil}, disables the dynamic determination of the base -direction, and instead forces all paragraphs in the buffer to have the -direction specified by its buffer-local value. The value can be either -@code{right-to-left} or @code{left-to-right}. Any other value is -interpreted as @code{nil}. - -@cindex LRM -@cindex RLM - Alternatively, you can control the base direction of a paragraph by -inserting special formatting characters in front of the paragraph. -The special character @code{RIGHT-TO-LEFT MARK}, or @sc{rlm}, forces -the right-to-left direction on the following paragraph, while -@code{LEFT-TO-RIGHT MARK}, or @sc{lrm} forces the left-to-right -direction. (You can use @kbd{C-x 8 @key{RET}} to insert these characters.) -In a GUI session, the @sc{lrm} and @sc{rlm} characters display as very -thin blank characters; on text terminals they display as blanks. - - Because characters are reordered for display, Emacs commands that -operate in the logical order or on stretches of buffer positions may -produce unusual effects. For example, @kbd{C-f} and @kbd{C-b} -commands move point in the logical order, so the cursor will sometimes -jump when point traverses reordered bidirectional text. Similarly, a -highlighted region covering a contiguous range of character positions -may look discontinuous if the region spans reordered text. This is -normal and similar to the behavior of other programs that support -bidirectional text. If you set @code{visual-order-cursor-movement} to -a non-@code{nil} value, cursor motion by the arrow keys follows the -visual order on screen (@pxref{Moving Point, visual-order movement}). diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi deleted file mode 100644 index 136eff7e2fe..00000000000 --- a/doc/emacs/package.texi +++ /dev/null @@ -1,299 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Packages -@chapter Emacs Lisp Packages -@cindex Package -@cindex Emacs Lisp package archive -@cindex Package archive -@cindex Emacs Lisp package - -Emacs includes a facility that lets you easily download and install -@dfn{packages} that implement additional features. Each package is a -separate Emacs Lisp program, sometimes including other components such -as an Info manual. - - @kbd{M-x list-packages} brings up a buffer named @file{*Packages*} -with a list of all packages. You can install or uninstall packages -via this buffer. @xref{Package Menu}. - -@findex describe-package - The command @kbd{C-h P} (@code{describe-package}) prompts for the -name of a package, and displays a help buffer describing the -attributes of the package and the features that it implements. - - By default, Emacs downloads packages from a @dfn{package archive} -maintained by the Emacs developers and hosted by the GNU project. -Optionally, you can also download packages from archives maintained by -third parties. @xref{Package Installation}. - - For information about turning an Emacs Lisp program into an -installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference -Manual}. For information about finding third-party packages and other -Emacs Lisp extensions, @xref{Packages that do not come with -Emacs,,,efaq, GNU Emacs FAQ}. - -@menu -* Package Menu:: Buffer for viewing and managing packages. -* Package Installation:: Options for package installation. -* Package Files:: Where packages are installed. -@end menu - -@node Package Menu -@section The Package Menu Buffer -@cindex package menu -@cindex built-in package -@findex list-packages - -The command @kbd{M-x list-packages} brings up the @dfn{package menu}. -This is a buffer listing all the packages that Emacs knows about, one -on each line, with the following information: - -@itemize @bullet -@item -The package name (e.g., @samp{auctex}). - -@item -The package's version number (e.g., @samp{11.86}). - -@item -The package's status---normally one of @samp{available} (can be -downloaded from the package archive), @samp{installed}, -@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}), -or @samp{built-in} (included in Emacs by default). - -The status can also be @samp{new}. This is equivalent to -@samp{available}, except that it means the package became newly -available on the package archive after your last invocation of -@kbd{M-x list-packages}. In other instances, a package may have the -status @samp{held}, @samp{disabled}, or @samp{obsolete}. -@xref{Package Installation}. - -@item -A short description of the package. -@end itemize - -@noindent -The @code{list-packages} command accesses the network, to retrieve the -list of available packages from the package archive server. If the -network is unavailable, it falls back on the most recently retrieved -list. - -The following commands are available in the package menu: - -@table @kbd -@item h -Print a short message summarizing how to use the package menu -(@code{package-menu-quick-help}). - -@item ? -@itemx @key{RET} -Display a help buffer for the package on the current line -(@code{package-menu-describe-package}), similar to the help window -displayed by the @kbd{C-h P} command (@pxref{Packages}). - -@item i -Mark the package on the current line for installation -(@code{package-menu-mark-install}). If the package status is -@samp{available}, this adds an @samp{I} character to the start of the -line; typing @kbd{x} (see below) will download and install the -package. - -@item d -Mark the package on the current line for deletion -(@code{package-menu-mark-delete}). If the package status is -@samp{installed}, this adds a @samp{D} character to the start of the -line; typing @kbd{x} (see below) will delete the package. -@xref{Package Files}, for information about what package deletion -entails. - -@item u -Remove any installation or deletion mark previously added to the -current line by an @kbd{i} or @kbd{d} command. - -@item U -Mark all package with a newer available version for ``upgrading'' -(@code{package-menu-mark-upgrades}). This places an installation mark -on the new available versions, and a deletion mark on the old -installed versions. - -@item x -Download and install all packages marked with @kbd{i}, and their -dependencies; also, delete all packages marked with @kbd{d} -(@code{package-menu-execute}). This also removes the marks. - -@item r -Refresh the package list (@code{package-menu-refresh}). This fetches -the list of available packages from the package archive again, and -recomputes the package list. - -@item f -Filter the package list (@code{package-menu-filter}). This prompts -for a keyword (e.g., @samp{games}), then shows only the packages -that relate to that keyword. To restore the full package list, -type @kbd{q}. -@end table - -@noindent -For example, you can install a package by typing @kbd{i} on the line -listing that package, followed by @kbd{x}. - -@node Package Installation -@section Package Installation - -@findex package-install - Packages are most conveniently installed using the package menu -(@pxref{Package Menu}), but you can also use the command @kbd{M-x -package-install}. This prompts for the name of a package with the -@samp{available} status, then downloads and installs it. - -@cindex package requirements - A package may @dfn{require} certain other packages to be installed, -because it relies on functionality provided by them. When Emacs -installs such a package, it also automatically downloads and installs -any required package that is not already installed. (If a required -package is somehow unavailable, Emacs signals an error and stops -installation.) A package's requirements list is shown in its help -buffer. - -@vindex package-archives - By default, packages are downloaded from a single package archive -maintained by the Emacs developers. This is controlled by the -variable @code{package-archives}, whose value is a list of package -archives known to Emacs. Each list element must have the form -@code{(@var{id} . @var{location})}, where @var{id} is the name of a -package archive and @var{location} is the @acronym{HTTP} address or -directory name of the package archive. You can alter this list if you -wish to use third party package archives---but do so at your own risk, -and use only third parties that you think you can trust! - -@anchor{Package Signing} -@cindex package security -@cindex package signing - The maintainers of package archives can increase the trust that you -can have in their packages by @dfn{signing} them. They generate a -private/public pair of cryptographic keys, and use the private key to -create a @dfn{signature file} for each package. With the public key, you -can use the signature files to verify who created the package, and -that it has not been modified. A valid signature is not a cast-iron -guarantee that a package is not malicious, so you should still -exercise caution. Package archives should provide instructions -on how you can obtain their public key. One way is to download the -key from a server such as @url{http://pgp.mit.edu/}. -Use @kbd{M-x package-import-keyring} to import the key into Emacs. -Emacs stores package keys in the @file{gnupg} subdirectory -of @code{package-user-dir}. -The public key for the GNU package archive is distributed with Emacs, -in the @file{etc/package-keyring.gpg}. Emacs uses it automatically. - -@vindex package-check-signature -@vindex package-unsigned-archives - If the user option @code{package-check-signature} is non-@code{nil}, -Emacs attempts to verify signatures when you install packages. If the -option has the value @code{allow-unsigned}, you can still install a -package that is not signed. If you use some archives that do not sign -their packages, you can add them to the list @code{package-unsigned-archives}. - - For more information on cryptographic keys and signing, -@pxref{Top,, Top, gnupg, The GNU Privacy Guard Manual}. -Emacs comes with an interface to GNU Privacy Guard, -@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}. - -@vindex package-pinned-packages - If you have more than one package archive enabled, and some of them -offer different versions of the same package, you may find the option -@code{package-pinned-packages} useful. You can add package/archive -pairs to this list, to ensure that the specified package is only ever -downloaded from the specified archive. - - Once a package is downloaded and installed, it is @dfn{loaded} into -the current Emacs session. Loading a package is not quite the same as -loading a Lisp library (@pxref{Lisp Libraries}); its effect varies -from package to package. Most packages just make some new commands -available, while others have more wide-ranging effects on the Emacs -session. For such information, consult the package's help buffer. - - By default, Emacs also automatically loads all installed packages in -subsequent Emacs sessions. This happens at startup, after processing -the init file (@pxref{Init File}). As an exception, Emacs does not -load packages at startup if invoked with the @samp{-q} or -@samp{--no-init-file} options (@pxref{Initial Options}). - -@vindex package-enable-at-startup - To disable automatic package loading, change the variable -@code{package-enable-at-startup} to @code{nil}. - -@findex package-initialize - The reason automatic package loading occurs after loading the init -file is that user options only receive their customized values after -loading the init file, including user options which affect the -packaging system. In some circumstances, you may want to load -packages explicitly in your init file (usually because some other code -in your init file depends on a package). In that case, your init file -should call the function @code{package-initialize}. It is up to you -to ensure that relevant user options, such as @code{package-load-list} -(see below), are set up prior to the @code{package-initialize} call. -You should also set @code{package-enable-at-startup} to @code{nil}, to -avoid loading the packages again after processing the init file. -Alternatively, you may choose to completely inhibit package loading at -startup, and invoke the command @kbd{M-x package-initialize} to load -your packages manually. - -@vindex package-load-list - For finer control over package loading, you can use the variable -@code{package-load-list}. Its value should be a list. A list element -of the form @code{(@var{name} @var{version})} tells Emacs to load -version @var{version} of the package named @var{name}. Here, -@var{version} should be a version string (corresponding to a specific -version of the package), or @code{t} (which means to load any -installed version), or @code{nil} (which means no version; this -``disables'' the package, preventing it from being loaded). A list -element can also be the symbol @code{all}, which means to load the -latest installed version of any package not named by the other list -elements. The default value is just @code{'(all)}. - - For example, if you set @code{package-load-list} to @code{'((muse -"3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse} -package, plus any installed version of packages other than -@samp{muse}. Any other version of @samp{muse} that happens to be -installed will be ignored. The @samp{muse} package will be listed in -the package menu with the @samp{held} status. - -@node Package Files -@section Package Files and Directory Layout -@cindex package directory - -@cindex package file -@findex package-install-file - Each package is downloaded from the package archive in the form of a -single @dfn{package file}---either an Emacs Lisp source file, or a tar -file containing multiple Emacs Lisp source and other files. Package -files are automatically retrieved, processed, and disposed of by the -Emacs commands that install packages. Normally, you will not need to -deal directly with them, unless you are making a package -(@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}). Should -you ever need to install a package directly from a package file, use -the command @kbd{M-x package-install-file}. - -@vindex package-user-dir - Once installed, the contents of a package are placed in a -subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of -that directory by changing the variable @code{package-user-dir}). The -package subdirectory is named @file{@var{name}-@var{version}}, where -@var{name} is the package name and @var{version} is its version -string. - -@cindex system-wide packages -@vindex package-directory-list - In addition to @code{package-user-dir}, Emacs looks for installed -packages in the directories listed in @code{package-directory-list}. -These directories are meant for system administrators to make Emacs -packages available system-wide; Emacs itself never installs packages -there. The package subdirectories for @code{package-directory-list} -are laid out in the same way as in @code{package-user-dir}. - - Deleting a package (@pxref{Package Menu}) involves deleting the -corresponding package subdirectory. This only works for packages -installed in @code{package-user-dir}; if told to act on a package in a -system-wide package directory, the deletion command signals an error. diff --git a/doc/emacs/picture-xtra.texi b/doc/emacs/picture-xtra.texi deleted file mode 100644 index 6f29e92732c..00000000000 --- a/doc/emacs/picture-xtra.texi +++ /dev/null @@ -1,289 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Picture Mode -@section Editing Pictures -@cindex pictures -@cindex making pictures out of text characters -@findex picture-mode - - To edit a picture made out of text characters (for example, a picture -of the division of a register into fields, as a comment in a program), -use the command @kbd{M-x picture-mode} to enter Picture mode. - - In Picture mode, editing is based on the @dfn{quarter-plane} model of -text, according to which the text characters lie studded on an area that -stretches infinitely far to the right and downward. The concept of the end -of a line does not exist in this model; the most you can say is where the -last nonblank character on the line is found. - - Of course, Emacs really always considers text as a sequence of -characters, and lines really do have ends. But Picture mode replaces -the most frequently-used commands with variants that simulate the -quarter-plane model of text. They do this by inserting spaces or by -converting tabs to spaces. - - Most of the basic editing commands of Emacs are redefined by Picture mode -to do essentially the same thing but in a quarter-plane way. In addition, -Picture mode defines various keys starting with the @kbd{C-c} prefix to -run special picture editing commands. - - One of these keys, @kbd{C-c C-c}, is particularly important. Often -a picture is part of a larger file that is usually edited in some -other major mode. Picture mode records the name of the previous major -mode so you can use the @kbd{C-c C-c} command -(@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c -C-c} also deletes spaces from the ends of lines, unless given a -numeric argument. - - The special commands of Picture mode all work in other modes (provided -the @file{picture} library is loaded), but are not bound to keys except -in Picture mode. The descriptions below talk of moving ``one column'' -and so on, but all the picture mode commands handle numeric arguments as -their normal equivalents do. - -@vindex picture-mode-hook - Turning on Picture mode runs the hook @code{picture-mode-hook}. -Additional extensions to Picture mode can be found in -@file{artist.el}. - -@menu -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. -@end menu - -@node Basic Picture -@subsection Basic Editing in Picture Mode - -@findex picture-forward-column -@findex picture-backward-column -@findex picture-move-down -@findex picture-move-up -@cindex editing in Picture mode - - Most keys do the same thing in Picture mode that they usually do, but -do it in a quarter-plane style. For example, @kbd{C-f} is rebound to -run @code{picture-forward-column}, a command which moves point one -column to the right, inserting a space if necessary so that the actual -end of the line makes no difference. @kbd{C-b} is rebound to run -@code{picture-backward-column}, which always moves point left one -column, converting a tab to multiple spaces if necessary. @kbd{C-n} and -@kbd{C-p} are rebound to run @code{picture-move-down} and -@code{picture-move-up}, which can either insert spaces or convert tabs -as necessary to make sure that point stays in exactly the same column. -@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last -nonblank character on the line. @kbd{C-a} runs -@code{picture-beginning-of-line}. (The choice of screen model does not -affect beginnings of lines; the only extra thing this command does is -update the current picture column to 0.) - -@findex picture-newline - Insertion of text is adapted to the quarter-plane screen model -through the use of Overwrite mode -@iftex -(@pxref{Minor Modes,,, emacs, the Emacs Manual}.) -@end iftex -@ifnottex -(@pxref{Minor Modes}.) -@end ifnottex -Self-inserting characters replace existing text, column by column, -rather than pushing existing text to the right. @key{RET} runs -@code{picture-newline}, which just moves to the beginning of the -following line so that new text will replace that line. - -@findex picture-backward-clear-column -@findex picture-clear-column -@findex picture-clear-line - In Picture mode, the commands that normally delete or kill text, -instead erase text (replacing it with spaces). @key{DEL} -(@code{picture-backward-clear-column}) replaces the preceding -character with a space rather than removing it; this moves point -backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the next -character or characters with spaces, but does not move point. (If you -want to clear characters to spaces and move forward over them, use -@key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the -contents of lines, but does not delete the newlines from the buffer. - -@findex picture-open-line - To do actual insertion, you must use special commands. @kbd{C-o} -(@code{picture-open-line}) creates a blank line after the current -line; it never splits a line. @kbd{C-M-o} (@code{split-line}) makes -sense in Picture mode, so it is not changed. @kbd{C-j} -(@code{picture-duplicate-line}) inserts another line with the same -contents below the current line. - -@kindex C-c C-d @r{(Picture mode)} - To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d} -(which is defined as @code{delete-char}, as @kbd{C-d} is in other -modes), or one of the picture rectangle commands (@pxref{Rectangles in -Picture}). - -@node Insert in Picture -@subsection Controlling Motion after Insert - -@findex picture-movement-up -@findex picture-movement-down -@findex picture-movement-left -@findex picture-movement-right -@findex picture-movement-nw -@findex picture-movement-ne -@findex picture-movement-sw -@findex picture-movement-se -@kindex C-c < @r{(Picture mode)} -@kindex C-c > @r{(Picture mode)} -@kindex C-c ^ @r{(Picture mode)} -@kindex C-c . @r{(Picture mode)} -@kindex C-c ` @r{(Picture mode)} -@kindex C-c ' @r{(Picture mode)} -@kindex C-c / @r{(Picture mode)} -@kindex C-c \ @r{(Picture mode)} - Since ``self-inserting'' characters in Picture mode overwrite and move -point, there is no essential restriction on how point should be moved. -Normally point moves right, but you can specify any of the eight -orthogonal or diagonal directions for motion after a ``self-inserting'' -character. This is useful for drawing lines in the buffer. - -@table @kbd -@item C-c < -@itemx C-c @key{LEFT} -Move left after insertion (@code{picture-movement-left}). -@item C-c > -@itemx C-c @key{RIGHT} -Move right after insertion (@code{picture-movement-right}). -@item C-c ^ -@itemx C-c @key{UP} -Move up after insertion (@code{picture-movement-up}). -@item C-c . -@itemx C-c @key{DOWN} -Move down after insertion (@code{picture-movement-down}). -@item C-c ` -@itemx C-c @key{Home} -Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). -@item C-c ' -@itemx C-c @key{prior} -Move up and right (``northeast'') after insertion -(@code{picture-movement-ne}). -@item C-c / -@itemx C-c @key{End} -Move down and left (``southwest'') after insertion -@*(@code{picture-movement-sw}). -@item C-c \ -@itemx C-c @key{next} -Move down and right (``southeast'') after insertion -@*(@code{picture-movement-se}). -@end table - -@kindex C-c C-f @r{(Picture mode)} -@kindex C-c C-b @r{(Picture mode)} -@findex picture-motion -@findex picture-motion-reverse - Two motion commands move based on the current Picture insertion -direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the -same direction as motion after ``insertion'' currently does, while @kbd{C-c -C-b} (@code{picture-motion-reverse}) moves in the opposite direction. - -@node Tabs in Picture -@subsection Picture Mode Tabs - -@kindex M-TAB @r{(Picture mode)} -@findex picture-tab-search -@vindex picture-tab-chars - Two kinds of tab-like action are provided in Picture mode. Use -@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing. -With no argument, it moves to a point underneath the next -``interesting'' character that follows whitespace in the previous -nonblank line. ``Next'' here means ``appearing at a horizontal position -greater than the one point starts out at''. With an argument, as in -@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting -character in the current line. @kbd{M-@key{TAB}} does not change the -text; it only moves point. ``Interesting'' characters are defined by -the variable @code{picture-tab-chars}, which should define a set of -characters. The syntax for this variable is like the syntax used inside -of @samp{[@dots{}]} in a regular expression---but without the @samp{[} -and the @samp{]}. Its default value is @code{"!-~"}. - -@findex picture-tab - @key{TAB} itself runs @code{picture-tab}, which operates based on the -current tab stop settings; it is the Picture mode equivalent of -@code{tab-to-tab-stop}. Normally it just moves point, but with a numeric -argument it clears the text that it moves over. - -@kindex C-c TAB @r{(Picture mode)} -@findex picture-set-tab-stops - The context-based and tab-stop-based forms of tabbing are brought -together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}). -This command sets the tab stops to the positions which @kbd{M-@key{TAB}} -would consider significant in the current line. The use of this command, -together with @key{TAB}, can get the effect of context-based tabbing. But -@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. - - It may be convenient to prevent use of actual tab characters in -pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing -up the picture. You can do this by setting the variable -@code{indent-tabs-mode} to @code{nil}. - -@node Rectangles in Picture -@subsection Picture Mode Rectangle Commands -@cindex rectangles and Picture mode -@cindex Picture mode and rectangles - - Picture mode defines commands for working on rectangular pieces of -the text in ways that fit with the quarter-plane model. The standard -rectangle commands may also be useful. -@iftex -@xref{Rectangles,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Rectangles}. -@end ifnottex - -@table @kbd -@item C-c C-k -Clear out the region-rectangle with spaces -(@code{picture-clear-rectangle}). With a prefix argument, delete the -text. -@item C-c C-w @var{r} -Similar, but save rectangle contents in register @var{r} first -(@code{picture-clear-rectangle-to-register}). -@item C-c C-y -Copy last killed rectangle into the buffer by overwriting, with upper -left corner at point (@code{picture-yank-rectangle}). With argument, -insert instead. -@item C-c C-x @var{r} -Similar, but use the rectangle in register @var{r} -(@code{picture-yank-rectangle-from-register}). -@end table - -@kindex C-c C-k @r{(Picture mode)} -@kindex C-c C-w @r{(Picture mode)} -@findex picture-clear-rectangle -@findex picture-clear-rectangle-to-register - The picture rectangle commands @kbd{C-c C-k} -(@code{picture-clear-rectangle}) and @kbd{C-c C-w} -(@code{picture-clear-rectangle-to-register}) differ from the standard -rectangle commands in that they normally clear the rectangle instead of -deleting it; this is analogous with the way @kbd{C-d} is changed in Picture -mode. - - However, deletion of rectangles can be useful in Picture mode, so -these commands delete the rectangle if given a numeric argument. -@kbd{C-c C-k} either with or without a numeric argument saves the -rectangle for @kbd{C-c C-y}. - -@kindex C-c C-y @r{(Picture mode)} -@kindex C-c C-x @r{(Picture mode)} -@findex picture-yank-rectangle -@findex picture-yank-rectangle-from-register - The Picture mode commands for yanking rectangles differ from the -standard ones in that they overwrite instead of inserting. This is -the same way that Picture mode insertion of other text differs from -other modes. @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts -(by overwriting) the rectangle that was most recently killed, while -@kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does -likewise for the rectangle found in a specified register. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi deleted file mode 100644 index 05008790b4f..00000000000 --- a/doc/emacs/programs.texi +++ /dev/null @@ -1,1839 +0,0 @@ -@c -*- coding: utf-8 -*- -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Programs -@chapter Editing Programs -@cindex Lisp editing -@cindex C editing -@cindex program editing - - This chapter describes Emacs features for facilitating editing -programs. Some of the things these features can do are: - -@itemize @bullet -@item -Find or move over top-level definitions (@pxref{Defuns}). -@item -Apply the usual indentation conventions of the language -(@pxref{Program Indent}). -@item -Balance parentheses (@pxref{Parentheses}). -@item -Insert, kill or align comments (@pxref{Comments}). -@item -Highlight program syntax (@pxref{Font Lock}). -@end itemize - -@menu -* Program Modes:: Major modes for editing programs. -* Defuns:: Commands to operate on major top-level parts - of a program. -* Program Indent:: Adjusting indentation to show the nesting. -* Parentheses:: Commands that operate on parentheses. -* Comments:: Inserting, killing, and aligning comments. -* Documentation:: Getting documentation of functions you plan to call. -* Hideshow:: Displaying blocks selectively. -* Symbol Completion:: Completion on symbol names of your program or language. -* MixedCase Words:: Dealing with identifiersLikeThis. -* Semantic:: Suite of editing tools based on source code parsing. -* Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, Java, - IDL, Pike and AWK modes. -* Asm Mode:: Asm mode and its special features. -@ifnottex -* Fortran:: Fortran mode and its special features. -@end ifnottex -@end menu - -@node Program Modes -@section Major Modes for Programming Languages -@cindex modes for programming languages - - Emacs has specialized major modes (@pxref{Major Modes}) for many -programming languages. A programming language mode typically -specifies the syntax of expressions, the customary rules for -indentation, how to do syntax highlighting for the language, and how -to find the beginning or end of a function definition. It often has -features for compiling and debugging programs as well. The major mode -for each language is named after the language; for instance, the major -mode for the C programming language is @code{c-mode}. - -@cindex Perl mode -@cindex Icon mode -@cindex Makefile mode -@cindex Tcl mode -@cindex CPerl mode -@cindex DSSSL mode -@cindex Octave mode -@cindex Metafont mode -@cindex Modula2 mode -@cindex Prolog mode -@cindex Python mode -@cindex Ruby mode -@cindex Simula mode -@cindex VHDL mode -@cindex M4 mode -@cindex Shell-script mode -@cindex OPascal mode -@cindex PostScript mode -@cindex Conf mode -@cindex DNS mode -@cindex Javascript mode - Emacs has programming language modes for Lisp, Scheme, the -Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, -Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont -(@TeX{}'s companion for font creation), Modula2, Object Pascal, Objective-C, -Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, -and VHDL@. An alternative mode for Perl is called CPerl mode. Modes are -also available for the scripting languages of the common GNU and Unix -shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for -makefiles, DNS master files, and various sorts of configuration files. - - Ideally, Emacs should have a major mode for each programming -language that you might want to edit. If it doesn't have a mode for -your favorite language, the mode might be implemented in a package not -distributed with Emacs (@pxref{Packages}); or you can contribute one. - -@kindex DEL @r{(programming modes)} -@findex c-electric-backspace -@findex backward-delete-char-untabify - In most programming languages, indentation should vary from line to -line to illustrate the structure of the program. Therefore, in most -programming language modes, typing @key{TAB} updates the indentation -of the current line (@pxref{Program Indent}). Furthermore, @key{DEL} -is usually bound to @code{backward-delete-char-untabify}, which -deletes backward treating each tab as if it were the equivalent number -of spaces, so that you can delete one column of indentation without -worrying whether the whitespace consists of spaces or tabs. - -@cindex mode hook -@vindex c-mode-hook -@vindex lisp-mode-hook -@vindex emacs-lisp-mode-hook -@vindex lisp-interaction-mode-hook -@vindex scheme-mode-hook - Entering a programming language mode runs the custom Lisp functions -specified in the hook variable @code{prog-mode-hook}, followed by -those specified in the mode's own mode hook (@pxref{Major Modes}). -For instance, entering C mode runs the hooks @code{prog-mode-hook} and -@code{c-mode-hook}. @xref{Hooks}, for information about hooks. - -@ifnottex - Separate manuals are available for the modes for Ada (@pxref{Top,, -Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba -IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE -(@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}). -@end ifnottex -@iftex - The Emacs distribution contains Info manuals for the major modes for -Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE@. For -Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized Emacs Features}. -@end iftex - -@node Defuns -@section Top-Level Definitions, or Defuns - - In Emacs, a major definition at the top level in the buffer, such as -a function, is called a @dfn{defun}. The name comes from Lisp, but in -Emacs we use it for all languages. - -@menu -* Left Margin Paren:: An open-paren or similar opening delimiter - starts a defun if it is at the left margin. -* Moving by Defuns:: Commands to move over or mark a major definition. -* Imenu:: Making buffer indexes as menus. -* Which Function:: Which Function mode shows which function you are in. -@end menu - -@node Left Margin Paren -@subsection Left Margin Convention - -@cindex open-parenthesis in leftmost column -@cindex ( in leftmost column - Many programming-language modes assume by default that any opening -delimiter found at the left margin is the start of a top-level -definition, or defun. Therefore, @strong{don't put an opening -delimiter at the left margin unless it should have that significance}. -For instance, never put an open-parenthesis at the left margin in a -Lisp file unless it is the start of a top-level list. - - The convention speeds up many Emacs operations, which would -otherwise have to scan back to the beginning of the buffer to analyze -the syntax of the code. - - If you don't follow this convention, not only will you have trouble -when you explicitly use the commands for motion by defuns; other -features that use them will also give you trouble. This includes the -indentation commands (@pxref{Program Indent}) and Font Lock mode -(@pxref{Font Lock}). - - The most likely problem case is when you want an opening delimiter -at the start of a line inside a string. To avoid trouble, put an -escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some -other Lisp dialects) before the opening delimiter. This will not -affect the contents of the string, but will prevent that opening -delimiter from starting a defun. Here's an example: - -@example - (insert "Foo: -\(bar) -") -@end example - - To help you catch violations of this convention, Font Lock mode -highlights confusing opening delimiters (those that ought to be -quoted) in bold red. - -@vindex open-paren-in-column-0-is-defun-start - If you need to override this convention, you can do so by setting -the variable @code{open-paren-in-column-0-is-defun-start}. -If this user option is set to @code{t} (the default), opening -parentheses or braces at column zero always start defuns. When it is -@code{nil}, defuns are found by searching for parens or braces at the -outermost level. - - Usually, you should leave this option at its default value of -@code{t}. If your buffer contains parentheses or braces in column -zero which don't start defuns, and it is somehow impractical to remove -these parentheses or braces, it might be helpful to set the option to -@code{nil}. Be aware that this might make scrolling and display in -large buffers quite sluggish. Furthermore, the parentheses and braces -must be correctly matched throughout the buffer for it to work -properly. - -@node Moving by Defuns -@subsection Moving by Defuns -@cindex defuns - - These commands move point or set up the region based on top-level -major definitions, also called @dfn{defuns}. - -@table @kbd -@item C-M-a -Move to beginning of current or preceding defun -(@code{beginning-of-defun}). -@item C-M-e -Move to end of current or following defun (@code{end-of-defun}). -@item C-M-h -Put region around whole current or following defun (@code{mark-defun}). -@end table - -@cindex move to beginning or end of function -@cindex function, move to beginning or end -@kindex C-M-a -@kindex C-M-e -@kindex C-M-h -@findex beginning-of-defun -@findex end-of-defun -@findex mark-defun - The commands to move to the beginning and end of the current defun -are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} -(@code{end-of-defun}). If you repeat one of these commands, or use a -positive numeric argument, each repetition moves to the next defun in -the direction of motion. - - @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward -@var{n} times to the next beginning of a defun. This is not exactly -the same place that @kbd{C-M-e} with argument @var{n} would move to; -the end of this defun is not usually exactly the same place as the -beginning of the following defun. (Whitespace, comments, and perhaps -declarations can separate them.) Likewise, @kbd{C-M-e} with a -negative argument moves back to an end of a defun, which is not quite -the same as @kbd{C-M-a} with a positive argument. - -@kindex C-M-h @r{(C mode)} -@findex c-mark-function - To operate on the current defun, use @kbd{C-M-h} -(@code{mark-defun}), which sets the mark at the end of the current -defun and puts point at its beginning. @xref{Marking Objects}. This -is the easiest way to get ready to kill the defun in order to move it -to a different place in the file. If you use the command while point -is between defuns, it uses the following defun. If you use the -command while the mark is already active, it sets the mark but does -not move point; furthermore, each successive use of @kbd{C-M-h} -extends the end of the region to include one more defun. - - In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, -which is almost the same as @code{mark-defun}; the difference is that -it backs up over the argument declarations, function name and returned -data type so that the entire C function is inside the region. This is -an example of how major modes adjust the standard key bindings so that -they do their standard jobs in a way better fitting a particular -language. Other major modes may replace any or all of these key -bindings for that purpose. - -@node Imenu -@subsection Imenu -@cindex index of buffer definitions -@cindex buffer definitions index - - The Imenu facility offers a way to find the major definitions in -a file by name. It is also useful in text formatter major modes, -where it treats each chapter, section, etc., as a definition. -(@xref{Tags}, for a more powerful feature that handles multiple files -together.) - -@findex imenu - If you type @kbd{M-x imenu}, it reads the name of a definition using -the minibuffer, then moves point to that definition. You can use -completion to specify the name; the command always displays the whole -list of valid names. - -@findex imenu-add-menubar-index - Alternatively, you can bind the command @code{imenu} to a mouse -click. Then it displays mouse menus for you to select a definition -name. You can also add the buffer's index to the menu bar by calling -@code{imenu-add-menubar-index}. If you want to have this menu bar -item available for all buffers in a certain major mode, you can do -this by adding @code{imenu-add-menubar-index} to its mode hook. But -if you have done that, you will have to wait a little while each time -you visit a file in that mode, while Emacs finds all the definitions -in that buffer. - -@vindex imenu-auto-rescan - When you change the contents of a buffer, if you add or delete -definitions, you can update the buffer's index based on the -new contents by invoking the @samp{*Rescan*} item in the menu. -Rescanning happens automatically if you set @code{imenu-auto-rescan} to -a non-@code{nil} value. There is no need to rescan because of small -changes in the text. - -@vindex imenu-sort-function - You can customize the way the menus are sorted by setting the -variable @code{imenu-sort-function}. By default, names are ordered as -they occur in the buffer; if you want alphabetic sorting, use the -symbol @code{imenu--sort-by-name} as the value. You can also -define your own comparison function by writing Lisp code. - - Imenu provides the information to guide Which Function mode -@ifnottex -(@pxref{Which Function}). -@end ifnottex -@iftex -(see below). -@end iftex -The Speedbar can also use it (@pxref{Speedbar}). - -@node Which Function -@subsection Which Function Mode -@cindex current function name in mode line - - Which Function mode is a global minor mode (@pxref{Minor Modes}) -which displays the current function name in the mode line, updating it -as you move around in a buffer. - -@findex which-function-mode -@vindex which-func-modes - To either enable or disable Which Function mode, use the command -@kbd{M-x which-function-mode}. Which Function mode is a global minor -mode. By default, it takes effect in all major modes major modes that -know how to support it (i.e., all the major modes that support -Imenu). You can restrict it to a specific list of major modes by -changing the value of the variable @code{which-func-modes} from -@code{t} (which means to support all available major modes) to a list -of major mode names. - -@node Program Indent -@section Indentation for Programs -@cindex indentation for programs - - The best way to keep a program properly indented is to use Emacs to -reindent it as you change it. Emacs has commands to indent either a -single line, a specified number of lines, or all of the lines inside a -single parenthetical grouping. - - @xref{Indentation}, for general information about indentation. This -section describes indentation features specific to programming -language modes. - -@menu -* Basic Indent:: Indenting a single line. -* Multi-line Indent:: Commands to reindent many lines at once. -* Lisp Indent:: Specifying how each Lisp function should be indented. -* C Indent:: Extra features for indenting C and related modes. -* Custom C Indent:: Controlling indentation style for C and related modes. -@end menu - -@cindex pretty-printer - Emacs also provides a Lisp pretty-printer in the @code{pp} package, -which reformats Lisp objects with nice-looking indentation. - -@node Basic Indent -@subsection Basic Program Indentation Commands - -@table @kbd -@item @key{TAB} -Adjust indentation of current line (@code{indent-for-tab-command}). -@item @key{RET} -Insert a newline, then adjust indentation of following line -(@code{newline}). -@end table - -@kindex TAB @r{(programming modes)} -@findex c-indent-command -@findex indent-line-function -@findex indent-for-tab-command - The basic indentation command is @key{TAB} -(@code{indent-for-tab-command}), which was documented in -@ref{Indentation}. In programming language modes, @key{TAB} indents -the current line, based on the indentation and syntactic content of -the preceding lines; if the region is active, @key{TAB} indents each -line within the region, not just the current line. - - The command @key{RET} (@code{newline}), which was documented in -@ref{Inserting Text}, does the same as @key{C-j} followed by -@key{TAB}: it inserts a new line, then adjusts the line's indentation. - - When indenting a line that starts within a parenthetical grouping, -Emacs usually places the start of the line under the preceding line -within the group, or under the text after the parenthesis. If you -manually give one of these lines a nonstandard indentation (e.g., for -aesthetic purposes), the lines below will follow it. - - The indentation commands for most programming language modes assume -that a open-parenthesis, open-brace or other opening delimiter at the -left margin is the start of a function. If the code you are editing -violates this assumption---even if the delimiters occur in strings or -comments---you must set @code{open-paren-in-column-0-is-defun-start} -to @code{nil} for indentation to work properly. @xref{Left Margin -Paren}. - -@node Multi-line Indent -@subsection Indenting Several Lines - - Sometimes, you may want to reindent several lines of code at a time. -One way to do this is to use the mark; when the mark is active and the -region is non-empty, @key{TAB} indents every line in the region. -Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents -every line in the region, whether or not the mark is active -(@pxref{Indentation Commands}). - - In addition, Emacs provides the following commands for indenting -large chunks of code: - -@table @kbd -@item C-M-q -Reindent all the lines within one parenthetical grouping. -@item C-u @key{TAB} -Shift an entire parenthetical grouping rigidly sideways so that its -first line is properly indented. -@item M-x indent-code-rigidly -Shift all the lines in the region rigidly sideways, but do not alter -lines that start inside comments and strings. -@end table - -@kindex C-M-q -@findex indent-pp-sexp - To reindent the contents of a single parenthetical grouping, -position point before the beginning of the grouping and type -@kbd{C-M-q}. This changes the relative indentation within the -grouping, without affecting its overall indentation (i.e., the -indentation of the line where the grouping starts). The function that -@kbd{C-M-q} runs depends on the major mode; it is -@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode, -etc. To correct the overall indentation as well, type @key{TAB} -first. - -@kindex C-u TAB - If you like the relative indentation within a grouping but not the -indentation of its first line, move point to that first line and type -@kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes, -@key{TAB} with a numeric argument reindents the current line as usual, -then reindents by the same amount all the lines in the parenthetical -grouping starting on the current line. It is clever, though, and does -not alter lines that start inside strings. Neither does it alter C -preprocessor lines when in C mode, but it does reindent any -continuation lines that may be attached to them. - -@findex indent-code-rigidly - The command @kbd{M-x indent-code-rigidly} rigidly shifts all the -lines in the region sideways, like @code{indent-rigidly} does -(@pxref{Indentation Commands}). It doesn't alter the indentation of -lines that start inside a string, unless the region also starts inside -that string. The prefix arg specifies the number of columns to -indent. - -@node Lisp Indent -@subsection Customizing Lisp Indentation -@cindex customizing Lisp indentation - - The indentation pattern for a Lisp expression can depend on the function -called by the expression. For each Lisp function, you can choose among -several predefined patterns of indentation, or define an arbitrary one with -a Lisp program. - - The standard pattern of indentation is as follows: the second line of the -expression is indented under the first argument, if that is on the same -line as the beginning of the expression; otherwise, the second line is -indented underneath the function name. Each following line is indented -under the previous line whose nesting depth is the same. - -@vindex lisp-indent-offset - If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides -the usual indentation pattern for the second line of an expression, so that -such lines are always indented @code{lisp-indent-offset} more columns than -the containing list. - -@vindex lisp-body-indent - Certain functions override the standard pattern. Functions whose -names start with @code{def} treat the second lines as the start of -a @dfn{body}, by indenting the second line @code{lisp-body-indent} -additional columns beyond the open-parenthesis that starts the -expression. - -@cindex @code{lisp-indent-function} property - You can override the standard pattern in various ways for individual -functions, according to the @code{lisp-indent-function} property of -the function name. This is normally done for macro definitions, using -the @code{declare} construct. @xref{Defining Macros,,, elisp, the -Emacs Lisp Reference Manual}. - -@node C Indent -@subsection Commands for C Indentation - - Here are special features for indentation in C mode and related modes: - -@table @code -@item C-c C-q -@kindex C-c C-q @r{(C mode)} -@findex c-indent-defun -Reindent the current top-level function definition or aggregate type -declaration (@code{c-indent-defun}). - -@item C-M-q -@kindex C-M-q @r{(C mode)} -@findex c-indent-exp -Reindent each line in the balanced expression that follows point -(@code{c-indent-exp}). A prefix argument inhibits warning messages -about invalid syntax. - -@item @key{TAB} -@findex c-indent-command -Reindent the current line, and/or in some cases insert a tab character -(@code{c-indent-command}). - -@vindex c-tab-always-indent -If @code{c-tab-always-indent} is @code{t}, this command always reindents -the current line and does nothing else. This is the default. - -If that variable is @code{nil}, this command reindents the current line -only if point is at the left margin or in the line's indentation; -otherwise, it inserts a tab (or the equivalent number of spaces, -if @code{indent-tabs-mode} is @code{nil}). - -Any other value (not @code{nil} or @code{t}) means always reindent the -line, and also insert a tab if within a comment or a string. -@end table - - To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This -first selects the whole buffer as the region, then reindents that -region. - - To reindent the current block, use @kbd{C-M-u C-M-q}. This moves -to the front of the block and then reindents it all. - -@node Custom C Indent -@subsection Customizing C Indentation -@cindex style (for indentation) - - C mode and related modes use a flexible mechanism for customizing -indentation. C mode indents a source line in two steps: first it -classifies the line syntactically according to its contents and -context; second, it determines the indentation offset associated by -your selected @dfn{style} with the syntactic construct and adds this -onto the indentation of the @dfn{anchor statement}. - -@table @kbd -@item C-c . @key{RET} @var{style} @key{RET} -Select a predefined style @var{style} (@code{c-set-style}). -@end table - - A @dfn{style} is a named collection of customizations that can be -used in C mode and the related modes. @ref{Styles,,, ccmode, The CC -Mode Manual}, for a complete description. Emacs comes with several -predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, -@code{stroustrup}, @code{linux}, @code{python}, @code{java}, -@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these -styles are primarily intended for one language, but any of them can be -used with any of the languages supported by these modes. To find out -what a style looks like, select it and reindent some code, e.g., by -typing @key{C-M-q} at the start of a function definition. - -@kindex C-c . @r{(C mode)} -@findex c-set-style - To choose a style for the current buffer, use the command @w{@kbd{C-c -.}}. Specify a style name as an argument (case is not significant). -This command affects the current buffer only, and it affects only -future invocations of the indentation commands; it does not reindent -the code already in the buffer. To reindent the whole buffer in the -new style, you can type @kbd{C-x h C-M-\}. - -@vindex c-default-style - You can also set the variable @code{c-default-style} to specify the -default style for various major modes. Its value should be either the -style's name (a string) or an alist, in which each element specifies -one major mode and which indentation style to use for it. For -example, - -@example -(setq c-default-style - '((java-mode . "java") - (awk-mode . "awk") - (other . "gnu"))) -@end example - -@noindent -specifies explicit choices for Java and AWK modes, and the default -@samp{gnu} style for the other C-like modes. (These settings are -actually the defaults.) This variable takes effect when you select -one of the C-like major modes; thus, if you specify a new default -style for Java mode, you can make it take effect in an existing Java -mode buffer by typing @kbd{M-x java-mode} there. - - The @code{gnu} style specifies the formatting recommended by the GNU -Project for C; it is the default, so as to encourage use of our -recommended style. - - @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and -@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more -information on customizing indentation for C and related modes, -including how to override parts of an existing style and how to define -your own styles. - -@findex c-guess -@findex c-guess-install - As an alternative to specifying a style, you can tell Emacs to guess -a style by typing @kbd{M-x c-guess} in a sample code buffer. You can -then apply the guessed style to other buffers with @kbd{M-x -c-guess-install}. @xref{Guessing the Style,,, ccmode, the CC Mode -Manual}, for details. - -@node Parentheses -@section Commands for Editing with Parentheses - -@findex check-parens -@cindex unbalanced parentheses and quotes - This section describes the commands and features that take advantage -of the parenthesis structure in a program, or help you keep it -balanced. - - When talking about these facilities, the term ``parenthesis'' also -includes braces, brackets, or whatever delimiters are defined to match -in pairs. The major mode controls which delimiters are significant, -through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp, -The Emacs Lisp Reference Manual}). In Lisp, only parentheses count; -in C, these commands apply to braces and brackets too. - - You can use @kbd{M-x check-parens} to find any unbalanced -parentheses and unbalanced string quotes in the buffer. - -@menu -* Expressions:: Expressions with balanced parentheses. -* Moving by Parens:: Commands for moving up, down and across - in the structure of parentheses. -* Matching:: Insertion of a close-delimiter flashes matching open. -@end menu - -@node Expressions -@subsection Expressions with Balanced Parentheses - -@cindex sexp -@cindex expression -@cindex balanced expression - Each programming language mode has its own definition of a -@dfn{balanced expression}. Balanced expressions typically include -individual symbols, numbers, and string constants, as well as pieces -of code enclosed in a matching pair of delimiters. The following -commands deal with balanced expressions (in Emacs, such expressions -are referred to internally as @dfn{sexps}@footnote{The word ``sexp'' -is used to refer to an expression in Lisp.}). - -@table @kbd -@item C-M-f -Move forward over a balanced expression (@code{forward-sexp}). -@item C-M-b -Move backward over a balanced expression (@code{backward-sexp}). -@item C-M-k -Kill balanced expression forward (@code{kill-sexp}). -@item C-M-t -Transpose expressions (@code{transpose-sexps}). -@item C-M-@@ -@itemx C-M-@key{SPC} -Put mark after following expression (@code{mark-sexp}). -@end table - -@kindex C-M-f -@kindex C-M-b -@findex forward-sexp -@findex backward-sexp - To move forward over a balanced expression, use @kbd{C-M-f} -(@code{forward-sexp}). If the first significant character after point -is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C), -this command moves past the matching closing delimiter. If the -character begins a symbol, string, or number, the command moves over -that. - - The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a -balanced expression---like @kbd{C-M-f}, but in the reverse direction. -If the expression is preceded by any prefix characters (single-quote, -backquote and comma, in Lisp), the command moves back over them as -well. - - @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation -the specified number of times; with a negative argument means to move -in the opposite direction. In most modes, these two commands move -across comments as if they were whitespace. Note that their keys, -@kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b}, -which move by characters (@pxref{Moving Point}), and @kbd{M-f} and -@kbd{M-b}, which move by words (@pxref{Words}). - -@cindex killing expressions -@kindex C-M-k -@findex kill-sexp - To kill a whole balanced expression, type @kbd{C-M-k} -(@code{kill-sexp}). This kills the text that @kbd{C-M-f} would move -over. - -@cindex transposition of expressions -@kindex C-M-t -@findex transpose-sexps - @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the -previous balanced expression and the next one. It is analogous to the -@kbd{C-t} command, which transposes characters (@pxref{Transpose}). -An argument to @kbd{C-M-t} serves as a repeat count, moving the -previous expression over that many following ones. A negative -argument moves the previous balanced expression backwards across those -before it. An argument of zero, rather than doing nothing, transposes -the balanced expressions ending at or after point and the mark. - -@kindex C-M-@@ -@kindex C-M-@key{SPC} -@findex mark-sexp - To operate on balanced expressions with a command which acts on the -region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}). This sets the -mark where @kbd{C-M-f} would move to. While the mark is active, each -successive call to this command extends the region by shifting the -mark by one expression. Positive or negative numeric arguments move -the mark forward or backward by the specified number of expressions. -The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}. -@xref{Marking Objects}, for more information about this and related -commands. - - In languages that use infix operators, such as C, it is not possible -to recognize all balanced expressions because there can be multiple -possibilities at a given position. For example, C mode does not treat -@samp{foo + bar} as a single expression, even though it @emph{is} one -C expression; instead, it recognizes @samp{foo} as one expression and -@samp{bar} as another, with the @samp{+} as punctuation between them. -However, C mode recognizes @samp{(foo + bar)} as a single expression, -because of the parentheses. - -@node Moving by Parens -@subsection Moving in the Parenthesis Structure - -@cindex parenthetical groupings -@cindex parentheses, moving across -@cindex matching parenthesis and braces, moving to -@cindex braces, moving across -@cindex list commands - - The following commands move over groupings delimited by parentheses -(or whatever else serves as delimiters in the language you are working -with). They ignore strings and comments, including any parentheses -within them, and also ignore parentheses that are ``quoted'' with an -escape character. These commands are mainly intended for editing -programs, but can be useful for editing any text containing -parentheses. They are referred to internally as ``list'' commands -because in Lisp these groupings are lists. - - These commands assume that the starting point is not inside a string -or a comment. If you invoke them from inside a string or comment, the -results are unreliable. - -@table @kbd -@item C-M-n -Move forward over a parenthetical group (@code{forward-list}). -@item C-M-p -Move backward over a parenthetical group (@code{backward-list}). -@item C-M-u -Move up in parenthesis structure (@code{backward-up-list}). -@item C-M-d -Move down in parenthesis structure (@code{down-list}). -@end table - -@kindex C-M-n -@kindex C-M-p -@findex forward-list -@findex backward-list - The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and -@kbd{C-M-p} (@code{backward-list}) move forward or backward over one -(or @var{n}) parenthetical groupings. - -@kindex C-M-u -@findex backward-up-list - @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the -parenthesis structure. To move @emph{up} one (or @var{n}) levels, use -@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up -past one unmatched opening delimiter. A positive argument serves as a -repeat count; a negative argument reverses the direction of motion, so -that the command moves forward and up one or more levels. - -@kindex C-M-d -@findex down-list - To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} -(@code{down-list}). In Lisp mode, where @samp{(} is the only opening -delimiter, this is nearly the same as searching for a @samp{(}. An -argument specifies the number of levels to go down. - -@node Matching -@subsection Matching Parentheses -@cindex matching parentheses -@cindex parentheses, displaying matches - - Emacs has a number of @dfn{parenthesis matching} features, which -make it easy to see how and whether parentheses (or other delimiters) -match up. - - Whenever you type a self-inserting character that is a closing -delimiter, Emacs briefly indicates the location of the matching -opening delimiter, provided that is on the screen. If it is not on -the screen, Emacs displays some of the text near it in the echo area. -Either way, you can tell which grouping you are closing off. If the -opening delimiter and closing delimiter are mismatched---such as in -@samp{[x)}---a warning message is displayed in the echo area. - -@vindex blink-matching-paren -@vindex blink-matching-paren-distance -@vindex blink-matching-delay - Three variables control the display of matching parentheses: - -@itemize @bullet -@item -@code{blink-matching-paren} turns the feature on or off: @code{nil} -disables it, but the default is @code{t} to enable it. Set it to -@code{jump} to make indication work by momentarily moving the cursor -to the matching opening delimiter. - -@item -@code{blink-matching-delay} says how many seconds to keep indicating -the matching opening delimiter. This may be an integer or -floating-point number; the default is 1. - -@item -@code{blink-matching-paren-distance} specifies how many characters -back to search to find the matching opening delimiter. If the match -is not found in that distance, Emacs stops scanning and nothing is -displayed. The default is 102400. -@end itemize - -@cindex Show Paren mode -@cindex highlighting matching parentheses -@findex show-paren-mode - Show Paren mode, a global minor mode, provides a more powerful kind -of automatic matching. Whenever point is before an opening delimiter -or after a closing delimiter, both that delimiter and its opposite -delimiter are highlighted. To toggle Show Paren mode, type @kbd{M-x -show-paren-mode}. - -@cindex Electric Pair mode -@cindex inserting matching parentheses -@findex electric-pair-mode - Electric Pair mode, a global minor mode, provides a way to easily -insert matching delimiters. Whenever you insert an opening delimiter, -the matching closing delimiter is automatically inserted as well, -leaving point between the two. Conversely, when you insert a closing -delimiter over an existing one, no inserting takes places and that -position is simply skipped over. These variables control additional -features of Electric Pair mode: - -@itemize @bullet -@item -@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the -default pairing logic balance out the number of opening and closing -delimiters. - -@item -@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes -backspacing between two adjacent delimiters also automatically delete -the closing delimiter. - -@item -@code{electric-pair-open-newline-between-pairs}, when non-@code{nil}, -makes inserting inserting a newline between two adjacent pairs also -automatically open and extra newline after point. - -@item -@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor -mode to skip whitespace forward before deciding whether to skip over -the closing delimiter. -@end itemize - -To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}. - -@node Comments -@section Manipulating Comments -@cindex comments - - Because comments are such an important part of programming, Emacs -provides special commands for editing and inserting comments. It can -also do spell checking on comments with Flyspell Prog mode -(@pxref{Spelling}). - - Some major modes have special rules for indenting different kinds of -comments. For example, in Lisp code, comments starting with two -semicolons are indented as if they were lines of code, while those -starting with three semicolons are supposed to be aligned to the left -margin and are often used for sectioning purposes. Emacs understand -these conventions; for instance, typing @key{TAB} on a comment line -will indent the comment to the appropriate position. - -@example -;; This function is just an example. -;;; Here either two or three semicolons are appropriate. -(defun foo (x) -;;; And now, the first part of the function: - ;; The following line adds one. - (1+ x)) ; This line adds one. -@end example - -@menu -* Comment Commands:: Inserting, killing, and aligning comments. -* Multi-Line Comments:: Commands for adding and editing multi-line comments. -* Options for Comments::Customizing the comment features. -@end menu - -@node Comment Commands -@subsection Comment Commands -@cindex indentation for comments -@cindex alignment for comments - - The following commands operate on comments: - -@table @asis -@item @kbd{M-;} -Insert or realign comment on current line; if the region is active, -comment or uncomment the region instead (@code{comment-dwim}). -@item @kbd{C-u M-;} -Kill comment on current line (@code{comment-kill}). -@item @kbd{C-x ;} -Set comment column (@code{comment-set-column}). -@item @kbd{C-M-j} -@itemx @kbd{M-j} -Like @key{RET} followed by inserting and aligning a comment -(@code{comment-indent-new-line}). @xref{Multi-Line Comments}. -@item @kbd{M-x comment-region} -@itemx @kbd{C-c C-c} (in C-like modes) -Add comment delimiters to all the lines in the region. -@end table - -@kindex M-; -@findex comment-dwim - The command to create or align a comment is @kbd{M-;} -(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What -I Mean''; it indicates that this command can be used for many -different jobs relating to comments, depending on the situation where -you use it. - - When a region is active (@pxref{Mark}), @kbd{M-;} either adds -comment delimiters to the region, or removes them. If every line in -the region is already a comment, it ``uncomments'' each of those lines -by removing their comment delimiters. Otherwise, it adds comment -delimiters to enclose the text in the region. - - If you supply a prefix argument to @kbd{M-;} when a region is -active, that specifies the number of comment delimiters to add or -delete. A positive argument @var{n} adds @var{n} delimiters, while a -negative argument @var{-n} removes @var{n} delimiters. - - If the region is not active, and there is no existing comment on the -current line, @kbd{M-;} adds a new comment to the current line. If -the line is blank (i.e., empty or containing only whitespace -characters), the comment is indented to the same position where -@key{TAB} would indent to (@pxref{Basic Indent}). If the line is -non-blank, the comment is placed after the last non-whitespace -character on the line; normally, Emacs tries putting it at the column -specified by the variable @code{comment-column} (@pxref{Options for -Comments}), but if the line already extends past that column, it puts -the comment at some suitable position, usually separated from the -non-comment text by at least one space. In each case, Emacs places -point after the comment's starting delimiter, so that you can start -typing the comment text right away. - - You can also use @kbd{M-;} to align an existing comment. If a line -already contains the comment-start string, @kbd{M-;} realigns it to -the conventional alignment and moves point after the comment's -starting delimiter. As an exception, comments starting in column 0 -are not moved. Even when an existing comment is properly aligned, -@kbd{M-;} is still useful for moving directly to the start of the -comment text. - -@findex comment-kill -@kindex C-u M-; - @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any -comment on the current line, along with the whitespace before it. -Since the comment is saved to the kill ring, you can reinsert it on -another line by moving to the end of that line, doing @kbd{C-y}, and -then @kbd{M-;} to realign the comment. You can achieve the same -effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill} -(@code{comment-dwim} actually calls @code{comment-kill} as a -subroutine when it is given a prefix argument). - -@kindex C-c C-c (C mode) -@findex comment-region -@findex uncomment-region - The command @kbd{M-x comment-region} is equivalent to calling -@kbd{M-;} on an active region, except that it always acts on the -region, even if the mark is inactive. In C mode and related modes, -this command is bound to @kbd{C-c C-c}. The command @kbd{M-x -uncomment-region} uncomments each line in the region; a numeric prefix -argument specifies the number of comment delimiters to remove -(negative arguments specify the number of comment to delimiters to -add). - - For C-like modes, you can configure the exact effect of @kbd{M-;} by -setting the variables @code{c-indent-comment-alist} and -@code{c-indent-comments-syntactically-p}. For example, on a line -ending in a closing brace, @kbd{M-;} puts the comment one space after -the brace rather than at @code{comment-column}. For full details see -@ref{Comment Commands,,, ccmode, The CC Mode Manual}. - -@node Multi-Line Comments -@subsection Multiple Lines of Comments - -@kindex C-M-j -@kindex M-j -@cindex blank lines in programs -@findex comment-indent-new-line -@vindex comment-multi-line - If you are typing a comment and wish to continue it to another line, -type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}). This -breaks the current line, and inserts the necessary comment delimiters -and indentation to continue the comment. - - For languages with closing comment delimiters (e.g., @samp{*/} in -C), the exact behavior of @kbd{M-j} depends on the value of the -variable @code{comment-multi-line}. If the value is @code{nil}, the -command closes the comment on the old line and starts a new comment on -the new line. Otherwise, it opens a new line within the current -comment delimiters. - - When Auto Fill mode is on, going past the fill column while typing a -comment also continues the comment, in the same way as an explicit -invocation of @kbd{M-j}. - - To turn existing lines into comment lines, use @kbd{M-;} with the -region active, or use @kbd{M-x comment-region} -@ifinfo -(@pxref{Comment Commands}). -@end ifinfo -@ifnotinfo -as described in the preceding section. -@end ifnotinfo - - You can configure C Mode such that when you type a @samp{/} at the -start of a line in a multi-line block comment, this closes the -comment. Enable the @code{comment-close-slash} clean-up for this. -@xref{Clean-ups,,, ccmode, The CC Mode Manual}. - -@node Options for Comments -@subsection Options Controlling Comments - -@vindex comment-column -@kindex C-x ; -@findex comment-set-column - As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command -adds a comment to a line, it tries to place the comment at the column -specified by the buffer-local variable @code{comment-column}. You can -set either the local value or the default value of this buffer-local -variable in the usual way (@pxref{Locals}). Alternatively, you can -type @kbd{C-x ;} (@code{comment-set-column}) to set the value of -@code{comment-column} in the current buffer to the column where point -is currently located. @kbd{C-u C-x ;} sets the comment column to -match the last comment before point in the buffer, and then does a -@kbd{M-;} to align the current line's comment under the previous one. - -@vindex comment-start-skip - The comment commands recognize comments based on the regular -expression that is the value of the variable @code{comment-start-skip}. -Make sure this regexp does not match the null string. It may match more -than the comment starting delimiter in the strictest sense of the word; -for example, in C mode the value of the variable is -@c This stops M-q from breaking the line inside that @code. -@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and -spaces after the @samp{/*} itself, and accepts C++ style comments -also. (Note that @samp{\\} is needed in Lisp syntax to include a -@samp{\} in the string, which is needed to deny the first star its -special meaning in regexp syntax. @xref{Regexp Backslash}.) - -@vindex comment-start -@vindex comment-end - When a comment command makes a new comment, it inserts the value of -@code{comment-start} as an opening comment delimiter. It also inserts -the value of @code{comment-end} after point, as a closing comment -delimiter. For example, in Lisp mode, @code{comment-start} is -@samp{";"} and @code{comment-end} is @code{""} (the empty string). In -C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is -@code{" */"}. - -@vindex comment-padding - The variable @code{comment-padding} specifies a string that the -commenting commands should insert between the comment delimiter(s) and -the comment text. The default, @samp{" "}, specifies a single space. -Alternatively, the value can be a number, which specifies that number -of spaces, or @code{nil}, which means no spaces at all. - - The variable @code{comment-multi-line} controls how @kbd{M-j} and -Auto Fill mode continue comments over multiple lines. -@xref{Multi-Line Comments}. - -@vindex comment-indent-function - The variable @code{comment-indent-function} should contain a function -that will be called to compute the alignment for a newly inserted -comment or for aligning an existing comment. It is set differently by -various major modes. The function is called with no arguments, but with -point at the beginning of the comment, or at the end of a line if a new -comment is to be inserted. It should return the column in which the -comment ought to start. For example, in Lisp mode, the indent hook -function bases its decision on how many semicolons begin an existing -comment, and on the code in the preceding lines. - -@node Documentation -@section Documentation Lookup - - Emacs provides several features you can use to look up the -documentation of functions, variables and commands that you plan to -use in your program. - -@menu -* Info Lookup:: Looking up library functions and commands in Info files. -* Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. -@end menu - -@node Info Lookup -@subsection Info Documentation Lookup - -@findex info-lookup-symbol -@findex info-lookup-file -@kindex C-h S - For major modes that apply to languages which have documentation in -Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the -Info documentation for a symbol used in the program. You specify the -symbol with the minibuffer; the default is the symbol appearing in the -buffer at point. For example, in C mode this looks for the symbol in -the C Library Manual. The command only works if the appropriate -manual's Info files are installed. - - The major mode determines where to look for documentation for the -symbol---which Info files to look in, and which indices to search. -You can also use @kbd{M-x info-lookup-file} to look for documentation -for a file name. - - If you use @kbd{C-h S} in a major mode that does not support it, -it asks you to specify the ``symbol help mode''. You should enter -a command such as @code{c-mode} that would select a major -mode which @kbd{C-h S} does support. - -@node Man Page -@subsection Man Page Lookup - -@cindex man page - On Unix, the main form of on-line documentation was the @dfn{manual -page} or @dfn{man page}. In the GNU operating system, we aim to -replace man pages with better-organized manuals that you can browse -with Info (@pxref{Misc Help}). This process is not finished, so it is -still useful to read manual pages. - -@findex manual-entry - You can read the man page for an operating system command, library -function, or system call, with the @kbd{M-x man} command. This -prompts for a topic, with completion (@pxref{Completion}), and runs -the @command{man} program to format the corresponding man page. If -the system permits, it runs @command{man} asynchronously, so that you -can keep on editing while the page is being formatted. The result -goes in a buffer named @file{*Man @var{topic}*}. These buffers use a -special major mode, Man mode, that facilitates scrolling and jumping -to other manual pages. For details, type @kbd{C-h m} while in a Man -mode buffer. - -@cindex sections of manual pages - Each man page belongs to one of ten or more @dfn{sections}, each -named by a digit or by a digit and a letter. Sometimes there are man -pages with the same name in different sections. To read a man page -from a specific section, type @samp{@var{topic}(@var{section})} or -@samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts -for the topic. For example, the man page for the C library function -@code{chmod} is in section 2, but there is a shell command of the same -name, whose man page is in section 1; to view the former, type -@kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}. - -@vindex Man-switches -@kindex M-n @r{(Man mode)} -@kindex M-p @r{(Man mode)} - If you do not specify a section, @kbd{M-x man} normally displays -only the first man page found. On some systems, the @code{man} -program accepts a @samp{-a} command-line option, which tells it to -display all the man pages for the specified topic. To make use of -this, change the value of the variable @code{Man-switches} to -@samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and -@kbd{M-p} to switch between man pages in different sections. The mode -line shows how many manual pages are available. - -@findex woman -@cindex manual pages, on MS-DOS/MS-Windows - An alternative way of reading manual pages is the @kbd{M-x woman} -command. Unlike @kbd{M-x man}, it does not run any external programs -to format and display the man pages; the formatting is done by Emacs, -so it works on systems such as MS-Windows where the @command{man} -program may be unavailable. It prompts for a man page, and displays -it in a buffer named @file{*WoMan @var{section} @var{topic}}. - - @kbd{M-x woman} computes the completion list for manpages the first -time you invoke the command. With a numeric argument, it recomputes -this list; this is useful if you add or delete manual pages. - - If you type a name of a manual page and @kbd{M-x woman} finds that -several manual pages by the same name exist in different sections, it -pops up a window with possible candidates asking you to choose one of -them. - - For more information about setting up and using @kbd{M-x woman}, see -@ifinfo -@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The -WoMan Manual}. -@end ifinfo -@ifnotinfo -the WoMan Info manual, which is distributed with Emacs. -@end ifnotinfo - -@node Lisp Doc -@subsection Emacs Lisp Documentation Lookup - - When editing Emacs Lisp code, you can use the commands @kbd{C-h f} -(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) -to view the built-in documentation for the Lisp functions and -variables that you want to use. @xref{Name Help}. - -@cindex Eldoc mode -@findex eldoc-mode - Eldoc is a buffer-local minor mode that helps with looking up Lisp -documentation. When it is enabled, the echo area displays some useful -information whenever there is a Lisp function or variable at point; -for a function, it shows the argument list, and for a variable it -shows the first line of the variable's documentation string. To -toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used -with the Emacs Lisp and Lisp Interaction major modes. - -@node Hideshow -@section Hideshow minor mode -@cindex Hideshow mode -@cindex mode, Hideshow - -@findex hs-minor-mode - Hideshow mode is a buffer-local minor mode that allows you to -selectively display portions of a program, which are referred to as -@dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode -(@pxref{Minor Modes}). - - When you use Hideshow mode to hide a block, the block disappears -from the screen, to be replaced by an ellipsis (three periods in a -row). Just what constitutes a block depends on the major mode. In C -mode and related modes, blocks are delimited by braces, while in Lisp -mode they are delimited by parentheses. Multi-line comments also -count as blocks. - - Hideshow mode provides the following commands: - -@findex hs-hide-all -@findex hs-hide-block -@findex hs-show-all -@findex hs-show-block -@findex hs-show-region -@findex hs-hide-level -@findex hs-minor-mode -@kindex C-c @@ C-h -@kindex C-c @@ C-s -@kindex C-c @@ C-M-h -@kindex C-c @@ C-M-s -@kindex C-c @@ C-r -@kindex C-c @@ C-l -@kindex S-Mouse-2 -@table @kbd -@item C-c @@ C-h -Hide the current block (@code{hs-hide-block}). -@item C-c @@ C-s -Show the current block (@code{hs-show-block}). -@item C-c @@ C-c -Either hide or show the current block (@code{hs-toggle-hiding}). -@item S-Mouse-2 -Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}). -@item C-c @@ C-M-h -Hide all top-level blocks (@code{hs-hide-all}). -@item C-c @@ C-M-s -Show all blocks in the buffer (@code{hs-show-all}). -@item C-c @@ C-l -Hide all blocks @var{n} levels below this block -(@code{hs-hide-level}). -@end table - -@vindex hs-hide-comments-when-hiding-all -@vindex hs-isearch-open -@vindex hs-special-modes-alist - These variables can be used to customize Hideshow mode: - -@table @code -@item hs-hide-comments-when-hiding-all -If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides -comments too. - -@item hs-isearch-open -This variable specifies the conditions under which incremental search -should unhide a hidden block when matching text occurs within the -block. Its value should be either @code{code} (unhide only code -blocks), @code{comment} (unhide only comments), @code{t} (unhide both -code blocks and comments), or @code{nil} (unhide neither code blocks -nor comments). The default value is @code{code}. -@end table - -@node Symbol Completion -@section Completion for Symbol Names -@cindex completion (symbol names) - - Completion is normally done in the minibuffer (@pxref{Completion}), -but you can also complete symbol names in ordinary Emacs buffers. - -@kindex M-TAB -@kindex C-M-i - In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}} -to complete the partial symbol before point. On graphical displays, -the @kbd{M-@key{TAB}} key is usually reserved by the window manager -for switching graphical windows, so you should type @kbd{C-M-i} or -@kbd{@key{ESC} @key{TAB}} instead. - -@cindex tags-based completion -@findex completion-at-point -@cindex Lisp symbol completion -@cindex completion (Lisp symbols) - In most programming language modes, @kbd{C-M-i} (or -@kbd{M-@key{TAB}}) invokes the command @code{completion-at-point}, -which generates its completion list in a flexible way. If Semantic -mode is enabled, it tries to use the Semantic parser data for -completion (@pxref{Semantic}). If Semantic mode is not enabled or -fails at performing completion, it tries to complete using the -selected tags table (@pxref{Tags}). If in Emacs Lisp mode, it -performs completion using the function, variable, or property names -defined in the current Emacs session. - - In all other respects, in-buffer symbol completion behaves like -minibuffer completion. For instance, if Emacs cannot complete to a -unique symbol, it displays a list of completion alternatives in -another window. @xref{Completion}. - - In Text mode and related modes, @kbd{M-@key{TAB}} completes words -based on the spell-checker's dictionary. @xref{Spelling}. - -@node MixedCase Words -@section MixedCase Words -@cindex camel case - - Some programming styles make use of mixed-case (or ``CamelCase'') -symbols like @samp{unReadableSymbol}. (In the GNU project, we recommend -using underscores to separate words within an identifier, rather than -using case distinctions.) Emacs has various features to make it easier -to deal with such symbols. - -@cindex Glasses mode -@findex mode, Glasses - Glasses mode is a buffer-local minor mode that makes it easier to read -such symbols, by altering how they are displayed. By default, it -displays extra underscores between each lower-case letter and the -following capital letter. This does not alter the buffer text, only how -it is displayed. - - To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor -Modes}). When Glasses mode is enabled, the minor mode indicator -@samp{o^o} appears in the mode line. For more information about -Glasses mode, type @kbd{C-h P glasses @key{RET}}. - -@cindex Subword mode -@findex subword-mode - Subword mode is another buffer-local minor mode. In subword mode, -Emacs's word commands recognize upper case letters in -@samp{StudlyCapsIdentifiers} as word boundaries. When Subword mode is -enabled, the minor mode indicator @samp{,} appears in the mode line. -See also the similar @code{superword-mode} (@pxref{Misc for Programs}). - -@node Semantic -@section Semantic -@cindex Semantic package - -Semantic is a package that provides language-aware editing commands -based on @code{source code parsers}. This section provides a brief -description of Semantic; for full details, -@ifnottex -see @ref{Top, Semantic,, semantic, Semantic}. -@end ifnottex -@iftex -see the Semantic Info manual, which is distributed with Emacs. -@end iftex - - Most of the ``language aware'' features in Emacs, such as Font Lock -mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular -expressions and syntax tables.} that usually give good results but are -never completely exact. In contrast, the parsers used by Semantic -have an exact understanding of programming language syntax. This -allows Semantic to provide search, navigation, and completion commands -that are powerful and precise. - -@cindex Semantic mode -@cindex mode, Semantic - To begin using Semantic, type @kbd{M-x semantic-mode} or click on -the menu item named @samp{Source Code Parsers (Semantic)} in the -@samp{Tools} menu. This enables Semantic mode, a global minor mode. - - When Semantic mode is enabled, Emacs automatically attempts to -parse each file you visit. Currently, Semantic understands C, C++, -Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer, -the following commands are available: - -@table @kbd -@item C-c , j -@kindex C-c , j -Prompt for the name of a function defined in the current file, and -move point there (@code{semantic-complete-jump-local}). - -@item C-c , J -@kindex C-c , J -Prompt for the name of a function defined in any file Emacs has -parsed, and move point there (@code{semantic-complete-jump}). - -@item C-c , @key{SPC} -@kindex C-c , @key{SPC} -Display a list of possible completions for the symbol at point -(@code{semantic-complete-analyze-inline}). This also activates a set -of special key bindings for choosing a completion: @key{RET} accepts -the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible -completions, @key{TAB} completes as far as possible and then cycles, -and @kbd{C-g} or any other key aborts completion. - -@item C-c , l -@kindex C-c , l -Display a list of the possible completions of the symbol at point, in -another window (@code{semantic-analyze-possible-completions}). -@end table - -@noindent -In addition to the above commands, the Semantic package provides a -variety of other ways to make use of parser information. For -instance, you can use it to display a list of completions when Emacs -is idle. -@ifnottex -@xref{Top, Semantic,, semantic, Semantic}, for details. -@end ifnottex - -@node Misc for Programs -@section Other Features Useful for Editing Programs - - Some Emacs commands that aren't designed specifically for editing -programs are useful for that nonetheless. - - The Emacs commands that operate on words, sentences and paragraphs -are useful for editing code. Most symbols names contain words -(@pxref{Words}), while sentences can be found in strings and comments -(@pxref{Sentences}). As for paragraphs, they are defined in most -programming language modes to begin and end at blank lines -(@pxref{Paragraphs}). Therefore, judicious use of blank lines to make -the program clearer will also provide useful chunks of text for the -paragraph commands to work on. Auto Fill mode, if enabled in a -programming language major mode, indents the new lines which it -creates. - -@findex superword-mode - Superword mode is a buffer-local minor mode that causes editing and -motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words. -When Subword mode is enabled, the minor mode indicator -@iftex -@samp{@math{^2}} -@end iftex -@ifnottex -@samp{²} -@end ifnottex -appears in the mode line. See also the similar @code{subword-mode} -(@pxref{MixedCase Words}). - -@findex electric-layout-mode - Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global -minor mode that automatically inserts newlines when you type certain -characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript -mode. - - Apart from Hideshow mode (@pxref{Hideshow}), another way to -selectively display parts of a program is to use the selective display -feature (@pxref{Selective Display}). Programming modes often also -support Outline minor mode (@pxref{Outline Mode}), which can be used -with the Foldout package (@pxref{Foldout}). - -@ifinfo - The ``automatic typing'' features may be useful for writing programs. -@xref{Top,,Autotyping, autotype, Autotyping}. -@end ifinfo - -@findex prettify-symbols-mode - Prettify Symbols mode is a buffer-local minor mode that replaces -certain strings with more ``attractive'' versions for display -purposes. For example, in Emacs Lisp mode, it replaces the string -``lambda'' with the Greek lambda character. You may wish to use this -in non-programming modes as well. You can customize the mode by -adding more entries to @code{prettify-symbols-alist}. There is also a -global version, @code{global-prettify-symbols-mode}, which enables the -mode in all buffers that support it. - - -@node C Modes -@section C and Related Modes -@cindex C mode -@cindex Java mode -@cindex Pike mode -@cindex IDL mode -@cindex CORBA IDL mode -@cindex Objective C mode -@cindex C++ mode -@cindex AWK mode -@cindex mode, Java -@cindex mode, C -@cindex mode, C++ -@cindex mode, Objective C -@cindex mode, CORBA IDL -@cindex mode, Pike -@cindex mode, AWK - - This section gives a brief description of the special features -available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. -(These are called ``C mode and related modes''.) -@ifinfo -@xref{Top,, CC Mode, ccmode, CC Mode}, for more details. -@end ifinfo -@ifnotinfo -For more details, see the CC mode Info manual, which is distributed -with Emacs. -@end ifnotinfo - -@menu -* Motion in C:: Commands to move by C statements, etc. -* Electric C:: Colon and other chars can automatically reindent. -* Hungry Delete:: A more powerful DEL command. -* Other C Commands:: Filling comments, viewing expansion of macros, - and other neat features. -@end menu - -@node Motion in C -@subsection C Mode Motion Commands - - This section describes commands for moving point, in C mode and -related modes. - -@table @code -@item C-M-a -@itemx C-M-e -@findex c-beginning-of-defun -@findex c-end-of-defun -Move point to the beginning or end of the current function or -top-level definition. In languages with enclosing scopes (such as -C++'s classes) the @dfn{current function} is the immediate one, -possibly inside a scope. Otherwise it is the one defined by the least -enclosing braces. (By contrast, @code{beginning-of-defun} and -@code{end-of-defun} search for braces in column zero.) @xref{Moving -by Defuns}. - -@item C-c C-u -@kindex C-c C-u @r{(C mode)} -@findex c-up-conditional -Move point back to the containing preprocessor conditional, leaving the -mark behind. A prefix argument acts as a repeat count. With a negative -argument, move point forward to the end of the containing -preprocessor conditional. - -@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so -the function will stop at a @samp{#elif} when going backward, but not -when going forward. - -@item C-c C-p -@kindex C-c C-p @r{(C mode)} -@findex c-backward-conditional -Move point back over a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move forward. - -@item C-c C-n -@kindex C-c C-n @r{(C mode)} -@findex c-forward-conditional -Move point forward across a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move backward. - -@item M-a -@kindex M-a (C mode) -@findex c-beginning-of-statement -Move point to the beginning of the innermost C statement -(@code{c-beginning-of-statement}). If point is already at the beginning -of a statement, move to the beginning of the preceding statement. With -prefix argument @var{n}, move back @var{n} @minus{} 1 statements. - -In comments or in strings which span more than one line, this command -moves by sentences instead of statements. - -@item M-e -@kindex M-e (C mode) -@findex c-end-of-statement -Move point to the end of the innermost C statement or sentence; like -@kbd{M-a} except that it moves in the other direction -(@code{c-end-of-statement}). -@end table - -@node Electric C -@subsection Electric C Characters - - In C mode and related modes, certain printing characters are -@dfn{electric}---in addition to inserting themselves, they also -reindent the current line, and optionally also insert newlines. The -``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, -@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and -@kbd{)}. - - You might find electric indentation inconvenient if you are editing -chaotically indented code. If you are new to CC Mode, you might find -it disconcerting. You can toggle electric action with the command -@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line -after the mode name: - -@table @kbd -@item C-c C-l -@kindex C-c C-l @r{(C mode)} -@findex c-toggle-electric-state -Toggle electric action (@code{c-toggle-electric-state}). With a -positive prefix argument, this command enables electric action, with a -negative one it disables it. -@end table - - Electric characters insert newlines only when, in addition to the -electric state, the @dfn{auto-newline} feature is enabled (indicated -by @samp{/la} in the mode line after the mode name). You can turn -this feature on or off with the command @kbd{C-c C-a}: - -@table @kbd -@item C-c C-a -@kindex C-c C-a @r{(C mode)} -@findex c-toggle-auto-newline -Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a -prefix argument, this command turns the auto-newline feature on if the -argument is positive, and off if it is negative. -@end table - - Usually the CC Mode style configures the exact circumstances in -which Emacs inserts auto-newlines. You can also configure this -directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. - -@node Hungry Delete -@subsection Hungry Delete Feature in C -@cindex hungry deletion (C Mode) - - If you want to delete an entire block of whitespace at point, you -can use @dfn{hungry deletion}. This deletes all the contiguous -whitespace either before point or after point in a single operation. -@dfn{Whitespace} here includes tabs and newlines, but not comments or -preprocessor commands. - -@table @kbd -@item C-c C-@key{DEL} -@itemx C-c @key{DEL} -@findex c-hungry-delete-backwards -@kindex C-c C-@key{DEL} (C Mode) -@kindex C-c @key{DEL} (C Mode) -Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}). - -@item C-c C-d -@itemx C-c C-@key{Delete} -@itemx C-c @key{Delete} -@findex c-hungry-delete-forward -@kindex C-c C-d (C Mode) -@kindex C-c C-@key{Delete} (C Mode) -@kindex C-c @key{Delete} (C Mode) -Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}). -@end table - - As an alternative to the above commands, you can enable @dfn{hungry -delete mode}. When this feature is enabled (indicated by @samp{/h} in -the mode line after the mode name), a single @key{DEL} deletes all -preceding whitespace, not just one space, and a single @kbd{C-c C-d} -(but @emph{not} plain @key{Delete}) deletes all following whitespace. - -@table @kbd -@item M-x c-toggle-hungry-state -@findex c-toggle-hungry-state -Toggle the hungry-delete feature -(@code{c-toggle-hungry-state}). With a prefix argument, -this command turns the hungry-delete feature on if the argument is -positive, and off if it is negative. -@end table - -@vindex c-hungry-delete-key - The variable @code{c-hungry-delete-key} controls whether the -hungry-delete feature is enabled. - -@node Other C Commands -@subsection Other Commands for C Mode - -@table @kbd -@item M-x c-context-line-break -@findex c-context-line-break -This command inserts a line break and indents the new line in a manner -appropriate to the context. In normal code, it does the work of -@key{RET} (@code{newline}), in a C preprocessor line it additionally -inserts a @samp{\} at the line break, and within comments it's like -@kbd{M-j} (@code{c-indent-new-comment-line}). - -@code{c-context-line-break} isn't bound to a key by default, but it -needs a binding to be useful. The following code will bind it to -@key{RET}. We use @code{c-initialization-hook} here to make sure -the keymap is loaded before we try to change it. - -@example -(defun my-bind-clb () - (define-key c-mode-base-map "\C-m" - 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-bind-clb) -@end example - -@item C-M-h -Put mark at the end of a function definition, and put point at the -beginning (@code{c-mark-function}). - -@item M-q -@kindex M-q @r{(C mode)} -@findex c-fill-paragraph -Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). -If any part of the current line is a comment or within a comment, this -command fills the comment or the paragraph of it that point is in, -preserving the comment indentation and comment delimiters. - -@item C-c C-e -@cindex macro expansion in C -@cindex expansion of C macros -@findex c-macro-expand -@kindex C-c C-e @r{(C mode)} -Run the C preprocessor on the text in the region, and show the result, -which includes the expansion of all the macro calls -(@code{c-macro-expand}). The buffer text before the region is also -included in preprocessing, for the sake of macros defined there, but the -output from this part isn't shown. - -When you are debugging C code that uses macros, sometimes it is hard to -figure out precisely how the macros expand. With this command, you -don't have to figure it out; you can see the expansions. - -@item C-c C-\ -@findex c-backslash-region -@kindex C-c C-\ @r{(C mode)} -Insert or align @samp{\} characters at the ends of the lines of the -region (@code{c-backslash-region}). This is useful after writing or -editing a C macro definition. - -If a line already ends in @samp{\}, this command adjusts the amount of -whitespace before it. Otherwise, it inserts a new @samp{\}. However, -the last line in the region is treated specially; no @samp{\} is -inserted on that line, and any @samp{\} there is deleted. - -@item M-x cpp-highlight-buffer -@cindex preprocessor highlighting -@findex cpp-highlight-buffer -Highlight parts of the text according to its preprocessor conditionals. -This command displays another buffer named @file{*CPP Edit*}, which -serves as a graphic menu for selecting how to display particular kinds -of conditionals and their contents. After changing various settings, -click on @samp{[A]pply these settings} (or go to that buffer and type -@kbd{a}) to rehighlight the C mode buffer accordingly. - -@item C-c C-s -@findex c-show-syntactic-information -@kindex C-c C-s @r{(C mode)} -Display the syntactic information about the current source line -(@code{c-show-syntactic-information}). This information directs how -the line is indented. - -@item M-x cwarn-mode -@itemx M-x global-cwarn-mode -@findex cwarn-mode -@findex global-cwarn-mode -@vindex global-cwarn-mode -@cindex CWarn mode -@cindex suspicious constructions in C, C++ -CWarn minor mode highlights certain suspicious C and C++ constructions: - -@itemize @bullet{} -@item -Assignments inside expressions. -@item -Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} -(except after a @samp{do @dots{} while} statement); -@item -C++ functions with reference parameters. -@end itemize - -@noindent -You can enable the mode for one buffer with the command @kbd{M-x -cwarn-mode}, or for all suitable buffers with the command @kbd{M-x -global-cwarn-mode} or by customizing the variable -@code{global-cwarn-mode}. You must also enable Font Lock mode to make -it work. - -@item M-x hide-ifdef-mode -@findex hide-ifdef-mode -@cindex Hide-ifdef mode -@vindex hide-ifdef-shadow -Hide-ifdef minor mode hides selected code within @samp{#if} and -@samp{#ifdef} preprocessor blocks. If you change the variable -@code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode -``shadows'' preprocessor blocks by displaying them with a less -prominent face, instead of hiding them entirely. See the -documentation string of @code{hide-ifdef-mode} for more information. - -@item M-x ff-find-related-file -@cindex related files -@findex ff-find-related-file -@vindex ff-related-file-alist -Find a file ``related'' in a special way to the file visited by the -current buffer. Typically this will be the header file corresponding -to a C/C++ source file, or vice versa. The variable -@code{ff-related-file-alist} specifies how to compute related file -names. -@end table - -@node Asm Mode -@section Asm Mode - -@cindex Asm mode -@cindex assembler mode -Asm mode is a major mode for editing files of assembler code. It -defines these commands: - -@table @kbd -@item @key{TAB} -@code{tab-to-tab-stop}. -@c FIXME: Maybe this should be consistent with other programming modes. -@item C-j -Insert a newline and then indent using @code{tab-to-tab-stop}. -@item : -Insert a colon and then remove the indentation from before the label -preceding colon. Then do @code{tab-to-tab-stop}. -@item ; -Insert or align a comment. -@end table - - The variable @code{asm-comment-char} specifies which character -starts comments in assembler syntax. - -@ifnottex -@include fortran-xtra.texi -@end ifnottex diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi deleted file mode 100644 index a0ff7079388..00000000000 --- a/doc/emacs/regs.texi +++ /dev/null @@ -1,385 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Registers -@chapter Registers -@cindex registers - - Emacs @dfn{registers} are compartments where you can save text, -rectangles, positions, and other things for later use. Once you save -text or a rectangle in a register, you can copy it into the buffer -once, or many times; once you save a position in a register, you can -jump back to that position once, or many times. - - Each register has a name that consists of a single character, which -we will denote by @var{r}; @var{r} can be a letter (such as @samp{a}) -or a number (such as @samp{1}); case matters, so register @samp{a} is -not the same as register @samp{A}. - -@findex view-register - A register can store a position, a piece of text, a rectangle, a -number, a window configuration, or a file name, but only one thing at -any given time. Whatever you store in a register remains there until -you store something else in that register. To see what register -@var{r} contains, use @kbd{M-x view-register}: - -@table @kbd -@item M-x view-register @key{RET} @var{r} -Display a description of what register @var{r} contains. -@end table - -@vindex register-preview-delay -@cindex preview of registers - All of the commands that prompt for a register will display a -``preview'' window that lists the existing registers (if there are -any) after a short delay. To change the length of the delay, -customize @code{register-preview-delay}. To prevent this display, set -that option to @code{nil}. You can explicitly request a preview -window by pressing @kbd{C-h} or @key{F1}. - - @dfn{Bookmarks} record files and positions in them, so you can -return to those positions when you look at the file again. Bookmarks -are similar in spirit to registers, so they are also documented in -this chapter. - -@menu -* Position Registers:: Saving positions in registers. -* Text Registers:: Saving text in registers. -* Rectangle Registers:: Saving rectangles in registers. -* Configuration Registers:: Saving window configurations in registers. -* Number Registers:: Numbers in registers. -* File Registers:: File names in registers. -* Keyboard Macro Registers:: Keyboard macros in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. -@end menu - -@node Position Registers -@section Saving Positions in Registers -@cindex saving position in a register - -@table @kbd -@item C-x r @key{SPC} @var{r} -Record the position of point and the current buffer in register -@var{r} (@code{point-to-register}). -@item C-x r j @var{r} -Jump to the position and buffer saved in register @var{r} -(@code{jump-to-register}). -@end table - -@kindex C-x r SPC -@findex point-to-register - Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by -a character @kbd{@var{r}}, saves both the position of point and the -current buffer in register @var{r}. The register retains this -information until you store something else in it. - -@kindex C-x r j -@findex jump-to-register - The command @kbd{C-x r j @var{r}} switches to the buffer recorded in -register @var{r}, and moves point to the recorded position. The -contents of the register are not changed, so you can jump to the saved -position any number of times. - - If you use @kbd{C-x r j} to go to a saved position, but the buffer it -was saved from has been killed, @kbd{C-x r j} tries to create the buffer -again by visiting the same file. Of course, this works only for buffers -that were visiting files. - -@node Text Registers -@section Saving Text in Registers -@cindex saving text in a register - - When you want to insert a copy of the same piece of text several -times, it may be inconvenient to yank it from the kill ring, since each -subsequent kill moves that entry further down the ring. An alternative -is to store the text in a register and later retrieve it. - -@table @kbd -@item C-x r s @var{r} -Copy region into register @var{r} (@code{copy-to-register}). -@item C-x r i @var{r} -Insert text from register @var{r} (@code{insert-register}). -@item M-x append-to-register @key{RET} @var{r} -Append region to text in register @var{r}. - -@kindex C-x r + -When register @var{r} contains text, you can use @kbd{C-x r +} -(@code{increment-register}) to append to that register. Note that -command @kbd{C-x r +} behaves differently if @var{r} contains a -number. @xref{Number Registers}. - -@item M-x prepend-to-register @key{RET} @var{r} -Prepend region to text in register @var{r}. -@end table - -@kindex C-x r s -@findex copy-to-register - @kbd{C-x r s @var{r}} stores a copy of the text of the region into -the register named @var{r}. If the mark is inactive, Emacs first -reactivates the mark where it was last set. The mark is deactivated -at the end of this command. @xref{Mark}. @kbd{C-u C-x r s @var{r}}, -the same command with a prefix argument, copies the text into register -@var{r} and deletes the text from the buffer as well; you can think of -this as ``moving'' the region text into the register. - -@findex append-to-register -@findex prepend-to-register - @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of -the text in the region to the text already stored in the register -named @var{r}. If invoked with a prefix argument, it deletes the -region after appending it to the register. The command -@code{prepend-to-register} is similar, except that it @emph{prepends} -the region text to the text in the register instead of -@emph{appending} it. - -@vindex register-separator - When you are collecting text using @code{append-to-register} and -@code{prepend-to-register}, you may want to separate individual -collected pieces using a separator. In that case, configure a -@code{register-separator} and store the separator text in to that -register. For example, to get double newlines as text separator -during the collection process, you can use the following setting. - -@example -(setq register-separator ?+) -(set-register register-separator "\n\n") -@end example - -@kindex C-x r i -@findex insert-register - @kbd{C-x r i @var{r}} inserts in the buffer the text from register -@var{r}. Normally it leaves point before the text and sets the mark -after, without activating it. With a numeric argument, it instead -puts point after the text and the mark before. - -@node Rectangle Registers -@section Saving Rectangles in Registers -@cindex saving rectangle in a register - - A register can contain a rectangle instead of linear text. -@xref{Rectangles}, for basic information on how to specify a rectangle -in the buffer. - -@table @kbd -@findex copy-rectangle-to-register -@kindex C-x r r -@item C-x r r @var{r} -Copy the region-rectangle into register @var{r} -(@code{copy-rectangle-to-register}). With numeric argument, delete it as -well. -@item C-x r i @var{r} -Insert the rectangle stored in register @var{r} (if it contains a -rectangle) (@code{insert-register}). -@end table - - The @kbd{C-x r i @var{r}} (@code{insert-register}) command, -previously documented in @ref{Text Registers}, inserts a rectangle -rather than a text string, if the register contains a rectangle. - -@node Configuration Registers -@section Saving Window Configurations in Registers -@cindex saving window configuration in a register - -@findex window-configuration-to-register -@findex frameset-to-register -@kindex C-x r w -@kindex C-x r f - You can save the window configuration of the selected frame in a -register, or even the configuration of all windows in all frames, and -restore the configuration later. @xref{Windows}, for information -about window configurations. - -@table @kbd -@item C-x r w @var{r} -Save the state of the selected frame's windows in register @var{r} -(@code{window-configuration-to-register}). -@item C-x r f @var{r} -Save the state of all frames, including all their windows, in register -@var{r} (@code{frameset-to-register}). -@end table - - Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. -This is the same command used to restore a cursor position. When you -restore a frame configuration, any existing frames not included in the -configuration become invisible. If you wish to delete these frames -instead, use @kbd{C-u C-x r j @var{r}}. - -@node Number Registers -@section Keeping Numbers in Registers -@cindex saving number in a register - - There are commands to store a number in a register, to insert -the number in the buffer in decimal, and to increment it. These commands -can be useful in keyboard macros (@pxref{Keyboard Macros}). - -@table @kbd -@item C-u @var{number} C-x r n @var{r} -@kindex C-x r n -@findex number-to-register -Store @var{number} into register @var{r} (@code{number-to-register}). -@item C-u @var{number} C-x r + @var{r} -@kindex C-x r + -@findex increment-register -If @var{r} contains a number, increment the number in that register by -@var{number}. Note that command @kbd{C-x r +} -(@code{increment-register}) behaves differently if @var{r} contains -text. @xref{Text Registers}. -@item C-x r i @var{r} -Insert the number from register @var{r} into the buffer. -@end table - - @kbd{C-x r i} is the same command used to insert any other sort of -register contents into the buffer. @kbd{C-x r +} with no numeric -argument increments the register value by 1; @kbd{C-x r n} with no -numeric argument stores zero in the register. - -@node File Registers -@section Keeping File Names in Registers -@cindex saving file name in a register - - If you visit certain file names frequently, you can visit them more -conveniently if you put their names in registers. Here's the Lisp code -used to put a file @var{name} into register @var{r}: - -@smallexample -(set-register @var{r} '(file . @var{name})) -@end smallexample - -@need 3000 -@noindent -For example, - -@smallexample -(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog")) -@end smallexample - -@noindent -puts the file name shown in register @samp{z}. - - To visit the file whose name is in register @var{r}, type @kbd{C-x r j -@var{r}}. (This is the same command used to jump to a position or -restore a frame configuration.) - -@node Keyboard Macro Registers -@section Keyboard Macro Registers -@cindex saving keyboard macro in a register -@cindex keyboard macros, in registers - -@kindex C-x C-k x -@findex kmacro-to-register - If you need to execute a keyboard macro (@pxref{Keyboard Macros}) -frequently, it is more convenient to put it in a register or save it -(@pxref{Save Keyboard Macro}). @kbd{C-x C-k x @var{r}} -(@code{kmacro-to-register}) stores the last keyboard macro in register -@var{r}. - - To execute the keyboard macro in register @var{r}, type @kbd{C-x r j -@var{r}}. (This is the same command used to jump to a position or -restore a frameset.) - -@node Bookmarks -@section Bookmarks -@cindex bookmarks - - @dfn{Bookmarks} are somewhat like registers in that they record -positions you can jump to. Unlike registers, they have long names, and -they persist automatically from one Emacs session to the next. The -prototypical use of bookmarks is to record ``where you were reading'' in -various files. - -@table @kbd -@item C-x r m @key{RET} -Set the bookmark for the visited file, at point. - -@item C-x r m @var{bookmark} @key{RET} -@findex bookmark-set -Set the bookmark named @var{bookmark} at point (@code{bookmark-set}). - -@item C-x r b @var{bookmark} @key{RET} -@findex bookmark-jump -Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}). - -@item C-x r l -@findex list-bookmarks -List all bookmarks (@code{list-bookmarks}). - -@item M-x bookmark-save -@findex bookmark-save -Save all the current bookmark values in the default bookmark file. -@end table - -@kindex C-x r m -@findex bookmark-set -@kindex C-x r b -@findex bookmark-jump - The prototypical use for bookmarks is to record one current position -in each of several files. So the command @kbd{C-x r m}, which sets a -bookmark, uses the visited file name as the default for the bookmark -name. If you name each bookmark after the file it points to, then you -can conveniently revisit any of those files with @kbd{C-x r b}, and move -to the position of the bookmark at the same time. - -@kindex C-x r l - To display a list of all your bookmarks in a separate buffer, type -@kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer, -you can use it to edit your bookmark definitions or annotate the -bookmarks. Type @kbd{C-h m} in the bookmark buffer for more -information about its special editing commands. - - When you kill Emacs, Emacs saves your bookmarks, if -you have changed any bookmark values. You can also save the bookmarks -at any time with the @kbd{M-x bookmark-save} command. Bookmarks are -saved to the file @file{~/.emacs.d/bookmarks} (for compatibility with -older versions of Emacs, if you have a file named @file{~/.emacs.bmk}, -that is used instead). The bookmark commands load your default -bookmark file automatically. This saving and loading is how bookmarks -persist from one Emacs session to the next. - -@vindex bookmark-save-flag - If you set the variable @code{bookmark-save-flag} to 1, each command -that sets a bookmark will also save your bookmarks; this way, you -don't lose any bookmark values even if Emacs crashes. The value, if -a number, says how many bookmark modifications should go by between -saving. If you set this variable to @code{nil}, Emacs only -saves bookmarks if you explicitly use @kbd{M-x bookmark-save}. - -@vindex bookmark-default-file - The variable @code{bookmark-default-file} specifies the file in -which to save bookmarks by default. - -@vindex bookmark-search-size - Bookmark position values are saved with surrounding context, so that -@code{bookmark-jump} can find the proper position even if the file is -modified slightly. The variable @code{bookmark-search-size} says how -many characters of context to record on each side of the bookmark's -position. - - Here are some additional commands for working with bookmarks: - -@table @kbd -@item M-x bookmark-load @key{RET} @var{filename} @key{RET} -@findex bookmark-load -Load a file named @var{filename} that contains a list of bookmark -values. You can use this command, as well as @code{bookmark-write}, to -work with other files of bookmark values in addition to your default -bookmark file. - -@item M-x bookmark-write @key{RET} @var{filename} @key{RET} -@findex bookmark-write -Save all the current bookmark values in the file @var{filename}. - -@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET} -@findex bookmark-delete -Delete the bookmark named @var{bookmark}. - -@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET} -@findex bookmark-insert-location -Insert in the buffer the name of the file that bookmark @var{bookmark} -points to. - -@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET} -@findex bookmark-insert -Insert in the buffer the @emph{contents} of the file that bookmark -@var{bookmark} points to. -@end table diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi deleted file mode 100644 index 6fab25a187d..00000000000 --- a/doc/emacs/rmail.texi +++ /dev/null @@ -1,1578 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Rmail -@chapter Reading Mail with Rmail -@cindex Rmail -@cindex reading mail -@findex rmail -@findex rmail-mode -@vindex rmail-mode-hook - - Rmail is an Emacs subsystem for reading and disposing of mail that -you receive. Rmail stores mail messages in files called Rmail files. -Reading the messages in an Rmail file is done in a special major mode, -Rmail mode, which redefines most letters to run commands for managing mail. -@menu -* Basic: Rmail Basics. Basic concepts of Rmail, and simple use. -* Scroll: Rmail Scrolling. Scrolling through a message. -* Motion: Rmail Motion. Moving to another message. -* Deletion: Rmail Deletion. Deleting and expunging messages. -* Inbox: Rmail Inbox. How mail gets into the Rmail file. -* Files: Rmail Files. Using multiple Rmail files. -* Output: Rmail Output. Copying messages out to files. -* Labels: Rmail Labels. Classifying messages by labeling them. -* Attrs: Rmail Attributes. Certain standard labels, called attributes. -* Reply: Rmail Reply. Sending replies to messages you are viewing. -* Summary: Rmail Summary. Summaries show brief info on many messages. -* Sort: Rmail Sorting. Sorting messages in Rmail. -* Display: Rmail Display. How Rmail displays a message; customization. -* Coding: Rmail Coding. How Rmail handles decoding character sets. -* Editing: Rmail Editing. Editing message text and headers in Rmail. -* Digest: Rmail Digest. Extracting the messages from a digest message. -* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code. -* Movemail:: More details of fetching new mail. -* Remote Mailboxes:: Retrieving mail from remote mailboxes. -* Other Mailbox Formats:: Retrieving mail from local mailboxes in - various formats. -@end menu - -@node Rmail Basics -@section Basic Concepts of Rmail - -@cindex primary Rmail file -@vindex rmail-file-name - Using Rmail in the simplest fashion, you have one Rmail file -@file{~/RMAIL} in which all of your mail is saved. It is called your -@dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary -Rmail file, merges new mail in from your inboxes, displays the first -message you haven't read yet, and lets you begin reading. The variable -@code{rmail-file-name} specifies the name of the primary Rmail file. - - Rmail displays only one message in the Rmail file at a time. -The message that is shown is called the @dfn{current message}. Rmail -mode's special commands can do such things as delete the current -message, copy it into another file, send a reply, or move to another -message. You can also create multiple Rmail files and use Rmail to move -messages between them. - -@cindex message number - Within the Rmail file, messages are normally arranged sequentially in -order of receipt; you can specify other ways to sort them (@pxref{Rmail -Sorting}). Messages are identified by consecutive integers which are -their @dfn{message numbers}. The number of the current message is -displayed in Rmail's mode line, followed by the total number of messages -in the file. You can move to a message by specifying its message number -with the @kbd{j} key (@pxref{Rmail Motion}). - -@kindex s @r{(Rmail)} -@findex rmail-expunge-and-save - Following the usual conventions of Emacs, changes in an Rmail file -become permanent only when you save the file. You can save it with -@kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted -messages from the file first (@pxref{Rmail Deletion}). To save the -file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail -file after merging new mail from an inbox file (@pxref{Rmail Inbox}). - -@kindex q @r{(Rmail)} -@findex rmail-quit -@kindex b @r{(Rmail)} -@findex rmail-bury - You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges -and saves the Rmail file, then buries the Rmail buffer as well as its -summary buffer, if present (@pxref{Rmail Summary}). But there is no -need to ``exit'' formally. If you switch from Rmail to editing in -other buffers, and never switch back, you have exited. Just make sure -to save the Rmail file eventually (like any other file you have -changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save -Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the -Rmail buffer and its summary without expunging and saving the Rmail file. - -@node Rmail Scrolling -@section Scrolling Within a Message - - When Rmail displays a message that does not fit on the screen, you -must scroll through it to read the rest. You could do this with -@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so -frequent that it deserves to be easier. - -@table @kbd -@item @key{SPC} -Scroll forward (@code{scroll-up-command}). -@item @key{DEL} -@itemx S-@key{SPC} -Scroll backward (@code{scroll-down-command}). -@item . -Scroll to start of message (@code{rmail-beginning-of-message}). -@item / -Scroll to end of message (@code{rmail-end-of-message}). -@end table - -@kindex SPC @r{(Rmail)} -@kindex DEL @r{(Rmail)} -@kindex S-SPC @r{(Rmail)} - Since the most common thing to do while reading a message is to -scroll through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} -(or @kbd{S-@key{SPC}}) do the same as @kbd{C-v} (@code{scroll-up-command}) -and @kbd{M-v} (@code{scroll-down-command}) respectively. - -@kindex . @r{(Rmail)} -@kindex / @r{(Rmail)} -@findex rmail-beginning-of-message -@findex rmail-end-of-message - The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the -beginning of the selected message. This is not quite the same as @kbd{M-<}: -for one thing, it does not set the mark; for another, it resets the buffer -boundaries of the current message if you have changed them. Similarly, -the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end -of the selected message. -@c The comment about buffer boundaries is still true in mbox Rmail, if -@c less likely to be relevant. - -@node Rmail Motion -@section Moving Among Messages - - The most basic thing to do with a message is to read it. The way to -do this in Rmail is to make the message current. The usual practice is -to move sequentially through the file, since this is the order of -receipt of messages. When you enter Rmail, you are positioned at the -first message that you have not yet made current (that is, the first one -that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move -forward to see the other new messages; move backward to re-examine old -messages. - -@table @kbd -@item n -Move to the next nondeleted message, skipping any intervening deleted -messages (@code{rmail-next-undeleted-message}). -@item p -Move to the previous nondeleted message -(@code{rmail-previous-undeleted-message}). -@item M-n -Move to the next message, including deleted messages -(@code{rmail-next-message}). -@item M-p -Move to the previous message, including deleted messages -(@code{rmail-previous-message}). -@item C-c C-n -Move to the next message with the same subject as the current one -(@code{rmail-next-same-subject}). -@item C-c C-p -Move to the previous message with the same subject as the current one -(@code{rmail-previous-same-subject}). -@item j -Move to the first message. With argument @var{n}, move to -message number @var{n} (@code{rmail-show-message}). -@item > -Move to the last message (@code{rmail-last-message}). -@item < -Move to the first message (@code{rmail-first-message}). - -@item M-s @var{regexp} @key{RET} -Move to the next message containing a match for @var{regexp} -(@code{rmail-search}). - -@item - M-s @var{regexp} @key{RET} -Move to the previous message containing a match for @var{regexp}. -@end table - -@kindex n @r{(Rmail)} -@kindex p @r{(Rmail)} -@kindex M-n @r{(Rmail)} -@kindex M-p @r{(Rmail)} -@findex rmail-next-undeleted-message -@findex rmail-previous-undeleted-message -@findex rmail-next-message -@findex rmail-previous-message - @kbd{n} and @kbd{p} are the usual way of moving among messages in -Rmail. They move through the messages sequentially, but skip over -deleted messages, which is usually what you want to do. Their command -definitions are named @code{rmail-next-undeleted-message} and -@code{rmail-previous-undeleted-message}. If you do not want to skip -deleted messages---for example, if you want to move to a message to -undelete it---use the variants @kbd{M-n} and @kbd{M-p} -(@code{rmail-next-message} and @code{rmail-previous-message}). A -numeric argument to any of these commands serves as a repeat -count. - - In Rmail, you can specify a numeric argument by typing just the -digits. You don't need to type @kbd{C-u} first. - -@kindex M-s @r{(Rmail)} -@findex rmail-search -@cindex searching in Rmail - The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of -search. The usual incremental search command @kbd{C-s} works in Rmail, -but it searches only within the current message. The purpose of -@kbd{M-s} is to search for another message. It reads a regular -expression (@pxref{Regexps}) nonincrementally, then searches starting at -the beginning of the following message for a match. It then selects -that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp -used the previous time. - - To search backward in the file for another message, give @kbd{M-s} a -negative argument. In Rmail you can do this with @kbd{- M-s}. This -begins searching from the end of the previous message. - - It is also possible to search for a message based on labels. -@xref{Rmail Labels}. - -@kindex C-c C-n @r{(Rmail)} -@kindex C-c C-p @r{(Rmail)} -@findex rmail-next-same-subject -@findex rmail-previous-same-subject - The @kbd{C-c C-n} (@code{rmail-next-same-subject}) command moves to -the next message with the same subject as the current one. A prefix -argument serves as a repeat count. With a negative argument, this -command moves backward, acting like @kbd{C-c C-p} -(@code{rmail-previous-same-subject}). When comparing subjects, these -commands ignore the prefixes typically added to the subjects of replies. - -@kindex j @r{(Rmail)} -@kindex > @r{(Rmail)} -@kindex < @r{(Rmail)} -@findex rmail-show-message -@findex rmail-last-message -@findex rmail-first-message - To move to a message specified by absolute message number, use @kbd{j} -(@code{rmail-show-message}) with the message number as argument. With -no argument, @kbd{j} selects the first message. @kbd{<} -(@code{rmail-first-message}) also selects the first message. @kbd{>} -(@code{rmail-last-message}) selects the last message. - -@node Rmail Deletion -@section Deleting Messages - -@cindex deletion (Rmail) - When you no longer need to keep a message, you can @dfn{delete} it. This -flags it as ignorable, and some Rmail commands pretend it is no longer -present; but it still has its place in the Rmail file, and still has its -message number. - -@cindex expunging (Rmail) - @dfn{Expunging} the Rmail file actually removes the deleted messages. -The remaining messages are renumbered consecutively. -@c The following is neither true (there is also unforward, sorting, -@c etc), nor especially interesting. -@c Expunging is the only action that changes the message number of any -@c message, except for undigestifying (@pxref{Rmail Digest}). - -@table @kbd -@item d -Delete the current message, and move to the next nondeleted message -(@code{rmail-delete-forward}). -@item C-d -Delete the current message, and move to the previous nondeleted -message (@code{rmail-delete-backward}). -@item u -Undelete the current message, or move back to the previous deleted -message and undelete it (@code{rmail-undelete-previous-message}). -@item x -Expunge the Rmail file (@code{rmail-expunge}). -@end table - -@kindex d @r{(Rmail)} -@kindex C-d @r{(Rmail)} -@findex rmail-delete-forward -@findex rmail-delete-backward - There are two Rmail commands for deleting messages. Both delete the -current message and select another. @kbd{d} -(@code{rmail-delete-forward}) moves to the following message, skipping -messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward}) -moves to the previous nondeleted message. If there is no nondeleted -message to move to in the specified direction, the message that was just -deleted remains current. @kbd{d} with a prefix argument is equivalent -to @kbd{C-d}. Note that the Rmail summary versions of these commands -behave slightly differently (@pxref{Rmail Summary Edit}). - -@c mention other hooks, e.g., show message hook? -@vindex rmail-delete-message-hook - Whenever Rmail deletes a message, it runs the hook -@code{rmail-delete-message-hook}. When the hook functions are invoked, -the message has been marked deleted, but it is still the current message -in the Rmail buffer. - -@cindex undeletion (Rmail) -@kindex x @r{(Rmail)} -@findex rmail-expunge -@kindex u @r{(Rmail)} -@findex rmail-undelete-previous-message - To make all the deleted messages finally vanish from the Rmail file, -type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still -@dfn{undelete} the deleted messages. The undeletion command, @kbd{u} -(@code{rmail-undelete-previous-message}), is designed to cancel the -effect of a @kbd{d} command in most cases. It undeletes the current -message if the current message is deleted. Otherwise it moves backward -to previous messages until a deleted message is found, and undeletes -that message. - - You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} -moves back to and undeletes the message that the @kbd{d} deleted. But -this does not work when the @kbd{d} skips a few already-deleted messages -that follow the message being deleted; then the @kbd{u} command -undeletes the last of the messages that were skipped. There is no clean -way to avoid this problem. However, by repeating the @kbd{u} command, -you can eventually get back to the message that you intend to -undelete. You can also select a particular deleted message with -the @kbd{M-p} command, then type @kbd{u} to undelete it. - - A deleted message has the @samp{deleted} attribute, and as a result -@samp{deleted} appears in the mode line when the current message is -deleted. In fact, deleting or undeleting a message is nothing more than -adding or removing this attribute. @xref{Rmail Attributes}. - -@node Rmail Inbox -@section Rmail Files and Inboxes -@cindex inbox file - - When you receive mail locally, the operating system places incoming -mail for you in a file that we call your @dfn{inbox}. When you start -up Rmail, it runs a C program called @code{movemail} to copy the new -messages from your local inbox into your primary Rmail file, which -also contains other messages saved from previous Rmail sessions. It -is in this file that you actually read the mail with Rmail. This -operation is called @dfn{getting new mail}. You can get new mail at -any time in Rmail by typing @kbd{g}. - -@vindex rmail-primary-inbox-list -@cindex @env{MAIL} environment variable - The variable @code{rmail-primary-inbox-list} contains a list of the -files that are inboxes for your primary Rmail file. If you don't set -this variable explicitly, Rmail uses the @env{MAIL} environment -variable, or, as a last resort, a default inbox based on -@code{rmail-spool-directory}. The default inbox file depends on your -operating system; often it is @file{/var/mail/@var{username}}, -@file{/var/spool/mail/@var{username}}, or -@file{/usr/spool/mail/@var{username}}. - - You can specify the inbox file(s) for any Rmail file for the current -session with the command @code{set-rmail-inbox-list}; see @ref{Rmail -Files}. - - There are two reasons for having separate Rmail files and inboxes. - -@enumerate -@item -The inbox file format varies between operating systems and according to -the other mail software in use. Only one part of Rmail needs to know -about the alternatives, and it need only understand how to convert all -of them to Rmail's own format. - -@item -It is very cumbersome to access an inbox file without danger of losing -mail, because it is necessary to interlock with mail delivery. -Moreover, different operating systems use different interlocking -techniques. The strategy of moving mail out of the inbox once and for -all into a separate Rmail file avoids the need for interlocking in all -the rest of Rmail, since only Rmail operates on the Rmail file. -@end enumerate - -@c FIXME remove this in Emacs 25; won't be relevant any more. -@cindex Babyl files -@cindex mbox files - Rmail was originally written to use the Babyl format as its internal -format. Since then, we have recognized that the usual inbox format -(@samp{mbox}) on Unix and GNU systems is adequate for the job, and so -since Emacs 23 Rmail uses that as its internal format. The Rmail file -is still separate from the inbox file, even though their format is the -same. -@c But this bit should stay in some form. -@vindex rmail-mbox-format -(In fact, there are a few slightly different mbox formats. -The differences are not very important, but you can set the variable -@code{rmail-mbox-format} to tell Rmail which form your system uses. -See that variable's documentation for more details.) - -@vindex rmail-preserve-inbox - When getting new mail, Rmail first copies the new mail from the -inbox file to the Rmail file; then it saves the Rmail file; then it -clears out the inbox file. This way, a system crash may cause -duplication of mail between the inbox and the Rmail file, but cannot -lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then -Rmail does not clear out the inbox file when it gets new mail. You -may wish to set this, for example, on a portable computer you use to -check your mail via POP while traveling, so that your mail will remain -on the server and you can save it later on your workstation. - - In some cases, Rmail copies the new mail from the inbox file -indirectly. First it runs the @code{movemail} program to move the mail -from the inbox to an intermediate file called -@file{.newmail-@var{inboxname}}, in the same directory as the Rmail -file. Then Rmail merges the new mail from that file, saves the Rmail -file, and only then deletes the intermediate file. If there is a crash -at the wrong time, this file continues to exist, and Rmail will use it -again the next time it gets new mail from that inbox. - - If Rmail is unable to convert the data in -@file{.newmail-@var{inboxname}} into mbox format, it renames the file to -@file{RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the name -unique) so that Rmail will not have trouble with the data again. You -should look at the file, find whatever message confuses Rmail (probably -one that includes the control-underscore character, octal code 037), and -delete it. Then you can use @kbd{1 g} to get new mail from the -corrected file. - -@node Rmail Files -@section Multiple Rmail Files - - Rmail operates by default on your @dfn{primary Rmail file}, which is named -@file{~/RMAIL} and receives your incoming mail from your system inbox file. -But you can also have other Rmail files and edit them with Rmail. These -files can receive mail through their own inboxes, or you can move messages -into them with explicit Rmail commands (@pxref{Rmail Output}). - -@table @kbd -@item i @var{file} @key{RET} -Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}). - -@item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET} -Specify inbox file names for current Rmail file to get mail from. - -@item g -Merge new mail from current Rmail file's inboxes -(@code{rmail-get-new-mail}). - -@item C-u g @var{file} @key{RET} -Merge new mail from inbox file @var{file}. -@end table - -@kindex i @r{(Rmail)} -@findex rmail-input - To run Rmail on a file other than your primary Rmail file, you can use -the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file -in Rmail mode. You can use @kbd{M-x rmail-input} even when not in -Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the -same thing. - - The file you read with @kbd{i} should normally be a valid mbox file. -If it is not, Rmail tries to convert its text to mbox format, and -visits the converted text in the buffer. If you save the buffer, that -converts the file. - - If you specify a file name that doesn't exist, @kbd{i} initializes a -new buffer for creating a new Rmail file. - -@vindex rmail-secondary-file-directory -@vindex rmail-secondary-file-regexp - You can also select an Rmail file from a menu. In the Classify menu, -choose the Input Rmail File item; then choose the Rmail file you want. -The variables @code{rmail-secondary-file-directory} and -@code{rmail-secondary-file-regexp} specify which files to offer in the -menu: the first variable says which directory to find them in; the -second says which files in that directory to offer (all those that match -the regular expression). If no files match, you cannot select this menu -item. These variables also apply to choosing a file for output -(@pxref{Rmail Output}). -@c FIXME matches only checked when Rmail file first visited? - -@ignore -@findex set-rmail-inbox-list - Each Rmail file can contain a list of inbox file names; you can specify -this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files} -@key{RET}}. The argument can contain any number of file names, separated -by commas. It can also be empty, which specifies that this file should -have no inboxes. Once you specify a list of inboxes in an Rmail file, -the Rmail file remembers it permanently until you specify a different list. -@end ignore - -@vindex rmail-inbox-list - The inbox files to use are specified by the variable -@code{rmail-inbox-list}, which is buffer-local in Rmail mode. As a -special exception, if you have specified no inbox files for your primary -Rmail file, it uses the @env{MAIL} environment variable, or your -standard system inbox. - -@kindex g @r{(Rmail)} -@findex rmail-get-new-mail - The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the -current Rmail file from its inboxes. If the Rmail file has no -inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also -merges new mail into your primary Rmail file. - - To merge mail from a file that is not the usual inbox, give the -@kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file -name and merges mail from that file. The inbox file is not deleted or -changed in any way when @kbd{g} with an argument is used. This is, -therefore, a general way of merging one file of messages into another. - -@node Rmail Output -@section Copying Messages Out to Files - - These commands copy messages from an Rmail file into another file. - -@table @kbd -@item o @var{file} @key{RET} -Append a full copy of the current message to the file @var{file} -(@code{rmail-output}). - -@item C-o @var{file} @key{RET} -Append a copy of the current message, as displayed, to the file -@var{file} (@code{rmail-output-as-seen}). - -@item w @var{file} @key{RET} -Output just the message body to the file @var{file}, taking the default -file name from the message @samp{Subject} header. -@end table - -@kindex o @r{(Rmail)} -@findex rmail-output-as-seen -@kindex C-o @r{(Rmail)} -@findex rmail-output - The commands @kbd{o} and @kbd{C-o} copy the current message into a -specified file, adding it at the end. The two commands differ mainly -in how much to copy: @kbd{o} copies the full message headers, even if -they are not all visible, while @kbd{C-o} copies exactly the headers -currently displayed and no more. @xref{Rmail Display}. In addition, -@kbd{o} converts the message to Babyl format (used by Rmail in Emacs -version 22 and before) if the file is in Babyl format; @kbd{C-o} -cannot output to Babyl files at all. -@c FIXME remove BABYL mention in Emacs 25? - - If the output file is currently visited in an Emacs buffer, the -output commands append the message to that buffer. It is up to you to -save the buffer eventually in its file. - -@kindex w @r{(Rmail)} -@findex rmail-output-body-to-file - Sometimes you may receive a message whose body holds the contents of a -file. You can save the body to a file (excluding the message header) -with the @kbd{w} command (@code{rmail-output-body-to-file}). Often -these messages contain the intended file name in the @samp{Subject} -field, so the @kbd{w} command uses the @samp{Subject} field as the -default for the output file name. However, the file name is read using -the minibuffer, so you can specify a different name if you wish. - - You can also output a message to an Rmail file chosen with a menu. -In the Classify menu, choose the Output Rmail File menu item; then -choose the Rmail file you want. This outputs the current message to -that file, like the @kbd{o} command. The variables -@code{rmail-secondary-file-directory} and -@code{rmail-secondary-file-regexp} specify which files to offer in the -menu: the first variable says which directory to find them in; the -second says which files in that directory to offer (all those that -match the regular expression). If no files match, you cannot select -this menu item. - -@vindex rmail-delete-after-output - Copying a message with @kbd{o} or @kbd{C-o} gives the original copy -of the message the @samp{filed} attribute, so that @samp{filed} -appears in the mode line when such a message is current. - - If you like to keep just a single copy of every mail message, set -the variable @code{rmail-delete-after-output} to @code{t}; then the -@kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message -after copying it. (You can undelete it afterward if you wish.) - -@vindex rmail-output-file-alist - The variable @code{rmail-output-file-alist} lets you specify -intelligent defaults for the output file, based on the contents of the -current message. The value should be a list whose elements have this -form: - -@example -(@var{regexp} . @var{name-exp}) -@end example - -@noindent -If there's a match for @var{regexp} in the current message, then the -default file name for output is @var{name-exp}. If multiple elements -match the message, the first matching element decides the default file -name. The subexpression @var{name-exp} may be a string constant giving -the file name to use, or more generally it may be any Lisp expression -that returns a file name as a string. @code{rmail-output-file-alist} -applies to both @kbd{o} and @kbd{C-o}. - -@vindex rmail-automatic-folder-directives -Rmail can automatically save messages from your primary Rmail file -(the one that @code{rmail-file-name} specifies) to other files, based -on the value of the variable @code{rmail-automatic-folder-directives}. -This variable is a list of elements (@samp{directives}) that say which -messages to save where. Each directive is a list consisting of an -output file, followed by one or more pairs of a header name and a regular -expression. If a message has a header matching the specified regular -expression, that message is saved to the given file. If the directive -has more than one header entry, all must match. Rmail checks directives -when it shows a message from the file @code{rmail-file-name}, and -applies the first that matches (if any). If the output file is -@code{nil}, the message is deleted, not saved. For example, you can use -this feature to save messages from a particular address, or with a -particular subject, to a dedicated file. - -@node Rmail Labels -@section Labels -@cindex label (Rmail) -@cindex attribute (Rmail) - - Each message can have various @dfn{labels} assigned to it as a means -of classification. Each label has a name; different names are different -labels. Any given label is either present or absent on a particular -message. A few label names have standard meanings and are given to -messages automatically by Rmail when appropriate; these special labels -are called @dfn{attributes}. -@ifnottex -(@xref{Rmail Attributes}.) -@end ifnottex -All other labels are assigned only by users. - -@table @kbd -@item a @var{label} @key{RET} -Assign the label @var{label} to the current message (@code{rmail-add-label}). -@item k @var{label} @key{RET} -Remove the label @var{label} from the current message (@code{rmail-kill-label}). -@item C-M-n @var{labels} @key{RET} -Move to the next message that has one of the labels @var{labels} -(@code{rmail-next-labeled-message}). -@item C-M-p @var{labels} @key{RET} -Move to the previous message that has one of the labels @var{labels} -(@code{rmail-previous-labeled-message}). -@item l @var{labels} @key{RET} -@itemx C-M-l @var{labels} @key{RET} -Make a summary of all messages containing any of the labels @var{labels} -(@code{rmail-summary-by-labels}). -@end table - -@kindex a @r{(Rmail)} -@kindex k @r{(Rmail)} -@findex rmail-add-label -@findex rmail-kill-label - The @kbd{a} (@code{rmail-add-label}) and @kbd{k} -(@code{rmail-kill-label}) commands allow you to assign or remove any -label on the current message. If the @var{label} argument is empty, it -means to assign or remove the same label most recently assigned or -removed. - - Once you have given messages labels to classify them as you wish, there -are three ways to use the labels: in moving, in summaries, and in sorting. - -@kindex C-M-n @r{(Rmail)} -@kindex C-M-p @r{(Rmail)} -@findex rmail-next-labeled-message -@findex rmail-previous-labeled-message - @kbd{C-M-n @var{labels} @key{RET}} -(@code{rmail-next-labeled-message}) moves to the next message that has -one of the labels @var{labels}. The argument @var{labels} specifies -one or more label names, separated by commas. @kbd{C-M-p} -(@code{rmail-previous-labeled-message}) is similar, but moves -backwards to previous messages. A numeric argument to either command -serves as a repeat count. - - The command @kbd{C-M-l @var{labels} @key{RET}} -(@code{rmail-summary-by-labels}) displays a summary containing only the -messages that have at least one of a specified set of labels. The -argument @var{labels} is one or more label names, separated by commas. -@xref{Rmail Summary}, for information on summaries. - - If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or -@kbd{C-M-l} is empty, it means to use the last set of labels specified -for any of these commands. - - @xref{Rmail Sorting}, for information on sorting messages with labels. - -@node Rmail Attributes -@section Rmail Attributes - - Some labels such as @samp{deleted} and @samp{filed} have built-in -meanings, and Rmail assigns them to messages automatically at -appropriate times; these labels are called @dfn{attributes}. Here is -a list of Rmail attributes: - -@table @samp -@item unseen -Means the message has never been current. Assigned to messages when -they come from an inbox file, and removed when a message is made -current. When you start Rmail, it initially shows the first message -that has this attribute. -@item deleted -Means the message is deleted. Assigned by deletion commands and -removed by undeletion commands (@pxref{Rmail Deletion}). -@item filed -Means the message has been copied to some other file. Assigned by the -@kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}). -@item answered -Means you have mailed an answer to the message. Assigned by the @kbd{r} -command (@code{rmail-reply}). @xref{Rmail Reply}. -@item forwarded -Means you have forwarded the message. Assigned by the @kbd{f} command -(@code{rmail-forward}). @xref{Rmail Reply}. -@item edited -Means you have edited the text of the message within Rmail. -@xref{Rmail Editing}. -@item resent -Means you have resent the message. Assigned by the command @kbd{M-x -rmail-resend}. @xref{Rmail Reply}. -@item retried -Means you have retried a failed outgoing message. Assigned by the -command @kbd{M-x rmail-retry-failure}. @xref{Rmail Reply}. -@end table - - All other labels are assigned or removed only by users, and have no -standard meaning. - -@node Rmail Reply -@section Sending Replies - - Rmail has several commands to send outgoing mail. @xref{Sending -Mail}, for information on using Message mode, including certain -features meant to work with Rmail. What this section documents are -the special commands of Rmail for entering the mail buffer. Note that -the usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and -@kbd{C-x 5 m}---also work normally in Rmail mode. - -@table @kbd -@item m -Send a message (@code{rmail-mail}). -@item c -Continue editing the already started outgoing message (@code{rmail-continue}). -@item r -Send a reply to the current Rmail message (@code{rmail-reply}). -@item f -Forward the current message to other users (@code{rmail-forward}). -@item C-u f -Resend the current message to other users (@code{rmail-resend}). -@item M-m -Try sending a bounced message a second time (@code{rmail-retry-failure}). -@end table - -@kindex r @r{(Rmail)} -@findex rmail-reply -@cindex reply to a message - The most common reason to send a message while in Rmail is to reply -to the message you are reading. To do this, type @kbd{r} -(@code{rmail-reply}). This displays a mail composition buffer in -another window, much like @kbd{C-x 4 m}, but preinitializes the -@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and -@samp{References} header fields based on the message you are replying -to. The @samp{To} field starts out as the address of the person who -sent the message you received, and the @samp{CC} field starts out with -all the other recipients of that message. - -@vindex mail-dont-reply-to-names - You can exclude certain recipients from being included automatically -in replies, using the variable @code{mail-dont-reply-to-names}. Its -value should be a regular expression; any recipients that match are -excluded from the @samp{CC} field. They are also excluded from the -@samp{To} field, unless this would leave the field empty. If this -variable is @code{nil}, then the first time you compose a reply it is -initialized to a default value that matches your own address. - - To omit the @samp{CC} field completely for a particular reply, enter -the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}. -This means to reply only to the sender of the original message. - - Once the mail composition buffer has been initialized, editing and -sending the mail goes as usual (@pxref{Sending Mail}). You can edit -the presupplied header fields if they are not what you want. You can -also use commands such as @kbd{C-c C-y}, which yanks in the message -that you are replying to (@pxref{Mail Commands}). You can also switch -to the Rmail buffer, select a different message there, switch back, -and yank the new current message. - -@kindex M-m @r{(Rmail)} -@findex rmail-retry-failure -@cindex retrying a failed message -@vindex rmail-retry-ignored-headers - Sometimes a message does not reach its destination. Mailers usually -send the failed message back to you, enclosed in a @dfn{failure -message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure}) -prepares to send the same message a second time: it sets up a -mail composition buffer with the same text and header fields as before. If -you type @kbd{C-c C-c} right away, you send the message again exactly -the same as the first time. Alternatively, you can edit the text or -headers and then send it. The variable -@code{rmail-retry-ignored-headers}, in the same format as -@code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which -headers are stripped from the failed message when retrying it. - -@kindex f @r{(Rmail)} -@findex rmail-forward -@cindex forwarding a message - Another frequent reason to send mail in Rmail is to @dfn{forward} the -current message to other users. @kbd{f} (@code{rmail-forward}) makes -this easy by preinitializing the mail composition buffer with the current -message as the text, and a subject of the form @code{[@var{from}: -@var{subject}]}, where @var{from} and @var{subject} are the sender and -subject of the original message. All you have to do is fill in the -recipients and send. When you forward a message, recipients get a -message which is ``from'' you, and which has the original message in -its contents. - -@vindex rmail-enable-mime-composing -@findex unforward-rmail-message - Rmail offers two formats for forwarded messages. The default is to -use MIME (@pxref{Rmail Display}) format. This includes the original -message as a separate part. You can use a simpler format if you -prefer, by setting the variable @code{rmail-enable-mime-composing} to -@code{nil}. In this case, Rmail just includes the original message -enclosed between two delimiter lines. It also modifies every line -that starts with a dash, by inserting @w{@samp{- }} at the start of -the line. When you receive a forwarded message in this format, if it -contains something besides ordinary text---for example, program source -code---you might find it useful to undo that transformation. You can -do this by selecting the forwarded message and typing @kbd{M-x -unforward-rmail-message}. This command extracts the original -forwarded message, deleting the inserted @w{@samp{- }} strings, and -inserts it into the Rmail file as a separate message immediately -following the current one. - -@findex rmail-resend - @dfn{Resending} is an alternative similar to forwarding; the -difference is that resending sends a message that is ``from'' the -original sender, just as it reached you---with a few added header fields -(@samp{Resent-From} and @samp{Resent-To}) to indicate that it came via -you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs -@code{rmail-forward}, which invokes @code{rmail-resend} if you provide a -numeric argument.) - -@kindex m @r{(Rmail)} -@findex rmail-mail - Use the @kbd{m} (@code{rmail-mail}) command to start editing an -outgoing message that is not a reply. It leaves the header fields empty. -Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer -accessible for @kbd{C-c C-y}, just as @kbd{r} does. -@ignore -@c Not a good idea, because it does not include Reply-To etc. -Thus, @kbd{m} can be used to reply to or forward a message; it can do -anything @kbd{r} or @kbd{f} can do. -@end ignore - -@kindex c @r{(Rmail)} -@findex rmail-continue - The @kbd{c} (@code{rmail-continue}) command resumes editing the -mail composition buffer, to finish editing an outgoing message you were -already composing, or to alter a message you have sent. - -@vindex rmail-mail-new-frame - If you set the variable @code{rmail-mail-new-frame} to a -non-@code{nil} value, then all the Rmail commands to start sending a -message create a new frame to edit it in. This frame is deleted when -you send the message. -@ignore -@c FIXME does not work with Message -> Kill Message -, or when you use the @samp{Cancel} item in the @samp{Mail} menu. -@end ignore - - All the Rmail commands to send a message use the mail-composition -method that you have chosen (@pxref{Mail Methods}). - -@node Rmail Summary -@section Summaries -@cindex summary (Rmail) - - A @dfn{summary} is a buffer containing one line per message to give -you an overview of the mail in an Rmail file. Each line shows the -message number and date, the sender, the line count, the labels, and -the subject. Moving point in the summary buffer selects messages as -you move to their summary lines. Almost all Rmail commands are valid -in the summary buffer also; when used there, they apply to the message -described by the current line of the summary. - - A summary buffer applies to a single Rmail file only; if you are -editing multiple Rmail files, each one can have its own summary buffer. -The summary buffer name is made by appending @samp{-summary} to the -Rmail buffer's name. Normally only one summary buffer is displayed at a -time. - -@menu -* Rmail Make Summary:: Making various sorts of summaries. -* Rmail Summary Edit:: Manipulating messages from the summary. -@end menu - -@node Rmail Make Summary -@subsection Making Summaries - - Here are the commands to create a summary for the current Rmail -buffer. Once the Rmail buffer has a summary, changes in the Rmail -buffer (such as deleting or expunging messages, and getting new mail) -automatically update the summary. - -@table @kbd -@item h -@itemx C-M-h -Summarize all messages (@code{rmail-summary}). -@item l @var{labels} @key{RET} -@itemx C-M-l @var{labels} @key{RET} -Summarize messages that have one or more of the specified labels -(@code{rmail-summary-by-labels}). -@item C-M-r @var{rcpts} @key{RET} -Summarize messages that match the specified recipients -(@code{rmail-summary-by-recipients}). -@item C-M-t @var{topic} @key{RET} -Summarize messages that have a match for the specified regexp -@var{topic} in their subjects (@code{rmail-summary-by-topic}). -@item C-M-s @var{regexp} @key{RET} -Summarize messages whose headers match the specified regular expression -@var{regexp} (@code{rmail-summary-by-regexp}). -@item C-M-f @var{senders} @key{RET} -Summarize messages that match the specified senders. -(@code{rmail-summary-by-senders}). -@end table - -@kindex h @r{(Rmail)} -@findex rmail-summary - The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer -for the current Rmail buffer with a summary of all the messages in the buffer. -It then displays and selects the summary buffer in another window. - -@kindex l @r{(Rmail)} -@kindex C-M-l @r{(Rmail)} -@findex rmail-summary-by-labels - @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes -a partial summary mentioning only the messages that have one or more of the -labels @var{labels}. @var{labels} should contain label names separated by -commas. - -@kindex C-M-r @r{(Rmail)} -@findex rmail-summary-by-recipients - @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients}) -makes a partial summary mentioning only the messages that have one or -more recipients matching the regular expression @var{rcpts}. You can -use commas to separate multiple regular expressions. These are matched -against the @samp{To}, @samp{From}, and @samp{CC} headers (supply a prefix -argument to exclude this header). - -@kindex C-M-t @r{(Rmail)} -@findex rmail-summary-by-topic - @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic}) -makes a partial summary mentioning only the messages whose subjects have -a match for the regular expression @var{topic}. You can use commas to -separate multiple regular expressions. With a prefix argument, the -match is against the whole message, not just the subject. - -@kindex C-M-s @r{(Rmail)} -@findex rmail-summary-by-regexp - @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp}) -makes a partial summary that mentions only the messages whose headers -(including the date and the subject lines) match the regular -expression @var{regexp}. - -@kindex C-M-f @r{(Rmail)} -@findex rmail-summary-by-senders - @kbd{C-M-f @var{senders} @key{RET}} (@code{rmail-summary-by-senders}) -makes a partial summary that mentions only the messages whose @samp{From} -fields match the regular expression @var{senders}. You can use commas to -separate multiple regular expressions. - - Note that there is only one summary buffer for any Rmail buffer; -making any kind of summary discards any previous summary. - -@vindex rmail-summary-window-size -@vindex rmail-summary-line-count-flag - The variable @code{rmail-summary-window-size} says how many lines to -use for the summary window. The variable -@code{rmail-summary-line-count-flag} controls whether the summary line -for a message should include the line count of the message. Setting -this option to @code{nil} might speed up the generation of summaries. - -@node Rmail Summary Edit -@subsection Editing in Summaries - - You can use the Rmail summary buffer to do almost anything you can do -in the Rmail buffer itself. In fact, once you have a summary buffer, -there's no need to switch back to the Rmail buffer. - - You can select and display various messages in the Rmail buffer, from -the summary buffer, just by moving point in the summary buffer to -different lines. It doesn't matter what Emacs command you use to move -point; whichever line point is on at the end of the command, that -message is selected in the Rmail buffer. - - Almost all Rmail commands work in the summary buffer as well as in the -Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current -message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the -summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u} -serves as a repeat count. A negative argument reverses the meaning of -@kbd{d} and @kbd{C-d}. Also, if there are no more undeleted messages in -the relevant direction, the delete commands go to the first or last -message, rather than staying on the current message.) @kbd{o} and -@kbd{C-o} output the current message to a FILE; @kbd{r} starts a reply -to it; etc. You can scroll the current message while remaining in the -summary buffer using @key{SPC} and @key{DEL}. -@c rmail-summary-scroll-between-messages not mentioned. - -@findex rmail-summary-undelete-many -@kbd{M-u} (@code{rmail-summary-undelete-many}) undeletes all deleted -messages in the summary. A prefix argument means to undelete that many -of the previous deleted messages. - - The Rmail commands to move between messages also work in the summary -buffer, but with a twist: they move through the set of messages included -in the summary. They also ensure the Rmail buffer appears on the screen -(unlike cursor motion commands, which update the contents of the Rmail -buffer but don't display it in a window unless it already appears). -Here is a list of these commands: - -@table @kbd -@item n -Move to next line, skipping lines saying `deleted', and select its -message (@code{rmail-summary-next-msg}). -@item p -Move to previous line, skipping lines saying `deleted', and select -its message (@code{rmail-summary-previous-msg}). -@item M-n -Move to next line and select its message (@code{rmail-summary-next-all}). -@item M-p -Move to previous line and select its message -(@code{rmail-summary-previous-all}). -@item > -Move to the last line, and select its message -(@code{rmail-summary-last-message}). -@item < -Move to the first line, and select its message -(@code{rmail-summary-first-message}). -@item j -@itemx @key{RET} -Select the message on the current line (ensuring that the Rmail buffer -appears on the screen; @code{rmail-summary-goto-msg}). With argument -@var{n}, select message number @var{n} and move to its line in the -summary buffer; this signals an error if the message is not listed in -the summary buffer. -@item M-s @var{pattern} @key{RET} -Search through messages for @var{pattern} starting with the current -message; select the message found, and move point in the summary buffer -to that message's line (@code{rmail-summary-search}). A prefix argument -acts as a repeat count; a negative argument means search backward -(equivalent to @code{rmail-summary-search-backward}.) -@item C-M-n @var{labels} @key{RET} -Move to the next message with at least one of the specified labels -(@code{rmail-summary-next-labeled-message}). @var{labels} is a -comma-separated list of labels. A prefix argument acts as a repeat -count. -@item C-M-p @var{labels} @key{RET} -Move to the previous message with at least one of the specified labels -(@code{rmail-summary-previous-labeled-message}). -@item C-c C-n @key{RET} -Move to the next message with the same subject as the current message -(@code{rmail-summary-next-same-subject}). A prefix argument acts as a -repeat count. -@item C-c C-p @key{RET} -Move to the previous message with the same subject as the current message -(@code{rmail-summary-previous-same-subject}). -@end table - -@vindex rmail-redisplay-summary - Deletion, undeletion, and getting new mail, and even selection of a -different message all update the summary buffer when you do them in the -Rmail buffer. If the variable @code{rmail-redisplay-summary} is -non-@code{nil}, these actions also bring the summary buffer back onto -the screen. - -@kindex Q @r{(Rmail summary)} -@findex rmail-summary-wipe -@kindex q @r{(Rmail summary)} -@findex rmail-summary-quit -@kindex b @r{(Rmail summary)} -@findex rmail-summary-bury - When you are finished using the summary, type @kbd{Q} -(@code{rmail-summary-wipe}) to delete the summary buffer's window. You -can also exit Rmail while in the summary: @kbd{q} -(@code{rmail-summary-quit}) deletes the summary window, then exits from -Rmail by saving the Rmail file and switching to another buffer. -Alternatively, @kbd{b} (@code{rmail-summary-bury}) simply buries the -Rmail summary and buffer. - -@node Rmail Sorting -@section Sorting the Rmail File -@cindex sorting Rmail file -@cindex Rmail file sorting - -@table @kbd -@findex rmail-sort-by-date -@item C-c C-s C-d -@itemx M-x rmail-sort-by-date -Sort messages of current Rmail buffer by date. - -@findex rmail-sort-by-subject -@item C-c C-s C-s -@itemx M-x rmail-sort-by-subject -Sort messages of current Rmail buffer by subject. - -@findex rmail-sort-by-author -@item C-c C-s C-a -@itemx M-x rmail-sort-by-author -Sort messages of current Rmail buffer by author's name. - -@findex rmail-sort-by-recipient -@item C-c C-s C-r -@itemx M-x rmail-sort-by-recipient -Sort messages of current Rmail buffer by recipient's names. - -@findex rmail-sort-by-correspondent -@item C-c C-s C-c -@itemx M-x rmail-sort-by-correspondent -Sort messages of current Rmail buffer by the name of the other -correspondent. - -@findex rmail-sort-by-lines -@item C-c C-s C-l -@itemx M-x rmail-sort-by-lines -Sort messages of current Rmail buffer by number of lines. - -@findex rmail-sort-by-labels -@item C-c C-s C-k @key{RET} @var{labels} @key{RET} -@itemx M-x rmail-sort-by-labels @key{RET} @var{labels} @key{RET} -Sort messages of current Rmail buffer by labels. The argument -@var{labels} should be a comma-separated list of labels. The order of -these labels specifies the order of messages; messages with the first -label come first, messages with the second label come second, and so on. -Messages that have none of these labels come last. -@end table - - The Rmail sort commands perform a @emph{stable sort}: if there is no -reason to prefer either one of two messages, their order remains -unchanged. You can use this to sort by more than one criterion. For -example, if you use @code{rmail-sort-by-date} and then -@code{rmail-sort-by-author}, messages from the same author appear in -order by date. - - With a prefix argument, all these commands reverse the order of -comparison. This means they sort messages from newest to oldest, from -biggest to smallest, or in reverse alphabetical order. - - The same keys in the summary buffer run similar functions; for -example, @kbd{C-c C-s C-l} runs @code{rmail-summary-sort-by-lines}. -Note that these commands always sort the whole Rmail buffer, even if the -summary is only showing a subset of messages. - - Note that you cannot undo a sort, so you may wish to save the Rmail -buffer before sorting it. - -@node Rmail Display -@section Display of Messages - - This section describes how Rmail displays mail headers, -@acronym{MIME} sections and attachments, URLs, and encrypted messages. - -@table @kbd -@item t -Toggle display of complete header (@code{rmail-toggle-header}). -@end table - -@kindex t @r{(Rmail)} -@findex rmail-toggle-header - Before displaying each message for the first time, Rmail reformats -its header, hiding uninteresting header fields to reduce clutter. The -@kbd{t} (@code{rmail-toggle-header}) command toggles this, switching -between showing the reformatted header fields and showing the -complete, original header. With a positive prefix argument, the -command shows the reformatted header; with a zero or negative prefix -argument, it shows the full header. Selecting the message again also -reformats it if necessary. - -@vindex rmail-ignored-headers -@vindex rmail-displayed-headers -@vindex rmail-nonignored-headers - The variable @code{rmail-ignored-headers} holds a regular expression -specifying the header fields to hide; any matching header line will be -hidden. The variable @code{rmail-nonignored-headers} overrides this: -any header field matching that regular expression is shown even if it -matches @code{rmail-ignored-headers} too. The variable -@code{rmail-displayed-headers} is an alternative to these two -variables; if non-@code{nil}, this should be a regular expression -specifying which headers to display (the default is @code{nil}). - -@vindex rmail-highlighted-headers - Rmail highlights certain header fields that are especially -interesting---by default, the @samp{From} and @samp{Subject} fields. -This highlighting uses the @code{rmail-highlight} face. The variable -@code{rmail-highlighted-headers} holds a regular expression specifying -the header fields to highlight; if it matches the beginning of a -header field, that whole field is highlighted. To disable this -feature, set @code{rmail-highlighted-headers} to @code{nil}. - -@cindex MIME messages (Rmail) -@vindex rmail-enable-mime - If a message is in @acronym{MIME} (Multipurpose Internet Mail -Extensions) format and contains multiple parts (@acronym{MIME} -entities), Rmail displays each part with a @dfn{tagline}. The tagline -summarizes the part's index, size, and content type. Depending on the -content type, it may also contain one or more buttons; these perform -actions such as saving the part into a file. - -@table @kbd -@findex rmail-mime-toggle-hidden -@item @key{RET} -Hide or show the @acronym{MIME} part at point -(@code{rmail-mime-toggle-hidden}). - -@findex rmail-mime-next-item -@item @key{TAB} -Move point to the next @acronym{MIME} tagline button. -(@code{rmail-mime-next-item}). - -@findex rmail-mime-previous-item -@item S-@key{TAB} -Move point to the previous @acronym{MIME} part -(@code{rmail-mime-previous-item}). - -@findex rmail-mime -@item v -@kindex v @r{(Rmail)} -Toggle between @acronym{MIME} display and raw message -(@code{rmail-mime}). -@end table - - Each plain-text @acronym{MIME} part is initially displayed -immediately after its tagline, as part of the Rmail buffer, while -@acronym{MIME} parts of other types are represented only by their -taglines, with their actual contents hidden. In either case, you can -toggle a @acronym{MIME} part between its ``displayed'' and ``hidden'' -states by typing @key{RET} anywhere in the part---or anywhere in its -tagline (except for buttons for other actions, if there are any). Type -@key{RET} (or click with the mouse) to activate a tagline button, and -@key{TAB} to cycle point between tagline buttons. - - The @kbd{v} (@code{rmail-mime}) command toggles between the default -@acronym{MIME} display described above, and a ``raw'' display showing -the undecoded @acronym{MIME} data. With a prefix argument, this -command toggles the display of only an entity at point. - - To prevent Rmail from handling MIME decoded messages, change the -variable @code{rmail-enable-mime} to @code{nil}. When this is the -case, the @kbd{v} (@code{rmail-mime}) command instead creates a -temporary buffer to display the current @acronym{MIME} message. - -@findex rmail-epa-decrypt -@cindex encrypted mails (reading in Rmail) - If the current message is an encrypted one, use the command @kbd{M-x -rmail-epa-decrypt} to decrypt it, using the EasyPG library -(@pxref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}). - - You can highlight and activate URLs in the Rmail buffer using Goto -Address mode: - -@c FIXME goto-addr.el commentary says to use goto-address instead. -@example -(add-hook 'rmail-show-message-hook 'goto-address-mode) -@end example - -@noindent -Then you can browse these URLs by clicking on them with @kbd{Mouse-2} -(or @kbd{Mouse-1} quickly) or by moving to one and typing @kbd{C-c -@key{RET}}. @xref{Goto Address mode, Activating URLs, Activating URLs}. - -@node Rmail Coding -@section Rmail and Coding Systems - -@cindex decoding mail messages (Rmail) - Rmail automatically decodes messages which contain non-@acronym{ASCII} -characters, just as Emacs does with files you visit and with subprocess -output. Rmail uses the standard @samp{charset=@var{charset}} header in -the message, if any, to determine how the message was encoded by the -sender. It maps @var{charset} into the corresponding Emacs coding -system (@pxref{Coding Systems}), and uses that coding system to decode -message text. If the message header doesn't have the @samp{charset} -specification, or if @var{charset} is not recognized, -Rmail chooses the coding system with the usual Emacs heuristics and -defaults (@pxref{Recognize Coding}). - -@cindex fixing incorrectly decoded mail messages - Occasionally, a message is decoded incorrectly, either because Emacs -guessed the wrong coding system in the absence of the @samp{charset} -specification, or because the specification was inaccurate. For -example, a misconfigured mailer could send a message with a -@samp{charset=iso-8859-1} header when the message is actually encoded -in @code{koi8-r}. When you see the message text garbled, or some of -its characters displayed as hex codes or empty boxes, this may have -happened. - -@findex rmail-redecode-body - You can correct the problem by decoding the message again using the -right coding system, if you can figure out or guess which one is -right. To do this, invoke the @kbd{M-x rmail-redecode-body} command. -It reads the name of a coding system, and then redecodes the message -using the coding system you specified. If you specified the right -coding system, the result should be readable. - -@vindex rmail-file-coding-system - When you get new mail in Rmail, each message is translated -automatically from the coding system it is written in, as if it were a -separate file. This uses the priority list of coding systems that you -have specified. If a MIME message specifies a character set, Rmail -obeys that specification. For reading and saving Rmail files -themselves, Emacs uses the coding system specified by the variable -@code{rmail-file-coding-system}. The default value is @code{nil}, -which means that Rmail files are not translated (they are read and -written in the Emacs internal character code). - -@node Rmail Editing -@section Editing Within a Message - - Most of the usual Emacs key bindings are available in Rmail mode, -though a few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by -Rmail for other purposes. However, the Rmail buffer is normally read -only, and most of the letters are redefined as Rmail commands. If you -want to edit the text of a message, you must use the Rmail command -@kbd{e}. - -@table @kbd -@item e -Edit the current message as ordinary text. -@end table - -@kindex e @r{(Rmail)} -@findex rmail-edit-current-message - The @kbd{e} command (@code{rmail-edit-current-message}) switches from -Rmail mode into Rmail Edit mode, another major mode which is nearly the -same as Text mode. The mode line indicates this change. - - In Rmail Edit mode, letters insert themselves as usual and the Rmail -commands are not available. You can edit the message body and header -fields. When you are finished editing the message, type @kbd{C-c C-c} -to switch back to Rmail mode. Alternatively, you can return to Rmail -mode but cancel any editing that you have done, by typing @kbd{C-c C-]}. - -@vindex rmail-edit-mode-hook - Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then -it runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}). -Returning to ordinary Rmail mode adds the attribute @samp{edited} to -the message, if you have made any changes in it. - -@node Rmail Digest -@section Digest Messages -@cindex digest message -@cindex undigestify - - A @dfn{digest message} is a message which exists to contain and carry -several other messages. Digests are used on some mailing -lists; all the messages that arrive for the list during a period of time -such as one day are put inside a single digest which is then sent to the -subscribers. Transmitting the single digest uses less computer -time than transmitting the individual messages even though the total -size is the same, because of the per-message overhead in network mail -transmission. - -@findex undigestify-rmail-message - When you receive a digest message, the most convenient way to read it is -to @dfn{undigestify} it: to turn it back into many individual messages. -Then you can read and delete the individual messages as it suits you. -To do this, select the digest message and type the command @kbd{M-x -undigestify-rmail-message}. This extracts the submessages as separate -Rmail messages, and inserts them following the digest. The digest -message itself is flagged as deleted. - -@node Rmail Rot13 -@section Reading Rot13 Messages -@cindex rot13 code - - Mailing list messages that might offend or annoy some readers are sometimes -encoded in a simple code called @dfn{rot13}---so named because it -rotates the alphabet by 13 letters. This code is not for secrecy, as it -provides none; rather, it enables those who wish to to avoid -seeing the real text of the message. For example, a review of a film -might use rot13 to hide important plot points. - -@findex rot13-other-window - To view a buffer that uses the rot13 code, use the command @kbd{M-x -rot13-other-window}. This displays the current buffer in another window -which applies the code when displaying the text. - -@node Movemail -@section @code{movemail} program -@cindex @code{movemail} program - - Rmail uses the @code{movemail} program to move mail from your inbox to -your Rmail file (@pxref{Rmail Inbox}). When loaded for the first time, -Rmail attempts to locate the @code{movemail} program and determine its -version. There are two versions of the @code{movemail} program: the -native one, shipped with GNU Emacs (the ``emacs version'') and the one -included in GNU mailutils (the ``mailutils version'', -@pxref{movemail,,,mailutils,GNU mailutils}). They support the same -command line syntax and the same basic subset of options. However, the -Mailutils version offers additional features. - - The Emacs version of @code{movemail} is able to retrieve mail from -the usual Unix mailbox formats and from remote mailboxes using the -POP3 protocol. - - The Mailutils version is able to handle a wide set of mailbox -formats, such as plain Unix mailboxes, @code{maildir} and @code{MH} -mailboxes, etc. It is able to access remote mailboxes using the POP3 -or IMAP4 protocol, and can retrieve mail from them using a TLS -encrypted channel. It also accepts mailbox arguments in @acronym{URL} -form. The detailed description of mailbox @acronym{URL}s can be found -@c Note this node seems to be missing in some versions of mailutils.info? -in @ref{URL,,,mailutils,Mailbox URL Formats}. In short, a -@acronym{URL} is: - -@smallexample -@var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name} -@end smallexample - -@noindent -where square brackets denote optional elements. - -@table @var -@item proto -Specifies the @dfn{mailbox protocol}, or @dfn{format} to -use. The exact semantics of the rest of @acronym{URL} elements depends -on the actual value of @var{proto} (see below). - -@item user -User name to access the remote mailbox. - -@item password -User password to access the remote mailbox. - -@item host-or-file-name -Hostname of the remote server for remote mailboxes or file name of a -local mailbox. -@end table - -@noindent -@var{Proto} can be one of: - -@table @code -@item mbox -Usual Unix mailbox format. In this case, neither @var{user} nor -@var{pass} are used, and @var{host-or-file-name} denotes the file name -of the mailbox file, e.g., @code{mbox://var/spool/mail/smith}. - -@item mh -A local mailbox in the @acronym{MH} format. @var{User} and -@var{pass} are not used. @var{Host-or-file-name} denotes the name of -@acronym{MH} folder, e.g., @code{mh://Mail/inbox}. - -@item maildir -A local mailbox in the @acronym{maildir} format. @var{User} and -@var{pass} are not used, and @var{host-or-file-name} denotes the name of -@code{maildir} mailbox, e.g., @code{maildir://mail/inbox}. - -@item file -Any local mailbox format. Its actual format is detected automatically -by @code{movemail}. - -@item pop -A remote mailbox to be accessed via POP3 protocol. @var{User} -specifies the remote user name to use, @var{pass} may be used to -specify the user password, @var{host-or-file-name} is the name or IP -address of the remote mail server to connect to; e.g., -@code{pop://smith:guessme@@remote.server.net}. - -@item imap -A remote mailbox to be accessed via IMAP4 protocol. @var{User} -specifies the remote user name to use, @var{pass} may be used to -specify the user password, @var{host-or-file-name} is the name or IP -address of the remote mail server to connect to; -e.g., @code{imap://smith:guessme@@remote.server.net}. -@end table - - Alternatively, you can specify the file name of the mailbox to use. -This is equivalent to specifying the @samp{file} protocol: - -@smallexample -/var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user} -@end smallexample - -@vindex rmail-movemail-program -@vindex rmail-movemail-search-path - The variable @code{rmail-movemail-program} controls which version of -@code{movemail} to use. If that is a string, it specifies the -absolute file name of the @code{movemail} executable. If it is -@code{nil}, Rmail searches for @code{movemail} in the directories -listed in @code{rmail-movemail-search-path}, then in @code{exec-path} -(@pxref{Shell}), then in @code{exec-directory}. - -@node Remote Mailboxes -@section Retrieving Mail from Remote Mailboxes -@pindex movemail - - Some sites use a method called POP for accessing users' inbox data -instead of storing the data in inbox files. By default, the @code{Emacs -movemail} can work with POP (unless the Emacs @code{configure} script -was run with the option @samp{--without-pop}). - -Similarly, the Mailutils @code{movemail} by default supports POP, unless -it was configured with the @samp{--disable-pop} option. - -Both versions of @code{movemail} only work with POP3, not with older -versions of POP. - -@cindex @env{MAILHOST} environment variable -@cindex POP mailboxes - No matter which flavor of @code{movemail} you use, you can specify -a POP inbox by using a POP @dfn{URL} (@pxref{Movemail}). A POP -@acronym{URL} is a ``file name'' of the form -@samp{pop://@var{username}@@@var{hostname}}, where -@var{hostname} is the host name or IP address of the remote mail -server and @var{username} is the user name on that server. -Additionally, you may specify the password in the mailbox @acronym{URL}: -@samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this -case, @var{password} takes preference over the one set by -@code{rmail-remote-password} (see below). This is especially useful -if you have several remote mailboxes with different passwords. - - For backward compatibility, Rmail also supports an alternative way of -specifying remote POP mailboxes. Specifying an inbox name in the form -@samp{po:@var{username}:@var{hostname}} is equivalent to -@samp{pop://@var{username}@@@var{hostname}}. If you omit the -@var{:hostname} part, the @env{MAILHOST} environment variable specifies -the machine on which to look for the POP server. - -@c FIXME mention --with-hesiod "support Hesiod to get the POP server host"? - -@cindex IMAP mailboxes - Another method for accessing remote mailboxes is IMAP@. This method is -supported only by the Mailutils @code{movemail}. To specify an IMAP -mailbox in the inbox list, use the following mailbox @acronym{URL}: -@samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The -@var{password} part is optional, as described above. - -@vindex rmail-remote-password -@vindex rmail-remote-password-required - Accessing a remote mailbox may require a password. Rmail uses the -following algorithm to retrieve it: - -@enumerate -@item -If a @var{password} is present in the mailbox URL (see above), it is -used. -@item -If the variable @code{rmail-remote-password-required} is @code{nil}, -Rmail assumes no password is required. -@item -If the variable @code{rmail-remote-password} is non-@code{nil}, its -value is used. -@item -Otherwise, Rmail will ask you for the password to use. -@end enumerate - -@vindex rmail-movemail-flags - If you need to pass additional command-line flags to @code{movemail}, -set the variable @code{rmail-movemail-flags} a list of the flags you -wish to use. Do not use this variable to pass the @samp{-p} flag to -preserve your inbox contents; use @code{rmail-preserve-inbox} instead. - -@cindex Kerberos POP authentication - The @code{movemail} program installed at your site may support -Kerberos authentication (the Emacs @code{movemail} does so if Emacs was -configured with the option @code{--with-kerberos} or -@code{--with-kerberos5}). If it is supported, it is used by default -whenever you attempt to retrieve POP mail when -@code{rmail-remote-password} and @code{rmail-remote-password-required} -are unset. - -@cindex reverse order in POP inboxes - Some POP servers store messages in reverse order. If your server does -this, and you would rather read your mail in the order in which it was -received, you can tell @code{movemail} to reverse the order of -downloaded messages by adding the @samp{-r} flag to -@code{rmail-movemail-flags}. - -@cindex TLS encryption (Rmail) - Mailutils @code{movemail} supports TLS encryption. If you wish to -use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}. - -@node Other Mailbox Formats -@section Retrieving Mail from Local Mailboxes in Various Formats - - If your incoming mail is stored on a local machine in a format other -than Unix mailbox, you will need the Mailutils @code{movemail} to -retrieve it. @xref{Movemail}, for the detailed description of -@code{movemail} versions. For example, to access mail from a inbox in -@code{maildir} format located in @file{/var/spool/mail/in}, you would -include the following in the Rmail inbox list: - -@smallexample -maildir://var/spool/mail/in -@end smallexample diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi deleted file mode 100644 index 3c254268ed2..00000000000 --- a/doc/emacs/screen.texi +++ /dev/null @@ -1,324 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Screen -@chapter The Organization of the Screen -@cindex screen -@cindex frame - - On a graphical display, such as on GNU/Linux using the X Window -System, Emacs occupies a ``graphical window''. On a text terminal, -Emacs occupies the entire terminal screen. We will use the term -@dfn{frame} to mean a graphical window or terminal screen occupied by -Emacs. Emacs behaves very similarly on both kinds of frames. It -normally starts out with just one frame, but you can create additional -frames if you wish (@pxref{Frames}). - - Each frame consists of several distinct regions. At the top of the -frame is a @dfn{menu bar}, which allows you to access commands via a -series of menus. On a graphical display, directly below the menu bar -is a @dfn{tool bar}, a row of icons that perform editing commands if -you click on them. At the very bottom of the frame is an @dfn{echo -area}, where informative messages are displayed and where you enter -information when Emacs asks for it. - - The main area of the frame, below the tool bar (if one exists) and -above the echo area, is called @dfn{the window}. Henceforth in this -manual, we will use the word ``window'' in this sense. Graphical -display systems commonly use the word ``window'' with a different -meaning; but, as stated above, we refer to those ``graphical windows'' -as ``frames''. - - An Emacs window is where the @dfn{buffer}---the text you are -editing---is displayed. On a graphical display, the window possesses -a @dfn{scroll bar} on one side, which can be used to scroll through -the buffer. The last line of the window is a @dfn{mode line}. This -displays various information about what is going on in the buffer, -such as whether there are unsaved changes, the editing modes that are -in use, the current line number, and so forth. - - When you start Emacs, there is normally only one window in the -frame. However, you can subdivide this window horizontally or -vertically to create multiple windows, each of which can independently -display a buffer (@pxref{Windows}). - - At any time, one window is the @dfn{selected window}. On a -graphical display, the selected window shows a more prominent cursor -(usually solid and blinking); other windows show a less prominent -cursor (usually a hollow box). On a text terminal, there is only one -cursor, which is shown in the selected window. The buffer displayed -in the selected window is called the @dfn{current buffer}, and it is -where editing happens. Most Emacs commands implicitly apply to the -current buffer; the text displayed in unselected windows is mostly -visible for reference. If you use multiple frames on a graphical -display, selecting a particular frame selects a window in that frame. - -@menu -* Point:: The place in the text where editing commands operate. -* Echo Area:: Short messages appear at the bottom of the screen. -* Mode Line:: Interpreting the mode line. -* Menu Bar:: How to use the menu bar. -@end menu - -@node Point -@section Point -@cindex point -@cindex cursor - - The cursor in the selected window shows the location where most -editing commands take effect, which is called @dfn{point}@footnote{The -term ``point'' comes from the character @samp{.}, which was the -command in TECO (the language in which the original Emacs was written) -for accessing the editing position.}. Many Emacs commands move point -to different places in the buffer; for example, you can place point by -clicking mouse button 1 (normally the left button) at the desired -location. - - By default, the cursor in the selected window is drawn as a solid -block and appears to be @emph{on} a character, but you should think of -point as @emph{between} two characters; it is situated @emph{before} -the character under the cursor. For example, if your text looks like -@samp{frob} with the cursor over the @samp{b}, then point is between -the @samp{o} and the @samp{b}. If you insert the character @samp{!} -at that position, the result is @samp{fro!b}, with point between the -@samp{!} and the @samp{b}. Thus, the cursor remains over the -@samp{b}, as before. - - If you are editing several files in Emacs, each in its own buffer, -each buffer has its own value of point. A buffer that is not -currently displayed remembers its value of point if you later display -it again. Furthermore, if a buffer is displayed in multiple windows, -each of those windows has its own value of point. - - @xref{Cursor Display}, for options that control how Emacs displays -the cursor. - -@node Echo Area -@section The Echo Area -@cindex echo area - - The line at the very bottom of the frame is the @dfn{echo area}. It -is used to display small amounts of text for various purposes. - -@cindex echoing - The echo area is so-named because one of the things it is used for -is @dfn{echoing}, which means displaying the characters of a -multi-character command as you type. Single-character commands are -not echoed. Multi-character commands (@pxref{Keys}) are echoed if you -pause for more than a second in the middle of a command. Emacs then -echoes all the characters of the command so far, to prompt you for the -rest. Once echoing has started, the rest of the command echoes -immediately as you type it. This behavior is designed to give -confident users fast response, while giving hesitant users maximum -feedback. - -@cindex error message -@cindex echo area message - The echo area is also used to display an @dfn{error message} when a -command cannot do its job. Error messages may be accompanied by -beeping or by flashing the screen. - - Some commands display informative messages in the echo area to tell -you what the command has done, or to provide you with some specific -information. These @dfn{informative} messages, unlike error messages, -are not accompanied with a beep or flash. For example, @kbd{C-x =} -(hold down @key{Ctrl} and type @kbd{x}, then let go of @key{Ctrl} and -type @kbd{=}) displays a message describing the character at point, -its position in the buffer, and its current column in the window. -Commands that take a long time often display messages ending in -@samp{...} while they are working (sometimes also indicating how much -progress has been made, as a percentage), and add @samp{done} when -they are finished. - -@cindex @file{*Messages*} buffer -@cindex saved echo area messages -@cindex messages saved from echo area -@vindex message-log-max - Informative echo area messages are saved in a special buffer named -@file{*Messages*}. (We have not explained buffers yet; see -@ref{Buffers}, for more information about them.) If you miss a -message that appeared briefly on the screen, you can switch to the -@file{*Messages*} buffer to see it again. The @file{*Messages*} -buffer is limited to a certain number of lines, specified by the -variable @code{message-log-max}. (We have not explained variables -either; see @ref{Variables}, for more information about them.) Beyond -this limit, one line is deleted from the beginning whenever a new -message line is added at the end. - - @xref{Display Custom}, for options that control how Emacs uses the -echo area. - -@cindex minibuffer - The echo area is also used to display the @dfn{minibuffer}, a -special window where you can input arguments to commands, such as the -name of a file to be edited. When the minibuffer is in use, the text -displayed in the echo area begins with a @dfn{prompt string}, and the -active cursor appears within the minibuffer, which is temporarily -considered the selected window. You can always get out of the -minibuffer by typing @kbd{C-g}. @xref{Minibuffer}. - -@node Mode Line -@section The Mode Line -@cindex mode line -@cindex top level - - At the bottom of each window is a @dfn{mode line}, which describes -what is going on in the current buffer. When there is only one -window, the mode line appears right above the echo area; it is the -next-to-last line in the frame. On a graphical display, the mode line -is drawn with a 3D box appearance. Emacs also usually draws the mode -line of the selected window with a different color than that of -unselected windows, in order to make it stand out. - - The text displayed in the mode line has the following format: - -@example - @var{cs}:@var{ch}-@var{fr} @var{buf} @var{pos} @var{line} (@var{major} @var{minor}) -@end example - -@noindent -On a text terminal, this text is followed by a series of dashes -extending to the right edge of the window. These dashes are omitted -on a graphical display. - -The @var{cs} string and the colon character after it describe the -character set and newline convention used for the current buffer. -Normally, Emacs automatically handles these settings for you, but it -is sometimes useful to have this information. - - @var{cs} describes the character set of the text in the buffer -(@pxref{Coding Systems}). If it is a dash (@samp{-}), that indicates -no special character set handling (with the possible exception of -end-of-line conventions, described in the next paragraph). @samp{=} -means no conversion whatsoever, and is usually used for files -containing non-textual data. Other characters represent various -@dfn{coding systems}---for example, @samp{1} represents ISO Latin-1. - - On a text terminal, @var{cs} is preceded by two additional -characters that describe the coding systems for keyboard input and -terminal output. Furthermore, if you are using an input method, -@var{cs} is preceded by a string that identifies the input method -(@pxref{Input Methods}). - -@cindex end-of-line convention, mode-line indication - The character after @var{cs} is usually a colon. If a different -string is displayed, that indicates a nontrivial end-of-line -convention for encoding a file. Usually, lines of text are separated -by @dfn{newline characters} in a file, but two other conventions are -sometimes used. The MS-DOS convention uses a ``carriage-return'' -character followed by a ``linefeed'' character; when editing such -files, the colon changes to either a backslash (@samp{\}) or -@samp{(DOS)}, depending on the operating system. Another convention, -employed by older Macintosh systems, uses a ``carriage-return'' -character instead of a newline; when editing such files, the colon -changes to either a forward slash (@samp{/}) or @samp{(Mac)}. On some -systems, Emacs displays @samp{(Unix)} instead of the colon for files -that use newline as the line separator. - - The next element on the mode line is the string indicated by -@var{ch}. This shows two dashes (@samp{--}) if the buffer displayed -in the window has the same contents as the corresponding file on the -disk; i.e., if the buffer is ``unmodified''. If the buffer is -modified, it shows two stars (@samp{**}). For a read-only buffer, it -shows @samp{%*} if the buffer is modified, and @samp{%%} otherwise. - - The character after @var{ch} is normally a dash (@samp{-}). -However, if the default-directory for the current buffer is on a -remote machine, @samp{@@} is displayed instead (@pxref{File Names}). - - @var{fr} gives the selected frame name (@pxref{Frames}). It appears -only on text terminals. The initial frame's name is @samp{F1}. - - @var{buf} is the name of the buffer displayed in the window. -Usually, this is the same as the name of a file you are editing. -@xref{Buffers}. - - @var{pos} tells you whether there is additional text above the top -of the window, or below the bottom. If your buffer is small and all -of it is visible in the window, @var{pos} is @samp{All}. Otherwise, -it is @samp{Top} if you are looking at the beginning of the buffer, -@samp{Bot} if you are looking at the end of the buffer, or -@samp{@var{nn}%}, where @var{nn} is the percentage of the buffer above -the top of the window. With Size Indication mode, you can display the -size of the buffer as well. @xref{Optional Mode Line}. - - @var{line} is the character @samp{L} followed by the line number at -point. (You can display the current column number too, by turning on -Column Number mode. @xref{Optional Mode Line}.) - - @var{major} is the name of the @dfn{major mode} used in the buffer. -A major mode is a principal editing mode for the buffer, such as Text -mode, Lisp mode, C mode, and so forth. @xref{Major Modes}. Some -major modes display additional information after the major mode name. -For example, Compilation buffers and Shell buffers display the status -of the subprocess. - - @var{minor} is a list of some of the enabled @dfn{minor modes}, -which are optional editing modes that provide additional features on -top of the major mode. @xref{Minor Modes}. - - Some features are listed together with the minor modes whenever they -are turned on, even though they are not really minor modes. -@samp{Narrow} means that the buffer being displayed has editing -restricted to only a portion of its text (@pxref{Narrowing}). -@samp{Def} means that a keyboard macro is currently being defined -(@pxref{Keyboard Macros}). - - In addition, if Emacs is inside a recursive editing level, square -brackets (@samp{[@dots{}]}) appear around the parentheses that -surround the modes. If Emacs is in one recursive editing level within -another, double square brackets appear, and so on. Since recursive -editing levels affect Emacs globally, such square brackets appear in -the mode line of every window. @xref{Recursive Edit}. - - You can change the appearance of the mode line as well as the format -of its contents. @xref{Optional Mode Line}. In addition, the mode -line is mouse-sensitive; clicking on different parts of the mode line -performs various commands. @xref{Mode Line Mouse}. - -@node Menu Bar -@section The Menu Bar -@cindex menu bar - - Each Emacs frame normally has a @dfn{menu bar} at the top which you -can use to perform common operations. There's no need to list them -here, as you can more easily see them yourself. - - On a display that supports a mouse, you can use the mouse to choose a -command from the menu bar. An arrow on the right edge of a menu item -means it leads to a subsidiary menu, or @dfn{submenu}. A @samp{...} -at the end of a menu item means that the command will prompt you for -further input before it actually does anything. - - Some of the commands in the menu bar have ordinary key bindings as -well; if so, a key binding is shown in parentheses after the item -itself. To view the full command name and documentation for a menu -item, type @kbd{C-h k}, and then select the menu bar with the mouse in -the usual way (@pxref{Key Help}). - -@kindex F10 -@findex menu-bar-open -@cindex menu bar access using keyboard - Instead of using the mouse, you can also invoke the first menu bar -item by pressing @key{F10} (to run the command @code{menu-bar-open}). -You can then navigate the menus with the arrow keys. To activate a -selected menu item, press @key{RET}; to cancel menu navigation, press -@kbd{C-g} or @kbd{@key{ESC} @key{ESC} @key{ESC}}. - -@kindex M-` -@findex tmm-menubar -@vindex tty-menu-open-use-tmm - On a text terminal, you can optionally access the menu-bar menus in -the echo area. To this end, customize the variable -@code{tty-menu-open-use-tmm} to a non-@code{nil} value. Then typing -@key{F10} will run the command @code{tmm-menubar} instead of dropping -down the menu. (You can also type @kbd{M-`}, which always invokes -@code{tmm-menubar}.) @code{tmm-menubar} lets you select a menu item -with the keyboard. A provisional choice appears in the echo area. -You can use the up and down arrow keys to move through the menu to -different items, and then you can type @key{RET} to select the item. -Each menu item is also designated by a letter or digit (usually the -initial of some word in the item's name). This letter or digit is -separated from the item name by @samp{==>}. You can type the item's -letter or digit to select the item. diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi deleted file mode 100644 index bdfb534e186..00000000000 --- a/doc/emacs/search.texi +++ /dev/null @@ -1,1509 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Search -@chapter Searching and Replacement -@cindex searching -@cindex finding strings within text - - Like other editors, Emacs has commands to search for occurrences of -a string. Emacs also has commands to replace occurrences of a string -with a different string. There are also commands that do the same -thing, but search for patterns instead of fixed strings. - - You can also search multiple files under the control of a tags table -(@pxref{Tags Search}) or through the Dired @kbd{A} command -(@pxref{Operating on Files}), or ask the @code{grep} program to do it -(@pxref{Grep Searching}). - -@menu -* Incremental Search:: Search happens as you type the string. -* Nonincremental Search:: Specify entire string and then search. -* Word Search:: Search for sequence of words. -* Symbol Search:: Search for a source code symbol. -* Regexp Search:: Search for match for a regexp. -* Regexps:: Syntax of regular expressions. -* Regexp Backslash:: Regular expression constructs starting with `\'. -* Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. -* Replace:: Search, and replace some or all matches. -* Other Repeating Search:: Operating on all matches for some regexp. -@end menu - -@node Incremental Search -@section Incremental Search -@cindex incremental search -@cindex isearch - - The principal search command in Emacs is @dfn{incremental}: it -begins searching as soon as you type the first character of the search -string. As you type in the search string, Emacs shows you where the -string (as you have typed it so far) would be found. When you have -typed enough characters to identify the place you want, you can stop. -Depending on what you plan to do next, you may or may not need to -terminate the search explicitly with @key{RET}. - -@table @kbd -@item C-s -Incremental search forward (@code{isearch-forward}). -@item C-r -Incremental search backward (@code{isearch-backward}). -@end table - -@menu -* Basic Isearch:: Basic incremental search commands. -* Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. -* Isearch Yank:: Commands that grab text into the search string - or else edit the search string. -* Not Exiting Isearch:: Prefix argument and scrolling commands. -* Isearch Minibuffer:: Incremental search of the minibuffer history. -@end menu - -@node Basic Isearch -@subsection Basics of Incremental Search - -@table @kbd -@item C-s -Begin incremental search (@code{isearch-forward}). -@item C-r -Begin reverse incremental search (@code{isearch-backward}). -@end table - -@kindex C-s -@findex isearch-forward - @kbd{C-s} (@code{isearch-forward}) starts a forward incremental -search. It reads characters from the keyboard, and moves point just -past the end of the next occurrence of those characters in the buffer. - - For instance, if you type @kbd{C-s} and then @kbd{F}, that puts the -cursor after the first @samp{F} that occurs in the buffer after the -starting point. Then if you then type @kbd{O}, the cursor moves to -just after the first @samp{FO}; the @samp{F} in that @samp{FO} might -not be the first @samp{F} previously found. After another @kbd{O}, -the cursor moves to just after the first @samp{FOO}. - -@cindex faces for highlighting search matches - At each step, Emacs highlights the @dfn{current match}---the buffer -text that matches the search string---using the @code{isearch} face -(@pxref{Faces}). The current search string is also displayed in the -echo area. - - If you make a mistake typing the search string, type @key{DEL}. -Each @key{DEL} cancels the last character of the search string. - - When you are satisfied with the place you have reached, type -@key{RET}. This stops searching, leaving the cursor where the search -brought it. Also, any command not specially meaningful in searches -stops the searching and is then executed. Thus, typing @kbd{C-a} -exits the search and then moves to the beginning of the line. -@key{RET} is necessary only if the next command you want to type is a -printing character, @key{DEL}, @key{RET}, or another character that is -special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, -@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others -described below). - - As a special exception, entering @key{RET} when the search string is -empty launches nonincremental search (@pxref{Nonincremental Search}). - - When you exit the incremental search, it adds the original value of -point to the mark ring, without activating the mark; you can thus use -@kbd{C-u C-@key{SPC}} to return to where you were before beginning the -search. @xref{Mark Ring}. It only does this if the mark was not -already active. - -@kindex C-r -@findex isearch-backward - To search backwards, use @kbd{C-r} (@code{isearch-backward}) instead -of @kbd{C-s} to start the search. A backward search finds matches -that end before the starting point, just as a forward search finds -matches that begin after it. - -@node Repeat Isearch -@subsection Repeating Incremental Search - - Suppose you search forward for @samp{FOO} and find a match, but not -the one you expected to find: the @samp{FOO} you were aiming for -occurs later in the buffer. In this event, type another @kbd{C-s} to -move to the next occurrence of the search string. You can repeat this -any number of times. If you overshoot, you can cancel some @kbd{C-s} -characters with @key{DEL}. Similarly, each @kbd{C-r} in a backward -incremental search repeats the backward search. - -@cindex lazy search highlighting -@vindex isearch-lazy-highlight - If you pause for a little while during incremental search, Emacs -highlights all the other possible matches for the search string that -are present on the screen. This helps you anticipate where you can -get to by typing @kbd{C-s} or @kbd{C-r} to repeat the search. The -other matches are highlighted differently from the current match, -using the customizable face @code{lazy-highlight} (@pxref{Faces}). If -you don't like this feature, you can disable it by setting -@code{isearch-lazy-highlight} to @code{nil}. - - After exiting a search, you can search for the same string again by -typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that -invokes incremental search, and the second @kbd{C-s} means ``search -again''. Similarly, @kbd{C-r C-r} searches backward for the last -search string. In determining the last search string, it doesn't -matter whether the string was searched for with @kbd{C-s} or -@kbd{C-r}. - - If you are searching forward but you realize you were looking for -something before the starting point, type @kbd{C-r} to switch to a -backward search, leaving the search string unchanged. Similarly, -@kbd{C-s} in a backward search switches to a forward search. - - If a search is failing and you ask to repeat it by typing another -@kbd{C-s}, it starts again from the beginning of the buffer. -Repeating a failing reverse search with @kbd{C-r} starts again from -the end. This is called @dfn{wrapping around}, and @samp{Wrapped} -appears in the search prompt once this has happened. If you keep on -going past the original starting point of the search, it changes to -@samp{Overwrapped}, which means that you are revisiting matches that -you have already seen. - -@cindex search ring -@kindex M-n @r{(Incremental search)} -@kindex M-p @r{(Incremental search)} - To reuse earlier search strings, use the @dfn{search ring}. The -commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a -search string to reuse. These commands leave the selected search ring -element in the minibuffer, where you can edit it. - -@kindex M-e @r{(Incremental search)} - To edit the current search string in the minibuffer without -replacing it with items from the search ring, type @kbd{M-e}. Type @key{RET}, -@kbd{C-s} or @kbd{C-r} to finish editing the string and search for it. - -@node Error in Isearch -@subsection Errors in Incremental Search - - If your string is not found at all, the echo area says @samp{Failing -I-Search}, and the cursor moves past the place where Emacs found as -much of your string as it could. Thus, if you search for @samp{FOOT}, -and there is no @samp{FOOT}, you might see the cursor after the -@samp{FOO} in @samp{FOOL}. In the echo area, the part of the search -string that failed to match is highlighted using the face -@code{isearch-fail}. - - At this point, there are several things you can do. If your string -was mistyped, you can use @key{DEL} to erase some of it and correct -it. If you like the place you have found, you can type @key{RET} to -remain there. Or you can type @kbd{C-g}, which removes from the -search string the characters that could not be found (the @samp{T} in -@samp{FOOT}), leaving those that were found (the @samp{FOO} in -@samp{FOOT}). A second @kbd{C-g} at that point cancels the search -entirely, returning point to where it was when the search started. - -@cindex quitting (in search) -@kindex C-g @r{(Incremental search)} - The quit command, @kbd{C-g}, does special things during searches; -just what it does depends on the status of the search. If the search -has found what you specified and is waiting for input, @kbd{C-g} -cancels the entire search, moving the cursor back to where you started -the search. If @kbd{C-g} is typed when there are characters in the -search string that have not been found---because Emacs is still -searching for them, or because it has failed to find them---then the -search string characters which have not been found are discarded from -the search string. With them gone, the search is now successful and -waiting for more input, so a second @kbd{C-g} will cancel the entire -search. - -@node Special Isearch -@subsection Special Input for Incremental Search - - Some of the characters you type during incremental search have -special effects. - -@cindex lax space matching -@kindex M-s SPC @r{(Incremental search)} -@kindex SPC @r{(Incremental search)} -@findex isearch-toggle-lax-whitespace -@vindex search-whitespace-regexp - By default, incremental search performs @dfn{lax space matching}: -each space, or sequence of spaces, matches any sequence of one or more -spaces in the text. Hence, @samp{foo bar} matches @samp{foo bar}, -@samp{foo bar}, @samp{foo bar}, and so on (but not @samp{foobar}). -More precisely, Emacs matches each sequence of space characters in the -search string to a regular expression specified by the variable -@code{search-whitespace-regexp}. For example, to make spaces match -sequences of newlines as well as spaces, set it to -@samp{"[[:space:]\n]+"}. - - To toggle lax space matching, type @kbd{M-s @key{SPC}} -(@code{isearch-toggle-lax-whitespace}). To disable this feature -entirely, change @code{search-whitespace-regexp} to @code{nil}; then -each space in the search string matches exactly one space. - - If the search string you entered contains only lower-case letters, -the search is case-insensitive; as long as an upper-case letter exists -in the search string, the search becomes case-sensitive. If you -delete the upper-case character from the search string, it ceases to -have this effect. @xref{Search Case}. - -@cindex invisible text, searching for -@kindex M-s i @r{(Incremental search)} -@findex isearch-toggle-invisible - To toggle whether or not invisible text is searched, type -@kbd{M-s i} (@code{isearch-toggle-invisible}). @xref{Outline Search}. - - To search for a newline character, type @kbd{C-j}. - - To search for non-@acronym{ASCII} characters, use one of the -following methods: - -@itemize @bullet -@item -Type @kbd{C-q}, followed by a non-graphic character or a sequence of -octal digits. This adds a character to the search string, similar to -inserting into a buffer using @kbd{C-q} (@pxref{Inserting Text}). For -example, @kbd{C-q C-s} during incremental search adds the -@samp{control-S} character to the search string. - -@item -Type @kbd{C-x 8 @key{RET}}, followed by a Unicode name or code-point. -This adds the specified character into the search string, similar to -the usual @code{insert-char} command (@pxref{Inserting Text}). - -@item -Use an input method (@pxref{Input Methods}). If an input method is -enabled in the current buffer when you start the search, you can use -it in the search string also. While typing the search string, you can -toggle the input method with @kbd{C-\} -(@code{isearch-toggle-input-method}). You can also turn on a -non-default input method with @kbd{C-^} -(@code{isearch-toggle-specified-input-method}), which prompts for the -name of the input method. When an input method is active during -incremental search, the search prompt includes the input method -mnemonic, like this: - -@example -I-search [@var{im}]: -@end example - -@noindent -@findex isearch-toggle-input-method -@findex isearch-toggle-specified-input-method -where @var{im} is the mnemonic of the active input method. Any input -method you enable during incremental search remains enabled in the -current buffer afterwards. -@end itemize - -@kindex M-% @r{(Incremental search)} - Typing @kbd{M-%} in incremental search invokes @code{query-replace} -or @code{query-replace-regexp} (depending on search mode) with the -current search string used as the string to replace. A negative -prefix argument means to replace backward. @xref{Query Replace}. - -@kindex M-TAB @r{(Incremental search)} - Typing @kbd{M-@key{TAB}} in incremental search invokes -@code{isearch-complete}, which attempts to complete the search string -using the search ring as a list of completion alternatives. -@xref{Completion}. In many operating systems, the @kbd{M-@key{TAB}} -key sequence is captured by the window manager; you then need to -rebind @code{isearch-complete} to another key sequence if you want to -use it (@pxref{Rebinding}). - -@vindex isearch-mode-map - When incremental search is active, you can type @kbd{C-h C-h} to -access interactive help options, including a list of special key -bindings. These key bindings are part of the keymap -@code{isearch-mode-map} (@pxref{Keymaps}). - -@node Isearch Yank -@subsection Isearch Yanking - -@kindex C-y @r{(Incremental search)} -@kindex M-y @r{(Incremental search)} -@findex isearch-yank-kill -@findex isearch-yank-pop - Within incremental search, @kbd{C-y} (@code{isearch-yank-kill}) -appends the current kill to the search string. @kbd{M-y} -(@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that -appended text with an earlier kill, similar to the usual @kbd{M-y} -(@code{yank-pop}) command (@pxref{Yanking}). @kbd{Mouse-2} appends -the current X selection (@pxref{Primary Selection}). - -@kindex C-w @r{(Incremental search)} -@findex isearch-yank-word-or-char - @kbd{C-w} (@code{isearch-yank-word-or-char}) appends the next -character or word at point to the search string. This is an easy way -to search for another occurrence of the text at point. (The decision -of whether to copy a character or a word is heuristic.) - -@kindex M-s C-e @r{(Incremental search)} -@findex isearch-yank-line - Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest -of the current line to the search string. If point is already at the -end of a line, it appends the next line. With a prefix argument -@var{n}, it appends the next @var{n} lines. - - If the search is currently case-insensitive, both @kbd{C-w} and -@kbd{M-s C-e} convert the text they copy to lower case, so that the -search remains case-insensitive. - -@kindex C-M-w @r{(Incremental search)} -@kindex C-M-y @r{(Incremental search)} -@findex isearch-del-char -@findex isearch-yank-char - @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character -from the search string, and @kbd{C-M-y} (@code{isearch-yank-char}) -appends the character after point to the search string. An -alternative method to add the character after point is to enter the -minibuffer with @kbd{M-e} (@pxref{Repeat Isearch}) and type @kbd{C-f} -at the end of the search string in the minibuffer. - -@node Not Exiting Isearch -@subsection Not Exiting Incremental Search - -This subsection describes two categories of commands which you can -type without exiting the current incremental search, even though they -are not themselves part of incremental search. - -@table @asis -@item Prefix Arguments -@vindex isearch-allow-prefix - In incremental search, when you enter a prefix argument -(@pxref{Arguments}), by default it will apply either to the next -action in the search or to the command that exits the search. - - In previous versions of Emacs, entering a prefix argument always -terminated the search. You can revert to this behavior by setting the -variable @code{isearch-allow-prefix} to @code{nil}. - - When @code{isearch-allow-scroll} is non-@code{nil} (see below), -prefix arguments always have the default behavior described above. - -@item Scrolling Commands -@vindex isearch-allow-scroll - Normally, scrolling commands exit incremental search. If you change -the variable @code{isearch-allow-scroll} to a non-@code{nil} value, -that enables the use of the scroll-bar, as well as keyboard scrolling -commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}). -This applies only to calling these commands via their bound key -sequences---typing @kbd{M-x} will still exit the search. You can give -prefix arguments to these commands in the usual way. This feature -won't let you scroll the current match out of visibility, however. - - The @code{isearch-allow-scroll} feature also affects some other -commands, such as @kbd{C-x 2} (@code{split-window-below}) and @kbd{C-x -^} (@code{enlarge-window}), which don't exactly scroll but do affect -where the text appears on the screen. It applies to any command whose -name has a non-@code{nil} @code{isearch-scroll} property. So you can -control which commands are affected by changing these properties. - - For example, to make @kbd{C-h l} usable within an incremental search -in all future Emacs sessions, use @kbd{C-h c} to find what command it -runs (@pxref{Key Help}), which is @code{view-lossage}. Then you can -put the following line in your init file (@pxref{Init File}): - -@example -(put 'view-lossage 'isearch-scroll t) -@end example - -@noindent -This feature can be applied to any command that doesn't permanently -change point, the buffer contents, the match data, the current buffer, -or the selected window and frame. The command must not itself attempt -an incremental search. -@end table - -@node Isearch Minibuffer -@subsection Searching the Minibuffer -@cindex minibuffer history, searching - -If you start an incremental search while the minibuffer is active, -Emacs searches the contents of the minibuffer. Unlike searching an -ordinary buffer, the search string is not shown in the echo area, -because that is used to display the minibuffer. - -If an incremental search fails in the minibuffer, it tries searching -the minibuffer history. @xref{Minibuffer History}. You can visualize -the minibuffer and its history as a series of ``pages'', with the -earliest history element on the first page and the current minibuffer -on the last page. A forward search, @kbd{C-s}, searches forward to -later pages; a reverse search, @kbd{C-r}, searches backwards to -earlier pages. Like in ordinary buffer search, a failing search can -wrap around, going from the last page to the first page or vice versa. - -When the current match is on a history element, that history element -is pulled into the minibuffer. If you exit the incremental search -normally (e.g., by typing @key{RET}), it remains in the minibuffer -afterwards. Canceling the search, with @kbd{C-g}, restores the -contents of the minibuffer when you began the search. - -@node Nonincremental Search -@section Nonincremental Search -@cindex nonincremental search - - Emacs also has conventional nonincremental search commands, which require -you to type the entire search string before searching begins. - -@table @kbd -@item C-s @key{RET} @var{string} @key{RET} -Search for @var{string}. -@item C-r @key{RET} @var{string} @key{RET} -Search backward for @var{string}. -@end table - - To start a nonincremental search, first type @kbd{C-s @key{RET}}. -This enters the minibuffer to read the search string; terminate the -string with @key{RET}, and then the search takes place. If the string -is not found, the search command signals an error. - -@findex search-forward -@findex search-backward - When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental -search as usual. That command is specially programmed to invoke the -command for nonincremental search, @code{search-forward}, if the -string you specify is empty. (Such an empty argument would otherwise -be useless.) @kbd{C-r @key{RET}} does likewise, invoking the command -@code{search-backward}. - -@node Word Search -@section Word Search -@cindex word search - - A @dfn{word search} finds a sequence of words without regard to the -type of punctuation between them. For instance, if you enter a search -string that consists of two words separated by a single space, the -search matches any sequence of those two words separated by one or -more spaces, newlines, or other punctuation characters. This is -particularly useful for searching text documents, because you don't -have to worry whether the words you are looking for are separated by -newlines or spaces. - -@table @kbd -@item M-s w -If incremental search is active, toggle word search mode -(@code{isearch-toggle-word}); otherwise, begin an incremental forward -word search (@code{isearch-forward-word}). -@item M-s w @key{RET} @var{words} @key{RET} -Search for @var{words}, using a forward nonincremental word search. -@item M-s w C-r @key{RET} @var{words} @key{RET} -Search backward for @var{words}, using a nonincremental word search. -@end table - -@kindex M-s w -@findex isearch-forward-word - To begin a forward incremental word search, type @kbd{M-s w}. If -incremental search is not already active, this runs the command -@code{isearch-forward-word}. If incremental search is already active -(whether a forward or backward search), @kbd{M-s w} switches to a word -search while keeping the direction of the search and the current -search string unchanged. You can toggle word search back off by -typing @kbd{M-s w} again. - -@findex word-search-forward -@findex word-search-backward - To begin a nonincremental word search, type @kbd{M-s w @key{RET}} -for a forward search, or @kbd{M-s w C-r @key{RET}} for a backward search. -These run the commands @code{word-search-forward} and -@code{word-search-backward} respectively. - - Incremental and nonincremental word searches differ slightly in the -way they find a match. In a nonincremental word search, each word in -the search string must exactly match a whole word. In an incremental -word search, the matching is more lax: while you are typing the search -string, its first and last words need not match whole words. This is -so that the matching can proceed incrementally as you type. This -additional laxity does not apply to the lazy highlight, which always -matches whole words. - -@node Symbol Search -@section Symbol Search -@cindex symbol search - - A @dfn{symbol search} is much like an ordinary search, except that -the boundaries of the search must match the boundaries of a symbol. -The meaning of @dfn{symbol} in this context depends on the major mode, -and usually refers to a source code token, such as a Lisp symbol in -Emacs Lisp mode. For instance, if you perform an incremental symbol -search for the Lisp symbol @code{forward-word}, it would not match -@code{isearch-forward-word}. This feature is thus mainly useful for -searching source code. - -@table @kbd -@item M-s _ -If incremental search is active, toggle symbol search mode -(@code{isearch-toggle-symbol}); otherwise, begin an incremental -forward symbol search (@code{isearch-forward-symbol}). -@item M-s . -Start a symbol incremental search forward with the symbol found near -point added to the search string initially. -@item M-s _ @key{RET} @var{symbol} @key{RET} -Search forward for @var{symbol}, nonincrementally. -@item M-s _ C-r @key{RET} @var{symbol} @key{RET} -Search backward for @var{symbol}, nonincrementally. -@end table - -@kindex M-s _ -@kindex M-s . -@findex isearch-forward-symbol -@findex isearch-forward-symbol-at-point - To begin a forward incremental symbol search, type @kbd{M-s _} (or -@kbd{M-s .} if the symbol to search is near point). If incremental -search is not already active, this runs the command -@code{isearch-forward-symbol}. If incremental search is already -active, @kbd{M-s _} switches to a symbol search, preserving the -direction of the search and the current search string; you can disable -symbol search by typing @kbd{M-s _} again. In incremental symbol -search, only the beginning of the search string is required to match -the beginning of a symbol. - - To begin a nonincremental symbol search, type @kbd{M-s _ @key{RET}} -for a forward search, or @kbd{M-s _ C-r @key{RET}} or a backward -search. In nonincremental symbol searches, the beginning and end of -the search string are required to match the beginning and end of a -symbol, respectively. - -@node Regexp Search -@section Regular Expression Search -@cindex regexp search -@cindex search for a regular expression - - A @dfn{regular expression} (or @dfn{regexp} for short) is a pattern -that denotes a class of alternative strings to match. Emacs -provides both incremental and nonincremental ways to search for a -match for a regexp. The syntax of regular expressions is explained in -the next section. - -@table @kbd -@item C-M-s -Begin incremental regexp search (@code{isearch-forward-regexp}). -@item C-M-r -Begin reverse incremental regexp search (@code{isearch-backward-regexp}). -@end table - -@kindex C-M-s -@findex isearch-forward-regexp -@kindex C-M-r -@findex isearch-backward-regexp - Incremental search for a regexp is done by typing @kbd{C-M-s} -(@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a -prefix argument (whose value does not matter), or by typing @kbd{M-r} -within a forward incremental search. This command reads a -search string incrementally just like @kbd{C-s}, but it treats the -search string as a regexp rather than looking for an exact match -against the text in the buffer. Each time you add text to the search -string, you make the regexp longer, and the new regexp is searched -for. To search backward for a regexp, use @kbd{C-M-r} -(@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, -or @kbd{M-r} within a backward incremental search. - - All of the special key sequences in an ordinary incremental search -do similar things in an incremental regexp search. For instance, -typing @kbd{C-s} immediately after starting the search retrieves the -last incremental search regexp used and searches forward for it. -Incremental regexp and non-regexp searches have independent defaults. -They also have separate search rings, which you can access with -@kbd{M-p} and @kbd{M-n}. - - Unlike ordinary incremental search, incremental regexp search -do not use lax space matching by default. To toggle this feature -use @kbd{M-s @key{SPC}} (@code{isearch-toggle-lax-whitespace}). -Then any @key{SPC} typed in incremental regexp search will match -any sequence of one or more whitespace characters. The variable -@code{search-whitespace-regexp} specifies the regexp for the lax -space matching. @xref{Special Isearch}. - - In some cases, adding characters to the regexp in an incremental -regexp search can make the cursor move back and start again. For -example, if you have searched for @samp{foo} and you add @samp{\|bar}, -the cursor backs up in case the first @samp{bar} precedes the first -@samp{foo}. @xref{Regexps}. - - Forward and backward regexp search are not symmetrical, because -regexp matching in Emacs always operates forward, starting with the -beginning of the regexp. Thus, forward regexp search scans forward, -trying a forward match at each possible starting position. Backward -regexp search scans backward, trying a forward match at each possible -starting position. These search methods are not mirror images. - -@findex re-search-forward -@findex re-search-backward - Nonincremental search for a regexp is done with the commands -@code{re-search-forward} and @code{re-search-backward}. You can -invoke these with @kbd{M-x}, or by way of incremental regexp search -with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}. - - If you use the incremental regexp search commands with a prefix -argument, they perform ordinary string search, like -@code{isearch-forward} and @code{isearch-backward}. @xref{Incremental -Search}. - -@node Regexps -@section Syntax of Regular Expressions -@cindex syntax of regexps -@cindex regular expression -@cindex regexp - - This manual describes regular expression features that users -typically use. @xref{Regular Expressions,,, elisp, The Emacs Lisp -Reference Manual}, for additional features used mainly in Lisp -programs. - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are @dfn{ordinary}. An ordinary -character matches that same character and nothing else. The special -characters are @samp{$^.*+?[\}. The character @samp{]} is special if -it ends a character alternative (see later). The character @samp{-} -is special inside a character alternative. Any other character -appearing in a regular expression is ordinary, unless a @samp{\} -precedes it. (When you use regular expressions in a Lisp program, -each @samp{\} must be doubled, see the example near the end of this -section.) - - For example, @samp{f} is not a special character, so it is ordinary, and -therefore @samp{f} is a regular expression that matches the string -@samp{f} and no other string. (It does @emph{not} match the string -@samp{ff}.) Likewise, @samp{o} is a regular expression that matches -only @samp{o}. (When case distinctions are being ignored, these regexps -also match @samp{F} and @samp{O}, but we consider this a generalization -of ``the same string'', rather than an exception.) - - Any two regular expressions @var{a} and @var{b} can be concatenated. -The result is a regular expression which matches a string if @var{a} -matches some amount of the beginning of that string and @var{b} -matches the rest of the string. For example, concatenating the -regular expressions @samp{f} and @samp{o} gives the regular expression -@samp{fo}, which matches only the string @samp{fo}. Still trivial. -To do something nontrivial, you need to use one of the special -characters. Here is a list of them. - -@table @asis -@item @kbd{.}@: @r{(Period)} -is a special character that matches any single character except a -newline. For example, the regular expressions @samp{a.b} matches any -three-character string that begins with @samp{a} and ends with -@samp{b}. - -@item @kbd{*} -is not a construct by itself; it is a postfix operator that means to -match the preceding regular expression repetitively any number of -times, as many times as possible. Thus, @samp{o*} matches any number -of @samp{o}s, including no @samp{o}s. - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating -@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. - -The matcher processes a @samp{*} construct by matching, immediately, -as many repetitions as can be found. Then it continues with the rest -of the pattern. If that fails, backtracking occurs, discarding some -of the matches of the @samp{*}-modified construct in case that makes -it possible to match the rest of the pattern. For example, in matching -@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first -tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. -With this choice, the rest of the regexp matches successfully. - -@item @kbd{+} -is a postfix operator, similar to @samp{*} except that it must match -the preceding expression at least once. Thus, @samp{ca+r} matches the -strings @samp{car} and @samp{caaaar} but not the string @samp{cr}, -whereas @samp{ca*r} matches all three strings. - -@item @kbd{?} -is a postfix operator, similar to @samp{*} except that it can match -the preceding expression either once or not at all. Thus, @samp{ca?r} -matches @samp{car} or @samp{cr}, and nothing else. - -@item @kbd{*?}, @kbd{+?}, @kbd{??} -@cindex non-greedy regexp matching -are non-@dfn{greedy} variants of the operators above. The normal -operators @samp{*}, @samp{+}, @samp{?} match as much as they can, as -long as the overall regexp can still match. With a following -@samp{?}, they will match as little as possible. - -Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a} -and the string @samp{abbbb}; but if you try to match them both against -the text @samp{abbb}, @samp{ab*} will match it all (the longest valid -match), while @samp{ab*?} will match just @samp{a} (the shortest -valid match). - -Non-greedy operators match the shortest possible string starting at a -given starting point; in a forward search, though, the earliest -possible starting point for match is always the one chosen. Thus, if -you search for @samp{a.*?$} against the text @samp{abbab} followed by -a newline, it matches the whole string. Since it @emph{can} match -starting at the first @samp{a}, it does. - -@item @kbd{\@{@var{n}\@}} -is a postfix operator specifying @var{n} repetitions---that is, the -preceding regular expression must match exactly @var{n} times in a -row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and -nothing else. - -@item @kbd{\@{@var{n},@var{m}\@}} -is a postfix operator specifying between @var{n} and @var{m} -repetitions---that is, the preceding regular expression must match at -least @var{n} times, but no more than @var{m} times. If @var{m} is -omitted, then there is no upper limit, but the preceding regular -expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is -equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to -@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. - -@item @kbd{[ @dots{} ]} -is a @dfn{character set}, beginning with @samp{[} and terminated by -@samp{]}. - -In the simplest case, the characters between the two brackets are what -this set can match. Thus, @samp{[ad]} matches either one @samp{a} or -one @samp{d}, and @samp{[ad]*} matches any string composed of just -@samp{a}s and @samp{d}s (including the empty string). It follows that -@samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr}, -@samp{caddaar}, etc. - -You can also include character ranges in a character set, by writing the -starting and ending characters with a @samp{-} between them. Thus, -@samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be -intermixed freely with individual characters, as in @samp{[a-z$%.]}, -which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or -period. - -You can also include certain special @dfn{character classes} in a -character set. A @samp{[:} and balancing @samp{:]} enclose a -character class inside a character alternative. For instance, -@samp{[[:alnum:]]} matches any letter or digit. @xref{Char Classes,,, -elisp, The Emacs Lisp Reference Manual}, for a list of character -classes. - -To include a @samp{]} in a character set, you must make it the first -character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To -include a @samp{-}, write @samp{-} as the first or last character of the -set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]} -and @samp{-}. - -To include @samp{^} in a set, put it anywhere but at the beginning of -the set. (At the beginning, it complements the set---see below.) - -When you use a range in case-insensitive search, you should write both -ends of the range in upper case, or both in lower case, or both should -be non-letters. The behavior of a mixed-case range such as @samp{A-z} -is somewhat ill-defined, and it may change in future Emacs versions. - -@item @kbd{[^ @dots{} ]} -@samp{[^} begins a @dfn{complemented character set}, which matches any -character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches -all characters @emph{except} @acronym{ASCII} letters and digits. - -@samp{^} is not special in a character set unless it is the first -character. The character following the @samp{^} is treated as if it -were first (in other words, @samp{-} and @samp{]} are not special there). - -A complemented character set can match a newline, unless newline is -mentioned as one of the characters not to match. This is in contrast to -the handling of regexps in programs such as @code{grep}. - -@item @kbd{^} -is a special character that matches the empty string, but only at the -beginning of a line in the text being matched. Otherwise it fails to -match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at -the beginning of a line. - -For historical compatibility reasons, @samp{^} can be used with this -meaning only at the beginning of the regular expression, or after -@samp{\(} or @samp{\|}. - -@item @kbd{$} -is similar to @samp{^} but matches only at the end of a line. Thus, -@samp{x+$} matches a string of one @samp{x} or more at the end of a line. - -For historical compatibility reasons, @samp{$} can be used with this -meaning only at the end of the regular expression, or before @samp{\)} -or @samp{\|}. - -@item @kbd{\} -has two functions: it quotes the special characters (including -@samp{\}), and it introduces additional special constructs. - -Because @samp{\} quotes special characters, @samp{\$} is a regular -expression that matches only @samp{$}, and @samp{\[} is a regular -expression that matches only @samp{[}, and so on. - -See the following section for the special constructs that begin -with @samp{\}. -@end table - - Note: for historical compatibility, special characters are treated as -ordinary ones if they are in contexts where their special meanings make no -sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is -no preceding expression on which the @samp{*} can act. It is poor practice -to depend on this behavior; it is better to quote the special character anyway, -regardless of where it appears. - -As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. - -@node Regexp Backslash -@section Backslash in Regular Expressions - - For the most part, @samp{\} followed by any character matches only -that character. However, there are several exceptions: two-character -sequences starting with @samp{\} that have special meanings. The -second character in the sequence is always an ordinary character when -used on its own. Here is a table of @samp{\} constructs. - -@table @kbd -@item \| -specifies an alternative. Two regular expressions @var{a} and @var{b} -with @samp{\|} in between form an expression that matches some text if -either @var{a} matches it or @var{b} matches it. It works by trying to -match @var{a}, and if that fails, by trying to match @var{b}. - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string. - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}. - -Full backtracking capability exists to handle multiple uses of @samp{\|}. - -@item \( @dots{} \) -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. -Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. - -@item -To enclose a complicated expression for the postfix operators @samp{*}, -@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches -@samp{bananana}, etc., with any (zero or more) number of @samp{na} -strings. - -@item -To record a matched substring for future reference. -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that is assigned as a -second meaning to the same @samp{\( @dots{} \)} construct. In practice -there is usually no conflict between the two meanings; when there is -a conflict, you can use a ``shy'' group. - -@item \(?: @dots{} \) -@cindex shy group, in regexp -specifies a ``shy'' group that does not record the matched substring; -you can't refer back to it with @samp{\@var{d}}. This is useful -in mechanically combining regular expressions, so that you -can add groups for syntactic purposes without interfering with -the numbering of the groups that are meant to be referred to. - -@item \@var{d} -@cindex back reference, in regexp -matches the same text that matched the @var{d}th occurrence of a -@samp{\( @dots{} \)} construct. This is called a @dfn{back -reference}. - -After the end of a @samp{\( @dots{} \)} construct, the matcher remembers -the beginning and end of the text matched by that construct. Then, -later on in the regular expression, you can use @samp{\} followed by the -digit @var{d} to mean ``match the same text matched the @var{d}th time -by the @samp{\( @dots{} \)} construct''. - -The strings matching the first nine @samp{\( @dots{} \)} constructs -appearing in a regular expression are assigned numbers 1 through 9 in -the order that the open-parentheses appear in the regular expression. -So you can use @samp{\1} through @samp{\9} to refer to the text matched -by the corresponding @samp{\( @dots{} \)} constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -If a particular @samp{\( @dots{} \)} construct matches more than once -(which can easily happen if it is followed by @samp{*}), only the last -match is recorded. - -@item \` -matches the empty string, but only at the beginning of the string or -buffer (or its accessible portion) being matched against. - -@item \' -matches the empty string, but only at the end of the string or buffer -(or its accessible portion) being matched against. - -@item \= -matches the empty string, but only at point. - -@item \b -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word. - -@samp{\b} matches at the beginning or end of the buffer -regardless of what text appears next to it. - -@item \B -matches the empty string, but @emph{not} at the beginning or -end of a word. - -@item \< -matches the empty string, but only at the beginning of a word. -@samp{\<} matches at the beginning of the buffer only if a -word-constituent character follows. - -@item \> -matches the empty string, but only at the end of a word. @samp{\>} -matches at the end of the buffer only if the contents end with a -word-constituent character. - -@item \w -matches any word-constituent character. The syntax table determines -which characters these are. @xref{Syntax Tables,, Syntax Tables, -elisp, The Emacs Lisp Reference Manual}. - -@item \W -matches any character that is not a word-constituent. - -@item \_< -matches the empty string, but only at the beginning of a symbol. -A symbol is a sequence of one or more symbol-constituent characters. -A symbol-constituent character is a character whose syntax is either -@samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the -buffer only if a symbol-constituent character follows. - -@item \_> -matches the empty string, but only at the end of a symbol. @samp{\_>} -matches at the end of the buffer only if the contents end with a -symbol-constituent character. - -@item \s@var{c} -matches any character whose syntax is @var{c}. Here @var{c} is a -character that designates a particular syntax class: thus, @samp{w} -for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.} -for ordinary punctuation, etc. @xref{Syntax Tables,, Syntax Tables, -elisp, The Emacs Lisp Reference Manual}. - -@item \S@var{c} -matches any character whose syntax is not @var{c}. - -@cindex categories of characters -@cindex characters which belong to a specific language -@findex describe-categories -@item \c@var{c} -matches any character that belongs to the category @var{c}. For -example, @samp{\cc} matches Chinese characters, @samp{\cg} matches -Greek characters, etc. For the description of the known categories, -type @kbd{M-x describe-categories @key{RET}}. - -@item \C@var{c} -matches any character that does @emph{not} belong to category -@var{c}. -@end table - - The constructs that pertain to words and syntax are controlled by -the setting of the syntax table. @xref{Syntax Tables,, Syntax Tables, -elisp, The Emacs Lisp Reference Manual}. - -@node Regexp Example -@section Regular Expression Example - - Here is an example of a regexp---similar to the regexp that Emacs -uses, by default, to recognize the end of a sentence, not including -the following space (i.e., the variable @code{sentence-end-base}): - -@example -@verbatim -[.?!][]\"')}]* -@end verbatim -@end example - -@noindent -This contains two parts in succession: a character set matching -period, @samp{?}, or @samp{!}, and a character set matching -close-brackets, quotes, or parentheses, repeated zero or more times. - -@node Search Case -@section Searching and Case - - Searches in Emacs normally ignore the case of the text they are -searching through, if you specify the text in lower case. Thus, if -you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo} -also match. Regexps, and in particular character sets, behave -likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or -@samp{B}. - - An upper-case letter anywhere in the incremental search string makes -the search case-sensitive. Thus, searching for @samp{Foo} does not find -@samp{foo} or @samp{FOO}. This applies to regular expression search as -well as to string search. The effect ceases if you delete the -upper-case letter from the search string. - -@vindex case-fold-search - If you set the variable @code{case-fold-search} to @code{nil}, then -all letters must match exactly, including case. This is a per-buffer -variable; altering the variable normally affects only the current buffer, -unless you change its default value. @xref{Locals}. -This variable applies to nonincremental searches also, including those -performed by the replace commands (@pxref{Replace}) and the minibuffer -history matching commands (@pxref{Minibuffer History}). - -@c isearch-toggle-case-fold - Typing @kbd{M-c} within an incremental search toggles the case -sensitivity of that search. The effect does not extend beyond the -current incremental search to the next one, but it does override the -effect of adding or removing an upper-case letter in the current -search. - - Several related variables control case-sensitivity of searching and -matching for specific commands or activities. For instance, -@code{tags-case-fold-search} controls case sensitivity for -@code{find-tag}. To find these variables, do @kbd{M-x -apropos-variable @key{RET} case-fold-search @key{RET}}. - -@node Replace -@section Replacement Commands -@cindex replacement -@cindex search-and-replace commands -@cindex string substitution -@cindex global substitution - - Emacs provides several commands for performing search-and-replace -operations. In addition to the simple @kbd{M-x replace-string} -command, there is @kbd{M-%} (@code{query-replace}), which presents -each occurrence of the pattern and asks you whether to replace it. - - The replace commands normally operate on the text from point to the -end of the buffer. When the region is active, they operate on it -instead (@pxref{Mark}). The basic replace commands replace one -@dfn{search string} (or regexp) with one @dfn{replacement string}. It -is possible to perform several replacements in parallel, using the -command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}). - -@vindex replace-lax-whitespace - Unlike incremental search, the replacement commands do not use lax -space matching (@pxref{Special Isearch}) by default. To enable lax -space matching for replacement, change the variable -@code{replace-lax-whitespace} to @code{t}. (This only affects how -Emacs finds the text to replace, not the replacement text.) - -@menu -* Unconditional Replace:: Replacing all matches for a string. -* Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. -* Query Replace:: How to use querying. -@end menu - -@node Unconditional Replace -@subsection Unconditional Replacement -@findex replace-string - -@table @kbd -@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} -Replace every occurrence of @var{string} with @var{newstring}. -@end table - - To replace every instance of @samp{foo} after point with @samp{bar}, -use the command @kbd{M-x replace-string} with the two arguments -@samp{foo} and @samp{bar}. Replacement happens only in the text after -point, so if you want to cover the whole buffer you must go to the -beginning first. All occurrences up to the end of the buffer are -replaced; to limit replacement to part of the buffer, activate the -region around that part. When the region is active, replacement is -limited to the region (@pxref{Mark}). - - When @code{replace-string} exits, it leaves point at the last -occurrence replaced. It adds the prior position of point (where the -@code{replace-string} command was issued) to the mark ring, without -activating the mark; use @kbd{C-u C-@key{SPC}} to move back there. -@xref{Mark Ring}. - - A prefix argument restricts replacement to matches that are -surrounded by word boundaries. - - @xref{Replacement and Case}, for details about case-sensitivity in -replace commands. - -@node Regexp Replace -@subsection Regexp Replacement -@findex replace-regexp - - The @kbd{M-x replace-string} command replaces exact matches for a -single string. The similar command @kbd{M-x replace-regexp} replaces -any match for a specified pattern. - -@table @kbd -@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} -Replace every match for @var{regexp} with @var{newstring}. -@end table - -@cindex back reference, in regexp replacement - In @code{replace-regexp}, the @var{newstring} need not be constant: -it can refer to all or part of what is matched by the @var{regexp}. -@samp{\&} in @var{newstring} stands for the entire match being -replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a -digit, stands for whatever matched the @var{d}th parenthesized -grouping in @var{regexp}. (This is called a ``back reference''.) -@samp{\#} refers to the count of replacements already made in this -command, as a decimal number. In the first replacement, @samp{\#} -stands for @samp{0}; in the second, for @samp{1}; and so on. For -example, - -@example -M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} -@end example - -@noindent -replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} -with @samp{cddr-safe}. - -@example -M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} -@end example - -@noindent -performs the inverse transformation. To include a @samp{\} in the -text to replace with, you must enter @samp{\\}. - - If you want to enter part of the replacement string by hand each -time, use @samp{\?} in the replacement string. Each replacement will -ask you to edit the replacement string in the minibuffer, putting -point where the @samp{\?} was. - - The remainder of this subsection is intended for specialized tasks -and requires knowledge of Lisp. Most readers can skip it. - - You can use Lisp expressions to calculate parts of the -replacement string. To do this, write @samp{\,} followed by the -expression in the replacement string. Each replacement calculates the -value of the expression and converts it to text without quoting (if -it's a string, this means using the string's contents), and uses it in -the replacement string in place of the expression itself. If the -expression is a symbol, one space in the replacement string after the -symbol name goes with the symbol name, so the value replaces them -both. - - Inside such an expression, you can use some special sequences. -@samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire -match as a string, and to a submatch as a string. @var{n} may be -multiple digits, and the value of @samp{\@var{n}} is @code{nil} if -subexpression @var{n} did not match. You can also use @samp{\#&} and -@samp{\#@var{n}} to refer to those matches as numbers (this is valid -when the match or submatch has the form of a numeral). @samp{\#} here -too stands for the number of already-completed replacements. - - Repeating our example to exchange @samp{x} and @samp{y}, we can thus -do it also this way: - -@example -M-x replace-regexp @key{RET} \(x\)\|y @key{RET} -\,(if \1 "y" "x") @key{RET} -@end example - - For computing replacement strings for @samp{\,}, the @code{format} -function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs -Lisp Reference Manual}). For example, to add consecutively numbered -strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are -already occupied), you can use - -@example -M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET} -\,(format "%-72sABC%05d" \& \#) @key{RET} -@end example - -@node Replacement and Case -@subsection Replace Commands and Case - - If the first argument of a replace command is all lower case, the -command ignores case while searching for occurrences to -replace---provided @code{case-fold-search} is non-@code{nil}. If -@code{case-fold-search} is set to @code{nil}, case is always significant -in all searches. - -@vindex case-replace - In addition, when the @var{newstring} argument is all or partly lower -case, replacement commands try to preserve the case pattern of each -occurrence. Thus, the command - -@example -M-x replace-string @key{RET} foo @key{RET} bar @key{RET} -@end example - -@noindent -replaces a lower case @samp{foo} with a lower case @samp{bar}, an -all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with -@samp{Bar}. (These three alternatives---lower case, all caps, and -capitalized, are the only ones that @code{replace-string} can -distinguish.) - - If upper-case letters are used in the replacement string, they remain -upper case every time that text is inserted. If upper-case letters are -used in the first argument, the second argument is always substituted -exactly as given, with no case conversion. Likewise, if either -@code{case-replace} or @code{case-fold-search} is set to @code{nil}, -replacement is done without case conversion. - -@node Query Replace -@subsection Query Replace -@cindex query replace - -@table @kbd -@item M-% @var{string} @key{RET} @var{newstring} @key{RET} -Replace some occurrences of @var{string} with @var{newstring}. -@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET} -Replace some matches for @var{regexp} with @var{newstring}. -@end table - -@kindex M-% -@findex query-replace - If you want to change only some of the occurrences of @samp{foo} to -@samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}). -This command finds occurrences of @samp{foo} one by one, displays each -occurrence and asks you whether to replace it. Aside from querying, -@code{query-replace} works just like @code{replace-string} -(@pxref{Unconditional Replace}). In particular, it preserves case -provided @code{case-replace} is non-@code{nil}, as it normally is -(@pxref{Replacement and Case}). A numeric argument means to consider -only occurrences that are bounded by word-delimiter characters. A -negative prefix argument replaces backward. - -@kindex C-M-% -@findex query-replace-regexp - @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). -It works like @code{replace-regexp} except that it queries -like @code{query-replace}. - -@cindex faces for highlighting query replace - These commands highlight the current match using the face -@code{query-replace}. They highlight other matches using -@code{lazy-highlight} just like incremental search (@pxref{Incremental -Search}). By default, @code{query-replace-regexp} will show the -substituted replacement string for the current match in the -minibuffer. If you want to keep special sequences @samp{\&} and -@samp{\@var{n}} unexpanded, customize -@code{query-replace-show-replacement} variable. - - The characters you can type when you are shown a match for the string -or regexp are: - -@ignore @c Not worth it. -@kindex SPC @r{(query-replace)} -@kindex DEL @r{(query-replace)} -@kindex , @r{(query-replace)} -@kindex RET @r{(query-replace)} -@kindex . @r{(query-replace)} -@kindex ! @r{(query-replace)} -@kindex ^ @r{(query-replace)} -@kindex C-r @r{(query-replace)} -@kindex C-w @r{(query-replace)} -@kindex C-l @r{(query-replace)} -@end ignore - -@c WideCommands -@table @kbd -@item @key{SPC} -to replace the occurrence with @var{newstring}. - -@item @key{DEL} -to skip to the next occurrence without replacing this one. - -@item , @r{(Comma)} -to replace this occurrence and display the result. You are then asked -for another input character to say what to do next. Since the -replacement has already been made, @key{DEL} and @key{SPC} are -equivalent in this situation; both move to the next occurrence. - -You can type @kbd{C-r} at this point (see below) to alter the replaced -text. You can also type @kbd{C-x u} to undo the replacement; this exits -the @code{query-replace}, so if you want to do further replacement you -must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart -(@pxref{Repetition}). - -@item @key{RET} -to exit without doing any more replacements. - -@item .@: @r{(Period)} -to replace this occurrence and then exit without searching for more -occurrences. - -@item ! -to replace all remaining occurrences without asking again. - -@item Y @r{(Upper-case)} -to replace all remaining occurrences in all remaining buffers in -multi-buffer replacements (like the Dired @key{Q} command that performs -query replace on selected files). It answers this question and all -subsequent questions in the series with "yes", without further -user interaction. - -@item N @r{(Upper-case)} -to skip to the next buffer in multi-buffer replacements without -replacing remaining occurrences in the current buffer. It answers -this question "no", gives up on the questions for the current buffer, -and continues to the next buffer in the sequence. - -@item ^ -to go back to the position of the previous occurrence (or what used to -be an occurrence), in case you changed it by mistake or want to -reexamine it. - -@item C-r -to enter a recursive editing level, in case the occurrence needs to be -edited rather than just replaced with @var{newstring}. When you are -done, exit the recursive editing level with @kbd{C-M-c} to proceed to -the next occurrence. @xref{Recursive Edit}. - -@item C-w -to delete the occurrence, and then enter a recursive editing level as in -@kbd{C-r}. Use the recursive edit to insert text to replace the deleted -occurrence of @var{string}. When done, exit the recursive editing level -with @kbd{C-M-c} to proceed to the next occurrence. - -@item e -to edit the replacement string in the minibuffer. When you exit the -minibuffer by typing @key{RET}, the minibuffer contents replace the -current occurrence of the pattern. They also become the new -replacement string for any further occurrences. - -@item C-l -to redisplay the screen. Then you must type another character to -specify what to do with this occurrence. - -@item C-h -to display a message summarizing these options. Then you must type -another character to specify what to do with this occurrence. -@end table - - Some other characters are aliases for the ones listed above: @kbd{y}, -@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and -@key{RET}. - - Aside from this, any other character exits the @code{query-replace}, -and is then reread as part of a key sequence. Thus, if you type -@kbd{C-k}, it exits the @code{query-replace} and then kills to end of -line. - - To restart a @code{query-replace} once it is exited, use @kbd{C-x -@key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it -used the minibuffer to read its arguments. @xref{Repetition, C-x ESC -ESC}. - -@cindex invisible text, and query-replace - The option @code{search-invisible} determines how @code{query-replace} -treats invisible text. @xref{Outline Search}. - - @xref{Operating on Files}, for the Dired @kbd{Q} command which -performs query replace on selected files. See also @ref{Transforming -File Names}, for Dired commands to rename, copy, or link files by -replacing regexp matches in file names. - -@node Other Repeating Search -@section Other Search-and-Loop Commands - - Here are some other commands that find matches for a regular -expression. They all ignore case in matching, if the pattern contains -no upper-case letters and @code{case-fold-search} is non-@code{nil}. -Aside from @code{occur} and its variants, all operate on the text from -point to the end of the buffer, or on the region if it is active. - -@findex list-matching-lines -@findex occur -@findex multi-occur -@findex multi-occur-in-matching-buffers -@findex how-many -@findex flush-lines -@findex keep-lines - -@table @kbd -@item M-x multi-isearch-buffers -Prompt for one or more buffer names, ending with @key{RET}; then, -begin a multi-buffer incremental search in those buffers. (If the -search fails in one buffer, the next @kbd{C-s} tries searching the -next specified buffer, and so forth.) With a prefix argument, prompt -for a regexp and begin a multi-buffer incremental search in buffers -matching that regexp. - -@item M-x multi-isearch-buffers-regexp -This command is just like @code{multi-isearch-buffers}, except it -performs an incremental regexp search. - -@cindex Occur mode -@cindex mode, Occur -@item M-x occur -Prompt for a regexp, and display a list showing each line in the -buffer that contains a match for it. To limit the search to part of -the buffer, narrow to that part (@pxref{Narrowing}). A numeric -argument @var{n} specifies that @var{n} lines of context are to be -displayed before and after each matching line. - -@kindex RET @r{(Occur mode)} -@kindex o @r{(Occur mode)} -@kindex C-o @r{(Occur mode)} -In the @file{*Occur*} buffer, you can click on each entry, or move -point there and type @key{RET}, to visit the corresponding position in -the buffer that was searched. @kbd{o} and @kbd{C-o} display the match -in another window; @kbd{C-o} does not select it. Alternatively, you -can use the @kbd{C-x `} (@code{next-error}) command to visit the -occurrences one by one (@pxref{Compilation Mode}). - -@cindex Occur Edit mode -@cindex mode, Occur Edit -Typing @kbd{e} in the @file{*Occur*} buffer switches to Occur Edit -mode, in which edits made to the entries are also applied to the text -in the originating buffer. Type @kbd{C-c C-c} to return to Occur -mode. - -The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x -occur}. - -@kindex M-s o -@item M-s o -Run @code{occur} using the search string of the last incremental -string search. You can also run @kbd{M-s o} when an incremental -search is active; this uses the current search string. - -@item M-x multi-occur -This command is just like @code{occur}, except it is able to search -through multiple buffers. It asks you to specify the buffer names one -by one. - -@item M-x multi-occur-in-matching-buffers -This command is similar to @code{multi-occur}, except the buffers to -search are specified by a regular expression that matches visited file -names. With a prefix argument, it uses the regular expression to -match buffer names instead. - -@item M-x how-many -Prompt for a regexp, and print the number of matches for it in the -buffer after point. If the region is active, this operates on the -region instead. - -@item M-x flush-lines -Prompt for a regexp, and delete each line that contains a match for -it, operating on the text after point. This command deletes the -current line if it contains a match starting after point. If the -region is active, it operates on the region instead; if a line -partially contained in the region contains a match entirely contained -in the region, it is deleted. - -If a match is split across lines, @code{flush-lines} deletes all those -lines. It deletes the lines before starting to look for the next -match; hence, it ignores a match starting on the same line at which -another match ended. - -@item M-x keep-lines -Prompt for a regexp, and delete each line that @emph{does not} contain -a match for it, operating on the text after point. If point is not at -the beginning of a line, this command always keeps the current line. -If the region is active, the command operates on the region instead; -it never deletes lines that are only partially contained in the region -(a newline that ends a line counts as part of that line). - -If a match is split across lines, this command keeps all those lines. -@end table diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi deleted file mode 100644 index 02b38cc6748..00000000000 --- a/doc/emacs/sending.texi +++ /dev/null @@ -1,697 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Sending Mail -@chapter Sending Mail -@cindex sending mail -@cindex mail -@cindex email -@cindex message - -@kindex C-x m -@findex compose-mail - To send an email message from Emacs, type @kbd{C-x m}. This -switches to a buffer named @file{*unsent mail*}, where you can edit -the text and headers of the message. When done, type @kbd{C-c C-s} or -@kbd{C-c C-c} to send it. - -@table @kbd -@item C-x m -Begin composing mail (@code{compose-mail}). -@item C-x 4 m -Likewise, in another window (@code{compose-mail-other-window}). -@item C-x 5 m -Likewise, but in a new frame (@code{compose-mail-other-frame}). -@item C-c C-s -In the mail buffer, send the message (@code{message-send}). -@item C-c C-c -In the mail buffer, send the message and bury the buffer -(@code{message-send-and-exit}). -@end table - - The mail buffer is an ordinary Emacs buffer, so you can switch to -other buffers while composing the mail. If you want to send another -mail before finishing the current one, type @kbd{C-x m} again to open -a new mail buffer whose name has a different numeric suffix -(@pxref{Misc Buffer}). If you invoke the command with a prefix -argument, @w{@kbd{C-u C-x m}}, Emacs switches back to the last mail -buffer, and asks if you want to erase the message in that buffer; if -you answer no, this lets you pick up editing the message where you -left off. - -@kindex C-x 4 m -@findex compose-mail-other-window -@kindex C-x 5 m -@findex compose-mail-other-frame - The command @kbd{C-x 4 m} (@code{compose-mail-other-window}) does -the same as @kbd{C-x m}, except it displays the mail buffer in a -different window. The command @kbd{C-x 5 m} -(@code{compose-mail-other-frame}) does it in a new frame. - - When you type @kbd{C-c C-c} or @kbd{C-c C-s} to send the mail, Emacs -may ask you how it should deliver the mail---either directly via SMTP, -or using some other method. @xref{Mail Sending}, for details. - -@menu -* Format: Mail Format. Format of a mail message. -* Headers: Mail Headers. Details of some standard mail header fields. -* Aliases: Mail Aliases. Abbreviating and grouping mail addresses. -* Commands: Mail Commands. Special commands for editing mail being composed. -* Signature: Mail Signature. Adding a signature to every message. -* Amuse: Mail Amusements. Distracting the NSA; adding fortune messages. -* Methods: Mail Methods. Using alternative mail-composition methods. -@end menu - -@node Mail Format -@section The Format of the Mail Buffer - - Here is an example of the contents of a mail buffer: - -@example -To: subotai@@example.org -CC: mongol.soldier@@example.net, rms@@gnu.org -Subject: Re: What is best in life? -From: conan@@example.org ---text follows this line-- -To crush your enemies, see them driven before you, and to -hear the lamentation of their women. -@end example - -@noindent -At the top of the mail buffer is a set of @dfn{header fields}, which -are used for specifying information about the email's recipient(s), -subject, and so on. The above buffer contains header fields for -@samp{To}, @samp{Cc}, @samp{Subject}, and @samp{From}. Some header -fields are automatically pre-initialized in the mail buffer, when -appropriate. - - The line that says @samp{--text follows this line--} separates the -header fields from the @dfn{body} (or @dfn{text}) of the message. -Everything above that line is treated as part of the headers; -everything below it is treated as the body. The delimiter line itself -does not appear in the message actually sent. - - You can insert and edit header fields using ordinary editing -commands. @xref{Header Editing}, for commands specific to editing -header fields. Certain headers, such as @samp{Date} and -@samp{Message-Id}, are normally omitted from the mail buffer and are -created automatically when the message is sent. - -@node Mail Headers -@section Mail Header Fields -@cindex headers (of mail message) - - A header field in the mail buffer starts with a field name at the -beginning of a line, terminated by a colon. Upper and lower case are -equivalent in field names. After the colon and optional whitespace -comes the contents of the field. - - You can use any name you like for a header field, but normally -people use only standard field names with accepted meanings. - -@vindex user-full-name -@vindex user-mail-address - The @samp{From} header field identifies the person sending the email -(i.e., you). This should be a valid mailing address, as replies are -normally sent there. The default contents of this header field are -computed from the variables @code{user-full-name} (which specifies -your full name) and @code{user-mail-address} (your email address). On -some operating systems, Emacs initializes these two variables using -environment variables (@pxref{General Variables}). If this -information is unavailable or wrong, you should customize the -variables yourself (@pxref{Easy Customization}). - -@vindex mail-from-style - The value of the variable @code{mail-from-style} specifies how to -format the contents of the @samp{From} field: - -@table @asis -@item @code{nil} -Use just the address, as in @samp{king@@grassland.com}. -@item @code{parens} -Use both address and full name, as in:@* -@samp{king@@grassland.com (Elvis Parsley)}. -@item @code{angles} -Use both address and full name, as in:@* -@samp{Elvis Parsley }. -@item any other value -Use @code{angles} normally. But if the address must be ``quoted'' to -remain syntactically valid under the @code{angles} format but not -under the @code{parens} format, use @code{parens} instead. This is -the default. -@end table - - Apart from @samp{From}, here is a table of commonly-used fields: - -@table @samp -@item To -The mailing address(es) to which the message is addressed. To list -more than one address, use commas to separate them. - -@item Subject -The subject of the message. - -@item CC -Additional mailing address(es) to send the message to. This is like -@samp{To}, except that these readers should not regard the message as -directed at them. - -@item BCC -Additional mailing address(es) to send the message to, which should -not appear in the header of the message actually sent. ``BCC'' stands -for @dfn{blind carbon copies}. - -@item FCC -The name of a file, to which a copy of the sent message should be -appended. Emacs writes the message in mbox format, unless the file is -in Babyl format (used by Rmail before Emacs 23), in which case Emacs -writes in Babyl format. If an Rmail buffer is visiting the file, -Emacs updates it accordingly. To specify more than one file, use -several @samp{FCC} fields, with one file name in each field. - -@item Reply-to -An address to which replies should be sent, instead of @samp{From}. -This is used if, for some reason, your @samp{From} address cannot -receive replies. - -@item Mail-reply-to -This field takes precedence over @samp{Reply-to}. It is used because -some mailing lists set the @samp{Reply-to} field for their own -purposes (a somewhat controversial practice). - -@item Mail-followup-to -One of more address(es) to use as default recipient(s) for follow-up -messages. This is typically used when you reply to a message from a -mailing list that you are subscribed to, and want replies to go to the -list without sending an extra copy to you. - -@item In-reply-to -An identifier for the message you are replying to. Most mail readers -use this information to group related messages together. Normally, -this header is filled in automatically when you reply to a message in -any mail program built into Emacs. - -@item References -Identifiers for previous related messages. Like @samp{In-reply-to}, -this is normally filled in automatically for you. -@end table - -@noindent -The @samp{To}, @samp{CC}, and @samp{BCC} fields can appear any number -of times, and each such header field can contain multiple addresses, -separated by commas. This way, you can specify any number of places -to send the message. These fields can also have continuation lines: -one or more lines starting with whitespace, following the starting -line of the field, are considered part of the field. Here's an -example of a @samp{To} field with a continuation line: - -@example -@group -To: foo@@example.net, this@@example.net, - bob@@example.com -@end group -@end example - -@c There is also mail-specify-envelope-from and mail-envelope-from, but -@c these are probably not topics for the Emacs manual. - -@vindex mail-default-headers - You can direct Emacs to insert certain default headers into the mail -buffer by setting the variable @code{mail-default-headers} to a -string. Then @kbd{C-x m} inserts this string into the message -headers. For example, here is how to add a @samp{Reply-to} and -@samp{FCC} header to each message: - -@smallexample -(setq mail-default-headers - "Reply-to: foo@@example.com\nFCC: ~/Mail/sent") -@end smallexample - -@noindent -If the default header fields are not appropriate for a -particular message, edit them as necessary before sending the message. - -@node Mail Aliases -@section Mail Aliases -@cindex mail aliases -@cindex @file{.mailrc} file -@cindex mailrc file -@vindex mail-personal-alias-file - - You can define @dfn{mail aliases}, which are short mnemonic names -that stand for one or more mailing addresses. By default, mail -aliases are defined in the file @file{~/.mailrc}. You can specify a -different file name to use, by setting the variable -@code{mail-personal-alias-file}. - - To define an alias in @file{.mailrc}, write a line like this: - -@example -alias @var{nick} @var{fulladdresses} -@end example - -@noindent -This means that @var{nick} should expand into @var{fulladdresses}, -where @var{fulladdresses} can be either a single address, or multiple -addresses separated with spaces. For instance, to make @code{maingnu} -stand for @code{gnu@@gnu.org} plus a local address of your own, put in -this line: - -@example -alias maingnu gnu@@gnu.org local-gnu -@end example - -@noindent -If an address contains a space, quote the whole address with a pair of -double quotes, like this: - -@example -alias jsmith "John Q. Smith " -@end example - -@noindent -Note that you need not include double quotes around individual parts -of the address, such as the person's full name. Emacs puts them in if -they are needed. For instance, it inserts the above address as -@samp{"John Q. Smith" }. - - Emacs also recognizes ``include'' commands in @file{.mailrc}. They -look like this: - -@example -source @var{filename} -@end example - -@noindent -The @file{.mailrc} file is not unique to Emacs; many other -mail-reading programs use it for mail aliases, and it can contain -various other commands. However, Emacs ignores everything except -alias definitions and include commands. - -@findex mail-abbrev-insert-alias - Mail aliases expand as abbrevs---that is to say, as soon as you type -a word-separator character after an alias (@pxref{Abbrevs}). This -expansion takes place only within the @samp{To}, @samp{From}, -@samp{CC}, @samp{BCC}, and @samp{Reply-to} header fields (plus their -@samp{Resent-} variants); it does not take place in other header -fields, such as @samp{Subject}. - - You can also insert an aliased address directly, using the command -@kbd{M-x mail-abbrev-insert-alias}. This reads an alias name, with -completion, and inserts its definition at point. - -@node Mail Commands -@section Mail Commands -@cindex Message mode -@cindex mode, Message - - The default major mode for the @file{*mail*} buffer is called -Message mode. It behaves like Text mode in many ways, but provides -several additional commands on the @kbd{C-c} prefix, which make -editing a message more convenient. - - In this section, we will describe some of the most commonly-used -commands available in Message mode. -@ifnottex -Message mode also has its own manual, where its features are described -in greater detail. @xref{Top,,Message, message, Message}. -@end ifnottex - -@menu -* Mail Sending:: Commands to send the message. -* Header Editing:: Commands to move to header fields and edit them. -* Citing Mail:: Quoting a message you are replying to. -* Mail Misc:: Attachments, spell checking, etc. -@end menu - -@node Mail Sending -@subsection Mail Sending - -@table @kbd -@item C-c C-c -Send the message, and bury the mail buffer (@code{message-send-and-exit}). -@item C-c C-s -Send the message, and leave the mail buffer selected (@code{message-send}). -@end table - -@kindex C-c C-s @r{(Message mode)} -@kindex C-c C-c @r{(Message mode)} -@findex message-send -@vindex message-kill-buffer-on-exit - The usual command to send a message is @kbd{C-c C-c} -(@code{mail-send-and-exit}). This sends the message and then -``buries'' the mail buffer, putting it at the lowest priority for -reselection. If you want it to kill the mail buffer instead, change -the variable @code{message-kill-buffer-on-exit} to @code{t}. - -@findex message-send-and-exit - The command @kbd{C-c C-s} (@code{message-send}) sends the message -and leaves the buffer selected. Use this command if you want to -modify the message (perhaps with new recipients) and send it again. - -@vindex message-send-hook - Sending a message runs the hook @code{message-send-hook}. It also -marks the mail buffer as unmodified, except if the mail buffer is also -a file-visiting buffer (in that case, only saving the file does that, -and you don't get a warning if you try to send the same message -twice). - -@cindex SMTP -@cindex Feedmail -@cindex Sendmail -@cindex Mailclient -@vindex send-mail-function - The variable @code{send-mail-function} controls how the message is -delivered. Its value should be one of the following functions: - -@table @code -@item sendmail-query-once -Query for a delivery method (one of the other entries in this list), -and use that method for this message; then save the method to -@code{send-mail-function}, so that it is used for future deliveries. -This is the default, unless you have already set the variables for -sending mail via @code{smtpmail-send-it} (see below). - -@item smtpmail-send-it -Send mail through an external mail host, such as your -Internet service provider's outgoing SMTP mail server. If you have -not told Emacs how to contact the SMTP server, it prompts for this -information, which is saved in the @code{smtpmail-smtp-server} variable -and the file @file{~/.authinfo}. -@xref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}. - -@item sendmail-send-it -Send mail using the system's default @command{sendmail} program, or -equivalent. This requires the system to be set up for delivering mail -directly via SMTP. - -@item mailclient-send-it -Pass the mail buffer on to the system's designated mail client. See -the commentary section in the file @file{mailclient.el} for details. - -@item feedmail-send-it -This is similar to @code{sendmail-send-it}, but allows you to queue -messages for later sending. See the commentary section in the file -@file{feedmail.el} for details. -@end table - -@vindex sendmail-coding-system - When you send a message containing non-@acronym{ASCII} characters, -they need to be encoded with a coding system (@pxref{Coding Systems}). -Usually the coding system is specified automatically by your chosen -language environment (@pxref{Language Environments}). You can -explicitly specify the coding system for outgoing mail by setting the -variable @code{sendmail-coding-system} (@pxref{Recognize Coding}). If -the coding system thus determined does not handle the characters in a -particular message, Emacs asks you to select the coding system to use, -showing a list of possible coding systems. - -@node Header Editing -@subsection Mail Header Editing - - Message mode provides the following special commands to move to -particular header fields and to complete addresses in headers. - -@table @kbd -@item C-c C-f C-t -Move to the @samp{To} header (@code{message-goto-to}). -@item C-c C-f C-s -Move to the @samp{Subject} header (@code{message-goto-subject}). -@item C-c C-f C-c -Move to the @samp{CC} header (@code{message-goto-cc}). -@item C-c C-f C-b -Move to the @samp{BCC} header (@code{message-goto-bcc}). -@item C-c C-f C-r -Move to the @samp{Reply-To} header (@code{message-goto-reply-to}). -@item C-c C-f C-f -Move to the @samp{Mail-Followup-To} header field -(@code{message-goto-followup-to}). -@item C-c C-f C-w -Add a new @samp{FCC} header field, with file-name completion -(@code{message-goto-fcc}). -@item C-c C-b -Move to the start of the message body (@code{message-goto-body}). -@item @key{TAB} -Complete a mailing address (@code{message-tab}). -@end table - -@kindex C-c C-f C-t @r{(Message mode)} -@findex message-goto-to -@kindex C-c C-f C-s @r{(Message mode)} -@findex message-goto-subject -@kindex C-c C-f C-c @r{(Message mode)} -@findex message-goto-cc -@kindex C-c C-f C-b @r{(Message mode)} -@findex message-goto-bcc -@kindex C-c C-f C-r @r{(Message mode)} -@findex goto-reply-to -@kindex C-c C-f C-f @r{(Message mode)} -@findex goto-followup-to -@kindex C-c C-f C-w @r{(Message mode)} -@findex message-goto-fcc - The commands to move point to particular header fields are all based -on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). If the -field in question does not exist, the command creates one (the -exception is @code{mail-fcc}, which creates a new field each time). - -@kindex C-c C-b @r{(Message mode)} -@findex mail-text - The command @kbd{C-c C-b} (@code{message-goto-body}) moves point to -just after the header separator line---that is, to the beginning of -the body. - -@findex message-tab -@kindex TAB @r{(Message mode)} - While editing a header field that contains addresses, such as -@samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete an address by -typing @key{TAB} (@code{message-tab}). This attempts to insert the -full name corresponding to the address based on a couple of methods, -including EUDC, a library that recognizes a number of directory server -protocols (@pxref{Top,,EUDC,eudc, The Emacs Unified Directory -Client}). Failing that, it attempts to expand the address as a mail -alias (@pxref{Mail Aliases}). If point is on a header field that does -not take addresses, or if it is in the message body, then @key{TAB} -just inserts a tab character. - -@node Citing Mail -@subsection Citing Mail -@cindex citing mail - -@table @kbd -@item C-c C-y -Yank the selected message from the mail reader, as a citation -(@code{message-yank-original}). -@item C-c C-q -Fill each paragraph cited from another message -(@code{message-fill-yanked-message}). -@end table - -@kindex C-c C-y @r{(Message mode)} -@findex message-yank-original -@findex message-yank-prefix - You can use the command @kbd{C-c C-y} (@code{message-yank-original}) -to @dfn{cite} a message that you are replying to. This inserts the -text of that message into the mail buffer. This command works only if -the mail buffer is invoked from a mail reader running in Emacs, such -as Rmail. - - By default, Emacs inserts the string @samp{>} in front of each line -of the cited text; this prefix string is specified by the variable -@code{message-yank-prefix}. If you call @code{message-yank-original} -with a prefix argument, the citation prefix is not inserted. - -@kindex C-c C-q @r{(Message mode)} -@findex mail-fill-yanked-message - After using @kbd{C-c C-y}, you can type @kbd{C-c C-q} -(@code{message-fill-yanked-message}) to fill the paragraphs of the -cited message. One use of @kbd{C-c C-q} fills all such paragraphs, -each one individually. To fill a single paragraph of the quoted -message, use @kbd{M-q}. If filling does not automatically handle the -type of citation prefix you use, try setting the fill prefix -explicitly. @xref{Filling}. - -@vindex mail-citation-hook - You can customize mail citation through the hook -@code{mail-citation-hook}. For example, you can use the Supercite -package, which provides more flexible citation -(@pxref{Introduction,,,sc, Supercite}). - -@node Mail Misc -@subsection Mail Miscellany - -@kindex C-c C-a @r{(Message mode)} -@findex mml-attach-file -@cindex MIME -@cindex Multipurpose Internet Mail Extensions - You can @dfn{attach} a file to an outgoing message by typing -@kbd{C-c C-a} (@code{mml-attach-file}) in the mail buffer. Attaching -is done using the Multipurpose Internet Mail Extensions -(@acronym{MIME}) standard. - - The @code{mml-attach-file} command prompts for the name of the file, -and for the attachment's @dfn{content type}, @dfn{description}, and -@dfn{disposition}. The content type is normally detected -automatically; just type @key{RET} to accept the default. The -description is a single line of text that the recipient will see next -to the attachment; you may also choose to leave this empty. The -disposition is either @samp{inline} (the default), which means the -recipient will see a link to the attachment within the message body, -or @samp{attachment}, which means the link will be separate from the -body. - -@findex mail-add-attachment - The @code{mml-attach-file} command is specific to Message mode; in -Mail mode use @kbd{mail-add-attachment} instead. It will prompt only -for the name of the file, and will determine the content type and the -disposition automatically. If you want to include some description of -the attached file, type that in the message body. - - The actual contents of the attached file are not inserted into the -mail buffer. Instead, some placeholder text is inserted into the mail -buffer, like this: - -@smallexample -<#part type="text/plain" filename="~/foo.txt" disposition=inline> -<#/part> -@end smallexample - -@noindent -When you type @kbd{C-c C-c} or @kbd{C-c C-s} to send the message, the -attached file will be delivered with it. - -@findex ispell-message - While composing a message, you can do spelling correction on the -message text by typing @kbd{M-x ispell-message}. If you have yanked -an incoming message into the outgoing draft, this command skips what -was yanked, but it checks the text that you yourself inserted (it -looks for indentation or @code{mail-yank-prefix} to distinguish the -cited lines from your input). @xref{Spelling}. - -@vindex mail-mode-hook -@vindex mail-setup-hook - Turning on Message mode (which @kbd{C-x m} does automatically) runs -the normal hooks @code{text-mode-hook} and @code{message-mode-hook}. -Initializing a new outgoing message runs the normal hook -@code{message-setup-hook}; you can use this hook if you want to make -changes to the appearance of the mail buffer. @xref{Hooks}. - - The main difference between these hooks is just when they are -invoked. Whenever you type @kbd{C-x m}, @code{message-mode-hook} runs -as soon as the mail buffer is created. Then the @code{message-setup} -function inserts the default contents of the buffer. After these -default contents are inserted, @code{message-setup-hook} runs. - - If you use @kbd{C-x m} to continue an existing composition, -@code{message-mode-hook} runs immediately after switching to the mail -buffer. If the buffer is unmodified, or if you decide to erase it and -start again, @code{message-setup-hook} runs after the default contents -are inserted. - -@node Mail Signature -@section Mail Signature - -@cindex mail signature -@vindex message-signature-file -@vindex message-signature - You can add a standard piece of text---your @dfn{mail -signature}---to the end of every message. This signature may contain -information such as your telephone number or your physical location. -The variable @code{message-signature} determines how Emacs handles the -mail signature. - - The default value of @code{message-signature} is @code{t}; this -means to look for your mail signature in the file @file{~/.signature}. -If this file exists, its contents are automatically inserted into the -end of the mail buffer. You can change the signature file via the -variable @code{message-signature-file}. - - If you change @code{message-signature} to a string, that specifies -the text of the signature directly. - -@kindex C-c C-w @r{(Message mode)} -@findex message-insert-signature - If you change @code{message-signature} to @code{nil}, Emacs will not -insert your mail signature automatically. You can insert your mail -signature by typing @kbd{C-c C-w} (@code{message-insert-signature}) in -the mail buffer. Emacs will look for your signature in the signature -file. - -@vindex mail-signature-file -@vindex mail-signature - If you use Mail mode rather than Message mode for composing your -mail, the corresponding variables that determine how your signature is -sent are @code{mail-signature} and @code{mail-signature-file} instead. - - By convention, a mail signature should be marked by a line whose -contents are @samp{-- }. If your signature lacks this prefix, it is -added for you. The remainder of your signature should be no more than -four lines. - -@node Mail Amusements -@section Mail Amusements - -@findex spook -@cindex NSA - @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing -mail message. The keywords are chosen from a list of words that suggest -you are discussing something subversive. - - The idea behind this feature is the suspicion that the -NSA@footnote{The US National Security Agency.} and other intelligence -agencies snoop on all electronic mail messages that contain keywords -suggesting they might find them interesting. (The agencies say that -they don't, but that's what they @emph{would} say.) The idea is that if -lots of people add suspicious words to their messages, the agencies will -get so busy with spurious input that they will have to give up reading -it all. Whether or not this is true, it at least amuses some people. - -@findex fortune-to-signature -@cindex fortune cookies - You can use the @code{fortune} program to put a ``fortune cookie'' -message into outgoing mail. To do this, add -@code{fortune-to-signature} to @code{mail-setup-hook}: - -@example -(add-hook 'mail-setup-hook 'fortune-to-signature) -@end example - -@noindent -You will probably need to set the variable @code{fortune-file} before -using this. - -@node Mail Methods -@section Mail-Composition Methods -@cindex mail-composition methods -@cindex Mail mode -@cindex mode, Mail - -@cindex MH mail interface -@cindex Message mode for sending mail - In this chapter we have described the usual Emacs mode for editing -and sending mail---Message mode. This is only one of several -available modes. Prior to Emacs 23.2, the default mode was Mail mode, -which is similar to Message mode in many respects but lacks features -such as MIME support. Another available mode is MH-E -(@pxref{Top,,MH-E,mh-e, The Emacs Interface to MH}). - -@vindex mail-user-agent - You can choose any of these @dfn{mail user agents} as your preferred -method for editing and sending mail. The commands @code{C-x m}, -@code{C-x 4 m} and @code{C-x 5 m} use whichever agent you have -specified; so do various other parts of Emacs that send mail, such as -the bug reporter (@pxref{Bugs}). To specify a mail user agent, -customize the variable @code{mail-user-agent}. Currently, legitimate -values include @code{message-user-agent} (Message mode) -@code{sendmail-user-agent} (Mail mode), @code{gnus-user-agent}, and -@code{mh-e-user-agent}. - - If you select a different mail-composition method, the information -in this chapter about the mail buffer and Message mode does not apply; -the other methods use a different format of text in a different -buffer, and their commands are different as well. - -@vindex read-mail-command - Similarly, to specify your preferred method for reading mail, -customize the variable @code{read-mail-command}. The default is -@code{rmail} (@pxref{Rmail}). diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi deleted file mode 100644 index cebbdf9d95b..00000000000 --- a/doc/emacs/text.texi +++ /dev/null @@ -1,2818 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Text -@chapter Commands for Human Languages -@cindex text -@cindex manipulating text - - This chapter describes Emacs commands that act on @dfn{text}, by -which we mean sequences of characters in a human language (as opposed -to, say, a computer programming language). These commands act in ways -that take into account the syntactic and stylistic conventions of -human languages: conventions involving words, sentences, paragraphs, -and capital letters. There are also commands for @dfn{filling}, which -means rearranging the lines of a paragraph to be approximately equal -in length. These commands, while intended primarily for editing text, -are also often useful for editing programs. - - Emacs has several major modes for editing human-language text. If -the file contains ordinary text, use Text mode, which customizes Emacs -in small ways for the syntactic conventions of text. Outline mode -provides special commands for operating on text with an outline -structure. Org mode extends Outline mode and turn Emacs into a -full-fledged organizer: you can manage TODO lists, store notes and -publish them in many formats. - -@iftex -@xref{Outline Mode}. -@end iftex - -@cindex nXML mode -@cindex mode, XML -@cindex mode, nXML -@findex nxml-mode - Emacs has other major modes for text which contains ``embedded'' -commands, such as @TeX{} and @LaTeX{} (@pxref{TeX Mode}); HTML and -SGML (@pxref{HTML Mode}); XML -@ifinfo -(@pxref{Top,The nXML Mode Manual,,nxml-mode, nXML Mode}); -@end ifinfo -@ifnotinfo -(see the nXML mode Info manual, which is distributed with Emacs); -@end ifnotinfo -and Groff and Nroff (@pxref{Nroff Mode}). - -@cindex ASCII art - If you need to edit pictures made out of text characters (commonly -referred to as ``ASCII art''), use Picture mode, a special major mode -for editing such pictures. -@iftex -@xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Picture Mode}. -@end ifnottex - -@ifinfo -@cindex skeletons -@cindex templates -@cindex autotyping -@cindex automatic typing - The ``automatic typing'' features may be useful when writing text. -@inforef{Top,The Autotype Manual,autotype}. -@end ifinfo - -@menu -* Words:: Moving over and killing words. -* Sentences:: Moving over and killing sentences. -* Paragraphs:: Moving over paragraphs. -* Pages:: Moving over pages. -* Filling:: Filling or justifying text. -* Case:: Changing the case of text. -* Text Mode:: The major modes for editing text files. -* Outline Mode:: Editing outlines. -* Org Mode:: The Emacs organizer. -* TeX Mode:: Editing TeX and LaTeX files. -* HTML Mode:: Editing HTML and SGML files. -* Nroff Mode:: Editing input to the nroff formatter. -* Enriched Text:: Editing text "enriched" with fonts, colors, etc. -* Text Based Tables:: Commands for editing text-based tables. -* Two-Column:: Splitting text columns into separate windows. -@end menu - -@node Words -@section Words -@cindex words -@cindex Meta commands and words - - Emacs defines several commands for moving over or operating on -words: - -@table @kbd -@item M-f -Move forward over a word (@code{forward-word}). -@item M-b -Move backward over a word (@code{backward-word}). -@item M-d -Kill up to the end of a word (@code{kill-word}). -@item M-@key{DEL} -Kill back to the beginning of a word (@code{backward-kill-word}). -@item M-@@ -Mark the end of the next word (@code{mark-word}). -@item M-t -Transpose two words or drag a word across others -(@code{transpose-words}). -@end table - - Notice how these keys form a series that parallels the character-based -@kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is -cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}. - -@kindex M-f -@kindex M-b -@findex forward-word -@findex backward-word - The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b} -(@code{backward-word}) move forward and backward over words. These -@key{META}-based key sequences are analogous to the key sequences -@kbd{C-f} and @kbd{C-b}, which move over single characters. The -analogy extends to numeric arguments, which serve as repeat counts. -@kbd{M-f} with a negative argument moves backward, and @kbd{M-b} with -a negative argument moves forward. Forward motion stops right after -the last letter of the word, while backward motion stops right before -the first letter. - -@kindex M-d -@findex kill-word - @kbd{M-d} (@code{kill-word}) kills the word after point. To be -precise, it kills everything from point to the place @kbd{M-f} would -move to. Thus, if point is in the middle of a word, @kbd{M-d} kills -just the part after point. If some punctuation comes between point -and the next word, it is killed along with the word. (If you wish to -kill only the next word but not the punctuation before it, simply do -@kbd{M-f} to get the end, and kill the word backwards with -@kbd{M-@key{DEL}}.) @kbd{M-d} takes arguments just like @kbd{M-f}. - -@findex backward-kill-word -@kindex M-DEL - @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before -point. It kills everything from point back to where @kbd{M-b} would -move to. For instance, if point is after the space in @w{@samp{FOO, -BAR}}, it kills @w{@samp{FOO, }}. If you wish to kill just -@samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead -of @kbd{M-@key{DEL}}. - -@c Don't index M-t and transpose-words here, they are indexed in -@c fixit.texi, in the node "Transpose". -@c @kindex M-t -@c @findex transpose-words - @kbd{M-t} (@code{transpose-words}) exchanges the word before or -containing point with the following word. The delimiter characters between -the words do not move. For example, @w{@samp{FOO, BAR}} transposes into -@w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for -more on transposition. - -@kindex M-@@ -@findex mark-word - To operate on words with an operation which acts on the region, use -the command @kbd{M-@@} (@code{mark-word}). This command sets the mark -where @kbd{M-f} would move to. @xref{Marking Objects}, for more -information about this command. - - The word commands' understanding of word boundaries is controlled by -the syntax table. Any character can, for example, be declared to be a -word delimiter. @xref{Syntax Tables,, Syntax Tables, elisp, The Emacs -Lisp Reference Manual}. - - In addition, see @ref{Position Info} for the @kbd{M-=} -(@code{count-words-region}) and @kbd{M-x count-words} commands, which -count and report the number of words in the region or buffer. - -@node Sentences -@section Sentences -@cindex sentences -@cindex manipulating sentences - - The Emacs commands for manipulating sentences and paragraphs are -mostly on Meta keys, like the word-handling commands. - -@table @kbd -@item M-a -Move back to the beginning of the sentence (@code{backward-sentence}). -@item M-e -Move forward to the end of the sentence (@code{forward-sentence}). -@item M-k -Kill forward to the end of the sentence (@code{kill-sentence}). -@item C-x @key{DEL} -Kill back to the beginning of the sentence (@code{backward-kill-sentence}). -@end table - -@kindex M-a -@kindex M-e -@findex backward-sentence -@findex forward-sentence - The commands @kbd{M-a} (@code{backward-sentence}) and @kbd{M-e} -(@code{forward-sentence}) move to the beginning and end of the current -sentence, respectively. Their bindings were chosen to resemble -@kbd{C-a} and @kbd{C-e}, which move to the beginning and end of a -line. Unlike them, @kbd{M-a} and @kbd{M-e} move over successive -sentences if repeated. - - Moving backward over a sentence places point just before the first -character of the sentence; moving forward places point right after the -punctuation that ends the sentence. Neither one moves over the -whitespace at the sentence boundary. - -@kindex M-k -@findex kill-sentence - Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to -go with them, @kbd{M-a} and @kbd{M-e} have a corresponding kill -command: @kbd{M-k} (@code{kill-sentence}) kills from point to the end -of the sentence. With a positive numeric argument @var{n}, it kills -the next @var{n} sentences; with a negative argument @minus{}@var{n}, -it kills back to the beginning of the @var{n}th preceding sentence. - -@kindex C-x DEL -@findex backward-kill-sentence - The @kbd{C-x @key{DEL}} (@code{backward-kill-sentence}) kills back -to the beginning of a sentence. - - The sentence commands assume that you follow the American typist's -convention of putting two spaces at the end of a sentence. That is, a -sentence ends wherever there is a @samp{.}, @samp{?} or @samp{!} -followed by the end of a line or two spaces, with any number of -@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in -between. A sentence also begins or ends wherever a paragraph begins -or ends. It is useful to follow this convention, because it allows -the Emacs sentence commands to distinguish between periods that end a -sentence and periods that indicate abbreviations. - -@vindex sentence-end-double-space - If you want to use just one space between sentences, you can set the -variable @code{sentence-end-double-space} to @code{nil} to make the -sentence commands stop for single spaces. However, this has a -drawback: there is no way to distinguish between periods that end -sentences and those that indicate abbreviations. For convenient and -reliable editing, we therefore recommend you follow the two-space -convention. The variable @code{sentence-end-double-space} also -affects filling (@pxref{Fill Commands}). - -@vindex sentence-end - The variable @code{sentence-end} controls how to recognize the end -of a sentence. If non-@code{nil}, its value should be a regular -expression, which is used to match the last few characters of a -sentence, together with the whitespace following the sentence -(@pxref{Regexps}). If the value is @code{nil}, the default, then -Emacs computes sentence ends according to various criteria such as the -value of @code{sentence-end-double-space}. - -@vindex sentence-end-without-period - Some languages, such as Thai, do not use periods to indicate the end -of a sentence. Set the variable @code{sentence-end-without-period} to -@code{t} in such cases. - -@node Paragraphs -@section Paragraphs -@cindex paragraphs -@cindex manipulating paragraphs - - The Emacs commands for manipulating paragraphs are also on Meta keys. - -@table @kbd -@item M-@{ -Move back to previous paragraph beginning (@code{backward-paragraph}). -@item M-@} -Move forward to next paragraph end (@code{forward-paragraph}). -@item M-h -Put point and mark around this or next paragraph (@code{mark-paragraph}). -@end table - -@kindex M-@{ -@kindex M-@} -@findex backward-paragraph -@findex forward-paragraph - @kbd{M-@{} (@code{backward-paragraph}) moves to the beginning of the -current or previous paragraph (see below for the definition of a -paragraph). @kbd{M-@}} (@code{forward-paragraph}) moves to the end of -the current or next paragraph. If there is a blank line before the -paragraph, @kbd{M-@{} moves to the blank line. - -@kindex M-h -@findex mark-paragraph - When you wish to operate on a paragraph, type @kbd{M-h} -(@code{mark-paragraph}) to set the region around it. For example, -@kbd{M-h C-w} kills the paragraph around or after point. @kbd{M-h} -puts point at the beginning and mark at the end of the paragraph point -was in. If point is between paragraphs (in a run of blank lines, or -at a boundary), @kbd{M-h} sets the region around the paragraph -following point. If there are blank lines preceding the first line of -the paragraph, one of these blank lines is included in the region. If -the region is already active, the command sets the mark without -changing point, and each subsequent @kbd{M-h} further advances the -mark by one paragraph. - - The definition of a paragraph depends on the major mode. In -Fundamental mode, as well as Text mode and related modes, a paragraph -is separated each neighboring paragraph another by one or more -@dfn{blank lines}---lines that are either empty, or consist solely of -space, tab and/or formfeed characters. In programming language modes, -paragraphs are usually defined in a similar way, so that you can use -the paragraph commands even though there are no paragraphs as such in -a program. - - Note that an indented line is @emph{not} itself a paragraph break in -Text mode. If you want indented lines to separate paragraphs, use -Paragraph-Indent Text mode instead. @xref{Text Mode}. - - If you set a fill prefix, then paragraphs are delimited by all lines -which don't start with the fill prefix. @xref{Filling}. - -@vindex paragraph-start -@vindex paragraph-separate - The precise definition of a paragraph boundary is controlled by the -variables @code{paragraph-separate} and @code{paragraph-start}. The -value of @code{paragraph-start} is a regular expression that should -match lines that either start or separate paragraphs -(@pxref{Regexps}). The value of @code{paragraph-separate} is another -regular expression that should match lines that separate paragraphs -without being part of any paragraph (for example, blank lines). Lines -that start a new paragraph and are contained in it must match only -@code{paragraph-start}, not @code{paragraph-separate}. For example, -in Fundamental mode, @code{paragraph-start} is @w{@code{"\f\\|[ -\t]*$"}}, and @code{paragraph-separate} is @w{@code{"[ \t\f]*$"}}. - -@node Pages -@section Pages - -@cindex pages -@cindex formfeed character - Within some text files, text is divided into @dfn{pages} delimited -by the @dfn{formfeed character} (@acronym{ASCII} code 12, also denoted -as @samp{control-L}), which is displayed in Emacs as the escape -sequence @samp{^L} (@pxref{Text Display}). Traditionally, when such -text files are printed to hardcopy, each formfeed character forces a -page break. Most Emacs commands treat it just like any other -character, so you can insert it with @kbd{C-q C-l}, delete it with -@key{DEL}, etc. In addition, Emacs provides commands to move over -pages and operate on them. - -@table @kbd -@item M-x what-page -Display the page number of point, and the line number within that page. -@item C-x [ -Move point to previous page boundary (@code{backward-page}). -@item C-x ] -Move point to next page boundary (@code{forward-page}). -@item C-x C-p -Put point and mark around this page (or another page) (@code{mark-page}). -@item C-x l -Count the lines in this page (@code{count-lines-page}). -@end table - -@findex what-page - @kbd{M-x what-page} counts pages from the beginning of the file, and -counts lines within the page, showing both numbers in the echo area. - -@kindex C-x [ -@kindex C-x ] -@findex forward-page -@findex backward-page - The @kbd{C-x [} (@code{backward-page}) command moves point to immediately -after the previous page delimiter. If point is already right after a page -delimiter, it skips that one and stops at the previous one. A numeric -argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page}) -command moves forward past the next page delimiter. - -@kindex C-x C-p -@findex mark-page - The @kbd{C-x C-p} command (@code{mark-page}) puts point at the -beginning of the current page (after that page delimiter at the -front), and the mark at the end of the page (after the page delimiter -at the end). - - @kbd{C-x C-p C-w} is a handy way to kill a page to move it -elsewhere. If you move to another page delimiter with @kbd{C-x [} and -@kbd{C-x ]}, then yank the killed page, all the pages will be properly -delimited once again. The reason @kbd{C-x C-p} includes only the -following page delimiter in the region is to ensure that. - - A numeric argument to @kbd{C-x C-p} specifies which page to go to, -relative to the current one. Zero means the current page, one -the next page, and @minus{}1 the previous one. - -@kindex C-x l -@findex count-lines-page - The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding -where to break a page in two. It displays in the echo area the total number -of lines in the current page, and then divides it up into those preceding -the current line and those following, as in - -@example -Page has 96 (72+25) lines -@end example - -@noindent - Notice that the sum is off by one; this is correct if point is not at the -beginning of a line. - -@vindex page-delimiter - The variable @code{page-delimiter} controls where pages begin. Its -value is a regular expression that matches the beginning of a line -that separates pages (@pxref{Regexps}). The normal value of this -variable is @code{"^\f"}, which matches a formfeed character at the -beginning of a line. - -@node Filling -@section Filling Text -@cindex filling text - - @dfn{Filling} text means breaking it up into lines that fit a -specified width. Emacs does filling in two ways. In Auto Fill mode, -inserting text with self-inserting characters also automatically fills -it. There are also explicit fill commands that you can use when editing -text. - -@menu -* Auto Fill:: Auto Fill mode breaks long lines automatically. -* Fill Commands:: Commands to refill paragraphs and center lines. -* Fill Prefix:: Filling paragraphs that are indented or in a comment, etc. -* Adaptive Fill:: How Emacs can determine the fill prefix automatically. -@end menu - -@node Auto Fill -@subsection Auto Fill Mode -@cindex Auto Fill mode -@cindex mode, Auto Fill - - @dfn{Auto Fill} mode is a buffer-local minor mode (@pxref{Minor -Modes}) in which lines are broken automatically when they become too -wide. Breaking happens only when you type a @key{SPC} or @key{RET}. - -@table @kbd -@item M-x auto-fill-mode -Enable or disable Auto Fill mode. -@item @key{SPC} -@itemx @key{RET} -In Auto Fill mode, break lines when appropriate. -@end table - -@findex auto-fill-mode - The mode command @kbd{M-x auto-fill-mode} toggles Auto Fill mode in -the current buffer. With a positive numeric argument, it enables Auto -Fill mode, and with a negative argument it disables it. If -@code{auto-fill-mode} is called from Lisp with an omitted or -@code{nil} argument, it enables Auto Fill mode. To enable Auto Fill -mode automatically in certain major modes, add @code{auto-fill-mode} -to the mode hooks (@pxref{Major Modes}). When Auto Fill mode is -enabled, the mode indicator @samp{Fill} appears in the mode line -(@pxref{Mode Line}). - - Auto Fill mode breaks lines automatically at spaces whenever they -get longer than the desired width. This line breaking occurs only -when you type @key{SPC} or @key{RET}. If you wish to insert a space -or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} -or @kbd{C-q C-j} respectively. Also, @kbd{C-o} inserts a newline -without line breaking. - - When Auto Fill mode breaks a line, it tries to obey the -@dfn{adaptive fill prefix}: if a fill prefix can be deduced from the -first and/or second line of the current paragraph, it is inserted into -the new line (@pxref{Adaptive Fill}). Otherwise the new line is -indented, as though you had typed @key{TAB} on it -(@pxref{Indentation}). In a programming language mode, if a line is -broken in the middle of a comment, the comment is split by inserting -new comment delimiters as appropriate. - - Auto Fill mode does not refill entire paragraphs; it breaks lines -but does not merge lines. Therefore, editing in the middle of a -paragraph can result in a paragraph that is not correctly filled. To -fill it, call the explicit fill commands -@iftex -described in the next section. -@end iftex -@ifnottex -(@pxref{Fill Commands}). -@end ifnottex - -@node Fill Commands -@subsection Explicit Fill Commands - -@table @kbd -@item M-q -Fill current paragraph (@code{fill-paragraph}). -@item C-x f -Set the fill column (@code{set-fill-column}). -@item M-x fill-region -Fill each paragraph in the region (@code{fill-region}). -@item M-x fill-region-as-paragraph -Fill the region, considering it as one paragraph. -@item M-o M-s -Center a line. -@end table - -@kindex M-q -@findex fill-paragraph - The command @kbd{M-q} (@code{fill-paragraph}) @dfn{fills} the -current paragraph. It redistributes the line breaks within the -paragraph, and deletes any excess space and tab characters occurring -within the paragraph, in such a way that the lines end up fitting -within a certain maximum width. - -@findex fill-region - Normally, @kbd{M-q} acts on the paragraph where point is, but if -point is between paragraphs, it acts on the paragraph after point. If -the region is active, it acts instead on the text in the region. You -can also call @kbd{M-x fill-region} to specifically fill the text in -the region. - -@findex fill-region-as-paragraph - @kbd{M-q} and @code{fill-region} use the usual Emacs criteria for -finding paragraph boundaries (@pxref{Paragraphs}). For more control, -you can use @kbd{M-x fill-region-as-paragraph}, which refills -everything between point and mark as a single paragraph. This command -deletes any blank lines within the region, so separate blocks of text -end up combined into one block. - -@cindex justification - A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text -as well as filling it. This means that extra spaces are inserted to -make the right margin line up exactly at the fill column. To remove -the extra spaces, use @kbd{M-q} with no argument. (Likewise for -@code{fill-region}.) - -@vindex fill-column -@kindex C-x f -@findex set-fill-column - The maximum line width for filling is specified by the buffer-local -variable @code{fill-column}. The default value (@pxref{Locals}) is -70. The easiest way to set @code{fill-column} in the current buffer -is to use the command @kbd{C-x f} (@code{set-fill-column}). With a -numeric argument, it uses that as the new fill column. With just -@kbd{C-u} as argument, it sets @code{fill-column} to the current -horizontal position of point. - -@kindex M-o M-s @r{(Text mode)} -@cindex centering -@findex center-line - The command @kbd{M-o M-s} (@code{center-line}) centers the current line -within the current fill column. With an argument @var{n}, it centers -@var{n} lines individually and moves past them. This binding is -made by Text mode and is available only in that and related modes -(@pxref{Text Mode}). - - By default, Emacs considers a period followed by two spaces or by a -newline as the end of a sentence; a period followed by just one space -indicates an abbreviation, not the end of a sentence. Accordingly, -the fill commands will not break a line after a period followed by -just one space. If you set the variable -@code{sentence-end-double-space} to @code{nil}, the fill commands will -break a line after a period followed by one space, and put just one -space after each period. @xref{Sentences}, for other effects and -possible drawbacks of this. - -@vindex colon-double-space - If the variable @code{colon-double-space} is non-@code{nil}, the -fill commands put two spaces after a colon. - -@vindex fill-nobreak-predicate - To specify additional conditions where line-breaking is not allowed, -customize the abnormal hook variable @code{fill-nobreak-predicate} -(@pxref{Hooks}). Each function in this hook is called with no -arguments, with point positioned where Emacs is considering breaking a -line. If a function returns a non-@code{nil} value, Emacs will not -break the line there. Functions you can use there include: -@code{fill-single-word-nobreak-p} (don't break after the first word of -a sentence or before the last); @code{fill-single-char-nobreak-p} -(don't break after a one-letter word); and @code{fill-french-nobreak-p} -(don't break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). - -@node Fill Prefix -@subsection The Fill Prefix - -@cindex fill prefix - The @dfn{fill prefix} feature allows paragraphs to be filled so that -each line starts with a special string of characters (such as a -sequence of spaces, giving an indented paragraph). You can specify a -fill prefix explicitly; otherwise, Emacs tries to deduce one -automatically (@pxref{Adaptive Fill}). - -@table @kbd -@item C-x . -Set the fill prefix (@code{set-fill-prefix}). -@item M-q -Fill a paragraph using current fill prefix (@code{fill-paragraph}). -@item M-x fill-individual-paragraphs -Fill the region, considering each change of indentation as starting a -new paragraph. -@item M-x fill-nonuniform-paragraphs -Fill the region, considering only paragraph-separator lines as starting -a new paragraph. -@end table - -@kindex C-x . -@findex set-fill-prefix - To specify a fill prefix for the current buffer, move to a line that -starts with the desired prefix, put point at the end of the prefix, -and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period -after the @kbd{C-x}.) To turn off the fill prefix, specify an empty -prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line. - - When a fill prefix is in effect, the fill commands remove the fill -prefix from each line of the paragraph before filling, and insert it -on each line after filling. (The beginning of the first line of the -paragraph is left unchanged, since often that is intentionally -different.) Auto Fill mode also inserts the fill prefix automatically -when it makes a new line (@pxref{Auto Fill}). The @kbd{C-o} command -inserts the fill prefix on new lines it creates, when you use it at -the beginning of a line (@pxref{Blank Lines}). Conversely, the -command @kbd{M-^} deletes the prefix (if it occurs) after the newline -that it deletes (@pxref{Indentation}). - - For example, if @code{fill-column} is 40 and you set the fill prefix -to @samp{;; }, then @kbd{M-q} in the following text - -@example -;; This is an -;; example of a paragraph -;; inside a Lisp-style comment. -@end example - -@noindent -produces this: - -@example -;; This is an example of a paragraph -;; inside a Lisp-style comment. -@end example - - Lines that do not start with the fill prefix are considered to start -paragraphs, both in @kbd{M-q} and the paragraph commands; this gives -good results for paragraphs with hanging indentation (every line -indented except the first one). Lines which are blank or indented once -the prefix is removed also separate or start paragraphs; this is what -you want if you are writing multi-paragraph comments with a comment -delimiter on each line. - -@findex fill-individual-paragraphs - You can use @kbd{M-x fill-individual-paragraphs} to set the fill -prefix for each paragraph automatically. This command divides the -region into paragraphs, treating every change in the amount of -indentation as the start of a new paragraph, and fills each of these -paragraphs. Thus, all the lines in one ``paragraph'' have the same -amount of indentation. That indentation serves as the fill prefix for -that paragraph. - -@findex fill-nonuniform-paragraphs - @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides -the region into paragraphs in a different way. It considers only -paragraph-separating lines (as defined by @code{paragraph-separate}) as -starting a new paragraph. Since this means that the lines of one -paragraph may have different amounts of indentation, the fill prefix -used is the smallest amount of indentation of any of the lines of the -paragraph. This gives good results with styles that indent a paragraph's -first line more or less that the rest of the paragraph. - -@vindex fill-prefix - The fill prefix is stored in the variable @code{fill-prefix}. Its value -is a string, or @code{nil} when there is no fill prefix. This is a -per-buffer variable; altering the variable affects only the current buffer, -but there is a default value which you can change as well. @xref{Locals}. - - The @code{indentation} text property provides another way to control -the amount of indentation paragraphs receive. @xref{Enriched -Indentation}. - -@node Adaptive Fill -@subsection Adaptive Filling - -@cindex adaptive filling - The fill commands can deduce the proper fill prefix for a paragraph -automatically in certain cases: either whitespace or certain punctuation -characters at the beginning of a line are propagated to all lines of the -paragraph. - - If the paragraph has two or more lines, the fill prefix is taken from -the paragraph's second line, but only if it appears on the first line as -well. - - If a paragraph has just one line, fill commands @emph{may} take a -prefix from that line. The decision is complicated because there are -three reasonable things to do in such a case: - -@itemize @bullet -@item -Use the first line's prefix on all the lines of the paragraph. - -@item -Indent subsequent lines with whitespace, so that they line up under the -text that follows the prefix on the first line, but don't actually copy -the prefix from the first line. - -@item -Don't do anything special with the second and following lines. -@end itemize - - All three of these styles of formatting are commonly used. So the -fill commands try to determine what you would like, based on the prefix -that appears and on the major mode. Here is how. - -@vindex adaptive-fill-first-line-regexp - If the prefix found on the first line matches -@code{adaptive-fill-first-line-regexp}, or if it appears to be a -comment-starting sequence (this depends on the major mode), then the -prefix found is used for filling the paragraph, provided it would not -act as a paragraph starter on subsequent lines. - - Otherwise, the prefix found is converted to an equivalent number of -spaces, and those spaces are used as the fill prefix for the rest of the -lines, provided they would not act as a paragraph starter on subsequent -lines. - - In Text mode, and other modes where only blank lines and page -delimiters separate paragraphs, the prefix chosen by adaptive filling -never acts as a paragraph starter, so it can always be used for filling. - -@vindex adaptive-fill-mode -@vindex adaptive-fill-regexp - The variable @code{adaptive-fill-regexp} determines what kinds of line -beginnings can serve as a fill prefix: any characters at the start of -the line that match this regular expression are used. If you set the -variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is -never chosen automatically. - -@vindex adaptive-fill-function - You can specify more complex ways of choosing a fill prefix -automatically by setting the variable @code{adaptive-fill-function} to a -function. This function is called with point after the left margin of a -line, and it should return the appropriate fill prefix based on that -line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets -a chance to find a prefix. - -@node Case -@section Case Conversion Commands -@cindex case conversion - - Emacs has commands for converting either a single word or any arbitrary -range of text to upper case or to lower case. - -@table @kbd -@item M-l -Convert following word to lower case (@code{downcase-word}). -@item M-u -Convert following word to upper case (@code{upcase-word}). -@item M-c -Capitalize the following word (@code{capitalize-word}). -@item C-x C-l -Convert region to lower case (@code{downcase-region}). -@item C-x C-u -Convert region to upper case (@code{upcase-region}). -@end table - -@kindex M-l -@kindex M-u -@kindex M-c -@cindex words, case conversion -@cindex converting text to upper or lower case -@cindex capitalizing words -@findex downcase-word -@findex upcase-word -@findex capitalize-word - @kbd{M-l} (@code{downcase-word}) converts the word after point to -lower case, moving past it. Thus, repeating @kbd{M-l} converts -successive words. @kbd{M-u} (@code{upcase-word}) converts to all -capitals instead, while @kbd{M-c} (@code{capitalize-word}) puts the -first letter of the word into upper case and the rest into lower case. -All these commands convert several words at once if given an argument. -They are especially convenient for converting a large amount of text -from all upper case to mixed case, because you can move through the -text using @kbd{M-l}, @kbd{M-u} or @kbd{M-c} on each word as -appropriate, occasionally using @kbd{M-f} instead to skip a word. - - When given a negative argument, the word case conversion commands apply -to the appropriate number of words before point, but do not move point. -This is convenient when you have just typed a word in the wrong case: you -can give the case conversion command and continue typing. - - If a word case conversion command is given in the middle of a word, -it applies only to the part of the word which follows point. (This is -comparable to what @kbd{M-d} (@code{kill-word}) does.) With a -negative argument, case conversion applies only to the part of the -word before point. - -@kindex C-x C-l -@kindex C-x C-u -@findex downcase-region -@findex upcase-region - The other case conversion commands are @kbd{C-x C-u} -(@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which -convert everything between point and mark to the specified case. Point and -mark do not move. - - The region case conversion commands @code{upcase-region} and -@code{downcase-region} are normally disabled. This means that they ask -for confirmation if you try to use them. When you confirm, you may -enable the command, which means it will not ask for confirmation again. -@xref{Disabling}. - -@node Text Mode -@section Text Mode -@cindex Text mode -@cindex mode, Text -@findex text-mode - - Text mode is a major mode for editing files of text in a human -language. Files which have names ending in the extension @file{.txt} -are usually opened in Text mode (@pxref{Choosing Modes}). To -explicitly switch to Text mode, type @kbd{M-x text-mode}. - - In Text mode, only blank lines and page delimiters separate -paragraphs. As a result, paragraphs can be indented, and adaptive -filling determines what indentation to use when filling a paragraph. -@xref{Adaptive Fill}. - -@kindex TAB @r{(Text mode)} - In Text mode, the @key{TAB} (@code{indent-for-tab-command}) command -usually inserts whitespace up to the next tab stop, instead of -indenting the current line. @xref{Indentation}, for details. - - Text mode turns off the features concerned with comments except when -you explicitly invoke them. It changes the syntax table so that -single-quotes are considered part of words (e.g., @samp{don't} is -considered one word). However, if a word starts with a single-quote, -it is treated as a prefix for the purposes of capitalization -(e.g., @kbd{M-c} converts @samp{'hello'} into @samp{'Hello'}, as -expected). - -@cindex Paragraph-Indent Text mode -@cindex mode, Paragraph-Indent Text -@findex paragraph-indent-text-mode -@findex paragraph-indent-minor-mode - If you indent the first lines of paragraphs, then you should use -Paragraph-Indent Text mode (@kbd{M-x paragraph-indent-text-mode}) -rather than Text mode. In that mode, you do not need to have blank -lines between paragraphs, because the first-line indentation is -sufficient to start a paragraph; however paragraphs in which every -line is indented are not supported. Use @kbd{M-x -paragraph-indent-minor-mode} to enable an equivalent minor mode for -situations where you shouldn't change the major mode---in mail -composition, for instance. - -@kindex M-TAB @r{(Text mode)} - Text mode binds @kbd{M-@key{TAB}} to @code{ispell-complete-word}. -This command performs completion of the partial word in the buffer -before point, using the spelling dictionary as the space of possible -words. @xref{Spelling}. If your window manager defines -@kbd{M-@key{TAB}} to switch windows, you can type @kbd{@key{ESC} -@key{TAB}} or @kbd{C-M-i} instead. - -@vindex text-mode-hook - Entering Text mode runs the mode hook @code{text-mode-hook} -(@pxref{Major Modes}). - - The following sections describe several major modes that are -@dfn{derived} from Text mode. These derivatives share most of the -features of Text mode described above. In particular, derivatives of -Text mode run @code{text-mode-hook} prior to running their own mode -hooks. - -@node Outline Mode -@section Outline Mode -@cindex Outline mode -@cindex mode, Outline -@cindex invisible lines - -@findex outline-mode -@findex outline-minor-mode -@vindex outline-minor-mode-prefix -@vindex outline-mode-hook - Outline mode is a major mode derived from Text mode, which is -specialized for editing outlines. It provides commands to navigate -between entries in the outline structure, and commands to make parts -of a buffer temporarily invisible, so that the outline structure may -be more easily viewed. Type @kbd{M-x outline-mode} to switch to -Outline mode. Entering Outline mode runs the hook -@code{text-mode-hook} followed by the hook @code{outline-mode-hook} -(@pxref{Hooks}). - - When you use an Outline mode command to make a line invisible -(@pxref{Outline Visibility}), the line disappears from the screen. An -ellipsis (three periods in a row) is displayed at the end of the -previous visible line, to indicate the hidden text. Multiple -consecutive invisible lines produce just one ellipsis. - - Editing commands that operate on lines, such as @kbd{C-n} and -@kbd{C-p}, treat the text of the invisible line as part of the -previous visible line. Killing the ellipsis at the end of a visible -line really kills all the following invisible text associated with the -ellipsis. - - Outline minor mode is a buffer-local minor mode which provides the -same commands as the major mode, Outline mode, but can be used in -conjunction with other major modes. You can type @kbd{M-x -outline-minor-mode} to toggle Outline minor mode in the current -buffer, or use a file-local variable setting to enable it in a -specific file (@pxref{File Variables}). - -@kindex C-c @@ @r{(Outline minor mode)} - The major mode, Outline mode, provides special key bindings on the -@kbd{C-c} prefix. Outline minor mode provides similar bindings with -@kbd{C-c @@} as the prefix; this is to reduce the conflicts with the -major mode's special commands. (The variable -@code{outline-minor-mode-prefix} controls the prefix used.) - -@menu -* Outline Format:: What the text of an outline looks like. -* Outline Motion:: Special commands for moving through outlines. -* Outline Visibility:: Commands to control what is visible. -* Outline Views:: Outlines and multiple views. -* Foldout:: Folding means zooming in on outlines. -@end menu - -@node Outline Format -@subsection Format of Outlines - -@cindex heading lines (Outline mode) -@cindex body lines (Outline mode) - Outline mode assumes that the lines in the buffer are of two types: -@dfn{heading lines} and @dfn{body lines}. A heading line represents a -topic in the outline. Heading lines start with one or more asterisk -(@samp{*}) characters; the number of asterisks determines the depth of -the heading in the outline structure. Thus, a heading line with one -@samp{*} is a major topic; all the heading lines with two @samp{*}s -between it and the next one-@samp{*} heading are its subtopics; and so -on. Any line that is not a heading line is a body line. Body lines -belong with the preceding heading line. Here is an example: - -@example -* Food -This is the body, -which says something about the topic of food. - -** Delicious Food -This is the body of the second-level header. - -** Distasteful Food -This could have -a body too, with -several lines. - -*** Dormitory Food - -* Shelter -Another first-level topic with its header line. -@end example - - A heading line together with all following body lines is called -collectively an @dfn{entry}. A heading line together with all following -deeper heading lines and their body lines is called a @dfn{subtree}. - -@vindex outline-regexp - You can customize the criterion for distinguishing heading lines by -setting the variable @code{outline-regexp}. (The recommended ways to -do this are in a major mode function or with a file local variable.) -Any line whose beginning has a match for this regexp is considered a -heading line. Matches that start within a line (not at the left -margin) do not count. - - The length of the matching text determines the level of the heading; -longer matches make a more deeply nested level. Thus, for example, if -a text formatter has commands @samp{@@chapter}, @samp{@@section} and -@samp{@@subsection} to divide the document into chapters and sections, -you could make those lines count as heading lines by setting -@code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note -the trick: the two words @samp{chapter} and @samp{section} are equally -long, but by defining the regexp to match only @samp{chap} we ensure -that the length of the text matched on a chapter heading is shorter, -so that Outline mode will know that sections are contained in -chapters. This works as long as no other command starts with -@samp{@@chap}. - -@vindex outline-level - You can explicitly specify a rule for calculating the level of a -heading line by setting the variable @code{outline-level}. The value -of @code{outline-level} should be a function that takes no arguments -and returns the level of the current heading. The recommended ways to -set this variable are in a major mode command or with a file local -variable. - -@node Outline Motion -@subsection Outline Motion Commands - - Outline mode provides special motion commands that move backward and -forward to heading lines. - -@table @kbd -@item C-c C-n -Move point to the next visible heading line -(@code{outline-next-visible-heading}). -@item C-c C-p -Move point to the previous visible heading line -(@code{outline-previous-visible-heading}). -@item C-c C-f -Move point to the next visible heading line at the same level -as the one point is on (@code{outline-forward-same-level}). -@item C-c C-b -Move point to the previous visible heading line at the same level -(@code{outline-backward-same-level}). -@item C-c C-u -Move point up to a lower-level (more inclusive) visible heading line -(@code{outline-up-heading}). -@end table - -@findex outline-next-visible-heading -@findex outline-previous-visible-heading -@kindex C-c C-n @r{(Outline mode)} -@kindex C-c C-p @r{(Outline mode)} - @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to -the next heading line. @kbd{C-c C-p} -(@code{outline-previous-visible-heading}) moves similarly backward. -Both accept numeric arguments as repeat counts. - -@findex outline-up-heading -@findex outline-forward-same-level -@findex outline-backward-same-level -@kindex C-c C-f @r{(Outline mode)} -@kindex C-c C-b @r{(Outline mode)} -@kindex C-c C-u @r{(Outline mode)} - @kbd{C-c C-f} (@code{outline-forward-same-level}) and @kbd{C-c C-b} -(@code{outline-backward-same-level}) move from one heading line to -another visible heading at the same depth in the outline. @kbd{C-c -C-u} (@code{outline-up-heading}) moves backward to another heading -that is less deeply nested. - -@node Outline Visibility -@subsection Outline Visibility Commands - - Outline mode provides several commands for temporarily hiding or -revealing parts of the buffer, based on the outline structure. These -commands are not undoable; their effects are simply not recorded by -the undo mechanism, so you can undo right past them (@pxref{Undo}). - - Many of these commands act on the ``current'' heading line. If -point is on a heading line, that is the current heading line; if point -is on a body line, the current heading line is the nearest preceding -header line. - -@table @kbd -@item C-c C-c -Make the current heading line's body invisible (@code{hide-entry}). -@item C-c C-e -Make the current heading line's body visible (@code{show-entry}). -@item C-c C-d -Make everything under the current heading invisible, not including the -heading itself (@code{hide-subtree}). -@item C-c C-s -Make everything under the current heading visible, including body, -subheadings, and their bodies (@code{show-subtree}). -@item C-c C-l -Make the body of the current heading line, and of all its subheadings, -invisible (@code{hide-leaves}). -@item C-c C-k -Make all subheadings of the current heading line, at all levels, -visible (@code{show-branches}). -@item C-c C-i -Make immediate subheadings (one level down) of the current heading -line visible (@code{show-children}). -@item C-c C-t -Make all body lines in the buffer invisible (@code{hide-body}). -@item C-c C-a -Make all lines in the buffer visible (@code{show-all}). -@item C-c C-q -Hide everything except the top @var{n} levels of heading lines -(@code{hide-sublevels}). -@item C-c C-o -Hide everything except for the heading or body that point is in, plus -the headings leading up from there to the top level of the outline -(@code{hide-other}). -@end table - -@findex hide-entry -@findex show-entry -@kindex C-c C-c @r{(Outline mode)} -@kindex C-c C-e @r{(Outline mode)} - The simplest of these commands are @kbd{C-c C-c} -(@code{hide-entry}), which hides the body lines directly following the -current heading line, and @kbd{C-c C-e} (@code{show-entry}), which -reveals them. Subheadings and their bodies are not affected. - -@findex hide-subtree -@findex show-subtree -@kindex C-c C-s @r{(Outline mode)} -@kindex C-c C-d @r{(Outline mode)} -@cindex subtree (Outline mode) - The commands @kbd{C-c C-d} (@code{hide-subtree}) and @kbd{C-c C-s} -(@code{show-subtree}) are more powerful. They apply to the current -heading line's @dfn{subtree}: its body, all of its subheadings, both -direct and indirect, and all of their bodies. - -@findex hide-leaves -@findex show-branches -@findex show-children -@kindex C-c C-l @r{(Outline mode)} -@kindex C-c C-k @r{(Outline mode)} -@kindex C-c C-i @r{(Outline mode)} - The command @kbd{C-c C-l} (@code{hide-leaves}) hides the body of the -current heading line as well as all the bodies in its subtree; the -subheadings themselves are left visible. The command @kbd{C-c C-k} -(@code{show-branches}) reveals the subheadings, if they had previously -been hidden (e.g., by @kbd{C-c C-d}). The command @kbd{C-c C-i} -(@code{show-children}) is a weaker version of this; it reveals just -the direct subheadings, i.e., those one level down. - -@findex hide-other -@kindex C-c C-o @r{(Outline mode)} - The command @kbd{C-c C-o} (@code{hide-other}) hides everything -except the entry that point is in, plus its parents (the headers -leading up from there to top level in the outline) and the top level -headings. - -@findex hide-body -@findex show-all -@kindex C-c C-t @r{(Outline mode)} -@kindex C-c C-a @r{(Outline mode)} -@findex hide-sublevels -@kindex C-c C-q @r{(Outline mode)} - The remaining commands affect the whole buffer. @kbd{C-c C-t} -(@code{hide-body}) makes all body lines invisible, so that you see -just the outline structure (as a special exception, it will not hide -lines at the top of the file, preceding the first header line, even -though these are technically body lines). @kbd{C-c C-a} -(@code{show-all}) makes all lines visible. @kbd{C-c C-q} -(@code{hide-sublevels}) hides all but the top level headings; with a -numeric argument @var{n}, it hides everything except the top @var{n} -levels of heading lines. - -@anchor{Outline Search} -@findex reveal-mode -@vindex search-invisible - When incremental search finds text that is hidden by Outline mode, -it makes that part of the buffer visible. If you exit the search at -that position, the text remains visible. To toggle whether or not -an active incremental search can match hidden text, type @kbd{M-s i}. -To change the default for future searches, customize the option -@code{search-invisible}. (This option also affects how @code{query-replace} -and related functions treat hidden text, @pxref{Query Replace}.) -You can also automatically make text visible as you navigate in it by -using Reveal mode (@kbd{M-x reveal-mode}), a buffer-local minor mode. - -@node Outline Views -@subsection Viewing One Outline in Multiple Views - -@cindex multiple views of outline -@cindex views of an outline -@cindex outline with multiple views -@cindex indirect buffers and outlines - You can display two views of a single outline at the same time, in -different windows. To do this, you must create an indirect buffer using -@kbd{M-x make-indirect-buffer}. The first argument of this command is -the existing outline buffer name, and its second argument is the name to -use for the new indirect buffer. @xref{Indirect Buffers}. - - Once the indirect buffer exists, you can display it in a window in the -normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline -mode commands to show and hide parts of the text operate on each buffer -independently; as a result, each buffer can have its own view. If you -want more than two views on the same outline, create additional indirect -buffers. - -@node Foldout -@subsection Folding Editing - -@cindex folding editing - The Foldout package extends Outline mode and Outline minor mode with -``folding'' commands. The idea of folding is that you zoom in on a -nested portion of the outline, while hiding its relatives at higher -levels. - - Consider an Outline mode buffer with all the text and subheadings under -level-1 headings hidden. To look at what is hidden under one of these -headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose -the body, or @kbd{C-c C-i} to expose the child (level-2) headings. - -@kindex C-c C-z -@findex foldout-zoom-subtree - With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}). -This exposes the body and child subheadings, and narrows the buffer so -that only the @w{level-1} heading, the body and the level-2 headings are -visible. Now to look under one of the level-2 headings, position the -cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body -and its level-3 child subheadings and narrows the buffer again. Zooming -in on successive subheadings can be done as much as you like. A string -in the mode line shows how deep you've gone. - - When zooming in on a heading, to see only the child subheadings specify -a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children -can be specified too (compare @kbd{M-x show-children}), e.g., @kbd{M-2 -C-c C-z} exposes two levels of child subheadings. Alternatively, the -body can be specified with a negative argument: @kbd{M-- C-c C-z}. The -whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x -show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}. - - While you're zoomed in, you can still use Outline mode's exposure and -hiding functions without disturbing Foldout. Also, since the buffer is -narrowed, ``global'' editing actions will only affect text under the -zoomed-in heading. This is useful for restricting changes to a -particular chapter or section of your document. - -@kindex C-c C-x -@findex foldout-exit-fold - To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}). -This hides all the text and subheadings under the top-level heading and -returns you to the previous view of the buffer. Specifying a numeric -argument exits that many levels of folds. Specifying a zero argument -exits all folds. - - To cancel the narrowing of a fold without hiding the text and -subheadings, specify a negative argument. For example, @kbd{M--2 C-c -C-x} exits two folds and leaves the text and subheadings exposed. - - Foldout mode also provides mouse commands for entering and exiting -folds, and for showing and hiding text: - -@table @asis -@item @kbd{C-M-Mouse-1} zooms in on the heading clicked on -@itemize @w{} -@item -single click: expose body. -@item -double click: expose subheadings. -@item -triple click: expose body and subheadings. -@item -quad click: expose entire subtree. -@end itemize -@item @kbd{C-M-Mouse-2} exposes text under the heading clicked on -@itemize @w{} -@item -single click: expose body. -@item -double click: expose subheadings. -@item -triple click: expose body and subheadings. -@item -quad click: expose entire subtree. -@end itemize -@item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold -@itemize @w{} -@item -single click: hide subtree. -@item -double click: exit fold and hide text. -@item -triple click: exit fold without hiding text. -@item -quad click: exit all folds and hide text. -@end itemize -@end table - -@c FIXME not marked as a user variable -@vindex foldout-mouse-modifiers - You can specify different modifier keys (instead of -@kbd{@key{Ctrl}-@key{META}-}) by setting @code{foldout-mouse-modifiers}; but if -you have already loaded the @file{foldout.el} library, you must reload -it in order for this to take effect. - - To use the Foldout package, you can type @kbd{M-x load-library -@key{RET} foldout @key{RET}}; or you can arrange for to do that -automatically by putting the following in your init file: - -@example -(eval-after-load "outline" '(require 'foldout)) -@end example - -@node Org Mode -@section Org Mode -@cindex organizer -@cindex planner -@findex Org mode -@findex mode, Org - -@findex org-mode - Org mode is a variant of Outline mode for using Emacs as an -organizer and/or authoring system. Files with names ending in the -extension @file{.org} are opened in Org mode (@pxref{Choosing Modes}). -To explicitly switch to Org mode, type @kbd{M-x org-mode}. - - In Org mode, as in Outline mode, each entry has a heading line that -starts with one or more @samp{*} characters. @xref{Outline Format}. -In addition, any line that begins with the @samp{#} character is -treated as a comment. - -@kindex TAB @r{(Org Mode)} -@findex org-cycle - Org mode provides commands for easily viewing and manipulating the -outline structure. The simplest of these commands is @key{TAB} -(@code{org-cycle}). If invoked on a heading line, it cycles through -the different visibility states of the subtree: (i) showing only that -heading line, (ii) showing only the heading line and the heading lines -of its direct children, if any, and (iii) showing the entire subtree. -If invoked in a body line, the global binding for @key{TAB} is -executed. - -@kindex S-TAB @r{(Org Mode)} -@findex org-shifttab - Typing @key{S-TAB} (@code{org-shifttab}) anywhere in an Org mode -buffer cycles the visibility of the entire outline structure, between -(i) showing only top-level heading lines, (ii) showing all heading -lines but no body lines, and (iii) showing everything. - -@kindex M- @r{(Org Mode)} -@kindex M- @r{(Org Mode)} -@kindex M- @r{(Org Mode)} -@kindex M- @r{(Org Mode)} -@findex org-metaup -@findex org-metadown -@findex org-metaleft -@findex org-metaright - You can move an entire entry up or down in the buffer, including its -body lines and subtree (if any), by typing @kbd{M-} -(@code{org-metaup}) or @kbd{M-} (@code{org-metadown}) on the -heading line. Similarly, you can promote or demote a heading line -with @kbd{M-} (@code{org-metaleft}) and @kbd{M-} -(@code{org-metaright}). These commands execute their global bindings -if invoked on a body line. - - The following subsections give basic instructions for using Org mode -as an organizer and as an authoring system. For details, @pxref{Top, -The Org Mode Manual, Introduction, org, The Org Manual}. - -@menu -* Org Organizer:: Managing TODO lists and agendas. -* Org Authoring:: Exporting Org buffers to various formats. -@end menu - -@node Org Organizer -@subsection Org as an organizer -@cindex TODO item -@cindex Org agenda - -@kindex C-c C-t @r{(Org Mode)} -@findex org-todo -@vindex org-todo-keywords - You can tag an Org entry as a @dfn{TODO} item by typing @kbd{C-c -C-t} (@code{org-todo}) anywhere in the entry. This adds the keyword -@samp{TODO} to the heading line. Typing @kbd{C-c C-t} again switches -the keyword to @samp{DONE}; another @kbd{C-c C-t} removes the keyword -entirely, and so forth. You can customize the keywords used by -@kbd{C-c C-t} via the variable @code{org-todo-keywords}. - -@kindex C-c C-s @r{(Org Mode)} -@kindex C-c C-d @r{(Org Mode)} -@findex org-schedule -@findex org-deadline - Apart from marking an entry as TODO, you can attach a date to it, by -typing @kbd{C-c C-s} (@code{org-schedule}) in the entry. This prompts -for a date by popping up the Emacs Calendar (@pxref{Calendar/Diary}), -and then adds the tag @samp{SCHEDULED}, together with the selected -date, beneath the heading line. The command @kbd{C-c C-d} -(@code{org-deadline}) has the same effect, except that it uses the tag -@code{DEADLINE}. - -@kindex C-c [ @r{(Org Mode)} -@findex org-agenda-file-to-front -@vindex org-agenda-files - Once you have some TODO items planned in an Org file, you can add -that file to the list of @dfn{agenda files} by typing @kbd{C-c [} -(@code{org-agenda-file-to-front}). Org mode is designed to let you -easily maintain multiple agenda files, e.g., for organizing different -aspects of your life. The list of agenda files is stored in the -variable @code{org-agenda-files}. - -@findex org-agenda - To view items coming from your agenda files, type @kbd{M-x -org-agenda}. This command prompts for what you want to see: a list of -things to do this week, a list of TODO items with specific keywords, -etc. -@ifnottex -@xref{Agenda Views,,,org, The Org Manual}, for details. -@end ifnottex - -@node Org Authoring -@subsection Org as an authoring system -@cindex Org exporting - -@findex org-export -@kindex C-c C-e @r{(Org mode)} - You may want to format your Org notes nicely and to prepare them for -export and publication. To export the current buffer, type @kbd{C-c -C-e} (@code{org-export}) anywhere in an Org buffer. This command -prompts for an export format; currently supported formats include -HTML, @LaTeX{}, OpenDocument (@file{.odt}), and PDF@. Some formats, -such as PDF, require certain system tools to be installed. - -@vindex org-publish-project-alist - To export several files at once to a specific directory, either -locally or over the network, you must define a list of projects -through the variable @code{org-publish-project-alist}. See its -documentation for details. - - Org supports a simple markup scheme for applying text formatting to -exported documents: - -@example -- This text is /emphasized/ -- This text is *in bold* -- This text is _underlined_ -- This text uses =a teletype font= - -#+begin_quote -``This is a quote.'' -#+end_quote - -#+begin_example -This is an example. -#+end_example -@end example - - For further details, @ref{Exporting,,,org, The Org Manual}, and -@ref{Publishing,,,org, The Org Manual}. - -@node TeX Mode -@section @TeX{} Mode -@cindex @TeX{} mode -@cindex @LaTeX{} mode -@cindex Sli@TeX{} mode -@cindex Doc@TeX{} mode -@cindex mode, @TeX{} -@cindex mode, @LaTeX{} -@cindex mode, Sli@TeX{} -@cindex mode, Doc@TeX{} -@findex tex-mode -@findex plain-tex-mode -@findex latex-mode -@findex slitex-mode -@findex doctex-mode -@findex bibtex-mode - - Emacs provides special major modes for editing files written in -@TeX{} and its related formats. @TeX{} is a powerful text formatter -written by Donald Knuth; like GNU Emacs, it is free software. -@LaTeX{} is a simplified input format for @TeX{}, implemented using -@TeX{} macros. Doc@TeX{} is a special file format in which the -@LaTeX{} sources are written, combining sources with documentation. -Sli@TeX{} is an obsolete special form of @LaTeX{}.@footnote{It has -been replaced by the @samp{slides} document class, which comes with -@LaTeX{}.} - -@vindex tex-default-mode - @TeX{} mode has four variants: Plain @TeX{} mode, @LaTeX{} mode, -Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ -only slightly, and are designed for editing the four different -formats. Emacs selects the appropriate mode by looking at the -contents of the buffer. (This is done by the @code{tex-mode} command, -which is normally called automatically when you visit a @TeX{}-like -file. @xref{Choosing Modes}.) If the contents are insufficient to -determine this, Emacs chooses the mode specified by the variable -@code{tex-default-mode}; its default value is @code{latex-mode}. If -Emacs does not guess right, you can select the correct variant of -@TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x -latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}. - - The following sections document the features of @TeX{} mode and its -variants. There are several other @TeX{}-related Emacs packages, -which are not documented in this manual: - -@itemize @bullet -@item -Bib@TeX{} mode is a major mode for Bib@TeX{} files, which are commonly -used for keeping bibliographic references for @LaTeX{} documents. For -more information, see the documentation string for the command -@code{bibtex-mode}. - -@item -The Ref@TeX{} package provides a minor mode which can be used with -@LaTeX{} mode to manage bibliographic references. -@ifinfo -@xref{Top,The Ref@TeX{} Manual,,reftex}. -@end ifinfo -@ifnotinfo -For more information, see the Ref@TeX{} Info manual, which is -distributed with Emacs. -@end ifnotinfo - -@item -The AUC@TeX{} package provides more advanced features for editing -@TeX{} and its related formats, including the ability to preview -@TeX{} equations within Emacs buffers. Unlike Bib@TeX{} mode and the -Ref@TeX{} package, AUC@TeX{} is not distributed with Emacs by default. -It can be downloaded via the Package Menu (@pxref{Packages}); once -installed, see -@ifinfo -@ref{Top,The AUC@TeX{} Manual,,auctex}. -@end ifinfo -@ifnotinfo -the AUC@TeX{} manual, which is included with the package. -@end ifnotinfo -@end itemize - -@menu -* TeX Editing:: Special commands for editing in TeX mode. -* LaTeX Editing:: Additional commands for LaTeX input files. -* TeX Print:: Commands for printing part of a file with TeX. -* TeX Misc:: Customization of TeX mode, and related features. -@end menu - -@node TeX Editing -@subsection @TeX{} Editing Commands - -@table @kbd -@item " -Insert, according to context, either @samp{``} or @samp{"} or -@samp{''} (@code{tex-insert-quote}). -@item C-j -Insert a paragraph break (two newlines) and check the previous -paragraph for unbalanced braces or dollar signs -(@code{tex-terminate-paragraph}). -@item M-x tex-validate-region -Check each paragraph in the region for unbalanced braces or dollar signs. -@item C-c @{ -Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}). -@item C-c @} -Move forward past the next unmatched close brace (@code{up-list}). -@end table - -@findex tex-insert-quote -@kindex " @r{(@TeX{} mode)} - In @TeX{}, the character @samp{"} is not normally used; instead, -quotations begin with @samp{``} and end with @samp{''}. @TeX{} mode -therefore binds the @kbd{"} key to the @code{tex-insert-quote} -command. This inserts @samp{``} after whitespace or an open brace, -@samp{"} after a backslash, and @samp{''} after any other character. - - As a special exception, if you type @kbd{"} when the text before -point is either @samp{``} or @samp{''}, Emacs replaces that preceding -text with a single @samp{"} character. You can therefore type -@kbd{""} to insert @samp{"}, should you ever need to do so. (You can -also use @kbd{C-q "} to insert this character.) - - In @TeX{} mode, @samp{$} has a special syntax code which attempts to -understand the way @TeX{} math mode delimiters match. When you insert a -@samp{$} that is meant to exit math mode, the position of the matching -@samp{$} that entered math mode is displayed for a second. This is the -same feature that displays the open brace that matches a close brace that -is inserted. However, there is no way to tell whether a @samp{$} enters -math mode or leaves it; so when you insert a @samp{$} that enters math -mode, the previous @samp{$} position is shown as if it were a match, even -though they are actually unrelated. - -@findex tex-insert-braces -@kindex C-c @{ @r{(@TeX{} mode)} -@findex up-list -@kindex C-c @} @r{(@TeX{} mode)} - @TeX{} uses braces as delimiters that must match. Some users prefer -to keep braces balanced at all times, rather than inserting them -singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of -braces. It leaves point between the two braces so you can insert the -text that belongs inside. Afterward, use the command @kbd{C-c @}} -(@code{up-list}) to move forward past the close brace. - -@findex tex-validate-region -@findex tex-terminate-paragraph -@kindex C-j @r{(@TeX{} mode)} - There are two commands for checking the matching of braces. -@kbd{C-j} (@code{tex-terminate-paragraph}) checks the paragraph before -point, and inserts two newlines to start a new paragraph. It outputs -a message in the echo area if any mismatch is found. @kbd{M-x -tex-validate-region} checks a region, paragraph by paragraph. The -errors are listed in an @file{*Occur*} buffer; you can use the usual -Occur mode commands in that buffer, such as @kbd{C-c C-c}, to visit a -particular mismatch (@pxref{Other Repeating Search}). - - Note that Emacs commands count square brackets and parentheses in -@TeX{} mode, not just braces. This is not strictly correct for the -purpose of checking @TeX{} syntax. However, parentheses and square -brackets are likely to be used in text as matching delimiters, and it -is useful for the various motion commands and automatic match display -to work with them. - -@node LaTeX Editing -@subsection @LaTeX{} Editing Commands - - @LaTeX{} mode provides a few extra features not applicable to plain -@TeX{}: - -@table @kbd -@item C-c C-o -Insert @samp{\begin} and @samp{\end} for @LaTeX{} block and position -point on a line between them (@code{tex-latex-block}). -@item C-c C-e -Close the innermost @LaTeX{} block not yet closed -(@code{tex-close-latex-block}). -@end table - -@findex tex-latex-block -@kindex C-c C-o @r{(@LaTeX{} mode)} - In @LaTeX{} input, @samp{\begin} and @samp{\end} tags are used to -group blocks of text. To insert a block, type @kbd{C-c C-o} -(@code{tex-latex-block}). This prompts for a block type, and inserts -the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a -blank line between the two and moving point there. - -@vindex latex-block-names - When entering the block type argument to @kbd{C-c C-o}, you can use -the usual completion commands (@pxref{Completion}). The default -completion list contains the standard @LaTeX{} block types. If you -want additional block types for completion, customize the list -variable @code{latex-block-names}. - -@findex tex-close-latex-block -@kindex C-c C-e @r{(@LaTeX{} mode)} -@findex latex-electric-env-pair-mode - In @LaTeX{} input, @samp{\begin} and @samp{\end} tags must balance. -You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an -@samp{\end} tag which matches the last unmatched @samp{\begin}. It -also indents the @samp{\end} to match the corresponding @samp{\begin}, -and inserts a newline after the @samp{\end} tag if point is at the -beginning of a line. The minor mode @code{latex-electric-env-pair-mode} -automatically inserts an @samp{\end} or @samp{\begin} tag for you -when you type the corresponding one. - -@node TeX Print -@subsection @TeX{} Printing Commands - - You can invoke @TeX{} as an subprocess of Emacs, supplying either -the entire contents of the buffer or just part of it (e.g., one -chapter of a larger document). - -@table @kbd -@item C-c C-b -Invoke @TeX{} on the entire current buffer (@code{tex-buffer}). -@item C-c C-r -Invoke @TeX{} on the current region, together with the buffer's header -(@code{tex-region}). -@item C-c C-f -Invoke @TeX{} on the current file (@code{tex-file}). - -@item C-c C-v -Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c -C-f} command (@code{tex-view}). - -@item C-c C-p -Print the output from the last @kbd{C-c C-b}, @kbd{C-c C-r}, or -@kbd{C-c C-f} command (@code{tex-print}). - -@item C-c @key{TAB} -Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}). -@item C-c C-l -Recenter the window showing output from @TeX{} so that the last line -can be seen (@code{tex-recenter-output-buffer}). -@item C-c C-k -Kill the @TeX{} subprocess (@code{tex-kill-job}). -@item C-c C-c -Invoke some other compilation command on the entire current buffer -(@code{tex-compile}). -@end table - -@findex tex-buffer -@kindex C-c C-b @r{(@TeX{} mode)} -@findex tex-view -@kindex C-c C-v @r{(@TeX{} mode)} -@findex tex-print -@kindex C-c C-p @r{(@TeX{} mode)} - To pass the current buffer through @TeX{}, type @kbd{C-c C-b} -(@code{tex-buffer}). The formatted output goes in a temporary file, -normally a @file{.dvi} file. Afterwards, you can type @kbd{C-c C-v} -(@code{tex-view}) to launch an external program, such as -@command{xdvi}, to view this output file. You can also type @kbd{C-c -C-p} (@code{tex-print}) to print a hardcopy of the output file. - -@cindex @env{TEXINPUTS} environment variable -@vindex tex-directory - By default, @kbd{C-c C-b} runs @TeX{} in the current directory. The -output of @TeX{} also goes in this directory. To run @TeX{} in a -different directory, change the variable @code{tex-directory} to the -desired directory name. If your environment variable @env{TEXINPUTS} -contains relative directory names, or if your files contains -@samp{\input} commands with relative file names, then -@code{tex-directory} @emph{must} be @code{"."} or you will get the -wrong results. Otherwise, it is safe to specify some other directory, -such as @code{"/tmp"}. - -@vindex tex-run-command -@vindex latex-run-command -@vindex tex-dvi-view-command -@vindex tex-dvi-print-command - The buffer's @TeX{} variant determines what shell command @kbd{C-c -C-b} actually runs. In Plain @TeX{} mode, it is specified by the -variable @code{tex-run-command}, which defaults to @code{"tex"}. In -@LaTeX{} mode, it is specified by @code{latex-run-command}, which -defaults to @code{"latex"}. The shell command that @kbd{C-c C-v} runs -to view the @file{.dvi} output is determined by the variable -@code{tex-dvi-view-command}, regardless of the @TeX{} variant. The -shell command that @kbd{C-c C-p} runs to print the output is -determined by the variable @code{tex-dvi-print-command}. - - Normally, Emacs automatically appends the output file name to the -shell command strings described in the preceding paragraph. For -example, if @code{tex-dvi-view-command} is @code{"xdvi"}, @kbd{C-c -C-v} runs @command{xdvi @var{output-file-name}}. In some cases, -however, the file name needs to be embedded in the command, e.g., if -you need to provide the file name as an argument to one command whose -output is piped to another. You can specify where to put the file -name with @samp{*} in the command string. For example, - -@example -(setq tex-dvi-print-command "dvips -f * | lpr") -@end example - -@findex tex-kill-job -@kindex C-c C-k @r{(@TeX{} mode)} -@findex tex-recenter-output-buffer -@kindex C-c C-l @r{(@TeX{} mode)} - The terminal output from @TeX{}, including any error messages, -appears in a buffer called @file{*tex-shell*}. If @TeX{} gets an -error, you can switch to this buffer and feed it input (this works as -in Shell mode; @pxref{Interactive Shell}). Without switching to this -buffer you can scroll it so that its last line is visible by typing -@kbd{C-c C-l}. - - Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if -you see that its output is no longer useful. Using @kbd{C-c C-b} or -@kbd{C-c C-r} also kills any @TeX{} process still running. - -@findex tex-region -@kindex C-c C-r @r{(@TeX{} mode)} - You can also pass an arbitrary region through @TeX{} by typing -@kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because -most files of @TeX{} input contain commands at the beginning to set -parameters and define macros, without which no later part of the file -will format correctly. To solve this problem, @kbd{C-c C-r} allows -you to designate a part of the file as containing essential commands; -it is included before the specified region as part of the input to -@TeX{}. The designated part of the file is called the @dfn{header}. - -@cindex header (@TeX{} mode) - To indicate the bounds of the header in Plain @TeX{} mode, you insert two -special strings in the file. Insert @samp{%**start of header} before the -header, and @samp{%**end of header} after it. Each string must appear -entirely on one line, but there may be other text on the line before or -after. The lines containing the two strings are included in the header. -If @samp{%**start of header} does not appear within the first 100 lines of -the buffer, @kbd{C-c C-r} assumes that there is no header. - - In @LaTeX{} mode, the header begins with @samp{\documentclass} or -@samp{\documentstyle} and ends with @samp{\begin@{document@}}. These -are commands that @LaTeX{} requires you to use in any case, so nothing -special needs to be done to identify the header. - -@findex tex-file -@kindex C-c C-f @r{(@TeX{} mode)} - The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their -work in a temporary directory, and do not have available any of the auxiliary -files needed by @TeX{} for cross-references; these commands are generally -not suitable for running the final copy in which all of the cross-references -need to be correct. - - When you want the auxiliary files for cross references, use @kbd{C-c -C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file, -in that file's directory. Before running @TeX{}, it offers to save any -modified buffers. Generally, you need to use (@code{tex-file}) twice to -get the cross-references right. - -@vindex tex-start-options - The value of the variable @code{tex-start-options} specifies -options for the @TeX{} run. - -@vindex tex-start-commands - The value of the variable @code{tex-start-commands} specifies @TeX{} -commands for starting @TeX{}. The default value causes @TeX{} to run -in nonstop mode. To run @TeX{} interactively, set the variable to -@code{""}. - -@vindex tex-main-file - Large @TeX{} documents are often split into several files---one main -file, plus subfiles. Running @TeX{} on a subfile typically does not -work; you have to run it on the main file. In order to make -@code{tex-file} useful when you are editing a subfile, you can set the -variable @code{tex-main-file} to the name of the main file. Then -@code{tex-file} runs @TeX{} on that file. - - The most convenient way to use @code{tex-main-file} is to specify it -in a local variable list in each of the subfiles. @xref{File -Variables}. - -@findex tex-bibtex-file -@kindex C-c TAB @r{(@TeX{} mode)} -@vindex tex-bibtex-command - For @LaTeX{} files, you can use Bib@TeX{} to process the auxiliary -file for the current buffer's file. Bib@TeX{} looks up bibliographic -citations in a data base and prepares the cited references for the -bibliography section. The command @kbd{C-c @key{TAB}} -(@code{tex-bibtex-file}) runs the shell command -(@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the -current buffer's file. Generally, you need to do @kbd{C-c C-f} -(@code{tex-file}) once to generate the @samp{.aux} file, then do -@kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f} -(@code{tex-file}) twice more to get the cross-references correct. - -@findex tex-compile -@kindex C-c C-c @r{(@TeX{} mode)} - To invoke some other compilation program on the current @TeX{} -buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows -how to pass arguments to many common programs, including -@file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can -select your desired compilation program using the standard completion -keys (@pxref{Completion}). - -@node TeX Misc -@subsection @TeX{} Mode Miscellany - -@vindex tex-shell-hook -@vindex tex-mode-hook -@vindex latex-mode-hook -@vindex slitex-mode-hook -@vindex plain-tex-mode-hook - Entering any variant of @TeX{} mode runs the hooks -@code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either -@code{plain-tex-mode-hook}, @code{latex-mode-hook}, or -@code{slitex-mode-hook}, whichever is appropriate. Starting the -@TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}. - -@findex iso-iso2tex -@findex iso-tex2iso -@findex iso-iso2gtex -@findex iso-gtex2iso -@cindex Latin-1 @TeX{} encoding -@cindex @TeX{} encoding - The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x -iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert -between Latin-1 encoded files and @TeX{}-encoded equivalents. - -@node HTML Mode -@section SGML and HTML Modes -@cindex SGML mode -@cindex HTML mode -@cindex mode, SGML -@cindex mode, HTML -@findex sgml-mode -@findex html-mode - - The major modes for SGML and HTML provide indentation support and -commands for operating on tags. HTML mode is a slightly customized -variant of SGML mode. - -@table @kbd -@item C-c C-n -@kindex C-c C-n @r{(SGML mode)} -@findex sgml-name-char -Interactively specify a special character and insert the SGML -@samp{&}-command for that character (@code{sgml-name-char}). - -@item C-c C-t -@kindex C-c C-t @r{(SGML mode)} -@findex sgml-tag -Interactively specify a tag and its attributes (@code{sgml-tag}). -This command asks you for a tag name and for the attribute values, -then inserts both the opening tag and the closing tag, leaving point -between them. - -With a prefix argument @var{n}, the command puts the tag around the -@var{n} words already present in the buffer after point. Whenever a -region is active, it puts the tag around the region (when Transient -Mark mode is off, it does this when a numeric argument of @minus{}1 is -supplied.) - -@item C-c C-a -@kindex C-c C-a @r{(SGML mode)} -@findex sgml-attributes -Interactively insert attribute values for the current tag -(@code{sgml-attributes}). - -@item C-c C-f -@kindex C-c C-f @r{(SGML mode)} -@findex sgml-skip-tag-forward -Skip across a balanced tag group (which extends from an opening tag -through its corresponding closing tag) (@code{sgml-skip-tag-forward}). -A numeric argument acts as a repeat count. - -@item C-c C-b -@kindex C-c C-b @r{(SGML mode)} -@findex sgml-skip-tag-backward -Skip backward across a balanced tag group (which extends from an -opening tag through its corresponding closing tag) -(@code{sgml-skip-tag-backward}). A numeric argument acts as a repeat -count. - -@item C-c C-d -@kindex C-c C-d @r{(SGML mode)} -@findex sgml-delete-tag -Delete the tag at or after point, and delete the matching tag too -(@code{sgml-delete-tag}). If the tag at or after point is an opening -tag, delete the closing tag too; if it is a closing tag, delete the -opening tag too. - -@item C-c ? @var{tag} @key{RET} -@kindex C-c ? @r{(SGML mode)} -@findex sgml-tag-help -Display a description of the meaning of tag @var{tag} -(@code{sgml-tag-help}). If the argument @var{tag} is empty, describe -the tag at point. - -@item C-c / -@kindex C-c / @r{(SGML mode)} -@findex sgml-close-tag -Insert a close tag for the innermost unterminated tag -(@code{sgml-close-tag}). If called within a tag or a comment, -close it instead of inserting a close tag. - -@item C-c 8 -@kindex C-c 8 @r{(SGML mode)} -@findex sgml-name-8bit-mode -Toggle a minor mode in which Latin-1 characters insert the -corresponding SGML commands that stand for them, instead of the -characters themselves (@code{sgml-name-8bit-mode}). - -@item C-c C-v -@kindex C-c C-v @r{(SGML mode)} -@findex sgml-validate -Run a shell command (which you must specify) to validate the current -buffer as SGML (@code{sgml-validate}). - -@item C-c @key{TAB} -@kindex C-c TAB @r{(SGML mode)} -@findex sgml-tags-invisible -Toggle the visibility of existing tags in the buffer. This can be -used as a cheap preview (@code{sgml-tags-invisible}). -@end table - -@cindex nXML mode -@cindex mode, nXML -@findex nxml-mode -@cindex XML schema - The major mode for editing XML documents is called nXML mode. This -is a powerful major mode that can recognize many existing XML schema -and use them to provide completion of XML elements via -@kbd{M-@key{TAB}}, as well as ``on-the-fly'' XML -validation with error highlighting. To enable nXML mode in an -existing buffer, type @kbd{M-x nxml-mode}, or, equivalently, @kbd{M-x -xml-mode}. Emacs uses nXML mode for files which have the extension -@file{.xml}. For XHTML files, which have the extension @file{.xhtml}, -Emacs uses HTML mode by default; you can make it use nXML mode by -customizing the variable @code{auto-mode-alist} (@pxref{Choosing -Modes}). -@ifinfo -nXML mode is described in its own manual: @xref{Top, nXML -Mode,,nxml-mode, nXML Mode}. -@end ifinfo -@ifnotinfo -nXML mode is described in an Info manual, which is distributed with -Emacs. -@end ifnotinfo - -@vindex sgml-xml-mode - You may choose to use the less powerful SGML mode for editing XML, -since XML is a strict subset of SGML@. To enable SGML mode in an -existing buffer, type @kbd{M-x sgml-mode}. On enabling SGML mode, -Emacs examines the buffer to determine whether it is XML; if so, it -sets the variable @code{sgml-xml-mode} to a non-@code{nil} value. -This causes SGML mode's tag insertion commands, described above, to -always insert explicit closing tags as well. - -@node Nroff Mode -@section Nroff Mode - -@cindex nroff -@findex nroff-mode -@vindex nroff-mode-hook - Nroff mode, a major mode derived from Text mode, is -specialized for editing nroff files (e.g., Unix man pages). Type -@kbd{M-x nroff-mode} to enter this mode. Entering Nroff mode runs the -hook @code{text-mode-hook}, then @code{nroff-mode-hook} -(@pxref{Hooks}). - - In Nroff mode, nroff command lines are treated as paragraph -separators, pages are separated by @samp{.bp} commands, and comments -start with backslash-doublequote. It also defines these commands: - -@findex forward-text-line -@findex backward-text-line -@findex count-text-lines -@kindex M-n @r{(Nroff mode)} -@kindex M-p @r{(Nroff mode)} -@kindex M-? @r{(Nroff mode)} -@table @kbd -@item M-n -Move to the beginning of the next line that isn't an nroff command -(@code{forward-text-line}). An argument is a repeat count. -@item M-p -Like @kbd{M-n} but move up (@code{backward-text-line}). -@item M-? -Displays in the echo area the number of text lines (lines that are not -nroff commands) in the region (@code{count-text-lines}). -@end table - -@findex electric-nroff-mode - Electric Nroff mode is a buffer-local minor mode that can be used -with Nroff mode. To toggle this minor mode, type @kbd{M-x -electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each -time you type @key{RET} to end a line containing an nroff command that -opens a kind of grouping, the nroff command to close that grouping is -automatically inserted on the following line. - - If you use Outline minor mode with Nroff mode (@pxref{Outline -Mode}), heading lines are lines of the form @samp{.H} followed by a -number (the header level). - -@node Enriched Text -@section Enriched Text -@cindex Enriched mode -@cindex mode, Enriched -@cindex enriched text -@cindex WYSIWYG -@cindex word processing -@cindex text/enriched MIME format - - Enriched mode is a minor mode for editing formatted text files in a -WYSIWYG (``what you see is what you get'') fashion. When Enriched -mode is enabled, you can apply various formatting properties to the -text in the buffer, such as fonts and colors; upon saving the buffer, -those properties are saved together with the text, using the MIME -@samp{text/enriched} file format. - - Enriched mode is typically used with Text mode (@pxref{Text Mode}). -It is @emph{not} compatible with Font Lock mode, which is used by many -major modes, including most programming language modes, for syntax -highlighting (@pxref{Font Lock}). Unlike Enriched mode, Font Lock -mode assigns text properties automatically, based on the current -buffer contents; those properties are not saved to disk. - - The file @file{enriched.txt} in Emacs's @code{data-directory} -serves as an example of the features of Enriched mode. - -@menu -* Enriched Mode:: Entering and exiting Enriched mode. -* Hard and Soft Newlines:: There are two different kinds of newlines. -* Editing Format Info:: How to edit text properties. -* Enriched Faces:: Bold, italic, underline, etc. -* Enriched Indentation:: Changing the left and right margins. -* Enriched Justification:: Centering, setting text flush with the - left or right margin, etc. -* Enriched Properties:: The "special" text properties submenu. -@end menu - -@node Enriched Mode -@subsection Enriched Mode - - Enriched mode is a buffer-local minor mode (@pxref{Minor Modes}). -When you visit a file that has been saved in the @samp{text/enriched} -format, Emacs automatically enables Enriched mode, and applies the -formatting information in the file to the buffer text. When you save -a buffer with Enriched mode enabled, it is saved using the -@samp{text/enriched} format, including the formatting information. - -@findex enriched-mode - To create a new file of formatted text, visit the nonexistent file -and type @kbd{M-x enriched-mode}. This command actually toggles -Enriched mode. With a prefix argument, it enables Enriched mode if -the argument is positive, and disables Enriched mode otherwise. If -you disable Enriched mode, Emacs no longer saves the buffer using the -@samp{text/enriched} format; any formatting properties that have been -added to the buffer remain in the buffer, but they are not saved to -disk. - -@vindex enriched-translations - Enriched mode does not save all Emacs text properties, only those -specified in the variable @code{enriched-translations}. These include -properties for fonts, colors, indentation, and justification. - -@findex format-decode-buffer - If you visit a file and Emacs fails to recognize that it is in the -@samp{text/enriched} format, type @kbd{M-x format-decode-buffer}. -This command prompts for a file format, and re-reads the file in that -format. Specifying the @samp{text/enriched} format automatically -enables Enriched mode. - - To view a @samp{text/enriched} file in raw form (as plain text with -markup tags rather than formatted text), use @kbd{M-x -find-file-literally} (@pxref{Visiting}). - - @xref{Format Conversion,, Format Conversion, elisp, the Emacs Lisp -Reference Manual}, for details of how Emacs recognizes and converts -file formats like @samp{text/enriched}. @xref{Text Properties,,, -elisp, the Emacs Lisp Reference Manual}, for more information about -text properties. - -@node Hard and Soft Newlines -@subsection Hard and Soft Newlines -@cindex hard newline -@cindex soft newline -@cindex newlines, hard and soft - -@cindex use-hard-newlines - In Enriched mode, Emacs distinguishes between two different kinds of -newlines, @dfn{hard} newlines and @dfn{soft} newlines. You can also -enable or disable this feature in other buffers, by typing @kbd{M-x -use-hard-newlines}. - - Hard newlines are used to separate paragraphs, or anywhere there -needs to be a line break regardless of how the text is filled; soft -newlines are used for filling. The @key{RET} (@code{newline}) and -@kbd{C-o} (@code{open-line}) commands insert hard newlines. The fill -commands, including Auto Fill (@pxref{Auto Fill}), insert only soft -newlines and delete only soft newlines, leaving hard newlines alone. - -@c FIXME: I don't see 'unfilled' in that node. --xfq - Thus, when editing with Enriched mode, you should not use @key{RET} -or @kbd{C-o} to break lines in the middle of filled paragraphs. Use -Auto Fill mode or explicit fill commands (@pxref{Fill Commands}) -instead. Use @key{RET} or @kbd{C-o} where line breaks should always -remain, such as in tables and lists. For such lines, you may also -want to set the justification style to @code{unfilled} -(@pxref{Enriched Justification}). - -@node Editing Format Info -@subsection Editing Format Information - - The easiest way to alter properties is with the @samp{Text -Properties} menu. You can get to this menu from the @samp{Edit} menu -in the menu bar (@pxref{Menu Bar}), or with @kbd{C-Mouse-2} -(@pxref{Menu Mouse Clicks}). Some of the commands in the @samp{Text -Properties} menu are listed below (you can also invoke them with -@kbd{M-x}): - -@table @code -@findex facemenu-remove-face-props -@item Remove Face Properties -Remove face properties from the region -(@code{facemenu-remove-face-props}). - -@findex facemenu-remove-all -@item Remove Text Properties -Remove all text properties from the region, including face properties -(@code{facemenu-remove-all}). - -@findex describe-text-properties -@cindex text properties of characters -@cindex overlays at character position -@cindex widgets at buffer position -@cindex buttons at buffer position -@item Describe Properties -List all text properties and other information about the character -following point (@code{describe-text-properties}). - -@item Display Faces -Display a list of defined faces (@code{list-faces-display}). -@xref{Faces}. - -@item Display Colors -Display a list of defined colors (@code{list-colors-display}). -@xref{Colors}. -@end table - -@noindent -The other menu entries are described in the following sections. - -@node Enriched Faces -@subsection Faces in Enriched Text - - The following commands can be used to add or remove faces -(@pxref{Faces}). Each applies to the text in the region if the mark -is active, and to the next self-inserting character if the mark is -inactive. With a prefix argument, each command applies to the next -self-inserting character even if the region is active. - -@table @kbd -@kindex M-o d @r{(Enriched mode)} -@findex facemenu-set-default -@item M-o d -Remove all @code{face} properties (@code{facemenu-set-default}). - -@kindex M-o b @r{(Enriched mode)} -@findex facemenu-set-bold -@item M-o b -Apply the @code{bold} face (@code{facemenu-set-bold}). - -@kindex M-o i @r{(Enriched mode)} -@findex facemenu-set-italic -@item M-o i -Apply the @code{italic} face (@code{facemenu-set-italic}). - -@kindex M-o l @r{(Enriched mode)} -@findex facemenu-set-bold-italic -@item M-o l -Apply the @code{bold-italic} face (@code{facemenu-set-bold-italic}). - -@kindex M-o u @r{(Enriched mode)} -@findex facemenu-set-underline -@item M-o u -Apply the @code{underline} face (@code{facemenu-set-underline}). - -@kindex M-o o @r{(Enriched mode)} -@findex facemenu-set-face -@item M-o o @var{face} @key{RET} -Apply the face @var{face} (@code{facemenu-set-face}). - -@findex facemenu-set-foreground -@item M-x facemenu-set-foreground -Prompt for a color (@pxref{Colors}), and apply it as a foreground -color. - -@findex facemenu-set-background -@item M-x facemenu-set-background -Prompt for a color, and apply it as a background color. -@end table - -@noindent -These command are also available via the Text Properties menu. - - A self-inserting character normally inherits the face properties -(and most other text properties) from the preceding character in the -buffer. If you use one of the above commands to specify the face for -the next self-inserting character, that character will not inherit the -faces properties from the preceding character, but it will still -inherit other text properties. - - Enriched mode defines two additional faces: @code{excerpt} and -@code{fixed}. These correspond to codes used in the text/enriched -file format. The @code{excerpt} face is intended for quotations; by -default, it appears the same as @code{italic}. The @code{fixed} face -specifies fixed-width text; by default, it appears the same as -@code{bold}. - -@node Enriched Indentation -@subsection Indentation in Enriched Text - - In Enriched mode, you can specify different amounts of indentation -for the right or left margin of a paragraph or a part of a paragraph. -These margins also affect fill commands such as @kbd{M-q} -(@pxref{Filling}). - - The Indentation submenu of Text Properties offers commands -for specifying indentation: - -@table @code -@kindex C-x TAB @r{(Enriched mode)} -@findex increase-left-margin -@item Indent More -Indent the region by 4 columns (@code{increase-left-margin}). In -Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if -you supply a numeric argument, that says how many columns to add to the -margin (a negative argument reduces the number of columns). - -@item Indent Less -Remove 4 columns of indentation from the region. - -@item Indent Right More -Make the text narrower by indenting 4 columns at the right margin. - -@item Indent Right Less -Remove 4 columns of indentation from the right margin. -@end table - -@vindex standard-indent - The variable @code{standard-indent} specifies how many columns these -commands should add to or subtract from the indentation. The default -value is 4. The default right margin for Enriched mode is controlled -by the variable @code{fill-column}, as usual. - -@kindex C-c [ @r{(Enriched mode)} -@kindex C-c ] @r{(Enriched mode)} -@findex set-left-margin -@findex set-right-margin - You can also type @kbd{C-c [} (@code{set-left-margin}) and @kbd{C-c -]} (@code{set-right-margin}) to set the left and right margins. You -can specify the margin width with a numeric argument; otherwise these -commands prompt for a value via the minibuffer. - - The fill prefix, if any, works in addition to the specified paragraph -indentation: @kbd{C-x .} does not include the specified indentation's -whitespace in the new value for the fill prefix, and the fill commands -look for the fill prefix after the indentation on each line. @xref{Fill -Prefix}. - -@node Enriched Justification -@subsection Justification in Enriched Text -@cindex justification style - - In Enriched mode, you can use the following commands to specify -various @dfn{justification styles} for filling. These commands apply -to the paragraph containing point, or, if the region is active, to all -paragraphs overlapping the region. - -@table @kbd -@kindex M-j l @r{(Enriched mode)} -@findex set-justification-left -@item M-j l -Align lines to the left margin (@code{set-justification-left}). - -@kindex M-j r @r{(Enriched mode)} -@findex set-justification-right -@item M-j r -Align lines to the right margin (@code{set-justification-right}). - -@kindex M-j b @r{(Enriched mode)} -@findex set-justification-full -@item M-j b -Align lines to both margins, inserting spaces in the middle of the -line to achieve this (@code{set-justification-full}). - -@kindex M-j c @r{(Enriched mode)} -@kindex M-S @r{(Enriched mode)} -@findex set-justification-center -@item M-j c -@itemx M-S -Center lines between the margins (@code{set-justification-center}). - -@kindex M-j u @r{(Enriched mode)} -@findex set-justification-none -@item M-j u -Turn off filling entirely (@code{set-justification-none}). The fill -commands do nothing on text with this setting. You can, however, -still indent the left margin. -@end table - -@vindex default-justification - You can also specify justification styles using the Justification -submenu in the Text Properties menu. The default justification style -is specified by the per-buffer variable @code{default-justification}. -Its value should be one of the symbols @code{left}, @code{right}, -@code{full}, @code{center}, or @code{none}; their meanings correspond -to the commands above. - -@node Enriched Properties -@subsection Setting Other Text Properties - - The Special Properties submenu of Text Properties has entries for -adding or removing three other text properties: @code{read-only}, -(which disallows alteration of the text), @code{invisible} (which -hides text), and @code{intangible} (which disallows moving point -within the text). The @samp{Remove Special} menu item removes all of -these special properties from the text in the region. - - The @code{invisible} and @code{intangible} properties are not saved. - -@node Text Based Tables -@section Editing Text-based Tables -@cindex table mode -@cindex text-based tables - - The @code{table} package provides commands to easily edit text-based -tables. Here is an example of what such a table looks like: - -@smallexample -@group -+-----------------+--------------------------------+-----------------+ -| Command | Description | Key Binding | -+-----------------+--------------------------------+-----------------+ -| forward-char |Move point right N characters | C-f | -| |(left if N is negative). | | -| | | | -+-----------------+--------------------------------+-----------------+ -| backward-char |Move point left N characters | C-b | -| |(right if N is negative). | | -| | | | -+-----------------+--------------------------------+-----------------+ -@end group -@end smallexample - - When Emacs recognizes such a stretch of text as a table -(@pxref{Table Recognition}), editing the contents of each table cell -will automatically resize the table, whenever the contents become too -large to fit in the cell. You can use the commands defined in the -following sections for navigating and editing the table layout. - -@findex table-fixed-width-mode - Type @kbd{M-x table-fixed-width-mode} to toggle the automatic table -resizing feature. - -@menu -* Table Definition:: What is a text based table. -* Table Creation:: How to create a table. -* Table Recognition:: How to activate and deactivate tables. -* Cell Commands:: Cell-oriented commands in a table. -* Cell Justification:: Justifying cell contents. -* Table Rows and Columns:: Inserting and deleting rows and columns. -* Table Conversion:: Converting between plain text and tables. -* Table Misc:: Table miscellany. -@end menu - -@node Table Definition -@subsection What is a Text-based Table? -@cindex cells, for text-based tables - - A @dfn{table} consists of a rectangular text area which is divided -into @dfn{cells}. Each cell must be at least one character wide and -one character high, not counting its border lines. A cell can be -subdivided into more cells, but they cannot overlap. - - Cell border lines are drawn with three special characters, specified -by the following variables: - -@table @code -@vindex table-cell-vertical-char -@item table-cell-vertical-char -The character used for vertical lines. The default is @samp{|}. - -@vindex table-cell-horizontal-chars -@item table-cell-horizontal-chars -The characters used for horizontal lines. The default is @samp{"-="}. - -@vindex table-cell-intersection-char -@item table-cell-intersection-char -The character used for the intersection of horizontal and vertical -lines. The default is @samp{+}. -@end table - -@noindent -The following are examples of @emph{invalid} tables: - -@example - +-----+ +--+ +-++--+ - | | | | | || | - | | | | | || | - +--+ | +--+--+ +-++--+ - | | | | | | +-++--+ - | | | | | | | || | - +--+--+ +--+--+ +-++--+ - a b c -@end example - -@noindent -From left to right: - -@enumerate a -@item -Overlapped cells or non-rectangular cells are not allowed. -@item -The border must be rectangular. -@item -Cells must have a minimum width/height of one character. -@end enumerate - -@node Table Creation -@subsection Creating a Table -@cindex create a text-based table -@cindex table creation - -@findex table-insert - To create a text-based table from scratch, type @kbd{M-x -table-insert}. This command prompts for the number of table columns, -the number of table rows, cell width and cell height. The cell width -and cell height do not include the cell borders; each can be specified -as a single integer (which means each cell is given the same -width/height), or as a sequence of integers separated by spaces or -commas (which specify the width/height of the individual table -columns/rows, counting from left to right for table columns and from -top to bottom for table rows). The specified table is then inserted -at point. - - The table inserted by @kbd{M-x table-insert} contains special text -properties, which tell Emacs to treat it specially as a text-based -table. If you save the buffer to a file and visit it again later, -those properties are lost, and the table appears to Emacs as an -ordinary piece of text. See the next section, for how to convert it -back into a table. - -@node Table Recognition -@subsection Table Recognition -@cindex table recognition - -@findex table-recognize -@findex table-unrecognize - Existing text-based tables in a buffer, which lack the special text -properties applied by @kbd{M-x table-insert}, are not treated -specially as tables. To apply those text properties, type @kbd{M-x -table-recognize}. This command scans the current buffer, -@dfn{recognizes} valid table cells, and applies the relevant text -properties. Conversely, type @kbd{M-x table-unrecognize} to -@dfn{unrecognize} all tables in the current buffer, removing the -special text properties and converting tables back to plain text. - - You can also use the following commands to selectively recognize or -unrecognize tables: - -@table @kbd -@findex table-recognize-region -@item M-x table-recognize-region -Recognize tables within the current region. - -@findex table-unrecognize-region -@item M-x table-unrecognize-region -Unrecognize tables within the current region. - -@findex table-recognize-table -@item M-x table-recognize-table -Recognize the table at point and activate it. - -@findex table-unrecognize-table -@item M-x table-unrecognize-table -Deactivate the table at point. - -@findex table-recognize-cell -@item M-x table-recognize-cell -Recognize the cell at point and activate it. - -@findex table-unrecognize-cell -@item M-x table-unrecognize-cell -Deactivate the cell at point. -@end table - - @xref{Table Conversion}, for another way to recognize a table. - -@node Cell Commands -@subsection Commands for Table Cells - -@findex table-forward-cell -@findex table-backward-cell - The commands @kbd{M-x table-forward-cell} and @kbd{M-x -table-backward-cell} move point from the current cell to an adjacent -cell. The order is cyclic: when point is in the last cell of a table, -@kbd{M-x table-forward-cell} moves to the first cell. Likewise, when -point is on the first cell, @kbd{M-x table-backward-cell} moves to the -last cell. - -@findex table-span-cell - @kbd{M-x table-span-cell} prompts for a direction---right, left, -above, or below---and merges the current cell with the adjacent cell -in that direction. This command signals an error if the merge would -result in an illegitimate cell layout. - -@findex table-split-cell -@findex table-split-cell-vertically -@findex table-split-cell-horizontally -@cindex text-based tables, splitting cells -@cindex splitting table cells - @kbd{M-x table-split-cell} splits the current cell vertically or -horizontally, prompting for the direction with the minibuffer. To -split in a specific direction, use @kbd{M-x -table-split-cell-vertically} and @kbd{M-x -table-split-cell-horizontally}. When splitting vertically, the old -cell contents are automatically split between the two new cells. When -splitting horizontally, you are prompted for how to divide the cell -contents, if the cell is non-empty; the options are @samp{split} -(divide the contents at point), @samp{left} (put all the contents in -the left cell), and @samp{right} (put all the contents in the right -cell). - - The following commands enlarge or shrink a cell. By default, they -resize by one row or column; if a numeric argument is supplied, that -specifies the number of rows or columns to resize by. - -@table @kbd -@findex table-heighten-cell -@item M-x table-heighten-cell -Enlarge the current cell vertically. - -@findex table-shorten-cell -@item M-x table-shorten-cell -Shrink the current cell vertically. - -@findex table-widen-cell -@item M-x table-widen-cell -Enlarge the current cell horizontally. - -@findex table-narrow-cell -@item M-x table-narrow-cell -Shrink the current cell horizontally. -@end table - -@node Cell Justification -@subsection Cell Justification -@cindex justification in text-based tables - - The command @kbd{M-x table-justify} imposes @dfn{justification} on -one or more cells in a text-based table. Justification determines how -the text in the cell is aligned, relative to the edges of the cell. -Each cell in a table can be separately justified. - -@findex table-justify - @kbd{M-x table-justify} first prompts for what to justify; the -options are @samp{cell} (just the current cell), @samp{column} (all -cells in the current table column) and @samp{row} (all cells in the -current table row). The command then prompts for the justification -style; the options are @code{left}, @code{center}, @code{right}, -@code{top}, @code{middle}, @code{bottom}, or @code{none} (meaning no -vertical justification). - - Horizontal and vertical justification styles are specified -independently, and both types can be in effect simultaneously; for -instance, you can call @kbd{M-x table-justify} twice, once to specify -@code{right} justification and once to specify @code{bottom} -justification, to align the contents of a cell to the bottom right. - -@vindex table-detect-cell-alignment - The justification style is stored in the buffer as a text property, -and is lost when you kill the buffer or exit Emacs. However, the -table recognition commands, such as @kbd{M-x table-recognize} -(@pxref{Table Recognition}), attempt to determine and re-apply each -cell's justification style, by examining its contents. To disable -this feature, change the variable @code{table-detect-cell-alignment} -to @code{nil}. - -@node Table Rows and Columns -@subsection Table Rows and Columns -@cindex inserting rows and columns in text-based tables - -@findex table-insert-row - @kbd{M-x table-insert-row} inserts a row of cells before the current -table row. The current row, together with point, is pushed down past -the new row. To insert a row after the last row at the bottom of a -table, invoke this command with point below the table, just below the -bottom edge. You can insert more than one row at a time by using a -numeric prefix argument. - -@c A numeric prefix argument specifies the number of rows to insert. - -@findex table-insert-column - Similarly, @kbd{M-x table-insert-column} inserts a column of cells -to the left of the current table column. To insert a column to the -right side of the rightmost column, invoke this command with point to -the right of the rightmost column, outside the table. A numeric -prefix argument specifies the number of columns to insert. - -@cindex deleting rows and column in text-based tables - @kbd{M-x table-delete-column} deletes the column of cells at point. -Similarly, @kbd{M-x table-delete-row} deletes the row of cells at -point. A numeric prefix argument to either command specifies the -number of columns or rows to delete. - -@node Table Conversion -@subsection Converting Between Plain Text and Tables -@cindex text to table -@cindex table to text - -@findex table-capture - The command @kbd{M-x table-capture} captures plain text in a region -and turns it into a table. Unlike @kbd{M-x table-recognize} -(@pxref{Table Recognition}), the original text does not need to have a -table appearance; it only needs to have a logical table-like -structure. - - For example, suppose we have the following numbers, which are -divided into three lines and separated horizontally by commas: - -@example -1, 2, 3, 4 -5, 6, 7, 8 -, 9, 10 -@end example - -@noindent -Invoking @kbd{M-x table-capture} on that text produces this table: - -@example -+-----+-----+-----+-----+ -|1 |2 |3 |4 | -+-----+-----+-----+-----+ -|5 |6 |7 |8 | -+-----+-----+-----+-----+ -| |9 |10 | | -+-----+-----+-----+-----+ -@end example - -@findex table-release - @kbd{M-x table-release} does the opposite: it converts a table back -to plain text, removing its cell borders. - - One application of this pair of commands is to edit a text in -layout. Look at the following three paragraphs (the latter two are -indented with header lines): - -@example -table-capture is a powerful command. -Here are some things it can do: - -Parse Cell Items Using row and column delimiter regexps, - it parses the specified text area and - extracts cell items into a table. -@end example - -@noindent -Applying @code{table-capture} to a region containing the above text, -with empty strings for the column and row delimiter regexps, creates a -table with a single cell like the following one. - -@smallexample -@group -+----------------------------------------------------------+ -|table-capture is a powerful command. | -|Here are some things it can do: | -| | -|Parse Cell Items Using row and column delimiter regexps,| -| it parses the specified text area and | -| extracts cell items into a table. | -+----------------------------------------------------------+ -@end group -@end smallexample - -@noindent -We can then use the cell splitting commands (@pxref{Cell Commands}) to -subdivide the table so that each paragraph occupies a cell: - -@smallexample -+----------------------------------------------------------+ -|table-capture is a powerful command. | -|Here are some things it can do: | -+-----------------+----------------------------------------+ -|Parse Cell Items | Using row and column delimiter regexps,| -| | it parses the specified text area and | -| | extracts cell items into a table. | -+-----------------+----------------------------------------+ -@end smallexample - -@noindent -Each cell can now be edited independently without affecting the layout -of other cells. When finished, we can invoke @kbd{M-x table-release} -to convert the table back to plain text. - -@node Table Misc -@subsection Table Miscellany - -@cindex table dimensions -@findex table-query-dimension - The command @code{table-query-dimension} reports the layout of the -table and table cell at point. Here is an example of its output: - -@smallexample -Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5 -@end smallexample - -@noindent -This indicates that the current cell is 21 characters wide and 6 lines -high, the table is 67 characters wide and 16 lines high with 2 columns -and 3 rows, and a total of 5 cells. - -@findex table-insert-sequence - @kbd{M-x table-insert-sequence} inserts a string into each cell. -Each string is a part of a sequence i.e., a series of increasing -integer numbers. - -@cindex table for HTML and LaTeX -@findex table-generate-source - @kbd{M-x table-generate-source} generates a table formatted for a -specific markup language. It asks for a language (which must be one -of @code{html}, @code{latex}, or @code{cals}), a destination buffer in -which to put the result, and a table caption, and then inserts the -generated table into the specified buffer. The default destination -buffer is @code{table.@var{lang}}, where @var{lang} is the language -you specified. - -@node Two-Column -@section Two-Column Editing -@cindex two-column editing -@cindex splitting columns -@cindex columns, splitting - - Two-column mode lets you conveniently edit two side-by-side columns -of text. It uses two side-by-side windows, each showing its own -buffer. There are three ways to enter two-column mode: - -@table @asis -@item @kbd{@key{F2} 2} or @kbd{C-x 6 2} -@kindex F2 2 -@kindex C-x 6 2 -@findex 2C-two-columns -Enter two-column mode with the current buffer on the left, and on the -right, a buffer whose name is based on the current buffer's name -(@code{2C-two-columns}). If the right-hand buffer doesn't already -exist, it starts out empty; the current buffer's contents are not -changed. - -This command is appropriate when the current buffer is empty or contains -just one column and you want to add another column. - -@item @kbd{@key{F2} s} or @kbd{C-x 6 s} -@kindex F2 s -@kindex C-x 6 s -@findex 2C-split -Split the current buffer, which contains two-column text, into two -buffers, and display them side by side (@code{2C-split}). The current -buffer becomes the left-hand buffer, but the text in the right-hand -column is moved into the right-hand buffer. The current column -specifies the split point. Splitting starts with the current line and -continues to the end of the buffer. - -This command is appropriate when you have a buffer that already contains -two-column text, and you wish to separate the columns temporarily. - -@item @kbd{@key{F2} b @var{buffer} @key{RET}} -@itemx @kbd{C-x 6 b @var{buffer} @key{RET}} -@kindex F2 b -@kindex C-x 6 b -@findex 2C-associate-buffer -Enter two-column mode using the current buffer as the left-hand buffer, -and using buffer @var{buffer} as the right-hand buffer -(@code{2C-associate-buffer}). -@end table - - @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which -is a string that appears on each line between the two columns. You can -specify the width of the separator with a numeric argument to -@kbd{@key{F2} s}; that many characters, before point, constitute the -separator string. By default, the width is 1, so the column separator -is the character before point. - - When a line has the separator at the proper place, @kbd{@key{F2} s} -puts the text after the separator into the right-hand buffer, and -deletes the separator. Lines that don't have the column separator at -the proper place remain unsplit; they stay in the left-hand buffer, and -the right-hand buffer gets an empty line to correspond. (This is the -way to write a line that ``spans both columns while in two-column -mode'': write it in the left-hand buffer, and put an empty line in the -right-hand buffer.) - -@kindex F2 RET -@kindex C-x 6 RET -@findex 2C-newline - The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}} -(@code{2C-newline}) inserts a newline in each of the two buffers at -corresponding positions. This is the easiest way to add a new line to -the two-column text while editing it in split buffers. - -@kindex F2 1 -@kindex C-x 6 1 -@findex 2C-merge - When you have edited both buffers as you wish, merge them with -@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the -text from the right-hand buffer as a second column in the other buffer. -To go back to two-column editing, use @kbd{@key{F2} s}. - -@kindex F2 d -@kindex C-x 6 d -@findex 2C-dissociate - Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers, -leaving each as it stands (@code{2C-dissociate}). If the other buffer, -the one not current when you type @kbd{@key{F2} d}, is empty, -@kbd{@key{F2} d} kills it. diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi deleted file mode 100644 index 09260a1e5a9..00000000000 --- a/doc/emacs/trouble.texi +++ /dev/null @@ -1,1238 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Dealing with Common Problems - - If you type an Emacs command you did not intend, the results are often -mysterious. This chapter tells what you can do to cancel your mistake or -recover from a mysterious situation. Emacs bugs and system crashes are -also considered. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Quitting -@section Quitting and Aborting -@cindex quitting - -@table @kbd -@item C-g -@itemx C-@key{Break} @r{(MS-DOS only)} -Quit: cancel running or partially typed command. -@item C-] -Abort innermost recursive editing level and cancel the command which -invoked it (@code{abort-recursive-edit}). -@item @key{ESC} @key{ESC} @key{ESC} -Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). -@item M-x top-level -Abort all recursive editing levels that are currently executing. -@item C-/ -@itemx C-x u -@itemx C-_ -Cancel a previously made change in the buffer contents (@code{undo}). -@end table - - There are two ways of canceling a command before it has finished: -@dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or -@kbd{M-x top-level}. Quitting cancels a partially typed command, or -one which is still running. Aborting exits a recursive editing level -and cancels the command that invoked the recursive edit -(@pxref{Recursive Edit}). - -@cindex quitting -@kindex C-g - Quitting with @kbd{C-g} is the way to get rid of a partially typed -command, or a numeric argument that you don't want. Furthermore, if -you are in the middle of a command that is running, @kbd{C-g} stops -the command in a relatively safe way. For example, if you quit out of -a kill command that is taking a long time, either your text will -@emph{all} still be in the buffer, or it will @emph{all} be in the -kill ring, or maybe both. If the region is active, @kbd{C-g} -deactivates the mark, unless Transient Mark mode is off -(@pxref{Disabled Transient Mark}). If you are in the middle of an -incremental search, @kbd{C-g} behaves specially; it may take two -successive @kbd{C-g} characters to get out of a search. -@xref{Incremental Search}, for details. - - On MS-DOS, the character @kbd{C-@key{Break}} serves as a quit character -like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to -recognize @kbd{C-g} while a command is running, between interactions -with the user. By contrast, it @emph{is} feasible to recognize -@kbd{C-@key{Break}} at all times. -@iftex -@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{MS-DOS Keyboard}. -@end ifnottex - -@findex keyboard-quit - @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} -the instant @kbd{C-g} is typed; Emacs Lisp checks this variable -frequently, and quits if it is non-@code{nil}. @kbd{C-g} is only -actually executed as a command if you type it while Emacs is waiting for -input. In that case, the command it runs is @code{keyboard-quit}. - - On a text terminal, if you quit with @kbd{C-g} a second time before -the first @kbd{C-g} is recognized, you activate the ``emergency -escape'' feature and return to the shell. @xref{Emergency Escape}. - -@cindex NFS and quitting - There are some situations where you cannot quit. When Emacs is -waiting for the operating system to do something, quitting is -impossible unless special pains are taken for the particular system -call within Emacs where the waiting occurs. We have done this for the -system calls that users are likely to want to quit from, but it's -possible you will encounter a case not handled. In one very common -case---waiting for file input or output using NFS---Emacs itself knows -how to quit, but many NFS implementations simply do not allow user -programs to stop waiting for NFS when the NFS server is hung. - -@cindex aborting recursive edit -@findex abort-recursive-edit -@kindex C-] - Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get -out of a recursive editing level and cancel the command which invoked -it. Quitting with @kbd{C-g} does not do this, and could not do this, -because it is used to cancel a partially typed command @emph{within} the -recursive editing level. Both operations are useful. For example, if -you are in a recursive edit and type @kbd{C-u 8} to enter a numeric -argument, you can cancel that argument with @kbd{C-g} and remain in the -recursive edit. - -@findex keyboard-escape-quit -@kindex ESC ESC ESC - The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}} -(@code{keyboard-escape-quit}) can either quit or abort. (We defined -it this way because @key{ESC} means ``get out'' in many PC programs.) -It can cancel a prefix argument, clear a selected region, or get out -of a Query Replace, like @kbd{C-g}. It can get out of the minibuffer -or a recursive edit, like @kbd{C-]}. It can also get out of splitting -the frame into multiple windows, as with @kbd{C-x 1}. One thing it -cannot do, however, is stop a command that is running. That's because -it executes as an ordinary command, and Emacs doesn't notice it until -it is ready for the next command. - -@findex top-level - The command @kbd{M-x top-level} is equivalent to ``enough'' -@kbd{C-]} commands to get you out of all the levels of recursive edits -that you are in; it also exits the minibuffer if it is active. -@kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level} -goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} -are like all other commands, and unlike @kbd{C-g}, in that they take -effect only when Emacs is ready for a command. @kbd{C-]} is an -ordinary key and has its meaning only because of its binding in the -keymap. @xref{Recursive Edit}. - - @kbd{C-/} (@code{undo}) is not strictly speaking a way of canceling -a command, but you can think of it as canceling a command that already -finished executing. @xref{Undo}, for more information about the undo -facility. - -@node Lossage -@section Dealing with Emacs Trouble -@cindex troubleshooting Emacs - - This section describes how to recognize and deal with situations in -which Emacs does not work as you expect, such as keyboard code mixups, -garbled displays, running out of memory, and crashes and hangs. - - @xref{Bugs}, for what to do when you think you have found a bug in -Emacs. - -@menu -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. -* Screen Garbled:: Garbage on the screen. -* Text Garbled:: Garbage in the text. -* Memory Full:: How to cope when you run out of memory. -* Crashing:: What Emacs does when it crashes. -* After a Crash:: Recovering editing in an Emacs session that crashed. -* Emergency Escape:: What to do if Emacs stops responding. -@end menu - -@node DEL Does Not Delete -@subsection If @key{DEL} Fails to Delete -@cindex @key{DEL} vs @key{BACKSPACE} -@cindex @key{BACKSPACE} vs @key{DEL} -@cindex @key{DEL} does not delete - - Every keyboard has a large key, usually labeled @key{BACKSPACE}, -which is ordinarily used to erase the last character that you typed. -In Emacs, this key is supposed to be equivalent to @key{DEL}. - - When Emacs starts up on a graphical display, it determines -automatically which key should be @key{DEL}. In some unusual cases, -Emacs gets the wrong information from the system, and @key{BACKSPACE} -ends up deleting forwards instead of backwards. - - Some keyboards also have a @key{Delete} key, which is ordinarily -used to delete forwards. If this key deletes backward in Emacs, that -too suggests Emacs got the wrong information---but in the opposite -sense. - - On a text terminal, if you find that @key{BACKSPACE} prompts for a -Help command, like @kbd{Control-h}, instead of deleting a character, -it means that key is actually sending the @samp{BS} character. Emacs -ought to be treating @key{BS} as @key{DEL}, but it isn't. - -@findex normal-erase-is-backspace-mode - In all of those cases, the immediate remedy is the same: use the -command @kbd{M-x normal-erase-is-backspace-mode}. This toggles -between the two modes that Emacs supports for handling @key{DEL}, so -if Emacs starts in the wrong mode, this should switch to the right -mode. On a text terminal, if you want to ask for help when @key{BS} -is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also work, if it -sends character code 127. - - To fix the problem in every Emacs session, put one of the following -lines into your initialization file (@pxref{Init File}). For the -first case above, where @key{BACKSPACE} deletes forwards instead of -backwards, use this line to make @key{BACKSPACE} act as @key{DEL}: - -@lisp -(normal-erase-is-backspace-mode 0) -@end lisp - -@noindent -For the other two cases, use this line: - -@lisp -(normal-erase-is-backspace-mode 1) -@end lisp - -@vindex normal-erase-is-backspace - Another way to fix the problem for every Emacs session is to -customize the variable @code{normal-erase-is-backspace}: the value -@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is -@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy -Customization}. - -@node Stuck Recursive -@subsection Recursive Editing Levels -@cindex stuck in recursive editing -@cindex recursive editing, cannot exit - - Recursive editing levels are important and useful features of Emacs, but -they can seem like malfunctions if you do not understand them. - - If the mode line has square brackets @samp{[@dots{}]} around the -parentheses that contain the names of the major and minor modes, you -have entered a recursive editing level. If you did not do this on -purpose, or if you don't understand what that means, you should just -get out of the recursive editing level. To do so, type @kbd{M-x -top-level}. @xref{Recursive Edit}. - -@node Screen Garbled -@subsection Garbage on the Screen -@cindex garbled display -@cindex display, incorrect -@cindex screen display, wrong - - If the text on a text terminal looks wrong, the first thing to do is -see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay -the entire screen. If the screen appears correct after this, the -problem was entirely in the previous screen update. (Otherwise, see -the following section.) - - Display updating problems often result from an incorrect terminfo -entry for the terminal you are using. The file @file{etc/TERMS} in -the Emacs distribution gives the fixes for known problems of this -sort. @file{INSTALL} contains general advice for these problems in -one of its sections. If you seem to be using the right terminfo -entry, it is possible that there is a bug in the terminfo entry, or a -bug in Emacs that appears for certain terminal types. - -@node Text Garbled -@subsection Garbage in the Text -@cindex garbled text -@cindex buffer text garbled - - If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to -see what commands you typed to produce the observed results. Then try -undoing the changes step by step using @kbd{C-x u}, until it gets back -to a state you consider correct. - - If a large portion of text appears to be missing at the beginning or -end of the buffer, check for the word @samp{Narrow} in the mode line. -If it appears, the text you don't see is probably still present, but -temporarily off-limits. To make it accessible again, type @kbd{C-x n -w}. @xref{Narrowing}. - -@node Memory Full -@subsection Running out of Memory -@cindex memory full -@cindex out of memory - - If you get the error message @samp{Virtual memory exceeded}, save -your modified buffers with @kbd{C-x s}. This method of saving them -has the smallest need for additional memory. Emacs keeps a reserve of -memory which it makes available when this error happens; that should -be enough to enable @kbd{C-x s} to complete its work. When the -reserve has been used, @samp{!MEM FULL!} appears at the beginning of -the mode line, indicating there is no more reserve. - - Once you have saved your modified buffers, you can exit this Emacs -session and start another, or you can use @kbd{M-x kill-some-buffers} -to free space in the current Emacs job. If this frees up sufficient -space, Emacs will refill its memory reserve, and @samp{!MEM FULL!} -will disappear from the mode line. That means you can safely go on -editing in the same Emacs session. - - Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run -out of memory, because the Buffer Menu needs a fair amount of memory -itself, and the reserve supply may not be enough. - -@node Crashing -@subsection When Emacs Crashes - -@cindex crash report -@cindex backtrace -@cindex @file{emacs_backtrace.txt} file, MS-Windows - Emacs is not supposed to crash, but if it does, it produces a -@dfn{crash report} prior to exiting. The crash report is printed to -the standard error stream. If Emacs was started from a graphical -desktop on a GNU or Unix system, the standard error stream is commonly -redirected to a file such as @file{~/.xsession-errors}, so you can -look for the crash report there. On MS-Windows, the crash report is -written to a file named @file{emacs_backtrace.txt} in the current -directory of the Emacs process, in addition to the standard error -stream. - - The format of the crash report depends on the platform. On some -platforms, such as those using the GNU C Library, the crash report -includes a @dfn{backtrace} describing the execution state prior to -crashing, which can be used to help debug the crash. Here is an -example for a GNU system: - -@example -Fatal error 11: Segmentation fault -Backtrace: -emacs[0x5094e4] -emacs[0x4ed3e6] -emacs[0x4ed504] -/lib64/libpthread.so.0[0x375220efe0] -/lib64/libpthread.so.0(read+0xe)[0x375220e08e] -emacs[0x509af6] -emacs[0x5acc26] -@dots{} -@end example - -@noindent -The number @samp{11} is the system signal number corresponding to the -crash---in this case a segmentation fault. The hexadecimal numbers -are program addresses, which can be associated with source code lines -using a debugging tool. For example, the GDB command -@samp{list *0x509af6} prints the source-code lines corresponding to -the @samp{emacs[0x509af6]} entry. If your system has the -@command{addr2line} utility, the following shell command outputs a -backtrace with source-code line numbers: - -@example -sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} | - addr2line -C -f -i -p -e @var{bindir}/@var{emacs-binary} -@end example - -@noindent -Here, @var{backtrace} is the name of a text file containing a copy of -the backtrace, @var{bindir} is the name of the directory that -contains the Emacs executable, and @var{emacs-binary} is the name of -the Emacs executable file, normally @file{emacs} on GNU and Unix -systems and @file{emacs.exe} on MS-Windows and MS-DOS. Omit the -@option{-p} option if your version of @command{addr2line} is too old -to have it. - -@cindex core dump - Optionally, Emacs can generate a @dfn{core dump} when it crashes, on -systems that support core files. A core dump is a file containing -voluminous data about the state of the program prior to the crash, -usually examined by loading it into a debugger such as GDB@. On many -platforms, core dumps are disabled by default, and you must explicitly -enable them by running the shell command @samp{ulimit -c unlimited} -(e.g., in your shell startup script). - -@node After a Crash -@subsection Recovery After a Crash -@cindex recovering crashed session - - If Emacs or the computer crashes, you can recover the files you were -editing at the time of the crash from their auto-save files. To do -this, start Emacs again and type the command @kbd{M-x recover-session}. - - This command initially displays a buffer which lists interrupted -session files, each with its date. You must choose which session to -recover from. Typically the one you want is the most recent one. Move -point to the one you choose, and type @kbd{C-c C-c}. - - Then @code{recover-session} considers each of the files that you -were editing during that session; for each such file, it asks whether -to recover that file. If you answer @kbd{y} for a file, it shows the -dates of that file and its auto-save file, then asks once again -whether to recover that file. For the second question, you must -confirm with @kbd{yes}. If you do, Emacs visits the file but gets the -text from the auto-save file. - - When @code{recover-session} is done, the files you've chosen to -recover are present in Emacs buffers. You should then save them. Only -this---saving them---updates the files themselves. - - As a last resort, if you had buffers with content which were not -associated with any files, or if the autosave was not recent enough to -have recorded important changes, you can use the -@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to -retrieve them from a core dump--provided that a core dump was saved, -and that the Emacs executable was not stripped of its debugging -symbols. - - As soon as you get the core dump, rename it to another name such as -@file{core.emacs}, so that another crash won't overwrite it. - - To use this script, run @code{gdb} with the file name of your Emacs -executable and the file name of the core dump, e.g., @samp{gdb -/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the -recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}. -Then type the command @code{ybuffer-list} to see which buffers are -available. For each buffer, it lists a buffer number. To save a -buffer, use @code{ysave-buffer}; you specify the buffer number, and -the file name to write that buffer into. You should use a file name -which does not already exist; if the file does exist, the script does -not make a backup of its old contents. - -@node Emergency Escape -@subsection Emergency Escape -@cindex emergency escape - - On text terminals, the @dfn{emergency escape} feature suspends Emacs -immediately if you type @kbd{C-g} a second time before Emacs can -actually respond to the first one by quitting. This is so you can -always get out of GNU Emacs no matter how badly it might be hung. -When things are working properly, Emacs recognizes and handles the -first @kbd{C-g} so fast that the second one won't trigger emergency -escape. However, if some problem prevents Emacs from handling the -first @kbd{C-g} properly, then the second one will get you back to the -shell. - - When you resume Emacs after a suspension caused by emergency escape, -it asks two questions before going back to what it had been doing: - -@example -Auto-save? (y or n) -Abort (and dump core)? (y or n) -@end example - -@noindent -Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. - - Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of -all modified buffers in which auto-saving is enabled. Saying @kbd{n} -skips this. - - Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to -crash, dumping core. This is to enable a wizard to figure out why -Emacs was failing to quit in the first place. Execution does not -continue after a core dump. - - If you answer this question @kbd{n}, Emacs execution resumes. With -luck, Emacs will ultimately do the requested quit. If not, each -subsequent @kbd{C-g} invokes emergency escape again. - - If Emacs is not really hung, just slow, you may invoke the double -@kbd{C-g} feature without really meaning to. Then just resume and -answer @kbd{n} to both questions, and you will get back to the former -state. The quit you requested will happen by and by. - - Emergency escape is active only for text terminals. On graphical -displays, you can use the mouse to kill Emacs or switch to another -program. - - On MS-DOS, you must type @kbd{C-@key{Break}} (twice) to cause -emergency escape---but there are cases where it won't work, when -system call hangs or when Emacs is stuck in a tight loop in C code. - -@node Bugs -@section Reporting Bugs - -@cindex bugs - If you think you have found a bug in Emacs, please report it. We -cannot promise to fix it, or always to agree that it is a bug, but we -certainly want to hear about it. The same applies for new features -you would like to see added. The following sections will help you to -construct an effective bug report. - -@menu -* Known Problems:: How to read about known problems and bugs. -* Criteria: Bug Criteria. Have you really found a bug? -* Understanding Bug Reporting:: How to report a bug effectively. -* Checklist:: Steps to follow for a good bug report. -* Sending Patches:: How to send a patch for GNU Emacs. -@end menu - -@node Known Problems -@subsection Reading Existing Bug Reports and Known Problems - - Before reporting a bug, if at all possible please check to see if it -is already known about. Indeed, it may already have been fixed in a -later release of Emacs, or in the development version. Here is a list -of the main places you can read about known issues: - -@itemize -@item -The @file{etc/PROBLEMS} file; type @kbd{C-h C-p} to read it. This -file contains a list of particularly well-known issues that have been -encountered in compiling, installing and running Emacs. Often, there -are suggestions for workarounds and solutions. - -@item -Some additional user-level problems can be found in @ref{Bugs and -problems, , Bugs and problems, efaq, GNU Emacs FAQ}. - -@cindex bug tracker -@item -The GNU Bug Tracker at @url{http://debbugs.gnu.org}. Emacs bugs are -filed in the tracker under the @samp{emacs} package. The tracker -records information about the status of each bug, the initial bug -report, and the follow-up messages by the bug reporter and Emacs -developers. You can search for bugs by subject, severity, and other -criteria. - -@cindex debbugs package -Instead of browsing the bug tracker as a webpage, you can browse it -from Emacs using the @code{debbugs} package, which can be downloaded -via the Package Menu (@pxref{Packages}). This package provides the -command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x -debbugs-gnu-search} to search for a specific bug. User tags, applied -by the Emacs maintainers, are shown by @kbd{M-x debbugs-gnu-usertags}. - -@item -The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup -@samp{gnu.emacs.bug}). You can read the list archives at -@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. This list -works as a ``mirror'' of the Emacs bug reports and follow-up messages -which are sent to the bug tracker. It also contains old bug reports -from before the bug tracker was introduced (in early 2008). - -If you like, you can subscribe to the list. Be aware that its purpose -is to provide the Emacs maintainers with information about bugs and -feature requests, so reports may contain fairly large amounts of data; -spectators should not complain about this. - -@item -The @samp{emacs-pretest-bug} mailing list. This list is no longer -used, and is mainly of historical interest. At one time, it was used -for bug reports in development (i.e., not yet released) versions of -Emacs. You can read the archives for 2003 to mid 2007 at -@url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. Nowadays, -it is an alias for @samp{bug-gnu-emacs}. - -@item -The @samp{emacs-devel} mailing list. Sometimes people report bugs to -this mailing list. This is not the main purpose of the list, however, -and it is much better to send bug reports to the bug list. You should -not feel obliged to read this list before reporting a bug. - -@end itemize - - -@node Bug Criteria -@subsection When Is There a Bug -@cindex bug criteria -@cindex what constitutes an Emacs bug - - If Emacs accesses an invalid memory location (``segmentation -fault''), or exits with an operating system error message that -indicates a problem in the program (as opposed to something like -``disk full''), then it is certainly a bug. - - If the Emacs display does not correspond properly to the contents of -the buffer, then it is a bug. But you should check that features like -buffer narrowing (@pxref{Narrowing}), which can hide parts of the -buffer or change how it is displayed, are not responsible. - - Taking forever to complete a command can be a bug, but you must make -sure that it is really Emacs's fault. Some commands simply take a -long time. Type @kbd{C-g} (@kbd{C-@key{Break}} on MS-DOS) and then -@kbd{C-h l} to see whether the input Emacs received was what you -intended to type; if the input was such that you @emph{know} it should -have been processed quickly, report a bug. If you don't know whether -the command should take a long time, find out by looking in the manual -or by asking for assistance. - - If a command you are familiar with causes an Emacs error message in a -case where its usual definition ought to be reasonable, it is probably a -bug. - - If a command does the wrong thing, that is a bug. But be sure you -know for certain what it ought to have done. If you aren't familiar -with the command, it might actually be working right. If in doubt, -read the command's documentation (@pxref{Name Help}). - - A command's intended definition may not be the best possible -definition for editing with. This is a very important sort of -problem, but it is also a matter of judgment. Also, it is easy to -come to such a conclusion out of ignorance of some of the existing -features. It is probably best not to complain about such a problem -until you have checked the documentation in the usual ways, feel -confident that you understand it, and know for certain that what you -want is not available. Ask other Emacs users, too. If you are not -sure what the command is supposed to do after a careful reading of the -manual, check the index and glossary for any terms that may be -unclear. - - If after careful rereading of the manual you still do not understand -what the command should do, that indicates a bug in the manual, which -you should report. The manual's job is to make everything clear to -people who are not Emacs experts---including you. It is just as -important to report documentation bugs as program bugs. - - If the built-in documentation for a function or variable disagrees -with the manual, one of them must be wrong; that is a bug. - -@node Understanding Bug Reporting -@subsection Understanding Bug Reporting -@cindex bug reporting -@cindex report an Emacs bug, how to - -@findex emacs-version - When you decide that there is a bug, it is important to report it -and to report it in a way which is useful. What is most useful is an -exact description of what commands you type, starting with the shell -command to run Emacs, until the problem happens. - - The most important principle in reporting a bug is to report -@emph{facts}. Hypotheses and verbal descriptions are no substitute -for the detailed raw data. Reporting the facts is straightforward, -but many people strain to posit explanations and report them instead -of the facts. If the explanations are based on guesses about how -Emacs is implemented, they will be useless; meanwhile, lacking the -facts, we will have no real information about the bug. If you want to -actually @emph{debug} the problem, and report explanations that are -more than guesses, that is useful---but please include the raw facts -as well. - - For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh -@key{RET}}, visiting a file which (you know) happens to be rather -large, and Emacs displays @samp{I feel pretty today}. The bug report -would need to provide all that information. You should not assume -that the problem is due to the size of the file and say, ``I visited a -large file, and Emacs displayed @samp{I feel pretty today}.'' This is -what we mean by ``guessing explanations''. The problem might be due -to the fact that there is a @samp{z} in the file name. If this is so, -then when we got your report, we would try out the problem with some -``large file'', probably with no @samp{z} in its name, and not see any -problem. There is no way we could guess that we should try visiting a -file with a @samp{z} in its name. - - You should not even say ``visit a file'' instead of @kbd{C-x C-f}. -Similarly, rather than saying ``if I have three characters on the -line'', say ``after I type @kbd{@key{RET} A B C @key{RET} C-p}'', if -that is the way you entered the text. - - If possible, try quickly to reproduce the bug by invoking Emacs with -@command{emacs -Q} (so that Emacs starts with no initial -customizations; @pxref{Initial Options}), and repeating the steps that -you took to trigger the bug. If you can reproduce the bug this way, -that rules out bugs in your personal customizations. Then your bug -report should begin by stating that you started Emacs with -@command{emacs -Q}, followed by the exact sequence of steps for -reproducing the bug. If possible, inform us of the exact contents of -any file that is needed to reproduce the bug. - - Some bugs are not reproducible from @command{emacs -Q}; some are not -easily reproducible at all. In that case, you should report what you -have---but, as before, please stick to the raw facts about what you -did to trigger the bug the first time. - - If you have multiple issues that you want to report, please make a -separate bug report for each. - -@node Checklist -@subsection Checklist for Bug Reports -@cindex checklist before reporting a bug -@cindex bug reporting, checklist - - Before reporting a bug, first try to see if the problem has already -been reported (@pxref{Known Problems}). - -If you are able to, try the latest release of Emacs to see if the -problem has already been fixed. Even better is to try the latest -development version. We recognize that this is not easy for some -people, so do not feel that you absolutely must do this before making -a report. - -@findex report-emacs-bug - The best way to write a bug report for Emacs is to use the command -@kbd{M-x report-emacs-bug}. This sets up a mail buffer -(@pxref{Sending Mail}) and automatically inserts @emph{some} of the -essential information. However, it cannot supply all the necessary -information; you should still read and follow the guidelines below, so -you can enter the other crucial information by hand before you send -the message. You may feel that some of the information inserted by -@kbd{M-x report-emacs-bug} is not relevant, but unless you are -absolutely sure it is best to leave it, so that the developers can -decide for themselves. - -When you have finished writing your report, type @kbd{C-c C-c} and it -will be sent to the Emacs maintainers at -@ifnothtml -@email{bug-gnu-emacs@@gnu.org}. -@end ifnothtml -@ifhtml -@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}. -@end ifhtml -(If you want to suggest an improvement or new feature, use the same -address.) If you cannot send mail from inside Emacs, you can copy the -text of your report to your normal mail client (if your system -supports it, you can type @kbd{C-c M-i} to have Emacs do this for you) -and send it to that address. Or you can simply send an email to that -address describing the problem. - -Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and -stored in the GNU Bug Tracker at @url{http://debbugs.gnu.org}. Please -include a valid reply email address, in case we need to ask you for -more information about your report. Submissions are moderated, so -there may be a delay before your report appears. - -You do not need to know how the Gnu Bug Tracker works in order to -report a bug, but if you want to, you can read the tracker's online -documentation to see the various features you can use. - -All mail sent to the @samp{bug-gnu-emacs} mailing list is also -gatewayed to the @samp{gnu.emacs.bug} newsgroup. The reverse is also -true, but we ask you not to post bug reports (or replies) via the -newsgroup. It can make it much harder to contact you if we need to ask -for more information, and it does not integrate well with the bug -tracker. - -If your data is more than 500,000 bytes, please don't include it -directly in the bug report; instead, offer to send it on request, or -make it available by ftp and say where. - - To enable maintainers to investigate a bug, your report -should include all these things: - -@itemize @bullet -@item -The version number of Emacs. Without this, we won't know whether there is any -point in looking for the bug in the current version of GNU Emacs. - -@kbd{M-x report-emacs-bug} includes this information automatically, -but if you are not using that command for your report you can get the -version number by typing @kbd{M-x emacs-version @key{RET}}. If that -command does not work, you probably have something other than GNU -Emacs, so you will have to report the bug somewhere else. - -@item -The type of machine you are using, and the operating system name and -version number (again, automatically included by @kbd{M-x -report-emacs-bug}). @kbd{M-x emacs-version @key{RET}} provides this -information too. Copy its output from the @file{*Messages*} buffer, -so that you get it all and get it accurately. - -@item -The operands given to the @code{configure} command when Emacs was -installed (automatically included by @kbd{M-x report-emacs-bug}). - -@item -A complete list of any modifications you have made to the Emacs source. -(We may not have time to investigate the bug unless it happens in an -unmodified Emacs. But if you've made modifications and you don't tell -us, you are sending us on a wild goose chase.) - -Be precise about these changes. A description in English is not -enough---send a context diff for them. - -Adding files of your own, or porting to another machine, is a -modification of the source. - -@item -Details of any other deviations from the standard procedure for installing -GNU Emacs. - -@item -The complete text of any files needed to reproduce the bug. - - If you can tell us a way to cause the problem without visiting any files, -please do so. This makes it much easier to debug. If you do need files, -make sure you arrange for us to see their exact contents. For example, it -can matter whether there are spaces at the ends of lines, or a -newline after the last line in the buffer (nothing ought to care whether -the last line is terminated, but try telling the bugs that). - -@item -The precise commands we need to type to reproduce the bug. If at all -possible, give a full recipe for an Emacs started with the @samp{-Q} -option (@pxref{Initial Options}). This bypasses your personal -customizations. - -@findex open-dribble-file -@cindex dribble file -@cindex logging keystrokes -One way to record the input to Emacs precisely is to write a dribble -file. To start the file, use the @kbd{M-x open-dribble-file -@key{RET}} command. From then on, Emacs copies all your input to the -specified dribble file until the Emacs process is killed. Be aware -that sensitive information (such as passwords) may end up recorded in -the dribble file. - -@item -@findex open-termscript -@cindex termscript file -@cindex @env{TERM} environment variable -For possible display bugs, the terminal type (the value of environment -variable @env{TERM}), the complete termcap entry for the terminal from -@file{/etc/termcap} (since that file is not identical on all machines), -and the output that Emacs actually sent to the terminal. - -The way to collect the terminal output is to execute the Lisp expression - -@example -(open-termscript "~/termscript") -@end example - -@noindent -using @kbd{M-:} or from the @file{*scratch*} buffer just after -starting Emacs. From then on, Emacs copies all terminal output to the -specified termscript file as well, until the Emacs process is killed. -If the problem happens when Emacs starts up, put this expression into -your Emacs initialization file so that the termscript file will be -open when Emacs displays the screen for the first time. - -Be warned: it is often difficult, and sometimes impossible, to fix a -terminal-dependent bug without access to a terminal of the type that -stimulates the bug. - -@item -If non-@acronym{ASCII} text or internationalization is relevant, the locale that -was current when you started Emacs. On GNU/Linux and Unix systems, or -if you use a Posix-style shell such as Bash, you can use this shell -command to view the relevant values: - -@smallexample -echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \ - LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG -@end smallexample - -Alternatively, use the @command{locale} command, if your system has it, -to display your locale settings. - -You can use the @kbd{M-!} command to execute these commands from -Emacs, and then copy the output from the @file{*Messages*} buffer into -the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL -@key{RET}} will display the value of @code{LC_ALL} in the echo area, and -you can copy its output from the @file{*Messages*} buffer. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``The Emacs process gets a fatal signal'', or, -``The resulting text is as follows, which I think is wrong.'' - -Of course, if the bug is that Emacs gets a fatal signal, then one can't -miss it. But if the bug is incorrect text, the maintainer might fail to -notice what is wrong. Why leave it to chance? - -Even if the problem you experience is a fatal signal, you should still -say so explicitly. Suppose something strange is going on, such as, your -copy of the source is out of sync, or you have encountered a bug in the -C library on your system. (This has happened!) Your copy might crash -and the copy here might not. If you @emph{said} to expect a crash, then -when Emacs here fails to crash, we would know that the bug was not -happening. If you don't say to expect a crash, then we would not know -whether the bug was happening---we would not be able to draw any -conclusion from our observations. - -@item -If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual -fails to describe the actual behavior of Emacs, or that the text is -confusing, copy in the text from the manual which you think is -at fault. If the section is small, just the section name is enough. - -@item -If the manifestation of the bug is an Emacs error message, it is -important to report the precise text of the error message, and a -backtrace showing how the Lisp program in Emacs arrived at the error. - -To get the error message text accurately, copy it from the -@file{*Messages*} buffer into the bug report. Copy all of it, not just -part. - -@findex toggle-debug-on-error -@pindex Edebug -To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} -before the error happens (that is to say, you must give that command -and then make the bug happen). This causes the error to start the Lisp -debugger, which shows you a backtrace. Copy the text of the -debugger's backtrace into the bug report. @xref{Edebug,, Edebug, -elisp, the Emacs Lisp Reference Manual}, for information on debugging -Emacs Lisp programs with the Edebug package. - -This use of the debugger is possible only if you know how to make the -bug happen again. If you can't make it happen again, at least copy -the whole error message. - -@vindex debug-on-quit -If Emacs appears to be stuck in an infinite loop or in a very long -operation, typing @kbd{C-g} with the variable @code{debug-on-quit} -non-@code{nil} will start the Lisp debugger and show a backtrace. -This backtrace is useful for debugging such long loops, so if you can -produce it, copy it into the bug report. - -@vindex debug-on-event -If you cannot get Emacs to respond to @kbd{C-g} (e.g., because -@code{inhibit-quit} is set), then you can try sending the signal -specified by @code{debug-on-event} (default SIGUSR2) from outside -Emacs to cause it to enter the debugger. - -@item -Check whether any programs you have loaded into the Lisp world, -including your initialization file, set any variables that may affect -the functioning of Emacs. Also, see whether the problem happens in a -freshly started Emacs without loading your initialization file (start -Emacs with the @code{-Q} switch to prevent loading the init files). -If the problem does @emph{not} occur then, you must report the precise -contents of any programs that you must load into the Lisp world in -order to cause the problem to occur. - -@item -If the problem does depend on an init file or other Lisp programs that -are not part of the standard Emacs system, then you should make sure it -is not a bug in those programs by complaining to their maintainers -first. After they verify that they are using Emacs in a way that is -supposed to work, they should report the bug. - -@item -If you wish to mention something in the GNU Emacs source, show the line -of code with a few lines of context. Don't just give a line number. - -The line numbers in the development sources don't match those in your -sources. It would take extra work for the maintainers to determine what -code is in your version at a given line number, and we could not be -certain. - -@item -Additional information from a C debugger such as GDB might enable -someone to find a problem on a machine which he does not have available. -If you don't know how to use GDB, please read the GDB manual---it is not -very long, and using GDB is easy. You can find the GDB distribution, -including the GDB manual in online form, in most of the same places you -can find the Emacs distribution. To run Emacs under GDB, you should -switch to the @file{src} subdirectory in which Emacs was compiled, then -do @samp{gdb emacs}. It is important for the directory @file{src} to be -current so that GDB will read the @file{.gdbinit} file in this -directory. - -However, you need to think when you collect the additional information -if you want it to show what causes the bug. - -@cindex backtrace for bug reports -For example, many people send just a backtrace, but that is not very -useful by itself. A simple backtrace with arguments often conveys -little about what is happening inside GNU Emacs, because most of the -arguments listed in the backtrace are pointers to Lisp objects. The -numeric values of these pointers have no significance whatever; all that -matters is the contents of the objects they point to (and most of the -contents are themselves pointers). - -@findex debug_print -To provide useful information, you need to show the values of Lisp -objects in Lisp notation. Do this for each variable which is a Lisp -object, in several stack frames near the bottom of the stack. Look at -the source to see which variables are Lisp objects, because the debugger -thinks of them as integers. - -To show a variable's value in Lisp syntax, first print its value, then -use the user-defined GDB command @code{pr} to print the Lisp object in -Lisp syntax. (If you must use another debugger, call the function -@code{debug_print} with the object as an argument.) The @code{pr} -command is defined by the file @file{.gdbinit}, and it works only if you -are debugging a running process (not with a core dump). - -To make Lisp errors stop Emacs and return to GDB, put a breakpoint at -@code{Fsignal}. - -For a short listing of Lisp functions running, type the GDB -command @code{xbacktrace}. - -The file @file{.gdbinit} defines several other commands that are useful -for examining the data types and contents of Lisp objects. Their names -begin with @samp{x}. These commands work at a lower level than -@code{pr}, and are less convenient, but they may work even when -@code{pr} does not, such as when debugging a core dump or when Emacs has -had a fatal signal. - -@cindex debugging Emacs, tricks and techniques -More detailed advice and other useful techniques for debugging Emacs -are available in the file @file{etc/DEBUG} in the Emacs distribution. -That file also includes instructions for investigating problems -whereby Emacs stops responding (many people assume that Emacs is -``hung'', whereas in fact it might be in an infinite loop). - -To find the file @file{etc/DEBUG} in your Emacs installation, use the -directory name stored in the variable @code{data-directory}. -@end itemize - -Here are some things that are not necessary in a bug report: - -@itemize @bullet -@item -A description of the envelope of the bug---this is not necessary for a -reproducible bug. - -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. - -This is often time-consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger -with breakpoints, not by pure deduction from a series of examples. -You might as well save time by not searching for additional examples. -It is better to send the bug report right away, go back to editing, -and find another bug to report. - -Of course, if you can find a simpler example to report @emph{instead} of -the original one, that is a convenience. Errors in the output will be -easier to spot, running under the debugger will take less time, etc. - -However, simplification is not vital; if you can't do this or don't have -time to try, please report the bug with your original test case. - -@item -A core dump file. - -Debugging the core dump might be useful, but it can only be done on -your machine, with your Emacs executable. Therefore, sending the core -dump file to the Emacs maintainers won't be useful. Above all, don't -include the core file in an email bug report! Such a large message -can be extremely inconvenient. - -@item -A system-call trace of Emacs execution. - -System-call traces are very useful for certain special kinds of -debugging, but in most cases they give little useful information. It is -therefore strange that many people seem to think that @emph{the} way to -report information about a crash is to send a system-call trace. Perhaps -this is a habit formed from experience debugging programs that don't -have source code or debugging symbols. - -In most programs, a backtrace is normally far, far more informative than -a system-call trace. Even in Emacs, a simple backtrace is generally -more informative, though to give full information you should supplement -the backtrace by displaying variable values and printing them as Lisp -objects with @code{pr} (see above). - -@item -A patch for the bug. - -A patch for the bug is useful if it is a good one. But don't omit the -other information that a bug report needs, such as the test case, on the -assumption that a patch is sufficient. We might see problems with your -patch and decide to fix the problem another way, or we might not -understand it at all. And if we can't understand what bug you are -trying to fix, or why your patch should be an improvement, we mustn't -install it. - -@ifnottex -@xref{Sending Patches}, for guidelines on how to make it easy for us to -understand and install your patches. -@end ifnottex - -@item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even experts can't guess right about -such things without first using the debugger to find the facts. -@end itemize - -@node Sending Patches -@subsection Sending Patches for GNU Emacs - -@cindex sending patches for GNU Emacs -@cindex patches, sending - If you would like to write bug fixes or improvements for GNU Emacs, -that is very helpful. When you send your changes, please follow these -guidelines to make it easy for the maintainers to use them. If you -don't follow these guidelines, your information might still be useful, -but using it will take extra work. Maintaining GNU Emacs is a lot of -work in the best of circumstances, and we can't keep up unless you do -your best to help. - -@itemize @bullet -@item -Send an explanation with your changes of what problem they fix or what -improvement they bring about. For a fix for an existing bug, it is -best to reply to the relevant discussion on the @samp{bug-gnu-emacs} -list, or the bug entry in the GNU Bug Tracker at -@url{http://debbugs.gnu.org}. Explain why your change fixes the bug. - -@item -Always include a proper bug report for the problem you think you have -fixed. We need to convince ourselves that the change is right before -installing it. Even if it is correct, we might have trouble -understanding it if we don't have a way to reproduce the problem. - -@item -Include all the comments that are appropriate to help people reading the -source in the future understand why this change was needed. - -@item -Don't mix together changes made for different reasons. -Send them @emph{individually}. - -If you make two changes for separate reasons, then we might not want to -install them both. We might want to install just one. If you send them -all jumbled together in a single set of diffs, we have to do extra work -to disentangle them---to figure out which parts of the change serve -which purpose. If we don't have time for this, we might have to ignore -your changes entirely. - -If you send each change as soon as you have written it, with its own -explanation, then two changes never get tangled up, and we can consider -each one properly without any extra work to disentangle them. - -@item -Send each change as soon as that change is finished. Sometimes people -think they are helping us by accumulating many changes to send them all -together. As explained above, this is absolutely the worst thing you -could do. - -Since you should send each change separately, you might as well send it -right away. That gives us the option of installing it immediately if it -is important. - -@item -Use @samp{diff -c} to make your diffs. Diffs without context are hard -to install reliably. More than that, they are hard to study; we must -always study a patch to decide whether we want to install it. Unidiff -format is better than contextless diffs, but not as easy to read as -@samp{-c} format. - -If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when -making diffs of C code. This shows the name of the function that each -change occurs in. - -@item -Avoid any ambiguity as to which is the old version and which is the new. -Please make the old version the first argument to diff, and the new -version the second argument. And please give one version or the other a -name that indicates whether it is the old version or your new changed -one. - -@item -Write the change log entries for your changes. This is both to save us -the extra work of writing them, and to help explain your changes so we -can understand them. - -The purpose of the change log is to show people where to find what was -changed. So you need to be specific about what functions you changed; -in large functions, it's often helpful to indicate where within the -function the change was. - -On the other hand, once you have shown people where to find the change, -you need not explain its purpose in the change log. Thus, if you add a -new function, all you need to say about it is that it is new. If you -feel that the purpose needs explaining, it probably does---but put the -explanation in comments in the code. It will be more useful there. - -Please read the @file{ChangeLog} files in the @file{src} and -@file{lisp} directories to see what sorts of information to put in, -and to learn the style that we use. @xref{Change Log}. - -@item -When you write the fix, keep in mind that we can't install a change that -would break other systems. Please think about what effect your change -will have if compiled on another type of system. - -Sometimes people send fixes that @emph{might} be an improvement in -general---but it is hard to be sure of this. It's hard to install -such changes because we have to study them very carefully. Of course, -a good explanation of the reasoning by which you concluded the change -was correct can help convince us. - -The safest changes are changes to the configuration files for a -particular machine. These are safe because they can't create new bugs -on other machines. - -Please help us keep up with the workload by designing the patch in a -form that is clearly safe to install. -@end itemize - -@c FIXME: Include the node above? -@node Contributing -@section Contributing to Emacs Development -@cindex contributing to Emacs - -If you would like to work on improving Emacs, please contact the maintainers at -@ifnothtml -@email{emacs-devel@@gnu.org}. -@end ifnothtml -@ifhtml -@url{http://lists.gnu.org/mailman/listinfo/emacs-devel, the -emacs-devel mailing list}. -@end ifhtml -You can ask for suggested projects or suggest your own ideas. - -If you have already written an improvement, please tell us about it. If -you have not yet started work, it is useful to contact -@ifnothtml -@email{emacs-devel@@gnu.org} -@end ifnothtml -@ifhtml -@url{http://lists.gnu.org/mailman/listinfo/emacs-devel, emacs-devel} -@end ifhtml -before you start; it might be possible to suggest ways to make your -extension fit in better with the rest of Emacs. - -The development version of Emacs can be downloaded from the -repository where it is actively maintained by a group of developers. -See the Emacs project page -@url{http://savannah.gnu.org/projects/emacs/} for details. - -For more information on how to contribute, see the -@ifset WWW_GNU_ORG -@ifhtml -@url{http://gnu.org/software/emacs/CONTRIBUTE, etc/CONTRIBUTE} -@end ifhtml -@ifnothtml -@file{etc/CONTRIBUTE} -@end ifnothtml -@end ifset -@ifclear WWW_GNU_ORG -@file{etc/CONTRIBUTE} -@end ifclear -file in the Emacs distribution. - -@node Service -@section How To Get Help with GNU Emacs -@cindex help in using Emacs -@cindex help-gnu-emacs mailing list -@cindex gnu.emacs.help newsgroup - -If you need help installing, using or changing GNU Emacs, there are two -ways to find it: - -@itemize @bullet -@item -Send a message to -@ifnothtml -the mailing list @email{help-gnu-emacs@@gnu.org}, -@end ifnothtml -@ifhtml -@url{http://lists.gnu.org/mailman/listinfo/help-gnu-emacs, the -help-gnu-emacs mailing list}, -@end ifhtml -or post your request on newsgroup @code{gnu.emacs.help}. (This -mailing list and newsgroup interconnect, so it does not matter which -one you use.) - -@item -Look in the @uref{http://www.fsf.org/resources/service/, service -directory} for someone who might help you for a fee. -@end itemize - -@ifnottex -@lowersections -@end ifnottex diff --git a/doc/emacs/vc-xtra.texi b/doc/emacs/vc-xtra.texi deleted file mode 100644 index 52fee145b42..00000000000 --- a/doc/emacs/vc-xtra.texi +++ /dev/null @@ -1,25 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included in emacs-xtra.texi when producing the printed -@c version. -@iftex -@node Advanced VC Usage -@section Advanced VC Usage - - Commonly used features of Emacs's version control (VC) support are -described in the main Emacs manual (@pxref{Version Control,,,emacs, -the Emacs Manual}). This chapter describes more advanced VC usage. - -@menu -* Remote Repositories:: Efficient access to remote VCS servers. -* Revision Tags:: Symbolic names for revisions. -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end menu -@end iftex - -@iftex -@include vc1-xtra.texi -@end iftex diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi deleted file mode 100644 index dd52d97780d..00000000000 --- a/doc/emacs/vc1-xtra.texi +++ /dev/null @@ -1,447 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in vc-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). - -@node Miscellaneous VC -@subsection Miscellaneous Commands and Features of VC - - This section explains the less-frequently-used features of VC. - -@menu -* Change Logs and VC:: Generating a change log file from log entries. -* VC Delete/Rename:: Deleting and renaming version-controlled files. -* Revision Tags:: Symbolic names for revisions. -* Version Headers:: Inserting version control headers into working files. -@end menu - -@node Change Logs and VC -@subsubsection Change Logs and VC - - If you use RCS or CVS for a program with a @file{ChangeLog} file -@iftex -(@pxref{Change Log,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Change Log}), -@end ifnottex -you can generate change log entries from the version control log -entries of previous commits. - - Note that this only works with RCS or CVS@. This procedure would be -particularly incorrect on a modern changeset-based version control -system, where changes to the @file{ChangeLog} file would normally be -committed as part of a changeset. In that case, you should write the -change log entries first, then pull them into the @samp{*vc-log*} -buffer when you commit -@iftex -(@pxref{Log Buffer,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Log Buffer}). -@end ifnottex - -@table @kbd -@item C-x v a -@kindex C-x v a -@findex vc-update-change-log -Visit the current directory's @file{ChangeLog} file and, for -registered files in that directory, create new entries for versions -committed since the most recent change log entry -(@code{vc-update-change-log}). - -@item C-u C-x v a -As above, but only find entries for the current buffer's file. -@end table - - For example, suppose the first line of @file{ChangeLog} is dated -1999-04-10, and that the only check-in since then was by Nathaniel -Bowditch to @file{rcs2log} on 1999-05-22 with log entry @samp{Ignore -log messages that start with `#'.}. Then @kbd{C-x v a} inserts this -@file{ChangeLog} entry: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-22 Nathaniel Bowditch - - * rcs2log: Ignore log messages that start with `#'. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - -@noindent -If the version control log entry specifies a function name (in -parenthesis at the beginning of a line), that is reflected in the -@file{ChangeLog} entry. For example, if a log entry for @file{vc.el} -is @samp{(vc-do-command): Check call-process status.}, the -@file{ChangeLog} entry is: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-06 Nathaniel Bowditch - - * vc.el (vc-do-command): Check call-process status. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - - When @kbd{C-x v a} adds several change log entries at once, it -groups related log entries together if they all are checked in by the -same author at nearly the same time. If the log entries for several -such files all have the same text, it coalesces them into a single -entry. - -@node VC Delete/Rename -@subsubsection Deleting and Renaming Version-Controlled Files -@cindex renaming version-controlled files - -@table @kbd -@item M-x vc-delete-file -Prompt for a file name, delete the file from the working tree, and -schedule the deletion for committing. - -@item M-x vc-rename-file -Prompt for two file names, @var{var} and @var{old}, rename them in the -working tree, and schedule the renaming for committing. -@end table - -@findex vc-delete-file - If you wish to delete a version-controlled file, use the command -@kbd{M-x vc-delete-file}. This prompts for the file name, and deletes -it via the version control system. The file is removed from the -working tree, and in the VC Directory buffer -@iftex -(@pxref{VC Directory Mode,,, emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{VC Directory Mode}), -@end ifnottex -it is displayed with the @samp{removed} status. When you commit it, -the deletion takes effect in the repository. - -@findex vc-rename-file - To rename a version-controlled file, type @kbd{M-x vc-rename-file}. -This prompts for two arguments: the name of the file you wish to -rename, and the new name; then it performs the renaming via the -version control system. The renaming takes effect immediately in the -working tree, and takes effect in the repository when you commit the -renamed file. - - On modern version control systems that have built-in support for -renaming, the renamed file retains the full change history of the -original file. On CVS and older version control systems, the -@code{vc-rename-file} command actually works by creating a copy of the -old file under the new name, registering it, and deleting the old -file. In this case, the change history is not preserved. - -@node Revision Tags -@subsubsection Revision Tags -@cindex revision tag -@cindex tags for version control - - Most version control systems allow you to apply a @dfn{revision tag} -to a specific version of a version-controlled tree. On modern -changeset-based version control systems, a revision tag is simply a -symbolic name for a particular revision. On older file-based systems -like CVS, each tag is added to the entire set of version-controlled -files, allowing them to be handled as a unit. Revision tags are -commonly used to identify releases that are distributed to users. - - There are two basic commands for tags; one makes a tag with a given -name, the other retrieves a named tag. - -@table @code -@kindex C-x v s -@findex vc-create-tag -@item C-x v s @var{name} @key{RET} -Define the working revision of every registered file in or under the -current directory as a tag named @var{name} -(@code{vc-create-tag}). - -@kindex C-x v r -@findex vc-retrieve-tag -@item C-x v r @var{name} @key{RET} -For all registered files at or below the current directory level, -retrieve the tagged revision @var{name}. This command will switch to a -branch if @var{name} is a branch name and your VCS distinguishes -branches from tags. (@code{vc-retrieve-tag}). - -This command reports an error if any files are locked at or below the -current directory, without changing anything; this is to avoid -overwriting work in progress. -@end table - - You can give a tag or branch name as an argument to @kbd{C-x v =} or -@kbd{C-x v ~} -@iftex -(@pxref{Old Revisions,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Old Revisions}). -@end ifnottex -Thus, you can use it to compare a tagged version against the current files, -or two tagged versions against each other. - - On SCCS, VC implements tags itself; these tags are visible only -through VC@. Most later systems (including CVS, Subversion, bzr, git, -and hg) have a native tag facility, and VC uses it where available; -those tags will be visible even when you bypass VC. - - In file-based version control systems, when you rename a registered -file you need to rename its master along with it; the command -@code{vc-rename-file} will do this automatically -@iftex -(@pxref{VC Delete/Rename,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{VC Delete/Rename}). -@end ifnottex -If you are using SCCS, you must also update the records of the tag, to -mention the file by its new name (@code{vc-rename-file} does this, -too). An old tag that refers to a master file that no longer exists -under the recorded name is invalid; VC can no longer retrieve it. It -would be beyond the scope of this manual to explain enough about RCS -and SCCS to explain how to update the tags by hand. Using -@code{vc-rename-file} makes the tag remain valid for retrieval, but it -does not solve all problems. For example, some of the files in your -program probably refer to others by name. At the very least, the -makefile probably mentions the file that you renamed. If you retrieve -an old tag, the renamed file is retrieved under its new name, which is -not the name that the makefile expects. So the program won't really -work as retrieved. - -@node Version Headers -@subsubsection Inserting Version Control Headers - - On Subversion, CVS, RCS, and SCCS, you can put certain special -strings called @dfn{version headers} into a work file. When the file -is committed, the version control system automatically puts the -revision number, the name of the user who made the commit, and other -relevant information into the version header. - -@vindex vc-consult-headers - VC does not normally use the information in the version headers. As -an exception, when using RCS, Emacs uses the version header, if there -is one, to determine the file version, since it is often more reliable -than the RCS master file. To inhibit using the version header this -way, change the variable @code{vc-consult-headers} to @code{nil}. - -@kindex C-x v h -@findex vc-insert-headers -@vindex vc-@var{backend}-header - To insert a suitable header string into the current buffer, type -@kbd{C-x v h} (@code{vc-insert-headers}). This command works only on -Subversion, CVS, RCS, and SCCS@. The variable -@code{vc-@var{backend}-header} contains the list of keywords to insert -into the version header; for instance, CVS uses @code{vc-cvs-header}, -whose default value is @code{'("\$Id\$")}. (The extra backslashes -prevent the string constant from being interpreted as a header, if the -Emacs Lisp file defining it is maintained with version control.) The -@kbd{C-x v h} command inserts each keyword in the list on a new line -at point, surrounded by tabs, and inside comment delimiters if -necessary. - -@vindex vc-static-header-alist - The variable @code{vc-static-header-alist} specifies further strings -to add based on the name of the buffer. Its value should be a list of -elements of the form @code{(@var{regexp} . @var{format})}. Whenever -@var{regexp} matches the buffer name, @var{format} is also inserted as -part of the version header. A @samp{%s} in @var{format} is replaced -with the file's version control type. - -@node Customizing VC -@subsection Customizing VC - -@vindex vc-handled-backends - The variable @code{vc-handled-backends} determines which version -control systems VC should handle. The default value is @code{(RCS CVS -SVN SCCS Bzr Git Hg Mtn Arch)}, so it contains all the version systems -that are currently supported. If you want VC to ignore one or more of -these systems, exclude its name from the list. To disable VC -entirely, set this variable to @code{nil}. - - The order of systems in the list is significant: when you visit a -file registered in more than one system, VC uses the system that comes -first in @code{vc-handled-backends} by default. The order is also -significant when you register a file for the first time -@iftex -(@pxref{Registering,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Registering}). -@end ifnottex - -@menu -* General VC Options:: Options that apply to multiple back ends. -* RCS and SCCS:: Options for RCS and SCCS. -* CVS Options:: Options for CVS. -@end menu - -@node General VC Options -@subsubsection General Options - -@vindex vc-make-backup-files - Emacs normally does not save backup files for source files that are -maintained with version control. If you want to make backup files even -for files that use version control, set the variable -@code{vc-make-backup-files} to a non-@code{nil} value. - -@vindex vc-follow-symlinks -@cindex symbolic links (and version control) - Editing a version-controlled file through a symbolic link may cause -unexpected results, if you are unaware that the underlying file is -version-controlled. The variable @code{vc-follow-symlinks} controls -what Emacs does if you try to visit a symbolic link pointing to a -version-controlled file. If the value is @code{ask} (the default), -Emacs asks for confirmation. If it is @code{nil}, Emacs just displays -a warning message. If it is @code{t}, Emacs automatically follows the -link and visits the real file instead. - -@vindex vc-suppress-confirm - If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} -and @kbd{C-x v i} can save the current buffer without asking, and -@kbd{C-x v u} also operates without asking for confirmation. - -@vindex vc-command-messages - VC mode does much of its work by running the shell commands for the -appropriate version control system. If @code{vc-command-messages} is -non-@code{nil}, VC displays messages to indicate which shell commands -it runs, and additional messages when the commands finish. - -@node RCS and SCCS -@subsubsection Options for RCS and SCCS - -@cindex non-strict locking (RCS) -@cindex locking, non-strict (RCS) - By default, RCS uses locking to coordinate the activities of several -users, but there is a mode called @dfn{non-strict locking} in which -you can check-in changes without locking the file first. Use -@samp{rcs -U} to switch to non-strict locking for a particular file, -see the @code{rcs} manual page for details. - - When deducing the version control state of an RCS file, VC first -looks for an RCS version header string in the file (@pxref{Version -Headers}). If there is no header string, VC normally looks at the -file permissions of the work file; this is fast. But there might be -situations when the file permissions cannot be trusted. In this case -the master file has to be consulted, which is rather expensive. Also -the master file can only tell you @emph{if} there's any lock on the -file, but not whether your work file really contains that locked -version. - -@vindex vc-consult-headers - You can tell VC not to use version headers to determine the file -status by setting @code{vc-consult-headers} to @code{nil}. VC then -always uses the file permissions (if it is supposed to trust them), or -else checks the master file. - -@vindex vc-mistrust-permissions - You can specify the criterion for whether to trust the file -permissions by setting the variable @code{vc-mistrust-permissions}. -Its value can be @code{t} (always mistrust the file permissions and -check the master file), @code{nil} (always trust the file -permissions), or a function of one argument which makes the decision. -The argument is the directory name of the @file{RCS} subdirectory. A -non-@code{nil} value from the function says to mistrust the file -permissions. If you find that the file permissions of work files are -changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. -Then VC always checks the master file to determine the file's status. - - VC determines the version control state of files under SCCS much as -with RCS@. It does not consider SCCS version headers, though. Thus, -the variable @code{vc-mistrust-permissions} affects SCCS use, but -@code{vc-consult-headers} does not. - -@node CVS Options -@subsubsection Options specific for CVS - -@vindex vc-cvs-global-switches - You can specify additional command line options to pass to all CVS -operations in the variable @code{vc-cvs-global-switches}. These -switches are inserted immediately after the @code{cvs} command, before -the name of the operation to invoke. - -@vindex vc-stay-local -@vindex vc-cvs-stay-local -@cindex remote repositories (CVS) - When using a CVS repository on a remote machine, VC can try keeping -network interactions to a minimum. This is controlled by the variable -@code{vc-cvs-stay-local}. There is another variable, -@code{vc-stay-local}, which enables the feature also for other back -ends that support it, including CVS@. In the following, we will talk -only about @code{vc-cvs-stay-local}, but everything applies to -@code{vc-stay-local} as well. - - If @code{vc-cvs-stay-local} is @code{only-file} (the default), VC -determines the version control status of each file using only the -entry in the local CVS subdirectory and the information returned by -previous CVS commands. As a consequence, if you have modified a file -and somebody else has checked in other changes, you will not be -notified of the conflict until you try to commit. - - If you change @code{vc-cvs-stay-local} to @code{nil}, VC queries the -remote repository @emph{before} it decides what to do in -@code{vc-next-action} (@kbd{C-x v v}), just as it does for local -repositories. - - You can also set @code{vc-cvs-stay-local} to a regular expression -that is matched against the repository host name; VC then stays local -only for repositories from hosts that match the pattern. - -@cindex automatic version backups - When using a remote repository, Emacs normally makes @dfn{automatic -version backups} of the original versions of each edited file. These -local backups are made whenever you save the first changes to a file, -and they are removed after you commit your changes to the repository. -(Note that these are not the same as ordinary Emacs backup files; -@iftex -@pxref{Backup,,,emacs, the Emacs Manual}.) -@end iftex -@ifnottex -@pxref{Backup}.) -@end ifnottex -Commands like @kbd{C-x v =} and @kbd{C-x v u} make use of automatic -version backups, if possible, to avoid having to access the network. - - Setting @code{vc-cvs-stay-local} to @code{nil} disables the making -of automatic version backups. - -@cindex manual version backups - Automatic version backups have names of the form -@w{@code{@var{file}.~@var{version}.~}}. This is similar to the name -that @kbd{C-x v ~} saves old versions to -@iftex -(@pxref{Old Revisions,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Old Revisions}), -@end ifnottex -except for the additional dot (@samp{.}) after the version. The -relevant VC commands can use both kinds of version backups. The main -difference is that the ``manual'' version backups made by @kbd{C-x v -~} are not deleted automatically when you commit. - -@cindex locking (CVS) - CVS does not use locking by default, but there are ways to enable -locking-like behavior using its @env{CVSREAD} or @dfn{watch} feature; -see the CVS documentation for details. If that case, you can use -@kbd{C-x v v} in Emacs to toggle locking, as you would for a -locking-based version control system -@iftex -(@pxref{VC With A Locking VCS,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{VC With A Locking VCS}). -@end ifnottex diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi deleted file mode 100644 index 4a5f24c13fb..00000000000 --- a/doc/emacs/windows.texi +++ /dev/null @@ -1,461 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Windows -@chapter Multiple Windows -@cindex windows in Emacs -@cindex multiple windows in Emacs - - Emacs can split a frame into two or many windows. Multiple windows -can display parts of different buffers, or different parts of one -buffer. Multiple frames always imply multiple windows, because each -frame has its own set of windows. Each window belongs to one and only -one frame. - -@menu -* Basic Window:: Introduction to Emacs windows. -* Split Window:: New windows are made by splitting existing windows. -* Other Window:: Moving to another window or doing something to it. -* Pop Up Window:: Finding a file or buffer in another window. -* Change Window:: Deleting windows and changing their sizes. -* Displaying Buffers:: How Emacs picks a window for displaying a buffer. -* Window Convenience:: Convenience functions for window handling. -@end menu - -@node Basic Window -@section Concepts of Emacs Windows - - Each Emacs window displays one Emacs buffer at any time. A single -buffer may appear in more than one window; if it does, any changes in -its text are displayed in all the windows where it appears. But these -windows can show different parts of the buffer, because each window -has its own value of point. - -@cindex selected window - At any time, one Emacs window is the @dfn{selected window}; the -buffer this window is displaying is the current buffer. On graphical -displays, the point is indicated by a solid blinking cursor in the -selected window, and by a hollow box in non-selected windows. On text -terminals, the cursor is drawn only in the selected window. -@xref{Cursor Display}. - - Commands to move point affect the value of point for the selected -Emacs window only. They do not change the value of point in other -Emacs windows, even those showing the same buffer. The same is true -for buffer-switching commands such as @kbd{C-x b}; they do not affect -other windows at all. However, there are other commands such as -@kbd{C-x 4 b} that select a different window and switch buffers in it. -Also, all commands that display information in a window, including -(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b} -(@code{list-buffers}), work by switching buffers in a nonselected -window without affecting the selected window. - - When multiple windows show the same buffer, they can have different -regions, because they can have different values of point. However, -they all have the same value for the mark, because each buffer has -only one mark position. - - Each window has its own mode line, which displays the buffer name, -modification status and major and minor modes of the buffer that is -displayed in the window. The selected window's mode line appears in a -different color. @xref{Mode Line}, for details. - -@node Split Window -@section Splitting Windows - -@table @kbd -@item C-x 2 -Split the selected window into two windows, one above the other -(@code{split-window-below}). -@item C-x 3 -Split the selected window into two windows, positioned side by side -(@code{split-window-right}). -@item C-Mouse-2 -In the mode line of a window, split that window. -@end table - -@kindex C-x 2 -@findex split-window-below - @kbd{C-x 2} (@code{split-window-below}) splits the selected window -into two windows, one above the other. After splitting, the selected -window is the upper one, and the newly split-off window is below. -Both windows have the same value of point as before, and display the -same portion of the buffer (or as close to it as possible). If -necessary, the windows are scrolled to keep point on-screen. By -default, the two windows each get half the height of the original -window. A positive numeric argument specifies how many lines to give -to the top window; a negative numeric argument specifies how many -lines to give to the bottom window. - -@vindex split-window-keep-point - If you change the variable @code{split-window-keep-point} to -@code{nil}, @kbd{C-x 2} instead adjusts the portion of the buffer -displayed by the two windows, as well as the value of point in each -window, in order to keep the text on the screen as close as possible -to what it was before; furthermore, if point was in the lower half of -the original window, the bottom window is selected instead of the -upper one. - -@kindex C-x 3 -@findex split-window-right - @kbd{C-x 3} (@code{split-window-right}) splits the selected window -into two side-by-side windows. The left window is the selected one; -the right window displays the same portion of the same buffer, and has -the same value of point. A positive numeric argument specifies how -many columns to give the left window; a negative numeric argument -specifies how many columns to give the right window. - -@vindex truncate-partial-width-windows - When you split a window with @kbd{C-x 3}, each resulting window -occupies less than the full width of the frame. If it becomes too -narrow, the buffer may be difficult to read if continuation lines are -in use (@pxref{Continuation Lines}). Therefore, Emacs automatically -switches to line truncation if the window width becomes narrower than -50 columns. This truncation occurs regardless of the value of the -variable @code{truncate-lines} (@pxref{Line Truncation}); it is -instead controlled by the variable -@code{truncate-partial-width-windows}. If the value of this variable -is a positive integer (the default is 50), that specifies the minimum -width for a partial-width window before automatic line truncation -occurs; if the value is @code{nil}, automatic line truncation is -disabled; and for any other non-@code{nil} value, Emacs truncates -lines in every partial-width window regardless of its width. - - On text terminals, side-by-side windows are separated by a vertical -divider which is drawn using the @code{vertical-border} face. - -@kindex C-Mouse-2 @r{(mode line)} -@kindex C-Mouse-2 @r{(scroll bar)} - If you click @kbd{C-Mouse-2} in the mode line of a window, that -splits the window, putting a vertical divider where you click. -Depending on how Emacs is compiled, you can also split a window by -clicking @kbd{C-Mouse-2} in the scroll bar, which puts a horizontal -divider where you click (this feature does not work when Emacs uses -GTK+ scroll bars). - -@node Other Window -@section Using Other Windows - -@table @kbd -@item C-x o -Select another window (@code{other-window}). -@item C-M-v -Scroll the next window (@code{scroll-other-window}). -@item Mouse-1 -@kbd{Mouse-1}, in the text area of a window, selects the window and -moves point to the position clicked. Clicking in the mode line -selects the window without moving point in it. -@end table - -@kindex C-x o -@findex other-window -With the keyboard, you can switch windows by typing @kbd{C-x o} -(@code{other-window}). That is an @kbd{o}, for ``other'', not a zero. -When there are more than two windows, this command moves through all the -windows in a cyclic order, generally top to bottom and left to right. -After the rightmost and bottommost window, it goes back to the one at -the upper left corner. A numeric argument means to move several steps -in the cyclic order of windows. A negative argument moves around the -cycle in the opposite order. When the minibuffer is active, the -minibuffer is the last window in the cycle; you can switch from the -minibuffer window to one of the other windows, and later switch back and -finish supplying the minibuffer argument that is requested. -@xref{Minibuffer Edit}. - -@kindex C-M-v -@findex scroll-other-window - The usual scrolling commands (@pxref{Display}) apply to the selected -window only, but there is one command to scroll the next window. -@kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that -@kbd{C-x o} would select. It takes arguments, positive and negative, -like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the help -window associated with the minibuffer, if any, rather than the next -window in the standard cyclic order; @pxref{Minibuffer Edit}.) - -@vindex mouse-autoselect-window - If you set @code{mouse-autoselect-window} to a non-@code{nil} value, -moving the mouse over a different window selects that window. This -feature is off by default. - -@node Pop Up Window -@section Displaying in Another Window - -@cindex selecting buffers in other windows -@kindex C-x 4 - @kbd{C-x 4} is a prefix key for a variety of commands that switch to -a buffer in a different window---either another existing window, or a -new window created by splitting the selected window. @xref{Window -Choice}, for how Emacs picks or creates the window to use. - -@table @kbd -@findex switch-to-buffer-other-window -@item C-x 4 b @var{bufname} @key{RET} -Select buffer @var{bufname} in another window -(@code{switch-to-buffer-other-window}). - -@findex display-buffer -@item C-x 4 C-o @var{bufname} @key{RET} -@kindex C-x 4 C-o -Display buffer @var{bufname} in some window, without trying to select -it (@code{display-buffer}). @xref{Displaying Buffers}, for details -about how the window is chosen. - -@findex find-file-other-window -@item C-x 4 f @var{filename} @key{RET} -Visit file @var{filename} and select its buffer in another window -(@code{find-file-other-window}). @xref{Visiting}. - -@findex dired-other-window -@item C-x 4 d @var{directory} @key{RET} -Select a Dired buffer for directory @var{directory} in another window -(@code{dired-other-window}). @xref{Dired}. - -@findex mail-other-window -@item C-x 4 m -Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending -Mail}), but in another window (@code{mail-other-window}). - -@findex find-tag-other-window -@item C-x 4 . -Find a tag in the current tags table, similar to @kbd{M-.} -(@pxref{Tags}), but in another window (@code{find-tag-other-window}). -@item C-x 4 r @var{filename} @key{RET} -Visit file @var{filename} read-only, and select its buffer in another -window (@code{find-file-read-only-other-window}). @xref{Visiting}. -@end table - -@node Change Window -@section Deleting and Rearranging Windows - -@table @kbd -@item C-x 0 -Delete the selected window (@code{delete-window}). -@item C-x 1 -Delete all windows in the selected frame except the selected window -(@code{delete-other-windows}). -@item C-x 4 0 -Delete the selected window and kill the buffer that was showing in it -(@code{kill-buffer-and-window}). The last character in this key -sequence is a zero. -@item C-x ^ -Make selected window taller (@code{enlarge-window}). -@item C-x @} -Make selected window wider (@code{enlarge-window-horizontally}). -@item C-x @{ -Make selected window narrower (@code{shrink-window-horizontally}). -@item C-x - -Shrink this window if its buffer doesn't need so many lines -(@code{shrink-window-if-larger-than-buffer}). -@item C-x + -Make all windows the same height (@code{balance-windows}). -@end table - -@kindex C-x 0 -@findex delete-window - To delete the selected window, type @kbd{C-x 0} -(@code{delete-window}). (That is a zero.) Once a window is deleted, -the space that it occupied is given to an adjacent window (but not the -minibuffer window, even if that is active at the time). Deleting the -window has no effect on the buffer it used to display; the buffer -continues to exist, and you can still switch to it with @kbd{C-x b}. - -@findex kill-buffer-and-window -@kindex C-x 4 0 - @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command -than @kbd{C-x 0}; it kills the current buffer and then deletes the -selected window. - -@kindex C-x 1 -@findex delete-other-windows - @kbd{C-x 1} (@code{delete-other-windows}) deletes all the windows, -@emph{except} the selected one; the selected window expands to use the -whole frame. (This command cannot be used while the minibuffer window -is active; attempting to do so signals an error.) - -@kindex C-x ^ -@findex enlarge-window -@kindex C-x @} -@vindex window-min-height - The command @kbd{C-x ^} (@code{enlarge-window}) makes the selected -window one line taller, taking space from a vertically adjacent window -without changing the height of the frame. With a positive numeric -argument, this command increases the window height by that many lines; -with a negative argument, it reduces the height by that many lines. -If there are no vertically adjacent windows (i.e., the window is at the -full frame height), that signals an error. The command also signals -an error if you attempt to reduce the height of any window below a -certain minimum number of lines, specified by the variable -@code{window-min-height} (the default is 4). - -@findex enlarge-window-horizontally -@findex shrink-window-horizontally -@vindex window-min-width - Similarly, @kbd{C-x @}} (@code{enlarge-window-horizontally}) makes -the selected window wider, and @kbd{C-x @{} -(@code{shrink-window-horizontally}) makes it narrower. These commands -signal an error if you attempt to reduce the width of any window below -a certain minimum number of columns, specified by the variable -@code{window-min-width} (the default is 10). - -@kindex C-x - -@findex shrink-window-if-larger-than-buffer - @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) reduces the -height of the selected window, if it is taller than necessary to show -the whole text of the buffer it is displaying. It gives the extra -lines to other windows in the frame. - -@kindex C-x + -@findex balance-windows - You can also use @kbd{C-x +} (@code{balance-windows}) to even out the -heights of all the windows in the selected frame. - - Mouse clicks on the mode line provide another way to change window -heights and to delete windows. @xref{Mode Line Mouse}. - -@node Displaying Buffers -@section Displaying a Buffer in a Window - - It is a common Emacs operation to display or ``pop up'' some buffer -in response to a user command. There are several different ways in -which commands do this. - - Many commands, like @kbd{C-x C-f} (@code{find-file}), display the -buffer by ``taking over'' the selected window, expecting that the -user's attention will be diverted to that buffer. These commands -usually work by calling @code{switch-to-buffer} internally -(@pxref{Select Buffer}). - -@findex display-buffer - Some commands try to display ``intelligently'', trying not to take -over the selected window, e.g., by splitting off a new window and -displaying the desired buffer there. Such commands, which include the -various help commands (@pxref{Help}), work by calling -@code{display-buffer} internally. @xref{Window Choice}, for details. - - Other commands do the same as @code{display-buffer}, and -additionally select the displaying window so that you can begin -editing its buffer. The command @kbd{C-x `} (@code{next-error}) is -one example (@pxref{Compilation Mode}). Such commands work by calling -the function @code{pop-to-buffer} internally. @xref{Switching -Buffers,,Switching to a Buffer in a Window, elisp, The Emacs Lisp -Reference Manual}. - - Commands with names ending in @code{-other-window} behave like -@code{display-buffer}, except that they never display in the selected -window. Several of these commands are bound in the @kbd{C-x 4} prefix -key (@pxref{Pop Up Window}). - - Commands with names ending in @code{-other-frame} behave like -@code{display-buffer}, except that they (i) never display in the -selected window and (ii) prefer to create a new frame to display the -desired buffer instead of splitting a window---as though the variable -@code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}). -Several of these commands are bound in the @kbd{C-x 5} prefix key. - -@menu -* Window Choice:: How @code{display-buffer} works. -@end menu - -@node Window Choice -@subsection How @code{display-buffer} works -@findex display-buffer - -The @code{display-buffer} command (as well as commands that call it -internally) chooses a window to display by following the steps given -below. @xref{Choosing Window,,Choosing a Window for Display, elisp, -The Emacs Lisp Reference Manual}, for details about how to alter this -sequence of steps. - -@itemize -@vindex same-window-buffer-names -@vindex same-window-regexps -@item -First, check if the buffer should be displayed in the selected window -regardless of other considerations. You can tell Emacs to do this by -adding the desired buffer's name to the list -@code{same-window-buffer-names}, or adding a matching regular -expression to the list @code{same-window-regexps}. By default, these -variables are @code{nil}, so this step is skipped. - -@item -Otherwise, if the buffer is already displayed in an existing window, -``reuse'' that window. Normally, only windows on the selected frame -are considered, but windows on other frames are also reusable if you -change @code{pop-up-frames} (see below) to @code{t}. - -@vindex pop-up-frames -@item -Otherwise, optionally create a new frame and display the buffer there. -By default, this step is skipped. To enable it, change the variable -@code{pop-up-frames} to a non-@code{nil} value. The special value -@code{graphic-only} means to do this only on graphical displays. - -@item -Otherwise, try to create a new window by splitting the selected -window, and display the buffer in that new window. - -@vindex split-height-threshold -@vindex split-width-threshold -The split can be either vertical or horizontal, depending on the -variables @code{split-height-threshold} and -@code{split-width-threshold}. These variables should have integer -values. If @code{split-height-threshold} is smaller than the selected -window's height, the split puts the new window below. Otherwise, if -@code{split-width-threshold} is smaller than the window's width, the -split puts the new window on the right. If neither condition holds, -Emacs tries to split so that the new window is below---but only if the -window was not split before (to avoid excessive splitting). - -@item -Otherwise, display the buffer in an existing window on the selected -frame. - -@item -If all the above methods fail for whatever reason, create a new frame -and display the buffer there. -@end itemize - -@node Window Convenience -@section Convenience Features for Window Handling - -@findex winner-mode -@cindex Winner mode -@cindex mode, Winner -@cindex undoing window configuration changes -@cindex window configuration changes, undoing - Winner mode is a global minor mode that records the changes in the -window configuration (i.e., how the frames are partitioned into -windows), so that you can ``undo'' them. You can toggle Winner mode -with @kbd{M-x winner-mode}, or by customizing the variable -@code{winner-mode}. When the mode is enabled, @kbd{C-c left} -(@code{winner-undo}) undoes the last window configuration change. If -you change your mind while undoing, you can redo the changes you had -undone using @kbd{C-c right} (@code{M-x winner-redo}). - - Follow mode (@kbd{M-x follow-mode}) synchronizes several windows on -the same buffer so that they always display adjacent sections of that -buffer. @xref{Follow Mode}. - -@cindex Windmove package -@cindex directional window selection -@findex windmove-right -@findex windmove-default-keybindings - The Windmove package defines commands for moving directionally -between neighboring windows in a frame. @kbd{M-x windmove-right} -selects the window immediately to the right of the currently selected -one, and similarly for the ``left'', ``up'', and ``down'' -counterparts. @kbd{M-x windmove-default-keybindings} binds these -commands to @kbd{S-right} etc.; doing so disables shift selection for -those keys (@pxref{Shift Selection}). - - The command @kbd{M-x compare-windows} lets you compare the text -shown in different windows. @xref{Comparing Files}. - -@vindex scroll-all-mode -@cindex scrolling windows together -@cindex Scroll-all mode -@cindex mode, Scroll-all - Scroll All mode (@kbd{M-x scroll-all-mode}) is a global minor mode -that causes scrolling commands and point motion commands to apply to -every single window. diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi deleted file mode 100644 index b372708d022..00000000000 --- a/doc/emacs/xresources.texi +++ /dev/null @@ -1,821 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1987, 1993-1995, 1997, 2001-2014 Free Software -@c Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node X Resources -@appendix X Options and Resources - - You can customize some X-related aspects of Emacs behavior using X -resources, as is usual for programs that use X. - - When Emacs is compiled with GTK+ support, the appearance of various -graphical widgets, such as the menu-bar, scroll-bar, and dialog boxes, -is determined by -@ifnottex -``GTK resources'', which we will also describe. -@end ifnottex -@iftex -``GTK resources''. -@end iftex -When Emacs is built without GTK+ support, the appearance of these -widgets is determined by additional X resources. - - On MS-Windows, you can customize some of the same aspects using the -system registry (@pxref{MS-Windows Registry}). - -@menu -* Resources:: Using X resources with Emacs (in general). -* Table of Resources:: Table of specific X resources that affect Emacs. -* Lucid Resources:: X resources for Lucid menus. -* Motif Resources:: X resources for Motif and LessTif menus. -* GTK resources:: Resources for GTK widgets. -@end menu - -@node Resources -@appendixsec X Resources -@cindex resources -@cindex X resources -@cindex @file{~/.Xdefaults} file -@cindex @file{~/.Xresources} file - - Programs running under the X Window System organize their user -options under a hierarchy of classes and resources. You can specify -default values for these options in your @dfn{X resource file}, -usually named @file{~/.Xdefaults} or @file{~/.Xresources}. Changes in -this file do not take effect immediately, because the X server stores -its own list of resources; to update it, use the command -@command{xrdb}---for instance, @samp{xrdb ~/.Xdefaults}. - -@cindex registry, setting resources (MS-Windows) - (MS-Windows systems do not support X resource files; on such systems, -Emacs looks for X resources in the Windows Registry, first under the -key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs}, which affects only -the current user and override the system-wide settings, and then under -the key @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}, which affects -all users of the system. The menu and scroll bars are native widgets -on MS-Windows, so they are only customizable via the system-wide -settings in the Display Control Panel. You can also set resources -using the @samp{-xrm} command line option, as explained below.) - - Each line in the X resource file specifies a value for one option or -for a collection of related options. The order in which the lines -appear in the file does not matter. Each resource specification -consists of a @dfn{program name} and a @dfn{resource name}. Case -distinctions are significant in each of these names. Here is an -example: - -@example -emacs.cursorColor: dark green -@end example - - The program name is the name of the executable file to which the -resource applies. For Emacs, this is normally @samp{emacs}. To -specify a definition that applies to all instances of Emacs, -regardless of the name of the Emacs executable, use @samp{Emacs}. - - The resource name is the name of a program setting. For instance, -Emacs recognizes a @samp{cursorColor} resource that controls the color -of the text cursor. - - Resources are grouped into named classes. For instance, the -@samp{Foreground} class contains the @samp{cursorColor}, -@samp{foreground} and @samp{pointerColor} resources (@pxref{Table of -Resources}). Instead of using a resource name, you can use a class -name to specify the default value for all resources in that class, -like this: - -@example -emacs.Foreground: dark green -@end example - - Emacs does not process X resources at all if you set the variable -@code{inhibit-x-resources} to a non-@code{nil} value. If you invoke -Emacs with the @samp{-Q} (or @samp{--quick}) command-line option, -@code{inhibit-x-resources} is automatically set to @code{t} -(@pxref{Initial Options}). - -@ifnottex - In addition, you can use the following command-line options to -override the X resources file: - -@table @samp -@item -name @var{name} -@opindex --name -@itemx --name=@var{name} -@cindex resource name, command-line argument -This option sets the program name of the initial Emacs frame to -@var{name}. It also sets the title of the initial frame to -@var{name}. This option does not affect subsequent frames. - -If you don't specify this option, the default is to use the Emacs -executable's name as the program name. - -For consistency, @samp{-name} also specifies the name to use for other -resource values that do not belong to any particular frame. - -The resources that name Emacs invocations also belong to a class, -named @samp{Emacs}. If you write @samp{Emacs} instead of -@samp{emacs}, the resource applies to all frames in all Emacs jobs, -regardless of frame titles and regardless of the name of the -executable file. - -@item -xrm @var{resource-values} -@opindex --xrm -@itemx --xrm=@var{resource-values} -@cindex resource values, command-line argument -This option specifies X resource values for the present Emacs job. - -@var{resource-values} should have the same format that you would use -inside a file of X resources. To include multiple resource -specifications in @var{resource-values}, put a newline between them, -just as you would in a file. You can also use @samp{#include -"@var{filename}"} to include a file full of resource specifications. -Resource values specified with @samp{-xrm} take precedence over all -other resource specifications. -@end table -@end ifnottex - -@node Table of Resources -@appendixsec Table of X Resources for Emacs - - This table lists the X resource names that Emacs recognizes, -excluding those that control the appearance of graphical widgets like -the menu bar: - -@table @asis -@item @code{background} (class @code{Background}) -Background color (@pxref{Colors}). - -@item @code{bitmapIcon} (class @code{BitmapIcon}) -Tell the window manager to display the Emacs icon if @samp{on}; don't -do so if @samp{off}. @xref{Icons X}, for a description of the icon. - -@ifnottex -@item @code{borderColor} (class @code{BorderColor}) -Color of the frame's external border. This has no effect if Emacs is -compiled with GTK+ support. - -@item @code{borderWidth} (class @code{BorderWidth}) -Width of the frame's external border, in pixels. This has no effect -if Emacs is compiled with GTK+ support. -@end ifnottex - -@item @code{cursorColor} (class @code{Foreground}) -Text cursor color. If this resource is specified when Emacs starts -up, Emacs sets its value as the background color of the @code{cursor} -face (@pxref{Faces}). - -@item @code{cursorBlink} (class @code{CursorBlink}) -If the value of this resource is @samp{off} or @samp{false} or -@samp{0} at startup, Emacs disables Blink Cursor mode (@pxref{Cursor -Display}). - -@item @code{font} (class @code{Font}) -Font name for the @code{default} face (@pxref{Fonts}). You can also -specify a fontset name (@pxref{Fontsets}). - -@item @code{fontBackend} (class @code{FontBackend}) -Comma-delimited list of backend(s) to use for drawing fonts, in order -of precedence. For instance, the value @samp{x,xft} tells Emacs to -draw fonts using the X core font driver, falling back on the Xft font -driver if that fails. Normally, you should leave this resource unset, -in which case Emacs tries using all available font backends. - -@item @code{foreground} (class @code{Foreground}) -Default foreground color for text. - -@item @code{geometry} (class @code{Geometry}) -Window size and position. The value should be a size and position -specification, of the same form as in the @samp{-g} or -@samp{--geometry} command-line option (@pxref{Window Size X}). - -The size applies to all frames in the Emacs session, but the position -applies only to the initial Emacs frame (or, in the case of a resource -for a specific frame name, only that frame). - - -Be careful not to specify this resource as @samp{emacs*geometry}, as -that may affect individual menus as well as the main Emacs frame. - -@item @code{fullscreen} (class @code{Fullscreen}) -The desired fullscreen size. The value can be one of @code{fullboth}, -@code{maximized}, @code{fullwidth} or @code{fullheight}, which -correspond to the command-line options @samp{-fs}, @samp{-mm}, -@samp{-fw}, and @samp{-fh} (@pxref{Window Size X}). Note that this -applies to the initial frame only. - -@ifnottex -@item @code{iconName} (class @code{Title}) -Name to display in the icon. - -@item @code{internalBorder} (class @code{BorderWidth}) -Width of the internal frame border, in pixels. -@end ifnottex - -@item @code{lineSpacing} (class @code{LineSpacing}) -@cindex line spacing -Additional space between lines, in pixels. - -@item @code{menuBar} (class @code{MenuBar}) -@cindex menu bar -If the value of this resource is @samp{off} or @samp{false} or -@samp{0}, Emacs disables Menu Bar mode at startup (@pxref{Menu Bars}). - -@ifnottex -@item @code{minibuffer} (class @code{Minibuffer}) -If @samp{none}, Emacs will not make a minibuffer in this frame; it -will use a separate minibuffer frame instead. - -@item @code{paneFont} (class @code{Font}) -@cindex font for menus -Font name for menu pane titles, in non-toolkit versions of Emacs. -@end ifnottex - -@item @code{pointerColor} (class @code{Foreground}) -Color of the mouse cursor. This has no effect in many graphical -desktop environments, as they do not let Emacs change the mouse cursor -this way. - -@ifnottex -@item @code{privateColormap} (class @code{PrivateColormap}) -If @samp{on}, use a private color map, in the case where the ``default -visual'' of class PseudoColor and Emacs is using it. - -@item @code{reverseVideo} (class @code{ReverseVideo}) -Switch foreground and background default colors if @samp{on}, use colors as -specified if @samp{off}. - -@item @code{screenGamma} (class @code{ScreenGamma}) -@cindex gamma correction -Gamma correction for colors, equivalent to the frame parameter -@code{screen-gamma}. - -@item @code{scrollBarWidth} (class @code{ScrollBarWidth}) -@cindex scrollbar width -The scroll bar width in pixels, equivalent to the frame parameter -@code{scroll-bar-width}. Do not set this resource if Emacs is -compiled with GTK+ support. -@end ifnottex - -@ifnottex -@item @code{selectionFont} (class @code{SelectionFont}) -Font name for pop-up menu items, in non-toolkit versions of Emacs. (For -toolkit versions, see @ref{Lucid Resources}, also see @ref{Motif -Resources}.) - -@item @code{selectionTimeout} (class @code{SelectionTimeout}) -Number of milliseconds to wait for a selection reply. -If the selection owner doesn't reply in this time, we give up. -A value of 0 means wait as long as necessary. - -@item @code{synchronous} (class @code{Synchronous}) -@cindex debugging X problems -@cindex synchronous X mode -Run Emacs in synchronous mode if @samp{on}. Synchronous mode is -useful for debugging X problems. -@end ifnottex - -@item @code{title} (class @code{Title}) -Name to display in the title bar of the initial Emacs frame. - -@item @code{toolBar} (class @code{ToolBar}) -@cindex tool bar -If the value of this resource is @samp{off} or @samp{false} or -@samp{0}, Emacs disables Tool Bar mode at startup (@pxref{Tool Bars}). - -@item @code{useXIM} (class @code{UseXIM}) -@cindex XIM -@cindex X input methods -@cindex input methods, X -Disable use of X input methods (XIM) if @samp{false} or @samp{off}. -This is only relevant if your Emacs is built with XIM support. It -might be useful to turn off XIM on slow X client/server links. - -@item @code{verticalScrollBars} (class @code{ScrollBars}) -Give frames scroll bars if @samp{on}; don't have scroll bars if -@samp{off}. - -@ifnottex -@item @code{visualClass} (class @code{VisualClass}) -The @dfn{visual class} for X color display. If specified, the value -should start with one of @samp{TrueColor}, @samp{PseudoColor}, -@samp{DirectColor}, @samp{StaticColor}, @samp{GrayScale}, and -@samp{StaticGray}, followed by @samp{-@var{depth}}, where @var{depth} -is the number of color planes. -@end ifnottex -@end table - - You can also use X resources to customize individual Emacs faces -(@pxref{Faces}). For example, setting the resource -@samp{@var{face}.attributeForeground} is equivalent to customizing the -@samp{foreground} attribute of the face @var{face}. However, we -recommend customizing faces from within Emacs, instead of using X -resources. @xref{Face Customization}. - -@ifnottex -@node Lucid Resources -@appendixsec Lucid Menu And Dialog X Resources -@cindex Menu X Resources (Lucid widgets) -@cindex Dialog X Resources (Lucid widgets) -@cindex Lucid Widget X Resources - - If Emacs is compiled with the X toolkit support using Lucid widgets, -you can use X resources to customize the appearance of the menu bar, -pop-up menus, and dialog boxes. The resources for the menu bar fall -in the @samp{pane.menubar} class (following, as always, either the -name of the Emacs executable or @samp{Emacs} for all Emacs -invocations). The resources for the pop-up menu are in the -@samp{menu*} class. The resources for dialog boxes are in the -@samp{dialog*} class. - - For example, to display menu bar entries with the @samp{Courier-12} -font (@pxref{Fonts}), write this: - -@example -Emacs.pane.menubar.font: Courier-12 -@end example - -@noindent -Lucid widgets can display multilingual text in your locale. To enable -this, specify a @code{fontSet} resource instead of a @code{font} -resource. @xref{Fontsets}. If both @code{font} and @code{fontSet} -resources are specified, the @code{fontSet} resource is used. - -Here is a list of resources for menu bars, pop-up menus, and dialogs: - -@table @code -@item font -Font for menu item text. -@item fontSet -Fontset for menu item text. -@item foreground -Foreground color. -@item background -Background color. -@item buttonForeground -Foreground color for a selected item. -@ifnottex -@item horizontalSpacing -Horizontal spacing in pixels between items. Default is 3. -@item verticalSpacing -Vertical spacing in pixels between items. Default is 2. -@item arrowSpacing -Horizontal spacing between the arrow (which indicates a submenu) and -the associated text. Default is 10. -@item shadowThickness -Thickness of shadow lines for 3D buttons, arrows, and other graphical -elements. Default is 1. -@end ifnottex -@item margin -Margin of the menu bar, in characters. Default is 1. -@end table - -@node Motif Resources -@appendixsec Motif Menu X Resources -@cindex Menu X Resources (Motif widgets) -@cindex Motif Widget X Resources - - If Emacs is compiled with the X toolkit support using Motif or -LessTif widgets, you can use X resources to customize the appearance -of the menu bar, pop-up menus, and dialog boxes. However, the -resources are organized differently from Lucid widgets. - - The resource names for the menu bar are in the @samp{pane.menubar} -class, and they must be specified in this form: - -@smallexample -Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value} -@end smallexample - -@noindent -For pop-up menus, the resources are in the @samp{menu*} class, instead -of @samp{pane.menubar}. For dialog boxes, they are in @samp{dialog}. -In each case, each individual menu string is a subwidget; the -subwidget's name is the same as the menu item string. For example, -the @samp{File} menu in the menu bar is a subwidget named -@samp{emacs.pane.menubar.File}. - - Typically, you want to specify the same resources for the whole menu -bar. To do this, use @samp{*} instead of a specific subwidget name. -For example, to specify the font @samp{8x16} for all menu bar items, -including submenus, write this: - -@smallexample -Emacs.pane.menubar.*.fontList: 8x16 -@end smallexample - - Each item in a submenu also has its own name for X resources; for -example, the @samp{File} submenu has an item named @samp{Save (current -buffer)}. A resource specification for a submenu item looks like -this: - -@smallexample -Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value} -@end smallexample - -@noindent -For example, here's how to specify the font for the @samp{Save (current -buffer)} item: - -@smallexample -Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16 -@end smallexample - -@noindent -For an item in a second-level submenu, such as @samp{Complete Word} -under @samp{Spell Checking} under @samp{Tools}, the resource fits this -template: - -@smallexample -Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value} -@end smallexample - -@noindent -For example, - -@smallexample -Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value} -@end smallexample - -@noindent -(This should be one long line.) - - If you want the submenu items to look different from the menu bar -itself, you must first specify the resource for all of them, then -override the value for submenus alone. Here is an example: - -@smallexample -Emacs.pane.menubar.*.fontList: 8x16 -Emacs.pane.menubar.popup_*.fontList: 8x16 -@end smallexample - - To specify resources for the LessTif file-selection box, use -@samp{fsb*}, like this: - -@example -Emacs.fsb*.fontList: 8x16 -@end example - - Here is a list of resources for LessTif menu bars and pop-up menus: - -@table @code -@item armColor -The color to show in an armed button. -@item fontList -The font to use. -@item marginBottom -@itemx marginHeight -@itemx marginLeft -@itemx marginRight -@itemx marginTop -@itemx marginWidth -Amount of space to leave around the item, within the border. -@item borderWidth -The width of the border around the menu item, on all sides. -@item shadowThickness -The width of the border shadow. -@item bottomShadowColor -The color for the border shadow, on the bottom and the right. -@item topShadowColor -The color for the border shadow, on the top and the left. -@end table -@end ifnottex - -@node GTK resources -@appendixsec GTK resources -@cindex GTK+ resources -@cindex resource files for GTK -@cindex @file{~/.gtkrc-2.0} file -@cindex @file{~/.emacs.d/gtkrc} file - - If Emacs is compiled with GTK+ toolkit support, the simplest way to -customize its GTK+ widgets (e.g., menus, dialogs, tool bars and -scroll bars) is to choose an appropriate GTK+ theme, for example with -the GNOME theme selector. - - In GTK+ version 2, you can also use @dfn{GTK+ resources} to -customize the appearance of GTK+ widgets used by Emacs. These -resources are specified in either the file @file{~/.emacs.d/gtkrc} -(for Emacs-specific GTK+ resources), or @file{~/.gtkrc-2.0} (for -general GTK+ resources). We recommend using @file{~/.emacs.d/gtkrc}, -since GTK+ seems to ignore @file{~/.gtkrc-2.0} when running GConf with -GNOME@. Note, however, that some GTK themes may override -customizations in @file{~/.emacs.d/gtkrc}; there is nothing we can do -about this. GTK+ resources do not affect aspects of Emacs unrelated -to GTK+ widgets, such as fonts and colors in the main Emacs window; -those are governed by normal X resources (@pxref{Resources}). - - The following sections describe how to customize GTK+ resources for -Emacs. For details about GTK+ resources, see the GTK+ API document at -@uref{http://developer.gnome.org/gtk2/stable/gtk2-Resource-Files.html}. - - In GTK+ version 3, GTK+ resources have been replaced by a completely -different system. The appearance of GTK+ widgets is now determined by -CSS-like style files: @file{gtk-3.0/gtk.css} in the GTK+ installation -directory, and @file{~/.themes/@var{theme}/gtk-3.0/gtk.css} for local -style settings (where @var{theme} is the name of the current GTK+ -theme). Therefore, the description of GTK+ resources in this section -does not apply to GTK+ 3. For details about the GTK+ 3 styling -system, see -@uref{http://developer.gnome.org/gtk3/3.0/GtkCssProvider.html}. - -@menu -* GTK Resource Basics:: Basic usage of GTK+ resources. -* GTK Widget Names:: How GTK+ widgets are named. -* GTK Names in Emacs:: GTK widgets used by Emacs. -* GTK styles:: What can be customized in a GTK widget. -@end menu - -@node GTK Resource Basics -@appendixsubsec GTK Resource Basics - - In a GTK+ 2 resource file (usually @file{~/.emacs.d/gtkrc}), the -simplest kinds of resource settings simply assign a value to a -variable. For example, putting the following line in the resource -file changes the font on all GTK+ widgets to @samp{courier-12}: - -@smallexample -gtk-font-name = "courier 12" -@end smallexample - -@noindent -Note that in this case the font name must be supplied as a GTK font -pattern (also called a @dfn{Pango font name}), not as a -Fontconfig-style font name or XLFD@. @xref{Fonts}. - - To customize widgets you first define a @dfn{style}, and then apply -the style to the widgets. Here is an example that sets the font for -menus (@samp{#} characters indicate comments): - -@smallexample -# @r{Define the style @samp{my_style}.} -style "my_style" -@{ - font_name = "helvetica bold 14" -@} - -# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{my_style}.} -widget "*emacs-menuitem*" style "my_style" -@end smallexample - -@noindent -The widget name in this example contains wildcards, so the style is -applied to all widgets matching @samp{*emacs-menuitem*}. The widgets -are named by the way they are contained, from the outer widget to the -inner widget. Here is another example that applies @samp{my_style} -specifically to the Emacs menu bar: - -@smallexample -widget "Emacs.pane.menubar.*" style "my_style" -@end smallexample - - Here is a more elaborate example, showing how to change the parts of -the scroll bar: - -@smallexample -style "scroll" -@{ - fg[NORMAL] = "red"@ @ @ @ @ # @r{Arrow color.} - bg[NORMAL] = "yellow"@ @ # @r{Thumb and background around arrow.} - bg[ACTIVE] = "blue"@ @ @ @ # @r{Trough color.} - bg[PRELIGHT] = "white"@ # @r{Thumb color when the mouse is over it.} -@} - -widget "*verticalScrollBar*" style "scroll" -@end smallexample - -@node GTK Widget Names -@appendixsubsec GTK widget names -@cindex GTK widget names - - A GTK+ widget is specified by a @dfn{widget name} and a @dfn{widget -class}. The widget name refers to a specific widget -(e.g., @samp{emacs-menuitem}), while the widget class refers to a -collection of similar widgets (e.g., @samp{GtkMenuItem}). A widget -always has a class, but need not have a name. - - @dfn{Absolute names} are sequences of widget names or widget -classes, corresponding to hierarchies of widgets embedded within -other widgets. For example, if a @code{GtkWindow} named @code{top} -contains a @code{GtkVBox} named @code{box}, which in turn contains -a @code{GtkMenuBar} called @code{menubar}, the absolute class name -of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and -its absolute widget name is @code{top.box.menubar}. - - GTK+ resource files can contain two types of commands for specifying -widget appearances: - -@table @code -@item widget -specifies a style for widgets based on the class name, or just the -class. - -@item widget_class -specifies a style for widgets based on the class name. -@end table - -@noindent -See the previous subsection for examples of using the @code{widget} -command; the @code{widget_class} command is used similarly. Note that -the widget name/class and the style must be enclosed in double-quotes, -and these commands must be at the top level in the GTK+ resource file. - - As previously noted, you may specify a widget name or class with -shell wildcard syntax: @samp{*} matches zero or more characters and -@samp{?} matches one character. This example assigns a style to all -widgets: - -@smallexample -widget "*" style "my_style" -@end smallexample - -@node GTK Names in Emacs -@appendixsubsec GTK Widget Names in Emacs -@cindex GTK widget names -@cindex GTK widget classes - - The GTK+ widgets used by an Emacs frame are listed below: - -@table @asis -@item @code{Emacs} (class @code{GtkWindow}) -@table @asis -@item @code{pane} (class @code{GtkVBox}) -@table @asis -@item @code{menubar} (class @code{GtkMenuBar}) -@table @asis -@item [menu item widgets] -@end table -@item [unnamed widget] (class @code{GtkHandleBox}) -@table @asis -@item @code{emacs-toolbar} (class @code{GtkToolbar}) -@table @asis -@item [tool bar item widgets] -@end table -@end table -@item @code{emacs} (class @code{GtkFixed}) -@table @asis -@item @code{verticalScrollBar} (class @code{GtkVScrollbar}) -@end table -@end table -@end table -@end table - -@noindent -The contents of Emacs windows are drawn in the @code{emacs} widget. -Note that even if there are multiple Emacs windows, each scroll bar -widget is named @code{verticalScrollBar}. - - For example, here are two different ways to set the menu bar style: - -@smallexample -widget "Emacs.pane.menubar.*" style "my_style" -widget_class "GtkWindow.GtkVBox.GtkMenuBar.*" style "my_style" -@end smallexample - - For GTK+ dialogs, Emacs uses a widget named @code{emacs-dialog}, of -class @code{GtkDialog}. For file selection, Emacs uses a widget named -@code{emacs-filedialog}, of class @code{GtkFileSelection}. - - Because the widgets for pop-up menus and dialogs are free-standing -windows and not ``contained'' in the @code{Emacs} widget, their GTK+ -absolute names do not start with @samp{Emacs}. To customize these -widgets, use wildcards like this: - -@smallexample -widget "*emacs-dialog*" style "my_dialog_style" -widget "*emacs-filedialog* style "my_file_style" -widget "*emacs-menuitem* style "my_menu_style" -@end smallexample - - If you want to apply a style to all menus in Emacs, use this: - -@smallexample -widget_class "*Menu*" style "my_menu_style" -@end smallexample - -@node GTK styles -@appendixsubsec GTK styles -@cindex GTK styles - - Here is an example of two GTK+ style declarations: - -@smallexample -pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" - -style "default" -@{ - font_name = "helvetica 12" - - bg[NORMAL] = @{ 0.83, 0.80, 0.73 @} - bg[SELECTED] = @{ 0.0, 0.55, 0.55 @} - bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @} - bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @} - bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @} - - fg[NORMAL] = "black" - fg[SELECTED] = @{ 0.9, 0.9, 0.9 @} - fg[ACTIVE] = "black" - fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @} - - base[INSENSITIVE] = "#777766" - text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @} - - bg_pixmap[NORMAL] = "background.xpm" - bg_pixmap[INSENSITIVE] = "background.xpm" - bg_pixmap[ACTIVE] = "background.xpm" - bg_pixmap[PRELIGHT] = "" - -@} - -style "ruler" = "default" -@{ - font_name = "helvetica 8" -@} - -@end smallexample - - The style @samp{ruler} inherits from @samp{default}. This way you can build -on existing styles. The syntax for fonts and colors is described below. - - As this example shows, it is possible to specify several values for -foreground and background depending on the widget's @dfn{state}. The -possible states are: - -@table @code -@item NORMAL -This is the default state for widgets. -@item ACTIVE -This is the state for a widget that is ready to do something. It is -also for the trough of a scroll bar, i.e., @code{bg[ACTIVE] = "red"} -sets the scroll bar trough to red. Buttons that have been pressed but -not released yet (``armed'') are in this state. -@item PRELIGHT -This is the state for a widget that can be manipulated, when the mouse -pointer is over it---for example when the mouse is over the thumb in -the scroll bar or over a menu item. When the mouse is over a button -that is not pressed, the button is in this state. -@item SELECTED -This is the state for data that has been selected by the user. It can -be selected text or items selected in a list. This state is not used -in Emacs. -@item INSENSITIVE -This is the state for widgets that are visible, but they can not be -manipulated in the usual way---for example, buttons that can't be -pressed, and disabled menu items. To display disabled menu items in -yellow, use @code{fg[INSENSITIVE] = "yellow"}. -@end table - - Here are the things that can go in a style declaration: - -@table @code -@item bg[@var{state}] = @var{color} -This specifies the background color for the widget. Note that -editable text doesn't use @code{bg}; it uses @code{base} instead. - -@item base[@var{state}] = @var{color} -This specifies the background color for editable text. In Emacs, this -color is used for the background of the text fields in the file -dialog. - -@item bg_pixmap[@var{state}] = "@var{pixmap}" -This specifies an image background (instead of a background color). -@var{pixmap} should be the image file name. GTK can use a number of -image file formats, including XPM, XBM, GIF, JPEG and PNG@. If you -want a widget to use the same image as its parent, use -@samp{}. If you don't want any image, use @samp{}. -@samp{} is the way to cancel a background image inherited from a -parent style. - -You can't specify the file by its absolute file name. GTK looks for -the pixmap file in directories specified in @code{pixmap_path}. -@code{pixmap_path} is a colon-separated list of directories within -double quotes, specified at the top level in a @file{gtkrc} file -(i.e., not inside a style definition; see example above): - -@smallexample -pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" -@end smallexample - -@item fg[@var{state}] = @var{color} -This specifies the foreground color for widgets to use. It is the -color of text in menus and buttons, and the color for the arrows in -the scroll bar. For editable text, use @code{text}. - -@item text[@var{state}] = @var{color} -This is the color for editable text. In Emacs, this color is used for the -text fields in the file dialog. - -@item font_name = "@var{font}" -This specifies the font for text in the widget. @var{font} is a -GTK-style (or Pango) font name, like @samp{Sans Italic 10}. -@xref{Fonts}. The names are case insensitive. -@end table - - There are three ways to specify a color: a color name, an RGB -triplet, or a GTK-style RGB triplet. @xref{Colors}, for a description -of color names and RGB triplets. Color names should be enclosed with -double quotes, e.g., @samp{"red"}. RGB triplets should be written -without double quotes, e.g., @samp{#ff0000}. GTK-style RGB triplets -have the form @w{@code{@{ @var{r}, @var{g}, @var{b} @}}}, where -@var{r}, @var{g} and @var{b} are either integers in the range 0--65535 -or floats in the range 0.0--1.0. diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog deleted file mode 100644 index d70345983f7..00000000000 --- a/doc/lispintro/ChangeLog +++ /dev/null @@ -1,753 +0,0 @@ -2014-10-20 Glenn Morris - - * Version 24.4 released. - -2014-10-13 Glenn Morris - - * Makefile.in (dist): Update for new output variables. - -2014-07-15 Álvar Jesús Ibeas Martín (tiny change) - - * emacs-lisp-intro.texi (Variables, Buffer Names, if & or) - (Symbols as Chest, fwd-para while): Fix typos. - -2014-06-29 Glenn Morris - - * emacs-lisp-intro.texi (Note for Novices, Finding More, Conclusion): - "Online" help doesn't mean what it used to any more. - -2014-02-25 Glenn Morris - - * emacs-lisp-intro.texi (X11 Colors): Don't use setq with hooks. - -2014-02-06 Glenn Morris - - * emacs-lisp-intro.texi (Recursive Patterns): - Do not use colons in index entries. - -2014-01-23 Glenn Morris - - * emacs-lisp-intro.texi (lengths-list-file): Fix textual parentheses. - -2013-12-30 Paul Eggert - - Specify .texi encoding (Bug#16292). - * emacs-lisp-intro.texi: Add @documentencoding. - -2013-12-30 Glenn Morris - - * emacs-lisp-intro.texi: Use @quotation for license notice. - -2013-12-12 Glenn Morris - - * emacs-lisp-intro.texi: Tweak dircategory. - - * emacs-lisp-intro.texi: Sync direntry with info/dir version. - -2013-12-02 Paul Eggert - - * emacs-lisp-intro.texi (Counting Words): Don't use ':' in xref - titles, as this isn't supported by Texinfo. - -2013-11-30 Glenn Morris - - * Makefile.in (distclean): Remove Makefile. - -2013-10-23 Glenn Morris - - * Makefile.in (install-dvi, install-html, install-pdf) - (install-ps, uninstall-dvi, uninstall-html, uninstall-ps) - (uninstall-pdf): Quote entities that might contain whitespace. - -2013-09-01 Glenn Morris - - * emacs-lisp-intro.texi (beginning-of-buffer complete): - Put back a version of the removed paragraph about raw prefix arg. - -2013-09-01 Dani Moncayo - - * emacs-lisp-intro.texi (beginning-of-buffer complete): - Update function details. (Bug#15085) - -2013-08-28 Paul Eggert - - * Makefile.in (SHELL): Now @SHELL@, not /bin/sh, - for portability to hosts where /bin/sh has problems. - -2013-08-12 Glenn Morris - - * emacs-lisp-intro.texi (Complete copy-region-as-kill): Fix typo. - - * emacs-lisp-intro.texi (Thank You): Avoid mailto: in html output. - - * Makefile.in (prefix, datarootdir, datadir, PACKAGE_TARNAME) - (docdir, dvidir, htmldir, pdfdir, psdir, GZIP_PROG, INSTALL) - (INSTALL_DATA): New, set by configure. - (HTML_OPTS, DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS): - New variables. - (.SUFFIXES): Add .ps and .dvi. - (.dvi.ps): New suffix rule. - (dvi, html, pdf, ps): Use *_TARGETS variables. - (emacs-lisp-intro.ps): Remove explicit rule. - (emacs-lisp-intro.html): Use HTML_OPTS. - (clean): Use DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS. - (.PHONY): install-dvi, install-html, install-pdf, install-ps, - install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, - uninstall-ps, and uninstall-doc. - (install-dvi, install-html, install-pdf, install-ps, install-doc) - (uninstall-dvi, uninstall-html, uninstall-ps, uninstall-pdf) - (uninstall-doc): New rules. - -2013-08-07 Eli Zaretskii - - * emacs-lisp-intro.texi (Beginning init File): Rename from - "Beginning a .emacs File", since a node name cannot include a - period. - (Top, Emacs Initialization, Change a defun): All references - changed. (Bug#15038) - -2013-08-02 Xue Fuqiao - - * emacs-lisp-intro.texi (zap-to-char): Remove obsolete stuff. - -2013-07-06 Glenn Morris - - * emacs-lisp-intro.texi (Top): - Move WWW_GNU_ORG section outside @copying, update URL. - -2013-07-03 Glenn Morris - - * emacs-lisp-intro.texi (edebug): Fix cross-references. - -2013-06-19 Glenn Morris - - * Makefile.in (dist): Edit more configure variables. (Bug#14660) - Try to check that we do not miss any in future. - -2013-04-24 Eli Zaretskii - - * makefile.w32-in (INFO_OPTS): Add "-I$(emacsdir)" to fix last - commit. - -2013-04-24 Glenn Morris - - * emacs-lisp-intro.texi (emacsver.texi): Include it. - (copying): For non-printed versions, uses Emacs version rather - than that of the printed book. - (Complications, Lisp macro, defvar and asterisk, defcustom): Copyedits. - * Makefile.in (emacsdir): New variable.. - (MAKEINFO_OPTS, ENVADD): Add $emacsdir. - (srcs): Add emacsver.texi. - (dist): Include emacsver.texi. Edit emacsdir. - * makefile.w32-in (emacsdir): New variable. - (INFO_SOURCES): Add emacsver.texi. - (ENVADD): Add $emacsdir (and $texinfodir). - -2013-04-23 Xue Fuqiao - - * emacs-lisp-intro.texi (Complications, defvar, Writing Defuns) - (Prevent confusion, Determining the Element, lambda): Refine the - doc about Lisp macros, reported by Glenn Morris. - -2013-04-21 Xue Fuqiao - - * emacs-lisp-intro.texi (defcustom, defun) - (simplified-beginning-of-buffer, defvar, Building Robots, Review) - (save-excursion): `defun' and `defcustom' are now macros rather - than special forms. (Bug#13853) - -2013-03-16 Glenn Morris - - * emacs-lisp-intro.texi: Add some stuff specific to www.gnu.org. - -2013-03-03 Glenn Morris - - * emacs-lisp-intro.texi (Digression into C): Update example. - (defcustom, Simple Extension): Fix typos. - -2012-12-22 Glenn Morris - - * Makefile.in (srcs): New variable, adding doclicense.texi. - (${buildinfodir}/eintr$(INFO_EXT), emacs-lisp-intro.dvi) - (emacs-lisp-intro.pdf, emacs-lisp-intro.html): - Use $srcs for dependencies. - -2012-12-14 Paul Eggert - - Fix permissions bugs with setgid directories etc. (Bug#13125) - * emacs-lisp-intro.texi (Files List): - directory-files-and-attributes now outputs t for attribute that's - now a placeholder. - -2012-12-06 Paul Eggert - - * doclicense.texi: Update to latest version from FSF. - These are just minor editorial changes. - -2012-11-24 Paul Eggert - - * doclicense.texi: Update to latest version from FSF. - These are just minor editorial changes. - -2012-10-24 Paul Eggert - - * emacs-lisp-intro.texi (Files List): - Update manual for new time stamp format (Bug#12706). - -2012-10-17 Gregor Zattler (tiny change) - - * emacs-lisp-intro.texi (Narrowing advantages): - Minor update for changed what-line implementation. (Bug#12629) - -2012-06-21 Glenn Morris - - * Makefile.in: Rename infodir to buildinfodir throughout. (Bug#11737) - -2012-05-29 Glenn Morris - - * emacs-lisp-intro.texi: Nuke hand-written node pointers. - (dolist, dotimes): Fix sectioning. - -2012-05-12 Glenn Morris - - * Makefile.in (MKDIR_P): New, set by configure. - (mkinfodir): Use $MKDIR_P. - -2012-05-05 Glenn Morris - - * emacs-lisp-intro.texi (Making Errors): Don't mention Emacs 20. - (Void Function, Wrong Type of Argument, Recursion with list) - (Simple Extension): Assume a non-ancient Emacs. - (Void Variable, Switching Buffers): Improve page breaks. - - * emacs-lisp-intro.texi: Update GNU Press contact details. - -2012-05-04 Glenn Morris - - * Makefile.in (INFO_EXT, INFO_OPTS): New, set by configure. - (info, infoclean): Use $INFO_EXT. - (${infodir}/eintr$(INFO_EXT)): Use $INFO_EXT and $INFO_OPT. - * makefile.w32-in (INFO_EXT, INFO_OPTS): New. - (INFO_TARGETS, clean): Use $INFO_EXT. - ($(infodir)/eintr$(INFO_EXT)): Use $INFO_EXT and $INFO_OPT. - -2012-05-02 Glenn Morris - - * emacs-lisp-intro.texi (Syntax): Reword to avoid underfull hbox. - -2012-04-14 Glenn Morris - - * Makefile.in: Replace non-portable use of $< in ordinary rules. - -2012-02-28 Glenn Morris - - * emacs-lisp-intro.texi: Standardize possessive apostrophe usage. - -2012-02-17 Glenn Morris - - * emacs-lisp-intro.texi (Design @value{COUNT-WORDS}, Syntax) - (count-words-in-defun): Fix cross-refs to Emacs manual. - -2012-01-28 Andreas Schwab - - * emacs-lisp-intro.texi (Top): Move setting of COUNT-WORDS outside - of @menu. (Bug#10628) - -2012-01-19 Juanma Barranquero - - * emacs-lisp-intro.texi (count-words-in-defun): - Add missing parenthesis (bug#10544). - -2012-01-17 Glenn Morris - - * emacs-lisp-intro.texi (re-search-forward): Fix typo. - -2011-11-24 Juanma Barranquero - - * makefile.w32-in: Update dependencies. - -2011-11-16 Juanma Barranquero - - * emacs-lisp-intro.texi (etags): Fix typo. - -2011-03-07 Chong Yidong - - * Version 23.3 released. - -2011-02-19 Eli Zaretskii - - * emacs-lisp-intro.texi: Sync @dircategory with ../../info/dir. - -2011-01-23 Werner Lemberg - - * Makefile.in (MAKEINFO): Now controlled by `configure'. - (MAKEINFO_OPTS): New variable. Use it where appropriate. - (ENVADD): New variable to control texi2dvi and texi2pdf. - -2010-11-13 Glenn Morris - - * emacs-lisp-intro.texi: Rename the `count-words-region' example, - since there is now a standard command of that name. - -2010-10-11 Glenn Morris - - * Makefile.in (.dvi.ps): Remove unnecessary suffix rule. - (.PHONY): Add ps. - (ps, emacs-lisp-intro.ps): New targets. - (clean): Delete ps file. - (MAKEINFO): Use --force like the other doc/ Makefiles do. - Add explicit -I$srcdir. - -2010-10-09 Glenn Morris - - * Makefile.in (VPATH): Remove. - (infodir): Make it absolute. - (mkinfodir, $(infodir)/eintr, infoclean): No need to cd $srcdir. - - * Makefile.in (dist): Anchor regexps. - - * Makefile.in (${infodir}/eintr, emacs-lisp-intro.dvi) - (emacs-lisp-intro.pdf, emacs-lisp-intro.html): Use $<. - - * Makefile.in (infoclean): Remove harmless, long-standing error. - - * Makefile.in ($(infodir)): Delete rule. - (mkinfodir): New. - ($(infodir)/eintr): Use $mkinfodir instead of infodir. - -2010-10-09 Glenn Morris - - * Makefile.in (.PHONY): Declare info, dvi, html, pdf, dist. - -2010-10-07 Glenn Morris - - * Makefile.in (version): New, set by configure. - (clean): Delete dist tar file. - (dist): Use version in tar name. - -2010-10-06 Glenn Morris - - * Makefile.in (SHELL): Use /bin/sh, like every other Makefile.in. - (INFO_SOURCES, INFO_TARGETS, DVI_TARGETS): Remove variables. - ($(infodir), html, pdf, infoclean, dist): New rules. - (${infodir}/eintr): Ensure $infodir exists. Use $@. - (emacs-lisp-intro.dvi, emacs-lisp-intro.pdf, emacs-lisp-intro.html): - Use $^. - (.PHONY): Declare clean rules. - (mostlyclean): Delete more temp files. - (clean): Delete specific dvi, pdf and html files. - (maintainer-clean): Use infoclean. - (.NOEXPORT): Remove, unused by any other Makefile.in. - -2010-09-21 Glenn Morris - - * cons-1.eps, cons-2.eps, cons-2a.eps, cons-3.eps, cons-4.eps: - * cons-5.eps, lambda-1.eps, lambda-2.eps, lambda-3.eps: - Add first line EPSF magic comment. (Bug#7064) - -2010-06-23 Glenn Morris - - * emacs-lisp-intro.texi: Untabify. - -2010-05-07 Chong Yidong - - * Version 23.2 released. - -2010-03-10 Chong Yidong - - * Branch for 23.2. - -2010-02-16 Glenn Morris - - * emacs-lisp-intro.texi: Fix typo in name of `find-tag' command. - -2010-02-01 Stefan Monnier - - * emacs-lisp-intro.texi (Text and Auto-fill, Mode Line): - Avoid obsolete special default variables like default-major-mode. - -2009-12-09 David Robinow (tiny change) - - * makefile.w32-in: Use parenthesis for macros for nmake compatibility. - -2009-12-03 Glenn Morris - - * emacs-lisp-intro.texi (Free Software and Free Manuals): - Update URL, and remove duplicate text. - -2009-10-28 Robert J. Chassell - - * emacs-lisp-intro.texi: Don't change urlcolor or linkcolor in tex - output (not needed and does not work with recent texinfo.tex). - Bump edition number. - -2009-10-27 Robert J. Chassell - - * emacs-lisp-intro.texi: Bump edition number. - -2009-10-27 Glenn Morris - - * cons-1.pdf, cons-2.pdf, cons-2a.pdf, cons-3.pdf, cons-4.pdf: - * cons-5.pdf, drawers.pdf, lambda-1.pdf, lambda-2.pdf, lambda-3.pdf: - New files, generated from .eps versions with epstopdf. - * README: Add copyright information for PDF images. - - * Makefile.in (TEXI2PDF): New variable. - (emacs-lisp-intro.pdf): New target. - - * makefile.w32-in (texinfodir, TEXI2PDF): New variables. - (ENVADD): Add -I$texinfodir. - (emacs-lisp-intro.pdf): New target. - -2009-07-28 Chong Yidong - - * emacs-lisp-intro.texi (Simple Extension): Bump emacs versions in - examples. - -2009-07-10 Glenn Morris - - * emacs-lisp-intro.texi (Top): Add missing @detailmenu entry. - -2009-07-09 Glenn Morris - - * Makefile.in (texinfodir): Rename from usermanualdir, and update. - -2009-07-06 Glenn Morris - - * emacs-lisp-intro.texi (defvar and asterisk): Minor rephrasing. - -2009-06-21 Chong Yidong - - * Branch for 23.1. - -2009-06-14 Chong Yidong - - * emacs-lisp-intro.texi (edebug): Fix typo. - -2009-02-22 Karl Berry - - * emacs-lisp-intro.texi (Default Configuration): Fix dup word "by by". - -2009-02-20 Juanma Barranquero - - * emacs-lisp-intro.texi (current-kill, Code for current-kill) - (Body of current-kill): Remove duplicate words. - -2008-11-19 Glenn Morris - - * doclicense.texi: New file. - * emacs-lisp-intro.texi: Relicense under FDL 1.3 or later. - Include doclicense.texi rather than having license in the file itself. - -2008-10-16 Sean Sieger (tiny change) - - * emacs-lisp-intro.texi (Recursion with list): Fix typo. - -2008-10-04 Karl Berry - - * emacs-lisp-intro.texi: Apply similar formatting changes as for - the emacs and lispref manuals, to save pages. A couple minor - rewordings and reformatting of code to avoid overfull and - underfull lines. - (edition-number): Bump to 3.08. - (update-date): Bump to 4 October 2008. - -2008-06-20 Eli Zaretskii - - * makefile.w32-in (distclean): Remove makefile. - -2008-06-16 Glenn Morris - - * Makefile.am, Makefile.old, aclocal.m4, configure, configure.in: - * install-sh, missing, mkinstalldirs: Remove obsolete files. - -2008-05-13 Chong Yidong - - * emacs-lisp-intro.texi (Lisp Atoms): Rephrase "in addition" to - avoid confusion with addition operation discussed in previous - paragraph. - -2008-01-31 Robert J. Chassell - - * emacs-lisp-intro.texi: Update back cover text. - -2007-09-12 Robert J. Chassell - - * emacs-lisp-intro.texi: Add email address to Thank You correctly. - -2007-09-06 Romain Francoise - - * Makefile.in (maintainer-clean): Delete info files. - -2007-09-06 Glenn Morris - - Move from lispintro/ to doc/lispintro/. - * Makefile.in (infodir): Go up one more level. - (usermanualdir): Change from ../man to ../emacs. - * makefile.w32-in (infodir, ENVADD): Go up one more level. - * emacs-lisp-intro.texi (setfilename): Go up one more level. - -2007-07-30 Robert J. Chassell - - * emacs-lisp-intro.texi: Fix typo on line 5173, change `thee' to - `these'. - -2007-07-25 Glenn Morris - - * Relicense all FSF files to GPLv3 or later. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-01-30 Robert J. Chassell - - * emacs-lisp-intro.texi (else): Rephrase message of first - if-then-else example so it is right both in itself and in the - "true" case of the expression, which asks whether 4 is greater - than 5. - -2006-11-27 Andreas Schwab - - * Makefile.in (usermanualdir): Define. - (emacs-lisp-intro.dvi): Pass -I options to texi2dvi instead of - using TEXINPUTS. - - * emacs-lisp-intro.texi: Input texinfo instead of ../man/texinfo - to fix building outside source directory. - -2006-11-09 Robert J. Chassell - - * emacs-lisp-intro.texi: Copy descriptions from detailed master - menu to menus within body. - - * emacs-lisp-intro.texi (at the beginning): Add `other shell - commands' to produce additional output formats; total is now ten. - (A Loop with an Incrementing Counter, and others): Ensure Info - menus will appear in short windows. - (Disentangle beginning-of-buffer): Replace `version 21' with `more - recent versions'. - (Simple Extension): Show how to handle multiple versions by adding - an alternative with a test of `>= 21'. - -2006-11-06 Robert J. Chassell - - * emacs-lisp-intro.texi: Finish minor changes seen from DVI output. - Replace 22.1.100 with 22.1.1. - (current-kill): Mention functions that directly or indirectly call - `kill-new', which sets `kill-ring-yank-pointer'. - (Understanding current-kill): Change `lasted' to `last'. Remove - extraneous parenthesis. Reword item about returning `car' of list. - (yank): Remove mention of `rotate-yank-pointer'. - (Y Axis Element): Add comment regarding replacement of blank space. - (print-Y-axis Penultimate): Explain that `print-graph' will pass - `height-of-top-line' so `print-Y-axis' does not have a bug. - -2006-11-05 Robert J. Chassell - - * emacs-lisp-intro.texi: Yet more minor changes: - (defcustom): Said that `:options' is usually for a hook. Remove - extraneous space in parenthetical remark concerning - `text-mode-hook-identify'. At end, mention other defines, too. - (Beginning a .emacs File): Reverse words about comments so they - parallel numbers of listed semi-colons. - (Text and Auto-fill): Remove extraneous blank line in example. - (Mail Aliases): Remove extraneous blank line in example. - (Keybindings): Reformat as needed with `key' rather than `kbd'. - (Keybindings, Miscellaneous, Mode Line): For small book format, start - section name on top of new page. - (Simple Extension): Replace longer expression with - `emacs-major-version'. Remove comment about `number-to-string' - function. - (Miscellaneous): Add filename option, `-H', to `grep' example. - (debug, debug-on-entry): Replace `GNU Emacs 22' with `a recent - GNU Emacs'. - (edebug): More properly state where to place point for 'M-x - edebug-defun'. - - * emacs-lisp-intro.texi: More minor changes. - Center images for TeX output. - (kill-new function): Remove indentation for sentence talking about - momentarily skipping code. - (cons & search-fwd Review): Document @code{funcall}. Document - @code{re-search-forward} with existing @code{search-forward}. - Reference chapter on regular expression searches. - (Recursion with list): Specify a more recent version as being Emacs. - (Recursion with list, Every, recursive-graph-body-print): Change - `if ... progn' expression to `when'. - (Recursive triangle function): For printing in small book, ensure - section name is not last on bottom of preceding page. - (Keep): Remove extraneous space in function definition example. - (sentence-end): Specify `in English' for glyphs that end a sentence. - Note that in GNU Emacs 22, the name refers to both a variable and a - function. - (fwd-sentence while loops): Write a function as one, not as a form. - (fwd-para let): Add `which' to sentence with `parstart' and `parsep'. - (etags): Move sentences involving `find-tag' and sources. State - location of Emacs `src' directory. - (Design count-words-region): Better explain two backslashes in a row. - (Find a File): Fix grammar; add a `to' and write `to visit'. Change - `named' to `selected'. - (lengths-list-file): Remove extraneous parenthesis from reference. - (lengths-list-many-files): Explain `expand-file-name' better. - (Files List): Rephrase sentence regarding Lisp sources directory. - -2006-11-04 Robert J. Chassell - - * emacs-lisp-intro.texi: Replace 22.0.100 with 22.1.100. - (defcustom): Note that the value set by defconst is a variable. - (Buffer Size & Locations): Parenthetical remark about evaluation. - (Finding More): Change text to include C sources by inference. - - * emacs-lisp-intro.texi: Minor fixes. - Replace all tabs with eight spaces each so printed text looks correct. - Remove extraneous comma in a printed node name produced by `ref'. - (insert-buffer): Add a missing beginning parenthesis. - (beginning-of-buffer): Add `beginning of' to note about accessible - portion. - (narrow Exercise): Write closing parenthesis at end of correct - paragraph. - (zap-to-char): Remove extraneous `a' from first sentence. - (Complete zap-to-char): Remove two extraneous sentences. - (zap-to-char body): Move sentences on documentation two nodes earlier. - (Lisp macro): Add definition of `unless' macro. - (last-command & this-command): Remove comment that `we have not yet - seen' the @code{eq} function. - (kill-append function): Reformat `kill-append' function definition so - it prints well. - (kill-new function): Indent the sentence beginning `notice'. Replace - `the same as' with `similar to'. Repair typo. Remove obsolete - references to `yank' and `yank-pop. End section with a note that `we - will digress into C.' - -2006-11-02 Robert J. Chassell - - * emacs-lisp-intro.texi (kill-ring-yank-pointer): Revert addition - of extraneous quotation mark to rotate-yank-pointer. - -2006-11-01 Juri Linkov - - * emacs-lisp-intro.texi: Fix unbalanced quotes. - -2006-10-31 Robert J. Chassell - - * emacs-lisp-intro.texi: Revised text for kill-region, - copy-region-as-kill, kill-append, kill-new, forward-sentence, - forward-paragraph, find-file, current-kill, yank, and yank-pop. - Removed INSTALL MANIFEST from the directory since those files are - now irrelevant. Updated Info file in ../info. Changed numbering - so is now Revised Third Edition and this instance's edition-number - is 3.00. Did not update ISBN number. - - * emacs-lisp-intro.texi: Remove version reference for X colors. - Document `='. Remove mention that :eval was new in 21. Updated - instance's edition-number to 3.01. - -2006-10-30 Robert J. Chassell - - * emacs-lisp-intro.texi: Many changes since it turned out that - many `simple' functions were rewritten. Changes to the text - regarding zap-to-char, mark-whole-buffer, append-to-buffer, - copy-to-buffer, beginning-of-buffer, what-line, and possibly - others. (I have not reviewed all yet.) This instance does build - for Info and TeX. - -2006-10-29 Chong Yidong - - * Makefile.in: Use relative paths to avoid advertising filesystem - contents during compilation. - -2006-08-21 Robert J. Chassell - - * emacs-lisp-intro.texi: Deleted in directory copy of texinfo.tex - and pointed towards ../man/texinfo.tex so only one file - needs updating. Added comment of what to do when building on own. - - * texinfo.tex: Changed to version 2006-02-13.16 - to enable a DVI build using the more recent versions of TeX. - -2006-05-25 David Kastrup - - * emacs-lisp-intro.texi (setcar): Replace an antelope rather than - a giraffe with a hippopotamus. - -2006-05-19 Thien-Thi Nguyen - - * emacs-lisp-intro.texi (Digression concerning error): Fix typo. - -2005-09-16 Romain Francoise - - * emacs-lisp-intro.texi (GNU Free Documentation License): - Specify GFDL version 1.2. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run install-info. - ($(infodir)/dir): New target, produced by running install-info. - -2005-07-04 Lute Kamstra - - Update FSF's address in GPL notices. - - * emacs-lisp-intro.texi: Update FSF's address. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (mostlyclean, clean, maintainer-clean): - Use $(DEL) instead of rm, and ignore exit code. - -2003-11-16 Kevin Ryde - - * emacs-lisp-intro.texi: [CVS commitment by ] - Corrections to cross references. - (Interactive Options): elisp "interactive" -> "Using Interactive". - (defvar and asterisk): Remove emacs "Edit Options" reference, - edit-options is no longer described in the emacs manual. - (Lists diagrammed): elisp "List Type" -> "Cons Cell Type". - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2001-11-29 Eli Zaretskii - - * emacs-lisp-intro.texi (Index): @ignore extraneous text. - Use @dircategory and @direntry to define the DIR entry. - -2001-11-25 Robert J. Chassell - - * emacs-lisp-intro.texi: Move @contents to the beginning of the - file. Set the size to @smallbook. - -2001-11-24 Eli Zaretskii - - * Makefile.in: New file. - - * README: Update. - - * *.eps: Rename to avoid clashes in DOS 8+3 namespace. - -;; Local Variables: -;; coding: utf-8 -;; End: - - Copyright (C) 2001-2014 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in deleted file mode 100644 index f88a8cb419b..00000000000 --- a/doc/lispintro/Makefile.in +++ /dev/null @@ -1,207 +0,0 @@ -### @configure_input@ - -# Copyright (C) 1994-1999, 2001-2014 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -SHELL = @SHELL@ - -# NB If you add any more configure variables, -# update the sed rules in the dist target below. -srcdir = @srcdir@ -version=@version@ - -buildinfodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs - -prefix = @prefix@ -datarootdir = @datarootdir@ -datadir = @datadir@ -PACKAGE_TARNAME = @PACKAGE_TARNAME@ -docdir = @docdir@ -dvidir = @dvidir@ -htmldir = @htmldir@ -pdfdir = @pdfdir@ -psdir = @psdir@ - -MKDIR_P = @MKDIR_P@ - -GZIP_PROG = @GZIP_PROG@ - -HTML_OPTS = --no-split --html - -INFO_EXT=@INFO_EXT@ -# Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ - -INSTALL = @INSTALL@ -INSTALL_DATA = @INSTALL_DATA@ - -MAKEINFO = @MAKEINFO@ -MAKEINFO_OPTS = --force -I $(emacsdir) -I $(srcdir) -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips - -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" - -DVI_TARGETS = emacs-lisp-intro.dvi -HTML_TARGETS = emacs-lisp-intro.html -PDF_TARGETS = emacs-lisp-intro.pdf -PS_TARGETS = emacs-lisp-intro.ps - -mkinfodir = @${MKDIR_P} ${buildinfodir} - -srcs = ${srcdir}/emacs-lisp-intro.texi ${srcdir}/doclicense.texi \ - ${emacsdir}/emacsver.texi - -.PHONY: info dvi html pdf ps - -.SUFFIXES: .ps .dvi - -.dvi.ps: - $(DVIPS) -o $@ $< - -info: ${buildinfodir}/eintr$(INFO_EXT) - -dvi: $(DVI_TARGETS) -html: $(HTML_TARGETS) -pdf: $(PDF_TARGETS) -ps: $(PS_TARGETS) - -# The file name eintr must fit within 5 characters, to allow for -# -NN extensions to fit into DOS 8+3 limits without clashing. -# Note: "<" is not portable in ordinary make rules. -${buildinfodir}/eintr$(INFO_EXT): ${srcs} - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/emacs-lisp-intro.texi - -emacs-lisp-intro.dvi: ${srcs} - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-lisp-intro.texi - -emacs-lisp-intro.pdf: ${srcs} - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-lisp-intro.texi - -emacs-lisp-intro.html: ${srcs} - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/emacs-lisp-intro.texi - -.PHONY: mostlyclean clean distclean maintainer-clean infoclean - -mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs - -clean: mostlyclean - rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) - rm -f emacs-lispintro-${version}.tar* - -distclean: clean - rm -f Makefile - -infoclean: - -cd $(buildinfodir) && rm -f eintr$(INFO_EXT) eintr$(INFO_EXT)-[1-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -dist: - rm -rf emacs-lispintro-${version} - mkdir emacs-lispintro-${version} - cp ${srcdir}/*.texi ${srcdir}/*.eps ${srcdir}/*.pdf \ - ${texinfodir}/texinfo.tex ${emacsdir}/emacsver.texi \ - ${srcdir}/ChangeLog* ${srcdir}/README emacs-lispintro-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(emacsdir *=\).*/\1 ./' \ - -e 's/^\(buildinfodir *=\).*/\1 ./' \ - -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \ - -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \ - -e 's|@SH[E]LL@|/bin/bash|' \ - -e 's|@[p]refix@|/usr/local|' \ - -e 's|@[d]atarootdir@|$${prefix}/share|' \ - -e 's|@[d]atadir@|$${datarootdir}|' \ - -e 's|@[P]ACKAGE_TARNAME@|emacs|' \ - -e 's|@[d]ocdir@|$${datarootdir}/doc/$${PACKAGE_TARNAME}|' \ - -e 's|@[d]vidir@|$${docdir}|' \ - -e 's|@[h]tmldir@|$${docdir}|' \ - -e 's|@[p]dfdir@|$${docdir}|' \ - -e 's|@[p]sdir@|$${docdir}|' \ - -e 's|@[G]ZIP_PROG@|gzip|' \ - -e 's|@IN[S]TALL@|install -c|' \ - -e 's|@IN[S]TALL_DATA@|$${INSTALL} -m 644|' \ - -e '/@[c]onfigure_input@/d' \ - ${srcdir}/Makefile.in > emacs-lispintro-${version}/Makefile - @if grep '@[a-zA-Z_]*@' emacs-lispintro-${version}/Makefile; then \ - echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \ - fi - tar -cf emacs-lispintro-${version}.tar emacs-lispintro-${version} - rm -rf emacs-lispintro-${version} - - -.PHONY: install-dvi install-html install-pdf install-ps install-doc - -install-dvi: dvi - umask 022; $(MKDIR_P) "$(DESTDIR)$(dvidir)" - $(INSTALL_DATA) $(DVI_TARGETS) "$(DESTDIR)$(dvidir)" -install-html: html - umask 022; $(MKDIR_P) "$(DESTDIR)$(htmldir)" - $(INSTALL_DATA) $(HTML_TARGETS) "$(DESTDIR)$(htmldir)" -install-pdf: pdf - umask 022;$(MKDIR_P) "$(DESTDIR)$(pdfdir)" - $(INSTALL_DATA) $(PDF_TARGETS) "$(DESTDIR)$(pdfdir)" -install-ps: ps - umask 022; $(MKDIR_P) "$(DESTDIR)$(psdir)" - for file in $(PS_TARGETS); do \ - $(INSTALL_DATA) $${file} "$(DESTDIR)$(psdir)"; \ - [ -n "${GZIP_PROG}" ] || continue; \ - rm -f "$(DESTDIR)$(psdir)/$${file}.gz"; \ - ${GZIP_PROG} -9n "$(DESTDIR)$(psdir)/$${file}"; \ - done - -## Top-level Makefile installs the info pages. -install-doc: install-dvi install-html install-pdf install-ps - - -.PHONY: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps uninstall-doc - -uninstall-dvi: - for file in $(DVI_TARGETS); do \ - rm -f "$(DESTDIR)$(dvidir)/$${file}"; \ - done -uninstall-html: - for file in $(HTML_TARGETS); do \ - rm -f "$(DESTDIR)$(htmldir)/$${file}"; \ - done -uninstall-ps: - ext= ; [ -n "${GZIP_PROG}" ] && ext=.gz; \ - for file in $(PS_TARGETS); do \ - rm -f "$(DESTDIR)$(psdir)/$${file}$${ext}"; \ - done -uninstall-pdf: - for file in $(PDF_TARGETS); do \ - rm -f "$(DESTDIR)$(pdfdir)/$${file}"; \ - done - -uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps - - -### Makefile ends here diff --git a/doc/lispintro/README b/doc/lispintro/README deleted file mode 100644 index 872813e6d2b..00000000000 --- a/doc/lispintro/README +++ /dev/null @@ -1,45 +0,0 @@ -Copyright (C) 2001-2014 Free Software Foundation, Inc. -See the end of the file for license conditions. - - -This directory contains the source of the "Introduction to Programming -in Emacs Lisp" written by Robert J. Chassell, bob@gnu.org. This -manual is an elementary introduction to programming in Emacs Lisp for -people who are not programmers, and who are not necessarily interested -in programming, but who do want to customize or extend their computing -environment. - -This third edition of 2006 Oct 31 updates the previous editions to GNU -Emacs 22. - -You will find additional instructions on formatting in the beginning -of the Texinfo file 'emacs-lisp-intro.texi'. Best Wishes! - -2006 Oct 31 -Robert J. Chassell, bob@gnu.org - - - -COPYRIGHT AND LICENSE INFORMATION FOR IMAGE FILES - -The PostScript images (*.eps) contain copyright and license information -in their headers. The PDF versions were automatically generated using -the epstopdf utility, and are subject to the same conditions as their -EPS counterparts. - - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/doc/lispintro/cons-1.eps b/doc/lispintro/cons-1.eps deleted file mode 100644 index 06cc7cc5e64..00000000000 --- a/doc/lispintro/cons-1.eps +++ /dev/null @@ -1,578 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 35 711 289 757 -%%Title: cons-cell-diagram1 -%%CreationDate: Wed Mar 8 14:26:58 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2014 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 35 711 289 757 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% BOX -gsave - 1.415 setmiterlimit - newpath - 66 66 moveto 130 66 lineto 130 98 lineto 66 98 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 98 66 moveto - 98 98 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 114 82 moveto - 0 80 atan dup cos 8 mul 194 exch sub - exch sin 8 mul 82 exch sub lineto - stroke -grestore -gsave - newpath - 194 82 8 3 80 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 146 136 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 82 82 moveto - 82 131 lineto - 0 48 atan dup cos 8 mul 130 exch sub - exch sin 8 mul 131 exch sub lineto - stroke -grestore -gsave - newpath - 130 131 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 199 66 moveto 263 66 lineto 263 98 lineto 199 98 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 231 66 moveto - 231 98 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 247 82 moveto - 0 93 atan dup cos 8 mul 340 exch sub - exch sin 8 mul 82 exch sub lineto - stroke -grestore -gsave - newpath - 340 82 8 3 93 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 279 136 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 215 82 moveto - 215 131 lineto - 0 48 atan dup cos 8 mul 263 exch sub - exch sin 8 mul 131 exch sub lineto - stroke -grestore -gsave - newpath - 263 131 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 342 64 moveto 406 64 lineto 406 96 lineto 342 96 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 373 64 moveto - 373 96 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 389 81 moveto - 0 48 atan dup cos 8 mul 437 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 437 81 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 421 135 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 357 81 moveto - 357 130 lineto - 0 48 atan dup cos 8 mul 405 exch sub - exch sin 8 mul 130 exch sub lineto - stroke -grestore -gsave - newpath - 405 130 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 449 87 moveto (nil) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:26:58 1995 diff --git a/doc/lispintro/cons-1.pdf b/doc/lispintro/cons-1.pdf deleted file mode 100644 index 2ee86b12311..00000000000 --- a/doc/lispintro/cons-1.pdf +++ /dev/null @@ -1,71 +0,0 @@ -%PDF-1.3 -%Ç쏢 -5 0 obj -<> -stream -xœ“ËNÃ0E÷󳄍ñøí-bÕEi¾€*EE ¥/ø}lÇvݖnªH‰æú:¾s2Ù"g„<^ù¹áéÍâÇ43Bã/S¤q„kàø -‚XЅvÌj”†#9Ž»Á1ÁÓ²’iy,u¶Á%|R¤ÊãMSGÇ°ê—$播fÊ9À -¶@©̏åˆÏ]hÇ¡g:šºL]*Ë(ædAáa·Ù÷Ý'¼t0¢ó³smeÚ2€”æ¬^€t­c,îuƒç)fjgÒÞFéÕ´^Y¡I\Í5Y5YvF“BëL_;*É"ÜI’Â@ø¡ üYo†þPa:=…®ç¡â#îTì¡áI$|#ÕSˆ–ú)é°#²üš'ف*Íãs­éH'S-µJñâèÙ*ixÃÁ7\2BNµ%vÍø¿¸°]3žVÐ÷ãáÐï–ÇïӀ}‘¢(6vrN¶uèϋÆ1V‡©cßˆ8D&d§ä_ë¡fžÃՊâendstream -endobj -6 0 obj -390 -endobj -4 0 obj -<> -/Contents 5 0 R ->> -endobj -3 0 obj -<< /Type /Pages /Kids [ -4 0 R -] /Count 1 ->> -endobj -1 0 obj -<> -endobj -7 0 obj -<>endobj -9 0 obj -<> -endobj -10 0 obj -<> -endobj -8 0 obj -<> -endobj -2 0 obj -<>endobj -xref -0 11 -0000000000 65535 f -0000000702 00000 n -0000000912 00000 n -0000000643 00000 n -0000000494 00000 n -0000000015 00000 n -0000000475 00000 n -0000000750 00000 n -0000000850 00000 n -0000000791 00000 n -0000000820 00000 n -trailer -<< /Size 11 /Root 1 0 R /Info 2 0 R -/ID [(ª@}`&¿ÆÈ'S©‚Ü)(ª@}`&¿ÆÈ'S©‚Ü)] ->> -startxref -1023 -%%EOF diff --git a/doc/lispintro/cons-2.eps b/doc/lispintro/cons-2.eps deleted file mode 100644 index e942b6264e7..00000000000 --- a/doc/lispintro/cons-2.eps +++ /dev/null @@ -1,600 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 15 712 321 775 -%%Title: cons-cell-diagram2 -%%CreationDate: Wed Mar 8 14:26:39 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2014 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 15 712 321 775 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 32 47 moveto (bouquet) show - grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 122 65 moveto 186 65 lineto 186 97 lineto 122 97 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 154 65 moveto - 154 97 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 170 81 moveto - 0 80 atan dup cos 8 mul 250 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 250 81 8 3 80 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 202 135 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 138 81 moveto - 138 130 lineto - 0 48 atan dup cos 8 mul 186 exch sub - exch sin 8 mul 130 exch sub lineto - stroke -grestore -gsave - newpath - 186 130 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 255 65 moveto 319 65 lineto 319 97 lineto 255 97 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 287 65 moveto - 287 97 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 303 81 moveto - 0 93 atan dup cos 8 mul 396 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 396 81 8 3 93 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 335 135 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 271 81 moveto - 271 130 lineto - 0 48 atan dup cos 8 mul 319 exch sub - exch sin 8 mul 130 exch sub lineto - stroke -grestore -gsave - newpath - 319 130 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 398 63 moveto 462 63 lineto 462 95 lineto 398 95 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 429 63 moveto - 429 95 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 445 80 moveto - 0 48 atan dup cos 8 mul 493 exch sub - exch sin 8 mul 80 exch sub lineto - stroke -grestore -gsave - newpath - 493 80 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 477 134 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 413 80 moveto - 413 129 lineto - 0 48 atan dup cos 8 mul 461 exch sub - exch sin 8 mul 129 exch sub lineto - stroke -grestore -gsave - newpath - 461 129 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 505 86 moveto (nil) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 66 53 moveto - 66 81 lineto - 0 46 atan dup cos 8 mul 112 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 112 81 8 3 46 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:26:39 1995 diff --git a/doc/lispintro/cons-2.pdf b/doc/lispintro/cons-2.pdf deleted file mode 100644 index c26906f6f86cb89d237c16510dd5e82ae719ba37..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1399 zcmZuxe@qi+7~Ui#=F3zTrAku5H#U}*rQThy*Oq}Dk+u%CQhLpFbag512h^3GyE{xJ zvH@9Gh7K03L}X0#4}VXiZrO~T(Fuyd40TcrE^KpT(F9EpH^`h}-&YEq#rx;(p7(v8 zdw)FN<=D+u4YQmDIafwo4*(9*P$=I73JR#TC|D_1K|Mwsl+_=Qkq9Ykz#}6w@(Mm= zG66{zk*6AjzU<`t94W7)MaI*We>GlvDP?pZw~t?VV_U#*#6r~v!tvj#$q-|pCN%od`rwiLq#>j*0=7@5M%Xc=U_+#T2ueF0^ z-2*@W{Z0PYErZ+FfB0RRbTOCNH!u8R+nMh_(Cj(h3{RJiY}omE>sZ;t^>>*^?C)^A z$!c2Q#vHuKtA;JI(d~c7V>+d*8Ve33QL|tIgUL>{q#;{3SC(F= z-JMz6bbg0>L1tEN*2i@xC%lKR2DYcy6QwlGa+Bq_re#X;#^p=ut-q%p`LXE91~GchAgoNpd3gNYD6!RuzBpF;N_9*qOiRnnfKWLjFUFA`N2-VRq) z36d;%MgL|Q8X0amtySZZ;u9+Sg`gRaU1fe#OVfD_t<^I|R>$aZ+$Q**ADZnmB%%sH zLxutL>;?54$8xX&&R_->4}e@SIE&@!=3;sS?ma1w)8bJkVKjp+kc4q$s7aW?I5*Gu zJWPwNp2RhB|KrM{#~(l<{_#PI_tzraFQgoTfXzg92dUy. - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 15 702 300 767 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 32 62 moveto (bouquet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 64 80 moveto - 64 120 lineto - 0 49 atan dup cos 8 mul 113 exch sub - exch sin 8 mul 120 exch sub lineto - stroke -grestore -gsave - newpath - 113 120 8 3 49 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 128 110 moveto (car) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 128 142 moveto (rose) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 192 110 moveto (cdr) show - grestore - -% OVAL -gsave - newpath 207 124 4 4 tgifellipse stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 217 123 moveto - 0 38 atan dup cos 8 mul 255 exch sub - exch sin 8 mul 123 exch sub lineto - stroke -grestore -gsave - newpath - 255 123 8 3 38 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 268 111 moveto (car) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 264 143 moveto (violet) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 332 111 moveto (cdr) show - grestore - -% OVAL -gsave - newpath 347 125 4 4 tgifellipse stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 357 124 moveto - 0 38 atan dup cos 8 mul 395 exch sub - exch sin 8 mul 124 exch sub lineto - stroke -grestore -gsave - newpath - 395 124 8 3 38 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 408 112 moveto (car) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 408 136 moveto (butter-) show - 408 153 moveto (cup) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 496 113 moveto (cdr) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 495 137 moveto (nil) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 178 86 moveto - 178 157 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 485 84 moveto - 485 157 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 327 85 moveto - 327 157 lineto - stroke -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 120 86 moveto 234 86 lineto 234 157 lineto 120 157 lineto - closepath stroke - 1 setmiterlimit -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 257 85 moveto 371 85 lineto 371 157 lineto 257 157 lineto - closepath stroke - 1 setmiterlimit -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 397 84 moveto 531 84 lineto 531 157 lineto 397 157 lineto - closepath stroke - 1 setmiterlimit -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Tue Mar 14 15:09:30 1995 diff --git a/doc/lispintro/cons-2a.pdf b/doc/lispintro/cons-2a.pdf deleted file mode 100644 index c159e8b9d82a20fc18c928aea9591ff493eb2df3..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1504 zcmZuxdr%a09JhyB>uJ~^M4A2IJUu{fANSyRhyur5N1oi=9fBTL9(Q|ibnG&_iyn{U zSvK^7A;6+3CMgsoh#AMi0<2NIQHU&ajHs9}=A@Bv7{RE?ehUW#vH$G;KHu->v){*O zSEN^|cj6K$BI^6&tq&17zyO_*jl{&Ddr2yj%K{3B7*Ms-#gPm^)h;VXsz@7cCu3s~ zmSae34&r{V*3?f8VS?`QP|jS~5tj6}$g);&&UK7BT6#_Qn&3|7XP&7UVW{VDrKPO5 zT6^^GZ#7r9=d91V+*9yoO~Ji@yW>e}*K)9wuqCq*?3o@+c7m{Js1 z_;lF=Kj?1V_PQf2hsXXJX`Ydt)NB%*xc~UQ@Lh#B#b8bA_I%bJEmnn}40$Q__*Wsx zt=G1BI?oG_`yZHOjOT;1>+34}o{^@m(?0gX_rpa+L&L@T?(3)B+a@Q!NMCb$LYHK! zl%^l72{zk=21-NZGeIR6>!+(r0`_hQxtZQV?bAu(G-odPgXoqMGsIIn!+KbgHdSz@ z^McdteYUCWjVnLK3sWYF>JF{@w1Ro`Y}cmMrn-`Vh$GRHzm|`*UdTS+o!G3I2=f+C z^(6#_e2{j(=lQLvj|_Y{C~teR>%okVYdlx|yt|QU(BDGb2{bC6*sps1&#*l;FCtT~ z))G-WhMU#7Rqc%IotUJJ;k_d%B}dLy?fa;A6gB?d)ZbSBlPFW@8tVvdlnhw!p30|l z{J+^a?afYzIpx;8FBzMpZfEJ<6^8a*rVWQ25uap#*FF%CmKstua{ZqU8L>KON5#*V zdQ*aCx`w!6znA?+KOY(2pZ`#4tkyOd*YHZqjWR)euIs4NFwWxzEOHb)?MD% z<~X>%$Frq;tXeJpWov0nOYtf)Fp;F}K4-uu-c7uR_`94?B0fmAXf#uPE{W=`nIx(s z?M`bv?FMEHh6$w{DC8Cd#u$>~fRuM4f*MGc&SPvO3q7i5Xq%Db%qVm*Kux5ZgXxKG zPGjVtPeJ4yLrp_A&Py5)=vp)Zo}nNMc(>0&zM}Xy%()+m!K%P)Su8-GbJ|&8M);x) zhy_4}JYJGl^HK2ys*jmq<*Y6`b6#Su_{IE)rTL3RBWSW-2k_WfpD^Ep?~61*j!H7^eQurg_oHV6^V;8HU2n>tFF+zbWr7~Or<2u^Da%iDX zH$yrQ4B$9|EnIN@a;Y3Rz&xgu!7cI^pyn|glm8FHB9w3+OY<;=6n3->!*FPUWtako zyIO`Rm2j5Ju*j7#0. - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: -1 691 324 757 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% BOX -gsave - 1.415 setmiterlimit - newpath - 128 102 moveto 192 102 lineto 192 134 lineto 128 134 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 160 102 moveto - 160 134 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 176 124 moveto - 0 80 atan dup cos 8 mul 256 exch sub - exch sin 8 mul 124 exch sub lineto - stroke -grestore -gsave - newpath - 256 124 8 3 80 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 208 172 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 144 118 moveto - 144 167 lineto - 0 48 atan dup cos 8 mul 192 exch sub - exch sin 8 mul 167 exch sub lineto - stroke -grestore -gsave - newpath - 192 167 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 261 102 moveto 325 102 lineto 325 134 lineto 261 134 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 293 102 moveto - 293 134 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 309 118 moveto - 0 93 atan dup cos 8 mul 402 exch sub - exch sin 8 mul 118 exch sub lineto - stroke -grestore -gsave - newpath - 402 118 8 3 93 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 341 172 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 277 118 moveto - 277 167 lineto - 0 48 atan dup cos 8 mul 325 exch sub - exch sin 8 mul 167 exch sub lineto - stroke -grestore -gsave - newpath - 325 167 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 404 100 moveto 468 100 lineto 468 132 lineto 404 132 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 435 100 moveto - 435 132 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 451 117 moveto - 0 48 atan dup cos 8 mul 499 exch sub - exch sin 8 mul 117 exch sub lineto - stroke -grestore -gsave - newpath - 499 117 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 483 171 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 419 117 moveto - 419 166 lineto - 0 48 atan dup cos 8 mul 467 exch sub - exch sin 8 mul 166 exch sub lineto - stroke -grestore -gsave - newpath - 467 166 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 511 123 moveto (nil) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 131 80 moveto (flowers) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 210 75 moveto - 237 75 lineto - 237 113 lineto - 0 18 atan dup cos 8 mul 255 exch sub - exch sin 8 mul 113 exch sub lineto - stroke -grestore -gsave - newpath - 255 113 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 2 80 moveto (bouquet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 81 77 moveto - 108 77 lineto - 108 115 lineto - 0 18 atan dup cos 8 mul 126 exch sub - exch sin 8 mul 115 exch sub lineto - stroke -grestore -gsave - newpath - 126 115 8 3 18 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:25:41 1995 diff --git a/doc/lispintro/cons-3.pdf b/doc/lispintro/cons-3.pdf deleted file mode 100644 index 91046d06e9c52c7691697b131715e3354a0a65f8..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1475 zcmZuxeM}Q)9G=OtEvF$Oj!tCwj-?Yu>D{$lTRs8~3dpduw3uZgxI$lOwf6AtI;t}p zfsIThBa3V!V98)0!jvrpH|lhJxXGlb5td~PMk7kx0wch}R5WAn3k3#x|J>d4`#sP5 z`*`leI(1SwEtM1Eo{920f&mm@bM_N4G2||2%NNW*fe<~JWU&g617wobC_pvLWlb

(wC|2onM;wc`@qnA;9SGHjHYMmUBwv#GokuNwI9_wDw_jKWYVs4svmB*dggxZ zo9Wr;d}qt%#`z7I>C&e+b*8>9Eq!x1@LuEe(3Ip|pV4eb*^5oTX*&OGsC^|nUAAqH zUAkM*%QO`>zi`0v@!!OhyS|fa`L@l!PTQA$x++mEX-ppgQGc9C8|dF(#!R<`&8$Cj zwDp4Ne(R9-wyWVet7mBMhm1zl7acrutvXw-)SNg!s=XRK*Y>j6aLdrLlaAZ=Y?_qp zFFp~o{Yu4_%b#C#2Z-bom1k$BKIy%q6K($L$d74t3Gn2#3Tw*jy|JS~<<;&Ee@Vc@ zn+b5QGma|?O7{FB9CwAbA50K;+ucPYVX~WkXRpssp1$+I|D_u~DX+CgKk`)$S>~gH zwBs#1ej4u`x%aVZEFAwhX z`OJ3r>Ze-2o>OkKq`qZ+&8yj-$Z<{;HXRapzox1>@9-s2peV-GA!2{;6Z6n!@~$5} zVas5n;5$RngcpifaZ|?O0!ZqN`H<8=lf@X%IzT3c!g3h{6pAbY#W-jafE?S6AoY-E z?OZP8kr8zqn`?kVCW)*H$PDNZPeq*kW^bZo3w828})?DR?k)ATDU3r#IWRfKAF6u)|d@kSovG2qHM3*;7xBr!se z278WxSAaW4=Pq?5TVbOyo9wxe3rRHSK(d+T1wNOv6bL{?Gg3+xibjgQcEQ5h)M)G> z>L?jSMbeZ^L965uv;xI7tm(<2Vhg{HPPPyRoyz!@!8$f2JoAPtry z5cLa4J. - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 6 681 355 758 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% POLY/OPEN-SPLINE -gsave - newpath - 274 102 moveto - 274 134 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 289 122 moveto - 0 56 atan dup cos 8 mul 345 exch sub - exch sin 8 mul 122 exch sub lineto - stroke -grestore -gsave - newpath - 345 122 8 3 56 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 350 100 moveto 414 100 lineto 414 132 lineto 350 132 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 382 100 moveto - 382 132 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 397 114 moveto - 0 59 atan dup cos 8 mul 456 exch sub - exch sin 8 mul 114 exch sub lineto - stroke -grestore -gsave - newpath - 456 114 8 3 59 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 430 170 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 366 116 moveto - 366 165 lineto - 0 48 atan dup cos 8 mul 414 exch sub - exch sin 8 mul 165 exch sub lineto - stroke -grestore -gsave - newpath - 414 165 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 219 78 moveto (flowers) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 298 73 moveto - 325 73 lineto - 325 111 lineto - 0 18 atan dup cos 8 mul 343 exch sub - exch sin 8 mul 111 exch sub lineto - stroke -grestore -gsave - newpath - 343 111 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 459 95 moveto 523 95 lineto 523 127 lineto 459 127 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 490 95 moveto - 490 127 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 506 112 moveto - 0 48 atan dup cos 8 mul 554 exch sub - exch sin 8 mul 112 exch sub lineto - stroke -grestore -gsave - newpath - 554 112 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 566 118 moveto (nil) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 538 151 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 474 109 moveto - 474 146 lineto - 0 48 atan dup cos 8 mul 522 exch sub - exch sin 8 mul 146 exch sub lineto - stroke -grestore -gsave - newpath - 522 146 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 244 102 moveto 308 102 lineto 308 134 lineto 244 134 lineto - closepath stroke - 1 setmiterlimit -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 324 189 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 260 117 moveto - 260 184 lineto - 0 48 atan dup cos 8 mul 308 exch sub - exch sin 8 mul 184 exch sub lineto - stroke -grestore -gsave - newpath - 308 184 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 146 101 moveto 210 101 lineto 210 133 lineto 146 133 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 177 101 moveto - 177 133 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 193 118 moveto - 0 48 atan dup cos 8 mul 241 exch sub - exch sin 8 mul 118 exch sub lineto - stroke -grestore -gsave - newpath - 241 118 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 187 178 moveto (lily) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 163 118 moveto - 163 171 lineto - 0 18 atan dup cos 8 mul 181 exch sub - exch sin 8 mul 171 exch sub lineto - stroke -grestore -gsave - newpath - 181 171 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 16 78 moveto (bouquet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 95 73 moveto - 122 73 lineto - 122 111 lineto - 0 18 atan dup cos 8 mul 140 exch sub - exch sin 8 mul 111 exch sub lineto - stroke -grestore -gsave - newpath - 140 111 8 3 18 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:25:06 1995 diff --git a/doc/lispintro/cons-4.pdf b/doc/lispintro/cons-4.pdf deleted file mode 100644 index 1165ef03de51bde98e7400700a887fc608f981e8..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1587 zcmY!laBp~n!G=6{e{1j2>6SX}UwNA6aF=W5z6GjpmlXSY z+`91a{Y3dq`5BQdCsq3TRerzlxaOF}8Z_NM{{7}3KXgwWPk$I{5VwzOLj23!!cldC z4+KOO-fP?RgfSw%(e)13hlMR(>1(>KvcHwmu#2)2>iJb`FDnvuywM`|q|PJ9hN1`D zOP6dsa#JAm=T)JA(~q|qC~UqMarT~QvE1)xaTXFCVT`hJ8}8=I$X+VHdNBL{_N&gz zuWft5zP`C()#5j&Yp2aOTcUbuNloD`f$z^0c$bFuF|OCqovpL3?(MhJ-<}?R=2>&E zL;957)#|zVUn==6IA$!n?b5N4Gd-@ds&(^>E0g#1m^p-mn0g8|Wp0t5_V@L-A2yZj zD|!WjR;?8L>@mk9&23tv&sT=tV6kuxQ9~UXH;3;q?wJ^qz=0L^B3jc7;O}7^G)k(ZBwAK zpK9B*)Qn~3wo`Jv?^~xG;Ap?Hd+ST%9(T2~Q$+)6eSWp~OZK--ycjp#RCur53T1cg zu#%g)``Z`2h@Q;D#dD$My|`LNxc`%|CF_)d-rgz~+1mQQg6VZ+@pgMzztxg27p;DD zCQ|s!%@2_hGm2Fc-p;%_r*rF{;!`F3^9*yX)z9?)VCGm~bUHOJ1)AJ|EKm{!B}_1F zXv_r_GC`!?kjjEo{eZ;uRDIvnl*~k@{0fC=1E93AiKT+Mc`O%Dt|&FHM8O!8yt(v) zQj7CTi;`1|feAmLC_gzkwIo^}m^BpiLsBbBfXZDfO5B4>fQeth5~9N`AE?_9WMmK* zFe~Ug1NlG$ixogw2rLA36vzfhmI4|Ebd>_wS;Y$a-kB-I3ej93M+b4mDgaF=1sMr4 z4XV`;t`(}&Ik6-$CqEr#1jO+O_2#JR5sv24_Yd$@FtoFS8VvFSG@A#RbAhx4Axr^# z3MOm8Wq~RS;zA{z5{pwo!2oi3QD$lp*pd1m5ib4U(xehl6o7mTv=`BrDDRt}f?W#k&x)edG%f=LLqjeDI8ZP%H8nO>NK=4`SsDSO3&Mrq0qF7=Nf@h6dQg41q}mU7ZP%-jbrk%$(FB zV4hHz{06CE}hyVZp diff --git a/doc/lispintro/cons-5.eps b/doc/lispintro/cons-5.eps deleted file mode 100644 index 14edd8432a4..00000000000 --- a/doc/lispintro/cons-5.eps +++ /dev/null @@ -1,622 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 15 680 305 764 -%%Title: cons-cell-diagram5 -%%CreationDate: Wed Mar 8 14:27:28 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2014 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 15 680 305 764 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% POLY/OPEN-SPLINE -gsave - newpath - 156 105 moveto - 156 137 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 171 125 moveto - 0 56 atan dup cos 8 mul 227 exch sub - exch sin 8 mul 125 exch sub lineto - stroke -grestore -gsave - newpath - 227 125 8 3 56 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 232 103 moveto 296 103 lineto 296 135 lineto 232 135 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 264 103 moveto - 264 135 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 279 117 moveto - 0 59 atan dup cos 8 mul 338 exch sub - exch sin 8 mul 117 exch sub lineto - stroke -grestore -gsave - newpath - 338 117 8 3 59 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 289 172 moveto (a different piece of text) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 248 119 moveto - 248 168 lineto - 0 29 atan dup cos 8 mul 277 exch sub - exch sin 8 mul 168 exch sub lineto - stroke -grestore -gsave - newpath - 277 168 8 3 29 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 147 66 moveto (kill-ring-yank-pointer) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 207 76 moveto - 207 114 lineto - 0 18 atan dup cos 8 mul 225 exch sub - exch sin 8 mul 114 exch sub lineto - stroke -grestore -gsave - newpath - 225 114 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 341 98 moveto 405 98 lineto 405 130 lineto 341 130 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 372 98 moveto - 372 130 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 388 115 moveto - 0 48 atan dup cos 8 mul 436 exch sub - exch sin 8 mul 115 exch sub lineto - stroke -grestore -gsave - newpath - 436 115 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 448 121 moveto (nil) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 397 154 moveto (yet more text) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 356 112 moveto - 356 149 lineto - 0 35 atan dup cos 8 mul 391 exch sub - exch sin 8 mul 149 exch sub lineto - stroke -grestore -gsave - newpath - 391 149 8 3 35 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 126 105 moveto 190 105 lineto 190 137 lineto 126 137 lineto - closepath stroke - 1 setmiterlimit -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 206 192 moveto (some text) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 142 120 moveto - 142 187 lineto - 0 48 atan dup cos 8 mul 190 exch sub - exch sin 8 mul 187 exch sub lineto - stroke -grestore -gsave - newpath - 190 187 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 32 66 moveto (kill-ring) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 65 81 moveto - 65 121 lineto - 0 51 atan dup cos 8 mul 116 exch sub - exch sin 8 mul 121 exch sub lineto - stroke -grestore -gsave - newpath - 116 121 8 3 51 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:27:28 1995 diff --git a/doc/lispintro/cons-5.pdf b/doc/lispintro/cons-5.pdf deleted file mode 100644 index b9e713f2dac7aaf285cba703f78e16f1c387eb2e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1511 zcmZuxeNYs27#5wvc9g-1lmM9@C3#4?yZ3!|0VCXTe4oeh6%yUY9xTu;?JjU4B;A-g zh@hy9C7le76gU|}86eEy6!9@QAmM~YNi%TT7-C2R12WKW;ebH*pSykD_j&expWn0V zs}51_#rFvi-_EhJYD5GuKo5JNGcVW5meKmfw9 zG@<(tu~c5r_Lzq-*VajYOQegwxnT0Ws;=4-;`vW*p55YGUCG<{+gxFDL0B$>TZ?S{ zZ|CJTjlN^w!s~2n@ZK~tHT27XbN{W)Q46kBfg=klX(5PDtf}2@3%g4466;EKKUH~c zU?v(jp8GYZs72M>QB^$fs*|g!@5%Yf(70etgPYj(14LM{X}?J%k8@8zN(Zi#d48q8 zQX;CG6B!eKzUbxFo#0=#bK3ZyY(uqfdpsJhRZM$lM!!{IcmHcT`1^r_ zeL_=U`}T$+YeUz;+fCg*XIgg8%3Xrn{+$dT?wG$jFc~yB|0MsY#V62ZbcfS6f&U*K z!JGXgsyAOhX{}d`?{OJQI6eC5{lVkZ)%%Githdgs)ZSJ)aA)sG!J~l74+h5{%X>51 zvaU1g^cxda`**!f_nd#%8$7qQoP5~&<&QPw!#nQZ_RNgew0~~2vVL<5vI!)!zh>O_ z(OH9&HNtrQLU&`(vD>+!yH1a$X0je-wYom)ha{C}=jFpma$DysTOS|mnacY!{Fb2k z*;s-{Z^TiNAo^7KyIOGQdQ7%0T4$&y?bCDptQXQ`)#8?^)cL)c39Nbw%=v9bZ2+#VfmK zGwS4kKBCC6`6UhCt9I=Y7w)Y0shM%UslW>ev(XU|_>YSf7bfmkB#R~ix&xF2BxA75mtjCEOhI6cCd@1laFIk%4Z%=3w1Hq?Sk*LTh$Yx$6vi2# zTEfD@c7=rvjb&kAfozGPq#zsTBsB<(FB%N*p&$de*e^nkp|~e3y#`PWP6ZanVgMRJ z8X1s`a6@a56aW=+I7v>;LB&_74rZ{9)n!p>%Mwe&ul7sU_OA|&pfTzwfCmIPgt;9Y zuck(Va5T-T%HmSXRVgA}Tjg#Y#REEq;B4R~r%8fd91`Ua1dYwnv)mDI8^h-=Z^U0^ zLz|5`27=}(V$~otonlzVK$F=lkm90!7~cJ}7+;J_1wvc` z>rs^P#if-!Ei_?5Fo5F-wsHZnNF)#e6IjNiLTCqf0rN73W1{CUOah~`t`8Fn;Tf&v zVi*o1unrUR;pXcwsSFyw4wJnI6F|?`_lf_. - -/tgifdict 53 dict def -tgifdict begin - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/TGEL % tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/TGMAX - { exch dup 3 1 roll exch dup 3 1 roll gt { pop } { exch pop } ifelse - } def -/TGMIN - { exch dup 3 1 roll exch dup 3 1 roll lt { pop } { exch pop } ifelse - } def -/TGSW { stringwidth pop } def - -/bd { bind def } bind def - -/GS { gsave } bd -/GR { grestore } bd -/NP { newpath } bd -/CP { closepath } bd -/CHP { charpath } bd -/CT { curveto } bd -/L { lineto } bd -/RL { rlineto } bd -/M { moveto } bd -/RM { rmoveto } bd -/S { stroke } bd -/F { fill } bd -/TR { translate } bd -/RO { rotate } bd -/SC { scale } bd -/MU { mul } bd -/DI { div } bd -/DU { dup } bd -/NE { neg } bd -/AD { add } bd -/SU { sub } bd -/PO { pop } bd -/EX { exch } bd -/CO { concat } bd -/CL { clip } bd -/EC { eoclip } bd -/EF { eofill } bd -/IM { image } bd -/IMM { imagemask } bd -/ARY { array } bd -/SG { setgray } bd -/RG { setrgbcolor } bd -/SD { setdash } bd -/W { setlinewidth } bd -/SM { setmiterlimit } bd -/SLC { setlinecap } bd -/SLJ { setlinejoin } bd -/SH { show } bd -/FF { findfont } bd -/MS { makefont setfont } bd -/AR { arcto 4 {pop} repeat } bd -/CURP { currentpoint } bd -/FLAT { flattenpath strokepath clip newpath } bd -/TGSM { tgiforigctm setmatrix } def -/TGRM { savematrix setmatrix } def - -end - -%%EndProlog -%%Page: 1 1 - -%%PageBoundingBox: 34 577 324 778 -tgifdict begin -/tgifsavedpage save def - -1 SM -1 W - -0 SG - -72 0 MU 72 11 MU TR -72 128 DI 100.000 MU 100 DI DU NE SC - -GS - -/tgiforigctm matrix currentmatrix def - -% BOX -0 SG -GS - 10 SM - GS - NP 64 104 M 255 104 L 255 360 L 64 360 L CP - S - GR -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 65 296 M - 254 296 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 63 233 M - 255 233 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 63 169 M - 255 169 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 251 362 M - 251 361 L - 251 379 L - 244 379 L - 229 361 L - TGSM - 1 W - S -GR - -% OVAL -0 SG -GS - GS - NP 160 72 10 6 TGEL - S - GR -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 63 104 M - 128 64 L - 138 69 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 255 103 M - 190 63 L - 180 68 L - TGSM - 1 W - S -GR - -% TEXT -NP -0 SG - GS - 1 W - 160 152 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (symbol name) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (symbol name) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 160 41 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (Chest of Drawers) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (Chest of Drawers) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 41 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (Contents of Drawers) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 160 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (bouquet) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 220 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - ([none]) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 279 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (\(rose violet buttercup\)) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 337 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - ([not described here]) SH - GR - GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 68 362 M - 68 361 L - 68 379 L - 75 379 L - 90 361 L - TGSM - 1 W - S -GR - -% TEXT -NP -0 SG - GS - 1 W - 158 132 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 345 139 M - GS - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (map to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 350 259 M - GS - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (map to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 159 213 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (symbol definition) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (symbol definition) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 159 195 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 160 276 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (variable name) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (variable name) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 158 260 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 160 339 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (property list) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (property list) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 158 323 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -GR -tgifsavedpage restore -end -showpage - -%%Trailer -%MatchingCreationDate: Fri Sep 14 17:40:57 2001 -%%DocumentFonts: NewCenturySchlbk-Roman -%%+ Courier -%%EOF diff --git a/doc/lispintro/drawers.pdf b/doc/lispintro/drawers.pdf deleted file mode 100644 index ca7e0ff1629d4977f6a1cf835e160f22e6bc4075..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3906 zcmb_fc{o&U8!r)!LbfR7Btp@dGh-I<$`X<#W+8@ZjMEs)40DFGP%2s^X(3rcWvwW$ zq|#eN2??Pj3DKK1>QhpE=SYisulM`so4MwibME`O@8{m0^ZOkw$JJK)&>uz66 zI*tV30fDCv&e#~VgZW&MH$X-uG|-CYCxV3lXywNi!K-18zza4p!670c%=X8HB%Pq! zBZ+vql3tg-3-5R3fP1f!`$ZWIi|PYxh546~9zyNY9F~5$d0l>!5s%yQ0_blDyBTU6 z-Yzd5+Tcp+>#S8DXy1Vm&fVemG(ixl+p^dLdf<3Df+p^q=17p zGuRMvUzFOb;~ zFeAJ09$bCY?^3)AKwNIn8I{ZCas}kdTYlOVrtjn)P#+yJgP~ zjx*%mDH@eF$uc(z#+4U^suMzWpOA>*S+23iNWN9>-nB1g4ii}|S5FajKSz5Se7Oa! zkaXF*>Wma!qw?vs(Z=;#`loTM#n&8N<)hiC9d_y+dmFRWX*qBG$jgS8ZgfRumr}9M zulZ|<`l8+~K`eTWN^o7y(bm+~fFwLIqQv)&y_SZB(VXncrE+^xnnO$4`aWr#rUa?U zXcR_voL*bqmJLPy=cvW=g*#T=EWNp?;tM$UPC!lAjNL(`hcMr3a>~#vY%;NVocPBZ z;3h=|KZcgEH2?-3*<2X3hrM`gb3q8e!lP<}A^O8Z9ynAfg!v+Xh>bN4q``TgF3H64?1xy5n0H7_;3jtU-ENmLi13*0lVJ?3%#kQI}hF>i$*dn%{fcwqG z*XVz2MVY$(N7OiQoufSfnV3w*G?B!lXBq{E+0lNunaJv!mWrcdT95|eaS&F+pBMhf z4WtKoim<9l4pD;!-SjC^U=P{gsd!?K5Y?hsBrIl^+mD+TT);8XQ}Rc6JRWG zNnCRQ>bg%X5WTIgS#YHqC!IJlTD2RlimQ_^%ZiYRe_2Unz7-A70D2C|&|RsDH+Phk zeLS-vVeOu!%VU&n&k?el^*5Y9uKP-=n0B!)OZrtpy6fB04<6t1X7-En63LTa7JH1^H) zO2M+SW0b&*}-B#(dozQ#?trJP7@Lo_6=pqnvEQhth9^V<>A^L->rH0 z5i`TdPa@XgY&_FyR&;`6kHMIAT*6p(Scj}wGJflPz0EOqyRDobF)y$CEAQ6X)hwIf zO56B*PVrgsEAn@l7UjsQY!k+4iz?D}j-M>>*RSMy+D4v~qqL2Pcbfw-3A2gfxLEf> ziP$QIzak*HkdBW}J(}t}Uf1SEGZ}$tm(-MEpY*TXSJqPZrRG$g^5tXQb$xo|x0$Z^ zfzP_l^r9oRjQFbwTbGz2r-xGGD(B^oy_kGGwbyN_j`R(MvB`w7CVzHEHmXN#ZxbZ>w@d~wLkE0Y4h7WiL zwJ_T~vPKNvNsY>?{ViH7b0pC(N1@be*kt=OOZQK@g8bp0YdiDnyYv>o5^dVoI=2N` z>=z&I;SQ~knm40j?EEor&Sf2`eCdm$*7=!CtU*@|Vosa_FO?i`$hsj7d=bPJb= zGu?Wwoyx$|lq+L0BdH}LRE>ROo$-{}4q0cx*ZY;Oz*o|wJ>8-q8@F~CdYU?8P5?yxe?j^>_OLh!Q z3;S%W0uG-1kW#0YjzI%Rlt8YhjbeJ3=!$p7V+J>Lok^lB>rr9XY=&eq&U7Xk5 zFcqXbFa@6+jl4HnsW{rX7Wb4qZ%)0s}|5YLLlP!bp{aKKr_|XM?n4!6NVLiopAkXI_-`YX`Jig3+ z=*4_W)*jQ2_A1NxkT+2;hm78JCpm96KT{xN%&n{r4L8qa>Rg!5Dr)p8^1ZNOr9*s@ zL&+^WVT}6wP_6g7U%lv>^~_GJb#AIH9Nd`Z=SxErt#1t0hs0JN?a6no_OLfPRh5{% ztl_~kZwfDXA(f9DkN;CjRylFlaha}``J96X&zcK&`(83nQu{+|-2Fb-38$_@Qy}t_M3bcI zRtyTK!uJFSU=Rb5@YHWei2=@D>XcoP&g0=^SrAPhWkSz@N>Z@V6R9I6_{4NFW3ZCx8wEu*sdQctS*E;msBT zL;`5Xp1g)2GU&qd5_uym9D#xb{V!kKzvwW#|AU@H!pM+;fdN3Gpg;V#9f=S|MX)cG zY6y@~%tv)NY|Yoz24o^Yq#9!EhL19N9-oV*#W&+4yzlo@K>bIlu|iE&`g^s0)N!JC z4s3rI{NL3#N2wXg%=8I(0zf5G0Sb}gfsqC-0vO;xGlYYYG*pQ4D|Wydn8)>=yv4S| zbeJU$v_WYRk7LH?`oU;PLAnU`cLpFLdTGx?5Hz!iegP03EdYo$6eV~%ARpv_0?-Q# z0AWxFBA^K5fo#wpL;~0xSa%`~^o0i|qMp!%f8sqD>zm9UWs6=x99XDhNp}RSy#o@^ah_nJv&_%aHUyejP0e>~h9(7i)B;fIe5S~DWs6+#Zg6i!BUjMB6&elSN@Md&Q zAQBFZfARy6NhBf(*bID=8A9kJVjqD2O-3YQy`Cz=Q%Pv|evwh|zuDsP*!29ej*QOH zuQEe2I(<{u5y*yU!KTWH(C_gPD5T%^KwE^e(W$l&p7;+k?Bq>dM<7$s&U}-Jglx2V zLi8OL0O`DKD03$PAWa}ZDK^$k0JPz6764xfJZQ5TVCl>_D9%W@)Lr^vwn1f|>>> - -@set smallbook -@ifset smallbook -@smallbook -@clear largebook -@end ifset - -@c ================ Included Figures ================ - -@c If you clear this, the figures will be printed as ASCII diagrams -@c rather than PostScript/PDF. -@c (This is not relevant to Info, since Info only handles ASCII.) -@set print-postscript-figures -@c clear print-postscript-figures - -@comment %**end of header - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 - -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@c These refer to the printed book sold by the FSF. -@set edition-number 3.10 -@set update-date 28 October 2009 - -@c For next or subsequent edition: -@c create function using with-output-to-temp-buffer -@c create a major mode, with keymaps -@c run an asynchronous process, like grep or diff - -@c For 8.5 by 11 inch format: do not use such a small amount of -@c whitespace between paragraphs as smallbook format -@ifset largebook -@tex -\global\parskip 6pt plus 1pt -@end tex -@end ifset - -@c For all sized formats: print within-book cross -@c reference with ``...'' rather than [...] - -@c This works with the texinfo.tex file, version 2003-05-04.08, -@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution. - -@tex -\if \xrefprintnodename - \global\def\xrefprintnodename#1{\unskip, ``#1''} - \else - \global\def\xrefprintnodename#1{ ``#1''} -\fi -% \global\def\xrefprintnodename#1{, ``#1''} -@end tex - -@c ---------------------------------------------------- - -@dircategory Emacs lisp -@direntry -* Emacs Lisp Intro: (eintr). A simple introduction to Emacs Lisp programming. -@end direntry - -@copying -This is an @cite{Introduction to Programming in Emacs Lisp}, for -people who are not programmers. -@sp 1 -@iftex -Edition @value{edition-number}, @value{update-date} -@end iftex -@ifnottex -Distributed with Emacs version @value{EMACSVER}. -@end ifnottex -@sp 1 -Copyright @copyright{} 1990--1995, 1997, 2001--2014 Free Software -Foundation, Inc. -@sp 1 - -@iftex -Published by the:@* - -GNU Press, @hfill @uref{http://www.fsf.org/licensing/gnu-press/}@* -a division of the @hfill email: @email{sales@@fsf.org}@* -Free Software Foundation, Inc. @hfill Tel: +1 (617) 542-5942@* -51 Franklin Street, Fifth Floor @hfill Fax: +1 (617) 542-2652@* -Boston, MA 02110-1301 USA -@end iftex - -@ifnottex -Printed copies available from @uref{http://shop.fsf.org/}. Published by: - -@example -GNU Press, http://www.fsf.org/licensing/gnu-press/ -a division of the email: sales@@fsf.org -Free Software Foundation, Inc. Tel: +1 (617) 542-5942 -51 Franklin Street, Fifth Floor Fax: +1 (617) 542-2652 -Boston, MA 02110-1301 USA -@end example -@end ifnottex - -@sp 1 -ISBN 1-882114-43-4 - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; there -being no Invariant Section, with the Front-Cover Texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of -the license is included in the section entitled ``GNU Free -Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@c half title; two lines here, so do not use `shorttitlepage' -@tex -{\begingroup% - \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% - \endgroup}% -{\begingroup\hbox{}\vskip 0.25in \chaprm% - \centerline{Programming in Emacs Lisp}% - \endgroup\page\hbox{}\page} -@end tex - -@titlepage -@sp 6 -@center @titlefont{An Introduction to} -@sp 2 -@center @titlefont{Programming in Emacs Lisp} -@sp 2 -@center Revised Third Edition -@sp 4 -@center by Robert J. Chassell - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@iftex -@headings off -@evenheading @thispage @| @| @thischapter -@oddheading @thissection @| @| @thispage -@end iftex - -@ifnothtml -@c Keep T.O.C. short by tightening up for largebook -@ifset largebook -@tex -\global\parskip 2pt plus 1pt -\global\advance\baselineskip by -1pt -@end tex -@end ifset -@end ifnothtml - -@shortcontents -@contents - -@ifnottex -@node Top -@top An Introduction to Programming in Emacs Lisp - -@ifset WWW_GNU_ORG -@html -

The homepage for GNU Emacs is at -http://www.gnu.org/software/emacs/.
-To view this manual in other formats, click -here. -@end html -@end ifset - -@insertcopying - -This master menu first lists each chapter and index; then it lists -every node in every chapter. -@end ifnottex - -@c >>>> Set pageno appropriately <<<< - -@c The first page of the Preface is a roman numeral; it is the first -@c right handed page after the Table of Contents; hence the following -@c setting must be for an odd negative number. - -@c iftex -@c global@pageno = -11 -@c end iftex - -@set COUNT-WORDS count-words-example -@c Length of variable name chosen so that things still line up when expanded. - -@menu -* Preface:: What to look for. -* List Processing:: What is Lisp? -* Practicing Evaluation:: Running several programs. -* Writing Defuns:: How to write function definitions. -* Buffer Walk Through:: Exploring a few buffer-related functions. -* More Complex:: A few, even more complex functions. -* Narrowing & Widening:: Restricting your and Emacs attention to - a region. -* car cdr & cons:: Fundamental functions in Lisp. -* Cutting & Storing Text:: Removing text and saving it. -* List Implementation:: How lists are implemented in the computer. -* Yanking:: Pasting stored text. -* Loops & Recursion:: How to repeat a process. -* Regexp Search:: Regular expression searches. -* Counting Words:: A review of repetition and regexps. -* Words in a defun:: Counting words in a @code{defun}. -* Readying a Graph:: A prototype graph printing function. -* Emacs Initialization:: How to write a @file{.emacs} file. -* Debugging:: How to run the Emacs Lisp debuggers. -* Conclusion:: Now you have the basics. -* the-the:: An appendix: how to find reduplicated words. -* Kill Ring:: An appendix: how the kill ring works. -* Full Graph:: How to create a graph with labeled axes. -* Free Software and Free Manuals:: -* GNU Free Documentation License:: -* Index:: -* About the Author:: - -@detailmenu - --- The Detailed Node Listing --- - -Preface - -* Why:: Why learn Emacs Lisp? -* On Reading this Text:: Read, gain familiarity, pick up habits.... -* Who You Are:: For whom this is written. -* Lisp History:: -* Note for Novices:: You can read this as a novice. -* Thank You:: - -List Processing - -* Lisp Lists:: What are lists? -* Run a Program:: Any list in Lisp is a program ready to run. -* Making Errors:: Generating an error message. -* Names & Definitions:: Names of symbols and function definitions. -* Lisp Interpreter:: What the Lisp interpreter does. -* Evaluation:: Running a program. -* Variables:: Returning a value from a variable. -* Arguments:: Passing information to a function. -* set & setq:: Setting the value of a variable. -* Summary:: The major points. -* Error Message Exercises:: - -Lisp Lists - -* Numbers Lists:: List have numbers, other lists, in them. -* Lisp Atoms:: Elemental entities. -* Whitespace in Lists:: Formatting lists to be readable. -* Typing Lists:: How GNU Emacs helps you type lists. - -The Lisp Interpreter - -* Complications:: Variables, Special forms, Lists within. -* Byte Compiling:: Specially processing code for speed. - -Evaluation - -* How the Interpreter Acts:: Returns and Side Effects... -* Evaluating Inner Lists:: Lists within lists... - -Variables - -* fill-column Example:: -* Void Function:: The error message for a symbol - without a function. -* Void Variable:: The error message for a symbol without a value. - -Arguments - -* Data types:: Types of data passed to a function. -* Args as Variable or List:: An argument can be the value - of a variable or list. -* Variable Number of Arguments:: Some functions may take a - variable number of arguments. -* Wrong Type of Argument:: Passing an argument of the wrong type - to a function. -* message:: A useful function for sending messages. - -Setting the Value of a Variable - -* Using set:: Setting values. -* Using setq:: Setting a quoted value. -* Counting:: Using @code{setq} to count. - -Practicing Evaluation - -* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} - causes evaluation. -* Buffer Names:: Buffers and files are different. -* Getting Buffers:: Getting a buffer itself, not merely its name. -* Switching Buffers:: How to change to another buffer. -* Buffer Size & Locations:: Where point is located and the size of - the buffer. -* Evaluation Exercise:: - -How To Write Function Definitions - -* Primitive Functions:: -* defun:: The @code{defun} macro. -* Install:: Install a function definition. -* Interactive:: Making a function interactive. -* Interactive Options:: Different options for @code{interactive}. -* Permanent Installation:: Installing code permanently. -* let:: Creating and initializing local variables. -* if:: What if? -* else:: If--then--else expressions. -* Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. -* Review:: -* defun Exercises:: - -Install a Function Definition - -* Effect of installation:: -* Change a defun:: How to change a function definition. - -Make a Function Interactive - -* Interactive multiply-by-seven:: An overview. -* multiply-by-seven in detail:: The interactive version. - -@code{let} - -* Prevent confusion:: -* Parts of let Expression:: -* Sample let Expression:: -* Uninitialized let Variables:: - -The @code{if} Special Form - -* if in more detail:: -* type-of-animal in detail:: An example of an @code{if} expression. - -Truth and Falsehood in Emacs Lisp - -* nil explained:: @code{nil} has two meanings. - -@code{save-excursion} - -* Point and mark:: A review of various locations. -* Template for save-excursion:: - -A Few Buffer--Related Functions - -* Finding More:: How to find more information. -* simplified-beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. -* append-to-buffer:: Uses @code{save-excursion} and - @code{insert-buffer-substring}. -* Buffer Related Review:: Review. -* Buffer Exercises:: - -The Definition of @code{mark-whole-buffer} - -* mark-whole-buffer overview:: -* Body of mark-whole-buffer:: Only three lines of code. - -The Definition of @code{append-to-buffer} - -* append-to-buffer overview:: -* append interactive:: A two part interactive expression. -* append-to-buffer body:: Incorporates a @code{let} expression. -* append save-excursion:: How the @code{save-excursion} works. - -A Few More Complex Functions - -* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. -* insert-buffer:: Read-only, and with @code{or}. -* beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* Second Buffer Related Review:: -* optional Exercise:: - -The Definition of @code{insert-buffer} - -* insert-buffer code:: -* insert-buffer interactive:: When you can read, but not write. -* insert-buffer body:: The body has an @code{or} and a @code{let}. -* if & or:: Using an @code{if} instead of an @code{or}. -* Insert or:: How the @code{or} expression works. -* Insert let:: Two @code{save-excursion} expressions. -* New insert-buffer:: - -The Interactive Expression in @code{insert-buffer} - -* Read-only buffer:: When a buffer cannot be modified. -* b for interactive:: An existing buffer or else its name. - -Complete Definition of @code{beginning-of-buffer} - -* Optional Arguments:: -* beginning-of-buffer opt arg:: Example with optional argument. -* beginning-of-buffer complete:: - -@code{beginning-of-buffer} with an Argument - -* Disentangle beginning-of-buffer:: -* Large buffer case:: -* Small buffer case:: - -Narrowing and Widening - -* Narrowing advantages:: The advantages of narrowing -* save-restriction:: The @code{save-restriction} special form. -* what-line:: The number of the line that point is on. -* narrow Exercise:: - -@code{car}, @code{cdr}, @code{cons}: Fundamental Functions - -* Strange Names:: An historical aside: why the strange names? -* car & cdr:: Functions for extracting part of a list. -* cons:: Constructing a list. -* nthcdr:: Calling @code{cdr} repeatedly. -* nth:: -* setcar:: Changing the first element of a list. -* setcdr:: Changing the rest of a list. -* cons Exercise:: - -@code{cons} - -* Build a list:: -* length:: How to find the length of a list. - -Cutting and Storing Text - -* Storing Text:: Text is stored in a list. -* zap-to-char:: Cutting out text up to a character. -* kill-region:: Cutting text out of a region. -* copy-region-as-kill:: A definition for copying text. -* Digression into C:: Minor note on C programming language macros. -* defvar:: How to give a variable an initial value. -* cons & search-fwd Review:: -* search Exercises:: - -@code{zap-to-char} - -* Complete zap-to-char:: The complete implementation. -* zap-to-char interactive:: A three part interactive expression. -* zap-to-char body:: A short overview. -* search-forward:: How to search for a string. -* progn:: The @code{progn} special form. -* Summing up zap-to-char:: Using @code{point} and @code{search-forward}. - -@code{kill-region} - -* Complete kill-region:: The function definition. -* condition-case:: Dealing with a problem. -* Lisp macro:: - -@code{copy-region-as-kill} - -* Complete copy-region-as-kill:: The complete function definition. -* copy-region-as-kill body:: The body of @code{copy-region-as-kill}. - -The Body of @code{copy-region-as-kill} - -* last-command & this-command:: -* kill-append function:: -* kill-new function:: - -Initializing a Variable with @code{defvar} - -* See variable current value:: -* defvar and asterisk:: - -How Lists are Implemented - -* Lists diagrammed:: -* Symbols as Chest:: Exploring a powerful metaphor. -* List Exercise:: - -Yanking Text Back - -* Kill Ring Overview:: -* kill-ring-yank-pointer:: The kill ring is a list. -* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. - -Loops and Recursion - -* while:: Causing a stretch of code to repeat. -* dolist dotimes:: -* Recursion:: Causing a function to call itself. -* Looping exercise:: - -@code{while} - -* Looping with while:: Repeat so long as test returns true. -* Loop Example:: A @code{while} loop that uses a list. -* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. -* Incrementing Loop:: A loop with an incrementing counter. -* Incrementing Loop Details:: -* Decrementing Loop:: A loop with a decrementing counter. - -Details of an Incrementing Loop - -* Incrementing Example:: Counting pebbles in a triangle. -* Inc Example parts:: The parts of the function definition. -* Inc Example altogether:: Putting the function definition together. - -Loop with a Decrementing Counter - -* Decrementing Example:: More pebbles on the beach. -* Dec Example parts:: The parts of the function definition. -* Dec Example altogether:: Putting the function definition together. - -Save your time: @code{dolist} and @code{dotimes} - -* dolist:: -* dotimes:: - -Recursion - -* Building Robots:: Same model, different serial number ... -* Recursive Definition Parts:: Walk until you stop ... -* Recursion with list:: Using a list as the test whether to recurse. -* Recursive triangle function:: -* Recursion with cond:: -* Recursive Patterns:: Often used templates. -* No Deferment:: Don't store up work ... -* No deferment solution:: - -Recursion in Place of a Counter - -* Recursive Example arg of 1 or 2:: -* Recursive Example arg of 3 or 4:: - -Recursive Patterns - -* Every:: -* Accumulate:: -* Keep:: - -Regular Expression Searches - -* sentence-end:: The regular expression for @code{sentence-end}. -* re-search-forward:: Very similar to @code{search-forward}. -* forward-sentence:: A straightforward example of regexp search. -* forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. -* Regexp Review:: -* re-search Exercises:: - -@code{forward-sentence} - -* Complete forward-sentence:: -* fwd-sentence while loops:: Two @code{while} loops. -* fwd-sentence re-search:: A regular expression search. - -@code{forward-paragraph}: a Goldmine of Functions - -* forward-paragraph in brief:: Key parts of the function definition. -* fwd-para let:: The @code{let*} expression. -* fwd-para while:: The forward motion @code{while} loop. - -Counting: Repetition and Regexps - -* Why Count Words:: -* @value{COUNT-WORDS}:: Use a regexp, but find a problem. -* recursive-count-words:: Start with case of no words in region. -* Counting Exercise:: - -The @code{@value{COUNT-WORDS}} Function - -* Design @value{COUNT-WORDS}:: The definition using a @code{while} loop. -* Whitespace Bug:: The Whitespace Bug in @code{@value{COUNT-WORDS}}. - -Counting Words in a @code{defun} - -* Divide and Conquer:: -* Words and Symbols:: What to count? -* Syntax:: What constitutes a word or symbol? -* count-words-in-defun:: Very like @code{@value{COUNT-WORDS}}. -* Several defuns:: Counting several defuns in a file. -* Find a File:: Do you want to look at a file? -* lengths-list-file:: A list of the lengths of many definitions. -* Several files:: Counting in definitions in different files. -* Several files recursively:: Recursively counting in different files. -* Prepare the data:: Prepare the data for display in a graph. - -Count Words in @code{defuns} in Different Files - -* lengths-list-many-files:: Return a list of the lengths of defuns. -* append:: Attach one list to another. - -Prepare the Data for Display in a Graph - -* Data for Display in Detail:: -* Sorting:: Sorting lists. -* Files List:: Making a list of files. -* Counting function definitions:: - -Readying a Graph - -* Columns of a graph:: -* graph-body-print:: How to print the body of a graph. -* recursive-graph-body-print:: -* Printed Axes:: -* Line Graph Exercise:: - -Your @file{.emacs} File - -* Default Configuration:: -* Site-wide Init:: You can write site-wide init files. -* defcustom:: Emacs will write code for you. -* Beginning init File:: How to write a @file{.emacs} init file. -* Text and Auto-fill:: Automatically wrap lines. -* Mail Aliases:: Use abbreviations for email addresses. -* Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. -* Keymaps:: More about key binding. -* Loading Files:: Load (i.e., evaluate) files automatically. -* Autoload:: Make functions available. -* Simple Extension:: Define a function; bind it to a key. -* X11 Colors:: Colors in X. -* Miscellaneous:: -* Mode Line:: How to customize your mode line. - -Debugging - -* debug:: How to use the built-in debugger. -* debug-on-entry:: Start debugging when you call a function. -* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. -* edebug:: How to use Edebug, a source level debugger. -* Debugging Exercises:: - -Handling the Kill Ring - -* What the Kill Ring Does:: -* current-kill:: -* yank:: Paste a copy of a clipped element. -* yank-pop:: Insert element pointed to. -* ring file:: - -The @code{current-kill} Function - -* Code for current-kill:: -* Understanding current-kill:: - -@code{current-kill} in Outline - -* Body of current-kill:: -* Digression concerning error:: How to mislead humans, but not computers. -* Determining the Element:: - -A Graph with Labeled Axes - -* Labeled Example:: -* print-graph Varlist:: @code{let} expression in @code{print-graph}. -* print-Y-axis:: Print a label for the vertical axis. -* print-X-axis:: Print a horizontal label. -* Print Whole Graph:: The function to print a complete graph. - -The @code{print-Y-axis} Function - -* print-Y-axis in Detail:: -* Height of label:: What height for the Y axis? -* Compute a Remainder:: How to compute the remainder of a division. -* Y Axis Element:: Construct a line for the Y axis. -* Y-axis-column:: Generate a list of Y axis labels. -* print-Y-axis Penultimate:: A not quite final version. - -The @code{print-X-axis} Function - -* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. -* X Axis Tic Marks:: Create tic marks for the horizontal axis. - -Printing the Whole Graph - -* The final version:: A few changes. -* Test print-graph:: Run a short test. -* Graphing words in defuns:: Executing the final code. -* lambda:: How to write an anonymous function. -* mapcar:: Apply a function to elements of a list. -* Another Bug:: Yet another bug @dots{} most insidious. -* Final printed graph:: The graph itself! - -@end detailmenu -@end menu - -@node Preface -@unnumbered Preface - -Most of the GNU Emacs integrated environment is written in the programming -language called Emacs Lisp. The code written in this programming -language is the software---the sets of instructions---that tell the -computer what to do when you give it commands. Emacs is designed so -that you can write new code in Emacs Lisp and easily install it as an -extension to the editor. - -(GNU Emacs is sometimes called an ``extensible editor'', but it does -much more than provide editing capabilities. It is better to refer to -Emacs as an ``extensible computing environment''. However, that -phrase is quite a mouthful. It is easier to refer to Emacs simply as -an editor. Moreover, everything you do in Emacs---find the Mayan date -and phases of the moon, simplify polynomials, debug code, manage -files, read letters, write books---all these activities are kinds of -editing in the most general sense of the word.) - -@menu -* Why:: Why learn Emacs Lisp? -* On Reading this Text:: Read, gain familiarity, pick up habits.... -* Who You Are:: For whom this is written. -* Lisp History:: -* Note for Novices:: You can read this as a novice. -* Thank You:: -@end menu - -@ifnottex -@node Why -@unnumberedsec Why Study Emacs Lisp? -@end ifnottex - -Although Emacs Lisp is usually thought of in association only with Emacs, -it is a full computer programming language. You can use Emacs Lisp as -you would any other programming language. - -Perhaps you want to understand programming; perhaps you want to extend -Emacs; or perhaps you want to become a programmer. This introduction to -Emacs Lisp is designed to get you started: to guide you in learning the -fundamentals of programming, and more importantly, to show you how you -can teach yourself to go further. - -@node On Reading this Text -@unnumberedsec On Reading this Text - -All through this document, you will see little sample programs you can -run inside of Emacs. If you read this document in Info inside of GNU -Emacs, you can run the programs as they appear. (This is easy to do and -is explained when the examples are presented.) Alternatively, you can -read this introduction as a printed book while sitting beside a computer -running Emacs. (This is what I like to do; I like printed books.) If -you don't have a running Emacs beside you, you can still read this book, -but in this case, it is best to treat it as a novel or as a travel guide -to a country not yet visited: interesting, but not the same as being -there. - -Much of this introduction is dedicated to walkthroughs or guided tours -of code used in GNU Emacs. These tours are designed for two purposes: -first, to give you familiarity with real, working code (code you use -every day); and, second, to give you familiarity with the way Emacs -works. It is interesting to see how a working environment is -implemented. -Also, I -hope that you will pick up the habit of browsing through source code. -You can learn from it and mine it for ideas. Having GNU Emacs is like -having a dragon's cave of treasures. - -In addition to learning about Emacs as an editor and Emacs Lisp as a -programming language, the examples and guided tours will give you an -opportunity to get acquainted with Emacs as a Lisp programming -environment. GNU Emacs supports programming and provides tools that -you will want to become comfortable using, such as @kbd{M-.} (the key -which invokes the @code{find-tag} command). You will also learn about -buffers and other objects that are part of the environment. -Learning about these features of Emacs is like learning new routes -around your home town. - -@ignore -In addition, I have written several programs as extended examples. -Although these are examples, the programs are real. I use them. -Other people use them. You may use them. Beyond the fragments of -programs used for illustrations, there is very little in here that is -`just for teaching purposes'; what you see is used. This is a great -advantage of Emacs Lisp: it is easy to learn to use it for work. -@end ignore - -Finally, I hope to convey some of the skills for using Emacs to -learn aspects of programming that you don't know. You can often use -Emacs to help you understand what puzzles you or to find out how to do -something new. This self-reliance is not only a pleasure, but an -advantage. - -@node Who You Are -@unnumberedsec For Whom This is Written - -This text is written as an elementary introduction for people who are -not programmers. If you are a programmer, you may not be satisfied with -this primer. The reason is that you may have become expert at reading -reference manuals and be put off by the way this text is organized. - -An expert programmer who reviewed this text said to me: - -@quotation -@i{I prefer to learn from reference manuals. I ``dive into'' each -paragraph, and ``come up for air'' between paragraphs.} - -@i{When I get to the end of a paragraph, I assume that that subject is -done, finished, that I know everything I need (with the -possible exception of the case when the next paragraph starts talking -about it in more detail). I expect that a well written reference manual -will not have a lot of redundancy, and that it will have excellent -pointers to the (one) place where the information I want is.} -@end quotation - -This introduction is not written for this person! - -Firstly, I try to say everything at least three times: first, to -introduce it; second, to show it in context; and third, to show it in a -different context, or to review it. - -Secondly, I hardly ever put all the information about a subject in one -place, much less in one paragraph. To my way of thinking, that imposes -too heavy a burden on the reader. Instead I try to explain only what -you need to know at the time. (Sometimes I include a little extra -information so you won't be surprised later when the additional -information is formally introduced.) - -When you read this text, you are not expected to learn everything the -first time. Frequently, you need only make, as it were, a `nodding -acquaintance' with some of the items mentioned. My hope is that I have -structured the text and given you enough hints that you will be alert to -what is important, and concentrate on it. - -You will need to ``dive into'' some paragraphs; there is no other way -to read them. But I have tried to keep down the number of such -paragraphs. This book is intended as an approachable hill, rather than -as a daunting mountain. - -This introduction to @cite{Programming in Emacs Lisp} has a companion -document, -@iftex -@cite{The GNU Emacs Lisp Reference Manual}. -@end iftex -@ifnottex -@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU -Emacs Lisp Reference Manual}. -@end ifnottex -The reference manual has more detail than this introduction. In the -reference manual, all the information about one topic is concentrated -in one place. You should turn to it if you are like the programmer -quoted above. And, of course, after you have read this -@cite{Introduction}, you will find the @cite{Reference Manual} useful -when you are writing your own programs. - -@node Lisp History -@unnumberedsec Lisp History -@cindex Lisp history - -Lisp was first developed in the late 1950s at the Massachusetts -Institute of Technology for research in artificial intelligence. The -great power of the Lisp language makes it superior for other purposes as -well, such as writing editor commands and integrated environments. - -@cindex Maclisp -@cindex Common Lisp -GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT -in the 1960s. It is somewhat inspired by Common Lisp, which became a -standard in the 1980s. However, Emacs Lisp is much simpler than Common -Lisp. (The standard Emacs distribution contains an optional extensions -file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) - -@node Note for Novices -@unnumberedsec A Note for Novices - -If you don't know GNU Emacs, you can still read this document -profitably. However, I recommend you learn Emacs, if only to learn to -move around your computer screen. You can teach yourself how to use -Emacs with the built-in tutorial. To use it, type @kbd{C-h t}. (This -means you press and release the @key{CTRL} key and the @kbd{h} at the -same time, and then press and release @kbd{t}.) - -Also, I often refer to one of Emacs's standard commands by listing the -keys which you press to invoke the command and then giving the name of -the command in parentheses, like this: @kbd{M-C-\} -(@code{indent-region}). What this means is that the -@code{indent-region} command is customarily invoked by typing -@kbd{M-C-\}. (You can, if you wish, change the keys that are typed to -invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, , -Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your -@key{META} key, @key{CTRL} key and @key{\} key all at the same time. -(On many modern keyboards the @key{META} key is labeled -@key{ALT}.) -Sometimes a combination like this is called a keychord, since it is -similar to the way you play a chord on a piano. If your keyboard does -not have a @key{META} key, the @key{ESC} key prefix is used in place -of it. In this case, @kbd{M-C-\} means that you press and release your -@key{ESC} key and then type the @key{CTRL} key and the @key{\} key at -the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key -along with the key that is labeled @key{ALT} and, at the same time, -press the @key{\} key. - -In addition to typing a lone keychord, you can prefix what you type -with @kbd{C-u}, which is called the `universal argument'. The -@kbd{C-u} keychord passes an argument to the subsequent command. -Thus, to indent a region of plain text by 6 spaces, mark the region, -and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number, -Emacs either passes the number 4 to the command or otherwise runs the -command differently than it would otherwise.) @xref{Arguments, , -Numeric Arguments, emacs, The GNU Emacs Manual}. - -If you are reading this in Info using GNU Emacs, you can read through -this whole document just by pressing the space bar, @key{SPC}. -(To learn about Info, type @kbd{C-h i} and then select Info.) - -A note on terminology: when I use the word Lisp alone, I often am -referring to the various dialects of Lisp in general, but when I speak -of Emacs Lisp, I am referring to GNU Emacs Lisp in particular. - -@node Thank You -@unnumberedsec Thank You - -My thanks to all who helped me with this book. My especial thanks to -@r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland -McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M. -Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both -@w{Philip Johnson} and @w{David Stampe} for their patient -encouragement. My mistakes are my own. - -@flushright -Robert J. Chassell -@ifnothtml -@email{bob@@gnu.org} -@end ifnothtml -@ifhtml -bob@@gnu.org -@end ifhtml -@end flushright - -@c ================ Beginning of main text ================ - -@c Start main text on right-hand (verso) page - -@tex -\par\vfill\supereject -\headings off -\ifodd\pageno - \par\vfill\supereject -\else - \par\vfill\supereject - \page\hbox{}\page - \par\vfill\supereject -\fi -@end tex - -@c Note: this resetting of the page number back to 1 causes TeX to gripe -@c about already having seen page numbers 1-4 before (in the preface): -@c pdfTeX warning (ext4): destination with the same identifier (name{1}) -@c has been already used, duplicate ignored -@c I guess that is harmless (what happens if a later part of the text -@c makes a link to something in the first 4 pages though?). -@c E.g., note that the Emacs manual has a preface, but does not bother -@c resetting the page numbers back to 1 after that. -@iftex -@headings off -@evenheading @thispage @| @| @thischapter -@oddheading @thissection @| @| @thispage -@global@pageno = 1 -@end iftex - -@node List Processing -@chapter List Processing - -To the untutored eye, Lisp is a strange programming language. In Lisp -code there are parentheses everywhere. Some people even claim that -the name stands for `Lots of Isolated Silly Parentheses'. But the -claim is unwarranted. Lisp stands for LISt Processing, and the -programming language handles @emph{lists} (and lists of lists) by -putting them between parentheses. The parentheses mark the boundaries -of the list. Sometimes a list is preceded by a single apostrophe or -quotation mark, @samp{'}@footnote{The single apostrophe or quotation -mark is an abbreviation for the function @code{quote}; you need not -think about functions now; functions are defined in @ref{Making -Errors, , Generate an Error Message}.} Lists are the basis of Lisp. - -@menu -* Lisp Lists:: What are lists? -* Run a Program:: Any list in Lisp is a program ready to run. -* Making Errors:: Generating an error message. -* Names & Definitions:: Names of symbols and function definitions. -* Lisp Interpreter:: What the Lisp interpreter does. -* Evaluation:: Running a program. -* Variables:: Returning a value from a variable. -* Arguments:: Passing information to a function. -* set & setq:: Setting the value of a variable. -* Summary:: The major points. -* Error Message Exercises:: -@end menu - -@node Lisp Lists -@section Lisp Lists -@cindex Lisp Lists - -In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}. -This list is preceded by a single apostrophe. It could just as well be -written as follows, which looks more like the kind of list you are likely -to be familiar with: - -@smallexample -@group -'(rose - violet - daisy - buttercup) -@end group -@end smallexample - -@noindent -The elements of this list are the names of the four different flowers, -separated from each other by whitespace and surrounded by parentheses, -like flowers in a field with a stone wall around them. -@cindex Flowers in a field - -@menu -* Numbers Lists:: List have numbers, other lists, in them. -* Lisp Atoms:: Elemental entities. -* Whitespace in Lists:: Formatting lists to be readable. -* Typing Lists:: How GNU Emacs helps you type lists. -@end menu - -@ifnottex -@node Numbers Lists -@unnumberedsubsec Numbers, Lists inside of Lists -@end ifnottex - -Lists can also have numbers in them, as in this list: @code{(+ 2 2)}. -This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each -separated by whitespace. - -In Lisp, both data and programs are represented the same way; that is, -they are both lists of words, numbers, or other lists, separated by -whitespace and surrounded by parentheses. (Since a program looks like -data, one program may easily serve as data for another; this is a very -powerful feature of Lisp.) (Incidentally, these two parenthetical -remarks are @emph{not} Lisp lists, because they contain @samp{;} and -@samp{.} as punctuation marks.) - -@need 1200 -Here is another list, this time with a list inside of it: - -@smallexample -'(this list has (a list inside of it)) -@end smallexample - -The components of this list are the words @samp{this}, @samp{list}, -@samp{has}, and the list @samp{(a list inside of it)}. The interior -list is made up of the words @samp{a}, @samp{list}, @samp{inside}, -@samp{of}, @samp{it}. - -@node Lisp Atoms -@subsection Lisp Atoms -@cindex Lisp Atoms - -In Lisp, what we have been calling words are called @dfn{atoms}. This -term comes from the historical meaning of the word atom, which means -`indivisible'. As far as Lisp is concerned, the words we have been -using in the lists cannot be divided into any smaller parts and still -mean the same thing as part of a program; likewise with numbers and -single character symbols like @samp{+}. On the other hand, unlike an -ancient atom, a list can be split into parts. (@xref{car cdr & cons, -, @code{car} @code{cdr} & @code{cons} Fundamental Functions}.) - -In a list, atoms are separated from each other by whitespace. They can be -right next to a parenthesis. - -@cindex @samp{empty list} defined -Technically speaking, a list in Lisp consists of parentheses surrounding -atoms separated by whitespace or surrounding other lists or surrounding -both atoms and other lists. A list can have just one atom in it or -have nothing in it at all. A list with nothing in it looks like this: -@code{()}, and is called the @dfn{empty list}. Unlike anything else, an -empty list is considered both an atom and a list at the same time. - -@cindex Symbolic expressions, introduced -@cindex @samp{expression} defined -@cindex @samp{form} defined -The printed representation of both atoms and lists are called -@dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}. -The word @dfn{expression} by itself can refer to either the printed -representation, or to the atom or list as it is held internally in the -computer. Often, people use the term @dfn{expression} -indiscriminately. (Also, in many texts, the word @dfn{form} is used -as a synonym for expression.) - -Incidentally, the atoms that make up our universe were named such when -they were thought to be indivisible; but it has been found that physical -atoms are not indivisible. Parts can split off an atom or it can -fission into two parts of roughly equal size. Physical atoms were named -prematurely, before their truer nature was found. In Lisp, certain -kinds of atom, such as an array, can be separated into parts; but the -mechanism for doing this is different from the mechanism for splitting a -list. As far as list operations are concerned, the atoms of a list are -unsplittable. - -As in English, the meanings of the component letters of a Lisp atom -are different from the meaning the letters make as a word. For -example, the word for the South American sloth, the @samp{ai}, is -completely different from the two words, @samp{a}, and @samp{i}. - -There are many kinds of atom in nature but only a few in Lisp: for -example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such -as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have -listed in the examples above are all symbols. In everyday Lisp -conversation, the word ``atom'' is not often used, because programmers -usually try to be more specific about what kind of atom they are dealing -with. Lisp programming is mostly about symbols (and sometimes numbers) -within lists. (Incidentally, the preceding three word parenthetical -remark is a proper list in Lisp, since it consists of atoms, which in -this case are symbols, separated by whitespace and enclosed by -parentheses, without any non-Lisp punctuation.) - -@need 1250 -Text between double quotation marks---even sentences or -paragraphs---is also an atom. Here is an example: -@cindex Text between double quotation marks - -@smallexample -'(this list includes "text between quotation marks.") -@end smallexample - -@cindex @samp{string} defined -@noindent -In Lisp, all of the quoted text including the punctuation mark and the -blank spaces is a single atom. This kind of atom is called a -@dfn{string} (for `string of characters') and is the sort of thing that -is used for messages that a computer can print for a human to read. -Strings are a different kind of atom than numbers or symbols and are -used differently. - -@node Whitespace in Lists -@subsection Whitespace in Lists -@cindex Whitespace in lists - -@need 1200 -The amount of whitespace in a list does not matter. From the point of view -of the Lisp language, - -@smallexample -@group -'(this list - looks like this) -@end group -@end smallexample - -@need 800 -@noindent -is exactly the same as this: - -@smallexample -'(this list looks like this) -@end smallexample - -Both examples show what to Lisp is the same list, the list made up of -the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and -@samp{this} in that order. - -Extra whitespace and newlines are designed to make a list more readable -by humans. When Lisp reads the expression, it gets rid of all the extra -whitespace (but it needs to have at least one space between atoms in -order to tell them apart.) - -Odd as it seems, the examples we have seen cover almost all of what Lisp -lists look like! Every other list in Lisp looks more or less like one -of these examples, except that the list may be longer and more complex. -In brief, a list is between parentheses, a string is between quotation -marks, a symbol looks like a word, and a number looks like a number. -(For certain situations, square brackets, dots and a few other special -characters may be used; however, we will go quite far without them.) - -@node Typing Lists -@subsection GNU Emacs Helps You Type Lists -@cindex Help typing lists -@cindex Formatting help - -When you type a Lisp expression in GNU Emacs using either Lisp -Interaction mode or Emacs Lisp mode, you have available to you several -commands to format the Lisp expression so it is easy to read. For -example, pressing the @key{TAB} key automatically indents the line the -cursor is on by the right amount. A command to properly indent the -code in a region is customarily bound to @kbd{M-C-\}. Indentation is -designed so that you can see which elements of a list belong to which -list---elements of a sub-list are indented more than the elements of -the enclosing list. - -In addition, when you type a closing parenthesis, Emacs momentarily -jumps the cursor back to the matching opening parenthesis, so you can -see which one it is. This is very useful, since every list you type -in Lisp must have its closing parenthesis match its opening -parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs -Manual}, for more information about Emacs's modes.) - -@node Run a Program -@section Run a Program -@cindex Run a program -@cindex Program, running one - -@cindex @samp{evaluate} defined -A list in Lisp---any list---is a program ready to run. If you run it -(for which the Lisp jargon is @dfn{evaluate}), the computer will do one -of three things: do nothing except return to you the list itself; send -you an error message; or, treat the first symbol in the list as a -command to do something. (Usually, of course, it is the last of these -three things that you really want!) - -@c use code for the single apostrophe, not samp. -The single apostrophe, @code{'}, that I put in front of some of the -example lists in preceding sections is called a @dfn{quote}; when it -precedes a list, it tells Lisp to do nothing with the list, other than -take it as it is written. But if there is no quote preceding a list, -the first item of the list is special: it is a command for the computer -to obey. (In Lisp, these commands are called @emph{functions}.) The list -@code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp -understands that the @code{+} is an instruction to do something with the -rest of the list: add the numbers that follow. - -@need 1250 -If you are reading this inside of GNU Emacs in Info, here is how you can -evaluate such a list: place your cursor immediately after the right -hand parenthesis of the following list and then type @kbd{C-x C-e}: - -@smallexample -(+ 2 2) -@end smallexample - -@c use code for the number four, not samp. -@noindent -You will see the number @code{4} appear in the echo area. (In the -jargon, what you have just done is ``evaluate the list.'' The echo area -is the line at the bottom of the screen that displays or ``echoes'' -text.) Now try the same thing with a quoted list: place the cursor -right after the following list and type @kbd{C-x C-e}: - -@smallexample -'(this is a quoted list) -@end smallexample - -@noindent -You will see @code{(this is a quoted list)} appear in the echo area. - -@cindex Lisp interpreter, explained -@cindex Interpreter, Lisp, explained -In both cases, what you are doing is giving a command to the program -inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the -interpreter a command to evaluate the expression. The name of the Lisp -interpreter comes from the word for the task done by a human who comes -up with the meaning of an expression---who ``interprets'' it. - -You can also evaluate an atom that is not part of a list---one that is -not surrounded by parentheses; again, the Lisp interpreter translates -from the humanly readable expression to the language of the computer. -But before discussing this (@pxref{Variables}), we will discuss what the -Lisp interpreter does when you make an error. - -@node Making Errors -@section Generate an Error Message -@cindex Generate an error message -@cindex Error message generation - -Partly so you won't worry if you do it accidentally, we will now give -a command to the Lisp interpreter that generates an error message. -This is a harmless activity; and indeed, we will often try to generate -error messages intentionally. Once you understand the jargon, error -messages can be informative. Instead of being called ``error'' -messages, they should be called ``help'' messages. They are like -signposts to a traveler in a strange country; deciphering them can be -hard, but once understood, they can point the way. - -The error message is generated by a built-in GNU Emacs debugger. We -will `enter the debugger'. You get out of the debugger by typing @code{q}. - -What we will do is evaluate a list that is not quoted and does not -have a meaningful command as its first element. Here is a list almost -exactly the same as the one we just used, but without the single-quote -in front of it. Position the cursor right after it and type @kbd{C-x -C-e}: - -@smallexample -(this is an unquoted list) -@end smallexample - -@ignore -@noindent -What you see depends on which version of Emacs you are running. GNU -Emacs version 22 provides more information than version 20 and before. -First, the more recent result of generating an error; then the -earlier, version 20 result. - -@need 1250 -@noindent -In GNU Emacs version 22, a @file{*Backtrace*} window will open up and -you will see the following in it: -@end ignore - -A @file{*Backtrace*} window will open up and you should see the -following in it: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function this) - (this is an unquoted list) - eval((this is an unquoted list)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1200 -@noindent -Your cursor will be in this window (you may have to wait a few seconds -before it becomes visible). To quit the debugger and make the -debugger window go away, type: - -@smallexample -q -@end smallexample - -@noindent -Please type @kbd{q} right now, so you become confident that you can -get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter -it. - -@cindex @samp{function} defined -Based on what we already know, we can almost read this error message. - -You read the @file{*Backtrace*} buffer from the bottom up; it tells -you what Emacs did. When you typed @kbd{C-x C-e}, you made an -interactive call to the command @code{eval-last-sexp}. @code{eval} is -an abbreviation for `evaluate' and @code{sexp} is an abbreviation for -`symbolic expression'. The command means `evaluate last symbolic -expression', which is the expression just before your cursor. - -Each line above tells you what the Lisp interpreter evaluated next. -The most recent action is at the top. The buffer is called the -@file{*Backtrace*} buffer because it enables you to track Emacs -backwards. - -@need 800 -At the top of the @file{*Backtrace*} buffer, you see the line: - -@smallexample -Debugger entered--Lisp error: (void-function this) -@end smallexample - -@noindent -The Lisp interpreter tried to evaluate the first atom of the list, the -word @samp{this}. It is this action that generated the error message -@samp{void-function this}. - -The message contains the words @samp{void-function} and @samp{this}. - -@cindex @samp{function} defined -The word @samp{function} was mentioned once before. It is a very -important word. For our purposes, we can define it by saying that a -@dfn{function} is a set of instructions to the computer that tell the -computer to do something. - -Now we can begin to understand the error message: @samp{void-function -this}. The function (that is, the word @samp{this}) does not have a -definition of any set of instructions for the computer to carry out. - -The slightly odd word, @samp{void-function}, is designed to cover the -way Emacs Lisp is implemented, which is that when a symbol does not -have a function definition attached to it, the place that should -contain the instructions is `void'. - -On the other hand, since we were able to add 2 plus 2 successfully, by -evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must -have a set of instructions for the computer to obey and those -instructions must be to add the numbers that follow the @code{+}. - -It is possible to prevent Emacs entering the debugger in cases like -this. We do not explain how to do that here, but we will mention what -the result looks like, because you may encounter a similar situation -if there is a bug in some Emacs code that you are using. In such -cases, you will see only one line of error message; it will appear in -the echo area and look like this: - -@smallexample -Symbol's function definition is void:@: this -@end smallexample - -@noindent -@ignore -(Also, your terminal may beep at you---some do, some don't; and others -blink. This is just a device to get your attention.) -@end ignore -The message goes away as soon as you type a key, even just to -move the cursor. - -We know the meaning of the word @samp{Symbol}. It refers to the first -atom of the list, the word @samp{this}. The word @samp{function} -refers to the instructions that tell the computer what to do. -(Technically, the symbol tells the computer where to find the -instructions, but this is a complication we can ignore for the -moment.) - -The error message can be understood: @samp{Symbol's function -definition is void:@: this}. The symbol (that is, the word -@samp{this}) lacks instructions for the computer to carry out. - -@node Names & Definitions -@section Symbol Names and Function Definitions -@cindex Symbol names - -We can articulate another characteristic of Lisp based on what we have -discussed so far---an important characteristic: a symbol, like -@code{+}, is not itself the set of instructions for the computer to -carry out. Instead, the symbol is used, perhaps temporarily, as a way -of locating the definition or set of instructions. What we see is the -name through which the instructions can be found. Names of people -work the same way. I can be referred to as @samp{Bob}; however, I am -not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the -consciousness consistently associated with a particular life-form. -The name is not me, but it can be used to refer to me. - -In Lisp, one set of instructions can be attached to several names. -For example, the computer instructions for adding numbers can be -linked to the symbol @code{plus} as well as to the symbol @code{+} -(and are in some dialects of Lisp). Among humans, I can be referred -to as @samp{Robert} as well as @samp{Bob} and by other words as well. - -On the other hand, a symbol can have only one function definition -attached to it at a time. Otherwise, the computer would be confused as -to which definition to use. If this were the case among people, only -one person in the world could be named @samp{Bob}. However, the function -definition to which the name refers can be changed readily. -(@xref{Install, , Install a Function Definition}.) - -Since Emacs Lisp is large, it is customary to name symbols in a way -that identifies the part of Emacs to which the function belongs. -Thus, all the names for functions that deal with Texinfo start with -@samp{texinfo-} and those for functions that deal with reading mail -start with @samp{rmail-}. - -@node Lisp Interpreter -@section The Lisp Interpreter -@cindex Lisp interpreter, what it does -@cindex Interpreter, what it does - -Based on what we have seen, we can now start to figure out what the -Lisp interpreter does when we command it to evaluate a list. -First, it looks to see whether there is a quote before the list; if -there is, the interpreter just gives us the list. On the other -hand, if there is no quote, the interpreter looks at the first element -in the list and sees whether it has a function definition. If it does, -the interpreter carries out the instructions in the function definition. -Otherwise, the interpreter prints an error message. - -This is how Lisp works. Simple. There are added complications which we -will get to in a minute, but these are the fundamentals. Of course, to -write Lisp programs, you need to know how to write function definitions -and attach them to names, and how to do this without confusing either -yourself or the computer. - -@menu -* Complications:: Variables, Special forms, Lists within. -* Byte Compiling:: Specially processing code for speed. -@end menu - -@ifnottex -@node Complications -@unnumberedsubsec Complications -@end ifnottex - -Now, for the first complication. In addition to lists, the Lisp -interpreter can evaluate a symbol that is not quoted and does not have -parentheses around it. The Lisp interpreter will attempt to determine -the symbol's value as a @dfn{variable}. This situation is described -in the section on variables. (@xref{Variables}.) - -@cindex Special form -The second complication occurs because some functions are unusual and -do not work in the usual manner. Those that don't are called -@dfn{special forms}. They are used for special jobs, like defining a -function, and there are not many of them. In the next few chapters, -you will be introduced to several of the more important special forms. - -As well as special forms, there are also @dfn{macros}. A macro -is a construct defined in Lisp, which differs from a function in that it -translates a Lisp expression into another expression that is to be -evaluated in place of the original expression. (@xref{Lisp macro}.) - -For the purposes of this introduction, you do not need to worry too much -about whether something is a special form, macro, or ordinary function. -For example, @code{if} is a special form (@pxref{if}), but @code{when} -is a macro (@pxref{Lisp macro}). In earlier versions of Emacs, -@code{defun} was a special form, but now it is a macro (@pxref{defun}). -It still behaves in the same way. - -The final complication is this: if the function that the -Lisp interpreter is looking at is not a special form, and if it is part -of a list, the Lisp interpreter looks to see whether the list has a list -inside of it. If there is an inner list, the Lisp interpreter first -figures out what it should do with the inside list, and then it works on -the outside list. If there is yet another list embedded inside the -inner list, it works on that one first, and so on. It always works on -the innermost list first. The interpreter works on the innermost list -first, to evaluate the result of that list. The result may be -used by the enclosing expression. - -Otherwise, the interpreter works left to right, from one expression to -the next. - -@node Byte Compiling -@subsection Byte Compiling -@cindex Byte compiling - -One other aspect of interpreting: the Lisp interpreter is able to -interpret two kinds of entity: humanly readable code, on which we will -focus exclusively, and specially processed code, called @dfn{byte -compiled} code, which is not humanly readable. Byte compiled code -runs faster than humanly readable code. - -You can transform humanly readable code into byte compiled code by -running one of the compile commands such as @code{byte-compile-file}. -Byte compiled code is usually stored in a file that ends with a -@file{.elc} extension rather than a @file{.el} extension. You will -see both kinds of file in the @file{emacs/lisp} directory; the files -to read are those with @file{.el} extensions. - -As a practical matter, for most things you might do to customize or -extend Emacs, you do not need to byte compile; and I will not discuss -the topic here. @xref{Byte Compilation, , Byte Compilation, elisp, -The GNU Emacs Lisp Reference Manual}, for a full description of byte -compilation. - -@node Evaluation -@section Evaluation -@cindex Evaluation - -When the Lisp interpreter works on an expression, the term for the -activity is called @dfn{evaluation}. We say that the interpreter -`evaluates the expression'. I've used this term several times before. -The word comes from its use in everyday language, `to ascertain the -value or amount of; to appraise', according to @cite{Webster's New -Collegiate Dictionary}. - -@menu -* How the Interpreter Acts:: Returns and Side Effects... -* Evaluating Inner Lists:: Lists within lists... -@end menu - -@ifnottex -@node How the Interpreter Acts -@unnumberedsubsec How the Lisp Interpreter Acts -@end ifnottex - -@cindex @samp{returned value} explained -After evaluating an expression, the Lisp interpreter will most likely -@dfn{return} the value that the computer produces by carrying out the -instructions it found in the function definition, or perhaps it will -give up on that function and produce an error message. (The interpreter -may also find itself tossed, so to speak, to a different function or it -may attempt to repeat continually what it is doing for ever and ever in -what is called an `infinite loop'. These actions are less common; and -we can ignore them.) Most frequently, the interpreter returns a value. - -@cindex @samp{side effect} defined -At the same time the interpreter returns a value, it may do something -else as well, such as move a cursor or copy a file; this other kind of -action is called a @dfn{side effect}. Actions that we humans think are -important, such as printing results, are often ``side effects'' to the -Lisp interpreter. The jargon can sound peculiar, but it turns out that -it is fairly easy to learn to use side effects. - -In summary, evaluating a symbolic expression most commonly causes the -Lisp interpreter to return a value and perhaps carry out a side effect; -or else produce an error. - -@node Evaluating Inner Lists -@subsection Evaluating Inner Lists -@cindex Inner list evaluation -@cindex Evaluating inner lists - -If evaluation applies to a list that is inside another list, the outer -list may use the value returned by the first evaluation as information -when the outer list is evaluated. This explains why inner expressions -are evaluated first: the values they return are used by the outer -expressions. - -@need 1250 -We can investigate this process by evaluating another addition example. -Place your cursor after the following expression and type @kbd{C-x C-e}: - -@smallexample -(+ 2 (+ 3 3)) -@end smallexample - -@noindent -The number 8 will appear in the echo area. - -What happens is that the Lisp interpreter first evaluates the inner -expression, @code{(+ 3 3)}, for which the value 6 is returned; then it -evaluates the outer expression as if it were written @code{(+ 2 6)}, which -returns the value 8. Since there are no more enclosing expressions to -evaluate, the interpreter prints that value in the echo area. - -Now it is easy to understand the name of the command invoked by the -keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The -letters @code{sexp} are an abbreviation for `symbolic expression', and -@code{eval} is an abbreviation for `evaluate'. The command means -`evaluate last symbolic expression'. - -As an experiment, you can try evaluating the expression by putting the -cursor at the beginning of the next line immediately following the -expression, or inside the expression. - -@need 800 -Here is another copy of the expression: - -@smallexample -(+ 2 (+ 3 3)) -@end smallexample - -@noindent -If you place the cursor at the beginning of the blank line that -immediately follows the expression and type @kbd{C-x C-e}, you will -still get the value 8 printed in the echo area. Now try putting the -cursor inside the expression. If you put it right after the next to -last parenthesis (so it appears to sit on top of the last parenthesis), -you will get a 6 printed in the echo area! This is because the command -evaluates the expression @code{(+ 3 3)}. - -Now put the cursor immediately after a number. Type @kbd{C-x C-e} and -you will get the number itself. In Lisp, if you evaluate a number, you -get the number itself---this is how numbers differ from symbols. If you -evaluate a list starting with a symbol like @code{+}, you will get a -value returned that is the result of the computer carrying out the -instructions in the function definition attached to that name. If a -symbol by itself is evaluated, something different happens, as we will -see in the next section. - -@node Variables -@section Variables -@cindex Variables - -In Emacs Lisp, a symbol can have a value attached to it just as it can -have a function definition attached to it. The two are different. -The function definition is a set of instructions that a computer will -obey. A value, on the other hand, is something, such as number or a -name, that can vary (which is why such a symbol is called a variable). -The value of a symbol can be any expression in Lisp, such as a symbol, -number, list, or string. A symbol that has a value is often called a -@dfn{variable}. - -A symbol can have both a function definition and a value attached to -it at the same time. Or it can have just one or the other. -The two are separate. This is somewhat similar -to the way the name Cambridge can refer to the city in Massachusetts -and have some information attached to the name as well, such as -``great programming center''. - -@ignore -(Incidentally, in Emacs Lisp, a symbol can have two -other things attached to it, too: a property list and a documentation -string; these are discussed later.) -@end ignore - -Another way to think about this is to imagine a symbol as being a chest -of drawers. The function definition is put in one drawer, the value in -another, and so on. What is put in the drawer holding the value can be -changed without affecting the contents of the drawer holding the -function definition, and vice versa. - -@menu -* fill-column Example:: -* Void Function:: The error message for a symbol - without a function. -* Void Variable:: The error message for a symbol without a value. -@end menu - -@ifnottex -@node fill-column Example -@unnumberedsubsec @code{fill-column}, an Example Variable -@end ifnottex - -@findex fill-column, @r{an example variable} -@cindex Example variable, @code{fill-column} -@cindex Variable, example of, @code{fill-column} -The variable @code{fill-column} illustrates a symbol with a value -attached to it: in every GNU Emacs buffer, this symbol is set to some -value, usually 72 or 70, but sometimes to some other value. To find the -value of this symbol, evaluate it by itself. If you are reading this in -Info inside of GNU Emacs, you can do this by putting the cursor after -the symbol and typing @kbd{C-x C-e}: - -@smallexample -fill-column -@end smallexample - -@noindent -After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo -area. This is the value for which @code{fill-column} is set for me as I -write this. It may be different for you in your Info buffer. Notice -that the value returned as a variable is printed in exactly the same way -as the value returned by a function carrying out its instructions. From -the point of view of the Lisp interpreter, a value returned is a value -returned. What kind of expression it came from ceases to matter once -the value is known. - -A symbol can have any value attached to it or, to use the jargon, we can -@dfn{bind} the variable to a value: to a number, such as 72; to a -string, @code{"such as this"}; to a list, such as @code{(spruce pine -oak)}; we can even bind a variable to a function definition. - -A symbol can be bound to a value in several ways. @xref{set & setq, , -Setting the Value of a Variable}, for information about one way to do -this. - -@node Void Function -@subsection Error Message for a Symbol Without a Function -@cindex Symbol without function error -@cindex Error for symbol without function - -When we evaluated @code{fill-column} to find its value as a variable, -we did not place parentheses around the word. This is because we did -not intend to use it as a function name. - -If @code{fill-column} were the first or only element of a list, the -Lisp interpreter would attempt to find the function definition -attached to it. But @code{fill-column} has no function definition. -Try evaluating this: - -@smallexample -(fill-column) -@end smallexample - -@need 1250 -@noindent -You will create a @file{*Backtrace*} buffer that says: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function fill-column) - (fill-column) - eval((fill-column)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(Remember, to quit the debugger and make the debugger window go away, -type @kbd{q} in the @file{*Backtrace*} buffer.) - -@ignore -@need 800 -In GNU Emacs 20 and before, you will produce an error message that says: - -@smallexample -Symbol's function definition is void:@: fill-column -@end smallexample - -@noindent -(The message will go away as soon as you move the cursor or type -another key.) -@end ignore - -@node Void Variable -@subsection Error Message for a Symbol Without a Value -@cindex Symbol without value error -@cindex Error for symbol without value - -If you attempt to evaluate a symbol that does not have a value bound to -it, you will receive an error message. You can see this by -experimenting with our 2 plus 2 addition. In the following expression, -put your cursor right after the @code{+}, before the first number 2, -type @kbd{C-x C-e}: - -@smallexample -(+ 2 2) -@end smallexample - -@need 1500 -@noindent -In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that -says: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-variable +) - eval(+) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(Again, you can quit the debugger by -typing @kbd{q} in the @file{*Backtrace*} buffer.) - -This backtrace is different from the very first error message we saw, -which said, @samp{Debugger entered--Lisp error: (void-function this)}. -In this case, the function does not have a value as a variable; while -in the other error message, the function (the word `this') did not -have a definition. - -In this experiment with the @code{+}, what we did was cause the Lisp -interpreter to evaluate the @code{+} and look for the value of the -variable instead of the function definition. We did this by placing the -cursor right after the symbol rather than after the parenthesis of the -enclosing list as we did before. As a consequence, the Lisp interpreter -evaluated the preceding s-expression, which in this case was -@code{+} by itself. - -Since @code{+} does not have a value bound to it, just the function -definition, the error message reported that the symbol's value as a -variable was void. - -@ignore -@need 800 -In GNU Emacs version 20 and before, your error message will say: - -@example -Symbol's value as variable is void:@: + -@end example - -@noindent -The meaning is the same as in GNU Emacs 22. -@end ignore - -@node Arguments -@section Arguments -@cindex Arguments -@cindex Passing information to functions - -To see how information is passed to functions, let's look again at -our old standby, the addition of two plus two. In Lisp, this is written -as follows: - -@smallexample -(+ 2 2) -@end smallexample - -If you evaluate this expression, the number 4 will appear in your echo -area. What the Lisp interpreter does is add the numbers that follow -the @code{+}. - -@cindex @samp{argument} defined -The numbers added by @code{+} are called the @dfn{arguments} of the -function @code{+}. These numbers are the information that is given to -or @dfn{passed} to the function. - -The word `argument' comes from the way it is used in mathematics and -does not refer to a disputation between two people; instead it refers to -the information presented to the function, in this case, to the -@code{+}. In Lisp, the arguments to a function are the atoms or lists -that follow the function. The values returned by the evaluation of -these atoms or lists are passed to the function. Different functions -require different numbers of arguments; some functions require none at -all.@footnote{It is curious to track the path by which the word `argument' -came to have two different meanings, one in mathematics and the other in -everyday English. According to the @cite{Oxford English Dictionary}, -the word derives from the Latin for @samp{to make clear, prove}; thus it -came to mean, by one thread of derivation, `the evidence offered as -proof', which is to say, `the information offered', which led to its -meaning in Lisp. But in the other thread of derivation, it came to mean -`to assert in a manner against which others may make counter -assertions', which led to the meaning of the word as a disputation. -(Note here that the English word has two different definitions attached -to it at the same time. By contrast, in Emacs Lisp, a symbol cannot -have two different function definitions at the same time.)} - -@menu -* Data types:: Types of data passed to a function. -* Args as Variable or List:: An argument can be the value - of a variable or list. -* Variable Number of Arguments:: Some functions may take a - variable number of arguments. -* Wrong Type of Argument:: Passing an argument of the wrong type - to a function. -* message:: A useful function for sending messages. -@end menu - -@node Data types -@subsection Arguments' Data Types -@cindex Data types -@cindex Types of data -@cindex Arguments' data types - -The type of data that should be passed to a function depends on what -kind of information it uses. The arguments to a function such as -@code{+} must have values that are numbers, since @code{+} adds numbers. -Other functions use different kinds of data for their arguments. - -@need 1250 -@findex concat -For example, the @code{concat} function links together or unites two or -more strings of text to produce a string. The arguments are strings. -Concatenating the two character strings @code{abc}, @code{def} produces -the single string @code{abcdef}. This can be seen by evaluating the -following: - -@smallexample -(concat "abc" "def") -@end smallexample - -@noindent -The value produced by evaluating this expression is @code{"abcdef"}. - -A function such as @code{substring} uses both a string and numbers as -arguments. The function returns a part of the string, a substring of -the first argument. This function takes three arguments. Its first -argument is the string of characters, the second and third arguments are -numbers that indicate the beginning and end of the substring. The -numbers are a count of the number of characters (including spaces and -punctuation) from the beginning of the string. - -@need 800 -For example, if you evaluate the following: - -@smallexample -(substring "The quick brown fox jumped." 16 19) -@end smallexample - -@noindent -you will see @code{"fox"} appear in the echo area. The arguments are the -string and the two numbers. - -Note that the string passed to @code{substring} is a single atom even -though it is made up of several words separated by spaces. Lisp counts -everything between the two quotation marks as part of the string, -including the spaces. You can think of the @code{substring} function as -a kind of `atom smasher' since it takes an otherwise indivisible atom -and extracts a part. However, @code{substring} is only able to extract -a substring from an argument that is a string, not from another type of -atom such as a number or symbol. - -@node Args as Variable or List -@subsection An Argument as the Value of a Variable or List - -An argument can be a symbol that returns a value when it is evaluated. -For example, when the symbol @code{fill-column} by itself is evaluated, -it returns a number. This number can be used in an addition. - -@need 1250 -Position the cursor after the following expression and type @kbd{C-x -C-e}: - -@smallexample -(+ 2 fill-column) -@end smallexample - -@noindent -The value will be a number two more than what you get by evaluating -@code{fill-column} alone. For me, this is 74, because my value of -@code{fill-column} is 72. - -As we have just seen, an argument can be a symbol that returns a value -when evaluated. In addition, an argument can be a list that returns a -value when it is evaluated. For example, in the following expression, -the arguments to the function @code{concat} are the strings -@w{@code{"The "}} and @w{@code{" red foxes."}} and the list -@code{(number-to-string (+ 2 fill-column))}. - -@c For GNU Emacs 22, need number-to-string -@smallexample -(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") -@end smallexample - -@noindent -If you evaluate this expression---and if, as with my Emacs, -@code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will -appear in the echo area. (Note that you must put spaces after the -word @samp{The} and before the word @samp{red} so they will appear in -the final string. The function @code{number-to-string} converts the -integer that the addition function returns to a string. -@code{number-to-string} is also known as @code{int-to-string}.) - -@node Variable Number of Arguments -@subsection Variable Number of Arguments -@cindex Variable number of arguments -@cindex Arguments, variable number of - -Some functions, such as @code{concat}, @code{+} or @code{*}, take any -number of arguments. (The @code{*} is the symbol for multiplication.) -This can be seen by evaluating each of the following expressions in -the usual way. What you will see in the echo area is printed in this -text after @samp{@result{}}, which you may read as `evaluates to'. - -@need 1250 -In the first set, the functions have no arguments: - -@smallexample -@group -(+) @result{} 0 - -(*) @result{} 1 -@end group -@end smallexample - -@need 1250 -In this set, the functions have one argument each: - -@smallexample -@group -(+ 3) @result{} 3 - -(* 3) @result{} 3 -@end group -@end smallexample - -@need 1250 -In this set, the functions have three arguments each: - -@smallexample -@group -(+ 3 4 5) @result{} 12 - -(* 3 4 5) @result{} 60 -@end group -@end smallexample - -@node Wrong Type of Argument -@subsection Using the Wrong Type Object as an Argument -@cindex Wrong type of argument -@cindex Argument, wrong type of - -When a function is passed an argument of the wrong type, the Lisp -interpreter produces an error message. For example, the @code{+} -function expects the values of its arguments to be numbers. As an -experiment we can pass it the quoted symbol @code{hello} instead of a -number. Position the cursor after the following expression and type -@kbd{C-x C-e}: - -@smallexample -(+ 2 'hello) -@end smallexample - -@noindent -When you do this you will generate an error message. What has happened -is that @code{+} has tried to add the 2 to the value returned by -@code{'hello}, but the value returned by @code{'hello} is the symbol -@code{hello}, not a number. Only numbers can be added. So @code{+} -could not carry out its addition. - -@need 1250 -You will create and enter a @file{*Backtrace*} buffer that says: - -@noindent -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: - (wrong-type-argument number-or-marker-p hello) - +(2 hello) - eval((+ 2 (quote hello))) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1250 -As usual, the error message tries to be helpful and makes sense after you -learn how to read it.@footnote{@code{(quote hello)} is an expansion of -the abbreviation @code{'hello}.} - -The first part of the error message is straightforward; it says -@samp{wrong type argument}. Next comes the mysterious jargon word -@w{@samp{number-or-marker-p}}. This word is trying to tell you what -kind of argument the @code{+} expected. - -The symbol @code{number-or-marker-p} says that the Lisp interpreter is -trying to determine whether the information presented it (the value of -the argument) is a number or a marker (a special object representing a -buffer position). What it does is test to see whether the @code{+} is -being given numbers to add. It also tests to see whether the -argument is something called a marker, which is a specific feature of -Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. -When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command, -its position is kept as a marker. The mark can be considered a -number---the number of characters the location is from the beginning -of the buffer.) In Emacs Lisp, @code{+} can be used to add the -numeric value of marker positions as numbers. - -The @samp{p} of @code{number-or-marker-p} is the embodiment of a -practice started in the early days of Lisp programming. The @samp{p} -stands for `predicate'. In the jargon used by the early Lisp -researchers, a predicate refers to a function to determine whether some -property is true or false. So the @samp{p} tells us that -@code{number-or-marker-p} is the name of a function that determines -whether it is true or false that the argument supplied is a number or -a marker. Other Lisp symbols that end in @samp{p} include @code{zerop}, -a function that tests whether its argument has the value of zero, and -@code{listp}, a function that tests whether its argument is a list. - -Finally, the last part of the error message is the symbol @code{hello}. -This is the value of the argument that was passed to @code{+}. If the -addition had been passed the correct type of object, the value passed -would have been a number, such as 37, rather than a symbol like -@code{hello}. But then you would not have got the error message. - -@ignore -@need 1250 -In GNU Emacs version 20 and before, the echo area displays an error -message that says: - -@smallexample -Wrong type argument:@: number-or-marker-p, hello -@end smallexample - -This says, in different words, the same as the top line of the -@file{*Backtrace*} buffer. -@end ignore - -@node message -@subsection The @code{message} Function -@findex message - -Like @code{+}, the @code{message} function takes a variable number of -arguments. It is used to send messages to the user and is so useful -that we will describe it here. - -@need 1250 -A message is printed in the echo area. For example, you can print a -message in your echo area by evaluating the following list: - -@smallexample -(message "This message appears in the echo area!") -@end smallexample - -The whole string between double quotation marks is a single argument -and is printed @i{in toto}. (Note that in this example, the message -itself will appear in the echo area within double quotes; that is -because you see the value returned by the @code{message} function. In -most uses of @code{message} in programs that you write, the text will -be printed in the echo area as a side-effect, without the quotes. -@xref{multiply-by-seven in detail, , @code{multiply-by-seven} in -detail}, for an example of this.) - -However, if there is a @samp{%s} in the quoted string of characters, the -@code{message} function does not print the @samp{%s} as such, but looks -to the argument that follows the string. It evaluates the second -argument and prints the value at the location in the string where the -@samp{%s} is. - -@need 1250 -You can see this by positioning the cursor after the following -expression and typing @kbd{C-x C-e}: - -@smallexample -(message "The name of this buffer is: %s." (buffer-name)) -@end smallexample - -@noindent -In Info, @code{"The name of this buffer is: *info*."} will appear in the -echo area. The function @code{buffer-name} returns the name of the -buffer as a string, which the @code{message} function inserts in place -of @code{%s}. - -To print a value as an integer, use @samp{%d} in the same way as -@samp{%s}. For example, to print a message in the echo area that -states the value of the @code{fill-column}, evaluate the following: - -@smallexample -(message "The value of fill-column is %d." fill-column) -@end smallexample - -@noindent -On my system, when I evaluate this list, @code{"The value of -fill-column is 72."} appears in my echo area@footnote{Actually, you -can use @code{%s} to print a number. It is non-specific. @code{%d} -prints only the part of a number left of a decimal point, and not -anything that is not a number.}. - -If there is more than one @samp{%s} in the quoted string, the value of -the first argument following the quoted string is printed at the -location of the first @samp{%s} and the value of the second argument is -printed at the location of the second @samp{%s}, and so on. - -@need 1250 -For example, if you evaluate the following, - -@smallexample -@group -(message "There are %d %s in the office!" - (- fill-column 14) "pink elephants") -@end group -@end smallexample - -@noindent -a rather whimsical message will appear in your echo area. On my system -it says, @code{"There are 58 pink elephants in the office!"}. - -The expression @code{(- fill-column 14)} is evaluated and the resulting -number is inserted in place of the @samp{%d}; and the string in double -quotes, @code{"pink elephants"}, is treated as a single argument and -inserted in place of the @samp{%s}. (That is to say, a string between -double quotes evaluates to itself, like a number.) - -Finally, here is a somewhat complex example that not only illustrates -the computation of a number, but also shows how you can use an -expression within an expression to generate the text that is substituted -for @samp{%s}: - -@smallexample -@group -(message "He saw %d %s" - (- fill-column 32) - (concat "red " - (substring - "The quick brown foxes jumped." 16 21) - " leaping.")) -@end group -@end smallexample - -In this example, @code{message} has three arguments: the string, -@code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and -the expression beginning with the function @code{concat}. The value -resulting from the evaluation of @code{(- fill-column 32)} is inserted -in place of the @samp{%d}; and the value returned by the expression -beginning with @code{concat} is inserted in place of the @samp{%s}. - -When your fill column is 70 and you evaluate the expression, the -message @code{"He saw 38 red foxes leaping."} appears in your echo -area. - -@node set & setq -@section Setting the Value of a Variable -@cindex Variable, setting value -@cindex Setting value of variable - -@cindex @samp{bind} defined -There are several ways by which a variable can be given a value. One of -the ways is to use either the function @code{set} or the function -@code{setq}. Another way is to use @code{let} (@pxref{let}). (The -jargon for this process is to @dfn{bind} a variable to a value.) - -The following sections not only describe how @code{set} and @code{setq} -work but also illustrate how arguments are passed. - -@menu -* Using set:: Setting values. -* Using setq:: Setting a quoted value. -* Counting:: Using @code{setq} to count. -@end menu - -@node Using set -@subsection Using @code{set} -@findex set - -To set the value of the symbol @code{flowers} to the list @code{'(rose -violet daisy buttercup)}, evaluate the following expression by -positioning the cursor after the expression and typing @kbd{C-x C-e}. - -@smallexample -(set 'flowers '(rose violet daisy buttercup)) -@end smallexample - -@noindent -The list @code{(rose violet daisy buttercup)} will appear in the echo -area. This is what is @emph{returned} by the @code{set} function. As a -side effect, the symbol @code{flowers} is bound to the list; that is, -the symbol @code{flowers}, which can be viewed as a variable, is given -the list as its value. (This process, by the way, illustrates how a -side effect to the Lisp interpreter, setting the value, can be the -primary effect that we humans are interested in. This is because every -Lisp function must return a value if it does not get an error, but it -will only have a side effect if it is designed to have one.) - -After evaluating the @code{set} expression, you can evaluate the symbol -@code{flowers} and it will return the value you just set. Here is the -symbol. Place your cursor after it and type @kbd{C-x C-e}. - -@smallexample -flowers -@end smallexample - -@noindent -When you evaluate @code{flowers}, the list -@code{(rose violet daisy buttercup)} appears in the echo area. - -Incidentally, if you evaluate @code{'flowers}, the variable with a quote -in front of it, what you will see in the echo area is the symbol itself, -@code{flowers}. Here is the quoted symbol, so you can try this: - -@smallexample -'flowers -@end smallexample - -Note also, that when you use @code{set}, you need to quote both -arguments to @code{set}, unless you want them evaluated. Since we do -not want either argument evaluated, neither the variable -@code{flowers} nor the list @code{(rose violet daisy buttercup)}, both -are quoted. (When you use @code{set} without quoting its first -argument, the first argument is evaluated before anything else is -done. If you did this and @code{flowers} did not have a value -already, you would get an error message that the @samp{Symbol's value -as variable is void}; on the other hand, if @code{flowers} did return -a value after it was evaluated, the @code{set} would attempt to set -the value that was returned. There are situations where this is the -right thing for the function to do; but such situations are rare.) - -@node Using setq -@subsection Using @code{setq} -@findex setq - -As a practical matter, you almost always quote the first argument to -@code{set}. The combination of @code{set} and a quoted first argument -is so common that it has its own name: the special form @code{setq}. -This special form is just like @code{set} except that the first argument -is quoted automatically, so you don't need to type the quote mark -yourself. Also, as an added convenience, @code{setq} permits you to set -several different variables to different values, all in one expression. - -To set the value of the variable @code{carnivores} to the list -@code{'(lion tiger leopard)} using @code{setq}, the following expression -is used: - -@smallexample -(setq carnivores '(lion tiger leopard)) -@end smallexample - -@noindent -This is exactly the same as using @code{set} except the first argument -is automatically quoted by @code{setq}. (The @samp{q} in @code{setq} -means @code{quote}.) - -@need 1250 -With @code{set}, the expression would look like this: - -@smallexample -(set 'carnivores '(lion tiger leopard)) -@end smallexample - -Also, @code{setq} can be used to assign different values to -different variables. The first argument is bound to the value -of the second argument, the third argument is bound to the value of the -fourth argument, and so on. For example, you could use the following to -assign a list of trees to the symbol @code{trees} and a list of herbivores -to the symbol @code{herbivores}: - -@smallexample -@group -(setq trees '(pine fir oak maple) - herbivores '(gazelle antelope zebra)) -@end group -@end smallexample - -@noindent -(The expression could just as well have been on one line, but it might -not have fit on a page; and humans find it easier to read nicely -formatted lists.) - -Although I have been using the term `assign', there is another way of -thinking about the workings of @code{set} and @code{setq}; and that is to -say that @code{set} and @code{setq} make the symbol @emph{point} to the -list. This latter way of thinking is very common and in forthcoming -chapters we shall come upon at least one symbol that has `pointer' as -part of its name. The name is chosen because the symbol has a value, -specifically a list, attached to it; or, expressed another way, -the symbol is set to ``point'' to the list. - -@node Counting -@subsection Counting -@cindex Counting - -Here is an example that shows how to use @code{setq} in a counter. You -might use this to count how many times a part of your program repeats -itself. First set a variable to zero; then add one to the number each -time the program repeats itself. To do this, you need a variable that -serves as a counter, and two expressions: an initial @code{setq} -expression that sets the counter variable to zero; and a second -@code{setq} expression that increments the counter each time it is -evaluated. - -@smallexample -@group -(setq counter 0) ; @r{Let's call this the initializer.} - -(setq counter (+ counter 1)) ; @r{This is the incrementer.} - -counter ; @r{This is the counter.} -@end group -@end smallexample - -@noindent -(The text following the @samp{;} are comments. @xref{Change a -defun, , Change a Function Definition}.) - -If you evaluate the first of these expressions, the initializer, -@code{(setq counter 0)}, and then evaluate the third expression, -@code{counter}, the number @code{0} will appear in the echo area. If -you then evaluate the second expression, the incrementer, @code{(setq -counter (+ counter 1))}, the counter will get the value 1. So if you -again evaluate @code{counter}, the number @code{1} will appear in the -echo area. Each time you evaluate the second expression, the value of -the counter will be incremented. - -When you evaluate the incrementer, @code{(setq counter (+ counter 1))}, -the Lisp interpreter first evaluates the innermost list; this is the -addition. In order to evaluate this list, it must evaluate the variable -@code{counter} and the number @code{1}. When it evaluates the variable -@code{counter}, it receives its current value. It passes this value and -the number @code{1} to the @code{+} which adds them together. The sum -is then returned as the value of the inner list and passed to the -@code{setq} which sets the variable @code{counter} to this new value. -Thus, the value of the variable, @code{counter}, is changed. - -@node Summary -@section Summary - -Learning Lisp is like climbing a hill in which the first part is the -steepest. You have now climbed the most difficult part; what remains -becomes easier as you progress onwards. - -@need 1000 -In summary, - -@itemize @bullet - -@item -Lisp programs are made up of expressions, which are lists or single atoms. - -@item -Lists are made up of zero or more atoms or inner lists, separated by whitespace and -surrounded by parentheses. A list can be empty. - -@item -Atoms are multi-character symbols, like @code{forward-paragraph}, single -character symbols like @code{+}, strings of characters between double -quotation marks, or numbers. - -@item -A number evaluates to itself. - -@item -A string between double quotes also evaluates to itself. - -@item -When you evaluate a symbol by itself, its value is returned. - -@item -When you evaluate a list, the Lisp interpreter looks at the first symbol -in the list and then at the function definition bound to that symbol. -Then the instructions in the function definition are carried out. - -@item -A single quotation mark, -@ifinfo -' -@end ifinfo -@ifnotinfo -@code{'} -@end ifnotinfo -, tells the Lisp interpreter that it should -return the following expression as written, and not evaluate it as it -would if the quote were not there. - -@item -Arguments are the information passed to a function. The arguments to a -function are computed by evaluating the rest of the elements of the list -of which the function is the first element. - -@item -A function always returns a value when it is evaluated (unless it gets -an error); in addition, it may also carry out some action called a -``side effect''. In many cases, a function's primary purpose is to -create a side effect. -@end itemize - -@node Error Message Exercises -@section Exercises - -A few simple exercises: - -@itemize @bullet -@item -Generate an error message by evaluating an appropriate symbol that is -not within parentheses. - -@item -Generate an error message by evaluating an appropriate symbol that is -between parentheses. - -@item -Create a counter that increments by two rather than one. - -@item -Write an expression that prints a message in the echo area when -evaluated. -@end itemize - -@node Practicing Evaluation -@chapter Practicing Evaluation -@cindex Practicing evaluation -@cindex Evaluation practice - -Before learning how to write a function definition in Emacs Lisp, it is -useful to spend a little time evaluating various expressions that have -already been written. These expressions will be lists with the -functions as their first (and often only) element. Since some of the -functions associated with buffers are both simple and interesting, we -will start with those. In this section, we will evaluate a few of -these. In another section, we will study the code of several other -buffer-related functions, to see how they were written. - -@menu -* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} - causes evaluation. -* Buffer Names:: Buffers and files are different. -* Getting Buffers:: Getting a buffer itself, not merely its name. -* Switching Buffers:: How to change to another buffer. -* Buffer Size & Locations:: Where point is located and the size of - the buffer. -* Evaluation Exercise:: -@end menu - -@ifnottex -@node How to Evaluate -@unnumberedsec How to Evaluate -@end ifnottex - -@i{Whenever you give an editing command} to Emacs Lisp, such as the -command to move the cursor or to scroll the screen, @i{you are evaluating -an expression,} the first element of which is a function. @i{This is -how Emacs works.} - -@cindex @samp{interactive function} defined -@cindex @samp{command} defined -When you type keys, you cause the Lisp interpreter to evaluate an -expression and that is how you get your results. Even typing plain text -involves evaluating an Emacs Lisp function, in this case, one that uses -@code{self-insert-command}, which simply inserts the character you -typed. The functions you evaluate by typing keystrokes are called -@dfn{interactive} functions, or @dfn{commands}; how you make a function -interactive will be illustrated in the chapter on how to write function -definitions. @xref{Interactive, , Making a Function Interactive}. - -In addition to typing keyboard commands, we have seen a second way to -evaluate an expression: by positioning the cursor after a list and -typing @kbd{C-x C-e}. This is what we will do in the rest of this -section. There are other ways to evaluate an expression as well; these -will be described as we come to them. - -Besides being used for practicing evaluation, the functions shown in the -next few sections are important in their own right. A study of these -functions makes clear the distinction between buffers and files, how to -switch to a buffer, and how to determine a location within it. - -@node Buffer Names -@section Buffer Names -@findex buffer-name -@findex buffer-file-name - -The two functions, @code{buffer-name} and @code{buffer-file-name}, show -the difference between a file and a buffer. When you evaluate the -following expression, @code{(buffer-name)}, the name of the buffer -appears in the echo area. When you evaluate @code{(buffer-file-name)}, -the name of the file to which the buffer refers appears in the echo -area. Usually, the name returned by @code{(buffer-name)} is the same as -the name of the file to which it refers, and the name returned by -@code{(buffer-file-name)} is the full path-name of the file. - -A file and a buffer are two different entities. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of Emacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; we say -the buffer is @dfn{visiting} that file. This copy is what you work on -and modify. Changes to the buffer do not change the file, until you -save the buffer. When you save the buffer, the buffer is copied to the file -and is thus saved permanently. - -@need 1250 -If you are reading this in Info inside of GNU Emacs, you can evaluate -each of the following expressions by positioning the cursor after it and -typing @kbd{C-x C-e}. - -@example -@group -(buffer-name) - -(buffer-file-name) -@end group -@end example - -@noindent -When I do this in Info, the value returned by evaluating -@code{(buffer-name)} is @file{"*info*"}, and the value returned by -evaluating @code{(buffer-file-name)} is @file{nil}. - -On the other hand, while I am writing this document, the value -returned by evaluating @code{(buffer-name)} is -@file{"introduction.texinfo"}, and the value returned by evaluating -@code{(buffer-file-name)} is -@file{"/gnu/work/intro/introduction.texinfo"}. - -@cindex @code{nil}, history of word -The former is the name of the buffer and the latter is the name of the -file. In Info, the buffer name is @file{"*info*"}. Info does not -point to any file, so the result of evaluating -@code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is -from the Latin word for `nothing'; in this case, it means that the -buffer is not associated with any file. (In Lisp, @code{nil} is also -used to mean `false' and is a synonym for the empty list, @code{()}.) - -When I am writing, the name of my buffer is -@file{"introduction.texinfo"}. The name of the file to which it -points is @file{"/gnu/work/intro/introduction.texinfo"}. - -(In the expressions, the parentheses tell the Lisp interpreter to -treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as -functions; without the parentheses, the interpreter would attempt to -evaluate the symbols as variables. @xref{Variables}.) - -In spite of the distinction between files and buffers, you will often -find that people refer to a file when they mean a buffer and vice versa. -Indeed, most people say, ``I am editing a file,'' rather than saying, -``I am editing a buffer which I will soon save to a file.'' It is -almost always clear from context what people mean. When dealing with -computer programs, however, it is important to keep the distinction in mind, -since the computer is not as smart as a person. - -@cindex Buffer, history of word -The word `buffer', by the way, comes from the meaning of the word as a -cushion that deadens the force of a collision. In early computers, a -buffer cushioned the interaction between files and the computer's -central processing unit. The drums or tapes that held a file and the -central processing unit were pieces of equipment that were very -different from each other, working at their own speeds, in spurts. The -buffer made it possible for them to work together effectively. -Eventually, the buffer grew from being an intermediary, a temporary -holding place, to being the place where work is done. This -transformation is rather like that of a small seaport that grew into a -great city: once it was merely the place where cargo was warehoused -temporarily before being loaded onto ships; then it became a business -and cultural center in its own right. - -Not all buffers are associated with files. For example, a -@file{*scratch*} buffer does not visit any file. Similarly, a -@file{*Help*} buffer is not associated with any file. - -In the old days, when you lacked a @file{~/.emacs} file and started an -Emacs session by typing the command @code{emacs} alone, without naming -any files, Emacs started with the @file{*scratch*} buffer visible. -Nowadays, you will see a splash screen. You can follow one of the -commands suggested on the splash screen, visit a file, or press the -spacebar to reach the @file{*scratch*} buffer. - -If you switch to the @file{*scratch*} buffer, type -@code{(buffer-name)}, position the cursor after it, and then type -@kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"} -will be returned and will appear in the echo area. @code{"*scratch*"} -is the name of the buffer. When you type @code{(buffer-file-name)} in -the @file{*scratch*} buffer and evaluate that, @code{nil} will appear -in the echo area, just as it does when you evaluate -@code{(buffer-file-name)} in Info. - -Incidentally, if you are in the @file{*scratch*} buffer and want the -value returned by an expression to appear in the @file{*scratch*} -buffer itself rather than in the echo area, type @kbd{C-u C-x C-e} -instead of @kbd{C-x C-e}. This causes the value returned to appear -after the expression. The buffer will look like this: - -@smallexample -(buffer-name)"*scratch*" -@end smallexample - -@noindent -You cannot do this in Info since Info is read-only and it will not allow -you to change the contents of the buffer. But you can do this in any -buffer you can edit; and when you write code or documentation (such as -this book), this feature is very useful. - -@node Getting Buffers -@section Getting Buffers -@findex current-buffer -@findex other-buffer -@cindex Getting a buffer - -The @code{buffer-name} function returns the @emph{name} of the buffer; -to get the buffer @emph{itself}, a different function is needed: the -@code{current-buffer} function. If you use this function in code, what -you get is the buffer itself. - -A name and the object or entity to which the name refers are different -from each other. You are not your name. You are a person to whom -others refer by name. If you ask to speak to George and someone hands you -a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r}, -@samp{g}, and @samp{e} written on it, you might be amused, but you would -not be satisfied. You do not want to speak to the name, but to the -person to whom the name refers. A buffer is similar: the name of the -scratch buffer is @file{*scratch*}, but the name is not the buffer. To -get a buffer itself, you need to use a function such as -@code{current-buffer}. - -However, there is a slight complication: if you evaluate -@code{current-buffer} in an expression on its own, as we will do here, -what you see is a printed representation of the name of the buffer -without the contents of the buffer. Emacs works this way for two -reasons: the buffer may be thousands of lines long---too long to be -conveniently displayed; and, another buffer may have the same contents -but a different name, and it is important to distinguish between them. - -@need 800 -Here is an expression containing the function: - -@smallexample -(current-buffer) -@end smallexample - -@noindent -If you evaluate this expression in Info in Emacs in the usual way, -@file{#} will appear in the echo area. The special -format indicates that the buffer itself is being returned, rather than -just its name. - -Incidentally, while you can type a number or symbol into a program, you -cannot do that with the printed representation of a buffer: the only way -to get a buffer itself is with a function such as @code{current-buffer}. - -A related function is @code{other-buffer}. This returns the most -recently selected buffer other than the one you are in currently, not -a printed representation of its name. If you have recently switched -back and forth from the @file{*scratch*} buffer, @code{other-buffer} -will return that buffer. - -@need 800 -You can see this by evaluating the expression: - -@smallexample -(other-buffer) -@end smallexample - -@noindent -You should see @file{#} appear in the echo area, or -the name of whatever other buffer you switched back from most -recently@footnote{Actually, by default, if the buffer from which you -just switched is visible to you in another window, @code{other-buffer} -will choose the most recent buffer that you cannot see; this is a -subtlety that I often forget.}. - -@node Switching Buffers -@section Switching Buffers -@findex switch-to-buffer -@findex set-buffer -@cindex Switching to a buffer - -The @code{other-buffer} function actually provides a buffer when it is -used as an argument to a function that requires one. We can see this -by using @code{other-buffer} and @code{switch-to-buffer} to switch to a -different buffer. - -But first, a brief introduction to the @code{switch-to-buffer} -function. When you switched back and forth from Info to the -@file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most -likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or -rather, to save typing, you probably only typed @kbd{RET} if the -default buffer was @file{*scratch*}, or if it was different, then you -typed just part of the name, such as @code{*sc}, pressed your -@kbd{TAB} key to cause it to expand to the full name, and then typed -@kbd{RET}.} when prompted in the minibuffer for the name of -the buffer to which you wanted to switch. The keystrokes, @kbd{C-x -b}, cause the Lisp interpreter to evaluate the interactive function -@code{switch-to-buffer}. As we said before, this is how Emacs works: -different keystrokes call or run different functions. For example, -@kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls -@code{forward-sentence}, and so on. - -By writing @code{switch-to-buffer} in an expression, and giving it a -buffer to switch to, we can switch buffers just the way @kbd{C-x b} -does: - -@smallexample -(switch-to-buffer (other-buffer)) -@end smallexample - -@noindent -The symbol @code{switch-to-buffer} is the first element of the list, -so the Lisp interpreter will treat it as a function and carry out the -instructions that are attached to it. But before doing that, the -interpreter will note that @code{other-buffer} is inside parentheses -and work on that symbol first. @code{other-buffer} is the first (and -in this case, the only) element of this list, so the Lisp interpreter -calls or runs the function. It returns another buffer. Next, the -interpreter runs @code{switch-to-buffer}, passing to it, as an -argument, the other buffer, which is what Emacs will switch to. If -you are reading this in Info, try this now. Evaluate the expression. -(To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this -expression will move you to your most recent other buffer that you -cannot see. If you really want to go to your most recently selected -buffer, even if you can still see it, you need to evaluate the -following more complex expression: - -@smallexample -(switch-to-buffer (other-buffer (current-buffer) t)) -@end smallexample - -@c noindent -In this case, the first argument to @code{other-buffer} tells it which -buffer to skip---the current one---and the second argument tells -@code{other-buffer} it is OK to switch to a visible buffer. -In regular use, @code{switch-to-buffer} takes you to an invisible -window since you would most likely use @kbd{C-x o} (@code{other-window}) -to go to another visible buffer.} - -In the programming examples in later sections of this document, you will -see the function @code{set-buffer} more often than -@code{switch-to-buffer}. This is because of a difference between -computer programs and humans: humans have eyes and expect to see the -buffer on which they are working on their computer terminals. This is -so obvious, it almost goes without saying. However, programs do not -have eyes. When a computer program works on a buffer, that buffer does -not need to be visible on the screen. - -@code{switch-to-buffer} is designed for humans and does two different -things: it switches the buffer to which Emacs's attention is directed; and -it switches the buffer displayed in the window to the new buffer. -@code{set-buffer}, on the other hand, does only one thing: it switches -the attention of the computer program to a different buffer. The buffer -on the screen remains unchanged (of course, normally nothing happens -there until the command finishes running). - -@cindex @samp{call} defined -Also, we have just introduced another jargon term, the word @dfn{call}. -When you evaluate a list in which the first symbol is a function, you -are calling that function. The use of the term comes from the notion of -the function as an entity that can do something for you if you `call' -it---just as a plumber is an entity who can fix a leak if you call him -or her. - -@node Buffer Size & Locations -@section Buffer Size and the Location of Point -@cindex Size of buffer -@cindex Buffer size -@cindex Point location -@cindex Location of point - -Finally, let's look at several rather simple functions, -@code{buffer-size}, @code{point}, @code{point-min}, and -@code{point-max}. These give information about the size of a buffer and -the location of point within it. - -The function @code{buffer-size} tells you the size of the current -buffer; that is, the function returns a count of the number of -characters in the buffer. - -@smallexample -(buffer-size) -@end smallexample - -@noindent -You can evaluate this in the usual way, by positioning the -cursor after the expression and typing @kbd{C-x C-e}. - -@cindex @samp{point} defined -In Emacs, the current position of the cursor is called @dfn{point}. -The expression @code{(point)} returns a number that tells you where the -cursor is located as a count of the number of characters from the -beginning of the buffer up to point. - -@need 1250 -You can see the character count for point in this buffer by evaluating -the following expression in the usual way: - -@smallexample -(point) -@end smallexample - -@noindent -As I write this, the value of @code{point} is 65724. The @code{point} -function is frequently used in some of the examples later in this -book. - -@need 1250 -The value of point depends, of course, on its location within the -buffer. If you evaluate point in this spot, the number will be larger: - -@smallexample -(point) -@end smallexample - -@noindent -For me, the value of point in this location is 66043, which means that -there are 319 characters (including spaces) between the two -expressions. (Doubtless, you will see different numbers, since I will -have edited this since I first evaluated point.) - -@cindex @samp{narrowing} defined -The function @code{point-min} is somewhat similar to @code{point}, but -it returns the value of the minimum permissible value of point in the -current buffer. This is the number 1 unless @dfn{narrowing} is in -effect. (Narrowing is a mechanism whereby you can restrict yourself, -or a program, to operations on just a part of a buffer. -@xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the -function @code{point-max} returns the value of the maximum permissible -value of point in the current buffer. - -@node Evaluation Exercise -@section Exercise - -Find a file with which you are working and move towards its middle. -Find its buffer name, file name, length, and your position in the file. - -@node Writing Defuns -@chapter How To Write Function Definitions -@cindex Definition writing -@cindex Function definition writing -@cindex Writing a function definition - -When the Lisp interpreter evaluates a list, it looks to see whether the -first symbol on the list has a function definition attached to it; or, -put another way, whether the symbol points to a function definition. If -it does, the computer carries out the instructions in the definition. A -symbol that has a function definition is called, simply, a function -(although, properly speaking, the definition is the function and the -symbol refers to it.) - -@menu -* Primitive Functions:: -* defun:: The @code{defun} macro. -* Install:: Install a function definition. -* Interactive:: Making a function interactive. -* Interactive Options:: Different options for @code{interactive}. -* Permanent Installation:: Installing code permanently. -* let:: Creating and initializing local variables. -* if:: What if? -* else:: If--then--else expressions. -* Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. -* Review:: -* defun Exercises:: -@end menu - -@ifnottex -@node Primitive Functions -@unnumberedsec An Aside about Primitive Functions -@end ifnottex -@cindex Primitive functions -@cindex Functions, primitive - -@cindex C language primitives -@cindex Primitives written in C -All functions are defined in terms of other functions, except for a few -@dfn{primitive} functions that are written in the C programming -language. When you write functions' definitions, you will write them in -Emacs Lisp and use other functions as your building blocks. Some of the -functions you will use will themselves be written in Emacs Lisp (perhaps -by you) and some will be primitives written in C@. The primitive -functions are used exactly like those written in Emacs Lisp and behave -like them. They are written in C so we can easily run GNU Emacs on any -computer that has sufficient power and can run C. - -Let me re-emphasize this: when you write code in Emacs Lisp, you do not -distinguish between the use of functions written in C and the use of -functions written in Emacs Lisp. The difference is irrelevant. I -mention the distinction only because it is interesting to know. Indeed, -unless you investigate, you won't know whether an already-written -function is written in Emacs Lisp or C. - -@node defun -@section The @code{defun} Macro -@findex defun - -@cindex @samp{function definition} defined -In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to -it that tells the computer what to do when the function is called. -This code is called the @dfn{function definition} and is created by -evaluating a Lisp expression that starts with the symbol @code{defun} -(which is an abbreviation for @emph{define function}). - -In subsequent sections, we will look at function definitions from the -Emacs source code, such as @code{mark-whole-buffer}. In this section, -we will describe a simple function definition so you can see how it -looks. This function definition uses arithmetic because it makes for a -simple example. Some people dislike examples using arithmetic; however, -if you are such a person, do not despair. Hardly any of the code we -will study in the remainder of this introduction involves arithmetic or -mathematics. The examples mostly involve text in one way or another. - -A function definition has up to five parts following the word -@code{defun}: - -@enumerate -@item -The name of the symbol to which the function definition should be -attached. - -@item -A list of the arguments that will be passed to the function. If no -arguments will be passed to the function, this is an empty list, -@code{()}. - -@item -Documentation describing the function. (Technically optional, but -strongly recommended.) - -@item -Optionally, an expression to make the function interactive so you can -use it by typing @kbd{M-x} and then the name of the function; or by -typing an appropriate key or keychord. - -@cindex @samp{body} defined -@item -The code that instructs the computer what to do: the @dfn{body} of the -function definition. -@end enumerate - -It is helpful to think of the five parts of a function definition as -being organized in a template, with slots for each part: - -@smallexample -@group -(defun @var{function-name} (@var{arguments}@dots{}) - "@var{optional-documentation}@dots{}" - (interactive @var{argument-passing-info}) ; @r{optional} - @var{body}@dots{}) -@end group -@end smallexample - -As an example, here is the code for a function that multiplies its -argument by 7. (This example is not interactive. @xref{Interactive, -, Making a Function Interactive}, for that information.) - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -This definition begins with a parenthesis and the symbol @code{defun}, -followed by the name of the function. - -@cindex @samp{argument list} defined -The name of the function is followed by a list that contains the -arguments that will be passed to the function. This list is called -the @dfn{argument list}. In this example, the list has only one -element, the symbol, @code{number}. When the function is used, the -symbol will be bound to the value that is used as the argument to the -function. - -Instead of choosing the word @code{number} for the name of the argument, -I could have picked any other name. For example, I could have chosen -the word @code{multiplicand}. I picked the word `number' because it -tells what kind of value is intended for this slot; but I could just as -well have chosen the word `multiplicand' to indicate the role that the -value placed in this slot will play in the workings of the function. I -could have called it @code{foogle}, but that would have been a bad -choice because it would not tell humans what it means. The choice of -name is up to the programmer and should be chosen to make the meaning of -the function clear. - -Indeed, you can choose any name you wish for a symbol in an argument -list, even the name of a symbol used in some other function: the name -you use in an argument list is private to that particular definition. -In that definition, the name refers to a different entity than any use -of the same name outside the function definition. Suppose you have a -nick-name `Shorty' in your family; when your family members refer to -`Shorty', they mean you. But outside your family, in a movie, for -example, the name `Shorty' refers to someone else. Because a name in an -argument list is private to the function definition, you can change the -value of such a symbol inside the body of a function without changing -its value outside the function. The effect is similar to that produced -by a @code{let} expression. (@xref{let, , @code{let}}.) - -@ignore -Note also that we discuss the word `number' in two different ways: as a -symbol that appears in the code, and as the name of something that will -be replaced by a something else during the evaluation of the function. -In the first case, @code{number} is a symbol, not a number; it happens -that within the function, it is a variable who value is the number in -question, but our primary interest in it is as a symbol. On the other -hand, when we are talking about the function, our interest is that we -will substitute a number for the word @var{number}. To keep this -distinction clear, we use different typography for the two -circumstances. When we talk about this function, or about how it works, -we refer to this number by writing @var{number}. In the function -itself, we refer to it by writing @code{number}. -@end ignore - -The argument list is followed by the documentation string that -describes the function. This is what you see when you type -@w{@kbd{C-h f}} and the name of a function. Incidentally, when you -write a documentation string like this, you should make the first line -a complete sentence since some commands, such as @code{apropos}, print -only the first line of a multi-line documentation string. Also, you -should not indent the second line of a documentation string, if you -have one, because that looks odd when you use @kbd{C-h f} -(@code{describe-function}). The documentation string is optional, but -it is so useful, it should be included in almost every function you -write. - -@findex * @r{(multiplication)} -The third line of the example consists of the body of the function -definition. (Most functions' definitions, of course, are longer than -this.) In this function, the body is the list, @code{(* 7 number)}, which -says to multiply the value of @var{number} by 7. (In Emacs Lisp, -@code{*} is the function for multiplication, just as @code{+} is the -function for addition.) - -When you use the @code{multiply-by-seven} function, the argument -@code{number} evaluates to the actual number you want used. Here is an -example that shows how @code{multiply-by-seven} is used; but don't try -to evaluate this yet! - -@smallexample -(multiply-by-seven 3) -@end smallexample - -@noindent -The symbol @code{number}, specified in the function definition in the -next section, is given or ``bound to'' the value 3 in the actual use of -the function. Note that although @code{number} was inside parentheses -in the function definition, the argument passed to the -@code{multiply-by-seven} function is not in parentheses. The -parentheses are written in the function definition so the computer can -figure out where the argument list ends and the rest of the function -definition begins. - -If you evaluate this example, you are likely to get an error message. -(Go ahead, try it!) This is because we have written the function -definition, but not yet told the computer about the definition---we have -not yet installed (or `loaded') the function definition in Emacs. -Installing a function is the process that tells the Lisp interpreter the -definition of the function. Installation is described in the next -section. - -@node Install -@section Install a Function Definition -@cindex Install a Function Definition -@cindex Definition installation -@cindex Function definition installation - -If you are reading this inside of Info in Emacs, you can try out the -@code{multiply-by-seven} function by first evaluating the function -definition and then evaluating @code{(multiply-by-seven 3)}. A copy of -the function definition follows. Place the cursor after the last -parenthesis of the function definition and type @kbd{C-x C-e}. When you -do this, @code{multiply-by-seven} will appear in the echo area. (What -this means is that when a function definition is evaluated, the value it -returns is the name of the defined function.) At the same time, this -action installs the function definition. - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -@noindent -By evaluating this @code{defun}, you have just installed -@code{multiply-by-seven} in Emacs. The function is now just as much a -part of Emacs as @code{forward-word} or any other editing function you -use. (@code{multiply-by-seven} will stay installed until you quit -Emacs. To reload code automatically whenever you start Emacs, see -@ref{Permanent Installation, , Installing Code Permanently}.) - -@menu -* Effect of installation:: -* Change a defun:: How to change a function definition. -@end menu - -@ifnottex -@node Effect of installation -@unnumberedsubsec The effect of installation -@end ifnottex - -You can see the effect of installing @code{multiply-by-seven} by -evaluating the following sample. Place the cursor after the following -expression and type @kbd{C-x C-e}. The number 21 will appear in the -echo area. - -@smallexample -(multiply-by-seven 3) -@end smallexample - -If you wish, you can read the documentation for the function by typing -@kbd{C-h f} (@code{describe-function}) and then the name of the -function, @code{multiply-by-seven}. When you do this, a -@file{*Help*} window will appear on your screen that says: - -@smallexample -@group -multiply-by-seven is a Lisp function. -(multiply-by-seven NUMBER) - -Multiply NUMBER by seven. -@end group -@end smallexample - -@noindent -(To return to a single window on your screen, type @kbd{C-x 1}.) - -@node Change a defun -@subsection Change a Function Definition -@cindex Changing a function definition -@cindex Function definition, how to change -@cindex Definition, how to change - -If you want to change the code in @code{multiply-by-seven}, just rewrite -it. To install the new version in place of the old one, evaluate the -function definition again. This is how you modify code in Emacs. It is -very simple. - -As an example, you can change the @code{multiply-by-seven} function to -add the number to itself seven times instead of multiplying the number -by seven. It produces the same answer, but by a different path. At -the same time, we will add a comment to the code; a comment is text -that the Lisp interpreter ignores, but that a human reader may find -useful or enlightening. The comment is that this is the ``second -version''. - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Second version.} - "Multiply NUMBER by seven." - (+ number number number number number number number)) -@end group -@end smallexample - -@cindex Comments in Lisp code -The comment follows a semicolon, @samp{;}. In Lisp, everything on a -line that follows a semicolon is a comment. The end of the line is the -end of the comment. To stretch a comment over two or more lines, begin -each line with a semicolon. - -@xref{Beginning init File, , Beginning a @file{.emacs} -File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp -Reference Manual}, for more about comments. - -You can install this version of the @code{multiply-by-seven} function by -evaluating it in the same way you evaluated the first function: place -the cursor after the last parenthesis and type @kbd{C-x C-e}. - -In summary, this is how you write code in Emacs Lisp: you write a -function; install it; test it; and then make fixes or enhancements and -install it again. - -@node Interactive -@section Make a Function Interactive -@cindex Interactive functions -@findex interactive - -You make a function interactive by placing a list that begins with -the special form @code{interactive} immediately after the -documentation. A user can invoke an interactive function by typing -@kbd{M-x} and then the name of the function; or by typing the keys to -which it is bound, for example, by typing @kbd{C-n} for -@code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}. - -Interestingly, when you call an interactive function interactively, -the value returned is not automatically displayed in the echo area. -This is because you often call an interactive function for its side -effects, such as moving forward by a word or line, and not for the -value returned. If the returned value were displayed in the echo area -each time you typed a key, it would be very distracting. - -@menu -* Interactive multiply-by-seven:: An overview. -* multiply-by-seven in detail:: The interactive version. -@end menu - -@ifnottex -@node Interactive multiply-by-seven -@unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview -@end ifnottex - -Both the use of the special form @code{interactive} and one way to -display a value in the echo area can be illustrated by creating an -interactive version of @code{multiply-by-seven}. - -@need 1250 -Here is the code: - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Interactive version.} - "Multiply NUMBER by seven." - (interactive "p") - (message "The result is %d" (* 7 number))) -@end group -@end smallexample - -@noindent -You can install this code by placing your cursor after it and typing -@kbd{C-x C-e}. The name of the function will appear in your echo area. -Then, you can use this code by typing @kbd{C-u} and a number and then -typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase -@samp{The result is @dots{}} followed by the product will appear in the -echo area. - -Speaking more generally, you invoke a function like this in either of two -ways: - -@enumerate -@item -By typing a prefix argument that contains the number to be passed, and -then typing @kbd{M-x} and the name of the function, as with -@kbd{C-u 3 M-x forward-sentence}; or, - -@item -By typing whatever key or keychord the function is bound to, as with -@kbd{C-u 3 M-e}. -@end enumerate - -@noindent -Both the examples just mentioned work identically to move point forward -three sentences. (Since @code{multiply-by-seven} is not bound to a key, -it could not be used as an example of key binding.) - -(@xref{Keybindings, , Some Keybindings}, to learn how to bind a command -to a key.) - -A prefix argument is passed to an interactive function by typing the -@key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by -typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you -type @kbd{C-u} without a number, it defaults to 4). - -@node multiply-by-seven in detail -@subsection An Interactive @code{multiply-by-seven} - -Let's look at the use of the special form @code{interactive} and then at -the function @code{message} in the interactive version of -@code{multiply-by-seven}. You will recall that the function definition -looks like this: - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Interactive version.} - "Multiply NUMBER by seven." - (interactive "p") - (message "The result is %d" (* 7 number))) -@end group -@end smallexample - -In this function, the expression, @code{(interactive "p")}, is a list of -two elements. The @code{"p"} tells Emacs to pass the prefix argument to -the function and use its value for the argument of the function. - -@need 1000 -The argument will be a number. This means that the symbol -@code{number} will be bound to a number in the line: - -@smallexample -(message "The result is %d" (* 7 number)) -@end smallexample - -@need 1250 -@noindent -For example, if your prefix argument is 5, the Lisp interpreter will -evaluate the line as if it were: - -@smallexample -(message "The result is %d" (* 7 5)) -@end smallexample - -@noindent -(If you are reading this in GNU Emacs, you can evaluate this expression -yourself.) First, the interpreter will evaluate the inner list, which -is @code{(* 7 5)}. This returns a value of 35. Next, it -will evaluate the outer list, passing the values of the second and -subsequent elements of the list to the function @code{message}. - -As we have seen, @code{message} is an Emacs Lisp function especially -designed for sending a one line message to a user. (@xref{message, , -The @code{message} function}.) In summary, the @code{message} -function prints its first argument in the echo area as is, except for -occurrences of @samp{%d} or @samp{%s} (and various other %-sequences -which we have not mentioned). When it sees a control sequence, the -function looks to the second or subsequent arguments and prints the -value of the argument in the location in the string where the control -sequence is located. - -In the interactive @code{multiply-by-seven} function, the control string -is @samp{%d}, which requires a number, and the value returned by -evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35 -is printed in place of the @samp{%d} and the message is @samp{The result -is 35}. - -(Note that when you call the function @code{multiply-by-seven}, the -message is printed without quotes, but when you call @code{message}, the -text is printed in double quotes. This is because the value returned by -@code{message} is what appears in the echo area when you evaluate an -expression whose first element is @code{message}; but when embedded in a -function, @code{message} prints the text as a side effect without -quotes.) - -@node Interactive Options -@section Different Options for @code{interactive} -@cindex Options for @code{interactive} -@cindex Interactive options - -In the example, @code{multiply-by-seven} used @code{"p"} as the -argument to @code{interactive}. This argument told Emacs to interpret -your typing either @kbd{C-u} followed by a number or @key{META} -followed by a number as a command to pass that number to the function -as its argument. Emacs has more than twenty characters predefined for -use with @code{interactive}. In almost every case, one of these -options will enable you to pass the right information interactively to -a function. (@xref{Interactive Codes, , Code Characters for -@code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.) - -@need 1250 -Consider the function @code{zap-to-char}. Its interactive expression -is - -@smallexample -(interactive "p\ncZap to char: ") -@end smallexample - -The first part of the argument to @code{interactive} is @samp{p}, with -which you are already familiar. This argument tells Emacs to -interpret a `prefix', as a number to be passed to the function. You -can specify a prefix either by typing @kbd{C-u} followed by a number -or by typing @key{META} followed by a number. The prefix is the -number of specified characters. Thus, if your prefix is three and the -specified character is @samp{x}, then you will delete all the text up -to and including the third next @samp{x}. If you do not set a prefix, -then you delete all the text up to and including the specified -character, but no more. - -The @samp{c} tells the function the name of the character to which to delete. - -More formally, a function with two or more arguments can have -information passed to each argument by adding parts to the string that -follows @code{interactive}. When you do this, the information is -passed to each argument in the same order it is specified in the -@code{interactive} list. In the string, each part is separated from -the next part by a @samp{\n}, which is a newline. For example, you -can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }. -This causes Emacs to pass the value of the prefix argument (if there -is one) and the character. - -In this case, the function definition looks like the following, where -@code{arg} and @code{char} are the symbols to which @code{interactive} -binds the prefix argument and the specified character: - -@smallexample -@group -(defun @var{name-of-function} (arg char) - "@var{documentation}@dots{}" - (interactive "p\ncZap to char: ") - @var{body-of-function}@dots{}) -@end group -@end smallexample - -@noindent -(The space after the colon in the prompt makes it look better when you -are prompted. @xref{copy-to-buffer, , The Definition of -@code{copy-to-buffer}}, for an example.) - -When a function does not take arguments, @code{interactive} does not -require any. Such a function contains the simple expression -@code{(interactive)}. The @code{mark-whole-buffer} function is like -this. - -Alternatively, if the special letter-codes are not right for your -application, you can pass your own arguments to @code{interactive} as -a list. - -@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}, -for an example. @xref{Using Interactive, , Using @code{Interactive}, -elisp, The GNU Emacs Lisp Reference Manual}, for a more complete -explanation about this technique. - -@node Permanent Installation -@section Install Code Permanently -@cindex Install code permanently -@cindex Permanent code installation -@cindex Code installation - -When you install a function definition by evaluating it, it will stay -installed until you quit Emacs. The next time you start a new session -of Emacs, the function will not be installed unless you evaluate the -function definition again. - -At some point, you may want to have code installed automatically -whenever you start a new session of Emacs. There are several ways of -doing this: - -@itemize @bullet -@item -If you have code that is just for yourself, you can put the code for the -function definition in your @file{.emacs} initialization file. When you -start Emacs, your @file{.emacs} file is automatically evaluated and all -the function definitions within it are installed. -@xref{Emacs Initialization, , Your @file{.emacs} File}. - -@item -Alternatively, you can put the function definitions that you want -installed in one or more files of their own and use the @code{load} -function to cause Emacs to evaluate and thereby install each of the -functions in the files. -@xref{Loading Files, , Loading Files}. - -@item -Thirdly, if you have code that your whole site will use, it is usual -to put it in a file called @file{site-init.el} that is loaded when -Emacs is built. This makes the code available to everyone who uses -your machine. (See the @file{INSTALL} file that is part of the Emacs -distribution.) -@end itemize - -Finally, if you have code that everyone who uses Emacs may want, you -can post it on a computer network or send a copy to the Free Software -Foundation. (When you do this, please license the code and its -documentation under a license that permits other people to run, copy, -study, modify, and redistribute the code and which protects you from -having your work taken from you.) If you send a copy of your code to -the Free Software Foundation, and properly protect yourself and -others, it may be included in the next release of Emacs. In large -part, this is how Emacs has grown over the past years, by donations. - -@node let -@section @code{let} -@findex let - -The @code{let} expression is a special form in Lisp that you will need -to use in most function definitions. - -@code{let} is used to attach or bind a symbol to a value in such a way -that the Lisp interpreter will not confuse the variable with a -variable of the same name that is not part of the function. - -To understand why the @code{let} special form is necessary, consider -the situation in which you own a home that you generally refer to as -`the house', as in the sentence, ``The house needs painting.'' If you -are visiting a friend and your host refers to `the house', he is -likely to be referring to @emph{his} house, not yours, that is, to a -different house. - -If your friend is referring to his house and you think he is referring -to your house, you may be in for some confusion. The same thing could -happen in Lisp if a variable that is used inside of one function has -the same name as a variable that is used inside of another function, -and the two are not intended to refer to the same value. The -@code{let} special form prevents this kind of confusion. - -@menu -* Prevent confusion:: -* Parts of let Expression:: -* Sample let Expression:: -* Uninitialized let Variables:: -@end menu - -@ifnottex -@node Prevent confusion -@unnumberedsubsec @code{let} Prevents Confusion -@end ifnottex - -@cindex @samp{local variable} defined -@cindex @samp{variable, local}, defined -The @code{let} special form prevents confusion. @code{let} creates a -name for a @dfn{local variable} that overshadows any use of the same -name outside the @code{let} expression. This is like understanding -that whenever your host refers to `the house', he means his house, not -yours. (Symbols used in argument lists work the same way. -@xref{defun, , The @code{defun} Macro}.) - -Local variables created by a @code{let} expression retain their value -@emph{only} within the @code{let} expression itself (and within -expressions called within the @code{let} expression); the local -variables have no effect outside the @code{let} expression. - -Another way to think about @code{let} is that it is like a @code{setq} -that is temporary and local. The values set by @code{let} are -automatically undone when the @code{let} is finished. The setting -only affects expressions that are inside the bounds of the @code{let} -expression. In computer science jargon, we would say ``the binding of -a symbol is visible only in functions called in the @code{let} form; -in Emacs Lisp, scoping is dynamic, not lexical.'' - -@code{let} can create more than one variable at once. Also, -@code{let} gives each variable it creates an initial value, either a -value specified by you, or @code{nil}. (In the jargon, this is called -`binding the variable to the value'.) After @code{let} has created -and bound the variables, it executes the code in the body of the -@code{let}, and returns the value of the last expression in the body, -as the value of the whole @code{let} expression. (`Execute' is a jargon -term that means to evaluate a list; it comes from the use of the word -meaning `to give practical effect to' (@cite{Oxford English -Dictionary}). Since you evaluate an expression to perform an action, -`execute' has evolved as a synonym to `evaluate'.) - -@node Parts of let Expression -@subsection The Parts of a @code{let} Expression -@cindex @code{let} expression, parts of -@cindex Parts of @code{let} expression - -@cindex @samp{varlist} defined -A @code{let} expression is a list of three parts. The first part is -the symbol @code{let}. The second part is a list, called a -@dfn{varlist}, each element of which is either a symbol by itself or a -two-element list, the first element of which is a symbol. The third -part of the @code{let} expression is the body of the @code{let}. The -body usually consists of one or more lists. - -@need 800 -A template for a @code{let} expression looks like this: - -@smallexample -(let @var{varlist} @var{body}@dots{}) -@end smallexample - -@noindent -The symbols in the varlist are the variables that are given initial -values by the @code{let} special form. Symbols by themselves are given -the initial value of @code{nil}; and each symbol that is the first -element of a two-element list is bound to the value that is returned -when the Lisp interpreter evaluates the second element. - -Thus, a varlist might look like this: @code{(thread (needles 3))}. In -this case, in a @code{let} expression, Emacs binds the symbol -@code{thread} to an initial value of @code{nil}, and binds the symbol -@code{needles} to an initial value of 3. - -When you write a @code{let} expression, what you do is put the -appropriate expressions in the slots of the @code{let} expression -template. - -If the varlist is composed of two-element lists, as is often the case, -the template for the @code{let} expression looks like this: - -@smallexample -@group -(let ((@var{variable} @var{value}) - (@var{variable} @var{value}) - @dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -@node Sample let Expression -@subsection Sample @code{let} Expression -@cindex Sample @code{let} expression -@cindex @code{let} expression sample - -The following expression creates and gives initial values -to the two variables @code{zebra} and @code{tiger}. The body of the -@code{let} expression is a list which calls the @code{message} function. - -@smallexample -@group -(let ((zebra 'stripes) - (tiger 'fierce)) - (message "One kind of animal has %s and another is %s." - zebra tiger)) -@end group -@end smallexample - -Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. - -The two variables are @code{zebra} and @code{tiger}. Each variable is -the first element of a two-element list and each value is the second -element of its two-element list. In the varlist, Emacs binds the -variable @code{zebra} to the value @code{stripes}@footnote{According -to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras -become impossibly dangerous as they grow older'' but the claim here is -that they do not become fierce like a tiger. (1997, W. W. Norton and -Co., ISBN 0-393-03894-2, page 171)}, and binds the -variable @code{tiger} to the value @code{fierce}. In this example, -both values are symbols preceded by a quote. The values could just as -well have been another list or a string. The body of the @code{let} -follows after the list holding the variables. In this example, the -body is a list that uses the @code{message} function to print a string -in the echo area. - -@need 1500 -You may evaluate the example in the usual fashion, by placing the -cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do -this, the following will appear in the echo area: - -@smallexample -"One kind of animal has stripes and another is fierce." -@end smallexample - -As we have seen before, the @code{message} function prints its first -argument, except for @samp{%s}. In this example, the value of the variable -@code{zebra} is printed at the location of the first @samp{%s} and the -value of the variable @code{tiger} is printed at the location of the -second @samp{%s}. - -@node Uninitialized let Variables -@subsection Uninitialized Variables in a @code{let} Statement -@cindex Uninitialized @code{let} variables -@cindex @code{let} variables uninitialized - -If you do not bind the variables in a @code{let} statement to specific -initial values, they will automatically be bound to an initial value of -@code{nil}, as in the following expression: - -@smallexample -@group -(let ((birch 3) - pine - fir - (oak 'some)) - (message - "Here are %d variables with %s, %s, and %s value." - birch pine fir oak)) -@end group -@end smallexample - -@noindent -Here, the varlist is @code{((birch 3) pine fir (oak 'some))}. - -@need 1250 -If you evaluate this expression in the usual way, the following will -appear in your echo area: - -@smallexample -"Here are 3 variables with nil, nil, and some value." -@end smallexample - -@noindent -In this example, Emacs binds the symbol @code{birch} to the number 3, -binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds -the symbol @code{oak} to the value @code{some}. - -Note that in the first part of the @code{let}, the variables @code{pine} -and @code{fir} stand alone as atoms that are not surrounded by -parentheses; this is because they are being bound to @code{nil}, the -empty list. But @code{oak} is bound to @code{some} and so is a part of -the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the -number 3 and so is in a list with that number. (Since a number -evaluates to itself, the number does not need to be quoted. Also, the -number is printed in the message using a @samp{%d} rather than a -@samp{%s}.) The four variables as a group are put into a list to -delimit them from the body of the @code{let}. - -@node if -@section The @code{if} Special Form -@findex if -@cindex Conditional with @code{if} - -A third special form, in addition to @code{defun} and @code{let}, is the -conditional @code{if}. This form is used to instruct the computer to -make decisions. You can write function definitions without using -@code{if}, but it is used often enough, and is important enough, to be -included here. It is used, for example, in the code for the -function @code{beginning-of-buffer}. - -The basic idea behind an @code{if}, is that ``@emph{if} a test is true, -@emph{then} an expression is evaluated.'' If the test is not true, the -expression is not evaluated. For example, you might make a decision -such as, ``if it is warm and sunny, then go to the beach!'' - -@menu -* if in more detail:: -* type-of-animal in detail:: An example of an @code{if} expression. -@end menu - -@ifnottex -@node if in more detail -@unnumberedsubsec @code{if} in more detail -@end ifnottex - -@cindex @samp{if-part} defined -@cindex @samp{then-part} defined -An @code{if} expression written in Lisp does not use the word `then'; -the test and the action are the second and third elements of the list -whose first element is @code{if}. Nonetheless, the test part of an -@code{if} expression is often called the @dfn{if-part} and the second -argument is often called the @dfn{then-part}. - -Also, when an @code{if} expression is written, the true-or-false-test -is usually written on the same line as the symbol @code{if}, but the -action to carry out if the test is true, the ``then-part'', is written -on the second and subsequent lines. This makes the @code{if} -expression easier to read. - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-test-is-true}) -@end group -@end smallexample - -@noindent -The true-or-false-test will be an expression that -is evaluated by the Lisp interpreter. - -Here is an example that you can evaluate in the usual manner. The test -is whether the number 5 is greater than the number 4. Since it is, the -message @samp{5 is greater than 4!} will be printed. - -@smallexample -@group -(if (> 5 4) ; @r{if-part} - (message "5 is greater than 4!")) ; @r{then-part} -@end group -@end smallexample - -@noindent -(The function @code{>} tests whether its first argument is greater than -its second argument and returns true if it is.) -@findex > (greater than) - -Of course, in actual use, the test in an @code{if} expression will not -be fixed for all time as it is by the expression @code{(> 5 4)}. -Instead, at least one of the variables used in the test will be bound to -a value that is not known ahead of time. (If the value were known ahead -of time, we would not need to run the test!) - -For example, the value may be bound to an argument of a function -definition. In the following function definition, the character of the -animal is a value that is passed to the function. If the value bound to -@code{characteristic} is @code{fierce}, then the message, @samp{It's a -tiger!} will be printed; otherwise, @code{nil} will be returned. - -@smallexample -@group -(defun type-of-animal (characteristic) - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger." - (if (equal characteristic 'fierce) - (message "It's a tiger!"))) -@end group -@end smallexample - -@need 1500 -@noindent -If you are reading this inside of GNU Emacs, you can evaluate the -function definition in the usual way to install it in Emacs, and then you -can evaluate the following two expressions to see the results: - -@smallexample -@group -(type-of-animal 'fierce) - -(type-of-animal 'zebra) - -@end group -@end smallexample - -@c Following sentences rewritten to prevent overfull hbox. -@noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; and -when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil} -printed in the echo area. - -@node type-of-animal in detail -@subsection The @code{type-of-animal} Function in Detail - -Let's look at the @code{type-of-animal} function in detail. - -The function definition for @code{type-of-animal} was written by filling -the slots of two templates, one for a function definition as a whole, and -a second for an @code{if} expression. - -@need 1250 -The template for every function that is not interactive is: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - @var{body}@dots{}) -@end group -@end smallexample - -@need 800 -The parts of the function that match this template look like this: - -@smallexample -@group -(defun type-of-animal (characteristic) - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger." - @var{body: the} @code{if} @var{expression}) -@end group -@end smallexample - -The name of function is @code{type-of-animal}; it is passed the value -of one argument. The argument list is followed by a multi-line -documentation string. The documentation string is included in the -example because it is a good habit to write documentation string for -every function definition. The body of the function definition -consists of the @code{if} expression. - -@need 800 -The template for an @code{if} expression looks like this: - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-the-test-returns-true}) -@end group -@end smallexample - -@need 1250 -In the @code{type-of-animal} function, the code for the @code{if} -looks like this: - -@smallexample -@group -(if (equal characteristic 'fierce) - (message "It's a tiger!"))) -@end group -@end smallexample - -@need 800 -Here, the true-or-false-test is the expression: - -@smallexample -(equal characteristic 'fierce) -@end smallexample - -@noindent -In Lisp, @code{equal} is a function that determines whether its first -argument is equal to its second argument. The second argument is the -quoted symbol @code{'fierce} and the first argument is the value of the -symbol @code{characteristic}---in other words, the argument passed to -this function. - -In the first exercise of @code{type-of-animal}, the argument -@code{fierce} is passed to @code{type-of-animal}. Since @code{fierce} -is equal to @code{fierce}, the expression, @code{(equal characteristic -'fierce)}, returns a value of true. When this happens, the @code{if} -evaluates the second argument or then-part of the @code{if}: -@code{(message "It's tiger!")}. - -On the other hand, in the second exercise of @code{type-of-animal}, the -argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra} -is not equal to @code{fierce}, so the then-part is not evaluated and -@code{nil} is returned by the @code{if} expression. - -@node else -@section If--then--else Expressions -@cindex Else - -An @code{if} expression may have an optional third argument, called -the @dfn{else-part}, for the case when the true-or-false-test returns -false. When this happens, the second argument or then-part of the -overall @code{if} expression is @emph{not} evaluated, but the third or -else-part @emph{is} evaluated. You might think of this as the cloudy -day alternative for the decision ``if it is warm and sunny, then go to -the beach, else read a book!''. - -The word ``else'' is not written in the Lisp code; the else-part of an -@code{if} expression comes after the then-part. In the written Lisp, the -else-part is usually written to start on a line of its own and is -indented less than the then-part: - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-the-test-returns-true} - @var{action-to-carry-out-if-the-test-returns-false}) -@end group -@end smallexample - -For example, the following @code{if} expression prints the message @samp{4 -is not greater than 5!} when you evaluate it in the usual way: - -@smallexample -@group -(if (> 4 5) ; @r{if-part} - (message "4 falsely greater than 5!") ; @r{then-part} - (message "4 is not greater than 5!")) ; @r{else-part} -@end group -@end smallexample - -@noindent -Note that the different levels of indentation make it easy to -distinguish the then-part from the else-part. (GNU Emacs has several -commands that automatically indent @code{if} expressions correctly. -@xref{Typing Lists, , GNU Emacs Helps You Type Lists}.) - -We can extend the @code{type-of-animal} function to include an -else-part by simply incorporating an additional part to the @code{if} -expression. - -@need 1500 -You can see the consequences of doing this if you evaluate the following -version of the @code{type-of-animal} function definition to install it -and then evaluate the two subsequent expressions to pass different -arguments to the function. - -@smallexample -@group -(defun type-of-animal (characteristic) ; @r{Second version.} - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger; -else say it's not fierce." - (if (equal characteristic 'fierce) - (message "It's a tiger!") - (message "It's not fierce!"))) -@end group -@end smallexample -@sp 1 - -@smallexample -@group -(type-of-animal 'fierce) - -(type-of-animal 'zebra) - -@end group -@end smallexample - -@c Following sentence rewritten to prevent overfull hbox. -@noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; but -when you evaluate @code{(type-of-animal 'zebra)}, you will see -@code{"It's not fierce!"}. - -(Of course, if the @var{characteristic} were @code{ferocious}, the -message @code{"It's not fierce!"} would be printed; and it would be -misleading! When you write code, you need to take into account the -possibility that some such argument will be tested by the @code{if} -and write your program accordingly.) - -@node Truth & Falsehood -@section Truth and Falsehood in Emacs Lisp -@cindex Truth and falsehood in Emacs Lisp -@cindex Falsehood and truth in Emacs Lisp -@findex nil - -There is an important aspect to the truth test in an @code{if} -expression. So far, we have spoken of `true' and `false' as values of -predicates as if they were new kinds of Emacs Lisp objects. In fact, -`false' is just our old friend @code{nil}. Anything else---anything -at all---is `true'. - -The expression that tests for truth is interpreted as @dfn{true} -if the result of evaluating it is a value that is not @code{nil}. In -other words, the result of the test is considered true if the value -returned is a number such as 47, a string such as @code{"hello"}, or a -symbol (other than @code{nil}) such as @code{flowers}, or a list (so -long as it is not empty), or even a buffer! - -@menu -* nil explained:: @code{nil} has two meanings. -@end menu - -@ifnottex -@node nil explained -@unnumberedsubsec An explanation of @code{nil} -@end ifnottex - -Before illustrating a test for truth, we need an explanation of @code{nil}. - -In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the -empty list. Second, it means false and is the value returned when a -true-or-false-test tests false. @code{nil} can be written as an empty -list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is -concerned, @code{()} and @code{nil} are the same. Humans, however, tend -to use @code{nil} for false and @code{()} for the empty list. - -In Emacs Lisp, any value that is not @code{nil}---is not the empty -list---is considered true. This means that if an evaluation returns -something that is not an empty list, an @code{if} expression will test -true. For example, if a number is put in the slot for the test, it -will be evaluated and will return itself, since that is what numbers -do when evaluated. In this conditional, the @code{if} expression will -test true. The expression tests false only when @code{nil}, an empty -list, is returned by evaluating the expression. - -You can see this by evaluating the two expressions in the following examples. - -In the first example, the number 4 is evaluated as the test in the -@code{if} expression and returns itself; consequently, the then-part -of the expression is evaluated and returned: @samp{true} appears in -the echo area. In the second example, the @code{nil} indicates false; -consequently, the else-part of the expression is evaluated and -returned: @samp{false} appears in the echo area. - -@smallexample -@group -(if 4 - 'true - 'false) -@end group - -@group -(if nil - 'true - 'false) -@end group -@end smallexample - -@need 1250 -Incidentally, if some other useful value is not available for a test that -returns true, then the Lisp interpreter will return the symbol @code{t} -for true. For example, the expression @code{(> 5 4)} returns @code{t} -when evaluated, as you can see by evaluating it in the usual way: - -@smallexample -(> 5 4) -@end smallexample - -@need 1250 -@noindent -On the other hand, this function returns @code{nil} if the test is false. - -@smallexample -(> 4 5) -@end smallexample - -@node save-excursion -@section @code{save-excursion} -@findex save-excursion -@cindex Region, what it is -@cindex Preserving point, mark, and buffer -@cindex Point, mark, buffer preservation -@findex point -@findex mark - -The @code{save-excursion} function is the third and final special form -that we will discuss in this chapter. - -In Emacs Lisp programs used for editing, the @code{save-excursion} -function is very common. It saves the location of point and mark, -executes the body of the function, and then restores point and mark to -their previous positions if their locations were changed. Its primary -purpose is to keep the user from being surprised and disturbed by -unexpected movement of point or mark. - -@menu -* Point and mark:: A review of various locations. -* Template for save-excursion:: -@end menu - -@ifnottex -@node Point and mark -@unnumberedsubsec Point and Mark -@end ifnottex - -Before discussing @code{save-excursion}, however, it may be useful -first to review what point and mark are in GNU Emacs. @dfn{Point} is -the current location of the cursor. Wherever the cursor -is, that is point. More precisely, on terminals where the cursor -appears to be on top of a character, point is immediately before the -character. In Emacs Lisp, point is an integer. The first character in -a buffer is number one, the second is number two, and so on. The -function @code{point} returns the current position of the cursor as a -number. Each buffer has its own value for point. - -The @dfn{mark} is another position in the buffer; its value can be set -with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If -a mark has been set, you can use the command @kbd{C-x C-x} -(@code{exchange-point-and-mark}) to cause the cursor to jump to the mark -and set the mark to be the previous position of point. In addition, if -you set another mark, the position of the previous mark is saved in the -mark ring. Many mark positions can be saved this way. You can jump the -cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more -times. - -The part of the buffer between point and mark is called @dfn{the -region}. Numerous commands work on the region, including -@code{center-region}, @code{count-lines-region}, @code{kill-region}, and -@code{print-region}. - -The @code{save-excursion} special form saves the locations of point and -mark and restores those positions after the code within the body of the -special form is evaluated by the Lisp interpreter. Thus, if point were -in the beginning of a piece of text and some code moved point to the end -of the buffer, the @code{save-excursion} would put point back to where -it was before, after the expressions in the body of the function were -evaluated. - -In Emacs, a function frequently moves point as part of its internal -workings even though a user would not expect this. For example, -@code{count-lines-region} moves point. To prevent the user from being -bothered by jumps that are both unexpected and (from the user's point of -view) unnecessary, @code{save-excursion} is often used to keep point and -mark in the location expected by the user. The use of -@code{save-excursion} is good housekeeping. - -To make sure the house stays clean, @code{save-excursion} restores the -values of point and mark even if something goes wrong in the code inside -of it (or, to be more precise and to use the proper jargon, ``in case of -abnormal exit''). This feature is very helpful. - -In addition to recording the values of point and mark, -@code{save-excursion} keeps track of the current buffer, and restores -it, too. This means you can write code that will change the buffer and -have @code{save-excursion} switch you back to the original buffer. -This is how @code{save-excursion} is used in @code{append-to-buffer}. -(@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) - -@node Template for save-excursion -@subsection Template for a @code{save-excursion} Expression - -@need 800 -The template for code using @code{save-excursion} is simple: - -@smallexample -@group -(save-excursion - @var{body}@dots{}) -@end group -@end smallexample - -@noindent -The body of the function is one or more expressions that will be -evaluated in sequence by the Lisp interpreter. If there is more than -one expression in the body, the value of the last one will be returned -as the value of the @code{save-excursion} function. The other -expressions in the body are evaluated only for their side effects; and -@code{save-excursion} itself is used only for its side effect (which -is restoring the positions of point and mark). - -@need 1250 -In more detail, the template for a @code{save-excursion} expression -looks like this: - -@smallexample -@group -(save-excursion - @var{first-expression-in-body} - @var{second-expression-in-body} - @var{third-expression-in-body} - @dots{} - @var{last-expression-in-body}) -@end group -@end smallexample - -@noindent -An expression, of course, may be a symbol on its own or a list. - -In Emacs Lisp code, a @code{save-excursion} expression often occurs -within the body of a @code{let} expression. It looks like this: - -@smallexample -@group -(let @var{varlist} - (save-excursion - @var{body}@dots{})) -@end group -@end smallexample - -@node Review -@section Review - -In the last few chapters we have introduced a macro and a fair number -of functions and special forms. Here they are described in brief, -along with a few similar functions that have not been mentioned yet. - -@table @code -@item eval-last-sexp -Evaluate the last symbolic expression before the current location of -point. The value is printed in the echo area unless the function is -invoked with an argument; in that case, the output is printed in the -current buffer. This command is normally bound to @kbd{C-x C-e}. - -@item defun -Define function. This macro has up to five parts: the name, a -template for the arguments that will be passed to the function, -documentation, an optional interactive declaration, and the body of -the definition. - -@need 1250 -For example, in an early version of Emacs, the function definition was -as follows. (It is slightly more complex now that it seeks the first -non-whitespace character rather than the first visible character.) - -@smallexample -@group -(defun back-to-indentation () - "Move point to first visible character on line." - (interactive) - (beginning-of-line 1) - (skip-chars-forward " \t")) -@end group -@end smallexample - -@ignore -In GNU Emacs 22, - -(defun backward-to-indentation (&optional arg) - "Move backward ARG lines and position at first nonblank character." - (interactive "p") - (forward-line (- (or arg 1))) - (skip-chars-forward " \t")) - -(defun back-to-indentation () - "Move point to the first non-whitespace character on this line." - (interactive) - (beginning-of-line 1) - (skip-syntax-forward " " (line-end-position)) - ;; Move back over chars that have whitespace syntax but have the p flag. - (backward-prefix-chars)) -@end ignore - -@item interactive -Declare to the interpreter that the function can be used -interactively. This special form may be followed by a string with one -or more parts that pass the information to the arguments of the -function, in sequence. These parts may also tell the interpreter to -prompt for information. Parts of the string are separated by -newlines, @samp{\n}. - -@need 1000 -Common code characters are: - -@table @code -@item b -The name of an existing buffer. - -@item f -The name of an existing file. - -@item p -The numeric prefix argument. (Note that this `p' is lower case.) - -@item r -Point and the mark, as two numeric arguments, smallest first. This -is the only code letter that specifies two successive arguments -rather than one. -@end table - -@xref{Interactive Codes, , Code Characters for @samp{interactive}, -elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of -code characters. - -@item let -Declare that a list of variables is for use within the body of the -@code{let} and give them an initial value, either @code{nil} or a -specified value; then evaluate the rest of the expressions in the body -of the @code{let} and return the value of the last one. Inside the -body of the @code{let}, the Lisp interpreter does not see the values of -the variables of the same names that are bound outside of the -@code{let}. - -@need 1250 -For example, - -@smallexample -@group -(let ((foo (buffer-name)) - (bar (buffer-size))) - (message - "This buffer is %s and has %d characters." - foo bar)) -@end group -@end smallexample - -@item save-excursion -Record the values of point and mark and the current buffer before -evaluating the body of this special form. Restore the values of point -and mark and buffer afterward. - -@need 1250 -For example, - -@smallexample -@group -(message "We are %d characters into this buffer." - (- (point) - (save-excursion - (goto-char (point-min)) (point)))) -@end group -@end smallexample - -@item if -Evaluate the first argument to the function; if it is true, evaluate -the second argument; else evaluate the third argument, if there is one. - -The @code{if} special form is called a @dfn{conditional}. There are -other conditionals in Emacs Lisp, but @code{if} is perhaps the most -commonly used. - -@need 1250 -For example, - -@smallexample -@group -(if (= 22 emacs-major-version) - (message "This is version 22 Emacs") - (message "This is not version 22 Emacs")) -@end group -@end smallexample - -@need 1250 -@item < -@itemx > -@itemx <= -@itemx >= -The @code{<} function tests whether its first argument is smaller than -its second argument. A corresponding function, @code{>}, tests whether -the first argument is greater than the second. Likewise, @code{<=} -tests whether the first argument is less than or equal to the second and -@code{>=} tests whether the first argument is greater than or equal to -the second. In all cases, both arguments must be numbers or markers -(markers indicate positions in buffers). - -@need 800 -@item = -The @code{=} function tests whether two arguments, both numbers or -markers, are equal. - -@need 1250 -@item equal -@itemx eq -Test whether two objects are the same. @code{equal} uses one meaning -of the word `same' and @code{eq} uses another: @code{equal} returns -true if the two objects have a similar structure and contents, such as -two copies of the same book. On the other hand, @code{eq}, returns -true if both arguments are actually the same object. -@findex equal -@findex eq - -@need 1250 -@item string< -@itemx string-lessp -@itemx string= -@itemx string-equal -The @code{string-lessp} function tests whether its first argument is -smaller than the second argument. A shorter, alternative name for the -same function (a @code{defalias}) is @code{string<}. - -The arguments to @code{string-lessp} must be strings or symbols; the -ordering is lexicographic, so case is significant. The print names of -symbols are used instead of the symbols themselves. - -@cindex @samp{empty string} defined -An empty string, @samp{""}, a string with no characters in it, is -smaller than any string of characters. - -@code{string-equal} provides the corresponding test for equality. Its -shorter, alternative name is @code{string=}. There are no string test -functions that correspond to @var{>}, @code{>=}, or @code{<=}. - -@item message -Print a message in the echo area. The first argument is a string that -can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of -arguments that follow the string. The argument used by @samp{%s} must -be a string or a symbol; the argument used by @samp{%d} must be a -number. The argument used by @samp{%c} must be an @sc{ascii} code -number; it will be printed as the character with that @sc{ascii} code. -(Various other %-sequences have not been mentioned.) - -@item setq -@itemx set -The @code{setq} function sets the value of its first argument to the -value of the second argument. The first argument is automatically -quoted by @code{setq}. It does the same for succeeding pairs of -arguments. Another function, @code{set}, takes only two arguments and -evaluates both of them before setting the value returned by its first -argument to the value returned by its second argument. - -@item buffer-name -Without an argument, return the name of the buffer, as a string. - -@item buffer-file-name -Without an argument, return the name of the file the buffer is -visiting. - -@item current-buffer -Return the buffer in which Emacs is active; it may not be -the buffer that is visible on the screen. - -@item other-buffer -Return the most recently selected buffer (other than the buffer passed -to @code{other-buffer} as an argument and other than the current -buffer). - -@item switch-to-buffer -Select a buffer for Emacs to be active in and display it in the current -window so users can look at it. Usually bound to @kbd{C-x b}. - -@item set-buffer -Switch Emacs's attention to a buffer on which programs will run. Don't -alter what the window is showing. - -@item buffer-size -Return the number of characters in the current buffer. - -@item point -Return the value of the current position of the cursor, as an -integer counting the number of characters from the beginning of the -buffer. - -@item point-min -Return the minimum permissible value of point in -the current buffer. This is 1, unless narrowing is in effect. - -@item point-max -Return the value of the maximum permissible value of point in the -current buffer. This is the end of the buffer, unless narrowing is in -effect. -@end table - -@need 1500 -@node defun Exercises -@section Exercises - -@itemize @bullet -@item -Write a non-interactive function that doubles the value of its -argument, a number. Make that function interactive. - -@item -Write a function that tests whether the current value of -@code{fill-column} is greater than the argument passed to the function, -and if so, prints an appropriate message. -@end itemize - -@node Buffer Walk Through -@chapter A Few Buffer--Related Functions - -In this chapter we study in detail several of the functions used in GNU -Emacs. This is called a ``walk-through''. These functions are used as -examples of Lisp code, but are not imaginary examples; with the -exception of the first, simplified function definition, these functions -show the actual code used in GNU Emacs. You can learn a great deal from -these definitions. The functions described here are all related to -buffers. Later, we will study other functions. - -@menu -* Finding More:: How to find more information. -* simplified-beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. -* append-to-buffer:: Uses @code{save-excursion} and - @code{insert-buffer-substring}. -* Buffer Related Review:: Review. -* Buffer Exercises:: -@end menu - -@node Finding More -@section Finding More Information - -@findex describe-function, @r{introduced} -@cindex Find function documentation -In this walk-through, I will describe each new function as we come to -it, sometimes in detail and sometimes briefly. If you are interested, -you can get the full documentation of any Emacs Lisp function at any -time by typing @kbd{C-h f} and then the name of the function (and then -@key{RET}). Similarly, you can get the full documentation for a -variable by typing @kbd{C-h v} and then the name of the variable (and -then @key{RET}). - -@cindex Find source of function -@c In version 22, tells location both of C and of Emacs Lisp -Also, @code{describe-function} will tell you the location of the -function definition. - -Put point into the name of the file that contains the function and -press the @key{RET} key. In this case, @key{RET} means -@code{push-button} rather than `return' or `enter'. Emacs will take -you directly to the function definition. - -@ignore -Not In version 22 - -If you move point over the file name and press -the @key{RET} key, which in this case means @code{help-follow} rather -than `return' or `enter', Emacs will take you directly to the function -definition. -@end ignore - -More generally, if you want to see a function in its original source -file, you can use the @code{find-tag} function to jump to it. -@code{find-tag} works with a wide variety of languages, not just -Lisp, and C, and it works with non-programming text as well. For -example, @code{find-tag} will jump to the various nodes in the -Texinfo source file of this document. -The @code{find-tag} function depends on `tags tables' that record -the locations of the functions, variables, and other items to which -@code{find-tag} jumps. - -To use the @code{find-tag} command, type @kbd{M-.} (i.e., press the -period key while holding down the @key{META} key, or else type the -@key{ESC} key and then type the period key), and then, at the prompt, -type in the name of the function whose source code you want to see, -such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will -switch buffers and display the source code for the function on your -screen. To switch back to your current buffer, type @kbd{C-x b -@key{RET}}. (On some keyboards, the @key{META} key is labeled -@key{ALT}.) - -@c !!! 22.1.1 tags table location in this paragraph -@cindex TAGS table, specifying -@findex find-tag -Depending on how the initial default values of your copy of Emacs are -set, you may also need to specify the location of your `tags table', -which is a file called @file{TAGS}. For example, if you are -interested in Emacs sources, the tags table you will most likely want, -if it has already been created for you, will be in a subdirectory of -the @file{/usr/local/share/emacs/} directory; thus you would use the -@code{M-x visit-tags-table} command and specify a pathname such as -@file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table -has not already been created, you will have to create it yourself. It -will be in a file such as @file{/usr/local/src/emacs/src/TAGS}. - -@need 1250 -To create a @file{TAGS} file in a specific directory, switch to that -directory in Emacs using @kbd{M-x cd} command, or list the directory -with @kbd{C-x d} (@code{dired}). Then run the compile command, with -@w{@code{etags *.el}} as the command to execute: - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -For more information, see @ref{etags, , Create Your Own @file{TAGS} File}. - -After you become more familiar with Emacs Lisp, you will find that you will -frequently use @code{find-tag} to navigate your way around source code; -and you will create your own @file{TAGS} tables. - -@cindex Library, as term for `file' -Incidentally, the files that contain Lisp code are conventionally -called @dfn{libraries}. The metaphor is derived from that of a -specialized library, such as a law library or an engineering library, -rather than a general library. Each library, or file, contains -functions that relate to a particular topic or activity, such as -@file{abbrev.el} for handling abbreviations and other typing -shortcuts, and @file{help.el} for help. (Sometimes several -libraries provide code for a single activity, as the various -@file{rmail@dots{}} files provide code for reading electronic mail.) -In @cite{The GNU Emacs Manual}, you will see sentences such as ``The -@kbd{C-h p} command lets you search the standard Emacs Lisp libraries -by topic keywords.'' - -@node simplified-beginning-of-buffer -@section A Simplified @code{beginning-of-buffer} Definition -@findex simplified-beginning-of-buffer - -The @code{beginning-of-buffer} command is a good function to start with -since you are likely to be familiar with it and it is easy to -understand. Used as an interactive command, @code{beginning-of-buffer} -moves the cursor to the beginning of the buffer, leaving the mark at the -previous position. It is generally bound to @kbd{M-<}. - -In this section, we will discuss a shortened version of the function -that shows how it is most frequently used. This shortened function -works as written, but it does not contain the code for a complex option. -In another section, we will describe the entire function. -(@xref{beginning-of-buffer, , Complete Definition of -@code{beginning-of-buffer}}.) - -Before looking at the code, let's consider what the function -definition has to contain: it must include an expression that makes -the function interactive so it can be called by typing @kbd{M-x -beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it -must include code to leave a mark at the original position in the -buffer; and it must include code to move the cursor to the beginning -of the buffer. - -@need 1250 -Here is the complete text of the shortened version of the function: - -@smallexample -@group -(defun simplified-beginning-of-buffer () - "Move point to the beginning of the buffer; -leave mark at previous position." - (interactive) - (push-mark) - (goto-char (point-min))) -@end group -@end smallexample - -Like all function definitions, this definition has five parts following -the macro @code{defun}: - -@enumerate -@item -The name: in this example, @code{simplified-beginning-of-buffer}. - -@item -A list of the arguments: in this example, an empty list, @code{()}, - -@item -The documentation string. - -@item -The interactive expression. - -@item -The body. -@end enumerate - -@noindent -In this function definition, the argument list is empty; this means that -this function does not require any arguments. (When we look at the -definition for the complete function, we will see that it may be passed -an optional argument.) - -The interactive expression tells Emacs that the function is intended to -be used interactively. In this example, @code{interactive} does not have -an argument because @code{simplified-beginning-of-buffer} does not -require one. - -@need 800 -The body of the function consists of the two lines: - -@smallexample -@group -(push-mark) -(goto-char (point-min)) -@end group -@end smallexample - -The first of these lines is the expression, @code{(push-mark)}. When -this expression is evaluated by the Lisp interpreter, it sets a mark at -the current position of the cursor, wherever that may be. The position -of this mark is saved in the mark ring. - -The next line is @code{(goto-char (point-min))}. This expression -jumps the cursor to the minimum point in the buffer, that is, to the -beginning of the buffer (or to the beginning of the accessible portion -of the buffer if it is narrowed. @xref{Narrowing & Widening, , -Narrowing and Widening}.) - -The @code{push-mark} command sets a mark at the place where the cursor -was located before it was moved to the beginning of the buffer by the -@code{(goto-char (point-min))} expression. Consequently, you can, if -you wish, go back to where you were originally by typing @kbd{C-x C-x}. - -That is all there is to the function definition! - -@findex describe-function -When you are reading code such as this and come upon an unfamiliar -function, such as @code{goto-char}, you can find out what it does by -using the @code{describe-function} command. To use this command, type -@kbd{C-h f} and then type in the name of the function and press -@key{RET}. The @code{describe-function} command will print the -function's documentation string in a @file{*Help*} window. For -example, the documentation for @code{goto-char} is: - -@smallexample -@group -Set point to POSITION, a number or marker. -Beginning of buffer is position (point-min), end is (point-max). -@end group -@end smallexample - -@noindent -The function's one argument is the desired position. - -@noindent -(The prompt for @code{describe-function} will offer you the symbol -under or preceding the cursor, so you can save typing by positioning -the cursor right over or after the function and then typing @kbd{C-h f -@key{RET}}.) - -The @code{end-of-buffer} function definition is written in the same way as -the @code{beginning-of-buffer} definition except that the body of the -function contains the expression @code{(goto-char (point-max))} in place -of @code{(goto-char (point-min))}. - -@node mark-whole-buffer -@section The Definition of @code{mark-whole-buffer} -@findex mark-whole-buffer - -The @code{mark-whole-buffer} function is no harder to understand than the -@code{simplified-beginning-of-buffer} function. In this case, however, -we will look at the complete function, not a shortened version. - -The @code{mark-whole-buffer} function is not as commonly used as the -@code{beginning-of-buffer} function, but is useful nonetheless: it -marks a whole buffer as a region by putting point at the beginning and -a mark at the end of the buffer. It is generally bound to @kbd{C-x -h}. - -@menu -* mark-whole-buffer overview:: -* Body of mark-whole-buffer:: Only three lines of code. -@end menu - -@ifnottex -@node mark-whole-buffer overview -@unnumberedsubsec An overview of @code{mark-whole-buffer} -@end ifnottex - -@need 1250 -In GNU Emacs 22, the code for the complete function looks like this: - -@smallexample -@group -(defun mark-whole-buffer () - "Put point at beginning and mark at end of buffer. -You probably should not use this function in Lisp programs; -it is usually a mistake for a Lisp function to use any subroutine -that uses or sets the mark." - (interactive) - (push-mark (point)) - (push-mark (point-max) nil t) - (goto-char (point-min))) -@end group -@end smallexample - -@need 1250 -Like all other functions, the @code{mark-whole-buffer} function fits -into the template for a function definition. The template looks like -this: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -Here is how the function works: the name of the function is -@code{mark-whole-buffer}; it is followed by an empty argument list, -@samp{()}, which means that the function does not require arguments. -The documentation comes next. - -The next line is an @code{(interactive)} expression that tells Emacs -that the function will be used interactively. These details are similar -to the @code{simplified-beginning-of-buffer} function described in the -previous section. - -@need 1250 -@node Body of mark-whole-buffer -@subsection Body of @code{mark-whole-buffer} - -The body of the @code{mark-whole-buffer} function consists of three -lines of code: - -@c GNU Emacs 22 -@smallexample -@group -(push-mark (point)) -(push-mark (point-max) nil t) -(goto-char (point-min)) -@end group -@end smallexample - -The first of these lines is the expression, @code{(push-mark (point))}. - -This line does exactly the same job as the first line of the body of -the @code{simplified-beginning-of-buffer} function, which is written -@code{(push-mark)}. In both cases, the Lisp interpreter sets a mark -at the current position of the cursor. - -I don't know why the expression in @code{mark-whole-buffer} is written -@code{(push-mark (point))} and the expression in -@code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps -whoever wrote the code did not know that the arguments for -@code{push-mark} are optional and that if @code{push-mark} is not -passed an argument, the function automatically sets mark at the -location of point by default. Or perhaps the expression was written -so as to parallel the structure of the next line. In any case, the -line causes Emacs to determine the position of point and set a mark -there. - -In earlier versions of GNU Emacs, the next line of -@code{mark-whole-buffer} was @code{(push-mark (point-max))}. This -expression sets a mark at the point in the buffer that has the highest -number. This will be the end of the buffer (or, if the buffer is -narrowed, the end of the accessible portion of the buffer. -@xref{Narrowing & Widening, , Narrowing and Widening}, for more about -narrowing.) After this mark has been set, the previous mark, the one -set at point, is no longer set, but Emacs remembers its position, just -as all other recent marks are always remembered. This means that you -can, if you wish, go back to that position by typing @kbd{C-u -C-@key{SPC}} twice. - -@need 1250 -In GNU Emacs 22, the @code{(point-max)} is slightly more complicated. -The line reads - -@smallexample -(push-mark (point-max) nil t) -@end smallexample - -@noindent -The expression works nearly the same as before. It sets a mark at the -highest numbered place in the buffer that it can. However, in this -version, @code{push-mark} has two additional arguments. The second -argument to @code{push-mark} is @code{nil}. This tells the function -it @emph{should} display a message that says `Mark set' when it pushes -the mark. The third argument is @code{t}. This tells -@code{push-mark} to activate the mark when Transient Mark mode is -turned on. Transient Mark mode highlights the currently active -region. It is often turned off. - -Finally, the last line of the function is @code{(goto-char -(point-min)))}. This is written exactly the same way as it is written -in @code{beginning-of-buffer}. The expression moves the cursor to -the minimum point in the buffer, that is, to the beginning of the buffer -(or to the beginning of the accessible portion of the buffer). As a -result of this, point is placed at the beginning of the buffer and mark -is set at the end of the buffer. The whole buffer is, therefore, the -region. - -@node append-to-buffer -@section The Definition of @code{append-to-buffer} -@findex append-to-buffer - -The @code{append-to-buffer} command is more complex than the -@code{mark-whole-buffer} command. What it does is copy the region -(that is, the part of the buffer between point and mark) from the -current buffer to a specified buffer. - -@menu -* append-to-buffer overview:: -* append interactive:: A two part interactive expression. -* append-to-buffer body:: Incorporates a @code{let} expression. -* append save-excursion:: How the @code{save-excursion} works. -@end menu - -@ifnottex -@node append-to-buffer overview -@unnumberedsubsec An Overview of @code{append-to-buffer} -@end ifnottex - -@findex insert-buffer-substring -The @code{append-to-buffer} command uses the -@code{insert-buffer-substring} function to copy the region. -@code{insert-buffer-substring} is described by its name: it takes a -string of characters from part of a buffer, a ``substring'', and -inserts them into another buffer. - -Most of @code{append-to-buffer} is -concerned with setting up the conditions for -@code{insert-buffer-substring} to work: the code must specify both the -buffer to which the text will go, the window it comes from and goes -to, and the region that will be copied. - -@need 1250 -Here is the complete text of the function: - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. -@end group - -@group -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer - (current-buffer) t)) - (region-beginning) (region-end))) -@end group -@group - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end group -@end smallexample - -The function can be understood by looking at it as a series of -filled-in templates. - -The outermost template is for the function definition. In this -function, it looks like this (with several slots filled in): - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "@var{documentation}@dots{}" - (interactive @dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -The first line of the function includes its name and three arguments. -The arguments are the @code{buffer} to which the text will be copied, and -the @code{start} and @code{end} of the region in the current buffer that -will be copied. - -The next part of the function is the documentation, which is clear and -complete. As is conventional, the three arguments are written in -upper case so you will notice them easily. Even better, they are -described in the same order as in the argument list. - -Note that the documentation distinguishes between a buffer and its -name. (The function can handle either.) - -@node append interactive -@subsection The @code{append-to-buffer} Interactive Expression - -Since the @code{append-to-buffer} function will be used interactively, -the function must have an @code{interactive} expression. (For a -review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: - -@smallexample -@group -(interactive - (list (read-buffer - "Append to buffer: " - (other-buffer (current-buffer) t)) - (region-beginning) - (region-end))) -@end group -@end smallexample - -@noindent -This expression is not one with letters standing for parts, as -described earlier. Instead, it starts a list with these parts: - -The first part of the list is an expression to read the name of a -buffer and return it as a string. That is @code{read-buffer}. The -function requires a prompt as its first argument, @samp{"Append to -buffer: "}. Its second argument tells the command what value to -provide if you don't specify anything. - -In this case that second argument is an expression containing the -function @code{other-buffer}, an exception, and a @samp{t}, standing -for true. - -The first argument to @code{other-buffer}, the exception, is yet -another function, @code{current-buffer}. That is not going to be -returned. The second argument is the symbol for true, @code{t}. that -tells @code{other-buffer} that it may show visible buffers (except in -this case, it will not show the current buffer, which makes sense). - -@need 1250 -The expression looks like this: - -@smallexample -(other-buffer (current-buffer) t) -@end smallexample - -The second and third arguments to the @code{list} expression are -@code{(region-beginning)} and @code{(region-end)}. These two -functions specify the beginning and end of the text to be appended. - -@need 1250 -Originally, the command used the letters @samp{B} and @samp{r}. -The whole @code{interactive} expression looked like this: - -@smallexample -(interactive "BAppend to buffer:@: \nr") -@end smallexample - -@noindent -But when that was done, the default value of the buffer switched to -was invisible. That was not wanted. - -(The prompt was separated from the second argument with a newline, -@samp{\n}. It was followed by an @samp{r} that told Emacs to bind the -two arguments that follow the symbol @code{buffer} in the function's -argument list (that is, @code{start} and @code{end}) to the values of -point and mark. That argument worked fine.) - -@node append-to-buffer body -@subsection The Body of @code{append-to-buffer} - -@ignore -in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el - -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. - -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) - (region-beginning) (region-end))) - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - -The body of the @code{append-to-buffer} function begins with @code{let}. - -As we have seen before (@pxref{let, , @code{let}}), the purpose of a -@code{let} expression is to create and give initial values to one or -more variables that will only be used within the body of the -@code{let}. This means that such a variable will not be confused with -any variable of the same name outside the @code{let} expression. - -We can see how the @code{let} expression fits into the function as a -whole by showing a template for @code{append-to-buffer} with the -@code{let} expression in outline: - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "@var{documentation}@dots{}" - (interactive @dots{}) - (let ((@var{variable} @var{value})) - @var{body}@dots{}) -@end group -@end smallexample - -The @code{let} expression has three elements: - -@enumerate -@item -The symbol @code{let}; - -@item -A varlist containing, in this case, a single two-element list, -@code{(@var{variable} @var{value})}; - -@item -The body of the @code{let} expression. -@end enumerate - -@need 800 -In the @code{append-to-buffer} function, the varlist looks like this: - -@smallexample -(oldbuf (current-buffer)) -@end smallexample - -@noindent -In this part of the @code{let} expression, the one variable, -@code{oldbuf}, is bound to the value returned by the -@code{(current-buffer)} expression. The variable, @code{oldbuf}, is -used to keep track of the buffer in which you are working and from -which you will copy. - -The element or elements of a varlist are surrounded by a set of -parentheses so the Lisp interpreter can distinguish the varlist from -the body of the @code{let}. As a consequence, the two-element list -within the varlist is surrounded by a circumscribing set of parentheses. -The line looks like this: - -@smallexample -@group -(let ((oldbuf (current-buffer))) - @dots{} ) -@end group -@end smallexample - -@noindent -The two parentheses before @code{oldbuf} might surprise you if you did -not realize that the first parenthesis before @code{oldbuf} marks the -boundary of the varlist and the second parenthesis marks the beginning -of the two-element list, @code{(oldbuf (current-buffer))}. - -@node append save-excursion -@subsection @code{save-excursion} in @code{append-to-buffer} - -The body of the @code{let} expression in @code{append-to-buffer} -consists of a @code{save-excursion} expression. - -The @code{save-excursion} function saves the locations of point and -mark, and restores them to those positions after the expressions in the -body of the @code{save-excursion} complete execution. In addition, -@code{save-excursion} keeps track of the original buffer, and -restores it. This is how @code{save-excursion} is used in -@code{append-to-buffer}. - -@need 1500 -@cindex Indentation for formatting -@cindex Formatting convention -Incidentally, it is worth noting here that a Lisp function is normally -formatted so that everything that is enclosed in a multi-line spread is -indented more to the right than the first symbol. In this function -definition, the @code{let} is indented more than the @code{defun}, and -the @code{save-excursion} is indented more than the @code{let}, like -this: - -@smallexample -@group -(defun @dots{} - @dots{} - @dots{} - (let@dots{} - (save-excursion - @dots{} -@end group -@end smallexample - -@need 1500 -@noindent -This formatting convention makes it easy to see that the lines in -the body of the @code{save-excursion} are enclosed by the parentheses -associated with @code{save-excursion}, just as the -@code{save-excursion} itself is enclosed by the parentheses associated -with the @code{let}: - -@smallexample -@group -(let ((oldbuf (current-buffer))) - (save-excursion - @dots{} - (set-buffer @dots{}) - (insert-buffer-substring oldbuf start end) - @dots{})) -@end group -@end smallexample - -@need 1200 -The use of the @code{save-excursion} function can be viewed as a process -of filling in the slots of a template: - -@smallexample -@group -(save-excursion - @var{first-expression-in-body} - @var{second-expression-in-body} - @dots{} - @var{last-expression-in-body}) -@end group -@end smallexample - -@need 1200 -@noindent -In this function, the body of the @code{save-excursion} contains only -one expression, the @code{let*} expression. You know about a -@code{let} function. The @code{let*} function is different. It has a -@samp{*} in its name. It enables Emacs to set each variable in its -varlist in sequence, one after another. - -Its critical feature is that variables later in the varlist can make -use of the values to which Emacs set variables earlier in the varlist. -@xref{fwd-para let, , The @code{let*} expression}. - -We will skip functions like @code{let*} and focus on two: the -@code{set-buffer} function and the @code{insert-buffer-substring} -function. - -@need 1250 -In the old days, the @code{set-buffer} expression was simply - -@smallexample -(set-buffer (get-buffer-create buffer)) -@end smallexample - -@need 1250 -@noindent -but now it is - -@smallexample -(set-buffer append-to) -@end smallexample - -@noindent -@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier -on in the @code{let*} expression. That extra binding would not be -necessary except for that @code{append-to} is used later in the -varlist as an argument to @code{get-buffer-window-list}. - -@ignore -in GNU Emacs 22 - - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - -The @code{append-to-buffer} function definition inserts text from the -buffer in which you are currently to a named buffer. It happens that -@code{insert-buffer-substring} copies text from another buffer to the -current buffer, just the reverse---that is why the -@code{append-to-buffer} definition starts out with a @code{let} that -binds the local symbol @code{oldbuf} to the value returned by -@code{current-buffer}. - -@need 1250 -The @code{insert-buffer-substring} expression looks like this: - -@smallexample -(insert-buffer-substring oldbuf start end) -@end smallexample - -@noindent -The @code{insert-buffer-substring} function copies a string -@emph{from} the buffer specified as its first argument and inserts the -string into the present buffer. In this case, the argument to -@code{insert-buffer-substring} is the value of the variable created -and bound by the @code{let}, namely the value of @code{oldbuf}, which -was the current buffer when you gave the @code{append-to-buffer} -command. - -After @code{insert-buffer-substring} has done its work, -@code{save-excursion} will restore the action to the original buffer -and @code{append-to-buffer} will have done its job. - -@need 800 -Written in skeletal form, the workings of the body look like this: - -@smallexample -@group -(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) - (save-excursion ; @r{Keep track of buffer.} - @var{change-buffer} - @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}) - - @var{change-back-to-original-buffer-when-finished} -@var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished} -@end group -@end smallexample - -In summary, @code{append-to-buffer} works as follows: it saves the -value of the current buffer in the variable called @code{oldbuf}. It -gets the new buffer (creating one if need be) and switches Emacs's -attention to it. Using the value of @code{oldbuf}, it inserts the -region of text from the old buffer into the new buffer; and then using -@code{save-excursion}, it brings you back to your original buffer. - -In looking at @code{append-to-buffer}, you have explored a fairly -complex function. It shows how to use @code{let} and -@code{save-excursion}, and how to change to and come back from another -buffer. Many function definitions use @code{let}, -@code{save-excursion}, and @code{set-buffer} this way. - -@node Buffer Related Review -@section Review - -Here is a brief summary of the various functions discussed in this chapter. - -@table @code -@item describe-function -@itemx describe-variable -Print the documentation for a function or variable. -Conventionally bound to @kbd{C-h f} and @kbd{C-h v}. - -@item find-tag -Find the file containing the source for a function or variable and -switch buffers to it, positioning point at the beginning of the item. -Conventionally bound to @kbd{M-.} (that's a period following the -@key{META} key). - -@item save-excursion -Save the location of point and mark and restore their values after the -arguments to @code{save-excursion} have been evaluated. Also, remember -the current buffer and return to it. - -@item push-mark -Set mark at a location and record the value of the previous mark on the -mark ring. The mark is a location in the buffer that will keep its -relative position even if text is added to or removed from the buffer. - -@item goto-char -Set point to the location specified by the value of the argument, which -can be a number, a marker, or an expression that returns the number of -a position, such as @code{(point-min)}. - -@item insert-buffer-substring -Copy a region of text from a buffer that is passed to the function as -an argument and insert the region into the current buffer. - -@item mark-whole-buffer -Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. - -@item set-buffer -Switch the attention of Emacs to another buffer, but do not change the -window being displayed. Used when the program rather than a human is -to work on a different buffer. - -@item get-buffer-create -@itemx get-buffer -Find a named buffer or create one if a buffer of that name does not -exist. The @code{get-buffer} function returns @code{nil} if the named -buffer does not exist. -@end table - -@need 1500 -@node Buffer Exercises -@section Exercises - -@itemize @bullet -@item -Write your own @code{simplified-end-of-buffer} function definition; -then test it to see whether it works. - -@item -Use @code{if} and @code{get-buffer} to write a function that prints a -message telling you whether a buffer exists. - -@item -Using @code{find-tag}, find the source for the @code{copy-to-buffer} -function. -@end itemize - -@node More Complex -@chapter A Few More Complex Functions - -In this chapter, we build on what we have learned in previous chapters -by looking at more complex functions. The @code{copy-to-buffer} -function illustrates use of two @code{save-excursion} expressions in -one definition, while the @code{insert-buffer} function illustrates -use of an asterisk in an @code{interactive} expression, use of -@code{or}, and the important distinction between a name and the object -to which the name refers. - -@menu -* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. -* insert-buffer:: Read-only, and with @code{or}. -* beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* Second Buffer Related Review:: -* optional Exercise:: -@end menu - -@node copy-to-buffer -@section The Definition of @code{copy-to-buffer} -@findex copy-to-buffer - -After understanding how @code{append-to-buffer} works, it is easy to -understand @code{copy-to-buffer}. This function copies text into a -buffer, but instead of adding to the second buffer, it replaces all the -previous text in the second buffer. - -@need 800 -The body of @code{copy-to-buffer} looks like this, - -@smallexample -@group -@dots{} -(interactive "BCopy to buffer: \nr") -(let ((oldbuf (current-buffer))) - (with-current-buffer (get-buffer-create buffer) - (barf-if-buffer-read-only) - (erase-buffer) - (save-excursion - (insert-buffer-substring oldbuf start end))))) -@end group -@end smallexample - -The @code{copy-to-buffer} function has a simpler @code{interactive} -expression than @code{append-to-buffer}. - -@need 800 -The definition then says - -@smallexample -(with-current-buffer (get-buffer-create buffer) @dots{} -@end smallexample - -First, look at the earliest inner expression; that is evaluated first. -That expression starts with @code{get-buffer-create buffer}. The -function tells the computer to use the buffer with the name specified -as the one to which you are copying, or if such a buffer does not -exist, to create it. Then, the @code{with-current-buffer} function -evaluates its body with that buffer temporarily current. - -(This demonstrates another way to shift the computer's attention but -not the user's. The @code{append-to-buffer} function showed how to do -the same with @code{save-excursion} and @code{set-buffer}. -@code{with-current-buffer} is a newer, and arguably easier, -mechanism.) - -The @code{barf-if-buffer-read-only} function sends you an error -message saying the buffer is read-only if you cannot modify it. - -The next line has the @code{erase-buffer} function as its sole -contents. That function erases the buffer. - -Finally, the last two lines contain the @code{save-excursion} -expression with @code{insert-buffer-substring} as its body. -The @code{insert-buffer-substring} expression copies the text from -the buffer you are in (and you have not seen the computer shift its -attention, so you don't know that that buffer is now called -@code{oldbuf}). - -Incidentally, this is what is meant by `replacement'. To replace text, -Emacs erases the previous text and then inserts new text. - -@need 1250 -In outline, the body of @code{copy-to-buffer} looks like this: - -@smallexample -@group -(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) - (@var{with-the-buffer-you-are-copying-to} - (@var{but-do-not-erase-or-copy-to-a-read-only-buffer}) - (erase-buffer) - (save-excursion - @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}))) -@end group -@end smallexample - -@node insert-buffer -@section The Definition of @code{insert-buffer} -@findex insert-buffer - -@code{insert-buffer} is yet another buffer-related function. This -command copies another buffer @emph{into} the current buffer. It is the -reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they -copy a region of text @emph{from} the current buffer to another buffer. - -Here is a discussion based on the original code. The code was -simplified in 2003 and is harder to understand. - -(@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see -a discussion of the new body.) - -In addition, this code illustrates the use of @code{interactive} with a -buffer that might be @dfn{read-only} and the important distinction -between the name of an object and the object actually referred to. - -@menu -* insert-buffer code:: -* insert-buffer interactive:: When you can read, but not write. -* insert-buffer body:: The body has an @code{or} and a @code{let}. -* if & or:: Using an @code{if} instead of an @code{or}. -* Insert or:: How the @code{or} expression works. -* Insert let:: Two @code{save-excursion} expressions. -* New insert-buffer:: -@end menu - -@ifnottex -@node insert-buffer code -@unnumberedsubsec The Code for @code{insert-buffer} -@end ifnottex - -@need 800 -Here is the earlier code: - -@smallexample -@group -(defun insert-buffer (buffer) - "Insert after point the contents of BUFFER. -Puts mark after the inserted text. -BUFFER may be a buffer or a buffer name." - (interactive "*bInsert buffer:@: ") -@end group -@group - (or (bufferp buffer) - (setq buffer (get-buffer buffer))) - (let (start end newmark) - (save-excursion - (save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) -@end group -@group - (insert-buffer-substring buffer start end) - (setq newmark (point))) - (push-mark newmark))) -@end group -@end smallexample - -@need 1200 -As with other function definitions, you can use a template to see an -outline of the function: - -@smallexample -@group -(defun insert-buffer (buffer) - "@var{documentation}@dots{}" - (interactive "*bInsert buffer:@: ") - @var{body}@dots{}) -@end group -@end smallexample - -@node insert-buffer interactive -@subsection The Interactive Expression in @code{insert-buffer} -@findex interactive, @r{example use of} - -In @code{insert-buffer}, the argument to the @code{interactive} -declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert -buffer:@: }. - -@menu -* Read-only buffer:: When a buffer cannot be modified. -* b for interactive:: An existing buffer or else its name. -@end menu - -@node Read-only buffer -@unnumberedsubsubsec A Read-only Buffer -@cindex Read-only buffer -@cindex Asterisk for read-only buffer -@findex * @r{for read-only buffer} - -The asterisk is for the situation when the current buffer is a -read-only buffer---a buffer that cannot be modified. If -@code{insert-buffer} is called when the current buffer is read-only, a -message to this effect is printed in the echo area and the terminal -may beep or blink at you; you will not be permitted to insert anything -into current buffer. The asterisk does not need to be followed by a -newline to separate it from the next argument. - -@node b for interactive -@unnumberedsubsubsec @samp{b} in an Interactive Expression - -The next argument in the interactive expression starts with a lower -case @samp{b}. (This is different from the code for -@code{append-to-buffer}, which uses an upper-case @samp{B}. -@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) -The lower-case @samp{b} tells the Lisp interpreter that the argument -for @code{insert-buffer} should be an existing buffer or else its -name. (The upper-case @samp{B} option provides for the possibility -that the buffer does not exist.) Emacs will prompt you for the name -of the buffer, offering you a default buffer, with name completion -enabled. If the buffer does not exist, you receive a message that -says ``No match''; your terminal may beep at you as well. - -The new and simplified code generates a list for @code{interactive}. -It uses the @code{barf-if-buffer-read-only} and @code{read-buffer} -functions with which we are already familiar and the @code{progn} -special form with which we are not. (It will be described later.) - -@node insert-buffer body -@subsection The Body of the @code{insert-buffer} Function - -The body of the @code{insert-buffer} function has two major parts: an -@code{or} expression and a @code{let} expression. The purpose of the -@code{or} expression is to ensure that the argument @code{buffer} is -bound to a buffer and not just the name of a buffer. The body of the -@code{let} expression contains the code which copies the other buffer -into the current buffer. - -@need 1250 -In outline, the two expressions fit into the @code{insert-buffer} -function like this: - -@smallexample -@group -(defun insert-buffer (buffer) - "@var{documentation}@dots{}" - (interactive "*bInsert buffer:@: ") - (or @dots{} - @dots{} -@end group -@group - (let (@var{varlist}) - @var{body-of-}@code{let}@dots{} ) -@end group -@end smallexample - -To understand how the @code{or} expression ensures that the argument -@code{buffer} is bound to a buffer and not to the name of a buffer, it -is first necessary to understand the @code{or} function. - -Before doing this, let me rewrite this part of the function using -@code{if} so that you can see what is done in a manner that will be familiar. - -@node if & or -@subsection @code{insert-buffer} With an @code{if} Instead of an @code{or} - -The job to be done is to make sure the value of @code{buffer} is a -buffer itself and not the name of a buffer. If the value is the name, -then the buffer itself must be got. - -You can imagine yourself at a conference where an usher is wandering -around holding a list with your name on it and looking for you: the -usher is ``bound'' to your name, not to you; but when the usher finds -you and takes your arm, the usher becomes ``bound'' to you. - -@need 800 -In Lisp, you might describe this situation like this: - -@smallexample -@group -(if (not (holding-on-to-guest)) - (find-and-take-arm-of-guest)) -@end group -@end smallexample - -We want to do the same thing with a buffer---if we do not have the -buffer itself, we want to get it. - -@need 1200 -Using a predicate called @code{bufferp} that tells us whether we have a -buffer (rather than its name), we can write the code like this: - -@smallexample -@group -(if (not (bufferp buffer)) ; @r{if-part} - (setq buffer (get-buffer buffer))) ; @r{then-part} -@end group -@end smallexample - -@noindent -Here, the true-or-false-test of the @code{if} expression is -@w{@code{(not (bufferp buffer))}}; and the then-part is the expression -@w{@code{(setq buffer (get-buffer buffer))}}. - -In the test, the function @code{bufferp} returns true if its argument is -a buffer---but false if its argument is the name of the buffer. (The -last character of the function name @code{bufferp} is the character -@samp{p}; as we saw earlier, such use of @samp{p} is a convention that -indicates that the function is a predicate, which is a term that means -that the function will determine whether some property is true or false. -@xref{Wrong Type of Argument, , Using the Wrong Type Object as an -Argument}.) - -@need 1200 -The function @code{not} precedes the expression @code{(bufferp buffer)}, -so the true-or-false-test looks like this: - -@smallexample -(not (bufferp buffer)) -@end smallexample - -@noindent -@code{not} is a function that returns true if its argument is false -and false if its argument is true. So if @code{(bufferp buffer)} -returns true, the @code{not} expression returns false and vice versa: -what is ``not true'' is false and what is ``not false'' is true. - -Using this test, the @code{if} expression works as follows: when the -value of the variable @code{buffer} is actually a buffer rather than -its name, the true-or-false-test returns false and the @code{if} -expression does not evaluate the then-part. This is fine, since we do -not need to do anything to the variable @code{buffer} if it really is -a buffer. - -On the other hand, when the value of @code{buffer} is not a buffer -itself, but the name of a buffer, the true-or-false-test returns true -and the then-part of the expression is evaluated. In this case, the -then-part is @code{(setq buffer (get-buffer buffer))}. This -expression uses the @code{get-buffer} function to return an actual -buffer itself, given its name. The @code{setq} then sets the variable -@code{buffer} to the value of the buffer itself, replacing its previous -value (which was the name of the buffer). - -@node Insert or -@subsection The @code{or} in the Body - -The purpose of the @code{or} expression in the @code{insert-buffer} -function is to ensure that the argument @code{buffer} is bound to a -buffer and not just to the name of a buffer. The previous section shows -how the job could have been done using an @code{if} expression. -However, the @code{insert-buffer} function actually uses @code{or}. -To understand this, it is necessary to understand how @code{or} works. - -@findex or -An @code{or} function can have any number of arguments. It evaluates -each argument in turn and returns the value of the first of its -arguments that is not @code{nil}. Also, and this is a crucial feature -of @code{or}, it does not evaluate any subsequent arguments after -returning the first non-@code{nil} value. - -@need 800 -The @code{or} expression looks like this: - -@smallexample -@group -(or (bufferp buffer) - (setq buffer (get-buffer buffer))) -@end group -@end smallexample - -@noindent -The first argument to @code{or} is the expression @code{(bufferp buffer)}. -This expression returns true (a non-@code{nil} value) if the buffer is -actually a buffer, and not just the name of a buffer. In the @code{or} -expression, if this is the case, the @code{or} expression returns this -true value and does not evaluate the next expression---and this is fine -with us, since we do not want to do anything to the value of -@code{buffer} if it really is a buffer. - -On the other hand, if the value of @code{(bufferp buffer)} is @code{nil}, -which it will be if the value of @code{buffer} is the name of a buffer, -the Lisp interpreter evaluates the next element of the @code{or} -expression. This is the expression @code{(setq buffer (get-buffer -buffer))}. This expression returns a non-@code{nil} value, which -is the value to which it sets the variable @code{buffer}---and this -value is a buffer itself, not the name of a buffer. - -The result of all this is that the symbol @code{buffer} is always -bound to a buffer itself rather than to the name of a buffer. All -this is necessary because the @code{set-buffer} function in a -following line only works with a buffer itself, not with the name to a -buffer. - -@need 1250 -Incidentally, using @code{or}, the situation with the usher would be -written like this: - -@smallexample -(or (holding-on-to-guest) (find-and-take-arm-of-guest)) -@end smallexample - -@node Insert let -@subsection The @code{let} Expression in @code{insert-buffer} - -After ensuring that the variable @code{buffer} refers to a buffer itself -and not just to the name of a buffer, the @code{insert-buffer function} -continues with a @code{let} expression. This specifies three local -variables, @code{start}, @code{end}, and @code{newmark} and binds them -to the initial value @code{nil}. These variables are used inside the -remainder of the @code{let} and temporarily hide any other occurrence of -variables of the same name in Emacs until the end of the @code{let}. - -@need 1200 -The body of the @code{let} contains two @code{save-excursion} -expressions. First, we will look at the inner @code{save-excursion} -expression in detail. The expression looks like this: - -@smallexample -@group -(save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) -@end group -@end smallexample - -@noindent -The expression @code{(set-buffer buffer)} changes Emacs's attention -from the current buffer to the one from which the text will copied. -In that buffer, the variables @code{start} and @code{end} are set to -the beginning and end of the buffer, using the commands -@code{point-min} and @code{point-max}. Note that we have here an -illustration of how @code{setq} is able to set two variables in the -same expression. The first argument of @code{setq} is set to the -value of its second, and its third argument is set to the value of its -fourth. - -After the body of the inner @code{save-excursion} is evaluated, the -@code{save-excursion} restores the original buffer, but @code{start} and -@code{end} remain set to the values of the beginning and end of the -buffer from which the text will be copied. - -@need 1250 -The outer @code{save-excursion} expression looks like this: - -@smallexample -@group -(save-excursion - (@var{inner-}@code{save-excursion}@var{-expression} - (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end}) - (insert-buffer-substring buffer start end) - (setq newmark (point))) -@end group -@end smallexample - -@noindent -The @code{insert-buffer-substring} function copies the text -@emph{into} the current buffer @emph{from} the region indicated by -@code{start} and @code{end} in @code{buffer}. Since the whole of the -second buffer lies between @code{start} and @code{end}, the whole of -the second buffer is copied into the buffer you are editing. Next, -the value of point, which will be at the end of the inserted text, is -recorded in the variable @code{newmark}. - -After the body of the outer @code{save-excursion} is evaluated, point -and mark are relocated to their original places. - -However, it is convenient to locate a mark at the end of the newly -inserted text and locate point at its beginning. The @code{newmark} -variable records the end of the inserted text. In the last line of -the @code{let} expression, the @code{(push-mark newmark)} expression -function sets a mark to this location. (The previous location of the -mark is still accessible; it is recorded on the mark ring and you can -go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is -located at the beginning of the inserted text, which is where it was -before you called the insert function, the position of which was saved -by the first @code{save-excursion}. - -@need 1250 -The whole @code{let} expression looks like this: - -@smallexample -@group -(let (start end newmark) - (save-excursion - (save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) - (insert-buffer-substring buffer start end) - (setq newmark (point))) - (push-mark newmark)) -@end group -@end smallexample - -Like the @code{append-to-buffer} function, the @code{insert-buffer} -function uses @code{let}, @code{save-excursion}, and -@code{set-buffer}. In addition, the function illustrates one way to -use @code{or}. All these functions are building blocks that we will -find and use again and again. - -@node New insert-buffer -@subsection New Body for @code{insert-buffer} -@findex insert-buffer, new version body -@findex new version body for insert-buffer - -The body in the GNU Emacs 22 version is more confusing than the original. - -@need 1250 -It consists of two expressions, - -@smallexample -@group - (push-mark - (save-excursion - (insert-buffer-substring (get-buffer buffer)) - (point))) - - nil -@end group -@end smallexample - -@noindent -except, and this is what confuses novices, very important work is done -inside the @code{push-mark} expression. - -The @code{get-buffer} function returns a buffer with the name -provided. You will note that the function is @emph{not} called -@code{get-buffer-create}; it does not create a buffer if one does not -already exist. The buffer returned by @code{get-buffer}, an existing -buffer, is passed to @code{insert-buffer-substring}, which inserts the -whole of the buffer (since you did not specify anything else). - -The location into which the buffer is inserted is recorded by -@code{push-mark}. Then the function returns @code{nil}, the value of -its last command. Put another way, the @code{insert-buffer} function -exists only to produce a side effect, inserting another buffer, not to -return any value. - -@node beginning-of-buffer -@section Complete Definition of @code{beginning-of-buffer} -@findex beginning-of-buffer - -The basic structure of the @code{beginning-of-buffer} function has -already been discussed. (@xref{simplified-beginning-of-buffer, , A -Simplified @code{beginning-of-buffer} Definition}.) -This section describes the complex part of the definition. - -As previously described, when invoked without an argument, -@code{beginning-of-buffer} moves the cursor to the beginning of the -buffer (in truth, the beginning of the accessible portion of the -buffer), leaving the mark at the previous position. However, when the -command is invoked with a number between one and ten, the function -considers that number to be a fraction of the length of the buffer, -measured in tenths, and Emacs moves the cursor that fraction of the -way from the beginning of the buffer. Thus, you can either call this -function with the key command @kbd{M-<}, which will move the cursor to -the beginning of the buffer, or with a key command such as @kbd{C-u 7 -M-<} which will move the cursor to a point 70% of the way through the -buffer. If a number bigger than ten is used for the argument, it -moves to the end of the buffer. - -The @code{beginning-of-buffer} function can be called with or without an -argument. The use of the argument is optional. - -@menu -* Optional Arguments:: -* beginning-of-buffer opt arg:: Example with optional argument. -* beginning-of-buffer complete:: -@end menu - -@node Optional Arguments -@subsection Optional Arguments - -Unless told otherwise, Lisp expects that a function with an argument in -its function definition will be called with a value for that argument. -If that does not happen, you get an error and a message that says -@samp{Wrong number of arguments}. - -@cindex Optional arguments -@cindex Keyword -@findex optional -However, optional arguments are a feature of Lisp: a particular -@dfn{keyword} is used to tell the Lisp interpreter that an argument is -optional. The keyword is @code{&optional}. (The @samp{&} in front of -@samp{optional} is part of the keyword.) In a function definition, if -an argument follows the keyword @code{&optional}, no value need be -passed to that argument when the function is called. - -@need 1200 -The first line of the function definition of @code{beginning-of-buffer} -therefore looks like this: - -@smallexample -(defun beginning-of-buffer (&optional arg) -@end smallexample - -@need 1250 -In outline, the whole function looks like this: - -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "@var{documentation}@dots{}" - (interactive "P") - (or (@var{is-the-argument-a-cons-cell} arg) - (and @var{are-both-transient-mark-mode-and-mark-active-true}) - (push-mark)) - (let (@var{determine-size-and-set-it}) - (goto-char - (@var{if-there-is-an-argument} - @var{figure-out-where-to-go} - @var{else-go-to} - (point-min)))) - @var{do-nicety} -@end group -@end smallexample - -The function is similar to the @code{simplified-beginning-of-buffer} -function except that the @code{interactive} expression has @code{"P"} -as an argument and the @code{goto-char} function is followed by an -if-then-else expression that figures out where to put the cursor if -there is an argument that is not a cons cell. - -(Since I do not explain a cons cell for many more chapters, please -consider ignoring the function @code{consp}. @xref{List -Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type, -, Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference -Manual}.) - -The @code{"P"} in the @code{interactive} expression tells Emacs to -pass a prefix argument, if there is one, to the function in raw form. -A prefix argument is made by typing the @key{META} key followed by a -number, or by typing @kbd{C-u} and then a number. (If you don't type -a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase -@code{"p"} in the @code{interactive} expression causes the function to -convert a prefix arg to a number.) - -The true-or-false-test of the @code{if} expression looks complex, but -it is not: it checks whether @code{arg} has a value that is not -@code{nil} and whether it is a cons cell. (That is what @code{consp} -does; it checks whether its argument is a cons cell.) If @code{arg} -has a value that is not @code{nil} (and is not a cons cell), which -will be the case if @code{beginning-of-buffer} is called with a -numeric argument, then this true-or-false-test will return true and -the then-part of the @code{if} expression will be evaluated. On the -other hand, if @code{beginning-of-buffer} is not called with an -argument, the value of @code{arg} will be @code{nil} and the else-part -of the @code{if} expression will be evaluated. The else-part is -simply @code{point-min}, and when this is the outcome, the whole -@code{goto-char} expression is @code{(goto-char (point-min))}, which -is how we saw the @code{beginning-of-buffer} function in its -simplified form. - -@node beginning-of-buffer opt arg -@subsection @code{beginning-of-buffer} with an Argument - -When @code{beginning-of-buffer} is called with an argument, an -expression is evaluated which calculates what value to pass to -@code{goto-char}. This expression is rather complicated at first sight. -It includes an inner @code{if} expression and much arithmetic. It looks -like this: - -@smallexample -@group -(if (> (buffer-size) 10000) - ;; @r{Avoid overflow for large buffer sizes!} - (* (prefix-numeric-value arg) - (/ size 10)) - (/ - (+ 10 - (* - size (prefix-numeric-value arg))) 10))) -@end group -@end smallexample - -@menu -* Disentangle beginning-of-buffer:: -* Large buffer case:: -* Small buffer case:: -@end menu - -@ifnottex -@node Disentangle beginning-of-buffer -@unnumberedsubsubsec Disentangle @code{beginning-of-buffer} -@end ifnottex - -Like other complex-looking expressions, the conditional expression -within @code{beginning-of-buffer} can be disentangled by looking at it -as parts of a template, in this case, the template for an if-then-else -expression. In skeletal form, the expression looks like this: - -@smallexample -@group -(if (@var{buffer-is-large} - @var{divide-buffer-size-by-10-and-multiply-by-arg} - @var{else-use-alternate-calculation} -@end group -@end smallexample - -The true-or-false-test of this inner @code{if} expression checks the -size of the buffer. The reason for this is that the old version 18 -Emacs used numbers that are no bigger than eight million or so and in -the computation that followed, the programmer feared that Emacs might -try to use over-large numbers if the buffer were large. The term -`overflow', mentioned in the comment, means numbers that are over -large. More recent versions of Emacs use larger numbers, but this -code has not been touched, if only because people now look at buffers -that are far, far larger than ever before. - -There are two cases: if the buffer is large and if it is not. - -@node Large buffer case -@unnumberedsubsubsec What happens in a large buffer - -In @code{beginning-of-buffer}, the inner @code{if} expression tests -whether the size of the buffer is greater than 10,000 characters. To do -this, it uses the @code{>} function and the computation of @code{size} -that comes from the let expression. - -In the old days, the function @code{buffer-size} was used. Not only -was that function called several times, it gave the size of the whole -buffer, not the accessible part. The computation makes much more -sense when it handles just the accessible part. (@xref{Narrowing & -Widening, , Narrowing and Widening}, for more information on focusing -attention to an `accessible' part.) - -@need 800 -The line looks like this: - -@smallexample -(if (> size 10000) -@end smallexample - -@need 1200 -@noindent -When the buffer is large, the then-part of the @code{if} expression is -evaluated. It reads like this (after formatting for easy reading): - -@smallexample -@group -(* - (prefix-numeric-value arg) - (/ size 10)) -@end group -@end smallexample - -@noindent -This expression is a multiplication, with two arguments to the function -@code{*}. - -The first argument is @code{(prefix-numeric-value arg)}. When -@code{"P"} is used as the argument for @code{interactive}, the value -passed to the function as its argument is passed a ``raw prefix -argument'', and not a number. (It is a number in a list.) To perform -the arithmetic, a conversion is necessary, and -@code{prefix-numeric-value} does the job. - -@findex / @r{(division)} -@cindex Division -The second argument is @code{(/ size 10)}. This expression divides -the numeric value by ten---the numeric value of the size of the -accessible portion of the buffer. This produces a number that tells -how many characters make up one tenth of the buffer size. (In Lisp, -@code{/} is used for division, just as @code{*} is used for -multiplication.) - -@need 1200 -In the multiplication expression as a whole, this amount is multiplied -by the value of the prefix argument---the multiplication looks like this: - -@smallexample -@group -(* @var{numeric-value-of-prefix-arg} - @var{number-of-characters-in-one-tenth-of-the-accessible-buffer}) -@end group -@end smallexample - -@noindent -If, for example, the prefix argument is @samp{7}, the one-tenth value -will be multiplied by 7 to give a position 70% of the way through. - -@need 1200 -The result of all this is that if the accessible portion of the buffer -is large, the @code{goto-char} expression reads like this: - -@smallexample -@group -(goto-char (* (prefix-numeric-value arg) - (/ size 10))) -@end group -@end smallexample - -This puts the cursor where we want it. - -@node Small buffer case -@unnumberedsubsubsec What happens in a small buffer - -If the buffer contains fewer than 10,000 characters, a slightly -different computation is performed. You might think this is not -necessary, since the first computation could do the job. However, in -a small buffer, the first method may not put the cursor on exactly the -desired line; the second method does a better job. - -@need 800 -The code looks like this: - -@c Keep this on one line. -@smallexample -(/ (+ 10 (* size (prefix-numeric-value arg))) 10)) -@end smallexample - -@need 1200 -@noindent -This is code in which you figure out what happens by discovering how the -functions are embedded in parentheses. It is easier to read if you -reformat it with each expression indented more deeply than its -enclosing expression: - -@smallexample -@group - (/ - (+ 10 - (* - size - (prefix-numeric-value arg))) - 10)) -@end group -@end smallexample - -@need 1200 -@noindent -Looking at parentheses, we see that the innermost operation is -@code{(prefix-numeric-value arg)}, which converts the raw argument to -a number. In the following expression, this number is multiplied by -the size of the accessible portion of the buffer: - -@smallexample -(* size (prefix-numeric-value arg)) -@end smallexample - -@noindent -This multiplication creates a number that may be larger than the size of -the buffer---seven times larger if the argument is 7, for example. Ten -is then added to this number and finally the large number is divided by -ten to provide a value that is one character larger than the percentage -position in the buffer. - -The number that results from all this is passed to @code{goto-char} and -the cursor is moved to that point. - -@need 1500 -@node beginning-of-buffer complete -@subsection The Complete @code{beginning-of-buffer} - -@need 1000 -Here is the complete text of the @code{beginning-of-buffer} function: -@sp 1 - -@c In GNU Emacs 22 -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "Move point to the beginning of the buffer; -leave mark at previous position. -With \\[universal-argument] prefix, -do not set mark at previous position. -With numeric arg N, -put point N/10 of the way from the beginning. - -If the buffer is narrowed, -this command uses the beginning and size -of the accessible part of the buffer. -@end group - -@group -Don't use this command in Lisp programs! -\(goto-char (point-min)) is faster -and avoids clobbering the mark." - (interactive "P") - (or (consp arg) - (and transient-mark-mode mark-active) - (push-mark)) -@end group -@group - (let ((size (- (point-max) (point-min)))) - (goto-char (if (and arg (not (consp arg))) - (+ (point-min) - (if (> size 10000) - ;; Avoid overflow for large buffer sizes! - (* (prefix-numeric-value arg) - (/ size 10)) - (/ (+ 10 (* size (prefix-numeric-value arg))) - 10))) - (point-min)))) - (if (and arg (not (consp arg))) (forward-line 1))) -@end group -@end smallexample - -@ignore -From before GNU Emacs 22 -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "Move point to the beginning of the buffer; -leave mark at previous position. -With arg N, put point N/10 of the way -from the true beginning. -@end group -@group -Don't use this in Lisp programs! -\(goto-char (point-min)) is faster -and does not set the mark." - (interactive "P") - (push-mark) -@end group -@group - (goto-char - (if arg - (if (> (buffer-size) 10000) - ;; @r{Avoid overflow for large buffer sizes!} - (* (prefix-numeric-value arg) - (/ (buffer-size) 10)) -@end group -@group - (/ (+ 10 (* (buffer-size) - (prefix-numeric-value arg))) - 10)) - (point-min))) - (if arg (forward-line 1))) -@end group -@end smallexample -@end ignore - -@noindent -Except for two small points, the previous discussion shows how this -function works. The first point deals with a detail in the -documentation string, and the second point concerns the last line of -the function. - -@need 800 -In the documentation string, there is reference to an expression: - -@smallexample -\\[universal-argument] -@end smallexample - -@noindent -A @samp{\\} is used before the first square bracket of this -expression. This @samp{\\} tells the Lisp interpreter to substitute -whatever key is currently bound to the @samp{[@dots{}]}. In the case -of @code{universal-argument}, that is usually @kbd{C-u}, but it might -be different. (@xref{Documentation Tips, , Tips for Documentation -Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more -information.) - -@need 1200 -Finally, the last line of the @code{beginning-of-buffer} command says -to move point to the beginning of the next line if the command is -invoked with an argument: - -@smallexample -(if (and arg (not (consp arg))) (forward-line 1)) -@end smallexample - -@noindent -This puts the cursor at the beginning of the first line after the -appropriate tenths position in the buffer. This is a flourish that -means that the cursor is always located @emph{at least} the requested -tenths of the way through the buffer, which is a nicety that is, -perhaps, not necessary, but which, if it did not occur, would be sure -to draw complaints. (The @code{(not (consp arg))} portion is so that -if you specify the command with a @kbd{C-u}, but without a number, -that is to say, if the `raw prefix argument' is simply a cons cell, -the command does not put you at the beginning of the second line.) - -@node Second Buffer Related Review -@section Review - -Here is a brief summary of some of the topics covered in this chapter. - -@table @code -@item or -Evaluate each argument in sequence, and return the value of the first -argument that is not @code{nil}; if none return a value that is not -@code{nil}, return @code{nil}. In brief, return the first true value -of the arguments; return a true value if one @emph{or} any of the -others are true. - -@item and -Evaluate each argument in sequence, and if any are @code{nil}, return -@code{nil}; if none are @code{nil}, return the value of the last -argument. In brief, return a true value only if all the arguments are -true; return a true value if one @emph{and} each of the others is -true. - -@item &optional -A keyword used to indicate that an argument to a function definition -is optional; this means that the function can be evaluated without the -argument, if desired. - -@item prefix-numeric-value -Convert the `raw prefix argument' produced by @code{(interactive -"P")} to a numeric value. - -@item forward-line -Move point forward to the beginning of the next line, or if the argument -is greater than one, forward that many lines. If it can't move as far -forward as it is supposed to, @code{forward-line} goes forward as far as -it can and then returns a count of the number of additional lines it was -supposed to move but couldn't. - -@item erase-buffer -Delete the entire contents of the current buffer. - -@item bufferp -Return @code{t} if its argument is a buffer; otherwise return @code{nil}. -@end table - -@node optional Exercise -@section @code{optional} Argument Exercise - -Write an interactive function with an optional argument that tests -whether its argument, a number, is greater than or equal to, or else, -less than the value of @code{fill-column}, and tells you which, in a -message. However, if you do not pass an argument to the function, use -56 as a default value. - -@node Narrowing & Widening -@chapter Narrowing and Widening -@cindex Focusing attention (narrowing) -@cindex Narrowing -@cindex Widening - -Narrowing is a feature of Emacs that makes it possible for you to focus -on a specific part of a buffer, and work without accidentally changing -other parts. Narrowing is normally disabled since it can confuse -novices. - -@menu -* Narrowing advantages:: The advantages of narrowing -* save-restriction:: The @code{save-restriction} special form. -* what-line:: The number of the line that point is on. -* narrow Exercise:: -@end menu - -@ifnottex -@node Narrowing advantages -@unnumberedsec The Advantages of Narrowing -@end ifnottex - -With narrowing, the rest of a buffer is made invisible, as if it weren't -there. This is an advantage if, for example, you want to replace a word -in one part of a buffer but not in another: you narrow to the part you want -and the replacement is carried out only in that section, not in the rest -of the buffer. Searches will only work within a narrowed region, not -outside of one, so if you are fixing a part of a document, you can keep -yourself from accidentally finding parts you do not need to fix by -narrowing just to the region you want. -(The key binding for @code{narrow-to-region} is @kbd{C-x n n}.) - -However, narrowing does make the rest of the buffer invisible, which -can scare people who inadvertently invoke narrowing and think they -have deleted a part of their file. Moreover, the @code{undo} command -(which is usually bound to @kbd{C-x u}) does not turn off narrowing -(nor should it), so people can become quite desperate if they do not -know that they can return the rest of a buffer to visibility with the -@code{widen} command. -(The key binding for @code{widen} is @kbd{C-x n w}.) - -Narrowing is just as useful to the Lisp interpreter as to a human. -Often, an Emacs Lisp function is designed to work on just part of a -buffer; or conversely, an Emacs Lisp function needs to work on all of a -buffer that has been narrowed. The @code{what-line} function, for -example, removes the narrowing from a buffer, if it has any narrowing -and when it has finished its job, restores the narrowing to what it was. -On the other hand, the @code{count-lines} function -uses narrowing to restrict itself to just that portion -of the buffer in which it is interested and then restores the previous -situation. - -@node save-restriction -@section The @code{save-restriction} Special Form -@findex save-restriction - -In Emacs Lisp, you can use the @code{save-restriction} special form to -keep track of whatever narrowing is in effect, if any. When the Lisp -interpreter meets with @code{save-restriction}, it executes the code -in the body of the @code{save-restriction} expression, and then undoes -any changes to narrowing that the code caused. If, for example, the -buffer is narrowed and the code that follows @code{save-restriction} -gets rid of the narrowing, @code{save-restriction} returns the buffer -to its narrowed region afterwards. In the @code{what-line} command, -any narrowing the buffer may have is undone by the @code{widen} -command that immediately follows the @code{save-restriction} command. -Any original narrowing is restored just before the completion of the -function. - -@need 1250 -The template for a @code{save-restriction} expression is simple: - -@smallexample -@group -(save-restriction - @var{body}@dots{} ) -@end group -@end smallexample - -@noindent -The body of the @code{save-restriction} is one or more expressions that -will be evaluated in sequence by the Lisp interpreter. - -Finally, a point to note: when you use both @code{save-excursion} and -@code{save-restriction}, one right after the other, you should use -@code{save-excursion} outermost. If you write them in reverse order, -you may fail to record narrowing in the buffer to which Emacs switches -after calling @code{save-excursion}. Thus, when written together, -@code{save-excursion} and @code{save-restriction} should be written -like this: - -@smallexample -@group -(save-excursion - (save-restriction - @var{body}@dots{})) -@end group -@end smallexample - -In other circumstances, when not written together, the -@code{save-excursion} and @code{save-restriction} special forms must -be written in the order appropriate to the function. - -@need 1250 -For example, - -@smallexample -@group - (save-restriction - (widen) - (save-excursion - @var{body}@dots{})) -@end group -@end smallexample - -@ignore -Emacs 22 -/usr/local/src/emacs/lisp/simple.el - -(defun what-line () - "Print the current buffer line number and narrowed line number of point." - (interactive) - (let ((start (point-min)) - (n (line-number-at-pos))) - (if (= start 1) - (message "Line %d" n) - (save-excursion - (save-restriction - (widen) - (message "line %d (narrowed line %d)" - (+ n (line-number-at-pos start) -1) n)))))) - -(defun line-number-at-pos (&optional pos) - "Return (narrowed) buffer line number at position POS. -If POS is nil, use current buffer location. -Counting starts at (point-min), so the value refers -to the contents of the accessible portion of the buffer." - (let ((opoint (or pos (point))) start) - (save-excursion - (goto-char (point-min)) - (setq start (point)) - (goto-char opoint) - (forward-line 0) - (1+ (count-lines start (point)))))) - -(defun count-lines (start end) - "Return number of lines between START and END. -This is usually the number of newlines between them, -but can be one more if START is not equal to END -and the greater of them is not at the start of a line." - (save-excursion - (save-restriction - (narrow-to-region start end) - (goto-char (point-min)) - (if (eq selective-display t) - (save-match-data - (let ((done 0)) - (while (re-search-forward "[\n\C-m]" nil t 40) - (setq done (+ 40 done))) - (while (re-search-forward "[\n\C-m]" nil t 1) - (setq done (+ 1 done))) - (goto-char (point-max)) - (if (and (/= start end) - (not (bolp))) - (1+ done) - done))) - (- (buffer-size) (forward-line (buffer-size))))))) -@end ignore - -@node what-line -@section @code{what-line} -@findex what-line -@cindex Widening, example of - -The @code{what-line} command tells you the number of the line in which -the cursor is located. The function illustrates the use of the -@code{save-restriction} and @code{save-excursion} commands. Here is the -original text of the function: - -@smallexample -@group -(defun what-line () - "Print the current line number (in the buffer) of point." - (interactive) - (save-restriction - (widen) - (save-excursion - (beginning-of-line) - (message "Line %d" - (1+ (count-lines 1 (point))))))) -@end group -@end smallexample - -(In recent versions of GNU Emacs, the @code{what-line} function has -been expanded to tell you your line number in a narrowed buffer as -well as your line number in a widened buffer. The recent version is -more complex than the version shown here. If you feel adventurous, -you might want to look at it after figuring out how this version -works. You will probably need to use @kbd{C-h f} -(@code{describe-function}). The newer version uses a conditional to -determine whether the buffer has been narrowed. - -(Also, it uses @code{line-number-at-pos}, which among other simple -expressions, such as @code{(goto-char (point-min))}, moves point to -the beginning of the current line with @code{(forward-line 0)} rather -than @code{beginning-of-line}.) - -The @code{what-line} function as shown here has a documentation line -and is interactive, as you would expect. The next two lines use the -functions @code{save-restriction} and @code{widen}. - -The @code{save-restriction} special form notes whatever narrowing is in -effect, if any, in the current buffer and restores that narrowing after -the code in the body of the @code{save-restriction} has been evaluated. - -The @code{save-restriction} special form is followed by @code{widen}. -This function undoes any narrowing the current buffer may have had -when @code{what-line} was called. (The narrowing that was there is -the narrowing that @code{save-restriction} remembers.) This widening -makes it possible for the line counting commands to count from the -beginning of the buffer. Otherwise, they would have been limited to -counting within the accessible region. Any original narrowing is -restored just before the completion of the function by the -@code{save-restriction} special form. - -The call to @code{widen} is followed by @code{save-excursion}, which -saves the location of the cursor (i.e., of point) and of the mark, and -restores them after the code in the body of the @code{save-excursion} -uses the @code{beginning-of-line} function to move point. - -(Note that the @code{(widen)} expression comes between the -@code{save-restriction} and @code{save-excursion} special forms. When -you write the two @code{save- @dots{}} expressions in sequence, write -@code{save-excursion} outermost.) - -@need 1200 -The last two lines of the @code{what-line} function are functions to -count the number of lines in the buffer and then print the number in the -echo area. - -@smallexample -@group -(message "Line %d" - (1+ (count-lines 1 (point))))))) -@end group -@end smallexample - -The @code{message} function prints a one-line message at the bottom of -the Emacs screen. The first argument is inside of quotation marks and -is printed as a string of characters. However, it may contain a -@samp{%d} expression to print a following argument. @samp{%d} prints -the argument as a decimal, so the message will say something such as -@samp{Line 243}. - -@need 1200 -The number that is printed in place of the @samp{%d} is computed by the -last line of the function: - -@smallexample -(1+ (count-lines 1 (point))) -@end smallexample - -@ignore -GNU Emacs 22 - -(defun count-lines (start end) - "Return number of lines between START and END. -This is usually the number of newlines between them, -but can be one more if START is not equal to END -and the greater of them is not at the start of a line." - (save-excursion - (save-restriction - (narrow-to-region start end) - (goto-char (point-min)) - (if (eq selective-display t) - (save-match-data - (let ((done 0)) - (while (re-search-forward "[\n\C-m]" nil t 40) - (setq done (+ 40 done))) - (while (re-search-forward "[\n\C-m]" nil t 1) - (setq done (+ 1 done))) - (goto-char (point-max)) - (if (and (/= start end) - (not (bolp))) - (1+ done) - done))) - (- (buffer-size) (forward-line (buffer-size))))))) -@end ignore - -@noindent -What this does is count the lines from the first position of the -buffer, indicated by the @code{1}, up to @code{(point)}, and then add -one to that number. (The @code{1+} function adds one to its -argument.) We add one to it because line 2 has only one line before -it, and @code{count-lines} counts only the lines @emph{before} the -current line. - -After @code{count-lines} has done its job, and the message has been -printed in the echo area, the @code{save-excursion} restores point and -mark to their original positions; and @code{save-restriction} restores -the original narrowing, if any. - -@node narrow Exercise -@section Exercise with Narrowing - -Write a function that will display the first 60 characters of the -current buffer, even if you have narrowed the buffer to its latter -half so that the first line is inaccessible. Restore point, mark, and -narrowing. For this exercise, you need to use a whole potpourri of -functions, including @code{save-restriction}, @code{widen}, -@code{goto-char}, @code{point-min}, @code{message}, and -@code{buffer-substring}. - -@cindex Properties, mention of @code{buffer-substring-no-properties} -(@code{buffer-substring} is a previously unmentioned function you will -have to investigate yourself; or perhaps you will have to use -@code{buffer-substring-no-properties} or -@code{filter-buffer-substring} @dots{}, yet other functions. Text -properties are a feature otherwise not discussed here. @xref{Text -Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference -Manual}.) - -Additionally, do you really need @code{goto-char} or @code{point-min}? -Or can you write the function without them? - -@node car cdr & cons -@chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions -@findex car, @r{introduced} -@findex cdr, @r{introduced} - -In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental -functions. The @code{cons} function is used to construct lists, and -the @code{car} and @code{cdr} functions are used to take them apart. - -In the walk through of the @code{copy-region-as-kill} function, we -will see @code{cons} as well as two variants on @code{cdr}, -namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) - -@menu -* Strange Names:: An historical aside: why the strange names? -* car & cdr:: Functions for extracting part of a list. -* cons:: Constructing a list. -* nthcdr:: Calling @code{cdr} repeatedly. -* nth:: -* setcar:: Changing the first element of a list. -* setcdr:: Changing the rest of a list. -* cons Exercise:: -@end menu - -@ifnottex -@node Strange Names -@unnumberedsec Strange Names -@end ifnottex - -The name of the @code{cons} function is not unreasonable: it is an -abbreviation of the word `construct'. The origins of the names for -@code{car} and @code{cdr}, on the other hand, are esoteric: @code{car} -is an acronym from the phrase `Contents of the Address part of the -Register'; and @code{cdr} (pronounced `could-er') is an acronym from -the phrase `Contents of the Decrement part of the Register'. These -phrases refer to specific pieces of hardware on the very early -computer on which the original Lisp was developed. Besides being -obsolete, the phrases have been completely irrelevant for more than 25 -years to anyone thinking about Lisp. Nonetheless, although a few -brave scholars have begun to use more reasonable names for these -functions, the old terms are still in use. In particular, since the -terms are used in the Emacs Lisp source code, we will use them in this -introduction. - -@node car & cdr -@section @code{car} and @code{cdr} - -The @sc{car} of a list is, quite simply, the first item in the list. -Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is -@code{rose}. - -@need 1200 -If you are reading this in Info in GNU Emacs, you can see this by -evaluating the following: - -@smallexample -(car '(rose violet daisy buttercup)) -@end smallexample - -@noindent -After evaluating the expression, @code{rose} will appear in the echo -area. - -Clearly, a more reasonable name for the @code{car} function would be -@code{first} and this is often suggested. - -@code{car} does not remove the first item from the list; it only reports -what it is. After @code{car} has been applied to a list, the list is -still the same as it was. In the jargon, @code{car} is -`non-destructive'. This feature turns out to be important. - -The @sc{cdr} of a list is the rest of the list, that is, the -@code{cdr} function returns the part of the list that follows the -first item. Thus, while the @sc{car} of the list @code{'(rose violet -daisy buttercup)} is @code{rose}, the rest of the list, the value -returned by the @code{cdr} function, is @code{(violet daisy -buttercup)}. - -@need 800 -You can see this by evaluating the following in the usual way: - -@smallexample -(cdr '(rose violet daisy buttercup)) -@end smallexample - -@noindent -When you evaluate this, @code{(violet daisy buttercup)} will appear in -the echo area. - -Like @code{car}, @code{cdr} does not remove any elements from the -list---it just returns a report of what the second and subsequent -elements are. - -Incidentally, in the example, the list of flowers is quoted. If it were -not, the Lisp interpreter would try to evaluate the list by calling -@code{rose} as a function. In this example, we do not want to do that. - -Clearly, a more reasonable name for @code{cdr} would be @code{rest}. - -(There is a lesson here: when you name new functions, consider very -carefully what you are doing, since you may be stuck with the names -for far longer than you expect. The reason this document perpetuates -these names is that the Emacs Lisp source code uses them, and if I did -not use them, you would have a hard time reading the code; but do, -please, try to avoid using these terms yourself. The people who come -after you will be grateful to you.) - -When @code{car} and @code{cdr} are applied to a list made up of symbols, -such as the list @code{(pine fir oak maple)}, the element of the list -returned by the function @code{car} is the symbol @code{pine} without -any parentheses around it. @code{pine} is the first element in the -list. However, the @sc{cdr} of the list is a list itself, @code{(fir -oak maple)}, as you can see by evaluating the following expressions in -the usual way: - -@smallexample -@group -(car '(pine fir oak maple)) - -(cdr '(pine fir oak maple)) -@end group -@end smallexample - -On the other hand, in a list of lists, the first element is itself a -list. @code{car} returns this first element as a list. For example, -the following list contains three sub-lists, a list of carnivores, a -list of herbivores and a list of sea mammals: - -@smallexample -@group -(car '((lion tiger cheetah) - (gazelle antelope zebra) - (whale dolphin seal))) -@end group -@end smallexample - -@noindent -In this example, the first element or @sc{car} of the list is the list of -carnivores, @code{(lion tiger cheetah)}, and the rest of the list is -@code{((gazelle antelope zebra) (whale dolphin seal))}. - -@smallexample -@group -(cdr '((lion tiger cheetah) - (gazelle antelope zebra) - (whale dolphin seal))) -@end group -@end smallexample - -It is worth saying again that @code{car} and @code{cdr} are -non-destructive---that is, they do not modify or change lists to which -they are applied. This is very important for how they are used. - -Also, in the first chapter, in the discussion about atoms, I said that -in Lisp, ``certain kinds of atom, such as an array, can be separated -into parts; but the mechanism for doing this is different from the -mechanism for splitting a list. As far as Lisp is concerned, the -atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The -@code{car} and @code{cdr} functions are used for splitting lists and -are considered fundamental to Lisp. Since they cannot split or gain -access to the parts of an array, an array is considered an atom. -Conversely, the other fundamental function, @code{cons}, can put -together or construct a list, but not an array. (Arrays are handled -by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU -Emacs Lisp Reference Manual}.) - -@node cons -@section @code{cons} -@findex cons, @r{introduced} - -The @code{cons} function constructs lists; it is the inverse of -@code{car} and @code{cdr}. For example, @code{cons} can be used to make -a four element list from the three element list, @code{(fir oak maple)}: - -@smallexample -(cons 'pine '(fir oak maple)) -@end smallexample - -@need 800 -@noindent -After evaluating this list, you will see - -@smallexample -(pine fir oak maple) -@end smallexample - -@noindent -appear in the echo area. @code{cons} causes the creation of a new -list in which the element is followed by the elements of the original -list. - -We often say that `@code{cons} puts a new element at the beginning of -a list; it attaches or pushes elements onto the list', but this -phrasing can be misleading, since @code{cons} does not change an -existing list, but creates a new one. - -Like @code{car} and @code{cdr}, @code{cons} is non-destructive. - -@menu -* Build a list:: -* length:: How to find the length of a list. -@end menu - -@ifnottex -@node Build a list -@unnumberedsubsec Build a list -@end ifnottex - -@code{cons} must have a list to attach to.@footnote{Actually, you can -@code{cons} an element to an atom to produce a dotted pair. Dotted -pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted -Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You -cannot start from absolutely nothing. If you are building a list, you -need to provide at least an empty list at the beginning. Here is a -series of @code{cons} expressions that build up a list of flowers. If -you are reading this in Info in GNU Emacs, you can evaluate each of -the expressions in the usual way; the value is printed in this text -after @samp{@result{}}, which you may read as `evaluates to'. - -@smallexample -@group -(cons 'buttercup ()) - @result{} (buttercup) -@end group - -@group -(cons 'daisy '(buttercup)) - @result{} (daisy buttercup) -@end group - -@group -(cons 'violet '(daisy buttercup)) - @result{} (violet daisy buttercup) -@end group - -@group -(cons 'rose '(violet daisy buttercup)) - @result{} (rose violet daisy buttercup) -@end group -@end smallexample - -@noindent -In the first example, the empty list is shown as @code{()} and a list -made up of @code{buttercup} followed by the empty list is constructed. -As you can see, the empty list is not shown in the list that was -constructed. All that you see is @code{(buttercup)}. The empty list is -not counted as an element of a list because there is nothing in an empty -list. Generally speaking, an empty list is invisible. - -The second example, @code{(cons 'daisy '(buttercup))} constructs a new, -two element list by putting @code{daisy} in front of @code{buttercup}; -and the third example constructs a three element list by putting -@code{violet} in front of @code{daisy} and @code{buttercup}. - -@node length -@subsection Find the Length of a List: @code{length} -@findex length - -You can find out how many elements there are in a list by using the Lisp -function @code{length}, as in the following examples: - -@smallexample -@group -(length '(buttercup)) - @result{} 1 -@end group - -@group -(length '(daisy buttercup)) - @result{} 2 -@end group - -@group -(length (cons 'violet '(daisy buttercup))) - @result{} 3 -@end group -@end smallexample - -@noindent -In the third example, the @code{cons} function is used to construct a -three element list which is then passed to the @code{length} function as -its argument. - -@need 1200 -We can also use @code{length} to count the number of elements in an -empty list: - -@smallexample -@group -(length ()) - @result{} 0 -@end group -@end smallexample - -@noindent -As you would expect, the number of elements in an empty list is zero. - -An interesting experiment is to find out what happens if you try to find -the length of no list at all; that is, if you try to call @code{length} -without giving it an argument, not even an empty list: - -@smallexample -(length ) -@end smallexample - -@need 800 -@noindent -What you see, if you evaluate this, is the error message - -@smallexample -Lisp error: (wrong-number-of-arguments length 0) -@end smallexample - -@noindent -This means that the function receives the wrong number of -arguments, zero, when it expects some other number of arguments. In -this case, one argument is expected, the argument being a list whose -length the function is measuring. (Note that @emph{one} list is -@emph{one} argument, even if the list has many elements inside it.) - -The part of the error message that says @samp{length} is the name of -the function. - -@ignore -@code{length} is still a subroutine, but you need C-h f to discover that. - -In an earlier version: - This is written with a special notation, @samp{# (length string) 0) - (if yank-handler - (put-text-property 0 (length string) - 'yank-handler yank-handler string)) - (if yank-handler - (signal 'args-out-of-range - (list string "yank-handler specified for empty string")))) -@end group -@group - (if (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) -@end group -@group - (if (and replace kill-ring) - (setcar kill-ring string) - (push string kill-ring) - (if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) -@end group -@group - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample -@ignore -was: -(defun kill-new (string &optional replace) - "Make STRING the latest kill in the kill ring. -Set the kill-ring-yank pointer to point to it. -If `interprogram-cut-function' is non-nil, apply it to STRING. -Optional second argument REPLACE non-nil means that STRING will replace -the front of the kill ring, rather than being added to the list." - (and (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) - (if (and replace kill-ring) - (setcar kill-ring string) - (setq kill-ring (cons string kill-ring)) - (if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end ignore - -(Notice that the function is not interactive.) - -As usual, we can look at this function in parts. - -The function definition has an optional @code{yank-handler} argument, -which when invoked tells the function how to deal with properties -added to the text, such as `bold' or `italics'. We will skip that. - -@need 1200 -The first line of the documentation makes sense: - -@smallexample -Make STRING the latest kill in the kill ring. -@end smallexample - -@noindent -Let's skip over the rest of the documentation for the moment. - -@noindent -Also, let's skip over the initial @code{if} expression and those lines -of code involving @code{menu-bar-update-yank-menu}. We will explain -them below. - -@need 1200 -The critical lines are these: - -@smallexample -@group - (if (and replace kill-ring) - ;; @r{then} - (setcar kill-ring string) -@end group -@group - ;; @r{else} - (push string kill-ring) -@end group -@group - (setq kill-ring (cons string kill-ring)) - (if (> (length kill-ring) kill-ring-max) - ;; @r{avoid overly long kill ring} - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) -@end group -@group - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample - -The conditional test is @w{@code{(and replace kill-ring)}}. -This will be true when two conditions are met: the kill ring has -something in it, and the @code{replace} variable is true. - -@need 1250 -When the @code{kill-append} function sets @code{replace} to be true -and when the kill ring has at least one item in it, the @code{setcar} -expression is executed: - -@smallexample -(setcar kill-ring string) -@end smallexample - -The @code{setcar} function actually changes the first element of the -@code{kill-ring} list to the value of @code{string}. It replaces the -first element. - -@need 1250 -On the other hand, if the kill ring is empty, or replace is false, the -else-part of the condition is executed: - -@smallexample -(push string kill-ring) -@end smallexample - -@noindent -@need 1250 -@code{push} puts its first argument onto the second. It is similar to -the older - -@smallexample -(setq kill-ring (cons string kill-ring)) -@end smallexample - -@noindent -@need 1250 -or the newer - -@smallexample -(add-to-list kill-ring string) -@end smallexample - -@noindent -When it is false, the expression first constructs a new version of the -kill ring by prepending @code{string} to the existing kill ring as a -new element (that is what the @code{push} does). Then it executes a -second @code{if} clause. This second @code{if} clause keeps the kill -ring from growing too long. - -Let's look at these two expressions in order. - -The @code{push} line of the else-part sets the new value of the kill -ring to what results from adding the string being killed to the old -kill ring. - -We can see how this works with an example. - -@need 800 -First, - -@smallexample -(setq example-list '("here is a clause" "another clause")) -@end smallexample - -@need 1200 -@noindent -After evaluating this expression with @kbd{C-x C-e}, you can evaluate -@code{example-list} and see what it returns: - -@smallexample -@group -example-list - @result{} ("here is a clause" "another clause") -@end group -@end smallexample - -@need 1200 -@noindent -Now, we can add a new element on to this list by evaluating the -following expression: -@findex push, @r{example} - -@smallexample -(push "a third clause" example-list) -@end smallexample - -@need 800 -@noindent -When we evaluate @code{example-list}, we find its value is: - -@smallexample -@group -example-list - @result{} ("a third clause" "here is a clause" "another clause") -@end group -@end smallexample - -@noindent -Thus, the third clause is added to the list by @code{push}. - -@need 1200 -Now for the second part of the @code{if} clause. This expression -keeps the kill ring from growing too long. It looks like this: - -@smallexample -@group -(if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)) -@end group -@end smallexample - -The code checks whether the length of the kill ring is greater than -the maximum permitted length. This is the value of -@code{kill-ring-max} (which is 60, by default). If the length of the -kill ring is too long, then this code sets the last element of the -kill ring to @code{nil}. It does this by using two functions, -@code{nthcdr} and @code{setcdr}. - -We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}). -It sets the @sc{cdr} of a list, just as @code{setcar} sets the -@sc{car} of a list. In this case, however, @code{setcdr} will not be -setting the @sc{cdr} of the whole kill ring; the @code{nthcdr} -function is used to cause it to set the @sc{cdr} of the next to last -element of the kill ring---this means that since the @sc{cdr} of the -next to last element is the last element of the kill ring, it will set -the last element of the kill ring. - -@findex nthcdr, @r{example} -The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a -list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr} -@dots{} It does this @var{N} times and returns the results. -(@xref{nthcdr, , @code{nthcdr}}.) - -@findex setcdr, @r{example} -Thus, if we had a four element list that was supposed to be three -elements long, we could set the @sc{cdr} of the next to last element -to @code{nil}, and thereby shorten the list. (If you set the last -element to some other value than @code{nil}, which you could do, then -you would not have shortened the list. @xref{setcdr, , -@code{setcdr}}.) - -You can see shortening by evaluating the following three expressions -in turn. First set the value of @code{trees} to @code{(maple oak pine -birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil} -and then find the value of @code{trees}: - -@smallexample -@group -(setq trees '(maple oak pine birch)) - @result{} (maple oak pine birch) -@end group - -@group -(setcdr (nthcdr 2 trees) nil) - @result{} nil - -trees - @result{} (maple oak pine) -@end group -@end smallexample - -@noindent -(The value returned by the @code{setcdr} expression is @code{nil} since -that is what the @sc{cdr} is set to.) - -To repeat, in @code{kill-new}, the @code{nthcdr} function takes the -@sc{cdr} a number of times that is one less than the maximum permitted -size of the kill ring and @code{setcdr} sets the @sc{cdr} of that -element (which will be the rest of the elements in the kill ring) to -@code{nil}. This prevents the kill ring from growing too long. - -@need 800 -The next to last expression in the @code{kill-new} function is - -@smallexample -(setq kill-ring-yank-pointer kill-ring) -@end smallexample - -The @code{kill-ring-yank-pointer} is a global variable that is set to be -the @code{kill-ring}. - -Even though the @code{kill-ring-yank-pointer} is called a -@samp{pointer}, it is a variable just like the kill ring. However, the -name has been chosen to help humans understand how the variable is used. - -@need 1200 -Now, to return to an early expression in the body of the function: - -@smallexample -@group - (if (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) -@end group -@end smallexample - -@noindent -It starts with an @code{if} expression - -In this case, the expression tests first to see whether -@code{menu-bar-update-yank-menu} exists as a function, and if so, -calls it. The @code{fboundp} function returns true if the symbol it -is testing has a function definition that `is not void'. If the -symbol's function definition were void, we would receive an error -message, as we did when we created errors intentionally (@pxref{Making -Errors, , Generate an Error Message}). - -@noindent -The then-part contains an expression whose first element is the -function @code{and}. - -@findex and -The @code{and} special form evaluates each of its arguments until one -of the arguments returns a value of @code{nil}, in which case the -@code{and} expression returns @code{nil}; however, if none of the -arguments returns a value of @code{nil}, the value resulting from -evaluating the last argument is returned. (Since such a value is not -@code{nil}, it is considered true in Emacs Lisp.) In other words, an -@code{and} expression returns a true value only if all its arguments -are true. (@xref{Second Buffer Related Review}.) - -The expression determines whether the second argument to -@code{menu-bar-update-yank-menu} is true or not. -@ignore - ;; If we're supposed to be extending an existing string, and that - ;; string really is at the front of the menu, then update it in place. -@end ignore - -@code{menu-bar-update-yank-menu} is one of the functions that make it -possible to use the `Select and Paste' menu in the Edit item of a menu -bar; using a mouse, you can look at the various pieces of text you -have saved and select one piece to paste. - -The last expression in the @code{kill-new} function adds the newly -copied string to whatever facility exists for copying and pasting -among different programs running in a windowing system. In the X -Windowing system, for example, the @code{x-select-text} function takes -the string and stores it in memory operated by X@. You can paste the -string in another program, such as an Xterm. - -@need 1200 -The expression looks like this: - -@smallexample -@group - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample - -If an @code{interprogram-cut-function} exists, then Emacs executes -@code{funcall}, which in turn calls its first argument as a function -and passes the remaining arguments to it. (Incidentally, as far as I -can see, this @code{if} expression could be replaced by an @code{and} -expression similar to the one in the first part of the function.) - -We are not going to discuss windowing systems and other programs -further, but merely note that this is a mechanism that enables GNU -Emacs to work easily and well with other programs. - -This code for placing text in the kill ring, either concatenated with -an existing element or as a new element, leads us to the code for -bringing back text that has been cut out of the buffer---the yank -commands. However, before discussing the yank commands, it is better -to learn how lists are implemented in a computer. This will make -clear such mysteries as the use of the term `pointer'. But before -that, we will digress into C. - -@ignore -@c is this true in Emacs 22? Does not seems to be - - (If the @w{@code{(< end beg))}} -expression is true, @code{kill-append} prepends the string to the just -previously clipped text. For a detailed discussion, see -@ref{kill-append function, , The @code{kill-append} function}.) - -If you then yank back the text, i.e., `paste' it, you get both -pieces of text at once. That way, if you delete two words in a row, -and then yank them back, you get both words, in their proper order, -with one yank. (The @w{@code{(< end beg))}} expression makes sure the -order is correct.) - -On the other hand, if the previous command is not @code{kill-region}, -then the @code{kill-new} function is called, which adds the text to -the kill ring as the latest item, and sets the -@code{kill-ring-yank-pointer} variable to point to it. -@end ignore -@ignore - -@c Evidently, changed for Emacs 22. The zap-to-char command does not -@c use the delete-and-extract-region function - -2006 Oct 26, the Digression into C is now OK but should come after -copy-region-as-kill and filter-buffer-substring - -2006 Oct 24 -In Emacs 22, -copy-region-as-kill is short, 12 lines, and uses -filter-buffer-substring, which is longer, 39 lines -and has delete-and-extract-region in it. -delete-and-extract-region is written in C. - -see Initializing a Variable with @code{defvar} -@end ignore - -@node Digression into C -@section Digression into C -@findex delete-and-extract-region -@cindex C, a digression into -@cindex Digression into C - -The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, , -@code{copy-region-as-kill}}) uses the @code{filter-buffer-substring} -function, which in turn uses the @code{delete-and-extract-region} -function. It removes the contents of a region and you cannot get them -back. - -Unlike the other code discussed here, the -@code{delete-and-extract-region} function is not written in Emacs -Lisp; it is written in C and is one of the primitives of the GNU Emacs -system. Since it is very simple, I will digress briefly from Lisp and -describe it here. - -@c GNU Emacs 24 in src/editfns.c -@c the DEFUN for delete-and-extract-region - -@need 1500 -Like many of the other Emacs primitives, -@code{delete-and-extract-region} is written as an instance of a C -macro, a macro being a template for code. The complete macro looks -like this: - -@smallexample -@group -DEFUN ("delete-and-extract-region", Fdelete_and_extract_region, - Sdelete_and_extract_region, 2, 2, 0, - doc: /* Delete the text between START and END and return it. */) - (Lisp_Object start, Lisp_Object end) -@{ - validate_region (&start, &end); - if (XINT (start) == XINT (end)) - return empty_unibyte_string; - return del_range_1 (XINT (start), XINT (end), 1, 1); -@} -@end group -@end smallexample - -Without going into the details of the macro writing process, let me -point out that this macro starts with the word @code{DEFUN}. The word -@code{DEFUN} was chosen since the code serves the same purpose as -@code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in -@file{emacs/src/lisp.h}.) - -The word @code{DEFUN} is followed by seven parts inside of -parentheses: - -@itemize @bullet -@item -The first part is the name given to the function in Lisp, -@code{delete-and-extract-region}. - -@item -The second part is the name of the function in C, -@code{Fdelete_and_extract_region}. By convention, it starts with -@samp{F}. Since C does not use hyphens in names, underscores are used -instead. - -@item -The third part is the name for the C constant structure that records -information on this function for internal use. It is the name of the -function in C but begins with an @samp{S} instead of an @samp{F}. - -@item -The fourth and fifth parts specify the minimum and maximum number of -arguments the function can have. This function demands exactly 2 -arguments. - -@item -The sixth part is nearly like the argument that follows the -@code{interactive} declaration in a function written in Lisp: a letter -followed, perhaps, by a prompt. The only difference from the Lisp is -when the macro is called with no arguments. Then you write a @code{0} -(which is a `null string'), as in this macro. - -If you were to specify arguments, you would place them between -quotation marks. The C macro for @code{goto-char} includes -@code{"NGoto char: "} in this position to indicate that the function -expects a raw prefix, in this case, a numerical location in a buffer, -and provides a prompt. - -@item -The seventh part is a documentation string, just like the one for a -function written in Emacs Lisp. This is written as a C comment. (When -you build Emacs, the program @command{lib-src/make-docfile} extracts -these comments and uses them to make the ``real'' documentation.) -@end itemize - -@need 1200 -In a C macro, the formal parameters come next, with a statement of -what kind of object they are, followed by what might be called the `body' -of the macro. For @code{delete-and-extract-region} the `body' -consists of the following four lines: - -@smallexample -@group -validate_region (&start, &end); -if (XINT (start) == XINT (end)) - return empty_unibyte_string; -return del_range_1 (XINT (start), XINT (end), 1, 1); -@end group -@end smallexample - -The @code{validate_region} function checks whether the values -passed as the beginning and end of the region are the proper type and -are within range. If the beginning and end positions are the same, -then return an empty string. - -The @code{del_range_1} function actually deletes the text. It is a -complex function we will not look into. It updates the buffer and -does other things. However, it is worth looking at the two arguments -passed to @code{del_range}. These are @w{@code{XINT (start)}} and -@w{@code{XINT (end)}}. - -As far as the C language is concerned, @code{start} and @code{end} are -two integers that mark the beginning and end of the region to be -deleted@footnote{More precisely, and requiring more expert knowledge -to understand, the two integers are of type `Lisp_Object', which can -also be a C union instead of an integer type.}. - -In early versions of Emacs, these two numbers were thirty-two bits -long, but the code is slowly being generalized to handle other -lengths. Three of the available bits are used to specify the type of -information; the remaining bits are used as `content'. - -@samp{XINT} is a C macro that extracts the relevant number from the -longer collection of bits; the three other bits are discarded. - -@need 800 -The command in @code{delete-and-extract-region} looks like this: - -@smallexample -del_range_1 (XINT (start), XINT (end), 1, 1); -@end smallexample - -@noindent -It deletes the region between the beginning position, @code{start}, -and the ending position, @code{end}. - -From the point of view of the person writing Lisp, Emacs is all very -simple; but hidden underneath is a great deal of complexity to make it -all work. - -@node defvar -@section Initializing a Variable with @code{defvar} -@findex defvar -@cindex Initializing a variable -@cindex Variable initialization - -@ignore -2006 Oct 24 -In Emacs 22, -copy-region-as-kill is short, 12 lines, and uses -filter-buffer-substring, which is longer, 39 lines -and has delete-and-extract-region in it. -delete-and-extract-region is written in C. - -see Initializing a Variable with @code{defvar} - -@end ignore - -The @code{copy-region-as-kill} function is written in Emacs Lisp. Two -functions within it, @code{kill-append} and @code{kill-new}, copy a -region in a buffer and save it in a variable called the -@code{kill-ring}. This section describes how the @code{kill-ring} -variable is created and initialized using the @code{defvar} special -form. - -(Again we note that the term @code{kill-ring} is a misnomer. The text -that is clipped out of the buffer can be brought back; it is not a ring -of corpses, but a ring of resurrectable text.) - -In Emacs Lisp, a variable such as the @code{kill-ring} is created and -given an initial value by using the @code{defvar} special form. The -name comes from ``define variable''. - -The @code{defvar} special form is similar to @code{setq} in that it sets -the value of a variable. It is unlike @code{setq} in two ways: first, -it only sets the value of the variable if the variable does not already -have a value. If the variable already has a value, @code{defvar} does -not override the existing value. Second, @code{defvar} has a -documentation string. - -(There is a related macro, @code{defcustom}, designed for variables -that people customize. It has more features than @code{defvar}. -(@xref{defcustom, , Setting Variables with @code{defcustom}}.) - -@menu -* See variable current value:: -* defvar and asterisk:: -@end menu - -@ifnottex -@node See variable current value -@unnumberedsubsec Seeing the Current Value of a Variable -@end ifnottex - -You can see the current value of a variable, any variable, by using -the @code{describe-variable} function, which is usually invoked by -typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring} -(followed by @key{RET}) when prompted, you will see what is in your -current kill ring---this may be quite a lot! Conversely, if you have -been doing nothing this Emacs session except read this document, you -may have nothing in it. Also, you will see the documentation for -@code{kill-ring}: - -@smallexample -@group -Documentation: -List of killed text sequences. -Since the kill ring is supposed to interact nicely with cut-and-paste -facilities offered by window systems, use of this variable should -@end group -@group -interact nicely with `interprogram-cut-function' and -`interprogram-paste-function'. The functions `kill-new', -`kill-append', and `current-kill' are supposed to implement this -interaction; you may want to use them instead of manipulating the kill -ring directly. -@end group -@end smallexample - -@need 800 -The kill ring is defined by a @code{defvar} in the following way: - -@smallexample -@group -(defvar kill-ring nil - "List of killed text sequences. -@dots{}") -@end group -@end smallexample - -@noindent -In this variable definition, the variable is given an initial value of -@code{nil}, which makes sense, since if you have saved nothing, you want -nothing back if you give a @code{yank} command. The documentation -string is written just like the documentation string of a @code{defun}. -As with the documentation string of the @code{defun}, the first line of -the documentation should be a complete sentence, since some commands, -like @code{apropos}, print only the first line of documentation. -Succeeding lines should not be indented; otherwise they look odd when -you use @kbd{C-h v} (@code{describe-variable}). - -@node defvar and asterisk -@subsection @code{defvar} and an asterisk -@findex defvar @r{for a user customizable variable} -@findex defvar @r{with an asterisk} - -In the past, Emacs used the @code{defvar} special form both for -internal variables that you would not expect a user to change and for -variables that you do expect a user to change. Although you can still -use @code{defvar} for user customizable variables, please use -@code{defcustom} instead, since it provides a path into -the Customization commands. (@xref{defcustom, , Specifying Variables -using @code{defcustom}}.) - -When you specified a variable using the @code{defvar} special form, -you could distinguish a variable that a user might want to change from -others by typing an asterisk, @samp{*}, in the first column of its -documentation string. For example: - -@smallexample -@group -(defvar shell-command-default-error-buffer nil - "*Buffer name for `shell-command' @dots{} error output. -@dots{} ") -@end group -@end smallexample - -@findex set-variable -@noindent -You could (and still can) use the @code{set-variable} command to -change the value of @code{shell-command-default-error-buffer} -temporarily. However, options set using @code{set-variable} are set -only for the duration of your editing session. The new values are not -saved between sessions. Each time Emacs starts, it reads the original -value, unless you change the value within your @file{.emacs} file, -either by setting it manually or by using @code{customize}. -@xref{Emacs Initialization, , Your @file{.emacs} File}. - -For me, the major use of the @code{set-variable} command is to suggest -variables that I might want to set in my @file{.emacs} file. There -are now more than 700 such variables, far too many to remember -readily. Fortunately, you can press @key{TAB} after calling the -@code{M-x set-variable} command to see the list of variables. -(@xref{Examining, , Examining and Setting Variables, emacs, -The GNU Emacs Manual}.) - -@need 1250 -@node cons & search-fwd Review -@section Review - -Here is a brief summary of some recently introduced functions. - -@table @code -@item car -@itemx cdr -@code{car} returns the first element of a list; @code{cdr} returns the -second and subsequent elements of a list. - -@need 1250 -For example: - -@smallexample -@group -(car '(1 2 3 4 5 6 7)) - @result{} 1 -(cdr '(1 2 3 4 5 6 7)) - @result{} (2 3 4 5 6 7) -@end group -@end smallexample - -@item cons -@code{cons} constructs a list by prepending its first argument to its -second argument. - -@need 1250 -For example: - -@smallexample -@group -(cons 1 '(2 3 4)) - @result{} (1 2 3 4) -@end group -@end smallexample - -@item funcall -@code{funcall} evaluates its first argument as a function. It passes -its remaining arguments to its first argument. - -@item nthcdr -Return the result of taking @sc{cdr} `n' times on a list. -@iftex -The -@tex -$n^{th}$ -@end tex -@code{cdr}. -@end iftex -The `rest of the rest', as it were. - -@need 1250 -For example: - -@smallexample -@group -(nthcdr 3 '(1 2 3 4 5 6 7)) - @result{} (4 5 6 7) -@end group -@end smallexample - -@item setcar -@itemx setcdr -@code{setcar} changes the first element of a list; @code{setcdr} -changes the second and subsequent elements of a list. - -@need 1250 -For example: - -@smallexample -@group -(setq triple '(1 2 3)) - -(setcar triple '37) - -triple - @result{} (37 2 3) - -(setcdr triple '("foo" "bar")) - -triple - @result{} (37 "foo" "bar") -@end group -@end smallexample - -@item progn -Evaluate each argument in sequence and then return the value of the -last. - -@need 1250 -For example: - -@smallexample -@group -(progn 1 2 3 4) - @result{} 4 -@end group -@end smallexample - -@item save-restriction -Record whatever narrowing is in effect in the current buffer, if any, -and restore that narrowing after evaluating the arguments. - -@item search-forward -Search for a string, and if the string is found, move point. With a -regular expression, use the similar @code{re-search-forward}. -(@xref{Regexp Search, , Regular Expression Searches}, for an -explanation of regular expression patterns and searches.) - -@need 1250 -@noindent -@code{search-forward} and @code{re-search-forward} take four -arguments: - -@enumerate -@item -The string or regular expression to search for. - -@item -Optionally, the limit of the search. - -@item -Optionally, what to do if the search fails, return @code{nil} or an -error message. - -@item -Optionally, how many times to repeat the search; if negative, the -search goes backwards. -@end enumerate - -@item kill-region -@itemx delete-and-extract-region -@itemx copy-region-as-kill - -@code{kill-region} cuts the text between point and mark from the -buffer and stores that text in the kill ring, so you can get it back -by yanking. - -@code{copy-region-as-kill} copies the text between point and mark into -the kill ring, from which you can get it by yanking. The function -does not cut or remove the text from the buffer. -@end table - -@code{delete-and-extract-region} removes the text between point and -mark from the buffer and throws it away. You cannot get it back. -(This is not an interactive command.) - -@need 1500 -@node search Exercises -@section Searching Exercises - -@itemize @bullet -@item -Write an interactive function that searches for a string. If the -search finds the string, leave point after it and display a message -that says ``Found!''. (Do not use @code{search-forward} for the name -of this function; if you do, you will overwrite the existing version of -@code{search-forward} that comes with Emacs. Use a name such as -@code{test-search} instead.) - -@item -Write a function that prints the third element of the kill ring in the -echo area, if any; if the kill ring does not contain a third element, -print an appropriate message. -@end itemize - -@node List Implementation -@chapter How Lists are Implemented -@cindex Lists in a computer - -In Lisp, atoms are recorded in a straightforward fashion; if the -implementation is not straightforward in practice, it is, nonetheless, -straightforward in theory. The atom @samp{rose}, for example, is -recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s}, -@samp{e}. A list, on the other hand, is kept differently. The mechanism -is equally simple, but it takes a moment to get used to the idea. A -list is kept using a series of pairs of pointers. In the series, the -first pointer in each pair points to an atom or to another list, and the -second pointer in each pair points to the next pair, or to the symbol -@code{nil}, which marks the end of the list. - -A pointer itself is quite simply the electronic address of what is -pointed to. Hence, a list is kept as a series of electronic addresses. - -@menu -* Lists diagrammed:: -* Symbols as Chest:: Exploring a powerful metaphor. -* List Exercise:: -@end menu - -@ifnottex -@node Lists diagrammed -@unnumberedsec Lists diagrammed -@end ifnottex - -For example, the list @code{(rose violet buttercup)} has three elements, -@samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the -electronic address of @samp{rose} is recorded in a segment of computer -memory along with the address that gives the electronic address of where -the atom @samp{violet} is located; and that address (the one that tells -where @samp{violet} is located) is kept along with an address that tells -where the address for the atom @samp{buttercup} is located. - -@need 1200 -This sounds more complicated than it is and is easier seen in a diagram: - -@c clear print-postscript-figures -@c !!! cons-cell-diagram #1 -@ifnottex -@smallexample -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-1} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -In the diagram, each box represents a word of computer memory that -holds a Lisp object, usually in the form of a memory address. The boxes, -i.e., the addresses, are in pairs. Each arrow points to what the address -is the address of, either an atom or another pair of addresses. The -first box is the electronic address of @samp{rose} and the arrow points -to @samp{rose}; the second box is the address of the next pair of boxes, -the first part of which is the address of @samp{violet} and the second -part of which is the address of the next pair. The very last box -points to the symbol @code{nil}, which marks the end of the list. - -@need 1200 -When a variable is set to a list with a function such as @code{setq}, -it stores the address of the first box in the variable. Thus, -evaluation of the expression - -@smallexample -(setq bouquet '(rose violet buttercup)) -@end smallexample - -@need 1250 -@noindent -creates a situation like this: - -@c cons-cell-diagram #2 -@ifnottex -@smallexample -@group -bouquet - | - | ___ ___ ___ ___ ___ ___ - --> |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-2} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -bouquet - | - | ___ ___ ___ ___ ___ ___ - --> |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -In this example, the symbol @code{bouquet} holds the address of the first -pair of boxes. - -@need 1200 -This same list can be illustrated in a different sort of box notation -like this: - -@c cons-cell-diagram #2a -@ifnottex -@smallexample -@group -bouquet - | - | -------------- --------------- ---------------- - | | car | cdr | | car | cdr | | car | cdr | - -->| rose | o------->| violet | o------->| butter- | nil | - | | | | | | | cup | | - -------------- --------------- ---------------- -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-2a} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -bouquet - | - | -------------- --------------- ---------------- - | | car | cdr | | car | cdr | | car | cdr | - -->| rose | o------->| violet | o------->| butter- | nil | - | | | | | | | cup | | - -------------- --------------- ---------------- -@end group -@end smallexample -@end iftex -@end ifclear - -(Symbols consist of more than pairs of addresses, but the structure of -a symbol is made up of addresses. Indeed, the symbol @code{bouquet} -consists of a group of address-boxes, one of which is the address of -the printed word @samp{bouquet}, a second of which is the address of a -function definition attached to the symbol, if any, a third of which -is the address of the first pair of address-boxes for the list -@code{(rose violet buttercup)}, and so on. Here we are showing that -the symbol's third address-box points to the first pair of -address-boxes for the list.) - -If a symbol is set to the @sc{cdr} of a list, the list itself is not -changed; the symbol simply has an address further down the list. (In -the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus, -evaluation of the following expression - -@smallexample -(setq flowers (cdr bouquet)) -@end smallexample - -@need 800 -@noindent -produces this: - -@c cons-cell-diagram #3 -@ifnottex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ | ___ ___ ___ ___ - --> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-3} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ | ___ ___ ___ ___ - --> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@noindent -The value of @code{flowers} is @code{(violet buttercup)}, which is -to say, the symbol @code{flowers} holds the address of the pair of -address-boxes, the first of which holds the address of @code{violet}, -and the second of which holds the address of @code{buttercup}. - -A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted -pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp -Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair -Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more -information about cons cells and dotted pairs. - -@need 1200 -The function @code{cons} adds a new pair of addresses to the front of -a series of addresses like that shown above. For example, evaluating -the expression - -@smallexample -(setq bouquet (cons 'lily bouquet)) -@end smallexample - -@need 1500 -@noindent -produces: - -@c cons-cell-diagram #4 -@ifnottex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ ___ ___ | ___ ___ ___ ___ - --> | | | | | | --> | | | | | | - |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil - | | | | - | | | | - --> lily --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-4} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ ___ ___ | ___ ___ ___ ___ - --> | | | | | | --> | | | | | | - |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil - | | | | - | | | | - --> lily --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@need 1200 -@noindent -However, this does not change the value of the symbol -@code{flowers}, as you can see by evaluating the following, - -@smallexample -(eq (cdr (cdr bouquet)) flowers) -@end smallexample - -@noindent -which returns @code{t} for true. - -Until it is reset, @code{flowers} still has the value -@code{(violet buttercup)}; that is, it has the address of the cons -cell whose first address is of @code{violet}. Also, this does not -alter any of the pre-existing cons cells; they are all still there. - -Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address -of the next cons cell in the series; to get the @sc{car} of a list, -you get the address of the first element of the list; to @code{cons} a -new element on a list, you add a new cons cell to the front of the list. -That is all there is to it! The underlying structure of Lisp is -brilliantly simple! - -And what does the last address in a series of cons cells refer to? It -is the address of the empty list, of @code{nil}. - -In summary, when a Lisp variable is set to a value, it is provided with -the address of the list to which the variable refers. - -@node Symbols as Chest -@section Symbols as a Chest of Drawers -@cindex Symbols as a Chest of Drawers -@cindex Chest of Drawers, metaphor for a symbol -@cindex Drawers, Chest of, metaphor for a symbol - -In an earlier section, I suggested that you might imagine a symbol as -being a chest of drawers. The function definition is put in one -drawer, the value in another, and so on. What is put in the drawer -holding the value can be changed without affecting the contents of the -drawer holding the function definition, and vice versa. - -Actually, what is put in each drawer is the address of the value or -function definition. It is as if you found an old chest in the attic, -and in one of its drawers you found a map giving you directions to -where the buried treasure lies. - -(In addition to its name, symbol definition, and variable value, a -symbol has a `drawer' for a @dfn{property list} which can be used to -record other information. Property lists are not discussed here; see -@ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp -Reference Manual}.) - -@need 1500 -Here is a fanciful representation: - -@c chest-of-drawers diagram -@ifnottex -@sp 1 -@smallexample -@group - Chest of Drawers Contents of Drawers - - __ o0O0o __ - / \ - --------------------- - | directions to | [map to] - | symbol name | bouquet - | | - +---------------------+ - | directions to | - | symbol definition | [none] - | | - +---------------------+ - | directions to | [map to] - | variable value | (rose violet buttercup) - | | - +---------------------+ - | directions to | - | property list | [not described here] - | | - +---------------------+ - |/ \| -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{drawers} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group - Chest of Drawers Contents of Drawers - - __ o0O0o __ - / \ - --------------------- - | directions to | [map to] - | symbol name | bouquet - | | - +---------------------+ - | directions to | - | symbol definition | [none] - | | - +---------------------+ - | directions to | [map to] - | variable value | (rose violet buttercup) - | | - +---------------------+ - | directions to | - | property list | [not described here] - | | - +---------------------+ - |/ \| -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@node List Exercise -@section Exercise - -Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two -more flowers on to this list and set this new list to -@code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish. -What does the @code{more-flowers} list now contain? - -@node Yanking -@chapter Yanking Text Back -@findex yank -@cindex Text retrieval -@cindex Retrieving text -@cindex Pasting text - -Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, -you can bring it back with a `yank' command. The text that is cut out of -the buffer is put in the kill ring and the yank commands insert the -appropriate contents of the kill ring back into a buffer (not necessarily -the original buffer). - -A simple @kbd{C-y} (@code{yank}) command inserts the first item from -the kill ring into the current buffer. If the @kbd{C-y} command is -followed immediately by @kbd{M-y}, the first element is replaced by -the second element. Successive @kbd{M-y} commands replace the second -element with the third, fourth, or fifth element, and so on. When the -last element in the kill ring is reached, it is replaced by the first -element and the cycle is repeated. (Thus the kill ring is called a -`ring' rather than just a `list'. However, the actual data structure -that holds the text is a list. -@xref{Kill Ring, , Handling the Kill Ring}, for the details of how the -list is handled as a ring.) - -@menu -* Kill Ring Overview:: -* kill-ring-yank-pointer:: The kill ring is a list. -* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. -@end menu - -@node Kill Ring Overview -@section Kill Ring Overview -@cindex Kill ring overview - -The kill ring is a list of textual strings. This is what it looks like: - -@smallexample -("some text" "a different piece of text" "yet more text") -@end smallexample - -If this were the contents of my kill ring and I pressed @kbd{C-y}, the -string of characters saying @samp{some text} would be inserted in this -buffer where my cursor is located. - -The @code{yank} command is also used for duplicating text by copying it. -The copied text is not cut from the buffer, but a copy of it is put on the -kill ring and is inserted by yanking it back. - -Three functions are used for bringing text back from the kill ring: -@code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop}, -which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer}, -which is used by the two other functions. - -These functions refer to the kill ring through a variable called the -@code{kill-ring-yank-pointer}. Indeed, the insertion code for both the -@code{yank} and @code{yank-pop} functions is: - -@smallexample -(insert (car kill-ring-yank-pointer)) -@end smallexample - -@noindent -(Well, no more. In GNU Emacs 22, the function has been replaced by -@code{insert-for-yank} which calls @code{insert-for-yank-1} -repetitively for each @code{yank-handler} segment. In turn, -@code{insert-for-yank-1} strips text properties from the inserted text -according to @code{yank-excluded-properties}. Otherwise, it is just -like @code{insert}. We will stick with plain @code{insert} since it -is easier to understand.) - -To begin to understand how @code{yank} and @code{yank-pop} work, it is -first necessary to look at the @code{kill-ring-yank-pointer} variable. - -@node kill-ring-yank-pointer -@section The @code{kill-ring-yank-pointer} Variable - -@code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is -a variable. It points to something by being bound to the value of what -it points to, like any other Lisp variable. - -@need 1000 -Thus, if the value of the kill ring is: - -@smallexample -("some text" "a different piece of text" "yet more text") -@end smallexample - -@need 1250 -@noindent -and the @code{kill-ring-yank-pointer} points to the second clause, the -value of @code{kill-ring-yank-pointer} is: - -@smallexample -("a different piece of text" "yet more text") -@end smallexample - -As explained in the previous chapter (@pxref{List Implementation}), the -computer does not keep two different copies of the text being pointed to -by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The -words ``a different piece of text'' and ``yet more text'' are not -duplicated. Instead, the two Lisp variables point to the same pieces of -text. Here is a diagram: - -@c cons-cell-diagram #5 -@ifnottex -@smallexample -@group -kill-ring kill-ring-yank-pointer - | | - | ___ ___ | ___ ___ ___ ___ - ---> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - | | --> "yet more text" - | | - | --> "a different piece of text" - | - --> "some text" -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-5} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -kill-ring kill-ring-yank-pointer - | | - | ___ ___ | ___ ___ ___ ___ - ---> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - | | --> "yet more text" - | | - | --> "a different piece of text - | - --> "some text" -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -Both the variable @code{kill-ring} and the variable -@code{kill-ring-yank-pointer} are pointers. But the kill ring itself is -usually described as if it were actually what it is composed of. The -@code{kill-ring} is spoken of as if it were the list rather than that it -points to the list. Conversely, the @code{kill-ring-yank-pointer} is -spoken of as pointing to a list. - -These two ways of talking about the same thing sound confusing at first but -make sense on reflection. The kill ring is generally thought of as the -complete structure of data that holds the information of what has recently -been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer} -on the other hand, serves to indicate---that is, to `point to'---that part -of the kill ring of which the first element (the @sc{car}) will be -inserted. - -@ignore -In GNU Emacs 22, the @code{kill-new} function calls - -@code{(setq kill-ring-yank-pointer kill-ring)} - -(defun rotate-yank-pointer (arg) - "Rotate the yanking point in the kill ring. -With argument, rotate that many kills forward (or backward, if negative)." - (interactive "p") - (current-kill arg)) - -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." - (let ((interprogram-paste (and (= n 0) - interprogram-paste-function - (funcall interprogram-paste-function)))) - (if interprogram-paste - (progn - ;; Disable the interprogram cut function when we add the new - ;; text to the kill ring, so Emacs doesn't try to own the - ;; selection, with identical text. - (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) - (or kill-ring (error "Kill ring is empty")) - (let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element))))) - -@end ignore - -@need 1500 -@node yank nthcdr Exercises -@section Exercises with @code{yank} and @code{nthcdr} - -@itemize @bullet -@item -Using @kbd{C-h v} (@code{describe-variable}), look at the value of -your kill ring. Add several items to your kill ring; look at its -value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way -around the kill ring. How many items were in your kill ring? Find -the value of @code{kill-ring-max}. Was your kill ring full, or could -you have kept more blocks of text within it? - -@item -Using @code{nthcdr} and @code{car}, construct a series of expressions -to return the first, second, third, and fourth elements of a list. -@end itemize - -@node Loops & Recursion -@chapter Loops and Recursion -@cindex Loops and recursion -@cindex Recursion and loops -@cindex Repetition (loops) - -Emacs Lisp has two primary ways to cause an expression, or a series of -expressions, to be evaluated repeatedly: one uses a @code{while} -loop, and the other uses @dfn{recursion}. - -Repetition can be very valuable. For example, to move forward four -sentences, you need only write a program that will move forward one -sentence and then repeat the process four times. Since a computer does -not get bored or tired, such repetitive action does not have the -deleterious effects that excessive or the wrong kinds of repetition can -have on humans. - -People mostly write Emacs Lisp functions using @code{while} loops and -their kin; but you can use recursion, which provides a very powerful -way to think about and then to solve problems@footnote{You can write -recursive functions to be frugal or wasteful of mental or computer -resources; as it happens, methods that people find easy---that are -frugal of `mental resources'---sometimes use considerable computer -resources. Emacs was designed to run on machines that we now consider -limited and its default settings are conservative. You may want to -increase the values of @code{max-specpdl-size} and -@code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to -15 and 30 times their default value.}. - -@menu -* while:: Causing a stretch of code to repeat. -* dolist dotimes:: -* Recursion:: Causing a function to call itself. -* Looping exercise:: -@end menu - -@node while -@section @code{while} -@cindex Loops -@findex while - -The @code{while} special form tests whether the value returned by -evaluating its first argument is true or false. This is similar to what -the Lisp interpreter does with an @code{if}; what the interpreter does -next, however, is different. - -In a @code{while} expression, if the value returned by evaluating the -first argument is false, the Lisp interpreter skips the rest of the -expression (the @dfn{body} of the expression) and does not evaluate it. -However, if the value is true, the Lisp interpreter evaluates the body -of the expression and then again tests whether the first argument to -@code{while} is true or false. If the value returned by evaluating the -first argument is again true, the Lisp interpreter again evaluates the -body of the expression. - -@need 1200 -The template for a @code{while} expression looks like this: - -@smallexample -@group -(while @var{true-or-false-test} - @var{body}@dots{}) -@end group -@end smallexample - -@menu -* Looping with while:: Repeat so long as test returns true. -* Loop Example:: A @code{while} loop that uses a list. -* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. -* Incrementing Loop:: A loop with an incrementing counter. -* Incrementing Loop Details:: -* Decrementing Loop:: A loop with a decrementing counter. -@end menu - -@ifnottex -@node Looping with while -@unnumberedsubsec Looping with @code{while} -@end ifnottex - -So long as the true-or-false-test of the @code{while} expression -returns a true value when it is evaluated, the body is repeatedly -evaluated. This process is called a loop since the Lisp interpreter -repeats the same thing again and again, like an airplane doing a loop. -When the result of evaluating the true-or-false-test is false, the -Lisp interpreter does not evaluate the rest of the @code{while} -expression and `exits the loop'. - -Clearly, if the value returned by evaluating the first argument to -@code{while} is always true, the body following will be evaluated -again and again @dots{} and again @dots{} forever. Conversely, if the -value returned is never true, the expressions in the body will never -be evaluated. The craft of writing a @code{while} loop consists of -choosing a mechanism such that the true-or-false-test returns true -just the number of times that you want the subsequent expressions to -be evaluated, and then have the test return false. - -The value returned by evaluating a @code{while} is the value of the -true-or-false-test. An interesting consequence of this is that a -@code{while} loop that evaluates without error will return @code{nil} -or false regardless of whether it has looped 1 or 100 times or none at -all. A @code{while} expression that evaluates successfully never -returns a true value! What this means is that @code{while} is always -evaluated for its side effects, which is to say, the consequences of -evaluating the expressions within the body of the @code{while} loop. -This makes sense. It is not the mere act of looping that is desired, -but the consequences of what happens when the expressions in the loop -are repeatedly evaluated. - -@node Loop Example -@subsection A @code{while} Loop and a List - -A common way to control a @code{while} loop is to test whether a list -has any elements. If it does, the loop is repeated; but if it does not, -the repetition is ended. Since this is an important technique, we will -create a short example to illustrate it. - -A simple way to test whether a list has elements is to evaluate the -list: if it has no elements, it is an empty list and will return the -empty list, @code{()}, which is a synonym for @code{nil} or false. On -the other hand, a list with elements will return those elements when it -is evaluated. Since Emacs Lisp considers as true any value that is not -@code{nil}, a list that returns elements will test true in a -@code{while} loop. - -@need 1200 -For example, you can set the variable @code{empty-list} to @code{nil} by -evaluating the following @code{setq} expression: - -@smallexample -(setq empty-list ()) -@end smallexample - -@noindent -After evaluating the @code{setq} expression, you can evaluate the -variable @code{empty-list} in the usual way, by placing the cursor after -the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your -echo area: - -@smallexample -empty-list -@end smallexample - -On the other hand, if you set a variable to be a list with elements, the -list will appear when you evaluate the variable, as you can see by -evaluating the following two expressions: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -animals -@end group -@end smallexample - -Thus, to create a @code{while} loop that tests whether there are any -items in the list @code{animals}, the first part of the loop will be -written like this: - -@smallexample -@group -(while animals - @dots{} -@end group -@end smallexample - -@noindent -When the @code{while} tests its first argument, the variable -@code{animals} is evaluated. It returns a list. So long as the list -has elements, the @code{while} considers the results of the test to be -true; but when the list is empty, it considers the results of the test -to be false. - -To prevent the @code{while} loop from running forever, some mechanism -needs to be provided to empty the list eventually. An oft-used -technique is to have one of the subsequent forms in the @code{while} -expression set the value of the list to be the @sc{cdr} of the list. -Each time the @code{cdr} function is evaluated, the list will be made -shorter, until eventually only the empty list will be left. At this -point, the test of the @code{while} loop will return false, and the -arguments to the @code{while} will no longer be evaluated. - -For example, the list of animals bound to the variable @code{animals} -can be set to be the @sc{cdr} of the original list with the -following expression: - -@smallexample -(setq animals (cdr animals)) -@end smallexample - -@noindent -If you have evaluated the previous expressions and then evaluate this -expression, you will see @code{(giraffe lion tiger)} appear in the echo -area. If you evaluate the expression again, @code{(lion tiger)} will -appear in the echo area. If you evaluate it again and yet again, -@code{(tiger)} appears and then the empty list, shown by @code{nil}. - -A template for a @code{while} loop that uses the @code{cdr} function -repeatedly to cause the true-or-false-test eventually to test false -looks like this: - -@smallexample -@group -(while @var{test-whether-list-is-empty} - @var{body}@dots{} - @var{set-list-to-cdr-of-list}) -@end group -@end smallexample - -This test and use of @code{cdr} can be put together in a function that -goes through a list and prints each element of the list on a line of its -own. - -@node print-elements-of-list -@subsection An Example: @code{print-elements-of-list} -@findex print-elements-of-list - -The @code{print-elements-of-list} function illustrates a @code{while} -loop with a list. - -@cindex @file{*scratch*} buffer -The function requires several lines for its output. If you are -reading this in a recent instance of GNU Emacs, -@c GNU Emacs 21, GNU Emacs 22, or a later version, -you can evaluate the following expression inside of Info, as usual. - -If you are using an earlier version of Emacs, you need to copy the -necessary expressions to your @file{*scratch*} buffer and evaluate -them there. This is because the echo area had only one line in the -earlier versions. - -You can copy the expressions by marking the beginning of the region -with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to -the end of the region and then copying the region using @kbd{M-w} -(@code{kill-ring-save}, which calls @code{copy-region-as-kill} and -then provides visual feedback). In the @file{*scratch*} -buffer, you can yank the expressions back by typing @kbd{C-y} -(@code{yank}). - -After you have copied the expressions to the @file{*scratch*} buffer, -evaluate each expression in turn. Be sure to evaluate the last -expression, @code{(print-elements-of-list animals)}, by typing -@kbd{C-u C-x C-e}, that is, by giving an argument to -@code{eval-last-sexp}. This will cause the result of the evaluation -to be printed in the @file{*scratch*} buffer instead of being printed -in the echo area. (Otherwise you will see something like this in your -echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which -each @samp{^J} stands for a `newline'.) - -@need 1500 -In a recent instance of GNU Emacs, you can evaluate these expressions -directly in the Info buffer, and the echo area will grow to show the -results. - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun print-elements-of-list (list) - "Print each element of LIST on a line of its own." - (while list - (print (car list)) - (setq list (cdr list)))) - -(print-elements-of-list animals) -@end group -@end smallexample - -@need 1200 -@noindent -When you evaluate the three expressions in sequence, you will see -this: - -@smallexample -@group -gazelle - -giraffe - -lion - -tiger -nil -@end group -@end smallexample - -Each element of the list is printed on a line of its own (that is what -the function @code{print} does) and then the value returned by the -function is printed. Since the last expression in the function is the -@code{while} loop, and since @code{while} loops always return -@code{nil}, a @code{nil} is printed after the last element of the list. - -@node Incrementing Loop -@subsection A Loop with an Incrementing Counter - -A loop is not useful unless it stops when it ought. Besides -controlling a loop with a list, a common way of stopping a loop is to -write the first argument as a test that returns false when the correct -number of repetitions are complete. This means that the loop must -have a counter---an expression that counts how many times the loop -repeats itself. - -@ifnottex -@node Incrementing Loop Details -@unnumberedsubsec Details of an Incrementing Loop -@end ifnottex - -The test for a loop with an incrementing counter can be an expression -such as @code{(< count desired-number)} which returns @code{t} for -true if the value of @code{count} is less than the -@code{desired-number} of repetitions and @code{nil} for false if the -value of @code{count} is equal to or is greater than the -@code{desired-number}. The expression that increments the count can -be a simple @code{setq} such as @code{(setq count (1+ count))}, where -@code{1+} is a built-in function in Emacs Lisp that adds 1 to its -argument. (The expression @w{@code{(1+ count)}} has the same result -as @w{@code{(+ count 1)}}, but is easier for a human to read.) - -@need 1250 -The template for a @code{while} loop controlled by an incrementing -counter looks like this: - -@smallexample -@group -@var{set-count-to-initial-value} -(while (< count desired-number) ; @r{true-or-false-test} - @var{body}@dots{} - (setq count (1+ count))) ; @r{incrementer} -@end group -@end smallexample - -@noindent -Note that you need to set the initial value of @code{count}; usually it -is set to 1. - -@menu -* Incrementing Example:: Counting pebbles in a triangle. -* Inc Example parts:: The parts of the function definition. -* Inc Example altogether:: Putting the function definition together. -@end menu - -@node Incrementing Example -@unnumberedsubsubsec Example with incrementing counter - -Suppose you are playing on the beach and decide to make a triangle of -pebbles, putting one pebble in the first row, two in the second row, -three in the third row and so on, like this: - -@sp 1 -@c pebble diagram -@ifnottex -@smallexample -@group - * - * * - * * * - * * * * -@end group -@end smallexample -@end ifnottex -@iftex -@smallexample -@group - @bullet{} - @bullet{} @bullet{} - @bullet{} @bullet{} @bullet{} - @bullet{} @bullet{} @bullet{} @bullet{} -@end group -@end smallexample -@end iftex -@sp 1 - -@noindent -(About 2500 years ago, Pythagoras and others developed the beginnings of -number theory by considering questions such as this.) - -Suppose you want to know how many pebbles you will need to make a -triangle with 7 rows? - -Clearly, what you need to do is add up the numbers from 1 to 7. There -are two ways to do this; start with the smallest number, one, and add up -the list in sequence, 1, 2, 3, 4 and so on; or start with the largest -number and add the list going down: 7, 6, 5, 4 and so on. Because both -mechanisms illustrate common ways of writing @code{while} loops, we will -create two examples, one counting up and the other counting down. In -this first example, we will start with 1 and add 2, 3, 4 and so on. - -If you are just adding up a short list of numbers, the easiest way to do -it is to add up all the numbers at once. However, if you do not know -ahead of time how many numbers your list will have, or if you want to be -prepared for a very long list, then you need to design your addition so -that what you do is repeat a simple process many times instead of doing -a more complex process once. - -For example, instead of adding up all the pebbles all at once, what you -can do is add the number of pebbles in the first row, 1, to the number -in the second row, 2, and then add the total of those two rows to the -third row, 3. Then you can add the number in the fourth row, 4, to the -total of the first three rows; and so on. - -The critical characteristic of the process is that each repetitive -action is simple. In this case, at each step we add only two numbers, -the number of pebbles in the row and the total already found. This -process of adding two numbers is repeated again and again until the last -row has been added to the total of all the preceding rows. In a more -complex loop the repetitive action might not be so simple, but it will -be simpler than doing everything all at once. - -@node Inc Example parts -@unnumberedsubsubsec The parts of the function definition - -The preceding analysis gives us the bones of our function definition: -first, we will need a variable that we can call @code{total} that will -be the total number of pebbles. This will be the value returned by -the function. - -Second, we know that the function will require an argument: this -argument will be the total number of rows in the triangle. It can be -called @code{number-of-rows}. - -Finally, we need a variable to use as a counter. We could call this -variable @code{counter}, but a better name is @code{row-number}. That -is because what the counter does in this function is count rows, and a -program should be written to be as understandable as possible. - -When the Lisp interpreter first starts evaluating the expressions in the -function, the value of @code{total} should be set to zero, since we have -not added anything to it. Then the function should add the number of -pebbles in the first row to the total, and then add the number of -pebbles in the second to the total, and then add the number of -pebbles in the third row to the total, and so on, until there are no -more rows left to add. - -Both @code{total} and @code{row-number} are used only inside the -function, so they can be declared as local variables with @code{let} -and given initial values. Clearly, the initial value for @code{total} -should be 0. The initial value of @code{row-number} should be 1, -since we start with the first row. This means that the @code{let} -statement will look like this: - -@smallexample -@group - (let ((total 0) - (row-number 1)) - @var{body}@dots{}) -@end group -@end smallexample - -After the internal variables are declared and bound to their initial -values, we can begin the @code{while} loop. The expression that serves -as the test should return a value of @code{t} for true so long as the -@code{row-number} is less than or equal to the @code{number-of-rows}. -(If the expression tests true only so long as the row number is less -than the number of rows in the triangle, the last row will never be -added to the total; hence the row number has to be either less than or -equal to the number of rows.) - -@need 1500 -@findex <= @r{(less than or equal)} -Lisp provides the @code{<=} function that returns true if the value of -its first argument is less than or equal to the value of its second -argument and false otherwise. So the expression that the @code{while} -will evaluate as its test should look like this: - -@smallexample -(<= row-number number-of-rows) -@end smallexample - -The total number of pebbles can be found by repeatedly adding the number -of pebbles in a row to the total already found. Since the number of -pebbles in the row is equal to the row number, the total can be found by -adding the row number to the total. (Clearly, in a more complex -situation, the number of pebbles in the row might be related to the row -number in a more complicated way; if this were the case, the row number -would be replaced by the appropriate expression.) - -@smallexample -(setq total (+ total row-number)) -@end smallexample - -@noindent -What this does is set the new value of @code{total} to be equal to the -sum of adding the number of pebbles in the row to the previous total. - -After setting the value of @code{total}, the conditions need to be -established for the next repetition of the loop, if there is one. This -is done by incrementing the value of the @code{row-number} variable, -which serves as a counter. After the @code{row-number} variable has -been incremented, the true-or-false-test at the beginning of the -@code{while} loop tests whether its value is still less than or equal to -the value of the @code{number-of-rows} and if it is, adds the new value -of the @code{row-number} variable to the @code{total} of the previous -repetition of the loop. - -@need 1200 -The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the -@code{row-number} variable can be incremented with this expression: - -@smallexample -(setq row-number (1+ row-number)) -@end smallexample - -@node Inc Example altogether -@unnumberedsubsubsec Putting the function definition together - -We have created the parts for the function definition; now we need to -put them together. - -@need 800 -First, the contents of the @code{while} expression: - -@smallexample -@group -(while (<= row-number number-of-rows) ; @r{true-or-false-test} - (setq total (+ total row-number)) - (setq row-number (1+ row-number))) ; @r{incrementer} -@end group -@end smallexample - -Along with the @code{let} expression varlist, this very nearly -completes the body of the function definition. However, it requires -one final element, the need for which is somewhat subtle. - -The final touch is to place the variable @code{total} on a line by -itself after the @code{while} expression. Otherwise, the value returned -by the whole function is the value of the last expression that is -evaluated in the body of the @code{let}, and this is the value -returned by the @code{while}, which is always @code{nil}. - -This may not be evident at first sight. It almost looks as if the -incrementing expression is the last expression of the whole function. -But that expression is part of the body of the @code{while}; it is the -last element of the list that starts with the symbol @code{while}. -Moreover, the whole of the @code{while} loop is a list within the body -of the @code{let}. - -@need 1250 -In outline, the function will look like this: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (let (@var{varlist}) - (while (@var{true-or-false-test}) - @var{body-of-while}@dots{} ) - @dots{} )) ; @r{Need final expression here.} -@end group -@end smallexample - -The result of evaluating the @code{let} is what is going to be returned -by the @code{defun} since the @code{let} is not embedded within any -containing list, except for the @code{defun} as a whole. However, if -the @code{while} is the last element of the @code{let} expression, the -function will always return @code{nil}. This is not what we want! -Instead, what we want is the value of the variable @code{total}. This -is returned by simply placing the symbol as the last element of the list -starting with @code{let}. It gets evaluated after the preceding -elements of the list are evaluated, which means it gets evaluated after -it has been assigned the correct value for the total. - -It may be easier to see this by printing the list starting with -@code{let} all on one line. This format makes it evident that the -@var{varlist} and @code{while} expressions are the second and third -elements of the list starting with @code{let}, and the @code{total} is -the last element: - -@smallexample -@group -(let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total) -@end group -@end smallexample - -@need 1200 -Putting everything together, the @code{triangle} function definition -looks like this: - -@smallexample -@group -(defun triangle (number-of-rows) ; @r{Version with} - ; @r{ incrementing counter.} - "Add up the number of pebbles in a triangle. -The first row has one pebble, the second row two pebbles, -the third row three pebbles, and so on. -The argument is NUMBER-OF-ROWS." -@end group -@group - (let ((total 0) - (row-number 1)) - (while (<= row-number number-of-rows) - (setq total (+ total row-number)) - (setq row-number (1+ row-number))) - total)) -@end group -@end smallexample - -@need 1200 -After you have installed @code{triangle} by evaluating the function, you -can try it out. Here are two examples: - -@smallexample -@group -(triangle 4) - -(triangle 7) -@end group -@end smallexample - -@noindent -The sum of the first four numbers is 10 and the sum of the first seven -numbers is 28. - -@node Decrementing Loop -@subsection Loop with a Decrementing Counter - -Another common way to write a @code{while} loop is to write the test -so that it determines whether a counter is greater than zero. So long -as the counter is greater than zero, the loop is repeated. But when -the counter is equal to or less than zero, the loop is stopped. For -this to work, the counter has to start out greater than zero and then -be made smaller and smaller by a form that is evaluated -repeatedly. - -The test will be an expression such as @code{(> counter 0)} which -returns @code{t} for true if the value of @code{counter} is greater -than zero, and @code{nil} for false if the value of @code{counter} is -equal to or less than zero. The expression that makes the number -smaller and smaller can be a simple @code{setq} such as @code{(setq -counter (1- counter))}, where @code{1-} is a built-in function in -Emacs Lisp that subtracts 1 from its argument. - -@need 1250 -The template for a decrementing @code{while} loop looks like this: - -@smallexample -@group -(while (> counter 0) ; @r{true-or-false-test} - @var{body}@dots{} - (setq counter (1- counter))) ; @r{decrementer} -@end group -@end smallexample - -@menu -* Decrementing Example:: More pebbles on the beach. -* Dec Example parts:: The parts of the function definition. -* Dec Example altogether:: Putting the function definition together. -@end menu - -@node Decrementing Example -@unnumberedsubsubsec Example with decrementing counter - -To illustrate a loop with a decrementing counter, we will rewrite the -@code{triangle} function so the counter decreases to zero. - -This is the reverse of the earlier version of the function. In this -case, to find out how many pebbles are needed to make a triangle with -3 rows, add the number of pebbles in the third row, 3, to the number -in the preceding row, 2, and then add the total of those two rows to -the row that precedes them, which is 1. - -Likewise, to find the number of pebbles in a triangle with 7 rows, add -the number of pebbles in the seventh row, 7, to the number in the -preceding row, which is 6, and then add the total of those two rows to -the row that precedes them, which is 5, and so on. As in the previous -example, each addition only involves adding two numbers, the total of -the rows already added up and the number of pebbles in the row that is -being added to the total. This process of adding two numbers is -repeated again and again until there are no more pebbles to add. - -We know how many pebbles to start with: the number of pebbles in the -last row is equal to the number of rows. If the triangle has seven -rows, the number of pebbles in the last row is 7. Likewise, we know how -many pebbles are in the preceding row: it is one less than the number in -the row. - -@node Dec Example parts -@unnumberedsubsubsec The parts of the function definition - -We start with three variables: the total number of rows in the -triangle; the number of pebbles in a row; and the total number of -pebbles, which is what we want to calculate. These variables can be -named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and -@code{total}, respectively. - -Both @code{total} and @code{number-of-pebbles-in-row} are used only -inside the function and are declared with @code{let}. The initial -value of @code{total} should, of course, be zero. However, the -initial value of @code{number-of-pebbles-in-row} should be equal to -the number of rows in the triangle, since the addition will start with -the longest row. - -@need 1250 -This means that the beginning of the @code{let} expression will look -like this: - -@smallexample -@group -(let ((total 0) - (number-of-pebbles-in-row number-of-rows)) - @var{body}@dots{}) -@end group -@end smallexample - -The total number of pebbles can be found by repeatedly adding the number -of pebbles in a row to the total already found, that is, by repeatedly -evaluating the following expression: - -@smallexample -(setq total (+ total number-of-pebbles-in-row)) -@end smallexample - -@noindent -After the @code{number-of-pebbles-in-row} is added to the @code{total}, -the @code{number-of-pebbles-in-row} should be decremented by one, since -the next time the loop repeats, the preceding row will be -added to the total. - -The number of pebbles in a preceding row is one less than the number of -pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be -used to compute the number of pebbles in the preceding row. This can be -done with the following expression: - -@smallexample -@group -(setq number-of-pebbles-in-row - (1- number-of-pebbles-in-row)) -@end group -@end smallexample - -Finally, we know that the @code{while} loop should stop making repeated -additions when there are no pebbles in a row. So the test for -the @code{while} loop is simply: - -@smallexample -(while (> number-of-pebbles-in-row 0) -@end smallexample - -@node Dec Example altogether -@unnumberedsubsubsec Putting the function definition together - -We can put these expressions together to create a function definition -that works. However, on examination, we find that one of the local -variables is unneeded! - -@need 1250 -The function definition looks like this: - -@smallexample -@group -;;; @r{First subtractive version.} -(defun triangle (number-of-rows) - "Add up the number of pebbles in a triangle." - (let ((total 0) - (number-of-pebbles-in-row number-of-rows)) - (while (> number-of-pebbles-in-row 0) - (setq total (+ total number-of-pebbles-in-row)) - (setq number-of-pebbles-in-row - (1- number-of-pebbles-in-row))) - total)) -@end group -@end smallexample - -As written, this function works. - -However, we do not need @code{number-of-pebbles-in-row}. - -@cindex Argument as local variable -When the @code{triangle} function is evaluated, the symbol -@code{number-of-rows} will be bound to a number, giving it an initial -value. That number can be changed in the body of the function as if -it were a local variable, without any fear that such a change will -effect the value of the variable outside of the function. This is a -very useful characteristic of Lisp; it means that the variable -@code{number-of-rows} can be used anywhere in the function where -@code{number-of-pebbles-in-row} is used. - -@need 800 -Here is a second version of the function written a bit more cleanly: - -@smallexample -@group -(defun triangle (number) ; @r{Second version.} - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (setq number (1- number))) - total)) -@end group -@end smallexample - -In brief, a properly written @code{while} loop will consist of three parts: - -@enumerate -@item -A test that will return false after the loop has repeated itself the -correct number of times. - -@item -An expression the evaluation of which will return the value desired -after being repeatedly evaluated. - -@item -An expression to change the value passed to the true-or-false-test so -that the test returns false after the loop has repeated itself the right -number of times. -@end enumerate - -@node dolist dotimes -@section Save your time: @code{dolist} and @code{dotimes} - -In addition to @code{while}, both @code{dolist} and @code{dotimes} -provide for looping. Sometimes these are quicker to write than the -equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, , -Macros, elisp, The GNU Emacs Lisp Reference Manual}. ) - -@code{dolist} works like a @code{while} loop that `@sc{cdr}s down a -list': @code{dolist} automatically shortens the list each time it -loops---takes the @sc{cdr} of the list---and binds the @sc{car} of -each shorter version of the list to the first of its arguments. - -@code{dotimes} loops a specific number of times: you specify the number. - -@menu -* dolist:: -* dotimes:: -@end menu - -@node dolist -@unnumberedsubsec The @code{dolist} Macro -@findex dolist - -Suppose, for example, you want to reverse a list, so that -``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''. - -@need 1250 -In practice, you would use the @code{reverse} function, like this: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(reverse animals) -@end group -@end smallexample - -@need 800 -@noindent -Here is how you could reverse the list using a @code{while} loop: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun reverse-list-with-while (list) - "Using while, reverse the order of LIST." - (let (value) ; make sure list starts empty - (while list - (setq value (cons (car list) value)) - (setq list (cdr list))) - value)) - -(reverse-list-with-while animals) -@end group -@end smallexample - -@need 800 -@noindent -And here is how you could use the @code{dolist} macro: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun reverse-list-with-dolist (list) - "Using dolist, reverse the order of LIST." - (let (value) ; make sure list starts empty - (dolist (element list value) - (setq value (cons element value))))) - -(reverse-list-with-dolist animals) -@end group -@end smallexample - -@need 1250 -@noindent -In Info, you can place your cursor after the closing parenthesis of -each expression and type @kbd{C-x C-e}; in each case, you should see - -@smallexample -(tiger lion giraffe gazelle) -@end smallexample - -@noindent -in the echo area. - -For this example, the existing @code{reverse} function is obviously best. -The @code{while} loop is just like our first example (@pxref{Loop -Example, , A @code{while} Loop and a List}). The @code{while} first -checks whether the list has elements; if so, it constructs a new list -by adding the first element of the list to the existing list (which in -the first iteration of the loop is @code{nil}). Since the second -element is prepended in front of the first element, and the third -element is prepended in front of the second element, the list is reversed. - -In the expression using a @code{while} loop, -the @w{@code{(setq list (cdr list))}} -expression shortens the list, so the @code{while} loop eventually -stops. In addition, it provides the @code{cons} expression with a new -first element by creating a new and shorter list at each repetition of -the loop. - -The @code{dolist} expression does very much the same as the -@code{while} expression, except that the @code{dolist} macro does some -of the work you have to do when writing a @code{while} expression. - -Like a @code{while} loop, a @code{dolist} loops. What is different is -that it automatically shortens the list each time it loops---it -`@sc{cdr}s down the list' on its own---and it automatically binds -the @sc{car} of each shorter version of the list to the first of its -arguments. - -In the example, the @sc{car} of each shorter version of the list is -referred to using the symbol @samp{element}, the list itself is called -@samp{list}, and the value returned is called @samp{value}. The -remainder of the @code{dolist} expression is the body. - -The @code{dolist} expression binds the @sc{car} of each shorter -version of the list to @code{element} and then evaluates the body of -the expression; and repeats the loop. The result is returned in -@code{value}. - -@node dotimes -@unnumberedsubsec The @code{dotimes} Macro -@findex dotimes - -The @code{dotimes} macro is similar to @code{dolist}, except that it -loops a specific number of times. - -The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 -and so forth each time around the loop, and the value of the third -argument is returned. You need to provide the value of the second -argument, which is how many times the macro loops. - -@need 1250 -For example, the following binds the numbers from 0 up to, but not -including, the number 3 to the first argument, @var{number}, and then -constructs a list of the three numbers. (The first number is 0, the -second number is 1, and the third number is 2; this makes a total of -three numbers in all, starting with zero as the first number.) - -@smallexample -@group -(let (value) ; otherwise a value is a void variable - (dotimes (number 3 value) - (setq value (cons number value)))) - -@result{} (2 1 0) -@end group -@end smallexample - -@noindent -@code{dotimes} returns @code{value}, so the way to use -@code{dotimes} is to operate on some expression @var{number} number of -times and then return the result, either as a list or an atom. - -@need 1250 -Here is an example of a @code{defun} that uses @code{dotimes} to add -up the number of pebbles in a triangle. - -@smallexample -@group -(defun triangle-using-dotimes (number-of-rows) - "Using dotimes, add up the number of pebbles in a triangle." -(let ((total 0)) ; otherwise a total is a void variable - (dotimes (number number-of-rows total) - (setq total (+ total (1+ number)))))) - -(triangle-using-dotimes 4) -@end group -@end smallexample - -@node Recursion -@section Recursion -@cindex Recursion - -A recursive function contains code that tells the Lisp interpreter to -call a program that runs exactly like itself, but with slightly -different arguments. The code runs exactly the same because it has -the same name. However, even though the program has the same name, it -is not the same entity. It is different. In the jargon, it is a -different `instance'. - -Eventually, if the program is written correctly, the `slightly -different arguments' will become sufficiently different from the first -arguments that the final instance will stop. - -@menu -* Building Robots:: Same model, different serial number ... -* Recursive Definition Parts:: Walk until you stop ... -* Recursion with list:: Using a list as the test whether to recurse. -* Recursive triangle function:: -* Recursion with cond:: -* Recursive Patterns:: Often used templates. -* No Deferment:: Don't store up work ... -* No deferment solution:: -@end menu - -@node Building Robots -@subsection Building Robots: Extending the Metaphor -@cindex Building robots -@cindex Robots, building - -It is sometimes helpful to think of a running program as a robot that -does a job. In doing its job, a recursive function calls on a second -robot to help it. The second robot is identical to the first in every -way, except that the second robot helps the first and has been -passed different arguments than the first. - -In a recursive function, the second robot may call a third; and the -third may call a fourth, and so on. Each of these is a different -entity; but all are clones. - -Since each robot has slightly different instructions---the arguments -will differ from one robot to the next---the last robot should know -when to stop. - -Let's expand on the metaphor in which a computer program is a robot. - -A function definition provides the blueprints for a robot. When you -install a function definition, that is, when you evaluate a -@code{defun} macro, you install the necessary equipment to build -robots. It is as if you were in a factory, setting up an assembly -line. Robots with the same name are built according to the same -blueprints. So they have, as it were, the same `model number', but a -different `serial number'. - -We often say that a recursive function `calls itself'. What we mean -is that the instructions in a recursive function cause the Lisp -interpreter to run a different function that has the same name and -does the same job as the first, but with different arguments. - -It is important that the arguments differ from one instance to the -next; otherwise, the process will never stop. - -@node Recursive Definition Parts -@subsection The Parts of a Recursive Definition -@cindex Parts of a Recursive Definition -@cindex Recursive Definition Parts - -A recursive function typically contains a conditional expression which -has three parts: - -@enumerate -@item -A true-or-false-test that determines whether the function is called -again, here called the @dfn{do-again-test}. - -@item -The name of the function. When this name is called, a new instance of -the function---a new robot, as it were---is created and told what to do. - -@item -An expression that returns a different value each time the function is -called, here called the @dfn{next-step-expression}. Consequently, the -argument (or arguments) passed to the new instance of the function -will be different from that passed to the previous instance. This -causes the conditional expression, the @dfn{do-again-test}, to test -false after the correct number of repetitions. -@end enumerate - -Recursive functions can be much simpler than any other kind of -function. Indeed, when people first start to use them, they often look -so mysteriously simple as to be incomprehensible. Like riding a -bicycle, reading a recursive function definition takes a certain knack -which is hard at first but then seems simple. - -@need 1200 -There are several different common recursive patterns. A very simple -pattern looks like this: - -@smallexample -@group -(defun @var{name-of-recursive-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (if @var{do-again-test} - @var{body}@dots{} - (@var{name-of-recursive-function} - @var{next-step-expression}))) -@end group -@end smallexample - -Each time a recursive function is evaluated, a new instance of it is -created and told what to do. The arguments tell the instance what to do. - -An argument is bound to the value of the next-step-expression. Each -instance runs with a different value of the next-step-expression. - -The value in the next-step-expression is used in the do-again-test. - -The value returned by the next-step-expression is passed to the new -instance of the function, which evaluates it (or some -transmogrification of it) to determine whether to continue or stop. -The next-step-expression is designed so that the do-again-test returns -false when the function should no longer be repeated. - -The do-again-test is sometimes called the @dfn{stop condition}, -since it stops the repetitions when it tests false. - -@node Recursion with list -@subsection Recursion with a List - -The example of a @code{while} loop that printed the elements of a list -of numbers can be written recursively. Here is the code, including -an expression to set the value of the variable @code{animals} to a list. - -If you are reading this in Info in Emacs, you can evaluate this -expression directly in Info. Otherwise, you must copy the example -to the @file{*scratch*} buffer and evaluate each expression there. -Use @kbd{C-u C-x C-e} to evaluate the -@code{(print-elements-recursively animals)} expression so that the -results are printed in the buffer; otherwise the Lisp interpreter will -try to squeeze the results into the one line of the echo area. - -Also, place your cursor immediately after the last closing parenthesis -of the @code{print-elements-recursively} function, before the comment. -Otherwise, the Lisp interpreter will try to evaluate the comment. - -@findex print-elements-recursively -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun print-elements-recursively (list) - "Print each element of LIST on a line of its own. -Uses recursion." - (when list ; @r{do-again-test} - (print (car list)) ; @r{body} - (print-elements-recursively ; @r{recursive call} - (cdr list)))) ; @r{next-step-expression} - -(print-elements-recursively animals) -@end group -@end smallexample - -The @code{print-elements-recursively} function first tests whether -there is any content in the list; if there is, the function prints the -first element of the list, the @sc{car} of the list. Then the -function `invokes itself', but gives itself as its argument, not the -whole list, but the second and subsequent elements of the list, the -@sc{cdr} of the list. - -Put another way, if the list is not empty, the function invokes -another instance of code that is similar to the initial code, but is a -different thread of execution, with different arguments than the first -instance. - -Put in yet another way, if the list is not empty, the first robot -assembles a second robot and tells it what to do; the second robot is -a different individual from the first, but is the same model. - -When the second evaluation occurs, the @code{when} expression is -evaluated and if true, prints the first element of the list it -receives as its argument (which is the second element of the original -list). Then the function `calls itself' with the @sc{cdr} of the list -it is invoked with, which (the second time around) is the @sc{cdr} of -the @sc{cdr} of the original list. - -Note that although we say that the function `calls itself', what we -mean is that the Lisp interpreter assembles and instructs a new -instance of the program. The new instance is a clone of the first, -but is a separate individual. - -Each time the function `invokes itself', it invokes itself on a -shorter version of the original list. It creates a new instance that -works on a shorter list. - -Eventually, the function invokes itself on an empty list. It creates -a new instance whose argument is @code{nil}. The conditional expression -tests the value of @code{list}. Since the value of @code{list} is -@code{nil}, the @code{when} expression tests false so the then-part is -not evaluated. The function as a whole then returns @code{nil}. - -@need 1200 -When you evaluate the expression @code{(print-elements-recursively -animals)} in the @file{*scratch*} buffer, you see this result: - -@smallexample -@group -gazelle - -giraffe - -lion - -tiger -nil -@end group -@end smallexample - -@need 2000 -@node Recursive triangle function -@subsection Recursion in Place of a Counter -@findex triangle-recursively - -@need 1200 -The @code{triangle} function described in a previous section can also -be written recursively. It looks like this: - -@smallexample -@group -(defun triangle-recursively (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) ; @r{do-again-test} - 1 ; @r{then-part} - (+ number ; @r{else-part} - (triangle-recursively ; @r{recursive call} - (1- number))))) ; @r{next-step-expression} - -(triangle-recursively 7) -@end group -@end smallexample - -@noindent -You can install this function by evaluating it and then try it by -evaluating @code{(triangle-recursively 7)}. (Remember to put your -cursor immediately after the last parenthesis of the function -definition, before the comment.) The function evaluates to 28. - -To understand how this function works, let's consider what happens in the -various cases when the function is passed 1, 2, 3, or 4 as the value of -its argument. - -@menu -* Recursive Example arg of 1 or 2:: -* Recursive Example arg of 3 or 4:: -@end menu - -@ifnottex -@node Recursive Example arg of 1 or 2 -@unnumberedsubsubsec An argument of 1 or 2 -@end ifnottex - -First, what happens if the value of the argument is 1? - -The function has an @code{if} expression after the documentation -string. It tests whether the value of @code{number} is equal to 1; if -so, Emacs evaluates the then-part of the @code{if} expression, which -returns the number 1 as the value of the function. (A triangle with -one row has one pebble in it.) - -Suppose, however, that the value of the argument is 2. In this case, -Emacs evaluates the else-part of the @code{if} expression. - -@need 1200 -The else-part consists of an addition, the recursive call to -@code{triangle-recursively} and a decrementing action; and it looks like -this: - -@smallexample -(+ number (triangle-recursively (1- number))) -@end smallexample - -When Emacs evaluates this expression, the innermost expression is -evaluated first; then the other parts in sequence. Here are the steps -in detail: - -@table @i -@item Step 1 @w{ } Evaluate the innermost expression. - -The innermost expression is @code{(1- number)} so Emacs decrements the -value of @code{number} from 2 to 1. - -@item Step 2 @w{ } Evaluate the @code{triangle-recursively} function. - -The Lisp interpreter creates an individual instance of -@code{triangle-recursively}. It does not matter that this function is -contained within itself. Emacs passes the result Step 1 as the -argument used by this instance of the @code{triangle-recursively} -function - -In this case, Emacs evaluates @code{triangle-recursively} with an -argument of 1. This means that this evaluation of -@code{triangle-recursively} returns 1. - -@item Step 3 @w{ } Evaluate the value of @code{number}. - -The variable @code{number} is the second element of the list that -starts with @code{+}; its value is 2. - -@item Step 4 @w{ } Evaluate the @code{+} expression. - -The @code{+} expression receives two arguments, the first -from the evaluation of @code{number} (Step 3) and the second from the -evaluation of @code{triangle-recursively} (Step 2). - -The result of the addition is the sum of 2 plus 1, and the number 3 is -returned, which is correct. A triangle with two rows has three -pebbles in it. -@end table - -@node Recursive Example arg of 3 or 4 -@unnumberedsubsubsec An argument of 3 or 4 - -Suppose that @code{triangle-recursively} is called with an argument of -3. - -@table @i -@item Step 1 @w{ } Evaluate the do-again-test. - -The @code{if} expression is evaluated first. This is the do-again -test and returns false, so the else-part of the @code{if} expression -is evaluated. (Note that in this example, the do-again-test causes -the function to call itself when it tests false, not when it tests -true.) - -@item Step 2 @w{ } Evaluate the innermost expression of the else-part. - -The innermost expression of the else-part is evaluated, which decrements -3 to 2. This is the next-step-expression. - -@item Step 3 @w{ } Evaluate the @code{triangle-recursively} function. - -The number 2 is passed to the @code{triangle-recursively} function. - -We already know what happens when Emacs evaluates @code{triangle-recursively} with -an argument of 2. After going through the sequence of actions described -earlier, it returns a value of 3. So that is what will happen here. - -@item Step 4 @w{ } Evaluate the addition. - -3 will be passed as an argument to the addition and will be added to the -number with which the function was called, which is 3. -@end table - -@noindent -The value returned by the function as a whole will be 6. - -Now that we know what will happen when @code{triangle-recursively} is -called with an argument of 3, it is evident what will happen if it is -called with an argument of 4: - -@quotation -@need 800 -In the recursive call, the evaluation of - -@smallexample -(triangle-recursively (1- 4)) -@end smallexample - -@need 800 -@noindent -will return the value of evaluating - -@smallexample -(triangle-recursively 3) -@end smallexample - -@noindent -which is 6 and this value will be added to 4 by the addition in the -third line. -@end quotation - -@noindent -The value returned by the function as a whole will be 10. - -Each time @code{triangle-recursively} is evaluated, it evaluates a -version of itself---a different instance of itself---with a smaller -argument, until the argument is small enough so that it does not -evaluate itself. - -Note that this particular design for a recursive function -requires that operations be deferred. - -Before @code{(triangle-recursively 7)} can calculate its answer, it -must call @code{(triangle-recursively 6)}; and before -@code{(triangle-recursively 6)} can calculate its answer, it must call -@code{(triangle-recursively 5)}; and so on. That is to say, the -calculation that @code{(triangle-recursively 7)} makes must be -deferred until @code{(triangle-recursively 6)} makes its calculation; -and @code{(triangle-recursively 6)} must defer until -@code{(triangle-recursively 5)} completes; and so on. - -If each of these instances of @code{triangle-recursively} are thought -of as different robots, the first robot must wait for the second to -complete its job, which must wait until the third completes, and so -on. - -There is a way around this kind of waiting, which we will discuss in -@ref{No Deferment, , Recursion without Deferments}. - -@node Recursion with cond -@subsection Recursion Example Using @code{cond} -@findex cond - -The version of @code{triangle-recursively} described earlier is written -with the @code{if} special form. It can also be written using another -special form called @code{cond}. The name of the special form -@code{cond} is an abbreviation of the word @samp{conditional}. - -Although the @code{cond} special form is not used as often in the -Emacs Lisp sources as @code{if}, it is used often enough to justify -explaining it. - -@need 800 -The template for a @code{cond} expression looks like this: - -@smallexample -@group -(cond - @var{body}@dots{}) -@end group -@end smallexample - -@noindent -where the @var{body} is a series of lists. - -@need 800 -Written out more fully, the template looks like this: - -@smallexample -@group -(cond - (@var{first-true-or-false-test} @var{first-consequent}) - (@var{second-true-or-false-test} @var{second-consequent}) - (@var{third-true-or-false-test} @var{third-consequent}) - @dots{}) -@end group -@end smallexample - -When the Lisp interpreter evaluates the @code{cond} expression, it -evaluates the first element (the @sc{car} or true-or-false-test) of -the first expression in a series of expressions within the body of the -@code{cond}. - -If the true-or-false-test returns @code{nil} the rest of that -expression, the consequent, is skipped and the true-or-false-test of the -next expression is evaluated. When an expression is found whose -true-or-false-test returns a value that is not @code{nil}, the -consequent of that expression is evaluated. The consequent can be one -or more expressions. If the consequent consists of more than one -expression, the expressions are evaluated in sequence and the value of -the last one is returned. If the expression does not have a consequent, -the value of the true-or-false-test is returned. - -If none of the true-or-false-tests test true, the @code{cond} expression -returns @code{nil}. - -@need 1250 -Written using @code{cond}, the @code{triangle} function looks like this: - -@smallexample -@group -(defun triangle-using-cond (number) - (cond ((<= number 0) 0) - ((= number 1) 1) - ((> number 1) - (+ number (triangle-using-cond (1- number)))))) -@end group -@end smallexample - -@noindent -In this example, the @code{cond} returns 0 if the number is less than or -equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+ -number (triangle-using-cond (1- number)))} if the number is greater than -1. - -@node Recursive Patterns -@subsection Recursive Patterns -@cindex Recursive Patterns - -Here are three common recursive patterns. Each involves a list. -Recursion does not need to involve lists, but Lisp is designed for lists -and this provides a sense of its primal capabilities. - -@menu -* Every:: -* Accumulate:: -* Keep:: -@end menu - -@node Every -@unnumberedsubsubsec Recursive Pattern: @emph{every} -@cindex Every, type of recursive pattern -@cindex Recursive pattern - every - -In the @code{every} recursive pattern, an action is performed on every -element of a list. - -@need 1500 -The basic pattern is: - -@itemize @bullet -@item -If a list be empty, return @code{nil}. -@item -Else, act on the beginning of the list (the @sc{car} of the list) - @itemize @minus - @item - through a recursive call by the function on the rest (the - @sc{cdr}) of the list, - @item - and, optionally, combine the acted-on element, using @code{cons}, - with the results of acting on the rest. - @end itemize -@end itemize - -@need 1500 -Here is example: - -@smallexample -@group -(defun square-each (numbers-list) - "Square each of a NUMBERS LIST, recursively." - (if (not numbers-list) ; do-again-test - nil - (cons - (* (car numbers-list) (car numbers-list)) - (square-each (cdr numbers-list))))) ; next-step-expression -@end group - -@group -(square-each '(1 2 3)) - @result{} (1 4 9) -@end group -@end smallexample - -@need 1200 -@noindent -If @code{numbers-list} is empty, do nothing. But if it has content, -construct a list combining the square of the first number in the list -with the result of the recursive call. - -(The example follows the pattern exactly: @code{nil} is returned if -the numbers' list is empty. In practice, you would write the -conditional so it carries out the action when the numbers' list is not -empty.) - -The @code{print-elements-recursively} function (@pxref{Recursion with -list, , Recursion with a List}) is another example of an @code{every} -pattern, except in this case, rather than bring the results together -using @code{cons}, we print each element of output. - -@need 1250 -The @code{print-elements-recursively} function looks like this: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) -@end group - -@group -(defun print-elements-recursively (list) - "Print each element of LIST on a line of its own. -Uses recursion." - (when list ; @r{do-again-test} - (print (car list)) ; @r{body} - (print-elements-recursively ; @r{recursive call} - (cdr list)))) ; @r{next-step-expression} - -(print-elements-recursively animals) -@end group -@end smallexample - -@need 1500 -The pattern for @code{print-elements-recursively} is: - -@itemize @bullet -@item -When the list is empty, do nothing. -@item -But when the list has at least one element, - @itemize @minus - @item - act on the beginning of the list (the @sc{car} of the list), - @item - and make a recursive call on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@node Accumulate -@unnumberedsubsubsec Recursive Pattern: @emph{accumulate} -@cindex Accumulate, type of recursive pattern -@cindex Recursive pattern - accumulate - -Another recursive pattern is called the @code{accumulate} pattern. In -the @code{accumulate} recursive pattern, an action is performed on -every element of a list and the result of that action is accumulated -with the results of performing the action on the other elements. - -This is very like the `every' pattern using @code{cons}, except that -@code{cons} is not used, but some other combiner. - -@need 1500 -The pattern is: - -@itemize @bullet -@item -If a list be empty, return zero or some other constant. -@item -Else, act on the beginning of the list (the @sc{car} of the list), - @itemize @minus - @item - and combine that acted-on element, using @code{+} or - some other combining function, with - @item - a recursive call by the function on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@need 1500 -Here is an example: - -@smallexample -@group -(defun add-elements (numbers-list) - "Add the elements of NUMBERS-LIST together." - (if (not numbers-list) - 0 - (+ (car numbers-list) (add-elements (cdr numbers-list))))) -@end group - -@group -(add-elements '(1 2 3 4)) - @result{} 10 -@end group -@end smallexample - -@xref{Files List, , Making a List of Files}, for an example of the -accumulate pattern. - -@node Keep -@unnumberedsubsubsec Recursive Pattern: @emph{keep} -@cindex Keep, type of recursive pattern -@cindex Recursive pattern - keep - -A third recursive pattern is called the @code{keep} pattern. -In the @code{keep} recursive pattern, each element of a list is tested; -the element is acted on and the results are kept only if the element -meets a criterion. - -Again, this is very like the `every' pattern, except the element is -skipped unless it meets a criterion. - -@need 1500 -The pattern has three parts: - -@itemize @bullet -@item -If a list be empty, return @code{nil}. -@item -Else, if the beginning of the list (the @sc{car} of the list) passes - a test - @itemize @minus - @item - act on that element and combine it, using @code{cons} with - @item - a recursive call by the function on the rest (the @sc{cdr}) of the list. - @end itemize -@item -Otherwise, if the beginning of the list (the @sc{car} of the list) fails -the test - @itemize @minus - @item - skip on that element, - @item - and, recursively call the function on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@need 1500 -Here is an example that uses @code{cond}: - -@smallexample -@group -(defun keep-three-letter-words (word-list) - "Keep three letter words in WORD-LIST." - (cond - ;; First do-again-test: stop-condition - ((not word-list) nil) - - ;; Second do-again-test: when to act - ((eq 3 (length (symbol-name (car word-list)))) - ;; combine acted-on element with recursive call on shorter list - (cons (car word-list) (keep-three-letter-words (cdr word-list)))) - - ;; Third do-again-test: when to skip element; - ;; recursively call shorter list with next-step expression - (t (keep-three-letter-words (cdr word-list))))) -@end group - -@group -(keep-three-letter-words '(one two three four five six)) - @result{} (one two six) -@end group -@end smallexample - -It goes without saying that you need not use @code{nil} as the test for -when to stop; and you can, of course, combine these patterns. - -@node No Deferment -@subsection Recursion without Deferments -@cindex Deferment in recursion -@cindex Recursion without Deferments - -Let's consider again what happens with the @code{triangle-recursively} -function. We will find that the intermediate calculations are -deferred until all can be done. - -@need 800 -Here is the function definition: - -@smallexample -@group -(defun triangle-recursively (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) ; @r{do-again-test} - 1 ; @r{then-part} - (+ number ; @r{else-part} - (triangle-recursively ; @r{recursive call} - (1- number))))) ; @r{next-step-expression} -@end group -@end smallexample - -What happens when we call this function with a argument of 7? - -The first instance of the @code{triangle-recursively} function adds -the number 7 to the value returned by a second instance of -@code{triangle-recursively}, an instance that has been passed an -argument of 6. That is to say, the first calculation is: - -@smallexample -(+ 7 (triangle-recursively 6)) -@end smallexample - -@noindent -The first instance of @code{triangle-recursively}---you may want to -think of it as a little robot---cannot complete its job. It must hand -off the calculation for @code{(triangle-recursively 6)} to a second -instance of the program, to a second robot. This second individual is -completely different from the first one; it is, in the jargon, a -`different instantiation'. Or, put another way, it is a different -robot. It is the same model as the first; it calculates triangle -numbers recursively; but it has a different serial number. - -And what does @code{(triangle-recursively 6)} return? It returns the -number 6 added to the value returned by evaluating -@code{triangle-recursively} with an argument of 5. Using the robot -metaphor, it asks yet another robot to help it. - -@need 800 -Now the total is: - -@smallexample -(+ 7 6 (triangle-recursively 5)) -@end smallexample - -@need 800 -And what happens next? - -@smallexample -(+ 7 6 5 (triangle-recursively 4)) -@end smallexample - -Each time @code{triangle-recursively} is called, except for the last -time, it creates another instance of the program---another robot---and -asks it to make a calculation. - -@need 800 -Eventually, the full addition is set up and performed: - -@smallexample -(+ 7 6 5 4 3 2 1) -@end smallexample - -This design for the function defers the calculation of the first step -until the second can be done, and defers that until the third can be -done, and so on. Each deferment means the computer must remember what -is being waited on. This is not a problem when there are only a few -steps, as in this example. But it can be a problem when there are -more steps. - -@node No deferment solution -@subsection No Deferment Solution -@cindex No deferment solution -@cindex Solution without deferment - -The solution to the problem of deferred operations is to write in a -manner that does not defer operations@footnote{The phrase @dfn{tail -recursive} is used to describe such a process, one that uses -`constant space'.}. This requires -writing to a different pattern, often one that involves writing two -function definitions, an `initialization' function and a `helper' -function. - -The `initialization' function sets up the job; the `helper' function -does the work. - -@need 1200 -Here are the two function definitions for adding up numbers. They are -so simple, I find them hard to understand. - -@smallexample -@group -(defun triangle-initialization (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -This is the `initialization' component of a two function -duo that uses recursion." - (triangle-recursive-helper 0 0 number)) -@end group -@end smallexample - -@smallexample -@group -(defun triangle-recursive-helper (sum counter number) - "Return SUM, using COUNTER, through NUMBER inclusive. -This is the `helper' component of a two function duo -that uses recursion." - (if (> counter number) - sum - (triangle-recursive-helper (+ sum counter) ; @r{sum} - (1+ counter) ; @r{counter} - number))) ; @r{number} -@end group -@end smallexample - -@need 1250 -Install both function definitions by evaluating them, then call -@code{triangle-initialization} with 2 rows: - -@smallexample -@group -(triangle-initialization 2) - @result{} 3 -@end group -@end smallexample - -The `initialization' function calls the first instance of the `helper' -function with three arguments: zero, zero, and a number which is the -number of rows in the triangle. - -The first two arguments passed to the `helper' function are -initialization values. These values are changed when -@code{triangle-recursive-helper} invokes new instances.@footnote{The -jargon is mildly confusing: @code{triangle-recursive-helper} uses a -process that is iterative in a procedure that is recursive. The -process is called iterative because the computer need only record the -three values, @code{sum}, @code{counter}, and @code{number}; the -procedure is recursive because the function `calls itself'. On the -other hand, both the process and the procedure used by -@code{triangle-recursively} are called recursive. The word -`recursive' has different meanings in the two contexts.} - -Let's see what happens when we have a triangle that has one row. (This -triangle will have one pebble in it!) - -@need 1200 -@code{triangle-initialization} will call its helper with -the arguments @w{@code{0 0 1}}. That function will run the conditional -test whether @code{(> counter number)}: - -@smallexample -(> 0 1) -@end smallexample - -@need 1200 -@noindent -and find that the result is false, so it will invoke -the else-part of the @code{if} clause: - -@smallexample -@group - (triangle-recursive-helper - (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} - (1+ counter) ; @r{increment counter} @result{} @r{counter} - number) ; @r{number stays the same} -@end group -@end smallexample - -@need 800 -@noindent -which will first compute: - -@smallexample -@group -(triangle-recursive-helper (+ 0 0) ; @r{sum} - (1+ 0) ; @r{counter} - 1) ; @r{number} -@exdent which is: - -(triangle-recursive-helper 0 1 1) -@end group -@end smallexample - -Again, @code{(> counter number)} will be false, so again, the Lisp -interpreter will evaluate @code{triangle-recursive-helper}, creating a -new instance with new arguments. - -@need 800 -This new instance will be; - -@smallexample -@group - (triangle-recursive-helper - (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} - (1+ counter) ; @r{increment counter} @result{} @r{counter} - number) ; @r{number stays the same} - -@exdent which is: - -(triangle-recursive-helper 1 2 1) -@end group -@end smallexample - -In this case, the @code{(> counter number)} test will be true! So the -instance will return the value of the sum, which will be 1, as -expected. - -Now, let's pass @code{triangle-initialization} an argument -of 2, to find out how many pebbles there are in a triangle with two rows. - -That function calls @code{(triangle-recursive-helper 0 0 2)}. - -@need 800 -In stages, the instances called will be: - -@smallexample -@group - @r{sum counter number} -(triangle-recursive-helper 0 1 2) - -(triangle-recursive-helper 1 2 2) - -(triangle-recursive-helper 3 3 2) -@end group -@end smallexample - -When the last instance is called, the @code{(> counter number)} test -will be true, so the instance will return the value of @code{sum}, -which will be 3. - -This kind of pattern helps when you are writing functions that can use -many resources in a computer. - -@need 1500 -@node Looping exercise -@section Looping Exercise - -@itemize @bullet -@item -Write a function similar to @code{triangle} in which each row has a -value which is the square of the row number. Use a @code{while} loop. - -@item -Write a function similar to @code{triangle} that multiplies instead of -adds the values. - -@item -Rewrite these two functions recursively. Rewrite these functions -using @code{cond}. - -@c comma in printed title causes problem in Info cross reference -@item -Write a function for Texinfo mode that creates an index entry at the -beginning of a paragraph for every @samp{@@dfn} within the paragraph. -(In a Texinfo file, @samp{@@dfn} marks a definition. This book is -written in Texinfo.) - -Many of the functions you will need are described in two of the -previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing -Text}, and @ref{Yanking, , Yanking Text Back}. If you use -@code{forward-paragraph} to put the index entry at the beginning of -the paragraph, you will have to use @w{@kbd{C-h f}} -(@code{describe-function}) to find out how to make the command go -backwards. - -For more information, see -@ifinfo -@ref{Indicating, , Indicating Definitions, texinfo}. -@end ifinfo -@ifhtml -@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to -a Texinfo manual in the current directory. Or, if you are on the -Internet, see -@uref{http://www.gnu.org/software/texinfo/manual/texinfo/} -@end ifhtml -@iftex -``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU -Documentation Format}. -@end iftex -@end itemize - -@node Regexp Search -@chapter Regular Expression Searches -@cindex Searches, illustrating -@cindex Regular expression searches -@cindex Patterns, searching for -@cindex Motion by sentence and paragraph -@cindex Sentences, movement by -@cindex Paragraphs, movement by - -Regular expression searches are used extensively in GNU Emacs. The -two functions, @code{forward-sentence} and @code{forward-paragraph}, -illustrate these searches well. They use regular expressions to find -where to move point. The phrase `regular expression' is often written -as `regexp'. - -Regular expression searches are described in @ref{Regexp Search, , -Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in -@ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference -Manual}. In writing this chapter, I am presuming that you have at -least a mild acquaintance with them. The major point to remember is -that regular expressions permit you to search for patterns as well as -for literal strings of characters. For example, the code in -@code{forward-sentence} searches for the pattern of possible -characters that could mark the end of a sentence, and moves point to -that spot. - -Before looking at the code for the @code{forward-sentence} function, it -is worth considering what the pattern that marks the end of a sentence -must be. The pattern is discussed in the next section; following that -is a description of the regular expression search function, -@code{re-search-forward}. The @code{forward-sentence} function -is described in the section following. Finally, the -@code{forward-paragraph} function is described in the last section of -this chapter. @code{forward-paragraph} is a complex function that -introduces several new features. - -@menu -* sentence-end:: The regular expression for @code{sentence-end}. -* re-search-forward:: Very similar to @code{search-forward}. -* forward-sentence:: A straightforward example of regexp search. -* forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. -* Regexp Review:: -* re-search Exercises:: -@end menu - -@node sentence-end -@section The Regular Expression for @code{sentence-end} -@findex sentence-end - -The symbol @code{sentence-end} is bound to the pattern that marks the -end of a sentence. What should this regular expression be? - -Clearly, a sentence may be ended by a period, a question mark, or an -exclamation mark. Indeed, in English, only clauses that end with one -of those three characters should be considered the end of a sentence. -This means that the pattern should include the character set: - -@smallexample -[.?!] -@end smallexample - -However, we do not want @code{forward-sentence} merely to jump to a -period, a question mark, or an exclamation mark, because such a character -might be used in the middle of a sentence. A period, for example, is -used after abbreviations. So other information is needed. - -According to convention, you type two spaces after every sentence, but -only one space after a period, a question mark, or an exclamation mark in -the body of a sentence. So a period, a question mark, or an exclamation -mark followed by two spaces is a good indicator of an end of sentence. -However, in a file, the two spaces may instead be a tab or the end of a -line. This means that the regular expression should include these three -items as alternatives. - -@need 800 -This group of alternatives will look like this: - -@smallexample -@group -\\($\\| \\| \\) - ^ ^^ - TAB SPC -@end group -@end smallexample - -@noindent -Here, @samp{$} indicates the end of the line, and I have pointed out -where the tab and two spaces are inserted in the expression. Both are -inserted by putting the actual characters into the expression. - -Two backslashes, @samp{\\}, are required before the parentheses and -vertical bars: the first backslash quotes the following backslash in -Emacs; and the second indicates that the following character, the -parenthesis or the vertical bar, is special. - -@need 1000 -Also, a sentence may be followed by one or more carriage returns, like -this: - -@smallexample -@group -[ -]* -@end group -@end smallexample - -@noindent -Like tabs and spaces, a carriage return is inserted into a regular -expression by inserting it literally. The asterisk indicates that the -@key{RET} is repeated zero or more times. - -But a sentence end does not consist only of a period, a question mark or -an exclamation mark followed by appropriate space: a closing quotation -mark or a closing brace of some kind may precede the space. Indeed more -than one such mark or brace may precede the space. These require a -expression that looks like this: - -@smallexample -[]\"')@}]* -@end smallexample - -In this expression, the first @samp{]} is the first character in the -expression; the second character is @samp{"}, which is preceded by a -@samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last -three characters are @samp{'}, @samp{)}, and @samp{@}}. - -All this suggests what the regular expression pattern for matching the -end of a sentence should be; and, indeed, if we evaluate -@code{sentence-end} we find that it returns the following value: - -@smallexample -@group -sentence-end - @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[ -]*" -@end group -@end smallexample - -@noindent -(Well, not in GNU Emacs 22; that is because of an effort to make the -process simpler and to handle more glyphs and languages. When the -value of @code{sentence-end} is @code{nil}, then use the value defined -by the function @code{sentence-end}. (Here is a use of the difference -between a value and a function in Emacs Lisp.) The function returns a -value constructed from the variables @code{sentence-end-base}, -@code{sentence-end-double-space}, @code{sentence-end-without-period}, -and @code{sentence-end-without-space}. The critical variable is -@code{sentence-end-base}; its global value is similar to the one -described above but it also contains two additional quotation marks. -These have differing degrees of curliness. The -@code{sentence-end-without-period} variable, when true, tells Emacs -that a sentence may end without a period, such as text in Thai.) - -@ignore -@noindent -(Note that here the @key{TAB}, two spaces, and @key{RET} are shown -literally in the pattern.) - -This regular expression can be deciphered as follows: - -@table @code -@item [.?!] -The first part of the pattern is the three characters, a period, a question -mark and an exclamation mark, within square brackets. The pattern must -begin with one or other of these characters. - -@item []\"')@}]* -The second part of the pattern is the group of closing braces and -quotation marks, which can appear zero or more times. These may follow -the period, question mark or exclamation mark. In a regular expression, -the backslash, @samp{\}, followed by the double quotation mark, -@samp{"}, indicates the class of string-quote characters. Usually, the -double quotation mark is the only character in this class. The -asterisk, @samp{*}, indicates that the items in the previous group (the -group surrounded by square brackets, @samp{[]}) may be repeated zero or -more times. - -@item \\($\\| \\| \\) -The third part of the pattern is one or other of: either the end of a -line, or two blank spaces, or a tab. The double back-slashes are used -to prevent Emacs from reading the parentheses and vertical bars as part -of the search pattern; the parentheses are used to mark the group and -the vertical bars are used to indicated that the patterns to either side -of them are alternatives. The dollar sign is used to indicate the end -of a line and both the two spaces and the tab are each inserted as is to -indicate what they are. - -@item [@key{RET}]* -Finally, the last part of the pattern indicates that the end of the line -or the whitespace following the period, question mark or exclamation -mark may, but need not, be followed by one or more carriage returns. In -the pattern, the carriage return is inserted as an actual carriage -return between square brackets but here it is shown as @key{RET}. -@end table -@end ignore - -@node re-search-forward -@section The @code{re-search-forward} Function -@findex re-search-forward - -The @code{re-search-forward} function is very like the -@code{search-forward} function. (@xref{search-forward, , The -@code{search-forward} Function}.) - -@code{re-search-forward} searches for a regular expression. If the -search is successful, it leaves point immediately after the last -character in the target. If the search is backwards, it leaves point -just before the first character in the target. You may tell -@code{re-search-forward} to return @code{t} for true. (Moving point -is therefore a `side effect'.) - -Like @code{search-forward}, the @code{re-search-forward} function takes -four arguments: - -@enumerate -@item -The first argument is the regular expression that the function searches -for. The regular expression will be a string between quotation marks. - -@item -The optional second argument limits how far the function will search; it is a -bound, which is specified as a position in the buffer. - -@item -The optional third argument specifies how the function responds to -failure: @code{nil} as the third argument causes the function to -signal an error (and print a message) when the search fails; any other -value causes it to return @code{nil} if the search fails and @code{t} -if the search succeeds. - -@item -The optional fourth argument is the repeat count. A negative repeat -count causes @code{re-search-forward} to search backwards. -@end enumerate - -@need 800 -The template for @code{re-search-forward} looks like this: - -@smallexample -@group -(re-search-forward "@var{regular-expression}" - @var{limit-of-search} - @var{what-to-do-if-search-fails} - @var{repeat-count}) -@end group -@end smallexample - -The second, third, and fourth arguments are optional. However, if you -want to pass a value to either or both of the last two arguments, you -must also pass a value to all the preceding arguments. Otherwise, the -Lisp interpreter will mistake which argument you are passing the value -to. - -@need 1200 -In the @code{forward-sentence} function, the regular expression will be -the value of the variable @code{sentence-end}. In simple form, that is: - -@smallexample -@group -"[.?!][]\"')@}]*\\($\\| \\| \\)[ -]*" -@end group -@end smallexample - -@noindent -The limit of the search will be the end of the paragraph (since a -sentence cannot go beyond a paragraph). If the search fails, the -function will return @code{nil}; and the repeat count will be provided -by the argument to the @code{forward-sentence} function. - -@node forward-sentence -@section @code{forward-sentence} -@findex forward-sentence - -The command to move the cursor forward a sentence is a straightforward -illustration of how to use regular expression searches in Emacs Lisp. -Indeed, the function looks longer and more complicated than it is; this -is because the function is designed to go backwards as well as forwards; -and, optionally, over more than one sentence. The function is usually -bound to the key command @kbd{M-e}. - -@menu -* Complete forward-sentence:: -* fwd-sentence while loops:: Two @code{while} loops. -* fwd-sentence re-search:: A regular expression search. -@end menu - -@ifnottex -@node Complete forward-sentence -@unnumberedsubsec Complete @code{forward-sentence} function definition -@end ifnottex - -@need 1250 -Here is the code for @code{forward-sentence}: - -@c in GNU Emacs 22 -@smallexample -@group -(defun forward-sentence (&optional arg) - "Move forward to next `sentence-end'. With argument, repeat. -With negative argument, move backward repeatedly to `sentence-beginning'. - -The variable `sentence-end' is a regular expression that matches ends of -sentences. Also, every paragraph boundary terminates sentences as well." -@end group -@group - (interactive "p") - (or arg (setq arg 1)) - (let ((opoint (point)) - (sentence-end (sentence-end))) - (while (< arg 0) - (let ((pos (point)) - (par-beg (save-excursion (start-of-paragraph-text) (point)))) - (if (and (re-search-backward sentence-end par-beg t) - (or (< (match-end 0) pos) - (re-search-backward sentence-end par-beg t))) - (goto-char (match-end 0)) - (goto-char par-beg))) - (setq arg (1+ arg))) -@end group -@group - (while (> arg 0) - (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) - (setq arg (1- arg))) - (constrain-to-field nil opoint t))) -@end group -@end smallexample - -@ignore -GNU Emacs 21 -@smallexample -@group -(defun forward-sentence (&optional arg) - "Move forward to next sentence-end. With argument, repeat. -With negative argument, move backward repeatedly to sentence-beginning. -Sentence ends are identified by the value of sentence-end -treated as a regular expression. Also, every paragraph boundary -terminates sentences as well." -@end group -@group - (interactive "p") - (or arg (setq arg 1)) - (while (< arg 0) - (let ((par-beg - (save-excursion (start-of-paragraph-text) (point)))) - (if (re-search-backward - (concat sentence-end "[^ \t\n]") par-beg t) - (goto-char (1- (match-end 0))) - (goto-char par-beg))) - (setq arg (1+ arg))) - (while (> arg 0) - (let ((par-end - (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) - (setq arg (1- arg)))) -@end group -@end smallexample -@end ignore - -The function looks long at first sight and it is best to look at its -skeleton first, and then its muscle. The way to see the skeleton is to -look at the expressions that start in the left-most columns: - -@smallexample -@group -(defun forward-sentence (&optional arg) - "@var{documentation}@dots{}" - (interactive "p") - (or arg (setq arg 1)) - (let ((opoint (point)) (sentence-end (sentence-end))) - (while (< arg 0) - (let ((pos (point)) - (par-beg (save-excursion (start-of-paragraph-text) (point)))) - @var{rest-of-body-of-while-loop-when-going-backwards} - (while (> arg 0) - (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) - @var{rest-of-body-of-while-loop-when-going-forwards} - @var{handle-forms-and-equivalent} -@end group -@end smallexample - -This looks much simpler! The function definition consists of -documentation, an @code{interactive} expression, an @code{or} -expression, a @code{let} expression, and @code{while} loops. - -Let's look at each of these parts in turn. - -We note that the documentation is thorough and understandable. - -The function has an @code{interactive "p"} declaration. This means -that the processed prefix argument, if any, is passed to the -function as its argument. (This will be a number.) If the function -is not passed an argument (it is optional) then the argument -@code{arg} will be bound to 1. - -When @code{forward-sentence} is called non-interactively without an -argument, @code{arg} is bound to @code{nil}. The @code{or} expression -handles this. What it does is either leave the value of @code{arg} as -it is, but only if @code{arg} is bound to a value; or it sets the -value of @code{arg} to 1, in the case when @code{arg} is bound to -@code{nil}. - -Next is a @code{let}. That specifies the values of two local -variables, @code{point} and @code{sentence-end}. The local value of -point, from before the search, is used in the -@code{constrain-to-field} function which handles forms and -equivalents. The @code{sentence-end} variable is set by the -@code{sentence-end} function. - -@node fwd-sentence while loops -@unnumberedsubsec The @code{while} loops - -Two @code{while} loops follow. The first @code{while} has a -true-or-false-test that tests true if the prefix argument for -@code{forward-sentence} is a negative number. This is for going -backwards. The body of this loop is similar to the body of the second -@code{while} clause, but it is not exactly the same. We will skip -this @code{while} loop and concentrate on the second @code{while} -loop. - -@need 1500 -The second @code{while} loop is for moving point forward. Its skeleton -looks like this: - -@smallexample -@group -(while (> arg 0) ; @r{true-or-false-test} - (let @var{varlist} - (if (@var{true-or-false-test}) - @var{then-part} - @var{else-part} - (setq arg (1- arg)))) ; @code{while} @r{loop decrementer} -@end group -@end smallexample - -The @code{while} loop is of the decrementing kind. -(@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It -has a true-or-false-test that tests true so long as the counter (in -this case, the variable @code{arg}) is greater than zero; and it has a -decrementer that subtracts 1 from the value of the counter every time -the loop repeats. - -If no prefix argument is given to @code{forward-sentence}, which is -the most common way the command is used, this @code{while} loop will -run once, since the value of @code{arg} will be 1. - -The body of the @code{while} loop consists of a @code{let} expression, -which creates and binds a local variable, and has, as its body, an -@code{if} expression. - -@need 1250 -The body of the @code{while} loop looks like this: - -@smallexample -@group -(let ((par-end - (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) -@end group -@end smallexample - -The @code{let} expression creates and binds the local variable -@code{par-end}. As we shall see, this local variable is designed to -provide a bound or limit to the regular expression search. If the -search fails to find a proper sentence ending in the paragraph, it will -stop on reaching the end of the paragraph. - -But first, let us examine how @code{par-end} is bound to the value of -the end of the paragraph. What happens is that the @code{let} sets the -value of @code{par-end} to the value returned when the Lisp interpreter -evaluates the expression - -@smallexample -@group -(save-excursion (end-of-paragraph-text) (point)) -@end group -@end smallexample - -@noindent -In this expression, @code{(end-of-paragraph-text)} moves point to the -end of the paragraph, @code{(point)} returns the value of point, and then -@code{save-excursion} restores point to its original position. Thus, -the @code{let} binds @code{par-end} to the value returned by the -@code{save-excursion} expression, which is the position of the end of -the paragraph. (The @code{end-of-paragraph-text} function uses -@code{forward-paragraph}, which we will discuss shortly.) - -@need 1200 -Emacs next evaluates the body of the @code{let}, which is an @code{if} -expression that looks like this: - -@smallexample -@group -(if (re-search-forward sentence-end par-end t) ; @r{if-part} - (skip-chars-backward " \t\n") ; @r{then-part} - (goto-char par-end))) ; @r{else-part} -@end group -@end smallexample - -The @code{if} tests whether its first argument is true and if so, -evaluates its then-part; otherwise, the Emacs Lisp interpreter -evaluates the else-part. The true-or-false-test of the @code{if} -expression is the regular expression search. - -It may seem odd to have what looks like the `real work' of -the @code{forward-sentence} function buried here, but this is a common -way this kind of operation is carried out in Lisp. - -@node fwd-sentence re-search -@unnumberedsubsec The regular expression search - -The @code{re-search-forward} function searches for the end of the -sentence, that is, for the pattern defined by the @code{sentence-end} -regular expression. If the pattern is found---if the end of the sentence is -found---then the @code{re-search-forward} function does two things: - -@enumerate -@item -The @code{re-search-forward} function carries out a side effect, which -is to move point to the end of the occurrence found. - -@item -The @code{re-search-forward} function returns a value of true. This is -the value received by the @code{if}, and means that the search was -successful. -@end enumerate - -@noindent -The side effect, the movement of point, is completed before the -@code{if} function is handed the value returned by the successful -conclusion of the search. - -When the @code{if} function receives the value of true from a successful -call to @code{re-search-forward}, the @code{if} evaluates the then-part, -which is the expression @code{(skip-chars-backward " \t\n")}. This -expression moves backwards over any blank spaces, tabs or carriage -returns until a printed character is found and then leaves point after -the character. Since point has already been moved to the end of the -pattern that marks the end of the sentence, this action leaves point -right after the closing printed character of the sentence, which is -usually a period. - -On the other hand, if the @code{re-search-forward} function fails to -find a pattern marking the end of the sentence, the function returns -false. The false then causes the @code{if} to evaluate its third -argument, which is @code{(goto-char par-end)}: it moves point to the -end of the paragraph. - -(And if the text is in a form or equivalent, and point may not move -fully, then the @code{constrain-to-field} function comes into play.) - -Regular expression searches are exceptionally useful and the pattern -illustrated by @code{re-search-forward}, in which the search is the -test of an @code{if} expression, is handy. You will see or write code -incorporating this pattern often. - -@node forward-paragraph -@section @code{forward-paragraph}: a Goldmine of Functions -@findex forward-paragraph - -@ignore -@c in GNU Emacs 22 -(defun forward-paragraph (&optional arg) - "Move forward to end of paragraph. -With argument ARG, do it ARG times; -a negative argument ARG = -N means move backward N paragraphs. - -A line which `paragraph-start' matches either separates paragraphs -\(if `paragraph-separate' matches it also) or is the first line of a paragraph. -A paragraph end is the beginning of a line which is not part of the paragraph -to which the end of the previous line belongs, or the end of the buffer. -Returns the count of paragraphs left to move." - (interactive "p") - (or arg (setq arg 1)) - (let* ((opoint (point)) - (fill-prefix-regexp - (and fill-prefix (not (equal fill-prefix "")) - (not paragraph-ignore-fill-prefix) - (regexp-quote fill-prefix))) - ;; Remove ^ from paragraph-start and paragraph-sep if they are there. - ;; These regexps shouldn't be anchored, because we look for them - ;; starting at the left-margin. This allows paragraph commands to - ;; work normally with indented text. - ;; This hack will not find problem cases like "whatever\\|^something". - (parstart (if (and (not (equal "" paragraph-start)) - (equal ?^ (aref paragraph-start 0))) - (substring paragraph-start 1) - paragraph-start)) - (parsep (if (and (not (equal "" paragraph-separate)) - (equal ?^ (aref paragraph-separate 0))) - (substring paragraph-separate 1) - paragraph-separate)) - (parsep - (if fill-prefix-regexp - (concat parsep "\\|" - fill-prefix-regexp "[ \t]*$") - parsep)) - ;; This is used for searching. - (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)")) - start found-start) - (while (and (< arg 0) (not (bobp))) - (if (and (not (looking-at parsep)) - (re-search-backward "^\n" (max (1- (point)) (point-min)) t) - (looking-at parsep)) - (setq arg (1+ arg)) - (setq start (point)) - ;; Move back over paragraph-separating lines. - (forward-char -1) (beginning-of-line) - (while (and (not (bobp)) - (progn (move-to-left-margin) - (looking-at parsep))) - (forward-line -1)) - (if (bobp) - nil - (setq arg (1+ arg)) - ;; Go to end of the previous (non-separating) line. - (end-of-line) - ;; Search back for line that starts or separates paragraphs. - (if (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (let (multiple-lines) - (while (and (progn (beginning-of-line) (not (bobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (looking-at fill-prefix-regexp)) - (unless (= (point) start) - (setq multiple-lines t)) - (forward-line -1)) - (move-to-left-margin) - ;; This deleted code caused a long hanging-indent line - ;; not to be filled together with the following lines. - ;; ;; Don't move back over a line before the paragraph - ;; ;; which doesn't start with fill-prefix - ;; ;; unless that is the only line we've moved over. - ;; (and (not (looking-at fill-prefix-regexp)) - ;; multiple-lines - ;; (forward-line 1)) - (not (bobp))) - (while (and (re-search-backward sp-parstart nil 1) - (setq found-start t) - ;; Found a candidate, but need to check if it is a - ;; REAL parstart. - (progn (setq start (point)) - (move-to-left-margin) - (not (looking-at parsep))) - (not (and (looking-at parstart) - (or (not use-hard-newlines) - (bobp) - (get-text-property - (1- start) 'hard))))) - (setq found-start nil) - (goto-char start)) - found-start) - ;; Found one. - (progn - ;; Move forward over paragraph separators. - ;; We know this cannot reach the place we started - ;; because we know we moved back over a non-separator. - (while (and (not (eobp)) - (progn (move-to-left-margin) - (looking-at parsep))) - (forward-line 1)) - ;; If line before paragraph is just margin, back up to there. - (end-of-line 0) - (if (> (current-column) (current-left-margin)) - (forward-char 1) - (skip-chars-backward " \t") - (if (not (bolp)) - (forward-line 1)))) - ;; No starter or separator line => use buffer beg. - (goto-char (point-min)))))) - - (while (and (> arg 0) (not (eobp))) - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) - (if (< (point) (point-max)) - (goto-char start)))) - (constrain-to-field nil opoint t) - ;; Return the number of steps that could not be done. - arg)) -@end ignore - -The @code{forward-paragraph} function moves point forward to the end -of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a -number of functions that are important in themselves, including -@code{let*}, @code{match-beginning}, and @code{looking-at}. - -The function definition for @code{forward-paragraph} is considerably -longer than the function definition for @code{forward-sentence} -because it works with a paragraph, each line of which may begin with a -fill prefix. - -A fill prefix consists of a string of characters that are repeated at -the beginning of each line. For example, in Lisp code, it is a -convention to start each line of a paragraph-long comment with -@samp{;;; }. In Text mode, four blank spaces make up another common -fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , , -emacs, The GNU Emacs Manual}, for more information about fill -prefixes.) - -The existence of a fill prefix means that in addition to being able to -find the end of a paragraph whose lines begin on the left-most -column, the @code{forward-paragraph} function must be able to find the -end of a paragraph when all or many of the lines in the buffer begin -with the fill prefix. - -Moreover, it is sometimes practical to ignore a fill prefix that -exists, especially when blank lines separate paragraphs. -This is an added complication. - -@menu -* forward-paragraph in brief:: Key parts of the function definition. -* fwd-para let:: The @code{let*} expression. -* fwd-para while:: The forward motion @code{while} loop. -@end menu - -@ifnottex -@node forward-paragraph in brief -@unnumberedsubsec Shortened @code{forward-paragraph} function definition -@end ifnottex - -Rather than print all of the @code{forward-paragraph} function, we -will only print parts of it. Read without preparation, the function -can be daunting! - -@need 800 -In outline, the function looks like this: - -@smallexample -@group -(defun forward-paragraph (&optional arg) - "@var{documentation}@dots{}" - (interactive "p") - (or arg (setq arg 1)) - (let* - @var{varlist} - (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code} - @dots{} - (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code} - @dots{} -@end group -@end smallexample - -The first parts of the function are routine: the function's argument -list consists of one optional argument. Documentation follows. - -The lower case @samp{p} in the @code{interactive} declaration means -that the processed prefix argument, if any, is passed to the function. -This will be a number, and is the repeat count of how many paragraphs -point will move. The @code{or} expression in the next line handles -the common case when no argument is passed to the function, which occurs -if the function is called from other code rather than interactively. -This case was described earlier. (@xref{forward-sentence, The -@code{forward-sentence} function}.) Now we reach the end of the -familiar part of this function. - -@node fwd-para let -@unnumberedsubsec The @code{let*} expression - -The next line of the @code{forward-paragraph} function begins a -@code{let*} expression. This is a different than @code{let}. The -symbol is @code{let*} not @code{let}. - -The @code{let*} special form is like @code{let} except that Emacs sets -each variable in sequence, one after another, and variables in the -latter part of the varlist can make use of the values to which Emacs -set variables in the earlier part of the varlist. - -@ignore -( refappend save-excursion, , code save-excursion in code append-to-buffer .) -@end ignore - -(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) - -In the @code{let*} expression in this function, Emacs binds a total of -seven variables: @code{opoint}, @code{fill-prefix-regexp}, -@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and -@code{found-start}. - -The variable @code{parsep} appears twice, first, to remove instances -of @samp{^}, and second, to handle fill prefixes. - -The variable @code{opoint} is just the value of @code{point}. As you -can guess, it is used in a @code{constrain-to-field} expression, just -as in @code{forward-sentence}. - -The variable @code{fill-prefix-regexp} is set to the value returned by -evaluating the following list: - -@smallexample -@group -(and fill-prefix - (not (equal fill-prefix "")) - (not paragraph-ignore-fill-prefix) - (regexp-quote fill-prefix)) -@end group -@end smallexample - -@noindent -This is an expression whose first element is the @code{and} special form. - -As we learned earlier (@pxref{kill-new function, , The @code{kill-new} -function}), the @code{and} special form evaluates each of its -arguments until one of the arguments returns a value of @code{nil}, in -which case the @code{and} expression returns @code{nil}; however, if -none of the arguments returns a value of @code{nil}, the value -resulting from evaluating the last argument is returned. (Since such -a value is not @code{nil}, it is considered true in Lisp.) In other -words, an @code{and} expression returns a true value only if all its -arguments are true. -@findex and - -In this case, the variable @code{fill-prefix-regexp} is bound to a -non-@code{nil} value only if the following four expressions produce a -true (i.e., a non-@code{nil}) value when they are evaluated; otherwise, -@code{fill-prefix-regexp} is bound to @code{nil}. - -@table @code -@item fill-prefix -When this variable is evaluated, the value of the fill prefix, if any, -is returned. If there is no fill prefix, this variable returns -@code{nil}. - -@item (not (equal fill-prefix "") -This expression checks whether an existing fill prefix is an empty -string, that is, a string with no characters in it. An empty string is -not a useful fill prefix. - -@item (not paragraph-ignore-fill-prefix) -This expression returns @code{nil} if the variable -@code{paragraph-ignore-fill-prefix} has been turned on by being set to a -true value such as @code{t}. - -@item (regexp-quote fill-prefix) -This is the last argument to the @code{and} special form. If all the -arguments to the @code{and} are true, the value resulting from -evaluating this expression will be returned by the @code{and} expression -and bound to the variable @code{fill-prefix-regexp}, -@end table - -@findex regexp-quote -@noindent -The result of evaluating this @code{and} expression successfully is that -@code{fill-prefix-regexp} will be bound to the value of -@code{fill-prefix} as modified by the @code{regexp-quote} function. -What @code{regexp-quote} does is read a string and return a regular -expression that will exactly match the string and match nothing else. -This means that @code{fill-prefix-regexp} will be set to a value that -will exactly match the fill prefix if the fill prefix exists. -Otherwise, the variable will be set to @code{nil}. - -The next two local variables in the @code{let*} expression are -designed to remove instances of @samp{^} from @code{parstart} and -@code{parsep}, the local variables which indicate the paragraph start -and the paragraph separator. The next expression sets @code{parsep} -again. That is to handle fill prefixes. - -This is the setting that requires the definition call @code{let*} -rather than @code{let}. The true-or-false-test for the @code{if} -depends on whether the variable @code{fill-prefix-regexp} evaluates to -@code{nil} or some other value. - -If @code{fill-prefix-regexp} does not have a value, Emacs evaluates -the else-part of the @code{if} expression and binds @code{parsep} to -its local value. (@code{parsep} is a regular expression that matches -what separates paragraphs.) - -But if @code{fill-prefix-regexp} does have a value, Emacs evaluates -the then-part of the @code{if} expression and binds @code{parsep} to a -regular expression that includes the @code{fill-prefix-regexp} as part -of the pattern. - -Specifically, @code{parsep} is set to the original value of the -paragraph separate regular expression concatenated with an alternative -expression that consists of the @code{fill-prefix-regexp} followed by -optional whitespace to the end of the line. The whitespace is defined -by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the -regexp as an alternative to @code{parsep}. - -According to a comment in the code, the next local variable, -@code{sp-parstart}, is used for searching, and then the final two, -@code{start} and @code{found-start}, are set to @code{nil}. - -Now we get into the body of the @code{let*}. The first part of the body -of the @code{let*} deals with the case when the function is given a -negative argument and is therefore moving backwards. We will skip this -section. - -@node fwd-para while -@unnumberedsubsec The forward motion @code{while} loop - -The second part of the body of the @code{let*} deals with forward -motion. It is a @code{while} loop that repeats itself so long as the -value of @code{arg} is greater than zero. In the most common use of -the function, the value of the argument is 1, so the body of the -@code{while} loop is evaluated exactly once, and the cursor moves -forward one paragraph. - -@ignore -(while (and (> arg 0) (not (eobp))) - - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) - - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) - - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) - - (if (< (point) (point-max)) - (goto-char start)))) -@end ignore - -This part handles three situations: when point is between paragraphs, -when there is a fill prefix and when there is no fill prefix. - -@need 800 -The @code{while} loop looks like this: - -@smallexample -@group -;; @r{going forwards and not at the end of the buffer} -(while (and (> arg 0) (not (eobp))) - - ;; @r{between paragraphs} - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - ;; @r{This decrements the loop} - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) -@end group - -@group - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart; - ;; we go forward line by line - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) -@end group - -@group - ;; There is no fill prefix; - ;; we go forward character by character - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) -@end group - -@group - ;; and if there is no fill prefix and if we are not at the end, - ;; go to whatever was found in the regular expression search - ;; for sp-parstart - (if (< (point) (point-max)) - (goto-char start)))) -@end group -@end smallexample - -@findex eobp -We can see that this is a decrementing counter @code{while} loop, -using the expression @code{(setq arg (1- arg))} as the decrementer. -That expression is not far from the @code{while}, but is hidden in -another Lisp macro, an @code{unless} macro. Unless we are at the end -of the buffer---that is what the @code{eobp} function determines; it -is an abbreviation of @samp{End Of Buffer P}---we decrease the value -of @code{arg} by one. - -(If we are at the end of the buffer, we cannot go forward any more and -the next loop of the @code{while} expression will test false since the -test is an @code{and} with @code{(not (eobp))}. The @code{not} -function means exactly as you expect; it is another name for -@code{null}, a function that returns true when its argument is false.) - -Interestingly, the loop count is not decremented until we leave the -space between paragraphs, unless we come to the end of buffer or stop -seeing the local value of the paragraph separator. - -That second @code{while} also has a @code{(move-to-left-margin)} -expression. The function is self-explanatory. It is inside a -@code{progn} expression and not the last element of its body, so it is -only invoked for its side effect, which is to move point to the left -margin of the current line. - -@findex looking-at -The @code{looking-at} function is also self-explanatory; it returns -true if the text after point matches the regular expression given as -its argument. - -The rest of the body of the loop looks difficult at first, but makes -sense as you come to understand it. - -@need 800 -First consider what happens if there is a fill prefix: - -@smallexample -@group - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart; - ;; we go forward line by line - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) -@end group -@end smallexample - -@noindent -This expression moves point forward line by line so long -as four conditions are true: - -@enumerate -@item -Point is not at the end of the buffer. - -@item -We can move to the left margin of the text and are -not at the end of the buffer. - -@item -The text following point does not separate paragraphs. - -@item -The pattern following point is the fill prefix regular expression. -@end enumerate - -The last condition may be puzzling, until you remember that point was -moved to the beginning of the line early in the @code{forward-paragraph} -function. This means that if the text has a fill prefix, the -@code{looking-at} function will see it. - -@need 1250 -Consider what happens when there is no fill prefix. - -@smallexample -@group - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) -@end group -@end smallexample - -@noindent -This @code{while} loop has us searching forward for -@code{sp-parstart}, which is the combination of possible whitespace -with the local value of the start of a paragraph or of a paragraph -separator. (The latter two are within an expression starting -@code{\(?:} so that they are not referenced by the -@code{match-beginning} function.) - -@need 800 -The two expressions, - -@smallexample -@group -(setq start (match-beginning 0)) -(goto-char start) -@end group -@end smallexample - -@noindent -mean go to the start of the text matched by the regular expression -search. - -The @code{(match-beginning 0)} expression is new. It returns a number -specifying the location of the start of the text that was matched by -the last search. - -The @code{match-beginning} function is used here because of a -characteristic of a forward search: a successful forward search, -regardless of whether it is a plain search or a regular expression -search, moves point to the end of the text that is found. In this -case, a successful search moves point to the end of the pattern for -@code{sp-parstart}. - -However, we want to put point at the end of the current paragraph, not -somewhere else. Indeed, since the search possibly includes the -paragraph separator, point may end up at the beginning of the next one -unless we use an expression that includes @code{match-beginning}. - -@findex match-beginning -When given an argument of 0, @code{match-beginning} returns the -position that is the start of the text matched by the most recent -search. In this case, the most recent search looks for -@code{sp-parstart}. The @code{(match-beginning 0)} expression returns -the beginning position of that pattern, rather than the end position -of that pattern. - -(Incidentally, when passed a positive number as an argument, the -@code{match-beginning} function returns the location of point at that -parenthesized expression in the last search unless that parenthesized -expression begins with @code{\(?:}. I don't know why @code{\(?:} -appears here since the argument is 0.) - -@need 1250 -The last expression when there is no fill prefix is - -@smallexample -@group -(if (< (point) (point-max)) - (goto-char start)))) -@end group -@end smallexample - -@noindent -This says that if there is no fill prefix and if we are not at the -end, point should move to the beginning of whatever was found by the -regular expression search for @code{sp-parstart}. - -The full definition for the @code{forward-paragraph} function not only -includes code for going forwards, but also code for going backwards. - -If you are reading this inside of GNU Emacs and you want to see the -whole function, you can type @kbd{C-h f} (@code{describe-function}) -and the name of the function. This gives you the function -documentation and the name of the library containing the function's -source. Place point over the name of the library and press the RET -key; you will be taken directly to the source. (Be sure to install -your sources! Without them, you are like a person who tries to drive -a car with his eyes shut!) - -@node etags -@section Create Your Own @file{TAGS} File -@findex etags -@cindex @file{TAGS} file, create own - -Besides @kbd{C-h f} (@code{describe-function}), another way to see the -source of a function is to type @kbd{M-.} (@code{find-tag}) and the -name of the function when prompted for it. This is a good habit to -get into. The @kbd{M-.} (@code{find-tag}) command takes you directly -to the source for a function, variable, or node. The function depends -on tags tables to tell it where to go. - -If the @code{find-tag} function first asks you for the name of a -@file{TAGS} table, give it the name of a @file{TAGS} file such as -@file{/usr/local/src/emacs/src/TAGS}. (The exact path to your -@file{TAGS} file depends on how your copy of Emacs was installed. I -just told you the location that provides both my C and my Emacs Lisp -sources.) - -You can also create your own @file{TAGS} file for directories that -lack one. - -You often need to build and install tags tables yourself. They are -not built automatically. A tags table is called a @file{TAGS} file; -the name is in upper case letters. - -You can create a @file{TAGS} file by calling the @code{etags} program -that comes as a part of the Emacs distribution. Usually, @code{etags} -is compiled and installed when Emacs is built. (@code{etags} is not -an Emacs Lisp function or a part of Emacs; it is a C program.) - -@need 1250 -To create a @file{TAGS} file, first switch to the directory in which -you want to create the file. In Emacs you can do this with the -@kbd{M-x cd} command, or by visiting a file in the directory, or by -listing the directory with @kbd{C-x d} (@code{dired}). Then run the -compile command, with @w{@code{etags *.el}} as the command to execute - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -@noindent -to create a @file{TAGS} file for Emacs Lisp. - -For example, if you have a large number of files in your -@file{~/emacs} directory, as I do---I have 137 @file{.el} files in it, -of which I load 12---you can create a @file{TAGS} file for the Emacs -Lisp files in that directory. - -@need 1250 -The @code{etags} program takes all the usual shell `wildcards'. For -example, if you have two directories for which you want a single -@file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where -@file{../elisp/} is the second directory: - -@smallexample -M-x compile RET etags *.el ../elisp/*.el RET -@end smallexample - -@need 1250 -Type - -@smallexample -M-x compile RET etags --help RET -@end smallexample - -@noindent -to see a list of the options accepted by @code{etags} as well as a -list of supported languages. - -The @code{etags} program handles more than 20 languages, including -Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java, -LaTeX, Pascal, Perl, PostScript, Python, TeX, Texinfo, makefiles, and -most assemblers. The program has no switches for specifying the -language; it recognizes the language in an input file according to its -file name and contents. - -@file{etags} is very helpful when you are writing code yourself and -want to refer back to functions you have already written. Just run -@code{etags} again at intervals as you write new functions, so they -become part of the @file{TAGS} file. - -If you think an appropriate @file{TAGS} file already exists for what -you want, but do not know where it is, you can use the @code{locate} -program to attempt to find it. - -Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list -for you the full path names of all your @file{TAGS} files. On my -system, this command lists 34 @file{TAGS} files. On the other hand, a -`plain vanilla' system I recently installed did not contain any -@file{TAGS} files. - -If the tags table you want has been created, you can use the @code{M-x -visit-tags-table} command to specify it. Otherwise, you will need to -create the tag table yourself and then use @code{M-x -visit-tags-table}. - -@subsubheading Building Tags in the Emacs sources -@cindex Building Tags in the Emacs sources -@cindex Tags in the Emacs sources -@findex make tags - -The GNU Emacs sources come with a @file{Makefile} that contains a -sophisticated @code{etags} command that creates, collects, and merges -tags tables from all over the Emacs sources and puts the information -into one @file{TAGS} file in the @file{src/} directory. (The -@file{src/} directory is below the top level of your Emacs directory.) - -@need 1250 -To build this @file{TAGS} file, go to the top level of your Emacs -source directory and run the compile command @code{make tags}: - -@smallexample -M-x compile RET make tags RET -@end smallexample - -@noindent -(The @code{make tags} command works well with the GNU Emacs sources, -as well as with some other source packages.) - -For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs -Manual}. - -@node Regexp Review -@section Review - -Here is a brief summary of some recently introduced functions. - -@table @code -@item while -Repeatedly evaluate the body of the expression so long as the first -element of the body tests true. Then return @code{nil}. (The -expression is evaluated only for its side effects.) - -@need 1250 -For example: - -@smallexample -@group -(let ((foo 2)) - (while (> foo 0) - (insert (format "foo is %d.\n" foo)) - (setq foo (1- foo)))) - - @result{} foo is 2. - foo is 1. - nil -@end group -@end smallexample - -@noindent -(The @code{insert} function inserts its arguments at point; the -@code{format} function returns a string formatted from its arguments -the way @code{message} formats its arguments; @code{\n} produces a new -line.) - -@item re-search-forward -Search for a pattern, and if the pattern is found, move point to rest -just after it. - -@noindent -Takes four arguments, like @code{search-forward}: - -@enumerate -@item -A regular expression that specifies the pattern to search for. -(Remember to put quotation marks around this argument!) - -@item -Optionally, the limit of the search. - -@item -Optionally, what to do if the search fails, return @code{nil} or an -error message. - -@item -Optionally, how many times to repeat the search; if negative, the -search goes backwards. -@end enumerate - -@item let* -Bind some variables locally to particular values, -and then evaluate the remaining arguments, returning the value of the -last one. While binding the local variables, use the local values of -variables bound earlier, if any. - -@need 1250 -For example: - -@smallexample -@group -(let* ((foo 7) - (bar (* 3 foo))) - (message "`bar' is %d." bar)) - @result{} `bar' is 21. -@end group -@end smallexample - -@item match-beginning -Return the position of the start of the text found by the last regular -expression search. - -@item looking-at -Return @code{t} for true if the text after point matches the argument, -which should be a regular expression. - -@item eobp -Return @code{t} for true if point is at the end of the accessible part -of a buffer. The end of the accessible part is the end of the buffer -if the buffer is not narrowed; it is the end of the narrowed part if -the buffer is narrowed. -@end table - -@need 1500 -@node re-search Exercises -@section Exercises with @code{re-search-forward} - -@itemize @bullet -@item -Write a function to search for a regular expression that matches two -or more blank lines in sequence. - -@item -Write a function to search for duplicated words, such as `the the'. -@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs -Manual}, for information on how to write a regexp (a regular -expression) to match a string that is composed of two identical -halves. You can devise several regexps; some are better than others. -The function I use is described in an appendix, along with several -regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. -@end itemize - -@node Counting Words -@chapter Counting via Repetition and Regexps -@cindex Repetition for word counting -@cindex Regular expressions for word counting - -Repetition and regular expression searches are powerful tools that you -often use when you write code in Emacs Lisp. This chapter illustrates -the use of regular expression searches through the construction of -word count commands using @code{while} loops and recursion. - -@menu -* Why Count Words:: -* @value{COUNT-WORDS}:: Use a regexp, but find a problem. -* recursive-count-words:: Start with case of no words in region. -* Counting Exercise:: -@end menu - -@ifnottex -@node Why Count Words -@unnumberedsec Counting words -@end ifnottex - -The standard Emacs distribution contains functions for counting the -number of lines and words within a region. - -Certain types of writing ask you to count words. Thus, if you write -an essay, you may be limited to 800 words; if you write a novel, you -may discipline yourself to write 1000 words a day. It seems odd, but -for a long time, Emacs lacked a word count command. Perhaps people used -Emacs mostly for code or types of documentation that did not require -word counts; or perhaps they restricted themselves to the operating -system word count command, @code{wc}. Alternatively, people may have -followed the publishers' convention and computed a word count by -dividing the number of characters in a document by five. - -There are many ways to implement a command to count words. Here are -some examples, which you may wish to compare with the standard Emacs -command, @code{count-words-region}. - -@node @value{COUNT-WORDS} -@section The @code{@value{COUNT-WORDS}} Function -@findex @value{COUNT-WORDS} - -A word count command could count words in a line, paragraph, region, -or buffer. What should the command cover? You could design the -command to count the number of words in a complete buffer. However, -the Emacs tradition encourages flexibility---you may want to count -words in just a section, rather than all of a buffer. So it makes -more sense to design the command to count the number of words in a -region. Once you have a command to count words in a region, you can, -if you wish, count words in a whole buffer by marking it with -@w{@kbd{C-x h}} (@code{mark-whole-buffer}). - -Clearly, counting words is a repetitive act: starting from the -beginning of the region, you count the first word, then the second -word, then the third word, and so on, until you reach the end of the -region. This means that word counting is ideally suited to recursion -or to a @code{while} loop. - -@menu -* Design @value{COUNT-WORDS}:: The definition using a @code{while} loop. -* Whitespace Bug:: The Whitespace Bug in @code{@value{COUNT-WORDS}}. -@end menu - -@ifnottex -@node Design @value{COUNT-WORDS} -@unnumberedsubsec Designing @code{@value{COUNT-WORDS}} -@end ifnottex - -First, we will implement the word count command with a @code{while} -loop, then with recursion. The command will, of course, be -interactive. - -@need 800 -The template for an interactive function definition is, as always: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -What we need to do is fill in the slots. - -The name of the function should be self-explanatory and similar to the -existing @code{count-lines-region} name. This makes the name easier -to remember. @code{count-words-region} is the obvious choice. Since -that name is now used for the standard Emacs command to count words, we -will name our implementation @code{@value{COUNT-WORDS}}. - -The function counts words within a region. This means that the -argument list must contain symbols that are bound to the two -positions, the beginning and end of the region. These two positions -can be called @samp{beginning} and @samp{end} respectively. The first -line of the documentation should be a single sentence, since that is -all that is printed as documentation by a command such as -@code{apropos}. The interactive expression will be of the form -@samp{(interactive "r")}, since that will cause Emacs to pass the -beginning and end of the region to the function's argument list. All -this is routine. - -The body of the function needs to be written to do three tasks: -first, to set up conditions under which the @code{while} loop can -count words, second, to run the @code{while} loop, and third, to send -a message to the user. - -When a user calls @code{@value{COUNT-WORDS}}, point may be at the -beginning or the end of the region. However, the counting process -must start at the beginning of the region. This means we will want -to put point there if it is not already there. Executing -@code{(goto-char beginning)} ensures this. Of course, we will want to -return point to its expected position when the function finishes its -work. For this reason, the body must be enclosed in a -@code{save-excursion} expression. - -The central part of the body of the function consists of a -@code{while} loop in which one expression jumps point forward word by -word, and another expression counts those jumps. The true-or-false-test -of the @code{while} loop should test true so long as point should jump -forward, and false when point is at the end of the region. - -We could use @code{(forward-word 1)} as the expression for moving point -forward word by word, but it is easier to see what Emacs identifies as a -`word' if we use a regular expression search. - -A regular expression search that finds the pattern for which it is -searching leaves point after the last character matched. This means -that a succession of successful word searches will move point forward -word by word. - -As a practical matter, we want the regular expression search to jump -over whitespace and punctuation between words as well as over the -words themselves. A regexp that refuses to jump over interword -whitespace would never jump more than one word! This means that -the regexp should include the whitespace and punctuation that follows -a word, if any, as well as the word itself. (A word may end a buffer -and not have any following whitespace or punctuation, so that part of -the regexp must be optional.) - -Thus, what we want for the regexp is a pattern defining one or more -word constituent characters followed, optionally, by one or more -characters that are not word constituents. The regular expression for -this is: - -@smallexample -\w+\W* -@end smallexample - -@noindent -The buffer's syntax table determines which characters are and are not -word constituents. For more information about syntax, -@pxref{Syntax Tables, , Syntax Tables, elisp, The GNU Emacs Lisp -Reference Manual}. - -@need 800 -The search expression looks like this: - -@smallexample -(re-search-forward "\\w+\\W*") -@end smallexample - -@noindent -(Note that paired backslashes precede the @samp{w} and @samp{W}. A -single backslash has special meaning to the Emacs Lisp interpreter. -It indicates that the following character is interpreted differently -than usual. For example, the two characters, @samp{\n}, stand for -@samp{newline}, rather than for a backslash followed by @samp{n}. Two -backslashes in a row stand for an ordinary, `unspecial' backslash, so -Emacs Lisp interpreter ends of seeing a single backslash followed by a -letter. So it discovers the letter is special.) - -We need a counter to count how many words there are; this variable -must first be set to 0 and then incremented each time Emacs goes -around the @code{while} loop. The incrementing expression is simply: - -@smallexample -(setq count (1+ count)) -@end smallexample - -Finally, we want to tell the user how many words there are in the -region. The @code{message} function is intended for presenting this -kind of information to the user. The message has to be phrased so -that it reads properly regardless of how many words there are in the -region: we don't want to say that ``there are 1 words in the region''. -The conflict between singular and plural is ungrammatical. We can -solve this problem by using a conditional expression that evaluates -different messages depending on the number of words in the region. -There are three possibilities: no words in the region, one word in the -region, and more than one word. This means that the @code{cond} -special form is appropriate. - -@need 1500 -All this leads to the following function definition: - -@smallexample -@group -;;; @r{First version; has bugs!} -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region. -Words are defined as at least one word-constituent -character followed by at least one character that -is not a word-constituent. The buffer's syntax -table determines which characters these are." - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (goto-char beginning) - (let ((count 0)) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (< (point) end) - (re-search-forward "\\w+\\W*") - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@noindent -As written, the function works, but not in all circumstances. - -@node Whitespace Bug -@subsection The Whitespace Bug in @code{@value{COUNT-WORDS}} - -The @code{@value{COUNT-WORDS}} command described in the preceding -section has two bugs, or rather, one bug with two manifestations. -First, if you mark a region containing only whitespace in the middle -of some text, the @code{@value{COUNT-WORDS}} command tells you that the -region contains one word! Second, if you mark a region containing -only whitespace at the end of the buffer or the accessible portion of -a narrowed buffer, the command displays an error message that looks -like this: - -@smallexample -Search failed: "\\w+\\W*" -@end smallexample - -If you are reading this in Info in GNU Emacs, you can test for these -bugs yourself. - -First, evaluate the function in the usual manner to install it. -@ifinfo -Here is a copy of the definition. Place your cursor after the closing -parenthesis and type @kbd{C-x C-e} to install it. - -@smallexample -@group -;; @r{First version; has bugs!} -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region. -Words are defined as at least one word-constituent character followed -by at least one character that is not a word-constituent. The buffer's -syntax table determines which characters these are." -@end group -@group - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (goto-char beginning) - (let ((count 0)) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (< (point) end) - (re-search-forward "\\w+\\W*") - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message "The region does NOT have any words.")) - ((= 1 count) (message "The region has 1 word.")) - (t (message "The region has %d words." count)))))) -@end group -@end smallexample -@end ifinfo - -@need 1000 -If you wish, you can also install this keybinding by evaluating it: - -@smallexample -(global-set-key "\C-c=" '@value{COUNT-WORDS}) -@end smallexample - -To conduct the first test, set mark and point to the beginning and end -of the following line and then type @kbd{C-c =} (or @kbd{M-x -@value{COUNT-WORDS}} if you have not bound @kbd{C-c =}): - -@smallexample - one two three -@end smallexample - -@noindent -Emacs will tell you, correctly, that the region has three words. - -Repeat the test, but place mark at the beginning of the line and place -point just @emph{before} the word @samp{one}. Again type the command -@kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}). Emacs should tell you -that the region has no words, since it is composed only of the -whitespace at the beginning of the line. But instead Emacs tells you -that the region has one word! - -For the third test, copy the sample line to the end of the -@file{*scratch*} buffer and then type several spaces at the end of the -line. Place mark right after the word @samp{three} and point at the -end of line. (The end of the line will be the end of the buffer.) -Type @kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}) as you did before. -Again, Emacs should tell you that the region has no words, since it is -composed only of the whitespace at the end of the line. Instead, -Emacs displays an error message saying @samp{Search failed}. - -The two bugs stem from the same problem. - -Consider the first manifestation of the bug, in which the command -tells you that the whitespace at the beginning of the line contains -one word. What happens is this: The @code{M-x @value{COUNT-WORDS}} -command moves point to the beginning of the region. The @code{while} -tests whether the value of point is smaller than the value of -@code{end}, which it is. Consequently, the regular expression search -looks for and finds the first word. It leaves point after the word. -@code{count} is set to one. The @code{while} loop repeats; but this -time the value of point is larger than the value of @code{end}, the -loop is exited; and the function displays a message saying the number -of words in the region is one. In brief, the regular expression -search looks for and finds the word even though it is outside -the marked region. - -In the second manifestation of the bug, the region is whitespace at -the end of the buffer. Emacs says @samp{Search failed}. What happens -is that the true-or-false-test in the @code{while} loop tests true, so -the search expression is executed. But since there are no more words -in the buffer, the search fails. - -In both manifestations of the bug, the search extends or attempts to -extend outside of the region. - -The solution is to limit the search to the region---this is a fairly -simple action, but as you may have come to expect, it is not quite as -simple as you might think. - -As we have seen, the @code{re-search-forward} function takes a search -pattern as its first argument. But in addition to this first, -mandatory argument, it accepts three optional arguments. The optional -second argument bounds the search. The optional third argument, if -@code{t}, causes the function to return @code{nil} rather than signal -an error if the search fails. The optional fourth argument is a -repeat count. (In Emacs, you can see a function's documentation by -typing @kbd{C-h f}, the name of the function, and then @key{RET}.) - -In the @code{@value{COUNT-WORDS}} definition, the value of the end of -the region is held by the variable @code{end} which is passed as an -argument to the function. Thus, we can add @code{end} as an argument -to the regular expression search expression: - -@smallexample -(re-search-forward "\\w+\\W*" end) -@end smallexample - -However, if you make only this change to the @code{@value{COUNT-WORDS}} -definition and then test the new version of the definition on a -stretch of whitespace, you will receive an error message saying -@samp{Search failed}. - -What happens is this: the search is limited to the region, and fails -as you expect because there are no word-constituent characters in the -region. Since it fails, we receive an error message. But we do not -want to receive an error message in this case; we want to receive the -message that "The region does NOT have any words." - -The solution to this problem is to provide @code{re-search-forward} -with a third argument of @code{t}, which causes the function to return -@code{nil} rather than signal an error if the search fails. - -However, if you make this change and try it, you will see the message -``Counting words in region ... '' and @dots{} you will keep on seeing -that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}). - -Here is what happens: the search is limited to the region, as before, -and it fails because there are no word-constituent characters in the -region, as expected. Consequently, the @code{re-search-forward} -expression returns @code{nil}. It does nothing else. In particular, -it does not move point, which it does as a side effect if it finds the -search target. After the @code{re-search-forward} expression returns -@code{nil}, the next expression in the @code{while} loop is evaluated. -This expression increments the count. Then the loop repeats. The -true-or-false-test tests true because the value of point is still less -than the value of end, since the @code{re-search-forward} expression -did not move point. @dots{} and the cycle repeats @dots{} - -The @code{@value{COUNT-WORDS}} definition requires yet another -modification, to cause the true-or-false-test of the @code{while} loop -to test false if the search fails. Put another way, there are two -conditions that must be satisfied in the true-or-false-test before the -word count variable is incremented: point must still be within the -region and the search expression must have found a word to count. - -Since both the first condition and the second condition must be true -together, the two expressions, the region test and the search -expression, can be joined with an @code{and} special form and embedded in -the @code{while} loop as the true-or-false-test, like this: - -@smallexample -(and (< (point) end) (re-search-forward "\\w+\\W*" end t)) -@end smallexample - -@c colon in printed section title causes problem in Info cross reference -@c also trouble with an overfull hbox -@iftex -@noindent -(For information about @code{and}, see -@ref{kill-new function, , The @code{kill-new} function}.) -@end iftex -@ifinfo -@noindent -(@xref{kill-new function, , The @code{kill-new} function}, for -information about @code{and}.) -@end ifinfo - -The @code{re-search-forward} expression returns @code{t} if the search -succeeds and as a side effect moves point. Consequently, as words are -found, point is moved through the region. When the search expression -fails to find another word, or when point reaches the end of the -region, the true-or-false-test tests false, the @code{while} loop -exits, and the @code{@value{COUNT-WORDS}} function displays one or -other of its messages. - -After incorporating these final changes, the @code{@value{COUNT-WORDS}} -works without bugs (or at least, without bugs that I have found!). -Here is what it looks like: - -@smallexample -@group -;;; @r{Final version:} @code{while} -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region." - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (let ((count 0)) - (goto-char beginning) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (and (< (point) end) - (re-search-forward "\\w+\\W*" end t)) - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@node recursive-count-words -@section Count Words Recursively -@cindex Count words recursively -@cindex Recursively counting words -@cindex Words, counted recursively - -You can write the function for counting words recursively as well as -with a @code{while} loop. Let's see how this is done. - -First, we need to recognize that the @code{@value{COUNT-WORDS}} -function has three jobs: it sets up the appropriate conditions for -counting to occur; it counts the words in the region; and it sends a -message to the user telling how many words there are. - -If we write a single recursive function to do everything, we will -receive a message for every recursive call. If the region contains 13 -words, we will receive thirteen messages, one right after the other. -We don't want this! Instead, we must write two functions to do the -job, one of which (the recursive function) will be used inside of the -other. One function will set up the conditions and display the -message; the other will return the word count. - -Let us start with the function that causes the message to be displayed. -We can continue to call this @code{@value{COUNT-WORDS}}. - -This is the function that the user will call. It will be interactive. -Indeed, it will be similar to our previous versions of this -function, except that it will call @code{recursive-count-words} to -determine how many words are in the region. - -@need 1250 -We can readily construct a template for this function, based on our -previous versions: - -@smallexample -@group -;; @r{Recursive version; uses regular expression search} -(defun @value{COUNT-WORDS} (beginning end) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) -@end group -@group - -;;; @r{1. Set up appropriate conditions.} - (@var{explanatory message}) - (@var{set-up functions}@dots{} -@end group -@group - -;;; @r{2. Count the words.} - @var{recursive call} -@end group -@group - -;;; @r{3. Send a message to the user.} - @var{message providing word count})) -@end group -@end smallexample - -The definition looks straightforward, except that somehow the count -returned by the recursive call must be passed to the message -displaying the word count. A little thought suggests that this can be -done by making use of a @code{let} expression: we can bind a variable -in the varlist of a @code{let} expression to the number of words in -the region, as returned by the recursive call; and then the -@code{cond} expression, using binding, can display the value to the -user. - -Often, one thinks of the binding within a @code{let} expression as -somehow secondary to the `primary' work of a function. But in this -case, what you might consider the `primary' job of the function, -counting words, is done within the @code{let} expression. - -@need 1250 -Using @code{let}, the function definition looks like this: - -@smallexample -@group -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region." - (interactive "r") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (message "Counting words in region ... ") - (save-excursion - (goto-char beginning) -@end group - -@group -;;; @r{2. Count the words.} - (let ((count (recursive-count-words end))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -Next, we need to write the recursive counting function. - -A recursive function has at least three parts: the `do-again-test', the -`next-step-expression', and the recursive call. - -The do-again-test determines whether the function will or will not be -called again. Since we are counting words in a region and can use a -function that moves point forward for every word, the do-again-test -can check whether point is still within the region. The do-again-test -should find the value of point and determine whether point is before, -at, or after the value of the end of the region. We can use the -@code{point} function to locate point. Clearly, we must pass the -value of the end of the region to the recursive counting function as an -argument. - -In addition, the do-again-test should also test whether the search finds a -word. If it does not, the function should not call itself again. - -The next-step-expression changes a value so that when the recursive -function is supposed to stop calling itself, it stops. More -precisely, the next-step-expression changes a value so that at the -right time, the do-again-test stops the recursive function from -calling itself again. In this case, the next-step-expression can be -the expression that moves point forward, word by word. - -The third part of a recursive function is the recursive call. - -Somewhere, also, we also need a part that does the `work' of the -function, a part that does the counting. A vital part! - -@need 1250 -But already, we have an outline of the recursive counting function: - -@smallexample -@group -(defun recursive-count-words (region-end) - "@var{documentation}@dots{}" - @var{do-again-test} - @var{next-step-expression} - @var{recursive call}) -@end group -@end smallexample - -Now we need to fill in the slots. Let's start with the simplest cases -first: if point is at or beyond the end of the region, there cannot -be any words in the region, so the function should return zero. -Likewise, if the search fails, there are no words to count, so the -function should return zero. - -On the other hand, if point is within the region and the search -succeeds, the function should call itself again. - -@need 800 -Thus, the do-again-test should look like this: - -@smallexample -@group -(and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group -@end smallexample - -Note that the search expression is part of the do-again-test---the -function returns @code{t} if its search succeeds and @code{nil} if it -fails. (@xref{Whitespace Bug, , The Whitespace Bug in -@code{@value{COUNT-WORDS}}}, for an explanation of how -@code{re-search-forward} works.) - -The do-again-test is the true-or-false test of an @code{if} clause. -Clearly, if the do-again-test succeeds, the then-part of the @code{if} -clause should call the function again; but if it fails, the else-part -should return zero since either point is outside the region or the -search failed because there were no words to find. - -But before considering the recursive call, we need to consider the -next-step-expression. What is it? Interestingly, it is the search -part of the do-again-test. - -In addition to returning @code{t} or @code{nil} for the -do-again-test, @code{re-search-forward} moves point forward as a side -effect of a successful search. This is the action that changes the -value of point so that the recursive function stops calling itself -when point completes its movement through the region. Consequently, -the @code{re-search-forward} expression is the next-step-expression. - -@need 1200 -In outline, then, the body of the @code{recursive-count-words} -function looks like this: - -@smallexample -@group -(if @var{do-again-test-and-next-step-combined} - ;; @r{then} - @var{recursive-call-returning-count} - ;; @r{else} - @var{return-zero}) -@end group -@end smallexample - -How to incorporate the mechanism that counts? - -If you are not used to writing recursive functions, a question like -this can be troublesome. But it can and should be approached -systematically. - -We know that the counting mechanism should be associated in some way -with the recursive call. Indeed, since the next-step-expression moves -point forward by one word, and since a recursive call is made for -each word, the counting mechanism must be an expression that adds one -to the value returned by a call to @code{recursive-count-words}. - -@need 800 -Consider several cases: - -@itemize @bullet -@item -If there are two words in the region, the function should return -a value resulting from adding one to the value returned when it counts -the first word, plus the number returned when it counts the remaining -words in the region, which in this case is one. - -@item -If there is one word in the region, the function should return -a value resulting from adding one to the value returned when it counts -that word, plus the number returned when it counts the remaining -words in the region, which in this case is zero. - -@item -If there are no words in the region, the function should return zero. -@end itemize - -From the sketch we can see that the else-part of the @code{if} returns -zero for the case of no words. This means that the then-part of the -@code{if} must return a value resulting from adding one to the value -returned from a count of the remaining words. - -@need 1200 -The expression will look like this, where @code{1+} is a function that -adds one to its argument. - -@smallexample -(1+ (recursive-count-words region-end)) -@end smallexample - -@need 1200 -The whole @code{recursive-count-words} function will then look like -this: - -@smallexample -@group -(defun recursive-count-words (region-end) - "@var{documentation}@dots{}" - -;;; @r{1. do-again-test} - (if (and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group - -@group -;;; @r{2. then-part: the recursive call} - (1+ (recursive-count-words region-end)) - -;;; @r{3. else-part} - 0)) -@end group -@end smallexample - -@need 1250 -Let's examine how this works: - -If there are no words in the region, the else part of the @code{if} -expression is evaluated and consequently the function returns zero. - -If there is one word in the region, the value of point is less than -the value of @code{region-end} and the search succeeds. In this case, -the true-or-false-test of the @code{if} expression tests true, and the -then-part of the @code{if} expression is evaluated. The counting -expression is evaluated. This expression returns a value (which will -be the value returned by the whole function) that is the sum of one -added to the value returned by a recursive call. - -Meanwhile, the next-step-expression has caused point to jump over the -first (and in this case only) word in the region. This means that -when @code{(recursive-count-words region-end)} is evaluated a second -time, as a result of the recursive call, the value of point will be -equal to or greater than the value of region end. So this time, -@code{recursive-count-words} will return zero. The zero will be added -to one, and the original evaluation of @code{recursive-count-words} -will return one plus zero, which is one, which is the correct amount. - -Clearly, if there are two words in the region, the first call to -@code{recursive-count-words} returns one added to the value returned -by calling @code{recursive-count-words} on a region containing the -remaining word---that is, it adds one to one, producing two, which is -the correct amount. - -Similarly, if there are three words in the region, the first call to -@code{recursive-count-words} returns one added to the value returned -by calling @code{recursive-count-words} on a region containing the -remaining two words---and so on and so on. - -@need 1250 -@noindent -With full documentation the two functions look like this: - -@need 1250 -@noindent -The recursive function: - -@findex recursive-count-words -@smallexample -@group -(defun recursive-count-words (region-end) - "Number of words between point and REGION-END." -@end group - -@group -;;; @r{1. do-again-test} - (if (and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group - -@group -;;; @r{2. then-part: the recursive call} - (1+ (recursive-count-words region-end)) - -;;; @r{3. else-part} - 0)) -@end group -@end smallexample - -@need 800 -@noindent -The wrapper: - -@smallexample -@group -;;; @r{Recursive version} -(defun @value{COUNT-WORDS} (beginning end) - "Print number of words in the region. -@end group - -@group -Words are defined as at least one word-constituent -character followed by at least one character that is -not a word-constituent. The buffer's syntax table -determines which characters these are." -@end group -@group - (interactive "r") - (message "Counting words in region ... ") - (save-excursion - (goto-char beginning) - (let ((count (recursive-count-words end))) -@end group -@group - (cond ((zerop count) - (message - "The region does NOT have any words.")) -@end group -@group - ((= 1 count) - (message "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@node Counting Exercise -@section Exercise: Counting Punctuation - -Using a @code{while} loop, write a function to count the number of -punctuation marks in a region---period, comma, semicolon, colon, -exclamation mark, and question mark. Do the same using recursion. - -@node Words in a defun -@chapter Counting Words in a @code{defun} -@cindex Counting words in a @code{defun} -@cindex Word counting in a @code{defun} - -Our next project is to count the number of words in a function -definition. Clearly, this can be done using some variant of -@code{@value{COUNT-WORDS}}. @xref{Counting Words, , Counting via -Repetition and Regexps}. If we are just going to count the words in -one definition, it is easy enough to mark the definition with the -@kbd{C-M-h} (@code{mark-defun}) command, and then call -@code{@value{COUNT-WORDS}}. - -However, I am more ambitious: I want to count the words and symbols in -every definition in the Emacs sources and then print a graph that -shows how many functions there are of each length: how many contain 40 -to 49 words or symbols, how many contain 50 to 59 words or symbols, -and so on. I have often been curious how long a typical function is, -and this will tell. - -@menu -* Divide and Conquer:: -* Words and Symbols:: What to count? -* Syntax:: What constitutes a word or symbol? -* count-words-in-defun:: Very like @code{@value{COUNT-WORDS}}. -* Several defuns:: Counting several defuns in a file. -* Find a File:: Do you want to look at a file? -* lengths-list-file:: A list of the lengths of many definitions. -* Several files:: Counting in definitions in different files. -* Several files recursively:: Recursively counting in different files. -* Prepare the data:: Prepare the data for display in a graph. -@end menu - -@ifnottex -@node Divide and Conquer -@unnumberedsec Divide and Conquer -@end ifnottex - -Described in one phrase, the histogram project is daunting; but -divided into numerous small steps, each of which we can take one at a -time, the project becomes less fearsome. Let us consider what the -steps must be: - -@itemize @bullet -@item -First, write a function to count the words in one definition. This -includes the problem of handling symbols as well as words. - -@item -Second, write a function to list the numbers of words in each function -in a file. This function can use the @code{count-words-in-defun} -function. - -@item -Third, write a function to list the numbers of words in each function -in each of several files. This entails automatically finding the -various files, switching to them, and counting the words in the -definitions within them. - -@item -Fourth, write a function to convert the list of numbers that we -created in step three to a form that will be suitable for printing as -a graph. - -@item -Fifth, write a function to print the results as a graph. -@end itemize - -This is quite a project! But if we take each step slowly, it will not -be difficult. - -@node Words and Symbols -@section What to Count? -@cindex Words and symbols in defun - -When we first start thinking about how to count the words in a -function definition, the first question is (or ought to be) what are -we going to count? When we speak of `words' with respect to a Lisp -function definition, we are actually speaking, in large part, of -`symbols'. For example, the following @code{multiply-by-seven} -function contains the five symbols @code{defun}, -@code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In -addition, in the documentation string, it contains the four words -@samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The -symbol @samp{number} is repeated, so the definition contains a total -of ten words and symbols. - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -@noindent -However, if we mark the @code{multiply-by-seven} definition with -@kbd{C-M-h} (@code{mark-defun}), and then call -@code{@value{COUNT-WORDS}} on it, we will find that -@code{@value{COUNT-WORDS}} claims the definition has eleven words, not -ten! Something is wrong! - -The problem is twofold: @code{@value{COUNT-WORDS}} does not count the -@samp{*} as a word, and it counts the single symbol, -@code{multiply-by-seven}, as containing three words. The hyphens are -treated as if they were interword spaces rather than intraword -connectors: @samp{multiply-by-seven} is counted as if it were written -@samp{multiply by seven}. - -The cause of this confusion is the regular expression search within -the @code{@value{COUNT-WORDS}} definition that moves point forward word -by word. In the canonical version of @code{@value{COUNT-WORDS}}, the -regexp is: - -@smallexample -"\\w+\\W*" -@end smallexample - -@noindent -This regular expression is a pattern defining one or more word -constituent characters possibly followed by one or more characters -that are not word constituents. What is meant by `word constituent -characters' brings us to the issue of syntax, which is worth a section -of its own. - -@node Syntax -@section What Constitutes a Word or Symbol? -@cindex Syntax categories and tables - -Emacs treats different characters as belonging to different -@dfn{syntax categories}. For example, the regular expression, -@samp{\\w+}, is a pattern specifying one or more @emph{word -constituent} characters. Word constituent characters are members of -one syntax category. Other syntax categories include the class of -punctuation characters, such as the period and the comma, and the -class of whitespace characters, such as the blank space and the tab -character. (For more information, @pxref{Syntax Tables, , Syntax -Tables, elisp, The GNU Emacs Lisp Reference Manual}.) - -Syntax tables specify which characters belong to which categories. -Usually, a hyphen is not specified as a `word constituent character'. -Instead, it is specified as being in the `class of characters that are -part of symbol names but not words.' This means that the -@code{@value{COUNT-WORDS}} function treats it in the same way it treats -an interword white space, which is why @code{@value{COUNT-WORDS}} -counts @samp{multiply-by-seven} as three words. - -There are two ways to cause Emacs to count @samp{multiply-by-seven} as -one symbol: modify the syntax table or modify the regular expression. - -We could redefine a hyphen as a word constituent character by -modifying the syntax table that Emacs keeps for each mode. This -action would serve our purpose, except that a hyphen is merely the -most common character within symbols that is not typically a word -constituent character; there are others, too. - -Alternatively, we can redefine the regexp used in the -@code{@value{COUNT-WORDS}} definition so as to include symbols. This -procedure has the merit of clarity, but the task is a little tricky. - -@need 1200 -The first part is simple enough: the pattern must match ``at least one -character that is a word or symbol constituent''. Thus: - -@smallexample -"\\(\\w\\|\\s_\\)+" -@end smallexample - -@noindent -The @samp{\\(} is the first part of the grouping construct that -includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated -by the @samp{\\|}. The @samp{\\w} matches any word-constituent -character and the @samp{\\s_} matches any character that is part of a -symbol name but not a word-constituent character. The @samp{+} -following the group indicates that the word or symbol constituent -characters must be matched at least once. - -However, the second part of the regexp is more difficult to design. -What we want is to follow the first part with ``optionally one or more -characters that are not constituents of a word or symbol''. At first, -I thought I could define this with the following: - -@smallexample -"\\(\\W\\|\\S_\\)*" -@end smallexample - -@noindent -The upper case @samp{W} and @samp{S} match characters that are -@emph{not} word or symbol constituents. Unfortunately, this -expression matches any character that is either not a word constituent -or not a symbol constituent. This matches any character! - -I then noticed that every word or symbol in my test region was -followed by white space (blank space, tab, or newline). So I tried -placing a pattern to match one or more blank spaces after the pattern -for one or more word or symbol constituents. This failed, too. Words -and symbols are often separated by whitespace, but in actual code -parentheses may follow symbols and punctuation may follow words. So -finally, I designed a pattern in which the word or symbol constituents -are followed optionally by characters that are not white space and -then followed optionally by white space. - -@need 800 -Here is the full regular expression: - -@smallexample -"\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" -@end smallexample - -@node count-words-in-defun -@section The @code{count-words-in-defun} Function -@cindex Counting words in a @code{defun} - -We have seen that there are several ways to write a -@code{count-words-region} function. To write a -@code{count-words-in-defun}, we need merely adapt one of these -versions. - -The version that uses a @code{while} loop is easy to understand, so I -am going to adapt that. Because @code{count-words-in-defun} will be -part of a more complex program, it need not be interactive and it need -not display a message but just return the count. These considerations -simplify the definition a little. - -On the other hand, @code{count-words-in-defun} will be used within a -buffer that contains function definitions. Consequently, it is -reasonable to ask that the function determine whether it is called -when point is within a function definition, and if it is, to return -the count for that definition. This adds complexity to the -definition, but saves us from needing to pass arguments to the -function. - -@need 1250 -These considerations lead us to prepare the following template: - -@smallexample -@group -(defun count-words-in-defun () - "@var{documentation}@dots{}" - (@var{set up}@dots{} - (@var{while loop}@dots{}) - @var{return count}) -@end group -@end smallexample - -@noindent -As usual, our job is to fill in the slots. - -First, the set up. - -We are presuming that this function will be called within a buffer -containing function definitions. Point will either be within a -function definition or not. For @code{count-words-in-defun} to work, -point must move to the beginning of the definition, a counter must -start at zero, and the counting loop must stop when point reaches the -end of the definition. - -The @code{beginning-of-defun} function searches backwards for an -opening delimiter such as a @samp{(} at the beginning of a line, and -moves point to that position, or else to the limit of the search. In -practice, this means that @code{beginning-of-defun} moves point to the -beginning of an enclosing or preceding function definition, or else to -the beginning of the buffer. We can use @code{beginning-of-defun} to -place point where we wish to start. - -The @code{while} loop requires a counter to keep track of the words or -symbols being counted. A @code{let} expression can be used to create -a local variable for this purpose, and bind it to an initial value of zero. - -The @code{end-of-defun} function works like @code{beginning-of-defun} -except that it moves point to the end of the definition. -@code{end-of-defun} can be used as part of an expression that -determines the position of the end of the definition. - -The set up for @code{count-words-in-defun} takes shape rapidly: first -we move point to the beginning of the definition, then we create a -local variable to hold the count, and finally, we record the position -of the end of the definition so the @code{while} loop will know when to stop -looping. - -@need 1250 -The code looks like this: - -@smallexample -@group -(beginning-of-defun) -(let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group -@end smallexample - -@noindent -The code is simple. The only slight complication is likely to concern -@code{end}: it is bound to the position of the end of the definition -by a @code{save-excursion} expression that returns the value of point -after @code{end-of-defun} temporarily moves it to the end of the -definition. - -The second part of the @code{count-words-in-defun}, after the set up, -is the @code{while} loop. - -The loop must contain an expression that jumps point forward word by -word and symbol by symbol, and another expression that counts the -jumps. The true-or-false-test for the @code{while} loop should test -true so long as point should jump forward, and false when point is at -the end of the definition. We have already redefined the regular -expression for this, so the loop is straightforward: - -@smallexample -@group -(while (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)) - (setq count (1+ count))) -@end group -@end smallexample - -The third part of the function definition returns the count of words -and symbols. This part is the last expression within the body of the -@code{let} expression, and can be, very simply, the local variable -@code{count}, which when evaluated returns the count. - -@need 1250 -Put together, the @code{count-words-in-defun} definition looks like this: - -@findex count-words-in-defun -@smallexample -@group -(defun count-words-in-defun () - "Return the number of words and symbols in a defun." - (beginning-of-defun) - (let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group -@group - (while - (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" - end t)) - (setq count (1+ count))) - count)) -@end group -@end smallexample - -How to test this? The function is not interactive, but it is easy to -put a wrapper around the function to make it interactive; we can use -almost the same code as for the recursive version of -@code{@value{COUNT-WORDS}}: - -@smallexample -@group -;;; @r{Interactive version.} -(defun count-words-defun () - "Number of words and symbols in a function definition." - (interactive) - (message - "Counting words and symbols in function definition ... ") -@end group -@group - (let ((count (count-words-in-defun))) - (cond - ((zerop count) - (message - "The definition does NOT have any words or symbols.")) -@end group -@group - ((= 1 count) - (message - "The definition has 1 word or symbol.")) - (t - (message - "The definition has %d words or symbols." count))))) -@end group -@end smallexample - -@need 800 -@noindent -Let's re-use @kbd{C-c =} as a convenient keybinding: - -@smallexample -(global-set-key "\C-c=" 'count-words-defun) -@end smallexample - -Now we can try out @code{count-words-defun}: install both -@code{count-words-in-defun} and @code{count-words-defun}, and set the -keybinding, and then place the cursor within the following definition: - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) - @result{} 10 -@end group -@end smallexample - -@noindent -Success! The definition has 10 words and symbols. - -The next problem is to count the numbers of words and symbols in -several definitions within a single file. - -@node Several defuns -@section Count Several @code{defuns} Within a File - -A file such as @file{simple.el} may have a hundred or more function -definitions within it. Our long term goal is to collect statistics on -many files, but as a first step, our immediate goal is to collect -statistics on one file. - -The information will be a series of numbers, each number being the -length of a function definition. We can store the numbers in a list. - -We know that we will want to incorporate the information regarding one -file with information about many other files; this means that the -function for counting definition lengths within one file need only -return the list of lengths. It need not and should not display any -messages. - -The word count commands contain one expression to jump point forward -word by word and another expression to count the jumps. The function -to return the lengths of definitions can be designed to work the same -way, with one expression to jump point forward definition by -definition and another expression to construct the lengths' list. - -This statement of the problem makes it elementary to write the -function definition. Clearly, we will start the count at the -beginning of the file, so the first command will be @code{(goto-char -(point-min))}. Next, we start the @code{while} loop; and the -true-or-false test of the loop can be a regular expression search for -the next function definition---so long as the search succeeds, point -is moved forward and then the body of the loop is evaluated. The body -needs an expression that constructs the lengths' list. @code{cons}, -the list construction command, can be used to create the list. That -is almost all there is to it. - -@need 800 -Here is what this fragment of code looks like: - -@smallexample -@group -(goto-char (point-min)) -(while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) -@end group -@end smallexample - -What we have left out is the mechanism for finding the file that -contains the function definitions. - -In previous examples, we either used this, the Info file, or we -switched back and forth to some other buffer, such as the -@file{*scratch*} buffer. - -Finding a file is a new process that we have not yet discussed. - -@node Find a File -@section Find a File -@cindex Find a File - -To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file}) -command. This command is almost, but not quite right for the lengths -problem. - -@need 1200 -Let's look at the source for @code{find-file}: - -@smallexample -@group -(defun find-file (filename) - "Edit file FILENAME. -Switch to a buffer visiting file FILENAME, -creating one if none already exists." - (interactive "FFind file: ") - (switch-to-buffer (find-file-noselect filename))) -@end group -@end smallexample - -@noindent -(The most recent version of the @code{find-file} function definition -permits you to specify optional wildcards to visit multiple files; that -makes the definition more complex and we will not discuss it here, -since it is not relevant. You can see its source using either -@kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).) - -@ignore -In Emacs 22 -(defun find-file (filename &optional wildcards) - "Edit file FILENAME. -Switch to a buffer visiting file FILENAME, -creating one if none already exists. -Interactively, the default if you just type RET is the current directory, -but the visited file name is available through the minibuffer history: -type M-n to pull it into the minibuffer. - -Interactively, or if WILDCARDS is non-nil in a call from Lisp, -expand wildcards (if any) and visit multiple files. You can -suppress wildcard expansion by setting `find-file-wildcards' to nil. - -To visit a file without any kind of conversion and without -automatically choosing a major mode, use \\[find-file-literally]." - (interactive (find-file-read-args "Find file: " nil)) - (let ((value (find-file-noselect filename nil nil wildcards))) - (if (listp value) - (mapcar 'switch-to-buffer (nreverse value)) - (switch-to-buffer value)))) -@end ignore - -The definition I am showing possesses short but complete documentation -and an interactive specification that prompts you for a file name when -you use the command interactively. The body of the definition -contains two functions, @code{find-file-noselect} and -@code{switch-to-buffer}. - -According to its documentation as shown by @kbd{C-h f} (the -@code{describe-function} command), the @code{find-file-noselect} -function reads the named file into a buffer and returns the buffer. -(Its most recent version includes an optional wildcards argument, -too, as well as another to read a file literally and an other you -suppress warning messages. These optional arguments are irrelevant.) - -However, the @code{find-file-noselect} function does not select the -buffer in which it puts the file. Emacs does not switch its attention -(or yours if you are using @code{find-file-noselect}) to the selected -buffer. That is what @code{switch-to-buffer} does: it switches the -buffer to which Emacs attention is directed; and it switches the -buffer displayed in the window to the new buffer. We have discussed -buffer switching elsewhere. (@xref{Switching Buffers}.) - -In this histogram project, we do not need to display each file on the -screen as the program determines the length of each definition within -it. Instead of employing @code{switch-to-buffer}, we can work with -@code{set-buffer}, which redirects the attention of the computer -program to a different buffer but does not redisplay it on the screen. -So instead of calling on @code{find-file} to do the job, we must write -our own expression. - -The task is easy: use @code{find-file-noselect} and @code{set-buffer}. - -@node lengths-list-file -@section @code{lengths-list-file} in Detail - -The core of the @code{lengths-list-file} function is a @code{while} -loop containing a function to move point forward `defun by defun' and -a function to count the number of words and symbols in each defun. -This core must be surrounded by functions that do various other tasks, -including finding the file, and ensuring that point starts out at the -beginning of the file. The function definition looks like this: -@findex lengths-list-file - -@smallexample -@group -(defun lengths-list-file (filename) - "Return list of definitions' lengths within FILE. -The returned list is a list of numbers. -Each number is the number of words or -symbols in one function definition." -@end group -@group - (message "Working on `%s' ... " filename) - (save-excursion - (let ((buffer (find-file-noselect filename)) - (lengths-list)) - (set-buffer buffer) - (setq buffer-read-only t) - (widen) - (goto-char (point-min)) - (while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) - (kill-buffer buffer) - lengths-list))) -@end group -@end smallexample - -@noindent -The function is passed one argument, the name of the file on which it -will work. It has four lines of documentation, but no interactive -specification. Since people worry that a computer is broken if they -don't see anything going on, the first line of the body is a -message. - -The next line contains a @code{save-excursion} that returns Emacs's -attention to the current buffer when the function completes. This is -useful in case you embed this function in another function that -presumes point is restored to the original buffer. - -In the varlist of the @code{let} expression, Emacs finds the file and -binds the local variable @code{buffer} to the buffer containing the -file. At the same time, Emacs creates @code{lengths-list} as a local -variable. - -Next, Emacs switches its attention to the buffer. - -In the following line, Emacs makes the buffer read-only. Ideally, -this line is not necessary. None of the functions for counting words -and symbols in a function definition should change the buffer. -Besides, the buffer is not going to be saved, even if it were changed. -This line is entirely the consequence of great, perhaps excessive, -caution. The reason for the caution is that this function and those -it calls work on the sources for Emacs and it is inconvenient if they -are inadvertently modified. It goes without saying that I did not -realize a need for this line until an experiment went awry and started -to modify my Emacs source files @dots{} - -Next comes a call to widen the buffer if it is narrowed. This -function is usually not needed---Emacs creates a fresh buffer if none -already exists; but if a buffer visiting the file already exists Emacs -returns that one. In this case, the buffer may be narrowed and must -be widened. If we wanted to be fully `user-friendly', we would -arrange to save the restriction and the location of point, but we -won't. - -The @code{(goto-char (point-min))} expression moves point to the -beginning of the buffer. - -Then comes a @code{while} loop in which the `work' of the function is -carried out. In the loop, Emacs determines the length of each -definition and constructs a lengths' list containing the information. - -Emacs kills the buffer after working through it. This is to save -space inside of Emacs. My version of GNU Emacs 19 contained over 300 -source files of interest; GNU Emacs 22 contains over a thousand source -files. Another function will apply @code{lengths-list-file} to each -of the files. - -Finally, the last expression within the @code{let} expression is the -@code{lengths-list} variable; its value is returned as the value of -the whole function. - -You can try this function by installing it in the usual fashion. Then -place your cursor after the following expression and type @kbd{C-x -C-e} (@code{eval-last-sexp}). - -@c !!! 22.1.1 lisp sources location here -@smallexample -(lengths-list-file - "/usr/local/share/emacs/22.1/lisp/emacs-lisp/debug.el") -@end smallexample - -@noindent -You may need to change the pathname of the file; the one here is for -GNU Emacs version 22.1. To change the expression, copy it to -the @file{*scratch*} buffer and edit it. - -@need 1200 -@noindent -Also, to see the full length of the list, rather than a truncated -version, you may have to evaluate the following: -@c We do not want to insert, so do not mention the zero prefix argument. - -@smallexample -(custom-set-variables '(eval-expression-print-length nil)) -@end smallexample - -@noindent -(@xref{defcustom, , Specifying Variables using @code{defcustom}}. -Then evaluate the @code{lengths-list-file} expression.) - -@need 1200 -The lengths' list for @file{debug.el} takes less than a second to -produce and looks like this in GNU Emacs 22: - -@smallexample -(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587) -@end smallexample - -@need 1500 -(Using my old machine, the version 19 lengths' list for @file{debug.el} -took seven seconds to produce and looked like this: - -@smallexample -(75 41 80 62 20 45 44 68 45 12 34 235) -@end smallexample - -@noindent -The newer version of @file{debug.el} contains more defuns than the -earlier one; and my new machine is much faster than the old one.) - -Note that the length of the last definition in the file is first in -the list. - -@node Several files -@section Count Words in @code{defuns} in Different Files - -In the previous section, we created a function that returns a list of -the lengths of each definition in a file. Now, we want to define a -function to return a master list of the lengths of the definitions in -a list of files. - -Working on each of a list of files is a repetitious act, so we can use -either a @code{while} loop or recursion. - -@menu -* lengths-list-many-files:: Return a list of the lengths of defuns. -* append:: Attach one list to another. -@end menu - -@ifnottex -@node lengths-list-many-files -@unnumberedsubsec Determine the lengths of @code{defuns} -@end ifnottex - -The design using a @code{while} loop is routine. The argument passed -the function is a list of files. As we saw earlier (@pxref{Loop -Example}), you can write a @code{while} loop so that the body of the -loop is evaluated if such a list contains elements, but to exit the -loop if the list is empty. For this design to work, the body of the -loop must contain an expression that shortens the list each time the -body is evaluated, so that eventually the list is empty. The usual -technique is to set the value of the list to the value of the @sc{cdr} -of the list each time the body is evaluated. - -@need 800 -The template looks like this: - -@smallexample -@group -(while @var{test-whether-list-is-empty} - @var{body}@dots{} - @var{set-list-to-cdr-of-list}) -@end group -@end smallexample - -Also, we remember that a @code{while} loop returns @code{nil} (the -result of evaluating the true-or-false-test), not the result of any -evaluation within its body. (The evaluations within the body of the -loop are done for their side effects.) However, the expression that -sets the lengths' list is part of the body---and that is the value -that we want returned by the function as a whole. To do this, we -enclose the @code{while} loop within a @code{let} expression, and -arrange that the last element of the @code{let} expression contains -the value of the lengths' list. (@xref{Incrementing Example, , Loop -Example with an Incrementing Counter}.) - -@findex lengths-list-many-files -@need 1250 -These considerations lead us directly to the function itself: - -@smallexample -@group -;;; @r{Use @code{while} loop.} -(defun lengths-list-many-files (list-of-files) - "Return list of lengths of defuns in LIST-OF-FILES." -@end group -@group - (let (lengths-list) - -;;; @r{true-or-false-test} - (while list-of-files - (setq lengths-list - (append - lengths-list - -;;; @r{Generate a lengths' list.} - (lengths-list-file - (expand-file-name (car list-of-files))))) -@end group - -@group -;;; @r{Make files' list shorter.} - (setq list-of-files (cdr list-of-files))) - -;;; @r{Return final value of lengths' list.} - lengths-list)) -@end group -@end smallexample - -@code{expand-file-name} is a built-in function that converts a file -name to the absolute, long, path name form. The function employs the -name of the directory in which the function is called. - -@c !!! 22.1.1 lisp sources location here -@need 1500 -Thus, if @code{expand-file-name} is called on @code{debug.el} when -Emacs is visiting the -@file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory, - -@smallexample -debug.el -@end smallexample - -@need 800 -@noindent -becomes - -@c !!! 22.1.1 lisp sources location here -@smallexample -/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el -@end smallexample - -The only other new element of this function definition is the as yet -unstudied function @code{append}, which merits a short section for -itself. - -@node append -@subsection The @code{append} Function - -@need 800 -The @code{append} function attaches one list to another. Thus, - -@smallexample -(append '(1 2 3 4) '(5 6 7 8)) -@end smallexample - -@need 800 -@noindent -produces the list - -@smallexample -(1 2 3 4 5 6 7 8) -@end smallexample - -This is exactly how we want to attach two lengths' lists produced by -@code{lengths-list-file} to each other. The results contrast with -@code{cons}, - -@smallexample -(cons '(1 2 3 4) '(5 6 7 8)) -@end smallexample - -@need 1250 -@noindent -which constructs a new list in which the first argument to @code{cons} -becomes the first element of the new list: - -@smallexample -((1 2 3 4) 5 6 7 8) -@end smallexample - -@node Several files recursively -@section Recursively Count Words in Different Files - -Besides a @code{while} loop, you can work on each of a list of files -with recursion. A recursive version of @code{lengths-list-many-files} -is short and simple. - -The recursive function has the usual parts: the `do-again-test', the -`next-step-expression', and the recursive call. The `do-again-test' -determines whether the function should call itself again, which it -will do if the @code{list-of-files} contains any remaining elements; -the `next-step-expression' resets the @code{list-of-files} to the -@sc{cdr} of itself, so eventually the list will be empty; and the -recursive call calls itself on the shorter list. The complete -function is shorter than this description! -@findex recursive-lengths-list-many-files - -@smallexample -@group -(defun recursive-lengths-list-many-files (list-of-files) - "Return list of lengths of each defun in LIST-OF-FILES." - (if list-of-files ; @r{do-again-test} - (append - (lengths-list-file - (expand-file-name (car list-of-files))) - (recursive-lengths-list-many-files - (cdr list-of-files))))) -@end group -@end smallexample - -@noindent -In a sentence, the function returns the lengths' list for the first of -the @code{list-of-files} appended to the result of calling itself on -the rest of the @code{list-of-files}. - -Here is a test of @code{recursive-lengths-list-many-files}, along with -the results of running @code{lengths-list-file} on each of the files -individually. - -Install @code{recursive-lengths-list-many-files} and -@code{lengths-list-file}, if necessary, and then evaluate the -following expressions. You may need to change the files' pathnames; -those here work when this Info file and the Emacs sources are located -in their customary places. To change the expressions, copy them to -the @file{*scratch*} buffer, edit them, and then evaluate them. - -The results are shown after the @samp{@result{}}. (These results are -for files from Emacs version 22.1.1; files from other versions of -Emacs may produce different results.) - -@c !!! 22.1.1 lisp sources location here -@smallexample -@group -(cd "/usr/local/share/emacs/22.1.1/") - -(lengths-list-file "./lisp/macros.el") - @result{} (283 263 480 90) -@end group - -@group -(lengths-list-file "./lisp/mail/mailalias.el") - @result{} (38 32 29 95 178 180 321 218 324) -@end group - -@group -(lengths-list-file "./lisp/makesum.el") - @result{} (85 181) -@end group - -@group - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181) -@end group -@end smallexample - -The @code{recursive-lengths-list-many-files} function produces the -output we want. - -The next step is to prepare the data in the list for display in a graph. - -@node Prepare the data -@section Prepare the Data for Display in a Graph - -The @code{recursive-lengths-list-many-files} function returns a list -of numbers. Each number records the length of a function definition. -What we need to do now is transform this data into a list of numbers -suitable for generating a graph. The new list will tell how many -functions definitions contain less than 10 words and -symbols, how many contain between 10 and 19 words and symbols, how -many contain between 20 and 29 words and symbols, and so on. - -In brief, we need to go through the lengths' list produced by the -@code{recursive-lengths-list-many-files} function and count the number -of defuns within each range of lengths, and produce a list of those -numbers. - -@menu -* Data for Display in Detail:: -* Sorting:: Sorting lists. -* Files List:: Making a list of files. -* Counting function definitions:: -@end menu - -@ifnottex -@node Data for Display in Detail -@unnumberedsubsec The Data for Display in Detail -@end ifnottex - -Based on what we have done before, we can readily foresee that it -should not be too hard to write a function that `@sc{cdr}s' down the -lengths' list, looks at each element, determines which length range it -is in, and increments a counter for that range. - -However, before beginning to write such a function, we should consider -the advantages of sorting the lengths' list first, so the numbers are -ordered from smallest to largest. First, sorting will make it easier -to count the numbers in each range, since two adjacent numbers will -either be in the same length range or in adjacent ranges. Second, by -inspecting a sorted list, we can discover the highest and lowest -number, and thereby determine the largest and smallest length range -that we will need. - -@node Sorting -@subsection Sorting Lists -@findex sort - -Emacs contains a function to sort lists, called (as you might guess) -@code{sort}. The @code{sort} function takes two arguments, the list -to be sorted, and a predicate that determines whether the first of -two list elements is ``less'' than the second. - -As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong -Type Object as an Argument}), a predicate is a function that -determines whether some property is true or false. The @code{sort} -function will reorder a list according to whatever property the -predicate uses; this means that @code{sort} can be used to sort -non-numeric lists by non-numeric criteria---it can, for example, -alphabetize a list. - -@need 1250 -The @code{<} function is used when sorting a numeric list. For example, - -@smallexample -(sort '(4 8 21 17 33 7 21 7) '<) -@end smallexample - -@need 800 -@noindent -produces this: - -@smallexample -(4 7 7 8 17 21 21 33) -@end smallexample - -@noindent -(Note that in this example, both the arguments are quoted so that the -symbols are not evaluated before being passed to @code{sort} as -arguments.) - -Sorting the list returned by the -@code{recursive-lengths-list-many-files} function is straightforward; -it uses the @code{<} function: - -@ignore -2006 Oct 29 -In GNU Emacs 22, eval -(progn - (cd "/usr/local/share/emacs/22.0.50/") - (sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - '<)) - -@end ignore - -@smallexample -@group -(sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mailalias.el" - "./lisp/makesum.el")) - '<) -@end group -@end smallexample - -@need 800 -@noindent -which produces: - -@smallexample -(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480) -@end smallexample - -@noindent -(Note that in this example, the first argument to @code{sort} is not -quoted, since the expression must be evaluated so as to produce the -list that is passed to @code{sort}.) - -@node Files List -@subsection Making a List of Files - -The @code{recursive-lengths-list-many-files} function requires a list -of files as its argument. For our test examples, we constructed such -a list by hand; but the Emacs Lisp source directory is too large for -us to do for that. Instead, we will write a function to do the job -for us. In this function, we will use both a @code{while} loop and a -recursive call. - -@findex directory-files -We did not have to write a function like this for older versions of -GNU Emacs, since they placed all the @samp{.el} files in one -directory. Instead, we were able to use the @code{directory-files} -function, which lists the names of files that match a specified -pattern within a single directory. - -However, recent versions of Emacs place Emacs Lisp files in -sub-directories of the top level @file{lisp} directory. This -re-arrangement eases navigation. For example, all the mail related -files are in a @file{lisp} sub-directory called @file{mail}. But at -the same time, this arrangement forces us to create a file listing -function that descends into the sub-directories. - -@findex files-in-below-directory -We can create this function, called @code{files-in-below-directory}, -using familiar functions such as @code{car}, @code{nthcdr}, and -@code{substring} in conjunction with an existing function called -@code{directory-files-and-attributes}. This latter function not only -lists all the filenames in a directory, including the names -of sub-directories, but also their attributes. - -To restate our goal: to create a function that will enable us -to feed filenames to @code{recursive-lengths-list-many-files} -as a list that looks like this (but with more elements): - -@smallexample -@group -("./lisp/macros.el" - "./lisp/mail/rmail.el" - "./lisp/makesum.el") -@end group -@end smallexample - -The @code{directory-files-and-attributes} function returns a list of -lists. Each of the lists within the main list consists of 13 -elements. The first element is a string that contains the name of the -file---which, in GNU/Linux, may be a `directory file', that is to -say, a file with the special attributes of a directory. The second -element of the list is @code{t} for a directory, a string -for symbolic link (the string is the name linked to), or @code{nil}. - -For example, the first @samp{.el} file in the @file{lisp/} directory -is @file{abbrev.el}. Its name is -@file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a -directory or a symbolic link. - -@need 1000 -This is how @code{directory-files-and-attributes} lists that file and -its attributes: - -@smallexample -@group -("abbrev.el" -nil -1 -1000 -100 -@end group -@group -(20615 27034 579989 697000) -(17905 55681 0 0) -(20615 26327 734791 805000) -13188 -"-rw-r--r--" -@end group -@group -t -2971624 -773) -@end group -@end smallexample - -@need 1200 -On the other hand, @file{mail/} is a directory within the @file{lisp/} -directory. The beginning of its listing looks like this: - -@smallexample -@group -("mail" -t -@dots{} -) -@end group -@end smallexample - -(To learn about the different attributes, look at the documentation of -@code{file-attributes}. Bear in mind that the @code{file-attributes} -function does not list the filename, so its first element is -@code{directory-files-and-attributes}'s second element.) - -We will want our new function, @code{files-in-below-directory}, to -list the @samp{.el} files in the directory it is told to check, and in -any directories below that directory. - -This gives us a hint on how to construct -@code{files-in-below-directory}: within a directory, the function -should add @samp{.el} filenames to a list; and if, within a directory, -the function comes upon a sub-directory, it should go into that -sub-directory and repeat its actions. - -However, we should note that every directory contains a name that -refers to itself, called @file{.}, (``dot'') and a name that refers to -its parent directory, called @file{..} (``double dot''). (In -@file{/}, the root directory, @file{..} refers to itself, since -@file{/} has no parent.) Clearly, we do not want our -@code{files-in-below-directory} function to enter those directories, -since they always lead us, directly or indirectly, to the current -directory. - -Consequently, our @code{files-in-below-directory} function must do -several tasks: - -@itemize @bullet -@item -Check to see whether it is looking at a filename that ends in -@samp{.el}; and if so, add its name to a list. - -@item -Check to see whether it is looking at a filename that is the name of a -directory; and if so, - -@itemize @minus -@item -Check to see whether it is looking at @file{.} or @file{..}; and if -so skip it. - -@item -Or else, go into that directory and repeat the process. -@end itemize -@end itemize - -Let's write a function definition to do these tasks. We will use a -@code{while} loop to move from one filename to another within a -directory, checking what needs to be done; and we will use a recursive -call to repeat the actions on each sub-directory. The recursive -pattern is `accumulate' -(@pxref{Accumulate}), -using @code{append} as the combiner. - -@ignore -(directory-files "/usr/local/src/emacs/lisp/" t "\\.el$") -(shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'") - -(directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$") -(shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'") -@end ignore - -@c /usr/local/share/emacs/22.1.1/lisp/ - -@need 800 -Here is the function: - -@smallexample -@group -(defun files-in-below-directory (directory) - "List the .el files in DIRECTORY and in its sub-directories." - ;; Although the function will be used non-interactively, - ;; it will be easier to test if we make it interactive. - ;; The directory will have a name such as - ;; "/usr/local/share/emacs/22.1.1/lisp/" - (interactive "DDirectory name: ") -@end group -@group - (let (el-files-list - (current-directory-list - (directory-files-and-attributes directory t))) - ;; while we are in the current directory - (while current-directory-list -@end group -@group - (cond - ;; check to see whether filename ends in `.el' - ;; and if so, append its name to a list. - ((equal ".el" (substring (car (car current-directory-list)) -3)) - (setq el-files-list - (cons (car (car current-directory-list)) el-files-list))) -@end group -@group - ;; check whether filename is that of a directory - ((eq t (car (cdr (car current-directory-list)))) - ;; decide whether to skip or recurse - (if - (equal "." - (substring (car (car current-directory-list)) -1)) - ;; then do nothing since filename is that of - ;; current directory or parent, "." or ".." - () -@end group -@group - ;; else descend into the directory and repeat the process - (setq el-files-list - (append - (files-in-below-directory - (car (car current-directory-list))) - el-files-list))))) - ;; move to the next filename in the list; this also - ;; shortens the list so the while loop eventually comes to an end - (setq current-directory-list (cdr current-directory-list))) - ;; return the filenames - el-files-list)) -@end group -@end smallexample - -@c (files-in-below-directory "/usr/local/src/emacs/lisp/") -@c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") - -The @code{files-in-below-directory} @code{directory-files} function -takes one argument, the name of a directory. - -@need 1250 -Thus, on my system, - -@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/")) - -@c !!! 22.1.1 lisp sources location here -@smallexample -@group -(length - (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")) -@end group -@end smallexample - -@noindent -tells me that in and below my Lisp sources directory are 1031 -@samp{.el} files. - -@code{files-in-below-directory} returns a list in reverse alphabetical -order. An expression to sort the list in alphabetical order looks -like this: - -@smallexample -@group -(sort - (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") - 'string-lessp) -@end group -@end smallexample - -@ignore -(defun test () - "Test how long it takes to find lengths of all sorted elisp defuns." - (insert "\n" (current-time-string) "\n") - (sit-for 0) - (sort - (recursive-lengths-list-many-files - (files-in-below-directory "/usr/local/src/emacs/lisp/")) - '<) - (insert (format "%s" (current-time-string)))) -@end ignore - -@node Counting function definitions -@subsection Counting function definitions - -Our immediate goal is to generate a list that tells us how many -function definitions contain fewer than 10 words and symbols, how many -contain between 10 and 19 words and symbols, how many contain between -20 and 29 words and symbols, and so on. - -With a sorted list of numbers, this is easy: count how many elements -of the list are smaller than 10, then, after moving past the numbers -just counted, count how many are smaller than 20, then, after moving -past the numbers just counted, count how many are smaller than 30, and -so on. Each of the numbers, 10, 20, 30, 40, and the like, is one -larger than the top of that range. We can call the list of such -numbers the @code{top-of-ranges} list. - -@need 1200 -If we wished, we could generate this list automatically, but it is -simpler to write a list manually. Here it is: -@vindex top-of-ranges - -@smallexample -@group -(defvar top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250 - 260 270 280 290 300) - "List specifying ranges for `defuns-per-range'.") -@end group -@end smallexample - -To change the ranges, we edit this list. - -Next, we need to write the function that creates the list of the -number of definitions within each range. Clearly, this function must -take the @code{sorted-lengths} and the @code{top-of-ranges} lists -as arguments. - -The @code{defuns-per-range} function must do two things again and -again: it must count the number of definitions within a range -specified by the current top-of-range value; and it must shift to the -next higher value in the @code{top-of-ranges} list after counting the -number of definitions in the current range. Since each of these -actions is repetitive, we can use @code{while} loops for the job. -One loop counts the number of definitions in the range defined by the -current top-of-range value, and the other loop selects each of the -top-of-range values in turn. - -Several entries of the @code{sorted-lengths} list are counted for each -range; this means that the loop for the @code{sorted-lengths} list -will be inside the loop for the @code{top-of-ranges} list, like a -small gear inside a big gear. - -The inner loop counts the number of definitions within the range. It -is a simple counting loop of the type we have seen before. -(@xref{Incrementing Loop, , A loop with an incrementing counter}.) -The true-or-false test of the loop tests whether the value from the -@code{sorted-lengths} list is smaller than the current value of the -top of the range. If it is, the function increments the counter and -tests the next value from the @code{sorted-lengths} list. - -@need 1250 -The inner loop looks like this: - -@smallexample -@group -(while @var{length-element-smaller-than-top-of-range} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) -@end group -@end smallexample - -The outer loop must start with the lowest value of the -@code{top-of-ranges} list, and then be set to each of the succeeding -higher values in turn. This can be done with a loop like this: - -@smallexample -@group -(while top-of-ranges - @var{body-of-loop}@dots{} - (setq top-of-ranges (cdr top-of-ranges))) -@end group -@end smallexample - -@need 1200 -Put together, the two loops look like this: - -@smallexample -@group -(while top-of-ranges - - ;; @r{Count the number of elements within the current range.} - (while @var{length-element-smaller-than-top-of-range} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) - - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges))) -@end group -@end smallexample - -In addition, in each circuit of the outer loop, Emacs should record -the number of definitions within that range (the value of -@code{number-within-range}) in a list. We can use @code{cons} for -this purpose. (@xref{cons, , @code{cons}}.) - -The @code{cons} function works fine, except that the list it -constructs will contain the number of definitions for the highest -range at its beginning and the number of definitions for the lowest -range at its end. This is because @code{cons} attaches new elements -of the list to the beginning of the list, and since the two loops are -working their way through the lengths' list from the lower end first, -the @code{defuns-per-range-list} will end up largest number first. -But we will want to print our graph with smallest values first and the -larger later. The solution is to reverse the order of the -@code{defuns-per-range-list}. We can do this using the -@code{nreverse} function, which reverses the order of a list. -@findex nreverse - -@need 800 -For example, - -@smallexample -(nreverse '(1 2 3 4)) -@end smallexample - -@need 800 -@noindent -produces: - -@smallexample -(4 3 2 1) -@end smallexample - -Note that the @code{nreverse} function is ``destructive''---that is, -it changes the list to which it is applied; this contrasts with the -@code{car} and @code{cdr} functions, which are non-destructive. In -this case, we do not want the original @code{defuns-per-range-list}, -so it does not matter that it is destroyed. (The @code{reverse} -function provides a reversed copy of a list, leaving the original list -as is.) -@findex reverse - -@need 1250 -Put all together, the @code{defuns-per-range} looks like this: - -@smallexample -@group -(defun defuns-per-range (sorted-lengths top-of-ranges) - "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." - (let ((top-of-range (car top-of-ranges)) - (number-within-range 0) - defuns-per-range-list) -@end group - -@group - ;; @r{Outer loop.} - (while top-of-ranges -@end group - -@group - ;; @r{Inner loop.} - (while (and - ;; @r{Need number for numeric test.} - (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) -@end group - -@group - ;; @r{Count number of definitions within current range.} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) - - ;; @r{Exit inner loop but remain within outer loop.} -@end group - -@group - (setq defuns-per-range-list - (cons number-within-range defuns-per-range-list)) - (setq number-within-range 0) ; @r{Reset count to zero.} -@end group - -@group - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges)) - ;; @r{Specify next top of range value.} - (setq top-of-range (car top-of-ranges))) -@end group - -@group - ;; @r{Exit outer loop and count the number of defuns larger than} - ;; @r{ the largest top-of-range value.} - (setq defuns-per-range-list - (cons - (length sorted-lengths) - defuns-per-range-list)) -@end group - -@group - ;; @r{Return a list of the number of definitions within each range,} - ;; @r{ smallest to largest.} - (nreverse defuns-per-range-list))) -@end group -@end smallexample - -@need 1200 -@noindent -The function is straightforward except for one subtle feature. The -true-or-false test of the inner loop looks like this: - -@smallexample -@group -(and (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) -@end group -@end smallexample - -@need 800 -@noindent -instead of like this: - -@smallexample -(< (car sorted-lengths) top-of-range) -@end smallexample - -The purpose of the test is to determine whether the first item in the -@code{sorted-lengths} list is less than the value of the top of the -range. - -The simple version of the test works fine unless the -@code{sorted-lengths} list has a @code{nil} value. In that case, the -@code{(car sorted-lengths)} expression function returns -@code{nil}. The @code{<} function cannot compare a number to -@code{nil}, which is an empty list, so Emacs signals an error and -stops the function from attempting to continue to execute. - -The @code{sorted-lengths} list always becomes @code{nil} when the -counter reaches the end of the list. This means that any attempt to -use the @code{defuns-per-range} function with the simple version of -the test will fail. - -We solve the problem by using the @code{(car sorted-lengths)} -expression in conjunction with the @code{and} expression. The -@code{(car sorted-lengths)} expression returns a non-@code{nil} -value so long as the list has at least one number within it, but -returns @code{nil} if the list is empty. The @code{and} expression -first evaluates the @code{(car sorted-lengths)} expression, and -if it is @code{nil}, returns false @emph{without} evaluating the -@code{<} expression. But if the @code{(car sorted-lengths)} -expression returns a non-@code{nil} value, the @code{and} expression -evaluates the @code{<} expression, and returns that value as the value -of the @code{and} expression. - -@c colon in printed section title causes problem in Info cross reference -This way, we avoid an error. -@iftex -@noindent -(For information about @code{and}, see -@ref{kill-new function, , The @code{kill-new} function}.) -@end iftex -@ifinfo -@noindent -(@xref{kill-new function, , The @code{kill-new} function}, for -information about @code{and}.) -@end ifinfo - -Here is a short test of the @code{defuns-per-range} function. First, -evaluate the expression that binds (a shortened) -@code{top-of-ranges} list to the list of values, then evaluate the -expression for binding the @code{sorted-lengths} list, and then -evaluate the @code{defuns-per-range} function. - -@smallexample -@group -;; @r{(Shorter list than we will use later.)} -(setq top-of-ranges - '(110 120 130 140 150 - 160 170 180 190 200)) - -(setq sorted-lengths - '(85 86 110 116 122 129 154 176 179 200 265 300 300)) - -(defuns-per-range sorted-lengths top-of-ranges) -@end group -@end smallexample - -@need 800 -@noindent -The list returned looks like this: - -@smallexample -(2 2 2 0 0 1 0 2 0 0 4) -@end smallexample - -@noindent -Indeed, there are two elements of the @code{sorted-lengths} list -smaller than 110, two elements between 110 and 119, two elements -between 120 and 129, and so on. There are four elements with a value -of 200 or larger. - -@c The next step is to turn this numbers' list into a graph. -@node Readying a Graph -@chapter Readying a Graph -@cindex Readying a graph -@cindex Graph prototype -@cindex Prototype graph -@cindex Body of graph - -Our goal is to construct a graph showing the numbers of function -definitions of various lengths in the Emacs lisp sources. - -As a practical matter, if you were creating a graph, you would -probably use a program such as @code{gnuplot} to do the job. -(@code{gnuplot} is nicely integrated into GNU Emacs.) In this case, -however, we create one from scratch, and in the process we will -re-acquaint ourselves with some of what we learned before and learn -more. - -In this chapter, we will first write a simple graph printing function. -This first definition will be a @dfn{prototype}, a rapidly written -function that enables us to reconnoiter this unknown graph-making -territory. We will discover dragons, or find that they are myth. -After scouting the terrain, we will feel more confident and enhance -the function to label the axes automatically. - -@menu -* Columns of a graph:: -* graph-body-print:: How to print the body of a graph. -* recursive-graph-body-print:: -* Printed Axes:: -* Line Graph Exercise:: -@end menu - -@ifnottex -@node Columns of a graph -@unnumberedsec Printing the Columns of a Graph -@end ifnottex - -Since Emacs is designed to be flexible and work with all kinds of -terminals, including character-only terminals, the graph will need to -be made from one of the `typewriter' symbols. An asterisk will do; as -we enhance the graph-printing function, we can make the choice of -symbol a user option. - -We can call this function @code{graph-body-print}; it will take a -@code{numbers-list} as its only argument. At this stage, we will not -label the graph, but only print its body. - -The @code{graph-body-print} function inserts a vertical column of -asterisks for each element in the @code{numbers-list}. The height of -each line is determined by the value of that element of the -@code{numbers-list}. - -Inserting columns is a repetitive act; that means that this function can -be written either with a @code{while} loop or recursively. - -Our first challenge is to discover how to print a column of asterisks. -Usually, in Emacs, we print characters onto a screen horizontally, -line by line, by typing. We have two routes we can follow: write our -own column-insertion function or discover whether one exists in Emacs. - -To see whether there is one in Emacs, we can use the @kbd{M-x apropos} -command. This command is like the @kbd{C-h a} (@code{command-apropos}) -command, except that the latter finds only those functions that are -commands. The @kbd{M-x apropos} command lists all symbols that match -a regular expression, including functions that are not interactive. -@findex apropos - -What we want to look for is some command that prints or inserts -columns. Very likely, the name of the function will contain either -the word `print' or the word `insert' or the word `column'. -Therefore, we can simply type @kbd{M-x apropos RET -print\|insert\|column RET} and look at the result. On my system, this -command once too takes quite some time, and then produced a list of 79 -functions and variables. Now it does not take much time at all and -produces a list of 211 functions and variables. Scanning down the -list, the only function that looks as if it might do the job is -@code{insert-rectangle}. - -@need 1200 -Indeed, this is the function we want; its documentation says: - -@smallexample -@group -insert-rectangle: -Insert text of RECTANGLE with upper left corner at point. -RECTANGLE's first line is inserted at point, -its second line is inserted at a point vertically under point, etc. -RECTANGLE should be a list of strings. -After this command, the mark is at the upper left corner -and point is at the lower right corner. -@end group -@end smallexample - -We can run a quick test, to make sure it does what we expect of it. - -Here is the result of placing the cursor after the -@code{insert-rectangle} expression and typing @kbd{C-u C-x C-e} -(@code{eval-last-sexp}). The function inserts the strings -@samp{"first"}, @samp{"second"}, and @samp{"third"} at and below -point. Also the function returns @code{nil}. - -@smallexample -@group -(insert-rectangle '("first" "second" "third"))first - second - thirdnil -@end group -@end smallexample - -@noindent -Of course, we won't be inserting the text of the -@code{insert-rectangle} expression itself into the buffer in which we -are making the graph, but will call the function from our program. We -shall, however, have to make sure that point is in the buffer at the -place where the @code{insert-rectangle} function will insert its -column of strings. - -If you are reading this in Info, you can see how this works by -switching to another buffer, such as the @file{*scratch*} buffer, -placing point somewhere in the buffer, typing @kbd{M-:}, typing the -@code{insert-rectangle} expression into the minibuffer at the prompt, -and then typing @key{RET}. This causes Emacs to evaluate the -expression in the minibuffer, but to use as the value of point the -position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the -keybinding for @code{eval-expression}. Also, @code{nil} does not -appear in the @file{*scratch*} buffer since the expression is -evaluated in the minibuffer.) - -We find when we do this that point ends up at the end of the last -inserted line---that is to say, this function moves point as a -side-effect. If we were to repeat the command, with point at this -position, the next insertion would be below and to the right of the -previous insertion. We don't want this! If we are going to make a -bar graph, the columns need to be beside each other. - -So we discover that each cycle of the column-inserting @code{while} -loop must reposition point to the place we want it, and that place -will be at the top, not the bottom, of the column. Moreover, we -remember that when we print a graph, we do not expect all the columns -to be the same height. This means that the top of each column may be -at a different height from the previous one. We cannot simply -reposition point to the same line each time, but moved over to the -right---or perhaps we can@dots{} - -We are planning to make the columns of the bar graph out of asterisks. -The number of asterisks in the column is the number specified by the -current element of the @code{numbers-list}. We need to construct a -list of asterisks of the right length for each call to -@code{insert-rectangle}. If this list consists solely of the requisite -number of asterisks, then we will have position point the right number -of lines above the base for the graph to print correctly. This could -be difficult. - -Alternatively, if we can figure out some way to pass -@code{insert-rectangle} a list of the same length each time, then we -can place point on the same line each time, but move it over one -column to the right for each new column. If we do this, however, some -of the entries in the list passed to @code{insert-rectangle} must be -blanks rather than asterisks. For example, if the maximum height of -the graph is 5, but the height of the column is 3, then -@code{insert-rectangle} requires an argument that looks like this: - -@smallexample -(" " " " "*" "*" "*") -@end smallexample - -This last proposal is not so difficult, so long as we can determine -the column height. There are two ways for us to specify the column -height: we can arbitrarily state what it will be, which would work -fine for graphs of that height; or we can search through the list of -numbers and use the maximum height of the list as the maximum height -of the graph. If the latter operation were difficult, then the former -procedure would be easiest, but there is a function built into Emacs -that determines the maximum of its arguments. We can use that -function. The function is called @code{max} and it returns the -largest of all its arguments, which must be numbers. Thus, for -example, - -@smallexample -(max 3 4 6 5 7 3) -@end smallexample - -@noindent -returns 7. (A corresponding function called @code{min} returns the -smallest of all its arguments.) -@findex max -@findex min - -However, we cannot simply call @code{max} on the @code{numbers-list}; -the @code{max} function expects numbers as its argument, not a list of -numbers. Thus, the following expression, - -@smallexample -(max '(3 4 6 5 7 3)) -@end smallexample - -@need 800 -@noindent -produces the following error message; - -@smallexample -Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) -@end smallexample - -@findex apply -We need a function that passes a list of arguments to a function. -This function is @code{apply}. This function `applies' its first -argument (a function) to its remaining arguments, the last of which -may be a list. - -@need 1250 -For example, - -@smallexample -(apply 'max 3 4 7 3 '(4 8 5)) -@end smallexample - -@noindent -returns 8. - -(Incidentally, I don't know how you would learn of this function -without a book such as this. It is possible to discover other -functions, like @code{search-forward} or @code{insert-rectangle}, by -guessing at a part of their names and then using @code{apropos}. Even -though its base in metaphor is clear---`apply' its first argument to -the rest---I doubt a novice would come up with that particular word -when using @code{apropos} or other aid. Of course, I could be wrong; -after all, the function was first named by someone who had to invent -it.) - -The second and subsequent arguments to @code{apply} are optional, so -we can use @code{apply} to call a function and pass the elements of a -list to it, like this, which also returns 8: - -@smallexample -(apply 'max '(4 8 5)) -@end smallexample - -This latter way is how we will use @code{apply}. The -@code{recursive-lengths-list-many-files} function returns a numbers' -list to which we can apply @code{max} (we could also apply @code{max} to -the sorted numbers' list; it does not matter whether the list is -sorted or not.) - -@need 800 -Hence, the operation for finding the maximum height of the graph is this: - -@smallexample -(setq max-graph-height (apply 'max numbers-list)) -@end smallexample - -Now we can return to the question of how to create a list of strings -for a column of the graph. Told the maximum height of the graph -and the number of asterisks that should appear in the column, the -function should return a list of strings for the -@code{insert-rectangle} command to insert. - -Each column is made up of asterisks or blanks. Since the function is -passed the value of the height of the column and the number of -asterisks in the column, the number of blanks can be found by -subtracting the number of asterisks from the height of the column. -Given the number of blanks and the number of asterisks, two -@code{while} loops can be used to construct the list: - -@smallexample -@group -;;; @r{First version.} -(defun column-of-graph (max-graph-height actual-height) - "Return list of strings that is one column of a graph." - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) -@end group - -@group - ;; @r{Fill in asterisks.} - (while (> actual-height 0) - (setq insert-list (cons "*" insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in blanks.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons " " insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) -@end group - -@group - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -If you install this function and then evaluate the following -expression you will see that it returns the list as desired: - -@smallexample -(column-of-graph 5 3) -@end smallexample - -@need 800 -@noindent -returns - -@smallexample -(" " " " "*" "*" "*") -@end smallexample - -As written, @code{column-of-graph} contains a major flaw: the symbols -used for the blank and for the marked entries in the column are -`hard-coded' as a space and asterisk. This is fine for a prototype, -but you, or another user, may wish to use other symbols. For example, -in testing the graph function, you many want to use a period in place -of the space, to make sure the point is being repositioned properly -each time the @code{insert-rectangle} function is called; or you might -want to substitute a @samp{+} sign or other symbol for the asterisk. -You might even want to make a graph-column that is more than one -display column wide. The program should be more flexible. The way to -do that is to replace the blank and the asterisk with two variables -that we can call @code{graph-blank} and @code{graph-symbol} and define -those variables separately. - -Also, the documentation is not well written. These considerations -lead us to the second version of the function: - -@smallexample -@group -(defvar graph-symbol "*" - "String used as symbol in graph, usually an asterisk.") -@end group - -@group -(defvar graph-blank " " - "String used as blank in graph, usually a blank space. -graph-blank must be the same number of columns wide -as graph-symbol.") -@end group -@end smallexample - -@noindent -(For an explanation of @code{defvar}, see -@ref{defvar, , Initializing a Variable with @code{defvar}}.) - -@smallexample -@group -;;; @r{Second version.} -(defun column-of-graph (max-graph-height actual-height) - "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols. - -@end group -@group -The graph-symbols are contiguous entries at the end -of the list. -The list will be inserted as one column of a graph. -The strings are either graph-blank or graph-symbol." -@end group - -@group - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-symbols}.} - (while (> actual-height 0) - (setq insert-list (cons graph-symbol insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-blanks}.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons graph-blank insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) - - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -If we wished, we could rewrite @code{column-of-graph} a third time to -provide optionally for a line graph as well as for a bar graph. This -would not be hard to do. One way to think of a line graph is that it -is no more than a bar graph in which the part of each bar that is -below the top is blank. To construct a column for a line graph, the -function first constructs a list of blanks that is one shorter than -the value, then it uses @code{cons} to attach a graph symbol to the -list; then it uses @code{cons} again to attach the `top blanks' to -the list. - -It is easy to see how to write such a function, but since we don't -need it, we will not do it. But the job could be done, and if it were -done, it would be done with @code{column-of-graph}. Even more -important, it is worth noting that few changes would have to be made -anywhere else. The enhancement, if we ever wish to make it, is -simple. - -Now, finally, we come to our first actual graph printing function. -This prints the body of a graph, not the labels for the vertical and -horizontal axes, so we can call this @code{graph-body-print}. - -@node graph-body-print -@section The @code{graph-body-print} Function -@findex graph-body-print - -After our preparation in the preceding section, the -@code{graph-body-print} function is straightforward. The function -will print column after column of asterisks and blanks, using the -elements of a numbers' list to specify the number of asterisks in each -column. This is a repetitive act, which means we can use a -decrementing @code{while} loop or recursive function for the job. In -this section, we will write the definition using a @code{while} loop. - -The @code{column-of-graph} function requires the height of the graph -as an argument, so we should determine and record that as a local variable. - -This leads us to the following template for the @code{while} loop -version of this function: - -@smallexample -@group -(defun graph-body-print (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group - -@group - (while numbers-list - @var{insert-columns-and-reposition-point} - (setq numbers-list (cdr numbers-list))))) -@end group -@end smallexample - -@noindent -We need to fill in the slots of the template. - -Clearly, we can use the @code{(apply 'max numbers-list)} expression to -determine the height of the graph. - -The @code{while} loop will cycle through the @code{numbers-list} one -element at a time. As it is shortened by the @code{(setq numbers-list -(cdr numbers-list))} expression, the @sc{car} of each instance of the -list is the value of the argument for @code{column-of-graph}. - -At each cycle of the @code{while} loop, the @code{insert-rectangle} -function inserts the list returned by @code{column-of-graph}. Since -the @code{insert-rectangle} function moves point to the lower right of -the inserted rectangle, we need to save the location of point at the -time the rectangle is inserted, move back to that position after the -rectangle is inserted, and then move horizontally to the next place -from which @code{insert-rectangle} is called. - -If the inserted columns are one character wide, as they will be if -single blanks and asterisks are used, the repositioning command is -simply @code{(forward-char 1)}; however, the width of a column may be -greater than one. This means that the repositioning command should be -written @code{(forward-char symbol-width)}. The @code{symbol-width} -itself is the length of a @code{graph-blank} and can be found using -the expression @code{(length graph-blank)}. The best place to bind -the @code{symbol-width} variable to the value of the width of graph -column is in the varlist of the @code{let} expression. - -@need 1250 -These considerations lead to the following function definition: - -@smallexample -@group -(defun graph-body-print (numbers-list) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values." - - (let ((height (apply 'max numbers-list)) - (symbol-width (length graph-blank)) - from-position) -@end group - -@group - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) -@end group -@group - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n") -)) -@end group -@end smallexample - -@noindent -The one unexpected expression in this function is the -@w{@code{(sit-for 0)}} expression in the @code{while} loop. This -expression makes the graph printing operation more interesting to -watch than it would be otherwise. The expression causes Emacs to -`sit' or do nothing for a zero length of time and then redraw the -screen. Placed here, it causes Emacs to redraw the screen column by -column. Without it, Emacs would not redraw the screen until the -function exits. - -We can test @code{graph-body-print} with a short list of numbers. - -@enumerate -@item -Install @code{graph-symbol}, @code{graph-blank}, -@code{column-of-graph}, which are in -@iftex -@ref{Readying a Graph, , Readying a Graph}, -@end iftex -@ifinfo -@ref{Columns of a graph}, -@end ifinfo -and @code{graph-body-print}. - -@need 800 -@item -Copy the following expression: - -@smallexample -(graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3)) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the graph to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the @code{graph-body-print} expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the @code{graph-body-print} expression. -@end enumerate - -@need 800 -Emacs will print a graph like this: - -@smallexample -@group - * - * ** - * **** - *** **** - ********* * - ************ - ************* -@end group -@end smallexample - -@node recursive-graph-body-print -@section The @code{recursive-graph-body-print} Function -@findex recursive-graph-body-print - -The @code{graph-body-print} function may also be written recursively. -The recursive solution is divided into two parts: an outside `wrapper' -that uses a @code{let} expression to determine the values of several -variables that need only be found once, such as the maximum height of -the graph, and an inside function that is called recursively to print -the graph. - -@need 1250 -The `wrapper' is uncomplicated: - -@smallexample -@group -(defun recursive-graph-body-print (numbers-list) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values." - (let ((height (apply 'max numbers-list)) - (symbol-width (length graph-blank)) - from-position) - (recursive-graph-body-print-internal - numbers-list - height - symbol-width))) -@end group -@end smallexample - -The recursive function is a little more difficult. It has four parts: -the `do-again-test', the printing code, the recursive call, and the -`next-step-expression'. The `do-again-test' is a @code{when} -expression that determines whether the @code{numbers-list} contains -any remaining elements; if it does, the function prints one column of -the graph using the printing code and calls itself again. The -function calls itself again according to the value produced by the -`next-step-expression' which causes the call to act on a shorter -version of the @code{numbers-list}. - -@smallexample -@group -(defun recursive-graph-body-print-internal - (numbers-list height symbol-width) - "Print a bar graph. -Used within recursive-graph-body-print function." -@end group - -@group - (when numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) -@end group -@group - (goto-char from-position) - (forward-char symbol-width) - (sit-for 0) ; @r{Draw graph column by column.} - (recursive-graph-body-print-internal - (cdr numbers-list) height symbol-width))) -@end group -@end smallexample - -@need 1250 -After installation, this expression can be tested; here is a sample: - -@smallexample -(recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1)) -@end smallexample - -@need 800 -Here is what @code{recursive-graph-body-print} produces: - -@smallexample -@group - * - ** * - **** * - **** *** - * ********* - ************ - ************* -@end group -@end smallexample - -Either of these two functions, @code{graph-body-print} or -@code{recursive-graph-body-print}, create the body of a graph. - -@node Printed Axes -@section Need for Printed Axes - -A graph needs printed axes, so you can orient yourself. For a do-once -project, it may be reasonable to draw the axes by hand using Emacs's -Picture mode; but a graph drawing function may be used more than once. - -For this reason, I have written enhancements to the basic -@code{print-graph-body} function that automatically print labels for -the horizontal and vertical axes. Since the label printing functions -do not contain much new material, I have placed their description in -an appendix. @xref{Full Graph, , A Graph with Labeled Axes}. - -@node Line Graph Exercise -@section Exercise - -Write a line graph version of the graph printing functions. - -@node Emacs Initialization -@chapter Your @file{.emacs} File -@cindex @file{.emacs} file -@cindex Customizing your @file{.emacs} file -@cindex Initialization file - -``You don't have to like Emacs to like it''---this seemingly -paradoxical statement is the secret of GNU Emacs. The plain, `out of -the box' Emacs is a generic tool. Most people who use it, customize -it to suit themselves. - -GNU Emacs is mostly written in Emacs Lisp; this means that by writing -expressions in Emacs Lisp you can change or extend Emacs. - -@menu -* Default Configuration:: -* Site-wide Init:: You can write site-wide init files. -* defcustom:: Emacs will write code for you. -* Beginning init File:: How to write a @file{.emacs} init file. -* Text and Auto-fill:: Automatically wrap lines. -* Mail Aliases:: Use abbreviations for email addresses. -* Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. -* Keymaps:: More about key binding. -* Loading Files:: Load (i.e., evaluate) files automatically. -* Autoload:: Make functions available. -* Simple Extension:: Define a function; bind it to a key. -* X11 Colors:: Colors in X. -* Miscellaneous:: -* Mode Line:: How to customize your mode line. -@end menu - -@ifnottex -@node Default Configuration -@unnumberedsec Emacs's Default Configuration -@end ifnottex - -There are those who appreciate Emacs's default configuration. After -all, Emacs starts you in C mode when you edit a C file, starts you in -Fortran mode when you edit a Fortran file, and starts you in -Fundamental mode when you edit an unadorned file. This all makes -sense, if you do not know who is going to use Emacs. Who knows what a -person hopes to do with an unadorned file? Fundamental mode is the -right default for such a file, just as C mode is the right default for -editing C code. (Enough programming languages have syntaxes -that enable them to share or nearly share features, so C mode is -now provided by CC mode, the `C Collection'.) - -But when you do know who is going to use Emacs---you, -yourself---then it makes sense to customize Emacs. - -For example, I seldom want Fundamental mode when I edit an -otherwise undistinguished file; I want Text mode. This is why I -customize Emacs: so it suits me. - -You can customize and extend Emacs by writing or adapting a -@file{~/.emacs} file. This is your personal initialization file; its -contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You -may also add @file{.el} to @file{~/.emacs} and call it a -@file{~/.emacs.el} file. In the past, you were forbidden to type the -extra keystrokes that the name @file{~/.emacs.el} requires, but now -you may. The new format is consistent with the Emacs Lisp file -naming conventions; the old format saves typing.} - -A @file{~/.emacs} file contains Emacs Lisp code. You can write this -code yourself; or you can use Emacs's @code{customize} feature to write -the code for you. You can combine your own expressions and -auto-written Customize expressions in your @file{.emacs} file. - -(I myself prefer to write my own expressions, except for those, -particularly fonts, that I find easier to manipulate using the -@code{customize} command. I combine the two methods.) - -Most of this chapter is about writing expressions yourself. It -describes a simple @file{.emacs} file; for more information, see -@ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and -@ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference -Manual}. - -@node Site-wide Init -@section Site-wide Initialization Files - -@cindex @file{default.el} init file -@cindex @file{site-init.el} init file -@cindex @file{site-load.el} init file -In addition to your personal initialization file, Emacs automatically -loads various site-wide initialization files, if they exist. These -have the same form as your @file{.emacs} file, but are loaded by -everyone. - -Two site-wide initialization files, @file{site-load.el} and -@file{site-init.el}, are loaded into Emacs and then `dumped' if a -`dumped' version of Emacs is created, as is most common. (Dumped -copies of Emacs load more quickly. However, once a file is loaded and -dumped, a change to it does not lead to a change in Emacs unless you -load it yourself or re-dump Emacs. @xref{Building Emacs, , Building -Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the -@file{INSTALL} file.) - -Three other site-wide initialization files are loaded automatically -each time you start Emacs, if they exist. These are -@file{site-start.el}, which is loaded @emph{before} your @file{.emacs} -file, and @file{default.el}, and the terminal type file, which are both -loaded @emph{after} your @file{.emacs} file. - -Settings and definitions in your @file{.emacs} file will overwrite -conflicting settings and definitions in a @file{site-start.el} file, -if it exists; but the settings and definitions in a @file{default.el} -or terminal type file will overwrite those in your @file{.emacs} file. -(You can prevent interference from a terminal type file by setting -@code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A -Simple Extension}.) - -@c Rewritten to avoid overfull hbox. -The @file{INSTALL} file that comes in the distribution contains -descriptions of the @file{site-init.el} and @file{site-load.el} files. - -The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files -control loading. These files are in the @file{lisp} directory of the -Emacs distribution and are worth perusing. - -The @file{loaddefs.el} file contains a good many suggestions as to -what to put into your own @file{.emacs} file, or into a site-wide -initialization file. - -@node defcustom -@section Specifying Variables using @code{defcustom} -@findex defcustom - -You can specify variables using @code{defcustom} so that you and -others can then use Emacs's @code{customize} feature to set their -values. (You cannot use @code{customize} to write function -definitions; but you can write @code{defuns} in your @file{.emacs} -file. Indeed, you can write any Lisp expression in your @file{.emacs} -file.) - -The @code{customize} feature depends on the @code{defcustom} macro. -Although you can use @code{defvar} or @code{setq} for variables that -users set, the @code{defcustom} macro is designed for the job. - -You can use your knowledge of @code{defvar} for writing the -first three arguments for @code{defcustom}. The first argument to -@code{defcustom} is the name of the variable. The second argument is -the variable's initial value, if any; and this value is set only if -the value has not already been set. The third argument is the -documentation. - -The fourth and subsequent arguments to @code{defcustom} specify types -and options; these are not featured in @code{defvar}. (These -arguments are optional.) - -Each of these arguments consists of a keyword followed by a value. -Each keyword starts with the colon character @samp{:}. - -@need 1250 -For example, the customizable user option variable -@code{text-mode-hook} looks like this: - -@smallexample -@group -(defcustom text-mode-hook nil - "Normal hook run when entering Text mode and many related modes." - :type 'hook - :options '(turn-on-auto-fill flyspell-mode) - :group 'wp) -@end group -@end smallexample - -@noindent -The name of the variable is @code{text-mode-hook}; it has no default -value; and its documentation string tells you what it does. - -The @code{:type} keyword tells Emacs the kind of data to which -@code{text-mode-hook} should be set and how to display the value in a -Customization buffer. - -The @code{:options} keyword specifies a suggested list of values for -the variable. Usually, @code{:options} applies to a hook. -The list is only a suggestion; it is not exclusive; a person who sets -the variable may set it to other values; the list shown following the -@code{:options} keyword is intended to offer convenient choices to a -user. - -Finally, the @code{:group} keyword tells the Emacs Customization -command in which group the variable is located. This tells where to -find it. - -The @code{defcustom} macro recognizes more than a dozen keywords. -For more information, see @ref{Customization, , Writing Customization -Definitions, elisp, The GNU Emacs Lisp Reference Manual}. - -Consider @code{text-mode-hook} as an example. - -There are two ways to customize this variable. You can use the -customization command or write the appropriate expressions yourself. - -@need 800 -Using the customization command, you can type: - -@smallexample -M-x customize -@end smallexample - -@noindent -and find that the group for editing files of data is called `data'. -Enter that group. Text Mode Hook is the first member. You can click -on its various options, such as @code{turn-on-auto-fill}, to set the -values. After you click on the button to - -@smallexample -Save for Future Sessions -@end smallexample - -@noindent -Emacs will write an expression into your @file{.emacs} file. -It will look like this: - -@smallexample -@group -(custom-set-variables - ;; custom-set-variables was added by Custom. - ;; If you edit it by hand, you could mess it up, so be careful. - ;; Your init file should contain only one such instance. - ;; If there is more than one, they won't work right. - '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) -@end group -@end smallexample - -@noindent -(The @code{text-mode-hook-identify} function tells -@code{toggle-text-mode-auto-fill} which buffers are in Text mode. -It comes on automatically.) - -The @code{custom-set-variables} function works somewhat differently -than a @code{setq}. While I have never learned the differences, I -modify the @code{custom-set-variables} expressions in my @file{.emacs} -file by hand: I make the changes in what appears to me to be a -reasonable manner and have not had any problems. Others prefer to use -the Customization command and let Emacs do the work for them. - -Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. -This function sets the various font faces. Over time, I have set a -considerable number of faces. Some of the time, I re-set them using -@code{customize}; other times, I simply edit the -@code{custom-set-faces} expression in my @file{.emacs} file itself. - -The second way to customize your @code{text-mode-hook} is to set it -yourself in your @file{.emacs} file using code that has nothing to do -with the @code{custom-set-@dots{}} functions. - -@need 800 -When you do this, and later use @code{customize}, you will see a -message that says - -@smallexample -CHANGED outside Customize; operating on it here may be unreliable. -@end smallexample - -@need 800 -This message is only a warning. If you click on the button to - -@smallexample -Save for Future Sessions -@end smallexample - -@noindent -Emacs will write a @code{custom-set-@dots{}} expression near the end -of your @file{.emacs} file that will be evaluated after your -hand-written expression. It will, therefore, overrule your -hand-written expression. No harm will be done. When you do this, -however, be careful to remember which expression is active; if you -forget, you may confuse yourself. - -So long as you remember where the values are set, you will have no -trouble. In any event, the values are always set in your -initialization file, which is usually called @file{.emacs}. - -I myself use @code{customize} for hardly anything. Mostly, I write -expressions myself. - -@findex defsubst -@findex defconst -Incidentally, to be more complete concerning defines: @code{defsubst} -defines an inline function. The syntax is just like that of -@code{defun}. @code{defconst} defines a symbol as a constant. The -intent is that neither programs nor users should ever change a value -set by @code{defconst}. (You can change it; the value set is a -variable; but please do not.) - -@node Beginning init File -@section Beginning a @file{.emacs} File -@cindex @file{.emacs} file, beginning of - -When you start Emacs, it loads your @file{.emacs} file unless you tell -it not to by specifying @samp{-q} on the command line. (The -@code{emacs -q} command gives you a plain, out-of-the-box Emacs.) - -A @file{.emacs} file contains Lisp expressions. Often, these are no -more than expressions to set values; sometimes they are function -definitions. - -@xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs -Manual}, for a short description of initialization files. - -This chapter goes over some of the same ground, but is a walk among -extracts from a complete, long-used @file{.emacs} file---my own. - -The first part of the file consists of comments: reminders to myself. -By now, of course, I remember these things, but when I started, I did -not. - -@need 1200 -@smallexample -@group -;;;; Bob's .emacs file -; Robert J. Chassell -; 26 September 1985 -@end group -@end smallexample - -@noindent -Look at that date! I started this file a long time ago. I have been -adding to it ever since. - -@smallexample -@group -; Each section in this file is introduced by a -; line beginning with four semicolons; and each -; entry is introduced by a line beginning with -; three semicolons. -@end group -@end smallexample - -@noindent -This describes the usual conventions for comments in Emacs Lisp. -Everything on a line that follows a semicolon is a comment. Two, -three, and four semicolons are used as subsection and section markers. -(@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for -more about comments.) - -@smallexample -@group -;;;; The Help Key -; Control-h is the help key; -; after typing control-h, type a letter to -; indicate the subject about which you want help. -; For an explanation of the help facility, -; type control-h two times in a row. -@end group -@end smallexample - -@noindent -Just remember: type @kbd{C-h} two times for help. - -@smallexample -@group -; To find out about any mode, type control-h m -; while in that mode. For example, to find out -; about mail mode, enter mail mode and then type -; control-h m. -@end group -@end smallexample - -@noindent -`Mode help', as I call this, is very helpful. Usually, it tells you -all you need to know. - -Of course, you don't need to include comments like these in your -@file{.emacs} file. I included them in mine because I kept forgetting -about Mode help or the conventions for comments---but I was able to -remember to look here to remind myself. - -@node Text and Auto-fill -@section Text and Auto Fill Mode - -Now we come to the part that `turns on' Text mode and -Auto Fill mode. - -@smallexample -@group -;;; Text mode and Auto Fill mode -;; The next two lines put Emacs into Text mode -;; and Auto Fill mode, and are for writers who -;; want to start writing prose rather than code. -(setq-default major-mode 'text-mode) -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end group -@end smallexample - -Here is the first part of this @file{.emacs} file that does something -besides remind a forgetful human! - -The first of the two lines in parentheses tells Emacs to turn on Text -mode when you find a file, @emph{unless} that file should go into some -other mode, such as C mode. - -@cindex Per-buffer, local variables list -@cindex Local variables list, per-buffer, -@cindex Automatic mode selection -@cindex Mode selection, automatic -When Emacs reads a file, it looks at the extension to the file name, -if any. (The extension is the part that comes after a @samp{.}.) If -the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns -on C mode. Also, Emacs looks at first nonblank line of the file; if -the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs -possesses a list of extensions and specifications that it uses -automatically. In addition, Emacs looks near the last page for a -per-buffer, ``local variables list'', if any. - -@ifinfo -@xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU -Emacs Manual}. - -@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}. -@end ifinfo -@iftex -See sections ``How Major Modes are Chosen'' and ``Local Variables in -Files'' in @cite{The GNU Emacs Manual}. -@end iftex - -Now, back to the @file{.emacs} file. - -@need 800 -Here is the line again; how does it work? - -@cindex Text Mode turned on -@smallexample -(setq major-mode 'text-mode) -@end smallexample - -@noindent -This line is a short, but complete Emacs Lisp expression. - -We are already familiar with @code{setq}. It sets the following variable, -@code{major-mode}, to the subsequent value, which is @code{text-mode}. -The single quote mark before @code{text-mode} tells Emacs to deal directly -with the @code{text-mode} symbol, not with whatever it might stand for. -@xref{set & setq, , Setting the Value of a Variable}, -for a reminder of how @code{setq} works. -The main point is that there is no difference between the procedure you -use to set a value in your @file{.emacs} file and the procedure you use -anywhere else in Emacs. - -@need 800 -Here is the next line: - -@cindex Auto Fill mode turned on -@findex add-hook -@smallexample -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end smallexample - -@noindent -In this line, the @code{add-hook} command adds -@code{turn-on-auto-fill} to the variable. - -@code{turn-on-auto-fill} is the name of a program, that, you guessed -it!, turns on Auto Fill mode. - -Every time Emacs turns on Text mode, Emacs runs the commands `hooked' -onto Text mode. So every time Emacs turns on Text mode, Emacs also -turns on Auto Fill mode. - -In brief, the first line causes Emacs to enter Text mode when you edit a -file, unless the file name extension, a first non-blank line, or local -variables to tell Emacs otherwise. - -Text mode among other actions, sets the syntax table to work -conveniently for writers. In Text mode, Emacs considers an apostrophe -as part of a word like a letter; but Emacs does not consider a period -or a space as part of a word. Thus, @kbd{M-f} moves you over -@samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after -the @samp{t} of @samp{it's}. - -The second line causes Emacs to turn on Auto Fill mode when it turns -on Text mode. In Auto Fill mode, Emacs automatically breaks a line -that is too wide and brings the excessively wide part of the line down -to the next line. Emacs breaks lines between words, not within them. - -When Auto Fill mode is turned off, lines continue to the right as you -type them. Depending on how you set the value of -@code{truncate-lines}, the words you type either disappear off the -right side of the screen, or else are shown, in a rather ugly and -unreadable manner, as a continuation line on the screen. - -@need 1250 -In addition, in this part of my @file{.emacs} file, I tell the Emacs -fill commands to insert two spaces after a colon: - -@smallexample -(setq colon-double-space t) -@end smallexample - -@node Mail Aliases -@section Mail Aliases - -Here is a @code{setq} that `turns on' mail aliases, along with more -reminders. - -@smallexample -@group -;;; Mail mode -; To enter mail mode, type `C-x m' -; To enter RMAIL (for reading mail), -; type `M-x rmail' -(setq mail-aliases t) -@end group -@end smallexample - -@cindex Mail aliases -@noindent -This @code{setq} command sets the value of the variable -@code{mail-aliases} to @code{t}. Since @code{t} means true, the line -says, in effect, ``Yes, use mail aliases.'' - -Mail aliases are convenient short names for long email addresses or -for lists of email addresses. The file where you keep your `aliases' -is @file{~/.mailrc}. You write an alias like this: - -@smallexample -alias geo george@@foobar.wiz.edu -@end smallexample - -@noindent -When you write a message to George, address it to @samp{geo}; the -mailer will automatically expand @samp{geo} to the full address. - -@node Indent Tabs Mode -@section Indent Tabs Mode -@cindex Tabs, preventing -@findex indent-tabs-mode - -By default, Emacs inserts tabs in place of multiple spaces when it -formats a region. (For example, you might indent many lines of text -all at once with the @code{indent-region} command.) Tabs look fine on -a terminal or with ordinary printing, but they produce badly indented -output when you use @TeX{} or Texinfo since @TeX{} ignores tabs. - -@need 1250 -The following turns off Indent Tabs mode: - -@smallexample -@group -;;; Prevent Extraneous Tabs -(setq-default indent-tabs-mode nil) -@end group -@end smallexample - -Note that this line uses @code{setq-default} rather than the -@code{setq} command that we have seen before. The @code{setq-default} -command sets values only in buffers that do not have their own local -values for the variable. - -@ifinfo -@xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}. - -@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}. -@end ifinfo -@iftex -See sections ``Tabs vs.@: Spaces'' and ``Local Variables in -Files'' in @cite{The GNU Emacs Manual}. -@end iftex - -@need 1700 -@node Keybindings -@section Some Keybindings - -Now for some personal keybindings: - -@smallexample -@group -;;; Compare windows -(global-set-key "\C-cw" 'compare-windows) -@end group -@end smallexample - -@findex compare-windows -@code{compare-windows} is a nifty command that compares the text in -your current window with text in the next window. It makes the -comparison by starting at point in each window, moving over text in -each window as far as they match. I use this command all the time. - -This also shows how to set a key globally, for all modes. - -@cindex Setting a key globally -@cindex Global set key -@cindex Key setting globally -@findex global-set-key -The command is @code{global-set-key}. It is followed by the -keybinding. In a @file{.emacs} file, the keybinding is written as -shown: @code{\C-c} stands for `control-c', which means `press the -control key and the @key{c} key at the same time'. The @code{w} means -`press the @key{w} key'. The keybinding is surrounded by double -quotation marks. In documentation, you would write this as -@w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as -@kbd{M-c}, rather than a @key{CTRL} key, you would write -@w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, , -Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for -details.) - -The command invoked by the keys is @code{compare-windows}. Note that -@code{compare-windows} is preceded by a single quote; otherwise, Emacs -would first try to evaluate the symbol to determine its value. - -These three things, the double quotation marks, the backslash before -the @samp{C}, and the single quote mark are necessary parts of -keybinding that I tend to forget. Fortunately, I have come to -remember that I should look at my existing @file{.emacs} file, and -adapt what is there. - -As for the keybinding itself: @kbd{C-c w}. This combines the prefix -key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This -set of keys, @kbd{C-c} followed by a single character, is strictly -reserved for individuals' own use. (I call these `own' keys, since -these are for my own use.) You should always be able to create such a -keybinding for your own use without stomping on someone else's -keybinding. If you ever write an extension to Emacs, please avoid -taking any of these keys for public use. Create a key like @kbd{C-c -C-w} instead. Otherwise, we will run out of `own' keys. - -@need 1250 -Here is another keybinding, with a comment: - -@smallexample -@group -;;; Keybinding for `occur' -; I use occur a lot, so let's bind it to a key: -(global-set-key "\C-co" 'occur) -@end group -@end smallexample - -@findex occur -The @code{occur} command shows all the lines in the current buffer -that contain a match for a regular expression. Matching lines are -shown in a buffer called @file{*Occur*}. That buffer serves as a menu -to jump to occurrences. - -@findex global-unset-key -@cindex Unbinding key -@cindex Key unbinding -@need 1250 -Here is how to unbind a key, so it does not -work: - -@smallexample -@group -;;; Unbind `C-x f' -(global-unset-key "\C-xf") -@end group -@end smallexample - -There is a reason for this unbinding: I found I inadvertently typed -@w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a -file, as I intended, I accidentally set the width for filled text, -almost always to a width I did not want. Since I hardly ever reset my -default width, I simply unbound the key. - -@findex list-buffers, @r{rebound} -@findex buffer-menu, @r{bound to key} -@need 1250 -The following rebinds an existing key: - -@smallexample -@group -;;; Rebind `C-x C-b' for `buffer-menu' -(global-set-key "\C-x\C-b" 'buffer-menu) -@end group -@end smallexample - -By default, @kbd{C-x C-b} runs the -@code{list-buffers} command. This command lists -your buffers in @emph{another} window. Since I -almost always want to do something in that -window, I prefer the @code{buffer-menu} -command, which not only lists the buffers, -but moves point into that window. - -@node Keymaps -@section Keymaps -@cindex Keymaps -@cindex Rebinding keys - -Emacs uses @dfn{keymaps} to record which keys call which commands. -When you use @code{global-set-key} to set the keybinding for a single -command in all parts of Emacs, you are specifying the keybinding in -@code{current-global-map}. - -Specific modes, such as C mode or Text mode, have their own keymaps; -the mode-specific keymaps override the global map that is shared by -all buffers. - -The @code{global-set-key} function binds, or rebinds, the global -keymap. For example, the following binds the key @kbd{C-x C-b} to the -function @code{buffer-menu}: - -@smallexample -(global-set-key "\C-x\C-b" 'buffer-menu) -@end smallexample - -Mode-specific keymaps are bound using the @code{define-key} function, -which takes a specific keymap as an argument, as well as the key and -the command. For example, my @file{.emacs} file contains the -following expression to bind the @code{texinfo-insert-@@group} command -to @kbd{C-c C-c g}: - -@smallexample -@group -(define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group) -@end group -@end smallexample - -@noindent -The @code{texinfo-insert-@@group} function itself is a little extension -to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I -use this command all the time and prefer to type the three strokes -@kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}. -(@samp{@@group} and its matching @samp{@@end group} are commands that -keep all enclosed text together on one page; many multi-line examples -in this book are surrounded by @samp{@@group @dots{} @@end group}.) - -@need 1250 -Here is the @code{texinfo-insert-@@group} function definition: - -@smallexample -@group -(defun texinfo-insert-@@group () - "Insert the string @@group in a Texinfo buffer." - (interactive) - (beginning-of-line) - (insert "@@group\n")) -@end group -@end smallexample - -(Of course, I could have used Abbrev mode to save typing, rather than -write a function to insert a word; but I prefer key strokes consistent -with other Texinfo mode key bindings.) - -You will see numerous @code{define-key} expressions in -@file{loaddefs.el} as well as in the various mode libraries, such as -@file{cc-mode.el} and @file{lisp-mode.el}. - -@xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs -Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp -Reference Manual}, for more information about keymaps. - -@node Loading Files -@section Loading Files -@cindex Loading files -@c findex load - -Many people in the GNU Emacs community have written extensions to -Emacs. As time goes by, these extensions are often included in new -releases. For example, the Calendar and Diary packages are now part -of the standard GNU Emacs, as is Calc. - -You can use a @code{load} command to evaluate a complete file and -thereby install all the functions and variables in the file into Emacs. -For example: - -@c (auto-compression-mode t) - -@smallexample -(load "~/emacs/slowsplit") -@end smallexample - -This evaluates, i.e., loads, the @file{slowsplit.el} file or if it -exists, the faster, byte compiled @file{slowsplit.elc} file from the -@file{emacs} sub-directory of your home directory. The file contains -the function @code{split-window-quietly}, which John Robinson wrote in -1989. - -The @code{split-window-quietly} function splits a window with the -minimum of redisplay. I installed it in 1989 because it worked well -with the slow 1200 baud terminals I was then using. Nowadays, I only -occasionally come across such a slow connection, but I continue to use -the function because I like the way it leaves the bottom half of a -buffer in the lower of the new windows and the top half in the upper -window. - -@need 1250 -To replace the key binding for the default -@code{split-window-vertically}, you must also unset that key and bind -the keys to @code{split-window-quietly}, like this: - -@smallexample -@group -(global-unset-key "\C-x2") -(global-set-key "\C-x2" 'split-window-quietly) -@end group -@end smallexample - -@vindex load-path -If you load many extensions, as I do, then instead of specifying the -exact location of the extension file, as shown above, you can specify -that directory as part of Emacs's @code{load-path}. Then, when Emacs -loads a file, it will search that directory as well as its default -list of directories. (The default list is specified in @file{paths.h} -when Emacs is built.) - -@need 1250 -The following command adds your @file{~/emacs} directory to the -existing load path: - -@smallexample -@group -;;; Emacs Load Path -(setq load-path (cons "~/emacs" load-path)) -@end group -@end smallexample - -Incidentally, @code{load-library} is an interactive interface to the -@code{load} function. The complete function looks like this: - -@findex load-library -@smallexample -@group -(defun load-library (library) - "Load the library named LIBRARY. -This is an interface to the function `load'." - (interactive - (list (completing-read "Load library: " - (apply-partially 'locate-file-completion-table - load-path - (get-load-suffixes))))) - (load library)) -@end group -@end smallexample - -The name of the function, @code{load-library}, comes from the use of -`library' as a conventional synonym for `file'. The source for the -@code{load-library} command is in the @file{files.el} library. - -Another interactive command that does a slightly different job is -@code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for -Emacs, emacs, The GNU Emacs Manual}, for information on the -distinction between @code{load-library} and this command. - -@node Autoload -@section Autoloading -@findex autoload - -Instead of installing a function by loading the file that contains it, -or by evaluating the function definition, you can make the function -available but not actually install it until it is first called. This -is called @dfn{autoloading}. - -When you execute an autoloaded function, Emacs automatically evaluates -the file that contains the definition, and then calls the function. - -Emacs starts quicker with autoloaded functions, since their libraries -are not loaded right away; but you need to wait a moment when you -first use such a function, while its containing file is evaluated. - -Rarely used functions are frequently autoloaded. The -@file{loaddefs.el} library contains hundreds of autoloaded functions, -from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may -come to use a `rare' function frequently. When you do, you should -load that function's file with a @code{load} expression in your -@file{.emacs} file. - -In my @file{.emacs} file, I load 14 libraries that contain functions -that would otherwise be autoloaded. (Actually, it would have been -better to include these files in my `dumped' Emacs, but I forgot. -@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp -Reference Manual}, and the @file{INSTALL} file for more about -dumping.) - -You may also want to include autoloaded expressions in your @file{.emacs} -file. @code{autoload} is a built-in function that takes up to five -arguments, the final three of which are optional. The first argument -is the name of the function to be autoloaded; the second is the name -of the file to be loaded. The third argument is documentation for the -function, and the fourth tells whether the function can be called -interactively. The fifth argument tells what type of -object---@code{autoload} can handle a keymap or macro as well as a -function (the default is a function). - -@need 800 -Here is a typical example: - -@smallexample -@group -(autoload 'html-helper-mode - "html-helper-mode" "Edit HTML documents" t) -@end group -@end smallexample - -@noindent -(@code{html-helper-mode} is an older alternative to @code{html-mode}, -which is a standard part of the distribution.) - -@noindent -This expression autoloads the @code{html-helper-mode} function. It -takes it from the @file{html-helper-mode.el} file (or from the byte -compiled version @file{html-helper-mode.elc}, if that exists.) The -file must be located in a directory specified by @code{load-path}. -The documentation says that this is a mode to help you edit documents -written in the HyperText Markup Language. You can call this mode -interactively by typing @kbd{M-x html-helper-mode}. (You need to -duplicate the function's regular documentation in the autoload -expression because the regular function is not yet loaded, so its -documentation is not available.) - -@xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference -Manual}, for more information. - -@node Simple Extension -@section A Simple Extension: @code{line-to-top-of-window} -@findex line-to-top-of-window -@cindex Simple extension in @file{.emacs} file - -Here is a simple extension to Emacs that moves the line point is on to -the top of the window. I use this all the time, to make text easier -to read. - -You can put the following code into a separate file and then load it -from your @file{.emacs} file, or you can include it within your -@file{.emacs} file. - -@need 1250 -Here is the definition: - -@smallexample -@group -;;; Line to top of window; -;;; replace three keystroke sequence C-u 0 C-l -(defun line-to-top-of-window () - "Move the line point is on to top of window." - (interactive) - (recenter 0)) -@end group -@end smallexample - -@need 1250 -Now for the keybinding. - -Nowadays, function keys as well as mouse button events and -non-@sc{ascii} characters are written within square brackets, without -quotation marks. (In Emacs version 18 and before, you had to write -different function key bindings for each different make of terminal.) - -I bind @code{line-to-top-of-window} to my @key{F6} function key like -this: - -@smallexample -(global-set-key [f6] 'line-to-top-of-window) -@end smallexample - -For more information, see @ref{Init Rebinding, , Rebinding Keys in -Your Init File, emacs, The GNU Emacs Manual}. - -@cindex Conditional 'twixt two versions of Emacs -@cindex Version of Emacs, choosing -@cindex Emacs version, choosing -If you run two versions of GNU Emacs, such as versions 22 and 23, and -use one @file{.emacs} file, you can select which code to evaluate with -the following conditional: - -@smallexample -@group -(cond - ((= 22 emacs-major-version) - ;; evaluate version 22 code - ( @dots{} )) - ((= 23 emacs-major-version) - ;; evaluate version 23 code - ( @dots{} ))) -@end group -@end smallexample - -For example, recent versions blink -their cursors by default. I hate such blinking, as well as other -features, so I placed the following in my @file{.emacs} -file@footnote{When I start instances of Emacs that do not load my -@file{.emacs} file or any site file, I also turn off blinking: - -@smallexample -emacs -q --no-site-file -eval '(blink-cursor-mode nil)' - -@exdent Or nowadays, using an even more sophisticated set of options, - -emacs -Q -D -@end smallexample -}: - -@smallexample -@group -(when (>= emacs-major-version 21) - (blink-cursor-mode 0) - ;; Insert newline when you press `C-n' (next-line) - ;; at the end of the buffer - (setq next-line-add-newlines t) -@end group -@group - ;; Turn on image viewing - (auto-image-file-mode t) -@end group -@group - ;; Turn on menu bar (this bar has text) - ;; (Use numeric argument to turn on) - (menu-bar-mode 1) -@end group -@group - ;; Turn off tool bar (this bar has icons) - ;; (Use numeric argument to turn on) - (tool-bar-mode nil) -@end group -@group - ;; Turn off tooltip mode for tool bar - ;; (This mode causes icon explanations to pop up) - ;; (Use numeric argument to turn on) - (tooltip-mode nil) - ;; If tooltips turned on, make tips appear promptly - (setq tooltip-delay 0.1) ; default is 0.7 second - ) -@end group -@end smallexample - -@node X11 Colors -@section X11 Colors - -You can specify colors when you use Emacs with the MIT X Windowing -system. - -I dislike the default colors and specify my own. - -@need 1250 -Here are the expressions in my @file{.emacs} -file that set values: - -@smallexample -@group -;; Set cursor color -(set-cursor-color "white") - -;; Set mouse color -(set-mouse-color "white") - -;; Set foreground and background -(set-foreground-color "white") -(set-background-color "darkblue") -@end group - -@group -;;; Set highlighting colors for isearch and drag -(set-face-foreground 'highlight "white") -(set-face-background 'highlight "blue") -@end group - -@group -(set-face-foreground 'region "cyan") -(set-face-background 'region "blue") -@end group - -@group -(set-face-foreground 'secondary-selection "skyblue") -(set-face-background 'secondary-selection "darkblue") -@end group - -@group -;; Set calendar highlighting colors -(add-hook 'calendar-load-hook - (lambda () - (set-face-foreground 'diary-face "skyblue") - (set-face-background 'holiday-face "slate blue") - (set-face-foreground 'holiday-face "white"))) -@end group -@end smallexample - -The various shades of blue soothe my eye and prevent me from seeing -the screen flicker. - -Alternatively, I could have set my specifications in various X -initialization files. For example, I could set the foreground, -background, cursor, and pointer (i.e., mouse) colors in my -@file{~/.Xresources} file like this: - -@smallexample -@group -Emacs*foreground: white -Emacs*background: darkblue -Emacs*cursorColor: white -Emacs*pointerColor: white -@end group -@end smallexample - -In any event, since it is not part of Emacs, I set the root color of -my X window in my @file{~/.xinitrc} file, like this@footnote{I also -run more modern window managers, such as Enlightenment, Gnome, or KDE; -in those cases, I often specify an image rather than a plain color.}: - -@smallexample -xsetroot -solid Navy -fg white & -@end smallexample - -@need 1700 -@node Miscellaneous -@section Miscellaneous Settings for a @file{.emacs} File - -@need 1250 -Here are a few miscellaneous settings: -@sp 1 - -@itemize @minus -@item -Set the shape and color of the mouse cursor: - -@smallexample -@group -; Cursor shapes are defined in -; `/usr/include/X11/cursorfont.h'; -; for example, the `target' cursor is number 128; -; the `top_left_arrow' cursor is number 132. -@end group - -@group -(let ((mpointer (x-get-resource "*mpointer" - "*emacs*mpointer"))) - ;; If you have not set your mouse pointer - ;; then set it, otherwise leave as is: - (if (eq mpointer nil) - (setq mpointer "132")) ; top_left_arrow -@end group -@group - (setq x-pointer-shape (string-to-int mpointer)) - (set-mouse-color "white")) -@end group -@end smallexample - -@item -Or you can set the values of a variety of features in an alist, like -this: - -@smallexample -@group -(setq-default - default-frame-alist - '((cursor-color . "white") - (mouse-color . "white") - (foreground-color . "white") - (background-color . "DodgerBlue4") - ;; (cursor-type . bar) - (cursor-type . box) -@end group -@group - (tool-bar-lines . 0) - (menu-bar-lines . 1) - (width . 80) - (height . 58) - (font . - "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1") - )) -@end group -@end smallexample - -@item -Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL} -into @kbd{@key{CTRL}-h}.@* -(Some older keyboards needed this, although I have not seen the -problem recently.) - -@smallexample -@group -;; Translate `C-h' to . -; (keyboard-translate ?\C-h ?\C-?) - -;; Translate to `C-h'. -(keyboard-translate ?\C-? ?\C-h) -@end group -@end smallexample - -@item Turn off a blinking cursor! - -@smallexample -@group -(if (fboundp 'blink-cursor-mode) - (blink-cursor-mode -1)) -@end group -@end smallexample - -@noindent -or start GNU Emacs with the command @code{emacs -nbc}. - -@need 1250 -@item When using `grep'@* -@samp{-i}@w{ } Ignore case distinctions@* -@samp{-n}@w{ } Prefix each line of output with line number@* -@samp{-H}@w{ } Print the filename for each match.@* -@samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-} - -@smallexample -(setq grep-command "grep -i -nH -e ") -@end smallexample - -@ignore -@c Evidently, no longer needed in GNU Emacs 22 - -item Automatically uncompress compressed files when visiting them - -smallexample -(load "uncompress") -end smallexample - -@end ignore - -@item Find an existing buffer, even if it has a different name@* -This avoids problems with symbolic links. - -@smallexample -(setq find-file-existing-other-name t) -@end smallexample - -@item Set your language environment and default input method - -@smallexample -@group -(set-language-environment "latin-1") -;; Remember you can enable or disable multilingual text input -;; with the @code{toggle-input-method'} (@kbd{C-\}) command -(setq default-input-method "latin-1-prefix") -@end group -@end smallexample - -If you want to write with Chinese `GB' characters, set this instead: - -@smallexample -@group -(set-language-environment "Chinese-GB") -(setq default-input-method "chinese-tonepy") -@end group -@end smallexample -@end itemize - -@subsubheading Fixing Unpleasant Key Bindings -@cindex Key bindings, fixing -@cindex Bindings, key, fixing unpleasant - -Some systems bind keys unpleasantly. Sometimes, for example, the -@key{CTRL} key appears in an awkward spot rather than at the far left -of the home row. - -Usually, when people fix these sorts of keybindings, they do not -change their @file{~/.emacs} file. Instead, they bind the proper keys -on their consoles with the @code{loadkeys} or @code{install-keymap} -commands in their boot script and then include @code{xmodmap} commands -in their @file{.xinitrc} or @file{.Xsession} file for X Windows. - -@need 1250 -@noindent -For a boot script: - -@smallexample -@group -loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz -@exdent or -install-keymap emacs2 -@end group -@end smallexample - -@need 1250 -@noindent -For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps -Lock} key is at the far left of the home row: - -@smallexample -@group -# Bind the key labeled `Caps Lock' to `Control' -# (Such a broken user interface suggests that keyboard manufacturers -# think that computers are typewriters from 1885.) - -xmodmap -e "clear Lock" -xmodmap -e "add Control = Caps_Lock" -@end group -@end smallexample - -@need 1250 -@noindent -In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} -key to a @key{META} key: - -@smallexample -@group -# Some ill designed keyboards have a key labeled ALT and no Meta -xmodmap -e "keysym Alt_L = Meta_L Alt_L" -@end group -@end smallexample - -@need 1700 -@node Mode Line -@section A Modified Mode Line -@vindex mode-line-format -@cindex Mode line format - -Finally, a feature I really like: a modified mode line. - -When I work over a network, I forget which machine I am using. Also, -I tend to I lose track of where I am, and which line point is on. - -So I reset my mode line to look like this: - -@smallexample --:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top -@end smallexample - -I am visiting a file called @file{foo.texi}, on my machine -@file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in -Texinfo mode, and am at the top of the buffer. - -@need 1200 -My @file{.emacs} file has a section that looks like this: - -@smallexample -@group -;; Set a Mode Line that tells me which machine, which directory, -;; and which line I am on, plus the other customary information. -(setq-default mode-line-format - (quote - (#("-" 0 1 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - mode-line-mule-info - mode-line-modified - mode-line-frame-identification - " " -@end group -@group - mode-line-buffer-identification - " " - (:eval (substring - (system-name) 0 (string-match "\\..+" (system-name)))) - ":" - default-directory - #(" " 0 1 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - (line-number-mode " Line %l ") - global-mode-string -@end group -@group - #(" %[(" 0 6 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - (:eval (mode-line-mode-name)) - mode-line-process - minor-mode-alist - #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...))) - ")%] " - (-3 . "%P") - ;; "-%-" - ))) -@end group -@end smallexample - -@noindent -Here, I redefine the default mode line. Most of the parts are from -the original; but I make a few changes. I set the @emph{default} mode -line format so as to permit various modes, such as Info, to override -it. - -Many elements in the list are self-explanatory: -@code{mode-line-modified} is a variable that tells whether the buffer -has been modified, @code{mode-name} tells the name of the mode, and so -on. However, the format looks complicated because of two features we -have not discussed. - -@cindex Properties, in mode line example -The first string in the mode line is a dash or hyphen, @samp{-}. In -the old days, it would have been specified simply as @code{"-"}. But -nowadays, Emacs can add properties to a string, such as highlighting -or, as in this case, a help feature. If you place your mouse cursor -over the hyphen, some help information appears (By default, you must -wait seven-tenths of a second before the information appears. You can -change that timing by changing the value of @code{tooltip-delay}.) - -@need 1000 -The new string format has a special syntax: - -@smallexample -#("-" 0 1 (help-echo "mouse-1: select window, ...")) -@end smallexample - -@noindent -The @code{#(} begins a list. The first element of the list is the -string itself, just one @samp{-}. The second and third -elements specify the range over which the fourth element applies. A -range starts @emph{after} a character, so a zero means the range -starts just before the first character; a 1 means that the range ends -just after the first character. The third element is the property for -the range. It consists of a property list, a -property name, in this case, @samp{help-echo}, followed by a value, in this -case, a string. The second, third, and fourth elements of this new -string format can be repeated. - -@xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp -Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, -elisp, The GNU Emacs Lisp Reference Manual}, for more information. - -@code{mode-line-buffer-identification} -displays the current buffer name. It is a list -beginning @code{(#("%12b" 0 4 @dots{}}. -The @code{#(} begins the list. - -The @samp{"%12b"} displays the current buffer name, using the -@code{buffer-name} function with which we are familiar; the `12' -specifies the maximum number of characters that will be displayed. -When a name has fewer characters, whitespace is added to fill out to -this number. (Buffer names can and often should be longer than 12 -characters; this length works well in a typical 80 column wide -window.) - -@code{:eval} says to evaluate the following form and use the result as -a string to display. In this case, the expression displays the first -component of the full system name. The end of the first component is -a @samp{.} (`period'), so I use the @code{string-match} function to -tell me the length of the first component. The substring from the -zeroth character to that length is the name of the machine. - -@need 1250 -This is the expression: - -@smallexample -@group -(:eval (substring - (system-name) 0 (string-match "\\..+" (system-name)))) -@end group -@end smallexample - -@samp{%[} and @samp{%]} cause a pair of square brackets -to appear for each recursive editing level. @samp{%n} says `Narrow' -when narrowing is in effect. @samp{%P} tells you the percentage of -the buffer that is above the bottom of the window, or `Top', `Bottom', -or `All'. (A lower case @samp{p} tell you the percentage above the -@emph{top} of the window.) @samp{%-} inserts enough dashes to fill -out the line. - -Remember, ``You don't have to like Emacs to like it''---your own -Emacs can have different colors, different commands, and different -keys than a default Emacs. - -On the other hand, if you want to bring up a plain `out of the box' -Emacs, with no customization, type: - -@smallexample -emacs -q -@end smallexample - -@noindent -This will start an Emacs that does @emph{not} load your -@file{~/.emacs} initialization file. A plain, default Emacs. Nothing -more. - -@node Debugging -@chapter Debugging -@cindex debugging - -GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The -first is built into the internals of Emacs and is always with you; -the second requires that you instrument a function before you can use it. - -Both debuggers are described extensively in @ref{Debugging, , -Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}. -In this chapter, I will walk through a short example of each. - -@menu -* debug:: How to use the built-in debugger. -* debug-on-entry:: Start debugging when you call a function. -* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. -* edebug:: How to use Edebug, a source level debugger. -* Debugging Exercises:: -@end menu - -@node debug -@section @code{debug} -@findex debug - -Suppose you have written a function definition that is intended to -return the sum of the numbers 1 through a given number. (This is the -@code{triangle} function discussed earlier. @xref{Decrementing -Example, , Example with Decrementing Counter}, for a discussion.) -@c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.) - -However, your function definition has a bug. You have mistyped -@samp{1=} for @samp{1-}. Here is the broken definition: - -@findex triangle-bugged -@smallexample -@group -(defun triangle-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (setq number (1= number))) ; @r{Error here.} - total)) -@end group -@end smallexample - -If you are reading this in Info, you can evaluate this definition in -the normal fashion. You will see @code{triangle-bugged} appear in the -echo area. - -@need 1250 -Now evaluate the @code{triangle-bugged} function with an -argument of 4: - -@smallexample -(triangle-bugged 4) -@end smallexample - -@noindent -In a recent GNU Emacs, you will create and enter a @file{*Backtrace*} -buffer that says: - -@noindent -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function 1=) - (1= number) - (setq number (1= number)) - (while (> number 0) (setq total (+ total number)) - (setq number (1= number))) - (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) - triangle-bugged(4) -@end group -@group - eval((triangle-bugged 4)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(I have reformatted this example slightly; the debugger does not fold -long lines. As usual, you can quit the debugger by typing @kbd{q} in -the @file{*Backtrace*} buffer.) - -In practice, for a bug as simple as this, the `Lisp error' line will -tell you what you need to know to correct the definition. The -function @code{1=} is `void'. - -@ignore -@need 800 -In GNU Emacs 20 and before, you will see: - -@smallexample -Symbol's function definition is void:@: 1= -@end smallexample - -@noindent -which has the same meaning as the @file{*Backtrace*} buffer line in -version 21. -@end ignore - -However, suppose you are not quite certain what is going on? -You can read the complete backtrace. - -In this case, you need to run a recent GNU Emacs, which automatically -starts the debugger that puts you in the @file{*Backtrace*} buffer; or -else, you need to start the debugger manually as described below. - -Read the @file{*Backtrace*} buffer from the bottom up; it tells you -what Emacs did that led to the error. Emacs made an interactive call -to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation -of the @code{triangle-bugged} expression. Each line above tells you -what the Lisp interpreter evaluated next. - -@need 1250 -The third line from the top of the buffer is - -@smallexample -(setq number (1= number)) -@end smallexample - -@noindent -Emacs tried to evaluate this expression; in order to do so, it tried -to evaluate the inner expression shown on the second line from the -top: - -@smallexample -(1= number) -@end smallexample - -@need 1250 -@noindent -This is where the error occurred; as the top line says: - -@smallexample -Debugger entered--Lisp error: (void-function 1=) -@end smallexample - -@noindent -You can correct the mistake, re-evaluate the function definition, and -then run your test again. - -@node debug-on-entry -@section @code{debug-on-entry} -@findex debug-on-entry - -A recent GNU Emacs starts the debugger automatically when your -function has an error. - -@ignore -GNU Emacs version 20 and before did not; it simply -presented you with an error message. You had to start the debugger -manually. -@end ignore - -Incidentally, you can start the debugger manually for all versions of -Emacs; the advantage is that the debugger runs even if you do not have -a bug in your code. Sometimes your code will be free of bugs! - -You can enter the debugger when you call the function by calling -@code{debug-on-entry}. - -@need 1250 -@noindent -Type: - -@smallexample -M-x debug-on-entry RET triangle-bugged RET -@end smallexample - -@need 1250 -@noindent -Now, evaluate the following: - -@smallexample -(triangle-bugged 5) -@end smallexample - -@noindent -All versions of Emacs will create a @file{*Backtrace*} buffer and tell -you that it is beginning to evaluate the @code{triangle-bugged} -function: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--entering a function: -* triangle-bugged(5) - eval((triangle-bugged 5)) -@end group -@group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate -the first expression in @code{triangle-bugged}; the buffer will look -like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--beginning evaluation of function call form: -* (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) -* triangle-bugged(5) - eval((triangle-bugged 5)) -@end group -@group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -Now, type @kbd{d} again, eight times, slowly. Each time you type -@kbd{d}, Emacs will evaluate another expression in the function -definition. - -@need 1750 -Eventually, the buffer will look like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--beginning evaluation of function call form: -* (setq number (1= number)) -* (while (> number 0) (setq total (+ total number)) - (setq number (1= number))) -@group -@end group -* (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) -* triangle-bugged(5) - eval((triangle-bugged 5)) -@group -@end group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1500 -@noindent -Finally, after you type @kbd{d} two more times, Emacs will reach the -error, and the top two lines of the @file{*Backtrace*} buffer will look -like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function 1=) -* (1= number) -@dots{} ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -By typing @kbd{d}, you were able to step through the function. - -You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this -quits the trace, but does not cancel @code{debug-on-entry}. - -@findex cancel-debug-on-entry -To cancel the effect of @code{debug-on-entry}, call -@code{cancel-debug-on-entry} and the name of the function, like this: - -@smallexample -M-x cancel-debug-on-entry RET triangle-bugged RET -@end smallexample - -@noindent -(If you are reading this in Info, cancel @code{debug-on-entry} now.) - -@node debug-on-quit -@section @code{debug-on-quit} and @code{(debug)} - -In addition to setting @code{debug-on-error} or calling @code{debug-on-entry}, -there are two other ways to start @code{debug}. - -@findex debug-on-quit -You can start @code{debug} whenever you type @kbd{C-g} -(@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to -@code{t}. This is useful for debugging infinite loops. - -@need 1500 -@cindex @code{(debug)} in code -Or, you can insert a line that says @code{(debug)} into your code -where you want the debugger to start, like this: - -@smallexample -@group -(defun triangle-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (debug) ; @r{Start debugger.} - (setq number (1= number))) ; @r{Error here.} - total)) -@end group -@end smallexample - -The @code{debug} function is described in detail in @ref{Debugger, , -The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}. - -@node edebug -@section The @code{edebug} Source Level Debugger -@cindex Source level debugger -@findex edebug - -Edebug is a source level debugger. Edebug normally displays the -source of the code you are debugging, with an arrow at the left that -shows which line you are currently executing. - -You can walk through the execution of a function, line by line, or run -quickly until reaching a @dfn{breakpoint} where execution stops. - -Edebug is described in @ref{Edebug, , , elisp, The GNU Emacs -Lisp Reference Manual}. - -@need 1250 -Here is a bugged function definition for @code{triangle-recursively}. -@xref{Recursive triangle function, , Recursion in place of a counter}, -for a review of it. - -@smallexample -@group -(defun triangle-recursively-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) - 1 - (+ number - (triangle-recursively-bugged - (1= number))))) ; @r{Error here.} -@end group -@end smallexample - -@noindent -Normally, you would install this definition by positioning your cursor -after the function's closing parenthesis and typing @kbd{C-x C-e} -(@code{eval-last-sexp}) or else by positioning your cursor within the -definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default, -the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp -Interaction mode.) - -@need 1500 -However, to prepare this function definition for Edebug, you must -first @dfn{instrument} the code using a different command. You can do -this by positioning your cursor within or just after the definition -and typing - -@smallexample -M-x edebug-defun RET -@end smallexample - -@noindent -This will cause Emacs to load Edebug automatically if it is not -already loaded, and properly instrument the function. - -After instrumenting the function, place your cursor after the -following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}): - -@smallexample -(triangle-recursively-bugged 3) -@end smallexample - -@noindent -You will be jumped back to the source for -@code{triangle-recursively-bugged} and the cursor positioned at the -beginning of the @code{if} line of the function. Also, you will see -an arrowhead at the left hand side of that line. The arrowhead marks -the line where the function is executing. (In the following examples, -we show the arrowhead with @samp{=>}; in a windowing system, you may -see the arrowhead as a solid triangle in the window `fringe'.) - -@smallexample -=>@point{}(if (= number 1) -@end smallexample - -@noindent -@iftex -In the example, the location of point is displayed with a star, -@samp{@point{}} (in Info, it is displayed as @samp{-!-}). -@end iftex -@ifnottex -In the example, the location of point is displayed as @samp{@point{}} -(in a printed book, it is displayed with a five pointed star). -@end ifnottex - -If you now press @key{SPC}, point will move to the next expression to -be executed; the line will look like this: - -@smallexample -=>(if @point{}(= number 1) -@end smallexample - -@noindent -As you continue to press @key{SPC}, point will move from expression to -expression. At the same time, whenever an expression returns a value, -that value will be displayed in the echo area. For example, after you -move point past @code{number}, you will see the following: - -@smallexample -Result: 3 (#o3, #x3, ?\C-c) -@end smallexample - -@noindent -This means the value of @code{number} is 3, which is octal three, -hexadecimal three, and @sc{ascii} `control-c' (the third letter of the -alphabet, in case you need to know this information). - -You can continue moving through the code until you reach the line with -the error. Before evaluation, that line looks like this: - -@smallexample -=> @point{}(1= number))))) ; @r{Error here.} -@end smallexample - -@need 1250 -@noindent -When you press @key{SPC} once again, you will produce an error message -that says: - -@smallexample -Symbol's function definition is void:@: 1= -@end smallexample - -@noindent -This is the bug. - -Press @kbd{q} to quit Edebug. - -To remove instrumentation from a function definition, simply -re-evaluate it with a command that does not instrument it. -For example, you could place your cursor after the definition's -closing parenthesis and type @kbd{C-x C-e}. - -Edebug does a great deal more than walk with you through a function. -You can set it so it races through on its own, stopping only at an -error or at specified stopping points; you can cause it to display the -changing values of various expressions; you can find out how many -times a function is called, and more. - -Edebug is described in @ref{Edebug, , , elisp, The GNU Emacs -Lisp Reference Manual}. - -@need 1500 -@node Debugging Exercises -@section Debugging Exercises - -@itemize @bullet -@item -Install the @code{@value{COUNT-WORDS}} function and then cause it to -enter the built-in debugger when you call it. Run the command on a -region containing two words. You will need to press @kbd{d} a -remarkable number of times. On your system, is a `hook' called after -the command finishes? (For information on hooks, see @ref{Command -Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference -Manual}.) - -@item -Copy @code{@value{COUNT-WORDS}} into the @file{*scratch*} buffer, -instrument the function for Edebug, and walk through its execution. -The function does not need to have a bug, although you can introduce -one if you wish. If the function lacks a bug, the walk-through -completes without problems. - -@item -While running Edebug, type @kbd{?} to see a list of all the Edebug commands. -(The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e., -@kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix -for commands made outside of the Edebug debugging buffer.) - -@item -In the Edebug debugging buffer, use the @kbd{p} -(@code{edebug-bounce-point}) command to see where in the region the -@code{@value{COUNT-WORDS}} is working. - -@item -Move point to some spot further down the function and then type the -@kbd{h} (@code{edebug-goto-here}) command to jump to that location. - -@item -Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to -walk through the function on its own; use an upper case @kbd{T} for -@code{edebug-Trace-fast-mode}. - -@item -Set a breakpoint, then run Edebug in Trace mode until it reaches the -stopping point. -@end itemize - -@node Conclusion -@chapter Conclusion - -We have now reached the end of this Introduction. You have now -learned enough about programming in Emacs Lisp to set values, to write -simple @file{.emacs} files for yourself and your friends, and write -simple customizations and extensions to Emacs. - -This is a place to stop. Or, if you wish, you can now go onward, and -teach yourself. - -You have learned some of the basic nuts and bolts of programming. But -only some. There are a great many more brackets and hinges that are -easy to use that we have not touched. - -A path you can follow right now lies among the sources to GNU Emacs -and in -@ifnotinfo -@cite{The GNU Emacs Lisp Reference Manual}. -@end ifnotinfo -@ifinfo -@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU -Emacs Lisp Reference Manual}. -@end ifinfo - -The Emacs Lisp sources are an adventure. When you read the sources and -come across a function or expression that is unfamiliar, you need to -figure out or find out what it does. - -Go to the Reference Manual. It is a thorough, complete, and fairly -easy-to-read description of Emacs Lisp. It is written not only for -experts, but for people who know what you know. (The @cite{Reference -Manual} comes with the standard GNU Emacs distribution. Like this -introduction, it comes as a Texinfo source file, so you can read it -on your computer and as a typeset, printed book.) - -Go to the other built-in help that is part of GNU Emacs: the built-in -documentation for all functions and variables, and @code{find-tag}, -the program that takes you to sources. - -Here is an example of how I explore the sources. Because of its name, -@file{simple.el} is the file I looked at first, a long time ago. As -it happens some of the functions in @file{simple.el} are complicated, -or at least look complicated at first sight. The @code{open-line} -function, for example, looks complicated. - -You may want to walk through this function slowly, as we did with the -@code{forward-sentence} function. (@xref{forward-sentence, The -@code{forward-sentence} function}.) Or you may want to skip that -function and look at another, such as @code{split-line}. You don't -need to read all the functions. According to -@code{count-words-in-defun}, the @code{split-line} function contains -102 words and symbols. - -Even though it is short, @code{split-line} contains expressions -we have not studied: @code{skip-chars-forward}, @code{indent-to}, -@code{current-column} and @code{insert-and-inherit}. - -Consider the @code{skip-chars-forward} function. (It is part of the -function definition for @code{back-to-indentation}, which is shown in -@ref{Review, , Review}.) - -In GNU Emacs, you can find out more about @code{skip-chars-forward} by -typing @kbd{C-h f} (@code{describe-function}) and the name of the -function. This gives you the function documentation. - -You may be able to guess what is done by a well named function such as -@code{indent-to}; or you can look it up, too. Incidentally, the -@code{describe-function} function itself is in @file{help.el}; it is -one of those long, but decipherable functions. You can look up -@code{describe-function} using the @kbd{C-h f} command! - -In this instance, since the code is Lisp, the @file{*Help*} buffer -contains the name of the library containing the function's source. -You can put point over the name of the library and press the RET key, -which in this situation is bound to @code{help-follow}, and be taken -directly to the source, in the same way as @kbd{M-.} -(@code{find-tag}). - -The definition for @code{describe-function} illustrates how to -customize the @code{interactive} expression without using the standard -character codes; and it shows how to create a temporary buffer. - -(The @code{indent-to} function is written in C rather than Emacs Lisp; -it is a `built-in' function. @code{help-follow} takes you to its -source as does @code{find-tag}, when properly set up.) - -You can look at a function's source using @code{find-tag}, which is -bound to @kbd{M-.} Finally, you can find out what the Reference -Manual has to say by visiting the manual in Info, and typing @kbd{i} -(@code{Info-index}) and the name of the function, or by looking up the -function in the index to a printed copy of the manual. - -Similarly, you can find out what is meant by -@code{insert-and-inherit}. - -Other interesting source files include @file{paragraphs.el}, -@file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el} -file includes short, easily understood functions as well as longer -ones. The @file{loaddefs.el} file contains the many standard -autoloads and many keymaps. I have never looked at it all; only at -parts. @file{loadup.el} is the file that loads the standard parts of -Emacs; it tells you a great deal about how Emacs is built. -(@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp -Reference Manual}, for more about building.) - -As I said, you have learned some nuts and bolts; however, and very -importantly, we have hardly touched major aspects of programming; I -have said nothing about how to sort information, except to use the -predefined @code{sort} function; I have said nothing about how to store -information, except to use variables and lists; I have said nothing -about how to write programs that write programs. These are topics for -another, and different kind of book, a different kind of learning. - -What you have done is learn enough for much practical work with GNU -Emacs. What you have done is get started. This is the end of a -beginning. - -@c ================ Appendix ================ - -@node the-the -@appendix The @code{the-the} Function -@findex the-the -@cindex Duplicated words function -@cindex Words, duplicated - -Sometimes when you you write text, you duplicate words---as with ``you -you'' near the beginning of this sentence. I find that most -frequently, I duplicate ``the''; hence, I call the function for -detecting duplicated words, @code{the-the}. - -@need 1250 -As a first step, you could use the following regular expression to -search for duplicates: - -@smallexample -\\(\\w+[ \t\n]+\\)\\1 -@end smallexample - -@noindent -This regexp matches one or more word-constituent characters followed -by one or more spaces, tabs, or newlines. However, it does not detect -duplicated words on different lines, since the ending of the first -word, the end of the line, is different from the ending of the second -word, a space. (For more information about regular expressions, see -@ref{Regexp Search, , Regular Expression Searches}, as well as -@ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs -Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp, -The GNU Emacs Lisp Reference Manual}.) - -You might try searching just for duplicated word-constituent -characters but that does not work since the pattern detects doubles -such as the two occurrences of `th' in `with the'. - -Another possible regexp searches for word-constituent characters -followed by non-word-constituent characters, reduplicated. Here, -@w{@samp{\\w+}} matches one or more word-constituent characters and -@w{@samp{\\W*}} matches zero or more non-word-constituent characters. - -@smallexample -\\(\\(\\w+\\)\\W*\\)\\1 -@end smallexample - -@noindent -Again, not useful. - -Here is the pattern that I use. It is not perfect, but good enough. -@w{@samp{\\b}} matches the empty string, provided it is at the beginning -or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of -any characters that are @emph{not} an @@-sign, space, newline, or tab. - -@smallexample -\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b -@end smallexample - -One can write more complicated expressions, but I found that this -expression is good enough, so I use it. - -Here is the @code{the-the} function, as I include it in my -@file{.emacs} file, along with a handy global key binding: - -@smallexample -@group -(defun the-the () - "Search forward for for a duplicated word." - (interactive) - (message "Searching for for duplicated words ...") - (push-mark) -@end group -@group - ;; This regexp is not perfect - ;; but is fairly good over all: - (if (re-search-forward - "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move) - (message "Found duplicated word.") - (message "End of buffer"))) -@end group - -@group -;; Bind `the-the' to C-c \ -(global-set-key "\C-c\\" 'the-the) -@end group -@end smallexample - -@sp 1 -Here is test text: - -@smallexample -@group -one two two three four five -five six seven -@end group -@end smallexample - -You can substitute the other regular expressions shown above in the -function definition and try each of them on this list. - -@node Kill Ring -@appendix Handling the Kill Ring -@cindex Kill ring handling -@cindex Handling the kill ring -@cindex Ring, making a list like a - -The kill ring is a list that is transformed into a ring by the -workings of the @code{current-kill} function. The @code{yank} and -@code{yank-pop} commands use the @code{current-kill} function. - -This appendix describes the @code{current-kill} function as well as -both the @code{yank} and the @code{yank-pop} commands, but first, -consider the workings of the kill ring. - -@menu -* What the Kill Ring Does:: -* current-kill:: -* yank:: Paste a copy of a clipped element. -* yank-pop:: Insert element pointed to. -* ring file:: -@end menu - -@ifnottex -@node What the Kill Ring Does -@unnumberedsec What the Kill Ring Does -@end ifnottex - -@need 1250 -The kill ring has a default maximum length of sixty items; this number -is too large for an explanation. Instead, set it to four. Please -evaluate the following: - -@smallexample -@group -(setq old-kill-ring-max kill-ring-max) -(setq kill-ring-max 4) -@end group -@end smallexample - -@noindent -Then, please copy each line of the following indented example into the -kill ring. You may kill each line with @kbd{C-k} or mark it and copy -it with @kbd{M-w}. - -@noindent -(In a read-only buffer, such as the @file{*info*} buffer, the kill -command, @kbd{C-k} (@code{kill-line}), will not remove the text, -merely copy it to the kill ring. However, your machine may beep at -you. Alternatively, for silence, you may copy the region of each line -with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark -each line for this command to succeed, but it does not matter at which -end you put point or mark.) - -@need 1250 -@noindent -Please invoke the calls in order, so that five elements attempt to -fill the kill ring: - -@smallexample -@group -first some text -second piece of text -third line -fourth line of text -fifth bit of text -@end group -@end smallexample - -@need 1250 -@noindent -Then find the value of @code{kill-ring} by evaluating - -@smallexample -kill-ring -@end smallexample - -@need 800 -@noindent -It is: - -@smallexample -@group -("fifth bit of text" "fourth line of text" -"third line" "second piece of text") -@end group -@end smallexample - -@noindent -The first element, @samp{first some text}, was dropped. - -@need 1250 -To return to the old value for the length of the kill ring, evaluate: - -@smallexample -(setq kill-ring-max old-kill-ring-max) -@end smallexample - -@node current-kill -@appendixsec The @code{current-kill} Function -@findex current-kill - -The @code{current-kill} function changes the element in the kill ring -to which @code{kill-ring-yank-pointer} points. (Also, the -@code{kill-new} function sets @code{kill-ring-yank-pointer} to point -to the latest element of the kill ring. The @code{kill-new} -function is used directly or indirectly by @code{kill-append}, -@code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line}, -and @code{kill-region}.) - -@menu -* Code for current-kill:: -* Understanding current-kill:: -@end menu - -@ifnottex -@node Code for current-kill -@unnumberedsubsec The code for @code{current-kill} -@end ifnottex - - -@need 1500 -The @code{current-kill} function is used by @code{yank} and by -@code{yank-pop}. Here is the code for @code{current-kill}: - -@smallexample -@group -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. -@end group -@group -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." - (let ((interprogram-paste (and (= n 0) - interprogram-paste-function - (funcall interprogram-paste-function)))) -@end group -@group - (if interprogram-paste - (progn - ;; Disable the interprogram cut function when we add the new - ;; text to the kill ring, so Emacs doesn't try to own the - ;; selection, with identical text. - (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) -@end group -@group - (or kill-ring (error "Kill ring is empty")) - (let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element))))) -@end group -@end smallexample - -Remember also that the @code{kill-new} function sets -@code{kill-ring-yank-pointer} to the latest element of the kill -ring, which means that all the functions that call it set the value -indirectly: @code{kill-append}, @code{copy-region-as-kill}, -@code{kill-ring-save}, @code{kill-line}, and @code{kill-region}. - -@need 1500 -Here is the line in @code{kill-new}, which is explained in -@ref{kill-new function, , The @code{kill-new} function}. - -@smallexample -(setq kill-ring-yank-pointer kill-ring) -@end smallexample - -@ifnottex -@node Understanding current-kill -@unnumberedsubsec @code{current-kill} in Outline -@end ifnottex - -The @code{current-kill} function looks complex, but as usual, it can -be understood by taking it apart piece by piece. First look at it in -skeletal form: - -@smallexample -@group -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill." - (let @var{varlist} - @var{body}@dots{}) -@end group -@end smallexample - -This function takes two arguments, one of which is optional. It has a -documentation string. It is @emph{not} interactive. - -@menu -* Body of current-kill:: -* Digression concerning error:: How to mislead humans, but not computers. -* Determining the Element:: -@end menu - -@ifnottex -@node Body of current-kill -@unnumberedsubsubsec The Body of @code{current-kill} -@end ifnottex - -The body of the function definition is a @code{let} expression, which -itself has a body as well as a @var{varlist}. - -The @code{let} expression declares a variable that will be only usable -within the bounds of this function. This variable is called -@code{interprogram-paste} and is for copying to another program. It -is not for copying within this instance of GNU Emacs. Most window -systems provide a facility for interprogram pasting. Sadly, that -facility usually provides only for the last element. Most windowing -systems have not adopted a ring of many possibilities, even though -Emacs has provided it for decades. - -The @code{if} expression has two parts, one if there exists -@code{interprogram-paste} and one if not. - -@need 2000 -Let us consider the `if not' or else-part of the @code{current-kill} -function. (The then-part uses the @code{kill-new} function, which -we have already described. @xref{kill-new function, , The -@code{kill-new} function}.) - -@smallexample -@group -(or kill-ring (error "Kill ring is empty")) -(let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element)) -@end group -@end smallexample - -@noindent -The code first checks whether the kill ring has content; otherwise it -signals an error. - -@need 1000 -Note that the @code{or} expression is very similar to testing length -with an @code{if}: - -@findex zerop -@findex error -@smallexample -@group -(if (zerop (length kill-ring)) ; @r{if-part} - (error "Kill ring is empty")) ; @r{then-part} - ;; No else-part -@end group -@end smallexample - -@noindent -If there is not anything in the kill ring, its length must be zero and -an error message sent to the user: @samp{Kill ring is empty}. The -@code{current-kill} function uses an @code{or} expression which is -simpler. But an @code{if} expression reminds us what goes on. - -This @code{if} expression uses the function @code{zerop} which returns -true if the value it is testing is zero. When @code{zerop} tests -true, the then-part of the @code{if} is evaluated. The then-part is a -list starting with the function @code{error}, which is a function that -is similar to the @code{message} function -(@pxref{message, , The @code{message} Function}) in that -it prints a one-line message in the echo area. However, in addition -to printing a message, @code{error} also stops evaluation of the -function within which it is embedded. This means that the rest of the -function will not be evaluated if the length of the kill ring is zero. - -Then the @code{current-kill} function selects the element to return. -The selection depends on the number of places that @code{current-kill} -rotates and on where @code{kill-ring-yank-pointer} points. - -Next, either the optional @code{do-not-move} argument is true or the -current value of @code{kill-ring-yank-pointer} is set to point to the -list. Finally, another expression returns the first element of the -list even if the @code{do-not-move} argument is true. - -@ifnottex -@node Digression concerning error -@unnumberedsubsubsec Digression about the word `error' -@end ifnottex - -In my opinion, it is slightly misleading, at least to humans, to use -the term `error' as the name of the @code{error} function. A better -term would be `cancel'. Strictly speaking, of course, you cannot -point to, much less rotate a pointer to a list that has no length, so -from the point of view of the computer, the word `error' is correct. -But a human expects to attempt this sort of thing, if only to find out -whether the kill ring is full or empty. This is an act of -exploration. - -From the human point of view, the act of exploration and discovery is -not necessarily an error, and therefore should not be labeled as one, -even in the bowels of a computer. As it is, the code in Emacs implies -that a human who is acting virtuously, by exploring his or her -environment, is making an error. This is bad. Even though the computer -takes the same steps as it does when there is an `error', a term such as -`cancel' would have a clearer connotation. - -@ifnottex -@node Determining the Element -@unnumberedsubsubsec Determining the Element -@end ifnottex - -Among other actions, the else-part of the @code{if} expression sets -the value of @code{kill-ring-yank-pointer} to -@code{ARGth-kill-element} when the kill ring has something in it and -the value of @code{do-not-move} is @code{nil}. - -@need 800 -The code looks like this: - -@smallexample -@group -(nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) -@end group -@end smallexample - -This needs some examination. Unless it is not supposed to move the -pointer, the @code{current-kill} function changes where -@code{kill-ring-yank-pointer} points. -That is what the -@w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}} -expression does. Also, clearly, @code{ARGth-kill-element} is being -set to be equal to some @sc{cdr} of the kill ring, using the -@code{nthcdr} function that is described in an earlier section. -(@xref{copy-region-as-kill}.) How does it do this? - -As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function -works by repeatedly taking the @sc{cdr} of a list---it takes the -@sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{} - -@need 800 -The two following expressions produce the same result: - -@smallexample -@group -(setq kill-ring-yank-pointer (cdr kill-ring)) - -(setq kill-ring-yank-pointer (nthcdr 1 kill-ring)) -@end group -@end smallexample - -However, the @code{nthcdr} expression is more complicated. It uses -the @code{mod} function to determine which @sc{cdr} to select. - -(You will remember to look at inner functions first; indeed, we will -have to go inside the @code{mod}.) - -The @code{mod} function returns the value of its first argument modulo -the second; that is to say, it returns the remainder after dividing -the first argument by the second. The value returned has the same -sign as the second argument. - -@need 800 -Thus, - -@smallexample -@group -(mod 12 4) - @result{} 0 ;; @r{because there is no remainder} -(mod 13 4) - @result{} 1 -@end group -@end smallexample - -@need 1250 -In this case, the first argument is often smaller than the second. -That is fine. - -@smallexample -@group -(mod 0 4) - @result{} 0 -(mod 1 4) - @result{} 1 -@end group -@end smallexample - -We can guess what the @code{-} function does. It is like @code{+} but -subtracts instead of adds; the @code{-} function subtracts its second -argument from its first. Also, we already know what the @code{length} -function does (@pxref{length}). It returns the length of a list. - -And @code{n} is the name of the required argument to the -@code{current-kill} function. - -@need 1250 -So when the first argument to @code{nthcdr} is zero, the @code{nthcdr} -expression returns the whole list, as you can see by evaluating the -following: - -@smallexample -@group -;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four} -;; @r{and} (mod (- 0 4) 4) @result{} 0 -(nthcdr (mod (- 0 4) 4) - '("fourth line of text" - "third line" - "second piece of text" - "first some text")) -@end group -@end smallexample - -@need 1250 -When the first argument to the @code{current-kill} function is one, -the @code{nthcdr} expression returns the list without its first -element. - -@smallexample -@group -(nthcdr (mod (- 1 4) 4) - '("fourth line of text" - "third line" - "second piece of text" - "first some text")) -@end group -@end smallexample - -@cindex @samp{global variable} defined -@cindex @samp{variable, global}, defined -Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer} -are @dfn{global variables}. That means that any expression in Emacs -Lisp can access them. They are not like the local variables set by -@code{let} or like the symbols in an argument list. -Local variables can only be accessed -within the @code{let} that defines them or the function that specifies -them in an argument list (and within expressions called by them). - -@ignore -@c texi2dvi fails when the name of the section is within ifnottex ... -(@xref{Prevent confusion, , @code{let} Prevents Confusion}, and -@ref{defun, , The @code{defun} Macro}.) -@end ignore - -@node yank -@appendixsec @code{yank} -@findex yank - -After learning about @code{current-kill}, the code for the -@code{yank} function is almost easy. - -The @code{yank} function does not use the -@code{kill-ring-yank-pointer} variable directly. It calls -@code{insert-for-yank} which calls @code{current-kill} which sets the -@code{kill-ring-yank-pointer} variable. - -@need 1250 -The code looks like this: - -@c in GNU Emacs 22 -@smallexample -@group -(defun yank (&optional arg) - "Reinsert (\"paste\") the last stretch of killed text. -More precisely, reinsert the stretch of killed text most recently -killed OR yanked. Put point at end, and set mark at beginning. -With just \\[universal-argument] as argument, same but put point at -beginning (and mark at end). With argument N, reinsert the Nth most -recently killed stretch of killed text. - -When this command inserts killed text into the buffer, it honors -`yank-excluded-properties' and `yank-handler' as described in the -doc string for `insert-for-yank-1', which see. - -See also the command \\[yank-pop]." -@end group -@group - (interactive "*P") - (setq yank-window-start (window-start)) - ;; If we don't get all the way thru, make last-command indicate that - ;; for the following command. - (setq this-command t) - (push-mark (point)) -@end group -@group - (insert-for-yank (current-kill (cond - ((listp arg) 0) - ((eq arg '-) -2) - (t (1- arg))))) - (if (consp arg) - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. - ;; It is cleaner to avoid activation, even though the command - ;; loop would deactivate the mark because we inserted text. - (goto-char (prog1 (mark t) - (set-marker (mark-marker) (point) (current-buffer))))) -@end group -@group - ;; If we do get all the way thru, make this-command indicate that. - (if (eq this-command t) - (setq this-command 'yank)) - nil) -@end group -@end smallexample - -The key expression is @code{insert-for-yank}, which inserts the string -returned by @code{current-kill}, but removes some text properties from -it. - -However, before getting to that expression, the function sets the value -of @code{yank-window-start} to the position returned by the -@code{(window-start)} expression, the position at which the display -currently starts. The @code{yank} function also sets -@code{this-command} and pushes the mark. - -After it yanks the appropriate element, if the optional argument is a -@sc{cons} rather than a number or nothing, it puts point at beginning -of the yanked text and mark at its end. - -(The @code{prog1} function is like @code{progn} but returns the value -of its first argument rather than the value of its last argument. Its -first argument is forced to return the buffer's mark as an integer. -You can see the documentation for these functions by placing point -over them in this buffer and then typing @kbd{C-h f} -(@code{describe-function}) followed by a @kbd{RET}; the default is the -function.) - -The last part of the function tells what to do when it succeeds. - -@node yank-pop -@appendixsec @code{yank-pop} -@findex yank-pop - -After understanding @code{yank} and @code{current-kill}, you know how -to approach the @code{yank-pop} function. Leaving out the -documentation to save space, it looks like this: - -@c GNU Emacs 22 -@smallexample -@group -(defun yank-pop (&optional arg) - "@dots{}" - (interactive "*p") - (if (not (eq last-command 'yank)) - (error "Previous command was not a yank")) -@end group -@group - (setq this-command 'yank) - (unless arg (setq arg 1)) - (let ((inhibit-read-only t) - (before (< (point) (mark t)))) -@end group -@group - (if before - (funcall (or yank-undo-function 'delete-region) (point) (mark t)) - (funcall (or yank-undo-function 'delete-region) (mark t) (point))) - (setq yank-undo-function nil) -@end group -@group - (set-marker (mark-marker) (point) (current-buffer)) - (insert-for-yank (current-kill arg)) - ;; Set the window start back where it was in the yank command, - ;; if possible. - (set-window-start (selected-window) yank-window-start t) -@end group -@group - (if before - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. - ;; It is cleaner to avoid activation, even though the command - ;; loop would deactivate the mark because we inserted text. - (goto-char (prog1 (mark t) - (set-marker (mark-marker) - (point) - (current-buffer)))))) - nil) -@end group -@end smallexample - -The function is interactive with a small @samp{p} so the prefix -argument is processed and passed to the function. The command can -only be used after a previous yank; otherwise an error message is -sent. This check uses the variable @code{last-command} which is set -by @code{yank} and is discussed elsewhere. -(@xref{copy-region-as-kill}.) - -The @code{let} clause sets the variable @code{before} to true or false -depending whether point is before or after mark and then the region -between point and mark is deleted. This is the region that was just -inserted by the previous yank and it is this text that will be -replaced. - -@code{funcall} calls its first argument as a function, passing -remaining arguments to it. The first argument is whatever the -@code{or} expression returns. The two remaining arguments are the -positions of point and mark set by the preceding @code{yank} command. - -There is more, but that is the hardest part. - -@node ring file -@appendixsec The @file{ring.el} File -@cindex @file{ring.el} file - -Interestingly, GNU Emacs posses a file called @file{ring.el} that -provides many of the features we just discussed. But functions such -as @code{kill-ring-yank-pointer} do not use this library, possibly -because they were written earlier. - -@node Full Graph -@appendix A Graph with Labeled Axes - -Printed axes help you understand a graph. They convey scale. In an -earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we -wrote the code to print the body of a graph. Here we write the code -for printing and labeling vertical and horizontal axes, along with the -body itself. - -@menu -* Labeled Example:: -* print-graph Varlist:: @code{let} expression in @code{print-graph}. -* print-Y-axis:: Print a label for the vertical axis. -* print-X-axis:: Print a horizontal label. -* Print Whole Graph:: The function to print a complete graph. -@end menu - -@ifnottex -@node Labeled Example -@unnumberedsec Labeled Example Graph -@end ifnottex - -Since insertions fill a buffer to the right and below point, the new -graph printing function should first print the Y or vertical axis, -then the body of the graph, and finally the X or horizontal axis. -This sequence lays out for us the contents of the function: - -@enumerate -@item -Set up code. - -@item -Print Y axis. - -@item -Print body of graph. - -@item -Print X axis. -@end enumerate - -@need 800 -Here is an example of how a finished graph should look: - -@smallexample -@group - 10 - - * - * * - * ** - * *** - 5 - * ******* - * *** ******* - ************* - *************** - 1 - **************** - | | | | - 1 5 10 15 -@end group -@end smallexample - -@noindent -In this graph, both the vertical and the horizontal axes are labeled -with numbers. However, in some graphs, the horizontal axis is time -and would be better labeled with months, like this: - -@smallexample -@group - 5 - * - * ** * - ******* - ********** ** - 1 - ************** - | ^ | - Jan June Jan -@end group -@end smallexample - -Indeed, with a little thought, we can easily come up with a variety of -vertical and horizontal labeling schemes. Our task could become -complicated. But complications breed confusion. Rather than permit -this, it is better choose a simple labeling scheme for our first -effort, and to modify or replace it later. - -@need 1200 -These considerations suggest the following outline for the -@code{print-graph} function: - -@smallexample -@group -(defun print-graph (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group -@group - (print-Y-axis height @dots{} ) - (graph-body-print numbers-list) - (print-X-axis @dots{} ))) -@end group -@end smallexample - -We can work on each part of the @code{print-graph} function definition -in turn. - -@node print-graph Varlist -@appendixsec The @code{print-graph} Varlist -@cindex @code{print-graph} varlist - -In writing the @code{print-graph} function, the first task is to write -the varlist in the @code{let} expression. (We will leave aside for the -moment any thoughts about making the function interactive or about the -contents of its documentation string.) - -The varlist should set several values. Clearly, the top of the label -for the vertical axis must be at least the height of the graph, which -means that we must obtain this information here. Note that the -@code{print-graph-body} function also requires this information. There -is no reason to calculate the height of the graph in two different -places, so we should change @code{print-graph-body} from the way we -defined it earlier to take advantage of the calculation. - -Similarly, both the function for printing the X axis labels and the -@code{print-graph-body} function need to learn the value of the width of -each symbol. We can perform the calculation here and change the -definition for @code{print-graph-body} from the way we defined it in the -previous chapter. - -The length of the label for the horizontal axis must be at least as long -as the graph. However, this information is used only in the function -that prints the horizontal axis, so it does not need to be calculated here. - -These thoughts lead us directly to the following form for the varlist -in the @code{let} for @code{print-graph}: - -@smallexample -@group -(let ((height (apply 'max numbers-list)) ; @r{First version.} - (symbol-width (length graph-blank))) -@end group -@end smallexample - -@noindent -As we shall see, this expression is not quite right. - -@need 2000 -@node print-Y-axis -@appendixsec The @code{print-Y-axis} Function -@cindex Axis, print vertical -@cindex Y axis printing -@cindex Vertical axis printing -@cindex Print vertical axis - -The job of the @code{print-Y-axis} function is to print a label for -the vertical axis that looks like this: - -@smallexample -@group - 10 - - - - - - 5 - - - - - 1 - -@end group -@end smallexample - -@noindent -The function should be passed the height of the graph, and then should -construct and insert the appropriate numbers and marks. - -@menu -* print-Y-axis in Detail:: -* Height of label:: What height for the Y axis? -* Compute a Remainder:: How to compute the remainder of a division. -* Y Axis Element:: Construct a line for the Y axis. -* Y-axis-column:: Generate a list of Y axis labels. -* print-Y-axis Penultimate:: A not quite final version. -@end menu - -@ifnottex -@node print-Y-axis in Detail -@unnumberedsubsec The @code{print-Y-axis} Function in Detail -@end ifnottex - -It is easy enough to see in the figure what the Y axis label should -look like; but to say in words, and then to write a function -definition to do the job is another matter. It is not quite true to -say that we want a number and a tic every five lines: there are only -three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4), -but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8, -and 9). It is better to say that we want a number and a tic mark on -the base line (number 1) and then that we want a number and a tic on -the fifth line from the bottom and on every line that is a multiple of -five. - -@ifnottex -@node Height of label -@unnumberedsubsec What height should the label be? -@end ifnottex - -The next issue is what height the label should be? Suppose the maximum -height of tallest column of the graph is seven. Should the highest -label on the Y axis be @samp{5 -}, and should the graph stick up above -the label? Or should the highest label be @samp{7 -}, and mark the peak -of the graph? Or should the highest label be @code{10 -}, which is a -multiple of five, and be higher than the topmost value of the graph? - -The latter form is preferred. Most graphs are drawn within rectangles -whose sides are an integral number of steps long---5, 10, 15, and so -on for a step distance of five. But as soon as we decide to use a -step height for the vertical axis, we discover that the simple -expression in the varlist for computing the height is wrong. The -expression is @code{(apply 'max numbers-list)}. This returns the -precise height, not the maximum height plus whatever is necessary to -round up to the nearest multiple of five. A more complex expression -is required. - -As usual in cases like this, a complex problem becomes simpler if it is -divided into several smaller problems. - -First, consider the case when the highest value of the graph is an -integral multiple of five---when it is 5, 10, 15, or some higher -multiple of five. We can use this value as the Y axis height. - -A fairly simply way to determine whether a number is a multiple of -five is to divide it by five and see if the division results in a -remainder. If there is no remainder, the number is a multiple of -five. Thus, seven divided by five has a remainder of two, and seven -is not an integral multiple of five. Put in slightly different -language, more reminiscent of the classroom, five goes into seven -once, with a remainder of two. However, five goes into ten twice, -with no remainder: ten is an integral multiple of five. - -@node Compute a Remainder -@appendixsubsec Side Trip: Compute a Remainder - -@findex % @r{(remainder function)} -@cindex Remainder function, @code{%} -In Lisp, the function for computing a remainder is @code{%}. The -function returns the remainder of its first argument divided by its -second argument. As it happens, @code{%} is a function in Emacs Lisp -that you cannot discover using @code{apropos}: you find nothing if you -type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to -learn of the existence of @code{%} is to read about it in a book such -as this or in the Emacs Lisp sources. - -You can try the @code{%} function by evaluating the following two -expressions: - -@smallexample -@group -(% 7 5) - -(% 10 5) -@end group -@end smallexample - -@noindent -The first expression returns 2 and the second expression returns 0. - -To test whether the returned value is zero or some other number, we -can use the @code{zerop} function. This function returns @code{t} if -its argument, which must be a number, is zero. - -@smallexample -@group -(zerop (% 7 5)) - @result{} nil - -(zerop (% 10 5)) - @result{} t -@end group -@end smallexample - -Thus, the following expression will return @code{t} if the height -of the graph is evenly divisible by five: - -@smallexample -(zerop (% height 5)) -@end smallexample - -@noindent -(The value of @code{height}, of course, can be found from @code{(apply -'max numbers-list)}.) - -On the other hand, if the value of @code{height} is not a multiple of -five, we want to reset the value to the next higher multiple of five. -This is straightforward arithmetic using functions with which we are -already familiar. First, we divide the value of @code{height} by five -to determine how many times five goes into the number. Thus, five -goes into twelve twice. If we add one to this quotient and multiply by -five, we will obtain the value of the next multiple of five that is -larger than the height. Five goes into twelve twice. Add one to two, -and multiply by five; the result is fifteen, which is the next multiple -of five that is higher than twelve. The Lisp expression for this is: - -@smallexample -(* (1+ (/ height 5)) 5) -@end smallexample - -@noindent -For example, if you evaluate the following, the result is 15: - -@smallexample -(* (1+ (/ 12 5)) 5) -@end smallexample - -All through this discussion, we have been using `five' as the value -for spacing labels on the Y axis; but we may want to use some other -value. For generality, we should replace `five' with a variable to -which we can assign a value. The best name I can think of for this -variable is @code{Y-axis-label-spacing}. - -@need 1250 -Using this term, and an @code{if} expression, we produce the -following: - -@smallexample -@group -(if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing)) -@end group -@end smallexample - -@noindent -This expression returns the value of @code{height} itself if the height -is an even multiple of the value of the @code{Y-axis-label-spacing} or -else it computes and returns a value of @code{height} that is equal to -the next higher multiple of the value of the @code{Y-axis-label-spacing}. - -We can now include this expression in the @code{let} expression of the -@code{print-graph} function (after first setting the value of -@code{Y-axis-label-spacing}): -@vindex Y-axis-label-spacing - -@smallexample -@group -(defvar Y-axis-label-spacing 5 - "Number of lines from one Y axis label to next.") -@end group - -@group -@dots{} -(let* ((height (apply 'max numbers-list)) - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height -@end group -@group - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) - (symbol-width (length graph-blank)))) -@dots{} -@end group -@end smallexample - -@noindent -(Note use of the @code{let*} function: the initial value of height is -computed once by the @code{(apply 'max numbers-list)} expression and -then the resulting value of @code{height} is used to compute its -final value. @xref{fwd-para let, , The @code{let*} expression}, for -more about @code{let*}.) - -@node Y Axis Element -@appendixsubsec Construct a Y Axis Element - -When we print the vertical axis, we want to insert strings such as -@w{@samp{5 -}} and @w{@samp{10 - }} every five lines. -Moreover, we want the numbers and dashes to line up, so shorter -numbers must be padded with leading spaces. If some of the strings -use two digit numbers, the strings with single digit numbers must -include a leading blank space before the number. - -@findex number-to-string -To figure out the length of the number, the @code{length} function is -used. But the @code{length} function works only with a string, not with -a number. So the number has to be converted from being a number to -being a string. This is done with the @code{number-to-string} function. -For example, - -@smallexample -@group -(length (number-to-string 35)) - @result{} 2 - -(length (number-to-string 100)) - @result{} 3 -@end group -@end smallexample - -@noindent -(@code{number-to-string} is also called @code{int-to-string}; you will -see this alternative name in various sources.) - -In addition, in each label, each number is followed by a string such -as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker. -This variable is defined with @code{defvar}: - -@vindex Y-axis-tic -@smallexample -@group -(defvar Y-axis-tic " - " - "String that follows number in a Y axis label.") -@end group -@end smallexample - -The length of the Y label is the sum of the length of the Y axis tic -mark and the length of the number of the top of the graph. - -@smallexample -(length (concat (number-to-string height) Y-axis-tic))) -@end smallexample - -This value will be calculated by the @code{print-graph} function in -its varlist as @code{full-Y-label-width} and passed on. (Note that we -did not think to include this in the varlist when we first proposed it.) - -To make a complete vertical axis label, a tic mark is concatenated -with a number; and the two together may be preceded by one or more -spaces depending on how long the number is. The label consists of -three parts: the (optional) leading spaces, the number, and the tic -mark. The function is passed the value of the number for the specific -row, and the value of the width of the top line, which is calculated -(just once) by @code{print-graph}. - -@smallexample -@group -(defun Y-axis-element (number full-Y-label-width) - "Construct a NUMBERed label element. -A numbered element looks like this ` 5 - ', -and is padded as needed so all line up with -the element for the largest number." -@end group -@group - (let* ((leading-spaces - (- full-Y-label-width - (length - (concat (number-to-string number) - Y-axis-tic))))) -@end group -@group - (concat - (make-string leading-spaces ? ) - (number-to-string number) - Y-axis-tic))) -@end group -@end smallexample - -The @code{Y-axis-element} function concatenates together the leading -spaces, if any; the number, as a string; and the tic mark. - -To figure out how many leading spaces the label will need, the -function subtracts the actual length of the label---the length of the -number plus the length of the tic mark---from the desired label width. - -@findex make-string -Blank spaces are inserted using the @code{make-string} function. This -function takes two arguments: the first tells it how long the string -will be and the second is a symbol for the character to insert, in a -special format. The format is a question mark followed by a blank -space, like this, @samp{? }. @xref{Character Type, , Character Type, -elisp, The GNU Emacs Lisp Reference Manual}, for a description of the -syntax for characters. (Of course, you might want to replace the -blank space by some other character @dots{} You know what to do.) - -The @code{number-to-string} function is used in the concatenation -expression, to convert the number to a string that is concatenated -with the leading spaces and the tic mark. - -@node Y-axis-column -@appendixsubsec Create a Y Axis Column - -The preceding functions provide all the tools needed to construct a -function that generates a list of numbered and blank strings to insert -as the label for the vertical axis: - -@findex Y-axis-column -@smallexample -@group -(defun Y-axis-column (height width-of-label) - "Construct list of Y axis labels and blank strings. -For HEIGHT of line above base and WIDTH-OF-LABEL." - (let (Y-axis) -@group -@end group - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element height width-of-label) - Y-axis)) -@group -@end group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) - ;; @r{Insert base line.} - (setq Y-axis - (cons (Y-axis-element 1 width-of-label) Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -In this function, we start with the value of @code{height} and -repetitively subtract one from its value. After each subtraction, we -test to see whether the value is an integral multiple of the -@code{Y-axis-label-spacing}. If it is, we construct a numbered label -using the @code{Y-axis-element} function; if not, we construct a -blank label using the @code{make-string} function. The base line -consists of the number one followed by a tic mark. - -@need 2000 -@node print-Y-axis Penultimate -@appendixsubsec The Not Quite Final Version of @code{print-Y-axis} - -The list constructed by the @code{Y-axis-column} function is passed to -the @code{print-Y-axis} function, which inserts the list as a column. - -@findex print-Y-axis -@smallexample -@group -(defun print-Y-axis (height full-Y-label-width) - "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH. -Height must be the maximum height of the graph. -Full width is the width of the highest label element." -;; Value of height and full-Y-label-width -;; are passed by `print-graph'. -@end group -@group - (let ((start (point))) - (insert-rectangle - (Y-axis-column height full-Y-label-width)) - ;; @r{Place point ready for inserting graph.} - (goto-char start) - ;; @r{Move point forward by value of} full-Y-label-width - (forward-char full-Y-label-width))) -@end group -@end smallexample - -The @code{print-Y-axis} uses the @code{insert-rectangle} function to -insert the Y axis labels created by the @code{Y-axis-column} function. -In addition, it places point at the correct position for printing the body of -the graph. - -You can test @code{print-Y-axis}: - -@enumerate -@item -Install - -@smallexample -@group -Y-axis-label-spacing -Y-axis-tic -Y-axis-element -Y-axis-column -print-Y-axis -@end group -@end smallexample - -@item -Copy the following expression: - -@smallexample -(print-Y-axis 12 5) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the @code{graph-body-print} expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -Emacs will print labels vertically, the top one being @w{@samp{10 -@w{ -}}}. (The @code{print-graph} function will pass the value of -@code{height-of-top-line}, which in this case will end up as 15, -thereby getting rid of what might appear as a bug.) - -@need 2000 -@node print-X-axis -@appendixsec The @code{print-X-axis} Function -@cindex Axis, print horizontal -@cindex X axis printing -@cindex Print horizontal axis -@cindex Horizontal axis printing - -X axis labels are much like Y axis labels, except that the ticks are on a -line above the numbers. Labels should look like this: - -@smallexample -@group - | | | | - 1 5 10 15 -@end group -@end smallexample - -The first tic is under the first column of the graph and is preceded by -several blank spaces. These spaces provide room in rows above for the Y -axis labels. The second, third, fourth, and subsequent ticks are all -spaced equally, according to the value of @code{X-axis-label-spacing}. - -The second row of the X axis consists of numbers, preceded by several -blank spaces and also separated according to the value of the variable -@code{X-axis-label-spacing}. - -The value of the variable @code{X-axis-label-spacing} should itself be -measured in units of @code{symbol-width}, since you may want to change -the width of the symbols that you are using to print the body of the -graph without changing the ways the graph is labeled. - -@menu -* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. -* X Axis Tic Marks:: Create tic marks for the horizontal axis. -@end menu - -@ifnottex -@node Similarities differences -@unnumberedsubsec Similarities and differences -@end ifnottex - -The @code{print-X-axis} function is constructed in more or less the -same fashion as the @code{print-Y-axis} function except that it has -two lines: the line of tic marks and the numbers. We will write a -separate function to print each line and then combine them within the -@code{print-X-axis} function. - -This is a three step process: - -@enumerate -@item -Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}. - -@item -Write a function to print the X numbers, @code{print-X-axis-numbered-line}. - -@item -Write a function to print both lines, the @code{print-X-axis} function, -using @code{print-X-axis-tic-line} and -@code{print-X-axis-numbered-line}. -@end enumerate - -@node X Axis Tic Marks -@appendixsubsec X Axis Tic Marks - -The first function should print the X axis tic marks. We must specify -the tic marks themselves and their spacing: - -@smallexample -@group -(defvar X-axis-label-spacing - (if (boundp 'graph-blank) - (* 5 (length graph-blank)) 5) - "Number of units from one X axis label to next.") -@end group -@end smallexample - -@noindent -(Note that the value of @code{graph-blank} is set by another -@code{defvar}. The @code{boundp} predicate checks whether it has -already been set; @code{boundp} returns @code{nil} if it has not. If -@code{graph-blank} were unbound and we did not use this conditional -construction, in a recent GNU Emacs, we would enter the debugger and -see an error message saying @samp{@w{Debugger entered--Lisp error:} -@w{(void-variable graph-blank)}}.) - -@need 1200 -Here is the @code{defvar} for @code{X-axis-tic-symbol}: - -@smallexample -@group -(defvar X-axis-tic-symbol "|" - "String to insert to point to a column in X axis.") -@end group -@end smallexample - -@need 1250 -The goal is to make a line that looks like this: - -@smallexample - | | | | -@end smallexample - -The first tic is indented so that it is under the first column, which is -indented to provide space for the Y axis labels. - -A tic element consists of the blank spaces that stretch from one tic to -the next plus a tic symbol. The number of blanks is determined by the -width of the tic symbol and the @code{X-axis-label-spacing}. - -@need 1250 -The code looks like this: - -@smallexample -@group -;;; X-axis-tic-element -@dots{} -(concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol) -@dots{} -@end group -@end smallexample - -Next, we determine how many blanks are needed to indent the first tic -mark to the first column of the graph. This uses the value of -@code{full-Y-label-width} passed it by the @code{print-graph} function. - -@need 1250 -The code to make @code{X-axis-leading-spaces} -looks like this: - -@smallexample -@group -;; X-axis-leading-spaces -@dots{} -(make-string full-Y-label-width ? ) -@dots{} -@end group -@end smallexample - -We also need to determine the length of the horizontal axis, which is -the length of the numbers list, and the number of ticks in the horizontal -axis: - -@smallexample -@group -;; X-length -@dots{} -(length numbers-list) -@end group - -@group -;; tic-width -@dots{} -(* symbol-width X-axis-label-spacing) -@end group - -@group -;; number-of-X-ticks -(if (zerop (% (X-length tic-width))) - (/ (X-length tic-width)) - (1+ (/ (X-length tic-width)))) -@end group -@end smallexample - -@need 1250 -All this leads us directly to the function for printing the X axis tic line: - -@findex print-X-axis-tic-line -@smallexample -@group -(defun print-X-axis-tic-line - (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) - "Print ticks for X axis." - (insert X-axis-leading-spaces) - (insert X-axis-tic-symbol) ; @r{Under first column.} -@end group -@group - ;; @r{Insert second tic in the right spot.} - (insert (concat - (make-string - (- (* symbol-width X-axis-label-spacing) - ;; @r{Insert white space up to second tic symbol.} - (* 2 (length X-axis-tic-symbol))) - ? ) - X-axis-tic-symbol)) -@end group -@group - ;; @r{Insert remaining ticks.} - (while (> number-of-X-tics 1) - (insert X-axis-tic-element) - (setq number-of-X-tics (1- number-of-X-tics)))) -@end group -@end smallexample - -The line of numbers is equally straightforward: - -@need 1250 -First, we create a numbered element with blank spaces before each number: - -@findex X-axis-element -@smallexample -@group -(defun X-axis-element (number) - "Construct a numbered X axis element." - (let ((leading-spaces - (- (* symbol-width X-axis-label-spacing) - (length (number-to-string number))))) - (concat (make-string leading-spaces ? ) - (number-to-string number)))) -@end group -@end smallexample - -Next, we create the function to print the numbered line, starting with -the number ``1'' under the first column: - -@findex print-X-axis-numbered-line -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing)) - (insert X-axis-leading-spaces) - (insert "1") -@end group -@group - (insert (concat - (make-string - ;; @r{Insert white space up to next number.} - (- (* symbol-width X-axis-label-spacing) 2) - ? ) - (number-to-string number))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element number)) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -Finally, we need to write the @code{print-X-axis} that uses -@code{print-X-axis-tic-line} and -@code{print-X-axis-numbered-line}. - -The function must determine the local values of the variables used by both -@code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and -then it must call them. Also, it must print the carriage return that -separates the two lines. - -The function consists of a varlist that specifies five local variables, -and calls to each of the two line printing functions: - -@findex print-X-axis -@smallexample -@group -(defun print-X-axis (numbers-list) - "Print X axis labels to length of NUMBERS-LIST." - (let* ((leading-spaces - (make-string full-Y-label-width ? )) -@end group -@group - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string -@end group -@group - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) -@end group -@group - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group -@group - (print-X-axis-tic-line tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line tic-number leading-spaces))) -@end group -@end smallexample - -@need 1250 -You can test @code{print-X-axis}: - -@enumerate -@item -Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing}, -@code{print-X-axis-tic-line}, as well as @code{X-axis-element}, -@code{print-X-axis-numbered-line}, and @code{print-X-axis}. - -@item -Copy the following expression: - -@smallexample -@group -(progn - (let ((full-Y-label-width 5) - (symbol-width 1)) - (print-X-axis - '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16)))) -@end group -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the test expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -@need 1250 -Emacs will print the horizontal axis like this: -@sp 1 - -@smallexample -@group - | | | | | - 1 5 10 15 20 -@end group -@end smallexample - -@node Print Whole Graph -@appendixsec Printing the Whole Graph -@cindex Printing the whole graph -@cindex Whole graph printing -@cindex Graph, printing all - -Now we are nearly ready to print the whole graph. - -The function to print the graph with the proper labels follows the -outline we created earlier (@pxref{Full Graph, , A Graph with Labeled -Axes}), but with additions. - -@need 1250 -Here is the outline: - -@smallexample -@group -(defun print-graph (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group -@group - (print-Y-axis height @dots{} ) - (graph-body-print numbers-list) - (print-X-axis @dots{} ))) -@end group -@end smallexample - -@menu -* The final version:: A few changes. -* Test print-graph:: Run a short test. -* Graphing words in defuns:: Executing the final code. -* lambda:: How to write an anonymous function. -* mapcar:: Apply a function to elements of a list. -* Another Bug:: Yet another bug @dots{} most insidious. -* Final printed graph:: The graph itself! -@end menu - -@ifnottex -@node The final version -@unnumberedsubsec Changes for the Final Version -@end ifnottex - -The final version is different from what we planned in two ways: -first, it contains additional values calculated once in the varlist; -second, it carries an option to specify the labels' increment per row. -This latter feature turns out to be essential; otherwise, a graph may -have more rows than fit on a display or on a sheet of paper. - -@need 1500 -This new feature requires a change to the @code{Y-axis-column} -function, to add @code{vertical-step} to it. The function looks like -this: - -@findex Y-axis-column @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun Y-axis-column - (height width-of-label &optional vertical-step) - "Construct list of labels for Y axis. -HEIGHT is maximum height of graph. -WIDTH-OF-LABEL is maximum width of label. -VERTICAL-STEP, an option, is a positive integer -that specifies how much a Y axis label increments -for each line. For example, a step of 5 means -that each line is five units of the graph." -@end group -@group - (let (Y-axis - (number-per-line (or vertical-step 1))) - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) -@end group -@group - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element - (* height number-per-line) - width-of-label) - Y-axis)) -@end group -@group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) -@end group -@group - ;; @r{Insert base line.} - (setq Y-axis (cons (Y-axis-element - (or vertical-step 1) - width-of-label) - Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -The values for the maximum height of graph and the width of a symbol -are computed by @code{print-graph} in its @code{let} expression; so -@code{graph-body-print} must be changed to accept them. - -@findex graph-body-print @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun graph-body-print (numbers-list height symbol-width) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -HEIGHT is maximum height of graph. -SYMBOL-WIDTH is number of each column." -@end group -@group - (let (from-position) - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n"))) -@end group -@end smallexample - -@need 1250 -Finally, the code for the @code{print-graph} function: - -@findex print-graph @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun print-graph - (numbers-list &optional vertical-step) - "Print labeled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units." -@end group -@group - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length -@end group -@group - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group - -@group - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) -@end group -@group - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list))) -@end group -@end smallexample - -@node Test print-graph -@appendixsubsec Testing @code{print-graph} - -@need 1250 -We can test the @code{print-graph} function with a short list of numbers: - -@enumerate -@item -Install the final versions of @code{Y-axis-column}, -@code{graph-body-print}, and @code{print-graph} (in addition to the -rest of the code.) - -@item -Copy the following expression: - -@smallexample -(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1)) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the test expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -@need 1250 -Emacs will print a graph that looks like this: - -@smallexample -@group -10 - - - - * - ** * - 5 - **** * - **** *** - * ********* - ************ - 1 - ************* - - | | | | - 1 5 10 15 -@end group -@end smallexample - -@need 1200 -On the other hand, if you pass @code{print-graph} a -@code{vertical-step} value of 2, by evaluating this expression: - -@smallexample -(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) -@end smallexample - -@need 1250 -@noindent -The graph looks like this: - -@smallexample -@group -20 - - - - * - ** * -10 - **** * - **** *** - * ********* - ************ - 2 - ************* - - | | | | - 1 5 10 15 -@end group -@end smallexample - -@noindent -(A question: is the `2' on the bottom of the vertical axis a bug or a -feature? If you think it is a bug, and should be a `1' instead, (or -even a `0'), you can modify the sources.) - -@node Graphing words in defuns -@appendixsubsec Graphing Numbers of Words and Symbols - -Now for the graph for which all this code was written: a graph that -shows how many function definitions contain fewer than 10 words and -symbols, how many contain between 10 and 19 words and symbols, how -many contain between 20 and 29 words and symbols, and so on. - -This is a multi-step process. First make sure you have loaded all the -requisite code. - -@need 1500 -It is a good idea to reset the value of @code{top-of-ranges} in case -you have set it to some different value. You can evaluate the -following: - -@smallexample -@group -(setq top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250 - 260 270 280 290 300) -@end group -@end smallexample - -@noindent -Next create a list of the number of words and symbols in each range. - -@need 1500 -@noindent -Evaluate the following: - -@smallexample -@group -(setq list-for-graph - (defuns-per-range - (sort - (recursive-lengths-list-many-files - (directory-files "/usr/local/emacs/lisp" - t ".+el$")) - '<) - top-of-ranges)) -@end group -@end smallexample - -@noindent -On my old machine, this took about an hour. It looked though 303 Lisp -files in my copy of Emacs version 19.23. After all that computing, -the @code{list-for-graph} had this value: - -@smallexample -@group -(537 1027 955 785 594 483 349 292 224 199 166 120 116 99 -90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) -@end group -@end smallexample - -@noindent -This means that my copy of Emacs had 537 function definitions with -fewer than 10 words or symbols in them, 1,027 function definitions -with 10 to 19 words or symbols in them, 955 function definitions with -20 to 29 words or symbols in them, and so on. - -Clearly, just by looking at this list we can see that most function -definitions contain ten to thirty words and symbols. - -Now for printing. We do @emph{not} want to print a graph that is -1,030 lines high @dots{} Instead, we should print a graph that is -fewer than twenty-five lines high. A graph that height can be -displayed on almost any monitor, and easily printed on a sheet of paper. - -This means that each value in @code{list-for-graph} must be reduced to -one-fiftieth its present value. - -Here is a short function to do just that, using two functions we have -not yet seen, @code{mapcar} and @code{lambda}. - -@smallexample -@group -(defun one-fiftieth (full-range) - "Return list, each number one-fiftieth of previous." - (mapcar (lambda (arg) (/ arg 50)) full-range)) -@end group -@end smallexample - -@node lambda -@appendixsubsec A @code{lambda} Expression: Useful Anonymity -@cindex Anonymous function -@findex lambda - -@code{lambda} is the symbol for an anonymous function, a function -without a name. Every time you use an anonymous function, you need to -include its whole body. - -@need 1250 -@noindent -Thus, - -@smallexample -(lambda (arg) (/ arg 50)) -@end smallexample - -@noindent -is a function definition that says `return the value resulting from -dividing whatever is passed to me as @code{arg} by 50'. - -@need 1200 -Earlier, for example, we had a function @code{multiply-by-seven}; it -multiplied its argument by 7. This function is similar, except it -divides its argument by 50; and, it has no name. The anonymous -equivalent of @code{multiply-by-seven} is: - -@smallexample -(lambda (number) (* 7 number)) -@end smallexample - -@noindent -(@xref{defun, , The @code{defun} Macro}.) - -@need 1250 -@noindent -If we want to multiply 3 by 7, we can write: - -@c clear print-postscript-figures -@c lambda example diagram #1 -@ifnottex -@smallexample -@group -(multiply-by-seven 3) - \_______________/ ^ - | | - function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-1} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -(multiply-by-seven 3) - \_______________/ ^ - | | - function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -This expression returns 21. - -@need 1250 -@noindent -Similarly, we can write: - -@c lambda example diagram #2 -@ifnottex -@smallexample -@group -((lambda (number) (* 7 number)) 3) - \____________________________/ ^ - | | - anonymous function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-2} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -((lambda (number) (* 7 number)) 3) - \____________________________/ ^ - | | - anonymous function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@need 1250 -@noindent -If we want to divide 100 by 50, we can write: - -@c lambda example diagram #3 -@ifnottex -@smallexample -@group -((lambda (arg) (/ arg 50)) 100) - \______________________/ \_/ - | | - anonymous function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-3} -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -((lambda (arg) (/ arg 50)) 100) - \______________________/ \_/ - | | - anonymous function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -This expression returns 2. The 100 is passed to the function, which -divides that number by 50. - -@xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs -Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda -expressions derive from the Lambda Calculus. - -@node mapcar -@appendixsubsec The @code{mapcar} Function -@findex mapcar - -@code{mapcar} is a function that calls its first argument with each -element of its second argument, in turn. The second argument must be -a sequence. - -The @samp{map} part of the name comes from the mathematical phrase, -`mapping over a domain', meaning to apply a function to each of the -elements in a domain. The mathematical phrase is based on the -metaphor of a surveyor walking, one step at a time, over an area he is -mapping. And @samp{car}, of course, comes from the Lisp notion of the -first of a list. - -@need 1250 -@noindent -For example, - -@smallexample -@group -(mapcar '1+ '(2 4 6)) - @result{} (3 5 7) -@end group -@end smallexample - -@noindent -The function @code{1+} which adds one to its argument, is executed on -@emph{each} element of the list, and a new list is returned. - -Contrast this with @code{apply}, which applies its first argument to -all the remaining. -(@xref{Readying a Graph, , Readying a Graph}, for a explanation of -@code{apply}.) - -@need 1250 -In the definition of @code{one-fiftieth}, the first argument is the -anonymous function: - -@smallexample -(lambda (arg) (/ arg 50)) -@end smallexample - -@noindent -and the second argument is @code{full-range}, which will be bound to -@code{list-for-graph}. - -@need 1250 -The whole expression looks like this: - -@smallexample -(mapcar (lambda (arg) (/ arg 50)) full-range)) -@end smallexample - -@xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs -Lisp Reference Manual}, for more about @code{mapcar}. - -Using the @code{one-fiftieth} function, we can generate a list in -which each element is one-fiftieth the size of the corresponding -element in @code{list-for-graph}. - -@smallexample -@group -(setq fiftieth-list-for-graph - (one-fiftieth list-for-graph)) -@end group -@end smallexample - -@need 1250 -The resulting list looks like this: - -@smallexample -@group -(10 20 19 15 11 9 6 5 4 3 3 2 2 -1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4) -@end group -@end smallexample - -@noindent -This, we are almost ready to print! (We also notice the loss of -information: many of the higher ranges are 0, meaning that fewer than -50 defuns had that many words or symbols---but not necessarily meaning -that none had that many words or symbols.) - -@node Another Bug -@appendixsubsec Another Bug @dots{} Most Insidious -@cindex Bug, most insidious type -@cindex Insidious type of bug - -I said `almost ready to print'! Of course, there is a bug in the -@code{print-graph} function @dots{} It has a @code{vertical-step} -option, but not a @code{horizontal-step} option. The -@code{top-of-range} scale goes from 10 to 300 by tens. But the -@code{print-graph} function will print only by ones. - -This is a classic example of what some consider the most insidious -type of bug, the bug of omission. This is not the kind of bug you can -find by studying the code, for it is not in the code; it is an omitted -feature. Your best actions are to try your program early and often; -and try to arrange, as much as you can, to write code that is easy to -understand and easy to change. Try to be aware, whenever you can, -that whatever you have written, @emph{will} be rewritten, if not soon, -eventually. A hard maxim to follow. - -It is the @code{print-X-axis-numbered-line} function that needs the -work; and then the @code{print-X-axis} and the @code{print-graph} -functions need to be adapted. Not much needs to be done; there is one -nicety: the numbers ought to line up under the tic marks. This takes -a little thought. - -@need 1250 -Here is the corrected @code{print-X-axis-numbered-line}: - -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces - &optional horizontal-step) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing) - (horizontal-step (or horizontal-step 1))) -@end group -@group - (insert X-axis-leading-spaces) - ;; @r{Delete extra leading spaces.} - (delete-char - (- (1- - (length (number-to-string horizontal-step))))) - (insert (concat - (make-string -@end group -@group - ;; @r{Insert white space.} - (- (* symbol-width - X-axis-label-spacing) - (1- - (length - (number-to-string horizontal-step))) - 2) - ? ) - (number-to-string - (* number horizontal-step)))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element - (* number horizontal-step))) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -@need 1500 -If you are reading this in Info, you can see the new versions of -@code{print-X-axis} @code{print-graph} and evaluate them. If you are -reading this in a printed book, you can see the changed lines here -(the full text is too much to print). - -@iftex -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - @dots{} - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step)) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list - &optional vertical-step horizontal-step) - @dots{} - (print-X-axis numbers-list horizontal-step)) -@end group -@end smallexample -@end iftex - -@ifnottex -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - "Print X axis labels to length of NUMBERS-LIST. -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." -@end group -@group -;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. - (let* ((leading-spaces - (make-string full-Y-label-width ? )) - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group - -@group - (print-X-axis-tic-line - tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step))) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list &optional vertical-step horizontal-step) - "Print labeled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units. -@end group - -@group -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group -@group - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list horizontal-step))) -@end group -@end smallexample -@end ifnottex - -@c qqq -@ignore -Graphing Definitions Re-listed - -@need 1250 -Here are all the graphing definitions in their final form: - -@smallexample -@group -(defvar top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250) - "List specifying ranges for `defuns-per-range'.") -@end group - -@group -(defvar graph-symbol "*" - "String used as symbol in graph, usually an asterisk.") -@end group - -@group -(defvar graph-blank " " - "String used as blank in graph, usually a blank space. -graph-blank must be the same number of columns wide -as graph-symbol.") -@end group - -@group -(defvar Y-axis-tic " - " - "String that follows number in a Y axis label.") -@end group - -@group -(defvar Y-axis-label-spacing 5 - "Number of lines from one Y axis label to next.") -@end group - -@group -(defvar X-axis-tic-symbol "|" - "String to insert to point to a column in X axis.") -@end group - -@group -(defvar X-axis-label-spacing - (if (boundp 'graph-blank) - (* 5 (length graph-blank)) 5) - "Number of units from one X axis label to next.") -@end group -@end smallexample - -@smallexample -@group -(defun count-words-in-defun () - "Return the number of words and symbols in a defun." - (beginning-of-defun) - (let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group - -@group - (while - (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" - end t)) - (setq count (1+ count))) - count)) -@end group -@end smallexample - -@smallexample -@group -(defun lengths-list-file (filename) - "Return list of definitions' lengths within FILE. -The returned list is a list of numbers. -Each number is the number of words or -symbols in one function definition." -@end group - -@group - (message "Working on `%s' ... " filename) - (save-excursion - (let ((buffer (find-file-noselect filename)) - (lengths-list)) - (set-buffer buffer) - (setq buffer-read-only t) - (widen) - (goto-char (point-min)) -@end group - -@group - (while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) - (kill-buffer buffer) - lengths-list))) -@end group -@end smallexample - -@smallexample -@group -(defun lengths-list-many-files (list-of-files) - "Return list of lengths of defuns in LIST-OF-FILES." - (let (lengths-list) -;;; @r{true-or-false-test} - (while list-of-files - (setq lengths-list - (append - lengths-list -@end group -@group -;;; @r{Generate a lengths' list.} - (lengths-list-file - (expand-file-name (car list-of-files))))) -;;; @r{Make files' list shorter.} - (setq list-of-files (cdr list-of-files))) -;;; @r{Return final value of lengths' list.} - lengths-list)) -@end group -@end smallexample - -@smallexample -@group -(defun defuns-per-range (sorted-lengths top-of-ranges) - "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." - (let ((top-of-range (car top-of-ranges)) - (number-within-range 0) - defuns-per-range-list) -@end group - -@group - ;; @r{Outer loop.} - (while top-of-ranges - - ;; @r{Inner loop.} - (while (and - ;; @r{Need number for numeric test.} - (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) - - ;; @r{Count number of definitions within current range.} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) -@end group - -@group - ;; @r{Exit inner loop but remain within outer loop.} - - (setq defuns-per-range-list - (cons number-within-range defuns-per-range-list)) - (setq number-within-range 0) ; @r{Reset count to zero.} - - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges)) - ;; @r{Specify next top of range value.} - (setq top-of-range (car top-of-ranges))) -@end group - -@group - ;; @r{Exit outer loop and count the number of defuns larger than} - ;; @r{ the largest top-of-range value.} - (setq defuns-per-range-list - (cons - (length sorted-lengths) - defuns-per-range-list)) - - ;; @r{Return a list of the number of definitions within each range,} - ;; @r{ smallest to largest.} - (nreverse defuns-per-range-list))) -@end group -@end smallexample - -@smallexample -@group -(defun column-of-graph (max-graph-height actual-height) - "Return list of MAX-GRAPH-HEIGHT strings; -ACTUAL-HEIGHT are graph-symbols. -The graph-symbols are contiguous entries at the end -of the list. -The list will be inserted as one column of a graph. -The strings are either graph-blank or graph-symbol." -@end group - -@group - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) - - ;; @r{Fill in @code{graph-symbols}.} - (while (> actual-height 0) - (setq insert-list (cons graph-symbol insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-blanks}.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons graph-blank insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) - - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -@smallexample -@group -(defun Y-axis-element (number full-Y-label-width) - "Construct a NUMBERed label element. -A numbered element looks like this ` 5 - ', -and is padded as needed so all line up with -the element for the largest number." -@end group -@group - (let* ((leading-spaces - (- full-Y-label-width - (length - (concat (number-to-string number) - Y-axis-tic))))) -@end group -@group - (concat - (make-string leading-spaces ? ) - (number-to-string number) - Y-axis-tic))) -@end group -@end smallexample - -@smallexample -@group -(defun print-Y-axis - (height full-Y-label-width &optional vertical-step) - "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH. -Height must be the maximum height of the graph. -Full width is the width of the highest label element. -Optionally, print according to VERTICAL-STEP." -@end group -@group -;; Value of height and full-Y-label-width -;; are passed by `print-graph'. - (let ((start (point))) - (insert-rectangle - (Y-axis-column height full-Y-label-width vertical-step)) -@end group -@group - ;; @r{Place point ready for inserting graph.} - (goto-char start) - ;; @r{Move point forward by value of} full-Y-label-width - (forward-char full-Y-label-width))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis-tic-line - (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) - "Print ticks for X axis." - (insert X-axis-leading-spaces) - (insert X-axis-tic-symbol) ; @r{Under first column.} -@end group -@group - ;; @r{Insert second tic in the right spot.} - (insert (concat - (make-string - (- (* symbol-width X-axis-label-spacing) - ;; @r{Insert white space up to second tic symbol.} - (* 2 (length X-axis-tic-symbol))) - ? ) - X-axis-tic-symbol)) -@end group -@group - ;; @r{Insert remaining ticks.} - (while (> number-of-X-tics 1) - (insert X-axis-tic-element) - (setq number-of-X-tics (1- number-of-X-tics)))) -@end group -@end smallexample - -@smallexample -@group -(defun X-axis-element (number) - "Construct a numbered X axis element." - (let ((leading-spaces - (- (* symbol-width X-axis-label-spacing) - (length (number-to-string number))))) - (concat (make-string leading-spaces ? ) - (number-to-string number)))) -@end group -@end smallexample - -@smallexample -@group -(defun graph-body-print (numbers-list height symbol-width) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -HEIGHT is maximum height of graph. -SYMBOL-WIDTH is number of each column." -@end group -@group - (let (from-position) - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n"))) -@end group -@end smallexample - -@smallexample -@group -(defun Y-axis-column - (height width-of-label &optional vertical-step) - "Construct list of labels for Y axis. -HEIGHT is maximum height of graph. -WIDTH-OF-LABEL is maximum width of label. -@end group -@group -VERTICAL-STEP, an option, is a positive integer -that specifies how much a Y axis label increments -for each line. For example, a step of 5 means -that each line is five units of the graph." - (let (Y-axis - (number-per-line (or vertical-step 1))) -@end group -@group - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element - (* height number-per-line) - width-of-label) - Y-axis)) -@end group -@group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) -@end group -@group - ;; @r{Insert base line.} - (setq Y-axis (cons (Y-axis-element - (or vertical-step 1) - width-of-label) - Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces - &optional horizontal-step) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing) - (horizontal-step (or horizontal-step 1))) -@end group -@group - (insert X-axis-leading-spaces) - ;; line up number - (delete-char (- (1- (length (number-to-string horizontal-step))))) - (insert (concat - (make-string - ;; @r{Insert white space up to next number.} - (- (* symbol-width X-axis-label-spacing) - (1- (length (number-to-string horizontal-step))) - 2) - ? ) - (number-to-string (* number horizontal-step)))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element (* number horizontal-step))) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - "Print X axis labels to length of NUMBERS-LIST. -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." -@end group -@group -;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. - (let* ((leading-spaces - (make-string full-Y-label-width ? )) - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group - -@group - (print-X-axis-tic-line - tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step))) -@end group -@end smallexample - -@smallexample -@group -(defun one-fiftieth (full-range) - "Return list, each number of which is 1/50th previous." - (mapcar (lambda (arg) (/ arg 50)) full-range)) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list &optional vertical-step horizontal-step) - "Print labeled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units. -@end group - -@group -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group -@group - - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list horizontal-step))) -@end group -@end smallexample -@c qqq -@end ignore - -@page -@node Final printed graph -@appendixsubsec The Printed Graph - -When made and installed, you can call the @code{print-graph} command -like this: -@sp 1 - -@smallexample -@group -(print-graph fiftieth-list-for-graph 50 10) -@end group -@end smallexample -@sp 1 - -@noindent -Here is the graph: -@sp 2 - -@smallexample -@group -1000 - * - ** - ** - ** - ** - 750 - *** - *** - *** - *** - **** - 500 - ***** - ****** - ****** - ****** - ******* - 250 - ******** - ********* * - *********** * - ************* * - 50 - ***************** * * - | | | | | | | | - 10 50 100 150 200 250 300 350 -@end group -@end smallexample - -@sp 2 - -@noindent -The largest group of functions contain 10--19 words and symbols each. - -@node Free Software and Free Manuals -@appendix Free Software and Free Manuals - -@strong{by Richard M. Stallman} -@sp 1 - -The biggest deficiency in free operating systems is not in the -software---it is the lack of good free manuals that we can include in -these systems. Many of our most important programs do not come with -full manuals. Documentation is an essential part of any software -package; when an important free software package does not come with a -free manual, that is a major gap. We have many such gaps today. - -Once upon a time, many years ago, I thought I would learn Perl. I got -a copy of a free manual, but I found it hard to read. When I asked -Perl users about alternatives, they told me that there were better -introductory manuals---but those were not free. - -Why was this? The authors of the good manuals had written them for -O'Reilly Associates, which published them with restrictive terms---no -copying, no modification, source files not available---which exclude -them from the free software community. - -That wasn't the first time this sort of thing has happened, and (to -our community's great loss) it was far from the last. Proprietary -manual publishers have enticed a great many authors to restrict their -manuals since then. Many times I have heard a GNU user eagerly tell me -about a manual that he is writing, with which he expects to help the -GNU project---and then had my hopes dashed, as he proceeded to explain -that he had signed a contract with a publisher that would restrict it -so that we cannot use it. - -Given that writing good English is a rare skill among programmers, we -can ill afford to lose manuals this way. - -Free documentation, like free software, is a matter of freedom, not -price. The problem with these manuals was not that O'Reilly Associates -charged a price for printed copies---that in itself is fine. The Free -Software Foundation @uref{http://shop.fsf.org, sells printed copies} of -free @uref{http://www.gnu.org/doc/doc.html, GNU manuals}, too. -But GNU manuals are available in source code form, while these manuals -are available only on paper. GNU manuals come with permission to copy -and modify; the Perl manuals do not. These restrictions are the -problems. - -The criterion for a free manual is pretty much the same as for free -software: it is a matter of giving all users certain -freedoms. Redistribution (including commercial redistribution) must be -permitted, so that the manual can accompany every copy of the program, -on-line or on paper. Permission for modification is crucial too. - -As a general rule, I don't believe that it is essential for people to -have permission to modify all sorts of articles and books. The issues -for writings are not necessarily the same as those for software. For -example, I don't think you or I are obliged to give permission to -modify articles like this one, which describe our actions and our -views. - -But there is a particular reason why the freedom to modify is crucial -for documentation for free software. When people exercise their right -to modify the software, and add or change its features, if they are -conscientious they will change the manual too---so they can provide -accurate and usable documentation with the modified program. A manual -which forbids programmers to be conscientious and finish the job, or -more precisely requires them to write a new manual from scratch if -they change the program, does not fill our community's needs. - -While a blanket prohibition on modification is unacceptable, some -kinds of limits on the method of modification pose no problem. For -example, requirements to preserve the original author's copyright -notice, the distribution terms, or the list of authors, are ok. It is -also no problem to require modified versions to include notice that -they were modified, even to have entire sections that may not be -deleted or changed, as long as these sections deal with nontechnical -topics. (Some GNU manuals have them.) - -These kinds of restrictions are not a problem because, as a practical -matter, they don't stop the conscientious programmer from adapting the -manual to fit the modified program. In other words, they don't block -the free software community from making full use of the manual. - -However, it must be possible to modify all the technical content of -the manual, and then distribute the result in all the usual media, -through all the usual channels; otherwise, the restrictions do block -the community, the manual is not free, and so we need another manual. - -Unfortunately, it is often hard to find someone to write another -manual when a proprietary manual exists. The obstacle is that many -users think that a proprietary manual is good enough---so they don't -see the need to write a free manual. They do not see that the free -operating system has a gap that needs filling. - -Why do users think that proprietary manuals are good enough? Some have -not considered the issue. I hope this article will do something to -change that. - -Other users consider proprietary manuals acceptable for the same -reason so many people consider proprietary software acceptable: they -judge in purely practical terms, not using freedom as a -criterion. These people are entitled to their opinions, but since -those opinions spring from values which do not include freedom, they -are no guide for those of us who do value freedom. - -Please spread the word about this issue. We continue to lose manuals -to proprietary publishing. If we spread the word that proprietary -manuals are not sufficient, perhaps the next person who wants to help -GNU by writing documentation will realize, before it is too late, that -he must above all make it free. - -We can also encourage commercial publishers to sell free, copylefted -manuals instead of proprietary ones. One way you can help this is to -check the distribution terms of a manual before you buy it, and prefer -copylefted manuals to non-copylefted ones. - -@sp 2 -@noindent -Note: The Free Software Foundation maintains a page on its Web site -that lists free books available from other publishers:@* -@uref{http://www.gnu.org/doc/other-free-books.html} - -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@cindex FDL, GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index - -@ignore -MENU ENTRY: NODE NAME. -@end ignore - -@printindex cp - -@iftex -@c Place biographical information on right-hand (verso) page - -@tex -\par\vfill\supereject -\ifodd\pageno - \global\evenheadline={\hfil} \global\evenfootline={\hfil} - \global\oddheadline={\hfil} \global\oddfootline={\hfil} - %\page\hbox{}\page -\else -% \par\vfill\supereject - \global\evenheadline={\hfil} \global\evenfootline={\hfil} - \global\oddheadline={\hfil} \global\oddfootline={\hfil} - %\page\hbox{}%\page - %\page\hbox{}%\page -\fi -@end tex - -@c page -@w{ } - -@c ================ Biographical information ================ - -@w{ } -@sp 8 -@center About the Author -@sp 1 -@end iftex - -@ifnottex -@node About the Author -@unnumbered About the Author -@end ifnottex - -@quotation -Robert J. Chassell has worked with GNU Emacs since 1985. He writes -and edits, teaches Emacs and Emacs Lisp, and speaks throughout the -world on software freedom. Chassell was a founding Director and -Treasurer of the Free Software Foundation, Inc. He is co-author of -the @cite{Texinfo} manual, and has edited more than a dozen other -books. He graduated from Cambridge University, in England. He has an -abiding interest in social and economic history and flies his own -airplane. -@end quotation - -@c @page -@c @w{ } -@c -@c @c Prevent page number on blank verso, so eject it first. -@c @tex -@c \par\vfill\supereject -@c @end tex - -@c @iftex -@c @headings off -@c @evenheading @thispage @| @| @thistitle -@c @oddheading @| @| @thispage -@c @end iftex - -@bye diff --git a/doc/lispintro/lambda-1.eps b/doc/lispintro/lambda-1.eps deleted file mode 100644 index 62025bd7018..00000000000 --- a/doc/lispintro/lambda-1.eps +++ /dev/null @@ -1,465 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 33 710 173 759 -%%Title: lambda-diagram1 -%%CreationDate: Wed Mar 8 14:31:53 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2014 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 33 710 173 759 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 63 75 moveto (\(multiply-by-seven 3\)) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 80 80 moveto - 96 96 lineto - 224 96 lineto - 240 80 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 264 119 moveto - -22 0 atan dup cos 8 mul 264 exch sub - exch sin 8 mul 97 exch sub lineto - stroke -grestore -gsave - newpath - 264 97 8 3 0 -22 tgifarrowtip - closepath fill -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 160 103 moveto - 160 119 lineto - stroke -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 112 139 moveto (function) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 224 139 moveto (argument) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:31:53 1995 diff --git a/doc/lispintro/lambda-1.pdf b/doc/lispintro/lambda-1.pdf deleted file mode 100644 index 158d6fd2276..00000000000 --- a/doc/lispintro/lambda-1.pdf +++ /dev/null @@ -1,69 +0,0 @@ -%PDF-1.3 -%Ç쏢 -5 0 obj -<> -stream -xœ•PMkÃ0 ½ëWè˜âYr<;×ÁvèæۺҐg횴ôßÏÎGéu!KïéI¼#JA(ã[réááÍ`s‰/!8M\RéñÉ’ÅBèGÖèj˜g YäÊhT…°É.ñc7´‡îš}_³Su®zT»4u{xv°-¢Æ%H¼†hX¢2=pXÈVb…Z$¸ƒw ÒIËIÁÏ%s!â 7œM>5"nHX{G!RVßujÐAœóU3Vë†(ù3ÂÑêæÃGR}9´?}š‘±Vpž|ý6£¯ú!ýt›ÙŒ-üxuVendstream -endobj -6 0 obj -236 -endobj -4 0 obj -<> -/Contents 5 0 R ->> -endobj -3 0 obj -<< /Type /Pages /Kids [ -4 0 R -] /Count 1 ->> -endobj -1 0 obj -<> -endobj -7 0 obj -<>endobj -9 0 obj -<> -endobj -10 0 obj -<> -endobj -8 0 obj -<> -endobj -2 0 obj -<>endobj -xref -0 11 -0000000000 65535 f -0000000548 00000 n -0000000758 00000 n -0000000489 00000 n -0000000340 00000 n -0000000015 00000 n -0000000321 00000 n -0000000596 00000 n -0000000696 00000 n -0000000637 00000 n -0000000666 00000 n -trailer -<< /Size 11 /Root 1 0 R /Info 2 0 R -/ID [(4Ðä@7‡måèbW9¨Áë)(4Ðä@7‡måèbW9¨Áë)] ->> -startxref -869 -%%EOF diff --git a/doc/lispintro/lambda-2.eps b/doc/lispintro/lambda-2.eps deleted file mode 100644 index c4c2b90a962..00000000000 --- a/doc/lispintro/lambda-2.eps +++ /dev/null @@ -1,465 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 33 730 240 777 -%%Title: lambda-diagram2 -%%CreationDate: Wed Mar 8 14:33:09 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) - -% Copyright (C) 1995, 1997, 2001-2014 Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 33 730 240 777 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 63 43 moveto (\(\(lambda \(number\) \(* 7 number\)\) 3\)) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 80 48 moveto - 96 64 lineto - 336 64 lineto - 353 49 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 395 85 moveto - -21 0 atan dup cos 8 mul 395 exch sub - exch sin 8 mul 64 exch sub lineto - stroke -grestore -gsave - newpath - 395 64 8 3 0 -21 tgifarrowtip - closepath fill -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 208 69 moveto - 208 85 lineto - stroke -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 112 102 moveto (anonymous function) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 344 102 moveto (argument) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:33:09 1995 diff --git a/doc/lispintro/lambda-2.pdf b/doc/lispintro/lambda-2.pdf deleted file mode 100644 index 33f3e0d25a07f285453146ff93e750d2508988a1..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1225 zcmZuxOH30{6!jB-FStNK7lJ-NjS!A=iuQdqb# z#vlGQl2{g^ZVZXV1S1imMk7`OabXCWs6-RgNR$|KA^zSgrPa!8X5P8?o_Fs#H=}b| z?d!P>2B7O3J=qR;$U>!NAK0{s*^WX1yce1XA~JS4h>;2zdr-p2ihPP6Su8-qDw66! zBzoTEsJqW*^?uy_zBOya^XqWi$Lg%P8}XC+=PMl-pJs0yU)}O^BJNl`)Hwgr+7BP% zgV|T%xp=5^;n>(nZ1aH!fp5!CY}q~QRq3*^&YClQ;!vrlqqsG&;5_@n^K3_CTiXmz zzsV@wu8R%4$+Y0IQmxiyQ6C4VsLor=}%Q9DCAG7 zK)$GQR4@A0^LmhkjA>DKH8mi{B?S=UKz>;&RU**KlCYjNL!-G8keG@>7#gVRfDw_V zgjFBXh#xLh@wpN9GQ=^+>_QPt(rpo3?#9FuSTtE-S4cHSDMdgWV#>&w5NeP*n}Cu{ z(Hkb6CS;^5m}pCbOoi;%pcl}lMNkO|Lzq%hwqz-nDos|FNmvRhfhmf~=F|D+fAiB# z1IFocK+a-G64M!y+b5a_cjS&FzBadle09K2>hOP~i9ttiF&)N|qkWO2|rNFR&KtS+FS)kP#JyEEDw( zGFwBn3Z&ALP2XyT-h#Ko;miGIy!1r0k)Pe=tS. - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 33 728 211 777 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 63 43 moveto (\(\(lambda \(arg\) \(/ arg 50\)\) 100\)) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 80 48 moveto - 96 64 lineto - 284 64 lineto - 299 48 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 354 86 moveto - -25 0 atan dup cos 8 mul 354 exch sub - exch sin 8 mul 61 exch sub lineto - stroke -grestore -gsave - newpath - 354 61 8 3 0 -25 tgifarrowtip - closepath fill -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 199 70 moveto - 199 86 lineto - stroke -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 101 106 moveto (anonymous function) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 293 106 moveto (argument) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:33:49 1995 diff --git a/doc/lispintro/lambda-3.pdf b/doc/lispintro/lambda-3.pdf deleted file mode 100644 index 6b54c9440ab..00000000000 --- a/doc/lispintro/lambda-3.pdf +++ /dev/null @@ -1,69 +0,0 @@ -%PDF-1.3 -%Ç쏢 -5 0 obj -<> -stream -xœ•PMO„0½Ï¯˜ãrp¶Ó/ÊÕʘxXå&…¬¡u—ÿ½S` WÓL^çõõuúN¨ˆQ¥µbaÿ”cw…÷Rœ€g®ÐD¼-E° çµÃ²…å.£&kr‡¦ Àé$®’Õ×ñí½ÆjWuU&¸GÙ¡SU&-+Á¬ü„»à(y~‹å£ÔX+4¹ÂZÐAa/œÏÉ]ã˜B˜E=<{Ï$ì|‚øG褓é¶"]ø™Kª<덊½µd†i!¥j»š_‰õµäý¯À̒”M$¯—]=ŒÃO§3¶ÓÐ\ŽãÝØÂsHùMñc¸d¯åÃ×~B©ašendstream -endobj -6 0 obj -258 -endobj -4 0 obj -<> -/Contents 5 0 R ->> -endobj -3 0 obj -<< /Type /Pages /Kids [ -4 0 R -] /Count 1 ->> -endobj -1 0 obj -<> -endobj -7 0 obj -<>endobj -9 0 obj -<> -endobj -10 0 obj -<> -endobj -8 0 obj -<> -endobj -2 0 obj -<>endobj -xref -0 11 -0000000000 65535 f -0000000570 00000 n -0000000780 00000 n -0000000511 00000 n -0000000362 00000 n -0000000015 00000 n -0000000343 00000 n -0000000618 00000 n -0000000718 00000 n -0000000659 00000 n -0000000688 00000 n -trailer -<< /Size 11 /Root 1 0 R /Info 2 0 R -/ID [(ß vFÙ ¶y¹¤l%t­)(ß vFÙ ¶y¹¤l%t­)] ->> -startxref -891 -%%EOF diff --git a/doc/lispintro/makefile.w32-in b/doc/lispintro/makefile.w32-in deleted file mode 100644 index 1767825dfea..00000000000 --- a/doc/lispintro/makefile.w32-in +++ /dev/null @@ -1,85 +0,0 @@ -#### -*- Makefile -*- for the Emacs Lisp Introduction manual. - -# Copyright (C) 2003-2014 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -srcdir = . - -infodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs - -INFO_EXT=.info -INFO_OPTS=--no-split -I$(emacsdir) -INFO_SOURCES = $(srcdir)/emacs-lisp-intro.texi $(emacsdir)/emacsver.texi \ - $(srcdir)/doclicense.texi -# The file name eintr must fit within 5 characters, to allow for -# -NN extensions to fit into DOS 8+3 limits without clashing -INFO_TARGETS = $(infodir)/eintr$(INFO_EXT) -DVI_TARGETS = emacs-lisp-intro.dvi - -MAKEINFO = makeinfo -INSTALL_INFO = install-info -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips -ENVADD = $(srcdir)\..\..\nt\envadd.bat \ - "TEXINPUTS=$(srcdir);$(texinfodir);$(emacsdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) -I$(srcdir) -I$(emacsdir) -I$(texinfodir)" /C - -.SUFFIXES: .dvi .ps .texi - -info: $(INFO_TARGETS) - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -$(infodir)/eintr$(INFO_EXT): $(INFO_SOURCES) - $(MAKEINFO) $(INFO_OPTS) -o $@ $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.dvi: $(INFO_SOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.pdf: $(INFO_SOURCES) - $(ENVADD) $(TEXI2PDF) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.html: $(INFO_SOURCES) - $(MAKEINFO) --html -o $@ $(srcdir)/emacs-lisp-intro.texi - -.dvi.ps: - $(DVIPS) $< -o $@ - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr *.tp - -clean: mostlyclean - - $(DEL) *.dvi $(infodir)/eintr$(INFO_EXT)* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc - -# Tell versions [3.59,3.63) of GNU make to not export all variables. -# Otherwise a system limit (for SysV at least) may be exceeded. -.NOEXPORT: diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog deleted file mode 100644 index f72e1054c5f..00000000000 --- a/doc/lispref/ChangeLog +++ /dev/null @@ -1,13388 +0,0 @@ -2014-10-20 Glenn Morris - - * Version 24.4 released. - -2014-10-13 Glenn Morris - - * Makefile.in (dist): Update for new output variables. - -2014-10-09 Glenn Morris - - * elisp.texi (DATE): Bump to October 2014. - - * frames.texi (Multiple Terminals): Copyedits. - -2014-10-08 Eli Zaretskii - - * frames.texi (Multiple Terminals): Improve the description of X - display names. Add index entries. - (Basic Parameters): Add a cross-reference to where X display names - are described. - (Position Parameters): Mention that positional parameters of the - form (+ POS) can be negative if they are on a non-primary monitor - of a multi-monitor display. (Bug#18636) - (Creating Frames): Mention that on multi-monitor displays the - frame might be positioned differently than specified by the frame - parameters alist. - -2014-10-04 Glenn Morris - - * commands.texi (Generic Commands): Copyedits. - - * display.texi (Scroll Bars): - * modes.texi (Header Lines): Copyedits. - - * buffers.texi (Buffer List): - * display.texi (Image Descriptors, Defining Images): - * functions.texi (Core Advising Primitives): Small fixes re @var usage. - - * windows.texi (Window Sizes, Resizing Windows): Copyedits. - - * frames.texi (Multiple Terminals): Copyedits re multiple monitors. - -2014-10-03 Martin Rudalics - - * frames.texi (Size Parameters, Size and Position): Mention that - with some window managers you have to set - `frame-resize-pixelwise' in order make a frame truly fullscreen - or maximized. - -2014-09-04 Stefan Monnier - - * functions.texi (Core Advising Primitives): Add a note about the - confusing treatment of `interactive' for :filter-args (bug#18399). - -2014-08-19 Eli Zaretskii - - * display.texi (Bidirectional Display): Update the Emacs's class - of bidirectional conformance. - -2014-07-08 Stefan Monnier - - * debugging.texi (Function Debugging, Debugger Commands): - Update debug-on-entry w.r.t behavior after redefinitions (bug#17902). - -2014-06-29 Glenn Morris - - * help.texi (Help Functions): "Online" help doesn't mean what it - used to any more. - -2014-06-26 Glenn Morris - - * minibuf.texi (Intro to Minibuffers): Batch mode is basic. - (Reading a Password): Mention batch mode. (Bug#17839) - -2014-06-21 Eli Zaretskii - - * positions.texi (Screen Lines): Clarify how columns are counted - by vertical-motion. - -2014-06-14 Eli Zaretskii - - * commands.texi (Accessing Mouse): Improve the wording of the - posn-col-row documentation. (Bug#17768) - -2014-06-08 Glenn Morris - - * os.texi (Startup Summary): Small fix for initial-buffer-choice. - - * files.texi (Subroutines of Visiting): Mention uniquify. - - * numbers.texi (Comparison of Numbers): Copyedits. - -2014-06-06 Glenn Morris - - * display.texi (Window Systems): Remove window-setup-hook. - * os.texi (Startup Summary, Init File): - Improve description of window-setup-hook. - (Terminal-Specific): Update window-setup-hook cross-reference. - * hooks.texi (Standard Hooks): Update window-setup-hook cross-reference. - - * display.texi (Overlay Properties): Update re priority. (Bug#17234) - -2014-06-05 Glenn Morris - - * package.texi (Package Archives): Mention signing packages. - -2014-05-27 Glenn Morris - - * text.texi (Buffer Contents): - Update for filter-buffer-substring changes. - - * abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes. - * functions.texi (Advising Functions): Standardize menu case. - -2014-05-17 Eli Zaretskii - - * display.texi (Invisible Text): Clarify the description of - line-move-ignore-invisible. (Bug#17511) - -2014-05-07 Paul Eggert - - * internals.texi (C Dialect): New section. - (C Integer Types): Mention bool_bf. - -2014-04-29 Stefan Monnier - - * processes.texi (Filter Functions, Sentinels): Advertise add-function. - -2014-04-24 Eli Zaretskii - - * strings.texi (Text Comparison): Mention equal-including-properties - for when text properties of the strings matter for comparison. - -2014-04-21 Eli Zaretskii - - * text.texi (Registers): Document register-read-with-preview. - - * internals.texi (Building Emacs): Improve indexing. - -2014-04-15 Stefan Monnier - - * display.texi (Overlay Properties): Reword the doc of `priority'. - (Finding Overlays): Document new arg of `overlays-at'. - -2014-04-05 Glenn Morris - - * os.texi (Recording Input): Dribble files may contain passwords. - -2014-04-04 Glenn Morris - - * backups.texi (Making Backups, Reverting): - Update for default values of some -function vars no longer being nil. - (Reverting): Update for buffer-stale-function - also applying to file-buffers. - -2014-03-25 Eli Zaretskii - - * files.texi (Kinds of Files): Improve documentation of - file-symlink-p. (Bug#17073) Add cross-references. - -2014-03-24 Barry O'Reilly - - * markers.texi (Moving Marker Positions): The 2014-03-02 doc - change mentioning undo's inability to handle relocated markers no - longer applies. See bug#16818. - * text.texi (Undo): Expand documentation of (TEXT . POS) and - (MARKER . ADJUSTMENT) undo elements. - -2014-03-22 Glenn Morris - - * commands.texi (Defining Commands): List interactive-only values. - -2014-03-22 Eli Zaretskii - - * functions.texi (Core Advising Primitives): Fix cross-reference - in last change. - -2014-03-21 Stefan Monnier - - * functions.texi (Advising Functions): Explain a bit more how - arguments work. - (Advice combinators): New node. - (Core Advising Primitives): Use it. Expand description of "depth". - (Advising Named Functions): Document limitation of advices on macros. - -2014-03-21 Martin Rudalics - - * frames.texi (Size and Position): In `frame-resize-pixelwise' - description drop remark about frame maximization. - * windows.texi (Display Action Functions): Add description for - `display-buffer-no-window' and explain use of `allow-no-window' - alist entries. - -2014-03-21 Glenn Morris - - * commands.texi (Defining Commands): Copyedit re `interactive-only'. - -2014-03-20 Paul Eggert - - * internals.texi (C Integer Types): Prefer 'false' and 'true' - to '0' and '1' for booleans. - -2014-03-19 Paul Eggert - - * numbers.texi: Improve and clarify a bit, and fix some minor bugs. - Remove now-obsolete hypothetical note about negative division, - as the C standard has changed. - - Fix porting inconsistency about rounding to even. - * numbers.texi (Numeric Conversions, Rounding Operations): - Document that 'round' and 'fround' round to even. - -2014-03-18 Juanma Barranquero - - * customize.texi (Variable Definitions): Recommend avoiding - destructive modification of the value argument of :set (bug#16755). - -2014-03-18 Stefan Monnier - - * modes.texi (Auto-Indentation): Mention electric-indent variables. - -2014-03-18 Juanma Barranquero - - * functions.texi (Advising Named Functions): Fix reference. - -2014-03-18 Paul Eggert - - Improve documentation for integer and floating-point basics. - * numbers.texi (Numbers, Integer Basics, Float Basics): - Document the basics a bit more precisely. Say more clearly - that Emacs floating-point numbers are IEEE doubles on all - current platforms. Give more details about frexp. - Say more clearly that '1.' is an integer. - (Predicates on Numbers): Fix wholenump typo. - * objects.texi (Integer Type): Adjust to match numbers.texi. - -2014-03-18 Stefan Monnier - - * functions.texi (Advising Functions): Try and improve the text. - Add example use of advice-add (bug#16959). - (Core Advising Primitives): Rename. Explain handling of interactive - specs, including advice-eval-interactive-spec. - (Advising Named Functions): Try and better explain the difference with - add-function. - (Porting old advices): New node. - -2014-03-18 Paul Eggert - - Style fixes for floating-point doc. - * commands.texi, customize.texi, display.texi, elisp.texi, files.texi: - * frames.texi, hash.texi, internals.texi, keymaps.texi, lists.texi: - * minibuf.texi, nonascii.texi, numbers.texi, objects.texi, os.texi: - * processes.texi, streams.texi, strings.texi, text.texi: - * variables.texi, windows.texi: - Hyphenate "floating-point" iff it precedes a noun. - Reword to avoid nouns and hyphenation when that's easy. - Prefer "integer" to "integer number" and "is floating point" - to "is a floating point number". - Prefer "@minus{}" to "-" when it's a minus. - -2014-03-16 Martin Rudalics - - * display.texi (Temporary Displays): Rewrite descriptions of - `with-output-to-temp-buffer' and `with-temp-buffer-window'. - * help.texi (Help Functions): Rewrite description of `with-help-window'. - -2014-03-15 Dmitry Gutov - - * display.texi (Blinking): Update WRT to the new - `blink-matchin-paren' behavior. - -2014-03-14 Martin Rudalics - - * display.texi (Temporary Displays): Say that - `with-temp-buffer-window' makes its buffer current. - * frames.texi (Size and Position): Describe new option - `frame-resize-pixelwise'. Rewrite descriptions of - `set-frame-size', `set-frame-height' and `set-frame-width'. - -2014-03-09 Martin Rudalics - - * elisp.texi (Top): Rename section "Width" to "Size of Displayed Text". - * text.texi (Primitive Indent): - * strings.texi (String Basics): - * sequences.texi (Sequence Functions): Update references accordingly. - * display.texi (Size of Displayed Text): Rename section from - "Width". Add description for `window-text-pixel-size'. - (Window Dividers): Reword description of window dividers. - * frames.texi (Layout Parameters): Improve description of window - divider parameters. - * windows.texi (Window Sizes): Add descriptions of - `window-mode-line-height' and `window-header-line-height'. - (Coordinates and Windows): Mention window dividers. - -2014-03-07 Martin Rudalics - - * buffers.texi (The Buffer List): Rename node to Buffer List. - Describe `buffer-list-update-hook'. - * elisp.texi (Top): "The Buffer List" renamed to "Buffer List". - Add node for Window Dividers. - * hooks.texi (Standard Hooks): Add reference to - `buffer-list-update-hook'. - * windows.texi (Window Sizes): Describe `window-min-size'. - (Splitting Windows): Update description of `split-window'. - (Selecting Windows): Update description of `select-window'. - -2014-03-06 Martin Rudalics - - * frames.texi (Size and Position): Rewrite entries for - `fit-frame-to-buffer' and `fit-frame-to-buffer-margins'. - Add description for `fit-frame-to-buffer-sizes'. - * windows.texi (Resizing Windows): Add descriptions for - pixelwise resizing. Add entries for `window-resize-pixelwise' - and `fit-window-to-buffer-horizontally'. - Rewrite `fit-window-to-buffer' entry. - -2014-03-06 Xue Fuqiao - - * internals.texi (Window Internals): Remove field `region_showing'. - -2014-03-06 Glenn Morris - - * searching.texi (Replacing Match): - Remove incorrect, uninteresting return value. (Bug#16942) - -2014-03-05 Martin Rudalics - - * display.texi (Window Dividers): New section. - * frames.texi (Layout Parameters): Add right-divider-width and - bottom-divider-width. - * windows.texi (Window Sizes): Redraw schematic and rewrite its - description. Rewrite descriptions of `window-total-height', - `window-total-width', `window-total-size', `window-body-height', - `window-body-width' and `window-size-fixed'. Add descriptions - for `window-pixel-height', `window-pixel-width', - `window-min-height' and `window-min-width'. Remove description - of `window-size-fixed-p' moving part of it to that of - `window-size-fixed'. - (Resizing Windows): Mention dividers when talking about minimum sizes. - -2014-03-05 Glenn Morris - - * modes.texi (SMIE Customization): New section. - * elisp.texi (Top): Update detailed menu. - -2014-03-04 Martin Rudalics - - * windows.texi (Windows and Frames): Add some missing &optional - designators. Adjust description of window-in-direction. - -2014-03-02 Barry O'Reilly - - * markers.texi (Moving Marker Positions): Clarify guidance about - when to move markers and when to create a new one, as discussed at - http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16818#17 - -2014-03-02 Glenn Morris - - * text.texi (Decompression): New node. - * elisp.texi (Top): Update detailed menu. - -2014-03-01 Glenn Morris - - * display.texi (Forcing Redisplay): Mention pre-redisplay-function. - -2014-02-28 Xue Fuqiao - - * functions.texi (Advising Functions, Advising Named Functions): - Tweak markup. - - * display.texi (Defining Faces): Doc fix for `face-spec-set'. - - * elisp.texi (Top): - * commands.texi (Generic Commands, Defining Commands): - Document `define-alternatives'. - -2014-02-27 Xue Fuqiao - - * windows.texi (Window Sizes): Document `window-size'. - (Display Action Functions): Document `display-buffer-at-bottom'. - (Window Configurations): Minor fixes. - - * modes.texi (Header Lines): Document `window-header-line-height'. - - * display.texi (Scroll Bars): Document `window-scroll-bar-width'. - - * windows.texi (Window Sizes, Resizing Windows): Document some - pixelwise window operations. - - * text.texi (Margins): Fix the description of RET and `C-j'. - - * frames.texi (Multiple Terminals): Document - `display-monitor-attributes-list' and `display-monitor-attributes'. - (Display Feature Testing): Add some notes about multi-monitor. - -2014-02-27 Glenn Morris - - * minibuf.texi (Programmed Completion): - Mention completion-table-with-cache. - -2014-02-25 Glenn Morris - - * display.texi (Window Systems): - Replace term-setup-hook with emacs-startup-hook. - * hooks.texi (Standard Hooks): - Replace term-setup-hook with tty-setup-hook. - * os.texi (Startup Summary, Init File, Terminal-Specific): - Replace term-setup-hook with tty-setup-hook, and update. - -2014-02-22 Stefan Monnier - - * functions.texi (Declare Form): Document gv-expander, gv-setter, - and compiler-macro (bug#16829, bug#15093). - -2014-02-21 Juanma Barranquero - - * windows.texi (Window Configurations): Doc fix. - (Windows and Frames): Fix typo. - -2014-02-21 Glenn Morris - - * internals.texi (Process Internals): - * processes.texi (Subprocess Creation, Deleting Processes) - (Output from Processes, Process Buffers, Filter Functions) - (Accepting Output, Sentinels, Network, Network Servers): - Filters and sentinels can no longer be nil. - * elisp.texi (Top): Menu update. - -2014-02-20 Glenn Morris - - * functions.texi (Defining Functions): Mention defalias-fset-function. - -2014-02-17 Stefan Monnier - - * minibuf.texi (Completion Commands): Don't document obsolete - `common-substring' arg of display-completion-list. - -2014-02-17 Glenn Morris - - * minibuf.texi (Text from Minibuffer): Update read-regexp details. - Mention read-regexp-defaults-function. - -2014-02-13 Glenn Morris - - * debugging.texi (Debugger Commands): Tiny edits. - -2014-02-12 Glenn Morris - - * package.texi (Simple Packages): Describe URL and Keywords headers. - -2014-02-10 Lars Ingebrigtsen - - * text.texi (User-Level Deletion): - Document `delete-trailing-whitespace' (bug#15309). - -2014-02-09 Lars Ingebrigtsen - - * text.texi (Changing Properties): Clarify `propertize' (bug#9825). - - * display.texi (Blinking): Clarify doc string in example (bug#10658). - - * commands.texi (Accessing Mouse): Mention that these function - also work on keyboard events (bug#14228). - (Quitting): Refer to the right node for `set-input-mode' (bug#11458). - -2014-02-08 Lars Ingebrigtsen - - * display.texi (Face Attributes): Add an index (bug#14924). - - * keymaps.texi (Menu Bar): Minor clarification (bug#15657). - -2014-02-06 Glenn Morris - - * display.texi (Truncation): - * positions.texi (Screen Lines): Do not mention cache-long-scans. - -2014-01-31 Juri Linkov - - * searching.texi (String Search): Incremental word search fixes. - -2014-01-28 Glenn Morris - - * text.texi (Indent Tabs): Update related to tab-stops. - -2014-01-24 Glenn Morris - - * control.texi (Handling Errors): Update with-demoted-errors. - - * files.texi (File Locks): Every platform supports locking now. - -2014-01-22 Glenn Morris - - * display.texi (ImageMagick Images): Expand on image-format-suffixes. - -2014-01-20 Glenn Morris - - * hash.texi (Other Hash): Do not mention subr-x.el functions; - reverts 2013-12-22 change. - -2014-01-10 Stefan Monnier - - * functions.texi (Advising Functions): New section. - * modes.texi (Running Hooks): Don't document with-wrapper-hook and - run-hook-wrapped any more. - (Hooks): Link to the new Advising Functions node. - * elisp.texi (Top): Don't include advice.texi. - * advice.texi: Remove. - * makefile.w32-in (srcs): - * Makefile.in (srcs): Adjust accordingly. - -2014-01-09 Rüdiger Sonderfeld - - * text.texi (Parsing HTML/XML): Document `shr-insert-document'. - - * strings.texi (Text Comparison): Document `string-suffix-p'. - -2014-01-07 Glenn Morris - - * files.texi (File Attributes): Fix superscipt typo. - -2014-01-07 Chong Yidong - - * files.texi (Changing Files): Document copy-file changes. - -2014-01-07 Glenn Morris - - * display.texi (Logging Messages): Copyedits re messages-buffer. - -2014-01-06 Paul Eggert - - Specify .texi encoding (Bug#16292). - * back.texi, book-spine.texi, lay-flat.texi: - Add @documentencoding. - -2014-01-05 Chong Yidong - - * backups.texi (Making Backups): Document backup-buffer change. - - * files.texi (Visiting Files): Copyedits. - (Testing Accessibility): Mention ACLs. Move file-modes here from - File Attributes. - (Truenames): Move file-equal-p here from Kinds of Files. - (File Attributes): Move file-newer-than-file-p here from Testing - Accessibility. - (Extended Attributes): New node. Add file-extended-attributes. - (Changing Files): Document set-file-extended-attributes. - - * commands.texi (Defining Commands): Document the interactive-form - property more carefully. Document interactive-only. - - * compile.texi (Compiler Errors): Copyedits. Note that the - details for byte-compile-warnings are in its docstring. - - * minibuf.texi (Minibuffer Contents): Remove obsolete function - minibuffer-completion-contents. - - * variables.texi (Defining Variables): Note that defvar acts - always on the dynamic value. - - * customize.texi (Variable Definitions): Likewise. - -2014-01-05 Paul Eggert - - Document vconcat and the empty vector (Bug#16246). - * sequences.texi (Vector Functions): - Document behavior better when the result is empty. - - Document behavior of (string-to-number "+@") (Bug#16293). - * strings.texi (String Conversion): Document behavior of - string-to-number on invalid strings that begin with "+", too. - -2014-01-03 Chong Yidong - - * help.texi (Documentation, Accessing Documentation): Copyedits. - (Documentation Basics): Rewrite, avoiding a repeat discussion of - docstring conventions. - - * tips.texi (Documentation Tips): Move discussion of - emacs-lisp-docstring-fill-column here from Documentation Basics. - - * compile.texi (Docs and Compilation): Copyedits. - -2014-01-02 Glenn Morris - - * numbers.texi (Numeric Conversions): Fix a typo. - -2013-12-29 Paul Eggert - - Plain copy-file no longer chmods an existing destination (Bug#16133). - * files.texi (Changing Files): Document this. - -2013-12-28 Chong Yidong - - * modes.texi (Auto Major Mode): Document interpreter-mode-alist change. - - * buffers.texi (Modification Time): Document visited-file-modtime - change. - -2013-12-28 Glenn Morris - - * control.texi (Pattern matching case statement): Brevity. - -2013-12-27 Chong Yidong - - * functions.texi (Function Cells): - * eval.texi (Function Indirection): Update for the fact that - symbol-function no longer signals an error. - - * commands.texi (Reading One Event): Mention keyboard coding. - - * keymaps.texi (Translation Keymaps, Translation Keymaps): - * nonascii.texi (Terminal I/O Encoding): Copyedits. - -2013-12-26 Chong Yidong - - * advice.texi (Advising Functions, Defining Advice): Special forms - can no longer be advised. - -2013-12-25 Chong Yidong - - * keymaps.texi (Active Keymaps): Re-organize the text. - (Searching Keymaps): Rewrite the pseudo-code for 24.4 changes. - (Controlling Active Maps): Note that set-transient-map uses - overriding-terminal-local-map. - - * tips.texi (Coding Conventions): Tweak the coding system tip; - Emacs now uses utf-8 by default for Emacs Lisp source files. - - * display.texi (Font Selection): Tweak example. - - * commands.texi (Event Input Misc): Document new arg to input-pending-p. - - * nonascii.texi (Specifying Coding Systems): Don't refer to - emacs-mule-dos. - (Lisp and Coding Systems): Describe emacs-mule return value in - modern terms. - -2013-12-25 Tassilo Horn - - * control.texi (Pattern matching case statement): Rephrase lexical - binding requirement: the example needs it, not `pcase' itself. - -2013-12-25 Chong Yidong - - * eval.texi (Eval): Document the LEXICAL arg to eval. - - * variables.texi (Variables, Void Variables): Use "scoping rule" - terminology consistently. - (Variable Scoping): Add index entries, and use "dynamic scope" - terminology in place of "indefinite scope" to reduce confusion. - (Lexical Binding): Document lexical environment format. - (Using Lexical Binding): Add index entries for error messages. - -2013-12-24 Tassilo Horn - - * control.texi (Pattern matching case statement): Fix missing - argument in simple expression language sample (Bug#16238). - Add some sample programs written in that language. Mention that - `pcase' requires lexical binding. - -2013-12-23 Xue Fuqiao - - * eval.texi (Special Forms): Document `special-form-p'. - - * macros.texi (Simple Macro): Document `macrop'. - - * files.texi (Changing Files): Fix an argument of `copy-file'. - - * strings.texi (Creating Strings): Document TRIM in `split-string'. - -2013-12-23 Chong Yidong - - * keymaps.texi (Controlling Active Maps): - Rename set-temporary-overlay-map to set-transient map. Doc fixes. - (Searching Keymaps): The transient keymap takes precedence. - -2013-12-23 Glenn Morris - - * loading.texi (How Programs Do Loading, Load Suffixes): - Mention `load-prefer-newer'. - -2013-12-22 Xue Fuqiao - - * hash.texi (Other Hash): Document `hash-table-keys' - and `hash-table-values'. - -2013-12-22 Eli Zaretskii - - * nonascii.texi (Character Properties): NAME or OLD-NAME - properties can be nil (there's no empty string). - (Character Properties): Update the reference to the UCD. - -2013-12-22 Xue Fuqiao - - * sequences.texi (Bool-Vectors): Document new bool-vector set - operation functions. - - * text.texi (Examining Properties): Document `get-pos-property'. - - * variables.texi (Directory Local Variables): - Document `enable-dir-local-variables'. - - * debugging.texi (Debugger Commands): - Document `debugger-toggle-locals'. - -2013-12-21 Chong Yidong - - * text.texi (Region Indent): Note the new interactive behavior of - indent-rigidly. - -2013-12-20 Tassilo Horn - - * numbers.texi (numbers): Document that =, <, <=, >, >= now accept - one or many arguments. - - * display.texi: Document `messages-buffer'. - - * os.texi: Document `initial-buffer-choice' changes. - -2013-12-20 Chong Yidong - - * text.texi (Changing Properties): Improve documentation for - add-face-text-property. - (Special Properties): Mention add-face-text-property. - -2013-12-18 Chong Yidong - - * customize.texi (Custom Themes): Document custom-known-themes - (Bug#15717). - - * modes.texi (Defining Minor Modes): Fix typo (Bug#14874). - (Keymaps and Minor Modes): Fix binding convention (Bug#11522). - -2013-12-13 Glenn Morris - - * internals.texi (Building Emacs): - * loading.texi (Library Search): Mention that site-load, - site-init cannot change load-path. - -2013-12-12 Glenn Morris - - * elisp.texi: Tweak dircategory. - -2013-12-12 Eli Zaretskii - - * nonascii.texi (Encoding and I/O): Document file-name encoding - peculiarities on MS-Windows. - -2013-12-12 Glenn Morris - - * elisp.texi: Sync direntry with info/dir version. - -2013-12-08 Juanma Barranquero - - * display.texi (Progress, Face Remapping): - * processes.texi (Serial Ports): - * windows.texi (Recombining Windows): Fix typos. (Bug#16089) - -2013-12-04 Juri Linkov - - * searching.texi (Search and Replace): Fix `unread-command-events' - and add ref. - -2013-12-03 Juri Linkov - - * windows.texi (Choosing Window): Rename `no-display-ok' to - `allow-no-window'. (Bug#13594) - -2013-11-30 Glenn Morris - - * Makefile.in (distclean): Remove Makefile. - -2013-11-29 Andreas Politz - - * modes.texi (Imenu): Make it clear that sub-alist is the cdr - (Bug#14029). - -2013-11-27 Glenn Morris - - * loading.texi (Library Search): - * os.texi (Startup Summary): No more leim directory. - -2013-11-26 Glenn Morris - - * os.texi (Startup Summary): Update for leim-list being preloaded. - -2013-11-23 Brian Jenkins (tiny change) - - * frames.texi (Input Focus): - * hooks.texi (Standard Hooks): Mention focus-in-hook, focus-out-hook. - -2013-11-23 Glenn Morris - - * loading.texi (Library Search): - Empty elements in EMACSLOADPATH now mean the default load-path. - -2013-11-22 Glenn Morris - - * loading.texi (Library Search): Minor clarification. - -2013-11-20 Leo Liu - - * windows.texi (Choosing Window): Mention `no-display-ok'. (Bug#13594) - -2013-11-19 Xue Fuqiao - - * os.texi (File Notifications): Add an index. - - * loading.texi (Loading): Add an cross-reference. - -2013-11-18 Xue Fuqiao - - * os.texi (Session Management, Desktop Notifications): Add some - indexes and a cross-reference. - -2013-11-17 Xue Fuqiao - - * os.texi (Time Parsing, Processor Run Time, Input Modes) - (Terminal Output): Minor fixes. - -2013-11-14 Glenn Morris - - * loading.texi (Library Search): Update section. - -2013-11-11 Xue Fuqiao - - * os.texi (User Identification, Time of Day, Time Conversion): - Minor fixes. - -2013-11-10 Jan Djärv - - * keymaps.texi (Tool Bar): Mention that Gtk+/NS ignores item 1 to 3. - -2013-11-09 Xue Fuqiao - - * os.texi (Startup Summary): Add an index about startup screen. - Typo fix. - (Command-Line Arguments): Add cross-reference for `dump-emacs'. - -2013-11-08 Eli Zaretskii - - * display.texi (Truncation): Document that cache-long-scans is now - non-nil by default. (Bug#15797) - -2013-11-05 Eli Zaretskii - - * lists.texi (Rearrangement): Fix indexing. - - * display.texi (Bidirectional Display): Fix indexing. - -2013-11-05 Xue Fuqiao - - * lists.texi (Rearrangement): Improve indexing. - - * display.texi (Glyphs): Add an index for glyph code. - (Bidirectional Display): Improve indexing. - -2013-11-01 Jan Djärv - - * display.texi (Face Attributes): Document :distant-foreground. - -2013-10-30 Xue Fuqiao - - * display.texi (Abstract Display): Improve indexing. - -2013-10-29 Stefan Monnier - - * display.texi (Selective Display): Discourage the use of explicit - selective display. - -2013-10-29 Xue Fuqiao - - * display.texi (Showing Images): Add an index for image-size. - Use @code instead of @var for a normal variable. - (Multi-Frame Images): Improve indexing. - (Button Buffer Commands): Use @code instead of @var for a normal - variable. - (Abstract Display): Explain the meaning of Ewoc. - -2013-10-27 Xue Fuqiao - - * display.texi (Image Descriptors): Improve indexing. - -2013-10-26 Xue Fuqiao - - * display.texi (Fringe Indicators): Add indexes for fringe indicators. - (Customizing Bitmaps): Add an index for customizing fringe bitmaps. - -2013-10-25 Xue Fuqiao - - * display.texi (Fontsets): Minor wording fix. - (Low-Level Font): Improve indexing. - - * nonascii.texi (Character Properties): Add an index for script symbols. - -2013-10-24 Xue Fuqiao - - * display.texi (Face Remapping): Add indexes for face remapping. - (Font Selection): Add indexes. - (Low-Level Font): Add an index for font registry. - -2013-10-23 Glenn Morris - - * eval.texi, files.texi, intro.texi, objects.texi, searching.texi: - Nuke @refill. - - * Makefile.in (install-dvi, install-html, install-pdf) - (install-ps, uninstall-dvi, uninstall-html, uninstall-ps) - (uninstall-pdf): Quote entities that might contain whitespace. - -2013-10-19 Xue Fuqiao - - * display.texi (Face Attributes): Add indexes for the ‘:box’ - face attribute. - -2013-10-18 Xue Fuqiao - - * display.texi (Line Height): Add indexes for line height. - -2013-10-17 Xue Fuqiao - - * display.texi (Width): Fix arguments of ‘truncate-string-to-width’. - -2013-10-16 Xue Fuqiao - - * display.texi (Selective Display): Add an index for explicit - selective display. - -2013-10-15 Xue Fuqiao - - * display.texi (Warning Basics): Mention the ‘*Warnings*’ buffer. - -2013-10-13 Glenn Morris - - * intro.texi (Acknowledgments): Use accented form of some names. - -2013-10-09 Glenn Morris - - * control.texi (Conditionals): Copyedits. (Bug#15558) - -2013-10-08 Eli Zaretskii - - Support menus on text-mode terminals. - * keymaps.texi (Defining Menus, Mouse Menus, Menu Bar): - Modify wording to the effect that menus are supported on TTYs. - - * frames.texi (Pop-Up Menus, Dialog Boxes) - (Display Feature Testing): Update for menu support on TTYs. - -2013-10-07 Stefan Monnier - - * tips.texi (Comment Tips): Discourage use of triple semi-colons for - non-headings. - -2013-10-05 Xue Fuqiao - - * syntax.texi (Categories): Add an index for category sets. - -2013-10-03 Xue Fuqiao - - * syntax.texi (Syntax Flags, Syntax Table Functions): Add indexes. - -2013-10-02 Xue Fuqiao - - * syntax.texi (Syntax Class Table): Add an index for syntax class table. - -2013-09-29 Xue Fuqiao - - * searching.texi (Regexp Search): Refine. - -2013-09-22 Xue Fuqiao - - * nonascii.texi (Default Coding Systems): Typo fix. - -2013-09-21 Xue Fuqiao - - * nonascii.texi (Coding System Basics): Add information about - carriage-return. - -2013-09-14 Eli Zaretskii - - * display.texi (Display Margins): State the units of measuring - margin width. (Bug#15375) - -2013-09-13 Eli Zaretskii - - * text.texi (Not Intervals): Minor wording fix. - -2013-09-12 Xue Fuqiao - - * functions.texi (Obsolete Functions): Add an index for obsolete - functions. - -2013-09-11 Xue Fuqiao - - * nonascii.texi (Character Properties): Character properties fix - for decimal-digit-value and digit-value. - -2013-09-08 Stefan Monnier - - * macros.texi (Defining Macros): Prefer "function" to "lambda - expression" (bug#15296). - -2013-08-28 Paul Eggert - - * Makefile.in (SHELL): Now @SHELL@, not /bin/sh, - for portability to hosts where /bin/sh has problems. - -2013-08-26 Stefan Monnier - - * variables.texi (File Local Variables): Don't recommend quoting! Ever! - -2013-08-20 Eli Zaretskii - - * files.texi (Information about Files): Mention file names with - trailing blanks on MS-Windows. (Bug#15130) - -2013-08-18 Xue Fuqiao - - * positions.texi (Positions): Improve indexing. - -2013-08-18 Eli Zaretskii - - * markers.texi (The Region): Improve indexing. - -2013-08-17 Xue Fuqiao - - * modes.texi (SMIE, SMIE Grammar, SMIE Indentation): Add some indexes. - - * text.texi (Maintaining Undo): Mention interactive call of - buffer-disable-undo. - (Filling): Add cross-reference for hard newlines. - (Sorting): Fix indentation. - (Columns): Comment out undefined behavior. - (Case Changes): Fix an `args-out-of-range' error in the example. - -2013-08-16 Xue Fuqiao - - * text.texi (Insertion): Refine. - (Margins): Add an index. - (Undo): Doc fix for `buffer-undo-list'. - - * positions.texi (Character Motion): - * markers.texi (Moving Markers, Creating Markers): - Comment out undefined behavior. - -2013-08-15 Xue Fuqiao - - * markers.texi (The Region): Add/move indexes. - -2013-08-13 Lars Magne Ingebrigtsen - - * display.texi (ImageMagick Images): Mention :content-type and - `image-content-type-suffixes'. - -2013-08-13 Xue Fuqiao - - * positions.texi (Word Motion): Remove redundant sentence. - -2013-08-13 Glenn Morris - - * lists.texi (List Elements): - Undocument behavior of nth and nthcdr with n < 0. (Bug#15059) - -2013-08-13 Xue Fuqiao - - * frames.texi (Display Feature Testing): Add indexes. - -2013-08-12 Glenn Morris - - * Makefile.in (prefix, datarootdir, datadir, PACKAGE_TARNAME) - (docdir, dvidir, htmldir, pdfdir, psdir, GZIP_PROG, INSTALL) - (INSTALL_DATA): New, set by configure. - (HTML_OPTS, DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS): - New variables. - (.SUFFIXES): Add .ps and .dvi. - (.dvi.ps): New suffix rule. - (dvi, html, pdf, ps): Use *_TARGETS variables. - (elisp.html): Use HTML_OPTS. - (elisp.ps): Remove explicit rule. - (.PHONY): install-dvi, install-html, install-pdf, install-ps, - install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, - uninstall-ps, and uninstall-doc. - (install-dvi, install-html, install-pdf, install-ps, install-doc) - (uninstall-dvi, uninstall-html, uninstall-ps, uninstall-pdf) - (uninstall-doc): New rules. - (clean): Use DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS. - -2013-08-10 Xue Fuqiao - - * edebug.texi (Instrumenting Macro Calls): Use @defmac for macros. - -2013-08-09 Xue Fuqiao - - * control.texi (Error Symbols): Minor fix for previous change. - -2013-08-09 Stefan Monnier - - * errors.texi (Standard Errors): Don't refer to `error-conditions'. - - * control.texi (Signaling Errors): Refer to define-error. - (Error Symbols): Add `define-error'. - -2013-08-06 Dmitry Antipov - - * positions.texi (Motion by Screen Lines): - * display.texi (Truncation): Rename `cache-long-line-scans' - to `cache-long-scans'. - -2013-08-05 Xue Fuqiao - - * windows.texi (Window Start and End): Add an index. - -2013-08-02 Xue Fuqiao - - * display.texi (Face Functions): Add an index. - - * variables.texi (Variable Aliases): Add an index. - - * functions.texi (Defining Functions): Add an index. - - * nonascii.texi (Coding System Basics): Add an index. - -2013-07-31 Xue Fuqiao - - * nonascii.texi (Non-ASCII Characters): Update menu. - (Disabling Multibyte): Move here from doc/emacs/mule.texi. - Fix cross-references. - - * elisp.texi (Top): Update menu. - -2013-07-30 Xue Fuqiao - - * windows.texi (Window History): Mention the default value of - switch-to-visible-buffer. Add cross-references. - -2013-07-24 Michael Albinus - - * errors.texi (Standard Errors): Fix typo. - - * files.texi (Magic File Names): - * os.texi (File Notifications): Remove file-notify-supported-p. - -2013-07-24 Paul Eggert - - * eval.texi (Special Forms): Mention 'lambda'. Also, say that - non-well-formed expressions result in unspecified behavior, though - Emacs will not crash. - -2013-07-22 Michael Albinus - - * files.texi (Magic File Names): Add file-notify-add-watch, - file-notify-rm-watch and file-notify-supported-p. - Move file-remote-p down. - - * errors.texi (Standard Errors): Add file-notify-error. - - * os.texi (Desktop Notifications): Rename from Notifications. - (File Notifications): New node. - - * elisp.texi (Top): Update menu for these changes. - -2013-07-19 Xue Fuqiao - - * windows.texi (Display Action Functions): Mention next-window. - -2013-07-16 Xue Fuqiao - - * windows.texi (Selecting Windows): Fix the introduction of - `set-frame-selected-window''s arguments. - -2013-07-10 Paul Eggert - - Timestamp fixes for undo (Bug#14824). - * text.texi (Undo): Document (t . 0) and (t . -1) in buffer-undo-list. - -2013-07-06 Eli Zaretskii - - * nonascii.texi (Text Representations): Document that - multibyte-string-p returns nil for non-string objects. - -2013-07-06 Glenn Morris - - * elisp.texi (Top): Move WWW_GNU_ORG section outside @copying. - -2013-07-03 Glenn Morris - - * debugging.texi (Debugging): - * files.texi (File Attributes, Changing Files): Fix cross-references. - - * package.texi (Package Archives): Fix @url call. - - * syntax.texi (Syntax Table Functions): Mention describe-syntax. - -2013-06-29 Eli Zaretskii - - * display.texi (Bidirectional Display): Document move-point-visually. - -2013-06-29 Xue Fuqiao - - * buffers.texi (Buffer File Name): Fix typo. - -2013-06-26 Christopher Schmidt - - * tips.texi (Coding Conventions): Improve wording. - -2013-06-24 Glenn Morris - - * loading.texi (Autoload): Fix typo. - - * variables.texi (Lexical Binding): Fix typo. - - * functions.texi (Anonymous Functions): Put back ' removed 2012-10-23. - -2013-06-23 Lars Magne Ingebrigtsen - - * display.texi (ImageMagick Images): Mention :max-width and - :max-height. - -2013-06-20 Paul Eggert - - * numbers.texi (Math Functions): Remove obsolete function log10. - -2013-06-19 Stefan Monnier - - * modes.texi (Mode Line Data, Properties in Mode): Advertise `keymap' - rather than `local-map'. - - * keymaps.texi (Active Keymaps): Fix documentation of - set-temporary-overlay-map and overriding-terminal-local-map. - -2013-06-19 Glenn Morris - - * Makefile.in (dist): Edit more configure variables. - Try to check that we do not miss any in future. - -2013-06-17 Juanma Barranquero - - * text.texi (Undo, Changing Properties): Fix typos. - -2013-06-17 Lars Magne Ingebrigtsen - - * text.texi (Changing Properties): Document `add-face-text-property'. - -2013-06-17 Kenichi Handa - - * display.texi (Face Attributes): Refer to "Low-Level font" (not - "Font Selection") in the explanation of :font attribute (bug#14629). - -2013-06-13 Stefan Monnier - - * loading.texi (Hooks for Loading): Don't document after-load-alist. - Document with-eval-after-load instead of eval-after-load. - -2013-06-11 Xue Fuqiao - - * files.texi (File Name Expansion): Make the example more - intuitive. - -2013-06-10 Paul Eggert - - Documentation fix for 'ls' and hard links. - * compile.texi (Compilation Functions): - * files.texi (File Attributes, Changing Files): - Use current format for GNU 'ls' output. - (File Attributes): Fix problem introduced in previous change: - the link count is the number of hard links, not the number - of hard links + 1. - -2013-06-10 Xue Fuqiao - - * files.texi (File Attributes): Fix typo. - -2013-05-29 Stefan Monnier - - * functions.texi (Lambda Expressions): Lambda expressions don't - evaluate to themselves in general (bug#11782). - -2013-05-15 Stefan Monnier - - * loading.texi (Autoload): - * help.texi (Documentation Basics, Accessing Documentation) - (Accessing Documentation, Accessing Documentation): DOC-* is now DOC. - -2013-04-23 Glenn Morris - - * internals.texi (Writing Emacs Primitives): Remove obvious example. - Tweak other to avoid overly long line. - -2013-04-21 Xue Fuqiao - - * internals.texi (Writing Emacs Primitives): Remove unnecessary - references to the sources. (Bug#13800) - - * searching.texi (Regexp Backslash): Doc fix for backslash - constructs in regular expressions. - -2013-04-15 Christopher Schmidt - - * tips.texi (Coding Conventions): Mention separation of package - descriptor and name of internal symbols by two hyphens. - -2013-04-13 Stephen Berman - - * windows.texi (Splitting Windows): Change category of - split-window from a command to a function. - -2013-04-06 Chong Yidong - - * display.texi (Faces): Minor clarifications. - (Defining Faces): Clarify default vs custom face specs. - Document face-spec-set. - - * display.texi (Overlay Properties): - * text.texi (Special Properties): Use the "anonymous face" - terminology. Describe foreground-color and background-color forms - as compatibility-only. - -2013-03-24 Eli Zaretskii - - * compile.texi (Byte-Code Objects): Add index entry. - (Disassembly): Add cross-references. - -2013-03-23 Eli Zaretskii - - * frames.texi (Size Parameters): More accurate description of the - difference between 'fullboth' and 'maximized'. (Bug#13935) - -2013-03-17 Christopher Schmidt - - * symbols.texi (Standard Properties): Document pure. (Bug#13823) - -2013-03-16 Glenn Morris - - * elisp.texi: Add some stuff specific to www.gnu.org. - -2013-03-11 Teodor Zlatanov - - * control.texi (Pattern matching case statement): Fix typo. - -2013-03-04 Paul Eggert - - * elisp.texi, intro.texi: Switch from Latin-1 to UTF-8. - -2013-03-03 Glenn Morris - - * objects.texi (Symbol Type): Fix typo. - -2013-02-28 Bastien Guerry - - * variables.texi (File Local Variables): Fix reference. - -2013-02-24 Eli Zaretskii - - * files.texi (Magic File Names): Improve wording and indexing. - -2013-02-21 Glenn Morris - - * display.texi (Multi-Frame Images): Minor rephrasing. - -2013-02-20 Glenn Morris - - * display.texi (GIF Images, TIFF Images): Delete these nodes. - (ImageMagick Images): For :index, use an xref rather than duplicating. - (Other Image Types): Add GIF, adjust formatting. - (Multi-Frame Images): Rename from Animated Images. Expand section. - * elisp.texi (Top): Update menu for these changes. - -2013-02-19 Glenn Morris - - * text.texi (Change Hooks): Fix typo. - -2013-02-15 Glenn Morris - - * modes.texi (Basic Major Modes): 'z' no longer bound in special-mode. - -2013-02-13 Glenn Morris - - * objects.texi (Char-Table Type): Add footnote about #^^. - - * modes.texi (Minor Mode Conventions): Fix typo. - - * keymaps.texi (Scanning Keymaps): Remove obsolete sentence about - meta characters; this changed in 22.1. (Bug#13684) - - * objects.texi (Char-Table Type): Add cindex. - - * keymaps.texi (Key Binding Commands): Trivial rephrasing. - -2013-02-10 Glenn Morris - - * keymaps.texi (Creating Keymaps): Update make-keymap result. - -2013-02-09 Eli Zaretskii - - * modes.texi (%-Constructs): Remove the description of %t. - - * nonascii.texi (MS-DOS File Types): Delete node. - -2013-02-08 Glenn Morris - - * keymaps.texi (Active Keymaps, Searching Keymaps): - Remove confusing mention of "symbolic prefix". (Bug#13643) - -2013-01-19 Glenn Morris - - * macros.texi (Indenting Macros): Fix order of an indent - symbol's arguments. (Bug#13450) - -2013-01-19 Paul Eggert - - Allow floating-point file offsets. - * files.texi (Reading from Files, Writing to Files): - Say that file offsets can be numbers, not just integers. - -2013-01-09 Glenn Morris - - * commands.texi (Interactive Codes): - Whitespace does not terminate interactive "S". (Bug#13393) - -2013-01-06 Chong Yidong - - * windows.texi (Vertical Scrolling): Fix typos (Bug#13267). - -2013-01-05 Glenn Morris - - * display.texi (Overlay Properties): Mention field. (Bug#13364) - -2013-01-05 Eli Zaretskii - - * hooks.texi (Standard Hooks): Use @item, not @itemx, as the first - directive in a group of items. - -2013-01-05 Chong Yidong - - * keymaps.texi (Key Sequences): Remove obsolete sentence - (Bug#13356). - -2013-01-04 Ari Roponen (tiny change) - - * hash.texi (Defining Hash): Fix typo. (Bug#13345) - -2013-01-04 Stefan Monnier - - * files.texi (File Attributes): Undocument return format of file-acl. - -2013-01-03 Glenn Morris - - * processes.texi (System Processes): - * syntax.texi (Syntax Table Functions): Tweak some line breaks. - - * searching.texi (Replacing Match): Fix xref. - - * elisp.texi (DATE): Bump to Jan 2013. - -2013-01-02 Glenn Morris - - * customize.texi (Common Keywords, Type Keywords): - Replace "active field" with "button". (Bug#13310) - - * customize.texi (Common Keywords): Add xref. (Bug#13311) - * tips.texi (Library Headers): Add cindex. - -2012-12-30 Wolfgang Jenkner - - * functions.texi (Declare Form): - * intro.texi (A Sample Function Description): - * syntax.texi (Syntax Table Internals, Syntax Table Functions): - * variables.texi (Using Lexical Binding): Don't use @var or CAPS - in @def.. commands. (Bug#13292) - -2012-12-29 Eli Zaretskii - - * files.texi (Changing Files): Document the return values of - set-file-selinux-context and set-file-acl. - -2012-12-27 Glenn Morris - - * files.texi (File Names): Mention Cygwin conversion functions. - -2012-12-22 Martin Rudalics - - * windows.texi (Selecting Windows): Reword description of - select-window (Bug#13248). - -2012-12-22 Eli Zaretskii - - * files.texi (File Attributes, Changing Files): Remove the details - about the text returned by file-acl. Instead, just document that - it is an opaque string meant to be used by set-file-acl. - -2012-12-21 Chong Yidong - - * modes.texi (Auto Major Mode): Fix typo (Bug#13230). - - * customize.texi (Simple Types): Document key-sequence type - (Bug#13048). - - * strings.texi (Text Comparison): Doc fix for compare-strings. - -2012-12-19 Michael Albinus - - * files.texi (Magic File Names): Add `file-acl', - `file-selinux-context', `set-file-acl' and - `set-file-selinux-context'. Make the list consistent. - -2012-12-19 Jonas Bernoulli - - * tips.texi (Library Headers): New header keyword `Homepage'. - Make continuation lines syntax more precise. - -2012-12-17 Eli Zaretskii - - * files.texi (File Attributes, Changing Files): Update to include - MS-Windows support for ACLs. - -2012-12-16 Romain Francoise - - * files.texi (File Attributes): Document ACL support and new - `file-acl' function. - (Changing Files): Mention argument name change of `copy-file' and - document new function `set-file-acl'. - -2012-12-14 Paul Eggert - - Fix permissions bugs with setgid directories etc. (Bug#13125) - * files.texi (Testing Accessibility): Document GROUP arg - of file-ownership-preserved-p. - (File Attributes): Document that 9th element is now - just a placeholder. - * os.texi (User Identification): Document new functions group-gid, - group-real-gid. - -2012-12-11 Paul Eggert - - * internals.texi (C Integer Types): New section. - This follows up and records an email in - . - -2012-12-10 Stefan Monnier - - * control.texi (Pattern matching case statement): New node. - - * customize.texi (Variable Definitions): Mention the default :group - for defcustoms (bug#13093). - -2012-12-09 Glenn Morris - - * customize.texi (Variable Definitions): Mention eval-defun - on a defcustom calls the :set function when appropriate. - -2012-12-06 Paul Eggert - - * doclicense.texi, gpl.texi: Update to latest version from FSF. - These are just minor editorial changes. - -2012-12-06 Chong Yidong - - * lists.texi (Plist Access): Move put example to Symbol Plists. - - * symbols.texi (Standard Properties): Fix typo. - -2012-12-03 Chong Yidong - - * symbols.texi (Symbol Properties): New node. - (Symbol Plists): Make it a subsection under Symbol Properties. - (Standard Properties): New node. - - * lists.texi (Property Lists): Move here from symbols.texi. - (Plist Access): Rename from Other Plists. - - * customize.texi (Variable Definitions): - * display.texi (Defining Faces): - * sequences.texi (Char-Tables): Fix xref. - - * keymaps.texi (Key Sequences): `kbd' is now a function. - - * commands.texi (Using Interactive): Fix index entry. - -2012-11-24 Paul Eggert - - * doclicense.texi: Update to latest version from FSF. - These are just minor editorial changes. - * elisp.texi (GNU Free Documentation License) - (GNU General Public Licens): - Provide sectioning, since doclicense.texi no longer does that. - - * loading.texi (Named Features): @ -> @@ to fix typo. - -2012-11-24 Martin Rudalics - - * windows.texi (Basic Windows): Fix typo. - (Windows and Frames): Fix example. Move description of - window-in-direction here. - (Recombining Windows): Fix example. - (Buffers and Windows): Fix description of replace-buffer-in-windows. - (Switching Buffers): Reword. - (Display Action Functions): Minor adjustments. - (Choosing Window Options): Minor fixes. - (Window History): Minor rewording. - (Dedicated Windows): Correct and reword part describing how - dedicatedness affects functions removing buffers or windows. - * buffers.texi (The Buffer List): Fix description of bury-buffer. - -2012-11-24 Chong Yidong - - * modes.texi (%-Constructs): Fix statement about mode construct - padding (Bug#12866). - -2012-11-24 Stefan Monnier - - * debugging.texi (Profiling): Make it more clear - that --enable-profiling is about profiling the C code. - -2012-11-21 Glenn Morris - - * display.texi (Attribute Functions): - Update for set-face-* name changes. - Add new "inherit" argument for face-bold-p etc. - Move description of this argument to a common section, like "frame". - - * debugging.texi (Profiling): New section. - (Debugging): Mention profiling in the introduction. - * tips.texi (Compilation Tips): Move profiling to separate section. - * elisp.texi: Add Profiling to detailed menu. - -2012-11-21 Martin Rudalics - - * windows.texi (Display Action Functions): Fix recently added - example. Suggested by Michael Heerdegen. - -2012-11-21 Paul Eggert - - Minor cleanup for times as lists of four integers. - * os.texi (Time Parsing): Time values can now be four integers. - -2012-11-18 Glenn Morris - - * loading.texi (How Programs Do Loading): Add eager macro expansion. - * macros.texi (Expansion): Mention eager macro expansion. - - * minibuf.texi (Basic Completion): Mention misc completion-table funcs. - -2012-11-18 Leo Liu - - * minibuf.texi (Programmed Completion): Doc fix for metadata - request (Bug#12850). - -2012-11-18 Glenn Morris - - * display.texi (Temporary Displays): Document with-temp-buffer-window. - - * frames.texi (Size and Position): Add fit-frame-to-buffer command. - * windows.texi (Resizing Windows): Add fit-frame-to-buffer option. - (Window Sizes): Add vindex for window-min-height, window-min-width. - (Display Action Functions): Mention pop-up-frame-parameters. - -2012-11-16 Martin Rudalics - - * windows.texi (Choosing Window): Rewrite description of - display-buffer-alist (Bug#12167). - (Display Action Functions): Mention inhibit-switch-frame. - Fix description of display-buffer-below-selected. Reorder actions. - Add example (Bug#12848). - -2012-11-16 Glenn Morris - - * display.texi (Face Attributes): Fix :underline COLOR description. - (Attribute Functions): Update for set-face-underline rename. - Tweak descriptions of face-underline-p, face-inverse-video-p. - - * keymaps.texi (Searching Keymaps, Tool Bar): Untabify examples, - so they align better in info. - (Active Keymaps, Searching Keymaps, Controlling Active Maps): - Document set-temporary-overlay-map. - -2012-11-15 Stefan Monnier - - * keymaps.texi (Translation Keymaps): Add a subsection "Interaction - with normal keymaps". - -2012-11-15 Dmitry Antipov - - * internals.texi (Garbage Collection): Update descriptions - of vectorlike_header, garbage-collect and gc-cons-threshold. - (Object Internals): Explain Lisp_Object layout and the basics - of an internal type system. - (Buffer Internals): Update description of struct buffer. - -2012-11-13 Glenn Morris - - * variables.texi (Adding Generalized Variables): - At least mention gv-define-expander and gv-letplace. - - * debugging.texi (Error Debugging): Mention debug-on-message. - (Using Debugger): Mention debugger-bury-or-kill. - - * control.texi (Signaling Errors): - * debugging.texi (Error Debugging): - * errors.texi (Standard Errors): Add user-error. - - * variables.texi (Adding Generalized Variables): - Use standard formatting for common lisp note about setf functions. - -2012-11-10 Martin Rudalics - - * elisp.texi (Top): Add Recombining Windows to menu. - * windows.texi (Recombining Windows): New subsection. - (Splitting Windows): Rewrite text on handling of window - combinations and move it to new subsection. - -2012-11-10 Chong Yidong - - * searching.texi (Replacing Match): Document \? in replace-match. - - * variables.texi (Creating Buffer-Local): Document setq-local and - defvar-local. - (Setting Generalized Variables): Arrange table alphabetically. - - * lists.texi (List Elements, List Variables): Clarify descriptions - of push and pop for generalized variables. - - * edebug.texi (Specification List): setf is no longer CL-only. - -2012-11-10 Glenn Morris - - * variables.texi (Adding Generalized Variables): - Update description of FIX-RETURN expansion. - - * variables.texi (Setting Generalized Variables): - Split most of previous contents into this subsection. - (Adding Generalized Variables): New subsection. - Move note on lack of setf functions here from misc/cl.texi. - - * elisp.texi: Add Generalized Variables subsections to detailed menu. - -2012-11-10 Chong Yidong - - * frames.texi (Initial Parameters): Doc fix (Bug#12144). - -2012-11-08 Michael Albinus - - * os.texi (Notifications): Update descriptions of - notifications-notify, notifications-close-notification and - notifications-get-capabilities according to latest code changes. - Add notifications-get-server-information. - -2012-11-03 Chong Yidong - - * objects.texi (General Escape Syntax): Clarify the explanation of - escape sequences. - (Non-ASCII in Strings): Clarify when a string is unibyte vs - multibyte. Hex escapes do not automatically make a string - multibyte. - -2012-11-03 Martin Rudalics - - * windows.texi (Switching Buffers): Document option - switch-to-buffer-preserve-window-point. - (Display Action Functions): Document window-height and - window-width alist entries. - (Display Action Functions): - Document display-buffer-below-selected and - display-buffer-in-previous-window. - (Quitting Windows): Document quit-restore-window. - Rewrite section. - (Window Configurations): In window-state-get mention that - argument window must be valid. - (Window Parameters): Document quit-restore window parameter - (Bug#12158). - -2012-10-31 Glenn Morris - - * control.texi (Catch and Throw): Add xref to cl.texi. - - * lists.texi (Sets And Lists): Point xref to better location. - - * errors.texi (Standard Errors): - * loading.texi (Autoload): Update for cl-lib namespace changes. - - * modes.texi (Defining Minor Modes): "Generalized Variables" - section is now in this manual rather than cl.texi. - - * eval.texi (Special Forms): No longer special forms: defmacro, - defun, save-window-excursion, with-output-to-temp-buffer. - * functions.texi (Defining Functions): Defun is now a macro. - Defalias is a function. - -2012-10-30 Glenn Morris - - * variables.texi (Generalized Variables): Fix typo. - -2012-10-30 Chong Yidong - - * symbols.texi (Symbol Plists): Document function-get. - - * loading.texi (Autoload): Document autoloadp, autoload-do-load. - - * frames.texi (Visibility of Frames): Document tty-top-frame. - -2012-10-28 Stefan Monnier - - * keymaps.texi (Format of Keymaps): Document the multiple - inheritance format. - -2012-10-28 Martin Rudalics - - * windows.texi (Basic Windows): Reformulate description of live, - internal and valid windows. - (Cyclic Window Ordering): Describe new argument of - get-lru-window and get-largest-window. Add description of - window-in-direction. - -2012-10-27 Glenn Morris - - * variables.texi (Generalized Variables): New section, - adapted from misc/cl.texi. - * elisp.texi (Top): Add Generalized Variables to menu. - * lists.texi (List Elements, List Variables): - Mention generalized variables. - - * lists.texi (List Elements): Typo fix. - -2012-10-27 Chong Yidong - - * minibuf.texi (High-Level Completion): Don't mention removed - function iswitchb-read-buffer. - - * commands.texi (Event Input Misc): Remove last-input-char. - (Command Loop Info): Remove last-command-char. - - * frames.texi (Initial Parameters): Don't mention the obsolete - special-display feature. - - * windows.texi (Choosing Window): Don't mention the obsolete - special display feature. - (Choosing Window Options): Remove obsolete special-display - variables, and the functions special-display-p and - special-display-popup-frame. - - * display.texi (Fringe Bitmaps): Add exclamation-mark bitmap. - - * hooks.texi (Standard Hooks): Remove obsolete hooks. - - * markers.texi (Information from Markers): Remove obsolete - function buffer-has-markers-at. - - * text.texi (Yanking): Document yank-handled-properties. - -2012-10-24 Paul Eggert - - Update manual for new time stamp format (Bug#12706). - * buffers.texi (Modification Time): - * files.texi (Testing Accessibility, File Attributes): - * intro.texi (Version Info): - * os.texi (Time of Day): - Update for new time stamp format (HIGH LOW MICROSEC PICOSEC). - These instances were missed the first time around. - Problem reported by Glenn Morris in . - -2012-10-24 Chong Yidong - - * minibuf.texi (Text from Minibuffer): Document read-regexp - changes. - - * nonascii.texi (Selecting a Representation): - Document set-buffer-multibyte changes. - - * keymaps.texi (Toolkit Differences): Node deleted. - (Easy Menu): New node. - -2012-10-23 Stefan Monnier - - * hooks.texi (Standard Hooks): Clarify that -hooks is deprecated. - -2012-10-23 Paul Eggert - - Fix outdated timestamp documentation in Elisp manual (bug#12706). - * files.texi (File Attributes): - * text.texi (Undo): - Time stamp resolution is now 1 picosecond, not 1 second. - -2012-10-23 Chong Yidong - - * display.texi (Font Lookup): Remove font-list-limit. - - * keymaps.texi (Key Sequences): Avoid referring to Edit Macro mode - (Bug#12529). - -2012-10-22 Glenn Morris - - * os.texi (Recording Input): Tiny fix. - - * intro.texi (Lisp History): - * lists.texi (Sets And Lists): Refer to cl-lib rather than cl. - * tips.texi (Coding Conventions): Recommend cl-lib over cl. - -2012-10-15 Chong Yidong - - * macros.texi (Defining Macros): defmacro is now a macro. - Explicitly list the docstring and declare arguments. - - * functions.texi (Anonymous Functions): Explicitly list the - docstring, declare, and interactive arguments to lambda. - (Defining Functions): Likewise for defun. - (Inline Functions): Likewise for defsubst. - (Declare Form): Tweak description. - -2012-10-13 Chong Yidong - - * display.texi (ImageMagick Images): ImageMagick enabled by default. - -2012-10-05 Chong Yidong - - * minibuf.texi (Basic Completion): Clarify list form of completion - table (Bug#12564). - -2012-10-05 Bruno Félix Rezende Ribeiro (tiny change) - - * functions.texi (Function Safety): Copyedit. (Bug#12562) - -2012-10-01 Paul Eggert - - Revert the FOLLOW-SYMLINKS change for file-attributes. - * files.texi (File Attributes, Magic File Names): Undo last change. - -2012-09-30 Paul Eggert - - file-attributes has a new optional arg FOLLOW-SYMLINKS. - * files.texi (File Attributes): Describe it. - (Magic File Names): Use it. - -2012-09-30 Chong Yidong - - * commands.texi (Click Events): Define "mouse position list". - Remove mention of unimplemented horizontal scroll bars. - (Drag Events, Motion Events): Refer to "mouse position list". - (Accessing Mouse): Document posnp. - - * errors.texi (Standard Errors): Tweak arith-error description. - Tweak markup. Remove domain-error and friends, which seem to be - unused after the floating-point code revamp. - - * functions.texi (Defining Functions): defun is now a macro. - (Obsolete Functions): Obsolescence also affects - documentation commands. Various clarifications. - (Declare Form): New node. - - * strings.texi (String Basics): Copyedits. - - * os.texi (Startup Summary): Document leim-list.el change. - (User Identification): Add system-users and system-groups. - (Idle Timers): Minor clarifications. - - * macros.texi (Defining Macros): Move description of `declare' to - Declare Form node. - - * loading.texi (Autoload): - * help.texi (Documentation Basics): The special sequences can - trigger autoloading. - - * numbers.texi (Integer Basics): Copyedits. - (Float Basics): Consider IEEE floating point always available. - (Random Numbers): Document actual limits. - (Arithmetic Operations): Clarify division by zero. Don't mention - the machine-independence of negative division since it does not - happen in practice. - -2012-09-28 Leo Liu - - * files.texi (Files): Fix typo. - -2012-09-23 Chong Yidong - - * buffers.texi (Read Only Buffers): Document read-only-mode. - - * keymaps.texi (Alias Menu Items): Replace toggle-read-only with - read-only-mode. - - * backups.texi (Auto-Saving): Refer to Minor Mode Conventions for - calling conventions. - -2012-09-22 Chong Yidong - - * searching.texi (Replacing Match): Minor clarification. - -2012-09-22 Eli Zaretskii - - * edebug.texi (Instrumenting): Improve indexing. - - * os.texi (Idle Timers): Warn against reinvoking an idle timer - from within its own timer action. (Bug#12447) - -2012-09-22 Chong Yidong - - * frames.texi (Pop-Up Menus): Minor clarification (Bug#11148). - -2012-09-21 Glenn Morris - - * debugging.texi (Using Debugger): Fix typo. - -2012-09-18 Chong Yidong - - * display.texi (Faces): Discuss anonymous faces. - (Face Attributes): Tweak intro. - (Defining Faces): Move after the Face Attributes node. Copyedits. - (Displaying Faces): Describe role of inheritance. - - * customize.texi (Customization): Define customization more - carefully (Bug#11440). - (Common Keywords): Add xref to Constant Variables. - - * variables.texi (Defining Variables): Link to defcustom's node - instead of the higher-level Customization chapter. - -2012-09-11 Paul Eggert - - Simplify, document, and port floating-point (Bug#12381). - * numbers.texi (Float Basics, Arithmetic Operations, Math Functions): - Document that / and mod (with floating point arguments), along - with asin, acos, log, log10, expt and sqrt, return special values - instead of signaling exceptions. - (Float Basics): Document that logb operates on the absolute value - of its argument. - (Math Functions): Document that (log ARG BASE) also returns NaN if - BASE is negative. Document that (expt X Y) returns NaN if X is a - finite negative number and Y a finite non-integer. - -2012-09-09 Chong Yidong - - * lists.texi (Sets And Lists): Explain that the return value for - delete should be used, like for delq. - - * minibuf.texi (Yes-or-No Queries): Document recentering and - scrolling in y-or-n-p. Remove gratuitous example. - - * searching.texi (Search and Replace): Document window scrolling - entries in query-replace-map. - -2012-09-08 Chong Yidong - - * syntax.texi (Syntax Table Internals): Define "raw syntax - descriptor" terminology (Bug#12383). - (Syntax Descriptors): Mention raw syntax descriptors. - -2012-09-07 Chong Yidong - - * variables.texi (Creating Buffer-Local): Fix description of - local-variable-if-set-p (Bug#10713). - - * eval.texi (Intro Eval): Add index entry for sexp (Bug#12233). - - * windows.texi (Display Action Functions) - (Choosing Window Options): Remove obsolete variable - display-buffer-reuse-frames. - (Switching Buffers): Minor doc tweak for switch-to-buffer. - - * positions.texi (Narrowing): Document buffer-narrowed-p. - - * markers.texi (Moving Markers): Add xref to Point (Bug#7151). - - * syntax.texi (Low-Level Parsing): Add xref to Parser State - (Bug#12269). - -2012-09-04 Lars Ingebrigtsen - - * debugging.texi (Explicit Debug): Document `debug-on-message'. - -2012-09-02 Chong Yidong - - * windows.texi (Window Configurations): Recommend against using - save-window-excursion (Bug#12075). - - * control.texi (Catch and Throw): - * positions.texi (Excursions): Don't mention it. - -2012-09-01 Paul Eggert - - Better seed support for (random). - * numbers.texi (Random Numbers): Document new behavior of - the calls (random) and (random STRING). - -2012-08-21 Martin Rudalics - - * windows.texi (Window Point): Document recent changes in - window-point and set-window-point. - (Selecting Windows): Document recent change in select-window. - -2012-08-06 Eli Zaretskii - - * functions.texi (Closures): Put the main index entry for - "closures" here. (Bug#12138) - - * variables.texi (Lexical Binding): Disambiguate the index entry - for "closures". - -2012-08-05 Chong Yidong - - * display.texi (Defining Faces): Move documentation of - frame-background-mode to the Emacs manual (Bug#7774). - -2012-08-04 Chong Yidong - - * syntax.texi (Syntax Basics): Rearrange the text for clarity. - Fix description of syntax table inheritance. - (Syntax Table Functions): Don't refer to internal contents of - syntax table, since that is not explained yet. Copyedits. - (Standard Syntax Tables): Node deleted. - (Syntax Table Internals): Misc clarifications. Improve table - formatting. - - * keymaps.texi (Inheritance and Keymaps): - * text.texi (Sticky Properties): Tweak index entry. - -2012-07-28 Eli Zaretskii - - * nonascii.texi (Character Sets): Fix a typo. (Bug#12062) - -2012-07-25 Paul Eggert - - Prefer typical American spelling for "acknowledgment". - * intro.texi (Acknowledgments): Rename from Acknowledgements. - -2012-07-21 Eli Zaretskii - - * commands.texi (Special Events): Mention language-change event. - (Input Events, Interactive Codes): - * keymaps.texi (Key Sequences): Mention events that are - non-keyboard but also non-mouse events. - -2012-07-17 Chong Yidong - - * text.texi (Insertion): Document insert-char changes. - -2012-07-15 Leo Liu - - * display.texi (Fringe Bitmaps): Add exclamation-mark. - -2012-07-13 Chong Yidong - - * buffers.texi (Read Only Buffers): Document toggle-read-only - changes. Reword to account for the fact that read-only is - currently not supported in overlay properties. - -2012-07-07 Chong Yidong - - * loading.texi (Library Search): Index site-lisp directories. - -2012-07-06 Chong Yidong - - * intro.texi (A Sample Function Description): Fix incorrect - markup, undoing previous change. - (A Sample Variable Description): Minor clarifications and markup - improvements. - - * elisp.texi (Top): - * text.texi (Text): Fix menu order. - -2012-07-06 Richard Stallman - - * intro.texi (Evaluation Notation, A Sample Function Description) - (A Sample Variable Description): Improve/undo previous changes. - -2012-07-05 Glenn Morris - - * intro.texi (A Sample Function Description): Fix cross-refs. - -2012-07-05 Michael Witten (tiny change) - - * intro.texi (Evaluation Notation, A Sample Function Description) - (A Sample Variable Description, Version Info): Copy edits (bug#11862). - -2012-06-27 Chong Yidong - - * processes.texi (Asynchronous Processes, Input to Processes): - * internals.texi (Process Internals): Don't capitalize "pty". - -2012-06-24 Thien-Thi Nguyen - - * processes.texi (Asynchronous Processes): Make the pty vs pipe - discussion more prominent. - -2012-06-23 Eli Zaretskii - - * commands.texi (Misc Events): Document the language-change event. - -2012-06-22 Paul Eggert - - Support higher-resolution time stamps (Bug#9000). - * os.texi (Time of Day, Time Parsing, Processor Run Time, Idle Timers): - * processes.texi (System Processes): - Time stamp resolution is now picosecond, not microsecond. - -2012-06-21 Glenn Morris - - * Makefile.in: Rename infodir to buildinfodir throughout. (Bug#11737) - -2012-06-18 Stefan Monnier - - * functions.texi (Defining Functions): - * macros.texi (Defining Macros): Un-define the return value of `defun', - `defmacro' and `defalias'. - -2012-06-17 Chong Yidong - - * elisp.texi: Remove urlcolor setting. - -2012-06-17 Glenn Morris - - * display.texi (Face Attributes): Copyedits. Add a few cindex entries. - Overlining no longer behaves exactly like underlining. - -2012-06-16 Aurélien Aptel - - * display.texi (Face Attributes): - Document wave-style underline face attribute. - -2012-06-11 Chong Yidong - - * display.texi (ImageMagick Images): ImageMagick now supports the - :background property. - -2012-06-10 Dmitry Antipov - - * internals.texi (Garbage Collection): Typo fix. - -2012-06-09 Chong Yidong - - * text.texi (Special Properties): Clarify the meaning of a list of - faces in the `face' property. - - * display.texi (Face Remapping): Minor clarification. - -2012-06-08 Chong Yidong - - * display.texi (Face Attributes): Font family does not accept - wildcards. De-document obsolete :bold and :italic attributes. - (Defining Faces): Use new-style face spec format. - -2012-06-08 Dmitry Antipov - - * internals.texi (Garbage Collection): Document new - vector management code and vectorlike_header structure. - -2012-06-03 Chong Yidong - - * modes.texi (Mode Line Data): Use "mode line construct" - terminology for consistency. - -2012-05-27 Glenn Morris - - * abbrevs.texi, advice.texi, anti.texi, backups.texi: - * buffers.texi, commands.texi, compile.texi, control.texi: - * customize.texi, debugging.texi, display.texi, doclicense.texi: - * edebug.texi, elisp.texi, errors.texi, eval.texi, files.texi: - * frames.texi, functions.texi, gpl.texi, hash.texi, help.texi: - * hooks.texi, index.texi, internals.texi, intro.texi, keymaps.texi: - * lists.texi, loading.texi, macros.texi, maps.texi, markers.texi: - * minibuf.texi, modes.texi, nonascii.texi, numbers.texi: - * objects.texi, os.texi, package.texi, positions.texi: - * processes.texi, searching.texi, sequences.texi, streams.texi: - * strings.texi, symbols.texi, syntax.texi, text.texi, tips.texi: - * variables.texi, windows.texi: Nuke hand-written node pointers. - -2012-05-27 Chong Yidong - - * functions.texi (Obsolete Functions): - Fix doc for set-advertised-calling-convention. - - * modes.texi (Mode Help): Fix describe-mode. - - * display.texi (Face Functions): Fix define-obsolete-face-alias. - - * variables.texi (Variable Aliases): Fix make-obsolete-variable. - -2012-05-27 Martin Rudalics - - * commands.texi (Recursive Editing): recursive-edit is a command. - - * compile.texi (Docs and Compilation): - byte-compile-dynamic-docstrings is an option. - - * debugging.texi (Invoking the Debugger): debug is a command. - - * display.texi (Progress): progress-reporter-update and - progress-reporter-force-update have VALUE argument optional. - (Animated Images): Use non-@code{nil} instead of non-nil. - - * files.texi (Format Conversion Round-Trip): - Use non-@code{nil} instead of non-nil. - - * frames.texi (Creating Frames): make-frame is a command. - (Input Focus): select-frame is a command. - (Pointer Shape): void-text-area-pointer is an option. - - * help.texi (Describing Characters): read-kbd-macro is a command. - (Help Functions): describe-prefix-bindings is a command. - - * markers.texi (Creating Markers): Both arguments of copy-marker - are optional. - - * minibuf.texi (Reading File Names): Use @kbd instead of @code. - - * modes.texi (Mode Line Variables): mode-line-remote and - mode-line-client are not options. - (Imenu): imenu-add-to-menubar is a command. - (SMIE Indentation Helpers): Use non-@code{nil} instead of non-nil. - - * os.texi (Sound Output): play-sound-file is a command. - - * package.texi (Package Archives): Use @key{RET} instead of @kbd{RET}. - - * processes.texi (Signals to Processes): - Use @key{RET} instead of @code{RET}. - (Signals to Processes): signal-process is a command. - - * text.texi (Clickable Text): Use @key{RET} instead of @kbd{RET}. - (Base 64): base64-encode-string is not a command while - base64-decode-region is. - - * windows.texi (Switching Buffers): pop-to-buffer is a command. - -2012-05-12 Glenn Morris - - * Makefile.in (MKDIR_P): New, set by configure. - (mkinfodir): Use $MKDIR_P. - -2012-05-10 Glenn Morris - - * loading.texi (Loading Non-ASCII): Replace the obsolete "unibyte: t" - with "coding: raw-text". - Concept of multibyte sessions no longer exists. - - * files.texi (File Locks): Mention create-lockfiles option. - -2012-05-09 Glenn Morris - - * vol1.texi, vol2.texi: Remove files. - * elisp.texi: Add VOL1,2 conditionals equivalent to vol1,2.texi - * two-volume.make: Use elisp.texi as input rather than vol1,2.texi. - - * Makefile.in (clean, mostlyclean): Add some more vol1/2 items. - - * two-volume.make (emacsdir): New. - (tex): Add directory with emacsver.texi to TEXINPUTS. - - * minibuf.texi (Minibuffer History, Basic Completion): - Tweak page breaks. - - * internals.texi (Garbage Collection, Memory Usage) - (Writing Emacs Primitives): Tweak page breaks. - - * streams.texi (Output Variables): Improve page break. - - * edebug.texi (Edebug Display Update): Improve page break. - - * compile.texi (Disassembly): Condense the examples. - - * eval.texi, functions.texi, loading.texi, macros.texi: - Where possible, use example rather than smallexample. - - * symbols.texi: Where possible, use example rather than smallexample. - (Symbol Components): Fix typo. - (Other Plists): Tweak page break. - - * sequences.texi (Arrays): Tweak page breaks. - - * customize.texi: Where possible, use example rather than smallexample. - (Common Keywords, Variable Definitions, Applying Customizations) - (Custom Themes): Tweak page breaks. - - * control.texi: Where possible, use example rather than smallexample. - (Sequencing, Conditionals, Signaling Errors, Handling Errors): - Tweak page breaks. - -2012-05-08 Glenn Morris - - * two.el: Remove; unused since creation of two-volume.make. - - * vol1.texi, vol2.texi: No need to keep menus in these files. - -2012-05-05 Glenn Morris - - * objects.texi (Process Type, Overlay Type): Tweak page-breaks. - - * intro.texi (Caveats): Copyedit. - (Lisp History): Convert inforef to xref. - (Lisp History, Printing Notation, Version Info): Improve page-breaks. - - * text.texi (Auto Filling): Don't mention Emacs 19. - - * commands.texi (Event Input Misc): Don't mention unread-command-char. - * numbers.texi (Predicates on Numbers): Don't mention Emacs 18. - - * elisp.texi (DATE): Forgot to change the month in 2012-04-21 change. - - * lists.texi (List-related Predicates, List Variables): - Tweak page-breaks. - (Sets And Lists): Convert inforef to xref. - -2012-05-04 Glenn Morris - - * Makefile.in (INFO_EXT, INFO_OPTS): New, set by configure. - (info, infoclean): Use $INFO_EXT. - ($(infodir)/elisp$(INFO_EXT)): Use $INFO_EXT and $INFO_OPT. - * makefile.w32-in (INFO_EXT, INFO_OPTS): New. - (info, maintainer-clean): Use $INFO_EXT. - ($(infodir)/elisp$(INFO_EXT)): Use $INFO_EXT and $INFO_OPT. - -2012-05-04 Chong Yidong - - * os.texi (Timers): Use defopt for timer-max-repeats. - -2012-05-03 Paul Eggert - - * os.texi (Time of Day): Do not limit current-time-string - to years 1000..9999. - -2012-05-02 Chong Yidong - - * display.texi (Font Lookup): - * frames.texi (Pointer Shape): - * processes.texi (Subprocess Creation): Use defopt for options. - -2012-05-02 Glenn Morris - - * elisp.texi (@copying): - * intro.texi (Introduction): Only print VERSION in the TeX version. - -2012-05-02 Chong Yidong - - * text.texi (Change Hooks): Minor fix for after-change-functions. - -2012-05-02 Glenn Morris - - * package.texi (Packaging Basics): - * loading.texi (Autoload): - * files.texi (Magic File Names): - Reword to remove/reduce some overly long/short lines. - -2012-04-27 Glenn Morris - - * elisp.texi, vol1.texi, vol2.texi: Some fixes for detailed menu. - * modes.texi (Major Modes, Auto-Indentation): - * buffers.texi (Buffers): Some fixes for menu descriptions. - -2012-04-27 Stefan Monnier - * functions.texi (Simple Lambda, Argument List): - * eval.texi (Function Indirection): Avoid deprecated form. - -2012-04-27 Glenn Morris - - * book-spine.texi, elisp.texi, vol1.texi, vol2.texi: - Add "et al." to authors. - - * buffers.texi, commands.texi, compile.texi, control.texi: - * customize.texi, display.texi, eval.texi, files.texi, frames.texi: - * hash.texi, help.texi, intro.texi, keymaps.texi, lists.texi: - * modes.texi, numbers.texi, objects.texi, streams.texi: - * symbols.texi, syntax.texi, text.texi, tips.texi, variables.texi: - Use Texinfo recommended convention for quotes+punctuation. - -2012-04-27 Chong Yidong - - * keymaps.texi (Scanning Keymaps): Fix description of NO-REMAP arg - to where-is-internal (Bug#10872). - -2012-04-27 Glenn Morris - - * macros.texi (Indenting Macros): Fix typo. - - * windows.texi (Basic Windows, Windows and Frames, Window Sizes) - (Resizing Windows, Deleting Windows, Selecting Windows) - (Choosing Window Options, Horizontal Scrolling) - (Cyclic Window Ordering, Window History, Dedicated Windows) - (Quitting Windows, Window Configurations, Textual Scrolling) - (Coordinates and Windows, Window Configurations) - (Window Parameters, Window Hooks): Copyedits. - (Splitting Windows, Deleting Windows): - Fix ignore-window-parameters logic. - (Selecting Windows, Choosing Window Options): Markup fixes. - (Window Start and End): Remove pointless example. - Remove cross-reference to deleted count-lines content. - (Textual Scrolling): Mention recenter-redisplay, recenter-top-bottom, - and recenter-positions. Remove recenter example. - - * elisp.texi, vol1.texi, vol2.texi: Bump VERSION and DATE. - - * minibuf.texi (Intro to Minibuffers): - Tweak discussion of resizing minibuffer window. - -2012-04-26 Glenn Morris - - * elisp-covers.texi, front-cover-1.texi: Remove files. - - * tindex.pl: Remove file. - - * makefile.w32-in (srcs): - * Makefile.in (srcs): Remove back.texi (which is unused). - -2012-04-24 Michael Albinus - - * os.texi (Notifications): Extend possible notification hints. - Add notifications-get-capabilities. - -2012-04-20 Chong Yidong - - * processes.texi (Asynchronous Processes): Mention nil argument to - start-process. - -2012-04-20 Glenn Morris - - * minibuf.texi (Basic Completion): No need to describe obarrays here. - Don't mention obsolete `nospace' argument of all-completions. - (Minibuffer Completion, Completion Commands, Reading File Names) - (Completion Variables): Copyedits. - (Completion Commands): Mention parent keymaps. - Remove obsolete minibuffer-local-filename-must-match-map. - (High-Level Completion): Remove read-variable's almost - word-for-word duplication of read-command. - * elisp.texi, vol1.texi, vol2.texi, minibuf.texi (Completion): - Update "High-Level Completion" description. - - * minibuf.texi (Minibuffers): - * elisp.texi, vol1.texi, vol2.texi: Fix minibuffer subsection order. - - * minibuf.texi: Standardize metasyntactic variables ("history", etc). - Use Texinfo-recommended form of quote+punctuation. - (Intro to Minibuffers): First minibuffer is #1, not #0. - Mention minibuffer-inactive-mode. - (Text from Minibuffer): Copyedits. - (Minibuffer History, Programmed Completion): Fix @var usage. - (Object from Minibuffer): Remove overly pedantic para. - (Minibuffer History): Copyedits. Add face-name-history. - (Initial Input, Yes-or-No Queries, Multiple Queries) - (Minibuffer Windows, Minibuffer Misc): Copyedits. - (Yes-or-No Queries): Tweak example. - (Minibuffer Commands): Add next-complete-history-element. - (Minibuffer Misc): Mention minibuffer-message-timeout, and - minibuffer-inactive-mode. - - * processes.texi (Serial Ports, Byte Packing, Bindat Spec) - (Bindat Functions): Copyedits. - -2012-04-20 Christopher Schmidt - - * files.texi (Saving Buffers): Document `visit and `visit-save' - values of require-final-newline. - -2012-04-20 Glenn Morris - - * processes.texi (Output from Processes, Filter Functions): - Mention waiting-for-user-input-p. - (Sentinels, Query Before Exit, System Processes, Transaction Queues) - (Network Servers, Datagrams, Network Processes, Network Options) - (Network Feature Testing, Serial Ports): Copyedits. - (Network): Add encrypted network overview paragraph. - Cross-reference the Emacs-GnuTLS manual. Use @acronym. - -2012-04-20 Chong Yidong - - * help.texi (Keys in Documentation): Mention :advertised-binding. - - * keymaps.texi (Menu Bar): Move most of the :advertised-binding - description to help.texi. - -2012-04-20 Glenn Morris - - * processes.texi (Process Information, Input to Processes) - (Signals to Processes, Output from Processes, Process Buffers) - (Filter Functions, Decoding Output): Copyedits. - (Accepting Output): Discourage use of `millisec' argument. - -2012-04-15 Glenn Morris - - * processes.texi (Processes, Subprocess Creation, Shell Arguments) - (Synchronous Processes, Asynchronous Processes, Deleting Processes): - Copyedits. - (Subprocess Creation): Discourage modifying exec-path directly. - (Synchronous Processes, Asynchronous Processes): - Update some example output. - (Process Information): Fix typo. - (Bindat Spec): Use Texinfo-recommended form of quote+punctuation. - -2012-04-15 Glenn Morris - - * anti.texi (Antinews): Copyedits. Don't @dfn anything here. - open-network-stream does exist in Emacs 23, but is simpler. - -2012-04-15 Chong Yidong - - * customize.texi (Custom Themes): Also document load-theme etc. - -2012-04-14 Chong Yidong - - * customize.texi (Applying Customizations, Custom Themes): New nodes. - - * display.texi (Defining Faces): Reference custom-set-faces. - - * modes.texi (Defining Minor Modes, Defining Minor Modes): - * os.texi (Startup Summary): Copyedits. - -2012-04-14 Glenn Morris - - * loading.texi (Loading Non-ASCII): "unibyte:" can also be at the end. - - * strings.texi (Case Tables): - * objects.texi (General Escape Syntax): - * keymaps.texi (Key Sequences): Use @acronym with "ASCII". - - * buffers.texi, compile.texi, customize.texi, debugging.texi: - * display.texi, edebug.texi, eval.texi, help.texi, intro.texi: - * keymaps.texi, minibuf.texi, modes.texi, os.texi, processes.texi: - * text.texi: Use @file for buffers, per the Texinfo manual. - - * compile.texi (Compiler Errors): Add missing space in buffer name. - -2012-04-14 Chong Yidong - - * processes.texi (Query Before Exit): Remove obsolete function - process-kill-without-query (Bug#11190). - -2012-04-14 Glenn Morris - - * files.texi, frames.texi, loading.texi, os.texi, processes.texi: - Use @env for environment variables. - - * Makefile.in: Replace non-portable use of $< in ordinary rules. - -2012-04-12 Jari Aalto - - * processes.texi (Synchronous Processes): - Mention `default-directory' (bug#7515). - -2012-04-09 Chong Yidong - - * customize.texi (Variable Definitions): Remove user-variable-p. - - * commands.texi (Interactive Codes): - * help.texi (Accessing Documentation): - * minibuf.texi (High-Level Completion): Callers changed. - -2012-04-06 Chong Yidong - - * minibuf.texi (Programmed Completion): Document metadata method. - (Completion Variables): Document completion-category-overrides. - -2012-04-05 Chong Yidong - - * anti.texi (Antinews): Rewrite for Emacs 23. - -2012-04-04 Chong Yidong - - * minibuf.texi (Programmed Completion): Remove obsolete variable - completion-annotate-function. - (Completion Variables): Rename from Completion Styles. - Document completion-extra-properties. Document completion-styles-alist - change. - (Reading File Names): minibuffer-local-filename-must-match-map is - not used anymore. - (Minibuffer Completion): Document completing-read-function. - (Completion in Buffers): completion-at-point-functions can return - properties recognized in completion-extra-properties. - - * display.texi (Delayed Warnings): New node. - - * os.texi (Notifications): Copyedits. - -2012-04-04 Glenn Morris - - * os.texi (Notifications): Copyedits. - -2012-04-03 Michael Albinus - - * os.texi (Terminal-Specific): Fix typo. - (Notifications): New section. - - * elisp.texi (Top): - * vol1.texi (Top): - * vol2.texi (Top): Add "Notifications" and "Dynamic Libraries" - menu entries. - -2012-04-01 Chong Yidong - - * files.texi (Kinds of Files): file-subdir-of-p renamed to - file-in-directory-p. - -2012-03-31 Glenn Morris - - * edebug.texi (Instrumenting Macro Calls): - Mention defining macros at instrumentation time. - (Edebug Options): Mention edebug-unwrap-results. - -2012-03-31 Eli Zaretskii - - * text.texi (Special Properties): Clarify the description of the - effect of integer values of the 'cursor' property on cursor - position. See the discussions in bug#11068 for more details and - context. - -2012-03-31 Glenn Morris - - * edebug.texi (Edebug Eval, Specification List, Edebug Options): - Copyedits. - -2012-03-30 Chong Yidong - - * display.texi (Image Formats): Add imagemagick type. - (Image Descriptors): Mention how they are used. - (ImageMagick Images): Clarify role of imagemagick-register-types. - (Character Display): Don't mention glyph tables. - (Display Tables): Use make-glyph-code in example. - (Glyphs): Avoid "simple glyph code" terminology. Note that glyph - tables are semi-obsolete. De-document create-glyph. - (Glyphless Chars): Note that display tables override this. - (Bidirectional Display): Copyedits. Introduce "bidirectional - reordering" terminology, and use it. - -2012-03-30 Glenn Morris - - * edebug.texi (Jumping): Give name of `i' binding. - -2012-03-28 Glenn Morris - - * searching.texi (Regular Expressions, Regexp Special) - (Regexp Backslash, Regexp Example, Regexp Functions, Regexp Search) - (Simple Match Data, Saving Match Data, Standard Regexps): Copyedits. - (Regexp Special): Mention collation. - Clarify char classes with an example. - (Regexp Functions): Mention regexp-opt is not guaranteed. - Mention regexp-opt-charset. - (Regexp Search): Recommend against looking-back. - (Search and Replace): Use Texinfo recommended quote convention. - Add more query-replace-map items. List multi-query-replace-map items. - -2012-03-27 Martin Rudalics - - * windows.texi (Window History): Describe new option - switch-to-visible-buffer. - -2012-03-27 Glenn Morris - - * searching.texi (String Search): Add xref to Emacs manual. - Copyedits. Mention the function word-search-regexp. - (Searching and Case): Add xref to Emacs manual. Copyedits. - - * processes.texi (Network Servers): Standardize apostrophe usage. - - * os.texi (System Environment): Copyedits. Remove some examples - that do not seem useful. Mention setenv third arg. - tty-erase-char does not seem to be nil under a window-system. - (User Identification): Copyedits. - Remove some examples that do not seem useful. - -2012-03-26 Glenn Morris - - * os.texi (Startup Summary): Copyedits. Fix startup screen logic. - (Init File): Copyedits. - (Command-Line Arguments): Copyedits. Do not mention argv alias. - (Killing Emacs): Copyedits. - (Suspending Emacs): Copyedits. Mention not very relevant with GUIs. - Shorten the example, use more standard shell prompts. - -2012-03-25 Chong Yidong - - * display.texi (Fringes): Note that fringes are shown on graphical - displays only. - (Fringe Size/Pos, Fringe Bitmaps, Making Buttons): Clarifications. - (Replacing Specs): Clarify example. - (Manipulating Buttons): Note that button-at can return a marker. - (Buttons): Minor rewrite. - (Character Display): New node. Consolidate all character display - related nodes into its subsections. - (Usual Display): Character 127 is also affected by ctl-arrow. - (Display Tables): Improve example. - -2012-03-22 Glenn Morris - - * strings.texi (Text Comparison): Mention string-prefix-p. - -2012-03-21 Chong Yidong - - * display.texi (The Echo Area): Add xref to Output Streams. - (Displaying Messages): Improve doc of message. - (Echo Area Customization, Invisible Text): Copyedits. - (Invisible Text): Mention that spec comparison is done with eq. - (Width): Improve doc of char-width. - (Faces): Recommend using symbol instead of string for face name. - Minor clarifications. - (Defining Faces): Copyedits. Update face example. - (Attribute Functions): Mark set-face-foreground etc as commands. - (Face Remapping): Mention text-scale-adjust. - Clarify face-remapping-alist and related docs. - (Face Functions): Don't document make-face or copy-face. - -2012-03-20 Chong Yidong - - * display.texi (Forcing Redisplay): Various rewrites to reflect - new value of redisplay-dont-pause. - (Truncation): Copyedits. - -2012-03-20 Glenn Morris - - * os.texi (Startup Summary): Don't mention initial-buffer-choice = t. - Add summary table of some relevant command-line options. - -2012-03-18 Chong Yidong - - * internals.texi (Building Emacs, Garbage Collection): Copyedits. - (Writing Emacs Primitives): Re-organize discussion of functions - with variable Lisp arguments are handled. Delete an obsolete - remark, previously tagged as FIXME. - - * os.texi (Idle Timers): Minor clarification. - (Idle Timers): Link to Time of Day for description of time list. - -2012-03-18 Glenn Morris - - * os.texi (System Interface): Flow control was removed. - (Startup Summary): General update. - (Init File): Don't mention compiling it. - -2012-03-17 Chong Yidong - - * os.texi (Startup Summary): Mention package loading. - (Init File): Don't refer to .emacs in section title. Copyedits. - (Terminal-Specific): Give a realistic example. - (Command-Line Arguments): Reference Entering Emacs instead of - repeating the spiel about not restarting Emacs. - (Time of Day): Discuss time representation at beginning of node. - (Sound Output): Copyedits. - - * package.texi (Packaging Basics): Document package-initialize. - -2012-03-17 Eli Zaretskii - - * frames.texi (Initial Parameters): Add an index entry for - minibuffer-only frame. - -2012-03-16 Glenn Morris - - * modes.texi (Major Mode Conventions): Mention the strange - relationship between View mode and special modes. (Bug#10650) - -2012-03-11 Chong Yidong - - * windows.texi (Window Configurations): save-window-excursion is - now a macro. - - * display.texi (Temporary Displays): with-output-to-temp-buffer is - now a macro. - - * text.texi (Fields): Minor copyedit. - -2012-03-10 Eli Zaretskii - - * strings.texi (String Basics): - * sequences.texi (Sequence Functions): Mention that `length' is - not appropriate for computing the string width on display; add a - cross-reference to the description of `string-width'. (Bug#10978) - - * eval.texi (Autoloading): Minor change of wording. - -2012-03-10 Chong Yidong - - * loading.texi (Autoload): Explicitly state which forms are - processed specially (Bug#7783). - - * keymaps.texi (Mouse Menus): Describe non-toolkit behavior as the - non-default situation. Describe one-submenu exception (Bug#7695). - - * nonascii.texi (Character Properties): Copyedits. - -2012-03-08 Chong Yidong - - * text.texi (Mode-Specific Indent): Document new behavior of - indent-for-tab-command. Document tab-always-indent. - (Special Properties): Copyedits. - (Checksum/Hash): Improve secure-hash doc. Do not recommend MD5. - (Parsing HTML/XML): Rename from Parsing HTML. Update doc of - libxml-parse-html-region. - -2012-03-07 Glenn Morris - - * markers.texi (The Region): Briefly mention use-empty-active-region - and region-active-p. - (Overview of Markers): Reword garbage collection, add cross-ref. - (The Mark): Tiny clarification re command loop and activate-mark-hook. - -2012-03-07 Chong Yidong - - * text.texi (Buffer Contents): Don't duplicate explanation of - region arguments from Text node. Put doc of obsolete var - buffer-substring-filters back, since it is referred to. - (Low-Level Kill Ring): Yank now uses clipboard instead of primary - selection by default. - - * markers.texi (The Mark): Fix typo. - (The Region): Copyedits. - -2012-03-07 Glenn Morris - - * markers.texi (Overview of Markers): Copyedits. - (Creating Markers): Update approximate example buffer size. - (The Mark): Don't mention uninteresting return values. - -2012-03-05 Chong Yidong - - * positions.texi (Text Lines): Document count-words. - -2012-03-04 Chong Yidong - - * frames.texi (Frames): Remove little-used "terminal frame" and - "window frame" terminology. - (Frame Parameters, Font and Color Parameters, Initial Parameters) - (Size and Position, Visibility of Frames): Callers changed. - (Frames): Clarify which terminals in framep are graphical. - (Initial Parameters): --geometry is not the only option which adds - to initial-frame-alist. - (Position Parameters): Note that icon-left and icon-top are for - old window managers only. - (Size Parameters): Sizes are in characters even on graphical - displays. - (Management Parameters): Note that window-id and outer-window-id - can't really be changed, and that auto-raise isn't always obeyed. - (Cursor Parameters): Document cursor-type explicitly. - (Size and Position): The aliases set-screen-height and - set-screen-width have been deleted. - (Visibility of Frames): Mention "minimization". - - * os.texi (Startup Summary): Minor clarifications. - (Startup Summary, Suspending Emacs): Standardize on "text - terminal" terminology. - - * windows.texi (Basic Windows, Coordinates and Windows) - (Coordinates and Windows): - * display.texi (Refresh Screen, Line Height, Face Attributes) - (Overlay Arrow, Beeping, Glyphless Chars): Likewise. - -2012-03-04 Glenn Morris - - * abbrevs.texi: Small copyedits throughout. - (Abbrev Mode): Remove this section, folding it into the top-level. - (Abbrev Tables): Don't mention irrelevant return values. - (Abbrev Expansion): Add cross-ref for wrapper hooks. - (Standard Abbrev Tables): Emacs Lisp mode now has its own table. - (Abbrev Table Properties): Update nil :regexp description. - -2012-03-03 Glenn Morris - - * internals.texi: Change @appendix section commands to @section. - (Building Emacs): Say less about CANNOT_DUMP platforms. - Replace deleted eval-at-startup with custom-initialize-delay. - (Pure Storage): Small changes. - (Memory Usage): Copyedit. - (Writing Emacs Primitives): Update Fcoordinates_in_window_p and For - example definitions. Give examples of things with non-nil - interactive args. Mention eval_sub. Remove old info about - strings and GCPRO. Mention cus-start.el. - (Buffer Internals, Window Internals, Process Internals): - Misc small updates and fixes for fields. - - * tips.texi: Copyedits. - (Coding Conventions): Mention autoloads. - Combine partially duplicated macro items. Fix xref. - Refer to Library Headers for copyright notice. - (Programming Tips): edit-options is long-obsolete. - (Compilation Tips): Mention loading bytecomp for byte-compile props. - (Warning Tips): Mention declare-function. - (Documentation Tips): Remove old info. - (Comment Tips): Mention comment-dwim, not indent-for-comment. - (Library Headers): General update. - -2012-03-02 Glenn Morris - - * backups.texi (Reverting): Un-duplicate revert-buffer-in-progress-p, - and relocate entry. Mention buffer-stale-function. - - * elisp.texi, vol1.texi, vol2.texi: Standardize some menu entries. - - * hooks.texi (Standard Hooks): General update. - Put related hooks together. Add and remove items. - * commands.texi (Keyboard Macros): Remove cross-ref to Standard Hooks. - * modes.texi (Hooks): Tweak cross-ref description. - -2012-03-01 Michael Albinus - - * files.texi (Kinds of Files): The return value of file-equal-p is - unspecified, if FILE1 or FILE2 does not exist. - -2012-03-01 Glenn Morris - - * hooks.texi (Standard Hooks): Remove mode-specific hooks. - - * maps.texi (Standard Keymaps): General update. - Remove mode-specific maps, talk about the more general keymaps. - * help.texi (Help Functions): Add vindex for Helper-help-map. - * keymaps.texi (Active Keymaps): Minor rephrasing. - -2012-02-29 Glenn Morris - - * elisp.texi, vol1.texi, vol2.texi: Use "" quotes in menus. - -2012-02-28 Thierry Volpiatto - - * files.texi (Kinds of Files): Rename files-equal-p to file-equal-p. - Update changed behavior of file-subdir-of-p. - -2012-02-28 Glenn Morris - - * advice.texi, anti.texi, display.texi, elisp.texi: - * processes.texi, variables.texi, vol1.texi, vol2.texi: - Standardize possessive apostrophe usage. - - * locals.texi: Remove file. - * elisp.texi, vol1.texi, vol2.texi: Don't include locals.texi. - Remove menu entry. - * errors.texi, maps.texi: Adjust node pointers. - * internals.texi (Buffer Internals): Remove cross-refs to locals.texi. - * makefile.w32-in (srcs): - * Makefile.in (srcs): Remove locals.texi. - - * frames.texi (Mouse Position): Fix cross-ref. - -2012-02-27 Chong Yidong - - * buffers.texi (Creating Buffers): Clarify that - generate-new-buffer uses generate-new-buffer-names. - (Killing Buffers): Remove bogus example duplicating buffer-live-p. - - * files.texi (Directory Names): Index entry for file name abbreviations. - (Relative File Names, File Name Expansion): Refer to it. - (Locating Files): Move locate-user-emacs-file documentation to - Standard File Names. - (Standard File Names): Add locate-user-emacs-file; update examples. - -2012-02-26 Michael Albinus - - * files.texi (Magic File Names): Add files-equal-p and file-subdir-of-p. - -2012-02-26 Chong Yidong - - * files.texi (Kinds of Files): Improve documentation of - files-equal-p and file-subdir-of-p. - -2012-02-26 Glenn Morris - - * intro.texi (Acknowledgements): Small changes. - -2012-02-25 Glenn Morris - - * errors.texi: Don't try to list _all_ the error symbols. - Add circular-list, cl-assertion-failed, compression-error. - * elisp.texi, vol1.texi, vol2.texi: - * control.texi (Error Symbols): Tweak "Standard Errors" description. - -2012-02-25 Thierry Volpiatto - - * files.texi (files-equal-p, file-subdir-of-p): New, - add initial documentation. - -2012-02-25 Chong Yidong - - * files.texi (File Attributes): Document file-selinux-context. - (Changing Files): Link to it. - (Changing Files): Document set-file-selinux-context. - - * backups.texi (Making Backups): Return value of backup-buffer is - changed. Mention default value of backup-directory-alist. - (Rename or Copy): Note that backup-by-copying-when-mismatch is t. - (Auto-Saving): New minor mode behavior for auto-save-mode. - (Reverting): Add defvar for revert-buffer-in-progress-p. - - * searching.texi (Regexp Backslash): Add index entry (Bug#10869). - -2012-02-24 Glenn Morris - - * errors.texi (Standard Errors): Mention dbus-error. - For arith-error sub-classes, just use one cross-ref. - -2012-02-23 Alan Mackenzie - - * modes.texi (Defining Minor Modes): Document the new keyword - :after-hook. - -2012-02-21 Chong Yidong - - * files.texi (Files): Mention magic file names as arguments. - (Reading from Files): Copyedits. - (File Attributes): Mention how to change file modes. - (Changing Files): Use standard "file permissions" terminology. - Add xref to File Attributes node. - (Locating Files): Document locate-user-emacs-file. - (Unique File Names): Recommend against using make-temp-name. - -2012-02-19 Chong Yidong - - * help.texi (Documentation, Documentation Basics, Help Functions): - Minor clarifications. - (Accessing Documentation): Clarify what documentation-property is - for. Add xref to Keys in Documentation. - - * tips.texi (Documentation Tips): Don't recommend using * in - docstrings. - - * macros.texi (Defining Macros): - * modes.texi (Derived Modes): Say "documentation string" instead - of docstring. - -2012-02-18 Chong Yidong - - * modes.texi (Tabulated List Mode): New node. - (Basic Major Modes): Add xref to it. - - * processes.texi (Process Information): Mention Process Menu mode. - -2012-02-17 Chong Yidong - - * syntax.texi (Motion via Parsing): Doc fix for scan-lists. - -2012-02-17 Glenn Morris - - * hooks.texi (Standard Hooks): Fix cross-ref to Emacs manual. - -2012-02-16 Chong Yidong - - * syntax.texi (Syntax Tables, Syntax Descriptors) - (Syntax Table Functions): Copyedits. - (Syntax Basics): Don't repeat the material in the preceding node. - (Syntax Class Table): Use a table. - (Syntax Properties): Document syntax-propertize-function and - syntax-propertize-extend-region-functions. - (Motion via Parsing): Clarify scan-lists. Fix indentation. - (Parser State): Update for the new "c" comment style. - Fix description of item 7 (comment style). - - * modes.texi (Minor Modes): Update how mode commands should treat - arguments now. - (Mode Line Basics): Clarify force-mode-line-update. - (Mode Line Top): Note that the example is not realistic. - (Mode Line Variables, Mode Line Data, %-Constructs, Header Lines) - (Emulating Mode Line): Use "mode line" instead of "mode-line", and - "mode line construct" instead of "mode line specification". - (Syntactic Font Lock): Remove mention of obsolete variable - font-lock-syntactic-keywords. - (Setting Syntax Properties): Node deleted. - (Font Lock Mode): Note that Font Lock mode is a minor mode. - (Font Lock Basics): Note that syntactic fontification falls back - on `syntax-table'. - (Search-based Fontification): Emphasize that font-lock-keywords - should not be set directly. - (Faces for Font Lock): Avoid some confusing terminology. - (Syntactic Font Lock): Minor clarifications. Add xref to - Syntactic Font Lock node. - -2012-02-15 Chong Yidong - - * minibuf.texi (Basic Completion): Define "completion table". - Move completion-in-region to Completion in Buffers node. - (Completion Commands): Use "completion table" terminology. - (Completion in Buffers): New node. - - * modes.texi (Hooks): add-hook can be used for abnormal hooks too. - (Setting Hooks): Update minor mode usage example. - (Major Mode Conventions): Note that completion-at-point-functions - should be altered locally. Add xref to Completion in Buffers. - Remove duplicate tip about auto-mode-alist. - (Minor Modes): Rewrite introduction. - (Minor Mode Conventions): Copyedits. Don't recommend - variable-only minor modes since few minor modes are like that. - -2012-02-15 Glenn Morris - - * processes.texi (Network): Document open-network-stream :parameters. - -2012-02-14 Chong Yidong - - * keymaps.texi (Format of Keymaps): The CACHE component of keymaps - was removed on 2009-09-10. Update lisp-mode-map example. - (Inheritance and Keymaps): Minor clarification. - (Searching Keymaps): Remove out-of-place enumeration. - (Key Lookup): Remove unnecessary example (one was already given in - Format of Keymaps). - (Changing Key Bindings): Update suppress-keymap example. - (Menu Bar, Tool Bar): Copyedits. - (Tool Bar): Update tool-bar-map example. - -2012-02-12 Chong Yidong - - * debugging.texi (Debugger Commands): Continuing is now allowed - for errors. - -2012-02-11 Chong Yidong - - * display.texi (Fringe Indicators): Add xref to Fringe Bitmaps. - Move the list of standard bitmaps there. - (Fringe Cursors): Rewrite for clarity. - (Fringe Bitmaps): Consolidate the list of standard bitmaps here. - - * commands.texi (Command Overview): Mention read-key. - (Using Interactive, Interactive Call): Minor clarifications. - (Function Keys, Click Events): Avoid "input stream" terminology. - (Click Events): Add xref to Window Sizes and Accessing Mouse. - Clarify column and row components. - (Accessing Mouse): Add xref to Click Events. Minor fixes. - (Special Events): Copyedits. - - * streams.texi (Input Streams): De-document get-file-char. - (Output Variables): Don't refer to old backquote syntax. - - * debugging.texi (Debugging): Copyedits. Describe testcover, ERT. - (Error Debugging): Note that debug-ignored-errors overrides list - values of debug-on-error too. Add xref to Signaling Errors. - Note that debug-on-signal is not customizable. - Mention condition-case-unless-debug. - (Compilation Errors): Node deleted. - - * compile.texi (Compiler Errors): Move a paragraph here from - deleted node Compilation Errors. - -2012-02-10 Leo Liu - - * control.texi (Handling Errors): Change condition-case-no-debug - to condition-case-unless-debug. - -2012-02-10 Chong Yidong - - * advice.texi (Defining Advice): Clarify ad-unadvise. - (Activation of Advice): Specifying the ACTIVATE flag in defadvice - is not abnormal. - (Advising Primitives): Node deleted; ad-define-subr-args has been - removed. - - * compile.texi (Speed of Byte-Code): Use float-time in example. - (Compilation Functions): Note that the log uses Compilation mode. - Don't discuss the contents of byte-code function object here. - (Compilation Functions): De-document internal function byte-code. - (Docs and Compilation): Minor clarifications. - - * objects.texi (Byte-Code Type): Add xref to Byte-Code Function - Objects. - -2012-02-10 Glenn Morris - - * text.texi (Checksum/Hash): Rename node from MD5 Checksum. - Mention secure-hash. - * elisp.texi, vol1.texi, vol2.texi: Update menu entry. - -2012-02-10 Chong Yidong - - * loading.texi (Loading): Don't emphasize "library" terminology. - (Library Search): load-path is not a user option. Mention role of - -L option and packages. Improve examples. - (Loading Non-ASCII): Don't mention unibyte Emacs, which is - obsolete. - (Autoload): Minor clarifications. - -2012-02-10 Glenn Morris - - * files.texi (Magic File Names): Tweak remote-file-name-inhibit-cache. - - * modes.texi (Basic Major Modes): Mention tabulated-list-mode. - -2012-02-08 Glenn Morris - - * loading.texi (Named Features): Update the require example. - -2012-02-07 Glenn Morris - - * modes.texi (Defining Minor Modes): - Expand on args of defined minor modes. - -2012-02-07 Chong Yidong - - * variables.texi (Creating Buffer-Local): Minor clarification - to buffer-local-variables doc (Bug#10715). - -2012-02-07 Glenn Morris - - * display.texi (ImageMagick Images): General update. - Move most details of imagemagick-render-type to the variable's doc. - -2012-02-06 Glenn Morris - - * keymaps.texi (Tool Bar): Mention separators. - (Inheritance and Keymaps): - Mention make-composed-keymap and multiple inheritance. - - * modes.texi (Running Hooks): Mention run-hook-wrapped. - - * control.texi (Handling Errors): - Mention condition-case-no-debug and with-demoted-errors. - -2012-02-05 Chong Yidong - - * customize.texi (Common Keywords): Minor clarifications. - Document custom-unlispify-remove-prefixes. - (Variable Definitions): Backquotes in defcustom seem to work fine - now. Various other copyedits. - (Simple Types): Copyedits. Document color selector. - (Composite Types): Copyedits. - (Splicing into Lists): Clarifications. - - * eval.texi (Backquote): Move from macros.texi. - - * macros.texi (Expansion): Minor clarification. - (Backquote): Move node to eval.texi. - (Defining Macros): Move an example from Backquote node. - (Argument Evaluation): No need to mention Pascal. - (Indenting Macros): Add xref to Defining Macros. - -2012-02-05 Glenn Morris - - * debugging.texi (Error Debugging): Mention debug-on-event default. - -2012-02-04 Glenn Morris - - * backups.texi (Reverting): Mention revert-buffer-in-progress-p. - - * debugging.texi (Error Debugging): Mention debug-on-event. - * commands.texi (Misc Events): Mention sigusr1,2 and debugging. - - * modes.texi (Running Hooks): Try to clarify with-wrapper-hook. - - * text.texi (Buffer Contents): - Update filter-buffer-substring description. - -2012-02-04 Chong Yidong - - * functions.texi (What Is a Function): Add closures. - Mention "return value" terminology. Add xref for command-execute. - Remove unused "keystroke command" terminology. - (Lambda Expressions): Give a different example than in the - following subsection. Add xref to Anonymous Functions. - (Function Documentation): Remove gratuitous markup. - (Function Names): Move introductory text to `What Is a Function'. - (Defining Functions): Fix defun argument spec. - (Anonymous Functions): Document lambda macro explicitly. - Mention effects on lexical binding. - (Function Cells): Downplay direct usage of fset. - (Closures): New node. - (Inline Functions): Remove "open-code" terminology. - (Declaring Functions): Minor tweak; .m is not C code. - - * variables.texi (Variables): Don't refer to "global value". - (Local Variables, Void Variables): Copyedits. - (Lexical Binding): Minor clarification of example. - (File Local Variables): Mention :safe and :risky defcustom args. - (Lexical Binding): Add xref to Closures node. - -2012-02-04 Glenn Morris - - * minibuf.texi (High-Level Completion): Updates for read-color. - -2012-02-03 Glenn Morris - - * display.texi (GIF Images): Mention animation. - Remove commented-out old example of animation. - (Animated Images): New subsection. - * elisp.texi (Top): - * vol1.texi (Top): - * vol2.texi (Top): Add Animated Images menu entry. - - * display.texi (Image Formats): Remove oddly specific information - on versions of image libraries. - (GIF Images, TIFF Images): Minor rephrasing. - -2012-02-02 Glenn Morris - - * processes.texi (Synchronous Processes): - Mention call-process's :file gets overwritten. - - * commands.texi (Reading One Event): - * help.texi (Help Functions): Document read-char-choice. - - * hooks.texi (Standard Hooks): - * modes.texi (Keymaps and Minor Modes): - * text.texi (Commands for Insertion): Document post-self-insert-hook. - - * hooks.texi (Standard Hooks): Add prog-mode-hook. - - * hooks.texi (Standard Hooks): - * modes.texi (Major Mode Conventions, Mode Hooks): - Document change-major-mode-after-body-hook. - -2012-02-01 Glenn Morris - - * modes.texi (Defining Minor Modes): - Mention disabling global minor modes on a per-major-mode basis. - -2012-01-31 Chong Yidong - - * syntax.texi (Parsing Expressions): Clarify intro (Bug#10657). - (Parser State): Remove unnecessary statement (Bug#10661). - - * eval.texi (Intro Eval): Add footnote about "sexp" terminology. - -2012-01-31 Glenn Morris - - * modes.texi (Defining Minor Modes): - Document define-minor-mode's new :variable keyword. - -2012-01-29 Chong Yidong - - * syntax.texi (Syntax Class Table): Tweak description of newline - char syntax (Bug#9619). - - * numbers.texi (Predicates on Numbers): Fix wholenump/natnump - description (Bug#10189). - -2012-01-29 Glenn Morris - - * files.texi (Changing Files): Document SELinux support. - - * windows.texi (Window Sizes): Fix typo. - -2012-01-28 Chong Yidong - - * display.texi (Fringe Indicators): Clarify fringe-indicator-alist - doc (Bug#8568). - - * frames.texi (Input Focus): Add NORECORD arg to - select-frame-set-input-focus. Clarify its role in select-frame. - - * text.texi (Transposition): We don't use transpose-region as an - internal subroutine (Bug#3249). - - * modes.texi (Example Major Modes): Update Lisp example code to - current sources. Delete the old non-derived-major-mode example, - which has diverged badly from current sources. - -2012-01-27 Glenn Morris - - * makefile.w32-in (texinputdir): Fix (presumed) typo. - (VERSION, manual): Remove, unused. - -2012-01-27 Chong Yidong - - * commands.texi (Command Overview): Minor clarification (Bug#10384). - -2012-01-26 Chong Yidong - - * searching.texi (String Search): Document negative repeat count - (Bug#10507). - -2012-01-26 Glenn Morris - - * variables.texi (Using Lexical Binding): - Mention that lexical-binding should be set in the first line. - -2012-01-26 Lars Ingebrigtsen - - * macros.texi (Defining Macros): Don't claim that `declare' only - affects Edebug and indentation. - -2012-01-25 Lars Ingebrigtsen - - * macros.texi (Defining Macros): Slight `declare' fixup. - -2012-01-25 Glenn Morris - - * makefile.w32-in (texinputdir): - * Makefile.in (ENVADD): Add $emacsdir. (Bug#10603) - -2012-01-24 Chong Yidong - - * variables.texi (Variables, Local Variables, Void Variables): - Edit to make the descriptions less specific to dynamic binding. - (Local Variables): Default max-specpdl-size is now 1300. - (Defining Variables): Edits for lexical scoping. - Delete information about starting docstrings with *. De-document - user-variable-p. - (Tips for Defining): Remove an unimportant discussion of quitting - in the middle of a load. - (Accessing Variables, Setting Variables): Discuss lexical binding. - (Variable Scoping): Rewrite. - (Scope, Extent, Impl of Scope): Nodes deleted. - (Dynamic Binding): New node, with material from Scope, Extent, and - Impl of Scope nodes. - (Dynamic Binding Tips): Rename from Using Scoping. - (Lexical Binding): Rewrite. - (Using Lexical Binding): Rename from Converting to Lexical - Binding. Convert to subsection. - - * customize.texi (Variable Definitions): Add custom-variable-p. - Move user-variable-p documentation here. - -2012-01-23 Chong Yidong - - * strings.texi (Text Comparison): Minor qualification. - - * lists.texi (Cons Cells): Copyedits. - (List Elements): Mention push. - (List Variables): Mention pop. - (Rings): Move to sequences.texi. - - * sequences.texi (Sequence Functions): Don't repeat the - introduction already given in the parent. - (Vectors): Copyedits. - (Rings): Move from lists.texi. Note that this is specific to the - ring package. - - * symbols.texi (Definitions, Symbol Components): Mention variable - scoping issues. - (Plists and Alists): Copyedits. - - * eval.texi (Intro Eval, Symbol Forms): Minor tweaks for - correctness with lexical scoping. - (Eval): Copyedits. - -2012-01-21 Chong Yidong - - * intro.texi (A Sample Function Description): Special notation - used for macros too. - - * objects.texi (Ctl-Char Syntax, Other Char Bits): Copyedits. - (Symbol Type): Add xref for keyword symbols. - (Sequence Type): Clarify differences between sequence types. - (Cons Cell Type): Add "linked list" index entry. - (Non-ASCII in Strings): Copyedits. - (Equality Predicates): Symbols with same name need not be eq. - - * numbers.texi (Float Basics): Document isnan, copysign, frexp and - ldexp. Move float-e and float-pi to Math Functions node. - -2012-01-21 Glenn Morris - - * modes.texi (Auto Major Mode): - * variables.texi (File Local Variables): - Mention inhibit-local-variables-regexps. - -2012-01-19 Martin Rudalics - - * windows.texi (Window Configurations): Rewrite references to - persistent window parameters. - (Window Parameters): Fix description of persistent window - parameters. - -2012-01-16 Juanma Barranquero - - * windows.texi (Window Parameters): Use @pxref. - -2012-01-16 Martin Rudalics - - * windows.texi (Window Configurations, Window Parameters): - Describe persistent window parameters. - -2011-12-27 Stefan Monnier - - * variables.texi (Creating Buffer-Local): Warn against misuses of - make-variable-buffer-local (bug#10258). - -2012-01-07 Lars Magne Ingebrigtsen - - * macros.texi (Defining Macros): Document `doc-string' (bug#9668). - -2012-01-06 Chong Yidong - - * variables.texi (Directory Local Variables): - Document hack-dir-local-variables-non-file-buffer. - -2012-01-06 Glenn Morris - - * maps.texi (Standard Keymaps): Refer to Info-edit by name - rather than by keybinding. - -2011-12-29 Juanma Barranquero - - * frames.texi (Font and Color Parameters): Add @pxref. - -2011-12-29 Daniel Colascione - - * frames.texi (Font and Color Parameters): - Document w32 font backends (bug#10399). - -2011-12-28 Paul Eggert - - * files.texi (File Attributes, Changing Files): - Use a more-natural notation for octal numbers. - -2011-12-23 Juanma Barranquero - - * variables.texi (Variables with Restricted Values): - Change reference to variable (bug#10354). - -2011-12-13 Martin Rudalics - - * windows.texi (Splitting Windows): Use t instead of non-nil - when describing window-combination-resize. - -2011-12-05 Stefan Monnier - - * text.texi (Special Properties): Warn against `intangible' properties - (bug#10222). - -2011-11-26 Eli Zaretskii - - * display.texi (Truncation): - * text.texi (Special Properties): Describe what a stretch-glyph is - instead of using that term without explanation. Make the - cross-references more accurate. - - * display.texi (Usual Display): Update the description, - cross-references, and indexing related to display of control - characters and raw bytes. - -2011-11-25 Martin Rudalics - - * windows.texi (Splitting Windows): Fix description of - window-combination-limit. Suggested by Eli Zaretskii. - -2011-11-23 Chong Yidong - - * windows.texi (Window Sizes): Move window-top-line, - window-left-column, and window-*-pixel-edges to Coordinates and - Windows node. - (Coordinates and Windows): Restore window-edges doc. - -2011-11-21 Martin Rudalics - - * windows.texi (Windows and Frames, Splitting Windows): - Fix typos. - -2011-11-21 Chong Yidong - - * windows.texi (Splitting Windows): Fix error in documentation of - window-combination-limit. - (Cyclic Window Ordering): Minor fixes to next-window, - one-window-p, and get-lru-window docs. Don't document - window-list-1. - (Buffers and Windows): Copyedits. - (Choosing Window): Document special handling of special-display-*. - (Choosing Window Options): Fix display-buffer-reuse-frames doc. - Don't document even-window-heights, which is going away. - Clarify which options are obeyed by which action functions. - -2011-11-20 Stefan Monnier - - * display.texi (Invisible Text): Clarify point adjustment (bug#10072). - -2011-11-20 Martin Rudalics - - * windows.texi (Resizing Windows, Splitting Windows): - Remove term "status" when talking about combination limits. - -2011-11-20 Juanma Barranquero - - * compile.texi (Compiler Errors): - * help.texi (Help Functions): Fix typos. - -2011-11-19 Chong Yidong - - * windows.texi (Splitting Windows): Clarify role of window - parameters in split-window. Shorten the example. - (Deleting Windows): Rewrite intro to handle internal windows. - Fix delete-windows-on doc. - (Selecting Windows): Copyedits. - -2011-11-17 Martin Rudalics - - * windows.texi (Resizing Windows, Splitting Windows) - (Deleting Windows): Use term window-combination-resize instead - of window-splits. - -2011-11-16 Martin Rudalics - - * windows.texi (Resizing Windows, Splitting Windows): - Rename occurrences of window-nest to window-combination-limit. - -2011-11-14 Juanma Barranquero - - * intro.texi (Lisp History): Fix typo. - -2011-11-12 Martin Rudalics - - * windows.texi (Splitting Windows, Deleting Windows): - Remove references to splits status of windows. - -2011-11-10 Glenn Morris - - * buffers.texi (Read Only Buffers): Expand a bit on why - toggle-read-only should only be used interactively. (Bug#7292) - -2011-11-09 Chong Yidong - - * windows.texi (Window Sizes): Document window-pixel-edges, - window-inside-pixel-edges, window-absolute-pixel-edges, and - window-inside-absolute-pixel-edges. - (Resizing Windows): shrink-window-if-larger-than-buffer works on - non-full-width windows. - -2011-11-09 Martin Rudalics - - * windows.texi (Resizing Windows): Rewrite documentation of - window-resizable. - -2011-11-09 Chong Yidong - - * windows.texi (Splitting Windows): Simplify example. - -2011-11-08 Chong Yidong - - * windows.texi (Window Sizes): Copyedits. Document - window-text-height. Remove window-min-height and window-min-width - discussion, referring instead to Emacs manual. - (Splitting Windows, Resizing Windows): Add xref to Emacs manual. - (Resizing Windows): Simplify introduction. Don't document - enlarge-window, shrink-window, enlarge-window-horizontally, and - shrink-window-horizontally; they are no longer preferred for - calling from Lisp, and are already documented in the Emacs manual. - -2011-11-07 Glenn Morris - - * windows.texi (Choosing Window): Fix keybinding typo. - -2011-11-07 Martin Rudalics - - * windows.texi (Resizing Windows, Splitting Windows) - (Window Configurations): Use "child window" instead of - "subwindow". - -2011-11-06 Chong Yidong - - * windows.texi (Basic Windows): Clarify various definitions. - Treat window-normalize-* as internal; don't document them. - (Windows and Frames): Various clarifications, e.g. non-live - windows also belong to frames. Fix window-list description. - Simplify window nesting example. - (Splitting Windows, Window Configurations): - Use split-window-below. - -2011-11-04 Eli Zaretskii - - * windows.texi (Window Sizes): Mention in the doc string that the - return values of `window-body-height' and `window-body-width' are - in frame's canonical units. (Bug#9949) - -2011-10-30 Martin Rudalics - - * windows.texi (Windows and Frames): Remove "iso-" infix from - documentation of window-iso-combined-p. - -2011-10-26 Chong Yidong - - * modes.texi (Running Hooks): Document with-wrapper-hook. - -2011-10-18 Chong Yidong - - * display.texi (Glyphless Chars): New node. - -2011-10-13 Chong Yidong - - * text.texi (Yanking): Document yank-excluded-properties. - - * package.texi (Packaging Basics): The commentary should say how - to begin using the package. - -2011-10-11 Martin Rudalics - - * windows.texi (Deleting Windows): Mention which window gets - selected when deleting the selected window. - -2011-10-09 Martin Rudalics - - * buffers.texi (The Buffer List): Describe how bury-buffer deals - with the selected window. - * windows.texi (Buffers and Windows): Reformulate text on how - replace-buffer-in-windows deals with a window. - (Quitting Windows): Describe how quit-window deals with a - standalone frame. Describe new option frame-auto-hide-function. - -2011-10-08 Glenn Morris - - * symbols.texi (Other Plists): Markup fix. (Bug#9702) - - * positions.texi (Excursions): Update warning message. - -2011-10-05 Chong Yidong - - * display.texi (Low-Level Font, Face Attributes, Font Lookup): - Fix Emacs manual xref (Bug#9675). - -2011-10-01 Chong Yidong - - * windows.texi (Textual Scrolling): Document scroll-up-command, - scroll-down-command, scroll-error-top-bottom, and the - scroll-command symbol property. - (Display Action Functions): Fix description of - display-buffer-pop-up-window. - -2011-09-28 Juanma Barranquero - - * windows.texi (Splitting Windows): Fix typos. - -2011-09-25 Martin Rudalics - - * windows.texi (Windows and Frames, Display Action Functions) - (Switching Buffers): Fix some typos. - (Buffers and Windows): Remove reference to window-auto-delete. - Reword description of replace-buffer-in-windows. - (Window History): Fix some typos and refer to frame local buffer - list. - (Quitting Windows): New node. - (Window Configurations): Add descriptions of window-state-get - and window-state-put. - (Window Parameters): Describe variable ignore-window-parameters. - Sketch some window parameters currently in use. - * elisp.texi (Top): Update node listing. - -2011-09-25 Chong Yidong - - * windows.texi (Display Action Functions) - (Choosing Window Options): New nodes. - -2011-09-24 Chong Yidong - - * windows.texi (Window History): New node. Move text here from - Buffers and Windows. - (Switching Buffers): Rename from Displaying Buffers, since we - don't document display-buffer here; callers changed. - Document FORCE-SAME-WINDOW arg to switch-to-buffer and - switch-to-buffer-other-frame. Delete duplicate - replace-buffer-in-windows doc. - (Choosing Window): Document display actions. - -2011-09-24 Eli Zaretskii - - * display.texi (Forcing Redisplay): Update the description of - redisplay-dont-pause due to change in the default value. - -2011-09-23 Martin Rudalics - - * frames.texi (Frames and Windows): Move section and rename to - Windows and Frames in windows.texi. - * windows.texi (Windows): Restructure. - (Basic Windows): Rewrite. Explain live and internal windows and - normalization functions. - (Windows and Frames): Move section here from frames.texi. - Describe subwindows, window combinations, window tree, and - corresponding functions including window-list here. - (Window Sizes): Rename section from Size of Window and move it - up in chapter. Describe total and body sizes and the - corresponding functions. Explain new semantics of - window-min-height/-width. - (Resizing Windows): Move section up in chapter. Describe new - resize functions. - (Splitting Windows): Describe new behavior of split-window, - split-window-above-each-other and split-window-side-by-side. - Provide examples. Describe window-nest and window-splits - options. - (Deleting Windows): Minor rewrite. - (Selecting Windows): Minor rewrite. - Describe frame-selected-window and set-frame-selected-window here. - (Cyclic Window Ordering): Minor rewrite. - Describe window-list-1. - (Buffers and Windows): Rewrite. Explain a window's previous and - next buffers and the corresponding functions. - (Window Tree): Merge into Windows and Frames section. - * elisp.texi (Top): Update node listings for frames and windows - sections. - -2011-09-21 Stefan Monnier - - * display.texi (Face Functions): `face-list' returns faces (bug#9564). - -2011-09-19 Lars Magne Ingebrigtsen - - * errors.texi (Standard Errors): Remove apparent placeholder text - (bug#9491). - -2011-09-18 Chong Yidong - - * frames.texi (Management Parameters): Fix description of - icon-type parameter. - -2011-09-17 Chong Yidong - - * tips.texi (Key Binding Conventions): Don't bind a key sequence - ending in C-g. Suggested by Edward O'Connor. - -2011-09-17 Eli Zaretskii - - * numbers.texi (Integer Basics): Add indexing for - most-positive-fixnum and most-negative-fixnum. (Bug#9525) - -2011-09-14 Dani Moncayo - - * lists.texi (Sets And Lists): Fix typo. (Bug#9393) - -2011-09-11 Juanma Barranquero - - * processes.texi (Network Servers): Clarify what the process - buffer is used for (bug#9233). - -2011-08-30 Dani Moncayo - - * lists.texi (Building Lists): Fix typo. - -2011-08-30 Chong Yidong - - * display.texi (Basic Faces): New node. Document new faces. - - * modes.texi (Major Mode Conventions): Move some text there. - (Mode Help): Remove major-mode var, duplicated in Major Modes. - -2011-08-29 Chong Yidong - - * modes.texi (Basic Major Modes): New node. Callers updated. - (Major Modes): Document fundamental-mode and major-mode. - (Major Mode Basics): Node deleted; text moved to Major Modes. - (Derived Modes): Document derived-mode-p. - -2011-08-28 Chong Yidong - - * files.texi (Changing Files, Create/Delete Dirs): Document new - arguments for delete-file, delete-directory, and copy-directory. - (Visiting Functions): Remove view-file; it is documented in the - Emacs manual. - - * frames.texi (Layout Parameters): The defaults for the - menu-bar-lines and tool-bar-lines parameters depend on the mode. - - * display.texi (Progress): Document spinner functionality. - - * os.texi (Killing Emacs): Note that kill-emacs can be called by - operating system signals. Refer to save-buffers-kill-terminal - instead of save-buffers-kill-emacs. - - * objects.texi (Symbol Type): Document ## print representation. - -2011-08-25 Eli Zaretskii - - * display.texi (Specified Space): Mention that `space' specs - influence bidi reordering. - (Bidirectional Display): Explain how to use `(space . PROPS)' for - separating fields with bidirectional content. - -2011-08-24 Eli Zaretskii - - * display.texi (Bidirectional Display): Document return value in - buffers that are not bidi-reordered for display, and in unibyte - buffers. - -2011-08-23 Eli Zaretskii - - * nonascii.texi (Character Properties): Document the values for - unassigned codepoints. - -2011-08-18 Eli Zaretskii - - * nonascii.texi (Character Properties): Document use of - `bidi-class' and `mirroring' properties as part of reordering. - Provide cross-references to "Bidirectional Display". - - * display.texi (Bidirectional Display): Document the pitfalls of - concatenating strings with bidirectional content, with possible - solutions. Document bidi-string-mark-left-to-right. - Mention paragraph direction in modes that inherit from prog-mode. - Document use of `bidi-class' and `mirroring' properties as part of - reordering. - -2011-08-16 Eli Zaretskii - - * modes.texi (Major Mode Conventions): Improve the documentation - of `mode-class' `special' modes. - - * nonascii.texi (Character Properties): Document the `mirroring' - property. Add index entries. - - * syntax.texi (Categories): Add an example of defining a new - category and category table. - - * searching.texi (Regexp Backslash): Document how to display - existing categories. Mention the possibility of adding - categories, and add an xref to where this is described. Add an - index entry. - -2011-08-09 Chong Yidong - - * text.texi (Special Properties): - * display.texi (Overlay Properties): Note that mouse-face cannot - change the text size (Bug#8530). - -2011-08-08 Chong Yidong - - * os.texi (Time of Day): Remove set-time-zone-rule, and recommend - using setenv instead. - -2011-07-28 Eli Zaretskii - - * display.texi (Bidirectional Display): Document the fact that - bidi-display-reordering is t by default. - -2011-07-23 Eli Zaretskii - - * display.texi (Bidirectional Display): New section. - -2011-07-16 Lars Magne Ingebrigtsen - Tim Cross (tiny change) - Glenn Morris - - * keymaps.texi (Toolkit Differences): New node. (Bug#8176) - -2011-07-15 Andreas Schwab - - * help.texi (Keys in Documentation): Revert last change. - -2011-07-15 Lars Magne Ingebrigtsen - - * help.texi (Keys in Documentation): Clarify that \= only quotes - the next character, and doesn't affect longer sequences in - particular (bug#8935). - - * debugging.texi (Using Debugger): - Mention @code{eval-expression-debug-on-error} (bug#8549). - -2011-07-14 Eli Zaretskii - - * display.texi (Other Display Specs): Document that `left-fringe' - and `right-fringe' display specifications are of the "replacing" - kind. - -2011-07-14 Lars Magne Ingebrigtsen - - * help.texi (Documentation Basics): Add a link to the Function - Documentation node (bug#6580). - -2011-07-13 Lars Magne Ingebrigtsen - - * keymaps.texi (Menu Bar): Mention :visible and :enable - (bug#6344). Text by Drew Adams. - - * modes.texi (Running Hooks): Mention buffer-local hook variables - (bug#6218). - - * objects.texi (General Escape Syntax): "a with grave accent" is - ?xe0, not ?x8e0 (bug#5259). - -2011-07-12 Chong Yidong - - * display.texi (Face Attributes, Font Selection): Add references - to the Fonts node in the Emacs manual (Bug#4178). - -2011-07-12 Chong Yidong - - * display.texi (Window Systems): `window-system' is - terminal-local. - - * frames.texi (Frame Parameters, Parameter Access): Don't mention - frame-local variables. - - * variables.texi (Buffer-Local Variables): Don't mention obsolete - frame-local variables. - (Frame-Local Variables): Node deleted. - - * elisp.texi (Top): Update node listing. - -2011-07-12 Lars Magne Ingebrigtsen - - * elisp.texi: Change "inferiors" to "subnodes" in three places - (bug#3523). - -2011-07-11 Chong Yidong - - * frames.texi (Window System Selections): Discussion of - x-select-enable-clipboard moved to Emacs manual. - -2011-07-11 Deniz Dogan - - * commands.texi (Prefix Command Arguments): Remove excessive - apostrophe. - -2011-07-11 Lars Magne Ingebrigtsen - - * syntax.texi (Syntax Descriptors): Clarify that the ". 23" syntax - description is a string (bug#3313). - - * frames.texi (Display Feature Testing): Try to explain what all - the visual classes mean (bug#3042). - -2011-07-10 Lars Magne Ingebrigtsen - - * modes.texi (Mode Line Variables): Document `mode-line-remote' - and `mode-line-client' (bug#2974). - - * text.texi (Insertion): Clarify marker movements (bug#1651). - Text from Drew Adams. - -2011-07-07 Lars Magne Ingebrigtsen - - * text.texi (Special Properties): Clarify the format of `face' - (bug#1375). - - * commands.texi (Interactive Call): Add a `call-interactively' - example (bug#1010). - -2011-07-06 Lars Magne Ingebrigtsen - - * functions.texi (Calling Functions): Link to the "Interactive - Call" node (bug#1001). - -2011-07-06 Chong Yidong - - * customize.texi (Composite Types): Move alist and plist to here - from Simple Types (Bug#7545). - - * elisp.texi (Top): Update menu description. - - * display.texi (Face Attributes): Document negative line widths - (Bug#6113). - -2011-07-03 Tobias C. Rittweiler (tiny change) - - * searching.texi (Match Data): Note that match data can be - overwritten by most functions (bug#2499). - -2011-07-03 Lars Magne Ingebrigtsen - - * strings.texi (Formatting Strings): Clarify what the "-" and "0" - flags mean (bug#6659). - - * functions.texi (What Is a Function): Document the autoload - object (bug#6496). - -2011-07-02 Lars Magne Ingebrigtsen - - * customize.texi (Variable Definitions): Clarify that SETFUNCTION - is only used in the Customize user interface (bug#6089). - - * display.texi (Showing Images): Mention the point of sliced - images (bug#7836). - -2011-07-02 Eli Zaretskii - - * variables.texi (Defining Variables, Void Variables) - (Constant Variables): Fix incorrect usage of @kindex. - -2011-07-02 Lars Magne Ingebrigtsen - - * variables.texi (Defining Variables): Add an index entry for - `set-variable' (bug#7262). - (Defining Variables): Use @findex for functions. - - * frames.texi (Basic Parameters): Document the `explicit-name' - parameter (bug#6951). - - * customize.texi (Type Keywords): Clarify that :value provides a - default value for all types (bug#7386). - - * streams.texi (Output Functions): Document `pp'. - -2011-06-25 Chong Yidong - - * keymaps.texi (Searching Keymaps): - * display.texi (Overlay Properties): Fix errors in 2011-05-29 - change. Suggested by Johan BockgÃ¥rd. - -2011-06-15 Chong Yidong - - * text.texi (Special Properties): Clarify role of font-lock-face. - -2011-06-15 Lars Magne Ingebrigtsen - - * processes.texi (Process Information): Rename `process-alive-p' - to `process-live-p' for consistency with other `-live-p' functions. - -2011-06-03 Paul Eggert - - Document wide integers better. - * files.texi (File Attributes): Document ino_t values better. - ino_t values no longer map to anything larger than a single cons. - * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations) - (Bitwise Operations): - * objects.texi (Integer Type): Use a binary notation that is a bit easier - to read, and that will port better if 62-bits becomes the default. - Fix or remove incorrect examples. - * os.texi (Time Conversion): Document time_t values better. - -2011-05-31 Lars Magne Ingebrigtsen - - * processes.texi (Process Information): - Document `process-alive-p'. - -2011-05-29 Chong Yidong - - * help.texi (Accessing Documentation): - * display.texi (Pixel Specification): - * processes.texi (Serial Ports, Serial Ports): - * nonascii.texi (Character Properties, Default Coding Systems): - * text.texi (Changing Properties, Special Properties): - * windows.texi (Window Start and End): - * modes.texi (SMIE Indentation Example, SMIE Tricks): - * keymaps.texi (Searching Keymaps, Tool Bar): - * minibuf.texi (Basic Completion): - * compile.texi (Eval During Compile): - * strings.texi (Formatting Strings): Tweaks to avoid overflowing - 7x9 paper in printed manual. - - * lists.texi (Sets And Lists): Fix misplaced text. - -2011-05-29 Chong Yidong - - * keymaps.texi (Remapping Commands): Emphasize that the keymap - needs to be active (Bug#8350). - -2011-05-28 Chong Yidong - - * minibuf.texi (Reading File Names): Clarify (Bug#8480). - - * tips.texi (Coding Conventions): Remove antediluvian filename - limit recommendation (Bug#8538). - -2011-05-27 Glenn Morris - - * modes.texi (Auto Major Mode): Update for set-auto-mode changes. - -2011-05-26 Glenn Morris - - * variables.texi (File Local Variables): - Update hack-local-variables `mode-only' return value. - Add some more details on what this function does in the other case. - -2011-05-19 Glenn Morris - - * lists.texi (Sets And Lists): Mention cl provides union etc. - -2011-05-19 Nix - - * windows.texi (Displaying Buffers): pop-to-buffer is not a command. - - * text.texi (Parsing HTML): Update for function name changes. - - * syntax.texi (Syntax Flags): Small fix. - - * keymaps.texi (Active Keymaps): Typo fix. - (Changing Key Bindings): Grammar fix. - - * frames.texi (Minibuffers and Frames): Grammar fix. - (Window System Selections): x-select-enable-clipboard now defaults to t. - - * customize.texi (Common Keywords): - * display.texi (Abstract Display): - * modes.texi (Auto-Indentation): - * nonascii.texi (Converting Representations): Typo fixes. - - * control.texi (Examples of Catch): Call it "goto" not "go to". - -2011-05-14 Eli Zaretskii - - * nonascii.texi (Character Properties): Fix inconsistencies with - implementation. - - * text.texi (Special Properties): Move @defvar's out of the - @table. (Bug#8652) - -2011-05-12 Glenn Morris - - * display.texi (Image Descriptors): Fix typo. (Bug#8495) - -2011-05-12 Stefan Monnier - - * modes.texi (Region to Refontify): Rename from "Region to Fontify". - (Multiline Font Lock): - * vol2.texi (Top): - * vol1.texi (Top): - * elisp.texi (Top): Update menu accordingly. - -2011-05-12 Drew Adams - - * modes.texi (Region to Fontify): Fix typo. - -2011-05-10 Jim Meyering - - * minibuf.texi: Fix typo "in in -> in". - -2011-05-06 Paul Eggert - - * numbers.texi (Integer Basics): Large integers are treated as floats. - -2011-04-30 Lars Magne Ingebrigtsen - - * processes.texi (Synchronous Processes): Document the (:file - "/file-name") syntax for `call-process'. - -2011-04-23 Juanma Barranquero - - * windows.texi (Choosing Window): Fix typo. - -2011-04-23 Chong Yidong - - * frames.texi (Layout Parameters): Note the difference between - querying and setting parameters for left-fringe and right-fringe - (Bug#6930). - -2011-03-21 Stefan Monnier - - * minibuf.texi (Basic Completion): Be a bit more precise about the - valid kinds of completion tables. - (Programmed Completion): Remove obsolete text about lambda expressions - not being valid completion tables. - -2011-03-19 Chong Yidong - - * positions.texi (Excursions): Explain the "save-excursion - defeated by set-buffer" warning. - - * buffers.texi (Current Buffer): Copyedits. Don't recommend using - save-excursion. Suggested by Uday S Reddy. - -2011-04-01 Stefan Monnier - - * variables.texi (Defining Variables): Mention the new meaning of `defvar'. - (Lexical Binding): New sub-section. - - * eval.texi (Eval): Discourage the use of `eval'. - Document its new `lexical' argument. - -2011-03-28 Stefan Monnier - - * commands.texi (Command Overview): `post-command-hook' is not reset to - nil any more. - -2011-03-19 Stefan Monnier - - * strings.texi (String Conversion): Don't mention - string-make-(uni|multi)byte (bug#8262). - * nonascii.texi (Converting Representations): Fix up range. - * keymaps.texi (Key Binding Commands): Update code point, avoid - "unibyte character" and remove mention of unibyte bindings. - -2011-03-10 Eli Zaretskii - - * modes.texi (Operator Precedence Grammars): Don't use characters - outside ISO-8859-1. - -2011-03-09 Eli Zaretskii - - * intro.texi (Acknowledgements): Convert to ISO-8859-1 encoding. - - * makefile.w32-in (MAKEINFO_OPTS): Add --enable-encoding. - -2011-03-08 Glenn Morris - - * Makefile.in (MAKEINFO_OPTS): Add --enable-encoding. - * intro.texi (Acknowledgements): Names to UTF-8. - * elisp.texi: Set documentencoding. - -2011-03-07 Chong Yidong - - * Version 23.3 released. - -2011-03-06 Chong Yidong - - * package.texi: Update index keywords. - (Package Archives): New node contents. Document package-x.el. - -2011-03-06 Juanma Barranquero - - * makefile.w32-in (srcs): Add package.texi. - -2011-03-06 Chong Yidong - - * package.texi (Packaging, Packaging Basics, Simple Packages) - (Multi-file Packages): Expand and clarify. - (Package Archives): Temporary placeholder node. - - * elisp.texi (Top): Update node listing. - - * Makefile.in (srcs): Add package.texi. - -2011-03-05 Chong Yidong - - * processes.texi (Synchronous Processes): Minor clarification - (Bug#8149). - -2011-03-03 Glenn Morris - - * files.texi (Truenames): Minor clarification. (Bug#2341) - -2011-03-01 Glenn Morris - - * variables.texi (Directory Local Variables): - Mention `(subdirs . nil)' alist element. - -2011-02-28 Glenn Morris - - * variables.texi (Directory Local Variables): Mention the optional - mtime argument of dir-locals-set-directory-class. (Bug#3577) - -2011-02-27 Chong Yidong - - * minibuf.texi (Minibuffer History): Clarify discussion of - minibuffer history lists (Bug#8085). - -2011-02-19 Eli Zaretskii - - * elisp.texi: Sync @dircategory with ../../info/dir. - - * files.texi (Visiting Functions): Document find-file-literally, - both the command and the variable. - - * variables.texi (Creating Buffer-Local): Explain the meaning of - permanent local variables. - - * files.texi (Visiting Functions): Document find-file-literally, - both the command and the variable. - - * variables.texi (Creating Buffer-Local): Explain the meaning of - permanent local variables. - -2011-02-19 Glenn Morris - - * keymaps.texi (Remapping Commands): Mention how to undo it. - -2011-02-09 Reuben Thomas - - * loading.texi (Hooks for Loading): Remove unnecessary advice - about eval-after-load (Bug#7986). - -2011-02-05 Chong Yidong - - * commands.texi (Accessing Mouse): Note that a header line is not - included in the row of posn-col-row. - -2011-02-02 Chong Yidong - - * modes.texi (Major Mode Conventions): Add face guidelines. - (Faces for Font Lock): List faces in order of prominence. - -2011-02-01 Paul Eggert - - format-time-string now supports subsecond time stamp resolution - * os.texi (Time Parsing): Document %N. - -2011-01-28 Chong Yidong - - * vol1.texi (Top): - * vol2.texi (Top): - * elisp.texi (Top): - * display.texi (Display Property): Shorten the menu description of - the "Other Display Specs" node (Bug#7816). - - * keymaps.texi (Defining Menus): Add "menu item" and "extended - menu item" concept index entries (Bug#7805). - -2011-01-29 Eli Zaretskii - - * makefile.w32-in (texinfodir): New variable. - (usermanualdir): Remove as redundant with $(emacsdir). - (MAKEINFO): Remove options, leave only program name. - (MAKEINFO_OPTS): New variable. - (texinputdir, $(infodir)/elisp): Use $(MAKEINFO_OPTS). - -2011-01-25 Chong Yidong - Richard Kim - - * loading.texi (Library Search): Document list-load-path-shadows - (Bug#7757). - -2011-01-25 Chong Yidong - - * searching.texi (Regexp Special): Remove outdated discussion of - character sets (Bug#7780). - - * frames.texi (Pop-Up Menus): Document where menu title comes - from (Bug#7684). - -2011-01-25 Glenn Morris - - * display.texi (Making Buttons): Mention limitation of text buttons. - -2011-01-23 Werner Lemberg - - * Makefile.in (MAKEINFO): Now controlled by `configure'. - (MAKEINFO_OPTS): New variable. Use it where appropriate. - (ENVADD): New variable to control texi2dvi and texi2pdf. - -2011-01-15 Chong Yidong - - * files.texi (Directory Names): Move directory-abbrev-alist doc to - Emacs manual. - -2011-01-15 Eli Zaretskii - - * files.texi (Directory Names): Explain why FROM in - directory-abbrev-alist should begin with \`. (Bug#7777) - -2011-01-11 Stefan Monnier - - * loading.texi (Hooks for Loading): Adjust doc of eval-after-load. - -2011-01-02 Eli Zaretskii - - * modes.texi (Emulating Mode Line): Fix last change. - -2011-01-02 Eli Zaretskii - - * modes.texi (Emulating Mode Line): Update documentation of - format-mode-line according to changes that fixed bug #7587. - -2010-12-18 Stefan Monnier - - * modes.texi (Derived Modes): Mention prog-mode. - - * keymaps.texi (Simple Menu Items, Extended Menu Items): Remove mention - of the key-binding-data cache since we don't use it any more. - -2010-12-13 Eli Zaretskii - - * processes.texi (Shell Arguments): - * strings.texi (Creating Strings): Don't mention "shell commands"; - make it explicit that `split-string-and-unquote' and - `combine-and-quote-strings' are mainly for working with arguments - to call-process and start-process. - - * processes.texi (Shell Arguments): Fix documentation of - `split-string-and-unquote'. Add indexing. (Bug#7563) - -2010-12-13 Stefan Monnier - - * modes.texi (Auto-Indentation): New section to document SMIE. - (Major Mode Conventions): - * text.texi (Mode-Specific Indent): Refer to it. - -2010-12-13 Eli Zaretskii - - * display.texi (Other Display Specs): Document left-fringe and - right-fringe display specs. - -2010-12-13 Stefan Monnier - - * backups.texi (Making Backups): - * modes.texi (Example Major Modes): Use recommended coding style. - (Major Mode Basics, Derived Modes): Encourge more strongly use of - define-derived-mode. Mention completion-at-point-functions. - -2010-12-13 Chong Yidong - - * nonascii.texi (Converting Representations): - Document byte-to-string. - -2010-12-08 Glenn Morris - - * buffers.texi (Modification Time): - verify-visited-file-modtime now defaults to the current buffer. - -2010-11-27 Chong Yidong - - * nonascii.texi (Converting Representations): Document byte-to-string. - - * strings.texi (Creating Strings): Don't mention semi-obsolete - function char-to-string. - (String Conversion): Shorten discussion of semi-obsolete function - string-to-char. Link to Converting Representations. - - * objects.texi (Symbol Type): - * text.texi (Near Point): - * help.texi (Help Functions): - * functions.texi (Mapping Functions): Use string instead of - char-to-string in examples. - -2010-11-27 Chong Yidong - - * text.texi (Kill Functions, Kill Functions) - (Low-Level Kill Ring, Low-Level Kill Ring): Remove obsolete - YANK-HANDLER args. - - * symbols.texi (Creating Symbols): Using unintern without an - obarray arg is now obsolete. - - * numbers.texi (Float Basics): Document float-e and float-pi. - - * variables.texi (Defining Variables): Change "pi" example to - "float-pi". - -2010-11-26 Eli Zaretskii - - * commands.texi (Click Events): Document the values of X, Y and - COL, ROW in the event's position, when the click is on the header - or mode line, on the fringes, or in the margins. - -2010-11-17 Eli Zaretskii - - * customize.texi (Composite Types): Lower-case index entry. - - * loading.texi (How Programs Do Loading): - Document load-file-name. (Bug#7346) - -2010-11-17 Glenn Morris - - * text.texi (Kill Functions, Low-Level Kill Ring): Small fixes. - -2010-11-13 Eli Zaretskii - - * display.texi (Usual Display): Characters with no fonts are not - necessarily displayed as empty boxes. - -2010-10-31 Glenn Morris - - * maps.texi (Standard Keymaps): Update File menu description. - -2010-10-28 Glenn Morris - - * Makefile.in (elisp.dvi, elisp.pdf): Also include $emacsdir. - -2010-10-24 Eli Zaretskii - - * display.texi (Window Systems): Deprecate use of window-system as - a predicate. - -2010-10-23 Glenn Morris - - * help.texi (Documentation Basics): Remove mentions of digest-doc and - sorted-doc. - -2010-10-15 Eli Zaretskii - - * os.texi (Dynamic Libraries): New node, with slightly modified - text deleted from "Image Formats". - (System Interface): Add @menu entry for "Dynamic Libraries". - - * display.texi (Image Formats): Remove description of - image-library-alist. (Renamed in 2010-10-13T14:50:06Z!lekktu@gmail.com.) - -2010-10-12 Glenn Morris - - * book-spine.texinfo: Rename to book-spine.texi. - -2010-10-11 Glenn Morris - - * Makefile.in (MAKEINFO): Add explicit -I$srcdir. - - * Makefile.in (DVIPS): New variable. - (.PHONY): Add html, ps. - (html, elisp.html, ps, elisp.ps): New targets. - (clean): Delete html, ps files. - ($(infodir)/elisp): Remove unnecessary includes. - -2010-10-09 Eli Zaretskii - - * makefile.w32-in (emacsdir): New variable. - (srcs): Add emacsver.texi. - ($(infodir)/elisp, elisp.dvi): Add -I$(emacsdir). - -2010-10-09 Glenn Morris - - * Makefile.in (VPATH): Remove. - (infodir): Make it absolute. - (mkinfodir, $(infodir)/elisp, infoclean): No need to cd $srcdir. - - * Makefile.in (dist): Anchor regexps. - - * Makefile.in (srcs): Put elisp.texi first. - ($(infodir)/elisp, elisp.dvi, elisp.pdf): Use $<. - - * Makefile.in (infoclean): Remove harmless, long-standing error. - - * Makefile.in ($(infodir)): Delete rule. - (mkinfodir): New. - ($(infodir)/elisp): Use $mkinfodir instead of infodir. - - * Makefile.in (dist): Remove reference to emacsver.texi.in. - Also copy emacsver.texi, and edit $emacsdir. - -2010-10-09 Glenn Morris - - * Makefile.in (emacsdir): New variable. - (MAKEINFO): Add -I $emacsdir. - (dist): Copy emacsver.texi. - (srcs): Add emacsver.texi. - - * book-spine.texinfo, elisp.texi, vol2.texi, vol1.texi: - Set EMACSVER by including emacsver.texi. - - * Makefile.in (.PHONY): Declare info, dvi, pdf, dist. - -2010-10-07 Glenn Morris - - * Makefile.in (version): New, set by configure. - (clean): Delete dist tar file. - (dist): Use version in tar name. - -2010-10-06 Glenn Morris - - * Makefile.in: Rearrange to more closely resemble doc/emacs/Makefile. - (INSTALL_INFO): Remove unused variable. - (mostlyclean, infoclean, dist): New rules. - (clean): Delete dvi and pdf files. - (maintainer-clean): Remove elisp.oaux, use infoclean. - ($(infodir)): Add parallel build workaround. - -2010-10-04 Glenn Morris - - * Makefile.in (dvi, pdf, $(infodir)): New targets. - ($(infodir)/elisp): Ensure target directory exists. Use $@. - Fix -I typo. - (clean): No 'make.out' or 'core' files. - (.PHONY): Declare clean rules. - (maintainer-clean): Delete pdf file. Guard against cd failures. - -2010-10-03 Glenn Morris - - * files.texi (File Name Components): Remove ignored section about - deleted variable directory-sep-char. - -2010-10-03 Michael Albinus - - * files.texi (Magic File Names): New defopt - remote-file-name-inhibit-cache. - -2010-10-02 Glenn Morris - - * os.texi (Killing Emacs): Hook now runs in batch mode. - -2010-09-18 Stefan Monnier - - * text.texi (Special Properties): Clarify when modification-hooks run. - -2010-09-11 Stefan Monnier - - * syntax.texi (Syntax Flags): Document new `c' flag. - -2010-09-09 Glenn Morris - - * display.texi (ImageMagick Images): General cleanup. - -2010-09-06 Alexander Klimov (tiny change) - - * files.texi (Directory Names): Use \` rather than ^. - -2010-09-02 Jan Djärv - - * text.texi (Low-Level Kill Ring): - * frames.texi (Window System Selections): Remove cut buffer - documentation. - -2010-08-28 Eli Zaretskii - - * display.texi (Fringe Size/Pos): Add a cross-reference to "Layout - Parameters", where the default fringe width is described. - - * frames.texi (Window Frame Parameters, Basic Parameters) - (Position Parameters, Layout Parameters, Management Parameters) - (Cursor Parameters, Font and Color Parameters): Add indexing for - frame parameters. (Bug#6929) - -2010-08-25 Tom Tromey - - * vol2.texi (Top): Update. - * vol1.texi (Top): Update. - * tips.texi (Library Headers): Mention Package-Version and - Package-Requires. - * package.texi: New file. - * os.texi (System Interface): Update pointers. - * elisp.texi (Top): Link to new nodes. Include package.texi. - * anti.texi (Antinews): Update pointers. - -2010-08-25 Eli Zaretskii - - * processes.texi (Filter Functions): Fix last change. - -2010-08-24 Markus Triska - - * processes.texi (Filter Functions): Use `buffer-live-p' instead - of `buffer-name' in the main text as well as in the example - (Bug#3098). - -2010-08-22 Chong Yidong - - * nonascii.texi (Text Representations): - * loading.texi (Loading Non-ASCII): - * compile.texi (Byte Compilation): Don't mention obsolete - --unibyte command-line argument. - -2010-08-22 Chong Yidong - - * modes.texi (Defining Minor Modes): Doc fix (Bug#6880). - -2010-08-22 Chong Yidong - - * objects.texi (Bool-Vector Type): Minor definition tweak (Bug#6878). - -2010-08-20 Eli Zaretskii - - * commands.texi (Misc Events): Add cross-references to where - POSITION of a mouse event is described in detail. - -2010-08-08 Christoph Scholtes - - * control.texi (Handling Errors) : Fix arg name. - -2010-08-08 Juanma Barranquero - - * modes.texi (Defining Minor Modes): Use C-backspace, not C-delete. - Suggested by Å těpán Němec . - -2010-08-08 Juanma Barranquero - - * minibuf.texi (High-Level Completion): Document args of - `read-buffer-function' (bug#5625). - -2010-07-29 Jan Djärv - - * frames.texi (Layout Parameters): Add doc for tool-bar-position. - -2010-07-29 Michael Albinus - - * processes.texi (Process Information): Explain process property - `remote-tty'. - -2010-07-27 Juanma Barranquero - - * modes.texi (Defining Minor Modes): Use C-delete in examples, - instead of "\C-\^?" (bug#6334). - - * text.texi (Special Properties): Fix typo. - -2010-07-09 Eli Zaretskii - - * internals.texi (Writing Emacs Primitives): Adapt to ANSI C - calling sequences, which are now the standard. - -2010-06-24 Chong Yidong - - * text.texi (Undo): Clarify command loop behavior (Bug#2433). - - * commands.texi (Command Overview): Mention undo-boundary call. - -2010-06-23 Glenn Morris - - * abbrevs.texi, commands.texi, compile.texi, debugging.texi: - * display.texi, edebug.texi, elisp.texi, eval.texi, files.texi: - * frames.texi, functions.texi, internals.texi, keymaps.texi: - * loading.texi, minibuf.texi, numbers.texi, os.texi, processes.texi: - * searching.texi, sequences.texi, strings.texi, syntax.texi: - * text.texi, tips.texi, vol1.texi, vol2.texi, windows.texi: - Untabify Texinfo files. - -2010-06-20 Chong Yidong - - * modes.texi (Minor Mode Conventions): Fix typo (Bug#6477). - -2010-06-19 Chong Yidong - - * errors.texi (Standard Errors): Remove unnecessary markup (Bug#6461). - -2010-06-02 Chong Yidong - - * searching.texi (Regexp Special): Remove obsolete information - about matching non-ASCII characters, and suggest using char - classes (Bug#6283). - -2010-05-30 Juanma Barranquero - - * minibuf.texi (Basic Completion): Add missing "@end defun". - -2010-05-30 Stefan Monnier - - * minibuf.texi (Basic Completion): Document completion-boundaries. - (Programmed Completion): Document the new fourth method for boundaries. - -2010-05-22 Chong Yidong - - * display.texi (Image Cache): Update documentation about image caching. - -2010-05-08 Å těpán Němec (tiny change) - - * windows.texi (Textual Scrolling): - * tips.texi (Coding Conventions): - * minibuf.texi (Minibuffer History): - * maps.texi (Standard Keymaps): - * loading.texi (Where Defined): - * edebug.texi (Instrumenting): Fix typos. - -2010-05-08 Chong Yidong - - * keymaps.texi (Menu Bar): Document :advertised-binding property. - - * functions.texi (Obsolete Functions): - Document set-advertised-calling-convention. - - * minibuf.texi (Basic Completion): Document completion-in-region. - (Programmed Completion): Document completion-annotate-function. - - * commands.texi (Reading One Event): Document read-key. - (Distinguish Interactive): Document KIND arg to - called-interactively-p. Delete obsolete interactive-p. - - * elisp.texi (Top): Update node description. - -2010-05-08 Eli Zaretskii - - * nonascii.texi (Character Properties): - Document unicode-category-table. Add an index entry for Unicode - general category. - -2010-05-07 Chong Yidong - - * Version 23.2 released. - -2010-04-20 Juanma Barranquero - - * locals.texi (Standard Buffer-Local Variables): - Remove @ignore'd reference to `direction-reversed'. - -2010-04-14 Juri Linkov - - Fix @deffn without category. - - * abbrevs.texi (Abbrev Expansion): Replace @deffn with @defun - for `abbrev-insert'. - - * buffers.texi (Indirect Buffers): Add category `Command' - to @deffn of `clone-indirect-buffer'. - - * windows.texi (Cyclic Window Ordering): Replace @deffn with @defun - for `next-window' and `previous-window'. Add category `Command' - to @deffn of `pop-to-buffer'. - -2010-04-01 Chong Yidong - - * nonascii.texi (Text Representations): Don't mark - enable-multibyte-characters as a user option. - -2010-03-31 Eli Zaretskii - - * control.texi (Handling Errors): How to re-throw a signal caught - by condition-case. - -2010-03-26 Chong Yidong - - * loading.texi (Hooks for Loading): Document after-load-functions. - Copyedits. - -2010-03-24 Arni Magnusson (tiny change) - - * frames.texi (Cursor Parameters): Fix typo. (Bug#5760) - -2010-03-24 Chong Yidong - - * processes.texi (Network Processes): Document seqpacket type. - -2010-03-20 Dan Nicolaescu - - * os.texi (System Environment): Do not mention lynxos. - -2010-03-10 Chong Yidong - - * Branch for 23.2. - -2010-03-06 Chong Yidong - - * objects.texi (Integer Type): Take note of the read syntax - exception for numbers that cannot fit in the integer type. - -2010-03-03 Glenn Morris - - * numbers.texi (Integer Basics, Bitwise Operations): - * objects.texi (Integer Type): Update for integers now being 30-bit. - -2010-02-27 Chong Yidong - - * display.texi (Low-Level Font): Document :otf font-spec property. - -2010-02-01 Stefan Monnier - - * display.texi (Line Height): Avoid obsolete special default variables - like default-major-mode. - -2010-01-28 Alan Mackenzie - - * display.texi (Auto Faces): Say fontification-functions is called - whether or not Font Lock is enabled. Tidy up the wording a bit. - -2010-01-17 Chong Yidong - - * elisp.texi: Remove duplicate edition information (Bug#5407). - -2010-01-17 Juanma Barranquero - - * two.el (volume-header-toc-markup): Fix typos in docstring. - -2010-01-04 Stefan Monnier - - Avoid dubious uses of save-excursions. - * positions.texi (Excursions): Recommend the use of - save-current-buffer if applicable. - * text.texi (Clickable Text): Fix the example code which used - save-excursion in a naive way which sometimes preserves point and - sometimes not. - * variables.texi (Creating Buffer-Local): - * os.texi (Session Management): - * display.texi (GIF Images): - * control.texi (Cleanups): Use (save|with)-current-buffer. - -2010-01-02 Eli Zaretskii - - * modes.texi (Example Major Modes): Fix indentation. (Bug#5195) - -2010-01-02 Chong Yidong - - * nonascii.texi (Text Representations, Character Codes) - (Converting Representations, Explicit Encoding) - (Translation of Characters): Use hex notation consistently. - (Character Sets): Fix map-charset-chars doc (Bug#5197). - -2010-01-01 Chong Yidong - - * loading.texi (Where Defined): Make it clearer that these are - loaded files (Bug#5068). - -2009-12-29 Chong Yidong - - * minibuf.texi (Completion Styles): Document `initials' style. - -2009-12-25 Chong Yidong - - * frames.texi (Resources): Describe inhibit-x-resources. - (Size Parameters): Copyedit. - - * hash.texi (Creating Hash): - * objects.texi (Hash Table Type): Document the new hash table - printed representation. - - * minibuf.texi (Basic Completion): 4th arg to all-completions is - obsolete. - - * processes.texi (Process Buffers): - Document process-kill-buffer-query-function. - -2009-12-05 Glenn Morris - - * hooks.texi (Standard Hooks): Remove diary-display-hook, replaced by - diary-display-function, and no longer recommended to be a hook. - Update for changes in the names of calendar and diary hooks. - diary-print-entries-hook has changed section. - -2009-11-28 Eli Zaretskii - - * text.texi (Special Properties): More accurate description of - what the `cursor' property does. - -2009-11-26 Kevin Ryde - - * commands.texi (Misc Events): vindex mouse-wheel-up-event and - mouse-wheel-down-event, the closest thing to a definition for them. - * os.texi (Startup Summary): vindex inhibit-startup-message and - inhibit-splash-screen. - (Command-Line Arguments): vindex argv. - (Suspending Emacs): vindex suspend-tty-functions and - resume-tty-functions. Don't want to index every hook, but having - the programming ones is helpful. - -2009-11-14 Chong Yidong - - * commands.texi (Motion Events): Fix typo (Bug#4907). - -2009-11-08 Chong Yidong - - * searching.texi (Char Classes): Note that [:upper:] and [:lower:] - are affected by case-fold-search (Bug#4483). - -2009-11-02 Chong Yidong - - * minibuf.texi (Reading File Names): Note that read-file-name may - use a graphical file dialog. - -2009-10-31 Glenn Morris - - * nonascii.texi (User-Chosen Coding Systems): Minor reword. (Bug#4817) - -2009-10-16 Kevin Ryde - - * files.texi (Magic File Names): Add @vindex file-name-handler-alist, - in particular so `info-lookup-symbol' can find its docs. - -2009-10-16 Chong Yidong - - * variables.texi (Constant Variables): Distinguish from defconst - variables. - (Defining Variables): Add cindex. - -2009-10-15 Chong Yidong - - * os.texi (Time of Day): Clarify that the microsecond part is - ignored (Bug#4637). - -2009-10-11 Glenn Morris - - * frames.texi (Size and Position): Clarify what is included in the frame - height. (Bug#4535) - -2009-10-10 Glenn Morris - - * windows.texi (Size of Window): The relationship between window and - frame heights is not so simple. (Bug#4535) - Mention window-full-height-p. - -2009-10-07 Stefan Monnier - - * positions.texi (Text Lines): Remove goto-line, since it shouldn't be - used from Lisp. - -2009-10-07 Eli Zaretskii - - * files.texi (Directory Names) : - Document that root home directories are not replaced with "~". - -2009-10-06 Eli Zaretskii - - * text.texi (Special Properties): Document the meaning of the - `cursor' text property whose value is an integer. - -2009-10-05 Michael Albinus - - * files.texi (Magic File Names): Add `copy-directory'. - -2009-10-05 Eli Zaretskii - - * files.texi (File Attributes): Fix description of file - attributes. (Bug#4638) Update attributes of files.texi example to - be more representative. - -2009-10-05 Michael Albinus - - * files.texi (Create/Delete Dirs): New command copy-directory. - -2009-10-04 Juanma Barranquero - - * anti.texi (Antinews): - * macros.texi (Indenting Macros): - * strings.texi (Creating Strings, Case Conversion): - Remove duplicate words. - -2009-10-01 Michael Albinus - - * files.texi (Create/Delete Dirs): delete-directory has an - optional parameter RECURSIVE. - -2009-10-01 Stefan Monnier - - * buffers.texi (Swapping Text): Minor clarification. - -2009-10-01 Glenn Morris - - * functions.texi (Declaring Functions): Mention that we also search for - ".m" files in the src/ directory. - -2009-09-25 David Engster - - * display.texi (Managing Overlays): Document copy-overlay (Bug#4549). - -2009-09-22 Glenn Morris - - * internals.texi (Building Emacs): Mention preloaded-file-list. - -2009-09-14 Alan Mackenzie - - * os.texi (Terminal Output): Put "@code{}" around "stdout". - -2009-09-13 Chong Yidong - - * functions.texi (Anonymous Functions): Rearrange discussion, - giving usage of unquoted lambda forms first. Mention that - `function' and `#'' are no longer required (Bug#4290). - -2009-09-11 Alan Mackenzie - - * os.texi (Terminal Output): Document `send-string-to-terminal' in - batch mode. - -2009-09-01 Glenn Morris - - * display.texi (Face Functions): Mention define-obsolete-face-alias. - -2009-08-26 Ulrich Mueller - - * nonascii.texi (Character Codes): Fix typos. - -2009-08-25 Michael Albinus - - * processes.texi (Synchronous Processes): New defvar - process-file-side-effects. - -2009-08-25 Glenn Morris - - * display.texi (Fontsets): Fix typo. - - * files.texi (Format Conversion Round-Trip): Mention nil regexp. - -2009-08-19 Stefan Monnier - - * processes.texi (Asynchronous Processes): Adjust arglist of - start-process-shell-command and start-file-process-shell-command. - -2009-08-15 Chong Yidong - - * advice.texi (Argument Access in Advice): Note that argument - positions are zero-based (Bug#3932). - - * commands.texi (Distinguish Interactive): Minor copyedit. - - * display.texi (Face Attributes): Add xref to Displaying Faces for - explanation of "underlying face". - - * customize.texi (Common Keywords): Add xref to Loading. - - * loading.texi (How Programs Do Loading): Add xref to Lisp - Libraries node in the Emacs manual. - -2009-08-13 Chong Yidong - - * objects.texi (Meta-Char Syntax): Add xref to Strings of Events. - -2009-07-18 Chong Yidong - - * processes.texi (Shell Arguments): Copyedits. - -2009-07-18 Glenn Morris - - * loading.texi (Repeated Loading): Fix typo. - -2009-07-16 Richard Stallman - - * buffers.texi (Swapping Text): Recommend setting - write-region-annotate-functions and buffer-saved-size. - - * backups.texi (Auto-Saving): Document buffer-saved-size = -2. - -2009-07-15 Glenn Morris - - * edebug.texi: Minor re-phrasings throughout. - (Edebug Execution Modes): Sit-for affects continue mode too. - (Jumping): Use `forward-sexp' rather than its keybinding. - (Edebug Misc): Fix Q binding. - (Edebug Eval): Remove cl version. - (Printing in Edebug): Clarify print-length etc. - (Instrumenting Macro Calls): Defopt edebug-eval-macro-args. - (Specification List): Remove edebug-unwrap findex entry. - (Specification Examples): defmacro is actually not the same as defun. - Escape "`" in example. - -2009-07-15 Chong Yidong - - * markers.texi (The Mark): Document optional arg to - deactivate-mark. - -2009-07-11 Kevin Ryde - - * hooks.texi (Standard Hooks): Fix cross-references. - - * loading.texi (Named Features): Refer to eval-after-load. - -2009-07-11 Glenn Morris - - * Makefile.in (TEXI2PDF): New. - (elisp.pdf): New target. - - * searching.texi (Regexp Backslash): Fix typo. - - * elisp.texi (Top): Display copyright notice at start of non-TeX. - -2009-07-10 Glenn Morris - - * elisp.texi, vol1.texi, vol2.texi: Update @detailmenu. - - * customize.texi (Customization Types): - * display.texi (Abstract Display): - * objects.texi (Character Type, String Type): - Merge in some menu descriptions from elisp.texi. - - * hash.texi (Hash Tables): - * modes.texi (Multiline Font Lock): - End menu description with period. - -2009-07-09 Glenn Morris - - * back.texi: Don't hard-code texinfo location. - - * two-volume.make (texinfodir): New, with location of texinfo.tex. - (tex): Add texinfodir to TEXINPUTS. - (elisp1med-init, elisp2med-init): Use texinfodir. - - * Makefile.in (texinfodir): Rename from usermanualdir, and update. - (clean): Add two-volume.make intermediate files. - - * elisp.texi, vol1.texi, vol2.texi: - Use a DATE variable with the publication date, and update it. - Fix antinews menu description. - - * vol1.texi, vol2.texi: Update VERSION to match elisp.texi. - Update the detailed node listing to match elisp.texi. - - * README: Update edition to match elisp.texi. - - * objects.texi (General Escape Syntax): - * nonascii.texi (Character Sets): - Use consistent case for "Unicode Standard". - - * anti.texi (Antinews): - * customize.texi (Variable Definitions): - * functions.texi (Declaring Functions): - * nonascii.texi (Character Properties): - * processes.texi (Serial Ports): - * text.texi (Special Properties): - * tips.texi (Coding Conventions): - Minor rearrangements to improve TeX line-filling. - - * commands.texi (Using Interactive): Fix cross-reference. - -2009-07-01 Jan Djärv - - * frames.texi (Management Parameters): Mention sticky. - -2009-07-01 Andreas Schwab - - * help.texi (Help Functions): Fix description of help-buffer and - help-setup-xref to use @defun instead of @deffn. - -2009-07-01 Jan Djärv - - * frames.texi (Size Parameters): Mention maximized for fullscreen. - -2009-06-24 Chong Yidong - - * display.texi (Window Systems): Add ns to the list. - -2009-06-21 Chong Yidong - - * Branch for 23.1. - -2009-06-17 Martin Rudalics - - * windows.texi (Dedicated Windows): Fix typo. - (Resizing Windows): Replace @defun by @deffn. - -2009-06-17 Glenn Morris - - * variables.texi (Directory Local Variables): - Update for 2009-04-11 name-change of dir-locals-directory-alist. - -2009-06-09 Kenichi Handa - - * nonascii.texi (Character Sets): State clearly that FROM and TO - are codepoints of CHARSET. - -2009-06-07 Chong Yidong - - * minibuf.texi (Reading File Names): Fix introductory text. - Suggested by stan@derbycityprints.com. - (High-Level Completion): Fix typo. - -2009-05-28 Chong Yidong - - * frames.texi (Text Terminal Colors): Multi-tty is already - implemented, but tty-local colors are not. - -2009-05-27 Chong Yidong - - * hooks.texi (Standard Hooks): Remove mention of obsolete - redisplay-end-trigger-functions. - - * internals.texi (Window Internals): Remove mention of obsolete - redisplay-end-trigger-functions. - -2009-05-21 Martin Rudalics - - * abbrevs.texi (Abbrev Mode): abbrev-mode is an option. - - * backups.texi (Making Backups): backup-directory-alist and - make-backup-file-name-function are options. - (Auto-Saving): auto-save-list-file-prefix is an option. - - * buffers.texi (Killing Buffers): buffer-offer-save is an - option. - - * display.texi (Refresh Screen): no-redraw-on-reenter is an - option. - (Echo Area Customization): echo-keystrokes is an option. - (Selective Display): selective-display-ellipses is an option. - (Temporary Displays): temp-buffer-show-function is an option. - (Face Attributes): underline-minimum-offset and x-bitmap-file-path - are options. - (Font Selection): face-font-family-alternatives, - face-font-selection-order, face-font-registry-alternatives, and - scalable-fonts-allowed are options. - (Fringe Indicators): indicate-buffer-boundaries is an option. - (Fringe Cursors): overflow-newline-into-fringe is an option. - (Scroll Bars): scroll-bar-mode is an option. - - * eval.texi (Eval): max-lisp-eval-depth is an option. - - * files.texi (Visiting Functions): find-file-hook is an option. - (Directory Names): directory-abbrev-alist is an option. - (Unique File Names): temporary-file-directory and - small-temporary-file-directory are options. - - * frames.texi (Initial Parameters): initial-frame-alist, - minibuffer-frame-alist and default-frame-alist are options. - (Cursor Parameters): blink-cursor-alist and - cursor-in-non-selected-windows ar options. - (Window System Selections): selection-coding-system is an - option. - (Display Feature Testing): display-mm-dimensions-alist is an - option. - - * help.texi (Help Functions): help-char and help-event-list are - options. - - * keymaps.texi (Functions for Key Lookup): meta-prefix-char is - an option. - - * minibuf.texi (Minibuffer History): history-length and - history-delete-duplicates are options. - (High-Level Completion): read-buffer-function and - read-buffer-completion-ignore-case are options. - (Reading File Names): read-file-name-completion-ignore-case is - an option. - - * modes.texi (Mode Line Top): mode-line-format is an option. - (Mode Line Variables): mode-line-position and mode-line-modes - are options. - - * nonascii.texi (Text Representations): - enable-multibyte-characters is an option. - (Default Coding Systems): auto-coding-regexp-alist, - file-coding-system-alist, auto-coding-alist and - auto-coding-functions are options. - (Specifying Coding Systems): inhibit-eol-conversion is an - option. - - * os.texi (Init File): site-run-file is an option. - (System Environment): mail-host-address is an option. - (User Identification): user-mail-address is an option. - (Terminal Output): baud-rate is an option. - - * positions.texi (Word Motion): words-include-escapes is an - option. - - * searching.texi (Standard Regexps): page-delimiter, - paragraph-separate, paragraph-separate and sentence-end are - options. - - * text.texi (Margins): left-margin and fill-nobreak-predicate - are options. - - * variables.texi (Local Variables): max-specpdl-size is an - option. - - * windows.texi (Choosing Window): - split-window-preferred-function, special-display-function and - display-buffer-function are options. - -2009-05-20 Chong Yidong - - Fix errors spotted by Martin Rudalics. - - * syntax.texi (Position Parse): Document rationale for ignored - arguments to syntax-ppss-flush-cache. - - * processes.texi (Input to Processes): Mark PROCESS arg to - process-running-child-p as optional. - (Network Options): Document NO-ERROR arg to - set-network-process-option. - - * buffers.texi (Indirect Buffers): Mark clone-indirect-buffer as a - command. - - * searching.texi (POSIX Regexps): Mark posix-search-forward and - posix-search-backward as commands. - - * os.texi (Killing Emacs): Mark kill-emacs as a command. - (Suspending Emacs): Mark suspend-emacs as a command. - (Processor Run Time): Mark emacs-uptime and emacs-init-time as - commands. - (Terminal Output): Remove obsolete function baud-rate. - Document TERMINAL arg for send-string-to-terminal. - - * nonascii.texi (Terminal I/O Encoding): Document TERMINAL arg for - terminal-coding-system and set-terminal-coding-system. - (Explicit Encoding): Mark DESTINATION arg of decode-coding-region - as optional. - (Character Sets): Document RESTRICTION arg of char-charset. - (Character Codes): Mark POS argument to get-byte as optional. - - * minibuf.texi (Minibuffer Misc): Document ARGS arg for - minibuffer-message. - - * files.texi (Create/Delete Dirs): Mark make-directory and - delete-directory as commands. - - * abbrevs.texi (Abbrev Tables): Fix arglist for make-abbrev-table. - - * text.texi (Base 64): Mark base64-decode-string and - base64-encode-string as commands. - (Columns): Mark move-to-column as a command. - (Mode-Specific Indent): Document RIGID arg to - indent-for-tab-command. - (Region Indent): Mark TO-COLUMN arg to indent-region as optional. - Mark indent-code-rigidly as a command. - (Substitution): Mark translate-region as a command. - - * frames.texi (Size and Position): Remove obsolete functions - screen-height and screen-width. - -2009-05-19 Chong Yidong - - * windows.texi (Cyclic Window Ordering, Cyclic Window Ordering) - (Displaying Buffers, Resizing Windows): Correct mistakes; - next-window, previous-window, and pop-to-buffer are not commands, - and fit-window-to-buffer" is a command. (Pointed out by Martin - Rudalics.) - -2009-05-17 Richard M Stallman - - * modes.texi (Precalculated Fontification): Clarify text. - -2009-05-17 Martin Rudalics - - * windows.texi (Selecting Windows): Clarify descriptions of - with-selected-window and get-lru-window. - (Cyclic Window Ordering): Refer to particular frame when talking - about how splitting affects the ordering. - (Displaying Buffers): Fix descriptions of switch-to-buffer and - switch-to-buffer-other-window. Explain how setting of - display-buffer-reuse-frames affects pop-to-buffer. - (Choosing Window): Clarify some details in descriptions of - display-buffer-reuse-frames, pop-up-frames, and - pop-up-frame-function. - (Dedicated Windows): Clarify some details. - (Textual Scrolling): Replace term vscroll by term vertical - scroll position. - (Vertical Scrolling): Fix typo. - (Window Hooks): Relate text on jit-lock-register to window - scrolling and size changes. - -2009-05-14 Chong Yidong - - * frames.texi (Initial Parameters): Clarify what the initial - minibuffer frame is. - (Buffer Parameters): Note that the minibuffer parameter can not be - altered. - - * anti.texi (Antinews): Copyedits. Rearrange some entries. - Document display-buffer changes. - -2009-05-13 Chong Yidong - - * anti.texi (Antinews): Rewrite for Emacs 22. - - * abbrevs.texi (Abbrevs): Add xref to Creating Symbols when - obarrays are first mentioned. Define "system abbrev" more - prominently, and add it to the index. - (Abbrev Mode, Abbrev Tables, Defining Abbrevs, Abbrev Properties): - Copyedits. - (Abbrev Expansion): Document abbrev-insert. - -2009-05-12 Chong Yidong - - * frames.texi (Font and Color Parameters): Rename from Color - Parameters. Document font-backend parameter. - - * vol2.texi (Top): Update node listing. - * vol1.texi (Top): Update node listing. - * elisp.texi (Top): Update node listing. - -2009-05-11 Martin Rudalics - - * windows.texi (Choosing Window): Don't explicitly refer to - split-window-sensibly's window argument in descriptions of - split-height-threshold and split-width-threshold. - -2009-05-10 Martin Rudalics - - * windows.texi (Choosing Window): Fix rewrite of window - splitting section. - -2009-05-09 Eli Zaretskii - - * nonascii.texi (Default Coding Systems): - Document find-auto-coding, set-auto-coding, and auto-coding-alist. - Add indexing. - (Lisp and Coding Systems): Add index entries. - -2009-05-09 Martin Rudalics - - * windows.texi (Choosing Window): Describe split-window-sensibly - and rewrite section on window splitting accordingly. - (Textual Scrolling): Replace `...' by @code{...}. - -2009-05-04 Chong Yidong - - * hooks.texi (Standard Hooks): Add abbrev-expand-functions. - Remove obsoleted pre-abbrev-expand-hook. - - * locals.texi (Standard Buffer-Local Variables): Consolidate table - entries. - - * internals.texi (Object Internals): Don't assume 32-bit machines - are the norm. - (Buffer Internals): Consolidate table entries for readability. - (Window Internals): Synch field names to window.h. - (Process Internals): Synch field names to process.h. - -2009-04-29 Chong Yidong - - * variables.texi (File Local Variables): Note that read-circle is - bound to nil when reading file-local variables. - - * streams.texi (Input Functions): Document read-circle. - (Output Variables): Add xref to Circular Objects. - -2009-04-25 Chong Yidong - - * tips.texi (Coding Conventions): Copyedits. Add xref to Named - Features and Coding System Basics. Node that "p" stands for - "predicate". Recommend utf-8-emacs instead of emacs-mule. - (Key Binding Conventions): Emacs does use S-down-mouse-1, for - mouse-appearance-menu. - (Programming Tips): Add xref to Progress. - -2009-04-22 Chong Yidong - - * os.texi (Command-Line Arguments): - Document command-line-args-left. - (Suspending Emacs): Adapt text to multi-tty case. Document use of - terminal objects for tty arguments. - (Startup Summary): Add xref to Session Management. - (Session Management): Mention emacs-session-restore. Copyedits. - -2009-04-20 Chong Yidong - - * os.texi (Startup Summary): Copyedits. The init file is not - necessarily named .emacs now. Document initial-buffer-choice and - initial-scratch-message. Note where Emacs exits in batch mode. - Document inhibit-splash-screen as an alias. - (Init File): Be neutral about which init file name to use. - -2009-04-16 Chong Yidong - - * os.texi (System Interface): Fix Texinfo usage. - -2009-04-15 Chong Yidong - - * searching.texi (Regexp Backslash): Also refer to shy groups as - non-capturing or unnumbered groups. - (Regexp Functions): Add cross-reference to Regexp Backslash. - - * display.texi (Truncation): Overlays can use line-prefix and - wrap-prefix too. - (Overlay Properties): Document wrap-prefix and line-prefix. - (Face Attributes): Document underline-minimum-offset. - (Face Remapping): Copyedits. - (Low-Level Font): Copyedits. - (Image Cache): Note that the image cache is shared between frames. - (Line Height): Emphasize that line-spacing only takes effect on - graphical terminals. - -2009-04-13 Chong Yidong - - * display.texi (Refresh Screen): Note that a passage about screen - refreshing is text terminal only. - (Forcing Redisplay): Delete misleading comment---sit-for calls - redisplay, not the other way around. - (Truncation): Note new values of truncate-partial-width-windows. - Copyedits. - (Invisible Text): Document invisible-p. - -2009-04-11 Eli Zaretskii - - * display.texi (Overlays): Overlays don't scale well. See - http://lists.gnu.org/archive/html/emacs-devel/2009-04/msg00243.html. - -2009-04-10 Chong Yidong - - * syntax.texi (Syntax Table Functions): Document cons cell - argument for modify-syntax-entry. - (Categories): Document cons cell argument for - modify-category-entry. - - * searching.texi (String Search): Document word-search-forward-lax - and word-search-backward-lax. - (Searching and Case): Describe isearch behavior more precisely. - - * keymaps.texi (Tool Bar): Mention that some platforms do not - support multi-line toolbars. Suggested by Stephen Eglen. - - * frames.texi (Layout Parameters): Mention that Nextstep also - allows only one tool-bar line. Suggested by Stephen Eglen. - - * nonascii.texi (Text Representations): Copyedits. - (Coding System Basics): Also mention utf-8-emacs. - (Converting Representations, Selecting a Representation) - (Scanning Charsets, Translation of Characters, Encoding and I/O): - Copyedits. - (Character Codes): Mention role of codepoints 1114112 to 4194175. - -2009-04-09 Chong Yidong - - * text.texi (Yank Commands): Note that yank uses push-mark. - (Filling): Clarify REGION argument of fill-paragraph. - Document fill-forward-paragraph-function. - (Special Properties): Remove "new in Emacs 22" declaration. - (Clickable Text): Merge with Links and Mouse-1 node. - - * display.texi (Button Properties, Button Buffer Commands): - Change xref to Clickable Text. - - * tips.texi (Key Binding Conventions): Change xref to Clickable - Text. - - * elisp.texi (Top): Update node listing. - -2009-04-05 Chong Yidong - - * markers.texi (The Mark): Copyedits. Improve description of - handle-shift-selection. - (The Region): Move use-region-p here from The Mark. - - * positions.texi (Screen Lines): Document (cols . lines) argument - for vertical-motion. - -2009-04-04 Chong Yidong - - * frames.texi (Frames): Clean up introduction. Document `ns' - return value for framep. - (Creating Frames): Note how the terminal is chosen. - (Multiple Terminals, Multiple Displays): Merge into a single node. - (Color Parameters): Fix typo. - - * variables.texi (Local Variables, Buffer-Local Variables) - (Creating Buffer-Local): Change link to Multiple Terminals. - - * os.texi (X11 Keysyms): Change link to Multiple Terminals. - - * keymaps.texi (Controlling Active Maps): Change link to Multiple - Terminals. - - * commands.texi (Command Loop Info, Keyboard Macros): Change link - to Multiple Terminals. - - * elisp.texi (Top): Update node listing. - * vol2.texi (Top): Update node listing. - * vol1.texi (Top): Update node listing. - - * buffers.texi (Current Buffer): Note that the append-to-buffer - example is no longer in synch with the latest code. Tie the two - examples together. - - * files.texi (File Attributes): Move note about MS-DOS from - Changing Files to File Attributes. - (Create/Delete Dirs): Note that mkdir is an alias for this. - -2009-04-01 Markus Triska - - * processes.texi (Filter Functions): Suggest how to handle output - batches. - -2009-03-30 Chong Yidong - - * help.texi (Accessing Documentation): Update example to use - help-setup-xref and with-help-window. - (Help Functions): Remove print-help-return-message, which is - semi-obsolete due to with-help-window. Document help-buffer and - help-setup-xref. - -2009-03-29 Chong Yidong - - * help.texi (Accessing Documentation, Help Functions): - Remove information about long-obsolete Emacs versions. - - * modes.texi (Mode Line Variables): The default values of the mode - line variables are now more complicated. - -2009-03-28 Chong Yidong - - * modes.texi (Major Mode Conventions): Note that specialness is - inherited. - (Derived Modes): Note that define-derive-mode sets the mode-class - property. - - * keymaps.texi (Prefix Keys): The M-g prefix key is now named - goto-map. Add search-map to the list. - -2009-03-27 Eli Zaretskii - - * os.texi (System Environment): Update the list of system-type - values. - - * markers.texi (The Mark) : Update for - removal of the optional argument DEACTIVATE. - -2009-03-25 Chong Yidong - - * commands.texi (Focus Events): Most X window managers don't use - focus-follows-mouse nowadays. - -2009-03-24 Chong Yidong - - * commands.texi (Defining Commands): Clarify introduction. - (Using Interactive): Not that interactive can be put in a symbol - property. - (Interactive Call): Note that a symbol with a non-nil - interactive-form property satisfies commandp. - -2009-03-23 Juanma Barranquero - - * minibuf.texi (Intro to Minibuffers): Fix typos. - -2009-03-23 Chong Yidong - - * minibuf.texi (Intro to Minibuffers): Remove long-obsolete info - about minibuffers in old Emacs versions. Copyedits. - Emphasize that enable-recursive-minibuffers defaults to nil. - (Text from Minibuffer): Simplify introduction. - -2009-03-22 Alan Mackenzie - - * commands.texi (Using Interactive): Clarify string argument to - `interactive' - even promptless elements need \n separators. - -2009-03-18 Chong Yidong - - * minibuf.texi (Completion Styles): New node. - - * elisp.texi (Top): Update node listing. - -2009-03-17 Chong Yidong - - * minibuf.texi (Basic Completion): Note that - read-file-name-completion-ignore-case and - read-buffer-completion-ignore-case can override - completion-ignore-case. - (Minibuffer Completion): Document completing-read changes. - (Completion Commands): Avoid mentioning partial completion mode. - Document minibuffer-completion-confirm changes, and - minibuffer-confirm-exit-commands. - (High-Level Completion): Document new require-match behavior for - read-buffer. Document read-buffer-completion-ignore-case. - (Reading File Names): Document new require-match behavior for - read-file-name. - -2009-03-14 Chong Yidong - - * debugging.texi (Error Debugging): Don't mislead the reader into - thinking that debug-on-error enters debugger for C-f at EOB. - (Error Debugging): Setting debug-on-init within the init file - works, and has for some time. - -2009-03-13 Kenichi Handa - - * display.texi (Fontsets): Update the description. - -2009-03-13 Chong Yidong - - * advice.texi (Advising Primitives): Link to What Is a Function. - -2009-03-12 Chong Yidong - - * compile.texi (Speed of Byte-Code): Update example. - (Disassembly): Update examples. - - * loading.texi (Repeated Loading): Simplify examples. - - * customize.texi (Common Keywords): It's not necessary to use :tag - to remove hyphens, as custom-unlispify-tag-name does it - automatically. - (Variable Definitions): Link to File Local Variables. - Document customized-value symbol property. - (Customization Types): Move menu to end of node. - -2009-03-10 Chong Yidong - - * macros.texi (Compiling Macros): Omit misleading sentence, which - implied that macros can only be used in the same file they are - defined. - (Backquote): Remove obsolete information about Emacs 19. - -2009-03-05 John Foerch (tiny change) - - * display.texi (Display Margins): Fix paren typo. - -2009-02-27 Chong Yidong - - * elisp.texi (Top): Update node listing. - - * variables.texi (Variables): Clarify introduction. - (Global Variables): Mention that setq is a special form. - (Local Variables): Use active voice. - (Tips for Defining): Mention marking variables as safe. - (Buffer-Local Variables): Mention terminal-local and frame-local - variables together. - (File Local Variables): Copyedits. - (Frame-Local Variables): Note that they are not really useful. - (Future Local Variables): Node deleted. - - * objects.texi (General Escape Syntax): Update explanation of - Unicode escape syntax. - -2009-02-23 Chong Yidong - - * control.texi (Control Structures): Add cindex entry for "textual - order". - - * eval.texi (Intro Eval): Copyedits. Standardize on "form" - instead of "expression" throughout. - (Function Indirection): Copyedits. Use active voice. - (Eval): The default value of max-lisp-eval-depth is now 400. - -2009-02-23 Miles Bader - - * processes.texi (System Processes): Rename `system-process-attributes' - to `process-attributes'. - -2009-02-22 Chong Yidong - - * symbols.texi (Property Lists): Emphasize that property lists are - not restricted to symbol cells. - (Other Plists): Copyedit. - - * sequences.texi (Sequences Arrays Vectors): Make introduction - more concise. - (Arrays): Mention char-tables and bool-vectors too. - (Vectors): Don't repeat information given in Arrays node. Link to - nodes that explain the vector usage examples. - (Char-Tables): Note that char-table elements can have arbitrary - type. Explain effect of omitted char-table-extra-slots property. - Link to Property Lists node. - -2009-02-22 Chong Yidong - - * lists.texi (Building Lists): Remove obsolete Emacs 20 usage of - `append'. - (List Elements): Copyedits. - - * sequences.texi (Vector Functions): Remove obsolete Emacs 20 use - of `vconcat'. - - * strings.texi (Creating Strings): Copyedits. Remove obsolete - Emacs 20 usage of `concat'. - (Case Conversion): Copyedits. - -2009-02-21 Chong Yidong - - * objects.texi (Lisp Data Types, Syntax for Strings, Buffer Type): - Minor edits. - (Frame Configuration Type): Emphasize that it is not primitive. - (Font Type): New node. - (Type Predicates): Add fontp; type-of now recognizes font object - types. - - * intro.texi (Version Info): Update version numbers in examples. - (Acknowledgements): List more contributors. - - * elisp.texi: Bump version number to 3.0. - (Top): Link to Font Type node. - -2009-02-20 Juanma Barranquero - - * modes.texi (Major Mode Conventions): Remove duplicate words. - (Customizing Keywords): Fix typo. - -2009-02-14 Eli Zaretskii - - * nonascii.texi (User-Chosen Coding Systems): Document that - select-safe-coding-system suggests raw-text if there are raw bytes - in the region. - (Explicit Encoding): Warn not to use `undecided' when encoding. - -2009-02-11 Glenn Morris - - * frames.texi (Visibility of Frames): Mention the effect multiple - workspaces/desktops can have on visibility. - -2009-02-07 Eli Zaretskii - - * text.texi (Commands for Insertion): - * commands.texi (Event Mod): - * keymaps.texi (Searching Keymaps): - * nonascii.texi (Translation of Characters): - Reinstate documentation of translation-table-for-input. - (Explicit Encoding): Document the `charset' text property produced - by decode-coding-region and decode-coding-string. - -2009-01-27 Alan Mackenzie - - * modes.texi (Search-based Fontification): Correct a typo. - -2009-01-25 Juanma Barranquero - - * abbrevs.texi (Abbrev Table Properties): Fix typo. - Reported by Seweryn Kokot . (Bug#2039) - -2009-01-24 Eli Zaretskii - - * display.texi (Window Systems): Document the value of - `initial-window-system' under --daemon. - - * os.texi (System Environment): Remove description of the - `environment' function which has been deleted. - -2009-01-22 Dan Nicolaescu - - * frames.texi (Multiple Displays): Remove documentation for - removed function make-frame-on-tty. - -2009-01-22 Chong Yidong - - * files.texi (Format Conversion Piecemeal): Clarify behavior of - write-region-annotate-functions. - Document write-region-post-annotation-function. - -2009-01-19 Chong Yidong - - * display.texi (Font Lookup): Document WIDTH argument of - x-list-fonts. - -2009-01-17 Eli Zaretskii - - * maps.texi (Standard Keymaps): Rename function-key-map to - local-function-key-map. - - * keymaps.texi (Translation Keymaps): Rename function-key-map to - local-function-key-map. - - * nonascii.texi (Terminal I/O Encoding): `keyboard-coding-system' - and `set-keyboard-coding-system' now accept an optional terminal - argument. - - * commands.texi (Event Mod): `keyboard-translate-table' is now - terminal-local. - (Function Keys): Rename function-key-map to - local-function-key-map. - - * elisp.texi (Top): Make @detailmenu be consistent with changes in - frames.texi. - - * hooks.texi (Standard Hooks): Document `delete-frame-functions' - `delete-terminal-functions', `suspend-tty-functions' and - `resume-tty-functions'. - - * frames.texi (Frames): Document `frame-terminal' and - `terminal-live-p'. - (Multiple Displays): Document `make-frame-on-tty'. - (Multiple Terminals): Document `terminal-list', `delete-terminal', - `terminal-name', and `get-device-terminal'. - (Terminal Parameters): Document `terminal-parameters', - `terminal-parameter', and `set-terminal-parameter'. - - * os.texi (System Environment): Document `environment' and - `initial-environment'. - (Suspending Emacs): Update for multi-tty; document - `suspend-tty', `resume-tty', and `controlling-tty-p'. - - * nonascii.texi (Coding System Basics): More accurate description - of `raw-text'. - -2009-01-12 Juanma Barranquero - - * display.texi (Low-Level Font): Fix typo. - -2009-01-10 Chong Yidong - - * elisp.texi (Top): Update node listing. - - * display.texi (PostScript Images): Node deleted. - -2009-01-10 Eli Zaretskii - - * processes.texi (Decoding Output): Document that null bytes force - no-conversion for reading process output. - - * files.texi (Reading from Files): Document that null bytes force - no-conversion when visiting files. - - * processes.texi (Serial Ports): Improve wording, suggested by RMS. - - * nonascii.texi (Lisp and Coding Systems): - Document inhibit-null-byte-detection and inhibit-iso-escape-detection. - (Character Properties): Improve wording. - -2009-01-09 Chong Yidong - - * display.texi (Font Lookup): Remove obsolete function - x-font-family-list. x-list-fonts accepts Fontconfig/GTK syntax. - (Low-Level Font): Rename from Fonts, move to end of Faces section. - (Font Selection): Reorder order of variable descriptions. - Minor clarifications. - - * elisp.texi (Top): Update node listing. - -2009-01-09 Glenn Morris - - * commands.texi (Command Loop Info): Say that last-command-char and - last-input-char are obsolete aliases. - - * edebug.texi (Edebug Recursive Edit): Remove separate references to - last-input-char and last-command-char, since they are just aliases for - last-input-event and last-command-event. - - * minibuf.texi (Minibuffer Commands): Use last-command-event rather than - last-command-char. - -2009-01-08 Chong Yidong - - * elisp.texi: Update node listing. - - * display.texi (Faces): Put Font Selection node after Auto Faces. - (Face Attributes): Don't link to Font Lookup. - Document font-family-list. - (Fonts): New node. - -2009-01-08 Jason Rumney - - * frames.texi (Pointer Shape): Clarify that only X supports - changing the standard pointer shapes. (Bug#1485) - -2009-01-08 Chong Yidong - - * display.texi (Attribute Functions): Note that a function value - :height is relative, and that compatibility functions work by - calling set-face-attribute. - (Displaying Faces): Reorder list in order of increasing priority. - (Face Remapping): New node. Content moved here from Displaying - Faces. - (Glyphs): Link to Face Functions. - -2009-01-08 Chong Yidong - - * display.texi (Faces): Don't discuss face id here. facep does - not return t. - (Defining Faces): Minor clarification. - (Face Attributes): Rearrange items to match docstring of - set-face-attribute. Add :foundry attribute. Document new role of - :font attribute. Texinfo usage fix. - (Attribute Functions): Copyedits. - (Face Functions): Note that face number is seldom used. - -2009-01-05 Richard M Stallman - - * strings.texi (Predicates for Strings): Minor clarification. - - * functions.texi (Function Safety): Texinfo usage fix. - -2009-01-04 Eduard Wiebe (tiny change) - - * objects.texi (General Escape Syntax): Fix typo. - -2009-01-03 Martin Rudalics - - * windows.texi (Choosing Window): Say that pop-up-frame-alist - works via the default value of pop-up-frame-function. - -2009-01-02 Eli Zaretskii - - * processes.texi (System Processes): Document the `time' and - `ctime' attributes of `system-process-attributes'. - -2009-01-01 Chong Yidong - - * display.texi (Face Attributes): Clarify :height attribute. - -2008-12-31 Martin Rudalics - - * buffers.texi (The Buffer List): Clarify what moves a buffer to - the front of the buffer list. Add entries for `last-buffer' and - `unbury-buffer'. - -2008-12-27 Eli Zaretskii - - * elisp.texi (Top): Add @detailmenu items for "Multiple Terminals" - and its subsections. - - * frames.texi (Multiple Terminals, Low-level Terminal) - (Terminal Parameters, Frames on Other TTY devices): New sections. - (Frames): Add an xref to "Multiple Terminals". - - * elisp.texi (Top): Add @detailmenu item for "Terminal Type". - - * objects.texi (Terminal Type): New node. - (Editing Types): Add it to the menu. - - * elisp.texi (Top): Add a @detailmenu item for "Directory Local - Variables". - - * variables.texi (Directory Local Variables): New node. - (Variables): Add a menu item for it. - - * loading.texi (Autoload): Document `generate-autoload-cookie' and - `generated-autoload-file'. - -2008-12-20 Eli Zaretskii - - * os.texi (Startup Summary): Add xref to documentation of - `initial-window-system'. - - * display.texi (Window Systems): Document `window-system' the - function. The variable `window-system' is now frame-local. - Document `initial-window-system'. - -2008-12-19 Martin Rudalics - - * windows.texi (Windows): Rewrite description of - fit-window-to-buffer. - -2008-12-13 Glenn Morris - - * modes.texi (Font Lock Basics): Fix level description. (Bug#1534) - (Levels of Font Lock): Refer to font-lock-maximum-decoration. - -2008-12-12 Glenn Morris - - * debugging.texi (Error Debugging): Refer forwards to - eval-expression-debug-on-error. - -2008-12-05 Eli Zaretskii - - * strings.texi (String Basics): Only unibyte strings that - represent key sequences hold 8-bit raw bytes. - - * nonascii.texi (Coding System Basics): Rewrite @ignore'd - paragraph to speak about `undecided'. - (Character Properties): Don't explain the meaning of each - property; instead, identify their Unicode Standard names. - (Character Sets): Document `map-charset-chars'. - -2008-12-02 Glenn Morris - - * files.texi (Format Conversion Round-Trip): Rewrite format-write-file - section yet again. - -2008-11-29 Eli Zaretskii - - * nonascii.texi (Character Properties): New Section. - (Specifying Coding Systems): Document - `coding-system-priority-list', `set-coding-system-priority', and - `with-coding-priority'. - (Lisp and Coding Systems): Document `check-coding-systems-region' - and `coding-system-charset-list'. - (Coding System Basics): Document `coding-system-aliases'. - - * elisp.texi (Top): Add a @detailmenu entry for "Character - Properties". - - * objects.texi (Character Type): Correct the range of Emacs - characters. Add an @xref to "Character Codes". - - * strings.texi (String Basics): Add an @xref to "Character Codes". - - * numbers.texi (Integer Basics): Add an @xref to `max-char'. - - * nonascii.texi (Explicit Encoding): Update for Emacs 23. - (Character Codes): Document `max-char'. - -2008-11-28 Eli Zaretskii - - * nonascii.texi (Text Representations, Converting Representations) - (Character Sets, Scanning Charsets, Translation of Characters): - Make text more accurate. - -2008-11-28 Glenn Morris - - * files.texi (Format Conversion Round-Trip): Improve previous change. - -2008-11-26 Chong Yidong - - * modes.texi (Auto Major Mode): Fix example. - -2008-11-25 Glenn Morris - - * control.texi (Signaling Errors): Fix `wrong-type-argument' name. - - * files.texi (Format Conversion Round-Trip): - Use active voice for previous change. - -2008-11-25 Chong Yidong - - * os.texi (Processor Run Time): - * processes.texi (Transaction Queues): - * markers.texi (The Mark): - * windows.texi (Choosing Window, Selecting Windows): - * files.texi (Changing Files, Magic File Names): - * commands.texi (Key Sequence Input): - * functions.texi (Declaring Functions): - * strings.texi (Predicates for Strings): - * intro.texi (nil and t): Fix typos (pointed out by Drew Adams). - -2008-11-24 Chong Yidong - - * help.texi (Accessing Documentation): Update example. - - * variables.texi (Defining Variables): Note that `*' is not - necessary if defcustom is used. - -2008-11-22 Eli Zaretskii - - * elisp.texi (Top): Remove "Chars and Bytes" and "Splitting - Characters" from @detailmenu. - - * nonascii.texi (Character Codes, Character Sets) - (Scanning Charsets, Translation of Characters): Update for Emacs 23. - (Chars and Bytes, Splitting Characters): Sections removed. - -2008-11-22 Lute Kamstra - - * positions.texi (Text Lines): Update goto-line documentation. - -2008-11-21 Martin Rudalics - - * frames.texi (Frames): Fix typo, add cross references, reword. - (Initial Parameters): Reword special-display-frame-alist text. - (Frames and Windows): Reword. Describe argument norecord for - set-frame-selected-window. - (Input Focus): Describe argument norecord for select-frame. - Remove comment on MS-Windows behavior for focus-follows-mouse. - (Raising and Lowering): Mention windows-frames dichotomy in - metaphor. - - * windows.texi (Displaying Buffers, Vertical Scrolling) - (Horizontal Scrolling): Fix indenting and rewording issues - introduced with 2008-11-07 change. - -2008-11-20 Glenn Morris - - * files.texi (Format Conversion Round-Trip): Mention `preserve' - element of `format-alist'. - -2008-11-19 Glenn Morris - - * doclicense.texi: Update to FDL 1.3. - * elisp.texi, vol1.texi, vol2.texi: Relicense under FDL 1.3 or later. - -2008-11-18 Chong Yidong - - * windows.texi (Window Hooks): Remove *-end-trigger-functions - vars, which are obsolete. Mention jit-lock-register. - - * modes.texi (Other Font Lock Variables): - Document jit-lock-register and jit-lock-unregister. - - * frames.texi (Color Parameters): Document alpha parameter. - -2008-11-16 Martin Rudalics - - * windows.texi (Splitting Windows, Deleting Windows) - (Selecting Windows, Cyclic Window Ordering) - (Buffers and Windows, Displaying Buffers, Choosing Window) - (Dedicated Windows, Window Point, Window Start and End) - (Textual Scrolling, Vertical Scrolling, Horizontal Scrolling) - (Size of Window, Resizing Windows, Window Configurations) - (Window Parameters): Avoid @var at beginning of sentences and - reword accordingly. - -2008-11-11 Lute Kamstra - - * files.texi (File Name Components): Fix file-name-extension - documentation. - -2008-11-11 Juanma Barranquero - - * frames.texi (Basic Parameters): Remove display-environment-variable - and term-environment-variable. - -2008-11-08 Eli Zaretskii - - * windows.texi (Basic Windows, Splitting Windows) - (Deleting Windows, Selecting Windows, Cyclic Window Ordering) - (Buffers and Windows, Displaying Buffers, Dedicated Windows) - (Resizing Windows, Window Configurations, Window Parameters): - Fix wording and markup. - -2008-11-07 Martin Rudalics - - * windows.texi (Windows): Update entries. - (Basic Windows): Remove listing of attributes. Reword. - (Splitting Windows, Deleting Windows): Reword. - (Selecting Windows, Cyclic Window Ordering): Reword with special - emphasis on order of recently selected windows and buffer list. - (Buffers and Windows, Choosing Window): Reword with special - emphasis on dedicated windows. - (Displaying Buffers): Reword. For switch-to-buffer mention that - it may fall back on pop-to-buffer. For other-window try to - explain how it treats the cyclic ordering of windows. - (Dedicated Windows): New node and section discussing dedicated - windows and associated functions. - (Window Point): Add entry for window-point-insertion-type. Reword. - (Window Start and End): Rename node and section title. Reword. - (Textual Scrolling, Vertical Scrolling, Horizontal Scrolling): - Minor rewording. - (Size of Window): Reword, in particular text on window-width. - (Resizing Windows): Reword. Add text on balancing windows. - (Window Configurations): Reword. Mention window parameters. - (Window Parameters): New node and section on window parameters. - (Window Hooks): Reword. Mention that - window-configuration-change-hook is run "buffer-locally". - * elisp.texi (Top): Update Windows entries in @detailmenu - section. - -2008-11-04 Juanma Barranquero - - * searching.texi (Regexp Search): Fix typo. - -2008-11-03 Seweryn Kokot (tiny change) - - * searching.texi (Regexp Search): Document GREEDY arg. - (Simple Match Data): Fix return value. - -2008-11-01 Eli Zaretskii - - * nonascii.texi (Text Representations): Rewrite to make consistent - with Emacs 23 internal representation of characters. - Document `unibyte-string'. - -2008-10-28 Chong Yidong - - * processes.texi (Process Information): Note that process-status - does not accept buffer names. - -2008-10-27 Seweryn Kokot (tiny change) - - * positions.texi (Skipping Characters): Correct return value of - skip-chars-forward. - -2008-10-25 Martin Rudalics - - * windows.texi (Deleting Windows): Update documentation of - delete-windows-on. - (Buffers and Windows): Update documentations of - get-buffer-window and get-buffer-window-list. - (Displaying Buffers): Update documentation of - replace-buffer-in-windows. - - * buffers.texi (Current Buffer): Reword set-buffer and - with-current-buffer documentations. - (Creating Buffers): Reword documentation of get-buffer-create. - -2008-10-23 Martin Rudalics - - * buffers.texi (Current Buffer): Reword documentation of - set-buffer. - (Buffer Names): Reword documentation of buffer-name. - (The Buffer List): For bury-buffer explain what happens with the - buffer's window. - (Creating Buffers): Say that get-buffer-create's arg is called - buffer-or-name. - -2008-10-22 Chong Yidong - - * advice.texi (Computed Advice): Explain what DEFINITION is. - - * nonascii.texi (Character Codes): Remove obsolete function - char-valid-p, and document characterp instead. - -2008-10-22 Martin Rudalics - - * windows.texi (Displaying Buffers): Reword documentation of - pop-to-buffer. - (Choosing Window): Rewrite documentation of display-buffer and - its options. - - * buffers.texi (Killing Buffers): Update documentation of - kill-buffer. - -2008-10-21 Eli Zaretskii - - * processes.texi (Serial Ports): Fix wording and improve markup. - - * searching.texi (Regexp Search): Document `string-match-p' and - `looking-at-p'. - (POSIX Regexps): Add an xref for "non-greedy". - (Regexp Special): Add @cindex entry for "non-greedy". - - * display.texi (Attribute Functions): Document `face-all-attributes'. - (Image Cache) : Minor wording fixes. - - * frames.texi (Color Names): Add an xref to `read-color'. - - * minibuf.texi (High-Level Completion): Document `read-color'. - - * elisp.texi (Top): Add "Swapping Text" to @detailmenu. - - * positions.texi (Narrowing): Add an xref to "Swapping Text". - - * buffers.texi (Swapping Text): New section, documents - `buffer-swap-text'. - -2008-10-21 Martin Rudalics - - * windows.texi (Resizing Windows): Minor wording fix. - -2008-10-20 Eli Zaretskii - - * processes.texi (Shell Arguments): Document `split-string-and-unquote' - and `combine-and-quote-strings'. - - * strings.texi (Creating Strings): Add xrefs for them. - -2008-10-19 Eli Zaretskii - - * elisp.texi (Top): Make descriptive text for "Reading File Names" - match the corresponding menu in minibuf.texi. - - * minibuf.texi (Reading File Names): Document `read-shell-command' - and `minibuffer-local-shell-command-map'. - -2008-10-19 Martin Rudalics - - * windows.texi (Resizing Windows): Remove var{} around "window" in - documentation of enlarge-window. - Rewrite documentation of window-min-height and window-min-width. - -2008-10-19 Eli Zaretskii - - * functions.texi (Calling Functions): Document `apply-partially'. - - * hooks.texi (Standard Hooks): Mention - `before-hack-local-variables-hook' and `hack-local-variables-hook'. - - * variables.texi (File Local Variables): Document - `file-local-variables-alist', `before-hack-local-variables-hook' - and `hack-local-variables-hook'. - - * processes.texi (Synchronous Processes): Document `process-lines'. - - * customize.texi (Variable Definitions): - Document `custom-reevaluate-setting'. - -2008-10-18 Martin Rudalics - - * windows.texi (Choosing Window, Deleting Windows) - (Displaying Buffers): Expand documentation of dedicated windows. - -2008-10-18 Eli Zaretskii - - * files.texi (Changing Files): Document symbolic input of file - modes to `set-file-modes'. Document `read-file-modes' and - `file-modes-symbolic-to-number'. - - * maps.texi (Standard Keymaps): Document `multi-query-replace-map' - and `search-map'. - - * searching.texi (Search and Replace): - Document `replace-search-function' and `replace-re-search-function'. - Document `multi-query-replace-map'. - - * minibuf.texi (Text from Minibuffer): Document `read-regexp'. - (Completion Commands, Reading File Names): - Rename `minibuffer-local-must-match-filename-map' to - `minibuffer-local-filename-must-match-map'. - (Minibuffer Completion): The `require-match' argument to - `completing-read' can now have the value `confirm-only'. - - * windows.texi (Displaying Buffers): Minor wording fix. - (Choosing Window): `split-height-threshold' can now be nil. - Document `split-width-threshold'. `pop-up-frames' can have the - value `graphic-only'. - -2008-10-17 Eli Zaretskii - - * os.texi (Startup Summary): Document `before-init-time' and - `after-init-time'. Document `initial-window-system' and - `window-system-initialization-alist'. Document reading the - abbrevs file. Document the call to `server-start' under --daemon. - Rearrange a bit to be consistent with the code flow. - (Processor Run Time): Document `emacs-uptime' and `emacs-init-time'. - (Time Parsing): Document `format-seconds'. - -2008-10-17 Martin Rudalics - - * windows.texi (Basic Windows, Splitting Windows): Fix whitespace - and reword. - -2008-10-16 Eli Zaretskii - - * markers.texi (The Mark): Document use-region-p. - -2008-10-15 Eli Zaretskii - - * internals.texi (Writing Emacs Primitives): The interactive spec - of a primitive can be a Lisp form. - - * markers.texi (The Mark): Document the `lambda' and `(only . OLD)' - values of transient-mark-mode. Document handle-shift-selection. - - * commands.texi (Using Interactive, Interactive Codes): Document `^'. - (Interactive Examples): Show an example of `^'. - (Key Sequence Input): Document this-command-keys-shift-translated. - (Defining Commands, Using Interactive): The interactive-form of a - function can be added via its symbol's property. - - * positions.texi (List Motion): beginning-of-defun-function can - now accept an argument. - - * text.texi (Low-Level Kill Ring): interprogram-paste-function can - now return a list of strings. - - * control.texi (Handling Errors): Document ignore-errors. - - * frames.texi (Creating Frames): Document frame-inherited-parameters. - (Parameter Access): Document set-frame-parameter. - - * variables.texi (Creating Buffer-Local): Add an xref to "Setting - Hooks" for the effect of kill-all-local-variables on local hook - functions. - - * modes.texi (Major Mode Conventions, Mode Line Variables): - `mode-name' need not be a string. xref to "Mode Line Data" for - details, and to "Emulating Mode Line" for computing a string - value. - -2008-10-14 Eli Zaretskii - - * processes.texi (System Processes): New section. - (Processes, Signals to Processes): Add xrefs to it. - - * objects.texi (Editing Types): A `process' is a subprocess of - Emacs, not just any process running on the OS. - - * elisp.texi (Top): Adjust the @detailmenu for the above two - changes. - - * sequences.texi (Char-Tables): Remove documentation of - set-char-table-default, which has no effect since Emacs 23. - : Don't mention generic - characters and charsets. Add a cons cell as a possible argument. - - * nonascii.texi (Splitting Characters) - (Translation of Characters): Don't mention generic characters. - - * display.texi (Fontsets): Don't mention generic characters. - - * sequences.texi (Char-Tables): `map-char-table' can now call its - argument FUNCTION with a cons cell as KEY. - -2008-10-13 Eli Zaretskii - - * objects.texi (Primitive Function Type): Move "@cindex special - forms" from here... - - * eval.texi (Special Forms): ...to here. - - * functions.texi (What Is a Function): `functionp' returns nil for - special forms. Add an xref. - - * elisp.texi (Top): Add a @detailmenu entry for "Frame-Local - Variables". - - * variables.texi (Frame-Local Variables): New section. - (Buffer-Local Variables): Add an xref to it. - (Intro to Buffer-Local, Creating Buffer-Local): A variable cannot - have both frame-local and buffer-local binding. - - * frames.texi (Frames): Mention multiple tty frames. - (Frame Parameters, Parameter Access): Mention frame-local variable - bindings. - -2008-09-20 Glenn Morris - - * display.texi (Defining Faces): Recommend against face variables. - -2008-09-16 Juanma Barranquero - - * display.texi (Echo Area Customization): Fix typo. - -2008-09-09 Juanma Barranquero - - * loading.texi (Where Defined): Add `defface' item. - -2008-09-06 Martin Rudalics - - * loading.texi (Where Defined): Fix description of symbol-file. - -2008-08-26 Jason Rumney - - * display.texi (TIFF Images): New section describing :index property. - -2008-08-23 Chong Yidong - - * display.texi (Temporary Displays): Remove unnecessary comment - about usage of temp-buffer-show-hook. - -2008-08-05 Chong Yidong - - * symbols.texi (Other Plists): Fix incorrect example. - Suggested by Florian Beck. - -2008-07-31 Juanma Barranquero - - * os.texi: Fix previous change. - -2008-07-31 Dan Nicolaescu - - * os.texi: - * intro.texi: - * files.texi: Remove VMS support. - -2008-07-27 Dan Nicolaescu - - * os.texi: - * frames.texi: - * display.texi: Remove mentions of Mac Carbon. - -2008-07-01 Miles Bader - - * text.texi (Special Properties): - * display.texi (Truncation): Add wrap-prefix and line-prefix. - -2008-06-28 Johan BockgÃ¥rd - - * display.texi (Other Image Types): Fix copy/paste error; say - "PBM", not "XBM". - -2008-06-26 Dan Nicolaescu - - * os.texi: Remove references to obsolete systems. - -2008-06-20 Eli Zaretskii - - * makefile.w32-in (distclean): Remove makefile. - -2008-06-17 Glenn Morris - - * Makefile.in (emacsver, miscmanualdir, VERSION, manual, install) - (elisp, dist): Remove rules and variables that are obsolete now - the lisp manual is no longer distributed separately. - -2008-06-16 Glenn Morris - - * configure, configure.in, mkinstalldirs: Remove unused files. - - * book-spine.texinfo: Set version to 23.0.60. - * vol1.texi (EMACSVER): - * vol2.texi (EMACSVER): Set to 23.0.60. - - * elisp.texi, vol1.texi, vol2.texi: Update Back-Cover Text - as per maintain.info. - -2008-06-15 Glenn Morris - - * makefile.w32-in (manual): Use "23" rather than "21". - - * Makefile.in (emacsver): New, set by configure. - (manual): Use emacsver. - - * intro.texi: Report bugs using M-x report-emacs-bug. - - * elisp.texi (EMACSVER): Remove duplicate, outdated setting. - -2008-06-13 Daniel Engeler - - * elisp.texi, internals.texi, processes.texi: Add documentation - about serial port access. - -2008-06-05 Miles Bader - - * display.texi (Displaying Faces): Update to reflect function - renamings in face-remap.el. - -2008-06-05 Juanma Barranquero - - * display.texi (Fontsets): Fix typos. - -2008-06-03 Miles Bader - - * display.texi (Displaying Faces): Add add-relative-face-remapping, - remove-relative-face-remapping, set-base-face-remapping, - and set-default-base-face-remapping. - -2008-06-01 Miles Bader - - * display.texi (Displaying Faces): Add face-remapping-alist. - -2008-05-30 Stefan Monnier - - * tips.texi (Coding Conventions): Do not encourage the use of "-flag" - variable names. - -2008-05-03 Eric S. Raymond - - * keymaps.texi: Clarify that (current-local-map) and - (current-global-map) return references, not copies. - -2008-05-02 Juri Linkov - - * minibuf.texi (Text from Minibuffer): Document a list of - default values for `read-from-minibuffer'. - -2008-04-24 Juanma Barranquero - - * nonascii.texi (Translation of Characters): Fix previous change. - -2008-04-20 Chong Yidong - - * display.texi (Overlay Properties): Clarify role of underlying - textprop and overlay keymaps for display strings. - - * keymaps.texi (Active Keymaps): Ditto. - -2008-04-19 Stefan Monnier - - * minibuf.texi (Programmed Completion): - Replace dynamic-completion-table with the new completion-table-dynamic. - -2008-04-07 Chong Yidong - - * intro.texi (Some Terms): Change "fonts in this manual" index - entry to "typographic conventions". - -2008-04-05 Eli Zaretskii - - * objects.texi (Text Props and Strings): Add indexing for read - syntax of text properties. - -2008-03-25 Stefan Monnier - - * processes.texi (Decoding Output): Remove process-filter-multibyte - functions. - -2008-03-15 Martin Rudalics - - * display.texi (Finding Overlays): Say that empty overlays at - the end of the buffer are reported too. - -2008-03-13 Glenn Morris - - * elisp.texi (EMACSVER): Set to 23.0.60. - -2008-02-26 Chong Yidong - - * strings.texi (Formatting Strings): Treat - and 0 as flag characters. - -2008-02-22 Glenn Morris - - * frames.texi (Position Parameters): Clarify the description of - `left' and `top', using information from "Geometry". - (Geometry): Give a pointer to "Position Parameters", rather than - repeating information. - -2008-02-11 Glenn Morris - - * objects.texi (Equality Predicates): No longer talk about "two" - functions. - -2008-02-11 Lawrence Mitchell (tiny change) - - * objects.texi (Equality Predicates): Add defun for - equal-including-properties. - -2008-02-10 Glenn Morris - - * objects.texi (Equality Predicates): - Mention equal-including-properties. - -2008-02-07 Richard Stallman - - * windows.texi (Window Start): Mention the feature of moving - window-start to start of line. - -2008-02-07 Jan Djärv - - * keymaps.texi (Tool Bar): Document rtl property. - -2008-01-27 Thien-Thi Nguyen - - * display.texi (Button Types): - For define-button-type, clarify type of NAME. - -2008-01-19 Martin Rudalics - - * buffers.texi (Buffer Modification): Fix typo. - -2008-01-06 Dan Nicolaescu - - * os.texi (System Environment): Remove references to OSes that are - not supported anymore. - -2008-01-05 Dan Nicolaescu - - * os.texi (System Environment): Remove mention for Masscomp. - -2008-01-04 Richard Stallman - - * display.texi (Faces): Don't talk about internal face vector as arg - to facep. - - * customize.texi (Type Keywords): Fix previous change. - - * text.texi (Links and Mouse-1): Fix xref for commands.texi change. - * elisp.texi (Top): Fix menu for commands.texi change. - -2007-12-30 Richard Stallman - - * commands.texi (Accessing Mouse): Rename from Accessing Events. - (Accessing Scroll): New node broken out of Accessing Mouse. - -2007-12-28 Richard Stallman - - * frames.texi (Size Parameters): Fix typo. - (Basic Parameters): For `title', refer to title bar. - (Size and Position): Explain meaning of frame pixel width and height. - -2007-12-23 Richard Stallman - - * customize.texi (Type Keywords): Uncomment :validate and clarify it. - Improve some of the commented-out keywords' text too. - -2007-12-14 Martin Rudalics - - * nonascii.texi (Encoding and I/O): Reword to avoid saying - "visit the current buffer". - - * os.texi (System Interface): Fix typo. - -2007-12-04 Richard Stallman - - * objects.texi (Symbol Type): Fix typo. - -2007-12-03 Richard Stallman - - * hooks.texi (Standard Hooks): Add link to Hooks for Loading. - -2007-12-01 Glenn Morris - - * functions.texi (Declaring Functions): Improve previous change. - -2007-11-30 Glenn Morris - - * functions.texi (Declaring Functions): Add optional fourth - argument of declare-function, and setting third argument to `t'. - -2007-11-29 Richard Stallman - - * customize.texi (Composite Types): Document `group' type. - -2007-11-29 Glenn Morris - - * functions.texi (Declaring Functions): Add findex. - Mention `external' files. - -2007-11-26 Juanma Barranquero - - * functions.texi (Declaring Functions): Fix directive. - -2007-11-25 Richard Stallman - - * help.texi (Help Functions): Clean up last change. - - * advice.texi (Preactivation, Activation of Advice): Minor cleanup. - - * loading.texi (Named Features): Minor cleanup. - - * macros.texi (Eval During Expansion): Minor cleanup. - - * variables.texi (Variable Aliases): Minor cleanup. - -2007-11-24 Richard Stallman - - * functions.texi (Declaring Functions): Clarify previous change. - - * compile.texi (Compiler Errors): Clarify previous change. - -2007-11-24 Richard Stallman - - * display.texi (Refresh Screen, Forcing Redisplay): - Clarify the text and move items around. - -2007-11-24 Glenn Morris - - * functions.texi (Declaring Functions): New section. - * compile.texi (Compiler Errors): Mention declaring functions, - defvar with no initvalue, and byte-compile-warnings. - -2007-11-15 Martin Rudalics - - * vol1.texi (Top): Remove Frame-Local Variables from Node Listing. - * vol2.texi (Top): Remove Frame-Local Variables from Node Listing. - -2007-11-13 Martin Rudalics - - * help.texi (Help Functions): Document new macro `with-help-window'. - -2007-11-10 Paul Pogonyshev - - * searching.texi (Replacing Match): Describe new - `match-substitute-replacement'. - -2007-10-31 Richard Stallman - - * strings.texi (Creating Strings): Null strings from concat not unique. - -2007-10-26 Richard Stallman - - * objects.texi (Equality Predicates): Null strings are uniquified. - - * minibuf.texi: Minor clarifications in previous change. - -2007-10-25 Glenn Morris - - * customize.texi (Variable Definitions): Add :risky and :safe keywords. - -2007-10-24 Richard Stallman - - * elisp.texi (Top): Delete Frame-Local Variables from subnode menu. - - * variables.texi (Frame-Local Variables): Node deleted. - (Variables): Delete Frame-Local Variables from menu. - (Local Variables, Buffer-Local Variables, Intro to Buffer-Local) - (Default Value): Don't mention frame-local vars. - - * os.texi (Idle Timers): current-idle-time returns nil if not idle. - - * loading.texi (Unloading): Document FEATURE-unload-function - instead of FEATURE-unload-hook. - - * frames.texi (Multiple Displays): Don't mention frame-local vars. - -2007-10-22 Juri Linkov - - * minibuf.texi (Text from Minibuffer, Minibuffer Completion) - (High-Level Completion): Document a list of default value strings - in the DEFAULT argument, for which minibuffer functions return the - first element. - -2007-10-17 Juri Linkov - - * text.texi (Filling): Update arguments of fill-paragraph. - fill-paragraph operates on the active region in Transient Mark mode. - Remove fill-paragraph-or-region. - -2007-10-13 Karl Berry - - * elisp.texi (@dircategory): Move to after @copying, - since we want @copying as close as possible to the beginning of - the output. - -2007-10-12 Richard Stallman - - * elisp.texi (Top): Add Distinguish Interactive to subnode menu. - - * commands.texi (Distinguish Interactive): New node, - broken out from Interactive Call and rewritten. - (Command Loop): Put Distinguish Interactive in menu. - -2007-10-09 Richard Stallman - - * text.texi (Examining Properties): Mention overlay priority. - - * display.texi (Display Margins): Correct the description - of margin display specifications. - (Replacing Specs): New subnode broken out of Display Property. - -2007-10-06 Juri Linkov - - * text.texi (Filling): Document fill-paragraph-or-region. - -2007-10-05 Juanma Barranquero - - * display.texi (Auto Faces): Fix typo. - -2007-10-02 Richard Stallman - - * display.texi (Display Property): Explain some display specs - don't let you move point in. - - * frames.texi (Cursor Parameters): - Describe cursor-in-non-selected-windows here. Explain more values. - - * windows.texi (Basic Windows): Don't describe - cursor-in-non-selected-windows here. - -2007-10-01 Eli Zaretskii - - * processes.texi (Misc Network): Note that these functions are - supported only on some systems. - -2007-10-01 Richard Stallman - - * display.texi (Overlay Properties): Explain nil as priority. - Explain that conflicts are unpredictable if not resolved by - priorities. - -2007-09-23 Richard Stallman - - * macros.texi (Backquote): Minor clarification. - -2007-09-19 Richard Stallman - - * display.texi (Display Property): Explain multiple display specs. - Clarify when they work in parallel and when one overrides. - Fix error in example. - -2007-09-06 Glenn Morris - - Move from lispref/ to doc/lispref/. Change all setfilename - commands to use ../../info. - * Makefile.in (infodir): Go up one more level. - (usermanualdir): Change from ../man to ../emacs. - (miscmanualdir): New. - (dist): Use new variable miscmanualdir. - * makefile.w32-in (infodir, texinputdir): Go up one more level. - (usermanualdir): Change from ../man to ../emacs. - -2007-08-30 Martin Rudalics - - * commands.texi (Command Loop Info): Advise against changing - most variables described here. Explain new variable - last-repeatable-command. - -2007-08-29 Glenn Morris - - * elisp.texi (EMACSVER): Increase to 23.0.50. - -2007-08-29 Dan Nicolaescu - - * frames.texi (Basic Parameters): Add display-environment-variable - and term-environment-variable. - -2007-08-28 Juri Linkov - - * display.texi (Image Formats, Other Image Types): Add SVG. - -2007-08-28 Juri Linkov - - * display.texi (Images): Move formats-related text to new node - "Image Formats". - (Image Formats): New node. - -2007-08-27 Richard Stallman - - * windows.texi (Window Configurations): Clarify what - a window configuration saves. - -2007-08-25 Richard Stallman - - * display.texi (Images): Delete redundant @findex. - -2007-08-16 Stefan Monnier - - * text.texi (Change Hooks): (after|before)-change-functions are no - longer bound to nil while running; rather inhibit-modification-hooks - is t. - -2007-08-16 Richard Stallman - - * processes.texi (Asynchronous Processes): - Clarify doc of start-file-process. - -2007-08-08 Martin Rudalics - - * modes.texi (Example Major Modes): Fix typo. - -2007-08-08 Glenn Morris - - * intro.texi (nil and t): Do not use `iff' in documentation. - - * tips.texi (Documentation Tips): Recommend against `iff'. - -2007-08-07 Chong Yidong - - * display.texi (Image Cache): Document image-refresh. - -2007-08-06 Martin Rudalics - - * windows.texi (Size of Window): Document window-full-width-p. - -2007-07-25 Glenn Morris - - * gpl.texi (GPL): Replace license with GPLv3. - - * Relicense all FSF files to GPLv3 or later. - -2007-07-24 Michael Albinus - - * processes.texi (Synchronous Processes): - Add `process-file-shell-command'. - (Asynchronous Processes): Mention restricted use of - `process-filter' and `process-sentinel' in - `start-file-process'. Add `start-file-process-shell-command'. - -2007-07-17 Michael Albinus - - * files.texi (Magic File Names): Introduce optional parameter - IDENTIFICATION for `file-remote-p'. - -2007-07-16 Richard Stallman - - * display.texi (Defining Faces): Fix previous change. - -2007-07-14 Richard Stallman - - * control.texi (Handling Errors): Document `debug' in handler list. - -2007-07-10 Richard Stallman - - * display.texi (Defining Faces): Explain C-M-x feature for defface. - -2007-07-09 Richard Stallman - - * files.texi (Magic File Names): Rewrite previous change. - -2007-07-08 Michael Albinus - - * files.texi (Magic File Names): Introduce optional parameter - CONNECTED for `file-remote-p'. - -2007-07-07 Michael Albinus - - * processes.texi (Asynchronous Processes): - * files.texi (Magic File Names): Add `start-file-process'. - -2007-06-27 Richard Stallman - - * files.texi (Format Conversion Piecemeal): - Clarify `after-insert-file-functions' calling convention. - -2007-06-27 Michael Albinus - - * files.texi (Magic File Names): Remove `dired-call-process'. - Add `process-file'. - -2007-06-27 Kenichi Handa - - * text.texi (Special Properties): Fix description about - `composition' property. - -2007-06-26 Kenichi Handa - - * nonascii.texi (Default Coding Systems): Document about the - return value `undecided'. - -2007-06-25 David Kastrup - - * keymaps.texi (Active Keymaps): Document new POSITION argument of - `current-active-maps'. - -2007-06-24 Karl Berry - - * elisp.texi, vol1.texi, vol2.texi: New Back-Cover Text. - -2007-06-15 Juanma Barranquero - - * display.texi (Overlay Arrow): Doc fix. - -2007-06-14 Karl Berry - - * anti.texi (Antinews): Typo. - -2007-06-14 Chong Yidong - - * display.texi (Image Cache): Document image-refresh. - -2007-06-12 Karl Berry - - * vol1.texi, vol2.texi, two-volume-cross-refs.txt: Update. - * two-volume.make: New file. - * .cvsignore: Ignore two-volume files. - -2007-06-12 Tom Tromey - - * os.texi (Init File): Document user-emacs-directory. - -2007-06-03 Nick Roberts - - * commands.texi (Click Events): Describe width and height when - object is nil. - -2007-05-30 Nick Roberts - - * commands.texi (Click Events): Layout more logically. - Describe width and height. - (Drag Events, Motion Events): Update to new format for position. - -2007-06-02 Richard Stallman - - * frames.texi (Color Parameters): Add xref to (emacs)Standard Faces. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-06-01 Stefan Monnier - - * text.texi (Special Properties): Correct meaning of fontified face. - -2007-05-30 Richard Stallman - - * text.texi (Special Properties): Add link to Adjusting Point. - -2007-05-12 Richard Stallman - - * text.texi (Margins): indent-to-left-margin is not the default. - (Mode-Specific Indent): For indent-line-function, the default - is indent-relative. - - * modes.texi (Example Major Modes): Explain last line of text-mode - is redundant. - -2007-05-10 Richard Stallman - - * keymaps.texi (Scanning Keymaps): Update where-is-internal example. - - * help.texi (Keys in Documentation): Add reference to - Documentation Tips. - - * files.texi (Format Conversion): TO-FN gets three arguments. - - * modes.texi (Auto Major Mode): Document file-start-mode-alist. - -2007-05-10 Thien-Thi Nguyen - - * elisp.texi (Top): Remove "Saving Properties" from detailed menu. - * files.texi (Format Conversion): Expand intro; add menu. - (Format Conversion Overview, Format Conversion Round-Trip) - (Format Conversion Piecemeal): New nodes/subsections. - * hooks.texi: Xref "Format Conversion" , not "Saving Properties". - * text.texi (Text Properties): Remove "Saving Properties" from menu. - (Saving Properties): Delete node/subsection. - -2007-05-07 Karl Berry - - * elisp.texi (EMACSVER): Back to 22. - -2007-05-06 Richard Stallman - - * processes.texi (Accepting Output): Revert most of previous change. - -2007-05-05 Richard Stallman - - * processes.texi (Accepting Output): accept-process-output - uses microseconds, not milliseconds. But that arg is obsolete. - -2007-05-04 Karl Berry - - * elisp.texi (EMACSVER) [smallbook]: 22.1, not 22. - -2007-05-04 Eli Zaretskii - - * tips.texi (Documentation Tips): Rearrange items to place the - more important ones first. Add an index entry for hyperlinks. - -2007-05-03 Karl Berry - - * elisp.texi (\urlcolor, \linkcolor) [smallbook]: \Black for printing. - (EMACSVER) [smallbook]: 22 for printed version. - - * control.texi (Signaling Errors) : texinfo.tex is fixed, - so restore anchor to normal position after defun. Found by Kevin Ryde. - -2007-04-26 Glenn Morris - - * elisp.texi (EMACSVER): Increase to 22.1.50. - -2007-04-28 Karl Berry - - * elisp.texi: Improve line breaks on copyright page, - similar layout to emacs manual, 8.5x11 by default. - -2007-04-24 Richard Stallman - - * text.texi (Special Properties): Add xref to Overlay Properties. - - * display.texi (Overlay Properties): Add xref to Special Properties. - -2007-04-22 Richard Stallman - - * keymaps.texi (Extended Menu Items): Move the info about - format with cached keyboard binding. - -2007-04-21 Richard Stallman - - * text.texi (Special Properties): Clarify previous change. - - * files.texi (File Name Expansion): Clarify previous change. - - * display.texi (Attribute Functions): Fix example for - face-attribute-relative-p. - -2007-04-19 Kenichi Handa - - * text.texi (Special Properties): Document composition property. - -2007-04-19 Glenn Morris - - * files.texi (File Name Expansion): Mention "superroot". - -2007-04-15 Chong Yidong - - * frames.texi (Multiple Displays): Add note about "multi-monitor" - setups. - (Display Feature Testing): Note that display refers to all - physical monitors for multi-monitor setups. - -2007-04-14 Richard Stallman - - * lists.texi (Sets And Lists): Clarify `delete' examples. - Remove spurious xref to same node. - Clarify xref for add-to-list. - -2007-04-12 Nick Roberts - - * keymaps.texi (Format of Keymaps): Remove spurious ")" from - value of lisp-mode-map. - -2007-04-11 Karl Berry - - * anti.texi (Antinews): - * display.texi (Overlay Properties, Defining Images): - * processes.texi (Synchronous Processes, Sentinels): - * syntax.texi (Syntax Table Internals): - * searching.texi (Regexp Special): - * nonascii.texi (Default Coding Systems): - * text.texi (Special Properties): - * minibuf.texi (Basic Completion): Wording to improve breaks in - 8.5x11 format. - * elisp.texi (smallbook): New @set to more easily switch between - smallbook and 8.5x11. - -2007-04-11 Richard Stallman - - * text.texi (Lazy Properties): Minor fix. - -2007-04-08 Karl Berry - - * symbols.texi (Plists and Alists): Period after "vs" in index entries. - * macros.texi (Backquote): Downcase Backquote in index entries for - consistency. - -2007-04-08 Richard Stallman - - * text.texi (Adaptive Fill): Just describe default, - don't show it (since it contains non-ASCII chars). - -2007-04-07 Karl Berry - - * text.texi (Adaptive Fill) [@iftex]: Omit binary characters in - adaptive-fill-regexp's value, since they are not in the standard - TeX fonts. - -2007-04-07 Guanpeng Xu - - * display.texi (Defining Faces): Fix example. - -2007-04-07 Karl Berry - - * display.texi (Button Buffer Commands): Improve page break. - -2007-04-07 Richard Stallman - - * advice.texi (Activation of Advice): Remove redundant index entry. - - * backups.texi: Improve index entries. Remove redundant ones. - - * compile.texi (Byte Compilation): Improve index entry. - - * hash.texi (Creating Hash): Improve index entry. - - * symbols.texi (Definitions): Improve index entry. - - * edebug.texi: Improve index entries. Remove redundant/useless ones. - - * maps.texi (Standard Keymaps): Remove useless index entry. - - * help.texi (Documentation Basics): Remove redundant index entries. - - * customize.texi: Improve index entries. - Remove redundant/useless ones. - - * locals.texi (Standard Buffer-Local Variables): Clarify intro text. - - * streams.texi (Output Variables): Improve index entry. - - * abbrevs.texi (Abbrevs): Remove useless index entry. - - * macros.texi (Expansion): Remove useless index entry. - - * text.texi: Improve index entries. Remove redundant/useless ones. - (Text Properties, Examining Properties) - (Special Properties): Use "property category" instead of "category" - to refer to the `category' property. - - * positions.texi: Improve index entries. Remove useless one. - - * lists.texi: Improve index entries. Remove redundant/useless ones. - - * os.texi: Improve index entries. - (Timers): Fix previous change. - - * buffers.texi: Improve index entries. - (Modification Time): Get rid of term "obsolete buffer". - - * debugging.texi: Improve index entries. - (Test Coverage): Add xref to other test coverage ftr. - - * eval.texi: Improve index entry. Remove redundant ones. - - * numbers.texi: Improve index entries. Remove redundant/useless ones. - - * files.texi: Improve index entries. Remove redundant/useless ones. - - * objects.texi: Improve index entries. - - * processes.texi: Improve index entries. - - * modes.texi: Improve index entry. Remove redundant one. - - * nonascii.texi: Improve index entries. - - * internals.texi: Improve index entries. - - * syntax.texi: Improve index entries. - - * keymaps.texi (Active Keymaps): Improve index entries. - - * commands.texi: Improve index entries. Remove redundant/useless ones. - - * frames.texi: Improve index entries. Remove redundant/useless ones. - - * markers.texi: Improve index entries. Remove redundant ones. - - * tips.texi: Improve index entries. - - * loading.texi (Unloading): Improve index entry. - - * variables.texi: Improve index entries. Remove redundant one. - - * sequences.texi: Improve index entry. - - * display.texi: Improve index entries. Remove redundant ones. - - * windows.texi: Improve index entries. - - * searching.texi: Improve index entries. Remove redundant one. - - * strings.texi (Case Tables): Improve last change. - -2007-04-04 Chong Yidong - - * strings.texi (Case Tables): Document with-case-table and - ascii-case-table. - -2007-04-03 Karl Berry - - * processes.texi (Network): Reword to improve page break. - -2007-04-03 Eli Zaretskii - - * functions.texi (Inline Functions): Describe more disadvantages - of defsubst, and make advice against it stronger. - -2007-04-02 Karl Berry - - * backups.texi (Backup Names): Avoid widow words. - * modes.texi (Example Major Modes): Align last comment. - -2007-04-01 Chong Yidong - - * keymaps.texi (Remapping Commands): Document new arg to - command-remapping. - -2007-04-01 Karl Berry - - * processes.texi (Low-Level Network): Typo. - * loading.texi (Hooks for Loading): Avoid double "the". - * keymaps.texi (Key Sequences): No double "and". - (Changing Key Bindings): Shorten to improve line break. - -2007-03-31 Glenn Morris - - * os.texi (Timers): Fix description of run-at-time TIME formats. - -2007-03-31 Richard Stallman - - * display.texi (Invisible Text): Correct buffer-invisibility-spec - regarding ellipsis. - -2007-03-31 Eli Zaretskii - - * intro.texi (nil and t): - * symbols.texi (Plists and Alists): - * variables.texi (Variable Aliases, Constant Variables): - * functions.texi (Defining Functions): - * advice.texi (Advising Primitives): - * debugging.texi (Syntax Errors, Compilation Errors): - * minibuf.texi (Minibuffer Windows): - * commands.texi (Adjusting Point): - * modes.texi (Syntactic Font Lock, Faces for Font Lock) - (Auto Major Mode, Major Mode Conventions): - * help.texi (Describing Characters): - * files.texi (Create/Delete Dirs, Information about Files) - (File Locks, Writing to Files, Reading from Files) - (Saving Buffers): - * windows.texi (Resizing Windows, Cyclic Window Ordering): - * frames.texi (Finding All Frames): - * positions.texi (Buffer End, Motion): - * markers.texi (The Region): - * text.texi (Deletion, Near Point): - * display.texi (Displaying Messages, Truncation): - * os.texi (Processor Run Time): - * tips.texi (Key Binding Conventions, Programming Tips) - (Warning Tips, Documentation Tips, Comment Tips): - * internals.texi (Memory Usage): Improve indexing. - - * variables.texi (Frame-Local Variables): - * functions.texi (Argument List): - * loading.texi (Library Search): - * streams.texi (Output Variables): - * keymaps.texi (Translation Keymaps, Searching Keymaps): - * searching.texi (Replacing Match, Search and Replace): - * processes.texi (Byte Packing, Decoding Output) - (Accepting Output, Network Servers, Shell Arguments): - * display.texi (Abstract Display, Image Cache, Scroll Bars): - * windows.texi (Window Point, Window Start): - * frames.texi (Management Parameters, Frame Parameters, Frame Titles): - * commands.texi (Reading Input, Keyboard Events): - * minibuf.texi (Reading File Names, Minibuffer Completion) - (Recursive Mini): - * positions.texi (List Motion): - * hash.texi (Hash Tables, Creating Hash, Defining Hash): - * numbers.texi (Arithmetic Operations, Math Functions) - (Predicates on Numbers, Comparison of Numbers, Numeric Conversions): - * locals.texi (Standard Buffer-Local Variables): - * maps.texi (Standard Keymaps): - * os.texi (User Identification, System Environment, Recording Input) - (X11 Keysyms): - * nonascii.texi (Non-ASCII Characters, Splitting Characters): - * backups.texi (Backups and Auto-Saving): - * customize.texi (Customization, Group Definitions) - (Variable Definitions): - * compile.texi (Byte Compilation): Improve index entries. - -2007-03-31 Karl Berry - - * macros.texi (Defining Macros): Avoid widow syllable. - -2007-03-31 Eli Zaretskii - - * elisp.texi (Top): Postscript -> PostScript. - - * display.texi (Images, Postscript Images): Postscript -> PostScript. - -2007-03-31 Markus Triska - - * internals.texi (Writing Emacs Primitives): Untabify `For'. - -2007-03-30 Karl Berry - - * lists.texi (List-related Predicates): Remove spurious @need. - (Setcdr): Use @smallexample to improve page break. - (Association Lists) : Reword to improve page break. - - * strings.texi (String Conversion): Insert blank line to improve - page break. - - * numbers.texi (Random Numbers): Use @minus{}. - (Math Functions): Use @minus{}. - - * intro.texi (Acknowledgements): Avoid line breaks before middle - initials. - -2007-03-24 Eli Zaretskii - - * errors.texi (Standard Errors): Add an index entry. - -2007-03-19 Richard Stallman - - * os.texi (Recording Input): recent-keys now gives 300 keys. - -2007-03-12 Glenn Morris - - * os.texi: Replace "daylight savings" with "daylight saving" - throughout. - -2007-03-05 Richard Stallman - - * variables.texi (File Local Variables): - Update enable-local-variables values. - -2007-03-04 Richard Stallman - - * syntax.texi (Control Parsing): Minor clarification. - - * strings.texi (Formatting Strings): Clarify width, precision, flags. - - * sequences.texi (Sequence Functions): Move string-bytes away, - add xref. - - * nonascii.texi (Text Representations): Move string-bytes here. - - * modes.texi (Major Mode Conventions): Fundamental mode is exception. - - * minibuf.texi (Basic Completion): Minor clarification. - - * markers.texi (The Mark): Clarify existence vs activation of mark. - Other cleanup. - - * display.texi (Finding Overlays): Write better example. - - * compile.texi (Eval During Compile): Clarify putting macros - in eval-when-compile. - -2007-02-25 Vinicius Jose Latorre (tiny change) - - * loading.texi (How Programs Do Loading): Fix anchor position at - load-read-function definition doc. - -2007-02-21 Kim F. Storm - - * strings.texi (Text Comparison): Mention that assoc-string - converts symbols to strings before testing. - -2007-02-17 Kim F. Storm - - * processes.texi (Bindat Spec): Vector types can have optional - element type. - (Bindat Examples): Fix example. Add vector with element type. - -2007-02-16 Andreas Schwab - - * strings.texi (Formatting Strings): Document '+' flag. - -2007-02-15 Juanma Barranquero - - * strings.texi (Modifying Strings): Clarify that `clear-string' - always converts the string to unibyte. - -2007-02-14 Kim F. Storm - - * display.texi (Glyphs): Add make-glyph-code, glyph-char, glyph-face. - Rewrite glyph code description to refer to these functions. - Remove details of encoding face number and char into integer code. - -2007-02-03 Alan Mackenzie - - * loading.texi (Hooks for Loading): Make the description of - `eval-after-load' more detailed, and amend the description of - after-load-alist, in accordance with changes from 2006-05. - -2007-02-03 Chong Yidong - - * modes.texi (Defining Minor Modes): Document that a :require - keyword or similar may be required to make saved customization - variables work. - -2007-02-03 Eli Zaretskii - - * elisp.texi (Top): Make the detailed menu headers compliant with - Texinfo guidelines and with what texnfo-upd.el expects. - Add comments to prevent people from inadvertently modifying the key - parts needed by `texinfo-multiple-files-update'. - -2007-02-02 Eli Zaretskii - - * elisp.texi (Top): Update the top-level menus. - - * syntax.texi (Categories): Add index entries. - -2007-02-01 Juanma Barranquero - - * display.texi (Attribute Functions): Fix name and description of - the UNDERLINE arg of `set-face-underline-p'. - -2007-01-29 Eli Zaretskii - - * elisp.texi (Top): Add "Standard Errors", "Standard Buffer-Local - Variables", and "Standard Keymaps" to the detailed menu. - - * variables.texi (Future Local Variables): Add index entry. - -2007-01-28 Richard Stallman - - * tips.texi (Coding Conventions): Clarify the tip about macros - that define a function or a variable. - - * files.texi (File Attributes): UID and GID can be floats. - (Magic File Names): Explain why deferring all operations to - the standard handler does not work. - -2007-01-23 Martin Rudalics - - * backups.texi (Reverting): Use "buffer" instead of "file" - when talking about major and minor modes. - -2007-01-21 Richard Stallman - - * help.texi (Documentation): Add xref to Documentation Tips. - -2007-01-14 Juanma Barranquero - - * tips.texi (Coding Conventions): Fix typos. - -2007-01-05 Richard Stallman - - * modes.texi (Defining Minor Modes): Fix previous change. - -2007-01-03 Richard Stallman - - * customize.texi (Variable Definitions, Customization Types): - Don't use * in doc string for defcustom. - -2007-01-02 Richard Stallman - - * variables.texi (Variable Aliases): Clarify that aliases vars - always have the same value. - - * processes.texi (Bindat Spec): Fix Texinfo usage. - - * modes.texi (Defining Minor Modes): Explain effect of command - defined with define-global-minor-mode on new buffers. - -2006-12-30 Kim F. Storm - - * keymaps.texi (Tool Bar): Describe `grow-only' value of - `auto-resize-tool-bars'. - -2006-12-30 Richard Stallman - - * keymaps.texi (Active Keymaps): Fix previous change. - -2006-12-30 Nick Roberts - - * keymaps.texi (Active Keymaps): Make xref to lookup-key. - -2006-12-30 Kim F. Storm - - * processes.texi (Bindat Spec): Clarify using field names in - length specifications. - -2006-12-29 Kim F. Storm - - * processes.texi (Bindat Spec): Explain eval forms and lengths better. - Add count and index variables for eval forms in repeat blocks. - -2006-12-24 Richard Stallman - - * customize.texi (Variable Definitions): - Document new name custom-add-frequent-value. - -2006-12-19 Kim F. Storm - - * commands.texi (Misc Events): User signals now result in sigusr1 - and sigusr2 events which are handled through special-event-map. - (Special Events): User signals and drag-n-drop are special. - -2006-12-17 Richard Stallman - - * loading.texi (Named Features): Explain subfeatures better. - - * customize.texi: Use "option" only for user options. - For the keyword values inside defcustom etc, say "keywords". - For :options value's elements, say "elements". - :group should not be omitted. - - * syntax.texi (Parsing Expressions): Split up node. - (Motion via Parsing, Position Parse, Parser State) - (Low-Level Parsing, Control Parsing): New subnodes. - (Parser State): Document syntax-ppss-toplevel-pos. - - * positions.texi (List Motion): Punctuation fix. - - * files.texi (File Name Completion): Document PREDICATE arg - to file-name-completion. - -2006-12-16 Eli Zaretskii - - * internals.texi (Building Emacs, Writing Emacs Primitives): - Add index entries. - -2006-12-11 Richard Stallman - - * modes.texi (Font Lock Basics): Explain how nil for font-lock-defaults - affects face menu. Explain how to make it non-nil without enabling - any fontification. - -2006-12-10 Chong Yidong - - * modes.texi (Font Lock Basics): Document nil value of - font-lock-defaults. - -2006-12-10 Glenn Morris - - * abbrevs.texi (Defining Abbrevs): Mention `define-abbrev' 'force - value for system-flag argument. Abbrev tables may not be empty - when major modes are loaded. - -2006-12-08 Juanma Barranquero - - * makefile.w32-in (maintainer-clean): Partially revert last - change; delete "elisp-?" and "elisp-??" instead of "elisp-*" - to protect elisp-covers.texi. - -2006-12-07 Juanma Barranquero - - * makefile.w32-in (maintainer-clean): Depend on `distclean'. - Don't remove elisp* info files; they are already deleted by the - `clean' and `distclean' targets, and they are in the $(infodir) - directory, not the current one. - -2006-12-04 Kim F. Storm - - * commands.texi (Misc Events): Update signal events. - (Event Examples): Add signal example. - -2006-11-29 Richard Stallman - - * frames.texi (Visibility of Frames): Explain visible windows - can be covered by others. Add xref for raise-frame. - -2006-11-28 Richard Stallman - - * searching.texi (Regexp Special): Update when ^ is special. - -2006-11-27 Eli Zaretskii - - * customize.texi (Customization, Common Keywords) - (Group Definitions, Variable Definitions, Composite Types) - (Type Keywords, Customization Types): Add index entries for - various customization keywords. - -2006-11-23 Stefan Monnier - - * modes.texi (Multiline Font Lock): Rephrase some parts for clarity. - -2006-11-10 Jan Djärv - - * frames.texi (Window System Selections): Remove clipboard from - description of selection-coding-system. - -2006-11-06 Richard Stallman - - * lists.texi (List Variables): Document COMPARE-FN. - - * keymaps.texi: Avoid use of "binding" to mean a relation; - use it only to refer to the meaning associated with a key. - (Keymaps): Change menu node description. - - * elisp.texi (Top): Change menu node description. - - * display.texi (Managing Overlays): Document overlay-recenter. - -2006-10-29 Chong Yidong - - * Makefile.in: Use relative paths to avoid advertising filesystem - contents during compilation. - -2006-10-23 Kim F. Storm - - * commands.texi (Event Input Misc): Update unread-command-events. - -2006-10-23 Nick Roberts - - * lists.texi (Sets And Lists): Fix typos. - -2006-10-18 Juanma Barranquero - - * control.texi (Processing of Errors): Use @var for an argument, - not @code. - -2006-10-16 Richard Stallman - - * edebug.texi (Edebug Recursive Edit): Minor cleanup. - - * keymaps.texi (Format of Keymaps): Show all the keymap element - patterns that result from menu items. - (Key Lookup): Minor cleanups. - - * modes.texi (Precalculated Fontification): Don't say that - not setting font-lock-defaults avoids loading font-lock. - - * help.texi (Documentation): Move xref to Emacs Manual here. - (Documentation Basics): From here. - Also doc emacs-lisp-docstring-fill-column. - - * elisp.texi: Update version and ISBN. - - * commands.texi (Interactive Call): Clarify KEYS arg to - call-interactively is a vector. - (Command Loop Info): Delete anchor in this-command-keys. - Add anchor in this-command-keys-vector. - (Recursive Editing): Document how recursive-edit - handles the current buffer. - -2006-10-13 Chong Yidong - - * frames.texi (Frame Titles): %c and %l are ignored in - frame-title-format. - -2006-10-11 Richard Stallman - - * keymaps.texi (Key Sequences): Clarify use of kbd. - -2006-10-10 Kim F. Storm - - * lists.texi (Sets And Lists): Add memql. - -2006-10-03 Richard Stallman - - * searching.texi (Char Classes): Document :multibyte: and :unibyte:. - Clarify :ascii: and :nonascii:. - -2006-09-29 Juri Linkov - - * modes.texi (%-Constructs): Reorder coding systems in the - documentation of %z to the real order displayed in the modeline. - -2006-09-25 Richard Stallman - - * os.texi (Timers): Describe timer-max-repeats. - -2006-09-25 Chong Yidong - - * os.texi (Timers): Mention with-local-quit. - -2006-09-24 Richard Stallman - - * searching.texi (Searching and Matching): Mention property search. - - * commands.texi (Command Loop Info): Explain how read-event affects - this-command-keys. - -2006-09-20 Richard Stallman - - * os.texi (Timers): Clarify about REPEAT when timer is delayed. - - * windows.texi (Window Start): Minor cleanups. - -2006-09-20 Kim F. Storm - - * windows.texi (Window Start): pos-visible-in-window-p allows - specifying t for position to mean "end of window". - Add window-line-height. - - * anti.texi (Antinews): Mention window-line-height. - -2006-09-19 David Kastrup - - * keymaps.texi (Searching Keymaps): Small clarification. - -2006-09-18 Richard Stallman - - * keymaps.texi (Creating Keymaps): Explain that keymap prompt strings - cause keyboard menus. - (Menu Keymaps): Likewise. - (Defining Menus, Keyboard Menus): Clarify. - - * text.texi (Fields): Clarify explanation of constrain-to-field. - -2006-09-16 Eli Zaretskii - - * variables.texi (Tips for Defining): Fix a typo. - -2006-09-15 Richard Stallman - - * keymaps.texi (Remapping Commands, Searching Keymaps) - (Active Keymaps): Clean up previous change. - -2006-09-15 Jay Belanger - - * gpl.texi: Replace "Library Public License" by "Lesser Public - License" throughout. - -2006-09-15 David Kastrup - - * keymaps.texi (Active Keymaps): Adapt description to use - `get-char-property' instead `get-text-property'. Explain how - mouse events change this. Explain the new optional argument of - `key-binding' and its mouse-dependent lookup. - (Searching Keymaps): Adapt description similarly. - (Remapping Commands): Explain the new optional argument of - `command-remapping'. - -2006-09-14 Richard Stallman - - * keymaps.texi (Searching Keymaps): Clarification. - (Active Keymaps): Refer to Searching Keymaps instead of duplication. - -2006-09-13 Richard Stallman - - * objects.texi (Character Type): Node split. - Add xref to Describing Characters. - (Basic Char Syntax, General Escape Syntax) - (Ctl-Char Syntax, Meta-Char Syntax): New subnodes. - -2006-09-11 Richard Stallman - - * display.texi (Display Table Format): Wording clarification. - (Glyphs): Clarifications. - -2006-09-10 Chong Yidong - - * keymaps.texi (Active Keymaps): Mention that key-binding checks - local maps. - -2006-09-10 Kim F. Storm - - * display.texi (Forcing Redisplay): Document return value of - function redisplay. - -2006-09-09 Richard Stallman - - * windows.texi (Window Hooks): Explain limits of - window-scroll-functions. - - * display.texi (Fringe Indicators): Update for last change in - indicate-buffer-boundaries. - -2006-09-08 Richard Stallman - - * processes.texi (Bindat Spec): Suggest names ending in -bindat-spec. - -2006-09-06 Kim F. Storm - - * frames.texi (Display Feature Testing): display-mm-dimensions-alist. - - * windows.texi (Window Start): Update pos-visible-in-window-p. - -2006-09-04 Richard Stallman - - * processes.texi (Accepting Output): Explain SECONDS=0 for - accept-process-output. - - * os.texi (Idle Timers): Explain why timer functions should not - loop until (input-pending-p). - -2006-09-02 Eli Zaretskii - - * makefile.w32-in (usermanualdir): New variable. - (elisp.dvi): Use it. - -2006-09-01 Eli Zaretskii - - * buffers.texi (Buffer Modification): Fix last change. - -2006-09-01 Chong Yidong - - * buffers.texi (Buffer Modification): - Document buffer-chars-modified-tick. - -2006-08-31 Richard Stallman - - * modes.texi (Syntactic Font Lock): Mention specific faces once again. - -2006-08-31 Richard Bielawski (tiny change) - - * modes.texi (Syntactic Font Lock): - Mention font-lock-syntactic-face-function - instead of specific faces. - -2006-08-29 Chong Yidong - - * display.texi (Images): Add xrref to display-images-p. - -2006-08-28 Kenichi Handa - - * nonascii.texi (Lisp and Coding Systems): Fix description of - detect-coding-region. - -2006-08-27 Michael Olson - - * processes.texi (Transaction Queues): Remove stray quote - character. - -2006-08-25 Richard Stallman - - * os.texi (Idle Timers): run-with-idle-timer allows Lisp time value. - Add xref. - -2006-08-24 Chong Yidong - - * os.texi (Timers): Avoid waiting inside timers. - -2006-08-21 Lute Kamstra - - * Makefile.in: Use ../man/texinfo.tex to build elisp.dvi. - -2006-08-20 Richard Stallman - - * os.texi (Idle Timers): New node, split out from Timers. - Document current-idle-time. - * commands.texi (Reading One Event): Update xref. - * elisp.texi (Top): Update subnode menu. - -2006-08-16 Richard Stallman - - * keymaps.texi (Extended Menu Items): Show format of cached - bindings in extended menu items. - - * customize.texi (Variable Definitions): Explain when the - standard value expression is evaluated. - -2006-08-15 Chong Yidong - - * commands.texi (Reading One Event): Explain idleness in - `read-event'. - -2006-08-12 Chong Yidong - - * text.texi (Near Point): Say "cursor" not "terminal cursor". - (Commands for Insertion): Remove split-line since it's not - relevant for Lisp programming. - (Yank Commands): Rewrite introduction. - (Undo): Clarify. - (Maintaining Undo): Clarify. Document undo-ask-before-discard. - (Filling): Remove redundant comment. Clarify return value of - current-justification. - (Margins): Minor clarifications. - (Adaptive Fill): Update default value of adaptive-fill-regexp. - (Sorting): Update definition of sort-lines. - (Columns): Clarify behavior of sort-columns. - (Indent Tabs): Link to Tab Stops in Emacs manual. - (Special Properties): Clarify. - (Clickable Text): Mention Buttons package. - -2006-08-12 Kevin Ryde - - * os.texi (Time Parsing): Add %z to description of - format-time-string, as per docstring. Add cross reference to - glibc manual for strftime. - -2006-08-08 Richard Stallman - - * modes.texi: Clean up wording in previous change. - -2006-08-07 Chong Yidong - - * modes.texi (Hooks): Clarify. - (Major Mode Basics): Mention define-derived-mode explicitly. - (Major Mode Conventions): Rebinding RET is OK for some modes. - Mention change-major-mode-hook and after-change-major-mode-hook. - (Example Major Modes): Move to end of Modes section. - (Mode Line Basics): Clarify. - (Mode Line Data): Mention help-echo and local-map in strings. - Explain reason for treatment of non-risky variables. - (Properties in Mode): Clarify. - (Faces for Font Lock): Add font-lock-negation-char-face. - -2006-08-04 Eli Zaretskii - - * strings.texi (Formatting Strings): Warn against arbitrary - strings as first arg to `format'. - -2006-07-31 Thien-Thi Nguyen - - * text.texi (Clickable Text): Mention `help-echo' text property. - Update intro, examples and associated explanations. - -2006-07-31 Richard Stallman - - * commands.texi: Update xrefs. - (Event Mod): New node, cut out from old Translating Input. - - * maps.texi: Update xrefs. - - * keymaps.texi (Translation Keymaps): New node. - Update xrefs from Translating Input to Translation Keymaps. - - * elisp.texi (Top): Update subnode menu. - - * display.texi (Face Functions): Fix explanations of FRAME=t or nil. - - * os.texi (System Interface): Fix menu descriptions of some nodes. - (Translating Input): Node deleted. - -2006-07-31 Nick Roberts - - * modes.texi (Minor Mode Conventions): Update xref for add-to-list. - - * lists.texi (Sets And Lists): Likewise. - -2006-07-30 Thien-Thi Nguyen - - * text.texi (Fields): Mention POS - requirement when narrowing is in effect. - -2006-07-28 Richard Stallman - - * display.texi (Face Attributes): Simplify wording. - (Attribute Functions): Clarify meaning of new-frame default - attribute settings. - - * customize.texi (Common Keywords): Document how to use - :package-version in a package not in Emacs. - -2006-07-28 Kim F. Storm - - * commands.texi (Reading One Event): Fix last change. - -2006-07-26 Chong Yidong - - * commands.texi (Reading One Event): Document SECONDS argument for - read-event, read-char, and read-char-exclusive. - -2006-07-25 Stefan Monnier - - * modes.texi (Multiline Font Lock): Can't use jit-lock-defer-multiline - to ensure correct identification. - -2006-07-24 Richard Stallman - - * text.texi (Clickable Text): Clarify. - - * sequences.texi (Vector Functions): Delete duplicate xref. - - * objects.texi (Function Type): Clarify. - - * modes.texi (Keymaps and Minor Modes): List punct chars for minor - modes. - - * lists.texi (List Variables): New node. - Material moved from other nodes. - - * variables.texi (Setting Variables): add-to-list and - add-to-ordered-list moved to List Variables node. - -2006-07-23 Thien-Thi Nguyen - - * text.texi (Links and Mouse-1): - For mouse-on-link-p, expand on arg POS. - -2006-07-21 Kim F. Storm - - * display.texi (Forcing Redisplay): Don't mention systems which - don't support sub-second timers for redisplay-preemption-period. - - * os.texi (Terminal Output): Clarify text vs graphical terminal. - -2006-07-21 Eli Zaretskii - - * frames.texi (Input Focus): Document that focus-follows-mouse has - no effect on MS-Windows. - -2006-07-18 Richard Stallman - - * display.texi (Forcing Redisplay): Cleanups in previous change. - - * processes.texi (Low-Level Network): Make menu more convenient. - -2006-07-18 Kim F. Storm - - * display.texi (Forcing Redisplay): redisplay-preemption-period - only used on window systems. Add xref to Terminal Output. - - * os.texi (Terminal Output): baud-rate only controls preemption on - non-window systems. Add xref to Forcing Redisplay. - - * processes.texi (Low-Level Network): Rename node "Make Network" - to "Network Processes". - -2006-07-18 Karl Berry - - * variables.texi, functions.texi, customize.texi, loading.texi: - * edebug.texi, minibuf.texi: Fix page breaks through chapter 20. - -2006-07-17 Chong Yidong - - * commands.texi (Waiting): Document batch-mode sit-for behavior. - -2006-07-17 Richard Stallman - - * eval.texi, elisp.texi, text.texi: Use real doublequote inside menus. - Put period and comma inside quotes. - - * loading.texi, markers.texi: Use real doublequote inside menus. - - * windows.texi: Put point and comma inside quotes. - (Textual Scrolling): Use @samp for error message. - - * variables.texi, tips.texi, syntax.texi, symbols.texi: - * strings.texi, streams.texi, processes.texi, os.texi: - * objects.texi, numbers.texi, modes.texi, minibuf.texi: - * lists.texi, keymaps.texi, intro.texi, hash.texi, internals.texi: - * gpl.texi, functions.texi, files.texi, frames.texi, doclicense.texi: - * display.texi, control.texi, commands.texi, buffers.texi, anti.texi: - Put point and comma inside quotes. - - * control.texi (Processing of Errors): Add command-error-function. - - * variables.texi (File Local Variables): Clarify that - file local variables make buffer-local bindings. - - * modes.texi (Syntactic Font Lock): Give default for - font-lock-syntax-table. - -2006-07-17 Nick Roberts - - * text.texi (Special Properties): Clean up previous change. - -2006-07-16 Karl Berry - - * objects.texi, numbers.texi, strings.texi, lists.texi, hash.texi: - * control.texi: Fix bad page breaks through chapter 10 (control). - - * anti.texi (Antinews): Reorder face-attribute fns to avoid - underfull hbox. - -2006-07-15 Nick Roberts - - * text.texi (Special Properties): Describe fontified text property - in relation to a character (not text). - -2006-07-15 Kim F. Storm - - * maps.texi (Standard Keymaps): Add xref for minibuffer maps. - Add apropos-mode-map, custom-mode-map, esc-map, global-map, - grep-mode-map, help-map, help-mode-map, kmacro-map, and tool-bar-map. - - * anti.texi (Antinews): Mention redisplay function. - The kbd macro existed, but was not documented, before 22.x. - Function pos-visible-in-window-p is not new in 22.x, just enhanced. - -2006-07-14 Nick Roberts - - * display.texi (Displaying Messages): Add anchor. - - * frames.texi (Dialog Boxes): Use it. - -2006-07-12 Richard Stallman - - * objects.texi (Frame Type): Explain nature of frames better. - - * frames.texi (Frames): Explain nature of frames better. - -2006-07-12 Ken Manheimer - - * tips.texi (Coding Conventions): Explain why use cl at compile time. - -2006-07-12 YAMAMOTO Mitsuharu - - * frames.texi (Window System Selections): Mention scrap support for Mac. - Default value of x-select-enable-clipboard is t on Mac. - - * os.texi (Getting Out): Suspending is not allowed on Mac, either. - -2006-07-11 Kim F. Storm - - * display.texi (Forcing Redisplay): Add `redisplay' function. - Don't mention (sit-for -1) -- use (redisplay t) instead. - - * commands.texi (Waiting): (sit-for -1) is no longer special. - (sit-for 0) is equivalent to (redisplay). - Iconifying/deiconifying no longer makes sit-for return. - -2006-07-10 Nick Roberts - - * display.texi (Buttons): Fix typo. - - * index.texi, elisp.texi (New Symbols): Comment node out. - -2006-07-09 Richard Stallman - - * display.texi (Truncation): Clean up previous change. - -2006-07-08 Richard Stallman - - * commands.texi (Interactive Call): Use 3 as prefix in example - for execute-extended-command. - - * display.texi (Attribute Functions): Move paragraph about - compatibility with Emacs < 21. - -2006-07-09 Kim F. Storm - - * display.texi (Refresh Screen): Clarify force-window-update. - (Truncation): "Normally" indicated by fringe arrows. - -2006-07-08 Eli Zaretskii - - * windows.texi (Textual Scrolling, Resizing Windows): - * variables.texi (Constant Variables): - * text.texi (Buffer Contents, Deletion, Changing Properties) - (Property Search, Special Properties, Sticky Properties) - (Links and Mouse-1, Fields, Change Hooks): - * syntax.texi (Syntax Table Functions, Parsing Expressions) - (Categories): - * symbols.texi (Other Plists): - * streams.texi (Output Variables): - * processes.texi (Input to Processes, Query Before Exit): - * positions.texi (Word Motion, Text Lines, List Motion): - * os.texi (Init File, System Environment, Sound Output) - (Session Management): - * nonascii.texi (Text Representations, Character Sets) - (Chars and Bytes, Locales): - * modes.texi (Defining Minor Modes, Header Lines): - * minibuf.texi (Minibuffer Contents): - * markers.texi (Information from Markers): - * lists.texi (List Elements, Building Lists, Association Lists): - * keymaps.texi (Tool Bar): - * hash.texi (Creating Hash, Hash Access, Defining Hash, Other Hash): - * functions.texi (What Is a Function, Mapping Functions): - * frames.texi (Creating Frames, Parameter Access, Pointer Shape) - (Color Names, Text Terminal Colors, Display Feature Testing): - * files.texi (Visiting Functions, File Name Components) - (Unique File Names, Contents of Directories): - * display.texi (Forcing Redisplay, Displaying Messages) - (Temporary Displays, Font Selection, Auto Faces) - (Font Lookup, Fringe Indicators, Display Margins) - (Image Descriptors, Showing Images, Image Cache, Button Types) - (Making Buttons, Manipulating Buttons, Button Buffer Commands) - (Display Table Format, Glyphs): - * control.texi (Iteration): - * commands.texi (Command Loop Info, Adjusting Point): - * backups.texi (Making Backups, Auto-Saving): - Remove @tindex entries. - -2006-07-07 Kim F. Storm - - * display.texi (Fringe Cursors): Fix typo. - (Customizing Bitmaps): Fix define-fringe-bitmap entry. - (Overlay Arrow): Default is overlay-arrow fringe indicator. - -2006-07-05 Richard Stallman - - * text.texi (Buffer Contents): Add example of text props - in result of buffer-substring. - (Text Properties): Explain better about use of specific property names. - (Property Search): Some cleanups; reorder some functions. - - * keymaps.texi (Changing Key Bindings): Cleanup. - Add xref to Key Binding Conventions. - - * display.texi (Attribute Functions): Add examples for - face-attribute-relative-p. - - * tips.texi (Coding Conventions): Cleanup last change. - -2006-07-05 Karl Berry - - * elisp.texi: Use @fonttextsize 10pt, a la emacs.texi. - Remove @setchapternewpage odd. - Result is 1013 pages, down from 1100. - - * anti.texi, customize.texi, display.texi, internals.texi: - * minibuf.texi, modes.texi, tips.texi: - Fix overfull/underfull boxes. - -2006-07-05 Thien-Thi Nguyen - - * edebug.texi (Instrumenting): - Add Edebug-specific findex for eval-buffer. - * loading.texi (Loading): - Replace eval-current-buffer with eval-buffer. - -2006-06-30 Nick Roberts - - * locals.texi (Standard Buffer-Local Variables): Update the list - of variables. - -2006-06-26 Nick Roberts - - * files.texi (File Name Completion): Point user to the node - "Reading File Names". - -2006-06-24 Eli Zaretskii - - * files.texi (Contents of Directories): Document case-insensitive - behavior on respective filesystems. - - * objects.texi (Character Type): Document that Emacs signals an - error for unsupported Unicode characters specified as \uNNNN. - -2006-06-19 Richard Stallman - - * processes.texi (Bindat Spec): Clarify previous change. - -2006-06-16 Richard Stallman - - * tips.texi (Coding Conventions): Better explain conventions - for definition constructs. - - * text.texi (Special Properties): String value of `read-only' - serves as the error message. - - * objects.texi (Character Type): Clarify prev. change. - (Non-ASCII in Strings): Mention \u and \U. - - * commands.texi (Using Interactive): Explain problem of - markers, etc., in command-history. - -2006-06-14 Kim F. Storm - - * commands.texi (Waiting): Negative arg to sit-for forces - redisplay even if input is pending. - - * display.texi (Forcing Redisplay): Use (sit-for -1) to force a - redisplay. Remove incorrect example of binding redisplay-dont-pause - around (sit-for 0). - -2006-06-13 Richard Stallman - - * display.texi (Forcing Redisplay): Clarify previous change. - -2006-06-13 Romain Francoise - - * display.texi (Forcing Redisplay): Fix typo. - -2006-06-13 Kim F. Storm - - * display.texi (Forcing Redisplay): Add redisplay-preemption-period. - -2006-06-10 Luc Teirlinck - - * tips.texi (Coding Conventions): Add `@end itemize'. - -2006-06-10 Richard Stallman - - * tips.texi (Coding Conventions): Explain use of coding systems - to ensure one decoding for strings. - -2006-06-09 Aidan Kehoe - - * objects.texi (Character Type): Describe the \uABCD and \U00ABCDEF - syntax. - -2006-06-07 Eli Zaretskii - - * display.texi (Font Selection): Remove description of - clear-face-cache. - - * compile.texi (Eval During Compile): Fix a typo. Add index - entries for possible uses of eval-when-compile. - -2006-06-04 Thien-Thi Nguyen - - * display.texi (Abstract Display): Fix typo. - -2006-06-03 Eli Zaretskii - - * minibuf.texi (Minibuffer History) : - Reword variable's description. - -2006-06-01 Richard Stallman - - * windows.texi (Splitting Windows): Clarify splitting nonselected - window. - -2006-05-31 Juri Linkov - - * minibuf.texi (Minibuffer History): Add history-add-new-input. - -2006-05-30 Richard Stallman - - * display.texi (Line Height): Fix errors in description of - default line height and line-height property. - - * nonascii.texi (Default Coding Systems): Further clarification. - -2006-05-29 Luc Teirlinck - - * internals.texi (Pure Storage): Mention that an overflow in pure - space causes a memory leak. - (Garbage Collection): If there was an overflow in pure space, - `garbage-collect' returns nil. - -2006-05-30 Eli Zaretskii - - * nonascii.texi (Default Coding Systems): Fix it some more. - -2006-05-29 Eli Zaretskii - - * nonascii.texi (Default Coding Systems): Fix last change. - -2006-05-29 Kenichi Handa - - * nonascii.texi (find-operation-coding-system): Describe the new - argument format (FILENAME . BUFFER). - -2006-05-28 Richard Stallman - - * tips.texi (Coding Conventions): Better explain reasons not to - advise other packages or use `eval-after-load'. - -2006-05-29 Kim F. Storm - - * processes.texi (Bindat Functions): Rename `pos' and `raw-data' to - `bindat-idx' and `bindat-raw' for clarity. - -2006-05-27 Thien-Thi Nguyen - - * processes.texi (Bindat Spec): Expand on `repeat' handler. - - * display.texi (Display): Add "Abstract Display" to menu. - (Abstract Display, Abstract Display Functions) - (Abstract Display Example): New nodes. - * elisp.texi (Top): Add "Abstract Display" to menu. - -2006-05-27 Chong Yidong - - * keymaps.texi (Key Sequences): Link to input events definition. - (Format of Keymaps): Delete material duplicated in Keymap Basics. - - * files.texi (Changing Files): Document updated argument list for - copy-file. - -2006-05-27 Thien-Thi Nguyen - - * processes.texi (Bindat Functions): Explain term "total length". - Use it in bindat-length and bindat-pack descriptions. - -2006-05-26 Eli Zaretskii - - * tips.texi (Coding Conventions): Advise against using - eval-after-load in packages. Add an index entry. - -2006-05-25 Juri Linkov - - * minibuf.texi (Text from Minibuffer): Undocument keep-all. - - * modes.texi (%-Constructs): Add %e, %z, %Z. - -2006-05-25 Richard Stallman - - * elisp.texi (Top): Update subnode menu. - - * keymaps.texi (Keymap Basics): New node, split out of Key Sequences. - (Keymaps): Update menu. - -2006-05-25 Chong Yidong - - * keymaps.texi (Key Sequences): Some clarifications. - -2006-05-25 Thien-Thi Nguyen - - * processes.texi (Bindat Functions): Say "unibyte string" - explicitly for bindat-unpack and bindat-pack descriptions. - (Bindat Examples): Don't call `string-make-unibyte' in example. - -2006-05-25 Chong Yidong - - * keymaps.texi (Key Sequences): Rename from Keymap Terminology. - Explain string and vector representations of key sequences. - - * keymaps.texi (Changing Key Bindings): - * commands.texi (Interactive Codes): - * help.texi (Describing Characters): Refer to it. - -2006-05-23 Luc Teirlinck - - * frames.texi (Pointer Shape): @end table -> @end defvar. - -2006-05-22 Richard Stallman - - * elisp.texi (Top): Update subnode menus. - - * frames.texi (Pointer Shape): Node renamed from Pointer Shapes. - Contents rewritten; material from old Pointer Shape node moved here. - - * display.texi (Pointer Shape): Node deleted. - (Image Descriptors): Minor cleanup. - -2006-05-21 Richard Stallman - - * syntax.texi (Parsing Expressions): Update info on which STATE - elements are ignored. - -2006-05-19 Luc Teirlinck - - * hooks.texi (Standard Hooks): Correct typo. - - * gpl.texi (GPL): ifinfo -> ifnottex. - -2006-05-19 Michael Ernst (tiny change) - - * searching.texi (Simple Match Data): Warn about match data being - set anew by every search. - -2006-05-17 Richard Stallman - - * minibuf.texi (Minibuffer History): Clarify. - - * searching.texi (Regexp Special): Clarify nested regexp warning. - -2006-05-16 Kim F. Storm - - * minibuf.texi (Minibuffer History): Update add-to-history. - -2006-05-15 Oliver Scholz (tiny change) - - * nonascii.texi (Explicit Encoding): - Fix typo (encoding<->decoding). - -2006-05-14 Richard Stallman - - * buffers.texi (Creating Buffers): Cleanup. - - * files.texi (Visiting Functions): Rewrite in find-file-noselect. - -2006-05-13 Eli Zaretskii - - * buffers.texi (Current Buffer): Document that with-temp-buffer - disables undo. - - * os.texi (Terminal-Specific): More accurate description of how - Emacs searches for the terminal-specific libraries. - -2006-05-12 Eli Zaretskii - - * hooks.texi (Standard Hooks) [iftex]: Convert @xref's to - emacs-xtra to @inforef's. - - * text.texi (Undo): Document that undo is turned off in buffers - whose names begin with a space. - - * buffers.texi (Buffer Names): Add index entries for buffers whose - names begin with a space. - (Creating Buffers): Document that undo is turned off in buffers - whose names begin with a space. - - * files.texi (Visiting Functions, Reading from Files) - (Saving Buffers): Mention code and EOL conversions by file I/O - primitives and subroutines. - - * nonascii.texi (Lisp and Coding Systems): - Document coding-system-eol-type. Add index entries for eol conversion. - - * display.texi (Defining Faces): Mention `mac', and add an xref to - where window-system is described. - -2006-05-10 Richard Stallman - - * internals.texi (Writing Emacs Primitives): Clarify GCPRO rules. - -2006-05-10 Reiner Steib - - * variables.texi (File Local Variables): Recommend to quote lambda - expressions in safe-local-variable property. - -2006-05-09 Richard Stallman - - * variables.texi (File Local Variables): - Document safe-local-eval-forms and safe-local-eval-function. - -2006-05-07 Kim F. Storm - - * minibuf.texi (Minibuffer History): Remove keep-dups arg - from add-to-history. - -2006-05-07 Romain Francoise - - * commands.texi (Event Input Misc): - * compile.texi (Eval During Compile): - * internals.texi (Buffer Internals): - * minibuf.texi (Initial Input): - * nonascii.texi (Scanning Charsets): - * numbers.texi (Comparison of Numbers): - * windows.texi (Textual Scrolling, Vertical Scrolling): - Fix various typos. - -2006-05-06 Eli Zaretskii - - * hooks.texi (Standard Hooks): Replace inforef to emacs-xtra by - conditional xref's to either emacs or emacs-xtra, depending on - @iftex/@ifnottex. - - * minibuf.texi (Minibuffer History): Document add-to-history. - -2006-05-05 Eli Zaretskii - - * internals.texi (Pure Storage): Mention the pure overflow message - at startup. - -2006-05-05 Johan BockgÃ¥rd - - * keymaps.texi (Active Keymaps): Fix pseudo-Lisp syntax. - (Searching Keymaps): Fix pseudo-Lisp description of keymap - search. - -2006-05-01 Richard Stallman - - * intro.texi (nil and t): Clarify. - - * variables.texi (File Local Variables): Suggest using booleanp. - -2006-05-01 Juanma Barranquero - - * objects.texi (Type Predicates): Fix typos. - -2006-05-01 Stefan Monnier - - * intro.texi (nil and t): Add booleanp. - - * objects.texi (Type Predicates): Add links for booleanp and - string-or-null-p. - -2006-04-29 Richard Stallman - - * modes.texi (Multiline Font Lock): Rename from - Multi line Font Lock Elements. Much clarification. - (Font Lock Multiline, Region to Fontify): Much clarification. - -2006-04-29 Stefan Monnier - - * variables.texi (File Local Variables): Remove the special case t for - safe-local-variable. - -2006-04-26 Richard Stallman - - * syntax.texi (Parsing Expressions): Minor cleanup. - -2006-04-18 Richard Stallman - - * tips.texi (Coding Conventions): Explain when the package's - prefix should appear later on (not at the start of the name). - - * searching.texi (String Search): Clarify effect of NOERROR. - - * modes.texi (Imenu): Clarify what special items do. - - * hooks.texi (Standard Hooks): Delete text about old hook names. - -2006-04-17 Romain Francoise - - * variables.texi (Local Variables): Update the default value of - `max-specpdl-size'. - -2006-04-15 Michael Olson - - * processes.texi (Transaction Queues): Mention the new optional - `delay-question' argument for `tq-enqueue'. - -2006-04-13 Bill Wohler - - * customize.texi (Common Keywords): Use dotted notation for - :package-version value. Specify its values. Improve documentation - for customize-package-emacs-version-alist. - -2006-04-12 Bill Wohler - - * customize.texi (Common Keywords): Move description of - customize-package-emacs-version-alist to @defvar. - -2006-04-10 Bill Wohler - - * customize.texi (Common Keywords): Add :package-version. - -2006-04-10 Kim F. Storm - - * text.texi (Buffer Contents): Add NOPROPS arg to - filter-buffer-substring. - -2006-04-08 Kevin Ryde - - * os.texi (Command-Line Arguments): Update xref to emacs manual - "Command Arguments" -> "Emacs Invocation", per change there. - -2006-04-08 Thien-Thi Nguyen - - * display.texi (Other Display Specs): Arrange a @code{DOTTED-LIST} to - be on one line to help makeinfo not render two spaces after the dot. - -2006-04-07 Reiner Steib - - * strings.texi (Predicates for Strings): Add string-or-null-p. - -2006-03-28 Kim F. Storm - - * processes.texi (Accepting Output): Remove obsolete (and incorrect) - remarks about systems that don't support fractional seconds. - -2006-03-25 Karl Berry - - * elisp.texi: Use @copyright{} instead of (C), and do not indent - the year list. - -2006-03-21 Nick Roberts - - * display.texi (Fringe Indicators): Fix typos. - -2006-03-19 Luc Teirlinck - - * tips.texi (Documentation Tips): One can now also write `program' - in front of a quoted symbol in a docstring to prevent making a - hyperlink. - -2006-03-19 Alan Mackenzie - - * text.texi (Special Properties): Clarify `fontified' property. - -2006-03-16 Richard Stallman - - * display.texi (Defining Images): Minor cleanup. - -2006-03-16 Bill Wohler - - * display.texi (Defining Images): In image-load-path-for-library, - prefer user's images. - -2006-03-15 Stefan Monnier - - * modes.texi (Region to Fontify): Remove font-lock-lines-before. - -2006-03-15 Bill Wohler - - * display.texi (Defining Images): Fix example in - image-load-path-for-library by not recommending that one binds - image-load-path. Just defvar it to placate compiler and only use - it if previously defined. - -2006-03-14 Bill Wohler - - * display.texi (Defining Images): In image-load-path-for-library, - always return list of directories. Update example. - -2006-03-14 Alan Mackenzie - - * modes.texi: New node, "Region to Fontify" (for Font Lock). - This describes font-lock-extend-region-function. - ("Other Font Lock Variables"): Move "font-lock-lines-before" to - the new node "Region to Fontify". - -2006-03-13 Richard Stallman - - * display.texi (Invisible Text): The impossible position is - now before the invisible text, not after. - (Defining Images): Clean up last change. - -2006-03-11 Bill Wohler - - * display.texi (Defining Images): Add image-load-path-for-library. - -2006-03-11 Luc Teirlinck - - * text.texi (Adaptive Fill): Fix Texinfo usage. - - * strings.texi (Creating Strings): Fix Texinfo usage. - - * searching.texi (Regexp Special): Use @samp for regular - expressions that are not in Lisp syntax. - -2006-03-08 Luc Teirlinck - - * searching.texi (Regexp Special): Put remark between parentheses - to avoid misreading. - -2006-03-07 Luc Teirlinck - - * searching.texi (Syntax of Regexps): More accurately describe - which characters are special in which situations. - (Regexp Special): Recommend _not_ to quote `]' or `-' when they - are not special. Describe in detail when `[' and `]' are special. - (Regexp Backslash): Plenty of regexps with unbalanced square - brackets are valid, so reword that statement. - -2006-03-02 Kim F. Storm - - * keymaps.texi (Tool Bar): Add tool-bar-border. - -2006-02-28 Luc Teirlinck - - * loading.texi (Load Suffixes): Rephrase last paragraph. Fix typos. - -2006-02-27 Luc Teirlinck - - * elisp.texi (Top): Include "Load Suffixes" in the detailed menu. - - * files.texi (Locating Files): Suggest additional values for the - SUFFIXES arg of `locate-file'. Update pxref. - - * loading.texi (Loading): Include new node "Load Suffixes" in menu. - (How Programs Do Loading): Discuss the effects of Auto Compression - mode on `load'. - (Load Suffixes): New node. - (Library Search): Delete description of `load-suffixes'; it was - moved to "Load Suffixes". - (Autoload, Named Features): Mention `load-suffixes'. - -2006-02-21 Giorgos Keramidas (tiny change) - - * display.texi (Fringe Indicators, Fringe Cursors): Fix typos. - - * windows.texi (Window Tree): Fix typo. - -2006-02-20 Kim F. Storm - - * display.texi (Fringe Indicators): New section. - Move indicate-empty-lines, indicate-buffer-boundaries, and - default-indicate-buffer-boundaries here. - Add fringe-indicator-alist and default-fringes-indicator-alist. - Add list of logical fringe indicator symbols. - Update list of standard bitmap names. - (Fringe Cursors): New section. - Move overflow-newline-into-fringe here. - Add fringe-cursor-alist and default-fringes-cursor-alist. - Add list of fringe cursor symbols. - -2006-02-20 Juanma Barranquero - - * commands.texi (Using Interactive): Fix reference to node - "Minibuffers". - -2006-02-19 Richard M. Stallman - - * minibuf.texi (High-Level Completion): - Add xref to read-input-method-name. - - * files.texi (Relative File Names): Move file-relative-name here. - (File Name Expansion): From here. Minor clarifications. - - * commands.texi (Using Interactive): Add xrefs about reading input. - Clarify remarks about that moving point and mark. - Put string case before list case. - -2006-02-16 Johan BockgÃ¥rd - - * display.texi (Other Display Specs, Image Descriptors): - Revert erroneous changes. The previous description of - image-descriptors as `(image . PROPS)' was correct. - -2006-02-14 Richard M. Stallman - - * variables.texi (File Local Variables): Clarifications. - -2006-02-14 Juanma Barranquero - - * variables.texi (File Local Variables): Use @code for a cons - cell, not @var. - -2006-02-13 Chong Yidong - - * variables.texi (File Local Variables): Document new file local - variable behavior. - -2006-02-10 Kim F. Storm - - * eval.texi (Function Indirection): Add NOERROR to indirect-function. - -2006-02-08 Juanma Barranquero - - * modes.texi (%-Constructs): Remove obsolete info about - `global-mode-string'. - -2006-02-07 Richard M. Stallman - - * commands.texi (Prefix Command Arguments): Minor cleanup. - - * display.texi: "Graphical display", not window system. - - * functions.texi (What Is a Function): Fix xref. - - * keymaps.texi (Key Lookup): Clarify wrt commands vs other functions. - (Changing Key Bindings): Clarify when remapping is better than - substitute-key-definition. - -2006-02-02 Richard M. Stallman - - * minibuf.texi (Basic Completion): Completion alists are risky. - - * keymaps.texi (Active Keymaps): Clarifications. - (Searching Keymaps): New node. - (Keymaps): Update menu. - - * frames.texi (Layout Parameters): Minor clarification. - (Drag and Drop): New node. - (Frames): Update menu. - -2006-01-29 Chong Yidong - - * display.texi (Other Display Specs, Image Descriptors): - Image description is a list, not a cons cell. - -2006-01-28 Luc Teirlinck - - * lists.texi (Cons Cells): Minor correction (the cdr of a dotted - list is not necessarily a list). - -2006-01-27 Eli Zaretskii - - * frames.texi (Layout Parameters): border-width and - internal-border-width belong to the frame, not the window. - -2006-01-19 Richard M. Stallman - - * nonascii.texi (Translation of Characters): Search cmds use - translation-table-for-input. Automatically made local. - - * markers.texi (Overview of Markers): Count insertion type - as one of a marker's attributes. - - * keymaps.texi (Controlling Active Maps): New node, split out of - Active Keymaps. - (Keymaps): Menu updated. - (Active Keymaps): Give pseudocode to explain how the active - maps are searched. current-active-maps and key-binding moved here. - (Functions for Key Lookup): current-active-maps and key-binding moved. - Clarifications. - (Searching the Keymaps): New subnode. - - * elisp.texi (Top): Menu clarification. - - * display.texi (Other Display Specs): Delete duplicate entry for - just a string as display spec. Move text about recursive display - specs on such a string. - - * commands.texi (Key Sequence Input): Clarify. - Move num-nonmacro-input-events out. - (Reading One Event): num-nonmacro-input-events moved here. - -2006-01-14 Nick Roberts - - * advice.texi (Simple Advice): Update example to fit argument - change in previous-line. - -2006-01-05 Richard M. Stallman - - * markers.texi (The Mark): Fix in `mark'. - -2006-01-04 Richard M. Stallman - - * processes.texi (Misc Network, Make Network): Minor cleanups. - -2006-01-04 Kim F. Storm - - * processes.texi (Make Network): Add IPv6 addresses and handling. - (Network Feature Testing): Mention (:family ipv6). - (Misc Network): Add IPv6 formats to format-network-address. - -2005-12-30 Richard M. Stallman - - * text.texi (Changing Properties): - Don't use return value of set-text-properties. - -2005-12-29 Luc Teirlinck - - * modes.texi (Mode Line Format): Correct typo in menu. - -2005-12-29 Richard M. Stallman - - * modes.texi (Mode Line Top): New node. - (Mode Line Data): Some text moved to new node. - Explain the data structure more concretely. - (Mode Line Basics): Clarifications. - (Mode Line Variables): Clarify intro paragraph. - (%-Constructs): Clarify intro paragraph. - (Mode Line Format): Update menu. - -2005-12-28 Luc Teirlinck - - * minibuf.texi (Basic Completion): Update lazy-completion-table - examples for removal of ARGS argument. - -2005-12-23 Richard M. Stallman - - * text.texi (Undo): Restore some explanation from the version - that was deleted. - -2005-12-23 Eli Zaretskii - - * text.texi (Undo): Remove duplicate descriptions of `apply - funname' and `apply delta' elements of the undo list. - -2005-12-20 Richard M. Stallman - - * help.texi (Help Functions): Update documentation of `apropos'. - -2005-12-20 Luc Teirlinck - - * customize.texi (Type Keywords): Delete xref to "Text help-echo", - because it is confusing. If the :help-echo keyword is a function, - it is not directly used as the :help-echo overlay property, as the - xref seems to suggest (it does not take the appropriate args). - -2005-12-19 Luc Teirlinck - - * customize.texi (Common Keywords): Fix Texinfo usage. - (Group Definitions, Variable Definitions): Update for new - conventions for using `*' in docstrings. - - * tips.texi (Documentation Tips): Update for new conventions for - using `*' in docstrings. - -2005-12-16 Richard M. Stallman - - * minibuf.texi (Minibuffer Contents): Minor cleanup. - -2005-12-16 Juri Linkov - - * minibuf.texi (Minibuffer Contents): Add minibuffer-completion-contents. - -2005-12-14 Romain Francoise - - * modes.texi (Customizing Keywords): Rename `append' to `how'. - Fix typo. - -2005-12-11 Juri Linkov - - * minibuf.texi (Completion Commands): Add mention of read-file-name - for filename completion keymaps. - (Reading File Names): Add mention of filename completion keymaps - for read-file-name and xref to `Completion Commands'. - -2005-12-10 Richard M. Stallman - - * customize.texi (Common Keywords): State caveats for use of :tag. - -2005-12-08 Richard M. Stallman - - * minibuf.texi (Intro to Minibuffers): Replace list of local maps - with xrefs and better explanation. - (Completion Commands): Add the filename completion maps. - - * objects.texi (Character Type): Clarify that \s is not space - if a dash follows. - -2005-12-05 Richard M. Stallman - - * windows.texi (Resizing Windows): Delete preserve-before args. - -2005-12-05 Stefan Monnier - - * keymaps.texi (Format of Keymaps): Remove mention of a quirk - in full keymaps, since the quirk has been fixed. - -2005-12-03 Eli Zaretskii - - * hooks.texi (Standard Hooks): Add index entries. - Mention `compilation-finish-functions'. - -2005-11-27 Richard M. Stallman - - * windows.texi (Resizing Windows): Add adjust-window-trailing-edge. - -2005-11-21 Juri Linkov - - * customize.texi (Common Keywords): Update links types - custom-manual and url-link. Add link types emacs-library-link, - file-link, function-link, variable-link, custom-group-link. - -2005-11-20 Chong Yidong - - * display.texi: Revert 2005-11-20 change. - -2005-11-20 Thien-Thi Nguyen - - * processes.texi (Bindat Functions): - Say "third" to refer to zero-based index "2". - -2005-11-18 Luc Teirlinck - - * loading.texi (Library Search): Update the default value of - `load-suffixes'. - -2005-11-17 Chong Yidong - - * display.texi (Attribute Functions): Mention :ignore-defface. - -2005-11-16 Stefan Monnier - - * modes.texi (Minor Mode Conventions): Use custom-set-minor-mode. - (Minor Mode Conventions): Mention the use of a hook. - -2005-11-06 Richard M. Stallman - - * files.texi (Magic File Names): find-file-name-handler checks the - `operations' property of the handler. - -2005-11-03 Richard M. Stallman - - * variables.texi (Frame-Local Variables): Small clarification. - -2005-10-29 Chong Yidong - - * os.texi (Init File): Document ~/.emacs.d/init.el. - -2005-10-29 Richard M. Stallman - - * internals.texi (Garbage Collection): Document memory-full. - -2005-10-28 Bill Wohler - - * tips.texi (Documentation Tips): Help mode now creates hyperlinks - for URLs. - -2005-10-28 Richard M. Stallman - - * minibuf.texi (Completion Commands): Clean up prev change. - -2005-10-26 Kevin Ryde - - * compile.texi (Eval During Compile): Explain recommended uses - of eval-when-compile and eval-and-compile. - -2005-10-27 Masatake YAMATO - - * minibuf.texi (Completion Commands): - Write about new optional argument for `display-completion-list'. - -2005-10-23 Richard M. Stallman - - * display.texi (Overlay Arrow): Clarify about local bindings of - overlay-arrow-position. - -2005-10-22 Eli Zaretskii - - * internals.texi (Building Emacs): Fix last change. - -2005-10-22 Richard M. Stallman - - * internals.texi (Building Emacs): Document eval-at-startup. - -2005-10-21 Richard M. Stallman - - * loading.texi (Where Defined): load-history contains abs file names. - symbol-file returns abs file names. - -2005-10-19 Kim F. Storm - - * display.texi (Showing Images): Add max-image-size integer value. - -2005-10-18 Chong Yidong - - * display.texi (Showing Images): Document max-image-size. - -2005-10-17 Richard M. Stallman - - * commands.texi (Quitting): Minor clarification. - - * processes.texi (Sentinels): Clarify about output and quitting. - (Filter Functions): Mention with-local-quit. - -2005-10-17 Juri Linkov - - * buffers.texi (Current Buffer): - * commands.texi (Event Input Misc): - * compile.texi (Eval During Compile, Compiler Errors): - * customize.texi (Group Definitions): - * display.texi (Progress, Defining Faces): - * files.texi (Writing to Files): - * modes.texi (Mode Hooks, Defining Minor Modes): - * streams.texi (Output Functions): - * syntax.texi (Syntax Table Functions): - * text.texi (Change Hooks): - Replace `...' with `@dots{}' in `@defmac' and `@defspec'. - - * commands.texi (Quitting): Replace arg `forms' with `body' in - `with-local-quit'. - - * positions.texi (Excursions): Replace arg `forms' with `body' in - `save-excursion'. - -2005-10-08 Kim F. Storm - - * windows.texi (Window Tree): Rename window-split-tree to window-tree. - Rename manual section accordingly. - -2005-10-04 Kim F. Storm - - * windows.texi (Window Split Tree): New section describing - new function window-split-tree function. - -2005-10-03 Nick Roberts - - * display.texi (Fringe Size/Pos): Simplify and add detail. - -2005-09-30 Romain Francoise - - * minibuf.texi (High-Level Completion): Explain that the prompt - given to `read-buffer' should end with a colon and a space. - Update usage examples. - -2005-09-29 Juri Linkov - - * display.texi (Displaying Messages): Rename argument name - `string' to `format-string' in functions `message', `message-box', - `message-or-box'. - -2005-09-26 Chong Yidong - - * errors.texi (Standard Errors): Correct xrefs. - -2005-09-18 Chong Yidong - - * display.texi (Defining Images): Update documentation for - `image-load-path'. - -2005-09-17 Richard M. Stallman - - * display.texi (Defining Images): Clean up previous change. - -2005-09-16 Romain Francoise - - * elisp.texi: Specify GFDL version 1.2. - - * doclicense.texi (GNU Free Documentation License): Update to - version 1.2. - -2005-09-15 Chong Yidong - - * display.texi (Defining Images): Document `image-load-path'. - -2005-09-15 Richard M. Stallman - - * objects.texi (Printed Representation): Minor cleanup. - (Box Diagrams): Minor fix. - (Cons Cell Type): Move (...) index item here. - (Box Diagrams): From here. - (Array Type): Minor fix. - (Type Predicates): Delete index "predicates". - (Hash Table Type): Clarify xref. - (Dotted Pair Notation): Minor fix. - -2005-09-10 Chong Yidong - - * files.texi (Saving Buffers): Fix typo. - -2005-09-08 Richard M. Stallman - - * tips.texi (Programming Tips): Correct the "default" prompt spec. - -2005-09-08 Chong Yidong - - * locals.texi (Standard Buffer-Local Variables): Don't include - mode variables for minor modes. - Fix xrefs for buffer-display-count, buffer-display-table, - buffer-offer-save, buffer-saved-size, cache-long-line-scans, - enable-multibyte-characters, fill-column, header-line-format, - left-fringe-width, left-margin, and right-fringe-width. - - * hooks.texi (Standard Hooks): All hooks should conform to the - standard naming convention now. - Fix xref for `echo-area-clear-hook'. - - * display.texi (Usual Display): Note that indicate-empty-lines and - tab-width are buffer-local. - - * files.texi (Saving Buffers): Add xref to `Killing Buffers'. - - * modes.texi (Mode Help): Note that major-mode is buffer-local. - - * nonascii.texi (Encoding and I/O): Note that - buffer-file-coding-system is buffer-local. - - * positions.texi (List Motion): Note that defun-prompt-regexp is - buffer-local. - - * text.texi (Auto Filling): Note that auto-fill-function is - buffer-local. - (Undo): Note that buffer-undo-list is buffer-local. - - * windows.texi (Buffers and Windows): - Document buffer-display-count. - -2005-09-06 Richard M. Stallman - - * tips.texi (Coding Conventions): Sometimes it is ok to put the - package prefix elsewhere than at the start of the name. - -2005-09-03 Richard M. Stallman - - * tips.texi (Programming Tips): Add conventions for minibuffer - questions and prompts. - -2005-09-03 Joshua Varner (tiny change) - - * intro.texi (nil and t): Minor cleanup. - Delete spurious mention of keyword symbols. - (Evaluation Notation): Add index entry. - (A Sample Function Description): Minor cleanup. - (A Sample Variable Description): Not all vars can be set. - -2005-09-03 Thien-Thi Nguyen - - * text.texi (Buffer Contents): Use "\n" in examples' result strings. - - (Insertion): Document precise type of `insert-char' arg COUNT. - -2005-09-02 Stefan Monnier - - * modes.texi (Other Font Lock Variables): Sync the default of - font-lock-lines-before. - -2005-08-31 Michael Albinus - - * files.texi (Magic File Names): Add `make-auto-save-file-name'. - -2005-08-29 Richard M. Stallman - - * elisp.texi (Top): Update subnode menu. - - * searching.texi (Searching and Matching): Move node. - Rearrange contents and add overall explanation. - (Searching and Case): Move node. - (Searching and Matching): Update menu. - -2005-08-27 Eli Zaretskii - - * os.texi (Startup Summary): Fix the description of the initial - startup message display. - -2005-08-25 Richard M. Stallman - - * searching.texi (Search and Replace): Add replace-regexp-in-string. - -2005-08-25 Emilio C. Lopes - - * display.texi (Finding Overlays): Fix `find-overlay-prop' in - `next-overlay-change' example. - -2005-08-22 Juri Linkov - - * display.texi (Attribute Functions): Add set-face-inverse-video-p. - Fix invert-face. Fix args of face-background. - - * display.texi (Standard Faces): Delete node. - (Faces): Add xref to `(emacs)Standard Faces'. - (Displaying Faces): Fix xref to `Standard Faces'. - - * modes.texi (Mode Line Data): Fix xref to Standard Faces. - -2005-08-20 Alan Mackenzie - - * buffers.texi (The Buffer List): Clarify the manipulation of the - buffer list. - -2005-08-14 Richard M. Stallman - - * modes.texi (Auto Major Mode): interpreter-mode-alist key is not - a regexp. - -2005-08-11 Richard M. Stallman - - * elisp.texi (Top): Update subnode lists. - - * display.texi (Inverse Video): Node deleted. - - * tips.texi (Key Binding Conventions, Programming Tips, Warning Tips): - New nodes split out of Coding Conventions. - - * searching.texi (Regular Expressions): Document re-builder. - - * os.texi (Time Parsing): New node split out of Time Conversion. - - * processes.texi (Misc Network, Network Feature Testing) - (Network Options, Make Network): New nodes split out of - Low-Level Network. - -2005-08-09 Richard M. Stallman - - * frames.texi (Geometry): New node, split from Size and Position. - (Frame Parameters): Refer to Geometry. - - * buffers.texi (The Buffer List): Fix xrefs. - - * windows.texi (Splitting Windows): Fix xref. - - * frames.texi (Layout Parameters): Add xref. - - * display.texi (Line Height, Scroll Bars): Fix xrefs. - - * keymaps.texi (Menu Bar): Fix xref. - - * locals.texi (Standard Buffer-Local Variables): Fix xref. - - * modes.texi (%-Constructs): Fix xref. - - * frames.texi (Window Frame Parameters): Node split up. - (Basic Parameters, Position Parameters, Size Parameters) - (Layout Parameters, Buffer Parameters, Management Parameters) - (Cursor Parameters, Color Parameters): New subnodes. - -2005-08-09 Luc Teirlinck - - * positions.texi (Screen Lines): Update xref for previous change - in minibuf.texi. - - * minibuf.texi (Intro to Minibuffers): Update pxref for previous - change in minibuf.texi. - -2005-08-09 Richard M. Stallman - - * tips.texi (Coding Conventions): Minor cleanup. - - * modes.texi (Defining Minor Modes): Explain when init-value - can be non-nil. - - * elisp.texi (Top): Update submenu for Minibuffer. - - * minibuf.texi (Minibuffer Misc): Node split up. - (Minibuffer Commands, Minibuffer Windows, Minibuffer Contents) - (Recursive Mini): New nodes split out from Minibuffer Misc. - (Minibuffer Misc): Document max-mini-window-height. - - * hash.texi (Defining Hash): Delete stray paren in example. - - * display.texi (Echo Area Customization): Don't define - max-mini-window-height here; xref instead. - - * commands.texi (Event Input Misc): Update while-no-input. - - * advice.texi (Advising Functions): Explain when to use advice - and when to use a hook. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run install-info. - ($(infodir)/dir): New target, produced by running install-info. - -2005-07-27 Luc Teirlinck - - * modes.texi (Defining Minor Modes): The keyword for the initial - value is :init-value, not :initial-value. - -2005-07-23 Eli Zaretskii - - * loading.texi (Autoload): Make the `doctor' example be consistent - with what's in current loaddefs.el. Describe the "fn" magic in - the usage portion of the doc string. - -2005-07-22 Richard M. Stallman - - * internals.texi (Garbage Collection): Clarify previous change. - -2005-07-21 Stefan Monnier - - * internals.texi (Garbage Collection): Add gc-cons-percentage. - -2005-07-18 Juri Linkov - - * commands.texi (Accessing Events): - * frames.texi (Text Terminal Colors, Resources): - * markers.texi (The Mark): - * modes.texi (Defining Minor Modes): - Delete duplicate duplicate words. - -2005-07-16 Richard M. Stallman - - * display.texi (Managing Overlays): Clarify make-overlay - args for insertion types. - -2005-07-13 Luc Teirlinck - - * customize.texi (Variable Definitions): - Add `custom-initialize-safe-set' and `custom-initialize-safe-default'. - `standard-value' is a list too. - (Defining New Types): Use @key{RET} instead of @key{ret}. - -2005-07-13 Francis Litterio (tiny change) - - * os.texi (Translating Input): Fix typo. - -2005-07-08 Richard M. Stallman - - * README: Update edition number and size estimate. - - * elisp.texi (VERSION): Set to 2.9. - -2005-07-07 Richard M. Stallman - - * book-spine.texinfo: Update Emacs version. - - * display.texi (Inverse Video): Delete mode-line-inverse-video. - -2005-07-06 Richard M. Stallman - - * searching.texi (Regexp Search): Clarify what re-search-forward - does when the search fails. - -2005-07-05 Lute Kamstra - - * Update FSF's address in GPL notices. - - * doclicense.texi (GNU Free Documentation License): - * gpl.texi (GPL): - * tips.texi (Coding Conventions, Library Headers): - * vol1.texi: - * vol2.texi: Update FSF's address. - -2005-07-04 Richard M. Stallman - - * hooks.texi (Standard Hooks): Add occur-hook. - -2005-07-03 Luc Teirlinck - - * display.texi (The Echo Area): Correct menu. - -2005-07-03 Richard M. Stallman - - * elisp.texi (Top): Update subnode menu for Display. - - * display.texi (Displaying Messages): New node, with most - of what was in The Echo Area. - (Progress): Move under The Echo Area. - (Logging Messages): New node with new text. - (Echo Area Customization): New node, the rest of what was - in The Echo Area. Document message-truncate-lines with @defvar. - (Display): Update menu. - - * windows.texi (Textual Scrolling): Doc 3 values for - scroll-preserve-screen-position. - - * text.texi (Special Properties): Change hook functions - should bind inhibit-modification-hooks around altering buffer text. - - * keymaps.texi (Key Binding Commands): Call binding BINDING - rather than DEFINITION. - -2005-06-29 Juanma Barranquero - - * variables.texi (Defining Variables): `user-variable-p' returns t - for aliases of user options, nil for alias loops. - -2005-06-28 Richard M. Stallman - - * keymaps.texi (Creating Keymaps): Put make-sparse-keymap before - make-keymap. - -2005-06-27 Luc Teirlinck - - * variables.texi (Setting Variables): Correct and clarify - description of `add-to-ordered-list'. - -2005-06-26 Richard M. Stallman - - * display.texi (Faces): Minor cleanup. - -2005-06-25 Luc Teirlinck - - * display.texi (Faces): `facep' returns t for strings that are - face names. - -2005-06-25 Richard M. Stallman - - * objects.texi (Equality Predicates): Clarify meaning of equal. - - * windows.texi (Selecting Windows): save-selected-window - and with-selected-window save and restore the current buffer. - -2005-06-24 Richard M. Stallman - - * numbers.texi (Float Basics): Explain how to test for NaN, - and printing the sign of NaNs. - -2005-06-24 Eli Zaretskii - - * makefile.w32-in (MAKEINFO): Use --force. - -2005-06-23 Richard M. Stallman - - * display.texi (Face Functions): Correct Texinfo usage. - -2005-06-23 Luc Teirlinck - - * lists.texi (Rings): `ring-elements' now returns the elements of - RING in order. - -2005-06-23 Juanma Barranquero - - * markers.texi (The Mark): Texinfo usage fix. - -2005-06-23 Kim F. Storm - - * searching.texi (Entire Match Data): Remove evaporate option for - match-data. Do not mention evaporate option for set-match-data. - -2005-06-22 Glenn Morris - - * display.texi (Face Functions): Mention face aliases. - -2005-06-21 Richard M. Stallman - - * anti.texi (Antinews): Texinfo usage fix. - -2005-06-21 Karl Berry - - * elisp.texi: Use @copying. - - * elisp.texi: Put @summarycontents and @contents before the Top - node, instead of the end of the file, so that the contents appear - in the right place in the dvi/pdf output. - -2005-06-21 Juri Linkov - - * display.texi (Defining Faces): Add `customized-face'. - -2005-06-20 Kim F. Storm - - * variables.texi (Setting Variables): Any type of element can be - given order in add-to-ordered-list. Compare elements with eq. - - * lists.texi (Rearrangement): Sort predicate may just return non-nil. - -2005-06-20 Karl Berry - - * syntax.texi (Syntax Flags): Make last column very slightly wider - to avoid "generic comment" breaking on two lines and causing an - underfull box. - -2005-06-19 Luc Teirlinck - - * lists.texi (Rings): Various minor clarifications and corrections. - -2005-06-18 Richard M. Stallman - - * functions.texi (Obsolete Functions): Simplify. - - * variables.texi (Variable Aliases): Simplify. - - * anti.texi, backups.texi, compile.texi, customize.texi: - * debugging.texi, display.texi, edebug.texi, errors.texi, frames.texi: - * functions.texi, help.texi, keymaps.texi, modes.texi, nonascii.texi: - * os.texi, processes.texi, searching.texi, strings.texi, text.texi: - * variables.texi: Fix formatting ugliness. - - * elisp.texi: Add links to Rings and Byte Packing. - Update version and copyright years. - - * minibuf.texi: Fix formatting ugliness. - (Completion Commands): Move keymap vars to the end - and vars completing-read binds to the top. - -2005-06-17 Luc Teirlinck - - * processes.texi: Fix typos. - (Bindat Spec): Correct Texinfo error. - (Byte Packing): Fix ungrammatical sentence. - -2005-06-17 Thien-Thi Nguyen - - * lists.texi (Rings): New node. - (Lists): Add it to menu. - - * processes.texi (Byte Packing): New node. - (Processes): Add it to menu. - -2005-06-17 Richard M. Stallman - - * syntax.texi (Parsing Expressions): Fix texinfo usage. - - * help.texi (Documentation Basics): Explain the xref to - Documentation Tips. - - * debugging.texi (Debugger Commands): Minor fix. - -2005-06-16 Luc Teirlinck - - * edebug.texi (Instrumenting): Eliminate duplicate link. - (Specification List): Replace references to "below", referring to - a later node, with one @ref to that node. - - * os.texi (Timers): Timers should save and restore the match data - if they change it. - - * debugging.texi (Debugger Commands): Mention that the Lisp - debugger can not step through primitive functions. - -2005-06-16 Juanma Barranquero - - * functions.texi (Obsolete Functions): Update argument names of - `make-obsolete' and `define-obsolete-function-alias'. - - * variables.texi (Variable Aliases): Update argument names of - `defvaralias', `make-obsolete-variable' and - `define-obsolete-variable-alias'. - -2005-06-15 Kim F. Storm - - * searching.texi (Entire Match Data): Rephrase warnings about - evaporate arg to match-data and set-match-data. - -2005-06-14 Luc Teirlinck - - * elisp.texi (Top): Update detailed menu. - - * edebug.texi (Edebug): Update menu. - (Instrumenting): Update xrefs. - (Edebug Execution Modes): Correct xref. - (Jumping): Clarify description of `h' command. - Eliminate redundant @ref. - (Breaks): New node. - (Breakpoints): Is now a subsubsection. - (Global Break Condition): Mention `C-x X X'. - (Edebug Views): Clarify `v' and `p'. Mention `C-x X w'. - (Trace Buffer): Clarify STRING arg of `edebug-tracing'. - (Edebug Display Update): Correct pxref. - (Edebug and Macros): New node. - (Instrumenting Macro Calls): Is now a subsubsection. - Neither arg of `def-edebug-spec' is evaluated. - (Instrumenting Macro Calls): Mention `edebug-eval-macro-args'. - (Specification Examples): Fix typo. - -2005-06-14 Lute Kamstra - - * debugging.texi (Function Debugging): Primitives can break on - entry too. - -2005-06-14 Kim F. Storm - - * variables.texi (Setting Variables): Add add-to-ordered-list. - -2005-06-13 Stefan Monnier - - * syntax.texi (Parsing Expressions): Document aux functions and vars of - syntax-ppss: syntax-ppss-flush-cache and syntax-begin-function. - -2005-06-13 Lute Kamstra - - * text.texi (Special Properties): Fix cross reference. - -2005-06-11 Luc Teirlinck - - * debugging.texi (Function Debugging): Delete mention of empty - string argument to `cancel-debug-on-entry'. Delete inaccurate - description of the return value of that command. - -2005-06-11 Alan Mackenzie - - * text.texi (Adaptive Fill): Amplify the description of - fill-context-prefix. - -2005-06-10 Luc Teirlinck - - * syntax.texi (Parsing Expressions): Fix Texinfo error. - -2005-06-10 Stefan Monnier - - * syntax.texi (Parsing Expressions): Document syntax-ppss. - -2005-06-10 Luc Teirlinck - - * debugging.texi (Error Debugging): Minor rewording. - (Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry' - is optional. - -2005-06-10 Lute Kamstra - - * elisp.texi: Use EMACSVER to refer to the current version of Emacs. - (Top): Give it a title. Correct version number. Give the - detailed node listing a more prominent header. - * intro.texi: Don't set VERSION here a second time. - Mention Emacs's version too. - * anti.texi (Antinews): Use EMACSVER to refer to the current - version of Emacs. - -2005-06-09 Kim F. Storm - - * searching.texi (Entire Match Data): Explain new `reseat' argument to - match-data and set-match-data. - -2005-06-08 Richard M. Stallman - - * searching.texi (Entire Match Data): Clarify when match-data - returns markers and when integers. - - * display.texi (Defining Faces): Explain that face name should not - end in `-face'. - - * modes.texi (Mode Line Data): Minor cleanup. - (Customizing Keywords): Node split out of Search-based Fontification. - Add example of using font-lock-add-keywords from a hook. - Clarify when MODE should be non-nil, and when nil. - -2005-06-06 Richard M. Stallman - - * modes.texi (Mode Line Data): Explain what happens when the car - of a list is a void symbol. - (Search-based Fontification): Explain MODE arg to - font-lock-add-keywords and warn about calls from major modes. - -2005-06-08 Juri Linkov - - * display.texi (Standard Faces): Add `shadow' face. - -2005-05-29 Luc Teirlinck - - * modes.texi (Major Mode Conventions): A derived mode only needs - to put the call to the parent mode inside `delay-mode-hooks'. - -2005-05-29 Richard M. Stallman - - * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook is - new, and what that implies. Clarify. - - * files.texi (Locating Files): Clean up the text. - - * frames.texi (Window Frame Parameters): Document user-size. - Shorten entry for top by referring to left. - -2005-05-26 Richard M. Stallman - - * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook - is new, and what the implications are. Other clarifications. - -2005-05-24 Richard M. Stallman - - * frames.texi (Dialog Boxes): Minor fixes. - -2005-05-25 Masatake YAMATO - - * display.texi (Standard Faces): Write about `mode-line-highlight'. - -2005-05-24 Luc Teirlinck - - * frames.texi (Dialog Boxes): HEADER argument to `x-popup-dialog' - is optional. - -2005-05-24 Nick Roberts - - * frames.texi (Dialog Boxes): Describe new optional argument. - -2005-05-23 Lute Kamstra - - * modes.texi (Font Lock Basics, Syntactic Font Lock): Recommend - syntax-begin-function over font-lock-beginning-of-syntax-function. - -2005-05-21 Luc Teirlinck - - * minibuf.texi (Reading File Names): Update description of - `read-directory-name'. - - * modes.texi (Derived Modes): Clarify :group keyword. - -2005-05-21 Eli Zaretskii - - * files.texi (Locating Files): New subsection. - Describe locate-file and executable-find. - -2005-05-21 Kevin Ryde - - * frames.texi (Initial Parameters): Update cross reference to - "Emacs Invocation". - -2005-05-19 Luc Teirlinck - - * keymaps.texi (Active Keymaps): Add anchor. - - * modes.texi (Hooks): Delete confusing and unnecessary sentence. - (Major Mode Conventions): Refer to `Auto Major Mode' in more - appropriate place. - (Derived Modes): Small clarifications. - (Minor Mode Conventions, Keymaps and Minor Modes): - Replace references to nodes with references to anchors. - (Mode Line Data): Warn that `(:eval FORM)' should not load any files. - Clarify description of lists whose first element is an integer. - (Mode Line Variables): Add anchor. - (%-Constructs): Clarify description of integer after %. - (Emulating Mode Line): Describe nil value for FACE. - -2005-05-18 Luc Teirlinck - - * modes.texi (Derived Modes): Correct references to non-existing - variable standard-syntax-table. - -2005-05-17 Lute Kamstra - - * modes.texi (Defining Minor Modes): Mention the mode hook. - -2005-05-15 Kim F. Storm - - * processes.texi (Network): Remove open-network-stream-nowait. - (Network Servers): Remove open-network-stream-server. - -2005-05-15 Luc Teirlinck - - * elisp.texi (Top): Update detailed menu. - - * variables.texi: Reorder nodes. - (Variables): Update menu. - (File Local Variables): Do not refer to the `-*-' line as - a "local variables list". Add pxref. - -2005-05-14 Luc Teirlinck - - * elisp.texi (Top): Update detailed menu for node changes. - - * modes.texi (Modes): Update Menu. - (Hooks): Move to beginning of chapter. - Most minor modes run mode hooks too. - `add-hook' can handle void hooks or hooks whose value is a single - function. - (Major Modes): Update Menu. - (Major Mode Basics): New node, split off from `Major Modes'. - (Major Mode Conventions): Correct xref. Explain how to handle - auto-mode-alist if the major mode command has an autoload cookie. - (Auto Major Mode): Major update. Add magic-mode-alist. - (Derived Modes): Major update. - (Mode Line Format): Update Menu. - (Mode Line Basics): New node, split off from `Mode Line Format'. - - * loading.texi (Autoload): Mention `autoload cookie' as synonym - for `magic autoload comment'. Add index entries and anchor. - -2005-05-14 Richard M. Stallman - - * tips.texi (Coding Conventions): Explain how important it is - that just loading certain files not change Emacs behavior. - - * modes.texi (Defining Minor Modes): Define define-global-minor-mode. - -2005-05-12 Lute Kamstra - - * modes.texi (Generic Modes): Update. - (Major Modes): Refer to node "Generic Modes". - - * elisp.texi (Top): Update to the current structure of the manual. - * processes.texi (Processes): Add menu description. - * customize.texi (Customization): Add menu descriptions. - -2005-05-11 Thien-Thi Nguyen - - * processes.texi (Signals to Processes) - (Low-Level Network): Fix typos. - -2005-05-11 Lute Kamstra - - * elisp.texi (Top): Add some nodes from the chapter "Major and - Minor Modes" to the detailed node listing. - -2005-05-10 Richard M. Stallman - - * keymaps.texi (Extended Menu Items): Menu item filter functions - can be called at any time. - -2005-05-08 Luc Teirlinck - - * variables.texi (File Local Variables): `(hack-local-variables t)' - now also checks whether a mode is specified in the local variables - list. - -2005-05-05 Kevin Ryde - - * display.texi (The Echo Area): Correct format function cross - reference. - -2005-05-05 Luc Teirlinck - - * variables.texi (Variable Aliases): Change description of - `define-obsolete-variable-alias'. - - * functions.texi (Functions): Add "Obsolete Functions" to menu. - (Defining Functions): Add xref. - (Obsolete Functions): New node. - (Function Safety): Standardize capitalization of section title. - - * frames.texi (Pop-Up Menus): Complete description of `x-popup-menu'. - (Dialog Boxes): Complete description of `x-popup-dialog'. - -2005-05-04 Richard M. Stallman - - * commands.texi (Interactive Codes): Fix Texinfo usage. - Document U more clearly. - -2005-05-01 Luc Teirlinck - - * variables.texi (Variable Aliases): `make-obsolete-variable' is a - function and not a macro. - - * frames.texi (Pop-Up Menus): Correct and clarify description of - `x-popup-menu'. - (Dialog Boxes): Clarify description of `x-popup-dialog'. - -2005-05-01 Richard M. Stallman - - * edebug.texi (Checking Whether to Stop): Fix previous change. - -2005-05-01 Luc Teirlinck - - * display.texi: Fix typos and Texinfo usage. - - * edebug.texi (Checking Whether to Stop): executing-macro -> - executing-kbd-macro. - -2005-05-01 Richard M. Stallman - - * display.texi (Invisible Text): Correct add-to-invisibility-spec. - -2005-04-30 Richard M. Stallman - - * files.texi (Magic File Names): Document `operations' property. - -2005-04-29 Lute Kamstra - - * modes.texi (Generic Modes): New node. - (Major Modes): Add it to the menu. - (Derived Modes): Add "derived mode" to concept index. - -2005-04-28 Lute Kamstra - - * modes.texi (Defining Minor Modes): Fix previous change. - (Font Lock Mode): Simplify. - (Font Lock Basics): Say that font-lock-defaults is buffer-local - when set and that some parts are optional. Add cross references. - (Search-based Fontification): Say how to specify font-lock-keywords. - Add cross references. Add font-lock-multiline to index. - Move font-lock-keywords-case-fold-search here from node "Other Font - Lock Variables". Document font-lock-add-keywords and - font-lock-remove-keywords. - (Other Font Lock Variables): Move font-lock-keywords-only, - font-lock-syntax-table, font-lock-beginning-of-syntax-function, - and font-lock-syntactic-face-function to node "Syntactic Font - Lock". Move font-lock-keywords-case-fold-search to node - "Search-based Fontification". Document font-lock-inhibit-thing-lock - and font-lock-{,un}fontify-{buffer,region}-function. - (Precalculated Fontification): Remove reference to deleted variable - font-lock-core-only. - (Faces for Font Lock): Add font-lock-comment-delimiter-face. - (Syntactic Font Lock): Add intro. Move font-lock-keywords-only, - font-lock-syntax-table, font-lock-beginning-of-syntax-function, - and font-lock-syntactic-face-function here from node "Other Font - Lock Variables". Move font-lock-syntactic-keywords to "Setting - Syntax Properties". Add cross references. - (Setting Syntax Properties): New node. - Move font-lock-syntactic-keywords here from "Syntactic Font Lock". - * syntax.texi (Syntax Properties): Add cross reference. - * hooks.texi (Standard Hooks): Add Font-Lock hooks. - -2005-04-26 Richard M. Stallman - - * display.texi (Defining Faces): - Document `default' elements of defface spec. - - * modes.texi (Major Mode Conventions): Explain customizing ElDoc mode. - - * variables.texi (Variable Aliases): Clarify text. - -2005-04-25 Chong Yidong - - * windows.texi (Window Hooks): Remove reference to obsolete Lazy Lock. - -2005-04-25 Luc Teirlinck - - * hooks.texi (Standard Hooks): Most minor modes have mode hooks too. - -2005-04-24 Eli Zaretskii - - * syntax.texi (Syntax Table Internals): Elaborate documentation of - syntax-after and syntax-class. - - * files.texi (Changing Files): Fix last change's cross-reference. - (Unique File Names): Don't mention "numbers" in the documentation - of make-temp-file and make-temp-name. - -2005-04-23 Richard M. Stallman - - * files.texi (Changing Files): Document MUSTBENEW arg in copy-file. - -2005-04-22 Nick Roberts - - * windows.texi (Cyclic Window Ordering): Clarify window-list. - -2005-04-22 Nick Roberts - - * variables.texi (Variable Aliases): Describe make-obsolete-variable - and define-obsolete-variable-alias. - -2005-04-22 Kim F. Storm - - * symbols.texi (Symbol Plists): Remove safe-get, as get is now safe. - (Other Plists): Remove safe-plist-get, as plist-get is now safe. - -2005-04-21 Lute Kamstra - - * lists.texi (Association Lists): Document rassq-delete-all. - -2005-04-19 Richard M. Stallman - - * modes.texi (Search-based Fontification): Explain that - facespec is an expression to be evaluated. - -2005-04-19 Kevin Ryde - - * streams.texi (Output Functions): Fix xref. - * strings.texi (String Conversion): Fix xref. - -2005-04-19 Kim F. Storm - - * symbols.texi (Symbol Plists): Add safe-get. - Mention that `get' may signal an error. - -2005-04-18 Nick Roberts - - * customize.texi (Variable Definitions): Replace tooltip-mode - example with save-place. - -2005-04-17 Richard M. Stallman - - * buffers.texi (Indirect Buffers): Clarify. - - * positions.texi (Positions): Clarify converting marker to integer. - - * strings.texi (String Basics): Mention string-match; clarify. - -2005-04-08 Lute Kamstra - - * modes.texi (Search-based Fontification): Fix cross references. - Use consistent terminology. Document anchored highlighting. - -2005-04-05 Lute Kamstra - - * modes.texi (Defining Minor Modes): Document :group keyword - argument and its default value. - -2005-04-03 Lute Kamstra - - * hooks.texi (Standard Hooks): Add some hooks. Add cross - references and/or descriptions. Delete major mode hooks; mention - them as a category instead. Rename or delete obsolete hooks. - -2005-04-02 Richard M. Stallman - - * nonascii.texi (Coding System Basics): Another wording cleanup. - -2005-04-01 Richard M. Stallman - - * nonascii.texi (Coding System Basics): Clarify previous change. - -2005-04-01 Kenichi Handa - - * nonascii.texi (Coding System Basics): Describe about roundtrip - identity of coding systems. - -2005-03-29 Chong Yidong - - * text.texi (Buffer Contents): Add filter-buffer-substring and - buffer-substring-filters. - -2005-03-26 Chong Yidong - - * anti.texi (Antinews): Mention `G' interactive code. - - * tips.texi (Compilation Tips): Mention benchmark.el. - -2005-03-27 Luc Teirlinck - - * modes.texi (Other Font Lock Variables): `font-lock-fontify-block' - is now bound to M-o M-o. - - * keymaps.texi (Prefix Keys): `facemenu-keymap' is now on M-o. - -2005-03-26 Glenn Morris - - * calendar.texi: Delete file (and move contents to emacs-xtra.texi - in the Emacs Manual). - * Makefile.in (srcs): Remove calendar.texi. - * makefile.w32-in (srcs): Remove calendar.texi. - * display.texi (Display): Change name of next node. - * os.texi (System In): Change name of previous node. - * elisp.texi (Top): Remove Calendar references. - * vol1.texi (Top): Remove Calendar references. - * vol2.texi (Top): Remove Calendar references. - -2005-03-25 Richard M. Stallman - - * display.texi (Standard Faces, Fringe Bitmaps, Customizing Bitmaps): - Cleanup previous change. - -2005-03-25 Chong Yidong - - * display.texi (Face Attributes): Faces earlier in an :inherit - list take precedence. - (Scroll Bars): Fix description of vertical-scroll-bars. - Document frame-current-scroll-bars and window-current-scroll-bars. - - * markers.texi (The Mark): Document temporary Transient Mark mode. - - * minibuf.texi (Reading File Names): - Document read-file-name-completion-ignore-case. - - * positions.texi (Screen Lines): Document nil for width argument - to compute-motion. - -2005-03-23 Kim F. Storm - - * display.texi (Standard Faces): Other faces used in the fringe - implicitly inherits from the fringe face. - (Fringe Bitmaps): FACE in right-fringe and left-fringe display - properties implicitly inherits from fringe face. - (Customizing Bitmaps): Likewise for set-fringe-bitmap-face. - -2005-03-20 Chong Yidong - - * display.texi (Invisible Text): State default value of - line-move-ignore-invisible. - (Managing Overlays): Document remove-overlays. - (Standard Faces): Document escape-glyph face. - - * minibuf.texi (Reading File Names): Document read-file-name-function. - - * modes.texi (Other Font Lock Variables): - Document font-lock-lines-before. - - * positions.texi (Skipping Characters): skip-chars-forward allows - character classes. - -2005-03-18 Lute Kamstra - - * edebug.texi (Instrumenting Macro Calls): Fix another typo. - -2005-03-17 Richard M. Stallman - - * text.texi (Undo): Document extensible undo entries. - - * searching.texi (String Search, Regexp Search): Cleanups. - - * nonascii.texi (Character Codes): Minor fix. - - * display.texi (Display Property): Explain the significance - of having text properties that are eq. - (Other Display Specs): Explain string as display spec. - - * commands.texi (Interactive Codes): Document G option. - -2005-03-17 Chong Yidong - - * text.texi (Filling): Add sentence-end-without-period and - sentence-end-without-space. - (Changing Properties): Minor fix. - - * anti.texi: Total rewrite. - -2005-03-15 Lute Kamstra - - * edebug.texi (Instrumenting Macro Calls): Fix typos. - -2005-03-08 Kim F. Storm - - * display.texi (Specified Space): Property :width is support on - non-graphic terminals, :height is not. - -2005-03-07 Richard M. Stallman - - * display.texi (Overlay Arrow, Fringe Bitmaps, Customizing Bitmaps): - Now subnodes of Fringes. - (Overlay Arrow): Document overlay-arrow-variable-list. - (Fringe Size/Pos): New node, broken out of Fringes. - (Display): Explain clearing vs redisplay better. - (Truncation): Clarify use of bitmaps. - (The Echo Area): Clarify the uses of the echo area. - Add max-mini-window-height. - (Progress): Clarify. - (Invisible Text): Explain that main loop moves point out. - (Selective Display): Say "hidden", not "invisible". - (Managing Overlays): Move up. Describe relation to Undo here. - (Overlay Properties): Clarify intro. - (Finding Overlays): Explain return values when nothing found. - (Width): truncate-string-to-width has added arg. - (Displaying Faces): Clarify and update mode line face handling. - (Face Functions): Minor cleanup. - (Conditional Display): Merge into Other Display Specs. - (Pixel Specification, Other Display Specs): Minor cleanups. - (Images, Image Descriptors): Minor cleanups. - (GIF Images): Patents have expired. - (Showing Images): Explain default text for insert-image. - (Manipulating Button Types): Merge into Manipulating Buttons. - (Making Buttons): Explain return values. - (Button Buffer Commands): Add xref. - (Inverse Video): Update mode-line-inverse-video. - (Display Table Format): Clarify. - (Active Display Table): Give defaults for window-display-table. - - * calendar.texi (Calendar Customizing): calendar-holiday-marker - and calendar-today-marker are strings, not chars. - (Holiday Customizing): Minor fix. - - * internals.texi (Writing Emacs Primitives): Update `or' example. - Update limit on # args of subr. - - * edebug.texi (Using Edebug): Arrow is in fringe. - (Instrumenting): Arg to eval-defun works without loading edebug. - (Edebug Execution Modes): Add xref. - - * customize.texi (Common Keywords): Clarify :require. - Mention :version here. - (Variable Definitions, Group Definitions): Not here. - (Variable Definitions): Clarify symbol arg to :initialize and :set fns. - -2005-03-07 Chong Yidong - * nonascii.texi (Text Representations): Clarify position-bytes. - (Character Sets): Add list-charset-chars. - (Scanning Charsets): Add charset-after. - (Encoding and I/O): Minor fix. - -2005-03-06 Richard M. Stallman - - * windows.texi (Vertical Scrolling): Get rid of "Emacs 21". - (Resizing Windows): Likewise. - - * text.texi (Change Hooks): Get rid of "Emacs 21". - - * strings.texi (Formatting Strings): Get rid of "Emacs 21". - - * streams.texi (Output Variables): Get rid of "Emacs 21". - - * searching.texi (Regexp Special, Char Classes): Get rid of "Emacs 21". - - * os.texi (Translating Input): Replace flow-control example - with a less obsolete example that uses `keyboard-translate'. - - * objects.texi (Hash Table Type, Circular Objects): - Get rid of "Emacs 21". - - * modes.texi (Mode Line Format): Get rid of "Emacs 21". - (Mode Line Data, Properties in Mode, Header Lines): Likewise. - - * minibuf.texi (Minibuffer Misc): Get rid of "Emacs 21". - - * lists.texi (List Elements, Building Lists): Get rid of "Emacs 21". - - * keymaps.texi (Menu Separators, Tool Bar): Get rid of "Emacs 21". - (Menu Bar): Fix when menu-bar-update-hook is called. - - * hash.texi (Hash Tables): Get rid of "Emacs 21". - - * frames.texi (Text Terminal Colors): Get rid of "Emacs 21", - and make it read better. - - * files.texi (Writing to Files): Get rid of "Emacs 21". - (Unique File Names): Likewise. - - * elisp.texi: Update Emacs version to 22. - - * display.texi (Forcing Redisplay): Get rid of "Emacs 21". - (Overlay Properties, Face Attributes): Likewise. - (Managing Overlays): Fix punctuation. - (Attribute Functions): Clarify set-face-font; get rid of - info about old Emacs versions. - (Auto Faces, Font Lookup, Display Property, Images): - Get rid of "Emacs 21". - - * calendar.texi (Calendar Customizing): Get rid of "Emacs 21". - -2005-03-05 Richard M. Stallman - - * debugging.texi (Error Debugging): Remove stack-trace-on-error. - -2005-03-04 Lute Kamstra - - * debugging.texi (Error Debugging): Document stack-trace-on-error. - -2005-03-03 Lute Kamstra - - * edebug.texi (Instrumenting Macro Calls): Fix typo. - -2005-03-01 Lute Kamstra - - * debugging.texi (Debugger Commands): Update `j'. - -2005-02-28 Lute Kamstra - - * debugging.texi (Debugging): Fix typo. - (Error Debugging): Document eval-expression-debug-on-error. - (Function Debugging): Update example. - (Using Debugger): Mention starred stack frames. - (Debugger Commands): Document `j' and `l'. - (Invoking the Debugger): `d' and `j' exit recursive edit too. - Update the messages that the debugger displays. - (Internals of Debugger): Add cross reference. Update example. - (Excess Open): Minor improvement. - (Excess Close): Minor improvement. - -2005-02-26 Richard M. Stallman - - * tips.texi (Coding Conventions): Clarify. - Put all the major mode key reservations together. - Mention the Mouse-1 => Mouse-2 conventions. - - * syntax.texi (Syntax Class Table): Clarify. - (Syntax Table Functions): syntax-after moved from here. - (Syntax Table Internals): syntax-after moved to here. - (Parsing Expressions): Update info on number of values - and what's meaningful in the STATE argument. - (Categories): Fix typo. - - * sequences.texi (Arrays): Cleanup. - (Char-Tables): Clarify. - - * processes.texi (Deleting Processes): Cleanups, add xref. - (Subprocess Creation): Explain nil in exec-path. Cleanup. - (Process Information): set-process-coding-system, some args optional. - (Input to Processes): Explain various types for PROCESS args. - Rename them from PROCESS-NAME to PROCESS. - (Signals to Processes): Likewise. - (Decoding Output): Cleanup. - (Query Before Exit): Clarify. - - * os.texi (Startup Summary): Correct the options; add missing ones. - (Terminal Output, Batch Mode): Clarify. - (Flow Control): Node deleted. - - * markers.texi (The Mark): Clarify. - - * macros.texi (Expansion): Cleanup. - (Indenting Macros): indent-spec allows ints, not floats. - - * keymaps.texi (Keymaps): Clarify. - (Format of Keymaps): Update lisp-mode-map example. - (Active Keymaps, Key Lookup): Clarify. - (Changing Key Bindings): Add xref to `kbd'. - (Key Binding Commands, Simple Menu Items): Clarify. - (Mouse Menus, Menu Bar): Clarify. - (Menu Example): Replace print example with menu-bar-replace-menu. - - * help.texi (Documentation Basics): Add function-documentation prop. - - * elisp.texi (Top): Don't refer to Flow Control node. - - * commands.texi (Command Overview): Improve xrefs. - (Adjusting Point): Adjusting point applies to intangible and invis. - (Key Sequence Input): Doc extra read-key-sequence args. - Likewise for read-key-sequence-vector. - - * backups.texi (Rename or Copy): Minor fix. - (Numbered Backups): For version-control, say the default. - (Auto-Saving): make-auto-save-file-name example is simplified. - - * advice.texi (Advising Functions): Don't imply one part of Emacs - should advise another part. Markup changes. - (Defining Advice): Move transitional para. - (Activation of Advice): Cleanup. - Explain if COMPILE is nil or negative. - - * abbrevs.texi (Abbrev Expansion): Clarify, fix typo. - -2005-02-24 Lute Kamstra - - * modes.texi (Defining Minor Modes): Explain that INIT-VALUE, - LIGHTER, and KEYMAP can be omitted when KEYWORD-ARGS are used. - -2005-02-23 Lute Kamstra - - * modes.texi (Defining Minor Modes): define-minor-mode can be used - to define global minor modes as well. - - * display.texi (Managing Overlays): overlay-buffer returns nil for - deleted overlays. - -2005-02-22 Kim F. Storm - - * minibuf.texi (Basic Completion): Allow symbols in addition to - strings in try-completion and all-completions. - -2005-02-14 Lute Kamstra - - * elisp.texi (Top): Remove reference to deleted node. - - * lists.texi (Lists): Remove reference to deleted node. - (Cons Cells): Fix typo. - - * loading.texi (Where Defined): Fix typo. - -2005-02-14 Richard M. Stallman - - * variables.texi (Creating Buffer-Local): change-major-mode-hook - is useful for discarding some minor modes. - - * symbols.texi (Symbol Components): Reorder examples. - - * streams.texi (Input Functions): State standard-input default. - (Output Variables): State standard-output default. - - * objects.texi (Printed Representation): Clarify read syntax vs print. - (Floating Point Type): Explain meaning better. - (Symbol Type): Explain uniqueness better. - (Cons Cell Type): Explain empty list sooner. CAR and CDR later. - List examples sooner. - (Box Diagrams): New subnode broken out. - Some examples moved from old Lists as Boxes node. - (Dotted Pair Notation): Clarify intro. - (Array Type): Clarify. - (Type Predicates): Add hash-table-p. - - * numbers.texi (Integer Basics): Clarify radix explanation. - (Predicates on Numbers): Minor clarification. - (Comparison of Numbers): Minor clarification. Clarify eql. - Typos in min, max. - (Math Functions): Clarify overflow in expt. - - * minibuf.texi (Text from Minibuffer): Minor clarification. - Mention arrow keys. - - * loading.texi (Autoload): defun's doc string overrides autoload's - doc string. - (Repeated Loading): Modernize "add to list" examples. - (Where Defined): Finish updating table of load-history elts. - - * lists.texi (List-related Predicates): Minor wording improvement. - (Lists as Boxes): Node deleted. - (Building Lists): Explain trivial cases of number-sequence. - - * hash.texi (Hash Tables): Add desc to menu items. - (Creating Hash): Explain "full" means "make larger". - (Hash Access): Any object can be a key. - State value of maphash. - - * functions.texi (What Is a Function): Wording cleanup. - (Function Documentation): Minor cleanup. - Explain purpose of calling convention at end of doc string. - (Function Names): Wording cleanup. - (Calling Functions): Wording cleanup. - Explain better how funcall calls the function. - (Function Cells): Delete example of saving and redefining function. - - * control.texi (Combining Conditions): Wording cleanup. - (Iteration): dolist and dotimes bind VAR locally. - (Cleanups): Xref to Atomic Changes. - - * compile.texi (Byte Compilation): Delete 19.29 info. - (Compilation Functions): Macros' difficulties don't affect defsubst. - (Docs and Compilation): Delete 19.29 info. - -2005-02-10 Richard M. Stallman - - * objects.texi (Symbol Type): Minor correction. - -2005-02-06 Lute Kamstra - - * modes.texi (Example Major Modes): Fix typos. - -2005-02-06 Richard M. Stallman - - * text.texi (Margins): fill-nobreak-predicate can be one function. - - * strings.texi (Modifying Strings): clear-string can make unibyte. - (Formatting Strings): format gives error if values missing. - - * positions.texi (Character Motion): Mention default arg - for forward-char. backward-char refers to forward-char. - (Word Motion): Mention default arg for forward-word. - (Buffer End Motion): Mention default arg for beginning-of-buffer. - Simplify end-of-buffer. - (Text Lines): Mention default arg for forward-line. - (List Motion): Mention default arg for beginning/end-of-defun. - (Skipping Characters): Minor fixes in explaining character-set. - - * modes.texi (Major Mode Conventions): Mention "system abbrevs". - Mode inheritance applies only when default-major-mode is nil. - Clarifications. - (Example Major Modes): Update Text mode and Lisp mode examples. - (Minor Mode Conventions): Mention define-minor-mode at top. - (Defining Minor Modes): In Hungry example, don't define C-M-DEL. - (Mode Line Format): Update mode line face display info. - (Properties in Mode): Mention effect of risky vars. - (Imenu): Define imenu-add-to-menubar. - (Font Lock Mode): Add descriptions to menu lines. - (Faces for Font Lock): Add font-lock-doc-face. - -2005-02-05 Lute Kamstra - - * text.texi (Maintaining Undo): Remove obsolete function. - -2005-02-05 Eli Zaretskii - - * frames.texi (Color Names): Add pointer to the X docs about RGB - color specifications. Improve indexing. - (Text Terminal Colors): Replace the description of RGB values by - an xref to "Color Names". - -2005-02-03 Richard M. Stallman - - * windows.texi (Basic Windows): Add cursor-in-non-selected-windows. - Clarify. - (Selecting Windows): Clarify save-selected-window. - (Cyclic Window Ordering): Clarify walk-windows. - (Window Point): Clarify. - (Window Start): Add comment to example. - (Resizing Windows): Add `interactive' specs in examples. - Document fit-window-to-buffer. - - * text.texi (User-Level Deletion): just-one-space takes numeric arg. - (Undo, Maintaining Undo): Clarify last change. - (Sorting): In sort-numeric-fields, explain about octal and hex. - Mention sort-numeric-base. - (Format Properties): Add xref for hard newlines. - - * frames.texi (Window Frame Parameters): Explain pixel=char on tty. - (Pop-Up Menus): Fix typo. - (Color Names): Explain all types of color names. - Explain color-values on B&W terminal. - (Text Terminal Colors): Explain "rgb values" are lists. Fix arg names. - - * files.texi (File Locks): Not supported on MS systems. - (Testing Accessibility): Clarify. - - * edebug.texi (Printing in Edebug): Fix edebug-print-circle. - (Coverage Testing): Fix typo. - - * commands.texi (Misc Events): Remove stray space. - - * buffers.texi (Buffer Names): Clarify generate-new-buffer-name. - (Modification Time): Clarify when visited-file-modtime returns 0. - (The Buffer List): Clarify bury-buffer. - (Killing Buffers): Clarify. - (Indirect Buffers): Add clone-indirect-buffer. - -2005-02-02 Matt Hodges - - * edebug.texi (Printing in Edebug): Fix default value of - edebug-print-circle. - (Coverage Testing): Fix displayed frequency count data. - -2005-02-02 Luc Teirlinck - - * text.texi (Maintaining Undo): Add `undo-outer-limit'. - -2005-02-02 Kim F. Storm - - * text.texi (Undo) : Describe `apply' elements. - -2005-01-29 Eli Zaretskii - - * commands.texi (Misc Events): Describe the help-echo event. - - * text.texi (Special Properties) : Use `pos' - consistently in description of the help-echo property. - Use @code{nil} instead of @var{nil}. - - * display.texi (Overlay Properties): Fix the index entry for - help-echo overlay property. - - * customize.texi (Type Keywords): Uncomment the xref to the - help-echo property documentation. - -2005-01-23 Kim F. Storm - - * windows.texi (Window Start): Fix `pos-visible-in-window-p' - return value. Third element FULLY replaced by PARTIAL which - specifies number of invisible pixels if row is only partially visible. - (Textual Scrolling): Mention auto-window-vscroll. - (Vertical Scrolling): New defvar auto-window-vscroll. - -2005-01-16 Luc Teirlinck - - * keymaps.texi (Changing Key Bindings): `suppress-keymap' now uses - command remapping. - -2005-01-15 Richard M. Stallman - - * display.texi (Defining Images): Mention DATA-P arg of create-image. - -2005-01-14 Kim F. Storm - - * commands.texi (Accessing Events): Add WHOLE arg to posn-at-x-y. - - * text.texi (Links and Mouse-1): Fix string and vector item. - -2005-01-13 Richard M. Stallman - - * keymaps.texi (Active Keymaps): Rewrite the text, and update the - descriptions of overriding-local-map and overriding-terminal-local-map. - - * text.texi (Links and Mouse-1): Clarify text. - -2005-01-13 Kim F. Storm - - * modes.texi (Emulating Mode Line): Update format-mode-line entry. - -2005-01-13 Francis Litterio (tiny change) - - * keymaps.texi (Active Keymaps): Fix overriding-local-map description. - -2005-01-12 Kim F. Storm - - * text.texi (Links and Mouse-1): Rename section from Enabling - Mouse-1 to Following Links. Change xrefs. - Add examples for define-button-type and define-widget. - - * display.texi (Button Properties, Button Buffer Commands): - Clarify mouse-1 and follow-link functionality. - -2005-01-12 Richard M. Stallman - - * text.texi (Enabling Mouse-1 to Follow Links): Redo prev. change. - - * display.texi (Beeping): Fix Texinfo usage. - - * modes.texi (Emulating Mode Line): Doc FACE arg in format-header-line. - -2005-01-11 Kim F. Storm - - * display.texi (Button Properties, Button Buffer Commands): - Mention mouse-1 binding. Add follow-link keyword. - - * text.texi (Text Properties): Add "Enable Mouse-1" to submenu. - (Enabling Mouse-1 to Follow Links): New subsection. - -2005-01-06 Richard M. Stallman - - * text.texi (Special Properties): Minor change. - - * os.texi (Timers): Clarify previous change. - - * modes.texi (Emulating Mode Line): format-mode-line requires 1 arg. - -2005-01-01 Luc Teirlinck - - * display.texi (Face Attributes): Correct xref to renamed node. - -2005-01-01 Richard M. Stallman - - * display.texi (Face Attributes): Describe hex color specs. - -2004-12-31 Richard M. Stallman - - * os.texi (Timers): Update previous change. - -2004-12-30 Kim F. Storm - - * display.texi (Line Height): Total line-height is now specified - in line-height property of form (HEIGHT TOTAL). Swap (FACE . RATIO) - in cons cells. (nil . RATIO) is relative to actual line height. - Use line-height `t' instead of `0' to get minimum height. - -2004-12-29 Richard M. Stallman - - * os.texi (Timers): Discuss timers vs editing the buffer and undo. - -2004-12-28 Richard M. Stallman - - * commands.texi (Quitting): Clarify value of with-local-quit. - - * elisp.texi (Top): Fix previous change. - - * loading.texi (Loading): Fix previous change. - -2004-12-27 Richard M. Stallman - - * Makefile.in (MAKEINFO): Specify --force. - - * buffers.texi (Killing Buffers): Add buffer-save-without-query. - - * modes.texi (Emulating Mode Line): Document format's BUFFER arg. - - * display.texi (Line Height): Further clarify. - - * elisp.texi (Top): Update Loading submenu. - - * loading.texi (Where Defined): New node. - (Unloading): load-history moved to Where Defined. - -2004-12-21 Richard M. Stallman - - * commands.texi (Event Input Misc): Add while-no-input. - -2004-12-11 Richard M. Stallman - - * display.texi (Line Height): Rewrite text for clarity. - -2004-12-11 Kim F. Storm - - * display.texi (Display): Add node "Line Height" to menu. - (Line Height): New node. Move full description of line-spacing - and line-height text properties here from text.texi. - (Scroll Bars): Add vertical-scroll-bar variable. - - * frames.texi (Window Frame Parameters): Remove line-height defvar. - - * locals.texi (Standard Buffer-Local Variables): Fix xref for - line-spacing and vertical-scroll-bar. - - * text.texi (Special Properties): Just mention line-spacing and - line-height here, add xref to new "Line Height" node. - -2004-12-09 Thien-Thi Nguyen - - * frames.texi (Window Frame Parameters): New @defvar for `line-spacing'. - - * locals.texi (Standard Buffer-Local Variables): - Add @xref for `line-spacing'. - -2004-12-05 Richard M. Stallman - - * Makefile.in (maintainer-clean): Remove the info files - in $(infodir) where they are created. - -2004-12-03 Richard M. Stallman - - * windows.texi (Selecting Windows): get-lru-window and - get-largest-window don't consider dedicated windows. - - * text.texi (Undo): Document undo-in-progress. - -2004-11-26 Richard M. Stallman - - * locals.texi (Standard Buffer-Local Variables): Undo prev change. - Remove a few vars that are not always buffer-local. - -2004-11-24 Luc Teirlinck - - * locals.texi (Standard Buffer-Local Variables): Comment out - xref's to non-existent node `Yet to be written'. - -2004-11-24 Richard M. Stallman - - * processes.texi (Synchronous Processes): Grammar fix. - - * numbers.texi (Comparison of Numbers): Add eql. - - * locals.texi (Standard Buffer-Local Variables): Add many vars. - - * intro.texi (Printing Notation): Fix previous change. - - * display.texi (Customizing Bitmaps): Move indicate-buffer-boundaries - and default-indicate-buffer-boundaries from here. - (Usual Display): To here. - (Scroll Bars): Add scroll-bar-mode and scroll-bar-width. - (Usual Display): Move tab-width up. - - * customize.texi (Variable Definitions): - Replace show-paren-mode example with tooltip-mode. - (Simple Types, Composite Types, Defining New Types): - Minor cleanups. - -2004-11-21 Jesper Harder - - * processes.texi (Synchronous Processes, Output from Processes): - Markup fix. - -2004-11-20 Richard M. Stallman - - * positions.texi (Skipping Characters): skip-chars-forward - now handles char classes. - - * intro.texi (Printing Notation): Avoid confusion of `print' - when explaining @print. - - * macros.texi (Argument Evaluation): Fix 1st `for' expansion example. - - * display.texi (Display Table Format): Minor fix. - - * streams.texi (Output Functions): Fix print example. - - * Makefile.in (elisp): New target. - (dist): Depend on $(infodir)/elisp, not elisp. - Copy the info files from $(infodir). - - * minibuf.texi (Text from Minibuffer): Document KEEP-ALL arg in - read-from-minibuffer. - - * searching.texi (Regexp Search): Rename that to search-spaces-regexp. - -2004-11-19 Richard M. Stallman - - * searching.texi (Regexp Search): Add search-whitespace-regexp. - -2004-11-19 CHENG Gao (tiny change) - - * tips.texi (Coding Conventions): Fix typo. - -2004-11-16 Richard M. Stallman - - * tips.texi (Coding Conventions): Separate defvar and require - methods to avoid warnings. Use require only when there are many - functions and variables from that package. - - * minibuf.texi (Minibuffer Completion): When ignoring case, - predicate must not be case-sensitive. - - * debugging.texi (Function Debugging, Explicit Debug): Clarified. - (Test Coverage): Don't talk about "splotches". Clarified. - -2004-11-16 Thien-Thi Nguyen - - * frames.texi (Window Frame Parameters): Fix typo. - -2004-11-15 Kim F. Storm - - * symbols.texi (Other Plists): Note that plist-get may signal error. - Add safe-plist-get. - -2004-11-15 Thien-Thi Nguyen - - * modes.texi (Font Lock Basics): Fix typo. - -2004-11-08 Richard M. Stallman - - * syntax.texi (Syntax Table Functions): Add syntax-after. - -2004-11-06 Lars Brinkhoff - - * os.texi (Processor Run Time): New section documenting - get-internal-run-time. - -2004-11-06 Eli Zaretskii - - * Makefile.in (install, maintainer-clean): Don't use "elisp-*" as - it nukes elisp-cover.texi. - (dist): Change elisp-[0-9] to elisp-[1-9], as there could be no - elisp-0 etc. - -2004-11-05 Luc Teirlinck - - * commands.texi (Keyboard Macros): Document `append' return value - of `defining-kbd-macro'. - -2004-11-01 Richard M. Stallman - - * commands.texi (Interactive Call): Add called-interactively-p. - -2004-10-29 Simon Josefsson - - * minibuf.texi (Reading a Password): Revert. - -2004-10-28 Richard M. Stallman - - * frames.texi (Display Feature Testing): Explain about "vendor". - -2004-10-27 Richard M. Stallman - - * commands.texi (Interactive Codes): `N' uses numeric prefix, - not raw. Clarify `n'. - (Interactive Call): Rewrite interactive-p, focusing on when - and how to use it. - (Misc Events): Clarify previous change. - - * advice.texi (Simple Advice): Clarify what job the example does. - (Around-Advice): Clarify ad-do-it. - (Activation of Advice): An option of ad-default-compilation-action - is `never', not `nil'. - -2004-10-26 Kim F. Storm - - * commands.texi (Interactive Codes): Add U code letter. - -2004-10-25 Simon Josefsson - - * minibuf.texi (Reading a Password): Add. - -2004-10-24 Jason Rumney - - * commands.texi (Misc Events): Remove mouse-wheel. Add wheel-up - and wheel-down. - -2004-10-24 Kai Grossjohann - - * processes.texi (Synchronous Processes): Document process-file. - -2004-10-22 Kenichi Handa - - * text.texi (translate-region): Document that it accepts also a - char-table. - -2004-10-22 David Ponce - - * windows.texi (Resizing Windows): Document the `preserve-before' - argument of the functions `enlarge-window' and `shrink-window'. - -2004-10-19 Jason Rumney - - * makefile.w32-in (elisp): Change order of arguments to makeinfo. - -2004-10-09 Luc Teirlinck - - * text.texi (Filling): Add anchor for definition of - `sentence-end-double-space'. - - * searching.texi (Regexp Example): Update description of how - Emacs currently recognizes the end of a sentence. - (Standard Regexps): Update definition of the variable - `sentence-end'. Add definition of the function `sentence-end'. - -2004-10-08 Paul Pogonyshev - - * display.texi (Progress): New node. - -2004-10-05 Kim F. Storm - - * display.texi (Fringe Bitmaps): Update fringe-bitmaps-at-pos. - -2004-09-29 Kim F. Storm - - * display.texi (Fringe Bitmaps): Use symbols rather than numbers - to identify bitmaps. Remove -fringe-bitmap suffix for standard - fringe bitmap symbols, as they now have their own namespace. - (Customizing Bitmaps) : Clarify bit ordering - vs. pixels. Signal error if no free bitmap slots. - (Pixel Specification): Change IMAGE to @var{image}. - -2004-09-28 Richard M. Stallman - - * text.texi (Special Properties): Clarify line-spacing and line-height. - - * searching.texi (Regexp Search): Add looking-back. - -2004-09-25 Luc Teirlinck - - * display.texi: Correct typos. - (Image Descriptors): Correct xref's. - -2004-09-25 Richard M. Stallman - - * text.texi (Special Properties): Cleanups in `cursor'. - Rewrites in `line-height' and `line-spacing'; exchange them. - - * display.texi (Fringes): Rewrite previous change. - (Fringe Bitmaps): Merge text from Display Fringe Bitmaps. Rewrite. - (Display Fringe Bitmaps): Node deleted, text moved. - (Customizing Bitmaps): Split off from Fringe Bitmaps. Rewrite. - (Scroll Bars): Clarify set-window-scroll-bars. - (Pointer Shape): Rewrite. - (Specified Space): Clarify :align-to, etc. - (Pixel Specification): Use @var. Clarify new text. - (Other Display Specs): Clarify `slice'. - (Image Descriptors): Cleanups. - (Showing Images): Cleanups. - -2004-09-24 Luc Teirlinck - - * hooks.texi (Standard Hooks): Add `after-change-major-mode-hook'. - - * modes.texi: Various minor changes in addition to: - (Major Mode Conventions): Final call to `run-mode-hooks' should - not be inside the `delay-mode-hooks' form. - (Mode Hooks): New node. - (Hooks): Delete obsolete example. - Move definitions of `run-mode-hooks' and `delay-mode-hooks' to new - node "Mode Hooks". - -2004-09-22 Luc Teirlinck - - * display.texi: Correct various typos. - (Display): Rename node "Pointer Shapes" to "Pointer - Shape". (There is already a node called "Pointer Shapes" in - frames.texi.) - (Images): Remove non-existent node "Image Slices" from menu. - -2004-09-23 Kim F. Storm - - * text.texi (Special Properties): Add `cursor', `pointer', - `line-height', and `line-spacing' properties. - - * display.texi (Display): Add 'Fringe Bitmaps' and 'Pointer - Shapes' to menu. - (Standard Faces): Doc fix for fringe face. - (Fringes): Add `overflow-newline-into-fringe' and - 'indicate-buffer-boundaries'. - (Fringe Bitmaps, Pointer Shapes): New nodes. - (Display Property): Add 'Pixel Specification' and 'Display Fringe - Bitmaps' to menu. - (Specified Space): Describe pixel width and height. - (Pixel Specification): New node. - (Other Display Specs): Add `slice' property. - (Display Fringe Bitmaps): New node. - (Images): Add 'Image Slices' to menu. - (Image Descriptors): Add `:pointer' and `:map' properties. - (Showing Images): Add slice arg to `insert-image'. - Add 'insert-sliced-image'. - -2004-09-20 Richard M. Stallman - - * commands.texi (Key Sequence Input): - Clarify downcasing in read-key-sequence. - -2004-09-08 Juri Linkov - - * minibuf.texi (Minibuffer History): Add `history-delete-duplicates'. - -2004-09-07 Luc Teirlinck - - * locals.texi (Standard Buffer-Local Variables): - Add `buffer-auto-save-file-format'. - * internals.texi (Buffer Internals): Describe new - auto_save_file_format field of the buffer structure. - * files.texi (Format Conversion): `auto-save-file-format' has been - renamed `buffer-auto-save-file-format'. - -2004-08-27 Luc Teirlinck - - * abbrevs.texi (Abbrev Expansion): `abbrev-start-location' can be - an integer or a marker. - (Abbrev Expansion): Replace example for `pre-abbrev-expand-hook'. - -2004-08-22 Richard M. Stallman - - * modes.texi (Major Mode Conventions): Discuss rebinding of - standard key bindings. - -2004-08-18 Kim F. Storm - - * processes.texi (Accepting Output): Add `just-this-one' arg to - `accept-process-output'. - (Output from Processes): New var `process-adaptive-read-buffering'. - -2004-08-10 Luc Teirlinck - - * keymaps.texi: Various changes in addition to: - (Keymap Terminology): `kbd' uses same syntax as Edit Macro mode. - Give more varied examples for `kbd'. - (Creating Keymaps): Char tables have slots for all characters - without modifiers. - (Active Keymaps): `overriding-local-map' and - `overriding-terminal-local-map' also override text property and - overlay keymaps. - (Functions for Key Lookup): Mention OLP arg to `current-active-maps'. - (Scanning Keymaps): `accessible-keymaps' uses `[]' instead of `""' - to denote a prefix of no events. - `map-keymap' includes parent's bindings _recursively_. - Clarify and correct description of `where-is-internal'. - Mention BUFFER-OR-NAME arg to `describe-bindings'. - (Menu Example): For menus intended for use with the keyboard, the - menu items should be bound to characters or real function keys. - -2004-08-08 Luc Teirlinck - - * objects.texi (Character Type): Reposition `@anchor' to prevent - double space inside sentence in Info. - - * hooks.texi (Standard Hooks): `disabled-command-hook' has been - renamed to `disabled-command-function'. - * commands.texi (Key Sequence Input): Remove unnecessary anchor. - (Command Loop Info): Replace reference to it. - (Disabling Commands): `disabled-command-hook' has been renamed to - `disabled-command-function'. - -2004-08-07 Luc Teirlinck - - * os.texi (Translating Input): Only non-prefix bindings in - `key-translation-map' override actual key bindings. Warn about - possible indirect effect of actual key bindings on non-prefix - bindings in `key-translation-map'. - -2004-08-06 Luc Teirlinck - - * minibuf.texi (High-Level Completion): Add anchor for definition - of `read-variable'. - - * commands.texi: Various changes in addition to: - (Using Interactive): Clarify description of `interactive-form'. - (Interactive Call): Mention default for KEYS argument to - `call-interactively'. - (Command Loop Info): Clarify description of `this-command-keys'. - Mention KEEP-RECORD argument to `clear-this-command-keys'. - Value of `last-event-frame' can be `macro'. - (Repeat Events): `double-click-fuzz' is also used to distinguish - clicks and drags. - (Classifying Events): Clarify descriptions of `event-modifiers' - `event-basic-type' and `event-convert-list'. - (Accessing Events): `posn-timestamp' takes POSITION argument. - (Quoted Character Input): Clarify description of - `read-quoted-char' and fix example. - (Quitting): Add `with-local-quit'. - (Disabling Commands): Correct and clarify descriptions of - `enable-command' and `disable-command'. - Mention what happens if `disabled-command-hook' is nil. - (Keyboard Macros): Mention LOOPFUNC arg to `execute-kbd-macro'. - Describe `executing-kbd-macro' instead of obsolete `executing-macro'. - -2004-07-24 Luc Teirlinck - - * frames.texi: Various changes in addition to: - (Creating Frames): Expand and clarify description of `make-frame'. - (Window Frame Parameters): Either none or both of the `icon-left' - and `icon-top' parameters must be specified. Put descriptions of - `menu-bar-lines' and `toolbar-lines' closer together and change - them accordingly. - (Frame Titles): `multiple-frames' is not guaranteed to be accurate - except while processing `frame-title-format' or `icon-title-format'. - (Deleting Frames): Correct description of `delete-frame'. - Non-nil return values of `frame-live-p' are like those of `framep'. - (Frames and Windows): Mention return value of - `set-frame-selected-window'. - (Visibility of Frames): Mention `force' argument to - `make-frame-invisible'. `frame-visible-p' returns t for all - frames on text-only terminals. - (Frame Configurations): Restoring a frame configuration does not - restore deleted frames. - (Window System Selections): `x-set-selection' returns DATA. - (Resources): Add example. - (Display Feature Testing): Clarify descriptions of - `display-pixel-height', `display-pixel-width', `x-server-version' - and `x-server-vendor'. - - * windows.texi (Choosing Window): Add anchor. - * minibuf.texi (Minibuffer Misc): Add anchor. - -2004-07-23 John Paul Wallington - - * macros.texi (Defining Macros): Declaration keyword for setting - Edebug spec is `debug' not `edebug'. - -2004-07-19 Luc Teirlinck - - * windows.texi: Various small changes in addition to: - (Window Point): Mention return value of `set-window-point'. - (Window Start): `pos-visible-in-window-p' disregards horizontal - scrolling. Explain return value if PARTIALLY is non-nil. - (Vertical Scrolling): Mention PIXELS-P argument to `window-vscroll' - and `set-window-vscroll'. - (Size of Window): The argument WINDOW to `window-inside-edges', - `window-pixel-edges' and `window-inside-pixel-edges' is optional. - (Resizing Windows): Explain return value of - `shrink-window-if-larger-than-buffer'. - `window-size-fixed' automatically becomes buffer local when set. - (Window Configurations): Explain return value of - `set-window-configuration'. - - * minibuf.texi (Minibuffer Misc): Add anchor for - `minibuffer-scroll-window'. - - * positions.texi (Text Lines): Add anchor for `count-lines'. - -2004-07-17 Richard M. Stallman - - * display.texi (Overlay Properties): Adding `evaporate' prop - deletes empty overlay immediately. - - * abbrevs.texi (Abbrev Expansion): Clarify pre-abbrev-expand-hook, - fix example. - -2004-07-16 Jim Blandy - - * searching.texi (Regexp Backslash): Document new \_< and \_> - operators. - -2004-07-16 Juanma Barranquero - - * display.texi (Images): Fix Texinfo usage. - -2004-07-14 Luc Teirlinck - - * buffers.texi (Modification Time): `visited-file-modtime' now - returns a list of two integers, instead of a cons. - -2004-07-13 Luc Teirlinck - - * windows.texi: Various changes in addition to: - (Splitting Windows): Add `split-window-keep-point'. - -2004-07-09 Richard M. Stallman - - * frames.texi (Input Focus): Minor fix. - -2004-07-07 Luc Teirlinck - - * frames.texi (Input Focus): Clarify descriptions of - `select-frame-set-input-focus' and `select-frame'. - -2004-07-06 Luc Teirlinck - - * os.texi: Various small changes in addition to: - (Killing Emacs): Expand and clarify description of - `kill-emacs-query-functions' and `kill-emacs-hook'. - (System Environment): Expand and clarify description of `getenv' - and `setenv'. - (Timers): Clarify description of `run-at-time'. - (Translating Input): Correct description of - `extra-keyboard-modifiers'. - (Flow Control): Correct description of `enable-flow-control'. - -2004-07-06 Thien-Thi Nguyen - - * os.texi: Update copyright. - (Session Management): Grammar fix. - Clarify which Emacs does the restarting. - Use @samp for *scratch* buffer. - -2004-07-04 Alan Mackenzie - - * frames.texi (Input Focus): Add documentation for - `select-frame-set-input-focus'. Replace refs to non-existent - `switch-frame' with `select-frame'. Minor corrections and tidying - up of text-only terminal stuff. - -2004-07-02 Richard M. Stallman - - * files.texi (Saving Buffers): Cleanup write-contents-function. - (Magic File Names): Cleanup file-remote-p. - -2004-07-02 Kai Großjohann - - * files.texi (Magic File Names): `file-remote-p' returns an - identifier of the remote system, not just t. - -2004-07-02 David Kastrup - - * searching.texi (Entire Match Data): Add explanation about new - match-data behavior when @var{integers} is non-nil. - -2004-06-24 Richard M. Stallman - - * commands.texi (Misc Events): Describe usr1-signal, usr2-signal event. - - * customize.texi (Variable Definitions): Note about doc strings - and :set. - - * keymaps.texi (Keymap Terminology): Document `kbd'. - (Changing Key Bindings, Key Binding Commands): Use kbd in examples. - - * display.texi (Invisible Text): Setting buffer-invisibility-spec - makes it buffer-local. - - * files.texi (Saving Buffers): Correct previous change. - - * commands.texi (Accessing Events): - Clarify posn-col-row and posn-actual-col-row. - -2004-06-24 David Ponce - - * commands.texi (Accessing Events): New functions - posn-at-point and posn-at-x-y. Add example to posn-x-y. - -2004-06-23 Luc Teirlinck - - * lists.texi, files.texi, processes.texi, macros.texi, hash.texi: - * frames.texi, buffers.texi, backups.texi, variables.texi: - * loading.texi, eval.texi, functions.texi, control.texi: - * symbols.texi, minibuf.texi: Reposition @anchor's. - - * help.texi: Various small changes in addition to the following. - (Describing Characters): Describe PREFIX argument to - `key-description'. Correct and clarify definition of - `text-char-description'. Describe NEED-VECTOR argument to - `read-kbd-macro'. - (Help Functions): Clarify definition of `apropos'. - -2004-06-23 Lars Hansen - - * files.texi (Saving Buffers): Correct description of - `write-contents-functions'. - -2004-06-21 Juanma Barranquero - - * display.texi (Images): Remove redundant @vindex directives. - Rewrite `image-library-alist' doc in active voice. - -2004-06-14 Juanma Barranquero - - * display.texi (Images): Document new delayed library loading, - variable `image-library-alist' and (existing but undocumented) - function `image-type-available-p'. - -2004-06-05 Richard M. Stallman - - * minibuf.texi (Minibuffer Completion): For INITIAL arg, - refer the user to the Initial Input node. - (Text from Minibuffer): Likewise. - (Initial Input): New node. Document this feature - and say it is mostly deprecated. - -2004-05-30 Richard M. Stallman - - * loading.texi (Named Features): Clarify return value - and meaning of NOERROR. - - * variables.texi (File Local Variables): Minor cleanup. - -2004-05-30 Michael Albinus - - * files.texi (Magic File Names): Add `file-remote-p' as operation - of file name handlers. - -2004-05-29 Richard M. Stallman - - * modes.texi (Minor Mode Conventions): (-) has no special meaning - as arg to a minor mode command. - -2004-05-22 Richard M. Stallman - - * syntax.texi (Syntax Class Table): Word syntax not just for English. - - * streams.texi (Output Variables): Doc float-output-format. - - * searching.texi (Regexp Special): Nested repetition can be infloop. - - * eval.texi (Eval): Increasing max-lisp-eval-depth can cause - real stack overflow. - - * compile.texi: Minor cleanups. - -2004-05-22 Luc Teirlinck - - * lists.texi (Cons Cells): Explain dotted lists, true lists, - circular lists. - (List Elements): Explain handling of circular and dotted lists. - -2004-05-19 Thien-Thi Nguyen - - * modes.texi (Search-based Fontification): Fix typo. - -2004-05-10 Juanma Barranquero - - * modes.texi (Mode Line Variables): Fix description of - global-mode-string, which is now after which-func-mode, not the - buffer name. - -2004-05-07 Lars Hansen - - * modes.texi (Desktop Save Mode): Add. - (Modes): Add menu entry Desktop Save Mode. - - * hooks.texi: Add desktop-after-read-hook, - desktop-no-desktop-file-hook and desktop-save-hook. - - * locals.texi: Add desktop-save-buffer. - -2004-04-30 Jesper Harder - - * display.texi: emacs -> Emacs. - -2004-04-27 Matthew Mundell - - * files.texi (Changing Files): Document set-file-times. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-04-18 Jesper Harder - - * tips.texi (Coding Conventions): defopt -> defcustom. - -2004-04-16 Luc Teirlinck - - * sequences.texi: Various clarifications. - -2004-04-14 Luc Teirlinck - - * buffers.texi (Read Only Buffers): Mention optional ARG to - `toggle-read-only'. - -2004-04-14 Nick Roberts - - * windows.texi (Selecting Windows): Note that get-lru-window - returns a full-width window if possible. - -2004-04-13 Luc Teirlinck - - * buffers.texi: Various changes in addition to: - (Buffer File Name): Add `find-buffer-visiting'. - (Buffer Modification): Mention optional ARG to `not-modified'. - (Indirect Buffers): Mention optional CLONE argument to - `make-indirect-buffer'. - - * files.texi: Various changes in addition to: - (Visiting Functions): `find-file-hook' is now a normal hook. - (File Name Expansion): Explain difference between the way that - `expand-file-name' and `file-truename' treat `..'. - (Contents of Directories): Mention optional ID-FORMAT argument to - `directory-files-and-attributes'. - (Format Conversion): Mention new optional CONFIRM argument to - `format-write-file'. - -2004-04-12 Miles Bader - - * macros.texi (Expansion): Add description of `macroexpand-all'. - -2004-04-05 Jesper Harder - - * variables.texi (Variable Aliases): - Mention cyclic-variable-indirection. - - * errors.texi (Standard Errors): Ditto. - -2004-04-04 Luc Teirlinck - - * backups.texi: Various small changes in addition to: - (Making Backups): Mention return value of `backup-buffer'. - (Auto-Saving): Mention optional FORCE argument to - `delete-auto-save-file-if-necessary'. - (Reverting): Mention optional PRESERVE-MODES argument to - `revert-buffer'. Correct description of `revert-buffer-function'. - -2004-03-22 Juri Linkov - - * sequences.texi (Sequence Functions): Replace xref to `Vectors' - with `Vector Functions'. - - * text.texi (Sorting): Add missing quote. - -2004-03-14 Luc Teirlinck - - * intro.texi (Lisp History): Replace xref to `cl' manual with - inforef. - -2004-03-12 Richard M. Stallman - - * intro.texi (Version Info): Add arg to emacs-version. - (Lisp History): Change xref to CL manual. - -2004-03-09 Luc Teirlinck - - * minibuf.texi (Completion Commands): Add xref to Emacs manual - for Partial Completion mode. - -2004-03-07 Thien-Thi Nguyen - - * customize.texi: Fix typo. Remove eol whitespace. - -2004-03-04 Richard M. Stallman - - * processes.texi: Fix typos. - - * lists.texi (Building Lists): Minor clarification. - - * hash.texi (Creating Hash): Correct the meaning of t for WEAK - in make-hash-table. - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (clean, maintainer-clean): Use $(DEL) instead of - rm, and ignore exit code. - -2004-02-27 Dan Nicolaescu - - * display.texi (Defining Faces): Add description for min-colors. - Update example. - -2004-02-23 Luc Teirlinck - - * abbrevs.texi: Various corrections and clarifications in addition - to the following: - (Abbrev Tables): Delete add-abbrev (as suggested by RMS). - -2004-02-22 Matthew Mundell (tiny change) - - * calendar.texi (Holiday Customizing): Quote arg of holiday-sexp. - -2004-02-21 Luc Teirlinck - - * text.texi: Various small changes in addition to the following: - (User-Level Deletion): Mention optional BACKWARD-ONLY argument - to delete-horizontal-space. - (Kill Functions, Yanking, Low-Level Kill Ring): Clarify and correct - description of yank-handler text property at various places. - - * frames.texi (Window System Selections): Add anchor. - - * syntax.texi (Syntax Table Functions): Clarify and correct - descriptions of make-syntax-table and copy-syntax-table. - (Motion and Syntax): Clarify SYNTAXES argument to - skip-syntax-forward. - (Parsing Expressions): Mention that the return value of - parse-partial-sexp is currently a list of ten rather than nine - elements. - (Categories): Various corrections and clarifications. - -2004-02-17 Luc Teirlinck - - * markers.texi (Marker Insertion Types): Minor change. - - * locals.texi (Standard Buffer-Local Variables): - * commands.texi (Interactive Codes, Using Interactive): - * functions.texi (Related Topics): Fix xrefs. - -2004-02-16 Luc Teirlinck - - * lists.texi (Sets And Lists): Update description of delete-dups. - -2004-02-16 Jesper Harder (tiny change) - - * keymaps.texi (Tool Bar): tool-bar-item => tool-bar-button. - -2004-02-16 Jan Djärv - - * frames.texi (Parameter Access): frame-parameters arg is optional. - modify-frame-parameters handles nil for FRAME. - (Window Frame Parameters): menu-bar-lines and tool-bar-lines - are all-or-nothing for certain toolkits. - Mention parameter wait-for-wm. - (Frames and Windows): In frame-first-window and frame-selected-window - the arg is optional. - (Input Focus): In redirect-frame-focus the second arg is optional. - (Window System Selections): Mention selection type CLIPBOARD. - Mention data-type UTF8_STRING. - Mention numbering of cut buffers. - (Resources): Describe x-resource-name. - -2004-02-16 Richard M. Stallman - - * windows.texi (Buffers and Windows): Delete false table - about all-frames. - - * syntax.texi (Parsing Expressions): Delete old caveat - about parse-sexp-ignore-comments. - - * streams.texi (Output Variables): Add print-quoted. - - * lists.texi (Building Lists): Minor cleanup. - - * hash.texi (Creating Hash): Correct and clarify doc of WEAK values. - - * display.texi (Overlays): Explain overlays use markers. - (Managing Overlays): Explain front-advance and rear-advance - in more detail. - - * loading.texi (Unloading): Document unload-feature-special-hooks. - Get rid of fns-NNN.el file. - -2004-02-16 Matthew Mundell (tiny change) - - * help.texi (Describing Characters): Fix text-char-description - example output. - - * edebug.texi (Using Edebug): Fix example. - - * debugging.texi (Internals of Debugger): Fix return value. - - * files.texi (Changing Files): Fix argname. - - * calendar.texi: Fix parens, and default values. - - * display.texi, frames.texi, internals.texi, modes.texi: Minor fixes. - * nonascii.texi, objects.texi, os.texi: Minor fixes. - * searching.texi, text.texi, tips.texi, windows.texi: Minor fixes. - - * positions.texi (Text Lines): Don't add -1 in current-line. - -2004-02-16 Richard M. Stallman - - * compile.texi (Compiler Errors): if-boundp feature applies to cond. - -2004-02-16 Jesper Harder (tiny change) - - * processes.texi (Low-Level Network): Fix a typo. - -2004-02-12 Kim F. Storm - - * display.texi (Fringes): Use consistent wording. - Note that window-fringe's window arg is optional. - (Scroll Bars): Use consistent wording. - -2004-02-11 Luc Teirlinck - - * tips.texi (Comment Tips): Document the new conventions for - commenting out code. - -2004-02-07 Jan Djärv - - * positions.texi (Text Lines): Add missing end defun. - -2004-02-07 Kim F. Storm - - * positions.texi (Text Lines): Add line-number-at-pos. - -2004-02-06 John Paul Wallington - - * display.texi (Button Properties, Button Buffer Commands): - mouse-2 invokes button, not down-mouse-1. - -2004-02-04 Jason Rumney - - * makefile.w32-in: Sync with Makefile.in changes. - -2004-02-03 Luc Teirlinck - - * minibuf.texi (Text from Minibuffer): Various corrections and - clarifications. - (Object from Minibuffer): Correct Lisp description of - read-minibuffer. - (Minibuffer History): Clarify description of cons values for - HISTORY arguments. - (Basic Completion): Various corrections and clarifications. - Add completion-regexp-list. - (Minibuffer Completion): Correct and clarify description of - completing-read. - (Completion Commands): Mention Partial Completion mode. - Various other minor changes. - (High-Level Completion): Various corrections and clarifications. - (Reading File Names): Ditto. - (Minibuffer Misc): Ditto. - -2004-01-26 Luc Teirlinck - - * strings.texi (Text Comparison): assoc-string also matches - elements of alists that are strings instead of conses. - (Formatting Strings): Standardize Texinfo usage. Update index - entries. - -2004-01-20 Luc Teirlinck - - * lists.texi (Sets And Lists): Add delete-dups. - -2004-01-15 Luc Teirlinck - - * edebug.texi (Instrumenting Macro Calls): `declare' is not a - special form. - * macros.texi (Defining Macros): Update description of `declare', - which now is a macro. - (Wrong Time): Fix typos. - -2004-01-14 Luc Teirlinck - - * compile.texi (Compilation Functions): Expand descriptions of - `compile-defun', `byte-compile-file', `byte-recompile-directory' - and `batch-byte-compile'. In particular, mention and describe - all optional arguments. - (Disassembly): Correct and clarify the description of `disassemble'. - -2004-01-11 Luc Teirlinck - - * searching.texi: Various small changes in addition to the - following. - (Regexp Example): Adapt to new value of `sentence-end'. - (Regexp Functions): The PAREN argument to `regexp-opt' can be - `words'. - (Search and Replace): Add usage note for `perform-replace'. - (Entire Match Data): Mention INTEGERS and REUSE arguments to - `match-data'. - (Standard Regexps): Update for new values of `paragraph-start' - and `sentence-end'. - -2004-01-07 Luc Teirlinck - - * files.texi (Saving Buffers): Clarify descriptions of - `write-contents-functions' and `before-save-hook'. - Make the defvar's for `before-save-hook' and `after-save-hook' - into defopt's. - -2004-01-07 Kim F. Storm - - * commands.texi (Click Events): Describe new image and - width/height elements of click events. - (Accessing Events): Add posn-string, posn-image, and - posn-object-width-height. Change posn-object to return either - image or string object. - -2004-01-01 Simon Josefsson - - * hooks.texi (Standard Hooks): Add before-save-hook. - * files.texi (Saving Buffers): Likewise. - -2004-01-03 Richard M. Stallman - - * frames.texi (Frames and Windows): Delete frame-root-window. - -2004-01-03 Luc Teirlinck - - * eval.texi, hash.texi, help.texi, symbols.texi: Add anchors. - - * functions.texi: Various small changes in addition to the - following. - (What Is a Function): `functionp' returns nil for macros. - Clarify behavior of this and following functions for symbol arguments. - (Function Documentation): Add `\' in front of (fn @var{arglist}) - and explain why. - (Defining Functions): Mention DOCSTRING argument to `defalias'. - Add anchor. - (Mapping Functions): Add anchor. Unquote nil in mapcar* example. - -2004-01-01 Miles Bader - - * display.texi (Buttons): New section. - -2003-12-31 Andreas Schwab - - * numbers.texi (Math Functions): sqrt reports a domain-error - error. - (Float Basics): Use `(/ 0.0 0.0)' instead of `(sqrt -1.0)'. - -2003-12-30 Luc Teirlinck - - * tips.texi (Documentation Tips): Update item on hyperlinks in - documentation strings. - - * errors.texi (Standard Errors): Various small corrections and - additions. - - * control.texi: Various small changes in addition to the - following. - (Signaling Errors): Provide some more details on how `signal' - constructs the error message. Add anchor to the definition of - `signal'. - (Error Symbols): Describe special treatment of `quit'. - (Cleanups): Rename BODY argument of `unwind-protect' to BODY-FORM - to emphasize that it has to be a single form. - - * buffers.texi: Add anchor. - -2003-12-29 Richard M. Stallman - - * windows.texi (Choosing Window): Add same-window-p, special-display-p. - (Window Configurations): Add window-configuration-frame. - - * variables.texi (Creating Buffer-Local): Add local-variable-if-set-p. - - * text.texi (Examining Properties): Add get-char-property-and-overlay. - Change arg name in get-char-property. - (Special Properties): Update handling of keymap property. - - * strings.texi (Modifying Strings): Add clear-string. - (Text Comparison): Add assoc-string and remove - assoc-ignore-case, assoc-ignore-representation. - - * os.texi (Time of Day): Add set-time-zone-rule. - - * numbers.texi (Math Functions): asin, acos, log, log10 - report domain-error errors. - - * nonascii.texi (Converting Representations): - Add multibyte-char-to-unibyte and unibyte-char-to-multibyte. - (Encoding and I/O): Add file-name-coding-system. - - * modes.texi (Search-based Fontification): Explain that - face specs are symbols with face names as values. - - * minibuf.texi (Minibuffer Misc): Add set-minibuffer-window. - - * lists.texi (Building Lists): remq moved elsewhere. - (Sets And Lists): remq moved here. - (Association Lists): Refer to assoc-string. - - * internals.texi (Garbage Collection): Add memory-use-counts. - - * frames.texi (Frames and Windows): Add set-frame-selected-window - and frame-root-window. - - * files.texi (Contents of Directories): - Add directory-files-and-attributes. - - * display.texi (Refresh Screen): Add force-window-update. - (Invisible Text): Explain about moving point out of invis text. - (Overlay Properties): Add overlay-properties. - (Managing Overlays): Add overlayp. - (GIF Images): Invalid image number displays a hollow box. - - * buffers.texi (Buffer Modification): Add restore-buffer-modified-p. - (Killing Buffers): Add buffer-live-p. - -2003-12-25 Markus Rost - - * display.texi (Fringes): Fix typo "set-buffer-window". - -2003-12-24 Luc Teirlinck - - * display.texi, eval.texi, help.texi, internals.texi, loading.texi: - * nonascii.texi, processes.texi, tips.texi, variables.texi: - Add or change various xrefs and anchors. - - * commands.texi: Replace all occurrences of @acronym{CAR} with - @sc{car}, for consistency with the rest of the Elisp manual. - `car' and `cdr' are historically acronyms, but are no longer - widely thought of as such. - - * internals.texi (Pure Storage): Mention that `purecopy' does not - copy text properties. - (Object Internals): Now 29 bits are used (in most implementations) - to address Lisp objects. - - * variables.texi (Variables with Restricted Values): New node. - - * objects.texi (Lisp Data Types): Mention that certain variables - can only take on a restricted set of values and add an xref to - the new node "Variables with Restricted Values". - - * eval.texi (Function Indirection): Describe the errors that - `indirect-function' can signal. - (Eval): Clarify the descriptions of `eval-region' and `values'. - Describe `eval-buffer' instead of `eval-current-buffer' and - mention `eval-current-buffer' as an alias for `current-buffer'. - Correct the description and mention all optional arguments. - - * nonascii.texi: Various small changes in addition to the - following. - (Converting Representations): Clarify behavior of - `string-make-multibyte' and `string-to-multibyte' for unibyte all - ASCII arguments. - (Character Sets): Document the variable `charset-list' and adapt - the definition of the function `charset-list' accordingly. - (Translation of Characters): Clarify use of generic characters in - `make-translation-table'. Clarify and correct the description of - the use of translation tables in encoding and decoding. - (User-Chosen Coding Systems): Correct and clarify the description - of `select-safe-coding-system'. - (Default Coding Systems): Clarify description of - `file-coding-system-alist'. - -2003-11-30 Luc Teirlinck - - * strings.texi (Text Comparison): Correctly describe when two - strings are `equal'. Combine and clarify descriptions of - `assoc-ignore-case' and `assoc-ignore-representation'. - - * objects.texi (Non-ASCII in Strings): Clarify description of - when a string is unibyte or multibyte. - (Bool-Vector Type): Update examples. - (Equality Predicates): Correctly describe when two strings are - `equal'. - -2003-11-29 Luc Teirlinck - - * lists.texi (Building Lists): `append' no longer accepts integer - arguments. Update the description of `number-sequence' to reflect - recent changes. - (Sets And Lists): Describe `member-ignore-case' after `member'. - -2003-11-27 Kim F. Storm - - * commands.texi (Click Events): Click object may be an images. - Describe (dx . dy) element of click positions. - (Accessing Events): Remove duplicate posn-timestamp. - New functions posn-object and posn-object-x-y. - -2003-11-23 Kim F. Storm - - * commands.texi (Click Events): Describe enhancements to event - position lists, including new text-pos and (col . row) items. - Mention left-fringe and right-fringe area events. - (Accessing Events): New functions posn-area and - posn-actual-col-row. Mention posn-timestamp. Mention that - posn-point in non-text area still returns buffer position. - Clarify posn-col-row. - -2003-11-21 Lars Hansen - - * files.texi (File Attributes): Describe new parameter ID-FORMAT. - * anti.texi (File Attributes): Describe removed parameter - ID-FORMAT. - -2003-11-20 Luc Teirlinck - - * positions.texi (Positions): Mention that, if a marker is used as - a position, its buffer is ignored. - - * markers.texi (Overview of Markers): Mention it here too. - -2003-11-12 Luc Teirlinck - - * numbers.texi (Numeric Conversions): Not just `floor', but also - `truncate', `ceiling' and `round' accept optional argument DIVISOR. - -2003-11-10 Luc Teirlinck - - * markers.texi (Creating Markers): Specify insertion type of - created markers. Add xref to `Marker Insertion Types'. - Second argument to `copy-marker' is optional. - (Marker Insertion Types): Mention that most markers are created - with insertion type nil. - (The Mark): Correctly describe when `mark' signals an error. - (The Region): Correctly describe when `region-beginning' and - `region-end' signal an error. - -2003-11-08 Luc Teirlinck - - * hash.texi (Creating Hash): Clarify description of `eql'. - `makehash' is obsolete. - (Hash Access): Add Common Lisp notes for `remhash' and `clrhash'. - - * positions.texi (Point): Change description of `buffer-end', so - that it is also correct for floating point arguments. - (List Motion): Correct argument lists of `beginning-of-defun' and - `end-of-defun'. - (Excursions): Add xref to `Marker Insertion Types'. - (Narrowing): Argument to `narrow-to-page' is optional. - -2003-11-06 Luc Teirlinck - - * streams.texi (Output Streams): Clarify behavior of point for - marker output streams. - -2003-11-04 Luc Teirlinck - - * variables.texi (Defining Variables): Second argument to - `defconst' is not optional. - (Setting Variables): Mention optional argument APPEND to - `add-to-list'. - (Creating Buffer-Local): Expand description of - `make-variable-buffer-local'. - (Frame-Local Variables): Expand description of - `make-variable-frame-local'. - (Variable Aliases): Correct description of optional argument - DOCSTRING to `defvaralias'. Mention return value of - `defvaralias'. - (File Local Variables): Add xref to `File variables' in Emacs - Manual. Correct description of `hack-local-variables'. Mention - `safe-local-variable' property. Mention optional second argument - to `risky-local-variable-p'. - -2003-11-03 Luc Teirlinck - - * symbols.texi (Symbol Plists): Mention return value of `setplist'. - -2003-11-02 Jesper Harder (tiny change) - - * anti.texi, backups.texi, commands.texi, customize.texi: - * display.texi, files.texi, internals.texi, keymaps.texi: - * loading.texi, modes.texi, nonascii.texi, numbers.texi: - * objects.texi, os.texi, positions.texi, processes.texi: - * searching.texi, sequences.texi, streams.texi, strings.texi: - * syntax.texi, text.texi: Replace @sc{foo} with @acronym{FOO}. - -2003-10-27 Luc Teirlinck - - * strings.texi (Creating Strings): Argument START to `substring' - can not be `nil'. Expand description of - `substring-no-properties'. Correct description of `split-string', - especially with respect to empty matches. Prevent very bad line - break in definition of `split-string-default-separators'. - (Text Comparison): `string=' and `string<' also accept symbols as - arguments. - (String Conversion): More completely describe argument BASE in - `string-to-number'. - (Formatting Strings): `%s' and `%S' in `format' do require - corresponding object. Clarify behavior of numeric prefix after - `%' in `format'. - (Case Conversion): The argument to `upcase-initials' can be a - character. - -2003-10-27 Kenichi Handa - - * display.texi (Fontsets): Fix texinfo usage. - -2003-10-25 Kenichi Handa - - * display.texi (Fontsets): Add description of the function - set-fontset-font. - -2003-10-23 Luc Teirlinck - - * display.texi (Temporary Displays): Add xref to `Documentation - Tips'. - - * functions.texi (Function Safety): Use inforef instead of pxref - for SES. - -2003-10-23 Andreas Schwab - - * Makefile.in (TEX, texinputdir): Don't define. - (TEXI2DVI): Define. - (srcs): Remove $(srcdir)/index.perm and $(srcdir)/index.unperm, - add $(srcdir)/index.texi. - ($(infodir)/elisp): Remove index.texi dependency. - (elisp.dvi): Likewise. Use $(TEXI2DVI). - (index.texi): Remove target. - (dist): Don't link $(srcdir)/permute-index. - (clean): Don't remove index.texi. - - * permute-index, index.perm: Remove. - * index.texi: Rename from index.unperm. - -2003-10-22 Luc Teirlinck - - * tips.texi (Documentation Tips): Document new behavior for face - and variable hyperlinks in Help mode. - -2003-10-21 Luc Teirlinck - - * objects.texi (Integer Type): Update for extra bit of integer range. - (Character Type): Ditto. - -2003-10-16 Eli Zaretskii - - * numbers.texi (Integer Basics): Add index entries for reading - numbers in hex, octal, and binary. - -2003-10-16 Lute Kamstra - - * modes.texi (Mode Line Format): Mention force-mode-line-update's - argument. - -2003-10-13 Luc Teirlinck - - * windows.texi (Choosing Window): Fix typo. - * edebug.texi (Edebug Execution Modes): Fix typo. - -2003-10-13 Richard M. Stallman - - * windows.texi (Basic Windows): A window has fringe settings, - display margins and scroll-bar settings. - (Splitting Windows): Doc split-window return value. - Clean up one-window-p. - (Selecting Windows): Fix typo. - (Cyclic Window Ordering): Explain frame as ALL-FRAMES in next-window. - (Buffers and Windows): In set-window-buffer, explain effect - on fringe settings and scroll bar settings. - (Displaying Buffers): In pop-to-buffer, explain nil as buffer arg. - (Choosing Window): Use defopt for pop-up-frame-function. - For special-display-buffer-names, explain same-window and same-frame. - Clarify window-dedicated-p return value. - (Textual Scrolling): scroll-up and scroll-down can get an error. - (Horizontal Scrolling): Clarify auto-hscroll-mode. - Clarify set-window-hscroll. - (Size of Window): Don't mention tool bar in window-height. - (Coordinates and Windows): Explain what coordinates-in-window-p - returns for fringes and display margins. - (Window Configurations): Explain saving fringes, etc. - - * tips.texi (Library Headers): Clean up Documentation. - - * syntax.texi (Parsing Expressions): Clean up forward-comment - and parse-sexp-lookup-properties. - - * sequences.texi (Sequence Functions): sequencep accepts bool-vectors. - - * os.texi (System Environment): Clean up text for load-average errors. - - * modes.texi (Hooks): Don't explain local hook details at front. - Clarify run-hooks and run-hook-with-args a little. - Clean up add-hook and remove-hook. - - * edebug.texi (Edebug Execution Modes): Clarify t. - Document edebug-sit-for-seconds. - (Coverage Testing): Document C-x X = and =. - (Instrumenting Macro Calls): Fix typo. - (Specification List): Don't index the specification keywords. - -2003-10-10 Kim F. Storm - - * processes.texi (Network): Introduce make-network-process. - -2003-10-09 Luc Teirlinck - - * tips.texi (Library Headers): Fix typo. - -2003-10-07 Juri Linkov - - * modes.texi (Imenu): Mention imenu-create-index-function's - default value. Explain submenus better. - -2003-10-07 Lute Kamstra - - * modes.texi (Faces for Font Lock): Fix typo. - (Hooks): Explain how buffer-local hook variables can refer to - global hook variables. - Various minor clarifications. - -2003-10-06 Lute Kamstra - - * tips.texi (Coding Conventions): Mention naming conventions for - hooks. - -2003-10-05 Luc Teirlinck - - * loading.texi (Library Search): Correct default value of - load-suffixes. - (Named Features): Fix typo. - -2003-10-05 Richard M. Stallman - - * loading.texi (Named Features): In `provide', - say how to test for subfeatures. - (Unloading): In unload-feature, use new var name - unload-feature-special-hooks. - -2003-10-03 Lute Kamstra - - * modes.texi (Major Mode Conventions): Mention third way to set up - Imenu. - (Imenu): A number of small fixes. - Delete documentation of internal variable imenu--index-alist. - Document the return value format of imenu-create-index-function - functions. - -2003-09-30 Richard M. Stallman - - * processes.texi (Network): Say what stopped datagram connections do. - - * lists.texi (Association Lists): Clarify `assq-delete-all'. - - * display.texi (Overlay Properties): Clarify `evaporate' property. - -2003-09-29 Lute Kamstra - - * modes.texi (Mode Line Data): Explain when symbols in mode-line - constructs should be marked as risky. - Change cons cell into proper list. - (Mode Line Variables): Change cons cell into proper list. - -2003-09-26 Lute Kamstra - - * modes.texi (Mode Line Data): Document the :propertize construct. - (Mode Line Variables): Reorder the descriptions of the variables - to match their order in the default mode-line-format. - Describe the new variables mode-line-position and mode-line-modes. - Update the default values of mode-line-frame-identification, - minor-mode-alist, and default-mode-line-format. - (Properties in Mode): Mention the :propertize construct. - -2003-09-26 Richard M. Stallman - - * buffers.texi, commands.texi, debugging.texi, eval.texi: - * loading.texi, minibuf.texi, text.texi, variables.texi: - Avoid @strong{Note:}. - -2003-09-26 Richard M. Stallman - - * keymaps.texi (Remapping Commands): Fix typo. - -2003-09-23 Luc Teirlinck - - * processes.texi (Low-Level Network): Fix typo. - -2003-09-23 Kim F. Storm - - * processes.texi (Network, Network Servers): Fix typos. - (Low-Level Network): Add timeout value for :server keyword. - Add new option keywords to make-network-process. - Add set-network-process-options. - Explain how to test availability of network options. - -2003-09-19 Richard M. Stallman - - * text.texi (Motion by Indent): Arg to - backward-to-indentation and forward-to-indentation is optional. - - * strings.texi (Creating Strings): Add substring-no-properties. - - * processes.texi - (Process Information): Add list-processes arg QUERY-ONLY. - Delete process-contact from here. - Add new status values for process-status. - Add process-get, process-put, process-plist, set-process-plist. - (Synchronous Processes): Add call-process-shell-command. - (Signals to Processes): signal-process allows process objects. - (Network): Complete rewrite. - (Network Servers, Datagrams, Low-Level Network): New nodes. - - * positions.texi (Word Motion): forward-word, backward-word - arg is optional. Reword. - - * abbrevs.texi (Defining Abbrevs): Index no-self-insert. - - * variables.texi (Creating Buffer-Local): - Delete duplicate definition of buffer-local-value. - (File Local Variables): Explain about discarding text props. - -2003-09-11 Richard M. Stallman - - * minibuf.texi (Intro to Minibuffers): Explain that the minibuffer - changes variables that record input events. - (Minibuffer Misc): Add minibuffer-selected-window. - - * lists.texi (Building Lists): Add copy-tree. - - * display.texi (Fontsets): Add char-displayable-p. - (Scroll Bars): New node. - -2003-09-08 Lute Kamstra - - * modes.texi (%-Constructs): Document new `%i' and `%I' - constructs. - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2003-08-29 Richard M. Stallman - - * display.texi (Overlay Properties): Clarify how priorities - affect use of the properties. - -2003-08-19 Luc Teirlinck - - * customize.texi (Type Keywords): Correct the description of - `:help-echo' in the case where `motion-doc' is a function. - -2003-08-14 John Paul Wallington - - * modes.texi (Emulating Mode Line): Subsection, not section. - -2003-08-13 Richard M. Stallman - - * elisp.texi (Top): Update subnode lists in menu. - - * text.texi (Insertion): Add insert-buffer-substring-no-properties. - (Kill Functions): kill-region has new arg yank-handler. - (Yanking): New node. - (Yank Commands): Add yank-undo-function. - (Low-Level Kill Ring): - kill-new and kill-append have new arg yank-handler. - (Changing Properties): Add remove-list-of-text-properties. - (Atomic Changes): New node. - - * symbols.texi (Other Plists): Add lax-plist-get, lax-plist-put. - - * streams.texi (Output Variables): Add eval-expression-print-length - and eval-expression-print-level. - - * os.texi (Time Conversion): For encode-time, explain limits on year. - - * objects.texi (Character Type): Define anchor "modifier bits". - - * modes.texi (Emulating Mode Line): New node. - (Search-based Fontification): Font Lock uses font-lock-face property. - (Other Font Lock Variables): Likewise. - - * keymaps.texi (Format of Keymaps): Keymaps contain char tables, - not vectors. - (Active Keymaps): Add emulation-mode-map-alists. - (Functions for Key Lookup): key-binding has new arg no-remap. - (Remapping Commands): New node. - (Scanning Keymaps): where-is-internal has new arg no-remap. - (Tool Bar): Add tool-bar-local-item-from-menu. - Clarify when to use tool-bar-add-item-from-menu. - - * commands.texi (Interactive Call): commandp has new arg. - (Command Loop Info): Add this-original-command. - -2003-08-06 John Paul Wallington - - * compile.texi (Compiler Errors): Say `@end defmac' after `@defmac'. - - * display.texi (Warning Basics): Fix typo. - (Fringes): Add closing curly bracket and fix typo. - - * elisp.texi (Top): Fix typo. - -2003-08-05 Richard M. Stallman - - * elisp.texi: Update lists of subnodes. - - * windows.texi (Buffers and Windows): set-window-buffer has new arg. - - * variables.texi (Local Variables): Use lc for example variable names. - - * tips.texi (Library Headers): Explain where to put -*-. - - * strings.texi (Creating Strings): Fix xref for vconcat. - - * sequences.texi (Vector Functions): - vconcat no longer allows integer args. - - * minibuf.texi (Reading File Names): read-file-name has new - arg PREDICATE. New function read-directory-name. - - * macros.texi (Defining Macros): Give definition of `declare'. - (Indenting Macros): New node. - - * frames.texi (Parameter Access): Add modify-all-frames-parameters. - (Window Frame Parameters): Make separate table of parameters - that are coupled with specific face attributes. - (Deleting Frames): delete-frame-hooks renamed to - delete-frame-functions. - - * files.texi (Magic File Names): Add file-remote-p. - Clarify file-local-copy. - - * edebug.texi (Instrumenting Macro Calls): Don't define `declare' - here; instead xref Defining Macros. - - * display.texi (Warnings): New node, and subnodes. - (Fringes): New node. - - * debugging.texi (Test Coverage): New node. - - * compile.texi (Compiler Errors): Explain with-no-warnings - and other ways to suppress warnings. - - * commands.texi (Interactive Call): Minor clarification. - - * buffers.texi (Buffer File Name): set-visited-file-name - renames the buffer too. - - * abbrevs.texi (Abbrev Tables): Add copy-abbrev-table. - -2003-07-24 Markus Rost - - * abbrevs.texi (Abbrev Expansion): Use \s syntax in example. - -2003-07-22 Markus Rost - - * internals.texi (Garbage Collection): Fix previous change. - -2003-07-22 Richard M. Stallman - - * files.texi (Truenames): Add LIMIT arg to file-chase-links. - - * display.texi (Width): Use \s syntax in example. - (Font Selection): Add face-font-rescale-alist. - - * modes.texi (Imenu): Add xref to Emacs Manual node on Imenu. - Remove spurious indent in example. - - * lists.texi (Building Lists): Add number-sequence. - - * internals.texi (Garbage Collection): Add gcs-done, gc-elapsed. - - * functions.texi (Function Documentation): Explain how to - show calling convention explicitly in the doc string. - - * windows.texi (Selecting Windows): save-selected-window saves - selected window of each frame. - (Window Configurations): Minor change. - - * syntax.texi (Syntax Table Functions): Use \s syntax in examples. - - * streams.texi (Output Variables): Add print-continuous-numbering - and print-number-table. - - * processes.texi (Decoding Output): New node. - - * os.texi (Time Conversion): decode-time arg is optional. - - * objects.texi (Character Type): Don't use space as example for \. - Make list of char names and \-sequences correspond. - Explain that \s is not used in strings. `\ ' needs space after. - - * nonascii.texi (Converting Representations): Add string-to-multibyte. - (Translation of Characters): Add translation-table-for-input. - (Default Coding Systems): Add auto-coding-functions. - (Explicit Encoding): Add decode-coding-inserted-region. - (Locales): Add locale-info. - - * minibuf.texi (Basic Completion): Describe test-completion. - Collections can be lists of strings. - Clean up lazy-completion-table. - (Programmed Completion): Mention test-completion. - Clarify why lambda expressions are not accepted. - (Minibuffer Misc): Describe minibufferp. - -2003-07-14 Richard M. Stallman - - * buffers.texi (Killing Buffers): kill-buffer-hook is perm local. - - * windows.texi (Selecting Windows): New arg to select-window. - (Selecting Windows): Add with-selected-window. - (Size of Window): Add window-inside-edges, etc. - - * internals.texi (Garbage Collection): Add post-gc-hook. - - * processes.texi (Subprocess Creation): Add exec-suffixes. - - * keymaps.texi (Functions for Key Lookup): Add current-active-maps. - (Scanning Keymaps): Add map-keymaps. - (Defining Menus): Add keymap-prompt. - - * numbers.texi (Integer Basics): Add most-positive-fixnum, - most-negative-fixnum. - - * compile.texi (Byte Compilation): Explain no-byte-compile. - (Compiler Errors): New node. - - * os.texi (User Identification): user-uid, user-real-uid - can return float. - - * modes.texi (Major Mode Conventions): Explain about run-mode-hooks - and about derived modes. - (Minor Modes): Add minor-mode-list. - (Defining Minor Modes): Keyword args for define-minor-mode. - (Search-based Fontification): Explain managing other properties. - (Other Font Lock Variables): Add font-lock-extra-managed-props. - (Faces for Font Lock): Add font-lock-preprocessor-face. - (Hooks): Add run-mode-hooks and delay-mode-hooks. - - * variables.texi (Creating Buffer-Local): Add buffer-local-value. - (Variable Aliases): Clarify defvaralias. - - * loading.texi (Library Search): Add load-suffixes. - - * minibuf.texi (Basic Completion): Add lazy-completion-table. - (Programmed Completion): Add dynamic-completion-table. - - * files.texi (Changing Files): copy-file allows dir as NEWNAME. - (Magic File Names): Specify precedence order of handlers. - - * commands.texi (Command Overview): Emacs server runs pre-command-hook - and post-command-hook. - (Waiting): New calling convention for sit-for. - - * text.texi (Special Properties): local-map and keymap properties - apply based on their stickiness. - -2003-07-07 Richard M. Stallman - - * modes.texi (Minor Mode Conventions): Specify only some kinds - of list values as args to minor modes. - - * files.texi (File Name Expansion): Warn about iterative use - of substitute-in-file-name. - - * advice.texi (Activation of Advice): Clean up previous change. - -2003-07-06 Markus Rost - - * advice.texi (Activation of Advice): Note that ad-start-advice is - turned on by default. - -2003-06-30 Richard M. Stallman - - * text.texi (Buffer Contents): Document current-word. - (Change Hooks): Not called for *Messages*. - - * functions.texi (Defining Functions): Explain about redefining - primitives. - (Function Safety): Rename. Minor changes. - Comment out the detailed criteria for what is safe. - -2003-06-22 Andreas Schwab - - * objects.texi (Symbol Type): Fix description of examples. - -2003-06-16 Andreas Schwab - - * hash.texi (Creating Hash): Fix description of :weakness. - -2003-06-13 Kai Großjohann - - * files.texi (Changing Files): copy-file copies file modes, too. - -2003-05-28 Richard M. Stallman - - * strings.texi (Creating Strings): Clarify split-string. - -2003-05-22 Stephen J. Turnbull - - * strings.texi (Creating Strings): Update split-string specification - and examples. - -2003-05-19 Richard M. Stallman - - * elisp.texi: Correct invariant section names. - -2003-04-20 Richard M. Stallman - - * os.texi (Timers): Explain about timers and quitting. - -2003-04-19 Richard M. Stallman - - * internals.texi (Writing Emacs Primitives): Strings are - no longer special for GCPROs. Mention GCPRO5, GCPRO6. - Explain GCPRO convention for varargs function args. - -2003-04-16 Richard M. Stallman - - * minibuf.texi (Minibuffer Misc): Document fn minibuffer-message. - -2003-04-08 Richard M. Stallman - - * files.texi (Kinds of Files): Correct return value of file-symlink-p. - -2003-02-13 Kim F. Storm - - * objects.texi (Character Type): New \s escape for space. - -2003-01-31 Joe Buehler - - * os.texi (System Environment): Add cygwin system-type. - -2003-01-25 Richard M. Stallman - - * keymaps.texi: Document that a symbol can act as a keymap. - -2003-01-13 Richard M. Stallman - - * text.texi (Changing Properties): Say string indices are origin-0. - - * positions.texi (Screen Lines) : - Correct order of elts in return value. - - * keymaps.texi (Changing Key Bindings) : Mention - how to define a default binding. - -2002-12-07 Markus Rost - - * loading.texi (Unloading): Fix recent change for load-history. - - * customize.texi (Simple Types): Clarify description of custom - type 'number. Describe new custom type 'float. - -2002-12-04 Markus Rost - - * variables.texi (File Local Variables): Fix typo. - -2002-10-23 Kai Großjohann - - From Michael Albinus . - - * README: Target for Info file is `make info'. - - * files.texi (File Name Components): Fix typos in - `file-name-sans-extension'. - (Magic File Names): Complete list of operations for magic file - name handlers. - -2002-09-16 Jonathan Yavner - - * variables.texi (File Local Variables): New function - risky-local-variable-p. - -2002-09-15 Jonathan Yavner - - * functions.texi (Function safety): New node about unsafep. - -2002-08-05 Per Abrahamsen - - * customize.texi (Splicing into Lists): Fix example. - Reported by Fabrice Bauzac . - -2002-06-17 Juanma Barranquero - - * frames.texi (Display Feature Testing): Fix typo. - -2002-06-12 Andreas Schwab - - * frames.texi (Initial Parameters, Resources): Fix references to - the Emacs manual. - -2002-05-13 Kim F. Storm - - * variables.texi (Intro to Buffer-Local): Update warning and - example relating to changing buffer inside let. - -2002-03-10 Jan Djärv - - * os.texi (Session Management): New node about X Session management. - -2002-01-18 Eli Zaretskii - - * elisp.texi (VERSION): Set to 2.9. Update the version of Emacs - to which the manual corresponds, and the copyright years. - - * Makefile.in (VERSION): Set to 2.9. - -2001-11-29 Eli Zaretskii - - * elisp.texi: Change the category in @dircategory to "Emacs", to - make it consistent with info/dir. - -2001-11-25 Miles Bader - - * text.texi (Fields): Describe new `limit' arg in - field-beginning/field-end. - -2001-11-17 Eli Zaretskii - - * permute-index: Don't depend on csh-specific features. - Replace the interpreter name with /bin/sh. - - * two-volume-cross-refs.txt: New file. - * two.el: New file. - * spellfile: New file. - -2001-11-16 Eli Zaretskii - - * permute-index: New file. - - * vol1.texi, vol2.texi: Renamed from elisp-vol1.texi and - elisp-vol2.texi, respectively, to avoid file-name clashes in DOS - 8+3 restricted namespace. - - * Makefile.in (infodir): Define relative to $(srcdir). - ($(infodir)/elisp): Don't chdir into $(srcdir), but add it to the - include directories list via -I switch to makeinfo. - (index.texi): Use cp if both hard and symbolic links fail. - -2001-11-10 Eli Zaretskii - - * Makefile.in (distclean): Add. - - The following changes make ELisp manual part of the Emacs - distribution: - - * Makefile.in: Add Copyright notice. - (prefix): Remove. - (infodir): Change value to "../info". - (VPATH): New variable. - (MAKE): Don't define. - (texmacrodir): Don't define. - (texinputdir): Append the existing value of TEXINPUTS. - ($(infodir)/elisp): Instead of just "elisp". Reformat the - command to be compatible with man/Makefile.in, and to put the - output into ../info. - (info): Add target. - (installall): Target removed. - -2001-10-31 Pavel Janík - - * tips.texi (Coding Conventions): Fix typo. - -2001-10-23 Gerd Moellmann - - * Makefile.in (srcs): Add gpl.texi and doclicense.texi. - -2001-10-22 Eli Zaretskii - - * files.texi (File Name Components): Update the description of - file-name-sans-extension and file-name-extension, as they now - ignore leading dots. - -2001-10-20 Gerd Moellmann - - * (Version 21.1 released.) - -2001-10-19 Miles Bader - - * positions.texi (Text Lines): Describe behavior of - `beginning-of-line'/`end-of-line' in the presence of field properties. - -2001-10-17 Gerd Moellmann - - * Makefile.in (VERSION): Set to 2.8. - (manual): Use `manual-21'. - - * elisp.texi (VERSION): Add and use it where the version - number was used. Set it to 2.8. - - * intro.texi: Likewise. - -2001-10-13 Eli Zaretskii - - * files.texi (File Name Completion): Document the significance of - a trailing slash in elements of completion-ignored-extensions. - -2001-10-06 Miles Bader - - * variables.texi (Variable Aliases): It's `@defmac', not `@defmacro'. - -2001-10-04 Gerd Moellmann - - * variables.texi (Variable Aliases): New node. - -2001-10-04 Gerd Moellmann - - * Branch for 21.1. - -2001-10-02 Miles Bader - - * minibuf.texi (Minibuffer Misc): Add entries for - `minibuffer-contents', `minibuffer-contents-no-properties', and - `delete-minibuffer-contents'. - Correct description for `minibuffer-prompt-end'. - - * text.texi (Property Search): Correct descriptions of - `next-char-property-change' and `previous-char-property-change'. - Add entries for `next-single-char-property-change' and - `previous-single-char-property-change'. - Make operand names a bit more consistent. - -2001-09-30 Eli Zaretskii - - * frames.texi (Finding All Frames): Document that next-frame and - previous-frame are local to current terminal. - -2001-09-26 Eli Zaretskii - - * keymaps.texi (Creating Keymaps): Fix the description of the - result of make-keymap. - -2001-09-23 Eli Zaretskii - - * display.texi (Font Lookup, Attribute Functions) - (Image Descriptors): Add cross-references to the definition of - selected frame. - - * buffers.texi (The Buffer List): Add cross-references to the - definition of selected frame. - - * frames.texi (Input Focus): Clarify which frame is _the_ selected - frame at any given time. - (Multiple Displays, Size and Position): Add a cross-reference to - the definition of the selected frame. - -2001-09-08 Eli Zaretskii - - * strings.texi (String Conversion) : Document - that a float is returned for integers that are too large. - - * frames.texi (Mouse Position): Document mouse-position-function. - (Display Feature Testing): Document display-images-p. - (Window Frame Parameters): Document the cursor-type variable. - - * numbers.texi (Integer Basics): Document CL style read syntax for - integers in bases other than 10. - - * positions.texi (List Motion): - Document open-paren-in-column-0-is-defun-start. - - * lists.texi (Sets And Lists): Document member-ignore-case. - - * internals.texi (Garbage Collection): Document the used and free - strings report. - (Memory Usage): Document strings-consed. - - * os.texi (Time of Day): Document float-time. - (Recording Input): Document that clear-this-command-keys clears - the vector to be returned by recent-keys. - - * keymaps.texi (Scanning Keymaps) : - The argument keymap can be a list. - - * nonascii.texi (User-Chosen Coding Systems) - : Document the new argument - accept-default-p and the variable - select-safe-coding-system-accept-default-p. Tell what happens if - buffer-file-coding-system is undecided. - (Default Coding Systems): Document auto-coding-regexp-alist. - - * display.texi (The Echo Area) : Document - message-truncate-lines. - (Glyphs): Document that the glyph table is unused on windowed - displays. - - * help.texi (Describing Characters) : - Document the new argument no-angles. - (Accessing Documentation) : Document that - a non-string property is evaluated. - : Document that the function-documentation property - is looked for. - - * windows.texi (Selecting Windows): Document some-window. - - * text.texi (MD5 Checksum): New node, documents the md5 primitive. - - * hooks.texi (Standard Hooks): Add kbd-macro-termination-hook and - apropos-mode-hook. - - * commands.texi (Using Interactive): Document interactive-form. - (Keyboard Macros): Document kbd-macro-termination-hook. - (Command Loop Info): Document that clear-this-command-keys clears - the vector to be returned by recent-keys. - -2001-09-04 Werner LEMBERG - - * Makefile.in (srcdir, texinputdir): New variables. - (srcs, index.texi, install): Use $(srcdir). - (.PHONY): Remove elisp.dvi. - (elisp): Use -I switch for makeinfo. - (elisp.dvi): Use $(srcdir) and $(texinputdir). - (installall, dist): Use $(srcdir). - Fix path to texinfo.tex. - (maintainer-clean): Add elisp.dvi and elisp.oaux. - -2001-08-30 Gerd Moellmann - - * display.texi (Conditional Display): Adjust to API change. - - * configure: New file. - -2001-07-30 Gerd Moellmann - - * commands.texi (Repeat Events): Add description of - double-click-fuzz. - -2001-05-08 Stefan Monnier - - * syntax.texi (Syntax Class Table): Add the missing designator for - comment and string fences. - (Syntax Properties): Add a xref to syntax table internals. - (Syntax Table Internals): Document string-to-syntax. - -2001-05-07 Gerd Moellmann - - * Makefile.in (install): Use install-info command line options - like in Emacs' Makefile.in. - -2000-12-09 Miles Bader - - * windows.texi (Window Start): Update documentation for - `pos-visible-in-window-p'. - -2000-11-12 Stefan Monnier - - * lists.texi (Building Lists): Add footnote to explain how to add - to the end of a list. - -2000-10-25 Gerd Moellmann - - * files.texi (Visiting Functions): Typos. - -2000-10-25 Kenichi Handa - - * files.texi (Visiting Functions): Return value of - find-file-noselect may be a list of buffers if wildcards are used. - -2000-10-24 Miles Bader - - * display.texi (Defining Faces): Document `graphic' display type - in face specs. - -2000-10-18 Kai Großjohann - - * hooks.texi (Standard Hooks): Replace obsolete - `after-make-frame-hook' with `after-make-frame-functions'. - - * frames.texi (Creating Frames): Ditto. - - * variables.texi (Future Local Variables): Ditto. - -2000-10-16 Gerd Moellmann - - * display.texi (Other Image Types): Add description of :foreground - and :background properties of mono PBM images. - -2000-08-17 Werner LEMBERG - - * .cvsignore: New file. - -2000-01-05 Gerd Moellmann - - * tindex.pl: New script. - -1999-12-03 Dave Love - - * Makefile.in (MAKEINFO): New parameter. - -1999-09-17 Richard Stallman - - * Makefile.in (srcs): Add hash.texi. - (VERSION): Update to 20.6. - -1999-09-13 Richard Stallman - - * Makefile.in (index.texi): If cannot make a symlink, make a hard link. - -1998-08-29 Karl Heuer - - * configure.in: New file. - * Makefile.in: Renamed from Makefile. - (prefix, infodir): Use value obtained from configure. - (emacslibdir): Obsolete variable deleted. - (dist): Distribute configure.in, configure, Makefile.in. - -1998-06-12 Richard Stallman - - * Makefile (INSTALL_INFO): New variable. - (install): Run install-info. - -1998-05-09 Richard Stallman - - * Makefile (elisp.dvi): Add missing backslash. - -1998-05-02 Richard Stallman - - * Makefile (elisp.dvi): Don't depend on texindex or on elisp.tps. - Run texindex without `./'. Always run texindex on elisp.tp. - (elisp.tps): Target deleted. - -1998-04-05 Richard Stallman - - * Makefile (srcs): Add nonascii.texi and customize.texi. - (dist): Start by deleting `temp'. - -1998-02-17 Richard Stallman - - * Makefile (makeinfo, texindex): Targets deleted. - (makeinfo.o, texindex.o): Targets deleted. - (clean, dist): Don't do anything with them or with getopt*. - -1998-01-30 Richard Stallman - - * Makefile (SHELL): Defined. - -1998-01-27 Richard Stallman - - * Makefile (elisp.tps): New target. - (elisp.dvi): Depend on elisp.tps. - -1996-04-03 Karl Heuer - - * README: Update phone number. - - * Makefile (elisp): Make this be the default target. - Depend on makeinfo.c instead of makeinfo. - (install): Don't depend on elisp.dvi, since we don't install that. - Use mkinstalldirs. - (dist): Add mkinstalldirs. - -1995-06-19 Richard Stallman - - * Makefile (VERSION): Update version number. - (maintainer-clean): Rename from realclean. - -1995-06-07 Karl Heuer - - * Makefile (realclean): New target. - (elisp): Remove any old elisp-* files first. - -1993-11-23 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) - - * Makefile (VERSION): New variable. - (dist): Make packaged directory name `elisp-manual-19-$(VERSION)'. - Compressed file suffix should be `.gz', not `.z'. - -1993-11-22 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (elisp): Depend on makeinfo. - -1993-11-19 Noah Friedman (friedman@gnu.ai.mit.edu) - - * Makefile (srcs): Add anti.texi. - -1993-05-28 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (infodir, prefix): New vars. - (install): Use infodir. - (emacsinfodir): Delete. - -1993-05-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (srcs): Add calendar.texi. - - * Makefile (dist): Copy texindex.c and makeinfo.c. - Limit elisp-* files to those with one or two digits. - -1993-05-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Change to use Gzip instead of compress. - -1993-04-23 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * loading.texi (Unloading): define-function changed back to - defalias. It may not stay this way, but at least it's - consistent with the known-good version of the code patch. - -1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) - - * modes.texi (Hooks): Document new optional arg of add-hook. - -1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * variables.texi: Document nil initial value of buffer-local variables. - - * tips.texi: Add new section on standard library headers. - -1993-02-27 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (srcs): Add frame.texi to the list of sources. - -1993-02-23 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Don't bother excluding autosave files; they'll - never make it into the temp directory anyway, and the hash marks - in the name are problematic for make and the Bourne shell. - (srcs): ??? - -1993-02-12 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Don't include backup files or autosave files in - the distribution tar file. - -1991-11-26 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (srcs): Add index.perm. - (elisp.dvi): Remove erroneous shell comment. - Expect output of permute-index in permuted.fns. - Save old elisp.aux in elisp.oaux. - (clean): Add index.texi to be deleted. - -1990-08-11 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * Makefile (elisp.dvi, index.texi): Use shell if instead of ifdef. - -1990-06-26 David Lawrence (tale@geech) - - * files.texi: Noted that completion-ignored-extensions is ignored - when making *Completions*. - -1990-06-08 Jay Fenlason (hack@ai.mit.edu) - - * Makefile make dist now depends on elisp.dvi, since it tries - to include it in the dist file. - -1990-03-28 Jim Kingdon (kingdon@mole.ai.mit.edu) - - * functions.texinfo (Mapping Functions): Add missing quote. - -1989-06-19 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * texinfo.tex (frenchspacing): Use decimal codes for char to be set. - (defunargs): Turn off \hyphenchar of \sl font temporarily. - -1989-05-10 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * @result{}, @expansion{}, @print{}, @quiv{}, @point{}, - and @error{} are the terms now being used. The files in the - directory have been changed to reflect this. - - * All instances of @indentedresultt{} have been changed to - ` @result{}', using 5 spaces at the beginning of the line. - -1989-04-24 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * @result{}, @expandsto{}, @prints{}, @quiv{}, @error{}, and the - experimental @indentedresult{}, @indentedexpandsto{} are part of - the texinfo.tex in this directory. These TeX macros are not - stable yet. - -1989-04-17 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * texinfo.tex: Temporarily added - \let\result=\dblarrow - \def\error{{\it ERROR} \longdblarrow} - We need to do this better soon. - -1989-04-11 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * Applied Karl Berry's patches to *.texinfo files, but not to - texinfo.tex; those diffs are in `berry-texinfo-tex-diffs'. (Karl's - new title page format is also not applied, since it requires - texinfo.tex changes.) - - * Cleaned up `Makefile' and defined the `emacslibdir' directory - for the Project GNU development environment. - -;; Local Variables: -;; coding: utf-8 -;; End: - - Copyright (C) 1998-2014 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in deleted file mode 100644 index fdb643e0fc8..00000000000 --- a/doc/lispref/Makefile.in +++ /dev/null @@ -1,262 +0,0 @@ -### @configure_input@ - -# Copyright (C) 1990-1996, 1998-2014 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -SHELL = @SHELL@ - -# NB If you add any more configure variables, -# update the sed rules in the dist target below. - -# Standard configure variables. -srcdir = @srcdir@ - -version=@version@ - -buildinfodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs - -prefix = @prefix@ -datarootdir = @datarootdir@ -datadir = @datadir@ -PACKAGE_TARNAME = @PACKAGE_TARNAME@ -docdir = @docdir@ -dvidir = @dvidir@ -htmldir = @htmldir@ -pdfdir = @pdfdir@ -psdir = @psdir@ - -MKDIR_P = @MKDIR_P@ - -GZIP_PROG = @GZIP_PROG@ - -HTML_OPTS = --no-split --html - -INFO_EXT=@INFO_EXT@ -# Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ - -INSTALL = @INSTALL@ -INSTALL_DATA = @INSTALL_DATA@ - -MAKEINFO = @MAKEINFO@ -MAKEINFO_OPTS = --force --enable-encoding -I $(emacsdir) -I $(srcdir) -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips - -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" - -DVI_TARGETS = elisp.dvi -HTML_TARGETS = elisp.html -PDF_TARGETS = elisp.pdf -PS_TARGETS = elisp.ps - -# List of all the texinfo files in the manual: - -srcs = \ - $(srcdir)/elisp.texi \ - $(emacsdir)/emacsver.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/backups.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/compile.texi \ - $(srcdir)/control.texi \ - $(srcdir)/customize.texi \ - $(srcdir)/debugging.texi \ - $(srcdir)/display.texi \ - $(srcdir)/edebug.texi \ - $(srcdir)/errors.texi \ - $(srcdir)/eval.texi \ - $(srcdir)/files.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/functions.texi \ - $(srcdir)/hash.texi \ - $(srcdir)/help.texi \ - $(srcdir)/hooks.texi \ - $(srcdir)/internals.texi \ - $(srcdir)/intro.texi \ - $(srcdir)/keymaps.texi \ - $(srcdir)/lists.texi \ - $(srcdir)/loading.texi \ - $(srcdir)/macros.texi \ - $(srcdir)/maps.texi \ - $(srcdir)/markers.texi \ - $(srcdir)/minibuf.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/nonascii.texi \ - $(srcdir)/numbers.texi \ - $(srcdir)/objects.texi \ - $(srcdir)/os.texi \ - $(srcdir)/package.texi \ - $(srcdir)/positions.texi \ - $(srcdir)/processes.texi \ - $(srcdir)/searching.texi \ - $(srcdir)/sequences.texi \ - $(srcdir)/streams.texi \ - $(srcdir)/strings.texi \ - $(srcdir)/symbols.texi \ - $(srcdir)/syntax.texi \ - $(srcdir)/text.texi \ - $(srcdir)/tips.texi \ - $(srcdir)/variables.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/index.texi \ - $(srcdir)/gpl.texi \ - $(srcdir)/doclicense.texi - -mkinfodir = @${MKDIR_P} ${buildinfodir} - -.PHONY: info dvi pdf ps - -.SUFFIXES: .ps .dvi - -.dvi.ps: - $(DVIPS) -o $@ $< - -info: $(buildinfodir)/elisp$(INFO_EXT) -dvi: $(DVI_TARGETS) -html: $(HTML_TARGETS) -pdf: $(PDF_TARGETS) -ps: $(PS_TARGETS) - -## Note: "<" is not portable in ordinary make rules. -$(buildinfodir)/elisp$(INFO_EXT): $(srcs) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $(srcdir)/elisp.texi - -elisp.dvi: $(srcs) - $(ENVADD) $(TEXI2DVI) $(srcdir)/elisp.texi - -elisp.html: $(srcs) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $(srcdir)/elisp.texi - -elisp.pdf: $(srcs) - $(ENVADD) $(TEXI2PDF) $(srcdir)/elisp.texi - -.PHONY: mostlyclean clean distclean maintainer-clean infoclean - -## [12] stuff is from two-volume.make. -mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs - rm -f elisp[12]* vol[12].tmp - -clean: mostlyclean - rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) - rm -f vol[12].dvi vol[12].pdf vol[12].ps - rm -f emacs-lispref-${version}.tar* - -distclean: clean - rm -f Makefile - -infoclean: - -cd $(buildinfodir) && rm -f elisp$(INFO_EXT) elisp$(INFO_EXT)-[1-9] elisp$(INFO_EXT)-[1-9][0-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -## Note this excludes the two-volume stuff. -dist: - rm -rf emacs-lispref-${version} - mkdir emacs-lispref-${version} - cp ${srcdir}/*.texi ${texinfodir}/texinfo.tex \ - $(emacsdir)/emacsver.texi ${srcdir}/ChangeLog* \ - ${srcdir}/README emacs-lispref-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(emacsdir *=\).*/\1 ./' \ - -e 's/^\(buildinfodir *=\).*/\1 ./' \ - -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \ - -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \ - -e 's|@SH[E]LL@|/bin/bash|' \ - -e 's|@[p]refix@|/usr/local|' \ - -e 's|@[d]atarootdir@|$${prefix}/share|' \ - -e 's|@[d]atadir@|$${datarootdir}|' \ - -e 's|@[P]ACKAGE_TARNAME@|emacs|' \ - -e 's|@[d]ocdir@|$${datarootdir}/doc/$${PACKAGE_TARNAME}|' \ - -e 's|@[d]vidir@|$${docdir}|' \ - -e 's|@[h]tmldir@|$${docdir}|' \ - -e 's|@[p]dfdir@|$${docdir}|' \ - -e 's|@[p]sdir@|$${docdir}|' \ - -e 's|@[G]ZIP_PROG@|gzip|' \ - -e 's|@IN[S]TALL@|install -c|' \ - -e 's|@IN[S]TALL_DATA@|$${INSTALL} -m 644|' \ - -e '/@[c]onfigure_input@/d' \ - ${srcdir}/Makefile.in > emacs-lispref-${version}/Makefile - @if grep '@[a-zA-Z_]*@' emacs-lispref-${version}/Makefile; then \ - echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \ - fi - tar -cf emacs-lispref-${version}.tar emacs-lispref-${version} - rm -rf emacs-lispref-${version} - -.PHONY: install-dvi install-html install-pdf install-ps install-doc - -install-dvi: dvi - umask 022; $(MKDIR_P) "$(DESTDIR)$(dvidir)" - $(INSTALL_DATA) $(DVI_TARGETS) "$(DESTDIR)$(dvidir)" -install-html: html - umask 022; $(MKDIR_P) "$(DESTDIR)$(htmldir)" - $(INSTALL_DATA) $(HTML_TARGETS) "$(DESTDIR)$(htmldir)" -install-pdf: pdf - umask 022;$(MKDIR_P) "$(DESTDIR)$(pdfdir)" - $(INSTALL_DATA) $(PDF_TARGETS) "$(DESTDIR)$(pdfdir)" -install-ps: ps - umask 022; $(MKDIR_P) "$(DESTDIR)$(psdir)" - for file in $(PS_TARGETS); do \ - $(INSTALL_DATA) $${file} "$(DESTDIR)$(psdir)"; \ - [ -n "${GZIP_PROG}" ] || continue; \ - rm -f "$(DESTDIR)$(psdir)/$${file}.gz"; \ - ${GZIP_PROG} -9n "$(DESTDIR)$(psdir)/$${file}"; \ - done - -## Top-level Makefile installs the info pages. -install-doc: install-dvi install-html install-pdf install-ps - - -.PHONY: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps uninstall-doc - -uninstall-dvi: - for file in $(DVI_TARGETS); do \ - rm -f "$(DESTDIR)$(dvidir)/$${file}"; \ - done -uninstall-html: - for file in $(HTML_TARGETS); do \ - rm -f "$(DESTDIR)$(htmldir)/$${file}"; \ - done -uninstall-ps: - ext= ; [ -n "${GZIP_PROG}" ] && ext=.gz; \ - for file in $(PS_TARGETS); do \ - rm -f "$(DESTDIR)$(psdir)/$${file}$${ext}"; \ - done -uninstall-pdf: - for file in $(PDF_TARGETS); do \ - rm -f "$(DESTDIR)$(pdfdir)/$${file}"; \ - done - -uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps - - -### Makefile ends here diff --git a/doc/lispref/README b/doc/lispref/README deleted file mode 100644 index e8dbaddde56..00000000000 --- a/doc/lispref/README +++ /dev/null @@ -1,48 +0,0 @@ -Copyright (C) 2001-2014 Free Software Foundation, Inc. -*- outline -*- -See the end of the file for license conditions. - - -README for the Emacs Lisp Reference Manual. - -* This directory contains the texinfo source files for the Emacs Lisp -Reference Manual. - -* Report bugs in the Lisp Manual (or in Emacs) using M-x report-emacs-bug. -To ask questions, use the help-gnu-emacs mailing list. - -* The Emacs Lisp Reference Manual is quite large. It totals around -1100 pages in smallbook format; the info files total around 3.0 megabytes. - -* You can format this manual for Info, for printing hardcopy using TeX, -or for HTML. - -* You can buy nicely printed copies from the Free Software Foundation. -Buying a manual from the Free Software Foundation helps support our GNU -development work. See . -(At time of writing, this manual is out of print.) - -* The master file for formatting this manual for Tex is called `elisp.texi'. -It contains @include commands to include all the chapters that make up -the manual. - -* This distribution contains a Makefile that you can use with GNU Make. - -** To make an Info file, you need to install Texinfo, then run `make info'. - -** Use `make elisp.pdf' or `make elisp.html' to create PDF or HTML versions. - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi deleted file mode 100644 index 73a3f5f1e05..00000000000 --- a/doc/lispref/abbrevs.texi +++ /dev/null @@ -1,497 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1999, 2001-2014 Free Software Foundation, -@c Inc. -@c See the file elisp.texi for copying conditions. -@node Abbrevs -@chapter Abbrevs and Abbrev Expansion -@cindex abbrev -@c @cindex abbrev table Redundant with "abbrev". - - An abbreviation or @dfn{abbrev} is a string of characters that may be -expanded to a longer string. The user can insert the abbrev string and -find it replaced automatically with the expansion of the abbrev. This -saves typing. - - The set of abbrevs currently in effect is recorded in an @dfn{abbrev -table}. Each buffer has a local abbrev table, but normally all buffers -in the same major mode share one abbrev table. There is also a global -abbrev table. Normally both are used. - - An abbrev table is represented as an obarray. @xref{Creating -Symbols}, for information about obarrays. Each abbreviation is -represented by a symbol in the obarray. The symbol's name is the -abbreviation; its value is the expansion; its function definition is -the hook function for performing the expansion (@pxref{Defining -Abbrevs}); and its property list cell contains various additional -properties, including the use count and the number of times the -abbreviation has been expanded (@pxref{Abbrev Properties}). - -@cindex system abbrev - Certain abbrevs, called @dfn{system abbrevs}, are defined by a major -mode instead of the user. A system abbrev is identified by its -non-@code{nil} @code{:system} property (@pxref{Abbrev Properties}). -When abbrevs are saved to an abbrev file, system abbrevs are omitted. -@xref{Abbrev Files}. - - Because the symbols used for abbrevs are not interned in the usual -obarray, they will never appear as the result of reading a Lisp -expression; in fact, normally they are never used except by the code -that handles abbrevs. Therefore, it is safe to use them in a -nonstandard way. - - If the minor mode Abbrev mode is enabled, the buffer-local variable -@code{abbrev-mode} is non-@code{nil}, and abbrevs are automatically -expanded in the buffer. For the user-level commands for abbrevs, see -@ref{Abbrevs,, Abbrev Mode, emacs, The GNU Emacs Manual}. - -@menu -* Tables: Abbrev Tables. Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Files: Abbrev Files. Saving abbrevs in files. -* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. -@end menu - -@node Abbrev Tables -@section Abbrev Tables - - This section describes how to create and manipulate abbrev tables. - -@defun make-abbrev-table &optional props -This function creates and returns a new, empty abbrev table---an -obarray containing no symbols. It is a vector filled with zeros. -@var{props} is a property list that is applied to the new table -(@pxref{Abbrev Table Properties}). -@end defun - -@defun abbrev-table-p object -This function returns a non-@code{nil} value if @var{object} is an -abbrev table. -@end defun - -@defun clear-abbrev-table abbrev-table -This function undefines all the abbrevs in @var{abbrev-table}, leaving -it empty. -@c Don't see why this needs saying. -@c It always returns @code{nil}. -@end defun - -@defun copy-abbrev-table abbrev-table -This function returns a copy of @var{abbrev-table}---a new abbrev -table containing the same abbrev definitions. It does @emph{not} copy -any property lists; only the names, values, and functions. -@end defun - -@defun define-abbrev-table tabname definitions &optional docstring &rest props -This function defines @var{tabname} (a symbol) as an abbrev table -name, i.e., as a variable whose value is an abbrev table. It defines -abbrevs in the table according to @var{definitions}, a list of -elements of the form @code{(@var{abbrevname} @var{expansion} -[@var{hook}] [@var{props}...])}. These elements are passed as -arguments to @code{define-abbrev}. @c The return value is always @code{nil}. - -The optional string @var{docstring} is the documentation string of the -variable @var{tabname}. The property list @var{props} is applied to -the abbrev table (@pxref{Abbrev Table Properties}). - -If this function is called more than once for the same @var{tabname}, -subsequent calls add the definitions in @var{definitions} to -@var{tabname}, rather than overwriting the entire original contents. -(A subsequent call only overrides abbrevs explicitly redefined or -undefined in @var{definitions}.) -@end defun - -@defvar abbrev-table-name-list -This is a list of symbols whose values are abbrev tables. -@code{define-abbrev-table} adds the new abbrev table name to this list. -@end defvar - -@defun insert-abbrev-table-description name &optional human -This function inserts before point a description of the abbrev table -named @var{name}. The argument @var{name} is a symbol whose value is an -abbrev table. @c The return value is always @code{nil}. - -If @var{human} is non-@code{nil}, the description is human-oriented. -System abbrevs are listed and identified as such. Otherwise the -description is a Lisp expression---a call to @code{define-abbrev-table} -that would define @var{name} as it is currently defined, but without -the system abbrevs. (The mode or package using @var{name} is supposed -to add these to @var{name} separately.) -@end defun - -@node Defining Abbrevs -@section Defining Abbrevs - - @code{define-abbrev} is the low-level basic function for defining an -abbrev in an abbrev table. - - When a major mode defines a system abbrev, it should call -@code{define-abbrev} and specify @code{t} for the @code{:system} -property. Be aware that any saved non-``system'' abbrevs are restored -at startup, i.e., before some major modes are loaded. Therefore, major -modes should not assume that their abbrev tables are empty when they -are first loaded. - -@defun define-abbrev abbrev-table name expansion &optional hook &rest props -This function defines an abbrev named @var{name}, in -@var{abbrev-table}, to expand to @var{expansion} and call @var{hook}, -with properties @var{props} (@pxref{Abbrev Properties}). The return -value is @var{name}. The @code{:system} property in @var{props} is -treated specially here: if it has the value @code{force}, then it will -overwrite an existing definition even for a non-``system'' abbrev of -the same name. - -@var{name} should be a string. The argument @var{expansion} is -normally the desired expansion (a string), or @code{nil} to undefine -the abbrev. If it is anything but a string or @code{nil}, then the -abbreviation ``expands'' solely by running @var{hook}. - -The argument @var{hook} is a function or @code{nil}. If @var{hook} is -non-@code{nil}, then it is called with no arguments after the abbrev is -replaced with @var{expansion}; point is located at the end of -@var{expansion} when @var{hook} is called. - -@cindex @code{no-self-insert} property -If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert} -property is non-@code{nil}, @var{hook} can explicitly control whether -to insert the self-inserting input character that triggered the -expansion. If @var{hook} returns non-@code{nil} in this case, that -inhibits insertion of the character. By contrast, if @var{hook} -returns @code{nil}, @code{expand-abbrev} (or @code{abbrev-insert}) -also returns @code{nil}, as if expansion had not really occurred. - -Normally, @code{define-abbrev} sets the variable -@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev. -This is so that some commands will offer to save the abbrevs. It -does not do this for a system abbrev, since those aren't saved anyway. -@end defun - -@defopt only-global-abbrevs -If this variable is non-@code{nil}, it means that the user plans to use -global abbrevs only. This tells the commands that define mode-specific -abbrevs to define global ones instead. This variable does not alter the -behavior of the functions in this section; it is examined by their -callers. -@end defopt - -@node Abbrev Files -@section Saving Abbrevs in Files - - A file of saved abbrev definitions is actually a file of Lisp code. -The abbrevs are saved in the form of a Lisp program to define the same -abbrev tables with the same contents. Therefore, you can load the file -with @code{load} (@pxref{How Programs Do Loading}). However, the -function @code{quietly-read-abbrev-file} is provided as a more -convenient interface. Emacs automatically calls this function at -startup. - - User-level facilities such as @code{save-some-buffers} can save -abbrevs in a file automatically, under the control of variables -described here. - -@defopt abbrev-file-name -This is the default file name for reading and saving abbrevs. -@end defopt - -@defun quietly-read-abbrev-file &optional filename -This function reads abbrev definitions from a file named @var{filename}, -previously written with @code{write-abbrev-file}. If @var{filename} is -omitted or @code{nil}, the file specified in @code{abbrev-file-name} is -used. - -As the name implies, this function does not display any messages. -@c It returns @code{nil}. -@end defun - -@defopt save-abbrevs -A non-@code{nil} value for @code{save-abbrevs} means that Emacs should -offer to save abbrevs (if any have changed) when files are saved. If -the value is @code{silently}, Emacs saves the abbrevs without asking -the user. @code{abbrev-file-name} specifies the file to save the -abbrevs in. -@end defopt - -@defvar abbrevs-changed -This variable is set non-@code{nil} by defining or altering any -abbrevs (except system abbrevs). This serves as a flag for various -Emacs commands to offer to save your abbrevs. -@end defvar - -@deffn Command write-abbrev-file &optional filename -Save all abbrev definitions (except system abbrevs), for all abbrev -tables listed in @code{abbrev-table-name-list}, in the file -@var{filename}, in the form of a Lisp program that when loaded will -define the same abbrevs. If @var{filename} is @code{nil} or omitted, -@code{abbrev-file-name} is used. This function returns @code{nil}. -@end deffn - -@node Abbrev Expansion -@section Looking Up and Expanding Abbreviations - - Abbrevs are usually expanded by certain interactive commands, -including @code{self-insert-command}. This section describes the -subroutines used in writing such commands, as well as the variables they -use for communication. - -@defun abbrev-symbol abbrev &optional table -This function returns the symbol representing the abbrev named -@var{abbrev}. It returns @code{nil} if that abbrev is not -defined. The optional second argument @var{table} is the abbrev table -in which to look it up. If @var{table} is @code{nil}, this function -tries first the current buffer's local abbrev table, and second the -global abbrev table. -@end defun - -@defun abbrev-expansion abbrev &optional table -This function returns the string that @var{abbrev} would expand into (as -defined by the abbrev tables used for the current buffer). It returns -@code{nil} if @var{abbrev} is not a valid abbrev. -The optional argument @var{table} specifies the abbrev table to use, -as in @code{abbrev-symbol}. -@end defun - -@deffn Command expand-abbrev -This command expands the abbrev before point, if any. If point does not -follow an abbrev, this command does nothing. To do the expansion, it -calls the function that is the value of the @code{abbrev-expand-function} -variable, with no arguments, and returns whatever that function does. - -The default expansion function returns the abbrev symbol if it did -expansion, and @code{nil} otherwise. If the abbrev symbol has a hook -function that is a symbol whose @code{no-self-insert} property is -non-@code{nil}, and if the hook function returns @code{nil} as its -value, then the default expansion function returns @code{nil}, -even though expansion did occur. -@end deffn - -@defun abbrev-insert abbrev &optional name start end -This function inserts the abbrev expansion of @code{abbrev}, replacing -the text between @code{start} and @code{end}. If @code{start} is -omitted, it defaults to point. @code{name}, if non-@code{nil}, should -be the name by which this abbrev was found (a string); it is used to -figure out whether to adjust the capitalization of the expansion. The -function returns @code{abbrev} if the abbrev was successfully -inserted. -@end defun - -@deffn Command abbrev-prefix-mark &optional arg -This command marks the current location of point as the beginning of -an abbrev. The next call to @code{expand-abbrev} will use the text -from here to point (where it is then) as the abbrev to expand, rather -than using the previous word as usual. - -First, this command expands any abbrev before point, unless @var{arg} -is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.) -Then it inserts a hyphen before point, to indicate the start of the -next abbrev to be expanded. The actual expansion removes the hyphen. -@end deffn - -@defopt abbrev-all-caps -When this is set non-@code{nil}, an abbrev entered entirely in upper -case is expanded using all upper case. Otherwise, an abbrev entered -entirely in upper case is expanded by capitalizing each word of the -expansion. -@end defopt - -@defvar abbrev-start-location -The value of this variable is a buffer position (an integer or a marker) -for @code{expand-abbrev} to use as the start of the next abbrev to be -expanded. The value can also be @code{nil}, which means to use the -word before point instead. @code{abbrev-start-location} is set to -@code{nil} each time @code{expand-abbrev} is called. This variable is -also set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar abbrev-start-location-buffer -The value of this variable is the buffer for which -@code{abbrev-start-location} has been set. Trying to expand an abbrev -in any other buffer clears @code{abbrev-start-location}. This variable -is set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar last-abbrev -This is the @code{abbrev-symbol} of the most recent abbrev expanded. This -information is left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding -Abbrevs, emacs, The GNU Emacs Manual}). -@end defvar - -@defvar last-abbrev-location -This is the location of the most recent abbrev expanded. This contains -information left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command. -@end defvar - -@defvar last-abbrev-text -This is the exact expansion text of the most recent abbrev expanded, -after case conversion (if any). Its value is @code{nil} if the abbrev -has already been unexpanded. This contains information left by -@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. -@end defvar - -@defvar abbrev-expand-function -The value of this variable is a function that @code{expand-abbrev} -will call with no arguments to do the expansion. The function can do -anything it wants before and after performing the expansion. -It should return the abbrev symbol if expansion took place. -@end defvar - - The following sample code shows a simple use of -@code{abbrev-expand-function}. It assumes that @code{foo-mode} is a -mode for editing certain files in which lines that start with @samp{#} -are comments. You want to use Text mode abbrevs for those lines. The -regular local abbrev table, @code{foo-mode-abbrev-table} is -appropriate for all other lines. @xref{Standard Abbrev Tables}, for the -definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. -@xref{Advising Functions}, for details of @code{add-function}. - -@smallexample -(defun foo-mode-abbrev-expand-function (expand) - (if (not (save-excursion (forward-line 0) (eq (char-after) ?#))) - ;; Performs normal expansion. - (funcall expand) - ;; We're inside a comment: use the text-mode abbrevs. - (let ((local-abbrev-table text-mode-abbrev-table)) - (funcall expand)))) - -(add-hook 'foo-mode-hook - #'(lambda () - (add-function :around (local 'abbrev-expand-function) - #'foo-mode-abbrev-expand-function))) -@end smallexample - -@node Standard Abbrev Tables -@section Standard Abbrev Tables - - Here we list the variables that hold the abbrev tables for the -preloaded major modes of Emacs. - -@defvar global-abbrev-table -This is the abbrev table for mode-independent abbrevs. The abbrevs -defined in it apply to all buffers. Each buffer may also have a local -abbrev table, whose abbrev definitions take precedence over those in the -global table. -@end defvar - -@defvar local-abbrev-table -The value of this buffer-local variable is the (mode-specific) -abbreviation table of the current buffer. It can also be a list of -such tables. -@end defvar - -@defvar abbrev-minor-mode-table-alist -The value of this variable is a list of elements of the form -@code{(@var{mode} . @var{abbrev-table})} where @var{mode} is the name -of a variable: if the variable is bound to a non-@code{nil} value, -then the @var{abbrev-table} is active, otherwise it is ignored. -@var{abbrev-table} can also be a list of abbrev tables. -@end defvar - -@defvar fundamental-mode-abbrev-table -This is the local abbrev table used in Fundamental mode; in other words, -it is the local abbrev table in all buffers in Fundamental mode. -@end defvar - -@defvar text-mode-abbrev-table -This is the local abbrev table used in Text mode. -@end defvar - -@defvar lisp-mode-abbrev-table -This is the local abbrev table used in Lisp mode. It is the parent -of the local abbrev table used in Emacs Lisp mode. @xref{Abbrev Table -Properties}. -@end defvar - -@node Abbrev Properties -@section Abbrev Properties - -Abbrevs have properties, some of which influence the way they work. -You can provide them as arguments to @code{define-abbrev}, and -manipulate them with the following functions: - -@defun abbrev-put abbrev prop val -Set the property @var{prop} of @var{abbrev} to value @var{val}. -@end defun - -@defun abbrev-get abbrev prop -Return the property @var{prop} of @var{abbrev}, or @code{nil} if the -abbrev has no such property. -@end defun - -The following properties have special meanings: - -@table @code -@item :count -This property counts the number of times the abbrev has -been expanded. If not explicitly set, it is initialized to 0 by -@code{define-abbrev}. - -@item :system -If non-@code{nil}, this property marks the abbrev as a system abbrev. -Such abbrevs are not saved (@pxref{Abbrev Files}). - -@item :enable-function -If non-@code{nil}, this property should be a function of no -arguments which returns @code{nil} if the abbrev should not be used -and @code{t} otherwise. - -@item :case-fixed -If non-@code{nil}, this property indicates that the case of the -abbrev's name is significant and should only match a text with the -same pattern of capitalization. It also disables the code that -modifies the capitalization of the expansion. -@end table - -@node Abbrev Table Properties -@section Abbrev Table Properties - -Like abbrevs, abbrev tables have properties, some of which influence -the way they work. You can provide them as arguments to -@code{define-abbrev-table}, and manipulate them with the functions: - -@defun abbrev-table-put table prop val -Set the property @var{prop} of abbrev table @var{table} to value @var{val}. -@end defun - -@defun abbrev-table-get table prop -Return the property @var{prop} of abbrev table @var{table}, or @code{nil} -if the abbrev has no such property. -@end defun - -The following properties have special meaning: - -@table @code -@item :enable-function -This is like the @code{:enable-function} abbrev property except that -it applies to all abbrevs in the table. It is used before even trying -to find the abbrev before point, so it can dynamically modify the -abbrev table. - -@item :case-fixed -This is like the @code{:case-fixed} abbrev property except that it -applies to all abbrevs in the table. - -@item :regexp -If non-@code{nil}, this property is a regular expression that -indicates how to extract the name of the abbrev before point, before -looking it up in the table. When the regular expression matches -before point, the abbrev name is expected to be in submatch 1. -If this property is @code{nil}, the default is to use -@code{backward-word} and @code{forward-word} to find the name. This -property allows the use of abbrevs whose name contains characters of -non-word syntax. - -@item :parents -This property holds a list of tables from which to inherit -other abbrevs. - -@item :abbrev-table-modiff -This property holds a counter incremented each time a new abbrev is -added to the table. - -@end table diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi deleted file mode 100644 index 2ca2290a022..00000000000 --- a/doc/lispref/anti.texi +++ /dev/null @@ -1,139 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2002-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. - -@c This node must have no pointers. - -@node Antinews -@appendix Emacs 23 Antinews -@c Update the elisp.texi Antinews menu entry with the above version number. - -For those users who live backwards in time, here is information about -downgrading to Emacs version 23.4. We hope you will enjoy the greater -simplicity that results from the absence of many Emacs @value{EMACSVER} -features. - -@section Old Lisp Features in Emacs 23 - -@itemize @bullet -@item -Support for lexical scoping has been removed; all variables are -dynamically scoped. The @code{lexical-binding} variable has been -removed, and so has the @var{lexical} argument to @code{eval}. The -@code{defvar} and @code{defconst} forms no longer mark variables as -dynamic, since all variables are dynamic. - -Having only dynamic binding follows the spirit of Emacs extensibility, -for it allows any Emacs code to access any defined variable with a -minimum of fuss. But @xref{Dynamic Binding Tips}, for tips to avoid -making your programs hard to understand. - -@item -Calling a minor mode function from Lisp with a @code{nil} or omitted argument -does not enable the minor mode unconditionally; instead, it toggles -the minor mode---which is the straightforward thing to do, since that -is the behavior when invoked interactively. One downside is that it -is more troublesome to enable minor modes from hooks; you have to do -something like - -@example -(add-hook 'foo-hook (lambda () (bar-mode 1))) -@end example - -@noindent -or define @code{turn-on-bar-mode} and call that from the hook. - -@item -The @code{prog-mode} dummy major mode has been removed. Instead of -using it as a crutch to meet programming mode conventions, you should -explicitly ensure that your mode follows those conventions. -@xref{Major Mode Conventions}. - -@item -Emacs no longer supports bidirectional display and editing. Since -there is no need to worry about the insertion of right-to-left text -messing up how lines and paragraphs are displayed, the function -@code{bidi-string-mark-left-to-right} has been removed; so have many -other functions and variables related to bidirectional display. -Unicode directionality characters like @code{U+200E} ("left-to-right -mark") have no special effect on display. - -@item -Emacs windows now have most of their internal state hidden from Lisp. -Internal windows are no longer visible to Lisp; functions such as -@code{window-parent}, window parameters related to window arrangement, -and window-local buffer lists have all been removed. Functions for -resizing windows can delete windows if they become too small. - -The ``action function'' feature for controlling buffer display has -been removed, including @code{display-buffer-overriding-action} and -related variables, as well as the @var{action} argument to -@code{display-buffer} and other functions. The way to -programmatically control how Emacs chooses a window to display a -buffer is to bind the right combination of @code{pop-up-frames} and -other variables. - -@item -The standard completion interface has been simplified, eliminating the -@code{completion-extra-properties} variable, the @code{metadata} -action flag for completion functions, and the concept of -``completion categories''. Lisp programmers may now find the choice -of methods for tuning completion less bewildering, but if a package -finds the streamlined interface insufficient for its needs, it must -implement its own specialized completion feature. - -@item -@code{copy-directory} now behaves the same whether or not the -destination is an existing directory: if the destination exists, the -@emph{contents} of the first directory are copied into it (with -subdirectories handled recursively), rather than copying the first -directory into a subdirectory. - -@item -The @var{trash} arguments for @code{delete-file} and -@code{delete-directory} have been removed. The variable -@code{delete-by-moving-to-trash} must now be used with care; whenever -it is non-@code{nil}, all calls to @code{delete-file} or -@code{delete-directory} use the trash. - -@item -Because Emacs no longer supports SELinux file contexts, the -@var{preserve-selinux-context} argument to @code{copy-file} has been -removed. The return value of @code{backup-buffer} no longer has an -entry for the SELinux file context. - -@item -For mouse click input events in the text area, the Y pixel coordinate -in the @var{position} list (@pxref{Click Events}) now counts from the -top of the header line, if there is one, rather than the top of the -text area. - -@item -Bindings in menu keymaps (@pxref{Format of Keymaps}) now sometimes get -an additional @var{cache} entry in their definitions, like this: - -@example -(@var{type} @var{item-name} @var{cache} . @var{binding}) -@end example - -@noindent -The @var{cache} entry is used internally by Emacs to record equivalent -keyboard key sequences for invoking the same command; Lisp programs -should never use it. -@c Not really NEWS-worthy then... - -@item -The @code{gnutls} library has been removed, and the function -@code{open-network-stream} correspondingly simplified. -Lisp programs that want an encrypted network connection must now call -external utilities such as @command{starttls} or @command{gnutls-cli}. - -@item -Tool bars can no longer display separators, which frees up several -pixels of space on each graphical frame. - -@item -As part of the ongoing quest for simplicity, many other functions and -variables have been eliminated. -@end itemize diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi deleted file mode 100644 index 177522e7b20..00000000000 --- a/doc/lispref/back.texi +++ /dev/null @@ -1,38 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@c %**start of header -@setfilename back-cover -@settitle GNU Emacs Lisp Reference Manual -@documentencoding UTF-8 -@c %**end of header -. -@sp 7 -@center @titlefont {GNU Emacs Lisp} -@sp 1 - -@quotation - Most of the GNU Emacs text editor is written in the programming -language called Emacs Lisp. You can write new code in Emacs Lisp and -install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming -language in its own right. You can use it as you would any other -programming language. - - Because Emacs Lisp is designed for use in an editor, it has special -features for scanning and parsing text as well as features for handling -files, buffers, displays, subprocesses, and so on. Emacs Lisp is -closely integrated with the editing facilities; thus, editing commands -are functions that can also conveniently be called from Lisp programs, -and parameters for customization are ordinary Lisp variables. - - This manual describes Emacs Lisp. Generally speaking, the earlier -chapters describe features of Emacs Lisp that have counterparts in -many programming languages, and later chapters describe features that -are peculiar to Emacs Lisp or relate specifically to editing. -@end quotation - -@hfil -@bye diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi deleted file mode 100644 index 63f8f227c84..00000000000 --- a/doc/lispref/backups.texi +++ /dev/null @@ -1,776 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1999, 2001-2014 Free Software Foundation, -@c Inc. -@c See the file elisp.texi for copying conditions. -@node Backups and Auto-Saving -@chapter Backups and Auto-Saving -@cindex backups and auto-saving - - Backup files and auto-save files are two methods by which Emacs tries -to protect the user from the consequences of crashes or of the user's -own errors. Auto-saving preserves the text from earlier in the current -editing session; backup files preserve file contents prior to the -current session. - -@menu -* Backup Files:: How backup files are made; how their names are chosen. -* Auto-Saving:: How auto-save files are made; how their names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize what it does. -@end menu - -@node Backup Files -@section Backup Files -@cindex backup file - - A @dfn{backup file} is a copy of the old contents of a file you are -editing. Emacs makes a backup file the first time you save a buffer -into its visited file. Thus, normally, the backup file contains the -contents of the file as it was before the current editing session. -The contents of the backup file normally remain unchanged once it -exists. - - Backups are usually made by renaming the visited file to a new name. -Optionally, you can specify that backup files should be made by copying -the visited file. This choice makes a difference for files with -multiple names; it also can affect whether the edited file remains owned -by the original owner or becomes owned by the user editing it. - - By default, Emacs makes a single backup file for each file edited. -You can alternatively request numbered backups; then each new backup -file gets a new name. You can delete old numbered backups when you -don't want them any more, or Emacs can delete them automatically. - -@menu -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. -@end menu - -@node Making Backups -@subsection Making Backup Files - -@defun backup-buffer - This function makes a backup of the file visited by the current -buffer, if appropriate. It is called by @code{save-buffer} before -saving the buffer the first time. - -If a backup was made by renaming, the return value is a cons cell of -the form (@var{modes} @var{extra-alist} @var{backupname}), where -@var{modes} are the mode bits of the original file, as returned by -@code{file-modes} (@pxref{Testing Accessibility}), @var{extra-alist} -is an alist describing the original file's extended attributes, as -returned by @code{file-extended-attributes} (@pxref{Extended -Attributes}), and @var{backupname} is the name of the backup. - -In all other cases (i.e., if a backup was made by copying or if no -backup was made), this function returns @code{nil}. -@end defun - -@defvar buffer-backed-up - This buffer-local variable says whether this buffer's file has -been backed up on account of this buffer. If it is non-@code{nil}, -the backup file has been written. Otherwise, the file should be backed -up when it is next saved (if backups are enabled). This is a -permanent local; @code{kill-all-local-variables} does not alter@tie{}it. -@end defvar - -@defopt make-backup-files -This variable determines whether or not to make backup files. If it -is non-@code{nil}, then Emacs creates a backup of each file when it is -saved for the first time---provided that @code{backup-inhibited} -is @code{nil} (see below). - -The following example shows how to change the @code{make-backup-files} -variable only in the Rmail buffers and not elsewhere. Setting it -@code{nil} stops Emacs from making backups of these files, which may -save disk space. (You would put this code in your init file.) - -@smallexample -@group -(add-hook 'rmail-mode-hook - (lambda () (setq-local make-backup-files nil))) -@end group -@end smallexample -@end defopt - -@defvar backup-enable-predicate -This variable's value is a function to be called on certain occasions to -decide whether a file should have backup files. The function receives -one argument, an absolute file name to consider. If the function returns -@code{nil}, backups are disabled for that file. Otherwise, the other -variables in this section say whether and how to make backups. - -@findex normal-backup-enable-predicate -The default value is @code{normal-backup-enable-predicate}, which checks -for files in @code{temporary-file-directory} and -@code{small-temporary-file-directory}. -@end defvar - -@defvar backup-inhibited -If this variable is non-@code{nil}, backups are inhibited. It records -the result of testing @code{backup-enable-predicate} on the visited file -name. It can also coherently be used by other mechanisms that inhibit -backups based on which file is visited. For example, VC sets this -variable non-@code{nil} to prevent making backups for files managed -with a version control system. - -This is a permanent local, so that changing the major mode does not lose -its value. Major modes should not set this variable---they should set -@code{make-backup-files} instead. -@end defvar - -@defopt backup-directory-alist -This variable's value is an alist of filename patterns and backup -directory names. Each element looks like -@smallexample -(@var{regexp} . @var{directory}) -@end smallexample - -@noindent -Backups of files with names matching @var{regexp} will be made in -@var{directory}. @var{directory} may be relative or absolute. If it is -absolute, so that all matching files are backed up into the same -directory, the file names in this directory will be the full name of the -file backed up with all directory separators changed to @samp{!} to -prevent clashes. This will not work correctly if your filesystem -truncates the resulting name. - -For the common case of all backups going into one directory, the alist -should contain a single element pairing @samp{"."} with the appropriate -directory name. - -If this variable is @code{nil} (the default), or it fails to match a -filename, the backup is made in the original file's directory. - -On MS-DOS filesystems without long names this variable is always -ignored. -@end defopt - -@defopt make-backup-file-name-function -This variable's value is a function to use for making backup file names. -The function @code{make-backup-file-name} calls it. -@xref{Backup Names,, Naming Backup Files}. - -This could be buffer-local to do something special for specific -files. If you change it, you may need to change -@code{backup-file-name-p} and @code{file-name-sans-versions} too. -@end defopt - - -@node Rename or Copy -@subsection Backup by Renaming or by Copying? -@cindex backup files, rename or copy - - There are two ways that Emacs can make a backup file: - -@itemize @bullet -@item -Emacs can rename the original file so that it becomes a backup file, and -then write the buffer being saved into a new file. After this -procedure, any other names (i.e., hard links) of the original file now -refer to the backup file. The new file is owned by the user doing the -editing, and its group is the default for new files written by the user -in that directory. - -@item -Emacs can copy the original file into a backup file, and then overwrite -the original file with new contents. After this procedure, any other -names (i.e., hard links) of the original file continue to refer to the -current (updated) version of the file. The file's owner and group will -be unchanged. -@end itemize - - The first method, renaming, is the default. - - The variable @code{backup-by-copying}, if non-@code{nil}, says to use -the second method, which is to copy the original file and overwrite it -with the new buffer contents. The variable @code{file-precious-flag}, -if non-@code{nil}, also has this effect (as a sideline of its main -significance). @xref{Saving Buffers}. - -@defopt backup-by-copying -If this variable is non-@code{nil}, Emacs always makes backup files by -copying. The default is @code{nil}. -@end defopt - - The following three variables, when non-@code{nil}, cause the second -method to be used in certain special cases. They have no effect on the -treatment of files that don't fall into the special cases. - -@defopt backup-by-copying-when-linked -If this variable is non-@code{nil}, Emacs makes backups by copying for -files with multiple names (hard links). The default is @code{nil}. - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defopt - -@defopt backup-by-copying-when-mismatch -If this variable is non-@code{nil} (the default), Emacs makes backups -by copying in cases where renaming would change either the owner or -the group of the file. - -The value has no effect when renaming would not alter the owner or -group of the file; that is, for files which are owned by the user and -whose group matches the default for a new file created there by the -user. - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defopt - -@defopt backup-by-copying-when-privileged-mismatch -This variable, if non-@code{nil}, specifies the same behavior as -@code{backup-by-copying-when-mismatch}, but only for certain user-id -values: namely, those less than or equal to a certain number. You set -this variable to that number. - -Thus, if you set @code{backup-by-copying-when-privileged-mismatch} -to 0, backup by copying is done for the superuser only, -when necessary to prevent a change in the owner of the file. - -The default is 200. -@end defopt - -@node Numbered Backups -@subsection Making and Deleting Numbered Backup Files - - If a file's name is @file{foo}, the names of its numbered backup -versions are @file{foo.~@var{v}~}, for various integers @var{v}, like -this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{}, -@file{foo.~259~}, and so on. - -@defopt version-control -This variable controls whether to make a single non-numbered backup -file or multiple numbered backups. - -@table @asis -@item @code{nil} -Make numbered backups if the visited file already has numbered backups; -otherwise, do not. This is the default. - -@item @code{never} -Do not make numbered backups. - -@item @var{anything else} -Make numbered backups. -@end table -@end defopt - - The use of numbered backups ultimately leads to a large number of -backup versions, which must then be deleted. Emacs can do this -automatically or it can ask the user whether to delete them. - -@defopt kept-new-versions -The value of this variable is the number of newest versions to keep -when a new numbered backup is made. The newly made backup is included -in the count. The default value is@tie{}2. -@end defopt - -@defopt kept-old-versions -The value of this variable is the number of oldest versions to keep -when a new numbered backup is made. The default value is@tie{}2. -@end defopt - - If there are backups numbered 1, 2, 3, 5, and 7, and both of these -variables have the value 2, then the backups numbered 1 and 2 are kept -as old versions and those numbered 5 and 7 are kept as new versions; -backup version 3 is excess. The function @code{find-backup-file-name} -(@pxref{Backup Names}) is responsible for determining which backup -versions to delete, but does not delete them itself. - -@defopt delete-old-versions -If this variable is @code{t}, then saving a file deletes excess -backup versions silently. If it is @code{nil}, that means -to ask for confirmation before deleting excess backups. -Otherwise, they are not deleted at all. -@end defopt - -@defopt dired-kept-versions -This variable specifies how many of the newest backup versions to keep -in the Dired command @kbd{.} (@code{dired-clean-directory}). That's the -same thing @code{kept-new-versions} specifies when you make a new backup -file. The default is@tie{}2. -@end defopt - -@node Backup Names -@subsection Naming Backup Files - - The functions in this section are documented mainly because you can -customize the naming conventions for backup files by redefining them. -If you change one, you probably need to change the rest. - -@defun backup-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -possible name for a backup file. It just checks the name, not whether -a file with the name @var{filename} exists. - -@smallexample -@group -(backup-file-name-p "foo") - @result{} nil -@end group -@group -(backup-file-name-p "foo~") - @result{} 3 -@end group -@end smallexample - -The standard definition of this function is as follows: - -@smallexample -@group -(defun backup-file-name-p (file) - "Return non-nil if FILE is a backup file \ -name (numeric or not)..." - (string-match "~\\'" file)) -@end group -@end smallexample - -@noindent -Thus, the function returns a non-@code{nil} value if the file name ends -with a @samp{~}. (We use a backslash to split the documentation -string's first line into two lines in the text, but produce just one -line in the string itself.) - -This simple expression is placed in a separate function to make it easy -to redefine for customization. -@end defun - -@defun make-backup-file-name filename -This function returns a string that is the name to use for a -non-numbered backup file for file @var{filename}. On Unix, this is just -@var{filename} with a tilde appended. - -The standard definition of this function, on most operating systems, is -as follows: - -@smallexample -@group -(defun make-backup-file-name (file) - "Create the non-numeric backup file name for FILE..." - (concat file "~")) -@end group -@end smallexample - -You can change the backup-file naming convention by redefining this -function. The following example redefines @code{make-backup-file-name} -to prepend a @samp{.} in addition to appending a tilde: - -@smallexample -@group -(defun make-backup-file-name (filename) - (expand-file-name - (concat "." (file-name-nondirectory filename) "~") - (file-name-directory filename))) -@end group - -@group -(make-backup-file-name "backups.texi") - @result{} ".backups.texi~" -@end group -@end smallexample - -Some parts of Emacs, including some Dired commands, assume that backup -file names end with @samp{~}. If you do not follow that convention, it -will not cause serious problems, but these commands may give -less-than-desirable results. -@end defun - -@defun find-backup-file-name filename -This function computes the file name for a new backup file for -@var{filename}. It may also propose certain existing backup files for -deletion. @code{find-backup-file-name} returns a list whose @sc{car} is -the name for the new backup file and whose @sc{cdr} is a list of backup -files whose deletion is proposed. The value can also be @code{nil}, -which means not to make a backup. - -Two variables, @code{kept-old-versions} and @code{kept-new-versions}, -determine which backup versions should be kept. This function keeps -those versions by excluding them from the @sc{cdr} of the value. -@xref{Numbered Backups}. - -In this example, the value says that @file{~rms/foo.~5~} is the name -to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess'' -version that the caller should consider deleting now. - -@smallexample -@group -(find-backup-file-name "~rms/foo") - @result{} ("~rms/foo.~5~" "~rms/foo.~3~") -@end group -@end smallexample -@end defun - -@c Emacs 19 feature -@defun file-newest-backup filename -This function returns the name of the most recent backup file for -@var{filename}, or @code{nil} if that file has no backup files. - -Some file comparison commands use this function so that they can -automatically compare a file with its most recent backup. -@end defun - -@node Auto-Saving -@section Auto-Saving -@c @cindex auto-saving Lots of symbols starting with auto-save here. - - Emacs periodically saves all files that you are visiting; this is -called @dfn{auto-saving}. Auto-saving prevents you from losing more -than a limited amount of work if the system crashes. By default, -auto-saves happen every 300 keystrokes, or after around 30 seconds of -idle time. @xref{Auto Save, Auto Save, Auto-Saving: Protection Against -Disasters, emacs, The GNU Emacs Manual}, for information on auto-save -for users. Here we describe the functions used to implement auto-saving -and the variables that control them. - -@defvar buffer-auto-save-file-name -This buffer-local variable is the name of the file used for -auto-saving the current buffer. It is @code{nil} if the buffer -should not be auto-saved. - -@example -@group -buffer-auto-save-file-name - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@end example -@end defvar - -@deffn Command auto-save-mode arg -This is the mode command for Auto Save mode, a buffer-local minor -mode. When Auto Save mode is enabled, auto-saving is enabled in the -buffer. The calling convention is the same as for other minor mode -commands (@pxref{Minor Mode Conventions}). - -Unlike most minor modes, there is no @code{auto-save-mode} variable. -Auto Save mode is enabled if @code{buffer-auto-save-file-name} is -non-@code{nil} and @code{buffer-saved-size} (see below) is non-zero. -@end deffn - -@defun auto-save-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -string that could be the name of an auto-save file. It assumes -the usual naming convention for auto-save files: a name that -begins and ends with hash marks (@samp{#}) is a possible auto-save file -name. The argument @var{filename} should not contain a directory part. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@group -(auto-save-file-name-p "#backups.texi#") - @result{} 0 -@end group -@group -(auto-save-file-name-p "backups.texi") - @result{} nil -@end group -@end example - -The standard definition of this function is as follows: - -@example -@group -(defun auto-save-file-name-p (filename) - "Return non-nil if FILENAME can be yielded by..." - (string-match "^#.*#$" filename)) -@end group -@end example - -This function exists so that you can customize it if you wish to -change the naming convention for auto-save files. If you redefine it, -be sure to redefine the function @code{make-auto-save-file-name} -correspondingly. -@end defun - -@defun make-auto-save-file-name -This function returns the file name to use for auto-saving the current -buffer. This is just the file name with hash marks (@samp{#}) prepended -and appended to it. This function does not look at the variable -@code{auto-save-visited-file-name} (described below); callers of this -function should check that variable first. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@end example - -Here is a simplified version of the standard definition of this -function: - -@example -@group -(defun make-auto-save-file-name () - "Return file name to use for auto-saves \ -of current buffer.." - (if buffer-file-name -@end group -@group - (concat - (file-name-directory buffer-file-name) - "#" - (file-name-nondirectory buffer-file-name) - "#") - (expand-file-name - (concat "#%" (buffer-name) "#")))) -@end group -@end example - -This exists as a separate function so that you can redefine it to -customize the naming convention for auto-save files. Be sure to -change @code{auto-save-file-name-p} in a corresponding way. -@end defun - -@defopt auto-save-visited-file-name -If this variable is non-@code{nil}, Emacs auto-saves buffers in -the files they are visiting. That is, the auto-save is done in the same -file that you are editing. Normally, this variable is @code{nil}, so -auto-save files have distinct names that are created by -@code{make-auto-save-file-name}. - -When you change the value of this variable, the new value does not take -effect in an existing buffer until the next time auto-save mode is -reenabled in it. If auto-save mode is already enabled, auto-saves -continue to go in the same file name until @code{auto-save-mode} is -called again. -@end defopt - -@defun recent-auto-save-p -This function returns @code{t} if the current buffer has been -auto-saved since the last time it was read in or saved. -@end defun - -@defun set-buffer-auto-saved -This function marks the current buffer as auto-saved. The buffer will -not be auto-saved again until the buffer text is changed again. The -function returns @code{nil}. -@end defun - -@defopt auto-save-interval -The value of this variable specifies how often to do auto-saving, in -terms of number of input events. Each time this many additional input -events are read, Emacs does auto-saving for all buffers in which that is -enabled. Setting this to zero disables autosaving based on the -number of characters typed. -@end defopt - -@defopt auto-save-timeout -The value of this variable is the number of seconds of idle time that -should cause auto-saving. Each time the user pauses for this long, -Emacs does auto-saving for all buffers in which that is enabled. (If -the current buffer is large, the specified timeout is multiplied by a -factor that increases as the size increases; for a million-byte -buffer, the factor is almost 4.) - -If the value is zero or @code{nil}, then auto-saving is not done as a -result of idleness, only after a certain number of input events as -specified by @code{auto-save-interval}. -@end defopt - -@defvar auto-save-hook -This normal hook is run whenever an auto-save is about to happen. -@end defvar - -@defopt auto-save-default -If this variable is non-@code{nil}, buffers that are visiting files -have auto-saving enabled by default. Otherwise, they do not. -@end defopt - -@deffn Command do-auto-save &optional no-message current-only -This function auto-saves all buffers that need to be auto-saved. It -saves all buffers for which auto-saving is enabled and that have been -changed since the previous auto-save. - -If any buffers are auto-saved, @code{do-auto-save} normally displays a -message saying @samp{Auto-saving...} in the echo area while -auto-saving is going on. However, if @var{no-message} is -non-@code{nil}, the message is inhibited. - -If @var{current-only} is non-@code{nil}, only the current buffer -is auto-saved. -@end deffn - -@defun delete-auto-save-file-if-necessary &optional force -This function deletes the current buffer's auto-save file if -@code{delete-auto-save-files} is non-@code{nil}. It is called every -time a buffer is saved. - -Unless @var{force} is non-@code{nil}, this function only deletes the -file if it was written by the current Emacs session since the last -true save. -@end defun - -@defopt delete-auto-save-files -This variable is used by the function -@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil}, -Emacs deletes auto-save files when a true save is done (in the visited -file). This saves disk space and unclutters your directory. -@end defopt - -@defun rename-auto-save-file -This function adjusts the current buffer's auto-save file name if the -visited file name has changed. It also renames an existing auto-save -file, if it was made in the current Emacs session. If the visited -file name has not changed, this function does nothing. -@end defun - -@defvar buffer-saved-size -The value of this buffer-local variable is the length of the current -buffer, when it was last read in, saved, or auto-saved. This is -used to detect a substantial decrease in size, and turn off auto-saving -in response. - -If it is @minus{}1, that means auto-saving is temporarily shut off in -this buffer due to a substantial decrease in size. Explicitly saving -the buffer stores a positive value in this variable, thus reenabling -auto-saving. Turning auto-save mode off or on also updates this -variable, so that the substantial decrease in size is forgotten. - -If it is @minus{}2, that means this buffer should disregard changes in -buffer size; in particular, it should not shut off auto-saving -temporarily due to changes in buffer size. -@end defvar - -@defvar auto-save-list-file-name -This variable (if non-@code{nil}) specifies a file for recording the -names of all the auto-save files. Each time Emacs does auto-saving, it -writes two lines into this file for each buffer that has auto-saving -enabled. The first line gives the name of the visited file (it's empty -if the buffer has none), and the second gives the name of the auto-save -file. - -When Emacs exits normally, it deletes this file; if Emacs crashes, you -can look in the file to find all the auto-save files that might contain -work that was otherwise lost. The @code{recover-session} command uses -this file to find them. - -The default name for this file specifies your home directory and starts -with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the -host name. -@end defvar - -@defopt auto-save-list-file-prefix -After Emacs reads your init file, it initializes -@code{auto-save-list-file-name} (if you have not already set it -non-@code{nil}) based on this prefix, adding the host name and process -ID@. If you set this to @code{nil} in your init file, then Emacs does -not initialize @code{auto-save-list-file-name}. -@end defopt - -@node Reverting -@section Reverting - - If you have made extensive changes to a file and then change your mind -about them, you can get rid of them by reading in the previous version -of the file with the @code{revert-buffer} command. @xref{Reverting, , -Reverting a Buffer, emacs, The GNU Emacs Manual}. - -@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes -This command replaces the buffer text with the text of the visited -file on disk. This action undoes all changes since the file was visited -or saved. - -By default, if the latest auto-save file is more recent than the visited -file, and the argument @var{ignore-auto} is @code{nil}, -@code{revert-buffer} asks the user whether to use that auto-save -instead. When you invoke this command interactively, @var{ignore-auto} -is @code{t} if there is no numeric prefix argument; thus, the -interactive default is not to check the auto-save file. - -Normally, @code{revert-buffer} asks for confirmation before it changes -the buffer; but if the argument @var{noconfirm} is non-@code{nil}, -@code{revert-buffer} does not ask for confirmation. - -Normally, this command reinitializes the buffer's major and minor modes -using @code{normal-mode}. But if @var{preserve-modes} is -non-@code{nil}, the modes remain unchanged. - -Reverting tries to preserve marker positions in the buffer by using the -replacement feature of @code{insert-file-contents}. If the buffer -contents and the file contents are identical before the revert -operation, reverting preserves all the markers. If they are not -identical, reverting does change the buffer; in that case, it preserves -the markers in the unchanged text (if any) at the beginning and end of -the buffer. Preserving any additional markers would be problematical. -@end deffn - -@defvar revert-buffer-in-progress-p -@code{revert-buffer} binds this variable to a non-@code{nil} value -while it is working. -@end defvar - -You can customize how @code{revert-buffer} does its work by setting -the variables described in the rest of this section. - -@defopt revert-without-query -This variable holds a list of files that should be reverted without -query. The value is a list of regular expressions. If the visited file -name matches one of these regular expressions, and the file has changed -on disk but the buffer is not modified, then @code{revert-buffer} -reverts the file without asking the user for confirmation. -@end defopt - - Some major modes customize @code{revert-buffer} by making -buffer-local bindings for these variables: - -@defvar revert-buffer-function -@anchor{Definition of revert-buffer-function} -The value of this variable is the function to use to revert this -buffer. It should be a function with two optional -arguments to do the work of reverting. The two optional arguments, -@var{ignore-auto} and @var{noconfirm}, are the arguments that -@code{revert-buffer} received. - -Modes such as Dired mode, in which the text being edited does not -consist of a file's contents but can be regenerated in some other -fashion, can give this variable a buffer-local value that is a special -function to regenerate the contents. -@end defvar - -@defvar revert-buffer-insert-file-contents-function -The value of this variable specifies the function to use to -insert the updated contents when reverting this buffer. The function -receives two arguments: first the file name to use; second, @code{t} if -the user has asked to read the auto-save file. - -The reason for a mode to change this variable instead of -@code{revert-buffer-function} is to avoid duplicating or replacing the -rest of what @code{revert-buffer} does: asking for confirmation, -clearing the undo list, deciding the proper major mode, and running the -hooks listed below. -@end defvar - -@defvar before-revert-hook -This normal hook is run by the default @code{revert-buffer-function} -before inserting the modified contents. A custom @code{revert-buffer-function} -may or may not run this hook. -@end defvar - -@defvar after-revert-hook -This normal hook is run by the default @code{revert-buffer-function} -after inserting the modified contents. A custom @code{revert-buffer-function} -may or may not run this hook. -@end defvar - -@c FIXME? Move this section from arevert-xtra to here? -@defvar buffer-stale-function -The value of this variable specifies a function to call to check -whether a buffer needs reverting. The default value only handles -buffers that are visiting files, by checking their modification time. -Buffers that are not visiting files require a custom function -@iftex -(@pxref{Supporting additional buffers,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Supporting additional buffers,,, emacs}). -@end ifnottex -@end defvar diff --git a/doc/lispref/book-spine.texi b/doc/lispref/book-spine.texi deleted file mode 100644 index f58fb77dcc1..00000000000 --- a/doc/lispref/book-spine.texi +++ /dev/null @@ -1,28 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename book-spine -@settitle book-spine -@documentencoding UTF-8 -@c %**end of header - -@include emacsver.texi - -@c need dot in text so first space command works! -. -@sp 7 - -@center @titlefont{GNU Emacs Lisp Reference Manual} -@sp 5 -@center GNU -@center Emacs Version @value{EMACSVER} -@center for Unix Users -@sp 5 - -@center by -@center Bil Lewis, -@center Dan LaLiberte, -@center the GNU Manual Group, -@center et al. -@sp 5 -@center Free Software Foundation -@bye diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi deleted file mode 100644 index 5ac2d6786e8..00000000000 --- a/doc/lispref/buffers.texi +++ /dev/null @@ -1,1238 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Buffers -@chapter Buffers -@cindex buffer - - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. While several buffers may -exist at one time, only one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. - -@menu -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - "behind Emacs's back". -* Read Only Buffers:: Modifying text is not allowed in a read-only buffer. -* Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. -@end menu - -@node Buffer Basics -@section Buffer Basics - -@ifnottex - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. Although several buffers -normally exist, only one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. -@end ifnottex - - Buffers in Emacs editing are objects that have distinct names and hold -text that can be edited. Buffers appear to Lisp programs as a special -data type. You can think of the contents of a buffer as a string that -you can extend; insertions and deletions may occur in any part of the -buffer. @xref{Text}. - - A Lisp buffer object contains numerous pieces of information. Some of -this information is directly accessible to the programmer through -variables, while other information is accessible only through -special-purpose functions. For example, the visited file name is -directly accessible through a variable, while the value of point is -accessible only through a primitive function. - - Buffer-specific information that is directly accessible is stored in -@dfn{buffer-local} variable bindings, which are variable values that are -effective only in a particular buffer. This feature allows each buffer -to override the values of certain variables. Most major modes override -variables such as @code{fill-column} or @code{comment-column} in this -way. For more information about buffer-local variables and functions -related to them, see @ref{Buffer-Local Variables}. - - For functions and variables related to visiting files in buffers, see -@ref{Visiting Files} and @ref{Saving Buffers}. For functions and -variables related to the display of buffers in windows, see -@ref{Buffers and Windows}. - -@defun bufferp object -This function returns @code{t} if @var{object} is a buffer, -@code{nil} otherwise. -@end defun - -@node Current Buffer -@section The Current Buffer -@cindex selecting a buffer -@cindex changing to another buffer -@cindex current buffer - - There are, in general, many buffers in an Emacs session. At any -time, one of them is designated the @dfn{current buffer}---the buffer -in which most editing takes place. Most of the primitives for -examining or changing text operate implicitly on the current buffer -(@pxref{Text}). - - Normally, the buffer displayed in the selected window is the current -buffer, but this is not always so: a Lisp program can temporarily -designate any buffer as current in order to operate on its contents, -without changing what is displayed on the screen. The most basic -function for designating a current buffer is @code{set-buffer}. - -@defun current-buffer -This function returns the current buffer. - -@example -@group -(current-buffer) - @result{} # -@end group -@end example -@end defun - -@defun set-buffer buffer-or-name -This function makes @var{buffer-or-name} the current buffer. -@var{buffer-or-name} must be an existing buffer or the name of an -existing buffer. The return value is the buffer made current. - -This function does not display the buffer in any window, so the user -cannot necessarily see the buffer. But Lisp programs will now operate -on it. -@end defun - - When an editing command returns to the editor command loop, Emacs -automatically calls @code{set-buffer} on the buffer shown in the -selected window. This is to prevent confusion: it ensures that the -buffer that the cursor is in, when Emacs reads a command, is the -buffer to which that command applies (@pxref{Command Loop}). Thus, -you should not use @code{set-buffer} to switch visibly to a different -buffer; for that, use the functions described in @ref{Switching -Buffers}. - - When writing a Lisp function, do @emph{not} rely on this behavior of -the command loop to restore the current buffer after an operation. -Editing commands can also be called as Lisp functions by other -programs, not just from the command loop; it is convenient for the -caller if the subroutine does not change which buffer is current -(unless, of course, that is the subroutine's purpose). - - To operate temporarily on another buffer, put the @code{set-buffer} -within a @code{save-current-buffer} form. Here, as an example, is a -simplified version of the command @code{append-to-buffer}: - -@example -@group -(defun append-to-buffer (buffer start end) - "Append the text of the region to BUFFER." - (interactive "BAppend to buffer: \nr") - (let ((oldbuf (current-buffer))) - (save-current-buffer - (set-buffer (get-buffer-create buffer)) - (insert-buffer-substring oldbuf start end)))) -@end group -@end example - -@noindent -Here, we bind a local variable to record the current buffer, and then -@code{save-current-buffer} arranges to make it current again later. -Next, @code{set-buffer} makes the specified buffer current, and -@code{insert-buffer-substring} copies the string from the original -buffer to the specified (and now current) buffer. - - Alternatively, we can use the @code{with-current-buffer} macro: - -@example -@group -(defun append-to-buffer (buffer start end) - "Append the text of the region to BUFFER." - (interactive "BAppend to buffer: \nr") - (let ((oldbuf (current-buffer))) - (with-current-buffer (get-buffer-create buffer) - (insert-buffer-substring oldbuf start end)))) -@end group -@end example - - In either case, if the buffer appended to happens to be displayed in -some window, the next redisplay will show how its text has changed. -If it is not displayed in any window, you will not see the change -immediately on the screen. The command causes the buffer to become -current temporarily, but does not cause it to be displayed. - - If you make local bindings (with @code{let} or function arguments) -for a variable that may also have buffer-local bindings, make sure -that the same buffer is current at the beginning and at the end of the -local binding's scope. Otherwise you might bind it in one buffer and -unbind it in another! - - Do not rely on using @code{set-buffer} to change the current buffer -back, because that won't do the job if a quit happens while the wrong -buffer is current. For instance, in the previous example, it would -have been wrong to do this: - -@example -@group - (let ((oldbuf (current-buffer))) - (set-buffer (get-buffer-create buffer)) - (insert-buffer-substring oldbuf start end) - (set-buffer oldbuf)) -@end group -@end example - -@noindent -Using @code{save-current-buffer} or @code{with-current-buffer}, as we -did, correctly handles quitting, errors, and @code{throw}, as well as -ordinary evaluation. - -@defspec save-current-buffer body@dots{} -The @code{save-current-buffer} special form saves the identity of the -current buffer, evaluates the @var{body} forms, and finally restores -that buffer as current. The return value is the value of the last -form in @var{body}. The current buffer is restored even in case of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). - -If the buffer that used to be current has been killed by the time of -exit from @code{save-current-buffer}, then it is not made current again, -of course. Instead, whichever buffer was current just before exit -remains current. -@end defspec - -@defmac with-current-buffer buffer-or-name body@dots{} -The @code{with-current-buffer} macro saves the identity of the current -buffer, makes @var{buffer-or-name} current, evaluates the @var{body} -forms, and finally restores the current buffer. @var{buffer-or-name} -must specify an existing buffer or the name of an existing buffer. - -The return value is the value of the last form in @var{body}. The -current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). -@end defmac - -@defmac with-temp-buffer body@dots{} -@anchor{Definition of with-temp-buffer} -The @code{with-temp-buffer} macro evaluates the @var{body} forms -with a temporary buffer as the current buffer. It saves the identity of -the current buffer, creates a temporary buffer and makes it current, -evaluates the @var{body} forms, and finally restores the previous -current buffer while killing the temporary buffer. By default, undo -information (@pxref{Undo}) is not recorded in the buffer created by -this macro (but @var{body} can enable that, if needed). - -The return value is the value of the last form in @var{body}. You can -return the contents of the temporary buffer by using -@code{(buffer-string)} as the last form. - -The current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -See also @code{with-temp-file} in @ref{Definition of with-temp-file,, -Writing to Files}. -@end defmac - -@node Buffer Names -@section Buffer Names -@cindex buffer names - - Each buffer has a unique name, which is a string. Many of the -functions that work on buffers accept either a buffer or a buffer name -as an argument. Any argument called @var{buffer-or-name} is of this -sort, and an error is signaled if it is neither a string nor a buffer. -Any argument called @var{buffer} must be an actual buffer -object, not a name. - -@cindex hidden buffers -@cindex buffers without undo information - Buffers that are ephemeral and generally uninteresting to the user -have names starting with a space, so that the @code{list-buffers} and -@code{buffer-menu} commands don't mention them (but if such a buffer -visits a file, it @strong{is} mentioned). A name starting with -space also initially disables recording undo information; see -@ref{Undo}. - -@defun buffer-name &optional buffer -This function returns the name of @var{buffer} as a string. -@var{buffer} defaults to the current buffer. - -If @code{buffer-name} returns @code{nil}, it means that @var{buffer} -has been killed. @xref{Killing Buffers}. - -@example -@group -(buffer-name) - @result{} "buffers.texi" -@end group - -@group -(setq foo (get-buffer "temp")) - @result{} # -@end group -@group -(kill-buffer foo) - @result{} nil -@end group -@group -(buffer-name foo) - @result{} nil -@end group -@group -foo - @result{} # -@end group -@end example -@end defun - -@deffn Command rename-buffer newname &optional unique -This function renames the current buffer to @var{newname}. An error -is signaled if @var{newname} is not a string. - -@c Emacs 19 feature -Ordinarily, @code{rename-buffer} signals an error if @var{newname} is -already in use. However, if @var{unique} is non-@code{nil}, it modifies -@var{newname} to make a name that is not in use. Interactively, you can -make @var{unique} non-@code{nil} with a numeric prefix argument. -(This is how the command @code{rename-uniquely} is implemented.) - -This function returns the name actually given to the buffer. -@end deffn - -@defun get-buffer buffer-or-name -This function returns the buffer specified by @var{buffer-or-name}. -If @var{buffer-or-name} is a string and there is no buffer with that -name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it -is returned as given; that is not very useful, so the argument is usually -a name. For example: - -@example -@group -(setq b (get-buffer "lewis")) - @result{} # -@end group -@group -(get-buffer b) - @result{} # -@end group -@group -(get-buffer "Frazzle-nots") - @result{} nil -@end group -@end example - -See also the function @code{get-buffer-create} in @ref{Creating Buffers}. -@end defun - -@c Emacs 19 feature -@defun generate-new-buffer-name starting-name &optional ignore -This function returns a name that would be unique for a new buffer---but -does not create the buffer. It starts with @var{starting-name}, and -produces a name not currently in use for any buffer by appending a -number inside of @samp{<@dots{}>}. It starts at 2 and keeps -incrementing the number until it is not the name of an existing buffer. - -If the optional second argument @var{ignore} is non-@code{nil}, it -should be a string, a potential buffer name. It means to consider -that potential buffer acceptable, if it is tried, even it is the name -of an existing buffer (which would normally be rejected). Thus, if -buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and -@samp{foo<4>} exist, - -@example -(generate-new-buffer-name "foo") - @result{} "foo<5>" -(generate-new-buffer-name "foo" "foo<3>") - @result{} "foo<3>" -(generate-new-buffer-name "foo" "foo<6>") - @result{} "foo<5>" -@end example - -See the related function @code{generate-new-buffer} in @ref{Creating -Buffers}. -@end defun - -@node Buffer File Name -@section Buffer File Name -@cindex visited file -@cindex buffer file name -@cindex file name of buffer - - The @dfn{buffer file name} is the name of the file that is visited in -that buffer. When a buffer is not visiting a file, its buffer file name -is @code{nil}. Most of the time, the buffer name is the same as the -nondirectory part of the buffer file name, but the buffer file name and -the buffer name are distinct and can be set independently. -@xref{Visiting Files}. - -@defun buffer-file-name &optional buffer -This function returns the absolute file name of the file that -@var{buffer} is visiting. If @var{buffer} is not visiting any file, -@code{buffer-file-name} returns @code{nil}. If @var{buffer} is not -supplied, it defaults to the current buffer. - -@example -@group -(buffer-file-name (other-buffer)) - @result{} "/usr/user/lewis/manual/files.texi" -@end group -@end example -@end defun - -@defvar buffer-file-name -This buffer-local variable contains the name of the file being visited -in the current buffer, or @code{nil} if it is not visiting a file. It -is a permanent local variable, unaffected by -@code{kill-all-local-variables}. - -@example -@group -buffer-file-name - @result{} "/usr/user/lewis/manual/buffers.texi" -@end group -@end example - -It is risky to change this variable's value without doing various other -things. Normally it is better to use @code{set-visited-file-name} (see -below); some of the things done there, such as changing the buffer name, -are not strictly necessary, but others are essential to avoid confusing -Emacs. -@end defvar - -@defvar buffer-file-truename -This buffer-local variable holds the abbreviated truename of the file -visited in the current buffer, or @code{nil} if no file is visited. -It is a permanent local, unaffected by -@code{kill-all-local-variables}. @xref{Truenames}, and -@ref{abbreviate-file-name}. -@end defvar - -@defvar buffer-file-number -This buffer-local variable holds the file number and directory device -number of the file visited in the current buffer, or @code{nil} if no -file or a nonexistent file is visited. It is a permanent local, -unaffected by @code{kill-all-local-variables}. - -The value is normally a list of the form @code{(@var{filenum} -@var{devnum})}. This pair of numbers uniquely identifies the file among -all files accessible on the system. See the function -@code{file-attributes}, in @ref{File Attributes}, for more information -about them. - -If @code{buffer-file-name} is the name of a symbolic link, then both -numbers refer to the recursive target. -@end defvar - -@defun get-file-buffer filename -This function returns the buffer visiting file @var{filename}. If -there is no such buffer, it returns @code{nil}. The argument -@var{filename}, which must be a string, is expanded (@pxref{File Name -Expansion}), then compared against the visited file names of all live -buffers. Note that the buffer's @code{buffer-file-name} must match -the expansion of @var{filename} exactly. This function will not -recognize other names for the same file. - -@example -@group -(get-file-buffer "buffers.texi") - @result{} # -@end group -@end example - -In unusual circumstances, there can be more than one buffer visiting -the same file name. In such cases, this function returns the first -such buffer in the buffer list. -@end defun - -@defun find-buffer-visiting filename &optional predicate -This is like @code{get-file-buffer}, except that it can return any -buffer visiting the file @emph{possibly under a different name}. That -is, the buffer's @code{buffer-file-name} does not need to match the -expansion of @var{filename} exactly, it only needs to refer to the -same file. If @var{predicate} is non-@code{nil}, it should be a -function of one argument, a buffer visiting @var{filename}. The -buffer is only considered a suitable return value if @var{predicate} -returns non-@code{nil}. If it can not find a suitable buffer to -return, @code{find-buffer-visiting} returns @code{nil}. -@end defun - -@deffn Command set-visited-file-name filename &optional no-query along-with-file -If @var{filename} is a non-empty string, this function changes the -name of the file visited in the current buffer to @var{filename}. (If the -buffer had no visited file, this gives it one.) The @emph{next time} -the buffer is saved it will go in the newly-specified file. - -This command marks the buffer as modified, since it does not (as far -as Emacs knows) match the contents of @var{filename}, even if it -matched the former visited file. It also renames the buffer to -correspond to the new file name, unless the new name is already in -use. - -If @var{filename} is @code{nil} or the empty string, that stands for -``no visited file''. In this case, @code{set-visited-file-name} marks -the buffer as having no visited file, without changing the buffer's -modified flag. - -Normally, this function asks the user for confirmation if there -already is a buffer visiting @var{filename}. If @var{no-query} is -non-@code{nil}, that prevents asking this question. If there already -is a buffer visiting @var{filename}, and the user confirms or -@var{no-query} is non-@code{nil}, this function makes the new -buffer name unique by appending a number inside of @samp{<@dots{}>} to -@var{filename}. - -If @var{along-with-file} is non-@code{nil}, that means to assume that -the former visited file has been renamed to @var{filename}. In this -case, the command does not change the buffer's modified flag, nor the -buffer's recorded last file modification time as reported by -@code{visited-file-modtime} (@pxref{Modification Time}). If -@var{along-with-file} is @code{nil}, this function clears the recorded -last file modification time, after which @code{visited-file-modtime} -returns zero. - -When the function @code{set-visited-file-name} is called -interactively, it prompts for @var{filename} in the minibuffer. -@end deffn - -@defvar list-buffers-directory -This buffer-local variable specifies a string to display in a buffer -listing where the visited file name would go, for buffers that don't -have a visited file name. Dired buffers use this variable. -@end defvar - -@node Buffer Modification -@section Buffer Modification -@cindex buffer modification -@cindex modification flag (of buffer) - - Emacs keeps a flag called the @dfn{modified flag} for each buffer, to -record whether you have changed the text of the buffer. This flag is -set to @code{t} whenever you alter the contents of the buffer, and -cleared to @code{nil} when you save it. Thus, the flag shows whether -there are unsaved changes. The flag value is normally shown in the mode -line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving -Buffers}) and auto-saving (@pxref{Auto-Saving}). - - Some Lisp programs set the flag explicitly. For example, the function -@code{set-visited-file-name} sets the flag to @code{t}, because the text -does not match the newly-visited file, even if it is unchanged from the -file formerly visited. - - The functions that modify the contents of buffers are described in -@ref{Text}. - -@defun buffer-modified-p &optional buffer -This function returns @code{t} if the buffer @var{buffer} has been modified -since it was last read in from a file or saved, or @code{nil} -otherwise. If @var{buffer} is not supplied, the current buffer -is tested. -@end defun - -@defun set-buffer-modified-p flag -This function marks the current buffer as modified if @var{flag} is -non-@code{nil}, or as unmodified if the flag is @code{nil}. - -Another effect of calling this function is to cause unconditional -redisplay of the mode line for the current buffer. In fact, the -function @code{force-mode-line-update} works by doing this: - -@example -@group -(set-buffer-modified-p (buffer-modified-p)) -@end group -@end example -@end defun - -@defun restore-buffer-modified-p flag -Like @code{set-buffer-modified-p}, but does not force redisplay -of mode lines. -@end defun - -@deffn Command not-modified &optional arg -This command marks the current buffer as unmodified, and not needing -to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as -modified, so that it will be saved at the next suitable occasion. -Interactively, @var{arg} is the prefix argument. - -Don't use this function in programs, since it prints a message in the -echo area; use @code{set-buffer-modified-p} (above) instead. -@end deffn - -@defun buffer-modified-tick &optional buffer -This function returns @var{buffer}'s modification-count. This is a -counter that increments every time the buffer is modified. If -@var{buffer} is @code{nil} (or omitted), the current buffer is used. -The counter can wrap around occasionally. -@end defun - -@defun buffer-chars-modified-tick &optional buffer -This function returns @var{buffer}'s character-change modification-count. -Changes to text properties leave this counter unchanged; however, each -time text is inserted or removed from the buffer, the counter is reset -to the value that would be returned by @code{buffer-modified-tick}. -By comparing the values returned by two @code{buffer-chars-modified-tick} -calls, you can tell whether a character change occurred in that buffer -in between the calls. If @var{buffer} is @code{nil} (or omitted), the -current buffer is used. -@end defun - -@node Modification Time -@section Buffer Modification Time -@cindex comparing file modification time -@cindex modification time of buffer - - Suppose that you visit a file and make changes in its buffer, and -meanwhile the file itself is changed on disk. At this point, saving the -buffer would overwrite the changes in the file. Occasionally this may -be what you want, but usually it would lose valuable information. Emacs -therefore checks the file's modification time using the functions -described below before saving the file. (@xref{File Attributes}, -for how to examine a file's modification time.) - -@defun verify-visited-file-modtime &optional buffer -This function compares what @var{buffer} (by default, the -current-buffer) has recorded for the modification time of its visited -file against the actual modification time of the file as recorded by the -operating system. The two should be the same unless some other process -has written the file since Emacs visited or saved it. - -The function returns @code{t} if the last actual modification time and -Emacs's recorded modification time are the same, @code{nil} otherwise. -It also returns @code{t} if the buffer has no recorded last -modification time, that is if @code{visited-file-modtime} would return -zero. - -It always returns @code{t} for buffers that are not visiting a file, -even if @code{visited-file-modtime} returns a non-zero value. For -instance, it always returns @code{t} for dired buffers. It returns -@code{t} for buffers that are visiting a file that does not exist and -never existed, but @code{nil} for file-visiting buffers whose file has -been deleted. -@end defun - -@defun clear-visited-file-modtime -This function clears out the record of the last modification time of -the file being visited by the current buffer. As a result, the next -attempt to save this buffer will not complain of a discrepancy in -file modification times. - -This function is called in @code{set-visited-file-name} and other -exceptional places where the usual test to avoid overwriting a changed -file should not be done. -@end defun - -@defun visited-file-modtime -This function returns the current buffer's recorded last file -modification time, as a list of the form @code{(@var{high} @var{low} -@var{microsec} @var{picosec})}. (This is the same format that -@code{file-attributes} uses to return time values; @pxref{File -Attributes}.) - -If the buffer has no recorded last modification time, this function -returns zero. This case occurs, for instance, if the buffer is not -visiting a file or if the time has been explicitly cleared by -@code{clear-visited-file-modtime}. Note, however, that -@code{visited-file-modtime} returns a list for some non-file buffers -too. For instance, in a Dired buffer listing a directory, it returns -the last modification time of that directory, as recorded by Dired. - -If the buffer is not visiting a file, this function returns -1. -@end defun - -@defun set-visited-file-modtime &optional time -This function updates the buffer's record of the last modification time -of the visited file, to the value specified by @var{time} if @var{time} -is not @code{nil}, and otherwise to the last modification time of the -visited file. - -If @var{time} is neither @code{nil} nor zero, it should have the form -@code{(@var{high} @var{low} @var{microsec} @var{picosec})}, -the format used by @code{current-time} (@pxref{Time of Day}). - -This function is useful if the buffer was not read from the file -normally, or if the file itself has been changed for some known benign -reason. -@end defun - -@defun ask-user-about-supersession-threat filename -This function is used to ask a user how to proceed after an attempt to -modify an buffer visiting file @var{filename} when the file is newer -than the buffer text. Emacs detects this because the modification -time of the file on disk is newer than the last save-time of the -buffer. This means some other program has probably altered the file. - -@kindex file-supersession -Depending on the user's answer, the function may return normally, in -which case the modification of the buffer proceeds, or it may signal a -@code{file-supersession} error with data @code{(@var{filename})}, in which -case the proposed buffer modification is not allowed. - -This function is called automatically by Emacs on the proper -occasions. It exists so you can customize Emacs by redefining it. -See the file @file{userlock.el} for the standard definition. - -See also the file locking mechanism in @ref{File Locks}. -@end defun - -@node Read Only Buffers -@section Read-Only Buffers -@cindex read-only buffer -@cindex buffer, read-only - - If a buffer is @dfn{read-only}, then you cannot change its contents, -although you may change your view of the contents by scrolling and -narrowing. - - Read-only buffers are used in two kinds of situations: - -@itemize @bullet -@item -A buffer visiting a write-protected file is normally read-only. - -Here, the purpose is to inform the user that editing the buffer with the -aim of saving it in the file may be futile or undesirable. The user who -wants to change the buffer text despite this can do so after clearing -the read-only flag with @kbd{C-x C-q}. - -@item -Modes such as Dired and Rmail make buffers read-only when altering the -contents with the usual editing commands would probably be a mistake. - -The special commands of these modes bind @code{buffer-read-only} to -@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to -@code{t} around the places where they themselves change the text. -@end itemize - -@defvar buffer-read-only -This buffer-local variable specifies whether the buffer is read-only. -The buffer is read-only if this variable is non-@code{nil}. -@end defvar - -@defvar inhibit-read-only -If this variable is non-@code{nil}, then read-only buffers and, -depending on the actual value, some or all read-only characters may be -modified. Read-only characters in a buffer are those that have a -non-@code{nil} @code{read-only} text property. @xref{Special -Properties}, for more information about text properties. - -If @code{inhibit-read-only} is @code{t}, all @code{read-only} character -properties have no effect. If @code{inhibit-read-only} is a list, then -@code{read-only} character properties have no effect if they are members -of the list (comparison is done with @code{eq}). -@end defvar - -@deffn Command read-only-mode &optional arg -This is the mode command for Read Only minor mode, a buffer-local -minor mode. When the mode is enabled, @code{buffer-read-only} is -non-@code{nil} in the buffer; when disabled, @code{buffer-read-only} -is @code{nil} in the buffer. The calling convention is the same as -for other minor mode commands (@pxref{Minor Mode Conventions}). - -This minor mode mainly serves as a wrapper for -@code{buffer-read-only}; unlike most minor modes, there is no separate -@code{read-only-mode} variable. Even when Read Only mode is disabled, -characters with non-@code{nil} @code{read-only} text properties remain -read-only. To temporarily ignore all read-only states, bind -@code{inhibit-read-only}, as described above. - -When enabling Read Only mode, this mode command also enables View mode -if the option @code{view-read-only} is non-@code{nil}. @xref{Misc -Buffer,,Miscellaneous Buffer Operations, emacs, The GNU Emacs Manual}. -When disabling Read Only mode, it disables View mode if View mode was -enabled. -@end deffn - -@defun barf-if-buffer-read-only -This function signals a @code{buffer-read-only} error if the current -buffer is read-only. @xref{Using Interactive}, for another way to -signal an error if the current buffer is read-only. -@end defun - -@node Buffer List -@section The Buffer List -@cindex buffer list - - The @dfn{buffer list} is a list of all live buffers. The order of the -buffers in this list is based primarily on how recently each buffer has -been displayed in a window. Several functions, notably -@code{other-buffer}, use this ordering. A buffer list displayed for the -user also follows this order. - - Creating a buffer adds it to the end of the buffer list, and killing -a buffer removes it from that list. A buffer moves to the front of -this list whenever it is chosen for display in a window -(@pxref{Switching Buffers}) or a window displaying it is selected -(@pxref{Selecting Windows}). A buffer moves to the end of the list -when it is buried (see @code{bury-buffer}, below). There are no -functions available to the Lisp programmer which directly manipulate -the buffer list. - - In addition to the fundamental buffer list just described, Emacs -maintains a local buffer list for each frame, in which the buffers that -have been displayed (or had their windows selected) in that frame come -first. (This order is recorded in the frame's @code{buffer-list} frame -parameter; see @ref{Buffer Parameters}.) Buffers never displayed in -that frame come afterward, ordered according to the fundamental buffer -list. - -@defun buffer-list &optional frame -This function returns the buffer list, including all buffers, even those -whose names begin with a space. The elements are actual buffers, not -their names. - -If @var{frame} is a frame, this returns @var{frame}'s local buffer list. -If @var{frame} is @code{nil} or omitted, the fundamental buffer list is -used: the buffers appear in order of most recent display or selection, -regardless of which frames they were displayed on. - -@example -@group -(buffer-list) - @result{} (# - # # - # #) -@end group - -@group -;; @r{Note that the name of the minibuffer} -;; @r{begins with a space!} -(mapcar (function buffer-name) (buffer-list)) - @result{} ("buffers.texi" " *Minibuf-1*" - "buffer.c" "*Help*" "TAGS") -@end group -@end example -@end defun - - The list returned by @code{buffer-list} is constructed specifically; -it is not an internal Emacs data structure, and modifying it has no -effect on the order of buffers. If you want to change the order of -buffers in the fundamental buffer list, here is an easy way: - -@example -(defun reorder-buffer-list (new-list) - (while new-list - (bury-buffer (car new-list)) - (setq new-list (cdr new-list)))) -@end example - - With this method, you can specify any order for the list, but there is -no danger of losing a buffer or adding something that is not a valid -live buffer. - - To change the order or value of a specific frame's buffer list, set -that frame's @code{buffer-list} parameter with -@code{modify-frame-parameters} (@pxref{Parameter Access}). - -@defun other-buffer &optional buffer visible-ok frame -This function returns the first buffer in the buffer list other than -@var{buffer}. Usually, this is the buffer appearing in the most -recently selected window (in frame @var{frame} or else the selected -frame, @pxref{Input Focus}), aside from @var{buffer}. Buffers whose -names start with a space are not considered at all. - -If @var{buffer} is not supplied (or if it is not a live buffer), then -@code{other-buffer} returns the first buffer in the selected frame's -local buffer list. (If @var{frame} is non-@code{nil}, it returns the -first buffer in @var{frame}'s local buffer list instead.) - -If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, -then @code{other-buffer} uses that predicate to decide which buffers to -consider. It calls the predicate once for each buffer, and if the value -is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. - -@c Emacs 19 feature -If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning -a buffer visible in any window on any visible frame, except as a last -resort. If @var{visible-ok} is non-@code{nil}, then it does not matter -whether a buffer is displayed somewhere or not. - -If no suitable buffer exists, the buffer @file{*scratch*} is returned -(and created, if necessary). -@end defun - -@defun last-buffer &optional buffer visible-ok frame -This function returns the last buffer in @var{frame}'s buffer list other -than @var{buffer}. If @var{frame} is omitted or @code{nil}, it uses the -selected frame's buffer list. - -The argument @var{visible-ok} is handled as with @code{other-buffer}, -see above. If no suitable buffer can be found, the buffer -@file{*scratch*} is returned. -@end defun - -@deffn Command bury-buffer &optional buffer-or-name -This command puts @var{buffer-or-name} at the end of the buffer list, -without changing the order of any of the other buffers on the list. -This buffer therefore becomes the least desirable candidate for -@code{other-buffer} to return. The argument can be either a buffer -itself or the name of one. - -This function operates on each frame's @code{buffer-list} parameter as -well as the fundamental buffer list; therefore, the buffer that you bury -will come last in the value of @code{(buffer-list @var{frame})} and in -the value of @code{(buffer-list)}. In addition, it also puts the buffer -at the end of the list of buffer of the selected window (@pxref{Window -History}) provided it is shown in that window. - -If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the -current buffer. In addition, if the current buffer is displayed in the -selected window, this makes sure that the window is either deleted or -another buffer is shown in it. More precisely, if the selected window -is dedicated (@pxref{Dedicated Windows}) and there are other windows on -its frame, the window is deleted. If it is the only window on its frame -and that frame is not the only frame on its terminal, the frame is -``dismissed'' by calling the function specified by -@code{frame-auto-hide-function} (@pxref{Quitting Windows}). Otherwise, -it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show -another buffer in that window. If @var{buffer-or-name} is displayed in -some other window, it remains displayed there. - -To replace a buffer in all the windows that display it, use -@code{replace-buffer-in-windows}, @xref{Buffers and Windows}. -@end deffn - -@deffn Command unbury-buffer -This command switches to the last buffer in the local buffer list of -the selected frame. More precisely, it calls the function -@code{switch-to-buffer} (@pxref{Switching Buffers}), to display the -buffer returned by @code{last-buffer} (see above), in the selected -window. -@end deffn - -@defvar buffer-list-update-hook -This is a normal hook run whenever the buffer list changes. Functions -(implicitly) running this hook are @code{get-buffer-create} -(@pxref{Creating Buffers}), @code{rename-buffer} (@pxref{Buffer Names}), -@code{kill-buffer} (@pxref{Killing Buffers}), @code{bury-buffer} (see -above) and @code{select-window} (@pxref{Selecting Windows}). -@end defvar - -@node Creating Buffers -@section Creating Buffers -@cindex creating buffers -@cindex buffers, creating - - This section describes the two primitives for creating buffers. -@code{get-buffer-create} creates a buffer if it finds no existing buffer -with the specified name; @code{generate-new-buffer} always creates a new -buffer and gives it a unique name. - - Other functions you can use to create buffers include -@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and -@code{create-file-buffer} (@pxref{Visiting Files}). Starting a -subprocess can also create a buffer (@pxref{Processes}). - -@defun get-buffer-create buffer-or-name -This function returns a buffer named @var{buffer-or-name}. The buffer -returned does not become the current buffer---this function does not -change which buffer is current. - -@var{buffer-or-name} must be either a string or an existing buffer. If -it is a string and a live buffer with that name already exists, -@code{get-buffer-create} returns that buffer. If no such buffer exists, -it creates a new buffer. If @var{buffer-or-name} is a buffer instead of -a string, it is returned as given, even if it is dead. - -@example -@group -(get-buffer-create "foo") - @result{} # -@end group -@end example - -The major mode for a newly created buffer is set to Fundamental mode. -(The default value of the variable @code{major-mode} is handled at a higher -level; see @ref{Auto Major Mode}.) If the name begins with a space, the -buffer initially disables undo information recording (@pxref{Undo}). -@end defun - -@defun generate-new-buffer name -This function returns a newly created, empty buffer, but does not make -it current. The name of the buffer is generated by passing @var{name} -to the function @code{generate-new-buffer-name} (@pxref{Buffer -Names}). Thus, if there is no buffer named @var{name}, then that is -the name of the new buffer; if that name is in use, a suffix of the -form @samp{<@var{n}>}, where @var{n} is an integer, is appended to -@var{name}. - -An error is signaled if @var{name} is not a string. - -@example -@group -(generate-new-buffer "bar") - @result{} # -@end group -@group -(generate-new-buffer "bar") - @result{} #> -@end group -@group -(generate-new-buffer "bar") - @result{} #> -@end group -@end example - -The major mode for the new buffer is set to Fundamental mode. The default -value of the variable @code{major-mode} is handled at a higher level. -@xref{Auto Major Mode}. -@end defun - -@node Killing Buffers -@section Killing Buffers -@cindex killing buffers -@cindex buffers, killing - - @dfn{Killing a buffer} makes its name unknown to Emacs and makes the -memory space it occupied available for other use. - - The buffer object for the buffer that has been killed remains in -existence as long as anything refers to it, but it is specially marked -so that you cannot make it current or display it. Killed buffers retain -their identity, however; if you kill two distinct buffers, they remain -distinct according to @code{eq} although both are dead. - - If you kill a buffer that is current or displayed in a window, Emacs -automatically selects or displays some other buffer instead. This -means that killing a buffer can change the current buffer. Therefore, -when you kill a buffer, you should also take the precautions -associated with changing the current buffer (unless you happen to know -that the buffer being killed isn't current). @xref{Current Buffer}. - - If you kill a buffer that is the base buffer of one or more indirect -@iftex -buffers, -@end iftex -@ifnottex -buffers (@pxref{Indirect Buffers}), -@end ifnottex -the indirect buffers are automatically killed as well. - -@cindex live buffer - The @code{buffer-name} of a buffer is @code{nil} if, and only if, -the buffer is killed. A buffer that has not been killed is called a -@dfn{live} buffer. To test whether a buffer is live or killed, use -the function @code{buffer-live-p} (see below). - -@deffn Command kill-buffer &optional buffer-or-name -This function kills the buffer @var{buffer-or-name}, freeing all its -memory for other uses or to be returned to the operating system. If -@var{buffer-or-name} is @code{nil} or omitted, it kills the current -buffer. - -Any processes that have this buffer as the @code{process-buffer} are -sent the @code{SIGHUP} (``hangup'') signal, which normally causes them -to terminate. @xref{Signals to Processes}. - -If the buffer is visiting a file and contains unsaved changes, -@code{kill-buffer} asks the user to confirm before the buffer is killed. -It does this even if not called interactively. To prevent the request -for confirmation, clear the modified flag before calling -@code{kill-buffer}. @xref{Buffer Modification}. - -This function calls @code{replace-buffer-in-windows} for cleaning up -all windows currently displaying the buffer to be killed. - -Killing a buffer that is already dead has no effect. - -This function returns @code{t} if it actually killed the buffer. It -returns @code{nil} if the user refuses to confirm or if -@var{buffer-or-name} was already dead. - -@smallexample -(kill-buffer "foo.unchanged") - @result{} t -(kill-buffer "foo.changed") - ----------- Buffer: Minibuffer ---------- -Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} ----------- Buffer: Minibuffer ---------- - - @result{} t -@end smallexample -@end deffn - -@defvar kill-buffer-query-functions -Before confirming unsaved changes, @code{kill-buffer} calls the functions -in the list @code{kill-buffer-query-functions}, in order of appearance, -with no arguments. The buffer being killed is the current buffer when -they are called. The idea of this feature is that these functions will -ask for confirmation from the user. If any of them returns @code{nil}, -@code{kill-buffer} spares the buffer's life. -@end defvar - -@defvar kill-buffer-hook -This is a normal hook run by @code{kill-buffer} after asking all the -questions it is going to ask, just before actually killing the buffer. -The buffer to be killed is current when the hook functions run. -@xref{Hooks}. This variable is a permanent local, so its local binding -is not cleared by changing major modes. -@end defvar - -@defopt buffer-offer-save -This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the -second optional argument to that function is @code{t}) to offer to -save that buffer, just as they offer to save file-visiting buffers. -@xref{Definition of save-some-buffers}. The variable -@code{buffer-offer-save} automatically becomes buffer-local when set -for any reason. @xref{Buffer-Local Variables}. -@end defopt - -@defvar buffer-save-without-query -This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} to save -this buffer (if it's modified) without asking the user. The variable -automatically becomes buffer-local when set for any reason. -@end defvar - -@defun buffer-live-p object -This function returns @code{t} if @var{object} is a live buffer (a -buffer which has not been killed), @code{nil} otherwise. -@end defun - -@node Indirect Buffers -@section Indirect Buffers -@cindex indirect buffers -@cindex base buffer - - An @dfn{indirect buffer} shares the text of some other buffer, which -is called the @dfn{base buffer} of the indirect buffer. In some ways it -is the analogue, for buffers, of a symbolic link among files. The base -buffer may not itself be an indirect buffer. - - The text of the indirect buffer is always identical to the text of its -base buffer; changes made by editing either one are visible immediately -in the other. This includes the text properties as well as the characters -themselves. - - In all other respects, the indirect buffer and its base buffer are -completely separate. They have different names, independent values of -point, independent narrowing, independent markers and overlays (though -inserting or deleting text in either buffer relocates the markers and -overlays for both), independent major modes, and independent -buffer-local variable bindings. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually saves the base -buffer. - - Killing an indirect buffer has no effect on its base buffer. Killing -the base buffer effectively kills the indirect buffer in that it cannot -ever again be the current buffer. - -@deffn Command make-indirect-buffer base-buffer name &optional clone -This creates and returns an indirect buffer named @var{name} whose -base buffer is @var{base-buffer}. The argument @var{base-buffer} may -be a live buffer or the name (a string) of an existing buffer. If -@var{name} is the name of an existing buffer, an error is signaled. - -If @var{clone} is non-@code{nil}, then the indirect buffer originally -shares the ``state'' of @var{base-buffer} such as major mode, minor -modes, buffer local variables and so on. If @var{clone} is omitted -or @code{nil} the indirect buffer's state is set to the default state -for new buffers. - -If @var{base-buffer} is an indirect buffer, its base buffer is used as -the base for the new buffer. If, in addition, @var{clone} is -non-@code{nil}, the initial state is copied from the actual base -buffer, not from @var{base-buffer}. -@end deffn - -@deffn Command clone-indirect-buffer newname display-flag &optional norecord -This function creates and returns a new indirect buffer that shares -the current buffer's base buffer and copies the rest of the current -buffer's attributes. (If the current buffer is not indirect, it is -used as the base buffer.) - -If @var{display-flag} is non-@code{nil}, that means to display the new -buffer by calling @code{pop-to-buffer}. If @var{norecord} is -non-@code{nil}, that means not to put the new buffer to the front of -the buffer list. -@end deffn - -@defun buffer-base-buffer &optional buffer -This function returns the base buffer of @var{buffer}, which defaults -to the current buffer. If @var{buffer} is not indirect, the value is -@code{nil}. Otherwise, the value is another buffer, which is never an -indirect buffer. -@end defun - -@node Swapping Text -@section Swapping Text Between Two Buffers -@cindex swap text between buffers -@cindex virtual buffers - - Specialized modes sometimes need to let the user access from the -same buffer several vastly different types of text. For example, you -may need to display a summary of the buffer text, in addition to -letting the user access the text itself. - - This could be implemented with multiple buffers (kept in sync when -the user edits the text), or with narrowing (@pxref{Narrowing}). But -these alternatives might sometimes become tedious or prohibitively -expensive, especially if each type of text requires expensive -buffer-global operations in order to provide correct display and -editing commands. - - Emacs provides another facility for such modes: you can quickly swap -buffer text between two buffers with @code{buffer-swap-text}. This -function is very fast because it doesn't move any text, it only -changes the internal data structures of the buffer object to point to -a different chunk of text. Using it, you can pretend that a group of -two or more buffers are actually a single virtual buffer that holds -the contents of all the individual buffers together. - -@defun buffer-swap-text buffer -This function swaps the text of the current buffer and that of its -argument @var{buffer}. It signals an error if one of the two buffers -is an indirect buffer (@pxref{Indirect Buffers}) or is a base buffer -of an indirect buffer. - -All the buffer properties that are related to the buffer text are -swapped as well: the positions of point and mark, all the markers, the -overlays, the text properties, the undo list, the value of the -@code{enable-multibyte-characters} flag (@pxref{Text Representations, -enable-multibyte-characters}), etc. -@end defun - - If you use @code{buffer-swap-text} on a file-visiting buffer, you -should set up a hook to save the buffer's original text rather than -what it was swapped with. @code{write-region-annotate-functions} -works for this purpose. You should probably set -@code{buffer-saved-size} to @minus{}2 in the buffer, so that changes -in the text it is swapped with will not interfere with auto-saving. - -@node Buffer Gap -@section The Buffer Gap - - Emacs buffers are implemented using an invisible @dfn{gap} to make -insertion and deletion faster. Insertion works by filling in part of -the gap, and deletion adds to the gap. Of course, this means that the -gap must first be moved to the locus of the insertion or deletion. -Emacs moves the gap only when you try to insert or delete. This is why -your first editing command in one part of a large buffer, after -previously editing in another far-away part, sometimes involves a -noticeable delay. - - This mechanism works invisibly, and Lisp code should never be affected -by the gap's current location, but these functions are available for -getting information about the gap status. - -@defun gap-position -This function returns the current gap position in the current buffer. -@end defun - -@defun gap-size -This function returns the current gap size of the current buffer. -@end defun diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi deleted file mode 100644 index 5e22941c037..00000000000 --- a/doc/lispref/commands.texi +++ /dev/null @@ -1,3515 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Command Loop -@chapter Command Loop -@cindex editor command loop -@cindex command loop - - When you run Emacs, it enters the @dfn{editor command loop} almost -immediately. This loop reads key sequences, executes their definitions, -and displays the results. In this chapter, we describe how these things -are done, and the subroutines that allow Lisp programs to do them. - -@menu -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. -@end menu - -@node Command Overview -@section Command Loop Overview - - The first thing the command loop must do is read a key sequence, -which is a sequence of input events that translates into a command. -It does this by calling the function @code{read-key-sequence}. Lisp -programs can also call this function (@pxref{Key Sequence Input}). -They can also read input at a lower level with @code{read-key} or -@code{read-event} (@pxref{Reading One Event}), or discard pending -input with @code{discard-input} (@pxref{Event Input Misc}). - - The key sequence is translated into a command through the currently -active keymaps. @xref{Key Lookup}, for information on how this is done. -The result should be a keyboard macro or an interactively callable -function. If the key is @kbd{M-x}, then it reads the name of another -command, which it then calls. This is done by the command -@code{execute-extended-command} (@pxref{Interactive Call}). - - Prior to executing the command, Emacs runs @code{undo-boundary} to -create an undo boundary. @xref{Maintaining Undo}. - - To execute a command, Emacs first reads its arguments by calling -@code{command-execute} (@pxref{Interactive Call}). For commands -written in Lisp, the @code{interactive} specification says how to read -the arguments. This may use the prefix argument (@pxref{Prefix -Command Arguments}) or may read with prompting in the minibuffer -(@pxref{Minibuffers}). For example, the command @code{find-file} has -an @code{interactive} specification which says to read a file name -using the minibuffer. The function body of @code{find-file} does not -use the minibuffer, so if you call @code{find-file} as a function from -Lisp code, you must supply the file name string as an ordinary Lisp -function argument. - - If the command is a keyboard macro (i.e., a string or vector), -Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard -Macros}). - -@defvar pre-command-hook -This normal hook is run by the editor command loop before it executes -each command. At that time, @code{this-command} contains the command -that is about to run, and @code{last-command} describes the previous -command. @xref{Command Loop Info}. -@end defvar - -@defvar post-command-hook -This normal hook is run by the editor command loop after it executes -each command (including commands terminated prematurely by quitting or -by errors). At that time, @code{this-command} refers to the command -that just ran, and @code{last-command} refers to the command before -that. - -This hook is also run when Emacs first enters the command loop (at -which point @code{this-command} and @code{last-command} are both -@code{nil}). -@end defvar - - Quitting is suppressed while running @code{pre-command-hook} and -@code{post-command-hook}. If an error happens while executing one of -these hooks, it does not terminate execution of the hook; instead -the error is silenced and the function in which the error occurred -is removed from the hook. - - A request coming into the Emacs server (@pxref{Emacs Server,,, -emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard -command does. - -@node Defining Commands -@section Defining Commands -@cindex defining commands -@cindex commands, defining -@cindex functions, making them interactive -@cindex interactive function - - The special form @code{interactive} turns a Lisp function into a -command. The @code{interactive} form must be located at top-level in -the function body, usually as the first form in the body; this applies -to both lambda expressions (@pxref{Lambda Expressions}) and -@code{defun} forms (@pxref{Defining Functions}). This form does -nothing during the actual execution of the function; its presence -serves as a flag, telling the Emacs command loop that the function can -be called interactively. The argument of the @code{interactive} form -specifies how the arguments for an interactive call should be read. - -@cindex @code{interactive-form} property - Alternatively, an @code{interactive} form may be specified in a -function symbol's @code{interactive-form} property. A non-@code{nil} -value for this property takes precedence over any @code{interactive} -form in the function body itself. This feature is seldom used. - -@cindex @code{interactive-only} property - Sometimes, a function is only intended to be called interactively, -never directly from Lisp. In that case, give the function a -non-@code{nil} @code{interactive-only} property. This causes the -byte compiler to warn if the command is called from Lisp. The value -of the property can be: a string, which the byte-compiler will -use directly in its warning (it should end with a period, -and not start with a capital, e.g. ``use @dots{} instead.''); @code{t}; -any other symbol, which should be an alternative function to use in -Lisp code. - -@menu -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. -* Generic Commands:: Select among command alternatives. -@end menu - -@node Using Interactive -@subsection Using @code{interactive} -@cindex arguments, interactive entry - - This section describes how to write the @code{interactive} form that -makes a Lisp function an interactively-callable command, and how to -examine a command's @code{interactive} form. - -@defspec interactive arg-descriptor -This special form declares that a function is a command, and that it -may therefore be called interactively (via @kbd{M-x} or by entering a -key sequence bound to it). The argument @var{arg-descriptor} declares -how to compute the arguments to the command when the command is called -interactively. - -A command may be called from Lisp programs like any other function, but -then the caller supplies the arguments and @var{arg-descriptor} has no -effect. - -@cindex @code{interactive-form}, symbol property -The @code{interactive} form must be located at top-level in the -function body, or in the function symbol's @code{interactive-form} -property (@pxref{Symbol Properties}). It has its effect because the -command loop looks for it before calling the function -(@pxref{Interactive Call}). Once the function is called, all its body -forms are executed; at this time, if the @code{interactive} form -occurs within the body, the form simply returns @code{nil} without -even evaluating its argument. - -By convention, you should put the @code{interactive} form in the -function body, as the first top-level form. If there is an -@code{interactive} form in both the @code{interactive-form} symbol -property and the function body, the former takes precedence. The -@code{interactive-form} symbol property can be used to add an -interactive form to an existing function, or change how its arguments -are processed interactively, without redefining the function. -@end defspec - -There are three possibilities for the argument @var{arg-descriptor}: - -@itemize @bullet -@item -It may be omitted or @code{nil}; then the command is called with no -arguments. This leads quickly to an error if the command requires one -or more arguments. - -@item -It may be a string; its contents are a sequence of elements separated -by newlines, one for each argument@footnote{Some elements actually -supply two arguments.}. Each element consists of a code character -(@pxref{Interactive Codes}) optionally followed by a prompt (which -some code characters use and some ignore). Here is an example: - -@smallexample -(interactive "P\nbFrobnicate buffer: ") -@end smallexample - -@noindent -The code letter @samp{P} sets the command's first argument to the raw -command prefix (@pxref{Prefix Command Arguments}). @samp{bFrobnicate -buffer: } prompts the user with @samp{Frobnicate buffer: } to enter -the name of an existing buffer, which becomes the second and final -argument. - -The prompt string can use @samp{%} to include previous argument values -(starting with the first argument) in the prompt. This is done using -@code{format} (@pxref{Formatting Strings}). For example, here is how -you could read the name of an existing buffer followed by a new name to -give to that buffer: - -@smallexample -@group -(interactive "bBuffer to rename: \nsRename buffer %s to: ") -@end group -@end smallexample - -@cindex @samp{*} in @code{interactive} -@cindex read-only buffers in interactive -If @samp{*} appears at the beginning of the string, then an error is -signaled if the buffer is read-only. - -@cindex @samp{@@} in @code{interactive} -If @samp{@@} appears at the beginning of the string, and if the key -sequence used to invoke the command includes any mouse events, then -the window associated with the first of those events is selected -before the command is run. - -@cindex @samp{^} in @code{interactive} -@cindex shift-selection, and @code{interactive} spec -If @samp{^} appears at the beginning of the string, and if the command -was invoked through @dfn{shift-translation}, set the mark and activate -the region temporarily, or extend an already active region, before the -command is run. If the command was invoked without shift-translation, -and the region is temporarily active, deactivate the region before the -command is run. Shift-translation is controlled on the user level by -@code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU -Emacs Manual}. - -You can use @samp{*}, @samp{@@}, and @code{^} together; the order does -not matter. Actual reading of arguments is controlled by the rest of -the prompt string (starting with the first character that is not -@samp{*}, @samp{@@}, or @samp{^}). - -@item -It may be a Lisp expression that is not a string; then it should be a -form that is evaluated to get a list of arguments to pass to the -command. Usually this form will call various functions to read input -from the user, most often through the minibuffer (@pxref{Minibuffers}) -or directly from the keyboard (@pxref{Reading Input}). - -Providing point or the mark as an argument value is also common, but -if you do this @emph{and} read input (whether using the minibuffer or -not), be sure to get the integer values of point or the mark after -reading. The current buffer may be receiving subprocess output; if -subprocess output arrives while the command is waiting for input, it -could relocate point and the mark. - -Here's an example of what @emph{not} to do: - -@smallexample -(interactive - (list (region-beginning) (region-end) - (read-string "Foo: " nil 'my-history))) -@end smallexample - -@noindent -Here's how to avoid the problem, by examining point and the mark after -reading the keyboard input: - -@smallexample -(interactive - (let ((string (read-string "Foo: " nil 'my-history))) - (list (region-beginning) (region-end) string))) -@end smallexample - -@strong{Warning:} the argument values should not include any data -types that can't be printed and then read. Some facilities save -@code{command-history} in a file to be read in the subsequent -sessions; if a command's arguments contain a data type that prints -using @samp{#<@dots{}>} syntax, those facilities won't work. - -There are, however, a few exceptions: it is ok to use a limited set of -expressions such as @code{(point)}, @code{(mark)}, -@code{(region-beginning)}, and @code{(region-end)}, because Emacs -recognizes them specially and puts the expression (rather than its -value) into the command history. To see whether the expression you -wrote is one of these exceptions, run the command, then examine -@code{(car command-history)}. -@end itemize - -@cindex examining the @code{interactive} form -@defun interactive-form function -This function returns the @code{interactive} form of @var{function}. -If @var{function} is an interactively callable function -(@pxref{Interactive Call}), the value is the command's -@code{interactive} form @code{(interactive @var{spec})}, which -specifies how to compute its arguments. Otherwise, the value is -@code{nil}. If @var{function} is a symbol, its function definition is -used. -@end defun - -@node Interactive Codes -@subsection Code Characters for @code{interactive} -@cindex interactive code description -@cindex description for interactive codes -@cindex codes, interactive, description of -@cindex characters for interactive codes - - The code character descriptions below contain a number of key words, -defined here as follows: - -@table @b -@item Completion -@cindex interactive completion -Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name -completion because the argument is read using @code{completing-read} -(@pxref{Completion}). @kbd{?} displays a list of possible completions. - -@item Existing -Require the name of an existing object. An invalid name is not -accepted; the commands to exit the minibuffer do not exit if the current -input is not valid. - -@item Default -@cindex default argument string -A default value of some sort is used if the user enters no text in the -minibuffer. The default depends on the code character. - -@item No I/O -This code letter computes an argument without reading any input. -Therefore, it does not use a prompt string, and any prompt string you -supply is ignored. - -Even though the code letter doesn't use a prompt string, you must follow -it with a newline if it is not the last code character in the string. - -@item Prompt -A prompt immediately follows the code character. The prompt ends either -with the end of the string or with a newline. - -@item Special -This code character is meaningful only at the beginning of the -interactive string, and it does not look for a prompt or a newline. -It is a single, isolated character. -@end table - -@cindex reading interactive arguments - Here are the code character descriptions for use with @code{interactive}: - -@table @samp -@item * -Signal an error if the current buffer is read-only. Special. - -@item @@ -Select the window mentioned in the first mouse event in the key -sequence that invoked this command. Special. - -@item ^ -If the command was invoked through shift-translation, set the mark and -activate the region temporarily, or extend an already active region, -before the command is run. If the command was invoked without -shift-translation, and the region is temporarily active, deactivate -the region before the command is run. Special. - -@item a -A function name (i.e., a symbol satisfying @code{fboundp}). Existing, -Completion, Prompt. - -@item b -The name of an existing buffer. By default, uses the name of the -current buffer (@pxref{Buffers}). Existing, Completion, Default, -Prompt. - -@item B -A buffer name. The buffer need not exist. By default, uses the name of -a recently used buffer other than the current buffer. Completion, -Default, Prompt. - -@item c -A character. The cursor does not move into the echo area. Prompt. - -@item C -A command name (i.e., a symbol satisfying @code{commandp}). Existing, -Completion, Prompt. - -@item d -@cindex position argument -The position of point, as an integer (@pxref{Point}). No I/O. - -@item D -A directory name. The default is the current default directory of the -current buffer, @code{default-directory} (@pxref{File Name Expansion}). -Existing, Completion, Default, Prompt. - -@item e -The first or next non-keyboard event in the key sequence that invoked -the command. More precisely, @samp{e} gets events that are lists, so -you can look at the data in the lists. @xref{Input Events}. No I/O. - -You use @samp{e} for mouse events and for special system events -(@pxref{Misc Events}). The event list that the command receives -depends on the event. @xref{Input Events}, which describes the forms -of the list for each event in the corresponding subsections. - -You can use @samp{e} more than once in a single command's interactive -specification. If the key sequence that invoked the command has -@var{n} events that are lists, the @var{n}th @samp{e} provides the -@var{n}th such event. Events that are not lists, such as function keys -and @acronym{ASCII} characters, do not count where @samp{e} is concerned. - -@item f -A file name of an existing file (@pxref{File Names}). The default -directory is @code{default-directory}. Existing, Completion, Default, -Prompt. - -@item F -A file name. The file need not exist. Completion, Default, Prompt. - -@item G -A file name. The file need not exist. If the user enters just a -directory name, then the value is just that directory name, with no -file name within the directory added. Completion, Default, Prompt. - -@item i -An irrelevant argument. This code always supplies @code{nil} as -the argument's value. No I/O. - -@item k -A key sequence (@pxref{Key Sequences}). This keeps reading events -until a command (or undefined command) is found in the current key -maps. The key sequence argument is represented as a string or vector. -The cursor does not move into the echo area. Prompt. - -If @samp{k} reads a key sequence that ends with a down-event, it also -reads and discards the following up-event. You can get access to that -up-event with the @samp{U} code character. - -This kind of input is used by commands such as @code{describe-key} and -@code{global-set-key}. - -@item K -A key sequence, whose definition you intend to change. This works like -@samp{k}, except that it suppresses, for the last input event in the key -sequence, the conversions that are normally used (when necessary) to -convert an undefined key into a defined one. - -@item m -@cindex marker argument -The position of the mark, as an integer. No I/O. - -@item M -Arbitrary text, read in the minibuffer using the current buffer's input -method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU -Emacs Manual}). Prompt. - -@item n -A number, read with the minibuffer. If the input is not a number, the -user has to try again. @samp{n} never uses the prefix argument. -Prompt. - -@item N -The numeric prefix argument; but if there is no prefix argument, read -a number as with @kbd{n}. The value is always a number. @xref{Prefix -Command Arguments}. Prompt. - -@item p -@cindex numeric prefix argument usage -The numeric prefix argument. (Note that this @samp{p} is lower case.) -No I/O. - -@item P -@cindex raw prefix argument usage -The raw prefix argument. (Note that this @samp{P} is upper case.) No -I/O. - -@item r -@cindex region argument -Point and the mark, as two numeric arguments, smallest first. This is -the only code letter that specifies two successive arguments rather than -one. No I/O. - -@item s -Arbitrary text, read in the minibuffer and returned as a string -(@pxref{Text from Minibuffer}). Terminate the input with either -@kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of -these characters in the input.) Prompt. - -@item S -An interned symbol whose name is read in the minibuffer. Terminate -the input with either @kbd{C-j} or @key{RET}. Other characters that -normally terminate a symbol (e.g., whitespace, parentheses and -brackets) do not do so here. Prompt. - -@item U -A key sequence or @code{nil}. Can be used after a @samp{k} or -@samp{K} argument to get the up-event that was discarded (if any) -after @samp{k} or @samp{K} read a down-event. If no up-event has been -discarded, @samp{U} provides @code{nil} as the argument. No I/O. - -@item v -A variable declared to be a user option (i.e., satisfying the -predicate @code{custom-variable-p}). This reads the variable using -@code{read-variable}. @xref{Definition of read-variable}. Existing, -Completion, Prompt. - -@item x -A Lisp object, specified with its read syntax, terminated with a -@kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from -Minibuffer}. Prompt. - -@item X -@cindex evaluated expression argument -A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates -the form so that its value becomes the argument for the command. -Prompt. - -@item z -A coding system name (a symbol). If the user enters null input, the -argument value is @code{nil}. @xref{Coding Systems}. Completion, -Existing, Prompt. - -@item Z -A coding system name (a symbol)---but only if this command has a prefix -argument. With no prefix argument, @samp{Z} provides @code{nil} as the -argument value. Completion, Existing, Prompt. -@end table - -@node Interactive Examples -@subsection Examples of Using @code{interactive} -@cindex examples of using @code{interactive} -@cindex @code{interactive}, examples of using - - Here are some examples of @code{interactive}: - -@example -@group -(defun foo1 () ; @r{@code{foo1} takes no arguments,} - (interactive) ; @r{just moves forward two words.} - (forward-word 2)) - @result{} foo1 -@end group - -@group -(defun foo2 (n) ; @r{@code{foo2} takes one argument,} - (interactive "^p") ; @r{which is the numeric prefix.} - ; @r{under @code{shift-select-mode},} - ; @r{will activate or extend region.} - (forward-word (* 2 n))) - @result{} foo2 -@end group - -@group -(defun foo3 (n) ; @r{@code{foo3} takes one argument,} - (interactive "nCount:") ; @r{which is read with the Minibuffer.} - (forward-word (* 2 n))) - @result{} foo3 -@end group - -@group -(defun three-b (b1 b2 b3) - "Select three existing buffers. -Put them into three windows, selecting the last one." -@end group - (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") - (delete-other-windows) - (split-window (selected-window) 8) - (switch-to-buffer b1) - (other-window 1) - (split-window (selected-window) 8) - (switch-to-buffer b2) - (other-window 1) - (switch-to-buffer b3)) - @result{} three-b -@group -(three-b "*scratch*" "declarations.texi" "*mail*") - @result{} nil -@end group -@end example - -@node Generic Commands -@subsection Select among Command Alternatives -@cindex generic commands -@cindex alternatives, defining - -The macro @code{define-alternatives} can be used to define -@dfn{generic commands}. These are interactive functions whose -implementation can be selected from several alternatives, as a matter -of user preference. - -@defmac define-alternatives command &rest customizations -Define the new command @var{command}, a symbol. - -When a user runs @kbd{M-x @var{command} @key{RET}} for the first time, -Emacs prompts for which real form of the command to use, and records -the selection by way of a custom variable. Using a prefix argument -repeats this process of choosing an alternative. - -The variable @code{@var{command}-alternatives} should contain an alist -with alternative implementations of @var{command}. -Until this variable is set, @code{define-alternatives} has no effect. - -If @var{customizations} is non-@code{nil}, it should consist of -alternating @code{defcustom} keywords (typically @code{:group} and -@code{:version}) and values to add to the declaration of -@code{@var{command}-alternatives}. -@end defmac - -@node Interactive Call -@section Interactive Call -@cindex interactive call - - After the command loop has translated a key sequence into a command, -it invokes that command using the function @code{command-execute}. If -the command is a function, @code{command-execute} calls -@code{call-interactively}, which reads the arguments and calls the -command. You can also call these functions yourself. - - Note that the term ``command'', in this context, refers to an -interactively callable function (or function-like object), or a -keyboard macro. It does not refer to the key sequence used to invoke -a command (@pxref{Keymaps}). - -@defun commandp object &optional for-call-interactively -This function returns @code{t} if @var{object} is a command. -Otherwise, it returns @code{nil}. - -Commands include strings and vectors (which are treated as keyboard -macros), lambda expressions that contain a top-level -@code{interactive} form (@pxref{Using Interactive}), byte-code -function objects made from such lambda expressions, autoload objects -that are declared as interactive (non-@code{nil} fourth argument to -@code{autoload}), and some primitive functions. Also, a symbol is -considered a command if it has a non-@code{nil} -@code{interactive-form} property, or if its function definition -satisfies @code{commandp}. - -If @var{for-call-interactively} is non-@code{nil}, then -@code{commandp} returns @code{t} only for objects that -@code{call-interactively} could call---thus, not for keyboard macros. - -See @code{documentation} in @ref{Accessing Documentation}, for a -realistic example of using @code{commandp}. -@end defun - -@defun call-interactively command &optional record-flag keys -This function calls the interactively callable function @var{command}, -providing arguments according to its interactive calling specifications. -It returns whatever @var{command} returns. - -If, for instance, you have a function with the following signature: - -@example -(defun foo (begin end) - (interactive "r") - ...) -@end example - -then saying - -@example -(call-interactively 'foo) -@end example - -will call @code{foo} with the region (@code{point} and @code{mark}) as -the arguments. - -An error is signaled if @var{command} is not a function or if it -cannot be called interactively (i.e., is not a command). Note that -keyboard macros (strings and vectors) are not accepted, even though -they are considered commands, because they are not functions. If -@var{command} is a symbol, then @code{call-interactively} uses its -function definition. - -@cindex record command history -If @var{record-flag} is non-@code{nil}, then this command and its -arguments are unconditionally added to the list @code{command-history}. -Otherwise, the command is added only if it uses the minibuffer to read -an argument. @xref{Command History}. - -The argument @var{keys}, if given, should be a vector which specifies -the sequence of events to supply if the command inquires which events -were used to invoke it. If @var{keys} is omitted or @code{nil}, the -default is the return value of @code{this-command-keys-vector}. -@xref{Definition of this-command-keys-vector}. -@end defun - -@defun command-execute command &optional record-flag keys special -@cindex keyboard macro execution -This function executes @var{command}. The argument @var{command} must -satisfy the @code{commandp} predicate; i.e., it must be an interactively -callable function or a keyboard macro. - -A string or vector as @var{command} is executed with -@code{execute-kbd-macro}. A function is passed to -@code{call-interactively} (see above), along with the -@var{record-flag} and @var{keys} arguments. - -If @var{command} is a symbol, its function definition is used in its -place. A symbol with an @code{autoload} definition counts as a -command if it was declared to stand for an interactively callable -function. Such a definition is handled by loading the specified -library and then rechecking the definition of the symbol. - -The argument @var{special}, if given, means to ignore the prefix -argument and not clear it. This is used for executing special events -(@pxref{Special Events}). -@end defun - -@deffn Command execute-extended-command prefix-argument -@cindex read command name -This function reads a command name from the minibuffer using -@code{completing-read} (@pxref{Completion}). Then it uses -@code{command-execute} to call the specified command. Whatever that -command returns becomes the value of @code{execute-extended-command}. - -@cindex execute with prefix argument -If the command asks for a prefix argument, it receives the value -@var{prefix-argument}. If @code{execute-extended-command} is called -interactively, the current raw prefix argument is used for -@var{prefix-argument}, and thus passed on to whatever command is run. - -@c !!! Should this be @kindex? -@cindex @kbd{M-x} -@code{execute-extended-command} is the normal definition of @kbd{M-x}, -so it uses the string @w{@samp{M-x }} as a prompt. (It would be better -to take the prompt from the events used to invoke -@code{execute-extended-command}, but that is painful to implement.) A -description of the value of the prefix argument, if any, also becomes -part of the prompt. - -@example -@group -(execute-extended-command 3) ----------- Buffer: Minibuffer ---------- -3 M-x forward-word RET ----------- Buffer: Minibuffer ---------- - @result{} t -@end group -@end example -@end deffn - -@node Distinguish Interactive -@section Distinguish Interactive Calls - - Sometimes a command should display additional visual feedback (such -as an informative message in the echo area) for interactive calls -only. There are three ways to do this. The recommended way to test -whether the function was called using @code{call-interactively} is to -give it an optional argument @code{print-message} and use the -@code{interactive} spec to make it non-@code{nil} in interactive -calls. Here's an example: - -@example -(defun foo (&optional print-message) - (interactive "p") - (when print-message - (message "foo"))) -@end example - -@noindent -We use @code{"p"} because the numeric prefix argument is never -@code{nil}. Defined in this way, the function does display the -message when called from a keyboard macro. - - The above method with the additional argument is usually best, -because it allows callers to say ``treat this call as interactive''. -But you can also do the job by testing @code{called-interactively-p}. - -@defun called-interactively-p kind -This function returns @code{t} when the calling function was called -using @code{call-interactively}. - -The argument @var{kind} should be either the symbol @code{interactive} -or the symbol @code{any}. If it is @code{interactive}, then -@code{called-interactively-p} returns @code{t} only if the call was -made directly by the user---e.g., if the user typed a key sequence -bound to the calling function, but @emph{not} if the user ran a -keyboard macro that called the function (@pxref{Keyboard Macros}). If -@var{kind} is @code{any}, @code{called-interactively-p} returns -@code{t} for any kind of interactive call, including keyboard macros. - -If in doubt, use @code{any}; the only known proper use of -@code{interactive} is if you need to decide whether to display a -helpful message while a function is running. - -A function is never considered to be called interactively if it was -called via Lisp evaluation (or with @code{apply} or @code{funcall}). -@end defun - -@noindent -Here is an example of using @code{called-interactively-p}: - -@example -@group -(defun foo () - (interactive) - (when (called-interactively-p 'any) - (message "Interactive!") - 'foo-called-interactively)) -@end group - -@group -;; @r{Type @kbd{M-x foo}.} - @print{} Interactive! -@end group - -@group -(foo) - @result{} nil -@end group -@end example - -@noindent -Here is another example that contrasts direct and indirect calls to -@code{called-interactively-p}. - -@example -@group -(defun bar () - (interactive) - (message "%s" (list (foo) (called-interactively-p 'any)))) -@end group - -@group -;; @r{Type @kbd{M-x bar}.} - @print{} (nil t) -@end group -@end example - -@node Command Loop Info -@section Information from the Command Loop - -The editor command loop sets several Lisp variables to keep status -records for itself and for commands that are run. With the exception of -@code{this-command} and @code{last-command} it's generally a bad idea to -change any of these variables in a Lisp program. - -@defvar last-command -This variable records the name of the previous command executed by the -command loop (the one before the current command). Normally the value -is a symbol with a function definition, but this is not guaranteed. - -The value is copied from @code{this-command} when a command returns to -the command loop, except when the command has specified a prefix -argument for the following command. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -@defvar real-last-command -This variable is set up by Emacs just like @code{last-command}, -but never altered by Lisp programs. -@end defvar - -@defvar last-repeatable-command -This variable stores the most recently executed command that was not -part of an input event. This is the command @code{repeat} will try to -repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}. -@end defvar - -@defvar this-command -@cindex current command -This variable records the name of the command now being executed by -the editor command loop. Like @code{last-command}, it is normally a symbol -with a function definition. - -The command loop sets this variable just before running a command, and -copies its value into @code{last-command} when the command finishes -(unless the command specified a prefix argument for the following -command). - -@cindex kill command repetition -Some commands set this variable during their execution, as a flag for -whatever command runs next. In particular, the functions for killing text -set @code{this-command} to @code{kill-region} so that any kill commands -immediately following will know to append the killed text to the -previous kill. -@end defvar - -If you do not want a particular command to be recognized as the previous -command in the case where it got an error, you must code that command to -prevent this. One way is to set @code{this-command} to @code{t} at the -beginning of the command, and set @code{this-command} back to its proper -value at the end, like this: - -@example -(defun foo (args@dots{}) - (interactive @dots{}) - (let ((old-this-command this-command)) - (setq this-command t) - @r{@dots{}do the work@dots{}} - (setq this-command old-this-command))) -@end example - -@noindent -We do not bind @code{this-command} with @code{let} because that would -restore the old value in case of error---a feature of @code{let} which -in this case does precisely what we want to avoid. - -@defvar this-original-command -This has the same value as @code{this-command} except when command -remapping occurs (@pxref{Remapping Commands}). In that case, -@code{this-command} gives the command actually run (the result of -remapping), and @code{this-original-command} gives the command that -was specified to run but remapped into another command. -@end defvar - -@defun this-command-keys -This function returns a string or vector containing the key sequence -that invoked the present command, plus any previous commands that -generated the prefix argument for this command. Any events read by the -command using @code{read-event} without a timeout get tacked on to the end. - -However, if the command has called @code{read-key-sequence}, it -returns the last read key sequence. @xref{Key Sequence Input}. The -value is a string if all events in the sequence were characters that -fit in a string. @xref{Input Events}. - -@example -@group -(this-command-keys) -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} "^U^X^E" -@end group -@end example -@end defun - -@defun this-command-keys-vector -@anchor{Definition of this-command-keys-vector} -Like @code{this-command-keys}, except that it always returns the events -in a vector, so you don't need to deal with the complexities of storing -input events in a string (@pxref{Strings of Events}). -@end defun - -@defun clear-this-command-keys &optional keep-record -This function empties out the table of events for -@code{this-command-keys} to return. Unless @var{keep-record} is -non-@code{nil}, it also empties the records that the function -@code{recent-keys} (@pxref{Recording Input}) will subsequently return. -This is useful after reading a password, to prevent the password from -echoing inadvertently as part of the next command in certain cases. -@end defun - -@defvar last-nonmenu-event -This variable holds the last input event read as part of a key sequence, -not counting events resulting from mouse menus. - -One use of this variable is for telling @code{x-popup-menu} where to pop -up a menu. It is also used internally by @code{y-or-n-p} -(@pxref{Yes-or-No Queries}). -@end defvar - -@defvar last-command-event -This variable is set to the last input event that was read by the -command loop as part of a command. The principal use of this variable -is in @code{self-insert-command}, which uses it to decide which -character to insert. - -@example -@group -last-command-event -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} 5 -@end group -@end example - -@noindent -The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}. -@end defvar - -@defvar last-event-frame -This variable records which frame the last input event was directed to. -Usually this is the frame that was selected when the event was -generated, but if that frame has redirected input focus to another -frame, the value is the frame to which the event was redirected. -@xref{Input Focus}. - -If the last event came from a keyboard macro, the value is @code{macro}. -@end defvar - -@node Adjusting Point -@section Adjusting Point After Commands -@cindex adjusting point -@cindex invisible/intangible text, and point -@cindex @code{display} property, and point display -@cindex @code{composition} property, and point display - - It is not easy to display a value of point in the middle of a -sequence of text that has the @code{display}, @code{composition} or -is invisible. Therefore, after a command finishes and returns to the -command loop, if point is within such a sequence, the command loop -normally moves point to the edge of the sequence. - - A command can inhibit this feature by setting the variable -@code{disable-point-adjustment}: - -@defvar disable-point-adjustment -If this variable is non-@code{nil} when a command returns to the -command loop, then the command loop does not check for those text -properties, and does not move point out of sequences that have them. - -The command loop sets this variable to @code{nil} before each command, -so if a command sets it, the effect applies only to that command. -@end defvar - -@defvar global-disable-point-adjustment -If you set this variable to a non-@code{nil} value, the feature of -moving point out of these sequences is completely turned off. -@end defvar - -@node Input Events -@section Input Events -@cindex events -@cindex input events - -The Emacs command loop reads a sequence of @dfn{input events} that -represent keyboard or mouse activity, or system events sent to Emacs. -The events for keyboard activity are characters or symbols; other -events are always lists. This section describes the representation -and meaning of input events in detail. - -@defun eventp object -This function returns non-@code{nil} if @var{object} is an input event -or event type. - -Note that any symbol might be used as an event or an event type. -@code{eventp} cannot distinguish whether a symbol is intended by Lisp -code to be used as an event. Instead, it distinguishes whether the -symbol has actually been used in an event that has been read as input in -the current Emacs session. If a symbol has not yet been so used, -@code{eventp} returns @code{nil}. -@end defun - -@menu -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. -@end menu - -@node Keyboard Events -@subsection Keyboard Events -@cindex keyboard events - -There are two kinds of input you can get from the keyboard: ordinary -keys, and function keys. Ordinary keys correspond to characters; the -events they generate are represented in Lisp as characters. The event -type of a character event is the character itself (an integer); see -@ref{Classifying Events}. - -@cindex modifier bits (of input character) -@cindex basic code (of input character) -An input character event consists of a @dfn{basic code} between 0 and -524287, plus any or all of these @dfn{modifier bits}: - -@table @asis -@item meta -The -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit in the character code indicates a character -typed with the meta key held down. - -@item control -The -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -bit in the character code indicates a non-@acronym{ASCII} -control character. - -@sc{ascii} control characters such as @kbd{C-a} have special basic -codes of their own, so Emacs needs no special bit to indicate them. -Thus, the code for @kbd{C-a} is just 1. - -But if you type a control combination not in @acronym{ASCII}, such as -@kbd{%} with the control key, the numeric value you get is the code -for @kbd{%} plus -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -(assuming the terminal supports non-@acronym{ASCII} -control characters). - -@item shift -The -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit in the character code indicates an @acronym{ASCII} control -character typed with the shift key held down. - -For letters, the basic code itself indicates upper versus lower case; -for digits and punctuation, the shift key selects an entirely different -character with a different basic code. In order to keep within the -@acronym{ASCII} character set whenever possible, Emacs avoids using the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit for those characters. - -However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from -@kbd{C-a}, so Emacs uses the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit in @kbd{C-A} and not in -@kbd{C-a}. - -@item hyper -The -@tex -@math{2^{24}} -@end tex -@ifnottex -2**24 -@end ifnottex -bit in the character code indicates a character -typed with the hyper key held down. - -@item super -The -@tex -@math{2^{23}} -@end tex -@ifnottex -2**23 -@end ifnottex -bit in the character code indicates a character -typed with the super key held down. - -@item alt -The -@tex -@math{2^{22}} -@end tex -@ifnottex -2**22 -@end ifnottex -bit in the character code indicates a character typed with the alt key -held down. (The key labeled @key{Alt} on most keyboards is actually -treated as the meta key, not this.) -@end table - - It is best to avoid mentioning specific bit numbers in your program. -To test the modifier bits of a character, use the function -@code{event-modifiers} (@pxref{Classifying Events}). When making key -bindings, you can use the read syntax for characters with modifier bits -(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with -@code{define-key}, you can use lists such as @code{(control hyper ?x)} to -specify the characters (@pxref{Changing Key Bindings}). The function -@code{event-convert-list} converts such a list into an event type -(@pxref{Classifying Events}). - -@node Function Keys -@subsection Function Keys - -@cindex function keys -Most keyboards also have @dfn{function keys}---keys that have names or -symbols that are not characters. Function keys are represented in -Emacs Lisp as symbols; the symbol's name is the function key's label, -in lower case. For example, pressing a key labeled @key{F1} generates -an input event represented by the symbol @code{f1}. - -The event type of a function key event is the event symbol itself. -@xref{Classifying Events}. - -Here are a few special cases in the symbol-naming convention for -function keys: - -@table @asis -@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete} -These keys correspond to common @acronym{ASCII} control characters that have -special keys on most keyboards. - -In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the -terminal can distinguish between them, Emacs conveys the distinction to -Lisp programs by representing the former as the integer 9, and the -latter as the symbol @code{tab}. - -Most of the time, it's not useful to distinguish the two. So normally -@code{local-function-key-map} (@pxref{Translation Keymaps}) is set up -to map @code{tab} into 9. Thus, a key binding for character code 9 -(the character @kbd{C-i}) also applies to @code{tab}. Likewise for -the other symbols in this group. The function @code{read-char} -likewise converts these events into characters. - -In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace} -converts into the character code 127 (@key{DEL}), not into code 8 -(@key{BS}). This is what most users prefer. - -@item @code{left}, @code{up}, @code{right}, @code{down} -Cursor arrow keys -@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{} -Keypad keys (to the right of the regular keyboard). -@item @code{kp-0}, @code{kp-1}, @dots{} -Keypad keys with digits. -@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} -Keypad PF keys. -@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down} -Keypad arrow keys. Emacs normally translates these into the -corresponding non-keypad keys @code{home}, @code{left}, @dots{} -@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete} -Additional keypad duplicates of keys ordinarily found elsewhere. Emacs -normally translates these into the like-named non-keypad keys. -@end table - -You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER}, -@key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to -represent them is with prefixes in the symbol name: - -@table @samp -@item A- -The alt modifier. -@item C- -The control modifier. -@item H- -The hyper modifier. -@item M- -The meta modifier. -@item S- -The shift modifier. -@item s- -The super modifier. -@end table - -Thus, the symbol for the key @key{F3} with @key{META} held down is -@code{M-f3}. When you use more than one prefix, we recommend you -write them in alphabetical order; but the order does not matter in -arguments to the key-binding lookup and modification functions. - -@node Mouse Events -@subsection Mouse Events - -Emacs supports four kinds of mouse events: click events, drag events, -button-down events, and motion events. All mouse events are represented -as lists. The @sc{car} of the list is the event type; this says which -mouse button was involved, and which modifier keys were used with it. -The event type can also distinguish double or triple button presses -(@pxref{Repeat Events}). The rest of the list elements give position -and time information. - -For key lookup, only the event type matters: two events of the same type -necessarily run the same command. The command can access the full -values of these events using the @samp{e} interactive code. -@xref{Interactive Codes}. - -A key sequence that starts with a mouse event is read using the keymaps -of the buffer in the window that the mouse was in, not the current -buffer. This does not imply that clicking in a window selects that -window or its buffer---that is entirely under the control of the command -binding of the key sequence. - -@node Click Events -@subsection Click Events -@cindex click event -@cindex mouse click event - -When the user presses a mouse button and releases it at the same -location, that generates a @dfn{click} event. All mouse click event -share the same format: - -@example -(@var{event-type} @var{position} @var{click-count}) -@end example - -@table @asis -@item @var{event-type} -This is a symbol that indicates which mouse button was used. It is -one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the -buttons are numbered left to right. - -You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, -@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift -and super, just as you would with function keys. - -This symbol also serves as the event type of the event. Key bindings -describe events by their types; thus, if there is a key binding for -@code{mouse-1}, that binding would apply to all events whose -@var{event-type} is @code{mouse-1}. - -@item @var{position} -@cindex mouse position list -This is a @dfn{mouse position list} specifying where the mouse click -occurred; see below for details. - -@item @var{click-count} -This is the number of rapid repeated presses so far of the same mouse -button. @xref{Repeat Events}. -@end table - - To access the contents of a mouse position list in the -@var{position} slot of a click event, you should typically use the -functions documented in @ref{Accessing Mouse}. The explicit format of -the list depends on where the click occurred. For clicks in the text -area, mode line, header line, or in the fringe or marginal areas, the -mouse position list has the form - -@example -(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} - @var{object} @var{text-pos} (@var{col} . @var{row}) - @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) -@end example - -@noindent -The meanings of these list elements are as follows: - -@table @asis -@item @var{window} -The window in which the click occurred. - -@item @var{pos-or-area} -The buffer position of the character clicked on in the text area; or, -if the click was outside the text area, the window area where it -occurred. It is one of the symbols @code{mode-line}, -@code{header-line}, @code{vertical-line}, @code{left-margin}, -@code{right-margin}, @code{left-fringe}, or @code{right-fringe}. - -In one special case, @var{pos-or-area} is a list containing a symbol -(one of the symbols listed above) instead of just the symbol. This -happens after the imaginary prefix keys for the event are registered -by Emacs. @xref{Key Sequence Input}. - -@item @var{x}, @var{y} -The relative pixel coordinates of the click. For clicks in the text -area of a window, the coordinate origin @code{(0 . 0)} is taken to be -the top left corner of the text area. @xref{Window Sizes}. For -clicks in a mode line or header line, the coordinate origin is the top -left corner of the window itself. For fringes, margins, and the -vertical border, @var{x} does not have meaningful data. For fringes -and margins, @var{y} is relative to the bottom edge of the header -line. In all cases, the @var{x} and @var{y} coordinates increase -rightward and downward respectively. - -@item @var{timestamp} -The time at which the event occurred, as an integer number of -milliseconds since a system-dependent initial time. - -@item @var{object} -Either @code{nil} if there is no string-type text property at the -click position, or a cons cell of the form (@var{string} -. @var{string-pos}) if there is one: - -@table @asis -@item @var{string} -The string which was clicked on, including any properties. - -@item @var{string-pos} -The position in the string where the click occurred. -@end table - -@item @var{text-pos} -For clicks on a marginal area or on a fringe, this is the buffer -position of the first visible character in the corresponding line in -the window. For other events, it is the current buffer position in -the window. - -@item @var{col}, @var{row} -These are the actual column and row coordinate numbers of the glyph -under the @var{x}, @var{y} position. If @var{x} lies beyond the last -column of actual text on its line, @var{col} is reported by adding -fictional extra columns that have the default character width. Row 0 -is taken to be the header line if the window has one, or the topmost -row of the text area otherwise. Column 0 is taken to be the leftmost -column of the text area for clicks on a window text area, or the -leftmost mode line or header line column for clicks there. For clicks -on fringes or vertical borders, these have no meaningful data. For -clicks on margins, @var{col} is measured from the left edge of the -margin area and @var{row} is measured from the top of the margin area. - -@item @var{image} -This is the image object on which the click occurred. It is either -@code{nil} if there is no image at the position clicked on, or it is -an image object as returned by @code{find-image} if click was in an image. - -@item @var{dx}, @var{dy} -These are the pixel coordinates of the click, relative to -the top left corner of @var{object}, which is @code{(0 . 0)}. If -@var{object} is @code{nil}, the coordinates are relative to the top -left corner of the character glyph clicked on. - -@item @var{width}, @var{height} -These are the pixel width and height of @var{object} or, if this is -@code{nil}, those of the character glyph clicked on. -@end table - -For clicks on a scroll bar, @var{position} has this form: - -@example -(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part}) -@end example - -@table @asis -@item @var{window} -The window whose scroll bar was clicked on. - -@item @var{area} -This is the symbol @code{vertical-scroll-bar}. - -@item @var{portion} -The number of pixels from the top of the scroll bar to the click -position. On some toolkits, including GTK+, Emacs cannot extract this -data, so the value is always @code{0}. - -@item @var{whole} -The total length, in pixels, of the scroll bar. On some toolkits, -including GTK+, Emacs cannot extract this data, so the value is always -@code{0}. - -@item @var{timestamp} -The time at which the event occurred, in milliseconds. On some -toolkits, including GTK+, Emacs cannot extract this data, so the value -is always @code{0}. - -@item @var{part} -The part of the scroll bar on which the click occurred. It is one of -the symbols @code{handle} (the scroll bar handle), @code{above-handle} -(the area above the handle), @code{below-handle} (the area below the -handle), @code{up} (the up arrow at one end of the scroll bar), or -@code{down} (the down arrow at one end of the scroll bar). -@c The `top', `bottom', and `end-scroll' codes don't seem to be used. -@end table - - -@node Drag Events -@subsection Drag Events -@cindex drag event -@cindex mouse drag event - -With Emacs, you can have a drag event without even changing your -clothes. A @dfn{drag event} happens every time the user presses a mouse -button and then moves the mouse to a different character position before -releasing the button. Like all mouse events, drag events are -represented in Lisp as lists. The lists record both the starting mouse -position and the final position, like this: - -@example -(@var{event-type} - (@var{window1} START-POSITION) - (@var{window2} END-POSITION)) -@end example - -For a drag event, the name of the symbol @var{event-type} contains the -prefix @samp{drag-}. For example, dragging the mouse with button 2 -held down generates a @code{drag-mouse-2} event. The second and third -elements of the event give the starting and ending position of the -drag, as mouse position lists (@pxref{Click Events}). You can access -the second element of any mouse event in the same way, with no need to -distinguish drag events from others. - -The @samp{drag-} prefix follows the modifier key prefixes such as -@samp{C-} and @samp{M-}. - -If @code{read-key-sequence} receives a drag event that has no key -binding, and the corresponding click event does have a binding, it -changes the drag event into a click event at the drag's starting -position. This means that you don't have to distinguish between click -and drag events unless you want to. - -@node Button-Down Events -@subsection Button-Down Events -@cindex button-down event - -Click and drag events happen when the user releases a mouse button. -They cannot happen earlier, because there is no way to distinguish a -click from a drag until the button is released. - -If you want to take action as soon as a button is pressed, you need to -handle @dfn{button-down} events.@footnote{Button-down is the -conservative antithesis of drag.} These occur as soon as a button is -pressed. They are represented by lists that look exactly like click -events (@pxref{Click Events}), except that the @var{event-type} symbol -name contains the prefix @samp{down-}. The @samp{down-} prefix follows -modifier key prefixes such as @samp{C-} and @samp{M-}. - -The function @code{read-key-sequence} ignores any button-down events -that don't have command bindings; therefore, the Emacs command loop -ignores them too. This means that you need not worry about defining -button-down events unless you want them to do something. The usual -reason to define a button-down event is so that you can track mouse -motion (by reading motion events) until the button is released. -@xref{Motion Events}. - -@node Repeat Events -@subsection Repeat Events -@cindex repeat events -@cindex double-click events -@cindex triple-click events -@cindex mouse events, repeated - -If you press the same mouse button more than once in quick succession -without moving the mouse, Emacs generates special @dfn{repeat} mouse -events for the second and subsequent presses. - -The most common repeat events are @dfn{double-click} events. Emacs -generates a double-click event when you click a button twice; the event -happens when you release the button (as is normal for all click -events). - -The event type of a double-click event contains the prefix -@samp{double-}. Thus, a double click on the second mouse button with -@key{meta} held down comes to the Lisp program as -@code{M-double-mouse-2}. If a double-click event has no binding, the -binding of the corresponding ordinary click event is used to execute -it. Thus, you need not pay attention to the double click feature -unless you really want to. - -When the user performs a double click, Emacs generates first an ordinary -click event, and then a double-click event. Therefore, you must design -the command binding of the double click event to assume that the -single-click command has already run. It must produce the desired -results of a double click, starting from the results of a single click. - -This is convenient, if the meaning of a double click somehow ``builds -on'' the meaning of a single click---which is recommended user interface -design practice for double clicks. - -If you click a button, then press it down again and start moving the -mouse with the button held down, then you get a @dfn{double-drag} event -when you ultimately release the button. Its event type contains -@samp{double-drag} instead of just @samp{drag}. If a double-drag event -has no binding, Emacs looks for an alternate binding as if the event -were an ordinary drag. - -Before the double-click or double-drag event, Emacs generates a -@dfn{double-down} event when the user presses the button down for the -second time. Its event type contains @samp{double-down} instead of just -@samp{down}. If a double-down event has no binding, Emacs looks for an -alternate binding as if the event were an ordinary button-down event. -If it finds no binding that way either, the double-down event is -ignored. - -To summarize, when you click a button and then press it again right -away, Emacs generates a down event and a click event for the first -click, a double-down event when you press the button again, and finally -either a double-click or a double-drag event. - -If you click a button twice and then press it again, all in quick -succession, Emacs generates a @dfn{triple-down} event, followed by -either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of -these events contain @samp{triple} instead of @samp{double}. If any -triple event has no binding, Emacs uses the binding that it would use -for the corresponding double event. - -If you click a button three or more times and then press it again, the -events for the presses beyond the third are all triple events. Emacs -does not have separate event types for quadruple, quintuple, etc.@: -events. However, you can look at the event list to find out precisely -how many times the button was pressed. - -@defun event-click-count event -This function returns the number of consecutive button presses that led -up to @var{event}. If @var{event} is a double-down, double-click or -double-drag event, the value is 2. If @var{event} is a triple event, -the value is 3 or greater. If @var{event} is an ordinary mouse event -(not a repeat event), the value is 1. -@end defun - -@defopt double-click-fuzz -To generate repeat events, successive mouse button presses must be at -approximately the same screen position. The value of -@code{double-click-fuzz} specifies the maximum number of pixels the -mouse may be moved (horizontally or vertically) between two successive -clicks to make a double-click. - -This variable is also the threshold for motion of the mouse to count -as a drag. -@end defopt - -@defopt double-click-time -To generate repeat events, the number of milliseconds between -successive button presses must be less than the value of -@code{double-click-time}. Setting @code{double-click-time} to -@code{nil} disables multi-click detection entirely. Setting it to -@code{t} removes the time limit; Emacs then detects multi-clicks by -position only. -@end defopt - -@node Motion Events -@subsection Motion Events -@cindex motion event -@cindex mouse motion events - -Emacs sometimes generates @dfn{mouse motion} events to describe motion -of the mouse without any button activity. Mouse motion events are -represented by lists that look like this: - -@example -(mouse-movement POSITION) -@end example - -@noindent -@var{position} is a mouse position list (@pxref{Click Events}), -specifying the current position of the mouse cursor. - -The special form @code{track-mouse} enables generation of motion -events within its body. Outside of @code{track-mouse} forms, Emacs -does not generate events for mere motion of the mouse, and these -events do not appear. @xref{Mouse Tracking}. - -@node Focus Events -@subsection Focus Events -@cindex focus event - -Window systems provide general ways for the user to control which window -gets keyboard input. This choice of window is called the @dfn{focus}. -When the user does something to switch between Emacs frames, that -generates a @dfn{focus event}. The normal definition of a focus event, -in the global keymap, is to select a new frame within Emacs, as the user -would expect. @xref{Input Focus}. - -Focus events are represented in Lisp as lists that look like this: - -@example -(switch-frame @var{new-frame}) -@end example - -@noindent -where @var{new-frame} is the frame switched to. - -Some X window managers are set up so that just moving the mouse into a -window is enough to set the focus there. Usually, there is no need -for a Lisp program to know about the focus change until some other -kind of input arrives. Emacs generates a focus event only when the -user actually types a keyboard key or presses a mouse button in the -new frame; just moving the mouse between frames does not generate a -focus event. - -A focus event in the middle of a key sequence would garble the -sequence. So Emacs never generates a focus event in the middle of a key -sequence. If the user changes focus in the middle of a key -sequence---that is, after a prefix key---then Emacs reorders the events -so that the focus event comes either before or after the multi-event key -sequence, and not within it. - -@node Misc Events -@subsection Miscellaneous System Events - -A few other event types represent occurrences within the system. - -@table @code -@cindex @code{delete-frame} event -@item (delete-frame (@var{frame})) -This kind of event indicates that the user gave the window manager -a command to delete a particular window, which happens to be an Emacs frame. - -The standard definition of the @code{delete-frame} event is to delete @var{frame}. - -@cindex @code{iconify-frame} event -@item (iconify-frame (@var{frame})) -This kind of event indicates that the user iconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been iconified, Emacs has no work to do. The purpose -of this event type is so that you can keep track of such events if you -want to. - -@cindex @code{make-frame-visible} event -@item (make-frame-visible (@var{frame})) -This kind of event indicates that the user deiconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been made visible, Emacs has no work to do. - -@cindex @code{wheel-up} event -@cindex @code{wheel-down} event -@item (wheel-up @var{position}) -@itemx (wheel-down @var{position}) -These kinds of event are generated by moving a mouse wheel. The -@var{position} element is a mouse position list (@pxref{Click -Events}), specifying the position of the mouse cursor when the event -occurred. - -@vindex mouse-wheel-up-event -@vindex mouse-wheel-down-event -This kind of event is generated only on some kinds of systems. On some -systems, @code{mouse-4} and @code{mouse-5} are used instead. For -portable code, use the variables @code{mouse-wheel-up-event} and -@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine -what event types to expect for the mouse wheel. - -@cindex @code{drag-n-drop} event -@item (drag-n-drop @var{position} @var{files}) -This kind of event is generated when a group of files is -selected in an application outside of Emacs, and then dragged and -dropped onto an Emacs frame. - -The element @var{position} is a list describing the position of the -event, in the same format as used in a mouse-click event (@pxref{Click -Events}), and @var{files} is the list of file names that were dragged -and dropped. The usual way to handle this event is by visiting these -files. - -This kind of event is generated, at present, only on some kinds of -systems. - -@cindex @code{help-echo} event -@item help-echo -This kind of event is generated when a mouse pointer moves onto a -portion of buffer text which has a @code{help-echo} text property. -The generated event has this form: - -@example -(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos}) -@end example - -@noindent -The precise meaning of the event parameters and the way these -parameters are used to display the help-echo text are described in -@ref{Text help-echo}. - -@cindex @code{sigusr1} event -@cindex @code{sigusr2} event -@cindex user signals -@item sigusr1 -@itemx sigusr2 -These events are generated when the Emacs process receives -the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no -additional data because signals do not carry additional information. -They can be useful for debugging (@pxref{Error Debugging}). - -To catch a user signal, bind the corresponding event to an interactive -command in the @code{special-event-map} (@pxref{Active Keymaps}). -The command is called with no arguments, and the specific signal event is -available in @code{last-input-event}. For example: - -@smallexample -(defun sigusr-handler () - (interactive) - (message "Caught signal %S" last-input-event)) - -(define-key special-event-map [sigusr1] 'sigusr-handler) -@end smallexample - -To test the signal handler, you can make Emacs send a signal to itself: - -@smallexample -(signal-process (emacs-pid) 'sigusr1) -@end smallexample - -@cindex @code{language-change} event -@item language-change -This kind of event is generated on MS-Windows when the input language -has changed. This typically means that the keyboard keys will send to -Emacs characters from a different language. The generated event has -this form: - -@smallexample -(language-change @var{frame} @var{codepage} @var{language-id}) -@end smallexample - -@noindent -Here @var{frame} is the frame which was current when the input -language changed; @var{codepage} is the new codepage number; and -@var{language-id} is the numerical ID of the new input language. The -coding-system (@pxref{Coding Systems}) that corresponds to -@var{codepage} is @code{cp@var{codepage}} or -@code{windows-@var{codepage}}. To convert @var{language-id} to a -string (e.g., to use it for various language-dependent features, such -as @code{set-language-environment}), use the -@code{w32-get-locale-info} function, like this: - -@smallexample -;; Get the abbreviated language name, such as "ENU" for English -(w32-get-locale-info language-id) -;; Get the full English name of the language, -;; such as "English (United States)" -(w32-get-locale-info language-id 4097) -;; Get the full localized name of the language -(w32-get-locale-info language-id t) -@end smallexample -@end table - - If one of these events arrives in the middle of a key sequence---that -is, after a prefix key---then Emacs reorders the events so that this -event comes either before or after the multi-event key sequence, not -within it. - -@node Event Examples -@subsection Event Examples - -If the user presses and releases the left mouse button over the same -location, that generates a sequence of events like this: - -@smallexample -(down-mouse-1 (# 2613 (0 . 38) -864320)) -(mouse-1 (# 2613 (0 . 38) -864180)) -@end smallexample - -While holding the control key down, the user might hold down the -second mouse button, and drag the mouse from one line to the next. -That produces two events, as shown here: - -@smallexample -(C-down-mouse-2 (# 3440 (0 . 27) -731219)) -(C-drag-mouse-2 (# 3440 (0 . 27) -731219) - (# 3510 (0 . 28) -729648)) -@end smallexample - -While holding down the meta and shift keys, the user might press the -second mouse button on the window's mode line, and then drag the mouse -into another window. That produces a pair of events like these: - -@smallexample -(M-S-down-mouse-2 (# mode-line (33 . 31) -457844)) -(M-S-drag-mouse-2 (# mode-line (33 . 31) -457844) - (# 161 (33 . 3) - -453816)) -@end smallexample - -To handle a SIGUSR1 signal, define an interactive function, and -bind it to the @code{signal usr1} event sequence: - -@smallexample -(defun usr1-handler () - (interactive) - (message "Got USR1 signal")) -(global-set-key [signal usr1] 'usr1-handler) -@end smallexample - -@node Classifying Events -@subsection Classifying Events -@cindex event type - - Every event has an @dfn{event type}, which classifies the event for -key binding purposes. For a keyboard event, the event type equals the -event value; thus, the event type for a character is the character, and -the event type for a function key symbol is the symbol itself. For -events that are lists, the event type is the symbol in the @sc{car} of -the list. Thus, the event type is always a symbol or a character. - - Two events of the same type are equivalent where key bindings are -concerned; thus, they always run the same command. That does not -necessarily mean they do the same things, however, as some commands look -at the whole event to decide what to do. For example, some commands use -the location of a mouse event to decide where in the buffer to act. - - Sometimes broader classifications of events are useful. For example, -you might want to ask whether an event involved the @key{META} key, -regardless of which other key or mouse button was used. - - The functions @code{event-modifiers} and @code{event-basic-type} are -provided to get such information conveniently. - -@defun event-modifiers event -This function returns a list of the modifiers that @var{event} has. The -modifiers are symbols; they include @code{shift}, @code{control}, -@code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition, -the modifiers list of a mouse event symbol always contains one of -@code{click}, @code{drag}, and @code{down}. For double or triple -events, it also contains @code{double} or @code{triple}. - -The argument @var{event} may be an entire event object, or just an -event type. If @var{event} is a symbol that has never been used in an -event that has been read as input in the current Emacs session, then -@code{event-modifiers} can return @code{nil}, even when @var{event} -actually has modifiers. - -Here are some examples: - -@example -(event-modifiers ?a) - @result{} nil -(event-modifiers ?A) - @result{} (shift) -(event-modifiers ?\C-a) - @result{} (control) -(event-modifiers ?\C-%) - @result{} (control) -(event-modifiers ?\C-\S-a) - @result{} (control shift) -(event-modifiers 'f5) - @result{} nil -(event-modifiers 's-f5) - @result{} (super) -(event-modifiers 'M-S-f5) - @result{} (meta shift) -(event-modifiers 'mouse-1) - @result{} (click) -(event-modifiers 'down-mouse-1) - @result{} (down) -@end example - -The modifiers list for a click event explicitly contains @code{click}, -but the event symbol name itself does not contain @samp{click}. -@end defun - -@defun event-basic-type event -This function returns the key or mouse button that @var{event} -describes, with all modifiers removed. The @var{event} argument is as -in @code{event-modifiers}. For example: - -@example -(event-basic-type ?a) - @result{} 97 -(event-basic-type ?A) - @result{} 97 -(event-basic-type ?\C-a) - @result{} 97 -(event-basic-type ?\C-\S-a) - @result{} 97 -(event-basic-type 'f5) - @result{} f5 -(event-basic-type 's-f5) - @result{} f5 -(event-basic-type 'M-S-f5) - @result{} f5 -(event-basic-type 'down-mouse-1) - @result{} mouse-1 -@end example -@end defun - -@defun mouse-movement-p object -This function returns non-@code{nil} if @var{object} is a mouse movement -event. -@end defun - -@defun event-convert-list list -This function converts a list of modifier names and a basic event type -to an event type which specifies all of them. The basic event type -must be the last element of the list. For example, - -@example -(event-convert-list '(control ?a)) - @result{} 1 -(event-convert-list '(control meta ?a)) - @result{} -134217727 -(event-convert-list '(control super f1)) - @result{} C-s-f1 -@end example -@end defun - -@node Accessing Mouse -@subsection Accessing Mouse Events -@cindex mouse events, data in -@cindex keyboard events, data in - - This section describes convenient functions for accessing the data in -a mouse button or motion event. Keyboard event data can be accessed -using the same functions, but data elements that aren't applicable to -keyboard events are zero or @code{nil}. - - The following two functions return a mouse position list -(@pxref{Click Events}), specifying the position of a mouse event. - -@defun event-start event -This returns the starting position of @var{event}. - -If @var{event} is a click or button-down event, this returns the -location of the event. If @var{event} is a drag event, this returns the -drag's starting position. -@end defun - -@defun event-end event -This returns the ending position of @var{event}. - -If @var{event} is a drag event, this returns the position where the user -released the mouse button. If @var{event} is a click or button-down -event, the value is actually the starting position, which is the only -position such events have. -@end defun - -@defun posnp object -This function returns non-@code{nil} if @var{object} is a mouse -position list, in either of the formats documented in @ref{Click -Events}); and @code{nil} otherwise. -@end defun - -@cindex mouse position list, accessing - These functions take a mouse position list as argument, and return -various parts of it: - -@defun posn-window position -Return the window that @var{position} is in. -@end defun - -@defun posn-area position -Return the window area recorded in @var{position}. It returns @code{nil} -when the event occurred in the text area of the window; otherwise, it -is a symbol identifying the area in which the event occurred. -@end defun - -@defun posn-point position -Return the buffer position in @var{position}. When the event occurred -in the text area of the window, in a marginal area, or on a fringe, -this is an integer specifying a buffer position. Otherwise, the value -is undefined. -@end defun - -@defun posn-x-y position -Return the pixel-based x and y coordinates in @var{position}, as a -cons cell @code{(@var{x} . @var{y})}. These coordinates are relative -to the window given by @code{posn-window}. - -This example shows how to convert the window-relative coordinates in -the text area of a window into frame-relative coordinates: - -@example -(defun frame-relative-coordinates (position) - "Return frame-relative coordinates from POSITION. -POSITION is assumed to lie in a window text area." - (let* ((x-y (posn-x-y position)) - (window (posn-window position)) - (edges (window-inside-pixel-edges window))) - (cons (+ (car x-y) (car edges)) - (+ (cdr x-y) (cadr edges))))) -@end example -@end defun - -@defun posn-col-row position -This function returns a cons cell @code{(@var{col} . @var{row})}, -containing the estimated column and row corresponding to buffer -position in @var{position}. The return value is given in units of the -frame's default character width and default line height (including -spacing), as computed from the @var{x} and @var{y} values -corresponding to @var{position}. (So, if the actual characters have -non-default sizes, the actual row and column may differ from these -computed values.) - -Note that @var{row} is counted from the top of the text area. If the -window given by @var{position} possesses a header line (@pxref{Header -Lines}), it is @emph{not} included in the @var{row} count. -@end defun - -@defun posn-actual-col-row position -Return the actual row and column in @var{position}, as a cons cell -@code{(@var{col} . @var{row})}. The values are the actual row and -column numbers in the window given by @var{position}. @xref{Click -Events}, for details. The function returns @code{nil} if -@var{position} does not include actual position values. -@end defun - -@defun posn-string position -Return the string object in @var{position}, either @code{nil}, or a -cons cell @code{(@var{string} . @var{string-pos})}. -@end defun - -@defun posn-image position -Return the image object in @var{position}, either @code{nil}, or an -image @code{(image ...)}. -@end defun - -@defun posn-object position -Return the image or string object in @var{position}, either -@code{nil}, an image @code{(image ...)}, or a cons cell -@code{(@var{string} . @var{string-pos})}. -@end defun - -@defun posn-object-x-y position -Return the pixel-based x and y coordinates relative to the upper left -corner of the object in @var{position} as a cons cell @code{(@var{dx} -. @var{dy})}. If the @var{position} is a buffer position, return the -relative position in the character at that position. -@end defun - -@defun posn-object-width-height position -Return the pixel width and height of the object in @var{position} as a -cons cell @code{(@var{width} . @var{height})}. If the @var{position} -is a buffer position, return the size of the character at that position. -@end defun - -@cindex timestamp of a mouse event -@defun posn-timestamp position -Return the timestamp in @var{position}. This is the time at which the -event occurred, in milliseconds. -@end defun - - These functions compute a position list given particular buffer -position or screen position. You can access the data in this position -list with the functions described above. - -@defun posn-at-point &optional pos window -This function returns a position list for position @var{pos} in -@var{window}. @var{pos} defaults to point in @var{window}; -@var{window} defaults to the selected window. - -@code{posn-at-point} returns @code{nil} if @var{pos} is not visible in -@var{window}. -@end defun - -@defun posn-at-x-y x y &optional frame-or-window whole -This function returns position information corresponding to pixel -coordinates @var{x} and @var{y} in a specified frame or window, -@var{frame-or-window}, which defaults to the selected window. -The coordinates @var{x} and @var{y} are relative to the -frame or window used. -If @var{whole} is @code{nil}, the coordinates are relative -to the window text area, otherwise they are relative to -the entire window area including scroll bars, margins and fringes. -@end defun - -@node Accessing Scroll -@subsection Accessing Scroll Bar Events -@cindex scroll bar events, data in - - These functions are useful for decoding scroll bar events. - -@defun scroll-bar-event-ratio event -This function returns the fractional vertical position of a scroll bar -event within the scroll bar. The value is a cons cell -@code{(@var{portion} . @var{whole})} containing two integers whose ratio -is the fractional position. -@end defun - -@defun scroll-bar-scale ratio total -This function multiplies (in effect) @var{ratio} by @var{total}, -rounding the result to an integer. The argument @var{ratio} is not a -number, but rather a pair @code{(@var{num} . @var{denom})}---typically a -value returned by @code{scroll-bar-event-ratio}. - -This function is handy for scaling a position on a scroll bar into a -buffer position. Here's how to do that: - -@example -(+ (point-min) - (scroll-bar-scale - (posn-x-y (event-start event)) - (- (point-max) (point-min)))) -@end example - -Recall that scroll bar events have two integers forming a ratio, in place -of a pair of x and y coordinates. -@end defun - -@node Strings of Events -@subsection Putting Keyboard Events in Strings -@cindex keyboard events in strings -@cindex strings with keyboard events - - In most of the places where strings are used, we conceptualize the -string as containing text characters---the same kind of characters found -in buffers or files. Occasionally Lisp programs use strings that -conceptually contain keyboard characters; for example, they may be key -sequences or keyboard macro definitions. However, storing keyboard -characters in a string is a complex matter, for reasons of historical -compatibility, and it is not always possible. - - We recommend that new programs avoid dealing with these complexities -by not storing keyboard events in strings. Here is how to do that: - -@itemize @bullet -@item -Use vectors instead of strings for key sequences, when you plan to use -them for anything other than as arguments to @code{lookup-key} and -@code{define-key}. For example, you can use -@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and -@code{this-command-keys-vector} instead of @code{this-command-keys}. - -@item -Use vectors to write key sequence constants containing meta characters, -even when passing them directly to @code{define-key}. - -@item -When you have to look at the contents of a key sequence that might be a -string, use @code{listify-key-sequence} (@pxref{Event Input Misc}) -first, to convert it to a list. -@end itemize - - The complexities stem from the modifier bits that keyboard input -characters can include. Aside from the Meta modifier, none of these -modifier bits can be included in a string, and the Meta modifier is -allowed only in special cases. - - The earliest GNU Emacs versions represented meta characters as codes -in the range of 128 to 255. At that time, the basic character codes -ranged from 0 to 127, so all keyboard character codes did fit in a -string. Many Lisp programs used @samp{\M-} in string constants to stand -for meta characters, especially in arguments to @code{define-key} and -similar functions, and key sequences and sequences of events were always -represented as strings. - - When we added support for larger basic character codes beyond 127, and -additional modifier bits, we had to change the representation of meta -characters. Now the flag that represents the Meta modifier in a -character is -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -and such numbers cannot be included in a string. - - To support programs with @samp{\M-} in string constants, there are -special rules for including certain meta characters in a string. -Here are the rules for interpreting a string as a sequence of input -characters: - -@itemize @bullet -@item -If the keyboard character value is in the range of 0 to 127, it can go -in the string unchanged. - -@item -The meta variants of those characters, with codes in the range of -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -to -@tex -@math{2^{27} + 127}, -@end tex -@ifnottex -2**27+127, -@end ifnottex -can also go in the string, but you must change their -numeric values. You must set the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit instead of the -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit, resulting in a value between 128 and 255. Only a unibyte string -can include these codes. - -@item -Non-@acronym{ASCII} characters above 256 can be included in a multibyte string. - -@item -Other keyboard character events cannot fit in a string. This includes -keyboard events in the range of 128 to 255. -@end itemize - - Functions such as @code{read-key-sequence} that construct strings of -keyboard input characters follow these rules: they construct vectors -instead of strings, when the events won't fit in a string. - - When you use the read syntax @samp{\M-} in a string, it produces a -code in the range of 128 to 255---the same code that you get if you -modify the corresponding keyboard event to put it in the string. Thus, -meta events in strings work consistently regardless of how they get into -the strings. - - However, most programs would do well to avoid these issues by -following the recommendations at the beginning of this section. - -@node Reading Input -@section Reading Input -@cindex read input -@cindex keyboard input - - The editor command loop reads key sequences using the function -@code{read-key-sequence}, which uses @code{read-event}. These and other -functions for event input are also available for use in Lisp programs. -See also @code{momentary-string-display} in @ref{Temporary Displays}, -and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for -functions and variables for controlling terminal input modes and -debugging terminal input. - - For higher-level input facilities, see @ref{Minibuffers}. - -@menu -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. -@end menu - -@node Key Sequence Input -@subsection Key Sequence Input -@cindex key sequence input - - The command loop reads input a key sequence at a time, by calling -@code{read-key-sequence}. Lisp programs can also call this function; -for example, @code{describe-key} uses it to read the key to describe. - -@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop -This function reads a key sequence and returns it as a string or -vector. It keeps reading events until it has accumulated a complete key -sequence; that is, enough to specify a non-prefix command using the -currently active keymaps. (Remember that a key sequence that starts -with a mouse event is read using the keymaps of the buffer in the -window that the mouse was in, not the current buffer.) - -If the events are all characters and all can fit in a string, then -@code{read-key-sequence} returns a string (@pxref{Strings of Events}). -Otherwise, it returns a vector, since a vector can hold all kinds of -events---characters, symbols, and lists. The elements of the string or -vector are the events in the key sequence. - -Reading a key sequence includes translating the events in various -ways. @xref{Translation Keymaps}. - -The argument @var{prompt} is either a string to be displayed in the -echo area as a prompt, or @code{nil}, meaning not to display a prompt. -The argument @var{continue-echo}, if non-@code{nil}, means to echo -this key as a continuation of the previous key. - -Normally any upper case event is converted to lower case if the -original event is undefined and the lower case equivalent is defined. -The argument @var{dont-downcase-last}, if non-@code{nil}, means do not -convert the last event to lower case. This is appropriate for reading -a key sequence to be defined. - -The argument @var{switch-frame-ok}, if non-@code{nil}, means that this -function should process a @code{switch-frame} event if the user -switches frames before typing anything. If the user switches frames -in the middle of a key sequence, or at the start of the sequence but -@var{switch-frame-ok} is @code{nil}, then the event will be put off -until after the current key sequence. - -The argument @var{command-loop}, if non-@code{nil}, means that this -key sequence is being read by something that will read commands one -after another. It should be @code{nil} if the caller will read just -one key sequence. - -In the following example, Emacs displays the prompt @samp{?} in the -echo area, and then the user types @kbd{C-x C-f}. - -@example -(read-key-sequence "?") - -@group ----------- Echo Area ---------- -?@kbd{C-x C-f} ----------- Echo Area ---------- - - @result{} "^X^F" -@end group -@end example - -The function @code{read-key-sequence} suppresses quitting: @kbd{C-g} -typed while reading with this function works like any other character, -and does not set @code{quit-flag}. @xref{Quitting}. -@end defun - -@defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop -This is like @code{read-key-sequence} except that it always -returns the key sequence as a vector, never as a string. -@xref{Strings of Events}. -@end defun - -@cindex upper case key sequence -@cindex downcasing in @code{lookup-key} -@cindex shift-translation -If an input character is upper-case (or has the shift modifier) and -has no key binding, but its lower-case equivalent has one, then -@code{read-key-sequence} converts the character to lower case. Note -that @code{lookup-key} does not perform case conversion in this way. - -@vindex this-command-keys-shift-translated -When reading input results in such a @dfn{shift-translation}, Emacs -sets the variable @code{this-command-keys-shift-translated} to a -non-@code{nil} value. Lisp programs can examine this variable if they -need to modify their behavior when invoked by shift-translated keys. -For example, the function @code{handle-shift-selection} examines the -value of this variable to determine how to activate or deactivate the -region (@pxref{The Mark, handle-shift-selection}). - -The function @code{read-key-sequence} also transforms some mouse events. -It converts unbound drag events into click events, and discards unbound -button-down events entirely. It also reshuffles focus events and -miscellaneous window events so that they never appear in a key sequence -with any other events. - -@cindex @code{header-line} prefix key -@cindex @code{mode-line} prefix key -@cindex @code{vertical-line} prefix key -@cindex @code{horizontal-scroll-bar} prefix key -@cindex @code{vertical-scroll-bar} prefix key -@cindex @code{menu-bar} prefix key -@cindex mouse events, in special parts of frame -When mouse events occur in special parts of a window, such as a mode -line or a scroll bar, the event type shows nothing special---it is the -same symbol that would normally represent that combination of mouse -button and modifier keys. The information about the window part is kept -elsewhere in the event---in the coordinates. But -@code{read-key-sequence} translates this information into imaginary -``prefix keys'', all of which are symbols: @code{header-line}, -@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, -@code{vertical-line}, and @code{vertical-scroll-bar}. You can define -meanings for mouse clicks in special window parts by defining key -sequences using these imaginary prefix keys. - -For example, if you call @code{read-key-sequence} and then click the -mouse on the window's mode line, you get two events, like this: - -@example -(read-key-sequence "Click on the mode line: ") - @result{} [mode-line - (mouse-1 - (# mode-line - (40 . 63) 5959987))] -@end example - -@defvar num-input-keys -This variable's value is the number of key sequences processed so far in -this Emacs session. This includes key sequences read from the terminal -and key sequences read from keyboard macros being executed. -@end defvar - -@node Reading One Event -@subsection Reading One Event -@cindex reading a single event -@cindex event, reading only one - - The lowest level functions for command input are @code{read-event}, -@code{read-char}, and @code{read-char-exclusive}. - -@defun read-event &optional prompt inherit-input-method seconds -This function reads and returns the next event of command input, -waiting if necessary until an event is available. - -The returned event may come directly from the user, or from a keyboard -macro. It is not decoded by the keyboard's input coding system -(@pxref{Terminal I/O Encoding}). - -If the optional argument @var{prompt} is non-@code{nil}, it should be a -string to display in the echo area as a prompt. Otherwise, -@code{read-event} does not display any message to indicate it is waiting -for input; instead, it prompts by echoing: it displays descriptions of -the events that led to or were read by the current command. @xref{The -Echo Area}. - -If @var{inherit-input-method} is non-@code{nil}, then the current input -method (if any) is employed to make it possible to enter a -non-@acronym{ASCII} character. Otherwise, input method handling is disabled -for reading this event. - -If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} -moves the cursor temporarily to the echo area, to the end of any message -displayed there. Otherwise @code{read-event} does not move the cursor. - -If @var{seconds} is non-@code{nil}, it should be a number specifying -the maximum time to wait for input, in seconds. If no input arrives -within that time, @code{read-event} stops waiting and returns -@code{nil}. A floating point @var{seconds} means to wait -for a fractional number of seconds. Some systems support only a whole -number of seconds; on these systems, @var{seconds} is rounded down. -If @var{seconds} is @code{nil}, @code{read-event} waits as long as -necessary for input to arrive. - -If @var{seconds} is @code{nil}, Emacs is considered idle while waiting -for user input to arrive. Idle timers---those created with -@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this -period. However, if @var{seconds} is non-@code{nil}, the state of -idleness remains unchanged. If Emacs is non-idle when -@code{read-event} is called, it remains non-idle throughout the -operation of @code{read-event}; if Emacs is idle (which can happen if -the call happens inside an idle timer), it remains idle. - -If @code{read-event} gets an event that is defined as a help character, -then in some cases @code{read-event} processes the event directly without -returning. @xref{Help Functions}. Certain other events, called -@dfn{special events}, are also processed directly within -@code{read-event} (@pxref{Special Events}). - -Here is what happens if you call @code{read-event} and then press the -right-arrow function key: - -@example -@group -(read-event) - @result{} right -@end group -@end example -@end defun - -@defun read-char &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the -user generates an event which is not a character (i.e., a mouse click or -function key event), @code{read-char} signals an error. The arguments -work as in @code{read-event}. - -In the first example, the user types the character @kbd{1} (@acronym{ASCII} -code 49). The second example shows a keyboard macro definition that -calls @code{read-char} from the minibuffer using @code{eval-expression}. -@code{read-char} reads the keyboard macro's very next character, which -is @kbd{1}. Then @code{eval-expression} displays its return value in -the echo area. - -@example -@group -(read-char) - @result{} 49 -@end group - -@group -;; @r{We assume here you use @kbd{M-:} to evaluate this.} -(symbol-function 'foo) - @result{} "^[:(read-char)^M1" -@end group -@group -(execute-kbd-macro 'foo) - @print{} 49 - @result{} nil -@end group -@end example -@end defun - -@defun read-char-exclusive &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the -user generates an event which is not a character, -@code{read-char-exclusive} ignores it and reads another event, until it -gets a character. The arguments work as in @code{read-event}. -@end defun - - None of the above functions suppress quitting. - -@defvar num-nonmacro-input-events -This variable holds the total number of input events received so far -from the terminal---not counting those generated by keyboard macros. -@end defvar - - We emphasize that, unlike @code{read-key-sequence}, the functions -@code{read-event}, @code{read-char}, and @code{read-char-exclusive} do -not perform the translations described in @ref{Translation Keymaps}. -If you wish to read a single key taking these translations into -account, use the function @code{read-key}: - -@defun read-key &optional prompt -This function reads a single key. It is ``intermediate'' between -@code{read-key-sequence} and @code{read-event}. Unlike the former, it -reads a single key, not a key sequence. Unlike the latter, it does -not return a raw event, but decodes and translates the user input -according to @code{input-decode-map}, @code{local-function-key-map}, -and @code{key-translation-map} (@pxref{Translation Keymaps}). - -The argument @var{prompt} is either a string to be displayed in the -echo area as a prompt, or @code{nil}, meaning not to display a prompt. -@end defun - -@defun read-char-choice prompt chars &optional inhibit-quit -This function uses @code{read-key} to read and return a single -character. It ignores any input that is not a member of @var{chars}, -a list of accepted characters. Optionally, it will also ignore -keyboard-quit events while it is waiting for valid input. If you bind -@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value -while calling @code{read-char-choice}, then pressing @code{help-char} -causes it to evaluate @code{help-form} and display the result. It -then continues to wait for a valid input character, or keyboard-quit. -@end defun - -@node Event Mod -@subsection Modifying and Translating Input Events - - Emacs modifies every event it reads according to -@code{extra-keyboard-modifiers}, then translates it through -@code{keyboard-translate-table} (if applicable), before returning it -from @code{read-event}. - -@defvar extra-keyboard-modifiers -This variable lets Lisp programs ``press'' the modifier keys on the -keyboard. The value is a character. Only the modifiers of the -character matter. Each time the user types a keyboard key, it is -altered as if those modifier keys were held down. For instance, if -you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all -keyboard input characters typed during the scope of the binding will -have the control and meta modifiers applied to them. The character -@code{?\C-@@}, equivalent to the integer 0, does not count as a control -character for this purpose, but as a character with no modifiers. -Thus, setting @code{extra-keyboard-modifiers} to zero cancels any -modification. - -When using a window system, the program can ``press'' any of the -modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} -keys can be virtually pressed. - -Note that this variable applies only to events that really come from -the keyboard, and has no effect on mouse events or any other events. -@end defvar - -@defvar keyboard-translate-table -This terminal-local variable is the translate table for keyboard -characters. It lets you reshuffle the keys on the keyboard without -changing any command bindings. Its value is normally a char-table, or -else @code{nil}. (It can also be a string or vector, but this is -considered obsolete.) - -If @code{keyboard-translate-table} is a char-table -(@pxref{Char-Tables}), then each character read from the keyboard is -looked up in this char-table. If the value found there is -non-@code{nil}, then it is used instead of the actual input character. - -Note that this translation is the first thing that happens to a -character after it is read from the terminal. Record-keeping features -such as @code{recent-keys} and dribble files record the characters after -translation. - -Note also that this translation is done before the characters are -supplied to input methods (@pxref{Input Methods}). Use -@code{translation-table-for-input} (@pxref{Translation of Characters}), -if you want to translate characters after input methods operate. -@end defvar - -@defun keyboard-translate from to -This function modifies @code{keyboard-translate-table} to translate -character code @var{from} into character code @var{to}. It creates -the keyboard translate table if necessary. -@end defun - - Here's an example of using the @code{keyboard-translate-table} to -make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste -operations: - -@example -(keyboard-translate ?\C-x 'control-x) -(keyboard-translate ?\C-c 'control-c) -(keyboard-translate ?\C-v 'control-v) -(global-set-key [control-x] 'kill-region) -(global-set-key [control-c] 'kill-ring-save) -(global-set-key [control-v] 'yank) -@end example - -@noindent -On a graphical terminal that supports extended @acronym{ASCII} input, -you can still get the standard Emacs meanings of one of those -characters by typing it with the shift key. That makes it a different -character as far as keyboard translation is concerned, but it has the -same usual meaning. - - @xref{Translation Keymaps}, for mechanisms that translate event sequences -at the level of @code{read-key-sequence}. - -@node Invoking the Input Method -@subsection Invoking the Input Method - - The event-reading functions invoke the current input method, if any -(@pxref{Input Methods}). If the value of @code{input-method-function} -is non-@code{nil}, it should be a function; when @code{read-event} reads -a printing character (including @key{SPC}) with no modifier bits, it -calls that function, passing the character as an argument. - -@defvar input-method-function -If this is non-@code{nil}, its value specifies the current input method -function. - -@strong{Warning:} don't bind this variable with @code{let}. It is often -buffer-local, and if you bind it around reading input (which is exactly -when you @emph{would} bind it), switching buffers asynchronously while -Emacs is waiting will cause the value to be restored in the wrong -buffer. -@end defvar - - The input method function should return a list of events which should -be used as input. (If the list is @code{nil}, that means there is no -input, so @code{read-event} waits for another event.) These events are -processed before the events in @code{unread-command-events} -(@pxref{Event Input Misc}). Events -returned by the input method function are not passed to the input method -function again, even if they are printing characters with no modifier -bits. - - If the input method function calls @code{read-event} or -@code{read-key-sequence}, it should bind @code{input-method-function} to -@code{nil} first, to prevent recursion. - - The input method function is not called when reading the second and -subsequent events of a key sequence. Thus, these characters are not -subject to input method processing. The input method function should -test the values of @code{overriding-local-map} and -@code{overriding-terminal-local-map}; if either of these variables is -non-@code{nil}, the input method should put its argument into a list and -return that list with no further processing. - -@node Quoted Character Input -@subsection Quoted Character Input -@cindex quoted character input - - You can use the function @code{read-quoted-char} to ask the user to -specify a character, and allow the user to specify a control or meta -character conveniently, either literally or as an octal character code. -The command @code{quoted-insert} uses this function. - -@defun read-quoted-char &optional prompt -@cindex octal character input -@cindex control characters, reading -@cindex nonprinting characters, reading -This function is like @code{read-char}, except that if the first -character read is an octal digit (0--7), it reads any number of octal -digits (but stopping if a non-octal digit is found), and returns the -character represented by that numeric character code. If the -character that terminates the sequence of octal digits is @key{RET}, -it is discarded. Any other terminating character is used as input -after this function returns. - -Quitting is suppressed when the first character is read, so that the -user can enter a @kbd{C-g}. @xref{Quitting}. - -If @var{prompt} is supplied, it specifies a string for prompting the -user. The prompt string is always displayed in the echo area, followed -by a single @samp{-}. - -In the following example, the user types in the octal number 177 (which -is 127 in decimal). - -@example -(read-quoted-char "What character") - -@group ----------- Echo Area ---------- -What character @kbd{1 7 7}- ----------- Echo Area ---------- - - @result{} 127 -@end group -@end example -@end defun - -@need 2000 -@node Event Input Misc -@subsection Miscellaneous Event Input Features - -This section describes how to ``peek ahead'' at events without using -them up, how to check for pending input, and how to discard pending -input. See also the function @code{read-passwd} (@pxref{Reading a -Password}). - -@defvar unread-command-events -@cindex next input -@cindex peeking at input -This variable holds a list of events waiting to be read as command -input. The events are used in the order they appear in the list, and -removed one by one as they are used. - -The variable is needed because in some cases a function reads an event -and then decides not to use it. Storing the event in this variable -causes it to be processed normally, by the command loop or by the -functions to read command input. - -@cindex prefix argument unreading -For example, the function that implements numeric prefix arguments reads -any number of digits. When it finds a non-digit event, it must unread -the event so that it can be read normally by the command loop. -Likewise, incremental search uses this feature to unread events with no -special meaning in a search, because these events should exit the search -and then execute normally. - -The reliable and easy way to extract events from a key sequence so as -to put them in @code{unread-command-events} is to use -@code{listify-key-sequence} (see below). - -Normally you add events to the front of this list, so that the events -most recently unread will be reread first. - -Events read from this list are not normally added to the current -command's key sequence (as returned by, e.g., @code{this-command-keys}), -as the events will already have been added once as they were read for -the first time. An element of the form @code{(@code{t} . @var{event})} -forces @var{event} to be added to the current command's key sequence. -@end defvar - -@defun listify-key-sequence key -This function converts the string or vector @var{key} to a list of -individual events, which you can put in @code{unread-command-events}. -@end defun - -@defun input-pending-p &optional check-timers -@cindex waiting for command key input -This function determines whether any command input is currently -available to be read. It returns immediately, with value @code{t} if -there is available input, @code{nil} otherwise. On rare occasions it -may return @code{t} when no input is available. - -If the optional argument @var{check-timers} is non-@code{nil}, then if -no input is available, Emacs runs any timers which are ready. -@xref{Timers}. -@end defun - -@defvar last-input-event -This variable records the last terminal input event read, whether -as part of a command or explicitly by a Lisp program. - -In the example below, the Lisp program reads the character @kbd{1}, -@acronym{ASCII} code 49. It becomes the value of @code{last-input-event}, -while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate -this expression) remains the value of @code{last-command-event}. - -@example -@group -(progn (print (read-char)) - (print last-command-event) - last-input-event) - @print{} 49 - @print{} 5 - @result{} 49 -@end group -@end example -@end defvar - -@defmac while-no-input body@dots{} -This construct runs the @var{body} forms and returns the value of the -last one---but only if no input arrives. If any input arrives during -the execution of the @var{body} forms, it aborts them (working much -like a quit). The @code{while-no-input} form returns @code{nil} if -aborted by a real quit, and returns @code{t} if aborted by arrival of -other input. - -If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil}, -arrival of input during those parts won't cause an abort until -the end of that part. - -If you want to be able to distinguish all possible values computed -by @var{body} from both kinds of abort conditions, write the code -like this: - -@example -(while-no-input - (list - (progn . @var{body}))) -@end example -@end defmac - -@defun discard-input -@cindex flushing input -@cindex discarding input -@cindex keyboard macro, terminating -This function discards the contents of the terminal input buffer and -cancels any keyboard macro that might be in the process of definition. -It returns @code{nil}. - -In the following example, the user may type a number of characters right -after starting the evaluation of the form. After the @code{sleep-for} -finishes sleeping, @code{discard-input} discards any characters typed -during the sleep. - -@example -(progn (sleep-for 2) - (discard-input)) - @result{} nil -@end example -@end defun - -@node Special Events -@section Special Events - -@cindex special events -Certain @dfn{special events} are handled at a very low level---as soon -as they are read. The @code{read-event} function processes these -events itself, and never returns them. Instead, it keeps waiting for -the first event that is not special and returns that one. - - Special events do not echo, they are never grouped into key -sequences, and they never appear in the value of -@code{last-command-event} or @code{(this-command-keys)}. They do not -discard a numeric argument, they cannot be unread with -@code{unread-command-events}, they may not appear in a keyboard macro, -and they are not recorded in a keyboard macro while you are defining -one. - - Special events do, however, appear in @code{last-input-event} -immediately after they are read, and this is the way for the event's -definition to find the actual event. - - The events types @code{iconify-frame}, @code{make-frame-visible}, -@code{delete-frame}, @code{drag-n-drop}, @code{language-change}, and -user signals like @code{sigusr1} are normally handled in this way. -The keymap which defines how to handle special events---and which -events are special---is in the variable @code{special-event-map} -(@pxref{Active Keymaps}). - -@node Waiting -@section Waiting for Elapsed Time or Input -@cindex waiting - - The wait functions are designed to wait for a certain amount of time -to pass or until there is input. For example, you may wish to pause in -the middle of a computation to allow the user time to view the display. -@code{sit-for} pauses and updates the screen, and returns immediately if -input comes in, while @code{sleep-for} pauses without updating the -screen. - -@defun sit-for seconds &optional nodisp -This function performs redisplay (provided there is no pending input -from the user), then waits @var{seconds} seconds, or until input is -available. The usual purpose of @code{sit-for} is to give the user -time to read text that you display. The value is @code{t} if -@code{sit-for} waited the full time with no input arriving -(@pxref{Event Input Misc}). Otherwise, the value is @code{nil}. - -The argument @var{seconds} need not be an integer. If it is floating -point, @code{sit-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)}, -i.e., it requests a redisplay, without any delay, if there is no pending input. -@xref{Forcing Redisplay}. - -If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not -redisplay, but it still returns as soon as input is available (or when -the timeout elapses). - -In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be -interrupted, even by input from the standard input descriptor. It is -thus equivalent to @code{sleep-for}, which is described below. - -It is also possible to call @code{sit-for} with three arguments, -as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})}, -but that is considered obsolete. -@end defun - -@defun sleep-for seconds &optional millisec -This function simply pauses for @var{seconds} seconds without updating -the display. It pays no attention to available input. It returns -@code{nil}. - -The argument @var{seconds} need not be an integer. If it is floating -point, @code{sleep-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The optional argument @var{millisec} specifies an additional waiting -period measured in milliseconds. This adds to the period specified by -@var{seconds}. If the system doesn't support waiting fractions of a -second, you get an error if you specify nonzero @var{millisec}. - -Use @code{sleep-for} when you wish to guarantee a delay. -@end defun - - @xref{Time of Day}, for functions to get the current time. - -@node Quitting -@section Quitting -@cindex @kbd{C-g} -@cindex quitting -@cindex interrupt Lisp functions - - Typing @kbd{C-g} while a Lisp function is running causes Emacs to -@dfn{quit} whatever it is doing. This means that control returns to the -innermost active command loop. - - Typing @kbd{C-g} while the command loop is waiting for keyboard input -does not cause a quit; it acts as an ordinary input character. In the -simplest case, you cannot tell the difference, because @kbd{C-g} -normally runs the command @code{keyboard-quit}, whose effect is to quit. -However, when @kbd{C-g} follows a prefix key, they combine to form an -undefined key. The effect is to cancel the prefix key as well as any -prefix argument. - - In the minibuffer, @kbd{C-g} has a different definition: it aborts out -of the minibuffer. This means, in effect, that it exits the minibuffer -and then quits. (Simply quitting would return to the command loop -@emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit -directly when the command reader is reading input is so that its meaning -can be redefined in the minibuffer in this way. @kbd{C-g} following a -prefix key is not redefined in the minibuffer, and it has its normal -effect of canceling the prefix key and prefix argument. This too -would not be possible if @kbd{C-g} always quit directly. - - When @kbd{C-g} does directly quit, it does so by setting the variable -@code{quit-flag} to @code{t}. Emacs checks this variable at appropriate -times and quits if it is not @code{nil}. Setting @code{quit-flag} -non-@code{nil} in any way thus causes a quit. - - At the level of C code, quitting cannot happen just anywhere; only at the -special places that check @code{quit-flag}. The reason for this is -that quitting at other places might leave an inconsistency in Emacs's -internal state. Because quitting is delayed until a safe place, quitting -cannot make Emacs crash. - - Certain functions such as @code{read-key-sequence} or -@code{read-quoted-char} prevent quitting entirely even though they wait -for input. Instead of quitting, @kbd{C-g} serves as the requested -input. In the case of @code{read-key-sequence}, this serves to bring -about the special behavior of @kbd{C-g} in the command loop. In the -case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used -to quote a @kbd{C-g}. - -@cindex preventing quitting - You can prevent quitting for a portion of a Lisp function by binding -the variable @code{inhibit-quit} to a non-@code{nil} value. Then, -although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the -usual result of this---a quit---is prevented. Eventually, -@code{inhibit-quit} will become @code{nil} again, such as when its -binding is unwound at the end of a @code{let} form. At that time, if -@code{quit-flag} is still non-@code{nil}, the requested quit happens -immediately. This behavior is ideal when you wish to make sure that -quitting does not happen within a ``critical section'' of the program. - -@cindex @code{read-quoted-char} quitting - In some functions (such as @code{read-quoted-char}), @kbd{C-g} is -handled in a special way that does not involve quitting. This is done -by reading the input with @code{inhibit-quit} bound to @code{t}, and -setting @code{quit-flag} to @code{nil} before @code{inhibit-quit} -becomes @code{nil} again. This excerpt from the definition of -@code{read-quoted-char} shows how this is done; it also shows that -normal quitting is permitted after the first character of input. - -@example -(defun read-quoted-char (&optional prompt) - "@dots{}@var{documentation}@dots{}" - (let ((message-log-max nil) done (first t) (code 0) char) - (while (not done) - (let ((inhibit-quit first) - @dots{}) - (and prompt (message "%s-" prompt)) - (setq char (read-event)) - (if inhibit-quit (setq quit-flag nil))) - @r{@dots{}set the variable @code{code}@dots{}}) - code)) -@end example - -@defvar quit-flag -If this variable is non-@code{nil}, then Emacs quits immediately, unless -@code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets -@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}. -@end defvar - -@defvar inhibit-quit -This variable determines whether Emacs should quit when @code{quit-flag} -is set to a value other than @code{nil}. If @code{inhibit-quit} is -non-@code{nil}, then @code{quit-flag} has no special effect. -@end defvar - -@defmac with-local-quit body@dots{} -This macro executes @var{body} forms in sequence, but allows quitting, at -least locally, within @var{body} even if @code{inhibit-quit} was -non-@code{nil} outside this construct. It returns the value of the -last form in @var{body}, unless exited by quitting, in which case -it returns @code{nil}. - -If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit}, -it only executes the @var{body}, and setting @code{quit-flag} causes -a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so -that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag} -triggers a special kind of local quit. This ends the execution of -@var{body} and exits the @code{with-local-quit} body with -@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit -will happen as soon as that is allowed. If @code{quit-flag} is -already non-@code{nil} at the beginning of @var{body}, the local quit -happens immediately and the body doesn't execute at all. - -This macro is mainly useful in functions that can be called from -timers, process filters, process sentinels, @code{pre-command-hook}, -@code{post-command-hook}, and other places where @code{inhibit-quit} is -normally bound to @code{t}. -@end defmac - -@deffn Command keyboard-quit -This function signals the @code{quit} condition with @code{(signal 'quit -nil)}. This is the same thing that quitting does. (See @code{signal} -in @ref{Errors}.) -@end deffn - - You can specify a character other than @kbd{C-g} to use for quitting. -See the function @code{set-input-mode} in @ref{Input Modes}. - -@node Prefix Command Arguments -@section Prefix Command Arguments -@cindex prefix argument -@cindex raw prefix argument -@cindex numeric prefix argument - - Most Emacs commands can use a @dfn{prefix argument}, a number -specified before the command itself. (Don't confuse prefix arguments -with prefix keys.) The prefix argument is at all times represented by a -value, which may be @code{nil}, meaning there is currently no prefix -argument. Each command may use the prefix argument or ignore it. - - There are two representations of the prefix argument: @dfn{raw} and -@dfn{numeric}. The editor command loop uses the raw representation -internally, and so do the Lisp variables that store the information, but -commands can request either representation. - - Here are the possible values of a raw prefix argument: - -@itemize @bullet -@item -@code{nil}, meaning there is no prefix argument. Its numeric value is -1, but numerous commands make a distinction between @code{nil} and the -integer 1. - -@item -An integer, which stands for itself. - -@item -A list of one element, which is an integer. This form of prefix -argument results from one or a succession of @kbd{C-u}s with no -digits. The numeric value is the integer in the list, but some -commands make a distinction between such a list and an integer alone. - -@item -The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was -typed, without following digits. The equivalent numeric value is -@minus{}1, but some commands make a distinction between the integer -@minus{}1 and the symbol @code{-}. -@end itemize - -We illustrate these possibilities by calling the following function with -various prefixes: - -@example -@group -(defun display-prefix (arg) - "Display the value of the raw prefix arg." - (interactive "P") - (message "%s" arg)) -@end group -@end example - -@noindent -Here are the results of calling @code{display-prefix} with various -raw prefix arguments: - -@example - M-x display-prefix @print{} nil - -C-u M-x display-prefix @print{} (4) - -C-u C-u M-x display-prefix @print{} (16) - -C-u 3 M-x display-prefix @print{} 3 - -M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)} - -C-u - M-x display-prefix @print{} - - -M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)} - -C-u - 7 M-x display-prefix @print{} -7 - -M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)} -@end example - - Emacs uses two variables to store the prefix argument: -@code{prefix-arg} and @code{current-prefix-arg}. Commands such as -@code{universal-argument} that set up prefix arguments for other -commands store them in @code{prefix-arg}. In contrast, -@code{current-prefix-arg} conveys the prefix argument to the current -command, so setting it has no effect on the prefix arguments for future -commands. - - Normally, commands specify which representation to use for the prefix -argument, either numeric or raw, in the @code{interactive} specification. -(@xref{Using Interactive}.) Alternatively, functions may look at the -value of the prefix argument directly in the variable -@code{current-prefix-arg}, but this is less clean. - -@defun prefix-numeric-value arg -This function returns the numeric meaning of a valid raw prefix argument -value, @var{arg}. The argument may be a symbol, a number, or a list. -If it is @code{nil}, the value 1 is returned; if it is @code{-}, the -value @minus{}1 is returned; if it is a number, that number is returned; -if it is a list, the @sc{car} of that list (which should be a number) is -returned. -@end defun - -@defvar current-prefix-arg -This variable holds the raw prefix argument for the @emph{current} -command. Commands may examine it directly, but the usual method for -accessing it is with @code{(interactive "P")}. -@end defvar - -@defvar prefix-arg -The value of this variable is the raw prefix argument for the -@emph{next} editing command. Commands such as @code{universal-argument} -that specify prefix arguments for the following command work by setting -this variable. -@end defvar - -@defvar last-prefix-arg -The raw prefix argument value used by the previous command. -@end defvar - - The following commands exist to set up prefix arguments for the -following command. Do not call them for any other reason. - -@deffn Command universal-argument -This command reads input and specifies a prefix argument for the -following command. Don't call this command yourself unless you know -what you are doing. -@end deffn - -@deffn Command digit-argument arg -This command adds to the prefix argument for the following command. The -argument @var{arg} is the raw prefix argument as it was before this -command; it is used to compute the updated prefix argument. Don't call -this command yourself unless you know what you are doing. -@end deffn - -@deffn Command negative-argument arg -This command adds to the numeric argument for the next command. The -argument @var{arg} is the raw prefix argument as it was before this -command; its value is negated to form the new prefix argument. Don't -call this command yourself unless you know what you are doing. -@end deffn - -@node Recursive Editing -@section Recursive Editing -@cindex recursive command loop -@cindex recursive editing level -@cindex command loop, recursive - - The Emacs command loop is entered automatically when Emacs starts up. -This top-level invocation of the command loop never exits; it keeps -running as long as Emacs does. Lisp programs can also invoke the -command loop. Since this makes more than one activation of the command -loop, we call it @dfn{recursive editing}. A recursive editing level has -the effect of suspending whatever command invoked it and permitting the -user to do arbitrary editing before resuming that command. - - The commands available during recursive editing are the same ones -available in the top-level editing loop and defined in the keymaps. -Only a few special commands exit the recursive editing level; the others -return to the recursive editing level when they finish. (The special -commands for exiting are always available, but they do nothing when -recursive editing is not in progress.) - - All command loops, including recursive ones, set up all-purpose error -handlers so that an error in a command run from the command loop will -not exit the loop. - -@cindex minibuffer input - Minibuffer input is a special kind of recursive editing. It has a few -special wrinkles, such as enabling display of the minibuffer and the -minibuffer window, but fewer than you might suppose. Certain keys -behave differently in the minibuffer, but that is only because of the -minibuffer's local map; if you switch windows, you get the usual Emacs -commands. - -@cindex @code{throw} example -@kindex exit -@cindex exit recursive editing -@cindex aborting - To invoke a recursive editing level, call the function -@code{recursive-edit}. This function contains the command loop; it also -contains a call to @code{catch} with tag @code{exit}, which makes it -possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a value other than @code{t}, -then @code{recursive-edit} returns normally to the function that called -it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. -Throwing a @code{t} value causes @code{recursive-edit} to quit, so that -control returns to the command loop one level up. This is called -@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). - - Most applications should not use recursive editing, except as part of -using the minibuffer. Usually it is more convenient for the user if you -change the major mode of the current buffer temporarily to a special -major mode, which should have a command to go back to the previous mode. -(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to -give the user different text to edit ``recursively'', create and select -a new buffer in a special mode. In this mode, define a command to -complete the processing and go back to the previous buffer. (The -@kbd{m} command in Rmail does this.) - - Recursive edits are useful in debugging. You can insert a call to -@code{debug} into a function definition as a sort of breakpoint, so that -you can look around when the function gets there. @code{debug} invokes -a recursive edit but also provides the other features of the debugger. - - Recursive editing levels are also used when you type @kbd{C-r} in -@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}). - -@deffn Command recursive-edit -@cindex suspend evaluation -This function invokes the editor command loop. It is called -automatically by the initialization of Emacs, to let the user begin -editing. When called from a Lisp program, it enters a recursive editing -level. - -If the current buffer is not the same as the selected window's buffer, -@code{recursive-edit} saves and restores the current buffer. Otherwise, -if you switch buffers, the buffer you switched to is current after -@code{recursive-edit} returns. - -In the following example, the function @code{simple-rec} first -advances point one word, then enters a recursive edit, printing out a -message in the echo area. The user can then do any editing desired, and -then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}. - -@example -(defun simple-rec () - (forward-word 1) - (message "Recursive edit in progress") - (recursive-edit) - (forward-word 1)) - @result{} simple-rec -(simple-rec) - @result{} nil -@end example -@end deffn - -@deffn Command exit-recursive-edit -This function exits from the innermost recursive edit (including -minibuffer input). Its definition is effectively @code{(throw 'exit -nil)}. -@end deffn - -@deffn Command abort-recursive-edit -This function aborts the command that requested the innermost recursive -edit (including minibuffer input), by signaling @code{quit} -after exiting the recursive edit. Its definition is effectively -@code{(throw 'exit t)}. @xref{Quitting}. -@end deffn - -@deffn Command top-level -This function exits all recursive editing levels; it does not return a -value, as it jumps completely out of any computation directly back to -the main command loop. -@end deffn - -@defun recursion-depth -This function returns the current depth of recursive edits. When no -recursive edit is active, it returns 0. -@end defun - -@node Disabling Commands -@section Disabling Commands -@cindex disabled command - - @dfn{Disabling a command} marks the command as requiring user -confirmation before it can be executed. Disabling is used for commands -which might be confusing to beginning users, to prevent them from using -the commands by accident. - -@kindex disabled - The low-level mechanism for disabling a command is to put a -non-@code{nil} @code{disabled} property on the Lisp symbol for the -command. These properties are normally set up by the user's -init file (@pxref{Init File}) with Lisp expressions such as this: - -@example -(put 'upcase-region 'disabled t) -@end example - -@noindent -For a few commands, these properties are present by default (you can -remove them in your init file if you wish). - - If the value of the @code{disabled} property is a string, the message -saying the command is disabled includes that string. For example: - -@example -(put 'delete-region 'disabled - "Text deleted this way cannot be yanked back!\n") -@end example - - @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on -what happens when a disabled command is invoked interactively. -Disabling a command has no effect on calling it as a function from Lisp -programs. - -@deffn Command enable-command command -Allow @var{command} (a symbol) to be executed without special -confirmation from now on, and alter the user's init file (@pxref{Init -File}) so that this will apply to future sessions. -@end deffn - -@deffn Command disable-command command -Require special confirmation to execute @var{command} from now on, and -alter the user's init file so that this will apply to future sessions. -@end deffn - -@defvar disabled-command-function -The value of this variable should be a function. When the user -invokes a disabled command interactively, this function is called -instead of the disabled command. It can use @code{this-command-keys} -to determine what the user typed to run the command, and thus find the -command itself. - -The value may also be @code{nil}. Then all commands work normally, -even disabled ones. - -By default, the value is a function that asks the user whether to -proceed. -@end defvar - -@node Command History -@section Command History -@cindex command history -@cindex complex command -@cindex history of commands - - The command loop keeps a history of the complex commands that have -been executed, to make it convenient to repeat these commands. A -@dfn{complex command} is one for which the interactive argument reading -uses the minibuffer. This includes any @kbd{M-x} command, any -@kbd{M-:} command, and any command whose @code{interactive} -specification reads an argument from the minibuffer. Explicit use of -the minibuffer during the execution of the command itself does not cause -the command to be considered complex. - -@defvar command-history -This variable's value is a list of recent complex commands, each -represented as a form to evaluate. It continues to accumulate all -complex commands for the duration of the editing session, but when it -reaches the maximum size (@pxref{Minibuffer History}), the oldest -elements are deleted as new ones are added. - -@example -@group -command-history -@result{} ((switch-to-buffer "chistory.texi") - (describe-key "^X^[") - (visit-tags-table "~/emacs/src/") - (find-tag "repeat-complex-command")) -@end group -@end example -@end defvar - - This history list is actually a special case of minibuffer history -(@pxref{Minibuffer History}), with one special twist: the elements are -expressions rather than strings. - - There are a number of commands devoted to the editing and recall of -previous commands. The commands @code{repeat-complex-command}, and -@code{list-command-history} are described in the user manual -(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the -minibuffer, the usual minibuffer history commands are available. - -@node Keyboard Macros -@section Keyboard Macros -@cindex keyboard macros - - A @dfn{keyboard macro} is a canned sequence of input events that can -be considered a command and made the definition of a key. The Lisp -representation of a keyboard macro is a string or vector containing the -events. Don't confuse keyboard macros with Lisp macros -(@pxref{Macros}). - -@defun execute-kbd-macro kbdmacro &optional count loopfunc -This function executes @var{kbdmacro} as a sequence of events. If -@var{kbdmacro} is a string or vector, then the events in it are executed -exactly as if they had been input by the user. The sequence is -@emph{not} expected to be a single key sequence; normally a keyboard -macro definition consists of several key sequences concatenated. - -If @var{kbdmacro} is a symbol, then its function definition is used in -place of @var{kbdmacro}. If that is another symbol, this process repeats. -Eventually the result should be a string or vector. If the result is -not a symbol, string, or vector, an error is signaled. - -The argument @var{count} is a repeat count; @var{kbdmacro} is executed that -many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is -executed once. If it is 0, @var{kbdmacro} is executed over and over until it -encounters an error or a failing search. - -If @var{loopfunc} is non-@code{nil}, it is a function that is called, -without arguments, prior to each iteration of the macro. If -@var{loopfunc} returns @code{nil}, then this stops execution of the macro. - -@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}. -@end defun - -@defvar executing-kbd-macro -This variable contains the string or vector that defines the keyboard -macro that is currently executing. It is @code{nil} if no macro is -currently executing. A command can test this variable so as to behave -differently when run from an executing macro. Do not set this variable -yourself. -@end defvar - -@defvar defining-kbd-macro -This variable is non-@code{nil} if and only if a keyboard macro is -being defined. A command can test this variable so as to behave -differently while a macro is being defined. The value is -@code{append} while appending to the definition of an existing macro. -The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and -@code{end-kbd-macro} set this variable---do not set it yourself. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -@defvar last-kbd-macro -This variable is the definition of the most recently defined keyboard -macro. Its value is a string or vector, or @code{nil}. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -@defvar kbd-macro-termination-hook -This normal hook is run when a keyboard macro terminates, regardless -of what caused it to terminate (reaching the macro end or an error -which ended the macro prematurely). -@end defvar diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi deleted file mode 100644 index fe492df1d94..00000000000 --- a/doc/lispref/compile.texi +++ /dev/null @@ -1,744 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Byte Compilation -@chapter Byte Compilation -@cindex byte compilation -@cindex byte-code -@cindex compilation (Emacs Lisp) - - Emacs Lisp has a @dfn{compiler} that translates functions written -in Lisp into a special representation called @dfn{byte-code} that can be -executed more efficiently. The compiler replaces Lisp function -definitions with byte-code. When a byte-code function is called, its -definition is evaluated by the @dfn{byte-code interpreter}. - - Because the byte-compiled code is evaluated by the byte-code -interpreter, instead of being executed directly by the machine's -hardware (as true compiled code is), byte-code is completely -transportable from machine to machine without recompilation. It is not, -however, as fast as true compiled code. - - In general, any version of Emacs can run byte-compiled code produced -by recent earlier versions of Emacs, but the reverse is not true. - -@vindex no-byte-compile - If you do not want a Lisp file to be compiled, ever, put a file-local -variable binding for @code{no-byte-compile} into it, like this: - -@example -;; -*-no-byte-compile: t; -*- -@end example - -@menu -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. -@end menu - -@node Speed of Byte-Code -@section Performance of Byte-Compiled Code - - A byte-compiled function is not as efficient as a primitive function -written in C, but runs much faster than the version written in Lisp. -Here is an example: - -@example -@group -(defun silly-loop (n) - "Return the time, in seconds, to run N iterations of a loop." - (let ((t1 (float-time))) - (while (> (setq n (1- n)) 0)) - (- (float-time) t1))) -@result{} silly-loop -@end group - -@group -(silly-loop 50000000) -@result{} 10.235304117202759 -@end group - -@group -(byte-compile 'silly-loop) -@result{} @r{[Compiled code not shown]} -@end group - -@group -(silly-loop 50000000) -@result{} 3.705854892730713 -@end group -@end example - - In this example, the interpreted code required 10 seconds to run, -whereas the byte-compiled code required less than 4 seconds. These -results are representative, but actual results may vary. - -@node Compilation Functions -@section Byte-Compilation Functions -@cindex compilation functions - - You can byte-compile an individual function or macro definition with -the @code{byte-compile} function. You can compile a whole file with -@code{byte-compile-file}, or several files with -@code{byte-recompile-directory} or @code{batch-byte-compile}. - - Sometimes, the byte compiler produces warning and/or error messages -(@pxref{Compiler Errors}, for details). These messages are recorded -in a buffer called @file{*Compile-Log*}, which uses Compilation mode. -@xref{Compilation Mode,,,emacs, The GNU Emacs Manual}. - -@cindex macro compilation - Be careful when writing macro calls in files that you intend to -byte-compile. Since macro calls are expanded when they are compiled, -the macros need to be loaded into Emacs or the byte compiler will not -do the right thing. The usual way to handle this is with -@code{require} forms which specify the files containing the needed -macro definitions (@pxref{Named Features}). Normally, the -byte compiler does not evaluate the code that it is compiling, but it -handles @code{require} forms specially, by loading the specified -libraries. To avoid loading the macro definition files when someone -@emph{runs} the compiled program, write @code{eval-when-compile} -around the @code{require} calls (@pxref{Eval During Compile}). For -more details, @xref{Compiling Macros}. - - Inline (@code{defsubst}) functions are less troublesome; if you -compile a call to such a function before its definition is known, the -call will still work right, it will just run slower. - -@defun byte-compile symbol -This function byte-compiles the function definition of @var{symbol}, -replacing the previous definition with the compiled one. The function -definition of @var{symbol} must be the actual code for the function; -@code{byte-compile} does not handle function indirection. The return -value is the byte-code function object which is the compiled -definition of @var{symbol} (@pxref{Byte-Code Objects}). - -@example -@group -(defun factorial (integer) - "Compute factorial of INTEGER." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) -@result{} factorial -@end group - -@group -(byte-compile 'factorial) -@result{} -#[(integer) - "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" - [integer 1 * factorial] - 4 "Compute factorial of INTEGER."] -@end group -@end example - -If @var{symbol}'s definition is a byte-code function object, -@code{byte-compile} does nothing and returns @code{nil}. It does not -``compile the symbol's definition again'', since the original -(non-compiled) code has already been replaced in the symbol's function -cell by the byte-compiled code. - -The argument to @code{byte-compile} can also be a @code{lambda} -expression. In that case, the function returns the corresponding -compiled code but does not store it anywhere. -@end defun - -@deffn Command compile-defun &optional arg -This command reads the defun containing point, compiles it, and -evaluates the result. If you use this on a defun that is actually a -function definition, the effect is to install a compiled version of that -function. - -@code{compile-defun} normally displays the result of evaluation in the -echo area, but if @var{arg} is non-@code{nil}, it inserts the result -in the current buffer after the form it compiled. -@end deffn - -@deffn Command byte-compile-file filename &optional load -This function compiles a file of Lisp code named @var{filename} into a -file of byte-code. The output file's name is made by changing the -@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in -@samp{.el}, it adds @samp{.elc} to the end of @var{filename}. - -Compilation works by reading the input file one form at a time. If it -is a definition of a function or macro, the compiled function or macro -definition is written out. Other forms are batched together, then each -batch is compiled, and written so that its compiled code will be -executed when the file is read. All comments are discarded when the -input file is read. - -This command returns @code{t} if there were no errors and @code{nil} -otherwise. When called interactively, it prompts for the file name. - -If @var{load} is non-@code{nil}, this command loads the compiled file -after compiling it. Interactively, @var{load} is the prefix argument. - -@example -@group -$ ls -l push* --rw-r--r-- 1 lewis lewis 791 Oct 5 20:31 push.el -@end group - -@group -(byte-compile-file "~/emacs/push.el") - @result{} t -@end group - -@group -$ ls -l push* --rw-r--r-- 1 lewis lewis 791 Oct 5 20:31 push.el --rw-rw-rw- 1 lewis lewis 638 Oct 8 20:25 push.elc -@end group -@end example -@end deffn - -@deffn Command byte-recompile-directory directory &optional flag force -@cindex library compilation -This command recompiles every @samp{.el} file in @var{directory} (or -its subdirectories) that needs recompilation. A file needs -recompilation if a @samp{.elc} file exists but is older than the -@samp{.el} file. - -When a @samp{.el} file has no corresponding @samp{.elc} file, -@var{flag} says what to do. If it is @code{nil}, this command ignores -these files. If @var{flag} is 0, it compiles them. If it is neither -@code{nil} nor 0, it asks the user whether to compile each such file, -and asks about each subdirectory as well. - -Interactively, @code{byte-recompile-directory} prompts for -@var{directory} and @var{flag} is the prefix argument. - -If @var{force} is non-@code{nil}, this command recompiles every -@samp{.el} file that has a @samp{.elc} file. - -The returned value is unpredictable. -@end deffn - -@defun batch-byte-compile &optional noforce -This function runs @code{byte-compile-file} on files specified on the -command line. This function must be used only in a batch execution of -Emacs, as it kills Emacs on completion. An error in one file does not -prevent processing of subsequent files, but no output file will be -generated for it, and the Emacs process will terminate with a nonzero -status code. - -If @var{noforce} is non-@code{nil}, this function does not recompile -files that have an up-to-date @samp{.elc} file. - -@example -$ emacs -batch -f batch-byte-compile *.el -@end example -@end defun - -@node Docs and Compilation -@section Documentation Strings and Compilation -@cindex dynamic loading of documentation - - When Emacs loads functions and variables from a byte-compiled file, -it normally does not load their documentation strings into memory. -Each documentation string is ``dynamically'' loaded from the -byte-compiled file only when needed. This saves memory, and speeds up -loading by skipping the processing of the documentation strings. - - This feature has a drawback: if you delete, move, or alter the -compiled file (such as by compiling a new version), Emacs may no -longer be able to access the documentation string of previously-loaded -functions or variables. Such a problem normally only occurs if you -build Emacs yourself, and happen to edit and/or recompile the Lisp -source files. To solve it, just reload each file after recompilation. - - Dynamic loading of documentation strings from byte-compiled files is -determined, at compile time, for each byte-compiled file. It can be -disabled via the option @code{byte-compile-dynamic-docstrings}. - -@defopt byte-compile-dynamic-docstrings -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic loading of documentation strings. - -To disable the dynamic loading feature for a specific file, set this -option to @code{nil} in its header line (@pxref{File Variables, , -Local Variables in Files, emacs, The GNU Emacs Manual}), like this: - -@smallexample --*-byte-compile-dynamic-docstrings: nil;-*- -@end smallexample - -This is useful mainly if you expect to change the file, and you want -Emacs sessions that have already loaded it to keep working when the -file changes. -@end defopt - -@cindex @samp{#@@@var{count}} -@cindex @samp{#$} -Internally, the dynamic loading of documentation strings is -accomplished by writing compiled files with a special Lisp reader -construct, @samp{#@@@var{count}}. This construct skips the next -@var{count} characters. It also uses the @samp{#$} construct, which -stands for ``the name of this file, as a string''. Do not use these -constructs in Lisp source files; they are not designed to be clear to -humans reading the file. - -@node Dynamic Loading -@section Dynamic Loading of Individual Functions - -@cindex dynamic loading of functions -@cindex lazy loading - When you compile a file, you can optionally enable the @dfn{dynamic -function loading} feature (also known as @dfn{lazy loading}). With -dynamic function loading, loading the file doesn't fully read the -function definitions in the file. Instead, each function definition -contains a place-holder which refers to the file. The first time each -function is called, it reads the full definition from the file, to -replace the place-holder. - - The advantage of dynamic function loading is that loading the file -becomes much faster. This is a good thing for a file which contains -many separate user-callable functions, if using one of them does not -imply you will probably also use the rest. A specialized mode which -provides many keyboard commands often has that usage pattern: a user may -invoke the mode, but use only a few of the commands it provides. - - The dynamic loading feature has certain disadvantages: - -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer load the remaining function definitions not already loaded. - -@item -If you alter the compiled file (such as by compiling a new version), -then trying to load any function not already loaded will usually yield -nonsense results. -@end itemize - - These problems will never happen in normal circumstances with -installed Emacs files. But they are quite likely to happen with Lisp -files that you are changing. The easiest way to prevent these problems -is to reload the new compiled file immediately after each recompilation. - - The byte compiler uses the dynamic function loading feature if the -variable @code{byte-compile-dynamic} is non-@code{nil} at compilation -time. Do not set this variable globally, since dynamic loading is -desirable only for certain files. Instead, enable the feature for -specific source files with file-local variable bindings. For example, -you could do it by writing this text in the source file's first line: - -@example --*-byte-compile-dynamic: t;-*- -@end example - -@defvar byte-compile-dynamic -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic function loading. -@end defvar - -@defun fetch-bytecode function -If @var{function} is a byte-code function object, this immediately -finishes loading the byte code of @var{function} from its -byte-compiled file, if it is not fully loaded already. Otherwise, -it does nothing. It always returns @var{function}. -@end defun - -@node Eval During Compile -@section Evaluation During Compilation - - These features permit you to write code to be evaluated during -compilation of a program. - -@defspec eval-and-compile body@dots{} -This form marks @var{body} to be evaluated both when you compile the -containing code and when you run it (whether compiled or not). - -You can get a similar result by putting @var{body} in a separate file -and referring to that file with @code{require}. That method is -preferable when @var{body} is large. Effectively @code{require} is -automatically @code{eval-and-compile}, the package is loaded both when -compiling and executing. - -@code{autoload} is also effectively @code{eval-and-compile} too. It's -recognized when compiling, so uses of such a function don't produce -``not known to be defined'' warnings. - -Most uses of @code{eval-and-compile} are fairly sophisticated. - -If a macro has a helper function to build its result, and that macro -is used both locally and outside the package, then -@code{eval-and-compile} should be used to get the helper both when -compiling and then later when running. - -If functions are defined programmatically (with @code{fset} say), then -@code{eval-and-compile} can be used to have that done at compile-time -as well as run-time, so calls to those functions are checked (and -warnings about ``not known to be defined'' suppressed). -@end defspec - -@defspec eval-when-compile body@dots{} -This form marks @var{body} to be evaluated at compile time but not when -the compiled program is loaded. The result of evaluation by the -compiler becomes a constant which appears in the compiled program. If -you load the source file, rather than compiling it, @var{body} is -evaluated normally. - -@cindex compile-time constant -If you have a constant that needs some calculation to produce, -@code{eval-when-compile} can do that at compile-time. For example, - -@lisp -(defvar my-regexp - (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) -@end lisp - -@cindex macros, at compile time -If you're using another package, but only need macros from it (the -byte compiler will expand those), then @code{eval-when-compile} can be -used to load it for compiling, but not executing. For example, - -@lisp -(eval-when-compile - (require 'my-macro-package)) -@end lisp - -The same sort of thing goes for macros and @code{defsubst} functions -defined locally and only for use within the file. They are needed for -compiling the file, but in most cases they are not needed for -execution of the compiled file. For example, - -@lisp -(eval-when-compile - (unless (fboundp 'some-new-thing) - (defmacro 'some-new-thing () - (compatibility code)))) -@end lisp - -@noindent -This is often good for code that's only a fallback for compatibility -with other versions of Emacs. - -@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common -Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the -Common Lisp @samp{#.} reader macro (but not when interpreting) is closer -to what @code{eval-when-compile} does. -@end defspec - -@node Compiler Errors -@section Compiler Errors -@cindex compiler errors - - Error and warning messages from byte compilation are printed in a -buffer named @file{*Compile-Log*}. These messages include file names -and line numbers identifying the location of the problem. The usual -Emacs commands for operating on compiler output can be used on these -messages. - - When an error is due to invalid syntax in the program, the byte -compiler might get confused about the errors' exact location. One way -to investigate is to switch to the buffer @w{@file{ *Compiler -Input*}}. (This buffer name starts with a space, so it does not show -up in the Buffer Menu.) This buffer contains the program being -compiled, and point shows how far the byte compiler was able to read; -the cause of the error might be nearby. @xref{Syntax Errors}, for -some tips for locating syntax errors. - - A common type of warning issued by the byte compiler is for -functions and variables that were used but not defined. Such warnings -report the line number for the end of the file, not the locations -where the missing functions or variables were used; to find these, you -must search the file manually. - - If you are sure that a warning message about a missing function or -variable is unjustified, there are several ways to suppress it: - -@itemize @bullet -@item -You can suppress the warning for a specific call to a function -@var{func} by conditionalizing it on an @code{fboundp} test, like -this: - -@example -(if (fboundp '@var{func}) ...(@var{func} ...)...) -@end example - -@noindent -The call to @var{func} must be in the @var{then-form} of the -@code{if}, and @var{func} must appear quoted in the call to -@code{fboundp}. (This feature operates for @code{cond} as well.) - -@item -Likewise, you can suppress the warning for a specific use of a -variable @var{variable} by conditionalizing it on a @code{boundp} -test: - -@example -(if (boundp '@var{variable}) ...@var{variable}...) -@end example - -@noindent -The reference to @var{variable} must be in the @var{then-form} of the -@code{if}, and @var{variable} must appear quoted in the call to -@code{boundp}. - -@item -You can tell the compiler that a function is defined using -@code{declare-function}. @xref{Declaring Functions}. - -@item -Likewise, you can tell the compiler that a variable is defined using -@code{defvar} with no initial value. (Note that this marks the -variable as special.) @xref{Defining Variables}. -@end itemize - - You can also suppress any and all compiler warnings within a certain -expression using the construct @code{with-no-warnings}: - -@c This is implemented with a defun, but conceptually it is -@c a special form. - -@defspec with-no-warnings body@dots{} -In execution, this is equivalent to @code{(progn @var{body}...)}, -but the compiler does not issue warnings for anything that occurs -inside @var{body}. - -We recommend that you use this construct around the smallest -possible piece of code, to avoid missing possible warnings other than -one you intend to suppress. -@end defspec - - Byte compiler warnings can be controlled more precisely by setting -the variable @code{byte-compile-warnings}. See its documentation -string for details. - -@node Byte-Code Objects -@section Byte-Code Function Objects -@cindex compiled function -@cindex byte-code function -@cindex byte-code object - - Byte-compiled functions have a special data type: they are -@dfn{byte-code function objects}. Whenever such an object appears as -a function to be called, Emacs uses the byte-code interpreter to -execute the byte-code. - - Internally, a byte-code function object is much like a vector; its -elements can be accessed using @code{aref}. Its printed -representation is like that for a vector, with an additional @samp{#} -before the opening @samp{[}. It must have at least four elements; -there is no maximum number, but only the first six elements have any -normal use. They are: - -@table @var -@item arglist -The list of argument symbols. - -@item byte-code -The string containing the byte-code instructions. - -@item constants -The vector of Lisp objects referenced by the byte code. These include -symbols used as function names and variable names. - -@item stacksize -The maximum stack size this function needs. - -@item docstring -The documentation string (if any); otherwise, @code{nil}. The value may -be a number or a list, in case the documentation string is stored in a -file. Use the function @code{documentation} to get the real -documentation string (@pxref{Accessing Documentation}). - -@item interactive -The interactive spec (if any). This can be a string or a Lisp -expression. It is @code{nil} for a function that isn't interactive. -@end table - -Here's an example of a byte-code function object, in printed -representation. It is the definition of the command -@code{backward-sexp}. - -@example -#[(&optional arg) - "^H\204^F^@@\301^P\302^H[!\207" - [arg 1 forward-sexp] - 2 - 254435 - "^p"] -@end example - - The primitive way to create a byte-code object is with -@code{make-byte-code}: - -@defun make-byte-code &rest elements -This function constructs and returns a byte-code function object -with @var{elements} as its elements. -@end defun - - You should not try to come up with the elements for a byte-code -function yourself, because if they are inconsistent, Emacs may crash -when you call the function. Always leave it to the byte compiler to -create these objects; it makes the elements consistent (we hope). - -@node Disassembly -@section Disassembled Byte-Code -@cindex disassembled byte-code - - People do not write byte-code; that job is left to the byte -compiler. But we provide a disassembler to satisfy a cat-like -curiosity. The disassembler converts the byte-compiled code into -human-readable form. - - The byte-code interpreter is implemented as a simple stack machine. -It pushes values onto a stack of its own, then pops them off to use them -in calculations whose results are themselves pushed back on the stack. -When a byte-code function returns, it pops a value off the stack and -returns it as the value of the function. - - In addition to the stack, byte-code functions can use, bind, and set -ordinary Lisp variables, by transferring values between variables and -the stack. - -@deffn Command disassemble object &optional buffer-or-name -This command displays the disassembled code for @var{object}. In -interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, -the output goes in a buffer named @file{*Disassemble*}. If -@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the -name of an existing buffer. Then the output goes there, at point, and -point is left before the output. - -The argument @var{object} can be a function name, a lambda expression -(@pxref{Lambda Expressions}), or a byte-code object (@pxref{Byte-Code -Objects}). If it is a lambda expression, @code{disassemble} compiles -it and disassembles the resulting compiled code. -@end deffn - - Here are two examples of using the @code{disassemble} function. We -have added explanatory comments to help you relate the byte-code to the -Lisp source; these do not appear in the output of @code{disassemble}. - -@example -@group -(defun factorial (integer) - "Compute factorial of an integer." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) - @result{} factorial -@end group - -@group -(factorial 4) - @result{} 24 -@end group - -@group -(disassemble 'factorial) - @print{} byte-code for factorial: - doc: Compute factorial of an integer. - args: (integer) -@end group - -@group -0 varref integer ; @r{Get the value of @code{integer} and} - ; @r{push it onto the stack.} -1 constant 1 ; @r{Push 1 onto stack.} -@end group -@group -2 eqlsign ; @r{Pop top two values off stack, compare} - ; @r{them, and push result onto stack.} -@end group -@group -3 goto-if-nil 1 ; @r{Pop and test top of stack;} - ; @r{if @code{nil}, go to 1, else continue.} -6 constant 1 ; @r{Push 1 onto top of stack.} -7 return ; @r{Return the top element of the stack.} -@end group -@group -8:1 varref integer ; @r{Push value of @code{integer} onto stack.} -9 constant factorial ; @r{Push @code{factorial} onto stack.} -10 varref integer ; @r{Push value of @code{integer} onto stack.} -11 sub1 ; @r{Pop @code{integer}, decrement value,} - ; @r{push new value onto stack.} -12 call 1 ; @r{Call function @code{factorial} using first} - ; @r{(i.e., top) stack element as argument;} - ; @r{push returned value onto stack.} -@end group -@group -13 mult ; @r{Pop top two values off stack, multiply} - ; @r{them, and push result onto stack.} -14 return ; @r{Return the top element of the stack.} -@end group -@end example - -The @code{silly-loop} function is somewhat more complex: - -@example -@group -(defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) - @result{} silly-loop -@end group - -@group -(disassemble 'silly-loop) - @print{} byte-code for silly-loop: - doc: Return time before and after N iterations of a loop. - args: (n) -@end group - -@group -0 constant current-time-string ; @r{Push @code{current-time-string}} - ; @r{onto top of stack.} -@end group -@group -1 call 0 ; @r{Call @code{current-time-string} with no} - ; @r{argument, push result onto stack.} -@end group -@group -2 varbind t1 ; @r{Pop stack and bind @code{t1} to popped value.} -@end group -@group -3:1 varref n ; @r{Get value of @code{n} from the environment} - ; @r{and push the value on the stack.} -4 sub1 ; @r{Subtract 1 from top of stack.} -@end group -@group -5 dup ; @r{Duplicate top of stack; i.e., copy the top} - ; @r{of the stack and push copy onto stack.} -6 varset n ; @r{Pop the top of the stack,} - ; @r{and bind @code{n} to the value.} - -;; @r{(In effect, the sequence @code{dup varset} copies the top of the stack} -;; @r{into the value of @code{n} without popping it.)} -@end group - -@group -7 constant 0 ; @r{Push 0 onto stack.} -8 gtr ; @r{Pop top two values off stack,} - ; @r{test if @var{n} is greater than 0} - ; @r{and push result onto stack.} -@end group -@group -9 goto-if-not-nil 1 ; @r{Goto 1 if @code{n} > 0} - ; @r{(this continues the while loop)} - ; @r{else continue.} -@end group -@group -12 varref t1 ; @r{Push value of @code{t1} onto stack.} -13 constant current-time-string ; @r{Push @code{current-time-string}} - ; @r{onto the top of the stack.} -14 call 0 ; @r{Call @code{current-time-string} again.} -@end group -@group -15 unbind 1 ; @r{Unbind @code{t1} in local environment.} -16 list2 ; @r{Pop top two elements off stack, create a} - ; @r{list of them, and push it onto stack.} -17 return ; @r{Return value of the top of stack.} -@end group -@end example diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi deleted file mode 100644 index 800e174d3fc..00000000000 --- a/doc/lispref/control.texi +++ /dev/null @@ -1,1457 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Control Structures -@chapter Control Structures -@cindex special forms for control structures -@cindex control structures - - A Lisp program consists of a set of @dfn{expressions}, or -@dfn{forms} (@pxref{Forms}). We control the order of execution of -these forms by enclosing them in @dfn{control structures}. Control -structures are special forms which control when, whether, or how many -times to execute the forms they contain. - -@cindex textual order - The simplest order of execution is sequential execution: first form -@var{a}, then form @var{b}, and so on. This is what happens when you -write several forms in succession in the body of a function, or at top -level in a file of Lisp code---the forms are executed in the order -written. We call this @dfn{textual order}. For example, if a function -body consists of two forms @var{a} and @var{b}, evaluation of the -function evaluates first @var{a} and then @var{b}. The result of -evaluating @var{b} becomes the value of the function. - - Explicit control structures make possible an order of execution other -than sequential. - - Emacs Lisp provides several kinds of control structure, including -other varieties of sequencing, conditionals, iteration, and (controlled) -jumps---all discussed below. The built-in control structures are -special forms since their subforms are not necessarily evaluated or not -evaluated sequentially. You can use macros to define your own control -structure constructs (@pxref{Macros}). - -@menu -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. -@end menu - -@node Sequencing -@section Sequencing - - Evaluating forms in the order they appear is the most common way -control passes from one form to another. In some contexts, such as in a -function body, this happens automatically. Elsewhere you must use a -control structure construct to do this: @code{progn}, the simplest -control construct of Lisp. - - A @code{progn} special form looks like this: - -@example -@group -(progn @var{a} @var{b} @var{c} @dots{}) -@end group -@end example - -@noindent -and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in -that order. These forms are called the @dfn{body} of the @code{progn} form. -The value of the last form in the body becomes the value of the entire -@code{progn}. @code{(progn)} returns @code{nil}. - -@cindex implicit @code{progn} - In the early days of Lisp, @code{progn} was the only way to execute -two or more forms in succession and use the value of the last of them. -But programmers found they often needed to use a @code{progn} in the -body of a function, where (at that time) only one form was allowed. So -the body of a function was made into an ``implicit @code{progn}'': -several forms are allowed just as in the body of an actual @code{progn}. -Many other control structures likewise contain an implicit @code{progn}. -As a result, @code{progn} is not used as much as it was many years ago. -It is needed now most often inside an @code{unwind-protect}, @code{and}, -@code{or}, or in the @var{then}-part of an @code{if}. - -@defspec progn forms@dots{} -This special form evaluates all of the @var{forms}, in textual -order, returning the result of the final form. - -@example -@group -(progn (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The third form" -@end group -@end example -@end defspec - - Two other constructs likewise evaluate a series of forms but return -different values: - -@defspec prog1 form1 forms@dots{} -This special form evaluates @var{form1} and all of the @var{forms}, in -textual order, returning the result of @var{form1}. - -@example -@group -(prog1 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The first form" -@end group -@end example - -Here is a way to remove the first element from a list in the variable -@code{x}, then return the value of that former element: - -@example -(prog1 (car x) (setq x (cdr x))) -@end example -@end defspec - -@defspec prog2 form1 form2 forms@dots{} -This special form evaluates @var{form1}, @var{form2}, and all of the -following @var{forms}, in textual order, returning the result of -@var{form2}. - -@example -@group -(prog2 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The second form" -@end group -@end example -@end defspec - -@node Conditionals -@section Conditionals -@cindex conditional evaluation - - Conditional control structures choose among alternatives. Emacs Lisp -has four conditional forms: @code{if}, which is much the same as in -other languages; @code{when} and @code{unless}, which are variants of -@code{if}; and @code{cond}, which is a generalized case statement. - -@defspec if condition then-form else-forms@dots{} -@code{if} chooses between the @var{then-form} and the @var{else-forms} -based on the value of @var{condition}. If the evaluated @var{condition} is -non-@code{nil}, @var{then-form} is evaluated and the result returned. -Otherwise, the @var{else-forms} are evaluated in textual order, and the -value of the last one is returned. (The @var{else} part of @code{if} is -an example of an implicit @code{progn}. @xref{Sequencing}.) - -If @var{condition} has the value @code{nil}, and no @var{else-forms} are -given, @code{if} returns @code{nil}. - -@code{if} is a special form because the branch that is not selected is -never evaluated---it is ignored. Thus, in this example, -@code{true} is not printed because @code{print} is never called: - -@example -@group -(if nil - (print 'true) - 'very-false) -@result{} very-false -@end group -@end example -@end defspec - -@defmac when condition then-forms@dots{} -This is a variant of @code{if} where there are no @var{else-forms}, -and possibly several @var{then-forms}. In particular, - -@example -(when @var{condition} @var{a} @var{b} @var{c}) -@end example - -@noindent -is entirely equivalent to - -@example -(if @var{condition} (progn @var{a} @var{b} @var{c}) nil) -@end example -@end defmac - -@defmac unless condition forms@dots{} -This is a variant of @code{if} where there is no @var{then-form}: - -@example -(unless @var{condition} @var{a} @var{b} @var{c}) -@end example - -@noindent -is entirely equivalent to - -@example -(if @var{condition} nil - @var{a} @var{b} @var{c}) -@end example -@end defmac - -@defspec cond clause@dots{} -@code{cond} chooses among an arbitrary number of alternatives. Each -@var{clause} in the @code{cond} must be a list. The @sc{car} of this -list is the @var{condition}; the remaining elements, if any, the -@var{body-forms}. Thus, a clause looks like this: - -@example -(@var{condition} @var{body-forms}@dots{}) -@end example - -@code{cond} tries the clauses in textual order, by evaluating the -@var{condition} of each clause. If the value of @var{condition} is -non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its -@var{body-forms}, and returns the value of the last of @var{body-forms}. -Any remaining clauses are ignored. - -If the value of @var{condition} is @code{nil}, the clause ``fails'', so -the @code{cond} moves on to the following clause, trying its @var{condition}. - -A clause may also look like this: - -@example -(@var{condition}) -@end example - -@noindent -Then, if @var{condition} is non-@code{nil} when tested, the @code{cond} -form returns the value of @var{condition}. - -If every @var{condition} evaluates to @code{nil}, so that every clause -fails, @code{cond} returns @code{nil}. - -The following example has four clauses, which test for the cases where -the value of @code{x} is a number, string, buffer and symbol, -respectively: - -@example -@group -(cond ((numberp x) x) - ((stringp x) x) - ((bufferp x) - (setq temporary-hack x) ; @r{multiple body-forms} - (buffer-name x)) ; @r{in one clause} - ((symbolp x) (symbol-value x))) -@end group -@end example - -Often we want to execute the last clause whenever none of the previous -clauses was successful. To do this, we use @code{t} as the -@var{condition} of the last clause, like this: @code{(t -@var{body-forms})}. The form @code{t} evaluates to @code{t}, which is -never @code{nil}, so this clause never fails, provided the @code{cond} -gets to it at all. For example: - -@example -@group -(setq a 5) -(cond ((eq a 'hack) 'foo) - (t "default")) -@result{} "default" -@end group -@end example - -@noindent -This @code{cond} expression returns @code{foo} if the value of @code{a} -is @code{hack}, and returns the string @code{"default"} otherwise. -@end defspec - -Any conditional construct can be expressed with @code{cond} or with -@code{if}. Therefore, the choice between them is a matter of style. -For example: - -@example -@group -(if @var{a} @var{b} @var{c}) -@equiv{} -(cond (@var{a} @var{b}) (t @var{c})) -@end group -@end example - -@menu -* Pattern matching case statement:: -@end menu - -@node Pattern matching case statement -@subsection Pattern matching case statement -@cindex pcase -@cindex pattern matching - -To compare a particular value against various possible cases, the macro -@code{pcase} can come handy. It takes the following form: - -@example -(pcase @var{exp} @var{branch}1 @var{branch}2 @var{branch}3 @dots{}) -@end example - -where each @var{branch} takes the form @code{(@var{upattern} -@var{body-forms}@dots{})}. - -It will first evaluate @var{exp} and then compare the value against each -@var{upattern} to see which @var{branch} to use, after which it will run the -corresponding @var{body-forms}. A common use case is to distinguish -between a few different constant values: - -@example -(pcase (get-return-code x) - (`success (message "Done!")) - (`would-block (message "Sorry, can't do it now")) - (`read-only (message "The shmliblick is read-only")) - (`access-denied (message "You do not have the needed rights")) - (code (message "Unknown return code %S" code))) -@end example - -In the last clause, @code{code} is a variable that gets bound to the value that -was returned by @code{(get-return-code x)}. - -To give a more complex example, a simple interpreter for a little -expression language could look like (note that this example requires -lexical binding): - -@example -(defun evaluate (exp env) - (pcase exp - (`(add ,x ,y) (+ (evaluate x env) (evaluate y env))) - (`(call ,fun ,arg) (funcall (evaluate fun env) (evaluate arg env))) - (`(fn ,arg ,body) (lambda (val) - (evaluate body (cons (cons arg val) env)))) - ((pred numberp) exp) - ((pred symbolp) (cdr (assq exp env))) - (_ (error "Unknown expression %S" exp)))) -@end example - -Where @code{`(add ,x ,y)} is a pattern that checks that @code{exp} is a three -element list starting with the symbol @code{add}, then extracts the second and -third elements and binds them to the variables @code{x} and @code{y}. -@code{(pred numberp)} is a pattern that simply checks that @code{exp} -is a number, and @code{_} is the catch-all pattern that matches anything. - -Here are some sample programs including their evaluation results: - -@example -(evaluate '(add 1 2) nil) ;=> 3 -(evaluate '(add x y) '((x . 1) (y . 2))) ;=> 3 -(evaluate '(call (fn x (add 1 x)) 2) nil) ;=> 3 -(evaluate '(sub 1 2) nil) ;=> error -@end example - -There are two kinds of patterns involved in @code{pcase}, called -@emph{U-patterns} and @emph{Q-patterns}. The @var{upattern} mentioned above -are U-patterns and can take the following forms: - -@table @code -@item `@var{qpattern} -This is one of the most common form of patterns. The intention is to mimic the -backquote macro: this pattern matches those values that could have been built -by such a backquote expression. Since we're pattern matching rather than -building a value, the unquote does not indicate where to plug an expression, -but instead it lets one specify a U-pattern that should match the value at -that location. - -More specifically, a Q-pattern can take the following forms: -@table @code -@item (@var{qpattern1} . @var{qpattern2}) -This pattern matches any cons cell whose @code{car} matches @var{QPATTERN1} and -whose @code{cdr} matches @var{PATTERN2}. -@item @var{atom} -This pattern matches any atom @code{equal} to @var{atom}. -@item ,@var{upattern} -This pattern matches any object that matches the @var{upattern}. -@end table - -@item @var{symbol} -A mere symbol in a U-pattern matches anything, and additionally let-binds this -symbol to the value that it matched, so that you can later refer to it, either -in the @var{body-forms} or also later in the pattern. -@item _ -This so-called @emph{don't care} pattern matches anything, like the previous -one, but unlike symbol patterns it does not bind any variable. -@item (pred @var{pred}) -This pattern matches if the function @var{pred} returns non-@code{nil} when -called with the object being matched. -@item (or @var{upattern1} @var{upattern2}@dots{}) -This pattern matches as soon as one of the argument patterns succeeds. -All argument patterns should let-bind the same variables. -@item (and @var{upattern1} @var{upattern2}@dots{}) -This pattern matches only if all the argument patterns succeed. -@item (guard @var{exp}) -This pattern ignores the object being examined and simply succeeds if @var{exp} -evaluates to non-@code{nil} and fails otherwise. It is typically used inside -an @code{and} pattern. For example, @code{(and x (guard (< x 10)))} -is a pattern which matches any number smaller than 10 and let-binds it to -the variable @code{x}. -@end table - -@node Combining Conditions -@section Constructs for Combining Conditions - - This section describes three constructs that are often used together -with @code{if} and @code{cond} to express complicated conditions. The -constructs @code{and} and @code{or} can also be used individually as -kinds of multiple conditional constructs. - -@defun not condition -This function tests for the falsehood of @var{condition}. It returns -@code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise. -The function @code{not} is identical to @code{null}, and we recommend -using the name @code{null} if you are testing for an empty list. -@end defun - -@defspec and conditions@dots{} -The @code{and} special form tests whether all the @var{conditions} are -true. It works by evaluating the @var{conditions} one by one in the -order written. - -If any of the @var{conditions} evaluates to @code{nil}, then the result -of the @code{and} must be @code{nil} regardless of the remaining -@var{conditions}; so @code{and} returns @code{nil} right away, ignoring -the remaining @var{conditions}. - -If all the @var{conditions} turn out non-@code{nil}, then the value of -the last of them becomes the value of the @code{and} form. Just -@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate -because all the @var{conditions} turned out non-@code{nil}. (Think -about it; which one did not?) - -Here is an example. The first condition returns the integer 1, which is -not @code{nil}. Similarly, the second condition returns the integer 2, -which is not @code{nil}. The third condition is @code{nil}, so the -remaining condition is never evaluated. - -@example -@group -(and (print 1) (print 2) nil (print 3)) - @print{} 1 - @print{} 2 -@result{} nil -@end group -@end example - -Here is a more realistic example of using @code{and}: - -@example -@group -(if (and (consp foo) (eq (car foo) 'x)) - (message "foo is a list starting with x")) -@end group -@end example - -@noindent -Note that @code{(car foo)} is not executed if @code{(consp foo)} returns -@code{nil}, thus avoiding an error. - -@code{and} expressions can also be written using either @code{if} or -@code{cond}. Here's how: - -@example -@group -(and @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(if @var{arg1} (if @var{arg2} @var{arg3})) -@equiv{} -(cond (@var{arg1} (cond (@var{arg2} @var{arg3})))) -@end group -@end example -@end defspec - -@defspec or conditions@dots{} -The @code{or} special form tests whether at least one of the -@var{conditions} is true. It works by evaluating all the -@var{conditions} one by one in the order written. - -If any of the @var{conditions} evaluates to a non-@code{nil} value, then -the result of the @code{or} must be non-@code{nil}; so @code{or} returns -right away, ignoring the remaining @var{conditions}. The value it -returns is the non-@code{nil} value of the condition just evaluated. - -If all the @var{conditions} turn out @code{nil}, then the @code{or} -expression returns @code{nil}. Just @code{(or)}, with no -@var{conditions}, returns @code{nil}, appropriate because all the -@var{conditions} turned out @code{nil}. (Think about it; which one -did not?) - -For example, this expression tests whether @code{x} is either -@code{nil} or the integer zero: - -@example -(or (eq x nil) (eq x 0)) -@end example - -Like the @code{and} construct, @code{or} can be written in terms of -@code{cond}. For example: - -@example -@group -(or @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(cond (@var{arg1}) - (@var{arg2}) - (@var{arg3})) -@end group -@end example - -You could almost write @code{or} in terms of @code{if}, but not quite: - -@example -@group -(if @var{arg1} @var{arg1} - (if @var{arg2} @var{arg2} - @var{arg3})) -@end group -@end example - -@noindent -This is not completely equivalent because it can evaluate @var{arg1} or -@var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2} -@var{arg3})} never evaluates any argument more than once. -@end defspec - -@node Iteration -@section Iteration -@cindex iteration -@cindex recursion - - Iteration means executing part of a program repetitively. For -example, you might want to repeat some computation once for each element -of a list, or once for each integer from 0 to @var{n}. You can do this -in Emacs Lisp with the special form @code{while}: - -@defspec while condition forms@dots{} -@code{while} first evaluates @var{condition}. If the result is -non-@code{nil}, it evaluates @var{forms} in textual order. Then it -reevaluates @var{condition}, and if the result is non-@code{nil}, it -evaluates @var{forms} again. This process repeats until @var{condition} -evaluates to @code{nil}. - -There is no limit on the number of iterations that may occur. The loop -will continue until either @var{condition} evaluates to @code{nil} or -until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}). - -The value of a @code{while} form is always @code{nil}. - -@example -@group -(setq num 0) - @result{} 0 -@end group -@group -(while (< num 4) - (princ (format "Iteration %d." num)) - (setq num (1+ num))) - @print{} Iteration 0. - @print{} Iteration 1. - @print{} Iteration 2. - @print{} Iteration 3. - @result{} nil -@end group -@end example - -To write a ``repeat...until'' loop, which will execute something on each -iteration and then do the end-test, put the body followed by the -end-test in a @code{progn} as the first argument of @code{while}, as -shown here: - -@example -@group -(while (progn - (forward-line 1) - (not (looking-at "^$")))) -@end group -@end example - -@noindent -This moves forward one line and continues moving by lines until it -reaches an empty line. It is peculiar in that the @code{while} has no -body, just the end test (which also does the real work of moving point). -@end defspec - - The @code{dolist} and @code{dotimes} macros provide convenient ways to -write two common kinds of loops. - -@defmac dolist (var list [result]) body@dots{} -This construct executes @var{body} once for each element of -@var{list}, binding the variable @var{var} locally to hold the current -element. Then it returns the value of evaluating @var{result}, or -@code{nil} if @var{result} is omitted. For example, here is how you -could use @code{dolist} to define the @code{reverse} function: - -@example -(defun reverse (list) - (let (value) - (dolist (elt list value) - (setq value (cons elt value))))) -@end example -@end defmac - -@defmac dotimes (var count [result]) body@dots{} -This construct executes @var{body} once for each integer from 0 -(inclusive) to @var{count} (exclusive), binding the variable @var{var} -to the integer for the current iteration. Then it returns the value -of evaluating @var{result}, or @code{nil} if @var{result} is omitted. -Here is an example of using @code{dotimes} to do something 100 times: - -@example -(dotimes (i 100) - (insert "I will not obey absurd orders\n")) -@end example -@end defmac - -@node Nonlocal Exits -@section Nonlocal Exits -@cindex nonlocal exits - - A @dfn{nonlocal exit} is a transfer of control from one point in a -program to another remote point. Nonlocal exits can occur in Emacs Lisp -as a result of errors; you can also use them under explicit control. -Nonlocal exits unbind all variable bindings made by the constructs being -exited. - -@menu -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an error happens. -@end menu - -@node Catch and Throw -@subsection Explicit Nonlocal Exits: @code{catch} and @code{throw} - - Most control constructs affect only the flow of control within the -construct itself. The function @code{throw} is the exception to this -rule of normal program execution: it performs a nonlocal exit on -request. (There are other exceptions, but they are for error handling -only.) @code{throw} is used inside a @code{catch}, and jumps back to -that @code{catch}. For example: - -@example -@group -(defun foo-outer () - (catch 'foo - (foo-inner))) - -(defun foo-inner () - @dots{} - (if x - (throw 'foo t)) - @dots{}) -@end group -@end example - -@noindent -The @code{throw} form, if executed, transfers control straight back to -the corresponding @code{catch}, which returns immediately. The code -following the @code{throw} is not executed. The second argument of -@code{throw} is used as the return value of the @code{catch}. - - The function @code{throw} finds the matching @code{catch} based on the -first argument: it searches for a @code{catch} whose first argument is -@code{eq} to the one specified in the @code{throw}. If there is more -than one applicable @code{catch}, the innermost one takes precedence. -Thus, in the above example, the @code{throw} specifies @code{foo}, and -the @code{catch} in @code{foo-outer} specifies the same symbol, so that -@code{catch} is the applicable one (assuming there is no other matching -@code{catch} in between). - - Executing @code{throw} exits all Lisp constructs up to the matching -@code{catch}, including function calls. When binding constructs such -as @code{let} or function calls are exited in this way, the bindings -are unbound, just as they are when these constructs exit normally -(@pxref{Local Variables}). Likewise, @code{throw} restores the buffer -and position saved by @code{save-excursion} (@pxref{Excursions}), and -the narrowing status saved by @code{save-restriction}. It also runs -any cleanups established with the @code{unwind-protect} special form -when it exits that form (@pxref{Cleanups}). - - The @code{throw} need not appear lexically within the @code{catch} -that it jumps to. It can equally well be called from another function -called within the @code{catch}. As long as the @code{throw} takes place -chronologically after entry to the @code{catch}, and chronologically -before exit from it, it has access to that @code{catch}. This is why -@code{throw} can be used in commands such as @code{exit-recursive-edit} -that throw back to the editor command loop (@pxref{Recursive Editing}). - -@cindex CL note---only @code{throw} in Emacs -@quotation -@b{Common Lisp note:} Most other versions of Lisp, including Common Lisp, -have several ways of transferring control nonsequentially: @code{return}, -@code{return-from}, and @code{go}, for example. Emacs Lisp has only -@code{throw}. The @file{cl-lib} library provides versions of some of -these. @xref{Blocks and Exits,,,cl,Common Lisp Extensions}. -@end quotation - -@defspec catch tag body@dots{} -@cindex tag on run time stack -@code{catch} establishes a return point for the @code{throw} function. -The return point is distinguished from other such return points by -@var{tag}, which may be any Lisp object except @code{nil}. The argument -@var{tag} is evaluated normally before the return point is established. - -With the return point in effect, @code{catch} evaluates the forms of the -@var{body} in textual order. If the forms execute normally (without -error or nonlocal exit) the value of the last body form is returned from -the @code{catch}. - -If a @code{throw} is executed during the execution of @var{body}, -specifying the same value @var{tag}, the @code{catch} form exits -immediately; the value it returns is whatever was specified as the -second argument of @code{throw}. -@end defspec - -@defun throw tag value -The purpose of @code{throw} is to return from a return point previously -established with @code{catch}. The argument @var{tag} is used to choose -among the various existing return points; it must be @code{eq} to the value -specified in the @code{catch}. If multiple return points match @var{tag}, -the innermost one is used. - -The argument @var{value} is used as the value to return from that -@code{catch}. - -@kindex no-catch -If no return point is in effect with tag @var{tag}, then a @code{no-catch} -error is signaled with data @code{(@var{tag} @var{value})}. -@end defun - -@node Examples of Catch -@subsection Examples of @code{catch} and @code{throw} - - One way to use @code{catch} and @code{throw} is to exit from a doubly -nested loop. (In most languages, this would be done with a ``goto''.) -Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} -varying from 0 to 9: - -@example -@group -(defun search-foo () - (catch 'loop - (let ((i 0)) - (while (< i 10) - (let ((j 0)) - (while (< j 10) - (if (foo i j) - (throw 'loop (list i j))) - (setq j (1+ j)))) - (setq i (1+ i)))))) -@end group -@end example - -@noindent -If @code{foo} ever returns non-@code{nil}, we stop immediately and return a -list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the -@code{catch} returns normally, and the value is @code{nil}, since that -is the result of the @code{while}. - - Here are two tricky examples, slightly different, showing two -return points at once. First, two return points with the same tag, -@code{hack}: - -@example -@group -(defun catch2 (tag) - (catch tag - (throw 'hack 'yes))) -@result{} catch2 -@end group - -@group -(catch 'hack - (print (catch2 'hack)) - 'no) -@print{} yes -@result{} no -@end group -@end example - -@noindent -Since both return points have tags that match the @code{throw}, it goes to -the inner one, the one established in @code{catch2}. Therefore, -@code{catch2} returns normally with value @code{yes}, and this value is -printed. Finally the second body form in the outer @code{catch}, which is -@code{'no}, is evaluated and returned from the outer @code{catch}. - - Now let's change the argument given to @code{catch2}: - -@example -@group -(catch 'hack - (print (catch2 'quux)) - 'no) -@result{} yes -@end group -@end example - -@noindent -We still have two return points, but this time only the outer one has -the tag @code{hack}; the inner one has the tag @code{quux} instead. -Therefore, @code{throw} makes the outer @code{catch} return the value -@code{yes}. The function @code{print} is never called, and the -body-form @code{'no} is never evaluated. - -@node Errors -@subsection Errors -@cindex errors - - When Emacs Lisp attempts to evaluate a form that, for some reason, -cannot be evaluated, it @dfn{signals} an @dfn{error}. - - When an error is signaled, Emacs's default reaction is to print an -error message and terminate execution of the current command. This is -the right thing to do in most cases, such as if you type @kbd{C-f} at -the end of the buffer. - - In complicated programs, simple termination may not be what you want. -For example, the program may have made temporary changes in data -structures, or created temporary buffers that should be deleted before -the program is finished. In such cases, you would use -@code{unwind-protect} to establish @dfn{cleanup expressions} to be -evaluated in case of error. (@xref{Cleanups}.) Occasionally, you may -wish the program to continue execution despite an error in a subroutine. -In these cases, you would use @code{condition-case} to establish -@dfn{error handlers} to recover control in case of error. - - Resist the temptation to use error handling to transfer control from -one part of the program to another; use @code{catch} and @code{throw} -instead. @xref{Catch and Throw}. - -@menu -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. -@end menu - -@node Signaling Errors -@subsubsection How to Signal an Error -@cindex signaling errors - - @dfn{Signaling} an error means beginning error processing. Error -processing normally aborts all or part of the running program and -returns to a point that is set up to handle the error -(@pxref{Processing of Errors}). Here we describe how to signal an -error. - - Most errors are signaled ``automatically'' within Lisp primitives -which you call for other purposes, such as if you try to take the -@sc{car} of an integer or move forward a character at the end of the -buffer. You can also signal errors explicitly with the functions -@code{error} and @code{signal}. - - Quitting, which happens when the user types @kbd{C-g}, is not -considered an error, but it is handled almost like an error. -@xref{Quitting}. - - Every error specifies an error message, one way or another. The -message should state what is wrong (``File does not exist''), not how -things ought to be (``File must exist''). The convention in Emacs -Lisp is that error messages should start with a capital letter, but -should not end with any sort of punctuation. - -@defun error format-string &rest args -This function signals an error with an error message constructed by -applying @code{format} (@pxref{Formatting Strings}) to -@var{format-string} and @var{args}. - -These examples show typical uses of @code{error}: - -@example -@group -(error "That is an error -- try something else") - @error{} That is an error -- try something else -@end group - -@group -(error "You have committed %d errors" 10) - @error{} You have committed 10 errors -@end group -@end example - -@code{error} works by calling @code{signal} with two arguments: the -error symbol @code{error}, and a list containing the string returned by -@code{format}. - -@strong{Warning:} If you want to use your own string as an error message -verbatim, don't just write @code{(error @var{string})}. If @var{string} -contains @samp{%}, it will be interpreted as a format specifier, with -undesirable results. Instead, use @code{(error "%s" @var{string})}. -@end defun - -@defun signal error-symbol data -@anchor{Definition of signal} -This function signals an error named by @var{error-symbol}. The -argument @var{data} is a list of additional Lisp objects relevant to -the circumstances of the error. - -The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol -defined with @code{define-error}. This is how Emacs Lisp classifies different -sorts of errors. @xref{Error Symbols}, for a description of error symbols, -error conditions and condition names. - -If the error is not handled, the two arguments are used in printing -the error message. Normally, this error message is provided by the -@code{error-message} property of @var{error-symbol}. If @var{data} is -non-@code{nil}, this is followed by a colon and a comma separated list -of the unevaluated elements of @var{data}. For @code{error}, the -error message is the @sc{car} of @var{data} (that must be a string). -Subcategories of @code{file-error} are handled specially. - -The number and significance of the objects in @var{data} depends on -@var{error-symbol}. For example, with a @code{wrong-type-argument} error, -there should be two objects in the list: a predicate that describes the type -that was expected, and the object that failed to fit that type. - -Both @var{error-symbol} and @var{data} are available to any error -handlers that handle the error: @code{condition-case} binds a local -variable to a list of the form @code{(@var{error-symbol} .@: -@var{data})} (@pxref{Handling Errors}). - -The function @code{signal} never returns. -@c (though in older Emacs versions it sometimes could). - -@example -@group -(signal 'wrong-number-of-arguments '(x y)) - @error{} Wrong number of arguments: x, y -@end group - -@group -(signal 'no-such-error '("My unknown error condition")) - @error{} peculiar error: "My unknown error condition" -@end group -@end example -@end defun - -@cindex user errors, signaling -@defun user-error format-string &rest args -This function behaves exactly like @code{error}, except that it uses -the error symbol @code{user-error} rather than @code{error}. As the -name suggests, this is intended to report errors on the part of the -user, rather than errors in the code itself. For example, -if you try to use the command @code{Info-history-back} (@kbd{l}) to -move back beyond the start of your Info browsing history, Emacs -signals a @code{user-error}. Such errors do not cause entry to the -debugger, even when @code{debug-on-error} is non-@code{nil}. -@xref{Error Debugging}. -@end defun - -@cindex CL note---no continuable errors -@quotation -@b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp -concept of continuable errors. -@end quotation - -@node Processing of Errors -@subsubsection How Emacs Processes Errors - -When an error is signaled, @code{signal} searches for an active -@dfn{handler} for the error. A handler is a sequence of Lisp -expressions designated to be executed if an error happens in part of the -Lisp program. If the error has an applicable handler, the handler is -executed, and control resumes following the handler. The handler -executes in the environment of the @code{condition-case} that -established it; all functions called within that @code{condition-case} -have already been exited, and the handler cannot return to them. - -If there is no applicable handler for the error, it terminates the -current command and returns control to the editor command loop. (The -command loop has an implicit handler for all kinds of errors.) The -command loop's handler uses the error symbol and associated data to -print an error message. You can use the variable -@code{command-error-function} to control how this is done: - -@defvar command-error-function -This variable, if non-@code{nil}, specifies a function to use to -handle errors that return control to the Emacs command loop. The -function should take three arguments: @var{data}, a list of the same -form that @code{condition-case} would bind to its variable; -@var{context}, a string describing the situation in which the error -occurred, or (more often) @code{nil}; and @var{caller}, the Lisp -function which called the primitive that signaled the error. -@end defvar - -@cindex @code{debug-on-error} use -An error that has no explicit handler may call the Lisp debugger. The -debugger is enabled if the variable @code{debug-on-error} (@pxref{Error -Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs -in the environment of the error, so that you can examine values of -variables precisely as they were at the time of the error. - -@node Handling Errors -@subsubsection Writing Code to Handle Errors -@cindex error handler -@cindex handling errors - - The usual effect of signaling an error is to terminate the command -that is running and return immediately to the Emacs editor command loop. -You can arrange to trap errors occurring in a part of your program by -establishing an error handler, with the special form -@code{condition-case}. A simple example looks like this: - -@example -@group -(condition-case nil - (delete-file filename) - (error nil)) -@end group -@end example - -@noindent -This deletes the file named @var{filename}, catching any error and -returning @code{nil} if an error occurs. (You can use the macro -@code{ignore-errors} for a simple case like this; see below.) - - The @code{condition-case} construct is often used to trap errors that -are predictable, such as failure to open a file in a call to -@code{insert-file-contents}. It is also used to trap errors that are -totally unpredictable, such as when the program evaluates an expression -read from the user. - - The second argument of @code{condition-case} is called the -@dfn{protected form}. (In the example above, the protected form is a -call to @code{delete-file}.) The error handlers go into effect when -this form begins execution and are deactivated when this form returns. -They remain in effect for all the intervening time. In particular, they -are in effect during the execution of functions called by this form, in -their subroutines, and so on. This is a good thing, since, strictly -speaking, errors can be signaled only by Lisp primitives (including -@code{signal} and @code{error}) called by the protected form, not by the -protected form itself. - - The arguments after the protected form are handlers. Each handler -lists one or more @dfn{condition names} (which are symbols) to specify -which errors it will handle. The error symbol specified when an error -is signaled also defines a list of condition names. A handler applies -to an error if they have any condition names in common. In the example -above, there is one handler, and it specifies one condition name, -@code{error}, which covers all errors. - - The search for an applicable handler checks all the established handlers -starting with the most recently established one. Thus, if two nested -@code{condition-case} forms offer to handle the same error, the inner of -the two gets to handle it. - - If an error is handled by some @code{condition-case} form, this -ordinarily prevents the debugger from being run, even if -@code{debug-on-error} says this error should invoke the debugger. - - If you want to be able to debug errors that are caught by a -@code{condition-case}, set the variable @code{debug-on-signal} to a -non-@code{nil} value. You can also specify that a particular handler -should let the debugger run first, by writing @code{debug} among the -conditions, like this: - -@example -@group -(condition-case nil - (delete-file filename) - ((debug error) nil)) -@end group -@end example - -@noindent -The effect of @code{debug} here is only to prevent -@code{condition-case} from suppressing the call to the debugger. Any -given error will invoke the debugger only if @code{debug-on-error} and -the other usual filtering mechanisms say it should. @xref{Error Debugging}. - -@defmac condition-case-unless-debug var protected-form handlers@dots{} -The macro @code{condition-case-unless-debug} provides another way to -handle debugging of such forms. It behaves exactly like -@code{condition-case}, unless the variable @code{debug-on-error} is -non-@code{nil}, in which case it does not handle any errors at all. -@end defmac - - Once Emacs decides that a certain handler handles the error, it -returns control to that handler. To do so, Emacs unbinds all variable -bindings made by binding constructs that are being exited, and -executes the cleanups of all @code{unwind-protect} forms that are -being exited. Once control arrives at the handler, the body of the -handler executes normally. - - After execution of the handler body, execution returns from the -@code{condition-case} form. Because the protected form is exited -completely before execution of the handler, the handler cannot resume -execution at the point of the error, nor can it examine variable -bindings that were made within the protected form. All it can do is -clean up and proceed. - - Error signaling and handling have some resemblance to @code{throw} and -@code{catch} (@pxref{Catch and Throw}), but they are entirely separate -facilities. An error cannot be caught by a @code{catch}, and a -@code{throw} cannot be handled by an error handler (though using -@code{throw} when there is no suitable @code{catch} signals an error -that can be handled). - -@defspec condition-case var protected-form handlers@dots{} -This special form establishes the error handlers @var{handlers} around -the execution of @var{protected-form}. If @var{protected-form} executes -without error, the value it returns becomes the value of the -@code{condition-case} form; in this case, the @code{condition-case} has -no effect. The @code{condition-case} form makes a difference when an -error occurs during @var{protected-form}. - -Each of the @var{handlers} is a list of the form @code{(@var{conditions} -@var{body}@dots{})}. Here @var{conditions} is an error condition name -to be handled, or a list of condition names (which can include @code{debug} -to allow the debugger to run before the handler); @var{body} is one or more -Lisp expressions to be executed when this handler handles an error. -Here are examples of handlers: - -@example -@group -(error nil) - -(arith-error (message "Division by zero")) - -((arith-error file-error) - (message - "Either division by zero or failure to open a file")) -@end group -@end example - -Each error that occurs has an @dfn{error symbol} that describes what -kind of error it is, and which describes also a list of condition names -(@pxref{Error Symbols}). Emacs -searches all the active @code{condition-case} forms for a handler that -specifies one or more of these condition names; the innermost matching -@code{condition-case} handles the error. Within this -@code{condition-case}, the first applicable handler handles the error. - -After executing the body of the handler, the @code{condition-case} -returns normally, using the value of the last form in the handler body -as the overall value. - -@cindex error description -The argument @var{var} is a variable. @code{condition-case} does not -bind this variable when executing the @var{protected-form}, only when it -handles an error. At that time, it binds @var{var} locally to an -@dfn{error description}, which is a list giving the particulars of the -error. The error description has the form @code{(@var{error-symbol} -. @var{data})}. The handler can refer to this list to decide what to -do. For example, if the error is for failure opening a file, the file -name is the second element of @var{data}---the third element of the -error description. - -If @var{var} is @code{nil}, that means no variable is bound. Then the -error symbol and associated data are not available to the handler. - -@cindex rethrow a signal -Sometimes it is necessary to re-throw a signal caught by -@code{condition-case}, for some outer-level handler to catch. Here's -how to do that: - -@example - (signal (car err) (cdr err)) -@end example - -@noindent -where @code{err} is the error description variable, the first argument -to @code{condition-case} whose error condition you want to re-throw. -@xref{Definition of signal}. -@end defspec - -@defun error-message-string error-descriptor -This function returns the error message string for a given error -descriptor. It is useful if you want to handle an error by printing the -usual error message for that error. @xref{Definition of signal}. -@end defun - -@cindex @code{arith-error} example -Here is an example of using @code{condition-case} to handle the error -that results from dividing by zero. The handler displays the error -message (but without a beep), then returns a very large number. - -@example -@group -(defun safe-divide (dividend divisor) - (condition-case err - ;; @r{Protected form.} - (/ dividend divisor) -@end group -@group - ;; @r{The handler.} - (arith-error ; @r{Condition.} - ;; @r{Display the usual message for this error.} - (message "%s" (error-message-string err)) - 1000000))) -@result{} safe-divide -@end group - -@group -(safe-divide 5 0) - @print{} Arithmetic error: (arith-error) -@result{} 1000000 -@end group -@end example - -@noindent -The handler specifies condition name @code{arith-error} so that it -will handle only division-by-zero errors. Other kinds of errors will -not be handled (by this @code{condition-case}). Thus: - -@example -@group -(safe-divide nil 3) - @error{} Wrong type argument: number-or-marker-p, nil -@end group -@end example - - Here is a @code{condition-case} that catches all kinds of errors, -including those from @code{error}: - -@example -@group -(setq baz 34) - @result{} 34 -@end group - -@group -(condition-case err - (if (eq baz 35) - t - ;; @r{This is a call to the function @code{error}.} - (error "Rats! The variable %s was %s, not 35" 'baz baz)) - ;; @r{This is the handler; it is not a form.} - (error (princ (format "The error was: %s" err)) - 2)) -@print{} The error was: (error "Rats! The variable baz was 34, not 35") -@result{} 2 -@end group -@end example - -@defmac ignore-errors body@dots{} -This construct executes @var{body}, ignoring any errors that occur -during its execution. If the execution is without error, -@code{ignore-errors} returns the value of the last form in @var{body}; -otherwise, it returns @code{nil}. - -Here's the example at the beginning of this subsection rewritten using -@code{ignore-errors}: - -@example -@group - (ignore-errors - (delete-file filename)) -@end group -@end example -@end defmac - -@defmac with-demoted-errors format body@dots{} -This macro is like a milder version of @code{ignore-errors}. Rather -than suppressing errors altogether, it converts them into messages. -It uses the string @var{format} to format the message. -@var{format} should contain a single @samp{%}-sequence; e.g., -@code{"Error: %S"}. Use @code{with-demoted-errors} around code -that is not expected to signal errors, but -should be robust if one does occur. Note that this macro uses -@code{condition-case-unless-debug} rather than @code{condition-case}. -@end defmac - -@node Error Symbols -@subsubsection Error Symbols and Condition Names -@cindex error symbol -@cindex error name -@cindex condition name -@cindex user-defined error -@kindex error-conditions -@kindex define-error - - When you signal an error, you specify an @dfn{error symbol} to specify -the kind of error you have in mind. Each error has one and only one -error symbol to categorize it. This is the finest classification of -errors defined by the Emacs Lisp language. - - These narrow classifications are grouped into a hierarchy of wider -classes called @dfn{error conditions}, identified by @dfn{condition -names}. The narrowest such classes belong to the error symbols -themselves: each error symbol is also a condition name. There are also -condition names for more extensive classes, up to the condition name -@code{error} which takes in all kinds of errors (but not @code{quit}). -Thus, each error has one or more condition names: @code{error}, the -error symbol if that is distinct from @code{error}, and perhaps some -intermediate classifications. - -@defun define-error name message &optional parent - In order for a symbol to be an error symbol, it must be defined with -@code{define-error} which takes a parent condition (defaults to @code{error}). -This parent defines the conditions that this kind of error belongs to. -The transitive set of parents always includes the error symbol itself, and the -symbol @code{error}. Because quitting is not considered an error, the set of -parents of @code{quit} is just @code{(quit)}. -@end defun - -@cindex peculiar error - In addition to its parents, the error symbol has a @var{message} which -is a string to be printed when that error is signaled but not handled. If that -message is not valid, the error message @samp{peculiar error} is used. -@xref{Definition of signal}. - -Internally, the set of parents is stored in the @code{error-conditions} -property of the error symbol and the message is stored in the -@code{error-message} property of the error symbol. - - Here is how we define a new error symbol, @code{new-error}: - -@example -@group -(define-error 'new-error "A new error" 'my-own-errors) -@end group -@end example - -@noindent -This error has several condition names: @code{new-error}, the narrowest -classification; @code{my-own-errors}, which we imagine is a wider -classification; and all the conditions of @code{my-own-errors} which should -include @code{error}, which is the widest of all. - - The error string should start with a capital letter but it should -not end with a period. This is for consistency with the rest of Emacs. - - Naturally, Emacs will never signal @code{new-error} on its own; only -an explicit call to @code{signal} (@pxref{Definition of signal}) in -your code can do this: - -@example -@group -(signal 'new-error '(x y)) - @error{} A new error: x, y -@end group -@end example - - This error can be handled through any of its condition names. -This example handles @code{new-error} and any other errors in the class -@code{my-own-errors}: - -@example -@group -(condition-case foo - (bar nil t) - (my-own-errors nil)) -@end group -@end example - - The significant way that errors are classified is by their condition -names---the names used to match errors with handlers. An error symbol -serves only as a convenient way to specify the intended error message -and list of condition names. It would be cumbersome to give -@code{signal} a list of condition names rather than one error symbol. - - By contrast, using only error symbols without condition names would -seriously decrease the power of @code{condition-case}. Condition names -make it possible to categorize errors at various levels of generality -when you write an error handler. Using error symbols alone would -eliminate all but the narrowest level of classification. - - @xref{Standard Errors}, for a list of the main error symbols -and their conditions. - -@node Cleanups -@subsection Cleaning Up from Nonlocal Exits - - The @code{unwind-protect} construct is essential whenever you -temporarily put a data structure in an inconsistent state; it permits -you to make the data consistent again in the event of an error or -throw. (Another more specific cleanup construct that is used only for -changes in buffer contents is the atomic change group; @ref{Atomic -Changes}.) - -@defspec unwind-protect body-form cleanup-forms@dots{} -@cindex cleanup forms -@cindex protected forms -@cindex error cleanup -@cindex unwinding -@code{unwind-protect} executes @var{body-form} with a guarantee that -the @var{cleanup-forms} will be evaluated if control leaves -@var{body-form}, no matter how that happens. @var{body-form} may -complete normally, or execute a @code{throw} out of the -@code{unwind-protect}, or cause an error; in all cases, the -@var{cleanup-forms} will be evaluated. - -If @var{body-form} finishes normally, @code{unwind-protect} returns the -value of @var{body-form}, after it evaluates the @var{cleanup-forms}. -If @var{body-form} does not finish, @code{unwind-protect} does not -return any value in the normal sense. - -Only @var{body-form} is protected by the @code{unwind-protect}. If any -of the @var{cleanup-forms} themselves exits nonlocally (via a -@code{throw} or an error), @code{unwind-protect} is @emph{not} -guaranteed to evaluate the rest of them. If the failure of one of the -@var{cleanup-forms} has the potential to cause trouble, then protect -it with another @code{unwind-protect} around that form. - -The number of currently active @code{unwind-protect} forms counts, -together with the number of local variable bindings, against the limit -@code{max-specpdl-size} (@pxref{Definition of max-specpdl-size,, Local -Variables}). -@end defspec - - For example, here we make an invisible buffer for temporary use, and -make sure to kill it before finishing: - -@example -@group -(let ((buffer (get-buffer-create " *temp*"))) - (with-current-buffer buffer - (unwind-protect - @var{body-form} - (kill-buffer buffer)))) -@end group -@end example - -@noindent -You might think that we could just as well write @code{(kill-buffer -(current-buffer))} and dispense with the variable @code{buffer}. -However, the way shown above is safer, if @var{body-form} happens to -get an error after switching to a different buffer! (Alternatively, -you could write a @code{save-current-buffer} around @var{body-form}, -to ensure that the temporary buffer becomes current again in time to -kill it.) - - Emacs includes a standard macro called @code{with-temp-buffer} which -expands into more or less the code shown above (@pxref{Definition of -with-temp-buffer,, Current Buffer}). Several of the macros defined in -this manual use @code{unwind-protect} in this way. - -@findex ftp-login - Here is an actual example derived from an FTP package. It creates a -process (@pxref{Processes}) to try to establish a connection to a remote -machine. As the function @code{ftp-login} is highly susceptible to -numerous problems that the writer of the function cannot anticipate, it -is protected with a form that guarantees deletion of the process in the -event of failure. Otherwise, Emacs might fill up with useless -subprocesses. - -@example -@group -(let ((win nil)) - (unwind-protect - (progn - (setq process (ftp-setup-buffer host file)) - (if (setq win (ftp-login process host user password)) - (message "Logged in") - (error "Ftp login failed"))) - (or win (and process (delete-process process))))) -@end group -@end example - - This example has a small bug: if the user types @kbd{C-g} to -quit, and the quit happens immediately after the function -@code{ftp-setup-buffer} returns but before the variable @code{process} is -set, the process will not be killed. There is no easy way to fix this bug, -but at least it is very unlikely. diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi deleted file mode 100644 index 0c6497fb4ef..00000000000 --- a/doc/lispref/customize.texi +++ /dev/null @@ -1,1467 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1997-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Customization -@chapter Customization Settings - -@cindex customization item - Users of Emacs can customize variables and faces without writing -Lisp code, by using the Customize interface. @xref{Easy -Customization,,, emacs, The GNU Emacs Manual}. This chapter describes -how to define @dfn{customization items} that users can interact with -through the Customize interface. - - Customization items include customizable variables, which are -defined with the -@ifinfo -@code{defcustom} macro (@pxref{Variable Definitions}); -@end ifinfo -@ifnotinfo -@code{defcustom} macro; -@end ifnotinfo -customizable faces, which are defined with @code{defface} (described -separately in @ref{Defining Faces}); and @dfn{customization groups}, -defined with -@ifinfo -@code{defgroup} (@pxref{Group Definitions}), -@end ifinfo -@ifnotinfo -@code{defgroup}, -@end ifnotinfo -which act as containers for groups of related customization items. - -@menu -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. -* Applying Customizations:: Functions to apply customization settings. -* Custom Themes:: Writing Custom themes. -@end menu - -@node Common Keywords -@section Common Item Keywords - -@cindex customization keywords - The customization declarations that we will describe in the next few -sections---@code{defcustom}, @code{defgroup}, etc.---all accept -keyword arguments (@pxref{Constant Variables}) for specifying various -information. This section describes keywords that apply to all types -of customization declarations. - - All of these keywords, except @code{:tag}, can be used more than once -in a given item. Each use of the keyword has an independent effect. -The keyword @code{:tag} is an exception because any given item can only -display one name. - -@table @code -@item :tag @var{label} -@kindex tag@r{, customization keyword} -Use @var{label}, a string, instead of the item's name, to label the -item in customization menus and buffers. @strong{Don't use a tag -which is substantially different from the item's real name; that would -cause confusion.} - -@kindex group@r{, customization keyword} -@item :group @var{group} -Put this customization item in group @var{group}. When you use -@code{:group} in a @code{defgroup}, it makes the new group a subgroup of -@var{group}. - -If you use this keyword more than once, you can put a single item into -more than one group. Displaying any of those groups will show this -item. Please don't overdo this, since the result would be annoying. - -@item :link @var{link-data} -@kindex link@r{, customization keyword} -Include an external link after the documentation string for this item. -This is a sentence containing a button that references some -other documentation. - -There are several alternatives you can use for @var{link-data}: - -@table @code -@item (custom-manual @var{info-node}) -Link to an Info node; @var{info-node} is a string which specifies the -node name, as in @code{"(emacs)Top"}. The link appears as -@samp{[Manual]} in the customization buffer and enters the built-in -Info reader on @var{info-node}. - -@item (info-link @var{info-node}) -Like @code{custom-manual} except that the link appears -in the customization buffer with the Info node name. - -@item (url-link @var{url}) -Link to a web page; @var{url} is a string which specifies the -@acronym{URL}. The link appears in the customization buffer as -@var{url} and invokes the WWW browser specified by -@code{browse-url-browser-function}. - -@item (emacs-commentary-link @var{library}) -Link to the commentary section of a library; @var{library} is a string -which specifies the library name. @xref{Library Headers}. - -@item (emacs-library-link @var{library}) -Link to an Emacs Lisp library file; @var{library} is a string which -specifies the library name. - -@item (file-link @var{file}) -Link to a file; @var{file} is a string which specifies the name of the -file to visit with @code{find-file} when the user invokes this link. - -@item (function-link @var{function}) -Link to the documentation of a function; @var{function} is a string -which specifies the name of the function to describe with -@code{describe-function} when the user invokes this link. - -@item (variable-link @var{variable}) -Link to the documentation of a variable; @var{variable} is a string -which specifies the name of the variable to describe with -@code{describe-variable} when the user invokes this link. - -@item (custom-group-link @var{group}) -Link to another customization group. Invoking it creates a new -customization buffer for @var{group}. -@end table - -You can specify the text to use in the customization buffer by adding -@code{:tag @var{name}} after the first element of the @var{link-data}; -for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to -the Emacs manual which appears in the buffer as @samp{foo}. - -You can use this keyword more than once, to add multiple links. - -@item :load @var{file} -@kindex load@r{, customization keyword} -Load file @var{file} (a string) before displaying this customization -item (@pxref{Loading}). Loading is done with @code{load}, and only if -the file is not already loaded. - -@item :require @var{feature} -@kindex require@r{, customization keyword} -Execute @code{(require '@var{feature})} when your saved customizations -set the value of this item. @var{feature} should be a symbol. - -The most common reason to use @code{:require} is when a variable enables -a feature such as a minor mode, and just setting the variable won't have -any effect unless the code which implements the mode is loaded. - -@item :version @var{version} -@kindex version@r{, customization keyword} -This keyword specifies that the item was first introduced in Emacs -version @var{version}, or that its default value was changed in that -version. The value @var{version} must be a string. - -@item :package-version '(@var{package} . @var{version}) -@kindex package-version@r{, customization keyword} -This keyword specifies that the item was first introduced in -@var{package} version @var{version}, or that its meaning or default -value was changed in that version. This keyword takes priority over -@code{:version}. - -@var{package} should be the official name of the package, as a symbol -(e.g., @code{MH-E}). @var{version} should be a string. If the -package @var{package} is released as part of Emacs, @var{package} and -@var{version} should appear in the value of -@code{customize-package-emacs-version-alist}. -@end table - -Packages distributed as part of Emacs that use the -@code{:package-version} keyword must also update the -@code{customize-package-emacs-version-alist} variable. - -@defvar customize-package-emacs-version-alist -This alist provides a mapping for the versions of Emacs that are -associated with versions of a package listed in the -@code{:package-version} keyword. Its elements are: - -@example -(@var{package} (@var{pversion} . @var{eversion})@dots{}) -@end example - -For each @var{package}, which is a symbol, there are one or more -elements that contain a package version @var{pversion} with an -associated Emacs version @var{eversion}. These versions are strings. -For example, the MH-E package updates this alist with the following: - -@c Must be small else too wide. -@c FIXME obviously this is out of date (in the code). -@smallexample -(add-to-list 'customize-package-emacs-version-alist - '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1") - ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1") - ("7.4" . "22.1") ("8.0" . "22.1"))) -@end smallexample - -The value of @var{package} needs to be unique and it needs to match -the @var{package} value appearing in the @code{:package-version} -keyword. Since the user might see the value in an error message, a good -choice is the official name of the package, such as MH-E or Gnus. -@end defvar - -@node Group Definitions -@section Defining Customization Groups -@cindex define customization group -@cindex customization groups, defining - - Each Emacs Lisp package should have one main customization group -which contains all the options, faces and other groups in the package. -If the package has a small number of options and faces, use just one -group and put everything in it. When there are more than twenty or so -options and faces, then you should structure them into subgroups, and -put the subgroups under the package's main customization group. It is -OK to put some of the options and faces in the package's main group -alongside the subgroups. - - The package's main or only group should be a member of one or more of -the standard customization groups. (To display the full list of them, -use @kbd{M-x customize}.) Choose one or more of them (but not too -many), and add your group to each of them using the @code{:group} -keyword. - - The way to declare new customization groups is with @code{defgroup}. - -@defmac defgroup group members doc [keyword value]@dots{} -Declare @var{group} as a customization group containing @var{members}. -Do not quote the symbol @var{group}. The argument @var{doc} specifies -the documentation string for the group. - -The argument @var{members} is a list specifying an initial set of -customization items to be members of the group. However, most often -@var{members} is @code{nil}, and you specify the group's members by -using the @code{:group} keyword when defining those members. - -If you want to specify group members through @var{members}, each element -should have the form @code{(@var{name} @var{widget})}. Here @var{name} -is a symbol, and @var{widget} is a widget type for editing that symbol. -Useful widgets are @code{custom-variable} for a variable, -@code{custom-face} for a face, and @code{custom-group} for a group. - -When you introduce a new group into Emacs, use the @code{:version} -keyword in the @code{defgroup}; then you need not use it for -the individual members of the group. - -In addition to the common keywords (@pxref{Common Keywords}), you can -also use this keyword in @code{defgroup}: - -@table @code -@item :prefix @var{prefix} -@kindex prefix@r{, @code{defgroup} keyword} -If the name of an item in the group starts with @var{prefix}, and the -customizable variable @code{custom-unlispify-remove-prefixes} is -non-@code{nil}, the item's tag will omit @var{prefix}. A group can -have any number of prefixes. -@end table -@end defmac - -@defopt custom-unlispify-remove-prefixes -If this variable is non-@code{nil}, the prefixes specified by a -group's @code{:prefix} keyword are omitted from tag names, whenever -the user customizes the group. - -The default value is @code{nil}, i.e., the prefix-discarding feature -is disabled. This is because discarding prefixes often leads to -confusing names for options and faces. -@end defopt - -@node Variable Definitions -@section Defining Customization Variables -@cindex define customization options -@cindex customizable variables, how to define -@cindex user options, how to define - - @dfn{Customizable variables}, also called @dfn{user options}, are -global Lisp variables whose values can be set through the Customize -interface. Unlike other global variables, which are defined with -@code{defvar} (@pxref{Defining Variables}), customizable variables are -defined using the @code{defcustom} macro. In addition to calling -@code{defvar} as a subroutine, @code{defcustom} states how the -variable should be displayed in the Customize interface, the values it -is allowed to take, etc. - -@defmac defcustom option standard doc [keyword value]@dots{} -This macro declares @var{option} as a user option (i.e., a -customizable variable). You should not quote @var{option}. - -The argument @var{standard} is an expression that specifies the -standard value for @var{option}. Evaluating the @code{defcustom} form -evaluates @var{standard}, but does not necessarily bind the option to -that value. If @var{option} already has a default value, it is left -unchanged. If the user has already saved a customization for -@var{option}, the user's customized value is installed as the default -value. Otherwise, the result of evaluating @var{standard} is -installed as the default value. - -Like @code{defvar}, this macro marks @code{option} as a special -variable, meaning that it should always be dynamically bound. If -@var{option} is already lexically bound, that lexical binding remains -in effect until the binding construct exits. @xref{Variable Scoping}. - -The expression @var{standard} can be evaluated at various other times, -too---whenever the customization facility needs to know @var{option}'s -standard value. So be sure to use an expression which is harmless to -evaluate at any time. - -The argument @var{doc} specifies the documentation string for the -variable. - -If a @code{defcustom} does not specify any @code{:group}, the last group -defined with @code{defgroup} in the same file will be used. This way, most -@code{defcustom} do not need an explicit @code{:group}. - -When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp -mode (@code{eval-defun}), a special feature of @code{eval-defun} -arranges to set the variable unconditionally, without testing whether -its value is void. (The same feature applies to @code{defvar}, -@pxref{Defining Variables}.) Using @code{eval-defun} on a defcustom -that is already defined calls the @code{:set} function (see below), -if there is one. - -If you put a @code{defcustom} in a pre-loaded Emacs Lisp file -(@pxref{Building Emacs}), the standard value installed at dump time -might be incorrect, e.g., because another variable that it depends on -has not been assigned the right value yet. In that case, use -@code{custom-reevaluate-setting}, described below, to re-evaluate the -standard value after Emacs starts up. -@end defmac - - In addition to the keywords listed in @ref{Common Keywords}, this -macro accepts the following keywords: - -@table @code -@item :type @var{type} -Use @var{type} as the data type for this option. It specifies which -values are legitimate, and how to display the value -(@pxref{Customization Types}). - -@item :options @var{value-list} -@kindex options@r{, @code{defcustom} keyword} -Specify the list of reasonable values for use in this -option. The user is not restricted to using only these values, but they -are offered as convenient alternatives. - -This is meaningful only for certain types, currently including -@code{hook}, @code{plist} and @code{alist}. See the definition of the -individual types for a description of how to use @code{:options}. - -@item :set @var{setfunction} -@kindex set@r{, @code{defcustom} keyword} -Specify @var{setfunction} as the way to change the value of this -option when using the Customize interface. The function -@var{setfunction} should take two arguments, a symbol (the option -name) and the new value, and should do whatever is necessary to update -the value properly for this option (which may not mean simply setting -the option as a Lisp variable); preferably, though, it should not -modify its value argument destructively. The default for -@var{setfunction} is @code{set-default}. - -If you specify this keyword, the variable's documentation string -should describe how to do the same job in hand-written Lisp code. - -@item :get @var{getfunction} -@kindex get@r{, @code{defcustom} keyword} -Specify @var{getfunction} as the way to extract the value of this -option. The function @var{getfunction} should take one argument, a -symbol, and should return whatever customize should use as the -``current value'' for that symbol (which need not be the symbol's Lisp -value). The default is @code{default-value}. - -You have to really understand the workings of Custom to use -@code{:get} correctly. It is meant for values that are treated in -Custom as variables but are not actually stored in Lisp variables. It -is almost surely a mistake to specify @var{getfunction} for a value -that really is stored in a Lisp variable. - -@item :initialize @var{function} -@kindex initialize@r{, @code{defcustom} keyword} -@var{function} should be a function used to initialize the variable -when the @code{defcustom} is evaluated. It should take two arguments, -the option name (a symbol) and the value. Here are some predefined -functions meant for use in this way: - -@table @code -@item custom-initialize-set -Use the variable's @code{:set} function to initialize the variable, but -do not reinitialize it if it is already non-void. - -@item custom-initialize-default -Like @code{custom-initialize-set}, but use the function -@code{set-default} to set the variable, instead of the variable's -@code{:set} function. This is the usual choice for a variable whose -@code{:set} function enables or disables a minor mode; with this choice, -defining the variable will not call the minor mode function, but -customizing the variable will do so. - -@item custom-initialize-reset -Always use the @code{:set} function to initialize the variable. If -the variable is already non-void, reset it by calling the @code{:set} -function using the current value (returned by the @code{:get} method). -This is the default @code{:initialize} function. - -@item custom-initialize-changed -Use the @code{:set} function to initialize the variable, if it is -already set or has been customized; otherwise, just use -@code{set-default}. - -@item custom-initialize-safe-set -@itemx custom-initialize-safe-default -These functions behave like @code{custom-initialize-set} -(@code{custom-initialize-default}, respectively), but catch errors. -If an error occurs during initialization, they set the variable to -@code{nil} using @code{set-default}, and signal no error. - -These functions are meant for options defined in pre-loaded files, -where the @var{standard} expression may signal an error because some -required variable or function is not yet defined. The value normally -gets updated in @file{startup.el}, ignoring the value computed by -@code{defcustom}. After startup, if one unsets the value and -reevaluates the @code{defcustom}, the @var{standard} expression can be -evaluated without error. -@end table - -@item :risky @var{value} -@kindex risky@r{, @code{defcustom} keyword} -Set the variable's @code{risky-local-variable} property to -@var{value} (@pxref{File Local Variables}). - -@item :safe @var{function} -@kindex safe@r{, @code{defcustom} keyword} -Set the variable's @code{safe-local-variable} property to -@var{function} (@pxref{File Local Variables}). - -@item :set-after @var{variables} -@kindex set-after@r{, @code{defcustom} keyword} -When setting variables according to saved customizations, make sure to -set the variables @var{variables} before this one; i.e., delay -setting this variable until after those others have been handled. Use -@code{:set-after} if setting this variable won't work properly unless -those other variables already have their intended values. -@end table - - It is useful to specify the @code{:require} keyword for an option -that ``turns on'' a certain feature. This causes Emacs to load the -feature, if it is not already loaded, whenever the option is set. -@xref{Common Keywords}. Here is an example, from the library -@file{saveplace.el}: - -@example -(defcustom save-place nil - "Non-nil means automatically save place in each file..." - :type 'boolean - :require 'saveplace - :group 'save-place) -@end example - -If a customization item has a type such as @code{hook} or -@code{alist}, which supports @code{:options}, you can add additional -values to the list from outside the @code{defcustom} declaration by -calling @code{custom-add-frequent-value}. For example, if you define a -function @code{my-lisp-mode-initialization} intended to be called from -@code{emacs-lisp-mode-hook}, you might want to add that to the list of -reasonable values for @code{emacs-lisp-mode-hook}, but not by editing -its definition. You can do it thus: - -@example -(custom-add-frequent-value 'emacs-lisp-mode-hook - 'my-lisp-mode-initialization) -@end example - -@defun custom-add-frequent-value symbol value -For the customization option @var{symbol}, add @var{value} to the -list of reasonable values. - -The precise effect of adding a value depends on the customization type -of @var{symbol}. -@end defun - -Internally, @code{defcustom} uses the symbol property -@code{standard-value} to record the expression for the standard value, -@code{saved-value} to record the value saved by the user with the -customization buffer, and @code{customized-value} to record the value -set by the user with the customization buffer, but not saved. -@xref{Symbol Properties}. These properties are lists, the car of -which is an expression that evaluates to the value. - -@defun custom-reevaluate-setting symbol -This function re-evaluates the standard value of @var{symbol}, which -should be a user option declared via @code{defcustom}. If the -variable was customized, this function re-evaluates the saved value -instead. Then it sets the user option to that value (using the -option's @code{:set} property if that is defined). - -This is useful for customizable options that are defined before their -value could be computed correctly. For example, during startup Emacs -calls this function for some user options that were defined in -pre-loaded Emacs Lisp files, but whose initial values depend on -information available only at run-time. -@end defun - -@defun custom-variable-p arg -This function returns non-@code{nil} if @var{arg} is a customizable -variable. A customizable variable is either a variable that has a -@code{standard-value} or @code{custom-autoload} property (usually -meaning it was declared with @code{defcustom}), or an alias for -another customizable variable. -@end defun - -@node Customization Types -@section Customization Types - -@cindex customization types - When you define a user option with @code{defcustom}, you must specify -its @dfn{customization type}. That is a Lisp object which describes (1) -which values are legitimate and (2) how to display the value in the -customization buffer for editing. - -@kindex type@r{, @code{defcustom} keyword} - You specify the customization type in @code{defcustom} with the -@code{:type} keyword. The argument of @code{:type} is evaluated, but -only once when the @code{defcustom} is executed, so it isn't useful -for the value to vary. Normally we use a quoted constant. For -example: - -@example -(defcustom diff-command "diff" - "The command to use to run diff." - :type '(string) - :group 'diff) -@end example - - In general, a customization type is a list whose first element is a -symbol, one of the customization type names defined in the following -sections. After this symbol come a number of arguments, depending on -the symbol. Between the type symbol and its arguments, you can -optionally write keyword-value pairs (@pxref{Type Keywords}). - - Some type symbols do not use any arguments; those are called -@dfn{simple types}. For a simple type, if you do not use any -keyword-value pairs, you can omit the parentheses around the type -symbol. For example just @code{string} as a customization type is -equivalent to @code{(string)}. - - All customization types are implemented as widgets; see @ref{Top, , -Introduction, widget, The Emacs Widget Library}, for details. - -@menu -* Simple Types:: Simple customization types: sexp, integer, etc. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. -@end menu - -@node Simple Types -@subsection Simple Types - - This section describes all the simple customization types. For -several of these customization types, the customization widget -provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}. - -@table @code -@item sexp -The value may be any Lisp object that can be printed and read back. -You can use @code{sexp} as a fall-back for any option, if you don't -want to take the time to work out a more specific type to use. - -@item integer -The value must be an integer. - -@item number -The value must be a number (floating point or integer). - -@item float -The value must be floating point. - -@item string -The value must be a string. The customization buffer shows the string -without delimiting @samp{"} characters or @samp{\} quotes. - -@item regexp -Like @code{string} except that the string must be a valid regular -expression. - -@item character -The value must be a character code. A character code is actually an -integer, but this type shows the value by inserting the character in the -buffer, rather than by showing the number. - -@item file -The value must be a file name. The widget provides completion. - -@item (file :must-match t) -The value must be a file name for an existing file. The widget -provides completion. - -@item directory -The value must be a directory name. The widget provides completion. - -@item hook -The value must be a list of functions. This customization type is -used for hook variables. You can use the @code{:options} keyword in a -hook variable's @code{defcustom} to specify a list of functions -recommended for use in the hook; @xref{Variable Definitions}. - -@item symbol -The value must be a symbol. It appears in the customization buffer as -the symbol name. The widget provides completion. - -@item function -The value must be either a lambda expression or a function name. The -widget provides completion for function names. - -@item variable -The value must be a variable name. The widget provides completion. - -@item face -The value must be a symbol which is a face name. The widget provides -completion. - -@item boolean -The value is boolean---either @code{nil} or @code{t}. Note that by -using @code{choice} and @code{const} together (see the next section), -you can specify that the value must be @code{nil} or @code{t}, but also -specify the text to describe each value in a way that fits the specific -meaning of the alternative. - -@item key-sequence -The value is a key sequence. The customization buffer shows the key -sequence using the same syntax as the @kbd{kbd} function. @xref{Key -Sequences}. - -@item coding-system -The value must be a coding-system name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item color -The value must be a valid color name. The widget provides completion -for color names, as well as a sample and a button for selecting a -color name from a list of color names shown in a @file{*Colors*} -buffer. -@end table - -@node Composite Types -@subsection Composite Types -@cindex composite types (customization) - - When none of the simple types is appropriate, you can use composite -types, which build new types from other types or from specified data. -The specified types or data are called the @dfn{arguments} of the -composite type. The composite type normally looks like this: - -@example -(@var{constructor} @var{arguments}@dots{}) -@end example - -@noindent -but you can also add keyword-value pairs before the arguments, like -this: - -@example -(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{}) -@end example - - Here is a table of constructors and how to use them to write -composite types: - -@table @code -@item (cons @var{car-type} @var{cdr-type}) -The value must be a cons cell, its @sc{car} must fit @var{car-type}, and -its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string -symbol)} is a customization type which matches values such as -@code{("foo" . foo)}. - -In the customization buffer, the @sc{car} and @sc{cdr} are displayed -and edited separately, each according to their specified type. - -@item (list @var{element-types}@dots{}) -The value must be a list with exactly as many elements as the -@var{element-types} given; and each element must fit the -corresponding @var{element-type}. - -For example, @code{(list integer string function)} describes a list of -three elements; the first element must be an integer, the second a -string, and the third a function. - -In the customization buffer, each element is displayed and edited -separately, according to the type specified for it. - -@item (group @var{element-types}@dots{}) -This works like @code{list} except for the formatting -of text in the Custom buffer. @code{list} labels each -element value with its tag; @code{group} does not. - -@item (vector @var{element-types}@dots{}) -Like @code{list} except that the value must be a vector instead of a -list. The elements work the same as in @code{list}. - -@item (alist :key-type @var{key-type} :value-type @var{value-type}) -The value must be a list of cons-cells, the @sc{car} of each cell -representing a key of customization type @var{key-type}, and the -@sc{cdr} of the same cell representing a value of customization type -@var{value-type}. The user can add and delete key/value pairs, and -edit both the key and the value of each pair. - -If omitted, @var{key-type} and @var{value-type} default to -@code{sexp}. - -The user can add any key matching the specified key type, but you can -give some keys a preferential treatment by specifying them with the -@code{:options} (see @ref{Variable Definitions}). The specified keys -will always be shown in the customize buffer (together with a suitable -value), with a checkbox to include or exclude or disable the key/value -pair from the alist. The user will not be able to edit the keys -specified by the @code{:options} keyword argument. - -The argument to the @code{:options} keywords should be a list of -specifications for reasonable keys in the alist. Ordinarily, they are -simply atoms, which stand for themselves. For example: - -@example -:options '("foo" "bar" "baz") -@end example - -@noindent -specifies that there are three ``known'' keys, namely @code{"foo"}, -@code{"bar"} and @code{"baz"}, which will always be shown first. - -You may want to restrict the value type for specific keys, for -example, the value associated with the @code{"bar"} key can only be an -integer. You can specify this by using a list instead of an atom in -the list. The first element will specify the key, like before, while -the second element will specify the value type. For example: - -@example -:options '("foo" ("bar" integer) "baz") -@end example - -Finally, you may want to change how the key is presented. By default, -the key is simply shown as a @code{const}, since the user cannot change -the special keys specified with the @code{:options} keyword. However, -you may want to use a more specialized type for presenting the key, like -@code{function-item} if you know it is a symbol with a function binding. -This is done by using a customization type specification instead of a -symbol for the key. - -@example -:options '("foo" - ((function-item some-function) integer) - "baz") -@end example - -Many alists use lists with two elements, instead of cons cells. For -example, - -@example -(defcustom list-alist - '(("foo" 1) ("bar" 2) ("baz" 3)) - "Each element is a list of the form (KEY VALUE).") -@end example - -@noindent -instead of - -@example -(defcustom cons-alist - '(("foo" . 1) ("bar" . 2) ("baz" . 3)) - "Each element is a cons-cell (KEY . VALUE).") -@end example - -Because of the way lists are implemented on top of cons cells, you can -treat @code{list-alist} in the example above as a cons cell alist, where -the value type is a list with a single element containing the real -value. - -@example -(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) - "Each element is a list of the form (KEY VALUE)." - :type '(alist :value-type (group integer))) -@end example - -The @code{group} widget is used here instead of @code{list} only because -the formatting is better suited for the purpose. - -Similarly, you can have alists with more values associated with each -key, using variations of this trick: - -@example -(defcustom person-data '(("brian" 50 t) - ("dorith" 55 nil) - ("ken" 52 t)) - "Alist of basic info about people. -Each element has the form (NAME AGE MALE-FLAG)." - :type '(alist :value-type (group integer boolean))) -@end example - -@item (plist :key-type @var{key-type} :value-type @var{value-type}) -This customization type is similar to @code{alist} (see above), except -that (i) the information is stored as a property list, -(@pxref{Property Lists}), and (ii) @var{key-type}, if omitted, -defaults to @code{symbol} rather than @code{sexp}. - -@item (choice @var{alternative-types}@dots{}) -The value must fit one of @var{alternative-types}. For example, -@code{(choice integer string)} allows either an integer or a string. - -In the customization buffer, the user selects an alternative -using a menu, and can then edit the value in the usual way for that -alternative. - -Normally the strings in this menu are determined automatically from the -choices; however, you can specify different strings for the menu by -including the @code{:tag} keyword in the alternatives. For example, if -an integer stands for a number of spaces, while a string is text to use -verbatim, you might write the customization type this way, - -@example -(choice (integer :tag "Number of spaces") - (string :tag "Literal text")) -@end example - -@noindent -so that the menu offers @samp{Number of spaces} and @samp{Literal text}. - -In any alternative for which @code{nil} is not a valid value, other than -a @code{const}, you should specify a valid default for that alternative -using the @code{:value} keyword. @xref{Type Keywords}. - -If some values are covered by more than one of the alternatives, -customize will choose the first alternative that the value fits. This -means you should always list the most specific types first, and the -most general last. Here's an example of proper usage: - -@example -(choice (const :tag "Off" nil) - symbol (sexp :tag "Other")) -@end example - -@noindent -This way, the special value @code{nil} is not treated like other -symbols, and symbols are not treated like other Lisp expressions. - -@item (radio @var{element-types}@dots{}) -This is similar to @code{choice}, except that the choices are displayed -using `radio buttons' rather than a menu. This has the advantage of -displaying documentation for the choices when applicable and so is often -a good choice for a choice between constant functions -(@code{function-item} customization types). - -@item (const @var{value}) -The value must be @var{value}---nothing else is allowed. - -The main use of @code{const} is inside of @code{choice}. For example, -@code{(choice integer (const nil))} allows either an integer or -@code{nil}. - -@code{:tag} is often used with @code{const}, inside of @code{choice}. -For example, - -@example -(choice (const :tag "Yes" t) - (const :tag "No" nil) - (const :tag "Ask" foo)) -@end example - -@noindent -describes a variable for which @code{t} means yes, @code{nil} means no, -and @code{foo} means ``ask''. - -@item (other @var{value}) -This alternative can match any Lisp value, but if the user chooses this -alternative, that selects the value @var{value}. - -The main use of @code{other} is as the last element of @code{choice}. -For example, - -@example -(choice (const :tag "Yes" t) - (const :tag "No" nil) - (other :tag "Ask" foo)) -@end example - -@noindent -describes a variable for which @code{t} means yes, @code{nil} means no, -and anything else means ``ask''. If the user chooses @samp{Ask} from -the menu of alternatives, that specifies the value @code{foo}; but any -other value (not @code{t}, @code{nil} or @code{foo}) displays as -@samp{Ask}, just like @code{foo}. - -@item (function-item @var{function}) -Like @code{const}, but used for values which are functions. This -displays the documentation string as well as the function name. -The documentation string is either the one you specify with -@code{:doc}, or @var{function}'s own documentation string. - -@item (variable-item @var{variable}) -Like @code{const}, but used for values which are variable names. This -displays the documentation string as well as the variable name. The -documentation string is either the one you specify with @code{:doc}, or -@var{variable}'s own documentation string. - -@item (set @var{types}@dots{}) -The value must be a list, and each element of the list must match one of -the @var{types} specified. - -This appears in the customization buffer as a checklist, so that each of -@var{types} may have either one corresponding element or none. It is -not possible to specify two different elements that match the same one -of @var{types}. For example, @code{(set integer symbol)} allows one -integer and/or one symbol in the list; it does not allow multiple -integers or multiple symbols. As a result, it is rare to use -nonspecific types such as @code{integer} in a @code{set}. - -Most often, the @var{types} in a @code{set} are @code{const} types, as -shown here: - -@example -(set (const :bold) (const :italic)) -@end example - -Sometimes they describe possible elements in an alist: - -@example -(set (cons :tag "Height" (const height) integer) - (cons :tag "Width" (const width) integer)) -@end example - -@noindent -That lets the user specify a height value optionally -and a width value optionally. - -@item (repeat @var{element-type}) -The value must be a list and each element of the list must fit the type -@var{element-type}. This appears in the customization buffer as a -list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding -more elements or removing elements. - -@item (restricted-sexp :match-alternatives @var{criteria}) -This is the most general composite type construct. The value may be -any Lisp object that satisfies one of @var{criteria}. @var{criteria} -should be a list, and each element should be one of these -possibilities: - -@itemize @bullet -@item -A predicate---that is, a function of one argument that has no side -effects, and returns either @code{nil} or non-@code{nil} according to -the argument. Using a predicate in the list says that objects for which -the predicate returns non-@code{nil} are acceptable. - -@item -A quoted constant---that is, @code{'@var{object}}. This sort of element -in the list says that @var{object} itself is an acceptable value. -@end itemize - -For example, - -@example -(restricted-sexp :match-alternatives - (integerp 't 'nil)) -@end example - -@noindent -allows integers, @code{t} and @code{nil} as legitimate values. - -The customization buffer shows all legitimate values using their read -syntax, and the user edits them textually. -@end table - - Here is a table of the keywords you can use in keyword-value pairs -in a composite type: - -@table @code -@item :tag @var{tag} -Use @var{tag} as the name of this alternative, for user communication -purposes. This is useful for a type that appears inside of a -@code{choice}. - -@item :match-alternatives @var{criteria} -@kindex match-alternatives@r{, customization keyword} -Use @var{criteria} to match possible values. This is used only in -@code{restricted-sexp}. - -@item :args @var{argument-list} -@kindex args@r{, customization keyword} -Use the elements of @var{argument-list} as the arguments of the type -construct. For instance, @code{(const :args (foo))} is equivalent to -@code{(const foo)}. You rarely need to write @code{:args} explicitly, -because normally the arguments are recognized automatically as -whatever follows the last keyword-value pair. -@end table - -@node Splicing into Lists -@subsection Splicing into Lists - - The @code{:inline} feature lets you splice a variable number of -elements into the middle of a @code{list} or @code{vector} -customization type. You use it by adding @code{:inline t} to a type -specification which is contained in a @code{list} or @code{vector} -specification. - - Normally, each entry in a @code{list} or @code{vector} type -specification describes a single element type. But when an entry -contains @code{:inline t}, the value it matches is merged directly -into the containing sequence. For example, if the entry matches a -list with three elements, those become three elements of the overall -sequence. This is analogous to @samp{,@@} in a backquote construct -(@pxref{Backquote}). - - For example, to specify a list whose first element must be @code{baz} -and whose remaining arguments should be zero or more of @code{foo} and -@code{bar}, use this customization type: - -@example -(list (const baz) (set :inline t (const foo) (const bar))) -@end example - -@noindent -This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)} -and @code{(baz foo bar)}. - - When the element-type is a @code{choice}, you use @code{:inline} not -in the @code{choice} itself, but in (some of) the alternatives of the -@code{choice}. For example, to match a list which must start with a -file name, followed either by the symbol @code{t} or two strings, use -this customization type: - -@example -(list file - (choice (const t) - (list :inline t string string))) -@end example - -@noindent -If the user chooses the first alternative in the choice, then the -overall list has two elements and the second element is @code{t}. If -the user chooses the second alternative, then the overall list has three -elements and the second and third must be strings. - -@node Type Keywords -@subsection Type Keywords - -You can specify keyword-argument pairs in a customization type after the -type name symbol. Here are the keywords you can use, and their -meanings: - -@table @code -@item :value @var{default} -Provide a default value. - -If @code{nil} is not a valid value for the alternative, then it is -essential to specify a valid default with @code{:value}. - -If you use this for a type that appears as an alternative inside of -@code{choice}; it specifies the default value to use, at first, if and -when the user selects this alternative with the menu in the -customization buffer. - -Of course, if the actual value of the option fits this alternative, it -will appear showing the actual value, not @var{default}. - -@item :format @var{format-string} -@kindex format@r{, customization keyword} -This string will be inserted in the buffer to represent the value -corresponding to the type. The following @samp{%} escapes are available -for use in @var{format-string}: - -@table @samp -@item %[@var{button}%] -Display the text @var{button} marked as a button. The @code{:action} -attribute specifies what the button will do if the user invokes it; -its value is a function which takes two arguments---the widget which -the button appears in, and the event. - -There is no way to specify two different buttons with different -actions. - -@item %@{@var{sample}%@} -Show @var{sample} in a special face specified by @code{:sample-face}. - -@item %v -Substitute the item's value. How the value is represented depends on -the kind of item, and (for variables) on the customization type. - -@item %d -Substitute the item's documentation string. - -@item %h -Like @samp{%d}, but if the documentation string is more than one line, -add a button to control whether to show all of it or just the first line. - -@item %t -Substitute the tag here. You specify the tag with the @code{:tag} -keyword. - -@item %% -Display a literal @samp{%}. -@end table - -@item :action @var{action} -@kindex action@r{, customization keyword} -Perform @var{action} if the user clicks on a button. - -@item :button-face @var{face} -@kindex button-face@r{, customization keyword} -Use the face @var{face} (a face name or a list of face names) for button -text displayed with @samp{%[@dots{}%]}. - -@item :button-prefix @var{prefix} -@itemx :button-suffix @var{suffix} -@kindex button-prefix@r{, customization keyword} -@kindex button-suffix@r{, customization keyword} -These specify the text to display before and after a button. -Each can be: - -@table @asis -@item @code{nil} -No text is inserted. - -@item a string -The string is inserted literally. - -@item a symbol -The symbol's value is used. -@end table - -@item :tag @var{tag} -Use @var{tag} (a string) as the tag for the value (or part of the value) -that corresponds to this type. - -@item :doc @var{doc} -@kindex doc@r{, customization keyword} -Use @var{doc} as the documentation string for this value (or part of the -value) that corresponds to this type. In order for this to work, you -must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} -in that value. - -The usual reason to specify a documentation string for a type is to -provide more information about the meanings of alternatives inside a -@code{:choice} type or the parts of some other composite type. - -@item :help-echo @var{motion-doc} -@kindex help-echo@r{, customization keyword} -When you move to this item with @code{widget-forward} or -@code{widget-backward}, it will display the string @var{motion-doc} in -the echo area. In addition, @var{motion-doc} is used as the mouse -@code{help-echo} string and may actually be a function or form evaluated -to yield a help string. If it is a function, it is called with one -argument, the widget. - -@item :match @var{function} -@kindex match@r{, customization keyword} -Specify how to decide whether a value matches the type. The -corresponding value, @var{function}, should be a function that accepts -two arguments, a widget and a value; it should return non-@code{nil} if -the value is acceptable. - -@item :validate @var{function} -Specify a validation function for input. @var{function} takes a -widget as an argument, and should return @code{nil} if the widget's -current value is valid for the widget. Otherwise, it should return -the widget containing the invalid data, and set that widget's -@code{:error} property to a string explaining the error. - -@ignore -@item :indent @var{columns} -Indent this item by @var{columns} columns. The indentation is used for -@samp{%n}, and automatically for group names, for checklists and radio -buttons, and for editable lists. It affects the whole of the -item except for the first line. - -@item :offset @var{extra} -Indent the subitems of this item @var{extra} columns more than this -item itself. By default, subitems are indented the same as their -parent. - -@item :extra-offset @var{n} -Add @var{n} extra spaces to this item's indentation, compared to its -parent's indentation. - -@item :notify @var{function} -Call @var{function} each time the item or a subitem is changed. The -function gets two or three arguments. The first argument is the item -itself, the second argument is the item that was changed, and the -third argument is the event leading to the change, if any. - -@item :menu-tag @var{tag-string} -Use @var{tag-string} in the menu when the widget is used as an option -in a @code{menu-choice} widget. - -@item :menu-tag-get -A function used for finding the tag when the widget is used as an option -in a @code{menu-choice} widget. By default, the tag used will be either the -@code{:menu-tag} or @code{:tag} property if present, or the @code{princ} -representation of the @code{:value} property if not. - -@item :tab-order -Specify the order in which widgets are traversed with -@code{widget-forward} or @code{widget-backward}. This is only partially -implemented. - -@enumerate a -@item -Widgets with tabbing order @code{-1} are ignored. - -@item -(Unimplemented) When on a widget with tabbing order @var{n}, go to the -next widget in the buffer with tabbing order @var{n+1} or @code{nil}, -whichever comes first. - -@item -When on a widget with no tabbing order specified, go to the next widget -in the buffer with a positive tabbing order, or @code{nil} -@end enumerate - -@item :parent -The parent of a nested widget (e.g., a @code{menu-choice} item or an -element of a @code{editable-list} widget). - -@item :sibling-args -This keyword is only used for members of a @code{radio-button-choice} or -@code{checklist}. The value should be a list of extra keyword -arguments, which will be used when creating the @code{radio-button} or -@code{checkbox} associated with this item. -@end ignore -@end table - -@node Defining New Types -@subsection Defining New Types - -In the previous sections we have described how to construct elaborate -type specifications for @code{defcustom}. In some cases you may want -to give such a type specification a name. The obvious case is when -you are using the same type for many user options: rather than repeat -the specification for each option, you can give the type specification -a name, and use that name each @code{defcustom}. The other case is -when a user option's value is a recursive data structure. To make it -possible for a datatype to refer to itself, it needs to have a name. - -Since custom types are implemented as widgets, the way to define a new -customize type is to define a new widget. We are not going to describe -the widget interface here in details, see @ref{Top, , Introduction, -widget, The Emacs Widget Library}, for that. Instead we are going to -demonstrate the minimal functionality needed for defining new customize -types by a simple example. - -@example -(define-widget 'binary-tree-of-string 'lazy - "A binary tree made of cons-cells and strings." - :offset 4 - :tag "Node" - :type '(choice (string :tag "Leaf" :value "") - (cons :tag "Interior" - :value ("" . "") - binary-tree-of-string - binary-tree-of-string))) - -(defcustom foo-bar "" - "Sample variable holding a binary tree of strings." - :type 'binary-tree-of-string) -@end example - -The function to define a new widget is called @code{define-widget}. The -first argument is the symbol we want to make a new widget type. The -second argument is a symbol representing an existing widget, the new -widget is going to be defined in terms of difference from the existing -widget. For the purpose of defining new customization types, the -@code{lazy} widget is perfect, because it accepts a @code{:type} keyword -argument with the same syntax as the keyword argument to -@code{defcustom} with the same name. The third argument is a -documentation string for the new widget. You will be able to see that -string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string -@key{RET}} command. - -After these mandatory arguments follow the keyword arguments. The most -important is @code{:type}, which describes the data type we want to match -with this widget. Here a @code{binary-tree-of-string} is described as -being either a string, or a cons-cell whose car and cdr are themselves -both @code{binary-tree-of-string}. Note the reference to the widget -type we are currently in the process of defining. The @code{:tag} -attribute is a string to name the widget in the user interface, and the -@code{:offset} argument is there to ensure that child nodes are -indented four spaces relative to the parent node, making the tree -structure apparent in the customization buffer. - -The @code{defcustom} shows how the new widget can be used as an ordinary -customization type. - -The reason for the name @code{lazy} is that the other composite -widgets convert their inferior widgets to internal form when the -widget is instantiated in a buffer. This conversion is recursive, so -the inferior widgets will convert @emph{their} inferior widgets. If -the data structure is itself recursive, this conversion is an infinite -recursion. The @code{lazy} widget prevents the recursion: it convert -its @code{:type} argument only when needed. - -@node Applying Customizations -@section Applying Customizations - -The following functions are responsible for installing the user's -customization settings for variables and faces, respectively. When -the user invokes @samp{Save for future sessions} in the Customize -interface, that takes effect by writing a @code{custom-set-variables} -and/or a @code{custom-set-faces} form into the custom file, to be -evaluated the next time Emacs starts. - -@defun custom-set-variables &rest args -This function installs the variable customizations specified by -@var{args}. Each argument in @var{args} should have the form - -@example -(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]]) -@end example - -@noindent -@var{var} is a variable name (a symbol), and @var{expression} is an -expression which evaluates to the desired customized value. - -If the @code{defcustom} form for @var{var} has been evaluated prior to -this @code{custom-set-variables} call, @var{expression} is immediately -evaluated, and the variable's value is set to the result. Otherwise, -@var{expression} is stored into the variable's @code{saved-value} -property, to be evaluated when the relevant @code{defcustom} is called -(usually when the library defining that variable is loaded into -Emacs). - -The @var{now}, @var{request}, and @var{comment} entries are for -internal use only, and may be omitted. @var{now}, if non-@code{nil}, -means to set the variable's value now, even if the variable's -@code{defcustom} form has not been evaluated. @var{request} is a list -of features to be loaded immediately (@pxref{Named Features}). -@var{comment} is a string describing the customization. -@end defun - -@defun custom-set-faces &rest args -This function installs the face customizations specified by -@var{args}. Each argument in @var{args} should have the form - -@example -(@var{face} @var{spec} [@var{now} [@var{comment}]]) -@end example - -@noindent -@var{face} is a face name (a symbol), and @var{spec} is the customized -face specification for that face (@pxref{Defining Faces}). - -The @var{now} and @var{comment} entries are for internal use only, and -may be omitted. @var{now}, if non-@code{nil}, means to install the -face specification now, even if the @code{defface} form has not been -evaluated. @var{comment} is a string describing the customization. -@end defun - -@node Custom Themes -@section Custom Themes - - @dfn{Custom themes} are collections of settings that can be enabled -or disabled as a unit. @xref{Custom Themes,,, emacs, The GNU Emacs -Manual}. Each Custom theme is defined by an Emacs Lisp source file, -which should follow the conventions described in this section. -(Instead of writing a Custom theme by hand, you can also create one -using a Customize-like interface; @pxref{Creating Custom Themes,,, -emacs, The GNU Emacs Manual}.) - - A Custom theme file should be named @file{@var{foo}-theme.el}, where -@var{foo} is the theme name. The first Lisp form in the file should -be a call to @code{deftheme}, and the last form should be a call to -@code{provide-theme}. - -@defmac deftheme theme &optional doc -This macro declares @var{theme} (a symbol) as the name of a Custom -theme. The optional argument @var{doc} should be a string describing -the theme; this is the description shown when the user invokes the -@code{describe-theme} command or types @kbd{?} in the @samp{*Custom -Themes*} buffer. - -Two special theme names are disallowed (using them causes an error): -@code{user} is a ``dummy'' theme that stores the user's direct -customization settings, and @code{changed} is a ``dummy'' theme that -stores changes made outside of the Customize system. -@end defmac - -@defmac provide-theme theme -This macro declares that the theme named @var{theme} has been fully -specified. -@end defmac - - In between @code{deftheme} and @code{provide-theme} are Lisp forms -specifying the theme settings: usually a call to -@code{custom-theme-set-variables} and/or a call to -@code{custom-theme-set-faces}. - -@defun custom-theme-set-variables theme &rest args -This function specifies the Custom theme @var{theme}'s variable -settings. @var{theme} should be a symbol. Each argument in -@var{args} should be a list of the form - -@example -(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]]) -@end example - -@noindent -where the list entries have the same meanings as in -@code{custom-set-variables}. @xref{Applying Customizations}. -@end defun - -@defun custom-theme-set-faces theme &rest args -This function specifies the Custom theme @var{theme}'s face settings. -@var{theme} should be a symbol. Each argument in @var{args} should be -a list of the form - -@example -(@var{face} @var{spec} [@var{now} [@var{comment}]]) -@end example - -@noindent -where the list entries have the same meanings as in -@code{custom-set-faces}. @xref{Applying Customizations}. -@end defun - - In theory, a theme file can also contain other Lisp forms, which -would be evaluated when loading the theme, but that is ``bad form''. -To protect against loading themes containing malicious code, Emacs -displays the source file and asks for confirmation from the user -before loading any non-built-in theme for the first time. - - The following functions are useful for programmatically enabling and -disabling themes: - -@defun custom-theme-p theme -This function return a non-@code{nil} value if @var{theme} (a symbol) -is the name of a Custom theme (i.e., a Custom theme which has been -loaded into Emacs, whether or not the theme is enabled). Otherwise, -it returns @code{nil}. -@end defun - -@defvar custom-known-themes -The value of this variable is a list of themes loaded into Emacs. -Each theme is represented by a Lisp symbol (the theme name). The -default value of this variable is a list containing two ``dummy'' -themes: @code{(user changed)}. The @code{changed} theme stores -settings made before any Custom themes are applied (e.g., variables -set outside of Customize). The @code{user} theme stores settings the -user has customized and saved. Any additional themes declared with -the @code{deftheme} macro are added to the front of this list. -@end defvar - -@deffn Command load-theme theme &optional no-confirm no-enable -This function loads the Custom theme named @var{theme} from its source -file, looking for the source file in the directories specified by the -variable @code{custom-theme-load-path}. @xref{Custom Themes,,, emacs, -The GNU Emacs Manual}. It also @dfn{enables} the theme (unless the -optional argument @var{no-enable} is non-@code{nil}), causing its -variable and face settings to take effect. It prompts the user for -confirmation before loading the theme, unless the optional argument -@var{no-confirm} is non-@code{nil}. -@end deffn - -@deffn Command enable-theme theme -This function enables the Custom theme named @var{theme}. It signals -an error if no such theme has been loaded. -@end deffn - -@deffn Command disable-theme theme -This function disables the Custom theme named @var{theme}. The theme -remains loaded, so that a subsequent call to @code{enable-theme} will -re-enable it. -@end deffn diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi deleted file mode 100644 index 66f12a022cb..00000000000 --- a/doc/lispref/debugging.texi +++ /dev/null @@ -1,866 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Debugging -@chapter Debugging Lisp Programs - - There are several ways to find and investigate problems in an Emacs -Lisp program. - -@itemize @bullet -@item -If a problem occurs when you run the program, you can use the built-in -Emacs Lisp debugger to suspend the Lisp evaluator, and examine and/or -alter its internal state. - -@item -You can use Edebug, a source-level debugger for Emacs Lisp. - -@item -If a syntactic problem is preventing Lisp from even reading the -program, you can locate it using Lisp editing commands. - -@item -You can look at the error and warning messages produced by the byte -compiler when it compiles the program. @xref{Compiler Errors}. - -@item -You can use the Testcover package to perform coverage testing on the -program. - -@item -You can use the ERT package to write regression tests for the program. -@xref{Top,the ERT manual,, ert, ERT: Emacs Lisp Regression Testing}. - -@item -You can profile the program to get hints about how to make it more efficient. -@end itemize - - Other useful tools for debugging input and output problems are the -dribble file (@pxref{Terminal Input}) and the @code{open-termscript} -function (@pxref{Terminal Output}). - -@menu -* Debugger:: A debugger for the Emacs Lisp evaluator. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. -* Profiling:: Measuring the resources that your code uses. -@end menu - -@node Debugger -@section The Lisp Debugger -@cindex debugger for Emacs Lisp -@cindex Lisp debugger -@cindex break - - The ordinary @dfn{Lisp debugger} provides the ability to suspend -evaluation of a form. While evaluation is suspended (a state that is -commonly known as a @dfn{break}), you may examine the run time stack, -examine the values of local or global variables, or change those values. -Since a break is a recursive edit, all the usual editing facilities of -Emacs are available; you can even run programs that will enter the -debugger recursively. @xref{Recursive Editing}. - -@menu -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. -@end menu - -@node Error Debugging -@subsection Entering the Debugger on an Error -@cindex error debugging -@cindex debugging errors - - The most important time to enter the debugger is when a Lisp error -happens. This allows you to investigate the immediate causes of the -error. - - However, entry to the debugger is not a normal consequence of an -error. Many commands signal Lisp errors when invoked inappropriately, -and during ordinary editing it would be very inconvenient to enter the -debugger each time this happens. So if you want errors to enter the -debugger, set the variable @code{debug-on-error} to non-@code{nil}. -(The command @code{toggle-debug-on-error} provides an easy way to do -this.) - -@defopt debug-on-error -This variable determines whether the debugger is called when an error -is signaled and not handled. If @code{debug-on-error} is @code{t}, -all kinds of errors call the debugger, except those listed in -@code{debug-ignored-errors} (see below). If it is @code{nil}, none -call the debugger. - -The value can also be a list of error conditions (@pxref{Signaling -Errors}). Then the debugger is called only for error conditions in -this list (except those also listed in @code{debug-ignored-errors}). -For example, if you set @code{debug-on-error} to the list -@code{(void-variable)}, the debugger is only called for errors about a -variable that has no value. - -Note that @code{eval-expression-debug-on-error} overrides this -variable in some cases; see below. - -When this variable is non-@code{nil}, Emacs does not create an error -handler around process filter functions and sentinels. Therefore, -errors in these functions also invoke the debugger. @xref{Processes}. -@end defopt - -@defopt debug-ignored-errors -This variable specifies errors which should not enter the debugger, -regardless of the value of @code{debug-on-error}. Its value is a list -of error condition symbols and/or regular expressions. If the error -has any of those condition symbols, or if the error message matches -any of the regular expressions, then that error does not enter the -debugger. - -The normal value of this variable includes @code{user-error}, as well -as several errors that happen often during editing but rarely result -from bugs in Lisp programs. However, ``rarely'' is not ``never''; if -your program fails with an error that matches this list, you may try -changing this list to debug the error. The easiest way is usually to -set @code{debug-ignored-errors} to @code{nil}. -@end defopt - -@defopt eval-expression-debug-on-error -If this variable has a non-@code{nil} value (the default), running the -command @code{eval-expression} causes @code{debug-on-error} to be -temporarily bound to to @code{t}. @xref{Lisp Eval,, Evaluating -Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}. - -If @code{eval-expression-debug-on-error} is @code{nil}, then the value -of @code{debug-on-error} is not changed during @code{eval-expression}. -@end defopt - -@defvar debug-on-signal -Normally, errors caught by @code{condition-case} never invoke the -debugger. The @code{condition-case} gets a chance to handle the error -before the debugger gets a chance. - -If you change @code{debug-on-signal} to a non-@code{nil} value, the -debugger gets the first chance at every error, regardless of the -presence of @code{condition-case}. (To invoke the debugger, the error -must still fulfill the criteria specified by @code{debug-on-error} and -@code{debug-ignored-errors}.) - -@strong{Warning:} Setting this variable to non-@code{nil} may have -annoying effects. Various parts of Emacs catch errors in the normal -course of affairs, and you may not even realize that errors happen -there. If you need to debug code wrapped in @code{condition-case}, -consider using @code{condition-case-unless-debug} (@pxref{Handling -Errors}). -@end defvar - -@defopt debug-on-event -If you set @code{debug-on-event} to a special event (@pxref{Special -Events}), Emacs will try to enter the debugger as soon as it receives -this event, bypassing @code{special-event-map}. At present, the only -supported values correspond to the signals @code{SIGUSR1} and -@code{SIGUSR2} (this is the default). This can be helpful when -@code{inhibit-quit} is set and Emacs is not otherwise responding. -@end defopt - -@cindex message, finding what causes a particular message -@defvar debug-on-message -If you set @code{debug-on-message} to a regular expression, -Emacs will enter the debugger if it displays a matching message in the -echo area. For example, this can be useful when trying to find the -cause of a particular message. -@end defvar - - To debug an error that happens during loading of the init -file, use the option @samp{--debug-init}. This binds -@code{debug-on-error} to @code{t} while loading the init file, and -bypasses the @code{condition-case} which normally catches errors in the -init file. - -@node Infinite Loops -@subsection Debugging Infinite Loops -@cindex infinite loops -@cindex loops, infinite -@cindex quitting from infinite loop -@cindex stopping an infinite loop - - When a program loops infinitely and fails to return, your first -problem is to stop the loop. On most operating systems, you can do -this with @kbd{C-g}, which causes a @dfn{quit}. @xref{Quitting}. - - Ordinary quitting gives no information about why the program was -looping. To get more information, you can set the variable -@code{debug-on-quit} to non-@code{nil}. Once you have the debugger -running in the middle of the infinite loop, you can proceed from the -debugger using the stepping commands. If you step through the entire -loop, you may get enough information to solve the problem. - - Quitting with @kbd{C-g} is not considered an error, and -@code{debug-on-error} has no effect on the handling of @kbd{C-g}. -Likewise, @code{debug-on-quit} has no effect on errors. - -@defopt debug-on-quit -This variable determines whether the debugger is called when -@code{quit} is signaled and not handled. If @code{debug-on-quit} is -non-@code{nil}, then the debugger is called whenever you quit (that -is, type @kbd{C-g}). If @code{debug-on-quit} is @code{nil} (the -default), then the debugger is not called when you quit. -@end defopt - -@node Function Debugging -@subsection Entering the Debugger on a Function Call -@cindex function call debugging -@cindex debugging specific functions - - To investigate a problem that happens in the middle of a program, one -useful technique is to enter the debugger whenever a certain function is -called. You can do this to the function in which the problem occurs, -and then step through the function, or you can do this to a function -called shortly before the problem, step quickly over the call to that -function, and then step through its caller. - -@deffn Command debug-on-entry function-name -This function requests @var{function-name} to invoke the debugger each -time it is called. - -Any function or macro defined as Lisp code may be set to break on -entry, regardless of whether it is interpreted code or compiled code. -If the function is a command, it will enter the debugger when called -from Lisp and when called interactively (after the reading of the -arguments). You can also set debug-on-entry for primitive functions -(i.e., those written in C) this way, but it only takes effect when the -primitive is called from Lisp code. Debug-on-entry is not allowed for -special forms. - -When @code{debug-on-entry} is called interactively, it prompts for -@var{function-name} in the minibuffer. If the function is already set -up to invoke the debugger on entry, @code{debug-on-entry} does nothing. -@code{debug-on-entry} always returns @var{function-name}. - -Here's an example to illustrate use of this function: - -@example -@group -(defun fact (n) - (if (zerop n) 1 - (* n (fact (1- n))))) - @result{} fact -@end group -@group -(debug-on-entry 'fact) - @result{} fact -@end group -@group -(fact 3) -@end group - -@group ------- Buffer: *Backtrace* ------ -Debugger entered--entering a function: -* fact(3) - eval((fact 3)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ------- Buffer: *Backtrace* ------ -@end group - -@end example -@end deffn - -@deffn Command cancel-debug-on-entry &optional function-name -This function undoes the effect of @code{debug-on-entry} on -@var{function-name}. When called interactively, it prompts for -@var{function-name} in the minibuffer. If @var{function-name} is -omitted or @code{nil}, it cancels break-on-entry for all functions. -Calling @code{cancel-debug-on-entry} does nothing to a function which is -not currently set up to break on entry. -@end deffn - -@node Explicit Debug -@subsection Explicit Entry to the Debugger - - You can cause the debugger to be called at a certain point in your -program by writing the expression @code{(debug)} at that point. To do -this, visit the source file, insert the text @samp{(debug)} at the -proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key -binding). @strong{Warning:} if you do this for temporary debugging -purposes, be sure to undo this insertion before you save the file! - - The place where you insert @samp{(debug)} must be a place where an -additional form can be evaluated and its value ignored. (If the value -of @code{(debug)} isn't ignored, it will alter the execution of the -program!) The most common suitable places are inside a @code{progn} or -an implicit @code{progn} (@pxref{Sequencing}). - - If you don't know exactly where in the source code you want to put -the debug statement, but you want to display a backtrace when a -certain message is displayed, you can set @code{debug-on-message} to a -regular expression matching the desired message. - -@node Using Debugger -@subsection Using the Debugger - - When the debugger is entered, it displays the previously selected -buffer in one window and a buffer named @file{*Backtrace*} in another -window. The backtrace buffer contains one line for each level of Lisp -function execution currently going on. At the beginning of this buffer -is a message describing the reason that the debugger was invoked (such -as the error message and associated data, if it was invoked due to an -error). - -@vindex debugger-bury-or-kill - The backtrace buffer is read-only and uses a special major mode, -Debugger mode, in which letters are defined as debugger commands. The -usual Emacs editing commands are available; thus, you can switch windows -to examine the buffer that was being edited at the time of the error, -switch buffers, visit files, or do any other sort of editing. However, -the debugger is a recursive editing level (@pxref{Recursive Editing}) -and it is wise to go back to the backtrace buffer and exit the debugger -(with the @kbd{q} command) when you are finished with it. Exiting -the debugger gets out of the recursive edit and buries the backtrace -buffer. (You can customize what the @kbd{q} command does with the -backtrace buffer by setting the variable @code{debugger-bury-or-kill}. -For example, set it to @code{kill} if you prefer to kill the buffer -rather than bury it. Consult the variable's documentation for more -possibilities.) - - When the debugger has been entered, the @code{debug-on-error} -variable is temporarily set according to -@code{eval-expression-debug-on-error}. If the latter variable is -non-@code{nil}, @code{debug-on-error} will temporarily be set to -@code{t}. This means that any further errors that occur while doing a -debugging session will (by default) trigger another backtrace. If -this is not what you want, you can either set -@code{eval-expression-debug-on-error} to @code{nil}, or set -@code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}. - -@cindex current stack frame - The backtrace buffer shows you the functions that are executing and -their argument values. It also allows you to specify a stack frame by -moving point to the line describing that frame. (A stack frame is the -place where the Lisp interpreter records information about a particular -invocation of a function.) The frame whose line point is on is -considered the @dfn{current frame}. Some of the debugger commands -operate on the current frame. If a line starts with a star, that means -that exiting that frame will call the debugger again. This is useful -for examining the return value of a function. - - If a function name is underlined, that means the debugger knows -where its source code is located. You can click with the mouse on -that name, or move to it and type @key{RET}, to visit the source code. - - The debugger itself must be run byte-compiled, since it makes -assumptions about how many stack frames are used for the debugger -itself. These assumptions are false if the debugger is running -interpreted. - -@node Debugger Commands -@subsection Debugger Commands -@cindex debugger command list - - The debugger buffer (in Debugger mode) provides special commands in -addition to the usual Emacs commands. The most important use of -debugger commands is for stepping through code, so that you can see -how control flows. The debugger can step through the control -structures of an interpreted function, but cannot do so in a -byte-compiled function. If you would like to step through a -byte-compiled function, replace it with an interpreted definition of -the same function. (To do this, visit the source for the function and -type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger -to step through a primitive function. - -@c FIXME: Add @findex for the following commands? --xfq - Here is a list of Debugger mode commands: - -@table @kbd -@item c -Exit the debugger and continue execution. This resumes execution of -the program as if the debugger had never been entered (aside from any -side-effects that you caused by changing variable values or data -structures while inside the debugger). - -@item d -Continue execution, but enter the debugger the next time any Lisp -function is called. This allows you to step through the -subexpressions of an expression, seeing what values the subexpressions -compute, and what else they do. - -The stack frame made for the function call which enters the debugger in -this way will be flagged automatically so that the debugger will be -called again when the frame is exited. You can use the @kbd{u} command -to cancel this flag. - -@item b -Flag the current frame so that the debugger will be entered when the -frame is exited. Frames flagged in this way are marked with stars -in the backtrace buffer. - -@item u -Don't enter the debugger when the current frame is exited. This -cancels a @kbd{b} command on that frame. The visible effect is to -remove the star from the line in the backtrace buffer. - -@item j -Flag the current frame like @kbd{b}. Then continue execution like -@kbd{c}, but temporarily disable break-on-entry for all functions that -are set up to do so by @code{debug-on-entry}. - -@item e -Read a Lisp expression in the minibuffer, evaluate it (with the -relevant lexical environment, if applicable), and print the -value in the echo area. The debugger alters certain important -variables, and the current buffer, as part of its operation; @kbd{e} -temporarily restores their values from outside the debugger, so you can -examine and change them. This makes the debugger more transparent. By -contrast, @kbd{M-:} does nothing special in the debugger; it shows you -the variable values within the debugger. - -@item R -Like @kbd{e}, but also save the result of evaluation in the -buffer @file{*Debugger-record*}. - -@item q -Terminate the program being debugged; return to top-level Emacs -command execution. - -If the debugger was entered due to a @kbd{C-g} but you really want -to quit, and not debug, use the @kbd{q} command. - -@item r -Return a value from the debugger. The value is computed by reading an -expression with the minibuffer and evaluating it. - -The @kbd{r} command is useful when the debugger was invoked due to exit -from a Lisp call frame (as requested with @kbd{b} or by entering the -frame with @kbd{d}); then the value specified in the @kbd{r} command is -used as the value of that frame. It is also useful if you call -@code{debug} and use its return value. Otherwise, @kbd{r} has the same -effect as @kbd{c}, and the specified return value does not matter. - -You can't use @kbd{r} when the debugger was entered due to an error. - -@item l -Display a list of functions that will invoke the debugger when called. -This is a list of functions that are set to break on entry by means of -@code{debug-on-entry}. - -@item v -Toggle the display of local variables of the current stack frame. -@end table - -@node Invoking the Debugger -@subsection Invoking the Debugger - - Here we describe in full detail the function @code{debug} that is used -to invoke the debugger. - -@deffn Command debug &rest debugger-args -This function enters the debugger. It switches buffers to a buffer -named @file{*Backtrace*} (or @file{*Backtrace*<2>} if it is the second -recursive entry to the debugger, etc.), and fills it with information -about the stack of Lisp function calls. It then enters a recursive -edit, showing the backtrace buffer in Debugger mode. - -The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit -the recursive edit; then @code{debug} switches back to the previous -buffer and returns to whatever called @code{debug}. This is the only -way the function @code{debug} can return to its caller. - -The use of the @var{debugger-args} is that @code{debug} displays the -rest of its arguments at the top of the @file{*Backtrace*} buffer, so -that the user can see them. Except as described below, this is the -@emph{only} way these arguments are used. - -However, certain values for first argument to @code{debug} have a -special significance. (Normally, these values are used only by the -internals of Emacs, and not by programmers calling @code{debug}.) Here -is a table of these special values: - -@table @code -@item lambda -@cindex @code{lambda} in debug -A first argument of @code{lambda} means @code{debug} was called -because of entry to a function when @code{debug-on-next-call} was -non-@code{nil}. The debugger displays @samp{Debugger -entered--entering a function:} as a line of text at the top of the -buffer. - -@item debug -@code{debug} as first argument means @code{debug} was called because -of entry to a function that was set to debug on entry. The debugger -displays the string @samp{Debugger entered--entering a function:}, -just as in the @code{lambda} case. It also marks the stack frame for -that function so that it will invoke the debugger when exited. - -@item t -When the first argument is @code{t}, this indicates a call to -@code{debug} due to evaluation of a function call form when -@code{debug-on-next-call} is non-@code{nil}. The debugger displays -@samp{Debugger entered--beginning evaluation of function call form:} -as the top line in the buffer. - -@item exit -When the first argument is @code{exit}, it indicates the exit of a -stack frame previously marked to invoke the debugger on exit. The -second argument given to @code{debug} in this case is the value being -returned from the frame. The debugger displays @samp{Debugger -entered--returning value:} in the top line of the buffer, followed by -the value being returned. - -@item error -@cindex @code{error} in debug -When the first argument is @code{error}, the debugger indicates that -it is being entered because an error or @code{quit} was signaled and -not handled, by displaying @samp{Debugger entered--Lisp error:} -followed by the error signaled and any arguments to @code{signal}. -For example, - -@example -@group -(let ((debug-on-error t)) - (/ 1 0)) -@end group - -@group ------- Buffer: *Backtrace* ------ -Debugger entered--Lisp error: (arith-error) - /(1 0) -... ------- Buffer: *Backtrace* ------ -@end group -@end example - -If an error was signaled, presumably the variable -@code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled, -then presumably the variable @code{debug-on-quit} is non-@code{nil}. - -@item nil -Use @code{nil} as the first of the @var{debugger-args} when you want -to enter the debugger explicitly. The rest of the @var{debugger-args} -are printed on the top line of the buffer. You can use this feature to -display messages---for example, to remind yourself of the conditions -under which @code{debug} is called. -@end table -@end deffn - -@node Internals of Debugger -@subsection Internals of the Debugger - - This section describes functions and variables used internally by the -debugger. - -@defvar debugger -The value of this variable is the function to call to invoke the -debugger. Its value must be a function of any number of arguments, or, -more typically, the name of a function. This function should invoke -some kind of debugger. The default value of the variable is -@code{debug}. - -The first argument that Lisp hands to the function indicates why it -was called. The convention for arguments is detailed in the description -of @code{debug} (@pxref{Invoking the Debugger}). -@end defvar - -@deffn Command backtrace -@cindex run time stack -@cindex call stack -This function prints a trace of Lisp function calls currently active. -This is the function used by @code{debug} to fill up the -@file{*Backtrace*} buffer. It is written in C, since it must have access -to the stack to determine which function calls are active. The return -value is always @code{nil}. - -In the following example, a Lisp expression calls @code{backtrace} -explicitly. This prints the backtrace to the stream -@code{standard-output}, which, in this case, is the buffer -@samp{backtrace-output}. - -Each line of the backtrace represents one function call. The line shows -the values of the function's arguments if they are all known; if they -are still being computed, the line says so. The arguments of special -forms are elided. - -@smallexample -@group -(with-output-to-temp-buffer "backtrace-output" - (let ((var 1)) - (save-excursion - (setq var (eval '(progn - (1+ var) - (list 'testing (backtrace)))))))) - - @result{} (testing nil) -@end group - -@group ------------ Buffer: backtrace-output ------------ - backtrace() - (list ...computing arguments...) -@end group - (progn ...) - eval((progn (1+ var) (list (quote testing) (backtrace)))) - (setq ...) - (save-excursion ...) - (let ...) - (with-output-to-temp-buffer ...) - eval((with-output-to-temp-buffer ...)) - eval-last-sexp-1(nil) -@group - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ------------ Buffer: backtrace-output ------------ -@end group -@end smallexample -@end deffn - -@defvar debug-on-next-call -@cindex @code{eval}, and debugging -@cindex @code{apply}, and debugging -@cindex @code{funcall}, and debugging -If this variable is non-@code{nil}, it says to call the debugger before -the next @code{eval}, @code{apply} or @code{funcall}. Entering the -debugger sets @code{debug-on-next-call} to @code{nil}. - -The @kbd{d} command in the debugger works by setting this variable. -@end defvar - -@defun backtrace-debug level flag -This function sets the debug-on-exit flag of the stack frame @var{level} -levels down the stack, giving it the value @var{flag}. If @var{flag} is -non-@code{nil}, this will cause the debugger to be entered when that -frame later exits. Even a nonlocal exit through that frame will enter -the debugger. - -This function is used only by the debugger. -@end defun - -@defvar command-debug-status -This variable records the debugging status of the current interactive -command. Each time a command is called interactively, this variable is -bound to @code{nil}. The debugger can set this variable to leave -information for future debugger invocations during the same command -invocation. - -The advantage of using this variable rather than an ordinary global -variable is that the data will never carry over to a subsequent command -invocation. -@end defvar - -@defun backtrace-frame frame-number -The function @code{backtrace-frame} is intended for use in Lisp -debuggers. It returns information about what computation is happening -in the stack frame @var{frame-number} levels down. - -If that frame has not evaluated the arguments yet, or is a special -form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. - -If that frame has evaluated its arguments and called its function -already, the return value is @code{(t @var{function} -@var{arg-values}@dots{})}. - -In the return value, @var{function} is whatever was supplied as the -@sc{car} of the evaluated list, or a @code{lambda} expression in the -case of a macro call. If the function has a @code{&rest} argument, that -is represented as the tail of the list @var{arg-values}. - -If @var{frame-number} is out of range, @code{backtrace-frame} returns -@code{nil}. -@end defun - -@include edebug.texi - -@node Syntax Errors -@section Debugging Invalid Lisp Syntax -@cindex debugging invalid Lisp syntax - - The Lisp reader reports invalid syntax, but cannot say where the real -problem is. For example, the error ``End of file during parsing'' in -evaluating an expression indicates an excess of open parentheses (or -square brackets). The reader detects this imbalance at the end of the -file, but it cannot figure out where the close parenthesis should have -been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close -parenthesis or missing open parenthesis, but does not say where the -missing parenthesis belongs. How, then, to find what to change? - - If the problem is not simply an imbalance of parentheses, a useful -technique is to try @kbd{C-M-e} at the beginning of each defun, and see -if it goes to the place where that defun appears to end. If it does -not, there is a problem in that defun. - -@cindex unbalanced parentheses -@cindex parenthesis mismatch, debugging - However, unmatched parentheses are the most common syntax errors in -Lisp, and we can give further advice for those cases. (In addition, -just moving point through the code with Show Paren mode enabled might -find the mismatch.) - -@menu -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. -@end menu - -@node Excess Open -@subsection Excess Open Parentheses - - The first step is to find the defun that is unbalanced. If there is -an excess open parenthesis, the way to do this is to go to the end of -the file and type @kbd{C-u C-M-u}. This will move you to the -beginning of the first defun that is unbalanced. - - The next step is to determine precisely what is wrong. There is no -way to be sure of this except by studying the program, but often the -existing indentation is a clue to where the parentheses should have -been. The easiest way to use this clue is to reindent with @kbd{C-M-q} -and see what moves. @strong{But don't do this yet!} Keep reading, -first. - - Before you do this, make sure the defun has enough close parentheses. -Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest -of the file until the end. So move to the end of the defun and insert a -close parenthesis there. Don't use @kbd{C-M-e} to move there, since -that too will fail to work until the defun is balanced. - - Now you can go to the beginning of the defun and type @kbd{C-M-q}. -Usually all the lines from a certain point to the end of the function -will shift to the right. There is probably a missing close parenthesis, -or a superfluous open parenthesis, near that point. (However, don't -assume this is true; study the code to make sure.) Once you have found -the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old -indentation is probably appropriate to the intended parentheses. - - After you think you have fixed the problem, use @kbd{C-M-q} again. If -the old indentation actually fit the intended nesting of parentheses, -and you have put back those parentheses, @kbd{C-M-q} should not change -anything. - -@node Excess Close -@subsection Excess Close Parentheses - - To deal with an excess close parenthesis, first go to the beginning -of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first -unbalanced defun. - - Then find the actual matching close parenthesis by typing @kbd{C-M-f} -at the beginning of that defun. This will leave you somewhere short of -the place where the defun ought to end. It is possible that you will -find a spurious close parenthesis in that vicinity. - - If you don't see a problem at that point, the next thing to do is to -type @kbd{C-M-q} at the beginning of the defun. A range of lines will -probably shift left; if so, the missing open parenthesis or spurious -close parenthesis is probably near the first of those lines. (However, -don't assume this is true; study the code to make sure.) Once you have -found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the -old indentation is probably appropriate to the intended parentheses. - - After you think you have fixed the problem, use @kbd{C-M-q} again. If -the old indentation actually fits the intended nesting of parentheses, -and you have put back those parentheses, @kbd{C-M-q} should not change -anything. - -@node Test Coverage -@section Test Coverage -@cindex coverage testing - -@findex testcover-start -@findex testcover-mark-all -@findex testcover-next-mark - You can do coverage testing for a file of Lisp code by loading the -@code{testcover} library and using the command @kbd{M-x -testcover-start @key{RET} @var{file} @key{RET}} to instrument the -code. Then test your code by calling it one or more times. Then use -the command @kbd{M-x testcover-mark-all} to display colored highlights -on the code to show where coverage is insufficient. The command -@kbd{M-x testcover-next-mark} will move point forward to the next -highlighted spot. - - Normally, a red highlight indicates the form was never completely -evaluated; a brown highlight means it always evaluated to the same -value (meaning there has been little testing of what is done with the -result). However, the red highlight is skipped for forms that can't -possibly complete their evaluation, such as @code{error}. The brown -highlight is skipped for forms that are expected to always evaluate to -the same value, such as @code{(setq x 14)}. - - For difficult cases, you can add do-nothing macros to your code to -give advice to the test coverage tool. - -@defmac 1value form -Evaluate @var{form} and return its value, but inform coverage testing -that @var{form}'s value should always be the same. -@end defmac - -@defmac noreturn form -Evaluate @var{form}, informing coverage testing that @var{form} should -never return. If it ever does return, you get a run-time error. -@end defmac - - Edebug also has a coverage testing feature (@pxref{Coverage -Testing}). These features partly duplicate each other, and it would -be cleaner to combine them. - - -@node Profiling -@section Profiling -@cindex profiling -@cindex measuring resource usage -@cindex memory usage - -If your program is working correctly, but you want to make it run more -quickly or efficiently, the first thing to do is @dfn{profile} your -code so that you know how it is using resources. If you find that one -particular function is responsible for a significant portion of the -runtime, you can start looking for ways to optimize that piece. - -Emacs has built-in support for this. To begin profiling, type -@kbd{M-x profiler-start}. You can choose to profile by processor -usage, memory usage, or both. After doing some work, type -@kbd{M-x profiler-report} to display a summary buffer for each -resource that you chose to profile. The names of the report buffers -include the times at which the reports were generated, so you can -generate another report later on without erasing previous results. -When you have finished profiling, type @kbd{M-x profiler-stop} (there -is a small overhead associated with profiling). - -The profiler report buffer shows, on each line, a function that was -called, followed by how much resource (processor or memory) it used in -absolute and percentage times since profiling started. If a given -line has a @samp{+} symbol at the left-hand side, you can expand that -line by typing @key{RET}, in order to see the function(s) called by -the higher-level function. Pressing @key{RET} again will collapse -back to the original state. - -Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function. -Press @kbd{d} to view a function's documentation. -You can save a profile to a file using @kbd{C-x C-w}. -You can compare two profiles using @kbd{=}. - -@c FIXME reversed calltree? - -@cindex @file{elp.el} -@cindex timing programs -The @file{elp} library offers an alternative approach. See the file -@file{elp.el} for instructions. - -@cindex @file{benchmark.el} -@cindex benchmarking -You can check the speed of individual Emacs Lisp forms using the -@file{benchmark} library. See the functions @code{benchmark-run} and -@code{benchmark-run-compiled} in @file{benchmark.el}. - -@c Not worth putting in the printed manual. -@ifnottex -@cindex --enable-profiling option of configure -To profile Emacs at the level of its C code, you can build it using the -@option{--enable-profiling} option of @command{configure}. When Emacs -exits, it generates a file @file{gmon.out} that you can examine using -the @command{gprof} utility. This feature is mainly useful for -debugging Emacs. It actually stops the Lisp-level @kbd{M-x -profiler-@dots{}} commands described above from working. -@end ifnottex diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi deleted file mode 100644 index 46be5ecf3f0..00000000000 --- a/doc/lispref/display.texi +++ /dev/null @@ -1,6741 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Display -@chapter Emacs Display - - This chapter describes a number of features related to the display -that Emacs presents to the user. - -@menu -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Size of Displayed Text:: How large displayed text is. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style for text characters: - font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Window Dividers:: Separating windows visually. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs's Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Character Display:: How Emacs displays individual characters. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. -* Bidirectional Display:: Display of bidirectional scripts, such as - Arabic and Farsi. -@end menu - -@node Refresh Screen -@section Refreshing the Screen - - The function @code{redraw-frame} clears and redisplays the entire -contents of a given frame (@pxref{Frames}). This is useful if the -screen is corrupted. - -@defun redraw-frame frame -This function clears and redisplays frame @var{frame}. -@end defun - - Even more powerful is @code{redraw-display}: - -@deffn Command redraw-display -This function clears and redisplays all visible frames. -@end deffn - - In Emacs, processing user input takes priority over redisplay. If -you call these functions when input is available, they don't redisplay -immediately, but the requested redisplay does happen -eventually---after all the input has been processed. - - On text terminals, suspending and resuming Emacs normally also -refreshes the screen. Some terminal emulators record separate -contents for display-oriented programs such as Emacs and for ordinary -sequential display. If you are using such a terminal, you might want -to inhibit the redisplay on resumption. - -@defopt no-redraw-on-reenter -@cindex suspend (cf. @code{no-redraw-on-reenter}) -@cindex resume (cf. @code{no-redraw-on-reenter}) -This variable controls whether Emacs redraws the entire screen after it -has been suspended and resumed. Non-@code{nil} means there is no need -to redraw, @code{nil} means redrawing is needed. The default is @code{nil}. -@end defopt - -@node Forcing Redisplay -@section Forcing Redisplay -@cindex forcing redisplay - - Emacs normally tries to redisplay the screen whenever it waits for -input. With the following function, you can request an immediate -attempt to redisplay, in the middle of Lisp code, without actually -waiting for input. - -@defun redisplay &optional force -This function tries immediately to redisplay. The optional argument -@var{force}, if non-@code{nil}, forces the redisplay to be performed, -instead of being preempted, even if input is pending and the variable -@code{redisplay-dont-pause} is @code{nil} (see below). If -@code{redisplay-dont-pause} is non-@code{nil} (the default), this -function redisplays in any case, i.e., @var{force} does nothing. - -The function returns @code{t} if it actually tried to redisplay, and -@code{nil} otherwise. A value of @code{t} does not mean that -redisplay proceeded to completion; it could have been preempted by -newly arriving input. -@end defun - -@defvar redisplay-dont-pause -If this variable is @code{nil}, arriving input events preempt -redisplay; Emacs avoids starting a redisplay, and stops any redisplay -that is in progress, until the input has been processed. In -particular, @code{(redisplay)} returns @code{nil} without actually -redisplaying, if there is pending input. - -The default value is @code{t}, which means that pending input does not -preempt redisplay. -@end defvar - -@defvar redisplay-preemption-period -If @code{redisplay-dont-pause} is @code{nil}, this variable specifies -how many seconds Emacs waits between checks for new input during -redisplay; if input arrives during this interval, redisplay stops and -the input is processed. The default value is 0.1; if the value is -@code{nil}, Emacs does not check for input during redisplay. - -This variable has no effect when @code{redisplay-dont-pause} is -non-@code{nil} (the default). -@end defvar - -@defvar pre-redisplay-function -A function run just before redisplay. It is called with one argument, -the set of windows to redisplay. -@end defvar - - Although @code{redisplay} tries immediately to redisplay, it does -not change how Emacs decides which parts of its frame(s) to redisplay. -By contrast, the following function adds certain windows to the -pending redisplay work (as if their contents had completely changed), -but does not immediately try to perform redisplay. - -@defun force-window-update &optional object -This function forces some or all windows to be updated the next time -Emacs does a redisplay. If @var{object} is a window, that window is -to be updated. If @var{object} is a buffer or buffer name, all -windows displaying that buffer are to be updated. If @var{object} is -@code{nil} (or omitted), all windows are to be updated. - -This function does not do a redisplay immediately; Emacs does that as -it waits for input, or when the function @code{redisplay} is called. -@end defun - -@node Truncation -@section Truncation -@cindex line wrapping -@cindex line truncation -@cindex continuation lines -@cindex @samp{$} in display -@cindex @samp{\} in display - - When a line of text extends beyond the right edge of a window, Emacs -can @dfn{continue} the line (make it ``wrap'' to the next screen -line), or @dfn{truncate} the line (limit it to one screen line). The -additional screen lines used to display a long text line are called -@dfn{continuation} lines. Continuation is not the same as filling; -continuation happens on the screen only, not in the buffer contents, -and it breaks a line precisely at the right margin, not at a word -boundary. @xref{Filling}. - - On a graphical display, tiny arrow images in the window fringes -indicate truncated and continued lines (@pxref{Fringes}). On a text -terminal, a @samp{$} in the rightmost column of the window indicates -truncation; a @samp{\} on the rightmost column indicates a line that -``wraps''. (The display table can specify alternate characters to use -for this; @pxref{Display Tables}). - -@defopt truncate-lines -If this buffer-local variable is non-@code{nil}, lines that extend -beyond the right edge of the window are truncated; otherwise, they are -continued. As a special exception, the variable -@code{truncate-partial-width-windows} takes precedence in -@dfn{partial-width} windows (i.e., windows that do not occupy the -entire frame width). -@end defopt - -@defopt truncate-partial-width-windows -@cindex partial-width windows -This variable controls line truncation in @dfn{partial-width} windows. -A partial-width window is one that does not occupy the entire frame -width (@pxref{Splitting Windows}). If the value is @code{nil}, line -truncation is determined by the variable @code{truncate-lines} (see -above). If the value is an integer @var{n}, lines are truncated if -the partial-width window has fewer than @var{n} columns, regardless of -the value of @code{truncate-lines}; if the partial-width window has -@var{n} or more columns, line truncation is determined by -@code{truncate-lines}. For any other non-@code{nil} value, lines are -truncated in every partial-width window, regardless of the value of -@code{truncate-lines}. -@end defopt - - When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in -a window, that forces truncation. - -@defvar wrap-prefix -If this buffer-local variable is non-@code{nil}, it defines a -@dfn{wrap prefix} which Emacs displays at the start of every -continuation line. (If lines are truncated, @code{wrap-prefix} is -never used.) Its value may be a string or an image (@pxref{Other -Display Specs}), or a stretch of whitespace such as specified by the -@code{:width} or @code{:align-to} display properties (@pxref{Specified -Space}). The value is interpreted in the same way as a @code{display} -text property. @xref{Display Property}. - -A wrap prefix may also be specified for regions of text, using the -@code{wrap-prefix} text or overlay property. This takes precedence -over the @code{wrap-prefix} variable. @xref{Special Properties}. -@end defvar - -@defvar line-prefix -If this buffer-local variable is non-@code{nil}, it defines a -@dfn{line prefix} which Emacs displays at the start of every -non-continuation line. Its value may be a string or an image -(@pxref{Other Display Specs}), or a stretch of whitespace such as -specified by the @code{:width} or @code{:align-to} display properties -(@pxref{Specified Space}). The value is interpreted in the same way -as a @code{display} text property. @xref{Display Property}. - -A line prefix may also be specified for regions of text using the -@code{line-prefix} text or overlay property. This takes precedence -over the @code{line-prefix} variable. @xref{Special Properties}. -@end defvar - -@ignore - If your buffer contains only very short lines, you might find it -advisable to set @code{cache-long-scans} to @code{nil}. - -@defvar cache-long-scans -If this variable is non-@code{nil} (the default), various indentation -and motion functions, and Emacs redisplay, cache the results of -scanning the buffer, and consult the cache to avoid rescanning regions -of the buffer unless they are modified. - -Turning off the cache speeds up processing of short lines somewhat. - -This variable is automatically buffer-local in every buffer. -@end defvar -@end ignore - -@node The Echo Area -@section The Echo Area -@cindex error display -@cindex echo area - -@c FIXME: Why not use @xref{Minibuffers} directly? --xfq - The @dfn{echo area} is used for displaying error messages -(@pxref{Errors}), for messages made with the @code{message} primitive, -and for echoing keystrokes. It is not the same as the minibuffer, -despite the fact that the minibuffer appears (when active) in the same -place on the screen as the echo area. @xref{Minibuffer,, The -Minibuffer, emacs, The GNU Emacs Manual}. - - Apart from the functions documented in this section, you can print -Lisp objects to the echo area by specifying @code{t} as the output -stream. @xref{Output Streams}. - -@menu -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. -@end menu - -@node Displaying Messages -@subsection Displaying Messages in the Echo Area -@cindex display message in echo area - - This section describes the standard functions for displaying -messages in the echo area. - -@defun message format-string &rest arguments -This function displays a message in the echo area. -@var{format-string} is a format string, and @var{arguments} are the -objects for its format specifications, like in the @code{format} -function (@pxref{Formatting Strings}). The resulting formatted string -is displayed in the echo area; if it contains @code{face} text -properties, it is displayed with the specified faces (@pxref{Faces}). -The string is also added to the @file{*Messages*} buffer, but without -text properties (@pxref{Logging Messages}). - -In batch mode, the message is printed to the standard error stream, -followed by a newline. - -If @var{format-string} is @code{nil} or the empty string, -@code{message} clears the echo area; if the echo area has been -expanded automatically, this brings it back to its normal size. If -the minibuffer is active, this brings the minibuffer contents back -onto the screen immediately. - -@example -@group -(message "Minibuffer depth is %d." - (minibuffer-depth)) - @print{} Minibuffer depth is 0. -@result{} "Minibuffer depth is 0." -@end group - -@group ----------- Echo Area ---------- -Minibuffer depth is 0. ----------- Echo Area ---------- -@end group -@end example - -To automatically display a message in the echo area or in a pop-buffer, -depending on its size, use @code{display-message-or-buffer} (see below). -@end defun - -@defmac with-temp-message message &rest body -This construct displays a message in the echo area temporarily, during -the execution of @var{body}. It displays @var{message}, executes -@var{body}, then returns the value of the last body form while restoring -the previous echo area contents. -@end defmac - -@defun message-or-box format-string &rest arguments -This function displays a message like @code{message}, but may display it -in a dialog box instead of the echo area. If this function is called in -a command that was invoked using the mouse---more precisely, if -@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either -@code{nil} or a list---then it uses a dialog box or pop-up menu to -display the message. Otherwise, it uses the echo area. (This is the -same criterion that @code{y-or-n-p} uses to make a similar decision; see -@ref{Yes-or-No Queries}.) - -You can force use of the mouse or of the echo area by binding -@code{last-nonmenu-event} to a suitable value around the call. -@end defun - -@defun message-box format-string &rest arguments -@anchor{message-box} -This function displays a message like @code{message}, but uses a dialog -box (or a pop-up menu) whenever that is possible. If it is impossible -to use a dialog box or pop-up menu, because the terminal does not -support them, then @code{message-box} uses the echo area, like -@code{message}. -@end defun - -@defun display-message-or-buffer message &optional buffer-name not-this-window frame -This function displays the message @var{message}, which may be either a -string or a buffer. If it is shorter than the maximum height of the -echo area, as defined by @code{max-mini-window-height}, it is displayed -in the echo area, using @code{message}. Otherwise, -@code{display-buffer} is used to show it in a pop-up buffer. - -Returns either the string shown in the echo area, or when a pop-up -buffer is used, the window used to display it. - -If @var{message} is a string, then the optional argument -@var{buffer-name} is the name of the buffer used to display it when a -pop-up buffer is used, defaulting to @file{*Message*}. In the case -where @var{message} is a string and displayed in the echo area, it is -not specified whether the contents are inserted into the buffer anyway. - -The optional arguments @var{not-this-window} and @var{frame} are as for -@code{display-buffer}, and only used if a buffer is displayed. -@end defun - -@defun current-message -This function returns the message currently being displayed in the -echo area, or @code{nil} if there is none. -@end defun - -@node Progress -@subsection Reporting Operation Progress -@cindex progress reporting - - When an operation can take a while to finish, you should inform the -user about the progress it makes. This way the user can estimate -remaining time and clearly see that Emacs is busy working, not hung. -A convenient way to do this is to use a @dfn{progress reporter}. - - Here is a working example that does nothing useful: - -@smallexample -(let ((progress-reporter - (make-progress-reporter "Collecting mana for Emacs..." - 0 500))) - (dotimes (k 500) - (sit-for 0.01) - (progress-reporter-update progress-reporter k)) - (progress-reporter-done progress-reporter)) -@end smallexample - -@defun make-progress-reporter message &optional min-value max-value current-value min-change min-time -This function creates and returns a progress reporter object, which -you will use as an argument for the other functions listed below. The -idea is to precompute as much data as possible to make progress -reporting very fast. - -When this progress reporter is subsequently used, it will display -@var{message} in the echo area, followed by progress percentage. -@var{message} is treated as a simple string. If you need it to depend -on a filename, for instance, use @code{format} before calling this -function. - -The arguments @var{min-value} and @var{max-value} should be numbers -standing for the starting and final states of the operation. For -instance, an operation that ``scans'' a buffer should set these to the -results of @code{point-min} and @code{point-max} correspondingly. -@var{max-value} should be greater than @var{min-value}. - -Alternatively, you can set @var{min-value} and @var{max-value} to -@code{nil}. In that case, the progress reporter does not report -process percentages; it instead displays a ``spinner'' that rotates a -notch each time you update the progress reporter. - -If @var{min-value} and @var{max-value} are numbers, you can give the -argument @var{current-value} a numerical value specifying the initial -progress; if omitted, this defaults to @var{min-value}. - -The remaining arguments control the rate of echo area updates. The -progress reporter will wait for at least @var{min-change} more -percents of the operation to be completed before printing next -message; the default is one percent. @var{min-time} specifies the -minimum time in seconds to pass between successive prints; the default -is 0.2 seconds. (On some operating systems, the progress reporter may -handle fractions of seconds with varying precision). - -This function calls @code{progress-reporter-update}, so the first -message is printed immediately. -@end defun - -@defun progress-reporter-update reporter &optional value -This function does the main work of reporting progress of your -operation. It displays the message of @var{reporter}, followed by -progress percentage determined by @var{value}. If percentage is zero, -or close enough according to the @var{min-change} and @var{min-time} -arguments, then it is omitted from the output. - -@var{reporter} must be the result of a call to -@code{make-progress-reporter}. @var{value} specifies the current -state of your operation and must be between @var{min-value} and -@var{max-value} (inclusive) as passed to -@code{make-progress-reporter}. For instance, if you scan a buffer, -then @var{value} should be the result of a call to @code{point}. - -This function respects @var{min-change} and @var{min-time} as passed -to @code{make-progress-reporter} and so does not output new messages -on every invocation. It is thus very fast and normally you should not -try to reduce the number of calls to it: resulting overhead will most -likely negate your effort. -@end defun - -@defun progress-reporter-force-update reporter &optional value new-message -This function is similar to @code{progress-reporter-update} except -that it prints a message in the echo area unconditionally. - -The first two arguments have the same meaning as for -@code{progress-reporter-update}. Optional @var{new-message} allows -you to change the message of the @var{reporter}. Since this function -always updates the echo area, such a change will be immediately -presented to the user. -@end defun - -@defun progress-reporter-done reporter -This function should be called when the operation is finished. It -prints the message of @var{reporter} followed by word ``done'' in the -echo area. - -You should always call this function and not hope for -@code{progress-reporter-update} to print ``100%''. Firstly, it may -never print it, there are many good reasons for this not to happen. -Secondly, ``done'' is more explicit. -@end defun - -@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} -This is a convenience macro that works the same way as @code{dotimes} -does, but also reports loop progress using the functions described -above. It allows you to save some typing. - -You can rewrite the example in the beginning of this node using -this macro this way: - -@example -(dotimes-with-progress-reporter - (k 500) - "Collecting some mana for Emacs..." - (sit-for 0.01)) -@end example -@end defmac - -@node Logging Messages -@subsection Logging Messages in @file{*Messages*} -@cindex logging echo-area messages - - Almost all the messages displayed in the echo area are also recorded -in the @file{*Messages*} buffer so that the user can refer back to -them. This includes all the messages that are output with -@code{message}. By default, this buffer is read-only and uses the major -mode @code{messages-buffer-mode}. Nothing prevents the user from -killing the @file{*Messages*} buffer, but the next display of a message -recreates it. Any Lisp code that needs to access the -@file{*Messages*} buffer directly and wants to ensure that it exists -should use the function @code{messages-buffer}. - -@defun messages-buffer -This function returns the @file{*Messages*} buffer. If it does not -exist, it creates it, and switches it to @code{messages-buffer-mode}. -@end defun - -@defopt message-log-max -This variable specifies how many lines to keep in the @file{*Messages*} -buffer. The value @code{t} means there is no limit on how many lines to -keep. The value @code{nil} disables message logging entirely. Here's -how to display a message and prevent it from being logged: - -@example -(let (message-log-max) - (message @dots{})) -@end example -@end defopt - - To make @file{*Messages*} more convenient for the user, the logging -facility combines successive identical messages. It also combines -successive related messages for the sake of two cases: question -followed by answer, and a series of progress messages. - - A ``question followed by an answer'' means two messages like the -ones produced by @code{y-or-n-p}: the first is @samp{@var{question}}, -and the second is @samp{@var{question}...@var{answer}}. The first -message conveys no additional information beyond what's in the second, -so logging the second message discards the first from the log. - - A ``series of progress messages'' means successive messages like -those produced by @code{make-progress-reporter}. They have the form -@samp{@var{base}...@var{how-far}}, where @var{base} is the same each -time, while @var{how-far} varies. Logging each message in the series -discards the previous one, provided they are consecutive. - - The functions @code{make-progress-reporter} and @code{y-or-n-p} -don't have to do anything special to activate the message log -combination feature. It operates whenever two consecutive messages -are logged that share a common prefix ending in @samp{...}. - -@node Echo Area Customization -@subsection Echo Area Customization - - These variables control details of how the echo area works. - -@defvar cursor-in-echo-area -This variable controls where the cursor appears when a message is -displayed in the echo area. If it is non-@code{nil}, then the cursor -appears at the end of the message. Otherwise, the cursor appears at -point---not in the echo area at all. - -The value is normally @code{nil}; Lisp programs bind it to @code{t} -for brief periods of time. -@end defvar - -@defvar echo-area-clear-hook -This normal hook is run whenever the echo area is cleared---either by -@code{(message nil)} or for any other reason. -@end defvar - -@defopt echo-keystrokes -This variable determines how much time should elapse before command -characters echo. Its value must be a number, and specifies the -number of seconds to wait before echoing. If the user types a prefix -key (such as @kbd{C-x}) and then delays this many seconds before -continuing, the prefix key is echoed in the echo area. (Once echoing -begins in a key sequence, all subsequent characters in the same key -sequence are echoed immediately.) - -If the value is zero, then command input is not echoed. -@end defopt - -@defvar message-truncate-lines -Normally, displaying a long message resizes the echo area to display -the entire message. But if the variable @code{message-truncate-lines} -is non-@code{nil}, the echo area does not resize, and the message is -truncated to fit it. -@end defvar - - The variable @code{max-mini-window-height}, which specifies the -maximum height for resizing minibuffer windows, also applies to the -echo area (which is really a special use of the minibuffer window; -@pxref{Minibuffer Misc}). - -@node Warnings -@section Reporting Warnings -@cindex warnings - - @dfn{Warnings} are a facility for a program to inform the user of a -possible problem, but continue running. - -@menu -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize their warnings. -* Warning Options:: Variables users set to control display of warnings. -* Delayed Warnings:: Deferring a warning until the end of a command. -@end menu - -@node Warning Basics -@subsection Warning Basics -@cindex severity level - - Every warning has a textual message, which explains the problem for -the user, and a @dfn{severity level} which is a symbol. Here are the -possible severity levels, in order of decreasing severity, and their -meanings: - -@table @code -@item :emergency -A problem that will seriously impair Emacs operation soon -if you do not attend to it promptly. -@item :error -A report of data or circumstances that are inherently wrong. -@item :warning -A report of data or circumstances that are not inherently wrong, but -raise suspicion of a possible problem. -@item :debug -A report of information that may be useful if you are debugging. -@end table - - When your program encounters invalid input data, it can either -signal a Lisp error by calling @code{error} or @code{signal} or report -a warning with severity @code{:error}. Signaling a Lisp error is the -easiest thing to do, but it means the program cannot continue -processing. If you want to take the trouble to implement a way to -continue processing despite the bad data, then reporting a warning of -severity @code{:error} is the right way to inform the user of the -problem. For instance, the Emacs Lisp byte compiler can report an -error that way and continue compiling other functions. (If the -program signals a Lisp error and then handles it with -@code{condition-case}, the user won't see the error message; it could -show the message to the user by reporting it as a warning.) - -@c FIXME: Why use "(bytecomp)" instead of "'bytecomp" or simply -@c "bytecomp" here? The parens are part of warning-type-format but -@c not part of the warning type. --xfq -@cindex warning type - Each warning has a @dfn{warning type} to classify it. The type is a -list of symbols. The first symbol should be the custom group that you -use for the program's user options. For example, byte compiler -warnings use the warning type @code{(bytecomp)}. You can also -subcategorize the warnings, if you wish, by using more symbols in the -list. - -@defun display-warning type message &optional level buffer-name -This function reports a warning, using @var{message} as the message -and @var{type} as the warning type. @var{level} should be the -severity level, with @code{:warning} being the default. - -@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer -for logging the warning. By default, it is @file{*Warnings*}. -@end defun - -@defun lwarn type level message &rest args -This function reports a warning using the value of @code{(format -@var{message} @var{args}...)} as the message in the @file{*Warnings*} -buffer. In other respects it is equivalent to @code{display-warning}. -@end defun - -@defun warn message &rest args -This function reports a warning using the value of @code{(format -@var{message} @var{args}...)} as the message, @code{(emacs)} as the -type, and @code{:warning} as the severity level. It exists for -compatibility only; we recommend not using it, because you should -specify a specific warning type. -@end defun - -@node Warning Variables -@subsection Warning Variables - - Programs can customize how their warnings appear by binding -the variables described in this section. - -@defvar warning-levels -This list defines the meaning and severity order of the warning -severity levels. Each element defines one severity level, -and they are arranged in order of decreasing severity. - -Each element has the form @code{(@var{level} @var{string} -@var{function})}, where @var{level} is the severity level it defines. -@var{string} specifies the textual description of this level. -@var{string} should use @samp{%s} to specify where to put the warning -type information, or it can omit the @samp{%s} so as not to include -that information. - -The optional @var{function}, if non-@code{nil}, is a function to call -with no arguments, to get the user's attention. - -Normally you should not change the value of this variable. -@end defvar - -@defvar warning-prefix-function -If non-@code{nil}, the value is a function to generate prefix text for -warnings. Programs can bind the variable to a suitable function. -@code{display-warning} calls this function with the warnings buffer -current, and the function can insert text in it. That text becomes -the beginning of the warning message. - -The function is called with two arguments, the severity level and its -entry in @code{warning-levels}. It should return a list to use as the -entry (this value need not be an actual member of -@code{warning-levels}). By constructing this value, the function can -change the severity of the warning, or specify different handling for -a given severity level. - -If the variable's value is @code{nil} then there is no function -to call. -@end defvar - -@defvar warning-series -Programs can bind this variable to @code{t} to say that the next -warning should begin a series. When several warnings form a series, -that means to leave point on the first warning of the series, rather -than keep moving it for each warning so that it appears on the last one. -The series ends when the local binding is unbound and -@code{warning-series} becomes @code{nil} again. - -The value can also be a symbol with a function definition. That is -equivalent to @code{t}, except that the next warning will also call -the function with no arguments with the warnings buffer current. The -function can insert text which will serve as a header for the series -of warnings. - -Once a series has begun, the value is a marker which points to the -buffer position in the warnings buffer of the start of the series. - -The variable's normal value is @code{nil}, which means to handle -each warning separately. -@end defvar - -@defvar warning-fill-prefix -When this variable is non-@code{nil}, it specifies a fill prefix to -use for filling each warning's text. -@end defvar - -@defvar warning-type-format -This variable specifies the format for displaying the warning type -in the warning message. The result of formatting the type this way -gets included in the message under the control of the string in the -entry in @code{warning-levels}. The default value is @code{" (%s)"}. -If you bind it to @code{""} then the warning type won't appear at -all. -@end defvar - -@node Warning Options -@subsection Warning Options - - These variables are used by users to control what happens -when a Lisp program reports a warning. - -@defopt warning-minimum-level -This user option specifies the minimum severity level that should be -shown immediately to the user. The default is @code{:warning}, which -means to immediately display all warnings except @code{:debug} -warnings. -@end defopt - -@defopt warning-minimum-log-level -This user option specifies the minimum severity level that should be -logged in the warnings buffer. The default is @code{:warning}, which -means to log all warnings except @code{:debug} warnings. -@end defopt - -@defopt warning-suppress-types -This list specifies which warning types should not be displayed -immediately for the user. Each element of the list should be a list -of symbols. If its elements match the first elements in a warning -type, then that warning is not displayed immediately. -@end defopt - -@defopt warning-suppress-log-types -This list specifies which warning types should not be logged in the -warnings buffer. Each element of the list should be a list of -symbols. If it matches the first few elements in a warning type, then -that warning is not logged. -@end defopt - -@node Delayed Warnings -@subsection Delayed Warnings - -Sometimes, you may wish to avoid showing a warning while a command is -running, and only show it only after the end of the command. You can -use the variable @code{delayed-warnings-list} for this. - -@defvar delayed-warnings-list -The value of this variable is a list of warnings to be displayed after -the current command has finished. Each element must be a list - -@smallexample -(@var{type} @var{message} [@var{level} [@var{buffer-name}]]) -@end smallexample - -@noindent -with the same form, and the same meanings, as the argument list of -@code{display-warning} (@pxref{Warning Basics}). Immediately after -running @code{post-command-hook} (@pxref{Command Overview}), the Emacs -command loop displays all the warnings specified by this variable, -then resets it to @code{nil}. -@end defvar - - Programs which need to further customize the delayed warnings -mechanism can change the variable @code{delayed-warnings-hook}: - -@defvar delayed-warnings-hook -This is a normal hook which is run by the Emacs command loop, after -@code{post-command-hook}, in order to to process and display delayed -warnings. - -Its default value is a list of two functions: - -@smallexample -(collapse-delayed-warnings display-delayed-warnings) -@end smallexample - -@findex collapse-delayed-warnings -@findex display-delayed-warnings -@noindent -The function @code{collapse-delayed-warnings} removes repeated entries -from @code{delayed-warnings-list}. The function -@code{display-delayed-warnings} calls @code{display-warning} on each -of the entries in @code{delayed-warnings-list}, in turn, and then sets -@code{delayed-warnings-list} to @code{nil}. -@end defvar - -@node Invisible Text -@section Invisible Text - -@cindex invisible text -You can make characters @dfn{invisible}, so that they do not appear on -the screen, with the @code{invisible} property. This can be either a -text property (@pxref{Text Properties}) or an overlay property -(@pxref{Overlays}). Cursor motion also partly ignores these -characters; if the command loop finds that point is inside a range of -invisible text after a command, it relocates point to the other side -of the text. - -In the simplest case, any non-@code{nil} @code{invisible} property makes -a character invisible. This is the default case---if you don't alter -the default value of @code{buffer-invisibility-spec}, this is how the -@code{invisible} property works. You should normally use @code{t} -as the value of the @code{invisible} property if you don't plan -to set @code{buffer-invisibility-spec} yourself. - -More generally, you can use the variable @code{buffer-invisibility-spec} -to control which values of the @code{invisible} property make text -invisible. This permits you to classify the text into different subsets -in advance, by giving them different @code{invisible} values, and -subsequently make various subsets visible or invisible by changing the -value of @code{buffer-invisibility-spec}. - -Controlling visibility with @code{buffer-invisibility-spec} is -especially useful in a program to display the list of entries in a -database. It permits the implementation of convenient filtering -commands to view just a part of the entries in the database. Setting -this variable is very fast, much faster than scanning all the text in -the buffer looking for properties to change. - -@defvar buffer-invisibility-spec -This variable specifies which kinds of @code{invisible} properties -actually make a character invisible. Setting this variable makes it -buffer-local. - -@table @asis -@item @code{t} -A character is invisible if its @code{invisible} property is -non-@code{nil}. This is the default. - -@item a list -Each element of the list specifies a criterion for invisibility; if a -character's @code{invisible} property fits any one of these criteria, -the character is invisible. The list can have two kinds of elements: - -@table @code -@item @var{atom} -A character is invisible if its @code{invisible} property value is -@var{atom} or if it is a list with @var{atom} as a member; comparison -is done with @code{eq}. - -@item (@var{atom} . t) -A character is invisible if its @code{invisible} property value is -@var{atom} or if it is a list with @var{atom} as a member; comparison -is done with @code{eq}. Moreover, a sequence of such characters -displays as an ellipsis. -@end table -@end table -@end defvar - - Two functions are specifically provided for adding elements to -@code{buffer-invisibility-spec} and removing elements from it. - -@defun add-to-invisibility-spec element -This function adds the element @var{element} to -@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec} -was @code{t}, it changes to a list, @code{(t)}, so that text whose -@code{invisible} property is @code{t} remains invisible. -@end defun - -@defun remove-from-invisibility-spec element -This removes the element @var{element} from -@code{buffer-invisibility-spec}. This does nothing if @var{element} -is not in the list. -@end defun - - A convention for use of @code{buffer-invisibility-spec} is that a -major mode should use the mode's own name as an element of -@code{buffer-invisibility-spec} and as the value of the -@code{invisible} property: - -@example -;; @r{If you want to display an ellipsis:} -(add-to-invisibility-spec '(my-symbol . t)) -;; @r{If you don't want ellipsis:} -(add-to-invisibility-spec 'my-symbol) - -(overlay-put (make-overlay beginning end) - 'invisible 'my-symbol) - -;; @r{When done with the invisibility:} -(remove-from-invisibility-spec '(my-symbol . t)) -;; @r{Or respectively:} -(remove-from-invisibility-spec 'my-symbol) -@end example - - You can check for invisibility using the following function: - -@defun invisible-p pos-or-prop -If @var{pos-or-prop} is a marker or number, this function returns a -non-@code{nil} value if the text at that position is invisible. - -If @var{pos-or-prop} is any other kind of Lisp object, that is taken -to mean a possible value of the @code{invisible} text or overlay -property. In that case, this function returns a non-@code{nil} value -if that value would cause text to become invisible, based on the -current value of @code{buffer-invisibility-spec}. -@end defun - -@vindex line-move-ignore-invisible - Ordinarily, functions that operate on text or move point do not care -whether the text is invisible, they process invisible characters and -visible characters alike. The user-level line motion commands, -such as @code{next-line}, @code{previous-line}, ignore invisible -newlines if @code{line-move-ignore-invisible} is non-@code{nil} (the -default), i.e., behave like these invisible newlines didn't exist in -the buffer, but only because they are explicitly programmed to do so. - - If a command ends with point inside or at the boundary of -invisible text, the main editing loop relocates point to one of the -two ends of the invisible text. Emacs chooses the direction of -relocation so that it is the same as the overall movement direction of -the command; if in doubt, it prefers a position where an inserted char -would not inherit the @code{invisible} property. Additionally, if the -text is not replaced by an ellipsis and the command only moved within -the invisible text, then point is moved one extra character so as to -try and reflect the command's movement by a visible movement of the -cursor. - - Thus, if the command moved point back to an invisible range (with the usual -stickiness), Emacs moves point back to the beginning of that range. If the -command moved point forward into an invisible range, Emacs moves point forward -to the first visible character that follows the invisible text and then forward -one more character. - - These @dfn{adjustments} of point that ended up in the middle of -invisible text can be disabled by setting @code{disable-point-adjustment} -to a non-@code{nil} value. @xref{Adjusting Point}. - - Incremental search can make invisible overlays visible temporarily -and/or permanently when a match includes invisible text. To enable -this, the overlay should have a non-@code{nil} -@code{isearch-open-invisible} property. The property value should be a -function to be called with the overlay as an argument. This function -should make the overlay visible permanently; it is used when the match -overlaps the overlay on exit from the search. - - During the search, such overlays are made temporarily visible by -temporarily modifying their invisible and intangible properties. If you -want this to be done differently for a certain overlay, give it an -@code{isearch-open-invisible-temporary} property which is a function. -The function is called with two arguments: the first is the overlay, and -the second is @code{nil} to make the overlay visible, or @code{t} to -make it invisible again. - -@node Selective Display -@section Selective Display -@c @cindex selective display Duplicates selective-display - - @dfn{Selective display} refers to a pair of related features for -hiding certain lines on the screen. - -@cindex explicit selective display - The first variant, explicit selective display, was designed for use in a Lisp -program: it controls which lines are hidden by altering the text. This kind of -hiding is now obsolete; instead you can get the same effect with the -@code{invisible} property (@pxref{Invisible Text}). - - In the second variant, the choice of lines to hide is made -automatically based on indentation. This variant is designed to be a -user-level feature. - - The way you control explicit selective display is by replacing a -newline (control-j) with a carriage return (control-m). The text that -was formerly a line following that newline is now hidden. Strictly -speaking, it is temporarily no longer a line at all, since only -newlines can separate lines; it is now part of the previous line. - - Selective display does not directly affect editing commands. For -example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly -into hidden text. However, the replacement of newline characters with -carriage return characters affects some editing commands. For -example, @code{next-line} skips hidden lines, since it searches only -for newlines. Modes that use selective display can also define -commands that take account of the newlines, or that control which -parts of the text are hidden. - - When you write a selectively displayed buffer into a file, all the -control-m's are output as newlines. This means that when you next read -in the file, it looks OK, with nothing hidden. The selective display -effect is seen only within Emacs. - -@defvar selective-display -This buffer-local variable enables selective display. This means that -lines, or portions of lines, may be made hidden. - -@itemize @bullet -@item -If the value of @code{selective-display} is @code{t}, then the character -control-m marks the start of hidden text; the control-m, and the rest -of the line following it, are not displayed. This is explicit selective -display. - -@item -If the value of @code{selective-display} is a positive integer, then -lines that start with more than that many columns of indentation are not -displayed. -@end itemize - -When some portion of a buffer is hidden, the vertical movement -commands operate as if that portion did not exist, allowing a single -@code{next-line} command to skip any number of hidden lines. -However, character movement commands (such as @code{forward-char}) do -not skip the hidden portion, and it is possible (if tricky) to insert -or delete text in an hidden portion. - -In the examples below, we show the @emph{display appearance} of the -buffer @code{foo}, which changes with the value of -@code{selective-display}. The @emph{contents} of the buffer do not -change. - -@example -@group -(setq selective-display nil) - @result{} nil - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 3n this column - 3n this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group - -@group -(setq selective-display 2) - @result{} 2 - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example -@end defvar - -@defopt selective-display-ellipses -If this buffer-local variable is non-@code{nil}, then Emacs displays -@samp{@dots{}} at the end of a line that is followed by hidden text. -This example is a continuation of the previous one. - -@example -@group -(setq selective-display-ellipses t) - @result{} t - ----------- Buffer: foo ---------- -1 on this column - 2on this column ... - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example - -You can use a display table to substitute other text for the ellipsis -(@samp{@dots{}}). @xref{Display Tables}. -@end defopt - -@node Temporary Displays -@section Temporary Displays - - Temporary displays are used by Lisp programs to put output into a -buffer and then present it to the user for perusal rather than for -editing. Many help commands use this feature. - -@defmac with-output-to-temp-buffer buffer-name body@dots{} -This function executes the forms in @var{body} while arranging to insert -any output they print into the buffer named @var{buffer-name}, which is -first created if necessary, and put into Help mode. (See the similar -form @code{with-temp-buffer-window} below.) Finally, the buffer is -displayed in some window, but that window is not selected. - -If the forms in @var{body} do not change the major mode in the output -buffer, so that it is still Help mode at the end of their execution, -then @code{with-output-to-temp-buffer} makes this buffer read-only at -the end, and also scans it for function and variable names to make them -into clickable cross-references. @xref{Docstring hyperlinks, , Tips for -Documentation Strings}, in particular the item on hyperlinks in -documentation strings, for more details. - -The string @var{buffer-name} specifies the temporary buffer, which need -not already exist. The argument must be a string, not a buffer. The -buffer is erased initially (with no questions asked), and it is marked -as unmodified after @code{with-output-to-temp-buffer} exits. - -@code{with-output-to-temp-buffer} binds @code{standard-output} to the -temporary buffer, then it evaluates the forms in @var{body}. Output -using the Lisp output functions within @var{body} goes by default to -that buffer (but screen display and messages in the echo area, although -they are ``output'' in the general sense of the word, are not affected). -@xref{Output Functions}. - -Several hooks are available for customizing the behavior -of this construct; they are listed below. - -The value of the last form in @var{body} is returned. - -@example -@group ----------- Buffer: foo ---------- - This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(with-output-to-temp-buffer "foo" - (print 20) - (print standard-output)) -@result{} # - ----------- Buffer: foo ---------- - -20 - -# - ----------- Buffer: foo ---------- -@end group -@end example -@end defmac - -@defopt temp-buffer-show-function -If this variable is non-@code{nil}, @code{with-output-to-temp-buffer} -calls it as a function to do the job of displaying a help buffer. The -function gets one argument, which is the buffer it should display. - -It is a good idea for this function to run @code{temp-buffer-show-hook} -just as @code{with-output-to-temp-buffer} normally would, inside of -@code{save-selected-window} and with the chosen window and buffer -selected. -@end defopt - -@defvar temp-buffer-setup-hook -This normal hook is run by @code{with-output-to-temp-buffer} before -evaluating @var{body}. When the hook runs, the temporary buffer is -current. This hook is normally set up with a function to put the -buffer in Help mode. -@end defvar - -@defvar temp-buffer-show-hook -This normal hook is run by @code{with-output-to-temp-buffer} after -displaying the temporary buffer. When the hook runs, the temporary buffer -is current, and the window it was displayed in is selected. -@end defvar - -@defmac with-temp-buffer-window buffer-or-name action quit-function body@dots{} -This macro is similar to @code{with-output-to-temp-buffer}. Like that -construct, it executes @var{body} while arranging to insert any output -it prints into the buffer named @var{buffer-or-name} and displays that -buffer in some window. Unlike @code{with-output-to-temp-buffer}, -however, it does not automatically switch that buffer to Help mode. - -Like @code{with-output-to-temp-buffer} it neither makes the buffer -specified by @var{buffer-or-name} current when executing @var{body}. -@findex with-current-buffer-window -The otherwise identical macro @code{with-current-buffer-window} can be -used to execute @var{body} with that buffer current. - -The argument @var{buffer-or-name} specifies the temporary buffer. It -can be either a buffer, which must already exist, or a string, in which -case a buffer of that name is created, if necessary. The buffer is -marked as unmodified and read-only when @code{with-temp-buffer-window} -exits. - -This macro does not call @code{temp-buffer-show-function}. Rather, it -passes the @var{action} argument to @code{display-buffer} in order to -display the buffer. - -The value of the last form in @var{body} is returned, unless the -argument @var{quit-function} is specified. In that case, it is called -with two arguments: the window showing the buffer and the result of -@var{body}. The final return value is then whatever -@var{quit-function} returns. - -@vindex temp-buffer-window-setup-hook -@vindex temp-buffer-window-show-hook -This macro uses the normal hooks @code{temp-buffer-window-setup-hook} -and @code{temp-buffer-window-show-hook} in place of the analogous hooks -run by @code{with-output-to-temp-buffer}. -@end defmac - -@defun momentary-string-display string position &optional char message -This function momentarily displays @var{string} in the current buffer at -@var{position}. It has no effect on the undo list or on the buffer's -modification status. - -The momentary display remains until the next input event. If the next -input event is @var{char}, @code{momentary-string-display} ignores it -and returns. Otherwise, that event remains buffered for subsequent use -as input. Thus, typing @var{char} will simply remove the string from -the display, while typing (say) @kbd{C-f} will remove the string from -the display and later (presumably) move point forward. The argument -@var{char} is a space by default. - -The return value of @code{momentary-string-display} is not meaningful. - -If the string @var{string} does not contain control characters, you can -do the same job in a more general way by creating (and then subsequently -deleting) an overlay with a @code{before-string} property. -@xref{Overlay Properties}. - -If @var{message} is non-@code{nil}, it is displayed in the echo area -while @var{string} is displayed in the buffer. If it is @code{nil}, a -default message says to type @var{char} to continue. - -In this example, point is initially located at the beginning of the -second line: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo. -@point{}Second line. ----------- Buffer: foo ---------- -@end group - -@group -(momentary-string-display - "**** Important Message! ****" - (point) ?\r - "Type RET when done reading") -@result{} t -@end group - -@group ----------- Buffer: foo ---------- -This is the contents of foo. -**** Important Message! ****Second line. ----------- Buffer: foo ---------- - ----------- Echo Area ---------- -Type RET when done reading ----------- Echo Area ---------- -@end group -@end example -@end defun - -@node Overlays -@section Overlays -@cindex overlays -@c FIXME: mention intervals in this section? - -You can use @dfn{overlays} to alter the appearance of a buffer's text on -the screen, for the sake of presentation features. An overlay is an -object that belongs to a particular buffer, and has a specified -beginning and end. It also has properties that you can examine and set; -these affect the display of the text within the overlay. - -@cindex scalability of overlays -The visual effect of an overlay is the same as of the corresponding -text property (@pxref{Text Properties}). However, due to a different -implementation, overlays generally don't scale well (many operations -take a time that is proportional to the number of overlays in the -buffer). If you need to affect the visual appearance of many portions -in the buffer, we recommend using text properties. - -An overlay uses markers to record its beginning and end; thus, -editing the text of the buffer adjusts the beginning and end of each -overlay so that it stays with the text. When you create the overlay, -you can specify whether text inserted at the beginning should be -inside the overlay or outside, and likewise for the end of the overlay. - -@menu -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. -@end menu - -@node Managing Overlays -@subsection Managing Overlays - - This section describes the functions to create, delete and move -overlays, and to examine their contents. Overlay changes are not -recorded in the buffer's undo list, since the overlays are not -part of the buffer's contents. - -@defun overlayp object -This function returns @code{t} if @var{object} is an overlay. -@end defun - -@defun make-overlay start end &optional buffer front-advance rear-advance -This function creates and returns an overlay that belongs to -@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} -and @var{end} must specify buffer positions; they may be integers or -markers. If @var{buffer} is omitted, the overlay is created in the -current buffer. - -The arguments @var{front-advance} and @var{rear-advance} specify the -marker insertion type for the start of the overlay and for the end of -the overlay, respectively. @xref{Marker Insertion Types}. If they -are both @code{nil}, the default, then the overlay extends to include -any text inserted at the beginning, but not text inserted at the end. -If @var{front-advance} is non-@code{nil}, text inserted at the -beginning of the overlay is excluded from the overlay. If -@var{rear-advance} is non-@code{nil}, text inserted at the end of the -overlay is included in the overlay. -@end defun - -@defun overlay-start overlay -This function returns the position at which @var{overlay} starts, -as an integer. -@end defun - -@defun overlay-end overlay -This function returns the position at which @var{overlay} ends, -as an integer. -@end defun - -@defun overlay-buffer overlay -This function returns the buffer that @var{overlay} belongs to. It -returns @code{nil} if @var{overlay} has been deleted. -@end defun - -@defun delete-overlay overlay -This function deletes @var{overlay}. The overlay continues to exist as -a Lisp object, and its property list is unchanged, but it ceases to be -attached to the buffer it belonged to, and ceases to have any effect on -display. - -A deleted overlay is not permanently disconnected. You can give it a -position in a buffer again by calling @code{move-overlay}. -@end defun - -@defun move-overlay overlay start end &optional buffer -This function moves @var{overlay} to @var{buffer}, and places its bounds -at @var{start} and @var{end}. Both arguments @var{start} and @var{end} -must specify buffer positions; they may be integers or markers. - -If @var{buffer} is omitted, @var{overlay} stays in the same buffer it -was already associated with; if @var{overlay} was deleted, it goes into -the current buffer. - -The return value is @var{overlay}. - -This is the only valid way to change the endpoints of an overlay. Do -not try modifying the markers in the overlay by hand, as that fails to -update other vital data structures and can cause some overlays to be -``lost''. -@end defun - -@defun remove-overlays &optional start end name value -This function removes all the overlays between @var{start} and -@var{end} whose property @var{name} has the value @var{value}. It can -move the endpoints of the overlays in the region, or split them. - -If @var{name} is omitted or @code{nil}, it means to delete all overlays in -the specified region. If @var{start} and/or @var{end} are omitted or -@code{nil}, that means the beginning and end of the buffer respectively. -Therefore, @code{(remove-overlays)} removes all the overlays in the -current buffer. -@end defun - -@defun copy-overlay overlay -This function returns a copy of @var{overlay}. The copy has the same -endpoints and properties as @var{overlay}. However, the marker -insertion type for the start of the overlay and for the end of the -overlay are set to their default values (@pxref{Marker Insertion -Types}). -@end defun - - Here are some examples: - -@example -;; @r{Create an overlay.} -(setq foo (make-overlay 1 10)) - @result{} # -(overlay-start foo) - @result{} 1 -(overlay-end foo) - @result{} 10 -(overlay-buffer foo) - @result{} # -;; @r{Give it a property we can check later.} -(overlay-put foo 'happy t) - @result{} t -;; @r{Verify the property is present.} -(overlay-get foo 'happy) - @result{} t -;; @r{Move the overlay.} -(move-overlay foo 5 20) - @result{} # -(overlay-start foo) - @result{} 5 -(overlay-end foo) - @result{} 20 -;; @r{Delete the overlay.} -(delete-overlay foo) - @result{} nil -;; @r{Verify it is deleted.} -foo - @result{} # -;; @r{A deleted overlay has no position.} -(overlay-start foo) - @result{} nil -(overlay-end foo) - @result{} nil -(overlay-buffer foo) - @result{} nil -;; @r{Undelete the overlay.} -(move-overlay foo 1 20) - @result{} # -;; @r{Verify the results.} -(overlay-start foo) - @result{} 1 -(overlay-end foo) - @result{} 20 -(overlay-buffer foo) - @result{} # -;; @r{Moving and deleting the overlay does not change its properties.} -(overlay-get foo 'happy) - @result{} t -@end example - - Emacs stores the overlays of each buffer in two lists, divided -around an arbitrary ``center position''. One list extends backwards -through the buffer from that center position, and the other extends -forwards from that center position. The center position can be anywhere -in the buffer. - -@defun overlay-recenter pos -This function recenters the overlays of the current buffer around -position @var{pos}. That makes overlay lookup faster for positions -near @var{pos}, but slower for positions far away from @var{pos}. -@end defun - - A loop that scans the buffer forwards, creating overlays, can run -faster if you do @code{(overlay-recenter (point-max))} first. - -@node Overlay Properties -@subsection Overlay Properties - - Overlay properties are like text properties in that the properties that -alter how a character is displayed can come from either source. But in -most respects they are different. @xref{Text Properties}, for comparison. - - Text properties are considered a part of the text; overlays and -their properties are specifically considered not to be part of the -text. Thus, copying text between various buffers and strings -preserves text properties, but does not try to preserve overlays. -Changing a buffer's text properties marks the buffer as modified, -while moving an overlay or changing its properties does not. Unlike -text property changes, overlay property changes are not recorded in -the buffer's undo list. - - Since more than one overlay can specify a property value for the -same character, Emacs lets you specify a priority value of each -overlay. In case two overlays have the same priority value, and one -is nested in the other, then the inner one will have priority over the -outer one. If neither is nested in the other then you should not make -assumptions about which overlay will prevail. - - These functions read and set the properties of an overlay: - -@defun overlay-get overlay prop -This function returns the value of property @var{prop} recorded in -@var{overlay}, if any. If @var{overlay} does not record any value for -that property, but it does have a @code{category} property which is a -symbol, that symbol's @var{prop} property is used. Otherwise, the value -is @code{nil}. -@end defun - -@defun overlay-put overlay prop value -This function sets the value of property @var{prop} recorded in -@var{overlay} to @var{value}. It returns @var{value}. -@end defun - -@defun overlay-properties overlay -This returns a copy of the property list of @var{overlay}. -@end defun - - See also the function @code{get-char-property} which checks both -overlay properties and text properties for a given character. -@xref{Examining Properties}. - - Many overlay properties have special meanings; here is a table -of them: - -@table @code -@item priority -@kindex priority @r{(overlay property)} -This property's value determines the priority of the overlay. -If you want to specify a priority value, use either @code{nil} -(or zero), or a positive integer. Any other value has undefined behavior. - -The priority matters when two or more overlays cover the same -character and both specify the same property; the one whose -@code{priority} value is larger overrides the other. For the -@code{face} property, the higher priority overlay's value does not -completely override the other value; instead, its face attributes -override the face attributes of the lower priority @code{face} -property. - -Currently, all overlays take priority over text properties. - -Note that Emacs sometimes uses non-numeric priority values for some of -its internal overlays, so do not try to do arithmetic on the -priority of an overlay (unless it is one that you created). If you -need to put overlays in priority order, use the @var{sorted} argument -of @code{overlays-at}. @xref{Finding Overlays}. - -@item window -@kindex window @r{(overlay property)} -If the @code{window} property is non-@code{nil}, then the overlay -applies only on that window. - -@item category -@kindex category @r{(overlay property)} -If an overlay has a @code{category} property, we call it the -@dfn{category} of the overlay. It should be a symbol. The properties -of the symbol serve as defaults for the properties of the overlay. - -@item face -@kindex face @r{(overlay property)} -This property controls the appearance of the text (@pxref{Faces}). -The value of the property can be the following: - -@itemize @bullet -@item -A face name (a symbol or string). - -@item -An anonymous face: a property list of the form @code{(@var{keyword} -@var{value} @dots{})}, where each @var{keyword} is a face attribute -name and @var{value} is a value for that attribute. - -@item -A list of faces. Each list element should be either a face name or an -anonymous face. This specifies a face which is an aggregate of the -attributes of each of the listed faces. Faces occurring earlier in -the list have higher priority. - -@item -A cons cell of the form @code{(foreground-color . @var{color-name})} -or @code{(background-color . @var{color-name})}. This specifies the -foreground or background color, similar to @code{(:foreground -@var{color-name})} or @code{(:background @var{color-name})}. This -form is supported for backward compatibility only, and should be -avoided. -@end itemize - -@item mouse-face -@kindex mouse-face @r{(overlay property)} -This property is used instead of @code{face} when the mouse is within -the range of the overlay. However, Emacs ignores all face attributes -from this property that alter the text size (e.g., @code{:height}, -@code{:weight}, and @code{:slant}). Those attributes are always the -same as in the unhighlighted text. - -@item display -@kindex display @r{(overlay property)} -This property activates various features that change the -way text is displayed. For example, it can make text appear taller -or shorter, higher or lower, wider or narrower, or replaced with an image. -@xref{Display Property}. - -@item help-echo -@kindex help-echo @r{(overlay property)} -If an overlay has a @code{help-echo} property, then when you move the -mouse onto the text in the overlay, Emacs displays a help string in the -echo area, or in the tooltip window. For details see @ref{Text -help-echo}. - -@item field -@kindex field @r{(overlay property)} -@c Copied from Special Properties. -Consecutive characters with the same @code{field} property constitute a -@emph{field}. Some motion functions including @code{forward-word} and -@code{beginning-of-line} stop moving at a field boundary. -@xref{Fields}. - -@item modification-hooks -@kindex modification-hooks @r{(overlay property)} -This property's value is a list of functions to be called if any -character within the overlay is changed or if text is inserted strictly -within the overlay. - -The hook functions are called both before and after each change. -If the functions save the information they receive, and compare notes -between calls, they can determine exactly what change has been made -in the buffer text. - -When called before a change, each function receives four arguments: the -overlay, @code{nil}, and the beginning and end of the text range to be -modified. - -When called after a change, each function receives five arguments: the -overlay, @code{t}, the beginning and end of the text range just -modified, and the length of the pre-change text replaced by that range. -(For an insertion, the pre-change length is zero; for a deletion, that -length is the number of characters deleted, and the post-change -beginning and end are equal.) - -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. - -Text properties also support the @code{modification-hooks} property, -but the details are somewhat different (@pxref{Special Properties}). - -@item insert-in-front-hooks -@kindex insert-in-front-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the beginning of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item insert-behind-hooks -@kindex insert-behind-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the end of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item invisible -@kindex invisible @r{(overlay property)} -The @code{invisible} property can make the text in the overlay -invisible, which means that it does not appear on the screen. -@xref{Invisible Text}, for details. - -@item intangible -@kindex intangible @r{(overlay property)} -The @code{intangible} property on an overlay works just like the -@code{intangible} text property. @xref{Special Properties}, for details. - -@item isearch-open-invisible -This property tells incremental search how to make an invisible overlay -visible, permanently, if the final match overlaps it. @xref{Invisible -Text}. - -@item isearch-open-invisible-temporary -This property tells incremental search how to make an invisible overlay -visible, temporarily, during the search. @xref{Invisible Text}. - -@item before-string -@kindex before-string @r{(overlay property)} -This property's value is a string to add to the display at the beginning -of the overlay. The string does not appear in the buffer in any -sense---only on the screen. - -@item after-string -@kindex after-string @r{(overlay property)} -This property's value is a string to add to the display at the end of -the overlay. The string does not appear in the buffer in any -sense---only on the screen. - -@item line-prefix -This property specifies a display spec to prepend to each -non-continuation line at display-time. @xref{Truncation}. - -@item wrap-prefix -This property specifies a display spec to prepend to each continuation -line at display-time. @xref{Truncation}. - -@item evaporate -@kindex evaporate @r{(overlay property)} -If this property is non-@code{nil}, the overlay is deleted automatically -if it becomes empty (i.e., if its length becomes zero). If you give -an empty overlay a non-@code{nil} @code{evaporate} property, that deletes -it immediately. - -@item keymap -@cindex keymap of character (and overlays) -@kindex keymap @r{(overlay property)} -If this property is non-@code{nil}, it specifies a keymap for a portion of the -text. This keymap is used when the character after point is within the -overlay, and takes precedence over most other keymaps. @xref{Active Keymaps}. - -@item local-map -@kindex local-map @r{(overlay property)} -The @code{local-map} property is similar to @code{keymap} but replaces the -buffer's local map rather than augmenting existing keymaps. This also means it -has lower precedence than minor mode keymaps. -@end table - -The @code{keymap} and @code{local-map} properties do not affect a -string displayed by the @code{before-string}, @code{after-string}, or -@code{display} properties. This is only relevant for mouse clicks and -other mouse events that fall on the string, since point is never on -the string. To bind special mouse events for the string, assign it a -@code{keymap} or @code{local-map} text property. @xref{Special -Properties}. - -@node Finding Overlays -@subsection Searching for Overlays - -@defun overlays-at pos &optional sorted -This function returns a list of all the overlays that cover the character at -position @var{pos} in the current buffer. If @var{sorted} is non-@code{nil}, -the list is in decreasing order of priority, otherwise it is in no particular -order. An overlay contains position @var{pos} if it begins at or before -@var{pos}, and ends after @var{pos}. - -To illustrate usage, here is a Lisp function that returns a list of the -overlays that specify property @var{prop} for the character at point: - -@smallexample -(defun find-overlays-specifying (prop) - (let ((overlays (overlays-at (point))) - found) - (while overlays - (let ((overlay (car overlays))) - (if (overlay-get overlay prop) - (setq found (cons overlay found)))) - (setq overlays (cdr overlays))) - found)) -@end smallexample -@end defun - -@defun overlays-in beg end -This function returns a list of the overlays that overlap the region -@var{beg} through @var{end}. ``Overlap'' means that at least one -character is contained within the overlay and also contained within the -specified region; however, empty overlays are included in the result if -they are located at @var{beg}, strictly between @var{beg} and @var{end}, -or at @var{end} when @var{end} denotes the position at the end of the -buffer. -@end defun - -@defun next-overlay-change pos -This function returns the buffer position of the next beginning or end -of an overlay, after @var{pos}. If there is none, it returns -@code{(point-max)}. -@end defun - -@defun previous-overlay-change pos -This function returns the buffer position of the previous beginning or -end of an overlay, before @var{pos}. If there is none, it returns -@code{(point-min)}. -@end defun - - As an example, here's a simplified (and inefficient) version of the -primitive function @code{next-single-char-property-change} -(@pxref{Property Search}). It searches forward from position -@var{pos} for the next position where the value of a given property -@code{prop}, as obtained from either overlays or text properties, -changes. - -@smallexample -(defun next-single-char-property-change (position prop) - (save-excursion - (goto-char position) - (let ((propval (get-char-property (point) prop))) - (while (and (not (eobp)) - (eq (get-char-property (point) prop) propval)) - (goto-char (min (next-overlay-change (point)) - (next-single-property-change (point) prop))))) - (point))) -@end smallexample - -@node Size of Displayed Text -@section Size of Displayed Text - -Since not all characters have the same width, these functions let you -check the width of a character. @xref{Primitive Indent}, and -@ref{Screen Lines}, for related functions. - -@defun char-width char -This function returns the width in columns of the character -@var{char}, if it were displayed in the current buffer (i.e., taking -into account the buffer's display table, if any; @pxref{Display -Tables}). The width of a tab character is usually @code{tab-width} -(@pxref{Usual Display}). -@end defun - -@defun string-width string -This function returns the width in columns of the string @var{string}, -if it were displayed in the current buffer and the selected window. -@end defun - -@defun truncate-string-to-width string width &optional start-column padding ellipsis -This function returns the part of @var{string} that fits within -@var{width} columns, as a new string. - -If @var{string} does not reach @var{width}, then the result ends where -@var{string} ends. If one multi-column character in @var{string} -extends across the column @var{width}, that character is not included in -the result. Thus, the result can fall short of @var{width} but cannot -go beyond it. - -The optional argument @var{start-column} specifies the starting column. -If this is non-@code{nil}, then the first @var{start-column} columns of -the string are omitted from the value. If one multi-column character in -@var{string} extends across the column @var{start-column}, that -character is not included. - -The optional argument @var{padding}, if non-@code{nil}, is a padding -character added at the beginning and end of the result string, to extend -it to exactly @var{width} columns. The padding character is used at the -end of the result if it falls short of @var{width}. It is also used at -the beginning of the result if one multi-column character in -@var{string} extends across the column @var{start-column}. - -If @var{ellipsis} is non-@code{nil}, it should be a string which will -replace the end of @var{string} (including any padding) if it extends -beyond @var{width}, unless the display width of @var{string} is equal -to or less than the display width of @var{ellipsis}. If -@var{ellipsis} is non-@code{nil} and not a string, it stands for -@code{"..."}. - -@example -(truncate-string-to-width "\tab\t" 12 4) - @result{} "ab" -(truncate-string-to-width "\tab\t" 12 4 ?\s) - @result{} " ab " -@end example -@end defun - -The following function returns the size in pixels of text as if it were -displayed in a given window. This function is used by -@code{fit-window-to-buffer} (@pxref{Resizing Windows}) and -@code{fit-frame-to-buffer} (@pxref{Size and Position}) to make a window -exactly as large as the text it contains. - -@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line -This function returns the size of the text of @var{window}'s buffer in -pixels. @var{window} must be a live window and defaults to the selected -one. The return value is a cons of the maximum pixel-width of any text -line and the maximum pixel-height of all text lines. - -The optional argument @var{from}, if non-@code{nil}, specifies the first -text position to consider and defaults to the minimum accessible -position of the buffer. If @var{from} is @code{t}, it uses the minimum -accessible position that is not a newline character. The optional -argument @var{to}, if non-@code{nil}, specifies the last text position -to consider and defaults to the maximum accessible position of the -buffer. If @var{to} is @code{t}, it uses the maximum accessible -position that is not a newline character. - -The optional argument @var{x-limit}, if non-@code{nil}, specifies the -maximum pixel-width that can be returned. @var{x-limit} @code{nil} or -omitted, means to use the pixel-width of @var{window}'s body -(@pxref{Window Sizes}); this is useful when the caller does not intend -to change the width of @var{window}. Otherwise, the caller should -specify here the maximum width @var{window}'s body may assume. Text -whose x-coordinate is beyond @var{x-limit} is ignored. Since -calculating the width of long lines can take some time, it's always a -good idea to make this argument as small as needed; in particular, if -the buffer might contain long lines that will be truncated anyway. - -The optional argument @var{y-limit}, if non-@code{nil}, specifies the -maximum pixel-height that can be returned. Text lines whose -y-coordinate is beyond @var{y-limit} are ignored. Since calculating the -pixel-height of a large buffer can take some time, it makes sense to -specify this argument; in particular, if the caller does not know the -size of the buffer. - -The optional argument @var{mode-and-header-line} @code{nil} or omitted -means to not include the height of the mode- or header-line of -@var{window} in the return value. If it is either the symbol -@code{mode-line} or @code{header-line}, include only the height of that -line, if present, in the return value. If it is @code{t}, include the -height of both, if present, in the return value. -@end defun - - -@node Line Height -@section Line Height -@cindex line height -@cindex height of a line - - The total height of each display line consists of the height of the -contents of the line, plus optional additional vertical line spacing -above or below the display line. - - The height of the line contents is the maximum height of any -character or image on that display line, including the final newline -if there is one. (A display line that is continued doesn't include a -final newline.) That is the default line height, if you do nothing to -specify a greater height. (In the most common case, this equals the -height of the default frame font.) - - There are several ways to explicitly specify a larger line height, -either by specifying an absolute height for the display line, or by -specifying vertical space. However, no matter what you specify, the -actual line height can never be less than the default. - -@kindex line-height @r{(text property)} - A newline can have a @code{line-height} text or overlay property -that controls the total height of the display line ending in that -newline. - - If the property value is @code{t}, the newline character has no -effect on the displayed height of the line---the visible contents -alone determine the height. This is useful for tiling small images -(or image slices) without adding blank areas between the images. - - If the property value is a list of the form @code{(@var{height} -@var{total})}, that adds extra space @emph{below} the display line. -First Emacs uses @var{height} as a height spec to control extra space -@emph{above} the line; then it adds enough space @emph{below} the line -to bring the total line height up to @var{total}. In this case, the -other ways to specify the line spacing are ignored. - -@cindex height spec - Any other kind of property value is a height spec, which translates -into a number---the specified line height. There are several ways to -write a height spec; here's how each of them translates into a number: - -@table @code -@item @var{integer} -If the height spec is a positive integer, the height value is that integer. -@item @var{float} -If the height spec is a float, @var{float}, the numeric height value -is @var{float} times the frame's default line height. -@item (@var{face} . @var{ratio}) -If the height spec is a cons of the format shown, the numeric height -is @var{ratio} times the height of face @var{face}. @var{ratio} can -be any type of number, or @code{nil} which means a ratio of 1. -If @var{face} is @code{t}, it refers to the current face. -@item (nil . @var{ratio}) -If the height spec is a cons of the format shown, the numeric height -is @var{ratio} times the height of the contents of the line. -@end table - - Thus, any valid height spec determines the height in pixels, one way -or another. If the line contents' height is less than that, Emacs -adds extra vertical space above the line to achieve the specified -total height. - - If you don't specify the @code{line-height} property, the line's -height consists of the contents' height plus the line spacing. -There are several ways to specify the line spacing for different -parts of Emacs text. - - On graphical terminals, you can specify the line spacing for all -lines in a frame, using the @code{line-spacing} frame parameter -(@pxref{Layout Parameters}). However, if the default value of -@code{line-spacing} is non-@code{nil}, it overrides the -frame's @code{line-spacing} parameter. An integer specifies the -number of pixels put below lines. A floating-point number specifies -the spacing relative to the frame's default line height. - -@vindex line-spacing - You can specify the line spacing for all lines in a buffer via the -buffer-local @code{line-spacing} variable. An integer specifies -the number of pixels put below lines. A floating-point number -specifies the spacing relative to the default frame line height. This -overrides line spacings specified for the frame. - -@kindex line-spacing @r{(text property)} - Finally, a newline can have a @code{line-spacing} text or overlay -property that overrides the default frame line spacing and the buffer -local @code{line-spacing} variable, for the display line ending in -that newline. - - One way or another, these mechanisms specify a Lisp value for the -spacing of each line. The value is a height spec, and it translates -into a Lisp value as described above. However, in this case the -numeric height value specifies the line spacing, rather than the line -height. - - On text terminals, the line spacing cannot be altered. - -@node Faces -@section Faces -@cindex faces - - A @dfn{face} is a collection of graphical attributes for displaying -text: font, foreground color, background color, optional underlining, -etc. Faces control how Emacs displays text in buffers, as well as -other parts of the frame such as the mode line. - -@cindex anonymous face - One way to represent a face is as a property list of attributes, -like @code{(:foreground "red" :weight bold)}. Such a list is called -an @dfn{anonymous face}. For example, you can assign an anonymous -face as the value of the @code{face} text property, and Emacs will -display the underlying text with the specified attributes. -@xref{Special Properties}. - -@cindex face name - More commonly, a face is referred to via a @dfn{face name}: a Lisp -symbol associated with a set of face attributes@footnote{For backward -compatibility, you can also use a string to specify a face name; that -is equivalent to a Lisp symbol with the same name.}. Named faces are -defined using the @code{defface} macro (@pxref{Defining Faces}). -Emacs comes with several standard named faces (@pxref{Basic Faces}). - - Many parts of Emacs required named faces, and do not accept -anonymous faces. These include the functions documented in -@ref{Attribute Functions}, and the variable @code{font-lock-keywords} -(@pxref{Search-based Fontification}). Unless otherwise stated, we -will use the term @dfn{face} to refer only to named faces. - -@defun facep object -This function returns a non-@code{nil} value if @var{object} is a -named face: a Lisp symbol or string which serves as a face name. -Otherwise, it returns @code{nil}. -@end defun - -@menu -* Face Attributes:: What is in a face? -* Defining Faces:: How to define a face. -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Basic Faces:: Faces that are defined by default. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. -@end menu - -@node Face Attributes -@subsection Face Attributes -@cindex face attributes - - @dfn{Face attributes} determine the visual appearance of a face. -The following table lists all the face attributes, their possible -values, and their effects. - - Apart from the values given below, each face attribute can have the -value @code{unspecified}. This special value means that the face -doesn't specify that attribute directly. An @code{unspecified} -attribute tells Emacs to refer instead to a parent face (see the -description @code{:inherit} attribute below); or, failing that, to an -underlying face (@pxref{Displaying Faces}). The @code{default} face -must specify all attributes. - - Some of these attributes are meaningful only on certain kinds of -displays. If your display cannot handle a certain attribute, the -attribute is ignored. - -@table @code -@item :family -Font family or fontset (a string). @xref{Fonts,,, emacs, The GNU -Emacs Manual}, for more information about font families. The function -@code{font-family-list} (see below) returns a list of available family -names. @xref{Fontsets}, for information about fontsets. - -@item :foundry -The name of the @dfn{font foundry} for the font family specified by -the @code{:family} attribute (a string). @xref{Fonts,,, emacs, The -GNU Emacs Manual}. - -@item :width -Relative character width. This should be one of the symbols -@code{ultra-condensed}, @code{extra-condensed}, @code{condensed}, -@code{semi-condensed}, @code{normal}, @code{semi-expanded}, -@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}. - -@item :height -The height of the font. In the simplest case, this is an integer in -units of 1/10 point. - -The value can also be floating point or a function, which -specifies the height relative to an @dfn{underlying face} -(@pxref{Displaying Faces}). A floating-point value -specifies the amount by which to scale the height of the -underlying face. A function value is called -with one argument, the height of the underlying face, and returns the -height of the new face. If the function is passed an integer -argument, it must return an integer. - -The height of the default face must be specified using an integer; -floating point and function values are not allowed. - -@item :weight -Font weight---one of the symbols (from densest to faintest) -@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold}, -@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, or -@code{ultra-light}. On text terminals which support -variable-brightness text, any weight greater than normal is displayed -as extra bright, and any weight less than normal is displayed as -half-bright. - -@cindex italic text -@item :slant -Font slant---one of the symbols @code{italic}, @code{oblique}, -@code{normal}, @code{reverse-italic}, or @code{reverse-oblique}. On -text terminals that support variable-brightness text, slanted text is -displayed as half-bright. - -@item :foreground -Foreground color, a string. The value can be a system-defined color -name, or a hexadecimal color specification. @xref{Color Names}. On -black-and-white displays, certain shades of gray are implemented by -stipple patterns. - -@item :distant-foreground -Alternative foreground color, a string. This is like @code{:foreground} -but the color is only used as a foreground when the background color is -near to the foreground that would have been used. This is useful for -example when marking text (i.e. the region face). If the text has a foreground -that is visible with the region face, that foreground is used. -If the foreground is near the region face background, -@code{:distant-foreground} is used instead so the text is readable. - -@item :background -Background color, a string. The value can be a system-defined color -name, or a hexadecimal color specification. @xref{Color Names}. - -@cindex underlined text -@item :underline -Whether or not characters should be underlined, and in what -way. The possible values of the @code{:underline} attribute are: - -@table @asis -@item @code{nil} -Don't underline. - -@item @code{t} -Underline with the foreground color of the face. - -@item @var{color} -Underline in color @var{color}, a string specifying a color. - -@item @code{(:color @var{color} :style @var{style})} -@var{color} is either a string, or the symbol @code{foreground-color}, -meaning the foreground color of the face. Omitting the attribute -@code{:color} means to use the foreground color of the face. -@var{style} should be a symbol @code{line} or @code{wave}, meaning to -use a straight or wavy line. Omitting the attribute @code{:style} -means to use a straight line. -@end table - -@cindex overlined text -@item :overline -Whether or not characters should be overlined, and in what color. -If the value is @code{t}, overlining uses the foreground color of the -face. If the value is a string, overlining uses that color. The -value @code{nil} means do not overline. - -@cindex strike-through text -@item :strike-through -Whether or not characters should be strike-through, and in what -color. The value is used like that of @code{:overline}. - -@cindex 2D box -@cindex 3D box -@item :box -Whether or not a box should be drawn around characters, its color, the -width of the box lines, and 3D appearance. Here are the possible -values of the @code{:box} attribute, and what they mean: - -@table @asis -@item @code{nil} -Don't draw a box. - -@item @code{t} -Draw a box with lines of width 1, in the foreground color. - -@item @var{color} -Draw a box with lines of width 1, in color @var{color}. - -@item @code{(:line-width @var{width} :color @var{color} :style @var{style})} -This way you can explicitly specify all aspects of the box. The value -@var{width} specifies the width of the lines to draw; it defaults to -1. A negative width @var{-n} means to draw a line of width @var{n} -that occupies the space of the underlying text, thus avoiding any -increase in the character height or width. - -The value @var{color} specifies the color to draw with. The default is -the foreground color of the face for simple boxes, and the background -color of the face for 3D boxes. - -The value @var{style} specifies whether to draw a 3D box. If it is -@code{released-button}, the box looks like a 3D button that is not being -pressed. If it is @code{pressed-button}, the box looks like a 3D button -that is being pressed. If it is @code{nil} or omitted, a plain 2D box -is used. -@end table - -@item :inverse-video -Whether or not characters should be displayed in inverse video. The -value should be @code{t} (yes) or @code{nil} (no). - -@item :stipple -The background stipple, a bitmap. - -The value can be a string; that should be the name of a file containing -external-format X bitmap data. The file is found in the directories -listed in the variable @code{x-bitmap-file-path}. - -Alternatively, the value can specify the bitmap directly, with a list -of the form @code{(@var{width} @var{height} @var{data})}. Here, -@var{width} and @var{height} specify the size in pixels, and -@var{data} is a string containing the raw bits of the bitmap, row by -row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes -in the string (which should be a unibyte string for best results). -This means that each row always occupies at least one whole byte. - -If the value is @code{nil}, that means use no stipple pattern. - -Normally you do not need to set the stipple attribute, because it is -used automatically to handle certain shades of gray. - -@item :font -The font used to display the face. Its value should be a font object. -@xref{Low-Level Font}, for information about font objects, font specs, -and font entities. - -When specifying this attribute using @code{set-face-attribute} -(@pxref{Attribute Functions}), you may also supply a font spec, a font -entity, or a string. Emacs converts such values to an appropriate -font object, and stores that font object as the actual attribute -value. If you specify a string, the contents of the string should be -a font name (@pxref{Fonts,,, emacs, The GNU Emacs Manual}); if the -font name is an XLFD containing wildcards, Emacs chooses the first -font matching those wildcards. Specifying this attribute also changes -the values of the @code{:family}, @code{:foundry}, @code{:width}, -@code{:height}, @code{:weight}, and @code{:slant} attributes. - -@cindex inheritance, for faces -@item :inherit -The name of a face from which to inherit attributes, or a list of face -names. Attributes from inherited faces are merged into the face like -an underlying face would be, with higher priority than underlying -faces (@pxref{Displaying Faces}). If a list of faces is used, -attributes from faces earlier in the list override those from later -faces. -@end table - -@defun font-family-list &optional frame -This function returns a list of available font family names. The -optional argument @var{frame} specifies the frame on which the text is -to be displayed; if it is @code{nil}, the selected frame is used. -@end defun - -@defopt underline-minimum-offset -This variable specifies the minimum distance between the baseline and -the underline, in pixels, when displaying underlined text. -@end defopt - -@defopt x-bitmap-file-path -This variable specifies a list of directories for searching -for bitmap files, for the @code{:stipple} attribute. -@end defopt - -@defun bitmap-spec-p object -This returns @code{t} if @var{object} is a valid bitmap specification, -suitable for use with @code{:stipple} (see above). It returns -@code{nil} otherwise. -@end defun - -@node Defining Faces -@subsection Defining Faces - -@cindex face spec - The usual way to define a face is through the @code{defface} macro. -This macro associates a face name (a symbol) with a default @dfn{face -spec}. A face spec is a construct which specifies what attributes a -face should have on any given terminal; for example, a face spec might -specify one foreground color on high-color terminals, and a different -foreground color on low-color terminals. - - People are sometimes tempted to create a variable whose value is a -face name. In the vast majority of cases, this is not necessary; the -usual procedure is to define a face with @code{defface}, and then use -its name directly. - -@defmac defface face spec doc [keyword value]@dots{} -This macro declares @var{face} as a named face whose default face spec -is given by @var{spec}. You should not quote the symbol @var{face}, -and it should not end in @samp{-face} (that would be redundant). The -argument @var{doc} is a documentation string for the face. The -additional @var{keyword} arguments have the same meanings as in -@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}). - -If @var{face} already has a default face spec, this macro does -nothing. - -The default face spec determines @var{face}'s appearance when no -customizations are in effect (@pxref{Customization}). If @var{face} -has already been customized (via Custom themes or via customizations -read from the init file), its appearance is determined by the custom -face spec(s), which override the default face spec @var{spec}. -However, if the customizations are subsequently removed, the -appearance of @var{face} will again be determined by its default face -spec. - -As an exception, if you evaluate a @code{defface} form with -@kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature -of @code{eval-defun} overrides any custom face specs on the face, -causing the face to reflect exactly what the @code{defface} says. - -The @var{spec} argument is a @dfn{face spec}, which states how the -face should appear on different kinds of terminals. It should be an -alist whose elements each have the form - -@example -(@var{display} . @var{plist}) -@end example - -@noindent -@var{display} specifies a class of terminals (see below). @var{plist} -is a property list of face attributes and their values, specifying how -the face appears on such terminals. For backward compatibility, you -can also write an element as @code{(@var{display} @var{plist})}. - -The @var{display} part of an element of @var{spec} determines which -terminals the element matches. If more than one element of @var{spec} -matches a given terminal, the first element that matches is the one -used for that terminal. There are three possibilities for -@var{display}: - -@table @asis -@item @code{default} -This element of @var{spec} doesn't match any terminal; instead, it -specifies defaults that apply to all terminals. This element, if -used, must be the first element of @var{spec}. Each of the following -elements can override any or all of these defaults. - -@item @code{t} -This element of @var{spec} matches all terminals. Therefore, any -subsequent elements of @var{spec} are never used. Normally @code{t} -is used in the last (or only) element of @var{spec}. - -@item a list -If @var{display} is a list, each element should have the form -@code{(@var{characteristic} @var{value}@dots{})}. Here -@var{characteristic} specifies a way of classifying terminals, and the -@var{value}s are possible classifications which @var{display} should -apply to. Here are the possible values of @var{characteristic}: - -@table @code -@item type -The kind of window system the terminal uses---either @code{graphic} -(any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS -console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a -non-graphics-capable display). @xref{Window Systems, window-system}. - -@item class -What kinds of colors the terminal supports---either @code{color}, -@code{grayscale}, or @code{mono}. - -@item background -The kind of background---either @code{light} or @code{dark}. - -@item min-colors -An integer that represents the minimum number of colors the terminal -should support. This matches a terminal if its -@code{display-color-cells} value is at least the specified integer. - -@item supports -Whether or not the terminal can display the face attributes given in -@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face -Attribute Testing}, for more information on exactly how this testing -is done. -@end table - -If an element of @var{display} specifies more than one @var{value} for -a given @var{characteristic}, any of those values is acceptable. If -@var{display} has more than one element, each element should specify a -different @var{characteristic}; then @emph{each} characteristic of the -terminal must match one of the @var{value}s specified for it in -@var{display}. -@end table -@end defmac - - For example, here's the definition of the standard face -@code{highlight}: - -@example -(defface highlight - '((((class color) (min-colors 88) (background light)) - :background "darkseagreen2") - (((class color) (min-colors 88) (background dark)) - :background "darkolivegreen") - (((class color) (min-colors 16) (background light)) - :background "darkseagreen2") - (((class color) (min-colors 16) (background dark)) - :background "darkolivegreen") - (((class color) (min-colors 8)) - :background "green" :foreground "black") - (t :inverse-video t)) - "Basic face for highlighting." - :group 'basic-faces) -@end example - - Internally, Emacs stores each face's default spec in its -@code{face-defface-spec} symbol property (@pxref{Symbol Properties}). -The @code{saved-face} property stores any face spec saved by the user -using the customization buffer; the @code{customized-face} property -stores the face spec customized for the current session, but not -saved; and the @code{theme-face} property stores an alist associating -the active customization settings and Custom themes with the face -specs for that face. The face's documentation string is stored in the -@code{face-documentation} property. - - Normally, a face is declared just once, using @code{defface}, and -any further changes to its appearance are applied using the Customize -framework (e.g., via the Customize user interface or via the -@code{custom-set-faces} function; @pxref{Applying Customizations}), or -by face remapping (@pxref{Face Remapping}). In the rare event that -you need to change a face spec directly from Lisp, you can use the -@code{face-spec-set} function. - -@defun face-spec-set face spec &optional spec-type -This function applies @var{spec} as a face spec for @code{face}. -@var{spec} should be a face spec, as described in the above -documentation for @code{defface}. - -This function also defines @var{face} as a valid face name if it is -not already one, and (re)calculates its attributes on existing frames. - -@cindex override spec @r{(for a face)} -The argument @var{spec-type} determines which spec to set. If it is -@code{nil} or @code{face-override-spec}, this function sets the -@dfn{override spec}, which overrides over all other face specs on -@var{face}. If it is @code{customized-face} or @code{saved-face}, -this function sets the customized spec or the saved custom spec. If -it is @code{face-defface-spec}, this function sets the default face -spec (the same one set by @code{defface}). If it is @code{reset}, -this function clears out all customization specs and override specs -from @var{face} (in this case, the value of @var{spec} is ignored). -Any other value of @var{spec-type} is reserved for internal use. -@end defun - -@node Attribute Functions -@subsection Face Attribute Functions - - This section describes functions for directly accessing and -modifying the attributes of a named face. - -@defun face-attribute face attribute &optional frame inherit -This function returns the value of the @var{attribute} attribute for -@var{face} on @var{frame}. - -If @var{frame} is @code{nil}, that means the selected frame -(@pxref{Input Focus}). If @var{frame} is @code{t}, this function -returns the value of the specified attribute for newly-created frames -(this is normally @code{unspecified}, unless you have specified some -value using @code{set-face-attribute}; see below). - -If @var{inherit} is @code{nil}, only attributes directly defined by -@var{face} are considered, so the return value may be -@code{unspecified}, or a relative value. If @var{inherit} is -non-@code{nil}, @var{face}'s definition of @var{attribute} is merged -with the faces specified by its @code{:inherit} attribute; however the -return value may still be @code{unspecified} or relative. If -@var{inherit} is a face or a list of faces, then the result is further -merged with that face (or faces), until it becomes specified and -absolute. - -To ensure that the return value is always specified and absolute, use -a value of @code{default} for @var{inherit}; this will resolve any -unspecified or relative values by merging with the @code{default} face -(which is always completely specified). - -For example, - -@example -(face-attribute 'bold :weight) - @result{} bold -@end example -@end defun - -@c FIXME: Add an index for "relative face attribute", maybe here? --xfq -@defun face-attribute-relative-p attribute value -This function returns non-@code{nil} if @var{value}, when used as the -value of the face attribute @var{attribute}, is relative. This means -it would modify, rather than completely override, any value that comes -from a subsequent face in the face list or that is inherited from -another face. - -@code{unspecified} is a relative value for all attributes. For -@code{:height}, floating point and function values are also relative. - -For example: - -@example -(face-attribute-relative-p :height 2.0) - @result{} t -@end example -@end defun - -@defun face-all-attributes face &optional frame -This function returns an alist of attributes of @var{face}. The -elements of the result are name-value pairs of the form -@w{@code{(@var{attr-name} . @var{attr-value})}}. Optional argument -@var{frame} specifies the frame whose definition of @var{face} to -return; if omitted or @code{nil}, the returned value describes the -default attributes of @var{face} for newly created frames. -@end defun - -@defun merge-face-attribute attribute value1 value2 -If @var{value1} is a relative value for the face attribute -@var{attribute}, returns it merged with the underlying value -@var{value2}; otherwise, if @var{value1} is an absolute value for the -face attribute @var{attribute}, returns @var{value1} unchanged. -@end defun - - Normally, Emacs uses the face specs of each face to automatically -calculate its attributes on each frame (@pxref{Defining Faces}). The -function @code{set-face-attribute} can override this calculation by -directly assigning attributes to a face, either on a specific frame or -for all frames. This function is mostly intended for internal usage. - -@defun set-face-attribute face frame &rest arguments -This function sets one or more attributes of @var{face} for -@var{frame}. The attributes specifies in this way override the face -spec(s) belonging to @var{face}. - -The extra arguments @var{arguments} specify the attributes to set, and -the values for them. They should consist of alternating attribute -names (such as @code{:family} or @code{:underline}) and values. Thus, - -@example -(set-face-attribute 'foo nil :weight 'bold :slant 'italic) -@end example - -@noindent -sets the attribute @code{:weight} to @code{bold} and the attribute -@code{:slant} to @code{italic}. - - -If @var{frame} is @code{t}, this function sets the default attributes -for newly created frames. If @var{frame} is @code{nil}, this function -sets the attributes for all existing frames, as well as for newly -created frames. -@end defun - - The following commands and functions mostly provide compatibility -with old versions of Emacs. They work by calling -@code{set-face-attribute}. Values of @code{t} and @code{nil} for -their @var{frame} argument are handled just like -@code{set-face-attribute} and @code{face-attribute}. The commands -read their arguments using the minibuffer, if called interactively. - -@deffn Command set-face-foreground face color &optional frame -@deffnx Command set-face-background face color &optional frame -These set the @code{:foreground} attribute (or @code{:background} -attribute, respectively) of @var{face} to @var{color}. -@end deffn - -@deffn Command set-face-stipple face pattern &optional frame -This sets the @code{:stipple} attribute of @var{face} to -@var{pattern}. -@end deffn - -@deffn Command set-face-font face font &optional frame -This sets the @code{:font} attribute of @var{face} to @var{font}. -@end deffn - -@defun set-face-bold face bold-p &optional frame -This sets the @code{:weight} attribute of @var{face} to @var{normal} -if @var{bold-p} is @code{nil}, and to @var{bold} otherwise. -@end defun - -@defun set-face-italic face italic-p &optional frame -This sets the @code{:slant} attribute of @var{face} to @var{normal} if -@var{italic-p} is @code{nil}, and to @var{italic} otherwise. -@end defun - -@defun set-face-underline face underline &optional frame -This sets the @code{:underline} attribute of @var{face} to -@var{underline}. -@end defun - -@defun set-face-inverse-video face inverse-video-p &optional frame -This sets the @code{:inverse-video} attribute of @var{face} to -@var{inverse-video-p}. -@end defun - -@deffn Command invert-face face &optional frame -This swaps the foreground and background colors of face @var{face}. -@end deffn - - The following functions examine the attributes of a face. They -mostly provide compatibility with old versions of Emacs. If you don't -specify @var{frame}, they refer to the selected frame; @code{t} refers -to the default data for new frames. They return @code{unspecified} if -the face doesn't define any value for that attribute. If -@var{inherit} is @code{nil}, only an attribute directly defined by the -face is returned. If @var{inherit} is non-@code{nil}, any faces -specified by its @code{:inherit} attribute are considered as well, and -if @var{inherit} is a face or a list of faces, then they are also -considered, until a specified attribute is found. To ensure that the -return value is always specified, use a value of @code{default} for -@var{inherit}. - -@defun face-font face &optional frame -This function returns the name of the font of face @var{face}. -@end defun - -@defun face-foreground face &optional frame inherit -@defunx face-background face &optional frame inherit -These functions return the foreground color (or background color, -respectively) of face @var{face}, as a string. -@end defun - -@defun face-stipple face &optional frame inherit -This function returns the name of the background stipple pattern of face -@var{face}, or @code{nil} if it doesn't have one. -@end defun - -@defun face-bold-p face &optional frame inherit -This function returns a non-@code{nil} value if the @code{:weight} -attribute of @var{face} is bolder than normal (i.e., one of -@code{semi-bold}, @code{bold}, @code{extra-bold}, or -@code{ultra-bold}). Otherwise, it returns @code{nil}. -@end defun - -@defun face-italic-p face &optional frame inherit -This function returns a non-@code{nil} value if the @code{:slant} -attribute of @var{face} is @code{italic} or @code{oblique}, and -@code{nil} otherwise. -@end defun - -@defun face-underline-p face &optional frame inherit -This function returns non-@code{nil} if face @var{face} specifies -a non-@code{nil} @code{:underline} attribute. -@end defun - -@defun face-inverse-video-p face &optional frame inherit -This function returns non-@code{nil} if face @var{face} specifies -a non-@code{nil} @code{:inverse-video} attribute. -@end defun - -@node Displaying Faces -@subsection Displaying Faces - - When Emacs displays a given piece of text, the visual appearance of -the text may be determined by faces drawn from different sources. If -these various sources together specify more than one face for a -particular character, Emacs merges the attributes of the various -faces. Here is the order in which Emacs merges the faces, from -highest to lowest priority: - -@itemize @bullet -@item -If the text consists of a special glyph, the glyph can specify a -particular face. @xref{Glyphs}. - -@item -If the text lies within an active region, Emacs highlights it using -the @code{region} face. @xref{Standard Faces,,, emacs, The GNU Emacs -Manual}. - -@item -If the text lies within an overlay with a non-@code{nil} @code{face} -property, Emacs applies the face(s) specified by that property. If -the overlay has a @code{mouse-face} property and the mouse is ``near -enough'' to the overlay, Emacs applies the face or face attributes -specified by the @code{mouse-face} property instead. @xref{Overlay -Properties}. - -When multiple overlays cover one character, an overlay with higher -priority overrides those with lower priority. @xref{Overlays}. - -@item -If the text contains a @code{face} or @code{mouse-face} property, -Emacs applies the specified faces and face attributes. @xref{Special -Properties}. (This is how Font Lock mode faces are applied. -@xref{Font Lock Mode}.) - -@item -If the text lies within the mode line of the selected window, Emacs -applies the @code{mode-line} face. For the mode line of a -non-selected window, Emacs applies the @code{mode-line-inactive} face. -For a header line, Emacs applies the @code{header-line} face. - -@item -If any given attribute has not been specified during the preceding -steps, Emacs applies the attribute of the @code{default} face. -@end itemize - - At each stage, if a face has a valid @code{:inherit} attribute, -Emacs treats any attribute with an @code{unspecified} value as having -the corresponding value drawn from the parent face(s). @pxref{Face -Attributes}. Note that the parent face(s) may also leave the -attribute unspecified; in that case, the attribute remains unspecified -at the next level of face merging. - -@node Face Remapping -@subsection Face Remapping - - The variable @code{face-remapping-alist} is used for buffer-local or -global changes in the appearance of a face. For instance, it is used -to implement the @code{text-scale-adjust} command (@pxref{Text -Scale,,, emacs, The GNU Emacs Manual}). - -@defvar face-remapping-alist -The value of this variable is an alist whose elements have the form -@code{(@var{face} . @var{remapping})}. This causes Emacs to display -any text having the face @var{face} with @var{remapping}, rather than -the ordinary definition of @var{face}. - -@var{remapping} may be any face spec suitable for a @code{face} text -property: either a face (i.e., a face name or a property list of -attribute/value pairs), or a list of faces. For details, see the -description of the @code{face} text property in @ref{Special -Properties}. @var{remapping} serves as the complete specification for -the remapped face---it replaces the normal definition of @var{face}, -instead of modifying it. - -If @code{face-remapping-alist} is buffer-local, its local value takes -effect only within that buffer. - -Note: face remapping is non-recursive. If @var{remapping} references -the same face name @var{face}, either directly or via the -@code{:inherit} attribute of some other face in @var{remapping}, that -reference uses the normal definition of @var{face}. For instance, if -the @code{mode-line} face is remapped using this entry in -@code{face-remapping-alist}: - -@example -(mode-line italic mode-line) -@end example - -@noindent -then the new definition of the @code{mode-line} face inherits from the -@code{italic} face, and the @emph{normal} (non-remapped) definition of -@code{mode-line} face. -@end defvar - -@cindex relative remapping, faces -@cindex base remapping, faces - The following functions implement a higher-level interface to -@code{face-remapping-alist}. Most Lisp code should use these -functions instead of setting @code{face-remapping-alist} directly, to -avoid trampling on remappings applied elsewhere. These functions are -intended for buffer-local remappings, so they all make -@code{face-remapping-alist} buffer-local as a side-effect. They manage -@code{face-remapping-alist} entries of the form - -@example - (@var{face} @var{relative-spec-1} @var{relative-spec-2} @var{...} @var{base-spec}) -@end example - -@noindent -where, as explained above, each of the @var{relative-spec-N} and -@var{base-spec} is either a face name, or a property list of -attribute/value pairs. Each of the @dfn{relative remapping} entries, -@var{relative-spec-N}, is managed by the -@code{face-remap-add-relative} and @code{face-remap-remove-relative} -functions; these are intended for simple modifications like changing -the text size. The @dfn{base remapping} entry, @var{base-spec}, has -the lowest priority and is managed by the @code{face-remap-set-base} -and @code{face-remap-reset-base} functions; it is intended for major -modes to remap faces in the buffers they control. - -@defun face-remap-add-relative face &rest specs -This function adds the face spec in @var{specs} as relative -remappings for face @var{face} in the current buffer. The remaining -arguments, @var{specs}, should form either a list of face names, or a -property list of attribute/value pairs. - -The return value is a Lisp object that serves as a ``cookie''; you can -pass this object as an argument to @code{face-remap-remove-relative} -if you need to remove the remapping later. - -@example -;; Remap the `escape-glyph' face into a combination -;; of the `highlight' and `italic' faces: -(face-remap-add-relative 'escape-glyph 'highlight 'italic) - -;; Increase the size of the `default' face by 50%: -(face-remap-add-relative 'default :height 1.5) -@end example -@end defun - -@defun face-remap-remove-relative cookie -This function removes a relative remapping previously added by -@code{face-remap-add-relative}. @var{cookie} should be the Lisp -object returned by @code{face-remap-add-relative} when the remapping -was added. -@end defun - -@defun face-remap-set-base face &rest specs -This function sets the base remapping of @var{face} in the current -buffer to @var{specs}. If @var{specs} is empty, the default base -remapping is restored, similar to calling @code{face-remap-reset-base} -(see below); note that this is different from @var{specs} containing a -single value @code{nil}, which has the opposite result (the global -definition of @var{face} is ignored). - -This overwrites the default @var{base-spec}, which inherits the global -face definition, so it is up to the caller to add such inheritance if -so desired. -@end defun - -@defun face-remap-reset-base face -This function sets the base remapping of @var{face} to its default -value, which inherits from @var{face}'s global definition. -@end defun - -@node Face Functions -@subsection Functions for Working with Faces - - Here are additional functions for creating and working with faces. - -@defun face-list -This function returns a list of all defined face names. -@end defun - -@defun face-id face -This function returns the @dfn{face number} of face @var{face}. This -is a number that uniquely identifies a face at low levels within -Emacs. It is seldom necessary to refer to a face by its face number. -@end defun - -@defun face-documentation face -This function returns the documentation string of face @var{face}, or -@code{nil} if none was specified for it. -@end defun - -@defun face-equal face1 face2 &optional frame -This returns @code{t} if the faces @var{face1} and @var{face2} have the -same attributes for display. -@end defun - -@defun face-differs-from-default-p face &optional frame -This returns non-@code{nil} if the face @var{face} displays -differently from the default face. -@end defun - -@cindex face alias -@cindex alias, for faces -A @dfn{face alias} provides an equivalent name for a face. You can -define a face alias by giving the alias symbol the @code{face-alias} -property, with a value of the target face name. The following example -makes @code{modeline} an alias for the @code{mode-line} face. - -@example -(put 'modeline 'face-alias 'mode-line) -@end example - -@defmac define-obsolete-face-alias obsolete-face current-face when -This macro defines @code{obsolete-face} as an alias for -@var{current-face}, and also marks it as obsolete, indicating that it -may be removed in future. @var{when} should be a string indicating -when @code{obsolete-face} was made obsolete (usually a version number -string). -@end defmac - -@node Auto Faces -@subsection Automatic Face Assignment -@cindex automatic face assignment -@cindex faces, automatic choice - - This hook is used for automatically assigning faces to text in the -buffer. It is part of the implementation of Jit-Lock mode, used by -Font-Lock. - -@defvar fontification-functions -This variable holds a list of functions that are called by Emacs -redisplay as needed, just before doing redisplay. They are called even -when Font Lock Mode isn't enabled. When Font Lock Mode is enabled, this -variable usually holds just one function, @code{jit-lock-function}. - -The functions are called in the order listed, with one argument, a -buffer position @var{pos}. Collectively they should attempt to assign -faces to the text in the current buffer starting at @var{pos}. - -The functions should record the faces they assign by setting the -@code{face} property. They should also add a non-@code{nil} -@code{fontified} property to all the text they have assigned faces to. -That property tells redisplay that faces have been assigned to that text -already. - -It is probably a good idea for the functions to do nothing if the -character after @var{pos} already has a non-@code{nil} @code{fontified} -property, but this is not required. If one function overrides the -assignments made by a previous one, the properties after the last -function finishes are the ones that really matter. - -For efficiency, we recommend writing these functions so that they -usually assign faces to around 400 to 600 characters at each call. -@end defvar - -@node Basic Faces -@subsection Basic Faces - -If your Emacs Lisp program needs to assign some faces to text, it is -often a good idea to use certain existing faces or inherit from them, -rather than defining entirely new faces. This way, if other users -have customized the basic faces to give Emacs a certain look, your -program will ``fit in'' without additional customization. - - Some of the basic faces defined in Emacs are listed below. In -addition to these, you might want to make use of the Font Lock faces -for syntactic highlighting, if highlighting is not already handled by -Font Lock mode, or if some Font Lock faces are not in use. -@xref{Faces for Font Lock}. - -@table @code -@item default -The default face, whose attributes are all specified. All other faces -implicitly inherit from it: any unspecified attribute defaults to the -attribute on this face (@pxref{Face Attributes}). - -@item bold -@itemx italic -@itemx bold-italic -@itemx underline -@itemx fixed-pitch -@itemx variable-pitch -These have the attributes indicated by their names (e.g., @code{bold} -has a bold @code{:weight} attribute), with all other attributes -unspecified (and so given by @code{default}). - -@item shadow -For ``dimmed out'' text. For example, it is used for the ignored -part of a filename in the minibuffer (@pxref{Minibuffer File,, -Minibuffers for File Names, emacs, The GNU Emacs Manual}). - -@item link -@itemx link-visited -For clickable text buttons that send the user to a different -buffer or ``location''. - -@item highlight -For stretches of text that should temporarily stand out. For example, -it is commonly assigned to the @code{mouse-face} property for cursor -highlighting (@pxref{Special Properties}). - -@item match -For text matching a search command. - -@item error -@itemx warning -@itemx success -For text concerning errors, warnings, or successes. For example, -these are used for messages in @file{*Compilation*} buffers. -@end table - -@node Font Selection -@subsection Font Selection -@cindex font selection -@cindex selecting a font - - Before Emacs can draw a character on a graphical display, it must -select a @dfn{font} for that character@footnote{In this context, the -term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock -Mode}).}. @xref{Fonts,,, emacs, The GNU Emacs Manual}. Normally, -Emacs automatically chooses a font based on the faces assigned to that -character---specifically, the face attributes @code{:family}, -@code{:weight}, @code{:slant}, and @code{:width} (@pxref{Face -Attributes}). The choice of font also depends on the character to be -displayed; some fonts can only display a limited set of characters. -If no available font exactly fits the requirements, Emacs looks for -the @dfn{closest matching font}. The variables in this section -control how Emacs makes this selection. - -@defopt face-font-family-alternatives -If a given family is specified but does not exist, this variable -specifies alternative font families to try. Each element should have -this form: - -@example -(@var{family} @var{alternate-families}@dots{}) -@end example - -If @var{family} is specified but not available, Emacs will try the other -families given in @var{alternate-families}, one by one, until it finds a -family that does exist. -@end defopt - -@defopt face-font-selection-order -If there is no font that exactly matches all desired face attributes -(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}), -this variable specifies the order in which these attributes should be -considered when selecting the closest matching font. The value should -be a list containing those four attribute symbols, in order of -decreasing importance. The default is @code{(:width :height :weight -:slant)}. - -Font selection first finds the best available matches for the first -attribute in the list; then, among the fonts which are best in that -way, it searches for the best matches in the second attribute, and so -on. - -The attributes @code{:weight} and @code{:width} have symbolic values in -a range centered around @code{normal}. Matches that are more extreme -(farther from @code{normal}) are somewhat preferred to matches that are -less extreme (closer to @code{normal}); this is designed to ensure that -non-normal faces contrast with normal ones, whenever possible. - -One example of a case where this variable makes a difference is when the -default font has no italic equivalent. With the default ordering, the -@code{italic} face will use a non-italic font that is similar to the -default one. But if you put @code{:slant} before @code{:height}, the -@code{italic} face will use an italic font, even if its height is not -quite right. -@end defopt - -@defopt face-font-registry-alternatives -This variable lets you specify alternative font registries to try, if a -given registry is specified and doesn't exist. Each element should have -this form: - -@example -(@var{registry} @var{alternate-registries}@dots{}) -@end example - -If @var{registry} is specified but not available, Emacs will try the -other registries given in @var{alternate-registries}, one by one, -until it finds a registry that does exist. -@end defopt - -@cindex scalable fonts - Emacs can make use of scalable fonts, but by default it does not use -them. - -@defopt scalable-fonts-allowed -This variable controls which scalable fonts to use. A value of -@code{nil}, the default, means do not use scalable fonts. @code{t} -means to use any scalable font that seems appropriate for the text. - -Otherwise, the value must be a list of regular expressions. Then a -scalable font is enabled for use if its name matches any regular -expression in the list. For example, - -@example -(setq scalable-fonts-allowed '("iso10646-1$")) -@end example - -@noindent -allows the use of scalable fonts with registry @code{iso10646-1}. -@end defopt - -@defvar face-font-rescale-alist -This variable specifies scaling for certain faces. Its value should -be a list of elements of the form - -@example -(@var{fontname-regexp} . @var{scale-factor}) -@end example - -If @var{fontname-regexp} matches the font name that is about to be -used, this says to choose a larger similar font according to the -factor @var{scale-factor}. You would use this feature to normalize -the font size if certain fonts are bigger or smaller than their -nominal heights and widths would suggest. -@end defvar - -@node Font Lookup -@subsection Looking Up Fonts - -@defun x-list-fonts name &optional reference-face frame maximum width -This function returns a list of available font names that match -@var{name}. @var{name} should be a string containing a font name in -either the Fontconfig, GTK, or XLFD format (@pxref{Fonts,,, emacs, The -GNU Emacs Manual}). Within an XLFD string, wildcard characters may be -used: the @samp{*} character matches any substring, and the @samp{?} -character matches any single character. Case is ignored when matching -font names. - -If the optional arguments @var{reference-face} and @var{frame} are -specified, the returned list includes only fonts that are the same -size as @var{reference-face} (a face name) currently is on the frame -@var{frame}. - -The optional argument @var{maximum} sets a limit on how many fonts to -return. If it is non-@code{nil}, then the return value is truncated -after the first @var{maximum} matching fonts. Specifying a small -value for @var{maximum} can make this function much faster, in cases -where many fonts match the pattern. - -The optional argument @var{width} specifies a desired font width. If -it is non-@code{nil}, the function only returns those fonts whose -characters are (on average) @var{width} times as wide as -@var{reference-face}. -@end defun - -@defun x-family-fonts &optional family frame -This function returns a list describing the available fonts for family -@var{family} on @var{frame}. If @var{family} is omitted or @code{nil}, -this list applies to all families, and therefore, it contains all -available fonts. Otherwise, @var{family} must be a string; it may -contain the wildcards @samp{?} and @samp{*}. - -The list describes the display that @var{frame} is on; if @var{frame} is -omitted or @code{nil}, it applies to the selected frame's display -(@pxref{Input Focus}). - -Each element in the list is a vector of the following form: - -@example -[@var{family} @var{width} @var{point-size} @var{weight} @var{slant} - @var{fixed-p} @var{full} @var{registry-and-encoding}] -@end example - -The first five elements correspond to face attributes; if you -specify these attributes for a face, it will use this font. - -The last three elements give additional information about the font. -@var{fixed-p} is non-@code{nil} if the font is fixed-pitch. -@var{full} is the full name of the font, and -@var{registry-and-encoding} is a string giving the registry and -encoding of the font. -@end defun - -@node Fontsets -@subsection Fontsets - - A @dfn{fontset} is a list of fonts, each assigned to a range of -character codes. An individual font cannot display the whole range of -characters that Emacs supports, but a fontset can. Fontsets have names, -just as fonts do, and you can use a fontset name in place of a font name -when you specify the ``font'' for a frame or a face. Here is -information about defining a fontset under Lisp program control. - -@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror -This function defines a new fontset according to the specification -string @var{fontset-spec}. The string should have this format: - -@smallexample -@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}} -@end smallexample - -@noindent -Whitespace characters before and after the commas are ignored. - -The first part of the string, @var{fontpattern}, should have the form of -a standard X font name, except that the last two fields should be -@samp{fontset-@var{alias}}. - -The new fontset has two names, one long and one short. The long name is -@var{fontpattern} in its entirety. The short name is -@samp{fontset-@var{alias}}. You can refer to the fontset by either -name. If a fontset with the same name already exists, an error is -signaled, unless @var{noerror} is non-@code{nil}, in which case this -function does nothing. - -If optional argument @var{style-variant-p} is non-@code{nil}, that says -to create bold, italic and bold-italic variants of the fontset as well. -These variant fontsets do not have a short name, only a long one, which -is made by altering @var{fontpattern} to indicate the bold and/or italic -status. - -The specification string also says which fonts to use in the fontset. -See below for the details. -@end defun - - The construct @samp{@var{charset}:@var{font}} specifies which font to -use (in this fontset) for one particular character set. Here, -@var{charset} is the name of a character set, and @var{font} is the font -to use for that character set. You can use this construct any number of -times in the specification string. - - For the remaining character sets, those that you don't specify -explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces -@samp{fontset-@var{alias}} with a value that names one character set. -For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced -with @samp{ISO8859-1}. - - In addition, when several consecutive fields are wildcards, Emacs -collapses them into a single wildcard. This is to prevent use of -auto-scaled fonts. Fonts made by scaling larger fonts are not usable -for editing, and scaling a smaller font is not useful because it is -better to use the smaller font in its own size, which Emacs does. - - Thus if @var{fontpattern} is this, - -@example --*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 -@end example - -@noindent -the font specification for @acronym{ASCII} characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-ISO8859-1 -@end example - -@noindent -and the font specification for Chinese GB2312 characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-gb2312*-* -@end example - - You may not have any Chinese font matching the above font -specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In -such a case, @samp{Fontset-@var{n}} can be specified as below: - -@smallexample -Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ - chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* -@end smallexample - -@noindent -Then, the font specifications for all but Chinese GB2312 characters have -@samp{fixed} in the @var{family} field, and the font specification for -Chinese GB2312 characters has a wild card @samp{*} in the @var{family} -field. - -@defun set-fontset-font name character font-spec &optional frame add -This function modifies the existing fontset @var{name} to use the font -matching with @var{font-spec} for the character @var{character}. - -If @var{name} is @code{nil}, this function modifies the fontset of the -selected frame or that of @var{frame} if @var{frame} is not -@code{nil}. - -If @var{name} is @code{t}, this function modifies the default -fontset, whose short name is @samp{fontset-default}. - -@var{character} may be a cons; @code{(@var{from} . @var{to})}, where -@var{from} and @var{to} are character codepoints. In that case, use -@var{font-spec} for all characters in the range @var{from} and @var{to} -(inclusive). - -@var{character} may be a charset. In that case, use -@var{font-spec} for all character in the charsets. - -@var{character} may be a script name. In that case, use -@var{font-spec} for all character in the charsets. - -@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})}, -where @var{family} is a family name of a font (possibly including a -foundry name at the head), @var{registry} is a registry name of a font -(possibly including an encoding name at the tail). - -@var{font-spec} may be a font name string. - -The optional argument @var{add}, if non-@code{nil}, specifies how to -add @var{font-spec} to the font specifications previously set. If it -is @code{prepend}, @var{font-spec} is prepended. If it is -@code{append}, @var{font-spec} is appended. By default, -@var{font-spec} overrides the previous settings. - -For instance, this changes the default fontset to use a font of which -family name is @samp{Kochi Gothic} for all characters belonging to -the charset @code{japanese-jisx0208}. - -@smallexample -(set-fontset-font t 'japanese-jisx0208 - (font-spec :family "Kochi Gothic")) -@end smallexample -@end defun - -@defun char-displayable-p char -This function returns @code{t} if Emacs ought to be able to display -@var{char}. More precisely, if the selected frame's fontset has a -font to display the character set that @var{char} belongs to. - -Fontsets can specify a font on a per-character basis; when the fontset -does that, this function's value may not be accurate. -@end defun - -@node Low-Level Font -@subsection Low-Level Font Representation -@cindex font property - - Normally, it is not necessary to manipulate fonts directly. In case -you need to do so, this section explains how. - - In Emacs Lisp, fonts are represented using three different Lisp -object types: @dfn{font objects}, @dfn{font specs}, and @dfn{font -entities}. - -@defun fontp object &optional type -Return @code{t} if @var{object} is a font object, font spec, or font -entity. Otherwise, return @code{nil}. - -The optional argument @var{type}, if non-@code{nil}, determines the -exact type of Lisp object to check for. In that case, @var{type} -should be one of @code{font-object}, @code{font-spec}, or -@code{font-entity}. -@end defun - -@cindex font object - A font object is a Lisp object that represents a font that Emacs has -@dfn{opened}. Font objects cannot be modified in Lisp, but they can -be inspected. - -@defun font-at position &optional window string -Return the font object that is being used to display the character at -position @var{position} in the window @var{window}. If @var{window} -is @code{nil}, it defaults to the selected window. If @var{string} is -@code{nil}, @var{position} specifies a position in the current buffer; -otherwise, @var{string} should be a string, and @var{position} -specifies a position in that string. -@end defun - -@cindex font spec - A font spec is a Lisp object that contains a set of specifications -that can be used to find a font. More than one font may match the -specifications in a font spec. - -@defun font-spec &rest arguments -Return a new font spec using the specifications in @var{arguments}, -which should come in @code{property}-@code{value} pairs. The possible -specifications are as follows: - -@table @code -@item :name -The font name (a string), in either XLFD, Fontconfig, or GTK format. -@xref{Fonts,,, emacs, The GNU Emacs Manual}. - -@item :family -@itemx :foundry -@itemx :weight -@itemx :slant -@itemx :width -These have the same meanings as the face attributes of the same name. -@xref{Face Attributes}. - -@item :size -The font size---either a non-negative integer that specifies the pixel -size, or a floating-point number that specifies the point size. - -@item :adstyle -Additional typographic style information for the font, such as -@samp{sans}. The value should be a string or a symbol. - -@cindex font registry -@item :registry -The charset registry and encoding of the font, such as -@samp{iso8859-1}. The value should be a string or a symbol. - -@item :script -The script that the font must support (a symbol). - -@item :otf -@cindex OpenType font -The font must be an OpenType font that supports these OpenType -features, provided Emacs is compiled with support for @samp{libotf} (a -library for performing complex text layout in certain scripts). The -value must be a list of the form - -@smallexample -@code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})} -@end smallexample - -where @var{script-tag} is the OpenType script tag symbol; -@var{langsys-tag} is the OpenType language system tag symbol, or -@code{nil} to use the default language system; @code{gsub} is a list -of OpenType GSUB feature tag symbols, or @code{nil} if none is -required; and @code{gpos} is a list of OpenType GPOS feature tag -symbols, or @code{nil} if none is required. If @code{gsub} or -@code{gpos} is a list, a @code{nil} element in that list means that -the font must not match any of the remaining tag symbols. The -@code{gpos} element may be omitted. -@end table -@end defun - -@defun font-put font-spec property value -Set the font property @var{property} in the font-spec @var{font-spec} -to @var{value}. -@end defun - -@cindex font entity - A font entity is a reference to a font that need not be open. Its -properties are intermediate between a font object and a font spec: -like a font object, and unlike a font spec, it refers to a single, -specific font. Unlike a font object, creating a font entity does not -load the contents of that font into computer memory. Emacs may open -multiple font objects of different sizes from a single font entity -referring to a scalable font. - -@defun find-font font-spec &optional frame -This function returns a font entity that best matches the font spec -@var{font-spec} on frame @var{frame}. If @var{frame} is @code{nil}, -it defaults to the selected frame. -@end defun - -@defun list-fonts font-spec &optional frame num prefer -This function returns a list of all font entities that match the font -spec @var{font-spec}. - -The optional argument @var{frame}, if non-@code{nil}, specifies the -frame on which the fonts are to be displayed. The optional argument -@var{num}, if non-@code{nil}, should be an integer that specifies the -maximum length of the returned list. The optional argument -@var{prefer}, if non-@code{nil}, should be another font spec, which is -used to control the order of the returned list; the returned font -entities are sorted in order of decreasing ``closeness'' to that font -spec. -@end defun - - If you call @code{set-face-attribute} and pass a font spec, font -entity, or font name string as the value of the @code{:font} -attribute, Emacs opens the best ``matching'' font that is available -for display. It then stores the corresponding font object as the -actual value of the @code{:font} attribute for that face. - - The following functions can be used to obtain information about a -font. For these functions, the @var{font} argument can be a font -object, a font entity, or a font spec. - -@defun font-get font property -This function returns the value of the font property @var{property} -for @var{font}. - -If @var{font} is a font spec and the font spec does not specify -@var{property}, the return value is @code{nil}. If @var{font} is a -font object or font entity, the value for the @var{:script} property -may be a list of scripts supported by the font. -@end defun - -@defun font-face-attributes font &optional frame -This function returns a list of face attributes corresponding to -@var{font}. The optional argument @var{frame} specifies the frame on -which the font is to be displayed. If it is @code{nil}, the selected -frame is used. The return value has the form - -@smallexample -(:family @var{family} :height @var{height} :weight @var{weight} - :slant @var{slant} :width @var{width}) -@end smallexample - -where the values of @var{family}, @var{height}, @var{weight}, -@var{slant}, and @var{width} are face attribute values. Some of these -key-attribute pairs may be omitted from the list if they are not -specified by @var{font}. -@end defun - -@defun font-xlfd-name font &optional fold-wildcards -This function returns the XLFD (X Logical Font Descriptor), a string, -matching @var{font}. @xref{Fonts,,, emacs, The GNU Emacs Manual}, for -information about XLFDs. If the name is too long for an XLFD (which -can contain at most 255 characters), the function returns @code{nil}. - -If the optional argument @var{fold-wildcards} is non-@code{nil}, -consecutive wildcards in the XLFD are folded into one. -@end defun - -@node Fringes -@section Fringes -@cindex fringes - - On graphical displays, Emacs draws @dfn{fringes} next to each -window: thin vertical strips down the sides which can display bitmaps -indicating truncation, continuation, horizontal scrolling, and so on. - -@menu -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. -@end menu - -@node Fringe Size/Pos -@subsection Fringe Size and Position - - The following buffer-local variables control the position and width -of fringes in windows showing that buffer. - -@defvar fringes-outside-margins -The fringes normally appear between the display margins and the window -text. If the value is non-@code{nil}, they appear outside the display -margins. @xref{Display Margins}. -@end defvar - -@defvar left-fringe-width -This variable, if non-@code{nil}, specifies the width of the left -fringe in pixels. A value of @code{nil} means to use the left fringe -width from the window's frame. -@end defvar - -@defvar right-fringe-width -This variable, if non-@code{nil}, specifies the width of the right -fringe in pixels. A value of @code{nil} means to use the right fringe -width from the window's frame. -@end defvar - - Any buffer which does not specify values for these variables uses -the values specified by the @code{left-fringe} and @code{right-fringe} -frame parameters (@pxref{Layout Parameters}). - - The above variables actually take effect via the function -@code{set-window-buffer} (@pxref{Buffers and Windows}), which calls -@code{set-window-fringes} as a subroutine. If you change one of these -variables, the fringe display is not updated in existing windows -showing the buffer, unless you call @code{set-window-buffer} again in -each affected window. You can also use @code{set-window-fringes} to -control the fringe display in individual windows. - -@defun set-window-fringes window left &optional right outside-margins -This function sets the fringe widths of window @var{window}. -If @var{window} is @code{nil}, the selected window is used. - -The argument @var{left} specifies the width in pixels of the left -fringe, and likewise @var{right} for the right fringe. A value of -@code{nil} for either one stands for the default width. If -@var{outside-margins} is non-@code{nil}, that specifies that fringes -should appear outside of the display margins. -@end defun - -@defun window-fringes &optional window -This function returns information about the fringes of a window -@var{window}. If @var{window} is omitted or @code{nil}, the selected -window is used. The value has the form @code{(@var{left-width} -@var{right-width} @var{outside-margins})}. -@end defun - - -@node Fringe Indicators -@subsection Fringe Indicators -@cindex fringe indicators -@cindex indicators, fringe - - @dfn{Fringe indicators} are tiny icons displayed in the window -fringe to indicate truncated or continued lines, buffer boundaries, -etc. - -@defopt indicate-empty-lines -@cindex fringes, and empty line indication -@cindex empty lines, indicating -When this is non-@code{nil}, Emacs displays a special glyph in the -fringe of each empty line at the end of the buffer, on graphical -displays. @xref{Fringes}. This variable is automatically -buffer-local in every buffer. -@end defopt - -@defopt indicate-buffer-boundaries -@cindex buffer boundaries, indicating -This buffer-local variable controls how the buffer boundaries and -window scrolling are indicated in the window fringes. - -Emacs can indicate the buffer boundaries---that is, the first and last -line in the buffer---with angle icons when they appear on the screen. -In addition, Emacs can display an up-arrow in the fringe to show -that there is text above the screen, and a down-arrow to show -there is text below the screen. - -There are three kinds of basic values: - -@table @asis -@item @code{nil} -Don't display any of these fringe icons. -@item @code{left} -Display the angle icons and arrows in the left fringe. -@item @code{right} -Display the angle icons and arrows in the right fringe. -@item any non-alist -Display the angle icons in the left fringe -and don't display the arrows. -@end table - -Otherwise the value should be an alist that specifies which fringe -indicators to display and where. Each element of the alist should -have the form @code{(@var{indicator} . @var{position})}. Here, -@var{indicator} is one of @code{top}, @code{bottom}, @code{up}, -@code{down}, and @code{t} (which covers all the icons not yet -specified), while @var{position} is one of @code{left}, @code{right} -and @code{nil}. - -For example, @code{((top . left) (t . right))} places the top angle -bitmap in left fringe, and the bottom angle bitmap as well as both -arrow bitmaps in right fringe. To show the angle bitmaps in the left -fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}. -@end defopt - -@defvar fringe-indicator-alist -This buffer-local variable specifies the mapping from logical fringe -indicators to the actual bitmaps displayed in the window fringes. The -value is an alist of elements @code{(@var{indicator} -. @var{bitmaps})}, where @var{indicator} specifies a logical indicator -type and @var{bitmaps} specifies the fringe bitmaps to use for that -indicator. - - Each @var{indicator} should be one of the following symbols: - -@table @asis -@item @code{truncation}, @code{continuation}. -Used for truncation and continuation lines. - -@item @code{up}, @code{down}, @code{top}, @code{bottom}, @code{top-bottom} -Used when @code{indicate-buffer-boundaries} is non-@code{nil}: -@code{up} and @code{down} indicate a buffer boundary lying above or -below the window edge; @code{top} and @code{bottom} indicate the -topmost and bottommost buffer text line; and @code{top-bottom} -indicates where there is just one line of text in the buffer. - -@item @code{empty-line} -Used to indicate empty lines when @code{indicate-empty-lines} is -non-@code{nil}. - -@item @code{overlay-arrow} -Used for overlay arrows (@pxref{Overlay Arrow}). -@c Is this used anywhere? -@c @item Unknown bitmap indicator: -@c @code{unknown}. -@end table - - Each @var{bitmaps} value may be a list of symbols @code{(@var{left} -@var{right} [@var{left1} @var{right1}])}. The @var{left} and -@var{right} symbols specify the bitmaps shown in the left and/or right -fringe, for the specific indicator. @var{left1} and @var{right1} are -specific to the @code{bottom} and @code{top-bottom} indicators, and -are used to indicate that the last text line has no final newline. -Alternatively, @var{bitmaps} may be a single symbol which is used in -both left and right fringes. - - @xref{Fringe Bitmaps}, for a list of standard bitmap symbols and how -to define your own. In addition, @code{nil} represents the empty -bitmap (i.e., an indicator that is not shown). - - When @code{fringe-indicator-alist} has a buffer-local value, and -there is no bitmap defined for a logical indicator, or the bitmap is -@code{t}, the corresponding value from the default value of -@code{fringe-indicator-alist} is used. -@end defvar - -@node Fringe Cursors -@subsection Fringe Cursors -@cindex fringe cursors -@cindex cursor, fringe - - When a line is exactly as wide as the window, Emacs displays the -cursor in the right fringe instead of using two lines. Different -bitmaps are used to represent the cursor in the fringe depending on -the current buffer's cursor type. - -@defopt overflow-newline-into-fringe -If this is non-@code{nil}, lines exactly as wide as the window (not -counting the final newline character) are not continued. Instead, -when point is at the end of the line, the cursor appears in the right -fringe. -@end defopt - -@defvar fringe-cursor-alist -This variable specifies the mapping from logical cursor type to the -actual fringe bitmaps displayed in the right fringe. The value is an -alist where each element has the form @code{(@var{cursor-type} -. @var{bitmap})}, which means to use the fringe bitmap @var{bitmap} to -display cursors of type @var{cursor-type}. - -Each @var{cursor-type} should be one of @code{box}, @code{hollow}, -@code{bar}, @code{hbar}, or @code{hollow-small}. The first four have -the same meanings as in the @code{cursor-type} frame parameter -(@pxref{Cursor Parameters}). The @code{hollow-small} type is used -instead of @code{hollow} when the normal @code{hollow-rectangle} -bitmap is too tall to fit on a specific display line. - -Each @var{bitmap} should be a symbol specifying the fringe bitmap to -be displayed for that logical cursor type. -@iftex -See the next subsection for details. -@end iftex -@ifnottex -@xref{Fringe Bitmaps}. -@end ifnottex - -@c FIXME: I can't find the fringes-indicator-alist variable. Maybe -@c it should be fringe-indicator-alist or fringe-cursor-alist? --xfq -When @code{fringe-cursor-alist} has a buffer-local value, and there is -no bitmap defined for a cursor type, the corresponding value from the -default value of @code{fringes-indicator-alist} is used. -@end defvar - -@node Fringe Bitmaps -@subsection Fringe Bitmaps -@cindex fringe bitmaps -@cindex bitmaps, fringe - - The @dfn{fringe bitmaps} are the actual bitmaps which represent the -logical fringe indicators for truncated or continued lines, buffer -boundaries, overlay arrows, etc. Each bitmap is represented by a -symbol. -@iftex -These symbols are referred to by the variables -@code{fringe-indicator-alist} and @code{fringe-cursor-alist}, -described in the previous subsections. -@end iftex -@ifnottex -These symbols are referred to by the variable -@code{fringe-indicator-alist}, which maps fringe indicators to bitmaps -(@pxref{Fringe Indicators}), and the variable -@code{fringe-cursor-alist}, which maps fringe cursors to bitmaps -(@pxref{Fringe Cursors}). -@end ifnottex - - Lisp programs can also directly display a bitmap in the left or -right fringe, by using a @code{display} property for one of the -characters appearing in the line (@pxref{Other Display Specs}). Such -a display specification has the form - -@example -(@var{fringe} @var{bitmap} [@var{face}]) -@end example - -@noindent -@var{fringe} is either the symbol @code{left-fringe} or -@code{right-fringe}. @var{bitmap} is a symbol identifying the bitmap -to display. The optional @var{face} names a face whose foreground -color is used to display the bitmap; this face is automatically merged -with the @code{fringe} face. - - Here is a list of the standard fringe bitmaps defined in Emacs, and -how they are currently used in Emacs (via -@code{fringe-indicator-alist} and @code{fringe-cursor-alist}): - -@table @asis -@item @code{left-arrow}, @code{right-arrow} -Used to indicate truncated lines. - -@item @code{left-curly-arrow}, @code{right-curly-arrow} -Used to indicate continued lines. - -@item @code{right-triangle}, @code{left-triangle} -The former is used by overlay arrows. The latter is unused. - -@item @code{up-arrow}, @code{down-arrow}, @code{top-left-angle} @code{top-right-angle} -@itemx @code{bottom-left-angle}, @code{bottom-right-angle} -@itemx @code{top-right-angle}, @code{top-left-angle} -@itemx @code{left-bracket}, @code{right-bracket}, @code{top-right-angle}, @code{top-left-angle} -Used to indicate buffer boundaries. - -@item @code{filled-rectangle}, @code{hollow-rectangle} -@itemx @code{filled-square}, @code{hollow-square} -@itemx @code{vertical-bar}, @code{horizontal-bar} -Used for different types of fringe cursors. - -@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}, @code{exclamation-mark} -Not used by core Emacs features. -@end table - -@noindent -The next subsection describes how to define your own fringe bitmaps. - -@defun fringe-bitmaps-at-pos &optional pos window -This function returns the fringe bitmaps of the display line -containing position @var{pos} in window @var{window}. The return -value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left} -is the symbol for the fringe bitmap in the left fringe (or @code{nil} -if no bitmap), @var{right} is similar for the right fringe, and @var{ov} -is non-@code{nil} if there is an overlay arrow in the left fringe. - -The value is @code{nil} if @var{pos} is not visible in @var{window}. -If @var{window} is @code{nil}, that stands for the selected window. -If @var{pos} is @code{nil}, that stands for the value of point in -@var{window}. -@end defun - -@node Customizing Bitmaps -@subsection Customizing Fringe Bitmaps -@cindex fringe bitmaps, customizing - -@defun define-fringe-bitmap bitmap bits &optional height width align -This function defines the symbol @var{bitmap} as a new fringe bitmap, -or replaces an existing bitmap with that name. - -The argument @var{bits} specifies the image to use. It should be -either a string or a vector of integers, where each element (an -integer) corresponds to one row of the bitmap. Each bit of an integer -corresponds to one pixel of the bitmap, where the low bit corresponds -to the rightmost pixel of the bitmap. - -The height is normally the length of @var{bits}. However, you -can specify a different height with non-@code{nil} @var{height}. The width -is normally 8, but you can specify a different width with non-@code{nil} -@var{width}. The width must be an integer between 1 and 16. - -The argument @var{align} specifies the positioning of the bitmap -relative to the range of rows where it is used; the default is to -center the bitmap. The allowed values are @code{top}, @code{center}, -or @code{bottom}. - -The @var{align} argument may also be a list @code{(@var{align} -@var{periodic})} where @var{align} is interpreted as described above. -If @var{periodic} is non-@code{nil}, it specifies that the rows in -@code{bits} should be repeated enough times to reach the specified -height. -@end defun - -@defun destroy-fringe-bitmap bitmap -This function destroy the fringe bitmap identified by @var{bitmap}. -If @var{bitmap} identifies a standard fringe bitmap, it actually -restores the standard definition of that bitmap, instead of -eliminating it entirely. -@end defun - -@defun set-fringe-bitmap-face bitmap &optional face -This sets the face for the fringe bitmap @var{bitmap} to @var{face}. -If @var{face} is @code{nil}, it selects the @code{fringe} face. The -bitmap's face controls the color to draw it in. - -@var{face} is merged with the @code{fringe} face, so normally -@var{face} should specify only the foreground color. -@end defun - -@node Overlay Arrow -@subsection The Overlay Arrow -@c @cindex overlay arrow Duplicates variable names - - The @dfn{overlay arrow} is useful for directing the user's attention -to a particular line in a buffer. For example, in the modes used for -interface to debuggers, the overlay arrow indicates the line of code -about to be executed. This feature has nothing to do with -@dfn{overlays} (@pxref{Overlays}). - -@defvar overlay-arrow-string -This variable holds the string to display to call attention to a -particular line, or @code{nil} if the arrow feature is not in use. -On a graphical display the contents of the string are ignored; instead a -glyph is displayed in the fringe area to the left of the display area. -@end defvar - -@defvar overlay-arrow-position -This variable holds a marker that indicates where to display the overlay -arrow. It should point at the beginning of a line. On a non-graphical -display the arrow text -appears at the beginning of that line, overlaying any text that would -otherwise appear. Since the arrow is usually short, and the line -usually begins with indentation, normally nothing significant is -overwritten. - -The overlay-arrow string is displayed in any given buffer if the value -of @code{overlay-arrow-position} in that buffer points into that -buffer. Thus, it is possible to display multiple overlay arrow strings -by creating buffer-local bindings of @code{overlay-arrow-position}. -However, it is usually cleaner to use -@code{overlay-arrow-variable-list} to achieve this result. -@c !!! overlay-arrow-position: but the overlay string may remain in the display -@c of some other buffer until an update is required. This should be fixed -@c now. Is it? -@end defvar - - You can do a similar job by creating an overlay with a -@code{before-string} property. @xref{Overlay Properties}. - - You can define multiple overlay arrows via the variable -@code{overlay-arrow-variable-list}. - -@defvar overlay-arrow-variable-list -This variable's value is a list of variables, each of which specifies -the position of an overlay arrow. The variable -@code{overlay-arrow-position} has its normal meaning because it is on -this list. -@end defvar - -Each variable on this list can have properties -@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that -specify an overlay arrow string (for text terminals) or fringe bitmap -(for graphical terminals) to display at the corresponding overlay -arrow position. If either property is not set, the default -@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator -is used. - -@node Scroll Bars -@section Scroll Bars -@cindex scroll bars - -Normally the frame parameter @code{vertical-scroll-bars} controls -whether the windows in the frame have vertical scroll bars, and -whether they are on the left or right. The frame parameter -@code{scroll-bar-width} specifies how wide they are (@code{nil} -meaning the default). @xref{Layout Parameters}. - -@defun frame-current-scroll-bars &optional frame -This function reports the scroll bar type settings for frame -@var{frame}. The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}, where -@var{vertical-type} is either @code{left}, @code{right}, or @code{nil} -(which means no scroll bar.) @var{horizontal-type} is meant to -specify the horizontal scroll bar type, but since they are not -implemented, it is always @code{nil}. -@end defun - -@vindex vertical-scroll-bar - You can enable or disable scroll bars for a particular buffer, -by setting the variable @code{vertical-scroll-bar}. This variable -automatically becomes buffer-local when set. The possible values are -@code{left}, @code{right}, @code{t}, which means to use the -frame's default, and @code{nil} for no scroll bar. - - You can also control this for individual windows. Call the function -@code{set-window-scroll-bars} to specify what to do for a specific window: - -@defun set-window-scroll-bars window width &optional vertical-type horizontal-type -This function sets the width and type of scroll bars for window -@var{window}. - -@var{width} specifies the scroll bar width in pixels (@code{nil} means -use the width specified for the frame). @var{vertical-type} specifies -whether to have a vertical scroll bar and, if so, where. The possible -values are @code{left}, @code{right} and @code{nil}, just like the -values of the @code{vertical-scroll-bars} frame parameter. - -The argument @var{horizontal-type} is meant to specify whether and -where to have horizontal scroll bars, but since they are not -implemented, it has no effect. If @var{window} is @code{nil}, the -selected window is used. -@end defun - -@defun window-scroll-bars &optional window -Report the width and type of scroll bars specified for @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a list of the form @code{(@var{width} -@var{cols} @var{vertical-type} @var{horizontal-type})}. The value -@var{width} is the value that was specified for the width (which may -be @code{nil}); @var{cols} is the number of columns that the scroll -bar actually occupies. - -@var{horizontal-type} is not actually meaningful. -@end defun - -@defun window-scroll-bar-width &optional window -This function returns the width in pixels of @var{window}'s vertical -scrollbar. @var{window} must be a live window, and defaults to the -selected window. -@end defun - -If you don't specify these values for a window with -@code{set-window-scroll-bars}, the buffer-local variables -@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being -displayed control the window's vertical scroll bars. The function -@code{set-window-buffer} examines these variables. If you change them -in a buffer that is already visible in a window, you can make the -window take note of the new values by calling @code{set-window-buffer} -specifying the same buffer that is already displayed. - -@defopt scroll-bar-mode -This variable, always local in all buffers, controls whether and where -to put scroll bars in windows displaying the buffer. The possible values -are @code{nil} for no scroll bar, @code{left} to put a scroll bar on -the left, and @code{right} to put a scroll bar on the right. -@end defopt - -@defun window-current-scroll-bars &optional window -This function reports the scroll bar type for window @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike -@code{window-scroll-bars}, this reports the scroll bar type actually -used, once frame defaults and @code{scroll-bar-mode} are taken into -account. -@end defun - -@defvar scroll-bar-width -This variable, always local in all buffers, specifies the width of the -buffer's scroll bars, measured in pixels. A value of @code{nil} means -to use the value specified by the frame. -@end defvar - -@node Window Dividers -@section Window Dividers -@cindex window dividers -@cindex right dividers -@cindex bottom dividers - -Window dividers are bars drawn between a frame's windows. A ``right'' -divider is drawn between a window and any adjacent windows on the right. -Its width (thickness) is specified by the frame parameter -@code{right-divider-width}. A ``bottom'' divider is drawn between a -window and adjacent windows on the bottom or the echo area. Its width -is specified by the frame parameter @code{bottom-divider-width}. In -either case, specifying a width of zero means to not draw such dividers. -@xref{Layout Parameters}. - - Technically, a right divider ``belongs'' to the window on its left, -which means that its width contributes to the total width of that -window. A bottom divider ``belongs'' to the window above it, which -means that its width contributes to the total height of that window. -@xref{Window Sizes}. When a window has both, a right and a bottom -divider, the bottom divider ``prevails''. This means that a bottom -divider is drawn over the full total width of its window while the right -divider ends above the bottom divider. - - Dividers can be dragged with the mouse and are therefore useful for -adjusting the sizes of adjacent windows with the mouse. They also serve -to visually set apart adjacent windows when no scroll bars or mode lines -are present. The following three faces allow to customize the -appearance of dividers: - -@table @code -@item window-divider -When a divider is less than three pixels wide, it is drawn solidly with -the foreground of this face. For larger dividers this face is used for -the inner part only, excluding the first and last pixel. - -@item window-divider-first-pixel -This is the face used for drawing the first pixel of a divider that is -at least three pixels wide. To obtain a solid appearance, set this to -the same value used for the @code{window-divider} face. - -@item window-divider-last-pixel -This is the face used for drawing the last pixel of a divider that is at -least three pixels wide. To obtain a solid appearance, set this to the -same value used for the @code{window-divider} face. -@end table - -You can get the sizes of the dividers of a specific window with the -following two functions. - -@defun window-right-divider-width &optional window -Return the width (thickness) in pixels of @var{window}'s right divider. -@var{window} must be a live window and defaults to the selected one. -The return value is always zero for a rightmost window. -@end defun - -@defun window-bottom-divider-width &optional window -Return the width (thickness) in pixels of @var{window}'s bottom divider. -@var{window} must be a live window and defaults to the selected one. -The return value is zero for the minibuffer window or a bottommost -window on a minibuffer-less frame. -@end defun - - -@node Display Property -@section The @code{display} Property -@cindex display specification -@kindex display @r{(text property)} - - The @code{display} text property (or overlay property) is used to -insert images into text, and to control other aspects of how text -displays. The value of the @code{display} property should be a -display specification, or a list or vector containing several display -specifications. Display specifications in the same @code{display} -property value generally apply in parallel to the text they cover. - - If several sources (overlays and/or a text property) specify values -for the @code{display} property, only one of the values takes effect, -following the rules of @code{get-char-property}. @xref{Examining -Properties}. - - The rest of this section describes several kinds of -display specifications and what they mean. - -@menu -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; adjusting the height, - spacing, and other properties of text. -* Display Margins:: Displaying text or images to the side of the main text. -@end menu - -@node Replacing Specs -@subsection Display Specs That Replace The Text - - Some kinds of display specifications specify something to display -instead of the text that has the property. These are called -@dfn{replacing} display specifications. Emacs does not allow the user -to interactively move point into the middle of buffer text that is -replaced in this way. - - If a list of display specifications includes more than one replacing -display specification, the first overrides the rest. Replacing -display specifications make most other display specifications -irrelevant, since those don't apply to the replacement. - - For replacing display specifications, ``the text that has the -property'' means all the consecutive characters that have the same -Lisp object as their @code{display} property; these characters are -replaced as a single unit. If two characters have different Lisp -objects as their @code{display} properties (i.e., objects which are -not @code{eq}), they are handled separately. - - Here is an example which illustrates this point. A string serves as -a replacing display specification, which replaces the text that has -the property with the specified string (@pxref{Other Display Specs}). -Consider the following function: - -@smallexample -(defun foo () - (dotimes (i 5) - (let ((string (concat "A")) - (start (+ i i (point-min)))) - (put-text-property start (1+ start) 'display string) - (put-text-property start (+ 2 start) 'display string)))) -@end smallexample - -@noindent -This function gives each of the first ten characters in the buffer a -@code{display} property which is a string @code{"A"}, but they don't -all get the same string object. The first two characters get the same -string object, so they are replaced with one @samp{A}; the fact that -the display property was assigned in two separate calls to -@code{put-text-property} is irrelevant. Similarly, the next two -characters get a second string (@code{concat} creates a new string -object), so they are replaced with one @samp{A}; and so on. Thus, the -ten characters appear as five A's. - -@node Specified Space -@subsection Specified Spaces -@cindex spaces, specified height or width -@cindex variable-width spaces - - To display a space of specified width and/or height, use a display -specification of the form @code{(space . @var{props})}, where -@var{props} is a property list (a list of alternating properties and -values). You can put this property on one or more consecutive -characters; a space of the specified height and width is displayed in -place of @emph{all} of those characters. These are the properties you -can use in @var{props} to specify the weight of the space: - -@table @code -@item :width @var{width} -If @var{width} is a number, it specifies -that the space width should be @var{width} times the normal character -width. @var{width} can also be a @dfn{pixel width} specification -(@pxref{Pixel Specification}). - -@item :relative-width @var{factor} -Specifies that the width of the stretch should be computed from the -first character in the group of consecutive characters that have the -same @code{display} property. The space width is the width of that -character, multiplied by @var{factor}. - -@item :align-to @var{hpos} -Specifies that the space should be wide enough to reach @var{hpos}. -If @var{hpos} is a number, it is measured in units of the normal -character width. @var{hpos} can also be a @dfn{pixel width} -specification (@pxref{Pixel Specification}). -@end table - - You should use one and only one of the above properties. You can -also specify the height of the space, with these properties: - -@table @code -@item :height @var{height} -Specifies the height of the space. -If @var{height} is a number, it specifies -that the space height should be @var{height} times the normal character -height. The @var{height} may also be a @dfn{pixel height} specification -(@pxref{Pixel Specification}). - -@item :relative-height @var{factor} -Specifies the height of the space, multiplying the ordinary height -of the text having this display specification by @var{factor}. - -@item :ascent @var{ascent} -If the value of @var{ascent} is a non-negative number no greater than -100, it specifies that @var{ascent} percent of the height of the space -should be considered as the ascent of the space---that is, the part -above the baseline. The ascent may also be specified in pixel units -with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}). - -@end table - - Don't use both @code{:height} and @code{:relative-height} together. - - The @code{:width} and @code{:align-to} properties are supported on -non-graphic terminals, but the other space properties in this section -are not. - - Note that space properties are treated as paragraph separators for -the purposes of reordering bidirectional text for display. -@xref{Bidirectional Display}, for the details. - -@node Pixel Specification -@subsection Pixel Specification for Spaces -@cindex spaces, pixel specification - - The value of the @code{:width}, @code{:align-to}, @code{:height}, -and @code{:ascent} properties can be a special kind of expression that -is evaluated during redisplay. The result of the evaluation is used -as an absolute number of pixels. - - The following expressions are supported: - -@smallexample -@group - @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form} - @var{num} ::= @var{integer} | @var{float} | @var{symbol} - @var{unit} ::= in | mm | cm | width | height -@end group -@group - @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin - | scroll-bar | text - @var{pos} ::= left | center | right - @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...) - @var{op} ::= + | - -@end group -@end smallexample - - The form @var{num} specifies a fraction of the default frame font -height or width. The form @code{(@var{num})} specifies an absolute -number of pixels. If @var{num} is a symbol, @var{symbol}, its -buffer-local variable binding is used. - - The @code{in}, @code{mm}, and @code{cm} units specify the number of -pixels per inch, millimeter, and centimeter, respectively. The -@code{width} and @code{height} units correspond to the default width -and height of the current face. An image specification @code{image} -corresponds to the width or height of the image. - - The elements @code{left-fringe}, @code{right-fringe}, -@code{left-margin}, @code{right-margin}, @code{scroll-bar}, and -@code{text} specify to the width of the corresponding area of the -window. - - The @code{left}, @code{center}, and @code{right} positions can be -used with @code{:align-to} to specify a position relative to the left -edge, center, or right edge of the text area. - - Any of the above window elements (except @code{text}) can also be -used with @code{:align-to} to specify that the position is relative to -the left edge of the given area. Once the base offset for a relative -position has been set (by the first occurrence of one of these -symbols), further occurrences of these symbols are interpreted as the -width of the specified area. For example, to align to the center of -the left-margin, use - -@example -:align-to (+ left-margin (0.5 . left-margin)) -@end example - - If no specific base offset is set for alignment, it is always relative -to the left edge of the text area. For example, @samp{:align-to 0} in a -header-line aligns with the first text column in the text area. - - A value of the form @code{(@var{num} . @var{expr})} stands for the -product of the values of @var{num} and @var{expr}. For example, -@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 . -@var{image})} specifies half the width (or height) of the specified -image. - - The form @code{(+ @var{expr} ...)} adds up the value of the -expressions. The form @code{(- @var{expr} ...)} negates or subtracts -the value of the expressions. - -@node Other Display Specs -@subsection Other Display Specifications - - Here are the other sorts of display specifications that you can use -in the @code{display} text property. - -@table @code -@item @var{string} -Display @var{string} instead of the text that has this property. - -Recursive display specifications are not supported---@var{string}'s -@code{display} properties, if any, are not used. - -@item (image . @var{image-props}) -This kind of display specification is an image descriptor (@pxref{Images}). -When used as a display specification, it means to display the image -instead of the text that has the display specification. - -@item (slice @var{x} @var{y} @var{width} @var{height}) -This specification together with @code{image} specifies a @dfn{slice} -(a partial area) of the image to display. The elements @var{y} and -@var{x} specify the top left corner of the slice, within the image; -@var{width} and @var{height} specify the width and height of the -slice. Integers are numbers of pixels. A floating-point number -in the range 0.0--1.0 stands for that fraction of the width or height -of the entire image. - -@item ((margin nil) @var{string}) -A display specification of this form means to display @var{string} -instead of the text that has the display specification, at the same -position as that text. It is equivalent to using just @var{string}, -but it is done as a special case of marginal display (@pxref{Display -Margins}). - -@item (left-fringe @var{bitmap} @r{[}@var{face}@r{]}) -@itemx (right-fringe @var{bitmap} @r{[}@var{face}@r{]}) -This display specification on any character of a line of text causes -the specified @var{bitmap} be displayed in the left or right fringes -for that line, instead of the characters that have the display -specification. The optional @var{face} specifies the colors to be -used for the bitmap. @xref{Fringe Bitmaps}, for the details. - -@item (space-width @var{factor}) -This display specification affects all the space characters within the -text that has the specification. It displays all of these spaces -@var{factor} times as wide as normal. The element @var{factor} should -be an integer or float. Characters other than spaces are not affected -at all; in particular, this has no effect on tab characters. - -@item (height @var{height}) -This display specification makes the text taller or shorter. -Here are the possibilities for @var{height}: - -@table @asis -@item @code{(+ @var{n})} -@c FIXME: Add an index for "step"? --xfq -This means to use a font that is @var{n} steps larger. A ``step'' is -defined by the set of available fonts---specifically, those that match -what was otherwise specified for this text, in all attributes except -height. Each size for which a suitable font is available counts as -another step. @var{n} should be an integer. - -@item @code{(- @var{n})} -This means to use a font that is @var{n} steps smaller. - -@item a number, @var{factor} -A number, @var{factor}, means to use a font that is @var{factor} times -as tall as the default font. - -@item a symbol, @var{function} -A symbol is a function to compute the height. It is called with the -current height as argument, and should return the new height to use. - -@item anything else, @var{form} -If the @var{height} value doesn't fit the previous possibilities, it is -a form. Emacs evaluates it to get the new height, with the symbol -@code{height} bound to the current specified font height. -@end table - -@item (raise @var{factor}) -This kind of display specification raises or lowers the text -it applies to, relative to the baseline of the line. - -@var{factor} must be a number, which is interpreted as a multiple of the -height of the affected text. If it is positive, that means to display -the characters raised. If it is negative, that means to display them -lower down. - -If the text also has a @code{height} display specification, that does -not affect the amount of raising or lowering, which is based on the -faces used for the text. -@end table - -@c We put all the `@code{(when ...)}' on one line to encourage -@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot -@c was at eol; the info file ended up w/ two spaces rendered after it. - You can make any display specification conditional. To do that, -package it in another list of the form -@code{(when @var{condition} . @var{spec})}. -Then the specification @var{spec} applies only when -@var{condition} evaluates to a non-@code{nil} value. During the -evaluation, @code{object} is bound to the string or buffer having the -conditional @code{display} property. @code{position} and -@code{buffer-position} are bound to the position within @code{object} -and the buffer position where the @code{display} property was found, -respectively. Both positions can be different when @code{object} is a -string. - -@node Display Margins -@subsection Displaying in the Margins -@cindex display margins -@cindex margins, display - - A buffer can have blank areas called @dfn{display margins} on the -left and on the right. Ordinary text never appears in these areas, -but you can put things into the display margins using the -@code{display} property. There is currently no way to make text or -images in the margin mouse-sensitive. - - The way to display something in the margins is to specify it in a -margin display specification in the @code{display} property of some -text. This is a replacing display specification, meaning that the -text you put it on does not get displayed; the margin display appears, -but that text does not. - - A margin display specification looks like @code{((margin -right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}. -Here, @var{spec} is another display specification that says what to -display in the margin. Typically it is a string of text to display, -or an image descriptor. - - To display something in the margin @emph{in association with} -certain buffer text, without altering or preventing the display of -that text, put a @code{before-string} property on the text and put the -margin display specification on the contents of the before-string. - - Before the display margins can display anything, you must give -them a nonzero width. The usual way to do that is to set these -variables: - -@defvar left-margin-width -This variable specifies the width of the left margin, in character -cell (a.k.a.@: ``column'') units. It is buffer-local in all buffers. -A value of @code{nil} means no left marginal area. -@end defvar - -@defvar right-margin-width -This variable specifies the width of the right margin, in character -cell units. It is buffer-local in all buffers. A value of @code{nil} -means no right marginal area. -@end defvar - - Setting these variables does not immediately affect the window. These -variables are checked when a new buffer is displayed in the window. -Thus, you can make changes take effect by calling -@code{set-window-buffer}. - - You can also set the margin widths immediately. - -@defun set-window-margins window left &optional right -This function specifies the margin widths for window @var{window}, in -character cell units. The argument @var{left} controls the left -margin, and @var{right} controls the right margin (default @code{0}). -@end defun - -@defun window-margins &optional window -This function returns the width of the left and right margins of -@var{window} as a cons cell of the form @w{@code{(@var{left} -. @var{right})}}. If one of the two marginal areas does not exist, -its width is returned as @code{nil}; if neither of the two margins exist, -the function returns @code{(nil)}. If @var{window} is @code{nil}, the -selected window is used. -@end defun - -@node Images -@section Images -@cindex images in buffers - - To display an image in an Emacs buffer, you must first create an image -descriptor, then use it as a display specifier in the @code{display} -property of text that is displayed (@pxref{Display Property}). - - Emacs is usually able to display images when it is run on a -graphical terminal. Images cannot be displayed in a text terminal, on -certain graphical terminals that lack the support for this, or if -Emacs is compiled without image support. You can use the function -@code{display-images-p} to determine if images can in principle be -displayed (@pxref{Display Feature Testing}). - -@menu -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* PostScript Images:: Special features for PostScript format. -* ImageMagick Images:: Special features available through ImageMagick. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once it is defined. -* Multi-Frame Images:: Some images contain more than one frame. -* Image Cache:: Internal mechanisms of image display. -@end menu - -@node Image Formats -@subsection Image Formats -@cindex image formats -@cindex image types - - Emacs can display a number of different image formats. Some of -these image formats are supported only if particular support libraries -are installed. On some platforms, Emacs can load support libraries on -demand; if so, the variable @code{dynamic-library-alist} can be used -to modify the set of known names for these dynamic libraries. -@xref{Dynamic Libraries}. - - Supported image formats (and the required support libraries) include -PBM and XBM (which do not depend on support libraries and are always -available), XPM (@code{libXpm}), GIF (@code{libgif} or -@code{libungif}), PostScript (@code{gs}), JPEG (@code{libjpeg}), TIFF -(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). - - Each of these image formats is associated with an @dfn{image type -symbol}. The symbols for the above formats are, respectively, -@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, -@code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. - - Furthermore, if you build Emacs with ImageMagick -(@code{libMagickWand}) support, Emacs can display any image format -that ImageMagick can. @xref{ImageMagick Images}. All images -displayed via ImageMagick have type symbol @code{imagemagick}. - -@defvar image-types -This variable contains a list of type symbols for image formats which -are potentially supported in the current configuration. - -``Potentially'' means that Emacs knows about the image types, not -necessarily that they can be used (for example, they could depend on -unavailable dynamic libraries). To know which image types are really -available, use @code{image-type-available-p}. -@end defvar - -@defun image-type-available-p type -This function returns non-@code{nil} if images of type @var{type} can -be loaded and displayed. @var{type} must be an image type symbol. - -For image types whose support libraries are statically linked, this -function always returns @code{t}. For image types whose support -libraries are dynamically loaded, it returns @code{t} if the library -could be loaded and @code{nil} otherwise. -@end defun - -@node Image Descriptors -@subsection Image Descriptors -@cindex image descriptor - - An @dfn{image descriptor} is a list which specifies the underlying -data for an image, and how to display it. It is typically used as the -value of a @code{display} overlay or text property (@pxref{Other -Display Specs}); but @xref{Showing Images}, for convenient helper -functions to insert images into buffers. - - Each image descriptor has the form @code{(image . @var{props})}, -where @var{props} is a property list of alternating keyword symbols -and values, including at least the pair @code{:type @var{type}} that -specifies the image type. - - The following is a list of properties that are meaningful for all -image types (there are also properties which are meaningful only for -certain image types, as documented in the following subsections): - -@table @code -@item :type @var{type} -The image type. -@ifnottex -@xref{Image Formats}. -@end ifnottex -Every image descriptor must include this property. - -@item :file @var{file} -This says to load the image from file @var{file}. If @var{file} is -not an absolute file name, it is expanded in @code{data-directory}. - -@item :data @var{data} -This specifies the raw image data. Each image descriptor must have -either @code{:data} or @code{:file}, but not both. - -For most image types, the value of a @code{:data} property should be a -string containing the image data. Some image types do not support -@code{:data}; for some others, @code{:data} alone is not enough, so -you need to use other image properties along with @code{:data}. See -the following subsections for details. - -@item :margin @var{margin} -This specifies how many pixels to add as an extra margin around the -image. The value, @var{margin}, must be a non-negative number, or a -pair @code{(@var{x} . @var{y})} of such numbers. If it is a pair, -@var{x} specifies how many pixels to add horizontally, and @var{y} -specifies how many pixels to add vertically. If @code{:margin} is not -specified, the default is zero. - -@item :ascent @var{ascent} -This specifies the amount of the image's height to use for its -ascent---that is, the part above the baseline. The value, -@var{ascent}, must be a number in the range 0 to 100, or the symbol -@code{center}. - -If @var{ascent} is a number, that percentage of the image's height is -used for its ascent. - -If @var{ascent} is @code{center}, the image is vertically centered -around a centerline which would be the vertical centerline of text drawn -at the position of the image, in the manner specified by the text -properties and overlays that apply to the image. - -If this property is omitted, it defaults to 50. - -@item :relief @var{relief} -This adds a shadow rectangle around the image. The value, -@var{relief}, specifies the width of the shadow lines, in pixels. If -@var{relief} is negative, shadows are drawn so that the image appears -as a pressed button; otherwise, it appears as an unpressed button. - -@item :conversion @var{algorithm} -This specifies a conversion algorithm that should be applied to the -image before it is displayed; the value, @var{algorithm}, specifies -which algorithm. - -@table @code -@item laplace -@itemx emboss -Specifies the Laplace edge detection algorithm, which blurs out small -differences in color while highlighting larger differences. People -sometimes consider this useful for displaying the image for a -``disabled'' button. - -@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust}) -@cindex edge detection, images -Specifies a general edge-detection algorithm. @var{matrix} must be -either a nine-element list or a nine-element vector of numbers. A pixel -at position @math{x/y} in the transformed image is computed from -original pixels around that position. @var{matrix} specifies, for each -pixel in the neighborhood of @math{x/y}, a factor with which that pixel -will influence the transformed pixel; element @math{0} specifies the -factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for -the pixel at @math{x/y-1} etc., as shown below: -@iftex -@tex -$$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr - x-1/y & x/y & x+1/y \cr - x-1/y+1& x/y+1 & x+1/y+1 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - (x-1/y-1 x/y-1 x+1/y-1 - x-1/y x/y x+1/y - x-1/y+1 x/y+1 x+1/y+1) -@end display -@end ifnottex - -The resulting pixel is computed from the color intensity of the color -resulting from summing up the RGB values of surrounding pixels, -multiplied by the specified factors, and dividing that sum by the sum -of the factors' absolute values. - -Laplace edge-detection currently uses a matrix of -@iftex -@tex -$$\pmatrix{1 & 0 & 0 \cr - 0& 0 & 0 \cr - 0 & 0 & -1 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - (1 0 0 - 0 0 0 - 0 0 -1) -@end display -@end ifnottex - -Emboss edge-detection uses a matrix of -@iftex -@tex -$$\pmatrix{ 2 & -1 & 0 \cr - -1 & 0 & 1 \cr - 0 & 1 & -2 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - ( 2 -1 0 - -1 0 1 - 0 1 -2) -@end display -@end ifnottex - -@item disabled -Specifies transforming the image so that it looks ``disabled''. -@end table - -@item :mask @var{mask} -If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build -a clipping mask for the image, so that the background of a frame is -visible behind the image. If @var{bg} is not specified, or if @var{bg} -is @code{t}, determine the background color of the image by looking at -the four corners of the image, assuming the most frequently occurring -color from the corners is the background color of the image. Otherwise, -@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})} -specifying the color to assume for the background of the image. - -If @var{mask} is @code{nil}, remove a mask from the image, if it has -one. Images in some formats include a mask which can be removed by -specifying @code{:mask nil}. - -@item :pointer @var{shape} -This specifies the pointer shape when the mouse pointer is over this -image. @xref{Pointer Shape}, for available pointer shapes. - -@item :map @var{map} -@cindex image maps -This associates an image map of @dfn{hot spots} with this image. - -An image map is an alist where each element has the format -@code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified -as either a rectangle, a circle, or a polygon. - -A rectangle is a cons -@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))} -which specifies the pixel coordinates of the upper left and bottom right -corners of the rectangle area. - -A circle is a cons -@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))} -which specifies the center and the radius of the circle; @var{r} may -be a float or integer. - -A polygon is a cons -@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])} -where each pair in the vector describes one corner in the polygon. - -When the mouse pointer lies on a hot-spot area of an image, the -@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo} -property, that defines a tool-tip for the hot-spot, and if it contains -a @code{pointer} property, that defines the shape of the mouse cursor when -it is on the hot-spot. -@xref{Pointer Shape}, for available pointer shapes. - -When you click the mouse when the mouse pointer is over a hot-spot, an -event is composed by combining the @var{id} of the hot-spot with the -mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's -@var{id} is @code{area4}. -@end table - -@defun image-mask-p spec &optional frame -This function returns @code{t} if image @var{spec} has a mask bitmap. -@var{frame} is the frame on which the image will be displayed. -@var{frame} @code{nil} or omitted means to use the selected frame -(@pxref{Input Focus}). -@end defun - -@node XBM Images -@subsection XBM Images -@cindex XBM - - To use XBM format, specify @code{xbm} as the image type. This image -format doesn't require an external library, so images of this type are -always supported. - - Additional image properties supported for the @code{xbm} image type are: - -@table @code -@item :foreground @var{foreground} -The value, @var{foreground}, should be a string specifying the image -foreground color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 1. The default is the frame's -foreground color. - -@item :background @var{background} -The value, @var{background}, should be a string specifying the image -background color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 0. The default is the frame's -background color. -@end table - - If you specify an XBM image using data within Emacs instead of an -external file, use the following three properties: - -@table @code -@item :data @var{data} -The value, @var{data}, specifies the contents of the image. -There are three formats you can use for @var{data}: - -@itemize @bullet -@item -A vector of strings or bool-vectors, each specifying one line of the -image. Do specify @code{:height} and @code{:width}. - -@item -A string containing the same byte sequence as an XBM file would contain. -You must not specify @code{:height} and @code{:width} in this case, -because omitting them is what indicates the data has the format of an -XBM file. The file contents specify the height and width of the image. - -@item -A string or a bool-vector containing the bits of the image (plus perhaps -some extra bits at the end that will not be used). It should contain at -least @var{width} * @code{height} bits. In this case, you must specify -@code{:height} and @code{:width}, both to indicate that the string -contains just the bits rather than a whole XBM file, and to specify the -size of the image. -@end itemize - -@item :width @var{width} -The value, @var{width}, specifies the width of the image, in pixels. - -@item :height @var{height} -The value, @var{height}, specifies the height of the image, in pixels. -@end table - -@node XPM Images -@subsection XPM Images -@cindex XPM - - To use XPM format, specify @code{xpm} as the image type. The -additional image property @code{:color-symbols} is also meaningful with -the @code{xpm} image type: - -@table @code -@item :color-symbols @var{symbols} -The value, @var{symbols}, should be an alist whose elements have the -form @code{(@var{name} . @var{color})}. In each element, @var{name} is -the name of a color as it appears in the image file, and @var{color} -specifies the actual color to use for displaying that name. -@end table - -@node PostScript Images -@subsection PostScript Images -@cindex postscript images - - To use PostScript for an image, specify image type @code{postscript}. -This works only if you have Ghostscript installed. You must always use -these three properties: - -@table @code -@item :pt-width @var{width} -The value, @var{width}, specifies the width of the image measured in -points (1/72 inch). @var{width} must be an integer. - -@item :pt-height @var{height} -The value, @var{height}, specifies the height of the image in points -(1/72 inch). @var{height} must be an integer. - -@item :bounding-box @var{box} -The value, @var{box}, must be a list or vector of four integers, which -specifying the bounding box of the PostScript image, analogous to the -@samp{BoundingBox} comment found in PostScript files. - -@example -%%BoundingBox: 22 171 567 738 -@end example -@end table - -@node ImageMagick Images -@subsection ImageMagick Images -@cindex ImageMagick images -@cindex images, support for more formats - - If you build Emacs with ImageMagick support, you can use the -ImageMagick library to load many image formats (@pxref{File -Conveniences,,, emacs, The GNU Emacs Manual}). The image type symbol -for images loaded via ImageMagick is @code{imagemagick}, regardless of -the actual underlying image format. - -@defun imagemagick-types -This function returns a list of image file extensions supported by the -current ImageMagick installation. Each list element is a symbol -representing an internal ImageMagick name for an image type, such as -@code{BMP} for @file{.bmp} images. -@end defun - -@defopt imagemagick-enabled-types -The value of this variable is a list of ImageMagick image types which -Emacs may attempt to render using ImageMagick. Each list element -should be one of the symbols in the list returned by -@code{imagemagick-types}, or an equivalent string. Alternatively, a -value of @code{t} enables ImageMagick for all possible image types. -Regardless of the value of this variable, -@code{imagemagick-types-inhibit} (see below) takes precedence. -@end defopt - -@defopt imagemagick-types-inhibit -The value of this variable lists the ImageMagick image types which -should never be rendered using ImageMagick, regardless of the value of -@code{imagemagick-enabled-types}. A value of @code{t} disables -ImageMagick entirely. -@end defopt - -@defvar image-format-suffixes -This variable is an alist mapping image types to file name extensions. -Emacs uses this in conjunction with the @code{:format} image property -(see below) to give a hint to the ImageMagick library as to the type -of an image. Each element has the form @code{(@var{type} -@var{extension})}, where @var{type} is a symbol specifying an image -content-type, and @var{extension} is a string that specifies the -associated file name extension. -@end defvar - - Images loaded with ImageMagick support the following additional -image descriptor properties: - -@table @code -@item :background @var{background} -@var{background}, if non-@code{nil}, should be a string specifying a -color, which is used as the image's background color if the image -supports transparency. If the value is @code{nil}, it defaults to the -frame's background color. - -@item :width @var{width}, :height @var{height} -The @code{:width} and @code{:height} keywords are used for scaling the -image. If only one of them is specified, the other one will be -calculated so as to preserve the aspect ratio. If both are specified, -aspect ratio may not be preserved. - -@item :max-width @var{max-width}, :max-height @var{max-height} -The @code{:max-width} and @code{:max-height} keywords are used for -scaling if the size of the image of the image exceeds these values. -If @code{:width} is set it will have precedence over @code{max-width}, -and if @code{:height} is set it will have precedence over -@code{max-height}, but you can otherwise mix these keywords as you -wish. @code{:max-width} and @code{:max-height} will always preserve -the aspect ratio. - -@item :format @var{type} -The value, @var{type}, should be a symbol specifying the type of the -image data, as found in @code{image-format-suffixes}. This is used -when the image does not have an associated file name, to provide a -hint to ImageMagick to help it detect the image type. - -@item :rotation @var{angle} -Specifies a rotation angle in degrees. - -@item :index @var{frame} -@c Doesn't work: http://debbugs.gnu.org/7978 -@xref{Multi-Frame Images}. -@end table - -@node Other Image Types -@subsection Other Image Types -@cindex PBM - - For PBM images, specify image type @code{pbm}. Color, gray-scale and -monochromatic images are supported. For mono PBM images, two additional -image properties are supported. - -@table @code -@item :foreground @var{foreground} -The value, @var{foreground}, should be a string specifying the image -foreground color, or @code{nil} for the default color. This color is -used for each pixel in the PBM that is 1. The default is the frame's -foreground color. - -@item :background @var{background} -The value, @var{background}, should be a string specifying the image -background color, or @code{nil} for the default color. This color is -used for each pixel in the PBM that is 0. The default is the frame's -background color. -@end table - -@noindent -The remaining image types that Emacs can support are: - -@table @asis -@item GIF -Image type @code{gif}. -Supports the @code{:index} property. @xref{Multi-Frame Images}. - -@item JPEG -Image type @code{jpeg}. - -@item PNG -Image type @code{png}. - -@item SVG -Image type @code{svg}. - -@item TIFF -Image type @code{tiff}. -Supports the @code{:index} property. @xref{Multi-Frame Images}. -@end table - -@node Defining Images -@subsection Defining Images - - The functions @code{create-image}, @code{defimage} and -@code{find-image} provide convenient ways to create image descriptors. - -@defun create-image file-or-data &optional type data-p &rest props -This function creates and returns an image descriptor which uses the -data in @var{file-or-data}. @var{file-or-data} can be a file name or -a string containing the image data; @var{data-p} should be @code{nil} -for the former case, non-@code{nil} for the latter case. - -The optional argument @var{type} is a symbol specifying the image type. -If @var{type} is omitted or @code{nil}, @code{create-image} tries to -determine the image type from the file's first few bytes, or else -from the file's name. - -The remaining arguments, @var{props}, specify additional image -properties---for example, - -@c ':heuristic-mask' is not documented? -@example -(create-image "foo.xpm" 'xpm nil :heuristic-mask t) -@end example - -The function returns @code{nil} if images of this type are not -supported. Otherwise it returns an image descriptor. -@end defun - -@defmac defimage symbol specs &optional doc -This macro defines @var{symbol} as an image name. The arguments -@var{specs} is a list which specifies how to display the image. -The third argument, @var{doc}, is an optional documentation string. - -Each argument in @var{specs} has the form of a property list, and each -one should specify at least the @code{:type} property and either the -@code{:file} or the @code{:data} property. The value of @code{:type} -should be a symbol specifying the image type, the value of -@code{:file} is the file to load the image from, and the value of -@code{:data} is a string containing the actual image data. Here is an -example: - -@example -(defimage test-image - ((:type xpm :file "~/test1.xpm") - (:type xbm :file "~/test1.xbm"))) -@end example - -@code{defimage} tests each argument, one by one, to see if it is -usable---that is, if the type is supported and the file exists. The -first usable argument is used to make an image descriptor which is -stored in @var{symbol}. - -If none of the alternatives will work, then @var{symbol} is defined -as @code{nil}. -@end defmac - -@defun find-image specs -This function provides a convenient way to find an image satisfying one -of a list of image specifications @var{specs}. - -Each specification in @var{specs} is a property list with contents -depending on image type. All specifications must at least contain the -properties @code{:type @var{type}} and either @w{@code{:file @var{file}}} -or @w{@code{:data @var{data}}}, where @var{type} is a symbol specifying -the image type, e.g., @code{xbm}, @var{file} is the file to load the -image from, and @var{data} is a string containing the actual image data. -The first specification in the list whose @var{type} is supported, and -@var{file} exists, is used to construct the image specification to be -returned. If no specification is satisfied, @code{nil} is returned. - -The image is looked for in @code{image-load-path}. -@end defun - -@defvar image-load-path -This variable's value is a list of locations in which to search for -image files. If an element is a string or a variable symbol whose -value is a string, the string is taken to be the name of a directory -to search. If an element is a variable symbol whose value is a list, -that is taken to be a list of directory names to search. - -The default is to search in the @file{images} subdirectory of the -directory specified by @code{data-directory}, then the directory -specified by @code{data-directory}, and finally in the directories in -@code{load-path}. Subdirectories are not automatically included in -the search, so if you put an image file in a subdirectory, you have to -supply the subdirectory name explicitly. For example, to find the -image @file{images/foo/bar.xpm} within @code{data-directory}, you -should specify the image as follows: - -@example -(defimage foo-image '((:type xpm :file "foo/bar.xpm"))) -@end example -@end defvar - -@defun image-load-path-for-library library image &optional path no-error -This function returns a suitable search path for images used by the -Lisp package @var{library}. - -The function searches for @var{image} first using @code{image-load-path}, -excluding @file{@code{data-directory}/images}, and then in -@code{load-path}, followed by a path suitable for @var{library}, which -includes @file{../../etc/images} and @file{../etc/images} relative to -the library file itself, and finally in -@file{@code{data-directory}/images}. - -Then this function returns a list of directories which contains first -the directory in which @var{image} was found, followed by the value of -@code{load-path}. If @var{path} is given, it is used instead of -@code{load-path}. - -If @var{no-error} is non-@code{nil} and a suitable path can't be -found, don't signal an error. Instead, return a list of directories as -before, except that @code{nil} appears in place of the image directory. - -Here is an example of using @code{image-load-path-for-library}: - -@example -(defvar image-load-path) ; shush compiler -(let* ((load-path (image-load-path-for-library - "mh-e" "mh-logo.xpm")) - (image-load-path (cons (car load-path) - image-load-path))) - (mh-tool-bar-folder-buttons-init)) -@end example -@end defun - -@node Showing Images -@subsection Showing Images - - You can use an image descriptor by setting up the @code{display} -property yourself, but it is easier to use the functions in this -section. - -@defun insert-image image &optional string area slice -This function inserts @var{image} in the current buffer at point. The -value @var{image} should be an image descriptor; it could be a value -returned by @code{create-image}, or the value of a symbol defined with -@code{defimage}. The argument @var{string} specifies the text to put -in the buffer to hold the image. If it is omitted or @code{nil}, -@code{insert-image} uses @code{" "} by default. - -The argument @var{area} specifies whether to put the image in a margin. -If it is @code{left-margin}, the image appears in the left margin; -@code{right-margin} specifies the right margin. If @var{area} is -@code{nil} or omitted, the image is displayed at point within the -buffer's text. - -The argument @var{slice} specifies a slice of the image to insert. If -@var{slice} is @code{nil} or omitted the whole image is inserted. -Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width} -@var{height})} which specifies the @var{x} and @var{y} positions and -@var{width} and @var{height} of the image area to insert. Integer -values are in units of pixels. A floating-point number in the range -0.0--1.0 stands for that fraction of the width or height of the entire -image. - -Internally, this function inserts @var{string} in the buffer, and gives -it a @code{display} property which specifies @var{image}. @xref{Display -Property}. -@end defun - -@cindex slice, image -@cindex image slice -@defun insert-sliced-image image &optional string area rows cols -This function inserts @var{image} in the current buffer at point, like -@code{insert-image}, but splits the image into @var{rows}x@var{cols} -equally sized slices. - -If an image is inserted ``sliced'', Emacs displays each slice as a -separate image, and allow more intuitive scrolling up/down, instead of -jumping up/down the entire image when paging through a buffer that -displays (large) images. -@end defun - -@defun put-image image pos &optional string area -This function puts image @var{image} in front of @var{pos} in the -current buffer. The argument @var{pos} should be an integer or a -marker. It specifies the buffer position where the image should appear. -The argument @var{string} specifies the text that should hold the image -as an alternative to the default. - -The argument @var{image} must be an image descriptor, perhaps returned -by @code{create-image} or stored by @code{defimage}. - -The argument @var{area} specifies whether to put the image in a margin. -If it is @code{left-margin}, the image appears in the left margin; -@code{right-margin} specifies the right margin. If @var{area} is -@code{nil} or omitted, the image is displayed at point within the -buffer's text. - -Internally, this function creates an overlay, and gives it a -@code{before-string} property containing text that has a @code{display} -property whose value is the image. (Whew!) -@end defun - -@defun remove-images start end &optional buffer -This function removes images in @var{buffer} between positions -@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil}, -images are removed from the current buffer. - -This removes only images that were put into @var{buffer} the way -@code{put-image} does it, not images that were inserted with -@code{insert-image} or in other ways. -@end defun - -@defun image-size spec &optional pixels frame -@cindex size of image -This function returns the size of an image as a pair -@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image -specification. @var{pixels} non-@code{nil} means return sizes -measured in pixels, otherwise return sizes measured in canonical -character units (fractions of the width/height of the frame's default -font). @var{frame} is the frame on which the image will be displayed. -@var{frame} null or omitted means use the selected frame (@pxref{Input -Focus}). -@end defun - -@defvar max-image-size -This variable is used to define the maximum size of image that Emacs -will load. Emacs will refuse to load (and display) any image that is -larger than this limit. - -If the value is an integer, it directly specifies the maximum -image height and width, measured in pixels. If it is floating -point, it specifies the maximum image height and width -as a ratio to the frame height and width. If the value is -non-numeric, there is no explicit limit on the size of images. - -The purpose of this variable is to prevent unreasonably large images -from accidentally being loaded into Emacs. It only takes effect the -first time an image is loaded. Once an image is placed in the image -cache, it can always be displayed, even if the value of -@code{max-image-size} is subsequently changed (@pxref{Image Cache}). -@end defvar - -@node Multi-Frame Images -@subsection Multi-Frame Images -@cindex multi-frame images - -@cindex animation -@cindex image animation -@cindex image frames -Some image files can contain more than one image. We say that there -are multiple ``frames'' in the image. At present, Emacs supports -multiple frames for GIF, TIFF, and certain ImageMagick formats such as -DJVM@. - -The frames can be used either to represent multiple ``pages'' (this is -usually the case with multi-frame TIFF files, for example), or to -create animation (usually the case with multi-frame GIF files). - -A multi-frame image has a property @code{:index}, whose value is an -integer (counting from 0) that specifies which frame is being displayed. - -@defun image-multi-frame-p image -This function returns non-@code{nil} if @var{image} contains more than -one frame. The actual return value is a cons @code{(@var{nimages} -. @var{delay})}, where @var{nimages} is the number of frames and -@var{delay} is the delay in seconds between them, or @code{nil} -if the image does not specify a delay. Images that are intended to be -animated usually specify a frame delay, whereas ones that are intended -to be treated as multiple pages do not. -@end defun - -@defun image-current-frame image -This function returns the index of the current frame number for -@var{image}, counting from 0. -@end defun - -@defun image-show-frame image n &optional nocheck -This function switches @var{image} to frame number @var{n}. It -replaces a frame number outside the valid range with that of the end -of the range, unless @var{nocheck} is non-@code{nil}. If @var{image} -does not contain a frame with the specified number, the image displays -as a hollow box. -@end defun - -@defun image-animate image &optional index limit -This function animates @var{image}. The optional integer @var{index} -specifies the frame from which to start (default 0). The optional -argument @var{limit} controls the length of the animation. If omitted -or @code{nil}, the image animates once only; if @code{t} it loops -forever; if a number animation stops after that many seconds. -@end defun - -@vindex image-minimum-frame-delay -@vindex image-default-frame-delay -@noindent Animation operates by means of a timer. Note that Emacs imposes a -minimum frame delay of 0.01 (@code{image-minimum-frame-delay}) seconds. -If the image itself does not specify a delay, Emacs uses -@code{image-default-frame-delay}. - -@defun image-animate-timer image -This function returns the timer responsible for animating @var{image}, -if there is one. -@end defun - - -@node Image Cache -@subsection Image Cache -@cindex image cache - - Emacs caches images so that it can display them again more -efficiently. When Emacs displays an image, it searches the image -cache for an existing image specification @code{equal} to the desired -specification. If a match is found, the image is displayed from the -cache. Otherwise, Emacs loads the image normally. - -@defun image-flush spec &optional frame -This function removes the image with specification @var{spec} from the -image cache of frame @var{frame}. Image specifications are compared -using @code{equal}. If @var{frame} is @code{nil}, it defaults to the -selected frame. If @var{frame} is @code{t}, the image is flushed on -all existing frames. - -In Emacs's current implementation, each graphical terminal possesses an -image cache, which is shared by all the frames on that terminal -(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame -also refreshes it in all other frames on the same terminal. -@end defun - - One use for @code{image-flush} is to tell Emacs about a change in an -image file. If an image specification contains a @code{:file} -property, the image is cached based on the file's contents when the -image is first displayed. Even if the file subsequently changes, -Emacs continues displaying the old version of the image. Calling -@code{image-flush} flushes the image from the cache, forcing Emacs to -re-read the file the next time it needs to display that image. - - Another use for @code{image-flush} is for memory conservation. If -your Lisp program creates a large number of temporary images over a -period much shorter than @code{image-cache-eviction-delay} (see -below), you can opt to flush unused images yourself, instead of -waiting for Emacs to do it automatically. - -@defun clear-image-cache &optional filter -This function clears an image cache, removing all the images stored in -it. If @var{filter} is omitted or @code{nil}, it clears the cache for -the selected frame. If @var{filter} is a frame, it clears the cache -for that frame. If @var{filter} is @code{t}, all image caches are -cleared. Otherwise, @var{filter} is taken to be a file name, and all -images associated with that file name are removed from all image -caches. -@end defun - -If an image in the image cache has not been displayed for a specified -period of time, Emacs removes it from the cache and frees the -associated memory. - -@defvar image-cache-eviction-delay -This variable specifies the number of seconds an image can remain in -the cache without being displayed. When an image is not displayed for -this length of time, Emacs removes it from the image cache. - -Under some circumstances, if the number of images in the cache grows -too large, the actual eviction delay may be shorter than this. - -If the value is @code{nil}, Emacs does not remove images from the cache -except when you explicitly clear it. This mode can be useful for -debugging. -@end defvar - -@node Buttons -@section Buttons -@cindex buttons in buffers -@cindex clickable buttons in buffers - - The Button package defines functions for inserting and manipulating -@dfn{buttons} that can be activated with the mouse or via keyboard -commands. These buttons are typically used for various kinds of -hyperlinks. - - A button is essentially a set of text or overlay properties, -attached to a stretch of text in a buffer. These properties are -called @dfn{button properties}. One of these properties, the -@dfn{action property}, specifies a function which is called when the -user invokes the button using the keyboard or the mouse. The action -function may examine the button and use its other properties as -desired. - - In some ways, the Button package duplicates the functionality in the -Widget package. @xref{Top, , Introduction, widget, The Emacs Widget -Library}. The advantage of the Button package is that it is faster, -smaller, and simpler to program. From the point of view of the user, -the interfaces produced by the two packages are very similar. - -@menu -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. -@end menu - -@node Button Properties -@subsection Button Properties -@cindex button properties - - Each button has an associated list of properties defining its -appearance and behavior, and other arbitrary properties may be used -for application specific purposes. The following properties have -special meaning to the Button package: - -@table @code -@item action -@kindex action @r{(button property)} -The function to call when the user invokes the button, which is passed -the single argument @var{button}. By default this is @code{ignore}, -which does nothing. - -@item mouse-action -@kindex mouse-action @r{(button property)} -This is similar to @code{action}, and when present, will be used -instead of @code{action} for button invocations resulting from -mouse-clicks (instead of the user hitting @key{RET}). If not -present, mouse-clicks use @code{action} instead. - -@item face -@kindex face @r{(button property)} -This is an Emacs face controlling how buttons of this type are -displayed; by default this is the @code{button} face. - -@item mouse-face -@kindex mouse-face @r{(button property)} -This is an additional face which controls appearance during -mouse-overs (merged with the usual button face); by default this is -the usual Emacs @code{highlight} face. - -@item keymap -@kindex keymap @r{(button property)} -The button's keymap, defining bindings active within the button -region. By default this is the usual button region keymap, stored -in the variable @code{button-map}, which defines @key{RET} and -@key{mouse-2} to invoke the button. - -@item type -@kindex type @r{(button property)} -The button type. @xref{Button Types}. - -@item help-echo -@kindex help-index @r{(button property)} -A string displayed by the Emacs tool-tip help system; by default, -@code{"mouse-2, RET: Push this button"}. - -@item follow-link -@kindex follow-link @r{(button property)} -The follow-link property, defining how a @key{Mouse-1} click behaves -on this button, @xref{Clickable Text}. - -@item button -@kindex button @r{(button property)} -All buttons have a non-@code{nil} @code{button} property, which may be useful -in finding regions of text that comprise buttons (which is what the -standard button functions do). -@end table - - There are other properties defined for the regions of text in a -button, but these are not generally interesting for typical uses. - -@node Button Types -@subsection Button Types -@cindex button types - - Every button has a @dfn{button type}, which defines default values -for the button's properties. Button types are arranged in a -hierarchy, with specialized types inheriting from more general types, -so that it's easy to define special-purpose types of buttons for -specific tasks. - -@defun define-button-type name &rest properties -Define a `button type' called @var{name} (a symbol). -The remaining arguments -form a sequence of @var{property value} pairs, specifying default -property values for buttons with this type (a button's type may be set -by giving it a @code{type} property when creating the button, using -the @code{:type} keyword argument). - -In addition, the keyword argument @code{:supertype} may be used to -specify a button-type from which @var{name} inherits its default -property values. Note that this inheritance happens only when -@var{name} is defined; subsequent changes to a supertype are not -reflected in its subtypes. -@end defun - - Using @code{define-button-type} to define default properties for -buttons is not necessary---buttons without any specified type use the -built-in button-type @code{button}---but it is encouraged, since -doing so usually makes the resulting code clearer and more efficient. - -@node Making Buttons -@subsection Making Buttons -@cindex making buttons - - Buttons are associated with a region of text, using an overlay or -text properties to hold button-specific information, all of which are -initialized from the button's type (which defaults to the built-in -button type @code{button}). Like all Emacs text, the appearance of -the button is governed by the @code{face} property; by default (via -the @code{face} property inherited from the @code{button} button-type) -this is a simple underline, like a typical web-page link. - - For convenience, there are two sorts of button-creation functions, -those that add button properties to an existing region of a buffer, -called @code{make-...button}, and those that also insert the button -text, called @code{insert-...button}. - - The button-creation functions all take the @code{&rest} argument -@var{properties}, which should be a sequence of @var{property value} -pairs, specifying properties to add to the button; see @ref{Button -Properties}. In addition, the keyword argument @code{:type} may be -used to specify a button-type from which to inherit other properties; -see @ref{Button Types}. Any properties not explicitly specified -during creation will be inherited from the button's type (if the type -defines such a property). - - The following functions add a button using an overlay -(@pxref{Overlays}) to hold the button properties: - -@defun make-button beg end &rest properties -This makes a button from @var{beg} to @var{end} in the -current buffer, and returns it. -@end defun - -@defun insert-button label &rest properties -This insert a button with the label @var{label} at point, -and returns it. -@end defun - - The following functions are similar, but using text properties -(@pxref{Text Properties}) to hold the button properties. Such buttons -do not add markers to the buffer, so editing in the buffer does not -slow down if there is an extremely large numbers of buttons. However, -if there is an existing face text property on the text (e.g., a face -assigned by Font Lock mode), the button face may not be visible. Both -of these functions return the starting position of the new button. - -@defun make-text-button beg end &rest properties -This makes a button from @var{beg} to @var{end} in the current buffer, -using text properties. -@end defun - -@defun insert-text-button label &rest properties -This inserts a button with the label @var{label} at point, using text -properties. -@end defun - -@node Manipulating Buttons -@subsection Manipulating Buttons -@cindex manipulating buttons - -These are functions for getting and setting properties of buttons. -Often these are used by a button's invocation function to determine -what to do. - -Where a @var{button} parameter is specified, it means an object -referring to a specific button, either an overlay (for overlay -buttons), or a buffer-position or marker (for text property buttons). -Such an object is passed as the first argument to a button's -invocation function when it is invoked. - -@defun button-start button -Return the position at which @var{button} starts. -@end defun - -@defun button-end button -Return the position at which @var{button} ends. -@end defun - -@defun button-get button prop -Get the property of button @var{button} named @var{prop}. -@end defun - -@defun button-put button prop val -Set @var{button}'s @var{prop} property to @var{val}. -@end defun - -@defun button-activate button &optional use-mouse-action -Call @var{button}'s @code{action} property (i.e., invoke it). If -@var{use-mouse-action} is non-@code{nil}, try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. -@end defun - -@defun button-label button -Return @var{button}'s text label. -@end defun - -@defun button-type button -Return @var{button}'s button-type. -@end defun - -@defun button-has-type-p button type -Return @code{t} if @var{button} has button-type @var{type}, or one of -@var{type}'s subtypes. -@end defun - -@defun button-at pos -Return the button at position @var{pos} in the current buffer, or -@code{nil}. If the button at @var{pos} is a text property button, the -return value is a marker pointing to @var{pos}. -@end defun - -@defun button-type-put type prop val -Set the button-type @var{type}'s @var{prop} property to @var{val}. -@end defun - -@defun button-type-get type prop -Get the property of button-type @var{type} named @var{prop}. -@end defun - -@defun button-type-subtype-p type supertype -Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. -@end defun - -@node Button Buffer Commands -@subsection Button Buffer Commands -@cindex button buffer commands - -These are commands and functions for locating and operating on -buttons in an Emacs buffer. - -@code{push-button} is the command that a user uses to actually `push' -a button, and is bound by default in the button itself to @key{RET} -and to @key{mouse-2} using a local keymap in the button's overlay or -text properties. Commands that are useful outside the buttons itself, -such as @code{forward-button} and @code{backward-button} are -additionally available in the keymap stored in -@code{button-buffer-map}; a mode which uses buttons may want to use -@code{button-buffer-map} as a parent keymap for its keymap. - -If the button has a non-@code{nil} @code{follow-link} property, and -@code{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click -will also activate the @code{push-button} command. -@xref{Clickable Text}. - -@deffn Command push-button &optional pos use-mouse-action -Perform the action specified by a button at location @var{pos}. -@var{pos} may be either a buffer position or a mouse-event. If -@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a -mouse-event (@pxref{Mouse Events}), try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. -@var{pos} defaults to point, except when @code{push-button} is invoked -interactively as the result of a mouse-event, in which case, the mouse -event's position is used. If there's no button at @var{pos}, do -nothing and return @code{nil}, otherwise return @code{t}. -@end deffn - -@deffn Command forward-button n &optional wrap display-message -Move to the @var{n}th next button, or @var{n}th previous button if -@var{n} is negative. If @var{n} is zero, move to the start of any -button at point. If @var{wrap} is non-@code{nil}, moving past either -end of the buffer continues from the other end. If -@var{display-message} is non-@code{nil}, the button's help-echo string -is displayed. Any button with a non-@code{nil} @code{skip} property -is skipped over. Returns the button found. -@end deffn - -@deffn Command backward-button n &optional wrap display-message -Move to the @var{n}th previous button, or @var{n}th next button if -@var{n} is negative. If @var{n} is zero, move to the start of any -button at point. If @var{wrap} is non-@code{nil}, moving past either -end of the buffer continues from the other end. If -@var{display-message} is non-@code{nil}, the button's help-echo string -is displayed. Any button with a non-@code{nil} @code{skip} property -is skipped over. Returns the button found. -@end deffn - -@defun next-button pos &optional count-current -@defunx previous-button pos &optional count-current -Return the next button after (for @code{next-button}) or before (for -@code{previous-button}) position @var{pos} in the current buffer. If -@var{count-current} is non-@code{nil}, count any button at @var{pos} -in the search, instead of starting at the next button. -@end defun - -@node Abstract Display -@section Abstract Display -@cindex ewoc -@cindex display, abstract -@cindex display, arbitrary objects -@cindex model/view/controller -@cindex view part, model/view/controller - - The Ewoc package constructs buffer text that represents a structure -of Lisp objects, and updates the text to follow changes in that -structure. This is like the ``view'' component in the -``model/view/controller'' design paradigm. Ewoc means ``Emacs's -Widget for Object Collections''. - - An @dfn{ewoc} is a structure that organizes information required to -construct buffer text that represents certain Lisp data. The buffer -text of the ewoc has three parts, in order: first, fixed @dfn{header} -text; next, textual descriptions of a series of data elements (Lisp -objects that you specify); and last, fixed @dfn{footer} text. -Specifically, an ewoc contains information on: - -@itemize @bullet -@item -The buffer which its text is generated in. - -@item -The text's start position in the buffer. - -@item -The header and footer strings. - -@item -@cindex node, ewoc -@c or "@cindex node, abstract display"? -A doubly-linked chain of @dfn{nodes}, each of which contains: - -@itemize -@item -A @dfn{data element}, a single Lisp object. - -@item -Links to the preceding and following nodes in the chain. -@end itemize - -@item -A @dfn{pretty-printer} function which is responsible for -inserting the textual representation of a data -element value into the current buffer. -@end itemize - - Typically, you define an ewoc with @code{ewoc-create}, and then pass -the resulting ewoc structure to other functions in the Ewoc package to -build nodes within it, and display it in the buffer. Once it is -displayed in the buffer, other functions determine the correspondence -between buffer positions and nodes, move point from one node's textual -representation to another, and so forth. @xref{Abstract Display -Functions}. - -@cindex encapsulation, ewoc -@c or "@cindex encapsulation, abstract display"? - A node @dfn{encapsulates} a data element much the way a variable -holds a value. Normally, encapsulation occurs as a part of adding a -node to the ewoc. You can retrieve the data element value and place a -new value in its place, like so: - -@lisp -(ewoc-data @var{node}) -@result{} value - -(ewoc-set-data @var{node} @var{new-value}) -@result{} @var{new-value} -@end lisp - -@noindent -You can also use, as the data element value, a Lisp object (list or -vector) that is a container for the ``real'' value, or an index into -some other structure. The example (@pxref{Abstract Display Example}) -uses the latter approach. - - When the data changes, you will want to update the text in the -buffer. You can update all nodes by calling @code{ewoc-refresh}, or -just specific nodes using @code{ewoc-invalidate}, or all nodes -satisfying a predicate using @code{ewoc-map}. Alternatively, you can -delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter}, -and add new nodes in their place. Deleting a node from an ewoc deletes -its associated textual description from buffer, as well. - -@menu -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. -@end menu - -@node Abstract Display Functions -@subsection Abstract Display Functions - - In this subsection, @var{ewoc} and @var{node} stand for the -structures described above (@pxref{Abstract Display}), while -@var{data} stands for an arbitrary Lisp object used as a data element. - -@defun ewoc-create pretty-printer &optional header footer nosep -This constructs and returns a new ewoc, with no nodes (and thus no data -elements). @var{pretty-printer} should be a function that takes one -argument, a data element of the sort you plan to use in this ewoc, and -inserts its textual description at point using @code{insert} (and never -@code{insert-before-markers}, because that would interfere with the -Ewoc package's internal mechanisms). - -Normally, a newline is automatically inserted after the header, -the footer and every node's textual description. If @var{nosep} -is non-@code{nil}, no newline is inserted. This may be useful for -displaying an entire ewoc on a single line, for example, or for -making nodes ``invisible'' by arranging for @var{pretty-printer} -to do nothing for those nodes. - -An ewoc maintains its text in the buffer that is current when -you create it, so switch to the intended buffer before calling -@code{ewoc-create}. -@end defun - -@defun ewoc-buffer ewoc -This returns the buffer where @var{ewoc} maintains its text. -@end defun - -@defun ewoc-get-hf ewoc -This returns a cons cell @code{(@var{header} . @var{footer})} -made from @var{ewoc}'s header and footer. -@end defun - -@defun ewoc-set-hf ewoc header footer -This sets the header and footer of @var{ewoc} to the strings -@var{header} and @var{footer}, respectively. -@end defun - -@defun ewoc-enter-first ewoc data -@defunx ewoc-enter-last ewoc data -These add a new node encapsulating @var{data}, putting it, respectively, -at the beginning or end of @var{ewoc}'s chain of nodes. -@end defun - -@defun ewoc-enter-before ewoc node data -@defunx ewoc-enter-after ewoc node data -These add a new node encapsulating @var{data}, adding it to -@var{ewoc} before or after @var{node}, respectively. -@end defun - -@defun ewoc-prev ewoc node -@defunx ewoc-next ewoc node -These return, respectively, the previous node and the next node of @var{node} -in @var{ewoc}. -@end defun - -@defun ewoc-nth ewoc n -This returns the node in @var{ewoc} found at zero-based index @var{n}. -A negative @var{n} means count from the end. @code{ewoc-nth} returns -@code{nil} if @var{n} is out of range. -@end defun - -@defun ewoc-data node -This extracts the data encapsulated by @var{node} and returns it. -@end defun - -@defun ewoc-set-data node data -This sets the data encapsulated by @var{node} to @var{data}. -@end defun - -@defun ewoc-locate ewoc &optional pos guess -This determines the node in @var{ewoc} which contains point (or -@var{pos} if specified), and returns that node. If @var{ewoc} has no -nodes, it returns @code{nil}. If @var{pos} is before the first node, -it returns the first node; if @var{pos} is after the last node, it returns -the last node. The optional third arg @var{guess} -should be a node that is likely to be near @var{pos}; this doesn't -alter the result, but makes the function run faster. -@end defun - -@defun ewoc-location node -This returns the start position of @var{node}. -@end defun - -@defun ewoc-goto-prev ewoc arg -@defunx ewoc-goto-next ewoc arg -These move point to the previous or next, respectively, @var{arg}th node -in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at -the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} -moves past the last node, returning @code{nil}. Excepting this special -case, these functions return the node moved to. -@end defun - -@defun ewoc-goto-node ewoc node -This moves point to the start of @var{node} in @var{ewoc}. -@end defun - -@defun ewoc-refresh ewoc -This function regenerates the text of @var{ewoc}. It works by -deleting the text between the header and the footer, i.e., all the -data elements' representations, and then calling the pretty-printer -function for each node, one by one, in order. -@end defun - -@defun ewoc-invalidate ewoc &rest nodes -This is similar to @code{ewoc-refresh}, except that only @var{nodes} in -@var{ewoc} are updated instead of the entire set. -@end defun - -@defun ewoc-delete ewoc &rest nodes -This deletes each node in @var{nodes} from @var{ewoc}. -@end defun - -@defun ewoc-filter ewoc predicate &rest args -This calls @var{predicate} for each data element in @var{ewoc} and -deletes those nodes for which @var{predicate} returns @code{nil}. -Any @var{args} are passed to @var{predicate}. -@end defun - -@defun ewoc-collect ewoc predicate &rest args -This calls @var{predicate} for each data element in @var{ewoc} -and returns a list of those elements for which @var{predicate} -returns non-@code{nil}. The elements in the list are ordered -as in the buffer. Any @var{args} are passed to @var{predicate}. -@end defun - -@defun ewoc-map map-function ewoc &rest args -This calls @var{map-function} for each data element in @var{ewoc} and -updates those nodes for which @var{map-function} returns non-@code{nil}. -Any @var{args} are passed to @var{map-function}. -@end defun - -@node Abstract Display Example -@subsection Abstract Display Example - - Here is a simple example using functions of the ewoc package to -implement a ``color components display'', an area in a buffer that -represents a vector of three integers (itself representing a 24-bit RGB -value) in various ways. - -@example -(setq colorcomp-ewoc nil - colorcomp-data nil - colorcomp-mode-map nil - colorcomp-labels ["Red" "Green" "Blue"]) - -(defun colorcomp-pp (data) - (if data - (let ((comp (aref colorcomp-data data))) - (insert (aref colorcomp-labels data) "\t: #x" - (format "%02X" comp) " " - (make-string (ash comp -2) ?#) "\n")) - (let ((cstr (format "#%02X%02X%02X" - (aref colorcomp-data 0) - (aref colorcomp-data 1) - (aref colorcomp-data 2))) - (samp " (sample text) ")) - (insert "Color\t: " - (propertize samp 'face - `(foreground-color . ,cstr)) - (propertize samp 'face - `(background-color . ,cstr)) - "\n")))) - -(defun colorcomp (color) - "Allow fiddling with COLOR in a new buffer. -The buffer is in Color Components mode." - (interactive "sColor (name or #RGB or #RRGGBB): ") - (when (string= "" color) - (setq color "green")) - (unless (color-values color) - (error "No such color: %S" color)) - (switch-to-buffer - (generate-new-buffer (format "originally: %s" color))) - (kill-all-local-variables) - (setq major-mode 'colorcomp-mode - mode-name "Color Components") - (use-local-map colorcomp-mode-map) - (erase-buffer) - (buffer-disable-undo) - (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8)) - (color-values color)))) - (ewoc (ewoc-create 'colorcomp-pp - "\nColor Components\n\n" - (substitute-command-keys - "\n\\@{colorcomp-mode-map@}")))) - (set (make-local-variable 'colorcomp-data) data) - (set (make-local-variable 'colorcomp-ewoc) ewoc) - (ewoc-enter-last ewoc 0) - (ewoc-enter-last ewoc 1) - (ewoc-enter-last ewoc 2) - (ewoc-enter-last ewoc nil))) -@end example - -@cindex controller part, model/view/controller - This example can be extended to be a ``color selection widget'' (in -other words, the controller part of the ``model/view/controller'' -design paradigm) by defining commands to modify @code{colorcomp-data} -and to ``finish'' the selection process, and a keymap to tie it all -together conveniently. - -@smallexample -(defun colorcomp-mod (index limit delta) - (let ((cur (aref colorcomp-data index))) - (unless (= limit cur) - (aset colorcomp-data index (+ cur delta))) - (ewoc-invalidate - colorcomp-ewoc - (ewoc-nth colorcomp-ewoc index) - (ewoc-nth colorcomp-ewoc -1)))) - -(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1)) -(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1)) -(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1)) -(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1)) -(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1)) -(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1)) - -(defun colorcomp-copy-as-kill-and-exit () - "Copy the color components into the kill ring and kill the buffer. -The string is formatted #RRGGBB (hash followed by six hex digits)." - (interactive) - (kill-new (format "#%02X%02X%02X" - (aref colorcomp-data 0) - (aref colorcomp-data 1) - (aref colorcomp-data 2))) - (kill-buffer nil)) - -(setq colorcomp-mode-map - (let ((m (make-sparse-keymap))) - (suppress-keymap m) - (define-key m "i" 'colorcomp-R-less) - (define-key m "o" 'colorcomp-R-more) - (define-key m "k" 'colorcomp-G-less) - (define-key m "l" 'colorcomp-G-more) - (define-key m "," 'colorcomp-B-less) - (define-key m "." 'colorcomp-B-more) - (define-key m " " 'colorcomp-copy-as-kill-and-exit) - m)) -@end smallexample - -Note that we never modify the data in each node, which is fixed when the -ewoc is created to be either @code{nil} or an index into the vector -@code{colorcomp-data}, the actual color components. - -@node Blinking -@section Blinking Parentheses -@cindex parenthesis matching -@cindex blinking parentheses -@cindex balancing parentheses - - This section describes the mechanism by which Emacs shows a matching -open parenthesis when the user inserts a close parenthesis. - -@defvar blink-paren-function -The value of this variable should be a function (of no arguments) to -be called whenever a character with close parenthesis syntax is inserted. -The value of @code{blink-paren-function} may be @code{nil}, in which -case nothing is done. -@end defvar - -@defopt blink-matching-paren -If this variable is @code{nil}, then @code{blink-matching-open} does -nothing. -@end defopt - -@defopt blink-matching-paren-distance -This variable specifies the maximum distance to scan for a matching -parenthesis before giving up. -@end defopt - -@defopt blink-matching-delay -This variable specifies the number of seconds to keep indicating the -matching parenthesis. A fraction of a second often gives good -results, but the default is 1, which works on all systems. -@end defopt - -@deffn Command blink-matching-open -This function is the default value of @code{blink-paren-function}. It -assumes that point follows a character with close parenthesis syntax -and applies the appropriate effect momentarily to the matching opening -character. If that character is not already on the screen, it -displays the character's context in the echo area. To avoid long -delays, this function does not search farther than -@code{blink-matching-paren-distance} characters. - -Here is an example of calling this function explicitly. - -@smallexample -@group -(defun interactive-blink-matching-open () - "Indicate momentarily the start of parenthesized sexp before point." - (interactive) -@end group -@group - (let ((blink-matching-paren-distance - (buffer-size)) - (blink-matching-paren t)) - (blink-matching-open))) -@end group -@end smallexample -@end deffn - -@node Character Display -@section Character Display - - This section describes how characters are actually displayed by -Emacs. Typically, a character is displayed as a @dfn{glyph} (a -graphical symbol which occupies one character position on the screen), -whose appearance corresponds to the character itself. For example, -the character @samp{a} (character code 97) is displayed as @samp{a}. -Some characters, however, are displayed specially. For example, the -formfeed character (character code 12) is usually displayed as a -sequence of two glyphs, @samp{^L}, while the newline character -(character code 10) starts a new screen line. - - You can modify how each character is displayed by defining a -@dfn{display table}, which maps each character code into a sequence of -glyphs. @xref{Display Tables}. - -@menu -* Usual Display:: The usual conventions for displaying characters. -* Display Tables:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. -* Glyphless Chars:: How glyphless characters are drawn. -@end menu - -@node Usual Display -@subsection Usual Display Conventions - - Here are the conventions for displaying each character code (in the -absence of a display table, which can override these -@iftex -conventions). -@end iftex -@ifnottex -conventions; @pxref{Display Tables}). -@end ifnottex - -@cindex printable ASCII characters -@itemize @bullet -@item -The @dfn{printable @acronym{ASCII} characters}, character codes 32 -through 126 (consisting of numerals, English letters, and symbols like -@samp{#}) are displayed literally. - -@item -The tab character (character code 9) displays as whitespace stretching -up to the next tab stop column. @xref{Text Display,,, emacs, The GNU -Emacs Manual}. The variable @code{tab-width} controls the number of -spaces per tab stop (see below). - -@item -The newline character (character code 10) has a special effect: it -ends the preceding line and starts a new line. - -@cindex ASCII control characters -@item -The non-printable @dfn{@acronym{ASCII} control characters}---character -codes 0 through 31, as well as the @key{DEL} character (character code -127)---display in one of two ways according to the variable -@code{ctl-arrow}. If this variable is non-@code{nil} (the default), -these characters are displayed as sequences of two glyphs, where the -first glyph is @samp{^} (a display table can specify a glyph to use -instead of @samp{^}); e.g., the @key{DEL} character is displayed as -@samp{^?}. - -If @code{ctl-arrow} is @code{nil}, these characters are displayed as -octal escapes (see below). - -This rule also applies to carriage return (character code 13), if that -character appears in the buffer. But carriage returns usually do not -appear in buffer text; they are eliminated as part of end-of-line -conversion (@pxref{Coding System Basics}). - -@cindex octal escapes -@item -@dfn{Raw bytes} are non-@acronym{ASCII} characters with codes 128 -through 255 (@pxref{Text Representations}). These characters display -as @dfn{octal escapes}: sequences of four glyphs, where the first -glyph is the @acronym{ASCII} code for @samp{\}, and the others are -digit characters representing the character code in octal. (A display -table can specify a glyph to use instead of @samp{\}.) - -@item -Each non-@acronym{ASCII} character with code above 255 is displayed -literally, if the terminal supports it. If the terminal does not -support it, the character is said to be @dfn{glyphless}, and it is -usually displayed using a placeholder glyph. For example, if a -graphical terminal has no font for a character, Emacs usually displays -a box containing the character code in hexadecimal. @xref{Glyphless -Chars}. -@end itemize - - The above display conventions apply even when there is a display -table, for any character whose entry in the active display table is -@code{nil}. Thus, when you set up a display table, you need only -specify the characters for which you want special behavior. - - The following variables affect how certain characters are displayed -on the screen. Since they change the number of columns the characters -occupy, they also affect the indentation functions. They also affect -how the mode line is displayed; if you want to force redisplay of the -mode line using the new values, call the function -@code{force-mode-line-update} (@pxref{Mode Line Format}). - -@defopt ctl-arrow -@cindex control characters in display -This buffer-local variable controls how control characters are -displayed. If it is non-@code{nil}, they are displayed as a caret -followed by the character: @samp{^A}. If it is @code{nil}, they are -displayed as octal escapes: a backslash followed by three octal -digits, as in @samp{\001}. -@end defopt - -@defopt tab-width -The value of this buffer-local variable is the spacing between tab -stops used for displaying tab characters in Emacs buffers. The value -is in units of columns, and the default is 8. Note that this feature -is completely independent of the user-settable tab stops used by the -command @code{tab-to-tab-stop}. @xref{Indent Tabs}. -@end defopt - -@node Display Tables -@subsection Display Tables - -@cindex display table - A display table is a special-purpose char-table -(@pxref{Char-Tables}), with @code{display-table} as its subtype, which -is used to override the usual character display conventions. This -section describes how to make, inspect, and assign elements to a -display table object. - -@defun make-display-table -This creates and returns a display table. The table initially has -@code{nil} in all elements. -@end defun - - The ordinary elements of the display table are indexed by character -codes; the element at index @var{c} says how to display the character -code @var{c}. The value should be @code{nil} (which means to display -the character @var{c} according to the usual display conventions; -@pxref{Usual Display}), or a vector of glyph codes (which means to -display the character @var{c} as those glyphs; @pxref{Glyphs}). - - @strong{Warning:} if you use the display table to change the display -of newline characters, the whole buffer will be displayed as one long -``line''. - - The display table also has six ``extra slots'' which serve special -purposes. Here is a table of their meanings; @code{nil} in any slot -means to use the default for that slot, as stated below. - -@table @asis -@item 0 -The glyph for the end of a truncated screen line (the default for this -is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses -arrows in the fringes to indicate truncation, so the display table has -no effect. - -@item 1 -The glyph for the end of a continued line (the default is @samp{\}). -On graphical terminals, Emacs uses curved arrows in the fringes to -indicate continuation, so the display table has no effect. - -@item 2 -The glyph for indicating a character displayed as an octal character -code (the default is @samp{\}). - -@item 3 -The glyph for indicating a control character (the default is @samp{^}). - -@item 4 -A vector of glyphs for indicating the presence of invisible lines (the -default is @samp{...}). @xref{Selective Display}. - -@item 5 -The glyph used to draw the border between side-by-side windows (the -default is @samp{|}). @xref{Splitting Windows}. This takes effect only -when there are no scroll bars; if scroll bars are supported and in use, -a scroll bar separates the two windows. -@end table - - For example, here is how to construct a display table that mimics -the effect of setting @code{ctl-arrow} to a non-@code{nil} value -(@pxref{Glyphs}, for the function @code{make-glyph-code}): - -@example -(setq disptab (make-display-table)) -(dotimes (i 32) - (or (= i ?\t) - (= i ?\n) - (aset disptab i - (vector (make-glyph-code ?^ 'escape-glyph) - (make-glyph-code (+ i 64) 'escape-glyph))))) -(aset disptab 127 - (vector (make-glyph-code ?^ 'escape-glyph) - (make-glyph-code ?? 'escape-glyph))))) -@end example - -@defun display-table-slot display-table slot -This function returns the value of the extra slot @var{slot} of -@var{display-table}. The argument @var{slot} may be a number from 0 to -5 inclusive, or a slot name (symbol). Valid symbols are -@code{truncation}, @code{wrap}, @code{escape}, @code{control}, -@code{selective-display}, and @code{vertical-border}. -@end defun - -@defun set-display-table-slot display-table slot value -This function stores @var{value} in the extra slot @var{slot} of -@var{display-table}. The argument @var{slot} may be a number from 0 to -5 inclusive, or a slot name (symbol). Valid symbols are -@code{truncation}, @code{wrap}, @code{escape}, @code{control}, -@code{selective-display}, and @code{vertical-border}. -@end defun - -@defun describe-display-table display-table -This function displays a description of the display table -@var{display-table} in a help buffer. -@end defun - -@deffn Command describe-current-display-table -This command displays a description of the current display table in a -help buffer. -@end deffn - -@node Active Display Table -@subsection Active Display Table -@cindex active display table - - Each window can specify a display table, and so can each buffer. -The window's display table, if there is one, takes precedence over the -buffer's display table. If neither exists, Emacs tries to use the -standard display table; if that is @code{nil}, Emacs uses the usual -character display conventions (@pxref{Usual Display}). - - Note that display tables affect how the mode line is displayed, so -if you want to force redisplay of the mode line using a new display -table, call @code{force-mode-line-update} (@pxref{Mode Line Format}). - -@defun window-display-table &optional window -This function returns @var{window}'s display table, or @code{nil} if -there is none. The default for @var{window} is the selected window. -@end defun - -@defun set-window-display-table window table -This function sets the display table of @var{window} to @var{table}. -The argument @var{table} should be either a display table or -@code{nil}. -@end defun - -@defvar buffer-display-table -This variable is automatically buffer-local in all buffers; its value -specifies the buffer's display table. If it is @code{nil}, there is -no buffer display table. -@end defvar - -@defvar standard-display-table -The value of this variable is the standard display table, which is -used when Emacs is displaying a buffer in a window with neither a -window display table nor a buffer display table defined. Its default -is @code{nil}. -@end defvar - -The @file{disp-table} library defines several functions for changing -the standard display table. - -@node Glyphs -@subsection Glyphs -@cindex glyph - -@cindex glyph code - A @dfn{glyph} is a graphical symbol which occupies a single -character position on the screen. Each glyph is represented in Lisp -as a @dfn{glyph code}, which specifies a character and optionally a -face to display it in (@pxref{Faces}). The main use of glyph codes is -as the entries of display tables (@pxref{Display Tables}). The -following functions are used to manipulate glyph codes: - -@defun make-glyph-code char &optional face -This function returns a glyph code representing char @var{char} with -face @var{face}. If @var{face} is omitted or @code{nil}, the glyph -uses the default face; in that case, the glyph code is an integer. If -@var{face} is non-@code{nil}, the glyph code is not necessarily an -integer object. -@end defun - -@defun glyph-char glyph -This function returns the character of glyph code @var{glyph}. -@end defun - -@defun glyph-face glyph -This function returns face of glyph code @var{glyph}, or @code{nil} if -@var{glyph} uses the default face. -@end defun - -@ifnottex - You can set up a @dfn{glyph table} to change how glyph codes are -actually displayed on text terminals. This feature is semi-obsolete; -use @code{glyphless-char-display} instead (@pxref{Glyphless Chars}). - -@defvar glyph-table -The value of this variable, if non-@code{nil}, is the current glyph -table. It takes effect only on character terminals; on graphical -displays, all glyphs are displayed literally. The glyph table should -be a vector whose @var{g}th element specifies how to display glyph -code @var{g}, where @var{g} is the glyph code for a glyph whose face -is unspecified. Each element should be one of the following: - -@table @asis -@item @code{nil} -Display this glyph literally. - -@item a string -Display this glyph by sending the specified string to the terminal. - -@item a glyph code -Display the specified glyph code instead. -@end table - -Any integer glyph code greater than or equal to the length of the -glyph table is displayed literally. -@end defvar -@end ifnottex - -@node Glyphless Chars -@subsection Glyphless Character Display -@cindex glyphless characters - - @dfn{Glyphless characters} are characters which are displayed in a -special way, e.g., as a box containing a hexadecimal code, instead of -being displayed literally. These include characters which are -explicitly defined to be glyphless, as well as characters for which -there is no available font (on a graphical display), and characters -which cannot be encoded by the terminal's coding system (on a text -terminal). - -@defvar glyphless-char-display -The value of this variable is a char-table which defines glyphless -characters and how they are displayed. Each entry must be one of the -following display methods: - -@table @asis -@item @code{nil} -Display the character in the usual way. - -@item @code{zero-width} -Don't display the character. - -@item @code{thin-space} -Display a thin space, 1-pixel wide on graphical displays, or -1-character wide on text terminals. - -@item @code{empty-box} -Display an empty box. - -@item @code{hex-code} -Display a box containing the Unicode codepoint of the character, in -hexadecimal notation. - -@item an @acronym{ASCII} string -Display a box containing that string. - -@item a cons cell @code{(@var{graphical} . @var{text})} -Display with @var{graphical} on graphical displays, and with -@var{text} on text terminals. Both @var{graphical} and @var{text} -must be one of the display methods described above. -@end table - -@noindent -The @code{thin-space}, @code{empty-box}, @code{hex-code}, and -@acronym{ASCII} string display methods are drawn with the -@code{glyphless-char} face. - -The char-table has one extra slot, which determines how to display any -character that cannot be displayed with any available font, or cannot -be encoded by the terminal's coding system. Its value should be one -of the above display methods, except @code{zero-width} or a cons cell. - -If a character has a non-@code{nil} entry in an active display table, -the display table takes effect; in this case, Emacs does not consult -@code{glyphless-char-display} at all. -@end defvar - -@defopt glyphless-char-display-control -This user option provides a convenient way to set -@code{glyphless-char-display} for groups of similar characters. Do -not set its value directly from Lisp code; the value takes effect only -via a custom @code{:set} function (@pxref{Variable Definitions}), -which updates @code{glyphless-char-display}. - -Its value should be an alist of elements @code{(@var{group} -. @var{method})}, where @var{group} is a symbol specifying a group of -characters, and @var{method} is a symbol specifying how to display -them. - -@var{group} should be one of the following: - -@table @code -@item c0-control -@acronym{ASCII} control characters @code{U+0000} to @code{U+001F}, -excluding the newline and tab characters (normally displayed as escape -sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed, -emacs, The GNU Emacs Manual}). - -@item c1-control -Non-@acronym{ASCII}, non-printing characters @code{U+0080} to -@code{U+009F} (normally displayed as octal escape sequences like -@samp{\230}). - -@item format-control -Characters of Unicode General Category `Cf', such as @samp{U+200E} -(Left-to-Right Mark), but excluding characters that have graphic -images, such as @samp{U+00AD} (Soft Hyphen). - -@item no-font -Characters for there is no suitable font, or which cannot be encoded -by the terminal's coding system. -@end table - -@c FIXME: this can also be `acronym', but that's not currently -@c completely implemented; it applies only to the format-control -@c group, and only works if the acronym is in `char-acronym-table'. -The @var{method} symbol should be one of @code{zero-width}, -@code{thin-space}, @code{empty-box}, or @code{hex-code}. These have -the same meanings as in @code{glyphless-char-display}, above. -@end defopt - -@node Beeping -@section Beeping -@cindex bell - - This section describes how to make Emacs ring the bell (or blink the -screen) to attract the user's attention. Be conservative about how -often you do this; frequent bells can become irritating. Also be -careful not to use just beeping when signaling an error is more -appropriate (@pxref{Errors}). - -@defun ding &optional do-not-terminate -@cindex keyboard macro termination -This function beeps, or flashes the screen (see @code{visible-bell} below). -It also terminates any keyboard macro currently executing unless -@var{do-not-terminate} is non-@code{nil}. -@end defun - -@defun beep &optional do-not-terminate -This is a synonym for @code{ding}. -@end defun - -@defopt visible-bell -This variable determines whether Emacs should flash the screen to -represent a bell. Non-@code{nil} means yes, @code{nil} means no. -This is effective on graphical displays, and on text terminals -provided the terminal's Termcap entry defines the visible bell -capability (@samp{vb}). -@end defopt - -@defvar ring-bell-function -If this is non-@code{nil}, it specifies how Emacs should ``ring the -bell''. Its value should be a function of no arguments. If this is -non-@code{nil}, it takes precedence over the @code{visible-bell} -variable. -@end defvar - -@node Window Systems -@section Window Systems - - Emacs works with several window systems, most notably the X Window -System. Both Emacs and X use the term ``window'', but use it -differently. An Emacs frame is a single window as far as X is -concerned; the individual Emacs windows are not known to X at all. - -@defvar window-system -This terminal-local variable tells Lisp programs what window system -Emacs is using for displaying the frame. The possible values are - -@table @code -@item x -@cindex X Window System -Emacs is displaying the frame using X. -@item w32 -Emacs is displaying the frame using native MS-Windows GUI. -@item ns -Emacs is displaying the frame using the Nextstep interface (used on -GNUstep and Mac OS X). -@item pc -Emacs is displaying the frame using MS-DOS direct screen writes. -@item nil -Emacs is displaying the frame on a character-based terminal. -@end table -@end defvar - -@defvar initial-window-system -This variable holds the value of @code{window-system} used for the -first frame created by Emacs during startup. (When Emacs is invoked -with the @option{--daemon} option, it does not create any initial -frames, so @code{initial-window-system} is @code{nil}. @xref{Initial -Options, daemon,, emacs, The GNU Emacs Manual}.) -@end defvar - -@defun window-system &optional frame -This function returns a symbol whose name tells what window system is -used for displaying @var{frame} (which defaults to the currently -selected frame). The list of possible symbols it returns is the same -one documented for the variable @code{window-system} above. -@end defun - - Do @emph{not} use @code{window-system} and -@code{initial-window-system} as predicates or boolean flag variables, -if you want to write code that works differently on text terminals and -graphic displays. That is because @code{window-system} is not a good -indicator of Emacs capabilities on a given display type. Instead, use -@code{display-graphic-p} or any of the other @code{display-*-p} -predicates described in @ref{Display Feature Testing}. - -@node Bidirectional Display -@section Bidirectional Display -@cindex bidirectional display -@cindex right-to-left text - - Emacs can display text written in scripts, such as Arabic, Farsi, -and Hebrew, whose natural ordering for horizontal text display runs -from right to left. Furthermore, segments of Latin script and digits -embedded in right-to-left text are displayed left-to-right, while -segments of right-to-left script embedded in left-to-right text -(e.g., Arabic or Hebrew text in comments or strings in a program -source file) are appropriately displayed right-to-left. We call such -mixtures of left-to-right and right-to-left text @dfn{bidirectional -text}. This section describes the facilities and options for editing -and displaying bidirectional text. - -@cindex logical order -@cindex reading order -@cindex visual order -@cindex unicode bidirectional algorithm -@cindex UBA -@cindex bidirectional reordering -@cindex reordering, of bidirectional text - Text is stored in Emacs buffers and strings in @dfn{logical} (or -@dfn{reading}) order, i.e., the order in which a human would read -each character. In right-to-left and bidirectional text, the order in -which characters are displayed on the screen (called @dfn{visual -order}) is not the same as logical order; the characters' screen -positions do not increase monotonically with string or buffer -position. In performing this @dfn{bidirectional reordering}, Emacs -follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}), -which is described in Annex #9 of the Unicode standard -(@url{http://www.unicode.org/reports/tr9/}). Emacs currently provides -a ``Non-isolate Bidirectionality'' class implementation of the -@acronym{UBA}: it does not yet support the isolate directional -formatting characters introduced with Unicode Standard v6.3.0. - -@defvar bidi-display-reordering -If the value of this buffer-local variable is non-@code{nil} (the -default), Emacs performs bidirectional reordering for display. The -reordering affects buffer text, as well as display strings and overlay -strings from text and overlay properties in the buffer (@pxref{Overlay -Properties}, and @pxref{Display Property}). If the value is -@code{nil}, Emacs does not perform bidirectional reordering in the -buffer. - -The default value of @code{bidi-display-reordering} controls the -reordering of strings which are not directly supplied by a buffer, -including the text displayed in mode lines (@pxref{Mode Line Format}) -and header lines (@pxref{Header Lines}). -@end defvar - -@cindex unibyte buffers, and bidi reordering - Emacs never reorders the text of a unibyte buffer, even if -@code{bidi-display-reordering} is non-@code{nil} in the buffer. This -is because unibyte buffers contain raw bytes, not characters, and thus -lack the directionality properties required for reordering. -Therefore, to test whether text in a buffer will be reordered for -display, it is not enough to test the value of -@code{bidi-display-reordering} alone. The correct test is this: - -@example - (if (and enable-multibyte-characters - bidi-display-reordering) - ;; Buffer is being reordered for display - ) -@end example - - However, unibyte display and overlay strings @emph{are} reordered if -their parent buffer is reordered. This is because plain-@sc{ascii} -strings are stored by Emacs as unibyte strings. If a unibyte display -or overlay string includes non-@sc{ascii} characters, these characters -are assumed to have left-to-right direction. - -@cindex display properties, and bidi reordering of text - Text covered by @code{display} text properties, by overlays with -@code{display} properties whose value is a string, and by any other -properties that replace buffer text, is treated as a single unit when -it is reordered for display. That is, the entire chunk of text -covered by these properties is reordered together. Moreover, the -bidirectional properties of the characters in such a chunk of text are -ignored, and Emacs reorders them as if they were replaced with a -single character @code{U+FFFC}, known as the @dfn{Object Replacement -Character}. This means that placing a display property over a portion -of text may change the way that the surrounding text is reordered for -display. To prevent this unexpected effect, always place such -properties on text whose directionality is identical with text that -surrounds it. - -@cindex base direction of a paragraph - Each paragraph of bidirectional text has a @dfn{base direction}, -either right-to-left or left-to-right. Left-to-right paragraphs are -displayed beginning at the left margin of the window, and are -truncated or continued when the text reaches the right margin. -Right-to-left paragraphs are displayed beginning at the right margin, -and are continued or truncated at the left margin. - - By default, Emacs determines the base direction of each paragraph by -looking at the text at its beginning. The precise method of -determining the base direction is specified by the @acronym{UBA}; in a -nutshell, the first character in a paragraph that has an explicit -directionality determines the base direction of the paragraph. -However, sometimes a buffer may need to force a certain base direction -for its paragraphs. For example, buffers containing program source -code should force all paragraphs to be displayed left-to-right. You -can use following variable to do this: - -@defvar bidi-paragraph-direction -If the value of this buffer-local variable is the symbol -@code{right-to-left} or @code{left-to-right}, all paragraphs in the -buffer are assumed to have that specified direction. Any other value -is equivalent to @code{nil} (the default), which means to determine -the base direction of each paragraph from its contents. - -@cindex @code{prog-mode}, and @code{bidi-paragraph-direction} -Modes for program source code should set this to @code{left-to-right}. -Prog mode does this by default, so modes derived from Prog mode do not -need to set this explicitly (@pxref{Basic Major Modes}). -@end defvar - -@defun current-bidi-paragraph-direction &optional buffer -This function returns the paragraph direction at point in the named -@var{buffer}. The returned value is a symbol, either -@code{left-to-right} or @code{right-to-left}. If @var{buffer} is -omitted or @code{nil}, it defaults to the current buffer. If the -buffer-local value of the variable @code{bidi-paragraph-direction} is -non-@code{nil}, the returned value will be identical to that value; -otherwise, the returned value reflects the paragraph direction -determined dynamically by Emacs. For buffers whose value of -@code{bidi-display-reordering} is @code{nil} as well as unibyte -buffers, this function always returns @code{left-to-right}. -@end defun - -@cindex visual-order cursor motion - Sometimes there's a need to move point in strict visual order, -either to the left or to the right of its current screen position. -Emacs provides a primitive to do that. - -@defun move-point-visually direction -This function moves point of the currently selected window to the -buffer position that appears immediately to the right or to the left -of point on the screen. If @var{direction} is positive, point will -move one screen position to the right, otherwise it will move one -screen position to the left. Note that, depending on the surrounding -bidirectional context, this could potentially move point many buffer -positions away. If invoked at the end of a screen line, the function -moves point to the rightmost or leftmost screen position of the next -or previous screen line, as appropriate for the value of -@var{direction}. - -The function returns the new buffer position as its value. -@end defun - -@cindex layout on display, and bidirectional text -@cindex jumbled display of bidirectional text -@cindex concatenating bidirectional strings - Bidirectional reordering can have surprising and unpleasant effects -when two strings with bidirectional content are juxtaposed in a -buffer, or otherwise programmatically concatenated into a string of -text. A typical problematic case is when a buffer consists of -sequences of text ``fields'' separated by whitespace or punctuation -characters, like Buffer Menu mode or Rmail Summary Mode. Because the -punctuation characters used as separators have @dfn{weak -directionality}, they take on the directionality of surrounding text. -As result, a numeric field that follows a field with bidirectional -content can be displayed @emph{to the left} of the preceding field, -messing up the expected layout. There are several ways to avoid this -problem: - -@itemize @minus -@item -Append the special character @code{U+200E}, LEFT-TO-RIGHT MARK, or -@acronym{LRM}, to the end of each field that may have bidirectional -content, or prepend it to the beginning of the following field. The -function @code{bidi-string-mark-left-to-right}, described below, comes -in handy for this purpose. (In a right-to-left paragraph, use -@code{U+200F}, RIGHT-TO-LEFT MARK, or @acronym{RLM}, instead.) This -is one of the solutions recommended by the UBA. - -@item -Include the tab character in the field separator. The tab character -plays the role of @dfn{segment separator} in bidirectional reordering, -causing the text on either side to be reordered separately. - -@cindex @code{space} display spec, and bidirectional text -@item -Separate fields with a @code{display} property or overlay with a -property value of the form @code{(space . PROPS)} (@pxref{Specified -Space}). Emacs treats this display specification as a @dfn{paragraph -separator}, and reorders the text on either side separately. -@end itemize - -@defun bidi-string-mark-left-to-right string -This function returns its argument @var{string}, possibly modified, -such that the result can be safely concatenated with another string, -or juxtaposed with another string in a buffer, without disrupting the -relative layout of this string and the next one on display. If the -string returned by this function is displayed as part of a -left-to-right paragraph, it will always appear on display to the left -of the text that follows it. The function works by examining the -characters of its argument, and if any of those characters could cause -reordering on display, the function appends the @acronym{LRM} -character to the string. The appended @acronym{LRM} character is made -invisible by giving it an @code{invisible} text property of @code{t} -(@pxref{Invisible Text}). -@end defun - - The reordering algorithm uses the bidirectional properties of the -characters stored as their @code{bidi-class} property -(@pxref{Character Properties}). Lisp programs can change these -properties by calling the @code{put-char-code-property} function. -However, doing this requires a thorough understanding of the -@acronym{UBA}, and is therefore not recommended. Any changes to the -bidirectional properties of a character have global effect: they -affect all Emacs frames and windows. - - Similarly, the @code{mirroring} property is used to display the -appropriate mirrored character in the reordered text. Lisp programs -can affect the mirrored display by changing this property. Again, any -such changes affect all of Emacs display. diff --git a/doc/lispref/doclicense.texi b/doc/lispref/doclicense.texi deleted file mode 100644 index 9c3bbe56e91..00000000000 --- a/doc/lispref/doclicense.texi +++ /dev/null @@ -1,505 +0,0 @@ -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, La@TeX{} input -format, SGML or XML using a publicly available -DTD, and standard-conforming simple HTML, -PostScript or PDF designed for human modification. Examples -of transparent image formats include PNG, XCF and -JPG@. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, SGML or -XML for which the DTD and/or processing tools are -not generally available, and the machine-generated HTML, -PostScript or PDF produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.''@: line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi deleted file mode 100644 index 85998fd3839..00000000000 --- a/doc/lispref/edebug.texi +++ /dev/null @@ -1,1635 +0,0 @@ -@comment -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1992-1994, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. - -@c This file can also be used by an independent Edebug User -@c Manual in which case the Edebug node below should be used -@c with the following links to the Bugs section and to the top level: - -@c , Bugs and Todo List, Top, Top - -@node Edebug -@section Edebug -@cindex Edebug debugging facility - - Edebug is a source-level debugger for Emacs Lisp programs, with which -you can: - -@itemize @bullet -@item -Step through evaluation, stopping before and after each expression. - -@item -Set conditional or unconditional breakpoints. - -@item -Stop when a specified condition is true (the global break event). - -@item -Trace slow or fast, stopping briefly at each stop point, or -at each breakpoint. - -@item -Display expression results and evaluate expressions as if outside of -Edebug. - -@item -Automatically re-evaluate a list of expressions and -display their results each time Edebug updates the display. - -@item -Output trace information on function calls and returns. - -@item -Stop when an error occurs. - -@item -Display a backtrace, omitting Edebug's own frames. - -@item -Specify argument evaluation for macros and defining forms. - -@item -Obtain rudimentary coverage testing and frequency counts. -@end itemize - -The first three sections below should tell you enough about Edebug to -start using it. - -@menu -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Modes: Edebug Execution Modes. Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Misc: Edebug Misc. Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Views: Edebug Views. Views inside and outside of Edebug. -* Eval: Edebug Eval. Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Options: Edebug Options. Option variables for customizing Edebug. -@end menu - -@node Using Edebug -@subsection Using Edebug - - To debug a Lisp program with Edebug, you must first @dfn{instrument} -the Lisp code that you want to debug. A simple way to do this is to -first move point into the definition of a function or macro and then do -@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See -@ref{Instrumenting}, for alternative ways to instrument code. - - Once a function is instrumented, any call to the function activates -Edebug. Depending on which Edebug execution mode you have selected, -activating Edebug may stop execution and let you step through the -function, or it may update the display and continue execution while -checking for debugging commands. The default execution mode is step, -which stops execution. @xref{Edebug Execution Modes}. - - Within Edebug, you normally view an Emacs buffer showing the source of -the Lisp code you are debugging. This is referred to as the @dfn{source -code buffer}, and it is temporarily read-only. - - An arrow in the left fringe indicates the line where the function is -executing. Point initially shows where within the line the function is -executing, but this ceases to be true if you move point yourself. - - If you instrument the definition of @code{fac} (shown below) and then -execute @code{(fac 3)}, here is what you would normally see. Point is -at the open-parenthesis before @code{if}. - -@example -(defun fac (n) -=>@point{}(if (< 0 n) - (* n (fac (1- n))) - 1)) -@end example - -@cindex stop points -The places within a function where Edebug can stop execution are called -@dfn{stop points}. These occur both before and after each subexpression -that is a list, and also after each variable reference. -Here we use periods to show the stop points in the function -@code{fac}: - -@example -(defun fac (n) - .(if .(< 0 n.). - .(* n. .(fac .(1- n.).).). - 1).) -@end example - -The special commands of Edebug are available in the source code buffer -in addition to the commands of Emacs Lisp mode. For example, you can -type the Edebug command @key{SPC} to execute until the next stop point. -If you type @key{SPC} once after entry to @code{fac}, here is the -display you will see: - -@example -(defun fac (n) -=>(if @point{}(< 0 n) - (* n (fac (1- n))) - 1)) -@end example - -When Edebug stops execution after an expression, it displays the -expression's value in the echo area. - -Other frequently used commands are @kbd{b} to set a breakpoint at a stop -point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to -exit Edebug and return to the top-level command loop. Type @kbd{?} to -display a list of all Edebug commands. - -@node Instrumenting -@subsection Instrumenting for Edebug -@cindex instrumenting for Edebug - - In order to use Edebug to debug Lisp code, you must first -@dfn{instrument} the code. Instrumenting code inserts additional code -into it, to invoke Edebug at the proper places. - -@kindex C-M-x -@findex eval-defun (Edebug) - When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a -prefix argument on a function definition, it instruments the -definition before evaluating it. (This does not modify the source -code itself.) If the variable @code{edebug-all-defs} is -non-@code{nil}, that inverts the meaning of the prefix argument: in -this case, @kbd{C-M-x} instruments the definition @emph{unless} it has -a prefix argument. The default value of @code{edebug-all-defs} is -@code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value -of the variable @code{edebug-all-defs}. - -@findex eval-region @r{(Edebug)} -@findex eval-buffer @r{(Edebug)} -@findex eval-current-buffer @r{(Edebug)} - If @code{edebug-all-defs} is non-@code{nil}, then the commands -@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} -also instrument any definitions they evaluate. Similarly, -@code{edebug-all-forms} controls whether @code{eval-region} should -instrument @emph{any} form, even non-defining forms. This doesn't apply -to loading or evaluations in the minibuffer. The command @kbd{M-x -edebug-all-forms} toggles this option. - -@findex edebug-eval-top-level-form -@findex edebug-defun - Another command, @kbd{M-x edebug-eval-top-level-form}, is available to -instrument any top-level form regardless of the values of -@code{edebug-all-defs} and @code{edebug-all-forms}. -@code{edebug-defun} is an alias for @code{edebug-eval-top-level-form}. - - While Edebug is active, the command @kbd{I} -(@code{edebug-instrument-callee}) instruments the definition of the -function or macro called by the list form after point, if it is not already -instrumented. This is possible only if Edebug knows where to find the -source for that function; for this reason, after loading Edebug, -@code{eval-region} records the position of every definition it -evaluates, even if not instrumenting it. See also the @kbd{i} command -(@pxref{Jumping}), which steps into the call after instrumenting the -function. - - Edebug knows how to instrument all the standard special forms, -@code{interactive} forms with an expression argument, anonymous lambda -expressions, and other defining forms. However, Edebug cannot determine -on its own what a user-defined macro will do with the arguments of a -macro call, so you must provide that information using Edebug -specifications; for details, @pxref{Edebug and Macros}. - - When Edebug is about to instrument code for the first time in a -session, it runs the hook @code{edebug-setup-hook}, then sets it to -@code{nil}. You can use this to load Edebug specifications -associated with a package you are using, but only when you use Edebug. - -@findex eval-expression @r{(Edebug)} - To remove instrumentation from a definition, simply re-evaluate its -definition in a way that does not instrument. There are two ways of -evaluating forms that never instrument them: from a file with -@code{load}, and from the minibuffer with @code{eval-expression} -(@kbd{M-:}). - - If Edebug detects a syntax error while instrumenting, it leaves point -at the erroneous code and signals an @code{invalid-read-syntax} error. -@c FIXME? I can't see that it "leaves point at the erroneous code". - - @xref{Edebug Eval}, for other evaluation functions available -inside of Edebug. - -@node Edebug Execution Modes -@subsection Edebug Execution Modes - -@cindex Edebug execution modes -Edebug supports several execution modes for running the program you are -debugging. We call these alternatives @dfn{Edebug execution modes}; do -not confuse them with major or minor modes. The current Edebug execution mode -determines how far Edebug continues execution before stopping---whether -it stops at each stop point, or continues to the next breakpoint, for -example---and how much Edebug displays the progress of the evaluation -before it stops. - -Normally, you specify the Edebug execution mode by typing a command to -continue the program in a certain mode. Here is a table of these -commands; all except for @kbd{S} resume execution of the program, at -least for a certain distance. - -@table @kbd -@item S -Stop: don't execute any more of the program, but wait for more -Edebug commands (@code{edebug-stop}). -@c FIXME Does not work. http://debbugs.gnu.org/9764 - -@item @key{SPC} -Step: stop at the next stop point encountered (@code{edebug-step-mode}). - -@item n -Next: stop at the next stop point encountered after an expression -(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in -@ref{Jumping}. - -@item t -Trace: pause (normally one second) at each Edebug stop point -(@code{edebug-trace-mode}). - -@item T -Rapid trace: update the display at each stop point, but don't actually -pause (@code{edebug-Trace-fast-mode}). - -@item g -Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}. - -@item c -Continue: pause one second at each breakpoint, and then continue -(@code{edebug-continue-mode}). - -@item C -Rapid continue: move point to each breakpoint, but don't pause -(@code{edebug-Continue-fast-mode}). - -@item G -Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You -can still stop the program by typing @kbd{S}, or any editing command. -@end table - -In general, the execution modes earlier in the above list run the -program more slowly or stop sooner than the modes later in the list. - -While executing or tracing, you can interrupt the execution by typing -any Edebug command. Edebug stops the program at the next stop point and -then executes the command you typed. For example, typing @kbd{t} during -execution switches to trace mode at the next stop point. You can use -@kbd{S} to stop execution without doing anything else. - -If your function happens to read input, a character you type intending -to interrupt execution may be read by the function instead. You can -avoid such unintended results by paying attention to when your program -wants input. - -@cindex keyboard macros (Edebug) -Keyboard macros containing the commands in this section do not -completely work: exiting from Edebug, to resume the program, loses track -of the keyboard macro. This is not easy to fix. Also, defining or -executing a keyboard macro outside of Edebug does not affect commands -inside Edebug. This is usually an advantage. See also the -@code{edebug-continue-kbd-macro} option in @ref{Edebug Options}. - -When you enter a new Edebug level, the initial execution mode comes -from the value of the variable @code{edebug-initial-mode} -(@pxref{Edebug Options}). By default, this specifies step mode. Note -that you may reenter the same Edebug level several times if, for -example, an instrumented function is called several times from one -command. - -@defopt edebug-sit-for-seconds -This option specifies how many seconds to wait between execution steps -in trace mode or continue mode. The default is 1 second. -@end defopt - -@node Jumping -@subsection Jumping - - The commands described in this section execute until they reach a -specified location. All except @kbd{i} make a temporary breakpoint to -establish the place to stop, then switch to go mode. Any other -breakpoint reached before the intended stop point will also stop -execution. @xref{Breakpoints}, for the details on breakpoints. - - These commands may fail to work as expected in case of nonlocal exit, -as that can bypass the temporary breakpoint where you expected the -program to stop. - -@table @kbd -@item h -Proceed to the stop point near where point is (@code{edebug-goto-here}). - -@item f -Run the program for one expression -(@code{edebug-forward-sexp}). - -@item o -Run the program until the end of the containing sexp (@code{edebug-step-out}). - -@item i -Step into the function or macro called by the form after point -(@code{edebug-step-in}). -@end table - -The @kbd{h} command proceeds to the stop point at or after the current -location of point, using a temporary breakpoint. - -The @kbd{f} command runs the program forward over one expression. More -precisely, it sets a temporary breakpoint at the position that -@code{forward-sexp} would reach, then executes in go mode so that -the program will stop at breakpoints. - -With a prefix argument @var{n}, the temporary breakpoint is placed -@var{n} sexps beyond point. If the containing list ends before @var{n} -more elements, then the place to stop is after the containing -expression. - -You must check that the position @code{forward-sexp} finds is a place -that the program will really get to. In @code{cond}, for example, -this may not be true. - -For flexibility, the @kbd{f} command does @code{forward-sexp} starting -at point, rather than at the stop point. If you want to execute one -expression @emph{from the current stop point}, first type @kbd{w} -(@code{edebug-where}) to move point there, and then type @kbd{f}. - -The @kbd{o} command continues ``out of'' an expression. It places a -temporary breakpoint at the end of the sexp containing point. If the -containing sexp is a function definition itself, @kbd{o} continues until -just before the last sexp in the definition. If that is where you are -now, it returns from the function and then stops. In other words, this -command does not exit the currently executing function unless you are -positioned after the last sexp. - -The @kbd{i} command steps into the function or macro called by the list -form after point, and stops at its first stop point. Note that the form -need not be the one about to be evaluated. But if the form is a -function call about to be evaluated, remember to use this command before -any of the arguments are evaluated, since otherwise it will be too late. - -The @kbd{i} command instruments the function or macro it's supposed to -step into, if it isn't instrumented already. This is convenient, but keep -in mind that the function or macro remains instrumented unless you explicitly -arrange to deinstrument it. - -@node Edebug Misc -@subsection Miscellaneous Edebug Commands - - Some miscellaneous Edebug commands are described here. - -@table @kbd -@item ? -Display the help message for Edebug (@code{edebug-help}). - -@item C-] -Abort one level back to the previous command level -(@code{abort-recursive-edit}). - -@item q -Return to the top level editor command loop (@code{top-level}). This -exits all recursive editing levels, including all levels of Edebug -activity. However, instrumented code protected with -@code{unwind-protect} or @code{condition-case} forms may resume -debugging. - -@item Q -Like @kbd{q}, but don't stop even for protected code -(@code{edebug-top-level-nonstop}). - -@item r -Redisplay the most recently known expression result in the echo area -(@code{edebug-previous-result}). - -@item d -Display a backtrace, excluding Edebug's own functions for clarity -(@code{edebug-backtrace}). - -You cannot use debugger commands in the backtrace buffer in Edebug as -you would in the standard debugger. - -The backtrace buffer is killed automatically when you continue -execution. -@end table - -You can invoke commands from Edebug that activate Edebug again -recursively. Whenever Edebug is active, you can quit to the top level -with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can -display a backtrace of all the pending evaluations with @kbd{d}. - -@node Breaks -@subsection Breaks - -Edebug's step mode stops execution when the next stop point is reached. -There are three other ways to stop Edebug execution once it has started: -breakpoints, the global break condition, and source breakpoints. - -@menu -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. -@end menu - -@node Breakpoints -@subsubsection Edebug Breakpoints - -@cindex breakpoints (Edebug) -While using Edebug, you can specify @dfn{breakpoints} in the program you -are testing: these are places where execution should stop. You can set a -breakpoint at any stop point, as defined in @ref{Using Edebug}. For -setting and unsetting breakpoints, the stop point that is affected is -the first one at or after point in the source code buffer. Here are the -Edebug commands for breakpoints: - -@table @kbd -@item b -Set a breakpoint at the stop point at or after point -(@code{edebug-set-breakpoint}). If you use a prefix argument, the -breakpoint is temporary---it turns off the first time it stops the -program. - -@item u -Unset the breakpoint (if any) at the stop point at or after -point (@code{edebug-unset-breakpoint}). - -@item x @var{condition} @key{RET} -Set a conditional breakpoint which stops the program only if -evaluating @var{condition} produces a non-@code{nil} value -(@code{edebug-set-conditional-breakpoint}). With a prefix argument, -the breakpoint is temporary. - -@item B -Move point to the next breakpoint in the current definition -(@code{edebug-next-breakpoint}). -@end table - -While in Edebug, you can set a breakpoint with @kbd{b} and unset one -with @kbd{u}. First move point to the Edebug stop point of your choice, -then type @kbd{b} or @kbd{u} to set or unset a breakpoint there. -Unsetting a breakpoint where none has been set has no effect. - -Re-evaluating or reinstrumenting a definition removes all of its -previous breakpoints. - -A @dfn{conditional breakpoint} tests a condition each time the program -gets there. Any errors that occur as a result of evaluating the -condition are ignored, as if the result were @code{nil}. To set a -conditional breakpoint, use @kbd{x}, and specify the condition -expression in the minibuffer. Setting a conditional breakpoint at a -stop point that has a previously established conditional breakpoint puts -the previous condition expression in the minibuffer so you can edit it. - -You can make a conditional or unconditional breakpoint -@dfn{temporary} by using a prefix argument with the command to set the -breakpoint. When a temporary breakpoint stops the program, it is -automatically unset. - -Edebug always stops or pauses at a breakpoint, except when the Edebug -mode is Go-nonstop. In that mode, it ignores breakpoints entirely. - -To find out where your breakpoints are, use the @kbd{B} command, which -moves point to the next breakpoint following point, within the same -function, or to the first breakpoint if there are no following -breakpoints. This command does not continue execution---it just moves -point in the buffer. - -@node Global Break Condition -@subsubsection Global Break Condition - -@cindex stopping on events -@cindex global break condition - A @dfn{global break condition} stops execution when a specified -condition is satisfied, no matter where that may occur. Edebug -evaluates the global break condition at every stop point; if it -evaluates to a non-@code{nil} value, then execution stops or pauses -depending on the execution mode, as if a breakpoint had been hit. If -evaluating the condition gets an error, execution does not stop. - -@findex edebug-set-global-break-condition - The condition expression is stored in -@code{edebug-global-break-condition}. You can specify a new expression -using the @kbd{X} command from the source code buffer while Edebug is -active, or using @kbd{C-x X X} from any buffer at any time, as long as -Edebug is loaded (@code{edebug-set-global-break-condition}). - - The global break condition is the simplest way to find where in your -code some event occurs, but it makes code run much more slowly. So you -should reset the condition to @code{nil} when not using it. - -@node Source Breakpoints -@subsubsection Source Breakpoints - -@findex edebug -@cindex source breakpoints - All breakpoints in a definition are forgotten each time you -reinstrument it. If you wish to make a breakpoint that won't be -forgotten, you can write a @dfn{source breakpoint}, which is simply a -call to the function @code{edebug} in your source code. You can, of -course, make such a call conditional. For example, in the @code{fac} -function, you can insert the first line as shown below, to stop when the -argument reaches zero: - -@example -(defun fac (n) - (if (= n 0) (edebug)) - (if (< 0 n) - (* n (fac (1- n))) - 1)) -@end example - - When the @code{fac} definition is instrumented and the function is -called, the call to @code{edebug} acts as a breakpoint. Depending on -the execution mode, Edebug stops or pauses there. - - If no instrumented code is being executed when @code{edebug} is called, -that function calls @code{debug}. -@c This may not be a good idea anymore. - -@node Trapping Errors -@subsection Trapping Errors - - Emacs normally displays an error message when an error is signaled and -not handled with @code{condition-case}. While Edebug is active and -executing instrumented code, it normally responds to all unhandled -errors. You can customize this with the options @code{edebug-on-error} -and @code{edebug-on-quit}; see @ref{Edebug Options}. - - When Edebug responds to an error, it shows the last stop point -encountered before the error. This may be the location of a call to a -function which was not instrumented, and within which the error actually -occurred. For an unbound variable error, the last known stop point -might be quite distant from the offending variable reference. In that -case, you might want to display a full backtrace (@pxref{Edebug Misc}). - -@c Edebug should be changed for the following: -- dan - If you change @code{debug-on-error} or @code{debug-on-quit} while -Edebug is active, these changes will be forgotten when Edebug becomes -inactive. Furthermore, during Edebug's recursive edit, these variables -are bound to the values they had outside of Edebug. - -@node Edebug Views -@subsection Edebug Views - - These Edebug commands let you view aspects of the buffer and window -status as they were before entry to Edebug. The outside window -configuration is the collection of windows and contents that were in -effect outside of Edebug. - -@table @kbd -@item v -Switch to viewing the outside window configuration -(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug. - -@item p -Temporarily display the outside current buffer with point at its -outside position (@code{edebug-bounce-point}), pausing for one second -before returning to Edebug. With a prefix argument @var{n}, pause for -@var{n} seconds instead. - -@item w -Move point back to the current stop point in the source code buffer -(@code{edebug-where}). - -If you use this command in a different window displaying the same -buffer, that window will be used instead to display the current -definition in the future. - -@item W -@c Its function is not simply to forget the saved configuration -- dan -Toggle whether Edebug saves and restores the outside window -configuration (@code{edebug-toggle-save-windows}). - -With a prefix argument, @code{W} only toggles saving and restoring of -the selected window. To specify a window that is not displaying the -source code buffer, you must use @kbd{C-x X W} from the global keymap. -@end table - - You can view the outside window configuration with @kbd{v} or just -bounce to the point in the current buffer with @kbd{p}, even if -it is not normally displayed. - - After moving point, you may wish to jump back to the stop point. -You can do that with @kbd{w} from a source code buffer. You can jump -back to the stop point in the source code buffer from any buffer using -@kbd{C-x X w}. - - Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the -saved outside window configuration---so that even if you turn saving -back @emph{on}, the current window configuration remains unchanged when -you next exit Edebug (by continuing the program). However, the -automatic redisplay of @file{*edebug*} and @file{*edebug-trace*} may -conflict with the buffers you wish to see unless you have enough windows -open. - -@node Edebug Eval -@subsection Evaluation - - While within Edebug, you can evaluate expressions as if Edebug -were not running. Edebug tries to be invisible to the expression's -evaluation and printing. Evaluation of expressions that cause side -effects will work as expected, except for changes to data that Edebug -explicitly saves and restores. @xref{The Outside Context}, for details -on this process. - -@table @kbd -@item e @var{exp} @key{RET} -Evaluate expression @var{exp} in the context outside of Edebug -(@code{edebug-eval-expression}). That is, Edebug tries to minimize its -interference with the evaluation. - -@item M-: @var{exp} @key{RET} -Evaluate expression @var{exp} in the context of Edebug itself -(@code{eval-expression}). - -@item C-x C-e -Evaluate the expression before point, in the context outside of Edebug -(@code{edebug-eval-last-sexp}). -@end table - -@cindex lexical binding (Edebug) - Edebug supports evaluation of expressions containing references to -lexically bound symbols created by the following constructs in -@file{cl.el}: @code{lexical-let}, @code{macrolet}, and -@code{symbol-macrolet}. -@c FIXME? What about lexical-binding = t? - -@node Eval List -@subsection Evaluation List Buffer - - You can use the @dfn{evaluation list buffer}, called @file{*edebug*}, to -evaluate expressions interactively. You can also set up the -@dfn{evaluation list} of expressions to be evaluated automatically each -time Edebug updates the display. - -@table @kbd -@item E -Switch to the evaluation list buffer @file{*edebug*} -(@code{edebug-visit-eval-list}). -@end table - - In the @file{*edebug*} buffer you can use the commands of Lisp -Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs -Manual}) as well as these special commands: - -@table @kbd -@item C-j -Evaluate the expression before point, in the outside context, and insert -the value in the buffer (@code{edebug-eval-print-last-sexp}). - -@item C-x C-e -Evaluate the expression before point, in the context outside of Edebug -(@code{edebug-eval-last-sexp}). - -@item C-c C-u -Build a new evaluation list from the contents of the buffer -(@code{edebug-update-eval-list}). - -@item C-c C-d -Delete the evaluation list group that point is in -(@code{edebug-delete-eval-item}). - -@item C-c C-w -Switch back to the source code buffer at the current stop point -(@code{edebug-where}). -@end table - - You can evaluate expressions in the evaluation list window with -@kbd{C-j} or @kbd{C-x C-e}, just as you would in @file{*scratch*}; -but they are evaluated in the context outside of Edebug. - - The expressions you enter interactively (and their results) are lost -when you continue execution; but you can set up an @dfn{evaluation list} -consisting of expressions to be evaluated each time execution stops. - -@cindex evaluation list group - To do this, write one or more @dfn{evaluation list groups} in the -evaluation list buffer. An evaluation list group consists of one or -more Lisp expressions. Groups are separated by comment lines. - - The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the -evaluation list, scanning the buffer and using the first expression of -each group. (The idea is that the second expression of the group is the -value previously computed and displayed.) - - Each entry to Edebug redisplays the evaluation list by inserting each -expression in the buffer, followed by its current value. It also -inserts comment lines so that each expression becomes its own group. -Thus, if you type @kbd{C-c C-u} again without changing the buffer text, -the evaluation list is effectively unchanged. - - If an error occurs during an evaluation from the evaluation list, -the error message is displayed in a string as if it were the result. -Therefore, expressions using variables that are not currently valid do -not interrupt your debugging. - - Here is an example of what the evaluation list window looks like after -several expressions have been added to it: - -@smallexample -(current-buffer) -# -;--------------------------------------------------------------- -(selected-window) -# -;--------------------------------------------------------------- -(point) -196 -;--------------------------------------------------------------- -bad-var -"Symbol's value as variable is void: bad-var" -;--------------------------------------------------------------- -(recursion-depth) -0 -;--------------------------------------------------------------- -this-command -eval-last-sexp -;--------------------------------------------------------------- -@end smallexample - -To delete a group, move point into it and type @kbd{C-c C-d}, or simply -delete the text for the group and update the evaluation list with -@kbd{C-c C-u}. To add a new expression to the evaluation list, insert -the expression at a suitable place, insert a new comment line, then type -@kbd{C-c C-u}. You need not insert dashes in the comment line---its -contents don't matter. - -After selecting @file{*edebug*}, you can return to the source code -buffer with @kbd{C-c C-w}. The @file{*edebug*} buffer is killed when -you continue execution, and recreated next time it is needed. - -@node Printing in Edebug -@subsection Printing in Edebug - -@cindex printing (Edebug) -@cindex printing circular structures -@pindex cust-print - If an expression in your program produces a value containing circular -list structure, you may get an error when Edebug attempts to print it. - - One way to cope with circular structure is to set @code{print-length} -or @code{print-level} to truncate the printing. Edebug does this for -you; it binds @code{print-length} and @code{print-level} to the values -of the variables @code{edebug-print-length} and -@code{edebug-print-level} (so long as they have non-@code{nil} -values). @xref{Output Variables}. - -@defopt edebug-print-length -If non-@code{nil}, Edebug binds @code{print-length} to this value while -printing results. The default value is @code{50}. -@end defopt - -@defopt edebug-print-level -If non-@code{nil}, Edebug binds @code{print-level} to this value while -printing results. The default value is @code{50}. -@end defopt - - You can also print circular structures and structures that share -elements more informatively by binding @code{print-circle} -to a non-@code{nil} value. - - Here is an example of code that creates a circular structure: - -@example -(setq a '(x y)) -(setcar a a) -@end example - -@noindent -Custom printing prints this as @samp{Result: #1=(#1# y)}. The -@samp{#1=} notation labels the structure that follows it with the label -@samp{1}, and the @samp{#1#} notation references the previously labeled -structure. This notation is used for any shared elements of lists or -vectors. - -@defopt edebug-print-circle -If non-@code{nil}, Edebug binds @code{print-circle} to this value while -printing results. The default value is @code{t}. -@end defopt - - Other programs can also use custom printing; see @file{cust-print.el} -for details. - -@node Trace Buffer -@subsection Trace Buffer -@cindex trace buffer - - Edebug can record an execution trace, storing it in a buffer named -@file{*edebug-trace*}. This is a log of function calls and returns, -showing the function names and their arguments and values. To enable -trace recording, set @code{edebug-trace} to a non-@code{nil} value. - - Making a trace buffer is not the same thing as using trace execution -mode (@pxref{Edebug Execution Modes}). - - When trace recording is enabled, each function entry and exit adds -lines to the trace buffer. A function entry record consists of -@samp{::::@{}, followed by the function name and argument values. A -function exit record consists of @samp{::::@}}, followed by the function -name and result of the function. - - The number of @samp{:}s in an entry shows its recursion depth. You -can use the braces in the trace buffer to find the matching beginning or -end of function calls. - -@findex edebug-print-trace-before -@findex edebug-print-trace-after - You can customize trace recording for function entry and exit by -redefining the functions @code{edebug-print-trace-before} and -@code{edebug-print-trace-after}. - -@defmac edebug-tracing string body@dots{} -This macro requests additional trace information around the execution -of the @var{body} forms. The argument @var{string} specifies text -to put in the trace buffer, after the @samp{@{} or @samp{@}}. All -the arguments are evaluated, and @code{edebug-tracing} returns the -value of the last form in @var{body}. -@end defmac - -@defun edebug-trace format-string &rest format-args -This function inserts text in the trace buffer. It computes the text -with @code{(apply 'format @var{format-string} @var{format-args})}. -It also appends a newline to separate entries. -@end defun - - @code{edebug-tracing} and @code{edebug-trace} insert lines in the -trace buffer whenever they are called, even if Edebug is not active. -Adding text to the trace buffer also scrolls its window to show the last -lines inserted. - -@node Coverage Testing -@subsection Coverage Testing - -@cindex coverage testing (Edebug) -@cindex frequency counts -@cindex performance analysis - Edebug provides rudimentary coverage testing and display of execution -frequency. - - Coverage testing works by comparing the result of each expression with -the previous result; each form in the program is considered ``covered'' -if it has returned two different values since you began testing coverage -in the current Emacs session. Thus, to do coverage testing on your -program, execute it under various conditions and note whether it behaves -correctly; Edebug will tell you when you have tried enough different -conditions that each form has returned two different values. - - Coverage testing makes execution slower, so it is only done if -@code{edebug-test-coverage} is non-@code{nil}. Frequency counting is -performed for all executions of an instrumented function, even if the -execution mode is Go-nonstop, and regardless of whether coverage testing -is enabled. - -@kindex C-x X = -@findex edebug-temp-display-freq-count - Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both -the coverage information and the frequency counts for a definition. -Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same -information temporarily, only until you type another key. - -@deffn Command edebug-display-freq-count -This command displays the frequency count data for each line of the -current definition. - -It inserts frequency counts as comment lines after each line of code. -You can undo all insertions with one @code{undo} command. The counts -appear under the @samp{(} before an expression or the @samp{)} after -an expression, or on the last character of a variable. To simplify -the display, a count is not shown if it is equal to the count of an -earlier expression on the same line. - -The character @samp{=} following the count for an expression says that -the expression has returned the same value each time it was evaluated. -In other words, it is not yet ``covered'' for coverage testing purposes. - -To clear the frequency count and coverage data for a definition, -simply reinstrument it with @code{eval-defun}. -@end deffn - -For example, after evaluating @code{(fac 5)} with a source -breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when -the breakpoint is reached, the frequency data looks like this: - -@example -(defun fac (n) - (if (= n 0) (edebug)) -;#6 1 = =5 - (if (< 0 n) -;#5 = - (* n (fac (1- n))) -;# 5 0 - 1)) -;# 0 -@end example - -The comment lines show that @code{fac} was called 6 times. The -first @code{if} statement returned 5 times with the same result each -time; the same is true of the condition on the second @code{if}. -The recursive call of @code{fac} did not return at all. - - -@node The Outside Context -@subsection The Outside Context - -Edebug tries to be transparent to the program you are debugging, but it -does not succeed completely. Edebug also tries to be transparent when -you evaluate expressions with @kbd{e} or with the evaluation list -buffer, by temporarily restoring the outside context. This section -explains precisely what context Edebug restores, and how Edebug fails to -be completely transparent. - -@menu -* Checking Whether to Stop:: When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. -@end menu - -@node Checking Whether to Stop -@subsubsection Checking Whether to Stop - -Whenever Edebug is entered, it needs to save and restore certain data -before even deciding whether to make trace information or stop the -program. - -@itemize @bullet -@item -@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both -increased to reduce Edebug's impact on the stack. You could, however, -still run out of stack space when using Edebug. - -@item -The state of keyboard macro execution is saved and restored. While -Edebug is active, @code{executing-kbd-macro} is bound to @code{nil} -unless @code{edebug-continue-kbd-macro} is non-@code{nil}. -@end itemize - - -@node Edebug Display Update -@subsubsection Edebug Display Update - -@c This paragraph is not filled, because LaLiberte's conversion script -@c needs an xref to be on just one line. -When Edebug needs to display something (e.g., in trace mode), it saves -the current window configuration from ``outside'' Edebug -(@pxref{Window Configurations}). When you exit Edebug, it restores -the previous window configuration. - -Emacs redisplays only when it pauses. Usually, when you continue -execution, the program re-enters Edebug at a breakpoint or after -stepping, without pausing or reading input in between. In such cases, -Emacs never gets a chance to redisplay the ``outside'' configuration. -Consequently, what you see is the same window configuration as the last -time Edebug was active, with no interruption. - -Entry to Edebug for displaying something also saves and restores the -following data (though some of them are deliberately not restored if an -error or quit signal occurs). - -@itemize @bullet -@item -@cindex current buffer point and mark (Edebug) -Which buffer is current, and the positions of point and the mark in the -current buffer, are saved and restored. - -@item -@cindex window configuration (Edebug) -The outside window configuration is saved and restored if -@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}). - -The window configuration is not restored on error or quit, but the -outside selected window @emph{is} reselected even on error or quit in -case a @code{save-excursion} is active. If the value of -@code{edebug-save-windows} is a list, only the listed windows are saved -and restored. - -The window start and horizontal scrolling of the source code buffer are -not restored, however, so that the display remains coherent within Edebug. - -@item -The value of point in each displayed buffer is saved and restored if -@code{edebug-save-displayed-buffer-points} is non-@code{nil}. - -@item -The variables @code{overlay-arrow-position} and -@code{overlay-arrow-string} are saved and restored, so you can safely -invoke Edebug from the recursive edit elsewhere in the same buffer. - -@item -@code{cursor-in-echo-area} is locally bound to @code{nil} so that -the cursor shows up in the window. -@end itemize - -@node Edebug Recursive Edit -@subsubsection Edebug Recursive Edit - -When Edebug is entered and actually reads commands from the user, it -saves (and later restores) these additional data: - -@itemize @bullet -@item -The current match data. @xref{Match Data}. - -@item -The variables @code{last-command}, @code{this-command}, -@code{last-command-event}, @code{last-input-event}, -@code{last-event-frame}, @code{last-nonmenu-event}, and -@code{track-mouse}. Commands in Edebug do not affect these variables -outside of Edebug. - -Executing commands within Edebug can change the key sequence that -would be returned by @code{this-command-keys}, and there is no way to -reset the key sequence from Lisp. - -Edebug cannot save and restore the value of -@code{unread-command-events}. Entering Edebug while this variable has a -nontrivial value can interfere with execution of the program you are -debugging. - -@item -Complex commands executed while in Edebug are added to the variable -@code{command-history}. In rare cases this can alter execution. - -@item -Within Edebug, the recursion depth appears one deeper than the recursion -depth outside Edebug. This is not true of the automatically updated -evaluation list window. - -@item -@code{standard-output} and @code{standard-input} are bound to @code{nil} -by the @code{recursive-edit}, but Edebug temporarily restores them during -evaluations. - -@item -The state of keyboard macro definition is saved and restored. While -Edebug is active, @code{defining-kbd-macro} is bound to -@code{edebug-continue-kbd-macro}. -@end itemize - -@node Edebug and Macros -@subsection Edebug and Macros - -To make Edebug properly instrument expressions that call macros, some -extra care is needed. This subsection explains the details. - -@menu -* Instrumenting Macro Calls:: The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. -@end menu - -@node Instrumenting Macro Calls -@subsubsection Instrumenting Macro Calls - - When Edebug instruments an expression that calls a Lisp macro, it needs -additional information about the macro to do the job properly. This is -because there is no a-priori way to tell which subexpressions of the -macro call are forms to be evaluated. (Evaluation may occur explicitly -in the macro body, or when the resulting expansion is evaluated, or any -time later.) - - Therefore, you must define an Edebug specification for each macro -that Edebug will encounter, to explain the format of calls to that -macro. To do this, add a @code{debug} declaration to the macro -definition. Here is a simple example that shows the specification for -the @code{for} example macro (@pxref{Argument Evaluation}). - -@smallexample -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - (declare (debug (symbolp "from" form "to" form "do" &rest form))) - ...) -@end smallexample - - The Edebug specification says which parts of a call to the macro are -forms to be evaluated. For simple macros, the specification -often looks very similar to the formal argument list of the macro -definition, but specifications are much more general than macro -arguments. @xref{Defining Macros}, for more explanation of -the @code{declare} form. - -@c See, e.g., http://debbugs.gnu.org/10577 -@c FIXME Maybe there should be an Edebug option to get it to -@c automatically load the entire source file containing the function -@c being instrumented. That would avoid this. - Take care to ensure that the specifications are known to Edebug when -you instrument code. If you are instrumenting a function from a file -that uses @code{eval-when-compile} to require another file containing -macro definitions, you may need to explicitly load that file. - - You can also define an edebug specification for a macro separately -from the macro definition with @code{def-edebug-spec}. Adding -@code{debug} declarations is preferred, and more convenient, for macro -definitions in Lisp, but @code{def-edebug-spec} makes it possible to -define Edebug specifications for special forms implemented in C. - -@defmac def-edebug-spec macro specification -Specify which expressions of a call to macro @var{macro} are forms to be -evaluated. @var{specification} should be the edebug specification. -Neither argument is evaluated. - -The @var{macro} argument can actually be any symbol, not just a macro -name. -@end defmac - -Here is a table of the possibilities for @var{specification} and how each -directs processing of arguments. - -@table @asis -@item @code{t} -All arguments are instrumented for evaluation. - -@item @code{0} -None of the arguments is instrumented. - -@item a symbol -The symbol must have an Edebug specification, which is used instead. -This indirection is repeated until another kind of specification is -found. This allows you to inherit the specification from another macro. - -@item a list -The elements of the list describe the types of the arguments of a -calling form. The possible elements of a specification list are -described in the following sections. -@end table - -If a macro has no Edebug specification, neither through a @code{debug} -declaration nor through a @code{def-edebug-spec} call, the variable -@code{edebug-eval-macro-args} comes into play. - -@defopt edebug-eval-macro-args -This controls the way Edebug treats macro arguments with no explicit -Edebug specification. If it is @code{nil} (the default), none of the -arguments is instrumented for evaluation. Otherwise, all arguments -are instrumented. -@end defopt - -@node Specification List -@subsubsection Specification List - -@cindex Edebug specification list -A @dfn{specification list} is required for an Edebug specification if -some arguments of a macro call are evaluated while others are not. Some -elements in a specification list match one or more arguments, but others -modify the processing of all following elements. The latter, called -@dfn{specification keywords}, are symbols beginning with @samp{&} (such -as @code{&optional}). - -A specification list may contain sublists, which match arguments that are -themselves lists, or it may contain vectors used for grouping. Sublists -and groups thus subdivide the specification list into a hierarchy of -levels. Specification keywords apply only to the remainder of the -sublist or group they are contained in. - -When a specification list involves alternatives or repetition, matching -it against an actual macro call may require backtracking. For more -details, @pxref{Backtracking}. - -Edebug specifications provide the power of regular expression matching, -plus some context-free grammar constructs: the matching of sublists with -balanced parentheses, recursive processing of forms, and recursion via -indirect specifications. - -Here's a table of the possible elements of a specification list, with -their meanings (see @ref{Specification Examples}, for the referenced -examples): - -@table @code -@item sexp -A single unevaluated Lisp object, which is not instrumented. -@c an "expression" is not necessarily intended for evaluation. - -@item form -A single evaluated expression, which is instrumented. - -@item place -A generalized variable. @xref{Generalized Variables}. - -@item body -Short for @code{&rest form}. See @code{&rest} below. - -@item function-form -A function form: either a quoted function symbol, a quoted lambda -expression, or a form (that should evaluate to a function symbol or -lambda expression). This is useful when an argument that's a lambda -expression might be quoted with @code{quote} rather than -@code{function}, since it instruments the body of the lambda expression -either way. - -@item lambda-expr -A lambda expression with no quoting. - -@item &optional -@c @kindex &optional @r{(Edebug)} -All following elements in the specification list are optional; as soon -as one does not match, Edebug stops matching at this level. - -To make just a few elements optional, followed by non-optional elements, -use @code{[&optional @var{specs}@dots{}]}. To specify that several -elements must all match or none, use @code{&optional -[@var{specs}@dots{}]}. See the @code{defun} example. - -@item &rest -@c @kindex &rest @r{(Edebug)} -All following elements in the specification list are repeated zero or -more times. In the last repetition, however, it is not a problem if the -expression runs out before matching all of the elements of the -specification list. - -To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}. -To specify several elements that must all match on every repetition, use -@code{&rest [@var{specs}@dots{}]}. - -@item &or -@c @kindex &or @r{(Edebug)} -Each of the following elements in the specification list is an -alternative. One of the alternatives must match, or the @code{&or} -specification fails. - -Each list element following @code{&or} is a single alternative. To -group two or more list elements as a single alternative, enclose them in -@code{[@dots{}]}. - -@item ¬ -@c @kindex ¬ @r{(Edebug)} -Each of the following elements is matched as alternatives as if by using -@code{&or}, but if any of them match, the specification fails. If none -of them match, nothing is matched, but the @code{¬} specification -succeeds. - -@c FIXME &key? - -@item &define -@c @kindex &define @r{(Edebug)} -Indicates that the specification is for a defining form. The defining -form itself is not instrumented (that is, Edebug does not stop before and -after the defining form), but forms inside it typically will be -instrumented. The @code{&define} keyword should be the first element in -a list specification. - -@item nil -This is successful when there are no more arguments to match at the -current argument list level; otherwise it fails. See sublist -specifications and the backquote example. - -@item gate -@cindex preventing backtracking -No argument is matched but backtracking through the gate is disabled -while matching the remainder of the specifications at this level. This -is primarily used to generate more specific syntax error messages. See -@ref{Backtracking}, for more details. Also see the @code{let} example. - -@item @var{other-symbol} -@cindex indirect specifications -Any other symbol in a specification list may be a predicate or an -indirect specification. - -If the symbol has an Edebug specification, this @dfn{indirect -specification} should be either a list specification that is used in -place of the symbol, or a function that is called to process the -arguments. The specification may be defined with @code{def-edebug-spec} -just as for macros. See the @code{defun} example. - -Otherwise, the symbol should be a predicate. The predicate is called -with the argument, and if the predicate returns @code{nil}, the -specification fails and the argument is not instrumented. - -Some suitable predicates include @code{symbolp}, @code{integerp}, -@code{stringp}, @code{vectorp}, and @code{atom}. - -@item [@var{elements}@dots{}] -@cindex [@dots{}] (Edebug) -A vector of elements groups the elements into a single @dfn{group -specification}. Its meaning has nothing to do with vectors. - -@item "@var{string}" -The argument should be a symbol named @var{string}. This specification -is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name -of @var{symbol} is the @var{string}, but the string form is preferred. - -@item (vector @var{elements}@dots{}) -The argument should be a vector whose elements must match the -@var{elements} in the specification. See the backquote example. - -@item (@var{elements}@dots{}) -Any other list is a @dfn{sublist specification} and the argument must be -a list whose elements match the specification @var{elements}. - -@cindex dotted lists (Edebug) -A sublist specification may be a dotted list and the corresponding list -argument may then be a dotted list. Alternatively, the last @sc{cdr} of a -dotted list specification may be another sublist specification (via a -grouping or an indirect specification, e.g., @code{(spec . [(more -specs@dots{})])}) whose elements match the non-dotted list arguments. -This is useful in recursive specifications such as in the backquote -example. Also see the description of a @code{nil} specification -above for terminating such recursion. - -Note that a sublist specification written as @code{(specs . nil)} -is equivalent to @code{(specs)}, and @code{(specs . -(sublist-elements@dots{}))} is equivalent to @code{(specs -sublist-elements@dots{})}. -@end table - -@c Need to document extensions with &symbol and :symbol - -Here is a list of additional specifications that may appear only after -@code{&define}. See the @code{defun} example. - -@table @code -@item name -The argument, a symbol, is the name of the defining form. - -A defining form is not required to have a name field; and it may have -multiple name fields. - -@item :name -This construct does not actually match an argument. The element -following @code{:name} should be a symbol; it is used as an additional -name component for the definition. You can use this to add a unique, -static component to the name of the definition. It may be used more -than once. - -@item arg -The argument, a symbol, is the name of an argument of the defining form. -However, lambda-list keywords (symbols starting with @samp{&}) -are not allowed. - -@item lambda-list -@cindex lambda-list (Edebug) -This matches a lambda list---the argument list of a lambda expression. - -@item def-body -The argument is the body of code in a definition. This is like -@code{body}, described above, but a definition body must be instrumented -with a different Edebug call that looks up information associated with -the definition. Use @code{def-body} for the highest level list of forms -within the definition. - -@item def-form -The argument is a single, highest-level form in a definition. This is -like @code{def-body}, except it is used to match a single form rather than -a list of forms. As a special case, @code{def-form} also means that -tracing information is not output when the form is executed. See the -@code{interactive} example. -@end table - -@node Backtracking -@subsubsection Backtracking in Specifications - -@cindex backtracking -@cindex syntax error (Edebug) -If a specification fails to match at some point, this does not -necessarily mean a syntax error will be signaled; instead, -@dfn{backtracking} will take place until all alternatives have been -exhausted. Eventually every element of the argument list must be -matched by some element in the specification, and every required element -in the specification must match some argument. - -When a syntax error is detected, it might not be reported until much -later, after higher-level alternatives have been exhausted, and with the -point positioned further from the real error. But if backtracking is -disabled when an error occurs, it can be reported immediately. Note -that backtracking is also reenabled automatically in several situations; -when a new alternative is established by @code{&optional}, -@code{&rest}, or @code{&or}, or at the start of processing a sublist, -group, or indirect specification. The effect of enabling or disabling -backtracking is limited to the remainder of the level currently being -processed and lower levels. - -Backtracking is disabled while matching any of the -form specifications (that is, @code{form}, @code{body}, @code{def-form}, and -@code{def-body}). These specifications will match any form so any error -must be in the form itself rather than at a higher level. - -Backtracking is also disabled after successfully matching a quoted -symbol or string specification, since this usually indicates a -recognized construct. But if you have a set of alternative constructs that -all begin with the same symbol, you can usually work around this -constraint by factoring the symbol out of the alternatives, e.g., -@code{["foo" &or [first case] [second case] ...]}. - -Most needs are satisfied by these two ways that backtracking is -automatically disabled, but occasionally it is useful to explicitly -disable backtracking by using the @code{gate} specification. This is -useful when you know that no higher alternatives could apply. See the -example of the @code{let} specification. - -@node Specification Examples -@subsubsection Specification Examples - -It may be easier to understand Edebug specifications by studying -the examples provided here. - -A @code{let} special form has a sequence of bindings and a body. Each -of the bindings is either a symbol or a sublist with a symbol and -optional expression. In the specification below, notice the @code{gate} -inside of the sublist to prevent backtracking once a sublist is found. - -@ignore -@c FIXME? The actual definition in edebug.el looks like this (and always -@c has AFAICS). In fact, nothing in edebug.el uses gate. So maybe -@c this is just an example for illustration? -(def-edebug-spec let - ((&rest - &or (symbolp &optional form) symbolp) - body)) -@end ignore -@example -(def-edebug-spec let - ((&rest - &or symbolp (gate symbolp &optional form)) - body)) -@end example - -Edebug uses the following specifications for @code{defun} and the -associated argument list and @code{interactive} specifications. It is -necessary to handle interactive forms specially since an expression -argument is actually evaluated outside of the function body. (The -specification for @code{defmacro} is very similar to that for -@code{defun}, but allows for the @code{declare} statement.) - -@smallexample -(def-edebug-spec defun - (&define name lambda-list - [&optional stringp] ; @r{Match the doc string, if present.} - [&optional ("interactive" interactive)] - def-body)) - -(def-edebug-spec lambda-list - (([&rest arg] - [&optional ["&optional" arg &rest arg]] - &optional ["&rest" arg] - ))) - -(def-edebug-spec interactive - (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}} -@end smallexample - -The specification for backquote below illustrates how to match -dotted lists and use @code{nil} to terminate recursion. It also -illustrates how components of a vector may be matched. (The actual -specification defined by Edebug is a little different, and does not -support dotted lists because doing so causes very deep recursion that -could fail.) - -@smallexample -(def-edebug-spec \` (backquote-form)) ; @r{Alias just for clarity.} - -(def-edebug-spec backquote-form - (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) - (backquote-form . [&or nil backquote-form]) - (vector &rest backquote-form) - sexp)) -@end smallexample - - -@node Edebug Options -@subsection Edebug Options - - These options affect the behavior of Edebug: -@c Previously defopt'd: -@c edebug-sit-for-seconds, edebug-print-length, edebug-print-level -@c edebug-print-circle, edebug-eval-macro-args - -@defopt edebug-setup-hook -Functions to call before Edebug is used. Each time it is set to a new -value, Edebug will call those functions once and then -reset @code{edebug-setup-hook} to @code{nil}. You could use this to -load up Edebug specifications associated with a package you are using, -but only when you also use Edebug. -@xref{Instrumenting}. -@end defopt - -@defopt edebug-all-defs -If this is non-@code{nil}, normal evaluation of defining forms such as -@code{defun} and @code{defmacro} instruments them for Edebug. This -applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer}, -and @code{eval-current-buffer}. - -Use the command @kbd{M-x edebug-all-defs} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-all-forms -If this is non-@code{nil}, the commands @code{eval-defun}, -@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer} -instrument all forms, even those that don't define anything. -This doesn't apply to loading or evaluations in the minibuffer. - -Use the command @kbd{M-x edebug-all-forms} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-save-windows -If this is non-@code{nil}, Edebug saves and restores the window -configuration. That takes some time, so if your program does not care -what happens to the window configurations, it is better to set this -variable to @code{nil}. - -If the value is a list, only the listed windows are saved and -restored. - -You can use the @kbd{W} command in Edebug to change this variable -interactively. @xref{Edebug Display Update}. -@end defopt - -@defopt edebug-save-displayed-buffer-points -If this is non-@code{nil}, Edebug saves and restores point in all -displayed buffers. - -Saving and restoring point in other buffers is necessary if you are -debugging code that changes the point of a buffer that is displayed in -a non-selected window. If Edebug or the user then selects the window, -point in that buffer will move to the window's value of point. - -Saving and restoring point in all buffers is expensive, since it -requires selecting each window twice, so enable this only if you need -it. @xref{Edebug Display Update}. -@end defopt - -@defopt edebug-initial-mode -If this variable is non-@code{nil}, it specifies the initial execution -mode for Edebug when it is first activated. Possible values are -@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace}, -@code{Trace-fast}, @code{continue}, and @code{Continue-fast}. - -The default value is @code{step}. -@xref{Edebug Execution Modes}. -@end defopt - -@defopt edebug-trace -If this is non-@code{nil}, trace each function entry and exit. -Tracing output is displayed in a buffer named @file{*edebug-trace*}, one -function entry or exit per line, indented by the recursion level. - -Also see @code{edebug-tracing}, in @ref{Trace Buffer}. -@end defopt - -@defopt edebug-test-coverage -If non-@code{nil}, Edebug tests coverage of all expressions debugged. -@xref{Coverage Testing}. -@end defopt - -@defopt edebug-continue-kbd-macro -If non-@code{nil}, continue defining or executing any keyboard macro -that is executing outside of Edebug. Use this with caution since it is not -debugged. -@xref{Edebug Execution Modes}. -@end defopt - -@defopt edebug-unwrap-results -If non-@code{nil}, Edebug tries to remove any of its own -instrumentation when showing the results of expressions. This is -relevant when debugging macros where the results of expressions are -themselves instrumented expressions. As a very artificial example, -suppose that the example function @code{fac} has been instrumented, -and consider a macro of the form: - -@c FIXME find a less silly example. -@smallexample -(defmacro test () "Edebug example." - (if (symbol-function 'fac) - @dots{})) -@end smallexample - -If you instrument the @code{test} macro and step through it, then by -default the result of the @code{symbol-function} call has numerous -@code{edebug-after} and @code{edebug-before} forms, which can make it -difficult to see the ``actual'' result. If -@code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove -these forms from the result. -@end defopt - -@defopt edebug-on-error -Edebug binds @code{debug-on-error} to this value, if -@code{debug-on-error} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - -@defopt edebug-on-quit -Edebug binds @code{debug-on-quit} to this value, if -@code{debug-on-quit} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - - If you change the values of @code{edebug-on-error} or -@code{edebug-on-quit} while Edebug is active, their values won't be used -until the @emph{next} time Edebug is invoked via a new command. -@c Not necessarily a deeper command level. -@c A new command is not precisely true, but that is close enough -- dan - -@defopt edebug-global-break-condition -If non-@code{nil}, an expression to test for at every stop point. If -the result is non-@code{nil}, then break. Errors are ignored. -@xref{Global Break Condition}. -@end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi deleted file mode 100644 index 973ee6f930c..00000000000 --- a/doc/lispref/elisp.texi +++ /dev/null @@ -1,1622 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename elisp - -@ifset VOL1 -@set volflag -@set voltitle Volume 1 -@end ifset - -@ifset VOL2 -@set volflag -@set voltitle Volume 2 -@end ifset - -@ifset volflag -@settitle GNU Emacs Lisp Reference Manual: @value{voltitle} -@end ifset -@ifclear volflag -@settitle GNU Emacs Lisp Reference Manual -@end ifclear - -@c %**end of header - -@c See two-volume-cross-refs.txt. -@tex -@ifset VOL1 -\message{Formatting for two volume edition...Volume 1...} -% -% Read special toc file, set up in two-volume.make. -\gdef\tocreadfilename{elisp1-toc-ready.toc} -% -% Don't make outlines, they're not needed and \readdatafile can't pay -% attention to the special definition above. -\global\let\pdfmakeoutlines=\relax -% -% Start volume 1 chapter numbering at 1; this must be listed as chapno0. -\global\chapno=0 -@end ifset -@ifset VOL2 -\message{Formatting for two volume edition...Volume 2...} -% -% Read special toc file, set up in two-volume.make. -\gdef\tocreadfilename{elisp2-toc-ready.toc} -% -% Don't make outlines, they're not needed and \readdatafile can't pay -% attention to the special definition above. -\global\let\pdfmakeoutlines=\relax -% -% Start volume 2 chapter numbering at 27; this must be listed as chapno26 -\global\chapno=26 -@end ifset -@end tex - - -@c Version of the manual and of Emacs. -@c (See comments for EDITION in emacs.texi) -@set VERSION 3.1 -@include emacsver.texi -@set DATE October 2014 - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. The manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@c @set smallbook - -@ifset volflag -@smallbook -@end ifset - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@c We use the "type index" to index new functions and variables. -@c @syncodeindex tp fn - -@copying -@iftex -This is edition @value{VERSION} of the @cite{GNU Emacs Lisp Reference Manual},@* -@end iftex -@ifnottex -This is the @cite{GNU Emacs Lisp Reference Manual} -@end ifnottex -corresponding to Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1990--1996, 1998--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License,'' with the -Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@documentencoding UTF-8 - -@dircategory Emacs lisp -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@titlepage -@title GNU Emacs Lisp Reference Manual -@ifset volflag -@subtitle @value{voltitle} -@end ifset -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, @value{DATE} - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman, -@author the GNU Manual Group, et al. -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - - -@c Print the tables of contents -@summarycontents -@contents - - -@ifnottex -@node Top -@top Emacs Lisp - -@ifset WWW_GNU_ORG -@html -

The homepage for GNU Emacs is at -http://www.gnu.org/software/emacs/.
-For information on using Emacs, refer to the -Emacs Manual.
-To view this manual in other formats, click -here. -@end html -@end ifset - -@insertcopying -@end ifnottex - -@menu -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Hash Tables:: Very fast lookup-tables. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. -* Customization:: Making variables and faces customizable. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple system-level windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Non-ASCII Characters:: Non-ASCII text in buffers and strings. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* Display:: Features for controlling the screen display. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. - -* Packaging:: Preparing Lisp code for distribution. - -Appendices - -* Antinews:: Info for users downgrading to Emacs 23. -* GNU Free Documentation License:: The license for this documentation. -* GPL:: Conditions for copying and changing GNU Emacs. -* Tips:: Advice and coding conventions for Emacs Lisp. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of some standard error symbols. -* Standard Keymaps:: List of some standard keymaps. -* Standard Hooks:: List of some standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - -@ignore -* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. -@end ignore - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are other nodes that are subnodes of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgments:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating-Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -Cons Cell and List Types - -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating-point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. - -Lists - -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. -* Property Lists:: A list of paired elements. - -Modifying Existing List Structure - -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Plist Access:: Accessing property lists stored elsewhere. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. -* Rings:: Managing a fixed-size ring of objects. - -Hash Tables - -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Symbol Properties:: Each symbol has a property list - for recording miscellaneous information. - -Symbol Properties - -* Symbol Plists:: Accessing symbol properties. -* Standard Properties:: Standard meanings of symbol properties. - -Evaluation - -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in - the program). -* Backquote:: Easier construction of list structure. -* Eval:: How to invoke the Lisp interpreter explicitly. - -Kinds of Forms - -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a - directory. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. -* Generalized Variables:: Extending the concept of variables. - -Scoping Rules for Variable Bindings - -* Dynamic Binding:: The default for binding local variables in Emacs. -* Dynamic Binding Tips:: Avoiding problems with dynamic binding. -* Lexical Binding:: A different type of local variable binding. -* Using Lexical Binding:: How to enable lexical binding. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. - -Generalized Variables - -* Setting Generalized Variables:: The @code{setf} macro. -* Adding Generalized Variables:: Defining new @code{setf} forms. - -Functions - -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Closures:: Functions that enclose a lexical environment. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Defining functions that the compiler - will expand inline. -* Declare Form:: Adding additional information about a function. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -Customization Settings - -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. -* Applying Customizations:: Functions to apply customization settings. -* Custom Themes:: Writing Custom themes. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, etc. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. - -Byte Compilation - -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Debugging Lisp Programs - -* Debugger:: A debugger for the Emacs Lisp evaluator. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. -* Profiling:: Measuring the resources that your code uses. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. - -Edebug - -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Edebug Execution Modes:: Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Edebug Misc:: Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Edebug Views:: Views inside and outside of Edebug. -* Edebug Eval:: Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Edebug Options:: Option variables for customizing Edebug. - -Breaks - -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. - -The Outside Context - -* Checking Whether to Stop::When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. - -Edebug and Macros - -* Instrumenting Macro Calls::The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing - functions do. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer names, variable names, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Variables:: Variables controlling completion behavior. -* Programmed Completion:: Writing your own completion function. -* Completion in Buffers:: Completing text in ordinary buffers. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. -* Generic Commands:: Select among command alternatives. - - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -Keymaps - -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. -* Easy Menu:: A convenience macro for defining menus. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding. -* Extended Menu Items:: More complex menu item definitions. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. - -Major and Minor Modes - -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: Providing a menu of definitions made in a buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Auto-Indentation:: How to teach Emacs to indent for a major mode. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. - -Hooks - -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. - -Major Modes - -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Basic Major Modes:: Modes that other modes are often derived from. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Tabulated List Mode:: Parent mode for buffers containing tabulated data. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Example Major Modes:: Text mode and Lisp modes. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. - -Mode Line Format - -* Mode Line Basics:: Basic ideas of mode line control. -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Top:: The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Refontify:: Controlling which region gets refontified - after a buffer change. - -Automatic Indentation of code - -* SMIE:: A simple minded indentation engine. - -Simple Minded Indentation Engine - -* SMIE setup:: SMIE setup and features. -* Operator Precedence Grammars:: A very simple parsing technique. -* SMIE Grammar:: Defining the grammar of a language. -* SMIE Lexer:: Defining tokens. -* SMIE Tricks:: Working around the parser's limitations. -* SMIE Indentation:: Specifying indentation rules. -* SMIE Indentation Helpers:: Helper functions for indentation rules. -* SMIE Indentation Example:: Sample indentation rules. -* SMIE Customization:: Customizing indentation. - -Documentation - -* Documentation Basics:: Where doc strings are defined and stored. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing permissions, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Special handling for certain file names. -* Format Conversion:: Conversion to and from various file formats. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: File sizes, modification times, etc. -* Extended Attributes:: Extended file attributes for access control. -* Locating Files:: How to find a file in standard places. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. - -File Format Conversion - -* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. -* Format Conversion Round-Trip:: Using @code{format-alist}. -* Format Conversion Piecemeal:: Specifying non-paired conversion. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - "behind Emacs's back". -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some - other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. - -Windows - -* Basic Windows:: Basic information on using windows. -* Windows and Frames:: Relating windows to the frame they appear on. -* Window Sizes:: Accessing a window's size. -* Resizing Windows:: Changing the sizes of windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Recombining Windows:: Preserving the frame layout when splitting and - deleting windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. -* Window History:: Each window remembers the buffers displayed in it. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Quitting Windows:: How to restore the state prior to displaying a - buffer. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections::Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers::Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for - later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix - from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Registers:: How registers are implemented. Accessing - the text or position stored in a register. -* Transposition:: Swapping two portions of a buffer. -* Decompression:: Dealing with compressed data. -* Base 64:: Conversion to or from base 64 encoding. -* Checksum/Hash:: Computing cryptographic hashes. -* Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. - -The Kill Ring - -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. - -Indentation - -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. - -Text Properties - -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. - -Non-@acronym{ASCII} Characters - -* Text Representations:: How Emacs represents text. -* Disabling Multibyte:: Controlling whether to use multibyte characters. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. - -Searching and Matching - -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. - -Syntax of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -Syntax Tables - -* Syntax Basics:: Basic concepts of syntax tables. -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -Abbrevs and Abbrev Expansion - -* Abbrev Tables:: Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Abbrev Files:: Saving abbrevs in files. -* Abbrev Expansion:: Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. - -Processes - -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for net connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. - -Receiving Output from Processes - -* Process Buffers:: By default, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. - -Low-Level Network Access - -* Network Processes:: Using @code{make-network-process}. -* Network Options:: Further control over network connections. -* Network Feature Testing:: Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Size of Displayed Text:: How large displayed text is. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style - for text characters: font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Window Dividers:: Separating windows visually. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs's Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Character Display:: How Emacs displays individual characters. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. -* Bidirectional Display:: Display of bidirectional scripts, such as - Arabic and Farsi. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize - their warnings. -* Warning Options:: Variables users set to control display of warnings. -* Delayed Warnings:: Deferring a warning until the end of a command. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Face Attributes:: What is in a face? -* Defining Faces:: How to define a face. -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Basic Faces:: Faces that are defined by default. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; adjusting the height, - spacing, and other properties of text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* PostScript Images:: Special features for PostScript format. -* ImageMagick Images:: Special features available through ImageMagick. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Multi-Frame Images:: Some images contain more than one frame. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Character Display - -* Usual Display:: The usual conventions for displaying characters. -* Display Tables:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. -* Glyphless Chars:: How glyphless characters are drawn. - -Operating System Interface - -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a - certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with - X Session Management. -* Desktop Notifications:: Desktop notifications. -* File Notifications:: File notifications. -* Dynamic Libraries:: On-demand loading of support libraries. - -Starting Up Emacs - -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. - -Getting Out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -Preparing Lisp code for distribution - -* Packaging Basics:: The basic concepts of Emacs Lisp packages. -* Simple Packages:: How to package a single .el file. -* Multi-file Packages:: How to package multiple files. -* Package Archives:: Maintaining package archives. - -Tips and Conventions - -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. - -GNU Emacs Internals - -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: Kludge to make preloaded Lisp functions shareable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end detailmenu -@end menu - -@ifclear VOL2 -@include intro.texi -@include objects.texi -@include numbers.texi -@include strings.texi - -@include lists.texi -@include sequences.texi -@include hash.texi -@include symbols.texi -@include eval.texi - -@include control.texi -@include variables.texi -@include functions.texi -@include macros.texi - -@include customize.texi -@include loading.texi -@include compile.texi - -@c This includes edebug.texi. -@include debugging.texi -@include streams.texi -@include minibuf.texi -@include commands.texi - -@include keymaps.texi -@include modes.texi -@include help.texi -@include files.texi - -@include backups.texi - -@end ifclear - -@c ================ Beginning of Volume 2 ================ -@ifclear VOL1 - -@include buffers.texi -@include windows.texi -@include frames.texi - -@include positions.texi -@include markers.texi -@include text.texi -@include nonascii.texi - -@include searching.texi -@include syntax.texi -@include abbrevs.texi -@include processes.texi - -@include display.texi -@include os.texi - -@include package.texi - -@c appendices - -@include anti.texi -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi -@node GPL -@appendix GNU General Public License -@include gpl.texi -@include tips.texi -@include internals.texi -@include errors.texi -@include maps.texi -@include hooks.texi - -@include index.texi - -@end ifclear - -@ignore -@node New Symbols -@unnumbered New Symbols Since the Previous Edition - -@printindex tp -@end ignore - -@bye - - -These words prevent "local variables" above from confusing Emacs. diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi deleted file mode 100644 index e00496e3478..00000000000 --- a/doc/lispref/errors.texi +++ /dev/null @@ -1,221 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2014 Free Software Foundation, -@c Inc. -@c See the file elisp.texi for copying conditions. -@node Standard Errors -@appendix Standard Errors -@cindex standard errors - - Here is a list of the more important error symbols in standard Emacs, grouped -by concept. The list includes each symbol's message and a cross reference -to a description of how the error can occur. - - Each error symbol has an set of parent error conditions that is a -list of symbols. Normally this list includes the error symbol itself -and the symbol @code{error}. Occasionally it includes additional -symbols, which are intermediate classifications, narrower than -@code{error} but broader than a single error symbol. For example, all -the errors in accessing files have the condition @code{file-error}. If -we do not say here that a certain error symbol has additional error -conditions, that means it has none. - - As a special exception, the error symbol @code{quit} does not have the -condition @code{error}, because quitting is not considered an error. - - Most of these error symbols are defined in C (mainly @file{data.c}), -but some are defined in Lisp. For example, the file @file{userlock.el} -defines the @code{file-locked} and @code{file-supersession} errors. -Several of the specialized Lisp libraries distributed with Emacs -define their own error symbols. We do not attempt to list of all -those here. - - @xref{Errors}, for an explanation of how errors are generated and -handled. - -@table @code -@item error -The message is @samp{error}. @xref{Errors}. - -@item quit -The message is @samp{Quit}. @xref{Quitting}. - -@item args-out-of-range -The message is @samp{Args out of range}. This happens when trying to -access an element beyond the range of a sequence, buffer, or other -container-like object. @xref{Sequences Arrays Vectors}, and -@xref{Text}. - -@item arith-error -The message is @samp{Arithmetic error}. This occurs when trying to -perform integer division by zero. @xref{Numeric Conversions}, and -@xref{Arithmetic Operations}. - -@item beginning-of-buffer -The message is @samp{Beginning of buffer}. @xref{Character Motion}. - -@item buffer-read-only -The message is @samp{Buffer is read-only}. @xref{Read Only Buffers}. - -@item circular-list -The message is @samp{List contains a loop}. This happens when a -circular structure is encountered. @xref{Circular Objects}. - -@item cl-assertion-failed -The message is @samp{Assertion failed}. This happens when the -@code{cl-assert} macro fails a test. @xref{Assertions,,, cl, Common Lisp -Extensions}. - -@item coding-system-error -The message is @samp{Invalid coding system}. @xref{Lisp and Coding -Systems}. - -@item cyclic-function-indirection -The message is @samp{Symbol's chain of function indirections contains -a loop}. @xref{Function Indirection}. - -@item cyclic-variable-indirection -The message is @samp{Symbol's chain of variable indirections contains -a loop}. @xref{Variable Aliases}. - -@item dbus-error -The message is @samp{D-Bus error}. This is only defined if Emacs was -compiled with D-Bus support. @xref{Errors and Events,,, dbus, D-Bus -integration in Emacs}. - -@item end-of-buffer -The message is @samp{End of buffer}. @xref{Character Motion}. - -@item end-of-file -The message is @samp{End of file during parsing}. Note that this is -not a subcategory of @code{file-error}, because it pertains to the -Lisp reader, not to file I/O@. @xref{Input Functions}. - -@item file-already-exists -This is a subcategory of @code{file-error}. @xref{Writing to Files}. - -@item file-date-error -This is a subcategory of @code{file-error}. It occurs when -@code{copy-file} tries and fails to set the last-modification time of -the output file. @xref{Changing Files}. - -@item file-error -We do not list the error-strings of this error and its subcategories, -because the error message is normally constructed from the data items -alone when the error condition @code{file-error} is present. Thus, -the error-strings are not very relevant. However, these error symbols -do have @code{error-message} properties, and if no data is provided, -the @code{error-message} property @emph{is} used. @xref{Files}. - -@c jka-compr.el -@item compression-error -This is a subcategory of @code{file-error}, which results from -problems handling a compressed file. @xref{How Programs Do Loading}. - -@c userlock.el -@item file-locked -This is a subcategory of @code{file-error}. @xref{File Locks}. - -@c userlock.el -@item file-supersession -This is a subcategory of @code{file-error}. @xref{Modification Time}. - -@c filenotify.el -@item file-notify-error -This is a subcategory of @code{file-error}. It happens, when a file -could not be watched for changes. @xref{File Notifications}. - -@c net/ange-ftp.el -@item ftp-error -This is a subcategory of @code{file-error}, which results from -problems in accessing a remote file using ftp. @xref{Remote Files,,, -emacs, The GNU Emacs Manual}. - -@item invalid-function -The message is @samp{Invalid function}. @xref{Function Indirection}. - -@item invalid-read-syntax -The message is @samp{Invalid read syntax}. @xref{Printed -Representation}. - -@item invalid-regexp -The message is @samp{Invalid regexp}. @xref{Regular Expressions}. - -@c simple.el -@item mark-inactive -The message is @samp{The mark is not active now}. @xref{The Mark}. - -@item no-catch -The message is @samp{No catch for tag}. @xref{Catch and Throw}. - -@ignore -@c Not actually used for anything? Probably definition should be removed. -@item protected-field -The message is @samp{Attempt to modify a protected file}. -@end ignore - -@item scan-error -The message is @samp{Scan error}. This happens when certain -syntax-parsing functions find invalid syntax or mismatched -parentheses. @xref{List Motion}, and @xref{Parsing Expressions}. - -@item search-failed -The message is @samp{Search failed}. @xref{Searching and Matching}. - -@item setting-constant -The message is @samp{Attempt to set a constant symbol}. This happens -when attempting to assign values to @code{nil}, @code{t}, and keyword -symbols. @xref{Constant Variables}. - -@c simple.el -@item text-read-only -The message is @samp{Text is read-only}. This is a subcategory of -@code{buffer-read-only}. @xref{Special Properties}. - -@item undefined-color -The message is @samp{Undefined color}. @xref{Color Names}. - -@item user-error -The message is the empty string. @xref{Signaling Errors}. - -@item void-function -The message is @samp{Symbol's function definition is void}. -@xref{Function Cells}. - -@item void-variable -The message is @samp{Symbol's value as variable is void}. -@xref{Accessing Variables}. - -@item wrong-number-of-arguments -The message is @samp{Wrong number of arguments}. @xref{Classifying -Lists}. - -@item wrong-type-argument -The message is @samp{Wrong type argument}. @xref{Type Predicates}. -@end table - -@ignore The following seem to be unused now. - The following kinds of error, which are classified as special cases of -@code{arith-error}, can occur on certain systems for invalid use of -mathematical functions. @xref{Math Functions}. - -@table @code -@item domain-error -The message is @samp{Arithmetic domain error}. - -@item overflow-error -The message is @samp{Arithmetic overflow error}. This is a subcategory -of @code{domain-error}. - -@item range-error -The message is @code{Arithmetic range error}. - -@item singularity-error -The message is @samp{Arithmetic singularity error}. This is a -subcategory of @code{domain-error}. - -@item underflow-error -The message is @samp{Arithmetic underflow error}. This is a -subcategory of @code{domain-error}. -@end table -@end ignore diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi deleted file mode 100644 index 05250233b00..00000000000 --- a/doc/lispref/eval.texi +++ /dev/null @@ -1,874 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998, 2001-2014 Free Software Foundation, -@c Inc. -@c See the file elisp.texi for copying conditions. -@node Evaluation -@chapter Evaluation -@cindex evaluation -@cindex interpreter -@cindex interpreter -@cindex value of expression - - The @dfn{evaluation} of expressions in Emacs Lisp is performed by the -@dfn{Lisp interpreter}---a program that receives a Lisp object as input -and computes its @dfn{value as an expression}. How it does this depends -on the data type of the object, according to rules described in this -chapter. The interpreter runs automatically to evaluate portions of -your program, but can also be called explicitly via the Lisp primitive -function @code{eval}. - -@ifnottex -@menu -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in the program). -* Backquote:: Easier construction of list structure. -* Eval:: How to invoke the Lisp interpreter explicitly. -@end menu - -@node Intro Eval -@section Introduction to Evaluation - - The Lisp interpreter, or evaluator, is the part of Emacs that -computes the value of an expression that is given to it. When a -function written in Lisp is called, the evaluator computes the value -of the function by evaluating the expressions in the function body. -Thus, running any Lisp program really means running the Lisp -interpreter. -@end ifnottex - -@cindex form -@cindex expression -@cindex S-expression -@cindex sexp - A Lisp object that is intended for evaluation is called a @dfn{form} -or @dfn{expression}@footnote{It is sometimes also referred to as an -@dfn{S-expression} or @dfn{sexp}, but we generally do not use this -terminology in this manual.}. The fact that forms are data objects -and not merely text is one of the fundamental differences between -Lisp-like languages and typical programming languages. Any object can -be evaluated, but in practice only numbers, symbols, lists and strings -are evaluated very often. - - In subsequent sections, we will describe the details of what -evaluation means for each kind of form. - - It is very common to read a Lisp form and then evaluate the form, -but reading and evaluation are separate activities, and either can be -performed alone. Reading per se does not evaluate anything; it -converts the printed representation of a Lisp object to the object -itself. It is up to the caller of @code{read} to specify whether this -object is a form to be evaluated, or serves some entirely different -purpose. @xref{Input Functions}. - -@cindex recursive evaluation - Evaluation is a recursive process, and evaluating a form often -involves evaluating parts within that form. For instance, when you -evaluate a @dfn{function call} form such as @code{(car x)}, Emacs -first evaluates the argument (the subform @code{x}). After evaluating -the argument, Emacs @dfn{executes} the function (@code{car}), and if -the function is written in Lisp, execution works by evaluating the -@dfn{body} of the function (in this example, however, @code{car} is -not a Lisp function; it is a primitive function implemented in C). -@xref{Functions}, for more information about functions and function -calls. - -@cindex environment - Evaluation takes place in a context called the @dfn{environment}, -which consists of the current values and bindings of all Lisp -variables (@pxref{Variables}).@footnote{This definition of -``environment'' is specifically not intended to include all the data -that can affect the result of a program.} Whenever a form refers to a -variable without creating a new binding for it, the variable evaluates -to the value given by the current environment. Evaluating a form may -also temporarily alter the environment by binding variables -(@pxref{Local Variables}). - -@cindex side effect - Evaluating a form may also make changes that persist; these changes -are called @dfn{side effects}. An example of a form that produces a -side effect is @code{(setq foo 1)}. - - Do not confuse evaluation with command key interpretation. The -editor command loop translates keyboard input into a command (an -interactively callable function) using the active keymaps, and then -uses @code{call-interactively} to execute that command. Executing the -command usually involves evaluation, if the command is written in -Lisp; however, this step is not considered a part of command key -interpretation. @xref{Command Loop}. - -@node Forms -@section Kinds of Forms - - A Lisp object that is intended to be evaluated is called a -@dfn{form} (or an @dfn{expression}). How Emacs evaluates a form -depends on its data type. Emacs has three different kinds of form -that are evaluated differently: symbols, lists, and ``all other -types''. This section describes all three kinds, one by one, starting -with the ``all other types'' which are self-evaluating forms. - -@menu -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. -@end menu - -@node Self-Evaluating Forms -@subsection Self-Evaluating Forms -@cindex vector evaluation -@cindex literal evaluation -@cindex self-evaluating form - - A @dfn{self-evaluating form} is any form that is not a list or -symbol. Self-evaluating forms evaluate to themselves: the result of -evaluation is the same object that was evaluated. Thus, the number 25 -evaluates to 25, and the string @code{"foo"} evaluates to the string -@code{"foo"}. Likewise, evaluating a vector does not cause evaluation -of the elements of the vector---it returns the same vector with its -contents unchanged. - -@example -@group -'123 ; @r{A number, shown without evaluation.} - @result{} 123 -@end group -@group -123 ; @r{Evaluated as usual---result is the same.} - @result{} 123 -@end group -@group -(eval '123) ; @r{Evaluated ``by hand''---result is the same.} - @result{} 123 -@end group -@group -(eval (eval '123)) ; @r{Evaluating twice changes nothing.} - @result{} 123 -@end group -@end example - - It is common to write numbers, characters, strings, and even vectors -in Lisp code, taking advantage of the fact that they self-evaluate. -However, it is quite unusual to do this for types that lack a read -syntax, because there's no way to write them textually. It is possible -to construct Lisp expressions containing these types by means of a Lisp -program. Here is an example: - -@example -@group -;; @r{Build an expression containing a buffer object.} -(setq print-exp (list 'print (current-buffer))) - @result{} (print #) -@end group -@group -;; @r{Evaluate it.} -(eval print-exp) - @print{} # - @result{} # -@end group -@end example - -@node Symbol Forms -@subsection Symbol Forms -@cindex symbol evaluation - - When a symbol is evaluated, it is treated as a variable. The result -is the variable's value, if it has one. If the symbol has no value as -a variable, the Lisp interpreter signals an error. For more -information on the use of variables, see @ref{Variables}. - - In the following example, we set the value of a symbol with -@code{setq}. Then we evaluate the symbol, and get back the value that -@code{setq} stored. - -@example -@group -(setq a 123) - @result{} 123 -@end group -@group -(eval 'a) - @result{} 123 -@end group -@group -a - @result{} 123 -@end group -@end example - - The symbols @code{nil} and @code{t} are treated specially, so that the -value of @code{nil} is always @code{nil}, and the value of @code{t} is -always @code{t}; you cannot set or bind them to any other values. Thus, -these two symbols act like self-evaluating forms, even though -@code{eval} treats them like any other symbol. A symbol whose name -starts with @samp{:} also self-evaluates in the same way; likewise, -its value ordinarily cannot be changed. @xref{Constant Variables}. - -@node Classifying Lists -@subsection Classification of List Forms -@cindex list form evaluation - - A form that is a nonempty list is either a function call, a macro -call, or a special form, according to its first element. These three -kinds of forms are evaluated in different ways, described below. The -remaining list elements constitute the @dfn{arguments} for the function, -macro, or special form. - - The first step in evaluating a nonempty list is to examine its first -element. This element alone determines what kind of form the list is -and how the rest of the list is to be processed. The first element is -@emph{not} evaluated, as it would be in some Lisp dialects such as -Scheme. - -@node Function Indirection -@subsection Symbol Function Indirection -@cindex symbol function indirection -@cindex indirection for functions -@cindex void function - - If the first element of the list is a symbol then evaluation -examines the symbol's function cell, and uses its contents instead of -the original symbol. If the contents are another symbol, this -process, called @dfn{symbol function indirection}, is repeated until -it obtains a non-symbol. @xref{Function Names}, for more information -about symbol function indirection. - - One possible consequence of this process is an infinite loop, in the -event that a symbol's function cell refers to the same symbol. -Otherwise, we eventually obtain a non-symbol, which ought to be a -function or other suitable object. - -@kindex invalid-function - More precisely, we should now have a Lisp function (a lambda -expression), a byte-code function, a primitive function, a Lisp macro, -a special form, or an autoload object. Each of these types is a case -described in one of the following sections. If the object is not one -of these types, Emacs signals an @code{invalid-function} error. - - The following example illustrates the symbol indirection process. -We use @code{fset} to set the function cell of a symbol and -@code{symbol-function} to get the function cell contents -(@pxref{Function Cells}). Specifically, we store the symbol -@code{car} into the function cell of @code{first}, and the symbol -@code{first} into the function cell of @code{erste}. - -@example -@group -;; @r{Build this function cell linkage:} -;; ------------- ----- ------- ------- -;; | # | <-- | car | <-- | first | <-- | erste | -;; ------------- ----- ------- ------- -@end group -@group -(symbol-function 'car) - @result{} # -@end group -@group -(fset 'first 'car) - @result{} car -@end group -@group -(fset 'erste 'first) - @result{} first -@end group -@group -(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.} - @result{} 1 -@end group -@end example - - By contrast, the following example calls a function without any symbol -function indirection, because the first element is an anonymous Lisp -function, not a symbol. - -@example -@group -((lambda (arg) (erste arg)) - '(1 2 3)) - @result{} 1 -@end group -@end example - -@noindent -Executing the function itself evaluates its body; this does involve -symbol function indirection when calling @code{erste}. - - This form is rarely used and is now deprecated. Instead, you should write it -as: - -@example -@group -(funcall (lambda (arg) (erste arg)) - '(1 2 3)) -@end group -@end example -or just -@example -@group -(let ((arg '(1 2 3))) (erste arg)) -@end group -@end example - - The built-in function @code{indirect-function} provides an easy way to -perform symbol function indirection explicitly. - -@c Emacs 19 feature -@defun indirect-function function &optional noerror -@anchor{Definition of indirect-function} -This function returns the meaning of @var{function} as a function. If -@var{function} is a symbol, then it finds @var{function}'s function -definition and starts over with that value. If @var{function} is not a -symbol, then it returns @var{function} itself. - -This function signals a @code{void-function} error if the final symbol -is unbound and optional argument @var{noerror} is @code{nil} or -omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns -@code{nil} if the final symbol is unbound. - -It signals a @code{cyclic-function-indirection} error if there is a -loop in the chain of symbols. - -Here is how you could define @code{indirect-function} in Lisp: - -@example -(defun indirect-function (function) - (if (symbolp function) - (indirect-function (symbol-function function)) - function)) -@end example -@end defun - -@node Function Forms -@subsection Evaluation of Function Forms -@cindex function form evaluation -@cindex function call - - If the first element of a list being evaluated is a Lisp function -object, byte-code object or primitive function object, then that list is -a @dfn{function call}. For example, here is a call to the function -@code{+}: - -@example -(+ 1 x) -@end example - - The first step in evaluating a function call is to evaluate the -remaining elements of the list from left to right. The results are the -actual argument values, one value for each list element. The next step -is to call the function with this list of arguments, effectively using -the function @code{apply} (@pxref{Calling Functions}). If the function -is written in Lisp, the arguments are used to bind the argument -variables of the function (@pxref{Lambda Expressions}); then the forms -in the function body are evaluated in order, and the value of the last -body form becomes the value of the function call. - -@node Macro Forms -@subsection Lisp Macro Evaluation -@cindex macro call evaluation - - If the first element of a list being evaluated is a macro object, then -the list is a @dfn{macro call}. When a macro call is evaluated, the -elements of the rest of the list are @emph{not} initially evaluated. -Instead, these elements themselves are used as the arguments of the -macro. The macro definition computes a replacement form, called the -@dfn{expansion} of the macro, to be evaluated in place of the original -form. The expansion may be any sort of form: a self-evaluating -constant, a symbol, or a list. If the expansion is itself a macro call, -this process of expansion repeats until some other sort of form results. - - Ordinary evaluation of a macro call finishes by evaluating the -expansion. However, the macro expansion is not necessarily evaluated -right away, or at all, because other programs also expand macro calls, -and they may or may not evaluate the expansions. - - Normally, the argument expressions are not evaluated as part of -computing the macro expansion, but instead appear as part of the -expansion, so they are computed when the expansion is evaluated. - - For example, given a macro defined as follows: - -@example -@group -(defmacro cadr (x) - (list 'car (list 'cdr x))) -@end group -@end example - -@noindent -an expression such as @code{(cadr (assq 'handler list))} is a macro -call, and its expansion is: - -@example -(car (cdr (assq 'handler list))) -@end example - -@noindent -Note that the argument @code{(assq 'handler list)} appears in the -expansion. - -@xref{Macros}, for a complete description of Emacs Lisp macros. - -@node Special Forms -@subsection Special Forms -@cindex special forms -@cindex evaluation of special forms - - A @dfn{special form} is a primitive function specially marked so that -its arguments are not all evaluated. Most special forms define control -structures or perform variable bindings---things which functions cannot -do. - - Each special form has its own rules for which arguments are evaluated -and which are used without evaluation. Whether a particular argument is -evaluated may depend on the results of evaluating other arguments. - - If an expression's first symbol is that of a special form, the -expression should follow the rules of that special form; otherwise, -Emacs's behavior is not well-defined (though it will not crash). For -example, @code{((lambda (x) x . 3) 4)} contains a subexpression that -begins with @code{lambda} but is not a well-formed @code{lambda} -expression, so Emacs may signal an error, or may return 3 or 4 or -@code{nil}, or may behave in other ways. - -@defun special-form-p object -This predicate tests whether its argument is a special form, and -returns @code{t} if so, @code{nil} otherwise. -@end defun - - Here is a list, in alphabetical order, of all of the special forms in -Emacs Lisp with a reference to where each is described. - -@table @code -@item and -@pxref{Combining Conditions} - -@item catch -@pxref{Catch and Throw} - -@item cond -@pxref{Conditionals} - -@item condition-case -@pxref{Handling Errors} - -@item defconst -@pxref{Defining Variables} - -@item defvar -@pxref{Defining Variables} - -@item function -@pxref{Anonymous Functions} - -@item if -@pxref{Conditionals} - -@item interactive -@pxref{Interactive Call} - -@item lambda -@pxref{Lambda Expressions} - -@item let -@itemx let* -@pxref{Local Variables} - -@item or -@pxref{Combining Conditions} - -@item prog1 -@itemx prog2 -@itemx progn -@pxref{Sequencing} - -@item quote -@pxref{Quoting} - -@item save-current-buffer -@pxref{Current Buffer} - -@item save-excursion -@pxref{Excursions} - -@item save-restriction -@pxref{Narrowing} - -@item setq -@pxref{Setting Variables} - -@item setq-default -@pxref{Creating Buffer-Local} - -@item track-mouse -@pxref{Mouse Tracking} - -@item unwind-protect -@pxref{Nonlocal Exits} - -@item while -@pxref{Iteration} -@end table - -@cindex CL note---special forms compared -@quotation -@b{Common Lisp note:} Here are some comparisons of special forms in -GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and -@code{catch} are special forms in both Emacs Lisp and Common Lisp. -@code{save-excursion} is a special form in Emacs Lisp, but -doesn't exist in Common Lisp. @code{throw} is a special form in -Common Lisp (because it must be able to throw multiple values), but it -is a function in Emacs Lisp (which doesn't have multiple -values). -@end quotation - -@node Autoloading -@subsection Autoloading - - The @dfn{autoload} feature allows you to call a function or macro -whose function definition has not yet been loaded into Emacs. It -specifies which file contains the definition. When an autoload object -appears as a symbol's function definition, calling that symbol as a -function automatically loads the specified file; then it calls the -real definition loaded from that file. The way to arrange for an -autoload object to appear as a symbol's function definition is -described in @ref{Autoload}. - -@node Quoting -@section Quoting - - The special form @code{quote} returns its single argument, as written, -without evaluating it. This provides a way to include constant symbols -and lists, which are not self-evaluating objects, in a program. (It is -not necessary to quote self-evaluating objects such as numbers, strings, -and vectors.) - -@defspec quote object -This special form returns @var{object}, without evaluating it. -@end defspec - -@cindex @samp{'} for quoting -@cindex quoting using apostrophe -@cindex apostrophe for quoting -Because @code{quote} is used so often in programs, Lisp provides a -convenient read syntax for it. An apostrophe character (@samp{'}) -followed by a Lisp object (in read syntax) expands to a list whose first -element is @code{quote}, and whose second element is the object. Thus, -the read syntax @code{'x} is an abbreviation for @code{(quote x)}. - -Here are some examples of expressions that use @code{quote}: - -@example -@group -(quote (+ 1 2)) - @result{} (+ 1 2) -@end group -@group -(quote foo) - @result{} foo -@end group -@group -'foo - @result{} foo -@end group -@group -''foo - @result{} (quote foo) -@end group -@group -'(quote foo) - @result{} (quote foo) -@end group -@group -['foo] - @result{} [(quote foo)] -@end group -@end example - - Other quoting constructs include @code{function} (@pxref{Anonymous -Functions}), which causes an anonymous lambda expression written in Lisp -to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote -only part of a list, while computing and substituting other parts. - -@node Backquote -@section Backquote -@cindex backquote (list substitution) -@cindex ` (list substitution) -@findex ` - - @dfn{Backquote constructs} allow you to quote a list, but -selectively evaluate elements of that list. In the simplest case, it -is identical to the special form @code{quote} -@iftex -@end iftex -@ifnottex -(described in the previous section; @pxref{Quoting}). -@end ifnottex -For example, these two forms yield identical results: - -@example -@group -`(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@group -'(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@end example - -@findex , @r{(with backquote)} - The special marker @samp{,} inside of the argument to backquote -indicates a value that isn't constant. The Emacs Lisp evaluator -evaluates the argument of @samp{,}, and puts the value in the list -structure: - -@example -@group -`(a list of ,(+ 2 3) elements) - @result{} (a list of 5 elements) -@end group -@end example - -@noindent -Substitution with @samp{,} is allowed at deeper levels of the list -structure also. For example: - -@example -@group -`(1 2 (3 ,(+ 4 5))) - @result{} (1 2 (3 9)) -@end group -@end example - -@findex ,@@ @r{(with backquote)} -@cindex splicing (with backquote) - You can also @dfn{splice} an evaluated value into the resulting list, -using the special marker @samp{,@@}. The elements of the spliced list -become elements at the same level as the other elements of the resulting -list. The equivalent code without using @samp{`} is often unreadable. -Here are some examples: - -@example -@group -(setq some-list '(2 3)) - @result{} (2 3) -@end group -@group -(cons 1 (append some-list '(4) some-list)) - @result{} (1 2 3 4 2 3) -@end group -@group -`(1 ,@@some-list 4 ,@@some-list) - @result{} (1 2 3 4 2 3) -@end group - -@group -(setq list '(hack foo bar)) - @result{} (hack foo bar) -@end group -@group -(cons 'use - (cons 'the - (cons 'words (append (cdr list) '(as elements))))) - @result{} (use the words foo bar as elements) -@end group -@group -`(use the words ,@@(cdr list) as elements) - @result{} (use the words foo bar as elements) -@end group -@end example - - -@node Eval -@section Eval - - Most often, forms are evaluated automatically, by virtue of their -occurrence in a program being run. On rare occasions, you may need to -write code that evaluates a form that is computed at run time, such as -after reading a form from text being edited or getting one from a -property list. On these occasions, use the @code{eval} function. -Often @code{eval} is not needed and something else should be used instead. -For example, to get the value of a variable, while @code{eval} works, -@code{symbol-value} is preferable; or rather than store expressions -in a property list that then need to go through @code{eval}, it is better to -store functions instead that are then passed to @code{funcall}. - - The functions and variables described in this section evaluate forms, -specify limits to the evaluation process, or record recently returned -values. Loading a file also does evaluation (@pxref{Loading}). - - It is generally cleaner and more flexible to store a function in a -data structure, and call it with @code{funcall} or @code{apply}, than -to store an expression in the data structure and evaluate it. Using -functions provides the ability to pass information to them as -arguments. - -@defun eval form &optional lexical -This is the basic function for evaluating an expression. It evaluates -@var{form} in the current environment, and returns the result. The -type of the @var{form} object determines how it is evaluated. -@xref{Forms}. - -The argument @var{lexical} specifies the scoping rule for local -variables (@pxref{Variable Scoping}). If it is omitted or @code{nil}, -that means to evaluate @var{form} using the default dynamic scoping -rule. If it is @code{t}, that means to use the lexical scoping rule. -The value of @var{lexical} can also be a non-empty alist specifying a -particular @dfn{lexical environment} for lexical bindings; however, -this feature is only useful for specialized purposes, such as in Emacs -Lisp debuggers. @xref{Lexical Binding}. - -Since @code{eval} is a function, the argument expression that appears -in a call to @code{eval} is evaluated twice: once as preparation before -@code{eval} is called, and again by the @code{eval} function itself. -Here is an example: - -@example -@group -(setq foo 'bar) - @result{} bar -@end group -@group -(setq bar 'baz) - @result{} baz -;; @r{Here @code{eval} receives argument @code{foo}} -(eval 'foo) - @result{} bar -;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}} -(eval foo) - @result{} baz -@end group -@end example - -The number of currently active calls to @code{eval} is limited to -@code{max-lisp-eval-depth} (see below). -@end defun - -@deffn Command eval-region start end &optional stream read-function -@anchor{Definition of eval-region} -This function evaluates the forms in the current buffer in the region -defined by the positions @var{start} and @var{end}. It reads forms from -the region and calls @code{eval} on them until the end of the region is -reached, or until an error is signaled and not handled. - -By default, @code{eval-region} does not produce any output. However, -if @var{stream} is non-@code{nil}, any output produced by output -functions (@pxref{Output Functions}), as well as the values that -result from evaluating the expressions in the region are printed using -@var{stream}. @xref{Output Streams}. - -If @var{read-function} is non-@code{nil}, it should be a function, -which is used instead of @code{read} to read expressions one by one. -This function is called with one argument, the stream for reading -input. You can also use the variable @code{load-read-function} -(@pxref{Definition of load-read-function,, How Programs Do Loading}) -to specify this function, but it is more robust to use the -@var{read-function} argument. - -@code{eval-region} does not move point. It always returns @code{nil}. -@end deffn - -@cindex evaluation of buffer contents -@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print -This is similar to @code{eval-region}, but the arguments provide -different optional features. @code{eval-buffer} operates on the -entire accessible portion of buffer @var{buffer-or-name}. -@var{buffer-or-name} can be a buffer, a buffer name (a string), or -@code{nil} (or omitted), which means to use the current buffer. -@var{stream} is used as in @code{eval-region}, unless @var{stream} is -@code{nil} and @var{print} non-@code{nil}. In that case, values that -result from evaluating the expressions are still discarded, but the -output of the output functions is printed in the echo area. -@var{filename} is the file name to use for @code{load-history} -(@pxref{Unloading}), and defaults to @code{buffer-file-name} -(@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil}, -@code{read} converts strings to unibyte whenever possible. - -@findex eval-current-buffer -@code{eval-current-buffer} is an alias for this command. -@end deffn - -@defopt max-lisp-eval-depth -@anchor{Definition of max-lisp-eval-depth} -This variable defines the maximum depth allowed in calls to @code{eval}, -@code{apply}, and @code{funcall} before an error is signaled (with error -message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). - -This limit, with the associated error when it is exceeded, is one way -Emacs Lisp avoids infinite recursion on an ill-defined function. If -you increase the value of @code{max-lisp-eval-depth} too much, such -code can cause stack overflow instead. -@cindex Lisp nesting error - -The depth limit counts internal uses of @code{eval}, @code{apply}, and -@code{funcall}, such as for calling the functions mentioned in Lisp -expressions, and recursive evaluation of function call arguments and -function body forms, as well as explicit calls in Lisp code. - -The default value of this variable is 400. If you set it to a value -less than 100, Lisp will reset it to 100 if the given value is -reached. Entry to the Lisp debugger increases the value, if there is -little room left, to make sure the debugger itself has room to -execute. - -@code{max-specpdl-size} provides another limit on nesting. -@xref{Definition of max-specpdl-size,, Local Variables}. -@end defopt - -@defvar values -The value of this variable is a list of the values returned by all the -expressions that were read, evaluated, and printed from buffers -(including the minibuffer) by the standard Emacs commands which do -this. (Note that this does @emph{not} include evaluation in -@file{*ielm*} buffers, nor evaluation using @kbd{C-j} in -@code{lisp-interaction-mode}.) The elements are ordered most recent -first. - -@example -@group -(setq x 1) - @result{} 1 -@end group -@group -(list 'A (1+ 2) auto-save-default) - @result{} (A 3 t) -@end group -@group -values - @result{} ((A 3 t) 1 @dots{}) -@end group -@end example - -This variable is useful for referring back to values of forms recently -evaluated. It is generally a bad idea to print the value of -@code{values} itself, since this may be very long. Instead, examine -particular elements, like this: - -@example -@group -;; @r{Refer to the most recent evaluation result.} -(nth 0 values) - @result{} (A 3 t) -@end group -@group -;; @r{That put a new element on,} -;; @r{so all elements move back one.} -(nth 1 values) - @result{} (A 3 t) -@end group -@group -;; @r{This gets the element that was next-to-most-recent} -;; @r{before this example.} -(nth 3 values) - @result{} 1 -@end group -@end example -@end defvar diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi deleted file mode 100644 index b071c6a8f35..00000000000 --- a/doc/lispref/files.texi +++ /dev/null @@ -1,3391 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Files -@chapter Files - - This chapter describes the Emacs Lisp functions and variables to -find, create, view, save, and otherwise work with files and -directories. A few other file-related functions are described in -@ref{Buffers}, and those related to backups and auto-saving are -described in @ref{Backups and Auto-Saving}. - - Many of the file functions take one or more arguments that are file -names. A file name is a string. Most of these functions expand file -name arguments using the function @code{expand-file-name}, so that -@file{~} is handled correctly, as are relative file names (including -@file{../}). @xref{File Name Expansion}. - - In addition, certain @dfn{magic} file names are handled specially. -For example, when a remote file name is specified, Emacs accesses the -file over the network via an appropriate protocol. @xref{Remote -Files,, Remote Files, emacs, The GNU Emacs Manual}. This handling is -done at a very low level, so you may assume that all the functions -described in this chapter accept magic file names as file name -arguments, except where noted. @xref{Magic File Names}, for details. - - When file I/O functions signal Lisp errors, they usually use the -condition @code{file-error} (@pxref{Handling Errors}). The error -message is in most cases obtained from the operating system, according -to locale @code{system-messages-locale}, and decoded using coding system -@code{locale-coding-system} (@pxref{Locales}). - -@menu -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing permissions, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Special handling for certain file names. -* Format Conversion:: Conversion to and from various file formats. -@end menu - -@node Visiting Files -@section Visiting Files -@cindex finding files -@cindex visiting files - - Visiting a file means reading a file into a buffer. Once this is -done, we say that the buffer is @dfn{visiting} that file, and call the -file ``the visited file'' of the buffer. - - A file and a buffer are two different things. A file is information -recorded permanently in the computer (unless you delete it). A -buffer, on the other hand, is information inside of Emacs that will -vanish at the end of the editing session (or when you kill the -buffer). When a buffer is visiting a file, it contains information -copied from the file. The copy in the buffer is what you modify with -editing commands. Changes to the buffer do not change the file; to -make the changes permanent, you must @dfn{save} the buffer, which -means copying the altered buffer contents back into the file. - - Despite the distinction between files and buffers, people often -refer to a file when they mean a buffer and vice-versa. Indeed, we -say, ``I am editing a file'', rather than, ``I am editing a buffer -that I will soon save as a file of the same name''. Humans do not -usually need to make the distinction explicit. When dealing with a -computer program, however, it is good to keep the distinction in mind. - -@menu -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. -@end menu - -@node Visiting Functions -@subsection Functions for Visiting Files - - This section describes the functions normally used to visit files. -For historical reasons, these functions have names starting with -@samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for -functions and variables that access the visited file name of a buffer or -that find an existing buffer by its visited file name. - - In a Lisp program, if you want to look at the contents of a file but -not alter it, the fastest way is to use @code{insert-file-contents} in a -temporary buffer. Visiting the file is not necessary and takes longer. -@xref{Reading from Files}. - -@deffn Command find-file filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, -using an existing buffer if there is one, and otherwise creating a -new buffer and reading the file into it. It also returns that buffer. - -Aside from some technical details, the body of the @code{find-file} -function is basically equivalent to: - -@smallexample -(switch-to-buffer (find-file-noselect filename nil nil wildcards)) -@end smallexample - -@noindent -(See @code{switch-to-buffer} in @ref{Switching Buffers}.) - -If @var{wildcards} is non-@code{nil}, which is always true in an -interactive call, then @code{find-file} expands wildcard characters in -@var{filename} and visits all the matching files. - -When @code{find-file} is called interactively, it prompts for -@var{filename} in the minibuffer. -@end deffn - -@deffn Command find-file-literally filename -This command visits @var{filename}, like @code{find-file} does, but it -does not perform any format conversions (@pxref{Format Conversion}), -character code conversions (@pxref{Coding Systems}), or end-of-line -conversions (@pxref{Coding System Basics, End of line conversion}). -The buffer visiting the file is made unibyte, and its major mode is -Fundamental mode, regardless of the file name. File local variable -specifications in the file (@pxref{File Local Variables}) are -ignored, and automatic decompression and adding a newline at the end -of the file due to @code{require-final-newline} (@pxref{Saving -Buffers, require-final-newline}) are also disabled. - -Note that if Emacs already has a buffer visiting the same file -non-literally, it will not visit the same file literally, but instead -just switch to the existing buffer. If you want to be sure of -accessing a file's contents literally, you should create a temporary -buffer and then read the file contents into it using -@code{insert-file-contents-literally} (@pxref{Reading from Files}). -@end deffn - -@defun find-file-noselect filename &optional nowarn rawfile wildcards -This function is the guts of all the file-visiting functions. It -returns a buffer visiting the file @var{filename}. You may make the -buffer current or display it in a window if you wish, but this -function does not do so. - -The function returns an existing buffer if there is one; otherwise it -creates a new buffer and reads the file into it. When -@code{find-file-noselect} uses an existing buffer, it first verifies -that the file has not changed since it was last visited or saved in -that buffer. If the file has changed, this function asks the user -whether to reread the changed file. If the user says @samp{yes}, any -edits previously made in the buffer are lost. - -Reading the file involves decoding the file's contents (@pxref{Coding -Systems}), including end-of-line conversion, and format conversion -(@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil}, -then @code{find-file-noselect} expands wildcard characters in -@var{filename} and visits all the matching files. - -This function displays warning or advisory messages in various peculiar -cases, unless the optional argument @var{nowarn} is non-@code{nil}. For -example, if it needs to create a buffer, and there is no file named -@var{filename}, it displays the message @samp{(New file)} in the echo -area, and leaves the buffer empty. - -The @code{find-file-noselect} function normally calls -@code{after-find-file} after reading the file (@pxref{Subroutines of -Visiting}). That function sets the buffer major mode, parses local -variables, warns the user if there exists an auto-save file more recent -than the file just visited, and finishes by running the functions in -@code{find-file-hook}. - -If the optional argument @var{rawfile} is non-@code{nil}, then -@code{after-find-file} is not called, and the -@code{find-file-not-found-functions} are not run in case of failure. -What's more, a non-@code{nil} @var{rawfile} value suppresses coding -system conversion and format conversion. - -The @code{find-file-noselect} function usually returns the buffer that -is visiting the file @var{filename}. But, if wildcards are actually -used and expanded, it returns a list of buffers that are visiting the -various files. - -@example -@group -(find-file-noselect "/etc/fstab") - @result{} # -@end group -@end example -@end defun - -@deffn Command find-file-other-window filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, but -does so in a window other than the selected window. It may use -another existing window or split a window; see @ref{Switching -Buffers}. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@deffn Command find-file-read-only filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, like -@code{find-file}, but it marks the buffer as read-only. @xref{Read Only -Buffers}, for related functions and variables. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@defopt find-file-wildcards -If this variable is non-@code{nil}, then the various @code{find-file} -commands check for wildcard characters and visit all the files that -match them (when invoked interactively or when their @var{wildcards} -argument is non-@code{nil}). If this option is @code{nil}, then -the @code{find-file} commands ignore their @var{wildcards} argument -and never treat wildcard characters specially. -@end defopt - -@defopt find-file-hook -The value of this variable is a list of functions to be called after a -file is visited. The file's local-variables specification (if any) will -have been processed before the hooks are run. The buffer visiting the -file is current when the hook functions are run. - -This variable is a normal hook. @xref{Hooks}. -@end defopt - -@defvar find-file-not-found-functions -The value of this variable is a list of functions to be called when -@code{find-file} or @code{find-file-noselect} is passed a nonexistent -file name. @code{find-file-noselect} calls these functions as soon as -it detects a nonexistent file. It calls them in the order of the list, -until one of them returns non-@code{nil}. @code{buffer-file-name} is -already set up. - -This is not a normal hook because the values of the functions are -used, and in many cases only some of the functions are called. -@end defvar - -@defvar find-file-literally -This buffer-local variable, if set to a non-@code{nil} value, makes -@code{save-buffer} behave as if the buffer were visiting its file -literally, i.e., without conversions of any kind. The command -@code{find-file-literally} sets this variable's local value, but other -equivalent functions and commands can do that as well, e.g., to avoid -automatic addition of a newline at the end of the file. This variable -is permanent local, so it is unaffected by changes of major modes. -@end defvar - -@node Subroutines of Visiting -@subsection Subroutines of Visiting - - The @code{find-file-noselect} function uses two important subroutines -which are sometimes useful in user Lisp code: @code{create-file-buffer} -and @code{after-find-file}. This section explains how to use them. - -@c FIXME This does not describe the default behavior, because -@c uniquify is enabled by default and advises this function. -@c This is confusing. uniquify should be folded into the function proper. -@defun create-file-buffer filename -This function creates a suitably named buffer for visiting -@var{filename}, and returns it. It uses @var{filename} (sans directory) -as the name if that name is free; otherwise, it appends a string such as -@samp{<2>} to get an unused name. See also @ref{Creating Buffers}. -Note that the @file{uniquify} library affects the result of this -function. @xref{Uniquify,,, emacs, The GNU Emacs Manual}. - -@strong{Please note:} @code{create-file-buffer} does @emph{not} -associate the new buffer with a file and does not select the buffer. -It also does not use the default major mode. - -@example -@group -(create-file-buffer "foo") - @result{} # -@end group -@group -(create-file-buffer "foo") - @result{} #> -@end group -@group -(create-file-buffer "foo") - @result{} #> -@end group -@end example - -This function is used by @code{find-file-noselect}. -It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). -@end defun - -@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes -This function sets the buffer major mode, and parses local variables -(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} -and by the default revert function (@pxref{Reverting}). - -@cindex new file message -@cindex file open error -If reading the file got an error because the file does not exist, but -its directory does exist, the caller should pass a non-@code{nil} value -for @var{error}. In that case, @code{after-find-file} issues a warning: -@samp{(New file)}. For more serious errors, the caller should usually not -call @code{after-find-file}. - -If @var{warn} is non-@code{nil}, then this function issues a warning -if an auto-save file exists and is more recent than the visited file. - -If @var{noauto} is non-@code{nil}, that says not to enable or disable -Auto-Save mode. The mode remains enabled if it was enabled before. - -If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that -means this call was from @code{revert-buffer}. This has no direct -effect, but some mode functions and hook functions check the value -of this variable. - -If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's -major mode, don't process local variables specifications in the file, -and don't run @code{find-file-hook}. This feature is used by -@code{revert-buffer} in some cases. - -The last thing @code{after-find-file} does is call all the functions -in the list @code{find-file-hook}. -@end defun - -@node Saving Buffers -@section Saving Buffers -@cindex saving buffers - - When you edit a file in Emacs, you are actually working on a buffer -that is visiting that file---that is, the contents of the file are -copied into the buffer and the copy is what you edit. Changes to the -buffer do not change the file until you @dfn{save} the buffer, which -means copying the contents of the buffer into the file. - -@deffn Command save-buffer &optional backup-option -This function saves the contents of the current buffer in its visited -file if the buffer has been modified since it was last visited or saved. -Otherwise it does nothing. - -@code{save-buffer} is responsible for making backup files. Normally, -@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup -file only if this is the first save since visiting the file. Other -values for @var{backup-option} request the making of backup files in -other circumstances: - -@itemize @bullet -@item -With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the -@code{save-buffer} function marks this version of the file to be -backed up when the buffer is next saved. - -@item -With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the -@code{save-buffer} function unconditionally backs up the previous -version of the file before saving it. - -@item -With an argument of 0, unconditionally do @emph{not} make any backup file. -@end itemize -@end deffn - -@deffn Command save-some-buffers &optional save-silently-p pred -@anchor{Definition of save-some-buffers} -This command saves some modified file-visiting buffers. Normally it -asks the user about each buffer. But if @var{save-silently-p} is -non-@code{nil}, it saves all the file-visiting buffers without querying -the user. - -The optional @var{pred} argument controls which buffers to ask about -(or to save silently if @var{save-silently-p} is non-@code{nil}). -If it is @code{nil}, that means to ask only about file-visiting buffers. -If it is @code{t}, that means also offer to save certain other non-file -buffers---those that have a non-@code{nil} buffer-local value of -@code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says -@samp{yes} to saving a non-file buffer is asked to specify the file -name to use. The @code{save-buffers-kill-emacs} function passes the -value @code{t} for @var{pred}. - -If @var{pred} is neither @code{t} nor @code{nil}, then it should be -a function of no arguments. It will be called in each buffer to decide -whether to offer to save that buffer. If it returns a non-@code{nil} -value in a certain buffer, that means do offer to save that buffer. -@end deffn - -@deffn Command write-file filename &optional confirm -@anchor{Definition of write-file} -This function writes the current buffer into file @var{filename}, makes -the buffer visit that file, and marks it not modified. Then it renames -the buffer based on @var{filename}, appending a string like @samp{<2>} -if necessary to make a unique buffer name. It does most of this work by -calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and -@code{save-buffer}. - -If @var{confirm} is non-@code{nil}, that means to ask for confirmation -before overwriting an existing file. Interactively, confirmation is -required, unless the user supplies a prefix argument. - -If @var{filename} is an existing directory, or a symbolic link to one, -@code{write-file} uses the name of the visited file, in directory -@var{filename}. If the buffer is not visiting a file, it uses the -buffer name instead. -@end deffn - - Saving a buffer runs several hooks. It also performs format -conversion (@pxref{Format Conversion}). - -@defvar write-file-functions -The value of this variable is a list of functions to be called before -writing out a buffer to its visited file. If one of them returns -non-@code{nil}, the file is considered already written and the rest of -the functions are not called, nor is the usual code for writing the file -executed. - -If a function in @code{write-file-functions} returns non-@code{nil}, it -is responsible for making a backup file (if that is appropriate). -To do so, execute the following code: - -@example -(or buffer-backed-up (backup-buffer)) -@end example - -You might wish to save the file modes value returned by -@code{backup-buffer} and use that (if non-@code{nil}) to set the mode -bits of the file that you write. This is what @code{save-buffer} -normally does. @xref{Making Backups,, Making Backup Files}. - -The hook functions in @code{write-file-functions} are also responsible -for encoding the data (if desired): they must choose a suitable coding -system and end-of-line conversion (@pxref{Lisp and Coding Systems}), -perform the encoding (@pxref{Explicit Encoding}), and set -@code{last-coding-system-used} to the coding system that was used -(@pxref{Encoding and I/O}). - -If you set this hook locally in a buffer, it is assumed to be -associated with the file or the way the contents of the buffer were -obtained. Thus the variable is marked as a permanent local, so that -changing the major mode does not alter a buffer-local value. On the -other hand, calling @code{set-visited-file-name} will reset it. -If this is not what you want, you might like to use -@code{write-contents-functions} instead. - -Even though this is not a normal hook, you can use @code{add-hook} and -@code{remove-hook} to manipulate the list. @xref{Hooks}. -@end defvar - -@c Emacs 19 feature -@defvar write-contents-functions -This works just like @code{write-file-functions}, but it is intended -for hooks that pertain to the buffer's contents, not to the particular -visited file or its location. Such hooks are usually set up by major -modes, as buffer-local bindings for this variable. This variable -automatically becomes buffer-local whenever it is set; switching to a -new major mode always resets this variable, but calling -@code{set-visited-file-name} does not. - -If any of the functions in this hook returns non-@code{nil}, the file -is considered already written and the rest are not called and neither -are the functions in @code{write-file-functions}. -@end defvar - -@defopt before-save-hook -This normal hook runs before a buffer is saved in its visited file, -regardless of whether that is done normally or by one of the hooks -described above. For instance, the @file{copyright.el} program uses -this hook to make sure the file you are saving has the current year in -its copyright notice. -@end defopt - -@c Emacs 19 feature -@defopt after-save-hook -This normal hook runs after a buffer has been saved in its visited file. -One use of this hook is in Fast Lock mode; it uses this hook to save the -highlighting information in a cache file. -@end defopt - -@defopt file-precious-flag -If this variable is non-@code{nil}, then @code{save-buffer} protects -against I/O errors while saving by writing the new file to a temporary -name instead of the name it is supposed to have, and then renaming it to -the intended name after it is clear there are no errors. This procedure -prevents problems such as a lack of disk space from resulting in an -invalid file. - -As a side effect, backups are necessarily made by copying. @xref{Rename -or Copy}. Yet, at the same time, saving a precious file always breaks -all hard links between the file you save and other file names. - -Some modes give this variable a non-@code{nil} buffer-local value -in particular buffers. -@end defopt - -@defopt require-final-newline -This variable determines whether files may be written out that do -@emph{not} end with a newline. If the value of the variable is -@code{t}, then @code{save-buffer} silently adds a newline at the end -of the buffer whenever it does not already end in one. If the value -is @code{visit}, Emacs adds a missing newline just after it visits the -file. If the value is @code{visit-save}, Emacs adds a missing newline -both on visiting and on saving. For any other non-@code{nil} value, -@code{save-buffer} asks the user whether to add a newline each time -the case arises. - -If the value of the variable is @code{nil}, then @code{save-buffer} -doesn't add newlines at all. @code{nil} is the default value, but a few -major modes set it to @code{t} in particular buffers. -@end defopt - - See also the function @code{set-visited-file-name} (@pxref{Buffer File -Name}). - -@node Reading from Files -@section Reading from Files -@cindex reading from files - - To copy the contents of a file into a buffer, use the function -@code{insert-file-contents}. (Don't use the command -@code{insert-file} in a Lisp program, as that sets the mark.) - -@defun insert-file-contents filename &optional visit beg end replace -This function inserts the contents of file @var{filename} into the -current buffer after point. It returns a list of the absolute file name -and the length of the data inserted. An error is signaled if -@var{filename} is not the name of a file that can be read. - -This function checks the file contents against the defined file -formats, and converts the file contents if appropriate and also calls -the functions in the list @code{after-insert-file-functions}. -@xref{Format Conversion}. Normally, one of the functions in the -@code{after-insert-file-functions} list determines the coding system -(@pxref{Coding Systems}) used for decoding the file's contents, -including end-of-line conversion. However, if the file contains null -bytes, it is by default visited without any code conversions. -@xref{Lisp and Coding Systems, inhibit-null-byte-detection}. - -If @var{visit} is non-@code{nil}, this function additionally marks the -buffer as unmodified and sets up various fields in the buffer so that it -is visiting the file @var{filename}: these include the buffer's visited -file name and its last save file modtime. This feature is used by -@code{find-file-noselect} and you probably should not use it yourself. - -If @var{beg} and @var{end} are non-@code{nil}, they should be numbers -that are byte offsets specifying the portion of the file to insert. -In this case, @var{visit} must be @code{nil}. For example, - -@example -(insert-file-contents filename nil 0 500) -@end example - -@noindent -inserts the first 500 characters of a file. - -If the argument @var{replace} is non-@code{nil}, it means to replace the -contents of the buffer (actually, just the accessible portion) with the -contents of the file. This is better than simply deleting the buffer -contents and inserting the whole file, because (1) it preserves some -marker positions and (2) it puts less data in the undo list. - -It is possible to read a special file (such as a FIFO or an I/O device) -with @code{insert-file-contents}, as long as @var{replace} and -@var{visit} are @code{nil}. -@end defun - -@defun insert-file-contents-literally filename &optional visit beg end replace -This function works like @code{insert-file-contents} except that it -does not run @code{find-file-hook}, and does not do format decoding, -character code conversion, automatic uncompression, and so on. -@end defun - -If you want to pass a file name to another process so that another -program can read the file, use the function @code{file-local-copy}; see -@ref{Magic File Names}. - -@node Writing to Files -@section Writing to Files -@cindex writing to files - - You can write the contents of a buffer, or part of a buffer, directly -to a file on disk using the @code{append-to-file} and -@code{write-region} functions. Don't use these functions to write to -files that are being visited; that could cause confusion in the -mechanisms for visiting. - -@deffn Command append-to-file start end filename -This function appends the contents of the region delimited by -@var{start} and @var{end} in the current buffer to the end of file -@var{filename}. If that file does not exist, it is created. This -function returns @code{nil}. - -An error is signaled if @var{filename} specifies a nonwritable file, -or a nonexistent file in a directory where files cannot be created. - -When called from Lisp, this function is completely equivalent to: - -@example -(write-region start end filename t) -@end example -@end deffn - -@deffn Command write-region start end filename &optional append visit lockname mustbenew -This function writes the region delimited by @var{start} and @var{end} -in the current buffer into the file specified by @var{filename}. - -If @var{start} is @code{nil}, then the command writes the entire buffer -contents (@emph{not} just the accessible portion) to the file and -ignores @var{end}. - -@c Emacs 19 feature -If @var{start} is a string, then @code{write-region} writes or appends -that string, rather than text from the buffer. @var{end} is ignored in -this case. - -If @var{append} is non-@code{nil}, then the specified text is appended -to the existing file contents (if any). If @var{append} is a -number, @code{write-region} seeks to that byte offset from the start -of the file and writes the data from there. - -If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks -for confirmation if @var{filename} names an existing file. If -@var{mustbenew} is the symbol @code{excl}, then @code{write-region} -does not ask for confirmation, but instead it signals an error -@code{file-already-exists} if the file already exists. - -The test for an existing file, when @var{mustbenew} is @code{excl}, uses -a special system feature. At least for files on a local disk, there is -no chance that some other program could create a file of the same name -before Emacs does, without Emacs's noticing. - -If @var{visit} is @code{t}, then Emacs establishes an association -between the buffer and the file: the buffer is then visiting that file. -It also sets the last file modification time for the current buffer to -@var{filename}'s modtime, and marks the buffer as not modified. This -feature is used by @code{save-buffer}, but you probably should not use -it yourself. - -@c Emacs 19 feature -If @var{visit} is a string, it specifies the file name to visit. This -way, you can write the data to one file (@var{filename}) while recording -the buffer as visiting another file (@var{visit}). The argument -@var{visit} is used in the echo area message and also for file locking; -@var{visit} is stored in @code{buffer-file-name}. This feature is used -to implement @code{file-precious-flag}; don't use it yourself unless you -really know what you're doing. - -The optional argument @var{lockname}, if non-@code{nil}, specifies the -file name to use for purposes of locking and unlocking, overriding -@var{filename} and @var{visit} for that purpose. - -The function @code{write-region} converts the data which it writes to -the appropriate file formats specified by @code{buffer-file-format} -and also calls the functions in the list -@code{write-region-annotate-functions}. -@xref{Format Conversion}. - -Normally, @code{write-region} displays the message @samp{Wrote -@var{filename}} in the echo area. If @var{visit} is neither @code{t} -nor @code{nil} nor a string, then this message is inhibited. This -feature is useful for programs that use files for internal purposes, -files that the user does not need to know about. -@end deffn - -@defmac with-temp-file file body@dots{} -@anchor{Definition of with-temp-file} -The @code{with-temp-file} macro evaluates the @var{body} forms with a -temporary buffer as the current buffer; then, at the end, it writes the -buffer contents into file @var{file}. It kills the temporary buffer -when finished, restoring the buffer that was current before the -@code{with-temp-file} form. Then it returns the value of the last form -in @var{body}. - -The current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -See also @code{with-temp-buffer} in @ref{Definition of -with-temp-buffer,, The Current Buffer}. -@end defmac - -@node File Locks -@section File Locks -@cindex file locks -@cindex lock file - - When two users edit the same file at the same time, they are likely -to interfere with each other. Emacs tries to prevent this situation -from arising by recording a @dfn{file lock} when a file is being -modified. -Emacs can then detect the first attempt to modify a buffer visiting a -file that is locked by another Emacs job, and ask the user what to do. -The file lock is really a file, a symbolic link with a special name, -stored in the same directory as the file you are editing. (On file -systems that do not support symbolic links, a regular file is used.) - - When you access files using NFS, there may be a small probability that -you and another user will both lock the same file ``simultaneously''. -If this happens, it is possible for the two users to make changes -simultaneously, but Emacs will still warn the user who saves second. -Also, the detection of modification of a buffer visiting a file changed -on disk catches some cases of simultaneous editing; see -@ref{Modification Time}. - -@defun file-locked-p filename -This function returns @code{nil} if the file @var{filename} is not -locked. It returns @code{t} if it is locked by this Emacs process, and -it returns the name of the user who has locked it if it is locked by -some other job. - -@example -@group -(file-locked-p "foo") - @result{} nil -@end group -@end example -@end defun - -@defun lock-buffer &optional filename -This function locks the file @var{filename}, if the current buffer is -modified. The argument @var{filename} defaults to the current buffer's -visited file. Nothing is done if the current buffer is not visiting a -file, or is not modified, or if the system does not support locking. -@end defun - -@defun unlock-buffer -This function unlocks the file being visited in the current buffer, -if the buffer is modified. If the buffer is not modified, then -the file should not be locked, so this function does nothing. It also -does nothing if the current buffer is not visiting a file, or if the -system does not support locking. -@end defun - -@defopt create-lockfiles -If this variable is @code{nil}, Emacs does not lock files. -@end defopt - -@defun ask-user-about-lock file other-user -This function is called when the user tries to modify @var{file}, but it -is locked by another user named @var{other-user}. The default -definition of this function asks the user to say what to do. The value -this function returns determines what Emacs does next: - -@itemize @bullet -@item -A value of @code{t} says to grab the lock on the file. Then -this user may edit the file and @var{other-user} loses the lock. - -@item -A value of @code{nil} says to ignore the lock and let this -user edit the file anyway. - -@item -@kindex file-locked -This function may instead signal a @code{file-locked} error, in which -case the change that the user was about to make does not take place. - -The error message for this error looks like this: - -@example -@error{} File is locked: @var{file} @var{other-user} -@end example - -@noindent -where @code{file} is the name of the file and @var{other-user} is the -name of the user who has locked the file. -@end itemize - -If you wish, you can replace the @code{ask-user-about-lock} function -with your own version that makes the decision in another way. -@end defun - -@node Information about Files -@section Information about Files -@cindex file, information about - - This section describes the functions for retrieving various types of -information about files (or directories or symbolic links), such as -whether a file is readable or writable, and its size. These functions -all take arguments which are file names. Except where noted, these -arguments need to specify existing files, or an error is signaled. - -@cindex file names, trailing whitespace -@cindex trailing blanks in file names - Be careful with file names that end in spaces. On some filesystems -(notably, MS-Windows), trailing whitespace characters in file names -are silently and automatically ignored. - -@menu -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: File sizes, modification times, etc. -* Extended Attributes:: Extended file attributes for access control. -* Locating Files:: How to find a file in standard places. -@end menu - -@node Testing Accessibility -@subsection Testing Accessibility -@cindex accessibility of a file -@cindex file accessibility - - These functions test for permission to access a file for reading, -writing, or execution. Unless explicitly stated otherwise, they -recursively follow symbolic links for their file name arguments, at -all levels (at the level of the file itself and at all levels of -parent directories). - - On some operating systems, more complex sets of access permissions -can be specified, via mechanisms such as Access Control Lists (ACLs). -@xref{Extended Attributes}, for how to query and set those -permissions. - -@defun file-exists-p filename -This function returns @code{t} if a file named @var{filename} appears -to exist. This does not mean you can necessarily read the file, only -that you can find out its attributes. (On Unix and GNU/Linux, this is -true if the file exists and you have execute permission on the -containing directories, regardless of the permissions of the file -itself.) - -If the file does not exist, or if access control policies prevent you -from finding its attributes, this function returns @code{nil}. - -Directories are files, so @code{file-exists-p} returns @code{t} when -given a directory name. However, symbolic links are treated -specially; @code{file-exists-p} returns @code{t} for a symbolic link -name only if the target file exists. -@end defun - -@defun file-readable-p filename -This function returns @code{t} if a file named @var{filename} exists -and you can read it. It returns @code{nil} otherwise. -@end defun - -@defun file-executable-p filename -This function returns @code{t} if a file named @var{filename} exists and -you can execute it. It returns @code{nil} otherwise. On Unix and -GNU/Linux, if the file is a directory, execute permission means you can -check the existence and attributes of files inside the directory, and -open those files if their modes permit. -@end defun - -@defun file-writable-p filename -This function returns @code{t} if the file @var{filename} can be written -or created by you, and @code{nil} otherwise. A file is writable if the -file exists and you can write it. It is creatable if it does not exist, -but the specified directory does exist and you can write in that -directory. - -In the example below, @file{foo} is not writable because the parent -directory does not exist, even though the user could create such a -directory. - -@example -@group -(file-writable-p "~/no-such-dir/foo") - @result{} nil -@end group -@end example -@end defun - -@defun file-accessible-directory-p dirname -This function returns @code{t} if you have permission to open existing -files in the directory whose name as a file is @var{dirname}; -otherwise (or if there is no such directory), it returns @code{nil}. -The value of @var{dirname} may be either a directory name (such as -@file{/foo/}) or the file name of a file which is a directory -(such as @file{/foo}, without the final slash). - -For example, from the following we deduce that any attempt to read a -file in @file{/foo/} will give an error: - -@example -(file-accessible-directory-p "/foo") - @result{} nil -@end example -@end defun - -@defun access-file filename string -This function opens file @var{filename} for reading, then closes it and -returns @code{nil}. However, if the open fails, it signals an error -using @var{string} as the error message text. -@end defun - -@defun file-ownership-preserved-p filename &optional group -This function returns @code{t} if deleting the file @var{filename} and -then creating it anew would keep the file's owner unchanged. It also -returns @code{t} for nonexistent files. - -If the optional argument @var{group} is non-@code{nil}, this function -also checks that the file's group would be unchanged. - -If @var{filename} is a symbolic link, then, unlike the other functions -discussed here, @code{file-ownership-preserved-p} does @emph{not} -replace @var{filename} with its target. However, it does recursively -follow symbolic links at all levels of parent directories. -@end defun - -@defun file-modes filename -@cindex mode bits -@cindex file permissions -@cindex permissions, file -@cindex file modes -This function returns the @dfn{mode bits} of @var{filename}---an -integer summarizing its read, write, and execution permissions. -Symbolic links in @var{filename} are recursively followed at all -levels. If the file does not exist, the return value is @code{nil}. - -@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils} -Manual}, for a description of mode bits. For example, if the -low-order bit is 1, the file is executable by all users; if the -second-lowest-order bit is 1, the file is writable by all users; etc. -The highest possible value is 4095 (7777 octal), meaning that everyone -has read, write, and execute permission, the @acronym{SUID} bit is set -for both others and group, and the sticky bit is set. - -@xref{Changing Files}, for the @code{set-file-modes} function, which -can be used to set these permissions. - -@example -@group -(file-modes "~/junk/diffs") - @result{} 492 ; @r{Decimal integer.} -@end group -@group -(format "%o" 492) - @result{} "754" ; @r{Convert to octal.} -@end group - -@group -(set-file-modes "~/junk/diffs" #o666) - @result{} nil -@end group - -@group -$ ls -l diffs --rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs -@end group -@end example - -@cindex MS-DOS and file modes -@cindex file modes and MS-DOS -@strong{MS-DOS note:} On MS-DOS, there is no such thing as an -``executable'' file mode bit. So @code{file-modes} considers a file -executable if its name ends in one of the standard executable -extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some -others. Files that begin with the Unix-standard @samp{#!} signature, -such as shell and Perl scripts, are also considered executable. -Directories are also reported as executable, for compatibility with -Unix. These conventions are also followed by @code{file-attributes} -(@pxref{File Attributes}). -@end defun - -@node Kinds of Files -@subsection Distinguishing Kinds of Files - - This section describes how to distinguish various kinds of files, such -as directories, symbolic links, and ordinary files. - -@defun file-symlink-p filename -@cindex file symbolic links -If the file @var{filename} is a symbolic link, the -@code{file-symlink-p} function returns its (non-recursive) link target -as a string. (The link target string is not necessarily the full -absolute file name of the target; determining the full file name that -the link points to is nontrivial, see below.) If the leading -directories of @var{filename} include symbolic links, this function -recursively follows them. - -If the file @var{filename} is not a symbolic link, or does not exist, -@code{file-symlink-p} returns @code{nil}. - -Here are a few examples of using this function: - -@example -@group -(file-symlink-p "not-a-symlink") - @result{} nil -@end group -@group -(file-symlink-p "sym-link") - @result{} "not-a-symlink" -@end group -@group -(file-symlink-p "sym-link2") - @result{} "sym-link" -@end group -@group -(file-symlink-p "/bin") - @result{} "/pub/bin" -@end group -@end example - -Note that in the third example, the function returned @file{sym-link}, -but did not proceed to resolve it, although that file is itself a -symbolic link. This is what we meant by ``non-recursive'' above---the -process of following the symbolic links does not recurse if the link -target is itself a link. - -The string that this function returns is what is recorded in the -symbolic link; it may or may not include any leading directories. -This function does @emph{not} expand the link target to produce a -fully-qualified file name, and in particular does not use the leading -directories, if any, of the @var{filename} argument if the link target -is not an absolute file name. Here's an example: - -@example -@group -(file-symlink-p "/foo/bar/baz") - @result{} "some-file" -@end group -@end example - -@noindent -Here, although @file{/foo/bar/baz} was given as a fully-qualified file -name, the result is not, and in fact does not have any leading -directories at all. And since @file{some-file} might itself be a -symbolic link, you cannot simply prepend leading directories to it, -nor even naively use @code{expand-file-name} (@pxref{File Name -Expansion}) to produce its absolute file name. - -For this reason, this function is seldom useful if you need to -determine more than just the fact that a file is or isn't a symbolic -link. If you actually need the file name of the link target, use -@code{file-chase-links} or @code{file-truename}, described in -@ref{Truenames}. -@end defun - -The next two functions recursively follow symbolic links at -all levels for @var{filename}. - -@defun file-directory-p filename -This function returns @code{t} if @var{filename} is the name of an -existing directory, @code{nil} otherwise. - -@example -@group -(file-directory-p "~rms") - @result{} t -@end group -@group -(file-directory-p "~rms/lewis/files.texi") - @result{} nil -@end group -@group -(file-directory-p "~rms/lewis/no-such-file") - @result{} nil -@end group -@group -(file-directory-p "$HOME") - @result{} nil -@end group -@group -(file-directory-p - (substitute-in-file-name "$HOME")) - @result{} t -@end group -@end example -@end defun - -@defun file-regular-p filename -This function returns @code{t} if the file @var{filename} exists and is -a regular file (not a directory, named pipe, terminal, or -other I/O device). -@end defun - -@node Truenames -@subsection Truenames -@cindex truename (of file) - - The @dfn{truename} of a file is the name that you get by following -symbolic links at all levels until none remain, then simplifying away -@samp{.}@: and @samp{..}@: appearing as name components. This results -in a sort of canonical name for the file. A file does not always have a -unique truename; the number of distinct truenames a file has is equal to -the number of hard links to the file. However, truenames are useful -because they eliminate symbolic links as a cause of name variation. - -@defun file-truename filename -This function returns the truename of the file @var{filename}. If the -argument is not an absolute file name, this function first expands it -against @code{default-directory}. - -This function does not expand environment variables. Only -@code{substitute-in-file-name} does that. @xref{Definition of -substitute-in-file-name}. - -If you may need to follow symbolic links preceding @samp{..}@: -appearing as a name component, call @code{file-truename} without prior -direct or indirect calls to @code{expand-file-name}. Otherwise, the -file name component immediately preceding @samp{..} will be -``simplified away'' before @code{file-truename} is called. To -eliminate the need for a call to @code{expand-file-name}, -@code{file-truename} handles @samp{~} in the same way that -@code{expand-file-name} does. @xref{File Name Expansion,, Functions -that Expand Filenames}. -@end defun - -@defun file-chase-links filename &optional limit -This function follows symbolic links, starting with @var{filename}, -until it finds a file name which is not the name of a symbolic link. -Then it returns that file name. This function does @emph{not} follow -symbolic links at the level of parent directories. - -If you specify a number for @var{limit}, then after chasing through -that many links, the function just returns what it has even if that is -still a symbolic link. -@end defun - - To illustrate the difference between @code{file-chase-links} and -@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to -the directory @file{/home/foo}, and @file{/home/foo/hello} is an -ordinary file (or at least, not a symbolic link) or nonexistent. Then -we would have: - -@example -(file-chase-links "/usr/foo/hello") - ;; @r{This does not follow the links in the parent directories.} - @result{} "/usr/foo/hello" -(file-truename "/usr/foo/hello") - ;; @r{Assuming that @file{/home} is not a symbolic link.} - @result{} "/home/foo/hello" -@end example - -@defun file-equal-p file1 file2 -This function returns @code{t} if the files @var{file1} and -@var{file2} name the same file. This is similar to comparing their -truenames, except that remote file names are also handled in an -appropriate manner. If @var{file1} or @var{file2} does not exist, the -return value is unspecified. -@end defun - -@defun file-in-directory-p file dir -This function returns @code{t} if @var{file} is a file in directory -@var{dir}, or in a subdirectory of @var{dir}. It also returns -@code{t} if @var{file} and @var{dir} are the same directory. It -compares the truenames of the two directories. If @var{dir} does not -name an existing directory, the return value is @code{nil}. -@end defun - -@node File Attributes -@subsection File Attributes -@cindex file attributes - - This section describes the functions for getting detailed -information about a file, including the owner and group numbers, the -number of names, the inode number, the size, and the times of access -and modification. - -@defun file-newer-than-file-p filename1 filename2 -@cindex file age -@cindex file modification time -This function returns @code{t} if the file @var{filename1} is -newer than file @var{filename2}. If @var{filename1} does not -exist, it returns @code{nil}. If @var{filename1} does exist, but -@var{filename2} does not, it returns @code{t}. - -In the following example, assume that the file @file{aug-19} was written -on the 19th, @file{aug-20} was written on the 20th, and the file -@file{no-file} doesn't exist at all. - -@example -@group -(file-newer-than-file-p "aug-19" "aug-20") - @result{} nil -@end group -@group -(file-newer-than-file-p "aug-20" "aug-19") - @result{} t -@end group -@group -(file-newer-than-file-p "aug-19" "no-file") - @result{} t -@end group -@group -(file-newer-than-file-p "no-file" "aug-19") - @result{} nil -@end group -@end example -@end defun - - If the @var{filename} argument to the next two functions is a -symbolic link, then these function do @emph{not} replace it with its -target. However, they both recursively follow symbolic links at all -levels of parent directories. - -@defun file-attributes filename &optional id-format -@anchor{Definition of file-attributes} -This function returns a list of attributes of file @var{filename}. If -the specified file cannot be opened, it returns @code{nil}. -The optional parameter @var{id-format} specifies the preferred format -of attributes @acronym{UID} and @acronym{GID} (see below)---the -valid values are @code{'string} and @code{'integer}. The latter is -the default, but we plan to change that, so you should specify a -non-@code{nil} value for @var{id-format} if you use the returned -@acronym{UID} or @acronym{GID}. - -The elements of the list, in order, are: - -@enumerate 0 -@item -@code{t} for a directory, a string for a symbolic link (the name -linked to), or @code{nil} for a text file. - -@c Wordy so as to prevent an overfull hbox. --rjc 15mar92 -@item -The number of names the file has. Alternate names, also known as hard -links, can be created by using the @code{add-name-to-file} function -(@pxref{Changing Files}). - -@item -The file's @acronym{UID}, normally as a string. However, if it does -not correspond to a named user, the value is a number. - -@item -The file's @acronym{GID}, likewise. - -@item -The time of last access, as a list of four integers @code{(@var{sec-high} -@var{sec-low} @var{microsec} @var{picosec})}. (This is similar to the -value of @code{current-time}; see @ref{Time of Day}.) Note that on -some FAT-based filesystems, only the date of last access is recorded, -so this time will always hold the midnight of the day of last access. - -@cindex modification time of file -@item -The time of last modification as a list of four integers (as above). -This is the last time when the file's contents were modified. - -@item -The time of last status change as a list of four integers (as above). -This is the time of the last change to the file's access mode bits, -its owner and group, and other information recorded in the filesystem -for the file, beyond the file's contents. - -@item -The size of the file in bytes. This is floating point if the size is -too large to fit in a Lisp integer. - -@item -The file's modes, as a string of ten letters or dashes, -as in @samp{ls -l}. - -@item -An unspecified value, present for backward compatibility. - -@item -The file's inode number. If possible, this is an integer. If the -inode number is too large to be represented as an integer in Emacs -Lisp but dividing it by @math{2^{16}} yields a representable integer, -then the value has the -form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 -bits. If the inode number is too wide for even that, the value is of the form -@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds -the high bits, @var{middle} the middle 24 bits, and @var{low} the low -16 bits. - -@item -The filesystem number of the device that the file is on. Depending on -the magnitude of the value, this can be either an integer or a cons -cell, in the same manner as the inode number. This element and the -file's inode number together give enough information to distinguish -any two files on the system---no two files can have the same values -for both of these numbers. -@end enumerate - -For example, here are the file attributes for @file{files.texi}: - -@example -@group -(file-attributes "files.texi" 'string) - @result{} (nil 1 "lh" "users" - (20614 64019 50040 152000) - (20000 23 0 0) - (20614 64555 902289 872000) - 122295 "-rw-rw-rw-" - t (5888 2 . 43978) - (15479 . 46724)) -@end group -@end example - -@noindent -and here is how the result is interpreted: - -@table @code -@item nil -is neither a directory nor a symbolic link. - -@item 1 -has only one name (the name @file{files.texi} in the current default -directory). - -@item "lh" -is owned by the user with name "lh". - -@item "users" -is in the group with name "users". - -@item (20614 64019 50040 152000) -was last accessed on October 23, 2012, at 20:12:03.050040152 UTC. - -@item (20000 23 0 0) -was last modified on July 15, 2001, at 08:53:43 UTC. - -@item (20614 64555 902289 872000) -last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC. - -@item 122295 -is 122295 bytes long. (It may not contain 122295 characters, though, -if some of the bytes belong to multibyte sequences, and also if the -end-of-line format is CR-LF.) - -@item "-rw-rw-rw-" -has a mode of read and write access for the owner, group, and world. - -@item t -is merely a placeholder; it carries no information. - -@item (5888 2 . 43978) -has an inode number of 6473924464520138. - -@item (15479 . 46724) -is on the file-system device whose number is 1014478468. -@end table -@end defun - -@defun file-nlinks filename -This function returns the number of names (i.e., hard links) that -file @var{filename} has. If the file does not exist, this function -returns @code{nil}. Note that symbolic links have no effect on this -function, because they are not considered to be names of the files -they link to. - -@example -@group -$ ls -l foo* --rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo --rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1 -@end group - -@group -(file-nlinks "foo") - @result{} 2 -@end group -@group -(file-nlinks "doesnt-exist") - @result{} nil -@end group -@end example -@end defun - -@node Extended Attributes -@subsection Extended File Attributes -@cindex extended file attributes - -On some operating systems, each file can be associated with arbitrary -@dfn{extended file attributes}. At present, Emacs supports querying -and setting two specific sets of extended file attributes: Access -Control Lists (ACLs) and SELinux contexts. These extended file -attributes are used, on some systems, to impose more sophisticated -file access controls than the basic ``Unix-style'' permissions -discussed in the previous sections. - -@cindex access control list -@cindex ACL entries -@cindex SELinux context - A detailed explanation of ACLs and SELinux is beyond the scope of -this manual. For our purposes, each file can be associated with an -@dfn{ACL}, which specifies its properties under an ACL-based file -control system, and/or an @dfn{SELinux context}, which specifies its -properties under the SELinux system. - -@defun file-acl filename -This function returns the ACL for the file @var{filename}. The exact -Lisp representation of the ACL is unspecified (and may change in -future Emacs versions), but it is the same as what @code{set-file-acl} -takes for its @var{acl} argument (@pxref{Changing Files}). - -The underlying ACL implementation is platform-specific; on GNU/Linux -and BSD, Emacs uses the POSIX ACL interface, while on MS-Windows Emacs -emulates the POSIX ACL interface with native file security APIs. - -If Emacs was not compiled with ACL support, or the file does not exist -or is inaccessible, or Emacs was unable to determine the ACL entries -for any other reason, then the return value is @code{nil}. -@end defun - -@defun file-selinux-context filename -This function returns the SELinux context of the file @var{filename}, -as a list of the form @code{(@var{user} @var{role} @var{type} -@var{range})}. The list elements are the context's user, role, type, -and range respectively, as Lisp strings; see the SELinux documentation -for details about what these actually mean. The return value has the -same form as what @code{set-file-selinux-context} takes for its -@var{context} argument (@pxref{Changing Files}). - -If Emacs was not compiled with SELinux support, or the file does not -exist or is inaccessible, or if the system does not support SELinux, -then the return value is @code{(nil nil nil nil)}. -@end defun - -@defun file-extended-attributes filename -This function returns an alist of the Emacs-recognized extended -attributes of file @var{filename}. Currently, it serves as a -convenient way to retrieve both the ACL and SELinux context; you can -then call the function @code{set-file-extended-attributes}, with the -returned alist as its second argument, to apply the same file access -attributes to another file (@pxref{Changing Files}). - -One of the elements is @code{(acl . @var{acl})}, where @var{acl} has -the same form returned by @code{file-acl}. - -Another element is @code{(selinux-context . @var{context})}, where -@var{context} is the SELinux context, in the same form returned by -@code{file-selinux-context}. -@end defun - -@node Locating Files -@subsection Locating Files in Standard Places -@cindex locate file in path -@cindex find file in path - - This section explains how to search for a file in a list of -directories (a @dfn{path}), or for an executable file in the standard -list of executable file directories. - - To search for a user-specific configuration file, @xref{Standard -File Names}, for the @code{locate-user-emacs-file} function. - -@defun locate-file filename path &optional suffixes predicate -This function searches for a file whose name is @var{filename} in a -list of directories given by @var{path}, trying the suffixes in -@var{suffixes}. If it finds such a file, it returns the file's -absolute file name (@pxref{Relative File Names}); otherwise it returns -@code{nil}. - -The optional argument @var{suffixes} gives the list of file-name -suffixes to append to @var{filename} when searching. -@code{locate-file} tries each possible directory with each of these -suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there -are no suffixes, and @var{filename} is used only as-is. Typical -values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess -Creation}), @code{load-suffixes}, @code{load-file-rep-suffixes} and -the return value of the function @code{get-load-suffixes} (@pxref{Load -Suffixes}). - -Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess -Creation}) when looking for executable programs, or @code{load-path} -(@pxref{Library Search}) when looking for Lisp files. If -@var{filename} is absolute, @var{path} has no effect, but the suffixes -in @var{suffixes} are still tried. - -The optional argument @var{predicate}, if non-@code{nil}, specifies a -predicate function for testing whether a candidate file is suitable. -The predicate is passed the candidate file name as its single -argument. If @var{predicate} is @code{nil} or omitted, -@code{locate-file} uses @code{file-readable-p} as the predicate. -@xref{Kinds of Files}, for other useful predicates, e.g., -@code{file-executable-p} and @code{file-directory-p}. - -For compatibility, @var{predicate} can also be one of the symbols -@code{executable}, @code{readable}, @code{writable}, @code{exists}, or -a list of one or more of these symbols. -@end defun - -@defun executable-find program -This function searches for the executable file of the named -@var{program} and returns the absolute file name of the executable, -including its file-name extensions, if any. It returns @code{nil} if -the file is not found. The functions searches in all the directories -in @code{exec-path}, and tries all the file-name extensions in -@code{exec-suffixes} (@pxref{Subprocess Creation}). -@end defun - -@node Changing Files -@section Changing File Names and Attributes -@c @cindex renaming files Duplicates rename-file -@cindex copying files -@cindex deleting files -@cindex linking files -@cindex setting modes of files - - The functions in this section rename, copy, delete, link, and set -the modes (permissions) of files. - - In the functions that have an argument @var{newname}, if a file by the -name of @var{newname} already exists, the actions taken depend on the -value of the argument @var{ok-if-already-exists}: - -@itemize @bullet -@item -Signal a @code{file-already-exists} error if -@var{ok-if-already-exists} is @code{nil}. - -@item -Request confirmation if @var{ok-if-already-exists} is a number. - -@item -Replace the old file without confirmation if @var{ok-if-already-exists} -is any other value. -@end itemize - -The next four commands all recursively follow symbolic links at all -levels of parent directories for their first argument, but, if that -argument is itself a symbolic link, then only @code{copy-file} -replaces it with its (recursive) target. - -@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists -@cindex file with multiple names -@cindex file hard link -This function gives the file named @var{oldname} the additional name -@var{newname}. This means that @var{newname} becomes a new ``hard -link'' to @var{oldname}. - -In the first part of the following example, we list two files, -@file{foo} and @file{foo3}. - -@example -@group -$ ls -li fo* -81908 -rw-rw-rw- 1 rms rms 29 Aug 18 20:32 foo -84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3 -@end group -@end example - -Now we create a hard link, by calling @code{add-name-to-file}, then list -the files again. This shows two names for one file, @file{foo} and -@file{foo2}. - -@example -@group -(add-name-to-file "foo" "foo2") - @result{} nil -@end group - -@group -$ ls -li fo* -81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo -81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo2 -84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3 -@end group -@end example - -Finally, we evaluate the following: - -@example -(add-name-to-file "foo" "foo3" t) -@end example - -@noindent -and list the files again. Now there are three names -for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old -contents of @file{foo3} are lost. - -@example -@group -(add-name-to-file "foo1" "foo3") - @result{} nil -@end group - -@group -$ ls -li fo* -81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo -81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo2 -81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo3 -@end group -@end example - -This function is meaningless on operating systems where multiple names -for one file are not allowed. Some systems implement multiple names -by copying the file instead. - -See also @code{file-nlinks} in @ref{File Attributes}. -@end deffn - -@deffn Command rename-file filename newname &optional ok-if-already-exists -This command renames the file @var{filename} as @var{newname}. - -If @var{filename} has additional names aside from @var{filename}, it -continues to have those names. In fact, adding the name @var{newname} -with @code{add-name-to-file} and then deleting @var{filename} has the -same effect as renaming, aside from momentary intermediate states. -@end deffn - -@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-extended-attributes -This command copies the file @var{oldname} to @var{newname}. An -error is signaled if @var{oldname} does not exist. If @var{newname} -names a directory, it copies @var{oldname} into that directory, -preserving its final name component. - -If @var{time} is non-@code{nil}, then this function gives the new file -the same last-modified time that the old one has. (This works on only -some operating systems.) If setting the time gets an error, -@code{copy-file} signals a @code{file-date-error} error. In an -interactive call, a prefix argument specifies a non-@code{nil} value -for @var{time}. - -If argument @var{preserve-uid-gid} is @code{nil}, we let the operating -system decide the user and group ownership of the new file (this is -usually set to the user running Emacs). If @var{preserve-uid-gid} is -non-@code{nil}, we attempt to copy the user and group ownership of the -file. This works only on some operating systems, and only if you have -the correct permissions to do so. - -If the optional argument @var{preserve-permissions} is non-@code{nil}, -this function copies the file modes (or ``permissions'') of -@var{oldname} to @var{newname}, as well as the Access Control List and -SELinux context (if any). @xref{Information about Files}. - -Otherwise, the file modes of @var{newname} are left unchanged if it is -an existing file, and set to those of @var{oldname}, masked by the -default file permissions (see @code{set-default-file-modes} below), if -@var{newname} is to be newly created. The Access Control List or -SELinux context are not copied over in either case. -@end deffn - -@deffn Command make-symbolic-link filename newname &optional ok-if-exists -@pindex ln -@kindex file-already-exists -This command makes a symbolic link to @var{filename}, named -@var{newname}. This is like the shell command @samp{ln -s -@var{filename} @var{newname}}. - -This function is not available on systems that don't support symbolic -links. -@end deffn - -@cindex trash -@vindex delete-by-moving-to-trash -@deffn Command delete-file filename &optional trash -@pindex rm -This command deletes the file @var{filename}. If the file has -multiple names, it continues to exist under the other names. If -@var{filename} is a symbolic link, @code{delete-file} deletes only the -symbolic link and not its target (though it does follow symbolic links -at all levels of parent directories). - -A suitable kind of @code{file-error} error is signaled if the file -does not exist, or is not deletable. (On Unix and GNU/Linux, a file -is deletable if its directory is writable.) - -If the optional argument @var{trash} is non-@code{nil} and the -variable @code{delete-by-moving-to-trash} is non-@code{nil}, this -command moves the file into the system Trash instead of deleting it. -@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU -Emacs Manual}. When called interactively, @var{trash} is @code{t} if -no prefix argument is given, and @code{nil} otherwise. - -See also @code{delete-directory} in @ref{Create/Delete Dirs}. -@end deffn - -@cindex file permissions, setting -@cindex permissions, file -@cindex file modes, setting -@deffn Command set-file-modes filename mode -This function sets the @dfn{file mode} (or @dfn{permissions}) of -@var{filename} to @var{mode}. It recursively follows symbolic links -at all levels for @var{filename}. - -If called non-interactively, @var{mode} must be an integer. Only the -lowest 12 bits of the integer are used; on most systems, only the -lowest 9 bits are meaningful. You can use the Lisp construct for -octal numbers to enter @var{mode}. For example, - -@example -(set-file-modes #o644) -@end example - -@noindent -specifies that the file should be readable and writable for its owner, -readable for group members, and readable for all other users. -@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils} -Manual}, for a description of mode bit specifications. - -Interactively, @var{mode} is read from the minibuffer using -@code{read-file-modes} (see below), which lets the user type in either -an integer or a string representing the permissions symbolically. - -@xref{File Attributes}, for the function @code{file-modes}, which -returns the permissions of a file. -@end deffn - -@defun set-default-file-modes mode -@cindex umask -This function sets the default permissions for new files created by -Emacs and its subprocesses. Every file created with Emacs initially -has these permissions, or a subset of them (@code{write-region} will -not grant execute permissions even if the default file permissions -allow execution). On Unix and GNU/Linux, the default permissions are -given by the bitwise complement of the ``umask'' value. - -The argument @var{mode} should be an integer which specifies the -permissions, similar to @code{set-file-modes} above. Only the lowest -9 bits are meaningful. - -The default file permissions have no effect when you save a modified -version of an existing file; saving a file preserves its existing -permissions. -@end defun - -@defun default-file-modes -This function returns the default file permissions, as an integer. -@end defun - -@defun read-file-modes &optional prompt base-file -This function reads a set of file mode bits from the minibuffer. The -first optional argument @var{prompt} specifies a non-default prompt. -Second second optional argument @var{base-file} is the name of a file -on whose permissions to base the mode bits that this function returns, -if what the user types specifies mode bits relative to permissions of -an existing file. - -If user input represents an octal number, this function returns that -number. If it is a complete symbolic specification of mode bits, as -in @code{"u=rwx"}, the function converts it to the equivalent numeric -value using @code{file-modes-symbolic-to-number} and returns the -result. If the specification is relative, as in @code{"o+g"}, then -the permissions on which the specification is based are taken from the -mode bits of @var{base-file}. If @var{base-file} is omitted or -@code{nil}, the function uses @code{0} as the base mode bits. The -complete and relative specifications can be combined, as in -@code{"u+r,g+rx,o+r,g-w"}. @xref{File permissions,,, coreutils, The -@sc{gnu} @code{Coreutils} Manual}, for a description of file mode -specifications. -@end defun - -@defun file-modes-symbolic-to-number modes &optional base-modes -This function converts a symbolic file mode specification in -@var{modes} into the equivalent integer. If the symbolic -specification is based on an existing file, that file's mode bits are -taken from the optional argument @var{base-modes}; if that argument is -omitted or @code{nil}, it defaults to 0, i.e., no access rights at -all. -@end defun - -@defun set-file-times filename &optional time -This function sets the access and modification times of @var{filename} -to @var{time}. The return value is @code{t} if the times are successfully -set, otherwise it is @code{nil}. @var{time} defaults to the current -time and must be in the format returned by @code{current-time} -(@pxref{Time of Day}). -@end defun - -@defun set-file-extended-attributes filename attribute-alist -This function sets the Emacs-recognized extended file attributes for -@code{filename}. The second argument @var{attribute-alist} should be -an alist of the same form returned by @code{file-extended-attributes}. -@xref{Extended Attributes}. -@end defun - -@defun set-file-selinux-context filename context -This function sets the SELinux security context for @var{filename} to -@var{context}. The @var{context} argument should be a list -@code{(@var{user} @var{role} @var{type} @var{range})}, where each -element is a string. @xref{Extended Attributes}. - -The function returns @code{t} if it succeeds in setting the SELinux -context of @var{filename}. It returns @code{nil} if the context was -not set (e.g., if SELinux is disabled, or if Emacs was compiled -without SELinux support). -@end defun - -@defun set-file-acl filename acl -This function sets the Access Control List for @var{filename} to -@var{acl}. The @var{acl} argument should have the same form returned -by the function @code{file-acl}. @xref{Extended Attributes}. - -The function returns @code{t} if it successfully sets the ACL of -@var{filename}, @code{nil} otherwise. -@end defun - -@node File Names -@section File Names -@cindex file names - - Files are generally referred to by their names, in Emacs as elsewhere. -File names in Emacs are represented as strings. The functions that -operate on a file all expect a file name argument. - - In addition to operating on files themselves, Emacs Lisp programs -often need to operate on file names; i.e., to take them apart and to use -part of a name to construct related file names. This section describes -how to manipulate file names. - - The functions in this section do not actually access files, so they -can operate on file names that do not refer to an existing file or -directory. - -@findex cygwin-convert-file-name-from-windows -@findex cygwin-convert-file-name-to-windows -@cindex MS-Windows file-name syntax -@cindex converting file names from/to MS-Windows syntax - On MS-DOS and MS-Windows, these functions (like the function that -actually operate on files) accept MS-DOS or MS-Windows file-name syntax, -where backslashes separate the components, as well as Unix syntax; but -they always return Unix syntax. This enables Lisp programs to specify -file names in Unix syntax and work properly on all systems without -change.@footnote{In MS-Windows versions of Emacs compiled for the Cygwin -environment, you can use the functions -@code{cygwin-convert-file-name-to-windows} and -@code{cygwin-convert-file-name-from-windows} to convert between the -two file-name syntaxes.} - -@menu -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. -@end menu - -@node File Name Components -@subsection File Name Components -@cindex directory part (of file name) -@cindex nondirectory part (of file name) -@cindex version number (in file name) - - The operating system groups files into directories. To specify a -file, you must specify the directory and the file's name within that -directory. Therefore, Emacs considers a file name as having two main -parts: the @dfn{directory name} part, and the @dfn{nondirectory} part -(or @dfn{file name within the directory}). Either part may be empty. -Concatenating these two parts reproduces the original file name. - - On most systems, the directory part is everything up to and including -the last slash (backslash is also allowed in input on MS-DOS or -MS-Windows); the nondirectory part is the rest. - - For some purposes, the nondirectory part is further subdivided into -the name proper and the @dfn{version number}. On most systems, only -backup files have version numbers in their names. - -@defun file-name-directory filename -This function returns the directory part of @var{filename}, as a -directory name (@pxref{Directory Names}), or @code{nil} if -@var{filename} does not include a directory part. - -On GNU and Unix systems, a string returned by this function always -ends in a slash. On MS-DOS it can also end in a colon. - -@example -@group -(file-name-directory "lewis/foo") ; @r{Unix example} - @result{} "lewis/" -@end group -@group -(file-name-directory "foo") ; @r{Unix example} - @result{} nil -@end group -@end example -@end defun - -@defun file-name-nondirectory filename -This function returns the nondirectory part of @var{filename}. - -@example -@group -(file-name-nondirectory "lewis/foo") - @result{} "foo" -@end group -@group -(file-name-nondirectory "foo") - @result{} "foo" -@end group -@group -(file-name-nondirectory "lewis/") - @result{} "" -@end group -@end example -@end defun - -@defun file-name-sans-versions filename &optional keep-backup-version -This function returns @var{filename} with any file version numbers, -backup version numbers, or trailing tildes discarded. - -If @var{keep-backup-version} is non-@code{nil}, then true file version -numbers understood as such by the file system are discarded from the -return value, but backup version numbers are kept. - -@example -@group -(file-name-sans-versions "~rms/foo.~1~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo") - @result{} "~rms/foo" -@end group -@end example -@end defun - -@defun file-name-extension filename &optional period -This function returns @var{filename}'s final ``extension'', if any, -after applying @code{file-name-sans-versions} to remove any -version/backup part. The extension, in a file name, is the part that -follows the last @samp{.} in the last name component (minus any -version/backup part). - -This function returns @code{nil} for extensionless file names such as -@file{foo}. It returns @code{""} for null extensions, as in -@file{foo.}. If the last component of a file name begins with a -@samp{.}, that @samp{.} doesn't count as the beginning of an -extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not -@samp{.emacs}. - -If @var{period} is non-@code{nil}, then the returned value includes -the period that delimits the extension, and if @var{filename} has no -extension, the value is @code{""}. -@end defun - -@defun file-name-sans-extension filename -This function returns @var{filename} minus its extension, if any. The -version/backup part, if present, is only removed if the file has an -extension. For example, - -@example -(file-name-sans-extension "foo.lose.c") - @result{} "foo.lose" -(file-name-sans-extension "big.hack/foo") - @result{} "big.hack/foo" -(file-name-sans-extension "/my/home/.emacs") - @result{} "/my/home/.emacs" -(file-name-sans-extension "/my/home/.emacs.el") - @result{} "/my/home/.emacs" -(file-name-sans-extension "~/foo.el.~3~") - @result{} "~/foo" -(file-name-sans-extension "~/foo.~3~") - @result{} "~/foo.~3~" -@end example - -Note that the @samp{.~3~} in the two last examples is the backup part, -not an extension. -@end defun - -@defun file-name-base &optional filename -This function is the composition of @code{file-name-sans-extension} -and @code{file-name-nondirectory}. For example, - -@example -(file-name-base "/my/home/foo.c") - @result{} "foo" -@end example - -The @var{filename} argument defaults to @code{buffer-file-name}. -@end defun - -@node Relative File Names -@subsection Absolute and Relative File Names -@cindex absolute file name -@cindex relative file name - - All the directories in the file system form a tree starting at the -root directory. A file name can specify all the directory names -starting from the root of the tree; then it is called an -@dfn{absolute} file name. Or it can specify the position of the file -in the tree relative to a default directory; then it is called a -@dfn{relative} file name. On Unix and GNU/Linux, an absolute file -name starts with a @samp{/} or a @samp{~} -(@pxref{abbreviate-file-name}), and a relative one does not. On -MS-DOS and MS-Windows, an absolute file name starts with a slash or a -backslash, or with a drive specification @samp{@var{x}:/}, where -@var{x} is the @dfn{drive letter}. - -@defun file-name-absolute-p filename -This function returns @code{t} if file @var{filename} is an absolute -file name, @code{nil} otherwise. - -@example -@group -(file-name-absolute-p "~rms/foo") - @result{} t -@end group -@group -(file-name-absolute-p "rms/foo") - @result{} nil -@end group -@group -(file-name-absolute-p "/user/rms/foo") - @result{} t -@end group -@end example -@end defun - - Given a possibly relative file name, you can convert it to an -absolute name using @code{expand-file-name} (@pxref{File Name -Expansion}). This function converts absolute file names to relative -names: - -@defun file-relative-name filename &optional directory -This function tries to return a relative name that is equivalent to -@var{filename}, assuming the result will be interpreted relative to -@var{directory} (an absolute directory name or directory file name). -If @var{directory} is omitted or @code{nil}, it defaults to the -current buffer's default directory. - -On some operating systems, an absolute file name begins with a device -name. On such systems, @var{filename} has no relative equivalent based -on @var{directory} if they start with two different device names. In -this case, @code{file-relative-name} returns @var{filename} in absolute -form. - -@example -(file-relative-name "/foo/bar" "/foo/") - @result{} "bar" -(file-relative-name "/foo/bar" "/hack/") - @result{} "../foo/bar" -@end example -@end defun - -@node Directory Names -@subsection Directory Names -@cindex directory name -@cindex file name of directory - - A @dfn{directory name} is the name of a directory. A directory is -actually a kind of file, so it has a file name, which is related to -the directory name but not identical to it. (This is not quite the -same as the usual Unix terminology.) These two different names for -the same entity are related by a syntactic transformation. On GNU and -Unix systems, this is simple: a directory name ends in a slash, -whereas the directory's name as a file lacks that slash. On MS-DOS -the relationship is more complicated. - - The difference between a directory name and its name as a file is -subtle but crucial. When an Emacs variable or function argument is -described as being a directory name, a file name of a directory is not -acceptable. When @code{file-name-directory} returns a string, that is -always a directory name. - - The following two functions convert between directory names and file -names. They do nothing special with environment variable substitutions -such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}. - -@defun file-name-as-directory filename -This function returns a string representing @var{filename} in a form -that the operating system will interpret as the name of a directory. On -most systems, this means appending a slash to the string (if it does not -already end in one). - -@example -@group -(file-name-as-directory "~rms/lewis") - @result{} "~rms/lewis/" -@end group -@end example -@end defun - -@defun directory-file-name dirname -This function returns a string representing @var{dirname} in a form that -the operating system will interpret as the name of a file. On most -systems, this means removing the final slash (or backslash) from the -string. - -@example -@group -(directory-file-name "~lewis/") - @result{} "~lewis" -@end group -@end example -@end defun - - Given a directory name, you can combine it with a relative file name -using @code{concat}: - -@example -(concat @var{dirname} @var{relfile}) -@end example - -@noindent -Be sure to verify that the file name is relative before doing that. -If you use an absolute file name, the results could be syntactically -invalid or refer to the wrong file. - - If you want to use a directory file name in making such a -combination, you must first convert it to a directory name using -@code{file-name-as-directory}: - -@example -(concat (file-name-as-directory @var{dirfile}) @var{relfile}) -@end example - -@noindent -Don't try concatenating a slash by hand, as in - -@example -;;; @r{Wrong!} -(concat @var{dirfile} "/" @var{relfile}) -@end example - -@noindent -because this is not portable. Always use -@code{file-name-as-directory}. - - To convert a directory name to its abbreviation, use this -function: - -@cindex file name abbreviations -@cindex abbreviated file names -@defun abbreviate-file-name filename -@anchor{abbreviate-file-name} -This function returns an abbreviated form of @var{filename}. It -applies the abbreviations specified in @code{directory-abbrev-alist} -(@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}), -then substitutes @samp{~} for the user's home directory if the -argument names a file in the home directory or one of its -subdirectories. If the home directory is a root directory, it is not -replaced with @samp{~}, because this does not make the result shorter -on many systems. - -You can use this function for directory names and for file names, -because it recognizes abbreviations even as part of the name. -@end defun - -@node File Name Expansion -@subsection Functions that Expand Filenames -@cindex expansion of file names - - @dfn{Expanding} a file name means converting a relative file name to -an absolute one. Since this is done relative to a default directory, -you must specify the default directory name as well as the file name -to be expanded. It also involves expanding abbreviations like -@file{~/} -@ifnottex -(@pxref{abbreviate-file-name}), -@end ifnottex -and eliminating redundancies like @file{./} and @file{@var{name}/../}. - -@defun expand-file-name filename &optional directory -This function converts @var{filename} to an absolute file name. If -@var{directory} is supplied, it is the default directory to start with -if @var{filename} is relative. (The value of @var{directory} should -itself be an absolute directory name or directory file name; it may -start with @samp{~}.) Otherwise, the current buffer's value of -@code{default-directory} is used. For example: - -@example -@group -(expand-file-name "foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@group -(expand-file-name "../foo") - @result{} "/xcssun/users/rms/foo" -@end group -@group -(expand-file-name "foo" "/usr/spool/") - @result{} "/usr/spool/foo" -@end group -@end example - -If the part of the combined file name before the first slash is -@samp{~}, it expands to the value of the @env{HOME} environment -variable (usually your home directory). If the part before the first -slash is @samp{~@var{user}} and if @var{user} is a valid login name, -it expands to @var{user}'s home directory. - -Filenames containing @samp{.} or @samp{..} are simplified to their -canonical form: - -@example -@group -(expand-file-name "bar/../foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@end example - -In some cases, a leading @samp{..} component can remain in the output: - -@example -@group -(expand-file-name "../home" "/") - @result{} "/../home" -@end group -@end example - -@noindent -This is for the sake of filesystems that have the concept of a -``superroot'' above the root directory @file{/}. On other filesystems, -@file{/../} is interpreted exactly the same as @file{/}. - -Note that @code{expand-file-name} does @emph{not} expand environment -variables; only @code{substitute-in-file-name} does that: - -@example -@group -(expand-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/lewis/$HOME/foo" -@end group -@end example - -Note also that @code{expand-file-name} does not follow symbolic links -at any level. This results in a difference between the way -@code{file-truename} and @code{expand-file-name} treat @samp{..}. -Assuming that @samp{/tmp/bar} is a symbolic link to the directory -@samp{/tmp/foo/bar} we get: - -@example -@group -(file-truename "/tmp/bar/../myfile") - @result{} "/tmp/foo/myfile" -@end group -@group -(expand-file-name "/tmp/bar/../myfile") - @result{} "/tmp/myfile" -@end group -@end example - -If you may need to follow symbolic links preceding @samp{..}, you -should make sure to call @code{file-truename} without prior direct or -indirect calls to @code{expand-file-name}. @xref{Truenames}. -@end defun - -@defvar default-directory -The value of this buffer-local variable is the default directory for the -current buffer. It should be an absolute directory name; it may start -with @samp{~}. This variable is buffer-local in every buffer. - -@code{expand-file-name} uses the default directory when its second -argument is @code{nil}. - -The value is always a string ending with a slash. - -@example -@group -default-directory - @result{} "/user/lewis/manual/" -@end group -@end example -@end defvar - -@defun substitute-in-file-name filename -@anchor{Definition of substitute-in-file-name} -This function replaces environment variable references in -@var{filename} with the environment variable values. Following -standard Unix shell syntax, @samp{$} is the prefix to substitute an -environment variable value. If the input contains @samp{$$}, that is -converted to @samp{$}; this gives the user a way to ``quote'' a -@samp{$}. - -The environment variable name is the series of alphanumeric characters -(including underscores) that follow the @samp{$}. If the character following -the @samp{$} is a @samp{@{}, then the variable name is everything up to the -matching @samp{@}}. - -Calling @code{substitute-in-file-name} on output produced by -@code{substitute-in-file-name} tends to give incorrect results. For -instance, use of @samp{$$} to quote a single @samp{$} won't work -properly, and @samp{$} in an environment variable's value could lead -to repeated substitution. Therefore, programs that call this function -and put the output where it will be passed to this function need to -double all @samp{$} characters to prevent subsequent incorrect -results. - -@c Wordy to avoid overfull hbox. --rjc 15mar92 -Here we assume that the environment variable @env{HOME}, which holds -the user's home directory name, has value @samp{/xcssun/users/rms}. - -@example -@group -(substitute-in-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/foo" -@end group -@end example - -After substitution, if a @samp{~} or a @samp{/} appears immediately -after another @samp{/}, the function discards everything before it (up -through the immediately preceding @samp{/}). - -@example -@group -(substitute-in-file-name "bar/~/foo") - @result{} "~/foo" -@end group -@group -(substitute-in-file-name "/usr/local/$HOME/foo") - @result{} "/xcssun/users/rms/foo" - ;; @r{@file{/usr/local/} has been discarded.} -@end group -@end example - -@end defun - -@node Unique File Names -@subsection Generating Unique File Names - - Some programs need to write temporary files. Here is the usual way to -construct a name for such a file: - -@example -(make-temp-file @var{name-of-application}) -@end example - -@noindent -The job of @code{make-temp-file} is to prevent two different users or -two different jobs from trying to use the exact same file name. - -@defun make-temp-file prefix &optional dir-flag suffix -This function creates a temporary file and returns its name. Emacs -creates the temporary file's name by adding to @var{prefix} some -random characters that are different in each Emacs job. The result is -guaranteed to be a newly created empty file. On MS-DOS, this function -can truncate the @var{string} prefix to fit into the 8+3 file-name -limits. If @var{prefix} is a relative file name, it is expanded -against @code{temporary-file-directory}. - -@example -@group -(make-temp-file "foo") - @result{} "/tmp/foo232J6v" -@end group -@end example - -When @code{make-temp-file} returns, the file has been created and is -empty. At that point, you should write the intended contents into the -file. - -If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an -empty directory instead of an empty file. It returns the file name, -not the directory name, of that directory. @xref{Directory Names}. - -If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at -the end of the file name. - -To prevent conflicts among different libraries running in the same -Emacs, each Lisp program that uses @code{make-temp-file} should have its -own @var{prefix}. The number added to the end of @var{prefix} -distinguishes between the same application running in different Emacs -jobs. Additional added characters permit a large number of distinct -names even in one Emacs job. -@end defun - - The default directory for temporary files is controlled by the -variable @code{temporary-file-directory}. This variable gives the user -a uniform way to specify the directory for all temporary files. Some -programs use @code{small-temporary-file-directory} instead, if that is -non-@code{nil}. To use it, you should expand the prefix against -the proper directory before calling @code{make-temp-file}. - -@defopt temporary-file-directory -@cindex @env{TMPDIR} environment variable -@cindex @env{TMP} environment variable -@cindex @env{TEMP} environment variable -This variable specifies the directory name for creating temporary files. -Its value should be a directory name (@pxref{Directory Names}), but it -is good for Lisp programs to cope if the value is a directory's file -name instead. Using the value as the second argument to -@code{expand-file-name} is a good way to achieve that. - -The default value is determined in a reasonable way for your operating -system; it is based on the @env{TMPDIR}, @env{TMP} and @env{TEMP} -environment variables, with a fall-back to a system-dependent name if -none of these variables is defined. - -Even if you do not use @code{make-temp-file} to create the temporary -file, you should still use this variable to decide which directory to -put the file in. However, if you expect the file to be small, you -should use @code{small-temporary-file-directory} first if that is -non-@code{nil}. -@end defopt - -@defopt small-temporary-file-directory -This variable specifies the directory name for -creating certain temporary files, which are likely to be small. - -If you want to write a temporary file which is likely to be small, you -should compute the directory like this: - -@example -(make-temp-file - (expand-file-name @var{prefix} - (or small-temporary-file-directory - temporary-file-directory))) -@end example -@end defopt - -@defun make-temp-name base-name -This function generates a string that can be used as a unique file -name. The name starts with @var{base-name}, and has several random -characters appended to it, which are different in each Emacs job. It -is like @code{make-temp-file} except that (i) it just constructs a -name, and does not create a file, and (ii) @var{base-name} should be -an absolute file name (on MS-DOS, this function can truncate -@var{base-name} to fit into the 8+3 file-name limits). - -@strong{Warning:} In most cases, you should not use this function; use -@code{make-temp-file} instead! This function is susceptible to a race -condition, between the @code{make-temp-name} call and the creation of -the file, which in some cases may cause a security hole. -@end defun - -@node File Name Completion -@subsection File Name Completion -@cindex file name completion subroutines -@cindex completion, file name - - This section describes low-level subroutines for completing a file -name. For higher level functions, see @ref{Reading File Names}. - -@defun file-name-all-completions partial-filename directory -This function returns a list of all possible completions for a file -whose name starts with @var{partial-filename} in directory -@var{directory}. The order of the completions is the order of the files -in the directory, which is unpredictable and conveys no useful -information. - -The argument @var{partial-filename} must be a file name containing no -directory part and no slash (or backslash on some systems). The current -buffer's default directory is prepended to @var{directory}, if -@var{directory} is not absolute. - -In the following example, suppose that @file{~rms/lewis} is the current -default directory, and has five files whose names begin with @samp{f}: -@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}. - -@example -@group -(file-name-all-completions "f" "") - @result{} ("foo" "file~" "file.c.~2~" - "file.c.~1~" "file.c") -@end group - -@group -(file-name-all-completions "fo" "") - @result{} ("foo") -@end group -@end example -@end defun - -@defun file-name-completion filename directory &optional predicate -This function completes the file name @var{filename} in directory -@var{directory}. It returns the longest prefix common to all file names -in directory @var{directory} that start with @var{filename}. If -@var{predicate} is non-@code{nil} then it ignores possible completions -that don't satisfy @var{predicate}, after calling that function -with one argument, the expanded absolute file name. - -If only one match exists and @var{filename} matches it exactly, the -function returns @code{t}. The function returns @code{nil} if directory -@var{directory} contains no name starting with @var{filename}. - -In the following example, suppose that the current default directory -has five files whose names begin with @samp{f}: @file{foo}, -@file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}. - -@example -@group -(file-name-completion "fi" "") - @result{} "file" -@end group - -@group -(file-name-completion "file.c.~1" "") - @result{} "file.c.~1~" -@end group - -@group -(file-name-completion "file.c.~1~" "") - @result{} t -@end group - -@group -(file-name-completion "file.c.~3" "") - @result{} nil -@end group -@end example -@end defun - -@defopt completion-ignored-extensions -@code{file-name-completion} usually ignores file names that end in any -string in this list. It does not ignore them when all the possible -completions end in one of these suffixes. This variable has no effect -on @code{file-name-all-completions}. - -A typical value might look like this: - -@example -@group -completion-ignored-extensions - @result{} (".o" ".elc" "~" ".dvi") -@end group -@end example - -If an element of @code{completion-ignored-extensions} ends in a slash -@samp{/}, it signals a directory. The elements which do @emph{not} end -in a slash will never match a directory; thus, the above value will not -filter out a directory named @file{foo.elc}. -@end defopt - -@node Standard File Names -@subsection Standard File Names - - Sometimes, an Emacs Lisp program needs to specify a standard file -name for a particular use---typically, to hold configuration data -specified by the current user. Usually, such files should be located -in the directory specified by @code{user-emacs-directory}, which is -@file{~/.emacs.d} by default (@pxref{Init File}). For example, abbrev -definitions are stored by default in @file{~/.emacs.d/abbrev_defs}. -The easiest way to specify such a file name is to use the function -@code{locate-user-emacs-file}. - -@defun locate-user-emacs-file base-name &optional old-name -This function returns an absolute file name for an Emacs-specific -configuration or data file. The argument @file{base-name} should be a -relative file name. The return value is the absolute name of a file -in the directory specified by @code{user-emacs-directory}; if that -directory does not exist, this function creates it. - -If the optional argument @var{old-name} is non-@code{nil}, it -specifies a file in the user's home directory, -@file{~/@var{old-name}}. If such a file exists, the return value is -the absolute name of that file, instead of the file specified by -@var{base-name}. This argument is intended to be used by Emacs -packages to provide backward compatibility. For instance, prior to -the introduction of @code{user-emacs-directory}, the abbrev file was -located in @file{~/.abbrev_defs}. Here is the definition of -@code{abbrev-file-name}: - -@example -(defcustom abbrev-file-name - (locate-user-emacs-file "abbrev_defs" ".abbrev_defs") - "Default name of file from which to read abbrevs." - @dots{} - :type 'file) -@end example -@end defun - - A lower-level function for standardizing file names, which -@code{locate-user-emacs-file} uses as a subroutine, is -@code{convert-standard-filename}. - -@defun convert-standard-filename filename -This function returns a file name based on @var{filename}, which fits -the conventions of the current operating system. - -On GNU and Unix systems, this simply returns @var{filename}. On other -operating systems, it may enforce system-specific file name -conventions; for example, on MS-DOS this function performs a variety -of changes to enforce MS-DOS file name limitations, including -converting any leading @samp{.} to @samp{_} and truncating to three -characters after the @samp{.}. - -The recommended way to use this function is to specify a name which -fits the conventions of GNU and Unix systems, and pass it to -@code{convert-standard-filename}. -@end defun - -@node Contents of Directories -@section Contents of Directories -@cindex directory-oriented functions -@cindex file names in directory - - A directory is a kind of file that contains other files entered under -various names. Directories are a feature of the file system. - - Emacs can list the names of the files in a directory as a Lisp list, -or display the names in a buffer using the @code{ls} shell command. In -the latter case, it can optionally display information about each file, -depending on the options passed to the @code{ls} command. - -@defun directory-files directory &optional full-name match-regexp nosort -This function returns a list of the names of the files in the directory -@var{directory}. By default, the list is in alphabetical order. - -If @var{full-name} is non-@code{nil}, the function returns the files' -absolute file names. Otherwise, it returns the names relative to -the specified directory. - -If @var{match-regexp} is non-@code{nil}, this function returns only -those file names that contain a match for that regular expression---the -other file names are excluded from the list. On case-insensitive -filesystems, the regular expression matching is case-insensitive. - -@c Emacs 19 feature -If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort -the list, so you get the file names in no particular order. Use this if -you want the utmost possible speed and don't care what order the files -are processed in. If the order of processing is visible to the user, -then the user will probably be happier if you do sort the names. - -@example -@group -(directory-files "~lewis") - @result{} ("#foo#" "#foo.el#" "." ".." - "dired-mods.el" "files.texi" - "files.texi.~1~") -@end group -@end example - -An error is signaled if @var{directory} is not the name of a directory -that can be read. -@end defun - -@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format -This is similar to @code{directory-files} in deciding which files -to report on and how to report their names. However, instead -of returning a list of file names, it returns for each file a -list @code{(@var{filename} . @var{attributes})}, where @var{attributes} -is what @code{file-attributes} would return for that file. -The optional argument @var{id-format} has the same meaning as the -corresponding argument to @code{file-attributes} (@pxref{Definition -of file-attributes}). -@end defun - -@defun file-expand-wildcards pattern &optional full -This function expands the wildcard pattern @var{pattern}, returning -a list of file names that match it. - -If @var{pattern} is written as an absolute file name, -the values are absolute also. - -If @var{pattern} is written as a relative file name, it is interpreted -relative to the current default directory. The file names returned are -normally also relative to the current default directory. However, if -@var{full} is non-@code{nil}, they are absolute. -@end defun - -@defun insert-directory file switches &optional wildcard full-directory-p -This function inserts (in the current buffer) a directory listing for -directory @var{file}, formatted with @code{ls} according to -@var{switches}. It leaves point after the inserted text. -@var{switches} may be a string of options, or a list of strings -representing individual options. - -The argument @var{file} may be either a directory name or a file -specification including wildcard characters. If @var{wildcard} is -non-@code{nil}, that means treat @var{file} as a file specification with -wildcards. - -If @var{full-directory-p} is non-@code{nil}, that means the directory -listing is expected to show the full contents of a directory. You -should specify @code{t} when @var{file} is a directory and switches do -not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to -describe a directory itself as a file, rather than showing its -contents.) - -On most systems, this function works by running a directory listing -program whose name is in the variable @code{insert-directory-program}. -If @var{wildcard} is non-@code{nil}, it also runs the shell specified by -@code{shell-file-name}, to expand the wildcards. - -MS-DOS and MS-Windows systems usually lack the standard Unix program -@code{ls}, so this function emulates the standard Unix program @code{ls} -with Lisp code. - -As a technical detail, when @var{switches} contains the long -@samp{--dired} option, @code{insert-directory} treats it specially, -for the sake of dired. However, the normally equivalent short -@samp{-D} option is just passed on to @code{insert-directory-program}, -as any other option. -@end defun - -@defvar insert-directory-program -This variable's value is the program to run to generate a directory listing -for the function @code{insert-directory}. It is ignored on systems -which generate the listing with Lisp code. -@end defvar - -@node Create/Delete Dirs -@section Creating, Copying and Deleting Directories -@cindex creating, copying and deleting directories -@c Emacs 19 features - - Most Emacs Lisp file-manipulation functions get errors when used on -files that are directories. For example, you cannot delete a directory -with @code{delete-file}. These special functions exist to create and -delete directories. - -@findex mkdir -@deffn Command make-directory dirname &optional parents -This command creates a directory named @var{dirname}. If -@var{parents} is non-@code{nil}, as is always the case in an -interactive call, that means to create the parent directories first, -if they don't already exist. - -@code{mkdir} is an alias for this. -@end deffn - -@deffn Command copy-directory dirname newname &optional keep-time parents copy-contents -This command copies the directory named @var{dirname} to -@var{newname}. If @var{newname} names an existing directory, -@var{dirname} will be copied to a subdirectory there. - -It always sets the file modes of the copied files to match the -corresponding original file. - -The third argument @var{keep-time} non-@code{nil} means to preserve the -modification time of the copied files. A prefix arg makes -@var{keep-time} non-@code{nil}. - -The fourth argument @var{parents} says whether to -create parent directories if they don't exist. Interactively, -this happens by default. - -The fifth argument @var{copy-contents}, if non-@code{nil}, means to -copy the contents of @var{dirname} directly into @var{newname} if the -latter is an existing directory, instead of copying @var{dirname} into -it as a subdirectory. -@end deffn - -@cindex trash -@vindex delete-by-moving-to-trash -@deffn Command delete-directory dirname &optional recursive trash -This command deletes the directory named @var{dirname}. The function -@code{delete-file} does not work for files that are directories; you -must use @code{delete-directory} for them. If @var{recursive} is -@code{nil}, and the directory contains any files, -@code{delete-directory} signals an error. - -@code{delete-directory} only follows symbolic links at the level of -parent directories. - -If the optional argument @var{trash} is non-@code{nil} and the -variable @code{delete-by-moving-to-trash} is non-@code{nil}, this -command moves the file into the system Trash instead of deleting it. -@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU -Emacs Manual}. When called interactively, @var{trash} is @code{t} if -no prefix argument is given, and @code{nil} otherwise. -@end deffn - -@node Magic File Names -@section Making Certain File Names ``Magic'' -@cindex magic file names - - You can implement special handling for certain file names. This is -called making those names @dfn{magic}. The principal use for this -feature is in implementing access to remote files (@pxref{Remote Files,, -Remote Files, emacs, The GNU Emacs Manual}). - - To define a kind of magic file name, you must supply a regular -expression to define the class of names (all those that match the -regular expression), plus a handler that implements all the primitive -Emacs file operations for file names that match. - -@cindex file handler -@vindex file-name-handler-alist - The variable @code{file-name-handler-alist} holds a list of handlers, -together with regular expressions that determine when to apply each -handler. Each element has this form: - -@example -(@var{regexp} . @var{handler}) -@end example - -@noindent -All the Emacs primitives for file access and file name transformation -check the given file name against @code{file-name-handler-alist}. If -the file name matches @var{regexp}, the primitives handle that file by -calling @var{handler}. - - The first argument given to @var{handler} is the name of the -primitive, as a symbol; the remaining arguments are the arguments that -were passed to that primitive. (The first of these arguments is most -often the file name itself.) For example, if you do this: - -@example -(file-exists-p @var{filename}) -@end example - -@noindent -and @var{filename} has handler @var{handler}, then @var{handler} is -called like this: - -@example -(funcall @var{handler} 'file-exists-p @var{filename}) -@end example - - When a function takes two or more arguments that must be file names, -it checks each of those names for a handler. For example, if you do -this: - -@example -(expand-file-name @var{filename} @var{dirname}) -@end example - -@noindent -then it checks for a handler for @var{filename} and then for a handler -for @var{dirname}. In either case, the @var{handler} is called like -this: - -@example -(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname}) -@end example - -@noindent -The @var{handler} then needs to figure out whether to handle -@var{filename} or @var{dirname}. - - If the specified file name matches more than one handler, the one -whose match starts last in the file name gets precedence. This rule -is chosen so that handlers for jobs such as uncompression are handled -first, before handlers for jobs such as remote file access. - - Here are the operations that a magic file name handler gets to handle: - -@ifnottex -@noindent -@code{access-file}, @code{add-name-to-file}, -@code{byte-compiler-base-file-name},@* -@code{copy-directory}, @code{copy-file}, -@code{delete-directory}, @code{delete-file}, -@code{diff-latest-backup-file}, -@code{directory-file-name}, -@code{directory-files}, -@code{directory-files-and-attributes}, -@code{dired-compress-file}, @code{dired-uncache},@* -@code{expand-file-name}, -@code{file-accessible-directory-p}, -@code{file-acl}, -@code{file-attributes}, -@code{file-directory-p}, -@code{file-equal-p}, -@code{file-executable-p}, @code{file-exists-p}, -@code{file-in-directory-p}, -@code{file-local-copy}, -@code{file-modes}, @code{file-name-all-completions}, -@code{file-name-as-directory}, -@code{file-name-completion}, -@code{file-name-directory}, -@code{file-name-nondirectory}, -@code{file-name-sans-versions}, @code{file-newer-than-file-p}, -@code{file-notify-add-watch}, @code{file-notify-rm-watch}, -@code{file-ownership-preserved-p}, -@code{file-readable-p}, @code{file-regular-p}, -@code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, -@code{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect},@* -@code{get-file-buffer}, -@code{insert-directory}, -@code{insert-file-contents},@* -@code{load}, -@code{make-auto-save-file-name}, -@code{make-directory}, -@code{make-directory-internal}, -@code{make-symbolic-link},@* -@code{process-file}, -@code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, -@code{set-file-selinux-context}, @code{set-file-times}, -@code{set-visited-file-modtime}, @code{shell-command}, -@code{start-file-process}, -@code{substitute-in-file-name},@* -@code{unhandled-file-name-directory}, -@code{vc-registered}, -@code{verify-visited-file-modtime},@* -@code{write-region}. -@end ifnottex -@iftex -@noindent -@flushleft -@code{access-file}, @code{add-name-to-file}, -@code{byte-com@discretionary{}{}{}piler-base-file-name}, -@code{copy-directory}, @code{copy-file}, -@code{delete-directory}, @code{delete-file}, -@code{diff-latest-backup-file}, -@code{directory-file-name}, -@code{directory-files}, -@code{directory-files-and-at@discretionary{}{}{}tributes}, -@code{dired-compress-file}, @code{dired-uncache}, -@code{expand-file-name}, -@code{file-accessible-direc@discretionary{}{}{}tory-p}, -@code{file-acl}, -@code{file-attributes}, -@code{file-direc@discretionary{}{}{}tory-p}, -@code{file-equal-p}, -@code{file-executable-p}, @code{file-exists-p}, -@code{file-in-directory-p}, -@code{file-local-copy}, -@code{file-modes}, @code{file-name-all-completions}, -@code{file-name-as-directory}, -@code{file-name-completion}, -@code{file-name-directory}, -@code{file-name-nondirec@discretionary{}{}{}tory}, -@code{file-name-sans-versions}, @code{file-newer-than-file-p}, -@code{file-notify-add-watch}, @code{file-notify-rm-watch}, -@code{file-ownership-pre@discretionary{}{}{}served-p}, -@code{file-readable-p}, @code{file-regular-p}, -@code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, -@code{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect}, -@code{get-file-buffer}, -@code{insert-directory}, -@code{insert-file-contents}, -@code{load}, -@code{make-auto-save-file-name}, -@code{make-direc@discretionary{}{}{}tory}, -@code{make-direc@discretionary{}{}{}tory-internal}, -@code{make-symbolic-link}, -@code{process-file}, -@code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, -@code{set-file-selinux-context}, @code{set-file-times}, -@code{set-visited-file-modtime}, @code{shell-command}, -@code{start-file-process}, -@code{substitute-in-file-name}, -@code{unhandled-file-name-directory}, -@code{vc-regis@discretionary{}{}{}tered}, -@code{verify-visited-file-modtime}, -@code{write-region}. -@end flushleft -@end iftex - - Handlers for @code{insert-file-contents} typically need to clear the -buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the -@var{visit} argument is non-@code{nil}. This also has the effect of -unlocking the buffer if it is locked. - - The handler function must handle all of the above operations, and -possibly others to be added in the future. It need not implement all -these operations itself---when it has nothing special to do for a -certain operation, it can reinvoke the primitive, to handle the -operation ``in the usual way''. It should always reinvoke the primitive -for an operation it does not recognize. Here's one way to do this: - -@smallexample -(defun my-file-handler (operation &rest args) - ;; @r{First check for the specific operations} - ;; @r{that we have special handling for.} - (cond ((eq operation 'insert-file-contents) @dots{}) - ((eq operation 'write-region) @dots{}) - @dots{} - ;; @r{Handle any operation we don't know about.} - (t (let ((inhibit-file-name-handlers - (cons 'my-file-handler - (and (eq inhibit-file-name-operation operation) - inhibit-file-name-handlers))) - (inhibit-file-name-operation operation)) - (apply operation args))))) -@end smallexample - - When a handler function decides to call the ordinary Emacs primitive for -the operation at hand, it needs to prevent the primitive from calling -the same handler once again, thus leading to an infinite recursion. The -example above shows how to do this, with the variables -@code{inhibit-file-name-handlers} and -@code{inhibit-file-name-operation}. Be careful to use them exactly as -shown above; the details are crucial for proper behavior in the case of -multiple handlers, and for operations that have two file names that may -each have handlers. - -@kindex safe-magic (@r{property}) - Handlers that don't really do anything special for actual access to the -file---such as the ones that implement completion of host names for -remote file names---should have a non-@code{nil} @code{safe-magic} -property. For instance, Emacs normally ``protects'' directory names -it finds in @code{PATH} from becoming magic, if they look like magic -file names, by prefixing them with @samp{/:}. But if the handler that -would be used for them has a non-@code{nil} @code{safe-magic} -property, the @samp{/:} is not added. - -@kindex operations (@r{property}) - A file name handler can have an @code{operations} property to -declare which operations it handles in a nontrivial way. If this -property has a non-@code{nil} value, it should be a list of -operations; then only those operations will call the handler. This -avoids inefficiency, but its main purpose is for autoloaded handler -functions, so that they won't be loaded except when they have real -work to do. - - Simply deferring all operations to the usual primitives does not -work. For instance, if the file name handler applies to -@code{file-exists-p}, then it must handle @code{load} itself, because -the usual @code{load} code won't work properly in that case. However, -if the handler uses the @code{operations} property to say it doesn't -handle @code{file-exists-p}, then it need not handle @code{load} -nontrivially. - -@defvar inhibit-file-name-handlers -This variable holds a list of handlers whose use is presently inhibited -for a certain operation. -@end defvar - -@defvar inhibit-file-name-operation -The operation for which certain handlers are presently inhibited. -@end defvar - -@defun find-file-name-handler file operation -This function returns the handler function for file name @var{file}, -or @code{nil} if there is none. The argument @var{operation} should -be the operation to be performed on the file---the value you will pass -to the handler as its first argument when you call it. If -@var{operation} equals @code{inhibit-file-name-operation}, or if it is -not found in the @code{operations} property of the handler, this -function returns @code{nil}. -@end defun - -@defun file-local-copy filename -This function copies file @var{filename} to an ordinary non-magic file -on the local machine, if it isn't on the local machine already. Magic -file names should handle the @code{file-local-copy} operation if they -refer to files on other machines. A magic file name that is used for -other purposes than remote file access should not handle -@code{file-local-copy}; then this function will treat the file as -local. - -If @var{filename} is local, whether magic or not, this function does -nothing and returns @code{nil}. Otherwise it returns the file name -of the local copy file. -@end defun - -@defun file-remote-p filename &optional identification connected -This function tests whether @var{filename} is a remote file. If -@var{filename} is local (not remote), the return value is @code{nil}. -If @var{filename} is indeed remote, the return value is a string that -identifies the remote system. - -This identifier string can include a host name and a user name, as -well as characters designating the method used to access the remote -system. For example, the remote identifier string for the filename -@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}. - -If @code{file-remote-p} returns the same identifier for two different -filenames, that means they are stored on the same file system and can -be accessed locally with respect to each other. This means, for -example, that it is possible to start a remote process accessing both -files at the same time. Implementers of file handlers need to ensure -this principle is valid. - -@var{identification} specifies which part of the identifier shall be -returned as string. @var{identification} can be the symbol -@code{method}, @code{user} or @code{host}; any other value is handled -like @code{nil} and means to return the complete identifier string. -In the example above, the remote @code{user} identifier string would -be @code{root}. - -If @var{connected} is non-@code{nil}, this function returns @code{nil} -even if @var{filename} is remote, if Emacs has no network connection -to its host. This is useful when you want to avoid the delay of -making connections when they don't exist. -@end defun - -@defun unhandled-file-name-directory filename -This function returns the name of a directory that is not magic. It -uses the directory part of @var{filename} if that is not magic. For a -magic file name, it invokes the file name handler, which therefore -decides what value to return. If @var{filename} is not accessible -from a local process, then the file name handler should indicate it by -returning @code{nil}. - -This is useful for running a subprocess; every subprocess must have a -non-magic directory to serve as its current directory, and this function -is a good way to come up with one. -@end defun - -@defopt remote-file-name-inhibit-cache -The attributes of remote files can be cached for better performance. If -they are changed outside of Emacs's control, the cached values become -invalid, and must be reread. - -When this variable is set to @code{nil}, cached values are never -expired. Use this setting with caution, only if you are sure nothing -other than Emacs ever changes the remote files. If it is set to -@code{t}, cached values are never used. This is the safest value, but -could result in performance degradation. - -A compromise is to set it to a positive number. This means that -cached values are used for that amount of seconds since they were -cached. If a remote file is checked regularly, it might be a good -idea to let-bind this variable to a value less than the time period -between consecutive checks. For example: - -@example -(defun display-time-file-nonempty-p (file) - (let ((remote-file-name-inhibit-cache - (- display-time-interval 5))) - (and (file-exists-p file) - (< 0 (nth 7 (file-attributes - (file-chase-links file))))))) -@end example -@end defopt - -@node Format Conversion -@section File Format Conversion - -@cindex file format conversion -@cindex encoding file formats -@cindex decoding file formats -@cindex text properties in files -@cindex saving text properties - Emacs performs several steps to convert the data in a buffer (text, -text properties, and possibly other information) to and from a -representation suitable for storing into a file. This section describes -the fundamental functions that perform this @dfn{format conversion}, -namely @code{insert-file-contents} for reading a file into a buffer, -and @code{write-region} for writing a buffer into a file. - -@menu -* Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}. -* Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}. -* Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion. -@end menu - -@node Format Conversion Overview -@subsection Overview -@noindent -The function @code{insert-file-contents}: - -@itemize -@item initially, inserts bytes from the file into the buffer; -@item decodes bytes to characters as appropriate; -@item processes formats as defined by entries in @code{format-alist}; and -@item calls functions in @code{after-insert-file-functions}. -@end itemize - -@noindent -The function @code{write-region}: - -@itemize -@item initially, calls functions in @code{write-region-annotate-functions}; -@item processes formats as defined by entries in @code{format-alist}; -@item encodes characters to bytes as appropriate; and -@item modifies the file with the bytes. -@end itemize - - This shows the symmetry of the lowest-level operations; reading and -writing handle things in opposite order. The rest of this section -describes the two facilities surrounding the three variables named -above, as well as some related functions. @ref{Coding Systems}, for -details on character encoding and decoding. - -@node Format Conversion Round-Trip -@subsection Round-Trip Specification - - The most general of the two facilities is controlled by the variable -@code{format-alist}, a list of @dfn{file format} specifications, which -describe textual representations used in files for the data in an Emacs -buffer. The descriptions for reading and writing are paired, which is -why we call this ``round-trip'' specification -(@pxref{Format Conversion Piecemeal}, for non-paired specification). - -@defvar format-alist -This list contains one format definition for each defined file format. -Each format definition is a list of this form: - -@example -(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve}) -@end example -@end defvar - -@cindex format definition -@noindent -Here is what the elements in a format definition mean: - -@table @var -@item name -The name of this format. - -@item doc-string -A documentation string for the format. - -@item regexp -A regular expression which is used to recognize files represented in -this format. If @code{nil}, the format is never applied automatically. - -@item from-fn -A shell command or function to decode data in this format (to convert -file data into the usual Emacs data representation). - -A shell command is represented as a string; Emacs runs the command as a -filter to perform the conversion. - -If @var{from-fn} is a function, it is called with two arguments, @var{begin} -and @var{end}, which specify the part of the buffer it should convert. -It should convert the text by editing it in place. Since this can -change the length of the text, @var{from-fn} should return the modified -end position. - -One responsibility of @var{from-fn} is to make sure that the beginning -of the file no longer matches @var{regexp}. Otherwise it is likely to -get called again. - -@item to-fn -A shell command or function to encode data in this format---that is, to -convert the usual Emacs data representation into this format. - -If @var{to-fn} is a string, it is a shell command; Emacs runs the -command as a filter to perform the conversion. - -If @var{to-fn} is a function, it is called with three arguments: -@var{begin} and @var{end}, which specify the part of the buffer it -should convert, and @var{buffer}, which specifies which buffer. There -are two ways it can do the conversion: - -@itemize @bullet -@item -By editing the buffer in place. In this case, @var{to-fn} should -return the end-position of the range of text, as modified. - -@item -By returning a list of annotations. This is a list of elements of the -form @code{(@var{position} . @var{string})}, where @var{position} is an -integer specifying the relative position in the text to be written, and -@var{string} is the annotation to add there. The list must be sorted in -order of position when @var{to-fn} returns it. - -When @code{write-region} actually writes the text from the buffer to the -file, it intermixes the specified annotations at the corresponding -positions. All this takes place without modifying the buffer. -@end itemize - -@item modify -A flag, @code{t} if the encoding function modifies the buffer, and -@code{nil} if it works by returning a list of annotations. - -@item mode-fn -A minor-mode function to call after visiting a file converted from this -format. The function is called with one argument, the integer 1; -that tells a minor-mode function to enable the mode. - -@item preserve -A flag, @code{t} if @code{format-write-file} should not remove this format -from @code{buffer-file-format}. -@end table - -The function @code{insert-file-contents} automatically recognizes file -formats when it reads the specified file. It checks the text of the -beginning of the file against the regular expressions of the format -definitions, and if it finds a match, it calls the decoding function for -that format. Then it checks all the known formats over again. -It keeps checking them until none of them is applicable. - -Visiting a file, with @code{find-file-noselect} or the commands that use -it, performs conversion likewise (because it calls -@code{insert-file-contents}); it also calls the mode function for each -format that it decodes. It stores a list of the format names in the -buffer-local variable @code{buffer-file-format}. - -@defvar buffer-file-format -This variable states the format of the visited file. More precisely, -this is a list of the file format names that were decoded in the course -of visiting the current buffer's file. It is always buffer-local in all -buffers. -@end defvar - -When @code{write-region} writes data into a file, it first calls the -encoding functions for the formats listed in @code{buffer-file-format}, -in the order of appearance in the list. - -@deffn Command format-write-file file format &optional confirm -This command writes the current buffer contents into the file @var{file} -in a format based on @var{format}, which is a list of format names. It -constructs the actual format starting from @var{format}, then appending -any elements from the value of @code{buffer-file-format} with a -non-@code{nil} @var{preserve} flag (see above), if they are not already -present in @var{format}. It then updates @code{buffer-file-format} with -this format, making it the default for future saves. Except for the -@var{format} argument, this command is similar to @code{write-file}. In -particular, @var{confirm} has the same meaning and interactive treatment -as the corresponding argument to @code{write-file}. @xref{Definition of -write-file}. -@end deffn - -@deffn Command format-find-file file format -This command finds the file @var{file}, converting it according to -format @var{format}. It also makes @var{format} the default if the -buffer is saved later. - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end deffn - -@deffn Command format-insert-file file format &optional beg end -This command inserts the contents of file @var{file}, converting it -according to format @var{format}. If @var{beg} and @var{end} are -non-@code{nil}, they specify which part of the file to read, as in -@code{insert-file-contents} (@pxref{Reading from Files}). - -The return value is like what @code{insert-file-contents} returns: a -list of the absolute file name and the length of the data inserted -(after conversion). - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end deffn - -@defvar buffer-auto-save-file-format -This variable specifies the format to use for auto-saving. Its value is -a list of format names, just like the value of -@code{buffer-file-format}; however, it is used instead of -@code{buffer-file-format} for writing auto-save files. If the value -is @code{t}, the default, auto-saving uses the same format as a -regular save in the same buffer. This variable is always buffer-local -in all buffers. -@end defvar - -@node Format Conversion Piecemeal -@subsection Piecemeal Specification - - In contrast to the round-trip specification described in the previous -subsection (@pxref{Format Conversion Round-Trip}), you can use the variables -@code{after-insert-file-functions} and @code{write-region-annotate-functions} -to separately control the respective reading and writing conversions. - - Conversion starts with one representation and produces another -representation. When there is only one conversion to do, there is no -conflict about what to start with. However, when there are multiple -conversions involved, conflict may arise when two conversions need to -start with the same data. - - This situation is best understood in the context of converting text -properties during @code{write-region}. For example, the character at -position 42 in a buffer is @samp{X} with a text property @code{foo}. If -the conversion for @code{foo} is done by inserting into the buffer, say, -@samp{FOO:}, then that changes the character at position 42 from -@samp{X} to @samp{F}. The next conversion will start with the wrong -data straight away. - - To avoid conflict, cooperative conversions do not modify the buffer, -but instead specify @dfn{annotations}, a list of elements of the form -@code{(@var{position} . @var{string})}, sorted in order of increasing -@var{position}. - - If there is more than one conversion, @code{write-region} merges their -annotations destructively into one sorted list. Later, when the text -from the buffer is actually written to the file, it intermixes the -specified annotations at the corresponding positions. All this takes -place without modifying the buffer. - -@c ??? What about ``overriding'' conversions like those allowed -@c ??? for `write-region-annotate-functions', below? --ttn - - In contrast, when reading, the annotations intermixed with the text -are handled immediately. @code{insert-file-contents} sets point to -the beginning of some text to be converted, then calls the conversion -functions with the length of that text. These functions should always -return with point at the beginning of the inserted text. This -approach makes sense for reading because annotations removed by the -first converter can't be mistakenly processed by a later converter. -Each conversion function should scan for the annotations it -recognizes, remove the annotation, modify the buffer text (to set a -text property, for example), and return the updated length of the -text, as it stands after those changes. The value returned by one -function becomes the argument to the next function. - -@defvar write-region-annotate-functions -A list of functions for @code{write-region} to call. Each function in -the list is called with two arguments: the start and end of the region -to be written. These functions should not alter the contents of the -buffer. Instead, they should return annotations. - -As a special case, a function may return with a different buffer -current. Emacs takes this to mean that the current buffer contains -altered text to be output. It therefore changes the @var{start} and -@var{end} arguments of the @code{write-region} call, giving them the -values of @code{point-min} and @code{point-max} in the new buffer, -respectively. It also discards all previous annotations, because they -should have been dealt with by this function. -@end defvar - -@defvar write-region-post-annotation-function -The value of this variable, if non-@code{nil}, should be a function. -This function is called, with no arguments, after @code{write-region} -has completed. - -If any function in @code{write-region-annotate-functions} returns with -a different buffer current, Emacs calls -@code{write-region-post-annotation-function} more than once. Emacs -calls it with the last buffer that was current, and again with the -buffer before that, and so on back to the original buffer. - -Thus, a function in @code{write-region-annotate-functions} can create -a buffer, give this variable the local value of @code{kill-buffer} in -that buffer, set up the buffer with altered text, and make the buffer -current. The buffer will be killed after @code{write-region} is done. -@end defvar - -@defvar after-insert-file-functions -Each function in this list is called by @code{insert-file-contents} -with one argument, the number of characters inserted, and with point -at the beginning of the inserted text. Each function should leave -point unchanged, and return the new character count describing the -inserted text as modified by the function. -@c ??? The docstring mentions a handler from `file-name-handler-alist' -@c "intercepting" `insert-file-contents'. Hmmm. --ttn -@end defvar - - We invite users to write Lisp programs to store and retrieve text -properties in files, using these hooks, and thus to experiment with -various data formats and find good ones. Eventually we hope users -will produce good, general extensions we can install in Emacs. - - We suggest not trying to handle arbitrary Lisp objects as text property -names or values---because a program that general is probably difficult -to write, and slow. Instead, choose a set of possible data types that -are reasonably flexible, and not too hard to encode. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi deleted file mode 100644 index d5617ed3cfd..00000000000 --- a/doc/lispref/frames.texi +++ /dev/null @@ -1,2670 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Frames -@chapter Frames -@cindex frame - - A @dfn{frame} is a screen object that contains one or more Emacs -windows (@pxref{Windows}). It is the kind of object called a -``window'' in the terminology of graphical environments; but we can't -call it a ``window'' here, because Emacs uses that word in a different -way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that -represents a frame on the screen. @xref{Frame Type}. - - A frame initially contains a single main window and/or a minibuffer -window; you can subdivide the main window vertically or horizontally -into smaller windows. @xref{Splitting Windows}. - -@cindex terminal - A @dfn{terminal} is a display device capable of displaying one or -more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp -object that represents a terminal. @xref{Terminal Type}. - -@cindex text terminal -@cindex graphical terminal -@cindex graphical display - There are two classes of terminals: @dfn{text terminals} and -@dfn{graphical terminals}. Text terminals are non-graphics-capable -displays, including @command{xterm} and other terminal emulators. On -a text terminal, each Emacs frame occupies the terminal's entire -screen; although you can create additional frames and switch between -them, the terminal only shows one frame at a time. Graphical -terminals, on the other hand, are managed by graphical display systems -such as the X Window System, which allow Emacs to show multiple frames -simultaneously on the same display. - - On GNU and Unix systems, you can create additional frames on any -available terminal, within a single Emacs session, regardless of -whether Emacs was started on a text or graphical terminal. Emacs can -display on both graphical and text terminals simultaneously. This -comes in handy, for instance, when you connect to the same session -from several remote locations. @xref{Multiple Terminals}. - -@defun framep object -This predicate returns a non-@code{nil} value if @var{object} is a -frame, and @code{nil} otherwise. For a frame, the value indicates which -kind of display the frame uses: - -@table @code -@item t -The frame is displayed on a text terminal. -@item x -The frame is displayed on an X graphical terminal. -@item w32 -The frame is displayed on a MS-Windows graphical terminal. -@item ns -The frame is displayed on a GNUstep or Macintosh Cocoa graphical -terminal. -@item pc -The frame is displayed on an MS-DOS terminal. -@end table -@end defun - -@defun frame-terminal &optional frame -This function returns the terminal object that displays @var{frame}. -If @var{frame} is @code{nil} or unspecified, it defaults to the -selected frame. -@end defun - -@defun terminal-live-p object -This predicate returns a non-@code{nil} value if @var{object} is a -terminal that is live (i.e., not deleted), and @code{nil} otherwise. -For live terminals, the return value indicates what kind of frames are -displayed on that terminal; the list of possible values is the same as -for @code{framep} above. -@end defun - -@menu -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections:: Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. -@end menu - -@node Creating Frames -@section Creating Frames - -To create a new frame, call the function @code{make-frame}. - -@deffn Command make-frame &optional alist -This function creates and returns a new frame, displaying the current -buffer. - -The @var{alist} argument is an alist that specifies frame parameters -for the new frame. @xref{Frame Parameters}. If you specify the -@code{terminal} parameter in @var{alist}, the new frame is created on -that terminal. Otherwise, if you specify the @code{window-system} -frame parameter in @var{alist}, that determines whether the frame -should be displayed on a text terminal or a graphical terminal. -@xref{Window Systems}. If neither is specified, the new frame is -created in the same terminal as the selected frame. - -Any parameters not mentioned in @var{alist} default to the values in -the alist @code{default-frame-alist} (@pxref{Initial Parameters}); -parameters not specified there default from the X resources or its -equivalent on your operating system (@pxref{X Resources,, X Resources, -emacs, The GNU Emacs Manual}). After the frame is created, Emacs -applies any parameters listed in @code{frame-inherited-parameters} -(see below) and not present in the argument, taking the values from -the frame that was selected when @code{make-frame} was called. - -Note that on multi-monitor displays (@pxref{Multiple Terminals}), the -window manager might position the frame differently than specified by -the positional parameters in @var{alist} (@pxref{Position -Parameters}). For example, some window managers have a policy of -displaying the frame on the monitor that contains the largest part of -the window (a.k.a.@: the @dfn{dominating} monitor). - -This function itself does not make the new frame the selected frame. -@xref{Input Focus}. The previously selected frame remains selected. -On graphical terminals, however, the windowing system may select the -new frame for its own reasons. -@end deffn - -@defvar before-make-frame-hook -A normal hook run by @code{make-frame} before it creates the frame. -@end defvar - -@defvar after-make-frame-functions -An abnormal hook run by @code{make-frame} after it creates the frame. -Each function in @code{after-make-frame-functions} receives one argument, the -frame just created. -@end defvar - -@defvar frame-inherited-parameters -This variable specifies the list of frame parameters that a newly -created frame inherits from the currently selected frame. For each -parameter (a symbol) that is an element in the list and is not present -in the argument to @code{make-frame}, the function sets the value of -that parameter in the created frame to its value in the selected -frame. -@end defvar - -@node Multiple Terminals -@section Multiple Terminals -@cindex multiple terminals -@cindex multi-tty -@cindex multiple X displays -@cindex displays, multiple - - Emacs represents each terminal as a @dfn{terminal object} data type -(@pxref{Terminal Type}). On GNU and Unix systems, Emacs can use -multiple terminals simultaneously in each session. On other systems, -it can only use a single terminal. Each terminal object has the -following attributes: - -@itemize @bullet -@item -The name of the device used by the terminal (e.g., @samp{:0.0} or -@file{/dev/tty}). - -@item -The terminal and keyboard coding systems used on the terminal. -@xref{Terminal I/O Encoding}. - -@item -The kind of display associated with the terminal. This is the symbol -returned by the function @code{terminal-live-p} (i.e., @code{x}, -@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}. - -@item -A list of terminal parameters. @xref{Terminal Parameters}. -@end itemize - - There is no primitive for creating terminal objects. Emacs creates -them as needed, such as when you call @code{make-frame-on-display} -(described below). - -@defun terminal-name &optional terminal -This function returns the file name of the device used by -@var{terminal}. If @var{terminal} is omitted or @code{nil}, it -defaults to the selected frame's terminal. @var{terminal} can also be -a frame, meaning that frame's terminal. -@end defun - -@defun terminal-list -This function returns a list of all live terminal objects. -@end defun - -@defun get-device-terminal device -This function returns a terminal whose device name is given by -@var{device}. If @var{device} is a string, it can be either the file -name of a terminal device, or the name of an X display of the form -@samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a -frame, this function returns that frame's terminal; @code{nil} means -the selected frame. Finally, if @var{device} is a terminal object -that represents a live terminal, that terminal is returned. The -function signals an error if its argument is none of the above. -@end defun - -@defun delete-terminal &optional terminal force -This function deletes all frames on @var{terminal} and frees the -resources used by it. It runs the abnormal hook -@code{delete-terminal-functions}, passing @var{terminal} as the -argument to each function. - -If @var{terminal} is omitted or @code{nil}, it defaults to the -selected frame's terminal. @var{terminal} can also be a frame, -meaning that frame's terminal. - -Normally, this function signals an error if you attempt to delete the -sole active terminal, but if @var{force} is non-@code{nil}, you are -allowed to do so. Emacs automatically calls this function when the -last frame on a terminal is deleted (@pxref{Deleting Frames}). -@end defun - -@defvar delete-terminal-functions -An abnormal hook run by @code{delete-terminal}. Each function -receives one argument, the @var{terminal} argument passed to -@code{delete-terminal}. Due to technical details, the functions may -be called either just before the terminal is deleted, or just -afterwards. -@end defvar - -@cindex terminal-local variables - A few Lisp variables are @dfn{terminal-local}; that is, they have a -separate binding for each terminal. The binding in effect at any time -is the one for the terminal that the currently selected frame belongs -to. These variables include @code{default-minibuffer-frame}, -@code{defining-kbd-macro}, @code{last-kbd-macro}, and -@code{system-key-alist}. They are always terminal-local, and can -never be buffer-local (@pxref{Buffer-Local Variables}). - - On GNU and Unix systems, each X display is a separate graphical -terminal. When Emacs is started from within the X window system, it -uses the X display specified by the @env{DISPLAY} environment -variable, or by the @samp{--display} option (@pxref{Initial Options,,, -emacs, The GNU Emacs Manual}). Emacs can connect to other X displays -via the command @code{make-frame-on-display}. Each X display has its -own selected frame and its own minibuffer windows; however, only one -of those frames is ``@emph{the} selected frame'' at any given moment -(@pxref{Input Focus}). Emacs can even connect to other text -terminals, by interacting with the @command{emacsclient} program. -@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. - -@cindex X display names -@cindex display name on X - A single X server can handle more than one display. Each X display -has a three-part name, -@samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}. The -first part, @var{hostname}, specifies the name of the machine to which -the display is physically connected. The second part, -@var{displaynumber}, is a zero-based number that identifies one or -more monitors connected to that machine that share a common keyboard -and pointing device (mouse, tablet, etc.). The third part, -@var{screennumber}, identifies a zero-based screen number (a separate -monitor) that is part of a single monitor collection on that X server. -When you use two or more screens belonging to one server, Emacs knows -by the similarity in their names that they share a single keyboard. - - Systems that don't use the X window system, such as MS-Windows, -don't support the notion of X displays, and have only one display on -each host. The display name on these systems doesn't follow the above -3-part format; for example, the display name on MS-Windows systems is -a constant string @samp{w32}, and exists for compatibility, so that -you could pass it to functions that expect a display name. - -@deffn Command make-frame-on-display display &optional parameters -This function creates and returns a new frame on @var{display}, taking -the other frame parameters from the alist @var{parameters}. -@var{display} should be the name of an X display (a string). - -Before creating the frame, this function ensures that Emacs is ``set -up'' to display graphics. For instance, if Emacs has not processed X -resources (e.g., if it was started on a text terminal), it does so at -this time. In all other respects, this function behaves like -@code{make-frame} (@pxref{Creating Frames}). -@end deffn - -@defun x-display-list -This function returns a list that indicates which X displays Emacs has -a connection to. The elements of the list are strings, and each one -is a display name. -@end defun - -@defun x-open-connection display &optional xrm-string must-succeed -This function opens a connection to the X display @var{display}, -without creating a frame on that display. Normally, Emacs Lisp -programs need not call this function, as @code{make-frame-on-display} -calls it automatically. The only reason for calling it is to check -whether communication can be established with a given X display. - -The optional argument @var{xrm-string}, if not @code{nil}, is a string -of resource names and values, in the same format used in the -@file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The -GNU Emacs Manual}. These values apply to all Emacs frames created on -this display, overriding the resource values recorded in the X server. -Here's an example of what this string might look like: - -@example -"*BorderWidth: 3\n*InternalBorder: 2\n" -@end example - -If @var{must-succeed} is non-@code{nil}, failure to open the connection -terminates Emacs. Otherwise, it is an ordinary Lisp error. -@end defun - -@defun x-close-connection display -This function closes the connection to display @var{display}. Before -you can do this, you must first delete all the frames that were open -on that display (@pxref{Deleting Frames}). -@end defun - -@cindex multi-monitor - On some ``multi-monitor'' setups, a single X display outputs to more -than one physical monitor. You can use the functions -@code{display-monitor-attributes-list} and @code{frame-monitor-attributes} -to obtain information about such setups. - -@defun display-monitor-attributes-list &optional display -This function returns a list of physical monitor attributes on -@var{display}, which can be a display name (a string), a terminal, or -a frame; if omitted or @code{nil}, it defaults to the selected frame's -display. Each element of the list is an association list, -representing the attributes of a physical monitor. The first element -corresponds to the primary monitor. The attribute keys and values -are: - -@table @samp -@item geometry -Position of the top-left corner of the monitor's screen and its size, -in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}. Note -that, if the monitor is not the primary monitor, some of the -coordinates might be negative. - -@item workarea -Position of the top-left corner and size of the work area (``usable'' -space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}. -This may be different from @samp{geometry} in that space occupied by -various window manager features (docks, taskbars, etc.) may be -excluded from the work area. Whether or not such features actually -subtract from the work area depends on the platform and environment. -Again, if the monitor is not the primary monitor, some of the -coordinates might be negative. - -@item mm-size -Width and height in millimeters as @samp{(@var{width} @var{height})} - -@item frames -List of frames that this physical monitor dominates (see below). - -@item name -Name of the physical monitor as @var{string}. - -@item source -Source of the multi-monitor information as @var{string}; -e.g., @samp{XRandr} or @samp{Xinerama}. -@end table - -@var{x}, @var{y}, @var{width}, and @var{height} are integers. -@samp{name} and @samp{source} may be absent. - -A frame is @dfn{dominated} by a physical monitor when either the -largest area of the frame resides in that monitor, or (if the frame -does not intersect any physical monitors) that monitor is the closest -to the frame. Every (non-tooltip) frame (whether visible or not) in a -graphical display is dominated by exactly one physical monitor at a -time, though the frame can span multiple (or no) physical monitors. - -Here's an example of the data produced by this function on a 2-monitor -display: - -@lisp - (display-monitor-attributes-list) - @result{} - (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor} - (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height} - (mm-size 677 381) - (name . "DISPLAY1") - (frames # - #)) - ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor} - (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used} - (mm-size 593 370) - (name . "DISPLAY2") - (frames))) -@end lisp - -@end defun - -@defun frame-monitor-attributes &optional frame -This function returns the attributes of the physical monitor -dominating (see above) @var{frame}, which defaults to the selected frame. -@end defun - -@node Frame Parameters -@section Frame Parameters -@cindex frame parameters - - A frame has many parameters that control its appearance and behavior. -Just what parameters a frame has depends on what display mechanism it -uses. - - Frame parameters exist mostly for the sake of graphical displays. -Most frame parameters have no effect when applied to a frame on a text -terminal; only the @code{height}, @code{width}, @code{name}, -@code{title}, @code{menu-bar-lines}, @code{buffer-list} and -@code{buffer-predicate} parameters do something special. If the -terminal supports colors, the parameters @code{foreground-color}, -@code{background-color}, @code{background-mode} and -@code{display-type} are also meaningful. If the terminal supports -frame transparency, the parameter @code{alpha} is also meaningful. - -@menu -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. -@end menu - -@node Parameter Access -@subsection Access to Frame Parameters - -These functions let you read and change the parameter values of a -frame. - -@defun frame-parameter frame parameter -This function returns the value of the parameter @var{parameter} (a -symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the -selected frame's parameter. If @var{frame} has no setting for -@var{parameter}, this function returns @code{nil}. -@end defun - -@defun frame-parameters &optional frame -The function @code{frame-parameters} returns an alist listing all the -parameters of @var{frame} and their values. If @var{frame} is -@code{nil} or omitted, this returns the selected frame's parameters -@end defun - -@defun modify-frame-parameters frame alist -This function alters the parameters of frame @var{frame} based on the -elements of @var{alist}. Each element of @var{alist} has the form -@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a -parameter. If you don't mention a parameter in @var{alist}, its value -doesn't change. If @var{frame} is @code{nil}, it defaults to the selected -frame. -@end defun - -@defun set-frame-parameter frame parm value -This function sets the frame parameter @var{parm} to the specified -@var{value}. If @var{frame} is @code{nil}, it defaults to the -selected frame. -@end defun - -@defun modify-all-frames-parameters alist -This function alters the frame parameters of all existing frames -according to @var{alist}, then modifies @code{default-frame-alist} -(and, if necessary, @code{initial-frame-alist}) to apply the same -parameter values to frames that will be created henceforth. -@end defun - -@node Initial Parameters -@subsection Initial Frame Parameters - -You can specify the parameters for the initial startup frame by -setting @code{initial-frame-alist} in your init file (@pxref{Init -File}). - -@defopt initial-frame-alist -This variable's value is an alist of parameter values used when -creating the initial frame. You can set this variable to specify the -appearance of the initial frame without altering subsequent frames. -Each element has the form: - -@example -(@var{parameter} . @var{value}) -@end example - -Emacs creates the initial frame before it reads your init -file. After reading that file, Emacs checks @code{initial-frame-alist}, -and applies the parameter settings in the altered value to the already -created initial frame. - -If these settings affect the frame geometry and appearance, you'll see -the frame appear with the wrong ones and then change to the specified -ones. If that bothers you, you can specify the same geometry and -appearance with X resources; those do take effect before the frame is -created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. - -X resource settings typically apply to all frames. If you want to -specify some X resources solely for the sake of the initial frame, and -you don't want them to apply to subsequent frames, here's how to achieve -this. Specify parameters in @code{default-frame-alist} to override the -X resources for subsequent frames; then, to prevent these from affecting -the initial frame, specify the same parameters in -@code{initial-frame-alist} with values that match the X resources. -@end defopt - -@cindex minibuffer-only frame -If these parameters include @code{(minibuffer . nil)}, that indicates -that the initial frame should have no minibuffer. In this case, Emacs -creates a separate @dfn{minibuffer-only frame} as well. - -@defopt minibuffer-frame-alist -This variable's value is an alist of parameter values used when -creating an initial minibuffer-only frame (i.e., the minibuffer-only -frame that Emacs creates if @code{initial-frame-alist} specifies a -frame with no minibuffer). -@end defopt - -@defopt default-frame-alist -This is an alist specifying default values of frame parameters for all -Emacs frames---the first frame, and subsequent frames. When using the X -Window System, you can get the same results by means of X resources -in many cases. - -Setting this variable does not affect existing frames. Furthermore, -functions that display a buffer in a separate frame may override the -default parameters by supplying their own parameters. -@end defopt - -If you invoke Emacs with command-line options that specify frame -appearance, those options take effect by adding elements to either -@code{initial-frame-alist} or @code{default-frame-alist}. Options -which affect just the initial frame, such as @samp{--geometry} and -@samp{--maximized}, add to @code{initial-frame-alist}; the others add -to @code{default-frame-alist}. @pxref{Emacs Invocation,, Command Line -Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}. - -@node Window Frame Parameters -@subsection Window Frame Parameters -@cindex frame parameters for windowed displays - - Just what parameters a frame has depends on what display mechanism -it uses. This section describes the parameters that have special -meanings on some or all kinds of terminals. Of these, @code{name}, -@code{title}, @code{height}, @code{width}, @code{buffer-list} and -@code{buffer-predicate} provide meaningful information in terminal -frames, and @code{tty-color-mode} is meaningful only for frames on -text terminals. - -@menu -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. -@end menu - -@node Basic Parameters -@subsubsection Basic Parameters - - These frame parameters give the most basic information about the -frame. @code{title} and @code{name} are meaningful on all terminals. - -@table @code -@vindex display, a frame parameter -@item display -The display on which to open this frame. It should be a string of the -form @samp{@var{host}:@var{dpy}.@var{screen}}, just like the -@env{DISPLAY} environment variable. @xref{Multiple Terminals}, for -more details about display names. - -@vindex display-type, a frame parameter -@item display-type -This parameter describes the range of possible colors that can be used -in this frame. Its value is @code{color}, @code{grayscale} or -@code{mono}. - -@vindex title, a frame parameter -@item title -If a frame has a non-@code{nil} title, it appears in the window -system's title bar at the top of the frame, and also in the mode line -of windows in that frame if @code{mode-line-frame-identification} uses -@samp{%F} (@pxref{%-Constructs}). This is normally the case when -Emacs is not using a window system, and can only display one frame at -a time. @xref{Frame Titles}. - -@vindex name, a frame parameter -@item name -The name of the frame. The frame name serves as a default for the frame -title, if the @code{title} parameter is unspecified or @code{nil}. If -you don't specify a name, Emacs sets the frame name automatically -(@pxref{Frame Titles}). - -If you specify the frame name explicitly when you create the frame, the -name is also used (instead of the name of the Emacs executable) when -looking up X resources for the frame. - -@item explicit-name -If the frame name was specified explicitly when the frame was created, -this parameter will be that name. If the frame wasn't explicitly -named, this parameter will be @code{nil}. -@end table - -@node Position Parameters -@subsubsection Position Parameters -@cindex window position on display - - Position parameters' values are normally measured in pixels, but on -text terminals they count characters or lines instead. - -@table @code -@vindex left, a frame parameter -@item left -The position, in pixels, of the left (or right) edge of the frame with -respect to the left (or right) edge of the screen. The value may be: - -@table @asis -@item an integer -A positive integer relates the left edge of the frame to the left edge -of the screen. A negative integer relates the right frame edge to the -right screen edge. - -@item @code{(+ @var{pos})} -This specifies the position of the left frame edge relative to the left -screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen or on a monitor -other than the primary one (for multi-monitor displays). - -@item @code{(- @var{pos})} -This specifies the position of the right frame edge relative to the right -screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen or on a monitor -other than the primary one (for multi-monitor displays). -@end table - -Some window managers ignore program-specified positions. If you want to -be sure the position you specify is not ignored, specify a -non-@code{nil} value for the @code{user-position} parameter as well. - -@vindex top, a frame parameter -@item top -The screen position of the top (or bottom) edge, in pixels, with respect -to the top (or bottom) edge of the screen. It works just like -@code{left}, except vertically instead of horizontally. - -@vindex icon-left, a frame parameter -@item icon-left -The screen position of the left edge of the frame's icon, in pixels, -counting from the left edge of the screen. This takes effect when the -frame is iconified, if the window manager supports this feature. If -you specify a value for this parameter, then you must also specify a -value for @code{icon-top} and vice versa. - -@vindex icon-top, a frame parameter -@item icon-top -The screen position of the top edge of the frame's icon, in pixels, -counting from the top edge of the screen. This takes effect when the -frame is iconified, if the window manager supports this feature. - -@vindex user-position, a frame parameter -@item user-position -When you create a frame and specify its screen position with the -@code{left} and @code{top} parameters, use this parameter to say whether -the specified position was user-specified (explicitly requested in some -way by a human user) or merely program-specified (chosen by a program). -A non-@code{nil} value says the position was user-specified. - -@cindex window positions and window managers -Window managers generally heed user-specified positions, and some heed -program-specified positions too. But many ignore program-specified -positions, placing the window in a default fashion or letting the user -place it with the mouse. Some window managers, including @code{twm}, -let the user specify whether to obey program-specified positions or -ignore them. - -When you call @code{make-frame}, you should specify a non-@code{nil} -value for this parameter if the values of the @code{left} and @code{top} -parameters represent the user's stated preference; otherwise, use -@code{nil}. -@end table - -@node Size Parameters -@subsubsection Size Parameters -@cindex window size on display - - Frame parameters specify frame sizes in character units. On -graphical displays, the @code{default} face determines the actual -pixel sizes of these character units (@pxref{Face Attributes}). - -@table @code -@vindex height, a frame parameter -@item height -The height of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) - -@vindex width, a frame parameter -@item width -The width of the frame contents, in characters. (To get the width in -pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) - -@vindex user-size, a frame parameter -@item user-size -This does for the size parameters @code{height} and @code{width} what -the @code{user-position} parameter (@pxref{Position Parameters, -user-position}) does for the position parameters @code{top} and -@code{left}. - -@cindex full-screen frames -@vindex fullscreen, a frame parameter -@item fullscreen -Specify that width, height or both shall be maximized. The value -@code{fullwidth} specifies that width shall be as wide as possible. -The value @code{fullheight} specifies that height shall be as tall as -possible. The value @code{fullboth} specifies that both the width and -the height shall be set to the size of the screen. The value -@code{maximized} specifies that the frame shall be maximized. The -difference between @code{maximized} and @code{fullboth} is that the -former can still be resized by dragging window manager decorations -with the mouse, while the latter really covers the whole screen and -does not allow resizing by mouse dragging. - -With some window managers you may have to customize the variable -@code{frame-resize-pixelwise} to a non-@code{nil} value in order to make -a frame appear ``maximized'' or ``fullscreen''. - -@end table - -@node Layout Parameters -@subsubsection Layout Parameters -@cindex layout parameters of frames -@cindex frame layout parameters - - These frame parameters enable or disable various parts of the -frame, or control their sizes. - -@table @code -@vindex border-width, a frame parameter -@item border-width -The width in pixels of the frame's border. - -@vindex internal-border-width, a frame parameter -@item internal-border-width -The distance in pixels between text (or fringe) and the frame's border. - -@vindex vertical-scroll-bars, a frame parameter -@item vertical-scroll-bars -Whether the frame has scroll bars for vertical scrolling, and which side -of the frame they should be on. The possible values are @code{left}, -@code{right}, and @code{nil} for no scroll bars. - -@ignore -@vindex horizontal-scroll-bars, a frame parameter -@item horizontal-scroll-bars -Whether the frame has scroll bars for horizontal scrolling -(non-@code{nil} means yes). Horizontal scroll bars are not currently -implemented. -@end ignore - -@vindex scroll-bar-width, a frame parameter -@item scroll-bar-width -The width of vertical scroll bars, in pixels, or @code{nil} meaning to -use the default width. - -@vindex left-fringe, a frame parameter -@vindex right-fringe, a frame parameter -@item left-fringe -@itemx right-fringe -The default width of the left and right fringes of windows in this -frame (@pxref{Fringes}). If either of these is zero, that effectively -removes the corresponding fringe. - -When you use @code{frame-parameter} to query the value of either of -these two frame parameters, the return value is always an integer. -When using @code{set-frame-parameter}, passing a @code{nil} value -imposes an actual default value of 8 pixels. - -The combined fringe widths must add up to an integral number of -columns, so the actual default fringe widths for the frame, as -reported by @code{frame-parameter}, may be larger than what you -specify. Any extra width is distributed evenly between the left and -right fringe. However, you can force one fringe or the other to a -precise width by specifying that width as a negative integer. If both -widths are negative, only the left fringe gets the specified width. - -@vindex right-divider-width, a frame parameter -@item right-divider-width -The width (thickness) reserved for the right divider (@pxref{Window -Dividers}) of any window on the frame, in pixels. A value of zero means -to not draw right dividers. - -@vindex bottom-divider-width, a frame parameter -@item bottom-divider-width -The width (thickness) reserved for the bottom divider (@pxref{Window -Dividers}) of any window on the frame, in pixels. A value of zero means -to not draw bottom dividers. - -@vindex menu-bar-lines frame parameter -@item menu-bar-lines -The number of lines to allocate at the top of the frame for a menu -bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise. -@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. - -@vindex tool-bar-lines frame parameter -@item tool-bar-lines -The number of lines to use for the tool bar. The default is 1 if Tool -Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The -GNU Emacs Manual}. - -@vindex tool-bar-position frame parameter -@item tool-bar-position -The position of the tool bar. Currently only for the GTK tool bar. -Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}. -The default is @code{top}. - -@vindex line-spacing, a frame parameter -@item line-spacing -Additional space to leave below each text line, in pixels (a positive -integer). @xref{Line Height}, for more information. -@end table - -@node Buffer Parameters -@subsubsection Buffer Parameters - - These frame parameters, meaningful on all kinds of terminals, deal -with which buffers have been, or should, be displayed in the frame. - -@table @code -@vindex minibuffer, a frame parameter -@item minibuffer -Whether this frame has its own minibuffer. The value @code{t} means -yes, @code{nil} means no, @code{only} means this frame is just a -minibuffer. If the value is a minibuffer window (in some other -frame), the frame uses that minibuffer. - -This frame parameter takes effect when the frame is created, and can -not be changed afterwards. - -@vindex buffer-predicate, a frame parameter -@item buffer-predicate -The buffer-predicate function for this frame. The function -@code{other-buffer} uses this predicate (from the selected frame) to -decide which buffers it should consider, if the predicate is not -@code{nil}. It calls the predicate with one argument, a buffer, once for -each buffer; if the predicate returns a non-@code{nil} value, it -considers that buffer. - -@vindex buffer-list, a frame parameter -@item buffer-list -A list of buffers that have been selected in this frame, ordered -most-recently-selected first. - -@vindex unsplittable, a frame parameter -@item unsplittable -If non-@code{nil}, this frame's window is never split automatically. -@end table - -@node Management Parameters -@subsubsection Window Management Parameters -@cindex window manager interaction, and frame parameters - - The following frame parameters control various aspects of the -frame's interaction with the window manager. They have no effect on -text terminals. - -@table @code -@vindex visibility, a frame parameter -@item visibility -The state of visibility of the frame. There are three possibilities: -@code{nil} for invisible, @code{t} for visible, and @code{icon} for -iconified. @xref{Visibility of Frames}. - -@vindex auto-raise, a frame parameter -@item auto-raise -If non-@code{nil}, Emacs automatically raises the frame when it is -selected. Some window managers do not allow this. - -@vindex auto-lower, a frame parameter -@item auto-lower -If non-@code{nil}, Emacs automatically lowers the frame when it is -deselected. Some window managers do not allow this. - -@vindex icon-type, a frame parameter -@item icon-type -The type of icon to use for this frame. If the value is a string, -that specifies a file containing a bitmap to use; @code{nil} specifies -no icon (in which case the window manager decides what to show); any -other non-@code{nil} value specifies the default Emacs icon. - -@vindex icon-name, a frame parameter -@item icon-name -The name to use in the icon for this frame, when and if the icon -appears. If this is @code{nil}, the frame's title is used. - -@vindex window-id, a frame parameter -@item window-id -The ID number which the graphical display uses for this frame. Emacs -assigns this parameter when the frame is created; changing the -parameter has no effect on the actual ID number. - -@vindex outer-window-id, a frame parameter -@item outer-window-id -The ID number of the outermost window-system window in which the frame -exists. As with @code{window-id}, changing this parameter has no -actual effect. - -@vindex wait-for-wm, a frame parameter -@item wait-for-wm -If non-@code{nil}, tell Xt to wait for the window manager to confirm -geometry changes. Some window managers, including versions of Fvwm2 -and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to -prevent hanging with those window managers. - -@vindex sticky, a frame parameter -@item sticky -If non-@code{nil}, the frame is visible on all virtual desktops on systems -with virtual desktops. - -@ignore -@vindex parent-id, a frame parameter -@item parent-id -@c ??? Not yet working. -The X window number of the window that should be the parent of this one. -Specifying this lets you create an Emacs window inside some other -application's window. (It is not certain this will be implemented; try -it and see if it works.) -@end ignore -@end table - -@node Cursor Parameters -@subsubsection Cursor Parameters -@cindex cursor, and frame parameters - - This frame parameter controls the way the cursor looks. - -@table @code -@vindex cursor-type, a frame parameter -@item cursor-type -How to display the cursor. Legitimate values are: - -@table @code -@item box -Display a filled box. (This is the default.) -@item hollow -Display a hollow box. -@item nil -Don't display a cursor. -@item bar -Display a vertical bar between characters. -@item (bar . @var{width}) -Display a vertical bar @var{width} pixels wide between characters. -@item hbar -Display a horizontal bar. -@item (hbar . @var{height}) -Display a horizontal bar @var{height} pixels high. -@end table -@end table - -@vindex cursor-type -The @code{cursor-type} frame parameter may be overridden by the -variables @code{cursor-type} and -@code{cursor-in-non-selected-windows}: - -@defvar cursor-type -This buffer-local variable controls how the cursor looks in a selected -window showing the buffer. If its value is @code{t}, that means to -use the cursor specified by the @code{cursor-type} frame parameter. -Otherwise, the value should be one of the cursor types listed above, -and it overrides the @code{cursor-type} frame parameter. -@end defvar - -@defopt cursor-in-non-selected-windows -This buffer-local variable controls how the cursor looks in a window -that is not selected. It supports the same values as the -@code{cursor-type} frame parameter; also, @code{nil} means don't -display a cursor in nonselected windows, and @code{t} (the default) -means use a standard modification of the usual cursor type (solid box -becomes hollow box, and bar becomes a narrower bar). -@end defopt - -@defopt blink-cursor-alist -This variable specifies how to blink the cursor. Each element has the -form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor -type equals @var{on-state} (comparing using @code{equal}), the -corresponding @var{off-state} specifies what the cursor looks like -when it blinks ``off''. Both @var{on-state} and @var{off-state} -should be suitable values for the @code{cursor-type} frame parameter. - -There are various defaults for how to blink each type of cursor, if -the type is not mentioned as an @var{on-state} here. Changes in this -variable do not take effect immediately, only when you specify the -@code{cursor-type} frame parameter. -@end defopt - -@node Font and Color Parameters -@subsubsection Font and Color Parameters -@cindex font and color, frame parameters - - These frame parameters control the use of fonts and colors. - -@table @code -@vindex font-backend, a frame parameter -@item font-backend -A list of symbols, specifying the @dfn{font backends} to use for -drawing fonts in the frame, in order of priority. On X, there are -currently two available font backends: @code{x} (the X core font -driver) and @code{xft} (the Xft font driver). On MS-Windows, there are -currently two available font backends: @code{gdi} and -@code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs -Manual}). On other systems, there is only one available font backend, -so it does not make sense to modify this frame parameter. - -@vindex background-mode, a frame parameter -@item background-mode -This parameter is either @code{dark} or @code{light}, according -to whether the background color is a light one or a dark one. - -@vindex tty-color-mode, a frame parameter -@item tty-color-mode -@cindex standard colors for character terminals -This parameter overrides the terminal's color support as given by the -system's terminal capabilities database in that this parameter's value -specifies the color mode to use on a text terminal. The value can be -either a symbol or a number. A number specifies the number of colors -to use (and, indirectly, what commands to issue to produce each -color). For example, @code{(tty-color-mode . 8)} specifies use of the -ANSI escape sequences for 8 standard text colors. A value of -1 turns -off color support. - -If the parameter's value is a symbol, it specifies a number through -the value of @code{tty-color-mode-alist}, and the associated number is -used instead. - -@vindex screen-gamma, a frame parameter -@item screen-gamma -@cindex gamma correction -If this is a number, Emacs performs ``gamma correction'' which adjusts -the brightness of all colors. The value should be the screen gamma of -your display. - -Usual PC monitors have a screen gamma of 2.2, so color values in -Emacs, and in X windows generally, are calibrated to display properly -on a monitor with that gamma value. If you specify 2.2 for -@code{screen-gamma}, that means no correction is needed. Other values -request correction, designed to make the corrected colors appear on -your screen the way they would have appeared without correction on an -ordinary monitor with a gamma value of 2.2. - -If your monitor displays colors too light, you should specify a -@code{screen-gamma} value smaller than 2.2. This requests correction -that makes colors darker. A screen gamma value of 1.5 may give good -results for LCD color displays. - -@vindex alpha, a frame parameter -@item alpha -@cindex opacity, frame -@cindex transparency, frame -@vindex frame-alpha-lower-limit -This parameter specifies the opacity of the frame, on graphical -displays that support variable opacity. It should be an integer -between 0 and 100, where 0 means completely transparent and 100 means -completely opaque. It can also have a @code{nil} value, which tells -Emacs not to set the frame opacity (leaving it to the window manager). - -To prevent the frame from disappearing completely from view, the -variable @code{frame-alpha-lower-limit} defines a lower opacity limit. -If the value of the frame parameter is less than the value of this -variable, Emacs uses the latter. By default, -@code{frame-alpha-lower-limit} is 20. - -The @code{alpha} frame parameter can also be a cons cell -@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the -opacity of the frame when it is selected, and @samp{inactive} is the -opacity when it is not selected. -@end table - -The following frame parameters are semi-obsolete in that they are -automatically equivalent to particular face attributes of particular -faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}): - -@table @code -@vindex font, a frame parameter -@item font -The name of the font for displaying text in the frame. This is a -string, either a valid font name for your system or the name of an Emacs -fontset (@pxref{Fontsets}). It is equivalent to the @code{font} -attribute of the @code{default} face. - -@vindex foreground-color, a frame parameter -@item foreground-color -The color to use for the image of a character. It is equivalent to -the @code{:foreground} attribute of the @code{default} face. - -@vindex background-color, a frame parameter -@item background-color -The color to use for the background of characters. It is equivalent to -the @code{:background} attribute of the @code{default} face. - -@vindex mouse-color, a frame parameter -@item mouse-color -The color for the mouse pointer. It is equivalent to the @code{:background} -attribute of the @code{mouse} face. - -@vindex cursor-color, a frame parameter -@item cursor-color -The color for the cursor that shows point. It is equivalent to the -@code{:background} attribute of the @code{cursor} face. - -@vindex border-color, a frame parameter -@item border-color -The color for the border of the frame. It is equivalent to the -@code{:background} attribute of the @code{border} face. - -@vindex scroll-bar-foreground, a frame parameter -@item scroll-bar-foreground -If non-@code{nil}, the color for the foreground of scroll bars. It is -equivalent to the @code{:foreground} attribute of the -@code{scroll-bar} face. - -@vindex scroll-bar-background, a frame parameter -@item scroll-bar-background -If non-@code{nil}, the color for the background of scroll bars. It is -equivalent to the @code{:background} attribute of the -@code{scroll-bar} face. -@end table - -@node Size and Position -@subsection Frame Size And Position -@cindex size of frame -@cindex screen size -@cindex frame size -@cindex resize frame - - You can read or change the size and position of a frame using the -frame parameters @code{left}, @code{top}, @code{height}, and -@code{width}. Whatever geometry parameters you don't specify are chosen -by the window manager in its usual fashion. - - Here are some special features for working with sizes and positions. -(For the precise meaning of ``selected frame'' used by these functions, -see @ref{Input Focus}.) - -@defun set-frame-position frame left top -This function sets the position of the top left corner of @var{frame} to -@var{left} and @var{top}. These arguments are measured in pixels, and -normally count from the top left corner of the screen. - -Negative parameter values position the bottom edge of the window up from -the bottom edge of the screen, or the right window edge to the left of -the right edge of the screen. It would probably be better if the values -were always counted from the left and top, so that negative arguments -would position the frame partly off the top or left edge of the screen, -but it seems inadvisable to change that now. -@end defun - -@defun frame-height &optional frame -@defunx frame-width &optional frame -These functions return the height and width of @var{frame}, measured in -lines and columns. If you don't supply @var{frame}, they use the -selected frame. -@end defun - -@defun frame-pixel-height &optional frame -@defunx frame-pixel-width &optional frame -These functions return the height and width of the main display area -of @var{frame}, measured in pixels. If you don't supply @var{frame}, -they use the selected frame. For a text terminal, the results are in -characters rather than pixels. - -These values include the internal borders, and windows' scroll bars -and fringes (which belong to individual windows, not to the frame -itself). The exact value of the heights depends on the window-system -and toolkit in use. With GTK+, the height does not include any tool -bar or menu bar. With the Motif or Lucid toolkits, it includes the -tool bar but not the menu bar. In a graphical version with no -toolkit, it includes both the tool bar and menu bar. For a text -terminal, the result includes the menu bar. -@end defun - -@defun frame-char-height &optional frame -@defunx frame-char-width &optional frame -These functions return the height and width of a character in -@var{frame}, measured in pixels. The values depend on the choice of -font. If you don't supply @var{frame}, these functions use the selected -frame. -@end defun - -@defopt frame-resize-pixelwise -If this option is @code{nil}, a frame's size is usually rounded to a -multiple of the current values of that frame's @code{frame-char-height} -and @code{frame-char-width}. If this is non-@code{nil}, no rounding -occurs, hence frame sizes can increase/decrease by one pixel. - -Setting this causes the next resize operation to pass the corresponding -size hints to the window manager. This means that this variable should -be set only in a user's initial file; applications should never bind it -temporarily. - -The precise meaning of a value of @code{nil} for this option depends -on the toolkit used. Dragging the frame border with the mouse is usually -done character-wise. Calling @code{set-frame-size} (see below) -with arguments that do not specify the frame size as an integer multiple -of its character size, however, may: be ignored, cause a -rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows). - -With some window managers you may have to set this to non-@code{nil} in -order to make a frame appear truly ``maximized'' or ``fullscreen''. -@end defopt - -@defun set-frame-size frame width height pixelwise -This function sets the size of @var{frame}, measured in characters; -@var{width} and @var{height} specify the new width in columns and the -new height in lines. - -The optional argument @var{pixelwise} non-@code{nil} means to measure -the new width and height in units of pixels instead. Note that if -@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to -fully honor the request if it does not increase/decrease the frame size -to a multiple of its character size. -@end defun - -@defun set-frame-height frame height &optional pretend pixelwise -This function resizes @var{frame} to a height of @var{height} lines. The -sizes of existing windows in @var{frame} are altered proportionally to -fit. - -If @var{pretend} is non-@code{nil}, then Emacs displays @var{height} -lines of output in @var{frame}, but does not change its value for the -actual height of the frame. This is only useful on text terminals. -Using a smaller height than the terminal actually implements may be -useful to reproduce behavior observed on a smaller screen, or if the -terminal malfunctions when using its whole screen. Setting the frame -height ``for real'' does not always work, because knowing the correct -actual size may be necessary for correct cursor positioning on -text terminals. - -The optional fourth argument @var{pixelwise} non-@code{nil} means that -@var{frame} should be @var{height} pixels high. Note that if -@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to -fully honor the request if it does not increase/decrease the frame -height to a multiple of its character height. -@end defun - -@defun set-frame-width frame width &optional pretend pixelwise -This function sets the width of @var{frame}, measured in characters. -The argument @var{pretend} has the same meaning as in -@code{set-frame-height}. - -The optional fourth argument @var{pixelwise} non-@code{nil} means that -@var{frame} should be @var{width} pixels wide. Note that if -@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to -fully honor the request if it does not increase/decrease the frame width -to a multiple of its character width. -@end defun - -@c FIXME? Belongs more in Emacs manual than here? -@c But, e.g., fit-window-to-buffer is in this manual. -If you have a frame that displays only one window, you can fit that -frame to its buffer using the command @code{fit-frame-to-buffer}. - -@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only -This command adjusts the size of @var{frame} to display the contents of -its buffer exactly. @var{frame} can be any live frame and defaults to -the selected one. Fitting is done only if @var{frame}'s root window is -live. The arguments @var{max-height}, @var{min-height}, @var{max-width} -and @var{min-width} specify bounds on the new total size of -@var{frame}'s root window. @var{min-height} and @var{min-width} default -to the values of @code{window-min-height} and @code{window-min-width} -respectively. - -If the optional argument @var{only} is @code{vertically}, this function -may resize the frame vertically only. If @var{only} is -@code{horizontally}, it may resize the frame horizontally only. -@end deffn - -The behavior of @code{fit-frame-to-buffer} can be controlled with the -help of the two options listed next. - -@defopt fit-frame-to-buffer-margins -This option can be used to specify margins around frames to be fit by -@code{fit-frame-to-buffer}. Such margins can be useful to avoid, for -example, that such frames overlap the taskbar. - -It specifies the numbers of pixels to be left free on the left, above, -the right, and below a frame that shall be fit. The default specifies -@code{nil} for each which means to use no margins. The value specified -here can be overridden for a specific frame by that frame's -@code{fit-frame-to-buffer-margins} parameter, if present. -@end defopt - -@defopt fit-frame-to-buffer-sizes -This option specifies size boundaries for @code{fit-frame-to-buffer}. -It specifies the total maximum and minimum lines and maximum and minimum -columns of the root window of any frame that shall be fit to its buffer. -If any of these values is non-@code{nil}, it overrides the corresponding -argument of @code{fit-frame-to-buffer}. -@end defopt - - -@node Geometry -@subsection Geometry - - Here's how to examine the data in an X-style window geometry -specification: - -@defun x-parse-geometry geom -@cindex geometry specification -The function @code{x-parse-geometry} converts a standard X window -geometry string to an alist that you can use as part of the argument to -@code{make-frame}. - -The alist describes which parameters were specified in @var{geom}, and -gives the values specified for them. Each element looks like -@code{(@var{parameter} . @var{value})}. The possible @var{parameter} -values are @code{left}, @code{top}, @code{width}, and @code{height}. - -For the size parameters, the value must be an integer. The position -parameter names @code{left} and @code{top} are not totally accurate, -because some values indicate the position of the right or bottom edges -instead. The @var{value} possibilities for the position parameters are: -an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})}; -as previously described (@pxref{Position Parameters}). - -Here is an example: - -@example -(x-parse-geometry "35x70+0-0") - @result{} ((height . 70) (width . 35) - (top - 0) (left . 0)) -@end example -@end defun - -@node Terminal Parameters -@section Terminal Parameters -@cindex terminal parameters - - Each terminal has a list of associated parameters. These -@dfn{terminal parameters} are mostly a convenient way of storage for -terminal-local variables, but some terminal parameters have a special -meaning. - - This section describes functions to read and change the parameter values -of a terminal. They all accept as their argument either a terminal or -a frame; the latter means use that frame's terminal. An argument of -@code{nil} means the selected frame's terminal. - -@defun terminal-parameters &optional terminal -This function returns an alist listing all the parameters of -@var{terminal} and their values. -@end defun - -@defun terminal-parameter terminal parameter -This function returns the value of the parameter @var{parameter} (a -symbol) of @var{terminal}. If @var{terminal} has no setting for -@var{parameter}, this function returns @code{nil}. -@end defun - -@defun set-terminal-parameter terminal parameter value -This function sets the parameter @var{parm} of @var{terminal} to the -specified @var{value}, and returns the previous value of that -parameter. -@end defun - -Here's a list of a few terminal parameters that have a special -meaning: - -@table @code -@item background-mode -The classification of the terminal's background color, either -@code{light} or @code{dark}. -@item normal-erase-is-backspace -Value is either 1 or 0, depending on whether -@code{normal-erase-is-backspace-mode} is turned on or off on this -terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}. -@item terminal-initted -After the terminal is initialized, this is set to the -terminal-specific initialization function. -@end table - -@node Frame Titles -@section Frame Titles -@cindex frame title - - Every frame has a @code{name} parameter; this serves as the default -for the frame title which window systems typically display at the top of -the frame. You can specify a name explicitly by setting the @code{name} -frame property. - - Normally you don't specify the name explicitly, and Emacs computes the -frame name automatically based on a template stored in the variable -@code{frame-title-format}. Emacs recomputes the name each time the -frame is redisplayed. - -@defvar frame-title-format -This variable specifies how to compute a name for a frame when you have -not explicitly specified one. The variable's value is actually a mode -line construct, just like @code{mode-line-format}, except that the -@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line -Data}. -@end defvar - -@defvar icon-title-format -This variable specifies how to compute the name for an iconified frame, -when you have not explicitly specified the frame title. This title -appears in the icon itself. -@end defvar - -@defvar multiple-frames -This variable is set automatically by Emacs. Its value is @code{t} when -there are two or more frames (not counting minibuffer-only frames or -invisible frames). The default value of @code{frame-title-format} uses -@code{multiple-frames} so as to put the buffer name in the frame title -only when there is more than one frame. - -The value of this variable is not guaranteed to be accurate except -while processing @code{frame-title-format} or -@code{icon-title-format}. -@end defvar - -@node Deleting Frames -@section Deleting Frames -@cindex deleting frames - - A @dfn{live frame} is one that has not been deleted. When a frame -is deleted, it is removed from its terminal display, although it may -continue to exist as a Lisp object until there are no more references -to it. - -@deffn Command delete-frame &optional frame force -@vindex delete-frame-functions -This function deletes the frame @var{frame}. Unless @var{frame} is a -tooltip, it first runs the hook @code{delete-frame-functions} (each -function gets one argument, @var{frame}). By default, @var{frame} is -the selected frame. - -A frame cannot be deleted if its minibuffer is used by other frames. -Normally, you cannot delete a frame if all other frames are invisible, -but if @var{force} is non-@code{nil}, then you are allowed to do so. -@end deffn - -@defun frame-live-p frame -The function @code{frame-live-p} returns non-@code{nil} if the frame -@var{frame} has not been deleted. The possible non-@code{nil} return -values are like those of @code{framep}. @xref{Frames}. -@end defun - - Some window managers provide a command to delete a window. These work -by sending a special message to the program that operates the window. -When Emacs gets one of these commands, it generates a -@code{delete-frame} event, whose normal definition is a command that -calls the function @code{delete-frame}. @xref{Misc Events}. - -@node Finding All Frames -@section Finding All Frames -@cindex frames, scanning all - -@defun frame-list -This function returns a list of all the live frames, i.e., those that -have not been deleted. It is analogous to @code{buffer-list} for -buffers, and includes frames on all terminals. The list that you get -is newly created, so modifying the list doesn't have any effect on the -internals of Emacs. -@end defun - -@defun visible-frame-list -This function returns a list of just the currently visible frames. -@xref{Visibility of Frames}. Frames on text terminals always count as -``visible'', even though only the selected one is actually displayed. -@end defun - -@defun next-frame &optional frame minibuf -This function lets you cycle conveniently through all the frames on -the current display from an arbitrary starting point. It returns the -``next'' frame after @var{frame} in the cycle. If @var{frame} is -omitted or @code{nil}, it defaults to the selected frame (@pxref{Input -Focus}). - -The second argument, @var{minibuf}, says which frames to consider: - -@table @asis -@item @code{nil} -Exclude minibuffer-only frames. -@item @code{visible} -Consider all visible frames. -@item 0 -Consider all visible or iconified frames. -@item a window -Consider only the frames using that particular window as their -minibuffer. -@item anything else -Consider all frames. -@end table -@end defun - -@defun previous-frame &optional frame minibuf -Like @code{next-frame}, but cycles through all frames in the opposite -direction. -@end defun - - See also @code{next-window} and @code{previous-window}, in @ref{Cyclic -Window Ordering}. - -@node Minibuffers and Frames -@section Minibuffers and Frames - -Normally, each frame has its own minibuffer window at the bottom, which -is used whenever that frame is selected. If the frame has a minibuffer, -you can get it with @code{minibuffer-window} (@pxref{Definition of -minibuffer-window}). - -However, you can also create a frame with no minibuffer. Such a frame -must use the minibuffer window of some other frame. When you create the -frame, you can explicitly specify the minibuffer window to use (in some -other frame). If you don't, then the minibuffer is found in the frame -which is the value of the variable @code{default-minibuffer-frame}. Its -value should be a frame that does have a minibuffer. - -If you use a minibuffer-only frame, you might want that frame to raise -when you enter the minibuffer. If so, set the variable -@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}. - -@defvar default-minibuffer-frame -This variable specifies the frame to use for the minibuffer window, by -default. It does not affect existing frames. It is always local to -the current terminal and cannot be buffer-local. @xref{Multiple -Terminals}. -@end defvar - -@node Input Focus -@section Input Focus -@cindex input focus -@c @cindex selected frame Duplicates selected-frame, same for selected-window. - -At any time, one frame in Emacs is the @dfn{selected frame}. The selected -window always resides on the selected frame. - -When Emacs displays its frames on several terminals (@pxref{Multiple -Terminals}), each terminal has its own selected frame. But only one -of these is ``@emph{the} selected frame'': it's the frame that belongs -to the terminal from which the most recent input came. That is, when -Emacs runs a command that came from a certain terminal, the selected -frame is the one of that terminal. Since Emacs runs only a single -command at any given time, it needs to consider only one selected -frame at a time; this frame is what we call @dfn{the selected frame} -in this manual. The display on which the selected frame is shown is -the @dfn{selected frame's display}. - -@defun selected-frame -This function returns the selected frame. -@end defun - -Some window systems and window managers direct keyboard input to the -window object that the mouse is in; others require explicit clicks or -commands to @dfn{shift the focus} to various window objects. Either -way, Emacs automatically keeps track of which frame has the focus. To -explicitly switch to a different frame from a Lisp function, call -@code{select-frame-set-input-focus}. - -Lisp programs can also switch frames ``temporarily'' by calling the -function @code{select-frame}. This does not alter the window system's -concept of focus; rather, it escapes from the window manager's control -until that control is somehow reasserted. - -When using a text terminal, only one frame can be displayed at a time -on the terminal, so after a call to @code{select-frame}, the next -redisplay actually displays the newly selected frame. This frame -remains selected until a subsequent call to @code{select-frame}. Each -frame on a text terminal has a number which appears in the mode line -before the buffer name (@pxref{Mode Line Variables}). - -@defun select-frame-set-input-focus frame &optional norecord -This function selects @var{frame}, raises it (should it happen to be -obscured by other frames) and tries to give it the X server's focus. -On a text terminal, the next redisplay displays the new frame on the -entire terminal screen. The optional argument @var{norecord} has the -same meaning as for @code{select-frame} (see below). The return value -of this function is not significant. -@end defun - -@deffn Command select-frame frame &optional norecord -This function selects frame @var{frame}, temporarily disregarding the -focus of the X server if any. The selection of @var{frame} lasts until -the next time the user does something to select a different frame, or -until the next time this function is called. (If you are using a -window system, the previously selected frame may be restored as the -selected frame after return to the command loop, because it still may -have the window system's input focus.) - -The specified @var{frame} becomes the selected frame, and its terminal -becomes the selected terminal. This function then calls -@code{select-window} as a subroutine, passing the window selected -within @var{frame} as its first argument and @var{norecord} as its -second argument (hence, if @var{norecord} is non-@code{nil}, this -avoids changing the order of recently selected windows nor the buffer -list). @xref{Selecting Windows}. - -This function returns @var{frame}, or @code{nil} if @var{frame} has -been deleted. - -In general, you should never use @code{select-frame} in a way that -could switch to a different terminal without switching back when -you're done. -@end deffn - -Emacs cooperates with the window system by arranging to select frames as -the server and window manager request. It does so by generating a -special kind of input event, called a @dfn{focus} event, when -appropriate. The command loop handles a focus event by calling -@code{handle-switch-frame}. @xref{Focus Events}. - -@deffn Command handle-switch-frame frame -This function handles a focus event by selecting frame @var{frame}. - -Focus events normally do their job by invoking this command. -Don't call it for any other reason. -@end deffn - -@defun redirect-frame-focus frame &optional focus-frame -This function redirects focus from @var{frame} to @var{focus-frame}. -This means that @var{focus-frame} will receive subsequent keystrokes and -events intended for @var{frame}. After such an event, the value of -@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame -events specifying @var{frame} will instead select @var{focus-frame}. - -If @var{focus-frame} is omitted or @code{nil}, that cancels any existing -redirection for @var{frame}, which therefore once again receives its own -events. - -One use of focus redirection is for frames that don't have minibuffers. -These frames use minibuffers on other frames. Activating a minibuffer -on another frame redirects focus to that frame. This puts the focus on -the minibuffer's frame, where it belongs, even though the mouse remains -in the frame that activated the minibuffer. - -Selecting a frame can also change focus redirections. Selecting frame -@code{bar}, when @code{foo} had been selected, changes any redirections -pointing to @code{foo} so that they point to @code{bar} instead. This -allows focus redirection to work properly when the user switches from -one frame to another using @code{select-window}. - -This means that a frame whose focus is redirected to itself is treated -differently from a frame whose focus is not redirected. -@code{select-frame} affects the former but not the latter. - -The redirection lasts until @code{redirect-frame-focus} is called to -change it. -@end defun - -@defvar focus-in-hook -This is a normal hook run when an Emacs frame gains input focus. -@end defvar - -@defvar focus-out-hook -This is a normal hook run when an Emacs frame loses input focus. -@end defvar - -@defopt focus-follows-mouse -This option is how you inform Emacs whether the window manager transfers -focus when the user moves the mouse. Non-@code{nil} says that it does. -When this is so, the command @code{other-frame} moves the mouse to a -position consistent with the new selected frame. -@end defopt - -@node Visibility of Frames -@section Visibility of Frames -@cindex visible frame -@cindex invisible frame -@cindex iconified frame -@cindex minimized frame -@cindex frame visibility - -A frame on a graphical display may be @dfn{visible}, @dfn{invisible}, -or @dfn{iconified}. If it is visible, its contents are displayed in -the usual manner. If it is iconified, its contents are not displayed, -but there is a little icon somewhere to bring the frame back into view -(some window managers refer to this state as @dfn{minimized} rather -than @dfn{iconified}, but from Emacs' point of view they are the same -thing). If a frame is invisible, it is not displayed at all. - - Visibility is meaningless on text terminals, since only the selected -one is actually displayed in any case. - -@defun frame-visible-p frame -This function returns the visibility status of frame @var{frame}. The -value is @code{t} if @var{frame} is visible, @code{nil} if it is -invisible, and @code{icon} if it is iconified. - -On a text terminal, all frames are considered ``visible'' for the -purposes of this function, even though only one frame is displayed. -@xref{Raising and Lowering}. -@end defun - -@deffn Command iconify-frame &optional frame -This function iconifies frame @var{frame}. If you omit @var{frame}, it -iconifies the selected frame. -@end deffn - -@deffn Command make-frame-visible &optional frame -This function makes frame @var{frame} visible. If you omit -@var{frame}, it makes the selected frame visible. This does not raise -the frame, but you can do that with @code{raise-frame} if you wish -(@pxref{Raising and Lowering}). -@end deffn - -@deffn Command make-frame-invisible &optional frame force -This function makes frame @var{frame} invisible. If you omit -@var{frame}, it makes the selected frame invisible. - -Unless @var{force} is non-@code{nil}, this function refuses to make -@var{frame} invisible if all other frames are invisible.. -@end deffn - - The visibility status of a frame is also available as a frame -parameter. You can read or change it as such. @xref{Management -Parameters}. The user can also iconify and deiconify frames with the -window manager. This happens below the level at which Emacs can exert -any control, but Emacs does provide events that you can use to keep -track of such changes. @xref{Misc Events}. - -@node Raising and Lowering -@section Raising and Lowering Frames - -@cindex raising a frame -@cindex lowering a frame - Most window systems use a desktop metaphor. Part of this metaphor -is the idea that system-level windows (e.g., Emacs frames) are -stacked in a notional third dimension perpendicular to the screen -surface. Where two overlap, the one higher up covers the one -underneath. You can @dfn{raise} or @dfn{lower} a frame using the -functions @code{raise-frame} and @code{lower-frame}. - -@deffn Command raise-frame &optional frame -This function raises frame @var{frame} (default, the selected frame). -If @var{frame} is invisible or iconified, this makes it visible. -@end deffn - -@deffn Command lower-frame &optional frame -This function lowers frame @var{frame} (default, the selected frame). -@end deffn - -@defopt minibuffer-auto-raise -If this is non-@code{nil}, activation of the minibuffer raises the frame -that the minibuffer window is in. -@end defopt - - On window systems, you can also enable auto-raising (on frame -selection) or auto-lowering (on frame deselection) using frame -parameters. @xref{Management Parameters}. - -@cindex top frame - The concept of raising and lowering frames also applies to text -terminal frames. On each text terminal, only the top frame is -displayed at any one time. - -@defun tty-top-frame terminal -This function returns the top frame on @var{terminal}. @var{terminal} -should be a terminal object, a frame (meaning that frame's terminal), -or @code{nil} (meaning the selected frame's terminal). If it does not -refer to a text terminal, the return value is @code{nil}. -@end defun - -@node Frame Configurations -@section Frame Configurations -@cindex frame configuration - - A @dfn{frame configuration} records the current arrangement of frames, -all their properties, and the window configuration of each one. -(@xref{Window Configurations}.) - -@defun current-frame-configuration -This function returns a frame configuration list that describes -the current arrangement of frames and their contents. -@end defun - -@defun set-frame-configuration configuration &optional nodelete -This function restores the state of frames described in -@var{configuration}. However, this function does not restore deleted -frames. - -Ordinarily, this function deletes all existing frames not listed in -@var{configuration}. But if @var{nodelete} is non-@code{nil}, the -unwanted frames are iconified instead. -@end defun - -@node Mouse Tracking -@section Mouse Tracking -@cindex mouse tracking -@c @cindex tracking the mouse Duplicates track-mouse - - Sometimes it is useful to @dfn{track} the mouse, which means to display -something to indicate where the mouse is and move the indicator as the -mouse moves. For efficient mouse tracking, you need a way to wait until -the mouse actually moves. - - The convenient way to track the mouse is to ask for events to represent -mouse motion. Then you can wait for motion by waiting for an event. In -addition, you can easily handle any other sorts of events that may -occur. That is useful, because normally you don't want to track the -mouse forever---only until some other event, such as the release of a -button. - -@defspec track-mouse body@dots{} -This special form executes @var{body}, with generation of mouse motion -events enabled. Typically, @var{body} would use @code{read-event} to -read the motion events and modify the display accordingly. @xref{Motion -Events}, for the format of mouse motion events. - -The value of @code{track-mouse} is that of the last form in @var{body}. -You should design @var{body} to return when it sees the up-event that -indicates the release of the button, or whatever kind of event means -it is time to stop tracking. -@end defspec - -The usual purpose of tracking mouse motion is to indicate on the screen -the consequences of pushing or releasing a button at the current -position. - -In many cases, you can avoid the need to track the mouse by using -the @code{mouse-face} text property (@pxref{Special Properties}). -That works at a much lower level and runs more smoothly than -Lisp-level mouse tracking. - -@ignore -@c These are not implemented yet. - -These functions change the screen appearance instantaneously. The -effect is transient, only until the next ordinary Emacs redisplay. That -is OK for mouse tracking, since it doesn't make sense for mouse tracking -to change the text, and the body of @code{track-mouse} normally reads -the events itself and does not do redisplay. - -@defun x-contour-region window beg end -This function draws lines to make a box around the text from @var{beg} -to @var{end}, in window @var{window}. -@end defun - -@defun x-uncontour-region window beg end -This function erases the lines that would make a box around the text -from @var{beg} to @var{end}, in window @var{window}. Use it to remove -a contour that you previously made by calling @code{x-contour-region}. -@end defun - -@defun x-draw-rectangle frame left top right bottom -This function draws a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. It uses the cursor color, the one used for indicating the -location of point. -@end defun - -@defun x-erase-rectangle frame left top right bottom -This function erases a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. Erasure means redrawing the text and background that -normally belong in the specified rectangle. -@end defun -@end ignore - -@node Mouse Position -@section Mouse Position -@cindex mouse position -@cindex position of mouse - - The functions @code{mouse-position} and @code{set-mouse-position} -give access to the current position of the mouse. - -@defun mouse-position -This function returns a description of the position of the mouse. The -value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} -and @var{y} are integers giving the position in characters relative to -the top left corner of the inside of @var{frame}. -@end defun - -@defvar mouse-position-function -If non-@code{nil}, the value of this variable is a function for -@code{mouse-position} to call. @code{mouse-position} calls this -function just before returning, with its normal return value as the -sole argument, and it returns whatever this function returns to it. - -This abnormal hook exists for the benefit of packages like -@file{xt-mouse.el} that need to do mouse handling at the Lisp level. -@end defvar - -@defun set-mouse-position frame x y -This function @dfn{warps the mouse} to position @var{x}, @var{y} in -frame @var{frame}. The arguments @var{x} and @var{y} are integers, -giving the position in characters relative to the top left corner of the -inside of @var{frame}. If @var{frame} is not visible, this function -does nothing. The return value is not significant. -@end defun - -@defun mouse-pixel-position -This function is like @code{mouse-position} except that it returns -coordinates in units of pixels rather than units of characters. -@end defun - -@defun set-mouse-pixel-position frame x y -This function warps the mouse like @code{set-mouse-position} except that -@var{x} and @var{y} are in units of pixels rather than units of -characters. These coordinates are not required to be within the frame. - -If @var{frame} is not visible, this function does nothing. The return -value is not significant. -@end defun - -@defun frame-pointer-visible-p &optional frame -This predicate function returns non-@code{nil} if the mouse pointer -displayed on @var{frame} is visible; otherwise it returns @code{nil}. -@var{frame} omitted or @code{nil} means the selected frame. This is -useful when @code{make-pointer-invisible} is set to @code{t}: it -allows to know if the pointer has been hidden. -@xref{Mouse Avoidance,,,emacs, The Emacs Manual}. -@end defun - -@need 3000 - -@node Pop-Up Menus -@section Pop-Up Menus - - A Lisp program can pop up a menu so that the user can choose an -alternative with the mouse. On a text terminal, if the mouse is not -available, the user can choose an alternative using the keyboard -motion keys---@kbd{C-n}, @kbd{C-p}, or up- and down-arrow keys. - -@defun x-popup-menu position menu -This function displays a pop-up menu and returns an indication of -what selection the user makes. - -The argument @var{position} specifies where on the screen to put the -top left corner of the menu. It can be either a mouse button event -(which says to put the menu where the user actuated the button) or a -list of this form: - -@example -((@var{xoffset} @var{yoffset}) @var{window}) -@end example - -@noindent -where @var{xoffset} and @var{yoffset} are coordinates, measured in -pixels, counting from the top left corner of @var{window}. @var{window} -may be a window or a frame. - -If @var{position} is @code{t}, it means to use the current mouse -position (or the top-left corner of the frame if the mouse is not -available on a text terminal). If @var{position} is @code{nil}, it -means to precompute the key binding equivalents for the keymaps -specified in @var{menu}, without actually displaying or popping up the -menu. - -The argument @var{menu} says what to display in the menu. It can be a -keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the -return value is the list of events corresponding to the user's choice. -This list has more than one element if the choice occurred in a -submenu. (Note that @code{x-popup-menu} does not actually execute the -command bound to that sequence of events.) On text terminals and -toolkits that support menu titles, the title is taken from the prompt -string of @var{menu} if @var{menu} is a keymap, or from the prompt -string of the first keymap in @var{menu} if it is a list of keymaps -(@pxref{Defining Menus}). - -Alternatively, @var{menu} can have the following form: - -@example -(@var{title} @var{pane1} @var{pane2}...) -@end example - -@noindent -where each pane is a list of form - -@example -(@var{title} @var{item1} @var{item2}...) -@end example - -Each @var{item} should be a cons cell, @code{(@var{line} . @var{value})}, -where @var{line} is a string and @var{value} is the value to return if -that @var{line} is chosen. Unlike in a menu keymap, a @code{nil} -@var{value} does not make the menu item non-selectable. -Alternatively, each @var{item} can be a string rather than a cons -cell; this makes a non-selectable menu item. - -If the user gets rid of the menu without making a valid choice, for -instance by clicking the mouse away from a valid choice or by typing -@kbd{C-g}, then this normally results in a quit and -@code{x-popup-menu} does not return. But if @var{position} is a mouse -button event (indicating that the user invoked the menu with the -mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}. -@end defun - - @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu -if you could do the job with a prefix key defined with a menu keymap. -If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h -a} can see the individual items in that menu and provide help for them. -If instead you implement the menu by defining a command that calls -@code{x-popup-menu}, the help facilities cannot know what happens inside -that command, so they cannot give any help for the menu's items. - - The menu bar mechanism, which lets you switch between submenus by -moving the mouse, cannot look within the definition of a command to see -that it calls @code{x-popup-menu}. Therefore, if you try to implement a -submenu using @code{x-popup-menu}, it cannot work with the menu bar in -an integrated fashion. This is why all menu bar submenus are -implemented with menu keymaps within the parent menu, and never with -@code{x-popup-menu}. @xref{Menu Bar}. - - If you want a menu bar submenu to have contents that vary, you should -still use a menu keymap to implement it. To make the contents vary, add -a hook function to @code{menu-bar-update-hook} to update the contents of -the menu keymap as necessary. - -@node Dialog Boxes -@section Dialog Boxes -@cindex dialog boxes - - A dialog box is a variant of a pop-up menu---it looks a little -different, it always appears in the center of a frame, and it has just -one level and one or more buttons. The main use of dialog boxes is -for asking questions that the user can answer with ``yes'', ``no'', -and a few other alternatives. With a single button, they can also -force the user to acknowledge important information. The functions -@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the -keyboard, when called from commands invoked by mouse clicks. - -@defun x-popup-dialog position contents &optional header -This function displays a pop-up dialog box and returns an indication of -what selection the user makes. The argument @var{contents} specifies -the alternatives to offer; it has this format: - -@example -(@var{title} (@var{string} . @var{value})@dots{}) -@end example - -@noindent -which looks like the list that specifies a single pane for -@code{x-popup-menu}. - -The return value is @var{value} from the chosen alternative. - -As for @code{x-popup-menu}, an element of the list may be just a -string instead of a cons cell @code{(@var{string} . @var{value})}. -That makes a box that cannot be selected. - -If @code{nil} appears in the list, it separates the left-hand items from -the right-hand items; items that precede the @code{nil} appear on the -left, and items that follow the @code{nil} appear on the right. If you -don't include a @code{nil} in the list, then approximately half the -items appear on each side. - -Dialog boxes always appear in the center of a frame; the argument -@var{position} specifies which frame. The possible values are as in -@code{x-popup-menu}, but the precise coordinates or the individual -window don't matter; only the frame matters. - -If @var{header} is non-@code{nil}, the frame title for the box is -@samp{Information}, otherwise it is @samp{Question}. The former is used -for @code{message-box} (@pxref{message-box}). (On text terminals, the -box title is not displayed.) - -In some configurations, Emacs cannot display a real dialog box; so -instead it displays the same items in a pop-up menu in the center of the -frame. - -If the user gets rid of the dialog box without making a valid choice, -for instance using the window manager, then this produces a quit and -@code{x-popup-dialog} does not return. -@end defun - -@node Pointer Shape -@section Pointer Shape -@cindex pointer shape -@cindex mouse pointer shape - - You can specify the mouse pointer style for particular text or -images using the @code{pointer} text property, and for images with the -@code{:pointer} and @code{:map} image properties. The values you can -use in these properties are @code{text} (or @code{nil}), @code{arrow}, -@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and -@code{hourglass}. @code{text} stands for the usual mouse pointer -style used over text. - - Over void parts of the window (parts that do not correspond to any -of the buffer contents), the mouse pointer usually uses the -@code{arrow} style, but you can specify a different style (one of -those above) by setting @code{void-text-area-pointer}. - -@defopt void-text-area-pointer -This variable specifies the mouse pointer style for void text areas. -These include the areas after the end of a line or below the last line -in the buffer. The default is to use the @code{arrow} (non-text) -pointer style. -@end defopt - - When using X, you can specify what the @code{text} pointer style -really looks like by setting the variable @code{x-pointer-shape}. - -@defvar x-pointer-shape -This variable specifies the pointer shape to use ordinarily in the -Emacs frame, for the @code{text} pointer style. -@end defvar - -@defvar x-sensitive-text-pointer-shape -This variable specifies the pointer shape to use when the mouse -is over mouse-sensitive text. -@end defvar - - These variables affect newly created frames. They do not normally -affect existing frames; however, if you set the mouse color of a -frame, that also installs the current value of those two variables. -@xref{Font and Color Parameters}. - - The values you can use, to specify either of these pointer shapes, are -defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos -@key{RET} x-pointer @key{RET}} to see a list of them. - -@node Window System Selections -@section Window System Selections -@cindex selection (for window systems) -@cindex clipboard -@cindex primary selection -@cindex secondary selection - - In the X window system, data can be transferred between different -applications by means of @dfn{selections}. X defines an arbitrary -number of @dfn{selection types}, each of which can store its own data; -however, only three are commonly used: the @dfn{clipboard}, -@dfn{primary selection}, and @dfn{secondary selection}. @xref{Cut and -Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs -commands that make use of these selections. This section documents -the low-level functions for reading and setting X selections. - -@deffn Command x-set-selection type data -This function sets an X selection. It takes two arguments: a -selection type @var{type}, and the value to assign to it, @var{data}. - -@var{type} should be a symbol; it is usually one of @code{PRIMARY}, -@code{SECONDARY} or @code{CLIPBOARD}. These are symbols with -upper-case names, in accord with X Window System conventions. If -@var{type} is @code{nil}, that stands for @code{PRIMARY}. - -If @var{data} is @code{nil}, it means to clear out the selection. -Otherwise, @var{data} may be a string, a symbol, an integer (or a cons -of two integers or list of two integers), an overlay, or a cons of two -markers pointing to the same buffer. An overlay or a pair of markers -stands for text in the overlay or between the markers. The argument -@var{data} may also be a vector of valid non-vector selection values. - -This function returns @var{data}. -@end deffn - -@defun x-get-selection &optional type data-type -This function accesses selections set up by Emacs or by other X -clients. It takes two optional arguments, @var{type} and -@var{data-type}. The default for @var{type}, the selection type, is -@code{PRIMARY}. - -The @var{data-type} argument specifies the form of data conversion to -use, to convert the raw data obtained from another X client into Lisp -data. Meaningful values include @code{TEXT}, @code{STRING}, -@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE}, -@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME}, -@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS}, -@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and -@code{INTEGER}. (These are symbols with upper-case names in accord -with X conventions.) The default for @var{data-type} is -@code{STRING}. -@end defun - -@defopt selection-coding-system -This variable specifies the coding system to use when reading and -writing selections or the clipboard. @xref{Coding -Systems}. The default is @code{compound-text-with-extensions}, which -converts to the text representation that X11 normally uses. -@end defopt - -@cindex clipboard support (for MS-Windows) -When Emacs runs on MS-Windows, it does not implement X selections in -general, but it does support the clipboard. @code{x-get-selection} -and @code{x-set-selection} on MS-Windows support the text data type -only; if the clipboard holds other types of data, Emacs treats the -clipboard as empty. - -@node Drag and Drop -@section Drag and Drop - -@vindex x-dnd-test-function -@vindex x-dnd-known-types - When a user drags something from another application over Emacs, that other -application expects Emacs to tell it if Emacs can handle the data that is -dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine -what to reply. The default value is @code{x-dnd-default-test-function} -which accepts drops if the type of the data to be dropped is present in -@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or -@code{x-dnd-known-types} if you want Emacs to accept or reject drops based -on some other criteria. - -@vindex x-dnd-types-alist - If you want to change the way Emacs handles drop of different types -or add a new type, customize @code{x-dnd-types-alist}. This requires -detailed knowledge of what types other applications use for drag and -drop. - -@vindex dnd-protocol-alist - When an URL is dropped on Emacs it may be a file, but it may also be -another URL type (ftp, http, etc.). Emacs first checks -@code{dnd-protocol-alist} to determine what to do with the URL@. If -there is no match there and if @code{browse-url-browser-function} is -an alist, Emacs looks for a match there. If no match is found the -text for the URL is inserted. If you want to alter Emacs behavior, -you can customize these variables. - -@node Color Names -@section Color Names - -@cindex color names -@cindex specify color -@cindex numerical RGB color specification - A color name is text (usually in a string) that specifies a color. -Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc., -are allowed; use @kbd{M-x list-colors-display} to see a list of -defined names. You can also specify colors numerically in forms such -as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where -@var{r} specifies the red level, @var{g} specifies the green level, -and @var{b} specifies the blue level. You can use either one, two, -three, or four hex digits for @var{r}; then you must use the same -number of hex digits for all @var{g} and @var{b} as well, making -either 3, 6, 9 or 12 hex digits in all. (See the documentation of the -X Window System for more details about numerical RGB specification of -colors.) - - These functions provide a way to determine which color names are -valid, and what they look like. In some cases, the value depends on the -@dfn{selected frame}, as described below; see @ref{Input Focus}, for the -meaning of the term ``selected frame''. - - To read user input of color names with completion, use -@code{read-color} (@pxref{High-Level Completion, read-color}). - -@defun color-defined-p color &optional frame -This function reports whether a color name is meaningful. It returns -@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says -which frame's display to ask about; if @var{frame} is omitted or -@code{nil}, the selected frame is used. - -Note that this does not tell you whether the display you are using -really supports that color. When using X, you can ask for any defined -color on any kind of display, and you will get some result---typically, -the closest it can do. To determine whether a frame can really display -a certain color, use @code{color-supported-p} (see below). - -@findex x-color-defined-p -This function used to be called @code{x-color-defined-p}, -and that name is still supported as an alias. -@end defun - -@defun defined-colors &optional frame -This function returns a list of the color names that are defined -and supported on frame @var{frame} (default, the selected frame). -If @var{frame} does not support colors, the value is @code{nil}. - -@findex x-defined-colors -This function used to be called @code{x-defined-colors}, -and that name is still supported as an alias. -@end defun - -@defun color-supported-p color &optional frame background-p -This returns @code{t} if @var{frame} can really display the color -@var{color} (or at least something close to it). If @var{frame} is -omitted or @code{nil}, the question applies to the selected frame. - -Some terminals support a different set of colors for foreground and -background. If @var{background-p} is non-@code{nil}, that means you are -asking whether @var{color} can be used as a background; otherwise you -are asking whether it can be used as a foreground. - -The argument @var{color} must be a valid color name. -@end defun - -@defun color-gray-p color &optional frame -This returns @code{t} if @var{color} is a shade of gray, as defined on -@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the -question applies to the selected frame. If @var{color} is not a valid -color name, this function returns @code{nil}. -@end defun - -@defun color-values color &optional frame -@cindex rgb value -This function returns a value that describes what @var{color} should -ideally look like on @var{frame}. If @var{color} is defined, the -value is a list of three integers, which give the amount of red, the -amount of green, and the amount of blue. Each integer ranges in -principle from 0 to 65535, but some displays may not use the full -range. This three-element list is called the @dfn{rgb values} of the -color. - -If @var{color} is not defined, the value is @code{nil}. - -@example -(color-values "black") - @result{} (0 0 0) -(color-values "white") - @result{} (65280 65280 65280) -(color-values "red") - @result{} (65280 0 0) -(color-values "pink") - @result{} (65280 49152 51968) -(color-values "hungry") - @result{} nil -@end example - -The color values are returned for @var{frame}'s display. If -@var{frame} is omitted or @code{nil}, the information is returned for -the selected frame's display. If the frame cannot display colors, the -value is @code{nil}. - -@findex x-color-values -This function used to be called @code{x-color-values}, -and that name is still supported as an alias. -@end defun - -@node Text Terminal Colors -@section Text Terminal Colors -@cindex colors on text terminals - - Text terminals usually support only a small number of colors, and -the computer uses small integers to select colors on the terminal. -This means that the computer cannot reliably tell what the selected -color looks like; instead, you have to inform your application which -small integers correspond to which colors. However, Emacs does know -the standard set of colors and will try to use them automatically. - - The functions described in this section control how terminal colors -are used by Emacs. - - Several of these functions use or return @dfn{rgb values}, described -in @ref{Color Names}. - - These functions accept a display (either a frame or the name of a -terminal) as an optional argument. We hope in the future to make -Emacs support different colors on different text terminals; then this -argument will specify which terminal to operate on (the default being -the selected frame's terminal; @pxref{Input Focus}). At present, -though, the @var{frame} argument has no effect. - -@defun tty-color-define name number &optional rgb frame -This function associates the color name @var{name} with -color number @var{number} on the terminal. - -The optional argument @var{rgb}, if specified, is an rgb value, a list -of three numbers that specify what the color actually looks like. -If you do not specify @var{rgb}, then this color cannot be used by -@code{tty-color-approximate} to approximate other colors, because -Emacs will not know what it looks like. -@end defun - -@defun tty-color-clear &optional frame -This function clears the table of defined colors for a text terminal. -@end defun - -@defun tty-color-alist &optional frame -This function returns an alist recording the known colors supported by -a text terminal. - -Each element has the form @code{(@var{name} @var{number} . @var{rgb})} -or @code{(@var{name} @var{number})}. Here, @var{name} is the color -name, @var{number} is the number used to specify it to the terminal. -If present, @var{rgb} is a list of three color values (for red, green, -and blue) that says what the color actually looks like. -@end defun - -@defun tty-color-approximate rgb &optional frame -This function finds the closest color, among the known colors -supported for @var{display}, to that described by the rgb value -@var{rgb} (a list of color values). The return value is an element of -@code{tty-color-alist}. -@end defun - -@defun tty-color-translate color &optional frame -This function finds the closest color to @var{color} among the known -colors supported for @var{display} and returns its index (an integer). -If the name @var{color} is not defined, the value is @code{nil}. -@end defun - -@node Resources -@section X Resources - -This section describes some of the functions and variables for -querying and using X resources, or their equivalent on your operating -system. @xref{X Resources,, X Resources, emacs, The GNU Emacs -Manual}, for more information about X resources. - -@defun x-get-resource attribute class &optional component subclass -The function @code{x-get-resource} retrieves a resource value from the X -Window defaults database. - -Resources are indexed by a combination of a @dfn{key} and a @dfn{class}. -This function searches using a key of the form -@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name -under which Emacs was invoked), and using @samp{Emacs.@var{class}} as -the class. - -The optional arguments @var{component} and @var{subclass} add to the key -and the class, respectively. You must specify both of them or neither. -If you specify them, the key is -@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is -@samp{Emacs.@var{class}.@var{subclass}}. -@end defun - -@defvar x-resource-class -This variable specifies the application name that @code{x-get-resource} -should look up. The default value is @code{"Emacs"}. You can examine X -resources for application names other than ``Emacs'' by binding this -variable to some other string, around a call to @code{x-get-resource}. -@end defvar - -@defvar x-resource-name -This variable specifies the instance name that @code{x-get-resource} -should look up. The default value is the name Emacs was invoked with, -or the value specified with the @samp{-name} or @samp{-rn} switches. -@end defvar - -To illustrate some of the above, suppose that you have the line: - -@example -xterm.vt100.background: yellow -@end example - -@noindent -in your X resources file (whose name is usually @file{~/.Xdefaults} -or @file{~/.Xresources}). Then: - -@example -@group -(let ((x-resource-class "XTerm") (x-resource-name "xterm")) - (x-get-resource "vt100.background" "VT100.Background")) - @result{} "yellow" -@end group -@group -(let ((x-resource-class "XTerm") (x-resource-name "xterm")) - (x-get-resource "background" "VT100" "vt100" "Background")) - @result{} "yellow" -@end group -@end example - -@defvar inhibit-x-resources -If this variable is non-@code{nil}, Emacs does not look up X -resources, and X resources do not have any effect when creating new -frames. -@end defvar - -@node Display Feature Testing -@section Display Feature Testing -@cindex display feature testing - - The functions in this section describe the basic capabilities of a -particular display. Lisp programs can use them to adapt their behavior -to what the display can do. For example, a program that ordinarily uses -a popup menu could use the minibuffer if popup menus are not supported. - - The optional argument @var{display} in these functions specifies which -display to ask the question about. It can be a display name, a frame -(which designates the display that frame is on), or @code{nil} (which -refers to the selected frame's display, @pxref{Input Focus}). - - @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to -obtain information about displays. - -@defun display-popup-menus-p &optional display -This function returns @code{t} if popup menus are supported on -@var{display}, @code{nil} if not. Support for popup menus requires -that the mouse be available, since the menu is popped up by clicking -the mouse on some portion of the Emacs display. -@end defun - -@defun display-graphic-p &optional display -This function returns @code{t} if @var{display} is a graphic display -capable of displaying several frames and several different fonts at -once. This is true for displays that use a window system such as X, -and false for text terminals. -@end defun - -@defun display-mouse-p &optional display -@cindex mouse, availability -This function returns @code{t} if @var{display} has a mouse available, -@code{nil} if not. -@end defun - -@defun display-color-p &optional display -@findex x-display-color-p -This function returns @code{t} if the screen is a color screen. -It used to be called @code{x-display-color-p}, and that name -is still supported as an alias. -@end defun - -@defun display-grayscale-p &optional display -This function returns @code{t} if the screen can display shades of gray. -(All color displays can do this.) -@end defun - -@defun display-supports-face-attributes-p attributes &optional display -@anchor{Display Face Attribute Testing} -This function returns non-@code{nil} if all the face attributes in -@var{attributes} are supported (@pxref{Face Attributes}). - -The definition of `supported' is somewhat heuristic, but basically -means that a face containing all the attributes in @var{attributes}, -when merged with the default face for display, can be represented in a -way that's - -@enumerate -@item -different in appearance than the default face, and - -@item -`close in spirit' to what the attributes specify, if not exact. -@end enumerate - -Point (2) implies that a @code{:weight black} attribute will be -satisfied by any display that can display bold, as will -@code{:foreground "yellow"} as long as some yellowish color can be -displayed, but @code{:slant italic} will @emph{not} be satisfied by -the tty display code's automatic substitution of a `dim' face for -italic. -@end defun - -@defun display-selections-p &optional display -This function returns @code{t} if @var{display} supports selections. -Windowed displays normally support selections, but they may also be -supported in some other cases. -@end defun - -@defun display-images-p &optional display -This function returns @code{t} if @var{display} can display images. -Windowed displays ought in principle to handle images, but some -systems lack the support for that. On a display that does not support -images, Emacs cannot display a tool bar. -@end defun - -@defun display-screens &optional display -This function returns the number of screens associated with the display. -@end defun - -@defun display-pixel-height &optional display -This function returns the height of the screen in pixels. -On a character terminal, it gives the height in characters. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the pixel height for all physical monitors associated with -@var{display}. @xref{Multiple Terminals}. -@end defun - -@defun display-pixel-width &optional display -This function returns the width of the screen in pixels. -On a character terminal, it gives the width in characters. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the pixel width for all physical monitors associated with -@var{display}. @xref{Multiple Terminals}. -@end defun - -@defun display-mm-height &optional display -This function returns the height of the screen in millimeters, -or @code{nil} if Emacs cannot get that information. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the height for all physical monitors associated with -@var{display}. @xref{Multiple Terminals}. -@end defun - -@defun display-mm-width &optional display -This function returns the width of the screen in millimeters, -or @code{nil} if Emacs cannot get that information. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the width for all physical monitors associated with -@var{display}. @xref{Multiple Terminals}. -@end defun - -@defopt display-mm-dimensions-alist -This variable allows the user to specify the dimensions of graphical -displays returned by @code{display-mm-height} and -@code{display-mm-width} in case the system provides incorrect values. -@end defopt - -@cindex backing store -@defun display-backing-store &optional display -This function returns the backing store capability of the display. -Backing store means recording the pixels of windows (and parts of -windows) that are not exposed, so that when exposed they can be -displayed very quickly. - -Values can be the symbols @code{always}, @code{when-mapped}, or -@code{not-useful}. The function can also return @code{nil} -when the question is inapplicable to a certain kind of display. -@end defun - -@cindex SaveUnder feature -@defun display-save-under &optional display -This function returns non-@code{nil} if the display supports the -SaveUnder feature. That feature is used by pop-up windows -to save the pixels they obscure, so that they can pop down -quickly. -@end defun - -@defun display-planes &optional display -This function returns the number of planes the display supports. -This is typically the number of bits per pixel. -For a tty display, it is log to base two of the number of colors supported. -@end defun - -@defun display-visual-class &optional display -This function returns the visual class for the screen. The value is -one of the symbols @code{static-gray} (a limited, unchangeable number -of grays), @code{gray-scale} (a full range of grays), -@code{static-color} (a limited, unchangeable number of colors), -@code{pseudo-color} (a limited number of colors), @code{true-color} (a -full range of colors), and @code{direct-color} (a full range of -colors). -@end defun - -@defun display-color-cells &optional display -This function returns the number of color cells the screen supports. -@end defun - - These functions obtain additional information specifically -about X displays. - -@defun x-server-version &optional display -This function returns the list of version numbers of the X server -running the display. The value is a list of three integers: the major -and minor version numbers of the X protocol, and the -distributor-specific release number of the X server software itself. -@end defun - -@defun x-server-vendor &optional display -This function returns the ``vendor'' that provided the X server -software (as a string). Really this means whoever distributes the X -server. - -When the developers of X labeled software distributors as -``vendors'', they showed their false assumption that no system could -ever be developed and distributed noncommercially. -@end defun - -@ignore -@defvar x-no-window-manager -This variable's value is @code{t} if no X window manager is in use. -@end defvar -@end ignore - -@ignore -@item -The functions @code{x-pixel-width} and @code{x-pixel-height} return the -width and height of an X Window frame, measured in pixels. -@end ignore diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi deleted file mode 100644 index f551a6c749d..00000000000 --- a/doc/lispref/functions.texi +++ /dev/null @@ -1,2022 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Functions -@chapter Functions - - A Lisp program is composed mainly of Lisp functions. This chapter -explains what functions are, how they accept arguments, and how to -define them. - -@menu -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Closures:: Functions that enclose a lexical environment. -* Advising Functions:: Adding to the definition of a function. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Functions that the compiler will expand inline. -* Declare Form:: Adding additional information about a function. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how functions work. -@end menu - -@node What Is a Function -@section What Is a Function? - -@cindex return value -@cindex value of function -@cindex argument - In a general sense, a function is a rule for carrying out a -computation given input values called @dfn{arguments}. The result of -the computation is called the @dfn{value} or @dfn{return value} of the -function. The computation can also have side effects, such as lasting -changes in the values of variables or the contents of data structures. - - In most computer languages, every function has a name. But in Lisp, -a function in the strictest sense has no name: it is an object which -can @emph{optionally} be associated with a symbol (e.g., @code{car}) -that serves as the function name. @xref{Function Names}. When a -function has been given a name, we usually also refer to that symbol -as a ``function'' (e.g., we refer to ``the function @code{car}''). -In this manual, the distinction between a function name and the -function object itself is usually unimportant, but we will take note -wherever it is relevant. - - Certain function-like objects, called @dfn{special forms} and -@dfn{macros}, also accept arguments to carry out computations. -However, as explained below, these are not considered functions in -Emacs Lisp. - - Here are important terms for functions and function-like objects: - -@table @dfn -@item lambda expression -A function (in the strict sense, i.e., a function object) which is -written in Lisp. These are described in the following section. -@ifnottex -@xref{Lambda Expressions}. -@end ifnottex - -@item primitive -@cindex primitive -@cindex subr -@cindex built-in function -A function which is callable from Lisp but is actually written in C@. -Primitives are also called @dfn{built-in functions}, or @dfn{subrs}. -Examples include functions like @code{car} and @code{append}. In -addition, all special forms (see below) are also considered -primitives. - -Usually, a function is implemented as a primitive because it is a -fundamental part of Lisp (e.g., @code{car}), or because it provides a -low-level interface to operating system services, or because it needs -to run fast. Unlike functions defined in Lisp, primitives can be -modified or added only by changing the C sources and recompiling -Emacs. See @ref{Writing Emacs Primitives}. - -@item special form -A primitive that is like a function but does not evaluate all of its -arguments in the usual way. It may evaluate only some of the -arguments, or may evaluate them in an unusual order, or several times. -Examples include @code{if}, @code{and}, and @code{while}. -@xref{Special Forms}. - -@item macro -@cindex macro -A construct defined in Lisp, which differs from a function in that it -translates a Lisp expression into another expression which is to be -evaluated instead of the original expression. Macros enable Lisp -programmers to do the sorts of things that special forms can do. -@xref{Macros}. - -@item command -@cindex command -An object which can be invoked via the @code{command-execute} -primitive, usually due to the user typing in a key sequence -@dfn{bound} to that command. @xref{Interactive Call}. A command is -usually a function; if the function is written in Lisp, it is made -into a command by an @code{interactive} form in the function -definition (@pxref{Defining Commands}). Commands that are functions -can also be called from Lisp expressions, just like other functions. - -Keyboard macros (strings and vectors) are commands also, even though -they are not functions. @xref{Keyboard Macros}. We say that a symbol -is a command if its function cell contains a command (@pxref{Symbol -Components}); such a @dfn{named command} can be invoked with -@kbd{M-x}. - -@item closure -A function object that is much like a lambda expression, except that -it also encloses an ``environment'' of lexical variable bindings. -@xref{Closures}. - -@item byte-code function -A function that has been compiled by the byte compiler. -@xref{Byte-Code Type}. - -@item autoload object -@cindex autoload object -A place-holder for a real function. If the autoload object is called, -Emacs loads the file containing the definition of the real function, -and then calls the real function. @xref{Autoload}. -@end table - - You can use the function @code{functionp} to test if an object is a -function: - -@defun functionp object -This function returns @code{t} if @var{object} is any kind of -function, i.e., can be passed to @code{funcall}. Note that -@code{functionp} returns @code{t} for symbols that are function names, -and returns @code{nil} for special forms. -@end defun - -@noindent -Unlike @code{functionp}, the next three functions do @emph{not} treat -a symbol as its function definition. - -@defun subrp object -This function returns @code{t} if @var{object} is a built-in function -(i.e., a Lisp primitive). - -@example -@group -(subrp 'message) ; @r{@code{message} is a symbol,} - @result{} nil ; @r{not a subr object.} -@end group -@group -(subrp (symbol-function 'message)) - @result{} t -@end group -@end example -@end defun - -@defun byte-code-function-p object -This function returns @code{t} if @var{object} is a byte-code -function. For example: - -@example -@group -(byte-code-function-p (symbol-function 'next-line)) - @result{} t -@end group -@end example -@end defun - -@defun subr-arity subr -This function provides information about the argument list of a -primitive, @var{subr}. The returned value is a pair -@code{(@var{min} . @var{max})}. @var{min} is the minimum number of -args. @var{max} is the maximum number or the symbol @code{many}, for a -function with @code{&rest} arguments, or the symbol @code{unevalled} if -@var{subr} is a special form. -@end defun - -@node Lambda Expressions -@section Lambda Expressions -@cindex lambda expression - - A lambda expression is a function object written in Lisp. Here is -an example: - -@example -(lambda (x) - "Return the hyperbolic cosine of X." - (* 0.5 (+ (exp x) (exp (- x))))) -@end example - -@noindent -In Emacs Lisp, such a list is a valid expression which evaluates to -a function object. - - A lambda expression, by itself, has no name; it is an @dfn{anonymous -function}. Although lambda expressions can be used this way -(@pxref{Anonymous Functions}), they are more commonly associated with -symbols to make @dfn{named functions} (@pxref{Function Names}). -Before going into these details, the following subsections describe -the components of a lambda expression and what they do. - -@menu -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. -@end menu - -@node Lambda Components -@subsection Components of a Lambda Expression - - A lambda expression is a list that looks like this: - -@example -(lambda (@var{arg-variables}@dots{}) - [@var{documentation-string}] - [@var{interactive-declaration}] - @var{body-forms}@dots{}) -@end example - -@cindex lambda list - The first element of a lambda expression is always the symbol -@code{lambda}. This indicates that the list represents a function. The -reason functions are defined to start with @code{lambda} is so that -other lists, intended for other uses, will not accidentally be valid as -functions. - - The second element is a list of symbols---the argument variable names. -This is called the @dfn{lambda list}. When a Lisp function is called, -the argument values are matched up against the variables in the lambda -list, which are given local bindings with the values provided. -@xref{Local Variables}. - - The documentation string is a Lisp string object placed within the -function definition to describe the function for the Emacs help -facilities. @xref{Function Documentation}. - - The interactive declaration is a list of the form @code{(interactive -@var{code-string})}. This declares how to provide arguments if the -function is used interactively. Functions with this declaration are called -@dfn{commands}; they can be called using @kbd{M-x} or bound to a key. -Functions not intended to be called in this way should not have interactive -declarations. @xref{Defining Commands}, for how to write an interactive -declaration. - -@cindex body of function - The rest of the elements are the @dfn{body} of the function: the Lisp -code to do the work of the function (or, as a Lisp programmer would say, -``a list of Lisp forms to evaluate''). The value returned by the -function is the value returned by the last element of the body. - -@node Simple Lambda -@subsection A Simple Lambda Expression Example - - Consider the following example: - -@example -(lambda (a b c) (+ a b c)) -@end example - -@noindent -We can call this function by passing it to @code{funcall}, like this: - -@example -@group -(funcall (lambda (a b c) (+ a b c)) - 1 2 3) -@end group -@end example - -@noindent -This call evaluates the body of the lambda expression with the variable -@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3. -Evaluation of the body adds these three numbers, producing the result 6; -therefore, this call to the function returns the value 6. - - Note that the arguments can be the results of other function calls, as in -this example: - -@example -@group -(funcall (lambda (a b c) (+ a b c)) - 1 (* 2 3) (- 5 4)) -@end group -@end example - -@noindent -This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5 -4)} from left to right. Then it applies the lambda expression to the -argument values 1, 6 and 1 to produce the value 8. - - As these examples show, you can use a form with a lambda expression -as its @sc{car} to make local variables and give them values. In the -old days of Lisp, this technique was the only way to bind and -initialize local variables. But nowadays, it is clearer to use the -special form @code{let} for this purpose (@pxref{Local Variables}). -Lambda expressions are mainly used as anonymous functions for passing -as arguments to other functions (@pxref{Anonymous Functions}), or -stored as symbol function definitions to produce named functions -(@pxref{Function Names}). - -@node Argument List -@subsection Other Features of Argument Lists -@kindex wrong-number-of-arguments -@cindex argument binding -@cindex binding arguments -@cindex argument lists, features - - Our simple sample function, @code{(lambda (a b c) (+ a b c))}, -specifies three argument variables, so it must be called with three -arguments: if you try to call it with only two arguments or four -arguments, you get a @code{wrong-number-of-arguments} error. - - It is often convenient to write a function that allows certain -arguments to be omitted. For example, the function @code{substring} -accepts three arguments---a string, the start index and the end -index---but the third argument defaults to the @var{length} of the -string if you omit it. It is also convenient for certain functions to -accept an indefinite number of arguments, as the functions @code{list} -and @code{+} do. - -@cindex optional arguments -@cindex rest arguments -@kindex &optional -@kindex &rest - To specify optional arguments that may be omitted when a function -is called, simply include the keyword @code{&optional} before the optional -arguments. To specify a list of zero or more extra arguments, include the -keyword @code{&rest} before one final argument. - - Thus, the complete syntax for an argument list is as follows: - -@example -@group -(@var{required-vars}@dots{} - @r{[}&optional @var{optional-vars}@dots{}@r{]} - @r{[}&rest @var{rest-var}@r{]}) -@end group -@end example - -@noindent -The square brackets indicate that the @code{&optional} and @code{&rest} -clauses, and the variables that follow them, are optional. - - A call to the function requires one actual argument for each of the -@var{required-vars}. There may be actual arguments for zero or more of -the @var{optional-vars}, and there cannot be any actual arguments beyond -that unless the lambda list uses @code{&rest}. In that case, there may -be any number of extra actual arguments. - - If actual arguments for the optional and rest variables are omitted, -then they always default to @code{nil}. There is no way for the -function to distinguish between an explicit argument of @code{nil} and -an omitted argument. However, the body of the function is free to -consider @code{nil} an abbreviation for some other meaningful value. -This is what @code{substring} does; @code{nil} as the third argument to -@code{substring} means to use the length of the string supplied. - -@cindex CL note---default optional arg -@quotation -@b{Common Lisp note:} Common Lisp allows the function to specify what -default value to use when an optional argument is omitted; Emacs Lisp -always uses @code{nil}. Emacs Lisp does not support ``supplied-p'' -variables that tell you whether an argument was explicitly passed. -@end quotation - - For example, an argument list that looks like this: - -@example -(a b &optional c d &rest e) -@end example - -@noindent -binds @code{a} and @code{b} to the first two actual arguments, which are -required. If one or two more arguments are provided, @code{c} and -@code{d} are bound to them respectively; any arguments after the first -four are collected into a list and @code{e} is bound to that list. If -there are only two arguments, @code{c} is @code{nil}; if two or three -arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e} -is @code{nil}. - - There is no way to have required arguments following optional -ones---it would not make sense. To see why this must be so, suppose -that @code{c} in the example were optional and @code{d} were required. -Suppose three actual arguments are given; which variable would the -third argument be for? Would it be used for the @var{c}, or for -@var{d}? One can argue for both possibilities. Similarly, it makes -no sense to have any more arguments (either required or optional) -after a @code{&rest} argument. - - Here are some examples of argument lists and proper calls: - -@example -(funcall (lambda (n) (1+ n)) ; @r{One required:} - 1) ; @r{requires exactly one argument.} - @result{} 2 -(funcall (lambda (n &optional n1) ; @r{One required and one optional:} - (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.} - 1 2) - @result{} 3 -(funcall (lambda (n &rest ns) ; @r{One required and one rest:} - (+ n (apply '+ ns))) ; @r{1 or more arguments.} - 1 2 3 4 5) - @result{} 15 -@end example - -@node Function Documentation -@subsection Documentation Strings of Functions -@cindex documentation of function - - A lambda expression may optionally have a @dfn{documentation string} -just after the lambda list. This string does not affect execution of -the function; it is a kind of comment, but a systematized comment -which actually appears inside the Lisp world and can be used by the -Emacs help facilities. @xref{Documentation}, for how the -documentation string is accessed. - - It is a good idea to provide documentation strings for all the -functions in your program, even those that are called only from within -your program. Documentation strings are like comments, except that they -are easier to access. - - The first line of the documentation string should stand on its own, -because @code{apropos} displays just this first line. It should consist -of one or two complete sentences that summarize the function's purpose. - - The start of the documentation string is usually indented in the -source file, but since these spaces come before the starting -double-quote, they are not part of the string. Some people make a -practice of indenting any additional lines of the string so that the -text lines up in the program source. @emph{That is a mistake.} The -indentation of the following lines is inside the string; what looks -nice in the source code will look ugly when displayed by the help -commands. - - You may wonder how the documentation string could be optional, since -there are required components of the function that follow it (the body). -Since evaluation of a string returns that string, without any side effects, -it has no effect if it is not the last form in the body. Thus, in -practice, there is no confusion between the first form of the body and the -documentation string; if the only body form is a string then it serves both -as the return value and as the documentation. - - The last line of the documentation string can specify calling -conventions different from the actual function arguments. Write -text like this: - -@example -\(fn @var{arglist}) -@end example - -@noindent -following a blank line, at the beginning of the line, with no newline -following it inside the documentation string. (The @samp{\} is used -to avoid confusing the Emacs motion commands.) The calling convention -specified in this way appears in help messages in place of the one -derived from the actual arguments of the function. - - This feature is particularly useful for macro definitions, since the -arguments written in a macro definition often do not correspond to the -way users think of the parts of the macro call. - -@node Function Names -@section Naming a Function -@cindex function definition -@cindex named function -@cindex function name - - A symbol can serve as the name of a function. This happens when the -symbol's @dfn{function cell} (@pxref{Symbol Components}) contains a -function object (e.g., a lambda expression). Then the symbol itself -becomes a valid, callable function, equivalent to the function object -in its function cell. - - The contents of the function cell are also called the symbol's -@dfn{function definition}. The procedure of using a symbol's function -definition in place of the symbol is called @dfn{symbol function -indirection}; see @ref{Function Indirection}. If you have not given a -symbol a function definition, its function cell is said to be -@dfn{void}, and it cannot be used as a function. - - In practice, nearly all functions have names, and are referred to by -their names. You can create a named Lisp function by defining a -lambda expression and putting it in a function cell (@pxref{Function -Cells}). However, it is more common to use the @code{defun} special -form, described in the next section. -@ifnottex -@xref{Defining Functions}. -@end ifnottex - - We give functions names because it is convenient to refer to them by -their names in Lisp expressions. Also, a named Lisp function can -easily refer to itself---it can be recursive. Furthermore, primitives -can only be referred to textually by their names, since primitive -function objects (@pxref{Primitive Function Type}) have no read -syntax. - - A function need not have a unique name. A given function object -@emph{usually} appears in the function cell of only one symbol, but -this is just a convention. It is easy to store it in several symbols -using @code{fset}; then each of the symbols is a valid name for the -same function. - - Note that a symbol used as a function name may also be used as a -variable; these two uses of a symbol are independent and do not -conflict. (This is not the case in some dialects of Lisp, like -Scheme.) - -@node Defining Functions -@section Defining Functions -@cindex defining a function - - We usually give a name to a function when it is first created. This -is called @dfn{defining a function}, and it is done with the -@code{defun} macro. - -@defmac defun name args [doc] [declare] [interactive] body@dots{} -@code{defun} is the usual way to define new Lisp functions. It -defines the symbol @var{name} as a function with argument list -@var{args} and body forms given by @var{body}. Neither @var{name} nor -@var{args} should be quoted. - -@var{doc}, if present, should be a string specifying the function's -documentation string (@pxref{Function Documentation}). @var{declare}, -if present, should be a @code{declare} form specifying function -metadata (@pxref{Declare Form}). @var{interactive}, if present, -should be an @code{interactive} form specifying how the function is to -be called interactively (@pxref{Interactive Call}). - -The return value of @code{defun} is undefined. - -Here are some examples: - -@example -@group -(defun foo () 5) -(foo) - @result{} 5 -@end group - -@group -(defun bar (a &optional b &rest c) - (list a b c)) -(bar 1 2 3 4 5) - @result{} (1 2 (3 4 5)) -@end group -@group -(bar 1) - @result{} (1 nil nil) -@end group -@group -(bar) -@error{} Wrong number of arguments. -@end group - -@group -(defun capitalize-backwards () - "Upcase the last letter of the word at point." - (interactive) - (backward-word 1) - (forward-word 1) - (backward-char 1) - (capitalize-word 1)) -@end group -@end example - -Be careful not to redefine existing functions unintentionally. -@code{defun} redefines even primitive functions such as @code{car} -without any hesitation or notification. Emacs does not prevent you -from doing this, because redefining a function is sometimes done -deliberately, and there is no way to distinguish deliberate -redefinition from unintentional redefinition. -@end defmac - -@cindex function aliases -@cindex alias, for functions -@defun defalias name definition &optional doc -@anchor{Definition of defalias} -This function defines the symbol @var{name} as a function, with -definition @var{definition} (which can be any valid Lisp function). -Its return value is @emph{undefined}. - -If @var{doc} is non-@code{nil}, it becomes the function documentation -of @var{name}. Otherwise, any documentation provided by -@var{definition} is used. - -@cindex defalias-fset-function property -Internally, @code{defalias} normally uses @code{fset} to set the definition. -If @var{name} has a @code{defalias-fset-function} property, however, -the associated value is used as a function to call in place of @code{fset}. - -The proper place to use @code{defalias} is where a specific function -name is being defined---especially where that name appears explicitly in -the source file being loaded. This is because @code{defalias} records -which file defined the function, just like @code{defun} -(@pxref{Unloading}). - -By contrast, in programs that manipulate function definitions for other -purposes, it is better to use @code{fset}, which does not keep such -records. @xref{Function Cells}. -@end defun - - You cannot create a new primitive function with @code{defun} or -@code{defalias}, but you can use them to change the function definition of -any symbol, even one such as @code{car} or @code{x-popup-menu} whose -normal definition is a primitive. However, this is risky: for -instance, it is next to impossible to redefine @code{car} without -breaking Lisp completely. Redefining an obscure function such as -@code{x-popup-menu} is less dangerous, but it still may not work as -you expect. If there are calls to the primitive from C code, they -call the primitive's C definition directly, so changing the symbol's -definition will have no effect on them. - - See also @code{defsubst}, which defines a function like @code{defun} -and tells the Lisp compiler to perform inline expansion on it. -@xref{Inline Functions}. - -@node Calling Functions -@section Calling Functions -@cindex function invocation -@cindex calling a function - - Defining functions is only half the battle. Functions don't do -anything until you @dfn{call} them, i.e., tell them to run. Calling a -function is also known as @dfn{invocation}. - - The most common way of invoking a function is by evaluating a list. -For example, evaluating the list @code{(concat "a" "b")} calls the -function @code{concat} with arguments @code{"a"} and @code{"b"}. -@xref{Evaluation}, for a description of evaluation. - - When you write a list as an expression in your program, you specify -which function to call, and how many arguments to give it, in the text -of the program. Usually that's just what you want. Occasionally you -need to compute at run time which function to call. To do that, use -the function @code{funcall}. When you also need to determine at run -time how many arguments to pass, use @code{apply}. - -@defun funcall function &rest arguments -@code{funcall} calls @var{function} with @var{arguments}, and returns -whatever @var{function} returns. - -Since @code{funcall} is a function, all of its arguments, including -@var{function}, are evaluated before @code{funcall} is called. This -means that you can use any expression to obtain the function to be -called. It also means that @code{funcall} does not see the -expressions you write for the @var{arguments}, only their values. -These values are @emph{not} evaluated a second time in the act of -calling @var{function}; the operation of @code{funcall} is like the -normal procedure for calling a function, once its arguments have -already been evaluated. - -The argument @var{function} must be either a Lisp function or a -primitive function. Special forms and macros are not allowed, because -they make sense only when given the ``unevaluated'' argument -expressions. @code{funcall} cannot provide these because, as we saw -above, it never knows them in the first place. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(funcall f 'x 'y 'z) - @result{} (x y z) -@end group -@group -(funcall f 'x 'y '(z)) - @result{} (x y (z)) -@end group -@group -(funcall 'and t nil) -@error{} Invalid function: # -@end group -@end example - -Compare these examples with the examples of @code{apply}. -@end defun - -@defun apply function &rest arguments -@code{apply} calls @var{function} with @var{arguments}, just like -@code{funcall} but with one difference: the last of @var{arguments} is a -list of objects, which are passed to @var{function} as separate -arguments, rather than a single list. We say that @code{apply} -@dfn{spreads} this list so that each individual element becomes an -argument. - -@code{apply} returns the result of calling @var{function}. As with -@code{funcall}, @var{function} must either be a Lisp function or a -primitive function; special forms and macros do not make sense in -@code{apply}. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(apply f 'x 'y 'z) -@error{} Wrong type argument: listp, z -@end group -@group -(apply '+ 1 2 '(3 4)) - @result{} 10 -@end group -@group -(apply '+ '(1 2 3 4)) - @result{} 10 -@end group - -@group -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end group -@end example - -For an interesting example of using @code{apply}, see @ref{Definition -of mapcar}. -@end defun - -@cindex partial application of functions -@cindex currying - Sometimes it is useful to fix some of the function's arguments at -certain values, and leave the rest of arguments for when the function -is actually called. The act of fixing some of the function's -arguments is called @dfn{partial application} of the function@footnote{ -This is related to, but different from @dfn{currying}, which -transforms a function that takes multiple arguments in such a way that -it can be called as a chain of functions, each one with a single -argument.}. -The result is a new function that accepts the rest of -arguments and calls the original function with all the arguments -combined. - - Here's how to do partial application in Emacs Lisp: - -@defun apply-partially func &rest args -This function returns a new function which, when called, will call -@var{func} with the list of arguments composed from @var{args} and -additional arguments specified at the time of the call. If @var{func} -accepts @var{n} arguments, then a call to @code{apply-partially} with -@w{@code{@var{m} < @var{n}}} arguments will produce a new function of -@w{@code{@var{n} - @var{m}}} arguments. - -Here's how we could define the built-in function @code{1+}, if it -didn't exist, using @code{apply-partially} and @code{+}, another -built-in function: - -@example -@group -(defalias '1+ (apply-partially '+ 1) - "Increment argument by one.") -@end group -@group -(1+ 10) - @result{} 11 -@end group -@end example -@end defun - -@cindex functionals - It is common for Lisp functions to accept functions as arguments or -find them in data structures (especially in hook variables and property -lists) and call them using @code{funcall} or @code{apply}. Functions -that accept function arguments are often called @dfn{functionals}. - - Sometimes, when you call a functional, it is useful to supply a no-op -function as the argument. Here are two different kinds of no-op -function: - -@defun identity arg -This function returns @var{arg} and has no side effects. -@end defun - -@defun ignore &rest args -This function ignores any arguments and returns @code{nil}. -@end defun - - Some functions are user-visible @dfn{commands}, which can be called -interactively (usually by a key sequence). It is possible to invoke -such a command exactly as though it was called interactively, by using -the @code{call-interactively} function. @xref{Interactive Call}. - -@node Mapping Functions -@section Mapping Functions -@cindex mapping functions - - A @dfn{mapping function} applies a given function (@emph{not} a -special form or macro) to each element of a list or other collection. -Emacs Lisp has several such functions; this section describes -@code{mapcar}, @code{mapc}, and @code{mapconcat}, which map over a -list. @xref{Definition of mapatoms}, for the function @code{mapatoms} -which maps over the symbols in an obarray. @xref{Definition of -maphash}, for the function @code{maphash} which maps over key/value -associations in a hash table. - - These mapping functions do not allow char-tables because a char-table -is a sparse array whose nominal range of indices is very large. To map -over a char-table in a way that deals properly with its sparse nature, -use the function @code{map-char-table} (@pxref{Char-Tables}). - -@defun mapcar function sequence -@anchor{Definition of mapcar} -@code{mapcar} applies @var{function} to each element of @var{sequence} -in turn, and returns a list of the results. - -The argument @var{sequence} can be any kind of sequence except a -char-table; that is, a list, a vector, a bool-vector, or a string. The -result is always a list. The length of the result is the same as the -length of @var{sequence}. For example: - -@example -@group -(mapcar 'car '((a b) (c d) (e f))) - @result{} (a c e) -(mapcar '1+ [1 2 3]) - @result{} (2 3 4) -(mapcar 'string "abc") - @result{} ("a" "b" "c") -@end group - -@group -;; @r{Call each function in @code{my-hooks}.} -(mapcar 'funcall my-hooks) -@end group - -@group -(defun mapcar* (function &rest args) - "Apply FUNCTION to successive cars of all ARGS. -Return the list of results." - ;; @r{If no list is exhausted,} - (if (not (memq nil args)) - ;; @r{apply function to @sc{car}s.} - (cons (apply function (mapcar 'car args)) - (apply 'mapcar* function - ;; @r{Recurse for rest of elements.} - (mapcar 'cdr args))))) -@end group - -@group -(mapcar* 'cons '(a b c) '(1 2 3 4)) - @result{} ((a . 1) (b . 2) (c . 3)) -@end group -@end example -@end defun - -@defun mapc function sequence -@code{mapc} is like @code{mapcar} except that @var{function} is used for -side-effects only---the values it returns are ignored, not collected -into a list. @code{mapc} always returns @var{sequence}. -@end defun - -@defun mapconcat function sequence separator -@code{mapconcat} applies @var{function} to each element of -@var{sequence}: the results, which must be strings, are concatenated. -Between each pair of result strings, @code{mapconcat} inserts the string -@var{separator}. Usually @var{separator} contains a space or comma or -other suitable punctuation. - -The argument @var{function} must be a function that can take one -argument and return a string. The argument @var{sequence} can be any -kind of sequence except a char-table; that is, a list, a vector, a -bool-vector, or a string. - -@example -@group -(mapconcat 'symbol-name - '(The cat in the hat) - " ") - @result{} "The cat in the hat" -@end group - -@group -(mapconcat (function (lambda (x) (format "%c" (1+ x)))) - "HAL-8000" - "") - @result{} "IBM.9111" -@end group -@end example -@end defun - -@node Anonymous Functions -@section Anonymous Functions -@cindex anonymous function - - Although functions are usually defined with @code{defun} and given -names at the same time, it is sometimes convenient to use an explicit -lambda expression---an @dfn{anonymous function}. Anonymous functions -are valid wherever function names are. They are often assigned as -variable values, or as arguments to functions; for instance, you might -pass one as the @var{function} argument to @code{mapcar}, which -applies that function to each element of a list (@pxref{Mapping -Functions}). @xref{describe-symbols example}, for a realistic example -of this. - - When defining a lambda expression that is to be used as an anonymous -function, you can in principle use any method to construct the list. -But typically you should use the @code{lambda} macro, or the -@code{function} special form, or the @code{#'} read syntax: - -@defmac lambda args [doc] [interactive] body@dots{} -This macro returns an anonymous function with argument list -@var{args}, documentation string @var{doc} (if any), interactive spec -@var{interactive} (if any), and body forms given by @var{body}. - -In effect, this macro makes @code{lambda} forms ``self-quoting'': -evaluating a form whose @sc{car} is @code{lambda} yields the form -itself: - -@example -(lambda (x) (* x x)) - @result{} (lambda (x) (* x x)) -@end example - -The @code{lambda} form has one other effect: it tells the Emacs -evaluator and byte-compiler that its argument is a function, by using -@code{function} as a subroutine (see below). -@end defmac - -@defspec function function-object -@cindex function quoting -This special form returns @var{function-object} without evaluating it. -In this, it is similar to @code{quote} (@pxref{Quoting}). But unlike -@code{quote}, it also serves as a note to the Emacs evaluator and -byte-compiler that @var{function-object} is intended to be used as a -function. Assuming @var{function-object} is a valid lambda -expression, this has two effects: - -@itemize -@item -When the code is byte-compiled, @var{function-object} is compiled into -a byte-code function object (@pxref{Byte Compilation}). - -@item -When lexical binding is enabled, @var{function-object} is converted -into a closure. @xref{Closures}. -@end itemize -@end defspec - -@cindex @samp{#'} syntax -The read syntax @code{#'} is a short-hand for using @code{function}. -The following forms are all equivalent: - -@example -(lambda (x) (* x x)) -(function (lambda (x) (* x x))) -#'(lambda (x) (* x x)) -@end example - - In the following example, we define a @code{change-property} -function that takes a function as its third argument, followed by a -@code{double-property} function that makes use of -@code{change-property} by passing it an anonymous function: - -@example -@group -(defun change-property (symbol prop function) - (let ((value (get symbol prop))) - (put symbol prop (funcall function value)))) -@end group - -@group -(defun double-property (symbol prop) - (change-property symbol prop (lambda (x) (* 2 x)))) -@end group -@end example - -@noindent -Note that we do not quote the @code{lambda} form. - - If you compile the above code, the anonymous function is also -compiled. This would not happen if, say, you had constructed the -anonymous function by quoting it as a list: - -@c Do not unquote this lambda! -@example -@group -(defun double-property (symbol prop) - (change-property symbol prop '(lambda (x) (* 2 x)))) -@end group -@end example - -@noindent -In that case, the anonymous function is kept as a lambda expression in -the compiled code. The byte-compiler cannot assume this list is a -function, even though it looks like one, since it does not know that -@code{change-property} intends to use it as a function. - -@node Function Cells -@section Accessing Function Cell Contents - - The @dfn{function definition} of a symbol is the object stored in the -function cell of the symbol. The functions described here access, test, -and set the function cell of symbols. - - See also the function @code{indirect-function}. @xref{Definition of -indirect-function}. - -@defun symbol-function symbol -@kindex void-function -This returns the object in the function cell of @var{symbol}. It does -not check that the returned object is a legitimate function. - -If the function cell is void, the return value is @code{nil}. To -distinguish between a function cell that is void and one set to -@code{nil}, use @code{fboundp} (see below). - -@example -@group -(defun bar (n) (+ n 2)) -(symbol-function 'bar) - @result{} (lambda (n) (+ n 2)) -@end group -@group -(fset 'baz 'bar) - @result{} bar -@end group -@group -(symbol-function 'baz) - @result{} bar -@end group -@end example -@end defun - -@cindex void function cell - If you have never given a symbol any function definition, we say -that that symbol's function cell is @dfn{void}. In other words, the -function cell does not have any Lisp object in it. If you try to call -the symbol as a function, Emacs signals a @code{void-function} error. - - Note that void is not the same as @code{nil} or the symbol -@code{void}. The symbols @code{nil} and @code{void} are Lisp objects, -and can be stored into a function cell just as any other object can be -(and they can be valid functions if you define them in turn with -@code{defun}). A void function cell contains no object whatsoever. - - You can test the voidness of a symbol's function definition with -@code{fboundp}. After you have given a symbol a function definition, you -can make it void once more using @code{fmakunbound}. - -@defun fboundp symbol -This function returns @code{t} if the symbol has an object in its -function cell, @code{nil} otherwise. It does not check that the object -is a legitimate function. -@end defun - -@defun fmakunbound symbol -This function makes @var{symbol}'s function cell void, so that a -subsequent attempt to access this cell will cause a -@code{void-function} error. It returns @var{symbol}. (See also -@code{makunbound}, in @ref{Void Variables}.) - -@example -@group -(defun foo (x) x) -(foo 1) - @result{}1 -@end group -@group -(fmakunbound 'foo) - @result{} foo -@end group -@group -(foo 1) -@error{} Symbol's function definition is void: foo -@end group -@end example -@end defun - -@defun fset symbol definition -This function stores @var{definition} in the function cell of -@var{symbol}. The result is @var{definition}. Normally -@var{definition} should be a function or the name of a function, but -this is not checked. The argument @var{symbol} is an ordinary evaluated -argument. - -The primary use of this function is as a subroutine by constructs that define -or alter functions, like @code{defun} or @code{advice-add} (@pxref{Advising -Functions}). You can also use it to give a symbol a function definition that -is not a function, e.g., a keyboard macro (@pxref{Keyboard Macros}): - -@example -;; @r{Define a named keyboard macro.} -(fset 'kill-two-lines "\^u2\^k") - @result{} "\^u2\^k" -@end example - -It you wish to use @code{fset} to make an alternate name for a -function, consider using @code{defalias} instead. @xref{Definition of -defalias}. -@end defun - -@node Closures -@section Closures - - As explained in @ref{Variable Scoping}, Emacs can optionally enable -lexical binding of variables. When lexical binding is enabled, any -named function that you create (e.g., with @code{defun}), as well as -any anonymous function that you create using the @code{lambda} macro -or the @code{function} special form or the @code{#'} syntax -(@pxref{Anonymous Functions}), is automatically converted into a -@dfn{closure}. - -@cindex closure - A closure is a function that also carries a record of the lexical -environment that existed when the function was defined. When it is -invoked, any lexical variable references within its definition use the -retained lexical environment. In all other respects, closures behave -much like ordinary functions; in particular, they can be called in the -same way as ordinary functions. - - @xref{Lexical Binding}, for an example of using a closure. - - Currently, an Emacs Lisp closure object is represented by a list -with the symbol @code{closure} as the first element, a list -representing the lexical environment as the second element, and the -argument list and body forms as the remaining elements: - -@example -;; @r{lexical binding is enabled.} -(lambda (x) (* x x)) - @result{} (closure (t) (x) (* x x)) -@end example - -@noindent -However, the fact that the internal structure of a closure is -``exposed'' to the rest of the Lisp world is considered an internal -implementation detail. For this reason, we recommend against directly -examining or altering the structure of closure objects. - -@node Advising Functions -@section Advising Emacs Lisp Functions -@cindex advising functions -@cindex piece of advice - -When you need to modify a function defined in another library, or when you need -to modify a hook like @code{@var{foo}-function}, a process filter, or basically -any variable or object field which holds a function value, you can use the -appropriate setter function, such as @code{fset} or @code{defun} for named -functions, @code{setq} for hook variables, or @code{set-process-filter} for -process filters, but those are often too blunt, completely throwing away the -previous value. - - The @dfn{advice} feature lets you add to the existing definition of -a function, by @dfn{advising the function}. This is a cleaner method -than redefining the whole function. - -Emacs's advice system provides two sets of primitives for that: the core set, -for function values held in variables and object fields (with the corresponding -primitives being @code{add-function} and @code{remove-function}) and another -set layered on top of it for named functions (with the main primitives being -@code{advice-add} and @code{advice-remove}). - -For example, in order to trace the calls to the process filter of a process -@var{proc}, you could use: - -@example -(defun my-tracing-function (proc string) - (message "Proc %S received %S" proc string)) - -(add-function :before (process-filter @var{proc}) #'my-tracing-function) -@end example - -This will cause the process's output to be passed to @code{my-tracing-function} -before being passed to the original process filter. @code{my-tracing-function} -receives the same arguments as the original function. When you're done with -it, you can revert to the untraced behavior with: - -@example -(remove-function (process-filter @var{proc}) #'my-tracing-function) -@end example - -Similarly, if you want to trace the execution of the function named -@code{display-buffer}, you could use: - -@example -(defun his-tracing-function (orig-fun &rest args) - (message "display-buffer called with args %S" args) - (let ((res (apply orig-fun args))) - (message "display-buffer returned %S" res) - res)) - -(advice-add 'display-buffer :around #'his-tracing-function) -@end example - -Here, @code{his-tracing-function} is called instead of the original function -and receives the original function (additionally to that function's arguments) -as argument, so it can call it if and when it needs to. -When you're tired of seeing this output, you can revert to the untraced -behavior with: - -@example -(advice-remove 'display-buffer #'his-tracing-function) -@end example - -The arguments @code{:before} and @code{:around} used in the above examples -specify how the two functions are composed, since there are many different -ways to do it. The added function is also called an @emph{advice}. - -@menu -* Core Advising Primitives:: Primitives to manipulate advice. -* Advising Named Functions:: Advising named functions. -* Advice combinators:: Ways to compose advices. -* Porting old advices:: Adapting code using the old defadvice. -@end menu - -@node Core Advising Primitives -@subsection Primitives to manipulate advices - -@defmac add-function where place function &optional props -This macro is the handy way to add the advice @var{function} to the function -stored in @var{place} (@pxref{Generalized Variables}). - -@var{where} determines how @var{function} is composed with the -existing function, e.g. whether @var{function} should be called before, or -after the original function. @xref{Advice combinators}, for the list of -available ways to compose the two functions. - -When modifying a variable (whose name will usually end with @code{-function}), -you can choose whether @var{function} is used globally or only in the current -buffer: if @var{place} is just a symbol, then @var{function} is added to the -global value of @var{place}. Whereas if @var{place} is of the form -@code{(local @var{symbol})}, where @var{symbol} is an expression which returns -the variable name, then @var{function} will only be added in the -current buffer. Finally, if you want to modify a lexical variable, you will -have to use @code{(var @var{variable})}. - -Every function added with @code{add-function} can be accompanied by an -association list of properties @var{props}. Currently only two of those -properties have a special meaning: - -@table @code -@item name -This gives a name to the advice, which @code{remove-function} can use to -identify which function to remove. Typically used when @var{function} is an -anonymous function. - -@item depth -This specifies how to order the advices, in case several advices are present. -By default, the depth is 0. A depth of 100 indicates that this advice should -be kept as deep as possible, whereas a depth of -100 indicates that it -should stay as the outermost advice. When two advices specify the same depth, -the most recently added advice will be outermost. - -For a @code{:before} advice, being outermost means that this advice will be run -first, before any other advice, whereas being innermost means that it will run -right before the original function, with no other advice run between itself and -the original function. Similarly, for an @code{:after} advice innermost means -that it will run right after the original function, with no other advice run in -between, whereas outermost means that it will be run very last after all -other advices. An innermost @code{:override} advice will only override the -original function and other advices will apply to it, whereas an outermost -@code{:override} advice will override not only the original function but all -other advices applied to it as well. -@end table - -If @var{function} is not interactive, then the combined function will inherit -the interactive spec, if any, of the original function. Else, the combined -function will be interactive and will use the interactive spec of -@var{function}. One exception: if the interactive spec of @var{function} -is a function (rather than an expression or a string), then the interactive -spec of the combined function will be a call to that function with as sole -argument the interactive spec of the original function. To interpret the spec -received as argument, use @code{advice-eval-interactive-spec}. - -Note: The interactive spec of @var{function} will apply to the combined -function and should hence obey the calling convention of the combined function -rather than that of @var{function}. In many cases, it makes no difference -since they are identical, but it does matter for @code{:around}, -@code{:filter-args}, and @code{filter-return}, where @var{function}. -@end defmac - -@defmac remove-function place function -This macro removes @var{function} from the function stored in -@var{place}. This only works if @var{function} was added to @var{place} -using @code{add-function}. - -@var{function} is compared with functions added to @var{place} using -@code{equal}, to try and make it work also with lambda expressions. It is -additionally compared also with the @code{name} property of the functions added -to @var{place}, which can be more reliable than comparing lambda expressions -using @code{equal}. -@end defmac - -@defun advice-function-member-p advice function-def -Return non-@code{nil} if @var{advice} is already in @var{function-def}. -Like for @code{remove-function} above, instead of @var{advice} being the actual -function, it can also be the @code{name} of the piece of advice. -@end defun - -@defun advice-function-mapc f function-def -Call the function @var{f} for every advice that was added to -@var{function-def}. @var{f} is called with two arguments: the advice function -and its properties. -@end defun - -@defun advice-eval-interactive-spec spec -Evaluate the interactive @var{spec} just like an interactive call to a function -with such a spec would, and then return the corresponding list of arguments -that was built. E.g. @code{(advice-eval-interactive-spec "r\nP")} will -return a list of three elements, containing the boundaries of the region and -the current prefix argument. -@end defun - -@node Advising Named Functions -@subsection Advising Named Functions - -A common use of advice is for named functions and macros. -You could just use @code{add-function} as in: - -@example -(add-function :around (symbol-function '@var{fun}) #'his-tracing-function) -@end example - - But you should use @code{advice-add} and @code{advice-remove} for that -instead. This separate set of functions to manipulate pieces of advice applied -to named functions, offers the following extra features compared to -@code{add-function}: they know how to deal with macros and autoloaded -functions, they let @code{describe-function} preserve the original docstring as -well as document the added advice, and they let you add and remove advices -before a function is even defined. - - @code{advice-add} can be useful for altering the behavior of existing calls -to an existing function without having to redefine the whole function. -However, it can be a source of bugs, since existing callers to the function may -assume the old behavior, and work incorrectly when the behavior is changed by -advice. Advice can also cause confusion in debugging, if the person doing the -debugging does not notice or remember that the function has been modified -by advice. - - For these reasons, advice should be reserved for the cases where you -cannot modify a function's behavior in any other way. If it is -possible to do the same thing via a hook, that is preferable -(@pxref{Hooks}). If you simply want to change what a particular key -does, it may be better to write a new command, and remap the old -command's key bindings to the new one (@pxref{Remapping Commands}). -In particular, Emacs's own source files should not put advice on -functions in Emacs. (There are currently a few exceptions to this -convention, but we aim to correct them.) - - Special forms (@pxref{Special Forms}) cannot be advised, however macros can -be advised, in much the same way as functions. Of course, this will not affect -code that has already been macro-expanded, so you need to make sure the advice -is installed before the macro is expanded. - - It is possible to advise a primitive (@pxref{What Is a Function}), -but one should typically @emph{not} do so, for two reasons. Firstly, -some primitives are used by the advice mechanism, and advising them -could cause an infinite recursion. Secondly, many primitives are -called directly from C, and such calls ignore advice; hence, one ends -up in a confusing situation where some calls (occurring from Lisp -code) obey the advice and other calls (from C code) do not. - -@defun advice-add symbol where function &optional props -Add the advice @var{function} to the named function @var{symbol}. -@var{where} and @var{props} have the same meaning as for @code{add-function} -(@pxref{Core Advising Primitives}). -@end defun - -@defun advice-remove symbol function -Remove the advice @var{function} from the named function @var{symbol}. -@var{function} can also be the @code{name} of an advice. -@end defun - -@defun advice-member-p function symbol -Return non-@code{nil} if the advice @var{function} is already in the named -function @var{symbol}. @var{function} can also be the @code{name} of -an advice. -@end defun - -@defun advice-mapc function symbol -Call @var{function} for every advice that was added to the named function -@var{symbol}. @var{function} is called with two arguments: the advice function -and its properties. -@end defun - -@node Advice combinators -@subsection Ways to compose advices - -Here are the different possible values for the @var{where} argument of -@code{add-function} and @code{advice-add}, specifying how the advice -@var{function} and the original function should be composed. - -@table @code -@item :before -Call @var{function} before the old function. Both functions receive the -same arguments, and the return value of the composition is the return value of -the old function. More specifically, the composition of the two functions -behaves like: -@example -(lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r)) -@end example -@code{(add-function :before @var{funvar} @var{function})} is comparable for -single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} for -normal hooks. - -@item :after -Call @var{function} after the old function. Both functions receive the -same arguments, and the return value of the composition is the return value of -the old function. More specifically, the composition of the two functions -behaves like: -@example -(lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r))) -@end example -@code{(add-function :after @var{funvar} @var{function})} is comparable for -single-function hooks to @code{(add-hook '@var{hookvar} @var{function} -'append)} for normal hooks. - -@item :override -This completely replaces the old function with the new one. The old function -can of course be recovered if you later call @code{remove-function}. - -@item :around -Call @var{function} instead of the old function, but provide the old function -as an extra argument to @var{function}. This is the most flexible composition. -For example, it lets you call the old function with different arguments, or -many times, or within a let-binding, or you can sometimes delegate the work to -the old function and sometimes override it completely. More specifically, the -composition of the two functions behaves like: -@example -(lambda (&rest r) (apply @var{function} @var{oldfun} r)) -@end example - -@item :before-while -Call @var{function} before the old function and don't call the old -function if @var{function} returns @code{nil}. Both functions receive the -same arguments, and the return value of the composition is the return value of -the old function. More specifically, the composition of the two functions -behaves like: -@example -(lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r))) -@end example -@code{(add-function :before-while @var{funvar} @var{function})} is comparable -for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} -when @var{hookvar} is run via @code{run-hook-with-args-until-failure}. - -@item :before-until -Call @var{function} before the old function and only call the old function if -@var{function} returns @code{nil}. More specifically, the composition of the -two functions behaves like: -@example -(lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r))) -@end example -@code{(add-function :before-until @var{funvar} @var{function})} is comparable -for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} -when @var{hookvar} is run via @code{run-hook-with-args-until-success}. - -@item :after-while -Call @var{function} after the old function and only if the old function -returned non-@code{nil}. Both functions receive the same arguments, and the -return value of the composition is the return value of @var{function}. -More specifically, the composition of the two functions behaves like: -@example -(lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r))) -@end example -@code{(add-function :after-while @var{funvar} @var{function})} is comparable -for single-function hooks to @code{(add-hook '@var{hookvar} @var{function} -'append)} when @var{hookvar} is run via -@code{run-hook-with-args-until-failure}. - -@item :after-until -Call @var{function} after the old function and only if the old function -returned @code{nil}. More specifically, the composition of the two functions -behaves like: -@example -(lambda (&rest r) (or (apply @var{oldfun} r) (apply @var{function} r))) -@end example -@code{(add-function :after-until @var{funvar} @var{function})} is comparable -for single-function hooks to @code{(add-hook '@var{hookvar} @var{function} -'append)} when @var{hookvar} is run via -@code{run-hook-with-args-until-success}. - -@item :filter-args -Call @var{function} first and use the result (which should be a list) as the -new arguments to pass to the old function. More specifically, the composition -of the two functions behaves like: -@example -(lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r))) -@end example - -@item :filter-return -Call the old function first and pass the result to @var{function}. -More specifically, the composition of the two functions behaves like: -@example -(lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r))) -@end example -@end table - - -@node Porting old advices -@subsection Adapting code using the old defadvice - -A lot of code uses the old @code{defadvice} mechanism, which is largely made -obsolete by the new @code{advice-add}, whose implementation and semantics is -significantly simpler. - -An old advice such as: - -@example -(defadvice previous-line (before next-line-at-end - (&optional arg try-vscroll)) - "Insert an empty line when moving up from the top line." - (if (and next-line-add-newlines (= arg 1) - (save-excursion (beginning-of-line) (bobp))) - (progn - (beginning-of-line) - (newline)))) -@end example - -could be translated in the new advice mechanism into a plain function: - -@example -(defun previous-line--next-line-at-end (&optional arg try-vscroll) - "Insert an empty line when moving up from the top line." - (if (and next-line-add-newlines (= arg 1) - (save-excursion (beginning-of-line) (bobp))) - (progn - (beginning-of-line) - (newline)))) -@end example - -Obviously, this does not actually modify @code{previous-line}. For that the -old advice needed: -@example -(ad-activate 'previous-line) -@end example -whereas the new advice mechanism needs: -@example -(advice-add 'previous-line :before #'previous-line--next-line-at-end) -@end example - -Note that @code{ad-activate} had a global effect: it activated all pieces of -advice enabled for that specified function. If you wanted to only activate or -deactivate a particular advice, you needed to @emph{enable} or @emph{disable} -that advice with @code{ad-enable-advice} and @code{ad-disable-advice}. -The new mechanism does away with this distinction. - -An around advice such as: - -@example -(defadvice foo (around foo-around) - "Ignore case in `foo'." - (let ((case-fold-search t)) - ad-do-it)) -(ad-activate 'foo) -@end example - -could translate into: - -@example -(defun foo--foo-around (orig-fun &rest args) - "Ignore case in `foo'." - (let ((case-fold-search t)) - (apply orig-fun args))) -(advice-add 'foo :around #'foo--foo-around) -@end example - -Regarding the advice's @emph{class}, note that the new @code{:before} is not -quite equivalent to the old @code{before}, because in the old advice you could -modify the function's arguments (e.g., with @code{ad-set-arg}), and that would -affect the argument values seen by the original function, whereas in the new -@code{:before}, modifying an argument via @code{setq} in the advice has no -effect on the arguments seen by the original function. -When porting a @code{before} advice which relied on this behavior, you'll need -to turn it into a new @code{:around} or @code{:filter-args} advice instead. - -Similarly an old @code{after} advice could modify the returned value by -changing @code{ad-return-value}, whereas a new @code{:after} advice cannot, so -when porting such an old @code{after} advice, you'll need to turn it into a new -@code{:around} or @code{:filter-return} advice instead. - -@node Obsolete Functions -@section Declaring Functions Obsolete -@cindex obsolete functions - - You can mark a named function as @dfn{obsolete}, meaning that it may -be removed at some point in the future. This causes Emacs to warn -that the function is obsolete whenever it byte-compiles code -containing that function, and whenever it displays the documentation -for that function. In all other respects, an obsolete function -behaves like any other function. - - The easiest way to mark a function as obsolete is to put a -@code{(declare (obsolete @dots{}))} form in the function's -@code{defun} definition. @xref{Declare Form}. Alternatively, you can -use the @code{make-obsolete} function, described below. - - A macro (@pxref{Macros}) can also be marked obsolete with -@code{make-obsolete}; this has the same effects as for a function. An -alias for a function or macro can also be marked as obsolete; this -makes the alias itself obsolete, not the function or macro which it -resolves to. - -@defun make-obsolete obsolete-name current-name &optional when -This function marks @var{obsolete-name} as obsolete. -@var{obsolete-name} should be a symbol naming a function or macro, or -an alias for a function or macro. - -If @var{current-name} is a symbol, the warning message says to use -@var{current-name} instead of @var{obsolete-name}. @var{current-name} -does not need to be an alias for @var{obsolete-name}; it can be a -different function with similar functionality. @var{current-name} can -also be a string, which serves as the warning message. The message -should begin in lower case, and end with a period. It can also be -@code{nil}, in which case the warning message provides no additional -details. - -If provided, @var{when} should be a string indicating when the function -was first made obsolete---for example, a date or a release number. -@end defun - -@defmac define-obsolete-function-alias obsolete-name current-name &optional when doc -This convenience macro marks the function @var{obsolete-name} obsolete -and also defines it as an alias for the function @var{current-name}. -It is equivalent to the following: - -@example -(defalias @var{obsolete-name} @var{current-name} @var{doc}) -(make-obsolete @var{obsolete-name} @var{current-name} @var{when}) -@end example -@end defmac - -In addition, you can mark a certain a particular calling convention -for a function as obsolete: - -@defun set-advertised-calling-convention function signature when -This function specifies the argument list @var{signature} as the -correct way to call @var{function}. This causes the Emacs byte -compiler to issue a warning whenever it comes across an Emacs Lisp -program that calls @var{function} any other way (however, it will -still allow the code to be byte compiled). @var{when} should be a -string indicating when the variable was first made obsolete (usually a -version number string). - -For instance, in old versions of Emacs the @code{sit-for} function -accepted three arguments, like this - -@example - (sit-for seconds milliseconds nodisp) -@end example - -However, calling @code{sit-for} this way is considered obsolete -(@pxref{Waiting}). The old calling convention is deprecated like -this: - -@example -(set-advertised-calling-convention - 'sit-for '(seconds &optional nodisp) "22.1") -@end example -@end defun - -@node Inline Functions -@section Inline Functions -@cindex inline functions - - An @dfn{inline function} is a function that works just like an -ordinary function, except for one thing: when you byte-compile a call -to the function (@pxref{Byte Compilation}), the function's definition -is expanded into the caller. To define an inline function, use -@code{defsubst} instead of @code{defun}. - -@defmac defsubst name args [doc] [declare] [interactive] body@dots{} -This macro defines an inline function. Its syntax is exactly the same -as @code{defun} (@pxref{Defining Functions}). -@end defmac - - Making a function inline often makes its function calls run faster. -But it also has disadvantages. For one thing, it reduces flexibility; -if you change the definition of the function, calls already inlined -still use the old definition until you recompile them. - - Another disadvantage is that making a large function inline can -increase the size of compiled code both in files and in memory. Since -the speed advantage of inline functions is greatest for small -functions, you generally should not make large functions inline. - - Also, inline functions do not behave well with respect to debugging, -tracing, and advising (@pxref{Advising Functions}). Since ease of -debugging and the flexibility of redefining functions are important -features of Emacs, you should not make a function inline, even if it's -small, unless its speed is really crucial, and you've timed the code -to verify that using @code{defun} actually has performance problems. - - It's possible to define a macro to expand into the same code that an -inline function would execute (@pxref{Macros}). But the macro would -be limited to direct use in expressions---a macro cannot be called -with @code{apply}, @code{mapcar} and so on. Also, it takes some work -to convert an ordinary function into a macro. To convert it into an -inline function is easy; just replace @code{defun} with -@code{defsubst}. Since each argument of an inline function is -evaluated exactly once, you needn't worry about how many times the -body uses the arguments, as you do for macros. - - After an inline function is defined, its inline expansion can be -performed later on in the same file, just like macros. - -@node Declare Form -@section The @code{declare} Form -@findex declare - - @code{declare} is a special macro which can be used to add ``meta'' -properties to a function or macro: for example, marking it as -obsolete, or giving its forms a special @key{TAB} indentation -convention in Emacs Lisp mode. - -@anchor{Definition of declare} -@defmac declare specs@dots{} -This macro ignores its arguments and evaluates to @code{nil}; it has -no run-time effect. However, when a @code{declare} form occurs in the -@var{declare} argument of a @code{defun} or @code{defsubst} function -definition (@pxref{Defining Functions}) or a @code{defmacro} macro -definition (@pxref{Defining Macros}), it appends the properties -specified by @var{specs} to the function or macro. This work is -specially performed by @code{defun}, @code{defsubst}, and -@code{defmacro}. - -Each element in @var{specs} should have the form @code{(@var{property} -@var{args}@dots{})}, which should not be quoted. These have the -following effects: - -@table @code -@item (advertised-calling-convention @var{signature} @var{when}) -This acts like a call to @code{set-advertised-calling-convention} -(@pxref{Obsolete Functions}); @var{signature} specifies the correct -argument list for calling the function or macro, and @var{when} should -be a string indicating when the old argument list was first made obsolete. - -@item (debug @var{edebug-form-spec}) -This is valid for macros only. When stepping through the macro with -Edebug, use @var{edebug-form-spec}. @xref{Instrumenting Macro Calls}. - -@item (doc-string @var{n}) -This is used when defining a function or macro which itself will be used to -define entities like functions, macros, or variables. It indicates that -the @var{n}th argument, if any, should be considered -as a documentation string. - -@item (indent @var{indent-spec}) -Indent calls to this function or macro according to @var{indent-spec}. -This is typically used for macros, though it works for functions too. -@xref{Indenting Macros}. - -@item (obsolete @var{current-name} @var{when}) -Mark the function or macro as obsolete, similar to a call to -@code{make-obsolete} (@pxref{Obsolete Functions}). @var{current-name} -should be a symbol (in which case the warning message says to use that -instead), a string (specifying the warning message), or @code{nil} (in -which case the warning message gives no extra details). @var{when} -should be a string indicating when the function or macro was first -made obsolete. - -@item (compiler-macro @var{expander}) -This can only be used for functions, and tells the compiler to use -@var{expander} as an optimization function. When encountering a call to the -function, of the form @code{(@var{function} @var{args}@dots{})}, the macro -expander will call @var{expander} with that form as well as with -@var{args}@dots{}, and @var{expander} can either return a new expression to use -instead of the function call, or it can return just the form unchanged, -to indicate that the function call should be left alone. @var{expander} can -be a symbol, or it can be a form @code{(lambda (@var{arg}) @var{body})} in -which case @var{arg} will hold the original function call expression, and the -(unevaluated) arguments to the function can be accessed using the function's -formal arguments. - -@item (gv-expander @var{expander}) -Declare @var{expander} to be the function to handle calls to the macro (or -function) as a generalized variable, similarly to @code{gv-define-expander}. -@var{expander} can be a symbol or it can be of the form @code{(lambda -(@var{arg}) @var{body})} in which case that function will additionally have -access to the macro (or function)'s arguments. - -@item (gv-setter @var{setter}) -Declare @var{setter} to be the function to handle calls to the macro (or -function) as a generalized variable. @var{setter} can be a symbol in which -case it will be passed to @code{gv-define-simple-setter}, or it can be of the -form @code{(lambda (@var{arg}) @var{body})} in which case that function will -additionally have access to the macro (or function)'s arguments and it will -passed to @code{gv-define-setter}. - -@end table - -@end defmac - -@node Declaring Functions -@section Telling the Compiler that a Function is Defined -@cindex function declaration -@cindex declaring functions -@findex declare-function - -Byte-compiling a file often produces warnings about functions that the -compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this -indicates a real problem, but usually the functions in question are -defined in other files which would be loaded if that code is run. For -example, byte-compiling @file{fortran.el} used to warn: - -@example -In end of data: -fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not - known to be defined. -@end example - -In fact, @code{gud-find-c-expr} is only used in the function that -Fortran mode uses for the local value of -@code{gud-find-expr-function}, which is a callback from GUD; if it is -called, the GUD functions will be loaded. When you know that such a -warning does not indicate a real problem, it is good to suppress the -warning. That makes new warnings which might mean real problems more -visible. You do that with @code{declare-function}. - -All you need to do is add a @code{declare-function} statement before the -first use of the function in question: - -@example -(declare-function gud-find-c-expr "gud.el" nil) -@end example - -This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the -@samp{.el} can be omitted). The compiler takes for granted that that file -really defines the function, and does not check. - - The optional third argument specifies the argument list of -@code{gud-find-c-expr}. In this case, it takes no arguments -(@code{nil} is different from not specifying a value). In other -cases, this might be something like @code{(file &optional overwrite)}. -You don't have to specify the argument list, but if you do the -byte compiler can check that the calls match the declaration. - -@defmac declare-function function file &optional arglist fileonly -Tell the byte compiler to assume that @var{function} is defined, with -arguments @var{arglist}, and that the definition should come from the -file @var{file}. @var{fileonly} non-@code{nil} means only check that -@var{file} exists, not that it actually defines @var{function}. -@end defmac - - To verify that these functions really are declared where -@code{declare-function} says they are, use @code{check-declare-file} -to check all @code{declare-function} calls in one source file, or use -@code{check-declare-directory} check all the files in and under a -certain directory. - - These commands find the file that ought to contain a function's -definition using @code{locate-library}; if that finds no file, they -expand the definition file name relative to the directory of the file -that contains the @code{declare-function} call. - - You can also say that a function is a primitive by specifying a file -name ending in @samp{.c} or @samp{.m}. This is useful only when you -call a primitive that is defined only on certain systems. Most -primitives are always defined, so they will never give you a warning. - - Sometimes a file will optionally use functions from an external package. -If you prefix the filename in the @code{declare-function} statement with -@samp{ext:}, then it will be checked if it is found, otherwise skipped -without error. - - There are some function definitions that @samp{check-declare} does not -understand (e.g., @code{defstruct} and some other macros). In such cases, -you can pass a non-@code{nil} @var{fileonly} argument to -@code{declare-function}, meaning to only check that the file exists, not -that it actually defines the function. Note that to do this without -having to specify an argument list, you should set the @var{arglist} -argument to @code{t} (because @code{nil} means an empty argument list, as -opposed to an unspecified one). - -@node Function Safety -@section Determining whether a Function is Safe to Call -@cindex function safety -@cindex safety of functions - -Some major modes, such as SES, call functions that are stored in user -files. (@inforef{Top, ,ses}, for more information on SES@.) User -files sometimes have poor pedigrees---you can get a spreadsheet from -someone you've just met, or you can get one through email from someone -you've never met. So it is risky to call a function whose source code -is stored in a user file until you have determined that it is safe. - -@defun unsafep form &optional unsafep-vars -Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or -returns a list that describes why it might be unsafe. The argument -@var{unsafep-vars} is a list of symbols known to have temporary -bindings at this point; it is mainly used for internal recursive -calls. The current buffer is an implicit argument, which provides a -list of buffer-local bindings. -@end defun - -Being quick and simple, @code{unsafep} does a very light analysis and -rejects many Lisp expressions that are actually safe. There are no -known cases where @code{unsafep} returns @code{nil} for an unsafe -expression. However, a ``safe'' Lisp expression can return a string -with a @code{display} property, containing an associated Lisp -expression to be executed after the string is inserted into a buffer. -This associated expression can be a virus. In order to be safe, you -must delete properties from all strings calculated by user code before -inserting them into buffers. - -@ignore -What is a safe Lisp expression? Basically, it's an expression that -calls only built-in functions with no side effects (or only innocuous -ones). Innocuous side effects include displaying messages and -altering non-risky buffer-local variables (but not global variables). - -@table @dfn -@item Safe expression -@itemize -@item -An atom or quoted thing. -@item -A call to a safe function (see below), if all its arguments are -safe expressions. -@item -One of the special forms @code{and}, @code{catch}, @code{cond}, -@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn}, -@code{while}, and @code{unwind-protect}], if all its arguments are -safe. -@item -A form that creates temporary bindings (@code{condition-case}, -@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or -@code{let*}), if all args are safe and the symbols to be bound are not -explicitly risky (see @pxref{File Local Variables}). -@item -An assignment using @code{add-to-list}, @code{setq}, @code{push}, or -@code{pop}, if all args are safe and the symbols to be assigned are -not explicitly risky and they already have temporary or buffer-local -bindings. -@item -One of [apply, mapc, mapcar, mapconcat] if the first argument is a -safe explicit lambda and the other args are safe expressions. -@end itemize - -@item Safe function -@itemize -@item -A lambda containing safe expressions. -@item -A symbol on the list @code{safe-functions}, so the user says it's safe. -@item -A symbol with a non-@code{nil} @code{side-effect-free} property. -@item -A symbol with a non-@code{nil} @code{safe-function} property. The -value @code{t} indicates a function that is safe but has innocuous -side effects. Other values will someday indicate functions with -classes of side effects that are not always safe. -@end itemize - -The @code{side-effect-free} and @code{safe-function} properties are -provided for built-in functions and for low-level functions and macros -defined in @file{subr.el}. You can assign these properties for the -functions you write. -@end table -@end ignore - -@node Related Topics -@section Other Topics Related to Functions - - Here is a table of several functions that do things related to -function calling and function definitions. They are documented -elsewhere, but we provide cross references here. - -@table @code -@item apply -See @ref{Calling Functions}. - -@item autoload -See @ref{Autoload}. - -@item call-interactively -See @ref{Interactive Call}. - -@item called-interactively-p -See @ref{Distinguish Interactive}. - -@item commandp -See @ref{Interactive Call}. - -@item documentation -See @ref{Accessing Documentation}. - -@item eval -See @ref{Eval}. - -@item funcall -See @ref{Calling Functions}. - -@item function -See @ref{Anonymous Functions}. - -@item ignore -See @ref{Calling Functions}. - -@item indirect-function -See @ref{Function Indirection}. - -@item interactive -See @ref{Using Interactive}. - -@item interactive-p -See @ref{Distinguish Interactive}. - -@item mapatoms -See @ref{Creating Symbols}. - -@item mapcar -See @ref{Mapping Functions}. - -@item map-char-table -See @ref{Char-Tables}. - -@item mapconcat -See @ref{Mapping Functions}. - -@item undefined -See @ref{Functions for Key Lookup}. -@end table diff --git a/doc/lispref/gpl.texi b/doc/lispref/gpl.texi deleted file mode 100644 index 0e2e212acb1..00000000000 --- a/doc/lispref/gpl.texi +++ /dev/null @@ -1,717 +0,0 @@ -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW@. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE@. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi deleted file mode 100644 index 536777add72..00000000000 --- a/doc/lispref/hash.texi +++ /dev/null @@ -1,355 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2001-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Hash Tables -@chapter Hash Tables -@cindex hash tables -@cindex lookup tables - - A hash table is a very fast kind of lookup table, somewhat like an -alist (@pxref{Association Lists}) in that it maps keys to -corresponding values. It differs from an alist in these ways: - -@itemize @bullet -@item -Lookup in a hash table is extremely fast for large tables---in fact, the -time required is essentially @emph{independent} of how many elements are -stored in the table. For smaller tables (a few tens of elements) -alists may still be faster because hash tables have a more-or-less -constant overhead. - -@item -The correspondences in a hash table are in no particular order. - -@item -There is no way to share structure between two hash tables, -the way two alists can share a common tail. -@end itemize - - Emacs Lisp provides a general-purpose hash table data type, along -with a series of functions for operating on them. Hash tables have a -special printed representation, which consists of @samp{#s} followed -by a list specifying the hash table properties and contents. -@xref{Creating Hash}. (Note that the term ``hash notation'', which -refers to the initial @samp{#} character used in the printed -representations of objects with no read representation, has nothing to -do with the term ``hash table''. @xref{Printed Representation}.) - - Obarrays are also a kind of hash table, but they are a different type -of object and are used only for recording interned symbols -(@pxref{Creating Symbols}). - -@menu -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. -@end menu - -@node Creating Hash -@section Creating Hash Tables -@cindex creating hash tables - - The principal function for creating a hash table is -@code{make-hash-table}. - -@defun make-hash-table &rest keyword-args -This function creates a new hash table according to the specified -arguments. The arguments should consist of alternating keywords -(particular symbols recognized specially) and values corresponding to -them. - -Several keywords make sense in @code{make-hash-table}, but the only two -that you really need to know about are @code{:test} and @code{:weakness}. - -@table @code -@item :test @var{test} -This specifies the method of key lookup for this hash table. The -default is @code{eql}; @code{eq} and @code{equal} are other -alternatives: - -@table @code -@item eql -Keys which are numbers are ``the same'' if they are @code{equal}, that -is, if they are equal in value and either both are integers or both -are floating point; otherwise, two distinct objects are never -``the same''. - -@item eq -Any two distinct Lisp objects are ``different'' as keys. - -@item equal -Two Lisp objects are ``the same'', as keys, if they are equal -according to @code{equal}. -@end table - -You can use @code{define-hash-table-test} (@pxref{Defining Hash}) to -define additional possibilities for @var{test}. - -@item :weakness @var{weak} -The weakness of a hash table specifies whether the presence of a key or -value in the hash table preserves it from garbage collection. - -The value, @var{weak}, must be one of @code{nil}, @code{key}, -@code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t} -which is an alias for @code{key-and-value}. If @var{weak} is @code{key} -then the hash table does not prevent its keys from being collected as -garbage (if they are not referenced anywhere else); if a particular key -does get collected, the corresponding association is removed from the -hash table. - -If @var{weak} is @code{value}, then the hash table does not prevent -values from being collected as garbage (if they are not referenced -anywhere else); if a particular value does get collected, the -corresponding association is removed from the hash table. - -If @var{weak} is @code{key-and-value} or @code{t}, both the key and -the value must be live in order to preserve the association. Thus, -the hash table does not protect either keys or values from garbage -collection; if either one is collected as garbage, that removes the -association. - -If @var{weak} is @code{key-or-value}, either the key or -the value can preserve the association. Thus, associations are -removed from the hash table when both their key and value would be -collected as garbage (if not for references from weak hash tables). - -The default for @var{weak} is @code{nil}, so that all keys and values -referenced in the hash table are preserved from garbage collection. - -@item :size @var{size} -This specifies a hint for how many associations you plan to store in the -hash table. If you know the approximate number, you can make things a -little more efficient by specifying it this way. If you specify too -small a size, the hash table will grow automatically when necessary, but -doing that takes some extra time. - -The default size is 65. - -@item :rehash-size @var{rehash-size} -When you add an association to a hash table and the table is ``full'', -it grows automatically. This value specifies how to make the hash table -larger, at that time. - -If @var{rehash-size} is an integer, it should be positive, and the hash -table grows by adding that much to the nominal size. If -@var{rehash-size} is floating point, it had better be greater -than 1, and the hash table grows by multiplying the old size by that -number. - -The default value is 1.5. - -@item :rehash-threshold @var{threshold} -This specifies the criterion for when the hash table is ``full'' (so -it should be made larger). The value, @var{threshold}, should be a -positive floating-point number, no greater than 1. The hash table is -``full'' whenever the actual number of entries exceeds this fraction -of the nominal size. The default for @var{threshold} is 0.8. -@end table -@end defun - -@defun makehash &optional test -This is equivalent to @code{make-hash-table}, but with a different style -argument list. The argument @var{test} specifies the method -of key lookup. - -This function is obsolete. Use @code{make-hash-table} instead. -@end defun - -You can also create a new hash table using the printed representation -for hash tables. The Lisp reader can read this printed -representation, provided each element in the specified hash table has -a valid read syntax (@pxref{Printed Representation}). For instance, -the following specifies a new hash table containing the keys -@code{key1} and @code{key2} (both symbols) associated with @code{val1} -(a symbol) and @code{300} (a number) respectively. - -@example -#s(hash-table size 30 data (key1 val1 key2 300)) -@end example - -@noindent -The printed representation for a hash table consists of @samp{#s} -followed by a list beginning with @samp{hash-table}. The rest of the -list should consist of zero or more property-value pairs specifying -the hash table's properties and initial contents. The properties and -values are read literally. Valid property names are @code{size}, -@code{test}, @code{weakness}, @code{rehash-size}, -@code{rehash-threshold}, and @code{data}. The @code{data} property -should be a list of key-value pairs for the initial contents; the -other properties have the same meanings as the matching -@code{make-hash-table} keywords (@code{:size}, @code{:test}, etc.), -described above. - -Note that you cannot specify a hash table whose initial contents -include objects that have no read syntax, such as buffers and frames. -Such objects may be added to the hash table after it is created. - -@node Hash Access -@section Hash Table Access - - This section describes the functions for accessing and storing -associations in a hash table. In general, any Lisp object can be used -as a hash key, unless the comparison method imposes limits. Any Lisp -object can also be used as the value. - -@defun gethash key table &optional default -This function looks up @var{key} in @var{table}, and returns its -associated @var{value}---or @var{default}, if @var{key} has no -association in @var{table}. -@end defun - -@defun puthash key value table -This function enters an association for @var{key} in @var{table}, with -value @var{value}. If @var{key} already has an association in -@var{table}, @var{value} replaces the old associated value. -@end defun - -@defun remhash key table -This function removes the association for @var{key} from @var{table}, if -there is one. If @var{key} has no association, @code{remhash} does -nothing. - -@b{Common Lisp note:} In Common Lisp, @code{remhash} returns -non-@code{nil} if it actually removed an association and @code{nil} -otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}. -@end defun - -@defun clrhash table -This function removes all the associations from hash table @var{table}, -so that it becomes empty. This is also called @dfn{clearing} the hash -table. - -@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty -@var{table}. In Emacs Lisp, it returns @code{nil}. -@end defun - -@defun maphash function table -@anchor{Definition of maphash} -This function calls @var{function} once for each of the associations in -@var{table}. The function @var{function} should accept two -arguments---a @var{key} listed in @var{table}, and its associated -@var{value}. @code{maphash} returns @code{nil}. -@end defun - -@node Defining Hash -@section Defining Hash Comparisons -@cindex hash code -@cindex define hash comparisons - - You can define new methods of key lookup by means of -@code{define-hash-table-test}. In order to use this feature, you need -to understand how hash tables work, and what a @dfn{hash code} means. - - You can think of a hash table conceptually as a large array of many -slots, each capable of holding one association. To look up a key, -@code{gethash} first computes an integer, the hash code, from the key. -It reduces this integer modulo the length of the array, to produce an -index in the array. Then it looks in that slot, and if necessary in -other nearby slots, to see if it has found the key being sought. - - Thus, to define a new method of key lookup, you need to specify both a -function to compute the hash code from a key, and a function to compare -two keys directly. - -@defun define-hash-table-test name test-fn hash-fn -This function defines a new hash table test, named @var{name}. - -After defining @var{name} in this way, you can use it as the @var{test} -argument in @code{make-hash-table}. When you do that, the hash table -will use @var{test-fn} to compare key values, and @var{hash-fn} to compute -a ``hash code'' from a key value. - -The function @var{test-fn} should accept two arguments, two keys, and -return non-@code{nil} if they are considered ``the same''. - -The function @var{hash-fn} should accept one argument, a key, and return -an integer that is the ``hash code'' of that key. For good results, the -function should use the whole range of integers for hash codes, -including negative integers. - -The specified functions are stored in the property list of @var{name} -under the property @code{hash-table-test}; the property value's form is -@code{(@var{test-fn} @var{hash-fn})}. -@end defun - -@defun sxhash obj -This function returns a hash code for Lisp object @var{obj}. -This is an integer which reflects the contents of @var{obj} -and the other Lisp objects it points to. - -If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash -@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer. - -If the two objects are not equal, the values returned by @code{sxhash} -are usually different, but not always; once in a rare while, by luck, -you will encounter two distinct-looking objects that give the same -result from @code{sxhash}. -@end defun - - This example creates a hash table whose keys are strings that are -compared case-insensitively. - -@example -(defun case-fold-string= (a b) - (eq t (compare-strings a nil nil b nil nil t))) -(defun case-fold-string-hash (a) - (sxhash (upcase a))) - -(define-hash-table-test 'case-fold - 'case-fold-string= 'case-fold-string-hash) - -(make-hash-table :test 'case-fold) -@end example - - Here is how you could define a hash table test equivalent to the -predefined test value @code{equal}. The keys can be any Lisp object, -and equal-looking objects are considered the same key. - -@example -(define-hash-table-test 'contents-hash 'equal 'sxhash) - -(make-hash-table :test 'contents-hash) -@end example - -@node Other Hash -@section Other Hash Table Functions - - Here are some other functions for working with hash tables. - -@defun hash-table-p table -This returns non-@code{nil} if @var{table} is a hash table object. -@end defun - -@defun copy-hash-table table -This function creates and returns a copy of @var{table}. Only the table -itself is copied---the keys and values are shared. -@end defun - -@defun hash-table-count table -This function returns the actual number of entries in @var{table}. -@end defun - -@defun hash-table-test table -This returns the @var{test} value that was given when @var{table} was -created, to specify how to hash and compare keys. See -@code{make-hash-table} (@pxref{Creating Hash}). -@end defun - -@defun hash-table-weakness table -This function returns the @var{weak} value that was specified for hash -table @var{table}. -@end defun - -@defun hash-table-rehash-size table -This returns the rehash size of @var{table}. -@end defun - -@defun hash-table-rehash-threshold table -This returns the rehash threshold of @var{table}. -@end defun - -@defun hash-table-size table -This returns the current nominal size of @var{table}. -@end defun diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi deleted file mode 100644 index 20fb0e651f9..00000000000 --- a/doc/lispref/help.texi +++ /dev/null @@ -1,712 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Documentation -@chapter Documentation -@cindex documentation strings - - GNU Emacs has convenient built-in help facilities, most of which -derive their information from documentation strings associated with -functions and variables. This chapter describes how to access -documentation strings in Lisp programs. - - The contents of a documentation string should follow certain -conventions. In particular, its first line should be a complete -sentence (or two complete sentences) that briefly describes what the -function or variable does. @xref{Documentation Tips}, for how to -write good documentation strings. - - Note that the documentation strings for Emacs are not the same thing -as the Emacs manual. Manuals have their own source files, written in -the Texinfo language; documentation strings are specified in the -definitions of the functions and variables they apply to. A collection -of documentation strings is not sufficient as a manual because a good -manual is not organized in that fashion; it is organized in terms of -topics of discussion. - - For commands to display documentation strings, see @ref{Help, , -Help, emacs, The GNU Emacs Manual}. - -@menu -* Documentation Basics:: Where doc strings are defined and stored. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. -@end menu - -@node Documentation Basics -@section Documentation Basics -@cindex documentation conventions -@cindex writing a documentation string -@cindex string, writing a doc string - - A documentation string is written using the Lisp syntax for strings, -with double-quote characters surrounding the text. It is, in fact, an -actual Lisp string. When the string appears in the proper place in a -function or variable definition, it serves as the function's or -variable's documentation. - -@cindex @code{function-documentation} property - In a function definition (a @code{lambda} or @code{defun} form), the -documentation string is specified after the argument list, and is -normally stored directly in the function object. @xref{Function -Documentation}. You can also put function documentation in the -@code{function-documentation} property of a function name -(@pxref{Accessing Documentation}). - -@cindex @code{variable-documentation} property - In a variable definition (a @code{defvar} form), the documentation -string is specified after the initial value. @xref{Defining -Variables}. The string is stored in the variable's -@code{variable-documentation} property. - -@cindex @file{DOC} (documentation) file - Sometimes, Emacs does not keep documentation strings in memory. -There are two such circumstances. Firstly, to save memory, the -documentation for preloaded functions and variables (including -primitives) is kept in a file named @file{DOC}, in the directory -specified by @code{doc-directory} (@pxref{Accessing Documentation}). -Secondly, when a function or variable is loaded from a byte-compiled -file, Emacs avoids loading its documentation string (@pxref{Docs and -Compilation}). In both cases, Emacs looks up the documentation string -from the file only when needed, such as when the user calls @kbd{C-h -f} (@code{describe-function}) for a function. - - Documentation strings can contain special @dfn{key substitution -sequences}, referring to key bindings which are looked up only when -the user views the documentation. This allows the help commands to -display the correct keys even if a user rearranges the default key -bindings. @xref{Keys in Documentation}. - - In the documentation string of an autoloaded command -(@pxref{Autoload}), these key-substitution sequences have an -additional special effect: they cause @kbd{C-h f} on the command to -trigger autoloading. (This is needed for correctly setting up the -hyperlinks in the @file{*Help*} buffer.) - -@node Accessing Documentation -@section Access to Documentation Strings - -@defun documentation-property symbol property &optional verbatim -This function returns the documentation string recorded in -@var{symbol}'s property list under property @var{property}. It is -most often used to look up the documentation strings of variables, for -which @var{property} is @code{variable-documentation}. However, it -can also be used to look up other kinds of documentation, such as for -customization groups (but for function documentation, use the -@code{documentation} function, below). - -If the property value refers to a documentation string stored in the -@file{DOC} file or a byte-compiled file, this function looks up that -string and returns it. - -If the property value isn't @code{nil}, isn't a string, and doesn't -refer to text in a file, then it is evaluated as a Lisp expression to -obtain a string. - -Finally, this function passes the string through -@code{substitute-command-keys} to substitute key bindings (@pxref{Keys -in Documentation}). It skips this step if @var{verbatim} is -non-@code{nil}. - -@smallexample -@group -(documentation-property 'command-line-processed - 'variable-documentation) - @result{} "Non-nil once command line has been processed" -@end group -@group -(symbol-plist 'command-line-processed) - @result{} (variable-documentation 188902) -@end group -@group -(documentation-property 'emacs 'group-documentation) - @result{} "Customization of the One True Editor." -@end group -@end smallexample -@end defun - -@defun documentation function &optional verbatim -This function returns the documentation string of @var{function}. It -handles macros, named keyboard macros, and special forms, as well as -ordinary functions. - -If @var{function} is a symbol, this function first looks for the -@code{function-documentation} property of that symbol; if that has a -non-@code{nil} value, the documentation comes from that value (if the -value is not a string, it is evaluated). - -If @var{function} is not a symbol, or if it has no -@code{function-documentation} property, then @code{documentation} -extracts the documentation string from the actual function definition, -reading it from a file if called for. - -Finally, unless @var{verbatim} is non-@code{nil}, this function calls -@code{substitute-command-keys}. The result is the documentation -string to return. - -The @code{documentation} function signals a @code{void-function} error -if @var{function} has no function definition. However, it is OK if -the function definition has no documentation string. In that case, -@code{documentation} returns @code{nil}. -@end defun - -@defun face-documentation face -This function returns the documentation string of @var{face} as a -face. -@end defun - -Here is an example of using the two functions, @code{documentation} and -@code{documentation-property}, to display the documentation strings for -several symbols in a @file{*Help*} buffer. - -@anchor{describe-symbols example} -@smallexample -@group -(defun describe-symbols (pattern) - "Describe the Emacs Lisp symbols matching PATTERN. -All symbols that have PATTERN in their name are described -in the `*Help*' buffer." - (interactive "sDescribe symbols matching: ") - (let ((describe-func - (function - (lambda (s) -@end group -@group - ;; @r{Print description of symbol.} - (if (fboundp s) ; @r{It is a function.} - (princ - (format "%s\t%s\n%s\n\n" s - (if (commandp s) - (let ((keys (where-is-internal s))) - (if keys - (concat - "Keys: " - (mapconcat 'key-description - keys " ")) - "Keys: none")) - "Function") -@end group -@group - (or (documentation s) - "not documented")))) - - (if (boundp s) ; @r{It is a variable.} -@end group -@group - (princ - (format "%s\t%s\n%s\n\n" s - (if (custom-variable-p s) - "Option " "Variable") -@end group -@group - (or (documentation-property - s 'variable-documentation) - "not documented"))))))) - sym-list) -@end group - -@group - ;; @r{Build a list of symbols that match pattern.} - (mapatoms (function - (lambda (sym) - (if (string-match pattern (symbol-name sym)) - (setq sym-list (cons sym sym-list)))))) -@end group - -@group - ;; @r{Display the data.} - (help-setup-xref (list 'describe-symbols pattern) (interactive-p)) - (with-help-window (help-buffer) - (mapcar describe-func (sort sym-list 'string<))))) -@end group -@end smallexample - - The @code{describe-symbols} function works like @code{apropos}, -but provides more information. - -@smallexample -@group -(describe-symbols "goal") - ----------- Buffer: *Help* ---------- -goal-column Option -Semipermanent goal column for vertical motion, as set by @dots{} -@end group -@c Do not blithely break or fill these lines. -@c That makes them incorrect. - -@group -set-goal-column Keys: C-x C-n -Set the current horizontal position as a goal for C-n and C-p. -@end group -@c DO NOT put a blank line here! That is factually inaccurate! -@group -Those commands will move to this position in the line moved to -rather than trying to keep the same horizontal position. -With a non-nil argument, clears out the goal column -so that C-n and C-p resume vertical motion. -The goal column is stored in the variable `goal-column'. -@end group - -@group -temporary-goal-column Variable -Current goal column for vertical motion. -It is the column where point was -at the start of current run of vertical motion commands. -When the `track-eol' feature is doing its job, the value is 9999. ----------- Buffer: *Help* ---------- -@end group -@end smallexample - -@anchor{Definition of Snarf-documentation} -@defun Snarf-documentation filename -This function is used when building Emacs, just before the runnable -Emacs is dumped. It finds the positions of the documentation strings -stored in the file @var{filename}, and records those positions into -memory in the function definitions and variable property lists. -@xref{Building Emacs}. - -Emacs reads the file @var{filename} from the @file{emacs/etc} directory. -When the dumped Emacs is later executed, the same file will be looked -for in the directory @code{doc-directory}. Usually @var{filename} is -@code{"DOC"}. -@end defun - -@defvar doc-directory -This variable holds the name of the directory which should contain the -file @code{"DOC"} that contains documentation strings for -built-in and preloaded functions and variables. - -In most cases, this is the same as @code{data-directory}. They may be -different when you run Emacs from the directory where you built it, -without actually installing it. @xref{Definition of data-directory}. -@end defvar - -@node Keys in Documentation -@section Substituting Key Bindings in Documentation -@cindex documentation, keys in -@cindex keys in documentation strings -@cindex substituting keys in documentation -@cindex key substitution sequence - - When documentation strings refer to key sequences, they should use the -current, actual key bindings. They can do so using certain special text -sequences described below. Accessing documentation strings in the usual -way substitutes current key binding information for these special -sequences. This works by calling @code{substitute-command-keys}. You -can also call that function yourself. - - Here is a list of the special sequences and what they mean: - -@table @code -@item \[@var{command}] -stands for a key sequence that will invoke @var{command}, or @samp{M-x -@var{command}} if @var{command} has no key bindings. - -@item \@{@var{mapvar}@} -stands for a summary of the keymap which is the value of the variable -@var{mapvar}. The summary is made using @code{describe-bindings}. - -@item \<@var{mapvar}> -stands for no text itself. It is used only for a side effect: it -specifies @var{mapvar}'s value as the keymap for any following -@samp{\[@var{command}]} sequences in this documentation string. - -@item \= -quotes the following character and is discarded; thus, @samp{\=\[} puts -@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the -output. -@end table - -@strong{Please note:} Each @samp{\} must be doubled when written in a -string in Emacs Lisp. - -@defun substitute-command-keys string -This function scans @var{string} for the above special sequences and -replaces them by what they stand for, returning the result as a string. -This permits display of documentation that refers accurately to the -user's own customized key bindings. - -@cindex advertised binding -If a command has multiple bindings, this function normally uses the -first one it finds. You can specify one particular key binding by -assigning an @code{:advertised-binding} symbol property to the -command, like this: - -@smallexample -(put 'undo :advertised-binding [?\C-/]) -@end smallexample - -@noindent -The @code{:advertised-binding} property also affects the binding shown -in menu items (@pxref{Menu Bar}). The property is ignored if it -specifies a key binding that the command does not actually have. -@end defun - - Here are examples of the special sequences: - -@smallexample -@group -(substitute-command-keys - "To abort recursive edit, type: \\[abort-recursive-edit]") -@result{} "To abort recursive edit, type: C-]" -@end group - -@group -(substitute-command-keys - "The keys that are defined for the minibuffer here are: - \\@{minibuffer-local-must-match-map@}") -@result{} "The keys that are defined for the minibuffer here are: -@end group - -? minibuffer-completion-help -SPC minibuffer-complete-word -TAB minibuffer-complete -C-j minibuffer-complete-and-exit -RET minibuffer-complete-and-exit -C-g abort-recursive-edit -" - -@group -(substitute-command-keys - "To abort a recursive edit from the minibuffer, type\ -\\\\[abort-recursive-edit].") -@result{} "To abort a recursive edit from the minibuffer, type C-g." -@end group -@end smallexample - - There are other special conventions for the text in documentation -strings---for instance, you can refer to functions, variables, and -sections of this manual. @xref{Documentation Tips}, for details. - -@node Describing Characters -@section Describing Characters for Help Messages -@cindex describe characters and events - - These functions convert events, key sequences, or characters to -textual descriptions. These descriptions are useful for including -arbitrary text characters or key sequences in messages, because they -convert non-printing and whitespace characters to sequences of printing -characters. The description of a non-whitespace printing character is -the character itself. - -@defun key-description sequence &optional prefix -@cindex Emacs event standard notation -This function returns a string containing the Emacs standard notation -for the input events in @var{sequence}. If @var{prefix} is -non-@code{nil}, it is a sequence of input events leading up to -@var{sequence} and is included in the return value. Both arguments -may be strings, vectors or lists. @xref{Input Events}, for more -information about valid events. - -@smallexample -@group -(key-description [?\M-3 delete]) - @result{} "M-3 " -@end group -@group -(key-description [delete] "\M-3") - @result{} "M-3 " -@end group -@end smallexample - - See also the examples for @code{single-key-description}, below. -@end defun - -@defun single-key-description event &optional no-angles -@cindex event printing -@cindex character printing -@cindex control character printing -@cindex meta character printing -This function returns a string describing @var{event} in the standard -Emacs notation for keyboard input. A normal printing character -appears as itself, but a control character turns into a string -starting with @samp{C-}, a meta character turns into a string starting -with @samp{M-}, and space, tab, etc., appear as @samp{SPC}, -@samp{TAB}, etc. A function key symbol appears inside angle brackets -@samp{<@dots{}>}. An event that is a list appears as the name of the -symbol in the @sc{car} of the list, inside angle brackets. - -If the optional argument @var{no-angles} is non-@code{nil}, the angle -brackets around function keys and event symbols are omitted; this is -for compatibility with old versions of Emacs which didn't use the -brackets. - -@smallexample -@group -(single-key-description ?\C-x) - @result{} "C-x" -@end group -@group -(key-description "\C-x \M-y \n \t \r \f123") - @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3" -@end group -@group -(single-key-description 'delete) - @result{} "" -@end group -@group -(single-key-description 'C-mouse-1) - @result{} "" -@end group -@group -(single-key-description 'C-mouse-1 t) - @result{} "C-mouse-1" -@end group -@end smallexample -@end defun - -@defun text-char-description character -This function returns a string describing @var{character} in the -standard Emacs notation for characters that appear in text---like -@code{single-key-description}, except that control characters are -represented with a leading caret (which is how control characters in -Emacs buffers are usually displayed). Another difference is that -@code{text-char-description} recognizes the 2**7 bit as the Meta -character, whereas @code{single-key-description} uses the 2**27 bit -for Meta. - -@smallexample -@group -(text-char-description ?\C-c) - @result{} "^C" -@end group -@group -(text-char-description ?\M-m) - @result{} "\xed" -@end group -@group -(text-char-description ?\C-\M-m) - @result{} "\x8d" -@end group -@group -(text-char-description (+ 128 ?m)) - @result{} "M-m" -@end group -@group -(text-char-description (+ 128 ?\C-m)) - @result{} "M-^M" -@end group -@end smallexample -@end defun - -@deffn Command read-kbd-macro string &optional need-vector -This function is used mainly for operating on keyboard macros, but it -can also be used as a rough inverse for @code{key-description}. You -call it with a string containing key descriptions, separated by spaces; -it returns a string or vector containing the corresponding events. -(This may or may not be a single valid key sequence, depending on what -events you use; @pxref{Key Sequences}.) If @var{need-vector} is -non-@code{nil}, the return value is always a vector. -@end deffn - -@node Help Functions -@section Help Functions - - Emacs provides a variety of built-in help functions, all accessible to -the user as subcommands of the prefix @kbd{C-h}. For more information -about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here -we describe some program-level interfaces to the same information. - -@deffn Command apropos pattern &optional do-all -This function finds all ``meaningful'' symbols whose names contain a -match for the apropos pattern @var{pattern}. An apropos pattern is -either a word to match, a space-separated list of words of which at -least two must match, or a regular expression (if any special regular -expression characters occur). A symbol is ``meaningful'' if it has a -definition as a function, variable, or face, or has properties. - -The function returns a list of elements that look like this: - -@example -(@var{symbol} @var{score} @var{function-doc} @var{variable-doc} - @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc}) -@end example - -Here, @var{score} is an integer measure of how important the symbol -seems to be as a match. Each of the remaining elements is a -documentation string, or @code{nil}, for @var{symbol} as a function, -variable, etc. - -It also displays the symbols in a buffer named @file{*Apropos*}, each -with a one-line description taken from the beginning of its -documentation string. - -If @var{do-all} is non-@code{nil}, or if the user option -@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also -shows key bindings for the functions that are found; it also shows -@emph{all} interned symbols, not just meaningful ones (and it lists -them in the return value as well). -@end deffn - -@defvar help-map -The value of this variable is a local keymap for characters following the -Help key, @kbd{C-h}. -@end defvar - -@deffn {Prefix Command} help-command -This symbol is not a function; its function definition cell holds the -keymap known as @code{help-map}. It is defined in @file{help.el} as -follows: - -@smallexample -@group -(define-key global-map (string help-char) 'help-command) -(fset 'help-command help-map) -@end group -@end smallexample -@end deffn - -@defopt help-char -The value of this variable is the help character---the character that -Emacs recognizes as meaning Help. By default, its value is 8, which -stands for @kbd{C-h}. When Emacs reads this character, if -@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that -expression, and displays the result in a window if it is a string. - -Usually the value of @code{help-form} is @code{nil}. Then the -help character has no special meaning at the level of command input, and -it becomes part of a key sequence in the normal way. The standard key -binding of @kbd{C-h} is a prefix key for several general-purpose help -features. - -The help character is special after prefix keys, too. If it has no -binding as a subcommand of the prefix key, it runs -@code{describe-prefix-bindings}, which displays a list of all the -subcommands of the prefix key. -@end defopt - -@defopt help-event-list -The value of this variable is a list of event types that serve as -alternative ``help characters''. These events are handled just like the -event specified by @code{help-char}. -@end defopt - -@defvar help-form -If this variable is non-@code{nil}, its value is a form to evaluate -whenever the character @code{help-char} is read. If evaluating the form -produces a string, that string is displayed. - -A command that calls @code{read-event}, @code{read-char-choice}, or -@code{read-char} probably should bind @code{help-form} to a -non-@code{nil} expression while it does input. (The time when you -should not do this is when @kbd{C-h} has some other meaning.) -Evaluating this expression should result in a string that explains -what the input is for and how to enter it properly. - -Entry to the minibuffer binds this variable to the value of -@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}). -@end defvar - -@defvar prefix-help-command -This variable holds a function to print help for a prefix key. The -function is called when the user types a prefix key followed by the help -character, and the help character has no binding after that prefix. The -variable's default value is @code{describe-prefix-bindings}. -@end defvar - -@deffn Command describe-prefix-bindings -This function calls @code{describe-bindings} to display a list of all -the subcommands of the prefix key of the most recent key sequence. The -prefix described consists of all but the last event of that key -sequence. (The last event is, presumably, the help character.) -@end deffn - - The following two functions are meant for modes that want to provide -help without relinquishing control, such as the ``electric'' modes. -Their names begin with @samp{Helper} to distinguish them from the -ordinary help functions. - -@deffn Command Helper-describe-bindings -This command pops up a window displaying a help buffer containing a -listing of all of the key bindings from both the local and global keymaps. -It works by calling @code{describe-bindings}. -@end deffn - -@deffn Command Helper-help -This command provides help for the current mode. It prompts the user -in the minibuffer with the message @samp{Help (Type ? for further -options)}, and then provides assistance in finding out what the key -bindings are, and what the mode is intended for. It returns @code{nil}. - -@vindex Helper-help-map -This can be customized by changing the map @code{Helper-help-map}. -@end deffn - -@defvar data-directory -@anchor{Definition of data-directory} -This variable holds the name of the directory in which Emacs finds -certain documentation and text files that come with Emacs. -@end defvar - -@defun help-buffer -This function returns the name of the help buffer, which is normally -@file{*Help*}; if such a buffer does not exist, it is first created. -@end defun - -@vindex help-window-select -@defmac with-help-window buffer-name body@dots{} -This macro evaluates @var{body} like @code{with-output-to-temp-buffer} -(@pxref{Temporary Displays}), inserting any output produced by its forms -into a buffer named @var{buffer-name}. (Usually, @var{buffer-name} -should be the value returned by the function @code{help-buffer}.) It -also puts the specified buffer into Help mode and displays a message -telling the user how to quit and scroll the help window. It selects the -help window if the current value of the user option -@code{help-window-select} has been set accordingly. It returns the last -value in @var{body}. -@end defmac - -@defun help-setup-xref item interactive-p -This function updates the cross reference data in the @file{*Help*} -buffer, which is used to regenerate the help information when the user -clicks on the @samp{Back} or @samp{Forward} buttons. Most commands -that use the @file{*Help*} buffer should invoke this function before -clearing the buffer. The @var{item} argument should have the form -@code{(@var{function} . @var{args})}, where @var{function} is a function -to call, with argument list @var{args}, to regenerate the help buffer. -The @var{interactive-p} argument is non-@code{nil} if the calling -command was invoked interactively; in that case, the stack of items -for the @file{*Help*} buffer's @samp{Back} buttons is cleared. -@end defun - -@xref{describe-symbols example}, for an example of using -@code{help-buffer}, @code{with-help-window}, and -@code{help-setup-xref}. - -@defmac make-help-screen fname help-line help-text help-map -This macro defines a help command named @var{fname} that acts like a -prefix key that shows a list of the subcommands it offers. - -When invoked, @var{fname} displays @var{help-text} in a window, then -reads and executes a key sequence according to @var{help-map}. The -string @var{help-text} should describe the bindings available in -@var{help-map}. - -The command @var{fname} is defined to handle a few events itself, by -scrolling the display of @var{help-text}. When @var{fname} reads one of -those special events, it does the scrolling and then reads another -event. When it reads an event that is not one of those few, and which -has a binding in @var{help-map}, it executes that key's binding and -then returns. - -The argument @var{help-line} should be a single-line summary of the -alternatives in @var{help-map}. In the current version of Emacs, this -argument is used only if you set the option @code{three-step-help} to -@code{t}. - -This macro is used in the command @code{help-for-help} which is the -binding of @kbd{C-h C-h}. -@end defmac - -@defopt three-step-help -If this variable is non-@code{nil}, commands defined with -@code{make-help-screen} display their @var{help-line} strings in the -echo area at first, and display the longer @var{help-text} strings only -if the user types the help character again. -@end defopt diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi deleted file mode 100644 index 547a2ffe442..00000000000 --- a/doc/lispref/hooks.texi +++ /dev/null @@ -1,278 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998, 2001-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Standard Hooks -@appendix Standard Hooks -@cindex standard hooks -@cindex hook variables, list of - -The following is a list of some hook variables that let you provide -functions to be called from within Emacs on suitable occasions. - -Most of these variables have names ending with @samp{-hook}. They are -@dfn{normal hooks}, run by means of @code{run-hooks}. The value of such -a hook is a list of functions; the functions are called with no -arguments and their values are completely ignored. The recommended way -to put a new function on such a hook is to call @code{add-hook}. -@xref{Hooks}, for more information about using hooks. - -The variables whose names end in @samp{-functions} are usually @dfn{abnormal -hooks} (some old code may also use the deprecated @samp{-hooks} suffix); their -values are lists of functions, but these functions are called in a special way -(they are passed arguments, or their return values are used). The variables -whose names end in @samp{-function} have single functions as their values. - -This is not an exhaustive list, it only covers the more general hooks. -For example, every major mode defines a hook named -@samp{@var{modename}-mode-hook}. The major mode command runs this -normal hook with @code{run-mode-hooks} as the very last thing it does. -@xref{Mode Hooks}. Most minor modes have mode hooks too. - -A special feature allows you to specify expressions to evaluate if and -when a file is loaded (@pxref{Hooks for Loading}). That feature is -not exactly a hook, but does a similar job. - -@c We need to xref to where each hook is documented or else document it here. -@c Add vindex for anything not indexed elsewhere. -@c This list is in alphabetical order, grouped by topic. -@c TODO It should probably be more thoroughly ordered by topic. - -@table @code -@item activate-mark-hook -@itemx deactivate-mark-hook -@xref{The Mark}. - -@item after-change-functions -@itemx before-change-functions -@itemx first-change-hook -@xref{Change Hooks}. - -@item after-change-major-mode-hook -@itemx change-major-mode-after-body-hook -@xref{Mode Hooks}. - -@item after-init-hook -@itemx before-init-hook -@itemx emacs-startup-hook -@itemx window-setup-hook -@xref{Init File}. - -@item after-insert-file-functions -@itemx write-region-annotate-functions -@itemx write-region-post-annotation-function -@xref{Format Conversion}. - -@item after-make-frame-functions -@itemx before-make-frame-hook -@xref{Creating Frames}. - -@c Not general enough? -@ignore -@item after-revert-hook -@itemx before-revert-hook -@itemx buffer-stale-function -@itemx revert-buffer-function -@itemx revert-buffer-insert-file-contents-function -@xref{Reverting}. -@end ignore - -@item after-save-hook -@itemx before-save-hook -@itemx write-contents-functions -@itemx write-file-functions -@xref{Saving Buffers}. - -@item after-setting-font-hook -@vindex after-setting-font-hook -Hook run after a frame's font changes. - -@item auto-save-hook -@xref{Auto-Saving}. - -@item before-hack-local-variables-hook -@itemx hack-local-variables-hook -@xref{File Local Variables}. - -@item buffer-access-fontify-functions -@xref{Lazy Properties}. - -@item buffer-list-update-hook -@vindex buffer-list-update-hook -Hook run when the buffer list changes (@pxref{Buffer List}). - -@item buffer-quit-function -@vindex buffer-quit-function -Function to call to ``quit'' the current buffer. - -@item change-major-mode-hook -@xref{Creating Buffer-Local}. - -@item command-line-functions -@xref{Command-Line Arguments}. - -@item delayed-warnings-hook -@vindex delayed-warnings-hook -The command loop runs this soon after @code{post-command-hook} (q.v.). - -@item focus-in-hook -@vindex focus-in-hook -@itemx focus-out-hook -@vindex focus-out-hook -@xref{Input Focus}. - -@item delete-frame-functions -@xref{Deleting Frames}. - -@item delete-terminal-functions -@xref{Multiple Terminals}. - -@item pop-up-frame-function -@itemx split-window-preferred-function -@xref{Choosing Window Options}. - -@item echo-area-clear-hook -@xref{Echo Area Customization}. - -@item find-file-hook -@itemx find-file-not-found-functions -@xref{Visiting Functions}. - -@item font-lock-extend-after-change-region-function -@xref{Region to Refontify}. - -@item font-lock-extend-region-functions -@xref{Multiline Font Lock}. - -@item font-lock-fontify-buffer-function -@itemx font-lock-fontify-region-function -@itemx font-lock-mark-block-function -@itemx font-lock-unfontify-buffer-function -@itemx font-lock-unfontify-region-function -@xref{Other Font Lock Variables}. - -@item fontification-functions -@xref{Auto Faces,, Automatic Face Assignment}. - -@item frame-auto-hide-function -@xref{Quitting Windows}. - -@item kill-buffer-hook -@itemx kill-buffer-query-functions -@xref{Killing Buffers}. - -@item kill-emacs-hook -@itemx kill-emacs-query-functions -@xref{Killing Emacs}. - -@item menu-bar-update-hook -@xref{Menu Bar}. - -@item minibuffer-setup-hook -@itemx minibuffer-exit-hook -@xref{Minibuffer Misc}. - -@item mouse-leave-buffer-hook -@vindex mouse-leave-buffer-hook -Hook run when about to switch windows with a mouse command. - -@item mouse-position-function -@xref{Mouse Position}. - -@item post-command-hook -@itemx pre-command-hook -@xref{Command Overview}. - -@item post-gc-hook -@xref{Garbage Collection}. - -@item post-self-insert-hook -@xref{Keymaps and Minor Modes}. - -@ignore -@item prog-mode-hook -@itemx special-mode-hook -@vindex special-mode-hook -@xref{Basic Major Modes}. -@end ignore - -@item suspend-hook -@itemx suspend-resume-hook -@itemx suspend-tty-functions -@itemx resume-tty-functions -@xref{Suspending Emacs}. - -@item syntax-begin-function -@itemx syntax-propertize-extend-region-functions -@itemx syntax-propertize-function -@itemx font-lock-syntactic-face-function -@xref{Syntactic Font Lock}. @xref{Syntax Properties}. - -@item temp-buffer-setup-hook -@itemx temp-buffer-show-function -@itemx temp-buffer-show-hook -@xref{Temporary Displays}. - -@item tty-setup-hook -@xref{Terminal-Specific}. - -@item window-configuration-change-hook -@itemx window-scroll-functions -@itemx window-size-change-functions -@xref{Window Hooks}. - -@item window-text-change-functions -@vindex window-text-change-functions -Functions to call in redisplay when text in the window might change. - -@end table - -@ignore -Some -hook, -function, -functions from preloaded Lisp or C files that -I thought did not need to be mentioned here: - -Lisp: -after-load-functions -auto-coding-functions -choose-completion-string-functions -completing-read-function -completion-annotate-function -completion-at-point-functions -completion-list-insert-choice-function -deactivate-current-input-method-function -describe-current-input-method-function -font-lock-function -menu-bar-select-buffer-function -read-file-name-function -replace-re-search-function -replace-search-function -yank-undo-function - -C hooks: -kbd-macro-termination-hook -signal-hook-function - -C functions: -redisplay-end-trigger-functions -x-lost-selection-functions -x-sent-selection-functions - -C function: -auto-composition-function -auto-fill-function -command-error-function -compose-chars-after-function -composition-function-table -deferred-action-function -input-method-function -load-read-function -load-source-file-function -read-buffer-function -ring-bell-function -select-safe-coding-system-function -set-auto-coding-function -show-help-function -signal-hook-function -undo-outer-limit-function - -@end ignore diff --git a/doc/lispref/index.texi b/doc/lispref/index.texi deleted file mode 100644 index 3f31c5dd656..00000000000 --- a/doc/lispref/index.texi +++ /dev/null @@ -1,26 +0,0 @@ -@c -*-texinfo-*- - -@c Indexing guidelines - -@c I assume that all indexes will be combined. -@c Therefore, if a generated findex and permutations -@c cover the ways an index user would look up the entry, -@c then no cindex is added. -@c Concept index (cindex) entries will also be permuted. Therefore, they -@c have no commas and few irrelevant connectives in them. - -@c I tried to include words in a cindex that give the context of the entry, -@c particularly if there is more than one entry for the same concept. -@c For example, "nil in keymap" -@c Similarly for explicit findex and vindex entries, e.g., "print example". - -@c Error codes are given cindex entries, e.g., "end-of-file error". - -@c pindex is used for .el files and Unix programs - -@node Index -@unnumbered Index - -@c Print the indices - -@printindex fn diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi deleted file mode 100644 index bfc9d491c5e..00000000000 --- a/doc/lispref/internals.texi +++ /dev/null @@ -1,1652 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node GNU Emacs Internals -@appendix GNU Emacs Internals - -This chapter describes how the runnable Emacs executable is dumped with -the preloaded Lisp libraries in it, how storage is allocated, and some -internal aspects of GNU Emacs that may be of interest to C programmers. - -@menu -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: Kludge to make preloaded Lisp functions shareable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* C Dialect:: What C variant Emacs is written in. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. -* C Integer Types:: How C integer types are used inside Emacs. -@end menu - -@node Building Emacs -@section Building Emacs -@cindex building Emacs -@pindex temacs - - This section explains the steps involved in building the Emacs -executable. You don't have to know this material to build and install -Emacs, since the makefiles do all these things automatically. This -information is pertinent to Emacs developers. - - Compilation of the C source files in the @file{src} directory -produces an executable file called @file{temacs}, also called a -@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and -I/O routines, but not the editing commands. - -@cindex @file{loadup.el} - The command @w{@command{temacs -l loadup}} would run @file{temacs} -and direct it to load @file{loadup.el}. The @code{loadup} library -loads additional Lisp libraries, which set up the normal Emacs editing -environment. After this step, the Emacs executable is no longer -@dfn{bare}. - -@cindex dumping Emacs - Because it takes some time to load the standard Lisp files, the -@file{temacs} executable usually isn't run directly by users. -Instead, as one of the last steps of building Emacs, the command -@samp{temacs -batch -l loadup dump} is run. The special @samp{dump} -argument causes @command{temacs} to dump out an executable program, -called @file{emacs}, which has all the standard Lisp files preloaded. -(The @samp{-batch} argument prevents @file{temacs} from trying to -initialize any of its data on the terminal, so that the tables of -terminal information are empty in the dumped Emacs.) - -@cindex preloaded Lisp files -@vindex preloaded-file-list - The dumped @file{emacs} executable (also called a @dfn{pure} Emacs) -is the one which is installed. The variable -@code{preloaded-file-list} stores a list of the Lisp files preloaded -into the dumped Emacs. If you port Emacs to a new operating system, -and are not able to implement dumping, then Emacs must load -@file{loadup.el} each time it starts. - -@cindex @file{site-load.el} - You can specify additional files to preload by writing a library named -@file{site-load.el} that loads them. You may need to rebuild Emacs -with an added definition - -@example -#define SITELOAD_PURESIZE_EXTRA @var{n} -@end example - -@noindent -to make @var{n} added bytes of pure space to hold the additional files; -see @file{src/puresize.h}. -(Try adding increments of 20000 until it is big enough.) However, the -advantage of preloading additional files decreases as machines get -faster. On modern machines, it is usually not advisable. - - After @file{loadup.el} reads @file{site-load.el}, it finds the -documentation strings for primitive and preloaded functions (and -variables) in the file @file{etc/DOC} where they are stored, by -calling @code{Snarf-documentation} (@pxref{Definition of -Snarf-documentation,, Accessing Documentation}). - -@cindex @file{site-init.el} -@cindex preloading additional functions and variables - You can specify other Lisp expressions to execute just before dumping -by putting them in a library named @file{site-init.el}. This file is -executed after the documentation strings are found. - - If you want to preload function or variable definitions, there are -three ways you can do this and make their documentation strings -accessible when you subsequently run Emacs: - -@itemize @bullet -@item -Arrange to scan these files when producing the @file{etc/DOC} file, -and load them with @file{site-load.el}. - -@item -Load the files with @file{site-init.el}, then copy the files into the -installation directory for Lisp files when you install Emacs. - -@item -Specify a @code{nil} value for @code{byte-compile-dynamic-docstrings} -as a local variable in each of these files, and load them with either -@file{site-load.el} or @file{site-init.el}. (This method has the -drawback that the documentation strings take up space in Emacs all the -time.) -@end itemize - -@cindex change @code{load-path} at configure time -@cindex @option{--enable-locallisppath} option to @command{configure} - It is not advisable to put anything in @file{site-load.el} or -@file{site-init.el} that would alter any of the features that users -expect in an ordinary unmodified Emacs. If you feel you must override -normal features for your site, do it with @file{default.el}, so that -users can override your changes if they wish. @xref{Startup Summary}. -Note that if either @file{site-load.el} or @file{site-init.el} changes -@code{load-path}, the changes will be lost after dumping. -@xref{Library Search}. To make a permanent change to -@code{load-path}, use the @option{--enable-locallisppath} option -of @command{configure}. - - In a package that can be preloaded, it is sometimes necessary (or -useful) to delay certain evaluations until Emacs subsequently starts -up. The vast majority of such cases relate to the values of -customizable variables. For example, @code{tutorial-directory} is a -variable defined in @file{startup.el}, which is preloaded. The default -value is set based on @code{data-directory}. The variable needs to -access the value of @code{data-directory} when Emacs starts, not when -it is dumped, because the Emacs executable has probably been installed -in a different location since it was dumped. - -@defun custom-initialize-delay symbol value -This function delays the initialization of @var{symbol} to the next -Emacs start. You normally use this function by specifying it as the -@code{:initialize} property of a customizable variable. (The argument -@var{value} is unused, and is provided only for compatibility with the -form Custom expects.) -@end defun - -In the unlikely event that you need a more general functionality than -@code{custom-initialize-delay} provides, you can use -@code{before-init-hook} (@pxref{Startup Summary}). - -@defun dump-emacs to-file from-file -@cindex unexec -This function dumps the current state of Emacs into an executable file -@var{to-file}. It takes symbols from @var{from-file} (this is normally -the executable file @file{temacs}). - -If you want to use this function in an Emacs that was already dumped, -you must run Emacs with @samp{-batch}. -@end defun - -@node Pure Storage -@section Pure Storage -@cindex pure storage - - Emacs Lisp uses two kinds of storage for user-created Lisp objects: -@dfn{normal storage} and @dfn{pure storage}. Normal storage is where -all the new data created during an Emacs session are kept -(@pxref{Garbage Collection}). Pure storage is used for certain data -in the preloaded standard Lisp files---data that should never change -during actual use of Emacs. - - Pure storage is allocated only while @command{temacs} is loading the -standard preloaded Lisp libraries. In the file @file{emacs}, it is -marked as read-only (on operating systems that permit this), so that -the memory space can be shared by all the Emacs jobs running on the -machine at once. Pure storage is not expandable; a fixed amount is -allocated when Emacs is compiled, and if that is not sufficient for -the preloaded libraries, @file{temacs} allocates dynamic memory for -the part that didn't fit. The resulting image will work, but garbage -collection (@pxref{Garbage Collection}) is disabled in this situation, -causing a memory leak. Such an overflow normally won't happen unless -you try to preload additional libraries or add features to the -standard ones. Emacs will display a warning about the overflow when -it starts. If this happens, you should increase the compilation -parameter @code{SYSTEM_PURESIZE_EXTRA} in the file -@file{src/puresize.h} and rebuild Emacs. - -@defun purecopy object -This function makes a copy in pure storage of @var{object}, and returns -it. It copies a string by simply making a new string with the same -characters, but without text properties, in pure storage. It -recursively copies the contents of vectors and cons cells. It does -not make copies of other objects such as symbols, but just returns -them unchanged. It signals an error if asked to copy markers. - -This function is a no-op except while Emacs is being built and dumped; -it is usually called only in preloaded Lisp files. -@end defun - -@defvar pure-bytes-used -The value of this variable is the number of bytes of pure storage -allocated so far. Typically, in a dumped Emacs, this number is very -close to the total amount of pure storage available---if it were not, -we would preallocate less. -@end defvar - -@defvar purify-flag -This variable determines whether @code{defun} should make a copy of the -function definition in pure storage. If it is non-@code{nil}, then the -function definition is copied into pure storage. - -This flag is @code{t} while loading all of the basic functions for -building Emacs initially (allowing those functions to be shareable and -non-collectible). Dumping Emacs as an executable always writes -@code{nil} in this variable, regardless of the value it actually has -before and after dumping. - -You should not change this flag in a running Emacs. -@end defvar - -@node Garbage Collection -@section Garbage Collection - -@cindex memory allocation - When a program creates a list or the user defines a new function -(such as by loading a library), that data is placed in normal storage. -If normal storage runs low, then Emacs asks the operating system to -allocate more memory. Different types of Lisp objects, such as -symbols, cons cells, small vectors, markers, etc., are segregated in -distinct blocks in memory. (Large vectors, long strings, buffers and -certain other editing types, which are fairly large, are allocated in -individual blocks, one per object; small strings are packed into blocks -of 8k bytes, and small vectors are packed into blocks of 4k bytes). - -@cindex vector-like objects, storage -@cindex storage of vector-like Lisp objects - Beyond the basic vector, a lot of objects like window, buffer, and -frame are managed as if they were vectors. The corresponding C data -structures include the @code{struct vectorlike_header} field whose -@code{size} member contains the subtype enumerated by @code{enum pvec_type} -and an information about how many @code{Lisp_Object} fields this structure -contains and what the size of the rest data is. This information is -needed to calculate the memory footprint of an object, and used -by the vector allocation code while iterating over the vector blocks. - -@cindex garbage collection - It is quite common to use some storage for a while, then release it -by (for example) killing a buffer or deleting the last pointer to an -object. Emacs provides a @dfn{garbage collector} to reclaim this -abandoned storage. The garbage collector operates by finding and -marking all Lisp objects that are still accessible to Lisp programs. -To begin with, it assumes all the symbols, their values and associated -function definitions, and any data presently on the stack, are -accessible. Any objects that can be reached indirectly through other -accessible objects are also accessible. - - When marking is finished, all objects still unmarked are garbage. No -matter what the Lisp program or the user does, it is impossible to refer -to them, since there is no longer a way to reach them. Their space -might as well be reused, since no one will miss them. The second -(``sweep'') phase of the garbage collector arranges to reuse them. - -@c ??? Maybe add something describing weak hash tables here? - -@cindex free list - The sweep phase puts unused cons cells onto a @dfn{free list} -for future allocation; likewise for symbols and markers. It compacts -the accessible strings so they occupy fewer 8k blocks; then it frees the -other 8k blocks. Unreachable vectors from vector blocks are coalesced -to create largest possible free areas; if a free area spans a complete -4k block, that block is freed. Otherwise, the free area is recorded -in a free list array, where each entry corresponds to a free list -of areas of the same size. Large vectors, buffers, and other large -objects are allocated and freed individually. - -@cindex CL note---allocate more storage -@quotation -@b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not -call the garbage collector when the free list is empty. Instead, it -simply requests the operating system to allocate more storage, and -processing continues until @code{gc-cons-threshold} bytes have been -used. - -This means that you can make sure that the garbage collector will not -run during a certain portion of a Lisp program by calling the garbage -collector explicitly just before it (provided that portion of the -program does not use so much space as to force a second garbage -collection). -@end quotation - -@deffn Command garbage-collect -This command runs a garbage collection, and returns information on -the amount of space in use. (Garbage collection can also occur -spontaneously if you use more than @code{gc-cons-threshold} bytes of -Lisp data since the previous garbage collection.) - -@code{garbage-collect} returns a list with information on amount of space in -use, where each entry has the form @samp{(@var{name} @var{size} @var{used})} -or @samp{(@var{name} @var{size} @var{used} @var{free})}. In the entry, -@var{name} is a symbol describing the kind of objects this entry represents, -@var{size} is the number of bytes used by each one, @var{used} is the number -of those objects that were found live in the heap, and optional @var{free} is -the number of those objects that are not live but that Emacs keeps around for -future allocations. So an overall result is: - -@example -((@code{conses} @var{cons-size} @var{used-conses} @var{free-conses}) - (@code{symbols} @var{symbol-size} @var{used-symbols} @var{free-symbols}) - (@code{miscs} @var{misc-size} @var{used-miscs} @var{free-miscs}) - (@code{strings} @var{string-size} @var{used-strings} @var{free-strings}) - (@code{string-bytes} @var{byte-size} @var{used-bytes}) - (@code{vectors} @var{vector-size} @var{used-vectors}) - (@code{vector-slots} @var{slot-size} @var{used-slots} @var{free-slots}) - (@code{floats} @var{float-size} @var{used-floats} @var{free-floats}) - (@code{intervals} @var{interval-size} @var{used-intervals} @var{free-intervals}) - (@code{buffers} @var{buffer-size} @var{used-buffers}) - (@code{heap} @var{unit-size} @var{total-size} @var{free-size})) -@end example - -Here is an example: - -@example -(garbage-collect) - @result{} ((conses 16 49126 8058) (symbols 48 14607 0) - (miscs 40 34 56) (strings 32 2942 2607) - (string-bytes 1 78607) (vectors 16 7247) - (vector-slots 8 341609 29474) (floats 8 71 102) - (intervals 56 27 26) (buffers 944 8) - (heap 1024 11715 2678)) -@end example - -Below is a table explaining each element. Note that last @code{heap} entry -is optional and present only if an underlying @code{malloc} implementation -provides @code{mallinfo} function. - -@table @var -@item cons-size -Internal size of a cons cell, i.e., @code{sizeof (struct Lisp_Cons)}. - -@item used-conses -The number of cons cells in use. - -@item free-conses -The number of cons cells for which space has been obtained from -the operating system, but that are not currently being used. - -@item symbol-size -Internal size of a symbol, i.e., @code{sizeof (struct Lisp_Symbol)}. - -@item used-symbols -The number of symbols in use. - -@item free-symbols -The number of symbols for which space has been obtained from -the operating system, but that are not currently being used. - -@item misc-size -Internal size of a miscellaneous entity, i.e., -@code{sizeof (union Lisp_Misc)}, which is a size of the -largest type enumerated in @code{enum Lisp_Misc_Type}. - -@item used-miscs -The number of miscellaneous objects in use. These include markers -and overlays, plus certain objects not visible to users. - -@item free-miscs -The number of miscellaneous objects for which space has been obtained -from the operating system, but that are not currently being used. - -@item string-size -Internal size of a string header, i.e., @code{sizeof (struct Lisp_String)}. - -@item used-strings -The number of string headers in use. - -@item free-strings -The number of string headers for which space has been obtained -from the operating system, but that are not currently being used. - -@item byte-size -This is used for convenience and equals to @code{sizeof (char)}. - -@item used-bytes -The total size of all string data in bytes. - -@item vector-size -Internal size of a vector header, i.e., @code{sizeof (struct Lisp_Vector)}. - -@item used-vectors -The number of vector headers allocated from the vector blocks. - -@item slot-size -Internal size of a vector slot, always equal to @code{sizeof (Lisp_Object)}. - -@item used-slots -The number of slots in all used vectors. - -@item free-slots -The number of free slots in all vector blocks. - -@item float-size -Internal size of a float object, i.e., @code{sizeof (struct Lisp_Float)}. -(Do not confuse it with the native platform @code{float} or @code{double}.) - -@item used-floats -The number of floats in use. - -@item free-floats -The number of floats for which space has been obtained from -the operating system, but that are not currently being used. - -@item interval-size -Internal size of an interval object, i.e., @code{sizeof (struct interval)}. - -@item used-intervals -The number of intervals in use. - -@item free-intervals -The number of intervals for which space has been obtained from -the operating system, but that are not currently being used. - -@item buffer-size -Internal size of a buffer, i.e., @code{sizeof (struct buffer)}. -(Do not confuse with the value returned by @code{buffer-size} function.) - -@item used-buffers -The number of buffer objects in use. This includes killed buffers -invisible to users, i.e., all buffers in @code{all_buffers} list. - -@item unit-size -The unit of heap space measurement, always equal to 1024 bytes. - -@item total-size -Total heap size, in @var{unit-size} units. - -@item free-size -Heap space which is not currently used, in @var{unit-size} units. -@end table - -If there was overflow in pure space (@pxref{Pure Storage}), -@code{garbage-collect} returns @code{nil}, because a real garbage -collection cannot be done. -@end deffn - -@defopt garbage-collection-messages -If this variable is non-@code{nil}, Emacs displays a message at the -beginning and end of garbage collection. The default value is -@code{nil}. -@end defopt - -@defvar post-gc-hook -This is a normal hook that is run at the end of garbage collection. -Garbage collection is inhibited while the hook functions run, so be -careful writing them. -@end defvar - -@defopt gc-cons-threshold -The value of this variable is the number of bytes of storage that must -be allocated for Lisp objects after one garbage collection in order to -trigger another garbage collection. You can use the result returned by -@code{garbage-collect} to get an information about size of the particular -object type; space allocated to the contents of buffers does not count. -Note that the subsequent garbage collection does not happen immediately -when the threshold is exhausted, but only the next time the Lisp interpreter -is called. - -The initial threshold value is @code{GC_DEFAULT_THRESHOLD}, defined in -@file{alloc.c}. Since it's defined in @code{word_size} units, the value -is 400,000 for the default 32-bit configuration and 800,000 for the 64-bit -one. If you specify a larger value, garbage collection will happen less -often. This reduces the amount of time spent garbage collecting, but -increases total memory use. You may want to do this when running a program -that creates lots of Lisp data. - -You can make collections more frequent by specifying a smaller value, down -to 1/10th of @code{GC_DEFAULT_THRESHOLD}. A value less than this minimum -will remain in effect only until the subsequent garbage collection, at which -time @code{garbage-collect} will set the threshold back to the minimum. -@end defopt - -@defopt gc-cons-percentage -The value of this variable specifies the amount of consing before a -garbage collection occurs, as a fraction of the current heap size. -This criterion and @code{gc-cons-threshold} apply in parallel, and -garbage collection occurs only when both criteria are satisfied. - -As the heap size increases, the time to perform a garbage collection -increases. Thus, it can be desirable to do them less frequently in -proportion. -@end defopt - - The value returned by @code{garbage-collect} describes the amount of -memory used by Lisp data, broken down by data type. By contrast, the -function @code{memory-limit} provides information on the total amount of -memory Emacs is currently using. - -@defun memory-limit -This function returns the address of the last byte Emacs has allocated, -divided by 1024. We divide the value by 1024 to make sure it fits in a -Lisp integer. - -You can use this to get a general idea of how your actions affect the -memory usage. -@end defun - -@defvar memory-full -This variable is @code{t} if Emacs is nearly out of memory for Lisp -objects, and @code{nil} otherwise. -@end defvar - -@defun memory-use-counts -This returns a list of numbers that count the number of objects -created in this Emacs session. Each of these counters increments for -a certain kind of object. See the documentation string for details. -@end defun - -@defvar gcs-done -This variable contains the total number of garbage collections -done so far in this Emacs session. -@end defvar - -@defvar gc-elapsed -This variable contains the total number of seconds of elapsed time -during garbage collection so far in this Emacs session, as a -floating-point number. -@end defvar - -@node Memory Usage -@section Memory Usage -@cindex memory usage - - These functions and variables give information about the total amount -of memory allocation that Emacs has done, broken down by data type. -Note the difference between these and the values returned by -@code{garbage-collect}; those count objects that currently exist, but -these count the number or size of all allocations, including those for -objects that have since been freed. - -@defvar cons-cells-consed -The total number of cons cells that have been allocated so far -in this Emacs session. -@end defvar - -@defvar floats-consed -The total number of floats that have been allocated so far -in this Emacs session. -@end defvar - -@defvar vector-cells-consed -The total number of vector cells that have been allocated so far -in this Emacs session. -@end defvar - -@defvar symbols-consed -The total number of symbols that have been allocated so far -in this Emacs session. -@end defvar - -@defvar string-chars-consed -The total number of string characters that have been allocated so far -in this session. -@end defvar - -@defvar misc-objects-consed -The total number of miscellaneous objects that have been allocated so -far in this session. These include markers and overlays, plus -certain objects not visible to users. -@end defvar - -@defvar intervals-consed -The total number of intervals that have been allocated so far -in this Emacs session. -@end defvar - -@defvar strings-consed -The total number of strings that have been allocated so far in this -Emacs session. -@end defvar - -@node C Dialect -@section C Dialect -@cindex C programming language - -The C part of Emacs is portable to C89: C99-specific features such as -@samp{} and @samp{inline} are not used without a check, -typically at configuration time, and the Emacs build procedure -provides a substitute implementation if necessary. Some C99 features, -such as declarations after statements, are too difficult to provide -substitutes for, so they are avoided entirely. - -At some point in the not-too-distant future the base C dialect will -change from C89 to C99, and eventually it will no doubt change to C11. - -@node Writing Emacs Primitives -@section Writing Emacs Primitives -@cindex primitive function internals -@cindex writing Emacs primitives - - Lisp primitives are Lisp functions implemented in C@. The details of -interfacing the C function so that Lisp can call it are handled by a few -C macros. The only way to really understand how to write new C code is -to read the source, but we can explain some things here. - - An example of a special form is the definition of @code{or}, from -@file{eval.c}. (An ordinary function would have the same general -appearance.) - -@cindex garbage collection protection -@smallexample -@group -DEFUN ("or", For, Sor, 0, UNEVALLED, 0, - doc: /* Eval args until one of them yields non-nil, then return -that value. -The remaining args are not evalled at all. -If all args return nil, return nil. -@end group -@group -usage: (or CONDITIONS ...) */) - (Lisp_Object args) -@{ - register Lisp_Object val = Qnil; - struct gcpro gcpro1; -@end group - -@group - GCPRO1 (args); -@end group - -@group - while (CONSP (args)) - @{ - val = eval_sub (XCAR (args)); - if (!NILP (val)) - break; - args = XCDR (args); - @} -@end group - -@group - UNGCPRO; - return val; -@} -@end group -@end smallexample - -@cindex @code{DEFUN}, C macro to define Lisp primitives - Let's start with a precise explanation of the arguments to the -@code{DEFUN} macro. Here is a template for them: - -@example -DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) -@end example - -@table @var -@item lname -This is the name of the Lisp symbol to define as the function name; in -the example above, it is @code{or}. - -@item fname -This is the C function name for this function. This is the name that -is used in C code for calling the function. The name is, by -convention, @samp{F} prepended to the Lisp name, with all dashes -(@samp{-}) in the Lisp name changed to underscores. Thus, to call -this function from C code, call @code{For}. - -@item sname -This is a C variable name to use for a structure that holds the data for -the subr object that represents the function in Lisp. This structure -conveys the Lisp symbol name to the initialization routine that will -create the symbol and store the subr object as its definition. By -convention, this name is always @var{fname} with @samp{F} replaced with -@samp{S}. - -@item min -This is the minimum number of arguments that the function requires. The -function @code{or} allows a minimum of zero arguments. - -@item max -This is the maximum number of arguments that the function accepts, if -there is a fixed maximum. Alternatively, it can be @code{UNEVALLED}, -indicating a special form that receives unevaluated arguments, or -@code{MANY}, indicating an unlimited number of evaluated arguments (the -equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are -macros. If @var{max} is a number, it must be more than @var{min} but -less than 8. - -@cindex interactive specification in primitives -@item interactive -This is an interactive specification, a string such as might be used -as the argument of @code{interactive} in a Lisp function. In the case -of @code{or}, it is 0 (a null pointer), indicating that @code{or} -cannot be called interactively. A value of @code{""} indicates a -function that should receive no arguments when called interactively. -If the value begins with a @samp{"(}, the string is evaluated as a -Lisp form. For example: - -@example -@group -DEFUN ("foo", Ffoo, Sfoo, 0, UNEVALLED, - "(list (read-char-by-name \"Insert character: \")\ - (prefix-numeric-value current-prefix-arg)\ - t))", - doc: /* @dots{} /*) -@end group -@end example - -@item doc -This is the documentation string. It uses C comment syntax rather -than C string syntax because comment syntax requires nothing special -to include multiple lines. The @samp{doc:} identifies the comment -that follows as the documentation string. The @samp{/*} and @samp{*/} -delimiters that begin and end the comment are not part of the -documentation string. - -If the last line of the documentation string begins with the keyword -@samp{usage:}, the rest of the line is treated as the argument list -for documentation purposes. This way, you can use different argument -names in the documentation string from the ones used in the C code. -@samp{usage:} is required if the function has an unlimited number of -arguments. - -All the usual rules for documentation strings in Lisp code -(@pxref{Documentation Tips}) apply to C code documentation strings -too. -@end table - - After the call to the @code{DEFUN} macro, you must write the -argument list for the C function, including the types for the -arguments. If the primitive accepts a fixed maximum number of Lisp -arguments, there must be one C argument for each Lisp argument, and -each argument must be of type @code{Lisp_Object}. (Various macros and -functions for creating values of type @code{Lisp_Object} are declared -in the file @file{lisp.h}.) If the primitive has no upper limit on -the number of Lisp arguments, it must have exactly two C arguments: -the first is the number of Lisp arguments, and the second is the -address of a block containing their values. These have types -@code{int} and @w{@code{Lisp_Object *}} respectively. Since -@code{Lisp_Object} can hold any Lisp object of any data type, you -can determine the actual data type only at run time; so if you want -a primitive to accept only a certain type of argument, you must check -the type explicitly using a suitable predicate (@pxref{Type Predicates}). -@cindex type checking internals - -@cindex @code{GCPRO} and @code{UNGCPRO} -@cindex protect C variables from garbage collection - Within the function @code{For} itself, note the use of the macros -@code{GCPRO1} and @code{UNGCPRO}. These macros are defined for the -sake of the few platforms which do not use Emacs' default -stack-marking garbage collector. The @code{GCPRO1} macro ``protects'' -a variable from garbage collection, explicitly informing the garbage -collector that that variable and all its contents must be as -accessible. GC protection is necessary in any function which can -perform Lisp evaluation by calling @code{eval_sub} or @code{Feval} as -a subroutine, either directly or indirectly. - - It suffices to ensure that at least one pointer to each object is -GC-protected. Thus, a particular local variable can do without -protection if it is certain that the object it points to will be -preserved by some other pointer (such as another local variable that -has a @code{GCPRO}). Otherwise, the local variable needs a -@code{GCPRO}. - - The macro @code{GCPRO1} protects just one local variable. If you -want to protect two variables, use @code{GCPRO2} instead; repeating -@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4}, -@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros -implicitly use local variables such as @code{gcpro1}; you must declare -these explicitly, with type @code{struct gcpro}. Thus, if you use -@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. - - @code{UNGCPRO} cancels the protection of the variables that are -protected in the current function. It is necessary to do this -explicitly. - - You must not use C initializers for static or global variables unless -the variables are never written once Emacs is dumped. These variables -with initializers are allocated in an area of memory that becomes -read-only (on certain operating systems) as a result of dumping Emacs. -@xref{Pure Storage}. - -@cindex @code{defsubr}, Lisp symbol for a primitive - Defining the C function is not enough to make a Lisp primitive -available; you must also create the Lisp symbol for the primitive and -store a suitable subr object in its function cell. The code looks like -this: - -@example -defsubr (&@var{sname}); -@end example - -@noindent -Here @var{sname} is the name you used as the third argument to @code{DEFUN}. - - If you add a new primitive to a file that already has Lisp primitives -defined in it, find the function (near the end of the file) named -@code{syms_of_@var{something}}, and add the call to @code{defsubr} -there. If the file doesn't have this function, or if you create a new -file, add to it a @code{syms_of_@var{filename}} (e.g., -@code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all -of these functions are called, and add a call to -@code{syms_of_@var{filename}} there. - -@anchor{Defining Lisp variables in C} -@vindex byte-boolean-vars -@cindex defining Lisp variables in C -@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL} - The function @code{syms_of_@var{filename}} is also the place to define -any C variables that are to be visible as Lisp variables. -@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible -in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int} -visible in Lisp with a value that is always an integer. -@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp -with a value that is either @code{t} or @code{nil}. Note that variables -defined with @code{DEFVAR_BOOL} are automatically added to the list -@code{byte-boolean-vars} used by the byte compiler. - -@cindex defining customization variables in C - If you want to make a Lisp variables that is defined in C behave -like one declared with @code{defcustom}, add an appropriate entry to -@file{cus-start.el}. - -@cindex @code{staticpro}, protection from GC - If you define a file-scope C variable of type @code{Lisp_Object}, -you must protect it from garbage-collection by calling @code{staticpro} -in @code{syms_of_@var{filename}}, like this: - -@example -staticpro (&@var{variable}); -@end example - - Here is another example function, with more complicated arguments. -This comes from the code in @file{window.c}, and it demonstrates the use -of macros and functions to manipulate Lisp objects. - -@smallexample -@group -DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, - Scoordinates_in_window_p, 2, 2, 0, - doc: /* Return non-nil if COORDINATES are in WINDOW. - ... -@end group -@group - or `right-margin' is returned. */) - (register Lisp_Object coordinates, Lisp_Object window) -@{ - struct window *w; - struct frame *f; - int x, y; - Lisp_Object lx, ly; -@end group - -@group - CHECK_LIVE_WINDOW (window); - w = XWINDOW (window); - f = XFRAME (w->frame); - CHECK_CONS (coordinates); - lx = Fcar (coordinates); - ly = Fcdr (coordinates); - CHECK_NUMBER_OR_FLOAT (lx); - CHECK_NUMBER_OR_FLOAT (ly); - x = FRAME_PIXEL_X_FROM_CANON_X (f, lx) + FRAME_INTERNAL_BORDER_WIDTH(f); - y = FRAME_PIXEL_Y_FROM_CANON_Y (f, ly) + FRAME_INTERNAL_BORDER_WIDTH(f); -@end group - -@group - switch (coordinates_in_window (w, x, y)) - @{ - case ON_NOTHING: /* NOT in window at all. */ - return Qnil; -@end group - - ... - -@group - case ON_MODE_LINE: /* In mode line of window. */ - return Qmode_line; -@end group - - ... - -@group - case ON_SCROLL_BAR: /* On scroll-bar of window. */ - /* Historically we are supposed to return nil in this case. */ - return Qnil; -@end group - -@group - default: - abort (); - @} -@} -@end group -@end smallexample - - Note that C code cannot call functions by name unless they are defined -in C@. The way to call a function written in Lisp is to use -@code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since -the Lisp function @code{funcall} accepts an unlimited number of -arguments, in C it takes two: the number of Lisp-level arguments, and a -one-dimensional array containing their values. The first Lisp-level -argument is the Lisp function to call, and the rest are the arguments to -pass to it. Since @code{Ffuncall} can call the evaluator, you must -protect pointers from garbage collection around the call to -@code{Ffuncall}. - - The C functions @code{call0}, @code{call1}, @code{call2}, and so on, -provide handy ways to call a Lisp function conveniently with a fixed -number of arguments. They work by calling @code{Ffuncall}. - - @file{eval.c} is a very good file to look through for examples; -@file{lisp.h} contains the definitions for some important macros and -functions. - - If you define a function which is side-effect free, update the code -in @file{byte-opt.el} that binds @code{side-effect-free-fns} and -@code{side-effect-and-error-free-fns} so that the compiler optimizer -knows about it. - -@node Object Internals -@section Object Internals -@cindex object internals - - Emacs Lisp provides a rich set of the data types. Some of them, like cons -cells, integers and strings, are common to nearly all Lisp dialects. Some -others, like markers and buffers, are quite special and needed to provide -the basic support to write editor commands in Lisp. To implement such -a variety of object types and provide an efficient way to pass objects between -the subsystems of an interpreter, there is a set of C data structures and -a special type to represent the pointers to all of them, which is known as -@dfn{tagged pointer}. - - In C, the tagged pointer is an object of type @code{Lisp_Object}. Any -initialized variable of such a type always holds the value of one of the -following basic data types: integer, symbol, string, cons cell, float, -vectorlike or miscellaneous object. Each of these data types has the -corresponding tag value. All tags are enumerated by @code{enum Lisp_Type} -and placed into a 3-bit bitfield of the @code{Lisp_Object}. The rest of the -bits is the value itself. Integers are immediate, i.e., directly -represented by those @dfn{value bits}, and all other objects are represented -by the C pointers to a corresponding object allocated from the heap. Width -of the @code{Lisp_Object} is platform- and configuration-dependent: usually -it's equal to the width of an underlying platform pointer (i.e., 32-bit on -a 32-bit machine and 64-bit on a 64-bit one), but also there is a special -configuration where @code{Lisp_Object} is 64-bit but all pointers are 32-bit. -The latter trick was designed to overcome the limited range of values for -Lisp integers on a 32-bit system by using 64-bit @code{long long} type for -@code{Lisp_Object}. - - The following C data structures are defined in @file{lisp.h} to represent -the basic data types beyond integers: - -@table @code -@item struct Lisp_Cons -Cons cell, an object used to construct lists. - -@item struct Lisp_String -String, the basic object to represent a sequence of characters. - -@item struct Lisp_Vector -Array, a fixed-size set of Lisp objects which may be accessed by an index. - -@item struct Lisp_Symbol -Symbol, the unique-named entity commonly used as an identifier. - -@item struct Lisp_Float -Floating-point value. - -@item union Lisp_Misc -Miscellaneous kinds of objects which don't fit into any of the above. -@end table - - These types are the first-class citizens of an internal type system. -Since the tag space is limited, all other types are the subtypes of either -@code{Lisp_Vectorlike} or @code{Lisp_Misc}. Vector subtypes are enumerated -by @code{enum pvec_type}, and nearly all complex objects like windows, buffers, -frames, and processes fall into this category. The rest of special types, -including markers and overlays, are enumerated by @code{enum Lisp_Misc_Type} -and form the set of subtypes of @code{Lisp_Misc}. - - Below there is a description of a few subtypes of @code{Lisp_Vectorlike}. -Buffer object represents the text to display and edit. Window is the part -of display structure which shows the buffer or used as a container to -recursively place other windows on the same frame. (Do not confuse Emacs Lisp -window object with the window as an entity managed by the user interface -system like X; in Emacs terminology, the latter is called frame.) Finally, -process object is used to manage the subprocesses. - -@menu -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end menu - -@node Buffer Internals -@subsection Buffer Internals -@cindex internals, of buffer -@cindex buffer internals - - Two structures (see @file{buffer.h}) are used to represent buffers -in C@. The @code{buffer_text} structure contains fields describing the -text of a buffer; the @code{buffer} structure holds other fields. In -the case of indirect buffers, two or more @code{buffer} structures -reference the same @code{buffer_text} structure. - -Here are some of the fields in @code{struct buffer_text}: - -@table @code -@item beg -The address of the buffer contents. - -@item gpt -@itemx gpt_byte -The character and byte positions of the buffer gap. @xref{Buffer -Gap}. - -@item z -@itemx z_byte -The character and byte positions of the end of the buffer text. - -@item gap_size -The size of buffer's gap. @xref{Buffer Gap}. - -@item modiff -@itemx save_modiff -@itemx chars_modiff -@itemx overlay_modiff -These fields count the number of buffer-modification events performed -in this buffer. @code{modiff} is incremented after each -buffer-modification event, and is never otherwise changed; -@code{save_modiff} contains the value of @code{modiff} the last time -the buffer was visited or saved; @code{chars_modiff} counts only -modifications to the characters in the buffer, ignoring all other -kinds of changes; and @code{overlay_modiff} counts only modifications -to the overlays. - -@item beg_unchanged -@itemx end_unchanged -The number of characters at the start and end of the text that are -known to be unchanged since the last complete redisplay. - -@item unchanged_modified -@itemx overlay_unchanged_modified -The values of @code{modiff} and @code{overlay_modiff}, respectively, -after the last complete redisplay. If their current values match -@code{modiff} or @code{overlay_modiff}, that means -@code{beg_unchanged} and @code{end_unchanged} contain no useful -information. - -@item markers -The markers that refer to this buffer. This is actually a single -marker, and successive elements in its marker @code{chain} are the other -markers referring to this buffer text. - -@item intervals -The interval tree which records the text properties of this buffer. -@end table - -Some of the fields of @code{struct buffer} are: - -@table @code -@item header -A header of type @code{struct vectorlike_header} is common to all -vectorlike objects. - -@item own_text -A @code{struct buffer_text} structure that ordinarily holds the buffer -contents. In indirect buffers, this field is not used. - -@item text -A pointer to the @code{buffer_text} structure for this buffer. In an -ordinary buffer, this is the @code{own_text} field above. In an -indirect buffer, this is the @code{own_text} field of the base buffer. - -@item next -A pointer to the next buffer, in the chain of all buffers, including -killed buffers. This chain is used only for allocation and garbage -collection, in order to collect killed buffers properly. - -@item pt -@itemx pt_byte -The character and byte positions of point in a buffer. - -@item begv -@itemx begv_byte -The character and byte positions of the beginning of the accessible -range of text in the buffer. - -@item zv -@itemx zv_byte -The character and byte positions of the end of the accessible range of -text in the buffer. - -@item base_buffer -In an indirect buffer, this points to the base buffer. In an ordinary -buffer, it is null. - -@item local_flags -This field contains flags indicating that certain variables are local -in this buffer. Such variables are declared in the C code using -@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored -in fields in the buffer structure itself. (Some of these fields are -described in this table.) - -@item modtime -The modification time of the visited file. It is set when the file is -written or read. Before writing the buffer into a file, this field is -compared to the modification time of the file to see if the file has -changed on disk. @xref{Buffer Modification}. - -@item auto_save_modified -The time when the buffer was last auto-saved. - -@item last_window_start -The @code{window-start} position in the buffer as of the last time the -buffer was displayed in a window. - -@item clip_changed -This flag indicates that narrowing has changed in the buffer. -@xref{Narrowing}. - -@item prevent_redisplay_optimizations_p -This flag indicates that redisplay optimizations should not be used to -display this buffer. - -@item overlay_center -This field holds the current overlay center position. @xref{Managing -Overlays}. - -@item overlays_before -@itemx overlays_after -These fields hold, respectively, a list of overlays that end at or -before the current overlay center, and a list of overlays that end -after the current overlay center. @xref{Managing Overlays}. -@code{overlays_before} is sorted in order of decreasing end position, -and @code{overlays_after} is sorted in order of increasing beginning -position. - -@c FIXME? the following are now all Lisp_Object BUFFER_INTERNAL_FIELD (foo). - -@item name -A Lisp string that names the buffer. It is guaranteed to be unique. -@xref{Buffer Names}. - -@item save_length -The length of the file this buffer is visiting, when last read or -saved. This and other fields concerned with saving are not kept in -the @code{buffer_text} structure because indirect buffers are never -saved. - -@item directory -The directory for expanding relative file names. This is the value of -the buffer-local variable @code{default-directory} (@pxref{File Name Expansion}). - -@item filename -The name of the file visited in this buffer, or @code{nil}. This is -the value of the buffer-local variable @code{buffer-file-name} -(@pxref{Buffer File Name}). - -@item undo_list -@itemx backed_up -@itemx auto_save_file_name -@itemx auto_save_file_format -@itemx read_only -@itemx file_format -@itemx file_truename -@itemx invisibility_spec -@itemx display_count -@itemx display_time -These fields store the values of Lisp variables that are automatically -buffer-local (@pxref{Buffer-Local Variables}), whose corresponding -variable names have the additional prefix @code{buffer-} and have -underscores replaced with dashes. For instance, @code{undo_list} -stores the value of @code{buffer-undo-list}. - -@item mark -The mark for the buffer. The mark is a marker, hence it is also -included on the list @code{markers}. @xref{The Mark}. - -@item local_var_alist -The association list describing the buffer-local variable bindings of -this buffer, not including the built-in buffer-local bindings that -have special slots in the buffer object. (Those slots are omitted -from this table.) @xref{Buffer-Local Variables}. - -@item major_mode -Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}. - -@item mode_name -Pretty name of the major mode, e.g., @code{"Lisp"}. - -@item keymap -@itemx abbrev_table -@itemx syntax_table -@itemx category_table -@itemx display_table -These fields store the buffer's local keymap (@pxref{Keymaps}), abbrev -table (@pxref{Abbrev Tables}), syntax table (@pxref{Syntax Tables}), -category table (@pxref{Categories}), and display table (@pxref{Display -Tables}). - -@item downcase_table -@itemx upcase_table -@itemx case_canon_table -These fields store the conversion tables for converting text to lower -case, upper case, and for canonicalizing text for case-fold search. -@xref{Case Tables}. - -@item minor_modes -An alist of the minor modes of this buffer. - -@item pt_marker -@itemx begv_marker -@itemx zv_marker -These fields are only used in an indirect buffer, or in a buffer that -is the base of an indirect buffer. Each holds a marker that records -@code{pt}, @code{begv}, and @code{zv} respectively, for this buffer -when the buffer is not current. - -@item mode_line_format -@itemx header_line_format -@itemx case_fold_search -@itemx tab_width -@itemx fill_column -@itemx left_margin -@itemx auto_fill_function -@itemx truncate_lines -@itemx word_wrap -@itemx ctl_arrow -@itemx bidi_display_reordering -@itemx bidi_paragraph_direction -@itemx selective_display -@itemx selective_display_ellipses -@itemx overwrite_mode -@itemx abbrev_mode -@itemx mark_active -@itemx enable_multibyte_characters -@itemx buffer_file_coding_system -@itemx cache_long_line_scans -@itemx point_before_scroll -@itemx left_fringe_width -@itemx right_fringe_width -@itemx fringes_outside_margins -@itemx scroll_bar_width -@itemx indicate_empty_lines -@itemx indicate_buffer_boundaries -@itemx fringe_indicator_alist -@itemx fringe_cursor_alist -@itemx scroll_up_aggressively -@itemx scroll_down_aggressively -@itemx cursor_type -@itemx cursor_in_non_selected_windows -These fields store the values of Lisp variables that are automatically -buffer-local (@pxref{Buffer-Local Variables}), whose corresponding -variable names have underscores replaced with dashes. For instance, -@code{mode_line_format} stores the value of @code{mode-line-format}. - -@item last_selected_window -This is the last window that was selected with this buffer in it, or @code{nil} -if that window no longer displays this buffer. -@end table - -@node Window Internals -@subsection Window Internals -@cindex internals, of window -@cindex window internals - - The fields of a window (for a complete list, see the definition of -@code{struct window} in @file{window.h}) include: - -@table @code -@item frame -The frame that this window is on. - -@item mini_p -Non-@code{nil} if this window is a minibuffer window. - -@item parent -Internally, Emacs arranges windows in a tree; each group of siblings has -a parent window whose area includes all the siblings. This field points -to a window's parent. - -Parent windows do not display buffers, and play little role in display -except to shape their child windows. Emacs Lisp programs usually have -no access to the parent windows; they operate on the windows at the -leaves of the tree, which actually display buffers. - -@c FIXME: These two slots and the `buffer' slot below were replaced -@c with a single slot `contents' on 2013-03-28. --xfq -@item hchild -@itemx vchild -These fields contain the window's leftmost child and its topmost child -respectively. @code{hchild} is used if the window is subdivided -horizontally by child windows, and @code{vchild} if it is subdivided -vertically. In a live window, only one of @code{hchild}, @code{vchild}, -and @code{buffer} (q.v.@:) is non-@code{nil}. - -@item next -@itemx prev -The next sibling and previous sibling of this window. @code{next} is -@code{nil} if the window is the right-most or bottom-most in its group; -@code{prev} is @code{nil} if it is the left-most or top-most in its -group. - -@item left_col -The left-hand edge of the window, measured in columns, relative to the -leftmost column in the frame (column 0). - -@item top_line -The top edge of the window, measured in lines, relative to the topmost -line in the frame (line 0). - -@item total_cols -@itemx total_lines -The width and height of the window, measured in columns and lines -respectively. The width includes the scroll bar and fringes, and/or -the separator line on the right of the window (if any). - -@item buffer -The buffer that the window is displaying. - -@item start -A marker pointing to the position in the buffer that is the first -character displayed in the window. - -@item pointm -@cindex window point internals -This is the value of point in the current buffer when this window is -selected; when it is not selected, it retains its previous value. - -@item force_start -If this flag is non-@code{nil}, it says that the window has been -scrolled explicitly by the Lisp program. This affects what the next -redisplay does if point is off the screen: instead of scrolling the -window to show the text around point, it moves point to a location that -is on the screen. - -@item frozen_window_start_p -This field is set temporarily to 1 to indicate to redisplay that -@code{start} of this window should not be changed, even if point -gets invisible. - -@item start_at_line_beg -Non-@code{nil} means current value of @code{start} was the beginning of a line -when it was chosen. - -@item use_time -This is the last time that the window was selected. The function -@code{get-lru-window} uses this field. - -@item sequence_number -A unique number assigned to this window when it was created. - -@item last_modified -The @code{modiff} field of the window's buffer, as of the last time -a redisplay completed in this window. - -@item last_overlay_modified -The @code{overlay_modiff} field of the window's buffer, as of the last -time a redisplay completed in this window. - -@item last_point -The buffer's value of point, as of the last time a redisplay completed -in this window. - -@item last_had_star -A non-@code{nil} value means the window's buffer was ``modified'' when the -window was last updated. - -@item vertical_scroll_bar -This window's vertical scroll bar. - -@item left_margin_cols -@itemx right_margin_cols -The widths of the left and right margins in this window. A value of -@code{nil} means no margin. - -@item left_fringe_width -@itemx right_fringe_width -The widths of the left and right fringes in this window. A value of -@code{nil} or @code{t} means use the values of the frame. - -@item fringes_outside_margins -A non-@code{nil} value means the fringes outside the display margins; -othersize they are between the margin and the text. - -@item window_end_pos -This is computed as @code{z} minus the buffer position of the last glyph -in the current matrix of the window. The value is only valid if -@code{window_end_valid} is not @code{nil}. - -@item window_end_bytepos -The byte position corresponding to @code{window_end_pos}. - -@item window_end_vpos -The window-relative vertical position of the line containing -@code{window_end_pos}. - -@item window_end_valid -This field is set to a non-@code{nil} value if @code{window_end_pos} is truly -valid. This is @code{nil} if nontrivial redisplay is pre-empted, since in that -case the display that @code{window_end_pos} was computed for did not get -onto the screen. - -@item cursor -A structure describing where the cursor is in this window. - -@item last_cursor -The value of @code{cursor} as of the last redisplay that finished. - -@item phys_cursor -A structure describing where the cursor of this window physically is. - -@item phys_cursor_type -@c FIXME What is this? -@c itemx phys_cursor_ascent -@itemx phys_cursor_height -@itemx phys_cursor_width -The type, height, and width of the cursor that was last displayed on -this window. - -@item phys_cursor_on_p -This field is non-zero if the cursor is physically on. - -@item cursor_off_p -Non-zero means the cursor in this window is logically off. This is -used for blinking the cursor. - -@item last_cursor_off_p -This field contains the value of @code{cursor_off_p} as of the time of -the last redisplay. - -@item must_be_updated_p -This is set to 1 during redisplay when this window must be updated. - -@item hscroll -This is the number of columns that the display in the window is scrolled -horizontally to the left. Normally, this is 0. - -@item vscroll -Vertical scroll amount, in pixels. Normally, this is 0. - -@item dedicated -Non-@code{nil} if this window is dedicated to its buffer. - -@item display_table -The window's display table, or @code{nil} if none is specified for it. - -@item update_mode_line -Non-@code{nil} means this window's mode line needs to be updated. - -@item base_line_number -The line number of a certain position in the buffer, or @code{nil}. -This is used for displaying the line number of point in the mode line. - -@item base_line_pos -The position in the buffer for which the line number is known, or -@code{nil} meaning none is known. If it is a buffer, don't display -the line number as long as the window shows that buffer. - -@item column_number_displayed -The column number currently displayed in this window's mode line, or @code{nil} -if column numbers are not being displayed. - -@item current_matrix -@itemx desired_matrix -Glyph matrices describing the current and desired display of this window. -@end table - -@node Process Internals -@subsection Process Internals -@cindex internals, of process -@cindex process internals - - The fields of a process (for a complete list, see the definition of -@code{struct Lisp_Process} in @file{process.h}) include: - -@table @code -@item name -A string, the name of the process. - -@item command -A list containing the command arguments that were used to start this -process. For a network or serial process, it is @code{nil} if the -process is running or @code{t} if the process is stopped. - -@item filter -A function used to accept output from the process. - -@item sentinel -A function called whenever the state of the process changes. - -@item buffer -The associated buffer of the process. - -@item pid -An integer, the operating system's process @acronym{ID}. -Pseudo-processes such as network or serial connections use a value of 0. - -@item childp -A flag, @code{t} if this is really a child process. For a network or -serial connection, it is a plist based on the arguments to -@code{make-network-process} or @code{make-serial-process}. - -@item mark -A marker indicating the position of the end of the last output from this -process inserted into the buffer. This is often but not always the end -of the buffer. - -@item kill_without_query -If this is non-zero, killing Emacs while this process is still running -does not ask for confirmation about killing the process. - -@item raw_status -The raw process status, as returned by the @code{wait} system call. - -@item status -The process status, as @code{process-status} should return it. - -@item tick -@itemx update_tick -If these two fields are not equal, a change in the status of the process -needs to be reported, either by running the sentinel or by inserting a -message in the process buffer. - -@item pty_flag -Non-@code{nil} if communication with the subprocess uses a pty; -@code{nil} if it uses a pipe. - -@item infd -The file descriptor for input from the process. - -@item outfd -The file descriptor for output to the process. - -@item tty_name -The name of the terminal that the subprocess is using, -or @code{nil} if it is using pipes. - -@item decode_coding_system -Coding-system for decoding the input from this process. - -@item decoding_buf -A working buffer for decoding. - -@item decoding_carryover -Size of carryover in decoding. - -@item encode_coding_system -Coding-system for encoding the output to this process. - -@item encoding_buf -A working buffer for encoding. - -@item inherit_coding_system_flag -Flag to set @code{coding-system} of the process buffer from the -coding system used to decode process output. - -@item type -Symbol indicating the type of process: @code{real}, @code{network}, -@code{serial}. - -@end table - -@node C Integer Types -@section C Integer Types -@cindex integer types (C programming language) - -Here are some guidelines for use of integer types in the Emacs C -source code. These guidelines sometimes give competing advice; common -sense is advised. - -@itemize @bullet -@item -Avoid arbitrary limits. For example, avoid @code{int len = strlen -(s);} unless the length of @code{s} is required for other reasons to -fit in @code{int} range. - -@item -Do not assume that signed integer arithmetic wraps around on overflow. -This is no longer true of Emacs porting targets: signed integer -overflow has undefined behavior in practice, and can dump core or -even cause earlier or later code to behave ``illogically''. Unsigned -overflow does wrap around reliably, modulo a power of two. - -@item -Prefer signed types to unsigned, as code gets confusing when signed -and unsigned types are combined. Many other guidelines assume that -types are signed; in the rarer cases where unsigned types are needed, -similar advice may apply to the unsigned counterparts (e.g., -@code{size_t} instead of @code{ptrdiff_t}, or @code{uintptr_t} instead -of @code{intptr_t}). - -@item -Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF. - -@item -Prefer @code{ptrdiff_t} for sizes, i.e., for integers bounded by the -maximum size of any individual C object or by the maximum number of -elements in any C array. This is part of Emacs's general preference -for signed types. Using @code{ptrdiff_t} limits objects to -@code{PTRDIFF_MAX} bytes, but larger objects would cause trouble -anyway since they would break pointer subtraction, so this does not -impose an arbitrary limit. - -@item -Prefer @code{intptr_t} for internal representations of pointers, or -for integers bounded only by the number of objects that can exist at -any given time or by the total number of bytes that can be allocated. -Currently Emacs sometimes uses other types when @code{intptr_t} would -be better; fixing this is lower priority, as the code works as-is on -Emacs's current porting targets. - -@item -Prefer the Emacs-defined type @code{EMACS_INT} for representing values -converted to or from Emacs Lisp fixnums, as fixnum arithmetic is based -on @code{EMACS_INT}. - -@item -When representing a system value (such as a file size or a count of -seconds since the Epoch), prefer the corresponding system type (e.g., -@code{off_t}, @code{time_t}). Do not assume that a system type is -signed, unless this assumption is known to be safe. For example, -although @code{off_t} is always signed, @code{time_t} need not be. - -@item -Prefer the Emacs-defined type @code{printmax_t} for representing -values that might be any signed integer that can be printed, -using a @code{printf}-family function. - -@item -Prefer @code{intmax_t} for representing values that might be any -signed integer value. - -@item -Prefer @code{bool}, @code{false} and @code{true} for booleans. -Using @code{bool} can make programs easier to read and a bit faster than -using @code{int}. Although it is also OK to use @code{int}, @code{0} -and @code{1}, this older style is gradually being phased out. When -using @code{bool}, respect the limitations of the replacement -implementation of @code{bool}, as documented in the source file -@file{lib/stdbool.in.h}, so that Emacs remains portable to pre-C99 -platforms. In particular, boolean bitfields should be of type -@code{bool_bf}, not @code{bool}, so that they work correctly even when -compiling Objective C with standard GCC. - -@item -In bitfields, prefer @code{unsigned int} or @code{signed int} to -@code{int}, as @code{int} is less portable: it might be signed, and -might not be. Single-bit bit fields should be @code{unsigned int} or -@code{bool_bf} so that their values are 0 or 1. -@end itemize - -@c FIXME Mention src/globals.h somewhere in this file? diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi deleted file mode 100644 index 0c5346fbb63..00000000000 --- a/doc/lispref/intro.texi +++ /dev/null @@ -1,555 +0,0 @@ -@c -*-coding: utf-8-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. - -@node Introduction -@chapter Introduction - - Most of the GNU Emacs text editor is written in the programming -language called Emacs Lisp. You can write new code in Emacs Lisp and -install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming -language in its own right. You can use it as you would any other -programming language. - - Because Emacs Lisp is designed for use in an editor, it has special -features for scanning and parsing text as well as features for handling -files, buffers, displays, subprocesses, and so on. Emacs Lisp is -closely integrated with the editing facilities; thus, editing commands -are functions that can also conveniently be called from Lisp programs, -and parameters for customization are ordinary Lisp variables. - - This manual attempts to be a full description of Emacs Lisp. For a -beginner's introduction to Emacs Lisp, see @cite{An Introduction to -Emacs Lisp Programming}, by Bob Chassell, also published by the Free -Software Foundation. This manual presumes considerable familiarity with -the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this -basic information. - - Generally speaking, the earlier chapters describe features of Emacs -Lisp that have counterparts in many programming languages, and later -chapters describe features that are peculiar to Emacs Lisp or relate -specifically to editing. - - This is -@iftex -edition @value{VERSION} of -@end iftex -the @cite{GNU Emacs Lisp Reference Manual}, -corresponding to Emacs version @value{EMACSVER}. - -@menu -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgments:: The authors, editors, and sponsors of this manual. -@end menu - -@node Caveats -@section Caveats -@cindex bugs in this manual - - This manual has gone through numerous drafts. It is nearly complete -but not flawless. There are a few topics that are not covered, either -because we consider them secondary (such as most of the individual -modes) or because they are yet to be written. Because we are not able -to deal with them completely, we have left out several parts -intentionally. - - The manual should be fully correct in what it does cover, and it is -therefore open to criticism on anything it says---from specific examples -and descriptive text, to the ordering of chapters and sections. If -something is confusing, or you find that you have to look at the sources -or experiment to learn something not covered in the manual, then perhaps -the manual should be fixed. Please let us know. - -@iftex - As you use this manual, we ask that you mark pages with corrections so -you can later look them up and send them to us. If you think of a simple, -real-life example for a function or group of functions, please make an -effort to write it up and send it in. Please reference any comments to -the chapter name, section name, and function name, as appropriate, since -page numbers and chapter and section numbers will change and we may have -trouble finding the text you are talking about. Also state the version -of the edition you are criticizing. -@end iftex -@ifnottex - -As you use this manual, we ask that you send corrections as soon as you -find them. If you think of a simple, real life example for a function -or group of functions, please make an effort to write it up and send it -in. Please reference any comments to the node name and function or -variable name, as appropriate. Also state the number of the edition -you are criticizing. -@end ifnottex - -@cindex bugs -@cindex suggestions -Please send comments and corrections using @kbd{M-x report-emacs-bug}. - -@node Lisp History -@section Lisp History -@cindex Lisp history - - Lisp (LISt Processing language) was first developed in the late 1950s -at the Massachusetts Institute of Technology for research in artificial -intelligence. The great power of the Lisp language makes it ideal -for other purposes as well, such as writing editing commands. - -@cindex Maclisp -@cindex Common Lisp - Dozens of Lisp implementations have been built over the years, each -with its own idiosyncrasies. Many of them were inspired by Maclisp, -which was written in the 1960s at MIT's Project MAC@. Eventually the -implementers of the descendants of Maclisp came together and developed a -standard for Lisp systems, called Common Lisp. In the meantime, Gerry -Sussman and Guy Steele at MIT developed a simplified but very powerful -dialect of Lisp, called Scheme. - - GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common -Lisp. If you know Common Lisp, you will notice many similarities. -However, many features of Common Lisp have been omitted or -simplified in order to reduce the memory requirements of GNU Emacs. -Sometimes the simplifications are so drastic that a Common Lisp user -might be very confused. We will occasionally point out how GNU Emacs -Lisp differs from Common Lisp. If you don't know Common Lisp, don't -worry about it; this manual is self-contained. - -@pindex cl - A certain amount of Common Lisp emulation is available via the -@file{cl-lib} library. @xref{Top,, Overview, cl, Common Lisp Extensions}. - - Emacs Lisp is not at all influenced by Scheme; but the GNU project has -an implementation of Scheme, called Guile. We use it in all new GNU -software that calls for extensibility. - -@node Conventions -@section Conventions - -This section explains the notational conventions that are used in this -manual. You may want to skip this section and refer back to it later. - -@menu -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. -@end menu - -@node Some Terms -@subsection Some Terms - - Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp -printer'' refer to those routines in Lisp that convert textual -representations of Lisp objects into actual Lisp objects, and vice -versa. @xref{Printed Representation}, for more details. You, the -person reading this manual, are thought of as ``the programmer'' and are -addressed as ``you''. ``The user'' is the person who uses Lisp -programs, including those you write. - -@cindex typographic conventions - Examples of Lisp code are formatted like this: @code{(list 1 2 3)}. -Names that represent metasyntactic variables, or arguments to a function -being described, are formatted like this: @var{first-number}. - -@node nil and t -@subsection @code{nil} and @code{t} -@cindex truth value -@cindex boolean - -@cindex @code{nil} -@cindex false - In Emacs Lisp, the symbol @code{nil} has three separate meanings: it -is a symbol with the name @samp{nil}; it is the logical truth value -@var{false}; and it is the empty list---the list of zero elements. -When used as a variable, @code{nil} always has the value @code{nil}. - - As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are -identical: they stand for the same object, the symbol @code{nil}. The -different ways of writing the symbol are intended entirely for human -readers. After the Lisp reader has read either @samp{()} or @samp{nil}, -there is no way to determine which representation was actually written -by the programmer. - - In this manual, we write @code{()} when we wish to emphasize that it -means the empty list, and we write @code{nil} when we wish to emphasize -that it means the truth value @var{false}. That is a good convention to use -in Lisp programs also. - -@example -(cons 'foo ()) ; @r{Emphasize the empty list} -(setq foo-flag nil) ; @r{Emphasize the truth value @var{false}} -@end example - -@cindex @code{t} -@cindex true - In contexts where a truth value is expected, any non-@code{nil} value -is considered to be @var{true}. However, @code{t} is the preferred way -to represent the truth value @var{true}. When you need to choose a -value which represents @var{true}, and there is no other basis for -choosing, use @code{t}. The symbol @code{t} always has the value -@code{t}. - - In Emacs Lisp, @code{nil} and @code{t} are special symbols that always -evaluate to themselves. This is so that you do not need to quote them -to use them as constants in a program. An attempt to change their -values results in a @code{setting-constant} error. @xref{Constant -Variables}. - -@defun booleanp object -Return non-@code{nil} if @var{object} is one of the two canonical -boolean values: @code{t} or @code{nil}. -@end defun - -@node Evaluation Notation -@subsection Evaluation Notation -@cindex evaluation notation -@cindex documentation notation -@cindex notation - - A Lisp expression that you can evaluate is called a @dfn{form}. -Evaluating a form always produces a result, which is a Lisp object. In -the examples in this manual, this is indicated with @samp{@result{}}: - -@example -(car '(1 2)) - @result{} 1 -@end example - -@noindent -You can read this as ``@code{(car '(1 2))} evaluates to 1''. - - When a form is a macro call, it expands into a new form for Lisp to -evaluate. We show the result of the expansion with -@samp{@expansion{}}. We may or may not show the result of the -evaluation of the expanded form. - -@example -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end example - - To help describe one form, we sometimes show another form that -produces identical results. The exact equivalence of two forms is -indicated with @samp{@equiv{}}. - -@example -(make-sparse-keymap) @equiv{} (list 'keymap) -@end example - -@node Printing Notation -@subsection Printing Notation -@cindex printing notation - - Many of the examples in this manual print text when they are -evaluated. If you execute example code in a Lisp Interaction buffer -(such as the buffer @file{*scratch*}), the printed text is inserted into -the buffer. If you execute the example by other means (such as by -evaluating the function @code{eval-region}), the printed text is -displayed in the echo area. - - Examples in this manual indicate printed text with @samp{@print{}}, -irrespective of where that text goes. The value returned by -evaluating the form follows on a separate line with -@samp{@result{}}. - -@example -@group -(progn (prin1 'foo) (princ "\n") (prin1 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end example - -@node Error Messages -@subsection Error Messages -@cindex error message notation - - Some examples signal errors. This normally displays an error message -in the echo area. We show the error message on a line starting with -@samp{@error{}}. Note that @samp{@error{}} itself does not appear in -the echo area. - -@example -(+ 23 'x) -@error{} Wrong type argument: number-or-marker-p, x -@end example - -@node Buffer Text Notation -@subsection Buffer Text Notation -@cindex buffer text notation - - Some examples describe modifications to the contents of a buffer, by -showing the ``before'' and ``after'' versions of the text. These -examples show the contents of the buffer in question between two lines -of dashes containing the buffer name. In addition, @samp{@point{}} -indicates the location of point. (The symbol for point, of course, is -not part of the text in the buffer; it indicates the place -@emph{between} two characters where point is currently located.) - -@example ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- -@end example - -@node Format of Descriptions -@subsection Format of Descriptions -@cindex description format - - Functions, variables, macros, commands, user options, and special -forms are described in this manual in a uniform format. The first -line of a description contains the name of the item followed by its -arguments, if any. -@ifnottex -The category---function, variable, or whatever---appears at the -beginning of the line. -@end ifnottex -@iftex -The category---function, variable, or whatever---is printed next to the -right margin. -@end iftex -The description follows on succeeding lines, sometimes with examples. - -@menu -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, - @code{electric-future-map}. -@end menu - -@node A Sample Function Description -@subsubsection A Sample Function Description -@cindex function descriptions -@cindex command descriptions -@cindex macro descriptions -@cindex special form descriptions - - In a function description, the name of the function being described -appears first. It is followed on the same line by a list of argument -names. These names are also used in the body of the description, to -stand for the values of the arguments. - - The appearance of the keyword @code{&optional} in the argument list -indicates that the subsequent arguments may be omitted (omitted -arguments default to @code{nil}). Do not write @code{&optional} when -you call the function. - - The keyword @code{&rest} (which must be followed by a single -argument name) indicates that any number of arguments can follow. The -single argument name following @code{&rest} receives, as its -value, a list of all the remaining arguments passed to the function. -Do not write @code{&rest} when you call the function. - - Here is a description of an imaginary function @code{foo}: - -@defun foo integer1 &optional integer2 &rest integers -The function @code{foo} subtracts @var{integer1} from @var{integer2}, -then adds all the rest of the arguments to the result. If @var{integer2} -is not supplied, then the number 19 is used by default. - -@example -(foo 1 5 3 9) - @result{} 16 -(foo 5) - @result{} 14 -@end example - -@need 1500 -More generally, - -@example -(foo @var{w} @var{x} @var{y}@dots{}) -@equiv{} -(+ (- @var{x} @var{w}) @var{y}@dots{}) -@end example -@end defun - - By convention, any argument whose name contains the name of a type -(e.g., @var{integer}, @var{integer1} or @var{buffer}) is expected to -be of that type. A plural of a type (such as @var{buffers}) often -means a list of objects of that type. An argument named @var{object} -may be of any type. (For a list of Emacs object types, @pxref{Lisp -Data Types}.) An argument with any other sort of name -(e.g., @var{new-file}) is specific to the function; if the function -has a documentation string, the type of the argument should be -described there (@pxref{Documentation}). - - @xref{Lambda Expressions}, for a more complete description of -arguments modified by @code{&optional} and @code{&rest}. - - Command, macro, and special form descriptions have the same format, -but the word @samp{Function} is replaced by @samp{Command}, -@samp{Macro}, or @samp{Special Form}, respectively. Commands are -simply functions that may be called interactively; macros process -their arguments differently from functions (the arguments are not -evaluated), but are presented the same way. - - The descriptions of macros and special forms use a more complex -notation to specify optional and repeated arguments, because they can -break the argument list down into separate arguments in more -complicated ways. @samp{@r{[}@var{optional-arg}@r{]}} means that -@var{optional-arg} is optional and @samp{@var{repeated-args}@dots{}} -stands for zero or more arguments. Parentheses are used when several -arguments are grouped into additional levels of list structure. Here -is an example: - -@defspec count-loop (var [from to [inc]]) body@dots{} -This imaginary special form implements a loop that executes the -@var{body} forms and then increments the variable @var{var} on each -iteration. On the first iteration, the variable has the value -@var{from}; on subsequent iterations, it is incremented by one (or by -@var{inc} if that is given). The loop exits before executing @var{body} -if @var{var} equals @var{to}. Here is an example: - -@example -(count-loop (i 0 10) - (prin1 i) (princ " ") - (prin1 (aref vector i)) - (terpri)) -@end example - -If @var{from} and @var{to} are omitted, @var{var} is bound to -@code{nil} before the loop begins, and the loop exits if @var{var} is -non-@code{nil} at the beginning of an iteration. Here is an example: - -@example -(count-loop (done) - (if (pending) - (fixit) - (setq done t))) -@end example - -In this special form, the arguments @var{from} and @var{to} are -optional, but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the form. -@end defspec - -@node A Sample Variable Description -@subsubsection A Sample Variable Description -@cindex variable descriptions -@cindex option descriptions - - A @dfn{variable} is a name that can be @dfn{bound} (or @dfn{set}) to -an object. The object to which a variable is bound is called a -@dfn{value}; we say also that variable holds that value. -Although nearly all variables can be set by the user, certain -variables exist specifically so that users can change them; these are -called @dfn{user options}. Ordinary variables and user options are -described using a format like that for functions, except that there -are no arguments. - - Here is a description of the imaginary @code{electric-future-map} -variable. - -@defvar electric-future-map -The value of this variable is a full keymap used by Electric Command -Future mode. The functions in this map allow you to edit commands you -have not yet thought about executing. -@end defvar - - User option descriptions have the same format, but @samp{Variable} -is replaced by @samp{User Option}. - -@node Version Info -@section Version Information - - These facilities provide information about which version of Emacs is -in use. - -@deffn Command emacs-version &optional here -This function returns a string describing the version of Emacs that is -running. It is useful to include this string in bug reports. - -@smallexample -@group -(emacs-version) - @result{} "GNU Emacs 23.1 (i686-pc-linux-gnu, GTK+ Version 2.14.4) - of 2009-06-01 on cyd.mit.edu" -@end group -@end smallexample - -If @var{here} is non-@code{nil}, it inserts the text in the buffer -before point, and returns @code{nil}. When this function is called -interactively, it prints the same information in the echo area, but -giving a prefix argument makes @var{here} non-@code{nil}. -@end deffn - -@defvar emacs-build-time -The value of this variable indicates the time at which Emacs was -built. It is a list of four integers, like the value of -@code{current-time} (@pxref{Time of Day}). - -@example -@group -emacs-build-time - @result{} (20614 63694 515336 438000) -@end group -@end example -@end defvar - -@defvar emacs-version -The value of this variable is the version of Emacs being run. It is a -string such as @code{"23.1.1"}. The last number in this string is not -really part of the Emacs release version number; it is incremented -each time Emacs is built in any given directory. A value with four -numeric components, such as @code{"22.0.91.1"}, indicates an -unreleased test version. -@end defvar - -@defvar emacs-major-version -The major version number of Emacs, as an integer. For Emacs version -23.1, the value is 23. -@end defvar - -@defvar emacs-minor-version -The minor version number of Emacs, as an integer. For Emacs version -23.1, the value is 1. -@end defvar - -@node Acknowledgments -@section Acknowledgments - - This manual was originally written by Robert Krawitz, Bil Lewis, Dan -LaLiberte, Richard@tie{}M. Stallman and Chris Welty, the volunteers of -the GNU manual group, in an effort extending over several years. -Robert@tie{}J. Chassell helped to review and edit the manual, with the -support of the Defense Advanced Research Projects Agency, ARPA Order -6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic, -Inc. Additional sections have since been written by Miles Bader, Lars -Brinkhoff, Chong Yidong, Kenichi Handa, Lute Kamstra, Juri Linkov, -Glenn Morris, Thien-Thi Nguyen, Dan Nicolaescu, Martin Rudalics, Kim -F. Storm, Luc Teirlinck, and Eli Zaretskii, and others. - - Corrections were supplied by Drew Adams, Juanma Barranquero, Karl -Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David Boyes, Alan -Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch, David -A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf Fassel, -Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, Jesper -Harder, George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak -Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, -K. Richard Magill, Brian Marick, Roland McGrath, Stefan Monnier, Skip -Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potortì, -Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Jason Rumney, -Per Starbäck, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill -Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding, -Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn. - - For a more complete list of contributors, please see the relevant -ChangeLog file in the Emacs sources. diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi deleted file mode 100644 index 7cc2b393456..00000000000 --- a/doc/lispref/keymaps.texi +++ /dev/null @@ -1,2955 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Keymaps -@chapter Keymaps -@cindex keymap - - The command bindings of input events are recorded in data structures -called @dfn{keymaps}. Each entry in a keymap associates (or -@dfn{binds}) an individual event type, either to another keymap or to -a command. When an event type is bound to a keymap, that keymap is -used to look up the next input event; this continues until a command -is found. The whole process is called @dfn{key lookup}. - -@menu -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. -@end menu - -@node Key Sequences -@section Key Sequences -@cindex key -@cindex keystroke -@cindex key sequence - - A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one -or more input events that form a unit. Input events include -characters, function keys, mouse actions, or system events external to -Emacs, such as @code{iconify-frame} (@pxref{Input Events}). -The Emacs Lisp representation for a key sequence is a string or -vector. Unless otherwise stated, any Emacs Lisp function that accepts -a key sequence as an argument can handle both representations. - - In the string representation, alphanumeric characters ordinarily -stand for themselves; for example, @code{"a"} represents @kbd{a} -and @code{"2"} represents @kbd{2}. Control character events are -prefixed by the substring @code{"\C-"}, and meta characters by -@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}. -In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events -are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and -@code{"\d"} respectively. The string representation of a complete key -sequence is the concatenation of the string representations of the -constituent events; thus, @code{"\C-xl"} represents the key sequence -@kbd{C-x l}. - - Key sequences containing function keys, mouse button events, system -events, or non-@acronym{ASCII} characters such as @kbd{C-=} or -@kbd{H-a} cannot be represented as strings; they have to be -represented as vectors. - - In the vector representation, each element of the vector represents -an input event, in its Lisp form. @xref{Input Events}. For example, -the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}. - - For examples of key sequences written in string and vector -representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}. - -@defun kbd keyseq-text -This function converts the text @var{keyseq-text} (a string constant) -into a key sequence (a string or vector constant). The contents of -@var{keyseq-text} should use the same syntax as in the buffer invoked -by the @kbd{C-x C-k @key{RET}} (@code{kmacro-edit-macro}) command; in -particular, you must surround function key names with -@samp{<@dots{}>}. @xref{Edit Keyboard Macro,,, emacs, The GNU Emacs -Manual}. - -@example -(kbd "C-x") @result{} "\C-x" -(kbd "C-x C-f") @result{} "\C-x\C-f" -(kbd "C-x 4 C-f") @result{} "\C-x4\C-f" -(kbd "X") @result{} "X" -(kbd "RET") @result{} "\^M" -(kbd "C-c SPC") @result{} "\C-c@ " -(kbd " SPC") @result{} [f1 32] -(kbd "C-M-") @result{} [C-M-down] -@end example -@end defun - -@node Keymap Basics -@section Keymap Basics -@cindex key binding -@cindex binding of a key -@cindex complete key -@cindex undefined key - - A keymap is a Lisp data structure that specifies @dfn{key bindings} -for various key sequences. - - A single keymap directly specifies definitions for individual -events. When a key sequence consists of a single event, its binding -in a keymap is the keymap's definition for that event. The binding of -a longer key sequence is found by an iterative process: first find the -definition of the first event (which must itself be a keymap); then -find the second event's definition in that keymap, and so on until all -the events in the key sequence have been processed. - - If the binding of a key sequence is a keymap, we call the key sequence -a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because -no more events can be added to it). If the binding is @code{nil}, -we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c}, -@kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are -@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete -keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more -details. - - The rule for finding the binding of a key sequence assumes that the -intermediate bindings (found for the events before the last) are all -keymaps; if this is not so, the sequence of events does not form a -unit---it is not really one key sequence. In other words, removing one -or more events from the end of any valid key sequence must always yield -a prefix key. For example, @kbd{C-f C-n} is not a key sequence; -@kbd{C-f} is not a prefix key, so a longer sequence starting with -@kbd{C-f} cannot be a key sequence. - - The set of possible multi-event key sequences depends on the bindings -for prefix keys; therefore, it can be different for different keymaps, -and can change when bindings are changed. However, a one-event sequence -is always a key sequence, because it does not depend on any prefix keys -for its well-formedness. - - At any time, several primary keymaps are @dfn{active}---that is, in -use for finding key bindings. These are the @dfn{global map}, which is -shared by all buffers; the @dfn{local keymap}, which is usually -associated with a specific major mode; and zero or more @dfn{minor mode -keymaps}, which belong to currently enabled minor modes. (Not all minor -modes have keymaps.) The local keymap bindings shadow (i.e., take -precedence over) the corresponding global bindings. The minor mode -keymaps shadow both local and global keymaps. @xref{Active Keymaps}, -for details. - -@node Format of Keymaps -@section Format of Keymaps -@cindex format of keymaps -@cindex keymap format -@cindex full keymap -@cindex sparse keymap - - Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The -remaining elements of the list define the key bindings of the keymap. -A symbol whose function definition is a keymap is also a keymap. Use -the function @code{keymapp} (see below) to test whether an object is a -keymap. - - Several kinds of elements may appear in a keymap, after the symbol -@code{keymap} that begins it: - -@table @code -@item (@var{type} .@: @var{binding}) -This specifies one binding, for events of type @var{type}. Each -ordinary binding applies to events of a particular @dfn{event type}, -which is always a character or a symbol. @xref{Classifying Events}. -In this kind of binding, @var{binding} is a command. - -@item (@var{type} @var{item-name} .@: @var{binding}) -This specifies a binding which is also a simple menu item that -displays as @var{item-name} in the menu. @xref{Simple Menu Items}. - -@item (@var{type} @var{item-name} @var{help-string} .@: @var{binding}) -This is a simple menu item with help string @var{help-string}. - -@item (@var{type} menu-item .@: @var{details}) -This specifies a binding which is also an extended menu item. This -allows use of other features. @xref{Extended Menu Items}. - -@item (t .@: @var{binding}) -@cindex default key binding -This specifies a @dfn{default key binding}; any event not bound by other -elements of the keymap is given @var{binding} as its binding. Default -bindings allow a keymap to bind all possible event types without having -to enumerate all of them. A keymap that has a default binding -completely masks any lower-precedence keymap, except for events -explicitly bound to @code{nil} (see below). - -@item @var{char-table} -If an element of a keymap is a char-table, it counts as holding -bindings for all character events with no modifier bits -(@pxref{modifier bits}): element @var{n} is the binding for the -character with code @var{n}. This is a compact way to record lots of -bindings. A keymap with such a char-table is called a @dfn{full -keymap}. Other keymaps are called @dfn{sparse keymaps}. - -@item @var{string} -@cindex keymap prompt string -@cindex overall prompt string -@cindex prompt string of keymap -Aside from elements that specify bindings for keys, a keymap can also -have a string as an element. This is called the @dfn{overall prompt -string} and makes it possible to use the keymap as a menu. -@xref{Defining Menus}. - -@item (keymap @dots{}) -If an element of a keymap is itself a keymap, it counts as if this inner keymap -were inlined in the outer keymap. This is used for multiple-inheritance, such -as in @code{make-composed-keymap}. -@end table - -When the binding is @code{nil}, it doesn't constitute a definition -but it does take precedence over a default binding or a binding in the -parent keymap. On the other hand, a binding of @code{nil} does -@emph{not} override lower-precedence keymaps; thus, if the local map -gives a binding of @code{nil}, Emacs uses the binding from the -global map. - -@cindex meta characters lookup - Keymaps do not directly record bindings for the meta characters. -Instead, meta characters are regarded for purposes of key lookup as -sequences of two characters, the first of which is @key{ESC} (or -whatever is currently the value of @code{meta-prefix-char}). Thus, the -key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its -global binding is found at the slot for @kbd{a} in @code{esc-map} -(@pxref{Prefix Keys}). - - This conversion applies only to characters, not to function keys or -other input events; thus, @kbd{M-@key{end}} has nothing to do with -@kbd{@key{ESC} @key{end}}. - - Here as an example is the local keymap for Lisp mode, a sparse -keymap. It defines bindings for @key{DEL}, @kbd{C-c C-z}, -@kbd{C-M-q}, and @kbd{C-M-x} (the actual value also contains a menu -binding, which is omitted here for the sake of brevity). - -@example -@group -lisp-mode-map -@result{} -@end group -@group -(keymap - (3 keymap - ;; @kbd{C-c C-z} - (26 . run-lisp)) -@end group -@group - (27 keymap - ;; @r{@kbd{C-M-x}, treated as @kbd{@key{ESC} C-x}} - (24 . lisp-send-defun)) -@end group -@group - ;; @r{This part is inherited from @code{lisp-mode-shared-map}.} - keymap - ;; @key{DEL} - (127 . backward-delete-char-untabify) -@end group -@group - (27 keymap - ;; @r{@kbd{C-M-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp))) -@end group -@end example - -@defun keymapp object -This function returns @code{t} if @var{object} is a keymap, @code{nil} -otherwise. More precisely, this function tests for a list whose -@sc{car} is @code{keymap}, or for a symbol whose function definition -satisfies @code{keymapp}. - -@example -@group -(keymapp '(keymap)) - @result{} t -@end group -@group -(fset 'foo '(keymap)) -(keymapp 'foo) - @result{} t -@end group -@group -(keymapp (current-global-map)) - @result{} t -@end group -@end example -@end defun - -@node Creating Keymaps -@section Creating Keymaps -@cindex creating keymaps - - Here we describe the functions for creating keymaps. - -@defun make-sparse-keymap &optional prompt -This function creates and returns a new sparse keymap with no entries. -(A sparse keymap is the kind of keymap you usually want.) The new -keymap does not contain a char-table, unlike @code{make-keymap}, and -does not bind any events. - -@example -@group -(make-sparse-keymap) - @result{} (keymap) -@end group -@end example - -If you specify @var{prompt}, that becomes the overall prompt string -for the keymap. You should specify this only for menu keymaps -(@pxref{Defining Menus}). A keymap with an overall prompt string will -always present a mouse menu or a keyboard menu if it is active for -looking up the next input event. Don't specify an overall prompt string -for the main map of a major or minor mode, because that would cause -the command loop to present a keyboard menu every time. -@end defun - -@defun make-keymap &optional prompt -This function creates and returns a new full keymap. That keymap -contains a char-table (@pxref{Char-Tables}) with slots for all -characters without modifiers. The new keymap initially binds all -these characters to @code{nil}, and does not bind any other kind of -event. The argument @var{prompt} specifies a -prompt string, as in @code{make-sparse-keymap}. - -@c This example seems kind of pointless, but I guess it serves -@c to contrast the result with make-sparse-keymap above. -@example -@group -(make-keymap) - @result{} (keymap #^[nil nil keymap nil nil nil @dots{}]) -@end group -@end example - -A full keymap is more efficient than a sparse keymap when it holds -lots of bindings; for just a few, the sparse keymap is better. -@end defun - -@defun copy-keymap keymap -This function returns a copy of @var{keymap}. Any keymaps that -appear directly as bindings in @var{keymap} are also copied recursively, -and so on to any number of levels. However, recursive copying does not -take place when the definition of a character is a symbol whose function -definition is a keymap; the same symbol appears in the new copy. -@c Emacs 19 feature - -@example -@group -(setq map (copy-keymap (current-local-map))) -@result{} (keymap -@end group -@group - ;; @r{(This implements meta characters.)} - (27 keymap - (83 . center-paragraph) - (115 . center-line)) - (9 . tab-to-tab-stop)) -@end group - -@group -(eq map (current-local-map)) - @result{} nil -@end group -@group -(equal map (current-local-map)) - @result{} t -@end group -@end example -@end defun - -@node Inheritance and Keymaps -@section Inheritance and Keymaps -@cindex keymap inheritance -@cindex inheritance, keymap - - A keymap can inherit the bindings of another keymap, which we call the -@dfn{parent keymap}. Such a keymap looks like this: - -@example -(keymap @var{elements}@dots{} . @var{parent-keymap}) -@end example - -@noindent -The effect is that this keymap inherits all the bindings of -@var{parent-keymap}, whatever they may be at the time a key is looked up, -but can add to them or override them with @var{elements}. - -If you change the bindings in @var{parent-keymap} using -@code{define-key} or other key-binding functions, these changed -bindings are visible in the inheriting keymap, unless shadowed by the -bindings made by @var{elements}. The converse is not true: if you use -@code{define-key} to change bindings in the inheriting keymap, these -changes are recorded in @var{elements}, but have no effect on -@var{parent-keymap}. - -The proper way to construct a keymap with a parent is to use -@code{set-keymap-parent}; if you have code that directly constructs a -keymap with a parent, please convert the program to use -@code{set-keymap-parent} instead. - -@defun keymap-parent keymap -This returns the parent keymap of @var{keymap}. If @var{keymap} -has no parent, @code{keymap-parent} returns @code{nil}. -@end defun - -@defun set-keymap-parent keymap parent -This sets the parent keymap of @var{keymap} to @var{parent}, and returns -@var{parent}. If @var{parent} is @code{nil}, this function gives -@var{keymap} no parent at all. - -If @var{keymap} has submaps (bindings for prefix keys), they too receive -new parent keymaps that reflect what @var{parent} specifies for those -prefix keys. -@end defun - - Here is an example showing how to make a keymap that inherits -from @code{text-mode-map}: - -@example -(let ((map (make-sparse-keymap))) - (set-keymap-parent map text-mode-map) - map) -@end example - - A non-sparse keymap can have a parent too, but this is not very -useful. A non-sparse keymap always specifies something as the binding -for every numeric character code without modifier bits, even if it is -@code{nil}, so these character's bindings are never inherited from -the parent keymap. - -@cindex keymap inheritance from multiple maps - Sometimes you want to make a keymap that inherits from more than one -map. You can use the function @code{make-composed-keymap} for this. - -@defun make-composed-keymap maps &optional parent -This function returns a new keymap composed of the existing keymap(s) -@var{maps}, and optionally inheriting from a parent keymap -@var{parent}. @var{maps} can be a single keymap or a list of more -than one. When looking up a key in the resulting new map, Emacs -searches in each of the @var{maps} in turn, and then in @var{parent}, -stopping at the first match. A @code{nil} binding in any one of -@var{maps} overrides any binding in @var{parent}, but it does not -override any non-@code{nil} binding in any other of the @var{maps}. -@end defun - -@noindent For example, here is how Emacs sets the parent of -@code{help-mode-map}, such that it inherits from both -@code{button-buffer-map} and @code{special-mode-map}: - -@example -(defvar help-mode-map - (let ((map (make-sparse-keymap))) - (set-keymap-parent map - (make-composed-keymap button-buffer-map special-mode-map)) - ... map) ... ) -@end example - - -@node Prefix Keys -@section Prefix Keys -@cindex prefix key - - A @dfn{prefix key} is a key sequence whose binding is a keymap. The -keymap defines what to do with key sequences that extend the prefix key. -For example, @kbd{C-x} is a prefix key, and it uses a keymap that is -also stored in the variable @code{ctl-x-map}. This keymap defines -bindings for key sequences starting with @kbd{C-x}. - - Some of the standard Emacs prefix keys use keymaps that are -also found in Lisp variables: - -@itemize @bullet -@item -@vindex esc-map -@findex ESC-prefix -@code{esc-map} is the global keymap for the @key{ESC} prefix key. Thus, -the global definitions of all meta characters are actually found here. -This map is also the function definition of @code{ESC-prefix}. - -@item -@cindex @kbd{C-h} -@code{help-map} is the global keymap for the @kbd{C-h} prefix key. - -@item -@cindex @kbd{C-c} -@vindex mode-specific-map -@code{mode-specific-map} is the global keymap for the prefix key -@kbd{C-c}. This map is actually global, not mode-specific, but its name -provides useful information about @kbd{C-c} in the output of @kbd{C-h b} -(@code{display-bindings}), since the main use of this prefix key is for -mode-specific bindings. - -@item -@cindex @kbd{C-x} -@vindex ctl-x-map -@findex Control-X-prefix -@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key. -This map is found via the function cell of the symbol -@code{Control-X-prefix}. - -@item -@cindex @kbd{C-x @key{RET}} -@vindex mule-keymap -@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}} -prefix key. - -@item -@cindex @kbd{C-x 4} -@vindex ctl-x-4-map -@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix -key. - -@item -@cindex @kbd{C-x 5} -@vindex ctl-x-5-map -@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix -key. - -@item -@cindex @kbd{C-x 6} -@vindex 2C-mode-map -@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix -key. - -@item -@cindex @kbd{C-x v} -@vindex vc-prefix-map -@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix -key. - -@item -@cindex @kbd{M-g} -@vindex goto-map -@code{goto-map} is the global keymap used for the @kbd{M-g} prefix -key. - -@item -@cindex @kbd{M-s} -@vindex search-map -@code{search-map} is the global keymap used for the @kbd{M-s} prefix -key. - -@item -@cindex @kbd{M-o} -@vindex facemenu-keymap -@code{facemenu-keymap} is the global keymap used for the @kbd{M-o} -prefix key. - -@item -The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x -@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have -no special names. -@end itemize - - The keymap binding of a prefix key is used for looking up the event -that follows the prefix key. (It may instead be a symbol whose function -definition is a keymap. The effect is the same, but the symbol serves -as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the -symbol @code{Control-X-prefix}, whose function cell holds the keymap -for @kbd{C-x} commands. (The same keymap is also the value of -@code{ctl-x-map}.) - - Prefix key definitions can appear in any active keymap. The -definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix -keys appear in the global map, so these prefix keys are always -available. Major and minor modes can redefine a key as a prefix by -putting a prefix key definition for it in the local map or the minor -mode's map. @xref{Active Keymaps}. - - If a key is defined as a prefix in more than one active map, then its -various definitions are in effect merged: the commands defined in the -minor mode keymaps come first, followed by those in the local map's -prefix definition, and then by those from the global map. - - In the following example, we make @kbd{C-p} a prefix key in the local -keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then -the binding for @kbd{C-p C-f} is the function @code{find-file}, just -like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any -active keymap. - -@example -@group -(use-local-map (make-sparse-keymap)) - @result{} nil -@end group -@group -(local-set-key "\C-p" ctl-x-map) - @result{} nil -@end group -@group -(key-binding "\C-p\C-f") - @result{} find-file -@end group - -@group -(key-binding "\C-p6") - @result{} nil -@end group -@end example - -@defun define-prefix-command symbol &optional mapvar prompt -@cindex prefix command -@anchor{Definition of define-prefix-command} -This function prepares @var{symbol} for use as a prefix key's binding: -it creates a sparse keymap and stores it as @var{symbol}'s function -definition. Subsequently binding a key sequence to @var{symbol} will -make that key sequence into a prefix key. The return value is @code{symbol}. - -This function also sets @var{symbol} as a variable, with the keymap as -its value. But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar} -as a variable instead. - -If @var{prompt} is non-@code{nil}, that becomes the overall prompt -string for the keymap. The prompt string should be given for menu keymaps -(@pxref{Defining Menus}). -@end defun - -@node Active Keymaps -@section Active Keymaps -@cindex active keymap - - Emacs contains many keymaps, but at any time only a few keymaps are -@dfn{active}. When Emacs receives user input, it translates the input -event (@pxref{Translation Keymaps}), and looks for a key binding in -the active keymaps. - - Usually, the active keymaps are: (i) the keymap specified by the -@code{keymap} property, (ii) the keymaps of enabled minor modes, (iii) -the current buffer's local keymap, and (iv) the global keymap, in that -order. Emacs searches for each input key sequence in all these -keymaps. - - Of these ``usual'' keymaps, the highest-precedence one is specified -by the @code{keymap} text or overlay property at point, if any. (For -a mouse input event, Emacs uses the event position instead of point; -@iftex -see the next section for details.) -@end iftex -@ifnottex -@pxref{Searching Keymaps}.) -@end ifnottex - - Next in precedence are keymaps specified by enabled minor modes. -These keymaps, if any, are specified by the variables -@code{emulation-mode-map-alists}, -@code{minor-mode-overriding-map-alist}, and -@code{minor-mode-map-alist}. @xref{Controlling Active Maps}. - -@cindex local keymap - Next in precedence is the buffer's @dfn{local keymap}, containing -key bindings specific to the buffer. The minibuffer also has a local -keymap (@pxref{Intro to Minibuffers}). If there is a @code{local-map} -text or overlay property at point, that specifies the local keymap to -use, in place of the buffer's default local keymap. - -@cindex major mode keymap - The local keymap is normally set by the buffer's major mode, and -every buffer with the same major mode shares the same local keymap. -Hence, if you call @code{local-set-key} (@pxref{Key Binding Commands}) -to change the local keymap in one buffer, that also affects the local -keymaps in other buffers with the same major mode. - -@cindex global keymap - Finally, the @dfn{global keymap} contains key bindings that are -defined regardless of the current buffer, such as @kbd{C-f}. It is -always active, and is bound to the variable @code{global-map}. - - Apart from the above ``usual'' keymaps, Emacs provides special ways -for programs to make other keymaps active. Firstly, the variable -@code{overriding-local-map} specifies a keymap that replaces the usual -active keymaps, except for the global keymap. Secondly, the -terminal-local variable @code{overriding-terminal-local-map} specifies -a keymap that takes precedence over @emph{all} other keymaps -(including @code{overriding-local-map}); this is normally used for -modal/transient keybindings (the function @code{set-transient-map} -provides a convenient interface for this). @xref{Controlling Active -Maps}, for details. - - Making keymaps active is not the only way to use them. Keymaps are -also used in other ways, such as for translating events within -@code{read-key-sequence}. @xref{Translation Keymaps}. - - @xref{Standard Keymaps}, for a list of some standard keymaps. - -@defun current-active-maps &optional olp position -This returns the list of active keymaps that would be used by the -command loop in the current circumstances to look up a key sequence. -Normally it ignores @code{overriding-local-map} and -@code{overriding-terminal-local-map}, but if @var{olp} is non-@code{nil} -then it pays attention to them. @var{position} can optionally be either -an event position as returned by @code{event-start} or a buffer -position, and may change the keymaps as described for -@code{key-binding}. -@end defun - -@defun key-binding key &optional accept-defaults no-remap position -This function returns the binding for @var{key} according to the -current active keymaps. The result is @code{nil} if @var{key} is -undefined in the keymaps. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}). - -When commands are remapped (@pxref{Remapping Commands}), -@code{key-binding} normally processes command remappings so as to -return the remapped command that will actually be executed. However, -if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores -remappings and returns the binding directly specified for @var{key}. - -If @var{key} starts with a mouse event (perhaps following a prefix -event), the maps to be consulted are determined based on the event's -position. Otherwise, they are determined based on the value of point. -However, you can override either of them by specifying @var{position}. -If @var{position} is non-@code{nil}, it should be either a buffer -position or an event position like the value of @code{event-start}. -Then the maps consulted are determined based on @var{position}. - -Emacs signals an error if @var{key} is not a string or a vector. - -@example -@group -(key-binding "\C-x\C-f") - @result{} find-file -@end group -@end example -@end defun - -@node Searching Keymaps -@section Searching the Active Keymaps -@cindex searching active keymaps for keys - -Here is a pseudo-Lisp summary of how Emacs searches the active -keymaps: - -@lisp -(or (if overriding-terminal-local-map - (@var{find-in} overriding-terminal-local-map)) - (if overriding-local-map - (@var{find-in} overriding-local-map) - (or (@var{find-in} (get-char-property (point) 'keymap)) - (@var{find-in-any} emulation-mode-map-alists) - (@var{find-in-any} minor-mode-overriding-map-alist) - (@var{find-in-any} minor-mode-map-alist) - (if (get-text-property (point) 'local-map) - (@var{find-in} (get-char-property (point) 'local-map)) - (@var{find-in} (current-local-map))))) - (@var{find-in} (current-global-map))) -@end lisp - -@noindent -Here, @var{find-in} and @var{find-in-any} are pseudo functions that -search in one keymap and in an alist of keymaps, respectively. Note -that the @code{set-transient-map} function works by setting -@code{overriding-terminal-local-map} (@pxref{Controlling Active -Maps}). - - In the above pseudo-code, if a key sequence starts with a mouse -event (@pxref{Mouse Events}), that event's position is used instead of -point, and the event's buffer is used instead of the current buffer. -In particular, this affects how the @code{keymap} and @code{local-map} -properties are looked up. If a mouse event occurs on a string -embedded with a @code{display}, @code{before-string}, or -@code{after-string} property (@pxref{Special Properties}), and the -string has a non-@code{nil} @code{keymap} or @code{local-map} -property, that overrides the corresponding property in the underlying -buffer text (i.e., the property specified by the underlying text is -ignored). - - When a key binding is found in one of the active keymaps, and that -binding is a command, the search is over---the command is executed. -However, if the binding is a symbol with a value or a string, Emacs -replaces the input key sequences with the variable's value or the -string, and restarts the search of the active keymaps. @xref{Key -Lookup}. - - The command which is finally found might also be remapped. -@xref{Remapping Commands}. - -@node Controlling Active Maps -@section Controlling the Active Keymaps - -@defvar global-map -This variable contains the default global keymap that maps Emacs -keyboard input to commands. The global keymap is normally this -keymap. The default global keymap is a full keymap that binds -@code{self-insert-command} to all of the printing characters. - -It is normal practice to change the bindings in the global keymap, but you -should not assign this variable any value other than the keymap it starts -out with. -@end defvar - -@defun current-global-map -This function returns the current global keymap. This is the same as -the value of @code{global-map} unless you change one or the other. -The return value is a reference, not a copy; if you use -@code{define-key} or other functions on it you will alter global -bindings. - -@example -@group -(current-global-map) -@result{} (keymap [set-mark-command beginning-of-line @dots{} - delete-backward-char]) -@end group -@end example -@end defun - -@defun current-local-map -This function returns the current buffer's local keymap, or @code{nil} -if it has none. In the following example, the keymap for the -@file{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap -in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse -keymap. - -@example -@group -(current-local-map) -@result{} (keymap - (10 . eval-print-last-sexp) - (9 . lisp-indent-line) - (127 . backward-delete-char-untabify) -@end group -@group - (27 keymap - (24 . eval-defun) - (17 . indent-sexp))) -@end group -@end example -@end defun - -@code{current-local-map} returns a reference to the local keymap, not -a copy of it; if you use @code{define-key} or other functions on it -you will alter local bindings. - -@defun current-minor-mode-maps -This function returns a list of the keymaps of currently enabled minor modes. -@end defun - -@defun use-global-map keymap -This function makes @var{keymap} the new current global keymap. It -returns @code{nil}. - -It is very unusual to change the global keymap. -@end defun - -@defun use-local-map keymap -This function makes @var{keymap} the new local keymap of the current -buffer. If @var{keymap} is @code{nil}, then the buffer has no local -keymap. @code{use-local-map} returns @code{nil}. Most major mode -commands use this function. -@end defun - -@defvar minor-mode-map-alist -@anchor{Definition of minor-mode-map-alist} -This variable is an alist describing keymaps that may or may not be -active according to the values of certain variables. Its elements look -like this: - -@example -(@var{variable} . @var{keymap}) -@end example - -The keymap @var{keymap} is active whenever @var{variable} has a -non-@code{nil} value. Typically @var{variable} is the variable that -enables or disables a minor mode. @xref{Keymaps and Minor Modes}. - -Note that elements of @code{minor-mode-map-alist} do not have the same -structure as elements of @code{minor-mode-alist}. The map must be the -@sc{cdr} of the element; a list with the map as the second element will -not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose -function definition is a keymap. - -When more than one minor mode keymap is active, the earlier one in -@code{minor-mode-map-alist} takes priority. But you should design -minor modes so that they don't interfere with each other. If you do -this properly, the order will not matter. - -See @ref{Keymaps and Minor Modes}, for more information about minor -modes. See also @code{minor-mode-key-binding} (@pxref{Functions for Key -Lookup}). -@end defvar - -@defvar minor-mode-overriding-map-alist -This variable allows major modes to override the key bindings for -particular minor modes. The elements of this alist look like the -elements of @code{minor-mode-map-alist}: @code{(@var{variable} -. @var{keymap})}. - -If a variable appears as an element of -@code{minor-mode-overriding-map-alist}, the map specified by that -element totally replaces any map specified for the same variable in -@code{minor-mode-map-alist}. - -@code{minor-mode-overriding-map-alist} is automatically buffer-local in -all buffers. -@end defvar - -@defvar overriding-local-map -If non-@code{nil}, this variable holds a keymap to use instead of the -buffer's local keymap, any text property or overlay keymaps, and any -minor mode keymaps. This keymap, if specified, overrides all other -maps that would have been active, except for the current global map. -@end defvar - -@defvar overriding-terminal-local-map -If non-@code{nil}, this variable holds a keymap to use instead of -@code{overriding-local-map}, the buffer's local keymap, text property -or overlay keymaps, and all the minor mode keymaps. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. It is used to implement -incremental search mode. -@end defvar - -@defvar overriding-local-map-menu-flag -If this variable is non-@code{nil}, the value of -@code{overriding-local-map} or @code{overriding-terminal-local-map} can -affect the display of the menu bar. The default value is @code{nil}, so -those map variables have no effect on the menu bar. - -Note that these two map variables do affect the execution of key -sequences entered using the menu bar, even if they do not affect the -menu bar display. So if a menu bar key sequence comes in, you should -clear the variables before looking up and executing that key sequence. -Modes that use the variables would typically do this anyway; normally -they respond to events that they do not handle by ``unreading'' them and -exiting. -@end defvar - -@defvar special-event-map -This variable holds a keymap for special events. If an event type has a -binding in this keymap, then it is special, and the binding for the -event is run directly by @code{read-event}. @xref{Special Events}. -@end defvar - -@defvar emulation-mode-map-alists -This variable holds a list of keymap alists to use for emulation -modes. It is intended for modes or packages using multiple minor-mode -keymaps. Each element is a keymap alist which has the same format and -meaning as @code{minor-mode-map-alist}, or a symbol with a variable -binding which is such an alist. The ``active'' keymaps in each alist -are used before @code{minor-mode-map-alist} and -@code{minor-mode-overriding-map-alist}. -@end defvar - -@cindex transient keymap -@defun set-transient-map keymap &optional keep -This function adds @var{keymap} as a @dfn{transient} keymap, which -takes precedence over other keymaps for one (or more) subsequent keys. - -Normally, @var{keymap} is used just once, to look up the very next -key. If the optional argument @var{pred} is @code{t}, the map stays -active as long as the user types keys defined in @var{keymap}; when -the user types a key that is not in @var{keymap}, the transient keymap -is deactivated and normal key lookup continues for that key. - -The @var{pred} argument can also be a function. In that case, the -function is called with no arguments, prior to running each command, -while @var{keymap} is active; it should return non-@code{nil} if -@var{keymap} should stay active. - -This function works by adding and removing @code{keymap} from the -variable @code{overriding-terminal-local-map}, which takes precedence -over all other active keymaps (@pxref{Searching Keymaps}). -@end defun - -@node Key Lookup -@section Key Lookup -@cindex key lookup -@cindex keymap entry - - @dfn{Key lookup} is the process of finding the binding of a key -sequence from a given keymap. The execution or use of the binding is -not part of key lookup. - - Key lookup uses just the event type of each event in the key sequence; -the rest of the event is ignored. In fact, a key sequence used for key -lookup may designate a mouse event with just its types (a symbol) -instead of the entire event (a list). @xref{Input Events}. Such -a ``key sequence'' is insufficient for @code{command-execute} to run, -but it is sufficient for looking up or rebinding a key. - - When the key sequence consists of multiple events, key lookup -processes the events sequentially: the binding of the first event is -found, and must be a keymap; then the second event's binding is found in -that keymap, and so on until all the events in the key sequence are used -up. (The binding thus found for the last event may or may not be a -keymap.) Thus, the process of key lookup is defined in terms of a -simpler process for looking up a single event in a keymap. How that is -done depends on the type of object associated with the event in that -keymap. - - Let's use the term @dfn{keymap entry} to describe the value found by -looking up an event type in a keymap. (This doesn't include the item -string and other extra elements in a keymap element for a menu item, because -@code{lookup-key} and other key lookup functions don't include them in -the returned value.) While any Lisp object may be stored in a keymap -as a keymap entry, not all make sense for key lookup. Here is a table -of the meaningful types of keymap entries: - -@table @asis -@item @code{nil} -@cindex @code{nil} in keymap -@code{nil} means that the events used so far in the lookup form an -undefined key. When a keymap fails to mention an event type at all, and -has no default binding, that is equivalent to a binding of @code{nil} -for that event type. - -@item @var{command} -@cindex command in keymap -The events used so far in the lookup form a complete key, -and @var{command} is its binding. @xref{What Is a Function}. - -@item @var{array} -@cindex string in keymap -The array (either a string or a vector) is a keyboard macro. The events -used so far in the lookup form a complete key, and the array is its -binding. See @ref{Keyboard Macros}, for more information. - -@item @var{keymap} -@cindex keymap in keymap -The events used so far in the lookup form a prefix key. The next -event of the key sequence is looked up in @var{keymap}. - -@item @var{list} -@cindex list in keymap -The meaning of a list depends on what it contains: - -@itemize @bullet -@item -If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list -is a keymap, and is treated as a keymap (see above). - -@item -@cindex @code{lambda} in keymap -If the @sc{car} of @var{list} is @code{lambda}, then the list is a -lambda expression. This is presumed to be a function, and is treated -as such (see above). In order to execute properly as a key binding, -this function must be a command---it must have an @code{interactive} -specification. @xref{Defining Commands}. - -@item -If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event -type, then this is an @dfn{indirect entry}: - -@example -(@var{othermap} . @var{othertype}) -@end example - -When key lookup encounters an indirect entry, it looks up instead the -binding of @var{othertype} in @var{othermap} and uses that. - -This feature permits you to define one key as an alias for another key. -For example, an entry whose @sc{car} is the keymap called @code{esc-map} -and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global -binding of @kbd{Meta-@key{SPC}}, whatever that may be''. -@end itemize - -@item @var{symbol} -@cindex symbol in keymap -The function definition of @var{symbol} is used in place of -@var{symbol}. If that too is a symbol, then this process is repeated, -any number of times. Ultimately this should lead to an object that is -a keymap, a command, or a keyboard macro. A list is allowed if it is a -keymap or a command, but indirect entries are not understood when found -via symbols. - -Note that keymaps and keyboard macros (strings and vectors) are not -valid functions, so a symbol with a keymap, string, or vector as its -function definition is invalid as a function. It is, however, valid as -a key binding. If the definition is a keyboard macro, then the symbol -is also valid as an argument to @code{command-execute} -(@pxref{Interactive Call}). - -@cindex @code{undefined} in keymap -The symbol @code{undefined} is worth special mention: it means to treat -the key as undefined. Strictly speaking, the key is defined, and its -binding is the command @code{undefined}; but that command does the same -thing that is done automatically for an undefined key: it rings the bell -(by calling @code{ding}) but does not signal an error. - -@cindex preventing prefix key -@code{undefined} is used in local keymaps to override a global key -binding and make the key ``undefined'' locally. A local binding of -@code{nil} would fail to do this because it would not override the -global binding. - -@item @var{anything else} -If any other type of object is found, the events used so far in the -lookup form a complete key, and the object is its binding, but the -binding is not executable as a command. -@end table - - In short, a keymap entry may be a keymap, a command, a keyboard -macro, a symbol that leads to one of them, or an indirection or -@code{nil}. - -@node Functions for Key Lookup -@section Functions for Key Lookup - - Here are the functions and variables pertaining to key lookup. - -@defun lookup-key keymap key &optional accept-defaults -This function returns the definition of @var{key} in @var{keymap}. All -the other functions described in this chapter that look up keys use -@code{lookup-key}. Here are examples: - -@example -@group -(lookup-key (current-global-map) "\C-x\C-f") - @result{} find-file -@end group -@group -(lookup-key (current-global-map) (kbd "C-x C-f")) - @result{} find-file -@end group -@group -(lookup-key (current-global-map) "\C-x\C-f12345") - @result{} 2 -@end group -@end example - -If the string or vector @var{key} is not a valid key sequence according -to the prefix keys specified in @var{keymap}, it must be ``too long'' -and have extra events at the end that do not fit into a single key -sequence. Then the value is a number, the number of events at the front -of @var{key} that compose a complete key. - -@c Emacs 19 feature -If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} -considers default bindings as well as bindings for the specific events -in @var{key}. Otherwise, @code{lookup-key} reports only bindings for -the specific sequence @var{key}, ignoring default bindings except when -you explicitly ask about them. (To do this, supply @code{t} as an -element of @var{key}; see @ref{Format of Keymaps}.) - -If @var{key} contains a meta character (not a function key), that -character is implicitly replaced by a two-character sequence: the value -of @code{meta-prefix-char}, followed by the corresponding non-meta -character. Thus, the first example below is handled by conversion into -the second example. - -@example -@group -(lookup-key (current-global-map) "\M-f") - @result{} forward-word -@end group -@group -(lookup-key (current-global-map) "\ef") - @result{} forward-word -@end group -@end example - -Unlike @code{read-key-sequence}, this function does not modify the -specified events in ways that discard information (@pxref{Key Sequence -Input}). In particular, it does not convert letters to lower case and -it does not change drag events to clicks. -@end defun - -@deffn Command undefined -Used in keymaps to undefine keys. It calls @code{ding}, but does -not cause an error. -@end deffn - -@defun local-key-binding key &optional accept-defaults -This function returns the binding for @var{key} in the current -local keymap, or @code{nil} if it is undefined there. - -@c Emacs 19 feature -The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). -@end defun - -@defun global-key-binding key &optional accept-defaults -This function returns the binding for command @var{key} in the -current global keymap, or @code{nil} if it is undefined there. - -@c Emacs 19 feature -The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). -@end defun - -@c Emacs 19 feature -@defun minor-mode-key-binding key &optional accept-defaults -This function returns a list of all the active minor mode bindings of -@var{key}. More precisely, it returns an alist of pairs -@code{(@var{modename} . @var{binding})}, where @var{modename} is the -variable that enables the minor mode, and @var{binding} is @var{key}'s -binding in that mode. If @var{key} has no minor-mode bindings, the -value is @code{nil}. - -If the first binding found is not a prefix definition (a keymap or a -symbol defined as a keymap), all subsequent bindings from other minor -modes are omitted, since they would be completely shadowed. Similarly, -the list omits non-prefix bindings that follow prefix bindings. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (above). -@end defun - -@defopt meta-prefix-char -@cindex @key{ESC} -This variable is the meta-prefix character code. It is used for -translating a meta character to a two-character sequence so it can be -looked up in a keymap. For useful results, the value should be a -prefix event (@pxref{Prefix Keys}). The default value is 27, which is -the @acronym{ASCII} code for @key{ESC}. - -As long as the value of @code{meta-prefix-char} remains 27, key lookup -translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined -as the @code{backward-word} command. However, if you were to set -@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will -translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the -@code{switch-to-buffer} command. (Don't actually do this!) Here is an -illustration of what would happen: - -@smallexample -@group -meta-prefix-char ; @r{The default value.} - @result{} 27 -@end group -@group -(key-binding "\M-b") - @result{} backward-word -@end group -@group -?\C-x ; @r{The print representation} - @result{} 24 ; @r{of a character.} -@end group -@group -(setq meta-prefix-char 24) - @result{} 24 -@end group -@group -(key-binding "\M-b") - @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is} - ; @r{like typing @kbd{C-x b}.} - -(setq meta-prefix-char 27) ; @r{Avoid confusion!} - @result{} 27 ; @r{Restore the default value!} -@end group -@end smallexample - -This translation of one event into two happens only for characters, not -for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function -key, is not converted into @kbd{@key{ESC} @key{F1}}. -@end defopt - -@node Changing Key Bindings -@section Changing Key Bindings -@cindex changing key bindings -@cindex rebinding - - The way to rebind a key is to change its entry in a keymap. If you -change a binding in the global keymap, the change is effective in all -buffers (though it has no direct effect in buffers that shadow the -global binding with a local one). If you change the current buffer's -local map, that usually affects all buffers using the same major mode. -The @code{global-set-key} and @code{local-set-key} functions are -convenient interfaces for these operations (@pxref{Key Binding -Commands}). You can also use @code{define-key}, a more general -function; then you must explicitly specify the map to change. - - When choosing the key sequences for Lisp programs to rebind, please -follow the Emacs conventions for use of various keys (@pxref{Key -Binding Conventions}). - -@cindex meta character key constants -@cindex control character key constants - In writing the key sequence to rebind, it is good to use the special -escape sequences for control and meta characters (@pxref{String Type}). -The syntax @samp{\C-} means that the following character is a control -character and @samp{\M-} means that the following character is a meta -character. Thus, the string @code{"\M-x"} is read as containing a -single @kbd{M-x}, @code{"\C-f"} is read as containing a single -@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as -containing a single @kbd{C-M-x}. You can also use this escape syntax in -vectors, as well as others that aren't allowed in strings; one example -is @samp{[?\C-\H-x home]}. @xref{Character Type}. - - The key definition and lookup functions accept an alternate syntax for -event types in a key sequence that is a vector: you can use a list -containing modifier names plus one base event (a character or function -key name). For example, @code{(control ?a)} is equivalent to -@code{?\C-a} and @code{(hyper control left)} is equivalent to -@code{C-H-left}. One advantage of such lists is that the precise -numeric codes for the modifier bits don't appear in compiled files. - - The functions below signal an error if @var{keymap} is not a keymap, -or if @var{key} is not a string or vector representing a key sequence. -You can use event types (symbols) as shorthand for events that are -lists. The @code{kbd} function (@pxref{Key Sequences}) is a -convenient way to specify the key sequence. - -@defun define-key keymap key binding -This function sets the binding for @var{key} in @var{keymap}. (If -@var{key} is more than one event long, the change is actually made -in another keymap reached from @var{keymap}.) The argument -@var{binding} can be any Lisp object, but only certain types are -meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) -The value returned by @code{define-key} is @var{binding}. - -If @var{key} is @code{[t]}, this sets the default binding in -@var{keymap}. When an event has no binding of its own, the Emacs -command loop uses the keymap's default binding, if there is one. - -@cindex invalid prefix key error -@cindex key sequence error -Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap) -or undefined; otherwise an error is signaled. If some prefix of -@var{key} is undefined, then @code{define-key} defines it as a prefix -key so that the rest of @var{key} can be defined as specified. - -If there was previously no binding for @var{key} in @var{keymap}, the -new binding is added at the beginning of @var{keymap}. The order of -bindings in a keymap makes no difference for keyboard input, but it -does matter for menu keymaps (@pxref{Menu Keymaps}). -@end defun - - This example creates a sparse keymap and makes a number of -bindings in it: - -@smallexample -@group -(setq map (make-sparse-keymap)) - @result{} (keymap) -@end group -@group -(define-key map "\C-f" 'forward-char) - @result{} forward-char -@end group -@group -map - @result{} (keymap (6 . forward-char)) -@end group - -@group -;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} -(define-key map (kbd "C-x f") 'forward-word) - @result{} forward-word -@end group -@group -map -@result{} (keymap - (24 keymap ; @kbd{C-x} - (102 . forward-word)) ; @kbd{f} - (6 . forward-char)) ; @kbd{C-f} -@end group - -@group -;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} -(define-key map (kbd "C-p") ctl-x-map) -;; @code{ctl-x-map} -@result{} [nil @dots{} find-file @dots{} backward-kill-sentence] -@end group - -@group -;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} -(define-key map (kbd "C-p C-f") 'foo) -@result{} 'foo -@end group -@group -map -@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.} - (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence]) - (24 keymap - (102 . forward-word)) - (6 . forward-char)) -@end group -@end smallexample - -@noindent -Note that storing a new binding for @kbd{C-p C-f} actually works by -changing an entry in @code{ctl-x-map}, and this has the effect of -changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the -default global map. - - The function @code{substitute-key-definition} scans a keymap for -keys that have a certain binding and rebinds them with a different -binding. Another feature which is cleaner and can often produce the -same results to remap one command into another (@pxref{Remapping -Commands}). - -@defun substitute-key-definition olddef newdef keymap &optional oldmap -@cindex replace bindings -This function replaces @var{olddef} with @var{newdef} for any keys in -@var{keymap} that were bound to @var{olddef}. In other words, -@var{olddef} is replaced with @var{newdef} wherever it appears. The -function returns @code{nil}. - -For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with -standard bindings: - -@smallexample -@group -(substitute-key-definition - 'find-file 'find-file-read-only (current-global-map)) -@end group -@end smallexample - -@c Emacs 19 feature -If @var{oldmap} is non-@code{nil}, that changes the behavior of -@code{substitute-key-definition}: the bindings in @var{oldmap} determine -which keys to rebind. The rebindings still happen in @var{keymap}, not -in @var{oldmap}. Thus, you can change one map under the control of the -bindings in another. For example, - -@smallexample -(substitute-key-definition - 'delete-backward-char 'my-funny-delete - my-map global-map) -@end smallexample - -@noindent -puts the special deletion command in @code{my-map} for whichever keys -are globally bound to the standard deletion command. - -Here is an example showing a keymap before and after substitution: - -@smallexample -@group -(setq map '(keymap - (?1 . olddef-1) - (?2 . olddef-2) - (?3 . olddef-1))) -@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1)) -@end group - -@group -(substitute-key-definition 'olddef-1 'newdef map) -@result{} nil -@end group -@group -map -@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef)) -@end group -@end smallexample -@end defun - -@defun suppress-keymap keymap &optional nodigits -@cindex @code{self-insert-command} override -This function changes the contents of the full keymap @var{keymap} by -remapping @code{self-insert-command} to the command @code{undefined} -(@pxref{Remapping Commands}). This has the effect of undefining all -printing characters, thus making ordinary insertion of text impossible. -@code{suppress-keymap} returns @code{nil}. - -If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines -digits to run @code{digit-argument}, and @kbd{-} to run -@code{negative-argument}. Otherwise it makes them undefined like the -rest of the printing characters. - -@cindex yank suppression -@cindex @code{quoted-insert} suppression -The @code{suppress-keymap} function does not make it impossible to -modify a buffer, as it does not suppress commands such as @code{yank} -and @code{quoted-insert}. To prevent any modification of a buffer, make -it read-only (@pxref{Read Only Buffers}). - -Since this function modifies @var{keymap}, you would normally use it -on a newly created keymap. Operating on an existing keymap -that is used for some other purpose is likely to cause trouble; for -example, suppressing @code{global-map} would make it impossible to use -most of Emacs. - -This function can be used to initialize the local keymap of a major -mode for which insertion of text is not desirable. But usually such a -mode should be derived from @code{special-mode} (@pxref{Basic Major -Modes}); then its keymap will automatically inherit from -@code{special-mode-map}, which is already suppressed. Here is how -@code{special-mode-map} is defined: - -@smallexample -@group -(defvar special-mode-map - (let ((map (make-sparse-keymap))) - (suppress-keymap map) - (define-key map "q" 'quit-window) - @dots{} - map)) -@end group -@end smallexample -@end defun - -@node Remapping Commands -@section Remapping Commands -@cindex remapping commands - - A special kind of key binding can be used to @dfn{remap} one command -to another, without having to refer to the key sequence(s) bound to -the original command. To use this feature, make a key binding for a -key sequence that starts with the dummy event @code{remap}, followed -by the command name you want to remap; for the binding, specify the -new definition (usually a command name, but possibly any other valid -definition for a key binding). - - For example, suppose My mode provides a special command -@code{my-kill-line}, which should be invoked instead of -@code{kill-line}. To establish this, its mode keymap should contain -the following remapping: - -@smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -@end smallexample - -@noindent -Then, whenever @code{my-mode-map} is active, if the user types -@kbd{C-k} (the default global key sequence for @code{kill-line}) Emacs -will instead run @code{my-kill-line}. - - Note that remapping only takes place through active keymaps; for -example, putting a remapping in a prefix keymap like @code{ctl-x-map} -typically has no effect, as such keymaps are not themselves active. -In addition, remapping only works through a single level; in the -following example, - -@smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line) -@end smallexample - -@noindent -@code{kill-line} is @emph{not} remapped to @code{my-other-kill-line}. -Instead, if an ordinary key binding specifies @code{kill-line}, it is -remapped to @code{my-kill-line}; if an ordinary binding specifies -@code{my-kill-line}, it is remapped to @code{my-other-kill-line}. - -To undo the remapping of a command, remap it to @code{nil}; e.g., - -@smallexample -(define-key my-mode-map [remap kill-line] nil) -@end smallexample - -@defun command-remapping command &optional position keymaps -This function returns the remapping for @var{command} (a symbol), -given the current active keymaps. If @var{command} is not remapped -(which is the usual situation), or not a symbol, the function returns -@code{nil}. @code{position} can optionally specify a buffer position -or an event position to determine the keymaps to use, as in -@code{key-binding}. - -If the optional argument @code{keymaps} is non-@code{nil}, it -specifies a list of keymaps to search in. This argument is ignored if -@code{position} is non-@code{nil}. -@end defun - -@node Translation Keymaps -@section Keymaps for Translating Sequences of Events -@cindex translation keymap -@cindex keymaps for translating events - - When the @code{read-key-sequence} function reads a key sequence -(@pxref{Key Sequence Input}), it uses @dfn{translation keymaps} to -translate certain event sequences into others. The translation -keymaps are @code{input-decode-map}, @code{local-function-key-map}, -and @code{key-translation-map} (in order of priority). - - Translation keymaps have the same structure as other keymaps, but -are used differently: they specify translations to make while reading -key sequences, rather than bindings for complete key sequences. As -each key sequence is read, it is checked against each translation -keymap. If one of the translation keymaps ``binds'' @var{k} to a -vector @var{v}, then whenever @var{k} appears as a sub-sequence -@emph{anywhere} in a key sequence, that sub-sequence is replaced with -the events in @var{v}. - - For example, VT100 terminals send @kbd{@key{ESC} O P} when the -keypad key @key{PF1} is pressed. On such terminals, Emacs must -translate that sequence of events into a single event @code{pf1}. -This is done by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in -@code{input-decode-map}. Thus, when you type @kbd{C-c @key{PF1}} on -the terminal, the terminal emits the character sequence @kbd{C-c -@key{ESC} O P}, and @code{read-key-sequence} translates this back into -@kbd{C-c @key{PF1}} and returns it as the vector @code{[?\C-c pf1]}. - - Translation keymaps take effect only after Emacs has decoded the -keyboard input (via the input coding system specified by -@code{keyboard-coding-system}). @xref{Terminal I/O Encoding}. - -@defvar input-decode-map -This variable holds a keymap that describes the character sequences sent -by function keys on an ordinary character terminal. - -The value of @code{input-decode-map} is usually set up automatically -according to the terminal's Terminfo or Termcap entry, but sometimes -those need help from terminal-specific Lisp files. Emacs comes with -terminal-specific files for many common terminals; their main purpose is -to make entries in @code{input-decode-map} beyond those that can be -deduced from Termcap and Terminfo. @xref{Terminal-Specific}. -@end defvar - -@defvar local-function-key-map -This variable holds a keymap similar to @code{input-decode-map} except -that it describes key sequences which should be translated to -alternative interpretations that are usually preferred. It applies -after @code{input-decode-map} and before @code{key-translation-map}. - -Entries in @code{local-function-key-map} are ignored if they conflict -with bindings made in the minor mode, local, or global keymaps. I.e., -the remapping only applies if the original key sequence would -otherwise not have any binding. - -@code{local-function-key-map} inherits from @code{function-key-map}, -but the latter should not be used directly. -@end defvar - -@defvar key-translation-map -This variable is another keymap used just like @code{input-decode-map} -to translate input events into other events. It differs from -@code{input-decode-map} in that it goes to work after -@code{local-function-key-map} is finished rather than before; it -receives the results of translation by @code{local-function-key-map}. - -Just like @code{input-decode-map}, but unlike -@code{local-function-key-map}, this keymap is applied regardless of -whether the input key-sequence has a normal binding. Note however -that actual key bindings can have an effect on -@code{key-translation-map}, even though they are overridden by it. -Indeed, actual key bindings override @code{local-function-key-map} and -thus may alter the key sequence that @code{key-translation-map} -receives. Clearly, it is better to avoid this type of situation. - -The intent of @code{key-translation-map} is for users to map one -character set to another, including ordinary characters normally bound -to @code{self-insert-command}. -@end defvar - -@cindex key translation function -You can use @code{input-decode-map}, @code{local-function-key-map}, -and @code{key-translation-map} for more than simple aliases, by using -a function, instead of a key sequence, as the ``translation'' of a -key. Then this function is called to compute the translation of that -key. - -The key translation function receives one argument, which is the prompt -that was specified in @code{read-key-sequence}---or @code{nil} if the -key sequence is being read by the editor command loop. In most cases -you can ignore the prompt value. - -If the function reads input itself, it can have the effect of altering -the event that follows. For example, here's how to define @kbd{C-c h} -to turn the character that follows into a Hyper character: - -@example -@group -(defun hyperify (prompt) - (let ((e (read-event))) - (vector (if (numberp e) - (logior (lsh 1 24) e) - (if (memq 'hyper (event-modifiers e)) - e - (add-event-modifier "H-" e)))))) - -(defun add-event-modifier (string e) - (let ((symbol (if (symbolp e) e (car e)))) - (setq symbol (intern (concat string - (symbol-name symbol)))) - (if (symbolp e) - symbol - (cons symbol (cdr e))))) - -(define-key local-function-key-map "\C-ch" 'hyperify) -@end group -@end example - -@subsection Interaction with normal keymaps - -The end of a key sequence is detected when that key sequence either is bound -to a command, or when Emacs determines that no additional event can lead -to a sequence that is bound to a command. - -This means that, while @code{input-decode-map} and @code{key-translation-map} -apply regardless of whether the original key sequence would have a binding, the -presence of such a binding can still prevent translation from taking place. -For example, let us return to our VT100 example above and add a binding for -@kbd{C-c @key{ESC}} to the global map; now when the user hits @kbd{C-c -@key{PF1}} Emacs will fail to decode @kbd{C-c @key{ESC} O P} into @kbd{C-c -@key{PF1}} because it will stop reading keys right after @kbd{C-x @key{ESC}}, -leaving @kbd{O P} for later. This is in case the user really hit @kbd{C-c -@key{ESC}}, in which case Emacs should not sit there waiting for the next key -to decide whether the user really pressed @kbd{@key{ESC}} or @kbd{@key{PF1}}. - -For that reason, it is better to avoid binding commands to key sequences where -the end of the key sequence is a prefix of a key translation. The main such -problematic suffixes/prefixes are @kbd{@key{ESC}}, @kbd{M-O} (which is really -@kbd{@key{ESC} O}) and @kbd{M-[} (which is really @kbd{@key{ESC} [}). - -@node Key Binding Commands -@section Commands for Binding Keys - - This section describes some convenient interactive interfaces for -changing key bindings. They work by calling @code{define-key}. - - People often use @code{global-set-key} in their init files -(@pxref{Init File}) for simple customization. For example, - -@smallexample -(global-set-key (kbd "C-x C-\\") 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [?\C-x ?\C-\\] 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [(control ?x) (control ?\\)] 'next-line) -@end smallexample - -@noindent -redefines @kbd{C-x C-\} to move down a line. - -@smallexample -(global-set-key [M-mouse-1] 'mouse-set-point) -@end smallexample - -@noindent -redefines the first (leftmost) mouse button, entered with the Meta key, to -set point where you click. - -@cindex non-@acronym{ASCII} text in keybindings - Be careful when using non-@acronym{ASCII} text characters in Lisp -specifications of keys to bind. If these are read as multibyte text, as -they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you -must type the keys as multibyte too. For instance, if you use this: - -@smallexample -(global-set-key "@"o" 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -or - -@smallexample -(global-set-key ?@"o 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -and your language environment is multibyte Latin-1, these commands -actually bind the multibyte character with code 246, not the byte -code 246 (@kbd{M-v}) sent by a Latin-1 terminal. In order to use this -binding, you need to teach Emacs how to decode the keyboard by using an -appropriate input method (@pxref{Input Methods, , Input Methods, emacs, The GNU -Emacs Manual}). - -@deffn Command global-set-key key binding -This function sets the binding of @var{key} in the current global map -to @var{binding}. - -@smallexample -@group -(global-set-key @var{key} @var{binding}) -@equiv{} -(define-key (current-global-map) @var{key} @var{binding}) -@end group -@end smallexample -@end deffn - -@deffn Command global-unset-key key -@cindex unbinding keys -This function removes the binding of @var{key} from the current -global map. - -One use of this function is in preparation for defining a longer key -that uses @var{key} as a prefix---which would not be allowed if -@var{key} has a non-prefix binding. For example: - -@smallexample -@group -(global-unset-key "\C-l") - @result{} nil -@end group -@group -(global-set-key "\C-l\C-l" 'redraw-display) - @result{} nil -@end group -@end smallexample - -This function is equivalent to using @code{define-key} as follows: - -@smallexample -@group -(global-unset-key @var{key}) -@equiv{} -(define-key (current-global-map) @var{key} nil) -@end group -@end smallexample -@end deffn - -@deffn Command local-set-key key binding -This function sets the binding of @var{key} in the current local -keymap to @var{binding}. - -@smallexample -@group -(local-set-key @var{key} @var{binding}) -@equiv{} -(define-key (current-local-map) @var{key} @var{binding}) -@end group -@end smallexample -@end deffn - -@deffn Command local-unset-key key -This function removes the binding of @var{key} from the current -local map. - -@smallexample -@group -(local-unset-key @var{key}) -@equiv{} -(define-key (current-local-map) @var{key} nil) -@end group -@end smallexample -@end deffn - -@node Scanning Keymaps -@section Scanning Keymaps - - This section describes functions used to scan all the current keymaps -for the sake of printing help information. - -@defun accessible-keymaps keymap &optional prefix -This function returns a list of all the keymaps that can be reached (via -zero or more prefix keys) from @var{keymap}. The value is an -association list with elements of the form @code{(@var{key} .@: -@var{map})}, where @var{key} is a prefix key whose definition in -@var{keymap} is @var{map}. - -The elements of the alist are ordered so that the @var{key} increases -in length. The first element is always @code{([] .@: @var{keymap})}, -because the specified keymap is accessible from itself with a prefix of -no events. - -If @var{prefix} is given, it should be a prefix key sequence; then -@code{accessible-keymaps} includes only the submaps whose prefixes start -with @var{prefix}. These elements look just as they do in the value of -@code{(accessible-keymaps)}; the only difference is that some elements -are omitted. - -In the example below, the returned alist indicates that the key -@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose -definition is the sparse keymap @code{(keymap (83 .@: center-paragraph) -(115 .@: foo))}. - -@smallexample -@group -(accessible-keymaps (current-local-map)) -@result{}(([] keymap - (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.} - (83 . center-paragraph) - (115 . center-line)) - (9 . tab-to-tab-stop)) -@end group - -@group - ("^[" keymap - (83 . center-paragraph) - (115 . foo))) -@end group -@end smallexample - -In the following example, @kbd{C-h} is a prefix key that uses a sparse -keymap starting with @code{(keymap (118 . describe-variable)@dots{})}. -Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of -the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of -several dummy events used as prefixes for mouse actions in special parts -of a window. - -@smallexample -@group -(accessible-keymaps (current-global-map)) -@result{} (([] keymap [set-mark-command beginning-of-line @dots{} - delete-backward-char]) -@end group -@group - ("^H" keymap (118 . describe-variable) @dots{} - (8 . help-for-help)) -@end group -@group - ("^X" keymap [x-flush-mouse-queue @dots{} - backward-kill-sentence]) -@end group -@group - ("^[" keymap [mark-sexp backward-sexp @dots{} - backward-kill-word]) -@end group - ("^X4" keymap (15 . display-buffer) @dots{}) -@group - ([mode-line] keymap - (S-mouse-2 . mouse-split-window-horizontally) @dots{})) -@end group -@end smallexample - -@noindent -These are not all the keymaps you would see in actuality. -@end defun - -@defun map-keymap function keymap -The function @code{map-keymap} calls @var{function} once -for each binding in @var{keymap}. It passes two arguments, -the event type and the value of the binding. If @var{keymap} -has a parent, the parent's bindings are included as well. -This works recursively: if the parent has itself a parent, then the -grandparent's bindings are also included and so on. - -This function is the cleanest way to examine all the bindings -in a keymap. -@end defun - -@defun where-is-internal command &optional keymap firstonly noindirect no-remap -This function is a subroutine used by the @code{where-is} command -(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list -of all key sequences (of any length) that are bound to @var{command} in a -set of keymaps. - -The argument @var{command} can be any object; it is compared with all -keymap entries using @code{eq}. - -If @var{keymap} is @code{nil}, then the maps used are the current active -keymaps, disregarding @code{overriding-local-map} (that is, pretending -its value is @code{nil}). If @var{keymap} is a keymap, then the -maps searched are @var{keymap} and the global keymap. If @var{keymap} -is a list of keymaps, only those keymaps are searched. - -Usually it's best to use @code{overriding-local-map} as the expression -for @var{keymap}. Then @code{where-is-internal} searches precisely -the keymaps that are active. To search only the global map, pass the -value @code{(keymap)} (an empty keymap) as @var{keymap}. - -If @var{firstonly} is @code{non-ascii}, then the value is a single -vector representing the first key sequence found, rather than a list of -all possible key sequences. If @var{firstonly} is @code{t}, then the -value is the first key sequence, except that key sequences consisting -entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} -characters) are preferred to all other key sequences and that the -return value can never be a menu binding. - -If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't -follow indirect keymap bindings. This makes it possible to search for -an indirect definition itself. - -The fifth argument, @var{no-remap}, determines how this function -treats command remappings (@pxref{Remapping Commands}). There are two -cases of interest: - -@table @asis -@item If a command @var{other-command} is remapped to @var{command}: -If @var{no-remap} is @code{nil}, find the bindings for -@var{other-command} and treat them as though they are also bindings -for @var{command}. If @var{no-remap} is non-@code{nil}, include the -vector @code{[remap @var{other-command}]} in the list of possible key -sequences, instead of finding those bindings. - -@item If @var{command} is remapped to @var{other-command}: -If @var{no-remap} is @code{nil}, return the bindings for -@var{other-command} rather than @var{command}. If @var{no-remap} is -non-@code{nil}, return the bindings for @var{command}, ignoring the -fact that it is remapped. -@end table -@end defun - -@deffn Command describe-bindings &optional prefix buffer-or-name -This function creates a listing of all current key bindings, and -displays it in a buffer named @file{*Help*}. The text is grouped by -modes---minor modes first, then the major mode, then global bindings. - -If @var{prefix} is non-@code{nil}, it should be a prefix key; then the -listing includes only keys that start with @var{prefix}. - -When several characters with consecutive @acronym{ASCII} codes have the -same definition, they are shown together, as -@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to -know the @acronym{ASCII} codes to understand which characters this means. -For example, in the default global map, the characters @samp{@key{SPC} -..@: ~} are described by a single line. @key{SPC} is @acronym{ASCII} 32, -@kbd{~} is @acronym{ASCII} 126, and the characters between them include all -the normal printing characters, (e.g., letters, digits, punctuation, -etc.@:); all these characters are bound to @code{self-insert-command}. - -If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a -buffer name. Then @code{describe-bindings} lists that buffer's bindings, -instead of the current buffer's. -@end deffn - -@node Menu Keymaps -@section Menu Keymaps -@cindex menu keymaps - -A keymap can operate as a menu as well as defining bindings for -keyboard keys and mouse buttons. Menus are usually actuated with the -mouse, but they can function with the keyboard also. If a menu keymap -is active for the next input event, that activates the keyboard menu -feature. - -@menu -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. -* Easy Menu:: A convenience macro for making menus. -@end menu - -@node Defining Menus -@subsection Defining Menus -@cindex defining menus -@cindex menu prompt string -@cindex prompt string (of menu) -@cindex menu item - -A keymap acts as a menu if it has an @dfn{overall prompt string}, -which is a string that appears as an element of the keymap. -(@xref{Format of Keymaps}.) The string should describe the purpose of -the menu's commands. Emacs displays the overall prompt string as the -menu title in some cases, depending on the toolkit (if any) used for -displaying menus.@footnote{It is required for menus which do not use a -toolkit, e.g., on a text terminal.} Keyboard menus also display the -overall prompt string. - -The easiest way to construct a keymap with a prompt string is to -specify the string as an argument when you call @code{make-keymap}, -@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or -@code{define-prefix-command} (@pxref{Definition of -define-prefix-command}). If you do not want the keymap to operate as -a menu, don't specify a prompt string for it. - -@defun keymap-prompt keymap -This function returns the overall prompt string of @var{keymap}, -or @code{nil} if it has none. -@end defun - -The menu's items are the bindings in the keymap. Each binding -associates an event type to a definition, but the event types have no -significance for the menu appearance. (Usually we use pseudo-events, -symbols that the keyboard cannot generate, as the event types for menu -item bindings.) The menu is generated entirely from the bindings that -correspond in the keymap to these events. - -The order of items in the menu is the same as the order of bindings in -the keymap. Since @code{define-key} puts new bindings at the front, you -should define the menu items starting at the bottom of the menu and -moving to the top, if you care about the order. When you add an item to -an existing menu, you can specify its position in the menu using -@code{define-key-after} (@pxref{Modifying Menus}). - -@menu -* Simple Menu Items:: A simple kind of menu key binding. -* Extended Menu Items:: More complex menu item definitions. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. -@end menu - -@node Simple Menu Items -@subsubsection Simple Menu Items - - The simpler (and original) way to define a menu item is to bind some -event type (it doesn't matter what event type) to a binding like this: - -@example -(@var{item-string} . @var{real-binding}) -@end example - -@noindent -The @sc{car}, @var{item-string}, is the string to be displayed in the -menu. It should be short---preferably one to three words. It should -describe the action of the command it corresponds to. Note that not -all graphical toolkits can display non-@acronym{ASCII} text in menus -(it will work for keyboard menus and will work to a large extent with -the GTK+ toolkit). - - You can also supply a second string, called the help string, as follows: - -@example -(@var{item-string} @var{help} . @var{real-binding}) -@end example - -@noindent -@var{help} specifies a ``help-echo'' string to display while the mouse -is on that item in the same way as @code{help-echo} text properties -(@pxref{Help display}). - - As far as @code{define-key} is concerned, @var{item-string} and -@var{help-string} are part of the event's binding. However, -@code{lookup-key} returns just @var{real-binding}, and only -@var{real-binding} is used for executing the key. - - If @var{real-binding} is @code{nil}, then @var{item-string} appears in -the menu but cannot be selected. - - If @var{real-binding} is a symbol and has a non-@code{nil} -@code{menu-enable} property, that property is an expression that -controls whether the menu item is enabled. Every time the keymap is -used to display a menu, Emacs evaluates the expression, and it enables -the menu item only if the expression's value is non-@code{nil}. When a -menu item is disabled, it is displayed in a ``fuzzy'' fashion, and -cannot be selected. - - The menu bar does not recalculate which items are enabled every time you -look at a menu. This is because the X toolkit requires the whole tree -of menus in advance. To force recalculation of the menu bar, call -@code{force-mode-line-update} (@pxref{Mode Line Format}). - -@node Extended Menu Items -@subsubsection Extended Menu Items -@kindex menu-item -@cindex extended menu item - - An extended-format menu item is a more flexible and also cleaner -alternative to the simple format. You define an event type with a -binding that's a list starting with the symbol @code{menu-item}. -For a non-selectable string, the binding looks like this: - -@example -(menu-item @var{item-name}) -@end example - -@noindent -A string starting with two or more dashes specifies a separator line; -see @ref{Menu Separators}. - - To define a real menu item which can be selected, the extended format -binding looks like this: - -@example -(menu-item @var{item-name} @var{real-binding} - . @var{item-property-list}) -@end example - -@noindent -Here, @var{item-name} is an expression which evaluates to the menu item -string. Thus, the string need not be a constant. The third element, -@var{real-binding}, is the command to execute. The tail of the list, -@var{item-property-list}, has the form of a property list which contains -other information. - - Here is a table of the properties that are supported: - -@table @code -@item :enable @var{form} -The result of evaluating @var{form} determines whether the item is -enabled (non-@code{nil} means yes). If the item is not enabled, -you can't really click on it. - -@item :visible @var{form} -The result of evaluating @var{form} determines whether the item should -actually appear in the menu (non-@code{nil} means yes). If the item -does not appear, then the menu is displayed as if this item were -not defined at all. - -@item :help @var{help} -The value of this property, @var{help}, specifies a ``help-echo'' string -to display while the mouse is on that item. This is displayed in the -same way as @code{help-echo} text properties (@pxref{Help display}). -Note that this must be a constant string, unlike the @code{help-echo} -property for text and overlays. - -@item :button (@var{type} . @var{selected}) -This property provides a way to define radio buttons and toggle buttons. -The @sc{car}, @var{type}, says which: it should be @code{:toggle} or -@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the -result of evaluating it says whether this button is currently selected. - -A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off'' -according to the value of @var{selected}. The command itself should -toggle @var{selected}, setting it to @code{t} if it is @code{nil}, -and to @code{nil} if it is @code{t}. Here is how the menu item -to toggle the @code{debug-on-error} flag is defined: - -@example -(menu-item "Debug on Error" toggle-debug-on-error - :button (:toggle - . (and (boundp 'debug-on-error) - debug-on-error))) -@end example - -@noindent -This works because @code{toggle-debug-on-error} is defined as a command -which toggles the variable @code{debug-on-error}. - -@dfn{Radio buttons} are a group of menu items, in which at any time one -and only one is ``selected''. There should be a variable whose value -says which one is selected at any time. The @var{selected} form for -each radio button in the group should check whether the variable has the -right value for selecting that button. Clicking on the button should -set the variable so that the button you clicked on becomes selected. - -@item :key-sequence @var{key-sequence} -This property specifies which key sequence is likely to be bound to the -same command invoked by this menu item. If you specify the right key -sequence, that makes preparing the menu for display run much faster. - -If you specify the wrong key sequence, it has no effect; before Emacs -displays @var{key-sequence} in the menu, it verifies that -@var{key-sequence} is really equivalent to this menu item. - -@item :key-sequence nil -This property indicates that there is normally no key binding which is -equivalent to this menu item. Using this property saves time in -preparing the menu for display, because Emacs does not need to search -the keymaps for a keyboard equivalent for this menu item. - -However, if the user has rebound this item's definition to a key -sequence, Emacs ignores the @code{:keys} property and finds the keyboard -equivalent anyway. - -@item :keys @var{string} -This property specifies that @var{string} is the string to display -as the keyboard equivalent for this menu item. You can use -the @samp{\\[...]} documentation construct in @var{string}. - -@item :filter @var{filter-fn} -This property provides a way to compute the menu item dynamically. -The property value @var{filter-fn} should be a function of one argument; -when it is called, its argument will be @var{real-binding}. The -function should return the binding to use instead. - -Emacs can call this function at any time that it does redisplay or -operates on menu data structures, so you should write it so it can -safely be called at any time. -@end table - -@node Menu Separators -@subsubsection Menu Separators -@cindex menu separators - - A menu separator is a kind of menu item that doesn't display any -text---instead, it divides the menu into subparts with a horizontal line. -A separator looks like this in the menu keymap: - -@example -(menu-item @var{separator-type}) -@end example - -@noindent -where @var{separator-type} is a string starting with two or more dashes. - - In the simplest case, @var{separator-type} consists of only dashes. -That specifies the default kind of separator. (For compatibility, -@code{""} and @code{-} also count as separators.) - - Certain other values of @var{separator-type} specify a different -style of separator. Here is a table of them: - -@table @code -@item "--no-line" -@itemx "--space" -An extra vertical space, with no actual line. - -@item "--single-line" -A single line in the menu's foreground color. - -@item "--double-line" -A double line in the menu's foreground color. - -@item "--single-dashed-line" -A single dashed line in the menu's foreground color. - -@item "--double-dashed-line" -A double dashed line in the menu's foreground color. - -@item "--shadow-etched-in" -A single line with a 3D sunken appearance. This is the default, -used separators consisting of dashes only. - -@item "--shadow-etched-out" -A single line with a 3D raised appearance. - -@item "--shadow-etched-in-dash" -A single dashed line with a 3D sunken appearance. - -@item "--shadow-etched-out-dash" -A single dashed line with a 3D raised appearance. - -@item "--shadow-double-etched-in" -Two lines with a 3D sunken appearance. - -@item "--shadow-double-etched-out" -Two lines with a 3D raised appearance. - -@item "--shadow-double-etched-in-dash" -Two dashed lines with a 3D sunken appearance. - -@item "--shadow-double-etched-out-dash" -Two dashed lines with a 3D raised appearance. -@end table - - You can also give these names in another style, adding a colon after -the double-dash and replacing each single dash with capitalization of -the following word. Thus, @code{"--:singleLine"}, is equivalent to -@code{"--single-line"}. - - You can use a longer form to specify keywords such as @code{:enable} -and @code{:visible} for a menu separator: - -@code{(menu-item @var{separator-type} nil . @var{item-property-list})} - -For example: - -@example -(menu-item "--" nil :visible (boundp 'foo)) -@end example - - Some systems and display toolkits don't really handle all of these -separator types. If you use a type that isn't supported, the menu -displays a similar kind of separator that is supported. - -@node Alias Menu Items -@subsubsection Alias Menu Items - - Sometimes it is useful to make menu items that use the ``same'' -command but with different enable conditions. The best way to do this -in Emacs now is with extended menu items; before that feature existed, -it could be done by defining alias commands and using them in menu -items. Here's an example that makes two aliases for -@code{read-only-mode} and gives them different enable conditions: - -@example -(defalias 'make-read-only 'read-only-mode) -(put 'make-read-only 'menu-enable '(not buffer-read-only)) -(defalias 'make-writable 'read-only-mode) -(put 'make-writable 'menu-enable 'buffer-read-only) -@end example - -When using aliases in menus, often it is useful to display the -equivalent key bindings for the ``real'' command name, not the aliases -(which typically don't have any key bindings except for the menu -itself). To request this, give the alias symbol a non-@code{nil} -@code{menu-alias} property. Thus, - -@example -(put 'make-read-only 'menu-alias t) -(put 'make-writable 'menu-alias t) -@end example - -@noindent -causes menu items for @code{make-read-only} and @code{make-writable} to -show the keyboard bindings for @code{read-only-mode}. - -@node Mouse Menus -@subsection Menus and the Mouse - - The usual way to make a menu keymap produce a menu is to make it the -definition of a prefix key. (A Lisp program can explicitly pop up a -menu and receive the user's choice---see @ref{Pop-Up Menus}.) - - If the prefix key ends with a mouse event, Emacs handles the menu keymap -by popping up a visible menu, so that the user can select a choice with -the mouse. When the user clicks on a menu item, the event generated is -whatever character or symbol has the binding that brought about that -menu item. (A menu item may generate a series of events if the menu has -multiple levels or comes from the menu bar.) - - It's often best to use a button-down event to trigger the menu. Then -the user can select a menu item by releasing the button. - -@cindex submenu - If the menu keymap contains a binding to a nested keymap, the nested -keymap specifies a @dfn{submenu}. There will be a menu item, labeled -by the nested keymap's item string, and clicking on this item -automatically pops up the specified submenu. As a special exception, -if the menu keymap contains a single nested keymap and no other menu -items, the menu shows the contents of the nested keymap directly, not -as a submenu. - - However, if Emacs is compiled without X toolkit support, or on text -terminals, submenus are not supported. Each nested keymap is shown as -a menu item, but clicking on it does not automatically pop up the -submenu. If you wish to imitate the effect of submenus, you can do -that by giving a nested keymap an item string which starts with -@samp{@@}. This causes Emacs to display the nested keymap using a -separate @dfn{menu pane}; the rest of the item string after the -@samp{@@} is the pane label. If Emacs is compiled without X toolkit -support, or if a menu is displayed on a text terminal, menu panes are -not used; in that case, a @samp{@@} at the beginning of an item string -is omitted when the menu label is displayed, and has no other effect. - -@node Keyboard Menus -@subsection Menus and the Keyboard - - When a prefix key ending with a keyboard event (a character or -function key) has a definition that is a menu keymap, the keymap -operates as a keyboard menu; the user specifies the next event by -choosing a menu item with the keyboard. - - Emacs displays the keyboard menu with the map's overall prompt -string, followed by the alternatives (the item strings of the map's -bindings), in the echo area. If the bindings don't all fit at once, -the user can type @key{SPC} to see the next line of alternatives. -Successive uses of @key{SPC} eventually get to the end of the menu and -then cycle around to the beginning. (The variable -@code{menu-prompt-more-char} specifies which character is used for -this; @key{SPC} is the default.) - - When the user has found the desired alternative from the menu, he or -she should type the corresponding character---the one whose binding is -that alternative. - -@defvar menu-prompt-more-char -This variable specifies the character to use to ask to see -the next line of a menu. Its initial value is 32, the code -for @key{SPC}. -@end defvar - -@node Menu Example -@subsection Menu Example -@cindex menu definition example - - Here is a complete example of defining a menu keymap. It is the -definition of the @samp{Replace} submenu in the @samp{Edit} menu in -the menu bar, and it uses the extended menu item format -(@pxref{Extended Menu Items}). First we create the keymap, and give -it a name: - -@smallexample -(defvar menu-bar-replace-menu (make-sparse-keymap "Replace")) -@end smallexample - -@noindent -Next we define the menu items: - -@smallexample -(define-key menu-bar-replace-menu [tags-repl-continue] - '(menu-item "Continue Replace" tags-loop-continue - :help "Continue last tags replace operation")) -(define-key menu-bar-replace-menu [tags-repl] - '(menu-item "Replace in tagged files" tags-query-replace - :help "Interactively replace a regexp in all tagged files")) -(define-key menu-bar-replace-menu [separator-replace-tags] - '(menu-item "--")) -;; @r{@dots{}} -@end smallexample - -@noindent -Note the symbols which the bindings are ``made for''; these appear -inside square brackets, in the key sequence being defined. In some -cases, this symbol is the same as the command name; sometimes it is -different. These symbols are treated as ``function keys'', but they are -not real function keys on the keyboard. They do not affect the -functioning of the menu itself, but they are ``echoed'' in the echo area -when the user selects from the menu, and they appear in the output of -@code{where-is} and @code{apropos}. - - The menu in this example is intended for use with the mouse. If a -menu is intended for use with the keyboard, that is, if it is bound to -a key sequence ending with a keyboard event, then the menu items -should be bound to characters or ``real'' function keys, that can be -typed with the keyboard. - - The binding whose definition is @code{("--")} is a separator line. -Like a real menu item, the separator has a key symbol, in this case -@code{separator-replace-tags}. If one menu has two separators, they -must have two different key symbols. - - Here is how we make this menu appear as an item in the parent menu: - -@example -(define-key menu-bar-edit-menu [replace] - (list 'menu-item "Replace" menu-bar-replace-menu)) -@end example - -@noindent -Note that this incorporates the submenu keymap, which is the value of -the variable @code{menu-bar-replace-menu}, rather than the symbol -@code{menu-bar-replace-menu} itself. Using that symbol in the parent -menu item would be meaningless because @code{menu-bar-replace-menu} is -not a command. - - If you wanted to attach the same replace menu to a mouse click, you -can do it this way: - -@example -(define-key global-map [C-S-down-mouse-1] - menu-bar-replace-menu) -@end example - -@node Menu Bar -@subsection The Menu Bar -@cindex menu bar - - Emacs usually shows a @dfn{menu bar} at the top of each frame. -@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu bar items are -subcommands of the fake ``function key'' @code{menu-bar}, as defined -in the active keymaps. - - To add an item to the menu bar, invent a fake ``function key'' of your -own (let's call it @var{key}), and make a binding for the key sequence -@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap, -so that pressing a button on the menu bar item leads to another menu. - - When more than one active keymap defines the same ``function key'' -for the menu bar, the item appears just once. If the user clicks on -that menu bar item, it brings up a single, combined menu containing -all the subcommands of that item---the global subcommands, the local -subcommands, and the minor mode subcommands. - - The variable @code{overriding-local-map} is normally ignored when -determining the menu bar contents. That is, the menu bar is computed -from the keymaps that would be active if @code{overriding-local-map} -were @code{nil}. @xref{Active Keymaps}. - - Here's an example of setting up a menu bar item: - -@example -@group -;; @r{Make a menu keymap (with a prompt string)} -;; @r{and make it the menu bar item's definition.} -(define-key global-map [menu-bar words] - (cons "Words" (make-sparse-keymap "Words"))) -@end group - -@group -;; @r{Define specific subcommands in this menu.} -(define-key global-map - [menu-bar words forward] - '("Forward word" . forward-word)) -@end group -@group -(define-key global-map - [menu-bar words backward] - '("Backward word" . backward-word)) -@end group -@end example - - A local keymap can cancel a menu bar item made by the global keymap by -rebinding the same fake function key with @code{undefined} as the -binding. For example, this is how Dired suppresses the @samp{Edit} menu -bar item: - -@example -(define-key dired-mode-map [menu-bar edit] 'undefined) -@end example - -@noindent -Here, @code{edit} is the fake function key used by the global map for -the @samp{Edit} menu bar item. The main reason to suppress a global -menu bar item is to regain space for mode-specific items. - -@defvar menu-bar-final-items -Normally the menu bar shows global items followed by items defined by the -local maps. - -This variable holds a list of fake function keys for items to display at -the end of the menu bar rather than in normal sequence. The default -value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears -at the end of the menu bar, following local menu items. -@end defvar - -@defvar menu-bar-update-hook -This normal hook is run by redisplay to update the menu bar contents, -before redisplaying the menu bar. You can use it to update menus -whose contents should vary. Since this hook is run frequently, we -advise you to ensure that the functions it calls do not take much time -in the usual case. -@end defvar - -Next to every menu bar item, Emacs displays a key binding that runs -the same command (if such a key binding exists). This serves as a -convenient hint for users who do not know the key binding. If a -command has multiple bindings, Emacs normally displays the first one -it finds. You can specify one particular key binding by assigning an -@code{:advertised-binding} symbol property to the command. @xref{Keys -in Documentation}. - -@node Tool Bar -@subsection Tool bars -@cindex tool bar - - A @dfn{tool bar} is a row of clickable icons at the top of a frame, -just below the menu bar. @xref{Tool Bars,,,emacs, The GNU Emacs -Manual}. Emacs normally shows a tool bar on graphical displays. - - On each frame, the frame parameter @code{tool-bar-lines} controls -how many lines' worth of height to reserve for the tool bar. A zero -value suppresses the tool bar. If the value is nonzero, and -@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands -and contracts automatically as needed to hold the specified contents. -If the value is @code{grow-only}, the tool bar expands automatically, -but does not contract automatically. - - The tool bar contents are controlled by a menu keymap attached to a -fake ``function key'' called @code{tool-bar} (much like the way the menu -bar is controlled). So you define a tool bar item using -@code{define-key}, like this: - -@example -(define-key global-map [tool-bar @var{key}] @var{item}) -@end example - -@noindent -where @var{key} is a fake ``function key'' to distinguish this item from -other items, and @var{item} is a menu item key binding (@pxref{Extended -Menu Items}), which says how to display this item and how it behaves. - - The usual menu keymap item properties, @code{:visible}, -@code{:enable}, @code{:button}, and @code{:filter}, are useful in -tool bar bindings and have their normal meanings. The @var{real-binding} -in the item must be a command, not a keymap; in other words, it does not -work to define a tool bar icon as a prefix key. - - The @code{:help} property specifies a ``help-echo'' string to display -while the mouse is on that item. This is displayed in the same way as -@code{help-echo} text properties (@pxref{Help display}). - - In addition, you should use the @code{:image} property; -this is how you specify the image to display in the tool bar: - -@table @code -@item :image @var{image} -@var{images} is either a single image specification or a vector of four -image specifications. If you use a vector of four, -one of them is used, depending on circumstances: - -@table @asis -@item item 0 -Used when the item is enabled and selected. -@item item 1 -Used when the item is enabled and deselected. -@item item 2 -Used when the item is disabled and selected. -@item item 3 -Used when the item is disabled and deselected. -@end table -@end table - -The GTK+ and NS versions of Emacs ignores items 1 to 3, because disabled and/or -deselected images are autocomputed from item 0. - -If @var{image} is a single image specification, Emacs draws the tool bar -button in disabled state by applying an edge-detection algorithm to the -image. - -The @code{:rtl} property specifies an alternative image to use for -right-to-left languages. Only the GTK+ version of Emacs supports this -at present. - -Like the menu bar, the tool bar can display separators (@pxref{Menu -Separators}). Tool bar separators are vertical rather than -horizontal, though, and only a single style is supported. They are -represented in the tool bar keymap by @code{(menu-item "--")} entries; -properties like @code{:visible} are not supported for tool bar -separators. Separators are rendered natively in GTK+ and Nextstep -tool bars; in the other cases, they are rendered using an image of a -vertical line. - -The default tool bar is defined so that items specific to editing do not -appear for major modes whose command symbol has a @code{mode-class} -property of @code{special} (@pxref{Major Mode Conventions}). Major -modes may add items to the global bar by binding @code{[tool-bar -@var{foo}]} in their local map. It makes sense for some major modes to -replace the default tool bar items completely, since not many can be -accommodated conveniently, and the default bindings make this easy by -using an indirection through @code{tool-bar-map}. - -@defvar tool-bar-map -By default, the global map binds @code{[tool-bar]} as follows: - -@example -(global-set-key [tool-bar] - `(menu-item ,(purecopy "tool bar") ignore - :filter tool-bar-make-keymap)) -@end example - -@noindent -The function @code{tool-bar-make-keymap}, in turn, derives the actual -tool bar map dynamically from the value of the variable -@code{tool-bar-map}. Hence, you should normally adjust the default -(global) tool bar by changing that map. Some major modes, such as -Info mode, completely replace the global tool bar by making -@code{tool-bar-map} buffer-local and setting it to a different keymap. -@end defvar - -There are two convenience functions for defining tool bar items, as -follows. - -@defun tool-bar-add-item icon def key &rest props -This function adds an item to the tool bar by modifying -@code{tool-bar-map}. The image to use is defined by @var{icon}, which -is the base name of an XPM, XBM or PBM image file to be located by -@code{find-image}. Given a value @samp{"exit"}, say, @file{exit.xpm}, -@file{exit.pbm} and @file{exit.xbm} would be searched for in that order -on a color display. On a monochrome display, the search order is -@samp{.pbm}, @samp{.xbm} and @samp{.xpm}. The binding to use is the -command @var{def}, and @var{key} is the fake function key symbol in the -prefix keymap. The remaining arguments @var{props} are additional -property list elements to add to the menu item specification. - -To define items in some local map, bind @code{tool-bar-map} with -@code{let} around calls of this function: -@example -(defvar foo-tool-bar-map - (let ((tool-bar-map (make-sparse-keymap))) - (tool-bar-add-item @dots{}) - @dots{} - tool-bar-map)) -@end example -@end defun - -@defun tool-bar-add-item-from-menu command icon &optional map &rest props -This function is a convenience for defining tool bar items which are -consistent with existing menu bar bindings. The binding of -@var{command} is looked up in the menu bar in @var{map} (default -@code{global-map}) and modified to add an image specification for -@var{icon}, which is found in the same way as by -@code{tool-bar-add-item}. The resulting binding is then placed in -@code{tool-bar-map}, so use this function only for global tool bar -items. - -@var{map} must contain an appropriate keymap bound to -@code{[menu-bar]}. The remaining arguments @var{props} are additional -property list elements to add to the menu item specification. -@end defun - -@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props -This function is used for making non-global tool bar items. Use it -like @code{tool-bar-add-item-from-menu} except that @var{in-map} -specifies the local map to make the definition in. The argument -@var{from-map} is like the @var{map} argument of -@code{tool-bar-add-item-from-menu}. -@end defun - -@defvar auto-resize-tool-bars -If this variable is non-@code{nil}, the tool bar automatically resizes to -show all defined tool bar items---but not larger than a quarter of the -frame's height. - -If the value is @code{grow-only}, the tool bar expands automatically, -but does not contract automatically. To contract the tool bar, the -user has to redraw the frame by entering @kbd{C-l}. - -If Emacs is built with GTK or Nextstep, the tool bar can only show one -line, so this variable has no effect. -@end defvar - -@defvar auto-raise-tool-bar-buttons -If this variable is non-@code{nil}, tool bar items display -in raised form when the mouse moves over them. -@end defvar - -@defvar tool-bar-button-margin -This variable specifies an extra margin to add around tool bar items. -The value is an integer, a number of pixels. The default is 4. -@end defvar - -@defvar tool-bar-button-relief -This variable specifies the shadow width for tool bar items. -The value is an integer, a number of pixels. The default is 1. -@end defvar - -@defvar tool-bar-border -This variable specifies the height of the border drawn below the tool -bar area. An integer specifies height as a number of pixels. -If the value is one of @code{internal-border-width} (the default) or -@code{border-width}, the tool bar border height corresponds to the -corresponding frame parameter. -@end defvar - - You can define a special meaning for clicking on a tool bar item with -the shift, control, meta, etc., modifiers. You do this by setting up -additional items that relate to the original item through the fake -function keys. Specifically, the additional items should use the -modified versions of the same fake function key used to name the -original item. - - Thus, if the original item was defined this way, - -@example -(define-key global-map [tool-bar shell] - '(menu-item "Shell" shell - :image (image :type xpm :file "shell.xpm"))) -@end example - -@noindent -then here is how you can define clicking on the same tool bar image with -the shift modifier: - -@example -(define-key global-map [tool-bar S-shell] 'some-command) -@end example - -@xref{Function Keys}, for more information about how to add modifiers to -function keys. - -@node Modifying Menus -@subsection Modifying Menus - - When you insert a new item in an existing menu, you probably want to -put it in a particular place among the menu's existing items. If you -use @code{define-key} to add the item, it normally goes at the front of -the menu. To put it elsewhere in the menu, use @code{define-key-after}: - -@defun define-key-after map key binding &optional after -Define a binding in @var{map} for @var{key}, with value @var{binding}, -just like @code{define-key}, but position the binding in @var{map} after -the binding for the event @var{after}. The argument @var{key} should be -of length one---a vector or string with just one element. But -@var{after} should be a single event type---a symbol or a character, not -a sequence. The new binding goes after the binding for @var{after}. If -@var{after} is @code{t} or is omitted, then the new binding goes last, at -the end of the keymap. However, new bindings are added before any -inherited keymap. - -Here is an example: - -@example -(define-key-after my-menu [drink] - '("Drink" . drink-command) 'eat) -@end example - -@noindent -makes a binding for the fake function key @key{DRINK} and puts it -right after the binding for @key{EAT}. - -Here is how to insert an item called @samp{Work} in the @samp{Signals} -menu of Shell mode, after the item @code{break}: - -@example -(define-key-after - (lookup-key shell-mode-map [menu-bar signals]) - [work] '("Work" . work-command) 'break) -@end example -@end defun - -@node Easy Menu -@subsection Easy Menu - - The following macro provides a convenient way to define pop-up menus -and/or menu bar menus. - -@defmac easy-menu-define symbol maps doc menu -This macro defines a pop-up menu and/or menu bar submenu, whose -contents are given by @var{menu}. - -If @var{symbol} is non-@code{nil}, it should be a symbol; then this -macro defines @var{symbol} as a function for popping up the menu -(@pxref{Pop-Up Menus}), with @var{doc} as its documentation string. -@var{symbol} should not be quoted. - -Regardless of the value of @var{symbol}, if @var{maps} is a keymap, -the menu is added to that keymap, as a top-level menu for the menu bar -(@pxref{Menu Bar}). It can also be a list of keymaps, in which case -the menu is added separately to each of those keymaps. - -The first element of @var{menu} must be a string, which serves as the -menu label. It may be followed by any number of the following -keyword-argument pairs: - -@table @code -@item :filter @var{function} -@var{function} must be a function which, if called with one -argument---the list of the other menu items---returns the actual items -to be displayed in the menu. - -@item :visible @var{include} -@var{include} is an expression; if it evaluates to @code{nil}, the -menu is made invisible. @code{:included} is an alias for -@code{:visible}. - -@item :active @var{enable} -@var{enable} is an expression; if it evaluates to @code{nil}, the menu -is not selectable. @code{:enable} is an alias for @code{:active}. -@end table - -The remaining elements in @var{menu} are menu items. - -A menu item can be a vector of three elements, @code{[@var{name} -@var{callback} @var{enable}]}. @var{name} is the menu item name (a -string). @var{callback} is a command to run, or an expression to -evaluate, when the item is chosen. @var{enable} is an expression; if -it evaluates to @code{nil}, the item is disabled for selection. - -Alternatively, a menu item may have the form: - -@smallexample - [ @var{name} @var{callback} [ @var{keyword} @var{arg} ]... ] -@end smallexample - -@noindent -where @var{name} and @var{callback} have the same meanings as above, -and each optional @var{keyword} and @var{arg} pair should be one of -the following: - -@table @code -@item :keys @var{keys} -@var{keys} is a keyboard equivalent to the menu item (a string). This -is normally not needed, as keyboard equivalents are computed -automatically. @var{keys} is expanded with -@code{substitute-command-keys} before it is displayed (@pxref{Keys in -Documentation}). - -@item :key-sequence @var{keys} -@var{keys} is a hint for speeding up Emacs's first display of the -menu. It should be @code{nil} if you know that the menu item has no keyboard -equivalent; otherwise it should be a string or vector specifying a -keyboard equivalent for the menu item. - -@item :active @var{enable} -@var{enable} is an expression; if it evaluates to @code{nil}, the item -is make unselectable.. @code{:enable} is an alias for @code{:active}. - -@item :visible @var{include} -@var{include} is an expression; if it evaluates to @code{nil}, the -item is made invisible. @code{:included} is an alias for -@code{:visible}. - -@item :label @var{form} -@var{form} is an expression that is evaluated to obtain a value which -serves as the menu item's label (the default is @var{name}). - -@item :suffix @var{form} -@var{form} is an expression that is dynamically evaluated and whose -value is concatenated with the menu entry's label. - -@item :style @var{style} -@var{style} is a symbol describing the type of menu item; it should be -@code{toggle} (a checkbox), or @code{radio} (a radio button), or -anything else (meaning an ordinary menu item). - -@item :selected @var{selected} -@var{selected} is an expression; the checkbox or radio button is -selected whenever the expression's value is non-@code{nil}. - -@item :help @var{help} -@var{help} is a string describing the menu item. -@end table - -Alternatively, a menu item can be a string. Then that string appears -in the menu as unselectable text. A string consisting of dashes is -displayed as a separator (@pxref{Menu Separators}). - -Alternatively, a menu item can be a list with the same format as -@var{menu}. This is a submenu. -@end defmac - -Here is an example of using @code{easy-menu-define} to define a menu -similar to the one defined in the example in @ref{Menu Bar}: - -@example -(easy-menu-define words-menu global-map - "Menu for word navigation commands." - '("Words" - ["Forward word" forward-word] - ["Backward word" backward-word])) -@end example diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi deleted file mode 100644 index 98c778ce7b9..00000000000 --- a/doc/lispref/lay-flat.texi +++ /dev/null @@ -1,44 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@comment %**start of header -@setfilename inner-covers.info -@settitle Inner Covers -@smallbook -@documentencoding UTF-8 -@comment %**end of header - -@headings off - -@w{ } -@sp 4 -@tex -\center {\secfonts \rm Lay-Flat Binding} -@end tex -@sp 2 - -We have bound this manual using a new @dfn{lay-flat} binding -technology. This type of binding allows you to open a soft cover book -so that it ``lays flat'' on a table without creasing the binding. - -In order to make the book lay flat properly, you need to ``crack'' the -binding. To do this, divide the book into two sections and bend it so -that the front and back covers meet. Do not worry; the pages are -sewn and glued to the binding, and will not fall out easily. -The outer cardboard binding itself is designed so that it will not -break or crease as an ordinary paperback binding will. Bend the book -several times in this manner, dividing it in a different place each -time and pressing the pages flat and open. With use, the binding will -become flexible and the pages will lay flat without needing to be -pushed or held down. - -@page - - -@tex -\center {\secfonts \rm Notes} -@end tex - -@bye diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi deleted file mode 100644 index cde7d9ce44c..00000000000 --- a/doc/lispref/lists.texi +++ /dev/null @@ -1,1956 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Lists -@chapter Lists -@cindex lists -@cindex element (of list) - - A @dfn{list} represents a sequence of zero or more elements (which may -be any Lisp objects). The important difference between lists and -vectors is that two or more lists can share part of their structure; in -addition, you can insert or delete elements in a list without copying -the whole list. - -@menu -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. -* Property Lists:: A list of paired elements. -@end menu - -@node Cons Cells -@section Lists and Cons Cells -@cindex lists and cons cells - - Lists in Lisp are not a primitive data type; they are built up from -@dfn{cons cells} (@pxref{Cons Cell Type}). A cons cell is a data -object that represents an ordered pair. That is, it has two slots, -and each slot @dfn{holds}, or @dfn{refers to}, some Lisp object. One -slot is known as the @sc{car}, and the other is known as the @sc{cdr}. -(These names are traditional; see @ref{Cons Cell Type}.) @sc{cdr} is -pronounced ``could-er''. - - We say that ``the @sc{car} of this cons cell is'' whatever object -its @sc{car} slot currently holds, and likewise for the @sc{cdr}. - - A list is a series of cons cells ``chained together'', so that each -cell refers to the next one. There is one cons cell for each element -of the list. By convention, the @sc{car}s of the cons cells hold the -elements of the list, and the @sc{cdr}s are used to chain the list -(this asymmetry between @sc{car} and @sc{cdr} is entirely a matter of -convention; at the level of cons cells, the @sc{car} and @sc{cdr} -slots have similar properties). Hence, the @sc{cdr} slot of each cons -cell in a list refers to the following cons cell. - -@cindex true list - Also by convention, the @sc{cdr} of the last cons cell in a list is -@code{nil}. We call such a @code{nil}-terminated structure a -@dfn{true list}. In Emacs Lisp, the symbol @code{nil} is both a -symbol and a list with no elements. For convenience, the symbol -@code{nil} is considered to have @code{nil} as its @sc{cdr} (and also -as its @sc{car}). - - Hence, the @sc{cdr} of a true list is always a true list. The -@sc{cdr} of a nonempty true list is a true list containing all the -elements except the first. - -@cindex dotted list -@cindex circular list - If the @sc{cdr} of a list's last cons cell is some value other than -@code{nil}, we call the structure a @dfn{dotted list}, since its -printed representation would use dotted pair notation (@pxref{Dotted -Pair Notation}). There is one other possibility: some cons cell's -@sc{cdr} could point to one of the previous cons cells in the list. -We call that structure a @dfn{circular list}. - - For some purposes, it does not matter whether a list is true, -circular or dotted. If a program doesn't look far enough down the -list to see the @sc{cdr} of the final cons cell, it won't care. -However, some functions that operate on lists demand true lists and -signal errors if given a dotted list. Most functions that try to find -the end of a list enter infinite loops if given a circular list. - -@cindex list structure - Because most cons cells are used as part of lists, we refer to any -structure made out of cons cells as a @dfn{list structure}. - -@node List-related Predicates -@section Predicates on Lists - - The following predicates test whether a Lisp object is an atom, -whether it is a cons cell or is a list, or whether it is the -distinguished object @code{nil}. (Many of these predicates can be -defined in terms of the others, but they are used so often that it is -worth having them.) - -@defun consp object -This function returns @code{t} if @var{object} is a cons cell, @code{nil} -otherwise. @code{nil} is not a cons cell, although it @emph{is} a list. -@end defun - -@defun atom object -This function returns @code{t} if @var{object} is an atom, @code{nil} -otherwise. All objects except cons cells are atoms. The symbol -@code{nil} is an atom and is also a list; it is the only Lisp object -that is both. - -@example -(atom @var{object}) @equiv{} (not (consp @var{object})) -@end example -@end defun - -@defun listp object -This function returns @code{t} if @var{object} is a cons cell or -@code{nil}. Otherwise, it returns @code{nil}. - -@example -@group -(listp '(1)) - @result{} t -@end group -@group -(listp '()) - @result{} t -@end group -@end example -@end defun - -@defun nlistp object -This function is the opposite of @code{listp}: it returns @code{t} if -@var{object} is not a list. Otherwise, it returns @code{nil}. - -@example -(listp @var{object}) @equiv{} (not (nlistp @var{object})) -@end example -@end defun - -@defun null object -This function returns @code{t} if @var{object} is @code{nil}, and -returns @code{nil} otherwise. This function is identical to @code{not}, -but as a matter of clarity we use @code{null} when @var{object} is -considered a list and @code{not} when it is considered a truth value -(see @code{not} in @ref{Combining Conditions}). - -@example -@group -(null '(1)) - @result{} nil -@end group -@group -(null '()) - @result{} t -@end group -@end example -@end defun - - -@node List Elements -@section Accessing Elements of Lists -@cindex list elements - -@defun car cons-cell -This function returns the value referred to by the first slot of the -cons cell @var{cons-cell}. In other words, it returns the @sc{car} of -@var{cons-cell}. - -As a special case, if @var{cons-cell} is @code{nil}, this function -returns @code{nil}. Therefore, any list is a valid argument. An -error is signaled if the argument is not a cons cell or @code{nil}. - -@example -@group -(car '(a b c)) - @result{} a -@end group -@group -(car '()) - @result{} nil -@end group -@end example -@end defun - -@defun cdr cons-cell -This function returns the value referred to by the second slot of the -cons cell @var{cons-cell}. In other words, it returns the @sc{cdr} of -@var{cons-cell}. - -As a special case, if @var{cons-cell} is @code{nil}, this function -returns @code{nil}; therefore, any list is a valid argument. An error -is signaled if the argument is not a cons cell or @code{nil}. - -@example -@group -(cdr '(a b c)) - @result{} (b c) -@end group -@group -(cdr '()) - @result{} nil -@end group -@end example -@end defun - -@defun car-safe object -This function lets you take the @sc{car} of a cons cell while avoiding -errors for other data types. It returns the @sc{car} of @var{object} if -@var{object} is a cons cell, @code{nil} otherwise. This is in contrast -to @code{car}, which signals an error if @var{object} is not a list. - -@example -@group -(car-safe @var{object}) -@equiv{} -(let ((x @var{object})) - (if (consp x) - (car x) - nil)) -@end group -@end example -@end defun - -@defun cdr-safe object -This function lets you take the @sc{cdr} of a cons cell while -avoiding errors for other data types. It returns the @sc{cdr} of -@var{object} if @var{object} is a cons cell, @code{nil} otherwise. -This is in contrast to @code{cdr}, which signals an error if -@var{object} is not a list. - -@example -@group -(cdr-safe @var{object}) -@equiv{} -(let ((x @var{object})) - (if (consp x) - (cdr x) - nil)) -@end group -@end example -@end defun - -@defmac pop listname -This macro provides a convenient way to examine the @sc{car} of a -list, and take it off the list, all at once. It operates on the list -stored in @var{listname}. It removes the first element from the list, -saves the @sc{cdr} into @var{listname}, then returns the removed -element. - -In the simplest case, @var{listname} is an unquoted symbol naming a -list; in that case, this macro is equivalent to @w{@code{(prog1 -(car listname) (setq listname (cdr listname)))}}. - -@example -x - @result{} (a b c) -(pop x) - @result{} a -x - @result{} (b c) -@end example - -More generally, @var{listname} can be a generalized variable. In that -case, this macro saves into @var{listname} using @code{setf}. -@xref{Generalized Variables}. - -For the @code{push} macro, which adds an element to a list, -@xref{List Variables}. -@end defmac - -@defun nth n list -@anchor{Definition of nth} -This function returns the @var{n}th element of @var{list}. Elements -are numbered starting with zero, so the @sc{car} of @var{list} is -element number zero. If the length of @var{list} is @var{n} or less, -the value is @code{nil}. - -@c Behavior for -ve n undefined since 2013/08; see bug#15059. -@ignore -If @var{n} is negative, @code{nth} returns the first element of @var{list}. -@end ignore - -@example -@group -(nth 2 '(1 2 3 4)) - @result{} 3 -@end group -@group -(nth 10 '(1 2 3 4)) - @result{} nil - -(nth n x) @equiv{} (car (nthcdr n x)) -@end group -@end example - -The function @code{elt} is similar, but applies to any kind of sequence. -For historical reasons, it takes its arguments in the opposite order. -@xref{Sequence Functions}. -@end defun - -@defun nthcdr n list -This function returns the @var{n}th @sc{cdr} of @var{list}. In other -words, it skips past the first @var{n} links of @var{list} and returns -what follows. - -@c "or negative" removed 2013/08; see bug#15059. -If @var{n} is zero, @code{nthcdr} returns all of -@var{list}. If the length of @var{list} is @var{n} or less, -@code{nthcdr} returns @code{nil}. - -@example -@group -(nthcdr 1 '(1 2 3 4)) - @result{} (2 3 4) -@end group -@group -(nthcdr 10 '(1 2 3 4)) - @result{} nil -@end group -@group -(nthcdr 0 '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@end example -@end defun - -@defun last list &optional n -This function returns the last link of @var{list}. The @code{car} of -this link is the list's last element. If @var{list} is null, -@code{nil} is returned. If @var{n} is non-@code{nil}, the -@var{n}th-to-last link is returned instead, or the whole of @var{list} -if @var{n} is bigger than @var{list}'s length. -@end defun - -@defun safe-length list -@anchor{Definition of safe-length} -This function returns the length of @var{list}, with no risk of either -an error or an infinite loop. It generally returns the number of -distinct cons cells in the list. However, for circular lists, -the value is just an upper bound; it is often too large. - -If @var{list} is not @code{nil} or a cons cell, @code{safe-length} -returns 0. -@end defun - - The most common way to compute the length of a list, when you are not -worried that it may be circular, is with @code{length}. @xref{Sequence -Functions}. - -@defun caar cons-cell -This is the same as @code{(car (car @var{cons-cell}))}. -@end defun - -@defun cadr cons-cell -This is the same as @code{(car (cdr @var{cons-cell}))} -or @code{(nth 1 @var{cons-cell})}. -@end defun - -@defun cdar cons-cell -This is the same as @code{(cdr (car @var{cons-cell}))}. -@end defun - -@defun cddr cons-cell -This is the same as @code{(cdr (cdr @var{cons-cell}))} -or @code{(nthcdr 2 @var{cons-cell})}. -@end defun - -@defun butlast x &optional n -This function returns the list @var{x} with the last element, -or the last @var{n} elements, removed. If @var{n} is greater -than zero it makes a copy of the list so as not to damage the -original list. In general, @code{(append (butlast @var{x} @var{n}) -(last @var{x} @var{n}))} will return a list equal to @var{x}. -@end defun - -@defun nbutlast x &optional n -This is a version of @code{butlast} that works by destructively -modifying the @code{cdr} of the appropriate element, rather than -making a copy of the list. -@end defun - -@node Building Lists -@section Building Cons Cells and Lists -@cindex cons cells -@cindex building lists - - Many functions build lists, as lists reside at the very heart of Lisp. -@code{cons} is the fundamental list-building function; however, it is -interesting to note that @code{list} is used more times in the source -code for Emacs than @code{cons}. - -@defun cons object1 object2 -This function is the most basic function for building new list -structure. It creates a new cons cell, making @var{object1} the -@sc{car}, and @var{object2} the @sc{cdr}. It then returns the new -cons cell. The arguments @var{object1} and @var{object2} may be any -Lisp objects, but most often @var{object2} is a list. - -@example -@group -(cons 1 '(2)) - @result{} (1 2) -@end group -@group -(cons 1 '()) - @result{} (1) -@end group -@group -(cons 1 2) - @result{} (1 . 2) -@end group -@end example - -@cindex consing -@code{cons} is often used to add a single element to the front of a -list. This is called @dfn{consing the element onto the list}. -@footnote{There is no strictly equivalent way to add an element to -the end of a list. You can use @code{(append @var{listname} (list -@var{newelt}))}, which creates a whole new list by copying @var{listname} -and adding @var{newelt} to its end. Or you can use @code{(nconc -@var{listname} (list @var{newelt}))}, which modifies @var{listname} -by following all the @sc{cdr}s and then replacing the terminating -@code{nil}. Compare this to adding an element to the beginning of a -list with @code{cons}, which neither copies nor modifies the list.} -For example: - -@example -(setq list (cons newelt list)) -@end example - -Note that there is no conflict between the variable named @code{list} -used in this example and the function named @code{list} described below; -any symbol can serve both purposes. -@end defun - -@defun list &rest objects -This function creates a list with @var{objects} as its elements. The -resulting list is always @code{nil}-terminated. If no @var{objects} -are given, the empty list is returned. - -@example -@group -(list 1 2 3 4 5) - @result{} (1 2 3 4 5) -@end group -@group -(list 1 2 '(3 4 5) 'foo) - @result{} (1 2 (3 4 5) foo) -@end group -@group -(list) - @result{} nil -@end group -@end example -@end defun - -@defun make-list length object -This function creates a list of @var{length} elements, in which each -element is @var{object}. Compare @code{make-list} with -@code{make-string} (@pxref{Creating Strings}). - -@example -@group -(make-list 3 'pigs) - @result{} (pigs pigs pigs) -@end group -@group -(make-list 0 'pigs) - @result{} nil -@end group -@group -(setq l (make-list 3 '(a b))) - @result{} ((a b) (a b) (a b)) -(eq (car l) (cadr l)) - @result{} t -@end group -@end example -@end defun - -@defun append &rest sequences -@cindex copying lists -This function returns a list containing all the elements of -@var{sequences}. The @var{sequences} may be lists, vectors, -bool-vectors, or strings, but the last one should usually be a list. -All arguments except the last one are copied, so none of the arguments -is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join -lists with no copying.) - -More generally, the final argument to @code{append} may be any Lisp -object. The final argument is not copied or converted; it becomes the -@sc{cdr} of the last cons cell in the new list. If the final argument -is itself a list, then its elements become in effect elements of the -result list. If the final element is not a list, the result is a -dotted list since its final @sc{cdr} is not @code{nil} as required -in a true list. -@end defun - - Here is an example of using @code{append}: - -@example -@group -(setq trees '(pine oak)) - @result{} (pine oak) -(setq more-trees (append '(maple birch) trees)) - @result{} (maple birch pine oak) -@end group - -@group -trees - @result{} (pine oak) -more-trees - @result{} (maple birch pine oak) -@end group -@group -(eq trees (cdr (cdr more-trees))) - @result{} t -@end group -@end example - - You can see how @code{append} works by looking at a box diagram. The -variable @code{trees} is set to the list @code{(pine oak)} and then the -variable @code{more-trees} is set to the list @code{(maple birch pine -oak)}. However, the variable @code{trees} continues to refer to the -original list: - -@smallexample -@group -more-trees trees -| | -| --- --- --- --- -> --- --- --- --- - --> | | |--> | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- --- --- - | | | | - | | | | - --> maple -->birch --> pine --> oak -@end group -@end smallexample - - An empty sequence contributes nothing to the value returned by -@code{append}. As a consequence of this, a final @code{nil} argument -forces a copy of the previous argument: - -@example -@group -trees - @result{} (pine oak) -@end group -@group -(setq wood (append trees nil)) - @result{} (pine oak) -@end group -@group -wood - @result{} (pine oak) -@end group -@group -(eq wood trees) - @result{} nil -@end group -@end example - -@noindent -This once was the usual way to copy a list, before the function -@code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}. - - Here we show the use of vectors and strings as arguments to @code{append}: - -@example -@group -(append [a b] "cd" nil) - @result{} (a b 99 100) -@end group -@end example - - With the help of @code{apply} (@pxref{Calling Functions}), we can append -all the lists in a list of lists: - -@example -@group -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end group -@end example - - If no @var{sequences} are given, @code{nil} is returned: - -@example -@group -(append) - @result{} nil -@end group -@end example - - Here are some examples where the final argument is not a list: - -@example -(append '(x y) 'z) - @result{} (x y . z) -(append '(x y) [z]) - @result{} (x y . [z]) -@end example - -@noindent -The second example shows that when the final argument is a sequence but -not a list, the sequence's elements do not become elements of the -resulting list. Instead, the sequence becomes the final @sc{cdr}, like -any other non-list final argument. - -@defun reverse list -This function creates a new list whose elements are the elements of -@var{list}, but in reverse order. The original argument @var{list} is -@emph{not} altered. - -@example -@group -(setq x '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@group -(reverse x) - @result{} (4 3 2 1) -x - @result{} (1 2 3 4) -@end group -@end example -@end defun - -@defun copy-tree tree &optional vecp -This function returns a copy of the tree @code{tree}. If @var{tree} is a -cons cell, this makes a new cons cell with the same @sc{car} and -@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the -same way. - -Normally, when @var{tree} is anything other than a cons cell, -@code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is -non-@code{nil}, it copies vectors too (and operates recursively on -their elements). -@end defun - -@defun number-sequence from &optional to separation -This returns a list of numbers starting with @var{from} and -incrementing by @var{separation}, and ending at or just before -@var{to}. @var{separation} can be positive or negative and defaults -to 1. If @var{to} is @code{nil} or numerically equal to @var{from}, -the value is the one-element list @code{(@var{from})}. If @var{to} is -less than @var{from} with a positive @var{separation}, or greater than -@var{from} with a negative @var{separation}, the value is @code{nil} -because those arguments specify an empty sequence. - -If @var{separation} is 0 and @var{to} is neither @code{nil} nor -numerically equal to @var{from}, @code{number-sequence} signals an -error, since those arguments specify an infinite sequence. - -All arguments are numbers. -Floating-point arguments can be tricky, because floating-point -arithmetic is inexact. For instance, depending on the machine, it may -quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns -the one element list @code{(0.4)}, whereas -@code{(number-sequence 0.4 0.8 0.2)} returns a list with three -elements. The @var{n}th element of the list is computed by the exact -formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if -one wants to make sure that @var{to} is included in the list, one can -pass an expression of this exact type for @var{to}. Alternatively, -one can replace @var{to} with a slightly larger value (or a slightly -more negative value if @var{separation} is negative). - -Some examples: - -@example -(number-sequence 4 9) - @result{} (4 5 6 7 8 9) -(number-sequence 9 4 -1) - @result{} (9 8 7 6 5 4) -(number-sequence 9 4 -2) - @result{} (9 7 5) -(number-sequence 8) - @result{} (8) -(number-sequence 8 5) - @result{} nil -(number-sequence 5 8 -1) - @result{} nil -(number-sequence 1.5 6 2) - @result{} (1.5 3.5 5.5) -@end example -@end defun - -@node List Variables -@section Modifying List Variables - - These functions, and one macro, provide convenient ways -to modify a list which is stored in a variable. - -@defmac push element listname -This macro creates a new list whose @sc{car} is @var{element} and -whose @sc{cdr} is the list specified by @var{listname}, and saves that -list in @var{listname}. In the simplest case, @var{listname} is an -unquoted symbol naming a list, and this macro is equivalent -to @w{@code{(setq @var{listname} (cons @var{element} @var{listname}))}}. - -@example -(setq l '(a b)) - @result{} (a b) -(push 'c l) - @result{} (c a b) -l - @result{} (c a b) -@end example - -More generally, @code{listname} can be a generalized variable. In -that case, this macro does the equivalent of @w{@code{(setf -@var{listname} (cons @var{element} @var{listname}))}}. -@xref{Generalized Variables}. - -For the @code{pop} macro, which removes the first element from a list, -@xref{List Elements}. -@end defmac - - Two functions modify lists that are the values of variables. - -@defun add-to-list symbol element &optional append compare-fn -This function sets the variable @var{symbol} by consing @var{element} -onto the old value, if @var{element} is not already a member of that -value. It returns the resulting list, whether updated or not. The -value of @var{symbol} had better be a list already before the call. -@code{add-to-list} uses @var{compare-fn} to compare @var{element} -against existing list members; if @var{compare-fn} is @code{nil}, it -uses @code{equal}. - -Normally, if @var{element} is added, it is added to the front of -@var{symbol}, but if the optional argument @var{append} is -non-@code{nil}, it is added at the end. - -The argument @var{symbol} is not implicitly quoted; @code{add-to-list} -is an ordinary function, like @code{set} and unlike @code{setq}. Quote -the argument yourself if that is what you want. -@end defun - -Here's a scenario showing how to use @code{add-to-list}: - -@example -(setq foo '(a b)) - @result{} (a b) - -(add-to-list 'foo 'c) ;; @r{Add @code{c}.} - @result{} (c a b) - -(add-to-list 'foo 'b) ;; @r{No effect.} - @result{} (c a b) - -foo ;; @r{@code{foo} was changed.} - @result{} (c a b) -@end example - - An equivalent expression for @code{(add-to-list '@var{var} -@var{value})} is this: - -@example -(or (member @var{value} @var{var}) - (setq @var{var} (cons @var{value} @var{var}))) -@end example - -@defun add-to-ordered-list symbol element &optional order -This function sets the variable @var{symbol} by inserting -@var{element} into the old value, which must be a list, at the -position specified by @var{order}. If @var{element} is already a -member of the list, its position in the list is adjusted according -to @var{order}. Membership is tested using @code{eq}. -This function returns the resulting list, whether updated or not. - -The @var{order} is typically a number (integer or float), and the -elements of the list are sorted in non-decreasing numerical order. - -@var{order} may also be omitted or @code{nil}. Then the numeric order -of @var{element} stays unchanged if it already has one; otherwise, -@var{element} has no numeric order. Elements without a numeric list -order are placed at the end of the list, in no particular order. - -Any other value for @var{order} removes the numeric order of @var{element} -if it already has one; otherwise, it is equivalent to @code{nil}. - -The argument @var{symbol} is not implicitly quoted; -@code{add-to-ordered-list} is an ordinary function, like @code{set} -and unlike @code{setq}. Quote the argument yourself if necessary. - -The ordering information is stored in a hash table on @var{symbol}'s -@code{list-order} property. -@end defun - -Here's a scenario showing how to use @code{add-to-ordered-list}: - -@example -(setq foo '()) - @result{} nil - -(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.} - @result{} (a) - -(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.} - @result{} (a c) - -(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.} - @result{} (a b c) - -(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.} - @result{} (a c b) - -(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} - @result{} (a c b d) - -(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. - @result{} (a c b e d) - -foo ;; @r{@code{foo} was changed.} - @result{} (a c b e d) -@end example - -@node Modifying Lists -@section Modifying Existing List Structure -@cindex destructive list operations - - You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the -primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' -operations because they change existing list structure. - -@cindex CL note---@code{rplaca} vs @code{setcar} -@quotation -@findex rplaca -@findex rplacd -@b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and -@code{rplacd} to alter list structure; they change structure the same -way as @code{setcar} and @code{setcdr}, but the Common Lisp functions -return the cons cell while @code{setcar} and @code{setcdr} return the -new @sc{car} or @sc{cdr}. -@end quotation - -@menu -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. -@end menu - -@node Setcar -@subsection Altering List Elements with @code{setcar} - - Changing the @sc{car} of a cons cell is done with @code{setcar}. When -used on a list, @code{setcar} replaces one element of a list with a -different element. - -@defun setcar cons object -This function stores @var{object} as the new @sc{car} of @var{cons}, -replacing its previous @sc{car}. In other words, it changes the -@sc{car} slot of @var{cons} to refer to @var{object}. It returns the -value @var{object}. For example: - -@example -@group -(setq x '(1 2)) - @result{} (1 2) -@end group -@group -(setcar x 4) - @result{} 4 -@end group -@group -x - @result{} (4 2) -@end group -@end example -@end defun - - When a cons cell is part of the shared structure of several lists, -storing a new @sc{car} into the cons changes one element of each of -these lists. Here is an example: - -@example -@group -;; @r{Create two lists that are partly shared.} -(setq x1 '(a b c)) - @result{} (a b c) -(setq x2 (cons 'z (cdr x1))) - @result{} (z b c) -@end group - -@group -;; @r{Replace the @sc{car} of a shared link.} -(setcar (cdr x1) 'foo) - @result{} foo -x1 ; @r{Both lists are changed.} - @result{} (a foo c) -x2 - @result{} (z foo c) -@end group - -@group -;; @r{Replace the @sc{car} of a link that is not shared.} -(setcar x1 'baz) - @result{} baz -x1 ; @r{Only one list is changed.} - @result{} (baz foo c) -x2 - @result{} (z foo c) -@end group -@end example - - Here is a graphical depiction of the shared structure of the two lists -in the variables @code{x1} and @code{x2}, showing why replacing @code{b} -changes them both: - -@example -@group - --- --- --- --- --- --- -x1---> | | |----> | | |--> | | |--> nil - --- --- --- --- --- --- - | --> | | - | | | | - --> a | --> b --> c - | - --- --- | -x2--> | | |-- - --- --- - | - | - --> z -@end group -@end example - - Here is an alternative form of box diagram, showing the same relationship: - -@example -@group -x1: - -------------- -------------- -------------- -| car | cdr | | car | cdr | | car | cdr | -| a | o------->| b | o------->| c | nil | -| | | -->| | | | | | - -------------- | -------------- -------------- - | -x2: | - -------------- | -| car | cdr | | -| z | o---- -| | | - -------------- -@end group -@end example - -@node Setcdr -@subsection Altering the CDR of a List - - The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: - -@defun setcdr cons object -This function stores @var{object} as the new @sc{cdr} of @var{cons}, -replacing its previous @sc{cdr}. In other words, it changes the -@sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the -value @var{object}. -@end defun - - Here is an example of replacing the @sc{cdr} of a list with a -different list. All but the first element of the list are removed in -favor of a different sequence of elements. The first element is -unchanged, because it resides in the @sc{car} of the list, and is not -reached via the @sc{cdr}. - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(setcdr x '(4)) - @result{} (4) -@end group -@group -x - @result{} (1 4) -@end group -@end example - - You can delete elements from the middle of a list by altering the -@sc{cdr}s of the cons cells in the list. For example, here we delete -the second element, @code{b}, from the list @code{(a b c)}, by changing -the @sc{cdr} of the first cons cell: - -@example -@group -(setq x1 '(a b c)) - @result{} (a b c) -(setcdr x1 (cdr (cdr x1))) - @result{} (c) -x1 - @result{} (a c) -@end group -@end example - - Here is the result in box notation: - -@smallexample -@group - -------------------- - | | - -------------- | -------------- | -------------- -| car | cdr | | | car | cdr | -->| car | cdr | -| a | o----- | b | o-------->| c | nil | -| | | | | | | | | - -------------- -------------- -------------- -@end group -@end smallexample - -@noindent -The second cons cell, which previously held the element @code{b}, still -exists and its @sc{car} is still @code{b}, but it no longer forms part -of this list. - - It is equally easy to insert a new element by changing @sc{cdr}s: - -@example -@group -(setq x1 '(a b c)) - @result{} (a b c) -(setcdr x1 (cons 'd (cdr x1))) - @result{} (d b c) -x1 - @result{} (a d b c) -@end group -@end example - - Here is this result in box notation: - -@smallexample -@group - -------------- ------------- ------------- -| car | cdr | | car | cdr | | car | cdr | -| a | o | -->| b | o------->| c | nil | -| | | | | | | | | | | - --------- | -- | ------------- ------------- - | | - ----- -------- - | | - | --------------- | - | | car | cdr | | - -->| d | o------ - | | | - --------------- -@end group -@end smallexample - -@node Rearrangement -@subsection Functions that Rearrange Lists -@cindex rearrangement of lists -@cindex reordering, of elements in lists -@cindex modification of lists - - Here are some functions that rearrange lists ``destructively'' by -modifying the @sc{cdr}s of their component cons cells. We call these -functions ``destructive'' because they chew up the original lists passed -to them as arguments, relinking their cons cells to form a new list that -is the returned value. - -@ifnottex - See @code{delq}, in @ref{Sets And Lists}, for another function -that modifies cons cells. -@end ifnottex -@iftex - The function @code{delq} in the following section is another example -of destructive list manipulation. -@end iftex - -@defun nconc &rest lists -@cindex concatenating lists -@cindex joining lists -This function returns a list containing all the elements of @var{lists}. -Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are -@emph{not} copied. Instead, the last @sc{cdr} of each of the -@var{lists} is changed to refer to the following list. The last of the -@var{lists} is not altered. For example: - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(nconc x '(4 5)) - @result{} (1 2 3 4 5) -@end group -@group -x - @result{} (1 2 3 4 5) -@end group -@end example - - Since the last argument of @code{nconc} is not itself modified, it is -reasonable to use a constant list, such as @code{'(4 5)}, as in the -above example. For the same reason, the last argument need not be a -list: - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(nconc x 'z) - @result{} (1 2 3 . z) -@end group -@group -x - @result{} (1 2 3 . z) -@end group -@end example - -However, the other arguments (all but the last) must be lists. - -A common pitfall is to use a quoted constant list as a non-last -argument to @code{nconc}. If you do this, your program will change -each time you run it! Here is what happens: - -@smallexample -@group -(defun add-foo (x) ; @r{We want this function to add} - (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.} -@end group - -@group -(symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo)) x)) -@end group - -@group -(setq xx (add-foo '(1 2))) ; @r{It seems to work.} - @result{} (foo 1 2) -@end group -@group -(setq xy (add-foo '(3 4))) ; @r{What happened?} - @result{} (foo 1 2 3 4) -@end group -@group -(eq xx xy) - @result{} t -@end group - -@group -(symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) -@end group -@end smallexample -@end defun - -@defun nreverse list -@cindex reversing a list - This function reverses the order of the elements of @var{list}. -Unlike @code{reverse}, @code{nreverse} alters its argument by reversing -the @sc{cdr}s in the cons cells forming the list. The cons cell that -used to be the last one in @var{list} becomes the first cons cell of the -value. - - For example: - -@example -@group -(setq x '(a b c)) - @result{} (a b c) -@end group -@group -x - @result{} (a b c) -(nreverse x) - @result{} (c b a) -@end group -@group -;; @r{The cons cell that was first is now last.} -x - @result{} (a) -@end group -@end example - - To avoid confusion, we usually store the result of @code{nreverse} -back in the same variable which held the original list: - -@example -(setq x (nreverse x)) -@end example - - Here is the @code{nreverse} of our favorite example, @code{(a b c)}, -presented graphically: - -@smallexample -@group -@r{Original list head:} @r{Reversed list:} - ------------- ------------- ------------ -| car | cdr | | car | cdr | | car | cdr | -| a | nil |<-- | b | o |<-- | c | o | -| | | | | | | | | | | | | - ------------- | --------- | - | -------- | - - | | | | - ------------- ------------ -@end group -@end smallexample -@end defun - -@defun sort list predicate -@cindex stable sort -@cindex sorting lists -This function sorts @var{list} stably, though destructively, and -returns the sorted list. It compares elements using @var{predicate}. A -stable sort is one in which elements with equal sort keys maintain their -relative order before and after the sort. Stability is important when -successive sorts are used to order elements according to different -criteria. - -The argument @var{predicate} must be a function that accepts two -arguments. It is called with two elements of @var{list}. To get an -increasing order sort, the @var{predicate} should return non-@code{nil} if the -first element is ``less than'' the second, or @code{nil} if not. - -The comparison function @var{predicate} must give reliable results for -any given pair of arguments, at least within a single call to -@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is -less than @var{b}, @var{b} must not be less than @var{a}. It must be -@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} -is less than @var{c}, then @var{a} must be less than @var{c}. If you -use a comparison function which does not meet these requirements, the -result of @code{sort} is unpredictable. - -The destructive aspect of @code{sort} is that it rearranges the cons -cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort -function would create new cons cells to store the elements in their -sorted order. If you wish to make a sorted copy without destroying the -original, copy it first with @code{copy-sequence} and then sort. - -Sorting does not change the @sc{car}s of the cons cells in @var{list}; -the cons cell that originally contained the element @code{a} in -@var{list} still has @code{a} in its @sc{car} after sorting, but it now -appears in a different position in the list due to the change of -@sc{cdr}s. For example: - -@example -@group -(setq nums '(1 3 2 6 5 4 0)) - @result{} (1 3 2 6 5 4 0) -@end group -@group -(sort nums '<) - @result{} (0 1 2 3 4 5 6) -@end group -@group -nums - @result{} (1 2 3 4 5 6) -@end group -@end example - -@noindent -@strong{Warning}: Note that the list in @code{nums} no longer contains -0; this is the same cons cell that it was before, but it is no longer -the first one in the list. Don't assume a variable that formerly held -the argument now holds the entire sorted list! Instead, save the result -of @code{sort} and use that. Most often we store the result back into -the variable that held the original list: - -@example -(setq nums (sort nums '<)) -@end example - -@xref{Sorting}, for more functions that perform sorting. -See @code{documentation} in @ref{Accessing Documentation}, for a -useful example of @code{sort}. -@end defun - -@node Sets And Lists -@section Using Lists as Sets -@cindex lists as sets -@cindex sets - - A list can represent an unordered mathematical set---simply consider a -value an element of a set if it appears in the list, and ignore the -order of the list. To form the union of two sets, use @code{append} (as -long as you don't mind having duplicate elements). You can remove -@code{equal} duplicates using @code{delete-dups}. Other useful -functions for sets include @code{memq} and @code{delq}, and their -@code{equal} versions, @code{member} and @code{delete}. - -@cindex CL note---lack @code{union}, @code{intersection} -@quotation -@b{Common Lisp note:} Common Lisp has functions @code{union} (which -avoids duplicate elements) and @code{intersection} for set operations. -Although standard GNU Emacs Lisp does not have them, the @file{cl-lib} -library provides versions. -@xref{Lists as Sets,,, cl, Common Lisp Extensions}. -@end quotation - -@defun memq object list -@cindex membership in a list -This function tests to see whether @var{object} is a member of -@var{list}. If it is, @code{memq} returns a list starting with the -first occurrence of @var{object}. Otherwise, it returns @code{nil}. -The letter @samp{q} in @code{memq} says that it uses @code{eq} to -compare @var{object} against the elements of the list. For example: - -@example -@group -(memq 'b '(a b c b a)) - @result{} (b c b a) -@end group -@group -(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} - @result{} nil -@end group -@end example -@end defun - -@defun delq object list -@cindex deleting list elements -This function destructively removes all elements @code{eq} to -@var{object} from @var{list}, and returns the resulting list. The -letter @samp{q} in @code{delq} says that it uses @code{eq} to compare -@var{object} against the elements of the list, like @code{memq} and -@code{remq}. - -Typically, when you invoke @code{delq}, you should use the return -value by assigning it to the variable which held the original list. -The reason for this is explained below. -@end defun - -The @code{delq} function deletes elements from the front of the list -by simply advancing down the list, and returning a sublist that starts -after those elements. For example: - -@example -@group -(delq 'a '(a b c)) @equiv{} (cdr '(a b c)) -@end group -@end example - -@noindent -When an element to be deleted appears in the middle of the list, -removing it involves changing the @sc{cdr}s (@pxref{Setcdr}). - -@example -@group -(setq sample-list '(a b c (4))) - @result{} (a b c (4)) -@end group -@group -(delq 'a sample-list) - @result{} (b c (4)) -@end group -@group -sample-list - @result{} (a b c (4)) -@end group -@group -(delq 'c sample-list) - @result{} (a b (4)) -@end group -@group -sample-list - @result{} (a b (4)) -@end group -@end example - -Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to -splice out the third element, but @code{(delq 'a sample-list)} does not -splice anything---it just returns a shorter list. Don't assume that a -variable which formerly held the argument @var{list} now has fewer -elements, or that it still holds the original list! Instead, save the -result of @code{delq} and use that. Most often we store the result back -into the variable that held the original list: - -@example -(setq flowers (delq 'rose flowers)) -@end example - -In the following example, the @code{(4)} that @code{delq} attempts to match -and the @code{(4)} in the @code{sample-list} are not @code{eq}: - -@example -@group -(delq '(4) sample-list) - @result{} (a c (4)) -@end group -@end example - -If you want to delete elements that are @code{equal} to a given value, -use @code{delete} (see below). - -@defun remq object list -This function returns a copy of @var{list}, with all elements removed -which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq} -says that it uses @code{eq} to compare @var{object} against the elements -of @code{list}. - -@example -@group -(setq sample-list '(a b c a b c)) - @result{} (a b c a b c) -@end group -@group -(remq 'a sample-list) - @result{} (b c b c) -@end group -@group -sample-list - @result{} (a b c a b c) -@end group -@end example -@end defun - -@defun memql object list -The function @code{memql} tests to see whether @var{object} is a member -of @var{list}, comparing members with @var{object} using @code{eql}, -so floating-point elements are compared by value. -If @var{object} is a member, @code{memql} returns a list starting with -its first occurrence in @var{list}. Otherwise, it returns @code{nil}. - -Compare this with @code{memq}: - -@example -@group -(memql 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are @code{eql}.} - @result{} (1.2 1.3) -@end group -@group -(memq 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are not @code{eq}.} - @result{} nil -@end group -@end example -@end defun - -The following three functions are like @code{memq}, @code{delq} and -@code{remq}, but use @code{equal} rather than @code{eq} to compare -elements. @xref{Equality Predicates}. - -@defun member object list -The function @code{member} tests to see whether @var{object} is a member -of @var{list}, comparing members with @var{object} using @code{equal}. -If @var{object} is a member, @code{member} returns a list starting with -its first occurrence in @var{list}. Otherwise, it returns @code{nil}. - -Compare this with @code{memq}: - -@example -@group -(member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.} - @result{} ((2)) -@end group -@group -(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} - @result{} nil -@end group -@group -;; @r{Two strings with the same contents are @code{equal}.} -(member "foo" '("foo" "bar")) - @result{} ("foo" "bar") -@end group -@end example -@end defun - -@defun delete object sequence -This function removes all elements @code{equal} to @var{object} from -@var{sequence}, and returns the resulting sequence. - -If @var{sequence} is a list, @code{delete} is to @code{delq} as -@code{member} is to @code{memq}: it uses @code{equal} to compare -elements with @var{object}, like @code{member}; when it finds an -element that matches, it cuts the element out just as @code{delq} -would. As with @code{delq}, you should typically use the return value -by assigning it to the variable which held the original list. - -If @code{sequence} is a vector or string, @code{delete} returns a copy -of @code{sequence} with all elements @code{equal} to @code{object} -removed. - -For example: - -@example -@group -(setq l '((2) (1) (2))) -(delete '(2) l) - @result{} ((1)) -l - @result{} ((2) (1)) -;; @r{If you want to change @code{l} reliably,} -;; @r{write @code{(setq l (delete '(2) l))}.} -@end group -@group -(setq l '((2) (1) (2))) -(delete '(1) l) - @result{} ((2) (2)) -l - @result{} ((2) (2)) -;; @r{In this case, it makes no difference whether you set @code{l},} -;; @r{but you should do so for the sake of the other case.} -@end group -@group -(delete '(2) [(2) (1) (2)]) - @result{} [(1)] -@end group -@end example -@end defun - -@defun remove object sequence -This function is the non-destructive counterpart of @code{delete}. It -returns a copy of @code{sequence}, a list, vector, or string, with -elements @code{equal} to @code{object} removed. For example: - -@example -@group -(remove '(2) '((2) (1) (2))) - @result{} ((1)) -@end group -@group -(remove '(2) [(2) (1) (2)]) - @result{} [(1)] -@end group -@end example -@end defun - -@quotation -@b{Common Lisp note:} The functions @code{member}, @code{delete} and -@code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common -Lisp. The Common Lisp versions do not use @code{equal} to compare -elements. -@end quotation - -@defun member-ignore-case object list -This function is like @code{member}, except that @var{object} should -be a string and that it ignores differences in letter-case and text -representation: upper-case and lower-case letters are treated as -equal, and unibyte strings are converted to multibyte prior to -comparison. -@end defun - -@defun delete-dups list -This function destructively removes all @code{equal} duplicates from -@var{list}, stores the result in @var{list} and returns it. Of -several @code{equal} occurrences of an element in @var{list}, -@code{delete-dups} keeps the first one. -@end defun - - See also the function @code{add-to-list}, in @ref{List Variables}, -for a way to add an element to a list stored in a variable and used as a -set. - -@node Association Lists -@section Association Lists -@cindex association list -@cindex alist - - An @dfn{association list}, or @dfn{alist} for short, records a mapping -from keys to values. It is a list of cons cells called -@dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the -@sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key'' -is not related to the term ``key sequence''; it means a value used to -look up an item in a table. In this case, the table is the alist, and -the alist associations are the items.} - - Here is an example of an alist. The key @code{pine} is associated with -the value @code{cones}; the key @code{oak} is associated with -@code{acorns}; and the key @code{maple} is associated with @code{seeds}. - -@example -@group -((pine . cones) - (oak . acorns) - (maple . seeds)) -@end group -@end example - - Both the values and the keys in an alist may be any Lisp objects. -For example, in the following alist, the symbol @code{a} is -associated with the number @code{1}, and the string @code{"b"} is -associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of -the alist element: - -@example -((a . 1) ("b" 2 3)) -@end example - - Sometimes it is better to design an alist to store the associated -value in the @sc{car} of the @sc{cdr} of the element. Here is an -example of such an alist: - -@example -((rose red) (lily white) (buttercup yellow)) -@end example - -@noindent -Here we regard @code{red} as the value associated with @code{rose}. One -advantage of this kind of alist is that you can store other related -information---even a list of other items---in the @sc{cdr} of the -@sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see -below) to find the element containing a given value. When neither of -these considerations is important, the choice is a matter of taste, as -long as you are consistent about it for any given alist. - - The same alist shown above could be regarded as having the -associated value in the @sc{cdr} of the element; the value associated -with @code{rose} would be the list @code{(red)}. - - Association lists are often used to record information that you might -otherwise keep on a stack, since new associations may be added easily to -the front of the list. When searching an association list for an -association with a given key, the first one found is returned, if there -is more than one. - - In Emacs Lisp, it is @emph{not} an error if an element of an -association list is not a cons cell. The alist search functions simply -ignore such elements. Many other versions of Lisp signal errors in such -cases. - - Note that property lists are similar to association lists in several -respects. A property list behaves like an association list in which -each key can occur only once. @xref{Property Lists}, for a comparison -of property lists and association lists. - -@defun assoc key alist -This function returns the first association for @var{key} in -@var{alist}, comparing @var{key} against the alist elements using -@code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no -association in @var{alist} has a @sc{car} @code{equal} to @var{key}. -For example: - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - @result{} ((pine . cones) (oak . acorns) (maple . seeds)) -(assoc 'oak trees) - @result{} (oak . acorns) -(cdr (assoc 'oak trees)) - @result{} acorns -(assoc 'birch trees) - @result{} nil -@end smallexample - -Here is another example, in which the keys and values are not symbols: - -@smallexample -(setq needles-per-cluster - '((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine"))) - -(cdr (assoc 3 needles-per-cluster)) - @result{} ("Pitch Pine") -(cdr (assoc 2 needles-per-cluster)) - @result{} ("Austrian Pine" "Red Pine") -@end smallexample -@end defun - - The function @code{assoc-string} is much like @code{assoc} except -that it ignores certain differences between strings. @xref{Text -Comparison}. - -@defun rassoc value alist -This function returns the first association with value @var{value} in -@var{alist}. It returns @code{nil} if no association in @var{alist} has -a @sc{cdr} @code{equal} to @var{value}. - -@code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of -each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assoc}'', finding the key for a given value. -@end defun - -@defun assq key alist -This function is like @code{assoc} in that it returns the first -association for @var{key} in @var{alist}, but it makes the comparison -using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil} -if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}. -This function is used more often than @code{assoc}, since @code{eq} is -faster than @code{equal} and most alists use symbols as keys. -@xref{Equality Predicates}. - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - @result{} ((pine . cones) (oak . acorns) (maple . seeds)) -(assq 'pine trees) - @result{} (pine . cones) -@end smallexample - -On the other hand, @code{assq} is not usually useful in alists where the -keys may not be symbols: - -@smallexample -(setq leaves - '(("simple leaves" . oak) - ("compound leaves" . horsechestnut))) - -(assq "simple leaves" leaves) - @result{} nil -(assoc "simple leaves" leaves) - @result{} ("simple leaves" . oak) -@end smallexample -@end defun - -@defun rassq value alist -This function returns the first association with value @var{value} in -@var{alist}. It returns @code{nil} if no association in @var{alist} has -a @sc{cdr} @code{eq} to @var{value}. - -@code{rassq} is like @code{assq} except that it compares the @sc{cdr} of -each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assq}'', finding the key for a given value. - -For example: - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - -(rassq 'acorns trees) - @result{} (oak . acorns) -(rassq 'spores trees) - @result{} nil -@end smallexample - -@code{rassq} cannot search for a value stored in the @sc{car} -of the @sc{cdr} of an element: - -@smallexample -(setq colors '((rose red) (lily white) (buttercup yellow))) - -(rassq 'white colors) - @result{} nil -@end smallexample - -In this case, the @sc{cdr} of the association @code{(lily white)} is not -the symbol @code{white}, but rather the list @code{(white)}. This -becomes clearer if the association is written in dotted pair notation: - -@smallexample -(lily white) @equiv{} (lily . (white)) -@end smallexample -@end defun - -@defun assoc-default key alist &optional test default -This function searches @var{alist} for a match for @var{key}. For each -element of @var{alist}, it compares the element (if it is an atom) or -the element's @sc{car} (if it is a cons) against @var{key}, by calling -@var{test} with two arguments: the element or its @sc{car}, and -@var{key}. The arguments are passed in that order so that you can get -useful results using @code{string-match} with an alist that contains -regular expressions (@pxref{Regexp Search}). If @var{test} is omitted -or @code{nil}, @code{equal} is used for comparison. - -If an alist element matches @var{key} by this criterion, -then @code{assoc-default} returns a value based on this element. -If the element is a cons, then the value is the element's @sc{cdr}. -Otherwise, the return value is @var{default}. - -If no alist element matches @var{key}, @code{assoc-default} returns -@code{nil}. -@end defun - -@defun copy-alist alist -@cindex copying alists -This function returns a two-level deep copy of @var{alist}: it creates a -new copy of each association, so that you can alter the associations of -the new alist without changing the old one. - -@smallexample -@group -(setq needles-per-cluster - '((2 . ("Austrian Pine" "Red Pine")) - (3 . ("Pitch Pine")) -@end group - (5 . ("White Pine")))) -@result{} -((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine")) - -(setq copy (copy-alist needles-per-cluster)) -@result{} -((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine")) - -(eq needles-per-cluster copy) - @result{} nil -(equal needles-per-cluster copy) - @result{} t -(eq (car needles-per-cluster) (car copy)) - @result{} nil -(cdr (car (cdr needles-per-cluster))) - @result{} ("Pitch Pine") -@group -(eq (cdr (car (cdr needles-per-cluster))) - (cdr (car (cdr copy)))) - @result{} t -@end group -@end smallexample - - This example shows how @code{copy-alist} makes it possible to change -the associations of one copy without affecting the other: - -@smallexample -@group -(setcdr (assq 3 copy) '("Martian Vacuum Pine")) -(cdr (assq 3 needles-per-cluster)) - @result{} ("Pitch Pine") -@end group -@end smallexample -@end defun - -@defun assq-delete-all key alist -This function deletes from @var{alist} all the elements whose @sc{car} -is @code{eq} to @var{key}, much as if you used @code{delq} to delete -each such element one by one. It returns the shortened alist, and -often modifies the original list structure of @var{alist}. For -correct results, use the return value of @code{assq-delete-all} rather -than looking at the saved value of @var{alist}. - -@example -(setq alist '((foo 1) (bar 2) (foo 3) (lose 4))) - @result{} ((foo 1) (bar 2) (foo 3) (lose 4)) -(assq-delete-all 'foo alist) - @result{} ((bar 2) (lose 4)) -alist - @result{} ((foo 1) (bar 2) (lose 4)) -@end example -@end defun - -@defun rassq-delete-all value alist -This function deletes from @var{alist} all the elements whose @sc{cdr} -is @code{eq} to @var{value}. It returns the shortened alist, and -often modifies the original list structure of @var{alist}. -@code{rassq-delete-all} is like @code{assq-delete-all} except that it -compares the @sc{cdr} of each @var{alist} association instead of the -@sc{car}. -@end defun - -@node Property Lists -@section Property Lists -@cindex property list -@cindex plist - - A @dfn{property list} (@dfn{plist} for short) is a list of paired -elements. Each of the pairs associates a property name (usually a -symbol) with a property or value. Here is an example of a property -list: - -@example -(pine cones numbers (1 2 3) color "blue") -@end example - -@noindent -This property list associates @code{pine} with @code{cones}, -@code{numbers} with @code{(1 2 3)}, and @code{color} with -@code{"blue"}. The property names and values can be any Lisp objects, -but the names are usually symbols (as they are in this example). - - Property lists are used in several contexts. For instance, the -function @code{put-text-property} takes an argument which is a -property list, specifying text properties and associated values which -are to be applied to text in a string or buffer. @xref{Text -Properties}. - - Another prominent use of property lists is for storing symbol -properties. Every symbol possesses a list of properties, used to -record miscellaneous information about the symbol; these properties -are stored in the form of a property list. @xref{Symbol Properties}. - -@menu -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Plist Access:: Accessing property lists stored elsewhere. -@end menu - -@node Plists and Alists -@subsection Property Lists and Association Lists -@cindex plist vs. alist -@cindex alist vs. plist - -@cindex property lists vs association lists - Association lists (@pxref{Association Lists}) are very similar to -property lists. In contrast to association lists, the order of the -pairs in the property list is not significant, since the property -names must be distinct. - - Property lists are better than association lists for attaching -information to various Lisp function names or variables. If your -program keeps all such information in one association list, it will -typically need to search that entire list each time it checks for an -association for a particular Lisp function name or variable, which -could be slow. By contrast, if you keep the same information in the -property lists of the function names or variables themselves, each -search will scan only the length of one property list, which is -usually short. This is why the documentation for a variable is -recorded in a property named @code{variable-documentation}. The byte -compiler likewise uses properties to record those functions needing -special treatment. - - However, association lists have their own advantages. Depending on -your application, it may be faster to add an association to the front of -an association list than to update a property. All properties for a -symbol are stored in the same property list, so there is a possibility -of a conflict between different uses of a property name. (For this -reason, it is a good idea to choose property names that are probably -unique, such as by beginning the property name with the program's usual -name-prefix for variables and functions.) An association list may be -used like a stack where associations are pushed on the front of the list -and later discarded; this is not possible with a property list. - -@node Plist Access -@subsection Property Lists Outside Symbols - - The following functions can be used to manipulate property lists. -They all compare property names using @code{eq}. - -@defun plist-get plist property -This returns the value of the @var{property} property stored in the -property list @var{plist}. It accepts a malformed @var{plist} -argument. If @var{property} is not found in the @var{plist}, it -returns @code{nil}. For example, - -@example -(plist-get '(foo 4) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'bad) - @result{} nil -(plist-get '(foo 4 bad) 'bar) - @result{} nil -@end example -@end defun - -@defun plist-put plist property value -This stores @var{value} as the value of the @var{property} property in -the property list @var{plist}. It may modify @var{plist} destructively, -or it may construct a new list structure without altering the old. The -function returns the modified property list, so you can store that back -in the place where you got @var{plist}. For example, - -@example -(setq my-plist '(bar t foo 4)) - @result{} (bar t foo 4) -(setq my-plist (plist-put my-plist 'foo 69)) - @result{} (bar t foo 69) -(setq my-plist (plist-put my-plist 'quux '(a))) - @result{} (bar t foo 69 quux (a)) -@end example -@end defun - -@defun lax-plist-get plist property -Like @code{plist-get} except that it compares properties -using @code{equal} instead of @code{eq}. -@end defun - -@defun lax-plist-put plist property value -Like @code{plist-put} except that it compares properties -using @code{equal} instead of @code{eq}. -@end defun - -@defun plist-member plist property -This returns non-@code{nil} if @var{plist} contains the given -@var{property}. Unlike @code{plist-get}, this allows you to distinguish -between a missing property and a property with the value @code{nil}. -The value is actually the tail of @var{plist} whose @code{car} is -@var{property}. -@end defun diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi deleted file mode 100644 index a07c2e8a792..00000000000 --- a/doc/lispref/loading.texi +++ /dev/null @@ -1,1074 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Loading -@chapter Loading -@cindex loading -@cindex library -@cindex Lisp library - - Loading a file of Lisp code means bringing its contents into the -Lisp environment in the form of Lisp objects. Emacs finds and opens -the file, reads the text, evaluates each form, and then closes the -file. Such a file is also called a @dfn{Lisp library}. - - The load functions evaluate all the expressions in a file just -as the @code{eval-buffer} function evaluates all the -expressions in a buffer. The difference is that the load functions -read and evaluate the text in the file as found on disk, not the text -in an Emacs buffer. - -@cindex top-level form - The loaded file must contain Lisp expressions, either as source code -or as byte-compiled code. Each form in the file is called a -@dfn{top-level form}. There is no special format for the forms in a -loadable file; any form in a file may equally well be typed directly -into a buffer and evaluated there. (Indeed, most code is tested this -way.) Most often, the forms are function definitions and variable -definitions. - -For on-demand loading of external libraries, @pxref{Dynamic Libraries}. - -@menu -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. -@end menu - -@node How Programs Do Loading -@section How Programs Do Loading - - Emacs Lisp has several interfaces for loading. For example, -@code{autoload} creates a placeholder object for a function defined in a -file; trying to call the autoloading function loads the file to get the -function's real definition (@pxref{Autoload}). @code{require} loads a -file if it isn't already loaded (@pxref{Named Features}). Ultimately, -all these facilities call the @code{load} function to do the work. - -@defun load filename &optional missing-ok nomessage nosuffix must-suffix -This function finds and opens a file of Lisp code, evaluates all the -forms in it, and closes the file. - -To find the file, @code{load} first looks for a file named -@file{@var{filename}.elc}, that is, for a file whose name is -@var{filename} with the extension @samp{.elc} appended. If such a -file exists, it is loaded. If there is no file by that name, then -@code{load} looks for a file named @file{@var{filename}.el}. If that -file exists, it is loaded. Finally, if neither of those names is -found, @code{load} looks for a file named @var{filename} with nothing -appended, and loads it if it exists. (The @code{load} function is not -clever about looking at @var{filename}. In the perverse case of a -file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will -indeed find it.) - -If Auto Compression mode is enabled, as it is by default, then if -@code{load} can not find a file, it searches for a compressed version -of the file before trying other file names. It decompresses and loads -it if it exists. It looks for compressed versions by appending each -of the suffixes in @code{jka-compr-load-suffixes} to the file name. -The value of this variable must be a list of strings. Its standard -value is @code{(".gz")}. - -If the optional argument @var{nosuffix} is non-@code{nil}, then -@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In -this case, you must specify the precise file name you want, except -that, if Auto Compression mode is enabled, @code{load} will still use -@code{jka-compr-load-suffixes} to find compressed versions. By -specifying the precise file name and using @code{t} for -@var{nosuffix}, you can prevent file names like @file{foo.el.el} from -being tried. - -If the optional argument @var{must-suffix} is non-@code{nil}, then -@code{load} insists that the file name used must end in either -@samp{.el} or @samp{.elc} (possibly extended with a compression -suffix), unless it contains an explicit directory name. - -If the option @code{load-prefer-newer} is non-@code{nil}, then when -searching suffixes, @code{load} selects whichever version of a file -(@samp{.elc}, @samp{.el}, etc.) has been modified most recently. - -If @var{filename} is a relative file name, such as @file{foo} or -@file{baz/foo.bar}, @code{load} searches for the file using the variable -@code{load-path}. It appends @var{filename} to each of the directories -listed in @code{load-path}, and loads the first file it finds whose name -matches. The current default directory is tried only if it is specified -in @code{load-path}, where @code{nil} stands for the default directory. -@code{load} tries all three possible suffixes in the first directory in -@code{load-path}, then all three suffixes in the second directory, and -so on. @xref{Library Search}. - -Whatever the name under which the file is eventually found, and the -directory where Emacs found it, Emacs sets the value of the variable -@code{load-file-name} to that file's name. - -If you get a warning that @file{foo.elc} is older than @file{foo.el}, it -means you should consider recompiling @file{foo.el}. @xref{Byte -Compilation}. - -When loading a source file (not compiled), @code{load} performs -character set translation just as Emacs would do when visiting the file. -@xref{Coding Systems}. - -@c This is referred to from the Macros chapter. -@c Not sure if it should be the other way round. -@cindex eager macro expansion -When loading an uncompiled file, Emacs tries to expand any macros -that the file contains (@pxref{Macros}). We refer to this as -@dfn{eager macro expansion}. Doing this (rather than deferring -the expansion until the relevant code runs) can significantly speed -up the execution of uncompiled code. Sometimes, this macro expansion -cannot be done, owing to a cyclic dependency. In the simplest -example of this, the file you are loading refers to a macro defined -in another file, and that file in turn requires the file you are -loading. This is generally harmless. Emacs prints a warning -(@samp{Eager macro-expansion skipped due to cycle@dots{}}) -giving details of the problem, but it still loads the file, just -leaving the macro unexpanded for now. You may wish to restructure -your code so that this does not happen. Loading a compiled file does -not cause macroexpansion, because this should already have happened -during compilation. @xref{Compiling Macros}. - -Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear -in the echo area during loading unless @var{nomessage} is -non-@code{nil}. - -@cindex load errors -Any unhandled errors while loading a file terminate loading. If the -load was done for the sake of @code{autoload}, any function definitions -made during the loading are undone. - -@kindex file-error -If @code{load} can't find the file to load, then normally it signals the -error @code{file-error} (with @samp{Cannot open load file -@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then -@code{load} just returns @code{nil}. - -You can use the variable @code{load-read-function} to specify a function -for @code{load} to use instead of @code{read} for reading expressions. -See below. - -@code{load} returns @code{t} if the file loads successfully. -@end defun - -@deffn Command load-file filename -This command loads the file @var{filename}. If @var{filename} is a -relative file name, then the current default directory is assumed. -This command does not use @code{load-path}, and does not append -suffixes. However, it does look for compressed versions (if Auto -Compression Mode is enabled). Use this command if you wish to specify -precisely the file name to load. -@end deffn - -@deffn Command load-library library -This command loads the library named @var{library}. It is equivalent to -@code{load}, except for the way it reads its argument interactively. -@xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}. -@end deffn - -@defvar load-in-progress -This variable is non-@code{nil} if Emacs is in the process of loading a -file, and it is @code{nil} otherwise. -@end defvar - -@defvar load-file-name -When Emacs is in the process of loading a file, this variable's value -is the name of that file, as Emacs found it during the search -described earlier in this section. -@end defvar - -@defvar load-read-function -@anchor{Definition of load-read-function} -@c do not allow page break at anchor; work around Texinfo deficiency. -This variable specifies an alternate expression-reading function for -@code{load} and @code{eval-region} to use instead of @code{read}. -The function should accept one argument, just as @code{read} does. - -Normally, the variable's value is @code{nil}, which means those -functions should use @code{read}. - -Instead of using this variable, it is cleaner to use another, newer -feature: to pass the function as the @var{read-function} argument to -@code{eval-region}. @xref{Definition of eval-region,, Eval}. -@end defvar - - For information about how @code{load} is used in building Emacs, see -@ref{Building Emacs}. - -@node Load Suffixes -@section Load Suffixes -We now describe some technical details about the exact suffixes that -@code{load} tries. - -@defvar load-suffixes -This is a list of suffixes indicating (compiled or source) Emacs Lisp -files. It should not include the empty string. @code{load} uses -these suffixes in order when it appends Lisp suffixes to the specified -file name. The standard value is @code{(".elc" ".el")} which produces -the behavior described in the previous section. -@end defvar - -@defvar load-file-rep-suffixes -This is a list of suffixes that indicate representations of the same -file. This list should normally start with the empty string. -When @code{load} searches for a file it appends the suffixes in this -list, in order, to the file name, before searching for another file. - -Enabling Auto Compression mode appends the suffixes in -@code{jka-compr-load-suffixes} to this list and disabling Auto -Compression mode removes them again. The standard value of -@code{load-file-rep-suffixes} if Auto Compression mode is disabled is -@code{("")}. Given that the standard value of -@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value -of @code{load-file-rep-suffixes} if Auto Compression mode is enabled -is @code{("" ".gz")}. -@end defvar - -@defun get-load-suffixes -This function returns the list of all suffixes that @code{load} should -try, in order, when its @var{must-suffix} argument is non-@code{nil}. -This takes both @code{load-suffixes} and @code{load-file-rep-suffixes} -into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes} -and @code{load-file-rep-suffixes} all have their standard values, this -function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto -Compression mode is enabled and @code{(".elc" ".el")} if Auto -Compression mode is disabled. -@end defun - -To summarize, @code{load} normally first tries the suffixes in the -value of @code{(get-load-suffixes)} and then those in -@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil}, -it skips the former group, and if @var{must-suffix} is non-@code{nil}, -it skips the latter group. - -@defopt load-prefer-newer -If this option is non-@code{nil}, then rather than stopping at the -first suffix that exists, @code{load} tests them all, and uses -whichever file is the newest. -@end defopt - -@node Library Search -@section Library Search -@cindex library search -@cindex find library - - When Emacs loads a Lisp library, it searches for the library -in a list of directories specified by the variable @code{load-path}. - -@defvar load-path -The value of this variable is a list of directories to search when -loading files with @code{load}. Each element is a string (which must be -a directory name) or @code{nil} (which stands for the current working -directory). -@end defvar - - When Emacs starts up, it sets up the value of @code{load-path} -in several steps. First, it initializes @code{load-path} using -default locations set when Emacs was compiled. Normally, this -is a directory something like - -@example -"/usr/local/share/emacs/@var{version}/lisp" -@end example - -(In this and the following examples, replace @file{/usr/local} with -the installation prefix appropriate for your Emacs.) -These directories contain the standard Lisp files that come with -Emacs. If Emacs cannot find them, it will not start correctly. - -If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---Emacs instead -initializes @code{load-path} using the @file{lisp} -directory in the directory containing the sources from which it -was built. -@c Though there should be no *.el files in builddir/lisp, so it's pointless. -If you built Emacs in a separate directory from the -sources, it also adds the lisp directories from the build directory. -(In all cases, elements are represented as absolute file names.) - -@cindex site-lisp directories -Unless you start Emacs with the @option{--no-site-lisp} option, -it then adds two more @file{site-lisp} directories to the front of -@code{load-path}. These are intended for locally installed Lisp files, -and are normally of the form: - -@example -"/usr/local/share/emacs/@var{version}/site-lisp" -@end example - -@noindent -and - -@example -"/usr/local/share/emacs/site-lisp" -@end example - -@noindent -The first one is for locally installed files for a specific Emacs -version; the second is for locally installed files meant for use -with all installed Emacs versions. (If Emacs is running uninstalled, -it also adds @file{site-lisp} directories from the source and build -directories, if they exist. Normally these directories do not contain -@file{site-lisp} directories.) - -@cindex @env{EMACSLOADPATH} environment variable -If the environment variable @env{EMACSLOADPATH} is set, it modifies -the above initialization procedure. Emacs initializes -@code{load-path} based on the value of the environment variable. - -The syntax of @env{EMACSLOADPATH} is the same as used for @code{PATH}; -directory names are separated by @samp{:} (or @samp{;}, on some -operating systems). -@ignore -@c AFAICS, does not (yet) work right to specify non-absolute elements. -and @samp{.} stands for the current default directory. -@end ignore -Here is an example of how to set @env{EMACSLOADPATH} variable (from a -@command{sh}-style shell): - -@example -export EMACSLOADPATH=/home/foo/.emacs.d/lisp: -@end example - -An empty element in the value of the environment variable, whether -trailing (as in the above example), leading, or embedded, is replaced -by the default value of @code{load-path} as determined by the standard -initialization procedure. If there are no such empty elements, then -@env{EMACSLOADPATH} specifies the entire @code{load-path}. You must -include either an empty element, or the explicit path to the directory -containing the standard Lisp files, else Emacs will not function. -(Another way to modify @code{load-path} is to use the @option{-L} -command-line option when starting Emacs; see below.) - - For each directory in @code{load-path}, Emacs then checks to see if -it contains a file @file{subdirs.el}, and if so, loads it. The -@file{subdirs.el} file is created when Emacs is built/installed, -and contains code that causes Emacs to add any subdirectories of those -directories to @code{load-path}. Both immediate subdirectories and -subdirectories multiple levels down are added. But it excludes -subdirectories whose names do not start with a letter or digit, and -subdirectories named @file{RCS} or @file{CVS}, and subdirectories -containing a file named @file{.nosearch}. - - Next, Emacs adds any extra load directories that you specify using the -@option{-L} command-line option (@pxref{Action Arguments,,,emacs, The -GNU Emacs Manual}). It also adds the directories where optional -packages are installed, if any (@pxref{Packaging Basics}). - - It is common to add code to one's init file (@pxref{Init File}) to -add one or more directories to @code{load-path}. For example: - -@example -(push "~/.emacs.d/lisp" load-path) -@end example - - Dumping Emacs uses a special value of @code{load-path}. If you use -a @file{site-load.el} or @file{site-init.el} file to customize the -dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path} -that these files make will be lost after dumping. - -@deffn Command locate-library library &optional nosuffix path interactive-call -This command finds the precise file name for library @var{library}. It -searches for the library in the same way @code{load} does, and the -argument @var{nosuffix} has the same meaning as in @code{load}: don't -add suffixes @samp{.elc} or @samp{.el} to the specified name -@var{library}. - -If the @var{path} is non-@code{nil}, that list of directories is used -instead of @code{load-path}. - -When @code{locate-library} is called from a program, it returns the file -name as a string. When the user runs @code{locate-library} -interactively, the argument @var{interactive-call} is @code{t}, and this -tells @code{locate-library} to display the file name in the echo area. -@end deffn - -@cindex shadowed Lisp files -@deffn Command list-load-path-shadows &optional stringp -This command shows a list of @dfn{shadowed} Emacs Lisp files. A -shadowed file is one that will not normally be loaded, despite being -in a directory on @code{load-path}, due to the existence of another -similarly-named file in a directory earlier on @code{load-path}. - -For instance, suppose @code{load-path} is set to - -@example - ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp") -@end example - -@noindent -and that both these directories contain a file named @file{foo.el}. -Then @code{(require 'foo)} never loads the file in the second -directory. Such a situation might indicate a problem in the way Emacs -was installed. - -When called from Lisp, this function prints a message listing the -shadowed files, instead of displaying them in a buffer. If the -optional argument @code{stringp} is non-@code{nil}, it instead returns -the shadowed files as a string. -@end deffn - -@node Loading Non-ASCII -@section Loading Non-@acronym{ASCII} Characters - - When Emacs Lisp programs contain string constants with non-@acronym{ASCII} -characters, these can be represented within Emacs either as unibyte -strings or as multibyte strings (@pxref{Text Representations}). Which -representation is used depends on how the file is read into Emacs. If -it is read with decoding into multibyte representation, the text of the -Lisp program will be multibyte text, and its string constants will be -multibyte strings. If a file containing Latin-1 characters (for -example) is read without decoding, the text of the program will be -unibyte text, and its string constants will be unibyte strings. -@xref{Coding Systems}. - - In most Emacs Lisp programs, the fact that non-@acronym{ASCII} -strings are multibyte strings should not be noticeable, since -inserting them in unibyte buffers converts them to unibyte -automatically. However, if this does make a difference, you can force -a particular Lisp file to be interpreted as unibyte by writing -@samp{coding: raw-text} in a local variables section. With -that designator, the file will unconditionally be interpreted as -unibyte. This can matter when making keybindings to -non-@acronym{ASCII} characters written as @code{?v@var{literal}}. - -@node Autoload -@section Autoload -@cindex autoload - - The @dfn{autoload} facility lets you register the existence of a -function or macro, but put off loading the file that defines it. The -first call to the function automatically loads the proper library, in -order to install the real definition and other associated code, then -runs the real definition as if it had been loaded all along. -Autoloading can also be triggered by looking up the documentation of -the function or macro (@pxref{Documentation Basics}). - - There are two ways to set up an autoloaded function: by calling -@code{autoload}, and by writing a special ``magic'' comment in the -source before the real definition. @code{autoload} is the low-level -primitive for autoloading; any Lisp program can call @code{autoload} at -any time. Magic comments are the most convenient way to make a function -autoload, for packages installed along with Emacs. These comments do -nothing on their own, but they serve as a guide for the command -@code{update-file-autoloads}, which constructs calls to @code{autoload} -and arranges to execute them when Emacs is built. - -@defun autoload function filename &optional docstring interactive type -This function defines the function (or macro) named @var{function} so as -to load automatically from @var{filename}. The string @var{filename} -specifies the file to load to get the real definition of @var{function}. - -If @var{filename} does not contain either a directory name, or the -suffix @code{.el} or @code{.elc}, this function insists on adding one -of these suffixes, and it will not load from a file whose name is just -@var{filename} with no added suffix. (The variable -@code{load-suffixes} specifies the exact required suffixes.) - -The argument @var{docstring} is the documentation string for the -function. Specifying the documentation string in the call to -@code{autoload} makes it possible to look at the documentation without -loading the function's real definition. Normally, this should be -identical to the documentation string in the function definition -itself. If it isn't, the function definition's documentation string -takes effect when it is loaded. - -If @var{interactive} is non-@code{nil}, that says @var{function} can be -called interactively. This lets completion in @kbd{M-x} work without -loading @var{function}'s real definition. The complete interactive -specification is not given here; it's not needed unless the user -actually calls @var{function}, and when that happens, it's time to load -the real definition. - -You can autoload macros and keymaps as well as ordinary functions. -Specify @var{type} as @code{macro} if @var{function} is really a macro. -Specify @var{type} as @code{keymap} if @var{function} is really a -keymap. Various parts of Emacs need to know this information without -loading the real definition. - -An autoloaded keymap loads automatically during key lookup when a prefix -key's binding is the symbol @var{function}. Autoloading does not occur -for other kinds of access to the keymap. In particular, it does not -happen when a Lisp program gets the keymap from the value of a variable -and calls @code{define-key}; not even if the variable name is the same -symbol @var{function}. - -@cindex function cell in autoload -If @var{function} already has a non-void function definition that is not -an autoload object, this function does nothing and returns @code{nil}. -Otherwise, it constructs an autoload object (@pxref{Autoload Type}), -and stores it as the function definition for @var{function}. The -autoload object has this form: - -@example -(autoload @var{filename} @var{docstring} @var{interactive} @var{type}) -@end example - -For example, - -@example -@group -(symbol-function 'run-prolog) - @result{} (autoload "prolog" 169681 t nil) -@end group -@end example - -@noindent -In this case, @code{"prolog"} is the name of the file to load, 169681 -refers to the documentation string in the -@file{emacs/etc/DOC} file (@pxref{Documentation Basics}), -@code{t} means the function is interactive, and @code{nil} that it is -not a macro or a keymap. -@end defun - -@defun autoloadp object -This function returns non-@code{nil} if @var{object} is an autoload -object. For example, to check if @code{run-prolog} is defined as an -autoloaded function, evaluate - -@smallexample -(autoloadp (symbol-function 'run-prolog)) -@end smallexample -@end defun - -@cindex autoload errors - The autoloaded file usually contains other definitions and may require -or provide one or more features. If the file is not completely loaded -(due to an error in the evaluation of its contents), any function -definitions or @code{provide} calls that occurred during the load are -undone. This is to ensure that the next attempt to call any function -autoloading from this file will try again to load the file. If not for -this, then some of the functions in the file might be defined by the -aborted load, but fail to work properly for the lack of certain -subroutines not loaded successfully because they come later in the file. - - If the autoloaded file fails to define the desired Lisp function or -macro, then an error is signaled with data @code{"Autoloading failed to -define function @var{function-name}"}. - -@findex update-file-autoloads -@findex update-directory-autoloads -@cindex magic autoload comment -@cindex autoload cookie -@anchor{autoload cookie} - A magic autoload comment (often called an @dfn{autoload cookie}) -consists of @samp{;;;###autoload}, on a line by itself, -just before the real definition of the function in its -autoloadable source file. The command @kbd{M-x update-file-autoloads} -writes a corresponding @code{autoload} call into @file{loaddefs.el}. -(The string that serves as the autoload cookie and the name of the -file generated by @code{update-file-autoloads} can be changed from the -above defaults, see below.) -Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. -@kbd{M-x update-directory-autoloads} is even more powerful; it updates -autoloads for all files in the current directory. - - The same magic comment can copy any kind of form into -@file{loaddefs.el}. The form following the magic comment is copied -verbatim, @emph{except} if it is one of the forms which the autoload -facility handles specially (e.g., by conversion into an -@code{autoload} call). The forms which are not copied verbatim are -the following: - -@table @asis -@item Definitions for function or function-like objects: -@code{defun} and @code{defmacro}; also @code{cl-defun} and -@code{cl-defmacro} (@pxref{Argument Lists,,,cl,Common Lisp Extensions}), -and @code{define-overloadable-function} (see the commentary in -@file{mode-local.el}). - -@item Definitions for major or minor modes: -@code{define-minor-mode}, @code{define-globalized-minor-mode}, -@code{define-generic-mode}, @code{define-derived-mode}, -@code{easy-mmode-define-minor-mode}, -@code{easy-mmode-define-global-mode}, @code{define-compilation-mode}, -and @code{define-global-minor-mode}. - -@item Other definition types: -@code{defcustom}, @code{defgroup}, @code{defclass} -(@pxref{Top,EIEIO,,eieio,EIEIO}), and @code{define-skeleton} (see the -commentary in @file{skeleton.el}). -@end table - - You can also use a magic comment to execute a form at build time -@emph{without} executing it when the file itself is loaded. To do this, -write the form @emph{on the same line} as the magic comment. Since it -is in a comment, it does nothing when you load the source file; but -@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where -it is executed while building Emacs. - - The following example shows how @code{doctor} is prepared for -autoloading with a magic comment: - -@example -;;;###autoload -(defun doctor () - "Switch to *doctor* buffer and start giving psychotherapy." - (interactive) - (switch-to-buffer "*doctor*") - (doctor-mode)) -@end example - -@noindent -Here's what that produces in @file{loaddefs.el}: - -@example -(autoload (quote doctor) "doctor" "\ -Switch to *doctor* buffer and start giving psychotherapy. - -\(fn)" t nil) -@end example - -@noindent -@cindex @code{fn} in function's documentation string -The backslash and newline immediately following the double-quote are a -convention used only in the preloaded uncompiled Lisp files such as -@file{loaddefs.el}; they tell @code{make-docfile} to put the -documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. -See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)} -in the usage part of the documentation string is replaced with the -function's name when the various help functions (@pxref{Help -Functions}) display it. - - If you write a function definition with an unusual macro that is not -one of the known and recognized function definition methods, use of an -ordinary magic autoload comment would copy the whole definition into -@code{loaddefs.el}. That is not desirable. You can put the desired -@code{autoload} call into @code{loaddefs.el} instead by writing this: - -@example -;;;###autoload (autoload 'foo "myfile") -(mydefunmacro foo - ...) -@end example - - You can use a non-default string as the autoload cookie and have the -corresponding autoload calls written into a file whose name is -different from the default @file{loaddefs.el}. Emacs provides two -variables to control this: - -@defvar generate-autoload-cookie -The value of this variable should be a string whose syntax is a Lisp -comment. @kbd{M-x update-file-autoloads} copies the Lisp form that -follows the cookie into the autoload file it generates. The default -value of this variable is @code{";;;###autoload"}. -@end defvar - -@defvar generated-autoload-file -The value of this variable names an Emacs Lisp file where the autoload -calls should go. The default value is @file{loaddefs.el}, but you can -override that, e.g., in the ``Local Variables'' section of a -@file{.el} file (@pxref{File Local Variables}). The autoload file is -assumed to contain a trailer starting with a formfeed character. -@end defvar - - The following function may be used to explicitly load the library -specified by an autoload object: - -@defun autoload-do-load autoload &optional name macro-only -This function performs the loading specified by @var{autoload}, which -should be an autoload object. The optional argument @var{name}, if -non-@code{nil}, should be a symbol whose function value is -@var{autoload}; in that case, the return value of this function is the -symbol's new function value. If the value of the optional argument -@var{macro-only} is @code{macro}, this function avoids loading a -function, only a macro. -@end defun - -@node Repeated Loading -@section Repeated Loading -@cindex repeated loading - - You can load a given file more than once in an Emacs session. For -example, after you have rewritten and reinstalled a function definition -by editing it in a buffer, you may wish to return to the original -version; you can do this by reloading the file it came from. - - When you load or reload files, bear in mind that the @code{load} and -@code{load-library} functions automatically load a byte-compiled file -rather than a non-compiled file of similar name. If you rewrite a file -that you intend to save and reinstall, you need to byte-compile the new -version; otherwise Emacs will load the older, byte-compiled file instead -of your newer, non-compiled file! If that happens, the message -displayed when loading the file includes, @samp{(compiled; note, source is -newer)}, to remind you to recompile it. - - When writing the forms in a Lisp library file, keep in mind that the -file might be loaded more than once. For example, think about whether -each variable should be reinitialized when you reload the library; -@code{defvar} does not change the value if the variable is already -initialized. (@xref{Defining Variables}.) - - The simplest way to add an element to an alist is like this: - -@example -(push '(leif-mode " Leif") minor-mode-alist) -@end example - -@noindent -But this would add multiple elements if the library is reloaded. To -avoid the problem, use @code{add-to-list} (@pxref{List Variables}): - -@example -(add-to-list 'minor-mode-alist '(leif-mode " Leif")) -@end example - - Occasionally you will want to test explicitly whether a library has -already been loaded. If the library uses @code{provide} to provide a -named feature, you can use @code{featurep} earlier in the file to test -whether the @code{provide} call has been executed before (@pxref{Named -Features}). Alternatively, you could use something like this: - -@example -(defvar foo-was-loaded nil) - -(unless foo-was-loaded - @var{execute-first-time-only} - (setq foo-was-loaded t)) -@end example - -@noindent - -@node Named Features -@section Features -@cindex features -@cindex requiring features -@cindex providing features - - @code{provide} and @code{require} are an alternative to -@code{autoload} for loading files automatically. They work in terms of -named @dfn{features}. Autoloading is triggered by calling a specific -function, but a feature is loaded the first time another program asks -for it by name. - - A feature name is a symbol that stands for a collection of functions, -variables, etc. The file that defines them should @dfn{provide} the -feature. Another program that uses them may ensure they are defined by -@dfn{requiring} the feature. This loads the file of definitions if it -hasn't been loaded already. - -@cindex load error with require - To require the presence of a feature, call @code{require} with the -feature name as argument. @code{require} looks in the global variable -@code{features} to see whether the desired feature has been provided -already. If not, it loads the feature from the appropriate file. This -file should call @code{provide} at the top level to add the feature to -@code{features}; if it fails to do so, @code{require} signals an error. - - For example, in @file{idlwave.el}, the definition for -@code{idlwave-complete-filename} includes the following code: - -@example -(defun idlwave-complete-filename () - "Use the comint stuff to complete a file name." - (require 'comint) - (let* ((comint-file-name-chars "~/A-Za-z0-9+@@:_.$#%=@{@}\\-") - (comint-completion-addsuffix nil) - ...) - (comint-dynamic-complete-filename))) -@end example - -@noindent -The expression @code{(require 'comint)} loads the file @file{comint.el} -if it has not yet been loaded, ensuring that -@code{comint-dynamic-complete-filename} is defined. Features are -normally named after the files that provide them, so that -@code{require} need not be given the file name. (Note that it is -important that the @code{require} statement be outside the body of the -@code{let}. Loading a library while its variables are let-bound can -have unintended consequences, namely the variables becoming unbound -after the let exits.) - -The @file{comint.el} file contains the following top-level expression: - -@example -(provide 'comint) -@end example - -@noindent -This adds @code{comint} to the global @code{features} list, so that -@code{(require 'comint)} will henceforth know that nothing needs to be -done. - -@cindex byte-compiling @code{require} - When @code{require} is used at top level in a file, it takes effect -when you byte-compile that file (@pxref{Byte Compilation}) as well as -when you load it. This is in case the required package contains macros -that the byte compiler must know about. It also avoids byte compiler -warnings for functions and variables defined in the file loaded with -@code{require}. - - Although top-level calls to @code{require} are evaluated during -byte compilation, @code{provide} calls are not. Therefore, you can -ensure that a file of definitions is loaded before it is byte-compiled -by including a @code{provide} followed by a @code{require} for the same -feature, as in the following example. - -@example -@group -(provide 'my-feature) ; @r{Ignored by byte compiler,} - ; @r{evaluated by @code{load}.} -(require 'my-feature) ; @r{Evaluated by byte compiler.} -@end group -@end example - -@noindent -The compiler ignores the @code{provide}, then processes the -@code{require} by loading the file in question. Loading the file does -execute the @code{provide} call, so the subsequent @code{require} call -does nothing when the file is loaded. - -@defun provide feature &optional subfeatures -This function announces that @var{feature} is now loaded, or being -loaded, into the current Emacs session. This means that the facilities -associated with @var{feature} are or will be available for other Lisp -programs. - -The direct effect of calling @code{provide} is if not already in -@var{features} then to add @var{feature} to the front of that list and -call any @code{eval-after-load} code waiting for it (@pxref{Hooks for -Loading}). The argument @var{feature} must be a symbol. -@code{provide} returns @var{feature}. - -If provided, @var{subfeatures} should be a list of symbols indicating -a set of specific subfeatures provided by this version of -@var{feature}. You can test the presence of a subfeature using -@code{featurep}. The idea of subfeatures is that you use them when a -package (which is one @var{feature}) is complex enough to make it -useful to give names to various parts or functionalities of the -package, which might or might not be loaded, or might or might not be -present in a given version. @xref{Network Feature Testing}, for -an example. - -@example -features - @result{} (bar bish) - -(provide 'foo) - @result{} foo -features - @result{} (foo bar bish) -@end example - -When a file is loaded to satisfy an autoload, and it stops due to an -error in the evaluation of its contents, any function definitions or -@code{provide} calls that occurred during the load are undone. -@xref{Autoload}. -@end defun - -@defun require feature &optional filename noerror -This function checks whether @var{feature} is present in the current -Emacs session (using @code{(featurep @var{feature})}; see below). The -argument @var{feature} must be a symbol. - -If the feature is not present, then @code{require} loads @var{filename} -with @code{load}. If @var{filename} is not supplied, then the name of -the symbol @var{feature} is used as the base file name to load. -However, in this case, @code{require} insists on finding @var{feature} -with an added @samp{.el} or @samp{.elc} suffix (possibly extended with -a compression suffix); a file whose name is just @var{feature} won't -be used. (The variable @code{load-suffixes} specifies the exact -required Lisp suffixes.) - -If @var{noerror} is non-@code{nil}, that suppresses errors from actual -loading of the file. In that case, @code{require} returns @code{nil} -if loading the file fails. Normally, @code{require} returns -@var{feature}. - -If loading the file succeeds but does not provide @var{feature}, -@code{require} signals an error, @samp{Required feature @var{feature} -was not provided}. -@end defun - -@defun featurep feature &optional subfeature -This function returns @code{t} if @var{feature} has been provided in -the current Emacs session (i.e., if @var{feature} is a member of -@code{features}.) If @var{subfeature} is non-@code{nil}, then the -function returns @code{t} only if that subfeature is provided as well -(i.e., if @var{subfeature} is a member of the @code{subfeature} -property of the @var{feature} symbol.) -@end defun - -@defvar features -The value of this variable is a list of symbols that are the features -loaded in the current Emacs session. Each symbol was put in this list -with a call to @code{provide}. The order of the elements in the -@code{features} list is not significant. -@end defvar - -@node Where Defined -@section Which File Defined a Certain Symbol - -@defun symbol-file symbol &optional type -This function returns the name of the file that defined @var{symbol}. -If @var{type} is @code{nil}, then any kind of definition is acceptable. -If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that -specifies function definition, variable definition, or face definition -only. - -The value is normally an absolute file name. It can also be @code{nil}, -if the definition is not associated with any file. If @var{symbol} -specifies an autoloaded function, the value can be a relative file name -without extension. -@end defun - - The basis for @code{symbol-file} is the data in the variable -@code{load-history}. - -@defvar load-history -The value of this variable is an alist that associates the names of -loaded library files with the names of the functions and variables -they defined, as well as the features they provided or required. - -Each element in this alist describes one loaded library (including -libraries that are preloaded at startup). It is a list whose @sc{car} -is the absolute file name of the library (a string). The rest of the -list elements have these forms: - -@table @code -@item @var{var} -The symbol @var{var} was defined as a variable. -@item (defun . @var{fun}) -The function @var{fun} was defined. -@item (t . @var{fun}) -The function @var{fun} was previously an autoload before this library -redefined it as a function. The following element is always -@code{(defun . @var{fun})}, which represents defining @var{fun} as a -function. -@item (autoload . @var{fun}) -The function @var{fun} was defined as an autoload. -@item (defface . @var{face}) -The face @var{face} was defined. -@item (require . @var{feature}) -The feature @var{feature} was required. -@item (provide . @var{feature}) -The feature @var{feature} was provided. -@end table - -The value of @code{load-history} may have one element whose @sc{car} is -@code{nil}. This element describes definitions made with -@code{eval-buffer} on a buffer that is not visiting a file. -@end defvar - - The command @code{eval-region} updates @code{load-history}, but does so -by adding the symbols defined to the element for the file being visited, -rather than replacing that element. @xref{Eval}. - -@node Unloading -@section Unloading -@cindex unloading packages - -@c Emacs 19 feature - You can discard the functions and variables loaded by a library to -reclaim memory for other Lisp objects. To do this, use the function -@code{unload-feature}: - -@deffn Command unload-feature feature &optional force -This command unloads the library that provided feature @var{feature}. -It undefines all functions, macros, and variables defined in that -library with @code{defun}, @code{defalias}, @code{defsubst}, -@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}. -It then restores any autoloads formerly associated with those symbols. -(Loading saves these in the @code{autoload} property of the symbol.) - -Before restoring the previous definitions, @code{unload-feature} runs -@code{remove-hook} to remove functions in the library from certain -hooks. These hooks include variables whose names end in @samp{-hook} -(or the deprecated suffix @samp{-hooks}), plus those listed in -@code{unload-feature-special-hooks}, as well as -@code{auto-mode-alist}. This is to prevent Emacs from ceasing to -function because important hooks refer to functions that are no longer -defined. - -Standard unloading activities also undoes ELP profiling of functions -in that library, unprovides any features provided by the library, and -cancels timers held in variables defined by the library. - -@vindex @var{feature}-unload-function -If these measures are not sufficient to prevent malfunction, a library -can define an explicit unloader named @code{@var{feature}-unload-function}. -If that symbol is defined as a function, @code{unload-feature} calls -it with no arguments before doing anything else. It can do whatever -is appropriate to unload the library. If it returns @code{nil}, -@code{unload-feature} proceeds to take the normal unload actions. -Otherwise it considers the job to be done. - -Ordinarily, @code{unload-feature} refuses to unload a library on which -other loaded libraries depend. (A library @var{a} depends on library -@var{b} if @var{a} contains a @code{require} for @var{b}.) If the -optional argument @var{force} is non-@code{nil}, dependencies are -ignored and you can unload any library. -@end deffn - - The @code{unload-feature} function is written in Lisp; its actions are -based on the variable @code{load-history}. - -@defvar unload-feature-special-hooks -This variable holds a list of hooks to be scanned before unloading a -library, to remove functions defined in the library. -@end defvar - -@node Hooks for Loading -@section Hooks for Loading -@cindex loading hooks -@cindex hooks for loading - -You can ask for code to be executed each time Emacs loads a library, -by using the variable @code{after-load-functions}: - -@defvar after-load-functions -This abnormal hook is run after loading a file. Each function in the -hook is called with a single argument, the absolute filename of the -file that was just loaded. -@end defvar - -If you want code to be executed when a @emph{particular} library is -loaded, use the macro @code{with-eval-after-load}: - -@defmac with-eval-after-load library body@dots{} -This macro arranges to evaluate @var{body} at the end of loading -the file @var{library}, each time @var{library} is loaded. If -@var{library} is already loaded, it evaluates @var{body} right away. - -You don't need to give a directory or extension in the file name -@var{library}. Normally, you just give a bare file name, like this: - -@example -(with-eval-after-load "edebug" (def-edebug-spec c-point t)) -@end example - -To restrict which files can trigger the evaluation, include a -directory or an extension or both in @var{library}. Only a file whose -absolute true name (i.e., the name with all symbolic links chased out) -matches all the given name components will match. In the following -example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory -@code{..../foo/bar} will trigger the evaluation, but not -@file{my_inst.el}: - -@example -(with-eval-after-load "foo/bar/my_inst.elc" @dots{}) -@end example - -@var{library} can also be a feature (i.e., a symbol), in which case -@var{body} is evaluated at the end of any file where -@code{(provide @var{library})} is called. - -An error in @var{body} does not undo the load, but does prevent -execution of the rest of @var{body}. -@end defmac - -Normally, well-designed Lisp programs should not use -@code{eval-after-load}. If you need to examine and set the variables -defined in another library (those meant for outside use), you can do -it immediately---there is no need to wait until the library is loaded. -If you need to call functions defined by that library, you should load -the library, preferably with @code{require} (@pxref{Named Features}). diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi deleted file mode 100644 index 9be12fa431b..00000000000 --- a/doc/lispref/macros.texi +++ /dev/null @@ -1,632 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998, 2001-2014 Free Software Foundation, -@c Inc. -@c See the file elisp.texi for copying conditions. -@node Macros -@chapter Macros -@cindex macros - - @dfn{Macros} enable you to define new control constructs and other -language features. A macro is defined much like a function, but instead -of telling how to compute a value, it tells how to compute another Lisp -expression which will in turn compute the value. We call this -expression the @dfn{expansion} of the macro. - - Macros can do this because they operate on the unevaluated expressions -for the arguments, not on the argument values as functions do. They can -therefore construct an expansion containing these argument expressions -or parts of them. - - If you are using a macro to do something an ordinary function could -do, just for the sake of speed, consider using an inline function -instead. @xref{Inline Functions}. - -@menu -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. -@end menu - -@node Simple Macro -@section A Simple Example of a Macro - - Suppose we would like to define a Lisp construct to increment a -variable value, much like the @code{++} operator in C@. We would like to -write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}. -Here's a macro definition that does the job: - -@findex inc -@example -@group -(defmacro inc (var) - (list 'setq var (list '1+ var))) -@end group -@end example - - When this is called with @code{(inc x)}, the argument @var{var} is the -symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would -be in a function. The body of the macro uses this to construct the -expansion, which is @code{(setq x (1+ x))}. Once the macro definition -returns this expansion, Lisp proceeds to evaluate it, thus incrementing -@code{x}. - -@defun macrop object -This predicate tests whether its argument is a macro, and returns -@code{t} if so, @code{nil} otherwise. -@end defun - -@node Expansion -@section Expansion of a Macro Call -@cindex expansion of macros -@cindex macro call - - A macro call looks just like a function call in that it is a list which -starts with the name of the macro. The rest of the elements of the list -are the arguments of the macro. - - Evaluation of the macro call begins like evaluation of a function call -except for one crucial difference: the macro arguments are the actual -expressions appearing in the macro call. They are not evaluated before -they are given to the macro definition. By contrast, the arguments of a -function are results of evaluating the elements of the function call -list. - - Having obtained the arguments, Lisp invokes the macro definition just -as a function is invoked. The argument variables of the macro are bound -to the argument values from the macro call, or to a list of them in the -case of a @code{&rest} argument. And the macro body executes and -returns its value just as a function body does. - - The second crucial difference between macros and functions is that -the value returned by the macro body is an alternate Lisp expression, -also known as the @dfn{expansion} of the macro. The Lisp interpreter -proceeds to evaluate the expansion as soon as it comes back from the -macro. - - Since the expansion is evaluated in the normal manner, it may contain -calls to other macros. It may even be a call to the same macro, though -this is unusual. - - Note that Emacs tries to expand macros when loading an uncompiled -Lisp file. This is not always possible, but if it is, it speeds up -subsequent execution. @xref{How Programs Do Loading}. - - You can see the expansion of a given macro call by calling -@code{macroexpand}. - -@defun macroexpand form &optional environment -@cindex macro expansion -This function expands @var{form}, if it is a macro call. If the result -is another macro call, it is expanded in turn, until something which is -not a macro call results. That is the value returned by -@code{macroexpand}. If @var{form} is not a macro call to begin with, it -is returned as given. - -Note that @code{macroexpand} does not look at the subexpressions of -@var{form} (although some macro definitions may do so). Even if they -are macro calls themselves, @code{macroexpand} does not expand them. - -The function @code{macroexpand} does not expand calls to inline functions. -Normally there is no need for that, since a call to an inline function is -no harder to understand than a call to an ordinary function. - -If @var{environment} is provided, it specifies an alist of macro -definitions that shadow the currently defined macros. Byte compilation -uses this feature. - -@example -@group -(defmacro inc (var) - (list 'setq var (list '1+ var))) -@end group - -@group -(macroexpand '(inc r)) - @result{} (setq r (1+ r)) -@end group - -@group -(defmacro inc2 (var1 var2) - (list 'progn (list 'inc var1) (list 'inc var2))) -@end group - -@group -(macroexpand '(inc2 r s)) - @result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.} -@end group -@end example -@end defun - - -@defun macroexpand-all form &optional environment -@code{macroexpand-all} expands macros like @code{macroexpand}, but -will look for and expand all macros in @var{form}, not just at the -top-level. If no macros are expanded, the return value is @code{eq} -to @var{form}. - -Repeating the example used for @code{macroexpand} above with -@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does} -expand the embedded calls to @code{inc}: - -@example -(macroexpand-all '(inc2 r s)) - @result{} (progn (setq r (1+ r)) (setq s (1+ s))) -@end example - -@end defun - -@node Compiling Macros -@section Macros and Byte Compilation -@cindex byte-compiling macros - - You might ask why we take the trouble to compute an expansion for a -macro and then evaluate the expansion. Why not have the macro body -produce the desired results directly? The reason has to do with -compilation. - - When a macro call appears in a Lisp program being compiled, the Lisp -compiler calls the macro definition just as the interpreter would, and -receives an expansion. But instead of evaluating this expansion, it -compiles the expansion as if it had appeared directly in the program. -As a result, the compiled code produces the value and side effects -intended for the macro, but executes at full compiled speed. This would -not work if the macro body computed the value and side effects -itself---they would be computed at compile time, which is not useful. - - In order for compilation of macro calls to work, the macros must -already be defined in Lisp when the calls to them are compiled. The -compiler has a special feature to help you do this: if a file being -compiled contains a @code{defmacro} form, the macro is defined -temporarily for the rest of the compilation of that file. - - Byte-compiling a file also executes any @code{require} calls at -top-level in the file, so you can ensure that necessary macro -definitions are available during compilation by requiring the files -that define them (@pxref{Named Features}). To avoid loading the macro -definition files when someone @emph{runs} the compiled program, write -@code{eval-when-compile} around the @code{require} calls (@pxref{Eval -During Compile}). - -@node Defining Macros -@section Defining Macros - - A Lisp macro object is a list whose @sc{car} is @code{macro}, and -whose @sc{cdr} is a function. Expansion of the macro works -by applying the function (with @code{apply}) to the list of -@emph{unevaluated} arguments from the macro call. - - It is possible to use an anonymous Lisp macro just like an anonymous -function, but this is never done, because it does not make sense to -pass an anonymous macro to functionals such as @code{mapcar}. In -practice, all Lisp macros have names, and they are almost always -defined with the @code{defmacro} macro. - -@defmac defmacro name args [doc] [declare] body@dots{} -@code{defmacro} defines the symbol @var{name} (which should not be -quoted) as a macro that looks like this: - -@example -(macro lambda @var{args} . @var{body}) -@end example - -(Note that the @sc{cdr} of this list is a lambda expression.) This -macro object is stored in the function cell of @var{name}. The -meaning of @var{args} is the same as in a function, and the keywords -@code{&rest} and @code{&optional} may be used (@pxref{Argument List}). -Neither @var{name} nor @var{args} should be quoted. The return value -of @code{defmacro} is undefined. - -@var{doc}, if present, should be a string specifying the macro's -documentation string. @var{declare}, if present, should be a -@code{declare} form specifying metadata for the macro (@pxref{Declare -Form}). Note that macros cannot have interactive declarations, since -they cannot be called interactively. -@end defmac - - Macros often need to construct large list structures from a mixture -of constants and nonconstant parts. To make this easier, use the -@samp{`} syntax (@pxref{Backquote}). For example: - -@example -@example -@group -(defmacro t-becomes-nil (variable) - `(if (eq ,variable t) - (setq ,variable nil))) -@end group - -@group -(t-becomes-nil foo) - @equiv{} (if (eq foo t) (setq foo nil)) -@end group -@end example -@end example - - The body of a macro definition can include a @code{declare} form, -which specifies additional properties about the macro. @xref{Declare -Form}. - -@node Problems with Macros -@section Common Problems Using Macros - - Macro expansion can have counterintuitive consequences. This -section describes some important consequences that can lead to -trouble, and rules to follow to avoid trouble. - -@menu -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. -@end menu - -@node Wrong Time -@subsection Wrong Time - - The most common problem in writing macros is doing some of the -real work prematurely---while expanding the macro, rather than in the -expansion itself. For instance, one real package had this macro -definition: - -@example -(defmacro my-set-buffer-multibyte (arg) - (if (fboundp 'set-buffer-multibyte) - (set-buffer-multibyte arg))) -@end example - -With this erroneous macro definition, the program worked fine when -interpreted but failed when compiled. This macro definition called -@code{set-buffer-multibyte} during compilation, which was wrong, and -then did nothing when the compiled package was run. The definition -that the programmer really wanted was this: - -@example -(defmacro my-set-buffer-multibyte (arg) - (if (fboundp 'set-buffer-multibyte) - `(set-buffer-multibyte ,arg))) -@end example - -@noindent -This macro expands, if appropriate, into a call to -@code{set-buffer-multibyte} that will be executed when the compiled -program is actually run. - -@node Argument Evaluation -@subsection Evaluating Macro Arguments Repeatedly - - When defining a macro you must pay attention to the number of times -the arguments will be evaluated when the expansion is executed. The -following macro (used to facilitate iteration) illustrates the -problem. This macro allows us to write a ``for'' loop construct. - -@findex for -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - (list 'let (list (list var init)) - (cons 'while - (cons (list '<= var final) - (append body (list (list 'inc var))))))) -@end group - -@group -(for i from 1 to 3 do - (setq square (* i i)) - (princ (format "\n%d %d" i square))) -@expansion{} -@end group -@group -(let ((i 1)) - (while (<= i 3) - (setq square (* i i)) - (princ (format "\n%d %d" i square)) - (inc i))) -@end group -@group - - @print{}1 1 - @print{}2 4 - @print{}3 9 -@result{} nil -@end group -@end example - -@noindent -The arguments @code{from}, @code{to}, and @code{do} in this macro are -``syntactic sugar''; they are entirely ignored. The idea is that you -will write noise words (such as @code{from}, @code{to}, and @code{do}) -in those positions in the macro call. - -Here's an equivalent definition simplified through use of backquote: - -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - `(let ((,var ,init)) - (while (<= ,var ,final) - ,@@body - (inc ,var)))) -@end group -@end example - -Both forms of this definition (with backquote and without) suffer from -the defect that @var{final} is evaluated on every iteration. If -@var{final} is a constant, this is not a problem. If it is a more -complex form, say @code{(long-complex-calculation x)}, this can slow -down the execution significantly. If @var{final} has side effects, -executing it more than once is probably incorrect. - -@cindex macro argument evaluation -A well-designed macro definition takes steps to avoid this problem by -producing an expansion that evaluates the argument expressions exactly -once unless repeated evaluation is part of the intended purpose of the -macro. Here is a correct expansion for the @code{for} macro: - -@example -@group -(let ((i 1) - (max 3)) - (while (<= i max) - (setq square (* i i)) - (princ (format "%d %d" i square)) - (inc i))) -@end group -@end example - -Here is a macro definition that creates this expansion: - -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." - `(let ((,var ,init) - (max ,final)) - (while (<= ,var max) - ,@@body - (inc ,var)))) -@end group -@end example - - Unfortunately, this fix introduces another problem, -described in the following section. - -@node Surprising Local Vars -@subsection Local Variables in Macro Expansions - -@ifnottex - In the previous section, the definition of @code{for} was fixed as -follows to make the expansion evaluate the macro arguments the proper -number of times: - -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." -@end group -@group - `(let ((,var ,init) - (max ,final)) - (while (<= ,var max) - ,@@body - (inc ,var)))) -@end group -@end example -@end ifnottex - - The new definition of @code{for} has a new problem: it introduces a -local variable named @code{max} which the user does not expect. This -causes trouble in examples such as the following: - -@example -@group -(let ((max 0)) - (for x from 0 to 10 do - (let ((this (frob x))) - (if (< max this) - (setq max this))))) -@end group -@end example - -@noindent -The references to @code{max} inside the body of the @code{for}, which -are supposed to refer to the user's binding of @code{max}, really access -the binding made by @code{for}. - -The way to correct this is to use an uninterned symbol instead of -@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be -bound and referred to just like any other symbol, but since it is -created by @code{for}, we know that it cannot already appear in the -user's program. Since it is not interned, there is no way the user can -put it into the program later. It will never appear anywhere except -where put by @code{for}. Here is a definition of @code{for} that works -this way: - -@example -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." - (let ((tempvar (make-symbol "max"))) - `(let ((,var ,init) - (,tempvar ,final)) - (while (<= ,var ,tempvar) - ,@@body - (inc ,var))))) -@end group -@end example - -@noindent -This creates an uninterned symbol named @code{max} and puts it in the -expansion instead of the usual interned symbol @code{max} that appears -in expressions ordinarily. - -@node Eval During Expansion -@subsection Evaluating Macro Arguments in Expansion - - Another problem can happen if the macro definition itself -evaluates any of the macro argument expressions, such as by calling -@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the -user's variables, you may have trouble if the user happens to use a -variable with the same name as one of the macro arguments. Inside the -macro body, the macro argument binding is the most local binding of this -variable, so any references inside the form being evaluated do refer to -it. Here is an example: - -@example -@group -(defmacro foo (a) - (list 'setq (eval a) t)) -@end group -@group -(setq x 'b) -(foo x) @expansion{} (setq b t) - @result{} t ; @r{and @code{b} has been set.} -;; @r{but} -(setq a 'c) -(foo a) @expansion{} (setq a t) - @result{} t ; @r{but this set @code{a}, not @code{c}.} - -@end group -@end example - - It makes a difference whether the user's variable is named @code{a} or -@code{x}, because @code{a} conflicts with the macro argument variable -@code{a}. - - Another problem with calling @code{eval} in a macro definition is that -it probably won't do what you intend in a compiled program. The -byte compiler runs macro definitions while compiling the program, when -the program's own computations (which you might have wished to access -with @code{eval}) don't occur and its local variable bindings don't -exist. - - To avoid these problems, @strong{don't evaluate an argument expression -while computing the macro expansion}. Instead, substitute the -expression into the macro expansion, so that its value will be computed -as part of executing the expansion. This is how the other examples in -this chapter work. - -@node Repeated Expansion -@subsection How Many Times is the Macro Expanded? - - Occasionally problems result from the fact that a macro call is -expanded each time it is evaluated in an interpreted function, but is -expanded only once (during compilation) for a compiled function. If the -macro definition has side effects, they will work differently depending -on how many times the macro is expanded. - - Therefore, you should avoid side effects in computation of the -macro expansion, unless you really know what you are doing. - - One special kind of side effect can't be avoided: constructing Lisp -objects. Almost all macro expansions include constructed lists; that is -the whole point of most macros. This is usually safe; there is just one -case where you must be careful: when the object you construct is part of a -quoted constant in the macro expansion. - - If the macro is expanded just once, in compilation, then the object is -constructed just once, during compilation. But in interpreted -execution, the macro is expanded each time the macro call runs, and this -means a new object is constructed each time. - - In most clean Lisp code, this difference won't matter. It can matter -only if you perform side-effects on the objects constructed by the macro -definition. Thus, to avoid trouble, @strong{avoid side effects on -objects constructed by macro definitions}. Here is an example of how -such side effects can get you into trouble: - -@lisp -@group -(defmacro empty-object () - (list 'quote (cons nil nil))) -@end group - -@group -(defun initialize (condition) - (let ((object (empty-object))) - (if condition - (setcar object condition)) - object)) -@end group -@end lisp - -@noindent -If @code{initialize} is interpreted, a new list @code{(nil)} is -constructed each time @code{initialize} is called. Thus, no side effect -survives between calls. If @code{initialize} is compiled, then the -macro @code{empty-object} is expanded during compilation, producing a -single ``constant'' @code{(nil)} that is reused and altered each time -@code{initialize} is called. - -One way to avoid pathological cases like this is to think of -@code{empty-object} as a funny kind of constant, not as a memory -allocation construct. You wouldn't use @code{setcar} on a constant such -as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)} -either. - -@node Indenting Macros -@section Indenting Macros - - Within a macro definition, you can use the @code{declare} form -(@pxref{Defining Macros}) to specify how @key{TAB} should indent -calls to the macro. An indentation specification is written like this: - -@example -(declare (indent @var{indent-spec})) -@end example - -@noindent -Here are the possibilities for @var{indent-spec}: - -@table @asis -@item @code{nil} -This is the same as no property---use the standard indentation pattern. -@item @code{defun} -Handle this function like a @samp{def} construct: treat the second -line as the start of a @dfn{body}. -@item an integer, @var{number} -The first @var{number} arguments of the function are -@dfn{distinguished} arguments; the rest are considered the body -of the expression. A line in the expression is indented according to -whether the first argument on it is distinguished or not. If the -argument is part of the body, the line is indented @code{lisp-body-indent} -more columns than the open-parenthesis starting the containing -expression. If the argument is distinguished and is either the first -or second argument, it is indented @emph{twice} that many extra columns. -If the argument is distinguished and not the first or second argument, -the line uses the standard pattern. -@item a symbol, @var{symbol} -@var{symbol} should be a function name; that function is called to -calculate the indentation of a line within this expression. The -function receives two arguments: - -@table @asis -@item @var{pos} -The position at which the line being indented begins. -@item @var{state} -The value returned by @code{parse-partial-sexp} (a Lisp primitive for -indentation and nesting computation) when it parses up to the -beginning of this line. -@end table - -@noindent -It should return either a number, which is the number of columns of -indentation for that line, or a list whose car is such a number. The -difference between returning a number and returning a list is that a -number says that all following lines at the same nesting level should -be indented just like this one; a list says that following lines might -call for different indentations. This makes a difference when the -indentation is being computed by @kbd{C-M-q}; if the value is a -number, @kbd{C-M-q} need not recalculate indentation for the following -lines until the end of the list. -@end table diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in deleted file mode 100644 index 01fe14944fd..00000000000 --- a/doc/lispref/makefile.w32-in +++ /dev/null @@ -1,128 +0,0 @@ -# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual. - -# Copyright (C) 2003-2014 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -# Standard configure variables. -srcdir = . - -infodir = $(srcdir)/../../info - -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -INFO_EXT=.info -INFO_OPTS=--no-split - -# Redefine `TEX' if `tex' does not invoke plain TeX. For example: -# TEX=platex -TEX=tex -INSTALL_INFO = install-info -MAKEINFO = makeinfo -MAKEINFO_OPTS = --force --enable-encoding -I$(srcdir) -I$(emacsdir) - -# The environment variable and its value to add $(srcdir) to the path -# searched for TeX input files. -texinputdir = $(srcdir)\..\..\nt\envadd.bat \ - "TEXINPUTS=$(srcdir);$(texinfodir);$(emacsdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) $(MAKEINFO_OPTS)" /C - -# List of all the texinfo files in the manual: - -srcs = \ - $(emacsdir)/emacsver.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/backups.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/compile.texi \ - $(srcdir)/control.texi \ - $(srcdir)/customize.texi \ - $(srcdir)/debugging.texi \ - $(srcdir)/display.texi \ - $(srcdir)/edebug.texi \ - $(srcdir)/elisp.texi \ - $(srcdir)/errors.texi \ - $(srcdir)/eval.texi \ - $(srcdir)/files.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/functions.texi \ - $(srcdir)/hash.texi \ - $(srcdir)/help.texi \ - $(srcdir)/hooks.texi \ - $(srcdir)/internals.texi \ - $(srcdir)/intro.texi \ - $(srcdir)/keymaps.texi \ - $(srcdir)/lists.texi \ - $(srcdir)/loading.texi \ - $(srcdir)/macros.texi \ - $(srcdir)/maps.texi \ - $(srcdir)/markers.texi \ - $(srcdir)/minibuf.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/nonascii.texi \ - $(srcdir)/numbers.texi \ - $(srcdir)/objects.texi \ - $(srcdir)/os.texi \ - $(srcdir)/package.texi \ - $(srcdir)/positions.texi \ - $(srcdir)/processes.texi \ - $(srcdir)/searching.texi \ - $(srcdir)/sequences.texi \ - $(srcdir)/streams.texi \ - $(srcdir)/strings.texi \ - $(srcdir)/symbols.texi \ - $(srcdir)/syntax.texi \ - $(srcdir)/text.texi \ - $(srcdir)/tips.texi \ - $(srcdir)/variables.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/index.texi \ - $(srcdir)/gpl.texi \ - $(srcdir)/doclicense.texi - - -.PHONY: clean - -# The info file is named `elisp'. - -info: $(infodir)/elisp$(INFO_EXT) - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp - -$(infodir)/elisp$(INFO_EXT): $(srcs) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $(srcdir)/elisp.texi - -elisp.dvi: $(srcs) - $(texinputdir) $(TEX) $(srcdir)/elisp.texi - -clean: - - $(DEL) *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ - *.vr *.vrs *.pg *.pgs *.ky *.kys - - $(DEL) make.out core - - $(DEL) $(infodir)/elisp* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) elisp$(INFO_EXT) elisp$(INFO_EXT)-? elisp$(INFO_EXT)-?? elisp.dvi elisp.oaux diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi deleted file mode 100644 index 14cbe72f67e..00000000000 --- a/doc/lispref/maps.texi +++ /dev/null @@ -1,199 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2014 Free Software Foundation, -@c Inc. -@c See the file elisp.texi for copying conditions. -@node Standard Keymaps -@appendix Standard Keymaps -@cindex keymaps, standard - -In this section we list some of the more general keymaps. Many of -these exist when Emacs is first started, but some are loaded only when -the respective feature is accessed. - -There are many other, more specialized, maps than these; in particular -those associated with major and minor modes. The minibuffer uses -several keymaps (@pxref{Completion Commands}). For more details on -keymaps, @pxref{Keymaps}. - -@c Don't list individual major mode keymaps here, only more general things. -@c Only add vindex for things not covered elsewhere in this manual. -@c Don't add xrefs to things covered in {Keymaps}. -@table @code -@item 2C-mode-map -A sparse keymap for subcommands of the prefix @kbd{C-x 6}.@* -@xref{Two-Column,, Two-Column Editing, emacs, The GNU Emacs Manual}. - -@item abbrev-map -@vindex abbrev-map -A sparse keymap for subcommands of the prefix @kbd{C-x a}.@* -@xref{Defining Abbrevs,,, emacs, The GNU Emacs Manual}. - -@item button-buffer-map -A sparse keymap useful for buffers containing buffers.@* -You may want to use this as a parent keymap. @xref{Buttons}. - -@item button-map -A sparse keymap used by buttons. - -@item ctl-x-4-map -A sparse keymap for subcommands of the prefix @kbd{C-x 4}. - -@item ctl-x-5-map -A sparse keymap for subcommands of the prefix @kbd{C-x 5}. - -@item ctl-x-map -A full keymap for @kbd{C-x} commands. - -@item ctl-x-r-map -@vindex ctl-x-r-map -A sparse keymap for subcommands of the prefix @kbd{C-x r}.@* -@xref{Registers,,, emacs, The GNU Emacs Manual}. - -@item esc-map -A full keymap for @kbd{ESC} (or @kbd{Meta}) commands. - -@item facemenu-keymap -A sparse keymap used for the @kbd{M-o} prefix key. - -@item function-key-map -The parent keymap of all @code{local-function-key-map} (q.v.@:) instances. - -@ignore -@c Doesn't exist. -@item fundamental-mode-map -@vindex fundamental-mode-map -The sparse keymap for Fundamental mode.@* -It is empty and should not be changed. -@end ignore - -@item global-map -The full keymap containing default global key bindings.@* -Modes should not modify the Global map. - -@item goto-map -A sparse keymap used for the @kbd{M-g} prefix key. - -@item help-map -A sparse keymap for the keys following the help character @kbd{C-h}.@* -@xref{Help Functions}. - -@item Helper-help-map -A full keymap used by the help utility package.@* -It has the same keymap in its value cell and in its function cell. - -@item input-decode-map -The keymap for translating keypad and function keys.@* -If there are none, then it contains an empty sparse keymap. -@xref{Translation Keymaps}. - -@item key-translation-map -A keymap for translating keys. This one overrides ordinary key -bindings, unlike @code{local-function-key-map}. @xref{Translation -Keymaps}. - -@item kmacro-keymap -@vindex kmacro-keymap -A sparse keymap for keys that follows the @kbd{C-x C-k} prefix search.@* -@xref{Keyboard Macros,,, emacs, The GNU Emacs Manual}. - -@item local-function-key-map -The keymap for translating key sequences to preferred alternatives.@* -If there are none, then it contains an empty sparse keymap. -@xref{Translation Keymaps}. - -@item menu-bar-file-menu -@itemx menu-bar-edit-menu -@itemx menu-bar-options-menu -@itemx global-buffers-menu-map -@itemx menu-bar-tools-menu -@itemx menu-bar-help-menu -@cindex menu bar keymaps -@vindex menu-bar-file-menu -@vindex menu-bar-options-menu -@vindex global-buffers-menu-map -@vindex menu-bar-tools-menu -@vindex menu-bar-help-menu -These keymaps display the main, top-level menus in the menu bar.@* -Some of them contain sub-menus. For example, the Edit menu contains -@code{menu-bar-search-menu}, etc. @xref{Menu Bar}. -@ignore -TODO list all submenus? -There are probably too many, and it would not be useful to do so, e.g.: -The Edit menu includes @code{yank-menu}, @code{menu-bar-search-menu}, -@code{menu-bar-replace-menu}, @code{menu-bar-goto-menu}, -@code{menu-bar-bookmark-map}, and @code{facemenu-menu}. -There is also mule-menu-keymap, set-coding-system-map, -setup-language-environment-map, describe-language-environment-map, -menu-bar-epatch-menu, menu-bar-ediff-merge-menu, menu-bar-ediff-menu, etc. -@end ignore - -@item minibuffer-inactive-mode-map -A full keymap used in the minibuffer when it is not active.@* -@xref{Minibuffer Edit,, Editing in the Minibuffer, emacs, The GNU Emacs Manual}. - -@item mode-line-coding-system-map -@itemx mode-line-input-method-map -@itemx mode-line-column-line-number-mode-map -@vindex mode-line-coding-system-map -@vindex mode-line-input-method-map -@vindex mode-line-column-line-number-mode-map -These keymaps control various areas of the mode line.@* -@xref{Mode Line Format}. - -@item mode-specific-map -The keymap for characters following @kbd{C-c}. Note, this is in the -global map. This map is not actually mode-specific: its name was chosen -to be informative in @kbd{C-h b} (@code{display-bindings}), -where it describes the main use of the @kbd{C-c} prefix key. - -@c FIXME - don't mention this one? -@item mouse-appearance-menu-map -@vindex mouse-appearance-menu-map -A sparse keymap used for the @kbd{S-mouse-1} key. - -@item mule-keymap -The global keymap used for the @kbd{C-x @key{RET}} prefix key. - -@item narrow-map -@vindex narrow-map -A sparse keymap for subcommands of the prefix @kbd{C-x n}. - -@item prog-mode-map -The keymap used by Prog mode.@* -@xref{Basic Major Modes}. - -@item query-replace-map -@itemx multi-query-replace-map -A sparse keymap used for responses in @code{query-replace} and related -commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions -that use this map do not support prefix keys; they look up one event at a -time. @code{multi-query-replace-map} extends @code{query-replace-map} -for multi-buffer replacements. @xref{Search and Replace, query-replace-map}. - -@item search-map -A sparse keymap that provides global bindings for search-related commands. - -@item special-mode-map -The keymap used by Special mode.@* -@xref{Basic Major Modes}. - -@item tool-bar-map -The keymap defining the contents of the tool bar.@* -@xref{Tool Bar}. - -@item universal-argument-map -@vindex universal-argument-map -A sparse keymap used while processing @kbd{C-u}.@* -@xref{Prefix Command Arguments}. - -@item vc-prefix-map -The global keymap used for the @kbd{C-x v} prefix key. - -@item x-alternatives-map -@vindex x-alternatives-map -@findex x-setup-function-keys -A sparse keymap used to map certain keys under graphical frames.@* -The function @code{x-setup-function-keys} uses this. - -@end table diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi deleted file mode 100644 index 51b87ab1e5b..00000000000 --- a/doc/lispref/markers.texi +++ /dev/null @@ -1,708 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Markers -@chapter Markers -@cindex markers - - A @dfn{marker} is a Lisp object used to specify a position in a buffer -relative to the surrounding text. A marker changes its offset from the -beginning of the buffer automatically whenever text is inserted or -deleted, so that it stays with the two characters on either side of it. - -@menu -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers:: Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". -@end menu - -@node Overview of Markers -@section Overview of Markers - - A marker specifies a buffer and a position in that buffer. A -marker can be used to represent a position in functions that -require one, just as an integer could be used. In that case, the -marker's buffer is normally ignored. Of course, a marker used in this -way usually points to a position in the buffer that the function -operates on, but that is entirely the programmer's responsibility. -@xref{Positions}, for a complete description of positions. - - A marker has three attributes: the marker position, the marker -buffer, and the insertion type. The marker position is an integer -that is equivalent (at a given time) to the marker as a position in -that buffer. But the marker's position value can change during -the life of the marker, and often does. Insertion and deletion of -text in the buffer relocate the marker. The idea is that a marker -positioned between two characters remains between those two characters -despite insertion and deletion elsewhere in the buffer. Relocation -changes the integer equivalent of the marker. - -@cindex marker relocation - Deleting text around a marker's position leaves the marker between the -characters immediately before and after the deleted text. Inserting -text at the position of a marker normally leaves the marker either in -front of or after the new text, depending on the marker's @dfn{insertion -type} (@pxref{Marker Insertion Types})---unless the insertion is done -with @code{insert-before-markers} (@pxref{Insertion}). - -@cindex marker garbage collection - Insertion and deletion in a buffer must check all the markers and -relocate them if necessary. This slows processing in a buffer with a -large number of markers. For this reason, it is a good idea to make a -marker point nowhere if you are sure you don't need it any more. -Markers that can no longer be accessed are eventually removed -(@pxref{Garbage Collection}). - -@cindex markers as numbers - Because it is common to perform arithmetic operations on a marker -position, most of these operations (including @code{+} and -@code{-}) accept markers as arguments. In such cases, the marker -stands for its current position. - -Here are examples of creating markers, setting markers, and moving point -to markers: - -@example -@group -;; @r{Make a new marker that initially does not point anywhere:} -(setq m1 (make-marker)) - @result{} # -@end group - -@group -;; @r{Set @code{m1} to point between the 99th and 100th characters} -;; @r{in the current buffer:} -(set-marker m1 100) - @result{} # -@end group - -@group -;; @r{Now insert one character at the beginning of the buffer:} -(goto-char (point-min)) - @result{} 1 -(insert "Q") - @result{} nil -@end group - -@group -;; @r{@code{m1} is updated appropriately.} -m1 - @result{} # -@end group - -@group -;; @r{Two markers that point to the same position} -;; @r{are not @code{eq}, but they are @code{equal}.} -(setq m2 (copy-marker m1)) - @result{} # -(eq m1 m2) - @result{} nil -(equal m1 m2) - @result{} t -@end group - -@group -;; @r{When you are finished using a marker, make it point nowhere.} -(set-marker m1 nil) - @result{} # -@end group -@end example - -@node Predicates on Markers -@section Predicates on Markers - - You can test an object to see whether it is a marker, or whether it is -either an integer or a marker. The latter test is useful in connection -with the arithmetic functions that work with both markers and integers. - -@defun markerp object -This function returns @code{t} if @var{object} is a marker, @code{nil} -otherwise. Note that integers are not markers, even though many -functions will accept either a marker or an integer. -@end defun - -@defun integer-or-marker-p object -This function returns @code{t} if @var{object} is an integer or a marker, -@code{nil} otherwise. -@end defun - -@defun number-or-marker-p object -This function returns @code{t} if @var{object} is a number (either -integer or floating point) or a marker, @code{nil} otherwise. -@end defun - -@node Creating Markers -@section Functions that Create Markers - - When you create a new marker, you can make it point nowhere, or point -to the present position of point, or to the beginning or end of the -accessible portion of the buffer, or to the same place as another given -marker. - -The next four functions all return markers with insertion type -@code{nil}. @xref{Marker Insertion Types}. - -@defun make-marker -This function returns a newly created marker that does not point -anywhere. - -@example -@group -(make-marker) - @result{} # -@end group -@end example -@end defun - -@defun point-marker -This function returns a new marker that points to the present position -of point in the current buffer. @xref{Point}. For an example, see -@code{copy-marker}, below. -@end defun - -@defun point-min-marker -This function returns a new marker that points to the beginning of the -accessible portion of the buffer. This will be the beginning of the -buffer unless narrowing is in effect. @xref{Narrowing}. -@end defun - -@defun point-max-marker -This function returns a new marker that points to the end of the -accessible portion of the buffer. This will be the end of the buffer -unless narrowing is in effect. @xref{Narrowing}. - -Here are examples of this function and @code{point-min-marker}, shown in -a buffer containing a version of the source file for the text of this -chapter. - -@example -@group -(point-min-marker) - @result{} # -(point-max-marker) - @result{} # -@end group - -@group -(narrow-to-region 100 200) - @result{} nil -@end group -@group -(point-min-marker) - @result{} # -@end group -@group -(point-max-marker) - @result{} # -@end group -@end example -@end defun - -@defun copy-marker &optional marker-or-integer insertion-type -If passed a marker as its argument, @code{copy-marker} returns a -new marker that points to the same place and the same buffer as does -@var{marker-or-integer}. If passed an integer as its argument, -@code{copy-marker} returns a new marker that points to position -@var{marker-or-integer} in the current buffer. - -The new marker's insertion type is specified by the argument -@var{insertion-type}. @xref{Marker Insertion Types}. - -@c This behavior used to be documented until 2013/08. -@ignore -If passed an integer argument less than 1, @code{copy-marker} returns a -new marker that points to the beginning of the current buffer. If -passed an integer argument greater than the length of the buffer, -@code{copy-marker} returns a new marker that points to the end of the -buffer. -@end ignore - -@example -@group -(copy-marker 0) - @result{} # -@end group - -@group -(copy-marker 90000) - @result{} # -@end group -@end example - -An error is signaled if @var{marker} is neither a marker nor an -integer. -@end defun - - Two distinct markers are considered @code{equal} (even though not -@code{eq}) to each other if they have the same position and buffer, or -if they both point nowhere. - -@example -@group -(setq p (point-marker)) - @result{} # -@end group - -@group -(setq q (copy-marker p)) - @result{} # -@end group - -@group -(eq p q) - @result{} nil -@end group - -@group -(equal p q) - @result{} t -@end group -@end example - -@node Information from Markers -@section Information from Markers - - This section describes the functions for accessing the components of a -marker object. - -@defun marker-position marker -This function returns the position that @var{marker} points to, or -@code{nil} if it points nowhere. -@end defun - -@defun marker-buffer marker -This function returns the buffer that @var{marker} points into, or -@code{nil} if it points nowhere. - -@c FIXME: The `buffer' argument of `set-marker' already defaults to -@c the current buffer, why use `(current-buffer)' explicitly here? -@example -@group -(setq m (make-marker)) - @result{} # -@end group -@group -(marker-position m) - @result{} nil -@end group -@group -(marker-buffer m) - @result{} nil -@end group - -@group -(set-marker m 3770 (current-buffer)) - @result{} # -@end group -@group -(marker-buffer m) - @result{} # -@end group -@group -(marker-position m) - @result{} 3770 -@end group -@end example -@end defun - -@node Marker Insertion Types -@section Marker Insertion Types - -@cindex insertion type of a marker - When you insert text directly at the place where a marker points, -there are two possible ways to relocate that marker: it can point before -the inserted text, or point after it. You can specify which one a given -marker should do by setting its @dfn{insertion type}. Note that use of -@code{insert-before-markers} ignores markers' insertion types, always -relocating a marker to point after the inserted text. - -@defun set-marker-insertion-type marker type -This function sets the insertion type of marker @var{marker} to -@var{type}. If @var{type} is @code{t}, @var{marker} will advance when -text is inserted at its position. If @var{type} is @code{nil}, -@var{marker} does not advance when text is inserted there. -@end defun - -@defun marker-insertion-type marker -This function reports the current insertion type of @var{marker}. -@end defun - -Most functions that create markers, without an argument allowing to -specify the insertion type, create them with insertion type -@code{nil}. Also, the mark has, by default, insertion type -@code{nil}. - -@node Moving Markers -@section Moving Marker Positions - - This section describes how to change the position of an existing -marker. When you do this, be sure you know whether the marker is used -outside of your program, and, if so, what effects will result from -moving it---otherwise, confusing things may happen in other parts of -Emacs. - -@defun set-marker marker position &optional buffer -This function moves @var{marker} to @var{position} -in @var{buffer}. If @var{buffer} is not provided, it defaults to -the current buffer. - -@c This behavior used to be documented until 2013/08. -@ignore -If @var{position} is less than 1, @code{set-marker} moves @var{marker} -to the beginning of the buffer. If @var{position} is greater than the -size of the buffer (@pxref{Point}), @code{set-marker} moves marker to -the end of the buffer. -@end ignore -If @var{position} is @code{nil} or a marker that points nowhere, then -@var{marker} is set to point nowhere. - -The value returned is @var{marker}. - -@example -@group -(setq m (point-marker)) - @result{} # -@end group -@group -(set-marker m 55) - @result{} # -@end group -@group -(setq b (get-buffer "foo")) - @result{} # -@end group -@group -(set-marker m 0 b) - @result{} # -@end group -@end example -@end defun - -@defun move-marker marker position &optional buffer -This is another name for @code{set-marker}. -@end defun - -@node The Mark -@section The Mark -@cindex mark, the -@c @cindex the mark? - - Each buffer has a special marker, which is designated @dfn{the -mark}. When a buffer is newly created, this marker exists but does -not point anywhere; this means that the mark ``doesn't exist'' in that -buffer yet. Subsequent commands can set the mark. - - The mark specifies a position to bound a range of text for many -commands, such as @code{kill-region} and @code{indent-rigidly}. These -commands typically act on the text between point and the mark, which -is called the @dfn{region}. If you are writing a command that -operates on the region, don't examine the mark directly; instead, use -@code{interactive} with the @samp{r} specification. This provides the -values of point and the mark as arguments to the command in an -interactive call, but permits other Lisp programs to specify arguments -explicitly. @xref{Interactive Codes}. - - Some commands set the mark as a side-effect. Commands should do -this only if it has a potential use to the user, and never for their -own internal purposes. For example, the @code{replace-regexp} command -sets the mark to the value of point before doing any replacements, -because this enables the user to move back there conveniently after -the replace is finished. - - Once the mark ``exists'' in a buffer, it normally never ceases to -exist. However, it may become @dfn{inactive}, if Transient Mark mode -is enabled. The buffer-local variable @code{mark-active}, if -non-@code{nil}, means that the mark is active. A command can call the -function @code{deactivate-mark} to deactivate the mark directly, or it -can request deactivation of the mark upon return to the editor command -loop by setting the variable @code{deactivate-mark} to a -non-@code{nil} value. - - If Transient Mark mode is enabled, certain editing commands that -normally apply to text near point, apply instead to the region when -the mark is active. This is the main motivation for using Transient -Mark mode. (Another is that this enables highlighting of the region -when the mark is active. @xref{Display}.) - -@cindex mark ring - In addition to the mark, each buffer has a @dfn{mark ring} which is a -list of markers containing previous values of the mark. When editing -commands change the mark, they should normally save the old value of the -mark on the mark ring. The variable @code{mark-ring-max} specifies the -maximum number of entries in the mark ring; once the list becomes this -long, adding a new element deletes the last element. - - There is also a separate global mark ring, but that is used only in a -few particular user-level commands, and is not relevant to Lisp -programming. So we do not describe it here. - -@defun mark &optional force -@cindex current buffer mark -This function returns the current buffer's mark position as an integer, -or @code{nil} if no mark has ever been set in this buffer. - -If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is -@code{nil}, @code{mark} signals an error if the mark is inactive. -However, if @var{force} is non-@code{nil}, then @code{mark} disregards -inactivity of the mark, and returns the mark position (or @code{nil}) -anyway. -@end defun - -@defun mark-marker -This function returns the marker that represents the current buffer's -mark. It is not a copy, it is the marker used internally. Therefore, -changing this marker's position will directly affect the buffer's -mark. Don't do that unless that is the effect you want. - -@example -@group -(setq m (mark-marker)) - @result{} # -@end group -@group -(set-marker m 100) - @result{} # -@end group -@group -(mark-marker) - @result{} # -@end group -@end example - -Like any marker, this marker can be set to point at any buffer you -like. If you make it point at any buffer other than the one of which -it is the mark, it will yield perfectly consistent, but rather odd, -results. We recommend that you not do it! -@end defun - -@defun set-mark position -This function sets the mark to @var{position}, and activates the mark. -The old value of the mark is @emph{not} pushed onto the mark ring. - -@strong{Please note:} Use this function only if you want the user to -see that the mark has moved, and you want the previous mark position to -be lost. Normally, when a new mark is set, the old one should go on the -@code{mark-ring}. For this reason, most applications should use -@code{push-mark} and @code{pop-mark}, not @code{set-mark}. - -Novice Emacs Lisp programmers often try to use the mark for the wrong -purposes. The mark saves a location for the user's convenience. An -editing command should not alter the mark unless altering the mark is -part of the user-level functionality of the command. (And, in that -case, this effect should be documented.) To remember a location for -internal use in the Lisp program, store it in a Lisp variable. For -example: - -@example -@group -(let ((beg (point))) - (forward-line 1) - (delete-region beg (point))). -@end group -@end example -@end defun - -@defun push-mark &optional position nomsg activate -This function sets the current buffer's mark to @var{position}, and -pushes a copy of the previous mark onto @code{mark-ring}. If -@var{position} is @code{nil}, then the value of point is used. -@c Doesn't seem relevant. -@c @code{push-mark} returns @code{nil}. - -The function @code{push-mark} normally @emph{does not} activate the -mark. To do that, specify @code{t} for the argument @var{activate}. - -A @samp{Mark set} message is displayed unless @var{nomsg} is -non-@code{nil}. -@end defun - -@defun pop-mark -This function pops off the top element of @code{mark-ring} and makes -that mark become the buffer's actual mark. This does not move point in -the buffer, and it does nothing if @code{mark-ring} is empty. It -deactivates the mark. -@c -@c Seems even less relevant. -@c The return value is not meaningful. -@end defun - -@defopt transient-mark-mode -This variable, if non-@code{nil}, enables Transient Mark mode. In -Transient Mark mode, every buffer-modifying primitive sets -@code{deactivate-mark}. As a consequence, most commands that modify -the buffer also deactivate the mark. - -When Transient Mark mode is enabled and the mark is active, many -commands that normally apply to the text near point instead apply to -the region. Such commands should use the function @code{use-region-p} -to test whether they should operate on the region. @xref{The Region}. - -Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, -non-@code{t} values to enable Transient Mark mode temporarily. If the -value is @code{lambda}, Transient Mark mode is automatically turned -off after any action, such as buffer modification, that would normally -deactivate the mark. If the value is @w{@code{(only . @var{oldval})}}, -then @code{transient-mark-mode} is set to the value @var{oldval} after -any subsequent command that moves point and is not shift-translated -(@pxref{Key Sequence Input, shift-translation}), or after any other -action that would normally deactivate the mark. -@end defopt - -@defopt mark-even-if-inactive -If this is non-@code{nil}, Lisp programs and the Emacs user can use the -mark even when it is inactive. This option affects the behavior of -Transient Mark mode. When the option is non-@code{nil}, deactivation of -the mark turns off region highlighting, but commands that use the mark -behave as if the mark were still active. -@end defopt - -@defvar deactivate-mark -If an editor command sets this variable non-@code{nil}, then the editor -command loop deactivates the mark after the command returns (if -Transient Mark mode is enabled). All the primitives that change the -buffer set @code{deactivate-mark}, to deactivate the mark when the -command is finished. - -To write Lisp code that modifies the buffer without causing -deactivation of the mark at the end of the command, bind -@code{deactivate-mark} to @code{nil} around the code that does the -modification. For example: - -@example -(let (deactivate-mark) - (insert " ")) -@end example -@end defvar - -@defun deactivate-mark &optional force -If Transient Mark mode is enabled or @var{force} is non-@code{nil}, -this function deactivates the mark and runs the normal hook -@code{deactivate-mark-hook}. Otherwise, it does nothing. -@end defun - -@defvar mark-active -The mark is active when this variable is non-@code{nil}. This -variable is always buffer-local in each buffer. Do @emph{not} use the -value of this variable to decide whether a command that normally -operates on text near point should operate on the region instead. Use -the function @code{use-region-p} for that (@pxref{The Region}). -@end defvar - -@defvar activate-mark-hook -@defvarx deactivate-mark-hook -These normal hooks are run, respectively, when the mark becomes active -and when it becomes inactive. The hook @code{activate-mark-hook} is -also run at the end of the command loop if the mark is active and it -is possible that the region may have changed. -@ignore -This piece of command_loop_1, run unless deactivating the mark: - if (current_buffer != prev_buffer || MODIFF != prev_modiff) - { - Lisp_Object hook = intern ("activate-mark-hook"); - Frun_hooks (1, &hook); - } -@end ignore -@end defvar - -@defun handle-shift-selection -This function implements the ``shift-selection'' behavior of -point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs -Manual}. It is called automatically by the Emacs command loop -whenever a command with a @samp{^} character in its @code{interactive} -spec is invoked, before the command itself is executed -(@pxref{Interactive Codes, ^}). - -If @code{shift-select-mode} is non-@code{nil} and the current command -was invoked via shift translation (@pxref{Key Sequence Input, -shift-translation}), this function sets the mark and temporarily -activates the region, unless the region was already temporarily -activated in this way. Otherwise, if the region has been activated -temporarily, it deactivates the mark and restores the variable -@code{transient-mark-mode} to its earlier value. -@end defun - -@defvar mark-ring -The value of this buffer-local variable is the list of saved former -marks of the current buffer, most recent first. - -@example -@group -mark-ring -@result{} (# - # - @dots{}) -@end group -@end example -@end defvar - -@defopt mark-ring-max -The value of this variable is the maximum size of @code{mark-ring}. If -more marks than this are pushed onto the @code{mark-ring}, -@code{push-mark} discards an old mark when it adds a new one. -@end defopt - -@c There is also global-mark-ring-max, but this chapter explicitly -@c does not talk about the global mark. - -@node The Region -@section The Region -@c The index entry must be just ``region'' to make it the first hit -@c when the user types ``i region RET'', because otherwise the Info -@c reader will present substring matches in alphabetical order, -@c putting this one near the end, with something utterly unrelated as -@c the first hit. -@cindex region - - The text between point and the mark is known as @dfn{the region}. -Various functions operate on text delimited by point and the mark, but -only those functions specifically related to the region itself are -described here. - -The next two functions signal an error if the mark does not point -anywhere. If Transient Mark mode is enabled and -@code{mark-even-if-inactive} is @code{nil}, they also signal an error -if the mark is inactive. - -@defun region-beginning -This function returns the position of the beginning of the region (as -an integer). This is the position of either point or the mark, -whichever is smaller. -@end defun - -@defun region-end -This function returns the position of the end of the region (as an -integer). This is the position of either point or the mark, whichever is -larger. -@end defun - -@c FIXME: Mention it in tips.texi? - Instead of using @code{region-beginning} and @code{region-end}, a -command designed to operate on a region should normally use -@code{interactive} with the @samp{r} specification to find the -beginning and end of the region. This lets other Lisp programs -specify the bounds explicitly as arguments. @xref{Interactive Codes}. - -@defun use-region-p -This function returns @code{t} if Transient Mark mode is enabled, the -mark is active, and there is a valid region in the buffer. This -function is intended to be used by commands that operate on the -region, instead of on text near point, when the mark is active. - -@cindex empty region -@vindex use-empty-active-region -A region is valid if it has a non-zero size, or if the user option -@code{use-empty-active-region} is non-@code{nil} (by default, it is -@code{nil}). The function @code{region-active-p} is similar to -@code{use-region-p}, but considers all regions as valid. In most -cases, you should not use @code{region-active-p}, since if the region -is empty it is often more appropriate to operate on point. -@end defun - diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi deleted file mode 100644 index 4a94f41d732..00000000000 --- a/doc/lispref/minibuf.texi +++ /dev/null @@ -1,2371 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Minibuffers -@chapter Minibuffers -@cindex arguments, reading -@cindex complex arguments -@cindex minibuffer - - A @dfn{minibuffer} is a special buffer that Emacs commands use to -read arguments more complicated than the single numeric prefix -argument. These arguments include file names, buffer names, and -command names (as in @kbd{M-x}). The minibuffer is displayed on the -bottom line of the frame, in the same place as the echo area -(@pxref{The Echo Area}), but only while it is in use for reading an -argument. - -@menu -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. -@end menu - -@node Intro to Minibuffers -@section Introduction to Minibuffers - - In most ways, a minibuffer is a normal Emacs buffer. Most operations -@emph{within} a buffer, such as editing commands, work normally in a -minibuffer. However, many operations for managing buffers do not apply -to minibuffers. The name of a minibuffer always has the form @w{@samp{ -*Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are -displayed only in special windows used only for minibuffers; these -windows always appear at the bottom of a frame. (Sometimes frames have -no minibuffer window, and sometimes a special kind of frame contains -nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) - - The text in the minibuffer always starts with the @dfn{prompt string}, -the text that was specified by the program that is using the minibuffer -to tell the user what sort of input to type. This text is marked -read-only so you won't accidentally delete or change it. It is also -marked as a field (@pxref{Fields}), so that certain motion functions, -including @code{beginning-of-line}, @code{forward-word}, -@code{forward-sentence}, and @code{forward-paragraph}, stop at the -boundary between the prompt and the actual text. - -@c See http://debbugs.gnu.org/11276 - The minibuffer's window is normally a single line; it grows -automatically if the contents require more space. Whilst it is -active, you can explicitly resize it temporarily with the window -sizing commands; it reverts to its normal size when the minibuffer is -exited. When the minibuffer is not active, you can resize it -permanently by using the window sizing commands in the frame's other -window, or dragging the mode line with the mouse. (Due to details of -the current implementation, for this to work @code{resize-mini-windows} -must be @code{nil}.) If the frame contains just a minibuffer, you can -change the minibuffer's size by changing the frame's size. - - Use of the minibuffer reads input events, and that alters the values -of variables such as @code{this-command} and @code{last-command} -(@pxref{Command Loop Info}). Your program should bind them around the -code that uses the minibuffer, if you do not want that to change them. - - Under some circumstances, a command can use a minibuffer even if -there is an active minibuffer; such a minibuffer is called a -@dfn{recursive minibuffer}. The first minibuffer is named -@w{@samp{ *Minibuf-1*}}. Recursive minibuffers are named by -incrementing the number at the end of the name. (The names begin with -a space so that they won't show up in normal buffer lists.) Of -several recursive minibuffers, the innermost (or most recently -entered) is the active minibuffer. We usually call this ``the'' -minibuffer. You can permit or forbid recursive minibuffers by setting -the variable @code{enable-recursive-minibuffers}, or by putting -properties of that name on command symbols (@xref{Recursive Mini}.) - - Like other buffers, a minibuffer uses a local keymap -(@pxref{Keymaps}) to specify special key bindings. The function that -invokes the minibuffer also sets up its local map according to the job -to be done. @xref{Text from Minibuffer}, for the non-completion -minibuffer local maps. @xref{Completion Commands}, for the minibuffer -local maps for completion. - -@cindex inactive minibuffer - When a minibuffer is inactive, its major mode is -@code{minibuffer-inactive-mode}, with keymap -@code{minibuffer-inactive-mode-map}. This is only really useful if -the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. - - When Emacs is running in batch mode, any request to read from the -minibuffer actually reads a line from the standard input descriptor that -was supplied when Emacs was started. This supports only basic input: -none of the special minibuffer features (history, completion, -password hiding, etc.) are available in batch mode. - -@node Text from Minibuffer -@section Reading Text Strings with the Minibuffer - - The most basic primitive for minibuffer input is -@code{read-from-minibuffer}, which can be used to read either a string -or a Lisp object in textual form. The function @code{read-regexp} is -used for reading regular expressions (@pxref{Regular Expressions}), -which are a special kind of string. There are also specialized -functions for reading commands, variables, file names, etc.@: -(@pxref{Completion}). - - In most cases, you should not call minibuffer input functions in the -middle of a Lisp function. Instead, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} -specification. @xref{Defining Commands}. - -@defun read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method -This function is the most general way to get input from the -minibuffer. By default, it accepts arbitrary text and returns it as a -string; however, if @var{read} is non-@code{nil}, then it uses -@code{read} to convert the text into a Lisp object (@pxref{Input -Functions}). - -The first thing this function does is to activate a minibuffer and -display it with @var{prompt} (which must be a string) as the -prompt. Then the user can edit text in the minibuffer. - -When the user types a command to exit the minibuffer, -@code{read-from-minibuffer} constructs the return value from the text in -the minibuffer. Normally it returns a string containing that text. -However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer} -reads the text and returns the resulting Lisp object, unevaluated. -(@xref{Input Functions}, for information about reading.) - -The argument @var{default} specifies default values to make available -through the history commands. It should be a string, a list of -strings, or @code{nil}. The string or strings become the minibuffer's -``future history'', available to the user with @kbd{M-n}. - -If @var{read} is non-@code{nil}, then @var{default} is also used -as the input to @code{read}, if the user enters empty input. -If @var{default} is a list of strings, the first string is used as the input. -If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error. -However, in the usual case (where @var{read} is @code{nil}), -@code{read-from-minibuffer} ignores @var{default} when the user enters -empty input and returns an empty string, @code{""}. In this respect, -it differs from all the other minibuffer input functions in this chapter. - -If @var{keymap} is non-@code{nil}, that keymap is the local keymap to -use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the -value of @code{minibuffer-local-map} is used as the keymap. Specifying -a keymap is the most important way to customize the minibuffer for -various applications such as completion. - -The argument @var{history} specifies a history list variable to use -for saving the input and for history commands used in the minibuffer. -It defaults to @code{minibuffer-history}. You can optionally specify -a starting position in the history list as well. @xref{Minibuffer History}. - -If the variable @code{minibuffer-allow-text-properties} is -non-@code{nil}, then the string that is returned includes whatever text -properties were present in the minibuffer. Otherwise all the text -properties are stripped when the value is returned. - -If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current input method (@pxref{Input Methods}) and -the setting of @code{enable-multibyte-characters} (@pxref{Text -Representations}) from whichever buffer was current before entering the -minibuffer. - -Use of @var{initial} is mostly deprecated; we recommend using -a non-@code{nil} value only in conjunction with specifying a cons cell -for @var{history}. @xref{Initial Input}. -@end defun - -@defun read-string prompt &optional initial history default inherit-input-method -This function reads a string from the minibuffer and returns it. The -arguments @var{prompt}, @var{initial}, @var{history} and -@var{inherit-input-method} are used as in @code{read-from-minibuffer}. -The keymap used is @code{minibuffer-local-map}. - -The optional argument @var{default} is used as in -@code{read-from-minibuffer}, except that, if non-@code{nil}, it also -specifies a default value to return if the user enters null input. As -in @code{read-from-minibuffer} it should be a string, a list of -strings, or @code{nil}, which is equivalent to an empty string. When -@var{default} is a string, that string is the default value. When it -is a list of strings, the first string is the default value. (All -these strings are available to the user in the ``future minibuffer -history''.) - -This function works by calling the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit}) -@equiv{} -(let ((value - (read-from-minibuffer @var{prompt} @var{initial} nil nil - @var{history} @var{default} @var{inherit}))) - (if (and (equal value "") @var{default}) - (if (consp @var{default}) (car @var{default}) @var{default}) - value)) -@end group -@end smallexample -@end defun - -@defun read-regexp prompt &optional defaults history -This function reads a regular expression as a string from the -minibuffer and returns it. If the minibuffer prompt string -@var{prompt} does not end in @samp{:} (followed by optional -whitespace), the function adds @samp{: } to the end, preceded by the -default return value (see below), if that is non-empty. - -The optional argument @var{defaults} controls the default value to -return if the user enters null input, and should be one of: a string; -@code{nil}, which is equivalent to an empty string; a list of strings; -or a symbol. - -If @var{defaults} is a symbol, @code{read-regexp} consults the value -of the variable @code{read-regexp-defaults-function} (see below), and -if that is non-@code{nil} uses it in preference to @var{defaults}. -The value in this case should be either: - -@itemize @minus -@item -@code{regexp-history-last}, which means to use the first element of -the appropriate minibuffer history list (see below). - -@item -A function of no arguments, whose return value (which should be -@code{nil}, a string, or a list of strings) becomes the value of -@var{defaults}. -@end itemize - -@code{read-regexp} now ensures that the result of processing -@var{defaults} is a list (i.e., if the value is @code{nil} or a -string, it converts it to a list of one element). To this list, -@code{read-regexp} then appends a few potentially useful candidates for -input. These are: - -@itemize @minus -@item -The word or symbol at point. -@item -The last regexp used in an incremental search. -@item -The last string used in an incremental search. -@item -The last string or pattern used in query-replace commands. -@end itemize - -The function now has a list of regular expressions that it passes to -@code{read-from-minibuffer} to obtain the user's input. The first -element of the list is the default result in case of empty input. All -elements of the list are available to the user as the ``future -minibuffer history list'' (@pxref{Minibuffer History, future list,, -emacs, The GNU Emacs Manual}). - -The optional argument @var{history}, if non-@code{nil}, is a symbol -specifying a minibuffer history list to use (@pxref{Minibuffer -History}). If it is omitted or @code{nil}, the history list defaults -to @code{regexp-history}. -@end defun - -@defvar read-regexp-defaults-function -The function @code{read-regexp} may use the value of this variable to -determine its list of default regular expressions. If non-@code{nil}, -the value of this variable should be either: - -@itemize @minus -@item -The symbol @code{regexp-history-last}. - -@item -A function of no arguments that returns either @code{nil}, a string, -or a list of strings. -@end itemize - -@noindent -See @code{read-regexp} above for details of how these values are used. -@end defvar - -@defvar minibuffer-allow-text-properties -If this variable is @code{nil}, then @code{read-from-minibuffer} -and @code{read-string} strip all text properties from the minibuffer -input before returning it. However, -@code{read-no-blanks-input} (see below), as well as -@code{read-minibuffer} and related functions (@pxref{Object from -Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all -functions that do minibuffer input with completion, discard text -properties unconditionally, regardless of the value of this variable. -@end defvar - -@defvar minibuffer-local-map -This -@anchor{Definition of minibuffer-local-map} -@c avoid page break at anchor; work around Texinfo deficiency -is the default local keymap for reading from the minibuffer. By -default, it makes the following bindings: - -@table @asis -@item @kbd{C-j} -@code{exit-minibuffer} - -@item @key{RET} -@code{exit-minibuffer} - -@item @kbd{C-g} -@code{abort-recursive-edit} - -@item @kbd{M-n} -@itemx @key{DOWN} -@code{next-history-element} - -@item @kbd{M-p} -@itemx @key{UP} -@code{previous-history-element} - -@item @kbd{M-s} -@code{next-matching-history-element} - -@item @kbd{M-r} -@code{previous-matching-history-element} - -@ignore -@c Does not seem worth/appropriate mentioning. -@item @kbd{C-@key{TAB}} -@code{file-cache-minibuffer-complete} -@end ignore -@end table -@end defvar - -@c In version 18, initial is required -@c Emacs 19 feature -@defun read-no-blanks-input prompt &optional initial inherit-input-method -This function reads a string from the minibuffer, but does not allow -whitespace characters as part of the input: instead, those characters -terminate the input. The arguments @var{prompt}, @var{initial}, and -@var{inherit-input-method} are used as in @code{read-from-minibuffer}. - -This is a simplified interface to the @code{read-from-minibuffer} -function, and passes the value of the @code{minibuffer-local-ns-map} -keymap as the @var{keymap} argument for that function. Since the keymap -@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is} -possible to put a space into the string, by quoting it. - -This function discards text properties, regardless of the value of -@code{minibuffer-allow-text-properties}. - -@smallexample -@group -(read-no-blanks-input @var{prompt} @var{initial}) -@equiv{} -(let (minibuffer-allow-text-properties) - (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)) -@end group -@end smallexample -@end defun - -@c Slightly unfortunate name, suggesting it might be related to the -@c Nextstep port... -@defvar minibuffer-local-ns-map -This built-in variable is the keymap used as the minibuffer local keymap -in the function @code{read-no-blanks-input}. By default, it makes the -following bindings, in addition to those of @code{minibuffer-local-map}: - -@table @asis -@item @key{SPC} -@cindex @key{SPC} in minibuffer -@code{exit-minibuffer} - -@item @key{TAB} -@cindex @key{TAB} in minibuffer -@code{exit-minibuffer} - -@item @kbd{?} -@cindex @kbd{?} in minibuffer -@code{self-insert-and-exit} -@end table -@end defvar - -@node Object from Minibuffer -@section Reading Lisp Objects with the Minibuffer - - This section describes functions for reading Lisp objects with the -minibuffer. - -@defun read-minibuffer prompt &optional initial -This function reads a Lisp object using the minibuffer, and returns it -without evaluating it. The arguments @var{prompt} and @var{initial} are -used as in @code{read-from-minibuffer}. - -This is a simplified interface to the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-minibuffer @var{prompt} @var{initial}) -@equiv{} -(let (minibuffer-allow-text-properties) - (read-from-minibuffer @var{prompt} @var{initial} nil t)) -@end group -@end smallexample - -Here is an example in which we supply the string @code{"(testing)"} as -initial input: - -@smallexample -@group -(read-minibuffer - "Enter an expression: " (format "%s" '(testing))) - -;; @r{Here is how the minibuffer is displayed:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Enter an expression: (testing)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -The user can type @key{RET} immediately to use the initial input as a -default, or can edit the input. -@end defun - -@defun eval-minibuffer prompt &optional initial -This function reads a Lisp expression using the minibuffer, evaluates -it, then returns the result. The arguments @var{prompt} and -@var{initial} are used as in @code{read-from-minibuffer}. - -This function simply evaluates the result of a call to -@code{read-minibuffer}: - -@smallexample -@group -(eval-minibuffer @var{prompt} @var{initial}) -@equiv{} -(eval (read-minibuffer @var{prompt} @var{initial})) -@end group -@end smallexample -@end defun - -@defun edit-and-eval-command prompt form -This function reads a Lisp expression in the minibuffer, evaluates it, -then returns the result. The difference between this command and -@code{eval-minibuffer} is that here the initial @var{form} is not -optional and it is treated as a Lisp object to be converted to printed -representation rather than as a string of text. It is printed with -@code{prin1}, so if it is a string, double-quote characters (@samp{"}) -appear in the initial text. @xref{Output Functions}. - -In the following example, we offer the user an expression with initial -text that is already a valid form: - -@smallexample -@group -(edit-and-eval-command "Please edit: " '(forward-word 1)) - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Please edit: (forward-word 1)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -Typing @key{RET} right away would exit the minibuffer and evaluate the -expression, thus moving point forward one word. -@end defun - -@node Minibuffer History -@section Minibuffer History -@cindex minibuffer history -@cindex history list - - A @dfn{minibuffer history list} records previous minibuffer inputs -so the user can reuse them conveniently. It is a variable whose value -is a list of strings (previous inputs), most recent first. - - There are many separate minibuffer history lists, used for different -kinds of inputs. It's the Lisp programmer's job to specify the right -history list for each use of the minibuffer. - - You specify a minibuffer history list with the optional @var{history} -argument to @code{read-from-minibuffer} or @code{completing-read}. -Here are the possible values for it: - -@table @asis -@item @var{variable} -Use @var{variable} (a symbol) as the history list. - -@item (@var{variable} . @var{startpos}) -Use @var{variable} (a symbol) as the history list, and assume that the -initial history position is @var{startpos} (a nonnegative integer). - -Specifying 0 for @var{startpos} is equivalent to just specifying the -symbol @var{variable}. @code{previous-history-element} will display -the most recent element of the history list in the minibuffer. If you -specify a positive @var{startpos}, the minibuffer history functions -behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the -history element currently shown in the minibuffer. - -For consistency, you should also specify that element of the history -as the initial minibuffer contents, using the @var{initial} argument -to the minibuffer input function (@pxref{Initial Input}). -@end table - - If you don't specify @var{history}, then the default history list -@code{minibuffer-history} is used. For other standard history lists, -see below. You can also create your own history list variable; just -initialize it to @code{nil} before the first use. - - Both @code{read-from-minibuffer} and @code{completing-read} add new -elements to the history list automatically, and provide commands to -allow the user to reuse items on the list. The only thing your program -needs to do to use a history list is to initialize it and to pass its -name to the input functions when you wish. But it is safe to modify the -list by hand when the minibuffer input functions are not using it. - - Emacs functions that add a new element to a history list can also -delete old elements if the list gets too long. The variable -@code{history-length} specifies the maximum length for most history -lists. To specify a different maximum length for a particular history -list, put the length in the @code{history-length} property of the -history list symbol. The variable @code{history-delete-duplicates} -specifies whether to delete duplicates in history. - -@defun add-to-history history-var newelt &optional maxelt keep-all -This function adds a new element @var{newelt}, if it isn't the empty -string, to the history list stored in the variable @var{history-var}, -and returns the updated history list. It limits the list length to -the value of @var{maxelt} (if non-@code{nil}) or @code{history-length} -(described below). The possible values of @var{maxelt} have the same -meaning as the values of @code{history-length}. - -Normally, @code{add-to-history} removes duplicate members from the -history list if @code{history-delete-duplicates} is non-@code{nil}. -However, if @var{keep-all} is non-@code{nil}, that says not to remove -duplicates, and to add @var{newelt} to the list even if it is empty. -@end defun - -@defvar history-add-new-input -If the value of this variable is @code{nil}, standard functions that -read from the minibuffer don't add new elements to the history list. -This lets Lisp programs explicitly manage input history by using -@code{add-to-history}. The default value is @code{t}. -@end defvar - -@defopt history-length -The value of this variable specifies the maximum length for all -history lists that don't specify their own maximum lengths. If the -value is @code{t}, that means there is no maximum (don't delete old -elements). If a history list variable's symbol has a non-@code{nil} -@code{history-length} property, it overrides this variable for that -particular history list. -@end defopt - -@defopt history-delete-duplicates -If the value of this variable is @code{t}, that means when adding a -new history element, all previous identical elements are deleted. -@end defopt - - Here are some of the standard minibuffer history list variables: - -@defvar minibuffer-history -The default history list for minibuffer history input. -@end defvar - -@defvar query-replace-history -A history list for arguments to @code{query-replace} (and similar -arguments to other commands). -@end defvar - -@defvar file-name-history -A history list for file-name arguments. -@end defvar - -@defvar buffer-name-history -A history list for buffer-name arguments. -@end defvar - -@defvar regexp-history -A history list for regular expression arguments. -@end defvar - -@defvar extended-command-history -A history list for arguments that are names of extended commands. -@end defvar - -@defvar shell-command-history -A history list for arguments that are shell commands. -@end defvar - -@defvar read-expression-history -A history list for arguments that are Lisp expressions to evaluate. -@end defvar - -@defvar face-name-history -A history list for arguments that are faces. -@end defvar - -@c Less common: coding-system-history, input-method-history, -@c command-history, grep-history, grep-find-history, -@c read-envvar-name-history, setenv-history, yes-or-no-p-history. - -@node Initial Input -@section Initial Input - -Several of the functions for minibuffer input have an argument called -@var{initial}. This is a mostly-deprecated -feature for specifying that the minibuffer should start out with -certain text, instead of empty as usual. - -If @var{initial} is a string, the minibuffer starts out containing the -text of the string, with point at the end, when the user starts to -edit the text. If the user simply types @key{RET} to exit the -minibuffer, it will use the initial input string to determine the -value to return. - -@strong{We discourage use of a non-@code{nil} value for -@var{initial}}, because initial input is an intrusive interface. -History lists and default values provide a much more convenient method -to offer useful default inputs to the user. - -There is just one situation where you should specify a string for an -@var{initial} argument. This is when you specify a cons cell for the -@var{history} argument. @xref{Minibuffer History}. - -@var{initial} can also be a cons cell of the form @code{(@var{string} -. @var{position})}. This means to insert @var{string} in the -minibuffer but put point at @var{position} within the string's text. - -As a historical accident, @var{position} was implemented -inconsistently in different functions. In @code{completing-read}, -@var{position}'s value is interpreted as origin-zero; that is, a value -of 0 means the beginning of the string, 1 means after the first -character, etc. In @code{read-minibuffer}, and the other -non-completion minibuffer input functions that support this argument, -1 means the beginning of the string, 2 means after the first character, -etc. - -Use of a cons cell as the value for @var{initial} arguments is deprecated. - -@node Completion -@section Completion -@cindex completion - - @dfn{Completion} is a feature that fills in the rest of a name -starting from an abbreviation for it. Completion works by comparing the -user's input against a list of valid names and determining how much of -the name is determined uniquely by what the user has typed. For -example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then -@c "This is the sort of English up with which I will not put." -type the first few letters of the name of the buffer to which you wish -to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs -extends the name as far as it can. - - Standard Emacs commands offer completion for names of symbols, files, -buffers, and processes; with the functions in this section, you can -implement completion for other kinds of names. - - The @code{try-completion} function is the basic primitive for -completion: it returns the longest determined completion of a given -initial string, with a given set of strings to match against. - - The function @code{completing-read} provides a higher-level interface -for completion. A call to @code{completing-read} specifies how to -determine the list of valid names. The function then activates the -minibuffer with a local keymap that binds a few keys to commands useful -for completion. Other functions provide convenient simple interfaces -for reading certain kinds of names with completion. - -@menu -* Basic Completion:: Low-level functions for completing strings. -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer names, variable names, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Variables:: Variables controlling completion behavior. -* Programmed Completion:: Writing your own completion function. -* Completion in Buffers:: Completing text in ordinary buffers. -@end menu - -@node Basic Completion -@subsection Basic Completion Functions - - The following completion functions have nothing in themselves to do -with minibuffers. We describe them here to keep them near the -higher-level completion features that do use the minibuffer. - -@defun try-completion string collection &optional predicate -This function returns the longest common substring of all possible -completions of @var{string} in @var{collection}. - -@cindex completion table -@var{collection} is called the @dfn{completion table}. Its value must -be a list of strings or cons cells, an obarray, a hash table, or a -completion function. - -@code{try-completion} compares @var{string} against each of the -permissible completions specified by the completion table. If no -permissible completions match, it returns @code{nil}. If there is -just one matching completion, and the match is exact, it returns -@code{t}. Otherwise, it returns the longest initial sequence common -to all possible matching completions. - -If @var{collection} is an list, the permissible completions are -specified by the elements of the list, each of which should be either -a string, or a cons cell whose @sc{car} is either a string or a symbol -(a symbol is converted to a string using @code{symbol-name}). If the -list contains elements of any other type, those are ignored. - -@cindex obarray in completion -If @var{collection} is an obarray (@pxref{Creating Symbols}), the names -of all symbols in the obarray form the set of permissible completions. - -If @var{collection} is a hash table, then the keys that are strings -are the possible completions. Other keys are ignored. - -You can also use a function as @var{collection}. Then the function is -solely responsible for performing completion; @code{try-completion} -returns whatever this function returns. The function is called with -three arguments: @var{string}, @var{predicate} and @code{nil} (the -third argument is so that the same function can be used -in @code{all-completions} and do the appropriate thing in either -case). @xref{Programmed Completion}. - -If the argument @var{predicate} is non-@code{nil}, then it must be a -function of one argument, unless @var{collection} is a hash table, in -which case it should be a function of two arguments. It is used to -test each possible match, and the match is accepted only if -@var{predicate} returns non-@code{nil}. The argument given to -@var{predicate} is either a string or a cons cell (the @sc{car} of -which is a string) from the alist, or a symbol (@emph{not} a symbol -name) from the obarray. If @var{collection} is a hash table, -@var{predicate} is called with two arguments, the string key and the -associated value. - -In addition, to be acceptable, a completion must also match all the -regular expressions in @code{completion-regexp-list}. (Unless -@var{collection} is a function, in which case that function has to -handle @code{completion-regexp-list} itself.) - -In the first of the following examples, the string @samp{foo} is -matched by three of the alist @sc{car}s. All of the matches begin with -the characters @samp{fooba}, so that is the result. In the second -example, there is only one possible match, and it is exact, so the -return value is @code{t}. - -@smallexample -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) - @result{} "fooba" -@end group - -@group -(try-completion "foo" '(("barfoo" 2) ("foo" 3))) - @result{} t -@end group -@end smallexample - -In the following example, numerous symbols begin with the characters -@samp{forw}, and all of them begin with the word @samp{forward}. In -most of the symbols, this is followed with a @samp{-}, but not in all, -so no more than @samp{forward} can be completed. - -@smallexample -@group -(try-completion "forw" obarray) - @result{} "forward" -@end group -@end smallexample - -Finally, in the following example, only two of the three possible -matches pass the predicate @code{test} (the string @samp{foobaz} is -too short). Both of those begin with the string @samp{foobar}. - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} "foobar" -@end group -@end smallexample -@end defun - -@c Removed obsolete argument nospace. -@defun all-completions string collection &optional predicate -This function returns a list of all possible completions of -@var{string}. The arguments to this function -@c (aside from @var{nospace}) -are the same as those of @code{try-completion}, and it -uses @code{completion-regexp-list} in the same way that -@code{try-completion} does. - -@ignore -The optional argument @var{nospace} is obsolete. If it is -non-@code{nil}, completions that start with a space are ignored unless -@var{string} starts with a space. -@end ignore - -If @var{collection} is a function, it is called with three arguments: -@var{string}, @var{predicate} and @code{t}; then @code{all-completions} -returns whatever the function returns. @xref{Programmed Completion}. - -Here is an example, using the function @code{test} shown in the -example for @code{try-completion}: - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group - -@group -(all-completions - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} ("foobar1" "foobar2") -@end group -@end smallexample -@end defun - -@defun test-completion string collection &optional predicate -@anchor{Definition of test-completion} -This function returns non-@code{nil} if @var{string} is a valid -completion alternative specified by @var{collection} and -@var{predicate}. The arguments are the same as in -@code{try-completion}. For instance, if @var{collection} is a list of -strings, this is true if @var{string} appears in the list and -@var{predicate} is satisfied. - -This function uses @code{completion-regexp-list} in the same -way that @code{try-completion} does. - -If @var{predicate} is non-@code{nil} and if @var{collection} contains -several strings that are equal to each other, as determined by -@code{compare-strings} according to @code{completion-ignore-case}, -then @var{predicate} should accept either all or none of them. -Otherwise, the return value of @code{test-completion} is essentially -unpredictable. - -If @var{collection} is a function, it is called with three arguments, -the values @var{string}, @var{predicate} and @code{lambda}; whatever -it returns, @code{test-completion} returns in turn. -@end defun - -@defun completion-boundaries string collection predicate suffix -This function returns the boundaries of the field on which @var{collection} -will operate, assuming that @var{string} holds the text before point -and @var{suffix} holds the text after point. - -Normally completion operates on the whole string, so for all normal -collections, this will always return @code{(0 . (length -@var{suffix}))}. But more complex completion such as completion on -files is done one field at a time. For example, completion of -@code{"/usr/sh"} will include @code{"/usr/share/"} but not -@code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists. -Also @code{all-completions} on @code{"/usr/sh"} will not include -@code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is -@code{"/usr/sh"} and @var{suffix} is @code{"e/doc"}, -@code{completion-boundaries} will return @code{(5 . 1)} which tells us -that the @var{collection} will only return completion information that -pertains to the area after @code{"/usr/"} and before @code{"/doc"}. -@end defun - -If you store a completion alist in a variable, you should mark the -variable as ``risky'' by giving it a non-@code{nil} -@code{risky-local-variable} property. @xref{File Local Variables}. - -@defvar completion-ignore-case -If the value of this variable is non-@code{nil}, case is not -considered significant in completion. Within @code{read-file-name}, -this variable is overridden by -@code{read-file-name-completion-ignore-case} (@pxref{Reading File -Names}); within @code{read-buffer}, it is overridden by -@code{read-buffer-completion-ignore-case} (@pxref{High-Level -Completion}). -@end defvar - -@defvar completion-regexp-list -This is a list of regular expressions. The completion functions only -consider a completion acceptable if it matches all regular expressions -in this list, with @code{case-fold-search} (@pxref{Searching and Case}) -bound to the value of @code{completion-ignore-case}. -@end defvar - -@defmac lazy-completion-table var fun -This macro provides a way to initialize the variable @var{var} as a -collection for completion in a lazy way, not computing its actual -contents until they are first needed. You use this macro to produce a -value that you store in @var{var}. The actual computation of the -proper value is done the first time you do completion using @var{var}. -It is done by calling @var{fun} with no arguments. The -value @var{fun} returns becomes the permanent value of @var{var}. - -Here is an example: - -@smallexample -(defvar foo (lazy-completion-table foo make-my-alist)) -@end smallexample -@end defmac - -@c FIXME? completion-table-with-context? -@findex completion-table-case-fold -@findex completion-table-in-turn -@findex completion-table-merge -@findex completion-table-subvert -@findex completion-table-with-quoting -@findex completion-table-with-predicate -@findex completion-table-with-terminator -@cindex completion table, modifying -@cindex completion tables, combining -There are several functions that take an existing completion table and -return a modified version. @code{completion-table-case-fold} returns -a case-insensitive table. @code{completion-table-in-turn} and -@code{completion-table-merge} combine multiple input tables in -different ways. @code{completion-table-subvert} alters a table to use -a different initial prefix. @code{completion-table-with-quoting} -returns a table suitable for operating on quoted text. -@code{completion-table-with-predicate} filters a table with a -predicate function. @code{completion-table-with-terminator} adds a -terminating string. - - -@node Minibuffer Completion -@subsection Completion and the Minibuffer -@cindex minibuffer completion -@cindex reading from minibuffer with completion - - This section describes the basic interface for reading from the -minibuffer with completion. - -@defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method -This function reads a string in the minibuffer, assisting the user by -providing completion. It activates the minibuffer with prompt -@var{prompt}, which must be a string. - -The actual completion is done by passing the completion table -@var{collection} and the completion predicate @var{predicate} to the -function @code{try-completion} (@pxref{Basic Completion}). This -happens in certain commands bound in the local keymaps used for -completion. Some of these commands also call @code{test-completion}. -Thus, if @var{predicate} is non-@code{nil}, it should be compatible -with @var{collection} and @code{completion-ignore-case}. -@xref{Definition of test-completion}. - -The value of the optional argument @var{require-match} determines how -the user may exit the minibuffer: - -@itemize @bullet -@item -If @code{nil}, the usual minibuffer exit commands work regardless of -the input in the minibuffer. - -@item -If @code{t}, the usual minibuffer exit commands won't exit unless the -input completes to an element of @var{collection}. - -@item -If @code{confirm}, the user can exit with any input, but is asked for -confirmation if the input is not an element of @var{collection}. - -@item -If @code{confirm-after-completion}, the user can exit with any input, -but is asked for confirmation if the preceding command was a -completion command (i.e., one of the commands in -@code{minibuffer-confirm-exit-commands}) and the resulting input is -not an element of @var{collection}. @xref{Completion Commands}. - -@item -Any other value of @var{require-match} behaves like @code{t}, except -that the exit commands won't exit if it performs completion. -@end itemize - -However, empty input is always permitted, regardless of the value of -@var{require-match}; in that case, @code{completing-read} returns the -first element of @var{default}, if it is a list; @code{""}, if -@var{default} is @code{nil}; or @var{default}. The string or strings -in @var{default} are also available to the user through the history -commands. - -The function @code{completing-read} uses -@code{minibuffer-local-completion-map} as the keymap if -@var{require-match} is @code{nil}, and uses -@code{minibuffer-local-must-match-map} if @var{require-match} is -non-@code{nil}. @xref{Completion Commands}. - -The argument @var{history} specifies which history list variable to use for -saving the input and for minibuffer history commands. It defaults to -@code{minibuffer-history}. @xref{Minibuffer History}. - -The argument @var{initial} is mostly deprecated; we recommend using a -non-@code{nil} value only in conjunction with specifying a cons cell -for @var{history}. @xref{Initial Input}. For default input, use -@var{default} instead. - -If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current input method (@pxref{Input -Methods}) and the setting of @code{enable-multibyte-characters} -(@pxref{Text Representations}) from whichever buffer was current before -entering the minibuffer. - -If the variable @code{completion-ignore-case} is -non-@code{nil}, completion ignores case when comparing the input -against the possible matches. @xref{Basic Completion}. In this mode -of operation, @var{predicate} must also ignore case, or you will get -surprising results. - -Here's an example of using @code{completing-read}: - -@smallexample -@group -(completing-read - "Complete a foo: " - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - nil t "fo") -@end group - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} - ----------- Buffer: Minibuffer ---------- -Complete a foo: fo@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}}, -@code{completing-read} returns @code{barfoo}. - -The @code{completing-read} function binds variables to pass -information to the commands that actually do completion. -They are described in the following section. -@end defun - -@defvar completing-read-function -The value of this variable must be a function, which is called by -@code{completing-read} to actually do its work. It should accept the -same arguments as @code{completing-read}. This can be bound to a -different function to completely override the normal behavior of -@code{completing-read}. -@end defvar - -@node Completion Commands -@subsection Minibuffer Commands that Do Completion - - This section describes the keymaps, commands and user options used -in the minibuffer to do completion. - -@defvar minibuffer-completion-table -The value of this variable is the completion table used for completion -in the minibuffer. This is the global variable that contains what -@code{completing-read} passes to @code{try-completion}. It is used by -minibuffer completion commands such as -@code{minibuffer-complete-word}. -@end defvar - -@defvar minibuffer-completion-predicate -This variable's value is the predicate that @code{completing-read} -passes to @code{try-completion}. The variable is also used by the other -minibuffer completion functions. -@end defvar - -@defvar minibuffer-completion-confirm -This variable determines whether Emacs asks for confirmation before -exiting the minibuffer; @code{completing-read} binds this variable, -and the function @code{minibuffer-complete-and-exit} checks the value -before exiting. If the value is @code{nil}, confirmation is not -required. If the value is @code{confirm}, the user may exit with an -input that is not a valid completion alternative, but Emacs asks for -confirmation. If the value is @code{confirm-after-completion}, the -user may exit with an input that is not a valid completion -alternative, but Emacs asks for confirmation if the user submitted the -input right after any of the completion commands in -@code{minibuffer-confirm-exit-commands}. -@end defvar - -@defvar minibuffer-confirm-exit-commands -This variable holds a list of commands that cause Emacs to ask for -confirmation before exiting the minibuffer, if the @var{require-match} -argument to @code{completing-read} is @code{confirm-after-completion}. -The confirmation is requested if the user attempts to exit the -minibuffer immediately after calling any command in this list. -@end defvar - -@deffn Command minibuffer-complete-word -This function completes the minibuffer contents by at most a single -word. Even if the minibuffer contents have only one completion, -@code{minibuffer-complete-word} does not add any characters beyond the -first character that is not a word constituent. @xref{Syntax Tables}. -@end deffn - -@deffn Command minibuffer-complete -This function completes the minibuffer contents as far as possible. -@end deffn - -@deffn Command minibuffer-complete-and-exit -This function completes the minibuffer contents, and exits if -confirmation is not required, i.e., if -@code{minibuffer-completion-confirm} is @code{nil}. If confirmation -@emph{is} required, it is given by repeating this command -immediately---the command is programmed to work without confirmation -when run twice in succession. -@end deffn - -@deffn Command minibuffer-completion-help -This function creates a list of the possible completions of the -current minibuffer contents. It works by calling @code{all-completions} -using the value of the variable @code{minibuffer-completion-table} as -the @var{collection} argument, and the value of -@code{minibuffer-completion-predicate} as the @var{predicate} argument. -The list of completions is displayed as text in a buffer named -@file{*Completions*}. -@end deffn - -@defun display-completion-list completions -This function displays @var{completions} to the stream in -@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more -information about streams.) The argument @var{completions} is normally -a list of completions just returned by @code{all-completions}, but it -does not have to be. Each element may be a symbol or a string, either -of which is simply printed. It can also be a list of two strings, -which is printed as if the strings were concatenated. The first of -the two strings is the actual completion, the second string serves as -annotation. - -This function is called by @code{minibuffer-completion-help}. A -common way to use it is together with -@code{with-output-to-temp-buffer}, like this: - -@example -(with-output-to-temp-buffer "*Completions*" - (display-completion-list - (all-completions (buffer-string) my-alist))) -@end example -@end defun - -@defopt completion-auto-help -If this variable is non-@code{nil}, the completion commands -automatically display a list of possible completions whenever nothing -can be completed because the next character is not uniquely determined. -@end defopt - -@defvar minibuffer-local-completion-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is not required. By default, this -keymap makes the following bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} -@end table - -@noindent -and uses @code{minibuffer-local-map} as its parent keymap -(@pxref{Definition of minibuffer-local-map}). -@end defvar - -@defvar minibuffer-local-must-match-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is required. Therefore, no keys -are bound to @code{exit-minibuffer}, the command that exits the -minibuffer unconditionally. By default, this keymap makes the following -bindings: - -@table @asis -@item @kbd{C-j} -@code{minibuffer-complete-and-exit} - -@item @key{RET} -@code{minibuffer-complete-and-exit} -@end table - -@noindent -and uses @code{minibuffer-local-completion-map} as its parent keymap. -@end defvar - -@defvar minibuffer-local-filename-completion-map -This is a sparse keymap that simply unbinds @key{SPC}; because -filenames can contain spaces. The function @code{read-file-name} -combines this keymap with either @code{minibuffer-local-completion-map} -or @code{minibuffer-local-must-match-map}. -@end defvar - - -@node High-Level Completion -@subsection High-Level Completion Functions - - This section describes the higher-level convenience functions for -reading certain sorts of names with completion. - - In most cases, you should not call these functions in the middle of a -Lisp function. When possible, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} -specification. @xref{Defining Commands}. - -@defun read-buffer prompt &optional default require-match -This function reads the name of a buffer and returns it as a string. -The argument @var{default} is the default name to use, the value to -return if the user exits with an empty minibuffer. If non-@code{nil}, -it should be a string, a list of strings, or a buffer. If it is -a list, the default value is the first element of this list. It is -mentioned in the prompt, but is not inserted in the minibuffer as -initial input. - -The argument @var{prompt} should be a string ending with a colon and a -space. If @var{default} is non-@code{nil}, the function inserts it in -@var{prompt} before the colon to follow the convention for reading from -the minibuffer with a default value (@pxref{Programming Tips}). - -The optional argument @var{require-match} has the same meaning as in -@code{completing-read}. @xref{Minibuffer Completion}. - -In the following example, the user enters @samp{minibuffer.t}, and -then types @key{RET}. The argument @var{require-match} is @code{t}, -and the only buffer name starting with the given input is -@samp{minibuffer.texi}, so that name is the value. - -@example -(read-buffer "Buffer name: " "foo" t) -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Buffer name (default foo): @point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{The user types @kbd{minibuffer.t @key{RET}}.} - @result{} "minibuffer.texi" -@end group -@end example -@end defun - -@defopt read-buffer-function -This variable, if non-@code{nil}, specifies a function for reading -buffer names. @code{read-buffer} calls this function instead of doing -its usual work, with the same arguments passed to @code{read-buffer}. -@end defopt - -@defopt read-buffer-completion-ignore-case -If this variable is non-@code{nil}, @code{read-buffer} ignores case -when performing completion. -@end defopt - -@defun read-command prompt &optional default -This function reads the name of a command and returns it as a Lisp -symbol. The argument @var{prompt} is used as in -@code{read-from-minibuffer}. Recall that a command is anything for -which @code{commandp} returns @code{t}, and a command name is a symbol -for which @code{commandp} returns @code{t}. @xref{Interactive Call}. - -The argument @var{default} specifies what to return if the user enters -null input. It can be a symbol, a string or a list of strings. If it -is a string, @code{read-command} interns it before returning it. -If it is a list, @code{read-command} interns the first element of this list. -If @var{default} is @code{nil}, that means no default has been -specified; then if the user enters null input, the return value is -@code{(intern "")}, that is, a symbol whose name is an empty string. - -@example -(read-command "Command name? ") - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Command name? ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -If the user types @kbd{forward-c @key{RET}}, then this function returns -@code{forward-char}. - -The @code{read-command} function is a simplified interface to -@code{completing-read}. It uses the variable @code{obarray} so as to -complete in the set of extant Lisp symbols, and it uses the -@code{commandp} predicate so as to accept only command names: - -@cindex @code{commandp} example -@example -@group -(read-command @var{prompt}) -@equiv{} -(intern (completing-read @var{prompt} obarray - 'commandp t nil)) -@end group -@end example -@end defun - -@defun read-variable prompt &optional default -@anchor{Definition of read-variable} -This function reads the name of a customizable variable and returns it -as a symbol. Its arguments have the same form as those of -@code{read-command}. It behaves just like @code{read-command}, except -that it uses the predicate @code{custom-variable-p} instead of -@code{commandp}. -@end defun - -@deffn Command read-color &optional prompt convert allow-empty display -This function reads a string that is a color specification, either the -color's name or an RGB hex value such as @code{#RRRGGGBBB}. It -prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"}) -and provides completion for color names, but not for hex RGB values. -In addition to names of standard colors, completion candidates include -the foreground and background colors at point. - -Valid RGB values are described in @ref{Color Names}. - -The function's return value is the string typed by the user in the -minibuffer. However, when called interactively or if the optional -argument @var{convert} is non-@code{nil}, it converts any input color -name into the corresponding RGB value string and instead returns that. -This function requires a valid color specification to be input. -Empty color names are allowed when @var{allow-empty} is -non-@code{nil} and the user enters null input. - -Interactively, or when @var{display} is non-@code{nil}, the return -value is also displayed in the echo area. -@end deffn - - See also the functions @code{read-coding-system} and -@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}, -and @code{read-input-method-name}, in @ref{Input Methods}. - -@node Reading File Names -@subsection Reading File Names -@cindex read file names -@cindex prompt for file name - - The high-level completion functions @code{read-file-name}, -@code{read-directory-name}, and @code{read-shell-command} are designed -to read file names, directory names, and shell commands, respectively. -They provide special features, including automatic insertion of the -default directory. - -@defun read-file-name prompt &optional directory default require-match initial predicate -This function reads a file name, prompting with @var{prompt} and -providing completion. - -As an exception, this function reads a file name using a graphical -file dialog instead of the minibuffer, if all of the following are -true: - -@enumerate -@item -It is invoked via a mouse command. - -@item -The selected frame is on a graphical display supporting such dialogs. - -@item -The variable @code{use-dialog-box} is non-@code{nil}. -@xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}. - -@item -The @var{directory} argument, described below, does not specify a -remote file. @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}. -@end enumerate - -@noindent -The exact behavior when using a graphical file dialog is -platform-dependent. Here, we simply document the behavior when using -the minibuffer. - -@code{read-file-name} does not automatically expand the returned file -name. You must call @code{expand-file-name} yourself if an absolute -file name is required. - -The optional argument @var{require-match} has the same meaning as in -@code{completing-read}. @xref{Minibuffer Completion}. - -The argument @var{directory} specifies the directory to use for -completing relative file names. It should be an absolute directory -name. If the variable @code{insert-default-directory} is non-@code{nil}, -@var{directory} is also inserted in the minibuffer as initial input. -It defaults to the current buffer's value of @code{default-directory}. - -If you specify @var{initial}, that is an initial file name to insert -in the buffer (after @var{directory}, if that is inserted). In this -case, point goes at the beginning of @var{initial}. The default for -@var{initial} is @code{nil}---don't insert any file name. To see what -@var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting -a file. @strong{Please note:} we recommend using @var{default} rather -than @var{initial} in most cases. - -If @var{default} is non-@code{nil}, then the function returns -@var{default} if the user exits the minibuffer with the same non-empty -contents that @code{read-file-name} inserted initially. The initial -minibuffer contents are always non-empty if -@code{insert-default-directory} is non-@code{nil}, as it is by -default. @var{default} is not checked for validity, regardless of the -value of @var{require-match}. However, if @var{require-match} is -non-@code{nil}, the initial minibuffer contents should be a valid file -(or directory) name. Otherwise @code{read-file-name} attempts -completion if the user exits without any editing, and does not return -@var{default}. @var{default} is also available through the history -commands. - -If @var{default} is @code{nil}, @code{read-file-name} tries to find a -substitute default to use in its place, which it treats in exactly the -same way as if it had been specified explicitly. If @var{default} is -@code{nil}, but @var{initial} is non-@code{nil}, then the default is -the absolute file name obtained from @var{directory} and -@var{initial}. If both @var{default} and @var{initial} are @code{nil} -and the buffer is visiting a file, @code{read-file-name} uses the -absolute file name of that file as default. If the buffer is not -visiting a file, then there is no default. In that case, if the user -types @key{RET} without any editing, @code{read-file-name} simply -returns the pre-inserted contents of the minibuffer. - -If the user types @key{RET} in an empty minibuffer, this function -returns an empty string, regardless of the value of -@var{require-match}. This is, for instance, how the user can make the -current buffer visit no file using @kbd{M-x set-visited-file-name}. - -If @var{predicate} is non-@code{nil}, it specifies a function of one -argument that decides which file names are acceptable completion -alternatives. A file name is an acceptable value if @var{predicate} -returns non-@code{nil} for it. - -Here is an example of using @code{read-file-name}: - -@example -@group -(read-file-name "The file is ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -Typing @kbd{manual @key{TAB}} results in the following: - -@example -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/manual.texi@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@c Wordy to avoid overfull hbox in smallbook mode. -@noindent -If the user types @key{RET}, @code{read-file-name} returns the file name -as the string @code{"/gp/gnu/elisp/manual.texi"}. -@end defun - -@defvar read-file-name-function -If non-@code{nil}, this should be a function that accepts the same -arguments as @code{read-file-name}. When @code{read-file-name} is -called, it calls this function with the supplied arguments instead of -doing its usual work. -@end defvar - -@defopt read-file-name-completion-ignore-case -If this variable is non-@code{nil}, @code{read-file-name} ignores case -when performing completion. -@end defopt - -@defun read-directory-name prompt &optional directory default require-match initial -This function is like @code{read-file-name} but allows only directory -names as completion alternatives. - -If @var{default} is @code{nil} and @var{initial} is non-@code{nil}, -@code{read-directory-name} constructs a substitute default by -combining @var{directory} (or the current buffer's default directory -if @var{directory} is @code{nil}) and @var{initial}. If both -@var{default} and @var{initial} are @code{nil}, this function uses -@var{directory} as substitute default, or the current buffer's default -directory if @var{directory} is @code{nil}. -@end defun - -@defopt insert-default-directory -This variable is used by @code{read-file-name}, and thus, indirectly, -by most commands reading file names. (This includes all commands that -use the code letters @samp{f} or @samp{F} in their interactive form. -@xref{Interactive Codes,, Code Characters for interactive}.) Its -value controls whether @code{read-file-name} starts by placing the -name of the default directory in the minibuffer, plus the initial file -name, if any. If the value of this variable is @code{nil}, then -@code{read-file-name} does not place any initial input in the -minibuffer (unless you specify initial input with the @var{initial} -argument). In that case, the default directory is still used for -completion of relative file names, but is not displayed. - -If this variable is @code{nil} and the initial minibuffer contents are -empty, the user may have to explicitly fetch the next history element -to access a default value. If the variable is non-@code{nil}, the -initial minibuffer contents are always non-empty and the user can -always request a default value by immediately typing @key{RET} in an -unedited minibuffer. (See above.) - -For example: - -@example -@group -;; @r{Here the minibuffer starts out with the default directory.} -(let ((insert-default-directory t)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is ~lewis/manual/@point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{Here the minibuffer is empty and only the prompt} -;; @r{appears on its line.} -(let ((insert-default-directory nil)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is @point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example -@end defopt - -@defun read-shell-command prompt &optional initial history &rest args -This function reads a shell command from the minibuffer, prompting -with @var{prompt} and providing intelligent completion. It completes -the first word of the command using candidates that are appropriate -for command names, and the rest of the command words as file names. - -This function uses @code{minibuffer-local-shell-command-map} as the -keymap for minibuffer input. The @var{history} argument specifies the -history list to use; if is omitted or @code{nil}, it defaults to -@code{shell-command-history} (@pxref{Minibuffer History, -shell-command-history}). The optional argument @var{initial} -specifies the initial content of the minibuffer (@pxref{Initial -Input}). The rest of @var{args}, if present, are used as the -@var{default} and @var{inherit-input-method} arguments in -@code{read-from-minibuffer} (@pxref{Text from Minibuffer}). -@end defun - -@defvar minibuffer-local-shell-command-map -This keymap is used by @code{read-shell-command} for completing -command and file names that are part of a shell command. It uses -@code{minibuffer-local-map} as its parent keymap, and binds @key{TAB} -to @code{completion-at-point}. -@end defvar - -@node Completion Variables -@subsection Completion Variables - - Here are some variables that can be used to alter the default -completion behavior. - -@cindex completion styles -@defopt completion-styles -The value of this variable is a list of completion style (symbols) to -use for performing completion. A @dfn{completion style} is a set of -rules for generating completions. Each symbol occurring this list -must have a corresponding entry in @code{completion-styles-alist}. -@end defopt - -@defvar completion-styles-alist -This variable stores a list of available completion styles. Each -element in the list has the form - -@example -(@var{style} @var{try-completion} @var{all-completions} @var{doc}) -@end example - -@noindent -Here, @var{style} is the name of the completion style (a symbol), -which may be used in the @code{completion-styles} variable to refer to -this style; @var{try-completion} is the function that does the -completion; @var{all-completions} is the function that lists the -completions; and @var{doc} is a string describing the completion -style. - -The @var{try-completion} and @var{all-completions} functions should -each accept four arguments: @var{string}, @var{collection}, -@var{predicate}, and @var{point}. The @var{string}, @var{collection}, -and @var{predicate} arguments have the same meanings as in -@code{try-completion} (@pxref{Basic Completion}), and the @var{point} -argument is the position of point within @var{string}. Each function -should return a non-@code{nil} value if it performed its job, and -@code{nil} if it did not (e.g., if there is no way to complete -@var{string} according to the completion style). - -When the user calls a completion command like -@code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks -for the first style listed in @code{completion-styles} and calls its -@var{try-completion} function. If this function returns @code{nil}, -Emacs moves to the next listed completion style and calls its -@var{try-completion} function, and so on until one of the -@var{try-completion} functions successfully performs completion and -returns a non-@code{nil} value. A similar procedure is used for -listing completions, via the @var{all-completions} functions. - -@xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a -description of the available completion styles. -@end defvar - -@defopt completion-category-overrides -This variable specifies special completion styles and other completion -behaviors to use when completing certain types of text. Its value -should be an alist with elements of the form @code{(@var{category} -. @var{alist})}. @var{category} is a symbol describing what is being -completed; currently, the @code{buffer}, @code{file}, and -@code{unicode-name} categories are defined, but others can be defined -via specialized completion functions (@pxref{Programmed Completion}). -@var{alist} is an association list describing how completion should -behave for the corresponding category. The following alist keys are -supported: - -@table @code -@item styles -The value should be a list of completion styles (symbols). - -@item cycle -The value should be a value for @code{completion-cycle-threshold} -(@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this -category. -@end table - -@noindent -Additional alist entries may be defined in the future. -@end defopt - -@defvar completion-extra-properties -This variable is used to specify extra properties of the current -completion command. It is intended to be let-bound by specialized -completion commands. Its value should be a list of property and value -pairs. The following properties are supported: - -@table @code -@item :annotation-function -The value should be a function to add annotations in the completions -buffer. This function must accept one argument, a completion, and -should either return @code{nil} or a string to be displayed next to -the completion. - -@item :exit-function -The value should be a function to run after performing completion. -The function should accept two arguments, @var{string} and -@var{status}, where @var{string} is the text to which the field was -completed, and @var{status} indicates what kind of operation happened: -@code{finished} if text is now complete, @code{sole} if the text -cannot be further completed but completion is not finished, or -@code{exact} if the text is a valid completion but may be further -completed. -@end table -@end defvar - -@node Programmed Completion -@subsection Programmed Completion -@cindex programmed completion - - Sometimes it is not possible or convenient to create an alist or -an obarray containing all the intended possible completions ahead -of time. In such a case, you can supply your own function to compute -the completion of a given string. This is called @dfn{programmed -completion}. Emacs uses programmed completion when completing file -names (@pxref{File Name Completion}), among many other cases. - - To use this feature, pass a function as the @var{collection} -argument to @code{completing-read}. The function -@code{completing-read} arranges to pass your completion function along -to @code{try-completion}, @code{all-completions}, and other basic -completion functions, which will then let your function do all -the work. - - The completion function should accept three arguments: - -@itemize @bullet -@item -The string to be completed. - -@item -A predicate function with which to filter possible matches, or -@code{nil} if none. The function should call the predicate for each -possible match, and ignore the match if the predicate returns -@code{nil}. - -@item -A flag specifying the type of completion operation to perform. This -is one of the following four values: - -@table @code -@item nil -This specifies a @code{try-completion} operation. The function should -return @code{t} if the specified string is a unique and exact match; -if there is more than one match, it should return the common substring -of all matches (if the string is an exact match for one completion -alternative but also matches other longer alternatives, the return -value is the string); if there are no matches, it should return -@code{nil}. - -@item t -This specifies an @code{all-completions} operation. The function -should return a list of all possible completions of the specified -string. - -@item lambda -This specifies a @code{test-completion} operation. The function -should return @code{t} if the specified string is an exact match for -some completion alternative; @code{nil} otherwise. - -@item (boundaries . @var{suffix}) -This specifies a @code{completion-boundaries} operation. The function -should return @code{(boundaries @var{start} . @var{end})}, where -@var{start} is the position of the beginning boundary in the specified -string, and @var{end} is the position of the end boundary in -@var{suffix}. - -@item metadata -This specifies a request for information about the state of the -current completion. The return value should have the form -@code{(metadata . @var{alist})}, where @var{alist} is an alist whose -elements are described below. -@end table - -@noindent -If the flag has any other value, the completion function should return -@code{nil}. -@end itemize - -The following is a list of metadata entries that a completion function -may return in response to a @code{metadata} flag argument: - -@table @code -@item category -The value should be a symbol describing what kind of text the -completion function is trying to complete. If the symbol matches one -of the keys in @code{completion-category-overrides}, the usual -completion behavior is overridden. @xref{Completion Variables}. - -@item annotation-function -The value should be a function for @dfn{annotating} completions. The -function should take one argument, @var{string}, which is a possible -completion. It should return a string, which is displayed after the -completion @var{string} in the @file{*Completions*} buffer. - -@item display-sort-function -The value should be a function for sorting completions. The function -should take one argument, a list of completion strings, and return a -sorted list of completion strings. It is allowed to alter the input -list destructively. - -@item cycle-sort-function -The value should be a function for sorting completions, when -@code{completion-cycle-threshold} is non-@code{nil} and the user is -cycling through completion alternatives. @xref{Completion Options,,, -emacs, The GNU Emacs Manual}. Its argument list and return value are -the same as for @code{display-sort-function}. -@end table - -@defun completion-table-dynamic function -This function is a convenient way to write a function that can act as -a programmed completion function. The argument @var{function} should be -a function that takes one argument, a string, and returns an alist of -possible completions of it. You can think of -@code{completion-table-dynamic} as a transducer between that interface -and the interface for programmed completion functions. -@end defun - -@defun completion-table-with-cache function &optional ignore-case -This is a wrapper for @code{completion-table-dynamic} that saves the -last argument-result pair. This means that multiple lookups with the -same argument only need to call @var{function} once. This can be useful -when a slow operation is involved, such as calling an external process. -@end defun - -@node Completion in Buffers -@subsection Completion in Ordinary Buffers -@cindex inline completion - -@findex completion-at-point - Although completion is usually done in the minibuffer, the -completion facility can also be used on the text in ordinary Emacs -buffers. In many major modes, in-buffer completion is performed by -the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to -@code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU -Emacs Manual}. This command uses the abnormal hook variable -@code{completion-at-point-functions}: - -@defvar completion-at-point-functions -The value of this abnormal hook should be a list of functions, which -are used to compute a completion table for completing the text at -point. It can be used by major modes to provide mode-specific -completion tables (@pxref{Major Mode Conventions}). - -When the command @code{completion-at-point} runs, it calls the -functions in the list one by one, without any argument. Each function -should return @code{nil} if it is unable to produce a completion table -for the text at point. Otherwise it should return a list of the form - -@example -(@var{start} @var{end} @var{collection} . @var{props}) -@end example - -@noindent -@var{start} and @var{end} delimit the text to complete (which should -enclose point). @var{collection} is a completion table for completing -that text, in a form suitable for passing as the second argument to -@code{try-completion} (@pxref{Basic Completion}); completion -alternatives will be generated from this completion table in the usual -way, via the completion styles defined in @code{completion-styles} -(@pxref{Completion Variables}). @var{props} is a property list for -additional information; any of the properties in -@code{completion-extra-properties} are recognized (@pxref{Completion -Variables}), as well as the following additional ones: - -@table @code -@item :predicate -The value should be a predicate that completion candidates need to -satisfy. - -@item :exclusive -If the value is @code{no}, then if the completion table fails to match -the text at point, @code{completion-at-point} moves on to the -next function in @code{completion-at-point-functions} instead of -reporting a completion failure. -@end table - -A function in @code{completion-at-point-functions} may also return a -function. In that case, that returned function is called, with no -argument, and it is entirely responsible for performing the -completion. We discourage this usage; it is intended to help convert -old code to using @code{completion-at-point}. - -The first function in @code{completion-at-point-functions} to return a -non-@code{nil} value is used by @code{completion-at-point}. The -remaining functions are not called. The exception to this is when -there is an @code{:exclusive} specification, as described above. -@end defvar - - The following function provides a convenient way to perform -completion on an arbitrary stretch of text in an Emacs buffer: - -@defun completion-in-region start end collection &optional predicate -This function completes the text in the current buffer between the -positions @var{start} and @var{end}, using @var{collection}. The -argument @var{collection} has the same meaning as in -@code{try-completion} (@pxref{Basic Completion}). - -This function inserts the completion text directly into the current -buffer. Unlike @code{completing-read} (@pxref{Minibuffer -Completion}), it does not activate the minibuffer. - -For this function to work, point must be somewhere between @var{start} -and @var{end}. -@end defun - - -@node Yes-or-No Queries -@section Yes-or-No Queries -@cindex asking the user questions -@cindex querying the user -@cindex yes-or-no questions - - This section describes functions used to ask the user a yes-or-no -question. The function @code{y-or-n-p} can be answered with a single -character; it is useful for questions where an inadvertent wrong answer -will not have serious consequences. @code{yes-or-no-p} is suitable for -more momentous questions, since it requires three or four characters to -answer. - - If either of these functions is called in a command that was invoked -using the mouse---more precisely, if @code{last-nonmenu-event} -(@pxref{Command Loop Info}) is either @code{nil} or a list---then it -uses a dialog box or pop-up menu to ask the question. Otherwise, it -uses keyboard input. You can force use either of the mouse or of keyboard -input by binding @code{last-nonmenu-event} to a suitable value around -the call. - - Strictly speaking, @code{yes-or-no-p} uses the minibuffer and -@code{y-or-n-p} does not; but it seems best to describe them together. - -@defun y-or-n-p prompt -This function asks the user a question, expecting input in the echo -area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the -user types @kbd{n}. This function also accepts @key{SPC} to mean yes -and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like -@kbd{C-g}, because the question might look like a minibuffer and for -that reason the user might try to use @kbd{C-]} to get out. The answer -is a single character, with no @key{RET} needed to terminate it. Upper -and lower case are equivalent. - -``Asking the question'' means printing @var{prompt} in the echo area, -followed by the string @w{@samp{(y or n) }}. If the input is not one of -the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}}, -@kbd{@key{DEL}}, or something that quits), the function responds -@samp{Please answer y or n.}, and repeats the request. - -This function does not actually use the minibuffer, since it does not -allow editing of the answer. It actually uses the echo area (@pxref{The -Echo Area}), which uses the same screen space as the minibuffer. The -cursor moves to the echo area while the question is being asked. - -The answers and their meanings, even @samp{y} and @samp{n}, are not -hardwired, and are specified by the keymap @code{query-replace-map} -(@pxref{Search and Replace}). In particular, if the user enters the -special responses @code{recenter}, @code{scroll-up}, -@code{scroll-down}, @code{scroll-other-window}, or -@code{scroll-other-window-down} (respectively bound to @kbd{C-l}, -@kbd{C-v}, @kbd{M-v}, @kbd{C-M-v} and @kbd{C-M-S-v} in -@code{query-replace-map}), this function performs the specified window -recentering or scrolling operation, and poses the question again. - -@noindent -We show successive lines of echo area messages, but only one actually -appears on the screen at a time. -@end defun - -@defun y-or-n-p-with-timeout prompt seconds default -Like @code{y-or-n-p}, except that if the user fails to answer within -@var{seconds} seconds, this function stops waiting and returns -@var{default}. It works by setting up a timer; see @ref{Timers}. -The argument @var{seconds} should be a number. -@end defun - -@defun yes-or-no-p prompt -This function asks the user a question, expecting input in the -minibuffer. It returns @code{t} if the user enters @samp{yes}, -@code{nil} if the user types @samp{no}. The user must type @key{RET} to -finalize the response. Upper and lower case are equivalent. - -@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area, -followed by @w{@samp{(yes or no) }}. The user must type one of the -expected responses; otherwise, the function responds @samp{Please answer -yes or no.}, waits about two seconds and repeats the request. - -@code{yes-or-no-p} requires more work from the user than -@code{y-or-n-p} and is appropriate for more crucial decisions. - -Here is an example: - -@smallexample -@group -(yes-or-no-p "Do you really want to remove everything? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: minibuffer ---------- -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user first types @kbd{y @key{RET}}, which is invalid because this -function demands the entire word @samp{yes}, it responds by displaying -these prompts, with a brief pause between them: - -@smallexample -@group ----------- Buffer: minibuffer ---------- -Please answer yes or no. -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample -@end defun - -@node Multiple Queries -@section Asking Multiple Y-or-N Questions - - When you have a series of similar questions to ask, such as ``Do you -want to save this buffer'' for each buffer in turn, you should use -@code{map-y-or-n-p} to ask the collection of questions, rather than -asking each question individually. This gives the user certain -convenient facilities such as the ability to answer the whole series at -once. - -@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area -This function asks the user a series of questions, reading a -single-character answer in the echo area for each one. - -The value of @var{list} specifies the objects to ask questions about. -It should be either a list of objects or a generator function. If it is -a function, it should expect no arguments, and should return either the -next object to ask about, or @code{nil}, meaning to stop asking questions. - -The argument @var{prompter} specifies how to ask each question. If -@var{prompter} is a string, the question text is computed like this: - -@example -(format @var{prompter} @var{object}) -@end example - -@noindent -where @var{object} is the next object to ask about (as obtained from -@var{list}). - -If not a string, @var{prompter} should be a function of one argument -(the next object to ask about) and should return the question text. If -the value is a string, that is the question to ask the user. The -function can also return @code{t}, meaning do act on this object (and -don't ask the user), or @code{nil}, meaning ignore this object (and don't -ask the user). - -The argument @var{actor} says how to act on the answers that the user -gives. It should be a function of one argument, and it is called with -each object that the user says yes for. Its argument is always an -object obtained from @var{list}. - -If the argument @var{help} is given, it should be a list of this form: - -@example -(@var{singular} @var{plural} @var{action}) -@end example - -@noindent -where @var{singular} is a string containing a singular noun that -describes the objects conceptually being acted on, @var{plural} is the -corresponding plural noun, and @var{action} is a transitive verb -describing what @var{actor} does. - -If you don't specify @var{help}, the default is @code{("object" -"objects" "act on")}. - -Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or -@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip -that object; @kbd{!} to act on all following objects; @key{ESC} or -@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on -the current object and then exit; or @kbd{C-h} to get help. These are -the same answers that @code{query-replace} accepts. The keymap -@code{query-replace-map} defines their meaning for @code{map-y-or-n-p} -as well as for @code{query-replace}; see @ref{Search and Replace}. - -You can use @var{action-alist} to specify additional possible answers -and what they mean. It is an alist of elements of the form -@code{(@var{char} @var{function} @var{help})}, each of which defines one -additional answer. In this element, @var{char} is a character (the -answer); @var{function} is a function of one argument (an object from -@var{list}); @var{help} is a string. - -When the user responds with @var{char}, @code{map-y-or-n-p} calls -@var{function}. If it returns non-@code{nil}, the object is considered -``acted upon'', and @code{map-y-or-n-p} advances to the next object in -@var{list}. If it returns @code{nil}, the prompt is repeated for the -same object. - -Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while -prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it -does not do that. - -If @code{map-y-or-n-p} is called in a command that was invoked using the -mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command -Loop Info}) is either @code{nil} or a list---then it uses a dialog box -or pop-up menu to ask the question. In this case, it does not use -keyboard input or the echo area. You can force use either of the mouse or -of keyboard input by binding @code{last-nonmenu-event} to a suitable -value around the call. - -The return value of @code{map-y-or-n-p} is the number of objects acted on. -@end defun -@c FIXME An example of this would be more useful than all the -@c preceding examples of simple things. - -@node Reading a Password -@section Reading a Password -@cindex passwords, reading - - To read a password to pass to another program, you can use the -function @code{read-passwd}. - -@defun read-passwd prompt &optional confirm default -This function reads a password, prompting with @var{prompt}. It does -not echo the password as the user types it; instead, it echoes @samp{.} -for each character in the password. (Note that in batch mode, the -input is not hidden.) - -The optional argument @var{confirm}, if non-@code{nil}, says to read the -password twice and insist it must be the same both times. If it isn't -the same, the user has to type it over and over until the last two -times match. - -The optional argument @var{default} specifies the default password to -return if the user enters empty input. If @var{default} is @code{nil}, -then @code{read-passwd} returns the null string in that case. -@end defun - -@node Minibuffer Commands -@section Minibuffer Commands - - This section describes some commands meant for use in the -minibuffer. - -@deffn Command exit-minibuffer -This command exits the active minibuffer. It is normally bound to -keys in minibuffer local keymaps. -@end deffn - -@deffn Command self-insert-and-exit -This command exits the active minibuffer after inserting the last -character typed on the keyboard (found in @code{last-command-event}; -@pxref{Command Loop Info}). -@end deffn - -@deffn Command previous-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element. -@end deffn - -@deffn Command next-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th more recent history element. -@end deffn - -@deffn Command previous-matching-history-element pattern n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element that matches @var{pattern} (a -regular expression). -@end deffn - -@deffn Command next-matching-history-element pattern n -This command replaces the minibuffer contents with the value of the -@var{n}th next (newer) history element that matches @var{pattern} (a -regular expression). -@end deffn - -@deffn Command previous-complete-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element that completes the current -contents of the minibuffer before the point. -@end deffn - -@deffn Command next-complete-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th next (newer) history element that completes the current -contents of the minibuffer before the point. -@end deffn - - -@node Minibuffer Windows -@section Minibuffer Windows -@cindex minibuffer windows - - These functions access and select minibuffer windows -and test whether they are active. - -@defun active-minibuffer-window -This function returns the currently active minibuffer window, or -@code{nil} if there is none. -@end defun - -@defun minibuffer-window &optional frame -@anchor{Definition of minibuffer-window} -This function returns the minibuffer window used for frame @var{frame}. -If @var{frame} is @code{nil}, that stands for the current frame. Note -that the minibuffer window used by a frame need not be part of that -frame---a frame that has no minibuffer of its own necessarily uses some -other frame's minibuffer window. -@end defun - -@defun set-minibuffer-window window -This function specifies @var{window} as the minibuffer window to use. -This affects where the minibuffer is displayed if you put text in it -without invoking the usual minibuffer commands. It has no effect on -the usual minibuffer input functions because they all start by -choosing the minibuffer window according to the current frame. -@end defun - -@c Emacs 19 feature -@defun window-minibuffer-p &optional window -This function returns non-@code{nil} if @var{window} is a minibuffer -window. -@var{window} defaults to the selected window. -@end defun - -It is not correct to determine whether a given window is a minibuffer by -comparing it with the result of @code{(minibuffer-window)}, because -there can be more than one minibuffer window if there is more than one -frame. - -@defun minibuffer-window-active-p window -This function returns non-@code{nil} if @var{window} is the currently -active minibuffer window. -@end defun - -@node Minibuffer Contents -@section Minibuffer Contents - - These functions access the minibuffer prompt and contents. - -@defun minibuffer-prompt -This function returns the prompt string of the currently active -minibuffer. If no minibuffer is active, it returns @code{nil}. -@end defun - -@defun minibuffer-prompt-end -This function returns the current -position of the end of the minibuffer prompt, if a minibuffer is -current. Otherwise, it returns the minimum valid buffer position. -@end defun - -@defun minibuffer-prompt-width -This function returns the current display-width of the minibuffer -prompt, if a minibuffer is current. Otherwise, it returns zero. -@end defun - -@defun minibuffer-contents -This function returns the editable -contents of the minibuffer (that is, everything except the prompt) as -a string, if a minibuffer is current. Otherwise, it returns the -entire contents of the current buffer. -@end defun - -@defun minibuffer-contents-no-properties -This is like @code{minibuffer-contents}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -@end defun - -@defun delete-minibuffer-contents -This function erases the editable contents of the minibuffer (that is, -everything except the prompt), if a minibuffer is current. Otherwise, -it erases the entire current buffer. -@end defun - -@node Recursive Mini -@section Recursive Minibuffers -@cindex recursive minibuffers - - These functions and variables deal with recursive minibuffers -(@pxref{Recursive Editing}): - -@defun minibuffer-depth -This function returns the current depth of activations of the -minibuffer, a nonnegative integer. If no minibuffers are active, it -returns zero. -@end defun - -@defopt enable-recursive-minibuffers -If this variable is non-@code{nil}, you can invoke commands (such as -@code{find-file}) that use minibuffers even while the minibuffer window -is active. Such invocation produces a recursive editing level for a new -minibuffer. The outer-level minibuffer is invisible while you are -editing the inner one. - -If this variable is @code{nil}, you cannot invoke minibuffer -commands when the minibuffer window is active, not even if you switch to -another window to do it. -@end defopt - -@c Emacs 19 feature -If a command name has a property @code{enable-recursive-minibuffers} -that is non-@code{nil}, then the command can use the minibuffer to read -arguments even if it is invoked from the minibuffer. A command can -also achieve this by binding @code{enable-recursive-minibuffers} -to @code{t} in the interactive declaration (@pxref{Using Interactive}). -The minibuffer command @code{next-matching-history-element} (normally -@kbd{M-s} in the minibuffer) does the latter. - -@node Minibuffer Misc -@section Minibuffer Miscellany - -@defun minibufferp &optional buffer-or-name -This function returns non-@code{nil} if @var{buffer-or-name} is a -minibuffer. If @var{buffer-or-name} is omitted, it tests the current -buffer. -@end defun - -@defvar minibuffer-setup-hook -This is a normal hook that is run whenever the minibuffer is entered. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-exit-hook -This is a normal hook that is run whenever the minibuffer is exited. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-help-form -@anchor{Definition of minibuffer-help-form} -The current value of this variable is used to rebind @code{help-form} -locally inside the minibuffer (@pxref{Help Functions}). -@end defvar - -@defvar minibuffer-scroll-window -@anchor{Definition of minibuffer-scroll-window} -If the value of this variable is non-@code{nil}, it should be a window -object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. -@end defvar - -@defun minibuffer-selected-window -This function returns the window that was selected when the -minibuffer was entered. If selected window is not a minibuffer -window, it returns @code{nil}. -@end defun - -@defopt max-mini-window-height -This variable specifies the maximum height for resizing minibuffer -windows. If a float, it specifies a fraction of the height of the -frame. If an integer, it specifies a number of lines. -@end defopt - -@vindex minibuffer-message-timeout -@defun minibuffer-message string &rest args -This function displays @var{string} temporarily at the end of the -minibuffer text, for a few seconds, or until the next input event -arrives, whichever comes first. The variable -@code{minibuffer-message-timeout} specifies the number of seconds to -wait in the absence of input. It defaults to 2. If @var{args} is -non-@code{nil}, the actual message is obtained by passing @var{string} -and @var{args} through @code{format}. @xref{Formatting Strings}. -@end defun - -@deffn Command minibuffer-inactive-mode -This is the major mode used in inactive minibuffers. It uses -keymap @code{minibuffer-inactive-mode-map}. This can be useful -if the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. -@end deffn diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi deleted file mode 100644 index d67bac63b15..00000000000 --- a/doc/lispref/modes.texi +++ /dev/null @@ -1,4068 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Modes -@chapter Major and Minor Modes -@cindex mode - - A @dfn{mode} is a set of definitions that customize Emacs and can be -turned on and off while you edit. There are two varieties of modes: -@dfn{major modes}, which are mutually exclusive and used for editing -particular kinds of text, and @dfn{minor modes}, which provide features -that users can enable individually. - - This chapter describes how to write both major and minor modes, how to -indicate them in the mode line, and how they run hooks supplied by the -user. For related topics such as keymaps and syntax tables, see -@ref{Keymaps}, and @ref{Syntax Tables}. - -@menu -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: Providing a menu of definitions made in a buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Auto-Indentation:: How to teach Emacs to indent for a major mode. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. -@end menu - -@node Hooks -@section Hooks -@cindex hooks - - A @dfn{hook} is a variable where you can store a function or functions -to be called on a particular occasion by an existing program. Emacs -provides hooks for the sake of customization. Most often, hooks are set -up in the init file (@pxref{Init File}), but Lisp programs can set them also. -@xref{Standard Hooks}, for a list of some standard hook variables. - -@cindex normal hook - Most of the hooks in Emacs are @dfn{normal hooks}. These variables -contain lists of functions to be called with no arguments. By -convention, whenever the hook name ends in @samp{-hook}, that tells -you it is normal. We try to make all hooks normal, as much as -possible, so that you can use them in a uniform way. - - Every major mode command is supposed to run a normal hook called the -@dfn{mode hook} as one of the last steps of initialization. This makes -it easy for a user to customize the behavior of the mode, by overriding -the buffer-local variable assignments already made by the mode. Most -minor mode functions also run a mode hook at the end. But hooks are -used in other contexts too. For example, the hook @code{suspend-hook} -runs just before Emacs suspends itself (@pxref{Suspending Emacs}). - - The recommended way to add a hook function to a hook is by calling -@code{add-hook} (@pxref{Setting Hooks}). The hook functions may be any -of the valid kinds of functions that @code{funcall} accepts (@pxref{What -Is a Function}). Most normal hook variables are initially void; -@code{add-hook} knows how to deal with this. You can add hooks either -globally or buffer-locally with @code{add-hook}. - -@cindex abnormal hook - If the hook variable's name does not end with @samp{-hook}, that -indicates it is probably an @dfn{abnormal hook}. That means the hook -functions are called with arguments, or their return values are used -in some way. The hook's documentation says how the functions are -called. You can use @code{add-hook} to add a function to an abnormal -hook, but you must write the function to follow the hook's calling -convention. By convention, abnormal hook names end in @samp{-functions}. - -@cindex single-function hook -If the variable's name ends in @samp{-function}, then its value is -just a single function, not a list of functions. @code{add-hook} cannot be -used to modify such a @emph{single function hook}, and you have to use -@code{add-function} instead (@pxref{Advising Functions}). - -@menu -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. -@end menu - -@node Running Hooks -@subsection Running Hooks - - In this section, we document the @code{run-hooks} function, which is -used to run a normal hook. We also document the functions for running -various kinds of abnormal hooks. - -@defun run-hooks &rest hookvars -This function takes one or more normal hook variable names as -arguments, and runs each hook in turn. Each argument should be a -symbol that is a normal hook variable. These arguments are processed -in the order specified. - -If a hook variable has a non-@code{nil} value, that value should be a -list of functions. @code{run-hooks} calls all the functions, one by -one, with no arguments. - -The hook variable's value can also be a single function---either a -lambda expression or a symbol with a function definition---which -@code{run-hooks} calls. But this usage is obsolete. - -If the hook variable is buffer-local, the buffer-local variable will -be used instead of the global variable. However, if the buffer-local -variable contains the element @code{t}, the global hook variable will -be run as well. -@end defun - -@defun run-hook-with-args hook &rest args -This function runs an abnormal hook by calling all the hook functions in -@var{hook}, passing each one the arguments @var{args}. -@end defun - -@defun run-hook-with-args-until-failure hook &rest args -This function runs an abnormal hook by calling each hook function in -turn, stopping if one of them ``fails'' by returning @code{nil}. Each -hook function is passed the arguments @var{args}. If this function -stops because one of the hook functions fails, it returns @code{nil}; -otherwise it returns a non-@code{nil} value. -@end defun - -@defun run-hook-with-args-until-success hook &rest args -This function runs an abnormal hook by calling each hook function, -stopping if one of them ``succeeds'' by returning a non-@code{nil} -value. Each hook function is passed the arguments @var{args}. If this -function stops because one of the hook functions returns a -non-@code{nil} value, it returns that value; otherwise it returns -@code{nil}. -@end defun - -@node Setting Hooks -@subsection Setting Hooks - - Here's an example that uses a mode hook to turn on Auto Fill mode when -in Lisp Interaction mode: - -@example -(add-hook 'lisp-interaction-mode-hook 'auto-fill-mode) -@end example - -@defun add-hook hook function &optional append local -This function is the handy way to add function @var{function} to hook -variable @var{hook}. You can use it for abnormal hooks as well as for -normal hooks. @var{function} can be any Lisp function that can accept -the proper number of arguments for @var{hook}. For example, - -@example -(add-hook 'text-mode-hook 'my-text-hook-function) -@end example - -@noindent -adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. - -If @var{function} is already present in @var{hook} (comparing using -@code{equal}), then @code{add-hook} does not add it a second time. - -If @var{function} has a non-@code{nil} property -@code{permanent-local-hook}, then @code{kill-all-local-variables} (or -changing major modes) won't delete it from the hook variable's local -value. - -For a normal hook, hook functions should be designed so that the order -in which they are executed does not matter. Any dependence on the order -is asking for trouble. However, the order is predictable: normally, -@var{function} goes at the front of the hook list, so it is executed -first (barring another @code{add-hook} call). If the optional argument -@var{append} is non-@code{nil}, the new hook function goes at the end of -the hook list and is executed last. - -@code{add-hook} can handle the cases where @var{hook} is void or its -value is a single function; it sets or changes the value to a list of -functions. - -If @var{local} is non-@code{nil}, that says to add @var{function} to the -buffer-local hook list instead of to the global hook list. This makes -the hook buffer-local and adds @code{t} to the buffer-local value. The -latter acts as a flag to run the hook functions in the default value as -well as in the local value. -@end defun - -@defun remove-hook hook function &optional local -This function removes @var{function} from the hook variable -@var{hook}. It compares @var{function} with elements of @var{hook} -using @code{equal}, so it works for both symbols and lambda -expressions. - -If @var{local} is non-@code{nil}, that says to remove @var{function} -from the buffer-local hook list instead of from the global hook list. -@end defun - -@node Major Modes -@section Major Modes -@cindex major mode - -@cindex major mode command - Major modes specialize Emacs for editing particular kinds of text. -Each buffer has one major mode at a time. Every major mode is -associated with a @dfn{major mode command}, whose name should end in -@samp{-mode}. This command takes care of switching to that mode in the -current buffer, by setting various buffer-local variables such as a -local keymap. @xref{Major Mode Conventions}. - - The least specialized major mode is called @dfn{Fundamental mode}, -which has no mode-specific definitions or variable settings. - -@deffn Command fundamental-mode -This is the major mode command for Fundamental mode. Unlike other mode -commands, it does @emph{not} run any mode hooks (@pxref{Major Mode -Conventions}), since you are not supposed to customize this mode. -@end deffn - - The easiest way to write a major mode is to use the macro -@code{define-derived-mode}, which sets up the new mode as a variant of -an existing major mode. @xref{Derived Modes}. We recommend using -@code{define-derived-mode} even if the new mode is not an obvious -derivative of another mode, as it automatically enforces many coding -conventions for you. @xref{Basic Major Modes}, for common modes to -derive from. - - The standard GNU Emacs Lisp directory tree contains the code for -several major modes, in files such as @file{text-mode.el}, -@file{texinfo.el}, @file{lisp-mode.el}, and @file{rmail.el}. You can -study these libraries to see how modes are written. - -@defopt major-mode -The buffer-local value of this variable holds the symbol for the current -major mode. Its default value holds the default major mode for new -buffers. The standard default value is @code{fundamental-mode}. - -If the default value is @code{nil}, then whenever Emacs creates a new -buffer via a command such as @kbd{C-x b} (@code{switch-to-buffer}), the -new buffer is put in the major mode of the previously current buffer. -As an exception, if the major mode of the previous buffer has a -@code{mode-class} symbol property with value @code{special}, the new -buffer is put in Fundamental mode (@pxref{Major Mode Conventions}). -@end defopt - -@menu -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Basic Major Modes:: Modes that other modes are often derived from. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Tabulated List Mode:: Parent mode for buffers containing tabulated data. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Example Major Modes:: Text mode and Lisp modes. -@end menu - -@node Major Mode Conventions -@subsection Major Mode Conventions -@cindex major mode conventions -@cindex conventions for writing major modes - - The code for every major mode should follow various coding -conventions, including conventions for local keymap and syntax table -initialization, function and variable names, and hooks. - - If you use the @code{define-derived-mode} macro, it will take care of -many of these conventions automatically. @xref{Derived Modes}. Note -also that Fundamental mode is an exception to many of these conventions, -because it represents the default state of Emacs. - - The following list of conventions is only partial. Each major mode -should aim for consistency in general with other Emacs major modes, as -this makes Emacs as a whole more coherent. It is impossible to list -here all the possible points where this issue might come up; if the -Emacs developers point out an area where your major mode deviates from -the usual conventions, please make it compatible. - -@itemize @bullet -@item -Define a major mode command whose name ends in @samp{-mode}. When -called with no arguments, this command should switch to the new mode in -the current buffer by setting up the keymap, syntax table, and -buffer-local variables in an existing buffer. It should not change the -buffer's contents. - -@item -Write a documentation string for this command that describes the special -commands available in this mode. @xref{Mode Help}. - -The documentation string may include the special documentation -substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and -@samp{\<@var{keymap}>}, which allow the help display to adapt -automatically to the user's own key bindings. @xref{Keys in -Documentation}. - -@item -The major mode command should start by calling -@code{kill-all-local-variables}. This runs the normal hook -@code{change-major-mode-hook}, then gets rid of the buffer-local -variables of the major mode previously in effect. @xref{Creating -Buffer-Local}. - -@item -The major mode command should set the variable @code{major-mode} to the -major mode command symbol. This is how @code{describe-mode} discovers -which documentation to print. - -@item -The major mode command should set the variable @code{mode-name} to the -``pretty'' name of the mode, usually a string (but see @ref{Mode Line -Data}, for other possible forms). The name of the mode appears -in the mode line. - -@item -@cindex functions in modes -Since all global names are in the same name space, all the global -variables, constants, and functions that are part of the mode should -have names that start with the major mode name (or with an abbreviation -of it if the name is long). @xref{Coding Conventions}. - -@item -In a major mode for editing some kind of structured text, such as a -programming language, indentation of text according to structure is -probably useful. So the mode should set @code{indent-line-function} -to a suitable function, and probably customize other variables -for indentation. @xref{Auto-Indentation}. - -@item -@cindex keymaps in modes -The major mode should usually have its own keymap, which is used as the -local keymap in all buffers in that mode. The major mode command should -call @code{use-local-map} to install this local map. @xref{Active -Keymaps}, for more information. - -This keymap should be stored permanently in a global variable named -@code{@var{modename}-mode-map}. Normally the library that defines the -mode sets this variable. - -@xref{Tips for Defining}, for advice about how to write the code to set -up the mode's keymap variable. - -@item -The key sequences bound in a major mode keymap should usually start with -@kbd{C-c}, followed by a control character, a digit, or @kbd{@{}, -@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation -characters are reserved for minor modes, and ordinary letters are -reserved for users. - -A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and -@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally -be some kind of ``moving forward and backward'', but this does not -necessarily mean cursor motion. - -It is legitimate for a major mode to rebind a standard key sequence if -it provides a command that does ``the same job'' in a way better -suited to the text this mode is used for. For example, a major mode -for editing a programming language might redefine @kbd{C-M-a} to -``move to the beginning of a function'' in a way that works better for -that language. - -It is also legitimate for a major mode to rebind a standard key -sequence whose standard meaning is rarely useful in that mode. For -instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is -rarely of any use in the minibuffer. Major modes such as Dired or -Rmail that do not allow self-insertion of text can reasonably redefine -letters and other printing characters as special commands. - -@item -Major modes for editing text should not define @key{RET} to do -anything other than insert a newline. However, it is ok for -specialized modes for text that users don't directly edit, such as -Dired and Info modes, to redefine @key{RET} to do something entirely -different. - -@item -Major modes should not alter options that are primarily a matter of user -preference, such as whether Auto-Fill mode is enabled. Leave this to -each user to decide. However, a major mode should customize other -variables so that Auto-Fill mode will work usefully @emph{if} the user -decides to use it. - -@item -@cindex syntax tables in modes -The mode may have its own syntax table or may share one with other -related modes. If it has its own syntax table, it should store this in -a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax -Tables}. - -@item -If the mode handles a language that has a syntax for comments, it should -set the variables that define the comment syntax. @xref{Options for -Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}. - -@item -@cindex abbrev tables in modes -The mode may have its own abbrev table or may share one with other -related modes. If it has its own abbrev table, it should store this -in a variable named @code{@var{modename}-mode-abbrev-table}. If the -major mode command defines any abbrevs itself, it should pass @code{t} -for the @var{system-flag} argument to @code{define-abbrev}. -@xref{Defining Abbrevs}. - -@item -The mode should specify how to do highlighting for Font Lock mode, by -setting up a buffer-local value for the variable -@code{font-lock-defaults} (@pxref{Font Lock Mode}). - -@item -Each face that the mode defines should, if possible, inherit from an -existing Emacs face. @xref{Basic Faces}, and @ref{Faces for Font Lock}. - -@item -The mode should specify how Imenu should find the definitions or -sections of a buffer, by setting up a buffer-local value for the -variable @code{imenu-generic-expression}, for the two variables -@code{imenu-prev-index-position-function} and -@code{imenu-extract-index-name-function}, or for the variable -@code{imenu-create-index-function} (@pxref{Imenu}). - -@item -The mode can specify a local value for -@code{eldoc-documentation-function} to tell ElDoc mode how to handle -this mode. - -@item -The mode can specify how to complete various keywords by adding one or -more buffer-local entries to the special hook -@code{completion-at-point-functions}. @xref{Completion in Buffers}. - -@item -@cindex buffer-local variables in modes -To make a buffer-local binding for an Emacs customization variable, use -@code{make-local-variable} in the major mode command, not -@code{make-variable-buffer-local}. The latter function would make the -variable local to every buffer in which it is subsequently set, which -would affect buffers that do not use this mode. It is undesirable for a -mode to have such global effects. @xref{Buffer-Local Variables}. - -With rare exceptions, the only reasonable way to use -@code{make-variable-buffer-local} in a Lisp package is for a variable -which is used only within that package. Using it on a variable used by -other packages would interfere with them. - -@item -@cindex mode hook -@cindex major mode hook -Each major mode should have a normal @dfn{mode hook} named -@code{@var{modename}-mode-hook}. The very last thing the major mode command -should do is to call @code{run-mode-hooks}. This runs the normal -hook @code{change-major-mode-after-body-hook}, the mode hook, -and then the normal hook @code{after-change-major-mode-hook}. -@xref{Mode Hooks}. - -@item -The major mode command may start by calling some other major mode -command (called the @dfn{parent mode}) and then alter some of its -settings. A mode that does this is called a @dfn{derived mode}. The -recommended way to define one is to use the @code{define-derived-mode} -macro, but this is not required. Such a mode should call the parent -mode command inside a @code{delay-mode-hooks} form. (Using -@code{define-derived-mode} does this automatically.) @xref{Derived -Modes}, and @ref{Mode Hooks}. - -@item -If something special should be done if the user switches a buffer from -this mode to any other major mode, this mode can set up a buffer-local -value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}). - -@item -If this mode is appropriate only for specially-prepared text produced by -the mode itself (rather than by the user typing at the keyboard or by an -external file), then the major mode command symbol should have a -property named @code{mode-class} with value @code{special}, put on as -follows: - -@kindex mode-class @r{(property)} -@cindex @code{special} modes -@example -(put 'funny-mode 'mode-class 'special) -@end example - -@noindent -This tells Emacs that new buffers created while the current buffer is in -Funny mode should not be put in Funny mode, even though the default -value of @code{major-mode} is @code{nil}. By default, the value of -@code{nil} for @code{major-mode} means to use the current buffer's major -mode when creating new buffers (@pxref{Auto Major Mode}), but with such -@code{special} modes, Fundamental mode is used instead. Modes such as -Dired, Rmail, and Buffer List use this feature. - -The function @code{view-buffer} does not enable View mode in buffers -whose mode-class is special, because such modes usually provide their -own View-like bindings. - -The @code{define-derived-mode} macro automatically marks the derived -mode as special if the parent mode is special. Special mode is a -convenient parent for such modes to inherit from; @xref{Basic Major -Modes}. - -@item -If you want to make the new mode the default for files with certain -recognizable names, add an element to @code{auto-mode-alist} to select -the mode for those file names (@pxref{Auto Major Mode}). If you -define the mode command to autoload, you should add this element in -the same file that calls @code{autoload}. If you use an autoload -cookie for the mode command, you can also use an autoload cookie for -the form that adds the element (@pxref{autoload cookie}). If you do -not autoload the mode command, it is sufficient to add the element in -the file that contains the mode definition. - -@item -@cindex mode loading -The top-level forms in the file defining the mode should be written so -that they may be evaluated more than once without adverse consequences. -For instance, use @code{defvar} or @code{defcustom} to set mode-related -variables, so that they are not reinitialized if they already have a -value (@pxref{Defining Variables}). - -@end itemize - -@node Auto Major Mode -@subsection How Emacs Chooses a Major Mode -@cindex major mode, automatic selection - - When Emacs visits a file, it automatically selects a major mode for -the buffer based on information in the file name or in the file itself. -It also processes local variables specified in the file text. - -@deffn Command normal-mode &optional find-file -This function establishes the proper major mode and buffer-local variable -bindings for the current buffer. First it calls @code{set-auto-mode} -(see below), then it runs @code{hack-local-variables} to parse, and -bind or evaluate as appropriate, the file's local variables -(@pxref{File Local Variables}). - -If the @var{find-file} argument to @code{normal-mode} is non-@code{nil}, -@code{normal-mode} assumes that the @code{find-file} function is calling -it. In this case, it may process local variables in the @samp{-*-} -line or at the end of the file. The variable -@code{enable-local-variables} controls whether to do so. @xref{File -Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, -for the syntax of the local variables section of a file. - -If you run @code{normal-mode} interactively, the argument -@var{find-file} is normally @code{nil}. In this case, -@code{normal-mode} unconditionally processes any file local variables. - -The function calls @code{set-auto-mode} to choose a major mode. If this -does not specify a mode, the buffer stays in the major mode determined -by the default value of @code{major-mode} (see below). - -@cindex file mode specification error -@code{normal-mode} uses @code{condition-case} around the call to the -major mode command, so errors are caught and reported as a @samp{File -mode specification error}, followed by the original error message. -@end deffn - -@defun set-auto-mode &optional keep-mode-if-same -@cindex visited file mode - This function selects the major mode that is appropriate for the -current buffer. It bases its decision (in order of precedence) on the -@w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of -a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}), -on the text at the beginning of the buffer (using -@code{magic-mode-alist}), and finally on the visited file name (using -@code{auto-mode-alist}). @xref{Choosing Modes, , How Major Modes are -Chosen, emacs, The GNU Emacs Manual}. If @code{enable-local-variables} -is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}} -line, or near the end of the file, for any mode tag. - -@vindex inhibit-local-variables-regexps -There are some file types where it is not appropriate to scan the file -contents for a mode specifier. For example, a tar archive may happen to -contain, near the end of the file, a member file that has a local -variables section specifying a mode for that particular file. This -should not be applied to the containing tar file. Similarly, a tiff -image file might just happen to contain a first line that seems to -match the @w{@samp{-*-}} pattern. For these reasons, both these file -extensions are members of the list @code{inhibit-local-variables-regexps}. -Add patterns to this list to prevent Emacs searching them for local -variables of any kind (not just mode specifiers). - -If @var{keep-mode-if-same} is non-@code{nil}, this function does not -call the mode command if the buffer is already in the proper major -mode. For instance, @code{set-visited-file-name} sets this to -@code{t} to avoid killing buffer local variables that the user may -have set. -@end defun - -@defun set-buffer-major-mode buffer -This function sets the major mode of @var{buffer} to the default value of -@code{major-mode}; if that is @code{nil}, it uses the -current buffer's major mode (if that is suitable). As an exception, -if @var{buffer}'s name is @file{*scratch*}, it sets the mode to -@code{initial-major-mode}. - -The low-level primitives for creating buffers do not use this function, -but medium-level commands such as @code{switch-to-buffer} and -@code{find-file-noselect} use it whenever they create buffers. -@end defun - -@defopt initial-major-mode -@cindex @file{*scratch*} -The value of this variable determines the major mode of the initial -@file{*scratch*} buffer. The value should be a symbol that is a major -mode command. The default value is @code{lisp-interaction-mode}. -@end defopt - -@defvar interpreter-mode-alist -This variable specifies major modes to use for scripts that specify a -command interpreter in a @samp{#!} line. Its value is an alist with -elements of the form @code{(@var{regexp} . @var{mode})}; this says to -use mode @var{mode} if the file specifies an interpreter which matches -@code{\\`@var{regexp}\\'}. For example, one of the default elements -is @code{("python[0-9.]*" . python-mode)}. -@end defvar - -@defvar magic-mode-alist -This variable's value is an alist with elements of the form -@code{(@var{regexp} . @var{function})}, where @var{regexp} is a -regular expression and @var{function} is a function or @code{nil}. -After visiting a file, @code{set-auto-mode} calls @var{function} if -the text at the beginning of the buffer matches @var{regexp} and -@var{function} is non-@code{nil}; if @var{function} is @code{nil}, -@code{auto-mode-alist} gets to decide the mode. -@end defvar - -@defvar magic-fallback-mode-alist -This works like @code{magic-mode-alist}, except that it is handled -only if @code{auto-mode-alist} does not specify a mode for this file. -@end defvar - -@defvar auto-mode-alist -This variable contains an association list of file name patterns -(regular expressions) and corresponding major mode commands. Usually, -the file name patterns test for suffixes, such as @samp{.el} and -@samp{.c}, but this need not be the case. An ordinary element of the -alist looks like @code{(@var{regexp} . @var{mode-function})}. - -For example, - -@smallexample -@group -(("\\`/tmp/fol/" . text-mode) - ("\\.texinfo\\'" . texinfo-mode) - ("\\.texi\\'" . texinfo-mode) -@end group -@group - ("\\.el\\'" . emacs-lisp-mode) - ("\\.c\\'" . c-mode) - ("\\.h\\'" . c-mode) - @dots{}) -@end group -@end smallexample - -When you visit a file whose expanded file name (@pxref{File Name -Expansion}), with version numbers and backup suffixes removed using -@code{file-name-sans-versions} (@pxref{File Name Components}), matches -a @var{regexp}, @code{set-auto-mode} calls the corresponding -@var{mode-function}. This feature enables Emacs to select the proper -major mode for most files. - -If an element of @code{auto-mode-alist} has the form @code{(@var{regexp} -@var{function} t)}, then after calling @var{function}, Emacs searches -@code{auto-mode-alist} again for a match against the portion of the file -name that did not match before. This feature is useful for -uncompression packages: an entry of the form @code{("\\.gz\\'" -@var{function} t)} can uncompress the file and then put the uncompressed -file in the proper mode according to the name sans @samp{.gz}. - -Here is an example of how to prepend several pattern pairs to -@code{auto-mode-alist}. (You might use this sort of expression in your -init file.) - -@smallexample -@group -(setq auto-mode-alist - (append - ;; @r{File name (within directory) starts with a dot.} - '(("/\\.[^/]*\\'" . fundamental-mode) - ;; @r{File name has no dot.} - ("/[^\\./]*\\'" . fundamental-mode) - ;; @r{File name ends in @samp{.C}.} - ("\\.C\\'" . c++-mode)) - auto-mode-alist)) -@end group -@end smallexample -@end defvar - -@node Mode Help -@subsection Getting Help about a Major Mode -@cindex mode help -@cindex help for major mode -@cindex documentation for major mode - - The @code{describe-mode} function provides information about major -modes. It is normally bound to @kbd{C-h m}. It uses the value of the -variable @code{major-mode} (@pxref{Major Modes}), which is why every -major mode command needs to set that variable. - -@deffn Command describe-mode &optional buffer -This command displays the documentation of the current buffer's major -mode and minor modes. It uses the @code{documentation} function to -retrieve the documentation strings of the major and minor mode -commands (@pxref{Accessing Documentation}). - -If called from Lisp with a non-@code{nil} @var{buffer} argument, this -function displays the documentation for that buffer's major and minor -modes, rather than those of the current buffer. -@end deffn - -@node Derived Modes -@subsection Defining Derived Modes -@cindex derived mode - - The recommended way to define a new major mode is to derive it from an -existing one using @code{define-derived-mode}. If there is no closely -related mode, you should inherit from either @code{text-mode}, -@code{special-mode}, or @code{prog-mode}. @xref{Basic Major Modes}. If -none of these are suitable, you can inherit from @code{fundamental-mode} -(@pxref{Major Modes}). - -@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{} -This macro defines @var{variant} as a major mode command, using -@var{name} as the string form of the mode name. @var{variant} and -@var{parent} should be unquoted symbols. - -The new command @var{variant} is defined to call the function -@var{parent}, then override certain aspects of that parent mode: - -@itemize @bullet -@item -The new mode has its own sparse keymap, named -@code{@var{variant}-map}. @code{define-derived-mode} -makes the parent mode's keymap the parent of the new map, unless -@code{@var{variant}-map} is already set and already has a parent. - -@item -The new mode has its own syntax table, kept in the variable -@code{@var{variant}-syntax-table}, unless you override this using the -@code{:syntax-table} keyword (see below). @code{define-derived-mode} -makes the parent mode's syntax-table the parent of -@code{@var{variant}-syntax-table}, unless the latter is already set -and already has a parent different from the standard syntax table. - -@item -The new mode has its own abbrev table, kept in the variable -@code{@var{variant}-abbrev-table}, unless you override this using the -@code{:abbrev-table} keyword (see below). - -@item -The new mode has its own mode hook, @code{@var{variant}-hook}. It -runs this hook, after running the hooks of its ancestor modes, with -@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. -@end itemize - -In addition, you can specify how to override other aspects of -@var{parent} with @var{body}. The command @var{variant} -evaluates the forms in @var{body} after setting up all its usual -overrides, just before running the mode hooks. - -If @var{parent} has a non-@code{nil} @code{mode-class} symbol -property, then @code{define-derived-mode} sets the @code{mode-class} -property of @var{variant} to the same value. This ensures, for -example, that if @var{parent} is a special mode, then @var{variant} is -also a special mode (@pxref{Major Mode Conventions}). - -You can also specify @code{nil} for @var{parent}. This gives the new -mode no parent. Then @code{define-derived-mode} behaves as described -above, but, of course, omits all actions connected with @var{parent}. - -The argument @var{docstring} specifies the documentation string for the -new mode. @code{define-derived-mode} adds some general information -about the mode's hook, followed by the mode's keymap, at the end of this -documentation string. If you omit @var{docstring}, -@code{define-derived-mode} generates a documentation string. - -The @var{keyword-args} are pairs of keywords and values. The values -are evaluated. The following keywords are currently supported: - -@table @code -@item :syntax-table -You can use this to explicitly specify a syntax table for the new -mode. If you specify a @code{nil} value, the new mode uses the same -syntax table as @var{parent}, or the standard syntax table if -@var{parent} is @code{nil}. (Note that this does @emph{not} follow -the convention used for non-keyword arguments that a @code{nil} value -is equivalent with not specifying the argument.) - -@item :abbrev-table -You can use this to explicitly specify an abbrev table for the new -mode. If you specify a @code{nil} value, the new mode uses the same -abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} -if @var{parent} is @code{nil}. (Again, a @code{nil} value is -@emph{not} equivalent to not specifying this keyword.) - -@item :group -If this is specified, the value should be the customization group for -this mode. (Not all major modes have one.) Only the (still -experimental and unadvertised) command @code{customize-mode} currently -uses this. @code{define-derived-mode} does @emph{not} automatically -define the specified customization group. -@end table - -Here is a hypothetical example: - -@example -(define-derived-mode hypertext-mode - text-mode "Hypertext" - "Major mode for hypertext. -\\@{hypertext-mode-map@}" - (setq case-fold-search nil)) - -(define-key hypertext-mode-map - [down-mouse-3] 'do-hyper-link) -@end example - -Do not write an @code{interactive} spec in the definition; -@code{define-derived-mode} does that automatically. -@end defmac - -@defun derived-mode-p &rest modes -This function returns non-@code{nil} if the current major mode is -derived from any of the major modes given by the symbols @var{modes}. -@end defun - -@node Basic Major Modes -@subsection Basic Major Modes - - Apart from Fundamental mode, there are three major modes that other -major modes commonly derive from: Text mode, Prog mode, and Special -mode. While Text mode is useful in its own right (e.g., for editing -files ending in @file{.txt}), Prog mode and Special mode exist mainly to -let other modes derive from them. - -@vindex prog-mode-hook - As far as possible, new major modes should be derived, either directly -or indirectly, from one of these three modes. One reason is that this -allows users to customize a single mode hook -(e.g., @code{prog-mode-hook}) for an entire family of relevant modes -(e.g., all programming language modes). - -@deffn Command text-mode -Text mode is a major mode for editing human languages. It defines the -@samp{"} and @samp{\} characters as having punctuation syntax -(@pxref{Syntax Class Table}), and binds @kbd{M-@key{TAB}} to -@code{ispell-complete-word} (@pxref{Spelling,,, emacs, The GNU Emacs -Manual}). - -An example of a major mode derived from Text mode is HTML mode. -@xref{HTML Mode,,SGML and HTML Modes, emacs, The GNU Emacs Manual}. -@end deffn - -@deffn Command prog-mode -Prog mode is a basic major mode for buffers containing programming -language source code. Most of the programming language major modes -built into Emacs are derived from it. - -Prog mode binds @code{parse-sexp-ignore-comments} to @code{t} -(@pxref{Motion via Parsing}) and @code{bidi-paragraph-direction} to -@code{left-to-right} (@pxref{Bidirectional Display}). -@end deffn - -@deffn Command special-mode -Special mode is a basic major mode for buffers containing text that is -produced specially by Emacs, rather than directly from a file. Major -modes derived from Special mode are given a @code{mode-class} property -of @code{special} (@pxref{Major Mode Conventions}). - -Special mode sets the buffer to read-only. Its keymap defines several -common bindings, including @kbd{q} for @code{quit-window} and @kbd{g} -for @code{revert-buffer} (@pxref{Reverting}). - -An example of a major mode derived from Special mode is Buffer Menu -mode, which is used by the @file{*Buffer List*} buffer. @xref{List -Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}. -@end deffn - - In addition, modes for buffers of tabulated data can inherit from -Tabulated List mode, which is in turn derived from Special mode. -@xref{Tabulated List Mode}. - -@node Mode Hooks -@subsection Mode Hooks - - Every major mode command should finish by running the mode-independent -normal hook @code{change-major-mode-after-body-hook}, its mode hook, -and the normal hook @code{after-change-major-mode-hook}. -It does this by calling @code{run-mode-hooks}. If the major mode is a -derived mode, that is if it calls another major mode (the parent mode) -in its body, it should do this inside @code{delay-mode-hooks} so that -the parent won't run these hooks itself. Instead, the derived mode's -call to @code{run-mode-hooks} runs the parent's mode hook too. -@xref{Major Mode Conventions}. - - Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. -Versions before 24 did not have @code{change-major-mode-after-body-hook}. -When user-implemented major modes do not use @code{run-mode-hooks} and -have not been updated to use these newer features, they won't entirely -follow these conventions: they may run the parent's mode hook too early, -or fail to run @code{after-change-major-mode-hook}. If you encounter -such a major mode, please correct it to follow these conventions. - - When you defined a major mode using @code{define-derived-mode}, it -automatically makes sure these conventions are followed. If you -define a major mode ``by hand'', not using @code{define-derived-mode}, -use the following functions to handle these conventions automatically. - -@defun run-mode-hooks &rest hookvars -Major modes should run their mode hook using this function. It is -similar to @code{run-hooks} (@pxref{Hooks}), but it also runs -@code{change-major-mode-after-body-hook} and -@code{after-change-major-mode-hook}. - -When this function is called during the execution of a -@code{delay-mode-hooks} form, it does not run the hooks immediately. -Instead, it arranges for the next call to @code{run-mode-hooks} to run -them. -@end defun - -@defmac delay-mode-hooks body@dots{} -When one major mode command calls another, it should do so inside of -@code{delay-mode-hooks}. - -This macro executes @var{body}, but tells all @code{run-mode-hooks} -calls during the execution of @var{body} to delay running their hooks. -The hooks will actually run during the next call to -@code{run-mode-hooks} after the end of the @code{delay-mode-hooks} -construct. -@end defmac - -@defvar change-major-mode-after-body-hook -This is a normal hook run by @code{run-mode-hooks}. It is run before -the mode hooks. -@end defvar - -@defvar after-change-major-mode-hook -This is a normal hook run by @code{run-mode-hooks}. It is run at the -very end of every properly-written major mode command. -@end defvar - -@node Tabulated List Mode -@subsection Tabulated List mode -@cindex Tabulated List mode - - Tabulated List mode is a major mode for displaying tabulated data, -i.e., data consisting of @dfn{entries}, each entry occupying one row of -text with its contents divided into columns. Tabulated List mode -provides facilities for pretty-printing rows and columns, and sorting -the rows according to the values in each column. It is derived from -Special mode (@pxref{Basic Major Modes}). - - Tabulated List mode is intended to be used as a parent mode by a more -specialized major mode. Examples include Process Menu mode -(@pxref{Process Information}) and Package Menu mode (@pxref{Package -Menu,,, emacs, The GNU Emacs Manual}). - -@findex tabulated-list-mode - Such a derived mode should use @code{define-derived-mode} in the usual -way, specifying @code{tabulated-list-mode} as the second argument -(@pxref{Derived Modes}). The body of the @code{define-derived-mode} -form should specify the format of the tabulated data, by assigning -values to the variables documented below; then, it should call the -function @code{tabulated-list-init-header} to initialize the header -line. - - The derived mode should also define a @dfn{listing command}. This, -not the mode command, is what the user calls (e.g., @kbd{M-x -list-processes}). The listing command should create or switch to a -buffer, turn on the derived mode, specify the tabulated data, and -finally call @code{tabulated-list-print} to populate the buffer. - -@defvar tabulated-list-format -This buffer-local variable specifies the format of the Tabulated List -data. Its value should be a vector. Each element of the vector -represents a data column, and should be a list @code{(@var{name} -@var{width} @var{sort})}, where - -@itemize -@item -@var{name} is the column's name (a string). - -@item -@var{width} is the width to reserve for the column (an integer). This -is meaningless for the last column, which runs to the end of each line. - -@item -@var{sort} specifies how to sort entries by the column. If @code{nil}, -the column cannot be used for sorting. If @code{t}, the column is -sorted by comparing string values. Otherwise, this should be a -predicate function for @code{sort} (@pxref{Rearrangement}), which -accepts two arguments with the same form as the elements of -@code{tabulated-list-entries} (see below). -@end itemize -@end defvar - -@defvar tabulated-list-entries -This buffer-local variable specifies the entries displayed in the -Tabulated List buffer. Its value should be either a list, or a -function. - -If the value is a list, each list element corresponds to one entry, and -should have the form @w{@code{(@var{id} @var{contents})}}, where - -@itemize -@item -@var{id} is either @code{nil}, or a Lisp object that identifies the -entry. If the latter, the cursor stays on the ``same'' entry when -re-sorting entries. Comparison is done with @code{equal}. - -@item -@var{contents} is a vector with the same number of elements as -@code{tabulated-list-format}. Each vector element is either a string, -which is inserted into the buffer as-is, or a list @code{(@var{label} -. @var{properties})}, which means to insert a text button by calling -@code{insert-text-button} with @var{label} and @var{properties} as -arguments (@pxref{Making Buttons}). - -There should be no newlines in any of these strings. -@end itemize - -Otherwise, the value should be a function which returns a list of the -above form when called with no arguments. -@end defvar - -@defvar tabulated-list-revert-hook -This normal hook is run prior to reverting a Tabulated List buffer. A -derived mode can add a function to this hook to recompute -@code{tabulated-list-entries}. -@end defvar - -@defvar tabulated-list-printer -The value of this variable is the function called to insert an entry at -point, including its terminating newline. The function should accept -two arguments, @var{id} and @var{contents}, having the same meanings as -in @code{tabulated-list-entries}. The default value is a function which -inserts an entry in a straightforward way; a mode which uses Tabulated -List mode in a more complex way can specify another function. -@end defvar - -@defvar tabulated-list-sort-key -The value of this variable specifies the current sort key for the -Tabulated List buffer. If it is @code{nil}, no sorting is done. -Otherwise, it should have the form @code{(@var{name} . @var{flip})}, -where @var{name} is a string matching one of the column names in -@code{tabulated-list-format}, and @var{flip}, if non-@code{nil}, means -to invert the sort order. -@end defvar - -@defun tabulated-list-init-header -This function computes and sets @code{header-line-format} for the -Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to -the header line to allow sort entries by clicking on column headers. - -Modes derived from Tabulated List mode should call this after setting -the above variables (in particular, only after setting -@code{tabulated-list-format}). -@end defun - -@defun tabulated-list-print &optional remember-pos -This function populates the current buffer with entries. It should be -called by the listing command. It erases the buffer, sorts the entries -specified by @code{tabulated-list-entries} according to -@code{tabulated-list-sort-key}, then calls the function specified by -@code{tabulated-list-printer} to insert each entry. - -If the optional argument @var{remember-pos} is non-@code{nil}, this -function looks for the @var{id} element on the current line, if any, and -tries to move to that entry after all the entries are (re)inserted. -@end defun - -@node Generic Modes -@subsection Generic Modes -@cindex generic mode - - @dfn{Generic modes} are simple major modes with basic support for -comment syntax and Font Lock mode. To define a generic mode, use the -macro @code{define-generic-mode}. See the file @file{generic-x.el} -for some examples of the use of @code{define-generic-mode}. - -@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring -This macro defines a generic mode command named @var{mode} (a symbol, -not quoted). The optional argument @var{docstring} is the -documentation for the mode command. If you do not supply it, -@code{define-generic-mode} generates one by default. - -The argument @var{comment-list} is a list in which each element is -either a character, a string of one or two characters, or a cons cell. -A character or a string is set up in the mode's syntax table as a -``comment starter''. If the entry is a cons cell, the @sc{car} is set -up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''. -(Use @code{nil} for the latter if you want comments to end at the end -of the line.) Note that the syntax table mechanism has limitations -about what comment starters and enders are actually possible. -@xref{Syntax Tables}. - -The argument @var{keyword-list} is a list of keywords to highlight -with @code{font-lock-keyword-face}. Each keyword should be a string. -Meanwhile, @var{font-lock-list} is a list of additional expressions to -highlight. Each element of this list should have the same form as an -element of @code{font-lock-keywords}. @xref{Search-based -Fontification}. - -The argument @var{auto-mode-list} is a list of regular expressions to -add to the variable @code{auto-mode-alist}. They are added by the execution -of the @code{define-generic-mode} form, not by expanding the macro call. - -Finally, @var{function-list} is a list of functions for the mode -command to call for additional setup. It calls these functions just -before it runs the mode hook variable @code{@var{mode}-hook}. -@end defmac - -@node Example Major Modes -@subsection Major Mode Examples - - Text mode is perhaps the simplest mode besides Fundamental mode. -Here are excerpts from @file{text-mode.el} that illustrate many of -the conventions listed above: - -@smallexample -@group -;; @r{Create the syntax table for this mode.} -(defvar text-mode-syntax-table - (let ((st (make-syntax-table))) - (modify-syntax-entry ?\" ". " st) - (modify-syntax-entry ?\\ ". " st) - ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. - (modify-syntax-entry ?' "w p" st) - st) - "Syntax table used while in `text-mode'.") -@end group - -;; @r{Create the keymap for this mode.} -@group -(defvar text-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\e\t" 'ispell-complete-word) - map) - "Keymap for `text-mode'. -Many other modes, such as `mail-mode', `outline-mode' and -`indented-text-mode', inherit all the commands defined in this map.") -@end group -@end smallexample - - Here is how the actual mode command is defined now: - -@smallexample -@group -(define-derived-mode text-mode nil "Text" - "Major mode for editing text written for humans to read. -In this mode, paragraphs are delimited only by blank or white lines. -You can thus get the full benefit of adaptive filling - (see the variable `adaptive-fill-mode'). -\\@{text-mode-map@} -Turning on Text mode runs the normal hook `text-mode-hook'." -@end group -@group - (set (make-local-variable 'text-mode-variant) t) - (set (make-local-variable 'require-final-newline) - mode-require-final-newline) - (set (make-local-variable 'indent-line-function) 'indent-relative)) -@end group -@end smallexample - -@noindent -(The last line is redundant nowadays, since @code{indent-relative} is -the default value, and we'll delete it in a future version.) - -@cindex @file{lisp-mode.el} - The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction -mode) have more features than Text mode and the code is correspondingly -more complicated. Here are excerpts from @file{lisp-mode.el} that -illustrate how these modes are written. - - Here is how the Lisp mode syntax and abbrev tables are defined: - -@cindex syntax table example -@smallexample -@group -;; @r{Create mode-specific table variables.} -(defvar lisp-mode-abbrev-table nil) -(define-abbrev-table 'lisp-mode-abbrev-table ()) - -(defvar lisp-mode-syntax-table - (let ((table (copy-syntax-table emacs-lisp-mode-syntax-table))) - (modify-syntax-entry ?\[ "_ " table) - (modify-syntax-entry ?\] "_ " table) - (modify-syntax-entry ?# "' 14" table) - (modify-syntax-entry ?| "\" 23bn" table) - table) - "Syntax table used in `lisp-mode'.") -@end group -@end smallexample - - The three modes for Lisp share much of their code. For instance, -each calls the following function to set various variables: - -@smallexample -@group -(defun lisp-mode-variables (&optional syntax keywords-case-insensitive) - (when syntax - (set-syntax-table lisp-mode-syntax-table)) - (setq local-abbrev-table lisp-mode-abbrev-table) - @dots{} -@end group -@end smallexample - -@noindent -Amongst other things, this function sets up the @code{comment-start} -variable to handle Lisp comments: - -@smallexample -@group - (make-local-variable 'comment-start) - (setq comment-start ";") - @dots{} -@end group -@end smallexample - - Each of the different Lisp modes has a slightly different keymap. For -example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other -Lisp modes do not. However, all Lisp modes have some commands in -common. The following code sets up the common commands: - -@smallexample -@group -(defvar lisp-mode-shared-map - (let ((map (make-sparse-keymap))) - (define-key map "\e\C-q" 'indent-sexp) - (define-key map "\177" 'backward-delete-char-untabify) - map) - "Keymap for commands shared by all sorts of Lisp modes.") -@end group -@end smallexample - -@noindent -And here is the code to set up the keymap for Lisp mode: - -@smallexample -@group -(defvar lisp-mode-map - (let ((map (make-sparse-keymap)) - (menu-map (make-sparse-keymap "Lisp"))) - (set-keymap-parent map lisp-mode-shared-map) - (define-key map "\e\C-x" 'lisp-eval-defun) - (define-key map "\C-c\C-z" 'run-lisp) - @dots{} - map) - "Keymap for ordinary Lisp mode. -All commands in `lisp-mode-shared-map' are inherited by this map.") -@end group -@end smallexample - -@noindent -Finally, here is the major mode command for Lisp mode: - -@smallexample -@group -(define-derived-mode lisp-mode prog-mode "Lisp" - "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. -Commands: -Delete converts tabs to spaces as it moves back. -Blank lines separate paragraphs. Semicolons start comments. - -\\@{lisp-mode-map@} -Note that `run-lisp' may be used either to start an inferior Lisp job -or to switch back to an existing one. -@end group - -@group -Entry to this mode calls the value of `lisp-mode-hook' -if that value is non-nil." - (lisp-mode-variables nil t) - (set (make-local-variable 'find-tag-default-function) - 'lisp-find-tag-default) - (set (make-local-variable 'comment-start-skip) - "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") - (setq imenu-case-fold-search t)) -@end group -@end smallexample - -@node Minor Modes -@section Minor Modes -@cindex minor mode - - A @dfn{minor mode} provides optional features that users may enable or -disable independently of the choice of major mode. Minor modes can be -enabled individually or in combination. - - Most minor modes implement features that are independent of the major -mode, and can thus be used with most major modes. For example, Auto -Fill mode works with any major mode that permits text insertion. A few -minor modes, however, are specific to a particular major mode. For -example, Diff Auto Refine mode is a minor mode that is intended to be -used only with Diff mode. - - Ideally, a minor mode should have its desired effect regardless of the -other minor modes in effect. It should be possible to activate and -deactivate minor modes in any order. - -@defvar minor-mode-list -The value of this variable is a list of all minor mode commands. -@end defvar - -@menu -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. -@end menu - -@node Minor Mode Conventions -@subsection Conventions for Writing Minor Modes -@cindex minor mode conventions -@cindex conventions for writing minor modes - - There are conventions for writing minor modes just as there are for -major modes. These conventions are described below. The easiest way to -follow them is to use the macro @code{define-minor-mode}. -@xref{Defining Minor Modes}. - -@itemize @bullet -@item -@cindex mode variable -Define a variable whose name ends in @samp{-mode}. We call this the -@dfn{mode variable}. The minor mode command should set this variable. -The value will be @code{nil} if the mode is disabled, and non-@code{nil} -if the mode is enabled. The variable should be buffer-local if the -minor mode is buffer-local. - -This variable is used in conjunction with the @code{minor-mode-alist} to -display the minor mode name in the mode line. It also determines -whether the minor mode keymap is active, via @code{minor-mode-map-alist} -(@pxref{Controlling Active Maps}). Individual commands or hooks can -also check its value. - -@item -Define a command, called the @dfn{mode command}, whose name is the same -as the mode variable. Its job is to set the value of the mode variable, -plus anything else that needs to be done to actually enable or disable -the mode's features. - -The mode command should accept one optional argument. If called -interactively with no prefix argument, it should toggle the mode -(i.e., enable if it is disabled, and disable if it is enabled). If -called interactively with a prefix argument, it should enable the mode -if the argument is positive and disable it otherwise. - -If the mode command is called from Lisp (i.e., non-interactively), it -should enable the mode if the argument is omitted or @code{nil}; it -should toggle the mode if the argument is the symbol @code{toggle}; -otherwise it should treat the argument in the same way as for an -interactive call with a numeric prefix argument, as described above. - -The following example shows how to implement this behavior (it is -similar to the code generated by the @code{define-minor-mode} macro): - -@example -(interactive (list (or current-prefix-arg 'toggle))) -(let ((enable (if (eq arg 'toggle) - (not foo-mode) ; @r{this mode's mode variable} - (> (prefix-numeric-value arg) 0)))) - (if enable - @var{do-enable} - @var{do-disable})) -@end example - -The reason for this somewhat complex behavior is that it lets users -easily toggle the minor mode interactively, and also lets the minor mode -be easily enabled in a mode hook, like this: - -@example -(add-hook 'text-mode-hook 'foo-mode) -@end example - -@noindent -This behaves correctly whether or not @code{foo-mode} was already -enabled, since the @code{foo-mode} mode command unconditionally enables -the minor mode when it is called from Lisp with no argument. Disabling -a minor mode in a mode hook is a little uglier: - -@example -(add-hook 'text-mode-hook (lambda () (foo-mode -1))) -@end example - -@noindent -However, this is not very commonly done. - -@item -Add an element to @code{minor-mode-alist} for each minor mode -(@pxref{Definition of minor-mode-alist}), if you want to indicate the -minor mode in the mode line. This element should be a list of the -following form: - -@smallexample -(@var{mode-variable} @var{string}) -@end smallexample - -Here @var{mode-variable} is the variable that controls enabling of the -minor mode, and @var{string} is a short string, starting with a space, -to represent the mode in the mode line. These strings must be short so -that there is room for several of them at once. - -When you add an element to @code{minor-mode-alist}, use @code{assq} to -check for an existing element, to avoid duplication. For example: - -@smallexample -@group -(unless (assq 'leif-mode minor-mode-alist) - (push '(leif-mode " Leif") minor-mode-alist)) -@end group -@end smallexample - -@noindent -or like this, using @code{add-to-list} (@pxref{List Variables}): - -@smallexample -@group -(add-to-list 'minor-mode-alist '(leif-mode " Leif")) -@end group -@end smallexample -@end itemize - - In addition, several major mode conventions apply to minor modes as -well: those regarding the names of global symbols, the use of a hook at -the end of the initialization function, and the use of keymaps and other -tables. - - The minor mode should, if possible, support enabling and disabling via -Custom (@pxref{Customization}). To do this, the mode variable should be -defined with @code{defcustom}, usually with @code{:type 'boolean}. If -just setting the variable is not sufficient to enable the mode, you -should also specify a @code{:set} method which enables the mode by -invoking the mode command. Note in the variable's documentation string -that setting the variable other than via Custom may not take effect. -Also, mark the definition with an autoload cookie (@pxref{autoload -cookie}), and specify a @code{:require} so that customizing the variable -will load the library that defines the mode. For example: - -@smallexample -@group -;;;###autoload -(defcustom msb-mode nil - "Toggle msb-mode. -Setting this variable directly does not take effect; -use either \\[customize] or the function `msb-mode'." - :set 'custom-set-minor-mode - :initialize 'custom-initialize-default - :version "20.4" - :type 'boolean - :group 'msb - :require 'msb) -@end group -@end smallexample - -@node Keymaps and Minor Modes -@subsection Keymaps and Minor Modes - - Each minor mode can have its own keymap, which is active when the mode -is enabled. To set up a keymap for a minor mode, add an element to the -alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}. - -@cindex @code{self-insert-command}, minor modes - One use of minor mode keymaps is to modify the behavior of certain -self-inserting characters so that they do something else as well as -self-insert. (Another way to customize @code{self-insert-command} is -through @code{post-self-insert-hook}. Apart from this, the facilities -for customizing @code{self-insert-command} are limited to special cases, -designed for abbrevs and Auto Fill mode. Do not try substituting your -own definition of @code{self-insert-command} for the standard one. The -editor command loop handles this function specially.) - -Minor modes may bind commands to key sequences consisting of @kbd{C-c} -followed by a punctuation character. However, sequences consisting of -@kbd{C-c} followed by one of @kbd{@{@}<>:;}, or a control character or -digit, are reserved for major modes. Also, @kbd{C-c @var{letter}} is -reserved for users. @xref{Key Binding Conventions}. - -@node Defining Minor Modes -@subsection Defining Minor Modes - - The macro @code{define-minor-mode} offers a convenient way of -implementing a mode in one self-contained definition. - -@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} -This macro defines a new minor mode whose name is @var{mode} (a -symbol). It defines a command named @var{mode} to toggle the minor -mode, with @var{doc} as its documentation string. - -The toggle command takes one optional (prefix) argument. -If called interactively with no argument it toggles the mode on or off. -A positive prefix argument enables the mode, any other prefix argument -disables it. From Lisp, an argument of @code{toggle} toggles the mode, -whereas an omitted or @code{nil} argument enables the mode. -This makes it easy to enable the minor mode in a major mode hook, for example. -If @var{doc} is nil, the macro supplies a default documentation string -explaining the above. - -By default, it also defines a variable named @var{mode}, which is set to -@code{t} or @code{nil} by enabling or disabling the mode. The variable -is initialized to @var{init-value}. Except in unusual circumstances -(see below), this value must be @code{nil}. - -The string @var{lighter} says what to display in the mode line -when the mode is enabled; if it is @code{nil}, the mode is not displayed -in the mode line. - -The optional argument @var{keymap} specifies the keymap for the minor -mode. If non-@code{nil}, it should be a variable name (whose value is -a keymap), a keymap, or an alist of the form - -@example -(@var{key-sequence} . @var{definition}) -@end example - -@noindent -where each @var{key-sequence} and @var{definition} are arguments -suitable for passing to @code{define-key} (@pxref{Changing Key -Bindings}). If @var{keymap} is a keymap or an alist, this also -defines the variable @code{@var{mode}-map}. - -The above three arguments @var{init-value}, @var{lighter}, and -@var{keymap} can be (partially) omitted when @var{keyword-args} are -used. The @var{keyword-args} consist of keywords followed by -corresponding values. A few keywords have special meanings: - -@table @code -@item :group @var{group} -Custom group name to use in all generated @code{defcustom} forms. -Defaults to @var{mode} without the possible trailing @samp{-mode}. -@strong{Warning:} don't use this default group name unless you have -written a @code{defgroup} to define that group properly. @xref{Group -Definitions}. - -@item :global @var{global} -If non-@code{nil}, this specifies that the minor mode should be global -rather than buffer-local. It defaults to @code{nil}. - -One of the effects of making a minor mode global is that the -@var{mode} variable becomes a customization variable. Toggling it -through the Customize interface turns the mode on and off, and its -value can be saved for future Emacs sessions (@pxref{Saving -Customizations,,, emacs, The GNU Emacs Manual}. For the saved -variable to work, you should ensure that the @code{define-minor-mode} -form is evaluated each time Emacs starts; for packages that are not -part of Emacs, the easiest way to do this is to specify a -@code{:require} keyword. - -@item :init-value @var{init-value} -This is equivalent to specifying @var{init-value} positionally. - -@item :lighter @var{lighter} -This is equivalent to specifying @var{lighter} positionally. - -@item :keymap @var{keymap} -This is equivalent to specifying @var{keymap} positionally. - -@item :variable @var{place} -This replaces the default variable @var{mode}, used to store the state -of the mode. If you specify this, the @var{mode} variable is not -defined, and any @var{init-value} argument is unused. @var{place} -can be a different named variable (which you must define yourself), or -anything that can be used with the @code{setf} function -(@pxref{Generalized Variables}). -@var{place} can also be a cons @code{(@var{get} . @var{set})}, -where @var{get} is an expression that returns the current state, -and @var{set} is a function of one argument (a state) that sets it. - -@item :after-hook @var{after-hook} -This defines a single Lisp form which is evaluated after the mode hooks -have run. It should not be quoted. -@end table - -Any other keyword arguments are passed directly to the -@code{defcustom} generated for the variable @var{mode}. - -The command named @var{mode} first performs the standard actions such as -setting the variable named @var{mode} and then executes the @var{body} -forms, if any. It then runs the mode hook variable -@code{@var{mode}-hook} and finishes by evaluating any form in -@code{:after-hook}. -@end defmac - - The initial value must be @code{nil} except in cases where (1) the -mode is preloaded in Emacs, or (2) it is painless for loading to -enable the mode even though the user did not request it. For -instance, if the mode has no effect unless something else is enabled, -and will always be loaded by that time, enabling it by default is -harmless. But these are unusual circumstances. Normally, the -initial value must be @code{nil}. - -@findex easy-mmode-define-minor-mode - The name @code{easy-mmode-define-minor-mode} is an alias -for this macro. - - Here is an example of using @code{define-minor-mode}: - -@smallexample -(define-minor-mode hungry-mode - "Toggle Hungry mode. -Interactively with no argument, this command toggles the mode. -A positive prefix argument enables the mode, any other prefix -argument disables it. From Lisp, argument omitted or nil enables -the mode, `toggle' toggles the state. - -When Hungry mode is enabled, the control delete key -gobbles all preceding whitespace except the last. -See the command \\[hungry-electric-delete]." - ;; The initial value. - nil - ;; The indicator for the mode line. - " Hungry" - ;; The minor mode bindings. - '(([C-backspace] . hungry-electric-delete)) - :group 'hunger) -@end smallexample - -@noindent -This defines a minor mode named ``Hungry mode'', a command named -@code{hungry-mode} to toggle it, a variable named @code{hungry-mode} -which indicates whether the mode is enabled, and a variable named -@code{hungry-mode-map} which holds the keymap that is active when the -mode is enabled. It initializes the keymap with a key binding for -@kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into -custom group @code{hunger}. There are no @var{body} forms---many -minor modes don't need any. - - Here's an equivalent way to write it: - -@smallexample -(define-minor-mode hungry-mode - "Toggle Hungry mode. -...rest of documentation as before..." - ;; The initial value. - :init-value nil - ;; The indicator for the mode line. - :lighter " Hungry" - ;; The minor mode bindings. - :keymap - '(([C-backspace] . hungry-electric-delete) - ([C-M-backspace] - . (lambda () - (interactive) - (hungry-electric-delete t)))) - :group 'hunger) -@end smallexample - -@defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{} -This defines a global toggle named @var{global-mode} whose meaning is -to enable or disable the buffer-local minor mode @var{mode} in all -buffers. To turn on the minor mode in a buffer, it uses the function -@var{turn-on}; to turn off the minor mode, it calls @var{mode} with -@minus{}1 as argument. - -Globally enabling the mode also affects buffers subsequently created -by visiting files, and buffers that use a major mode other than -Fundamental mode; but it does not detect the creation of a new buffer -in Fundamental mode. - -This defines the customization option @var{global-mode} (@pxref{Customization}), -which can be toggled in the Customize interface to turn the minor mode on -and off. As with @code{define-minor-mode}, you should ensure that the -@code{define-globalized-minor-mode} form is evaluated each time Emacs -starts, for example by providing a @code{:require} keyword. - -Use @code{:group @var{group}} in @var{keyword-args} to specify the -custom group for the mode variable of the global minor mode. - -Generally speaking, when you define a globalized minor mode, you should -also define a non-globalized version, so that people can use (or -disable) it in individual buffers. This also allows them to disable a -globally enabled minor mode in a specific major mode, by using that -mode's hook. -@end defmac - - -@node Mode Line Format -@section Mode Line Format -@cindex mode line - - Each Emacs window (aside from minibuffer windows) typically has a mode -line at the bottom, which displays status information about the buffer -displayed in the window. The mode line contains information about the -buffer, such as its name, associated file, depth of recursive editing, -and major and minor modes. A window can also have a @dfn{header -line}, which is much like the mode line but appears at the top of the -window. - - This section describes how to control the contents of the mode line -and header line. We include it in this chapter because much of the -information displayed in the mode line relates to the enabled major and -minor modes. - -@menu -* Base: Mode Line Basics. Basic ideas of mode line control. -* Data: Mode Line Data. The data structure that controls the mode line. -* Top: Mode Line Top. The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. -@end menu - -@node Mode Line Basics -@subsection Mode Line Basics - - The contents of each mode line are specified by the buffer-local -variable @code{mode-line-format} (@pxref{Mode Line Top}). This variable -holds a @dfn{mode line construct}: a template that controls what is -displayed on the buffer's mode line. The value of -@code{header-line-format} specifies the buffer's header line in the same -way. All windows for the same buffer use the same -@code{mode-line-format} and @code{header-line-format}. - - For efficiency, Emacs does not continuously recompute each window's -mode line and header line. It does so when circumstances appear to call -for it---for instance, if you change the window configuration, switch -buffers, narrow or widen the buffer, scroll, or modify the buffer. If -you alter any of the variables referenced by @code{mode-line-format} or -@code{header-line-format} (@pxref{Mode Line Variables}), or any other -data structures that affect how text is displayed (@pxref{Display}), you -should use the function @code{force-mode-line-update} to update the -display. - -@defun force-mode-line-update &optional all -This function forces Emacs to update the current buffer's mode line and -header line, based on the latest values of all relevant variables, -during its next redisplay cycle. If the optional argument @var{all} is -non-@code{nil}, it forces an update for all mode lines and header lines. - -This function also forces an update of the menu bar and frame title. -@end defun - - The selected window's mode line is usually displayed in a different -color using the face @code{mode-line}. Other windows' mode lines appear -in the face @code{mode-line-inactive} instead. @xref{Faces}. - -@node Mode Line Data -@subsection The Data Structure of the Mode Line -@cindex mode line construct - - The mode line contents are controlled by a data structure called a -@dfn{mode line construct}, made up of lists, strings, symbols, and -numbers kept in buffer-local variables. Each data type has a specific -meaning for the mode line appearance, as described below. The same data -structure is used for constructing frame titles (@pxref{Frame Titles}) -and header lines (@pxref{Header Lines}). - - A mode line construct may be as simple as a fixed string of text, -but it usually specifies how to combine fixed strings with variables' -values to construct the text. Many of these variables are themselves -defined to have mode line constructs as their values. - - Here are the meanings of various data types as mode line constructs: - -@table @code -@cindex percent symbol in mode line -@item @var{string} -A string as a mode line construct appears verbatim except for -@dfn{@code{%}-constructs} in it. These stand for substitution of -other data; see @ref{%-Constructs}. - -If parts of the string have @code{face} properties, they control -display of the text just as they would text in the buffer. Any -characters which have no @code{face} properties are displayed, by -default, in the face @code{mode-line} or @code{mode-line-inactive} -(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The -@code{help-echo} and @code{keymap} properties in @var{string} have -special meanings. @xref{Properties in Mode}. - -@item @var{symbol} -A symbol as a mode line construct stands for its value. The value of -@var{symbol} is used as a mode line construct, in place of @var{symbol}. -However, the symbols @code{t} and @code{nil} are ignored, as is any -symbol whose value is void. - -There is one exception: if the value of @var{symbol} is a string, it is -displayed verbatim: the @code{%}-constructs are not recognized. - -Unless @var{symbol} is marked as ``risky'' (i.e., it has a -non-@code{nil} @code{risky-local-variable} property), all text -properties specified in @var{symbol}'s value are ignored. This includes -the text properties of strings in @var{symbol}'s value, as well as all -@code{:eval} and @code{:propertize} forms in it. (The reason for this -is security: non-risky variables could be set automatically from file -variables without prompting the user.) - -@item (@var{string} @var{rest}@dots{}) -@itemx (@var{list} @var{rest}@dots{}) -A list whose first element is a string or list means to process all the -elements recursively and concatenate the results. This is the most -common form of mode line construct. - -@item (:eval @var{form}) -A list whose first element is the symbol @code{:eval} says to evaluate -@var{form}, and use the result as a string to display. Make sure this -evaluation cannot load any files, as doing so could cause infinite -recursion. - -@item (:propertize @var{elt} @var{props}@dots{}) -A list whose first element is the symbol @code{:propertize} says to -process the mode line construct @var{elt} recursively, then add the text -properties specified by @var{props} to the result. The argument -@var{props} should consist of zero or more pairs @var{text-property} -@var{value}. - -@item (@var{symbol} @var{then} @var{else}) -A list whose first element is a symbol that is not a keyword specifies -a conditional. Its meaning depends on the value of @var{symbol}. If -@var{symbol} has a non-@code{nil} value, the second element, -@var{then}, is processed recursively as a mode line construct. -Otherwise, the third element, @var{else}, is processed recursively. -You may omit @var{else}; then the mode line construct displays nothing -if the value of @var{symbol} is @code{nil} or void. - -@item (@var{width} @var{rest}@dots{}) -A list whose first element is an integer specifies truncation or -padding of the results of @var{rest}. The remaining elements -@var{rest} are processed recursively as mode line constructs and -concatenated together. When @var{width} is positive, the result is -space filled on the right if its width is less than @var{width}. When -@var{width} is negative, the result is truncated on the right to -@minus{}@var{width} columns if its width exceeds @minus{}@var{width}. - -For example, the usual way to show what percentage of a buffer is above -the top of the window is to use a list like this: @code{(-3 "%p")}. -@end table - -@node Mode Line Top -@subsection The Top Level of Mode Line Control - - The variable in overall control of the mode line is -@code{mode-line-format}. - -@defopt mode-line-format -The value of this variable is a mode line construct that controls the -contents of the mode-line. It is always buffer-local in all buffers. - -If you set this variable to @code{nil} in a buffer, that buffer does not -have a mode line. (A window that is just one line tall also does not -display a mode line.) -@end defopt - - The default value of @code{mode-line-format} is designed to use the -values of other variables such as @code{mode-line-position} and -@code{mode-line-modes} (which in turn incorporates the values of the -variables @code{mode-name} and @code{minor-mode-alist}). Very few -modes need to alter @code{mode-line-format} itself. For most -purposes, it is sufficient to alter some of the variables that -@code{mode-line-format} either directly or indirectly refers to. - - If you do alter @code{mode-line-format} itself, the new value should -use the same variables that appear in the default value (@pxref{Mode -Line Variables}), rather than duplicating their contents or displaying -the information in another fashion. This way, customizations made by -the user or by Lisp programs (such as @code{display-time} and major -modes) via changes to those variables remain effective. - - Here is a hypothetical example of a @code{mode-line-format} that might -be useful for Shell mode (in reality, Shell mode does not set -@code{mode-line-format}): - -@example -@group -(setq mode-line-format - (list "-" - 'mode-line-mule-info - 'mode-line-modified - 'mode-line-frame-identification - "%b--" -@end group -@group - ;; @r{Note that this is evaluated while making the list.} - ;; @r{It makes a mode line construct which is just a string.} - (getenv "HOST") -@end group - ":" - 'default-directory - " " - 'global-mode-string - " %[(" - '(:eval (mode-line-mode-name)) - 'mode-line-process - 'minor-mode-alist - "%n" - ")%]--" -@group - '(which-func-mode ("" which-func-format "--")) - '(line-number-mode "L%l--") - '(column-number-mode "C%c--") - '(-3 "%p"))) -@end group -@end example - -@noindent -(The variables @code{line-number-mode}, @code{column-number-mode} -and @code{which-func-mode} enable particular minor modes; as usual, -these variable names are also the minor mode command names.) - -@node Mode Line Variables -@subsection Variables Used in the Mode Line - - This section describes variables incorporated by the standard value of -@code{mode-line-format} into the text of the mode line. There is -nothing inherently special about these variables; any other variables -could have the same effects on the mode line if the value of -@code{mode-line-format} is changed to use them. However, various parts -of Emacs set these variables on the understanding that they will control -parts of the mode line; therefore, practically speaking, it is essential -for the mode line to use them. - -@defvar mode-line-mule-info -This variable holds the value of the mode line construct that displays -information about the language environment, buffer coding system, and -current input method. @xref{Non-ASCII Characters}. -@end defvar - -@defvar mode-line-modified -This variable holds the value of the mode line construct that displays -whether the current buffer is modified. Its default value displays -@samp{**} if the buffer is modified, @samp{--} if the buffer is not -modified, @samp{%%} if the buffer is read only, and @samp{%*} if the -buffer is read only and modified. - -Changing this variable does not force an update of the mode line. -@end defvar - -@defvar mode-line-frame-identification -This variable identifies the current frame. Its default value -displays @code{" "} if you are using a window system which can show -multiple frames, or @code{"-%F "} on an ordinary terminal which shows -only one frame at a time. -@end defvar - -@defvar mode-line-buffer-identification -This variable identifies the buffer being displayed in the window. -Its default value displays the buffer name, padded with spaces to at -least 12 columns. -@end defvar - -@defopt mode-line-position -This variable indicates the position in the buffer. Its default value -displays the buffer percentage and, optionally, the buffer size, the -line number and the column number. -@end defopt - -@defvar vc-mode -The variable @code{vc-mode}, buffer-local in each buffer, records -whether the buffer's visited file is maintained with version control, -and, if so, which kind. Its value is a string that appears in the mode -line, or @code{nil} for no version control. -@end defvar - -@defopt mode-line-modes -This variable displays the buffer's major and minor modes. Its -default value also displays the recursive editing level, information -on the process status, and whether narrowing is in effect. -@end defopt - -@defvar mode-line-remote -This variable is used to show whether @code{default-directory} for the -current buffer is remote. -@end defvar - -@defvar mode-line-client -This variable is used to identify @code{emacsclient} frames. -@end defvar - - The following three variables are used in @code{mode-line-modes}: - -@defvar mode-name -This buffer-local variable holds the ``pretty'' name of the current -buffer's major mode. Each major mode should set this variable so that -the mode name will appear in the mode line. The value does not have -to be a string, but can use any of the data types valid in a mode-line -construct (@pxref{Mode Line Data}). To compute the string that will -identify the mode name in the mode line, use @code{format-mode-line} -(@pxref{Emulating Mode Line}). -@end defvar - -@defvar mode-line-process -This buffer-local variable contains the mode line information on process -status in modes used for communicating with subprocesses. It is -displayed immediately following the major mode name, with no intervening -space. For example, its value in the @file{*shell*} buffer is -@code{(":%s")}, which allows the shell to display its status along -with the major mode as: @samp{(Shell:run)}. Normally this variable -is @code{nil}. -@end defvar - -@defvar minor-mode-alist -@anchor{Definition of minor-mode-alist} -This variable holds an association list whose elements specify how the -mode line should indicate that a minor mode is active. Each element of -the @code{minor-mode-alist} should be a two-element list: - -@example -(@var{minor-mode-variable} @var{mode-line-string}) -@end example - -More generally, @var{mode-line-string} can be any mode line construct. -It appears in the mode line when the value of @var{minor-mode-variable} -is non-@code{nil}, and not otherwise. These strings should begin with -spaces so that they don't run together. Conventionally, the -@var{minor-mode-variable} for a specific mode is set to a non-@code{nil} -value when that minor mode is activated. - -@code{minor-mode-alist} itself is not buffer-local. Each variable -mentioned in the alist should be buffer-local if its minor mode can be -enabled separately in each buffer. -@end defvar - -@defvar global-mode-string -This variable holds a mode line construct that, by default, appears in -the mode line just after the @code{which-func-mode} minor mode if set, -else after @code{mode-line-modes}. The command @code{display-time} sets -@code{global-mode-string} to refer to the variable -@code{display-time-string}, which holds a string containing the time and -load information. - -The @samp{%M} construct substitutes the value of -@code{global-mode-string}, but that is obsolete, since the variable is -included in the mode line from @code{mode-line-format}. -@end defvar - -Here is a simplified version of the default value of -@code{mode-line-format}. The real default value also -specifies addition of text properties. - -@example -@group -("-" - mode-line-mule-info - mode-line-modified - mode-line-frame-identification - mode-line-buffer-identification -@end group - " " - mode-line-position - (vc-mode vc-mode) - " " -@group - mode-line-modes - (which-func-mode ("" which-func-format "--")) - (global-mode-string ("--" global-mode-string)) - "-%-") -@end group -@end example - -@node %-Constructs -@subsection @code{%}-Constructs in the Mode Line - - Strings used as mode line constructs can use certain -@code{%}-constructs to substitute various kinds of data. The -following is a list of the defined @code{%}-constructs, and what they -mean. - - In any construct except @samp{%%}, you can add a decimal integer -after the @samp{%} to specify a minimum field width. If the width is -less, the field is padded to that width. Purely numeric constructs -(@samp{c}, @samp{i}, @samp{I}, and @samp{l}) are padded by inserting -spaces to the left, and others are padded by inserting spaces to the -right. - -@table @code -@item %b -The current buffer name, obtained with the @code{buffer-name} function. -@xref{Buffer Names}. - -@item %c -The current column number of point. - -@item %e -When Emacs is nearly out of memory for Lisp objects, a brief message -saying so. Otherwise, this is empty. - -@item %f -The visited file name, obtained with the @code{buffer-file-name} -function. @xref{Buffer File Name}. - -@item %F -The title (only on a window system) or the name of the selected frame. -@xref{Basic Parameters}. - -@item %i -The size of the accessible part of the current buffer; basically -@code{(- (point-max) (point-min))}. - -@item %I -Like @samp{%i}, but the size is printed in a more readable way by using -@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to -abbreviate. - -@item %l -The current line number of point, counting within the accessible portion -of the buffer. - -@item %n -@samp{Narrow} when narrowing is in effect; nothing otherwise (see -@code{narrow-to-region} in @ref{Narrowing}). - -@item %p -The percentage of the buffer text above the @strong{top} of window, or -@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default mode -line construct truncates this to three characters. - -@item %P -The percentage of the buffer text that is above the @strong{bottom} of -the window (which includes the text visible in the window, as well as -the text above the top), plus @samp{Top} if the top of the buffer is -visible on screen; or @samp{Bottom} or @samp{All}. - -@item %s -The status of the subprocess belonging to the current buffer, obtained with -@code{process-status}. @xref{Process Information}. - -@item %z -The mnemonics of keyboard, terminal, and buffer coding systems. - -@item %Z -Like @samp{%z}, but including the end-of-line format. - -@item %* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{-} otherwise. @xref{Buffer Modification}. - -@item %+ -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{-} otherwise. This differs from @samp{%*} only for a modified -read-only buffer. @xref{Buffer Modification}. - -@item %& -@samp{*} if the buffer is modified, and @samp{-} otherwise. - -@item %[ -An indication of the depth of recursive editing levels (not counting -minibuffer levels): one @samp{[} for each editing level. -@xref{Recursive Editing}. - -@item %] -One @samp{]} for each recursive editing level (not counting minibuffer -levels). - -@item %- -Dashes sufficient to fill the remainder of the mode line. - -@item %% -The character @samp{%}---this is how to include a literal @samp{%} in a -string in which @code{%}-constructs are allowed. -@end table - -The following two @code{%}-constructs are still supported, but they are -obsolete, since you can get the same results with the variables -@code{mode-name} and @code{global-mode-string}. - -@table @code -@item %m -The value of @code{mode-name}. - -@item %M -The value of @code{global-mode-string}. -@end table - -@node Properties in Mode -@subsection Properties in the Mode Line -@cindex text properties in the mode line - - Certain text properties are meaningful in the -mode line. The @code{face} property affects the appearance of text; the -@code{help-echo} property associates help strings with the text, and -@code{keymap} can make the text mouse-sensitive. - - There are four ways to specify text properties for text in the mode -line: - -@enumerate -@item -Put a string with a text property directly into the mode line data -structure. - -@item -Put a text property on a mode line %-construct such as @samp{%12b}; then -the expansion of the %-construct will have that same text property. - -@item -Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to -give @var{elt} a text property specified by @var{props}. - -@item -Use a list containing @code{:eval @var{form}} in the mode line data -structure, and make @var{form} evaluate to a string that has a text -property. -@end enumerate - - You can use the @code{keymap} property to specify a keymap. This -keymap only takes real effect for mouse clicks; binding character keys -and function keys to it has no effect, since it is impossible to move -point into the mode line. - - When the mode line refers to a variable which does not have a -non-@code{nil} @code{risky-local-variable} property, any text -properties given or specified within that variable's values are -ignored. This is because such properties could otherwise specify -functions to be called, and those functions could come from file -local variables. - -@node Header Lines -@subsection Window Header Lines -@cindex header line (of a window) -@cindex window header line - - A window can have a @dfn{header line} at the top, just as it can have -a mode line at the bottom. The header line feature works just like the -mode line feature, except that it's controlled by -@code{header-line-format}: - -@defvar header-line-format -This variable, local in every buffer, specifies how to display the -header line, for windows displaying the buffer. The format of the value -is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). -It is normally @code{nil}, so that ordinary buffers have no header line. -@end defvar - -@defun window-header-line-height &optional window -This function returns the height in pixels of @var{window}'s header -line. @var{window} must be a live window, and defaults to the -selected window. -@end defun - - A window that is just one line tall never displays a header line. A -window that is two lines tall cannot display both a mode line and a -header line at once; if it has a mode line, then it does not display a -header line. - -@node Emulating Mode Line -@subsection Emulating Mode Line Formatting - - You can use the function @code{format-mode-line} to compute the text -that would appear in a mode line or header line based on a certain -mode line construct. - -@defun format-mode-line format &optional face window buffer -This function formats a line of text according to @var{format} as if it -were generating the mode line for @var{window}, but it also returns the -text as a string. The argument @var{window} defaults to the selected -window. If @var{buffer} is non-@code{nil}, all the information used is -taken from @var{buffer}; by default, it comes from @var{window}'s -buffer. - -The value string normally has text properties that correspond to the -faces, keymaps, etc., that the mode line would have. Any character for -which no @code{face} property is specified by @var{format} gets a -default value determined by @var{face}. If @var{face} is @code{t}, that -stands for either @code{mode-line} if @var{window} is selected, -otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or -omitted, that stands for the default face. If @var{face} is an integer, -the value returned by this function will have no text properties. - -You can also specify other valid faces as the value of @var{face}. -If specified, that face provides the @code{face} property for characters -whose face is not specified by @var{format}. - -Note that using @code{mode-line}, @code{mode-line-inactive}, or -@code{header-line} as @var{face} will actually redisplay the mode line -or the header line, respectively, using the current definitions of the -corresponding face, in addition to returning the formatted string. -(Other faces do not cause redisplay.) - -For example, @code{(format-mode-line header-line-format)} returns the -text that would appear in the selected window's header line (@code{""} -if it has no header line). @code{(format-mode-line header-line-format -'header-line)} returns the same text, with each character -carrying the face that it will have in the header line itself, and also -redraws the header line. -@end defun - -@node Imenu -@section Imenu - -@cindex Imenu - @dfn{Imenu} is a feature that lets users select a definition or -section in the buffer, from a menu which lists all of them, to go -directly to that location in the buffer. Imenu works by constructing -a buffer index which lists the names and buffer positions of the -definitions, or other named portions of the buffer; then the user can -choose one of them and move point to it. Major modes can add a menu -bar item to use Imenu using @code{imenu-add-to-menubar}. - -@deffn Command imenu-add-to-menubar name -This function defines a local menu bar item named @var{name} -to run Imenu. -@end deffn - - The user-level commands for using Imenu are described in the Emacs -Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section -explains how to customize Imenu's method of finding definitions or -buffer portions for a particular major mode. - - The usual and simplest way is to set the variable -@code{imenu-generic-expression}: - -@defvar imenu-generic-expression -This variable, if non-@code{nil}, is a list that specifies regular -expressions for finding definitions for Imenu. Simple elements of -@code{imenu-generic-expression} look like this: - -@example -(@var{menu-title} @var{regexp} @var{index}) -@end example - -Here, if @var{menu-title} is non-@code{nil}, it says that the matches -for this element should go in a submenu of the buffer index; -@var{menu-title} itself specifies the name for the submenu. If -@var{menu-title} is @code{nil}, the matches for this element go directly -in the top level of the buffer index. - -The second item in the list, @var{regexp}, is a regular expression -(@pxref{Regular Expressions}); anything in the buffer that it matches -is considered a definition, something to mention in the buffer index. -The third item, @var{index}, is a non-negative integer that indicates -which subexpression in @var{regexp} matches the definition's name. - -An element can also look like this: - -@example -(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{}) -@end example - -Each match for this element creates an index item, and when the index -item is selected by the user, it calls @var{function} with arguments -consisting of the item name, the buffer position, and @var{arguments}. - -For Emacs Lisp mode, @code{imenu-generic-expression} could look like -this: - -@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+] -@example -@group -((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2) -@end group -@group - ("*Vars*" "^\\s-*(def\\(var\\|const\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2) -@end group -@group - ("*Types*" - "^\\s-*\ -(def\\(type\\|struct\\|class\\|ine-condition\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2)) -@end group -@end example - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-case-fold-search -This variable controls whether matching against the regular -expressions in the value of @code{imenu-generic-expression} is -case-sensitive: @code{t}, the default, means matching should ignore -case. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-syntax-alist -This variable is an alist of syntax table modifiers to use while -processing @code{imenu-generic-expression}, to override the syntax table -of the current buffer. Each element should have this form: - -@example -(@var{characters} . @var{syntax-description}) -@end example - -The @sc{car}, @var{characters}, can be either a character or a string. -The element says to give that character or characters the syntax -specified by @var{syntax-description}, which is passed to -@code{modify-syntax-entry} (@pxref{Syntax Table Functions}). - -This feature is typically used to give word syntax to characters which -normally have symbol syntax, and thus to simplify -@code{imenu-generic-expression} and speed up matching. -For example, Fortran mode uses it this way: - -@example -(setq imenu-syntax-alist '(("_$" . "w"))) -@end example - -The @code{imenu-generic-expression} regular expressions can then use -@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this -technique may be inconvenient when the mode needs to limit the initial -character of a name to a smaller set of characters than are allowed in -the rest of a name. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - - Another way to customize Imenu for a major mode is to set the -variables @code{imenu-prev-index-position-function} and -@code{imenu-extract-index-name-function}: - -@defvar imenu-prev-index-position-function -If this variable is non-@code{nil}, its value should be a function that -finds the next ``definition'' to put in the buffer index, scanning -backward in the buffer from point. It should return @code{nil} if it -doesn't find another ``definition'' before point. Otherwise it should -leave point at the place it finds a ``definition'' and return any -non-@code{nil} value. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-extract-index-name-function -If this variable is non-@code{nil}, its value should be a function to -return the name for a definition, assuming point is in that definition -as the @code{imenu-prev-index-position-function} function would leave -it. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - - The last way to customize Imenu for a major mode is to set the -variable @code{imenu-create-index-function}: - -@defvar imenu-create-index-function -This variable specifies the function to use for creating a buffer -index. The function should take no arguments, and return an index -alist for the current buffer. It is called within -@code{save-excursion}, so where it leaves point makes no difference. - -The index alist can have three types of elements. Simple elements -look like this: - -@example -(@var{index-name} . @var{index-position}) -@end example - -Selecting a simple element has the effect of moving to position -@var{index-position} in the buffer. Special elements look like this: - -@example -(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{}) -@end example - -Selecting a special element performs: - -@example -(funcall @var{function} - @var{index-name} @var{index-position} @var{arguments}@dots{}) -@end example - -A nested sub-alist element looks like this: - -@example -(@var{menu-title} . @var{sub-alist}) -@end example - -It creates the submenu @var{menu-title} specified by @var{sub-alist}. - -The default value of @code{imenu-create-index-function} is -@code{imenu-default-create-index-function}. This function calls the -value of @code{imenu-prev-index-position-function} and the value of -@code{imenu-extract-index-name-function} to produce the index alist. -However, if either of these two variables is @code{nil}, the default -function uses @code{imenu-generic-expression} instead. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@node Font Lock Mode -@section Font Lock Mode -@cindex Font Lock mode - - @dfn{Font Lock mode} is a buffer-local minor mode that automatically -attaches @code{face} properties to certain parts of the buffer based on -their syntactic role. How it parses the buffer depends on the major -mode; most major modes define syntactic criteria for which faces to use -in which contexts. This section explains how to customize Font Lock for -a particular major mode. - - Font Lock mode finds text to highlight in two ways: through -syntactic parsing based on the syntax table, and through searching -(usually for regular expressions). Syntactic fontification happens -first; it finds comments and string constants and highlights them. -Search-based fontification happens second. - -@menu -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. -@end menu - -@node Font Lock Basics -@subsection Font Lock Basics - - There are several variables that control how Font Lock mode highlights -text. But major modes should not set any of these variables directly. -Instead, they should set @code{font-lock-defaults} as a buffer-local -variable. The value assigned to this variable is used, if and when Font -Lock mode is enabled, to set all the other variables. - -@defvar font-lock-defaults -This variable is set by major modes to specify how to fontify text in -that mode. It automatically becomes buffer-local when set. If its -value is @code{nil}, Font Lock mode does no highlighting, and you can -use the @samp{Faces} menu (under @samp{Edit} and then @samp{Text -Properties} in the menu bar) to assign faces explicitly to text in the -buffer. - -If non-@code{nil}, the value should look like this: - -@example -(@var{keywords} [@var{keywords-only} [@var{case-fold} - [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]]) -@end example - -The first element, @var{keywords}, indirectly specifies the value of -@code{font-lock-keywords} which directs search-based fontification. -It can be a symbol, a variable or a function whose value is the list -to use for @code{font-lock-keywords}. It can also be a list of -several such symbols, one for each possible level of fontification. -The first symbol specifies the @samp{mode default} level of -fontification, the next symbol level 1 fontification, the next level 2, -and so on. The @samp{mode default} level is normally the same as level -1. It is used when @code{font-lock-maximum-decoration} has a @code{nil} -value. @xref{Levels of Font Lock}. - -The second element, @var{keywords-only}, specifies the value of the -variable @code{font-lock-keywords-only}. If this is omitted or -@code{nil}, syntactic fontification (of strings and comments) is also -performed. If this is non-@code{nil}, syntactic fontification is not -performed. @xref{Syntactic Font Lock}. - -The third element, @var{case-fold}, specifies the value of -@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil}, -Font Lock mode ignores case during search-based fontification. - -If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should -be a list of cons cells of the form @code{(@var{char-or-string} -. @var{string})}. These are used to set up a syntax table for syntactic -fontification; the resulting syntax table is stored in -@code{font-lock-syntax-table}. If @var{syntax-alist} is omitted or -@code{nil}, syntactic fontification uses the syntax table returned by -the @code{syntax-table} function. @xref{Syntax Table Functions}. - -The fifth element, @var{syntax-begin}, specifies the value of -@code{font-lock-beginning-of-syntax-function}. We recommend setting -this variable to @code{nil} and using @code{syntax-begin-function} -instead. - -All the remaining elements (if any) are collectively called -@var{other-vars}. Each of these elements should have the form -@code{(@var{variable} . @var{value})}---which means, make -@var{variable} buffer-local and then set it to @var{value}. You can -use these @var{other-vars} to set other variables that affect -fontification, aside from those you can control with the first five -elements. @xref{Other Font Lock Variables}. -@end defvar - - If your mode fontifies text explicitly by adding -@code{font-lock-face} properties, it can specify @code{(nil t)} for -@code{font-lock-defaults} to turn off all automatic fontification. -However, this is not required; it is possible to fontify some things -using @code{font-lock-face} properties and set up automatic -fontification for other parts of the text. - -@node Search-based Fontification -@subsection Search-based Fontification - - The variable which directly controls search-based fontification is -@code{font-lock-keywords}, which is typically specified via the -@var{keywords} element in @code{font-lock-defaults}. - -@defvar font-lock-keywords -The value of this variable is a list of the keywords to highlight. Lisp -programs should not set this variable directly. Normally, the value is -automatically set by Font Lock mode, using the @var{keywords} element in -@code{font-lock-defaults}. The value can also be altered using the -functions @code{font-lock-add-keywords} and -@code{font-lock-remove-keywords} (@pxref{Customizing Keywords}). -@end defvar - - Each element of @code{font-lock-keywords} specifies how to find -certain cases of text, and how to highlight those cases. Font Lock mode -processes the elements of @code{font-lock-keywords} one by one, and for -each element, it finds and handles all matches. Ordinarily, once -part of the text has been fontified already, this cannot be overridden -by a subsequent match in the same text; but you can specify different -behavior using the @var{override} element of a @var{subexp-highlighter}. - - Each element of @code{font-lock-keywords} should have one of these -forms: - -@table @code -@item @var{regexp} -Highlight all matches for @var{regexp} using -@code{font-lock-keyword-face}. For example, - -@example -;; @r{Highlight occurrences of the word @samp{foo}} -;; @r{using @code{font-lock-keyword-face}.} -"\\" -@end example - -Be careful when composing these regular expressions; a poorly written -pattern can dramatically slow things down! The function -@code{regexp-opt} (@pxref{Regexp Functions}) is useful for calculating -optimal regular expressions to match several keywords. - -@item @var{function} -Find text by calling @var{function}, and highlight the matches -it finds using @code{font-lock-keyword-face}. - -When @var{function} is called, it receives one argument, the limit of -the search; it should begin searching at point, and not search beyond the -limit. It should return non-@code{nil} if it succeeds, and set the -match data to describe the match that was found. Returning @code{nil} -indicates failure of the search. - -Fontification will call @var{function} repeatedly with the same limit, -and with point where the previous invocation left it, until -@var{function} fails. On failure, @var{function} need not reset point -in any particular way. - -@item (@var{matcher} . @var{subexp}) -In this kind of element, @var{matcher} is either a regular -expression or a function, as described above. The @sc{cdr}, -@var{subexp}, specifies which subexpression of @var{matcher} should be -highlighted (instead of the entire text that @var{matcher} matched). - -@example -;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},} -;; @r{using @code{font-lock-keyword-face}.} -("fu\\(bar\\)" . 1) -@end example - -If you use @code{regexp-opt} to produce the regular expression -@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp -Functions}) to calculate the value for @var{subexp}. - -@item (@var{matcher} . @var{facespec}) -In this kind of element, @var{facespec} is an expression whose value -specifies the face to use for highlighting. In the simplest case, -@var{facespec} is a Lisp variable (a symbol) whose value is a face -name. - -@example -;; @r{Highlight occurrences of @samp{fubar},} -;; @r{using the face which is the value of @code{fubar-face}.} -("fubar" . fubar-face) -@end example - -However, @var{facespec} can also evaluate to a list of this form: - -@example -(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) -@end example - -@noindent -to specify the face @var{face} and various additional text properties -to put on the text that matches. If you do this, be sure to add the -other text property names that you set in this way to the value of -@code{font-lock-extra-managed-props} so that the properties will also -be cleared out when they are no longer appropriate. Alternatively, -you can set the variable @code{font-lock-unfontify-region-function} to -a function that clears these properties. @xref{Other Font Lock -Variables}. - -@item (@var{matcher} . @var{subexp-highlighter}) -In this kind of element, @var{subexp-highlighter} is a list -which specifies how to highlight matches found by @var{matcher}. -It has the form: - -@example -(@var{subexp} @var{facespec} [@var{override} [@var{laxmatch}]]) -@end example - -The @sc{car}, @var{subexp}, is an integer specifying which subexpression -of the match to fontify (0 means the entire matching text). The second -subelement, @var{facespec}, is an expression whose value specifies the -face, as described above. - -The last two values in @var{subexp-highlighter}, @var{override} and -@var{laxmatch}, are optional flags. If @var{override} is @code{t}, -this element can override existing fontification made by previous -elements of @code{font-lock-keywords}. If it is @code{keep}, then -each character is fontified if it has not been fontified already by -some other element. If it is @code{prepend}, the face specified by -@var{facespec} is added to the beginning of the @code{font-lock-face} -property. If it is @code{append}, the face is added to the end of the -@code{font-lock-face} property. - -If @var{laxmatch} is non-@code{nil}, it means there should be no error -if there is no subexpression numbered @var{subexp} in @var{matcher}. -Obviously, fontification of the subexpression numbered @var{subexp} will -not occur. However, fontification of other subexpressions (and other -regexps) will continue. If @var{laxmatch} is @code{nil}, and the -specified subexpression is missing, then an error is signaled which -terminates search-based fontification. - -Here are some examples of elements of this kind, and what they do: - -@smallexample -;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using} -;; @r{@code{foo-bar-face}, even if they have already been highlighted.} -;; @r{@code{foo-bar-face} should be a variable whose value is a face.} -("foo\\|bar" 0 foo-bar-face t) - -;; @r{Highlight the first subexpression within each occurrence} -;; @r{that the function @code{fubar-match} finds,} -;; @r{using the face which is the value of @code{fubar-face}.} -(fubar-match 1 fubar-face) -@end smallexample - -@item (@var{matcher} . @var{anchored-highlighter}) -In this kind of element, @var{anchored-highlighter} specifies how to -highlight text that follows a match found by @var{matcher}. So a -match found by @var{matcher} acts as the anchor for further searches -specified by @var{anchored-highlighter}. @var{anchored-highlighter} -is a list of the following form: - -@example -(@var{anchored-matcher} @var{pre-form} @var{post-form} - @var{subexp-highlighters}@dots{}) -@end example - -Here, @var{anchored-matcher}, like @var{matcher}, is either a regular -expression or a function. After a match of @var{matcher} is found, -point is at the end of the match. Now, Font Lock evaluates the form -@var{pre-form}. Then it searches for matches of -@var{anchored-matcher} and uses @var{subexp-highlighters} to highlight -these. A @var{subexp-highlighter} is as described above. Finally, -Font Lock evaluates @var{post-form}. - -The forms @var{pre-form} and @var{post-form} can be used to initialize -before, and cleanup after, @var{anchored-matcher} is used. Typically, -@var{pre-form} is used to move point to some position relative to the -match of @var{matcher}, before starting with @var{anchored-matcher}. -@var{post-form} might be used to move back, before resuming with -@var{matcher}. - -After Font Lock evaluates @var{pre-form}, it does not search for -@var{anchored-matcher} beyond the end of the line. However, if -@var{pre-form} returns a buffer position that is greater than the -position of point after @var{pre-form} is evaluated, then the position -returned by @var{pre-form} is used as the limit of the search instead. -It is generally a bad idea to return a position greater than the end -of the line; in other words, the @var{anchored-matcher} search should -not span lines. - -For example, - -@smallexample -;; @r{Highlight occurrences of the word @samp{item} following} -;; @r{an occurrence of the word @samp{anchor} (on the same line)} -;; @r{in the value of @code{item-face}.} -("\\" "\\" nil nil (0 item-face)) -@end smallexample - -Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore -searching for @samp{item} starts at the end of the match of -@samp{anchor}, and searching for subsequent instances of @samp{anchor} -resumes from where searching for @samp{item} concluded. - -@item (@var{matcher} @var{highlighters}@dots{}) -This sort of element specifies several @var{highlighter} lists for a -single @var{matcher}. A @var{highlighter} list can be of the type -@var{subexp-highlighter} or @var{anchored-highlighter} as described -above. - -For example, - -@smallexample -;; @r{Highlight occurrences of the word @samp{anchor} in the value} -;; @r{of @code{anchor-face}, and subsequent occurrences of the word} -;; @r{@samp{item} (on the same line) in the value of @code{item-face}.} -("\\" (0 anchor-face) - ("\\" nil nil (0 item-face))) -@end smallexample - -@item (eval . @var{form}) -Here @var{form} is an expression to be evaluated the first time -this value of @code{font-lock-keywords} is used in a buffer. -Its value should have one of the forms described in this table. -@end table - -@strong{Warning:} Do not design an element of @code{font-lock-keywords} -to match text which spans lines; this does not work reliably. -For details, see @xref{Multiline Font Lock}. - -You can use @var{case-fold} in @code{font-lock-defaults} to specify -the value of @code{font-lock-keywords-case-fold-search} which says -whether search-based fontification should be case-insensitive. - -@defvar font-lock-keywords-case-fold-search -Non-@code{nil} means that regular expression matching for the sake of -@code{font-lock-keywords} should be case-insensitive. -@end defvar - -@node Customizing Keywords -@subsection Customizing Search-Based Fontification - - You can use @code{font-lock-add-keywords} to add additional -search-based fontification rules to a major mode, and -@code{font-lock-remove-keywords} to remove rules. - -@defun font-lock-add-keywords mode keywords &optional how -This function adds highlighting @var{keywords}, for the current buffer -or for major mode @var{mode}. The argument @var{keywords} should be a -list with the same format as the variable @code{font-lock-keywords}. - -If @var{mode} is a symbol which is a major mode command name, such as -@code{c-mode}, the effect is that enabling Font Lock mode in -@var{mode} will add @var{keywords} to @code{font-lock-keywords}. -Calling with a non-@code{nil} value of @var{mode} is correct only in -your @file{~/.emacs} file. - -If @var{mode} is @code{nil}, this function adds @var{keywords} to -@code{font-lock-keywords} in the current buffer. This way of calling -@code{font-lock-add-keywords} is usually used in mode hook functions. - -By default, @var{keywords} are added at the beginning of -@code{font-lock-keywords}. If the optional argument @var{how} is -@code{set}, they are used to replace the value of -@code{font-lock-keywords}. If @var{how} is any other non-@code{nil} -value, they are added at the end of @code{font-lock-keywords}. - -Some modes provide specialized support you can use in additional -highlighting patterns. See the variables -@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, -and @code{java-font-lock-extra-types}, for example. - -@strong{Warning:} Major mode commands must not call -@code{font-lock-add-keywords} under any circumstances, either directly -or indirectly, except through their mode hooks. (Doing so would lead to -incorrect behavior for some minor modes.) They should set up their -rules for search-based fontification by setting -@code{font-lock-keywords}. -@end defun - -@defun font-lock-remove-keywords mode keywords -This function removes @var{keywords} from @code{font-lock-keywords} -for the current buffer or for major mode @var{mode}. As in -@code{font-lock-add-keywords}, @var{mode} should be a major mode -command name or @code{nil}. All the caveats and requirements for -@code{font-lock-add-keywords} apply here too. -@end defun - - For example, the following code adds two fontification patterns for C -mode: one to fontify the word @samp{FIXME}, even in comments, and -another to fontify the words @samp{and}, @samp{or} and @samp{not} as -keywords. - -@smallexample -(font-lock-add-keywords 'c-mode - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) - ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) -@end smallexample - -@noindent -This example affects only C mode proper. To add the same patterns to C -mode @emph{and} all modes derived from it, do this instead: - -@smallexample -(add-hook 'c-mode-hook - (lambda () - (font-lock-add-keywords nil - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) - ("\\<\\(and\\|or\\|not\\)\\>" . - font-lock-keyword-face))))) -@end smallexample - -@node Other Font Lock Variables -@subsection Other Font Lock Variables - - This section describes additional variables that a major mode can -set by means of @var{other-vars} in @code{font-lock-defaults} -(@pxref{Font Lock Basics}). - -@defvar font-lock-mark-block-function -If this variable is non-@code{nil}, it should be a function that is -called with no arguments, to choose an enclosing range of text for -refontification for the command @kbd{M-o M-o} -(@code{font-lock-fontify-block}). - -The function should report its choice by placing the region around it. -A good choice is a range of text large enough to give proper results, -but not too large so that refontification becomes slow. Typical values -are @code{mark-defun} for programming modes or @code{mark-paragraph} for -textual modes. -@end defvar - -@defvar font-lock-extra-managed-props -This variable specifies additional properties (other than -@code{font-lock-face}) that are being managed by Font Lock mode. It -is used by @code{font-lock-default-unfontify-region}, which normally -only manages the @code{font-lock-face} property. If you want Font -Lock to manage other properties as well, you must specify them in a -@var{facespec} in @code{font-lock-keywords} as well as add them to -this list. @xref{Search-based Fontification}. -@end defvar - -@defvar font-lock-fontify-buffer-function -Function to use for fontifying the buffer. The default value is -@code{font-lock-default-fontify-buffer}. -@end defvar - -@defvar font-lock-unfontify-buffer-function -Function to use for unfontifying the buffer. This is used when -turning off Font Lock mode. The default value is -@code{font-lock-default-unfontify-buffer}. -@end defvar - -@defvar font-lock-fontify-region-function -Function to use for fontifying a region. It should take two -arguments, the beginning and end of the region, and an optional third -argument @var{verbose}. If @var{verbose} is non-@code{nil}, the -function should print status messages. The default value is -@code{font-lock-default-fontify-region}. -@end defvar - -@defvar font-lock-unfontify-region-function -Function to use for unfontifying a region. It should take two -arguments, the beginning and end of the region. The default value is -@code{font-lock-default-unfontify-region}. -@end defvar - -@defun jit-lock-register function &optional contextual -This function tells Font Lock mode to run the Lisp function -@var{function} any time it has to fontify or refontify part of the -current buffer. It calls @var{function} before calling the default -fontification functions, and gives it two arguments, @var{start} and -@var{end}, which specify the region to be fontified or refontified. - -The optional argument @var{contextual}, if non-@code{nil}, forces Font -Lock mode to always refontify a syntactically relevant part of the -buffer, and not just the modified lines. This argument can usually be -omitted. -@end defun - -@defun jit-lock-unregister function -If @var{function} was previously registered as a fontification -function using @code{jit-lock-register}, this function unregisters it. -@end defun - -@node Levels of Font Lock -@subsection Levels of Font Lock - - Some major modes offer three different levels of fontification. You -can define multiple levels by using a list of symbols for @var{keywords} -in @code{font-lock-defaults}. Each symbol specifies one level of -fontification; it is up to the user to choose one of these levels, -normally by setting @code{font-lock-maximum-decoration} (@pxref{Font -Lock,,, emacs, the GNU Emacs Manual}). The chosen level's symbol value -is used to initialize @code{font-lock-keywords}. - - Here are the conventions for how to define the levels of -fontification: - -@itemize @bullet -@item -Level 1: highlight function declarations, file directives (such as include or -import directives), strings and comments. The idea is speed, so only -the most important and top-level components are fontified. - -@item -Level 2: in addition to level 1, highlight all language keywords, -including type names that act like keywords, as well as named constant -values. The idea is that all keywords (either syntactic or semantic) -should be fontified appropriately. - -@item -Level 3: in addition to level 2, highlight the symbols being defined in -function and variable declarations, and all builtin function names, -wherever they appear. -@end itemize - -@node Precalculated Fontification -@subsection Precalculated Fontification - - Some major modes such as @code{list-buffers} and @code{occur} -construct the buffer text programmatically. The easiest way for them -to support Font Lock mode is to specify the faces of text when they -insert the text in the buffer. - - The way to do this is to specify the faces in the text with the -special text property @code{font-lock-face} (@pxref{Special -Properties}). When Font Lock mode is enabled, this property controls -the display, just like the @code{face} property. When Font Lock mode -is disabled, @code{font-lock-face} has no effect on the display. - - It is ok for a mode to use @code{font-lock-face} for some text and -also use the normal Font Lock machinery. But if the mode does not use -the normal Font Lock machinery, it should not set the variable -@code{font-lock-defaults}. - -@node Faces for Font Lock -@subsection Faces for Font Lock -@cindex faces for font lock -@cindex font lock faces - - Font Lock mode can highlight using any face, but Emacs defines several -faces specifically for Font Lock to use to highlight text. These -@dfn{Font Lock faces} are listed below. They can also be used by major -modes for syntactic highlighting outside of Font Lock mode (@pxref{Major -Mode Conventions}). - - Each of these symbols is both a face name, and a variable whose -default value is the symbol itself. Thus, the default value of -@code{font-lock-comment-face} is @code{font-lock-comment-face}. - - The faces are listed with descriptions of their typical usage, and in -order of greater to lesser ``prominence''. If a mode's syntactic -categories do not fit well with the usage descriptions, the faces can be -assigned using the ordering as a guide. - -@table @code -@item font-lock-warning-face -@vindex font-lock-warning-face -for a construct that is peculiar, or that greatly changes the meaning of -other text, like @samp{;;;###autoload} in Emacs Lisp and @samp{#error} -in C. - -@item font-lock-function-name-face -@vindex font-lock-function-name-face -for the name of a function being defined or declared. - -@item font-lock-variable-name-face -@vindex font-lock-variable-name-face -for the name of a variable being defined or declared. - -@item font-lock-keyword-face -@vindex font-lock-keyword-face -for a keyword with special syntactic significance, like @samp{for} and -@samp{if} in C. - -@item font-lock-comment-face -@vindex font-lock-comment-face -for comments. - -@item font-lock-comment-delimiter-face -@vindex font-lock-comment-delimiter-face -for comments delimiters, like @samp{/*} and @samp{*/} in C@. On most -terminals, this inherits from @code{font-lock-comment-face}. - -@item font-lock-type-face -@vindex font-lock-type-face -for the names of user-defined data types. - -@item font-lock-constant-face -@vindex font-lock-constant-face -for the names of constants, like @samp{NULL} in C. - -@item font-lock-builtin-face -@vindex font-lock-builtin-face -for the names of built-in functions. - -@item font-lock-preprocessor-face -@vindex font-lock-preprocessor-face -for preprocessor commands. This inherits, by default, from -@code{font-lock-builtin-face}. - -@item font-lock-string-face -@vindex font-lock-string-face -for string constants. - -@item font-lock-doc-face -@vindex font-lock-doc-face -for documentation strings in the code. This inherits, by default, from -@code{font-lock-string-face}. - -@item font-lock-negation-char-face -@vindex font-lock-negation-char-face -for easily-overlooked negation characters. -@end table - -@node Syntactic Font Lock -@subsection Syntactic Font Lock -@cindex syntactic font lock - -Syntactic fontification uses a syntax table (@pxref{Syntax Tables}) to -find and highlight syntactically relevant text. If enabled, it runs -prior to search-based fontification. The variable -@code{font-lock-syntactic-face-function}, documented below, determines -which syntactic constructs to highlight. There are several variables -that affect syntactic fontification; you should set them by means of -@code{font-lock-defaults} (@pxref{Font Lock Basics}). - - Whenever Font Lock mode performs syntactic fontification on a stretch -of text, it first calls the function specified by -@code{syntax-propertize-function}. Major modes can use this to apply -@code{syntax-table} text properties to override the buffer's syntax -table in special cases. @xref{Syntax Properties}. - -@defvar font-lock-keywords-only -If the value of this variable is non-@code{nil}, Font Lock does not do -syntactic fontification, only search-based fontification based on -@code{font-lock-keywords}. It is normally set by Font Lock mode based -on the @var{keywords-only} element in @code{font-lock-defaults}. -@end defvar - -@defvar font-lock-syntax-table -This variable holds the syntax table to use for fontification of -comments and strings. It is normally set by Font Lock mode based on the -@var{syntax-alist} element in @code{font-lock-defaults}. If this value -is @code{nil}, syntactic fontification uses the buffer's syntax table -(the value returned by the function @code{syntax-table}; @pxref{Syntax -Table Functions}). -@end defvar - -@defvar font-lock-beginning-of-syntax-function -If this variable is non-@code{nil}, it should be a function to move -point back to a position that is syntactically at ``top level'' and -outside of strings or comments. The value is normally set through an -@var{other-vars} element in @code{font-lock-defaults}. If it is -@code{nil}, Font Lock uses @code{syntax-begin-function} to move back -outside of any comment, string, or sexp (@pxref{Position Parse}). - -This variable is semi-obsolete; we usually recommend setting -@code{syntax-begin-function} instead. One of its uses is to tune the -behavior of syntactic fontification, e.g., to ensure that different -kinds of strings or comments are highlighted differently. - -The specified function is called with no arguments. It should leave -point at the beginning of any enclosing syntactic block. Typical values -are @code{beginning-of-line} (used when the start of the line is known -to be outside a syntactic block), or @code{beginning-of-defun} for -programming modes, or @code{backward-paragraph} for textual modes. -@end defvar - -@defvar font-lock-syntactic-face-function -If this variable is non-@code{nil}, it should be a function to determine -which face to use for a given syntactic element (a string or a comment). -The value is normally set through an @var{other-vars} element in -@code{font-lock-defaults}. - -The function is called with one argument, the parse state at point -returned by @code{parse-partial-sexp}, and should return a face. The -default value returns @code{font-lock-comment-face} for comments and -@code{font-lock-string-face} for strings (@pxref{Faces for Font Lock}). -@end defvar - -@node Multiline Font Lock -@subsection Multiline Font Lock Constructs -@cindex multiline font lock - - Normally, elements of @code{font-lock-keywords} should not match -across multiple lines; that doesn't work reliably, because Font Lock -usually scans just part of the buffer, and it can miss a multi-line -construct that crosses the line boundary where the scan starts. (The -scan normally starts at the beginning of a line.) - - Making elements that match multiline constructs work properly has -two aspects: correct @emph{identification} and correct -@emph{rehighlighting}. The first means that Font Lock finds all -multiline constructs. The second means that Font Lock will correctly -rehighlight all the relevant text when a multiline construct is -changed---for example, if some of the text that was previously part of -a multiline construct ceases to be part of it. The two aspects are -closely related, and often getting one of them to work will appear to -make the other also work. However, for reliable results you must -attend explicitly to both aspects. - - There are three ways to ensure correct identification of multiline -constructs: - -@itemize -@item -Add a function to @code{font-lock-extend-region-functions} that does -the @emph{identification} and extends the scan so that the scanned -text never starts or ends in the middle of a multiline construct. -@item -Use the @code{font-lock-fontify-region-function} hook similarly to -extend the scan so that the scanned text never starts or ends in the -middle of a multiline construct. -@item -Somehow identify the multiline construct right when it gets inserted -into the buffer (or at any point after that but before font-lock -tries to highlight it), and mark it with a @code{font-lock-multiline} -which will instruct font-lock not to start or end the scan in the -middle of the construct. -@end itemize - - There are three ways to do rehighlighting of multiline constructs: - -@itemize -@item -Place a @code{font-lock-multiline} property on the construct. This -will rehighlight the whole construct if any part of it is changed. In -some cases you can do this automatically by setting the -@code{font-lock-multiline} variable, which see. -@item -Make sure @code{jit-lock-contextually} is set and rely on it doing its -job. This will only rehighlight the part of the construct that -follows the actual change, and will do it after a short delay. -This only works if the highlighting of the various parts of your -multiline construct never depends on text in subsequent lines. -Since @code{jit-lock-contextually} is activated by default, this can -be an attractive solution. -@item -Place a @code{jit-lock-defer-multiline} property on the construct. -This works only if @code{jit-lock-contextually} is used, and with the -same delay before rehighlighting, but like @code{font-lock-multiline}, -it also handles the case where highlighting depends on -subsequent lines. -@end itemize - -@menu -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Refontify:: Controlling which region gets refontified - after a buffer change. -@end menu - -@node Font Lock Multiline -@subsubsection Font Lock Multiline - - One way to ensure reliable rehighlighting of multiline Font Lock -constructs is to put on them the text property @code{font-lock-multiline}. -It should be present and non-@code{nil} for text that is part of a -multiline construct. - - When Font Lock is about to highlight a range of text, it first -extends the boundaries of the range as necessary so that they do not -fall within text marked with the @code{font-lock-multiline} property. -Then it removes any @code{font-lock-multiline} properties from the -range, and highlights it. The highlighting specification (mostly -@code{font-lock-keywords}) must reinstall this property each time, -whenever it is appropriate. - - @strong{Warning:} don't use the @code{font-lock-multiline} property -on large ranges of text, because that will make rehighlighting slow. - -@defvar font-lock-multiline -If the @code{font-lock-multiline} variable is set to @code{t}, Font -Lock will try to add the @code{font-lock-multiline} property -automatically on multiline constructs. This is not a universal -solution, however, since it slows down Font Lock somewhat. It can -miss some multiline constructs, or make the property larger or smaller -than necessary. - -For elements whose @var{matcher} is a function, the function should -ensure that submatch 0 covers the whole relevant multiline construct, -even if only a small subpart will be highlighted. It is often just as -easy to add the @code{font-lock-multiline} property by hand. -@end defvar - - The @code{font-lock-multiline} property is meant to ensure proper -refontification; it does not automatically identify new multiline -constructs. Identifying the requires that Font Lock mode operate on -large enough chunks at a time. This will happen by accident on many -cases, which may give the impression that multiline constructs magically -work. If you set the @code{font-lock-multiline} variable -non-@code{nil}, this impression will be even stronger, since the -highlighting of those constructs which are found will be properly -updated from then on. But that does not work reliably. - - To find multiline constructs reliably, you must either manually place -the @code{font-lock-multiline} property on the text before Font Lock -mode looks at it, or use @code{font-lock-fontify-region-function}. - -@node Region to Refontify -@subsubsection Region to Fontify after a Buffer Change - - When a buffer is changed, the region that Font Lock refontifies is -by default the smallest sequence of whole lines that spans the change. -While this works well most of the time, sometimes it doesn't---for -example, when a change alters the syntactic meaning of text on an -earlier line. - - You can enlarge (or even reduce) the region to refontify by setting -the following variable: - -@defvar font-lock-extend-after-change-region-function -This buffer-local variable is either @code{nil} or a function for Font -Lock mode to call to determine the region to scan and fontify. - -The function is given three parameters, the standard @var{beg}, -@var{end}, and @var{old-len} from @code{after-change-functions} -(@pxref{Change Hooks}). It should return either a cons of the -beginning and end buffer positions (in that order) of the region to -fontify, or @code{nil} (which means choose the region in the standard -way). This function needs to preserve point, the match-data, and the -current restriction. The region it returns may start or end in the -middle of a line. - -Since this function is called after every buffer change, it should be -reasonably fast. -@end defvar - -@node Auto-Indentation -@section Automatic Indentation of code - -For programming languages, an important feature of a major mode is to -provide automatic indentation. There are two parts: one is to decide what -is the right indentation of a line, and the other is to decide when to -reindent a line. By default, Emacs reindents a line whenever you -type a character in @code{electric-indent-chars}, which by default only -includes Newline. Major modes can add chars to @code{electric-indent-chars} -according to the syntax of the language. - -Deciding what is the right indentation is controlled in Emacs by -@code{indent-line-function} (@pxref{Mode-Specific Indent}). For some modes, -the @emph{right} indentation cannot be known reliably, typically because -indentation is significant so several indentations are valid but with different -meanings. In that case, the mode should set @code{electric-indent-inhibit} to -make sure the line is not constantly re-indented against the user's wishes. - -Writing a good indentation function can be difficult and to a large extent it -is still a black art. Many major mode authors will start by writing a simple -indentation function that works for simple cases, for example by comparing with -the indentation of the previous text line. For most programming languages that -are not really line-based, this tends to scale very poorly: improving -such a function to let it handle more diverse situations tends to become more -and more difficult, resulting in the end with a large, complex, unmaintainable -indentation function which nobody dares to touch. - -A good indentation function will usually need to actually parse the -text, according to the syntax of the language. Luckily, it is not -necessary to parse the text in as much detail as would be needed -for a compiler, but on the other hand, the parser embedded in the -indentation code will want to be somewhat friendly to syntactically -incorrect code. - -Good maintainable indentation functions usually fall into two categories: -either parsing forward from some ``safe'' starting point until the -position of interest, or parsing backward from the position of interest. -Neither of the two is a clearly better choice than the other: parsing -backward is often more difficult than parsing forward because -programming languages are designed to be parsed forward, but for the -purpose of indentation it has the advantage of not needing to -guess a ``safe'' starting point, and it generally enjoys the property -that only a minimum of text will be analyzed to decide the indentation -of a line, so indentation will tend to be less affected by syntax errors in -some earlier unrelated piece of code. Parsing forward on the other hand -is usually easier and has the advantage of making it possible to -reindent efficiently a whole region at a time, with a single parse. - -Rather than write your own indentation function from scratch, it is -often preferable to try and reuse some existing ones or to rely -on a generic indentation engine. There are sadly few such -engines. The CC-mode indentation code (used with C, C++, Java, Awk -and a few other such modes) has been made more generic over the years, -so if your language seems somewhat similar to one of those languages, -you might try to use that engine. @c FIXME: documentation? -Another one is SMIE which takes an approach in the spirit -of Lisp sexps and adapts it to non-Lisp languages. - -@menu -* SMIE:: A simple minded indentation engine. -@end menu - -@node SMIE -@subsection Simple Minded Indentation Engine -@cindex SMIE - -SMIE is a package that provides a generic navigation and indentation -engine. Based on a very simple parser using an ``operator precedence -grammar'', it lets major modes extend the sexp-based navigation of Lisp -to non-Lisp languages as well as provide a simple to use but reliable -auto-indentation. - -Operator precedence grammar is a very primitive technology for parsing -compared to some of the more common techniques used in compilers. -It has the following characteristics: its parsing power is very limited, -and it is largely unable to detect syntax errors, but it has the -advantage of being algorithmically efficient and able to parse forward -just as well as backward. In practice that means that SMIE can use it -for indentation based on backward parsing, that it can provide both -@code{forward-sexp} and @code{backward-sexp} functionality, and that it -will naturally work on syntactically incorrect code without any extra -effort. The downside is that it also means that most programming -languages cannot be parsed correctly using SMIE, at least not without -resorting to some special tricks (@pxref{SMIE Tricks}). - -@menu -* SMIE setup:: SMIE setup and features. -* Operator Precedence Grammars:: A very simple parsing technique. -* SMIE Grammar:: Defining the grammar of a language. -* SMIE Lexer:: Defining tokens. -* SMIE Tricks:: Working around the parser's limitations. -* SMIE Indentation:: Specifying indentation rules. -* SMIE Indentation Helpers:: Helper functions for indentation rules. -* SMIE Indentation Example:: Sample indentation rules. -* SMIE Customization:: Customizing indentation. -@end menu - -@node SMIE setup -@subsubsection SMIE Setup and Features - -SMIE is meant to be a one-stop shop for structural navigation and -various other features which rely on the syntactic structure of code, in -particular automatic indentation. The main entry point is -@code{smie-setup} which is a function typically called while setting -up a major mode. - -@defun smie-setup grammar rules-function &rest keywords -Setup SMIE navigation and indentation. -@var{grammar} is a grammar table generated by @code{smie-prec2->grammar}. -@var{rules-function} is a set of indentation rules for use on -@code{smie-rules-function}. -@var{keywords} are additional arguments, which can include the following -keywords: -@itemize -@item -@code{:forward-token} @var{fun}: Specify the forward lexer to use. -@item -@code{:backward-token} @var{fun}: Specify the backward lexer to use. -@end itemize -@end defun - -Calling this function is sufficient to make commands such as -@code{forward-sexp}, @code{backward-sexp}, and @code{transpose-sexps} be -able to properly handle structural elements other than just the paired -parentheses already handled by syntax tables. For example, if the -provided grammar is precise enough, @code{transpose-sexps} can correctly -transpose the two arguments of a @code{+} operator, taking into account -the precedence rules of the language. - -Calling `smie-setup' is also sufficient to make TAB indentation work in -the expected way, extends @code{blink-matching-paren} to apply to -elements like @code{begin...end}, and provides some commands that you -can bind in the major mode keymap. - -@deffn Command smie-close-block -This command closes the most recently opened (and not yet closed) block. -@end deffn - -@deffn Command smie-down-list &optional arg -This command is like @code{down-list} but it also pays attention to -nesting of tokens other than parentheses, such as @code{begin...end}. -@end deffn - -@node Operator Precedence Grammars -@subsubsection Operator Precedence Grammars - -SMIE's precedence grammars simply give to each token a pair of -precedences: the left-precedence and the right-precedence. We say -@code{T1 < T2} if the right-precedence of token @code{T1} is less than -the left-precedence of token @code{T2}. A good way to read this -@code{<} is as a kind of parenthesis: if we find @code{... T1 something -T2 ...} then that should be parsed as @code{... T1 (something T2 ...} -rather than as @code{... T1 something) T2 ...}. The latter -interpretation would be the case if we had @code{T1 > T2}. If we have -@code{T1 = T2}, it means that token T2 follows token T1 in the same -syntactic construction, so typically we have @code{"begin" = "end"}. -Such pairs of precedences are sufficient to express left-associativity -or right-associativity of infix operators, nesting of tokens like -parentheses and many other cases. - -@c Let's leave this undocumented to leave it more open for change! -@c @defvar smie-grammar -@c The value of this variable is an alist specifying the left and right -@c precedence of each token. It is meant to be initialized by using one of -@c the functions below. -@c @end defvar - -@defun smie-prec2->grammar table -This function takes a @emph{prec2} grammar @var{table} and returns an -alist suitable for use in @code{smie-setup}. The @emph{prec2} -@var{table} is itself meant to be built by one of the functions below. -@end defun - -@defun smie-merge-prec2s &rest tables -This function takes several @emph{prec2} @var{tables} and merges them -into a new @emph{prec2} table. -@end defun - -@defun smie-precs->prec2 precs -This function builds a @emph{prec2} table from a table of precedences -@var{precs}. @var{precs} should be a list, sorted by precedence (for -example @code{"+"} will come before @code{"*"}), of elements of the form -@code{(@var{assoc} @var{op} ...)}, where each @var{op} is a token that -acts as an operator; @var{assoc} is their associativity, which can be -either @code{left}, @code{right}, @code{assoc}, or @code{nonassoc}. -All operators in a given element share the same precedence level -and associativity. -@end defun - -@defun smie-bnf->prec2 bnf &rest resolvers -This function lets you specify the grammar using a BNF notation. -It accepts a @var{bnf} description of the grammar along with a set of -conflict resolution rules @var{resolvers}, and -returns a @emph{prec2} table. - -@var{bnf} is a list of nonterminal definitions of the form -@code{(@var{nonterm} @var{rhs1} @var{rhs2} ...)} where each @var{rhs} -is a (non-empty) list of terminals (aka tokens) or non-terminals. - -Not all grammars are accepted: -@itemize -@item -An @var{rhs} cannot be an empty list (an empty list is never needed, -since SMIE allows all non-terminals to match the empty string anyway). -@item -An @var{rhs} cannot have 2 consecutive non-terminals: each pair of -non-terminals needs to be separated by a terminal (aka token). -This is a fundamental limitation of operator precedence grammars. -@end itemize - -Additionally, conflicts can occur: -@itemize -@item -The returned @emph{prec2} table holds constraints between pairs of tokens, and -for any given pair only one constraint can be present: T1 < T2, -T1 = T2, or T1 > T2. -@item -A token can be an @code{opener} (something similar to an open-paren), -a @code{closer} (like a close-paren), or @code{neither} of the two -(e.g., an infix operator, or an inner token like @code{"else"}). -@end itemize - -Precedence conflicts can be resolved via @var{resolvers}, which -is a list of @emph{precs} tables (see @code{smie-precs->prec2}): for -each precedence conflict, if those @code{precs} tables -specify a particular constraint, then the conflict is resolved by using -this constraint instead, else a conflict is reported and one of the -conflicting constraints is picked arbitrarily and the others are -simply ignored. -@end defun - -@node SMIE Grammar -@subsubsection Defining the Grammar of a Language -@cindex SMIE grammar -@cindex grammar, SMIE - -The usual way to define the SMIE grammar of a language is by -defining a new global variable that holds the precedence table by -giving a set of BNF rules. -For example, the grammar definition for a small Pascal-like language -could look like: -@example -@group -(require 'smie) -(defvar sample-smie-grammar - (smie-prec2->grammar - (smie-bnf->prec2 -@end group -@group - '((id) - (inst ("begin" insts "end") - ("if" exp "then" inst "else" inst) - (id ":=" exp) - (exp)) - (insts (insts ";" insts) (inst)) - (exp (exp "+" exp) - (exp "*" exp) - ("(" exps ")")) - (exps (exps "," exps) (exp))) -@end group -@group - '((assoc ";")) - '((assoc ",")) - '((assoc "+") (assoc "*"))))) -@end group -@end example - -@noindent -A few things to note: - -@itemize -@item -The above grammar does not explicitly mention the syntax of function -calls: SMIE will automatically allow any sequence of sexps, such as -identifiers, balanced parentheses, or @code{begin ... end} blocks -to appear anywhere anyway. -@item -The grammar category @code{id} has no right hand side: this does not -mean that it can match only the empty string, since as mentioned any -sequence of sexps can appear anywhere anyway. -@item -Because non terminals cannot appear consecutively in the BNF grammar, it -is difficult to correctly handle tokens that act as terminators, so the -above grammar treats @code{";"} as a statement @emph{separator} instead, -which SMIE can handle very well. -@item -Separators used in sequences (such as @code{","} and @code{";"} above) -are best defined with BNF rules such as @code{(foo (foo "separator" foo) ...)} -which generate precedence conflicts which are then resolved by giving -them an explicit @code{(assoc "separator")}. -@item -The @code{("(" exps ")")} rule was not needed to pair up parens, since -SMIE will pair up any characters that are marked as having paren syntax -in the syntax table. What this rule does instead (together with the -definition of @code{exps}) is to make it clear that @code{","} should -not appear outside of parentheses. -@item -Rather than have a single @emph{precs} table to resolve conflicts, it is -preferable to have several tables, so as to let the BNF part of the -grammar specify relative precedences where possible. -@item -Unless there is a very good reason to prefer @code{left} or -@code{right}, it is usually preferable to mark operators as associative, -using @code{assoc}. For that reason @code{"+"} and @code{"*"} are -defined above as @code{assoc}, although the language defines them -formally as left associative. -@end itemize - -@node SMIE Lexer -@subsubsection Defining Tokens -@cindex SMIE lexer -@cindex defining tokens, SMIE - -SMIE comes with a predefined lexical analyzer which uses syntax tables -in the following way: any sequence of characters that have word or -symbol syntax is considered a token, and so is any sequence of -characters that have punctuation syntax. This default lexer is -often a good starting point but is rarely actually correct for any given -language. For example, it will consider @code{"2,+3"} to be composed -of 3 tokens: @code{"2"}, @code{",+"}, and @code{"3"}. - -To describe the lexing rules of your language to SMIE, you need -2 functions, one to fetch the next token, and another to fetch the -previous token. Those functions will usually first skip whitespace and -comments and then look at the next chunk of text to see if it -is a special token. If so it should skip the token and -return a description of this token. Usually this is simply the string -extracted from the buffer, but it can be anything you want. -For example: -@example -@group -(defvar sample-keywords-regexp - (regexp-opt '("+" "*" "," ";" ">" ">=" "<" "<=" ":=" "="))) -@end group -@group -(defun sample-smie-forward-token () - (forward-comment (point-max)) - (cond - ((looking-at sample-keywords-regexp) - (goto-char (match-end 0)) - (match-string-no-properties 0)) - (t (buffer-substring-no-properties - (point) - (progn (skip-syntax-forward "w_") - (point)))))) -@end group -@group -(defun sample-smie-backward-token () - (forward-comment (- (point))) - (cond - ((looking-back sample-keywords-regexp (- (point) 2) t) - (goto-char (match-beginning 0)) - (match-string-no-properties 0)) - (t (buffer-substring-no-properties - (point) - (progn (skip-syntax-backward "w_") - (point)))))) -@end group -@end example - -Notice how those lexers return the empty string when in front of -parentheses. This is because SMIE automatically takes care of the -parentheses defined in the syntax table. More specifically if the lexer -returns nil or an empty string, SMIE tries to handle the corresponding -text as a sexp according to syntax tables. - -@node SMIE Tricks -@subsubsection Living With a Weak Parser - -The parsing technique used by SMIE does not allow tokens to behave -differently in different contexts. For most programming languages, this -manifests itself by precedence conflicts when converting the -BNF grammar. - -Sometimes, those conflicts can be worked around by expressing the -grammar slightly differently. For example, for Modula-2 it might seem -natural to have a BNF grammar that looks like this: - -@example - ... - (inst ("IF" exp "THEN" insts "ELSE" insts "END") - ("CASE" exp "OF" cases "END") - ...) - (cases (cases "|" cases) - (caselabel ":" insts) - ("ELSE" insts)) - ... -@end example - -But this will create conflicts for @code{"ELSE"}: on the one hand, the -IF rule implies (among many other things) that @code{"ELSE" = "END"}; -but on the other hand, since @code{"ELSE"} appears within @code{cases}, -which appears left of @code{"END"}, we also have @code{"ELSE" > "END"}. -We can solve the conflict either by using: -@example - ... - (inst ("IF" exp "THEN" insts "ELSE" insts "END") - ("CASE" exp "OF" cases "END") - ("CASE" exp "OF" cases "ELSE" insts "END") - ...) - (cases (cases "|" cases) (caselabel ":" insts)) - ... -@end example -or -@example - ... - (inst ("IF" exp "THEN" else "END") - ("CASE" exp "OF" cases "END") - ...) - (else (insts "ELSE" insts)) - (cases (cases "|" cases) (caselabel ":" insts) (else)) - ... -@end example - -Reworking the grammar to try and solve conflicts has its downsides, tho, -because SMIE assumes that the grammar reflects the logical structure of -the code, so it is preferable to keep the BNF closer to the intended -abstract syntax tree. - -Other times, after careful consideration you may conclude that those -conflicts are not serious and simply resolve them via the -@var{resolvers} argument of @code{smie-bnf->prec2}. Usually this is -because the grammar is simply ambiguous: the conflict does not affect -the set of programs described by the grammar, but only the way those -programs are parsed. This is typically the case for separators and -associative infix operators, where you want to add a resolver like -@code{'((assoc "|"))}. Another case where this can happen is for the -classic @emph{dangling else} problem, where you will use @code{'((assoc -"else" "then"))}. It can also happen for cases where the conflict is -real and cannot really be resolved, but it is unlikely to pose a problem -in practice. - -Finally, in many cases some conflicts will remain despite all efforts to -restructure the grammar. Do not despair: while the parser cannot be -made more clever, you can make the lexer as smart as you want. So, the -solution is then to look at the tokens involved in the conflict and to -split one of those tokens into 2 (or more) different tokens. E.g., if -the grammar needs to distinguish between two incompatible uses of the -token @code{"begin"}, make the lexer return different tokens (say -@code{"begin-fun"} and @code{"begin-plain"}) depending on which kind of -@code{"begin"} it finds. This pushes the work of distinguishing the -different cases to the lexer, which will thus have to look at the -surrounding text to find ad-hoc clues. - -@node SMIE Indentation -@subsubsection Specifying Indentation Rules -@cindex indentation rules, SMIE - -Based on the provided grammar, SMIE will be able to provide automatic -indentation without any extra effort. But in practice, this default -indentation style will probably not be good enough. You will want to -tweak it in many different cases. - -SMIE indentation is based on the idea that indentation rules should be -as local as possible. To this end, it relies on the idea of -@emph{virtual} indentation, which is the indentation that a particular -program point would have if it were at the beginning of a line. -Of course, if that program point is indeed at the beginning of a line, -its virtual indentation is its current indentation. But if not, then -SMIE uses the indentation algorithm to compute the virtual indentation -of that point. Now in practice, the virtual indentation of a program -point does not have to be identical to the indentation it would have if -we inserted a newline before it. To see how this works, the SMIE rule -for indentation after a @code{@{} in C does not care whether the -@code{@{} is standing on a line of its own or is at the end of the -preceding line. Instead, these different cases are handled in the -indentation rule that decides how to indent before a @code{@{}. - -Another important concept is the notion of @emph{parent}: The -@emph{parent} of a token, is the head token of the nearest enclosing -syntactic construct. For example, the parent of an @code{else} is the -@code{if} to which it belongs, and the parent of an @code{if}, in turn, -is the lead token of the surrounding construct. The command -@code{backward-sexp} jumps from a token to its parent, but there are -some caveats: for @emph{openers} (tokens which start a construct, like -@code{if}), you need to start with point before the token, while for -others you need to start with point after the token. -@code{backward-sexp} stops with point before the parent token if that is -the @emph{opener} of the token of interest, and otherwise it stops with -point after the parent token. - -SMIE indentation rules are specified using a function that takes two -arguments @var{method} and @var{arg} where the meaning of @var{arg} and the -expected return value depend on @var{method}. - -@var{method} can be: -@itemize -@item -@code{:after}, in which case @var{arg} is a token and the function -should return the @var{offset} to use for indentation after @var{arg}. -@item -@code{:before}, in which case @var{arg} is a token and the function -should return the @var{offset} to use to indent @var{arg} itself. -@item -@code{:elem}, in which case the function should return either the offset -to use to indent function arguments (if @var{arg} is the symbol -@code{arg}) or the basic indentation step (if @var{arg} is the symbol -@code{basic}). -@item -@code{:list-intro}, in which case @var{arg} is a token and the function -should return non-@code{nil} if the token is followed by a list of -expressions (not separated by any token) rather than an expression. -@end itemize - -When @var{arg} is a token, the function is called with point just before -that token. A return value of @code{nil} always means to fallback on the -default behavior, so the function should return @code{nil} for arguments it -does not expect. - -@var{offset} can be: -@itemize -@item -@code{nil}: use the default indentation rule. -@item -@code{(column . @var{column})}: indent to column @var{column}. -@item -@var{number}: offset by @var{number}, relative to a base token which is -the current token for @code{:after} and its parent for @code{:before}. -@end itemize - -@node SMIE Indentation Helpers -@subsubsection Helper Functions for Indentation Rules - -SMIE provides various functions designed specifically for use in the -indentation rules function (several of those functions break if used in -another context). These functions all start with the prefix -@code{smie-rule-}. - -@defun smie-rule-bolp -Return non-@code{nil} if the current token is the first on the line. -@end defun - -@defun smie-rule-hanging-p -Return non-@code{nil} if the current token is @emph{hanging}. -A token is @emph{hanging} if it is the last token on the line -and if it is preceded by other tokens: a lone token on a line is not -hanging. -@end defun - -@defun smie-rule-next-p &rest tokens -Return non-@code{nil} if the next token is among @var{tokens}. -@end defun - -@defun smie-rule-prev-p &rest tokens -Return non-@code{nil} if the previous token is among @var{tokens}. -@end defun - -@defun smie-rule-parent-p &rest parents -Return non-@code{nil} if the current token's parent is among @var{parents}. -@end defun - -@defun smie-rule-sibling-p -Return non-@code{nil} if the current token's parent is actually a -sibling. This is the case for example when the parent of a @code{","} -is just the previous @code{","}. -@end defun - -@defun smie-rule-parent &optional offset -Return the proper offset to align the current token with the parent. -If non-@code{nil}, @var{offset} should be an integer giving an -additional offset to apply. -@end defun - -@defun smie-rule-separator method -Indent current token as a @emph{separator}. - -By @emph{separator}, we mean here a token whose sole purpose is to -separate various elements within some enclosing syntactic construct, and -which does not have any semantic significance in itself (i.e., it would -typically not exist as a node in an abstract syntax tree). - -Such a token is expected to have an associative syntax and be closely -tied to its syntactic parent. Typical examples are @code{","} in lists -of arguments (enclosed inside parentheses), or @code{";"} in sequences -of instructions (enclosed in a @code{@{...@}} or @code{begin...end} -block). - -@var{method} should be the method name that was passed to -`smie-rules-function'. -@end defun - -@node SMIE Indentation Example -@subsubsection Sample Indentation Rules - -Here is an example of an indentation function: - -@example -(defun sample-smie-rules (kind token) - (pcase (cons kind token) - (`(:elem . basic) sample-indent-basic) - (`(,_ . ",") (smie-rule-separator kind)) - (`(:after . ":=") sample-indent-basic) - (`(:before . ,(or `"begin" `"(" `"@{"))) - (if (smie-rule-hanging-p) (smie-rule-parent))) - (`(:before . "if") - (and (not (smie-rule-bolp)) (smie-rule-prev-p "else") - (smie-rule-parent))))) -@end example - -@noindent -A few things to note: - -@itemize -@item -The first case indicates the basic indentation increment to use. -If @code{sample-indent-basic} is @code{nil}, then SMIE uses the global -setting @code{smie-indent-basic}. The major mode could have set -@code{smie-indent-basic} buffer-locally instead, but that -is discouraged. - -@item -The rule for the token @code{","} make SMIE try to be more clever when -the comma separator is placed at the beginning of lines. It tries to -outdent the separator so as to align the code after the comma; for -example: - -@example -x = longfunctionname ( - arg1 - , arg2 - ); -@end example - -@item -The rule for indentation after @code{":="} exists because otherwise -SMIE would treat @code{":="} as an infix operator and would align the -right argument with the left one. - -@item -The rule for indentation before @code{"begin"} is an example of the use -of virtual indentation: This rule is used only when @code{"begin"} is -hanging, which can happen only when @code{"begin"} is not at the -beginning of a line. So this is not used when indenting -@code{"begin"} itself but only when indenting something relative to this -@code{"begin"}. Concretely, this rule changes the indentation from: - -@example - if x > 0 then begin - dosomething(x); - end -@end example -to -@example - if x > 0 then begin - dosomething(x); - end -@end example - -@item -The rule for indentation before @code{"if"} is similar to the one for -@code{"begin"}, but where the purpose is to treat @code{"else if"} -as a single unit, so as to align a sequence of tests rather than indent -each test further to the right. This function does this only in the -case where the @code{"if"} is not placed on a separate line, hence the -@code{smie-rule-bolp} test. - -If we know that the @code{"else"} is always aligned with its @code{"if"} -and is always at the beginning of a line, we can use a more efficient -rule: -@example -((equal token "if") - (and (not (smie-rule-bolp)) - (smie-rule-prev-p "else") - (save-excursion - (sample-smie-backward-token) - (cons 'column (current-column))))) -@end example - -The advantage of this formulation is that it reuses the indentation of -the previous @code{"else"}, rather than going all the way back to the -first @code{"if"} of the sequence. -@end itemize - -@c In some sense this belongs more in the Emacs manual. -@node SMIE Customization -@subsubsection Customizing Indentation - -If you are using a mode whose indentation is provided by SMIE, you can -customize the indentation to suit your preferences. You can do this -on a per-mode basis (using the option @code{smie-config}), or a -per-file basis (using the function @code{smie-config-local} in a -file-local variable specification). - -@defopt smie-config -This option lets you customize indentation on a per-mode basis. -It is an alist with elements of the form @code{(@var{mode} . @var{rules})}. -For the precise form of rules, see the variable's documentation; but -you may find it easier to use the command @code{smie-config-guess}. -@end defopt - -@deffn Command smie-config-guess -This command tries to work out appropriate settings to produce -your preferred style of indentation. Simply call the command while -visiting a file that is indented with your style. -@end deffn - -@deffn Command smie-config-save -Call this command after using @code{smie-config-guess}, to save your -settings for future sessions. -@end deffn - -@deffn Command smie-config-show-indent &optional move -This command displays the rules that are used to indent the current -line. -@end deffn - -@deffn Command smie-config-set-indent -This command adds a local rule to adjust the indentation of the current line. -@end deffn - -@defun smie-config-local rules -This function adds @var{rules} as indentation rules for the current buffer. -These add to any mode-specific rules defined by the @code{smie-config} option. -To specify custom indentation rules for a specific file, add an entry -to the file's local variables of the form: -@code{eval: (smie-config-local '(@var{rules}))}. -@end defun - - -@node Desktop Save Mode -@section Desktop Save Mode -@cindex desktop save mode - -@dfn{Desktop Save Mode} is a feature to save the state of Emacs from -one session to another. The user-level commands for using Desktop -Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs -Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit -a file, don't have to do anything to use this feature. - -For buffers not visiting a file to have their state saved, the major -mode must bind the buffer local variable @code{desktop-save-buffer} to -a non-@code{nil} value. - -@defvar desktop-save-buffer -If this buffer-local variable is non-@code{nil}, the buffer will have -its state saved in the desktop file at desktop save. If the value is -a function, it is called at desktop save with argument -@var{desktop-dirname}, and its value is saved in the desktop file along -with the state of the buffer for which it was called. When file names -are returned as part of the auxiliary information, they should be -formatted using the call - -@example -(desktop-file-name @var{file-name} @var{desktop-dirname}) -@end example - -@end defvar - -For buffers not visiting a file to be restored, the major mode must -define a function to do the job, and that function must be listed in -the alist @code{desktop-buffer-mode-handlers}. - -@defvar desktop-buffer-mode-handlers -Alist with elements - -@example -(@var{major-mode} . @var{restore-buffer-function}) -@end example - -The function @var{restore-buffer-function} will be called with -argument list - -@example -(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc}) -@end example - -and it should return the restored buffer. -Here @var{desktop-buffer-misc} is the value returned by the function -optionally bound to @code{desktop-save-buffer}. -@end defvar diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi deleted file mode 100644 index d5bfacca976..00000000000 --- a/doc/lispref/nonascii.texi +++ /dev/null @@ -1,1977 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Non-ASCII Characters -@chapter Non-@acronym{ASCII} Characters -@cindex multibyte characters -@cindex characters, multi-byte -@cindex non-@acronym{ASCII} characters - - This chapter covers the special issues relating to characters and -how they are stored in strings and buffers. - -@menu -* Text Representations:: How Emacs represents text. -* Disabling Multibyte:: Controlling whether to use multibyte characters. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. -@end menu - -@node Text Representations -@section Text Representations -@cindex text representation - - Emacs buffers and strings support a large repertoire of characters -from many different scripts, allowing users to type and display text -in almost any known written language. - -@cindex character codepoint -@cindex codespace -@cindex Unicode - To support this multitude of characters and scripts, Emacs closely -follows the @dfn{Unicode Standard}. The Unicode Standard assigns a -unique number, called a @dfn{codepoint}, to each and every character. -The range of codepoints defined by Unicode, or the Unicode -@dfn{codespace}, is @code{0..#x10FFFF} (in hexadecimal notation), -inclusive. Emacs extends this range with codepoints in the range -@code{#x110000..#x3FFFFF}, which it uses for representing characters -that are not unified with Unicode and @dfn{raw 8-bit bytes} that -cannot be interpreted as characters. Thus, a character codepoint in -Emacs is a 22-bit integer. - -@cindex internal representation of characters -@cindex characters, representation in buffers and strings -@cindex multibyte text - To conserve memory, Emacs does not hold fixed-length 22-bit numbers -that are codepoints of text characters within buffers and strings. -Rather, Emacs uses a variable-length internal representation of -characters, that stores each character as a sequence of 1 to 5 8-bit -bytes, depending on the magnitude of its codepoint@footnote{ -This internal representation is based on one of the encodings defined -by the Unicode Standard, called @dfn{UTF-8}, for representing any -Unicode codepoint, but Emacs extends UTF-8 to represent the additional -codepoints it uses for raw 8-bit bytes and characters not unified with -Unicode.}. For example, any @acronym{ASCII} character takes up only 1 -byte, a Latin-1 character takes up 2 bytes, etc. We call this -representation of text @dfn{multibyte}. - - Outside Emacs, characters can be represented in many different -encodings, such as ISO-8859-1, GB-2312, Big-5, etc. Emacs converts -between these external encodings and its internal representation, as -appropriate, when it reads text into a buffer or a string, or when it -writes text to a disk file or passes it to some other process. - - Occasionally, Emacs needs to hold and manipulate encoded text or -binary non-text data in its buffers or strings. For example, when -Emacs visits a file, it first reads the file's text verbatim into a -buffer, and only then converts it to the internal representation. -Before the conversion, the buffer holds encoded text. - -@cindex unibyte text - Encoded text is not really text, as far as Emacs is concerned, but -rather a sequence of raw 8-bit bytes. We call buffers and strings -that hold encoded text @dfn{unibyte} buffers and strings, because -Emacs treats them as a sequence of individual bytes. Usually, Emacs -displays unibyte buffers and strings as octal codes such as -@code{\237}. We recommend that you never use unibyte buffers and -strings except for manipulating encoded text or binary non-text data. - - In a buffer, the buffer-local value of the variable -@code{enable-multibyte-characters} specifies the representation used. -The representation for a string is determined and recorded in the string -when the string is constructed. - -@defvar enable-multibyte-characters -This variable specifies the current buffer's text representation. -If it is non-@code{nil}, the buffer contains multibyte text; otherwise, -it contains unibyte encoded text or binary non-text data. - -You cannot set this variable directly; instead, use the function -@code{set-buffer-multibyte} to change a buffer's representation. -@end defvar - -@defun position-bytes position -Buffer positions are measured in character units. This function -returns the byte-position corresponding to buffer position -@var{position} in the current buffer. This is 1 at the start of the -buffer, and counts upward in bytes. If @var{position} is out of -range, the value is @code{nil}. -@end defun - -@defun byte-to-position byte-position -Return the buffer position, in character units, corresponding to given -@var{byte-position} in the current buffer. If @var{byte-position} is -out of range, the value is @code{nil}. In a multibyte buffer, an -arbitrary value of @var{byte-position} can be not at character -boundary, but inside a multibyte sequence representing a single -character; in this case, this function returns the buffer position of -the character whose multibyte sequence includes @var{byte-position}. -In other words, the value does not change for all byte positions that -belong to the same character. -@end defun - -@defun multibyte-string-p string -Return @code{t} if @var{string} is a multibyte string, @code{nil} -otherwise. This function also returns @code{nil} if @var{string} is -some object other than a string. -@end defun - -@defun string-bytes string -@cindex string, number of bytes -This function returns the number of bytes in @var{string}. -If @var{string} is a multibyte string, this can be greater than -@code{(length @var{string})}. -@end defun - -@defun unibyte-string &rest bytes -This function concatenates all its argument @var{bytes} and makes the -result a unibyte string. -@end defun - -@node Disabling Multibyte -@section Disabling Multibyte Characters -@cindex disabling multibyte - - By default, Emacs starts in multibyte mode: it stores the contents -of buffers and strings using an internal encoding that represents -non-@acronym{ASCII} characters using multi-byte sequences. Multibyte -mode allows you to use all the supported languages and scripts without -limitations. - -@cindex turn multibyte support on or off - Under very special circumstances, you may want to disable multibyte -character support, for a specific buffer. -When multibyte characters are disabled in a buffer, we call -that @dfn{unibyte mode}. In unibyte mode, each character in the -buffer has a character code ranging from 0 through 255 (0377 octal); 0 -through 127 (0177 octal) represent @acronym{ASCII} characters, and 128 -(0200 octal) through 255 (0377 octal) represent non-@acronym{ASCII} -characters. - - To edit a particular file in unibyte representation, visit it using -@code{find-file-literally}. @xref{Visiting Functions}. You can -convert a multibyte buffer to unibyte by saving it to a file, killing -the buffer, and visiting the file again with -@code{find-file-literally}. Alternatively, you can use @kbd{C-x -@key{RET} c} (@code{universal-coding-system-argument}) and specify -@samp{raw-text} as the coding system with which to visit or save a -file. @xref{Text Coding, , Specifying a Coding System for File Text, -emacs, GNU Emacs Manual}. Unlike @code{find-file-literally}, finding -a file as @samp{raw-text} doesn't disable format conversion, -uncompression, or auto mode selection. - -@c See http://debbugs.gnu.org/11226 for lack of unibyte tooltip. -@vindex enable-multibyte-characters -The buffer-local variable @code{enable-multibyte-characters} is -non-@code{nil} in multibyte buffers, and @code{nil} in unibyte ones. -The mode line also indicates whether a buffer is multibyte or not. -With a graphical display, in a multibyte buffer, the portion of the -mode line that indicates the character set has a tooltip that (amongst -other things) says that the buffer is multibyte. In a unibyte buffer, -the character set indicator is absent. Thus, in a unibyte buffer -(when using a graphical display) there is normally nothing before the -indication of the visited file's end-of-line convention (colon, -backslash, etc.), unless you are using an input method. - -@findex toggle-enable-multibyte-characters -You can turn off multibyte support in a specific buffer by invoking the -command @code{toggle-enable-multibyte-characters} in that buffer. - -@node Converting Representations -@section Converting Text Representations - - Emacs can convert unibyte text to multibyte; it can also convert -multibyte text to unibyte, provided that the multibyte text contains -only @acronym{ASCII} and 8-bit raw bytes. In general, these -conversions happen when inserting text into a buffer, or when putting -text from several strings together in one string. You can also -explicitly convert a string's contents to either representation. - - Emacs chooses the representation for a string based on the text from -which it is constructed. The general rule is to convert unibyte text -to multibyte text when combining it with other multibyte text, because -the multibyte representation is more general and can hold whatever -characters the unibyte text has. - - When inserting text into a buffer, Emacs converts the text to the -buffer's representation, as specified by -@code{enable-multibyte-characters} in that buffer. In particular, when -you insert multibyte text into a unibyte buffer, Emacs converts the text -to unibyte, even though this conversion cannot in general preserve all -the characters that might be in the multibyte text. The other natural -alternative, to convert the buffer contents to multibyte, is not -acceptable because the buffer's representation is a choice made by the -user that cannot be overridden automatically. - - Converting unibyte text to multibyte text leaves @acronym{ASCII} -characters unchanged, and converts bytes with codes 128 through 255 to -the multibyte representation of raw eight-bit bytes. - - Converting multibyte text to unibyte converts all @acronym{ASCII} -and eight-bit characters to their single-byte form, but loses -information for non-@acronym{ASCII} characters by discarding all but -the low 8 bits of each character's codepoint. Converting unibyte text -to multibyte and back to unibyte reproduces the original unibyte text. - -The next two functions either return the argument @var{string}, or a -newly created string with no text properties. - -@defun string-to-multibyte string -This function returns a multibyte string containing the same sequence -of characters as @var{string}. If @var{string} is a multibyte string, -it is returned unchanged. The function assumes that @var{string} -includes only @acronym{ASCII} characters and raw 8-bit bytes; the -latter are converted to their multibyte representation corresponding -to the codepoints @code{#x3FFF80} through @code{#x3FFFFF}, inclusive -(@pxref{Text Representations, codepoints}). -@end defun - -@defun string-to-unibyte string -This function returns a unibyte string containing the same sequence of -characters as @var{string}. It signals an error if @var{string} -contains a non-@acronym{ASCII} character. If @var{string} is a -unibyte string, it is returned unchanged. Use this function for -@var{string} arguments that contain only @acronym{ASCII} and eight-bit -characters. -@end defun - -@c FIXME: Should `@var{character}' be `@var{byte}'? -@defun byte-to-string byte -@cindex byte to string -This function returns a unibyte string containing a single byte of -character data, @var{character}. It signals an error if -@var{character} is not an integer between 0 and 255. -@end defun - -@defun multibyte-char-to-unibyte char -This converts the multibyte character @var{char} to a unibyte -character, and returns that character. If @var{char} is neither -@acronym{ASCII} nor eight-bit, the function returns @minus{}1. -@end defun - -@defun unibyte-char-to-multibyte char -This convert the unibyte character @var{char} to a multibyte -character, assuming @var{char} is either @acronym{ASCII} or raw 8-bit -byte. -@end defun - -@node Selecting a Representation -@section Selecting a Representation - - Sometimes it is useful to examine an existing buffer or string as -multibyte when it was unibyte, or vice versa. - -@defun set-buffer-multibyte multibyte -Set the representation type of the current buffer. If @var{multibyte} -is non-@code{nil}, the buffer becomes multibyte. If @var{multibyte} -is @code{nil}, the buffer becomes unibyte. - -This function leaves the buffer contents unchanged when viewed as a -sequence of bytes. As a consequence, it can change the contents -viewed as characters; for instance, a sequence of three bytes which is -treated as one character in multibyte representation will count as -three characters in unibyte representation. Eight-bit characters -representing raw bytes are an exception. They are represented by one -byte in a unibyte buffer, but when the buffer is set to multibyte, -they are converted to two-byte sequences, and vice versa. - -This function sets @code{enable-multibyte-characters} to record which -representation is in use. It also adjusts various data in the buffer -(including overlays, text properties and markers) so that they cover the -same text as they did before. - -This function signals an error if the buffer is narrowed, since the -narrowing might have occurred in the middle of multibyte character -sequences. - -This function also signals an error if the buffer is an indirect -buffer. An indirect buffer always inherits the representation of its -base buffer. -@end defun - -@defun string-as-unibyte string -If @var{string} is already a unibyte string, this function returns -@var{string} itself. Otherwise, it returns a new string with the same -bytes as @var{string}, but treating each byte as a separate character -(so that the value may have more characters than @var{string}); as an -exception, each eight-bit character representing a raw byte is -converted into a single byte. The newly-created string contains no -text properties. -@end defun - -@defun string-as-multibyte string -If @var{string} is a multibyte string, this function returns -@var{string} itself. Otherwise, it returns a new string with the same -bytes as @var{string}, but treating each multibyte sequence as one -character. This means that the value may have fewer characters than -@var{string} has. If a byte sequence in @var{string} is invalid as a -multibyte representation of a single character, each byte in the -sequence is treated as a raw 8-bit byte. The newly-created string -contains no text properties. -@end defun - -@node Character Codes -@section Character Codes -@cindex character codes - - The unibyte and multibyte text representations use different -character codes. The valid character codes for unibyte representation -range from 0 to @code{#xFF} (255)---the values that can fit in one -byte. The valid character codes for multibyte representation range -from 0 to @code{#x3FFFFF}. In this code space, values 0 through -@code{#x7F} (127) are for @acronym{ASCII} characters, and values -@code{#x80} (128) through @code{#x3FFF7F} (4194175) are for -non-@acronym{ASCII} characters. - - Emacs character codes are a superset of the Unicode standard. -Values 0 through @code{#x10FFFF} (1114111) correspond to Unicode -characters of the same codepoint; values @code{#x110000} (1114112) -through @code{#x3FFF7F} (4194175) represent characters that are not -unified with Unicode; and values @code{#x3FFF80} (4194176) through -@code{#x3FFFFF} (4194303) represent eight-bit raw bytes. - -@defun characterp charcode -This returns @code{t} if @var{charcode} is a valid character, and -@code{nil} otherwise. - -@example -@group -(characterp 65) - @result{} t -@end group -@group -(characterp 4194303) - @result{} t -@end group -@group -(characterp 4194304) - @result{} nil -@end group -@end example -@end defun - -@cindex maximum value of character codepoint -@cindex codepoint, largest value -@defun max-char -This function returns the largest value that a valid character -codepoint can have. - -@example -@group -(characterp (max-char)) - @result{} t -@end group -@group -(characterp (1+ (max-char))) - @result{} nil -@end group -@end example -@end defun - -@defun get-byte &optional pos string -This function returns the byte at character position @var{pos} in the -current buffer. If the current buffer is unibyte, this is literally -the byte at that position. If the buffer is multibyte, byte values of -@acronym{ASCII} characters are the same as character codepoints, -whereas eight-bit raw bytes are converted to their 8-bit codes. The -function signals an error if the character at @var{pos} is -non-@acronym{ASCII}. - -The optional argument @var{string} means to get a byte value from that -string instead of the current buffer. -@end defun - -@node Character Properties -@section Character Properties -@cindex character properties -A @dfn{character property} is a named attribute of a character that -specifies how the character behaves and how it should be handled -during text processing and display. Thus, character properties are an -important part of specifying the character's semantics. - -@c FIXME: Use the latest URI of this chapter? -@c http://www.unicode.org/versions/latest/ch04.pdf - On the whole, Emacs follows the Unicode Standard in its implementation -of character properties. In particular, Emacs supports the -@uref{http://www.unicode.org/reports/tr23/, Unicode Character Property -Model}, and the Emacs character property database is derived from the -Unicode Character Database (@acronym{UCD}). See the -@uref{http://www.unicode.org/versions/Unicode6.2.0/ch04.pdf, Character -Properties chapter of the Unicode Standard}, for a detailed -description of Unicode character properties and their meaning. This -section assumes you are already familiar with that chapter of the -Unicode Standard, and want to apply that knowledge to Emacs Lisp -programs. - - In Emacs, each property has a name, which is a symbol, and a set of -possible values, whose types depend on the property; if a character -does not have a certain property, the value is @code{nil}. As a -general rule, the names of character properties in Emacs are produced -from the corresponding Unicode properties by downcasing them and -replacing each @samp{_} character with a dash @samp{-}. For example, -@code{Canonical_Combining_Class} becomes -@code{canonical-combining-class}. However, sometimes we shorten the -names to make their use easier. - -@cindex unassigned character codepoints - Some codepoints are left @dfn{unassigned} by the -@acronym{UCD}---they don't correspond to any character. The Unicode -Standard defines default values of properties for such codepoints; -they are mentioned below for each property. - - Here is the full list of value types for all the character -properties that Emacs knows about: - -@table @code -@item name -Corresponds to the @code{Name} Unicode property. The value is a -string consisting of upper-case Latin letters A to Z, digits, spaces, -and hyphen @samp{-} characters. For unassigned codepoints, the value -is @code{nil}. - -@cindex unicode general category -@item general-category -Corresponds to the @code{General_Category} Unicode property. The -value is a symbol whose name is a 2-letter abbreviation of the -character's classification. For unassigned codepoints, the value -is @code{Cn}. - -@item canonical-combining-class -Corresponds to the @code{Canonical_Combining_Class} Unicode property. -The value is an integer. For unassigned codepoints, the value -is zero. - -@cindex bidirectional class of characters -@item bidi-class -Corresponds to the Unicode @code{Bidi_Class} property. The value is a -symbol whose name is the Unicode @dfn{directional type} of the -character. Emacs uses this property when it reorders bidirectional -text for display (@pxref{Bidirectional Display}). For unassigned -codepoints, the value depends on the code blocks to which the -codepoint belongs: most unassigned codepoints get the value of -@code{L} (strong L), but some get values of @code{AL} (Arabic letter) -or @code{R} (strong R). - -@item decomposition -Corresponds to the Unicode properties @code{Decomposition_Type} and -@code{Decomposition_Value}. The value is a list, whose first element -may be a symbol representing a compatibility formatting tag, such as -@code{small}@footnote{The Unicode specification writes these tag names -inside @samp{<..>} brackets, but the tag names in Emacs do not include -the brackets; e.g., Unicode specifies @samp{} where Emacs uses -@samp{small}. }; the other elements are characters that give the -compatibility decomposition sequence of this character. For -unassigned codepoints, the value is the character itself. - -@item decimal-digit-value -Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Decimal}. The value is -an integer. For unassigned codepoints, the value is -@code{nil}, which means @acronym{NaN}, or ``not-a-number''. - -@item digit-value -Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Digit}. The value is an -integer. Examples of such characters include compatibility -subscript and superscript digits, for which the value is the -corresponding number. For unassigned codepoints, the value is -@code{nil}, which means @acronym{NaN}. - -@item numeric-value -Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Numeric}. The value of -this property is a number. Examples of -characters that have this property include fractions, subscripts, -superscripts, Roman numerals, currency numerators, and encircled -numbers. For example, the value of this property for the character -@code{U+2155} (@sc{vulgar fraction one fifth}) is @code{0.2}. For -unassigned codepoints, the value is @code{nil}, which means -@acronym{NaN}. - -@cindex mirroring of characters -@item mirrored -Corresponds to the Unicode @code{Bidi_Mirrored} property. The value -of this property is a symbol, either @code{Y} or @code{N}. For -unassigned codepoints, the value is @code{N}. - -@item mirroring -Corresponds to the Unicode @code{Bidi_Mirroring_Glyph} property. The -value of this property is a character whose glyph represents the -mirror image of the character's glyph, or @code{nil} if there's no -defined mirroring glyph. All the characters whose @code{mirrored} -property is @code{N} have @code{nil} as their @code{mirroring} -property; however, some characters whose @code{mirrored} property is -@code{Y} also have @code{nil} for @code{mirroring}, because no -appropriate characters exist with mirrored glyphs. Emacs uses this -property to display mirror images of characters when appropriate -(@pxref{Bidirectional Display}). For unassigned codepoints, the value -is @code{nil}. - -@item old-name -Corresponds to the Unicode @code{Unicode_1_Name} property. The value -is a string. Unassigned codepoints, and characters that have no value -for this property, the value is @code{nil}. - -@item iso-10646-comment -Corresponds to the Unicode @code{ISO_Comment} property. The value is -a string. For unassigned codepoints, the value is an empty string. - -@item uppercase -Corresponds to the Unicode @code{Simple_Uppercase_Mapping} property. -The value of this property is a single character. For unassigned -codepoints, the value is @code{nil}, which means the character itself. - -@item lowercase -Corresponds to the Unicode @code{Simple_Lowercase_Mapping} property. -The value of this property is a single character. For unassigned -codepoints, the value is @code{nil}, which means the character itself. - -@item titlecase -Corresponds to the Unicode @code{Simple_Titlecase_Mapping} property. -@dfn{Title case} is a special form of a character used when the first -character of a word needs to be capitalized. The value of this -property is a single character. For unassigned codepoints, the value -is @code{nil}, which means the character itself. -@end table - -@defun get-char-code-property char propname -This function returns the value of @var{char}'s @var{propname} property. - -@example -@group -(get-char-code-property ?\s 'general-category) - @result{} Zs -@end group -@group -(get-char-code-property ?1 'general-category) - @result{} Nd -@end group -@group -;; subscript 4 -(get-char-code-property ?\u2084 'digit-value) - @result{} 4 -@end group -@group -;; one fifth -(get-char-code-property ?\u2155 'numeric-value) - @result{} 0.2 -@end group -@group -;; Roman IV -(get-char-code-property ?\u2163 'numeric-value) - @result{} 4 -@end group -@end example -@end defun - -@defun char-code-property-description prop value -This function returns the description string of property @var{prop}'s -@var{value}, or @code{nil} if @var{value} has no description. - -@example -@group -(char-code-property-description 'general-category 'Zs) - @result{} "Separator, Space" -@end group -@group -(char-code-property-description 'general-category 'Nd) - @result{} "Number, Decimal Digit" -@end group -@group -(char-code-property-description 'numeric-value '1/5) - @result{} nil -@end group -@end example -@end defun - -@defun put-char-code-property char propname value -This function stores @var{value} as the value of the property -@var{propname} for the character @var{char}. -@end defun - -@defvar unicode-category-table -The value of this variable is a char-table (@pxref{Char-Tables}) that -specifies, for each character, its Unicode @code{General_Category} -property as a symbol. -@end defvar - -@defvar char-script-table -@cindex script symbols -The value of this variable is a char-table that specifies, for each -character, a symbol whose name is the script to which the character -belongs, according to the Unicode Standard classification of the -Unicode code space into script-specific blocks. This char-table has a -single extra slot whose value is the list of all script symbols. -@end defvar - -@defvar char-width-table -The value of this variable is a char-table that specifies the width of -each character in columns that it will occupy on the screen. -@end defvar - -@defvar printable-chars -The value of this variable is a char-table that specifies, for each -character, whether it is printable or not. That is, if evaluating -@code{(aref printable-chars char)} results in @code{t}, the character -is printable, and if it results in @code{nil}, it is not. -@end defvar - -@node Character Sets -@section Character Sets -@cindex character sets - -@cindex charset -@cindex coded character set -An Emacs @dfn{character set}, or @dfn{charset}, is a set of characters -in which each character is assigned a numeric code point. (The -Unicode Standard calls this a @dfn{coded character set}.) Each Emacs -charset has a name which is a symbol. A single character can belong -to any number of different character sets, but it will generally have -a different code point in each charset. Examples of character sets -include @code{ascii}, @code{iso-8859-1}, @code{greek-iso8859-7}, and -@code{windows-1255}. The code point assigned to a character in a -charset is usually different from its code point used in Emacs buffers -and strings. - -@cindex @code{emacs}, a charset -@cindex @code{unicode}, a charset -@cindex @code{eight-bit}, a charset - Emacs defines several special character sets. The character set -@code{unicode} includes all the characters whose Emacs code points are -in the range @code{0..#x10FFFF}. The character set @code{emacs} -includes all @acronym{ASCII} and non-@acronym{ASCII} characters. -Finally, the @code{eight-bit} charset includes the 8-bit raw bytes; -Emacs uses it to represent raw bytes encountered in text. - -@defun charsetp object -Returns @code{t} if @var{object} is a symbol that names a character set, -@code{nil} otherwise. -@end defun - -@defvar charset-list -The value is a list of all defined character set names. -@end defvar - -@defun charset-priority-list &optional highestp -This function returns a list of all defined character sets ordered by -their priority. If @var{highestp} is non-@code{nil}, the function -returns a single character set of the highest priority. -@end defun - -@defun set-charset-priority &rest charsets -This function makes @var{charsets} the highest priority character sets. -@end defun - -@defun char-charset character &optional restriction -This function returns the name of the character set of highest -priority that @var{character} belongs to. @acronym{ASCII} characters -are an exception: for them, this function always returns @code{ascii}. - -If @var{restriction} is non-@code{nil}, it should be a list of -charsets to search. Alternatively, it can be a coding system, in -which case the returned charset must be supported by that coding -system (@pxref{Coding Systems}). -@end defun - -@c TODO: Explain the properties here and add indexes such as 'charset property'. -@defun charset-plist charset -This function returns the property list of the character set -@var{charset}. Although @var{charset} is a symbol, this is not the -same as the property list of that symbol. Charset properties include -important information about the charset, such as its documentation -string, short name, etc. -@end defun - -@defun put-charset-property charset propname value -This function sets the @var{propname} property of @var{charset} to the -given @var{value}. -@end defun - -@defun get-charset-property charset propname -This function returns the value of @var{charset}s property -@var{propname}. -@end defun - -@deffn Command list-charset-chars charset -This command displays a list of characters in the character set -@var{charset}. -@end deffn - - Emacs can convert between its internal representation of a character -and the character's codepoint in a specific charset. The following -two functions support these conversions. - -@c FIXME: decode-char and encode-char accept and ignore an additional -@c argument @var{restriction}. When that argument actually makes a -@c difference, it should be documented here. -@defun decode-char charset code-point -This function decodes a character that is assigned a @var{code-point} -in @var{charset}, to the corresponding Emacs character, and returns -it. If @var{charset} doesn't contain a character of that code point, -the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp -integer (@pxref{Integer Basics, most-positive-fixnum}), it can be -specified as a cons cell @code{(@var{high} . @var{low})}, where -@var{low} are the lower 16 bits of the value and @var{high} are the -high 16 bits. -@end defun - -@defun encode-char char charset -This function returns the code point assigned to the character -@var{char} in @var{charset}. If the result does not fit in a Lisp -integer, it is returned as a cons cell @code{(@var{high} . @var{low})} -that fits the second argument of @code{decode-char} above. If -@var{charset} doesn't have a codepoint for @var{char}, the value is -@code{nil}. -@end defun - - The following function comes in handy for applying a certain -function to all or part of the characters in a charset: - -@defun map-charset-chars function charset &optional arg from-code to-code -Call @var{function} for characters in @var{charset}. @var{function} -is called with two arguments. The first one is a cons cell -@code{(@var{from} . @var{to})}, where @var{from} and @var{to} -indicate a range of characters contained in charset. The second -argument passed to @var{function} is @var{arg}. - -By default, the range of codepoints passed to @var{function} includes -all the characters in @var{charset}, but optional arguments -@var{from-code} and @var{to-code} limit that to the range of -characters between these two codepoints of @var{charset}. If either -of them is @code{nil}, it defaults to the first or last codepoint of -@var{charset}, respectively. -@end defun - -@node Scanning Charsets -@section Scanning for Character Sets - - Sometimes it is useful to find out which character set a particular -character belongs to. One use for this is in determining which coding -systems (@pxref{Coding Systems}) are capable of representing all of -the text in question; another is to determine the font(s) for -displaying that text. - -@defun charset-after &optional pos -This function returns the charset of highest priority containing the -character at position @var{pos} in the current buffer. If @var{pos} -is omitted or @code{nil}, it defaults to the current value of point. -If @var{pos} is out of range, the value is @code{nil}. -@end defun - -@defun find-charset-region beg end &optional translation -This function returns a list of the character sets of highest priority -that contain characters in the current buffer between positions -@var{beg} and @var{end}. - -The optional argument @var{translation} specifies a translation table -to use for scanning the text (@pxref{Translation of Characters}). If -it is non-@code{nil}, then each character in the region is translated -through this table, and the value returned describes the translated -characters instead of the characters actually in the buffer. -@end defun - -@defun find-charset-string string &optional translation -This function returns a list of character sets of highest priority -that contain characters in @var{string}. It is just like -@code{find-charset-region}, except that it applies to the contents of -@var{string} instead of part of the current buffer. -@end defun - -@node Translation of Characters -@section Translation of Characters -@cindex character translation tables -@cindex translation tables - - A @dfn{translation table} is a char-table (@pxref{Char-Tables}) that -specifies a mapping of characters into characters. These tables are -used in encoding and decoding, and for other purposes. Some coding -systems specify their own particular translation tables; there are -also default translation tables which apply to all other coding -systems. - - A translation table has two extra slots. The first is either -@code{nil} or a translation table that performs the reverse -translation; the second is the maximum number of characters to look up -for translating sequences of characters (see the description of -@code{make-translation-table-from-alist} below). - -@defun make-translation-table &rest translations -This function returns a translation table based on the argument -@var{translations}. Each element of @var{translations} should be a -list of elements of the form @code{(@var{from} . @var{to})}; this says -to translate the character @var{from} into @var{to}. - -The arguments and the forms in each argument are processed in order, -and if a previous form already translates @var{to} to some other -character, say @var{to-alt}, @var{from} is also translated to -@var{to-alt}. -@end defun - - During decoding, the translation table's translations are applied to -the characters that result from ordinary decoding. If a coding system -has the property @code{:decode-translation-table}, that specifies the -translation table to use, or a list of translation tables to apply in -sequence. (This is a property of the coding system, as returned by -@code{coding-system-get}, not a property of the symbol that is the -coding system's name. @xref{Coding System Basics,, Basic Concepts of -Coding Systems}.) Finally, if -@code{standard-translation-table-for-decode} is non-@code{nil}, the -resulting characters are translated by that table. - - During encoding, the translation table's translations are applied to -the characters in the buffer, and the result of translation is -actually encoded. If a coding system has property -@code{:encode-translation-table}, that specifies the translation table -to use, or a list of translation tables to apply in sequence. In -addition, if the variable @code{standard-translation-table-for-encode} -is non-@code{nil}, it specifies the translation table to use for -translating the result. - -@defvar standard-translation-table-for-decode -This is the default translation table for decoding. If a coding -systems specifies its own translation tables, the table that is the -value of this variable, if non-@code{nil}, is applied after them. -@end defvar - -@defvar standard-translation-table-for-encode -This is the default translation table for encoding. If a coding -systems specifies its own translation tables, the table that is the -value of this variable, if non-@code{nil}, is applied after them. -@end defvar - -@c FIXME: This variable is obsolete since 23.1. We should mention -@c that here or simply remove this defvar. --xfq -@defvar translation-table-for-input -Self-inserting characters are translated through this translation -table before they are inserted. Search commands also translate their -input through this table, so they can compare more reliably with -what's in the buffer. - -This variable automatically becomes buffer-local when set. -@end defvar - -@defun make-translation-table-from-vector vec -This function returns a translation table made from @var{vec} that is -an array of 256 elements to map bytes (values 0 through #xFF) to -characters. Elements may be @code{nil} for untranslated bytes. The -returned table has a translation table for reverse mapping in the -first extra slot, and the value @code{1} in the second extra slot. - -This function provides an easy way to make a private coding system -that maps each byte to a specific character. You can specify the -returned table and the reverse translation table using the properties -@code{:decode-translation-table} and @code{:encode-translation-table} -respectively in the @var{props} argument to -@code{define-coding-system}. -@end defun - -@defun make-translation-table-from-alist alist -This function is similar to @code{make-translation-table} but returns -a complex translation table rather than a simple one-to-one mapping. -Each element of @var{alist} is of the form @code{(@var{from} -. @var{to})}, where @var{from} and @var{to} are either characters or -vectors specifying a sequence of characters. If @var{from} is a -character, that character is translated to @var{to} (i.e., to a -character or a character sequence). If @var{from} is a vector of -characters, that sequence is translated to @var{to}. The returned -table has a translation table for reverse mapping in the first extra -slot, and the maximum length of all the @var{from} character sequences -in the second extra slot. -@end defun - -@node Coding Systems -@section Coding Systems - -@cindex coding system - When Emacs reads or writes a file, and when Emacs sends text to a -subprocess or receives text from a subprocess, it normally performs -character code conversion and end-of-line conversion as specified -by a particular @dfn{coding system}. - - How to define a coding system is an arcane matter, and is not -documented here. - -@menu -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -@end menu - -@node Coding System Basics -@subsection Basic Concepts of Coding Systems - -@cindex character code conversion - @dfn{Character code conversion} involves conversion between the -internal representation of characters used inside Emacs and some other -encoding. Emacs supports many different encodings, in that it can -convert to and from them. For example, it can convert text to or from -encodings such as Latin 1, Latin 2, Latin 3, Latin 4, Latin 5, and -several variants of ISO 2022. In some cases, Emacs supports several -alternative encodings for the same characters; for example, there are -three coding systems for the Cyrillic (Russian) alphabet: ISO, -Alternativnyj, and KOI8. - - Every coding system specifies a particular set of character code -conversions, but the coding system @code{undecided} is special: it -leaves the choice unspecified, to be chosen heuristically for each -file, based on the file's data. - - In general, a coding system doesn't guarantee roundtrip identity: -decoding a byte sequence using coding system, then encoding the -resulting text in the same coding system, can produce a different byte -sequence. But some coding systems do guarantee that the byte sequence -will be the same as what you originally decoded. Here are a few -examples: - -@quotation -iso-8859-1, utf-8, big5, shift_jis, euc-jp -@end quotation - - Encoding buffer text and then decoding the result can also fail to -reproduce the original text. For instance, if you encode a character -with a coding system which does not support that character, the result -is unpredictable, and thus decoding it using the same coding system -may produce a different text. Currently, Emacs can't report errors -that result from encoding unsupported characters. - -@cindex EOL conversion -@cindex end-of-line conversion -@cindex line end conversion - @dfn{End of line conversion} handles three different conventions -used on various systems for representing end of line in files. The -Unix convention, used on GNU and Unix systems, is to use the linefeed -character (also called newline). The DOS convention, used on -MS-Windows and MS-DOS systems, is to use a carriage-return and a -linefeed at the end of a line. The Mac convention is to use just -carriage-return. (This was the convention used on the Macintosh -system prior to OS X.) - -@cindex base coding system -@cindex variant coding system - @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line -conversion unspecified, to be chosen based on the data. @dfn{Variant -coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and -@code{latin-1-mac} specify the end-of-line conversion explicitly as -well. Most base coding systems have three corresponding variants whose -names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}. - -@vindex raw-text@r{ coding system} - The coding system @code{raw-text} is special in that it prevents -character code conversion, and causes the buffer visited with this -coding system to be a unibyte buffer. For historical reasons, you can -save both unibyte and multibyte text with this coding system. When -you use @code{raw-text} to encode multibyte text, it does perform one -character code conversion: it converts eight-bit characters to their -single-byte external representation. @code{raw-text} does not specify -the end-of-line conversion, allowing that to be determined as usual by -the data, and has the usual three variants which specify the -end-of-line conversion. - -@vindex no-conversion@r{ coding system} -@vindex binary@r{ coding system} - @code{no-conversion} (and its alias @code{binary}) is equivalent to -@code{raw-text-unix}: it specifies no conversion of either character -codes or end-of-line. - -@vindex emacs-internal@r{ coding system} -@vindex utf-8-emacs@r{ coding system} - The coding system @code{utf-8-emacs} specifies that the data is -represented in the internal Emacs encoding (@pxref{Text -Representations}). This is like @code{raw-text} in that no code -conversion happens, but different in that the result is multibyte -data. The name @code{emacs-internal} is an alias for -@code{utf-8-emacs}. - -@defun coding-system-get coding-system property -This function returns the specified property of the coding system -@var{coding-system}. Most coding system properties exist for internal -purposes, but one that you might find useful is @code{:mime-charset}. -That property's value is the name used in MIME for the character coding -which this coding system can read and write. Examples: - -@example -(coding-system-get 'iso-latin-1 :mime-charset) - @result{} iso-8859-1 -(coding-system-get 'iso-2022-cn :mime-charset) - @result{} iso-2022-cn -(coding-system-get 'cyrillic-koi8 :mime-charset) - @result{} koi8-r -@end example - -The value of the @code{:mime-charset} property is also defined -as an alias for the coding system. -@end defun - -@cindex alias, for coding systems -@defun coding-system-aliases coding-system -This function returns the list of aliases of @var{coding-system}. -@end defun - -@node Encoding and I/O -@subsection Encoding and I/O - - The principal purpose of coding systems is for use in reading and -writing files. The function @code{insert-file-contents} uses a coding -system to decode the file data, and @code{write-region} uses one to -encode the buffer contents. - - You can specify the coding system to use either explicitly -(@pxref{Specifying Coding Systems}), or implicitly using a default -mechanism (@pxref{Default Coding Systems}). But these methods may not -completely specify what to do. For example, they may choose a coding -system such as @code{undefined} which leaves the character code -conversion to be determined from the data. In these cases, the I/O -operation finishes the job of choosing a coding system. Very often -you will want to find out afterwards which coding system was chosen. - -@defvar buffer-file-coding-system -This buffer-local variable records the coding system used for saving the -buffer and for writing part of the buffer with @code{write-region}. If -the text to be written cannot be safely encoded using the coding system -specified by this variable, these operations select an alternative -encoding by calling the function @code{select-safe-coding-system} -(@pxref{User-Chosen Coding Systems}). If selecting a different encoding -requires to ask the user to specify a coding system, -@code{buffer-file-coding-system} is updated to the newly selected coding -system. - -@code{buffer-file-coding-system} does @emph{not} affect sending text -to a subprocess. -@end defvar - -@defvar save-buffer-coding-system -This variable specifies the coding system for saving the buffer (by -overriding @code{buffer-file-coding-system}). Note that it is not used -for @code{write-region}. - -When a command to save the buffer starts out to use -@code{buffer-file-coding-system} (or @code{save-buffer-coding-system}), -and that coding system cannot handle -the actual text in the buffer, the command asks the user to choose -another coding system (by calling @code{select-safe-coding-system}). -After that happens, the command also updates -@code{buffer-file-coding-system} to represent the coding system that -the user specified. -@end defvar - -@defvar last-coding-system-used -I/O operations for files and subprocesses set this variable to the -coding system name that was used. The explicit encoding and decoding -functions (@pxref{Explicit Encoding}) set it too. - -@strong{Warning:} Since receiving subprocess output sets this variable, -it can change whenever Emacs waits; therefore, you should copy the -value shortly after the function call that stores the value you are -interested in. -@end defvar - - The variable @code{selection-coding-system} specifies how to encode -selections for the window system. @xref{Window System Selections}. - -@defvar file-name-coding-system -The variable @code{file-name-coding-system} specifies the coding -system to use for encoding file names. Emacs encodes file names using -that coding system for all file operations. If -@code{file-name-coding-system} is @code{nil}, Emacs uses a default -coding system determined by the selected language environment. In the -default language environment, any non-@acronym{ASCII} characters in -file names are not encoded specially; they appear in the file system -using the internal Emacs representation. -@end defvar - - @strong{Warning:} if you change @code{file-name-coding-system} (or -the language environment) in the middle of an Emacs session, problems -can result if you have already visited files whose names were encoded -using the earlier coding system and are handled differently under the -new coding system. If you try to save one of these buffers under the -visited file name, saving may use the wrong file name, or it may get -an error. If such a problem happens, use @kbd{C-x C-w} to specify a -new file name for that buffer. - -@cindex file-name encoding, MS-Windows - On Windows 2000 and later, Emacs by default uses Unicode APIs to -pass file names to the OS, so the value of -@code{file-name-coding-system} is largely ignored. Lisp applications -that need to encode or decode file names on the Lisp level should use -@code{utf-8} coding-system when @code{system-type} is -@code{windows-nt}; the conversion of UTF-8 encoded file names to the -encoding appropriate for communicating with the OS is performed -internally by Emacs. - -@node Lisp and Coding Systems -@subsection Coding Systems in Lisp - - Here are the Lisp facilities for working with coding systems: - -@cindex list all coding systems -@defun coding-system-list &optional base-only -This function returns a list of all coding system names (symbols). If -@var{base-only} is non-@code{nil}, the value includes only the -base coding systems. Otherwise, it includes alias and variant coding -systems as well. -@end defun - -@defun coding-system-p object -This function returns @code{t} if @var{object} is a coding system -name or @code{nil}. -@end defun - -@cindex validity of coding system -@cindex coding system, validity check -@defun check-coding-system coding-system -This function checks the validity of @var{coding-system}. If that is -valid, it returns @var{coding-system}. If @var{coding-system} is -@code{nil}, the function return @code{nil}. For any other values, it -signals an error whose @code{error-symbol} is @code{coding-system-error} -(@pxref{Signaling Errors, signal}). -@end defun - -@cindex eol type of coding system -@defun coding-system-eol-type coding-system -This function returns the type of end-of-line (a.k.a.@: @dfn{eol}) -conversion used by @var{coding-system}. If @var{coding-system} -specifies a certain eol conversion, the return value is an integer 0, -1, or 2, standing for @code{unix}, @code{dos}, and @code{mac}, -respectively. If @var{coding-system} doesn't specify eol conversion -explicitly, the return value is a vector of coding systems, each one -with one of the possible eol conversion types, like this: - -@lisp -(coding-system-eol-type 'latin-1) - @result{} [latin-1-unix latin-1-dos latin-1-mac] -@end lisp - -@noindent -If this function returns a vector, Emacs will decide, as part of the -text encoding or decoding process, what eol conversion to use. For -decoding, the end-of-line format of the text is auto-detected, and the -eol conversion is set to match it (e.g., DOS-style CRLF format will -imply @code{dos} eol conversion). For encoding, the eol conversion is -taken from the appropriate default coding system (e.g., -default value of @code{buffer-file-coding-system} for -@code{buffer-file-coding-system}), or from the default eol conversion -appropriate for the underlying platform. -@end defun - -@cindex eol conversion of coding system -@defun coding-system-change-eol-conversion coding-system eol-type -This function returns a coding system which is like @var{coding-system} -except for its eol conversion, which is specified by @code{eol-type}. -@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or -@code{nil}. If it is @code{nil}, the returned coding system determines -the end-of-line conversion from the data. - -@var{eol-type} may also be 0, 1 or 2, standing for @code{unix}, -@code{dos} and @code{mac}, respectively. -@end defun - -@cindex text conversion of coding system -@defun coding-system-change-text-conversion eol-coding text-coding -This function returns a coding system which uses the end-of-line -conversion of @var{eol-coding}, and the text conversion of -@var{text-coding}. If @var{text-coding} is @code{nil}, it returns -@code{undecided}, or one of its variants according to @var{eol-coding}. -@end defun - -@cindex safely encode region -@cindex coding systems for encoding region -@defun find-coding-systems-region from to -This function returns a list of coding systems that could be used to -encode a text between @var{from} and @var{to}. All coding systems in -the list can safely encode any multibyte characters in that portion of -the text. - -If the text contains no multibyte characters, the function returns the -list @code{(undecided)}. -@end defun - -@cindex safely encode a string -@cindex coding systems for encoding a string -@defun find-coding-systems-string string -This function returns a list of coding systems that could be used to -encode the text of @var{string}. All coding systems in the list can -safely encode any multibyte characters in @var{string}. If the text -contains no multibyte characters, this returns the list -@code{(undecided)}. -@end defun - -@cindex charset, coding systems to encode -@cindex safely encode characters in a charset -@defun find-coding-systems-for-charsets charsets -This function returns a list of coding systems that could be used to -encode all the character sets in the list @var{charsets}. -@end defun - -@defun check-coding-systems-region start end coding-system-list -This function checks whether coding systems in the list -@code{coding-system-list} can encode all the characters in the region -between @var{start} and @var{end}. If all of the coding systems in -the list can encode the specified text, the function returns -@code{nil}. If some coding systems cannot encode some of the -characters, the value is an alist, each element of which has the form -@code{(@var{coding-system1} @var{pos1} @var{pos2} @dots{})}, meaning -that @var{coding-system1} cannot encode characters at buffer positions -@var{pos1}, @var{pos2}, @enddots{}. - -@var{start} may be a string, in which case @var{end} is ignored and -the returned value references string indices instead of buffer -positions. -@end defun - -@defun detect-coding-region start end &optional highest -This function chooses a plausible coding system for decoding the text -from @var{start} to @var{end}. This text should be a byte sequence, -i.e., unibyte text or multibyte text with only @acronym{ASCII} and -eight-bit characters (@pxref{Explicit Encoding}). - -Normally this function returns a list of coding systems that could -handle decoding the text that was scanned. They are listed in order of -decreasing priority. But if @var{highest} is non-@code{nil}, then the -return value is just one coding system, the one that is highest in -priority. - -If the region contains only @acronym{ASCII} characters except for such -ISO-2022 control characters ISO-2022 as @code{ESC}, the value is -@code{undecided} or @code{(undecided)}, or a variant specifying -end-of-line conversion, if that can be deduced from the text. - -If the region contains null bytes, the value is @code{no-conversion}, -even if the region contains text encoded in some coding system. -@end defun - -@defun detect-coding-string string &optional highest -This function is like @code{detect-coding-region} except that it -operates on the contents of @var{string} instead of bytes in the buffer. -@end defun - -@cindex null bytes, and decoding text -@defvar inhibit-null-byte-detection -If this variable has a non-@code{nil} value, null bytes are ignored -when detecting the encoding of a region or a string. This allows to -correctly detect the encoding of text that contains null bytes, such -as Info files with Index nodes. -@end defvar - -@defvar inhibit-iso-escape-detection -If this variable has a non-@code{nil} value, ISO-2022 escape sequences -are ignored when detecting the encoding of a region or a string. The -result is that no text is ever detected as encoded in some ISO-2022 -encoding, and all escape sequences become visible in a buffer. -@strong{Warning:} @emph{Use this variable with extreme caution, -because many files in the Emacs distribution use ISO-2022 encoding.} -@end defvar - -@cindex charsets supported by a coding system -@defun coding-system-charset-list coding-system -This function returns the list of character sets (@pxref{Character -Sets}) supported by @var{coding-system}. Some coding systems that -support too many character sets to list them all yield special values: -@itemize @bullet -@item -If @var{coding-system} supports all Emacs characters, the value is -@code{(emacs)}. -@item -If @var{coding-system} supports all Unicode characters, the value is -@code{(unicode)}. -@item -If @var{coding-system} supports all ISO-2022 charsets, the value is -@code{iso-2022}. -@item -If @var{coding-system} supports all the characters in the internal -coding system used by Emacs version 21 (prior to the implementation of -internal Unicode support), the value is @code{emacs-mule}. -@end itemize -@end defun - - @xref{Coding systems for a subprocess,, Process Information}, in -particular the description of the functions -@code{process-coding-system} and @code{set-process-coding-system}, for -how to examine or set the coding systems used for I/O to a subprocess. - -@node User-Chosen Coding Systems -@subsection User-Chosen Coding Systems - -@cindex select safe coding system -@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file -This function selects a coding system for encoding specified text, -asking the user to choose if necessary. Normally the specified text -is the text in the current buffer between @var{from} and @var{to}. If -@var{from} is a string, the string specifies the text to encode, and -@var{to} is ignored. - -If the specified text includes raw bytes (@pxref{Text -Representations}), @code{select-safe-coding-system} suggests -@code{raw-text} for its encoding. - -If @var{default-coding-system} is non-@code{nil}, that is the first -coding system to try; if that can handle the text, -@code{select-safe-coding-system} returns that coding system. It can -also be a list of coding systems; then the function tries each of them -one by one. After trying all of them, it next tries the current -buffer's value of @code{buffer-file-coding-system} (if it is not -@code{undecided}), then the default value of -@code{buffer-file-coding-system} and finally the user's most -preferred coding system, which the user can set using the command -@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing -Coding Systems, emacs, The GNU Emacs Manual}). - -If one of those coding systems can safely encode all the specified -text, @code{select-safe-coding-system} chooses it and returns it. -Otherwise, it asks the user to choose from a list of coding systems -which can encode all the text, and returns the user's choice. - -@var{default-coding-system} can also be a list whose first element is -t and whose other elements are coding systems. Then, if no coding -system in the list can handle the text, @code{select-safe-coding-system} -queries the user immediately, without trying any of the three -alternatives described above. - -The optional argument @var{accept-default-p}, if non-@code{nil}, -should be a function to determine whether a coding system selected -without user interaction is acceptable. @code{select-safe-coding-system} -calls this function with one argument, the base coding system of the -selected coding system. If @var{accept-default-p} returns @code{nil}, -@code{select-safe-coding-system} rejects the silently selected coding -system, and asks the user to select a coding system from a list of -possible candidates. - -@vindex select-safe-coding-system-accept-default-p -If the variable @code{select-safe-coding-system-accept-default-p} is -non-@code{nil}, it should be a function taking a single argument. -It is used in place of @var{accept-default-p}, overriding any -value supplied for this argument. - -As a final step, before returning the chosen coding system, -@code{select-safe-coding-system} checks whether that coding system is -consistent with what would be selected if the contents of the region -were read from a file. (If not, this could lead to data corruption in -a file subsequently re-visited and edited.) Normally, -@code{select-safe-coding-system} uses @code{buffer-file-name} as the -file for this purpose, but if @var{file} is non-@code{nil}, it uses -that file instead (this can be relevant for @code{write-region} and -similar functions). If it detects an apparent inconsistency, -@code{select-safe-coding-system} queries the user before selecting the -coding system. -@end defun - - Here are two functions you can use to let the user specify a coding -system, with completion. @xref{Completion}. - -@defun read-coding-system prompt &optional default -This function reads a coding system using the minibuffer, prompting with -string @var{prompt}, and returns the coding system name as a symbol. If -the user enters null input, @var{default} specifies which coding system -to return. It should be a symbol or a string. -@end defun - -@defun read-non-nil-coding-system prompt -This function reads a coding system using the minibuffer, prompting with -string @var{prompt}, and returns the coding system name as a symbol. If -the user tries to enter null input, it asks the user to try again. -@xref{Coding Systems}. -@end defun - -@node Default Coding Systems -@subsection Default Coding Systems -@cindex default coding system -@cindex coding system, automatically determined - - This section describes variables that specify the default coding -system for certain files or when running certain subprograms, and the -function that I/O operations use to access them. - - The idea of these variables is that you set them once and for all to the -defaults you want, and then do not change them again. To specify a -particular coding system for a particular operation in a Lisp program, -don't change these variables; instead, override them using -@code{coding-system-for-read} and @code{coding-system-for-write} -(@pxref{Specifying Coding Systems}). - -@cindex file contents, and default coding system -@defopt auto-coding-regexp-alist -This variable is an alist of text patterns and corresponding coding -systems. Each element has the form @code{(@var{regexp} -. @var{coding-system})}; a file whose first few kilobytes match -@var{regexp} is decoded with @var{coding-system} when its contents are -read into a buffer. The settings in this alist take priority over -@code{coding:} tags in the files and the contents of -@code{file-coding-system-alist} (see below). The default value is set -so that Emacs automatically recognizes mail files in Babyl format and -reads them with no code conversions. -@end defopt - -@cindex file name, and default coding system -@defopt file-coding-system-alist -This variable is an alist that specifies the coding systems to use for -reading and writing particular files. Each element has the form -@code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular -expression that matches certain file names. The element applies to file -names that match @var{pattern}. - -The @sc{cdr} of the element, @var{coding}, should be either a coding -system, a cons cell containing two coding systems, or a function name (a -symbol with a function definition). If @var{coding} is a coding system, -that coding system is used for both reading the file and writing it. If -@var{coding} is a cons cell containing two coding systems, its @sc{car} -specifies the coding system for decoding, and its @sc{cdr} specifies the -coding system for encoding. - -If @var{coding} is a function name, the function should take one -argument, a list of all arguments passed to -@code{find-operation-coding-system}. It must return a coding system -or a cons cell containing two coding systems. This value has the same -meaning as described above. - -If @var{coding} (or what returned by the above function) is -@code{undecided}, the normal code-detection is performed. -@end defopt - -@defopt auto-coding-alist -This variable is an alist that specifies the coding systems to use for -reading and writing particular files. Its form is like that of -@code{file-coding-system-alist}, but, unlike the latter, this variable -takes priority over any @code{coding:} tags in the file. -@end defopt - -@cindex program name, and default coding system -@defvar process-coding-system-alist -This variable is an alist specifying which coding systems to use for a -subprocess, depending on which program is running in the subprocess. It -works like @code{file-coding-system-alist}, except that @var{pattern} is -matched against the program name used to start the subprocess. The coding -system or systems specified in this alist are used to initialize the -coding systems used for I/O to the subprocess, but you can specify -other coding systems later using @code{set-process-coding-system}. -@end defvar - - @strong{Warning:} Coding systems such as @code{undecided}, which -determine the coding system from the data, do not work entirely reliably -with asynchronous subprocess output. This is because Emacs handles -asynchronous subprocess output in batches, as it arrives. If the coding -system leaves the character code conversion unspecified, or leaves the -end-of-line conversion unspecified, Emacs must try to detect the proper -conversion from one batch at a time, and this does not always work. - - Therefore, with an asynchronous subprocess, if at all possible, use a -coding system which determines both the character code conversion and -the end of line conversion---that is, one like @code{latin-1-unix}, -rather than @code{undecided} or @code{latin-1}. - -@cindex port number, and default coding system -@cindex network service name, and default coding system -@defvar network-coding-system-alist -This variable is an alist that specifies the coding system to use for -network streams. It works much like @code{file-coding-system-alist}, -with the difference that the @var{pattern} in an element may be either a -port number or a regular expression. If it is a regular expression, it -is matched against the network service name used to open the network -stream. -@end defvar - -@defvar default-process-coding-system -This variable specifies the coding systems to use for subprocess (and -network stream) input and output, when nothing else specifies what to -do. - -The value should be a cons cell of the form @code{(@var{input-coding} -. @var{output-coding})}. Here @var{input-coding} applies to input from -the subprocess, and @var{output-coding} applies to output to it. -@end defvar - -@cindex default coding system, functions to determine -@defopt auto-coding-functions -This variable holds a list of functions that try to determine a -coding system for a file based on its undecoded contents. - -Each function in this list should be written to look at text in the -current buffer, but should not modify it in any way. The buffer will -contain undecoded text of parts of the file. Each function should -take one argument, @var{size}, which tells it how many characters to -look at, starting from point. If the function succeeds in determining -a coding system for the file, it should return that coding system. -Otherwise, it should return @code{nil}. - -If a file has a @samp{coding:} tag, that takes precedence, so these -functions won't be called. -@end defopt - -@defun find-auto-coding filename size -This function tries to determine a suitable coding system for -@var{filename}. It examines the buffer visiting the named file, using -the variables documented above in sequence, until it finds a match for -one of the rules specified by these variables. It then returns a cons -cell of the form @code{(@var{coding} . @var{source})}, where -@var{coding} is the coding system to use and @var{source} is a symbol, -one of @code{auto-coding-alist}, @code{auto-coding-regexp-alist}, -@code{:coding}, or @code{auto-coding-functions}, indicating which one -supplied the matching rule. The value @code{:coding} means the coding -system was specified by the @code{coding:} tag in the file -(@pxref{Specify Coding,, coding tag, emacs, The GNU Emacs Manual}). -The order of looking for a matching rule is @code{auto-coding-alist} -first, then @code{auto-coding-regexp-alist}, then the @code{coding:} -tag, and lastly @code{auto-coding-functions}. If no matching rule was -found, the function returns @code{nil}. - -The second argument @var{size} is the size of text, in characters, -following point. The function examines text only within @var{size} -characters after point. Normally, the buffer should be positioned at -the beginning when this function is called, because one of the places -for the @code{coding:} tag is the first one or two lines of the file; -in that case, @var{size} should be the size of the buffer. -@end defun - -@defun set-auto-coding filename size -This function returns a suitable coding system for file -@var{filename}. It uses @code{find-auto-coding} to find the coding -system. If no coding system could be determined, the function returns -@code{nil}. The meaning of the argument @var{size} is like in -@code{find-auto-coding}. -@end defun - -@defun find-operation-coding-system operation &rest arguments -This function returns the coding system to use (by default) for -performing @var{operation} with @var{arguments}. The value has this -form: - -@example -(@var{decoding-system} . @var{encoding-system}) -@end example - -The first element, @var{decoding-system}, is the coding system to use -for decoding (in case @var{operation} does decoding), and -@var{encoding-system} is the coding system for encoding (in case -@var{operation} does encoding). - -The argument @var{operation} is a symbol; it should be one of -@code{write-region}, @code{start-process}, @code{call-process}, -@code{call-process-region}, @code{insert-file-contents}, or -@code{open-network-stream}. These are the names of the Emacs I/O -primitives that can do character code and eol conversion. - -The remaining arguments should be the same arguments that might be given -to the corresponding I/O primitive. Depending on the primitive, one -of those arguments is selected as the @dfn{target}. For example, if -@var{operation} does file I/O, whichever argument specifies the file -name is the target. For subprocess primitives, the process name is the -target. For @code{open-network-stream}, the target is the service name -or port number. - -Depending on @var{operation}, this function looks up the target in -@code{file-coding-system-alist}, @code{process-coding-system-alist}, -or @code{network-coding-system-alist}. If the target is found in the -alist, @code{find-operation-coding-system} returns its association in -the alist; otherwise it returns @code{nil}. - -If @var{operation} is @code{insert-file-contents}, the argument -corresponding to the target may be a cons cell of the form -@code{(@var{filename} . @var{buffer})}. In that case, @var{filename} -is a file name to look up in @code{file-coding-system-alist}, and -@var{buffer} is a buffer that contains the file's contents (not yet -decoded). If @code{file-coding-system-alist} specifies a function to -call for this file, and that function needs to examine the file's -contents (as it usually does), it should examine the contents of -@var{buffer} instead of reading the file. -@end defun - -@node Specifying Coding Systems -@subsection Specifying a Coding System for One Operation - - You can specify the coding system for a specific operation by binding -the variables @code{coding-system-for-read} and/or -@code{coding-system-for-write}. - -@defvar coding-system-for-read -If this variable is non-@code{nil}, it specifies the coding system to -use for reading a file, or for input from a synchronous subprocess. - -It also applies to any asynchronous subprocess or network stream, but in -a different way: the value of @code{coding-system-for-read} when you -start the subprocess or open the network stream specifies the input -decoding method for that subprocess or network stream. It remains in -use for that subprocess or network stream unless and until overridden. - -The right way to use this variable is to bind it with @code{let} for a -specific I/O operation. Its global value is normally @code{nil}, and -you should not globally set it to any other value. Here is an example -of the right way to use the variable: - -@example -;; @r{Read the file with no character code conversion.} -(let ((coding-system-for-read 'no-conversion)) - (insert-file-contents filename)) -@end example - -When its value is non-@code{nil}, this variable takes precedence over -all other methods of specifying a coding system to use for input, -including @code{file-coding-system-alist}, -@code{process-coding-system-alist} and -@code{network-coding-system-alist}. -@end defvar - -@defvar coding-system-for-write -This works much like @code{coding-system-for-read}, except that it -applies to output rather than input. It affects writing to files, -as well as sending output to subprocesses and net connections. - -When a single operation does both input and output, as do -@code{call-process-region} and @code{start-process}, both -@code{coding-system-for-read} and @code{coding-system-for-write} -affect it. -@end defvar - -@defopt inhibit-eol-conversion -When this variable is non-@code{nil}, no end-of-line conversion is done, -no matter which coding system is specified. This applies to all the -Emacs I/O and subprocess primitives, and to the explicit encoding and -decoding functions (@pxref{Explicit Encoding}). -@end defopt - -@cindex priority order of coding systems -@cindex coding systems, priority - Sometimes, you need to prefer several coding systems for some -operation, rather than fix a single one. Emacs lets you specify a -priority order for using coding systems. This ordering affects the -sorting of lists of coding systems returned by functions such as -@code{find-coding-systems-region} (@pxref{Lisp and Coding Systems}). - -@defun coding-system-priority-list &optional highestp -This function returns the list of coding systems in the order of their -current priorities. Optional argument @var{highestp}, if -non-@code{nil}, means return only the highest priority coding system. -@end defun - -@defun set-coding-system-priority &rest coding-systems -This function puts @var{coding-systems} at the beginning of the -priority list for coding systems, thus making their priority higher -than all the rest. -@end defun - -@defmac with-coding-priority coding-systems &rest body@dots{} -This macro execute @var{body}, like @code{progn} does -(@pxref{Sequencing, progn}), with @var{coding-systems} at the front of -the priority list for coding systems. @var{coding-systems} should be -a list of coding systems to prefer during execution of @var{body}. -@end defmac - -@node Explicit Encoding -@subsection Explicit Encoding and Decoding -@cindex encoding in coding systems -@cindex decoding in coding systems - - All the operations that transfer text in and out of Emacs have the -ability to use a coding system to encode or decode the text. -You can also explicitly encode and decode text using the functions -in this section. - - The result of encoding, and the input to decoding, are not ordinary -text. They logically consist of a series of byte values; that is, a -series of @acronym{ASCII} and eight-bit characters. In unibyte -buffers and strings, these characters have codes in the range 0 -through #xFF (255). In a multibyte buffer or string, eight-bit -characters have character codes higher than #xFF (@pxref{Text -Representations}), but Emacs transparently converts them to their -single-byte values when you encode or decode such text. - - The usual way to read a file into a buffer as a sequence of bytes, so -you can decode the contents explicitly, is with -@code{insert-file-contents-literally} (@pxref{Reading from Files}); -alternatively, specify a non-@code{nil} @var{rawfile} argument when -visiting a file with @code{find-file-noselect}. These methods result in -a unibyte buffer. - - The usual way to use the byte sequence that results from explicitly -encoding text is to copy it to a file or process---for example, to write -it with @code{write-region} (@pxref{Writing to Files}), and suppress -encoding by binding @code{coding-system-for-write} to -@code{no-conversion}. - - Here are the functions to perform explicit encoding or decoding. The -encoding functions produce sequences of bytes; the decoding functions -are meant to operate on sequences of bytes. All of these functions -discard text properties. They also set @code{last-coding-system-used} -to the precise coding system they used. - -@deffn Command encode-coding-region start end coding-system &optional destination -This command encodes the text from @var{start} to @var{end} according -to coding system @var{coding-system}. Normally, the encoded text -replaces the original text in the buffer, but the optional argument -@var{destination} can change that. If @var{destination} is a buffer, -the encoded text is inserted in that buffer after point (point does -not move); if it is @code{t}, the command returns the encoded text as -a unibyte string without inserting it. - -If encoded text is inserted in some buffer, this command returns the -length of the encoded text. - -The result of encoding is logically a sequence of bytes, but the -buffer remains multibyte if it was multibyte before, and any 8-bit -bytes are converted to their multibyte representation (@pxref{Text -Representations}). - -@cindex @code{undecided} coding-system, when encoding -Do @emph{not} use @code{undecided} for @var{coding-system} when -encoding text, since that may lead to unexpected results. Instead, -use @code{select-safe-coding-system} (@pxref{User-Chosen Coding -Systems, select-safe-coding-system}) to suggest a suitable encoding, -if there's no obvious pertinent value for @var{coding-system}. -@end deffn - -@defun encode-coding-string string coding-system &optional nocopy buffer -This function encodes the text in @var{string} according to coding -system @var{coding-system}. It returns a new string containing the -encoded text, except when @var{nocopy} is non-@code{nil}, in which -case the function may return @var{string} itself if the encoding -operation is trivial. The result of encoding is a unibyte string. -@end defun - -@deffn Command decode-coding-region start end coding-system &optional destination -This command decodes the text from @var{start} to @var{end} according -to coding system @var{coding-system}. To make explicit decoding -useful, the text before decoding ought to be a sequence of byte -values, but both multibyte and unibyte buffers are acceptable (in the -multibyte case, the raw byte values should be represented as eight-bit -characters). Normally, the decoded text replaces the original text in -the buffer, but the optional argument @var{destination} can change -that. If @var{destination} is a buffer, the decoded text is inserted -in that buffer after point (point does not move); if it is @code{t}, -the command returns the decoded text as a multibyte string without -inserting it. - -If decoded text is inserted in some buffer, this command returns the -length of the decoded text. - -This command puts a @code{charset} text property on the decoded text. -The value of the property states the character set used to decode the -original text. -@end deffn - -@defun decode-coding-string string coding-system &optional nocopy buffer -This function decodes the text in @var{string} according to -@var{coding-system}. It returns a new string containing the decoded -text, except when @var{nocopy} is non-@code{nil}, in which case the -function may return @var{string} itself if the decoding operation is -trivial. To make explicit decoding useful, the contents of -@var{string} ought to be a unibyte string with a sequence of byte -values, but a multibyte string is also acceptable (assuming it -contains 8-bit bytes in their multibyte form). - -If optional argument @var{buffer} specifies a buffer, the decoded text -is inserted in that buffer after point (point does not move). In this -case, the return value is the length of the decoded text. - -@cindex @code{charset}, text property -This function puts a @code{charset} text property on the decoded text. -The value of the property states the character set used to decode the -original text: - -@example -@group -(decode-coding-string "Gr\374ss Gott" 'latin-1) - @result{} #("Gr@"uss Gott" 0 9 (charset iso-8859-1)) -@end group -@end example -@end defun - -@defun decode-coding-inserted-region from to filename &optional visit beg end replace -This function decodes the text from @var{from} to @var{to} as if -it were being read from file @var{filename} using @code{insert-file-contents} -using the rest of the arguments provided. - -The normal way to use this function is after reading text from a file -without decoding, if you decide you would rather have decoded it. -Instead of deleting the text and reading it again, this time with -decoding, you can call this function. -@end defun - -@node Terminal I/O Encoding -@subsection Terminal I/O Encoding - - Emacs can use coding systems to decode keyboard input and encode -terminal output. This is useful for terminals that transmit or -display text using a particular encoding, such as Latin-1. Emacs does -not set @code{last-coding-system-used} when encoding or decoding -terminal I/O. - -@defun keyboard-coding-system &optional terminal -This function returns the coding system used for decoding keyboard -input from @var{terminal}. A value of @code{no-conversion} means no -decoding is done. If @var{terminal} is omitted or @code{nil}, it -means the selected frame's terminal. @xref{Multiple Terminals}. -@end defun - -@deffn Command set-keyboard-coding-system coding-system &optional terminal -This command specifies @var{coding-system} as the coding system to use -for decoding keyboard input from @var{terminal}. If -@var{coding-system} is @code{nil}, that means not to decode keyboard -input. If @var{terminal} is a frame, it means that frame's terminal; -if it is @code{nil}, that means the currently selected frame's -terminal. @xref{Multiple Terminals}. -@end deffn - -@defun terminal-coding-system &optional terminal -This function returns the coding system that is in use for encoding -terminal output from @var{terminal}. A value of @code{no-conversion} -means no encoding is done. If @var{terminal} is a frame, it means -that frame's terminal; if it is @code{nil}, that means the currently -selected frame's terminal. -@end defun - -@deffn Command set-terminal-coding-system coding-system &optional terminal -This command specifies @var{coding-system} as the coding system to use -for encoding terminal output from @var{terminal}. If -@var{coding-system} is @code{nil}, that means not to encode terminal -output. If @var{terminal} is a frame, it means that frame's terminal; -if it is @code{nil}, that means the currently selected frame's -terminal. -@end deffn - -@node Input Methods -@section Input Methods -@cindex input methods - - @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII} -characters from the keyboard. Unlike coding systems, which translate -non-@acronym{ASCII} characters to and from encodings meant to be read by -programs, input methods provide human-friendly commands. (@xref{Input -Methods,,, emacs, The GNU Emacs Manual}, for information on how users -use input methods to enter text.) How to define input methods is not -yet documented in this manual, but here we describe how to use them. - - Each input method has a name, which is currently a string; -in the future, symbols may also be usable as input method names. - -@defvar current-input-method -This variable holds the name of the input method now active in the -current buffer. (It automatically becomes local in each buffer when set -in any fashion.) It is @code{nil} if no input method is active in the -buffer now. -@end defvar - -@defopt default-input-method -This variable holds the default input method for commands that choose an -input method. Unlike @code{current-input-method}, this variable is -normally global. -@end defopt - -@deffn Command set-input-method input-method -This command activates input method @var{input-method} for the current -buffer. It also sets @code{default-input-method} to @var{input-method}. -If @var{input-method} is @code{nil}, this command deactivates any input -method for the current buffer. -@end deffn - -@defun read-input-method-name prompt &optional default inhibit-null -This function reads an input method name with the minibuffer, prompting -with @var{prompt}. If @var{default} is non-@code{nil}, that is returned -by default, if the user enters empty input. However, if -@var{inhibit-null} is non-@code{nil}, empty input signals an error. - -The returned value is a string. -@end defun - -@defvar input-method-alist -This variable defines all the supported input methods. -Each element defines one input method, and should have the form: - -@example -(@var{input-method} @var{language-env} @var{activate-func} - @var{title} @var{description} @var{args}...) -@end example - -Here @var{input-method} is the input method name, a string; -@var{language-env} is another string, the name of the language -environment this input method is recommended for. (That serves only for -documentation purposes.) - -@var{activate-func} is a function to call to activate this method. The -@var{args}, if any, are passed as arguments to @var{activate-func}. All -told, the arguments to @var{activate-func} are @var{input-method} and -the @var{args}. - -@var{title} is a string to display in the mode line while this method is -active. @var{description} is a string describing this method and what -it is good for. -@end defvar - - The fundamental interface to input methods is through the -variable @code{input-method-function}. @xref{Reading One Event}, -and @ref{Invoking the Input Method}. - -@node Locales -@section Locales -@cindex locale - - POSIX defines a concept of ``locales'' which control which language -to use in language-related features. These Emacs variables control -how Emacs interacts with these features. - -@defvar locale-coding-system -@cindex keyboard input decoding on X -This variable specifies the coding system to use for decoding system -error messages and---on X Window system only---keyboard input, for -encoding the format argument to @code{format-time-string}, and for -decoding the return value of @code{format-time-string}. -@end defvar - -@defvar system-messages-locale -This variable specifies the locale to use for generating system error -messages. Changing the locale can cause messages to come out in a -different language or in a different orthography. If the variable is -@code{nil}, the locale is specified by environment variables in the -usual POSIX fashion. -@end defvar - -@defvar system-time-locale -This variable specifies the locale to use for formatting time values. -Changing the locale can cause messages to appear according to the -conventions of a different language. If the variable is @code{nil}, the -locale is specified by environment variables in the usual POSIX fashion. -@end defvar - -@defun locale-info item -This function returns locale data @var{item} for the current POSIX -locale, if available. @var{item} should be one of these symbols: - -@table @code -@item codeset -Return the character set as a string (locale item @code{CODESET}). - -@item days -Return a 7-element vector of day names (locale items -@code{DAY_1} through @code{DAY_7}); - -@item months -Return a 12-element vector of month names (locale items @code{MON_1} -through @code{MON_12}). - -@item paper -Return a list @code{(@var{width} @var{height})} for the default paper -size measured in millimeters (locale items @code{PAPER_WIDTH} and -@code{PAPER_HEIGHT}). -@end table - -If the system can't provide the requested information, or if -@var{item} is not one of those symbols, the value is @code{nil}. All -strings in the return value are decoded using -@code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual}, -for more information about locales and locale items. -@end defun diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi deleted file mode 100644 index 8fcd77c009a..00000000000 --- a/doc/lispref/numbers.texi +++ /dev/null @@ -1,1245 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Numbers -@chapter Numbers -@cindex integers -@cindex numbers - - GNU Emacs supports two numeric data types: @dfn{integers} and -@dfn{floating-point numbers}. Integers are whole numbers such as -@minus{}3, 0, 7, 13, and 511. Floating-point numbers are numbers with -fractional parts, such as @minus{}4.5, 0.0, and 2.71828. They can -also be expressed in exponential notation: @samp{1.5e2} is the same as -@samp{150.0}; here, @samp{e2} stands for ten to the second power, and -that is multiplied by 1.5. Integer computations are exact, though -they may overflow. Floating-point computations often involve rounding -errors, as the numbers have a fixed amount of precision. - -@menu -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating-point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. -@end menu - -@node Integer Basics -@section Integer Basics - - The range of values for an integer depends on the machine. The -minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., -@ifnottex -@minus{}2**29 -@end ifnottex -@tex -@math{-2^{29}} -@end tex -to -@ifnottex -2**29 @minus{} 1), -@end ifnottex -@tex -@math{2^{29}-1}), -@end tex -but many machines provide a wider range. Many examples in this -chapter assume the minimum integer width of 30 bits. -@cindex overflow - - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. An integer that is out of the -Emacs range is treated as a floating-point number. - -@example - 1 ; @r{The integer 1.} - 1. ; @r{The integer 1.} -+1 ; @r{Also the integer 1.} --1 ; @r{The integer @minus{}1.} - 9000000000000000000 - ; @r{The floating-point number 9e18.} - 0 ; @r{The integer 0.} --0 ; @r{The integer 0.} -@end example - -@cindex integers in specific radix -@cindex radix for reading an integer -@cindex base for reading an integer -@cindex hex numbers -@cindex octal numbers -@cindex reading numbers in hex, octal, and binary - The syntax for integers in bases other than 10 uses @samp{#} -followed by a letter that specifies the radix: @samp{b} for binary, -@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to -specify radix @var{radix}. Case is not significant for the letter -that specifies the radix. Thus, @samp{#b@var{integer}} reads -@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads -@var{integer} in radix @var{radix}. Allowed values of @var{radix} run -from 2 to 36. For example: - -@example -#b101100 @result{} 44 -#o54 @result{} 44 -#x2c @result{} 44 -#24r1k @result{} 44 -@end example - - To understand how various functions work on integers, especially the -bitwise operators (@pxref{Bitwise Operations}), it is often helpful to -view the numbers in their binary form. - - In 30-bit binary, the decimal integer 5 looks like this: - -@example -0000...000101 (30 bits total) -@end example - -@noindent -(The @samp{...} stands for enough bits to fill out a 30-bit word; in -this case, @samp{...} stands for twenty 0 bits. Later examples also -use the @samp{...} notation to make binary integers easier to read.) - - The integer @minus{}1 looks like this: - -@example -1111...111111 (30 bits total) -@end example - -@noindent -@cindex two's complement -@minus{}1 is represented as 30 ones. (This is called @dfn{two's -complement} notation.) - - Subtracting 4 from @minus{}1 returns the negative integer @minus{}5. -In binary, the decimal integer 4 is 100. Consequently, -@minus{}5 looks like this: - -@example -1111...111011 (30 bits total) -@end example - - In this implementation, the largest 30-bit binary integer is -536,870,911 in decimal. In binary, it looks like this: - -@example -0111...111111 (30 bits total) -@end example - - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 536,870,911, the value is the -negative integer @minus{}536,870,912: - -@example -(+ 1 536870911) - @result{} -536870912 - @result{} 1000...000000 (30 bits total) -@end example - - Many of the functions described in this chapter accept markers for -arguments in place of numbers. (@xref{Markers}.) Since the actual -arguments to such functions may be either numbers or markers, we often -give these arguments the name @var{number-or-marker}. When the argument -value is a marker, its position value is used and its buffer is ignored. - -@cindex largest Lisp integer -@cindex maximum Lisp integer -@defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp can -handle. Typical values are -@ifnottex -2**29 @minus{} 1 -@end ifnottex -@tex -@math{2^{29}-1} -@end tex -on 32-bit and -@ifnottex -2**61 @minus{} 1 -@end ifnottex -@tex -@math{2^{61}-1} -@end tex -on 64-bit platforms. -@end defvar - -@cindex smallest Lisp integer -@cindex minimum Lisp integer -@defvar most-negative-fixnum -The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. Typical values are -@ifnottex -@minus{}2**29 -@end ifnottex -@tex -@math{-2^{29}} -@end tex -on 32-bit and -@ifnottex -@minus{}2**61 -@end ifnottex -@tex -@math{-2^{61}} -@end tex -on 64-bit platforms. -@end defvar - - In Emacs Lisp, text characters are represented by integers. Any -integer between zero and the value of @code{(max-char)}, inclusive, is -considered to be valid as a character. @xref{Character Codes}. - -@node Float Basics -@section Floating-Point Basics - -@cindex @acronym{IEEE} floating point - Floating-point numbers are useful for representing numbers that are -not integral. The range of floating-point numbers is -the same as the range of the C data type @code{double} on the machine -you are using. On all computers currently supported by Emacs, this is -double-precision @acronym{IEEE} floating point. - - The read syntax for floating-point numbers requires either a decimal -point, an exponent, or both. Optional signs (@samp{+} or @samp{-}) -precede the number and its exponent. For example, @samp{1500.0}, -@samp{+15e2}, @samp{15.0e+2}, @samp{+1500000e-3}, and @samp{.15e4} are -five ways of writing a floating-point number whose value is 1500. -They are all equivalent. Like Common Lisp, Emacs Lisp requires at -least one digit after any decimal point in a floating-point number; -@samp{1500.} is an integer, not a floating-point number. - - Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero -with respect to @code{equal} and @code{=}. This follows the -@acronym{IEEE} floating-point standard, which says @code{-0.0} and -@code{0.0} are numerically equal even though other operations can -distinguish them. - -@cindex positive infinity -@cindex negative infinity -@cindex infinity -@cindex NaN - The @acronym{IEEE} floating-point standard supports positive -infinity and negative infinity as floating-point values. It also -provides for a class of values called NaN or ``not-a-number''; -numerical functions return such values in cases where there is no -correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN@. -Although NaN values carry a sign, for practical purposes there is no other -significant difference between different NaN values in Emacs Lisp. - -Here are read syntaxes for these special floating-point values: - -@table @asis -@item infinity -@samp{1.0e+INF} and @samp{-1.0e+INF} -@item not-a-number -@samp{0.0e+NaN} and @samp{-0.0e+NaN} -@end table - - The following functions are specialized for handling floating-point -numbers: - -@defun isnan x -This predicate returns @code{t} if its floating-point argument is a NaN, -@code{nil} otherwise. -@end defun - -@defun frexp x -This function returns a cons cell @code{(@var{s} . @var{e})}, -where @var{s} and @var{e} are respectively the significand and -exponent of the floating-point number @var{x}. - -If @var{x} is finite, then @var{s} is a floating-point number between 0.5 -(inclusive) and 1.0 (exclusive), @var{e} is an integer, and -@ifnottex -@var{x} = @var{s} * 2**@var{e}. -@end ifnottex -@tex -@math{x = s 2^e}. -@end tex -If @var{x} is zero or infinity, then @var{s} is the same as @var{x}. -If @var{x} is a NaN, then @var{s} is also a NaN. -If @var{x} is zero, then @var{e} is 0. -@end defun - -@defun ldexp sig &optional exp -This function returns a floating-point number corresponding to the -significand @var{sig} and exponent @var{exp}. -@end defun - -@defun copysign x1 x2 -This function copies the sign of @var{x2} to the value of @var{x1}, -and returns the result. @var{x1} and @var{x2} must be floating point. -@end defun - -@defun logb x -This function returns the binary exponent of @var{x}. More -precisely, the value is the logarithm base 2 of @math{|x|}, rounded -down to an integer. - -@example -(logb 10) - @result{} 3 -(logb 10.0e20) - @result{} 69 -@end example -@end defun - -@node Predicates on Numbers -@section Type Predicates for Numbers -@cindex predicates for numbers - - The functions in this section test for numbers, or for a specific -type of number. The functions @code{integerp} and @code{floatp} can -take any type of Lisp object as argument (they would not be of much -use otherwise), but the @code{zerop} predicate requires a number as -its argument. See also @code{integer-or-marker-p} and -@code{number-or-marker-p}, in @ref{Predicates on Markers}. - -@defun floatp object -This predicate tests whether its argument is floating point -and returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun integerp object -This predicate tests whether its argument is an integer, and returns -@code{t} if so, @code{nil} otherwise. -@end defun - -@defun numberp object -This predicate tests whether its argument is a number (either integer or -floating point), and returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun natnump object -@cindex natural numbers -This predicate (whose name comes from the phrase ``natural number'') -tests to see whether its argument is a nonnegative integer, and -returns @code{t} if so, @code{nil} otherwise. 0 is considered -non-negative. - -@findex wholenump -@code{wholenump} is a synonym for @code{natnump}. -@end defun - -@defun zerop number -This predicate tests whether its argument is zero, and returns @code{t} -if so, @code{nil} otherwise. The argument must be a number. - -@code{(zerop x)} is equivalent to @code{(= x 0)}. -@end defun - -@node Comparison of Numbers -@section Comparison of Numbers -@cindex number comparison -@cindex comparing numbers - - To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating-point -objects with the same numeric value. If you use @code{eq} to -compare them, then you test whether two values are the same -@emph{object}. By contrast, @code{=} compares only the numeric values -of the objects. - - In Emacs Lisp, each integer is a unique Lisp object. -Therefore, @code{eq} is equivalent to @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing -an unknown value with an integer, because @code{eq} does not report an -error if the unknown value is not a number---it accepts arguments of -any type. By contrast, @code{=} signals an error if the arguments are -not numbers or markers. However, it is better programming practice to -use @code{=} if you can, even for comparing integers. - - Sometimes it is useful to compare numbers with @code{equal}, which -treats two numbers as equal if they have the same data type (both -integers, or both floating point) and the same value. By contrast, -@code{=} can treat an integer and a floating-point number as equal. -@xref{Equality Predicates}. - - There is another wrinkle: because floating-point arithmetic is not -exact, it is often a bad idea to check for equality of floating-point -values. Usually it is better to test for approximate equality. -Here's a function to do this: - -@example -(defvar fuzz-factor 1.0e-6) -(defun approx-equal (x y) - (or (= x y) - (< (/ (abs (- x y)) - (max (abs x) (abs y))) - fuzz-factor))) -@end example - -@cindex CL note---integers vrs @code{eq} -@quotation -@b{Common Lisp note:} Comparing numbers in Common Lisp always requires -@code{=} because Common Lisp implements multi-word integers, and two -distinct integer objects can have the same numeric value. Emacs Lisp -can have just one integer object for any given value because it has a -limited range of integers. -@end quotation - -@defun = number-or-marker &rest number-or-markers -This function tests whether all its arguments are numerically equal, -and returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun eql value1 value2 -This function acts like @code{eq} except when both arguments are -numbers. It compares numbers by type and numeric value, so that -@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and -@code{(eql 1 1)} both return @code{t}. -@end defun - -@defun /= number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if they are not, and @code{nil} if they are. -@end defun - -@defun < number-or-marker &rest number-or-markers -This function tests whether each argument is strictly less than the -following argument. It returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun <= number-or-marker &rest number-or-markers -This function tests whether each argument is less than or equal to -the following argument. It returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun > number-or-marker &rest number-or-markers -This function tests whether each argument is strictly greater than -the following argument. It returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun >= number-or-marker &rest number-or-markers -This function tests whether each argument is greater than or equal to -the following argument. It returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun max number-or-marker &rest numbers-or-markers -This function returns the largest of its arguments. -If any of the arguments is floating point, the value is returned -as floating point, even if it was given as an integer. - -@example -(max 20) - @result{} 20 -(max 1 2.5) - @result{} 2.5 -(max 1 3 2.5) - @result{} 3.0 -@end example -@end defun - -@defun min number-or-marker &rest numbers-or-markers -This function returns the smallest of its arguments. -If any of the arguments is floating point, the value is returned -as floating point, even if it was given as an integer. - -@example -(min -4 1) - @result{} -4 -@end example -@end defun - -@defun abs number -This function returns the absolute value of @var{number}. -@end defun - -@node Numeric Conversions -@section Numeric Conversions -@cindex rounding in conversions -@cindex number conversions -@cindex converting numbers - -To convert an integer to floating point, use the function @code{float}. - -@defun float number -This returns @var{number} converted to floating point. -If @var{number} is already floating point, @code{float} returns -it unchanged. -@end defun - - There are four functions to convert floating-point numbers to -integers; they differ in how they round. All accept an argument -@var{number} and an optional argument @var{divisor}. Both arguments -may be integers or floating-point numbers. @var{divisor} may also be -@code{nil}. If @var{divisor} is @code{nil} or omitted, these -functions convert @var{number} to an integer, or return it unchanged -if it already is an integer. If @var{divisor} is non-@code{nil}, they -divide @var{number} by @var{divisor} and convert the result to an -integer. If @var{divisor} is zero (whether integer or -floating point), Emacs signals an @code{arith-error} error. - -@defun truncate number &optional divisor -This returns @var{number}, converted to an integer by rounding towards -zero. - -@example -(truncate 1.2) - @result{} 1 -(truncate 1.7) - @result{} 1 -(truncate -1.2) - @result{} -1 -(truncate -1.7) - @result{} -1 -@end example -@end defun - -@defun floor number &optional divisor -This returns @var{number}, converted to an integer by rounding downward -(towards negative infinity). - -If @var{divisor} is specified, this uses the kind of division -operation that corresponds to @code{mod}, rounding downward. - -@example -(floor 1.2) - @result{} 1 -(floor 1.7) - @result{} 1 -(floor -1.2) - @result{} -2 -(floor -1.7) - @result{} -2 -(floor 5.99 3) - @result{} 1 -@end example -@end defun - -@defun ceiling number &optional divisor -This returns @var{number}, converted to an integer by rounding upward -(towards positive infinity). - -@example -(ceiling 1.2) - @result{} 2 -(ceiling 1.7) - @result{} 2 -(ceiling -1.2) - @result{} -1 -(ceiling -1.7) - @result{} -1 -@end example -@end defun - -@defun round number &optional divisor -This returns @var{number}, converted to an integer by rounding towards the -nearest integer. Rounding a value equidistant between two integers -returns the even integer. - -@example -(round 1.2) - @result{} 1 -(round 1.7) - @result{} 2 -(round -1.2) - @result{} -1 -(round -1.7) - @result{} -2 -@end example -@end defun - -@node Arithmetic Operations -@section Arithmetic Operations -@cindex arithmetic operations - - Emacs Lisp provides the traditional four arithmetic operations -(addition, subtraction, multiplication, and division), as well as -remainder and modulus functions, and functions to add or subtract 1. -Except for @code{%}, each of these functions accepts both integer and -floating-point arguments, and returns a floating-point number if any -argument is floating point. - - Emacs Lisp arithmetic functions do not check for integer overflow. -Thus @code{(1+ 536870911)} may evaluate to -@minus{}536870912, depending on your hardware. - -@defun 1+ number-or-marker -This function returns @var{number-or-marker} plus 1. -For example, - -@example -(setq foo 4) - @result{} 4 -(1+ foo) - @result{} 5 -@end example - -This function is not analogous to the C operator @code{++}---it does not -increment a variable. It just computes a sum. Thus, if we continue, - -@example -foo - @result{} 4 -@end example - -If you want to increment the variable, you must use @code{setq}, -like this: - -@example -(setq foo (1+ foo)) - @result{} 5 -@end example -@end defun - -@defun 1- number-or-marker -This function returns @var{number-or-marker} minus 1. -@end defun - -@defun + &rest numbers-or-markers -This function adds its arguments together. When given no arguments, -@code{+} returns 0. - -@example -(+) - @result{} 0 -(+ 1) - @result{} 1 -(+ 1 2 3 4) - @result{} 10 -@end example -@end defun - -@defun - &optional number-or-marker &rest more-numbers-or-markers -The @code{-} function serves two purposes: negation and subtraction. -When @code{-} has a single argument, the value is the negative of the -argument. When there are multiple arguments, @code{-} subtracts each of -the @var{more-numbers-or-markers} from @var{number-or-marker}, -cumulatively. If there are no arguments, the result is 0. - -@example -(- 10 1 2 3 4) - @result{} 0 -(- 10) - @result{} -10 -(-) - @result{} 0 -@end example -@end defun - -@defun * &rest numbers-or-markers -This function multiplies its arguments together, and returns the -product. When given no arguments, @code{*} returns 1. - -@example -(*) - @result{} 1 -(* 1) - @result{} 1 -(* 1 2 3 4) - @result{} 24 -@end example -@end defun - -@defun / dividend divisor &rest divisors -This function divides @var{dividend} by @var{divisor} and returns the -quotient. If there are additional arguments @var{divisors}, then it -divides @var{dividend} by each divisor in turn. Each argument may be a -number or a marker. - -If all the arguments are integers, the result is an integer, obtained -by rounding the quotient towards zero after each division. - -@example -@group -(/ 6 2) - @result{} 3 -@end group -@group -(/ 5 2) - @result{} 2 -@end group -@group -(/ 5.0 2) - @result{} 2.5 -@end group -@group -(/ 5 2.0) - @result{} 2.5 -@end group -@group -(/ 5.0 2.0) - @result{} 2.5 -@end group -@group -(/ 25 3 2) - @result{} 4 -@end group -@group -(/ -17 6) - @result{} -2 -@end group -@end example - -@cindex @code{arith-error} in division -If you divide an integer by the integer 0, Emacs signals an -@code{arith-error} error (@pxref{Errors}). Floating-point division of -a nonzero number by zero yields either positive or negative infinity -(@pxref{Float Basics}). -@end defun - -@defun % dividend divisor -@cindex remainder -This function returns the integer remainder after division of @var{dividend} -by @var{divisor}. The arguments must be integers or markers. - -For any two integers @var{dividend} and @var{divisor}, - -@example -@group -(+ (% @var{dividend} @var{divisor}) - (* (/ @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend} if @var{divisor} is nonzero. - -@example -(% 9 4) - @result{} 1 -(% -9 4) - @result{} -1 -(% 9 -4) - @result{} 1 -(% -9 -4) - @result{} -1 -@end example -@end defun - -@defun mod dividend divisor -@cindex modulus -This function returns the value of @var{dividend} modulo @var{divisor}; -in other words, the remainder after division of @var{dividend} -by @var{divisor}, but with the same sign as @var{divisor}. -The arguments must be numbers or markers. - -Unlike @code{%}, @code{mod} permits floating-point arguments; it -rounds the quotient downward (towards minus infinity) to an integer, -and uses that quotient to compute the remainder. - -If @var{divisor} is zero, @code{mod} signals an @code{arith-error} -error if both arguments are integers, and returns a NaN otherwise. - -@example -@group -(mod 9 4) - @result{} 1 -@end group -@group -(mod -9 4) - @result{} 3 -@end group -@group -(mod 9 -4) - @result{} -3 -@end group -@group -(mod -9 -4) - @result{} -1 -@end group -@group -(mod 5.5 2.5) - @result{} .5 -@end group -@end example - -For any two numbers @var{dividend} and @var{divisor}, - -@example -@group -(+ (mod @var{dividend} @var{divisor}) - (* (floor @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}, subject to rounding error if either -argument is floating point and to an @code{arith-error} if @var{dividend} is an -integer and @var{divisor} is 0. For @code{floor}, see @ref{Numeric -Conversions}. -@end defun - -@node Rounding Operations -@section Rounding Operations -@cindex rounding without conversion - -The functions @code{ffloor}, @code{fceiling}, @code{fround}, and -@code{ftruncate} take a floating-point argument and return a floating-point -result whose value is a nearby integer. @code{ffloor} returns the -nearest integer below; @code{fceiling}, the nearest integer above; -@code{ftruncate}, the nearest integer in the direction towards zero; -@code{fround}, the nearest integer. - -@defun ffloor float -This function rounds @var{float} to the next lower integral value, and -returns that value as a floating-point number. -@end defun - -@defun fceiling float -This function rounds @var{float} to the next higher integral value, and -returns that value as a floating-point number. -@end defun - -@defun ftruncate float -This function rounds @var{float} towards zero to an integral value, and -returns that value as a floating-point number. -@end defun - -@defun fround float -This function rounds @var{float} to the nearest integral value, -and returns that value as a floating-point number. -Rounding a value equidistant between two integers returns the even integer. -@end defun - -@node Bitwise Operations -@section Bitwise Operations on Integers -@cindex bitwise arithmetic -@cindex logical arithmetic - - In a computer, an integer is represented as a binary number, a -sequence of @dfn{bits} (digits which are either zero or one). A bitwise -operation acts on the individual bits of such a sequence. For example, -@dfn{shifting} moves the whole sequence left or right one or more places, -reproducing the same pattern ``moved over''. - - The bitwise operations in Emacs Lisp apply only to integers. - -@defun lsh integer1 count -@cindex logical shift -@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the -bits in @var{integer1} to the left @var{count} places, or to the right -if @var{count} is negative, bringing zeros into the vacated bits. If -@var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if -@var{integer1} is negative. Contrast this with @code{ash}, below. - -Here are two examples of @code{lsh}, shifting a pattern of bits one -place to the left. We show only the low-order eight bits of the binary -pattern; the rest are all zero. - -@example -@group -(lsh 5 1) - @result{} 10 -;; @r{Decimal 5 becomes decimal 10.} -00000101 @result{} 00001010 - -(lsh 7 1) - @result{} 14 -;; @r{Decimal 7 becomes decimal 14.} -00000111 @result{} 00001110 -@end group -@end example - -@noindent -As the examples illustrate, shifting the pattern of bits one place to -the left produces a number that is twice the value of the previous -number. - -Shifting a pattern of bits two places to the left produces results -like this (with 8-bit binary numbers): - -@example -@group -(lsh 3 2) - @result{} 12 -;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 -@end group -@end example - -On the other hand, shifting one place to the right looks like this: - -@example -@group -(lsh 6 -1) - @result{} 3 -;; @r{Decimal 6 becomes decimal 3.} -00000110 @result{} 00000011 -@end group - -@group -(lsh 5 -1) - @result{} 2 -;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 -@end group -@end example - -@noindent -As the example illustrates, shifting one place to the right divides the -value of a positive integer by two, rounding downward. - -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -536,870,911 produces @minus{}2 in the 30-bit implementation: - -@example -(lsh 536870911 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, the argument looks like this: - -@example -@group -;; @r{Decimal 536,870,911} -0111...111111 (30 bits total) -@end group -@end example - -@noindent -which becomes the following when left shifted: - -@example -@group -;; @r{Decimal @minus{}2} -1111...111110 (30 bits total) -@end group -@end example -@end defun - -@defun ash integer1 count -@cindex arithmetic shift -@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} -to the left @var{count} places, or to the right if @var{count} -is negative. - -@code{ash} gives the same results as @code{lsh} except when -@var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts ones in the empty bit positions on the left, while -@code{lsh} puts zeros in those bit positions. - -Thus, with @code{ash}, shifting the pattern of bits one place to the right -looks like this: - -@example -@group -(ash -6 -1) @result{} -3 -;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1111...111010 (30 bits total) - @result{} -1111...111101 (30 bits total) -@end group -@end example - -In contrast, shifting the pattern of bits one place to the right with -@code{lsh} looks like this: - -@example -@group -(lsh -6 -1) @result{} 536870909 -;; @r{Decimal @minus{}6 becomes decimal 536,870,909.} -1111...111010 (30 bits total) - @result{} -0111...111101 (30 bits total) -@end group -@end example - -Here are other examples: - -@c !!! Check if lined up in smallbook format! XDVI shows problem -@c with smallbook but not with regular book! --rjc 16mar92 -@smallexample -@group - ; @r{ 30-bit binary values} - -(lsh 5 2) ; 5 = @r{0000...000101} - @result{} 20 ; = @r{0000...010100} -@end group -@group -(ash 5 2) - @result{} 20 -(lsh -5 2) ; -5 = @r{1111...111011} - @result{} -20 ; = @r{1111...101100} -(ash -5 2) - @result{} -20 -@end group -@group -(lsh 5 -2) ; 5 = @r{0000...000101} - @result{} 1 ; = @r{0000...000001} -@end group -@group -(ash 5 -2) - @result{} 1 -@end group -@group -(lsh -5 -2) ; -5 = @r{1111...111011} - @result{} 268435454 - ; = @r{0011...111110} -@end group -@group -(ash -5 -2) ; -5 = @r{1111...111011} - @result{} -2 ; = @r{1111...111110} -@end group -@end smallexample -@end defun - -@defun logand &rest ints-or-markers -This function returns the ``logical and'' of the arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in all the arguments. (``Set'' means that the value of the bit is 1 -rather than 0.) - -For example, using 4-bit binary numbers, the ``logical and'' of 13 and -12 is 12: 1101 combined with 1100 produces 1100. -In both the binary numbers, the leftmost two bits are set (i.e., they -are 1's), so the leftmost two bits of the returned value are set. -However, for the rightmost two bits, each is zero in at least one of -the arguments, so the rightmost two bits of the returned value are 0's. - -@noindent -Therefore, - -@example -@group -(logand 13 12) - @result{} 12 -@end group -@end example - -If @code{logand} is not passed any argument, it returns a value of -@minus{}1. This number is an identity element for @code{logand} -because its binary representation consists entirely of ones. If -@code{logand} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 30-bit binary values} - -(logand 14 13) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - @result{} 12 ; 12 = @r{0000...001100} -@end group - -@group -(logand 14 13 4) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - ; 4 = @r{0000...000100} - @result{} 4 ; 4 = @r{0000...000100} -@end group - -@group -(logand) - @result{} -1 ; -1 = @r{1111...111111} -@end group -@end smallexample -@end defun - -@defun logior &rest ints-or-markers -This function returns the ``inclusive or'' of its arguments: the @var{n}th bit -is set in the result if, and only if, the @var{n}th bit is set in at least -one of the arguments. If there are no arguments, the result is zero, -which is an identity element for this operation. If @code{logior} is -passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 30-bit binary values} - -(logior 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 13 ; 13 = @r{0000...001101} -@end group - -@group -(logior 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 15 ; 15 = @r{0000...001111} -@end group -@end smallexample -@end defun - -@defun logxor &rest ints-or-markers -This function returns the ``exclusive or'' of its arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in an odd number of the arguments. If there are no arguments, the -result is 0, which is an identity element for this operation. If -@code{logxor} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 30-bit binary values} - -(logxor 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 9 ; 9 = @r{0000...001001} -@end group - -@group -(logxor 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 14 ; 14 = @r{0000...001110} -@end group -@end smallexample -@end defun - -@defun lognot integer -This function returns the logical complement of its argument: the @var{n}th -bit is one in the result if, and only if, the @var{n}th bit is zero in -@var{integer}, and vice-versa. - -@example -(lognot 5) - @result{} -6 -;; 5 = @r{0000...000101} (30 bits total) -;; @r{becomes} -;; -6 = @r{1111...111010} (30 bits total) -@end example -@end defun - -@node Math Functions -@section Standard Mathematical Functions -@cindex transcendental functions -@cindex mathematical functions -@cindex floating-point functions - - These mathematical functions allow integers as well as floating-point -numbers as arguments. - -@defun sin arg -@defunx cos arg -@defunx tan arg -These are the basic trigonometric functions, with argument @var{arg} -measured in radians. -@end defun - -@defun asin arg -The value of @code{(asin @var{arg})} is a number between -@ifnottex -@minus{}pi/2 -@end ifnottex -@tex -@math{-\pi/2} -@end tex -and -@ifnottex -pi/2 -@end ifnottex -@tex -@math{\pi/2} -@end tex -(inclusive) whose sine is @var{arg}. If @var{arg} is out of range -(outside [@minus{}1, 1]), @code{asin} returns a NaN. -@end defun - -@defun acos arg -The value of @code{(acos @var{arg})} is a number between 0 and -@ifnottex -pi -@end ifnottex -@tex -@math{\pi} -@end tex -(inclusive) whose cosine is @var{arg}. If @var{arg} is out of range -(outside [@minus{}1, 1]), @code{acos} returns a NaN. -@end defun - -@defun atan y &optional x -The value of @code{(atan @var{y})} is a number between -@ifnottex -@minus{}pi/2 -@end ifnottex -@tex -@math{-\pi/2} -@end tex -and -@ifnottex -pi/2 -@end ifnottex -@tex -@math{\pi/2} -@end tex -(exclusive) whose tangent is @var{y}. If the optional second -argument @var{x} is given, the value of @code{(atan y x)} is the -angle in radians between the vector @code{[@var{x}, @var{y}]} and the -@code{X} axis. -@end defun - -@defun exp arg -This is the exponential function; it returns @math{e} to the power -@var{arg}. -@end defun - -@defun log arg &optional base -This function returns the logarithm of @var{arg}, with base -@var{base}. If you don't specify @var{base}, the natural base -@math{e} is used. If @var{arg} or @var{base} is negative, @code{log} -returns a NaN. -@end defun - -@defun expt x y -This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an -integer; in this case, overflow causes truncation, so watch out. -If @var{x} is a finite negative number and @var{y} is a finite -non-integer, @code{expt} returns a NaN. -@end defun - -@defun sqrt arg -This returns the square root of @var{arg}. If @var{arg} is finite -and less than zero, @code{sqrt} returns a NaN. -@end defun - -In addition, Emacs defines the following common mathematical -constants: - -@defvar float-e -The mathematical constant @math{e} (2.71828@dots{}). -@end defvar - -@defvar float-pi -The mathematical constant @math{pi} (3.14159@dots{}). -@end defvar - -@node Random Numbers -@section Random Numbers -@cindex random numbers - - A deterministic computer program cannot generate true random -numbers. For most purposes, @dfn{pseudo-random numbers} suffice. A -series of pseudo-random numbers is generated in a deterministic -fashion. The numbers are not truly random, but they have certain -properties that mimic a random series. For example, all possible -values occur equally often in a pseudo-random series. - - Pseudo-random numbers are generated from a ``seed''. Starting from -any given seed, the @code{random} function always generates the same -sequence of numbers. By default, Emacs initializes the random seed at -startup, in such a way that the sequence of values of @code{random} -(with overwhelming likelihood) differs in each Emacs run. - - Sometimes you want the random number sequence to be repeatable. For -example, when debugging a program whose behavior depends on the random -number sequence, it is helpful to get the same behavior in each -program run. To make the sequence repeat, execute @code{(random "")}. -This sets the seed to a constant value for your particular Emacs -executable (though it may differ for other Emacs builds). You can use -other strings to choose various seed values. - -@defun random &optional limit -This function returns a pseudo-random integer. Repeated calls return a -series of pseudo-random integers. - -If @var{limit} is a positive integer, the value is chosen to be -nonnegative and less than @var{limit}. Otherwise, the value might be -any integer representable in Lisp, i.e., an integer between -@code{most-negative-fixnum} and @code{most-positive-fixnum} -(@pxref{Integer Basics}). - -If @var{limit} is @code{t}, it means to choose a new seed as if Emacs -were restarting. - -If @var{limit} is a string, it means to choose a new seed based on the -string's contents. - -@end defun diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi deleted file mode 100644 index 4e8182ccf34..00000000000 --- a/doc/lispref/objects.texi +++ /dev/null @@ -1,2123 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Lisp Data Types -@chapter Lisp Data Types -@cindex object -@cindex Lisp object -@cindex type -@cindex data type - - A Lisp @dfn{object} is a piece of data used and manipulated by Lisp -programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of -possible objects. - - Every object belongs to at least one type. Objects of the same type -have similar structures and may usually be used in the same contexts. -Types can overlap, and objects can belong to two or more types. -Consequently, we can ask whether an object belongs to a particular type, -but not for ``the'' type of an object. - -@cindex primitive type - A few fundamental object types are built into Emacs. These, from -which all other types are constructed, are called @dfn{primitive types}. -Each object belongs to one and only one primitive type. These types -include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol}, -@dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and -@dfn{byte-code function}, plus several special types, such as -@dfn{buffer}, that are related to editing. (@xref{Editing Types}.) - - Each primitive type has a corresponding Lisp function that checks -whether an object is a member of that type. - - Lisp is unlike many other languages in that its objects are -@dfn{self-typing}: the primitive type of each object is implicit in -the object itself. For example, if an object is a vector, nothing can -treat it as a number; Lisp knows it is a vector, not a number. - - In most languages, the programmer must declare the data type of each -variable, and the type is known by the compiler but not represented in -the data. Such type declarations do not exist in Emacs Lisp. A Lisp -variable can have any type of value, and it remembers whatever value -you store in it, type and all. (Actually, a small number of Emacs -Lisp variables can only take on values of a certain type. -@xref{Variables with Restricted Values}.) - - This chapter describes the purpose, printed representation, and read -syntax of each of the standard types in GNU Emacs Lisp. Details on how -to use these types can be found in later chapters. - -@menu -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. -@end menu - -@node Printed Representation -@section Printed Representation and Read Syntax -@cindex printed representation -@cindex read syntax - - The @dfn{printed representation} of an object is the format of the -output generated by the Lisp printer (the function @code{prin1}) for -that object. Every data type has a unique printed representation. -The @dfn{read syntax} of an object is the format of the input accepted -by the Lisp reader (the function @code{read}) for that object. This -is not necessarily unique; many kinds of object have more than one -syntax. @xref{Read and Print}. - -@cindex hash notation - In most cases, an object's printed representation is also a read -syntax for the object. However, some types have no read syntax, since -it does not make sense to enter objects of these types as constants in -a Lisp program. These objects are printed in @dfn{hash notation}, -which consists of the characters @samp{#<}, a descriptive string -(typically the type name followed by the name of the object), and a -closing @samp{>}. For example: - -@example -(current-buffer) - @result{} # -@end example - -@noindent -Hash notation cannot be read at all, so the Lisp reader signals the -error @code{invalid-read-syntax} whenever it encounters @samp{#<}. -@kindex invalid-read-syntax - - In other languages, an expression is text; it has no other form. In -Lisp, an expression is primarily a Lisp object and only secondarily the -text that is the object's read syntax. Often there is no need to -emphasize this distinction, but you must keep it in the back of your -mind, or you will occasionally be very confused. - - When you evaluate an expression interactively, the Lisp interpreter -first reads the textual representation of it, producing a Lisp object, -and then evaluates that object (@pxref{Evaluation}). However, -evaluation and reading are separate activities. Reading returns the -Lisp object represented by the text that is read; the object may or may -not be evaluated later. @xref{Input Functions}, for a description of -@code{read}, the basic function for reading objects. - -@node Comments -@section Comments -@cindex comments -@cindex @samp{;} in comment - - A @dfn{comment} is text that is written in a program only for the sake -of humans that read the program, and that has no effect on the meaning -of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it -is not within a string or character constant. The comment continues to -the end of line. The Lisp reader discards comments; they do not become -part of the Lisp objects which represent the program within the Lisp -system. - - The @samp{#@@@var{count}} construct, which skips the next @var{count} -characters, is useful for program-generated comments containing binary -data. The Emacs Lisp byte compiler uses this in its output files -(@pxref{Byte Compilation}). It isn't meant for source files, however. - - @xref{Comment Tips}, for conventions for formatting comments. - -@node Programming Types -@section Programming Types -@cindex programming types - - There are two general categories of types in Emacs Lisp: those having -to do with Lisp programming, and those having to do with editing. The -former exist in many Lisp implementations, in one form or another. The -latter are unique to Emacs Lisp. - -@menu -* Integer Type:: Numbers without fractional parts. -* Floating-Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. -@end menu - -@node Integer Type -@subsection Integer Type - - The range of values for an integer depends on the machine. The -minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., -@ifnottex -@minus{}2**29 -@end ifnottex -@tex -@math{-2^{29}} -@end tex -to -@ifnottex -2**29 @minus{} 1) -@end ifnottex -@tex -@math{2^{29}-1}) -@end tex -but many machines provide a wider range. -Emacs Lisp arithmetic functions do not check for integer overflow. Thus -@code{(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 bits. - - The read syntax for integers is a sequence of (base ten) digits with an -optional sign at the beginning and an optional period at the end. The -printed representation produced by the Lisp interpreter never has a -leading @samp{+} or a final @samp{.}. - -@example -@group --1 ; @r{The integer @minus{}1.} -1 ; @r{The integer 1.} -1. ; @r{Also the integer 1.} -+1 ; @r{Also the integer 1.} -@end group -@end example - -@noindent -As a special exception, if a sequence of digits specifies an integer -too large or too small to be a valid integer object, the Lisp reader -reads it as a floating-point number (@pxref{Floating-Point Type}). -For instance, if Emacs integers are 30 bits, @code{536870912} is read -as the floating-point number @code{536870912.0}. - - @xref{Numbers}, for more information. - -@node Floating-Point Type -@subsection Floating-Point Type - - Floating-point numbers are the computer equivalent of scientific -notation; you can think of a floating-point number as a fraction -together with a power of ten. The precise number of significant -figures and the range of possible exponents is machine-specific; Emacs -uses the C data type @code{double} to store the value, and internally -this records a power of 2 rather than a power of 10. - - The printed representation for floating-point numbers requires either -a decimal point (with at least one digit following), an exponent, or -both. For example, @samp{1500.0}, @samp{+15e2}, @samp{15.0e+2}, -@samp{+1500000e-3}, and @samp{.15e4} are five ways of writing a floating-point -number whose value is 1500. They are all equivalent. - - @xref{Numbers}, for more information. - -@node Character Type -@subsection Character Type -@cindex @acronym{ASCII} character codes - - A @dfn{character} in Emacs Lisp is nothing more than an integer. In -other words, characters are represented by their character codes. For -example, the character @kbd{A} is represented as the @w{integer 65}. - - Individual characters are used occasionally in programs, but it is -more common to work with @emph{strings}, which are sequences composed -of characters. @xref{String Type}. - - Characters in strings and buffers are currently limited to the range -of 0 to 4194303---twenty two bits (@pxref{Character Codes}). Codes 0 -through 127 are @acronym{ASCII} codes; the rest are -non-@acronym{ASCII} (@pxref{Non-ASCII Characters}). Characters that -represent keyboard input have a much wider range, to encode modifier -keys such as Control, Meta and Shift. - - There are special functions for producing a human-readable textual -description of a character for the sake of messages. @xref{Describing -Characters}. - -@menu -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. -@end menu - -@node Basic Char Syntax -@subsubsection Basic Char Syntax -@cindex read syntax for characters -@cindex printed representation for characters -@cindex syntax for characters -@cindex @samp{?} in character constant -@cindex question mark in character constant - - Since characters are really integers, the printed representation of -a character is a decimal number. This is also a possible read syntax -for a character, but writing characters that way in Lisp programs is -not clear programming. You should @emph{always} use the special read -syntax formats that Emacs Lisp provides for characters. These syntax -formats start with a question mark. - - The usual read syntax for alphanumeric characters is a question mark -followed by the character; thus, @samp{?A} for the character -@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the -character @kbd{a}. - - For example: - -@example -?Q @result{} 81 ?q @result{} 113 -@end example - - You can use the same syntax for punctuation characters, but it is -often a good idea to add a @samp{\} so that the Emacs commands for -editing Lisp code don't get confused. For example, @samp{?\(} is the -way to write the open-paren character. If the character is @samp{\}, -you @emph{must} use a second @samp{\} to quote it: @samp{?\\}. - -@cindex whitespace -@cindex bell character -@cindex @samp{\a} -@cindex backspace -@cindex @samp{\b} -@cindex tab (ASCII character) -@cindex @samp{\t} -@cindex vertical tab -@cindex @samp{\v} -@cindex formfeed -@cindex @samp{\f} -@cindex newline -@cindex @samp{\n} -@cindex return (ASCII character) -@cindex @samp{\r} -@cindex escape (ASCII character) -@cindex @samp{\e} -@cindex space (ASCII character) -@cindex @samp{\s} - You can express the characters control-g, backspace, tab, newline, -vertical tab, formfeed, space, return, del, and escape as @samp{?\a}, -@samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, -@samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively. -(@samp{?\s} followed by a dash has a different meaning---it applies -the ``super'' modifier to the following character.) Thus, - -@example -?\a @result{} 7 ; @r{control-g, @kbd{C-g}} -?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}} -?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}} -?\n @result{} 10 ; @r{newline, @kbd{C-j}} -?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}} -?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}} -?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}} -?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}} -?\s @result{} 32 ; @r{space character, @key{SPC}} -?\\ @result{} 92 ; @r{backslash character, @kbd{\}} -?\d @result{} 127 ; @r{delete character, @key{DEL}} -@end example - -@cindex escape sequence - These sequences which start with backslash are also known as -@dfn{escape sequences}, because backslash plays the role of an -``escape character''; this terminology has nothing to do with the -character @key{ESC}. @samp{\s} is meant for use in character -constants; in string constants, just write the space. - - A backslash is allowed, and harmless, preceding any character without -a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}. -There is no reason to add a backslash before most characters. However, -you should add a backslash before any of the characters -@samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing -Lisp code. You can also add a backslash before whitespace characters such as -space, tab, newline and formfeed. However, it is cleaner to use one of -the easily readable escape sequences, such as @samp{\t} or @samp{\s}, -instead of an actual whitespace character such as a tab or a space. -(If you do write backslash followed by a space, you should write -an extra space after the character constant to separate it from the -following text.) - -@node General Escape Syntax -@subsubsection General Escape Syntax - - In addition to the specific escape sequences for special important -control characters, Emacs provides several types of escape syntax that -you can use to specify non-@acronym{ASCII} text characters. - -@cindex @samp{\} in character constant -@cindex backslash in character constants -@cindex unicode character escape - Firstly, you can specify characters by their Unicode values. -@code{?\u@var{nnnn}} represents a character with Unicode code point -@samp{U+@var{nnnn}}, where @var{nnnn} is (by convention) a hexadecimal -number with exactly four digits. The backslash indicates that the -subsequent characters form an escape sequence, and the @samp{u} -specifies a Unicode escape sequence. - - There is a slightly different syntax for specifying Unicode -characters with code points higher than @code{U+@var{ffff}}: -@code{?\U00@var{nnnnnn}} represents the character with code point -@samp{U+@var{nnnnnn}}, where @var{nnnnnn} is a six-digit hexadecimal -number. The Unicode Standard only defines code points up to -@samp{U+@var{10ffff}}, so if you specify a code point higher than -that, Emacs signals an error. - - Secondly, you can specify characters by their hexadecimal character -codes. A hexadecimal escape sequence consists of a backslash, -@samp{x}, and the hexadecimal character code. Thus, @samp{?\x41} is -the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and -@code{?\xe0} is the character -@iftex -@samp{@`a}. -@end iftex -@ifnottex -@samp{a} with grave accent. -@end ifnottex -You can use any number of hex digits, so you can represent any -character code in this way. - -@cindex octal character code - Thirdly, you can specify characters by their character code in -octal. An octal escape sequence consists of a backslash followed by -up to three octal digits; thus, @samp{?\101} for the character -@kbd{A}, @samp{?\001} for the character @kbd{C-a}, and @code{?\002} -for the character @kbd{C-b}. Only characters up to octal code 777 can -be specified this way. - - These escape sequences may also be used in strings. @xref{Non-ASCII -in Strings}. - -@node Ctl-Char Syntax -@subsubsection Control-Character Syntax - -@cindex control characters - Control characters can be represented using yet another read syntax. -This consists of a question mark followed by a backslash, caret, and the -corresponding non-control character, in either upper or lower case. For -example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the -character @kbd{C-i}, the character whose value is 9. - - Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is -equivalent to @samp{?\^I} and to @samp{?\^i}: - -@example -?\^I @result{} 9 ?\C-I @result{} 9 -@end example - - In strings and buffers, the only control characters allowed are those -that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn -any character into a control character with @samp{C-}. The character -codes for these non-@acronym{ASCII} control characters include the -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -bit as well as the code for the corresponding non-control character. -Ordinary text terminals have no way of generating non-@acronym{ASCII} -control characters, but you can generate them straightforwardly using -X and other window systems. - - For historical reasons, Emacs treats the @key{DEL} character as -the control equivalent of @kbd{?}: - -@example -?\^? @result{} 127 ?\C-? @result{} 127 -@end example - -@noindent -As a result, it is currently not possible to represent the character -@kbd{Control-?}, which is a meaningful input character under X, using -@samp{\C-}. It is not easy to change this, as various Lisp files refer -to @key{DEL} in this way. - - For representing control characters to be found in files or strings, -we recommend the @samp{^} syntax; for control characters in keyboard -input, we prefer the @samp{C-} syntax. Which one you use does not -affect the meaning of the program, but may guide the understanding of -people who read it. - -@node Meta-Char Syntax -@subsubsection Meta-Character Syntax - -@cindex meta characters - A @dfn{meta character} is a character typed with the @key{META} -modifier key. The integer that represents such a character has the -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit set. We use high bits for this and other modifiers to make -possible a wide range of basic character codes. - - In a string, the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit attached to an @acronym{ASCII} character indicates a meta -character; thus, the meta characters that can fit in a string have -codes in the range from 128 to 255, and are the meta versions of the -ordinary @acronym{ASCII} characters. @xref{Strings of Events}, for -details about @key{META}-handling in strings. - - The read syntax for meta characters uses @samp{\M-}. For example, -@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with -octal character codes (see below), with @samp{\C-}, or with any other -syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A}, -or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as -@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}. - -@node Other Char Bits -@subsubsection Other Character Modifier Bits - - The case of a graphic character is indicated by its character code; -for example, @acronym{ASCII} distinguishes between the characters @samp{a} -and @samp{A}. But @acronym{ASCII} has no way to represent whether a control -character is upper case or lower case. Emacs uses the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit to indicate that the shift key was used in typing a control -character. This distinction is possible only when you use X terminals -or other special terminals; ordinary text terminals do not report the -distinction. The Lisp syntax for the shift bit is @samp{\S-}; thus, -@samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o -character. - -@cindex hyper characters -@cindex super characters -@cindex alt characters - The X Window System defines three other -@anchor{modifier bits}modifier bits that can be set -in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes -for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is -significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents -@kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-} -represents the space character.) -@tex -Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}} -for super and @math{2^{24}} for hyper. -@end tex -@ifnottex -Numerically, the -bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper. -@end ifnottex - -@node Symbol Type -@subsection Symbol Type - - A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The -symbol name serves as the printed representation of the symbol. In -ordinary Lisp use, with one single obarray (@pxref{Creating Symbols}), -a symbol's name is unique---no two symbols have the same name. - - A symbol can serve as a variable, as a function name, or to hold a -property list. Or it may serve only to be distinct from all other Lisp -objects, so that its presence in a data structure may be recognized -reliably. In a given context, usually only one of these uses is -intended. But you can use one symbol in all of these ways, -independently. - - A symbol whose name starts with a colon (@samp{:}) is called a -@dfn{keyword symbol}. These symbols automatically act as constants, -and are normally used only by comparing an unknown symbol with a few -specific alternatives. @xref{Constant Variables}. - -@cindex @samp{\} in symbols -@cindex backslash in symbols - A symbol name can contain any characters whatever. Most symbol names -are written with letters, digits, and the punctuation characters -@samp{-+=*/}. Such names require no special punctuation; the characters -of the name suffice as long as the name does not look like a number. -(If it does, write a @samp{\} at the beginning of the name to force -interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are -less often used but also require no special punctuation. Any other -characters may be included in a symbol's name by escaping them with a -backslash. In contrast to its use in strings, however, a backslash in -the name of a symbol simply quotes the single character that follows the -backslash. For example, in a string, @samp{\t} represents a tab -character; in the name of a symbol, however, @samp{\t} merely quotes the -letter @samp{t}. To have a symbol with a tab character in its name, you -must actually use a tab (preceded with a backslash). But it's rare to -do such a thing. - -@cindex CL note---case of letters -@quotation -@b{Common Lisp note:} In Common Lisp, lower case letters are always -``folded'' to upper case, unless they are explicitly escaped. In Emacs -Lisp, upper case and lower case letters are distinct. -@end quotation - - Here are several examples of symbol names. Note that the @samp{+} in -the fourth example is escaped to prevent it from being read as a number. -This is not necessary in the sixth example because the rest of the name -makes it invalid as a number. - -@example -@group -foo ; @r{A symbol named @samp{foo}.} -FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} -@end group -@group -1+ ; @r{A symbol named @samp{1+}} - ; @r{(not @samp{+1}, which is an integer).} -@end group -@group -\+1 ; @r{A symbol named @samp{+1}} - ; @r{(not a very readable name).} -@end group -@group -\(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).} -@c the @'s in this next line use up three characters, hence the -@c apparent misalignment of the comment. -+-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.} - ; @r{These characters need not be escaped.} -@end group -@end example - -@cindex @samp{##} read syntax -@ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu -@cindex @samp{#@var{colon}} read syntax -@end ifinfo -@ifnotinfo -@cindex @samp{#:} read syntax -@end ifnotinfo - As an exception to the rule that a symbol's name serves as its -printed representation, @samp{##} is the printed representation for an -interned symbol whose name is an empty string. Furthermore, -@samp{#:@var{foo}} is the printed representation for an uninterned -symbol whose name is @var{foo}. (Normally, the Lisp reader interns -all symbols; @pxref{Creating Symbols}.) - -@node Sequence Type -@subsection Sequence Types - - A @dfn{sequence} is a Lisp object that represents an ordered set of -elements. There are two kinds of sequence in Emacs Lisp: @dfn{lists} -and @dfn{arrays}. - - Lists are the most commonly-used sequences. A list can hold -elements of any type, and its length can be easily changed by adding -or removing elements. See the next subsection for more about lists. - - Arrays are fixed-length sequences. They are further subdivided into -strings, vectors, char-tables and bool-vectors. Vectors can hold -elements of any type, whereas string elements must be characters, and -bool-vector elements must be @code{t} or @code{nil}. Char-tables are -like vectors except that they are indexed by any valid character code. -The characters in a string can have text properties like characters in -a buffer (@pxref{Text Properties}), but vectors do not support text -properties, even when their elements happen to be characters. - - Lists, strings and the other array types also share important -similarities. For example, all have a length @var{l}, and all have -elements which can be indexed from zero to @var{l} minus one. Several -functions, called sequence functions, accept any kind of sequence. -For example, the function @code{length} reports the length of any kind -of sequence. @xref{Sequences Arrays Vectors}. - - It is generally impossible to read the same sequence twice, since -sequences are always created anew upon reading. If you read the read -syntax for a sequence twice, you get two sequences with equal contents. -There is one exception: the empty list @code{()} always stands for the -same object, @code{nil}. - -@node Cons Cell Type -@subsection Cons Cell and List Types -@cindex address field of register -@cindex decrement field of register -@cindex pointers - - A @dfn{cons cell} is an object that consists of two slots, called -the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any -Lisp object. We also say that ``the @sc{car} of this cons cell is'' -whatever object its @sc{car} slot currently holds, and likewise for -the @sc{cdr}. - -@cindex list structure - A @dfn{list} is a series of cons cells, linked together so that the -@sc{cdr} slot of each cons cell holds either the next cons cell or the -empty list. The empty list is actually the symbol @code{nil}. -@xref{Lists}, for details. Because most cons cells are used as part -of lists, we refer to any structure made out of cons cells as a -@dfn{list structure}. - -@cindex linked list -@quotation -A note to C programmers: a Lisp list thus works as a @dfn{linked list} -built up of cons cells. Because pointers in Lisp are implicit, we do -not distinguish between a cons cell slot ``holding'' a value versus -``pointing to'' the value. -@end quotation - -@cindex atoms - Because cons cells are so central to Lisp, we also have a word for -``an object which is not a cons cell''. These objects are called -@dfn{atoms}. - -@cindex parenthesis -@cindex @samp{(@dots{})} in lists - The read syntax and printed representation for lists are identical, and -consist of a left parenthesis, an arbitrary number of elements, and a -right parenthesis. Here are examples of lists: - -@example -(A 2 "A") ; @r{A list of three elements.} -() ; @r{A list of no elements (the empty list).} -nil ; @r{A list of no elements (the empty list).} -("A ()") ; @r{A list of one element: the string @code{"A ()"}.} -(A ()) ; @r{A list of two elements: @code{A} and the empty list.} -(A nil) ; @r{Equivalent to the previous.} -((A B C)) ; @r{A list of one element} - ; @r{(which is a list of three elements).} -@end example - - Upon reading, each object inside the parentheses becomes an element -of the list. That is, a cons cell is made for each element. The -@sc{car} slot of the cons cell holds the element, and its @sc{cdr} -slot refers to the next cons cell of the list, which holds the next -element in the list. The @sc{cdr} slot of the last cons cell is set to -hold @code{nil}. - - The names @sc{car} and @sc{cdr} derive from the history of Lisp. The -original Lisp implementation ran on an @w{IBM 704} computer which -divided words into two parts, called the ``address'' part and the -``decrement''; @sc{car} was an instruction to extract the contents of -the address part of a register, and @sc{cdr} an instruction to extract -the contents of the decrement. By contrast, ``cons cells'' are named -for the function @code{cons} that creates them, which in turn was named -for its purpose, the construction of cells. - -@menu -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. -@end menu - -@node Box Diagrams -@subsubsection Drawing Lists as Box Diagrams -@cindex box diagrams, for lists -@cindex diagrams, boxed, for lists - - A list can be illustrated by a diagram in which the cons cells are -shown as pairs of boxes, like dominoes. (The Lisp reader cannot read -such an illustration; unlike the textual notation, which can be -understood by both humans and computers, the box illustrations can be -understood only by humans.) This picture represents the three-element -list @code{(rose violet buttercup)}: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example - - In this diagram, each box represents a slot that can hold or refer to -any Lisp object. Each pair of boxes represents a cons cell. Each arrow -represents a reference to a Lisp object, either an atom or another cons -cell. - - In this example, the first box, which holds the @sc{car} of the first -cons cell, refers to or ``holds'' @code{rose} (a symbol). The second -box, holding the @sc{cdr} of the first cons cell, refers to the next -pair of boxes, the second cons cell. The @sc{car} of the second cons -cell is @code{violet}, and its @sc{cdr} is the third cons cell. The -@sc{cdr} of the third (and last) cons cell is @code{nil}. - - Here is another diagram of the same list, @code{(rose violet -buttercup)}, sketched in a different manner: - -@smallexample -@group - --------------- ---------------- ------------------- -| car | cdr | | car | cdr | | car | cdr | -| rose | o-------->| violet | o-------->| buttercup | nil | -| | | | | | | | | - --------------- ---------------- ------------------- -@end group -@end smallexample - -@cindex @code{nil} as a list -@cindex empty list - A list with no elements in it is the @dfn{empty list}; it is identical -to the symbol @code{nil}. In other words, @code{nil} is both a symbol -and a list. - - Here is the list @code{(A ())}, or equivalently @code{(A nil)}, -depicted with boxes and arrows: - -@example -@group - --- --- --- --- - | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> A --> nil -@end group -@end example - - Here is a more complex illustration, showing the three-element list, -@code{((pine needles) oak maple)}, the first element of which is a -two-element list: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - | --> oak --> maple - | - | --- --- --- --- - --> | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> pine --> needles -@end group -@end example - - The same list represented in the second box notation looks like this: - -@example -@group - -------------- -------------- -------------- -| car | cdr | | car | cdr | | car | cdr | -| o | o------->| oak | o------->| maple | nil | -| | | | | | | | | | - -- | --------- -------------- -------------- - | - | - | -------------- ---------------- - | | car | cdr | | car | cdr | - ------>| pine | o------->| needles | nil | - | | | | | | - -------------- ---------------- -@end group -@end example - -@node Dotted Pair Notation -@subsubsection Dotted Pair Notation -@cindex dotted pair notation -@cindex @samp{.} in lists - - @dfn{Dotted pair notation} is a general syntax for cons cells that -represents the @sc{car} and @sc{cdr} explicitly. In this syntax, -@code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is -the object @var{a} and whose @sc{cdr} is the object @var{b}. Dotted -pair notation is more general than list syntax because the @sc{cdr} -does not have to be a list. However, it is more cumbersome in cases -where list syntax would work. In dotted pair notation, the list -@samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For -@code{nil}-terminated lists, you can use either notation, but list -notation is usually clearer and more convenient. When printing a -list, the dotted pair notation is only used if the @sc{cdr} of a cons -cell is not a list. - - Here's an example using boxes to illustrate dotted pair notation. -This example shows the pair @code{(rose . violet)}: - -@example -@group - --- --- - | | |--> violet - --- --- - | - | - --> rose -@end group -@end example - - You can combine dotted pair notation with list notation to represent -conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}. -You write a dot after the last element of the list, followed by the -@sc{cdr} of the final cons cell. For example, @code{(rose violet -. buttercup)} is equivalent to @code{(rose . (violet . buttercup))}. -The object looks like this: - -@example -@group - --- --- --- --- - | | |--> | | |--> buttercup - --- --- --- --- - | | - | | - --> rose --> violet -@end group -@end example - - The syntax @code{(rose .@: violet .@: buttercup)} is invalid because -there is nothing that it could mean. If anything, it would say to put -@code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already -used for @code{violet}. - - The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}, -and looks like this: - -@example -@group - --- --- --- --- - | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> rose --> violet -@end group -@end example - - Similarly, the three-element list @code{(rose violet buttercup)} -is equivalent to @code{(rose . (violet . (buttercup)))}. -@ifnottex -It looks like this: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example -@end ifnottex - -@node Association List Type -@subsubsection Association List Type - - An @dfn{association list} or @dfn{alist} is a specially-constructed -list whose elements are cons cells. In each element, the @sc{car} is -considered a @dfn{key}, and the @sc{cdr} is considered an -@dfn{associated value}. (In some cases, the associated value is stored -in the @sc{car} of the @sc{cdr}.) Association lists are often used as -stacks, since it is easy to add or remove associations at the front of -the list. - - For example, - -@example -(setq alist-of-colors - '((rose . red) (lily . white) (buttercup . yellow))) -@end example - -@noindent -sets the variable @code{alist-of-colors} to an alist of three elements. In the -first element, @code{rose} is the key and @code{red} is the value. - - @xref{Association Lists}, for a further explanation of alists and for -functions that work on alists. @xref{Hash Tables}, for another kind of -lookup table, which is much faster for handling a large number of keys. - -@node Array Type -@subsection Array Type - - An @dfn{array} is composed of an arbitrary number of slots for -holding or referring to other Lisp objects, arranged in a contiguous block of -memory. Accessing any element of an array takes approximately the same -amount of time. In contrast, accessing an element of a list requires -time proportional to the position of the element in the list. (Elements -at the end of a list take longer to access than elements at the -beginning of a list.) - - Emacs defines four types of array: strings, vectors, bool-vectors, and -char-tables. - - A string is an array of characters and a vector is an array of -arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}. -These kinds of array may have any length up to the largest integer. -Char-tables are sparse arrays indexed by any valid character code; they -can hold arbitrary objects. - - The first element of an array has index zero, the second element has -index 1, and so on. This is called @dfn{zero-origin} indexing. For -example, an array of four elements has indices 0, 1, 2, @w{and 3}. The -largest possible index value is one less than the length of the array. -Once an array is created, its length is fixed. - - All Emacs Lisp arrays are one-dimensional. (Most other programming -languages support multidimensional arrays, but they are not essential; -you can get the same effect with nested one-dimensional arrays.) Each -type of array has its own read syntax; see the following sections for -details. - - The array type is a subset of the sequence type, and contains the -string type, the vector type, the bool-vector type, and the char-table -type. - -@node String Type -@subsection String Type - - A @dfn{string} is an array of characters. Strings are used for many -purposes in Emacs, as can be expected in a text editor; for example, as -the names of Lisp symbols, as messages for the user, and to represent -text extracted from buffers. Strings in Lisp are constants: evaluation -of a string returns the same string. - - @xref{Strings and Characters}, for functions that operate on strings. - -@menu -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. -@end menu - -@node Syntax for Strings -@subsubsection Syntax for Strings - -@cindex @samp{"} in strings -@cindex double-quote in strings -@cindex @samp{\} in strings -@cindex backslash in strings - The read syntax for a string is a double-quote, an arbitrary number -of characters, and another double-quote, @code{"like this"}. To -include a double-quote in a string, precede it with a backslash; thus, -@code{"\""} is a string containing just a single double-quote -character. Likewise, you can include a backslash by preceding it with -another backslash, like this: @code{"this \\ is a single embedded -backslash"}. - -@cindex newline in strings - The newline character is not special in the read syntax for strings; -if you write a new line between the double-quotes, it becomes a -character in the string. But an escaped newline---one that is preceded -by @samp{\}---does not become part of the string; i.e., the Lisp reader -ignores an escaped newline while reading a string. An escaped space -@w{@samp{\ }} is likewise ignored. - -@example -"It is useful to include newlines -in documentation strings, -but the newline is \ -ignored if escaped." - @result{} "It is useful to include newlines -in documentation strings, -but the newline is ignored if escaped." -@end example - -@node Non-ASCII in Strings -@subsubsection Non-@acronym{ASCII} Characters in Strings - - There are two text representations for non-@acronym{ASCII} -characters in Emacs strings: multibyte and unibyte (@pxref{Text -Representations}). Roughly speaking, unibyte strings store raw bytes, -while multibyte strings store human-readable text. Each character in -a unibyte string is a byte, i.e., its value is between 0 and 255. By -contrast, each character in a multibyte string may have a value -between 0 to 4194303 (@pxref{Character Type}). In both cases, -characters above 127 are non-@acronym{ASCII}. - - You can include a non-@acronym{ASCII} character in a string constant -by writing it literally. If the string constant is read from a -multibyte source, such as a multibyte buffer or string, or a file that -would be visited as multibyte, then Emacs reads each -non-@acronym{ASCII} character as a multibyte character and -automatically makes the string a multibyte string. If the string -constant is read from a unibyte source, then Emacs reads the -non-@acronym{ASCII} character as unibyte, and makes the string -unibyte. - - Instead of writing a character literally into a multibyte string, -you can write it as its character code using an escape sequence. -@xref{General Escape Syntax}, for details about escape sequences. - - If you use any Unicode-style escape sequence @samp{\uNNNN} or -@samp{\U00NNNNNN} in a string constant (even for an @acronym{ASCII} -character), Emacs automatically assumes that it is multibyte. - - You can also use hexadecimal escape sequences (@samp{\x@var{n}}) and -octal escape sequences (@samp{\@var{n}}) in string constants. -@strong{But beware:} If a string constant contains hexadecimal or -octal escape sequences, and these escape sequences all specify unibyte -characters (i.e., less than 256), and there are no other literal -non-@acronym{ASCII} characters or Unicode-style escape sequences in -the string, then Emacs automatically assumes that it is a unibyte -string. That is to say, it assumes that all non-@acronym{ASCII} -characters occurring in the string are 8-bit raw bytes. - - In hexadecimal and octal escape sequences, the escaped character -code may contain a variable number of digits, so the first subsequent -character which is not a valid hexadecimal or octal digit terminates -the escape sequence. If the next character in a string could be -interpreted as a hexadecimal or octal digit, write @w{@samp{\ }} -(backslash and space) to terminate the escape sequence. For example, -@w{@samp{\xe0\ }} represents one character, @samp{a} with grave -accent. @w{@samp{\ }} in a string constant is just like -backslash-newline; it does not contribute any character to the string, -but it does terminate any preceding hex escape. - -@node Nonprinting Characters -@subsubsection Nonprinting Characters in Strings - - You can use the same backslash escape-sequences in a string constant -as in character literals (but do not use the question mark that begins a -character constant). For example, you can write a string containing the -nonprinting characters tab and @kbd{C-a}, with commas and spaces between -them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a -description of the read syntax for characters. - - However, not all of the characters you can write with backslash -escape-sequences are valid in strings. The only control characters that -a string can hold are the @acronym{ASCII} control characters. Strings do not -distinguish case in @acronym{ASCII} control characters. - - Properly speaking, strings cannot hold meta characters; but when a -string is to be used as a key sequence, there is a special convention -that provides a way to represent meta versions of @acronym{ASCII} -characters in a string. If you use the @samp{\M-} syntax to indicate -a meta character in a string constant, this sets the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit of the character in the string. If the string is used in -@code{define-key} or @code{lookup-key}, this numeric code is translated -into the equivalent meta character. @xref{Character Type}. - - Strings cannot hold characters that have the hyper, super, or alt -modifiers. - -@node Text Props and Strings -@subsubsection Text Properties in Strings - -@cindex @samp{#(} read syntax -@cindex text properties, read syntax - A string can hold properties for the characters it contains, in -addition to the characters themselves. This enables programs that copy -text between strings and buffers to copy the text's properties with no -special effort. @xref{Text Properties}, for an explanation of what text -properties mean. Strings with text properties use a special read and -print syntax: - -@example -#("@var{characters}" @var{property-data}...) -@end example - -@noindent -where @var{property-data} consists of zero or more elements, in groups -of three as follows: - -@example -@var{beg} @var{end} @var{plist} -@end example - -@noindent -The elements @var{beg} and @var{end} are integers, and together specify -a range of indices in the string; @var{plist} is the property list for -that range. For example, - -@example -#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic)) -@end example - -@noindent -represents a string whose textual contents are @samp{foo bar}, in which -the first three characters have a @code{face} property with value -@code{bold}, and the last three have a @code{face} property with value -@code{italic}. (The fourth character has no text properties, so its -property list is @code{nil}. It is not actually necessary to mention -ranges with @code{nil} as the property list, since any characters not -mentioned in any range will default to having no properties.) - -@node Vector Type -@subsection Vector Type - - A @dfn{vector} is a one-dimensional array of elements of any type. It -takes a constant amount of time to access any element of a vector. (In -a list, the access time of an element is proportional to the distance of -the element from the beginning of the list.) - - The printed representation of a vector consists of a left square -bracket, the elements, and a right square bracket. This is also the -read syntax. Like numbers and strings, vectors are considered constants -for evaluation. - -@example -[1 "two" (three)] ; @r{A vector of three elements.} - @result{} [1 "two" (three)] -@end example - - @xref{Vectors}, for functions that work with vectors. - -@node Char-Table Type -@subsection Char-Table Type - - A @dfn{char-table} is a one-dimensional array of elements of any type, -indexed by character codes. Char-tables have certain extra features to -make them more useful for many jobs that involve assigning information -to character codes---for example, a char-table can have a parent to -inherit from, a default value, and a small number of extra slots to use for -special purposes. A char-table can also specify a single value for -a whole character set. - -@cindex @samp{#^} read syntax - The printed representation of a char-table is like a vector -except that there is an extra @samp{#^} at the beginning.@footnote{You -may also encounter @samp{#^^}, used for ``sub-char-tables''.} - - @xref{Char-Tables}, for special functions to operate on char-tables. -Uses of char-tables include: - -@itemize @bullet -@item -Case tables (@pxref{Case Tables}). - -@item -Character category tables (@pxref{Categories}). - -@item -Display tables (@pxref{Display Tables}). - -@item -Syntax tables (@pxref{Syntax Tables}). -@end itemize - -@node Bool-Vector Type -@subsection Bool-Vector Type - - A @dfn{bool-vector} is a one-dimensional array whose elements must -be @code{t} or @code{nil}. - - The printed representation of a bool-vector is like a string, except -that it begins with @samp{#&} followed by the length. The string -constant that follows actually specifies the contents of the bool-vector -as a bitmap---each ``character'' in the string contains 8 bits, which -specify the next 8 elements of the bool-vector (1 stands for @code{t}, -and 0 for @code{nil}). The least significant bits of the character -correspond to the lowest indices in the bool-vector. - -@example -(make-bool-vector 3 t) - @result{} #&3"^G" -(make-bool-vector 3 nil) - @result{} #&3"^@@" -@end example - -@noindent -These results make sense, because the binary code for @samp{C-g} is -111 and @samp{C-@@} is the character with code 0. - - If the length is not a multiple of 8, the printed representation -shows extra elements, but these extras really make no difference. For -instance, in the next example, the two bool-vectors are equal, because -only the first 3 bits are used: - -@example -(equal #&3"\377" #&3"\007") - @result{} t -@end example - -@node Hash Table Type -@subsection Hash Table Type - - A hash table is a very fast kind of lookup table, somewhat like an -alist in that it maps keys to corresponding values, but much faster. -The printed representation of a hash table specifies its properties -and contents, like this: - -@example -(make-hash-table) - @result{} #s(hash-table size 65 test eql rehash-size 1.5 - rehash-threshold 0.8 data ()) -@end example - -@noindent -@xref{Hash Tables}, for more information about hash tables. - -@node Function Type -@subsection Function Type - - Lisp functions are executable code, just like functions in other -programming languages. In Lisp, unlike most languages, functions are -also Lisp objects. A non-compiled function in Lisp is a lambda -expression: that is, a list whose first element is the symbol -@code{lambda} (@pxref{Lambda Expressions}). - - In most programming languages, it is impossible to have a function -without a name. In Lisp, a function has no intrinsic name. A lambda -expression can be called as a function even though it has no name; to -emphasize this, we also call it an @dfn{anonymous function} -(@pxref{Anonymous Functions}). A named function in Lisp is just a -symbol with a valid function in its function cell (@pxref{Defining -Functions}). - - Most of the time, functions are called when their names are written in -Lisp expressions in Lisp programs. However, you can construct or obtain -a function object at run time and then call it with the primitive -functions @code{funcall} and @code{apply}. @xref{Calling Functions}. - -@node Macro Type -@subsection Macro Type - - A @dfn{Lisp macro} is a user-defined construct that extends the Lisp -language. It is represented as an object much like a function, but with -different argument-passing semantics. A Lisp macro has the form of a -list whose first element is the symbol @code{macro} and whose @sc{cdr} -is a Lisp function object, including the @code{lambda} symbol. - - Lisp macro objects are usually defined with the built-in -@code{defmacro} function, but any list that begins with @code{macro} is -a macro as far as Emacs is concerned. @xref{Macros}, for an explanation -of how to write a macro. - - @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard -Macros}) are entirely different things. When we use the word ``macro'' -without qualification, we mean a Lisp macro, not a keyboard macro. - -@node Primitive Function Type -@subsection Primitive Function Type -@cindex primitive function - - A @dfn{primitive function} is a function callable from Lisp but -written in the C programming language. Primitive functions are also -called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is -derived from ``subroutine''.) Most primitive functions evaluate all -their arguments when they are called. A primitive function that does -not evaluate all its arguments is called a @dfn{special form} -(@pxref{Special Forms}). - - It does not matter to the caller of a function whether the function is -primitive. However, this does matter if you try to redefine a primitive -with a function written in Lisp. The reason is that the primitive -function may be called directly from C code. Calls to the redefined -function from Lisp will use the new definition, but calls from C code -may still use the built-in definition. Therefore, @strong{we discourage -redefinition of primitive functions}. - - The term @dfn{function} refers to all Emacs functions, whether written -in Lisp or C@. @xref{Function Type}, for information about the -functions written in Lisp. - - Primitive functions have no read syntax and print in hash notation -with the name of the subroutine. - -@example -@group -(symbol-function 'car) ; @r{Access the function cell} - ; @r{of the symbol.} - @result{} # -(subrp (symbol-function 'car)) ; @r{Is this a primitive function?} - @result{} t ; @r{Yes.} -@end group -@end example - -@node Byte-Code Type -@subsection Byte-Code Function Type - -@dfn{Byte-code function objects} are produced by byte-compiling Lisp -code (@pxref{Byte Compilation}). Internally, a byte-code function -object is much like a vector; however, the evaluator handles this data -type specially when it appears in a function call. @xref{Byte-Code -Objects}. - -The printed representation and read syntax for a byte-code function -object is like that for a vector, with an additional @samp{#} before the -opening @samp{[}. - -@node Autoload Type -@subsection Autoload Type - - An @dfn{autoload object} is a list whose first element is the symbol -@code{autoload}. It is stored as the function definition of a symbol, -where it serves as a placeholder for the real definition. The autoload -object says that the real definition is found in a file of Lisp code -that should be loaded when necessary. It contains the name of the file, -plus some other information about the real definition. - - After the file has been loaded, the symbol should have a new function -definition that is not an autoload object. The new definition is then -called as if it had been there to begin with. From the user's point of -view, the function call works as expected, using the function definition -in the loaded file. - - An autoload object is usually created with the function -@code{autoload}, which stores the object in the function cell of a -symbol. @xref{Autoload}, for more details. - -@node Editing Types -@section Editing Types -@cindex editing types - - The types in the previous section are used for general programming -purposes, and most of them are common to most Lisp dialects. Emacs Lisp -provides several additional data types for purposes connected with -editing. - -@menu -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. -@end menu - -@node Buffer Type -@subsection Buffer Type - - A @dfn{buffer} is an object that holds text that can be edited -(@pxref{Buffers}). Most buffers hold the contents of a disk file -(@pxref{Files}) so they can be edited, but some are used for other -purposes. Most buffers are also meant to be seen by the user, and -therefore displayed, at some time, in a window (@pxref{Windows}). But -a buffer need not be displayed in any window. Each buffer has a -designated position called @dfn{point} (@pxref{Positions}); most -editing commands act on the contents of the current buffer in the -neighborhood of point. At any time, one buffer is the @dfn{current -buffer}. - - The contents of a buffer are much like a string, but buffers are not -used like strings in Emacs Lisp, and the available operations are -different. For example, you can insert text efficiently into an -existing buffer, altering the buffer's contents, whereas ``inserting'' -text into a string requires concatenating substrings, and the result -is an entirely new string object. - - Many of the standard Emacs functions manipulate or test the -characters in the current buffer; a whole chapter in this manual is -devoted to describing these functions (@pxref{Text}). - - Several other data structures are associated with each buffer: - -@itemize @bullet -@item -a local syntax table (@pxref{Syntax Tables}); - -@item -a local keymap (@pxref{Keymaps}); and, - -@item -a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}). - -@item -overlays (@pxref{Overlays}). - -@item -text properties for the text in the buffer (@pxref{Text Properties}). -@end itemize - -@noindent -The local keymap and variable list contain entries that individually -override global bindings or values. These are used to customize the -behavior of programs in different buffers, without actually changing the -programs. - - A buffer may be @dfn{indirect}, which means it shares the text -of another buffer, but presents it differently. @xref{Indirect Buffers}. - - Buffers have no read syntax. They print in hash notation, showing the -buffer name. - -@example -@group -(current-buffer) - @result{} # -@end group -@end example - -@node Marker Type -@subsection Marker Type - - A @dfn{marker} denotes a position in a specific buffer. Markers -therefore have two components: one for the buffer, and one for the -position. Changes in the buffer's text automatically relocate the -position value as necessary to ensure that the marker always points -between the same two characters in the buffer. - - Markers have no read syntax. They print in hash notation, giving the -current character position and the name of the buffer. - -@example -@group -(point-marker) - @result{} # -@end group -@end example - -@xref{Markers}, for information on how to test, create, copy, and move -markers. - -@node Window Type -@subsection Window Type - - A @dfn{window} describes the portion of the terminal screen that Emacs -uses to display a buffer. Every window has one associated buffer, whose -contents appear in the window. By contrast, a given buffer may appear -in one window, no window, or several windows. - - Though many windows may exist simultaneously, at any time one window -is designated the @dfn{selected window}. This is the window where the -cursor is (usually) displayed when Emacs is ready for a command. The -selected window usually displays the current buffer, but this is not -necessarily the case. - - Windows are grouped on the screen into frames; each window belongs to -one and only one frame. @xref{Frame Type}. - - Windows have no read syntax. They print in hash notation, giving the -window number and the name of the buffer being displayed. The window -numbers exist to identify windows uniquely, since the buffer displayed -in any given window can change frequently. - -@example -@group -(selected-window) - @result{} # -@end group -@end example - - @xref{Windows}, for a description of the functions that work on windows. - -@node Frame Type -@subsection Frame Type - - A @dfn{frame} is a screen area that contains one or more Emacs -windows; we also use the term ``frame'' to refer to the Lisp object -that Emacs uses to refer to the screen area. - - Frames have no read syntax. They print in hash notation, giving the -frame's title, plus its address in core (useful to identify the frame -uniquely). - -@example -@group -(selected-frame) - @result{} # -@end group -@end example - - @xref{Frames}, for a description of the functions that work on frames. - -@node Terminal Type -@subsection Terminal Type -@cindex terminal type - - A @dfn{terminal} is a device capable of displaying one or more -Emacs frames (@pxref{Frame Type}). - - Terminals have no read syntax. They print in hash notation giving -the terminal's ordinal number and its TTY device file name. - -@example -@group -(get-device-terminal nil) - @result{} # -@end group -@end example - -@c FIXME: add an xref to where terminal-related primitives are described. - -@node Window Configuration Type -@subsection Window Configuration Type -@cindex window layout in a frame - - A @dfn{window configuration} stores information about the positions, -sizes, and contents of the windows in a frame, so you can recreate the -same arrangement of windows later. - - Window configurations do not have a read syntax; their print syntax -looks like @samp{#}. @xref{Window -Configurations}, for a description of several functions related to -window configurations. - -@node Frame Configuration Type -@subsection Frame Configuration Type -@cindex screen layout -@cindex window layout, all frames - - A @dfn{frame configuration} stores information about the positions, -sizes, and contents of the windows in all frames. It is not a -primitive type---it is actually a list whose @sc{car} is -@code{frame-configuration} and whose @sc{cdr} is an alist. Each alist -element describes one frame, which appears as the @sc{car} of that -element. - - @xref{Frame Configurations}, for a description of several functions -related to frame configurations. - -@node Process Type -@subsection Process Type - - The word @dfn{process} usually means a running program. Emacs itself -runs in a process of this sort. However, in Emacs Lisp, a process is a -Lisp object that designates a subprocess created by the Emacs process. -Programs such as shells, GDB, ftp, and compilers, running in -subprocesses of Emacs, extend the capabilities of Emacs. - An Emacs subprocess takes textual input from Emacs and returns textual -output to Emacs for further manipulation. Emacs can also send signals -to the subprocess. - - Process objects have no read syntax. They print in hash notation, -giving the name of the process: - -@example -@group -(process-list) - @result{} (#) -@end group -@end example - -@xref{Processes}, for information about functions that create, delete, -return information about, send input or signals to, and receive output -from processes. - -@node Stream Type -@subsection Stream Type - - A @dfn{stream} is an object that can be used as a source or sink for -characters---either to supply characters for input or to accept them as -output. Many different types can be used this way: markers, buffers, -strings, and functions. Most often, input streams (character sources) -obtain characters from the keyboard, a buffer, or a file, and output -streams (character sinks) send characters to a buffer, such as a -@file{*Help*} buffer, or to the echo area. - - The object @code{nil}, in addition to its other meanings, may be used -as a stream. It stands for the value of the variable -@code{standard-input} or @code{standard-output}. Also, the object -@code{t} as a stream specifies input using the minibuffer -(@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo -Area}). - - Streams have no special printed representation or read syntax, and -print as whatever primitive type they are. - - @xref{Read and Print}, for a description of functions -related to streams, including parsing and printing functions. - -@node Keymap Type -@subsection Keymap Type - - A @dfn{keymap} maps keys typed by the user to commands. This mapping -controls how the user's command input is executed. A keymap is actually -a list whose @sc{car} is the symbol @code{keymap}. - - @xref{Keymaps}, for information about creating keymaps, handling prefix -keys, local as well as global keymaps, and changing key bindings. - -@node Overlay Type -@subsection Overlay Type - - An @dfn{overlay} specifies properties that apply to a part of a -buffer. Each overlay applies to a specified range of the buffer, and -contains a property list (a list whose elements are alternating property -names and values). Overlay properties are used to present parts of the -buffer temporarily in a different display style. Overlays have no read -syntax, and print in hash notation, giving the buffer name and range of -positions. - - @xref{Overlays}, for information on how you can create and use overlays. - -@node Font Type -@subsection Font Type - - A @dfn{font} specifies how to display text on a graphical terminal. -There are actually three separate font types---@dfn{font objects}, -@dfn{font specs}, and @dfn{font entities}---each of which has slightly -different properties. None of them have a read syntax; their print -syntax looks like @samp{#}, @samp{#}, and -@samp{#} respectively. @xref{Low-Level Font}, for a -description of these Lisp objects. - -@node Circular Objects -@section Read Syntax for Circular Objects -@cindex circular structure, read syntax -@cindex shared structure, read syntax -@cindex @samp{#@var{n}=} read syntax -@cindex @samp{#@var{n}#} read syntax - - To represent shared or circular structures within a complex of Lisp -objects, you can use the reader constructs @samp{#@var{n}=} and -@samp{#@var{n}#}. - - Use @code{#@var{n}=} before an object to label it for later reference; -subsequently, you can use @code{#@var{n}#} to refer the same object in -another place. Here, @var{n} is some integer. For example, here is how -to make a list in which the first element recurs as the third element: - -@example -(#1=(a) b #1#) -@end example - -@noindent -This differs from ordinary syntax such as this - -@example -((a) b (a)) -@end example - -@noindent -which would result in a list whose first and third elements -look alike but are not the same Lisp object. This shows the difference: - -@example -(prog1 nil - (setq x '(#1=(a) b #1#))) -(eq (nth 0 x) (nth 2 x)) - @result{} t -(setq x '((a) b (a))) -(eq (nth 0 x) (nth 2 x)) - @result{} nil -@end example - - You can also use the same syntax to make a circular structure, which -appears as an ``element'' within itself. Here is an example: - -@example -#1=(a #1#) -@end example - -@noindent -This makes a list whose second element is the list itself. -Here's how you can see that it really works: - -@example -(prog1 nil - (setq x '#1=(a #1#))) -(eq x (cadr x)) - @result{} t -@end example - - The Lisp printer can produce this syntax to record circular and shared -structure in a Lisp object, if you bind the variable @code{print-circle} -to a non-@code{nil} value. @xref{Output Variables}. - -@node Type Predicates -@section Type Predicates -@cindex type checking -@kindex wrong-type-argument - - The Emacs Lisp interpreter itself does not perform type checking on -the actual arguments passed to functions when they are called. It could -not do so, since function arguments in Lisp do not have declared data -types, as they do in other programming languages. It is therefore up to -the individual function to test whether each actual argument belongs to -a type that the function can use. - - All built-in functions do check the types of their actual arguments -when appropriate, and signal a @code{wrong-type-argument} error if an -argument is of the wrong type. For example, here is what happens if you -pass an argument to @code{+} that it cannot handle: - -@example -@group -(+ 2 'a) - @error{} Wrong type argument: number-or-marker-p, a -@end group -@end example - -@cindex type predicates -@cindex testing types - If you want your program to handle different types differently, you -must do explicit type checking. The most common way to check the type -of an object is to call a @dfn{type predicate} function. Emacs has a -type predicate for each type, as well as some predicates for -combinations of types. - - A type predicate function takes one argument; it returns @code{t} if -the argument belongs to the appropriate type, and @code{nil} otherwise. -Following a general Lisp convention for predicate functions, most type -predicates' names end with @samp{p}. - - Here is an example which uses the predicates @code{listp} to check for -a list and @code{symbolp} to check for a symbol. - -@example -(defun add-on (x) - (cond ((symbolp x) - ;; If X is a symbol, put it on LIST. - (setq list (cons x list))) - ((listp x) - ;; If X is a list, add its elements to LIST. - (setq list (append x list))) - (t - ;; We handle only symbols and lists. - (error "Invalid argument %s in add-on" x)))) -@end example - - Here is a table of predefined type predicates, in alphabetical order, -with references to further information. - -@table @code -@item atom -@xref{List-related Predicates, atom}. - -@item arrayp -@xref{Array Functions, arrayp}. - -@item bool-vector-p -@xref{Bool-Vectors, bool-vector-p}. - -@item bufferp -@xref{Buffer Basics, bufferp}. - -@item byte-code-function-p -@xref{Byte-Code Type, byte-code-function-p}. - -@item case-table-p -@xref{Case Tables, case-table-p}. - -@item char-or-string-p -@xref{Predicates for Strings, char-or-string-p}. - -@item char-table-p -@xref{Char-Tables, char-table-p}. - -@item commandp -@xref{Interactive Call, commandp}. - -@item consp -@xref{List-related Predicates, consp}. - -@item custom-variable-p -@xref{Variable Definitions, custom-variable-p}. - -@item display-table-p -@xref{Display Tables, display-table-p}. - -@item floatp -@xref{Predicates on Numbers, floatp}. - -@item fontp -@xref{Low-Level Font}. - -@item frame-configuration-p -@xref{Frame Configurations, frame-configuration-p}. - -@item frame-live-p -@xref{Deleting Frames, frame-live-p}. - -@item framep -@xref{Frames, framep}. - -@item functionp -@xref{Functions, functionp}. - -@item hash-table-p -@xref{Other Hash, hash-table-p}. - -@item integer-or-marker-p -@xref{Predicates on Markers, integer-or-marker-p}. - -@item integerp -@xref{Predicates on Numbers, integerp}. - -@item keymapp -@xref{Creating Keymaps, keymapp}. - -@item keywordp -@xref{Constant Variables}. - -@item listp -@xref{List-related Predicates, listp}. - -@item markerp -@xref{Predicates on Markers, markerp}. - -@item wholenump -@xref{Predicates on Numbers, wholenump}. - -@item nlistp -@xref{List-related Predicates, nlistp}. - -@item numberp -@xref{Predicates on Numbers, numberp}. - -@item number-or-marker-p -@xref{Predicates on Markers, number-or-marker-p}. - -@item overlayp -@xref{Overlays, overlayp}. - -@item processp -@xref{Processes, processp}. - -@item sequencep -@xref{Sequence Functions, sequencep}. - -@item stringp -@xref{Predicates for Strings, stringp}. - -@item subrp -@xref{Function Cells, subrp}. - -@item symbolp -@xref{Symbols, symbolp}. - -@item syntax-table-p -@xref{Syntax Tables, syntax-table-p}. - -@item vectorp -@xref{Vectors, vectorp}. - -@item window-configuration-p -@xref{Window Configurations, window-configuration-p}. - -@item window-live-p -@xref{Deleting Windows, window-live-p}. - -@item windowp -@xref{Basic Windows, windowp}. - -@item booleanp -@xref{nil and t, booleanp}. - -@item string-or-null-p -@xref{Predicates for Strings, string-or-null-p}. -@end table - - The most general way to check the type of an object is to call the -function @code{type-of}. Recall that each object belongs to one and -only one primitive type; @code{type-of} tells you which one (@pxref{Lisp -Data Types}). But @code{type-of} knows nothing about non-primitive -types. In most cases, it is more convenient to use type predicates than -@code{type-of}. - -@defun type-of object -This function returns a symbol naming the primitive type of -@var{object}. The value is one of the symbols @code{bool-vector}, -@code{buffer}, @code{char-table}, @code{compiled-function}, -@code{cons}, @code{float}, @code{font-entity}, @code{font-object}, -@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer}, -@code{marker}, @code{overlay}, @code{process}, @code{string}, -@code{subr}, @code{symbol}, @code{vector}, @code{window}, or -@code{window-configuration}. - -@example -(type-of 1) - @result{} integer -@group -(type-of 'nil) - @result{} symbol -(type-of '()) ; @r{@code{()} is @code{nil}.} - @result{} symbol -(type-of '(x)) - @result{} cons -@end group -@end example -@end defun - -@node Equality Predicates -@section Equality Predicates -@cindex equality - - Here we describe functions that test for equality between two -objects. Other functions test equality of contents between objects of -specific types, e.g., strings. For these predicates, see the -appropriate chapter describing the data type. - -@defun eq object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} are -the same object, and @code{nil} otherwise. - -If @var{object1} and @var{object2} are integers with the same value, -they are considered to be the same object (i.e., @code{eq} returns -@code{t}). If @var{object1} and @var{object2} are symbols with the -same name, they are normally the same object---but see @ref{Creating -Symbols} for exceptions. For other types (e.g., lists, vectors, -strings), two arguments with the same contents or elements are not -necessarily @code{eq} to each other: they are @code{eq} only if they -are the same object, meaning that a change in the contents of one will -be reflected by the same change in the contents of the other. - -@example -@group -(eq 'foo 'foo) - @result{} t -@end group - -@group -(eq 456 456) - @result{} t -@end group - -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(eq "" "") - @result{} t -;; @r{This exception occurs because Emacs Lisp} -;; @r{makes just one multibyte empty string, to save space.} -@end group - -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(setq foo '(1 (2 (3)))) - @result{} (1 (2 (3))) -(eq foo foo) - @result{} t -(eq foo '(1 (2 (3)))) - @result{} nil -@end group - -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -@noindent -The @code{make-symbol} function returns an uninterned symbol, distinct -from the symbol that is used if you write the name in a Lisp expression. -Distinct symbols with the same name are not @code{eq}. @xref{Creating -Symbols}. - -@example -@group -(eq (make-symbol "foo") 'foo) - @result{} nil -@end group -@end example -@end defun - -@defun equal object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} have -equal components, and @code{nil} otherwise. Whereas @code{eq} tests -if its arguments are the same object, @code{equal} looks inside -nonidentical arguments to see if their elements or contents are the -same. So, if two objects are @code{eq}, they are @code{equal}, but -the converse is not always true. - -@example -@group -(equal 'foo 'foo) - @result{} t -@end group - -@group -(equal 456 456) - @result{} t -@end group - -@group -(equal "asdf" "asdf") - @result{} t -@end group -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(equal '(1 (2 (3))) '(1 (2 (3)))) - @result{} t -@end group -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(equal [(1 2) 3] [(1 2) 3]) - @result{} t -@end group -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(equal (point-marker) (point-marker)) - @result{} t -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -Comparison of strings is case-sensitive, but does not take account of -text properties---it compares only the characters in the strings. -@xref{Text Properties}. Use @code{equal-including-properties} to also -compare text properties. For technical reasons, a unibyte string and -a multibyte string are @code{equal} if and only if they contain the -same sequence of character codes and all these codes are either in the -range 0 through 127 (@acronym{ASCII}) or 160 through 255 -(@code{eight-bit-graphic}). (@pxref{Text Representations}). - -@example -@group -(equal "asdf" "ASDF") - @result{} nil -@end group -@end example - -However, two distinct buffers are never considered @code{equal}, even if -their textual contents are the same. -@end defun - - The test for equality is implemented recursively; for example, given -two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})} -returns @code{t} if and only if both the expressions below return -@code{t}: - -@example -(equal (car @var{x}) (car @var{y})) -(equal (cdr @var{x}) (cdr @var{y})) -@end example - -Because of this recursive method, circular lists may therefore cause -infinite recursion (leading to an error). - -@defun equal-including-properties object1 object2 -This function behaves like @code{equal} in all cases but also requires -that for two strings to be equal, they have the same text properties. - -@example -@group -(equal "asdf" (propertize "asdf" '(asdf t))) - @result{} t -@end group -@group -(equal-including-properties "asdf" - (propertize "asdf" '(asdf t))) - @result{} nil -@end group -@end example -@end defun diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi deleted file mode 100644 index 3b63e08676c..00000000000 --- a/doc/lispref/os.texi +++ /dev/null @@ -1,2727 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node System Interface -@chapter Operating System Interface - - This chapter is about starting and getting out of Emacs, access to -values in the operating system environment, and terminal input, output. - - @xref{Building Emacs}, for related information. @xref{Display}, for -additional operating system status information pertaining to the -terminal and the screen. - -@menu -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with X Session Management. -* Desktop Notifications:: Desktop notifications. -* File Notifications:: File notifications. -* Dynamic Libraries:: On-demand loading of support libraries. -@end menu - -@node Starting Up -@section Starting Up Emacs - - This section describes what Emacs does when it is started, and how you -can customize these actions. - -@menu -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. -@end menu - -@node Startup Summary -@subsection Summary: Sequence of Actions at Startup -@cindex initialization of Emacs -@cindex startup of Emacs -@cindex @file{startup.el} - - When Emacs is started up, it performs the following operations -(see @code{normal-top-level} in @file{startup.el}): - -@enumerate -@item -It adds subdirectories to @code{load-path}, by running the file named -@file{subdirs.el} in each directory in the list. Normally, this file -adds the directory's subdirectories to the list, and those are scanned -in their turn. The files @file{subdirs.el} are normally generated -automatically when Emacs is installed. - -@item -It loads any @file{leim-list.el} that it finds in the @code{load-path} -directories. This file is intended for registering input methods. -The search is only for any personal @file{leim-list.el} files that you -may have created; it skips the directories containing the standard Emacs -libraries (these should contain only a single @file{leim-list.el} file, -which is compiled into the Emacs executable). - -@vindex before-init-time -@item -It sets the variable @code{before-init-time} to the value of -@code{current-time} (@pxref{Time of Day}). It also sets -@code{after-init-time} to @code{nil}, which signals to Lisp programs -that Emacs is being initialized. - -@c set-locale-environment -@item -It sets the language environment and the terminal coding system, -if requested by environment variables such as @env{LANG}. - -@item -It does some basic parsing of the command-line arguments. - -@vindex initial-window-system@r{, and startup} -@vindex window-system-initialization-alist -@item -If not running in batch mode, it initializes the window system that -the variable @code{initial-window-system} specifies (@pxref{Window -Systems, initial-window-system}). The initialization function for -each supported window system is specified by -@code{window-system-initialization-alist}. If the value -of @code{initial-window-system} is @var{windowsystem}, then the -appropriate initialization function is defined in the file -@file{term/@var{windowsystem}-win.el}. This file should have been -compiled into the Emacs executable when it was built. - -@item -It runs the normal hook @code{before-init-hook}. - -@item -If appropriate, it creates a graphical frame. This is not done if the -options @samp{--batch} or @samp{--daemon} were specified. - -@item -It initializes the initial frame's faces, and sets up the menu bar -and tool bar if needed. If graphical frames are supported, it sets up -the tool bar even if the current frame is not a graphical one, since a -graphical frame may be created later on. - -@item -It use @code{custom-reevaluate-setting} to re-initialize the members -of the list @code{custom-delayed-init-variables}. These are any -pre-loaded user options whose default value depends on the run-time, -rather than build-time, context. -@xref{Building Emacs, custom-initialize-delay}. - -@c @item -@c It registers the colors available for tty frames. - -@item -It loads the library @file{site-start}, if it exists. This is not -done if the options @samp{-Q} or @samp{--no-site-file} were specified. -@cindex @file{site-start.el} - -@item -It loads your init file (@pxref{Init File}). This is not done if the -options @samp{-q}, @samp{-Q}, or @samp{--batch} were specified. If -the @samp{-u} option was specified, Emacs looks for the init file in -that user's home directory instead. - -@item -It loads the library @file{default}, if it exists. This is not done -if @code{inhibit-default-init} is non-@code{nil}, nor if the options -@samp{-q}, @samp{-Q}, or @samp{--batch} were specified. -@cindex @file{default.el} - -@item -It loads your abbrevs from the file specified by -@code{abbrev-file-name}, if that file exists and can be read -(@pxref{Abbrev Files, abbrev-file-name}). This is not done if the -option @samp{--batch} was specified. - -@item -If @code{package-enable-at-startup} is non-@code{nil}, it calls the -function @code{package-initialize} to activate any optional Emacs Lisp -package that has been installed. @xref{Packaging Basics}. - -@vindex after-init-time -@item -It sets the variable @code{after-init-time} to the value of -@code{current-time}. This variable was set to @code{nil} earlier; -setting it to the current time signals that the initialization phase -is over, and, together with @code{before-init-time}, provides the -measurement of how long it took. - -@item -It runs the normal hook @code{after-init-hook}. - -@item -If the buffer @file{*scratch*} exists and is still in Fundamental mode -(as it should be by default), it sets its major mode according to -@code{initial-major-mode}. - -@item -If started on a text terminal, it loads the terminal-specific -Lisp library (@pxref{Terminal-Specific}), and runs the hook -@code{tty-setup-hook}. This is not done -in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}. - -@c Now command-line calls command-line-1. - -@item -It displays the initial echo area message, unless you have suppressed -that with @code{inhibit-startup-echo-area-message}. - -@item -It processes any command-line options that were not handled earlier. - -@c This next one is back in command-line, but the remaining bits of -@c command-line-1 are not done if noninteractive. -@item -It now exits if the option @code{--batch} was specified. - -@item -If @code{initial-buffer-choice} is a string, it visits the file (or -directory) with that name. If it is a function, it calls the function -with no arguments and selects the buffer that it returns. -@ignore -@c I do not think this should be mentioned. AFAICS it is just a dodge -@c around inhibit-startup-screen not being settable on a site-wide basis. -If it is @code{t}, it selects the @file{*scratch*} buffer. -@end ignore -If the @file{*scratch*} buffer exists and is empty, it inserts -@code{initial-scratch-message} into that buffer. - -@c To make things nice and confusing, the next three items can be -@c called from two places. If displaying a startup screen, they are -@c called in command-line-1 before the startup screen is shown. -@c inhibit-startup-hooks is then set and window-setup-hook set to nil. -@c If not displaying a startup screen, they are are called in -@c normal-top-level. -@c FIXME? So it seems they can be called before or after the -@c daemon/session restore step? - -@item -It runs @code{emacs-startup-hook}. - -@item -It calls @code{frame-notice-user-settings}, which modifies the -parameters of the selected frame according to whatever the init files -specify. - -@item -It runs @code{window-setup-hook}. The only difference between this -hook and @code{emacs-startup-hook} is that this one runs after the -previously mentioned modifications to the frame parameters. - -@item -@cindex startup screen -It displays the @dfn{startup screen}, which is a special buffer that -contains information about copyleft and basic Emacs usage. This is -not done if @code{inhibit-startup-screen} or @code{initial-buffer-choice} -are non-@code{nil}, or if the @samp{--no-splash} or @samp{-Q} command-line -options were specified. - -@c End of command-line-1. - -@c Back to command-line from command-line-1. - -@c This is the point at which we actually exit in batch mode, but the -@c last few bits of command-line-1 are not done in batch mode. - -@item -If the option @code{--daemon} was specified, it calls -@code{server-start} and detaches from the controlling terminal. -@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. - -@item -If started by the X session manager, it calls -@code{emacs-session-restore} passing it as argument the ID of the -previous session. @xref{Session Management}. - -@c End of command-line. - -@c Back to normal-top-level from command-line. - -@end enumerate - -@noindent -The following options affect some aspects of the startup sequence. - -@defopt inhibit-startup-screen -This variable, if non-@code{nil}, inhibits the startup screen. In -that case, Emacs typically displays the @file{*scratch*} buffer; but -see @code{initial-buffer-choice}, below. - -Do not set this variable in the init file of a new user, or in a way -that affects more than one user, as that would prevent new users from -receiving information about copyleft and basic Emacs usage. - -@vindex inhibit-startup-message -@vindex inhibit-splash-screen -@code{inhibit-startup-message} and @code{inhibit-splash-screen} are -aliases for this variable. -@end defopt - -@defopt initial-buffer-choice -If non-@code{nil}, this variable is a string that specifies a file or -directory for Emacs to display after starting up, instead of the -startup screen. -If its value is a function, Emacs calls that function which must -return a buffer which is then displayed. -If its value is @code{t}, Emacs displays the @file{*scratch*} buffer. -@end defopt - -@defopt inhibit-startup-echo-area-message -This variable controls the display of the startup echo area message. -You can suppress the startup echo area message by adding text with this -form to your init file: - -@example -(setq inhibit-startup-echo-area-message - "@var{your-login-name}") -@end example - -Emacs explicitly checks for an expression as shown above in your init -file; your login name must appear in the expression as a Lisp string -constant. You can also use the Customize interface. Other methods of -setting @code{inhibit-startup-echo-area-message} to the same value do -not inhibit the startup message. This way, you can easily inhibit the -message for yourself if you wish, but thoughtless copying of your init -file will not inhibit the message for someone else. -@end defopt - -@defopt initial-scratch-message -This variable, if non-@code{nil}, should be a string, which is -inserted into the @file{*scratch*} buffer when Emacs starts up. If it -is @code{nil}, the @file{*scratch*} buffer is empty. -@end defopt - -@noindent -The following command-line options affect some aspects of the startup -sequence. @xref{Initial Options,,, emacs, The GNU Emacs Manual}. - -@table @code -@item --no-splash -Do not display a splash screen. - -@item --batch -Run without an interactive terminal. @xref{Batch Mode}. - -@item --daemon -Do not initialize any display; just start a server in the background. - -@item --no-init-file -@itemx -q -Do not load either the init file, or the @file{default} library. - -@item --no-site-file -Do not load the @file{site-start} library. - -@item --quick -@itemx -Q -Equivalent to @samp{-q --no-site-file --no-splash}. -@c and --no-site-lisp, but let's not mention that here. -@end table - - -@node Init File -@subsection The Init File -@cindex init file -@cindex @file{.emacs} -@cindex @file{init.el} - - When you start Emacs, it normally attempts to load your @dfn{init -file}. This is either a file named @file{.emacs} or @file{.emacs.el} -in your home directory, or a file named @file{init.el} in a -subdirectory named @file{.emacs.d} in your home directory. -@ignore -Whichever place you use, you can also compile the file (@pxref{Byte -Compilation}); then the actual file loaded will be @file{.emacs.elc} -or @file{init.elc}. -@end ignore - - The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u} -control whether and where to find the init file; @samp{-q} (and the -stronger @samp{-Q}) says not to load an init file, while @samp{-u -@var{user}} says to load @var{user}'s init file instead of yours. -@xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither -option is specified, Emacs uses the @env{LOGNAME} environment -variable, or the @env{USER} (most systems) or @env{USERNAME} (MS -systems) variable, to find your home directory and thus your init -file; this way, even if you have su'd, Emacs still loads your own init -file. If those environment variables are absent, though, Emacs uses -your user-id to find your home directory. - -@cindex default init file - An Emacs installation may have a @dfn{default init file}, which is a -Lisp library named @file{default.el}. Emacs finds this file through -the standard search path for libraries (@pxref{How Programs Do -Loading}). The Emacs distribution does not come with this file; it is -intended for local customizations. If the default init file exists, -it is loaded whenever you start Emacs. But your own personal init -file, if any, is loaded first; if it sets @code{inhibit-default-init} -to a non-@code{nil} value, then Emacs does not subsequently load the -@file{default.el} file. In batch mode, or if you specify @samp{-q} -(or @samp{-Q}), Emacs loads neither your personal init file nor -the default init file. - - Another file for site-customization is @file{site-start.el}. Emacs -loads this @emph{before} the user's init file. You can inhibit the -loading of this file with the option @samp{--no-site-file}. - -@defopt site-run-file -This variable specifies the site-customization file to load before the -user's init file. Its normal value is @code{"site-start"}. The only -way you can change it with real effect is to do so before dumping -Emacs. -@c So why even mention it here. I imagine it is almost never changed. -@end defopt - - @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for -examples of how to make various commonly desired customizations in your -@file{.emacs} file. - -@defopt inhibit-default-init -If this variable is non-@code{nil}, it prevents Emacs from loading the -default initialization library file. The default value is @code{nil}. -@end defopt - -@defvar before-init-hook -This normal hook is run, once, just before loading all the init files -(@file{site-start.el}, your init file, and @file{default.el}). -(The only way to change it with real effect is before dumping Emacs.) -@end defvar - -@defvar after-init-hook -This normal hook is run, once, just after loading all the init files -(@file{site-start.el}, your init file, and @file{default.el}), -before loading the terminal-specific library (if started on a text -terminal) and processing the command-line action arguments. -@end defvar - -@defvar emacs-startup-hook -This normal hook is run, once, just after handling the command line -arguments. In batch mode, Emacs does not run this hook. -@end defvar - -@defvar window-setup-hook -This normal hook is very similar to @code{emacs-startup-hook}. -The only difference is that it runs slightly later, after setting -of the frame parameters. @xref{Startup Summary, window-setup-hook}. -@end defvar - -@defvar user-init-file -This variable holds the absolute file name of the user's init file. If the -actual init file loaded is a compiled file, such as @file{.emacs.elc}, -the value refers to the corresponding source file. -@end defvar - -@defvar user-emacs-directory -This variable holds the name of the @file{.emacs.d} directory. It is -@file{~/.emacs.d} on all platforms but MS-DOS. -@end defvar - -@node Terminal-Specific -@subsection Terminal-Specific Initialization -@cindex terminal-specific initialization - - Each terminal type can have its own Lisp library that Emacs loads when -run on that type of terminal. The library's name is constructed by -concatenating the value of the variable @code{term-file-prefix} and the -terminal type (specified by the environment variable @env{TERM}). -Normally, @code{term-file-prefix} has the value -@code{"term/"}; changing this is not recommended. Emacs finds the file -in the normal manner, by searching the @code{load-path} directories, and -trying the @samp{.elc} and @samp{.el} suffixes. - -@cindex Termcap - The usual role of a terminal-specific library is to enable special -keys to send sequences that Emacs can recognize. It may also need to -set or add to @code{input-decode-map} if the Termcap or Terminfo entry -does not specify all the terminal's function keys. @xref{Terminal Input}. - - When the name of the terminal type contains a hyphen or underscore, -and no library is found whose name is identical to the terminal's -name, Emacs strips from the terminal's name the last hyphen or -underscore and everything that follows -it, and tries again. This process is repeated until Emacs finds a -matching library, or until there are no more hyphens or underscores in the name -(i.e., there is no terminal-specific library). For example, if the -terminal name is @samp{xterm-256color} and there is no -@file{term/xterm-256color.el} library, Emacs tries to load -@file{term/xterm.el}. If necessary, the terminal library can evaluate -@code{(getenv "TERM")} to find the full name of the terminal type. - - Your init file can prevent the loading of the terminal-specific -library by setting the variable @code{term-file-prefix} to @code{nil}. - - You can also arrange to override some of the actions of the -terminal-specific library by using @code{tty-setup-hook}. This is -a normal hook that Emacs runs after initializing a new text terminal. -You could use this hook to define initializations for terminals that do not -have their own libraries. @xref{Hooks}. - -@defvar term-file-prefix -@cindex @env{TERM} environment variable -If the value of this variable is non-@code{nil}, Emacs loads a -terminal-specific initialization file as follows: - -@example -(load (concat term-file-prefix (getenv "TERM"))) -@end example - -@noindent -You may set the @code{term-file-prefix} variable to @code{nil} in your -init file if you do not wish to load the -terminal-initialization file. - -On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}. -@end defvar - -@defvar tty-setup-hook -This variable is a normal hook that Emacs runs after initializing a -new text terminal. (This applies when Emacs starts up in non-windowed -mode, and when making a tty @command{emacsclient} connection.) The -hook runs after loading your init file (if applicable) and the -terminal-specific Lisp file, so you can use it to adjust the -definitions made by that file. - -For a related feature, @pxref{Init File, window-setup-hook}. -@end defvar - -@node Command-Line Arguments -@subsection Command-Line Arguments -@cindex command-line arguments - - You can use command-line arguments to request various actions when -you start Emacs. Note that the recommended way of using Emacs is to -start it just once, after logging in, and then do all editing in the same -Emacs session (@pxref{Entering Emacs,,, emacs, The GNU Emacs Manual}). -For this reason, you might not use command-line arguments very often; -nonetheless, they can be useful when invoking Emacs from session -scripts or debugging Emacs. This section describes how Emacs -processes command-line arguments. - -@defun command-line -This function parses the command line that Emacs was called with, -processes it, and (amongst other things) loads the user's init file and -displays the startup messages. -@end defun - -@defvar command-line-processed -The value of this variable is @code{t} once the command line has been -processed. - -If you redump Emacs by calling @code{dump-emacs} (@pxref{Building -Emacs}), you may wish to set this variable to @code{nil} first in -order to cause the new dumped Emacs to process its new command-line -arguments. -@end defvar - -@defvar command-switch-alist -@cindex switches on command line -@cindex options on command line -@cindex command-line options -This variable is an alist of user-defined command-line options and -associated handler functions. By default it is empty, but you can -add elements if you wish. - -A @dfn{command-line option} is an argument on the command line, which -has the form: - -@example --@var{option} -@end example - -The elements of the @code{command-switch-alist} look like this: - -@example -(@var{option} . @var{handler-function}) -@end example - -The @sc{car}, @var{option}, is a string, the name of a command-line -option (not including the initial hyphen). The @var{handler-function} -is called to handle @var{option}, and receives the option name as its -sole argument. - -In some cases, the option is followed in the command line by an -argument. In these cases, the @var{handler-function} can find all the -remaining command-line arguments in the variable -@code{command-line-args-left} (see below). (The entire list of -command-line arguments is in @code{command-line-args}.) - -The command-line arguments are parsed by the @code{command-line-1} -function in the @file{startup.el} file. See also @ref{Emacs -Invocation, , Command Line Arguments for Emacs Invocation, emacs, The -GNU Emacs Manual}. -@end defvar - -@defvar command-line-args -The value of this variable is the list of command-line arguments passed -to Emacs. -@end defvar - -@defvar command-line-args-left -@vindex argv -The value of this variable is the list of command-line arguments that -have not yet been processed. -@c Don't mention this, since it is a "bad name for a dynamically bound variable" -@c @code{argv} is an alias for this. -@end defvar - -@defvar command-line-functions -This variable's value is a list of functions for handling an -unrecognized command-line argument. Each time the next argument to be -processed has no special meaning, the functions in this list are called, -in order of appearance, until one of them returns a non-@code{nil} -value. - -These functions are called with no arguments. They can access the -command-line argument under consideration through the variable -@code{argi}, which is bound temporarily at this point. The remaining -arguments (not including the current one) are in the variable -@code{command-line-args-left}. - -When a function recognizes and processes the argument in @code{argi}, it -should return a non-@code{nil} value to say it has dealt with that -argument. If it has also dealt with some of the following arguments, it -can indicate that by deleting them from @code{command-line-args-left}. - -If all of these functions return @code{nil}, then the argument is treated -as a file name to visit. -@end defvar - -@node Getting Out -@section Getting Out of Emacs -@cindex exiting Emacs - - There are two ways to get out of Emacs: you can kill the Emacs job, -which exits permanently, or you can suspend it, which permits you to -reenter the Emacs process later. (In a graphical environment, you can -of course simply switch to another application without doing anything -special to Emacs, then switch back to Emacs when you want.) - -@menu -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. -@end menu - -@node Killing Emacs -@subsection Killing Emacs -@cindex killing Emacs - - Killing Emacs means ending the execution of the Emacs process. -If you started Emacs from a terminal, the parent process normally -resumes control. The low-level primitive for killing Emacs is -@code{kill-emacs}. - -@deffn Command kill-emacs &optional exit-data -This command calls the hook @code{kill-emacs-hook}, then exits the -Emacs process and kills it. - -If @var{exit-data} is an integer, that is used as the exit status of -the Emacs process. (This is useful primarily in batch operation; see -@ref{Batch Mode}.) - -If @var{exit-data} is a string, its contents are stuffed into the -terminal input buffer so that the shell (or whatever program next reads -input) can read them. -@end deffn - -@cindex SIGTERM -@cindex SIGHUP -@cindex SIGINT -@cindex operating system signal - The @code{kill-emacs} function is normally called via the -higher-level command @kbd{C-x C-c} -(@code{save-buffers-kill-terminal}). @xref{Exiting,,, emacs, The GNU -Emacs Manual}. It is also called automatically if Emacs receives a -@code{SIGTERM} or @code{SIGHUP} operating system signal (e.g., when the -controlling terminal is disconnected), or if it receives a -@code{SIGINT} signal while running in batch mode (@pxref{Batch Mode}). - -@defvar kill-emacs-hook -This normal hook is run by @code{kill-emacs}, before it kills Emacs. - -Because @code{kill-emacs} can be called in situations where user -interaction is impossible (e.g., when the terminal is disconnected), -functions on this hook should not attempt to interact with the user. -If you want to interact with the user when Emacs is shutting down, use -@code{kill-emacs-query-functions}, described below. -@end defvar - - When Emacs is killed, all the information in the Emacs process, -aside from files that have been saved, is lost. Because killing Emacs -inadvertently can lose a lot of work, the -@code{save-buffers-kill-terminal} command queries for confirmation if -you have buffers that need saving or subprocesses that are running. -It also runs the abnormal hook @code{kill-emacs-query-functions}: - -@defvar kill-emacs-query-functions -When @code{save-buffers-kill-terminal} is killing Emacs, it calls the -functions in this hook, after asking the standard questions and before -calling @code{kill-emacs}. The functions are called in order of -appearance, with no arguments. Each function can ask for additional -confirmation from the user. If any of them returns @code{nil}, -@code{save-buffers-kill-emacs} does not kill Emacs, and does not run -the remaining functions in this hook. Calling @code{kill-emacs} -directly does not run this hook. -@end defvar - -@node Suspending Emacs -@subsection Suspending Emacs -@cindex suspending Emacs - - On text terminals, it is possible to @dfn{suspend Emacs}, which -means stopping Emacs temporarily and returning control to its superior -process, which is usually the shell. This allows you to resume -editing later in the same Emacs process, with the same buffers, the -same kill ring, the same undo history, and so on. To resume Emacs, -use the appropriate command in the parent shell---most likely -@code{fg}. - -@cindex controlling terminal - Suspending works only on a terminal device from which the Emacs -session was started. We call that device the @dfn{controlling -terminal} of the session. Suspending is not allowed if the -controlling terminal is a graphical terminal. Suspending is usually -not relevant in graphical environments, since you can simply switch to -another application without doing anything special to Emacs. - -@c FIXME? Are there any systems Emacs still supports that do not -@c have SIGTSTP? -@cindex SIGTSTP - Some operating systems (those without @code{SIGTSTP}, or MS-DOS) do -not support suspension of jobs; on these systems, ``suspension'' -actually creates a new shell temporarily as a subprocess of Emacs. -Then you would exit the shell to return to Emacs. - -@deffn Command suspend-emacs &optional string -This function stops Emacs and returns control to the superior process. -If and when the superior process resumes Emacs, @code{suspend-emacs} -returns @code{nil} to its caller in Lisp. - -This function works only on the controlling terminal of the Emacs -session; to relinquish control of other tty devices, use -@code{suspend-tty} (see below). If the Emacs session uses more than -one terminal, you must delete the frames on all the other terminals -before suspending Emacs, or this function signals an error. -@xref{Multiple Terminals}. - -If @var{string} is non-@code{nil}, its characters are sent to Emacs's -superior shell, to be read as terminal input. -@c FIXME? It seems to me that shell does echo STRING. -The characters in @var{string} are not echoed by the superior shell; -only the results appear. - -Before suspending, @code{suspend-emacs} runs the normal hook -@code{suspend-hook}. After the user resumes Emacs, -@code{suspend-emacs} runs the normal hook @code{suspend-resume-hook}. -@xref{Hooks}. - -The next redisplay after resumption will redraw the entire screen, -unless the variable @code{no-redraw-on-reenter} is non-@code{nil}. -@xref{Refresh Screen}. - -Here is an example of how you could use these hooks: - -@smallexample -@group -(add-hook 'suspend-hook - (lambda () (or (y-or-n-p "Really suspend? ") - (error "Suspend canceled")))) -@end group -(add-hook 'suspend-resume-hook (lambda () (message "Resumed!") - (sit-for 2))) -@end smallexample -@c The sit-for prevents the @code{nil} that suspend-emacs returns -@c hiding the message. - -Here is what you would see upon evaluating @code{(suspend-emacs "pwd")}: - -@smallexample -@group ----------- Buffer: Minibuffer ---------- -Really suspend? @kbd{y} ----------- Buffer: Minibuffer ---------- -@end group - -@group ----------- Parent Shell ---------- -bash$ /home/username -bash$ fg -@end group - -@group ----------- Echo Area ---------- -Resumed! -@end group -@end smallexample - -@c FIXME? AFAICS, it is echoed. -Note that @samp{pwd} is not echoed after Emacs is suspended. But it -is read and executed by the shell. -@end deffn - -@defvar suspend-hook -This variable is a normal hook that Emacs runs before suspending. -@end defvar - -@defvar suspend-resume-hook -This variable is a normal hook that Emacs runs on resuming -after a suspension. -@end defvar - -@defun suspend-tty &optional tty -If @var{tty} specifies a terminal device used by Emacs, this function -relinquishes the device and restores it to its prior state. Frames -that used the device continue to exist, but are not updated and Emacs -doesn't read input from them. @var{tty} can be a terminal object, a -frame (meaning the terminal for that frame), or @code{nil} (meaning -the terminal for the selected frame). @xref{Multiple Terminals}. - -If @var{tty} is already suspended, this function does nothing. - -@vindex suspend-tty-functions -This function runs the hook @code{suspend-tty-functions}, passing the -terminal object as an argument to each function. -@end defun - -@defun resume-tty &optional tty -This function resumes the previously suspended terminal device -@var{tty}; where @var{tty} has the same possible values as it does -for @code{suspend-tty}. - -@vindex resume-tty-functions -This function reopens the terminal device, re-initializes it, and -redraws it with that terminal's selected frame. It then runs the -hook @code{resume-tty-functions}, passing the terminal object as an -argument to each function. - -If the same device is already used by another Emacs terminal, this -function signals an error. If @var{tty} is not suspended, this -function does nothing. -@end defun - -@defun controlling-tty-p &optional tty -This function returns non-@code{nil} if @var{tty} is the -controlling terminal of the Emacs session; @var{tty} can be a -terminal object, a frame (meaning the terminal for that frame), or -@code{nil} (meaning the terminal for the selected frame). -@end defun - -@deffn Command suspend-frame -This command @dfn{suspends} a frame. For GUI frames, it calls -@code{iconify-frame} (@pxref{Visibility of Frames}); for frames on -text terminals, it calls either @code{suspend-emacs} or -@code{suspend-tty}, depending on whether the frame is displayed on the -controlling terminal device or not. -@end deffn - -@node System Environment -@section Operating System Environment -@cindex operating system environment - - Emacs provides access to variables in the operating system environment -through various functions. These variables include the name of the -system, the user's @acronym{UID}, and so on. - -@defvar system-configuration -This variable holds the standard GNU configuration name for the -hardware/software configuration of your system, as a string. For -example, a typical value for a 64-bit GNU/Linux system is -@samp{"x86_64-unknown-linux-gnu"}. -@end defvar - -@cindex system type and name -@defvar system-type -The value of this variable is a symbol indicating the type of operating -system Emacs is running on. The possible values are: - -@table @code -@item aix -IBM's AIX. - -@item berkeley-unix -Berkeley BSD and its variants. - -@item cygwin -Cygwin, a Posix layer on top of MS-Windows. - -@item darwin -Darwin (Mac OS X). - -@item gnu -The GNU system (using the GNU kernel, which consists of the HURD and Mach). - -@item gnu/linux -A GNU/Linux system---that is, a variant GNU system, using the Linux -kernel. (These systems are the ones people often call ``Linux'', but -actually Linux is just the kernel, not the whole system.) - -@item gnu/kfreebsd -A GNU (glibc-based) system with a FreeBSD kernel. - -@item hpux -Hewlett-Packard HPUX operating system. - -@item irix -Silicon Graphics Irix system. - -@item ms-dos -Microsoft's DOS@. Emacs compiled with DJGPP for MS-DOS binds -@code{system-type} to @code{ms-dos} even when you run it on MS-Windows. - -@item usg-unix-v -AT&T Unix System V. - -@item windows-nt -Microsoft Windows NT, 9X and later. The value of @code{system-type} -is always @code{windows-nt}, e.g., even on Windows 7. - -@end table - -We do not wish to add new symbols to make finer distinctions unless it -is absolutely necessary! In fact, we hope to eliminate some of these -alternatives in the future. If you need to make a finer distinction -than @code{system-type} allows for, you can test -@code{system-configuration}, e.g., against a regexp. -@end defvar - -@defun system-name -This function returns the name of the machine you are running on, as a -string. -@end defun - - The symbol @code{system-name} is a variable as well as a function. In -fact, the function returns whatever value the variable -@code{system-name} currently holds. Thus, you can set the variable -@code{system-name} in case Emacs is confused about the name of your -system. The variable is also useful for constructing frame titles -(@pxref{Frame Titles}). - -@c FIXME seems like this section is not the best place for this option? -@defopt mail-host-address -If this variable is non-@code{nil}, it is used instead of -@code{system-name} for purposes of generating email addresses. For -example, it is used when constructing the default value of -@code{user-mail-address}. @xref{User Identification}. (Since this is -done when Emacs starts up, the value actually used is the one saved when -Emacs was dumped. @xref{Building Emacs}.) -@c FIXME sounds like should probably give this a :set-after and some -@c custom-initialize-delay voodoo. -@end defopt - -@deffn Command getenv var &optional frame -@cindex environment variable access -This function returns the value of the environment variable @var{var}, -as a string. @var{var} should be a string. If @var{var} is undefined -in the environment, @code{getenv} returns @code{nil}. It returns -@samp{""} if @var{var} is set but null. Within Emacs, a list of environment -variables and their values is kept in the variable @code{process-environment}. - -@example -@group -(getenv "USER") - @result{} "lewis" -@end group -@end example - -The shell command @code{printenv} prints all or part of the environment: - -@example -@group -bash$ printenv -PATH=/usr/local/bin:/usr/bin:/bin -USER=lewis -@end group -@group -TERM=xterm -SHELL=/bin/bash -HOME=/home/lewis -@end group -@dots{} -@end example -@end deffn - -@deffn Command setenv variable &optional value substitute -This command sets the value of the environment variable named -@var{variable} to @var{value}. @var{variable} should be a string. -Internally, Emacs Lisp can handle any string. However, normally -@var{variable} should be a valid shell identifier, that is, a sequence -of letters, digits and underscores, starting with a letter or -underscore. Otherwise, errors may occur if subprocesses of Emacs try -to access the value of @var{variable}. If @var{value} is omitted or -@code{nil} (or, interactively, with a prefix argument), @code{setenv} -removes @var{variable} from the environment. Otherwise, @var{value} -should be a string. - -@c FIXME: Document `substitute-env-vars'? --xfq -If the optional argument @var{substitute} is non-@code{nil}, Emacs -calls the function @code{substitute-env-vars} to expand any -environment variables in @var{value}. - -@code{setenv} works by modifying @code{process-environment}; binding -that variable with @code{let} is also reasonable practice. - -@code{setenv} returns the new value of @var{variable}, or @code{nil} -if it removed @var{variable} from the environment. -@end deffn - -@defvar process-environment -This variable is a list of strings, each describing one environment -variable. The functions @code{getenv} and @code{setenv} work by means -of this variable. - -@smallexample -@group -process-environment -@result{} ("PATH=/usr/local/bin:/usr/bin:/bin" - "USER=lewis" -@end group -@group - "TERM=xterm" - "SHELL=/bin/bash" - "HOME=/home/lewis" - @dots{}) -@end group -@end smallexample - -If @code{process-environment} contains ``duplicate'' elements that -specify the same environment variable, the first of these elements -specifies the variable, and the other ``duplicates'' are ignored. -@end defvar - -@defvar initial-environment -This variable holds the list of environment variables Emacs inherited -from its parent process when Emacs started. -@end defvar - -@defvar path-separator -This variable holds a string that says which character separates -directories in a search path (as found in an environment variable). Its -value is @code{":"} for Unix and GNU systems, and @code{";"} for MS systems. -@end defvar - -@defun parse-colon-path path -This function takes a search path string such as the value of -the @env{PATH} environment variable, and splits it at the separators, -returning a list of directory names. @code{nil} in this list means -the current directory. Although the function's name says -``colon'', it actually uses the value of @code{path-separator}. - -@example -(parse-colon-path ":/foo:/bar") - @result{} (nil "/foo/" "/bar/") -@end example -@end defun - -@defvar invocation-name -This variable holds the program name under which Emacs was invoked. The -value is a string, and does not include a directory name. -@end defvar - -@defvar invocation-directory -This variable holds the directory from which the Emacs executable was -invoked, or @code{nil} if that directory cannot be determined. -@end defvar - -@defvar installation-directory -If non-@code{nil}, this is a directory within which to look for the -@file{lib-src} and @file{etc} subdirectories. In an installed Emacs, -it is normally @code{nil}. It is non-@code{nil} -when Emacs can't find those directories in their standard installed -locations, but can find them in a directory related somehow to the one -containing the Emacs executable (i.e., @code{invocation-directory}). -@end defvar - -@defun load-average &optional use-float -This function returns the current 1-minute, 5-minute, and 15-minute -system load averages, in a list. The load average indicates the -number of processes trying to run on the system. - -By default, the values are integers that are 100 times the system load -averages, but if @var{use-float} is non-@code{nil}, then they are -returned as floating-point numbers without multiplying by 100. - -If it is impossible to obtain the load average, this function signals -an error. On some platforms, access to load averages requires -installing Emacs as setuid or setgid so that it can read kernel -information, and that usually isn't advisable. -@c FIXME which platforms are these? Are they still relevant? - -If the 1-minute load average is available, but the 5- or 15-minute -averages are not, this function returns a shortened list containing -the available averages. - -@example -@group -(load-average) - @result{} (169 48 36) -@end group -@group -(load-average t) - @result{} (1.69 0.48 0.36) -@end group -@end example - -The shell command @code{uptime} returns similar information. -@end defun - -@defun emacs-pid -This function returns the process @acronym{ID} of the Emacs process, -as an integer. -@end defun - -@defvar tty-erase-char -This variable holds the erase character that was selected -in the system's terminal driver, before Emacs was started. -@c FIXME? Seems untrue since 23.1. For me, it is 0. -@c The value is @code{nil} if Emacs is running under a window system. -@end defvar - -@node User Identification -@section User Identification -@cindex user identification - -@defvar init-file-user -This variable says which user's init files should be used by -Emacs---or @code{nil} if none. @code{""} stands for the user who -originally logged in. The value reflects command-line options such as -@samp{-q} or @samp{-u @var{user}}. - -Lisp packages that load files of customizations, or any other sort of -user profile, should obey this variable in deciding where to find it. -They should load the profile of the user name found in this variable. -If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}, -@samp{-Q}, or @samp{-batch} option was used, then Lisp packages should -not load any customization files or user profile. -@end defvar - -@defopt user-mail-address -This holds the nominal email address of the user who is using Emacs. -Emacs normally sets this variable to a default value after reading your -init files, but not if you have already set it. So you can set the -variable to some other value in your init file if you do not -want to use the default value. -@end defopt - -@defun user-login-name &optional uid -This function returns the name under which the user is logged in. -It uses the environment variables @env{LOGNAME} or @env{USER} if -either is set. Otherwise, the value is based on the effective -@acronym{UID}, not the real @acronym{UID}. - -If you specify @var{uid} (a number), the result is the user name that -corresponds to @var{uid}, or @code{nil} if there is no such user. -@end defun - -@defun user-real-login-name -This function returns the user name corresponding to Emacs's real -@acronym{UID}. This ignores the effective @acronym{UID}, and the -environment variables @env{LOGNAME} and @env{USER}. -@end defun - -@defun user-full-name &optional uid -This function returns the full name of the logged-in user---or the value -of the environment variable @env{NAME}, if that is set. - -If the Emacs process's user-id does not correspond to any known user (and -provided @code{NAME} is not set), the result is @code{"unknown"}. - -If @var{uid} is non-@code{nil}, then it should be a number (a user-id) -or a string (a login name). Then @code{user-full-name} returns the full -name corresponding to that user-id or login name. If you specify a -user-id or login name that isn't defined, it returns @code{nil}. -@end defun - -@vindex user-full-name -@vindex user-real-login-name -@vindex user-login-name - The symbols @code{user-login-name}, @code{user-real-login-name} and -@code{user-full-name} are variables as well as functions. The functions -return the same values that the variables hold. These variables allow -you to ``fake out'' Emacs by telling the functions what to return. The -variables are also useful for constructing frame titles (@pxref{Frame -Titles}). - -@cindex UID -@defun user-real-uid -This function returns the real @acronym{UID} of the user. -The value may be floating point, in the (unlikely) event that -the UID is too large to fit in a Lisp integer. -@end defun - -@defun user-uid -This function returns the effective @acronym{UID} of the user. -The value may be floating point. -@end defun - -@cindex GID -@defun group-gid -This function returns the effective @acronym{GID} of the Emacs process. -The value may be floating point. -@end defun - -@defun group-real-gid -This function returns the real @acronym{GID} of the Emacs process. -The value may be floating point. -@end defun - -@defun system-users -This function returns a list of strings, listing the user names on the -system. If Emacs cannot retrieve this information, the return value -is a list containing just the value of @code{user-real-login-name}. -@end defun - -@cindex user groups -@defun system-groups -This function returns a list of strings, listing the names of user -groups on the system. If Emacs cannot retrieve this information, the -return value is @code{nil}. -@end defun - - -@node Time of Day -@section Time of Day - - This section explains how to determine the current time and time -zone. - -@cindex epoch - Most of these functions represent time as a list of either four -integers, @code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})}, or of three -integers, @code{(@var{sec-high} @var{sec-low} @var{microsec})}, or of -two integers, @code{(@var{sec-high} @var{sec-low})}. The integers -@var{sec-high} and @var{sec-low} give the high and low bits of an -integer number of seconds. This integer, -@ifnottex -@var{high} * 2**16 + @var{low}, -@end ifnottex -@tex -$high*2^{16}+low$, -@end tex -is the number of seconds from the @dfn{epoch} (0:00 January 1, 1970 -UTC) to the specified time. The third list element @var{microsec}, if -present, gives the number of microseconds from the start of that -second to the specified time. -Similarly, the fourth list element @var{picosec}, if present, gives -the number of picoseconds from the start of that microsecond to the -specified time. - - The return value of @code{current-time} represents time using four -integers, as do the timestamps in the return value of -@code{file-attributes} (@pxref{Definition of -file-attributes}). In function arguments, e.g., the @var{time-value} -argument to @code{current-time-string}, two-, three-, and four-integer -lists are accepted. You can convert times from the list -representation into standard human-readable strings using -@code{current-time-string}, or to other forms using the -@code{decode-time} and @code{format-time-string} functions documented -in the following sections. - -@defun current-time-string &optional time-value -This function returns the current time and date as a human-readable -string. The format does not vary for the initial part of the string, -which contains the day of week, month, day of month, and time of day -in that order: the number of characters used for these fields is -always the same, so you can reliably -use @code{substring} to extract them. You should count -characters from the beginning of the string rather than from the end, -as the year might not have exactly four digits, and additional -information may some day be added at the end. - -The argument @var{time-value}, if given, specifies a time to format -(represented as a list of integers), instead of the current time. - -@example -@group -(current-time-string) - @result{} "Wed Oct 14 22:21:05 1987" -@end group -@end example -@end defun - -@defun current-time -This function returns the current time, represented as a list of four -integers @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. -These integers have trailing zeros on systems that return time with -lower resolutions. On all current machines @var{picosec} is a -multiple of 1000, but this may change as higher-resolution clocks -become available. -@end defun - -@defun float-time &optional time-value -This function returns the current time as a floating-point number of -seconds since the epoch. The optional argument @var{time-value}, if -given, specifies a time (represented as a list of integers) to convert -instead of the current time. - -@emph{Warning}: Since the result is floating point, it may not be -exact. Do not use this function if precise time stamps are required. -@end defun - -@defun current-time-zone &optional time-value -@cindex time zone, current -This function returns a list describing the time zone that the user is -in. - -The value has the form @code{(@var{offset} @var{name})}. Here -@var{offset} is an integer giving the number of seconds ahead of UTC -(east of Greenwich). A negative value means west of Greenwich. The -second element, @var{name}, is a string giving the name of the time -zone. Both elements change when daylight saving time begins or ends; -if the user has specified a time zone that does not use a seasonal time -adjustment, then the value is constant through time. - -If the operating system doesn't supply all the information necessary to -compute the value, the unknown elements of the list are @code{nil}. - -The argument @var{time-value}, if given, specifies a time (represented -as a list of integers) to analyze instead of the current time. -@end defun - -The current time zone is determined by the @env{TZ} environment -variable. @xref{System Environment}. For example, you can tell Emacs -to use universal time with @code{(setenv "TZ" "UTC0")}. If @env{TZ} -is not in the environment, Emacs uses a platform-dependent default -time zone. - -@node Time Conversion -@section Time Conversion -@cindex calendrical information - - These functions convert time values (lists of two to four integers, -as explained in the previous section) into calendrical information and -vice versa. - - Many 32-bit operating systems are limited to time values containing -32 bits of information; these systems typically handle only the times -from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC@. -However, 64-bit and some 32-bit operating systems have larger time -values, and can represent times far in the past or future. - - Time conversion functions always use the Gregorian calendar, even -for dates before the Gregorian calendar was introduced. Year numbers -count the number of years since the year 1 B.C., and do not skip zero -as traditional Gregorian years do; for example, the year number -@minus{}37 represents the Gregorian year 38 B.C@. - -@defun decode-time &optional time -This function converts a time value into calendrical information. If -you don't specify @var{time}, it decodes the current time. The return -value is a list of nine elements, as follows: - -@example -(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) -@end example - -Here is what the elements mean: - -@table @var -@item seconds -The number of seconds past the minute, as an integer between 0 and 59. -On some operating systems, this is 60 for leap seconds. -@item minutes -The number of minutes past the hour, as an integer between 0 and 59. -@item hour -The hour of the day, as an integer between 0 and 23. -@item day -The day of the month, as an integer between 1 and 31. -@item month -The month of the year, as an integer between 1 and 12. -@item year -The year, an integer typically greater than 1900. -@item dow -The day of week, as an integer between 0 and 6, where 0 stands for -Sunday. -@item dst -@code{t} if daylight saving time is effect, otherwise @code{nil}. -@item zone -An integer indicating the time zone, as the number of seconds east of -Greenwich. -@end table - -@strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{zone}. -@end defun - -@defun encode-time seconds minutes hour day month year &optional zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a time value. For the meanings of the -arguments, see the table above under @code{decode-time}. - -Year numbers less than 100 are not treated specially. If you want them -to stand for years above 1900, or years above 2000, you must alter them -yourself before you call @code{encode-time}. - -The optional argument @var{zone} defaults to the current time zone and -its daylight saving time rules. If specified, it can be either a list -(as you would get from @code{current-time-zone}), a string as in the -@env{TZ} environment variable, @code{t} for Universal Time, or an -integer (as you would get from @code{decode-time}). The specified -zone is used without any further alteration for daylight saving time. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: - -@example -(apply 'encode-time (decode-time @dots{})) -@end example - -You can perform simple date arithmetic by using out-of-range values for -the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} -arguments; for example, day 0 means the day preceding the given month. - -The operating system puts limits on the range of possible time values; -if you try to encode a time that is out of range, an error results. -For instance, years before 1970 do not work on some systems; -on others, years as early as 1901 do work. -@end defun - -@node Time Parsing -@section Parsing and Formatting Times - - These functions convert time values to text in a string, and vice versa. -Time values are lists of two to four integers (@pxref{Time of Day}). - -@defun date-to-time string -This function parses the time-string @var{string} and returns the -corresponding time value. -@end defun - -@defun format-time-string format-string &optional time universal -This function converts @var{time} (or the current time, if @var{time} is -omitted) to a string according to @var{format-string}. The argument -@var{format-string} may contain @samp{%}-sequences which say to -substitute parts of the time. Here is a table of what the -@samp{%}-sequences mean: - -@table @samp -@item %a -This stands for the abbreviated name of the day of week. -@item %A -This stands for the full name of the day of week. -@item %b -This stands for the abbreviated name of the month. -@item %B -This stands for the full name of the month. -@item %c -This is a synonym for @samp{%x %X}. -@item %C -This has a locale-specific meaning. In the default locale (named C), it -is equivalent to @samp{%A, %B %e, %Y}. -@item %d -This stands for the day of month, zero-padded. -@item %D -This is a synonym for @samp{%m/%d/%y}. -@item %e -This stands for the day of month, blank-padded. -@item %h -This is a synonym for @samp{%b}. -@item %H -This stands for the hour (00--23). -@item %I -This stands for the hour (01--12). -@item %j -This stands for the day of the year (001--366). -@item %k -This stands for the hour (0--23), blank padded. -@item %l -This stands for the hour (1--12), blank padded. -@item %m -This stands for the month (01--12). -@item %M -This stands for the minute (00--59). -@item %n -This stands for a newline. -@item %N -This stands for the nanoseconds (000000000--999999999). To ask for -fewer digits, use @samp{%3N} for milliseconds, @samp{%6N} for -microseconds, etc. Any excess digits are discarded, without rounding. -@item %p -This stands for @samp{AM} or @samp{PM}, as appropriate. -@item %r -This is a synonym for @samp{%I:%M:%S %p}. -@item %R -This is a synonym for @samp{%H:%M}. -@item %S -This stands for the seconds (00--59). -@item %t -This stands for a tab character. -@item %T -This is a synonym for @samp{%H:%M:%S}. -@item %U -This stands for the week of the year (01--52), assuming that weeks -start on Sunday. -@item %w -This stands for the numeric day of week (0--6). Sunday is day 0. -@item %W -This stands for the week of the year (01--52), assuming that weeks -start on Monday. -@item %x -This has a locale-specific meaning. In the default locale (named -@samp{C}), it is equivalent to @samp{%D}. -@item %X -This has a locale-specific meaning. In the default locale (named -@samp{C}), it is equivalent to @samp{%T}. -@item %y -This stands for the year without century (00--99). -@item %Y -This stands for the year with century. -@item %Z -This stands for the time zone abbreviation (e.g., @samp{EST}). -@item %z -This stands for the time zone numerical offset (e.g., @samp{-0500}). -@end table - -You can also specify the field width and type of padding for any of -these @samp{%}-sequences. This works as in @code{printf}: you write -the field width as digits in the middle of a @samp{%}-sequences. If you -start the field width with @samp{0}, it means to pad with zeros. If you -start the field width with @samp{_}, it means to pad with spaces. - -For example, @samp{%S} specifies the number of seconds since the minute; -@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to -pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros, -because that is how @samp{%S} normally pads to two positions. - -The characters @samp{E} and @samp{O} act as modifiers when used between -@samp{%} and one of the letters in the table above. @samp{E} specifies -using the current locale's ``alternative'' version of the date and time. -In a Japanese locale, for example, @code{%Ex} might yield a date format -based on the Japanese Emperors' reigns. @samp{E} is allowed in -@samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and -@samp{%EY}. - -@samp{O} means to use the current locale's ``alternative'' -representation of numbers, instead of the ordinary decimal digits. This -is allowed with most letters, all the ones that output numbers. - -If @var{universal} is non-@code{nil}, that means to describe the time as -Universal Time; @code{nil} means describe it using what Emacs believes -is the local time zone (see @code{current-time-zone}). - -This function uses the C library function @code{strftime} -(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference -Manual}) to do most of the work. In order to communicate with that -function, it first encodes its argument using the coding system -specified by @code{locale-coding-system} (@pxref{Locales}); after -@code{strftime} returns the resulting string, -@code{format-time-string} decodes the string using that same coding -system. -@end defun - -@defun seconds-to-time seconds -This function converts @var{seconds}, the number of seconds since the -epoch, to a time value and returns that. To convert back, use -@code{float-time} (@pxref{Time of Day}). -@end defun - -@defun format-seconds format-string seconds -This function converts its argument @var{seconds} into a string of -years, days, hours, etc., according to @var{format-string}. The -argument @var{format-string} may contain @samp{%}-sequences which -control the conversion. Here is a table of what the -@samp{%}-sequences mean: - -@table @samp -@item %y -@itemx %Y -The integer number of 365-day years. -@item %d -@itemx %D -The integer number of days. -@item %h -@itemx %H -The integer number of hours. -@item %m -@itemx %M -The integer number of minutes. -@item %s -@itemx %S -The integer number of seconds. -@item %z -Non-printing control flag. When it is used, other specifiers must be -given in the order of decreasing size, i.e., years before days, hours -before minutes, etc. Nothing will be produced in the result string to -the left of @samp{%z} until the first non-zero conversion is -encountered. For example, the default format used by -@code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime}) -@w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds -will always be produced, but years, days, hours, and minutes will only -be shown if they are non-zero. -@item %% -Produces a literal @samp{%}. -@end table - -Upper-case format sequences produce the units in addition to the -numbers, lower-case formats produce only the numbers. - -You can also specify the field width by following the @samp{%} with a -number; shorter numbers will be padded with blanks. An optional -period before the width requests zero-padding instead. For example, -@code{"%.3Y"} might produce @code{"004 years"}. - -@emph{Warning:} This function works only with values of @var{seconds} -that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics, -most-positive-fixnum}). -@end defun - -@node Processor Run Time -@section Processor Run time -@cindex processor run time -@cindex Emacs process run time - - Emacs provides several functions and primitives that return time, -both elapsed and processor time, used by the Emacs process. - -@deffn Command emacs-uptime &optional format -@cindex uptime of Emacs -This function returns a string representing the Emacs -@dfn{uptime}---the elapsed wall-clock time this instance of Emacs is -running. The string is formatted by @code{format-seconds} according -to the optional argument @var{format}. For the available format -descriptors, see @ref{Time Parsing, format-seconds}. If @var{format} -is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M, -%z%S"}. - -When called interactively, it prints the uptime in the echo area. -@end deffn - -@defun get-internal-run-time -This function returns the processor run time used by Emacs as a list -of four integers: @code{(@var{high} @var{low} @var{microsec} -@var{picosec})}, using the same format as @code{current-time} -(@pxref{Time of Day}). - -Note that the time returned by this function excludes the time Emacs -was not using the processor, and if the Emacs process has several -threads, the returned value is the sum of the processor times used up -by all Emacs threads. - -If the system doesn't provide a way to determine the processor run -time, @code{get-internal-run-time} returns the same time as -@code{current-time}. -@end defun - -@deffn Command emacs-init-time -This function returns the duration of the Emacs initialization -(@pxref{Startup Summary}) in seconds, as a string. When called -interactively, it prints the duration in the echo area. -@end deffn - -@node Time Calculations -@section Time Calculations - - These functions perform calendrical computations using time values -(the kind of list that @code{current-time} returns). - -@defun time-less-p t1 t2 -This returns @code{t} if time value @var{t1} is less than time value -@var{t2}. -@end defun - -@defun time-subtract t1 t2 -This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, in the same format as a time value. -@end defun - -@defun time-add t1 t2 -This returns the sum of two time values, one of which ought to -represent a time difference rather than a point in time. -Here is how to add a number of seconds to a time value: - -@example -(time-add @var{time} (seconds-to-time @var{seconds})) -@end example -@end defun - -@defun time-to-days time -This function returns the number of days between the beginning of year -1 and @var{time}. -@end defun - -@defun time-to-day-in-year time -This returns the day number within the year corresponding to @var{time}. -@end defun - -@defun date-leap-year-p year -This function returns @code{t} if @var{year} is a leap year. -@end defun - -@node Timers -@section Timers for Delayed Execution -@cindex timer - - You can set up a @dfn{timer} to call a function at a specified -future time or after a certain length of idleness. - - Emacs cannot run timers at any arbitrary point in a Lisp program; it -can run them only when Emacs could accept output from a subprocess: -namely, while waiting or inside certain primitive functions such as -@code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a -timer's execution may be delayed if Emacs is busy. However, the time of -execution is very precise if Emacs is idle. - - Emacs binds @code{inhibit-quit} to @code{t} before calling the timer -function, because quitting out of many timer functions can leave -things in an inconsistent state. This is normally unproblematical -because most timer functions don't do a lot of work. Indeed, for a -timer to call a function that takes substantial time to run is likely -to be annoying. If a timer function needs to allow quitting, it -should use @code{with-local-quit} (@pxref{Quitting}). For example, if -a timer function calls @code{accept-process-output} to receive output -from an external process, that call should be wrapped inside -@code{with-local-quit}, to ensure that @kbd{C-g} works if the external -process hangs. - - It is usually a bad idea for timer functions to alter buffer -contents. When they do, they usually should call @code{undo-boundary} -both before and after changing the buffer, to separate the timer's -changes from user commands' changes and prevent a single undo entry -from growing to be quite large. - - Timer functions should also avoid calling functions that cause Emacs -to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to -unpredictable effects, since other timers (or even the same timer) can -run while waiting. If a timer function needs to perform an action -after a certain time has elapsed, it can do this by scheduling a new -timer. - - If a timer function calls functions that can change the match data, -it should save and restore the match data. @xref{Saving Match Data}. - -@deffn Command run-at-time time repeat function &rest args -This sets up a timer that calls the function @var{function} with -arguments @var{args} at time @var{time}. If @var{repeat} is a number -(integer or floating point), the timer is scheduled to run again every -@var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil}, -the timer runs only once. - -@var{time} may specify an absolute or a relative time. - -Absolute times may be specified using a string with a limited variety -of formats, and are taken to be times @emph{today}, even if already in -the past. The recognized forms are @samp{@var{xxxx}}, -@samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time), -and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm}, -@samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am}, -@samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or -@samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon -to separate the hour and minute parts. - -To specify a relative time as a string, use numbers followed by units. -For example: - -@table @samp -@item 1 min -denotes 1 minute from now. -@item 1 min 5 sec -denotes 65 seconds from now. -@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year -denotes exactly 103 months, 123 days, and 10862 seconds from now. -@end table - -For relative time values, Emacs considers a month to be exactly thirty -days, and a year to be exactly 365.25 days. - -Not all convenient formats are strings. If @var{time} is a number -(integer or floating point), that specifies a relative time measured in -seconds. The result of @code{encode-time} can also be used to specify -an absolute value for @var{time}. - -In most cases, @var{repeat} has no effect on when @emph{first} call -takes place---@var{time} alone specifies that. There is one exception: -if @var{time} is @code{t}, then the timer runs whenever the time is a -multiple of @var{repeat} seconds after the epoch. This is useful for -functions like @code{display-time}. - -The function @code{run-at-time} returns a timer value that identifies -the particular scheduled future action. You can use this value to call -@code{cancel-timer} (see below). -@end deffn - - A repeating timer nominally ought to run every @var{repeat} seconds, -but remember that any invocation of a timer can be late. Lateness of -one repetition has no effect on the scheduled time of the next -repetition. For instance, if Emacs is busy computing for long enough -to cover three scheduled repetitions of the timer, and then starts to -wait, it will immediately call the timer function three times in -immediate succession (presuming no other timers trigger before or -between them). If you want a timer to run again no less than @var{n} -seconds after the last invocation, don't use the @var{repeat} argument. -Instead, the timer function should explicitly reschedule the timer. - -@defopt timer-max-repeats -This variable's value specifies the maximum number of times to repeat -calling a timer function in a row, when many previously scheduled -calls were unavoidably delayed. -@end defopt - -@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{} -Execute @var{body}, but give up after @var{seconds} seconds. If -@var{body} finishes before the time is up, @code{with-timeout} returns -the value of the last form in @var{body}. If, however, the execution of -@var{body} is cut short by the timeout, then @code{with-timeout} -executes all the @var{timeout-forms} and returns the value of the last -of them. - -This macro works by setting a timer to run after @var{seconds} seconds. If -@var{body} finishes before that time, it cancels the timer. If the -timer actually runs, it terminates execution of @var{body}, then -executes @var{timeout-forms}. - -Since timers can run within a Lisp program only when the program calls a -primitive that can wait, @code{with-timeout} cannot stop executing -@var{body} while it is in the midst of a computation---only when it -calls one of those primitives. So use @code{with-timeout} only with a -@var{body} that waits for input, not one that does a long computation. -@end defmac - - The function @code{y-or-n-p-with-timeout} provides a simple way to use -a timer to avoid waiting too long for an answer. @xref{Yes-or-No -Queries}. - -@defun cancel-timer timer -This cancels the requested action for @var{timer}, which should be a -timer---usually, one previously returned by @code{run-at-time} or -@code{run-with-idle-timer}. This cancels the effect of that call to -one of these functions; the arrival of the specified time will not -cause anything special to happen. -@end defun - -@node Idle Timers -@section Idle Timers - - Here is how to set up a timer that runs when Emacs is idle for a -certain length of time. Aside from how to set them up, idle timers -work just like ordinary timers. - -@deffn Command run-with-idle-timer secs repeat function &rest args -Set up a timer which runs the next time Emacs is idle for @var{secs} -seconds. The value of @var{secs} may be a number or a value of the type -returned by @code{current-idle-time}. - -If @var{repeat} is @code{nil}, the timer runs just once, the first time -Emacs remains idle for a long enough time. More often @var{repeat} is -non-@code{nil}, which means to run the timer @emph{each time} Emacs -remains idle for @var{secs} seconds. - -The function @code{run-with-idle-timer} returns a timer value which you -can use in calling @code{cancel-timer} (@pxref{Timers}). -@end deffn - -@cindex idleness - Emacs becomes @dfn{idle} when it starts waiting for user input, and -it remains idle until the user provides some input. If a timer is set -for five seconds of idleness, it runs approximately five seconds after -Emacs first becomes idle. Even if @var{repeat} is non-@code{nil}, -this timer will not run again as long as Emacs remains idle, because -the duration of idleness will continue to increase and will not go -down to five seconds again. - - Emacs can do various things while idle: garbage collect, autosave or -handle data from a subprocess. But these interludes during idleness do -not interfere with idle timers, because they do not reset the clock of -idleness to zero. An idle timer set for 600 seconds will run when ten -minutes have elapsed since the last user command was finished, even if -subprocess output has been accepted thousands of times within those ten -minutes, and even if there have been garbage collections and autosaves. - - When the user supplies input, Emacs becomes non-idle while executing the -input. Then it becomes idle again, and all the idle timers that are -set up to repeat will subsequently run another time, one by one. - - Do not write an idle timer function containing a loop which does a -certain amount of processing each time around, and exits when -@code{(input-pending-p)} is non-@code{nil}. This approach seems very -natural but has two problems: - -@itemize -@item -It blocks out all process output (since Emacs accepts process output -only while waiting). - -@item -It blocks out any idle timers that ought to run during that time. -@end itemize - -@noindent -Similarly, do not write an idle timer function that sets up another -idle timer (including the same idle timer) with @var{secs} argument -less than or equal to the current idleness time. Such a timer will -run almost immediately, and continue running again and again, instead -of waiting for the next time Emacs becomes idle. The correct approach -is to reschedule with an appropriate increment of the current value of -the idleness time, as described below. - -@defun current-idle-time -If Emacs is idle, this function returns the length of time Emacs has -been idle, as a list of four integers: @code{(@var{sec-high} -@var{sec-low} @var{microsec} @var{picosec})}, using the same format as -@code{current-time} (@pxref{Time of Day}). - -When Emacs is not idle, @code{current-idle-time} returns @code{nil}. -This is a convenient way to test whether Emacs is idle. -@end defun - - The main use of @code{current-idle-time} is when an idle timer -function wants to ``take a break'' for a while. It can set up another -idle timer to call the same function again, after a few seconds more -idleness. Here's an example: - -@example -(defvar my-resume-timer nil - "Timer for `my-timer-function' to reschedule itself, or nil.") - -(defun my-timer-function () - ;; @r{If the user types a command while @code{my-resume-timer}} - ;; @r{is active, the next time this function is called from} - ;; @r{its main idle timer, deactivate @code{my-resume-timer}.} - (when my-resume-timer - (cancel-timer my-resume-timer)) - ...@var{do the work for a while}... - (when @var{taking-a-break} - (setq my-resume-timer - (run-with-idle-timer - ;; Compute an idle time @var{break-length} - ;; more than the current value. - (time-add (current-idle-time) - (seconds-to-time @var{break-length})) - nil - 'my-timer-function)))) -@end example - -@node Terminal Input -@section Terminal Input -@cindex terminal input - - This section describes functions and variables for recording or -manipulating terminal input. See @ref{Display}, for related -functions. - -@menu -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. -@end menu - -@node Input Modes -@subsection Input Modes -@cindex input modes -@cindex terminal input modes - -@defun set-input-mode interrupt flow meta &optional quit-char -This function sets the mode for reading keyboard input. If -@var{interrupt} is non-@code{nil}, then Emacs uses input interrupts. -If it is @code{nil}, then it uses @sc{cbreak} mode. The default -setting is system-dependent. Some systems always use @sc{cbreak} mode -regardless of what is specified. - -When Emacs communicates directly with X, it ignores this argument and -uses interrupts if that is the way it knows how to communicate. - -If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} -(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This -has no effect except in @sc{cbreak} mode. - -The argument @var{meta} controls support for input character codes -above 127. If @var{meta} is @code{t}, Emacs converts characters with -the 8th bit set into Meta characters. If @var{meta} is @code{nil}, -Emacs disregards the 8th bit; this is necessary when the terminal uses -it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, -Emacs uses all 8 bits of input unchanged. This is good for terminals -that use 8-bit character sets. - -If @var{quit-char} is non-@code{nil}, it specifies the character to -use for quitting. Normally this character is @kbd{C-g}. -@xref{Quitting}. -@end defun - -The @code{current-input-mode} function returns the input mode settings -Emacs is currently using. - -@defun current-input-mode -This function returns the current mode for reading keyboard input. It -returns a list, corresponding to the arguments of @code{set-input-mode}, -of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in -which: -@table @var -@item interrupt -is non-@code{nil} when Emacs is using interrupt-driven input. If -@code{nil}, Emacs is using @sc{cbreak} mode. -@item flow -is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) -flow control for output to the terminal. This value is meaningful only -when @var{interrupt} is @code{nil}. -@item meta -is @code{t} if Emacs treats the eighth bit of input characters as -the meta bit; @code{nil} means Emacs clears the eighth bit of every -input character; any other value means Emacs uses all eight bits as the -basic character code. -@item quit -is the character Emacs currently uses for quitting, usually @kbd{C-g}. -@end table -@end defun - -@node Recording Input -@subsection Recording Input -@cindex recording input - -@defun recent-keys -This function returns a vector containing the last 300 input events from -the keyboard or mouse. All input events are included, whether or not -they were used as parts of key sequences. Thus, you always get the last -300 input events, not counting events generated by keyboard macros. -(These are excluded because they are less interesting for debugging; it -should be enough to see the events that invoked the macros.) - -A call to @code{clear-this-command-keys} (@pxref{Command Loop Info}) -causes this function to return an empty vector immediately afterward. -@end defun - -@deffn Command open-dribble-file filename -@cindex dribble file -This function opens a @dfn{dribble file} named @var{filename}. When a -dribble file is open, each input event from the keyboard or mouse (but -not those from keyboard macros) is written in that file. A -non-character event is expressed using its printed representation -surrounded by @samp{<@dots{}>}. Be aware that sensitive information -(such as passwords) may end up recorded in the dribble file. - -You close the dribble file by calling this function with an argument -of @code{nil}. -@end deffn - - See also the @code{open-termscript} function (@pxref{Terminal Output}). - -@node Terminal Output -@section Terminal Output -@cindex terminal output - - The terminal output functions send output to a text terminal, or keep -track of output sent to the terminal. The variable @code{baud-rate} -tells you what Emacs thinks is the output speed of the terminal. - -@defopt baud-rate -This variable's value is the output speed of the terminal, as far as -Emacs knows. Setting this variable does not change the speed of actual -data transmission, but the value is used for calculations such as -padding. - - It also affects decisions about whether to scroll part of the -screen or repaint on text terminals. @xref{Forcing Redisplay}, -for the corresponding functionality on graphical terminals. - -The value is measured in baud. -@end defopt - - If you are running across a network, and different parts of the -network work at different baud rates, the value returned by Emacs may be -different from the value used by your local terminal. Some network -protocols communicate the local terminal speed to the remote machine, so -that Emacs and other programs can get the proper value, but others do -not. If Emacs has the wrong value, it makes decisions that are less -than optimal. To fix the problem, set @code{baud-rate}. - -@defun send-string-to-terminal string &optional terminal -This function sends @var{string} to @var{terminal} without alteration. -Control characters in @var{string} have terminal-dependent effects. -This function operates only on text terminals. @var{terminal} may be -a terminal object, a frame, or @code{nil} for the selected frame's -terminal. In batch mode, @var{string} is sent to @code{stdout} when -@var{terminal} is @code{nil}. - -One use of this function is to define function keys on terminals that -have downloadable function key definitions. For example, this is how (on -certain terminals) to define function key 4 to move forward four -characters (by transmitting the characters @kbd{C-u C-f} to the -computer): - -@example -@group -(send-string-to-terminal "\eF4\^U\^F") - @result{} nil -@end group -@end example -@end defun - -@deffn Command open-termscript filename -@cindex termscript file -This function is used to open a @dfn{termscript file} that will record -all the characters sent by Emacs to the terminal. It returns -@code{nil}. Termscript files are useful for investigating problems -where Emacs garbles the screen, problems that are due to incorrect -Termcap entries or to undesirable settings of terminal options more -often than to actual Emacs bugs. Once you are certain which characters -were actually output, you can determine reliably whether they correspond -to the Termcap specifications in use. - -@example -@group -(open-termscript "../junk/termscript") - @result{} nil -@end group -@end example - -You close the termscript file by calling this function with an -argument of @code{nil}. - -See also @code{open-dribble-file} in @ref{Recording Input}. -@end deffn - -@node Sound Output -@section Sound Output -@cindex sound - - To play sound using Emacs, use the function @code{play-sound}. Only -certain systems are supported; if you call @code{play-sound} on a -system which cannot really do the job, it gives an error. - -@c FIXME: Add indexes for Au and WAV? --xfq - The sound must be stored as a file in RIFF-WAVE format (@samp{.wav}) -or Sun Audio format (@samp{.au}). - -@defun play-sound sound -This function plays a specified sound. The argument, @var{sound}, has -the form @code{(sound @var{properties}...)}, where the @var{properties} -consist of alternating keywords (particular symbols recognized -specially) and values corresponding to them. - -Here is a table of the keywords that are currently meaningful in -@var{sound}, and their meanings: - -@table @code -@item :file @var{file} -This specifies the file containing the sound to play. -If the file name is not absolute, it is expanded against -the directory @code{data-directory}. - -@item :data @var{data} -This specifies the sound to play without need to refer to a file. The -value, @var{data}, should be a string containing the same bytes as a -sound file. We recommend using a unibyte string. - -@item :volume @var{volume} -This specifies how loud to play the sound. It should be a number in the -range of 0 to 1. The default is to use whatever volume has been -specified before. - -@item :device @var{device} -This specifies the system device on which to play the sound, as a -string. The default device is system-dependent. -@end table - -Before actually playing the sound, @code{play-sound} -calls the functions in the list @code{play-sound-functions}. -Each function is called with one argument, @var{sound}. -@end defun - -@deffn Command play-sound-file file &optional volume device -This function is an alternative interface to playing a sound @var{file} -specifying an optional @var{volume} and @var{device}. -@end deffn - -@defvar play-sound-functions -A list of functions to be called before playing a sound. Each function -is called with one argument, a property list that describes the sound. -@end defvar - -@node X11 Keysyms -@section Operating on X11 Keysyms -@cindex X11 keysyms - -To define system-specific X11 keysyms, set the variable -@code{system-key-alist}. - -@defvar system-key-alist -This variable's value should be an alist with one element for each -system-specific keysym. Each element has the form @code{(@var{code} -. @var{symbol})}, where @var{code} is the numeric keysym code (not -including the ``vendor specific'' bit, -@ifnottex -@minus{}2**28), -@end ifnottex -@tex -$-2^{28}$), -@end tex -and @var{symbol} is the name for the function key. - -For example @code{(168 . mute-acute)} defines a system-specific key (used -by HP X servers) whose numeric code is -@ifnottex -@minus{}2**28 -@end ifnottex -@tex -$-2^{28}$ -@end tex -+ 168. - -It is not crucial to exclude from the alist the keysyms of other X -servers; those do no harm, as long as they don't conflict with the ones -used by the X server actually in use. - -The variable is always local to the current terminal, and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables: - -@defvar x-alt-keysym -@defvarx x-meta-keysym -@defvarx x-hyper-keysym -@defvarx x-super-keysym -The name of the keysym that should stand for the Alt modifier -(respectively, for Meta, Hyper, and Super). For example, here is -how to swap the Meta and Alt modifiers within Emacs: -@lisp -(setq x-alt-keysym 'meta) -(setq x-meta-keysym 'alt) -@end lisp -@end defvar - -@node Batch Mode -@section Batch Mode -@cindex batch mode - - The command-line option @samp{-batch} causes Emacs to run -noninteractively. In this mode, Emacs does not read commands from the -terminal, it does not alter the terminal modes, and it does not expect -to be outputting to an erasable screen. The idea is that you specify -Lisp programs to run; when they are finished, Emacs should exit. The -way to specify the programs to run is with @samp{-l @var{file}}, which -loads the library named @var{file}, or @samp{-f @var{function}}, which -calls @var{function} with no arguments, or @samp{--eval @var{form}}. - - Any Lisp program output that would normally go to the echo area, -either using @code{message}, or using @code{prin1}, etc., with @code{t} -as the stream, goes instead to Emacs's standard error descriptor when -in batch mode. Similarly, input that would normally come from the -minibuffer is read from the standard input descriptor. -Thus, Emacs behaves much like a noninteractive -application program. (The echo area output that Emacs itself normally -generates, such as command echoing, is suppressed entirely.) - -@defvar noninteractive -This variable is non-@code{nil} when Emacs is running in batch mode. -@end defvar - -@node Session Management -@section Session Management -@cindex session manager - -Emacs supports the X Session Management Protocol, which is used to -suspend and restart applications. In the X Window System, a program -called the @dfn{session manager} is responsible for keeping track of -the applications that are running. When the X server shuts down, the -session manager asks applications to save their state, and delays the -actual shutdown until they respond. An application can also cancel -the shutdown. - -When the session manager restarts a suspended session, it directs -these applications to individually reload their saved state. It does -this by specifying a special command-line argument that says what -saved session to restore. For Emacs, this argument is @samp{--smid -@var{session}}. - -@defvar emacs-save-session-functions -@cindex session file -Emacs supports saving state via a hook called -@code{emacs-save-session-functions}. Emacs runs this hook when the -session manager tells it that the window system is shutting down. The -functions are called with no arguments, and with the current buffer -set to a temporary buffer. Each function can use @code{insert} to add -Lisp code to this buffer. At the end, Emacs saves the buffer in a -file, called the @dfn{session file}. - -@findex emacs-session-restore -Subsequently, when the session manager restarts Emacs, it loads the -session file automatically (@pxref{Loading}). This is performed by a -function named @code{emacs-session-restore}, which is called during -startup. @xref{Startup Summary}. - -If a function in @code{emacs-save-session-functions} returns -non-@code{nil}, Emacs tells the session manager to cancel the -shutdown. -@end defvar - -Here is an example that just inserts some text into @file{*scratch*} when -Emacs is restarted by the session manager. - -@example -@group -(add-hook 'emacs-save-session-functions 'save-yourself-test) -@end group - -@group -(defun save-yourself-test () - (insert "(save-current-buffer - (switch-to-buffer \"*scratch*\") - (insert \"I am restored\"))") - nil) -@end group -@end example - -@node Desktop Notifications -@section Desktop Notifications -@cindex desktop notifications -@cindex notifications, on desktop - -Emacs is able to send @dfn{notifications} on systems that support the -freedesktop.org Desktop Notifications Specification. In order to use -this functionality, Emacs must have been compiled with D-Bus support, -and the @code{notifications} library must be loaded. @xref{Top, , -D-Bus,dbus,D-Bus integration in Emacs}. - -@defun notifications-notify &rest params -This function sends a notification to the desktop via D-Bus, -consisting of the parameters specified by the @var{params} arguments. -These arguments should consist of alternating keyword and value pairs. -The supported keywords and values are as follows: - -@table @code -@item :bus @var{bus} -The D-Bus bus. This argument is needed only if a bus other than -@code{:session} shall be used. - -@item :title @var{title} -The notification title. - -@item :body @var{text} -The notification body text. Depending on the implementation of the -notification server, the text could contain HTML markups, like -@samp{"bold text"}, hyperlinks, or images. Special HTML -characters must be encoded, as @samp{"Contact -<postmaster@@localhost>!"}. - -@item :app-name @var{name} -The name of the application sending the notification. The default is -@code{notifications-application-name}. - -@item :replaces-id @var{id} -The notification @var{id} that this notification replaces. @var{id} -must be the result of a previous @code{notifications-notify} call. - -@item :app-icon @var{icon-file} -The file name of the notification icon. If set to @code{nil}, no icon -is displayed. The default is @code{notifications-application-icon}. - -@item :actions (@var{key} @var{title} @var{key} @var{title} ...) -A list of actions to be applied. @var{key} and @var{title} are both -strings. The default action (usually invoked by clicking the -notification) should have a key named @samp{"default"}. The title can -be anything, though implementations are free not to display it. - -@item :timeout @var{timeout} -The timeout time in milliseconds since the display of the notification -at which the notification should automatically close. If @minus{}1, the -notification's expiration time is dependent on the notification -server's settings, and may vary for the type of notification. If 0, -the notification never expires. Default value is @minus{}1. - -@item :urgency @var{urgency} -The urgency level. It can be @code{low}, @code{normal}, or @code{critical}. - -@item :action-items -When this keyword is given, the @var{title} string of the actions is -interpreted as icon name. - -@item :category @var{category} -The type of notification this is, a string. See the -@uref{http://developer.gnome.org/notification-spec/#categories, -Desktop Notifications Specification} for a list of standard -categories. - -@item :desktop-entry @var{filename} -This specifies the name of the desktop filename representing the -calling program, like @samp{"emacs"}. - -@item :image-data (@var{width} @var{height} @var{rowstride} @var{has-alpha} @var{bits} @var{channels} @var{data}) -This is a raw data image format that describes the width, height, -rowstride, whether there is an alpha channel, bits per sample, -channels and image data, respectively. - -@item :image-path @var{path} -This is represented either as a URI (@samp{file://} is the only URI -schema supported right now) or a name in a freedesktop.org-compliant -icon theme from @samp{$XDG_DATA_DIRS/icons}. - -@item :sound-file @var{filename} -The path to a sound file to play when the notification pops up. - -@item :sound-name @var{name} -A themable named sound from the freedesktop.org sound naming -specification from @samp{$XDG_DATA_DIRS/sounds}, to play when the -notification pops up. Similar to the icon name, only for sounds. An -example would be @samp{"message-new-instant"}. - -@item :suppress-sound -Causes the server to suppress playing any sounds, if it has that -ability. - -@item :resident -When set the server will not automatically remove the notification -when an action has been invoked. The notification will remain resident -in the server until it is explicitly removed by the user or by the -sender. This hint is likely only useful when the server has the -@code{:persistence} capability. - -@item :transient -When set the server will treat the notification as transient and -by-pass the server's persistence capability, if it should exist. - -@item :x @var{position} -@itemx :y @var{position} -Specifies the X, Y location on the screen that the -notification should point to. Both arguments must be used together. - -@item :on-action @var{function} -Function to call when an action is invoked. The notification @var{id} -and the @var{key} of the action are passed as arguments to the -function. - -@item :on-close @var{function} -Function to call when the notification has been closed by timeout or -by the user. The function receive the notification @var{id} and the closing -@var{reason} as arguments: - -@itemize -@item @code{expired} if the notification has expired -@item @code{dismissed} if the notification was dismissed by the user -@item @code{close-notification} if the notification was closed by a call to -@code{notifications-close-notification} -@item @code{undefined} if the notification server hasn't provided a reason -@end itemize -@end table - -Which parameters are accepted by the notification server can be -checked via @code{notifications-get-capabilities}. - -This function returns a notification id, an integer, which can be used -to manipulate the notification item with -@code{notifications-close-notification} or the @code{:replaces-id} -argument of another @code{notifications-notify} call. For example: - -@example -@group -(defun my-on-action-function (id key) - (message "Message %d, key \"%s\" pressed" id key)) - @result{} my-on-action-function -@end group - -@group -(defun my-on-close-function (id reason) - (message "Message %d, closed due to \"%s\"" id reason)) - @result{} my-on-close-function -@end group - -@group -(notifications-notify - :title "Title" - :body "This is important." - :actions '("Confirm" "I agree" "Refuse" "I disagree") - :on-action 'my-on-action-function - :on-close 'my-on-close-function) - @result{} 22 -@end group - -@group -A message window opens on the desktop. Press "I agree" - @result{} Message 22, key "Confirm" pressed - Message 22, closed due to "dismissed" -@end group -@end example -@end defun - -@defun notifications-close-notification id &optional bus -This function closes a notification with identifier @var{id}. -@var{bus} can be a string denoting a D-Bus connection, the default is -@code{:session}. -@end defun - -@defun notifications-get-capabilities &optional bus -Returns the capabilities of the notification server, a list of -symbols. @var{bus} can be a string denoting a D-Bus connection, the -default is @code{:session}. The following capabilities can be -expected: - -@table @code -@item :actions -The server will provide the specified actions to the user. - -@item :body -Supports body text. - -@item :body-hyperlinks -The server supports hyperlinks in the notifications. - -@item :body-images -The server supports images in the notifications. - -@item :body-markup -Supports markup in the body text. - -@item :icon-multi -The server will render an animation of all the frames in a given image -array. - -@item :icon-static -Supports display of exactly 1 frame of any given image array. This -value is mutually exclusive with @code{:icon-multi}. - -@item :persistence -The server supports persistence of notifications. - -@item :sound -The server supports sounds on notifications. -@end table - -Further vendor-specific caps start with @code{:x-vendor}, like -@code{:x-gnome-foo-cap}. -@end defun - -@defun notifications-get-server-information &optional bus -Return information on the notification server, a list of strings. -@var{bus} can be a string denoting a D-Bus connection, the default is -@code{:session}. The returned list is @code{(@var{name} @var{vendor} -@var{version} @var{spec-version})}. - -@table @var -@item name -The product name of the server. - -@item vendor -The vendor name. For example, @samp{"KDE"}, @samp{"GNOME"}. - -@item version -The server's version number. - -@item spec-version -The specification version the server is compliant with. -@end table - -If @var{SPEC_VERSION} is @code{nil}, the server supports a -specification prior to @samp{"1.0"}. -@end defun - -@node File Notifications -@section Notifications on File Changes -@cindex file notifications -@cindex watch, for filesystem events - -Several operating systems support watching of filesystems for changes -of files. If configured properly, Emacs links a respective library -like @file{gfilenotify}, @file{inotify}, or @file{w32notify} -statically. These libraries enable watching of filesystems on the -local machine. - -It is also possible to watch filesystems on remote machines, -@pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual} -This does not depend on one of the libraries linked to Emacs. - -Since all these libraries emit different events on notified file -changes, there is the Emacs library @code{filenotify} which provides a -unique interface. - -@defun file-notify-add-watch file flags callback -Add a watch for filesystem events pertaining to @var{file}. This -arranges for filesystem events pertaining to @var{file} to be reported -to Emacs. - -The returned value is a descriptor for the added watch. Its type -depends on the underlying library, it cannot be assumed to be an -integer as in the example below. It should be used for comparison by -@code{equal} only. - -If the @var{file} cannot be watched for some reason, this function -signals a @code{file-notify-error} error. - -Sometimes, mounted filesystems cannot be watched for file changes. -This is not detected by this function, a non-@code{nil} return value -does not guarantee that changes on @var{file} will be notified. - -@var{flags} is a list of conditions to set what will be watched for. -It can include the following symbols: - -@table @code -@item change -watch for file changes -@item attribute-change -watch for file attribute changes, like permissions or modification -time -@end table - -If @var{file} is a directory, changes for all files in that directory -will be notified. This does not work recursively. - -When any event happens, Emacs will call the @var{callback} function -passing it a single argument @var{event}, which is of the form - -@lisp -(@var{descriptor} @var{action} @var{file} [@var{file1}]) -@end lisp - -@var{descriptor} is the same object as the one returned by this -function. @var{action} is the description of the event. It could be -any one of the following symbols: - -@table @code -@item created -@var{file} was created -@item deleted -@var{file} was deleted -@item changed -@var{file} has changed -@item renamed -@var{file} has been renamed to @var{file1} -@item attribute-changed -a @var{file} attribute was changed -@end table - -@var{file} and @var{file1} are the name of the file(s) whose event is -being reported. For example: - -@example -@group -(require 'filenotify) - @result{} filenotify -@end group - -@group -(defun my-notify-callback (event) - (message "Event %S" event)) - @result{} my-notify-callback -@end group - -@group -(file-notify-add-watch - "/tmp" '(change attribute-change) 'my-notify-callback) - @result{} 35025468 -@end group - -@group -(write-region "foo" nil "/tmp/foo") - @result{} Event (35025468 created "/tmp/.#foo") - Event (35025468 created "/tmp/foo") - Event (35025468 changed "/tmp/foo") - Event (35025468 deleted "/tmp/.#foo") -@end group - -@group -(write-region "bla" nil "/tmp/foo") - @result{} Event (35025468 created "/tmp/.#foo") - Event (35025468 changed "/tmp/foo") [2 times] - Event (35025468 deleted "/tmp/.#foo") -@end group - -@group -(set-file-modes "/tmp/foo" (default-file-modes)) - @result{} Event (35025468 attribute-changed "/tmp/foo") -@end group -@end example - -Whether the action @code{renamed} is returned, depends on the used -watch library. It can be expected, when a directory is watched, and -both @var{file} and @var{file1} belong to this directory. Otherwise, -the actions @code{deleted} and @code{created} could be returned in a -random order. - -@example -@group -(rename-file "/tmp/foo" "/tmp/bla") - @result{} Event (35025468 renamed "/tmp/foo" "/tmp/bla") -@end group - -@group -(file-notify-add-watch - "/var/tmp" '(change attribute-change) 'my-notify-callback) - @result{} 35025504 -@end group - -@group -(rename-file "/tmp/bla" "/var/tmp/bla") - @result{} ;; gfilenotify - Event (35025468 renamed "/tmp/bla" "/var/tmp/bla") - - @result{} ;; inotify - Event (35025504 created "/var/tmp/bla") - Event (35025468 deleted "/tmp/bla") -@end group -@end example -@end defun - -@defun file-notify-rm-watch descriptor -Removes an existing file watch specified by its @var{descriptor}. -@var{descriptor} should be an object returned by -@code{file-notify-add-watch}. -@end defun - -@node Dynamic Libraries -@section Dynamically Loaded Libraries -@cindex dynamic libraries - - A @dfn{dynamically loaded library} is a library that is loaded on -demand, when its facilities are first needed. Emacs supports such -on-demand loading of support libraries for some of its features. - -@defvar dynamic-library-alist -This is an alist of dynamic libraries and external library files -implementing them. - -Each element is a list of the form -@w{@code{(@var{library} @var{files}@dots{})}}, where the @code{car} is -a symbol representing a supported external library, and the rest are -strings giving alternate filenames for that library. - -Emacs tries to load the library from the files in the order they -appear in the list; if none is found, the Emacs session won't have -access to that library, and the features it provides will be -unavailable. - -Image support on some platforms uses this facility. Here's an example -of setting this variable for supporting images on MS-Windows: - -@example -(setq dynamic-library-alist - '((xpm "libxpm.dll" "xpm4.dll" "libXpm-nox4.dll") - (png "libpng12d.dll" "libpng12.dll" "libpng.dll" - "libpng13d.dll" "libpng13.dll") - (jpeg "jpeg62.dll" "libjpeg.dll" "jpeg-62.dll" - "jpeg.dll") - (tiff "libtiff3.dll" "libtiff.dll") - (gif "giflib4.dll" "libungif4.dll" "libungif.dll") - (svg "librsvg-2-2.dll") - (gdk-pixbuf "libgdk_pixbuf-2.0-0.dll") - (glib "libglib-2.0-0.dll") - (gobject "libgobject-2.0-0.dll"))) -@end example - -Note that image types @code{pbm} and @code{xbm} do not need entries in -this variable because they do not depend on external libraries and are -always available in Emacs. - -Also note that this variable is not meant to be a generic facility for -accessing external libraries; only those already known by Emacs can -be loaded through it. - -This variable is ignored if the given @var{library} is statically -linked into Emacs. -@end defvar diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi deleted file mode 100644 index c92497a8ce3..00000000000 --- a/doc/lispref/package.texi +++ /dev/null @@ -1,379 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2010-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Packaging -@chapter Preparing Lisp code for distribution -@cindex package -@cindex Lisp package - - Emacs provides a standard way to distribute Emacs Lisp code to -users. A @dfn{package} is a collection of one or more files, -formatted and bundled in such a way that users can easily download, -install, uninstall, and upgrade it. - - The following sections describe how to create a package, and how to -put it in a @dfn{package archive} for others to download. -@xref{Packages,,, emacs, The GNU Emacs Manual}, for a description of -user-level features of the packaging system. - -@menu -* Packaging Basics:: The basic concepts of Emacs Lisp packages. -* Simple Packages:: How to package a single .el file. -* Multi-file Packages:: How to package multiple files. -* Package Archives:: Maintaining package archives. -@end menu - -@node Packaging Basics -@section Packaging Basics -@cindex package attributes -@cindex package name -@cindex package version -@cindex dependencies -@cindex package dependencies - - A package is either a @dfn{simple package} or a @dfn{multi-file -package}. A simple package is stored in a package archive as a single -Emacs Lisp file, while a multi-file package is stored as a tar file -(containing multiple Lisp files, and possibly non-Lisp files such as a -manual). - - In ordinary usage, the difference between simple packages and -multi-file packages is relatively unimportant; the Package Menu -interface makes no distinction between them. However, the procedure -for creating them differs, as explained in the following sections. - - Each package (whether simple or multi-file) has certain -@dfn{attributes}: - -@table @asis -@item Name -A short word (e.g., @samp{auctex}). This is usually also the symbol -prefix used in the program (@pxref{Coding Conventions}). - -@item Version -A version number, in a form that the function @code{version-to-list} -understands (e.g., @samp{11.86}). Each release of a package should be -accompanied by an increase in the version number. - -@item Brief description -This is shown when the package is listed in the Package Menu. It -should occupy a single line, ideally in 36 characters or less. - -@item Long description -This is shown in the buffer created by @kbd{C-h P} -(@code{describe-package}), following the package's brief description -and installation status. It normally spans multiple lines, and should -fully describe the package's capabilities and how to begin using it -once it is installed. - -@item Dependencies -A list of other packages (possibly including minimal acceptable -version numbers) on which this package depends. The list may be -empty, meaning this package has no dependencies. Otherwise, -installing this package also automatically installs its dependencies; -if any dependency cannot be found, the package cannot be installed. -@end table - -@cindex content directory, package - Installing a package, either via the command @code{package-install-file}, -or via the Package Menu, creates a subdirectory of -@code{package-user-dir} named @file{@var{name}-@var{version}}, where -@var{name} is the package's name and @var{version} its version -(e.g., @file{~/.emacs.d/elpa/auctex-11.86/}). We call this the -package's @dfn{content directory}. It is where Emacs puts the -package's contents (the single Lisp file for a simple package, or the -files extracted from a multi-file package). - -@cindex package autoloads - Emacs then searches every Lisp file in the content directory for -autoload magic comments (@pxref{Autoload}). These autoload -definitions are saved to a file named @file{@var{name}-autoloads.el} -in the content directory. They are typically used to autoload the -principal user commands defined in the package, but they can also -perform other tasks, such as adding an element to -@code{auto-mode-alist} (@pxref{Auto Major Mode}). Note that a package -typically does @emph{not} autoload every function and variable defined -within it---only the handful of commands typically called to begin -using the package. Emacs then byte-compiles every Lisp file in the -package. - - After installation, the installed package is @dfn{loaded}: Emacs -adds the package's content directory to @code{load-path}, and -evaluates the autoload definitions in @file{@var{name}-autoloads.el}. - - Whenever Emacs starts up, it automatically calls the function -@code{package-initialize} to load installed packages. This is done -after loading the init file and abbrev file (if any) and before -running @code{after-init-hook} (@pxref{Startup Summary}). Automatic -package loading is disabled if the user option -@code{package-enable-at-startup} is @code{nil}. - -@deffn Command package-initialize &optional no-activate -This function initializes Emacs' internal record of which packages are -installed, and loads them. The user option @code{package-load-list} -specifies which packages to load; by default, all installed packages -are loaded. @xref{Package Installation,,, emacs, The GNU Emacs -Manual}. - -The optional argument @var{no-activate}, if non-@code{nil}, causes -Emacs to update its record of installed packages without actually -loading them; it is for internal use only. -@end deffn - -@node Simple Packages -@section Simple Packages -@cindex single file package -@cindex simple package - - A simple package consists of a single Emacs Lisp source file. The -file must conform to the Emacs Lisp library header conventions -(@pxref{Library Headers}). The package's attributes are taken from -the various headers, as illustrated by the following example: - -@example -@group -;;; superfrobnicator.el --- Frobnicate and bifurcate flanges - -;; Copyright (C) 2011 Free Software Foundation, Inc. -@end group - -;; Author: J. R. Hacker -;; Version: 1.3 -;; Package-Requires: ((flange "1.0")) -;; Keywords: multimedia, frobnicate -;; URL: http://example.com/jrhacker/superfrobnicate - -@dots{} - -;;; Commentary: - -;; This package provides a minor mode to frobnicate and/or -;; bifurcate any flanges you desire. To activate it, just type -@dots{} - -;;;###autoload -(define-minor-mode superfrobnicator-mode -@dots{} -@end example - - The name of the package is the same as the base name of the file, as -written on the first line. Here, it is @samp{superfrobnicator}. - - The brief description is also taken from the first line. Here, it -is @samp{Frobnicate and bifurcate flanges}. - - The version number comes from the @samp{Package-Version} header, if -it exists, or from the @samp{Version} header otherwise. One or the -other @emph{must} be present. Here, the version number is 1.3. - - If the file has a @samp{;;; Commentary:} section, this section is -used as the long description. (When displaying the description, Emacs -omits the @samp{;;; Commentary:} line, as well as the leading comment -characters in the commentary itself.) - - If the file has a @samp{Package-Requires} header, that is used as -the package dependencies. In the above example, the package depends -on the @samp{flange} package, version 1.0 or higher. @xref{Library -Headers}, for a description of the @samp{Package-Requires} header. If -the header is omitted, the package has no dependencies. - - The @samp{Keywords} and @samp{URL} headers are optional, but recommended. -The command @code{describe-package} uses these to add links to its -output. The @samp{Keywords} header should contain at least one -standard keyword from the @code{finder-known-keywords} list. - - The file ought to also contain one or more autoload magic comments, -as explained in @ref{Packaging Basics}. In the above example, a magic -comment autoloads @code{superfrobnicator-mode}. - - @xref{Package Archives}, for a explanation of how to add a -single-file package to a package archive. - -@node Multi-file Packages -@section Multi-file Packages -@cindex multi-file package - - A multi-file package is less convenient to create than a single-file -package, but it offers more features: it can include multiple Emacs -Lisp files, an Info manual, and other file types (such as images). - - Prior to installation, a multi-file package is stored in a package -archive as a tar file. The tar file must be named -@file{@var{name}-@var{version}.tar}, where @var{name} is the package -name and @var{version} is the version number. Its contents, once -extracted, must all appear in a directory named -@file{@var{name}-@var{version}}, the @dfn{content directory} -(@pxref{Packaging Basics}). Files may also extract into -subdirectories of the content directory. - - One of the files in the content directory must be named -@file{@var{name}-pkg.el}. It must contain a single Lisp form, -consisting of a call to the function @code{define-package}, described -below. This defines the package's version, brief description, and -requirements. - - For example, if we distribute version 1.3 of the superfrobnicator as -a multi-file package, the tar file would be -@file{superfrobnicator-1.3.tar}. Its contents would extract into the -directory @file{superfrobnicator-1.3}, and one of these would be the -file @file{superfrobnicator-pkg.el}. - -@defun define-package name version &optional docstring requirements -This function defines a package. @var{name} is the package name, a -string. @var{version} is the version, as a string of a form that can -be understood by the function @code{version-to-list}. @var{docstring} -is the brief description. - -@var{requirements} is a list of required packages and their versions. -Each element in this list should have the form @code{(@var{dep-name} -@var{dep-version})}, where @var{dep-name} is a symbol whose name is -the dependency's package name, and @var{dep-version} is the -dependency's version (a string). -@end defun - - If the content directory contains a file named @file{README}, this -file is used as the long description. - - If the content directory contains a file named @file{dir}, this is -assumed to be an Info directory file made with @command{install-info}. -@xref{Invoking install-info, Invoking install-info, Invoking -install-info, texinfo, Texinfo}. The relevant Info files should also -be present in the content directory. In this case, Emacs will -automatically add the content directory to @code{Info-directory-list} -when the package is activated. - - Do not include any @file{.elc} files in the package. Those are -created when the package is installed. Note that there is no way to -control the order in which files are byte-compiled. - - Do not include any file named @file{@var{name}-autoloads.el}. This -file is reserved for the package's autoload definitions -(@pxref{Packaging Basics}). It is created automatically when the -package is installed, by searching all the Lisp files in the package -for autoload magic comments. - - If the multi-file package contains auxiliary data files (such as -images), the package's Lisp code can refer to these files via the -variable @code{load-file-name} (@pxref{Loading}). Here is an example: - -@smallexample -(defconst superfrobnicator-base (file-name-directory load-file-name)) - -(defun superfrobnicator-fetch-image (file) - (expand-file-name file superfrobnicator-base)) -@end smallexample - -@node Package Archives -@section Creating and Maintaining Package Archives -@cindex package archive - - Via the Package Menu, users may download packages from @dfn{package -archives}. Such archives are specified by the variable -@code{package-archives}, whose default value contains a single entry: -the archive hosted by the GNU project at @url{http://elpa.gnu.org}. This -section describes how to set up and maintain a package archive. - -@cindex base location, package archive -@defopt package-archives -The value of this variable is an alist of package archives recognized -by the Emacs package manager. - -Each alist element corresponds to one archive, and should have the -form @code{(@var{id} . @var{location})}, where @var{id} is the name of -the archive (a string) and @var{location} is its @dfn{base location} -(a string). - -If the base location starts with @samp{http:}, it is treated as a HTTP -URL, and packages are downloaded from this archive via HTTP (as is the -case for the default GNU archive). - -Otherwise, the base location should be a directory name. In this -case, Emacs retrieves packages from this archive via ordinary file -access. Such ``local'' archives are mainly useful for testing. -@end defopt - - A package archive is simply a directory in which the package files, -and associated files, are stored. If you want the archive to be -reachable via HTTP, this directory must be accessible to a web server. -How to accomplish this is beyond the scope of this manual. - - A convenient way to set up and update a package archive is via the -@code{package-x} library. This is included with Emacs, but not loaded -by default; type @kbd{M-x load-library @key{RET} package-x @key{RET}} to -load it, or add @code{(require 'package-x)} to your init file. -@xref{Lisp Libraries,, Lisp Libraries, emacs, The GNU Emacs Manual}. -Once loaded, you can make use of the following: - -@defopt package-archive-upload-base -The value of this variable is the base location of a package archive, -as a directory name. The commands in the @code{package-x} library -will use this base location. - -The directory name should be absolute. You may specify a remote name, -such as @file{/ssh:foo@@example.com:/var/www/packages/}, if the -package archive is on a different machine. @xref{Remote Files,, -Remote Files, emacs, The GNU Emacs Manual}. -@end defopt - -@deffn Command package-upload-file filename -This command prompts for @var{filename}, a file name, and uploads that -file to @code{package-archive-upload-base}. The file must be either a -simple package (a @file{.el} file) or a multi-file package (a -@file{.tar} file); otherwise, an error is raised. The package -attributes are automatically extracted, and the archive's contents -list is updated with this information. - -If @code{package-archive-upload-base} does not specify a valid -directory, the function prompts interactively for one. If the -directory does not exist, it is created. The directory need not have -any initial contents (i.e., you can use this command to populate an -initially empty archive). -@end deffn - -@deffn Command package-upload-buffer -This command is similar to @code{package-upload-file}, but instead of -prompting for a package file, it uploads the contents of the current -buffer. The current buffer must be visiting a simple package (a -@file{.el} file) or a multi-file package (a @file{.tar} file); -otherwise, an error is raised. -@end deffn - -@noindent -After you create an archive, remember that it is not accessible in the -Package Menu interface unless it is in @code{package-archives}. - -@cindex package archive security -@cindex package signing -Maintaining a public package archive entails a degree of responsibility. -When Emacs users install packages from your archive, those packages -can cause Emacs to run arbitrary code with the permissions of the -installing user. (This is true for Emacs code in general, not just -for packages.) So you should ensure that your archive is -well-maintained and keep the hosting system secure. - - One way to increase the security of your packages is to @dfn{sign} -them using a cryptographic key. If you have generated a -private/public gpg key pair, you can use gpg to sign the package like -this: - -@c FIXME EasyPG / package-x way to do this. -@example -gpg -ba -o @var{file}.sig @var{file} -@end example - -@noindent -For a single-file package, @var{file} is the package Lisp file; -for a multi-file package, it is the package tar file. -You can also sign the archive's contents file in the same way. -Make the @file{.sig} files available in the same location as the packages. -You should also make your public key available for people to download; -e.g., by uploading it to a key server such as @url{http://pgp.mit.edu/}. -When people install packages from your archive, they can use -your public key to verify the signatures. - -A full explanation of these matters is outside the scope of this -manual. For more information on cryptographic keys and signing, -@pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}. Emacs comes -with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa, -Emacs EasyPG Assistant Manual}. diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi deleted file mode 100644 index fee36fa833d..00000000000 --- a/doc/lispref/positions.texi +++ /dev/null @@ -1,999 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Positions -@chapter Positions -@cindex position (in buffer) -@cindex buffer position - - A @dfn{position} is the index of a character in the text of a buffer. -More precisely, a position identifies the place between two characters -(or before the first character, or after the last character), so we can -speak of the character before or after a given position. However, we -often speak of the character ``at'' a position, meaning the character -after that position. - - Positions are usually represented as integers starting from 1, but -can also be represented as @dfn{markers}---special objects that -relocate automatically when text is inserted or deleted so they stay -with the surrounding characters. Functions that expect an argument to -be a position (an integer), but accept a marker as a substitute, -normally ignore which buffer the marker points into; they convert the -marker to an integer, and use that integer, exactly as if you had -passed the integer as the argument, even if the marker points to the -``wrong'' buffer. A marker that points nowhere cannot convert to an -integer; using it instead of an integer causes an error. -@xref{Markers}. - - See also the ``field'' feature (@pxref{Fields}), which provides -functions that are used by many cursor-motion commands. - -@menu -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. -@end menu - -@node Point -@section Point -@cindex point - - @dfn{Point} is a special buffer position used by many editing -commands, including the self-inserting typed characters and text -insertion functions. Other commands move point through the text -to allow editing and insertion at different places. - - Like other positions, point designates a place between two characters -(or before the first character, or after the last character), rather -than a particular character. Usually terminals display the cursor over -the character that immediately follows point; point is actually before -the character on which the cursor sits. - -@cindex point with narrowing - The value of point is a number no less than 1, and no greater than the -buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then -point is constrained to fall within the accessible portion of the buffer -(possibly at one end of it). - - Each buffer has its own value of point, which is independent of the -value of point in other buffers. Each window also has a value of point, -which is independent of the value of point in other windows on the same -buffer. This is why point can have different values in various windows -that display the same buffer. When a buffer appears in only one window, -the buffer's point and the window's point normally have the same value, -so the distinction is rarely important. @xref{Window Point}, for more -details. - -@defun point -@cindex current buffer position -This function returns the value of point in the current buffer, -as an integer. - -@need 700 -@example -@group -(point) - @result{} 175 -@end group -@end example -@end defun - -@defun point-min -This function returns the minimum accessible value of point in the -current buffer. This is normally 1, but if narrowing is in effect, it -is the position of the start of the region that you narrowed to. -(@xref{Narrowing}.) -@end defun - -@defun point-max -This function returns the maximum accessible value of point in the -current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is -in effect, in which case it is the position of the end of the region -that you narrowed to. (@xref{Narrowing}.) -@end defun - -@defun buffer-end flag -This function returns @code{(point-max)} if @var{flag} is greater than -0, @code{(point-min)} otherwise. The argument @var{flag} must be a -number. -@end defun - -@defun buffer-size &optional buffer -This function returns the total number of characters in the current -buffer. In the absence of any narrowing (@pxref{Narrowing}), -@code{point-max} returns a value one larger than this. - -If you specify a buffer, @var{buffer}, then the value is the -size of @var{buffer}. - -@example -@group -(buffer-size) - @result{} 35 -@end group -@group -(point-max) - @result{} 36 -@end group -@end example -@end defun - -@node Motion -@section Motion -@cindex motion by chars, words, lines, lists - - Motion functions change the value of point, either relative to the -current value of point, relative to the beginning or end of the buffer, -or relative to the edges of the selected window. @xref{Point}. - -@menu -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. -@end menu - -@node Character Motion -@subsection Motion by Characters - - These functions move point based on a count of characters. -@code{goto-char} is the fundamental primitive; the other functions use -that. - -@deffn Command goto-char position -This function sets point in the current buffer to the value -@var{position}. -@c This behavior used to be documented until 2013/08. -@ignore -If @var{position} is less than 1, it moves point to the beginning of -the buffer. If @var{position} is greater than the length of the -buffer, it moves point to the end. -@end ignore - -If narrowing is in effect, @var{position} still counts from the -beginning of the buffer, but point cannot go outside the accessible -portion. If @var{position} is out of range, @code{goto-char} moves -point to the beginning or the end of the accessible portion. - -When this function is called interactively, @var{position} is the -numeric prefix argument, if provided; otherwise it is read from the -minibuffer. - -@code{goto-char} returns @var{position}. -@end deffn - -@deffn Command forward-char &optional count -@c @kindex beginning-of-buffer -@c @kindex end-of-buffer -This function moves point @var{count} characters forward, towards the -end of the buffer (or backward, towards the beginning of the buffer, if -@var{count} is negative). If @var{count} is @code{nil}, the default -is 1. - -If this attempts to move past the beginning or end of the buffer (or -the limits of the accessible portion, when narrowing is in effect), it -signals an error with error symbol @code{beginning-of-buffer} or -@code{end-of-buffer}. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@deffn Command backward-char &optional count -This is just like @code{forward-char} except that it moves -in the opposite direction. -@end deffn - -@node Word Motion -@subsection Motion by Words - - These functions for parsing words use the syntax table to decide -whether a given character is part of a word. @xref{Syntax Tables}. - -@deffn Command forward-word &optional count -This function moves point forward @var{count} words (or backward if -@var{count} is negative). If @var{count} is omitted or @code{nil}, it -defaults to 1. - -``Moving one word'' means moving until point crosses a -word-constituent character and then encounters a word-separator -character. However, this function cannot move point past the boundary -of the accessible portion of the buffer, or across a field boundary -(@pxref{Fields}). The most common case of a field boundary is the end -of the prompt in the minibuffer. - -If it is possible to move @var{count} words, without being stopped -prematurely by the buffer boundary or a field boundary, the value is -@code{t}. Otherwise, the return value is @code{nil} and point stops at -the buffer boundary or field boundary. - -If @code{inhibit-field-text-motion} is non-@code{nil}, -this function ignores field boundaries. - -In an interactive call, @var{count} is specified by the numeric prefix -argument. -@end deffn - -@deffn Command backward-word &optional count -This function is just like @code{forward-word}, except that it moves -backward until encountering the front of a word, rather than forward. -@end deffn - -@defopt words-include-escapes -@c Emacs 19 feature -This variable affects the behavior of @code{forward-word} and everything -that uses it. If it is non-@code{nil}, then characters in the -``escape'' and ``character quote'' syntax classes count as part of -words. Otherwise, they do not. -@end defopt - -@defvar inhibit-field-text-motion -If this variable is non-@code{nil}, certain motion functions including -@code{forward-word}, @code{forward-sentence}, and -@code{forward-paragraph} ignore field boundaries. -@end defvar - -@node Buffer End Motion -@subsection Motion to an End of the Buffer -@cindex move to beginning or end of buffer - - To move point to the beginning of the buffer, write: - -@example -@group -(goto-char (point-min)) -@end group -@end example - -@noindent -Likewise, to move to the end of the buffer, use: - -@example -@group -(goto-char (point-max)) -@end group -@end example - - Here are two commands that users use to do these things. They are -documented here to warn you not to use them in Lisp programs, because -they set the mark and display messages in the echo area. - -@deffn Command beginning-of-buffer &optional n -This function moves point to the beginning of the buffer (or the limits -of the accessible portion, when narrowing is in effect), setting the -mark at the previous position (except in Transient Mark mode, if -the mark is already active, it does not set the mark.) - -If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the -way from the beginning of the accessible portion of the buffer. In an -interactive call, @var{n} is the numeric prefix argument, if provided; -otherwise @var{n} defaults to @code{nil}. - -@strong{Warning:} Don't use this function in Lisp programs! -@end deffn - -@deffn Command end-of-buffer &optional n -This function moves point to the end of the buffer (or the limits of -the accessible portion, when narrowing is in effect), setting the mark -at the previous position (except in Transient Mark mode when the mark -is already active). If @var{n} is non-@code{nil}, then it puts point -@var{n} tenths of the way from the end of the accessible portion of -the buffer. - -In an interactive call, @var{n} is the numeric prefix argument, -if provided; otherwise @var{n} defaults to @code{nil}. - -@strong{Warning:} Don't use this function in Lisp programs! -@end deffn - -@node Text Lines -@subsection Motion by Text Lines -@cindex lines - - Text lines are portions of the buffer delimited by newline characters, -which are regarded as part of the previous line. The first text line -begins at the beginning of the buffer, and the last text line ends at -the end of the buffer whether or not the last character is a newline. -The division of the buffer into text lines is not affected by the width -of the window, by line continuation in display, or by how tabs and -control characters are displayed. - -@deffn Command beginning-of-line &optional count -This function moves point to the beginning of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the beginning of the line. - -This function does not move point across a field boundary -(@pxref{Fields}) unless doing so would move beyond there to a -different line; therefore, if @var{count} is @code{nil} or 1, and -point starts at a field boundary, point does not move. To ignore -field boundaries, either bind @code{inhibit-field-text-motion} to -@code{t}, or use the @code{forward-line} function instead. For -instance, @code{(forward-line 0)} does the same thing as -@code{(beginning-of-line)}, except that it ignores field boundaries. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@defun line-beginning-position &optional count -Return the position that @code{(beginning-of-line @var{count})} -would move to. -@end defun - -@deffn Command end-of-line &optional count -This function moves point to the end of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the end of the line. - -This function does not move point across a field boundary -(@pxref{Fields}) unless doing so would move beyond there to a -different line; therefore, if @var{count} is @code{nil} or 1, and -point starts at a field boundary, point does not move. To ignore -field boundaries, bind @code{inhibit-field-text-motion} to @code{t}. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@defun line-end-position &optional count -Return the position that @code{(end-of-line @var{count})} -would move to. -@end defun - -@deffn Command forward-line &optional count -@cindex beginning of line -This function moves point forward @var{count} lines, to the beginning of -the line. If @var{count} is negative, it moves point -@minus{}@var{count} lines backward, to the beginning of a line. If -@var{count} is zero, it moves point to the beginning of the current -line. If @var{count} is @code{nil}, that means 1. - -If @code{forward-line} encounters the beginning or end of the buffer (or -of the accessible portion) before finding that many lines, it sets point -there. No error is signaled. - -@code{forward-line} returns the difference between @var{count} and the -number of lines actually moved. If you attempt to move down five lines -from the beginning of a buffer that has only three lines, point stops at -the end of the last line, and the value will be 2. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@defun count-lines start end -@cindex lines in region -@anchor{Definition of count-lines} -This function returns the number of lines between the positions -@var{start} and @var{end} in the current buffer. If @var{start} and -@var{end} are equal, then it returns 0. Otherwise it returns at least -1, even if @var{start} and @var{end} are on the same line. This is -because the text between them, considered in isolation, must contain at -least one line unless it is empty. -@end defun - -@deffn Command count-words start end -@cindex words in region -This function returns the number of words between the positions -@var{start} and @var{end} in the current buffer. - -This function can also be called interactively. In that case, it -prints a message reporting the number of lines, words, and characters -in the buffer, or in the region if the region is active. -@end deffn - -@defun line-number-at-pos &optional pos -@cindex line number -This function returns the line number in the current buffer -corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil} -or omitted, the current buffer position is used. -@end defun - -@ignore -@c ================ -The @code{previous-line} and @code{next-line} commands are functions -that should not be used in programs. They are for users and are -mentioned here only for completeness. - -@deffn Command previous-line count -@cindex goal column -This function moves point up @var{count} lines (down if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} with a negative argument instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@deffn Command next-line count -This function moves point down @var{count} lines (up if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In the case where the @var{count} is 1, and point is on the last -line of the buffer (or clipped region), a new empty line is inserted at the -end of the buffer (or clipped region) and point moved there. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@c ================ -@end ignore - - Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}. -These functions do not move point, but test whether it is already at the -beginning or end of a line. - -@node Screen Lines -@subsection Motion by Screen Lines - - The line functions in the previous section count text lines, delimited -only by newline characters. By contrast, these functions count screen -lines, which are defined by the way the text appears on the screen. A -text line is a single screen line if it is short enough to fit the width -of the selected window, but otherwise it may occupy several screen -lines. - - In some cases, text lines are truncated on the screen rather than -continued onto additional screen lines. In these cases, -@code{vertical-motion} moves point much like @code{forward-line}. -@xref{Truncation}. - - Because the width of a given string depends on the flags that control -the appearance of certain characters, @code{vertical-motion} behaves -differently, for a given piece of text, depending on the buffer it is -in, and even on the selected window (because the width, the truncation -flag, and display table may vary between windows). @xref{Usual -Display}. - - These functions scan text to determine where screen lines break, and -thus take time proportional to the distance scanned. -@ignore -If you intend to use them heavily, Emacs provides caches which may -improve the performance of your code. @xref{Truncation, cache-long-scans}. -@end ignore - -@defun vertical-motion count &optional window -This function moves point to the start of the screen line @var{count} -screen lines down from the screen line containing point. If @var{count} -is negative, it moves up instead. - -The @var{count} argument can be a cons cell, @code{(@var{cols} -. @var{lines})}, instead of an integer. Then the function moves by -@var{lines} screen lines, and puts point @var{cols} columns from the -visual start of that screen line. Note that @var{cols} are counted -from the @emph{visual} start of the line; if the window is scrolled -horizontally (@pxref{Horizontal Scrolling}), the column on which point -will end is in addition to the number of columns by which the text is -scrolled. - -The return value is the number of screen lines over which point was -moved. The value may be less in absolute value than @var{count} if -the beginning or end of the buffer was reached. - -The window @var{window} is used for obtaining parameters such as the -width, the horizontal scrolling, and the display table. But -@code{vertical-motion} always operates on the current buffer, even if -@var{window} currently displays some other buffer. -@end defun - -@defun count-screen-lines &optional beg end count-final-newline window -This function returns the number of screen lines in the text from -@var{beg} to @var{end}. The number of screen lines may be different -from the number of actual lines, due to line continuation, the display -table, etc. If @var{beg} and @var{end} are @code{nil} or omitted, -they default to the beginning and end of the accessible portion of the -buffer. - -If the region ends with a newline, that is ignored unless the optional -third argument @var{count-final-newline} is non-@code{nil}. - -The optional fourth argument @var{window} specifies the window for -obtaining parameters such as width, horizontal scrolling, and so on. -The default is to use the selected window's parameters. - -Like @code{vertical-motion}, @code{count-screen-lines} always uses the -current buffer, regardless of which buffer is displayed in -@var{window}. This makes possible to use @code{count-screen-lines} in -any buffer, whether or not it is currently displayed in some window. -@end defun - -@deffn Command move-to-window-line count -This function moves point with respect to the text currently displayed -in the selected window. It moves point to the beginning of the screen -line @var{count} screen lines from the top of the window. If -@var{count} is negative, that specifies a position -@w{@minus{}@var{count}} lines from the bottom (or the last line of the -buffer, if the buffer ends above the specified screen position). - -If @var{count} is @code{nil}, then point moves to the beginning of the -line in the middle of the window. If the absolute value of @var{count} -is greater than the size of the window, then point moves to the place -that would appear on that screen line if the window were tall enough. -This will probably cause the next redisplay to scroll to bring that -location onto the screen. - -In an interactive call, @var{count} is the numeric prefix argument. - -The value returned is the window line number point has moved to, with -the top line in the window numbered 0. -@end deffn - -@defun compute-motion from frompos to topos width offsets window -This function scans the current buffer, calculating screen positions. -It scans the buffer forward from position @var{from}, assuming that is -at screen coordinates @var{frompos}, to position @var{to} or coordinates -@var{topos}, whichever comes first. It returns the ending buffer -position and screen coordinates. - -The coordinate arguments @var{frompos} and @var{topos} are cons cells of -the form @code{(@var{hpos} . @var{vpos})}. - -The argument @var{width} is the number of columns available to display -text; this affects handling of continuation lines. @code{nil} means -the actual number of usable text columns in the window, which is -equivalent to the value returned by @code{(window-width window)}. - -The argument @var{offsets} is either @code{nil} or a cons cell of the -form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is -the number of columns not being displayed at the left margin; most -callers get this by calling @code{window-hscroll}. Meanwhile, -@var{tab-offset} is the offset between column numbers on the screen and -column numbers in the buffer. This can be nonzero in a continuation -line, when the previous screen lines' widths do not add up to a multiple -of @code{tab-width}. It is always zero in a non-continuation line. - -The window @var{window} serves only to specify which display table to -use. @code{compute-motion} always operates on the current buffer, -regardless of what buffer is displayed in @var{window}. - -The return value is a list of five elements: - -@example -(@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin}) -@end example - -@noindent -Here @var{pos} is the buffer position where the scan stopped, @var{vpos} -is the vertical screen position, and @var{hpos} is the horizontal screen -position. - -The result @var{prevhpos} is the horizontal position one character back -from @var{pos}. The result @var{contin} is @code{t} if the last line -was continued after (or within) the previous character. - -For example, to find the buffer position of column @var{col} of screen line -@var{line} of a certain window, pass the window's display start location -as @var{from} and the window's upper-left coordinates as @var{frompos}. -Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to -the end of the accessible portion of the buffer, and pass @var{line} and -@var{col} as @var{topos}. Here's a function that does this: - -@example -(defun coordinates-of-position (col line) - (car (compute-motion (window-start) - '(0 . 0) - (point-max) - (cons col line) - (window-width) - (cons (window-hscroll) 0) - (selected-window)))) -@end example - -When you use @code{compute-motion} for the minibuffer, you need to use -@code{minibuffer-prompt-width} to get the horizontal position of the -beginning of the first screen line. @xref{Minibuffer Contents}. -@end defun - -@node List Motion -@subsection Moving over Balanced Expressions -@cindex sexp motion -@cindex Lisp expression motion -@cindex list motion -@cindex balanced parenthesis motion - - Here are several functions concerned with balanced-parenthesis -expressions (also called @dfn{sexps} in connection with moving across -them in Emacs). The syntax table controls how these functions interpret -various characters; see @ref{Syntax Tables}. @xref{Parsing -Expressions}, for lower-level primitives for scanning sexps or parts of -sexps. For user-level commands, see @ref{Parentheses,, Commands for -Editing with Parentheses, emacs, The GNU Emacs Manual}. - -@deffn Command forward-list &optional arg -This function moves forward across @var{arg} (default 1) balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command backward-list &optional arg -This function moves backward across @var{arg} (default 1) balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command up-list &optional arg -This function moves forward out of @var{arg} (default 1) levels of parentheses. -A negative argument means move backward but still to a less deep spot. -@end deffn - -@deffn Command down-list &optional arg -This function moves forward into @var{arg} (default 1) levels of -parentheses. A negative argument means move backward but still go -deeper in parentheses (@minus{}@var{arg} levels). -@end deffn - -@deffn Command forward-sexp &optional arg -This function moves forward across @var{arg} (default 1) balanced expressions. -Balanced expressions include both those delimited by parentheses and -other kinds, such as words and string constants. -@xref{Parsing Expressions}. For example, - -@example -@group ----------- Buffer: foo ---------- -(concat@point{} "foo " (car x) y z) ----------- Buffer: foo ---------- -@end group - -@group -(forward-sexp 3) - @result{} nil - ----------- Buffer: foo ---------- -(concat "foo " (car x) y@point{} z) ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command backward-sexp &optional arg -This function moves backward across @var{arg} (default 1) balanced expressions. -@end deffn - -@deffn Command beginning-of-defun &optional arg -This function moves back to the @var{arg}th beginning of a defun. If -@var{arg} is negative, this actually moves forward, but it still moves -to the beginning of a defun, not to the end of one. @var{arg} defaults -to 1. -@end deffn - -@deffn Command end-of-defun &optional arg -This function moves forward to the @var{arg}th end of a defun. If -@var{arg} is negative, this actually moves backward, but it still moves -to the end of a defun, not to the beginning of one. @var{arg} defaults -to 1. -@end deffn - -@defopt defun-prompt-regexp -If non-@code{nil}, this buffer-local variable holds a regular -expression that specifies what text can appear before the -open-parenthesis that starts a defun. That is to say, a defun begins -on a line that starts with a match for this regular expression, -followed by a character with open-parenthesis syntax. -@end defopt - -@defopt open-paren-in-column-0-is-defun-start -If this variable's value is non-@code{nil}, an open parenthesis in -column 0 is considered to be the start of a defun. If it is -@code{nil}, an open parenthesis in column 0 has no special meaning. -The default is @code{t}. -@end defopt - -@defvar beginning-of-defun-function -If non-@code{nil}, this variable holds a function for finding the -beginning of a defun. The function @code{beginning-of-defun} -calls this function instead of using its normal method, passing it its -optional argument. If the argument is non-@code{nil}, the function -should move back by that many functions, like -@code{beginning-of-defun} does. -@end defvar - -@defvar end-of-defun-function -If non-@code{nil}, this variable holds a function for finding the end of -a defun. The function @code{end-of-defun} calls this function instead -of using its normal method. -@end defvar - -@node Skipping Characters -@subsection Skipping Characters -@cindex skipping characters - - The following two functions move point over a specified set of -characters. For example, they are often used to skip whitespace. For -related functions, see @ref{Motion and Syntax}. - -These functions convert the set string to multibyte if the buffer is -multibyte, and they convert it to unibyte if the buffer is unibyte, as -the search functions do (@pxref{Searching and Matching}). - -@defun skip-chars-forward character-set &optional limit -This function moves point in the current buffer forward, skipping over a -given set of characters. It examines the character following point, -then advances point if the character matches @var{character-set}. This -continues until it reaches a character that does not match. The -function returns the number of characters moved over. - -The argument @var{character-set} is a string, like the inside of a -@samp{[@dots{}]} in a regular expression except that @samp{]} does not -terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. -Thus, @code{"a-zA-Z"} skips over all letters, stopping before the -first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before -the first letter. See @xref{Regular Expressions}. Character classes -can also be used, e.g., @code{"[:alnum:]"}. See @pxref{Char Classes}. - -If @var{limit} is supplied (it must be a number or a marker), it -specifies the maximum position in the buffer that point can be skipped -to. Point will stop at or before @var{limit}. - -In the following example, point is initially located directly before the -@samp{T}. After the form is evaluated, point is located at the end of -that line (between the @samp{t} of @samp{hat} and the newline). The -function skips all letters and spaces, but not newlines. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(skip-chars-forward "a-zA-Z ") - @result{} 18 - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end defun - -@defun skip-chars-backward character-set &optional limit -This function moves point backward, skipping characters that match -@var{character-set}, until @var{limit}. It is just like -@code{skip-chars-forward} except for the direction of motion. - -The return value indicates the distance traveled. It is an integer that -is zero or less. -@end defun - -@node Excursions -@section Excursions -@cindex excursion - - It is often useful to move point ``temporarily'' within a localized -portion of the program. This is called an @dfn{excursion}, and it is -done with the @code{save-excursion} special form. This construct -remembers the initial identity of the current buffer, and its values -of point and the mark, and restores them after the excursion -completes. It is the standard way to move point within one part of a -program and avoid affecting the rest of the program, and is used -thousands of times in the Lisp sources of Emacs. - - If you only need to save and restore the identity of the current -buffer, use @code{save-current-buffer} or @code{with-current-buffer} -instead (@pxref{Current Buffer}). If you need to save or restore -window configurations, see the forms described in @ref{Window -Configurations} and in @ref{Frame Configurations}. @c frameset? - -@defspec save-excursion body@dots{} -@cindex mark excursion -@cindex point excursion -This special form saves the identity of the current buffer and the -values of point and the mark in it, evaluates @var{body}, and finally -restores the buffer and its saved values of point and the mark. All -three saved values are restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -The value returned by @code{save-excursion} is the result of the last -form in @var{body}, or @code{nil} if no body forms were given. -@end defspec - - Because @code{save-excursion} only saves point and mark for the -buffer that was current at the start of the excursion, any changes -made to point and/or mark in other buffers, during the excursion, will -remain in effect afterward. This frequently leads to unintended -consequences, so the byte compiler warns if you call @code{set-buffer} -during an excursion: - -@example -Warning: Use `with-current-buffer' rather than - save-excursion+set-buffer -@end example - -@noindent -To avoid such problems, you should call @code{save-excursion} only -after setting the desired current buffer, as in the following example: - -@example -@group -(defun append-string-to-buffer (string buffer) - "Append STRING to the end of BUFFER." - (with-current-buffer buffer - (save-excursion - (goto-char (point-max)) - (insert string)))) -@end group -@end example - -@cindex window excursions - Likewise, @code{save-excursion} does not restore window-buffer -correspondences altered by functions such as @code{switch-to-buffer}. - - @strong{Warning:} Ordinary insertion of text adjacent to the saved -point value relocates the saved value, just as it relocates all -markers. More precisely, the saved value is a marker with insertion -type @code{nil}. @xref{Marker Insertion Types}. Therefore, when the -saved point value is restored, it normally comes before the inserted -text. - - Although @code{save-excursion} saves the location of the mark, it does -not prevent functions which modify the buffer from setting -@code{deactivate-mark}, and thus causing the deactivation of the mark -after the command finishes. @xref{The Mark}. - -@node Narrowing -@section Narrowing -@cindex narrowing -@cindex restriction (in a buffer) -@cindex accessible portion (of a buffer) - - @dfn{Narrowing} means limiting the text addressable by Emacs editing -commands to a limited range of characters in a buffer. The text that -remains addressable is called the @dfn{accessible portion} of the -buffer. - - Narrowing is specified with two buffer positions, which become the -beginning and end of the accessible portion. For most editing -commands and primitives, these positions replace the values of the -beginning and end of the buffer. While narrowing is in effect, no -text outside the accessible portion is displayed, and point cannot -move outside the accessible portion. Note that narrowing does not -alter actual buffer positions (@pxref{Point}); it only determines -which positions are considered the accessible portion of the buffer. -Most functions refuse to operate on text that is outside the -accessible portion. - - Commands for saving buffers are unaffected by narrowing; they save -the entire buffer regardless of any narrowing. - - If you need to display in a single buffer several very different -types of text, consider using an alternative facility described in -@ref{Swapping Text}. - -@deffn Command narrow-to-region start end -This function sets the accessible portion of the current buffer to start -at @var{start} and end at @var{end}. Both arguments should be character -positions. - -In an interactive call, @var{start} and @var{end} are set to the bounds -of the current region (point and the mark, with the smallest first). -@end deffn - -@deffn Command narrow-to-page &optional move-count -This function sets the accessible portion of the current buffer to -include just the current page. An optional first argument -@var{move-count} non-@code{nil} means to move forward or backward by -@var{move-count} pages and then narrow to one page. The variable -@code{page-delimiter} specifies where pages start and end -(@pxref{Standard Regexps}). - -In an interactive call, @var{move-count} is set to the numeric prefix -argument. -@end deffn - -@deffn Command widen -@cindex widening -This function cancels any narrowing in the current buffer, so that the -entire contents are accessible. This is called @dfn{widening}. -It is equivalent to the following expression: - -@example -(narrow-to-region 1 (1+ (buffer-size))) -@end example -@end deffn - -@defun buffer-narrowed-p -This function returns non-@code{nil} if the buffer is narrowed, and -@code{nil} otherwise. -@end defun - -@defspec save-restriction body@dots{} -This special form saves the current bounds of the accessible portion, -evaluates the @var{body} forms, and finally restores the saved bounds, -thus restoring the same state of narrowing (or absence thereof) formerly -in effect. The state of narrowing is restored even in the event of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). -Therefore, this construct is a clean way to narrow a buffer temporarily. - -The value returned by @code{save-restriction} is that returned by the -last form in @var{body}, or @code{nil} if no body forms were given. - -@c Wordy to avoid overfull hbox. --rjc 16mar92 -@strong{Caution:} it is easy to make a mistake when using the -@code{save-restriction} construct. Read the entire description here -before you try it. - -If @var{body} changes the current buffer, @code{save-restriction} still -restores the restrictions on the original buffer (the buffer whose -restrictions it saved from), but it does not restore the identity of the -current buffer. - -@code{save-restriction} does @emph{not} restore point and the mark; use -@code{save-excursion} for that. If you use both @code{save-restriction} -and @code{save-excursion} together, @code{save-excursion} should come -first (on the outside). Otherwise, the old point value would be -restored with temporary narrowing still in effect. If the old point -value were outside the limits of the temporary narrowing, this would -fail to restore it accurately. - -Here is a simple example of correct use of @code{save-restriction}: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo -This is the contents of foo -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group - -@group -(save-excursion - (save-restriction - (goto-char 1) - (forward-line 2) - (narrow-to-region 1 (point)) - (goto-char (point-min)) - (replace-string "foo" "bar"))) - ----------- Buffer: foo ---------- -This is the contents of bar -This is the contents of bar -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group -@end example -@end defspec diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi deleted file mode 100644 index c91afdffdeb..00000000000 --- a/doc/lispref/processes.texi +++ /dev/null @@ -1,3127 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Processes -@chapter Processes -@cindex child process -@cindex parent process -@cindex subprocess -@cindex process - - In the terminology of operating systems, a @dfn{process} is a space in -which a program can execute. Emacs runs in a process. Emacs Lisp -programs can invoke other programs in processes of their own. These are -called @dfn{subprocesses} or @dfn{child processes} of the Emacs process, -which is their @dfn{parent process}. - - A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous}, -depending on how it is created. When you create a synchronous -subprocess, the Lisp program waits for the subprocess to terminate -before continuing execution. When you create an asynchronous -subprocess, it can run in parallel with the Lisp program. This kind of -subprocess is represented within Emacs by a Lisp object which is also -called a ``process''. Lisp programs can use this object to communicate -with the subprocess or to control it. For example, you can send -signals, obtain status information, receive output from the process, or -send input to it. - -@defun processp object -This function returns @code{t} if @var{object} represents an Emacs -subprocess, @code{nil} otherwise. -@end defun - - In addition to subprocesses of the current Emacs session, you can -also access other processes running on your machine. @xref{System -Processes}. - -@menu -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for net connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. -@end menu - -@node Subprocess Creation -@section Functions that Create Subprocesses - - There are three primitives that create a new subprocess in which to run -a program. One of them, @code{start-process}, creates an asynchronous -process and returns a process object (@pxref{Asynchronous Processes}). -The other two, @code{call-process} and @code{call-process-region}, -create a synchronous process and do not return a process object -(@pxref{Synchronous Processes}). There are various higher-level -functions that make use of these primitives to run particular types of -process. - - Synchronous and asynchronous processes are explained in the following -sections. Since the three functions are all called in a similar -fashion, their common arguments are described here. - -@cindex execute program -@cindex @env{PATH} environment variable -@cindex @env{HOME} environment variable - In all cases, the function's @var{program} argument specifies the -program to be run. An error is signaled if the file is not found or -cannot be executed. If the file name is relative, the variable -@code{exec-path} contains a list of directories to search. Emacs -initializes @code{exec-path} when it starts up, based on the value of -the environment variable @env{PATH}. The standard file name -constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as -usual in @code{exec-path}, but environment variable substitutions -(@samp{$HOME}, etc.)@: are not recognized; use -@code{substitute-in-file-name} to perform them (@pxref{File Name -Expansion}). @code{nil} in this list refers to -@code{default-directory}. - - Executing a program can also try adding suffixes to the specified -name: - -@defopt exec-suffixes -This variable is a list of suffixes (strings) to try adding to the -specified program file name. The list should include @code{""} if you -want the name to be tried exactly as specified. The default value is -system-dependent. -@end defopt - - @strong{Please note:} The argument @var{program} contains only the -name of the program; it may not contain any command-line arguments. You -must use a separate argument, @var{args}, to provide those, as -described below. - - Each of the subprocess-creating functions has a @var{buffer-or-name} -argument that specifies where the standard output from the program will -go. It should be a buffer or a buffer name; if it is a buffer name, -that will create the buffer if it does not already exist. It can also -be @code{nil}, which says to discard the output, unless a custom filter function -handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) -Normally, you should avoid having multiple processes send output to the -same buffer because their output would be intermixed randomly. -For synchronous processes, you can send the output to a file instead -of a buffer. - -@cindex program arguments - All three of the subprocess-creating functions have a @code{&rest} -argument, @var{args}. The @var{args} must all be strings, and they are -supplied to @var{program} as separate command line arguments. Wildcard -characters and other shell constructs have no special meanings in these -strings, since the strings are passed directly to the specified program. - -@cindex environment variables, subprocesses - The subprocess inherits its environment from Emacs, but you can -specify overrides for it with @code{process-environment}. @xref{System -Environment}. The subprocess gets its current directory from the -value of @code{default-directory}. - -@defvar exec-directory -@pindex movemail -The value of this variable is a string, the name of a directory that -contains programs that come with GNU Emacs and are intended for Emacs -to invoke. The program @code{movemail} is an example of such a program; -Rmail uses it to fetch new mail from an inbox. -@end defvar - -@defopt exec-path -The value of this variable is a list of directories to search for -programs to run in subprocesses. Each element is either the name of a -directory (i.e., a string), or @code{nil}, which stands for the default -directory (which is the value of @code{default-directory}). -@cindex program directories - -The value of @code{exec-path} is used by @code{call-process} and -@code{start-process} when the @var{program} argument is not an absolute -file name. - -Generally, you should not modify @code{exec-path} directly. Instead, -ensure that your @env{PATH} environment variable is set appropriately -before starting Emacs. Trying to modify @code{exec-path} -independently of @env{PATH} can lead to confusing results. -@end defopt - -@node Shell Arguments -@section Shell Arguments -@cindex arguments for shell commands -@cindex shell command arguments - - Lisp programs sometimes need to run a shell and give it a command -that contains file names that were specified by the user. These -programs ought to be able to support any valid file name. But the shell -gives special treatment to certain characters, and if these characters -occur in the file name, they will confuse the shell. To handle these -characters, use the function @code{shell-quote-argument}: - -@defun shell-quote-argument argument -This function returns a string that represents, in shell syntax, -an argument whose actual contents are @var{argument}. It should -work reliably to concatenate the return value into a shell command -and then pass it to a shell for execution. - -Precisely what this function does depends on your operating system. The -function is designed to work with the syntax of your system's standard -shell; if you use an unusual shell, you will need to redefine this -function. - -@example -;; @r{This example shows the behavior on GNU and Unix systems.} -(shell-quote-argument "foo > bar") - @result{} "foo\\ \\>\\ bar" - -;; @r{This example shows the behavior on MS-DOS and MS-Windows.} -(shell-quote-argument "foo > bar") - @result{} "\"foo > bar\"" -@end example - -Here's an example of using @code{shell-quote-argument} to construct -a shell command: - -@example -(concat "diff -c " - (shell-quote-argument oldfile) - " " - (shell-quote-argument newfile)) -@end example -@end defun - -@cindex quoting and unquoting command-line arguments -@cindex minibuffer input, and command-line arguments -@cindex @code{call-process}, command-line arguments from minibuffer -@cindex @code{start-process}, command-line arguments from minibuffer - The following two functions are useful for combining a list of -individual command-line argument strings into a single string, and -taking a string apart into a list of individual command-line -arguments. These functions are mainly intended for -converting user input in the minibuffer, a Lisp string, into a list of -string arguments to be passed to @code{call-process} or -@code{start-process}, or for converting such lists of arguments into -a single Lisp string to be presented in the minibuffer or echo area. - -@defun split-string-and-unquote string &optional separators -This function splits @var{string} into substrings at matches for the -regular expression @var{separators}, like @code{split-string} does -(@pxref{Creating Strings}); in addition, it removes quoting from the -substrings. It then makes a list of the substrings and returns it. - -If @var{separators} is omitted or @code{nil}, it defaults to -@code{"\\s-+"}, which is a regular expression that matches one or more -characters with whitespace syntax (@pxref{Syntax Class Table}). - -This function supports two types of quoting: enclosing a whole string -in double quotes @code{"@dots{}"}, and quoting individual characters -with a backslash escape @samp{\}. The latter is also used in Lisp -strings, so this function can handle those as well. -@end defun - -@defun combine-and-quote-strings list-of-strings &optional separator -This function concatenates @var{list-of-strings} into a single string, -quoting each string as necessary. It also sticks the @var{separator} -string between each pair of strings; if @var{separator} is omitted or -@code{nil}, it defaults to @code{" "}. The return value is the -resulting string. - -The strings in @var{list-of-strings} that need quoting are those that -include @var{separator} as their substring. Quoting a string encloses -it in double quotes @code{"@dots{}"}. In the simplest case, if you -are consing a command from the individual command-line arguments, -every argument that includes embedded blanks will be quoted. -@end defun - -@node Synchronous Processes -@section Creating a Synchronous Process -@cindex synchronous subprocess - - After a @dfn{synchronous process} is created, Emacs waits for the -process to terminate before continuing. Starting Dired on GNU or -Unix@footnote{On other systems, Emacs uses a Lisp emulation of -@code{ls}; see @ref{Contents of Directories}.} is an example of this: it -runs @code{ls} in a synchronous process, then modifies the output -slightly. Because the process is synchronous, the entire directory -listing arrives in the buffer before Emacs tries to do anything with it. - - While Emacs waits for the synchronous subprocess to terminate, the -user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill -the subprocess with a @code{SIGINT} signal; but it waits until the -subprocess actually terminates before quitting. If during that time the -user types another @kbd{C-g}, that kills the subprocess instantly with -@code{SIGKILL} and quits immediately (except on MS-DOS, where killing -other processes doesn't work). @xref{Quitting}. - - The synchronous subprocess functions return an indication of how the -process terminated. - - The output from a synchronous subprocess is generally decoded using a -coding system, much like text read from a file. The input sent to a -subprocess by @code{call-process-region} is encoded using a coding -system, much like text written into a file. @xref{Coding Systems}. - -@defun call-process program &optional infile destination display &rest args -This function calls @var{program} and waits for it to finish. - -The current working directory of the subprocess is -@code{default-directory}. - -The standard input for the new process comes from file @var{infile} if -@var{infile} is not @code{nil}, and from the null device otherwise. -The argument @var{destination} says where to put the process output. -Here are the possibilities: - -@table @asis -@item a buffer -Insert the output in that buffer, before point. This includes both the -standard output stream and the standard error stream of the process. - -@item a string -Insert the output in a buffer with that name, before point. - -@item @code{t} -Insert the output in the current buffer, before point. - -@item @code{nil} -Discard the output. - -@item 0 -Discard the output, and return @code{nil} immediately without waiting -for the subprocess to finish. - -In this case, the process is not truly synchronous, since it can run in -parallel with Emacs; but you can think of it as synchronous in that -Emacs is essentially finished with the subprocess as soon as this -function returns. - -MS-DOS doesn't support asynchronous subprocesses, so this option doesn't -work there. - -@item @code{(:file @var{file-name})} -Send the output to the file name specified, overwriting it if it -already exists. - -@item @code{(@var{real-destination} @var{error-destination})} -Keep the standard output stream separate from the standard error stream; -deal with the ordinary output as specified by @var{real-destination}, -and dispose of the error output according to @var{error-destination}. -If @var{error-destination} is @code{nil}, that means to discard the -error output, @code{t} means mix it with the ordinary output, and a -string specifies a file name to redirect error output into. - -You can't directly specify a buffer to put the error output in; that is -too difficult to implement. But you can achieve this result by sending -the error output to a temporary file and then inserting the file into a -buffer. -@end table - -If @var{display} is non-@code{nil}, then @code{call-process} redisplays -the buffer as output is inserted. (However, if the coding system chosen -for decoding output is @code{undecided}, meaning deduce the encoding -from the actual data, then redisplay sometimes cannot continue once -non-@acronym{ASCII} characters are encountered. There are fundamental -reasons why it is hard to fix this; see @ref{Output from Processes}.) - -Otherwise the function @code{call-process} does no redisplay, and the -results become visible on the screen only when Emacs redisplays that -buffer in the normal course of events. - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -The value returned by @code{call-process} (unless you told it not to -wait) indicates the reason for process termination. A number gives the -exit status of the subprocess; 0 means success, and any other value -means failure. If the process terminated with a signal, -@code{call-process} returns a string describing the signal. - -In the examples below, the buffer @samp{foo} is current. - -@smallexample -@group -(call-process "pwd" nil t) - @result{} 0 - ----------- Buffer: foo ---------- -/home/lewis/manual ----------- Buffer: foo ---------- -@end group - -@group -(call-process "grep" nil "bar" nil "lewis" "/etc/passwd") - @result{} 0 - ----------- Buffer: bar ---------- -lewis:x:1001:1001:Bil Lewis,,,,:/home/lewis:/bin/bash - ----------- Buffer: bar ---------- -@end group -@end smallexample - -Here is an example of the use of @code{call-process}, as used to -be found in the definition of the @code{insert-directory} function: - -@smallexample -@group -(call-process insert-directory-program nil t nil switches - (if full-directory-p - (concat (file-name-as-directory file) ".") - file)) -@end group -@end smallexample -@end defun - -@defun process-file program &optional infile buffer display &rest args -This function processes files synchronously in a separate process. It -is similar to @code{call-process}, but may invoke a file handler based -on the value of the variable @code{default-directory}, which specifies -the current working directory of the subprocess. - -The arguments are handled in almost the same way as for -@code{call-process}, with the following differences: - -Some file handlers may not support all combinations and forms of the -arguments @var{infile}, @var{buffer}, and @var{display}. For example, -some file handlers might behave as if @var{display} were @code{nil}, -regardless of the value actually passed. As another example, some -file handlers might not support separating standard output and error -output by way of the @var{buffer} argument. - -If a file handler is invoked, it determines the program to run based -on the first argument @var{program}. For instance, suppose that a -handler for remote files is invoked. Then the path that is used for -searching for the program might be different from @code{exec-path}. - -The second argument @var{infile} may invoke a file handler. The file -handler could be different from the handler chosen for the -@code{process-file} function itself. (For example, -@code{default-directory} could be on one remote host, and -@var{infile} on a different remote host. Or @code{default-directory} -could be non-special, whereas @var{infile} is on a remote host.) - -If @var{buffer} is a list of the form @code{(@var{real-destination} -@var{error-destination})}, and @var{error-destination} names a file, -then the same remarks as for @var{infile} apply. - -The remaining arguments (@var{args}) will be passed to the process -verbatim. Emacs is not involved in processing file names that are -present in @var{args}. To avoid confusion, it may be best to avoid -absolute file names in @var{args}, but rather to specify all file -names as relative to @code{default-directory}. The function -@code{file-relative-name} is useful for constructing such relative -file names. -@end defun - -@defvar process-file-side-effects -This variable indicates whether a call of @code{process-file} changes -remote files. - -By default, this variable is always set to @code{t}, meaning that a -call of @code{process-file} could potentially change any file on a -remote host. When set to @code{nil}, a file handler could optimize -its behavior with respect to remote file attribute caching. - -You should only ever change this variable with a let-binding; never -with @code{setq}. -@end defvar - -@defun call-process-region start end program &optional delete destination display &rest args -This function sends the text from @var{start} to @var{end} as -standard input to a process running @var{program}. It deletes the text -sent if @var{delete} is non-@code{nil}; this is useful when -@var{destination} is @code{t}, to insert the output in the current -buffer in place of the input. - -The arguments @var{destination} and @var{display} control what to do -with the output from the subprocess, and whether to update the display -as it comes in. For details, see the description of -@code{call-process}, above. If @var{destination} is the integer 0, -@code{call-process-region} discards the output and returns @code{nil} -immediately, without waiting for the subprocess to finish (this only -works if asynchronous subprocesses are supported; i.e., not on MS-DOS). - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -The return value of @code{call-process-region} is just like that of -@code{call-process}: @code{nil} if you told it to return without -waiting; otherwise, a number or string which indicates how the -subprocess terminated. - -In the following example, we use @code{call-process-region} to run the -@code{cat} utility, with standard input being the first five characters -in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its -standard input into its standard output. Since the argument -@var{destination} is @code{t}, this output is inserted in the current -buffer. - -@smallexample -@group ----------- Buffer: foo ---------- -input@point{} ----------- Buffer: foo ---------- -@end group - -@group -(call-process-region 1 6 "cat" nil t) - @result{} 0 - ----------- Buffer: foo ---------- -inputinput@point{} ----------- Buffer: foo ---------- -@end group -@end smallexample - - For example, the @code{shell-command-on-region} command uses -@code{call-process-region} in a manner similar to this: - -@smallexample -@group -(call-process-region - start end - shell-file-name ; @r{name of program} - nil ; @r{do not delete region} - buffer ; @r{send output to @code{buffer}} - nil ; @r{no redisplay during output} - "-c" command) ; @r{arguments for the shell} -@end group -@end smallexample -@c It actually uses shell-command-switch, but no need to mention that here. -@end defun - -@defun call-process-shell-command command &optional infile destination display &rest args -This function executes the shell command @var{command} synchronously. -The final arguments @var{args} are additional arguments to add at the -end of @var{command}. The other arguments are handled as in -@code{call-process}. -@end defun - -@defun process-file-shell-command command &optional infile destination display &rest args -This function is like @code{call-process-shell-command}, but uses -@code{process-file} internally. Depending on @code{default-directory}, -@var{command} can be executed also on remote hosts. -@end defun - -@defun shell-command-to-string command -This function executes @var{command} (a string) as a shell command, -then returns the command's output as a string. -@end defun - -@c There is also shell-command-on-region, but that is more of a user -@c command, not something to use in programs. - -@defun process-lines program &rest args -This function runs @var{program}, waits for it to finish, and returns -its output as a list of strings. Each string in the list holds a -single line of text output by the program; the end-of-line characters -are stripped from each line. The arguments beyond @var{program}, -@var{args}, are strings that specify command-line arguments with which -to run the program. - -If @var{program} exits with a non-zero exit status, this function -signals an error. - -This function works by calling @code{call-process}, so program output -is decoded in the same way as for @code{call-process}. -@end defun - -@node Asynchronous Processes -@section Creating an Asynchronous Process -@cindex asynchronous subprocess - - In this section, we describe how to create an @dfn{asynchronous -process}. After an asynchronous process is created, it runs in -parallel with Emacs, and Emacs can communicate with it using the -functions described in the following sections (@pxref{Input to -Processes}, and @pxref{Output from Processes}). Note that process -communication is only partially asynchronous: Emacs sends data to the -process only when certain functions are called, and Emacs accepts data -from the process only while waiting for input or for a time delay. - -@cindex pty -@cindex pipe - An asynchronous process is controlled either via a @dfn{pty} -(pseudo-terminal) or a @dfn{pipe}. The choice of pty or pipe is made -when creating the process, based on the value of the variable -@code{process-connection-type} (see below). Ptys are usually -preferable for processes visible to the user, as in Shell mode, -because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.)@: -between the process and its children, whereas pipes do not. For -subprocesses used for internal purposes by programs, it is often -better to use a pipe, because they are more efficient, and because -they are immune to stray character injections that ptys introduce for -large (around 500 byte) messages. Also, the total number of ptys is -limited on many systems and it is good not to waste them. - -@defun start-process name buffer-or-name program &rest args -This function creates a new asynchronous subprocess and starts the -program @var{program} running in it. It returns a process object that -stands for the new subprocess in Lisp. The argument @var{name} -specifies the name for the process object; if a process with this name -already exists, then @var{name} is modified (by appending @samp{<1>}, -etc.)@: to be unique. The buffer @var{buffer-or-name} is the buffer to -associate with the process. - -If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty) -and associates its input and output with @var{buffer-or-name}, without -creating a subprocess. In that case, the remaining arguments -@var{args} are ignored. - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the subprocess. - -In the example below, the first process is started and runs (rather, -sleeps) for 100 seconds (the output buffer @samp{foo} is created -immediately). Meanwhile, the second process is started, and -given the name @samp{my-process<1>} for the sake of uniqueness. It -inserts the directory listing at the end of the buffer @samp{foo}, -before the first process finishes. Then it finishes, and a message to -that effect is inserted in the buffer. Much later, the first process -finishes, and another message is inserted in the buffer for it. - -@smallexample -@group -(start-process "my-process" "foo" "sleep" "100") - @result{} # -@end group - -@group -(start-process "my-process" "foo" "ls" "-l" "/bin") - @result{} #> - ----------- Buffer: foo ---------- -total 8336 --rwxr-xr-x 1 root root 971384 Mar 30 10:14 bash --rwxr-xr-x 1 root root 146920 Jul 5 2011 bsd-csh -@dots{} --rwxr-xr-x 1 root root 696880 Feb 28 15:55 zsh4 - -Process my-process<1> finished - -Process my-process finished ----------- Buffer: foo ---------- -@end group -@end smallexample -@end defun - -@defun start-file-process name buffer-or-name program &rest args -Like @code{start-process}, this function starts a new asynchronous -subprocess running @var{program} in it, and returns its process -object. - -The difference from @code{start-process} is that this function may -invoked a file handler based on the value of @code{default-directory}. -This handler ought to run @var{program}, perhaps on the local host, -perhaps on a remote host that corresponds to @code{default-directory}. -In the latter case, the local part of @code{default-directory} becomes -the working directory of the process. - -This function does not try to invoke file name handlers for -@var{program} or for the @var{program-args}. - -Depending on the implementation of the file handler, it might not be -possible to apply @code{process-filter} or @code{process-sentinel} to -the resulting process object. @xref{Filter Functions}, and @ref{Sentinels}. - -@c FIXME Can we find a better example (i.e., a more modern function -@c that is actually documented). -Some file handlers may not support @code{start-file-process} (for -example the function @code{ange-ftp-hook-function}). In such cases, -this function does nothing and returns @code{nil}. -@end defun - -@defun start-process-shell-command name buffer-or-name command -This function is like @code{start-process}, except that it uses a shell -to execute the specified command. The argument @var{command} is a shell -command name. The variable @code{shell-file-name} specifies which shell to -use. - -The point of running a program through the shell, rather than directly -with @code{start-process}, is so that you can employ shell features such -as wildcards in the arguments. It follows that if you include any -arbitrary user-specified arguments in the command, you should quote them -with @code{shell-quote-argument} first, so that any special shell -characters do @emph{not} have their special shell meanings. @xref{Shell -Arguments}. Of course, when executing commands based on user input -you should also consider the security implications. -@end defun - -@defun start-file-process-shell-command name buffer-or-name command -This function is like @code{start-process-shell-command}, but uses -@code{start-file-process} internally. Because of this, @var{command} -can also be executed on remote hosts, depending on @code{default-directory}. -@end defun - -@defvar process-connection-type -This variable controls the type of device used to communicate with -asynchronous subprocesses. If it is non-@code{nil}, then ptys are -used, when available. Otherwise, pipes are used. - -The value of @code{process-connection-type} takes effect when -@code{start-process} is called. So you can specify how to communicate -with one subprocess by binding the variable around the call to -@code{start-process}. - -@smallexample -@group -(let ((process-connection-type nil)) ; @r{use a pipe} - (start-process @dots{})) -@end group -@end smallexample - -To determine whether a given subprocess actually got a pipe or a pty, -use the function @code{process-tty-name} (@pxref{Process -Information}). -@end defvar - -@node Deleting Processes -@section Deleting Processes -@cindex deleting processes - - @dfn{Deleting a process} disconnects Emacs immediately from the -subprocess. Processes are deleted automatically after they terminate, -but not necessarily right away. You can delete a process explicitly -at any time. If you explicitly delete a terminated process before it -is deleted automatically, no harm results. Deleting a running -process sends a signal to terminate it (and its child processes, if -any), and calls the process sentinel. @xref{Sentinels}. - - When a process is deleted, the process object itself continues to -exist as long as other Lisp objects point to it. All the Lisp -primitives that work on process objects accept deleted processes, but -those that do I/O or send signals will report an error. The process -mark continues to point to the same place as before, usually into a -buffer where output from the process was being inserted. - -@defopt delete-exited-processes -This variable controls automatic deletion of processes that have -terminated (due to calling @code{exit} or to a signal). If it is -@code{nil}, then they continue to exist until the user runs -@code{list-processes}. Otherwise, they are deleted immediately after -they exit. -@end defopt - -@defun delete-process process -This function deletes a process, killing it with a @code{SIGKILL} -signal. The argument may be a process, the name of a process, a -buffer, or the name of a buffer. (A buffer or buffer-name stands for -the process that @code{get-buffer-process} returns.) Calling -@code{delete-process} on a running process terminates it, updates the -process status, and runs the sentinel immediately. If the -process has already terminated, calling @code{delete-process} has no -effect on its status, or on the running of its sentinel (which will -happen sooner or later). - -@smallexample -@group -(delete-process "*shell*") - @result{} nil -@end group -@end smallexample -@end defun - -@node Process Information -@section Process Information - - Several functions return information about processes. - -@deffn Command list-processes &optional query-only buffer -This command displays a listing of all living processes. In addition, -it finally deletes any process whose status was @samp{Exited} or -@samp{Signaled}. It returns @code{nil}. - -The processes are shown in a buffer named @file{*Process List*} -(unless you specify otherwise using the optional argument @var{buffer}), -whose major mode is Process Menu mode. - -If @var{query-only} is non-@code{nil}, it only lists processes -whose query flag is non-@code{nil}. @xref{Query Before Exit}. -@end deffn - -@defun process-list -This function returns a list of all processes that have not been deleted. - -@smallexample -@group -(process-list) - @result{} (# #) -@end group -@end smallexample -@end defun - -@defun get-process name -This function returns the process named @var{name} (a string), or -@code{nil} if there is none. - -@smallexample -@group -(get-process "shell") - @result{} # -@end group -@end smallexample -@end defun - -@defun process-command process -This function returns the command that was executed to start -@var{process}. This is a list of strings, the first string being the -program executed and the rest of the strings being the arguments that -were given to the program. - -@smallexample -@group -(process-command (get-process "shell")) - @result{} ("bash" "-i") -@end group -@end smallexample -@end defun - -@defun process-contact process &optional key - -This function returns information about how a network or serial -process was set up. When @var{key} is @code{nil}, it returns -@code{(@var{hostname} @var{service})} for a network process, and -@code{(@var{port} @var{speed})} for a serial process. -For an ordinary child process, this function always returns @code{t}. - -If @var{key} is @code{t}, the value is the complete status information -for the connection, server, or serial port; that is, the list of -keywords and values specified in @code{make-network-process} or -@code{make-serial-process}, except that some of the values represent -the current status instead of what you specified. - -For a network process, the values include (see -@code{make-network-process} for a complete list): - -@table @code -@item :buffer -The associated value is the process buffer. -@item :filter -The associated value is the process filter function. -@item :sentinel -The associated value is the process sentinel function. -@item :remote -In a connection, the address in internal format of the remote peer. -@item :local -The local address, in internal format. -@item :service -In a server, if you specified @code{t} for @var{service}, -this value is the actual port number. -@end table - -@code{:local} and @code{:remote} are included even if they were not -specified explicitly in @code{make-network-process}. - -For a serial process, see @code{make-serial-process} and -@code{serial-process-configure} for a list of keys. - -If @var{key} is a keyword, the function returns the value corresponding -to that keyword. -@end defun - -@defun process-id process -This function returns the @acronym{PID} of @var{process}. This is an -integer that distinguishes the process @var{process} from all other -processes running on the same computer at the current time. The -@acronym{PID} of a process is chosen by the operating system kernel when the -process is started and remains constant as long as the process exists. -@end defun - -@defun process-name process -This function returns the name of @var{process}, as a string. -@end defun - -@defun process-status process-name -This function returns the status of @var{process-name} as a symbol. -The argument @var{process-name} must be a process, a buffer, or a -process name (a string). - -The possible values for an actual subprocess are: - -@table @code -@item run -for a process that is running. -@item stop -for a process that is stopped but continuable. -@item exit -for a process that has exited. -@item signal -for a process that has received a fatal signal. -@item open -for a network connection that is open. -@item closed -for a network connection that is closed. Once a connection -is closed, you cannot reopen it, though you might be able to open -a new connection to the same place. -@item connect -for a non-blocking connection that is waiting to complete. -@item failed -for a non-blocking connection that has failed to complete. -@item listen -for a network server that is listening. -@item nil -if @var{process-name} is not the name of an existing process. -@end table - -@smallexample -@group -(process-status (get-buffer "*shell*")) - @result{} run -@end group -@end smallexample - -For a network connection, @code{process-status} returns one of the symbols -@code{open} or @code{closed}. The latter means that the other side -closed the connection, or Emacs did @code{delete-process}. -@end defun - -@defun process-live-p process -This function returns non-@code{nil} if @var{process} is alive. A -process is considered alive if its status is @code{run}, @code{open}, -@code{listen}, @code{connect} or @code{stop}. -@end defun - -@defun process-type process -This function returns the symbol @code{network} for a network -connection or server, @code{serial} for a serial port connection, or -@code{real} for a real subprocess. -@end defun - -@defun process-exit-status process -This function returns the exit status of @var{process} or the signal -number that killed it. (Use the result of @code{process-status} to -determine which of those it is.) If @var{process} has not yet -terminated, the value is 0. -@end defun - -@defun process-tty-name process -This function returns the terminal name that @var{process} is using for -its communication with Emacs---or @code{nil} if it is using pipes -instead of a terminal (see @code{process-connection-type} in -@ref{Asynchronous Processes}). If @var{process} represents a program -running on a remote host, the terminal name used by that program on -the remote host is provided as process property @code{remote-tty}. -@end defun - -@defun process-coding-system process -@anchor{Coding systems for a subprocess} -This function returns a cons cell @code{(@var{decode} . @var{encode})}, -describing the coding systems in use for decoding output from, and -encoding input to, @var{process} (@pxref{Coding Systems}). -@end defun - -@defun set-process-coding-system process &optional decoding-system encoding-system -This function specifies the coding systems to use for subsequent output -from and input to @var{process}. It will use @var{decoding-system} to -decode subprocess output, and @var{encoding-system} to encode subprocess -input. -@end defun - - Every process also has a property list that you can use to store -miscellaneous values associated with the process. - -@defun process-get process propname -This function returns the value of the @var{propname} property -of @var{process}. -@end defun - -@defun process-put process propname value -This function sets the value of the @var{propname} property -of @var{process} to @var{value}. -@end defun - -@defun process-plist process -This function returns the process plist of @var{process}. -@end defun - -@defun set-process-plist process plist -This function sets the process plist of @var{process} to @var{plist}. -@end defun - -@node Input to Processes -@section Sending Input to Processes -@cindex process input - - Asynchronous subprocesses receive input when it is sent to them by -Emacs, which is done with the functions in this section. You must -specify the process to send input to, and the input data to send. The -data appears on the ``standard input'' of the subprocess. - -@c FIXME which? - Some operating systems have limited space for buffered input in a -pty. On these systems, Emacs sends an @acronym{EOF} periodically -amidst the other characters, to force them through. For most -programs, these @acronym{EOF}s do no harm. - - Subprocess input is normally encoded using a coding system before the -subprocess receives it, much like text written into a file. You can use -@code{set-process-coding-system} to specify which coding system to use -(@pxref{Process Information}). Otherwise, the coding system comes from -@code{coding-system-for-write}, if that is non-@code{nil}; or else from -the defaulting mechanism (@pxref{Default Coding Systems}). - - Sometimes the system is unable to accept input for that process, -because the input buffer is full. When this happens, the send functions -wait a short while, accepting output from subprocesses, and then try -again. This gives the subprocess a chance to read more of its pending -input and make space in the buffer. It also allows filters, sentinels -and timers to run---so take account of that in writing your code. - - In these functions, the @var{process} argument can be a process or -the name of a process, or a buffer or buffer name (which stands -for a process via @code{get-buffer-process}). @code{nil} means -the current buffer's process. - -@defun process-send-string process string -This function sends @var{process} the contents of @var{string} as -standard input. It returns @code{nil}. For example, to make a -Shell buffer list files: - -@smallexample -@group -(process-send-string "shell<1>" "ls\n") - @result{} nil -@end group -@end smallexample -@end defun - -@defun process-send-region process start end -This function sends the text in the region defined by @var{start} and -@var{end} as standard input to @var{process}. - -An error is signaled unless both @var{start} and @var{end} are -integers or markers that indicate positions in the current buffer. (It -is unimportant which number is larger.) -@end defun - -@defun process-send-eof &optional process -This function makes @var{process} see an end-of-file in its -input. The @acronym{EOF} comes after any text already sent to it. -The function returns @var{process}. - -@smallexample -@group -(process-send-eof "shell") - @result{} "shell" -@end group -@end smallexample -@end defun - -@defun process-running-child-p &optional process -This function will tell you whether a @var{process} has given control of -its terminal to its own child process. The value is @code{t} if this is -true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain -that this is not so. -@end defun - -@node Signals to Processes -@section Sending Signals to Processes -@cindex process signals -@cindex sending signals -@cindex signals - - @dfn{Sending a signal} to a subprocess is a way of interrupting its -activities. There are several different signals, each with its own -meaning. The set of signals and their names is defined by the operating -system. For example, the signal @code{SIGINT} means that the user has -typed @kbd{C-c}, or that some analogous thing has happened. - - Each signal has a standard effect on the subprocess. Most signals -kill the subprocess, but some stop (or resume) execution instead. Most -signals can optionally be handled by programs; if the program handles -the signal, then we can say nothing in general about its effects. - - You can send signals explicitly by calling the functions in this -section. Emacs also sends signals automatically at certain times: -killing a buffer sends a @code{SIGHUP} signal to all its associated -processes; killing Emacs sends a @code{SIGHUP} signal to all remaining -processes. (@code{SIGHUP} is a signal that usually indicates that the -user ``hung up the phone'', i.e., disconnected.) - - Each of the signal-sending functions takes two optional arguments: -@var{process} and @var{current-group}. - - The argument @var{process} must be either a process, a process -name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name -stands for a process through @code{get-buffer-process}. @code{nil} -stands for the process associated with the current buffer. An error -is signaled if @var{process} does not identify a process. - - The argument @var{current-group} is a flag that makes a difference -when you are running a job-control shell as an Emacs subprocess. If it -is non-@code{nil}, then the signal is sent to the current process-group -of the terminal that Emacs uses to communicate with the subprocess. If -the process is a job-control shell, this means the shell's current -subjob. If it is @code{nil}, the signal is sent to the process group of -the immediate subprocess of Emacs. If the subprocess is a job-control -shell, this is the shell itself. - - The flag @var{current-group} has no effect when a pipe is used to -communicate with the subprocess, because the operating system does not -support the distinction in the case of pipes. For the same reason, -job-control shells won't work when a pipe is used. See -@code{process-connection-type} in @ref{Asynchronous Processes}. - -@defun interrupt-process &optional process current-group -This function interrupts the process @var{process} by sending the -signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt -character'' (normally @kbd{C-c} on some systems, and @key{DEL} on -others) sends this signal. When the argument @var{current-group} is -non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' -on the terminal by which Emacs talks to the subprocess. -@end defun - -@defun kill-process &optional process current-group -This function kills the process @var{process} by sending the -signal @code{SIGKILL}. This signal kills the subprocess immediately, -and cannot be handled by the subprocess. -@end defun - -@defun quit-process &optional process current-group -This function sends the signal @code{SIGQUIT} to the process -@var{process}. This signal is the one sent by the ``quit -@c FIXME? Never heard of C-b being used for this. In readline, e.g., -@c bash, that is backward-word. -character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside -Emacs. -@end defun - -@defun stop-process &optional process current-group -This function stops the process @var{process} by sending the -signal @code{SIGTSTP}. Use @code{continue-process} to resume its -execution. - -Outside of Emacs, on systems with job control, the ``stop character'' -(usually @kbd{C-z}) normally sends this signal. When -@var{current-group} is non-@code{nil}, you can think of this function as -``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the -subprocess. -@end defun - -@defun continue-process &optional process current-group -This function resumes execution of the process @var{process} by sending -it the signal @code{SIGCONT}. This presumes that @var{process} was -stopped previously. -@end defun - -@deffn Command signal-process process signal -This function sends a signal to process @var{process}. The argument -@var{signal} specifies which signal to send; it should be an integer, -or a symbol whose name is a signal. - -The @var{process} argument can be a system process @acronym{ID} (an -integer); that allows you to send signals to processes that are not -children of Emacs. @xref{System Processes}. -@end deffn - -@node Output from Processes -@section Receiving Output from Processes -@cindex process output -@cindex output from processes - - The output that a subprocess writes to its standard output stream -is passed to a function called the @dfn{filter function}. The default -filter function simply inserts the output into a buffer, which is -called the associated buffer of the process (@pxref{Process -Buffers}). If the process has no buffer then the default filter -discards the output. - - When a subprocess terminates, Emacs reads any pending output, -then stops reading output from that subprocess. Therefore, if the -subprocess has children that are still live and still producing -output, Emacs won't receive that output. - - Output from a subprocess can arrive only while Emacs is waiting: when -reading terminal input (see the function @code{waiting-for-user-input-p}), -in @code{sit-for} and @code{sleep-for} (@pxref{Waiting}), and in -@code{accept-process-output} (@pxref{Accepting Output}). This -minimizes the problem of timing errors that usually plague parallel -programming. For example, you can safely create a process and only -then specify its buffer or filter function; no output can arrive -before you finish, if the code in between does not call any primitive -that waits. - -@defvar process-adaptive-read-buffering -On some systems, when Emacs reads the output from a subprocess, the -output data is read in very small blocks, potentially resulting in -very poor performance. This behavior can be remedied to some extent -by setting the variable @code{process-adaptive-read-buffering} to a -non-@code{nil} value (the default), as it will automatically delay reading -from such processes, thus allowing them to produce more output before -Emacs tries to read it. -@end defvar - - It is impossible to separate the standard output and standard error -streams of the subprocess, because Emacs normally spawns the subprocess -inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If -you want to keep the output to those streams separate, you should -redirect one of them to a file---for example, by using an appropriate -shell command. - -@menu -* Process Buffers:: By default, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. -@end menu - -@node Process Buffers -@subsection Process Buffers - - A process can (and usually does) have an @dfn{associated buffer}, -which is an ordinary Emacs buffer that is used for two purposes: storing -the output from the process, and deciding when to kill the process. You -can also use the buffer to identify a process to operate on, since in -normal practice only one process is associated with any given buffer. -Many applications of processes also use the buffer for editing input to -be sent to the process, but this is not built into Emacs Lisp. - - By default, process output is inserted in the associated buffer. -(You can change this by defining a custom filter function, -@pxref{Filter Functions}.) The position to insert the output is -determined by the @code{process-mark}, which is then updated to point -to the end of the text just inserted. Usually, but not always, the -@code{process-mark} is at the end of the buffer. - -@findex process-kill-buffer-query-function - Killing the associated buffer of a process also kills the process. -Emacs asks for confirmation first, if the process's -@code{process-query-on-exit-flag} is non-@code{nil} (@pxref{Query -Before Exit}). This confirmation is done by the function -@code{process-kill-buffer-query-function}, which is run from -@code{kill-buffer-query-functions} (@pxref{Killing Buffers}). - -@defun process-buffer process -This function returns the associated buffer of the process -@var{process}. - -@smallexample -@group -(process-buffer (get-process "shell")) - @result{} # -@end group -@end smallexample -@end defun - -@defun process-mark process -This function returns the process marker for @var{process}, which is the -marker that says where to insert output from the process. - -If @var{process} does not have a buffer, @code{process-mark} returns a -marker that points nowhere. - -The default filter function uses this marker to decide where to -insert process output, and updates it to point after the inserted text. -That is why successive batches of output are inserted consecutively. - -Custom filter functions normally should use this marker in the same fashion. -For an example of a filter function that uses @code{process-mark}, -@pxref{Process Filter Example}. - -When the user is expected to enter input in the process buffer for -transmission to the process, the process marker separates the new input -from previous output. -@end defun - -@defun set-process-buffer process buffer -This function sets the buffer associated with @var{process} to -@var{buffer}. If @var{buffer} is @code{nil}, the process becomes -associated with no buffer. -@end defun - -@defun get-buffer-process buffer-or-name -This function returns a nondeleted process associated with the buffer -specified by @var{buffer-or-name}. If there are several processes -associated with it, this function chooses one (currently, the one most -recently created, but don't count on that). Deletion of a process -(see @code{delete-process}) makes it ineligible for this function to -return. - -It is usually a bad idea to have more than one process associated with -the same buffer. - -@smallexample -@group -(get-buffer-process "*shell*") - @result{} # -@end group -@end smallexample - -Killing the process's buffer deletes the process, which kills the -subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). -@end defun - -@node Filter Functions -@subsection Process Filter Functions -@cindex filter function -@cindex process filter - - A process @dfn{filter function} is a function that receives the -standard output from the associated process. @emph{All} output from -that process is passed to the filter. The default filter simply -outputs directly to the process buffer. - - The filter function can only be called when Emacs is waiting for -something, because process output arrives only at such times. Emacs -waits when reading terminal input (see the function -@code{waiting-for-user-input-p}), in @code{sit-for} and -@code{sleep-for} (@pxref{Waiting}), and in -@code{accept-process-output} (@pxref{Accepting Output}). - - A filter function must accept two arguments: the associated process -and a string, which is output just received from it. The function is -then free to do whatever it chooses with the output. - -@c Note this text is duplicated in the sentinels section. - Quitting is normally inhibited within a filter function---otherwise, -the effect of typing @kbd{C-g} at command level or to quit a user -command would be unpredictable. If you want to permit quitting inside -a filter function, bind @code{inhibit-quit} to @code{nil}. In most -cases, the right way to do this is with the macro -@code{with-local-quit}. @xref{Quitting}. - - If an error happens during execution of a filter function, it is -caught automatically, so that it doesn't stop the execution of whatever -program was running when the filter function was started. However, if -@code{debug-on-error} is non-@code{nil}, errors are not caught. -This makes it possible to use the Lisp debugger to debug the -filter function. @xref{Debugger}. - - Many filter functions sometimes (or always) insert the output in the -process's buffer, mimicking the actions of the default filter. -Such filter functions need to make sure that they save the -current buffer, select the correct buffer (if different) before -inserting output, and then restore the original buffer. -They should also check whether the buffer is still alive, update the -process marker, and in some cases update the value of point. Here is -how to do these things: - -@anchor{Process Filter Example} -@smallexample -@group -(defun ordinary-insertion-filter (proc string) - (when (buffer-live-p (process-buffer proc)) - (with-current-buffer (process-buffer proc) - (let ((moving (= (point) (process-mark proc)))) -@end group -@group - (save-excursion - ;; @r{Insert the text, advancing the process marker.} - (goto-char (process-mark proc)) - (insert string) - (set-marker (process-mark proc) (point))) - (if moving (goto-char (process-mark proc))))))) -@end group -@end smallexample - - To make the filter force the process buffer to be visible whenever new -text arrives, you could insert a line like the following just before the -@code{with-current-buffer} construct: - -@smallexample -(display-buffer (process-buffer proc)) -@end smallexample - - To force point to the end of the new output, no matter where it was -previously, eliminate the variable @code{moving} and call -@code{goto-char} unconditionally. - -@ignore - In earlier Emacs versions, every filter function that did regular -expression searching or matching had to explicitly save and restore the -match data. Now Emacs does this automatically for filter functions; -they never need to do it explicitly. -@end ignore - Note that Emacs automatically saves and restores the match data -while executing filter functions. @xref{Match Data}. - - The output to the filter may come in chunks of any size. A program -that produces the same output twice in a row may send it as one batch of -200 characters one time, and five batches of 40 characters the next. If -the filter looks for certain text strings in the subprocess output, make -sure to handle the case where one of these strings is split across two -or more batches of output; one way to do this is to insert the -received text into a temporary buffer, which can then be searched. - -@defun set-process-filter process filter -This function gives @var{process} the filter function @var{filter}. If -@var{filter} is @code{nil}, it gives the process the default filter, -which inserts the process output into the process buffer. -@end defun - -@defun process-filter process -This function returns the filter function of @var{process}. -@end defun - -In case the process's output needs to be passed to several filters, you can -use @code{add-function} to combine an existing filter with a new one. -@xref{Advising Functions}. - - Here is an example of the use of a filter function: - -@smallexample -@group -(defun keep-output (process output) - (setq kept (cons output kept))) - @result{} keep-output -@end group -@group -(setq kept nil) - @result{} nil -@end group -@group -(set-process-filter (get-process "shell") 'keep-output) - @result{} keep-output -@end group -@group -(process-send-string "shell" "ls ~/other\n") - @result{} nil -kept - @result{} ("lewis@@slug:$ " -@end group -@group -"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ -address.txt backup.psf kolstad.psf -backup.bib~ david.mss resume-Dec-86.mss~ -backup.err david.psf resume-Dec.psf -backup.mss dland syllabus.mss -" -"#backups.mss# backup.mss~ kolstad.mss -") -@end group -@end smallexample - -@ignore @c The code in this example doesn't show the right way to do things. -Here is another, more realistic example, which demonstrates how to use -the process mark to do insertion in the same fashion as the default filter: - -@smallexample -@group -;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} -;; @r{and make sure that buffer is shown in some window.} -(defun my-process-filter (proc str) - (let ((cur (selected-window)) - (pop-up-windows t)) - (pop-to-buffer my-shell-buffer) -@end group -@group - (goto-char (point-max)) - (insert str) - (set-marker (process-mark proc) (point-max)) - (select-window cur))) -@end group -@end smallexample -@end ignore - -@node Decoding Output -@subsection Decoding Process Output -@cindex decode process output - - When Emacs writes process output directly into a multibyte buffer, -it decodes the output according to the process output coding system. -If the coding system is @code{raw-text} or @code{no-conversion}, Emacs -converts the unibyte output to multibyte using -@code{string-to-multibyte}, and inserts the resulting multibyte text. - - You can use @code{set-process-coding-system} to specify which coding -system to use (@pxref{Process Information}). Otherwise, the coding -system comes from @code{coding-system-for-read}, if that is -non-@code{nil}; or else from the defaulting mechanism (@pxref{Default -Coding Systems}). If the text output by a process contains null -bytes, Emacs by default uses @code{no-conversion} for it; see -@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to -control this behavior. - - @strong{Warning:} Coding systems such as @code{undecided}, which -determine the coding system from the data, do not work entirely -reliably with asynchronous subprocess output. This is because Emacs -has to process asynchronous subprocess output in batches, as it -arrives. Emacs must try to detect the proper coding system from one -batch at a time, and this does not always work. Therefore, if at all -possible, specify a coding system that determines both the character -code conversion and the end of line conversion---that is, one like -@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}. - -@c Let's keep the index entries that were there for -@c set-process-filter-multibyte and process-filter-multibyte-p, -@cindex filter multibyte flag, of process -@cindex process filter multibyte flag - When Emacs calls a process filter function, it provides the process -output as a multibyte string or as a unibyte string according to the -process's filter coding system. Emacs -decodes the output according to the process output coding system, -which usually produces a multibyte string, except for coding systems -such as @code{binary} and @code{raw-text}. - -@node Accepting Output -@subsection Accepting Output from Processes -@cindex accept input from processes - - Output from asynchronous subprocesses normally arrives only while -Emacs is waiting for some sort of external event, such as elapsed time -or terminal input. Occasionally it is useful in a Lisp program to -explicitly permit output to arrive at a specific point, or even to wait -until output arrives from a process. - -@defun accept-process-output &optional process seconds millisec just-this-one -This function allows Emacs to read pending output from processes. The -output is given to their filter functions. If @var{process} is -non-@code{nil} then this function does not return until some output -has been received from @var{process}. - -The arguments @var{seconds} and @var{millisec} let you specify timeout -periods. The former specifies a period measured in seconds and the -latter specifies one measured in milliseconds. The two time periods -thus specified are added together, and @code{accept-process-output} -returns after that much time, whether or not there has been any -subprocess output. - -The argument @var{millisec} is obsolete (and should not be used), -because @var{seconds} can be floating point to specify -waiting a fractional number of seconds. If @var{seconds} is 0, the -function accepts whatever output is pending but does not wait. - -@c Emacs 22.1 feature -If @var{process} is a process, and the argument @var{just-this-one} is -non-@code{nil}, only output from that process is handled, suspending output -from other processes until some output has been received from that -process or the timeout expires. If @var{just-this-one} is an integer, -also inhibit running timers. This feature is generally not -recommended, but may be necessary for specific applications, such as -speech synthesis. - -The function @code{accept-process-output} returns non-@code{nil} if it -did get some output, or @code{nil} if the timeout expired before output -arrived. -@end defun - -@node Sentinels -@section Sentinels: Detecting Process Status Changes -@cindex process sentinel -@cindex sentinel (of process) - - A @dfn{process sentinel} is a function that is called whenever the -associated process changes status for any reason, including signals -(whether sent by Emacs or caused by the process's own actions) that -terminate, stop, or continue the process. The process sentinel is -also called if the process exits. The sentinel receives two -arguments: the process for which the event occurred, and a string -describing the type of event. - - The string describing the event looks like one of the following: - -@c FIXME? Also "killed\n" - see example below? -@itemize @bullet -@item -@code{"finished\n"}. - -@item -@code{"exited abnormally with code @var{exitcode}\n"}. - -@item -@code{"@var{name-of-signal}\n"}. - -@item -@code{"@var{name-of-signal} (core dumped)\n"}. -@end itemize - - A sentinel runs only while Emacs is waiting (e.g., for terminal -input, or for time to elapse, or for process output). This avoids the -timing errors that could result from running sentinels at random places in -the middle of other Lisp programs. A program can wait, so that -sentinels will run, by calling @code{sit-for} or @code{sleep-for} -(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting -Output}). Emacs also allows sentinels to run when the command loop is -reading input. @code{delete-process} calls the sentinel when it -terminates a running process. - - Emacs does not keep a queue of multiple reasons to call the sentinel -of one process; it records just the current status and the fact that -there has been a change. Therefore two changes in status, coming in -quick succession, can call the sentinel just once. However, process -termination will always run the sentinel exactly once. This is -because the process status can't change again after termination. - - Emacs explicitly checks for output from the process before running -the process sentinel. Once the sentinel runs due to process -termination, no further output can arrive from the process. - - A sentinel that writes the output into the buffer of the process -should check whether the buffer is still alive. If it tries to insert -into a dead buffer, it will get an error. If the buffer is dead, -@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. - -@c Note this text is duplicated in the filter functions section. - Quitting is normally inhibited within a sentinel---otherwise, the -effect of typing @kbd{C-g} at command level or to quit a user command -would be unpredictable. If you want to permit quitting inside a -sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the -right way to do this is with the macro @code{with-local-quit}. -@xref{Quitting}. - - If an error happens during execution of a sentinel, it is caught -automatically, so that it doesn't stop the execution of whatever -programs was running when the sentinel was started. However, if -@code{debug-on-error} is non-@code{nil}, errors are not caught. -This makes it possible to use the Lisp debugger to debug the -sentinel. @xref{Debugger}. - - While a sentinel is running, the process sentinel is temporarily -set to @code{nil} so that the sentinel won't run recursively. -For this reason it is not possible for a sentinel to specify -a new sentinel. - -@ignore - In earlier Emacs versions, every sentinel that did regular expression -searching or matching had to explicitly save and restore the match data. -Now Emacs does this automatically for sentinels; they never need to do -it explicitly. -@end ignore - Note that Emacs automatically saves and restores the match data -while executing sentinels. @xref{Match Data}. - -@defun set-process-sentinel process sentinel -This function associates @var{sentinel} with @var{process}. If -@var{sentinel} is @code{nil}, then the process will have the default -sentinel, which inserts a message in the process's buffer when the -process status changes. - -Changes in process sentinels take effect immediately---if the sentinel -is slated to be run but has not been called yet, and you specify a new -sentinel, the eventual call to the sentinel will use the new one. - -@smallexample -@group -(defun msg-me (process event) - (princ - (format "Process: %s had the event `%s'" process event))) -(set-process-sentinel (get-process "shell") 'msg-me) - @result{} msg-me -@end group -@group -(kill-process (get-process "shell")) - @print{} Process: # had the event `killed' - @result{} # -@end group -@end smallexample -@end defun - -@defun process-sentinel process -This function returns the sentinel of @var{process}. -@end defun - -In case a process status changes need to be passed to several sentinels, you -can use @code{add-function} to combine an existing sentinel with a new one. -@xref{Advising Functions}. - -@defun waiting-for-user-input-p -While a sentinel or filter function is running, this function returns -non-@code{nil} if Emacs was waiting for keyboard input from the user at -the time the sentinel or filter function was called, or @code{nil} if it -was not. -@end defun - -@node Query Before Exit -@section Querying Before Exit - - When Emacs exits, it terminates all its subprocesses by sending them -the @code{SIGHUP} signal. Because subprocesses may be doing -valuable work, Emacs normally asks the user to confirm that it is ok -to terminate them. Each process has a query flag, which, if -non-@code{nil}, says that Emacs should ask for confirmation before -exiting and thus killing that process. The default for the query flag -is @code{t}, meaning @emph{do} query. - -@defun process-query-on-exit-flag process -This returns the query flag of @var{process}. -@end defun - -@defun set-process-query-on-exit-flag process flag -This function sets the query flag of @var{process} to @var{flag}. It -returns @var{flag}. - -Here is an example of using @code{set-process-query-on-exit-flag} on a -shell process to avoid querying: - -@smallexample -@group -(set-process-query-on-exit-flag (get-process "shell") nil) - @result{} nil -@end group -@end smallexample -@end defun - -@node System Processes -@section Accessing Other Processes -@cindex system processes - - In addition to accessing and manipulating processes that are -subprocesses of the current Emacs session, Emacs Lisp programs can -also access other processes running on the same machine. We call -these @dfn{system processes}, to distinguish them from Emacs -subprocesses. - - Emacs provides several primitives for accessing system processes. -Not all platforms support these primitives; on those which don't, -these primitives return @code{nil}. - -@defun list-system-processes -This function returns a list of all the processes running on the -system. Each process is identified by its @acronym{PID}, a numerical -process ID that is assigned by the OS and distinguishes the process -from all the other processes running on the same machine at the same -time. -@end defun - -@defun process-attributes pid -This function returns an alist of attributes for the process specified -by its process ID @var{pid}. Each association in the alist is of the -form @code{(@var{key} . @var{value})}, where @var{key} designates the -attribute and @var{value} is the value of that attribute. The various -attribute @var{key}s that this function can return are listed below. -Not all platforms support all of these attributes; if an attribute is -not supported, its association will not appear in the returned alist. -Values that are numbers can be either integer or floating point, -depending on the magnitude of the value. - -@table @code -@item euid -The effective user ID of the user who invoked the process. The -corresponding @var{value} is a number. If the process was invoked by -the same user who runs the current Emacs session, the value is -identical to what @code{user-uid} returns (@pxref{User -Identification}). - -@item user -User name corresponding to the process's effective user ID, a string. - -@item egid -The group ID of the effective user ID, a number. - -@item group -Group name corresponding to the effective user's group ID, a string. - -@item comm -The name of the command that runs in the process. This is a string -that usually specifies the name of the executable file of the process, -without the leading directories. However, some special system -processes can report strings that do not correspond to an executable -file of a program. - -@item state -The state code of the process. This is a short string that encodes -the scheduling state of the process. Here's a list of the most -frequently seen codes: - -@table @code -@item "D" -uninterruptible sleep (usually I/O) -@item "R" -running -@item "S" -interruptible sleep (waiting for some event) -@item "T" -stopped, e.g., by a job control signal -@item "Z" -``zombie'': a process that terminated, but was not reaped by its parent -@end table - -@noindent -For the full list of the possible states, see the manual page of the -@command{ps} command. - -@item ppid -The process ID of the parent process, a number. - -@item pgrp -The process group ID of the process, a number. - -@item sess -The session ID of the process. This is a number that is the process -ID of the process's @dfn{session leader}. - -@item ttname -A string that is the name of the process's controlling terminal. On -Unix and GNU systems, this is normally the file name of the -corresponding terminal device, such as @file{/dev/pts65}. - -@item tpgid -The numerical process group ID of the foreground process group that -uses the process's terminal. - -@item minflt -The number of minor page faults caused by the process since its -beginning. (Minor page faults are those that don't involve reading -from disk.) - -@item majflt -The number of major page faults caused by the process since its -beginning. (Major page faults require a disk to be read, and are thus -more expensive than minor page faults.) - -@item cminflt -@itemx cmajflt -Like @code{minflt} and @code{majflt}, but include the number of page -faults for all the child processes of the given process. - -@item utime -Time spent by the process in the user context, for running the -application's code. The corresponding @var{value} is in the -@w{@code{(@var{high} @var{low} @var{microsec} @var{picosec})}} format, the same -format used by functions @code{current-time} (@pxref{Time of Day, -current-time}) and @code{file-attributes} (@pxref{File Attributes}). - -@item stime -Time spent by the process in the system (kernel) context, for -processing system calls. The corresponding @var{value} is in the same -format as for @code{utime}. - -@item time -The sum of @code{utime} and @code{stime}. The corresponding -@var{value} is in the same format as for @code{utime}. - -@item cutime -@itemx cstime -@itemx ctime -Like @code{utime}, @code{stime}, and @code{time}, but include the -times of all the child processes of the given process. - -@item pri -The numerical priority of the process. - -@item nice -The @dfn{nice value} of the process, a number. (Processes with smaller -nice values get scheduled more favorably.) - -@item thcount -The number of threads in the process. - -@item start -The time when the process was started, in the same -@code{(@var{high} @var{low} @var{microsec} @var{picosec})} format used by -@code{file-attributes} and @code{current-time}. - -@item etime -The time elapsed since the process started, in the format @code{(@var{high} -@var{low} @var{microsec} @var{picosec})}. - -@item vsize -The virtual memory size of the process, measured in kilobytes. - -@item rss -The size of the process's @dfn{resident set}, the number of kilobytes -occupied by the process in the machine's physical memory. - -@item pcpu -The percentage of the CPU time used by the process since it started. -The corresponding @var{value} is a floating-point number between 0 and -100. - -@item pmem -The percentage of the total physical memory installed on the machine -used by the process's resident set. The value is a floating-point -number between 0 and 100. - -@item args -The command-line with which the process was invoked. This is a string -in which individual command-line arguments are separated by blanks; -whitespace characters that are embedded in the arguments are quoted as -appropriate for the system's shell: escaped by backslash characters on -GNU and Unix, and enclosed in double quote characters on Windows. -Thus, this command-line string can be directly used in primitives such -as @code{shell-command}. -@end table - -@end defun - - -@node Transaction Queues -@section Transaction Queues -@cindex transaction queue - -@c That's not very informative. What is a transaction, and when might -@c I want to use one? -You can use a @dfn{transaction queue} to communicate with a subprocess -using transactions. First use @code{tq-create} to create a transaction -queue communicating with a specified process. Then you can call -@code{tq-enqueue} to send a transaction. - -@defun tq-create process -This function creates and returns a transaction queue communicating with -@var{process}. The argument @var{process} should be a subprocess -capable of sending and receiving streams of bytes. It may be a child -process, or it may be a TCP connection to a server, possibly on another -machine. -@end defun - -@defun tq-enqueue queue question regexp closure fn &optional delay-question -This function sends a transaction to queue @var{queue}. Specifying the -queue has the effect of specifying the subprocess to talk to. - -The argument @var{question} is the outgoing message that starts the -transaction. The argument @var{fn} is the function to call when the -corresponding answer comes back; it is called with two arguments: -@var{closure}, and the answer received. - -The argument @var{regexp} is a regular expression that should match -text at the end of the entire answer, but nothing before; that's how -@code{tq-enqueue} determines where the answer ends. - -If the argument @var{delay-question} is non-@code{nil}, delay sending -this question until the process has finished replying to any previous -questions. This produces more reliable results with some processes. -@ignore - -@c Let's not mention it then. -The return value of @code{tq-enqueue} itself is not meaningful. -@end ignore -@end defun - -@defun tq-close queue -Shut down transaction queue @var{queue}, waiting for all pending transactions -to complete, and then terminate the connection or child process. -@end defun - -Transaction queues are implemented by means of a filter function. -@xref{Filter Functions}. - -@node Network -@section Network Connections -@cindex network connection -@cindex TCP -@cindex UDP - - Emacs Lisp programs can open stream (TCP) and datagram (UDP) network -connections (@pxref{Datagrams}) to other processes on the same machine -or other machines. -A network connection is handled by Lisp much like a subprocess, and is -represented by a process object. However, the process you are -communicating with is not a child of the Emacs process, has no -process @acronym{ID}, and you can't kill it or send it signals. All you -can do is send and receive data. @code{delete-process} closes the -connection, but does not kill the program at the other end; that -program must decide what to do about closure of the connection. - - Lisp programs can listen for connections by creating network -servers. A network server is also represented by a kind of process -object, but unlike a network connection, the network server never -transfers data itself. When it receives a connection request, it -creates a new network connection to represent the connection just -made. (The network connection inherits certain information, including -the process plist, from the server.) The network server then goes -back to listening for more connection requests. - - Network connections and servers are created by calling -@code{make-network-process} with an argument list consisting of -keyword/argument pairs, for example @code{:server t} to create a -server process, or @code{:type 'datagram} to create a datagram -connection. @xref{Low-Level Network}, for details. You can also use -the @code{open-network-stream} function described below. - - To distinguish the different types of processes, the -@code{process-type} function returns the symbol @code{network} for a -network connection or server, @code{serial} for a serial port -connection, or @code{real} for a real subprocess. - - The @code{process-status} function returns @code{open}, -@code{closed}, @code{connect}, or @code{failed} for network -connections. For a network server, the status is always -@code{listen}. None of those values is possible for a real -subprocess. @xref{Process Information}. - - You can stop and resume operation of a network process by calling -@code{stop-process} and @code{continue-process}. For a server -process, being stopped means not accepting new connections. (Up to 5 -connection requests will be queued for when you resume the server; you -can increase this limit, unless it is imposed by the operating -system---see the @code{:server} keyword of @code{make-network-process}, -@ref{Network Processes}.) For a network stream connection, being -stopped means not processing input (any arriving input waits until you -resume the connection). For a datagram connection, some number of -packets may be queued but input may be lost. You can use the function -@code{process-command} to determine whether a network connection or -server is stopped; a non-@code{nil} value means yes. - -@cindex network connection, encrypted -@cindex encrypted network connections -@cindex @acronym{TLS} network connections -@cindex @acronym{STARTTLS} network connections -Emacs can create encrypted network connections, using either built-in -or external support. The built-in support uses the GnuTLS -(``Transport Layer Security'') library; see -@uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}. -If your Emacs was compiled with GnuTLS support, the function -@code{gnutls-available-p} is defined and returns non-@code{nil}. For -more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}. -The external support uses the @file{starttls.el} library, which -requires a helper utility such as @command{gnutls-cli} to be installed -on the system. The @code{open-network-stream} function can -transparently handle the details of creating encrypted connections for -you, using whatever support is available. - -@defun open-network-stream name buffer host service &rest parameters -This function opens a TCP connection, with optional encryption, and -returns a process object that represents the connection. - -The @var{name} argument specifies the name for the process object. It -is modified as necessary to make it unique. - -The @var{buffer} argument is the buffer to associate with the -connection. Output from the connection is inserted in the buffer, -unless you specify your own filter function to handle the output. If -@var{buffer} is @code{nil}, it means that the connection is not -associated with any buffer. - -The arguments @var{host} and @var{service} specify where to connect to; -@var{host} is the host name (a string), and @var{service} is the name of -a defined network service (a string) or a port number (an integer). - -The remaining arguments @var{parameters} are keyword/argument pairs -that are mainly relevant to encrypted connections: - -@table @code - -@item :nowait @var{boolean} -If non-@code{nil}, try to make an asynchronous connection. - -@item :type @var{type} -The type of connection. Options are: - -@table @code -@item plain -An ordinary, unencrypted connection. -@item tls -@itemx ssl -A @acronym{TLS} (``Transport Layer Security'') connection. -@item nil -@itemx network -Start with a plain connection, and if parameters @samp{:success} -and @samp{:capability-command} are supplied, try to upgrade to an encrypted -connection via @acronym{STARTTLS}. If that fails, retain the -unencrypted connection. -@item starttls -As for @code{nil}, but if @acronym{STARTTLS} fails drop the connection. -@item shell -A shell connection. -@end table - -@item :always-query-capabilities @var{boolean} -If non-@code{nil}, always ask for the server's capabilities, even when -doing a @samp{plain} connection. - -@item :capability-command @var{capability-command} -Command string to query the host capabilities. - -@item :end-of-command @var{regexp} -@itemx :end-of-capability @var{regexp} -Regular expression matching the end of a command, or the end of the -command @var{capability-command}. The latter defaults to the former. - -@item :starttls-function @var{function} -Function of one argument (the response to @var{capability-command}), -which returns either @code{nil}, or the command to activate @acronym{STARTTLS} -if supported. - -@item :success @var{regexp} -Regular expression matching a successful @acronym{STARTTLS} negotiation. - -@item :use-starttls-if-possible @var{boolean} -If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs -doesn't have built-in @acronym{TLS} support. - -@item :client-certificate @var{list-or-t} -Either a list of the form @code{(@var{key-file} @var{cert-file})}, -naming the certificate key file and certificate file itself, or -@code{t}, meaning to query @code{auth-source} for this information -(@pxref{Top,,Overview, auth, The Auth-Source Manual}). -Only used for @acronym{TLS} or @acronym{STARTTLS}. - -@item :return-list @var{cons-or-nil} -The return value of this function. If omitted or @code{nil}, return a -process object. Otherwise, a cons of the form @code{(@var{process-object} -. @var{plist})}, where @var{plist} has keywords: - -@table @code -@item :greeting @var{string-or-nil} -If non-@code{nil}, the greeting string returned by the host. -@item :capabilities @var{string-or-nil} -If non-@code{nil}, the host's capability string. -@item :type @var{symbol} -The connection type: @samp{plain} or @samp{tls}. -@end table - -@end table - -@end defun - -@node Network Servers -@section Network Servers -@cindex network servers - - You create a server by calling @code{make-network-process} -(@pxref{Network Processes}) with @code{:server t}. The server will -listen for connection requests from clients. When it accepts a client -connection request, that creates a new network connection, itself a -process object, with the following parameters: - -@itemize @bullet -@item -The connection's process name is constructed by concatenating the -server process's @var{name} with a client identification string. The -@c FIXME? What about IPv6? Say briefly what the difference is? -client identification string for an IPv4 connection looks like -@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}, which represents an -address and port number. Otherwise, it is a -unique number in brackets, as in @samp{<@var{nnn}>}. The number -is unique for each connection in the Emacs session. - -@item -If the server has a non-default filter, the connection process does -not get a separate process buffer; otherwise, Emacs creates a new -buffer for the purpose. The buffer name is the server's buffer name -or process name, concatenated with the client identification string. - -The server's process buffer value is never used directly, but the log -function can retrieve it and use it to log connections by inserting -text there. - -@item -The communication type and the process filter and sentinel are -inherited from those of the server. The server never directly -uses its filter and sentinel; their sole purpose is to initialize -connections made to the server. - -@item -The connection's process contact information is set according to the client's -addressing information (typically an IP address and a port number). -This information is associated with the @code{process-contact} -keywords @code{:host}, @code{:service}, @code{:remote}. - -@item -The connection's local address is set up according to the port -number used for the connection. - -@item -The client process's plist is initialized from the server's plist. -@end itemize - -@node Datagrams -@section Datagrams -@cindex datagrams - - A @dfn{datagram} connection communicates with individual packets rather -than streams of data. Each call to @code{process-send} sends one -datagram packet (@pxref{Input to Processes}), and each datagram -received results in one call to the filter function. - - The datagram connection doesn't have to talk with the same remote -peer all the time. It has a @dfn{remote peer address} which specifies -where to send datagrams to. Each time an incoming datagram is passed -to the filter function, the peer address is set to the address that -datagram came from; that way, if the filter function sends a datagram, -it will go back to that place. You can specify the remote peer -address when you create the datagram connection using the -@code{:remote} keyword. You can change it later on by calling -@code{set-process-datagram-address}. - -@defun process-datagram-address process -If @var{process} is a datagram connection or server, this function -returns its remote peer address. -@end defun - -@defun set-process-datagram-address process address -If @var{process} is a datagram connection or server, this function -sets its remote peer address to @var{address}. -@end defun - -@node Low-Level Network -@section Low-Level Network Access - - You can also create network connections by operating at a lower -level than that of @code{open-network-stream}, using -@code{make-network-process}. - -@menu -* Proc: Network Processes. Using @code{make-network-process}. -* Options: Network Options. Further control over network connections. -* Features: Network Feature Testing. - Determining which network features work on - the machine you are using. -@end menu - -@node Network Processes -@subsection @code{make-network-process} - - The basic function for creating network connections and network -servers is @code{make-network-process}. It can do either of those -jobs, depending on the arguments you give it. - -@defun make-network-process &rest args -This function creates a network connection or server and returns the -process object that represents it. The arguments @var{args} are a -list of keyword/argument pairs. Omitting a keyword is always -equivalent to specifying it with value @code{nil}, except for -@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here -are the meaningful keywords (those corresponding to network options -are listed in the following section): - -@table @asis -@item :name @var{name} -Use the string @var{name} as the process name. It is modified if -necessary to make it unique. - -@item :type @var{type} -Specify the communication type. A value of @code{nil} specifies a -stream connection (the default); @code{datagram} specifies a datagram -connection; @code{seqpacket} specifies a ``sequenced packet stream'' -connection. Both connections and servers can be of these types. - -@item :server @var{server-flag} -If @var{server-flag} is non-@code{nil}, create a server. Otherwise, -create a connection. For a stream type server, @var{server-flag} may -be an integer, which then specifies the length of the queue of pending -connections to the server. The default queue length is 5. - -@item :host @var{host} -Specify the host to connect to. @var{host} should be a host name or -Internet address, as a string, or the symbol @code{local} to specify -the local host. If you specify @var{host} for a server, it must -specify a valid address for the local host, and only clients -connecting to that address will be accepted. - -@item :service @var{service} -@var{service} specifies a port number to connect to; or, for a server, -the port number to listen on. It should be a service name that -translates to a port number, or an integer specifying the port number -directly. For a server, it can also be @code{t}, which means to let -the system select an unused port number. - -@item :family @var{family} -@var{family} specifies the address (and protocol) family for -communication. @code{nil} means determine the proper address family -automatically for the given @var{host} and @var{service}. -@code{local} specifies a Unix socket, in which case @var{host} is -ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6, -respectively. - -@item :local @var{local-address} -For a server process, @var{local-address} is the address to listen on. -It overrides @var{family}, @var{host} and @var{service}, so you -might as well not specify them. - -@item :remote @var{remote-address} -For a connection, @var{remote-address} is the address to connect to. -It overrides @var{family}, @var{host} and @var{service}, so you -might as well not specify them. - -For a datagram server, @var{remote-address} specifies the initial -setting of the remote datagram address. - -The format of @var{local-address} or @var{remote-address} depends on -the address family: - -@itemize - -@item -An IPv4 address is represented as a five-element vector of four 8-bit -integers and one 16-bit integer -@code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to -numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number -@var{p}. - -@item -An IPv6 address is represented as a nine-element vector of 16-bit -integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f} -@var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address -@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and -port number @var{p}. - -@item -A local address is represented as a string, which specifies the address -in the local address space. - -@item -An ``unsupported family'' address is represented by a cons -@code{(@var{f} . @var{av})}, where @var{f} is the family number and -@var{av} is a vector specifying the socket address using one element -per address data byte. Do not rely on this format in portable code, -as it may depend on implementation defined constants, data sizes, and -data structure alignment. -@end itemize - -@item :nowait @var{bool} -If @var{bool} is non-@code{nil} for a stream connection, return -without waiting for the connection to complete. When the connection -succeeds or fails, Emacs will call the sentinel function, with a -second argument matching @code{"open"} (if successful) or -@code{"failed"}. The default is to block, so that -@code{make-network-process} does not return until the connection -has succeeded or failed. - -@item :stop @var{stopped} -If @var{stopped} is non-@code{nil}, start the network connection or -server in the ``stopped'' state. - -@item :buffer @var{buffer} -Use @var{buffer} as the process buffer. - -@item :coding @var{coding} -Use @var{coding} as the coding system for this process. To specify -different coding systems for decoding data from the connection and for -encoding data sent to it, specify @code{(@var{decoding} . -@var{encoding})} for @var{coding}. - -If you don't specify this keyword at all, the default -is to determine the coding systems from the data. - -@item :noquery @var{query-flag} -Initialize the process query flag to @var{query-flag}. -@xref{Query Before Exit}. - -@item :filter @var{filter} -Initialize the process filter to @var{filter}. - -@item :filter-multibyte @var{multibyte} -If @var{multibyte} is non-@code{nil}, strings given to the process -filter are multibyte, otherwise they are unibyte. The default is the -default value of @code{enable-multibyte-characters}. - -@item :sentinel @var{sentinel} -Initialize the process sentinel to @var{sentinel}. - -@item :log @var{log} -Initialize the log function of a server process to @var{log}. The log -function is called each time the server accepts a network connection -from a client. The arguments passed to the log function are -@var{server}, @var{connection}, and @var{message}; where @var{server} -is the server process, @var{connection} is the new process for the -connection, and @var{message} is a string describing what has -happened. - -@item :plist @var{plist} -Initialize the process plist to @var{plist}. -@end table - -The original argument list, modified with the actual connection -information, is available via the @code{process-contact} function. -@end defun - -@node Network Options -@subsection Network Options - - The following network options can be specified when you create a -network process. Except for @code{:reuseaddr}, you can also set or -modify these options later, using @code{set-network-process-option}. - - For a server process, the options specified with -@code{make-network-process} are not inherited by the client -connections, so you will need to set the necessary options for each -child connection as it is created. - -@table @asis -@item :bindtodevice @var{device-name} -If @var{device-name} is a non-empty string identifying a network -interface name (see @code{network-interface-list}), only handle -packets received on that interface. If @var{device-name} is @code{nil} -(the default), handle packets received on any interface. - -Using this option may require special privileges on some systems. - -@item :broadcast @var{broadcast-flag} -If @var{broadcast-flag} is non-@code{nil} for a datagram process, the -process will receive datagram packet sent to a broadcast address, and -be able to send packets to a broadcast address. This is ignored for a stream -connection. - -@item :dontroute @var{dontroute-flag} -If @var{dontroute-flag} is non-@code{nil}, the process can only send -to hosts on the same network as the local host. - -@item :keepalive @var{keepalive-flag} -If @var{keepalive-flag} is non-@code{nil} for a stream connection, -enable exchange of low-level keep-alive messages. - -@item :linger @var{linger-arg} -If @var{linger-arg} is non-@code{nil}, wait for successful -transmission of all queued packets on the connection before it is -deleted (see @code{delete-process}). If @var{linger-arg} is an -integer, it specifies the maximum time in seconds to wait for queued -packets to be sent before closing the connection. The default is -@code{nil}, which means to discard unsent queued packets when the -process is deleted. - -@c FIXME Where out-of-band data is ...? -@item :oobinline @var{oobinline-flag} -If @var{oobinline-flag} is non-@code{nil} for a stream connection, -receive out-of-band data in the normal data stream. Otherwise, ignore -out-of-band data. - -@item :priority @var{priority} -Set the priority for packets sent on this connection to the integer -@var{priority}. The interpretation of this number is protocol -specific; such as setting the TOS (type of service) field on IP -packets sent on this connection. It may also have system dependent -effects, such as selecting a specific output queue on the network -interface. - -@item :reuseaddr @var{reuseaddr-flag} -If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream -server process, allow this server to reuse a specific port number (see -@code{:service}), unless another process on this host is already -listening on that port. If @var{reuseaddr-flag} is @code{nil}, there -may be a period of time after the last use of that port (by any -process on the host) where it is not possible to make a new server on -that port. -@end table - -@defun set-network-process-option process option value &optional no-error -This function sets or modifies a network option for network process -@var{process}. The accepted options and values are as for -@code{make-network-process}. If @var{no-error} is non-@code{nil}, -this function returns @code{nil} instead of signaling an error if -@var{option} is not a supported option. If the function successfully -completes, it returns @code{t}. - -The current setting of an option is available via the -@code{process-contact} function. -@end defun - -@node Network Feature Testing -@subsection Testing Availability of Network Features - - To test for the availability of a given network feature, use -@code{featurep} like this: - -@example -(featurep 'make-network-process '(@var{keyword} @var{value})) -@end example - -@noindent -The result of this form is @code{t} if it works to specify -@var{keyword} with value @var{value} in @code{make-network-process}. -Here are some of the @var{keyword}---@var{value} pairs you can test in -this way. - -@table @code -@item (:nowait t) -Non-@code{nil} if non-blocking connect is supported. -@item (:type datagram) -Non-@code{nil} if datagrams are supported. -@item (:family local) -Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported. -@item (:family ipv6) -Non-@code{nil} if IPv6 is supported. -@item (:service t) -Non-@code{nil} if the system can select the port for a server. -@end table - - To test for the availability of a given network option, use -@code{featurep} like this: - -@example -(featurep 'make-network-process '@var{keyword}) -@end example - -@noindent -The accepted @var{keyword} values are @code{:bindtodevice}, etc. -For the complete list, @pxref{Network Options}. This form returns -non-@code{nil} if that particular network option is supported by -@code{make-network-process} (or @code{set-network-process-option}). - -@node Misc Network -@section Misc Network Facilities - - These additional functions are useful for creating and operating -on network connections. Note that they are supported only on some -systems. - -@defun network-interface-list -This function returns a list describing the network interfaces -of the machine you are using. The value is an alist whose -elements have the form @code{(@var{name} . @var{address})}. -@var{address} has the same form as the @var{local-address} -and @var{remote-address} arguments to @code{make-network-process}. -@end defun - -@defun network-interface-info ifname -This function returns information about the network interface named -@var{ifname}. The value is a list of the form -@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}. - -@table @var -@item addr -The Internet protocol address. -@item bcast -The broadcast address. -@item netmask -The network mask. -@item hwaddr -The layer 2 address (Ethernet MAC address, for instance). -@item flags -The current flags of the interface. -@end table -@end defun - -@defun format-network-address address &optional omit-port -This function converts the Lisp representation of a network address to -a string. - -A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} -represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port -number @var{p}. @code{format-network-address} converts that to the -string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}. - -A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e} -@var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along -with a port number. @code{format-network-address} converts that to -the string -@code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}. - -If the vector does not include the port number, @var{p}, or if -@var{omit-port} is non-@code{nil}, the result does not include the -@code{:@var{p}} suffix. -@end defun - -@node Serial Ports -@section Communicating with Serial Ports -@cindex @file{/dev/tty} -@cindex @file{COM1} -@cindex serial connections - - Emacs can communicate with serial ports. For interactive use, -@kbd{M-x serial-term} opens a terminal window. In a Lisp program, -@code{make-serial-process} creates a process object. - - The serial port can be configured at run-time, without having to -close and re-open it. The function @code{serial-process-configure} -lets you change the speed, bytesize, and other parameters. In a -terminal window created by @code{serial-term}, you can click on the -mode line for configuration. - - A serial connection is represented by a process object, which can be -used in a similar way to a subprocess or network process. You can send and -receive data, and configure the serial port. A serial process object -has no process ID, however, and you can't send signals to it, and the -status codes are different from other types of processes. -@code{delete-process} on the process object or @code{kill-buffer} on -the process buffer close the connection, but this does not affect the -device connected to the serial port. - - The function @code{process-type} returns the symbol @code{serial} -for a process object representing a serial port connection. - - Serial ports are available on GNU/Linux, Unix, and MS Windows systems. - -@deffn Command serial-term port speed -Start a terminal-emulator for a serial port in a new buffer. -@var{port} is the name of the serial port to connect to. For -example, this could be @file{/dev/ttyS0} on Unix. On MS Windows, this -could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in -Lisp strings). - -@c FIXME is 9600 still the most common value, or is it 115200 now? -@c (Same value, 9600, appears below as well.) -@var{speed} is the speed of the serial port in bits per second. 9600 -is a common value. The buffer is in Term mode; see @ref{Term Mode,,, -emacs, The GNU Emacs Manual}, for the commands to use in that buffer. -You can change the speed and the configuration in the mode line menu. -@end deffn - -@defun make-serial-process &rest args -This function creates a process and a buffer. Arguments are specified -as keyword/argument pairs. Here's the list of the meaningful -keywords, with the first two (@var{port} and @var{speed}) being mandatory: - -@table @code -@item :port @var{port} -This is the name of the serial port. On Unix and GNU systems, this is -a file name such as @file{/dev/ttyS0}. On Windows, this could be -@file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9} -(double the backslashes in Lisp strings). - -@item :speed @var{speed} -The speed of the serial port in bits per second. This function calls -@code{serial-process-configure} to handle the speed; see the -following documentation of that function for more details. - -@item :name @var{name} -The name of the process. If @var{name} is not given, @var{port} will -serve as the process name as well. - -@item :buffer @var{buffer} -The buffer to associate with the process. The value can be either a -buffer or a string that names a buffer. Process output goes at the -end of that buffer, unless you specify an output stream or filter -function to handle the output. If @var{buffer} is not given, the -process buffer's name is taken from the value of the @code{:name} -keyword. - -@item :coding @var{coding} -If @var{coding} is a symbol, it specifies the coding system used for -both reading and writing for this process. If @var{coding} is a cons -@code{(@var{decoding} . @var{encoding})}, @var{decoding} is used for -reading, and @var{encoding} is used for writing. If not specified, -the default is to determine the coding systems from the data itself. - -@item :noquery @var{query-flag} -Initialize the process query flag to @var{query-flag}. @xref{Query -Before Exit}. The flags defaults to @code{nil} if unspecified. - -@item :stop @var{bool} -Start process in the ``stopped'' state if @var{bool} is -non-@code{nil}. In the stopped state, a serial process does not -accept incoming data, but you can send outgoing data. The stopped -state is cleared by @code{continue-process} and set by -@code{stop-process}. - -@item :filter @var{filter} -Install @var{filter} as the process filter. - -@item :sentinel @var{sentinel} -Install @var{sentinel} as the process sentinel. - -@item :plist @var{plist} -Install @var{plist} as the initial plist of the process. - -@item :bytesize -@itemx :parity -@itemx :stopbits -@itemx :flowcontrol -These are handled by @code{serial-process-configure}, which is called -by @code{make-serial-process}. -@end table - -The original argument list, possibly modified by later configuration, -is available via the function @code{process-contact}. - -Here is an example: - -@example -(make-serial-process :port "/dev/ttyS0" :speed 9600) -@end example -@end defun - -@defun serial-process-configure &rest args -@cindex baud, in serial connections -@cindex bytesize, in serial connections -@cindex parity, in serial connections -@cindex stopbits, in serial connections -@cindex flowcontrol, in serial connections - -This function configures a serial port connection. Arguments are -specified as keyword/argument pairs. Attributes that are not given -are re-initialized from the process's current configuration (available -via the function @code{process-contact}), or set to reasonable default -values. The following arguments are defined: - -@table @code -@item :process @var{process} -@itemx :name @var{name} -@itemx :buffer @var{buffer} -@itemx :port @var{port} -Any of these arguments can be given to identify the process that is to -be configured. If none of these arguments is given, the current -buffer's process is used. - -@item :speed @var{speed} -The speed of the serial port in bits per second, a.k.a.@: @dfn{baud -rate}. The value can be any number, but most serial ports work only -at a few defined values between 1200 and 115200, with 9600 being the -most common value. If @var{speed} is @code{nil}, the function ignores -all other arguments and does not configure the port. This may be -useful for special serial ports such as Bluetooth-to-serial converters, -which can only be configured through @samp{AT} commands sent through the -connection. The value of @code{nil} for @var{speed} is valid only for -connections that were already opened by a previous call to -@code{make-serial-process} or @code{serial-term}. - -@item :bytesize @var{bytesize} -The number of bits per byte, which can be 7 or 8. If @var{bytesize} -is not given or @code{nil}, it defaults to 8. - -@item :parity @var{parity} -The value can be @code{nil} (don't use parity), the symbol -@code{odd} (use odd parity), or the symbol @code{even} (use even -parity). If @var{parity} is not given, it defaults to no parity. - -@item :stopbits @var{stopbits} -The number of stopbits used to terminate a transmission -of each byte. @var{stopbits} can be 1 or 2. If @var{stopbits} is not -given or @code{nil}, it defaults to 1. - -@item :flowcontrol @var{flowcontrol} -The type of flow control to use for this connection, which is either -@code{nil} (don't use flow control), the symbol @code{hw} (use RTS/CTS -hardware flow control), or the symbol @code{sw} (use XON/XOFF software -flow control). If @var{flowcontrol} is not given, it defaults to no -flow control. -@end table - -Internally, @code{make-serial-process} calls -@code{serial-process-configure} for the initial configuration of the -serial port. -@end defun - -@node Byte Packing -@section Packing and Unpacking Byte Arrays -@cindex byte packing and unpacking - - This section describes how to pack and unpack arrays of bytes, -usually for binary network protocols. These functions convert byte arrays -to alists, and vice versa. The byte array can be represented as a -@c FIXME? No multibyte? -unibyte string or as a vector of integers, while the alist associates -symbols either with fixed-size objects or with recursive sub-alists. -To use the functions referred to in this section, load the -@code{bindat} library. -@c It doesn't have any autoloads. - -@cindex serializing -@cindex deserializing -@cindex packing -@cindex unpacking - Conversion from byte arrays to nested alists is also known as -@dfn{deserializing} or @dfn{unpacking}, while going in the opposite -direction is also known as @dfn{serializing} or @dfn{packing}. - -@menu -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! -@end menu - -@node Bindat Spec -@subsection Describing Data Layout - - To control unpacking and packing, you write a @dfn{data layout -specification}, a special nested list describing named and typed -@dfn{fields}. This specification controls the length of each field to be -processed, and how to pack or unpack it. We normally keep bindat specs -in variables whose names end in @samp{-bindat-spec}; that kind of name -is automatically recognized as ``risky''. - -@cindex endianness -@cindex big endian -@cindex little endian -@cindex network byte ordering - A field's @dfn{type} describes the size (in bytes) of the object -that the field represents and, in the case of multibyte fields, how -the bytes are ordered within the field. The two possible orderings -are ``big endian'' (also known as ``network byte ordering'') and -``little endian''. For instance, the number @code{#x23cd} (decimal -9165) in big endian would be the two bytes @code{#x23} @code{#xcd}; -and in little endian, @code{#xcd} @code{#x23}. Here are the possible -type values: - -@table @code -@item u8 -@itemx byte -Unsigned byte, with length 1. - -@item u16 -@itemx word -@itemx short -Unsigned integer in network byte order, with length 2. - -@item u24 -Unsigned integer in network byte order, with length 3. - -@item u32 -@itemx dword -@itemx long -Unsigned integer in network byte order, with length 4. -Note: These values may be limited by Emacs's integer implementation limits. - -@item u16r -@itemx u24r -@itemx u32r -Unsigned integer in little endian order, with length 2, 3 and 4, respectively. - -@item str @var{len} -String of length @var{len}. - -@item strz @var{len} -Zero-terminated string, in a fixed-size field with length @var{len}. - -@item vec @var{len} [@var{type}] -Vector of @var{len} elements of type @var{type}, defaulting to bytes. -The @var{type} is any of the simple types above, or another vector -specified as a list of the form @code{(vec @var{len} [@var{type}])}. - -@item ip -@c FIXME? IPv6? -Four-byte vector representing an Internet address. For example: -@code{[127 0 0 1]} for localhost. - -@item bits @var{len} -List of set bits in @var{len} bytes. The bytes are taken in big -endian order and the bits are numbered starting with @code{8 * -@var{len} @minus{} 1} and ending with zero. For example: @code{bits -2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and -@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}. - -@item (eval @var{form}) -@var{form} is a Lisp expression evaluated at the moment the field is -unpacked or packed. The result of the evaluation should be one of the -above-listed type specifications. -@end table - -For a fixed-size field, the length @var{len} is given as an integer -specifying the number of bytes in the field. - -When the length of a field is not fixed, it typically depends on the -value of a preceding field. In this case, the length @var{len} can be -given either as a list @code{(@var{name} ...)} identifying a -@dfn{field name} in the format specified for @code{bindat-get-field} -below, or by an expression @code{(eval @var{form})} where @var{form} -should evaluate to an integer, specifying the field length. - -A field specification generally has the form @code{([@var{name}] -@var{handler})}, where @var{name} is optional. Don't use names that -are symbols meaningful as type specifications (above) or handler -specifications (below), since that would be ambiguous. @var{name} can -be a symbol or an expression @code{(eval @var{form})}, in which case -@var{form} should evaluate to a symbol. - -@var{handler} describes how to unpack or pack the field and can be one -of the following: - -@table @code -@item @var{type} -Unpack/pack this field according to the type specification @var{type}. - -@item eval @var{form} -Evaluate @var{form}, a Lisp expression, for side-effect only. If the -field name is specified, the value is bound to that field name. - -@item fill @var{len} -Skip @var{len} bytes. In packing, this leaves them unchanged, -which normally means they remain zero. In unpacking, this means -they are ignored. - -@item align @var{len} -Skip to the next multiple of @var{len} bytes. - -@item struct @var{spec-name} -Process @var{spec-name} as a sub-specification. This describes a -structure nested within another structure. - -@item union @var{form} (@var{tag} @var{spec})@dots{} -@c ??? I don't see how one would actually use this. -@c ??? what kind of expression would be useful for @var{form}? -Evaluate @var{form}, a Lisp expression, find the first @var{tag} -that matches it, and process its associated data layout specification -@var{spec}. Matching can occur in one of three ways: - -@itemize -@item -If a @var{tag} has the form @code{(eval @var{expr})}, evaluate -@var{expr} with the variable @code{tag} dynamically bound to the value -of @var{form}. A non-@code{nil} result indicates a match. - -@item -@var{tag} matches if it is @code{equal} to the value of @var{form}. - -@item -@var{tag} matches unconditionally if it is @code{t}. -@end itemize - -@item repeat @var{count} @var{field-specs}@dots{} -Process the @var{field-specs} recursively, in order, then repeat -starting from the first one, processing all the specifications @var{count} -times overall. The @var{count} is given using the same formats as a -field length---if an @code{eval} form is used, it is evaluated just once. -For correct operation, each specification in @var{field-specs} must -include a name. -@end table - -For the @code{(eval @var{form})} forms used in a bindat specification, -the @var{form} can access and update these dynamically bound variables -during evaluation: - -@table @code -@item last -Value of the last field processed. - -@item bindat-raw -The data as a byte array. - -@item bindat-idx -Current index (within @code{bindat-raw}) for unpacking or packing. - -@item struct -The alist containing the structured data that have been unpacked so -far, or the entire structure being packed. You can use -@code{bindat-get-field} to access specific fields of this structure. - -@item count -@itemx index -Inside a @code{repeat} block, these contain the maximum number of -repetitions (as specified by the @var{count} parameter), and the -current repetition number (counting from 0). Setting @code{count} to -zero will terminate the inner-most repeat block after the current -repetition has completed. -@end table - -@node Bindat Functions -@subsection Functions to Unpack and Pack Bytes - - In the following documentation, @var{spec} refers to a data layout -specification, @code{bindat-raw} to a byte array, and @var{struct} to an -alist representing unpacked field data. - -@defun bindat-unpack spec bindat-raw &optional bindat-idx -@c FIXME? Again, no multibyte? -This function unpacks data from the unibyte string or byte -array @code{bindat-raw} -according to @var{spec}. Normally, this starts unpacking at the -beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it -specifies a zero-based starting position to use instead. - -The value is an alist or nested alist in which each element describes -one unpacked field. -@end defun - -@defun bindat-get-field struct &rest name -This function selects a field's data from the nested alist -@var{struct}. Usually @var{struct} was returned by -@code{bindat-unpack}. If @var{name} corresponds to just one argument, -that means to extract a top-level field value. Multiple @var{name} -arguments specify repeated lookup of sub-structures. An integer name -acts as an array index. - -For example, if @var{name} is @code{(a b 2 c)}, that means to find -field @code{c} in the third element of subfield @code{b} of field -@code{a}. (This corresponds to @code{struct.a.b[2].c} in C.) -@end defun - - Although packing and unpacking operations change the organization of -data (in memory), they preserve the data's @dfn{total length}, which is -the sum of all the fields' lengths, in bytes. This value is not -generally inherent in either the specification or alist alone; instead, -both pieces of information contribute to its calculation. Likewise, the -length of a string or array being unpacked may be longer than the data's -total length as described by the specification. - -@defun bindat-length spec struct -This function returns the total length of the data in @var{struct}, -according to @var{spec}. -@end defun - -@defun bindat-pack spec struct &optional bindat-raw bindat-idx -This function returns a byte array packed according to @var{spec} from -the data in the alist @var{struct}. It normally creates and fills a -new byte array starting at the beginning. However, if @var{bindat-raw} -is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to -pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting -offset for packing into @code{bindat-raw}. - -When pre-allocating, you should make sure @code{(length @var{bindat-raw})} -meets or exceeds the total length to avoid an out-of-range error. -@end defun - -@defun bindat-ip-to-string ip -Convert the Internet address vector @var{ip} to a string in the usual -dotted notation. -@c FIXME? Does it do IPv6? - -@example -(bindat-ip-to-string [127 0 0 1]) - @result{} "127.0.0.1" -@end example -@end defun - -@node Bindat Examples -@subsection Examples of Byte Unpacking and Packing -@c FIXME? This seems a very long example for something that is not used -@c very often. As of 24.1, gdb-mi.el is the only user of bindat.el in Emacs. -@c Maybe one or both of these examples should just be moved to the -@c commentary of bindat.el. - - Here is a complete example of byte unpacking and packing: - -@lisp -(require 'bindat) - -(defvar fcookie-index-spec - '((:version u32) - (:count u32) - (:longest u32) - (:shortest u32) - (:flags u32) - (:delim u8) - (:ignored fill 3) - (:offset repeat (:count) (:foo u32))) - "Description of a fortune cookie index file's contents.") - -(defun fcookie (cookies &optional index) - "Display a random fortune cookie from file COOKIES. -Optional second arg INDEX specifies the associated index -filename, by default \"COOKIES.dat\". Display cookie text -in buffer \"*Fortune Cookie: BASENAME*\", where BASENAME -is COOKIES without the directory part." - (interactive "fCookies file: ") - (let* ((info (with-temp-buffer - (insert-file-contents-literally - (or index (concat cookies ".dat"))) - (bindat-unpack fcookie-index-spec - (buffer-string)))) - (sel (random (bindat-get-field info :count))) - (beg (cdar (bindat-get-field info :offset sel))) - (end (or (cdar (bindat-get-field info - :offset (1+ sel))) - (nth 7 (file-attributes cookies))))) - (switch-to-buffer - (get-buffer-create - (format "*Fortune Cookie: %s*" - (file-name-nondirectory cookies)))) - (erase-buffer) - (insert-file-contents-literally - cookies nil beg (- end 3)))) - -(defun fcookie-create-index (cookies &optional index delim) - "Scan file COOKIES, and write out its index file. -Optional arg INDEX specifies the index filename, which by -default is \"COOKIES.dat\". Optional arg DELIM specifies the -unibyte character that, when found on a line of its own in -COOKIES, indicates the border between entries." - (interactive "fCookies file: ") - (setq delim (or delim ?%)) - (let ((delim-line (format "\n%c\n" delim)) - (count 0) - (max 0) - min p q len offsets) - (unless (= 3 (string-bytes delim-line)) - (error "Delimiter cannot be represented in one byte")) - (with-temp-buffer - (insert-file-contents-literally cookies) - (while (and (setq p (point)) - (search-forward delim-line (point-max) t) - (setq len (- (point) 3 p))) - (setq count (1+ count) - max (max max len) - min (min (or min max) len) - offsets (cons (1- p) offsets)))) - (with-temp-buffer - (set-buffer-multibyte nil) - (insert - (bindat-pack - fcookie-index-spec - `((:version . 2) - (:count . ,count) - (:longest . ,max) - (:shortest . ,min) - (:flags . 0) - (:delim . ,delim) - (:offset . ,(mapcar (lambda (o) - (list (cons :foo o))) - (nreverse offsets)))))) - (let ((coding-system-for-write 'raw-text-unix)) - (write-file (or index (concat cookies ".dat"))))))) -@end lisp - -The following is an example of defining and unpacking a complex -structure. Consider the following C structures: - -@example -struct header @{ - unsigned long dest_ip; - unsigned long src_ip; - unsigned short dest_port; - unsigned short src_port; -@}; - -struct data @{ - unsigned char type; - unsigned char opcode; - unsigned short length; /* in network byte order */ - unsigned char id[8]; /* null-terminated string */ - unsigned char data[/* (length + 3) & ~3 */]; -@}; - -struct packet @{ - struct header header; - unsigned long counters[2]; /* in little endian order */ - unsigned char items; - unsigned char filler[3]; - struct data item[/* items */]; - -@}; -@end example - -The corresponding data layout specification is: - -@lisp -(setq header-spec - '((dest-ip ip) - (src-ip ip) - (dest-port u16) - (src-port u16))) - -(setq data-spec - '((type u8) - (opcode u8) - (length u16) ; network byte order - (id strz 8) - (data vec (length)) - (align 4))) - -(setq packet-spec - '((header struct header-spec) - (counters vec 2 u32r) ; little endian order - (items u8) - (fill 3) - (item repeat (items) - (struct data-spec)))) -@end lisp - -A binary data representation is: - -@lisp -(setq binary-data - [ 192 168 1 100 192 168 1 101 01 28 21 32 - 160 134 1 0 5 1 0 0 2 0 0 0 - 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 - 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) -@end lisp - -The corresponding decoded structure is: - -@lisp -(setq decoded (bindat-unpack packet-spec binary-data)) - @result{} -((header - (dest-ip . [192 168 1 100]) - (src-ip . [192 168 1 101]) - (dest-port . 284) - (src-port . 5408)) - (counters . [100000 261]) - (items . 2) - (item ((data . [1 2 3 4 5]) - (id . "ABCDEF") - (length . 5) - (opcode . 3) - (type . 2)) - ((data . [6 7 8 9 10 11 12]) - (id . "BCDEFG") - (length . 7) - (opcode . 4) - (type . 1)))) -@end lisp - -An example of fetching data from this structure: - -@lisp -(bindat-get-field decoded 'item 1 'id) - @result{} "BCDEFG" -@end lisp diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi deleted file mode 100644 index 992ad001fe7..00000000000 --- a/doc/lispref/searching.texi +++ /dev/null @@ -1,1911 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Searching and Matching -@chapter Searching and Matching -@cindex searching - - GNU Emacs provides two ways to search through a buffer for specified -text: exact string searches and regular expression searches. After a -regular expression search, you can examine the @dfn{match data} to -determine which text matched the whole regular expression or various -portions of it. - -@menu -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... -@end menu - - The @samp{skip-chars@dots{}} functions also perform a kind of searching. -@xref{Skipping Characters}. To search for changes in character -properties, see @ref{Property Search}. - -@node String Search -@section Searching for Strings -@cindex string search - - These are the primitive functions for searching through the text in a -buffer. They are meant for use in programs, but you may call them -interactively. If you do so, they prompt for the search string; the -arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat} -is 1. For more details on interactive searching, @pxref{Search,, -Searching and Replacement, emacs, The GNU Emacs Manual}. - - These search functions convert the search string to multibyte if the -buffer is multibyte; they convert the search string to unibyte if the -buffer is unibyte. @xref{Text Representations}. - -@deffn Command search-forward string &optional limit noerror repeat -This function searches forward from point for an exact match for -@var{string}. If successful, it sets point to the end of the occurrence -found, and returns the new value of point. If no match is found, the -value and side effects depend on @var{noerror} (see below). - -In the following example, point is initially at the beginning of the -line. Then @code{(search-forward "fox")} moves point after the last -letter of @samp{fox}: - -@example -@group ----------- Buffer: foo ---------- -@point{}The quick brown fox jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group - -@group -(search-forward "fox") - @result{} 20 - ----------- Buffer: foo ---------- -The quick brown fox@point{} jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group -@end example - -The argument @var{limit} specifies the bound to the search, and should -be a position in the current buffer. No match extending after -that position is accepted. If @var{limit} is omitted or @code{nil}, it -defaults to the end of the accessible portion of the buffer. - -@kindex search-failed -What happens when the search fails depends on the value of -@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed} -error is signaled. If @var{noerror} is @code{t}, @code{search-forward} -returns @code{nil} and does nothing. If @var{noerror} is neither -@code{nil} nor @code{t}, then @code{search-forward} moves point to the -upper bound and returns @code{nil}. -@c I see no prospect of this ever changing, and frankly the current -@c behavior seems better, so there seems no need to mention this. -@ignore -(It would be more consistent now to return the new position of point -in that case, but some existing programs may depend on a value of -@code{nil}.) -@end ignore - -The argument @var{noerror} only affects valid searches which fail to -find a match. Invalid arguments cause errors regardless of -@var{noerror}. - -If @var{repeat} is a positive number @var{n}, it serves as a repeat -count: the search is repeated @var{n} times, each time starting at the -end of the previous time's match. If these successive searches -succeed, the function succeeds, moving point and returning its new -value. Otherwise the search fails, with results depending on the -value of @var{noerror}, as described above. If @var{repeat} is a -negative number -@var{n}, it serves as a repeat count of @var{n} for a -search in the opposite (backward) direction. -@end deffn - -@deffn Command search-backward string &optional limit noerror repeat -This function searches backward from point for @var{string}. It is -like @code{search-forward}, except that it searches backwards rather -than forwards. Backward searches leave point at the beginning of the -match. -@end deffn - -@deffn Command word-search-forward string &optional limit noerror repeat -This function searches forward from point for a ``word'' match for -@var{string}. If it finds a match, it sets point to the end of the -match found, and returns the new value of point. - -Word matching regards @var{string} as a sequence of words, disregarding -punctuation that separates them. It searches the buffer for the same -sequence of words. Each word must be distinct in the buffer (searching -for the word @samp{ball} does not match the word @samp{balls}), but the -details of punctuation and spacing are ignored (searching for @samp{ball -boy} does match @samp{ball. Boy!}). - -In this example, point is initially at the beginning of the buffer; the -search leaves it between the @samp{y} and the @samp{!}. - -@example -@group ----------- Buffer: foo ---------- -@point{}He said "Please! Find -the ball boy!" ----------- Buffer: foo ---------- -@end group - -@group -(word-search-forward "Please find the ball, boy.") - @result{} 39 - ----------- Buffer: foo ---------- -He said "Please! Find -the ball boy@point{}!" ----------- Buffer: foo ---------- -@end group -@end example - -If @var{limit} is non-@code{nil}, it must be a position in the current -buffer; it specifies the upper bound to the search. The match found -must not extend after that position. - -If @var{noerror} is @code{nil}, then @code{word-search-forward} signals -an error if the search fails. If @var{noerror} is @code{t}, then it -returns @code{nil} instead of signaling an error. If @var{noerror} is -neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the -end of the accessible portion of the buffer) and returns @code{nil}. - -If @var{repeat} is non-@code{nil}, then the search is repeated that many -times. Point is positioned at the end of the last match. - -@findex word-search-regexp -Internally, @code{word-search-forward} and related functions use the -function @code{word-search-regexp} to convert @var{string} to a -regular expression that ignores punctuation. -@end deffn - -@deffn Command word-search-forward-lax string &optional limit noerror repeat -This command is identical to @code{word-search-forward}, except that -the beginning or the end of @var{string} need not match a word -boundary, unless @var{string} begins or ends in whitespace. -For instance, searching for @samp{ball boy} matches @samp{ball boyee}, -but does not match @samp{balls boy}. -@end deffn - -@deffn Command word-search-backward string &optional limit noerror repeat -This function searches backward from point for a word match to -@var{string}. This function is just like @code{word-search-forward} -except that it searches backward and normally leaves point at the -beginning of the match. -@end deffn - -@deffn Command word-search-backward-lax string &optional limit noerror repeat -This command is identical to @code{word-search-backward}, except that -the beginning or the end of @var{string} need not match a word -boundary, unless @var{string} begins or ends in whitespace. -@end deffn - -@node Searching and Case -@section Searching and Case -@cindex searching and case - - By default, searches in Emacs ignore the case of the text they are -searching through; if you specify searching for @samp{FOO}, then -@samp{Foo} or @samp{foo} is also considered a match. This applies to -regular expressions, too; thus, @samp{[aB]} would match @samp{a} or -@samp{A} or @samp{b} or @samp{B}. - - If you do not want this feature, set the variable -@code{case-fold-search} to @code{nil}. Then all letters must match -exactly, including case. This is a buffer-local variable; altering the -variable affects only the current buffer. (@xref{Intro to -Buffer-Local}.) Alternatively, you may change the default value. -In Lisp code, you will more typically use @code{let} to bind -@code{case-fold-search} to the desired value. - - Note that the user-level incremental search feature handles case -distinctions differently. When the search string contains only lower -case letters, the search ignores case, but when the search string -contains one or more upper case letters, the search becomes -case-sensitive. But this has nothing to do with the searching -functions used in Lisp code. @xref{Incremental Search,,, emacs, -The GNU Emacs Manual}. - -@defopt case-fold-search -This buffer-local variable determines whether searches should ignore -case. If the variable is @code{nil} they do not ignore case; otherwise -(and by default) they do ignore case. -@end defopt - -@defopt case-replace -This variable determines whether the higher-level replacement -functions should preserve case. If the variable is @code{nil}, that -means to use the replacement text verbatim. A non-@code{nil} value -means to convert the case of the replacement text according to the -text being replaced. - -This variable is used by passing it as an argument to the function -@code{replace-match}. @xref{Replacing Match}. -@end defopt - -@node Regular Expressions -@section Regular Expressions -@cindex regular expression -@cindex regexp - - A @dfn{regular expression}, or @dfn{regexp} for short, is a pattern that -denotes a (possibly infinite) set of strings. Searching for matches for -a regexp is a very powerful operation. This section explains how to write -regexps; the following section says how to search for them. - -@findex re-builder -@cindex regular expressions, developing - For interactive development of regular expressions, you -can use the @kbd{M-x re-builder} command. It provides a convenient -interface for creating regular expressions, by giving immediate visual -feedback in a separate buffer. As you edit the regexp, all its -matches in the target buffer are highlighted. Each parenthesized -sub-expression of the regexp is shown in a distinct face, which makes -it easier to verify even very complex regexps. - -@menu -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. -@end menu - -@node Syntax of Regexps -@subsection Syntax of Regular Expressions - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are @dfn{ordinary}. An ordinary -character is a simple regular expression that matches that character -and nothing else. The special characters are @samp{.}, @samp{*}, -@samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new -special characters will be defined in the future. The character -@samp{]} is special if it ends a character alternative (see later). -The character @samp{-} is special inside a character alternative. A -@samp{[:} and balancing @samp{:]} enclose a character class inside a -character alternative. Any other character appearing in a regular -expression is ordinary, unless a @samp{\} precedes it. - - For example, @samp{f} is not a special character, so it is ordinary, and -therefore @samp{f} is a regular expression that matches the string -@samp{f} and no other string. (It does @emph{not} match the string -@samp{fg}, but it does match a @emph{part} of that string.) Likewise, -@samp{o} is a regular expression that matches only @samp{o}. - - Any two regular expressions @var{a} and @var{b} can be concatenated. The -result is a regular expression that matches a string if @var{a} matches -some amount of the beginning of that string and @var{b} matches the rest of -the string. - - As a simple example, we can concatenate the regular expressions @samp{f} -and @samp{o} to get the regular expression @samp{fo}, which matches only -the string @samp{fo}. Still trivial. To do something more powerful, you -need to use one of the special regular expression constructs. - -@menu -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. -@end menu - -@node Regexp Special -@subsubsection Special Characters in Regular Expressions - - Here is a list of the characters that are special in a regular -expression. - -@need 800 -@table @asis -@item @samp{.}@: @r{(Period)} -@cindex @samp{.} in regexp -is a special character that matches any single character except a newline. -Using concatenation, we can make regular expressions like @samp{a.b}, which -matches any three-character string that begins with @samp{a} and ends with -@samp{b}. - -@item @samp{*} -@cindex @samp{*} in regexp -is not a construct by itself; it is a postfix operator that means to -match the preceding regular expression repetitively as many times as -possible. Thus, @samp{o*} matches any number of @samp{o}s (including no -@samp{o}s). - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating -@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. - -@cindex backtracking and regular expressions -The matcher processes a @samp{*} construct by matching, immediately, as -many repetitions as can be found. Then it continues with the rest of -the pattern. If that fails, backtracking occurs, discarding some of the -matches of the @samp{*}-modified construct in the hope that that will -make it possible to match the rest of the pattern. For example, in -matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} -first tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. With -this choice, the rest of the regexp matches successfully. - -@strong{Warning:} Nested repetition operators can run for an -indefinitely long time, if they lead to ambiguous matching. For -example, trying to match the regular expression @samp{\(x+y*\)*a} -against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could -take hours before it ultimately fails. Emacs must try each way of -grouping the @samp{x}s before concluding that none of them can work. -Even worse, @samp{\(x*\)*} can match the null string in infinitely -many ways, so it causes an infinite loop. To avoid these problems, -check nested repetitions carefully, to make sure that they do not -cause combinatorial explosions in backtracking. - -@item @samp{+} -@cindex @samp{+} in regexp -is a postfix operator, similar to @samp{*} except that it must match -the preceding expression at least once. So, for example, @samp{ca+r} -matches the strings @samp{car} and @samp{caaaar} but not the string -@samp{cr}, whereas @samp{ca*r} matches all three strings. - -@item @samp{?} -@cindex @samp{?} in regexp -is a postfix operator, similar to @samp{*} except that it must match the -preceding expression either once or not at all. For example, -@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. - -@item @samp{*?}, @samp{+?}, @samp{??} -@cindex non-greedy repetition characters in regexp -These are ``non-greedy'' variants of the operators @samp{*}, @samp{+} -and @samp{?}. Where those operators match the largest possible -substring (consistent with matching the entire containing expression), -the non-greedy variants match the smallest possible substring -(consistent with matching the entire containing expression). - -For example, the regular expression @samp{c[ad]*a} when applied to the -string @samp{cdaaada} matches the whole string; but the regular -expression @samp{c[ad]*?a}, applied to that same string, matches just -@samp{cda}. (The smallest possible match here for @samp{[ad]*?} that -permits the whole expression to match is @samp{d}.) - -@item @samp{[ @dots{} ]} -@cindex character alternative (in regexp) -@cindex @samp{[} in regexp -@cindex @samp{]} in regexp -is a @dfn{character alternative}, which begins with @samp{[} and is -terminated by @samp{]}. In the simplest case, the characters between -the two brackets are what this character alternative can match. - -Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and -@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s -(including the empty string). It follows that @samp{c[ad]*r} -matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. - -You can also include character ranges in a character alternative, by -writing the starting and ending characters with a @samp{-} between them. -Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter. -Ranges may be intermixed freely with individual characters, as in -@samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter -or @samp{$}, @samp{%} or period. - -If @code{case-fold-search} is non-@code{nil}, @samp{[a-z]} also -matches upper-case letters. Note that a range like @samp{[a-z]} is -not affected by the locale's collation sequence, it always represents -a sequence in @acronym{ASCII} order. -@c This wasn't obvious to me, since, e.g., the grep manual "Character -@c Classes and Bracket Expressions" specifically notes the opposite -@c behavior. But by experiment Emacs seems unaffected by LC_COLLATE -@c in this regard. - -Note also that the usual regexp special characters are not special inside a -character alternative. A completely different set of characters is -special inside character alternatives: @samp{]}, @samp{-} and @samp{^}. - -To include a @samp{]} in a character alternative, you must make it the -first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. -To include a @samp{-}, write @samp{-} as the first or last character of -the character alternative, or put it after a range. Thus, @samp{[]-]} -matches both @samp{]} and @samp{-}. (As explained below, you cannot -use @samp{\]} to include a @samp{]} inside a character alternative, -since @samp{\} is not special there.) - -To include @samp{^} in a character alternative, put it anywhere but at -the beginning. - -@c What if it starts with a multibyte and ends with a unibyte? -@c That doesn't seem to match anything...? -If a range starts with a unibyte character @var{c} and ends with a -multibyte character @var{c2}, the range is divided into two parts: one -spans the unibyte characters @samp{@var{c}..?\377}, the other the -multibyte characters @samp{@var{c1}..@var{c2}}, where @var{c1} is the -first character of the charset to which @var{c2} belongs. - -A character alternative can also specify named character classes -(@pxref{Char Classes}). This is a POSIX feature. For example, -@samp{[[:ascii:]]} matches any @acronym{ASCII} character. -Using a character class is equivalent to mentioning each of the -characters in that class; but the latter is not feasible in practice, -since some classes include thousands of different characters. - -@item @samp{[^ @dots{} ]} -@cindex @samp{^} in regexp -@samp{[^} begins a @dfn{complemented character alternative}. This -matches any character except the ones specified. Thus, -@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and -digits. - -@samp{^} is not special in a character alternative unless it is the first -character. The character following the @samp{^} is treated as if it -were first (in other words, @samp{-} and @samp{]} are not special there). - -A complemented character alternative can match a newline, unless newline is -mentioned as one of the characters not to match. This is in contrast to -the handling of regexps in programs such as @code{grep}. - -You can specify named character classes, just like in character -alternatives. For instance, @samp{[^[:ascii:]]} matches any -non-@acronym{ASCII} character. @xref{Char Classes}. - -@item @samp{^} -@cindex beginning of line in regexp -When matching a buffer, @samp{^} matches the empty string, but only at the -beginning of a line in the text being matched (or the beginning of the -accessible portion of the buffer). Otherwise it fails to match -anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the -beginning of a line. - -When matching a string instead of a buffer, @samp{^} matches at the -beginning of the string or after a newline character. - -For historical compatibility reasons, @samp{^} can be used only at the -beginning of the regular expression, or after @samp{\(}, @samp{\(?:} -or @samp{\|}. - -@item @samp{$} -@cindex @samp{$} in regexp -@cindex end of line in regexp -is similar to @samp{^} but matches only at the end of a line (or the -end of the accessible portion of the buffer). Thus, @samp{x+$} -matches a string of one @samp{x} or more at the end of a line. - -When matching a string instead of a buffer, @samp{$} matches at the end -of the string or before a newline character. - -For historical compatibility reasons, @samp{$} can be used only at the -end of the regular expression, or before @samp{\)} or @samp{\|}. - -@item @samp{\} -@cindex @samp{\} in regexp -has two functions: it quotes the special characters (including -@samp{\}), and it introduces additional special constructs. - -Because @samp{\} quotes special characters, @samp{\$} is a regular -expression that matches only @samp{$}, and @samp{\[} is a regular -expression that matches only @samp{[}, and so on. - -Note that @samp{\} also has special meaning in the read syntax of Lisp -strings (@pxref{String Type}), and must be quoted with @samp{\}. For -example, the regular expression that matches the @samp{\} character is -@samp{\\}. To write a Lisp string that contains the characters -@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another -@samp{\}. Therefore, the read syntax for a regular expression matching -@samp{\} is @code{"\\\\"}. -@end table - -@strong{Please note:} For historical compatibility, special characters -are treated as ordinary ones if they are in contexts where their special -meanings make no sense. For example, @samp{*foo} treats @samp{*} as -ordinary since there is no preceding expression on which the @samp{*} -can act. It is poor practice to depend on this behavior; quote the -special character anyway, regardless of where it appears. - -As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. - -In practice, most @samp{]} that occur in regular expressions close a -character alternative and hence are special. However, occasionally a -regular expression may try to match a complex pattern of literal -@samp{[} and @samp{]}. In such situations, it sometimes may be -necessary to carefully parse the regexp from the start to determine -which square brackets enclose a character alternative. For example, -@samp{[^][]]} consists of the complemented character alternative -@samp{[^][]} (which matches any single character that is not a square -bracket), followed by a literal @samp{]}. - -The exact rules are that at the beginning of a regexp, @samp{[} is -special and @samp{]} not. This lasts until the first unquoted -@samp{[}, after which we are in a character alternative; @samp{[} is -no longer special (except when it starts a character class) but @samp{]} -is special, unless it immediately follows the special @samp{[} or that -@samp{[} followed by a @samp{^}. This lasts until the next special -@samp{]} that does not end a character class. This ends the character -alternative and restores the ordinary syntax of regular expressions; -an unquoted @samp{[} is special again and a @samp{]} not. - -@node Char Classes -@subsubsection Character Classes -@cindex character classes in regexp - - Here is a table of the classes you can use in a character alternative, -and what they mean: - -@table @samp -@item [:ascii:] -This matches any @acronym{ASCII} character (codes 0--127). -@item [:alnum:] -This matches any letter or digit. (At present, for multibyte -characters, it matches anything that has word syntax.) -@item [:alpha:] -This matches any letter. (At present, for multibyte characters, it -matches anything that has word syntax.) -@item [:blank:] -This matches space and tab only. -@item [:cntrl:] -This matches any @acronym{ASCII} control character. -@item [:digit:] -This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]} -matches any digit, as well as @samp{+} and @samp{-}. -@item [:graph:] -This matches graphic characters---everything except @acronym{ASCII} control -characters, space, and the delete character. -@item [:lower:] -This matches any lower-case letter, as determined by the current case -table (@pxref{Case Tables}). If @code{case-fold-search} is -non-@code{nil}, this also matches any upper-case letter. -@item [:multibyte:] -This matches any multibyte character (@pxref{Text Representations}). -@item [:nonascii:] -This matches any non-@acronym{ASCII} character. -@item [:print:] -This matches printing characters---everything except @acronym{ASCII} control -characters and the delete character. -@item [:punct:] -This matches any punctuation character. (At present, for multibyte -characters, it matches anything that has non-word syntax.) -@item [:space:] -This matches any character that has whitespace syntax -(@pxref{Syntax Class Table}). -@item [:unibyte:] -This matches any unibyte character (@pxref{Text Representations}). -@item [:upper:] -This matches any upper-case letter, as determined by the current case -table (@pxref{Case Tables}). If @code{case-fold-search} is -non-@code{nil}, this also matches any lower-case letter. -@item [:word:] -This matches any character that has word syntax (@pxref{Syntax Class -Table}). -@item [:xdigit:] -This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a} -through @samp{f} and @samp{A} through @samp{F}. -@end table - -@node Regexp Backslash -@subsubsection Backslash Constructs in Regular Expressions -@cindex backslash in regular expressions - - For the most part, @samp{\} followed by any character matches only -that character. However, there are several exceptions: certain -sequences starting with @samp{\} that have special meanings. Here is -a table of the special @samp{\} constructs. - -@table @samp -@item \| -@cindex @samp{|} in regexp -@cindex regexp alternative -specifies an alternative. -Two regular expressions @var{a} and @var{b} with @samp{\|} in -between form an expression that matches anything that either @var{a} or -@var{b} matches. - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string. - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}. - -If you need full backtracking capability to handle multiple uses of -@samp{\|}, use the POSIX regular expression functions (@pxref{POSIX -Regexps}). - -@item \@{@var{m}\@} -is a postfix operator that repeats the previous pattern exactly @var{m} -times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx} -and nothing else. @samp{c[ad]\@{3\@}r} matches string such as -@samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on. - -@item \@{@var{m},@var{n}\@} -is a more general postfix operator that specifies repetition with a -minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m} -is omitted, the minimum is 0; if @var{n} is omitted, there is no -maximum. - -For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car}, -@samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and -nothing else.@* -@samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}.@* -@samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}.@* -@samp{\@{1,\@}} is equivalent to @samp{+}. - -@item \( @dots{} \) -@cindex @samp{(} in regexp -@cindex @samp{)} in regexp -@cindex regexp grouping -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. Thus, -the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox} -or @samp{barx}. - -@item -To enclose a complicated expression for the postfix operators @samp{*}, -@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches -@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any -number (zero or more) of @samp{na} strings. - -@item -To record a matched substring for future reference with -@samp{\@var{digit}} (see below). -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that was assigned as a -second meaning to the same @samp{\( @dots{} \)} construct because, in -practice, there was usually no conflict between the two meanings. But -occasionally there is a conflict, and that led to the introduction of -shy groups. - -@item \(?: @dots{} \) -@cindex shy groups -@cindex non-capturing group -@cindex unnumbered group -@cindex @samp{(?:} in regexp -is the @dfn{shy group} construct. A shy group serves the first two -purposes of an ordinary group (controlling the nesting of other -operators), but it does not get a number, so you cannot refer back to -its value with @samp{\@var{digit}}. Shy groups are particularly -useful for mechanically-constructed regular expressions, because they -can be added automatically without altering the numbering of ordinary, -non-shy groups. - -Shy groups are also called @dfn{non-capturing} or @dfn{unnumbered -groups}. - -@item \(?@var{num}: @dots{} \) -is the @dfn{explicitly numbered group} construct. Normal groups get -their number implicitly, based on their position, which can be -inconvenient. This construct allows you to force a particular group -number. There is no particular restriction on the numbering, -e.g., you can have several groups with the same number in which case -the last one to match (i.e., the rightmost match) will win. -Implicitly numbered groups always get the smallest integer larger than -the one of any previous group. - -@item \@var{digit} -matches the same text that matched the @var{digit}th occurrence of a -grouping (@samp{\( @dots{} \)}) construct. - -In other words, after the end of a group, the matcher remembers the -beginning and end of the text matched by that group. Later on in the -regular expression you can use @samp{\} followed by @var{digit} to -match that same text, whatever it may have been. - -The strings matching the first nine grouping constructs appearing in -the entire regular expression passed to a search or matching function -are assigned numbers 1 through 9 in the order that the open -parentheses appear in the regular expression. So you can use -@samp{\1} through @samp{\9} to refer to the text matched by the -corresponding grouping constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -If a @samp{\( @dots{} \)} construct matches more than once (which can -happen, for instance, if it is followed by @samp{*}), only the last -match is recorded. - -If a particular grouping construct in the regular expression was never -matched---for instance, if it appears inside of an alternative that -wasn't used, or inside of a repetition that repeated zero times---then -the corresponding @samp{\@var{digit}} construct never matches -anything. To use an artificial example, @samp{\(foo\(b*\)\|lose\)\2} -cannot match @samp{lose}: the second alternative inside the larger -group matches it, but then @samp{\2} is undefined and can't match -anything. But it can match @samp{foobb}, because the first -alternative matches @samp{foob} and @samp{\2} matches @samp{b}. - -@item \w -@cindex @samp{\w} in regexp -matches any word-constituent character. The editor syntax table -determines which characters these are. @xref{Syntax Tables}. - -@item \W -@cindex @samp{\W} in regexp -matches any character that is not a word constituent. - -@item \s@var{code} -@cindex @samp{\s} in regexp -matches any character whose syntax is @var{code}. Here @var{code} is a -character that represents a syntax code: thus, @samp{w} for word -constituent, @samp{-} for whitespace, @samp{(} for open parenthesis, -etc. To represent whitespace syntax, use either @samp{-} or a space -character. @xref{Syntax Class Table}, for a list of syntax codes and -the characters that stand for them. - -@item \S@var{code} -@cindex @samp{\S} in regexp -matches any character whose syntax is not @var{code}. - -@cindex category, regexp search for -@item \c@var{c} -matches any character whose category is @var{c}. Here @var{c} is a -character that represents a category: thus, @samp{c} for Chinese -characters or @samp{g} for Greek characters in the standard category -table. You can see the list of all the currently defined categories -with @kbd{M-x describe-categories @key{RET}}. You can also define -your own categories in addition to the standard ones using the -@code{define-category} function (@pxref{Categories}). - -@item \C@var{c} -matches any character whose category is not @var{c}. -@end table - - The following regular expression constructs match the empty string---that is, -they don't use up any characters---but whether they match depends on the -context. For all, the beginning and end of the accessible portion of -the buffer are treated as if they were the actual beginning and end of -the buffer. - -@table @samp -@item \` -@cindex @samp{\`} in regexp -matches the empty string, but only at the beginning -of the buffer or string being matched against. - -@item \' -@cindex @samp{\'} in regexp -matches the empty string, but only at the end of -the buffer or string being matched against. - -@item \= -@cindex @samp{\=} in regexp -matches the empty string, but only at point. -(This construct is not defined when matching against a string.) - -@item \b -@cindex @samp{\b} in regexp -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word. - -@samp{\b} matches at the beginning or end of the buffer (or string) -regardless of what text appears next to it. - -@item \B -@cindex @samp{\B} in regexp -matches the empty string, but @emph{not} at the beginning or -end of a word, nor at the beginning or end of the buffer (or string). - -@item \< -@cindex @samp{\<} in regexp -matches the empty string, but only at the beginning of a word. -@samp{\<} matches at the beginning of the buffer (or string) only if a -word-constituent character follows. - -@item \> -@cindex @samp{\>} in regexp -matches the empty string, but only at the end of a word. @samp{\>} -matches at the end of the buffer (or string) only if the contents end -with a word-constituent character. - -@item \_< -@cindex @samp{\_<} in regexp -matches the empty string, but only at the beginning of a symbol. A -symbol is a sequence of one or more word or symbol constituent -characters. @samp{\_<} matches at the beginning of the buffer (or -string) only if a symbol-constituent character follows. - -@item \_> -@cindex @samp{\_>} in regexp -matches the empty string, but only at the end of a symbol. @samp{\_>} -matches at the end of the buffer (or string) only if the contents end -with a symbol-constituent character. -@end table - -@kindex invalid-regexp - Not every string is a valid regular expression. For example, a string -that ends inside a character alternative without a terminating @samp{]} -is invalid, and so is a string that ends with a single @samp{\}. If -an invalid regular expression is passed to any of the search functions, -an @code{invalid-regexp} error is signaled. - -@node Regexp Example -@subsection Complex Regexp Example - - Here is a complicated regexp which was formerly used by Emacs to -recognize the end of a sentence together with any whitespace that -follows. (Nowadays Emacs uses a similar but more complex default -regexp constructed by the function @code{sentence-end}. -@xref{Standard Regexps}.) - - Below, we show first the regexp as a string in Lisp syntax (to -distinguish spaces from tab characters), and then the result of -evaluating it. The string constant begins and ends with a -double-quote. @samp{\"} stands for a double-quote as part of the -string, @samp{\\} for a backslash as part of the string, @samp{\t} for a -tab and @samp{\n} for a newline. - -@example -@group -"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*" - @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[ -]*" -@end group -@end example - -@noindent -In the output, tab and newline appear as themselves. - - This regular expression contains four parts in succession and can be -deciphered as follows: - -@table @code -@item [.?!] -The first part of the pattern is a character alternative that matches -any one of three characters: period, question mark, and exclamation -mark. The match must begin with one of these three characters. (This -is one point where the new default regexp used by Emacs differs from -the old. The new value also allows some non-@acronym{ASCII} -characters that end a sentence without any following whitespace.) - -@item []\"')@}]* -The second part of the pattern matches any closing braces and quotation -marks, zero or more of them, that may follow the period, question mark -or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in -a string. The @samp{*} at the end indicates that the immediately -preceding regular expression (a character alternative, in this case) may be -repeated zero or more times. - -@item \\($\\|@ $\\|\t\\|@ @ \\) -The third part of the pattern matches the whitespace that follows the -end of a sentence: the end of a line (optionally with a space), or a -tab, or two spaces. The double backslashes mark the parentheses and -vertical bars as regular expression syntax; the parentheses delimit a -group and the vertical bars separate alternatives. The dollar sign is -used to match the end of a line. - -@item [ \t\n]* -Finally, the last part of the pattern matches any additional whitespace -beyond the minimum needed to end a sentence. -@end table - -@node Regexp Functions -@subsection Regular Expression Functions - - These functions operate on regular expressions. - -@defun regexp-quote string -This function returns a regular expression whose only exact match is -@var{string}. Using this regular expression in @code{looking-at} will -succeed only if the next characters in the buffer are @var{string}; -using it in a search function will succeed if the text being searched -contains @var{string}. @xref{Regexp Search}. - -This allows you to request an exact string match or search when calling -a function that wants a regular expression. - -@example -@group -(regexp-quote "^The cat$") - @result{} "\\^The cat\\$" -@end group -@end example - -One use of @code{regexp-quote} is to combine an exact string match with -context described as a regular expression. For example, this searches -for the string that is the value of @var{string}, surrounded by -whitespace: - -@example -@group -(re-search-forward - (concat "\\s-" (regexp-quote string) "\\s-")) -@end group -@end example -@end defun - -@defun regexp-opt strings &optional paren -This function returns an efficient regular expression that will match -any of the strings in the list @var{strings}. This is useful when you -need to make matching or searching as fast as possible---for example, -for Font Lock mode@footnote{Note that @code{regexp-opt} does not -guarantee that its result is absolutely the most efficient form -possible. A hand-tuned regular expression can sometimes be slightly -more efficient, but is almost never worth the effort.}. -@c E.g., see http://debbugs.gnu.org/2816 - -If the optional argument @var{paren} is non-@code{nil}, then the -returned regular expression is always enclosed by at least one -parentheses-grouping construct. If @var{paren} is @code{words}, then -that construct is additionally surrounded by @samp{\<} and @samp{\>}; -alternatively, if @var{paren} is @code{symbols}, then that construct -is additionally surrounded by @samp{\_<} and @samp{\_>} -(@code{symbols} is often appropriate when matching -programming-language keywords and the like). - -This simplified definition of @code{regexp-opt} produces a -regular expression which is equivalent to the actual value -(but not as efficient): - -@example -(defun regexp-opt (strings &optional paren) - (let ((open-paren (if paren "\\(" "")) - (close-paren (if paren "\\)" ""))) - (concat open-paren - (mapconcat 'regexp-quote strings "\\|") - close-paren))) -@end example -@end defun - -@defun regexp-opt-depth regexp -This function returns the total number of grouping constructs -(parenthesized expressions) in @var{regexp}. This does not include -shy groups (@pxref{Regexp Backslash}). -@end defun - -@c Supposedly an internal regexp-opt function, but table.el uses it at least. -@defun regexp-opt-charset chars -This function returns a regular expression matching a character in the -list of characters @var{chars}. - -@example -(regexp-opt-charset '(?a ?b ?c ?d ?e)) - @result{} "[a-e]" -@end example -@end defun - -@c Internal functions: regexp-opt-group - -@node Regexp Search -@section Regular Expression Searching -@cindex regular expression searching -@cindex regexp searching -@cindex searching for regexp - - In GNU Emacs, you can search for the next match for a regular -expression either incrementally or not. For incremental search -commands, see @ref{Regexp Search, , Regular Expression Search, emacs, -The GNU Emacs Manual}. Here we describe only the search functions -useful in programs. The principal one is @code{re-search-forward}. - - These search functions convert the regular expression to multibyte if -the buffer is multibyte; they convert the regular expression to unibyte -if the buffer is unibyte. @xref{Text Representations}. - -@deffn Command re-search-forward regexp &optional limit noerror repeat -This function searches forward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}. The -function skips over any amount of text that is not matched by -@var{regexp}, and leaves point at the end of the first match found. -It returns the new value of point. - -If @var{limit} is non-@code{nil}, it must be a position in the current -buffer. It specifies the upper bound to the search. No match -extending after that position is accepted. - -If @var{repeat} is supplied, it must be a positive number; the search -is repeated that many times; each repetition starts at the end of the -previous match. If all these successive searches succeed, the search -succeeds, moving point and returning its new value. Otherwise the -search fails. What @code{re-search-forward} does when the search -fails depends on the value of @var{noerror}: - -@table @asis -@item @code{nil} -Signal a @code{search-failed} error. -@item @code{t} -Do nothing and return @code{nil}. -@item anything else -Move point to @var{limit} (or the end of the accessible portion of the -buffer) and return @code{nil}. -@end table - -In the following example, point is initially before the @samp{T}. -Evaluating the search call moves point to the end of that line (between -the @samp{t} of @samp{hat} and the newline). - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(re-search-forward "[a-z]+" nil t 5) - @result{} 27 - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command re-search-backward regexp &optional limit noerror repeat -This function searches backward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}, leaving -point at the beginning of the first text found. - -This function is analogous to @code{re-search-forward}, but they are not -simple mirror images. @code{re-search-forward} finds the match whose -beginning is as close as possible to the starting point. If -@code{re-search-backward} were a perfect mirror image, it would find the -match whose end is as close as possible. However, in fact it finds the -match whose beginning is as close as possible (and yet ends before the -starting point). The reason for this is that matching a regular -expression at a given spot always works from beginning to end, and -starts at a specified beginning position. - -A true mirror-image of @code{re-search-forward} would require a special -feature for matching regular expressions from end to beginning. It's -not worth the trouble of implementing that. -@end deffn - -@defun string-match regexp string &optional start -This function returns the index of the start of the first match for -the regular expression @var{regexp} in @var{string}, or @code{nil} if -there is no match. If @var{start} is non-@code{nil}, the search starts -at that index in @var{string}. - -For example, - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly.") - @result{} 4 -@end group -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group -@end example - -@noindent -The index of the first character of the -string is 0, the index of the second character is 1, and so on. - -After this function returns, the index of the first character beyond -the match is available as @code{(match-end 0)}. @xref{Match Data}. - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group - -@group -(match-end 0) - @result{} 32 -@end group -@end example -@end defun - -@defun string-match-p regexp string &optional start -This predicate function does what @code{string-match} does, but it -avoids modifying the match data. -@end defun - -@defun looking-at regexp -This function determines whether the text in the current buffer directly -following point matches the regular expression @var{regexp}. ``Directly -following'' means precisely that: the search is ``anchored'' and it can -succeed only starting with the first character following point. The -result is @code{t} if so, @code{nil} otherwise. - -This function does not move point, but it does update the match data. -@xref{Match Data}. If you need to test for a match without modifying -the match data, use @code{looking-at-p}, described below. - -In this example, point is located directly before the @samp{T}. If it -were anywhere else, the result would be @code{nil}. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- - -(looking-at "The cat in the hat$") - @result{} t -@end group -@end example -@end defun - -@defun looking-back regexp &optional limit greedy -This function returns @code{t} if @var{regexp} matches the text -immediately before point (i.e., ending at point), and @code{nil} otherwise. - -Because regular expression matching works only going forward, this is -implemented by searching backwards from point for a match that ends at -point. That can be quite slow if it has to search a long distance. -You can bound the time required by specifying @var{limit}, which says -not to search before @var{limit}. In this case, the match that is -found must begin at or after @var{limit}. Here's an example: - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- - -(looking-back "read \"" 3) - @result{} t -(looking-back "read \"" 4) - @result{} nil -@end group -@end example - -If @var{greedy} is non-@code{nil}, this function extends the match -backwards as far as possible, stopping when a single additional -previous character cannot be part of a match for regexp. When the -match is extended, its starting position is allowed to occur before -@var{limit}. - -@c http://debbugs.gnu.org/5689 -As a general recommendation, try to avoid using @code{looking-back} -wherever possible, since it is slow. For this reason, there are no -plans to add a @code{looking-back-p} function. -@end defun - -@defun looking-at-p regexp -This predicate function works like @code{looking-at}, but without -updating the match data. -@end defun - -@defvar search-spaces-regexp -If this variable is non-@code{nil}, it should be a regular expression -that says how to search for whitespace. In that case, any group of -spaces in a regular expression being searched for stands for use of -this regular expression. However, spaces inside of constructs such as -@samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by -@code{search-spaces-regexp}. - -Since this variable affects all regular expression search and match -constructs, you should bind it temporarily for as small as possible -a part of the code. -@end defvar - -@node POSIX Regexps -@section POSIX Regular Expression Searching - -@cindex backtracking and POSIX regular expressions - The usual regular expression functions do backtracking when necessary -to handle the @samp{\|} and repetition constructs, but they continue -this only until they find @emph{some} match. Then they succeed and -report the first match found. - - This section describes alternative search functions which perform the -full backtracking specified by the POSIX standard for regular expression -matching. They continue backtracking until they have tried all -possibilities and found all matches, so they can report the longest -match, as required by POSIX@. This is much slower, so use these -functions only when you really need the longest match. - - The POSIX search and match functions do not properly support the -non-greedy repetition operators (@pxref{Regexp Special, non-greedy}). -This is because POSIX backtracking conflicts with the semantics of -non-greedy repetition. - -@deffn Command posix-search-forward regexp &optional limit noerror repeat -This is like @code{re-search-forward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end deffn - -@deffn Command posix-search-backward regexp &optional limit noerror repeat -This is like @code{re-search-backward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end deffn - -@defun posix-looking-at regexp -This is like @code{looking-at} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@defun posix-string-match regexp string &optional start -This is like @code{string-match} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@node Match Data -@section The Match Data -@cindex match data - - Emacs keeps track of the start and end positions of the segments of -text found during a search; this is called the @dfn{match data}. -Thanks to the match data, you can search for a complex pattern, such -as a date in a mail message, and then extract parts of the match under -control of the pattern. - - Because the match data normally describe the most recent search only, -you must be careful not to do another search inadvertently between the -search you wish to refer back to and the use of the match data. If you -can't avoid another intervening search, you must save and restore the -match data around it, to prevent it from being overwritten. - - Notice that all functions are allowed to overwrite the match data -unless they're explicitly documented not to do so. A consequence is -that functions that are run implicitly in the background -(@pxref{Timers}, and @ref{Idle Timers}) should likely save and restore -the match data explicitly. - -@menu -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. -@end menu - -@node Replacing Match -@subsection Replacing the Text that Matched -@cindex replace matched text - - This function replaces all or part of the text matched by the last -search. It works by means of the match data. - -@cindex case in replacements -@defun replace-match replacement &optional fixedcase literal string subexp -This function performs a replacement operation on a buffer or string. - -If you did the last search in a buffer, you should omit the -@var{string} argument or specify @code{nil} for it, and make sure that -the current buffer is the one in which you performed the last search. -Then this function edits the buffer, replacing the matched text with -@var{replacement}. It leaves point at the end of the replacement -text. - -If you performed the last search on a string, pass the same string as -@var{string}. Then this function returns a new string, in which the -matched text is replaced by @var{replacement}. - -If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses -the replacement text without case conversion; otherwise, it converts -the replacement text depending upon the capitalization of the text to -be replaced. If the original text is all upper case, this converts -the replacement text to upper case. If all words of the original text -are capitalized, this capitalizes all the words of the replacement -text. If all the words are one-letter and they are all upper case, -they are treated as capitalized words rather than all-upper-case -words. - -If @var{literal} is non-@code{nil}, then @var{replacement} is inserted -exactly as it is, the only alterations being case changes as needed. -If it is @code{nil} (the default), then the character @samp{\} is treated -specially. If a @samp{\} appears in @var{replacement}, then it must be -part of one of the following sequences: - -@table @asis -@item @samp{\&} -@cindex @samp{&} in replacement -This stands for the entire text being replaced. - -@item @samp{\@var{n}}, where @var{n} is a digit -@cindex @samp{\@var{n}} in replacement -This stands for the text that matched the @var{n}th subexpression in -the original regexp. Subexpressions are those expressions grouped -inside @samp{\(@dots{}\)}. If the @var{n}th subexpression never -matched, an empty string is substituted. - -@item @samp{\\} -@cindex @samp{\} in replacement -This stands for a single @samp{\} in the replacement text. - -@item @samp{\?} -This stands for itself (for compatibility with @code{replace-regexp} -and related commands; @pxref{Regexp Replace,,, emacs, The GNU -Emacs Manual}). -@end table - -@noindent -Any other character following @samp{\} signals an error. - -The substitutions performed by @samp{\&} and @samp{\@var{n}} occur -after case conversion, if any. Therefore, the strings they substitute -are never case-converted. - -If @var{subexp} is non-@code{nil}, that says to replace just -subexpression number @var{subexp} of the regexp that was matched, not -the entire match. For example, after matching @samp{foo \(ba*r\)}, -calling @code{replace-match} with 1 as @var{subexp} means to replace -just the text that matched @samp{\(ba*r\)}. -@end defun - -@defun match-substitute-replacement replacement &optional fixedcase literal string subexp -This function returns the text that would be inserted into the buffer -by @code{replace-match}, but without modifying the buffer. It is -useful if you want to present the user with actual replacement result, -with constructs like @samp{\@var{n}} or @samp{\&} substituted with -matched groups. Arguments @var{replacement} and optional -@var{fixedcase}, @var{literal}, @var{string} and @var{subexp} have the -same meaning as for @code{replace-match}. -@end defun - -@node Simple Match Data -@subsection Simple Match Data Access - - This section explains how to use the match data to find out what was -matched by the last search or match operation, if it succeeded. - - You can ask about the entire matching text, or about a particular -parenthetical subexpression of a regular expression. The @var{count} -argument in the functions below specifies which. If @var{count} is -zero, you are asking about the entire match. If @var{count} is -positive, it specifies which subexpression you want. - - Recall that the subexpressions of a regular expression are those -expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The -@var{count}th subexpression is found by counting occurrences of -@samp{\(} from the beginning of the whole regular expression. The first -subexpression is numbered 1, the second 2, and so on. Only regular -expressions can have subexpressions---after a simple string search, the -only information available is about the entire match. - - Every successful search sets the match data. Therefore, you should -query the match data immediately after searching, before calling any -other function that might perform another search. Alternatively, you -may save and restore the match data (@pxref{Saving Match Data}) around -the call to functions that could perform another search. Or use the -functions that explicitly do not modify the match data; -e.g., @code{string-match-p}. - -@c This is an old comment and presumably there is no prospect of this -@c changing now. But still the advice stands. - A search which fails may or may not alter the match data. In the -current implementation, it does not, but we may change it in the -future. Don't try to rely on the value of the match data after a -failing search. - -@defun match-string count &optional in-string -This function returns, as a string, the text matched in the last search -or match operation. It returns the entire text if @var{count} is zero, -or just the portion corresponding to the @var{count}th parenthetical -subexpression, if @var{count} is positive. - -If the last such operation was done against a string with -@code{string-match}, then you should pass the same string as the -argument @var{in-string}. After a buffer search or match, -you should omit @var{in-string} or pass @code{nil} for it; but you -should make sure that the current buffer when you call -@code{match-string} is the one in which you did the searching or -matching. Failure to follow this advice will lead to incorrect results. - -The value is @code{nil} if @var{count} is out of range, or for a -subexpression inside a @samp{\|} alternative that wasn't used or a -repetition that repeated zero times. -@end defun - -@defun match-string-no-properties count &optional in-string -This function is like @code{match-string} except that the result -has no text properties. -@end defun - -@defun match-beginning count -This function returns the position of the start of the text matched by the -last regular expression searched for, or a subexpression of it. - -If @var{count} is zero, then the value is the position of the start of -the entire match. Otherwise, @var{count} specifies a subexpression in -the regular expression, and the value of the function is the starting -position of the match for that subexpression. - -The value is @code{nil} for a subexpression inside a @samp{\|} -alternative that wasn't used or a repetition that repeated zero times. -@end defun - -@defun match-end count -This function is like @code{match-beginning} except that it returns the -position of the end of the match, rather than the position of the -beginning. -@end defun - - Here is an example of using the match data, with a comment showing the -positions within the text: - -@example -@group -(string-match "\\(qu\\)\\(ick\\)" - "The quick fox jumped quickly.") - ;0123456789 - @result{} 4 -@end group - -@group -(match-string 0 "The quick fox jumped quickly.") - @result{} "quick" -(match-string 1 "The quick fox jumped quickly.") - @result{} "qu" -(match-string 2 "The quick fox jumped quickly.") - @result{} "ick" -@end group - -@group -(match-beginning 1) ; @r{The beginning of the match} - @result{} 4 ; @r{with @samp{qu} is at index 4.} -@end group - -@group -(match-beginning 2) ; @r{The beginning of the match} - @result{} 6 ; @r{with @samp{ick} is at index 6.} -@end group - -@group -(match-end 1) ; @r{The end of the match} - @result{} 6 ; @r{with @samp{qu} is at index 6.} - -(match-end 2) ; @r{The end of the match} - @result{} 9 ; @r{with @samp{ick} is at index 9.} -@end group -@end example - - Here is another example. Point is initially located at the beginning -of the line. Searching moves point to between the space and the word -@samp{in}. The beginning of the entire match is at the 9th character of -the buffer (@samp{T}), and the beginning of the match for the first -subexpression is at the 13th character (@samp{c}). - -@example -@group -(list - (re-search-forward "The \\(cat \\)") - (match-beginning 0) - (match-beginning 1)) - @result{} (17 9 13) -@end group - -@group ----------- Buffer: foo ---------- -I read "The cat @point{}in the hat comes back" twice. - ^ ^ - 9 13 ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -(In this case, the index returned is a buffer position; the first -character of the buffer counts as 1.) - -@node Entire Match Data -@subsection Accessing the Entire Match Data - - The functions @code{match-data} and @code{set-match-data} read or -write the entire match data, all at once. - -@defun match-data &optional integers reuse reseat -This function returns a list of positions (markers or integers) that -record all the information on the text that the last search matched. -Element zero is the position of the beginning of the match for the -whole expression; element one is the position of the end of the match -for the expression. The next two elements are the positions of the -beginning and end of the match for the first subexpression, and so on. -In general, element -@ifnottex -number 2@var{n} -@end ifnottex -@tex -number {\mathsurround=0pt $2n$} -@end tex -corresponds to @code{(match-beginning @var{n})}; and -element -@ifnottex -number 2@var{n} + 1 -@end ifnottex -@tex -number {\mathsurround=0pt $2n+1$} -@end tex -corresponds to @code{(match-end @var{n})}. - -Normally all the elements are markers or @code{nil}, but if -@var{integers} is non-@code{nil}, that means to use integers instead -of markers. (In that case, the buffer itself is appended as an -additional element at the end of the list, to facilitate complete -restoration of the match data.) If the last match was done on a -string with @code{string-match}, then integers are always used, -since markers can't point into a string. - -If @var{reuse} is non-@code{nil}, it should be a list. In that case, -@code{match-data} stores the match data in @var{reuse}. That is, -@var{reuse} is destructively modified. @var{reuse} does not need to -have the right length. If it is not long enough to contain the match -data, it is extended. If it is too long, the length of @var{reuse} -stays the same, but the elements that were not used are set to -@code{nil}. The purpose of this feature is to reduce the need for -garbage collection. - -If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list -are reseated to point to nowhere. - -As always, there must be no possibility of intervening searches between -the call to a search function and the call to @code{match-data} that is -intended to access the match data for that search. - -@example -@group -(match-data) - @result{} (# - # - # - #) -@end group -@end example -@end defun - -@defun set-match-data match-list &optional reseat -This function sets the match data from the elements of @var{match-list}, -which should be a list that was the value of a previous call to -@code{match-data}. (More precisely, anything that has the same format -will work.) - -If @var{match-list} refers to a buffer that doesn't exist, you don't get -an error; that sets the match data in a meaningless but harmless way. - -If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list -are reseated to point to nowhere. - -@c TODO Make it properly obsolete. -@findex store-match-data -@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}. -@end defun - -@node Saving Match Data -@subsection Saving and Restoring the Match Data - - When you call a function that may search, you may need to save -and restore the match data around that call, if you want to preserve the -match data from an earlier search for later use. Here is an example -that shows the problem that arises if you fail to save the match data: - -@example -@group -(re-search-forward "The \\(cat \\)") - @result{} 48 -(foo) ; @r{@code{foo} does more searching.} -(match-end 0) - @result{} 61 ; @r{Unexpected result---not 48!} -@end group -@end example - - You can save and restore the match data with @code{save-match-data}: - -@defmac save-match-data body@dots{} -This macro executes @var{body}, saving and restoring the match -data around it. The return value is the value of the last form in -@var{body}. -@end defmac - - You could use @code{set-match-data} together with @code{match-data} to -imitate the effect of the special form @code{save-match-data}. Here is -how: - -@example -@group -(let ((data (match-data))) - (unwind-protect - @dots{} ; @r{Ok to change the original match data.} - (set-match-data data))) -@end group -@end example - - Emacs automatically saves and restores the match data when it runs -process filter functions (@pxref{Filter Functions}) and process -sentinels (@pxref{Sentinels}). - -@ignore - Here is a function which restores the match data provided the buffer -associated with it still exists. - -@smallexample -@group -(defun restore-match-data (data) -@c It is incorrect to split the first line of a doc string. -@c If there's a problem here, it should be solved in some other way. - "Restore the match data DATA unless the buffer is missing." - (catch 'foo - (let ((d data)) -@end group - (while d - (and (car d) - (null (marker-buffer (car d))) -@group - ;; @file{match-data} @r{buffer is deleted.} - (throw 'foo nil)) - (setq d (cdr d))) - (set-match-data data)))) -@end group -@end smallexample -@end ignore - -@node Search and Replace -@section Search and Replace -@cindex replacement after search -@cindex searching and replacing - - If you want to find all matches for a regexp in part of the buffer, -and replace them, the best way is to write an explicit loop using -@code{re-search-forward} and @code{replace-match}, like this: - -@example -(while (re-search-forward "foo[ \t]+bar" nil t) - (replace-match "foobar")) -@end example - -@noindent -@xref{Replacing Match,, Replacing the Text that Matched}, for a -description of @code{replace-match}. - - However, replacing matches in a string is more complex, especially -if you want to do it efficiently. So Emacs provides a function to do -this. - -@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start -This function copies @var{string} and searches it for matches for -@var{regexp}, and replaces them with @var{rep}. It returns the -modified copy. If @var{start} is non-@code{nil}, the search for -matches starts at that index in @var{string}, so matches starting -before that index are not changed. - -This function uses @code{replace-match} to do the replacement, and it -passes the optional arguments @var{fixedcase}, @var{literal} and -@var{subexp} along to @code{replace-match}. - -Instead of a string, @var{rep} can be a function. In that case, -@code{replace-regexp-in-string} calls @var{rep} for each match, -passing the text of the match as its sole argument. It collects the -value @var{rep} returns and passes that to @code{replace-match} as the -replacement string. The match data at this point are the result -of matching @var{regexp} against a substring of @var{string}. -@end defun - - If you want to write a command along the lines of @code{query-replace}, -you can use @code{perform-replace} to do the work. - -@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end -This function is the guts of @code{query-replace} and related -commands. It searches for occurrences of @var{from-string} in the -text between positions @var{start} and @var{end} and replaces some or -all of them. If @var{start} is @code{nil} (or omitted), point is used -instead, and the end of the buffer's accessible portion is used for -@var{end}. - -If @var{query-flag} is @code{nil}, it replaces all -occurrences; otherwise, it asks the user what to do about each one. - -If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is -considered a regular expression; otherwise, it must match literally. If -@var{delimited-flag} is non-@code{nil}, then only replacements -surrounded by word boundaries are considered. - -The argument @var{replacements} specifies what to replace occurrences -with. If it is a string, that string is used. It can also be a list of -strings, to be used in cyclic order. - -If @var{replacements} is a cons cell, @w{@code{(@var{function} -. @var{data})}}, this means to call @var{function} after each match to -get the replacement text. This function is called with two arguments: -@var{data}, and the number of replacements already made. - -If @var{repeat-count} is non-@code{nil}, it should be an integer. Then -it specifies how many times to use each of the strings in the -@var{replacements} list before advancing cyclically to the next one. - -If @var{from-string} contains upper-case letters, then -@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and -it uses the @var{replacements} without altering their case. - -Normally, the keymap @code{query-replace-map} defines the possible -user responses for queries. The argument @var{map}, if -non-@code{nil}, specifies a keymap to use instead of -@code{query-replace-map}. - -This function uses one of two functions to search for the next -occurrence of @var{from-string}. These functions are specified by the -values of two variables: @code{replace-re-search-function} and -@code{replace-search-function}. The former is called when the -argument @var{regexp-flag} is non-@code{nil}, the latter when it is -@code{nil}. -@end defun - -@defvar query-replace-map -This variable holds a special keymap that defines the valid user -responses for @code{perform-replace} and the commands that use it, as -well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual -in two ways: - -@itemize @bullet -@item -The ``key bindings'' are not commands, just symbols that are meaningful -to the functions that use this map. - -@item -Prefix keys are not supported; each key binding must be for a -single-event key sequence. This is because the functions don't use -@code{read-key-sequence} to get the input; instead, they read a single -event and look it up ``by hand''. -@end itemize -@end defvar - -Here are the meaningful ``bindings'' for @code{query-replace-map}. -Several of them are meaningful only for @code{query-replace} and -friends. - -@table @code -@item act -Do take the action being considered---in other words, ``yes''. - -@item skip -Do not take action for this question---in other words, ``no''. - -@item exit -Answer this question ``no'', and give up on the entire series of -questions, assuming that the answers will be ``no''. - -@item exit-prefix -Like @code{exit}, but add the key that was pressed to -@code{unread-command-events} (@pxref{Event Input Misc}). - -@item act-and-exit -Answer this question ``yes'', and give up on the entire series of -questions, assuming that subsequent answers will be ``no''. - -@item act-and-show -Answer this question ``yes'', but show the results---don't advance yet -to the next question. - -@item automatic -Answer this question and all subsequent questions in the series with -``yes'', without further user interaction. - -@item backup -Move back to the previous place that a question was asked about. - -@item edit -Enter a recursive edit to deal with this question---instead of any -other action that would normally be taken. - -@item edit-replacement -Edit the replacement for this question in the minibuffer. - -@item delete-and-edit -Delete the text being considered, then enter a recursive edit to replace -it. - -@item recenter -@itemx scroll-up -@itemx scroll-down -@itemx scroll-other-window -@itemx scroll-other-window-down -Perform the specified window scroll operation, then ask the same -question again. Only @code{y-or-n-p} and related functions use this -answer. - -@item quit -Perform a quit right away. Only @code{y-or-n-p} and related functions -use this answer. - -@item help -Display some help, then ask again. -@end table - -@defvar multi-query-replace-map -This variable holds a keymap that extends @code{query-replace-map} by -providing additional keybindings that are useful in multi-buffer -replacements. The additional ``bindings'' are: - -@table @code -@item automatic-all -Answer this question and all subsequent questions in the series with -``yes'', without further user interaction, for all remaining buffers. - -@item exit-current -Answer this question ``no'', and give up on the entire series of -questions for the current buffer. Continue to the next buffer in the -sequence. -@end table -@end defvar - -@defvar replace-search-function -This variable specifies a function that @code{perform-replace} calls -to search for the next string to replace. Its default value is -@code{search-forward}. Any other value should name a function of 3 -arguments: the first 3 arguments of @code{search-forward} -(@pxref{String Search}). -@end defvar - -@defvar replace-re-search-function -This variable specifies a function that @code{perform-replace} calls -to search for the next regexp to replace. Its default value is -@code{re-search-forward}. Any other value should name a function of 3 -arguments: the first 3 arguments of @code{re-search-forward} -(@pxref{Regexp Search}). -@end defvar - -@node Standard Regexps -@section Standard Regular Expressions Used in Editing -@cindex regexps used standardly in editing -@cindex standard regexps used in editing - - This section describes some variables that hold regular expressions -used for certain purposes in editing: - -@defopt page-delimiter -This is the regular expression describing line-beginnings that separate -pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or -@code{"^\C-l"}); this matches a line that starts with a formfeed -character. -@end defopt - - The following two regular expressions should @emph{not} assume the -match always starts at the beginning of a line; they should not use -@samp{^} to anchor the match. Most often, the paragraph commands do -check for a match only at the beginning of a line, which means that -@samp{^} would be superfluous. When there is a nonzero left margin, -they accept matches that start after the left margin. In that case, a -@samp{^} would be incorrect. However, a @samp{^} is harmless in modes -where a left margin is never used. - -@defopt paragraph-separate -This is the regular expression for recognizing the beginning of a line -that separates paragraphs. (If you change this, you may have to -change @code{paragraph-start} also.) The default value is -@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of -spaces, tabs, and form feeds (after its left margin). -@end defopt - -@defopt paragraph-start -This is the regular expression for recognizing the beginning of a line -that starts @emph{or} separates paragraphs. The default value is -@w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only -whitespace or starting with a form feed (after its left margin). -@end defopt - -@defopt sentence-end -If non-@code{nil}, the value should be a regular expression describing -the end of a sentence, including the whitespace following the -sentence. (All paragraph boundaries also end sentences, regardless.) - -If the value is @code{nil}, as it is by default, then the function -@code{sentence-end} constructs the regexp. That is why you -should always call the function @code{sentence-end} to obtain the -regexp to be used to recognize the end of a sentence. -@end defopt - -@defun sentence-end -This function returns the value of the variable @code{sentence-end}, -if non-@code{nil}. Otherwise it returns a default value based on the -values of the variables @code{sentence-end-double-space} -(@pxref{Definition of sentence-end-double-space}), -@code{sentence-end-without-period}, and -@code{sentence-end-without-space}. -@end defun diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi deleted file mode 100644 index b518bfc6b73..00000000000 --- a/doc/lispref/sequences.texi +++ /dev/null @@ -1,874 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Sequences Arrays Vectors -@chapter Sequences, Arrays, and Vectors -@cindex sequence - - The @dfn{sequence} type is the union of two other Lisp types: lists -and arrays. In other words, any list is a sequence, and any array is -a sequence. The common property that all sequences have is that each -is an ordered collection of elements. - - An @dfn{array} is a fixed-length object with a slot for each of its -elements. All the elements are accessible in constant time. The four -types of arrays are strings, vectors, char-tables and bool-vectors. - - A list is a sequence of elements, but it is not a single primitive -object; it is made of cons cells, one cell per element. Finding the -@var{n}th element requires looking through @var{n} cons cells, so -elements farther from the beginning of the list take longer to access. -But it is possible to add elements to the list, or remove elements. - - The following diagram shows the relationship between these types: - -@example -@group - _____________________________________________ - | | - | Sequence | - | ______ ________________________________ | - | | | | | | - | | List | | Array | | - | | | | ________ ________ | | - | |______| | | | | | | | - | | | Vector | | String | | | - | | |________| |________| | | - | | ____________ _____________ | | - | | | | | | | | - | | | Char-table | | Bool-vector | | | - | | |____________| |_____________| | | - | |________________________________| | - |_____________________________________________| -@end group -@end example - -@menu -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. -* Rings:: Managing a fixed-size ring of objects. -@end menu - -@node Sequence Functions -@section Sequences - - This section describes functions that accept any kind of sequence. - -@defun sequencep object -This function returns @code{t} if @var{object} is a list, vector, -string, bool-vector, or char-table, @code{nil} otherwise. -@end defun - -@defun length sequence -@cindex string length -@cindex list length -@cindex vector length -@cindex sequence length -@cindex char-table length -This function returns the number of elements in @var{sequence}. If -@var{sequence} is a dotted list, a @code{wrong-type-argument} error is -signaled. Circular lists may cause an infinite loop. For a -char-table, the value returned is always one more than the maximum -Emacs character code. - -@xref{Definition of safe-length}, for the related function @code{safe-length}. - -@example -@group -(length '(1 2 3)) - @result{} 3 -@end group -@group -(length ()) - @result{} 0 -@end group -@group -(length "foobar") - @result{} 6 -@end group -@group -(length [1 2 3]) - @result{} 3 -@end group -@group -(length (make-bool-vector 5 nil)) - @result{} 5 -@end group -@end example -@end defun - -@noindent -See also @code{string-bytes}, in @ref{Text Representations}. - -If you need to compute the width of a string on display, you should use -@code{string-width} (@pxref{Size of Displayed Text}), not @code{length}, -since @code{length} only counts the number of characters, but does not -account for the display width of each character. - -@defun elt sequence index -@cindex elements of sequences -This function returns the element of @var{sequence} indexed by -@var{index}. Legitimate values of @var{index} are integers ranging -from 0 up to one less than the length of @var{sequence}. If -@var{sequence} is a list, out-of-range values behave as for -@code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values -trigger an @code{args-out-of-range} error. - -@example -@group -(elt [1 2 3 4] 2) - @result{} 3 -@end group -@group -(elt '(1 2 3 4) 2) - @result{} 3 -@end group -@group -;; @r{We use @code{string} to show clearly which character @code{elt} returns.} -(string (elt "1234" 2)) - @result{} "3" -@end group -@group -(elt [1 2 3 4] 4) - @error{} Args out of range: [1 2 3 4], 4 -@end group -@group -(elt [1 2 3 4] -1) - @error{} Args out of range: [1 2 3 4], -1 -@end group -@end example - -This function generalizes @code{aref} (@pxref{Array Functions}) and -@code{nth} (@pxref{Definition of nth}). -@end defun - -@defun copy-sequence sequence -@cindex copying sequences -This function returns a copy of @var{sequence}. The copy is the same -type of object as the original sequence, and it has the same elements -in the same order. - -Storing a new element into the copy does not affect the original -@var{sequence}, and vice versa. However, the elements of the new -sequence are not copies; they are identical (@code{eq}) to the elements -of the original. Therefore, changes made within these elements, as -found via the copied sequence, are also visible in the original -sequence. - -If the sequence is a string with text properties, the property list in -the copy is itself a copy, not shared with the original's property -list. However, the actual values of the properties are shared. -@xref{Text Properties}. - -This function does not work for dotted lists. Trying to copy a -circular list may cause an infinite loop. - -See also @code{append} in @ref{Building Lists}, @code{concat} in -@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions}, -for other ways to copy sequences. - -@example -@group -(setq bar '(1 2)) - @result{} (1 2) -@end group -@group -(setq x (vector 'foo bar)) - @result{} [foo (1 2)] -@end group -@group -(setq y (copy-sequence x)) - @result{} [foo (1 2)] -@end group - -@group -(eq x y) - @result{} nil -@end group -@group -(equal x y) - @result{} t -@end group -@group -(eq (elt x 1) (elt y 1)) - @result{} t -@end group - -@group -;; @r{Replacing an element of one sequence.} -(aset x 0 'quux) -x @result{} [quux (1 2)] -y @result{} [foo (1 2)] -@end group - -@group -;; @r{Modifying the inside of a shared element.} -(setcar (aref x 1) 69) -x @result{} [quux (69 2)] -y @result{} [foo (69 2)] -@end group -@end example -@end defun - -@node Arrays -@section Arrays -@cindex array - - An @dfn{array} object has slots that hold a number of other Lisp -objects, called the elements of the array. Any element of an array -may be accessed in constant time. In contrast, the time to access an -element of a list is proportional to the position of that element in -the list. - - Emacs defines four types of array, all one-dimensional: -@dfn{strings} (@pxref{String Type}), @dfn{vectors} (@pxref{Vector -Type}), @dfn{bool-vectors} (@pxref{Bool-Vector Type}), and -@dfn{char-tables} (@pxref{Char-Table Type}). Vectors and char-tables -can hold elements of any type, but strings can only hold characters, -and bool-vectors can only hold @code{t} and @code{nil}. - - All four kinds of array share these characteristics: - -@itemize @bullet -@item -The first element of an array has index zero, the second element has -index 1, and so on. This is called @dfn{zero-origin} indexing. For -example, an array of four elements has indices 0, 1, 2, @w{and 3}. - -@item -The length of the array is fixed once you create it; you cannot -change the length of an existing array. - -@item -For purposes of evaluation, the array is a constant---i.e., -it evaluates to itself. - -@item -The elements of an array may be referenced or changed with the functions -@code{aref} and @code{aset}, respectively (@pxref{Array Functions}). -@end itemize - - When you create an array, other than a char-table, you must specify -its length. You cannot specify the length of a char-table, because that -is determined by the range of character codes. - - In principle, if you want an array of text characters, you could use -either a string or a vector. In practice, we always choose strings for -such applications, for four reasons: - -@itemize @bullet -@item -They occupy one-fourth the space of a vector of the same elements. - -@item -Strings are printed in a way that shows the contents more clearly -as text. - -@item -Strings can hold text properties. @xref{Text Properties}. - -@item -Many of the specialized editing and I/O facilities of Emacs accept only -strings. For example, you cannot insert a vector of characters into a -buffer the way you can insert a string. @xref{Strings and Characters}. -@end itemize - - By contrast, for an array of keyboard input characters (such as a key -sequence), a vector may be necessary, because many keyboard input -characters are outside the range that will fit in a string. @xref{Key -Sequence Input}. - -@node Array Functions -@section Functions that Operate on Arrays - - In this section, we describe the functions that accept all types of -arrays. - -@defun arrayp object -This function returns @code{t} if @var{object} is an array (i.e., a -vector, a string, a bool-vector or a char-table). - -@example -@group -(arrayp [a]) - @result{} t -(arrayp "asdf") - @result{} t -(arrayp (syntax-table)) ;; @r{A char-table.} - @result{} t -@end group -@end example -@end defun - -@defun aref array index -@cindex array elements -This function returns the @var{index}th element of @var{array}. The -first element is at index zero. - -@example -@group -(setq primes [2 3 5 7 11 13]) - @result{} [2 3 5 7 11 13] -(aref primes 4) - @result{} 11 -@end group -@group -(aref "abcdefg" 1) - @result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.} -@end group -@end example - -See also the function @code{elt}, in @ref{Sequence Functions}. -@end defun - -@defun aset array index object -This function sets the @var{index}th element of @var{array} to be -@var{object}. It returns @var{object}. - -@example -@group -(setq w [foo bar baz]) - @result{} [foo bar baz] -(aset w 0 'fu) - @result{} fu -w - @result{} [fu bar baz] -@end group - -@group -(setq x "asdfasfd") - @result{} "asdfasfd" -(aset x 3 ?Z) - @result{} 90 -x - @result{} "asdZasfd" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. The function converts a -unibyte string to multibyte if necessary to insert a character. -@end defun - -@defun fillarray array object -This function fills the array @var{array} with @var{object}, so that -each element of @var{array} is @var{object}. It returns @var{array}. - -@example -@group -(setq a [a b c d e f g]) - @result{} [a b c d e f g] -(fillarray a 0) - @result{} [0 0 0 0 0 0 0] -a - @result{} [0 0 0 0 0 0 0] -@end group -@group -(setq s "When in the course") - @result{} "When in the course" -(fillarray s ?-) - @result{} "------------------" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. -@end defun - -The general sequence functions @code{copy-sequence} and @code{length} -are often useful for objects known to be arrays. @xref{Sequence Functions}. - -@node Vectors -@section Vectors -@cindex vector (type) - - A @dfn{vector} is a general-purpose array whose elements can be any -Lisp objects. (By contrast, the elements of a string can only be -characters. @xref{Strings and Characters}.) Vectors are used in -Emacs for many purposes: as key sequences (@pxref{Key Sequences}), as -symbol-lookup tables (@pxref{Creating Symbols}), as part of the -representation of a byte-compiled function (@pxref{Byte Compilation}), -and more. - - Like other arrays, vectors use zero-origin indexing: the first -element has index 0. - - Vectors are printed with square brackets surrounding the elements. -Thus, a vector whose elements are the symbols @code{a}, @code{b} and -@code{a} is printed as @code{[a b a]}. You can write vectors in the -same way in Lisp input. - - A vector, like a string or a number, is considered a constant for -evaluation: the result of evaluating it is the same vector. This does -not evaluate or even examine the elements of the vector. -@xref{Self-Evaluating Forms}. - - Here are examples illustrating these principles: - -@example -@group -(setq avector [1 two '(three) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(eval avector) - @result{} [1 two (quote (three)) "four" [five]] -(eq avector (eval avector)) - @result{} t -@end group -@end example - -@node Vector Functions -@section Functions for Vectors - - Here are some functions that relate to vectors: - -@defun vectorp object -This function returns @code{t} if @var{object} is a vector. - -@example -@group -(vectorp [a]) - @result{} t -(vectorp "asdf") - @result{} nil -@end group -@end example -@end defun - -@defun vector &rest objects -This function creates and returns a vector whose elements are the -arguments, @var{objects}. - -@example -@group -(vector 'foo 23 [bar baz] "rats") - @result{} [foo 23 [bar baz] "rats"] -(vector) - @result{} [] -@end group -@end example -@end defun - -@defun make-vector length object -This function returns a new vector consisting of @var{length} elements, -each initialized to @var{object}. - -@example -@group -(setq sleepy (make-vector 9 'Z)) - @result{} [Z Z Z Z Z Z Z Z Z] -@end group -@end example -@end defun - -@defun vconcat &rest sequences -@cindex copying vectors -This function returns a new vector containing all the elements of -@var{sequences}. The arguments @var{sequences} may be true lists, -vectors, strings or bool-vectors. If no @var{sequences} are given, -the empty vector is returned. - -The value is either the empty vector, or is a newly constructed -nonempty vector that is not @code{eq} to any existing vector. - -@example -@group -(setq a (vconcat '(A B C) '(D E F))) - @result{} [A B C D E F] -(eq a (vconcat a)) - @result{} nil -@end group -@group -(vconcat) - @result{} [] -(vconcat [A B C] "aa" '(foo (6 7))) - @result{} [A B C 97 97 foo (6 7)] -@end group -@end example - -The @code{vconcat} function also allows byte-code function objects as -arguments. This is a special feature to make it easy to access the entire -contents of a byte-code function object. @xref{Byte-Code Objects}. - -For other concatenation functions, see @code{mapconcat} in @ref{Mapping -Functions}, @code{concat} in @ref{Creating Strings}, and @code{append} -in @ref{Building Lists}. -@end defun - - The @code{append} function also provides a way to convert a vector into a -list with the same elements: - -@example -@group -(setq avector [1 two (quote (three)) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(append avector nil) - @result{} (1 two (quote (three)) "four" [five]) -@end group -@end example - -@node Char-Tables -@section Char-Tables -@cindex char-tables -@cindex extra slots of char-table - - A char-table is much like a vector, except that it is indexed by -character codes. Any valid character code, without modifiers, can be -used as an index in a char-table. You can access a char-table's -elements with @code{aref} and @code{aset}, as with any array. In -addition, a char-table can have @dfn{extra slots} to hold additional -data not associated with particular character codes. Like vectors, -char-tables are constants when evaluated, and can hold elements of any -type. - -@cindex subtype of char-table - Each char-table has a @dfn{subtype}, a symbol, which serves two -purposes: - -@itemize @bullet -@item -The subtype provides an easy way to tell what the char-table is for. -For instance, display tables are char-tables with @code{display-table} -as the subtype, and syntax tables are char-tables with -@code{syntax-table} as the subtype. The subtype can be queried using -the function @code{char-table-subtype}, described below. - -@item -The subtype controls the number of @dfn{extra slots} in the -char-table. This number is specified by the subtype's -@code{char-table-extra-slots} symbol property (@pxref{Symbol -Properties}), whose value should be an integer between 0 and 10. If -the subtype has no such symbol property, the char-table has no extra -slots. -@end itemize - -@cindex parent of char-table - A char-table can have a @dfn{parent}, which is another char-table. If -it does, then whenever the char-table specifies @code{nil} for a -particular character @var{c}, it inherits the value specified in the -parent. In other words, @code{(aref @var{char-table} @var{c})} returns -the value from the parent of @var{char-table} if @var{char-table} itself -specifies @code{nil}. - -@cindex default value of char-table - A char-table can also have a @dfn{default value}. If so, then -@code{(aref @var{char-table} @var{c})} returns the default value -whenever the char-table does not specify any other non-@code{nil} value. - -@defun make-char-table subtype &optional init -Return a newly-created char-table, with subtype @var{subtype} (a -symbol). Each element is initialized to @var{init}, which defaults to -@code{nil}. You cannot alter the subtype of a char-table after the -char-table is created. - -There is no argument to specify the length of the char-table, because -all char-tables have room for any valid character code as an index. - -If @var{subtype} has the @code{char-table-extra-slots} symbol -property, that specifies the number of extra slots in the char-table. -This should be an integer between 0 and 10; otherwise, -@code{make-char-table} raises an error. If @var{subtype} has no -@code{char-table-extra-slots} symbol property (@pxref{Property -Lists}), the char-table has no extra slots. -@end defun - -@defun char-table-p object -This function returns @code{t} if @var{object} is a char-table, and -@code{nil} otherwise. -@end defun - -@defun char-table-subtype char-table -This function returns the subtype symbol of @var{char-table}. -@end defun - -There is no special function to access default values in a char-table. -To do that, use @code{char-table-range} (see below). - -@defun char-table-parent char-table -This function returns the parent of @var{char-table}. The parent is -always either @code{nil} or another char-table. -@end defun - -@defun set-char-table-parent char-table new-parent -This function sets the parent of @var{char-table} to @var{new-parent}. -@end defun - -@defun char-table-extra-slot char-table n -This function returns the contents of extra slot @var{n} of -@var{char-table}. The number of extra slots in a char-table is -determined by its subtype. -@end defun - -@defun set-char-table-extra-slot char-table n value -This function stores @var{value} in extra slot @var{n} of -@var{char-table}. -@end defun - - A char-table can specify an element value for a single character code; -it can also specify a value for an entire character set. - -@defun char-table-range char-table range -This returns the value specified in @var{char-table} for a range of -characters @var{range}. Here are the possibilities for @var{range}: - -@table @asis -@item @code{nil} -Refers to the default value. - -@item @var{char} -Refers to the element for character @var{char} -(supposing @var{char} is a valid character code). - -@item @code{(@var{from} . @var{to})} -A cons cell refers to all the characters in the inclusive range -@samp{[@var{from}..@var{to}]}. -@end table -@end defun - -@defun set-char-table-range char-table range value -This function sets the value in @var{char-table} for a range of -characters @var{range}. Here are the possibilities for @var{range}: - -@table @asis -@item @code{nil} -Refers to the default value. - -@item @code{t} -Refers to the whole range of character codes. - -@item @var{char} -Refers to the element for character @var{char} -(supposing @var{char} is a valid character code). - -@item @code{(@var{from} . @var{to})} -A cons cell refers to all the characters in the inclusive range -@samp{[@var{from}..@var{to}]}. -@end table -@end defun - -@defun map-char-table function char-table -This function calls its argument @var{function} for each element of -@var{char-table} that has a non-@code{nil} value. The call to -@var{function} is with two arguments, a key and a value. The key -is a possible @var{range} argument for @code{char-table-range}---either -a valid character or a cons cell @code{(@var{from} . @var{to})}, -specifying a range of characters that share the same value. The value is -what @code{(char-table-range @var{char-table} @var{key})} returns. - -Overall, the key-value pairs passed to @var{function} describe all the -values stored in @var{char-table}. - -The return value is always @code{nil}; to make calls to -@code{map-char-table} useful, @var{function} should have side effects. -For example, here is how to examine the elements of the syntax table: - -@example -(let (accumulator) - (map-char-table - #'(lambda (key value) - (setq accumulator - (cons (list - (if (consp key) - (list (car key) (cdr key)) - key) - value) - accumulator))) - (syntax-table)) - accumulator) -@result{} -(((2597602 4194303) (2)) ((2597523 2597601) (3)) - ... (65379 (5 . 65378)) (65378 (4 . 65379)) (65377 (1)) - ... (12 (0)) (11 (3)) (10 (12)) (9 (0)) ((0 8) (3))) -@end example -@end defun - -@node Bool-Vectors -@section Bool-vectors -@cindex Bool-vectors - - A bool-vector is much like a vector, except that it stores only the -values @code{t} and @code{nil}. If you try to store any non-@code{nil} -value into an element of the bool-vector, the effect is to store -@code{t} there. As with all arrays, bool-vector indices start from 0, -and the length cannot be changed once the bool-vector is created. -Bool-vectors are constants when evaluated. - - There are two special functions for working with bool-vectors; aside -from that, you manipulate them with same functions used for other kinds -of arrays. - -@defun make-bool-vector length initial -Return a new bool-vector of @var{length} elements, -each one initialized to @var{initial}. -@end defun - -@defun bool-vector-p object -This returns @code{t} if @var{object} is a bool-vector, -and @code{nil} otherwise. -@end defun - -There are also some bool-vector set operation functions, described below: - -@defun bool-vector-exclusive-or a b &optional c -Return @dfn{bitwise exclusive or} of bool vectors @var{a} and @var{b}. -If optional argument @var{c} is given, the result of this operation is -stored into @var{c}. All arguments should be bool vectors of the same length. -@end defun - -@defun bool-vector-union a b &optional c -Return @dfn{bitwise or} of bool vectors @var{a} and @var{b}. If -optional argument @var{c} is given, the result of this operation is -stored into @var{c}. All arguments should be bool vectors of the same length. -@end defun - -@defun bool-vector-intersection a b &optional c -Return @dfn{bitwise and} of bool vectors @var{a} and @var{b}. If -optional argument @var{c} is given, the result of this operation is -stored into @var{c}. All arguments should be bool vectors of the same length. -@end defun - -@defun bool-vector-set-difference a b &optional c -Return @dfn{set difference} of bool vectors @var{a} and @var{b}. If -optional argument @var{c} is given, the result of this operation is -stored into @var{c}. All arguments should be bool vectors of the same length. -@end defun - -@defun bool-vector-not a &optional b -Return @dfn{set complement} of bool vector @var{a}. If optional -argument @var{b} is given, the result of this operation is stored into -@var{b}. All arguments should be bool vectors of the same length. -@end defun - -@defun bool-vector-subsetp a b -Return @code{t} if every @code{t} value in @var{a} is also t in -@var{b}, @code{nil} otherwise. All arguments should be bool vectors of the -same length. -@end defun - -@defun bool-vector-count-consecutive a b i -Return the number of consecutive elements in @var{a} equal @var{b} -starting at @var{i}. @code{a} is a bool vector, @var{b} is @code{t} -or @code{nil}, and @var{i} is an index into @code{a}. -@end defun - -@defun bool-vector-count-population a -Return the number of elements that are @code{t} in bool vector @var{a}. -@end defun - - Here is an example of creating, examining, and updating a -bool-vector. Note that the printed form represents up to 8 boolean -values as a single character. - -@example -(setq bv (make-bool-vector 5 t)) - @result{} #&5"^_" -(aref bv 1) - @result{} t -(aset bv 3 nil) - @result{} nil -bv - @result{} #&5"^W" -@end example - -@noindent -These results make sense because the binary codes for control-_ and -control-W are 11111 and 10111, respectively. - -@node Rings -@section Managing a Fixed-Size Ring of Objects - -@cindex ring data structure - A @dfn{ring} is a fixed-size data structure that supports insertion, -deletion, rotation, and modulo-indexed reference and traversal. An -efficient ring data structure is implemented by the @code{ring} -package. It provides the functions listed in this section. - - Note that several ``rings'' in Emacs, like the kill ring and the -mark ring, are actually implemented as simple lists, @emph{not} using -the @code{ring} package; thus the following functions won't work on -them. - -@defun make-ring size -This returns a new ring capable of holding @var{size} objects. -@var{size} should be an integer. -@end defun - -@defun ring-p object -This returns @code{t} if @var{object} is a ring, @code{nil} otherwise. -@end defun - -@defun ring-size ring -This returns the maximum capacity of the @var{ring}. -@end defun - -@defun ring-length ring -This returns the number of objects that @var{ring} currently contains. -The value will never exceed that returned by @code{ring-size}. -@end defun - -@defun ring-elements ring -This returns a list of the objects in @var{ring}, in order, newest first. -@end defun - -@defun ring-copy ring -This returns a new ring which is a copy of @var{ring}. -The new ring contains the same (@code{eq}) objects as @var{ring}. -@end defun - -@defun ring-empty-p ring -This returns @code{t} if @var{ring} is empty, @code{nil} otherwise. -@end defun - - The newest element in the ring always has index 0. Higher indices -correspond to older elements. Indices are computed modulo the ring -length. Index @minus{}1 corresponds to the oldest element, @minus{}2 -to the next-oldest, and so forth. - -@defun ring-ref ring index -This returns the object in @var{ring} found at index @var{index}. -@var{index} may be negative or greater than the ring length. If -@var{ring} is empty, @code{ring-ref} signals an error. -@end defun - -@defun ring-insert ring object -This inserts @var{object} into @var{ring}, making it the newest -element, and returns @var{object}. - -If the ring is full, insertion removes the oldest element to -make room for the new element. -@end defun - -@defun ring-remove ring &optional index -Remove an object from @var{ring}, and return that object. The -argument @var{index} specifies which item to remove; if it is -@code{nil}, that means to remove the oldest item. If @var{ring} is -empty, @code{ring-remove} signals an error. -@end defun - -@defun ring-insert-at-beginning ring object -This inserts @var{object} into @var{ring}, treating it as the oldest -element. The return value is not significant. - -If the ring is full, this function removes the newest element to make -room for the inserted element. -@end defun - -@cindex fifo data structure - If you are careful not to exceed the ring size, you can -use the ring as a first-in-first-out queue. For example: - -@lisp -(let ((fifo (make-ring 5))) - (mapc (lambda (obj) (ring-insert fifo obj)) - '(0 one "two")) - (list (ring-remove fifo) t - (ring-remove fifo) t - (ring-remove fifo))) - @result{} (0 t one t "two") -@end lisp diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile deleted file mode 100644 index 590d356d2d4..00000000000 --- a/doc/lispref/spellfile +++ /dev/null @@ -1,730 +0,0 @@ -ARPA -Abbrev -Alan -Arnold -Autoloading -BAppend -Backquote -Beeping -Beverly -Boyes -Brian -CL -CSWKg -Carl -Carroll -Chris -Cleanups -DEC -DStandard -Dan -Dired's -Disassembly -Duff -EMAC -EMACSLOADPATH -Eckelkamp -Edward -Eirik -Emacses -Eric -Erlebacher -Fcar -Fcdr -Fcons -Fcoordinates -Feval -Frazzle -Frederick -Fri -Gardiner -Gentlemen -HAL -HATTED -HS -HU -Hanchrow -Hartzell -Hess -Hewlett -IBM -ISBN -Impl -Interning -Ithought -J's -Jacobson -Jak -Joe -Jones -Jr -Jul -Keymaps -Kimmo -Kirman -Knighten -Korz -Krawitz -LTsHm -LaLiberte -LaTeX -Lammens -Local' -MAC -MONIES -MSS -Maclisp -Magill -Marick -Matthew -Minibuf -Misc -Miscellany -Mocklisp -Montanaro -Myers -NFS -Nathan -Nope -OS -OSITIONS -Oct -Ovwrt -PURESIZE -Packard -Qlistp -Qnil -RMAIL -Raul -Resizing -Robbins -Rockwell -SCO -SIGCONT -SIGHUP -SIGINT -SIGKILL -SIGQUIT -SIGTSTP -SLOAD -Scoordinates -Set' -Setcar -Setcdr -Shinichirou -Snarf -Sor -SourceFile -Stops' -Subprocess -Sugou -Sunview -Suominen -T's -TCP -ThXs -Tharp -Thu -Trost -UCB -UNEVALLED -UNGCPRO -UniPlus -UniSoft's -VMS -Vip -Void' -Warren -Welty -Wethought -Wilding -Worley -Wright -XDVI -XFASTINT -XINT -XWINDOW -Xs -Yo -Zuhn -aB -aa -aaa -abbrevname -abbrevs -abc -abcdefg -abcxyz -abd -above' -abracadabra -address' -after' -alist -alists -anchored' -and' -ar -aref -arg'th -argdecl -arith -arrayp -arrow' -asa -asdZasfd -asdf -asdfasfd -aset -assoc -assq -at' -aug -autoload -automatic' -automatically' -avector -bBuffer -bFrobnicate -ba -back' -bananana -barfoo -barx -bballs -before' -beforep -bfoo -bil -binding's -bish -bobp -bolp -bottommost -boundp -brief' -buf -buffer' -bufferp -buttercup -ca -caaaar -caaar -caddaar -cadr -callable -cbreak -ce -cell' -cells' -cf -chaprm -character' -childp -chistory -ck -column' -commandp -concat -cond -conses -consing -consp -constant' -contains' -continuable -convert' -copyleft -correct' -counterintuitive -cr -creatable -customize -deactivate -deactivated -deassigns -decrement' -deffnx -definition' -defmacro -defsubr -deletable -deletion' -delq -depiction -deselecting -destructive' -destructively' -diffs -ding -directory' -dired -dirname -disassembler -dland -docfile -docstring -doesnt -dont -down' -downcasing -downloadable -dribble -dup -ef -efg -electric' -elided -elt -enablement -endkeyfun -endrecfun -environment' -eobp -eof -eol -eolp -eq -eqlsign -erminal -erste -etags -eval -evalled -evals -evaluate' -excess' -exec -exitcode -expression' -extra' -fails' -fascist -fboundp -featurep -ff -fg -fi -file' -filespec -filesystems -fillarray -firstchar -firstonly -fixedcase -fixit -fixup -floatp -fmakunbound -fns -fo -fol -folded' -following' -fooba -foobaz -foox -for' -formfeed -forms' -forw -found' -frob -from' -front' -fset -fstab -ftp -fu -garbles -gc -gcpro -gd -getenv -getprv -gid -gnuemacs -gp -grep -gtr -halves' -hand' -hashes' -hd -hexadecimal -hf -hfil -hookvar -horsechestnut -hostname -hpux -hscroll -ibmapa -ick -id -idiom -ii -indrm -inode -input' -inputinput -inserting' -integerp -intermixed -ints -irreversibly -jum -keymapp -kill' -killed' -killp -kludge -kolstad -language' -lastchar -lcl -ledit -leif -lessp -level' -lewis -library' -link' -lisplib -listexp -loadable -loadst -loadup -logand -logior -lognot -logxor -long' -loop's -lru -lrwxrwxrwx -ls -lsh -m's -macroexpand -makunbound -malloc -mapatoms -mapconcat -mapvar -mark' -marker's -markerp -mathsurround -medit -memq -mh -mim -mini -minibuffer's -minibuffers -misalignment -misnamed -mode's -modename -modes' -mods -modtime -mqueue -msg -multicharacter -myfile -nCount -nXExpression -na -name's -natnump -nb -nbBuffer -nconc -newdef -newelt -newname -nextrecfun -nfsusr -ninett -nlines -nlinks -nlistp -noconfirm -nodigits -noerror -noforce -nomessage -nominees -nomsg -nonblank -nonconstant -nondestructive -nondirectory -nonidentical -noninteractive -noninteractively -nonletter -nonletters -nonlocally -nonoverlapping -nonprinting -nonselected -nonsequentially -nonvoid -nonwarranty -nonwritable -noop -noprint -norecord -normal' -noselect -nosuffix -nots -noundo -nr -nreverse -ns -nsRename -nth -nthcdr -num -number' -numberp -nums -obarray -obarrays -object' -oldbuf -olddef -oldname -oo -oops -op -or' -otl -out' -over' -overful -overfullrule -overstrike -overstriking -overstruck -p' -paren -part' -passwd -pe -ped -perverse -pid -plist -pnt -pointer' -pointm -pos -preallocate -preload -prepend -prepended -prepends -pretty' -prin -princ -print' -printenv -printer' -proc -process' -processp -programmer' -prolog -protect' -ps -psf -psychotherapy -pty -purecopy -qu -quux -rassq -reader' -readin -rebind -rec -rechecking -recursively' -recycler' -redo -redrawing -redraws -redump -reenabled -reexposed -reg -region' -reindent -reindents -reinitialization -reinitialize -reinitialized -reinstall -reinstalled -resize -resized -resizes -reversibly -reworded -rhetorical -right' -ring' -risky -rmailedit -rms -rplaca -rplacd -rtu -runnable -rw -rwxrwxrwx -sDescribe -sans -se -searching' -section' -seed' -sequence' -sequencep -setp -setplist -setprv -settable -setuid -sexp -sexps -shape' -shell's -sideline -special' -specpdl -st -stanford -startkeyfun -str -stringp -stty -subcategories -subcommands -subexp -subform -subforms -subjob -submap -subprocesses -subr -subr' -subroutine' -subrp -subrs -subwindows -sugar' -suid -supersession -suspension' -symbolp -symlink -syms -syntactic -tabname -temacs -temporarily' -tempvar -tenths -termcap -termcaps -terminfo -termscript -termtype -terpri -text' -textrm -textsl -texttt -than' -the' -tildes -time's -to' -towards -transportable -txt -types' -uid -unbind -unbinding -unbinds -unchanged' -unclutters -undefine -undefines -underfull -undo's -unevaluated' -unexec -unexpand -unhesitatingly -uninterned -unisoft -unpaired -unread -unreadable -unreading -unsaved -untyped -ununderline -up' -uptime -usecount -used' -user' -userlock -usg -val -varbind -varname -varref -vars -varset -vb -vconcat -vectorp -vfil -vi -vn -voidness -vrs -vt -window' -windowing -windowp -wrapped' -xSpecify -xcoord -xcssun -xemacs -xenix -xf -xfirst -xoff -xon -xx -xxxxx -xxxxxxxxx -xy -xyz -ycoord -yes' -zA -zap -zerop diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi deleted file mode 100644 index 1d549ae8916..00000000000 --- a/doc/lispref/streams.texi +++ /dev/null @@ -1,835 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Read and Print -@chapter Reading and Printing Lisp Objects - - @dfn{Printing} and @dfn{reading} are the operations of converting Lisp -objects to textual form and vice versa. They use the printed -representations and read syntax described in @ref{Lisp Data Types}. - - This chapter describes the Lisp functions for reading and printing. -It also describes @dfn{streams}, which specify where to get the text (if -reading) or where to put it (if printing). - -@menu -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing functions do. -@end menu - -@node Streams Intro -@section Introduction to Reading and Printing -@cindex Lisp reader -@cindex printing -@cindex reading - - @dfn{Reading} a Lisp object means parsing a Lisp expression in textual -form and producing a corresponding Lisp object. This is how Lisp -programs get into Lisp from files of Lisp code. We call the text the -@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)} -is the read syntax for a cons cell whose @sc{car} is @code{a} and whose -@sc{cdr} is the number 5. - - @dfn{Printing} a Lisp object means producing text that represents that -object---converting the object to its @dfn{printed representation} -(@pxref{Printed Representation}). Printing the cons cell described -above produces the text @samp{(a .@: 5)}. - - Reading and printing are more or less inverse operations: printing the -object that results from reading a given piece of text often produces -the same text, and reading the text that results from printing an object -usually produces a similar-looking object. For example, printing the -symbol @code{foo} produces the text @samp{foo}, and reading that text -returns the symbol @code{foo}. Printing a list whose elements are -@code{a} and @code{b} produces the text @samp{(a b)}, and reading that -text produces a list (but not the same list) with elements @code{a} -and @code{b}. - - However, these two operations are not precisely inverse to each other. -There are three kinds of exceptions: - -@itemize @bullet -@item -Printing can produce text that cannot be read. For example, buffers, -windows, frames, subprocesses and markers print as text that starts -with @samp{#}; if you try to read this text, you get an error. There is -no way to read those data types. - -@item -One object can have multiple textual representations. For example, -@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and -@samp{(a .@: (b))} represent the same list. Reading will accept any of -the alternatives, but printing must choose one of them. - -@item -Comments can appear at certain points in the middle of an object's -read sequence without affecting the result of reading it. -@end itemize - -@node Input Streams -@section Input Streams -@cindex stream (for reading) -@cindex input stream - - Most of the Lisp functions for reading text take an @dfn{input stream} -as an argument. The input stream specifies where or how to get the -characters of the text to be read. Here are the possible types of input -stream: - -@table @asis -@item @var{buffer} -@cindex buffer input stream -The input characters are read from @var{buffer}, starting with the -character directly after point. Point advances as characters are read. - -@item @var{marker} -@cindex marker input stream -The input characters are read from the buffer that @var{marker} is in, -starting with the character directly after the marker. The marker -position advances as characters are read. The value of point in the -buffer has no effect when the stream is a marker. - -@item @var{string} -@cindex string input stream -The input characters are taken from @var{string}, starting at the first -character in the string and using as many characters as required. - -@item @var{function} -@cindex function input stream -The input characters are generated by @var{function}, which must support -two kinds of calls: - -@itemize @bullet -@item -When it is called with no arguments, it should return the next character. - -@item -When it is called with one argument (always a character), @var{function} -should save the argument and arrange to return it on the next call. -This is called @dfn{unreading} the character; it happens when the Lisp -reader reads one character too many and wants to ``put it back where it -came from''. In this case, it makes no difference what value -@var{function} returns. -@end itemize - -@item @code{t} -@cindex @code{t} input stream -@code{t} used as a stream means that the input is read from the -minibuffer. In fact, the minibuffer is invoked once and the text -given by the user is made into a string that is then used as the -input stream. If Emacs is running in batch mode, standard input is used -instead of the minibuffer. For example, -@example -(message "%s" (read t)) -@end example -will read a Lisp expression from standard input and print the result -to standard output. - -@item @code{nil} -@cindex @code{nil} input stream -@code{nil} supplied as an input stream means to use the value of -@code{standard-input} instead; that value is the @dfn{default input -stream}, and must be a non-@code{nil} input stream. - -@item @var{symbol} -A symbol as input stream is equivalent to the symbol's function -definition (if any). -@end table - - Here is an example of reading from a stream that is a buffer, showing -where point is located before and after: - -@example -@group ----------- Buffer: foo ---------- -This@point{} is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(read (get-buffer "foo")) - @result{} is -@end group -@group -(read (get-buffer "foo")) - @result{} the -@end group - -@group ----------- Buffer: foo ---------- -This is the@point{} contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -Note that the first read skips a space. Reading skips any amount of -whitespace preceding the significant text. - - Here is an example of reading from a stream that is a marker, -initially positioned at the beginning of the buffer shown. The value -read is the symbol @code{This}. - -@example -@group - ----------- Buffer: foo ---------- -This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(setq m (set-marker (make-marker) 1 (get-buffer "foo"))) - @result{} # -@end group -@group -(read m) - @result{} This -@end group -@group -m - @result{} # ;; @r{Before the first space.} -@end group -@end example - - Here we read from the contents of a string: - -@example -@group -(read "(When in) the course") - @result{} (When in) -@end group -@end example - - The following example reads from the minibuffer. The -prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt -used when you read from the stream @code{t}.) The user's input is shown -following the prompt. - -@example -@group -(read t) - @result{} 23 ----------- Buffer: Minibuffer ---------- -Lisp expression: @kbd{23 @key{RET}} ----------- Buffer: Minibuffer ---------- -@end group -@end example - - Finally, here is an example of a stream that is a function, named -@code{useless-stream}. Before we use the stream, we initialize the -variable @code{useless-list} to a list of characters. Then each call to -the function @code{useless-stream} obtains the next character in the list -or unreads a character by adding it to the front of the list. - -@example -@group -(setq useless-list (append "XY()" nil)) - @result{} (88 89 40 41) -@end group - -@group -(defun useless-stream (&optional unread) - (if unread - (setq useless-list (cons unread useless-list)) - (prog1 (car useless-list) - (setq useless-list (cdr useless-list))))) - @result{} useless-stream -@end group -@end example - -@noindent -Now we read using the stream thus constructed: - -@example -@group -(read 'useless-stream) - @result{} XY -@end group - -@group -useless-list - @result{} (40 41) -@end group -@end example - -@noindent -Note that the open and close parentheses remain in the list. The Lisp -reader encountered the open parenthesis, decided that it ended the -input, and unread it. Another attempt to read from the stream at this -point would read @samp{()} and return @code{nil}. - -@node Input Functions -@section Input Functions - - This section describes the Lisp functions and variables that pertain -to reading. - - In the functions below, @var{stream} stands for an input stream (see -the previous section). If @var{stream} is @code{nil} or omitted, it -defaults to the value of @code{standard-input}. - -@kindex end-of-file - An @code{end-of-file} error is signaled if reading encounters an -unterminated list, vector, or string. - -@defun read &optional stream -This function reads one textual Lisp expression from @var{stream}, -returning it as a Lisp object. This is the basic Lisp input function. -@end defun - -@defun read-from-string string &optional start end -@cindex string to object -This function reads the first textual Lisp expression from the text in -@var{string}. It returns a cons cell whose @sc{car} is that expression, -and whose @sc{cdr} is an integer giving the position of the next -remaining character in the string (i.e., the first one not read). - -If @var{start} is supplied, then reading begins at index @var{start} in -the string (where the first character is at index 0). If you specify -@var{end}, then reading is forced to stop just before that index, as if -the rest of the string were not there. - -For example: - -@example -@group -(read-from-string "(setq x 55) (setq y 5)") - @result{} ((setq x 55) . 11) -@end group -@group -(read-from-string "\"A short string\"") - @result{} ("A short string" . 16) -@end group - -@group -;; @r{Read starting at the first character.} -(read-from-string "(list 112)" 0) - @result{} ((list 112) . 10) -@end group -@group -;; @r{Read starting at the second character.} -(read-from-string "(list 112)" 1) - @result{} (list . 5) -@end group -@group -;; @r{Read starting at the seventh character,} -;; @r{and stopping at the ninth.} -(read-from-string "(list 112)" 6 8) - @result{} (11 . 8) -@end group -@end example -@end defun - -@defvar standard-input -This variable holds the default input stream---the stream that -@code{read} uses when the @var{stream} argument is @code{nil}. -The default is @code{t}, meaning use the minibuffer. -@end defvar - -@defvar read-circle -If non-@code{nil}, this variable enables the reading of circular and -shared structures. @xref{Circular Objects}. Its default value is -@code{t}. -@end defvar - -@node Output Streams -@section Output Streams -@cindex stream (for printing) -@cindex output stream - - An output stream specifies what to do with the characters produced -by printing. Most print functions accept an output stream as an -optional argument. Here are the possible types of output stream: - -@table @asis -@item @var{buffer} -@cindex buffer output stream -The output characters are inserted into @var{buffer} at point. -Point advances as characters are inserted. - -@item @var{marker} -@cindex marker output stream -The output characters are inserted into the buffer that @var{marker} -points into, at the marker position. The marker position advances as -characters are inserted. The value of point in the buffer has no effect -on printing when the stream is a marker, and this kind of printing -does not move point (except that if the marker points at or before the -position of point, point advances with the surrounding text, as -usual). - -@item @var{function} -@cindex function output stream -The output characters are passed to @var{function}, which is responsible -for storing them away. It is called with a single character as -argument, as many times as there are characters to be output, and -is responsible for storing the characters wherever you want to put them. - -@item @code{t} -@cindex @code{t} output stream -The output characters are displayed in the echo area. - -@item @code{nil} -@cindex @code{nil} output stream -@code{nil} specified as an output stream means to use the value of -@code{standard-output} instead; that value is the @dfn{default output -stream}, and must not be @code{nil}. - -@item @var{symbol} -A symbol as output stream is equivalent to the symbol's function -definition (if any). -@end table - - Many of the valid output streams are also valid as input streams. The -difference between input and output streams is therefore more a matter -of how you use a Lisp object, than of different types of object. - - Here is an example of a buffer used as an output stream. Point is -initially located as shown immediately before the @samp{h} in -@samp{the}. At the end, point is located directly before that same -@samp{h}. - -@cindex print example -@example -@group ----------- Buffer: foo ---------- -This is t@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group - -(print "This is the output" (get-buffer "foo")) - @result{} "This is the output" - -@group ----------- Buffer: foo ---------- -This is t -"This is the output" -@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - - Now we show a use of a marker as an output stream. Initially, the -marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in -the word @samp{the}. At the end, the marker has advanced over the -inserted text so that it remains positioned before the same @samp{h}. -Note that the location of point, shown in the usual fashion, has no -effect. - -@example -@group ----------- Buffer: foo ---------- -This is the @point{}output ----------- Buffer: foo ---------- -@end group - -@group -(setq m (copy-marker 10)) - @result{} # -@end group - -@group -(print "More output for foo." m) - @result{} "More output for foo." -@end group - -@group ----------- Buffer: foo ---------- -This is t -"More output for foo." -he @point{}output ----------- Buffer: foo ---------- -@end group - -@group -m - @result{} # -@end group -@end example - - The following example shows output to the echo area: - -@example -@group -(print "Echo Area output" t) - @result{} "Echo Area output" ----------- Echo Area ---------- -"Echo Area output" ----------- Echo Area ---------- -@end group -@end example - - Finally, we show the use of a function as an output stream. The -function @code{eat-output} takes each character that it is given and -conses it onto the front of the list @code{last-output} (@pxref{Building -Lists}). At the end, the list contains all the characters output, but -in reverse order. - -@example -@group -(setq last-output nil) - @result{} nil -@end group - -@group -(defun eat-output (c) - (setq last-output (cons c last-output))) - @result{} eat-output -@end group - -@group -(print "This is the output" 'eat-output) - @result{} "This is the output" -@end group - -@group -last-output - @result{} (10 34 116 117 112 116 117 111 32 101 104 - 116 32 115 105 32 115 105 104 84 34 10) -@end group -@end example - -@noindent -Now we can put the output in the proper order by reversing the list: - -@example -@group -(concat (nreverse last-output)) - @result{} " -\"This is the output\" -" -@end group -@end example - -@noindent -Calling @code{concat} converts the list to a string so you can see its -contents more clearly. - -@node Output Functions -@section Output Functions - - This section describes the Lisp functions for printing Lisp -objects---converting objects into their printed representation. - -@cindex @samp{"} in printing -@cindex @samp{\} in printing -@cindex quoting characters in printing -@cindex escape characters in printing - Some of the Emacs printing functions add quoting characters to the -output when necessary so that it can be read properly. The quoting -characters used are @samp{"} and @samp{\}; they distinguish strings from -symbols, and prevent punctuation characters in strings and symbols from -being taken as delimiters when reading. @xref{Printed Representation}, -for full details. You specify quoting or no quoting by the choice of -printing function. - - If the text is to be read back into Lisp, then you should print with -quoting characters to avoid ambiguity. Likewise, if the purpose is to -describe a Lisp object clearly for a Lisp programmer. However, if the -purpose of the output is to look nice for humans, then it is usually -better to print without quoting. - - Lisp objects can refer to themselves. Printing a self-referential -object in the normal way would require an infinite amount of text, and -the attempt could cause infinite recursion. Emacs detects such -recursion and prints @samp{#@var{level}} instead of recursively printing -an object already being printed. For example, here @samp{#0} indicates -a recursive reference to the object at level 0 of the current print -operation: - -@example -(setq foo (list nil)) - @result{} (nil) -(setcar foo foo) - @result{} (#0) -@end example - - In the functions below, @var{stream} stands for an output stream. -(See the previous section for a description of output streams.) If -@var{stream} is @code{nil} or omitted, it defaults to the value of -@code{standard-output}. - -@defun print object &optional stream -@cindex Lisp printer -The @code{print} function is a convenient way of printing. It outputs -the printed representation of @var{object} to @var{stream}, printing in -addition one newline before @var{object} and another after it. Quoting -characters are used. @code{print} returns @var{object}. For example: - -@example -@group -(progn (print 'The\ cat\ in) - (print "the hat") - (print " came back")) - @print{} - @print{} The\ cat\ in - @print{} - @print{} "the hat" - @print{} - @print{} " came back" - @result{} " came back" -@end group -@end example -@end defun - -@defun prin1 object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It does not print newlines to separate output as -@code{print} does, but it does use quoting characters just like -@code{print}. It returns @var{object}. - -@example -@group -(progn (prin1 'The\ cat\ in) - (prin1 "the hat") - (prin1 " came back")) - @print{} The\ cat\ in"the hat"" came back" - @result{} " came back" -@end group -@end example -@end defun - -@defun princ object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It returns @var{object}. - -This function is intended to produce output that is readable by people, -not by @code{read}, so it doesn't insert quoting characters and doesn't -put double-quotes around the contents of strings. It does not add any -spacing between calls. - -@example -@group -(progn - (princ 'The\ cat) - (princ " in the \"hat\"")) - @print{} The cat in the "hat" - @result{} " in the \"hat\"" -@end group -@end example -@end defun - -@defun terpri &optional stream -@cindex newline in print -This function outputs a newline to @var{stream}. The name stands -for ``terminate print''. -@end defun - -@defun write-char character &optional stream -This function outputs @var{character} to @var{stream}. It returns -@var{character}. -@end defun - -@defun prin1-to-string object &optional noescape -@cindex object to string -This function returns a string containing the text that @code{prin1} -would have printed for the same argument. - -@example -@group -(prin1-to-string 'foo) - @result{} "foo" -@end group -@group -(prin1-to-string (mark-marker)) - @result{} "#" -@end group -@end example - -If @var{noescape} is non-@code{nil}, that inhibits use of quoting -characters in the output. (This argument is supported in Emacs versions -19 and later.) - -@example -@group -(prin1-to-string "foo") - @result{} "\"foo\"" -@end group -@group -(prin1-to-string "foo" t) - @result{} "foo" -@end group -@end example - -See @code{format}, in @ref{Formatting Strings}, for other ways to obtain -the printed representation of a Lisp object as a string. -@end defun - -@defmac with-output-to-string body@dots{} -This macro executes the @var{body} forms with @code{standard-output} set -up to feed output into a string. Then it returns that string. - -For example, if the current buffer name is @samp{foo}, - -@example -(with-output-to-string - (princ "The buffer is ") - (princ (buffer-name))) -@end example - -@noindent -returns @code{"The buffer is foo"}. -@end defmac - -@defun pp object &optional stream -This function outputs @var{object} to @var{stream}, just like -@code{prin1}, but does it in a more ``pretty'' way. That is, it'll -indent and fill the object to make it more readable for humans. -@end defun - -@node Output Variables -@section Variables Affecting Output -@cindex output-controlling variables - -@defvar standard-output -The value of this variable is the default output stream---the stream -that print functions use when the @var{stream} argument is @code{nil}. -The default is @code{t}, meaning display in the echo area. -@end defvar - -@defvar print-quoted -If this is non-@code{nil}, that means to print quoted forms using -abbreviated reader syntax, e.g., @code{(quote foo)} prints as -@code{'foo}, and @code{(function foo)} as @code{#'foo}. -@end defvar - -@defvar print-escape-newlines -@cindex @samp{\n} in print -@cindex escape characters -If this variable is non-@code{nil}, then newline characters in strings -are printed as @samp{\n} and formfeeds are printed as @samp{\f}. -Normally these characters are printed as actual newlines and formfeeds. - -This variable affects the print functions @code{prin1} and @code{print} -that print with quoting. It does not affect @code{princ}. Here is an -example using @code{prin1}: - -@example -@group -(prin1 "a\nb") - @print{} "a - @print{} b" - @result{} "a -b" -@end group - -@group -(let ((print-escape-newlines t)) - (prin1 "a\nb")) - @print{} "a\nb" - @result{} "a -b" -@end group -@end example - -@noindent -In the second expression, the local binding of -@code{print-escape-newlines} is in effect during the call to -@code{prin1}, but not during the printing of the result. -@end defvar - -@defvar print-escape-nonascii -If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII} -characters in strings are unconditionally printed as backslash sequences -by the print functions @code{prin1} and @code{print} that print with -quoting. - -Those functions also use backslash sequences for unibyte non-@acronym{ASCII} -characters, regardless of the value of this variable, when the output -stream is a multibyte buffer or a marker pointing into one. -@end defvar - -@defvar print-escape-multibyte -If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII} -characters in strings are unconditionally printed as backslash sequences -by the print functions @code{prin1} and @code{print} that print with -quoting. - -Those functions also use backslash sequences for multibyte -non-@acronym{ASCII} characters, regardless of the value of this variable, -when the output stream is a unibyte buffer or a marker pointing into -one. -@end defvar - -@defvar print-length -@cindex printing limits -The value of this variable is the maximum number of elements to print in -any list, vector or bool-vector. If an object being printed has more -than this many elements, it is abbreviated with an ellipsis. - -If the value is @code{nil} (the default), then there is no limit. - -@example -@group -(setq print-length 2) - @result{} 2 -@end group -@group -(print '(1 2 3 4 5)) - @print{} (1 2 ...) - @result{} (1 2 ...) -@end group -@end example -@end defvar - -@defvar print-level -The value of this variable is the maximum depth of nesting of -parentheses and brackets when printed. Any list or vector at a depth -exceeding this limit is abbreviated with an ellipsis. A value of -@code{nil} (which is the default) means no limit. -@end defvar - -@defopt eval-expression-print-length -@defoptx eval-expression-print-level -These are the values for @code{print-length} and @code{print-level} -used by @code{eval-expression}, and thus, indirectly, by many -interactive evaluation commands (@pxref{Lisp Eval,, Evaluating -Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}). -@end defopt - - These variables are used for detecting and reporting circular -and shared structure: - -@defvar print-circle -If non-@code{nil}, this variable enables detection of circular and -shared structure in printing. @xref{Circular Objects}. -@end defvar - -@defvar print-gensym -If non-@code{nil}, this variable enables detection of uninterned symbols -(@pxref{Creating Symbols}) in printing. When this is enabled, -uninterned symbols print with the prefix @samp{#:}, which tells the Lisp -reader to produce an uninterned symbol. -@end defvar - -@defvar print-continuous-numbering -If non-@code{nil}, that means number continuously across print calls. -This affects the numbers printed for @samp{#@var{n}=} labels and -@samp{#@var{m}#} references. -Don't set this variable with @code{setq}; you should only bind it -temporarily to @code{t} with @code{let}. When you do that, you should -also bind @code{print-number-table} to @code{nil}. -@end defvar - -@defvar print-number-table -This variable holds a vector used internally by printing to implement -the @code{print-circle} feature. You should not use it except -to bind it to @code{nil} when you bind @code{print-continuous-numbering}. -@end defvar - -@defvar float-output-format -This variable specifies how to print floating-point numbers. The -default is @code{nil}, meaning use the shortest output -that represents the number without losing information. - -To control output format more precisely, you can put a string in this -variable. The string should hold a @samp{%}-specification to be used -in the C function @code{sprintf}. For further restrictions on what -you can use, see the variable's documentation string. -@end defvar diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi deleted file mode 100644 index e6b00f06f79..00000000000 --- a/doc/lispref/strings.texi +++ /dev/null @@ -1,1168 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Strings and Characters -@chapter Strings and Characters -@cindex strings -@cindex character arrays -@cindex characters -@cindex bytes - - A string in Emacs Lisp is an array that contains an ordered sequence -of characters. Strings are used as names of symbols, buffers, and -files; to send messages to users; to hold text being copied between -buffers; and for many other purposes. Because strings are so important, -Emacs Lisp has many functions expressly for manipulating them. Emacs -Lisp programs use strings more often than individual characters. - - @xref{Strings of Events}, for special considerations for strings of -keyboard character events. - -@menu -* Basics: String Basics. Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. -@end menu - -@node String Basics -@section String and Character Basics - - A character is a Lisp object which represents a single character of -text. In Emacs Lisp, characters are simply integers; whether an -integer is a character or not is determined only by how it is used. -@xref{Character Codes}, for details about character representation in -Emacs. - - A string is a fixed sequence of characters. It is a type of -sequence called a @dfn{array}, meaning that its length is fixed and -cannot be altered once it is created (@pxref{Sequences Arrays -Vectors}). Unlike in C, Emacs Lisp strings are @emph{not} terminated -by a distinguished character code. - - Since strings are arrays, and therefore sequences as well, you can -operate on them with the general array and sequence functions documented -in @ref{Sequences Arrays Vectors}. For example, you can access or -change individual characters in a string using the functions @code{aref} -and @code{aset} (@pxref{Array Functions}). However, note that -@code{length} should @emph{not} be used for computing the width of a -string on display; use @code{string-width} (@pxref{Size of Displayed -Text}) instead. - - There are two text representations for non-@acronym{ASCII} -characters in Emacs strings (and in buffers): unibyte and multibyte. -For most Lisp programming, you don't need to be concerned with these -two representations. @xref{Text Representations}, for details. - - Sometimes key sequences are represented as unibyte strings. When a -unibyte string is a key sequence, string elements in the range 128 to -255 represent meta characters (which are large integers) rather than -character codes in the range 128 to 255. Strings cannot hold -characters that have the hyper, super or alt modifiers; they can hold -@acronym{ASCII} control characters, but no other control characters. -They do not distinguish case in @acronym{ASCII} control characters. -If you want to store such characters in a sequence, such as a key -sequence, you must use a vector instead of a string. @xref{Character -Type}, for more information about keyboard input characters. - - Strings are useful for holding regular expressions. You can also -match regular expressions against strings with @code{string-match} -(@pxref{Regexp Search}). The functions @code{match-string} -(@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing -Match}) are useful for decomposing and modifying strings after -matching regular expressions against them. - - Like a buffer, a string can contain text properties for the characters -in it, as well as the characters themselves. @xref{Text Properties}. -All the Lisp primitives that copy text from strings to buffers or other -strings also copy the properties of the characters being copied. - - @xref{Text}, for information about functions that display strings or -copy them into buffers. @xref{Character Type}, and @ref{String Type}, -for information about the syntax of characters and strings. -@xref{Non-ASCII Characters}, for functions to convert between text -representations and to encode and decode character codes. - -@node Predicates for Strings -@section Predicates for Strings - -For more information about general sequence and array predicates, -see @ref{Sequences Arrays Vectors}, and @ref{Arrays}. - -@defun stringp object -This function returns @code{t} if @var{object} is a string, @code{nil} -otherwise. -@end defun - -@defun string-or-null-p object -This function returns @code{t} if @var{object} is a string or -@code{nil}. It returns @code{nil} otherwise. -@end defun - -@defun char-or-string-p object -This function returns @code{t} if @var{object} is a string or a -character (i.e., an integer), @code{nil} otherwise. -@end defun - -@node Creating Strings -@section Creating Strings - - The following functions create strings, either from scratch, or by -putting strings together, or by taking them apart. - -@defun make-string count character -This function returns a string made up of @var{count} repetitions of -@var{character}. If @var{count} is negative, an error is signaled. - -@example -(make-string 5 ?x) - @result{} "xxxxx" -(make-string 0 ?x) - @result{} "" -@end example - - Other functions to compare with this one include @code{make-vector} -(@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}). -@end defun - -@defun string &rest characters -This returns a string containing the characters @var{characters}. - -@example -(string ?a ?b ?c) - @result{} "abc" -@end example -@end defun - -@defun substring string start &optional end -This function returns a new string which consists of those characters -from @var{string} in the range from (and including) the character at the -index @var{start} up to (but excluding) the character at the index -@var{end}. The first character is at index zero. - -@example -@group -(substring "abcdefg" 0 3) - @result{} "abc" -@end group -@end example - -@noindent -In the above example, the index for @samp{a} is 0, the index for -@samp{b} is 1, and the index for @samp{c} is 2. The index 3---which -is the fourth character in the string---marks the character position -up to which the substring is copied. Thus, @samp{abc} is copied from -the string @code{"abcdefg"}. - -A negative number counts from the end of the string, so that @minus{}1 -signifies the index of the last character of the string. For example: - -@example -@group -(substring "abcdefg" -3 -1) - @result{} "ef" -@end group -@end example - -@noindent -In this example, the index for @samp{e} is @minus{}3, the index for -@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1. -Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded. - -When @code{nil} is used for @var{end}, it stands for the length of the -string. Thus, - -@example -@group -(substring "abcdefg" -3 nil) - @result{} "efg" -@end group -@end example - -Omitting the argument @var{end} is equivalent to specifying @code{nil}. -It follows that @code{(substring @var{string} 0)} returns a copy of all -of @var{string}. - -@example -@group -(substring "abcdefg" 0) - @result{} "abcdefg" -@end group -@end example - -@noindent -But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence -Functions}). - -If the characters copied from @var{string} have text properties, the -properties are copied into the new string also. @xref{Text Properties}. - -@code{substring} also accepts a vector for the first argument. -For example: - -@example -(substring [a b (c) "d"] 1 3) - @result{} [b (c)] -@end example - -A @code{wrong-type-argument} error is signaled if @var{start} is not -an integer or if @var{end} is neither an integer nor @code{nil}. An -@code{args-out-of-range} error is signaled if @var{start} indicates a -character following @var{end}, or if either integer is out of range -for @var{string}. - -Contrast this function with @code{buffer-substring} (@pxref{Buffer -Contents}), which returns a string containing a portion of the text in -the current buffer. The beginning of a string is at index 0, but the -beginning of a buffer is at index 1. -@end defun - -@defun substring-no-properties string &optional start end -This works like @code{substring} but discards all text properties from -the value. Also, @var{start} may be omitted or @code{nil}, which is -equivalent to 0. Thus, @w{@code{(substring-no-properties -@var{string})}} returns a copy of @var{string}, with all text -properties removed. -@end defun - -@defun concat &rest sequences -@cindex copying strings -@cindex concatenating strings -This function returns a new string consisting of the characters in the -arguments passed to it (along with their text properties, if any). The -arguments may be strings, lists of numbers, or vectors of numbers; they -are not themselves changed. If @code{concat} receives no arguments, it -returns an empty string. - -@example -(concat "abc" "-def") - @result{} "abc-def" -(concat "abc" (list 120 121) [122]) - @result{} "abcxyz" -;; @r{@code{nil} is an empty sequence.} -(concat "abc" nil "-def") - @result{} "abc-def" -(concat "The " "quick brown " "fox.") - @result{} "The quick brown fox." -(concat) - @result{} "" -@end example - -@noindent -This function always constructs a new string that is not @code{eq} to -any existing string, except when the result is the empty string (to -save space, Emacs makes only one empty multibyte string). - -For information about other concatenation functions, see the -description of @code{mapconcat} in @ref{Mapping Functions}, -@code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building -Lists}. For concatenating individual command-line arguments into a -string to be used as a shell command, see @ref{Shell Arguments, -combine-and-quote-strings}. -@end defun - -@defun split-string string &optional separators omit-nulls trim -This function splits @var{string} into substrings based on the regular -expression @var{separators} (@pxref{Regular Expressions}). Each match -for @var{separators} defines a splitting point; the substrings between -splitting points are made into a list, which is returned. - -If @var{omit-nulls} is @code{nil} (or omitted), the result contains -null strings whenever there are two consecutive matches for -@var{separators}, or a match is adjacent to the beginning or end of -@var{string}. If @var{omit-nulls} is @code{t}, these null strings are -omitted from the result. - -If @var{separators} is @code{nil} (or omitted), the default is the -value of @code{split-string-default-separators}. - -As a special case, when @var{separators} is @code{nil} (or omitted), -null strings are always omitted from the result. Thus: - -@example -(split-string " two words ") - @result{} ("two" "words") -@end example - -The result is not @code{("" "two" "words" "")}, which would rarely be -useful. If you need such a result, use an explicit value for -@var{separators}: - -@example -(split-string " two words " - split-string-default-separators) - @result{} ("" "two" "words" "") -@end example - -More examples: - -@example -(split-string "Soup is good food" "o") - @result{} ("S" "up is g" "" "d f" "" "d") -(split-string "Soup is good food" "o" t) - @result{} ("S" "up is g" "d f" "d") -(split-string "Soup is good food" "o+") - @result{} ("S" "up is g" "d f" "d") -@end example - -Empty matches do count, except that @code{split-string} will not look -for a final empty match when it already reached the end of the string -using a non-empty match or when @var{string} is empty: - -@example -(split-string "aooob" "o*") - @result{} ("" "a" "" "b" "") -(split-string "ooaboo" "o*") - @result{} ("" "" "a" "b" "") -(split-string "" "") - @result{} ("") -@end example - -However, when @var{separators} can match the empty string, -@var{omit-nulls} is usually @code{t}, so that the subtleties in the -three previous examples are rarely relevant: - -@example -(split-string "Soup is good food" "o*" t) - @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d") -(split-string "Nice doggy!" "" t) - @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!") -(split-string "" "" t) - @result{} nil -@end example - -Somewhat odd, but predictable, behavior can occur for certain -``non-greedy'' values of @var{separators} that can prefer empty -matches over non-empty matches. Again, such values rarely occur in -practice: - -@example -(split-string "ooo" "o*" t) - @result{} nil -(split-string "ooo" "\\|o+" t) - @result{} ("o" "o" "o") -@end example - -If the optional argument @var{trim} is non-@code{nil}, it should be a -regular expression to match text to trim from the beginning and end of -each substring. If trimming makes the substring empty, it is treated -as null. - -If you need to split a string into a list of individual command-line -arguments suitable for @code{call-process} or @code{start-process}, -see @ref{Shell Arguments, split-string-and-unquote}. -@end defun - -@defvar split-string-default-separators -The default value of @var{separators} for @code{split-string}. Its -usual value is @w{@code{"[ \f\t\n\r\v]+"}}. -@end defvar - -@node Modifying Strings -@section Modifying Strings - - The most basic way to alter the contents of an existing string is with -@code{aset} (@pxref{Array Functions}). @code{(aset @var{string} -@var{idx} @var{char})} stores @var{char} into @var{string} at index -@var{idx}. Each character occupies one or more bytes, and if @var{char} -needs a different number of bytes from the character already present at -that index, @code{aset} signals an error. - - A more powerful function is @code{store-substring}: - -@defun store-substring string idx obj -This function alters part of the contents of the string @var{string}, by -storing @var{obj} starting at index @var{idx}. The argument @var{obj} -may be either a character or a (smaller) string. - -Since it is impossible to change the length of an existing string, it is -an error if @var{obj} doesn't fit within @var{string}'s actual length, -or if any new character requires a different number of bytes from the -character currently present at that point in @var{string}. -@end defun - - To clear out a string that contained a password, use -@code{clear-string}: - -@defun clear-string string -This makes @var{string} a unibyte string and clears its contents to -zeros. It may also change @var{string}'s length. -@end defun - -@need 2000 -@node Text Comparison -@section Comparison of Characters and Strings -@cindex string equality - -@defun char-equal character1 character2 -This function returns @code{t} if the arguments represent the same -character, @code{nil} otherwise. This function ignores differences -in case if @code{case-fold-search} is non-@code{nil}. - -@example -(char-equal ?x ?x) - @result{} t -(let ((case-fold-search nil)) - (char-equal ?x ?X)) - @result{} nil -@end example -@end defun - -@defun string= string1 string2 -This function returns @code{t} if the characters of the two strings -match exactly. Symbols are also allowed as arguments, in which case -the symbol names are used. Case is always significant, regardless of -@code{case-fold-search}. - -This function is equivalent to @code{equal} for comparing two strings -(@pxref{Equality Predicates}). In particular, the text properties of -the two strings are ignored; use @code{equal-including-properties} if -you need to distinguish between strings that differ only in their text -properties. However, unlike @code{equal}, if either argument is not a -string or symbol, @code{string=} signals an error. - -@example -(string= "abc" "abc") - @result{} t -(string= "abc" "ABC") - @result{} nil -(string= "ab" "ABC") - @result{} nil -@end example - -For technical reasons, a unibyte and a multibyte string are -@code{equal} if and only if they contain the same sequence of -character codes and all these codes are either in the range 0 through -127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). -However, when a unibyte string is converted to a multibyte string, all -characters with codes in the range 160 through 255 are converted to -characters with higher codes, whereas @acronym{ASCII} characters -remain unchanged. Thus, a unibyte string and its conversion to -multibyte are only @code{equal} if the string is all @acronym{ASCII}. -Character codes 160 through 255 are not entirely proper in multibyte -text, even though they can occur. As a consequence, the situation -where a unibyte and a multibyte string are @code{equal} without both -being all @acronym{ASCII} is a technical oddity that very few Emacs -Lisp programmers ever get confronted with. @xref{Text -Representations}. -@end defun - -@defun string-equal string1 string2 -@code{string-equal} is another name for @code{string=}. -@end defun - -@cindex lexical comparison -@defun string< string1 string2 -@c (findex string< causes problems for permuted index!!) -This function compares two strings a character at a time. It -scans both the strings at the same time to find the first pair of corresponding -characters that do not match. If the lesser character of these two is -the character from @var{string1}, then @var{string1} is less, and this -function returns @code{t}. If the lesser character is the one from -@var{string2}, then @var{string1} is greater, and this function returns -@code{nil}. If the two strings match entirely, the value is @code{nil}. - -Pairs of characters are compared according to their character codes. -Keep in mind that lower case letters have higher numeric values in the -@acronym{ASCII} character set than their upper case counterparts; digits and -many punctuation characters have a lower numeric value than upper case -letters. An @acronym{ASCII} character is less than any non-@acronym{ASCII} -character; a unibyte non-@acronym{ASCII} character is always less than any -multibyte non-@acronym{ASCII} character (@pxref{Text Representations}). - -@example -@group -(string< "abc" "abd") - @result{} t -(string< "abd" "abc") - @result{} nil -(string< "123" "abc") - @result{} t -@end group -@end example - -When the strings have different lengths, and they match up to the -length of @var{string1}, then the result is @code{t}. If they match up -to the length of @var{string2}, the result is @code{nil}. A string of -no characters is less than any other string. - -@example -@group -(string< "" "abc") - @result{} t -(string< "ab" "abc") - @result{} t -(string< "abc" "") - @result{} nil -(string< "abc" "ab") - @result{} nil -(string< "" "") - @result{} nil -@end group -@end example - -Symbols are also allowed as arguments, in which case their print names -are used. -@end defun - -@defun string-lessp string1 string2 -@code{string-lessp} is another name for @code{string<}. -@end defun - -@defun string-prefix-p string1 string2 &optional ignore-case -This function returns non-@code{nil} if @var{string1} is a prefix of -@var{string2}; i.e., if @var{string2} starts with @var{string1}. If -the optional argument @var{ignore-case} is non-@code{nil}, the -comparison ignores case differences. -@end defun - -@defun string-suffix-p suffix string &optional ignore-case -This function returns non-@code{nil} if @var{suffix} is a suffix of -@var{string}; i.e., if @var{string} ends with @var{suffix}. If the -optional argument @var{ignore-case} is non-@code{nil}, the comparison -ignores case differences. -@end defun - -@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case -This function compares a specified part of @var{string1} with a -specified part of @var{string2}. The specified part of @var{string1} -runs from index @var{start1} (inclusive) up to index @var{end1} -(exclusive); @code{nil} for @var{start1} means the start of the -string, while @code{nil} for @var{end1} means the length of the -string. Likewise, the specified part of @var{string2} runs from index -@var{start2} up to index @var{end2}. - -The strings are compared by the numeric values of their characters. -For instance, @var{str1} is considered ``smaller than'' @var{str2} if -its first differing character has a smaller numeric value. If -@var{ignore-case} is non-@code{nil}, characters are converted to -lower-case before comparing them. Unibyte strings are converted to -multibyte for comparison (@pxref{Text Representations}), so that a -unibyte string and its conversion to multibyte are always regarded as -equal. - -If the specified portions of the two strings match, the value is -@code{t}. Otherwise, the value is an integer which indicates how many -leading characters agree, and which string is less. Its absolute -value is one plus the number of characters that agree at the beginning -of the two strings. The sign is negative if @var{string1} (or its -specified portion) is less. -@end defun - -@defun assoc-string key alist &optional case-fold -This function works like @code{assoc}, except that @var{key} must be a -string or symbol, and comparison is done using @code{compare-strings}. -Symbols are converted to strings before testing. -If @var{case-fold} is non-@code{nil}, it ignores case differences. -Unlike @code{assoc}, this function can also match elements of the alist -that are strings or symbols rather than conses. In particular, @var{alist} can -be a list of strings or symbols rather than an actual alist. -@xref{Association Lists}. -@end defun - - See also the function @code{compare-buffer-substrings} in -@ref{Comparing Text}, for a way to compare text in buffers. The -function @code{string-match}, which matches a regular expression -against a string, can be used for a kind of string comparison; see -@ref{Regexp Search}. - -@node String Conversion -@section Conversion of Characters and Strings -@cindex conversion of strings - - This section describes functions for converting between characters, -strings and integers. @code{format} (@pxref{Formatting Strings}) and -@code{prin1-to-string} (@pxref{Output Functions}) can also convert -Lisp objects into strings. @code{read-from-string} (@pxref{Input -Functions}) can ``convert'' a string representation of a Lisp object -into an object. The functions @code{string-to-multibyte} and -@code{string-to-unibyte} convert the text representation of a string -(@pxref{Converting Representations}). - - @xref{Documentation}, for functions that produce textual descriptions -of text characters and general input events -(@code{single-key-description} and @code{text-char-description}). These -are used primarily for making help messages. - -@defun number-to-string number -@cindex integer to string -@cindex integer to decimal -This function returns a string consisting of the printed base-ten -representation of @var{number}. The returned value starts with a -minus sign if the argument is negative. - -@example -(number-to-string 256) - @result{} "256" -@group -(number-to-string -23) - @result{} "-23" -@end group -(number-to-string -23.5) - @result{} "-23.5" -@end example - -@cindex int-to-string -@code{int-to-string} is a semi-obsolete alias for this function. - -See also the function @code{format} in @ref{Formatting Strings}. -@end defun - -@defun string-to-number string &optional base -@cindex string to number -This function returns the numeric value of the characters in -@var{string}. If @var{base} is non-@code{nil}, it must be an integer -between 2 and 16 (inclusive), and integers are converted in that base. -If @var{base} is @code{nil}, then base ten is used. Floating-point -conversion only works in base ten; we have not implemented other -radices for floating-point numbers, because that would be much more -work and does not seem useful. If @var{string} looks like an integer -but its value is too large to fit into a Lisp integer, -@code{string-to-number} returns a floating-point result. - -The parsing skips spaces and tabs at the beginning of @var{string}, -then reads as much of @var{string} as it can interpret as a number in -the given base. (On some systems it ignores other whitespace at the -beginning, not just spaces and tabs.) If @var{string} cannot be -interpreted as a number, this function returns 0. - -@example -(string-to-number "256") - @result{} 256 -(string-to-number "25 is a perfect square.") - @result{} 25 -(string-to-number "X256") - @result{} 0 -(string-to-number "-4.5") - @result{} -4.5 -(string-to-number "1e5") - @result{} 100000.0 -@end example - -@findex string-to-int -@code{string-to-int} is an obsolete alias for this function. -@end defun - -@defun char-to-string character -@cindex character to string -This function returns a new string containing one character, -@var{character}. This function is semi-obsolete because the function -@code{string} is more general. @xref{Creating Strings}. -@end defun - -@defun string-to-char string - This function returns the first character in @var{string}. This -mostly identical to @code{(aref string 0)}, except that it returns 0 -if the string is empty. (The value is also 0 when the first character -of @var{string} is the null character, @acronym{ASCII} code 0.) This -function may be eliminated in the future if it does not seem useful -enough to retain. -@end defun - - Here are some other functions that can convert to or from a string: - -@table @code -@item concat -This function converts a vector or a list into a string. -@xref{Creating Strings}. - -@item vconcat -This function converts a string into a vector. @xref{Vector -Functions}. - -@item append -This function converts a string into a list. @xref{Building Lists}. - -@item byte-to-string -This function converts a byte of character data into a unibyte string. -@xref{Converting Representations}. -@end table - -@node Formatting Strings -@section Formatting Strings -@cindex formatting strings -@cindex strings, formatting them - - @dfn{Formatting} means constructing a string by substituting -computed values at various places in a constant string. This constant -string controls how the other values are printed, as well as where -they appear; it is called a @dfn{format string}. - - Formatting is often useful for computing messages to be displayed. In -fact, the functions @code{message} and @code{error} provide the same -formatting feature described here; they differ from @code{format} only -in how they use the result of formatting. - -@defun format string &rest objects -This function returns a new string that is made by copying -@var{string} and then replacing any format specification -in the copy with encodings of the corresponding @var{objects}. The -arguments @var{objects} are the computed values to be formatted. - -The characters in @var{string}, other than the format specifications, -are copied directly into the output, including their text properties, -if any. -@end defun - -@cindex @samp{%} in format -@cindex format specification - A format specification is a sequence of characters beginning with a -@samp{%}. Thus, if there is a @samp{%d} in @var{string}, the -@code{format} function replaces it with the printed representation of -one of the values to be formatted (one of the arguments @var{objects}). -For example: - -@example -@group -(format "The value of fill-column is %d." fill-column) - @result{} "The value of fill-column is 72." -@end group -@end example - - Since @code{format} interprets @samp{%} characters as format -specifications, you should @emph{never} pass an arbitrary string as -the first argument. This is particularly true when the string is -generated by some Lisp code. Unless the string is @emph{known} to -never include any @samp{%} characters, pass @code{"%s"}, described -below, as the first argument, and the string as the second, like this: - -@example - (format "%s" @var{arbitrary-string}) -@end example - - If @var{string} contains more than one format specification, the -format specifications correspond to successive values from -@var{objects}. Thus, the first format specification in @var{string} -uses the first such value, the second format specification uses the -second such value, and so on. Any extra format specifications (those -for which there are no corresponding values) cause an error. Any -extra values to be formatted are ignored. - - Certain format specifications require values of particular types. If -you supply a value that doesn't fit the requirements, an error is -signaled. - - Here is a table of valid format specifications: - -@table @samp -@item %s -Replace the specification with the printed representation of the object, -made without quoting (that is, using @code{princ}, not -@code{prin1}---@pxref{Output Functions}). Thus, strings are represented -by their contents alone, with no @samp{"} characters, and symbols appear -without @samp{\} characters. - -If the object is a string, its text properties are -copied into the output. The text properties of the @samp{%s} itself -are also copied, but those of the object take priority. - -@item %S -Replace the specification with the printed representation of the object, -made with quoting (that is, using @code{prin1}---@pxref{Output -Functions}). Thus, strings are enclosed in @samp{"} characters, and -@samp{\} characters appear where necessary before special characters. - -@item %o -@cindex integer to octal -Replace the specification with the base-eight representation of an -integer. - -@item %d -Replace the specification with the base-ten representation of an -integer. - -@item %x -@itemx %X -@cindex integer to hexadecimal -Replace the specification with the base-sixteen representation of an -integer. @samp{%x} uses lower case and @samp{%X} uses upper case. - -@item %c -Replace the specification with the character which is the value given. - -@item %e -Replace the specification with the exponential notation for a -floating-point number. - -@item %f -Replace the specification with the decimal-point notation for a -floating-point number. - -@item %g -Replace the specification with notation for a floating-point number, -using either exponential notation or decimal-point notation, whichever -is shorter. - -@item %% -Replace the specification with a single @samp{%}. This format -specification is unusual in that it does not use a value. For example, -@code{(format "%% %d" 30)} returns @code{"% 30"}. -@end table - - Any other format character results in an @samp{Invalid format -operation} error. - - Here are several examples: - -@example -@group -(format "The name of this buffer is %s." (buffer-name)) - @result{} "The name of this buffer is strings.texi." - -(format "The buffer object prints as %s." (current-buffer)) - @result{} "The buffer object prints as strings.texi." - -(format "The octal value of %d is %o, - and the hex value is %x." 18 18 18) - @result{} "The octal value of 18 is 22, - and the hex value is 12." -@end group -@end example - -@cindex field width -@cindex padding - A specification can have a @dfn{width}, which is a decimal number -between the @samp{%} and the specification character. If the printed -representation of the object contains fewer characters than this -width, @code{format} extends it with padding. The width specifier is -ignored for the @samp{%%} specification. Any padding introduced by -the width specifier normally consists of spaces inserted on the left: - -@example -(format "%5d is padded on the left with spaces" 123) - @result{} " 123 is padded on the left with spaces" -@end example - -@noindent -If the width is too small, @code{format} does not truncate the -object's printed representation. Thus, you can use a width to specify -a minimum spacing between columns with no risk of losing information. -In the following three examples, @samp{%7s} specifies a minimum width -of 7. In the first case, the string inserted in place of @samp{%7s} -has only 3 letters, and needs 4 blank spaces as padding. In the -second case, the string @code{"specification"} is 13 letters wide but -is not truncated. - -@example -@group -(format "The word `%7s' has %d letters in it." - "foo" (length "foo")) - @result{} "The word ` foo' has 3 letters in it." -(format "The word `%7s' has %d letters in it." - "specification" (length "specification")) - @result{} "The word `specification' has 13 letters in it." -@end group -@end example - -@cindex flags in format specifications - Immediately after the @samp{%} and before the optional width -specifier, you can also put certain @dfn{flag characters}. - - The flag @samp{+} inserts a plus sign before a positive number, so -that it always has a sign. A space character as flag inserts a space -before a positive number. (Otherwise, positive numbers start with the -first digit.) These flags are useful for ensuring that positive -numbers and negative numbers use the same number of columns. They are -ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if -both flags are used, @samp{+} takes precedence. - - The flag @samp{#} specifies an ``alternate form'' which depends on -the format in use. For @samp{%o}, it ensures that the result begins -with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result -with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g}, -the @samp{#} flag means include a decimal point even if the precision -is zero. - - The flag @samp{0} ensures that the padding consists of @samp{0} -characters instead of spaces. This flag is ignored for non-numerical -specification characters like @samp{%s}, @samp{%S} and @samp{%c}. -These specification characters accept the @samp{0} flag, but still pad -with @emph{spaces}. - - The flag @samp{-} causes the padding inserted by the width -specifier, if any, to be inserted on the right rather than the left. -If both @samp{-} and @samp{0} are present, the @samp{0} flag is -ignored. - -@example -@group -(format "%06d is padded on the left with zeros" 123) - @result{} "000123 is padded on the left with zeros" - -(format "%-6d is padded on the right" 123) - @result{} "123 is padded on the right" - -(format "The word `%-7s' actually has %d letters in it." - "foo" (length "foo")) - @result{} "The word `foo ' actually has 3 letters in it." -@end group -@end example - -@cindex precision in format specifications - All the specification characters allow an optional @dfn{precision} -before the character (after the width, if present). The precision is -a decimal-point @samp{.} followed by a digit-string. For the -floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the -precision specifies how many decimal places to show; if zero, the -decimal-point itself is also omitted. For @samp{%s} and @samp{%S}, -the precision truncates the string to the given width, so @samp{%.3s} -shows only the first three characters of the representation for -@var{object}. Precision has no effect for other specification -characters. - -@node Case Conversion -@section Case Conversion in Lisp -@cindex upper case -@cindex lower case -@cindex character case -@cindex case conversion in Lisp - - The character case functions change the case of single characters or -of the contents of strings. The functions normally convert only -alphabetic characters (the letters @samp{A} through @samp{Z} and -@samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other -characters are not altered. You can specify a different case -conversion mapping by specifying a case table (@pxref{Case Tables}). - - These functions do not modify the strings that are passed to them as -arguments. - - The examples below use the characters @samp{X} and @samp{x} which have -@acronym{ASCII} codes 88 and 120 respectively. - -@defun downcase string-or-char -This function converts @var{string-or-char}, which should be either a -character or a string, to lower case. - -When @var{string-or-char} is a string, this function returns a new -string in which each letter in the argument that is upper case is -converted to lower case. When @var{string-or-char} is a character, -this function returns the corresponding lower case character (an -integer); if the original character is lower case, or is not a letter, -the return value is equal to the original character. - -@example -(downcase "The cat in the hat") - @result{} "the cat in the hat" - -(downcase ?X) - @result{} 120 -@end example -@end defun - -@defun upcase string-or-char -This function converts @var{string-or-char}, which should be either a -character or a string, to upper case. - -When @var{string-or-char} is a string, this function returns a new -string in which each letter in the argument that is lower case is -converted to upper case. When @var{string-or-char} is a character, -this function returns the corresponding upper case character (an -integer); if the original character is upper case, or is not a letter, -the return value is equal to the original character. - -@example -(upcase "The cat in the hat") - @result{} "THE CAT IN THE HAT" - -(upcase ?x) - @result{} 88 -@end example -@end defun - -@defun capitalize string-or-char -@cindex capitalization -This function capitalizes strings or characters. If -@var{string-or-char} is a string, the function returns a new string -whose contents are a copy of @var{string-or-char} in which each word -has been capitalized. This means that the first character of each -word is converted to upper case, and the rest are converted to lower -case. - -The definition of a word is any sequence of consecutive characters that -are assigned to the word constituent syntax class in the current syntax -table (@pxref{Syntax Class Table}). - -When @var{string-or-char} is a character, this function does the same -thing as @code{upcase}. - -@example -@group -(capitalize "The cat in the hat") - @result{} "The Cat In The Hat" -@end group - -@group -(capitalize "THE 77TH-HATTED CAT") - @result{} "The 77th-Hatted Cat" -@end group - -@group -(capitalize ?x) - @result{} 88 -@end group -@end example -@end defun - -@defun upcase-initials string-or-char -If @var{string-or-char} is a string, this function capitalizes the -initials of the words in @var{string-or-char}, without altering any -letters other than the initials. It returns a new string whose -contents are a copy of @var{string-or-char}, in which each word has -had its initial letter converted to upper case. - -The definition of a word is any sequence of consecutive characters that -are assigned to the word constituent syntax class in the current syntax -table (@pxref{Syntax Class Table}). - -When the argument to @code{upcase-initials} is a character, -@code{upcase-initials} has the same result as @code{upcase}. - -@example -@group -(upcase-initials "The CAT in the hAt") - @result{} "The CAT In The HAt" -@end group -@end example -@end defun - - @xref{Text Comparison}, for functions that compare strings; some of -them ignore case differences, or can optionally ignore case differences. - -@node Case Tables -@section The Case Table - - You can customize case conversion by installing a special @dfn{case -table}. A case table specifies the mapping between upper case and lower -case letters. It affects both the case conversion functions for Lisp -objects (see the previous section) and those that apply to text in the -buffer (@pxref{Case Changes}). Each buffer has a case table; there is -also a standard case table which is used to initialize the case table -of new buffers. - - A case table is a char-table (@pxref{Char-Tables}) whose subtype is -@code{case-table}. This char-table maps each character into the -corresponding lower case character. It has three extra slots, which -hold related tables: - -@table @var -@item upcase -The upcase table maps each character into the corresponding upper -case character. -@item canonicalize -The canonicalize table maps all of a set of case-related characters -into a particular member of that set. -@item equivalences -The equivalences table maps each one of a set of case-related characters -into the next character in that set. -@end table - - In simple cases, all you need to specify is the mapping to lower-case; -the three related tables will be calculated automatically from that one. - - For some languages, upper and lower case letters are not in one-to-one -correspondence. There may be two different lower case letters with the -same upper case equivalent. In these cases, you need to specify the -maps for both lower case and upper case. - - The extra table @var{canonicalize} maps each character to a canonical -equivalent; any two characters that are related by case-conversion have -the same canonical equivalent character. For example, since @samp{a} -and @samp{A} are related by case-conversion, they should have the same -canonical equivalent character (which should be either @samp{a} for both -of them, or @samp{A} for both of them). - - The extra table @var{equivalences} is a map that cyclically permutes -each equivalence class (of characters with the same canonical -equivalent). (For ordinary @acronym{ASCII}, this would map @samp{a} into -@samp{A} and @samp{A} into @samp{a}, and likewise for each set of -equivalent characters.) - - When constructing a case table, you can provide @code{nil} for -@var{canonicalize}; then Emacs fills in this slot from the lower case -and upper case mappings. You can also provide @code{nil} for -@var{equivalences}; then Emacs fills in this slot from -@var{canonicalize}. In a case table that is actually in use, those -components are non-@code{nil}. Do not try to specify -@var{equivalences} without also specifying @var{canonicalize}. - - Here are the functions for working with case tables: - -@defun case-table-p object -This predicate returns non-@code{nil} if @var{object} is a valid case -table. -@end defun - -@defun set-standard-case-table table -This function makes @var{table} the standard case table, so that it will -be used in any buffers created subsequently. -@end defun - -@defun standard-case-table -This returns the standard case table. -@end defun - -@defun current-case-table -This function returns the current buffer's case table. -@end defun - -@defun set-case-table table -This sets the current buffer's case table to @var{table}. -@end defun - -@defmac with-case-table table body@dots{} -The @code{with-case-table} macro saves the current case table, makes -@var{table} the current case table, evaluates the @var{body} forms, -and finally restores the case table. The return value is the value of -the last form in @var{body}. The case table is restored even in case -of an abnormal exit via @code{throw} or error (@pxref{Nonlocal -Exits}). -@end defmac - - Some language environments modify the case conversions of -@acronym{ASCII} characters; for example, in the Turkish language -environment, the @acronym{ASCII} character @samp{I} is downcased into -a Turkish ``dotless i''. This can interfere with code that requires -ordinary @acronym{ASCII} case conversion, such as implementations of -@acronym{ASCII}-based network protocols. In that case, use the -@code{with-case-table} macro with the variable @var{ascii-case-table}, -which stores the unmodified case table for the @acronym{ASCII} -character set. - -@defvar ascii-case-table -The case table for the @acronym{ASCII} character set. This should not be -modified by any language environment settings. -@end defvar - - The following three functions are convenient subroutines for packages -that define non-@acronym{ASCII} character sets. They modify the specified -case table @var{case-table}; they also modify the standard syntax table. -@xref{Syntax Tables}. Normally you would use these functions to change -the standard case table. - -@defun set-case-syntax-pair uc lc case-table -This function specifies a pair of corresponding letters, one upper case -and one lower case. -@end defun - -@defun set-case-syntax-delims l r case-table -This function makes characters @var{l} and @var{r} a matching pair of -case-invariant delimiters. -@end defun - -@defun set-case-syntax char syntax case-table -This function makes @var{char} case-invariant, with syntax -@var{syntax}. -@end defun - -@deffn Command describe-buffer-case-table -This command displays a description of the contents of the current -buffer's case table. -@end deffn diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi deleted file mode 100644 index e4455692d45..00000000000 --- a/doc/lispref/symbols.texi +++ /dev/null @@ -1,571 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Symbols -@chapter Symbols -@cindex symbol - - A @dfn{symbol} is an object with a unique name. This chapter -describes symbols, their components, their property lists, and how they -are created and interned. Separate chapters describe the use of symbols -as variables and as function names; see @ref{Variables}, and -@ref{Functions}. For the precise read syntax for symbols, see -@ref{Symbol Type}. - - You can test whether an arbitrary Lisp object is a symbol with -@code{symbolp}: - -@defun symbolp object -This function returns @code{t} if @var{object} is a symbol, @code{nil} -otherwise. -@end defun - -@menu -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Symbol Properties:: Each symbol has a property list - for recording miscellaneous information. -@end menu - -@node Symbol Components -@section Symbol Components -@cindex symbol components - - Each symbol has four components (or ``cells''), each of which -references another object: - -@table @asis -@item Print name -@cindex print name cell -The symbol's name. - -@item Value -@cindex value cell -The symbol's current value as a variable. - -@item Function -@cindex function cell -The symbol's function definition. It can also hold a symbol, a -keymap, or a keyboard macro. - -@item Property list -@cindex property list cell -The symbol's property list. -@end table - -@noindent -The print name cell always holds a string, and cannot be changed. -Each of the other three cells can be set to any Lisp object. - - The print name cell holds the string that is the name of a symbol. -Since symbols are represented textually by their names, it is -important not to have two symbols with the same name. The Lisp reader -ensures this: every time it reads a symbol, it looks for an existing -symbol with the specified name before it creates a new one. To get a -symbol's name, use the function @code{symbol-name} (@pxref{Creating -Symbols}). - - The value cell holds a symbol's value as a variable, which is what -you get if the symbol itself is evaluated as a Lisp expression. -@xref{Variables}, for details about how values are set and retrieved, -including complications such as @dfn{local bindings} and @dfn{scoping -rules}. Most symbols can have any Lisp object as a value, but certain -special symbols have values that cannot be changed; these include -@code{nil} and @code{t}, and any symbol whose name starts with -@samp{:} (those are called @dfn{keywords}). @xref{Constant -Variables}. - - The function cell holds a symbol's function definition. Often, we -refer to ``the function @code{foo}'' when we really mean the function -stored in the function cell of @code{foo}; we make the distinction -explicit only when necessary. Typically, the function cell is used to -hold a function (@pxref{Functions}) or a macro (@pxref{Macros}). -However, it can also be used to hold a symbol (@pxref{Function -Indirection}), keyboard macro (@pxref{Keyboard Macros}), keymap -(@pxref{Keymaps}), or autoload object (@pxref{Autoloading}). To get -the contents of a symbol's function cell, use the function -@code{symbol-function} (@pxref{Function Cells}). - - The property list cell normally should hold a correctly formatted -property list. To get a symbol's property list, use the function -@code{symbol-plist}. @xref{Symbol Properties}. - - The function cell or the value cell may be @dfn{void}, which means -that the cell does not reference any object. (This is not the same -thing as holding the symbol @code{void}, nor the same as holding the -symbol @code{nil}.) Examining a function or value cell that is void -results in an error, such as @samp{Symbol's value as variable is void}. - - Because each symbol has separate value and function cells, variables -names and function names do not conflict. For example, the symbol -@code{buffer-file-name} has a value (the name of the file being -visited in the current buffer) as well as a function definition (a -primitive function that returns the name of the file): - -@example -buffer-file-name - @result{} "/gnu/elisp/symbols.texi" -(symbol-function 'buffer-file-name) - @result{} # -@end example - -@node Definitions -@section Defining Symbols -@cindex definitions of symbols - - A @dfn{definition} is a special kind of Lisp expression that -announces your intention to use a symbol in a particular way. It -typically specifies a value or meaning for the symbol for one kind of -use, plus documentation for its meaning when used in this way. Thus, -when you define a symbol as a variable, you can supply an initial -value for the variable, plus documentation for the variable. - - @code{defvar} and @code{defconst} are special forms that define a -symbol as a @dfn{global variable}---a variable that can be accessed at -any point in a Lisp program. @xref{Variables}, for details about -variables. To define a customizable variable, use the -@code{defcustom} macro, which also calls @code{defvar} as a subroutine -(@pxref{Customization}). - - In principle, you can assign a variable value to any symbol with -@code{setq}, whether not it has first been defined as a variable. -However, you ought to write a variable definition for each global -variable that you want to use; otherwise, your Lisp program may not -act correctly if it is evaluated with lexical scoping enabled -(@pxref{Variable Scoping}). - - @code{defun} defines a symbol as a function, creating a lambda -expression and storing it in the function cell of the symbol. This -lambda expression thus becomes the function definition of the symbol. -(The term ``function definition'', meaning the contents of the function -cell, is derived from the idea that @code{defun} gives the symbol its -definition as a function.) @code{defsubst} and @code{defalias} are two -other ways of defining a function. @xref{Functions}. - - @code{defmacro} defines a symbol as a macro. It creates a macro -object and stores it in the function cell of the symbol. Note that a -given symbol can be a macro or a function, but not both at once, because -both macro and function definitions are kept in the function cell, and -that cell can hold only one Lisp object at any given time. -@xref{Macros}. - - As previously noted, Emacs Lisp allows the same symbol to be defined -both as a variable (e.g., with @code{defvar}) and as a function or -macro (e.g., with @code{defun}). Such definitions do not conflict. - - These definition also act as guides for programming tools. For -example, the @kbd{C-h f} and @kbd{C-h v} commands create help buffers -containing links to the relevant variable, function, or macro -definitions. @xref{Name Help,,, emacs, The GNU Emacs Manual}. - -@node Creating Symbols -@section Creating and Interning Symbols -@cindex reading symbols - - To understand how symbols are created in GNU Emacs Lisp, you must know -how Lisp reads them. Lisp must ensure that it finds the same symbol -every time it reads the same set of characters. Failure to do so would -cause complete confusion. - -@cindex symbol name hashing -@cindex hashing -@cindex obarray -@cindex bucket (in obarray) - When the Lisp reader encounters a symbol, it reads all the characters -of the name. Then it ``hashes'' those characters to find an index in a -table called an @dfn{obarray}. Hashing is an efficient method of -looking something up. For example, instead of searching a telephone -book cover to cover when looking up Jan Jones, you start with the J's -and go from there. That is a simple version of hashing. Each element -of the obarray is a @dfn{bucket} which holds all the symbols with a -given hash code; to look for a given name, it is sufficient to look -through all the symbols in the bucket for that name's hash code. (The -same idea is used for general Emacs hash tables, but they are a -different data type; see @ref{Hash Tables}.) - -@cindex interning - If a symbol with the desired name is found, the reader uses that -symbol. If the obarray does not contain a symbol with that name, the -reader makes a new symbol and adds it to the obarray. Finding or adding -a symbol with a certain name is called @dfn{interning} it, and the -symbol is then called an @dfn{interned symbol}. - - Interning ensures that each obarray has just one symbol with any -particular name. Other like-named symbols may exist, but not in the -same obarray. Thus, the reader gets the same symbols for the same -names, as long as you keep reading with the same obarray. - - Interning usually happens automatically in the reader, but sometimes -other programs need to do it. For example, after the @kbd{M-x} command -obtains the command name as a string using the minibuffer, it then -interns the string, to get the interned symbol with that name. - -@cindex symbol equality -@cindex uninterned symbol - No obarray contains all symbols; in fact, some symbols are not in any -obarray. They are called @dfn{uninterned symbols}. An uninterned -symbol has the same four cells as other symbols; however, the only way -to gain access to it is by finding it in some other object or as the -value of a variable. - - Creating an uninterned symbol is useful in generating Lisp code, -because an uninterned symbol used as a variable in the code you generate -cannot clash with any variables used in other Lisp programs. - - In Emacs Lisp, an obarray is actually a vector. Each element of the -vector is a bucket; its value is either an interned symbol whose name -hashes to that bucket, or 0 if the bucket is empty. Each interned -symbol has an internal link (invisible to the user) to the next symbol -in the bucket. Because these links are invisible, there is no way to -find all the symbols in an obarray except using @code{mapatoms} (below). -The order of symbols in a bucket is not significant. - - In an empty obarray, every element is 0, so you can create an obarray -with @code{(make-vector @var{length} 0)}. @strong{This is the only -valid way to create an obarray.} Prime numbers as lengths tend -to result in good hashing; lengths one less than a power of two are also -good. - - @strong{Do not try to put symbols in an obarray yourself.} This does -not work---only @code{intern} can enter a symbol in an obarray properly. - -@cindex CL note---symbol in obarrays -@quotation -@b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide -for interning a single symbol in several obarrays. -@end quotation - - Most of the functions below take a name and sometimes an obarray as -arguments. A @code{wrong-type-argument} error is signaled if the name -is not a string, or if the obarray is not a vector. - -@defun symbol-name symbol -This function returns the string that is @var{symbol}'s name. For example: - -@example -@group -(symbol-name 'foo) - @result{} "foo" -@end group -@end example - -@strong{Warning:} Changing the string by substituting characters does -change the name of the symbol, but fails to update the obarray, so don't -do it! -@end defun - -@defun make-symbol name -This function returns a newly-allocated, uninterned symbol whose name is -@var{name} (which must be a string). Its value and function definition -are void, and its property list is @code{nil}. In the example below, -the value of @code{sym} is not @code{eq} to @code{foo} because it is a -distinct uninterned symbol whose name is also @samp{foo}. - -@example -(setq sym (make-symbol "foo")) - @result{} foo -(eq sym 'foo) - @result{} nil -@end example -@end defun - -@defun intern name &optional obarray -This function returns the interned symbol whose name is @var{name}. If -there is no such symbol in the obarray @var{obarray}, @code{intern} -creates a new one, adds it to the obarray, and returns it. If -@var{obarray} is omitted, the value of the global variable -@code{obarray} is used. - -@example -(setq sym (intern "foo")) - @result{} foo -(eq sym 'foo) - @result{} t - -(setq sym1 (intern "foo" other-obarray)) - @result{} foo -(eq sym1 'foo) - @result{} nil -@end example -@end defun - -@cindex CL note---interning existing symbol -@quotation -@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol -in an obarray. In Emacs Lisp, you cannot do this, because the argument -to @code{intern} must be a string, not a symbol. -@end quotation - -@defun intern-soft name &optional obarray -This function returns the symbol in @var{obarray} whose name is -@var{name}, or @code{nil} if @var{obarray} has no symbol with that name. -Therefore, you can use @code{intern-soft} to test whether a symbol with -a given name is already interned. If @var{obarray} is omitted, the -value of the global variable @code{obarray} is used. - -The argument @var{name} may also be a symbol; in that case, -the function returns @var{name} if @var{name} is interned -in the specified obarray, and otherwise @code{nil}. - -@example -(intern-soft "frazzle") ; @r{No such symbol exists.} - @result{} nil -(make-symbol "frazzle") ; @r{Create an uninterned one.} - @result{} frazzle -@group -(intern-soft "frazzle") ; @r{That one cannot be found.} - @result{} nil -@end group -@group -(setq sym (intern "frazzle")) ; @r{Create an interned one.} - @result{} frazzle -@end group -@group -(intern-soft "frazzle") ; @r{That one can be found!} - @result{} frazzle -@end group -@group -(eq sym 'frazzle) ; @r{And it is the same one.} - @result{} t -@end group -@end example -@end defun - -@defvar obarray -This variable is the standard obarray for use by @code{intern} and -@code{read}. -@end defvar - -@defun mapatoms function &optional obarray -@anchor{Definition of mapatoms} -This function calls @var{function} once with each symbol in the obarray -@var{obarray}. Then it returns @code{nil}. If @var{obarray} is -omitted, it defaults to the value of @code{obarray}, the standard -obarray for ordinary symbols. - -@example -(setq count 0) - @result{} 0 -(defun count-syms (s) - (setq count (1+ count))) - @result{} count-syms -(mapatoms 'count-syms) - @result{} nil -count - @result{} 1871 -@end example - -See @code{documentation} in @ref{Accessing Documentation}, for another -example using @code{mapatoms}. -@end defun - -@defun unintern symbol obarray -This function deletes @var{symbol} from the obarray @var{obarray}. If -@code{symbol} is not actually in the obarray, @code{unintern} does -nothing. If @var{obarray} is @code{nil}, the current obarray is used. - -If you provide a string instead of a symbol as @var{symbol}, it stands -for a symbol name. Then @code{unintern} deletes the symbol (if any) in -the obarray which has that name. If there is no such symbol, -@code{unintern} does nothing. - -If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise -it returns @code{nil}. -@end defun - -@node Symbol Properties -@section Symbol Properties -@cindex symbol property - - A symbol may possess any number of @dfn{symbol properties}, which -can be used to record miscellaneous information about the symbol. For -example, when a symbol has a @code{risky-local-variable} property with -a non-@code{nil} value, that means the variable which the symbol names -is a risky file-local variable (@pxref{File Local Variables}). - - Each symbol's properties and property values are stored in the -symbol's property list cell (@pxref{Symbol Components}), in the form -of a property list (@pxref{Property Lists}). - -@menu -* Symbol Plists:: Accessing symbol properties. -* Standard Properties:: Standard meanings of symbol properties. -@end menu - -@node Symbol Plists -@subsection Accessing Symbol Properties - - The following functions can be used to access symbol properties. - -@defun get symbol property -This function returns the value of the property named @var{property} -in @var{symbol}'s property list. If there is no such property, it -returns @code{nil}. Thus, there is no distinction between a value of -@code{nil} and the absence of the property. - -The name @var{property} is compared with the existing property names -using @code{eq}, so any object is a legitimate property. - -See @code{put} for an example. -@end defun - -@defun put symbol property value -This function puts @var{value} onto @var{symbol}'s property list under -the property name @var{property}, replacing any previous property value. -The @code{put} function returns @var{value}. - -@example -(put 'fly 'verb 'transitive) - @result{}'transitive -(put 'fly 'noun '(a buzzing little bug)) - @result{} (a buzzing little bug) -(get 'fly 'verb) - @result{} transitive -(symbol-plist 'fly) - @result{} (verb transitive noun (a buzzing little bug)) -@end example -@end defun - -@defun symbol-plist symbol -This function returns the property list of @var{symbol}. -@end defun - -@defun setplist symbol plist -This function sets @var{symbol}'s property list to @var{plist}. -Normally, @var{plist} should be a well-formed property list, but this is -not enforced. The return value is @var{plist}. - -@example -(setplist 'foo '(a 1 b (2 3) c nil)) - @result{} (a 1 b (2 3) c nil) -(symbol-plist 'foo) - @result{} (a 1 b (2 3) c nil) -@end example - -For symbols in special obarrays, which are not used for ordinary -purposes, it may make sense to use the property list cell in a -nonstandard fashion; in fact, the abbrev mechanism does so -(@pxref{Abbrevs}). - -You could define @code{put} in terms of @code{setplist} and -@code{plist-put}, as follows: - -@example -(defun put (symbol prop value) - (setplist symbol - (plist-put (symbol-plist symbol) prop value))) -@end example -@end defun - -@defun function-get symbol property -This function is identical to @code{get}, except that if @var{symbol} -is the name of a function alias, it looks in the property list of the -symbol naming the actual function. @xref{Defining Functions}. -@end defun - -@node Standard Properties -@subsection Standard Symbol Properties - - Here, we list the symbol properties which are used for special -purposes in Emacs. In the following table, whenever we say ``the -named function'', that means the function whose name is the relevant -symbol; similarly for ``the named variable'' etc. - -@table @code -@item :advertised-binding -This property value specifies the preferred key binding, when showing -documentation, for the named function. @xref{Keys in Documentation}. - -@item char-table-extra-slots -The value, if non-@code{nil}, specifies the number of extra slots in -the named char-table type. @xref{Char-Tables}. - -@item customized-face -@itemx face-defface-spec -@itemx saved-face -@itemx theme-face -These properties are used to record a face's standard, saved, -customized, and themed face specs. Do not set them directly; they are -managed by @code{defface} and related functions. @xref{Defining -Faces}. - -@item customized-value -@itemx saved-value -@itemx standard-value -@itemx theme-value -These properties are used to record a customizable variable's standard -value, saved value, customized-but-unsaved value, and themed values. -Do not set them directly; they are managed by @code{defcustom} and -related functions. @xref{Variable Definitions}. - -@item disabled -If the value is non-@code{nil}, the named function is disabled as a -command. @xref{Disabling Commands}. - -@item face-documentation -The value stores the documentation string of the named face. This is -set automatically by @code{defface}. @xref{Defining Faces}. - -@item history-length -The value, if non-@code{nil}, specifies the maximum minibuffer history -length for the named history list variable. @xref{Minibuffer -History}. - -@item interactive-form -The value is an interactive form for the named function. Normally, -you should not set this directly; use the @code{interactive} special -form instead. @xref{Interactive Call}. - -@item menu-enable -The value is an expression for determining whether the named menu item -should be enabled in menus. @xref{Simple Menu Items}. - -@item mode-class -If the value is @code{special}, the named major mode is ``special''. -@xref{Major Mode Conventions}. - -@item permanent-local -If the value is non-@code{nil}, the named variable is a buffer-local -variable whose value should not be reset when changing major modes. -@xref{Creating Buffer-Local}. - -@item permanent-local-hook -If the value is non-@code{nil}, the named function should not be -deleted from the local value of a hook variable when changing major -modes. @xref{Setting Hooks}. - -@item pure -If the value is non-@code{nil}, the named function is considered to be -side-effect free. Calls with constant arguments can be evaluated at -compile time. This may shift run time errors to compile time. - -@item risky-local-variable -If the value is non-@code{nil}, the named variable is considered risky -as a file-local variable. @xref{File Local Variables}. - -@item safe-function -If the value is non-@code{nil}, the named function is considered -generally safe for evaluation. @xref{Function Safety}. - -@item safe-local-eval-function -If the value is non-@code{nil}, the named function is safe to call in -file-local evaluation forms. @xref{File Local Variables}. - -@item safe-local-variable -The value specifies a function for determining safe file-local values -for the named variable. @xref{File Local Variables}. - -@item side-effect-free -A non-@code{nil} value indicates that the named function is free of -side-effects, for determining function safety (@pxref{Function -Safety}) as well as for byte compiler optimizations. Do not set it. - -@item variable-documentation -If non-@code{nil}, this specifies the named variable's documentation -string. This is set automatically by @code{defvar} and related -functions. @xref{Defining Faces}. -@end table diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi deleted file mode 100644 index 25e6089491e..00000000000 --- a/doc/lispref/syntax.texi +++ /dev/null @@ -1,1201 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Syntax Tables -@chapter Syntax Tables -@cindex parsing buffer text -@cindex syntax table -@cindex text parsing - - A @dfn{syntax table} specifies the syntactic role of each character -in a buffer. It can be used to determine where words, symbols, and -other syntactic constructs begin and end. This information is used by -many Emacs facilities, including Font Lock mode (@pxref{Font Lock -Mode}) and the various complex movement commands (@pxref{Motion}). - -@menu -* Basics: Syntax Basics. Basic concepts of syntax tables. -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. -@end menu - -@node Syntax Basics -@section Syntax Table Concepts - - A syntax table is a data structure which can be used to look up the -@dfn{syntax class} and other syntactic properties of each character. -Syntax tables are used by Lisp programs for scanning and moving across -text. - - Internally, a syntax table is a char-table (@pxref{Char-Tables}). -The element at index @var{c} describes the character with code -@var{c}; its value is a cons cell which specifies the syntax of the -character in question. @xref{Syntax Table Internals}, for details. -However, instead of using @code{aset} and @code{aref} to modify and -inspect syntax table contents, you should usually use the higher-level -functions @code{char-syntax} and @code{modify-syntax-entry}, which are -described in @ref{Syntax Table Functions}. - -@defun syntax-table-p object -This function returns @code{t} if @var{object} is a syntax table. -@end defun - - Each buffer has its own major mode, and each major mode has its own -idea of the syntax class of various characters. For example, in Lisp -mode, the character @samp{;} begins a comment, but in C mode, it -terminates a statement. To support these variations, the syntax table -is local to each buffer. Typically, each major mode has its own -syntax table, which it installs in all buffers that use that mode. -For example, the variable @code{emacs-lisp-mode-syntax-table} holds -the syntax table used by Emacs Lisp mode, and -@code{c-mode-syntax-table} holds the syntax table used by C mode. -Changing a major mode's syntax table alters the syntax in all of that -mode's buffers, as well as in any buffers subsequently put in that -mode. Occasionally, several similar modes share one syntax table. -@xref{Example Major Modes}, for an example of how to set up a syntax -table. - -@cindex standard syntax table -@cindex inheritance, syntax table - A syntax table can @dfn{inherit} from another syntax table, which is -called its @dfn{parent syntax table}. A syntax table can leave the -syntax class of some characters unspecified, by giving them the -``inherit'' syntax class; such a character then acquires the syntax -class specified by the parent syntax table (@pxref{Syntax Class -Table}). Emacs defines a @dfn{standard syntax table}, which is the -default parent syntax table, and is also the syntax table used by -Fundamental mode. - -@defun standard-syntax-table -This function returns the standard syntax table, which is the syntax -table used in Fundamental mode. -@end defun - - Syntax tables are not used by the Emacs Lisp reader, which has its -own built-in syntactic rules which cannot be changed. (Some Lisp -systems provide ways to redefine the read syntax, but we decided to -leave this feature out of Emacs Lisp for simplicity.) - -@node Syntax Descriptors -@section Syntax Descriptors -@cindex syntax class - - The @dfn{syntax class} of a character describes its syntactic role. -Each syntax table specifies the syntax class of each character. There -is no necessary relationship between the class of a character in one -syntax table and its class in any other table. - - Each syntax class is designated by a mnemonic character, which -serves as the name of the class when you need to specify a class. -Usually, this designator character is one that is often assigned that -class; however, its meaning as a designator is unvarying and -independent of what syntax that character currently has. Thus, -@samp{\} as a designator character always means ``escape character'' -syntax, regardless of whether the @samp{\} character actually has that -syntax in the current syntax table. -@ifnottex -@xref{Syntax Class Table}, for a list of syntax classes and their -designator characters. -@end ifnottex - -@cindex syntax descriptor - A @dfn{syntax descriptor} is a Lisp string that describes the syntax -class and other syntactic properties of a character. When you want to -modify the syntax of a character, that is done by calling the function -@code{modify-syntax-entry} and passing a syntax descriptor as one of -its arguments (@pxref{Syntax Table Functions}). - - The first character in a syntax descriptor must be a syntax class -designator character. The second character, if present, specifies a -matching character (e.g., in Lisp, the matching character for -@samp{(} is @samp{)}); a space specifies that there is no matching -character. Then come characters specifying additional syntax -properties (@pxref{Syntax Flags}). - - If no matching character or flags are needed, only one character -(specifying the syntax class) is sufficient. - - For example, the syntax descriptor for the character @samp{*} in C -mode is @code{". 23"} (i.e., punctuation, matching character slot -unused, second character of a comment-starter, first character of a -comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e., -punctuation, matching character slot unused, first character of a -comment-starter, second character of a comment-ender). - - Emacs also defines @dfn{raw syntax descriptors}, which are used to -describe syntax classes at a lower level. @xref{Syntax Table -Internals}. - -@menu -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. -@end menu - -@node Syntax Class Table -@subsection Table of Syntax Classes -@cindex syntax class table - - Here is a table of syntax classes, the characters that designate -them, their meanings, and examples of their use. - -@table @asis -@item Whitespace characters: @samp{@ } or @samp{-} -Characters that separate symbols and words from each other. -Typically, whitespace characters have no other syntactic significance, -and multiple whitespace characters are syntactically equivalent to a -single one. Space, tab, and formfeed are classified as whitespace in -almost all major modes. - -This syntax class can be designated by either @w{@samp{@ }} or -@samp{-}. Both designators are equivalent. - -@item Word constituents: @samp{w} -Parts of words in human languages. These are typically used in -variable and command names in programs. All upper- and lower-case -letters, and the digits, are typically word constituents. - -@item Symbol constituents: @samp{_} -Extra characters used in variable and command names along with word -constituents. Examples include the characters @samp{$&*+-_<>} in Lisp -mode, which may be part of a symbol name even though they are not part -of English words. In standard C, the only non-word-constituent -character that is valid in symbols is underscore (@samp{_}). - -@item Punctuation characters: @samp{.} -Characters used as punctuation in a human language, or used in a -programming language to separate symbols from one another. Some -programming language modes, such as Emacs Lisp mode, have no -characters in this class since the few characters that are not symbol -or word constituents all have other uses. Other programming language -modes, such as C mode, use punctuation syntax for operators. - -@item Open parenthesis characters: @samp{(} -@itemx Close parenthesis characters: @samp{)} -Characters used in dissimilar pairs to surround sentences or -expressions. Such a grouping is begun with an open parenthesis -character and terminated with a close. Each open parenthesis -character matches a particular close parenthesis character, and vice -versa. Normally, Emacs indicates momentarily the matching open -parenthesis when you insert a close parenthesis. @xref{Blinking}. - -In human languages, and in C code, the parenthesis pairs are -@samp{()}, @samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters -for lists and vectors (@samp{()} and @samp{[]}) are classified as -parenthesis characters. - -@item String quotes: @samp{"} -Characters used to delimit string constants. The same string quote -character appears at the beginning and the end of a string. Such -quoted strings do not nest. - -The parsing facilities of Emacs consider a string as a single token. -The usual syntactic meanings of the characters in the string are -suppressed. - -The Lisp modes have two string quote characters: double-quote (@samp{"}) -and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it -is used in Common Lisp. C also has two string quote characters: -double-quote for strings, and single-quote (@samp{'}) for character -constants. - -Human text has no string quote characters. We do not want quotation -marks to turn off the usual syntactic properties of other characters -in the quotation. - -@item Escape-syntax characters: @samp{\} -Characters that start an escape sequence, such as is used in string -and character constants. The character @samp{\} belongs to this class -in both C and Lisp. (In C, it is used thus only inside strings, but -it turns out to cause no trouble to treat it this way throughout C -code.) - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. - -@item Character quotes: @samp{/} -Characters used to quote the following character so that it loses its -normal syntactic meaning. This differs from an escape character in -that only the character immediately following is ever affected. - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. - -This class is used for backslash in @TeX{} mode. - -@item Paired delimiters: @samp{$} -Similar to string quote characters, except that the syntactic -properties of the characters between the delimiters are not -suppressed. Only @TeX{} mode uses a paired delimiter presently---the -@samp{$} that both enters and leaves math mode. - -@item Expression prefixes: @samp{'} -Characters used for syntactic operators that are considered as part of -an expression if they appear next to one. In Lisp modes, these -characters include the apostrophe, @samp{'} (used for quoting), the -comma, @samp{,} (used in macros), and @samp{#} (used in the read -syntax for certain data types). - -@item Comment starters: @samp{<} -@itemx Comment enders: @samp{>} -@cindex comment syntax -Characters used in various languages to delimit comments. Human text -has no comment characters. In Lisp, the semicolon (@samp{;}) starts a -comment and a newline or formfeed ends one. - -@item Inherit standard syntax: @samp{@@} -This syntax class does not specify a particular syntax. It says to -look in the standard syntax table to find the syntax of this -character. - -@item Generic comment delimiters: @samp{!} -Characters that start or end a special kind of comment. @emph{Any} -generic comment delimiter matches @emph{any} generic comment -delimiter, but they cannot match a comment starter or comment ender; -generic comment delimiters can only match each other. - -This syntax class is primarily meant for use with the -@code{syntax-table} text property (@pxref{Syntax Properties}). You -can mark any range of characters as forming a comment, by giving the -first and last characters of the range @code{syntax-table} properties -identifying them as generic comment delimiters. - -@item Generic string delimiters: @samp{|} -Characters that start or end a string. This class differs from the -string quote class in that @emph{any} generic string delimiter can -match any other generic string delimiter; but they do not match -ordinary string quote characters. - -This syntax class is primarily meant for use with the -@code{syntax-table} text property (@pxref{Syntax Properties}). You -can mark any range of characters as forming a string constant, by -giving the first and last characters of the range @code{syntax-table} -properties identifying them as generic string delimiters. -@end table - -@node Syntax Flags -@subsection Syntax Flags -@cindex syntax flags - - In addition to the classes, entries for characters in a syntax table -can specify flags. There are eight possible flags, represented by the -characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{c}, -@samp{n}, and @samp{p}. - - All the flags except @samp{p} are used to describe comment -delimiters. The digit flags are used for comment delimiters made up -of 2 characters. They indicate that a character can @emph{also} be -part of a comment sequence, in addition to the syntactic properties -associated with its character class. The flags are independent of the -class and each other for the sake of characters such as @samp{*} in -C mode, which is a punctuation character, @emph{and} the second -character of a start-of-comment sequence (@samp{/*}), @emph{and} the -first character of an end-of-comment sequence (@samp{*/}). The flags -@samp{b}, @samp{c}, and @samp{n} are used to qualify the corresponding -comment delimiter. - - Here is a table of the possible flags for a character @var{c}, -and what they mean: - -@itemize @bullet -@item -@samp{1} means @var{c} is the start of a two-character comment-start -sequence. - -@item -@samp{2} means @var{c} is the second character of such a sequence. - -@item -@samp{3} means @var{c} is the start of a two-character comment-end -sequence. - -@item -@samp{4} means @var{c} is the second character of such a sequence. - -@item -@samp{b} means that @var{c} as a comment delimiter belongs to the -alternative ``b'' comment style. For a two-character comment starter, -this flag is only significant on the second char, and for a 2-character -comment ender it is only significant on the first char. - -@item -@samp{c} means that @var{c} as a comment delimiter belongs to the -alternative ``c'' comment style. For a two-character comment -delimiter, @samp{c} on either character makes it of style ``c''. - -@item -@samp{n} on a comment delimiter character specifies -that this kind of comment can be nested. For a two-character -comment delimiter, @samp{n} on either character makes it -nestable. - -@cindex comment style -Emacs supports several comment styles simultaneously in any one syntax -table. A comment style is a set of flags @samp{b}, @samp{c}, and -@samp{n}, so there can be up to 8 different comment styles. -Each comment delimiter has a style and only matches comment delimiters -of the same style. Thus if a comment starts with the comment-start -sequence of style ``bn'', it will extend until the next matching -comment-end sequence of style ``bn''. - -The appropriate comment syntax settings for C++ can be as follows: - -@table @asis -@item @samp{/} -@samp{124} -@item @samp{*} -@samp{23b} -@item newline -@samp{>} -@end table - -This defines four comment-delimiting sequences: - -@table @asis -@item @samp{/*} -This is a comment-start sequence for ``b'' style because the -second character, @samp{*}, has the @samp{b} flag. - -@item @samp{//} -This is a comment-start sequence for ``a'' style because the second -character, @samp{/}, does not have the @samp{b} flag. - -@item @samp{*/} -This is a comment-end sequence for ``b'' style because the first -character, @samp{*}, has the @samp{b} flag. - -@item newline -This is a comment-end sequence for ``a'' style, because the newline -character does not have the @samp{b} flag. -@end table - -@item -@samp{p} identifies an additional ``prefix character'' for Lisp syntax. -These characters are treated as whitespace when they appear between -expressions. When they appear within an expression, they are handled -according to their usual syntax classes. - -The function @code{backward-prefix-chars} moves back over these -characters, as well as over characters whose primary syntax class is -prefix (@samp{'}). @xref{Motion and Syntax}. -@end itemize - -@node Syntax Table Functions -@section Syntax Table Functions - - In this section we describe functions for creating, accessing and -altering syntax tables. - -@defun make-syntax-table &optional table -This function creates a new syntax table. If @var{table} is -non-@code{nil}, the parent of the new syntax table is @var{table}; -otherwise, the parent is the standard syntax table. - -In the new syntax table, all characters are initially given the -``inherit'' (@samp{@@}) syntax class, i.e., their syntax is inherited -from the parent table (@pxref{Syntax Class Table}). -@end defun - -@defun copy-syntax-table &optional table -This function constructs a copy of @var{table} and returns it. If -@var{table} is omitted or @code{nil}, it returns a copy of the -standard syntax table. Otherwise, an error is signaled if @var{table} -is not a syntax table. -@end defun - -@deffn Command modify-syntax-entry char syntax-descriptor &optional table -@cindex syntax entry, setting -This function sets the syntax entry for @var{char} according to -@var{syntax-descriptor}. @var{char} must be a character, or a cons -cell of the form @code{(@var{min} . @var{max})}; in the latter case, -the function sets the syntax entries for all characters in the range -between @var{min} and @var{max}, inclusive. - -The syntax is changed only for @var{table}, which defaults to the -current buffer's syntax table, and not in any other syntax table. - -The argument @var{syntax-descriptor} is a syntax descriptor, i.e., a -string whose first character is a syntax class designator and whose -second and subsequent characters optionally specify a matching -character and syntax flags. @xref{Syntax Descriptors}. An error is -signaled if @var{syntax-descriptor} is not a valid syntax descriptor. - -This function always returns @code{nil}. The old syntax information in -the table for this character is discarded. - -@example -@group -@exdent @r{Examples:} - -;; @r{Put the space character in class whitespace.} -(modify-syntax-entry ?\s " ") - @result{} nil -@end group - -@group -;; @r{Make @samp{$} an open parenthesis character,} -;; @r{with @samp{^} as its matching close.} -(modify-syntax-entry ?$ "(^") - @result{} nil -@end group - -@group -;; @r{Make @samp{^} a close parenthesis character,} -;; @r{with @samp{$} as its matching open.} -(modify-syntax-entry ?^ ")$") - @result{} nil -@end group - -@group -;; @r{Make @samp{/} a punctuation character,} -;; @r{the first character of a start-comment sequence,} -;; @r{and the second character of an end-comment sequence.} -;; @r{This is used in C mode.} -(modify-syntax-entry ?/ ". 14") - @result{} nil -@end group -@end example -@end deffn - -@defun char-syntax character -This function returns the syntax class of @var{character}, represented -by its designator character (@pxref{Syntax Class Table}). This -returns @emph{only} the class, not its matching character or syntax -flags. - -The following examples apply to C mode. (We use @code{string} to make -it easier to see the character returned by @code{char-syntax}.) - -@example -@group -;; Space characters have whitespace syntax class. -(string (char-syntax ?\s)) - @result{} " " -@end group - -@group -;; Forward slash characters have punctuation syntax. -;; Note that this @code{char-syntax} call does not reveal -;; that it is also part of comment-start and -end sequences. -(string (char-syntax ?/)) - @result{} "." -@end group - -@group -;; Open parenthesis characters have open parenthesis syntax. -;; Note that this @code{char-syntax} call does not reveal that -;; it has a matching character, @samp{)}. -(string (char-syntax ?\()) - @result{} "(" -@end group -@end example - -@end defun - -@defun set-syntax-table table -This function makes @var{table} the syntax table for the current buffer. -It returns @var{table}. -@end defun - -@defun syntax-table -This function returns the current syntax table, which is the table for -the current buffer. -@end defun - -@deffn Command describe-syntax &optional buffer -This command displays the contents of the syntax table of -@var{buffer} (by default, the current buffer) in a help buffer. -@end deffn - -@defmac with-syntax-table table body@dots{} -This macro executes @var{body} using @var{table} as the current syntax -table. It returns the value of the last form in @var{body}, after -restoring the old current syntax table. - -Since each buffer has its own current syntax table, we should make that -more precise: @code{with-syntax-table} temporarily alters the current -syntax table of whichever buffer is current at the time the macro -execution starts. Other buffers are not affected. -@end defmac - -@node Syntax Properties -@section Syntax Properties -@kindex syntax-table @r{(text property)} - -When the syntax table is not flexible enough to specify the syntax of -a language, you can override the syntax table for specific character -occurrences in the buffer, by applying a @code{syntax-table} text -property. @xref{Text Properties}, for how to apply text properties. - - The valid values of @code{syntax-table} text property are: - -@table @asis -@item @var{syntax-table} -If the property value is a syntax table, that table is used instead of -the current buffer's syntax table to determine the syntax for the -underlying text character. - -@item @code{(@var{syntax-code} . @var{matching-char})} -A cons cell of this format is a raw syntax descriptor (@pxref{Syntax -Table Internals}), which directly specifies a syntax class for the -underlying text character. - -@item @code{nil} -If the property is @code{nil}, the character's syntax is determined from -the current syntax table in the usual way. -@end table - -@defvar parse-sexp-lookup-properties -If this is non-@code{nil}, the syntax scanning functions, like -@code{forward-sexp}, pay attention to syntax text properties. -Otherwise they use only the current syntax table. -@end defvar - -@defvar syntax-propertize-function -This variable, if non-@code{nil}, should store a function for applying -@code{syntax-table} properties to a specified stretch of text. It is -intended to be used by major modes to install a function which applies -@code{syntax-table} properties in some mode-appropriate way. - -The function is called by @code{syntax-ppss} (@pxref{Position Parse}), -and by Font Lock mode during syntactic fontification (@pxref{Syntactic -Font Lock}). It is called with two arguments, @var{start} and -@var{end}, which are the starting and ending positions of the text on -which it should act. It is allowed to call @code{syntax-ppss} on any -position before @var{end}. However, it should not call -@code{syntax-ppss-flush-cache}; so, it is not allowed to call -@code{syntax-ppss} on some position and later modify the buffer at an -earlier position. -@end defvar - -@defvar syntax-propertize-extend-region-functions -This abnormal hook is run by the syntax parsing code prior to calling -@code{syntax-propertize-function}. Its role is to help locate safe -starting and ending buffer positions for passing to -@code{syntax-propertize-function}. For example, a major mode can add -a function to this hook to identify multi-line syntactic constructs, -and ensure that the boundaries do not fall in the middle of one. - -Each function in this hook should accept two arguments, @var{start} -and @var{end}. It should return either a cons cell of two adjusted -buffer positions, @code{(@var{new-start} . @var{new-end})}, or -@code{nil} if no adjustment is necessary. The hook functions are run -in turn, repeatedly, until they all return @code{nil}. -@end defvar - -@node Motion and Syntax -@section Motion and Syntax - - This section describes functions for moving across characters that -have certain syntax classes. - -@defun skip-syntax-forward syntaxes &optional limit -This function moves point forward across characters having syntax -classes mentioned in @var{syntaxes} (a string of syntax class -characters). It stops when it encounters the end of the buffer, or -position @var{limit} (if specified), or a character it is not supposed -to skip. - -If @var{syntaxes} starts with @samp{^}, then the function skips -characters whose syntax is @emph{not} in @var{syntaxes}. - -The return value is the distance traveled, which is a nonnegative -integer. -@end defun - -@defun skip-syntax-backward syntaxes &optional limit -This function moves point backward across characters whose syntax -classes are mentioned in @var{syntaxes}. It stops when it encounters -the beginning of the buffer, or position @var{limit} (if specified), or -a character it is not supposed to skip. - -If @var{syntaxes} starts with @samp{^}, then the function skips -characters whose syntax is @emph{not} in @var{syntaxes}. - -The return value indicates the distance traveled. It is an integer that -is zero or less. -@end defun - -@defun backward-prefix-chars -This function moves point backward over any number of characters with -expression prefix syntax. This includes both characters in the -expression prefix syntax class, and characters with the @samp{p} flag. -@end defun - -@node Parsing Expressions -@section Parsing Expressions - - This section describes functions for parsing and scanning balanced -expressions. We will refer to such expressions as @dfn{sexps}, -following the terminology of Lisp, even though these functions can act -on languages other than Lisp. Basically, a sexp is either a balanced -parenthetical grouping, a string, or a ``symbol'' (i.e., a sequence -of characters whose syntax is either word constituent or symbol -constituent). However, characters in the expression prefix syntax -class (@pxref{Syntax Class Table}) are treated as part of the sexp if -they appear next to it. - - The syntax table controls the interpretation of characters, so these -functions can be used for Lisp expressions when in Lisp mode and for C -expressions when in C mode. @xref{List Motion}, for convenient -higher-level functions for moving over balanced expressions. - - A character's syntax controls how it changes the state of the -parser, rather than describing the state itself. For example, a -string delimiter character toggles the parser state between -``in-string'' and ``in-code'', but the syntax of characters does not -directly say whether they are inside a string. For example (note that -15 is the syntax code for generic string delimiters), - -@example -(put-text-property 1 9 'syntax-table '(15 . nil)) -@end example - -@noindent -does not tell Emacs that the first eight chars of the current buffer -are a string, but rather that they are all string delimiters. As a -result, Emacs treats them as four consecutive empty string constants. - -@menu -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. -@end menu - -@node Motion via Parsing -@subsection Motion Commands Based on Parsing - - This section describes simple point-motion functions that operate -based on parsing expressions. - -@defun scan-lists from count depth -This function scans forward @var{count} balanced parenthetical -groupings from position @var{from}. It returns the position where the -scan stops. If @var{count} is negative, the scan moves backwards. - -If @var{depth} is nonzero, treat the starting position as being -@var{depth} parentheses deep. The scanner moves forward or backward -through the buffer until the depth changes to zero @var{count} times. -Hence, a positive value for @var{depth} has the effect of moving out -@var{depth} levels of parenthesis from the starting position, while a -negative @var{depth} has the effect of moving deeper by @var{-depth} -levels of parenthesis. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of the accessible part of the -buffer before it has scanned over @var{count} parenthetical groupings, -the return value is @code{nil} if the depth at that point is zero; if -the depth is non-zero, a @code{scan-error} error is signaled. -@end defun - -@defun scan-sexps from count -This function scans forward @var{count} sexps from position @var{from}. -It returns the position where the scan stops. If @var{count} is -negative, the scan moves backwards. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of (the accessible part of) the -buffer while in the middle of a parenthetical grouping, an error is -signaled. If it reaches the beginning or end between groupings but -before count is used up, @code{nil} is returned. -@end defun - -@defun forward-comment count -This function moves point forward across @var{count} complete comments - (that is, including the starting delimiter and the terminating -delimiter if any), plus any whitespace encountered on the way. It -moves backward if @var{count} is negative. If it encounters anything -other than a comment or whitespace, it stops, leaving point at the -place where it stopped. This includes (for instance) finding the end -of a comment when moving forward and expecting the beginning of one. -The function also stops immediately after moving over the specified -number of complete comments. If @var{count} comments are found as -expected, with nothing except whitespace between them, it returns -@code{t}; otherwise it returns @code{nil}. - -This function cannot tell whether the ``comments'' it traverses are -embedded within a string. If they look like comments, it treats them -as comments. - -To move forward over all comments and whitespace following point, use -@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a -good argument to use, because the number of comments in the buffer -cannot exceed that many. -@end defun - -@node Position Parse -@subsection Finding the Parse State for a Position - - For syntactic analysis, such as in indentation, often the useful -thing is to compute the syntactic state corresponding to a given buffer -position. This function does that conveniently. - -@defun syntax-ppss &optional pos -This function returns the parser state that the parser would reach at -position @var{pos} starting from the beginning of the buffer. -@iftex -See the next section for -@end iftex -@ifnottex -@xref{Parser State}, -@end ifnottex -for a description of the parser state. - -The return value is the same as if you call the low-level parsing -function @code{parse-partial-sexp} to parse from the beginning of the -buffer to @var{pos} (@pxref{Low-Level Parsing}). However, -@code{syntax-ppss} uses a cache to speed up the computation. Due to -this optimization, the second value (previous complete subexpression) -and sixth value (minimum parenthesis depth) in the returned parser -state are not meaningful. - -This function has a side effect: it adds a buffer-local entry to -@code{before-change-functions} (@pxref{Change Hooks}) for -@code{syntax-ppss-flush-cache} (see below). This entry keeps the -cache consistent as the buffer is modified. However, the cache might -not be updated if @code{syntax-ppss} is called while -@code{before-change-functions} is temporarily let-bound, or if the -buffer is modified without running the hook, such as when using -@code{inhibit-modification-hooks}. In those cases, it is necessary to -call @code{syntax-ppss-flush-cache} explicitly. -@end defun - -@defun syntax-ppss-flush-cache beg &rest ignored-args -This function flushes the cache used by @code{syntax-ppss}, starting -at position @var{beg}. The remaining arguments, @var{ignored-args}, -are ignored; this function accepts them so that it can be directly -used on hooks such as @code{before-change-functions} (@pxref{Change -Hooks}). -@end defun - - Major modes can make @code{syntax-ppss} run faster by specifying -where it needs to start parsing. - -@defvar syntax-begin-function -If this is non-@code{nil}, it should be a function that moves to an -earlier buffer position where the parser state is equivalent to -@code{nil}---in other words, a position outside of any comment, -string, or parenthesis. @code{syntax-ppss} uses it to further -optimize its computations, when the cache gives no help. -@end defvar - -@node Parser State -@subsection Parser State -@cindex parser state - - A @dfn{parser state} is a list of ten elements describing the state -of the syntactic parser, after it parses the text between a specified -starting point and a specified end point in the buffer. Parsing -functions such as @code{syntax-ppss} -@ifnottex -(@pxref{Position Parse}) -@end ifnottex -return a parser state as the value. Some parsing functions accept a -parser state as an argument, for resuming parsing. - - Here are the meanings of the elements of the parser state: - -@enumerate 0 -@item -The depth in parentheses, counting from 0. @strong{Warning:} this can -be negative if there are more close parens than open parens between -the parser's starting point and end point. - -@item -@cindex innermost containing parentheses -The character position of the start of the innermost parenthetical -grouping containing the stopping point; @code{nil} if none. - -@item -@cindex previous complete subexpression -The character position of the start of the last complete subexpression -terminated; @code{nil} if none. - -@item -@cindex inside string -Non-@code{nil} if inside a string. More precisely, this is the -character that will terminate the string, or @code{t} if a generic -string delimiter character should terminate it. - -@item -@cindex inside comment -@code{t} if inside a non-nestable comment (of any comment style; -@pxref{Syntax Flags}); or the comment nesting level if inside a -comment that can be nested. - -@item -@cindex quote character -@code{t} if the end point is just after a quote character. - -@item -The minimum parenthesis depth encountered during this scan. - -@item -What kind of comment is active: @code{nil} if not in a comment or in a -comment of style @samp{a}; 1 for a comment of style @samp{b}; 2 for a -comment of style @samp{c}; and @code{syntax-table} for a comment that -should be ended by a generic comment delimiter character. - -@item -The string or comment start position. While inside a comment, this is -the position where the comment began; while inside a string, this is the -position where the string began. When outside of strings and comments, -this element is @code{nil}. - -@item -Internal data for continuing the parsing. The meaning of this -data is subject to change; it is used if you pass this list -as the @var{state} argument to another call. -@end enumerate - - Elements 1, 2, and 6 are ignored in a state which you pass as an -argument to continue parsing, and elements 8 and 9 are used only in -trivial cases. Those elements are mainly used internally by the -parser code. - - One additional piece of useful information is available from a -parser state using this function: - -@defun syntax-ppss-toplevel-pos state -This function extracts, from parser state @var{state}, the last -position scanned in the parse which was at top level in grammatical -structure. ``At top level'' means outside of any parentheses, -comments, or strings. - -The value is @code{nil} if @var{state} represents a parse which has -arrived at a top level position. -@end defun - -@node Low-Level Parsing -@subsection Low-Level Parsing - - The most basic way to use the expression parser is to tell it -to start at a given position with a certain state, and parse up to -a specified end position. - -@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment -This function parses a sexp in the current buffer starting at -@var{start}, not scanning past @var{limit}. It stops at position -@var{limit} or when certain criteria described below are met, and sets -point to the location where parsing stops. It returns a parser state -@ifinfo -(@pxref{Parser State}) -@end ifinfo -describing the status of the parse at the point where it stops. - -@cindex parenthesis depth -If the third argument @var{target-depth} is non-@code{nil}, parsing -stops if the depth in parentheses becomes equal to @var{target-depth}. -The depth starts at 0, or at whatever is given in @var{state}. - -If the fourth argument @var{stop-before} is non-@code{nil}, parsing -stops when it comes to any character that starts a sexp. If -@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the -start of a comment. If @var{stop-comment} is the symbol -@code{syntax-table}, parsing stops after the start of a comment or a -string, or the end of a comment or a string, whichever comes first. - -If @var{state} is @code{nil}, @var{start} is assumed to be at the top -level of parenthesis structure, such as the beginning of a function -definition. Alternatively, you might wish to resume parsing in the -middle of the structure. To do this, you must provide a @var{state} -argument that describes the initial status of parsing. The value -returned by a previous call to @code{parse-partial-sexp} will do -nicely. -@end defun - -@node Control Parsing -@subsection Parameters to Control Parsing - -@defvar multibyte-syntax-as-symbol -If this variable is non-@code{nil}, @code{scan-sexps} treats all -non-@acronym{ASCII} characters as symbol constituents regardless -of what the syntax table says about them. (However, text properties -can still override the syntax.) -@end defvar - -@defopt parse-sexp-ignore-comments -@cindex skipping comments -If the value is non-@code{nil}, then comments are treated as -whitespace by the functions in this section and by @code{forward-sexp}, -@code{scan-lists} and @code{scan-sexps}. -@end defopt - -@vindex parse-sexp-lookup-properties -The behavior of @code{parse-partial-sexp} is also affected by -@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}). - -You can use @code{forward-comment} to move forward or backward over -one comment or several comments. - -@node Syntax Table Internals -@section Syntax Table Internals -@cindex syntax table internals - - Syntax tables are implemented as char-tables (@pxref{Char-Tables}), -but most Lisp programs don't work directly with their elements. -Syntax tables do not store syntax data as syntax descriptors -(@pxref{Syntax Descriptors}); they use an internal format, which is -documented in this section. This internal format can also be assigned -as syntax properties (@pxref{Syntax Properties}). - -@cindex syntax code -@cindex raw syntax descriptor - Each entry in a syntax table is a @dfn{raw syntax descriptor}: a -cons cell of the form @code{(@var{syntax-code} -. @var{matching-char})}. @var{syntax-code} is an integer which -encodes the syntax class and syntax flags, according to the table -below. @var{matching-char}, if non-@code{nil}, specifies a matching -character (similar to the second character in a syntax descriptor). - - Here are the syntax codes corresponding to the various syntax -classes: - -@multitable @columnfractions .2 .3 .2 .3 -@item -@i{Code} @tab @i{Class} @tab @i{Code} @tab @i{Class} -@item -0 @tab whitespace @tab 8 @tab paired delimiter -@item -1 @tab punctuation @tab 9 @tab escape -@item -2 @tab word @tab 10 @tab character quote -@item -3 @tab symbol @tab 11 @tab comment-start -@item -4 @tab open parenthesis @tab 12 @tab comment-end -@item -5 @tab close parenthesis @tab 13 @tab inherit -@item -6 @tab expression prefix @tab 14 @tab generic comment -@item -7 @tab string quote @tab 15 @tab generic string -@end multitable - -@noindent -For example, in the standard syntax table, the entry for @samp{(} is -@code{(4 . 41)}. 41 is the character code for @samp{)}. - - Syntax flags are encoded in higher order bits, starting 16 bits from -the least significant bit. This table gives the power of two which -corresponds to each syntax flag. - -@multitable @columnfractions .15 .3 .15 .3 -@item -@i{Prefix} @tab @i{Flag} @tab @i{Prefix} @tab @i{Flag} -@item -@samp{1} @tab @code{(lsh 1 16)} @tab @samp{p} @tab @code{(lsh 1 20)} -@item -@samp{2} @tab @code{(lsh 1 17)} @tab @samp{b} @tab @code{(lsh 1 21)} -@item -@samp{3} @tab @code{(lsh 1 18)} @tab @samp{n} @tab @code{(lsh 1 22)} -@item -@samp{4} @tab @code{(lsh 1 19)} -@end multitable - -@defun string-to-syntax desc -Given a syntax descriptor @var{desc} (a string), this function returns -the corresponding raw syntax descriptor. -@end defun - -@defun syntax-after pos -This function returns the raw syntax descriptor for the character in -the buffer after position @var{pos}, taking account of syntax -properties as well as the syntax table. If @var{pos} is outside the -buffer's accessible portion (@pxref{Narrowing, accessible portion}), -the return value is @code{nil}. -@end defun - -@defun syntax-class syntax -This function returns the syntax code for the raw syntax descriptor -@var{syntax}. More precisely, it takes the raw syntax descriptor's -@var{syntax-code} component, masks off the high 16 bits which record -the syntax flags, and returns the resulting integer. - -If @var{syntax} is @code{nil}, the return value is returns @code{nil}. -This is so that the expression - -@example -(syntax-class (syntax-after pos)) -@end example - -@noindent -evaluates to @code{nil} if @code{pos} is outside the buffer's -accessible portion, without throwing errors or returning an incorrect -code. -@end defun - -@node Categories -@section Categories -@cindex categories of characters -@cindex character categories - - @dfn{Categories} provide an alternate way of classifying characters -syntactically. You can define several categories as needed, then -independently assign each character to one or more categories. Unlike -syntax classes, categories are not mutually exclusive; it is normal for -one character to belong to several categories. - -@cindex category table - Each buffer has a @dfn{category table} which records which categories -are defined and also which characters belong to each category. Each -category table defines its own categories, but normally these are -initialized by copying from the standard categories table, so that the -standard categories are available in all modes. - - Each category has a name, which is an @acronym{ASCII} printing character in -the range @w{@samp{ }} to @samp{~}. You specify the name of a category -when you define it with @code{define-category}. - -@cindex category set - The category table is actually a char-table (@pxref{Char-Tables}). -The element of the category table at index @var{c} is a @dfn{category -set}---a bool-vector---that indicates which categories character @var{c} -belongs to. In this category set, if the element at index @var{cat} is -@code{t}, that means category @var{cat} is a member of the set, and that -character @var{c} belongs to category @var{cat}. - -For the next three functions, the optional argument @var{table} -defaults to the current buffer's category table. - -@defun define-category char docstring &optional table -This function defines a new category, with name @var{char} and -documentation @var{docstring}, for the category table @var{table}. - -Here's an example of defining a new category for characters that have -strong right-to-left directionality (@pxref{Bidirectional Display}) -and using it in a special category table: - -@example -(defvar special-category-table-for-bidi - (let ((category-table (make-category-table)) - (uniprop-table (unicode-property-table-internal 'bidi-class))) - (define-category ?R "Characters of bidi-class R, AL, or RLO" - category-table) - (map-char-table - #'(lambda (key val) - (if (memq val '(R AL RLO)) - (modify-category-entry key ?R category-table))) - uniprop-table) - category-table)) -@end example -@end defun - -@defun category-docstring category &optional table -This function returns the documentation string of category @var{category} -in category table @var{table}. - -@example -(category-docstring ?a) - @result{} "ASCII" -(category-docstring ?l) - @result{} "Latin" -@end example -@end defun - -@defun get-unused-category &optional table -This function returns a category name (a character) which is not -currently defined in @var{table}. If all possible categories are in use -in @var{table}, it returns @code{nil}. -@end defun - -@defun category-table -This function returns the current buffer's category table. -@end defun - -@defun category-table-p object -This function returns @code{t} if @var{object} is a category table, -otherwise @code{nil}. -@end defun - -@defun standard-category-table -This function returns the standard category table. -@end defun - -@defun copy-category-table &optional table -This function constructs a copy of @var{table} and returns it. If -@var{table} is not supplied (or is @code{nil}), it returns a copy of the -standard category table. Otherwise, an error is signaled if @var{table} -is not a category table. -@end defun - -@defun set-category-table table -This function makes @var{table} the category table for the current -buffer. It returns @var{table}. -@end defun - -@defun make-category-table -This creates and returns an empty category table. In an empty category -table, no categories have been allocated, and no characters belong to -any categories. -@end defun - -@defun make-category-set categories -This function returns a new category set---a bool-vector---whose initial -contents are the categories listed in the string @var{categories}. The -elements of @var{categories} should be category names; the new category -set has @code{t} for each of those categories, and @code{nil} for all -other categories. - -@example -(make-category-set "al") - @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -@end example -@end defun - -@defun char-category-set char -This function returns the category set for character @var{char} in the -current buffer's category table. This is the bool-vector which -records which categories the character @var{char} belongs to. The -function @code{char-category-set} does not allocate storage, because -it returns the same bool-vector that exists in the category table. - -@example -(char-category-set ?a) - @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -@end example -@end defun - -@defun category-set-mnemonics category-set -This function converts the category set @var{category-set} into a string -containing the characters that designate the categories that are members -of the set. - -@example -(category-set-mnemonics (char-category-set ?a)) - @result{} "al" -@end example -@end defun - -@defun modify-category-entry char category &optional table reset -This function modifies the category set of @var{char} in category -table @var{table} (which defaults to the current buffer's category -table). @var{char} can be a character, or a cons cell of the form -@code{(@var{min} . @var{max})}; in the latter case, the function -modifies the category sets of all characters in the range between -@var{min} and @var{max}, inclusive. - -Normally, it modifies a category set by adding @var{category} to it. -But if @var{reset} is non-@code{nil}, then it deletes @var{category} -instead. -@end defun - -@deffn Command describe-categories &optional buffer-or-name -This function describes the category specifications in the current -category table. It inserts the descriptions in a buffer, and then -displays that buffer. If @var{buffer-or-name} is non-@code{nil}, it -describes the category table of that buffer instead. -@end deffn diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi deleted file mode 100644 index 6665cc3e673..00000000000 --- a/doc/lispref/text.texi +++ /dev/null @@ -1,4539 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Text -@chapter Text -@cindex text - - This chapter describes the functions that deal with the text in a -buffer. Most examine, insert, or delete text in the current buffer, -often operating at point or on text adjacent to point. Many are -interactive. All the functions that change the text provide for undoing -the changes (@pxref{Undo}). - - Many text-related functions operate on a region of text defined by two -buffer positions passed in arguments named @var{start} and @var{end}. -These arguments should be either markers (@pxref{Markers}) or numeric -character positions (@pxref{Positions}). The order of these arguments -does not matter; it is all right for @var{start} to be the end of the -region and @var{end} the beginning. For example, @code{(delete-region 1 -10)} and @code{(delete-region 10 1)} are equivalent. An -@code{args-out-of-range} error is signaled if either @var{start} or -@var{end} is outside the accessible portion of the buffer. In an -interactive call, point and the mark are used for these arguments. - -@cindex buffer contents - Throughout this chapter, ``text'' refers to the characters in the -buffer, together with their properties (when relevant). Keep in mind -that point is always between two characters, and the cursor appears on -the character after point. - -@menu -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Registers:: How registers are implemented. Accessing the text or - position stored in a register. -* Transposition:: Swapping two portions of a buffer. -* Decompression:: Dealing with compressed data. -* Base 64:: Conversion to or from base 64 encoding. -* Checksum/Hash:: Computing cryptographic hashes. -* Parsing HTML/XML:: Parsing HTML and XML. -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. -@end menu - -@node Near Point -@section Examining Text Near Point -@cindex text near point - - Many functions are provided to look at the characters around point. -Several simple functions are described here. See also @code{looking-at} -in @ref{Regexp Search}. - -In the following four functions, ``beginning'' or ``end'' of buffer -refers to the beginning or end of the accessible portion. - -@defun char-after &optional position -This function returns the character in the current buffer at (i.e., -immediately after) position @var{position}. If @var{position} is out of -range for this purpose, either before the beginning of the buffer, or at -or beyond the end, then the value is @code{nil}. The default for -@var{position} is point. - -In the following example, assume that the first character in the -buffer is @samp{@@}: - -@example -@group -(string (char-after 1)) - @result{} "@@" -@end group -@end example -@end defun - -@defun char-before &optional position -This function returns the character in the current buffer immediately -before position @var{position}. If @var{position} is out of range for -this purpose, either at or before the beginning of the buffer, or beyond -the end, then the value is @code{nil}. The default for -@var{position} is point. -@end defun - -@defun following-char -This function returns the character following point in the current -buffer. This is similar to @code{(char-after (point))}. However, if -point is at the end of the buffer, then @code{following-char} returns 0. - -Remember that point is always between characters, and the cursor -normally appears over the character following point. Therefore, the -character returned by @code{following-char} is the character the -cursor is over. - -In this example, point is between the @samp{a} and the @samp{c}. - -@example -@group ----------- Buffer: foo ---------- -Gentlemen may cry ``Pea@point{}ce! Peace!,'' -but there is no peace. ----------- Buffer: foo ---------- -@end group - -@group -(string (preceding-char)) - @result{} "a" -(string (following-char)) - @result{} "c" -@end group -@end example -@end defun - -@defun preceding-char -This function returns the character preceding point in the current -buffer. See above, under @code{following-char}, for an example. If -point is at the beginning of the buffer, @code{preceding-char} returns -0. -@end defun - -@defun bobp -This function returns @code{t} if point is at the beginning of the -buffer. If narrowing is in effect, this means the beginning of the -accessible portion of the text. See also @code{point-min} in -@ref{Point}. -@end defun - -@defun eobp -This function returns @code{t} if point is at the end of the buffer. -If narrowing is in effect, this means the end of accessible portion of -the text. See also @code{point-max} in @xref{Point}. -@end defun - -@defun bolp -This function returns @code{t} if point is at the beginning of a line. -@xref{Text Lines}. The beginning of the buffer (or of its accessible -portion) always counts as the beginning of a line. -@end defun - -@defun eolp -This function returns @code{t} if point is at the end of a line. The -end of the buffer (or of its accessible portion) is always considered -the end of a line. -@end defun - -@node Buffer Contents -@section Examining Buffer Contents - - This section describes functions that allow a Lisp program to -convert any portion of the text in the buffer into a string. - -@defun buffer-substring start end -This function returns a string containing a copy of the text of the -region defined by positions @var{start} and @var{end} in the current -buffer. If the arguments are not positions in the accessible portion -of the buffer, @code{buffer-substring} signals an -@code{args-out-of-range} error. - -Here's an example which assumes Font-Lock mode is not enabled: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of buffer foo - ----------- Buffer: foo ---------- -@end group - -@group -(buffer-substring 1 10) - @result{} "This is t" -@end group -@group -(buffer-substring (point-max) 10) - @result{} "he contents of buffer foo\n" -@end group -@end example - -If the text being copied has any text properties, these are copied into -the string along with the characters they belong to. @xref{Text -Properties}. However, overlays (@pxref{Overlays}) in the buffer and -their properties are ignored, not copied. - -For example, if Font-Lock mode is enabled, you might get results like -these: - -@example -@group -(buffer-substring 1 10) - @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t)) -@end group -@end example -@end defun - -@defun buffer-substring-no-properties start end -This is like @code{buffer-substring}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -@end defun - -@defun buffer-string -This function returns the contents of the entire accessible portion of -the current buffer, as a string. -@end defun - -@defun filter-buffer-substring start end &optional delete -This function filters the buffer text between @var{start} and @var{end} -using a function specified by the variable -@code{filter-buffer-substring-function}, and returns the result. - -The default filter function consults the obsolete wrapper hook -@code{filter-buffer-substring-functions}, and the obsolete variable -@code{buffer-substring-filters}. If both of these are @code{nil}, it -returns the unaltered text from the buffer, i.e., what -@code{buffer-substring} would return. - -If @var{delete} is non-@code{nil}, the function deletes the text -between @var{start} and @var{end} after copying it, like -@code{delete-and-extract-region}. - -Lisp code should use this function instead of @code{buffer-substring}, -@code{buffer-substring-no-properties}, -or @code{delete-and-extract-region} when copying into user-accessible -data structures such as the kill-ring, X clipboard, and registers. -Major and minor modes can modify @code{filter-buffer-substring-function} -to alter such text as it is copied out of the buffer. -@end defun - -@defvar filter-buffer-substring-function -The value of this variable is a function that @code{filter-buffer-substring} -will call to do the actual work. The function receives three -arguments, the same as those of @code{filter-buffer-substring}, -which it should treat as per the documentation of that function. It -should return the filtered text (and optionally delete the source text). -@end defvar - -@noindent The following two variables are obsoleted by -@code{filter-buffer-substring-function}, but are still supported for -backward compatibility. - -@defvar filter-buffer-substring-functions -This obsolete variable is a wrapper hook, whose members should be functions -that accept four arguments: @var{fun}, @var{start}, @var{end}, and -@var{delete}. @var{fun} is a function that takes three arguments -(@var{start}, @var{end}, and @var{delete}), and returns a string. In -both cases, the @var{start}, @var{end}, and @var{delete} arguments are -the same as those of @code{filter-buffer-substring}. - -The first hook function is passed a @var{fun} that is equivalent to -the default operation of @code{filter-buffer-substring}, i.e., it -returns the buffer-substring between @var{start} and @var{end} -(processed by any @code{buffer-substring-filters}) and optionally -deletes the original text from the buffer. In most cases, the hook -function will call @var{fun} once, and then do its own processing of -the result. The next hook function receives a @var{fun} equivalent to -this, and so on. The actual return value is the result of all the -hook functions acting in sequence. -@end defvar - -@defvar buffer-substring-filters -The value of this obsolete variable should be a list of functions -that accept a single string argument and return another string. -The default @code{filter-buffer-substring} function passes the buffer -substring to the first function in this list, and the return value of -each function is passed to the next function. The return value of the -last function is passed to @code{filter-buffer-substring-functions}. -@end defvar - -@defun current-word &optional strict really-word -This function returns the symbol (or word) at or near point, as a -string. The return value includes no text properties. - -If the optional argument @var{really-word} is non-@code{nil}, it finds a -word; otherwise, it finds a symbol (which includes both word -characters and symbol constituent characters). - -If the optional argument @var{strict} is non-@code{nil}, then point -must be in or next to the symbol or word---if no symbol or word is -there, the function returns @code{nil}. Otherwise, a nearby symbol or -word on the same line is acceptable. -@end defun - -@defun thing-at-point thing -Return the @var{thing} around or next to point, as a string. - -The argument @var{thing} is a symbol which specifies a kind of syntactic -entity. Possibilities include @code{symbol}, @code{list}, @code{sexp}, -@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence}, -@code{whitespace}, @code{line}, @code{page}, and others. - -@example ----------- Buffer: foo ---------- -Gentlemen may cry ``Pea@point{}ce! Peace!,'' -but there is no peace. ----------- Buffer: foo ---------- - -(thing-at-point 'word) - @result{} "Peace" -(thing-at-point 'line) - @result{} "Gentlemen may cry ``Peace! Peace!,''\n" -(thing-at-point 'whitespace) - @result{} nil -@end example -@end defun - -@node Comparing Text -@section Comparing Text -@cindex comparing buffer text - - This function lets you compare portions of the text in a buffer, without -copying them into strings first. - -@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 -This function lets you compare two substrings of the same buffer or two -different buffers. The first three arguments specify one substring, -giving a buffer (or a buffer name) and two positions within the -buffer. The last three arguments specify the other substring in the -same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or -both to stand for the current buffer. - -The value is negative if the first substring is less, positive if the -first is greater, and zero if they are equal. The absolute value of -the result is one plus the index of the first differing characters -within the substrings. - -This function ignores case when comparing characters -if @code{case-fold-search} is non-@code{nil}. It always ignores -text properties. - -Suppose the current buffer contains the text @samp{foobarbar -haha!rara!}; then in this example the two substrings are @samp{rbar } -and @samp{rara!}. The value is 2 because the first substring is greater -at the second character. - -@example -(compare-buffer-substrings nil 6 11 nil 16 21) - @result{} 2 -@end example -@end defun - -@node Insertion -@section Inserting Text -@cindex insertion of text -@cindex text insertion - -@cindex insertion before point -@cindex before point, insertion - @dfn{Insertion} means adding new text to a buffer. The inserted text -goes at point---between the character before point and the character -after point. Some insertion functions leave point before the inserted -text, while other functions leave it after. We call the former -insertion @dfn{after point} and the latter insertion @dfn{before point}. - - Insertion moves markers located at positions after the insertion -point, so that they stay with the surrounding text (@pxref{Markers}). -When a marker points at the place of insertion, insertion may or may -not relocate the marker, depending on the marker's insertion type -(@pxref{Marker Insertion Types}). Certain special functions such as -@code{insert-before-markers} relocate all such markers to point after -the inserted text, regardless of the markers' insertion type. - - Insertion functions signal an error if the current buffer is -read-only (@pxref{Read Only Buffers}) or if they insert within -read-only text (@pxref{Special Properties}). - - These functions copy text characters from strings and buffers along -with their properties. The inserted characters have exactly the same -properties as the characters they were copied from. By contrast, -characters specified as separate arguments, not part of a string or -buffer, inherit their text properties from the neighboring text. - - The insertion functions convert text from unibyte to multibyte in -order to insert in a multibyte buffer, and vice versa---if the text -comes from a string or from a buffer. However, they do not convert -unibyte character codes 128 through 255 to multibyte characters, not -even if the current buffer is a multibyte buffer. @xref{Converting -Representations}. - -@defun insert &rest args -This function inserts the strings and/or characters @var{args} into the -current buffer, at point, moving point forward. In other words, it -inserts the text before point. An error is signaled unless all -@var{args} are either strings or characters. The value is @code{nil}. -@end defun - -@defun insert-before-markers &rest args -This function inserts the strings and/or characters @var{args} into the -current buffer, at point, moving point forward. An error is signaled -unless all @var{args} are either strings or characters. The value is -@code{nil}. - -This function is unlike the other insertion functions in that it -relocates markers initially pointing at the insertion point, to point -after the inserted text. If an overlay begins at the insertion point, -the inserted text falls outside the overlay; if a nonempty overlay -ends at the insertion point, the inserted text falls inside that -overlay. -@end defun - -@deffn Command insert-char character &optional count inherit -This command inserts @var{count} instances of @var{character} into the -current buffer before point. The argument @var{count} must be an -integer, and @var{character} must be a character. - -If called interactively, this command prompts for @var{character} -using its Unicode name or its code point. @xref{Inserting Text,,, -emacs, The GNU Emacs Manual}. - -This function does not convert unibyte character codes 128 through 255 -to multibyte characters, not even if the current buffer is a multibyte -buffer. @xref{Converting Representations}. - -If @var{inherit} is non-@code{nil}, the inserted characters inherit -sticky text properties from the two characters before and after the -insertion point. @xref{Sticky Properties}. -@end deffn - -@defun insert-buffer-substring from-buffer-or-name &optional start end -This function inserts a portion of buffer @var{from-buffer-or-name} -into the current buffer before point. The text inserted is the region -between @var{start} (inclusive) and @var{end} (exclusive). (These -arguments default to the beginning and end of the accessible portion -of that buffer.) This function returns @code{nil}. - -In this example, the form is executed with buffer @samp{bar} as the -current buffer. We assume that buffer @samp{bar} is initially empty. - -@example -@group ----------- Buffer: foo ---------- -We hold these truths to be self-evident, that all ----------- Buffer: foo ---------- -@end group - -@group -(insert-buffer-substring "foo" 1 20) - @result{} nil - ----------- Buffer: bar ---------- -We hold these truth@point{} ----------- Buffer: bar ---------- -@end group -@end example -@end defun - -@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end -This is like @code{insert-buffer-substring} except that it does not -copy any text properties. -@end defun - - @xref{Sticky Properties}, for other insertion functions that inherit -text properties from the nearby text in addition to inserting it. -Whitespace inserted by indentation functions also inherits text -properties. - -@node Commands for Insertion -@section User-Level Insertion Commands - - This section describes higher-level commands for inserting text, -commands intended primarily for the user but useful also in Lisp -programs. - -@deffn Command insert-buffer from-buffer-or-name -This command inserts the entire accessible contents of -@var{from-buffer-or-name} (which must exist) into the current buffer -after point. It leaves the mark after the inserted text. The value -is @code{nil}. -@end deffn - -@deffn Command self-insert-command count -@cindex character insertion -@cindex self-insertion -This command inserts the last character typed; it does so @var{count} -times, before point, and returns @code{nil}. Most printing characters -are bound to this command. In routine use, @code{self-insert-command} -is the most frequently called function in Emacs, but programs rarely use -it except to install it on a keymap. - -In an interactive call, @var{count} is the numeric prefix argument. - -@c FIXME: This variable is obsolete since 23.1. -Self-insertion translates the input character through -@code{translation-table-for-input}. @xref{Translation of Characters}. - -This command calls @code{auto-fill-function} whenever that is -non-@code{nil} and the character inserted is in the table -@code{auto-fill-chars} (@pxref{Auto Filling}). - -@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 -This command performs abbrev expansion if Abbrev mode is enabled and -the inserted character does not have word-constituent -syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also -responsible for calling @code{blink-paren-function} when the inserted -character has close parenthesis syntax (@pxref{Blinking}). - -@vindex post-self-insert-hook -The final thing this command does is to run the hook -@code{post-self-insert-hook}. You could use this to automatically -reindent text as it is typed, for example. - -Do not try substituting your own definition of -@code{self-insert-command} for the standard one. The editor command -loop handles this function specially. -@end deffn - -@deffn Command newline &optional number-of-newlines -This command inserts newlines into the current buffer before point. -If @var{number-of-newlines} is supplied, that many newline characters -are inserted. - -@cindex newline and Auto Fill mode -This function calls @code{auto-fill-function} if the current column -number is greater than the value of @code{fill-column} and -@var{number-of-newlines} is @code{nil}. Typically what -@code{auto-fill-function} does is insert a newline; thus, the overall -result in this case is to insert two newlines at different places: one -at point, and another earlier in the line. @code{newline} does not -auto-fill if @var{number-of-newlines} is non-@code{nil}. - -This command indents to the left margin if that is not zero. -@xref{Margins}. - -The value returned is @code{nil}. In an interactive call, @var{count} -is the numeric prefix argument. -@end deffn - -@defvar overwrite-mode -This variable controls whether overwrite mode is in effect. The value -should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, -or @code{nil}. @code{overwrite-mode-textual} specifies textual -overwrite mode (treats newlines and tabs specially), and -@code{overwrite-mode-binary} specifies binary overwrite mode (treats -newlines and tabs like any other characters). -@end defvar - -@node Deletion -@section Deleting Text -@cindex text deletion - -@cindex deleting text vs killing - Deletion means removing part of the text in a buffer, without saving -it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be -yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). -Some deletion functions do save text in the kill ring in some special -cases. - - All of the deletion functions operate on the current buffer. - -@deffn Command erase-buffer -This function deletes the entire text of the current buffer -(@emph{not} just the accessible portion), leaving it -empty. If the buffer is read-only, it signals a @code{buffer-read-only} -error; if some of the text in it is read-only, it signals a -@code{text-read-only} error. Otherwise, it deletes the text without -asking for any confirmation. It returns @code{nil}. - -Normally, deleting a large amount of text from a buffer inhibits further -auto-saving of that buffer ``because it has shrunk''. However, -@code{erase-buffer} does not do this, the idea being that the future -text is not really related to the former text, and its size should not -be compared with that of the former text. -@end deffn - -@deffn Command delete-region start end -This command deletes the text between positions @var{start} and -@var{end} in the current buffer, and returns @code{nil}. If point was -inside the deleted region, its value afterward is @var{start}. -Otherwise, point relocates with the surrounding text, as markers do. -@end deffn - -@defun delete-and-extract-region start end -This function deletes the text between positions @var{start} and -@var{end} in the current buffer, and returns a string containing the -text just deleted. - -If point was inside the deleted region, its value afterward is -@var{start}. Otherwise, point relocates with the surrounding text, as -markers do. -@end defun - -@deffn Command delete-char count &optional killp -This command deletes @var{count} characters directly after point, or -before point if @var{count} is negative. If @var{killp} is -non-@code{nil}, then it saves the deleted characters in the kill ring. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@deffn Command delete-backward-char count &optional killp -@cindex deleting previous char -This command deletes @var{count} characters directly before point, or -after point if @var{count} is negative. If @var{killp} is -non-@code{nil}, then it saves the deleted characters in the kill ring. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@deffn Command backward-delete-char-untabify count &optional killp -@cindex tab deletion -This command deletes @var{count} characters backward, changing tabs -into spaces. When the next character to be deleted is a tab, it is -first replaced with the proper number of spaces to preserve alignment -and then one of those spaces is deleted instead of the tab. If -@var{killp} is non-@code{nil}, then the command saves the deleted -characters in the kill ring. - -Conversion of tabs to spaces happens only if @var{count} is positive. -If it is negative, exactly @minus{}@var{count} characters after point -are deleted. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@defopt backward-delete-char-untabify-method -This option specifies how @code{backward-delete-char-untabify} should -deal with whitespace. Possible values include @code{untabify}, the -default, meaning convert a tab to many spaces and delete one; -@code{hungry}, meaning delete all tabs and spaces before point with -one command; @code{all} meaning delete all tabs, spaces and newlines -before point, and @code{nil}, meaning do nothing special for -whitespace characters. -@end defopt - -@node User-Level Deletion -@section User-Level Deletion Commands - - This section describes higher-level commands for deleting text, -commands intended primarily for the user but useful also in Lisp -programs. - -@deffn Command delete-horizontal-space &optional backward-only -@cindex deleting whitespace -This function deletes all spaces and tabs around point. It returns -@code{nil}. - -If @var{backward-only} is non-@code{nil}, the function deletes -spaces and tabs before point, but not after point. - -In the following examples, we call @code{delete-horizontal-space} four -times, once on each line, with point between the second and third -characters on the line each time. - -@example -@group ----------- Buffer: foo ---------- -I @point{}thought -I @point{} thought -We@point{} thought -Yo@point{}u thought ----------- Buffer: foo ---------- -@end group - -@group -(delete-horizontal-space) ; @r{Four times.} - @result{} nil - ----------- Buffer: foo ---------- -Ithought -Ithought -Wethought -You thought ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command delete-indentation &optional join-following-p -This function joins the line point is on to the previous line, deleting -any whitespace at the join and in some cases replacing it with one -space. If @var{join-following-p} is non-@code{nil}, -@code{delete-indentation} joins this line to the following line -instead. The function returns @code{nil}. - -If there is a fill prefix, and the second of the lines being joined -starts with the prefix, then @code{delete-indentation} deletes the -fill prefix before joining the lines. @xref{Margins}. - -In the example below, point is located on the line starting -@samp{events}, and it makes no difference if there are trailing spaces -in the preceding line. - -@smallexample -@group ----------- Buffer: foo ---------- -When in the course of human -@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group - -(delete-indentation) - @result{} nil - -@group ----------- Buffer: foo ---------- -When in the course of human@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group -@end smallexample - -After the lines are joined, the function @code{fixup-whitespace} is -responsible for deciding whether to leave a space at the junction. -@end deffn - -@deffn Command fixup-whitespace -This function replaces all the horizontal whitespace surrounding point -with either one space or no space, according to the context. It -returns @code{nil}. - -At the beginning or end of a line, the appropriate amount of space is -none. Before a character with close parenthesis syntax, or after a -character with open parenthesis or expression-prefix syntax, no space is -also appropriate. Otherwise, one space is appropriate. @xref{Syntax -Class Table}. - -In the example below, @code{fixup-whitespace} is called the first time -with point before the word @samp{spaces} in the first line. For the -second invocation, point is directly after the @samp{(}. - -@smallexample -@group ----------- Buffer: foo ---------- -This has too many @point{}spaces -This has too many spaces at the start of (@point{} this list) ----------- Buffer: foo ---------- -@end group - -@group -(fixup-whitespace) - @result{} nil -(fixup-whitespace) - @result{} nil -@end group - -@group ----------- Buffer: foo ---------- -This has too many spaces -This has too many spaces at the start of (this list) ----------- Buffer: foo ---------- -@end group -@end smallexample -@end deffn - -@deffn Command just-one-space &optional n -@comment !!SourceFile simple.el -This command replaces any spaces and tabs around point with a single -space, or @var{n} spaces if @var{n} is specified. It returns -@code{nil}. -@end deffn - -@c There is also cycle-spacing, but I cannot see it being useful in -@c Lisp programs, so it is not mentioned here. - -@deffn Command delete-blank-lines -This function deletes blank lines surrounding point. If point is on a -blank line with one or more blank lines before or after it, then all but -one of them are deleted. If point is on an isolated blank line, then it -is deleted. If point is on a nonblank line, the command deletes all -blank lines immediately following it. - -A blank line is defined as a line containing only tabs and spaces. -@c and the Newline character? - -@code{delete-blank-lines} returns @code{nil}. -@end deffn - -@deffn Command delete-trailing-whitespace start end -Delete trailing whitespace in the region defined by @var{start} and -@var{end}. - -This command deletes whitespace characters after the last -non-whitespace character in each line in the region. - -If this command acts on the entire buffer (i.e. if called -interactively with the mark inactive, or called from Lisp with -@var{end} @code{nil}), it also deletes all trailing lines at the end of the -buffer if the variable @code{delete-trailing-lines} is non-@code{nil}. -@end deffn - -@node The Kill Ring -@section The Kill Ring -@cindex kill ring - - @dfn{Kill functions} delete text like the deletion functions, but save -it so that the user can reinsert it by @dfn{yanking}. Most of these -functions have @samp{kill-} in their name. By contrast, the functions -whose names start with @samp{delete-} normally do not save text for -yanking (though they can still be undone); these are ``deletion'' -functions. - - Most of the kill commands are primarily for interactive use, and are -not described here. What we do describe are the functions provided for -use in writing such commands. You can use these functions to write -commands for killing text. When you need to delete text for internal -purposes within a Lisp function, you should normally use deletion -functions, so as not to disturb the kill ring contents. -@xref{Deletion}. - - Killed text is saved for later yanking in the @dfn{kill ring}. This -is a list that holds a number of recent kills, not just the last text -kill. We call this a ``ring'' because yanking treats it as having -elements in a cyclic order. The list is kept in the variable -@code{kill-ring}, and can be operated on with the usual functions for -lists; there are also specialized functions, described in this section, -that treat it as a ring. - - Some people think this use of the word ``kill'' is unfortunate, since -it refers to operations that specifically @emph{do not} destroy the -entities ``killed''. This is in sharp contrast to ordinary life, in -which death is permanent and ``killed'' entities do not come back to -life. Therefore, other metaphors have been proposed. For example, the -term ``cut ring'' makes sense to people who, in pre-computer days, used -scissors and paste to cut up and rearrange manuscripts. However, it -would be difficult to change the terminology now. - -@menu -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. -@end menu - -@node Kill Ring Concepts -@subsection Kill Ring Concepts - - The kill ring records killed text as strings in a list, most recent -first. A short kill ring, for example, might look like this: - -@example -("some text" "a different piece of text" "even older text") -@end example - -@noindent -When the list reaches @code{kill-ring-max} entries in length, adding a -new entry automatically deletes the last entry. - - When kill commands are interwoven with other commands, each kill -command makes a new entry in the kill ring. Multiple kill commands in -succession build up a single kill ring entry, which would be yanked as a -unit; the second and subsequent consecutive kill commands add text to -the entry made by the first one. - - For yanking, one entry in the kill ring is designated the ``front'' of -the ring. Some yank commands ``rotate'' the ring by designating a -different element as the ``front''. But this virtual rotation doesn't -change the list itself---the most recent entry always comes first in the -list. - -@node Kill Functions -@subsection Functions for Killing - - @code{kill-region} is the usual subroutine for killing text. Any -command that calls this function is a ``kill command'' (and should -probably have @samp{kill} in its name). @code{kill-region} puts the -newly killed text in a new element at the beginning of the kill ring or -adds it to the most recent element. It determines automatically (using -@code{last-command}) whether the previous command was a kill command, -and if so appends the killed text to the most recent entry. - -@deffn Command kill-region start end -This function kills the text in the region defined by @var{start} and -@var{end}. The text is deleted but saved in the kill ring, along with -its text properties. The value is always @code{nil}. - -In an interactive call, @var{start} and @var{end} are point and -the mark. - -If the buffer or text is read-only, @code{kill-region} modifies the kill -ring just the same, then signals an error without modifying the buffer. -This is convenient because it lets the user use a series of kill -commands to copy text from a read-only buffer into the kill ring. -@end deffn - -@defopt kill-read-only-ok -If this option is non-@code{nil}, @code{kill-region} does not signal an -error if the buffer or text is read-only. Instead, it simply returns, -updating the kill ring but not changing the buffer. -@end defopt - -@deffn Command copy-region-as-kill start end -This command saves the region defined by @var{start} and @var{end} on -the kill ring (including text properties), but does not delete the text -from the buffer. It returns @code{nil}. - -The command does not set @code{this-command} to @code{kill-region}, so a -subsequent kill command does not append to the same kill ring entry. - -@c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then? -@c Why is it used in many places in Emacs? -In Lisp programs, it is better to use @code{kill-new} or -@code{kill-append} instead of this command. @xref{Low-Level Kill Ring}. -@end deffn - -@node Yanking -@subsection Yanking - - Yanking means inserting text from the kill ring, but it does not -insert the text blindly. The @code{yank} command, and related -commands, use @code{insert-for-yank} to perform special processing on -the text before it is inserted. - -@defun insert-for-yank string -This function works like @code{insert}, except that it processes the -text in @var{string} according to the @code{yank-handler} text -property, as well as the variables @code{yank-handled-properties} and -@code{yank-excluded-properties} (see below), before inserting the -result into the current buffer. -@end defun - -@defun insert-buffer-substring-as-yank buf &optional start end -This function resembles @code{insert-buffer-substring}, except that it -processes the text according to @code{yank-handled-properties} and -@code{yank-excluded-properties}. (It does not handle the -@code{yank-handler} property, which does not normally occur in buffer -text anyway.) -@end defun - -@c FIXME: Add an index for yank-handler. - If you put a @code{yank-handler} text property on all or part of a -string, that alters how @code{insert-for-yank} inserts the string. If -different parts of the string have different @code{yank-handler} -values (comparison being done with @code{eq}), each substring is -handled separately. The property value must be a list of one to four -elements, with the following format (where elements after the first -may be omitted): - -@example -(@var{function} @var{param} @var{noexclude} @var{undo}) -@end example - - Here is what the elements do: - -@table @var -@item function -When @var{function} is non-@code{nil}, it is called instead of -@code{insert} to insert the string, with one argument---the string to -insert. - -@item param -If @var{param} is present and non-@code{nil}, it replaces @var{string} -(or the substring of @var{string} being processed) as the object -passed to @var{function} (or @code{insert}). For example, if -@var{function} is @code{yank-rectangle}, @var{param} should be a list -of strings to insert as a rectangle. - -@item noexclude -If @var{noexclude} is present and non-@code{nil}, that disables the -normal action of @code{yank-handled-properties} and -@code{yank-excluded-properties} on the inserted string. - -@item undo -If @var{undo} is present and non-@code{nil}, it is a function that will be -called by @code{yank-pop} to undo the insertion of the current object. -It is called with two arguments, the start and end of the current -region. @var{function} can set @code{yank-undo-function} to override -the @var{undo} value. -@end table - -@cindex yanking and text properties -@defopt yank-handled-properties -This variable specifies special text property handling conditions for -yanked text. It takes effect after the text has been inserted (either -normally, or via the @code{yank-handler} property), and prior to -@code{yank-excluded-properties} taking effect. - -The value should be an alist of elements @code{(@var{prop} -. @var{fun})}. Each alist element is handled in order. The inserted -text is scanned for stretches of text having text properties @code{eq} -to @var{prop}; for each such stretch, @var{fun} is called with three -arguments: the value of the property, and the start and end positions -of the text. -@end defopt - -@defopt yank-excluded-properties -The value of this variable is the list of properties to remove from -inserted text. Its default value contains properties that might lead -to annoying results, such as causing the text to respond to the mouse -or specifying key bindings. It takes effect after -@code{yank-handled-properties}. -@end defopt - - -@node Yank Commands -@subsection Functions for Yanking - - This section describes higher-level commands for yanking, which are -intended primarily for the user but useful also in Lisp programs. -Both @code{yank} and @code{yank-pop} honor the -@code{yank-excluded-properties} variable and @code{yank-handler} text -property (@pxref{Yanking}). - -@deffn Command yank &optional arg -@cindex inserting killed text -This command inserts before point the text at the front of the kill -ring. It sets the mark at the beginning of that text, using -@code{push-mark} (@pxref{The Mark}), and puts point at the end. - -If @var{arg} is a non-@code{nil} list (which occurs interactively when -the user types @kbd{C-u} with no digits), then @code{yank} inserts the -text as described above, but puts point before the yanked text and -sets the mark after it. - -If @var{arg} is a number, then @code{yank} inserts the @var{arg}th -most recently killed text---the @var{arg}th element of the kill ring -list, counted cyclically from the front, which is considered the -first element for this purpose. - -@code{yank} does not alter the contents of the kill ring, unless it -used text provided by another program, in which case it pushes that text -onto the kill ring. However if @var{arg} is an integer different from -one, it rotates the kill ring to place the yanked string at the front. - -@code{yank} returns @code{nil}. -@end deffn - -@deffn Command yank-pop &optional arg -This command replaces the just-yanked entry from the kill ring with a -different entry from the kill ring. - -This is allowed only immediately after a @code{yank} or another -@code{yank-pop}. At such a time, the region contains text that was just -inserted by yanking. @code{yank-pop} deletes that text and inserts in -its place a different piece of killed text. It does not add the deleted -text to the kill ring, since it is already in the kill ring somewhere. -It does however rotate the kill ring to place the newly yanked string at -the front. - -If @var{arg} is @code{nil}, then the replacement text is the previous -element of the kill ring. If @var{arg} is numeric, the replacement is -the @var{arg}th previous kill. If @var{arg} is negative, a more recent -kill is the replacement. - -The sequence of kills in the kill ring wraps around, so that after the -oldest one comes the newest one, and before the newest one goes the -oldest. - -The return value is always @code{nil}. -@end deffn - -@defvar yank-undo-function -If this variable is non-@code{nil}, the function @code{yank-pop} uses -its value instead of @code{delete-region} to delete the text -inserted by the previous @code{yank} or -@code{yank-pop} command. The value must be a function of two -arguments, the start and end of the current region. - -The function @code{insert-for-yank} automatically sets this variable -according to the @var{undo} element of the @code{yank-handler} -text property, if there is one. -@end defvar - -@node Low-Level Kill Ring -@subsection Low-Level Kill Ring - - These functions and variables provide access to the kill ring at a -lower level, but are still convenient for use in Lisp programs, -because they take care of interaction with window system selections -(@pxref{Window System Selections}). - -@defun current-kill n &optional do-not-move -The function @code{current-kill} rotates the yanking pointer, which -designates the ``front'' of the kill ring, by @var{n} places (from newer -kills to older ones), and returns the text at that place in the ring. - -If the optional second argument @var{do-not-move} is non-@code{nil}, -then @code{current-kill} doesn't alter the yanking pointer; it just -returns the @var{n}th kill, counting from the current yanking pointer. - -If @var{n} is zero, indicating a request for the latest kill, -@code{current-kill} calls the value of -@code{interprogram-paste-function} (documented below) before -consulting the kill ring. If that value is a function and calling it -returns a string or a list of several string, @code{current-kill} -pushes the strings onto the kill ring and returns the first string. -It also sets the yanking pointer to point to the kill-ring entry of -the first string returned by @code{interprogram-paste-function}, -regardless of the value of @var{do-not-move}. Otherwise, -@code{current-kill} does not treat a zero value for @var{n} specially: -it returns the entry pointed at by the yanking pointer and does not -move the yanking pointer. -@end defun - -@defun kill-new string &optional replace -This function pushes the text @var{string} onto the kill ring and -makes the yanking pointer point to it. It discards the oldest entry -if appropriate. It also invokes the value of -@code{interprogram-cut-function} (see below). - -If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the -first element of the kill ring with @var{string}, rather than pushing -@var{string} onto the kill ring. -@end defun - -@defun kill-append string before-p -This function appends the text @var{string} to the first entry in the -kill ring and makes the yanking pointer point to the combined entry. -Normally @var{string} goes at the end of the entry, but if -@var{before-p} is non-@code{nil}, it goes at the beginning. This -function also invokes the value of @code{interprogram-cut-function} -(see below). -@end defun - -@defvar interprogram-paste-function -This variable provides a way of transferring killed text from other -programs, when you are using a window system. Its value should be -@code{nil} or a function of no arguments. - -If the value is a function, @code{current-kill} calls it to get the -``most recent kill''. If the function returns a non-@code{nil} value, -then that value is used as the ``most recent kill''. If it returns -@code{nil}, then the front of the kill ring is used. - -To facilitate support for window systems that support multiple -selections, this function may also return a list of strings. In that -case, the first string is used as the ``most recent kill'', and all -the other strings are pushed onto the kill ring, for easy access by -@code{yank-pop}. - -The normal use of this function is to get the window system's -clipboard as the most recent kill, even if the selection belongs to -another application. @xref{Window System Selections}. However, if -the clipboard contents come from the current Emacs session, this -function should return @code{nil}. -@end defvar - -@defvar interprogram-cut-function -This variable provides a way of communicating killed text to other -programs, when you are using a window system. Its value should be -@code{nil} or a function of one required argument. - -If the value is a function, @code{kill-new} and @code{kill-append} call -it with the new first element of the kill ring as the argument. - -The normal use of this function is to put newly killed text in the -window system's clipboard. @xref{Window System Selections}. -@end defvar - -@node Internals of Kill Ring -@subsection Internals of the Kill Ring - - The variable @code{kill-ring} holds the kill ring contents, in the -form of a list of strings. The most recent kill is always at the front -of the list. - - The @code{kill-ring-yank-pointer} variable points to a link in the -kill ring list, whose @sc{car} is the text to yank next. We say it -identifies the ``front'' of the ring. Moving -@code{kill-ring-yank-pointer} to a different link is called -@dfn{rotating the kill ring}. We call the kill ring a ``ring'' because -the functions that move the yank pointer wrap around from the end of the -list to the beginning, or vice-versa. Rotation of the kill ring is -virtual; it does not change the value of @code{kill-ring}. - - Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp -variables whose values are normally lists. The word ``pointer'' in the -name of the @code{kill-ring-yank-pointer} indicates that the variable's -purpose is to identify one element of the list for use by the next yank -command. - - The value of @code{kill-ring-yank-pointer} is always @code{eq} to one -of the links in the kill ring list. The element it identifies is the -@sc{car} of that link. Kill commands, which change the kill ring, also -set this variable to the value of @code{kill-ring}. The effect is to -rotate the ring so that the newly killed text is at the front. - - Here is a diagram that shows the variable @code{kill-ring-yank-pointer} -pointing to the second entry in the kill ring @code{("some text" "a -different piece of text" "yet older text")}. - -@example -@group -kill-ring ---- kill-ring-yank-pointer - | | - | v - | --- --- --- --- --- --- - --> | | |------> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - | | -->"yet older text" - | | - | --> "a different piece of text" - | - --> "some text" -@end group -@end example - -@noindent -This state of affairs might occur after @kbd{C-y} (@code{yank}) -immediately followed by @kbd{M-y} (@code{yank-pop}). - -@defvar kill-ring -This variable holds the list of killed text sequences, most recently -killed first. -@end defvar - -@defvar kill-ring-yank-pointer -This variable's value indicates which element of the kill ring is at the -``front'' of the ring for yanking. More precisely, the value is a tail -of the value of @code{kill-ring}, and its @sc{car} is the kill string -that @kbd{C-y} should yank. -@end defvar - -@defopt kill-ring-max -The value of this variable is the maximum length to which the kill -ring can grow, before elements are thrown away at the end. The default -value for @code{kill-ring-max} is 60. -@end defopt - -@node Undo -@section Undo -@cindex redo - - Most buffers have an @dfn{undo list}, which records all changes made -to the buffer's text so that they can be undone. (The buffers that -don't have one are usually special-purpose buffers for which Emacs -assumes that undoing is not useful. In particular, any buffer whose -name begins with a space has its undo recording off by default; -see @ref{Buffer Names}.) All the primitives that modify the -text in the buffer automatically add elements to the front of the undo -list, which is in the variable @code{buffer-undo-list}. - -@defvar buffer-undo-list -This buffer-local variable's value is the undo list of the current -buffer. A value of @code{t} disables the recording of undo information. -@end defvar - -Here are the kinds of elements an undo list can have: - -@table @code -@item @var{position} -This kind of element records a previous value of point; undoing this -element moves point to @var{position}. Ordinary cursor motion does not -make any sort of undo record, but deletion operations use these entries -to record where point was before the command. - -@item (@var{beg} . @var{end}) -This kind of element indicates how to delete text that was inserted. -Upon insertion, the text occupied the range @var{beg}--@var{end} in the -buffer. - -@item (@var{text} . @var{position}) -This kind of element indicates how to reinsert text that was deleted. -The deleted text itself is the string @var{text}. The place to -reinsert it is @code{(abs @var{position})}. If @var{position} is -positive, point was at the beginning of the deleted text, otherwise it -was at the end. Zero or more (@var{marker} . @var{adjustment}) -elements follow immediately after this element. - -@item (t . @var{time-flag}) -This kind of element indicates that an unmodified buffer became -modified. A @var{time-flag} of the form -@code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})} represents the visited file's modification time as of -when it was previously visited or saved, using the same format as -@code{current-time}; see @ref{Time of Day}. -A @var{time-flag} of 0 means the buffer does not correspond to any file; -@minus{}1 means the visited file previously did not exist. -@code{primitive-undo} uses these -values to determine whether to mark the buffer as unmodified once again; -it does so only if the file's status matches that of @var{time-flag}. - -@item (nil @var{property} @var{value} @var{beg} . @var{end}) -This kind of element records a change in a text property. -Here's how you might undo the change: - -@example -(put-text-property @var{beg} @var{end} @var{property} @var{value}) -@end example - -@item (@var{marker} . @var{adjustment}) -This kind of element records the fact that the marker @var{marker} was -relocated due to deletion of surrounding text, and that it moved -@var{adjustment} character positions. If the marker's location is -consistent with the (@var{text} . @var{position}) element preceding it -in the undo list, then undoing this element moves @var{marker} -@minus{} @var{adjustment} characters. - -@item (apply @var{funname} . @var{args}) -This is an extensible undo item, which is undone by calling -@var{funname} with arguments @var{args}. - -@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args}) -This is an extensible undo item, which records a change limited to the -range @var{beg} to @var{end}, which increased the size of the buffer -by @var{delta} characters. It is undone by calling @var{funname} with -arguments @var{args}. - -This kind of element enables undo limited to a region to determine -whether the element pertains to that region. - -@item nil -This element is a boundary. The elements between two boundaries are -called a @dfn{change group}; normally, each change group corresponds to -one keyboard command, and undo commands normally undo an entire group as -a unit. -@end table - -@defun undo-boundary -This function places a boundary element in the undo list. The undo -command stops at such a boundary, and successive undo commands undo -to earlier and earlier boundaries. This function returns @code{nil}. - -The editor command loop automatically calls @code{undo-boundary} just -before executing each key sequence, so that each undo normally undoes -the effects of one command. As an exception, the command -@code{self-insert-command}, which produces self-inserting input -characters (@pxref{Commands for Insertion}), may remove the boundary -inserted by the command loop: a boundary is accepted for the first -such character, the next 19 consecutive self-inserting input -characters do not have boundaries, and then the 20th does; and so on -as long as the self-inserting characters continue. Hence, sequences -of consecutive character insertions can be undone as a group. - -All buffer modifications add a boundary whenever the previous undoable -change was made in some other buffer. This is to ensure that -each command makes a boundary in each buffer where it makes changes. - -Calling this function explicitly is useful for splitting the effects of -a command into more than one unit. For example, @code{query-replace} -calls @code{undo-boundary} after each replacement, so that the user can -undo individual replacements one by one. -@end defun - -@defvar undo-in-progress -This variable is normally @code{nil}, but the undo commands bind it to -@code{t}. This is so that various kinds of change hooks can tell when -they're being called for the sake of undoing. -@end defvar - -@defun primitive-undo count list -This is the basic function for undoing elements of an undo list. -It undoes the first @var{count} elements of @var{list}, returning -the rest of @var{list}. - -@code{primitive-undo} adds elements to the buffer's undo list when it -changes the buffer. Undo commands avoid confusion by saving the undo -list value at the beginning of a sequence of undo operations. Then the -undo operations use and update the saved value. The new elements added -by undoing are not part of this saved value, so they don't interfere with -continuing to undo. - -This function does not bind @code{undo-in-progress}. -@end defun - -@node Maintaining Undo -@section Maintaining Undo Lists - - This section describes how to enable and disable undo information for -a given buffer. It also explains how the undo list is truncated -automatically so it doesn't get too big. - - Recording of undo information in a newly created buffer is normally -enabled to start with; but if the buffer name starts with a space, the -undo recording is initially disabled. You can explicitly enable or -disable undo recording with the following two functions, or by setting -@code{buffer-undo-list} yourself. - -@deffn Command buffer-enable-undo &optional buffer-or-name -This command enables recording undo information for buffer -@var{buffer-or-name}, so that subsequent changes can be undone. If no -argument is supplied, then the current buffer is used. This function -does nothing if undo recording is already enabled in the buffer. It -returns @code{nil}. - -In an interactive call, @var{buffer-or-name} is the current buffer. -You cannot specify any other buffer. -@end deffn - -@deffn Command buffer-disable-undo &optional buffer-or-name -@cindex disabling undo -This function discards the undo list of @var{buffer-or-name}, and disables -further recording of undo information. As a result, it is no longer -possible to undo either previous changes or any subsequent changes. If -the undo list of @var{buffer-or-name} is already disabled, this function -has no effect. - -In an interactive call, BUFFER-OR-NAME is the current buffer. You -cannot specify any other buffer. This function returns @code{nil}. -@end deffn - - As editing continues, undo lists get longer and longer. To prevent -them from using up all available memory space, garbage collection trims -them back to size limits you can set. (For this purpose, the ``size'' -of an undo list measures the cons cells that make up the list, plus the -strings of deleted text.) Three variables control the range of acceptable -sizes: @code{undo-limit}, @code{undo-strong-limit} and -@code{undo-outer-limit}. In these variables, size is counted as the -number of bytes occupied, which includes both saved text and other -data. - -@defopt undo-limit -This is the soft limit for the acceptable size of an undo list. The -change group at which this size is exceeded is the last one kept. -@end defopt - -@defopt undo-strong-limit -This is the upper limit for the acceptable size of an undo list. The -change group at which this size is exceeded is discarded itself (along -with all older change groups). There is one exception: the very latest -change group is only discarded if it exceeds @code{undo-outer-limit}. -@end defopt - -@defopt undo-outer-limit -If at garbage collection time the undo info for the current command -exceeds this limit, Emacs discards the info and displays a warning. -This is a last ditch limit to prevent memory overflow. -@end defopt - -@defopt undo-ask-before-discard -If this variable is non-@code{nil}, when the undo info exceeds -@code{undo-outer-limit}, Emacs asks in the echo area whether to -discard the info. The default value is @code{nil}, which means to -discard it automatically. - -This option is mainly intended for debugging. Garbage collection is -inhibited while the question is asked, which means that Emacs might -leak memory if the user waits too long before answering the question. -@end defopt - -@node Filling -@section Filling -@cindex filling text - - @dfn{Filling} means adjusting the lengths of lines (by moving the line -breaks) so that they are nearly (but no greater than) a specified -maximum width. Additionally, lines can be @dfn{justified}, which means -inserting spaces to make the left and/or right margins line up -precisely. The width is controlled by the variable @code{fill-column}. -For ease of reading, lines should be no longer than 70 or so columns. - - You can use Auto Fill mode (@pxref{Auto Filling}) to fill text -automatically as you insert it, but changes to existing text may leave -it improperly filled. Then you must fill the text explicitly. - - Most of the commands in this section return values that are not -meaningful. All the functions that do filling take note of the current -left margin, current right margin, and current justification style -(@pxref{Margins}). If the current justification style is -@code{none}, the filling functions don't actually do anything. - - Several of the filling functions have an argument @var{justify}. -If it is non-@code{nil}, that requests some kind of justification. It -can be @code{left}, @code{right}, @code{full}, or @code{center}, to -request a specific style of justification. If it is @code{t}, that -means to use the current justification style for this part of the text -(see @code{current-justification}, below). Any other value is treated -as @code{full}. - - When you call the filling functions interactively, using a prefix -argument implies the value @code{full} for @var{justify}. - -@deffn Command fill-paragraph &optional justify region -This command fills the paragraph at or after point. If -@var{justify} is non-@code{nil}, each line is justified as well. -It uses the ordinary paragraph motion commands to find paragraph -boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}. - -When @var{region} is non-@code{nil}, then if Transient Mark mode is -enabled and the mark is active, this command calls @code{fill-region} -to fill all the paragraphs in the region, instead of filling only the -current paragraph. When this command is called interactively, -@var{region} is @code{t}. -@end deffn - -@deffn Command fill-region start end &optional justify nosqueeze to-eop -This command fills each of the paragraphs in the region from @var{start} -to @var{end}. It justifies as well if @var{justify} is -non-@code{nil}. - -If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace -other than line breaks untouched. If @var{to-eop} is non-@code{nil}, -that means to keep filling to the end of the paragraph---or the next hard -newline, if @code{use-hard-newlines} is enabled (see below). - -The variable @code{paragraph-separate} controls how to distinguish -paragraphs. @xref{Standard Regexps}. -@end deffn - -@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp -This command fills each paragraph in the region according to its -individual fill prefix. Thus, if the lines of a paragraph were indented -with spaces, the filled paragraph will remain indented in the same -fashion. - -The first two arguments, @var{start} and @var{end}, are the beginning -and end of the region to be filled. The third and fourth arguments, -@var{justify} and @var{citation-regexp}, are optional. If -@var{justify} is non-@code{nil}, the paragraphs are justified as -well as filled. If @var{citation-regexp} is non-@code{nil}, it means the -function is operating on a mail message and therefore should not fill -the header lines. If @var{citation-regexp} is a string, it is used as -a regular expression; if it matches the beginning of a line, that line -is treated as a citation marker. - -@c FIXME: "That mode" is confusing. It isn't a major/minor mode. -Ordinarily, @code{fill-individual-paragraphs} regards each change in -indentation as starting a new paragraph. If -@code{fill-individual-varying-indent} is non-@code{nil}, then only -separator lines separate paragraphs. That mode can handle indented -paragraphs with additional indentation on the first line. -@end deffn - -@defopt fill-individual-varying-indent -This variable alters the action of @code{fill-individual-paragraphs} as -described above. -@end defopt - -@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after -This command considers a region of text as a single paragraph and fills -it. If the region was made up of many paragraphs, the blank lines -between paragraphs are removed. This function justifies as well as -filling when @var{justify} is non-@code{nil}. - -If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace -other than line breaks untouched. If @var{squeeze-after} is -non-@code{nil}, it specifies a position in the region, and means don't -canonicalize spaces before that position. - -In Adaptive Fill mode, this command calls @code{fill-context-prefix} to -choose a fill prefix by default. @xref{Adaptive Fill}. -@end deffn - -@deffn Command justify-current-line &optional how eop nosqueeze -This command inserts spaces between the words of the current line so -that the line ends exactly at @code{fill-column}. It returns -@code{nil}. - -The argument @var{how}, if non-@code{nil} specifies explicitly the style -of justification. It can be @code{left}, @code{right}, @code{full}, -@code{center}, or @code{none}. If it is @code{t}, that means to do -follow specified justification style (see @code{current-justification}, -below). @code{nil} means to do full justification. - -If @var{eop} is non-@code{nil}, that means do only left-justification -if @code{current-justification} specifies full justification. This is -used for the last line of a paragraph; even if the paragraph as a -whole is fully justified, the last line should not be. - -If @var{nosqueeze} is non-@code{nil}, that means do not change interior -whitespace. -@end deffn - -@defopt default-justification -This variable's value specifies the style of justification to use for -text that doesn't specify a style with a text property. The possible -values are @code{left}, @code{right}, @code{full}, @code{center}, or -@code{none}. The default value is @code{left}. -@end defopt - -@defun current-justification -This function returns the proper justification style to use for filling -the text around point. - -This returns the value of the @code{justification} text property at -point, or the variable @var{default-justification} if there is no such -text property. However, it returns @code{nil} rather than @code{none} -to mean ``don't justify''. -@end defun - -@defopt sentence-end-double-space -@anchor{Definition of sentence-end-double-space} -If this variable is non-@code{nil}, a period followed by just one space -does not count as the end of a sentence, and the filling functions -avoid breaking the line at such a place. -@end defopt - -@defopt sentence-end-without-period -If this variable is non-@code{nil}, a sentence can end without a -period. This is used for languages like Thai, where sentences end -with a double space but without a period. -@end defopt - -@defopt sentence-end-without-space -If this variable is non-@code{nil}, it should be a string of -characters that can end a sentence without following spaces. -@end defopt - -@defvar fill-paragraph-function -This variable provides a way to override the filling of paragraphs. -If its value is non-@code{nil}, @code{fill-paragraph} calls this -function to do the work. If the function returns a non-@code{nil} -value, @code{fill-paragraph} assumes the job is done, and immediately -returns that value. - -The usual use of this feature is to fill comments in programming -language modes. If the function needs to fill a paragraph in the usual -way, it can do so as follows: - -@example -(let ((fill-paragraph-function nil)) - (fill-paragraph arg)) -@end example -@end defvar - -@defvar fill-forward-paragraph-function -This variable provides a way to override how the filling functions, -such as @code{fill-region} and @code{fill-paragraph}, move forward to -the next paragraph. Its value should be a function, which is called -with a single argument @var{n}, the number of paragraphs to move, and -should return the difference between @var{n} and the number of -paragraphs actually moved. The default value of this variable is -@code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs -Manual}. -@end defvar - -@defvar use-hard-newlines -If this variable is non-@code{nil}, the filling functions do not delete -newlines that have the @code{hard} text property. These ``hard -newlines'' act as paragraph separators. @xref{Hard and Soft -Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. -@end defvar - -@node Margins -@section Margins for Filling -@cindex margins, filling - -@defopt fill-prefix -This buffer-local variable, if non-@code{nil}, specifies a string of -text that appears at the beginning of normal text lines and should be -disregarded when filling them. Any line that fails to start with the -fill prefix is considered the start of a paragraph; so is any line -that starts with the fill prefix followed by additional whitespace. -Lines that start with the fill prefix but no additional whitespace are -ordinary text lines that can be filled together. The resulting filled -lines also start with the fill prefix. - -The fill prefix follows the left margin whitespace, if any. -@end defopt - -@defopt fill-column -This buffer-local variable specifies the maximum width of filled lines. -Its value should be an integer, which is a number of columns. All the -filling, justification, and centering commands are affected by this -variable, including Auto Fill mode (@pxref{Auto Filling}). - -As a practical matter, if you are writing text for other people to -read, you should set @code{fill-column} to no more than 70. Otherwise -the line will be too long for people to read comfortably, and this can -make the text seem clumsy. - -The default value for @code{fill-column} is 70. -@end defopt - -@deffn Command set-left-margin from to margin -This sets the @code{left-margin} property on the text from @var{from} to -@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this -command also refills the region to fit the new margin. -@end deffn - -@deffn Command set-right-margin from to margin -This sets the @code{right-margin} property on the text from @var{from} -to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, -this command also refills the region to fit the new margin. -@end deffn - -@defun current-left-margin -This function returns the proper left margin value to use for filling -the text around point. The value is the sum of the @code{left-margin} -property of the character at the start of the current line (or zero if -none), and the value of the variable @code{left-margin}. -@end defun - -@defun current-fill-column -This function returns the proper fill column value to use for filling -the text around point. The value is the value of the @code{fill-column} -variable, minus the value of the @code{right-margin} property of the -character after point. -@end defun - -@deffn Command move-to-left-margin &optional n force -This function moves point to the left margin of the current line. The -column moved to is determined by calling the function -@code{current-left-margin}. If the argument @var{n} is non-@code{nil}, -@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first. - -If @var{force} is non-@code{nil}, that says to fix the line's -indentation if that doesn't match the left margin value. -@end deffn - -@defun delete-to-left-margin &optional from to -This function removes left margin indentation from the text between -@var{from} and @var{to}. The amount of indentation to delete is -determined by calling @code{current-left-margin}. In no case does this -function delete non-whitespace. If @var{from} and @var{to} are omitted, -they default to the whole buffer. -@end defun - -@defun indent-to-left-margin -This function adjusts the indentation at the beginning of the current -line to the value specified by the variable @code{left-margin}. (That -may involve either inserting or deleting whitespace.) This function -is value of @code{indent-line-function} in Paragraph-Indent Text mode. -@end defun - -@defopt left-margin -This variable specifies the base left margin column. In Fundamental -mode, @kbd{RET} indents to this column. This variable automatically -becomes buffer-local when set in any fashion. -@end defopt - -@defopt fill-nobreak-predicate -This variable gives major modes a way to specify not to break a line -at certain places. Its value should be a list of functions. Whenever -filling considers breaking the line at a certain place in the buffer, -it calls each of these functions with no arguments and with point -located at that place. If any of the functions returns -non-@code{nil}, then the line won't be broken there. -@end defopt - -@node Adaptive Fill -@section Adaptive Fill Mode -@c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent. - - When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill -prefix automatically from the text in each paragraph being filled -rather than using a predetermined value. During filling, this fill -prefix gets inserted at the start of the second and subsequent lines -of the paragraph as described in @ref{Filling}, and in @ref{Auto -Filling}. - -@defopt adaptive-fill-mode -Adaptive Fill mode is enabled when this variable is non-@code{nil}. -It is @code{t} by default. -@end defopt - -@defun fill-context-prefix from to -This function implements the heart of Adaptive Fill mode; it chooses a -fill prefix based on the text between @var{from} and @var{to}, -typically the start and end of a paragraph. It does this by looking -at the first two lines of the paragraph, based on the variables -described below. -@c The optional argument first-line-regexp is not documented -@c because it exists for internal purposes and might be eliminated -@c in the future. - -Usually, this function returns the fill prefix, a string. However, -before doing this, the function makes a final check (not specially -mentioned in the following) that a line starting with this prefix -wouldn't look like the start of a paragraph. Should this happen, the -function signals the anomaly by returning @code{nil} instead. - -In detail, @code{fill-context-prefix} does this: - -@enumerate -@item -It takes a candidate for the fill prefix from the first line---it -tries first the function in @code{adaptive-fill-function} (if any), -then the regular expression @code{adaptive-fill-regexp} (see below). -The first non-@code{nil} result of these, or the empty string if -they're both @code{nil}, becomes the first line's candidate. -@item -If the paragraph has as yet only one line, the function tests the -validity of the prefix candidate just found. The function then -returns the candidate if it's valid, or a string of spaces otherwise. -(see the description of @code{adaptive-fill-first-line-regexp} below). -@item -When the paragraph already has two lines, the function next looks for -a prefix candidate on the second line, in just the same way it did for -the first line. If it doesn't find one, it returns @code{nil}. -@item -The function now compares the two candidate prefixes heuristically: if -the non-whitespace characters in the line 2 candidate occur in the -same order in the line 1 candidate, the function returns the line 2 -candidate. Otherwise, it returns the largest initial substring which -is common to both candidates (which might be the empty string). -@end enumerate -@end defun - -@defopt adaptive-fill-regexp -Adaptive Fill mode matches this regular expression against the text -starting after the left margin whitespace (if any) on a line; the -characters it matches are that line's candidate for the fill prefix. - -The default value matches whitespace with certain punctuation -characters intermingled. -@end defopt - -@defopt adaptive-fill-first-line-regexp -Used only in one-line paragraphs, this regular expression acts as an -additional check of the validity of the one available candidate fill -prefix: the candidate must match this regular expression, or match -@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} -replaces the candidate with a string of spaces ``of the same width'' -as it. - -The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which -matches only a string of whitespace. The effect of this default is to -force the fill prefixes found in one-line paragraphs always to be pure -whitespace. -@end defopt - -@defopt adaptive-fill-function -You can specify more complex ways of choosing a fill prefix -automatically by setting this variable to a function. The function is -called with point after the left margin (if any) of a line, and it -must preserve point. It should return either ``that line's'' fill -prefix or @code{nil}, meaning it has failed to determine a prefix. -@end defopt - -@node Auto Filling -@section Auto Filling -@cindex filling, automatic -@cindex Auto Fill mode - -@c FIXME: I don't think any of the variables below is a/an normal/abnormal hook. - Auto Fill mode is a minor mode that fills lines automatically as text -is inserted. This section describes the hook used by Auto Fill mode. -For a description of functions that you can call explicitly to fill and -justify existing text, see @ref{Filling}. - - Auto Fill mode also enables the functions that change the margins and -justification style to refill portions of the text. @xref{Margins}. - -@defvar auto-fill-function -The value of this buffer-local variable should be a function (of no -arguments) to be called after self-inserting a character from the table -@code{auto-fill-chars}. It may be @code{nil}, in which case nothing -special is done in that case. - -The value of @code{auto-fill-function} is @code{do-auto-fill} when -Auto-Fill mode is enabled. That is a function whose sole purpose is to -implement the usual strategy for breaking a line. -@end defvar - -@defvar normal-auto-fill-function -This variable specifies the function to use for -@code{auto-fill-function}, if and when Auto Fill is turned on. Major -modes can set buffer-local values for this variable to alter how Auto -Fill works. -@end defvar - -@defvar auto-fill-chars -A char table of characters which invoke @code{auto-fill-function} when -self-inserted---space and newline in most language environments. They -have an entry @code{t} in the table. -@end defvar - -@node Sorting -@section Sorting Text -@cindex sorting text - - The sorting functions described in this section all rearrange text in -a buffer. This is in contrast to the function @code{sort}, which -rearranges the order of the elements of a list (@pxref{Rearrangement}). -The values returned by these functions are not meaningful. - -@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate -This function is the general text-sorting routine that subdivides a -buffer into records and then sorts them. Most of the commands in this -section use this function. - -To understand how @code{sort-subr} works, consider the whole accessible -portion of the buffer as being divided into disjoint pieces called -@dfn{sort records}. The records may or may not be contiguous, but they -must not overlap. A portion of each sort record (perhaps all of it) is -designated as the sort key. Sorting rearranges the records in order by -their sort keys. - -Usually, the records are rearranged in order of ascending sort key. -If the first argument to the @code{sort-subr} function, @var{reverse}, -is non-@code{nil}, the sort records are rearranged in order of -descending sort key. - -The next four arguments to @code{sort-subr} are functions that are -called to move point across a sort record. They are called many times -from within @code{sort-subr}. - -@enumerate -@item -@var{nextrecfun} is called with point at the end of a record. This -function moves point to the start of the next record. The first record -is assumed to start at the position of point when @code{sort-subr} is -called. Therefore, you should usually move point to the beginning of -the buffer before calling @code{sort-subr}. - -This function can indicate there are no more sort records by leaving -point at the end of the buffer. - -@item -@var{endrecfun} is called with point within a record. It moves point to -the end of the record. - -@item -@var{startkeyfun} is called to move point from the start of a record to -the start of the sort key. This argument is optional; if it is omitted, -the whole record is the sort key. If supplied, the function should -either return a non-@code{nil} value to be used as the sort key, or -return @code{nil} to indicate that the sort key is in the buffer -starting at point. In the latter case, @var{endkeyfun} is called to -find the end of the sort key. - -@item -@var{endkeyfun} is called to move point from the start of the sort key -to the end of the sort key. This argument is optional. If -@var{startkeyfun} returns @code{nil} and this argument is omitted (or -@code{nil}), then the sort key extends to the end of the record. There -is no need for @var{endkeyfun} if @var{startkeyfun} returns a -non-@code{nil} value. -@end enumerate - -The argument @var{predicate} is the function to use to compare keys. -If keys are numbers, it defaults to @code{<}; otherwise it defaults to -@code{string<}. - -As an example of @code{sort-subr}, here is the complete function -definition for @code{sort-lines}: - -@example -@group -;; @r{Note that the first two lines of doc string} -;; @r{are effectively one line when viewed by a user.} -(defun sort-lines (reverse beg end) - "Sort lines in region alphabetically;\ - argument means descending order. -Called from a program, there are three arguments: -@end group -@group -REVERSE (non-nil means reverse order),\ - BEG and END (region to sort). -The variable `sort-fold-case' determines\ - whether alphabetic case affects -the sort order." -@end group -@group - (interactive "P\nr") - (save-excursion - (save-restriction - (narrow-to-region beg end) - (goto-char (point-min)) - (let ((inhibit-field-text-motion t)) - (sort-subr reverse 'forward-line 'end-of-line))))) -@end group -@end example - -Here @code{forward-line} moves point to the start of the next record, -and @code{end-of-line} moves point to the end of record. We do not pass -the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire -record is used as the sort key. - -The @code{sort-paragraphs} function is very much the same, except that -its @code{sort-subr} call looks like this: - -@example -@group -(sort-subr reverse - (function - (lambda () - (while (and (not (eobp)) - (looking-at paragraph-separate)) - (forward-line 1)))) - 'forward-paragraph) -@end group -@end example - -Markers pointing into any sort records are left with no useful -position after @code{sort-subr} returns. -@end defun - -@defopt sort-fold-case -If this variable is non-@code{nil}, @code{sort-subr} and the other -buffer sorting functions ignore case when comparing strings. -@end defopt - -@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end -This command sorts the region between @var{start} and @var{end} -alphabetically as specified by @var{record-regexp} and @var{key-regexp}. -If @var{reverse} is a negative integer, then sorting is in reverse -order. - -Alphabetical sorting means that two sort keys are compared by -comparing the first characters of each, the second characters of each, -and so on. If a mismatch is found, it means that the sort keys are -unequal; the sort key whose character is less at the point of first -mismatch is the lesser sort key. The individual characters are compared -according to their numerical character codes in the Emacs character set. - -The value of the @var{record-regexp} argument specifies how to divide -the buffer into sort records. At the end of each record, a search is -done for this regular expression, and the text that matches it is taken -as the next record. For example, the regular expression @samp{^.+$}, -which matches lines with at least one character besides a newline, would -make each such line into a sort record. @xref{Regular Expressions}, for -a description of the syntax and meaning of regular expressions. - -The value of the @var{key-regexp} argument specifies what part of each -record is the sort key. The @var{key-regexp} could match the whole -record, or only a part. In the latter case, the rest of the record has -no effect on the sorted order of records, but it is carried along when -the record moves to its new position. - -The @var{key-regexp} argument can refer to the text matched by a -subexpression of @var{record-regexp}, or it can be a regular expression -on its own. - -If @var{key-regexp} is: - -@table @asis -@item @samp{\@var{digit}} -then the text matched by the @var{digit}th @samp{\(...\)} parenthesis -grouping in @var{record-regexp} is the sort key. - -@item @samp{\&} -then the whole record is the sort key. - -@item a regular expression -then @code{sort-regexp-fields} searches for a match for the regular -expression within the record. If such a match is found, it is the sort -key. If there is no match for @var{key-regexp} within a record then -that record is ignored, which means its position in the buffer is not -changed. (The other records may move around it.) -@end table - -For example, if you plan to sort all the lines in the region by the -first word on each line starting with the letter @samp{f}, you should -set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to -@samp{\}. The resulting expression looks like this: - -@example -@group -(sort-regexp-fields nil "^.*$" "\\" - (region-beginning) - (region-end)) -@end group -@end example - -If you call @code{sort-regexp-fields} interactively, it prompts for -@var{record-regexp} and @var{key-regexp} in the minibuffer. -@end deffn - -@deffn Command sort-lines reverse start end -This command alphabetically sorts lines in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-paragraphs reverse start end -This command alphabetically sorts paragraphs in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-pages reverse start end -This command alphabetically sorts pages in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-fields field start end -This command sorts lines in the region between @var{start} and -@var{end}, comparing them alphabetically by the @var{field}th field -of each line. Fields are separated by whitespace and numbered starting -from 1. If @var{field} is negative, sorting is by the -@w{@minus{}@var{field}th} field from the end of the line. This command -is useful for sorting tables. -@end deffn - -@deffn Command sort-numeric-fields field start end -This command sorts lines in the region between @var{start} and -@var{end}, comparing them numerically by the @var{field}th field of -each line. Fields are separated by whitespace and numbered starting -from 1. The specified field must contain a number in each line of the -region. Numbers starting with 0 are treated as octal, and numbers -starting with @samp{0x} are treated as hexadecimal. - -If @var{field} is negative, sorting is by the -@w{@minus{}@var{field}th} field from the end of the line. This -command is useful for sorting tables. -@end deffn - -@defopt sort-numeric-base -This variable specifies the default radix for -@code{sort-numeric-fields} to parse numbers. -@end defopt - -@deffn Command sort-columns reverse &optional beg end -This command sorts the lines in the region between @var{beg} and -@var{end}, comparing them alphabetically by a certain range of -columns. The column positions of @var{beg} and @var{end} bound the -range of columns to sort on. - -If @var{reverse} is non-@code{nil}, the sort is in reverse order. - -One unusual thing about this command is that the entire line -containing position @var{beg}, and the entire line containing position -@var{end}, are included in the region sorted. - -Note that @code{sort-columns} rejects text that contains tabs, because -tabs could be split across the specified columns. Use @kbd{M-x -untabify} to convert tabs to spaces before sorting. - -When possible, this command actually works by calling the @code{sort} -utility program. -@end deffn - -@node Columns -@section Counting Columns -@cindex columns -@cindex counting columns -@cindex horizontal position - - The column functions convert between a character position (counting -characters from the beginning of the buffer) and a column position -(counting screen characters from the beginning of a line). - - These functions count each character according to the number of -columns it occupies on the screen. This means control characters count -as occupying 2 or 4 columns, depending upon the value of -@code{ctl-arrow}, and tabs count as occupying a number of columns that -depends on the value of @code{tab-width} and on the column where the tab -begins. @xref{Usual Display}. - - Column number computations ignore the width of the window and the -amount of horizontal scrolling. Consequently, a column value can be -arbitrarily high. The first (or leftmost) column is numbered 0. They -also ignore overlays and text properties, aside from invisibility. - -@defun current-column -This function returns the horizontal position of point, measured in -columns, counting from 0 at the left margin. The column position is the -sum of the widths of all the displayed representations of the characters -between the start of the current line and point. - -For an example of using @code{current-column}, see the description of -@code{count-lines} in @ref{Text Lines}. -@end defun - -@deffn Command move-to-column column &optional force -This function moves point to @var{column} in the current line. The -calculation of @var{column} takes into account the widths of the -displayed representations of the characters between the start of the -line and point. - -When called interactively, @var{column} is the value of prefix numeric -argument. If @var{column} is not an integer, an error is signaled. - -@c This behavior used to be documented until 2013/08. -@ignore -If column @var{column} is beyond the end of the line, point moves to -the end of the line. If @var{column} is negative, point moves to the -beginning of the line. -@end ignore - -If it is impossible to move to column @var{column} because that is in -the middle of a multicolumn character such as a tab, point moves to the -end of that character. However, if @var{force} is non-@code{nil}, and -@var{column} is in the middle of a tab, then @code{move-to-column} -converts the tab into spaces so that it can move precisely to column -@var{column}. Other multicolumn characters can cause anomalies despite -@var{force}, since there is no way to split them. - -The argument @var{force} also has an effect if the line isn't long -enough to reach column @var{column}; if it is @code{t}, that means to -add whitespace at the end of the line to reach that column. - -The return value is the column number actually moved to. -@end deffn - -@node Indentation -@section Indentation -@cindex indentation - - The indentation functions are used to examine, move to, and change -whitespace that is at the beginning of a line. Some of the functions -can also change whitespace elsewhere on a line. Columns and indentation -count from zero at the left margin. - -@menu -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. -@end menu - -@node Primitive Indent -@subsection Indentation Primitives - - This section describes the primitive functions used to count and -insert indentation. The functions in the following sections use these -primitives. @xref{Size of Displayed Text}, for related functions. - -@defun current-indentation -@comment !!Type Primitive Function -@comment !!SourceFile indent.c -This function returns the indentation of the current line, which is -the horizontal position of the first nonblank character. If the -contents are entirely blank, then this is the horizontal position of the -end of the line. -@end defun - -@deffn Command indent-to column &optional minimum -@comment !!Type Primitive Function -@comment !!SourceFile indent.c -This function indents from point with tabs and spaces until @var{column} -is reached. If @var{minimum} is specified and non-@code{nil}, then at -least that many spaces are inserted even if this requires going beyond -@var{column}. Otherwise the function does nothing if point is already -beyond @var{column}. The value is the column at which the inserted -indentation ends. - -The inserted whitespace characters inherit text properties from the -surrounding text (usually, from the preceding text only). @xref{Sticky -Properties}. -@end deffn - -@defopt indent-tabs-mode -@comment !!SourceFile indent.c -If this variable is non-@code{nil}, indentation functions can insert -tabs as well as spaces. Otherwise, they insert only spaces. Setting -this variable automatically makes it buffer-local in the current buffer. -@end defopt - -@node Mode-Specific Indent -@subsection Indentation Controlled by Major Mode - - An important function of each major mode is to customize the @key{TAB} -key to indent properly for the language being edited. This section -describes the mechanism of the @key{TAB} key and how to control it. -The functions in this section return unpredictable values. - -@deffn Command indent-for-tab-command &optional rigid -This is the command bound to @key{TAB} in most editing modes. Its -usual action is to indent the current line, but it can alternatively -insert a tab character or indent a region. - -Here is what it does: - -@itemize -@item -First, it checks whether Transient Mark mode is enabled and the region -is active. If so, it called @code{indent-region} to indent all the -text in the region (@pxref{Region Indent}). - -@item -Otherwise, if the indentation function in @code{indent-line-function} -is @code{indent-to-left-margin} (a trivial command that inserts a tab -character), or if the variable @code{tab-always-indent} specifies that -a tab character ought to be inserted (see below), then it inserts a -tab character. - -@item -Otherwise, it indents the current line; this is done by calling the -function in @code{indent-line-function}. If the line is already -indented, and the value of @code{tab-always-indent} is @code{complete} -(see below), it tries completing the text at point. -@end itemize - -If @var{rigid} is non-@code{nil} (interactively, with a prefix -argument), then after this command indents a line or inserts a tab, it -also rigidly indents the entire balanced expression which starts at -the beginning of the current line, in order to reflect the new -indentation. This argument is ignored if the command indents the -region. -@end deffn - -@defvar indent-line-function -This variable's value is the function to be used by -@code{indent-for-tab-command}, and various other indentation commands, -to indent the current line. It is usually assigned by the major mode; -for instance, Lisp mode sets it to @code{lisp-indent-line}, C mode -sets it to @code{c-indent-line}, and so on. The default value is -@code{indent-relative}. @xref{Auto-Indentation}. -@end defvar - -@deffn Command indent-according-to-mode -This command calls the function in @code{indent-line-function} to -indent the current line in a way appropriate for the current major mode. -@end deffn - -@deffn Command newline-and-indent -This function inserts a newline, then indents the new line (the one -following the newline just inserted) according to the major mode. It -does indentation by calling @code{indent-according-to-mode}. -@end deffn - -@deffn Command reindent-then-newline-and-indent -This command reindents the current line, inserts a newline at point, -and then indents the new line (the one following the newline just -inserted). It does indentation on both lines by calling -@code{indent-according-to-mode}. -@end deffn - -@defopt tab-always-indent -This variable can be used to customize the behavior of the @key{TAB} -(@code{indent-for-tab-command}) command. If the value is @code{t} -(the default), the command normally just indents the current line. If -the value is @code{nil}, the command indents the current line only if -point is at the left margin or in the line's indentation; otherwise, -it inserts a tab character. If the value is @code{complete}, the -command first tries to indent the current line, and if the line was -already indented, it calls @code{completion-at-point} to complete the -text at point (@pxref{Completion in Buffers}). -@end defopt - -@node Region Indent -@subsection Indenting an Entire Region - - This section describes commands that indent all the lines in the -region. They return unpredictable values. - -@deffn Command indent-region start end &optional to-column -This command indents each nonblank line starting between @var{start} -(inclusive) and @var{end} (exclusive). If @var{to-column} is -@code{nil}, @code{indent-region} indents each nonblank line by calling -the current mode's indentation function, the value of -@code{indent-line-function}. - -If @var{to-column} is non-@code{nil}, it should be an integer -specifying the number of columns of indentation; then this function -gives each line exactly that much indentation, by either adding or -deleting whitespace. - -If there is a fill prefix, @code{indent-region} indents each line -by making it start with the fill prefix. -@end deffn - -@defvar indent-region-function -The value of this variable is a function that can be used by -@code{indent-region} as a short cut. It should take two arguments, the -start and end of the region. You should design the function so -that it will produce the same results as indenting the lines of the -region one by one, but presumably faster. - -If the value is @code{nil}, there is no short cut, and -@code{indent-region} actually works line by line. - -A short-cut function is useful in modes such as C mode and Lisp mode, -where the @code{indent-line-function} must scan from the beginning of -the function definition: applying it to each line would be quadratic in -time. The short cut can update the scan information as it moves through -the lines indenting them; this takes linear time. In a mode where -indenting a line individually is fast, there is no need for a short cut. - -@code{indent-region} with a non-@code{nil} argument @var{to-column} has -a different meaning and does not use this variable. -@end defvar - -@deffn Command indent-rigidly start end count -This function indents all lines starting between @var{start} -(inclusive) and @var{end} (exclusive) sideways by @var{count} columns. -This ``preserves the shape'' of the affected region, moving it as a -rigid unit. - -This is useful not only for indenting regions of unindented text, but -also for indenting regions of formatted code. For example, if -@var{count} is 3, this command adds 3 columns of indentation to every -line that begins in the specified region. - -If called interactively with no prefix argument, this command invokes -a transient mode for adjusting indentation rigidly. @xref{Indentation -Commands,,, emacs, The GNU Emacs Manual}. -@end deffn - -@deffn Command indent-code-rigidly start end columns &optional nochange-regexp -This is like @code{indent-rigidly}, except that it doesn't alter lines -that start within strings or comments. - -In addition, it doesn't alter a line if @var{nochange-regexp} matches at -the beginning of the line (if @var{nochange-regexp} is non-@code{nil}). -@end deffn - -@node Relative Indent -@subsection Indentation Relative to Previous Lines - - This section describes two commands that indent the current line -based on the contents of previous lines. - -@deffn Command indent-relative &optional unindented-ok -This command inserts whitespace at point, extending to the same -column as the next @dfn{indent point} of the previous nonblank line. An -indent point is a non-whitespace character following whitespace. The -next indent point is the first one at a column greater than the current -column of point. For example, if point is underneath and to the left of -the first non-blank character of a line of text, it moves to that column -by inserting whitespace. - -If the previous nonblank line has no next indent point (i.e., none at a -great enough column position), @code{indent-relative} either does -nothing (if @var{unindented-ok} is non-@code{nil}) or calls -@code{tab-to-tab-stop}. Thus, if point is underneath and to the right -of the last column of a short line of text, this command ordinarily -moves point to the next tab stop by inserting whitespace. - -The return value of @code{indent-relative} is unpredictable. - -In the following example, point is at the beginning of the second -line: - -@example -@group - This line is indented twelve spaces. -@point{}The quick brown fox jumped. -@end group -@end example - -@noindent -Evaluation of the expression @code{(indent-relative nil)} produces the -following: - -@example -@group - This line is indented twelve spaces. - @point{}The quick brown fox jumped. -@end group -@end example - - In this next example, point is between the @samp{m} and @samp{p} of -@samp{jumped}: - -@example -@group - This line is indented twelve spaces. -The quick brown fox jum@point{}ped. -@end group -@end example - -@noindent -Evaluation of the expression @code{(indent-relative nil)} produces the -following: - -@example -@group - This line is indented twelve spaces. -The quick brown fox jum @point{}ped. -@end group -@end example -@end deffn - -@deffn Command indent-relative-maybe -@comment !!SourceFile indent.el -This command indents the current line like the previous nonblank line, -by calling @code{indent-relative} with @code{t} as the -@var{unindented-ok} argument. The return value is unpredictable. - -If the previous nonblank line has no indent points beyond the current -column, this command does nothing. -@end deffn - -@node Indent Tabs -@subsection Adjustable ``Tab Stops'' -@cindex tabs stops for indentation - - This section explains the mechanism for user-specified ``tab stops'' -and the mechanisms that use and set them. The name ``tab stops'' is -used because the feature is similar to that of the tab stops on a -typewriter. The feature works by inserting an appropriate number of -spaces and tab characters to reach the next tab stop column; it does not -affect the display of tab characters in the buffer (@pxref{Usual -Display}). Note that the @key{TAB} character as input uses this tab -stop feature only in a few major modes, such as Text mode. -@xref{Tab Stops,,, emacs, The GNU Emacs Manual}. - -@deffn Command tab-to-tab-stop -This command inserts spaces or tabs before point, up to the next tab -stop column defined by @code{tab-stop-list}. -@end deffn - -@defopt tab-stop-list -This variable defines the tab stop columns used by @code{tab-to-tab-stop}. -It should be either @code{nil}, or a list of increasing integers, -which need not be evenly spaced. The list is implicitly -extended to infinity through repetition of the interval between the -last and penultimate elements (or @code{tab-width} if the list has -fewer than two elements). A value of @code{nil} means a tab stop -every @code{tab-width} columns. - -Use @kbd{M-x edit-tab-stops} to edit the location of tab stops interactively. -@end defopt - -@node Motion by Indent -@subsection Indentation-Based Motion Commands - - These commands, primarily for interactive use, act based on the -indentation in the text. - -@deffn Command back-to-indentation -@comment !!SourceFile simple.el -This command moves point to the first non-whitespace character in the -current line (which is the line in which point is located). It returns -@code{nil}. -@end deffn - -@deffn Command backward-to-indentation &optional arg -@comment !!SourceFile simple.el -This command moves point backward @var{arg} lines and then to the -first nonblank character on that line. It returns @code{nil}. -If @var{arg} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@deffn Command forward-to-indentation &optional arg -@comment !!SourceFile simple.el -This command moves point forward @var{arg} lines and then to the first -nonblank character on that line. It returns @code{nil}. -If @var{arg} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@node Case Changes -@section Case Changes -@cindex case conversion in buffers - - The case change commands described here work on text in the current -buffer. @xref{Case Conversion}, for case conversion functions that work -on strings and characters. @xref{Case Tables}, for how to customize -which characters are upper or lower case and how to convert them. - -@deffn Command capitalize-region start end -This function capitalizes all words in the region defined by -@var{start} and @var{end}. To capitalize means to convert each word's -first character to upper case and convert the rest of each word to lower -case. The function returns @code{nil}. - -If one end of the region is in the middle of a word, the part of the -word within the region is treated as an entire word. - -When @code{capitalize-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. - -@example -@group ----------- Buffer: foo ---------- -This is the contents of the 5th foo. ----------- Buffer: foo ---------- -@end group - -@group -(capitalize-region 1 37) -@result{} nil - ----------- Buffer: foo ---------- -This Is The Contents Of The 5th Foo. ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command downcase-region start end -This function converts all of the letters in the region defined by -@var{start} and @var{end} to lower case. The function returns -@code{nil}. - -When @code{downcase-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. -@end deffn - -@deffn Command upcase-region start end -This function converts all of the letters in the region defined by -@var{start} and @var{end} to upper case. The function returns -@code{nil}. - -When @code{upcase-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. -@end deffn - -@deffn Command capitalize-word count -This function capitalizes @var{count} words after point, moving point -over as it does. To capitalize means to convert each word's first -character to upper case and convert the rest of each word to lower case. -If @var{count} is negative, the function capitalizes the -@minus{}@var{count} previous words but does not move point. The value -is @code{nil}. - -If point is in the middle of a word, the part of the word before point -is ignored when moving forward. The rest is treated as an entire word. - -When @code{capitalize-word} is called interactively, @var{count} is -set to the numeric prefix argument. -@end deffn - -@deffn Command downcase-word count -This function converts the @var{count} words after point to all lower -case, moving point over as it does. If @var{count} is negative, it -converts the @minus{}@var{count} previous words but does not move point. -The value is @code{nil}. - -When @code{downcase-word} is called interactively, @var{count} is set -to the numeric prefix argument. -@end deffn - -@deffn Command upcase-word count -This function converts the @var{count} words after point to all upper -case, moving point over as it does. If @var{count} is negative, it -converts the @minus{}@var{count} previous words but does not move point. -The value is @code{nil}. - -When @code{upcase-word} is called interactively, @var{count} is set to -the numeric prefix argument. -@end deffn - -@node Text Properties -@section Text Properties -@cindex text properties -@cindex attributes of text -@cindex properties of text - - Each character position in a buffer or a string can have a @dfn{text -property list}, much like the property list of a symbol (@pxref{Property -Lists}). The properties belong to a particular character at a -particular place, such as, the letter @samp{T} at the beginning of this -sentence or the first @samp{o} in @samp{foo}---if the same character -occurs in two different places, the two occurrences in general have -different properties. - - Each property has a name and a value. Both of these can be any Lisp -object, but the name is normally a symbol. Typically each property -name symbol is used for a particular purpose; for instance, the text -property @code{face} specifies the faces for displaying the character -(@pxref{Special Properties}). The usual way to access the property -list is to specify a name and ask what value corresponds to it. - - If a character has a @code{category} property, we call it the -@dfn{property category} of the character. It should be a symbol. The -properties of the symbol serve as defaults for the properties of the -character. - - Copying text between strings and buffers preserves the properties -along with the characters; this includes such diverse functions as -@code{substring}, @code{insert}, and @code{buffer-substring}. - -@menu -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. -@end menu - -@node Examining Properties -@subsection Examining Text Properties - - The simplest way to examine text properties is to ask for the value of -a particular property of a particular character. For that, use -@code{get-text-property}. Use @code{text-properties-at} to get the -entire property list of a character. @xref{Property Search}, for -functions to examine the properties of a number of characters at once. - - These functions handle both strings and buffers. Keep in mind that -positions in a string start from 0, whereas positions in a buffer start -from 1. - -@defun get-text-property pos prop &optional object -This function returns the value of the @var{prop} property of the -character after position @var{pos} in @var{object} (a buffer or -string). The argument @var{object} is optional and defaults to the -current buffer. - -If there is no @var{prop} property strictly speaking, but the character -has a property category that is a symbol, then @code{get-text-property} returns -the @var{prop} property of that symbol. -@end defun - -@defun get-char-property position prop &optional object -This function is like @code{get-text-property}, except that it checks -overlays first and then text properties. @xref{Overlays}. - -The argument @var{object} may be a string, a buffer, or a window. If -it is a window, then the buffer displayed in that window is used for -text properties and overlays, but only the overlays active for that -window are considered. If @var{object} is a buffer, then overlays in -that buffer are considered first, in order of decreasing priority, -followed by the text properties. If @var{object} is a string, only -text properties are considered, since strings never have overlays. -@end defun - -@defun get-pos-property position prop &optional object -This function is like @code{get-char-property}, except that it pays -attention to properties' stickiness and overlays' advancement settings -instead of the property of the character at (i.e. right after) -@var{position}. -@end defun - -@defun get-char-property-and-overlay position prop &optional object -This is like @code{get-char-property}, but gives extra information -about the overlay that the property value comes from. - -Its value is a cons cell whose @sc{car} is the property value, the -same value @code{get-char-property} would return with the same -arguments. Its @sc{cdr} is the overlay in which the property was -found, or @code{nil}, if it was found as a text property or not found -at all. - -If @var{position} is at the end of @var{object}, both the @sc{car} and -the @sc{cdr} of the value are @code{nil}. -@end defun - -@defvar char-property-alias-alist -This variable holds an alist which maps property names to a list of -alternative property names. If a character does not specify a direct -value for a property, the alternative property names are consulted in -order; the first non-@code{nil} value is used. This variable takes -precedence over @code{default-text-properties}, and @code{category} -properties take precedence over this variable. -@end defvar - -@defun text-properties-at position &optional object -This function returns the entire property list of the character at -@var{position} in the string or buffer @var{object}. If @var{object} is -@code{nil}, it defaults to the current buffer. -@end defun - -@defvar default-text-properties -This variable holds a property list giving default values for text -properties. Whenever a character does not specify a value for a -property, neither directly, through a category symbol, or through -@code{char-property-alias-alist}, the value stored in this list is -used instead. Here is an example: - -@example -(setq default-text-properties '(foo 69) - char-property-alias-alist nil) -;; @r{Make sure character 1 has no properties of its own.} -(set-text-properties 1 2 nil) -;; @r{What we get, when we ask, is the default value.} -(get-text-property 1 'foo) - @result{} 69 -@end example -@end defvar - -@node Changing Properties -@subsection Changing Text Properties - - The primitives for changing properties apply to a specified range of -text in a buffer or string. The function @code{set-text-properties} -(see end of section) sets the entire property list of the text in that -range; more often, it is useful to add, change, or delete just certain -properties specified by name. - - Since text properties are considered part of the contents of the -buffer (or string), and can affect how a buffer looks on the screen, -any change in buffer text properties marks the buffer as modified. -Buffer text property changes are undoable also (@pxref{Undo}). -Positions in a string start from 0, whereas positions in a buffer -start from 1. - -@defun put-text-property start end prop value &optional object -This function sets the @var{prop} property to @var{value} for the text -between @var{start} and @var{end} in the string or buffer @var{object}. -If @var{object} is @code{nil}, it defaults to the current buffer. -@end defun - -@defun add-text-properties start end props &optional object -This function adds or overrides text properties for the text between -@var{start} and @var{end} in the string or buffer @var{object}. If -@var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} specifies which properties to add. It should -have the form of a property list (@pxref{Property Lists}): a list whose -elements include the property names followed alternately by the -corresponding values. - -The return value is @code{t} if the function actually changed some -property's value; @code{nil} otherwise (if @var{props} is @code{nil} or -its values agree with those in the text). - -For example, here is how to set the @code{comment} and @code{face} -properties of a range of text: - -@example -(add-text-properties @var{start} @var{end} - '(comment t face highlight)) -@end example -@end defun - -@defun remove-text-properties start end props &optional object -This function deletes specified text properties from the text between -@var{start} and @var{end} in the string or buffer @var{object}. If -@var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} specifies which properties to delete. It -should have the form of a property list (@pxref{Property Lists}): a list -whose elements are property names alternating with corresponding values. -But only the names matter---the values that accompany them are ignored. -For example, here's how to remove the @code{face} property. - -@example -(remove-text-properties @var{start} @var{end} '(face nil)) -@end example - -The return value is @code{t} if the function actually changed some -property's value; @code{nil} otherwise (if @var{props} is @code{nil} or -if no character in the specified text had any of those properties). - -To remove all text properties from certain text, use -@code{set-text-properties} and specify @code{nil} for the new property -list. -@end defun - -@defun remove-list-of-text-properties start end list-of-properties &optional object -Like @code{remove-text-properties} except that -@var{list-of-properties} is a list of property names only, not an -alternating list of property names and values. -@end defun - -@defun set-text-properties start end props &optional object -This function completely replaces the text property list for the text -between @var{start} and @var{end} in the string or buffer @var{object}. -If @var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} is the new property list. It should be a list -whose elements are property names alternating with corresponding values. - -After @code{set-text-properties} returns, all the characters in the -specified range have identical properties. - -If @var{props} is @code{nil}, the effect is to get rid of all properties -from the specified range of text. Here's an example: - -@example -(set-text-properties @var{start} @var{end} nil) -@end example - -Do not rely on the return value of this function. -@end defun - -@defun add-face-text-property start end face &optional appendp object -This function acts on the text between @var{start} and @var{end}, -adding the face @var{face} to the @code{face} text property. -@var{face} should be a valid value for the @code{face} property -(@pxref{Special Properties}), such as a face name or an anonymous face -(@pxref{Faces}). - -If any text in the region already has a non-@code{nil} @code{face} property, -those face(s) are retained. This function sets the @code{face} -property to a list of faces, with @var{face} as the first element (by -default) and the pre-existing faces as the remaining elements. If the -optional argument @var{append} is non-@code{nil}, @var{face} is -appended to the end of the list instead. Note that in a face list, -the first occurring value for each attribute takes precedence. - -For example, the following code would assign a italicized green face -to the text between @var{start} and @var{end}: - -@example -(add-face-text-property @var{start} @var{end} 'italic) -(add-face-text-property @var{start} @var{end} '(:foreground "red")) -(add-face-text-property @var{start} @var{end} '(:foreground "green")) -@end example - -The optional argument @var{object}, if non-@code{nil}, specifies a -buffer or string to act on, rather than the current buffer. If -@var{object} is a string, then @var{start} and @var{end} are -zero-based indices into the string. -@end defun - - The easiest way to make a string with text properties is with -@code{propertize}: - -@defun propertize string &rest properties -This function returns a copy of @var{string} with the text properties -@var{properties} added. These properties apply to all the characters -in the string that is returned. Here is an example that constructs a -string with a @code{face} property and a @code{mouse-face} property: - -@smallexample -(propertize "foo" 'face 'italic - 'mouse-face 'bold-italic) - @result{} #("foo" 0 3 (mouse-face bold-italic face italic)) -@end smallexample - -To put different properties on various parts of a string, you can -construct each part with @code{propertize} and then combine them with -@code{concat}: - -@smallexample -(concat - (propertize "foo" 'face 'italic - 'mouse-face 'bold-italic) - " and " - (propertize "bar" 'face 'italic - 'mouse-face 'bold-italic)) - @result{} #("foo and bar" - 0 3 (face italic mouse-face bold-italic) - 3 8 nil - 8 11 (face italic mouse-face bold-italic)) -@end smallexample -@end defun - - @xref{Buffer Contents}, for the function -@code{buffer-substring-no-properties}, which copies text from the -buffer but does not copy its properties. - -@node Property Search -@subsection Text Property Search Functions - - In typical use of text properties, most of the time several or many -consecutive characters have the same value for a property. Rather than -writing your programs to examine characters one by one, it is much -faster to process chunks of text that have the same property value. - - Here are functions you can use to do this. They use @code{eq} for -comparing property values. In all cases, @var{object} defaults to the -current buffer. - - For good performance, it's very important to use the @var{limit} -argument to these functions, especially the ones that search for a -single property---otherwise, they may spend a long time scanning to the -end of the buffer, if the property you are interested in does not change. - - These functions do not move point; instead, they return a position (or -@code{nil}). Remember that a position is always between two characters; -the position returned by these functions is between two characters with -different properties. - -@defun next-property-change pos &optional object limit -The function scans the text forward from position @var{pos} in the -string or buffer @var{object} until it finds a change in some text -property, then returns the position of the change. In other words, it -returns the position of the first character beyond @var{pos} whose -properties are not identical to those of the character just after -@var{pos}. - -If @var{limit} is non-@code{nil}, then the scan ends at position -@var{limit}. If there is no property change before that point, this -function returns @var{limit}. - -The value is @code{nil} if the properties remain unchanged all the way -to the end of @var{object} and @var{limit} is @code{nil}. If the value -is non-@code{nil}, it is a position greater than or equal to @var{pos}. -The value equals @var{pos} only when @var{limit} equals @var{pos}. - -Here is an example of how to scan the buffer by chunks of text within -which all properties are constant: - -@smallexample -(while (not (eobp)) - (let ((plist (text-properties-at (point))) - (next-change - (or (next-property-change (point) (current-buffer)) - (point-max)))) - @r{Process text from point to @var{next-change}@dots{}} - (goto-char next-change))) -@end smallexample -@end defun - -@defun previous-property-change pos &optional object limit -This is like @code{next-property-change}, but scans back from @var{pos} -instead of forward. If the value is non-@code{nil}, it is a position -less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} -equals @var{pos}. -@end defun - -@defun next-single-property-change pos prop &optional object limit -The function scans text for a change in the @var{prop} property, then -returns the position of the change. The scan goes forward from -position @var{pos} in the string or buffer @var{object}. In other -words, this function returns the position of the first character -beyond @var{pos} whose @var{prop} property differs from that of the -character just after @var{pos}. - -If @var{limit} is non-@code{nil}, then the scan ends at position -@var{limit}. If there is no property change before that point, -@code{next-single-property-change} returns @var{limit}. - -The value is @code{nil} if the property remains unchanged all the way to -the end of @var{object} and @var{limit} is @code{nil}. If the value is -non-@code{nil}, it is a position greater than or equal to @var{pos}; it -equals @var{pos} only if @var{limit} equals @var{pos}. -@end defun - -@defun previous-single-property-change pos prop &optional object limit -This is like @code{next-single-property-change}, but scans back from -@var{pos} instead of forward. If the value is non-@code{nil}, it is a -position less than or equal to @var{pos}; it equals @var{pos} only if -@var{limit} equals @var{pos}. -@end defun - -@defun next-char-property-change pos &optional limit -This is like @code{next-property-change} except that it considers -overlay properties as well as text properties, and if no change is -found before the end of the buffer, it returns the maximum buffer -position rather than @code{nil} (in this sense, it resembles the -corresponding overlay function @code{next-overlay-change}, rather than -@code{next-property-change}). There is no @var{object} operand -because this function operates only on the current buffer. It returns -the next address at which either kind of property changes. -@end defun - -@defun previous-char-property-change pos &optional limit -This is like @code{next-char-property-change}, but scans back from -@var{pos} instead of forward, and returns the minimum buffer -position if no change is found. -@end defun - -@defun next-single-char-property-change pos prop &optional object limit -This is like @code{next-single-property-change} except that it -considers overlay properties as well as text properties, and if no -change is found before the end of the @var{object}, it returns the -maximum valid position in @var{object} rather than @code{nil}. Unlike -@code{next-char-property-change}, this function @emph{does} have an -@var{object} operand; if @var{object} is not a buffer, only -text-properties are considered. -@end defun - -@defun previous-single-char-property-change pos prop &optional object limit -This is like @code{next-single-char-property-change}, but scans back -from @var{pos} instead of forward, and returns the minimum valid -position in @var{object} if no change is found. -@end defun - -@defun text-property-any start end prop value &optional object -This function returns non-@code{nil} if at least one character between -@var{start} and @var{end} has a property @var{prop} whose value is -@var{value}. More precisely, it returns the position of the first such -character. Otherwise, it returns @code{nil}. - -The optional fifth argument, @var{object}, specifies the string or -buffer to scan. Positions are relative to @var{object}. The default -for @var{object} is the current buffer. -@end defun - -@defun text-property-not-all start end prop value &optional object -This function returns non-@code{nil} if at least one character between -@var{start} and @var{end} does not have a property @var{prop} with value -@var{value}. More precisely, it returns the position of the first such -character. Otherwise, it returns @code{nil}. - -The optional fifth argument, @var{object}, specifies the string or -buffer to scan. Positions are relative to @var{object}. The default -for @var{object} is the current buffer. -@end defun - -@node Special Properties -@subsection Properties with Special Meanings - - Here is a table of text property names that have special built-in -meanings. The following sections list a few additional special property -names that control filling and property inheritance. All other names -have no standard meaning, and you can use them as you like. - - Note: the properties @code{composition}, @code{display}, -@code{invisible} and @code{intangible} can also cause point to move to -an acceptable place, after each Emacs command. @xref{Adjusting -Point}. - -@table @code -@cindex property category of text character -@c FIXME: Isn't @kindex for keyboard commands? -@kindex category @r{(text property)} -@item category -If a character has a @code{category} property, we call it the -@dfn{property category} of the character. It should be a symbol. The -properties of this symbol serve as defaults for the properties of the -character. - -@item face -@cindex face codes of text -@kindex face @r{(text property)} -The @code{face} property controls the appearance of the character -(@pxref{Faces}). The value of the property can be the following: - -@itemize @bullet -@item -A face name (a symbol or string). - -@item -An anonymous face: a property list of the form @code{(@var{keyword} -@var{value} @dots{})}, where each @var{keyword} is a face attribute -name and @var{value} is a value for that attribute. - -@item -A list of faces. Each list element should be either a face name or an -anonymous face. This specifies a face which is an aggregate of the -attributes of each of the listed faces. Faces occurring earlier in -the list have higher priority. - -@item -A cons cell of the form @code{(foreground-color . @var{color-name})} -or @code{(background-color . @var{color-name})}. This specifies the -foreground or background color, similar to @code{(:foreground -@var{color-name})} or @code{(:background @var{color-name})}. This -form is supported for backward compatibility only, and should be -avoided. -@end itemize - -Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by -dynamically updating the @code{face} property of characters based on -the context. - -The @code{add-face-text-property} function provides a convenient way -to set this text property. @xref{Changing Properties}. - -@item font-lock-face -@kindex font-lock-face @r{(text property)} -This property specifies a value for the @code{face} property that Font -Lock mode should apply to the underlying text. It is one of the -fontification methods used by Font Lock mode, and is useful for -special modes that implement their own highlighting. -@xref{Precalculated Fontification}. When Font Lock mode is disabled, -@code{font-lock-face} has no effect. - -@item mouse-face -@kindex mouse-face @r{(text property)} -This property is used instead of @code{face} when the mouse is on or -near the character. For this purpose, ``near'' means that all text -between the character and where the mouse is have the same -@code{mouse-face} property value. - -Emacs ignores all face attributes from the @code{mouse-face} property -that alter the text size (e.g., @code{:height}, @code{:weight}, and -@code{:slant}). Those attributes are always the same as for the -unhighlighted text. - -@item fontified -@kindex fontified @r{(text property)} -This property says whether the text is ready for display. If -@code{nil}, Emacs's redisplay routine calls the functions in -@code{fontification-functions} (@pxref{Auto Faces}) to prepare this -part of the buffer before it is displayed. It is used internally by -the ``just in time'' font locking code. - -@item display -This property activates various features that change the -way text is displayed. For example, it can make text appear taller -or shorter, higher or lower, wider or narrow, or replaced with an image. -@xref{Display Property}. - -@item help-echo -@kindex help-echo @r{(text property)} -@cindex tooltip -@anchor{Text help-echo} -If text has a string as its @code{help-echo} property, then when you -move the mouse onto that text, Emacs displays that string in the echo -area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs -Manual}). - -If the value of the @code{help-echo} property is a function, that -function is called with three arguments, @var{window}, @var{object} and -@var{pos} and should return a help string or @code{nil} for -none. The first argument, @var{window} is the window in which -the help was found. The second, @var{object}, is the buffer, overlay or -string which had the @code{help-echo} property. The @var{pos} -argument is as follows: - -@itemize @bullet{} -@item -If @var{object} is a buffer, @var{pos} is the position in the buffer. -@item -If @var{object} is an overlay, that overlay has a @code{help-echo} -property, and @var{pos} is the position in the overlay's buffer. -@item -If @var{object} is a string (an overlay string or a string displayed -with the @code{display} property), @var{pos} is the position in that -string. -@end itemize - -If the value of the @code{help-echo} property is neither a function nor -a string, it is evaluated to obtain a help string. - -You can alter the way help text is displayed by setting the variable -@code{show-help-function} (@pxref{Help display}). - -This feature is used in the mode line and for other active text. - -@item keymap -@cindex keymap of character -@kindex keymap @r{(text property)} -The @code{keymap} property specifies an additional keymap for -commands. When this keymap applies, it is used for key lookup before -the minor mode keymaps and before the buffer's local map. -@xref{Active Keymaps}. If the property value is a symbol, the -symbol's function definition is used as the keymap. - -The property's value for the character before point applies if it is -non-@code{nil} and rear-sticky, and the property's value for the -character after point applies if it is non-@code{nil} and -front-sticky. (For mouse clicks, the position of the click is used -instead of the position of point.) - -@item local-map -@kindex local-map @r{(text property)} -This property works like @code{keymap} except that it specifies a -keymap to use @emph{instead of} the buffer's local map. For most -purposes (perhaps all purposes), it is better to use the @code{keymap} -property. - -@item syntax-table -The @code{syntax-table} property overrides what the syntax table says -about this particular character. @xref{Syntax Properties}. - -@item read-only -@cindex read-only character -@kindex read-only @r{(text property)} -If a character has the property @code{read-only}, then modifying that -character is not allowed. Any command that would do so gets an error, -@code{text-read-only}. If the property value is a string, that string -is used as the error message. - -Insertion next to a read-only character is an error if inserting -ordinary text there would inherit the @code{read-only} property due to -stickiness. Thus, you can control permission to insert next to -read-only text by controlling the stickiness. @xref{Sticky Properties}. - -Since changing properties counts as modifying the buffer, it is not -possible to remove a @code{read-only} property unless you know the -special trick: bind @code{inhibit-read-only} to a non-@code{nil} value -and then remove the property. @xref{Read Only Buffers}. - -@item invisible -@kindex invisible @r{(text property)} -A non-@code{nil} @code{invisible} property can make a character invisible -on the screen. @xref{Invisible Text}, for details. - -@item intangible -@kindex intangible @r{(text property)} -If a group of consecutive characters have equal and non-@code{nil} -@code{intangible} properties, then you cannot place point between them. -If you try to move point forward into the group, point actually moves to -the end of the group. If you try to move point backward into the group, -point actually moves to the start of the group. - -If consecutive characters have unequal non-@code{nil} -@code{intangible} properties, they belong to separate groups; each -group is separately treated as described above. - -When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, -the @code{intangible} property is ignored. - -Beware: this property operates at a very low level, and affects a lot of code -in unexpected ways. So use it with extreme caution. A common misuse is to put -an intangible property on invisible text, which is actually unnecessary since -the command loop will move point outside of the invisible text at the end of -each command anyway. @xref{Adjusting Point}. - -@item field -@kindex field @r{(text property)} -Consecutive characters with the same @code{field} property constitute a -@dfn{field}. Some motion functions including @code{forward-word} and -@code{beginning-of-line} stop moving at a field boundary. -@xref{Fields}. - -@item cursor -@kindex cursor @r{(text property)} -Normally, the cursor is displayed at the beginning or the end of any -overlay and text property strings present at the current buffer -position. You can place the cursor on any desired character of these -strings by giving that character a non-@code{nil} @code{cursor} text -property. In addition, if the value of the @code{cursor} property is -an integer, it specifies the number of buffer's character -positions, starting with the position where the overlay or the -@code{display} property begins, for which the cursor should be -displayed on that character. Specifically, if the value of the -@code{cursor} property of a character is the number @var{n}, the -cursor will be displayed on this character for any buffer position in -the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos} -is the overlay's starting position given by @code{overlay-start} -(@pxref{Managing Overlays}), or the position where the @code{display} -text property begins in the buffer. - -In other words, the string character with the @code{cursor} property -of any non-@code{nil} value is the character where to display the -cursor. The value of the property says for which buffer positions to -display the cursor there. If the value is an integer @var{n}, -the cursor is displayed there when point is anywhere between the -beginning of the overlay or @code{display} property and @var{n} -positions after that. If the value is anything else and -non-@code{nil}, the cursor is displayed there only when point is at -the beginning of the @code{display} property or at -@code{overlay-start}. - -@cindex cursor position for @code{display} properties and overlays -When the buffer has many overlay strings (e.g., @pxref{Overlay -Properties, before-string}) or @code{display} properties that are -strings, it is a good idea to use the @code{cursor} property on these -strings to cue the Emacs display about the places where to put the -cursor while traversing these strings. This directly communicates to -the display engine where the Lisp program wants to put the cursor, or -where the user would expect the cursor. - -@item pointer -@kindex pointer @r{(text property)} -This specifies a specific pointer shape when the mouse pointer is over -this text or image. @xref{Pointer Shape}, for possible pointer -shapes. - -@item line-spacing -@kindex line-spacing @r{(text property)} -A newline can have a @code{line-spacing} text or overlay property that -controls the height of the display line ending with that newline. The -property value overrides the default frame line spacing and the buffer -local @code{line-spacing} variable. @xref{Line Height}. - -@item line-height -@kindex line-height @r{(text property)} -A newline can have a @code{line-height} text or overlay property that -controls the total height of the display line ending in that newline. -@xref{Line Height}. - -@item wrap-prefix -If text has a @code{wrap-prefix} property, the prefix it defines will -be added at display time to the beginning of every continuation line -due to text wrapping (so if lines are truncated, the wrap-prefix is -never used). It may be a string or an image (@pxref{Other Display -Specs}), or a stretch of whitespace such as specified by the -@code{:width} or @code{:align-to} display properties (@pxref{Specified -Space}). - -A wrap-prefix may also be specified for an entire buffer using the -@code{wrap-prefix} buffer-local variable (however, a -@code{wrap-prefix} text-property takes precedence over the value of -the @code{wrap-prefix} variable). @xref{Truncation}. - -@item line-prefix -If text has a @code{line-prefix} property, the prefix it defines will -be added at display time to the beginning of every non-continuation -line. It may be a string or an image (@pxref{Other Display -Specs}), or a stretch of whitespace such as specified by the -@code{:width} or @code{:align-to} display properties (@pxref{Specified -Space}). - -A line-prefix may also be specified for an entire buffer using the -@code{line-prefix} buffer-local variable (however, a -@code{line-prefix} text-property takes precedence over the value of -the @code{line-prefix} variable). @xref{Truncation}. - -@item modification-hooks -@cindex change hooks for a character -@cindex hooks for changing a character -@kindex modification-hooks @r{(text property)} -If a character has the property @code{modification-hooks}, then its -value should be a list of functions; modifying that character calls -all of those functions before the actual modification. Each function -receives two arguments: the beginning and end of the part of the -buffer being modified. Note that if a particular modification hook -function appears on several characters being modified by a single -primitive, you can't predict how many times the function will -be called. -Furthermore, insertion will not modify any existing character, so this -hook will only be run when removing some characters, replacing them -with others, or changing their text-properties. - -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. - -Overlays also support the @code{modification-hooks} property, but the -details are somewhat different (@pxref{Overlay Properties}). - -@item insert-in-front-hooks -@itemx insert-behind-hooks -@kindex insert-in-front-hooks @r{(text property)} -@kindex insert-behind-hooks @r{(text property)} -The operation of inserting text in a buffer also calls the functions -listed in the @code{insert-in-front-hooks} property of the following -character and in the @code{insert-behind-hooks} property of the -preceding character. These functions receive two arguments, the -beginning and end of the inserted text. The functions are called -@emph{after} the actual insertion takes place. - -See also @ref{Change Hooks}, for other hooks that are called -when you change text in a buffer. - -@item point-entered -@itemx point-left -@cindex hooks for motion of point -@kindex point-entered @r{(text property)} -@kindex point-left @r{(text property)} -The special properties @code{point-entered} and @code{point-left} -record hook functions that report motion of point. Each time point -moves, Emacs compares these two property values: - -@itemize @bullet -@item -the @code{point-left} property of the character after the old location, -and -@item -the @code{point-entered} property of the character after the new -location. -@end itemize - -@noindent -If these two values differ, each of them is called (if not @code{nil}) -with two arguments: the old value of point, and the new one. - -The same comparison is made for the characters before the old and new -locations. The result may be to execute two @code{point-left} functions -(which may be the same function) and/or two @code{point-entered} -functions (which may be the same function). In any case, all the -@code{point-left} functions are called first, followed by all the -@code{point-entered} functions. - -It is possible to use @code{char-after} to examine characters at various -buffer positions without moving point to those positions. Only an -actual change in the value of point runs these hook functions. - -The variable @code{inhibit-point-motion-hooks} can inhibit running the -@code{point-left} and @code{point-entered} hooks, see @ref{Inhibit -point motion hooks}. - -@item composition -@kindex composition @r{(text property)} -This text property is used to display a sequence of characters as a -single glyph composed from components. But the value of the property -itself is completely internal to Emacs and should not be manipulated -directly by, for instance, @code{put-text-property}. - -@end table - -@defvar inhibit-point-motion-hooks -@anchor{Inhibit point motion hooks} When this variable is -non-@code{nil}, @code{point-left} and @code{point-entered} hooks are -not run, and the @code{intangible} property has no effect. Do not set -this variable globally; bind it with @code{let}. -@end defvar - -@defvar show-help-function -@anchor{Help display} If this variable is non-@code{nil}, it specifies a -function called to display help strings. These may be @code{help-echo} -properties, menu help strings (@pxref{Simple Menu Items}, -@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool -Bar}). The specified function is called with one argument, the help -string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs -Manual}) provides an example. -@end defvar - -@node Format Properties -@subsection Formatted Text Properties - - These text properties affect the behavior of the fill commands. They -are used for representing formatted text. @xref{Filling}, and -@ref{Margins}. - -@table @code -@item hard -If a newline character has this property, it is a ``hard'' newline. -The fill commands do not alter hard newlines and do not move words -across them. However, this property takes effect only if the -@code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft -Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. - -@item right-margin -This property specifies an extra right margin for filling this part of the -text. - -@item left-margin -This property specifies an extra left margin for filling this part of the -text. - -@item justification -This property specifies the style of justification for filling this part -of the text. -@end table - -@node Sticky Properties -@subsection Stickiness of Text Properties -@cindex sticky text properties -@cindex inheritance, text property - - Self-inserting characters normally take on the same properties as the -preceding character. This is called @dfn{inheritance} of properties. - - A Lisp program can do insertion with inheritance or without, -depending on the choice of insertion primitive. The ordinary text -insertion functions, such as @code{insert}, do not inherit any -properties. They insert text with precisely the properties of the -string being inserted, and no others. This is correct for programs -that copy text from one context to another---for example, into or out -of the kill ring. To insert with inheritance, use the special -primitives described in this section. Self-inserting characters -inherit properties because they work using these primitives. - - When you do insertion with inheritance, @emph{which} properties are -inherited, and from where, depends on which properties are @dfn{sticky}. -Insertion after a character inherits those of its properties that are -@dfn{rear-sticky}. Insertion before a character inherits those of its -properties that are @dfn{front-sticky}. When both sides offer different -sticky values for the same property, the previous character's value -takes precedence. - - By default, a text property is rear-sticky but not front-sticky; thus, -the default is to inherit all the properties of the preceding character, -and nothing from the following character. - - You can control the stickiness of various text properties with two -specific text properties, @code{front-sticky} and @code{rear-nonsticky}, -and with the variable @code{text-property-default-nonsticky}. You can -use the variable to specify a different default for a given property. -You can use those two text properties to make any specific properties -sticky or nonsticky in any particular part of the text. - - If a character's @code{front-sticky} property is @code{t}, then all -its properties are front-sticky. If the @code{front-sticky} property is -a list, then the sticky properties of the character are those whose -names are in the list. For example, if a character has a -@code{front-sticky} property whose value is @code{(face read-only)}, -then insertion before the character can inherit its @code{face} property -and its @code{read-only} property, but no others. - - The @code{rear-nonsticky} property works the opposite way. Most -properties are rear-sticky by default, so the @code{rear-nonsticky} -property says which properties are @emph{not} rear-sticky. If a -character's @code{rear-nonsticky} property is @code{t}, then none of its -properties are rear-sticky. If the @code{rear-nonsticky} property is a -list, properties are rear-sticky @emph{unless} their names are in the -list. - -@defvar text-property-default-nonsticky -This variable holds an alist which defines the default rear-stickiness -of various text properties. Each element has the form -@code{(@var{property} . @var{nonstickiness})}, and it defines the -stickiness of a particular text property, @var{property}. - -If @var{nonstickiness} is non-@code{nil}, this means that the property -@var{property} is rear-nonsticky by default. Since all properties are -front-nonsticky by default, this makes @var{property} nonsticky in both -directions by default. - -The text properties @code{front-sticky} and @code{rear-nonsticky}, when -used, take precedence over the default @var{nonstickiness} specified in -@code{text-property-default-nonsticky}. -@end defvar - - Here are the functions that insert text with inheritance of properties: - -@defun insert-and-inherit &rest strings -Insert the strings @var{strings}, just like the function @code{insert}, -but inherit any sticky properties from the adjoining text. -@end defun - -@defun insert-before-markers-and-inherit &rest strings -Insert the strings @var{strings}, just like the function -@code{insert-before-markers}, but inherit any sticky properties from the -adjoining text. -@end defun - - @xref{Insertion}, for the ordinary insertion functions which do not -inherit. - -@node Lazy Properties -@subsection Lazy Computation of Text Properties - - Instead of computing text properties for all the text in the buffer, -you can arrange to compute the text properties for parts of the text -when and if something depends on them. - - The primitive that extracts text from the buffer along with its -properties is @code{buffer-substring}. Before examining the properties, -this function runs the abnormal hook @code{buffer-access-fontify-functions}. - -@defvar buffer-access-fontify-functions -This variable holds a list of functions for computing text properties. -Before @code{buffer-substring} copies the text and text properties for a -portion of the buffer, it calls all the functions in this list. Each of -the functions receives two arguments that specify the range of the -buffer being accessed. (The buffer itself is always the current -buffer.) -@end defvar - - The function @code{buffer-substring-no-properties} does not call these -functions, since it ignores text properties anyway. - - In order to prevent the hook functions from being called more than -once for the same part of the buffer, you can use the variable -@code{buffer-access-fontified-property}. - -@defvar buffer-access-fontified-property -If this variable's value is non-@code{nil}, it is a symbol which is used -as a text property name. A non-@code{nil} value for that text property -means, ``the other text properties for this character have already been -computed''. - -If all the characters in the range specified for @code{buffer-substring} -have a non-@code{nil} value for this property, @code{buffer-substring} -does not call the @code{buffer-access-fontify-functions} functions. It -assumes these characters already have the right text properties, and -just copies the properties they already have. - -The normal way to use this feature is that the -@code{buffer-access-fontify-functions} functions add this property, as -well as others, to the characters they operate on. That way, they avoid -being called over and over for the same text. -@end defvar - -@node Clickable Text -@subsection Defining Clickable Text -@cindex clickable text -@cindex follow links -@cindex mouse-1 - - @dfn{Clickable text} is text that can be clicked, with either the -mouse or via a keyboard command, to produce some result. Many major -modes use clickable text to implement textual hyper-links, or -@dfn{links} for short. - - The easiest way to insert and manipulate links is to use the -@code{button} package. @xref{Buttons}. In this section, we will -explain how to manually set up clickable text in a buffer, using text -properties. For simplicity, we will refer to the clickable text as a -@dfn{link}. - - Implementing a link involves three separate steps: (1) indicating -clickability when the mouse moves over the link; (2) making @key{RET} -or @kbd{Mouse-2} on that link do something; and (3) setting up a -@code{follow-link} condition so that the link obeys -@code{mouse-1-click-follows-link}. - - To indicate clickability, add the @code{mouse-face} text property to -the text of the link; then Emacs will highlight the link when the -mouse moves over it. In addition, you should define a tooltip or echo -area message, using the @code{help-echo} text property. @xref{Special -Properties}. For instance, here is how Dired indicates that file -names are clickable: - -@smallexample - (if (dired-move-to-filename) - (add-text-properties - (point) - (save-excursion - (dired-move-to-end-of-filename) - (point)) - '(mouse-face highlight - help-echo "mouse-2: visit this file in other window"))) -@end smallexample - - To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to -commands that perform the desired action. Each command should check -to see whether it was called on a link, and act accordingly. For -instance, Dired's major mode keymap binds @kbd{Mouse-2} to the -following command: - -@smallexample -(defun dired-mouse-find-file-other-window (event) - "In Dired, visit the file or directory name you click on." - (interactive "e") - (let ((window (posn-window (event-end event))) - (pos (posn-point (event-end event))) - file) - (if (not (windowp window)) - (error "No file chosen")) - (with-current-buffer (window-buffer window) - (goto-char pos) - (setq file (dired-get-file-for-visit))) - (if (file-directory-p file) - (or (and (cdr dired-subdir-alist) - (dired-goto-subdir file)) - (progn - (select-window window) - (dired-other-window file))) - (select-window window) - (find-file-other-window (file-name-sans-versions file t))))) -@end smallexample - -@noindent -This command uses the functions @code{posn-window} and -@code{posn-point} to determine where the click occurred, and -@code{dired-get-file-for-visit} to determine which file to visit. - - Instead of binding the mouse command in a major mode keymap, you can -bind it within the link text, using the @code{keymap} text property -(@pxref{Special Properties}). For instance: - -@example -(let ((map (make-sparse-keymap))) - (define-key map [mouse-2] 'operate-this-button) - (put-text-property link-start link-end 'keymap map)) -@end example - -@noindent -With this method, you can easily define different commands for -different links. Furthermore, the global definition of @key{RET} and -@kbd{Mouse-2} remain available for the rest of the text in the buffer. - -@vindex mouse-1-click-follows-link - The basic Emacs command for clicking on links is @kbd{Mouse-2}. -However, for compatibility with other graphical applications, Emacs -also recognizes @kbd{Mouse-1} clicks on links, provided the user -clicks on the link quickly without moving the mouse. This behavior is -controlled by the user option @code{mouse-1-click-follows-link}. -@xref{Mouse References,,, emacs, The GNU Emacs Manual}. - - To set up the link so that it obeys -@code{mouse-1-click-follows-link}, you must either (1) apply a -@code{follow-link} text or overlay property to the link text, or (2) -bind the @code{follow-link} event to a keymap (which can be a major -mode keymap or a local keymap specified via the @code{keymap} text -property). The value of the @code{follow-link} property, or the -binding for the @code{follow-link} event, acts as a ``condition'' for -the link action. This condition tells Emacs two things: the -circumstances under which a @kbd{Mouse-1} click should be regarded as -occurring ``inside'' the link, and how to compute an ``action code'' -that says what to translate the @kbd{Mouse-1} click into. The link -action condition can be one of the following: - -@table @asis -@item @code{mouse-face} -If the condition is the symbol @code{mouse-face}, a position is inside -a link if there is a non-@code{nil} @code{mouse-face} property at that -position. The action code is always @code{t}. - -For example, here is how Info mode handles @key{Mouse-1}: - -@smallexample -(define-key Info-mode-map [follow-link] 'mouse-face) -@end smallexample - -@item a function -If the condition is a function, @var{func}, then a position @var{pos} -is inside a link if @code{(@var{func} @var{pos})} evaluates to -non-@code{nil}. The value returned by @var{func} serves as the action -code. - -For example, here is how pcvs enables @kbd{Mouse-1} to follow links on -file names only: - -@smallexample -(define-key map [follow-link] - (lambda (pos) - (eq (get-char-property pos 'face) 'cvs-filename-face))) -@end smallexample - -@item anything else -If the condition value is anything else, then the position is inside a -link and the condition itself is the action code. Clearly, you should -specify this kind of condition only when applying the condition via a -text or property overlay on the link text (so that it does not apply -to the entire buffer). -@end table - -@noindent -The action code tells @kbd{Mouse-1} how to follow the link: - -@table @asis -@item a string or vector -If the action code is a string or vector, the @kbd{Mouse-1} event is -translated into the first element of the string or vector; i.e., the -action of the @kbd{Mouse-1} click is the local or global binding of -that character or symbol. Thus, if the action code is @code{"foo"}, -@kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, -@kbd{Mouse-1} translates into @key{foo}. - -@item anything else -For any other non-@code{nil} action code, the @kbd{Mouse-1} event is -translated into a @kbd{Mouse-2} event at the same position. -@end table - - To define @kbd{Mouse-1} to activate a button defined with -@code{define-button-type}, give the button a @code{follow-link} -property. The property value should be a link action condition, as -described above. @xref{Buttons}. For example, here is how Help mode -handles @kbd{Mouse-1}: - -@smallexample -(define-button-type 'help-xref - 'follow-link t - 'action #'help-button-action) -@end smallexample - - To define @kbd{Mouse-1} on a widget defined with -@code{define-widget}, give the widget a @code{:follow-link} property. -The property value should be a link action condition, as described -above. For example, here is how the @code{link} widget specifies that -a @key{Mouse-1} click shall be translated to @key{RET}: - -@smallexample -(define-widget 'link 'item - "An embedded link." - :button-prefix 'widget-link-prefix - :button-suffix 'widget-link-suffix - :follow-link "\C-m" - :help-echo "Follow the link." - :format "%[%t%]") -@end smallexample - -@defun mouse-on-link-p pos -This function returns non-@code{nil} if position @var{pos} in the -current buffer is on a link. @var{pos} can also be a mouse event -location, as returned by @code{event-start} (@pxref{Accessing Mouse}). -@end defun - -@node Fields -@subsection Defining and Using Fields -@cindex fields - - A field is a range of consecutive characters in the buffer that are -identified by having the same value (comparing with @code{eq}) of the -@code{field} property (either a text-property or an overlay property). -This section describes special functions that are available for -operating on fields. - - You specify a field with a buffer position, @var{pos}. We think of -each field as containing a range of buffer positions, so the position -you specify stands for the field containing that position. - - When the characters before and after @var{pos} are part of the same -field, there is no doubt which field contains @var{pos}: the one those -characters both belong to. When @var{pos} is at a boundary between -fields, which field it belongs to depends on the stickiness of the -@code{field} properties of the two surrounding characters (@pxref{Sticky -Properties}). The field whose property would be inherited by text -inserted at @var{pos} is the field that contains @var{pos}. - - There is an anomalous case where newly inserted text at @var{pos} -would not inherit the @code{field} property from either side. This -happens if the previous character's @code{field} property is not -rear-sticky, and the following character's @code{field} property is not -front-sticky. In this case, @var{pos} belongs to neither the preceding -field nor the following field; the field functions treat it as belonging -to an empty field whose beginning and end are both at @var{pos}. - - In all of these functions, if @var{pos} is omitted or @code{nil}, the -value of point is used by default. If narrowing is in effect, then -@var{pos} should fall within the accessible portion. @xref{Narrowing}. - -@defun field-beginning &optional pos escape-from-edge limit -This function returns the beginning of the field specified by @var{pos}. - -If @var{pos} is at the beginning of its field, and -@var{escape-from-edge} is non-@code{nil}, then the return value is -always the beginning of the preceding field that @emph{ends} at @var{pos}, -regardless of the stickiness of the @code{field} properties around -@var{pos}. - -If @var{limit} is non-@code{nil}, it is a buffer position; if the -beginning of the field is before @var{limit}, then @var{limit} will be -returned instead. -@end defun - -@defun field-end &optional pos escape-from-edge limit -This function returns the end of the field specified by @var{pos}. - -If @var{pos} is at the end of its field, and @var{escape-from-edge} is -non-@code{nil}, then the return value is always the end of the following -field that @emph{begins} at @var{pos}, regardless of the stickiness of -the @code{field} properties around @var{pos}. - -If @var{limit} is non-@code{nil}, it is a buffer position; if the end -of the field is after @var{limit}, then @var{limit} will be returned -instead. -@end defun - -@defun field-string &optional pos -This function returns the contents of the field specified by @var{pos}, -as a string. -@end defun - -@defun field-string-no-properties &optional pos -This function returns the contents of the field specified by @var{pos}, -as a string, discarding text properties. -@end defun - -@defun delete-field &optional pos -This function deletes the text of the field specified by @var{pos}. -@end defun - -@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property -This function ``constrains'' @var{new-pos} to the field that -@var{old-pos} belongs to---in other words, it returns the position -closest to @var{new-pos} that is in the same field as @var{old-pos}. - -If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses -the value of point instead, and moves point to the resulting position -in addition to returning that position. - -If @var{old-pos} is at the boundary of two fields, then the acceptable -final positions depend on the argument @var{escape-from-edge}. If -@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in -the field whose @code{field} property equals what new characters -inserted at @var{old-pos} would inherit. (This depends on the -stickiness of the @code{field} property for the characters before and -after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil}, -@var{new-pos} can be anywhere in the two adjacent fields. -Additionally, if two fields are separated by another field with the -special value @code{boundary}, then any point within this special -field is also considered to be ``on the boundary''. - -Commands like @kbd{C-a} with no argument, that normally move backward -to a specific kind of location and stay there once there, probably -should specify @code{nil} for @var{escape-from-edge}. Other motion -commands that check fields should probably pass @code{t}. - -If the optional argument @var{only-in-line} is non-@code{nil}, and -constraining @var{new-pos} in the usual way would move it to a different -line, @var{new-pos} is returned unconstrained. This used in commands -that move by line, such as @code{next-line} and -@code{beginning-of-line}, so that they respect field boundaries only in -the case where they can still move to the right line. - -If the optional argument @var{inhibit-capture-property} is -non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that -name, then any field boundaries are ignored. - -You can cause @code{constrain-to-field} to ignore all field boundaries -(and so never constrain anything) by binding the variable -@code{inhibit-field-text-motion} to a non-@code{nil} value. -@end defun - -@node Not Intervals -@subsection Why Text Properties are not Intervals -@cindex intervals - - Some editors that support adding attributes to text in the buffer do -so by letting the user specify ``intervals'' within the text, and adding -the properties to the intervals. Those editors permit the user or the -programmer to determine where individual intervals start and end. We -deliberately provided a different sort of interface in Emacs Lisp to -avoid certain paradoxical behavior associated with text modification. - - If the actual subdivision into intervals is meaningful, that means you -can distinguish between a buffer that is just one interval with a -certain property, and a buffer containing the same text subdivided into -two intervals, both of which have that property. - - Suppose you take the buffer with just one interval and kill part of -the text. The text remaining in the buffer is one interval, and the -copy in the kill ring (and the undo list) becomes a separate interval. -Then if you yank back the killed text, you get two intervals with the -same properties. Thus, editing does not preserve the distinction -between one interval and two. - - Suppose we ``fix'' this problem by coalescing the two intervals when -the text is inserted. That works fine if the buffer originally was a -single interval. But suppose instead that we have two adjacent -intervals with the same properties, and we kill the text of one interval -and yank it back. The same interval-coalescence feature that rescues -the other case causes trouble in this one: after yanking, we have just -one interval. Once again, editing does not preserve the distinction -between one interval and two. - - Insertion of text at the border between intervals also raises -questions that have no satisfactory answer. - - However, it is easy to arrange for editing to behave consistently -for questions of the form, ``What are the properties of text at this -buffer or string position?'' So we have decided these are the only -questions that make sense; we have not implemented asking questions -about where intervals start or end. - - In practice, you can usually use the text property search functions in -place of explicit interval boundaries. You can think of them as finding -the boundaries of intervals, assuming that intervals are always -coalesced whenever possible. @xref{Property Search}. - - Emacs also provides explicit intervals as a presentation feature; see -@ref{Overlays}. - -@node Substitution -@section Substituting for a Character Code - - The following functions replace characters within a specified region -based on their character codes. - -@defun subst-char-in-region start end old-char new-char &optional noundo -@cindex replace characters -This function replaces all occurrences of the character @var{old-char} -with the character @var{new-char} in the region of the current buffer -defined by @var{start} and @var{end}. - -@cindex undo avoidance -If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does -not record the change for undo and does not mark the buffer as modified. -This was useful for controlling the old selective display feature -(@pxref{Selective Display}). - -@code{subst-char-in-region} does not move point and returns -@code{nil}. - -@example -@group ----------- Buffer: foo ---------- -This is the contents of the buffer before. ----------- Buffer: foo ---------- -@end group - -@group -(subst-char-in-region 1 20 ?i ?X) - @result{} nil - ----------- Buffer: foo ---------- -ThXs Xs the contents of the buffer before. ----------- Buffer: foo ---------- -@end group -@end example -@end defun - -@deffn Command translate-region start end table -This function applies a translation table to the characters in the -buffer between positions @var{start} and @var{end}. - -The translation table @var{table} is a string or a char-table; -@code{(aref @var{table} @var{ochar})} gives the translated character -corresponding to @var{ochar}. If @var{table} is a string, any -characters with codes larger than the length of @var{table} are not -altered by the translation. - -The return value of @code{translate-region} is the number of -characters that were actually changed by the translation. This does -not count characters that were mapped into themselves in the -translation table. -@end deffn - -@node Registers -@section Registers -@cindex registers - - A register is a sort of variable used in Emacs editing that can hold a -variety of different kinds of values. Each register is named by a -single character. All @acronym{ASCII} characters and their meta variants -(but with the exception of @kbd{C-g}) can be used to name registers. -Thus, there are 255 possible registers. A register is designated in -Emacs Lisp by the character that is its name. - -@defvar register-alist -This variable is an alist of elements of the form @code{(@var{name} . -@var{contents})}. Normally, there is one element for each Emacs -register that has been used. - -The object @var{name} is a character (an integer) identifying the -register. -@end defvar - - The @var{contents} of a register can have several possible types: - -@table @asis -@item a number -A number stands for itself. If @code{insert-register} finds a number -in the register, it converts the number to decimal. - -@item a marker -A marker represents a buffer position to jump to. - -@item a string -A string is text saved in the register. - -@item a rectangle -A rectangle is represented by a list of strings. - -@item @code{(@var{window-configuration} @var{position})} -This represents a window configuration to restore in one frame, and a -position to jump to in the current buffer. - -@c FIXME: Mention frameset here. -@item @code{(@var{frame-configuration} @var{position})} -This represents a frame configuration to restore, and a position -to jump to in the current buffer. - -@item (file @var{filename}) -This represents a file to visit; jumping to this value visits file -@var{filename}. - -@item (file-query @var{filename} @var{position}) -This represents a file to visit and a position in it; jumping to this -value visits file @var{filename} and goes to buffer position -@var{position}. Restoring this type of position asks the user for -confirmation first. -@end table - - The functions in this section return unpredictable values unless -otherwise stated. - -@defun get-register reg -This function returns the contents of the register -@var{reg}, or @code{nil} if it has no contents. -@end defun - -@defun set-register reg value -This function sets the contents of register @var{reg} to @var{value}. -A register can be set to any value, but the other register functions -expect only certain data types. The return value is @var{value}. -@end defun - -@deffn Command view-register reg -This command displays what is contained in register @var{reg}. -@end deffn - -@deffn Command insert-register reg &optional beforep -This command inserts contents of register @var{reg} into the current -buffer. - -Normally, this command puts point before the inserted text, and the -mark after it. However, if the optional second argument @var{beforep} -is non-@code{nil}, it puts the mark before and point after. -You can pass a non-@code{nil} second argument @var{beforep} to this -function interactively by supplying any prefix argument. - -If the register contains a rectangle, then the rectangle is inserted -with its upper left corner at point. This means that text is inserted -in the current line and underneath it on successive lines. - -If the register contains something other than saved text (a string) or -a rectangle (a list), currently useless things happen. This may be -changed in the future. -@end deffn - -@defun register-read-with-preview prompt -@cindex register preview -This function reads and returns a register name, prompting with -@var{prompt} and possibly showing a preview of the existing registers -and their contents. The preview is shown in a temporary window, after -the delay specified by the user option @code{register-preview-delay}, -if its value and @code{register-alist} are both non-@code{nil}. The -preview is also shown if the user requests help (e.g., by typing the -help character). We recommend that all interactive commands which -read register names use this function. -@end defun - -@node Transposition -@section Transposition of Text - - This function can be used to transpose stretches of text: - -@defun transpose-regions start1 end1 start2 end2 &optional leave-markers -This function exchanges two nonoverlapping portions of the buffer. -Arguments @var{start1} and @var{end1} specify the bounds of one portion -and arguments @var{start2} and @var{end2} specify the bounds of the -other portion. - -Normally, @code{transpose-regions} relocates markers with the transposed -text; a marker previously positioned within one of the two transposed -portions moves along with that portion, thus remaining between the same -two characters in their new position. However, if @var{leave-markers} -is non-@code{nil}, @code{transpose-regions} does not do this---it leaves -all markers unrelocated. -@end defun - -@node Decompression -@section Dealing With Compressed Data - -When @code{auto-compression-mode} is enabled, Emacs automatically -uncompresses compressed files when you visit them, and automatically -recompresses them if you alter and save them. @xref{Compressed -Files,,, emacs, The GNU Emacs Manual}. - -The above feature works by calling an external executable (e.g., -@command{gzip}). Emacs can also be compiled with support for built-in -decompression using the zlib library, which is faster than calling an -external program. - -@defun zlib-available-p -This function returns non-@code{nil} if built-in zlib decompression is -available. -@end defun - -@defun zlib-decompress-region start end -This function decompresses the region between @var{start} and -@var{end}, using built-in zlib decompression. The region should -contain data that were compressed with gzip or zlib. On success, the -function replaces the contents of the region with the decompressed -data. On failure, the function leaves the region unchanged and -returns @code{nil}. This function can be called only in unibyte -buffers. -@end defun - - -@node Base 64 -@section Base 64 Encoding -@cindex base 64 encoding - - Base 64 code is used in email to encode a sequence of 8-bit bytes as -a longer sequence of @acronym{ASCII} graphic characters. It is defined in -Internet RFC@footnote{ -An RFC, an acronym for @dfn{Request for Comments}, is a numbered -Internet informational document describing a standard. RFCs are -usually written by technical experts acting on their own initiative, -and are traditionally written in a pragmatic, experience-driven -manner. -}2045. This section describes the functions for -converting to and from this code. - -@deffn Command base64-encode-region beg end &optional no-line-break -This function converts the region from @var{beg} to @var{end} into base -64 code. It returns the length of the encoded text. An error is -signaled if a character in the region is multibyte, i.e., in a -multibyte buffer the region must contain only characters from the -charsets @code{ascii}, @code{eight-bit-control} and -@code{eight-bit-graphic}. - -Normally, this function inserts newline characters into the encoded -text, to avoid overlong lines. However, if the optional argument -@var{no-line-break} is non-@code{nil}, these newlines are not added, so -the output is just one long line. -@end deffn - -@defun base64-encode-string string &optional no-line-break -This function converts the string @var{string} into base 64 code. It -returns a string containing the encoded text. As for -@code{base64-encode-region}, an error is signaled if a character in the -string is multibyte. - -Normally, this function inserts newline characters into the encoded -text, to avoid overlong lines. However, if the optional argument -@var{no-line-break} is non-@code{nil}, these newlines are not added, so -the result string is just one long line. -@end defun - -@deffn Command base64-decode-region beg end -This function converts the region from @var{beg} to @var{end} from base -64 code into the corresponding decoded text. It returns the length of -the decoded text. - -The decoding functions ignore newline characters in the encoded text. -@end deffn - -@defun base64-decode-string string -This function converts the string @var{string} from base 64 code into -the corresponding decoded text. It returns a unibyte string containing the -decoded text. - -The decoding functions ignore newline characters in the encoded text. -@end defun - -@node Checksum/Hash -@section Checksum/Hash -@cindex MD5 checksum -@cindex SHA hash -@cindex hash, cryptographic -@cindex cryptographic hash - - Emacs has built-in support for computing @dfn{cryptographic hashes}. -A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint'' -of a piece of data (e.g., a block of text) which can be used to check -that you have an unaltered copy of that data. - -@cindex message digest - Emacs supports several common cryptographic hash algorithms: MD5, -SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the -oldest of these algorithms, and is commonly used in @dfn{message -digests} to check the integrity of messages transmitted over a -network. MD5 is not ``collision resistant'' (i.e., it is possible to -deliberately design different pieces of data which have the same MD5 -hash), so you should not used it for anything security-related. A -similar theoretical weakness also exists in SHA-1. Therefore, for -security-related applications you should use the other hash types, -such as SHA-2. - -@defun secure-hash algorithm object &optional start end binary -This function returns a hash for @var{object}. The argument -@var{algorithm} is a symbol stating which hash to compute: one of -@code{md5}, @code{sha1}, @code{sha224}, @code{sha256}, @code{sha384} -or @code{sha512}. The argument @var{object} should be a buffer or a -string. - -The optional arguments @var{start} and @var{end} are character -positions specifying the portion of @var{object} to compute the -message digest for. If they are @code{nil} or omitted, the hash is -computed for the whole of @var{object}. - -If the argument @var{binary} is omitted or @code{nil}, the function -returns the @dfn{text form} of the hash, as an ordinary Lisp string. -If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary -form}, as a sequence of bytes stored in a unibyte string. - -This function does not compute the hash directly from the internal -representation of @var{object}'s text (@pxref{Text Representations}). -Instead, it encodes the text using a coding system (@pxref{Coding -Systems}), and computes the hash from that encoded text. If -@var{object} is a buffer, the coding system used is the one which -would be chosen by default for writing the text into a file. If -@var{object} is a string, the user's preferred coding system is used -(@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}). -@end defun - -@defun md5 object &optional start end coding-system noerror -This function returns an MD5 hash. It is semi-obsolete, since for -most purposes it is equivalent to calling @code{secure-hash} with -@code{md5} as the @var{algorithm} argument. The @var{object}, -@var{start} and @var{end} arguments have the same meanings as in -@code{secure-hash}. - -If @var{coding-system} is non-@code{nil}, it specifies a coding system -to use to encode the text; if omitted or @code{nil}, the default -coding system is used, like in @code{secure-hash}. - -Normally, @code{md5} signals an error if the text can't be encoded -using the specified or chosen coding system. However, if -@var{noerror} is non-@code{nil}, it silently uses @code{raw-text} -coding instead. -@end defun - -@node Parsing HTML/XML -@section Parsing HTML and XML -@cindex parsing html - -When Emacs is compiled with libxml2 support, the following functions -are available to parse HTML or XML text into Lisp object trees. - -@defun libxml-parse-html-region start end &optional base-url -This function parses the text between @var{start} and @var{end} as -HTML, and returns a list representing the HTML @dfn{parse tree}. It -attempts to handle ``real world'' HTML by robustly coping with syntax -mistakes. - -The optional argument @var{base-url}, if non-@code{nil}, should be a -string specifying the base URL for relative URLs occurring in links. - -In the parse tree, each HTML node is represented by a list in which -the first element is a symbol representing the node name, the second -element is an alist of node attributes, and the remaining elements are -the subnodes. - -The following example demonstrates this. Given this (malformed) HTML -document: - -@example -

Foo
Yes -@end example - -@noindent -A call to @code{libxml-parse-html-region} returns this: - -@example -(html () - (head ()) - (body ((width . "101")) - (div ((class . "thing")) - "Foo" - (div () - "Yes")))) -@end example -@end defun - -@cindex rendering html -@defun shr-insert-document dom -This function renders the parsed HTML in @var{dom} into the current -buffer. The argument @var{dom} should be a list as generated by -@code{libxml-parse-html-region}. This function is, e.g., used by -@ref{Top, EWW,, eww, The Emacs Web Wowser Manual}. -@end defun - -@cindex parsing xml -@defun libxml-parse-xml-region start end &optional base-url -This function is the same as @code{libxml-parse-html-region}, except -that it parses the text as XML rather than HTML (so it is stricter -about syntax). -@end defun - -@node Atomic Changes -@section Atomic Change Groups -@cindex atomic changes - - In database terminology, an @dfn{atomic} change is an indivisible -change---it can succeed entirely or it can fail entirely, but it -cannot partly succeed. A Lisp program can make a series of changes to -one or several buffers as an @dfn{atomic change group}, meaning that -either the entire series of changes will be installed in their buffers -or, in case of an error, none of them will be. - - To do this for one buffer, the one already current, simply write a -call to @code{atomic-change-group} around the code that makes the -changes, like this: - -@example -(atomic-change-group - (insert foo) - (delete-region x y)) -@end example - -@noindent -If an error (or other nonlocal exit) occurs inside the body of -@code{atomic-change-group}, it unmakes all the changes in that buffer -that were during the execution of the body. This kind of change group -has no effect on any other buffers---any such changes remain. - - If you need something more sophisticated, such as to make changes in -various buffers constitute one atomic group, you must directly call -lower-level functions that @code{atomic-change-group} uses. - -@defun prepare-change-group &optional buffer -This function sets up a change group for buffer @var{buffer}, which -defaults to the current buffer. It returns a ``handle'' that -represents the change group. You must use this handle to activate the -change group and subsequently to finish it. -@end defun - - To use the change group, you must @dfn{activate} it. You must do -this before making any changes in the text of @var{buffer}. - -@defun activate-change-group handle -This function activates the change group that @var{handle} designates. -@end defun - - After you activate the change group, any changes you make in that -buffer become part of it. Once you have made all the desired changes -in the buffer, you must @dfn{finish} the change group. There are two -ways to do this: you can either accept (and finalize) all the changes, -or cancel them all. - -@defun accept-change-group handle -This function accepts all the changes in the change group specified by -@var{handle}, making them final. -@end defun - -@defun cancel-change-group handle -This function cancels and undoes all the changes in the change group -specified by @var{handle}. -@end defun - - Your code should use @code{unwind-protect} to make sure the group is -always finished. The call to @code{activate-change-group} should be -inside the @code{unwind-protect}, in case the user types @kbd{C-g} -just after it runs. (This is one reason why -@code{prepare-change-group} and @code{activate-change-group} are -separate functions, because normally you would call -@code{prepare-change-group} before the start of that -@code{unwind-protect}.) Once you finish the group, don't use the -handle again---in particular, don't try to finish the same group -twice. - - To make a multibuffer change group, call @code{prepare-change-group} -once for each buffer you want to cover, then use @code{nconc} to -combine the returned values, like this: - -@example -(nconc (prepare-change-group buffer-1) - (prepare-change-group buffer-2)) -@end example - -You can then activate the multibuffer change group with a single call -to @code{activate-change-group}, and finish it with a single call to -@code{accept-change-group} or @code{cancel-change-group}. - - Nested use of several change groups for the same buffer works as you -would expect. Non-nested use of change groups for the same buffer -will get Emacs confused, so don't let it happen; the first change -group you start for any given buffer should be the last one finished. - -@node Change Hooks -@section Change Hooks -@cindex change hooks -@cindex hooks for text changes - - These hook variables let you arrange to take notice of all changes in -all buffers (or in a particular buffer, if you make them buffer-local). -See also @ref{Special Properties}, for how to detect changes to specific -parts of the text. - - The functions you use in these hooks should save and restore the match -data if they do anything that uses regular expressions; otherwise, they -will interfere in bizarre ways with the editing operations that call -them. - -@defvar before-change-functions -This variable holds a list of functions to call before any buffer -modification. Each function gets two arguments, the beginning and end -of the region that is about to change, represented as integers. The -buffer that is about to change is always the current buffer. -@end defvar - -@defvar after-change-functions -This variable holds a list of functions to call after any buffer -modification. Each function receives three arguments: the beginning -and end of the region just changed, and the length of the text that -existed before the change. All three arguments are integers. The -buffer that has been changed is always the current buffer. - -The length of the old text is the difference between the buffer -positions before and after that text as it was before the change. As -for the changed text, its length is simply the difference between the -first two arguments. -@end defvar - - Output of messages into the @file{*Messages*} buffer does not -call these functions. - -@defmac combine-after-change-calls body@dots{} -The macro executes @var{body} normally, but arranges to call the -after-change functions just once for a series of several changes---if -that seems safe. - -If a program makes several text changes in the same area of the buffer, -using the macro @code{combine-after-change-calls} around that part of -the program can make it run considerably faster when after-change hooks -are in use. When the after-change hooks are ultimately called, the -arguments specify a portion of the buffer including all of the changes -made within the @code{combine-after-change-calls} body. - -@strong{Warning:} You must not alter the values of -@code{after-change-functions} within -the body of a @code{combine-after-change-calls} form. - -@strong{Warning:} if the changes you combine occur in widely scattered -parts of the buffer, this will still work, but it is not advisable, -because it may lead to inefficient behavior for some change hook -functions. -@end defmac - -@defvar first-change-hook -This variable is a normal hook that is run whenever a buffer is changed -that was previously in the unmodified state. -@end defvar - -@defvar inhibit-modification-hooks -If this variable is non-@code{nil}, all of the change hooks are -disabled; none of them run. This affects all the hook variables -described above in this section, as well as the hooks attached to -certain special text properties (@pxref{Special Properties}) and overlay -properties (@pxref{Overlay Properties}). - -Also, this variable is bound to non-@code{nil} while running those -same hook variables, so that by default modifying the buffer from -a modification hook does not cause other modification hooks to be run. -If you do want modification hooks to be run in a particular piece of -code that is itself run from a modification hook, then rebind locally -@code{inhibit-modification-hooks} to @code{nil}. -@end defvar diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi deleted file mode 100644 index d8b906d3bfe..00000000000 --- a/doc/lispref/tips.texi +++ /dev/null @@ -1,1076 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Tips -@appendix Tips and Conventions -@cindex tips for writing Lisp -@cindex standards of coding style -@cindex coding standards - - This chapter describes no additional features of Emacs Lisp. Instead -it gives advice on making effective use of the features described in the -previous chapters, and describes conventions Emacs Lisp programmers -should follow. - - You can automatically check some of the conventions described below by -running the command @kbd{M-x checkdoc RET} when visiting a Lisp file. -It cannot check all of the conventions, and not all the warnings it -gives necessarily correspond to problems, but it is worth examining them -all. - -@menu -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. -@end menu - -@node Coding Conventions -@section Emacs Lisp Coding Conventions - -@cindex coding conventions in Emacs Lisp - Here are conventions that you should follow when writing Emacs Lisp -code intended for widespread use: - -@itemize @bullet -@item -Simply loading a package should not change Emacs's editing behavior. -Include a command or commands to enable and disable the feature, -or to invoke it. - -This convention is mandatory for any file that includes custom -definitions. If fixing such a file to follow this convention requires -an incompatible change, go ahead and make the incompatible change; -don't postpone it. - -@item -You should choose a short word to distinguish your program from other -Lisp programs. The names of all global symbols in your program, that -is the names of variables, constants, and functions, should begin with -that chosen prefix. Separate the prefix from the rest of the name -with a hyphen, @samp{-}. This practice helps avoid name conflicts, -since all global variables in Emacs Lisp share the same name space, -and all functions share another name space@footnote{The benefits of a -Common Lisp-style package system are considered not to outweigh the -costs.}. Use two hyphens to separate prefix and name if the symbol is -not meant to be used by other packages. - -Occasionally, for a command name intended for users to use, it is more -convenient if some words come before the package's name prefix. And -constructs that define functions, variables, etc., work better if they -start with @samp{defun} or @samp{defvar}, so put the name prefix later -on in the name. - -This recommendation applies even to names for traditional Lisp -primitives that are not primitives in Emacs Lisp---such as -@code{copy-list}. Believe it or not, there is more than one plausible -way to define @code{copy-list}. Play it safe; append your name prefix -to produce a name like @code{foo-copy-list} or @code{mylib-copy-list} -instead. - -If you write a function that you think ought to be added to Emacs under -a certain name, such as @code{twiddle-files}, don't call it by that name -in your program. Call it @code{mylib-twiddle-files} in your program, -and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add -it to Emacs. If and when we do, we can change the name easily enough. - -If one prefix is insufficient, your package can use two or three -alternative common prefixes, so long as they make sense. - -@item -Put a call to @code{provide} at the end of each separate Lisp file. -@xref{Named Features}. - -@item -If a file requires certain other Lisp programs to be loaded -beforehand, then the comments at the beginning of the file should say -so. Also, use @code{require} to make sure they are loaded. -@xref{Named Features}. - -@item -If a file @var{foo} uses a macro defined in another file @var{bar}, -but does not use any functions or variables defined in @var{bar}, then -@var{foo} should contain the following expression: - -@example -(eval-when-compile (require '@var{bar})) -@end example - -@noindent -This tells Emacs to load @var{bar} just before byte-compiling -@var{foo}, so that the macro definition is available during -compilation. Using @code{eval-when-compile} avoids loading @var{bar} -when the compiled version of @var{foo} is @emph{used}. It should be -called before the first use of the macro in the file. @xref{Compiling -Macros}. - -@item -Avoid loading additional libraries at run time unless they are really -needed. If your file simply cannot work without some other library, -then just @code{require} that library at the top-level and be done -with it. But if your file contains several independent features, and -only one or two require the extra library, then consider putting -@code{require} statements inside the relevant functions rather than at -the top-level. Or use @code{autoload} statements to load the extra -library when needed. This way people who don't use those aspects of -your file do not need to load the extra library. - -@item -If you need Common Lisp extensions, use the @code{cl-lib} library -rather than the old @code{cl} library. The latter does not -use a clean namespace (i.e., its definitions do not -start with a @samp{cl-} prefix). If your package loads @code{cl} at -run time, that could cause name clashes for users who don't use that -package. - -There is no problem with using the @code{cl} package at @emph{compile} -time, with @code{(eval-when-compile (require 'cl))}. That's -sufficient for using the macros in the @code{cl} package, because the -compiler expands them before generating the byte-code. It is still -better to use the more modern @code{cl-lib} in this case, though. - -@item -When defining a major mode, please follow the major mode -conventions. @xref{Major Mode Conventions}. - -@item -When defining a minor mode, please follow the minor mode -conventions. @xref{Minor Mode Conventions}. - -@item -If the purpose of a function is to tell you whether a certain -condition is true or false, give the function a name that ends in -@samp{p} (which stands for ``predicate''). If the name is one word, -add just @samp{p}; if the name is multiple words, add @samp{-p}. -Examples are @code{framep} and @code{frame-live-p}. - -@item -If the purpose of a variable is to store a single function, give it a -name that ends in @samp{-function}. If the purpose of a variable is -to store a list of functions (i.e., the variable is a hook), please -follow the naming conventions for hooks. @xref{Hooks}. - -@item -@cindex unloading packages, preparing for -If loading the file adds functions to hooks, define a function -@code{@var{feature}-unload-hook}, where @var{feature} is the name of -the feature the package provides, and make it undo any such changes. -Using @code{unload-feature} to unload the file will run this function. -@xref{Unloading}. - -@item -It is a bad idea to define aliases for the Emacs primitives. Normally -you should use the standard names instead. The case where an alias -may be useful is where it facilitates backwards compatibility or -portability. - -@item -If a package needs to define an alias or a new function for -compatibility with some other version of Emacs, name it with the package -prefix, not with the raw name with which it occurs in the other version. -Here is an example from Gnus, which provides many examples of such -compatibility issues. - -@example -(defalias 'gnus-point-at-bol - (if (fboundp 'point-at-bol) - 'point-at-bol - 'line-beginning-position)) -@end example - -@item -Redefining or advising an Emacs primitive is a bad idea. It may do -the right thing for a particular program, but there is no telling what -other programs might break as a result. - -@item -It is likewise a bad idea for one Lisp package to advise a function in -another Lisp package (@pxref{Advising Functions}). - -@item -Avoid using @code{eval-after-load} in libraries and packages -(@pxref{Hooks for Loading}). This feature is meant for personal -customizations; using it in a Lisp program is unclean, because it -modifies the behavior of another Lisp file in a way that's not visible -in that file. This is an obstacle for debugging, much like advising a -function in the other package. - -@item -If a file does replace any of the standard functions or library -programs of Emacs, prominent comments at the beginning of the file -should say which functions are replaced, and how the behavior of the -replacements differs from that of the originals. - -@item -Constructs that define a function or variable should be macros, -not functions, and their names should start with @samp{define-}. -The macro should receive the name to be -defined as the first argument. That will help various tools find the -definition automatically. Avoid constructing the names in the macro -itself, since that would confuse these tools. - -@item -In some other systems there is a convention of choosing variable names -that begin and end with @samp{*}. We don't use that convention in Emacs -Lisp, so please don't use it in your programs. (Emacs uses such names -only for special-purpose buffers.) People will find Emacs more -coherent if all libraries use the same conventions. - -@item -The default file coding system for Emacs Lisp source files is UTF-8 -(@pxref{Text Representations}). In the rare event that your program -contains characters which are @emph{not} in UTF-8, you should specify -an appropriate coding system in the source file's @samp{-*-} line or -local variables list. @xref{File Variables, , Local Variables in -Files, emacs, The GNU Emacs Manual}. - -@item -Indent the file using the default indentation parameters. - -@item -Don't make a habit of putting close-parentheses on lines by -themselves; Lisp programmers find this disconcerting. - -@item -Please put a copyright notice and copying permission notice on the -file if you distribute copies. @xref{Library Headers}. - -@end itemize - -@node Key Binding Conventions -@section Key Binding Conventions -@cindex key binding, conventions for - -@itemize @bullet -@item -@cindex mouse-2 -@cindex references, following -Many special major modes, like Dired, Info, Compilation, and Occur, -are designed to handle read-only text that contains @dfn{hyper-links}. -Such a major mode should redefine @kbd{mouse-2} and @key{RET} to -follow the links. It should also set up a @code{follow-link} -condition, so that the link obeys @code{mouse-1-click-follows-link}. -@xref{Clickable Text}. @xref{Buttons}, for an easy method of -implementing such clickable links. - -@item -@cindex reserved keys -@cindex keys, reserved -Don't define @kbd{C-c @var{letter}} as a key in Lisp programs. -Sequences consisting of @kbd{C-c} and a letter (either upper or lower -case) are reserved for users; they are the @strong{only} sequences -reserved for users, so do not block them. - -Changing all the Emacs major modes to respect this convention was a -lot of work; abandoning this convention would make that work go to -waste, and inconvenience users. Please comply with it. - -@item -Function keys @key{F5} through @key{F9} without modifier keys are -also reserved for users to define. - -@item -Sequences consisting of @kbd{C-c} followed by a control character or a -digit are reserved for major modes. - -@item -Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}}, -@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes. - -@item -Sequences consisting of @kbd{C-c} followed by any other punctuation -character are allocated for minor modes. Using them in a major mode is -not absolutely prohibited, but if you do that, the major mode binding -may be shadowed from time to time by minor modes. - -@item -Don't bind @kbd{C-h} following any prefix character (including -@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically -available as a help character for listing the subcommands of the -prefix character. - -@item -Don't bind a key sequence ending in @key{ESC} except following another -@key{ESC}. (That is, it is OK to bind a sequence ending in -@kbd{@key{ESC} @key{ESC}}.) - -The reason for this rule is that a non-prefix binding for @key{ESC} in -any context prevents recognition of escape sequences as function keys in -that context. - -@item -Similarly, don't bind a key sequence ending in @key{C-g}, since that -is commonly used to cancel a key sequence. - -@item -Anything that acts like a temporary mode or state that the user can -enter and leave should define @kbd{@key{ESC} @key{ESC}} or -@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape. - -For a state that accepts ordinary Emacs commands, or more generally any -kind of state in which @key{ESC} followed by a function key or arrow key -is potentially meaningful, then you must not define @kbd{@key{ESC} -@key{ESC}}, since that would preclude recognizing an escape sequence -after @key{ESC}. In these states, you should define @kbd{@key{ESC} -@key{ESC} @key{ESC}} as the way to escape. Otherwise, define -@kbd{@key{ESC} @key{ESC}} instead. -@end itemize - -@node Programming Tips -@section Emacs Programming Tips -@cindex programming conventions - - Following these conventions will make your program fit better -into Emacs when it runs. - -@itemize @bullet -@item -Don't use @code{next-line} or @code{previous-line} in programs; nearly -always, @code{forward-line} is more convenient as well as more -predictable and robust. @xref{Text Lines}. - -@item -Don't call functions that set the mark, unless setting the mark is one -of the intended features of your program. The mark is a user-level -feature, so it is incorrect to change the mark except to supply a value -for the user's benefit. @xref{The Mark}. - -In particular, don't use any of these functions: - -@itemize @bullet -@item -@code{beginning-of-buffer}, @code{end-of-buffer} -@item -@code{replace-string}, @code{replace-regexp} -@item -@code{insert-file}, @code{insert-buffer} -@end itemize - -If you just want to move point, or replace a certain string, or insert -a file or buffer's contents, without any of the other features -intended for interactive users, you can replace these functions with -one or two lines of simple Lisp code. - -@item -Use lists rather than vectors, except when there is a particular reason -to use a vector. Lisp has more facilities for manipulating lists than -for vectors, and working with lists is usually more convenient. - -Vectors are advantageous for tables that are substantial in size and are -accessed in random order (not searched front to back), provided there is -no need to insert or delete elements (only lists allow that). - -@item -The recommended way to show a message in the echo area is with -the @code{message} function, not @code{princ}. @xref{The Echo Area}. - -@item -When you encounter an error condition, call the function @code{error} -(or @code{signal}). The function @code{error} does not return. -@xref{Signaling Errors}. - -Don't use @code{message}, @code{throw}, @code{sleep-for}, or -@code{beep} to report errors. - -@item -An error message should start with a capital letter but should not end -with a period. - -@item -A question asked in the minibuffer with @code{yes-or-no-p} or -@code{y-or-n-p} should start with a capital letter and end with -@samp{? }. - -@item -When you mention a default value in a minibuffer prompt, -put it and the word @samp{default} inside parentheses. -It should look like this: - -@example -Enter the answer (default 42): -@end example - -@item -In @code{interactive}, if you use a Lisp expression to produce a list -of arguments, don't try to provide the ``correct'' default values for -region or position arguments. Instead, provide @code{nil} for those -arguments if they were not specified, and have the function body -compute the default value when the argument is @code{nil}. For -instance, write this: - -@example -(defun foo (pos) - (interactive - (list (if @var{specified} @var{specified-pos}))) - (unless pos (setq pos @var{default-pos})) - ...) -@end example - -@noindent -rather than this: - -@example -(defun foo (pos) - (interactive - (list (if @var{specified} @var{specified-pos} - @var{default-pos}))) - ...) -@end example - -@noindent -This is so that repetition of the command will recompute -these defaults based on the current circumstances. - -You do not need to take such precautions when you use interactive -specs @samp{d}, @samp{m} and @samp{r}, because they make special -arrangements to recompute the argument values on repetition of the -command. - -@item -Many commands that take a long time to execute display a message that -says something like @samp{Operating...} when they start, and change it -to @samp{Operating...done} when they finish. Please keep the style of -these messages uniform: @emph{no} space around the ellipsis, and -@emph{no} period after @samp{done}. @xref{Progress}, for an easy way -to generate such messages. - -@item -Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} -command does: use a new local keymap that contains a command defined -to switch back to the old local keymap. Or simply switch to another -buffer and let the user switch back at will. @xref{Recursive Editing}. -@end itemize - -@node Compilation Tips -@section Tips for Making Compiled Code Fast -@cindex execution speed -@cindex speedups - - Here are ways of improving the execution speed of byte-compiled -Lisp programs. - -@itemize @bullet -@item -Profile your program, to find out where the time is being spent. -@xref{Profiling}. - -@item -Use iteration rather than recursion whenever possible. -Function calls are slow in Emacs Lisp even when a compiled function -is calling another compiled function. - -@item -Using the primitive list-searching functions @code{memq}, @code{member}, -@code{assq}, or @code{assoc} is even faster than explicit iteration. It -can be worth rearranging a data structure so that one of these primitive -search functions can be used. - -@item -Certain built-in functions are handled specially in byte-compiled code, -avoiding the need for an ordinary function call. It is a good idea to -use these functions rather than alternatives. To see whether a function -is handled specially by the compiler, examine its @code{byte-compile} -property. If the property is non-@code{nil}, then the function is -handled specially. - -For example, the following input will show you that @code{aref} is -compiled specially (@pxref{Array Functions}): - -@example -@group -(get 'aref 'byte-compile) - @result{} byte-compile-two-args -@end group -@end example - -@noindent -Note that in this case (and many others), you must first load the -@file{bytecomp} library, which defines the @code{byte-compile} property. - -@item -If calling a small function accounts for a substantial part of your -program's running time, make the function inline. This eliminates -the function call overhead. Since making a function inline reduces -the flexibility of changing the program, don't do it unless it gives -a noticeable speedup in something slow enough that users care about -the speed. @xref{Inline Functions}. -@end itemize - -@node Warning Tips -@section Tips for Avoiding Compiler Warnings -@cindex byte compiler warnings, how to avoid - -@itemize @bullet -@item -Try to avoid compiler warnings about undefined free variables, by adding -dummy @code{defvar} definitions for these variables, like this: - -@example -(defvar foo) -@end example - -Such a definition has no effect except to tell the compiler -not to warn about uses of the variable @code{foo} in this file. - -@item -Similarly, to avoid a compiler warning about an undefined function -that you know @emph{will} be defined, use a @code{declare-function} -statement (@pxref{Declaring Functions}). - -@item -If you use many functions and variables from a certain file, you can -add a @code{require} for that package to avoid compilation warnings -for them. For instance, - -@example -(eval-when-compile - (require 'foo)) -@end example - -@item -If you bind a variable in one function, and use it or set it in -another function, the compiler warns about the latter function unless -the variable has a definition. But adding a definition would be -unclean if the variable has a short name, since Lisp packages should -not define short variable names. The right thing to do is to rename -this variable to start with the name prefix used for the other -functions and variables in your package. - -@item -The last resort for avoiding a warning, when you want to do something -that is usually a mistake but you know is not a mistake in your usage, -is to put it inside @code{with-no-warnings}. @xref{Compiler Errors}. -@end itemize - -@node Documentation Tips -@section Tips for Documentation Strings -@cindex documentation strings, conventions and tips - -@findex checkdoc-minor-mode - Here are some tips and conventions for the writing of documentation -strings. You can check many of these conventions by running the command -@kbd{M-x checkdoc-minor-mode}. - -@itemize @bullet -@item -Every command, function, or variable intended for users to know about -should have a documentation string. - -@item -An internal variable or subroutine of a Lisp program might as well -have a documentation string. Documentation strings take up very -little space in a running Emacs. - -@item -Format the documentation string so that it fits in an Emacs window on an -80-column screen. It is a good idea for most lines to be no wider than -60 characters. The first line should not be wider than 67 characters -or it will look bad in the output of @code{apropos}. - -@vindex emacs-lisp-docstring-fill-column -You can fill the text if that looks good. Emacs Lisp mode fills -documentation strings to the width specified by -@code{emacs-lisp-docstring-fill-column}. However, you can sometimes -make a documentation string much more readable by adjusting its line -breaks with care. Use blank lines between sections if the -documentation string is long. - -@item -The first line of the documentation string should consist of one or two -complete sentences that stand on their own as a summary. @kbd{M-x -apropos} displays just the first line, and if that line's contents don't -stand on their own, the result looks bad. In particular, start the -first line with a capital letter and end it with a period. - -For a function, the first line should briefly answer the question, -``What does this function do?'' For a variable, the first line should -briefly answer the question, ``What does this value mean?'' - -Don't limit the documentation string to one line; use as many lines as -you need to explain the details of how to use the function or -variable. Please use complete sentences for the rest of the text too. - -@item -When the user tries to use a disabled command, Emacs displays just the -first paragraph of its documentation string---everything through the -first blank line. If you wish, you can choose which information to -include before the first blank line so as to make this display useful. - -@item -The first line should mention all the important arguments of the -function, and should mention them in the order that they are written -in a function call. If the function has many arguments, then it is -not feasible to mention them all in the first line; in that case, the -first line should mention the first few arguments, including the most -important arguments. - -@item -When a function's documentation string mentions the value of an argument -of the function, use the argument name in capital letters as if it were -a name for that value. Thus, the documentation string of the function -@code{eval} refers to its first argument as @samp{FORM}, because the -actual argument name is @code{form}: - -@example -Evaluate FORM and return its value. -@end example - -Also write metasyntactic variables in capital letters, such as when you -show the decomposition of a list or vector into subunits, some of which -may vary. @samp{KEY} and @samp{VALUE} in the following example -illustrate this practice: - -@example -The argument TABLE should be an alist whose elements -have the form (KEY . VALUE). Here, KEY is ... -@end example - -@item -Never change the case of a Lisp symbol when you mention it in a doc -string. If the symbol's name is @code{foo}, write ``foo'', not -``Foo'' (which is a different symbol). - -This might appear to contradict the policy of writing function -argument values, but there is no real contradiction; the argument -@emph{value} is not the same thing as the @emph{symbol} that the -function uses to hold the value. - -If this puts a lower-case letter at the beginning of a sentence -and that annoys you, rewrite the sentence so that the symbol -is not at the start of it. - -@item -Do not start or end a documentation string with whitespace. - -@item -@strong{Do not} indent subsequent lines of a documentation string so -that the text is lined up in the source code with the text of the first -line. This looks nice in the source code, but looks bizarre when users -view the documentation. Remember that the indentation before the -starting double-quote is not part of the string! - -@anchor{Docstring hyperlinks} -@item -@iftex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{`lambda'}. There are two exceptions: -write @code{t} and @code{nil} without single-quotes. -@end iftex -@ifnottex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{lambda}. There are two exceptions: write -t and nil without single-quotes. (In this manual, we use a different -convention, with single-quotes for all symbols.) -@end ifnottex - -@cindex hyperlinks in documentation strings -Help mode automatically creates a hyperlink when a documentation string -uses a symbol name inside single quotes, if the symbol has either a -function or a variable definition. You do not need to do anything -special to make use of this feature. However, when a symbol has both a -function definition and a variable definition, and you want to refer to -just one of them, you can specify which one by writing one of the words -@samp{variable}, @samp{option}, @samp{function}, or @samp{command}, -immediately before the symbol name. (Case makes no difference in -recognizing these indicator words.) For example, if you write - -@example -This function sets the variable `buffer-file-name'. -@end example - -@noindent -then the hyperlink will refer only to the variable documentation of -@code{buffer-file-name}, and not to its function documentation. - -If a symbol has a function definition and/or a variable definition, but -those are irrelevant to the use of the symbol that you are documenting, -you can write the words @samp{symbol} or @samp{program} before the -symbol name to prevent making any hyperlink. For example, - -@example -If the argument KIND-OF-RESULT is the symbol `list', -this function returns a list of all the objects -that satisfy the criterion. -@end example - -@noindent -does not make a hyperlink to the documentation, irrelevant here, of the -function @code{list}. - -Normally, no hyperlink is made for a variable without variable -documentation. You can force a hyperlink for such variables by -preceding them with one of the words @samp{variable} or -@samp{option}. - -Hyperlinks for faces are only made if the face name is preceded or -followed by the word @samp{face}. In that case, only the face -documentation will be shown, even if the symbol is also defined as a -variable or as a function. - -To make a hyperlink to Info documentation, write the name of the Info -node (or anchor) in single quotes, preceded by @samp{info node}, -@samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info -file name defaults to @samp{emacs}. For example, - -@smallexample -See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. -@end smallexample - -Finally, to create a hyperlink to URLs, write the URL in single -quotes, preceded by @samp{URL}. For example, - -@smallexample -The home page for the GNU project has more information (see URL -`http://www.gnu.org/'). -@end smallexample - -@item -Don't write key sequences directly in documentation strings. Instead, -use the @samp{\\[@dots{}]} construct to stand for them. For example, -instead of writing @samp{C-f}, write the construct -@samp{\\[forward-char]}. When Emacs displays the documentation string, -it substitutes whatever key is currently bound to @code{forward-char}. -(This is normally @samp{C-f}, but it may be some other character if the -user has moved key bindings.) @xref{Keys in Documentation}. - -@item -In documentation strings for a major mode, you will want to refer to the -key bindings of that mode's local map, rather than global ones. -Therefore, use the construct @samp{\\<@dots{}>} once in the -documentation string to specify which key map to use. Do this before -the first use of @samp{\\[@dots{}]}. The text inside the -@samp{\\<@dots{}>} should be the name of the variable containing the -local keymap for the major mode. - -It is not practical to use @samp{\\[@dots{}]} very many times, because -display of the documentation string will become slow. So use this to -describe the most important commands in your major mode, and then use -@samp{\\@{@dots{}@}} to display the rest of the mode's keymap. - -@item -For consistency, phrase the verb in the first sentence of a function's -documentation string as an imperative---for instance, use ``Return the -cons of A and B.@:'' in preference to ``Returns the cons of A and B@.'' -Usually it looks good to do likewise for the rest of the first -paragraph. Subsequent paragraphs usually look better if each sentence -is indicative and has a proper subject. - -@item -The documentation string for a function that is a yes-or-no predicate -should start with words such as ``Return t if'', to indicate -explicitly what constitutes ``truth''. The word ``return'' avoids -starting the sentence with lower-case ``t'', which could be somewhat -distracting. - -@item -If a line in a documentation string begins with an open-parenthesis, -write a backslash before the open-parenthesis, like this: - -@example -The argument FOO can be either a number -\(a buffer position) or a string (a file name). -@end example - -This prevents the open-parenthesis from being treated as the start of a -defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). - -@item -Write documentation strings in the active voice, not the passive, and in -the present tense, not the future. For instance, use ``Return a list -containing A and B.@:'' instead of ``A list containing A and B will be -returned.'' - -@item -Avoid using the word ``cause'' (or its equivalents) unnecessarily. -Instead of, ``Cause Emacs to display text in boldface'', write just -``Display text in boldface''. - -@item -Avoid using ``iff'' (a mathematics term meaning ``if and only if''), -since many people are unfamiliar with it and mistake it for a typo. In -most cases, the meaning is clear with just ``if''. Otherwise, try to -find an alternate phrasing that conveys the meaning. - -@item -When a command is meaningful only in a certain mode or situation, -do mention that in the documentation string. For example, -the documentation of @code{dired-find-file} is: - -@example -In Dired, visit the file or directory named on this line. -@end example - -@item -When you define a variable that represents an option users might want -to set, use @code{defcustom}. @xref{Defining Variables}. - -@item -The documentation string for a variable that is a yes-or-no flag should -start with words such as ``Non-nil means'', to make it clear that -all non-@code{nil} values are equivalent and indicate explicitly what -@code{nil} and non-@code{nil} mean. -@end itemize - -@node Comment Tips -@section Tips on Writing Comments -@cindex comments, Lisp convention for - - We recommend these conventions for comments: - -@table @samp -@item ; -Comments that start with a single semicolon, @samp{;}, should all be -aligned to the same column on the right of the source code. Such -comments usually explain how the code on that line does its job. -For example: - -@smallexample -@group -(setq base-version-list ; There was a base - (assoc (substring fn 0 start-vn) ; version to which - file-version-assoc-list)) ; this looks like - ; a subversion. -@end group -@end smallexample - -@item ;; -Comments that start with two semicolons, @samp{;;}, should be aligned to -the same level of indentation as the code. Such comments usually -describe the purpose of the following lines or the state of the program -at that point. For example: - -@smallexample -@group -(prog1 (setq auto-fill-function - @dots{} - @dots{} - ;; Update mode line. - (force-mode-line-update))) -@end group -@end smallexample - -We also normally use two semicolons for comments outside functions. - -@smallexample -@group -;; This Lisp code is run in Emacs when it is to operate as -;; a server for other processes. -@end group -@end smallexample - -If a function has no documentation string, it should instead have a -two-semicolon comment right before the function, explaining what the -function does and how to call it properly. Explain precisely what -each argument means and how the function interprets its possible -values. It is much better to convert such comments to documentation -strings, though. - -@item ;;; -Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. We use them -for comments which should be considered a -``heading'' by Outline minor mode. By default, comments starting with -at least three semicolons (followed by a single space and a -non-whitespace character) are considered headings, comments starting -with two or fewer are not. Historically, triple-semicolon comments have -also been used for commenting out lines within a function, but this use -is discouraged. - -When commenting out entire functions, use two semicolons. - -@item ;;;; -Comments that start with four semicolons, @samp{;;;;}, should be aligned -to the left margin and are used for headings of major sections of a -program. For example: - -@smallexample -;;;; The kill ring -@end smallexample -@end table - -@noindent -Generally speaking, the @kbd{M-;} (@code{comment-dwim}) command -automatically starts a comment of the appropriate type; or indents an -existing comment to the right place, depending on the number of -semicolons. -@xref{Comments,, Manipulating Comments, emacs, The GNU Emacs Manual}. - -@node Library Headers -@section Conventional Headers for Emacs Libraries -@cindex header comments -@cindex library header comments - - Emacs has conventions for using special comments in Lisp libraries -to divide them into sections and give information such as who wrote -them. Using a standard format for these items makes it easier for -tools (and people) to extract the relevant information. This section -explains these conventions, starting with an example: - -@smallexample -@group -;;; foo.el --- Support for the Foo programming language - -;; Copyright (C) 2010-2014 Your Name -@end group - -;; Author: Your Name -;; Maintainer: Someone Else -;; Created: 14 Jul 2010 -@group -;; Keywords: languages -;; Homepage: http://example.com/foo - -;; This file is not part of GNU Emacs. - -;; This file is free software@dots{} -@dots{} -;; along with this file. If not, see . -@end group -@end smallexample - - The very first line should have this format: - -@example -;;; @var{filename} --- @var{description} -@end example - -@noindent -The description should be contained in one line. If the file -needs a @samp{-*-} specification, put it after @var{description}. -If this would make the first line too long, use a Local Variables -section at the end of the file. - - The copyright notice usually lists your name (if you wrote the -file). If you have an employer who claims copyright on your work, you -might need to list them instead. Do not say that the copyright holder -is the Free Software Foundation (or that the file is part of GNU -Emacs) unless your file has been accepted into the Emacs distribution. -For more information on the form of copyright and license notices, see -@uref{http://www.gnu.org/licenses/gpl-howto.html, the guide on the GNU -website}. - - After the copyright notice come several @dfn{header comment} lines, -each beginning with @samp{;; @var{header-name}:}. Here is a table of -the conventional possibilities for @var{header-name}: - -@table @samp -@item Author -This line states the name and email address of at least the principal -author of the library. If there are multiple authors, list them on -continuation lines led by @code{;;} and a tab or at least two spaces. -We recommend including a contact email address, of the form -@samp{<@dots{}>}. For example: - -@smallexample -@group -;; Author: Your Name -;; Someone Else -;; Another Person -@end group -@end smallexample - -@item Maintainer -This header has the same format as the Author header. It lists the -person(s) who currently maintain(s) the file (respond to bug reports, -etc.). - -If there is no maintainer line, the person(s) in the Author field -is/are presumed to be the maintainers. Some files in Emacs use -@samp{FSF} for the maintainer. This means that the original author is -no longer responsible for the file, and that it is maintained as part -of Emacs. - -@item Created -This optional line gives the original creation date of the file, and -is for historical interest only. - -@item Version -If you wish to record version numbers for the individual Lisp program, -put them in this line. Lisp files distributed with Emacs generally do -not have a @samp{Version} header, since the version number of Emacs -itself serves the same purpose. If you are distributing a collection -of multiple files, we recommend not writing the version in every file, -but only the main one. - -@item Keywords -This line lists keywords for the @code{finder-by-keyword} help command. -Please use that command to see a list of the meaningful keywords. - -This field is how people will find your package when they're looking -for things by topic. To separate the keywords, you can use spaces, -commas, or both. - -The name of this field is unfortunate, since people often assume it is -the place to write arbitrary keywords that describe their package, -rather than just the relevant Finder keywords. - -@item Homepage -This line states the homepage of the library. - -@item Package-Version -If @samp{Version} is not suitable for use by the package manager, then -a package can define @samp{Package-Version}; it will be used instead. -This is handy if @samp{Version} is an RCS id or something else that -cannot be parsed by @code{version-to-list}. @xref{Packaging Basics}. - -@item Package-Requires -If this exists, it names packages on which the current package depends -for proper operation. @xref{Packaging Basics}. This is used by the -package manager both at download time (to ensure that a complete set -of packages is downloaded) and at activation time (to ensure that a -package is only activated if all its dependencies have been). - -Its format is a list of lists. The @code{car} of each sub-list is the -name of a package, as a symbol. The @code{cadr} of each sub-list is -the minimum acceptable version number, as a string. For instance: - -@smallexample -;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2")) -@end smallexample - -The package code automatically defines a package named @samp{emacs} -with the version number of the currently running Emacs. This can be -used to require a minimal version of Emacs for a package. -@end table - - Just about every Lisp library ought to have the @samp{Author} and -@samp{Keywords} header comment lines. Use the others if they are -appropriate. You can also put in header lines with other header -names---they have no standard meanings, so they can't do any harm. - - We use additional stylized comments to subdivide the contents of the -library file. These should be separated from anything else by blank -lines. Here is a table of them: - -@cindex commentary, in a Lisp library -@table @samp -@item ;;; Commentary: -This begins introductory comments that explain how the library works. -It should come right after the copying permissions, terminated by a -@samp{Change Log}, @samp{History} or @samp{Code} comment line. This -text is used by the Finder package, so it should make sense in that -context. - -@item ;;; Change Log: -This begins an optional log of changes to the file over time. Don't -put too much information in this section---it is better to keep the -detailed logs in a separate @file{ChangeLog} file (as Emacs does), -and/or to use a version control system. @samp{History} is an -alternative to @samp{Change Log}. - -@item ;;; Code: -This begins the actual code of the program. - -@item ;;; @var{filename} ends here -This is the @dfn{footer line}; it appears at the very end of the file. -Its purpose is to enable people to detect truncated versions of the file -from the lack of a footer line. -@end table diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt deleted file mode 100644 index f9d05126651..00000000000 --- a/doc/lispref/two-volume-cross-refs.txt +++ /dev/null @@ -1,319 +0,0 @@ -Copyright (C) 2001-2014 Free Software Foundation, Inc. -See end for copying conditions. - -Two Volume Cross References -=========================== - -12 June 2007 (karl) - -For lispref 2.9 (for Emacs 22, June 2007), I created a very ugly -Makefile, in the file two-volume.make, to encapsulate all the steps -below, without manual intervention. In theory, simply running "make -f -two-volume.make" should create a vol1.pdf and vol2.pdf with all the -niceties worked out. - -One issue not explicitly discussed below is getting page numbers right. -It's not enough to go through the whole process. You have to go through -the whole process twice -- otherwise, some index entries and/or toc -entries will be off by one. See two-volume.make for a few more comments. - -For future editions, it should suffice to update the usual things in -vol[12].texi (as well as elisp.texi). That was my hope, anyway. - - -18 March 1992 (bob) - -This enables you to create manuals in *two* volumes, with tables of -contents, cross references, and indices in each volume referring to -*both* volumes. - -The procedure is tedious. However, the resulting two volumes are -conveniently organized. Each has an index of the whole two volumes. -Each volume starts with page 1. (I don't like multi-volume works -where each volume starts with a higher page number since I find it -harder to go to the right place in the volume.) - -References to the same volume are just the page number; references to -the other volume are a volume number (in Roman numerals) preceding -the page number. - -For example, in Volume I: - - list length ......... 90 - list motion ......II:117 - -and in Volume II: - - list length ....... I:90 - list motion .........117 - -All other references and the table of contents work the same way. I -find this *very* helpful. - - -In brief: you run tex on a .texi file with - - a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file - b. redone .aux file - c. redone .fns file - - -Here are the steps in detail: - -% tex vol1.texi -% texindex vol1.?? -% tex vol1.texi - -% tex vol2.texi -% texindex vol2.?? -% tex vol2.texi - -### Create .aux files with volume numbers for other volume. - -% cp vol1.aux elisp1-aux -% cp vol2.aux elisp2-aux - -% cp vol1.aux elisp1-aux-vol-added -% cp vol2.aux elisp2-aux-vol-added - -on elisp1-aux-vol-number-added -(volume-aux-markup 1) see defun for volume-aux-markup below. -to create elisp1-aux-vol-added - -on elisp2-aux-vol-number-added -(volume-aux-markup 2) -to create elisp2-aux-vol-added - -insert elisp2-aux-vol-added into vol1.aux (append) -insert elisp1-aux-vol-added into vol2.aux (prepend) - -(so you don't have to do it again) -% cp vol1.aux elisp1-aux-ready -% cp vol2.aux elisp2-aux-ready - - -### Create .fn files with volume numbers for other volume. - -% cp vol1.fn elisp1-fn -% cp vol2.fn elisp2-fn - -% cp vol1.fn elisp1-fn-vol-number-added -% cp vol2.fn elisp2-fn-vol-number-added - -on elisp1-fn-vol-number-added -(volume-index-markup "I") -to create elisp1-fn-vol-number-added - -on elisp2-fn-vol-number-added -(volume-index-markup "II") -to create elisp2-fn-vol-number-added - -insert elisp2-fn-vol-number-added into vol1.fn: do following `cat' -insert elisp1-fn-vol-number-added into vol2.fn: do following `cat' - -% cat elisp2-fn-vol-number-added >> vol1.fn -% cat elisp1-fn-vol-number-added >> vol2.fn - -Be sure to handle special case entries by hand. -Be sure that .fn file has no blank lines. - -% texindex vol1.fn -% texindex vol2.fn - -(so you don't have to do it again) -% cp vol1.fns elisp1-fns-2vol-ready -% cp vol2.fns elisp2-fns-2vol-ready - -### Create merged .toc file with volume number headings. - -append vol2.toc to vol1.toc with following `cat' - -% cat vol1.toc vol2.toc > elisp-toc-2vol.toc - -and edit in Volume titles - -\unnumbchapentry {Volume 1}{} -\unnumbchapentry {}{} - -\unnumbchapentry {Index}{295} -\unnumbchapentry {}{} -\unnumbchapentry {Volume 2}{} -\unnumbchapentry {}{} - -If you want to put in volume numbers for TOC, then do this: -Create volume specific .toc files with volume numbers in them. - -% cp elisp-toc-2vol.toc elisp1-toc.toc -% cp elisp-toc-2vol.toc elisp2-toc.toc - -Use keyboard macro to put I: in first half of elisp1-toc.toc and -II: in first half of elisp2-toc.toc - -Copy the tocs to something you can remember more easily - -% cp elisp2-toc.toc elisp1-toc-ready.toc -% cp elisp1-toc.toc elisp2-toc-ready.toc - -Then, edit vol1.texi to input elisp1-toc-ready.toc -and vol2.texi to input elisp2-toc-ready.toc - - -### Now format the two volumes: - -% cp elisp1-aux-2vol-ready vol1.aux -% cp elisp2-aux-2vol-ready vol2.aux - -% tex vol1.texi -% tex vol2.texi - - - -For every additional run: - -### recopy aux files so the correct ones are read: -% cp elisp1-aux-2vol-ready vol1.aux -% cp elisp2-aux-2vol-ready vol2.aux - -Do not run texindex. Then proper sorted index will stay. - else do: % cp elisp2-fns-2vol-ready vol2.fns - -Do not change the .texi files; they will call the elisp-toc-2vol.toc file. - -% tex vol1.texi -% tex vol2.texi - -================================================================ - - -(defun volume-aux-markup (arg) - "Append `vol. NUMBER' to page number. -Apply to aux file that you save. -Then insert marked file into other volume's .aux file." - (interactive "sType volume number, 1 or 2: " ) - (goto-char (point-min)) - (while (search-forward "-pg" nil t) - (end-of-line 1) - (delete-backward-char 1 nil) - (insert ", vol.'tie" arg "}"))) - -(defun volume-index-markup (arg) - "Prepend `NUMBER:' to page number. Use Roman Numeral. -Apply only to unsorted index file, -Then insert marked file into other volume's unsorted index file. -Then run texindex on that file and save." - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "\\entry" nil t) - (search-forward "}{" (save-excursion (end-of-line) (point)) nil) - (insert arg ":"))) - - -================================================================ - - -The steps: - -1. Run TeX, texindex and TeX on file1. -2. Run TeX, texindex and TeX on file2. - -3. Copy both .aux files into specially named files - -4. In the case of the elisp ref manual, - - copy the *unsorted* function index files into specially named files - (no other index used in elisp ref manual) - - -5. For aux files: - - Run a function on the specially named .aux files to label each - entry according to volume. Save these files. - - i.e., convert - 'xrdef {Special-pg}{7} to 'xrdef {Special-pg}{7, vol.'tie1} - -5a.Insert each specially named .aux file into the regular .aux file of - the other volume. - -6. For index files: - - Run a function on the specially named unsorted index files to label - each entry according to volume. Save these files. - -6b.Insert each specially named marked unsorted index file into the - regular unsorted file of the other volume. Run texindex on this - -7. Insert the other volumes .toc file into the .toc, edit, and rename to - elisp-toc-2vol.toc - -7a. insert special @contents and @summarycontents defs into .texi files. - -8. Run TeX on each .texi file. - -================ - - - -Here is the discursive commentary: - -I've been running some small test files, called test1.texi and -test2.texi. As far as I can see, if we run tex on the two test files, -tex creates a .aux for each that includes the names of all the nodes -in that file. The node names are used for cross references. - -If you insert the .aux file for the second test file, test2.aux, into -the .aux file for the first test file, test1.aux, then when you next -run TeX on the first test file, test1.texi, the second volume cross -references are inserted. - -You can edit the text of the cross reference in test2.aux to include -the volume number. - -For example, you can take the following two lines from test1.texi and -insert them into test2.texi: - - 'xrdef {Special-pg}{7} - 'xrdef {Special-snt}{Section'tie1.6} - -You can re-edit this to show that the page is in volume 1: - - 'xrdef {Special-pg}{7, vol.'tie1} - 'xrdef {Special-snt}{Section'tie1.6} - -(The 'tie is a TeX special command to keep the number tied on one -line to the previous word. I don't know if it works after a period in -the "vol." but figure it is worth trying. {The ' is the @ of .aux files.} -Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the -definition for 'tie is the following: - - \def\tie{\penalty 10000\ } % Save plain tex definition of ~. - -) - -After running tex on the test2.texi file with the augmented test2.aux -file, you can see the following in the resulting DVI file: - - See Section 1.6 [Special], page 7, vol. 1 - -Note that TeX rewrites the .aux file each time TeX is run, so after -running Tex using an .aux file augmented with the .aux file from the -other volume, the new .aux file will *lack* the other volumes cross -references. Save your augmented .aux file in some other name for -another run! - - -COPYING CONDITIONS - -This file is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This file is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this file. If not, see . diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make deleted file mode 100644 index a75b26b58c7..00000000000 --- a/doc/lispref/two-volume.make +++ /dev/null @@ -1,236 +0,0 @@ -# Copyright (C) 2007-2014 Free Software Foundation, Inc. -# See end for copying conditions. - -# although it would be nice to use tex rather than pdftex to avoid -# colors, spurious warnings about names being referenced but not -# existing, etc., dvips | ps2pdf doesn't preserve the page size. -# Instead of creating a special dvips config file, put up with the warnings. -# (Note added 2012/05: for me, using texlive-2007-57, pdftex -# doesn't work for reason, but tex does.) -texinfodir=../misc -emacsdir=../emacs - -tex = TEXINPUTS=".:$(texinfodir):${emacsdir}:${TEXINPUTS}" pdftex -interaction=nonstopmode - -all: vol1.pdf vol2.pdf - -# There's probably a better way to do this, without using a temp file. -# Something like: -# tex -jobname=vol1 '\def\SETVOL1 \input{elisp.texi}' -# but I don't know what to use for "\def\SETVOL1". -tex1 = sed '/^@setfilename/a\ -@set VOL1' elisp.texi > elisp1tmp.tex && $(tex) -jobname=vol1 elisp1tmp.tex - -tex2 = sed '/^@setfilename/a\ -@set VOL2' elisp.texi > elisp2tmp.tex && $(tex) -jobname=vol2 elisp2tmp.tex - -# elisp.texi specially defines \tocreadfilename when VOL1 or VOL2 is -# set, so we can use our premade .toc's. -# -vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready - @echo -e "\f Final TeX run for volume 1..." - cp elisp1med-toc-ready elisp1-toc-ready.toc - cp elisp1med-fns-ready vol1.fns - cp elisp1med-aux-ready vol1.aux - $(tex1) -# -vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready - @echo "Final TeX run for volume 2..." - cp elisp2med-toc-ready elisp2-toc-ready.toc - cp elisp2med-fns-ready vol2.fns - cp elisp2med-aux-ready vol2.aux - $(tex2) - -# intermediate toc files. -# -# vol1 toc: volume 1, page break, volume 2 (with II: prepended). -elisp1med-toc-ready: elisp1med-init elisp2med-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - cat elisp1med-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@ -# -# vol2 toc: volume 1 (with I: prepended), page break, volume 2. -elisp2med-toc-ready: elisp1med-init elisp2med-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - cat elisp2med-toc >>$@ - - -# intermediate aux files. -# -# append vol2's fixed aux to normal vol1. -elisp1med-aux-ready: elisp2med-aux-vol-added - cat elisp1med-aux $< >$@ -# -# prepend vol1's fixed aux to vol2. -elisp2med-aux-ready: elisp1med-aux-vol-added - cat $< elisp2med-aux >$@ - -# on -pg entries, append volume number after page number. -elisp1med-aux-vol-added: elisp1med-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1med-aux >$@ -# -elisp2med-aux-vol-added: elisp2med-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@ - -# intermediate index (fns) file. -# -elisp1med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added - cat elisp2med-fn-vol-added >>vol1.fn - texindex vol1.fn - cp vol1.fns $@ -# -elisp2med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added - cat elisp1med-fn-vol-added >>vol2.fn - texindex vol2.fn - cp vol2.fns $@ - -# Insert volume number (I: or II:) into index file. -elisp1med-fn-vol-added: elisp1med-init - cp vol1.fn elisp1med-fn - sed 's/}{/}{I:/' elisp1med-fn >$@ -# -elisp2med-fn-vol-added: elisp2med-init - cp vol2.fn elisp2med-fn - sed 's/}{/}{II:/' elisp2med-fn >$@ - -# ----------------------------------------------------------------------------- -# everything above is essentially a duplicate of everything below. sorry. -# ----------------------------------------------------------------------------- - -# intermediate TeX runs. -# -# this generates what would be the final versions -- except the page -# numbers aren't right. The process of adding the I: and II: changes -# the page breaks, so a few index entries, at least are wrong. (In -# 2007, x-meta-keysym in vol.II ended up on page 374 when the index had -# it on page 375 from the initial run.) -# -# So, we start all over again, from these fns/aux/toc files. -# -elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready $(texinfodir)/texinfo.tex - @echo -e "\f Intermediate TeX run for volume 1..." - cp elisp1init-toc-ready elisp1-toc-ready.toc - cp elisp1-fns-ready vol1.fns - cp elisp1-aux-ready vol1.aux - $(tex1) - texindex vol1.?? - mv vol1.aux elisp1med-aux - mv vol1.toc elisp1med-toc -# -elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready $(texinfodir)/texinfo.tex - @echo "Final TeX run for volume 2..." - cp elisp2init-toc-ready elisp2-toc-ready.toc - cp elisp2-fns-ready vol2.fns - cp elisp2-aux-ready vol2.aux - $(tex2) - texindex vol2.?? - mv vol2.aux elisp2med-aux - mv vol2.toc elisp2med-toc - - -# initial toc files. -# -# vol1 toc: volume 1, page break, volume 2 (with II: prepended). -elisp1init-toc-ready: elisp1-init elisp2-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - cat elisp1-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@ -# -# vol2 toc: volume 1 (with I: prepended), page break, volume 2. -elisp2init-toc-ready: elisp1-init elisp2-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - cat elisp2-toc >>$@ - - -# initial aux files. -# -# append vol2's fixed aux to normal vol1. The initial runs saved -# elisp1-aux and elisp2-aux. -elisp1-aux-ready: elisp2-aux-vol-added - cat elisp1-aux $< >$@ -# -# prepend vol1's fixed aux to vol2. -elisp2-aux-ready: elisp1-aux-vol-added - cat $< elisp2-aux >$@ - -# on -pg entries, append volume number after page number. -elisp1-aux-vol-added: elisp1-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1-aux >$@ -# -elisp2-aux-vol-added: elisp2-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@ - -# initial index (fns) file. -# -# Append other volume's index entries to this one's. -# Index entries in this volume will then take precedence. -elisp1-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added - cat elisp2-fn-vol-added >>vol1.fn - texindex vol1.fn - cp vol1.fns $@ -# -elisp2-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added - cat elisp1-fn-vol-added >>vol2.fn - texindex vol2.fn - cp vol2.fns $@ - -# Insert volume number (I: or II:) into index file. -elisp1-fn-vol-added: elisp1-init - cp vol1.fn elisp1-fn - sed 's/}{/}{I:/' elisp1-fn >$@ -# -elisp2-fn-vol-added: elisp2-init - cp vol2.fn elisp2-fn - sed 's/}{/}{II:/' elisp2-fn >$@ - - -# initial TeX runs. -# -# We use the .fn, .aux, and .toc files created here in subsequent -# processing. The page numbers generated here will not be correct yet, -# but we run texindex and TeX a second time just to get them closer. -# Otherwise it might take even longer for them to converge. -# -elisp1-init: elisp.texi - @echo -e "\f Initial TeX run for volume 1..." - rm -f vol1.aux vol1.toc - $(tex1) - texindex vol1.?? - mv vol1.aux elisp1-aux - mv vol1.toc elisp1-toc - touch $@ -# -elisp2-init: elisp.texi - @echo "Initial TeX run for volume 2..." - rm -f vol2.aux vol2.toc - $(tex2) - texindex vol2.?? - mv vol2.aux elisp2-aux - mv vol2.toc elisp2-toc - touch $@ - -# COPYING CONDITIONS -# -# This file is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This file is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this file. If not, see . - diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi deleted file mode 100644 index e890dbce359..00000000000 --- a/doc/lispref/variables.texi +++ /dev/null @@ -1,2177 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Variables -@chapter Variables -@cindex variable - - A @dfn{variable} is a name used in a program to stand for a value. -In Lisp, each variable is represented by a Lisp symbol -(@pxref{Symbols}). The variable name is simply the symbol's name, and -the variable's value is stored in the symbol's value cell@footnote{To -be precise, under the default @dfn{dynamic scoping} rule, the value -cell always holds the variable's current value, but this is not the -case under the @dfn{lexical scoping} rule. @xref{Variable Scoping}, -for details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a -symbol as a variable is independent of its use as a function name. - - As previously noted in this manual, a Lisp program is represented -primarily by Lisp objects, and only secondarily as text. The textual -form of a Lisp program is given by the read syntax of the Lisp objects -that constitute the program. Hence, the textual form of a variable in -a Lisp program is written using the read syntax for the symbol -representing the variable. - -@menu -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a directory. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. -* Generalized Variables:: Extending the concept of variables. -@end menu - -@node Global Variables -@section Global Variables -@cindex global variable - - The simplest way to use a variable is @dfn{globally}. This means that -the variable has just one value at a time, and this value is in effect -(at least for the moment) throughout the Lisp system. The value remains -in effect until you specify a new one. When a new value replaces the -old one, no trace of the old value remains in the variable. - - You specify a value for a symbol with @code{setq}. For example, - -@example -(setq x '(a b)) -@end example - -@noindent -gives the variable @code{x} the value @code{(a b)}. Note that -@code{setq} is a special form (@pxref{Special Forms}); it does not -evaluate its first argument, the name of the variable, but it does -evaluate the second argument, the new value. - - Once the variable has a value, you can refer to it by using the -symbol itself as an expression. Thus, - -@example -@group -x @result{} (a b) -@end group -@end example - -@noindent -assuming the @code{setq} form shown above has already been executed. - - If you do set the same variable again, the new value replaces the old -one: - -@example -@group -x - @result{} (a b) -@end group -@group -(setq x 4) - @result{} 4 -@end group -@group -x - @result{} 4 -@end group -@end example - -@node Constant Variables -@section Variables that Never Change -@cindex @code{setting-constant} error -@cindex keyword symbol -@cindex variable with constant value -@cindex constant variables -@cindex symbol that evaluates to itself -@cindex symbol with constant value - - In Emacs Lisp, certain symbols normally evaluate to themselves. These -include @code{nil} and @code{t}, as well as any symbol whose name starts -with @samp{:} (these are called @dfn{keywords}). These symbols cannot -be rebound, nor can their values be changed. Any attempt to set or bind -@code{nil} or @code{t} signals a @code{setting-constant} error. The -same is true for a keyword (a symbol whose name starts with @samp{:}), -if it is interned in the standard obarray, except that setting such a -symbol to itself is not an error. - -@example -@group -nil @equiv{} 'nil - @result{} nil -@end group -@group -(setq nil 500) -@error{} Attempt to set constant symbol: nil -@end group -@end example - -@defun keywordp object -function returns @code{t} if @var{object} is a symbol whose name -starts with @samp{:}, interned in the standard obarray, and returns -@code{nil} otherwise. -@end defun - -These constants are fundamentally different from the ``constants'' -defined using the @code{defconst} special form (@pxref{Defining -Variables}). A @code{defconst} form serves to inform human readers -that you do not intend to change the value of a variable, but Emacs -does not raise an error if you actually change it. - -@node Local Variables -@section Local Variables -@cindex binding local variables -@cindex local variables -@cindex local binding -@cindex global binding - - Global variables have values that last until explicitly superseded -with new values. Sometimes it is useful to give a variable a -@dfn{local value}---a value that takes effect only within a certain -part of a Lisp program. When a variable has a local value, we say -that it is @dfn{locally bound} to that value, and that it is a -@dfn{local variable}. - - For example, when a function is called, its argument variables -receive local values, which are the actual arguments supplied to the -function call; these local bindings take effect within the body of the -function. To take another example, the @code{let} special form -explicitly establishes local bindings for specific variables, which -take effect within the body of the @code{let} form. - - We also speak of the @dfn{global binding}, which is where -(conceptually) the global value is kept. - -@cindex shadowing of variables - Establishing a local binding saves away the variable's previous -value (or lack of one). We say that the previous value is -@dfn{shadowed}. Both global and local values may be shadowed. If a -local binding is in effect, using @code{setq} on the local variable -stores the specified value in the local binding. When that local -binding is no longer in effect, the previously shadowed value (or lack -of one) comes back. - -@cindex current binding - A variable can have more than one local binding at a time (e.g., if -there are nested @code{let} forms that bind the variable). The -@dfn{current binding} is the local binding that is actually in effect. -It determines the value returned by evaluating the variable symbol, -and it is the binding acted on by @code{setq}. - - For most purposes, you can think of the current binding as the -``innermost'' local binding, or the global binding if there is no -local binding. To be more precise, a rule called the @dfn{scoping -rule} determines where in a program a local binding takes effect. The -default scoping rule in Emacs Lisp is called @dfn{dynamic scoping}, -which simply states that the current binding at any given point in the -execution of a program is the most recently-created binding for that -variable that still exists. For details about dynamic scoping, and an -alternative scoping rule called @dfn{lexical scoping}, @xref{Variable -Scoping}. - - The special forms @code{let} and @code{let*} exist to create local -bindings: - -@defspec let (bindings@dots{}) forms@dots{} -This special form sets up local bindings for a certain set of -variables, as specified by @var{bindings}, and then evaluates all of -the @var{forms} in textual order. Its return value is the value of -the last form in @var{forms}. - -Each of the @var{bindings} is either @w{(i) a} symbol, in which case -that symbol is locally bound to @code{nil}; or @w{(ii) a} list of the -form @code{(@var{symbol} @var{value-form})}, in which case -@var{symbol} is locally bound to the result of evaluating -@var{value-form}. If @var{value-form} is omitted, @code{nil} is used. - -All of the @var{value-form}s in @var{bindings} are evaluated in the -order they appear and @emph{before} binding any of the symbols to them. -Here is an example of this: @code{z} is bound to the old value of -@code{y}, which is 2, not the new value of @code{y}, which is 1. - -@example -@group -(setq y 2) - @result{} 2 -@end group - -@group -(let ((y 1) - (z y)) - (list y z)) - @result{} (1 2) -@end group -@end example -@end defspec - -@defspec let* (bindings@dots{}) forms@dots{} -This special form is like @code{let}, but it binds each variable right -after computing its local value, before computing the local value for -the next variable. Therefore, an expression in @var{bindings} can -refer to the preceding symbols bound in this @code{let*} form. -Compare the following example with the example above for @code{let}. - -@example -@group -(setq y 2) - @result{} 2 -@end group - -@group -(let* ((y 1) - (z y)) ; @r{Use the just-established value of @code{y}.} - (list y z)) - @result{} (1 1) -@end group -@end example -@end defspec - - Here is a complete list of the other facilities that create local -bindings: - -@itemize @bullet -@item -Function calls (@pxref{Functions}). - -@item -Macro calls (@pxref{Macros}). - -@item -@code{condition-case} (@pxref{Errors}). -@end itemize - - Variables can also have buffer-local bindings (@pxref{Buffer-Local -Variables}); a few variables have terminal-local bindings -(@pxref{Multiple Terminals}). These kinds of bindings work somewhat -like ordinary local bindings, but they are localized depending on -``where'' you are in Emacs. - -@defopt max-specpdl-size -@anchor{Definition of max-specpdl-size} -@cindex variable limit error -@cindex evaluation error -@cindex infinite recursion -This variable defines the limit on the total number of local variable -bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,, -Cleaning Up from Nonlocal Exits}) that are allowed before Emacs -signals an error (with data @code{"Variable binding depth exceeds -max-specpdl-size"}). - -This limit, with the associated error when it is exceeded, is one way -that Lisp avoids infinite recursion on an ill-defined function. -@code{max-lisp-eval-depth} provides another limit on depth of nesting. -@xref{Definition of max-lisp-eval-depth,, Eval}. - -The default value is 1300. Entry to the Lisp debugger increases the -value, if there is little room left, to make sure the debugger itself -has room to execute. -@end defopt - -@node Void Variables -@section When a Variable is ``Void'' -@cindex @code{void-variable} error -@cindex void variable - - We say that a variable is void if its symbol has an unassigned value -cell (@pxref{Symbol Components}). - - Under Emacs Lisp's default dynamic scoping rule (@pxref{Variable -Scoping}), the value cell stores the variable's current (local or -global) value. Note that an unassigned value cell is @emph{not} the -same as having @code{nil} in the value cell. The symbol @code{nil} is -a Lisp object and can be the value of a variable, just as any other -object can be; but it is still a value. If a variable is void, trying -to evaluate the variable signals a @code{void-variable} error, instead -of returning a value. - - Under the optional lexical scoping rule, the value cell only holds -the variable's global value---the value outside of any lexical binding -construct. When a variable is lexically bound, the local value is -determined by the lexical environment; hence, variables can have local -values even if their symbols' value cells are unassigned. - -@defun makunbound symbol -This function empties out the value cell of @var{symbol}, making the -variable void. It returns @var{symbol}. - -If @var{symbol} has a dynamic local binding, @code{makunbound} voids -the current binding, and this voidness lasts only as long as the local -binding is in effect. Afterwards, the previously shadowed local or -global binding is reexposed; then the variable will no longer be void, -unless the reexposed binding is void too. - -Here are some examples (assuming dynamic binding is in effect): - -@smallexample -@group -(setq x 1) ; @r{Put a value in the global binding.} - @result{} 1 -(let ((x 2)) ; @r{Locally bind it.} - (makunbound 'x) ; @r{Void the local binding.} - x) -@error{} Symbol's value as variable is void: x -@end group -@group -x ; @r{The global binding is unchanged.} - @result{} 1 - -(let ((x 2)) ; @r{Locally bind it.} - (let ((x 3)) ; @r{And again.} - (makunbound 'x) ; @r{Void the innermost-local binding.} - x)) ; @r{And refer: it's void.} -@error{} Symbol's value as variable is void: x -@end group - -@group -(let ((x 2)) - (let ((x 3)) - (makunbound 'x)) ; @r{Void inner binding, then remove it.} - x) ; @r{Now outer @code{let} binding is visible.} - @result{} 2 -@end group -@end smallexample -@end defun - -@defun boundp variable -This function returns @code{t} if @var{variable} (a symbol) is not -void, and @code{nil} if it is void. - -Here are some examples (assuming dynamic binding is in effect): - -@smallexample -@group -(boundp 'abracadabra) ; @r{Starts out void.} - @result{} nil -@end group -@group -(let ((abracadabra 5)) ; @r{Locally bind it.} - (boundp 'abracadabra)) - @result{} t -@end group -@group -(boundp 'abracadabra) ; @r{Still globally void.} - @result{} nil -@end group -@group -(setq abracadabra 5) ; @r{Make it globally nonvoid.} - @result{} 5 -@end group -@group -(boundp 'abracadabra) - @result{} t -@end group -@end smallexample -@end defun - -@node Defining Variables -@section Defining Global Variables -@cindex variable definition - - A @dfn{variable definition} is a construct that announces your -intention to use a symbol as a global variable. It uses the special -forms @code{defvar} or @code{defconst}, which are documented below. - - A variable definition serves three purposes. First, it informs -people who read the code that the symbol is @emph{intended} to be used -a certain way (as a variable). Second, it informs the Lisp system of -this, optionally supplying an initial value and a documentation -string. Third, it provides information to programming tools such as -@command{etags}, allowing them to find where the variable was defined. - - The difference between @code{defconst} and @code{defvar} is mainly a -matter of intent, serving to inform human readers of whether the value -should ever change. Emacs Lisp does not actually prevent you from -changing the value of a variable defined with @code{defconst}. One -notable difference between the two forms is that @code{defconst} -unconditionally initializes the variable, whereas @code{defvar} -initializes it only if it is originally void. - - To define a customizable variable, you should use @code{defcustom} -(which calls @code{defvar} as a subroutine). @xref{Variable -Definitions}. - -@defspec defvar symbol [value [doc-string]] -This special form defines @var{symbol} as a variable. Note that -@var{symbol} is not evaluated; the symbol to be defined should appear -explicitly in the @code{defvar} form. The variable is marked as -@dfn{special}, meaning that it should always be dynamically bound -(@pxref{Variable Scoping}). - -If @var{value} is specified, and @var{symbol} is void (i.e., it has no -dynamically bound value; @pxref{Void Variables}), then @var{value} is -evaluated and @var{symbol} is set to the result. But if @var{symbol} -is not void, @var{value} is not evaluated, and @var{symbol}'s value is -left unchanged. If @var{value} is omitted, the value of @var{symbol} -is not changed in any case. - -If @var{symbol} has a buffer-local binding in the current buffer, -@code{defvar} acts on the default value, which is buffer-independent, -rather than the buffer-local binding. It sets the default value if -the default value is void. @xref{Buffer-Local Variables}. - -If @var{symbol} is already lexically bound (e.g., if the @code{defvar} -form occurs in a @code{let} form with lexical binding enabled), then -@code{defvar} sets the dynamic value. The lexical binding remains in -effect until its binding construct exits. @xref{Variable Scoping}. - -When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in -Emacs Lisp mode (@code{eval-defun}), a special feature of -@code{eval-defun} arranges to set the variable unconditionally, without -testing whether its value is void. - -If the @var{doc-string} argument is supplied, it specifies the -documentation string for the variable (stored in the symbol's -@code{variable-documentation} property). @xref{Documentation}. - -Here are some examples. This form defines @code{foo} but does not -initialize it: - -@example -@group -(defvar foo) - @result{} foo -@end group -@end example - -This example initializes the value of @code{bar} to @code{23}, and gives -it a documentation string: - -@example -@group -(defvar bar 23 - "The normal weight of a bar.") - @result{} bar -@end group -@end example - -The @code{defvar} form returns @var{symbol}, but it is normally used -at top level in a file where its value does not matter. -@end defspec - -@cindex constant variables -@defspec defconst symbol value [doc-string] -This special form defines @var{symbol} as a value and initializes it. -It informs a person reading your code that @var{symbol} has a standard -global value, established here, that should not be changed by the user -or by other programs. Note that @var{symbol} is not evaluated; the -symbol to be defined must appear explicitly in the @code{defconst}. - -The @code{defconst} form, like @code{defvar}, marks the variable as -@dfn{special}, meaning that it should always be dynamically bound -(@pxref{Variable Scoping}). In addition, it marks the variable as -risky (@pxref{File Local Variables}). - -@code{defconst} always evaluates @var{value}, and sets the value of -@var{symbol} to the result. If @var{symbol} does have a buffer-local -binding in the current buffer, @code{defconst} sets the default value, -not the buffer-local value. (But you should not be making -buffer-local bindings for a symbol that is defined with -@code{defconst}.) - -An example of the use of @code{defconst} is Emacs's definition of -@code{float-pi}---the mathematical constant @math{pi}, which ought not -to be changed by anyone (attempts by the Indiana State Legislature -notwithstanding). As the second form illustrates, however, -@code{defconst} is only advisory. - -@example -@group -(defconst float-pi 3.141592653589793 "The value of Pi.") - @result{} float-pi -@end group -@group -(setq float-pi 3) - @result{} float-pi -@end group -@group -float-pi - @result{} 3 -@end group -@end example -@end defspec - - @strong{Warning:} If you use a @code{defconst} or @code{defvar} -special form while the variable has a local binding (made with -@code{let}, or a function argument), it sets the local binding rather -than the global binding. This is not what you usually want. To -prevent this, use these special forms at top level in a file, where -normally no local binding is in effect, and make sure to load the file -before making a local binding for the variable. - -@node Tips for Defining -@section Tips for Defining Variables Robustly - - When you define a variable whose value is a function, or a list of -functions, use a name that ends in @samp{-function} or -@samp{-functions}, respectively. - - There are several other variable name conventions; -here is a complete list: - -@table @samp -@item @dots{}-hook -The variable is a normal hook (@pxref{Hooks}). - -@item @dots{}-function -The value is a function. - -@item @dots{}-functions -The value is a list of functions. - -@item @dots{}-form -The value is a form (an expression). - -@item @dots{}-forms -The value is a list of forms (expressions). - -@item @dots{}-predicate -The value is a predicate---a function of one argument that returns -non-@code{nil} for ``good'' arguments and @code{nil} for ``bad'' -arguments. - -@item @dots{}-flag -The value is significant only as to whether it is @code{nil} or not. -Since such variables often end up acquiring more values over time, -this convention is not strongly recommended. - -@item @dots{}-program -The value is a program name. - -@item @dots{}-command -The value is a whole shell command. - -@item @dots{}-switches -The value specifies options for a command. -@end table - - When you define a variable, always consider whether you should mark -it as ``safe'' or ``risky''; see @ref{File Local Variables}. - - When defining and initializing a variable that holds a complicated -value (such as a keymap with bindings in it), it's best to put the -entire computation of the value into the @code{defvar}, like this: - -@example -(defvar my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - map) - @var{docstring}) -@end example - -@noindent -This method has several benefits. First, if the user quits while -loading the file, the variable is either still uninitialized or -initialized properly, never in-between. If it is still uninitialized, -reloading the file will initialize it properly. Second, reloading the -file once the variable is initialized will not alter it; that is -important if the user has run hooks to alter part of the contents -(such as, to rebind keys). Third, evaluating the @code{defvar} form -with @kbd{C-M-x} will reinitialize the map completely. - - Putting so much code in the @code{defvar} form has one disadvantage: -it puts the documentation string far away from the line which names the -variable. Here's a safe way to avoid that: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - (setq my-mode-map map))) -@end example - -@noindent -This has all the same advantages as putting the initialization inside -the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on -each form, if you do want to reinitialize the variable. - -@node Accessing Variables -@section Accessing Variable Values - - The usual way to reference a variable is to write the symbol which -names it. @xref{Symbol Forms}. - - Occasionally, you may want to reference a variable which is only -determined at run time. In that case, you cannot specify the variable -name in the text of the program. You can use the @code{symbol-value} -function to extract the value. - -@defun symbol-value symbol -This function returns the value stored in @var{symbol}'s value cell. -This is where the variable's current (dynamic) value is stored. If -the variable has no local binding, this is simply its global value. -If the variable is void, a @code{void-variable} error is signaled. - -If the variable is lexically bound, the value reported by -@code{symbol-value} is not necessarily the same as the variable's -lexical value, which is determined by the lexical environment rather -than the symbol's value cell. @xref{Variable Scoping}. - -@example -@group -(setq abracadabra 5) - @result{} 5 -@end group -@group -(setq foo 9) - @result{} 9 -@end group - -@group -;; @r{Here the symbol @code{abracadabra}} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value 'abracadabra)) - @result{} foo -@end group - -@group -;; @r{Here, the value of @code{abracadabra},} -;; @r{which is @code{foo},} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value abracadabra)) - @result{} 9 -@end group - -@group -(symbol-value 'abracadabra) - @result{} 5 -@end group -@end example -@end defun - -@node Setting Variables -@section Setting Variable Values - - The usual way to change the value of a variable is with the special -form @code{setq}. When you need to compute the choice of variable at -run time, use the function @code{set}. - -@defspec setq [symbol form]@dots{} -This special form is the most common method of changing a variable's -value. Each @var{symbol} is given a new value, which is the result of -evaluating the corresponding @var{form}. The current binding of the -symbol is changed. - -@code{setq} does not evaluate @var{symbol}; it sets the symbol that you -write. We say that this argument is @dfn{automatically quoted}. The -@samp{q} in @code{setq} stands for ``quoted''. - -The value of the @code{setq} form is the value of the last @var{form}. - -@example -@group -(setq x (1+ 2)) - @result{} 3 -@end group -x ; @r{@code{x} now has a global value.} - @result{} 3 -@group -(let ((x 5)) - (setq x 6) ; @r{The local binding of @code{x} is set.} - x) - @result{} 6 -@end group -x ; @r{The global value is unchanged.} - @result{} 3 -@end example - -Note that the first @var{form} is evaluated, then the first -@var{symbol} is set, then the second @var{form} is evaluated, then the -second @var{symbol} is set, and so on: - -@example -@group -(setq x 10 ; @r{Notice that @code{x} is set before} - y (1+ x)) ; @r{the value of @code{y} is computed.} - @result{} 11 -@end group -@end example -@end defspec - -@defun set symbol value -This function puts @var{value} in the value cell of @var{symbol}. -Since it is a function rather than a special form, the expression -written for @var{symbol} is evaluated to obtain the symbol to set. -The return value is @var{value}. - -When dynamic variable binding is in effect (the default), @code{set} -has the same effect as @code{setq}, apart from the fact that -@code{set} evaluates its @var{symbol} argument whereas @code{setq} -does not. But when a variable is lexically bound, @code{set} affects -its @emph{dynamic} value, whereas @code{setq} affects its current -(lexical) value. @xref{Variable Scoping}. - -@example -@group -(set one 1) -@error{} Symbol's value as variable is void: one -@end group -@group -(set 'one 1) - @result{} 1 -@end group -@group -(set 'two 'one) - @result{} one -@end group -@group -(set two 2) ; @r{@code{two} evaluates to symbol @code{one}.} - @result{} 2 -@end group -@group -one ; @r{So it is @code{one} that was set.} - @result{} 2 -(let ((one 1)) ; @r{This binding of @code{one} is set,} - (set 'one 3) ; @r{not the global value.} - one) - @result{} 3 -@end group -@group -one - @result{} 2 -@end group -@end example - -If @var{symbol} is not actually a symbol, a @code{wrong-type-argument} -error is signaled. - -@example -(set '(x y) 'z) -@error{} Wrong type argument: symbolp, (x y) -@end example -@end defun - -@node Variable Scoping -@section Scoping Rules for Variable Bindings -@cindex scoping rule - - When you create a local binding for a variable, that binding takes -effect only within a limited portion of the program (@pxref{Local -Variables}). This section describes exactly what this means. - -@cindex scope -@cindex extent - Each local binding has a certain @dfn{scope} and @dfn{extent}. -@dfn{Scope} refers to @emph{where} in the textual source code the -binding can be accessed. @dfn{Extent} refers to @emph{when}, as the -program is executing, the binding exists. - -@cindex dynamic binding -@cindex dynamic scope -@cindex dynamic extent - By default, the local bindings that Emacs creates are @dfn{dynamic -bindings}. Such a binding has @dfn{dynamic scope}, meaning that any -part of the program can potentially access the variable binding. It -also has @dfn{dynamic extent}, meaning that the binding lasts only -while the binding construct (such as the body of a @code{let} form) is -being executed. - -@cindex lexical binding -@cindex lexical scope -@cindex indefinite extent - Emacs can optionally create @dfn{lexical bindings}. A lexical -binding has @dfn{lexical scope}, meaning that any reference to the -variable must be located textually within the binding -construct@footnote{With some exceptions; for instance, a lexical -binding can also be accessed from the Lisp debugger.}. It also has -@dfn{indefinite extent}, meaning that under some circumstances the -binding can live on even after the binding construct has finished -executing, by means of special objects called @dfn{closures}. - - The following subsections describe dynamic binding and lexical -binding in greater detail, and how to enable lexical binding in Emacs -Lisp programs. - -@menu -* Dynamic Binding:: The default for binding local variables in Emacs. -* Dynamic Binding Tips:: Avoiding problems with dynamic binding. -* Lexical Binding:: A different type of local variable binding. -* Using Lexical Binding:: How to enable lexical binding. -@end menu - -@node Dynamic Binding -@subsection Dynamic Binding - - By default, the local variable bindings made by Emacs are dynamic -bindings. When a variable is dynamically bound, its current binding -at any point in the execution of the Lisp program is simply the most -recently-created dynamic local binding for that symbol, or the global -binding if there is no such local binding. - - Dynamic bindings have dynamic scope and extent, as shown by the -following example: - -@example -@group -(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.} - -(defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} - -(let ((x 1)) ; @r{@code{x} is dynamically bound.} - (getx)) - @result{} 1 - -;; @r{After the @code{let} form finishes, @code{x} reverts to its} -;; @r{previous value, which is @minus{}99.} - -(getx) - @result{} -99 -@end group -@end example - -@noindent -The function @code{getx} refers to @code{x}. This is a ``free'' -reference, in the sense that there is no binding for @code{x} within -that @code{defun} construct itself. When we call @code{getx} from -within a @code{let} form in which @code{x} is (dynamically) bound, it -retrieves the local value (i.e., 1). But when we call @code{getx} -outside the @code{let} form, it retrieves the global value (i.e., -@minus{}99). - - Here is another example, which illustrates setting a dynamically -bound variable using @code{setq}: - -@example -@group -(defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.} - -(defun addx () - (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.} - -(let ((x 1)) - (addx) - (addx)) - @result{} 3 ; @r{The two @code{addx} calls add to @code{x} twice.} - -;; @r{After the @code{let} form finishes, @code{x} reverts to its} -;; @r{previous value, which is @minus{}99.} - -(addx) - @result{} -98 -@end group -@end example - - Dynamic binding is implemented in Emacs Lisp in a simple way. Each -symbol has a value cell, which specifies its current dynamic value (or -absence of value). @xref{Symbol Components}. When a symbol is given -a dynamic local binding, Emacs records the contents of the value cell -(or absence thereof) in a stack, and stores the new local value in the -value cell. When the binding construct finishes executing, Emacs pops -the old value off the stack, and puts it in the value cell. - -@node Dynamic Binding Tips -@subsection Proper Use of Dynamic Binding - - Dynamic binding is a powerful feature, as it allows programs to -refer to variables that are not defined within their local textual -scope. However, if used without restraint, this can also make -programs hard to understand. There are two clean ways to use this -technique: - -@itemize @bullet -@item -If a variable has no global definition, use it as a local variable -only within a binding construct, such as the body of the @code{let} -form where the variable was bound. If this convention is followed -consistently throughout a program, the value of the variable will not -affect, nor be affected by, any uses of the same variable symbol -elsewhere in the program. - -@item -Otherwise, define the variable with @code{defvar}, @code{defconst}, or -@code{defcustom}. @xref{Defining Variables}. Usually, the definition -should be at top-level in an Emacs Lisp file. As far as possible, it -should include a documentation string which explains the meaning and -purpose of the variable. You should also choose the variable's name -to avoid name conflicts (@pxref{Coding Conventions}). - -Then you can bind the variable anywhere in a program, knowing reliably -what the effect will be. Wherever you encounter the variable, it will -be easy to refer back to the definition, e.g., via the @kbd{C-h v} -command (provided the variable definition has been loaded into Emacs). -@xref{Name Help,,, emacs, The GNU Emacs Manual}. - -For example, it is common to use local bindings for customizable -variables like @code{case-fold-search}: - -@example -@group -(defun search-for-abc () - "Search for the string \"abc\", ignoring case differences." - (let ((case-fold-search nil)) - (re-search-forward "abc"))) -@end group -@end example -@end itemize - -@node Lexical Binding -@subsection Lexical Binding - - Lexical binding was introduced to Emacs, as an optional feature, in -version 24.1. We expect its importance to increase in the future. -Lexical binding opens up many more opportunities for optimization, so -programs using it are likely to run faster in future Emacs versions. -Lexical binding is also more compatible with concurrency, which we -want to add to Emacs in the future. - - A lexically-bound variable has @dfn{lexical scope}, meaning that any -reference to the variable must be located textually within the binding -construct. Here is an example -@iftex -(see the next subsection, for how to actually enable lexical binding): -@end iftex -@ifnottex -(@pxref{Using Lexical Binding}, for how to actually enable lexical binding): -@end ifnottex - -@example -@group -(let ((x 1)) ; @r{@code{x} is lexically bound.} - (+ x 3)) - @result{} 4 - -(defun getx () - x) ; @r{@code{x} is used ``free'' in this function.} - -(let ((x 1)) ; @r{@code{x} is lexically bound.} - (getx)) -@error{} Symbol's value as variable is void: x -@end group -@end example - -@noindent -Here, the variable @code{x} has no global value. When it is lexically -bound within a @code{let} form, it can be used in the textual confines -of that @code{let} form. But it can @emph{not} be used from within a -@code{getx} function called from the @code{let} form, since the -function definition of @code{getx} occurs outside the @code{let} form -itself. - -@cindex lexical environment - Here is how lexical binding works. Each binding construct defines a -@dfn{lexical environment}, specifying the symbols that are bound -within the construct and their local values. When the Lisp evaluator -wants the current value of a variable, it looks first in the lexical -environment; if the variable is not specified in there, it looks in -the symbol's value cell, where the dynamic value is stored. - - (Internally, the lexical environment is an alist of symbol-value -pairs, with the final element in the alist being the symbol @code{t} -rather than a cons cell. Such an alist can be passed as the second -argument to the @code{eval} function, in order to specify a lexical -environment in which to evaluate a form. @xref{Eval}. Most Emacs -Lisp programs, however, should not interact directly with lexical -environments in this way; only specialized programs like debuggers.) - -@cindex closures, example of using - Lexical bindings have indefinite extent. Even after a binding -construct has finished executing, its lexical environment can be -``kept around'' in Lisp objects called @dfn{closures}. A closure is -created when you define a named or anonymous function with lexical -binding enabled. @xref{Closures}, for details. - - When a closure is called as a function, any lexical variable -references within its definition use the retained lexical environment. -Here is an example: - -@example -(defvar my-ticker nil) ; @r{We will use this dynamically bound} - ; @r{variable to store a closure.} - -(let ((x 0)) ; @r{@code{x} is lexically bound.} - (setq my-ticker (lambda () - (setq x (1+ x))))) - @result{} (closure ((x . 0) t) () - (setq x (1+ x))) - -(funcall my-ticker) - @result{} 1 - -(funcall my-ticker) - @result{} 2 - -(funcall my-ticker) - @result{} 3 - -x ; @r{Note that @code{x} has no global value.} -@error{} Symbol's value as variable is void: x -@end example - -@noindent -The @code{let} binding defines a lexical environment in which the -variable @code{x} is locally bound to 0. Within this binding -construct, we define a lambda expression which increments @code{x} by -one and returns the incremented value. This lambda expression is -automatically turned into a closure, in which the lexical environment -lives on even after the @code{let} binding construct has exited. Each -time we evaluate the closure, it increments @code{x}, using the -binding of @code{x} in that lexical environment. - - Note that functions like @code{symbol-value}, @code{boundp}, and -@code{set} only retrieve or modify a variable's dynamic binding -(i.e., the contents of its symbol's value cell). Also, the code in -the body of a @code{defun} or @code{defmacro} cannot refer to -surrounding lexical variables. - -@node Using Lexical Binding -@subsection Using Lexical Binding - - When loading an Emacs Lisp file or evaluating a Lisp buffer, lexical -binding is enabled if the buffer-local variable @code{lexical-binding} -is non-@code{nil}: - -@defvar lexical-binding -If this buffer-local variable is non-@code{nil}, Emacs Lisp files and -buffers are evaluated using lexical binding instead of dynamic -binding. (However, special variables are still dynamically bound; see -below.) If @code{nil}, dynamic binding is used for all local -variables. This variable is typically set for a whole Emacs Lisp -file, as a file local variable (@pxref{File Local Variables}). -Note that unlike other such variables, this one must be set in the -first line of a file. -@end defvar - -@noindent -When evaluating Emacs Lisp code directly using an @code{eval} call, -lexical binding is enabled if the @var{lexical} argument to -@code{eval} is non-@code{nil}. @xref{Eval}. - -@cindex special variables - Even when lexical binding is enabled, certain variables will -continue to be dynamically bound. These are called @dfn{special -variables}. Every variable that has been defined with @code{defvar}, -@code{defcustom} or @code{defconst} is a special variable -(@pxref{Defining Variables}). All other variables are subject to -lexical binding. - -@defun special-variable-p symbol -This function returns non-@code{nil} if @var{symbol} is a special -variable (i.e., it has a @code{defvar}, @code{defcustom}, or -@code{defconst} variable definition). Otherwise, the return value is -@code{nil}. -@end defun - - The use of a special variable as a formal argument in a function is -discouraged. Doing so gives rise to unspecified behavior when lexical -binding mode is enabled (it may use lexical binding sometimes, and -dynamic binding other times). - - Converting an Emacs Lisp program to lexical binding is easy. First, -add a file-local variable setting of @code{lexical-binding} to -@code{t} in the header line of the Emacs Lisp source file (@pxref{File -Local Variables}). Second, check that every variable in the program -which needs to be dynamically bound has a variable definition, so that -it is not inadvertently bound lexically. - -@cindex free variable -@cindex unused lexical variable - A simple way to find out which variables need a variable definition -is to byte-compile the source file. @xref{Byte Compilation}. If a -non-special variable is used outside of a @code{let} form, the -byte-compiler will warn about reference or assignment to a ``free -variable''. If a non-special variable is bound but not used within a -@code{let} form, the byte-compiler will warn about an ``unused lexical -variable''. The byte-compiler will also issue a warning if you use a -special variable as a function argument. - - (To silence byte-compiler warnings about unused variables, just use -a variable name that start with an underscore. The byte-compiler -interprets this as an indication that this is a variable known not to -be used.) - -@node Buffer-Local Variables -@section Buffer-Local Variables -@cindex variable, buffer-local -@cindex buffer-local variables - - Global and local variable bindings are found in most programming -languages in one form or another. Emacs, however, also supports -additional, unusual kinds of variable binding, such as -@dfn{buffer-local} bindings, which apply only in one buffer. Having -different values for a variable in different buffers is an important -customization method. (Variables can also have bindings that are -local to each terminal. @xref{Multiple Terminals}.) - -@menu -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. -@end menu - -@node Intro to Buffer-Local -@subsection Introduction to Buffer-Local Variables - - A buffer-local variable has a buffer-local binding associated with a -particular buffer. The binding is in effect when that buffer is -current; otherwise, it is not in effect. If you set the variable while -a buffer-local binding is in effect, the new value goes in that binding, -so its other bindings are unchanged. This means that the change is -visible only in the buffer where you made it. - - The variable's ordinary binding, which is not associated with any -specific buffer, is called the @dfn{default binding}. In most cases, -this is the global binding. - - A variable can have buffer-local bindings in some buffers but not in -other buffers. The default binding is shared by all the buffers that -don't have their own bindings for the variable. (This includes all -newly-created buffers.) If you set the variable in a buffer that does -not have a buffer-local binding for it, this sets the default binding, -so the new value is visible in all the buffers that see the default -binding. - - The most common use of buffer-local bindings is for major modes to change -variables that control the behavior of commands. For example, C mode and -Lisp mode both set the variable @code{paragraph-start} to specify that only -blank lines separate paragraphs. They do this by making the variable -buffer-local in the buffer that is being put into C mode or Lisp mode, and -then setting it to the new value for that mode. @xref{Major Modes}. - - The usual way to make a buffer-local binding is with -@code{make-local-variable}, which is what major mode commands typically -use. This affects just the current buffer; all other buffers (including -those yet to be created) will continue to share the default value unless -they are explicitly given their own buffer-local bindings. - -@cindex automatically buffer-local - A more powerful operation is to mark the variable as -@dfn{automatically buffer-local} by calling -@code{make-variable-buffer-local}. You can think of this as making the -variable local in all buffers, even those yet to be created. More -precisely, the effect is that setting the variable automatically makes -the variable local to the current buffer if it is not already so. All -buffers start out by sharing the default value of the variable as usual, -but setting the variable creates a buffer-local binding for the current -buffer. The new value is stored in the buffer-local binding, leaving -the default binding untouched. This means that the default value cannot -be changed with @code{setq} in any buffer; the only way to change it is -with @code{setq-default}. - - @strong{Warning:} When a variable has buffer-local -bindings in one or more buffers, @code{let} rebinds the binding that's -currently in effect. For instance, if the current buffer has a -buffer-local value, @code{let} temporarily rebinds that. If no -buffer-local bindings are in effect, @code{let} rebinds -the default value. If inside the @code{let} you then change to a -different current buffer in which a different binding is in effect, -you won't see the @code{let} binding any more. And if you exit the -@code{let} while still in the other buffer, you won't see the -unbinding occur (though it will occur properly). Here is an example -to illustrate: - -@example -@group -(setq foo 'g) -(set-buffer "a") -(make-local-variable 'foo) -@end group -(setq foo 'a) -(let ((foo 'temp)) - ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}} - (set-buffer "b") - ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}} - @var{body}@dots{}) -@group -foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},} - ; @r{but we don't see that in buffer @samp{b}} -@end group -@group -(set-buffer "a") ; @r{verify the local value was restored} -foo @result{} 'a -@end group -@end example - -@noindent -Note that references to @code{foo} in @var{body} access the -buffer-local binding of buffer @samp{b}. - - When a file specifies local variable values, these become buffer-local -values when you visit the file. @xref{File Variables,,, emacs, The -GNU Emacs Manual}. - - A buffer-local variable cannot be made terminal-local -(@pxref{Multiple Terminals}). - -@node Creating Buffer-Local -@subsection Creating and Deleting Buffer-Local Bindings - -@deffn Command make-local-variable variable -This function creates a buffer-local binding in the current buffer for -@var{variable} (a symbol). Other buffers are not affected. The value -returned is @var{variable}. - -The buffer-local value of @var{variable} starts out as the same value -@var{variable} previously had. If @var{variable} was void, it remains -void. - -@example -@group -;; @r{In buffer @samp{b1}:} -(setq foo 5) ; @r{Affects all buffers.} - @result{} 5 -@end group -@group -(make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.} - @result{} foo -@end group -@group -foo ; @r{That did not change} - @result{} 5 ; @r{the value.} -@end group -@group -(setq foo 6) ; @r{Change the value} - @result{} 6 ; @r{in @samp{b1}.} -@end group -@group -foo - @result{} 6 -@end group - -@group -;; @r{In buffer @samp{b2}, the value hasn't changed.} -(with-current-buffer "b2" - foo) - @result{} 5 -@end group -@end example - -Making a variable buffer-local within a @code{let}-binding for that -variable does not work reliably, unless the buffer in which you do this -is not current either on entry to or exit from the @code{let}. This is -because @code{let} does not distinguish between different kinds of -bindings; it knows only which variable the binding was made for. - -If the variable is terminal-local (@pxref{Multiple Terminals}), this -function signals an error. Such variables cannot have buffer-local -bindings as well. - -@strong{Warning:} do not use @code{make-local-variable} for a hook -variable. The hook variables are automatically made buffer-local as -needed if you use the @var{local} argument to @code{add-hook} or -@code{remove-hook}. -@end deffn - -@defmac setq-local variable value -This macro creates a buffer-local binding in the current buffer for -@var{variable}, and gives it the buffer-local value @var{value}. It -is equivalent to calling @code{make-local-variable} followed by -@code{setq}. @var{variable} should be an unquoted symbol. -@end defmac - -@deffn Command make-variable-buffer-local variable -This function marks @var{variable} (a symbol) automatically -buffer-local, so that any subsequent attempt to set it will make it -local to the current buffer at the time. Unlike -@code{make-local-variable}, with which it is often confused, this -cannot be undone, and affects the behavior of the variable in all -buffers. - -A peculiar wrinkle of this feature is that binding the variable (with -@code{let} or other binding constructs) does not create a buffer-local -binding for it. Only setting the variable (with @code{set} or -@code{setq}), while the variable does not have a @code{let}-style -binding that was made in the current buffer, does so. - -If @var{variable} does not have a default value, then calling this -command will give it a default value of @code{nil}. If @var{variable} -already has a default value, that value remains unchanged. -Subsequently calling @code{makunbound} on @var{variable} will result -in a void buffer-local value and leave the default value unaffected. - -The value returned is @var{variable}. - -@strong{Warning:} Don't assume that you should use -@code{make-variable-buffer-local} for user-option variables, simply -because users @emph{might} want to customize them differently in -different buffers. Users can make any variable local, when they wish -to. It is better to leave the choice to them. - -The time to use @code{make-variable-buffer-local} is when it is crucial -that no two buffers ever share the same binding. For example, when a -variable is used for internal purposes in a Lisp program which depends -on having separate values in separate buffers, then using -@code{make-variable-buffer-local} can be the best solution. -@end deffn - -@defmac defvar-local variable value &optional docstring -This macro defines @var{variable} as a variable with initial value -@var{value} and @var{docstring}, and marks it as automatically -buffer-local. It is equivalent to calling @code{defvar} followed by -@code{make-variable-buffer-local}. @var{variable} should be an -unquoted symbol. -@end defmac - -@defun local-variable-p variable &optional buffer -This returns @code{t} if @var{variable} is buffer-local in buffer -@var{buffer} (which defaults to the current buffer); otherwise, -@code{nil}. -@end defun - -@defun local-variable-if-set-p variable &optional buffer -This returns @code{t} if @var{variable} either has a buffer-local -value in buffer @var{buffer}, or is automatically buffer-local. -Otherwise, it returns @code{nil}. If omitted or @code{nil}, -@var{buffer} defaults to the current buffer. -@end defun - -@defun buffer-local-value variable buffer -This function returns the buffer-local binding of @var{variable} (a -symbol) in buffer @var{buffer}. If @var{variable} does not have a -buffer-local binding in buffer @var{buffer}, it returns the default -value (@pxref{Default Value}) of @var{variable} instead. -@end defun - -@defun buffer-local-variables &optional buffer -This function returns a list describing the buffer-local variables in -buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer -is used.) Normally, each list element has the form -@w{@code{(@var{sym} . @var{val})}}, where @var{sym} is a buffer-local -variable (a symbol) and @var{val} is its buffer-local value. But when -a variable's buffer-local binding in @var{buffer} is void, its list -element is just @var{sym}. - -@example -@group -(make-local-variable 'foobar) -(makunbound 'foobar) -(make-local-variable 'bind-me) -(setq bind-me 69) -@end group -(setq lcl (buffer-local-variables)) - ;; @r{First, built-in variables local in all buffers:} -@result{} ((mark-active . nil) - (buffer-undo-list . nil) - (mode-name . "Fundamental") - @dots{} -@group - ;; @r{Next, non-built-in buffer-local variables.} - ;; @r{This one is buffer-local and void:} - foobar - ;; @r{This one is buffer-local and nonvoid:} - (bind-me . 69)) -@end group -@end example - -Note that storing new values into the @sc{cdr}s of cons cells in this -list does @emph{not} change the buffer-local values of the variables. -@end defun - -@deffn Command kill-local-variable variable -This function deletes the buffer-local binding (if any) for -@var{variable} (a symbol) in the current buffer. As a result, the -default binding of @var{variable} becomes visible in this buffer. This -typically results in a change in the value of @var{variable}, since the -default value is usually different from the buffer-local value just -eliminated. - -If you kill the buffer-local binding of a variable that automatically -becomes buffer-local when set, this makes the default value visible in -the current buffer. However, if you set the variable again, that will -once again create a buffer-local binding for it. - -@code{kill-local-variable} returns @var{variable}. - -This function is a command because it is sometimes useful to kill one -buffer-local variable interactively, just as it is useful to create -buffer-local variables interactively. -@end deffn - -@defun kill-all-local-variables -This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent'' and local -hook functions that have a non-@code{nil} @code{permanent-local-hook} -property (@pxref{Setting Hooks}). As a result, the buffer will see -the default values of most variables. - -This function also resets certain other information pertaining to the -buffer: it sets the local keymap to @code{nil}, the syntax table to the -value of @code{(standard-syntax-table)}, the case table to -@code{(standard-case-table)}, and the abbrev table to the value of -@code{fundamental-mode-abbrev-table}. - -The very first thing this function does is run the normal hook -@code{change-major-mode-hook} (see below). - -Every major mode command begins by calling this function, which has the -effect of switching to Fundamental mode and erasing most of the effects -of the previous major mode. To ensure that this does its job, the -variables that major modes set should not be marked permanent. - -@code{kill-all-local-variables} returns @code{nil}. -@end defun - -@defvar change-major-mode-hook -The function @code{kill-all-local-variables} runs this normal hook -before it does anything else. This gives major modes a way to arrange -for something special to be done if the user switches to a different -major mode. It is also useful for buffer-specific minor modes -that should be forgotten if the user changes the major mode. - -For best results, make this variable buffer-local, so that it will -disappear after doing its job and will not interfere with the -subsequent major mode. @xref{Hooks}. -@end defvar - -@cindex permanent local variable -A buffer-local variable is @dfn{permanent} if the variable name (a -symbol) has a @code{permanent-local} property that is non-@code{nil}. -Such variables are unaffected by @code{kill-all-local-variables}, and -their local bindings are therefore not cleared by changing major modes. -Permanent locals are appropriate for data pertaining to where the file -came from or how to save it, rather than with how to edit the contents. - -@node Default Value -@subsection The Default Value of a Buffer-Local Variable -@cindex default value - - The global value of a variable with buffer-local bindings is also -called the @dfn{default} value, because it is the value that is in -effect whenever neither the current buffer nor the selected frame has -its own binding for the variable. - - The functions @code{default-value} and @code{setq-default} access and -change a variable's default value regardless of whether the current -buffer has a buffer-local binding. For example, you could use -@code{setq-default} to change the default setting of -@code{paragraph-start} for most buffers; and this would work even when -you are in a C or Lisp mode buffer that has a buffer-local value for -this variable. - -@c Emacs 19 feature - The special forms @code{defvar} and @code{defconst} also set the -default value (if they set the variable at all), rather than any -buffer-local value. - -@defun default-value symbol -This function returns @var{symbol}'s default value. This is the value -that is seen in buffers and frames that do not have their own values for -this variable. If @var{symbol} is not buffer-local, this is equivalent -to @code{symbol-value} (@pxref{Accessing Variables}). -@end defun - -@c Emacs 19 feature -@defun default-boundp symbol -The function @code{default-boundp} tells you whether @var{symbol}'s -default value is nonvoid. If @code{(default-boundp 'foo)} returns -@code{nil}, then @code{(default-value 'foo)} would get an error. - -@code{default-boundp} is to @code{default-value} as @code{boundp} is to -@code{symbol-value}. -@end defun - -@defspec setq-default [symbol form]@dots{} -This special form gives each @var{symbol} a new default value, which is -the result of evaluating the corresponding @var{form}. It does not -evaluate @var{symbol}, but does evaluate @var{form}. The value of the -@code{setq-default} form is the value of the last @var{form}. - -If a @var{symbol} is not buffer-local for the current buffer, and is not -marked automatically buffer-local, @code{setq-default} has the same -effect as @code{setq}. If @var{symbol} is buffer-local for the current -buffer, then this changes the value that other buffers will see (as long -as they don't have a buffer-local value), but not the value that the -current buffer sees. - -@example -@group -;; @r{In buffer @samp{foo}:} -(make-local-variable 'buffer-local) - @result{} buffer-local -@end group -@group -(setq buffer-local 'value-in-foo) - @result{} value-in-foo -@end group -@group -(setq-default buffer-local 'new-default) - @result{} new-default -@end group -@group -buffer-local - @result{} value-in-foo -@end group -@group -(default-value 'buffer-local) - @result{} new-default -@end group - -@group -;; @r{In (the new) buffer @samp{bar}:} -buffer-local - @result{} new-default -@end group -@group -(default-value 'buffer-local) - @result{} new-default -@end group -@group -(setq buffer-local 'another-default) - @result{} another-default -@end group -@group -(default-value 'buffer-local) - @result{} another-default -@end group - -@group -;; @r{Back in buffer @samp{foo}:} -buffer-local - @result{} value-in-foo -(default-value 'buffer-local) - @result{} another-default -@end group -@end example -@end defspec - -@defun set-default symbol value -This function is like @code{setq-default}, except that @var{symbol} is -an ordinary evaluated argument. - -@example -@group -(set-default (car '(a b c)) 23) - @result{} 23 -@end group -@group -(default-value 'a) - @result{} 23 -@end group -@end example -@end defun - -@node File Local Variables -@section File Local Variables -@cindex file local variables - - A file can specify local variable values; Emacs uses these to create -buffer-local bindings for those variables in the buffer visiting that -file. @xref{File Variables, , Local Variables in Files, emacs, The -GNU Emacs Manual}, for basic information about file-local variables. -This section describes the functions and variables that affect how -file-local variables are processed. - - If a file-local variable could specify an arbitrary function or Lisp -expression that would be called later, visiting a file could take over -your Emacs. Emacs protects against this by automatically setting only -those file-local variables whose specified values are known to be -safe. Other file-local variables are set only if the user agrees. - - For additional safety, @code{read-circle} is temporarily bound to -@code{nil} when Emacs reads file-local variables (@pxref{Input -Functions}). This prevents the Lisp reader from recognizing circular -and shared Lisp structures (@pxref{Circular Objects}). - -@defopt enable-local-variables -This variable controls whether to process file-local variables. -The possible values are: - -@table @asis -@item @code{t} (the default) -Set the safe variables, and query (once) about any unsafe variables. -@item @code{:safe} -Set only the safe variables and do not query. -@item @code{:all} -Set all the variables and do not query. -@item @code{nil} -Don't set any variables. -@item anything else -Query (once) about all the variables. -@end table -@end defopt - -@defvar inhibit-local-variables-regexps -This is a list of regular expressions. If a file has a name -matching an element of this list, then it is not scanned for -any form of file-local variable. For examples of why you might want -to use this, @pxref{Auto Major Mode}. -@end defvar - -@defun hack-local-variables &optional mode-only -This function parses, and binds or evaluates as appropriate, any local -variables specified by the contents of the current buffer. The variable -@code{enable-local-variables} has its effect here. However, this -function does not look for the @samp{mode:} local variable in the -@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking -@code{enable-local-variables} into account (@pxref{Auto Major Mode}). - -This function works by walking the alist stored in -@code{file-local-variables-alist} and applying each local variable in -turn. It calls @code{before-hack-local-variables-hook} and -@code{hack-local-variables-hook} before and after applying the -variables, respectively. It only calls the before-hook if the alist -is non-@code{nil}; it always calls the other hook. This -function ignores a @samp{mode} element if it specifies the same major -mode as the buffer already has. - -If the optional argument @var{mode-only} is non-@code{nil}, then all -this function does is return a symbol specifying the major mode, -if the @w{@samp{-*-}} line or the local variables list specifies one, -and @code{nil} otherwise. It does not set the mode nor any other -file-local variable. -@end defun - -@defvar file-local-variables-alist -This buffer-local variable holds the alist of file-local variable -settings. Each element of the alist is of the form -@w{@code{(@var{var} . @var{value})}}, where @var{var} is a symbol of -the local variable and @var{value} is its value. When Emacs visits a -file, it first collects all the file-local variables into this alist, -and then the @code{hack-local-variables} function applies them one by -one. -@end defvar - -@defvar before-hack-local-variables-hook -Emacs calls this hook immediately before applying file-local variables -stored in @code{file-local-variables-alist}. -@end defvar - -@defvar hack-local-variables-hook -Emacs calls this hook immediately after it finishes applying -file-local variables stored in @code{file-local-variables-alist}. -@end defvar - -@cindex safe local variable - You can specify safe values for a variable with a -@code{safe-local-variable} property. The property has to be a -function of one argument; any value is safe if the function returns -non-@code{nil} given that value. Many commonly-encountered file -variables have @code{safe-local-variable} properties; these include -@code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}. -For boolean-valued variables that are safe, use @code{booleanp} as the -property value. - - When defining a user option using @code{defcustom}, you can set its -@code{safe-local-variable} property by adding the arguments -@code{:safe @var{function}} to @code{defcustom} (@pxref{Variable -Definitions}). - -@defopt safe-local-variable-values -This variable provides another way to mark some variable values as -safe. It is a list of cons cells @code{(@var{var} . @var{val})}, -where @var{var} is a variable name and @var{val} is a value which is -safe for that variable. - -When Emacs asks the user whether or not to obey a set of file-local -variable specifications, the user can choose to mark them as safe. -Doing so adds those variable/value pairs to -@code{safe-local-variable-values}, and saves it to the user's custom -file. -@end defopt - -@defun safe-local-variable-p sym val -This function returns non-@code{nil} if it is safe to give @var{sym} -the value @var{val}, based on the above criteria. -@end defun - -@c @cindex risky local variable Duplicates risky-local-variable - Some variables are considered @dfn{risky}. If a variable is risky, -it is never entered automatically into -@code{safe-local-variable-values}; Emacs always queries before setting -a risky variable, unless the user explicitly allows a value by -customizing @code{safe-local-variable-values} directly. - - Any variable whose name has a non-@code{nil} -@code{risky-local-variable} property is considered risky. When you -define a user option using @code{defcustom}, you can set its -@code{risky-local-variable} property by adding the arguments -@code{:risky @var{value}} to @code{defcustom} (@pxref{Variable -Definitions}). In addition, any variable whose name ends in any of -@samp{-command}, @samp{-frame-alist}, @samp{-function}, -@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form}, -@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist}, -@samp{-program}, or @samp{-predicate} is automatically considered -risky. The variables @samp{font-lock-keywords}, -@samp{font-lock-keywords} followed by a digit, and -@samp{font-lock-syntactic-keywords} are also considered risky. - -@defun risky-local-variable-p sym -This function returns non-@code{nil} if @var{sym} is a risky variable, -based on the above criteria. -@end defun - -@defvar ignored-local-variables -This variable holds a list of variables that should not be given local -values by files. Any value specified for one of these variables is -completely ignored. -@end defvar - - The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs -normally asks for confirmation before handling it. - -@defopt enable-local-eval -This variable controls processing of @samp{Eval:} in @samp{-*-} lines -or local variables -lists in files being visited. A value of @code{t} means process them -unconditionally; @code{nil} means ignore them; anything else means ask -the user what to do for each file. The default value is @code{maybe}. -@end defopt - -@defopt safe-local-eval-forms -This variable holds a list of expressions that are safe to -evaluate when found in the @samp{Eval:} ``variable'' in a file -local variables list. -@end defopt - - If the expression is a function call and the function has a -@code{safe-local-eval-function} property, the property value -determines whether the expression is safe to evaluate. The property -value can be a predicate to call to test the expression, a list of -such predicates (it's safe if any predicate succeeds), or @code{t} -(always safe provided the arguments are constant). - - Text properties are also potential loopholes, since their values -could include functions to call. So Emacs discards all text -properties from string values specified for file-local variables. - -@node Directory Local Variables -@section Directory Local Variables -@cindex directory local variables - - A directory can specify local variable values common to all files in -that directory; Emacs uses these to create buffer-local bindings for -those variables in buffers visiting any file in that directory. This -is useful when the files in the directory belong to some @dfn{project} -and therefore share the same local variables. - - There are two different methods for specifying directory local -variables: by putting them in a special file, or by defining a -@dfn{project class} for that directory. - -@defvr Constant dir-locals-file -This constant is the name of the file where Emacs expects to find the -directory-local variables. The name of the file is -@file{.dir-locals.el}@footnote{ -The MS-DOS version of Emacs uses @file{_dir-locals.el} instead, due to -limitations of the DOS filesystems. -}. A file by that name in a directory causes Emacs to apply its -settings to any file in that directory or any of its subdirectories -(optionally, you can exclude subdirectories; see below). -If some of the subdirectories have their own @file{.dir-locals.el} -files, Emacs uses the settings from the deepest file it finds starting -from the file's directory and moving up the directory tree. The file -specifies local variables as a specially formatted list; see -@ref{Directory Variables, , Per-directory Local Variables, emacs, The -GNU Emacs Manual}, for more details. -@end defvr - -@defun hack-dir-local-variables -This function reads the @code{.dir-locals.el} file and stores the -directory-local variables in @code{file-local-variables-alist} that is -local to the buffer visiting any file in the directory, without -applying them. It also stores the directory-local settings in -@code{dir-locals-class-alist}, where it defines a special class for -the directory in which @file{.dir-locals.el} file was found. This -function works by calling @code{dir-locals-set-class-variables} and -@code{dir-locals-set-directory-class}, described below. -@end defun - -@defun hack-dir-local-variables-non-file-buffer -This function looks for directory-local variables, and immediately -applies them in the current buffer. It is intended to be called in -the mode commands for non-file buffers, such as Dired buffers, to let -them obey directory-local variable settings. For non-file buffers, -Emacs looks for directory-local variables in @code{default-directory} -and its parent directories. -@end defun - -@defun dir-locals-set-class-variables class variables -This function defines a set of variable settings for the named -@var{class}, which is a symbol. You can later assign the class to one -or more directories, and Emacs will apply those variable settings to -all files in those directories. The list in @var{variables} can be of -one of the two forms: @code{(@var{major-mode} . @var{alist})} or -@code{(@var{directory} . @var{list})}. With the first form, if the -file's buffer turns on a mode that is derived from @var{major-mode}, -then the all the variables in the associated @var{alist} are applied; -@var{alist} should be of the form @code{(@var{name} . @var{value})}. -A special value @code{nil} for @var{major-mode} means the settings are -applicable to any mode. In @var{alist}, you can use a special -@var{name}: @code{subdirs}. If the associated value is -@code{nil}, the alist is only applied to files in the relevant -directory, not to those in any subdirectories. - -With the second form of @var{variables}, if @var{directory} is the -initial substring of the file's directory, then @var{list} is applied -recursively by following the above rules; @var{list} should be of one -of the two forms accepted by this function in @var{variables}. -@end defun - -@defun dir-locals-set-directory-class directory class &optional mtime -This function assigns @var{class} to all the files in @code{directory} -and its subdirectories. Thereafter, all the variable settings -specified for @var{class} will be applied to any visited file in -@var{directory} and its children. @var{class} must have been already -defined by @code{dir-locals-set-class-variables}. - -Emacs uses this function internally when it loads directory variables -from a @code{.dir-locals.el} file. In that case, the optional -argument @var{mtime} holds the file modification time (as returned by -@code{file-attributes}). Emacs uses this time to check stored -local variables are still valid. If you are assigning a class -directly, not via a file, this argument should be @code{nil}. -@end defun - -@defvar dir-locals-class-alist -This alist holds the class symbols and the associated variable -settings. It is updated by @code{dir-locals-set-class-variables}. -@end defvar - -@defvar dir-locals-directory-cache -This alist holds directory names, their assigned class names, and -modification times of the associated directory local variables file -(if there is one). The function @code{dir-locals-set-directory-class} -updates this list. -@end defvar - -@defvar enable-dir-local-variables -If @code{nil}, directory-local variables are ignored. This variable -may be useful for modes that want to ignore directory-locals while -still respecting file-local variables (@pxref{File Local Variables}). -@end defvar - -@node Variable Aliases -@section Variable Aliases -@cindex variable aliases -@cindex alias, for variables - - It is sometimes useful to make two variables synonyms, so that both -variables always have the same value, and changing either one also -changes the other. Whenever you change the name of a -variable---either because you realize its old name was not well -chosen, or because its meaning has partly changed---it can be useful -to keep the old name as an @emph{alias} of the new one for -compatibility. You can do this with @code{defvaralias}. - -@defun defvaralias new-alias base-variable &optional docstring -This function defines the symbol @var{new-alias} as a variable alias -for symbol @var{base-variable}. This means that retrieving the value -of @var{new-alias} returns the value of @var{base-variable}, and -changing the value of @var{new-alias} changes the value of -@var{base-variable}. The two aliased variable names always share the -same value and the same bindings. - -If the @var{docstring} argument is non-@code{nil}, it specifies the -documentation for @var{new-alias}; otherwise, the alias gets the same -documentation as @var{base-variable} has, if any, unless -@var{base-variable} is itself an alias, in which case @var{new-alias} gets -the documentation of the variable at the end of the chain of aliases. - -This function returns @var{base-variable}. -@end defun - - Variable aliases are convenient for replacing an old name for a -variable with a new name. @code{make-obsolete-variable} declares that -the old name is obsolete and therefore that it may be removed at some -stage in the future. - -@defun make-obsolete-variable obsolete-name current-name when &optional access-type -This function makes the byte compiler warn that the variable -@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, -it is the variable's new name; then the warning message says to use -@var{current-name} instead of @var{obsolete-name}. If -@var{current-name} is a string, this is the message and there is no -replacement variable. @var{when} should be a string indicating when -the variable was first made obsolete (usually a version number -string). - -The optional argument @var{access-type}, if non-@code{nil}, should -should specify the kind of access that will trigger obsolescence -warnings; it can be either @code{get} or @code{set}. -@end defun - - You can make two variables synonyms and declare one obsolete at the -same time using the macro @code{define-obsolete-variable-alias}. - -@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring -This macro marks the variable @var{obsolete-name} as obsolete and also -makes it an alias for the variable @var{current-name}. It is -equivalent to the following: - -@example -(defvaralias @var{obsolete-name} @var{current-name} @var{docstring}) -(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when}) -@end example -@end defmac - -@defun indirect-variable variable -This function returns the variable at the end of the chain of aliases -of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is -not defined as an alias, the function returns @var{variable}. - -This function signals a @code{cyclic-variable-indirection} error if -there is a loop in the chain of symbols. -@end defun - -@example -(defvaralias 'foo 'bar) -(indirect-variable 'foo) - @result{} bar -(indirect-variable 'bar) - @result{} bar -(setq bar 2) -bar - @result{} 2 -@group -foo - @result{} 2 -@end group -(setq foo 0) -bar - @result{} 0 -foo - @result{} 0 -@end example - -@node Variables with Restricted Values -@section Variables with Restricted Values - - Ordinary Lisp variables can be assigned any value that is a valid -Lisp object. However, certain Lisp variables are not defined in Lisp, -but in C@. Most of these variables are defined in the C code using -@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on -any value. However, some variables are defined using -@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp -variables in C,, Writing Emacs Primitives}, in particular the -description of functions of the type @code{syms_of_@var{filename}}, -for a brief discussion of the C implementation. - - Variables of type @code{DEFVAR_BOOL} can only take on the values -@code{nil} or @code{t}. Attempting to assign them any other value -will set them to @code{t}: - -@example -(let ((display-hourglass 5)) - display-hourglass) - @result{} t -@end example - -@defvar byte-boolean-vars -This variable holds a list of all variables of type @code{DEFVAR_BOOL}. -@end defvar - - Variables of type @code{DEFVAR_INT} can take on only integer values. -Attempting to assign them any other value will result in an error: - -@example -(setq undo-limit 1000.0) -@error{} Wrong type argument: integerp, 1000.0 -@end example - -@node Generalized Variables -@section Generalized Variables - -A @dfn{generalized variable} or @dfn{place form} is one of the many places -in Lisp memory where values can be stored. The simplest place form is -a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements -of arrays, properties of symbols, and many other locations are also -places where Lisp values are stored. - -Generalized variables are analogous to ``lvalues'' in the C -language, where @samp{x = a[i]} gets an element from an array -and @samp{a[i] = x} stores an element using the same notation. -Just as certain forms like @code{a[i]} can be lvalues in C, there -is a set of forms that can be generalized variables in Lisp. - -@menu -* Setting Generalized Variables:: The @code{setf} macro. -* Adding Generalized Variables:: Defining new @code{setf} forms. -@end menu - -@node Setting Generalized Variables -@subsection The @code{setf} Macro - -The @code{setf} macro is the most basic way to operate on generalized -variables. The @code{setf} form is like @code{setq}, except that it -accepts arbitrary place forms on the left side rather than just -symbols. For example, @code{(setf (car a) b)} sets the car of -@code{a} to @code{b}, doing the same operation as @code{(setcar a b)}, -but without having to remember two separate functions for setting and -accessing every type of place. - -@defmac setf [place form]@dots{} -This macro evaluates @var{form} and stores it in @var{place}, which -must be a valid generalized variable form. If there are several -@var{place} and @var{form} pairs, the assignments are done sequentially -just as with @code{setq}. @code{setf} returns the value of the last -@var{form}. -@end defmac - -The following Lisp forms will work as generalized variables, and -so may appear in the @var{place} argument of @code{setf}: - -@itemize -@item -A symbol naming a variable. In other words, @code{(setf x y)} is -exactly equivalent to @code{(setq x y)}, and @code{setq} itself is -strictly speaking redundant given that @code{setf} exists. Many -programmers continue to prefer @code{setq} for setting simple -variables, though, purely for stylistic or historical reasons. -The macro @code{(setf x y)} actually expands to @code{(setq x y)}, -so there is no performance penalty for using it in compiled code. - -@item -A call to any of the following standard Lisp functions: - -@smallexample -aref cddr symbol-function -car elt symbol-plist -caar get symbol-value -cadr gethash -cdr nth -cdar nthcdr -@end smallexample - -@item -A call to any of the following Emacs-specific functions: - -@smallexample -default-value process-get -frame-parameter process-sentinel -terminal-parameter window-buffer -keymap-parent window-display-table -match-data window-dedicated-p -overlay-get window-hscroll -overlay-start window-parameter -overlay-end window-point -process-buffer window-start -process-filter -@end smallexample -@end itemize - -@noindent -@code{setf} signals an error if you pass a @var{place} form that it -does not know how to handle. - -@c And for cl-lib's cl-getf. -Note that for @code{nthcdr}, the list argument of the function must -itself be a valid @var{place} form. For example, @code{(setf (nthcdr -0 foo) 7)} will set @code{foo} itself to 7. -@c The use of @code{nthcdr} as a @var{place} form is an extension -@c to standard Common Lisp. - -@c FIXME I don't think is a particularly good way to do it, -@c but these macros are introduced before generalized variables are. -The macros @code{push} (@pxref{List Variables}) and @code{pop} -(@pxref{List Elements}) can manipulate generalized variables, -not just lists. @code{(pop @var{place})} removes and returns the first -element of the list stored in @var{place}. It is analogous to -@code{(prog1 (car @var{place}) (setf @var{place} (cdr @var{place})))}, -except that it takes care to evaluate all subforms only once. -@code{(push @var{x} @var{place})} inserts @var{x} at the front of -the list stored in @var{place}. It is analogous to @code{(setf -@var{place} (cons @var{x} @var{place}))}, except for evaluation of the -subforms. Note that @code{push} and @code{pop} on an @code{nthcdr} -place can be used to insert or delete at any position in a list. - -The @file{cl-lib} library defines various extensions for generalized -variables, including additional @code{setf} places. -@xref{Generalized Variables,,, cl, Common Lisp Extensions}. - - -@node Adding Generalized Variables -@subsection Defining new @code{setf} forms - -This section describes how to define new forms that @code{setf} can -operate on. - -@defmac gv-define-simple-setter name setter &optional fix-return -This macro enables you to easily define @code{setf} methods for simple -cases. @var{name} is the name of a function, macro, or special form. -You can use this macro whenever @var{name} has a directly -corresponding @var{setter} function that updates it, e.g., -@code{(gv-define-simple-setter car setcar)}. - -This macro translates a call of the form - -@example -(setf (@var{name} @var{args}@dots{}) @var{value}) -@end example - -into -@example -(@var{setter} @var{args}@dots{} @var{value}) -@end example - -@noindent -Such a @code{setf} call is documented to return @var{value}. This is -no problem with, e.g., @code{car} and @code{setcar}, because -@code{setcar} returns the value that it set. If your @var{setter} -function does not return @var{value}, use a non-@code{nil} value for -the @var{fix-return} argument of @code{gv-define-simple-setter}. This -expands into something equivalent to -@example -(let ((temp @var{value})) - (@var{setter} @var{args}@dots{} temp) - temp) -@end example -so ensuring that it returns the correct result. -@end defmac - - -@defmac gv-define-setter name arglist &rest body -This macro allows for more complex @code{setf} expansions than the -previous form. You may need to use this form, for example, if there -is no simple setter function to call, or if there is one but it -requires different arguments to the place form. - -This macro expands the form -@code{(setf (@var{name} @var{args}@dots{}) @var{value})} by -first binding the @code{setf} argument forms -@code{(@var{value} @var{args}@dots{})} according to @var{arglist}, -and then executing @var{body}. @var{body} should return a Lisp -form that does the assignment, and finally returns the value that was -set. An example of using this macro is: - -@example -(gv-define-setter caar (val x) `(setcar (car ,x) ,val)) -@end example -@end defmac - -@findex gv-define-expander -@findex gv-letplace -@c FIXME? Not sure what or how much to say about these. -@c See cl.texi for an example of using gv-letplace. -For more control over the expansion, see the macro @code{gv-define-expander}. -The macro @code{gv-letplace} can be useful in defining macros that -perform similarly to @code{setf}; for example, the @code{incf} macro -of Common Lisp. Consult the source file @file{gv.el} for more details. - -@cindex CL note---no @code{setf} functions -@quotation -@b{Common Lisp note:} Common Lisp defines another way to specify the -@code{setf} behavior of a function, namely ``@code{setf} functions'', -whose names are lists @code{(setf @var{name})} rather than symbols. -For example, @code{(defun (setf foo) @dots{})} defines the function -that is used when @code{setf} is applied to @code{foo}. Emacs does -not support this. It is a compile-time error to use @code{setf} on a -form that has not already had an appropriate expansion defined. In -Common Lisp, this is not an error since the function @code{(setf -@var{func})} might be defined later. -@end quotation diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi deleted file mode 100644 index 1e27d744c7e..00000000000 --- a/doc/lispref/windows.texi +++ /dev/null @@ -1,3995 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software -@c Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Windows -@chapter Windows - -This chapter describes the functions and variables related to Emacs -windows. @xref{Frames}, for how windows are assigned an area of screen -available for Emacs to use. @xref{Display}, for information on how text -is displayed in windows. - -@menu -* Basic Windows:: Basic information on using windows. -* Windows and Frames:: Relating windows to the frame they appear on. -* Window Sizes:: Accessing a window's size. -* Resizing Windows:: Changing the sizes of windows. -* Splitting Windows:: Creating a new window. -* Deleting Windows:: Removing a window from its frame. -* Recombining Windows:: Preserving the frame layout when splitting and - deleting windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. -* Window History:: Each window remembers the buffers displayed in it. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Quitting Windows:: How to restore the state prior to displaying a - buffer. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. -@end menu - - -@node Basic Windows -@section Basic Concepts of Emacs Windows -@cindex window - -A @dfn{window} is an area of the screen that is used to display a buffer -(@pxref{Buffers}). In Emacs Lisp, windows are represented by a special -Lisp object type. - -@cindex multiple windows - Windows are grouped into frames (@pxref{Frames}). Each frame -contains at least one window; the user can subdivide it into multiple, -non-overlapping windows to view several buffers at once. Lisp -programs can use multiple windows for a variety of purposes. In -Rmail, for example, you can view a summary of message titles in one -window, and the contents of the selected message in another window. - -@cindex terminal screen -@cindex screen of terminal - Emacs uses the word ``window'' with a different meaning than in -graphical desktop environments and window systems, such as the X -Window System. When Emacs is run on X, each of its graphical X -windows is an Emacs frame (containing one or more Emacs windows). -When Emacs is run on a text terminal, the frame fills the entire -terminal screen. - -@cindex tiled windows - Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap -within the area of the frame. When a window is created, resized, or -deleted, the change in window space is taken from or given to the -adjacent windows, so that the total area of the frame is unchanged. - -@defun windowp object -This function returns @code{t} if @var{object} is a window (whether or -not it displays a buffer). Otherwise, it returns @code{nil}. -@end defun - -@cindex live windows -A @dfn{live window} is one that is actually displaying a buffer in a -frame. - -@defun window-live-p object -This function returns @code{t} if @var{object} is a live window and -@code{nil} otherwise. A live window is one that displays a buffer. -@end defun - -@cindex internal windows -The windows in each frame are organized into a @dfn{window tree}. -@xref{Windows and Frames}. The leaf nodes of each window tree are live -windows---the ones actually displaying buffers. The internal nodes of -the window tree are @dfn{internal windows}, which are not live. - -@cindex valid windows - A @dfn{valid window} is one that is either live or internal. A valid -window can be @dfn{deleted}, i.e., removed from its frame -(@pxref{Deleting Windows}); then it is no longer valid, but the Lisp -object representing it might be still referenced from other Lisp -objects. A deleted window may be made valid again by restoring a saved -window configuration (@pxref{Window Configurations}). - - You can distinguish valid windows from deleted windows with -@code{window-valid-p}. - -@defun window-valid-p object -This function returns @code{t} if @var{object} is a live window, or an -internal window in a window tree. Otherwise, it returns @code{nil}, -including for the case where @var{object} is a deleted window. -@end defun - -@cindex selected window -@cindex window selected within a frame - In each frame, at any time, exactly one Emacs window is designated -as @dfn{selected within the frame}. For the selected frame, that -window is called the @dfn{selected window}---the one in which most -editing takes place, and in which the cursor for selected windows -appears (@pxref{Cursor Parameters}). The selected window's buffer is -usually also the current buffer, except when @code{set-buffer} has -been used (@pxref{Current Buffer}). As for non-selected frames, the -window selected within the frame becomes the selected window if the -frame is ever selected. @xref{Selecting Windows}. - -@defun selected-window -This function returns the selected window (which is always a live -window). -@end defun - -@node Windows and Frames -@section Windows and Frames - -Each window belongs to exactly one frame (@pxref{Frames}). - -@defun window-frame &optional window -This function returns the frame that the window @var{window} belongs -to. If @var{window} is @code{nil}, it defaults to the selected -window. -@end defun - -@defun window-list &optional frame minibuffer window -This function returns a list of live windows belonging to the frame -@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to -the selected frame. - -The optional argument @var{minibuffer} specifies whether to include -the minibuffer window in the returned list. If @var{minibuffer} is -@code{t}, the minibuffer window is included. If @var{minibuffer} is -@code{nil} or omitted, the minibuffer window is included only if it is -active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the -minibuffer window is never included. - -The optional argument @var{window}, if non-@code{nil}, should be a live -window on the specified frame; then @var{window} will be the first -element in the returned list. If @var{window} is omitted or @code{nil}, -the window selected within the frame is the first element. -@end defun - -@cindex window tree -@cindex root window - Windows in the same frame are organized into a @dfn{window tree}, -whose leaf nodes are the live windows. The internal nodes of a window -tree are not live; they exist for the purpose of organizing the -relationships between live windows. The root node of a window tree is -called the @dfn{root window}. It can be either a live window (if the -frame has just one window), or an internal window. - - A minibuffer window (@pxref{Minibuffer Windows}) is not part of its -frame's window tree unless the frame is a minibuffer-only frame. -Nonetheless, most of the functions in this section accept the -minibuffer window as an argument. Also, the function -@code{window-tree} described at the end of this section lists the -minibuffer window alongside the actual window tree. - -@defun frame-root-window &optional frame-or-window -This function returns the root window for @var{frame-or-window}. The -argument @var{frame-or-window} should be either a window or a frame; -if omitted or @code{nil}, it defaults to the selected frame. If -@var{frame-or-window} is a window, the return value is the root window -of that window's frame. -@end defun - -@cindex parent window -@cindex child window -@cindex sibling window - When a window is split, there are two live windows where previously -there was one. One of these is represented by the same Lisp window -object as the original window, and the other is represented by a -newly-created Lisp window object. Both of these live windows become -leaf nodes of the window tree, as @dfn{child windows} of a single -internal window. If necessary, Emacs automatically creates this -internal window, which is also called the @dfn{parent window}, and -assigns it to the appropriate position in the window tree. A set of -windows that share the same parent are called @dfn{siblings}. - -@cindex parent window -@defun window-parent &optional window -This function returns the parent window of @var{window}. If -@var{window} is omitted or @code{nil}, it defaults to the selected -window. The return value is @code{nil} if @var{window} has no parent -(i.e., it is a minibuffer window or the root window of its frame). -@end defun - - Each internal window always has at least two child windows. If this -number falls to one as a result of window deletion, Emacs -automatically deletes the internal window, and its sole remaining -child window takes its place in the window tree. - - Each child window can be either a live window, or an internal window -(which in turn would have its own child windows). Therefore, each -internal window can be thought of as occupying a certain rectangular -@dfn{screen area}---the union of the areas occupied by the live -windows that are ultimately descended from it. - -@cindex window combination -@cindex vertical combination -@cindex horizontal combination - For each internal window, the screen areas of the immediate children -are arranged either vertically or horizontally (never both). If the -child windows are arranged one above the other, they are said to form -a @dfn{vertical combination}; if they are arranged side by side, they -are said to form a @dfn{horizontal combination}. Consider the -following example: - -@smallexample -@group - ______________________________________ - | ______ ____________________________ | - || || __________________________ || - || ||| ||| - || ||| ||| - || ||| ||| - || |||____________W4____________||| - || || __________________________ || - || ||| ||| - || ||| ||| - || |||____________W5____________||| - ||__W2__||_____________W3_____________ | - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -The root window of this frame is an internal window, @var{W1}. Its -child windows form a horizontal combination, consisting of the live -window @var{W2} and the internal window @var{W3}. The child windows -of @var{W3} form a vertical combination, consisting of the live -windows @var{W4} and @var{W5}. Hence, the live windows in this -window tree are @var{W2}, @var{W4}, and @var{W5}. - - The following functions can be used to retrieve a child window of an -internal window, and the siblings of a child window. - -@defun window-top-child &optional window -This function returns the topmost child window of @var{window}, if -@var{window} is an internal window whose children form a vertical -combination. For any other type of window, the return value is -@code{nil}. -@end defun - -@defun window-left-child &optional window -This function returns the leftmost child window of @var{window}, if -@var{window} is an internal window whose children form a horizontal -combination. For any other type of window, the return value is -@code{nil}. -@end defun - -@defun window-child window -This function returns the first child window of the internal window -@var{window}---the topmost child window for a vertical combination, or -the leftmost child window for a horizontal combination. If -@var{window} is a live window, the return value is @code{nil}. -@end defun - -@defun window-combined-p &optional window horizontal -This function returns a non-@code{nil} value if and only if -@var{window} is part of a vertical combination. If @var{window} is -omitted or @code{nil}, it defaults to the selected one. - -If the optional argument @var{horizontal} is non-@code{nil}, this -means to return non-@code{nil} if and only if @var{window} is part of -a horizontal combination. -@end defun - -@defun window-next-sibling &optional window -This function returns the next sibling of the window @var{window}. If -omitted or @code{nil}, @var{window} defaults to the selected window. -The return value is @code{nil} if @var{window} is the last child of -its parent. -@end defun - -@defun window-prev-sibling &optional window -This function returns the previous sibling of the window @var{window}. -If omitted or @code{nil}, @var{window} defaults to the selected -window. The return value is @code{nil} if @var{window} is the first -child of its parent. -@end defun - -The functions @code{window-next-sibling} and -@code{window-prev-sibling} should not be confused with the functions -@code{next-window} and @code{previous-window}, which return the next -and previous window, respectively, in the cyclic ordering of windows -(@pxref{Cyclic Window Ordering}). - - You can use the following functions to find the first live window on a -frame and the window nearest to a given window. - -@defun frame-first-window &optional frame-or-window -This function returns the live window at the upper left corner of the -frame specified by @var{frame-or-window}. The argument -@var{frame-or-window} must denote a window or a live frame and defaults -to the selected frame. If @var{frame-or-window} specifies a window, -this function returns the first window on that window's frame. Under -the assumption that the frame from our canonical example is selected -@code{(frame-first-window)} returns @var{W2}. -@end defun - -@cindex window in direction -@defun window-in-direction direction &optional window ignore sign wrap mini -This function returns the nearest live window in direction -@var{direction} as seen from the position of @code{window-point} in -window @var{window}. The argument @var{direction} must be one of -@code{above}, @code{below}, @code{left} or @code{right}. The optional -argument @var{window} must denote a live window and defaults to the -selected one. - -This function does not return a window whose @code{no-other-window} -parameter is non-@code{nil} (@pxref{Window Parameters}). If the nearest -window's @code{no-other-window} parameter is non-@code{nil}, this -function tries to find another window in the indicated direction whose -@code{no-other-window} parameter is @code{nil}. If the optional -argument @var{ignore} is non-@code{nil}, a window may be returned even -if its @code{no-other-window} parameter is non-@code{nil}. - -If the optional argument @var{sign} is a negative number, it means to -use the right or bottom edge of @var{window} as reference position -instead of @code{window-point}. If @var{sign} is a positive number, it -means to use the left or top edge of @var{window} as reference position. - -If the optional argument @var{wrap} is non-@code{nil}, this means to -wrap @var{direction} around frame borders. For example, if @var{window} -is at the top of the frame and @var{direction} is @code{above}, then -return the minibuffer window provided the frame has one, and a window at -the bottom of the frame otherwise. - -If the optional argument @var{mini} is @code{nil}, this means to return -the minibuffer window if and only if it is currently active. If -@var{mini} is non-@code{nil}, it returns the minibuffer window even when -it's not active. However, if @var{wrap} non-@code{nil}, it always acts -as if @var{mini} were @code{nil}. - -If it doesn't find a suitable window, this function returns @code{nil}. -@end defun - -The following function allows to retrieve the entire window tree of a -frame: - -@defun window-tree &optional frame -This function returns a list representing the window tree for frame -@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to -the selected frame. - -The return value is a list of the form @code{(@var{root} @var{mini})}, -where @var{root} represents the window tree of the frame's root -window, and @var{mini} is the frame's minibuffer window. - -If the root window is live, @var{root} is that window itself. -Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} -@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal -combination and @code{t} for a vertical combination, @var{edges} gives -the size and position of the combination, and the remaining elements -are the child windows. Each child window may again be a window object -(for a live window) or a list with the same format as above (for an -internal window). The @var{edges} element is a list @code{(@var{left} -@var{top} @var{right} @var{bottom})}, similar to the value returned by -@code{window-edges} (@pxref{Coordinates and Windows}). -@end defun - - -@node Window Sizes -@section Window Sizes -@cindex window size -@cindex size of window - - The following schematic shows the structure of a live window: - -@smallexample -@group - ____________________________________________ - |______________ Header Line ______________|RD| ^ - ^ |LS|LF|LM| |RM|RF|RS| | | - | | | | | | | | | | | -Window | | | | Text Area | | | | | Window -Body | | | | | (Window Body) | | | | | Total -Height | | | | | | | | | Height - | | | | |<- Window Body Width ->| | | | | | - v |__|__|__|_______________________|__|__|__| | | - |_______________ Mode Line _______________|__| | - |_____________ Bottom Divider _______________| v - <---------- Window Total Width ------------> - -@end group -@end smallexample - -@cindex window body -@cindex text area of a window -@cindex body of a window - At the center of the window is the @dfn{text area}, or @dfn{body}, -where the buffer text is displayed. The text area can be surrounded by -a series of optional areas. On the left and right, from innermost to -outermost, these are the left and right margins, denoted by LM and RM in -the schematic (@pxref{Display Margins}); the left and right fringes, -denoted by LF and RF (@pxref{Fringes}); the left or right scroll bar, -only one of which is present at any time, denoted by LS and RS -(@pxref{Scroll Bars}); and the right divider, denoted by RD -(@pxref{Window Dividers}). At the top of the window is the header line -(@pxref{Header Lines}); at the bottom of the window is the mode line -(@pxref{Mode Line Format}) followed by the bottom divider (@pxref{Window -Dividers}). - - Emacs provides miscellaneous functions for finding the height and -width of a window. The return value of many of these functions can be -specified either in units of pixels or in units of lines and columns. -On a graphical display, the latter actually correspond to the height and -width of a ``default'' character specified by the frame's default font -as returned by @code{frame-char-height} and @code{frame-char-width} -(@pxref{Size and Position}). Thus, if a window is displaying text with -a different font or size, the reported line height and column width for -that window may differ from the actual number of text lines or columns -displayed within it. - -@cindex window height -@cindex height of a window -@cindex total height of a window - The @dfn{total height} of a window is the number of lines comprising -the window's body, the header line, the mode line and the bottom divider -(if any). Note that the height of a frame is not the same as the height -of its root window (@pxref{Windows and Frames}), since a frame may also -contain an echo area, a menu bar, and a tool bar (@pxref{Size and -Position}). - -@defun window-total-height &optional window round -This function returns the total height, in lines, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. If @var{window} is an internal window, the return -value is the total height occupied by its descendant windows. - - If a window's pixel height is not an integral multiple of its frame's -default character height, the number of lines occupied by the window is -rounded internally. This is done in a way such that, if the window is a -parent window, the sum of the total heights of all its child windows -internally equals the total height of their parent. This means that -although two windows have the same pixel height, their internal total -heights may differ by one line. This means also, that if this window is -vertically combined and has a right sibling, the topmost row of that -sibling can be calculated as the sum of this window's topmost row and -total height (@pxref{Coordinates and Windows}) - - If the optional argument @var{round} is @code{ceiling}, this -function returns the smallest integer larger than @var{window}'s pixel -height divided by the character height of its frame; if it is -@code{floor}, it returns the largest integer smaller than said value; -with any other @var{round} it returns the internal value of -@var{windows}'s total height. -@end defun - -@cindex window width -@cindex width of a window -@cindex total width of a window -The @dfn{total width} of a window is the number of lines comprising the -window's body, its margins, fringes, scroll bars and a right divider (if -any). - -@defun window-total-width &optional window round -This function returns the total width, in columns, of the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. If @var{window} is internal, the return value is -the total width occupied by its descendant windows. - - If a window's pixel width is not an integral multiple of its frame's -character width, the number of lines occupied by the window is rounded -internally. This is done in a way such that, if the window is a parent -window, the sum of the total widths of all its children internally -equals the total width of their parent. This means that although two -windows have the same pixel width, their internal total widths may -differ by one column. This means also, that if this window is -horizontally combined and has a right sibling, the leftmost column of -that sibling can be calculated as the sum of this window's leftmost -column and total width (@pxref{Coordinates and Windows}). The -optional argument @var{round} behaves as it does for -@code{window-total-height}. -@end defun - -@defun window-total-size &optional window horizontal round -This function returns either the total height in lines or the total -width in columns of the window @var{window}. If @var{horizontal} is -omitted or @code{nil}, this is equivalent to calling -@code{window-total-height} for @var{window}; otherwise it is equivalent -to calling @code{window-total-width} for @var{window}. The optional -argument @var{round} behaves as it does for @code{window-total-height}. -@end defun - -The following two functions can be used to return the total size of a -window in units of pixels. - -@cindex window pixel height -@cindex pixel height of a window -@cindex total pixel height of a window - -@defun window-pixel-height &optional window -This function returns the total height of window @var{window} in pixels. -@var{window} must be a valid window and defaults to the selected one. - -The return value includes mode and header line and a bottom divider, if -any. If @var{window} is an internal window, its pixel height is the -pixel height of the screen areas spanned by its children. -@end defun - -@cindex window pixel height -@cindex pixel height of a window -@cindex total pixel height of a window - -@defun window-pixel-width &optional Lisp_Object &optional window -This function returns the width of window @var{window} in pixels. -@var{window} must be a valid window and defaults to the selected one. - -The return value includes the fringes and margins of @var{window} as -well as any vertical dividers or scroll bars belonging to @var{window}. -If @var{window} is an internal window, its pixel width is the width of -the screen areas spanned by its children. -@end defun - -@cindex full-width window -@cindex full-height window - The following functions can be used to determine whether a given -window has any adjacent windows. - -@defun window-full-height-p &optional window -This function returns non-@code{nil} if @var{window} has no other -window above or below it in its frame, i.e., its total height equals -the total height of the root window on that frame. If @var{window} is -omitted or @code{nil}, it defaults to the selected window. -@end defun - -@defun window-full-width-p &optional window -This function returns non-@code{nil} if @var{window} has no other -window to the left or right in its frame, i.e., its total width equals -that of the root window on that frame. If @var{window} is omitted or -@code{nil}, it defaults to the selected window. -@end defun - -@cindex window body height -@cindex body height of a window -@cindex window body width -The @dfn{body height} of a window is the height of its text area, which -does not include a mode or header line or a bottom divider. - -@defun window-body-height &optional window pixelwise -This function returns the height, in lines, of the body of window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults to -the selected window; otherwise it must be a live window. - -If the optional argument @var{pixelwise} is non-@code{nil}, this -function returns the body height of @var{window} counted in pixels. - -If @var{pixelwise} is @code{nil}, the return value is rounded down to -the nearest integer, if necessary. This means that if a line at the -bottom of the text area is only partially visible, that line is not -counted. It also means that the height of a window's body can never -exceed its total height as returned by @code{window-total-height}. -@end defun - -@cindex body width of a window -@cindex body size of a window -@cindex window body size -The @dfn{body width} of a window is the width of its text area, which -does not include the scroll bar, fringes, margins or a right divider. - -@defun window-body-width &optional window pixelwise -This function returns the width, in columns, of the body of window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults to -the selected window; otherwise it must be a live window. - -If the optional argument @var{pixelwise} is non-@code{nil}, this -function returns the body width of @var{window} in units of pixels. - -If @var{pixelwise} is @code{nil}, the return value is rounded down to -the nearest integer, if necessary. This means that if a column on the -right of the text area is only partially visible, that column is not -counted. It also means that the width of a window's body can never -exceed its total width as returned by @code{window-total-width}. -@end defun - -@defun window-body-size &optional window horizontal pixelwise -This function returns the body height or body width of @var{window}. If -@var{horizontal} is omitted or @code{nil}, it is equivalent to calling -@code{window-body-height} for @var{window}; otherwise it is equivalent -to calling @code{window-body-width}. In either case, the optional -argument @var{pixelwise} is passed to the function called. -@end defun - - For compatibility with previous versions of Emacs, -@code{window-height} is an alias for @code{window-total-height}, and -@code{window-width} is an alias for @code{window-body-width}. These -aliases are considered obsolete and will be removed in the future. - - The pixel heights of a window's mode and header line can be retrieved -with the functions given below. Their return value is usually accurate -unless the window has not been displayed before: In that case, the -return value is based on an estimate of the font used for the window's -frame. - -@defun window-mode-line-height &optional window -This function returns the height in pixels of @var{window}'s mode line. -@var{window} must be a live window and defaults to the selected one. If -@var{window} has no mode line, the return value is zero. -@end defun - -@defun window-header-line-height &optional window -This function returns the height in pixels of @var{window}'s header -line. @var{window} must be a live window and defaults to the selected -one. If @var{window} has no header line, the return value is zero. -@end defun - -Functions for retrieving the height and/or width of window dividers -(@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars -(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are -described in the corresponding sections. - -@cindex fixed-size window -@vindex window-min-height -@vindex window-min-width - Commands that change the size of windows (@pxref{Resizing Windows}), -or split them (@pxref{Splitting Windows}), obey the variables -@code{window-min-height} and @code{window-min-width}, which specify the -smallest allowable window height and width. They also obey the variable -@code{window-size-fixed}, with which a window can be @dfn{fixed} in -size: - -@defopt window-min-height -This option specifies the minimum total height, in lines, of any window. -Its value has to accommodate at least one text line as well as a mode -and header line and a bottom divider, if present. -@end defopt - -@defopt window-min-width -This option specifies the minimum total width, in columns, of any -window. Its value has to accommodate two text columns as well as -margins, fringes, a scroll bar and a right divider, if present. -@end defopt - -@defvar window-size-fixed -If this buffer-local variable is non-@code{nil}, the size of any -window displaying the buffer cannot normally be changed. Deleting a -window or changing the frame's size may still change its size, if -there is no choice. - -If the value is @code{height}, then only the window's height is fixed; -if the value is @code{width}, then only the window's width is fixed. -Any other non-@code{nil} value fixes both the width and the height. - -If this variable is @code{nil}, this does not necessarily mean that any -window showing the buffer can be resized in the desired direction. To -determine that, use the function @code{window-resizable}. -@xref{Resizing Windows}. -@end defvar - -The following function tells how small a specific window can get taking -into account the sizes of its areas and the values of -@code{window-min-height}, @code{window-min-width} and -@code{window-size-fixed}. - -@defun window-min-size &optional window horizontal ignore pixelwise -This function returns the minimum size of @var{window}. @var{window} -must be a valid window and defaults to the selected one. The optional -argument @var{horizontal} non-@code{nil} means to return the minimum -number of columns of @var{window}; otherwise return the minimum number -of @var{window}'s lines. - -The return value makes sure that all components of @var{window} remain -fully visible if @var{window}'s size were actually set to it. With -@var{horizontal} @code{nil} it includes the mode and header line and the -bottom divider. With @var{horizontal} non-@code{nil} it includes the -fringes, a scroll bar, and a right divider, if present. It does not, -however, include the space reserved for the margins. - -The optional argument @var{ignore}, if non-@code{nil}, means ignore -restrictions imposed by fixed size windows, @code{window-min-height} or -@code{window-min-width} settings. If @var{ignore} equals @code{safe}, -live windows may get as small as @code{window-safe-min-height} lines and -@code{window-safe-min-width} columns. If @var{ignore} is a window, -ignore restrictions for that window only. Any other non-@code{nil} -value means ignore all of the above restrictions for all windows. - -The optional argument @var{pixelwise} non-@code{nil} means to return the -minimum size of @var{window} counted in pixels. -@end defun - -@node Resizing Windows -@section Resizing Windows -@cindex window resizing -@cindex resize window -@cindex changing window size -@cindex window size, changing - - This section describes functions for resizing a window without -changing the size of its frame. Because live windows do not overlap, -these functions are meaningful only on frames that contain two or more -windows: resizing a window also changes the size of a neighboring -window. If there is just one window on a frame, its size cannot be -changed except by resizing the frame (@pxref{Size and Position}). - - Except where noted, these functions also accept internal windows as -arguments. Resizing an internal window causes its child windows to be -resized to fit the same space. - -@defun window-resizable window delta &optional horizontal ignore pixelwise -This function returns @var{delta} if the size of @var{window} can be -changed vertically by @var{delta} lines. If the optional argument -@var{horizontal} is non-@code{nil}, it instead returns @var{delta} if -@var{window} can be resized horizontally by @var{delta} columns. It -does not actually change the window size. - -If @var{window} is @code{nil}, it defaults to the selected window. - -A positive value of @var{delta} means to check whether the window can be -enlarged by that number of lines or columns; a negative value of -@var{delta} means to check whether the window can be shrunk by that many -lines or columns. If @var{delta} is non-zero, a return value of 0 means -that the window cannot be resized. - -Normally, the variables @code{window-min-height} and -@code{window-min-width} specify the smallest allowable window size -(@pxref{Window Sizes}). However, if the optional argument @var{ignore} -is non-@code{nil}, this function ignores @code{window-min-height} and -@code{window-min-width}, as well as @code{window-size-fixed}. Instead, -it considers the minimum-height window to be one consisting of a header, -a mode line and a bottom divider (if any), plus a text area one line -tall; and a minimum-width window as one consisting of fringes, margins, -a scroll bar and a right divider (if any), plus a text area two columns -wide. - -If the optional argument @var{pixelwise} is non-@code{nil}, -@var{delta} is interpreted as pixels. -@end defun - -@defun window-resize window delta &optional horizontal ignore pixelwise -This function resizes @var{window} by @var{delta} increments. If -@var{horizontal} is @code{nil}, it changes the height by @var{delta} -lines; otherwise, it changes the width by @var{delta} columns. A -positive @var{delta} means to enlarge the window, and a negative -@var{delta} means to shrink it. - -If @var{window} is @code{nil}, it defaults to the selected window. If -the window cannot be resized as demanded, an error is signaled. - -The optional argument @var{ignore} has the same meaning as for the -function @code{window-resizable} above. - -If the optional argument @var{pixelwise} is non-@code{nil}, -@var{delta} will be interpreted as pixels. - -The choice of which window edges this function alters depends on the -values of the option @code{window-combination-resize} and the -combination limits of the involved windows; in some cases, it may alter -both edges. @xref{Recombining Windows}. To resize by moving only the -bottom or right edge of a window, use the function -@code{adjust-window-trailing-edge}. -@end defun - -@c The commands enlarge-window, enlarge-window-horizontally, -@c shrink-window, and shrink-window-horizontally are documented in the -@c Emacs manual. They are not preferred for calling from Lisp. - -@defun adjust-window-trailing-edge window delta &optional horizontal pixelwise -This function moves @var{window}'s bottom edge by @var{delta} lines. -If optional argument @var{horizontal} is non-@code{nil}, it instead -moves the right edge by @var{delta} columns. If @var{window} is -@code{nil}, it defaults to the selected window. - -If the optional argument @var{pixelwise} is non-@code{nil}, -@var{delta} is interpreted as pixels. - -A positive @var{delta} moves the edge downwards or to the right; a -negative @var{delta} moves it upwards or to the left. If the edge -cannot be moved as far as specified by @var{delta}, this function -moves it as far as possible but does not signal a error. - -This function tries to resize windows adjacent to the edge that is -moved. If this is not possible for some reason (e.g., if that adjacent -window is fixed-size), it may resize other windows. -@end defun - -@cindex pixelwise, resizing windows -@defopt window-resize-pixelwise -If the value of this option is non-@code{nil}, Emacs resizes windows in -units of pixels. This currently affects functions like -@code{split-window} (@pxref{Splitting Windows}), @code{maximize-window}, -@code{minimize-window}, @code{fit-window-to-buffer}, -@code{shrink-window-if-larger-than-buffer} (all listed below) and -@code{fit-frame-to-buffer} (@pxref{Size and Position}). - -Note that when a frame's pixel size is not a multiple of its character -size, at least one window may get resized pixelwise even if this -option is @code{nil}. The default value is @code{nil}. -@end defopt - - The following commands resize windows in more specific ways. When -called interactively, they act on the selected window. - -@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width -This command adjusts the height or width of @var{window} to fit the text -in it. It returns non-@code{nil} if it was able to resize @var{window}, -and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it -defaults to the selected window. Otherwise, it should be a live window. - -If @var{window} is part of a vertical combination, this function adjusts -@var{window}'s height. The new height is calculated from the actual -height of the accessible portion of its buffer. The optional argument -@var{max-height}, if non-@code{nil}, specifies the maximum total height -that this function can give @var{window}. The optional argument -@var{min-height}, if non-@code{nil}, specifies the minimum total height -that it can give, which overrides the variable @code{window-min-height}. -Both @var{max-height} and @var{min-height} are specified in lines and -include mode and header line and a bottom divider, if any. - -If @var{window} is part of a horizontal combination and the value of the -option @code{fit-window-to-buffer-horizontally} (see below) is -non-@code{nil}, this function adjusts @var{window}'s height. The new -width of @var{window} is calculated from the maximum length of its -buffer's lines that follow the current start position of @var{window}. -The optional argument @var{max-width} specifies a maximum width and -defaults to the width of @var{window}'s frame. The optional argument -@var{min-width} specifies a minimum width and defaults to -@code{window-min-width}. Both @var{max-width} and @var{min-width} are -specified in columns and include fringes, margins and scrollbars, if -any. - -If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil}, -this function will try to resize the frame of @var{window} to fit its -contents by calling @code{fit-frame-to-buffer} (@pxref{Size and -Position}). -@end deffn - -@defopt fit-window-to-buffer-horizontally -If this is non-@code{nil}, @code{fit-window-to-buffer} can resize -windows horizontally. If this is @code{nil} (the default) -@code{fit-window-to-buffer} never resizes windows horizontally. If this -is @code{only}, it can resize windows horizontally only. Any other -value means @code{fit-window-to-buffer} can resize windows in both -dimensions. -@end defopt - -@defopt fit-frame-to-buffer -If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a -frame to its buffer. A frame is fit if and only if its root window is a -live window and this option is non-@code{nil}. If this is -@code{horizontally}, frames are fit horizontally only. If this is -@code{vertically}, frames are fit vertically only. Any other -non-@code{nil} value means frames can be resized in both dimensions. -@end defopt - -@deffn Command shrink-window-if-larger-than-buffer &optional window -This command attempts to reduce @var{window}'s height as much as -possible while still showing its full buffer, but no less than -@code{window-min-height} lines. The return value is non-@code{nil} if -the window was resized, and @code{nil} otherwise. If @var{window} is -omitted or @code{nil}, it defaults to the selected window. Otherwise, -it should be a live window. - -This command does nothing if the window is already too short to -display all of its buffer, or if any of the buffer is scrolled -off-screen, or if the window is the only live window in its frame. - -This command calls @code{fit-window-to-buffer} (see above) to do its -work. -@end deffn - - -@cindex balancing window sizes -@deffn Command balance-windows &optional window-or-frame -This function balances windows in a way that gives more space to -full-width and/or full-height windows. If @var{window-or-frame} -specifies a frame, it balances all windows on that frame. If -@var{window-or-frame} specifies a window, it balances only that window -and its siblings (@pxref{Windows and Frames}). -@end deffn - -@deffn Command balance-windows-area -This function attempts to give all windows on the selected frame -approximately the same share of the screen area. Full-width or -full-height windows are not given more space than other windows. -@end deffn - -@cindex maximizing windows -@deffn Command maximize-window &optional window -This function attempts to make @var{window} as large as possible, in -both dimensions, without resizing its frame or deleting other windows. -If @var{window} is omitted or @code{nil}, it defaults to the selected -window. -@end deffn - -@cindex minimizing windows -@deffn Command minimize-window &optional window -This function attempts to make @var{window} as small as possible, in -both dimensions, without deleting it or resizing its frame. If -@var{window} is omitted or @code{nil}, it defaults to the selected -window. -@end deffn - - -@node Splitting Windows -@section Splitting Windows -@cindex splitting windows -@cindex window splitting - -This section describes functions for creating a new window by -@dfn{splitting} an existing one. - -@defun split-window &optional window size side pixelwise -This function creates a new live window next to the window -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. That window is ``split'', and reduced in -size. The space is taken up by the new window, which is returned. - -The optional second argument @var{size} determines the sizes of -@var{window} and/or the new window. If it is omitted or @code{nil}, -both windows are given equal sizes; if there is an odd line, it is -allocated to the new window. If @var{size} is a positive number, -@var{window} is given @var{size} lines (or columns, depending on the -value of @var{side}). If @var{size} is a negative number, the new -window is given @minus{}@var{size} lines (or columns). - -If @var{size} is @code{nil}, this function obeys the variables -@code{window-min-height} and @code{window-min-width} (@pxref{Window -Sizes}). Thus, it signals an error if splitting would result in making -a window smaller than those variables specify. However, a -non-@code{nil} value for @var{size} causes those variables to be -ignored; in that case, the smallest allowable window is considered to be -one that has space for a text area one line tall and/or two columns -wide. - -Hence, if @var{size} is specified, it's the caller's responsibility to -check whether the emanating windows are large enough to encompass all -areas like a mode line or a scroll bar. The function -@code{window-min-size} (@pxref{Window Sizes}) can be used to determine -the minimum requirements of @var{window} in this regard. Since the new -window usually ``inherits'' areas like the mode line or the scroll bar -from @var{window}, that function is also a good guess for the minimum -size of the new window. The caller should specify a smaller size only -if it correspondingly removes an inherited area before the next -redisplay. - -The optional third argument @var{side} determines the position of the -new window relative to @var{window}. If it is @code{nil} or -@code{below}, the new window is placed below @var{window}. If it is -@code{above}, the new window is placed above @var{window}. In both -these cases, @var{size} specifies a total window height, in lines. - -If @var{side} is @code{t} or @code{right}, the new window is placed on -the right of @var{window}. If @var{side} is @code{left}, the new -window is placed on the left of @var{window}. In both these cases, -@var{size} specifies a total window width, in columns. - -The optional fourth argument @var{pixelwise}, if non-@code{nil}, means -to interpret @var{size} in units of pixels, instead of lines and -columns. - -If @var{window} is a live window, the new window inherits various -properties from it, including margins and scroll bars. If -@var{window} is an internal window, the new window inherits the -properties of the window selected within @var{window}'s frame. - -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{split-window} window parameter is @code{t}, this function -ignores all other window parameters. Otherwise, if the value of the -@code{split-window} window parameter is a function, that function is -called with the arguments @var{window}, @var{size}, and @var{side}, in -lieu of the usual action of @code{split-window}. Otherwise, this -function obeys the @code{window-atom} or @code{window-side} window -parameter, if any. @xref{Window Parameters}. -@end defun - - As an example, here is a sequence of @code{split-window} calls that -yields the window configuration discussed in @ref{Windows and Frames}. -This example demonstrates splitting a live window as well as splitting -an internal window. We begin with a frame containing a single window -(a live root window), which we denote by @var{W4}. Calling -@code{(split-window W4)} yields this window configuration: - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - ||_________________W4_________________|| - | ____________________________________ | - || || - || || - || || - ||_________________W5_________________|| - |__________________W3__________________| - -@end group -@end smallexample - -@noindent -The @code{split-window} call has created a new live window, denoted by -@var{W5}. It has also created a new internal window, denoted by -@var{W3}, which becomes the root window and the parent of both -@var{W4} and @var{W5}. - - Next, we call @code{(split-window W3 nil 'left)}, passing the -internal window @var{W3} as the argument. The result: - -@smallexample -@group - ______________________________________ - | ______ ____________________________ | - || || __________________________ || - || ||| ||| - || ||| ||| - || ||| ||| - || |||____________W4____________||| - || || __________________________ || - || ||| ||| - || ||| ||| - || |||____________W5____________||| - ||__W2__||_____________W3_____________ | - |__________________W1__________________| -@end group -@end smallexample - -@noindent -A new live window @var{W2} is created, to the left of the internal -window @var{W3}. A new internal window @var{W1} is created, becoming -the new root window. - - For interactive use, Emacs provides two commands which always split -the selected window. These call @code{split-window} internally. - -@deffn Command split-window-right &optional size -This function splits the selected window into two side-by-side -windows, putting the selected window on the left. If @var{size} is -positive, the left window gets @var{size} columns; if @var{size} is -negative, the right window gets @minus{}@var{size} columns. -@end deffn - -@deffn Command split-window-below &optional size -This function splits the selected window into two windows, one above -the other, leaving the upper window selected. If @var{size} is -positive, the upper window gets @var{size} lines; if @var{size} is -negative, the lower window gets @minus{}@var{size} lines. -@end deffn - -@defopt split-window-keep-point -If the value of this variable is non-@code{nil} (the default), -@code{split-window-below} behaves as described above. - -If it is @code{nil}, @code{split-window-below} adjusts point in each -of the two windows to minimize redisplay. (This is useful on slow -terminals.) It selects whichever window contains the screen line that -point was previously on. Note that this only affects -@code{split-window-below}, not the lower-level @code{split-window} -function. -@end defopt - -@node Deleting Windows -@section Deleting Windows -@cindex deleting windows - - @dfn{Deleting} a window removes it from the frame's window tree. If -the window is a live window, it disappears from the screen. If the -window is an internal window, its child windows are deleted too. - - Even after a window is deleted, it continues to exist as a Lisp -object, until there are no more references to it. Window deletion can -be reversed, by restoring a saved window configuration (@pxref{Window -Configurations}). - -@deffn Command delete-window &optional window -This function removes @var{window} from display and returns -@code{nil}. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. If deleting the window would leave no more -windows in the window tree (e.g., if it is the only live window in the -frame), an error is signaled. - -By default, the space taken up by @var{window} is given to one of its -adjacent sibling windows, if any. However, if the variable -@code{window-combination-resize} is non-@code{nil}, the space is -proportionally distributed among any remaining windows in the window -combination. @xref{Recombining Windows}. - -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{delete-window} window parameter is @code{t}, this function -ignores all other window parameters. Otherwise, if the value of the -@code{delete-window} window parameter is a function, that function is -called with the argument @var{window}, in lieu of the usual action of -@code{delete-window}. Otherwise, this function obeys the -@code{window-atom} or @code{window-side} window parameter, if any. -@xref{Window Parameters}. -@end deffn - -@deffn Command delete-other-windows &optional window -This function makes @var{window} fill its frame, by deleting other -windows as necessary. If @var{window} is omitted or @code{nil}, it -defaults to the selected window. The return value is @code{nil}. - -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{delete-other-windows} window parameter is @code{t}, this -function ignores all other window parameters. Otherwise, if the value -of the @code{delete-other-windows} window parameter is a function, -that function is called with the argument @var{window}, in lieu of the -usual action of @code{delete-other-windows}. Otherwise, this function -obeys the @code{window-atom} or @code{window-side} window parameter, -if any. @xref{Window Parameters}. -@end deffn - -@deffn Command delete-windows-on &optional buffer-or-name frame -This function deletes all windows showing @var{buffer-or-name}, by -calling @code{delete-window} on those windows. @var{buffer-or-name} -should be a buffer, or the name of a buffer; if omitted or @code{nil}, -it defaults to the current buffer. If there are no windows showing -the specified buffer, this function does nothing. If the specified -buffer is a minibuffer, an error is signaled. - -If there is a dedicated window showing the buffer, and that window is -the only one on its frame, this function also deletes that frame if it -is not the only frame on the terminal. - -The optional argument @var{frame} specifies which frames to operate -on: - -@itemize @bullet -@item @code{nil} -means operate on all frames. -@item @code{t} -means operate on the selected frame. -@item @code{visible} -means operate on all visible frames. -@item @code{0} -means operate on all visible or iconified frames. -@item A frame -means operate on that frame. -@end itemize - -Note that this argument does not have the same meaning as in other -functions which scan all live windows (@pxref{Cyclic Window -Ordering}). Specifically, the meanings of @code{t} and @code{nil} here -are the opposite of what they are in those other functions. -@end deffn - - -@node Recombining Windows -@section Recombining Windows - -When deleting the last sibling of a window @var{W}, its parent window -is deleted too, with @var{W} replacing it in the window tree. This -means that @var{W} must be recombined with its parent's siblings to -form a new window combination (@pxref{Windows and Frames}). In some -occasions, deleting a live window may even entail the deletion of two -internal windows. - -@smallexample -@group - ______________________________________ - | ______ ____________________________ | - || || __________________________ || - || ||| ___________ ___________ ||| - || |||| || |||| - || ||||____W6_____||_____W7____|||| - || |||____________W4____________||| - || || __________________________ || - || ||| ||| - || ||| ||| - || |||____________W5____________||| - ||__W2__||_____________W3_____________ | - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -Deleting @var{W5} in this configuration normally causes the deletion of -@var{W3} and @var{W4}. The remaining live windows @var{W2}, -@var{W6} and @var{W7} are recombined to form a new horizontal -combination with parent @var{W1}. - - Sometimes, however, it makes sense to not delete a parent window like -@var{W4}. In particular, a parent window should not be removed when it -was used to preserve a combination embedded in a combination of the same -type. Such embeddings make sense to assure that when you split a window -and subsequently delete the new window, Emacs reestablishes the layout -of the associated frame as it existed before the splitting. - - Consider a scenario starting with two live windows @var{W2} and -@var{W3} and their parent @var{W1}. - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - || || - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -Split @var{W2} to make a new window @var{W4} as follows. - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - ||_________________W4_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -Now, when enlarging a window vertically, Emacs tries to obtain the -corresponding space from its lower sibling, provided such a window -exists. In our scenario, enlarging @var{W4} will steal space from -@var{W3}. - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - || || - || || - ||_________________W4_________________|| - | ____________________________________ | - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -Deleting @var{W4} will now give its entire space to @var{W2}, -including the space earlier stolen from @var{W3}. - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - || || - || || - || || - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -This can be counterintuitive, in particular if @var{W4} were used for -displaying a buffer only temporarily (@pxref{Temporary Displays}), and -you want to continue working with the initial layout. - -The behavior can be fixed by making a new parent window when splitting -@var{W2}. The variable described next allows to do that. - -@defopt window-combination-limit -This variable controls whether splitting a window shall make a new -parent window. The following values are recognized: - -@table @code -@item nil -This means that the new live window is allowed to share the existing -parent window, if one exists, provided the split occurs in the same -direction as the existing window combination (otherwise, a new internal -window is created anyway). - -@item window-size -In this case @code{display-buffer} makes a new parent window if it is -passed a @code{window-height} or @code{window-width} entry in the -@var{alist} argument (@pxref{Display Action Functions}). - -@item temp-buffer -This value causes the creation of a new parent window when a window is -split for showing a temporary buffer (@pxref{Temporary Displays}) only. - -@item display-buffer -This means that when @code{display-buffer} (@pxref{Choosing Window}) -splits a window it always makes a new parent window. - -@item t -In this case a new parent window is always created when splitting a -window. Thus, if the value of this variable is at all times @code{t}, -then at all times every window tree is a binary tree (a tree where each -window except the root window has exactly one sibling). -@end table - -The default is @code{nil}. Other values are reserved for future use. - -If, as a consequence of this variable's setting, @code{split-window} -makes a new parent window, it also calls -@code{set-window-combination-limit} (see below) on the newly-created -internal window. This affects how the window tree is rearranged when -the child windows are deleted (see below). -@end defopt - - If @code{window-combination-limit} is @code{t}, splitting @var{W2} in -the initial configuration of our scenario would have produced this: - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || __________________________________ || - ||| ||| - |||________________W2________________||| - || __________________________________ || - ||| ||| - |||________________W4________________||| - ||_________________W5_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -A new internal window @var{W5} has been created; its children are -@var{W2} and the new live window @var{W4}. Now, @var{W2} is the only -sibling of @var{W4}, so enlarging @var{W4} will try to shrink -@var{W2}, leaving @var{W3} unaffected. Observe that @var{W5} -represents a vertical combination of two windows embedded in the -vertical combination @var{W1}. - -@cindex window combination limit -@defun set-window-combination-limit window limit -This function sets the @dfn{combination limit} of the window -@var{window} to @var{limit}. This value can be retrieved via the -function @code{window-combination-limit}. See below for its effects; -note that it is only meaningful for internal windows. The -@code{split-window} function automatically calls this function, passing -it @code{t} as @var{limit}, provided the value of the variable -@code{window-combination-limit} is @code{t} when it is called. -@end defun - -@defun window-combination-limit window -This function returns the combination limit for @var{window}. - -The combination limit is meaningful only for an internal window. If it -is @code{nil}, then Emacs is allowed to automatically delete -@var{window}, in response to a window deletion, in order to group the -child windows of @var{window} with its sibling windows to form a new -window combination. If the combination limit is @code{t}, the child -windows of @var{window} are never automatically recombined with its -siblings. - -If, in the configuration shown at the beginning of this section, the -combination limit of @var{W4} (the parent window of @var{W6} and -@var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete -@var{W4} too. -@end defun - -Alternatively, the problems sketched above can be avoided by always -resizing all windows in the same combination whenever one of its windows -is split or deleted. This also permits to split windows that would be -otherwise too small for such an operation. - -@defopt window-combination-resize -If this variable is @code{nil}, @code{split-window} can only split a -window (denoted by @var{window}) if @var{window}'s screen area is large -enough to accommodate both itself and the new window. - -If this variable is @code{t}, @code{split-window} tries to resize all -windows that are part of the same combination as @var{window}, in order -to accommodate the new window. In particular, this may allow -@code{split-window} to succeed even if @var{window} is a fixed-size -window or too small to ordinarily split. Furthermore, subsequently -resizing or deleting @var{window} may resize all other windows in its -combination. - -The default is @code{nil}. Other values are reserved for future use. -The value of this variable is ignored when -@code{window-combination-limit} is non-@code{nil}. -@end defopt - - To illustrate the effect of @code{window-combination-resize}, consider -the following frame layout. - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -If @code{window-combination-resize} is @code{nil}, splitting window -@var{W3} leaves the size of @var{W2} unchanged: - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - ||_________________W3_________________|| - | ____________________________________ | - || || - ||_________________W4_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -If @code{window-combination-resize} is @code{t}, splitting @var{W3} -instead leaves all three live windows with approximately the same -height: - -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - | ____________________________________ | - || || - || || - ||_________________W4_________________|| - |__________________W1__________________| - -@end group -@end smallexample - -@noindent -Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will -distribute its space proportionally among the two remaining live -windows. - - -@node Selecting Windows -@section Selecting Windows -@cindex selecting a window - -@defun select-window window &optional norecord -This function makes @var{window} the selected window and the window -selected within its frame (@pxref{Basic Windows}) and selects that -frame. It also makes @var{window}'s buffer (@pxref{Buffers and -Windows}) current and sets that buffer's value of @code{point} to the -value of @code{window-point} (@pxref{Window Point}) in @var{window}. -@var{window} must be a live window. The return value is @var{window}. - -By default, this function also moves @var{window}'s buffer to the front -of the buffer list (@pxref{Buffer List}), and makes @var{window} the -most recently selected window. However, if the optional argument -@var{norecord} is non-@code{nil}, these additional actions are omitted. - -This function runs @code{buffer-list-update-hook} (@pxref{Buffer List}) -unless @var{norecord} is non-@code{nil}. Note that applications and -internal routines often temporarily select a window in order to simplify -coding. As a rule, such selections (including those made by the macros -@code{save-selected-window} and @code{with-selected-window} below) are -not recorded thus avoiding to pollute @code{buffer-list-update-hook}. -Selections that ``really count'' are those causing a visible change in -the next redisplay of @var{window}'s frame and should be always -recorded. This also means that to run a function each time a window -gets selected, putting it on @code{buffer-list-update-hook} should be -the right choice. -@end defun - -@cindex most recently selected windows - The sequence of calls to @code{select-window} with a non-@code{nil} -@var{norecord} argument determines an ordering of windows by their -selection time. The function @code{get-lru-window} can be used to -retrieve the least recently selected live window (@pxref{Cyclic Window -Ordering}). - -@defmac save-selected-window forms@dots{} -This macro records the selected frame, as well as the selected window -of each frame, executes @var{forms} in sequence, then restores the -earlier selected frame and windows. It also saves and restores the -current buffer. It returns the value of the last form in @var{forms}. - -This macro does not save or restore anything about the sizes, -arrangement or contents of windows; therefore, if @var{forms} change -them, the change persists. If the previously selected window of some -frame is no longer live at the time of exit from @var{forms}, that -frame's selected window is left alone. If the previously selected -window is no longer live, then whatever window is selected at the end of -@var{forms} remains selected. The current buffer is restored if and -only if it is still live when exiting @var{forms}. - -This macro changes neither the ordering of recently selected windows nor -the buffer list. -@end defmac - -@defmac with-selected-window window forms@dots{} -This macro selects @var{window}, executes @var{forms} in sequence, then -restores the previously selected window and current buffer. The ordering -of recently selected windows and the buffer list remain unchanged unless -you deliberately change them within @var{forms}; for example, by calling -@code{select-window} with argument @var{norecord} @code{nil}. - -This macro does not change the order of recently selected windows or -the buffer list. -@end defmac - -@defun frame-selected-window &optional frame -This function returns the window on @var{frame} that is selected -within that frame. @var{frame} should be a live frame; if omitted or -@code{nil}, it defaults to the selected frame. -@end defun - -@defun set-frame-selected-window frame window &optional norecord -This function makes @var{window} the window selected within the frame -@var{frame}. @var{frame} should be a live frame; if @code{nil}, it -defaults to the selected frame. @var{window} should be a live window; -if @code{nil}, it defaults to the selected window. - -If @var{frame} is the selected frame, this makes @var{window} the -selected window. - -If the optional argument @var{norecord} is non-@code{nil}, this -function does not alter the list of most recently selected windows, -nor the buffer list. -@end defun - -@node Cyclic Window Ordering -@section Cyclic Ordering of Windows -@cindex cyclic ordering of windows -@cindex ordering of windows, cyclic -@cindex window ordering, cyclic - - When you use the command @kbd{C-x o} (@code{other-window}) to select -some other window, it moves through live windows in a specific order. -For any given configuration of windows, this order never varies. It -is called the @dfn{cyclic ordering of windows}. - - The ordering is determined by a depth-first traversal of the frame's -window tree, retrieving the live windows which are the leaf nodes of -the tree (@pxref{Windows and Frames}). If the minibuffer is active, -the minibuffer window is included too. The ordering is cyclic, so the -last window in the sequence is followed by the first one. - -@defun next-window &optional window minibuf all-frames -@cindex minibuffer window, and @code{next-window} -This function returns a live window, the one following @var{window} in -the cyclic ordering of windows. @var{window} should be a live window; -if omitted or @code{nil}, it defaults to the selected window. - -The optional argument @var{minibuf} specifies whether minibuffer windows -should be included in the cyclic ordering. Normally, when @var{minibuf} -is @code{nil}, a minibuffer window is included only if it is currently -``active''; this matches the behavior of @kbd{C-x o}. (Note that a -minibuffer window is active as long as its minibuffer is in use; see -@ref{Minibuffers}). - -If @var{minibuf} is @code{t}, the cyclic ordering includes all -minibuffer windows. If @var{minibuf} is neither @code{t} nor -@code{nil}, minibuffer windows are not included even if they are active. - -The optional argument @var{all-frames} specifies which frames to -consider: - -@itemize @bullet -@item @code{nil} -means to consider windows on @var{window}'s frame. If the minibuffer -window is considered (as specified by the @var{minibuf} argument), -then frames that share the minibuffer window are considered too. - -@item @code{t} -means to consider windows on all existing frames. - -@item @code{visible} -means to consider windows on all visible frames. - -@item 0 -means to consider windows on all visible or iconified frames. - -@item A frame -means to consider windows on that specific frame. - -@item Anything else -means to consider windows on @var{window}'s frame, and no others. -@end itemize - -If more than one frame is considered, the cyclic ordering is obtained -by appending the orderings for those frames, in the same order as the -list of all live frames (@pxref{Finding All Frames}). -@end defun - -@defun previous-window &optional window minibuf all-frames -This function returns a live window, the one preceding @var{window} in -the cyclic ordering of windows. The other arguments are handled like -in @code{next-window}. -@end defun - -@deffn Command other-window count &optional all-frames -This function selects a live window, one @var{count} places from the -selected window in the cyclic ordering of windows. If @var{count} is -a positive number, it skips @var{count} windows forwards; if -@var{count} is negative, it skips @minus{}@var{count} windows -backwards; if @var{count} is zero, that simply re-selects the selected -window. When called interactively, @var{count} is the numeric prefix -argument. - -The optional argument @var{all-frames} has the same meaning as in -@code{next-window}, like a @code{nil} @var{minibuf} argument to -@code{next-window}. - -This function does not select a window that has a non-@code{nil} -@code{no-other-window} window parameter (@pxref{Window Parameters}). -@end deffn - -@defun walk-windows fun &optional minibuf all-frames -This function calls the function @var{fun} once for each live window, -with the window as the argument. - -It follows the cyclic ordering of windows. The optional arguments -@var{minibuf} and @var{all-frames} specify the set of windows -included; these have the same arguments as in @code{next-window}. If -@var{all-frames} specifies a frame, the first window walked is the -first window on that frame (the one returned by -@code{frame-first-window}), not necessarily the selected window. - -If @var{fun} changes the window configuration by splitting or deleting -windows, that does not alter the set of windows walked, which is -determined prior to calling @var{fun} for the first time. -@end defun - -@defun one-window-p &optional no-mini all-frames -This function returns @code{t} if the selected window is the only live -window, and @code{nil} otherwise. - -If the minibuffer window is active, it is normally considered (so that -this function returns @code{nil}). However, if the optional argument -@var{no-mini} is non-@code{nil}, the minibuffer window is ignored even -if active. The optional argument @var{all-frames} has the same -meaning as for @code{next-window}. -@end defun - -@cindex finding windows - The following functions return a window which satisfies some -criterion, without selecting it: - -@cindex least recently used window -@defun get-lru-window &optional all-frames dedicated not-selected -This function returns a live window which is heuristically the ``least -recently used'' window. The optional argument @var{all-frames} has -the same meaning as in @code{next-window}. - -If any full-width windows are present, only those windows are -considered. A minibuffer window is never a candidate. A dedicated -window (@pxref{Dedicated Windows}) is never a candidate unless the -optional argument @var{dedicated} is non-@code{nil}. The selected -window is never returned, unless it is the only candidate. However, if -the optional argument @var{not-selected} is non-@code{nil}, this -function returns @code{nil} in that case. -@end defun - -@cindex largest window -@defun get-largest-window &optional all-frames dedicated not-selected -This function returns the window with the largest area (height times -width). The optional argument @var{all-frames} specifies the windows to -search, and has the same meaning as in @code{next-window}. - -A minibuffer window is never a candidate. A dedicated window -(@pxref{Dedicated Windows}) is never a candidate unless the optional -argument @var{dedicated} is non-@code{nil}. The selected window is not -a candidate if the optional argument @var{not-selected} is -non-@code{nil}. If the optional argument @var{not-selected} is -non-@code{nil} and the selected window is the only candidate, this -function returns @code{nil}. - -If there are two candidate windows of the same size, this function -prefers the one that comes first in the cyclic ordering of windows, -starting from the selected window. -@end defun - -@cindex window that satisfies a predicate -@cindex conditional selection of windows -@defun get-window-with-predicate predicate &optional minibuf all-frames default -This function calls the function @var{predicate} for each of the -windows in the cyclic order of windows in turn, passing it the window -as an argument. If the predicate returns non-@code{nil} for any -window, this function stops and returns that window. If no such -window is found, the return value is @var{default} (which defaults to -@code{nil}). - -The optional arguments @var{minibuf} and @var{all-frames} specify the -windows to search, and have the same meanings as in -@code{next-window}. -@end defun - - -@node Buffers and Windows -@section Buffers and Windows -@cindex examining windows -@cindex windows, controlling precisely -@cindex buffers, controlled in windows - - This section describes low-level functions for examining and setting -the contents of windows. @xref{Switching Buffers}, for higher-level -functions for displaying a specific buffer in a window. - -@defun window-buffer &optional window -This function returns the buffer that @var{window} is displaying. If -@var{window} is omitted or @code{nil} it defaults to the selected -window. If @var{window} is an internal window, this function returns -@code{nil}. -@end defun - -@defun set-window-buffer window buffer-or-name &optional keep-margins -This function makes @var{window} display @var{buffer-or-name}. -@var{window} should be a live window; if @code{nil}, it defaults to -the selected window. @var{buffer-or-name} should be a buffer, or the -name of an existing buffer. This function does not change which -window is selected, nor does it directly change which buffer is -current (@pxref{Current Buffer}). Its return value is @code{nil}. - -If @var{window} is @dfn{strongly dedicated} to a buffer and -@var{buffer-or-name} does not specify that buffer, this function -signals an error. @xref{Dedicated Windows}. - -By default, this function resets @var{window}'s position, display -margins, fringe widths, and scroll bar settings, based on the local -variables in the specified buffer. However, if the optional argument -@var{keep-margins} is non-@code{nil}, it leaves the display margins -and fringe widths unchanged. - -When writing an application, you should normally use the higher-level -functions described in @ref{Switching Buffers}, instead of calling -@code{set-window-buffer} directly. - -This runs @code{window-scroll-functions}, followed by -@code{window-configuration-change-hook}. @xref{Window Hooks}. -@end defun - -@defvar buffer-display-count -This buffer-local variable records the number of times a buffer has been -displayed in a window. It is incremented each time -@code{set-window-buffer} is called for the buffer. -@end defvar - -@defvar buffer-display-time -This buffer-local variable records the time at which a buffer was last -displayed in a window. The value is @code{nil} if the buffer has -never been displayed. It is updated each time -@code{set-window-buffer} is called for the buffer, with the value -returned by @code{current-time} (@pxref{Time of Day}). -@end defvar - -@defun get-buffer-window &optional buffer-or-name all-frames -This function returns the first window displaying @var{buffer-or-name} -in the cyclic ordering of windows, starting from the selected window -(@pxref{Cyclic Window Ordering}). If no such window exists, the -return value is @code{nil}. - -@var{buffer-or-name} should be a buffer or the name of a buffer; if -omitted or @code{nil}, it defaults to the current buffer. The -optional argument @var{all-frames} specifies which windows to -consider: - -@itemize @bullet -@item -@code{t} means consider windows on all existing frames. -@item -@code{visible} means consider windows on all visible frames. -@item -0 means consider windows on all visible or iconified frames. -@item -A frame means consider windows on that frame only. -@item -Any other value means consider windows on the selected frame. -@end itemize - -Note that these meanings differ slightly from those of the -@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window -Ordering}). This function may be changed in a future version of Emacs -to eliminate this discrepancy. -@end defun - -@defun get-buffer-window-list &optional buffer-or-name minibuf all-frames -This function returns a list of all windows currently displaying -@var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the -name of an existing buffer. If omitted or @code{nil}, it defaults to -the current buffer. - -The arguments @var{minibuf} and @var{all-frames} have the same -meanings as in the function @code{next-window} (@pxref{Cyclic Window -Ordering}). Note that the @var{all-frames} argument does @emph{not} -behave exactly like in @code{get-buffer-window}. -@end defun - -@deffn Command replace-buffer-in-windows &optional buffer-or-name -This command replaces @var{buffer-or-name} with some other buffer, in -all windows displaying it. @var{buffer-or-name} should be a buffer, or -the name of an existing buffer; if omitted or @code{nil}, it defaults to -the current buffer. - -The replacement buffer in each window is chosen via -@code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated -window displaying @var{buffer-or-name} is deleted if possible -(@pxref{Dedicated Windows}). If such a window is the only window on its -frame and there are other frames on the same terminal, the frame is -deleted as well. If the dedicated window is the only window on the only -frame on its terminal, the buffer is replaced anyway. -@end deffn - - -@node Switching Buffers -@section Switching to a Buffer in a Window -@cindex switching to a buffer -@cindex displaying a buffer - -This section describes high-level functions for switching to a specified -buffer in some window. In general, ``switching to a buffer'' means to -(1) show the buffer in some window, (2) make that window the selected -window (and its frame the selected frame), and (3) make the buffer the -current buffer. - - Do @emph{not} use these functions to make a buffer temporarily -current just so a Lisp program can access or modify it. They have -side-effects, such as changing window histories (@pxref{Window -History}), which will surprise the user if used that way. If you want -to make a buffer current to modify it in Lisp, use -@code{with-current-buffer}, @code{save-current-buffer}, or -@code{set-buffer}. @xref{Current Buffer}. - -@deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window -This command attempts to display @var{buffer-or-name} in the selected -window and make it the current buffer. It is often used interactively -(as the binding of @kbd{C-x b}), as well as in Lisp programs. The -return value is the buffer switched to. - -If @var{buffer-or-name} is @code{nil}, it defaults to the buffer -returned by @code{other-buffer} (@pxref{Buffer List}). If -@var{buffer-or-name} is a string that is not the name of any existing -buffer, this function creates a new buffer with that name; the new -buffer's major mode is determined by the variable @code{major-mode} -(@pxref{Major Modes}). - -Normally, the specified buffer is put at the front of the buffer -list---both the global buffer list and the selected frame's buffer -list (@pxref{Buffer List}). However, this is not done if the -optional argument @var{norecord} is non-@code{nil}. - -Sometimes, @code{switch-to-buffer} may be unable to display the buffer -in the selected window. This happens if the selected window is a -minibuffer window, or if the selected window is strongly dedicated to -its buffer (@pxref{Dedicated Windows}). In that case, the command -normally tries to display the buffer in some other window, by invoking -@code{pop-to-buffer} (see below). However, if the optional argument -@var{force-same-window} is non-@code{nil}, it signals an error -instead. -@end deffn - -By default, @code{switch-to-buffer} shows the buffer at its position of -@code{point}. This behavior can be tuned using the following option. - -@defopt switch-to-buffer-preserve-window-point -If this variable is @code{nil}, @code{switch-to-buffer} displays the -buffer specified by @var{buffer-or-name} at the position of that -buffer's @code{point}. If this variable is @code{already-displayed}, it -tries to display the buffer at its previous position in the selected -window, provided the buffer is currently displayed in some other window -on any visible or iconified frame. If this variable is @code{t}, -@code{switch-to-buffer} unconditionally tries to display the buffer at -its previous position in the selected window. - -This variable is ignored if the buffer is already displayed in the -selected window or never appeared in it before, or if -@code{switch-to-buffer} calls @code{pop-to-buffer} to display the -buffer. -@end defopt - -The next two commands are similar to @code{switch-to-buffer}, except for -the described features. - -@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord -This function displays the buffer specified by @var{buffer-or-name} in -some window other than the selected window. It uses the function -@code{pop-to-buffer} internally (see below). - -If the selected window already displays the specified buffer, it -continues to do so, but another window is nonetheless found to display -it as well. - -The @var{buffer-or-name} and @var{norecord} arguments have the same -meanings as in @code{switch-to-buffer}. -@end deffn - -@deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord -This function displays the buffer specified by @var{buffer-or-name} in a -new frame. It uses the function @code{pop-to-buffer} internally (see -below). - -If the specified buffer is already displayed in another window, in any -frame on the current terminal, this switches to that window instead of -creating a new frame. However, the selected window is never used for -this. - -The @var{buffer-or-name} and @var{norecord} arguments have the same -meanings as in @code{switch-to-buffer}. -@end deffn - -The above commands use the function @code{pop-to-buffer}, which -flexibly displays a buffer in some window and selects that window for -editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for -displaying the buffer. Hence, all the variables affecting -@code{display-buffer} will affect it as well. @xref{Choosing Window}, -for the documentation of @code{display-buffer}. - -@deffn Command pop-to-buffer buffer-or-name &optional action norecord -This function makes @var{buffer-or-name} the current buffer and -displays it in some window, preferably not the window previously -selected. It then selects the displaying window. If that window is -on a different graphical frame, that frame is given input focus if -possible (@pxref{Input Focus}). The return value is the buffer that -was switched to. - -If @var{buffer-or-name} is @code{nil}, it defaults to the buffer -returned by @code{other-buffer} (@pxref{Buffer List}). If -@var{buffer-or-name} is a string that is not the name of any existing -buffer, this function creates a new buffer with that name; the new -buffer's major mode is determined by the variable @code{major-mode} -(@pxref{Major Modes}). - -If @var{action} is non-@code{nil}, it should be a display action to -pass to @code{display-buffer} (@pxref{Choosing Window}). -Alternatively, a non-@code{nil}, non-list value means to pop to a -window other than the selected one---even if the buffer is already -displayed in the selected window. - -Like @code{switch-to-buffer}, this function updates the buffer list -unless @var{norecord} is non-@code{nil}. -@end deffn - - -@node Choosing Window -@section Choosing a Window for Display - - The command @code{display-buffer} flexibly chooses a window for -display, and displays a specified buffer in that window. It can be -called interactively, via the key binding @kbd{C-x 4 C-o}. It is also -used as a subroutine by many functions and commands, including -@code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching -Buffers}). - -@cindex display action -@cindex action function, for @code{display-buffer} -@cindex action alist, for @code{display-buffer} - This command performs several complex steps to find a window to -display in. These steps are described by means of @dfn{display -actions}, which have the form @code{(@var{function} . @var{alist})}. -Here, @var{function} is either a function or a list of functions, -which we refer to as @dfn{action functions}; @var{alist} is an -association list, which we refer to as @dfn{action alists}. - - An action function accepts two arguments: the buffer to display and -an action alist. It attempts to display the buffer in some window, -picking or creating a window according to its own criteria. If -successful, it returns the window; otherwise, it returns @code{nil}. -@xref{Display Action Functions}, for a list of predefined action -functions. - - @code{display-buffer} works by combining display actions from -several sources, and calling the action functions in turn, until one -of them manages to display the buffer and returns a non-@code{nil} -value. - -@deffn Command display-buffer buffer-or-name &optional action frame -This command makes @var{buffer-or-name} appear in some window, without -selecting the window or making the buffer current. The argument -@var{buffer-or-name} must be a buffer or the name of an existing -buffer. The return value is the window chosen to display the buffer. - -The optional argument @var{action}, if non-@code{nil}, should normally -be a display action (described above). @code{display-buffer} builds a -list of action functions and an action alist, by consolidating display -actions from the following sources (in order): - -@itemize -@item -The variable @code{display-buffer-overriding-action}. - -@item -The user option @code{display-buffer-alist}. - -@item -The @var{action} argument. - -@item -The user option @code{display-buffer-base-action}. - -@item -The constant @code{display-buffer-fallback-action}. -@end itemize - -@noindent -Each action function is called in turn, passing the buffer as the -first argument and the combined action alist as the second argument, -until one of the functions returns non-@code{nil}. The caller can -pass @code{(allow-no-window . t)} as an element of the action alist to -indicate its readiness to handle the case of not displaying the -buffer in a window. - -The argument @var{action} can also have a non-@code{nil}, non-list -value. This has the special meaning that the buffer should be -displayed in a window other than the selected one, even if the -selected window is already displaying it. If called interactively -with a prefix argument, @var{action} is @code{t}. - -The optional argument @var{frame}, if non-@code{nil}, specifies which -frames to check when deciding whether the buffer is already displayed. -It is equivalent to adding an element @code{(reusable-frames -. @var{frame})} to the action alist of @var{action}. @xref{Display -Action Functions}. -@end deffn - -@defvar display-buffer-overriding-action -The value of this variable should be a display action, which is -treated with the highest priority by @code{display-buffer}. The -default value is empty, i.e., @code{(nil . nil)}. -@end defvar - -@defopt display-buffer-alist -The value of this option is an alist mapping conditions to display -actions. Each condition may be either a regular expression matching a -buffer name or a function that takes two arguments: a buffer name and -the @var{action} argument passed to @code{display-buffer}. If the name -of the buffer passed to @code{display-buffer} either matches a regular -expression in this alist or the function specified by a condition -returns non-@code{nil}, then @code{display-buffer} uses the -corresponding display action to display the buffer. -@end defopt - -@defopt display-buffer-base-action -The value of this option should be a display action. This option can -be used to define a ``standard'' display action for calls to -@code{display-buffer}. -@end defopt - -@defvr Constant display-buffer-fallback-action -This display action specifies the fallback behavior for -@code{display-buffer} if no other display actions are given. -@end defvr - - -@node Display Action Functions -@section Action Functions for @code{display-buffer} - -The following basic action functions are defined in Emacs. Each of -these functions takes two arguments: @var{buffer}, the buffer to -display, and @var{alist}, an action alist. Each action function -returns the window if it succeeds, and @code{nil} if it fails. - -@defun display-buffer-same-window buffer alist -This function tries to display @var{buffer} in the selected window. -It fails if the selected window is a minibuffer window or is dedicated -to another buffer (@pxref{Dedicated Windows}). It also fails if -@var{alist} has a non-@code{nil} @code{inhibit-same-window} entry. -@end defun - -@defun display-buffer-reuse-window buffer alist -This function tries to ``display'' @var{buffer} by finding a window -that is already displaying it. - -If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, -the selected window is not eligible for reuse. If @var{alist} -contains a @code{reusable-frames} entry, its value determines which -frames to search for a reusable window: - -@itemize @bullet -@item -@code{nil} means consider windows on the selected frame. -(Actually, the last non-minibuffer frame.) -@item -@code{t} means consider windows on all frames. -@item -@code{visible} means consider windows on all visible frames. -@item -0 means consider windows on all visible or iconified frames. -@item -A frame means consider windows on that frame only. -@end itemize - -Note that these meanings differ slightly from those of the -@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window -Ordering}). - -If @var{alist} contains no @code{reusable-frames} entry, this function -normally searches just the selected frame; however, if the variable -@code{pop-up-frames} is non-@code{nil}, it searches all frames on the -current terminal. @xref{Choosing Window Options}. - -If this function chooses a window on another frame, it makes that frame -visible and, unless @var{alist} contains an @code{inhibit-switch-frame} -entry (@pxref{Choosing Window Options}), raises that frame if necessary. -@end defun - -@defun display-buffer-pop-up-frame buffer alist -This function creates a new frame, and displays the buffer in that -frame's window. It actually performs the frame creation by calling -the function specified in @code{pop-up-frame-function} -(@pxref{Choosing Window Options}). If @var{alist} contains a -@code{pop-up-frame-parameters} entry, the associated value -is added to the newly created frame's parameters. -@end defun - -@defun display-buffer-pop-up-window buffer alist -This function tries to display @var{buffer} by splitting the largest -or least recently-used window (typically one on the selected frame). -It actually performs the split by calling the function specified in -@code{split-window-preferred-function} (@pxref{Choosing Window -Options}). - -The size of the new window can be adjusted by supplying -@code{window-height} and @code{window-width} entries in @var{alist}. To -adjust the window's height, use an entry whose @sc{car} is -@code{window-height} and whose @sc{cdr} is one of: - -@itemize @bullet -@item -@code{nil} means to leave the height of the new window alone. - -@item -A number specifies the desired height of the new window. An integer -specifies the number of lines of the window. A floating-point -number gives the fraction of the window's height with respect to the -height of the frame's root window. - -@item -If the @sc{cdr} specifies a function, that function is called with one -argument: the new window. The function is supposed to adjust the -height of the window; its return value is ignored. Suitable functions -are @code{shrink-window-if-larger-than-buffer} and -@code{fit-window-to-buffer}, see @ref{Resizing Windows}. -@end itemize - -To adjust the window's width, use an entry whose @sc{car} is -@code{window-width} and whose @sc{cdr} is one of: - -@itemize @bullet -@item -@code{nil} means to leave the width of the new window alone. - -@item -A number specifies the desired width of the new window. An integer -specifies the number of columns of the window. A floating-point -number gives the fraction of the window's width with respect to the -width of the frame's root window. - -@item -If the @sc{cdr} specifies a function, that function is called with one -argument: the new window. The function is supposed to adjust the width -of the window; its return value is ignored. -@end itemize - -This function can fail if no window splitting can be performed for some -reason (e.g., if the selected frame has an @code{unsplittable} frame -parameter; @pxref{Buffer Parameters}). -@end defun - -@defun display-buffer-below-selected buffer alist -This function tries to display @var{buffer} in a window below the -selected window. This means to either split the selected window or use -the window below the selected one. If it does create a new window, it -will also adjust its size provided @var{alist} contains a suitable -@code{window-height} or @code{window-width} entry, see above. -@end defun - -@defun display-buffer-in-previous-window buffer alist -This function tries to display @var{buffer} in a window previously -showing it. If @var{alist} has a non-@code{nil} -@code{inhibit-same-window} entry, the selected window is not eligible -for reuse. If @var{alist} contains a @code{reusable-frames} entry, its -value determines which frames to search for a suitable window as with -@code{display-buffer-reuse-window}. - -If @var{alist} has a @code{previous-window} entry, the window -specified by that entry will override any other window found by the -methods above, even if that window never showed @var{buffer} before. -@end defun - -@defun display-buffer-at-bottom buffer alist -This function tries to display @var{buffer} in a window at the bottom -of the selected frame. - -This either splits the window at the bottom of the frame or the -frame's root window, or reuses an existing window at the bottom of the -selected frame. -@end defun - -@defun display-buffer-use-some-window buffer alist -This function tries to display @var{buffer} by choosing an existing -window and displaying the buffer in that window. It can fail if all -windows are dedicated to another buffer (@pxref{Dedicated Windows}). -@end defun - -@defun display-buffer-no-window buffer alist -If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then -this function does not display @code{buffer}. This allows to override -the default action and avoid displaying the buffer. It is assumed that -when the caller specifies a non-@code{nil} @code{allow-no-window} value -it can handle a @code{nil} value returned from @code{display-buffer} in -this case. -@end defun - -To illustrate the use of action functions, consider the following -example. - -@example -@group -(display-buffer - (get-buffer-create "*foo*") - '((display-buffer-reuse-window - display-buffer-pop-up-window - display-buffer-pop-up-frame) - (reusable-frames . 0) - (window-height . 10) (window-width . 40))) -@end group -@end example - -@noindent -Evaluating the form above will cause @code{display-buffer} to proceed as -follows: If a buffer called *foo* already appears on a visible or -iconified frame, it will reuse its window. Otherwise, it will try to -pop up a new window or, if that is impossible, a new frame and show the -buffer there. If all these steps fail, it will proceed using whatever -@code{display-buffer-base-action} and -@code{display-buffer-fallback-action} prescribe. - - Furthermore, @code{display-buffer} will try to adjust a reused window -(provided *foo* was put by @code{display-buffer} there before) or a -popped-up window as follows: If the window is part of a vertical -combination, it will set its height to ten lines. Note that if, instead -of the number ``10'', we specified the function -@code{fit-window-to-buffer}, @code{display-buffer} would come up with a -one-line window to fit the empty buffer. If the window is part of a -horizontal combination, it sets its width to 40 columns. Whether a new -window is vertically or horizontally combined depends on the shape of -the window split and the values of -@code{split-window-preferred-function}, @code{split-height-threshold} -and @code{split-width-threshold} (@pxref{Choosing Window Options}). - - Now suppose we combine this call with a preexisting setup for -`display-buffer-alist' as follows. - -@example -@group -(let ((display-buffer-alist - (cons - '("\\*foo\\*" - (display-buffer-reuse-window display-buffer-below-selected) - (reusable-frames) - (window-height . 5)) - display-buffer-alist))) - (display-buffer - (get-buffer-create "*foo*") - '((display-buffer-reuse-window - display-buffer-pop-up-window - display-buffer-pop-up-frame) - (reusable-frames . 0) - (window-height . 10) (window-width . 40)))) -@end group -@end example - -@noindent -This form will have @code{display-buffer} first try reusing a window -that shows *foo* on the selected frame. If there's no such window, it -will try to split the selected window or, if that is impossible, use the -window below the selected window. - - If there's no window below the selected one, or the window below the -selected one is dedicated to its buffer, @code{display-buffer} will -proceed as described in the previous example. Note, however, that when -it tries to adjust the height of any reused or popped-up window, it will -in any case try to set its number of lines to ``5'' since that value -overrides the corresponding specification in the @var{action} argument -of @code{display-buffer}. - - -@node Choosing Window Options -@section Additional Options for Displaying Buffers - -The behavior of the standard display actions of @code{display-buffer} -(@pxref{Choosing Window}) can be modified by a variety of user -options. - -@defopt pop-up-windows -If the value of this variable is non-@code{nil}, @code{display-buffer} -is allowed to split an existing window to make a new window for -displaying in. This is the default. - -This variable is provided mainly for backward compatibility. It is -obeyed by @code{display-buffer} via a special mechanism in -@code{display-buffer-fallback-action}, which only calls the action -function @code{display-buffer-pop-up-window} (@pxref{Display Action -Functions}) when the value is @code{nil}. It is not consulted by -@code{display-buffer-pop-up-window} itself, which the user may specify -directly in @code{display-buffer-alist} etc. -@end defopt - -@defopt split-window-preferred-function -This variable specifies a function for splitting a window, in order to -make a new window for displaying a buffer. It is used by the -@code{display-buffer-pop-up-window} action function to actually split -the window (@pxref{Display Action Functions}). - -The default value is @code{split-window-sensibly}, which is documented -below. The value must be a function that takes one argument, a window, -and return either a new window (which will be used to display the -desired buffer) or @code{nil} (which means the splitting failed). -@end defopt - -@defun split-window-sensibly window -This function tries to split @var{window}, and return the newly -created window. If @var{window} cannot be split, it returns -@code{nil}. - -This function obeys the usual rules that determine when a window may -be split (@pxref{Splitting Windows}). It first tries to split by -placing the new window below, subject to the restriction imposed by -@code{split-height-threshold} (see below), in addition to any other -restrictions. If that fails, it tries to split by placing the new -window to the right, subject to @code{split-width-threshold} (see -below). If that fails, and the window is the only window on its -frame, this function again tries to split and place the new window -below, disregarding @code{split-height-threshold}. If this fails as -well, this function gives up and returns @code{nil}. -@end defun - -@defopt split-height-threshold -This variable, used by @code{split-window-sensibly}, specifies whether -to split the window placing the new window below. If it is an -integer, that means to split only if the original window has at least -that many lines. If it is @code{nil}, that means not to split this -way. -@end defopt - -@defopt split-width-threshold -This variable, used by @code{split-window-sensibly}, specifies whether -to split the window placing the new window to the right. If the value -is an integer, that means to split only if the original window has at -least that many columns. If the value is @code{nil}, that means not -to split this way. -@end defopt - -@defopt pop-up-frames -If the value of this variable is non-@code{nil}, that means -@code{display-buffer} may display buffers by making new frames. The -default is @code{nil}. - -A non-@code{nil} value also means that when @code{display-buffer} is -looking for a window already displaying @var{buffer-or-name}, it can -search any visible or iconified frame, not just the selected frame. - -This variable is provided mainly for backward compatibility. It is -obeyed by @code{display-buffer} via a special mechanism in -@code{display-buffer-fallback-action}, which calls the action function -@code{display-buffer-pop-up-frame} (@pxref{Display Action Functions}) -if the value is non-@code{nil}. (This is done before attempting to -split a window.) This variable is not consulted by -@code{display-buffer-pop-up-frame} itself, which the user may specify -directly in @code{display-buffer-alist} etc. -@end defopt - -@defopt pop-up-frame-function -This variable specifies a function for creating a new frame, in order -to make a new window for displaying a buffer. It is used by the -@code{display-buffer-pop-up-frame} action function (@pxref{Display -Action Functions}). - -The value should be a function that takes no arguments and returns a -frame, or @code{nil} if no frame could be created. The default value -is a function that creates a frame using the parameters specified by -@code{pop-up-frame-alist} (see below). -@end defopt - -@defopt pop-up-frame-alist -This variable holds an alist of frame parameters (@pxref{Frame -Parameters}), which is used by the default function in -@code{pop-up-frame-function} to make a new frame. The default is -@code{nil}. -@end defopt - -@defopt same-window-buffer-names -A list of buffer names for buffers that should be displayed in the -selected window. If a buffer's name is in this list, -@code{display-buffer} handles the buffer by showing it in the selected -window. -@end defopt - -@defopt same-window-regexps -A list of regular expressions that specify buffers that should be -displayed in the selected window. If the buffer's name matches any of -the regular expressions in this list, @code{display-buffer} handles the -buffer by showing it in the selected window. -@end defopt - -@defun same-window-p buffer-name -This function returns @code{t} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -put it in the selected window. -@end defun - -@node Window History -@section Window History -@cindex window history - -Each window remembers in a list the buffers it has previously displayed, -and the order in which these buffers were removed from it. This history -is used, for example, by @code{replace-buffer-in-windows} -(@pxref{Buffers and Windows}). The list is automatically maintained by -Emacs, but you can use the following functions to explicitly inspect or -alter it: - -@defun window-prev-buffers &optional window -This function returns a list specifying the previous contents of -@var{window}. The optional argument @var{window} should be a live -window and defaults to the selected one. - -Each list element has the form @code{(@var{buffer} @var{window-start} -@var{window-pos})}, where @var{buffer} is a buffer previously shown in -the window, @var{window-start} is the window start position -(@pxref{Window Start and End}) when that buffer was last shown, and -@var{window-pos} is the point position (@pxref{Window Point}) when -that buffer was last shown in @var{window}. - -The list is ordered so that earlier elements correspond to more -recently-shown buffers, and the first element usually corresponds to the -buffer most recently removed from the window. -@end defun - -@defun set-window-prev-buffers window prev-buffers -This function sets @var{window}'s previous buffers to the value of -@var{prev-buffers}. The argument @var{window} must be a live window -and defaults to the selected one. The argument @var{prev-buffers} -should be a list of the same form as that returned by -@code{window-prev-buffers}. -@end defun - -In addition, each buffer maintains a list of @dfn{next buffers}, which -is a list of buffers re-shown by @code{switch-to-prev-buffer} (see -below). This list is mainly used by @code{switch-to-prev-buffer} and -@code{switch-to-next-buffer} for choosing buffers to switch to. - -@defun window-next-buffers &optional window -This function returns the list of buffers recently re-shown in -@var{window} via @code{switch-to-prev-buffer}. The @var{window} -argument must denote a live window or @code{nil} (meaning the selected -window). -@end defun - -@defun set-window-next-buffers window next-buffers -This function sets the next buffer list of @var{window} to -@var{next-buffers}. The @var{window} argument should be a live window -or @code{nil} (meaning the selected window). The argument -@var{next-buffers} should be a list of buffers. -@end defun - -The following commands can be used to cycle through the global buffer -list, much like @code{bury-buffer} and @code{unbury-buffer}. However, -they cycle according to the specified window's history list, rather -than the global buffer list. In addition, they restore -window-specific window start and point positions, and may show a -buffer even if it is already shown in another window. The -@code{switch-to-prev-buffer} command, in particular, is used by -@code{replace-buffer-in-windows}, @code{bury-buffer} and -@code{quit-window} to find a replacement buffer for a window. - -@deffn Command switch-to-prev-buffer &optional window bury-or-kill -This command displays the previous buffer in @var{window}. The -argument @var{window} should be a live window or @code{nil} (meaning -the selected window). If the optional argument @var{bury-or-kill} is -non-@code{nil}, this means that the buffer currently shown in -@var{window} is about to be buried or killed and consequently should -not be switched to in future invocations of this command. - -The previous buffer is usually the buffer shown before the buffer -currently shown in @var{window}. However, a buffer that has been buried -or killed, or has been already shown by a recent invocation of -@code{switch-to-prev-buffer}, does not qualify as previous buffer. - -If repeated invocations of this command have already shown all buffers -previously shown in @var{window}, further invocations will show buffers -from the buffer list of the frame @var{window} appears on (@pxref{Buffer -List}), trying to skip buffers that are already shown in another window -on that frame. -@end deffn - -@deffn Command switch-to-next-buffer &optional window -This command switches to the next buffer in @var{window}, thus undoing -the effect of the last @code{switch-to-prev-buffer} command in -@var{window}. The argument @var{window} must be a live window and -defaults to the selected one. - -If there is no recent invocation of @code{switch-to-prev-buffer} that -can be undone, this function tries to show a buffer from the buffer list -of the frame @var{window} appears on (@pxref{Buffer List}). -@end deffn - -By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer} -can switch to a buffer that is already shown in another window on the -same frame. The following option can be used to override this behavior. - -@defopt switch-to-visible-buffer -If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and -@code{switch-to-next-buffer} may switch to a buffer that is already -visible on the same frame, provided the buffer was shown in the -relevant window before. If it is @code{nil}, -@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} always -try to avoid switching to a buffer that is already visible in another -window on the same frame. The default is @code{t}. -@end defopt - - -@node Dedicated Windows -@section Dedicated Windows -@cindex dedicated window - -Functions for displaying a buffer can be told to not use specific -windows by marking these windows as @dfn{dedicated} to their buffers. -@code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated -window for displaying another buffer in it. @code{get-lru-window} and -@code{get-largest-window} (@pxref{Cyclic Window Ordering}) do not -consider dedicated windows as candidates when their @var{dedicated} -argument is non-@code{nil}. The behavior of @code{set-window-buffer} -(@pxref{Buffers and Windows}) with respect to dedicated windows is -slightly different, see below. - - Functions supposed to remove a buffer from a window or a window from -a frame can behave specially when a window they operate on is dedicated. -We will distinguish three basic cases, namely where (1) the window is -not the only window on its frame, (2) the window is the only window on -its frame but there are other frames on the same terminal left, and (3) -the window is the only window on the only frame on the same terminal. - - In particular, @code{delete-windows-on} (@pxref{Deleting Windows}) -handles case (2) by deleting the associated frame and case (3) by -showing another buffer in that frame's only window. The function -@code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is -called when a buffer gets killed, deletes the window in case (1) and -behaves like @code{delete-windows-on} otherwise. -@c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)? - - When @code{bury-buffer} (@pxref{Buffer List}) operates on the -selected window (which shows the buffer that shall be buried), it -handles case (2) by calling @code{frame-auto-hide-function} -(@pxref{Quitting Windows}) to deal with the selected frame. The other -two cases are handled as with @code{replace-buffer-in-windows}. - -@defun window-dedicated-p &optional window -This function returns non-@code{nil} if @var{window} is dedicated to its -buffer and @code{nil} otherwise. More precisely, the return value is -the value assigned by the last call of @code{set-window-dedicated-p} for -@var{window}, or @code{nil} if that function was never called with -@var{window} as its argument. The default for @var{window} is the -selected window. -@end defun - -@defun set-window-dedicated-p window flag -This function marks @var{window} as dedicated to its buffer if -@var{flag} is non-@code{nil}, and non-dedicated otherwise. - -As a special case, if @var{flag} is @code{t}, @var{window} becomes -@dfn{strongly} dedicated to its buffer. @code{set-window-buffer} -signals an error when the window it acts upon is strongly dedicated to -its buffer and does not already display the buffer it is asked to -display. Other functions do not treat @code{t} differently from any -non-@code{nil} value. -@end defun - - -@node Quitting Windows -@section Quitting Windows - -When you want to get rid of a window used for displaying a buffer, you -can call @code{delete-window} or @code{delete-windows-on} -(@pxref{Deleting Windows}) to remove that window from its frame. If the -buffer is shown on a separate frame, you might want to call -@code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other -hand, a window has been reused for displaying the buffer, you might -prefer showing the buffer previously shown in that window, by calling the -function @code{switch-to-prev-buffer} (@pxref{Window History}). -Finally, you might want to either bury (@pxref{Buffer List}) or kill -(@pxref{Killing Buffers}) the window's buffer. - - The following command uses information on how the window for -displaying the buffer was obtained in the first place, thus attempting -to automate the above decisions for you. - -@deffn Command quit-window &optional kill window -This command quits @var{window} and buries its buffer. The argument -@var{window} must be a live window and defaults to the selected one. -With prefix argument @var{kill} non-@code{nil}, it kills the buffer -instead of burying it. It calls the function @code{quit-restore-window} -described next to deal with the window and its buffer. -@end deffn - -@defun quit-restore-window &optional window bury-or-kill -This function tries to restore the state of @var{window} that existed -before its buffer was displayed in it. The optional argument -@var{window} must be a live window and defaults to the selected one. - -If @var{window} was created specially for displaying its buffer, this -function deletes @var{window} provided its frame contains at least one -other live window. If @var{window} is the only window on its frame and -there are other frames on the frame's terminal, the value of the -optional argument @var{bury-or-kill} determines how to proceed with the -window. If @var{bury-or-kill} equals @code{kill}, the frame is deleted -unconditionally. Otherwise, the fate of the frame is determined by -calling @code{frame-auto-hide-function} (see below) with that frame as -sole argument. - -Otherwise, this function tries to redisplay the buffer previously shown -in @var{window}. It also tries to restore the window start -(@pxref{Window Start and End}) and point (@pxref{Window Point}) -positions of the previously shown buffer. If, in addition, -@var{window}'s buffer was temporarily resized, this function will also -try to restore the original height of @var{window}. - -The cases described so far require that the buffer shown in @var{window} -is still the buffer displayed by the last buffer display function for -this window. If another buffer has been shown in the meantime, or the -buffer previously shown no longer exists, this function calls -@code{switch-to-prev-buffer} (@pxref{Window History}) to show some other -buffer instead. - -The optional argument @var{bury-or-kill} specifies how to deal with -@var{window}'s buffer. The following values are handled: - -@table @code -@item nil -This means to not deal with the buffer in any particular way. As a -consequence, if @var{window} is not deleted, invoking -@code{switch-to-prev-buffer} will usually show the buffer again. - -@item append -This means that if @var{window} is not deleted, its buffer is moved to -the end of @var{window}'s list of previous buffers, so it's less likely -that a future invocation of @code{switch-to-prev-buffer} will switch to -it. Also, it moves the buffer to the end of the frame's buffer list. - -@item bury -This means that if @var{window} is not deleted, its buffer is removed -from @var{window}'s list of previous buffers. Also, it moves the buffer -to the end of the frame's buffer list. This value provides the most -reliable remedy to not have @code{switch-to-prev-buffer} switch to this -buffer again without killing the buffer. - -@item kill -This means to kill @var{window}'s buffer. -@end table - -@code{quit-restore-window} bases its decisions on information stored in -@var{window}'s @code{quit-restore} window parameter (@pxref{Window -Parameters}), and resets that parameter to @code{nil} after it's done. -@end defun - -The following option specifies how to deal with a frame containing just -one window that should be either quit, or whose buffer should be buried. - -@defopt frame-auto-hide-function -The function specified by this option is called to automatically hide -frames. This function is called with one argument---a frame. - -The function specified here is called by @code{bury-buffer} -(@pxref{Buffer List}) when the selected window is dedicated and shows -the buffer to bury. It is also called by @code{quit-restore-window} -(see above) when the frame of the window to quit has been specially -created for displaying that window's buffer and the buffer is not -killed. - -The default is to call @code{iconify-frame} (@pxref{Visibility of -Frames}). Alternatively, you may specify either @code{delete-frame} -(@pxref{Deleting Frames}) to remove the frame from its display, -@code{ignore} to leave the frame unchanged, or any other function that -can take a frame as its sole argument. - -Note that the function specified by this option is called only if the -specified frame contains just one live window and there is at least one -other frame on the same terminal. -@end defopt - - -@node Window Point -@section Windows and Point -@cindex window position -@cindex window point -@cindex position in window -@cindex point in window - - Each window has its own value of point (@pxref{Point}), independent of -the value of point in other windows displaying the same buffer. This -makes it useful to have multiple windows showing one buffer. - -@itemize @bullet -@item -The window point is established when a window is first created; it is -initialized from the buffer's point, or from the window point of another -window opened on the buffer if such a window exists. - -@item -Selecting a window sets the value of point in its buffer from the -window's value of point. Conversely, deselecting a window sets the -window's value of point from that of the buffer. Thus, when you switch -between windows that display a given buffer, the point value for the -selected window is in effect in the buffer, while the point values for -the other windows are stored in those windows. - -@item -As long as the selected window displays the current buffer, the window's -point and the buffer's point always move together; they remain equal. -@end itemize - -@cindex cursor - As far as the user is concerned, point is where the cursor is, and -when the user switches to another buffer, the cursor jumps to the -position of point in that buffer. - -@defun window-point &optional window -This function returns the current position of point in @var{window}. -For a nonselected window, this is the value point would have (in that -window's buffer) if that window were selected. The default for -@var{window} is the selected window. - -When @var{window} is the selected window, the value returned is the -value of point in that window's buffer. Strictly speaking, it would be -more correct to return the ``top-level'' value of point, outside of any -@code{save-excursion} forms. But that value is hard to find. -@end defun - -@defun set-window-point window position -This function positions point in @var{window} at position -@var{position} in @var{window}'s buffer. It returns @var{position}. - -If @var{window} is selected, this simply does @code{goto-char} in -@var{window}'s buffer. -@end defun - -@defvar window-point-insertion-type -This variable specifies the marker insertion type (@pxref{Marker -Insertion Types}) of @code{window-point}. The default is @code{nil}, -so @code{window-point} will stay behind text inserted there. -@end defvar - -@node Window Start and End -@section The Window Start and End Positions -@cindex window start position -@cindex display-start position - - Each window maintains a marker used to keep track of a buffer position -that specifies where in the buffer display should start. This position -is called the @dfn{display-start} position of the window (or just the -@dfn{start}). The character after this position is the one that appears -at the upper left corner of the window. It is usually, but not -inevitably, at the beginning of a text line. - - After switching windows or buffers, and in some other cases, if the -window start is in the middle of a line, Emacs adjusts the window -start to the start of a line. This prevents certain operations from -leaving the window start at a meaningless point within a line. This -feature may interfere with testing some Lisp code by executing it -using the commands of Lisp mode, because they trigger this -readjustment. To test such code, put it into a command and bind the -command to a key. - -@defun window-start &optional window -@cindex window top line -This function returns the display-start position of window -@var{window}. If @var{window} is @code{nil}, the selected window is -used. - -When you create a window, or display a different buffer in it, the -display-start position is set to a display-start position recently used -for the same buffer, or to @code{point-min} if the buffer doesn't have -any. - -Redisplay updates the window-start position (if you have not specified -it explicitly since the previous redisplay)---to make sure point appears -on the screen. Nothing except redisplay automatically changes the -window-start position; if you move point, do not expect the window-start -position to change in response until after the next redisplay. -@end defun - -@cindex window end position -@defun window-end &optional window update -This function returns the position where display of its buffer ends in -@var{window}. The default for @var{window} is the selected window. - -Simply changing the buffer text or moving point does not update the -value that @code{window-end} returns. The value is updated only when -Emacs redisplays and redisplay completes without being preempted. - -If the last redisplay of @var{window} was preempted, and did not finish, -Emacs does not know the position of the end of display in that window. -In that case, this function returns @code{nil}. - -If @var{update} is non-@code{nil}, @code{window-end} always returns an -up-to-date value for where display ends, based on the current -@code{window-start} value. If a previously saved value of that position -is still valid, @code{window-end} returns that value; otherwise it -computes the correct value by scanning the buffer text. - -Even if @var{update} is non-@code{nil}, @code{window-end} does not -attempt to scroll the display if point has moved off the screen, the -way real redisplay would do. It does not alter the -@code{window-start} value. In effect, it reports where the displayed -text will end if scrolling is not required. -@end defun - -@defun set-window-start window position &optional noforce -This function sets the display-start position of @var{window} to -@var{position} in @var{window}'s buffer. It returns @var{position}. - -The display routines insist that the position of point be visible when a -buffer is displayed. Normally, they change the display-start position -(that is, scroll the window) whenever necessary to make point visible. -However, if you specify the start position with this function using -@code{nil} for @var{noforce}, it means you want display to start at -@var{position} even if that would put the location of point off the -screen. If this does place point off screen, the display routines move -point to the left margin on the middle line in the window. - -For example, if point @w{is 1} and you set the start of the window -@w{to 37}, the start of the next line, point will be ``above'' the top -of the window. The display routines will automatically move point if -it is still 1 when redisplay occurs. Here is an example: - -@example -@group -;; @r{Here is what @samp{foo} looks like before executing} -;; @r{the @code{set-window-start} expression.} -@end group - -@group ----------- Buffer: foo ---------- -@point{}This is the contents of buffer foo. -2 -3 -4 -5 -6 ----------- Buffer: foo ---------- -@end group - -@group -(set-window-start - (selected-window) - (save-excursion - (goto-char 1) - (forward-line 1) - (point))) -@result{} 37 -@end group - -@group -;; @r{Here is what @samp{foo} looks like after executing} -;; @r{the @code{set-window-start} expression.} ----------- Buffer: foo ---------- -2 -3 -@point{}4 -5 -6 ----------- Buffer: foo ---------- -@end group -@end example - -If @var{noforce} is non-@code{nil}, and @var{position} would place point -off screen at the next redisplay, then redisplay computes a new window-start -position that works well with point, and thus @var{position} is not used. -@end defun - -@defun pos-visible-in-window-p &optional position window partially -This function returns non-@code{nil} if @var{position} is within the -range of text currently visible on the screen in @var{window}. It -returns @code{nil} if @var{position} is scrolled vertically out of view. -Locations that are partially obscured are not considered visible unless -@var{partially} is non-@code{nil}. The argument @var{position} defaults -to the current position of point in @var{window}; @var{window}, to the -selected window. If @var{position} is @code{t}, that means to check the -last visible position in @var{window}. - -This function considers only vertical scrolling. If @var{position} is -out of view only because @var{window} has been scrolled horizontally, -@code{pos-visible-in-window-p} returns non-@code{nil} anyway. -@xref{Horizontal Scrolling}. - -If @var{position} is visible, @code{pos-visible-in-window-p} returns -@code{t} if @var{partially} is @code{nil}; if @var{partially} is -non-@code{nil}, and the character following @var{position} is fully -visible, it returns a list of the form @code{(@var{x} @var{y})}, where -@var{x} and @var{y} are the pixel coordinates relative to the top left -corner of the window; otherwise it returns an extended list of the form -@code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})}, -where @var{rtop} and @var{rbot} specify the number of off-window pixels -at the top and bottom of the row at @var{position}, @var{rowh} specifies -the visible height of that row, and @var{vpos} specifies the vertical -position (zero-based row number) of that row. - -Here is an example: - -@example -@group -;; @r{If point is off the screen now, recenter it now.} -(or (pos-visible-in-window-p - (point) (selected-window)) - (recenter 0)) -@end group -@end example -@end defun - -@defun window-line-height &optional line window -This function returns the height of text line @var{line} in -@var{window}. If @var{line} is one of @code{header-line} or -@code{mode-line}, @code{window-line-height} returns information about -the corresponding line of the window. Otherwise, @var{line} is a text -line number starting from 0. A negative number counts from the end of -the window. The default for @var{line} is the current line in -@var{window}; the default for @var{window} is the selected window. - -If the display is not up to date, @code{window-line-height} returns -@code{nil}. In that case, @code{pos-visible-in-window-p} may be used -to obtain related information. - -If there is no line corresponding to the specified @var{line}, -@code{window-line-height} returns @code{nil}. Otherwise, it returns -a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, -where @var{height} is the height in pixels of the visible part of the -line, @var{vpos} and @var{ypos} are the vertical position in lines and -pixels of the line relative to the top of the first text line, and -@var{offbot} is the number of off-window pixels at the bottom of the -text line. If there are off-window pixels at the top of the (first) -text line, @var{ypos} is negative. -@end defun - -@node Textual Scrolling -@section Textual Scrolling -@cindex textual scrolling -@cindex scrolling textually - - @dfn{Textual scrolling} means moving the text up or down through a -window. It works by changing the window's display-start location. It -may also change the value of @code{window-point} to keep point on the -screen (@pxref{Window Point}). - - The basic textual scrolling functions are @code{scroll-up} (which -scrolls forward) and @code{scroll-down} (which scrolls backward). In -these function names, ``up'' and ``down'' refer to the direction of -motion of the buffer text relative to the window. Imagine that the -text is written on a long roll of paper and that the scrolling -commands move the paper up and down. Thus, if you are looking at the -middle of a buffer and repeatedly call @code{scroll-down}, you will -eventually see the beginning of the buffer. - - Unfortunately, this sometimes causes confusion, because some people -tend to think in terms of the opposite convention: they -imagine the window moving over text that remains in place, so that -``down'' commands take you to the end of the buffer. This convention -is consistent with fact that such a command is bound to a key named -@key{PageDown} on modern keyboards. -@ignore -We have not switched to this convention as that is likely to break -existing Emacs Lisp code. -@end ignore - - Textual scrolling functions (aside from @code{scroll-other-window}) -have unpredictable results if the current buffer is not the one -displayed in the selected window. @xref{Current Buffer}. - - If the window contains a row taller than the height of the window -(for example in the presence of a large image), the scroll functions -will adjust the window's vertical scroll position to scroll the -partially visible row. Lisp callers can disable this feature by -binding the variable @code{auto-window-vscroll} to @code{nil} -(@pxref{Vertical Scrolling}). - -@deffn Command scroll-up &optional count -This function scrolls forward by @var{count} lines in the selected -window. - -If @var{count} is negative, it scrolls backward instead. If -@var{count} is @code{nil} (or omitted), the distance scrolled is -@code{next-screen-context-lines} lines less than the height of the -window's text area. - -If the selected window cannot be scrolled any further, this function -signals an error. Otherwise, it returns @code{nil}. -@end deffn - -@deffn Command scroll-down &optional count -This function scrolls backward by @var{count} lines in the selected -window. - -If @var{count} is negative, it scrolls forward instead. In other -respects, it behaves the same way as @code{scroll-up} does. -@end deffn - -@deffn Command scroll-up-command &optional count -This behaves like @code{scroll-up}, except that if the selected window -cannot be scrolled any further and the value of the variable -@code{scroll-error-top-bottom} is @code{t}, it tries to move to the -end of the buffer instead. If point is already there, it signals an -error. -@end deffn - -@deffn Command scroll-down-command &optional count -This behaves like @code{scroll-down}, except that if the selected -window cannot be scrolled any further and the value of the variable -@code{scroll-error-top-bottom} is @code{t}, it tries to move to the -beginning of the buffer instead. If point is already there, it -signals an error. -@end deffn - -@deffn Command scroll-other-window &optional count -This function scrolls the text in another window upward @var{count} -lines. Negative values of @var{count}, or @code{nil}, are handled -as in @code{scroll-up}. - -You can specify which buffer to scroll by setting the variable -@code{other-window-scroll-buffer} to a buffer. If that buffer isn't -already displayed, @code{scroll-other-window} displays it in some -window. - -When the selected window is the minibuffer, the next window is normally -the leftmost one immediately above it. You can specify a different -window to scroll, when the minibuffer is selected, by setting the variable -@code{minibuffer-scroll-window}. This variable has no effect when any -other window is selected. When it is non-@code{nil} and the -minibuffer is selected, it takes precedence over -@code{other-window-scroll-buffer}. @xref{Definition of -minibuffer-scroll-window}. - -When the minibuffer is active, it is the next window if the selected -window is the one at the bottom right corner. In this case, -@code{scroll-other-window} attempts to scroll the minibuffer. If the -minibuffer contains just one line, it has nowhere to scroll to, so the -line reappears after the echo area momentarily displays the message -@samp{End of buffer}. -@end deffn - -@defvar other-window-scroll-buffer -If this variable is non-@code{nil}, it tells @code{scroll-other-window} -which buffer's window to scroll. -@end defvar - -@defopt scroll-margin -This option specifies the size of the scroll margin---a minimum number -of lines between point and the top or bottom of a window. Whenever -point gets within this many lines of the top or bottom of the window, -redisplay scrolls the text automatically (if possible) to move point -out of the margin, closer to the center of the window. -@end defopt - -@defopt scroll-conservatively -This variable controls how scrolling is done automatically when point -moves off the screen (or into the scroll margin). If the value is a -positive integer @var{n}, then redisplay scrolls the text up to -@var{n} lines in either direction, if that will bring point back into -proper view. This behavior is called @dfn{conservative scrolling}. -Otherwise, scrolling happens in the usual way, under the control of -other variables such as @code{scroll-up-aggressively} and -@code{scroll-down-aggressively}. - -The default value is zero, which means that conservative scrolling -never happens. -@end defopt - -@defopt scroll-down-aggressively -The value of this variable should be either @code{nil} or a fraction -@var{f} between 0 and 1. If it is a fraction, that specifies where on -the screen to put point when scrolling down. More precisely, when a -window scrolls down because point is above the window start, the new -start position is chosen to put point @var{f} part of the window -height from the top. The larger @var{f}, the more aggressive the -scrolling. - -A value of @code{nil} is equivalent to .5, since its effect is to center -point. This variable automatically becomes buffer-local when set in any -fashion. -@end defopt - -@defopt scroll-up-aggressively -Likewise, for scrolling up. The value, @var{f}, specifies how far -point should be placed from the bottom of the window; thus, as with -@code{scroll-up-aggressively}, a larger value scrolls more aggressively. -@end defopt - -@defopt scroll-step -This variable is an older variant of @code{scroll-conservatively}. -The difference is that if its value is @var{n}, that permits scrolling -only by precisely @var{n} lines, not a smaller number. This feature -does not work with @code{scroll-margin}. The default value is zero. -@end defopt - -@cindex @code{scroll-command} property -@defopt scroll-preserve-screen-position -If this option is @code{t}, whenever a scrolling command moves point -off-window, Emacs tries to adjust point to keep the cursor at its old -vertical position in the window, rather than the window edge. - -If the value is non-@code{nil} and not @code{t}, Emacs adjusts point -to keep the cursor at the same vertical position, even if the -scrolling command didn't move point off-window. - -This option affects all scroll commands that have a non-@code{nil} -@code{scroll-command} symbol property. -@end defopt - -@defopt next-screen-context-lines -The value of this variable is the number of lines of continuity to -retain when scrolling by full screens. For example, @code{scroll-up} -with an argument of @code{nil} scrolls so that this many lines at the -bottom of the window appear instead at the top. The default value is -@code{2}. -@end defopt - -@defopt scroll-error-top-bottom -If this option is @code{nil} (the default), @code{scroll-up-command} -and @code{scroll-down-command} simply signal an error when no more -scrolling is possible. - -If the value is @code{t}, these commands instead move point to the -beginning or end of the buffer (depending on scrolling direction); -only if point is already on that position do they signal an error. -@end defopt - -@deffn Command recenter &optional count -@cindex centering point -This function scrolls the text in the selected window so that point is -displayed at a specified vertical position within the window. It does -not ``move point'' with respect to the text. - -If @var{count} is a non-negative number, that puts the line containing -point @var{count} lines down from the top of the window. If -@var{count} is a negative number, then it counts upward from the -bottom of the window, so that @minus{}1 stands for the last usable -line in the window. - -If @var{count} is @code{nil} (or a non-@code{nil} list), -@code{recenter} puts the line containing point in the middle of the -window. If @var{count} is @code{nil}, this function may redraw the -frame, according to the value of @code{recenter-redisplay}. - -When @code{recenter} is called interactively, @var{count} is the raw -prefix argument. Thus, typing @kbd{C-u} as the prefix sets the -@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets -@var{count} to 4, which positions the current line four lines from the -top. - -With an argument of zero, @code{recenter} positions the current line at -the top of the window. The command @code{recenter-top-bottom} offers -a more convenient way to achieve this. -@end deffn - -@defopt recenter-redisplay -If this variable is non-@code{nil}, calling @code{recenter} with a -@code{nil} argument redraws the frame. The default value is -@code{tty}, which means only redraw the frame if it is a tty frame. -@end defopt - -@deffn Command recenter-top-bottom &optional count -This command, which is the default binding for @kbd{C-l}, acts like -@code{recenter}, except if called with no argument. In that case, -successive calls place point according to the cycling order defined -by the variable @code{recenter-positions}. -@end deffn - -@defopt recenter-positions -This variable controls how @code{recenter-top-bottom} behaves when -called with no argument. The default value is @code{(middle top -bottom)}, which means that successive calls of -@code{recenter-top-bottom} with no argument cycle between placing -point at the middle, top, and bottom of the window. -@end defopt - - -@node Vertical Scrolling -@section Vertical Fractional Scrolling -@cindex vertical fractional scrolling -@cindex vertical scroll position - - @dfn{Vertical fractional scrolling} means shifting text in a window -up or down by a specified multiple or fraction of a line. Each window -has a @dfn{vertical scroll position}, which is a number, never less than -zero. It specifies how far to raise the contents of the window. -Raising the window contents generally makes all or part of some lines -disappear off the top, and all or part of some other lines appear at the -bottom. The usual value is zero. - - The vertical scroll position is measured in units of the normal line -height, which is the height of the default font. Thus, if the value is -.5, that means the window contents are scrolled up half the normal line -height. If it is 3.3, that means the window contents are scrolled up -somewhat over three times the normal line height. - - What fraction of a line the vertical scrolling covers, or how many -lines, depends on what the lines contain. A value of .5 could scroll a -line whose height is very short off the screen, while a value of 3.3 -could scroll just part of the way through a tall line or an image. - -@defun window-vscroll &optional window pixels-p -This function returns the current vertical scroll position of -@var{window}. The default for @var{window} is the selected window. -If @var{pixels-p} is non-@code{nil}, the return value is measured in -pixels, rather than in units of the normal line height. - -@example -@group -(window-vscroll) - @result{} 0 -@end group -@end example -@end defun - -@defun set-window-vscroll window lines &optional pixels-p -This function sets @var{window}'s vertical scroll position to -@var{lines}. If @var{window} is @code{nil}, the selected window is -used. The argument @var{lines} should be zero or positive; if not, it -is taken as zero. - - -The actual vertical scroll position must always correspond -to an integral number of pixels, so the value you specify -is rounded accordingly. - -The return value is the result of this rounding. - -@example -@group -(set-window-vscroll (selected-window) 1.2) - @result{} 1.13 -@end group -@end example - -If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of -pixels. In this case, the return value is @var{lines}. -@end defun - -@defvar auto-window-vscroll -If this variable is non-@code{nil}, the @code{line-move}, -@code{scroll-up}, and @code{scroll-down} functions will automatically -modify the vertical scroll position to scroll through display rows -that are taller than the height of the window, for example in the -presence of large images. -@end defvar - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - - @dfn{Horizontal scrolling} means shifting the image in the window left -or right by a specified multiple of the normal character width. Each -window has a @dfn{horizontal scroll position}, which is a number, never -less than zero. It specifies how far to shift the contents left. -Shifting the window contents left generally makes all or part of some -characters disappear off the left, and all or part of some other -characters appear at the right. The usual value is zero. - - The horizontal scroll position is measured in units of the normal -character width, which is the width of space in the default font. Thus, -if the value is 5, that means the window contents are scrolled left by 5 -times the normal character width. How many characters actually -disappear off to the left depends on their width, and could vary from -line to line. - - Because we read from side to side in the ``inner loop'', and from top -to bottom in the ``outer loop'', the effect of horizontal scrolling is -not like that of textual or vertical scrolling. Textual scrolling -involves selection of a portion of text to display, and vertical -scrolling moves the window contents contiguously; but horizontal -scrolling causes part of @emph{each line} to go off screen. - - Usually, no horizontal scrolling is in effect; then the leftmost -column is at the left edge of the window. In this state, scrolling to -the right is meaningless, since there is no data to the left of the edge -to be revealed by it; so this is not allowed. Scrolling to the left is -allowed; it scrolls the first columns of text off the edge of the window -and can reveal additional columns on the right that were truncated -before. Once a window has a nonzero amount of leftward horizontal -scrolling, you can scroll it back to the right, but only so far as to -reduce the net horizontal scroll to zero. There is no limit to how far -left you can scroll, but eventually all the text will disappear off the -left edge. - -@vindex auto-hscroll-mode - If @code{auto-hscroll-mode} is set, redisplay automatically alters -the horizontal scrolling of a window as necessary to ensure that point -is always visible. However, you can still set the horizontal -scrolling value explicitly. The value you specify serves as a lower -bound for automatic scrolling, i.e., automatic scrolling will not -scroll a window to a column less than the specified one. - -@deffn Command scroll-left &optional count set-minimum -This function scrolls the selected window @var{count} columns to the -left (or to the right if @var{count} is negative). The default -for @var{count} is the window width, minus 2. - -The return value is the total amount of leftward horizontal scrolling in -effect after the change---just like the value returned by -@code{window-hscroll} (below). - -Once you scroll a window as far right as it can go, back to its normal -position where the total leftward scrolling is zero, attempts to scroll -any farther right have no effect. - -If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes -the lower bound for automatic scrolling; that is, automatic scrolling -will not scroll a window to a column less than the value returned by -this function. Interactive calls pass non-@code{nil} for -@var{set-minimum}. -@end deffn - -@deffn Command scroll-right &optional count set-minimum -This function scrolls the selected window @var{count} columns to the -right (or to the left if @var{count} is negative). The default -for @var{count} is the window width, minus 2. Aside from the direction -of scrolling, this works just like @code{scroll-left}. -@end deffn - -@defun window-hscroll &optional window -This function returns the total leftward horizontal scrolling of -@var{window}---the number of columns by which the text in @var{window} -is scrolled left past the left margin. The default for -@var{window} is the selected window. - -The return value is never negative. It is zero when no horizontal -scrolling has been done in @var{window} (which is usually the case). - - -@example -@group -(window-hscroll) - @result{} 0 -@end group -@group -(scroll-left 5) - @result{} 5 -@end group -@group -(window-hscroll) - @result{} 5 -@end group -@end example -@end defun - -@defun set-window-hscroll window columns -This function sets horizontal scrolling of @var{window}. The value of -@var{columns} specifies the amount of scrolling, in terms of columns -from the left margin. The argument @var{columns} should be zero or -positive; if not, it is taken as zero. Fractional values of -@var{columns} are not supported at present. - -Note that @code{set-window-hscroll} may appear not to work if you test -it by evaluating a call with @kbd{M-:} in a simple way. What happens -is that the function sets the horizontal scroll value and returns, but -then redisplay adjusts the horizontal scrolling to make point visible, -and this overrides what the function did. You can observe the -function's effect if you call it while point is sufficiently far from -the left margin that it will remain visible. - -The value returned is @var{columns}. - -@example -@group -(set-window-hscroll (selected-window) 10) - @result{} 10 -@end group -@end example -@end defun - - Here is how you can determine whether a given position @var{position} -is off the screen due to horizontal scrolling: - -@c FIXME: Maybe hscroll-on-screen-p is a better name? -@example -@group -(defun hscroll-on-screen (window position) - (save-excursion - (goto-char position) - (and - (>= (- (current-column) (window-hscroll window)) 0) - (< (- (current-column) (window-hscroll window)) - (window-width window))))) -@end group -@end example - -@node Coordinates and Windows -@section Coordinates and Windows -@cindex frame-relative coordinate -@cindex coordinate, relative to frame -@cindex window position - - This section describes functions that report the position of a -window. Most of these functions report positions relative to the -window's frame. In this case, the coordinate origin @samp{(0,0)} lies -near the upper left corner of the frame. For technical reasons, on -graphical displays the origin is not located at the exact corner of -the graphical window as it appears on the screen. If Emacs is built -with the GTK+ toolkit, the origin is at the upper left corner of the -frame area used for displaying Emacs windows, below the title-bar, -GTK+ menu bar, and tool bar (since these are drawn by the window -manager and/or GTK+, not by Emacs). But if Emacs is not built with -GTK+, the origin is at the upper left corner of the tool bar (since in -this case Emacs itself draws the tool bar). In both cases, the X and -Y coordinates increase rightward and downward respectively. - - Except where noted, X and Y coordinates are reported in integer -character units, i.e., numbers of lines and columns respectively. On a -graphical display, each ``line'' and ``column'' corresponds to the -height and width of a default character specified by the frame's -default font. - -@defun window-edges &optional window -This function returns a list of the edge coordinates of @var{window}. -If @var{window} is omitted or @code{nil}, it defaults to the selected -window. - -The return value has the form @code{(@var{left} @var{top} @var{right} -@var{bottom})}. These list elements are, respectively, the X -coordinate of the leftmost column occupied by the window, the Y -coordinate of the topmost row, the X coordinate one column to the -right of the rightmost column, and the Y coordinate one row down from -the bottommost row. - -Note that these are the actual outer edges of the window, including any -header line, mode line, scroll bar, fringes, window divider and display -margins. On a text terminal, if the window has a neighbor on its right, -its right edge includes the separator line between the window and its -neighbor. -@end defun - -@defun window-inside-edges &optional window -This function is similar to @code{window-edges}, but the returned edge -values are for the text area of the window. They exclude any header -line, mode line, scroll bar, fringes, window divider, display margins, -and vertical separator. -@end defun - -@defun window-top-line &optional window -This function returns the Y coordinate of the topmost row of -@var{window}, equivalent to the @var{top} entry in the list returned -by @code{window-edges}. -@end defun - -@defun window-left-column &optional window -This function returns the X coordinate of the leftmost column of -@var{window}, equivalent to the @var{left} entry in the list returned -by @code{window-edges}. -@end defun - - The following functions can be used to relate a set of -frame-relative coordinates to a window: - -@defun window-at x y &optional frame -This function returns the live window at the frame-relative -coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no -window at that position, the return value is @code{nil}. If -@var{frame} is omitted or @code{nil}, it defaults to the selected -frame. -@end defun - -@defun coordinates-in-window-p coordinates window -This function checks whether a window @var{window} occupies the -frame-relative coordinates @var{coordinates}, and if so, which part of -the window that is. @var{window} should be a live window. -@var{coordinates} should be a cons cell of the form @code{(@var{x} -. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates. - -If there is no window at the specified position, the return value is -@code{nil} . Otherwise, the return value is one of the following: - -@table @code -@item (@var{relx} . @var{rely}) -The coordinates are inside @var{window}. The numbers @var{relx} and -@var{rely} are the equivalent window-relative coordinates for the -specified position, counting from 0 at the top left corner of the -window. - -@item mode-line -The coordinates are in the mode line of @var{window}. - -@item header-line -The coordinates are in the header line of @var{window}. - -@item right-divider -The coordinates are in the divider separating @var{window} from a -window on the right. - -@item right-divider -The coordinates are in the divider separating @var{window} from a -window beneath. - -@item vertical-line -The coordinates are in the vertical line between @var{window} and its -neighbor to the right. This value occurs only if the window doesn't -have a scroll bar; positions in a scroll bar are considered outside the -window for these purposes. - -@item left-fringe -@itemx right-fringe -The coordinates are in the left or right fringe of the window. - -@item left-margin -@itemx right-margin -The coordinates are in the left or right margin of the window. - -@item nil -The coordinates are not in any part of @var{window}. -@end table - -The function @code{coordinates-in-window-p} does not require a frame as -argument because it always uses the frame that @var{window} is on. -@end defun - - The following functions return window positions in pixels, rather -than character units. Though mostly useful on graphical displays, -they can also be called on text terminals, where the screen area of -each text character is taken to be ``one pixel''. - -@defun window-pixel-edges &optional window -This function returns a list of pixel coordinates for the edges of -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. - -The return value has the form @code{(@var{left} @var{top} @var{right} -@var{bottom})}. The list elements are, respectively, the X pixel -coordinate of the left window edge, the Y pixel coordinate of the top -edge, one more than the X pixel coordinate of the right edge, and one -more than the Y pixel coordinate of the bottom edge. -@end defun - -@defun window-inside-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the pixel coordinates for the edges of the window's text area, -rather than the pixel coordinates for the edges of the window itself. -@var{window} must specify a live window. -@end defun - - The following functions return window positions in pixels, relative -to the display screen rather than the frame: - -@defun window-absolute-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. -@end defun - -@defun window-inside-absolute-pixel-edges &optional window -This function is like @code{window-inside-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. @var{window} must specify a live window. -@end defun - -@defun window-pixel-left &optional window -This function returns the left pixel edge of window @var{window}. -@var{window} must be a valid window and defaults to the selected one. -@end defun - -@defun window-pixel-top &optional window -This function returns the top pixel edge of window @var{window}. -@var{window} must be a valid window and defaults to the selected one. -@end defun - - -@node Window Configurations -@section Window Configurations -@cindex window configurations -@cindex saving window information - -A @dfn{window configuration} records the entire layout of one -frame---all windows, their sizes, which buffers they contain, how those -buffers are scrolled, and their values of point and the mark; also their -fringes, margins, and scroll bar settings. It also includes the value -of @code{minibuffer-scroll-window}. As a special exception, the window -configuration does not record the value of point in the selected window -for the current buffer. - - You can bring back an entire frame layout by restoring a previously -saved window configuration. If you want to record the layout of all -frames instead of just one, use a frame configuration instead of a -window configuration. @xref{Frame Configurations}. - -@defun current-window-configuration &optional frame -This function returns a new object representing @var{frame}'s current -window configuration. The default for @var{frame} is the selected -frame. The variable @code{window-persistent-parameters} specifies -which window parameters (if any) are saved by this function. -@xref{Window Parameters}. -@end defun - -@defun set-window-configuration configuration -This function restores the configuration of windows and buffers as -specified by @var{configuration}, for the frame that @var{configuration} -was created for. - -The argument @var{configuration} must be a value that was previously -returned by @code{current-window-configuration}. The configuration is -restored in the frame from which @var{configuration} was made, whether -that frame is selected or not. This always counts as a window size -change and triggers execution of the @code{window-size-change-functions} -(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't -know how to tell whether the new configuration actually differs from the -old one. - -If the frame from which @var{configuration} was saved is dead, all this -function does is restore the three variables @code{window-min-height}, -@code{window-min-width} and @code{minibuffer-scroll-window}. In this -case, the function returns @code{nil}. Otherwise, it returns @code{t}. - -Here is a way of using this function to get the same effect -as @code{save-window-excursion}: - -@example -@group -(let ((config (current-window-configuration))) - (unwind-protect - (progn (split-window-below nil) - @dots{}) - (set-window-configuration config))) -@end group -@end example -@end defun - -@defmac save-window-excursion forms@dots{} -This macro records the window configuration of the selected frame, -executes @var{forms} in sequence, then restores the earlier window -configuration. The return value is the value of the final form in -@var{forms}. - -Most Lisp code should not use this macro; @code{save-selected-window} -is typically sufficient. In particular, this macro cannot reliably -prevent the code in @var{forms} from opening new windows, because new -windows might be opened in other frames (@pxref{Choosing Window}), and -@code{save-window-excursion} only saves and restores the window -configuration on the current frame. - -Do not use this macro in @code{window-size-change-functions}; exiting -the macro triggers execution of @code{window-size-change-functions}, -leading to an endless loop. -@end defmac - -@defun window-configuration-p object -This function returns @code{t} if @var{object} is a window configuration. -@end defun - -@defun compare-window-configurations config1 config2 -This function compares two window configurations as regards the -structure of windows, but ignores the values of point and mark and the -saved scrolling positions---it can return @code{t} even if those -aspects differ. - -The function @code{equal} can also compare two window configurations; it -regards configurations as unequal if they differ in any respect, even a -saved point or mark. -@end defun - -@defun window-configuration-frame config -This function returns the frame for which the window configuration -@var{config} was made. -@end defun - - Other primitives to look inside of window configurations would make -sense, but are not implemented because we did not need them. See the -file @file{winner.el} for some more operations on windows -configurations. - - The objects returned by @code{current-window-configuration} die -together with the Emacs process. In order to store a window -configuration on disk and read it back in another Emacs session, you -can use the functions described next. These functions are also useful -to clone the state of a frame into an arbitrary live window -(@code{set-window-configuration} effectively clones the windows of a -frame into the root window of that very frame only). - -@cindex window state -@defun window-state-get &optional window writable -This function returns the state of @var{window} as a Lisp object. The -argument @var{window} must be a valid window and defaults to the root -window of the selected frame. - -If the optional argument @var{writable} is non-@code{nil}, this means to -not use markers for sampling positions like @code{window-point} or -@code{window-start}. This argument should be non-@code{nil} when the -state will be written to disk and read back in another session. - -Together, the argument @var{writable} and the variable -@code{window-persistent-parameters} specify which window parameters are -saved by this function. @xref{Window Parameters}. -@end defun - -The value returned by @code{window-state-get} can be used in the same -session to make a clone of a window in another window. It can be also -written to disk and read back in another session. In either case, use -the following function to restore the state of the window. - -@defun window-state-put state &optional window ignore -This function puts the window state @var{state} into @var{window}. -The argument @var{state} should be the state of a window returned by -an earlier invocation of @code{window-state-get}, see above. The -optional argument @var{window} can be either a live window or an -internal window (@pxref{Windows and Frames}) and defaults to the -selected one. If @var{window} is not live, it is replaced by a live -window before putting @var{state} into it. - -If the optional argument @var{ignore} is non-@code{nil}, it means to ignore -minimum window sizes and fixed-size restrictions. If @var{ignore} -is @code{safe}, this means windows can get as small as one line -and/or two columns. -@end defun - - -@node Window Parameters -@section Window Parameters -@cindex window parameters - -This section describes how window parameters can be used to associate -additional information with windows. - -@defun window-parameter window parameter -This function returns @var{window}'s value for @var{parameter}. The -default for @var{window} is the selected window. If @var{window} has no -setting for @var{parameter}, this function returns @code{nil}. -@end defun - -@defun window-parameters &optional window -This function returns all parameters of @var{window} and their values. -The default for @var{window} is the selected window. The return value -is either @code{nil}, or an association list whose elements have the form -@code{(@var{parameter} . @var{value})}. -@end defun - -@defun set-window-parameter window parameter value -This function sets @var{window}'s value of @var{parameter} to -@var{value} and returns @var{value}. The default for @var{window} -is the selected window. -@end defun - -By default, the functions that save and restore window configurations or the -states of windows (@pxref{Window Configurations}) do not care about -window parameters. This means that when you change the value of a -parameter within the body of a @code{save-window-excursion}, the -previous value is not restored when that macro exits. It also means -that when you restore via @code{window-state-put} a window state saved -earlier by @code{window-state-get}, all cloned windows have their -parameters reset to @code{nil}. The following variable allows you to -override the standard behavior: - -@defvar window-persistent-parameters -This variable is an alist specifying which parameters get saved by -@code{current-window-configuration} and @code{window-state-get}, and -subsequently restored by @code{set-window-configuration} and -@code{window-state-put}. @xref{Window Configurations}. - -The @sc{car} of each entry of this alist is a symbol specifying the -parameter. The @sc{cdr} should be one of the following: - -@table @asis -@item @code{nil} -This value means the parameter is saved neither by -@code{window-state-get} nor by @code{current-window-configuration}. - -@item @code{t} -This value specifies that the parameter is saved by -@code{current-window-configuration} and (provided its @var{writable} -argument is @code{nil}) by @code{window-state-get}. - -@item @code{writable} -This means that the parameter is saved unconditionally by both -@code{current-window-configuration} and @code{window-state-get}. This -value should not be used for parameters whose values do not have a read -syntax. Otherwise, invoking @code{window-state-put} in another session -may fail with an @code{invalid-read-syntax} error. -@end table -@end defvar - -Some functions (notably @code{delete-window}, -@code{delete-other-windows} and @code{split-window}), may behave specially -when their @var{window} argument has a parameter set. You can override -such special behavior by binding the following variable to a -non-@code{nil} value: - -@defvar ignore-window-parameters -If this variable is non-@code{nil}, some standard functions do not -process window parameters. The functions currently affected by this are -@code{split-window}, @code{delete-window}, @code{delete-other-windows}, -and @code{other-window}. - -An application can bind this variable to a non-@code{nil} value around -calls to these functions. If it does so, the application is fully -responsible for correctly assigning the parameters of all involved -windows when exiting that function. -@end defvar - -The following parameters are currently used by the window management -code: - -@table @asis -@item @code{delete-window} -This parameter affects the execution of @code{delete-window} -(@pxref{Deleting Windows}). - -@item @code{delete-other-windows} -This parameter affects the execution of @code{delete-other-windows} -(@pxref{Deleting Windows}). - -@item @code{split-window} -This parameter affects the execution of @code{split-window} -(@pxref{Splitting Windows}). - -@item @code{other-window} -This parameter affects the execution of @code{other-window} -(@pxref{Cyclic Window Ordering}). - -@item @code{no-other-window} -This parameter marks the window as not selectable by @code{other-window} -(@pxref{Cyclic Window Ordering}). - -@item @code{clone-of} -This parameter specifies the window that this one has been cloned -from. It is installed by @code{window-state-get} (@pxref{Window -Configurations}). - -@item @code{quit-restore} -This parameter is installed by the buffer display functions -(@pxref{Choosing Window}) and consulted by @code{quit-restore-window} -(@pxref{Quitting Windows}). It contains four elements: - -The first element is one of the symbols @code{window}, meaning that the -window has been specially created by @code{display-buffer}; @code{frame}, -a separate frame has been created; @code{same}, the window has -displayed the same buffer before; or @code{other}, the window showed -another buffer before. - -The second element is either one of the symbols @code{window} or -@code{frame}, or a list whose elements are the buffer shown in the -window before, that buffer's window start and window point positions, -and the window's height at that time. - -The third element is the window selected at the time the parameter was -created. The function @code{quit-restore-window} tries to reselect that -window when it deletes the window passed to it as argument. - -The fourth element is the buffer whose display caused the creation of -this parameter. @code{quit-restore-window} deletes the specified window -only if it still shows that buffer. -@end table - -There are additional parameters @code{window-atom} and @code{window-side}; -these are reserved and should not be used by applications. - - -@node Window Hooks -@section Hooks for Window Scrolling and Changes -@cindex hooks for window operations - -This section describes how a Lisp program can take action whenever a -window displays a different part of its buffer or a different buffer. -There are three actions that can change this: scrolling the window, -switching buffers in the window, and changing the size of the window. -The first two actions run @code{window-scroll-functions}; the last runs -@code{window-size-change-functions}. - -@defvar window-scroll-functions -This variable holds a list of functions that Emacs should call before -redisplaying a window with scrolling. Displaying a different buffer in -the window also runs these functions. - -This variable is not a normal hook, because each function is called with -two arguments: the window, and its new display-start position. - -These functions must take care when using @code{window-end} -(@pxref{Window Start and End}); if you need an up-to-date value, you -must use the @var{update} argument to ensure you get it. - -@strong{Warning:} don't use this feature to alter the way the window -is scrolled. It's not designed for that, and such use probably won't -work. -@end defvar - -@defvar window-size-change-functions -This variable holds a list of functions to be called if the size of any -window changes for any reason. The functions are called just once per -redisplay, and just once for each frame on which size changes have -occurred. - -Each function receives the frame as its sole argument. There is no -direct way to find out which windows on that frame have changed size, or -precisely how. However, if a size-change function records, at each -call, the existing windows and their sizes, it can also compare the -present sizes and the previous sizes. - -Creating or deleting windows counts as a size change, and therefore -causes these functions to be called. Changing the frame size also -counts, because it changes the sizes of the existing windows. - -You may use @code{save-selected-window} in these functions -(@pxref{Selecting Windows}). However, do not use -@code{save-window-excursion} (@pxref{Window Configurations}); exiting -that macro counts as a size change, which would cause these functions -to be called over and over. -@end defvar - -@defvar window-configuration-change-hook -A normal hook that is run every time you change the window configuration -of an existing frame. This includes splitting or deleting windows, -changing the sizes of windows, or displaying a different buffer in a -window. - -The buffer-local part of this hook is run once for each window on the -affected frame, with the relevant window selected and its buffer -current. The global part is run once for the modified frame, with that -frame selected. -@end defvar - - In addition, you can use @code{jit-lock-register} to register a Font -Lock fontification function, which will be called whenever parts of a -buffer are (re)fontified because a window was scrolled or its size -changed. @xref{Other Font Lock Variables}. diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi deleted file mode 100644 index e68bf055f35..00000000000 --- a/doc/misc/ada-mode.texi +++ /dev/null @@ -1,1526 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/ada-mode -@settitle Ada Mode -@documentencoding UTF-8 - -@copying -Copyright @copyright{} 1999--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs editing modes -@direntry -* Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code. -@end direntry - -@titlepage -@sp 10 -@title Ada Mode -@sp 2 -@subtitle An Emacs major mode for programming in Ada -@subtitle Ada Mode Version 4.00 -@sp 2 -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top Ada Mode - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: -* Installation:: Installing Ada mode on your system -* Customization:: Setting up Ada mode to your taste -* Compiling Executing:: Working with your application within Emacs -* Project files:: Describing the organization of your project -* Compiling Examples:: A small tutorial -* Moving Through Ada Code:: Moving easily through Ada sources -* Identifier completion:: Finishing words automatically -* Automatic Smart Indentation:: Indenting your code automatically as you type -* Formatting Parameter Lists:: Formatting subprograms' parameter lists - automatically -* Automatic Casing:: Adjusting the case of words automatically -* Statement Templates:: Inserting code templates -* Comment Handling:: Reformatting comments easily -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - - -@node Overview -@chapter Overview - -The Emacs mode for programming in Ada helps the user in understanding -existing code and facilitates writing new code. - -When the Gnu Ada compiler GNAT is used, the cross-reference -information output by the compiler is used to provide powerful code -navigation (jump to definition, find all uses, etc.). - -When you open a file with a file extension of @file{.ads} or -@file{.adb}, Emacs will automatically load and activate Ada mode. - -Ada mode works without any customization, if you are using the GNAT -compiler (@url{https://libre2.adacore.com/}) and the GNAT default -naming convention. - -You must customize a few things if you are using a different compiler -or file naming convention; @xref{Other compiler}, @xref{Non-standard -file names}. - -In addition, you may want to customize the indentation, -capitalization, and other things; @xref{Other customization}. - -Finally, for large Ada projects, you will want to set up an Emacs -Ada mode project file for each project; @xref{Project files}. Note -that these are different from the GNAT project files used by gnatmake -and other GNAT commands. - -See the Emacs info manual, section 'Running Debuggers Under Emacs', -for general information on debugging. - -@node Installation -@chapter Installation - -Ada mode is part of the standard Emacs distribution; if you use that, -no files need to be installed. - -Ada mode is also available as a separate distribution, from the Emacs -Ada mode website -@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The -separate distribution may be more recent. - -For installing the separate distribution, see the @file{README} file -in the distribution. - -To see what version of Ada mode you have installed, do @kbd{M-x -ada-mode-version}. - -The following files are provided with the Ada mode distribution: - -@itemize @bullet - -@item -@file{ada-mode.el}: The main file for Ada mode, providing indentation, -formatting of parameter lists, moving through code, comment handling -and automatic casing. - -@item -@file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs -widgets. - -@item -@file{ada-stmt.el}: Ada statement templates. - -@item -@file{ada-xref.el}: GNAT cross-references, completion of identifiers, -and compilation. Also provides project files (which are not -GNAT-specific). - -@end itemize - -@node Customization -@chapter Customizing Ada mode - -Here we assume you are familiar with setting variables in Emacs, -either thru 'customize' or in elisp (in your @file{.emacs} file). For -a basic introduction to customize, elisp, and Emacs in general, see -the tutorial in -@iftex -@cite{The GNU Emacs Manual}. -@end iftex -@ifhtml -@cite{The GNU Emacs Manual}. -@end ifhtml -@ifinfo -@ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}. -@end ifinfo - -These global Emacs settings are strongly recommended (put them in your -.emacs): - -@example -(global-font-lock-mode t) -(transient-mark-mode t) -@end example - -@samp{(global-font-lock-mode t)} turns on syntax -highlighting for all buffers (it is off by default because it may be -too slow for some machines). - -@samp{(transient-mark-mode t)} highlights selected text. - -See the Emacs help for each of these variables for more information. - -@menu -* Non-standard file names:: -* Other compiler:: -* Other customization:: -@end menu - -@node Non-standard file names -@section Non-standard file names - -By default, Ada mode is configured to use the GNAT file naming -convention, where file names are a simple modification of the Ada -names, and the extension for specs and bodies are -@samp{.ads} and @samp{.adb}, respectively. - -Ada mode uses the file extensions to allow moving from a package body -to the corresponding spec and back. - -Ada mode supports a list of alternative file extensions for specs and bodies. - -For instance, if your spec and bodies files are called -@file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you -can add the following to your @file{.emacs} file: - -@example -(ada-add-extensions "_s.ada" "_b.ada") -@end example - -You can define additional extensions: - -@example -(ada-add-extensions ".ads" "_b.ada") -(ada-add-extensions ".ads" ".body") -@end example - -This means that whenever Ada mode looks for the body for a file -whose extension is @file{.ads}, it will take the first available file -that ends with either @file{.adb}, @file{_b.ada} or -@file{.body}. - -Similarly, if Ada mode is looking for a spec, it will look for -@file{.ads} or @file{_s.ada}. - -If the filename is not derived from the Ada name following the GNAT -convention, things are a little more complicated. You then need to -rewrite the function @code{ada-make-filename-from-adaname}. Doing that -is beyond the scope of this manual; see the current definitions in -@file{ada-mode.el} and @file{ada-xref.el} for examples. - -@node Other compiler -@section Other compiler - -By default, Ada mode is configured to use the Gnu Ada compiler GNAT. - -To use a different Ada compiler, you must specify the command lines -used to run that compiler, either in lisp variables or in Emacs -Ada mode project files. See @ref{Project file variables} for the list -of project variables, and the corresponding lisp variables. - -@node Other customization -@section Other customization - -All user-settable Ada mode variables can be set via the menu -@samp{Ada | Customize}. Click on the @samp{Help} button there for help -on using customize. - -To modify a specific variable, you can directly call the function -@code{customize-variable}; just type @kbd{M-x customize-variable -@key{RET} @var{variable-name} @key{RET}}). - -Alternately, you can specify variable settings in the Emacs -configuration file, @file{.emacs}. This file is coded in Emacs lisp, -and the syntax to set a variable is the following: -@example -(setq variable-name value) -@end example - -@node Compiling Executing -@chapter Compiling Executing - -Ada projects can be compiled, linked, and executed using commands on -the Ada menu. All of these commands can be customized via a project -file (@pxref{Project files}), but the defaults are sufficient for using -the GNAT compiler for simple projects (single files, or several files -in a single directory). - -Even when no project file is used, the GUI project editor (menu -@samp{Ada | Project | Edit}) shows the settings of the various project -file variables referenced here. - -@menu -* Compile commands:: -* Compiler errors:: -@end menu - -@node Compile commands -@section Compile commands - -Here are the commands for building and using an Ada project, as -listed in the Ada menu. - -In multi-file projects, there must be one file that is the main -program. That is given by the @code{main} project file variable; -it defaults to the current file if not yet set, but is also set by the -``set main and build'' command. - -@table @code - -@item Check file -Compiles the current file in syntax check mode, by running -@code{check_cmd} defined in the current project file. This typically -runs faster than full compile mode, speeding up finding and fixing -compilation errors. - -This sets @code{main} only if it has not been set yet. - -@item Compile file -Compiles the current file, by running @code{comp_cmd} from the current -project file. - -This does not set @code{main}. - -@item Set main and Build -Sets @code{main} to the current file, then executes the Build -command. - -@item Show main -Display @code{main} in the message buffer. - -@item Build -Compiles all obsolete units of the current @code{main}, and links -@code{main}, by running @code{make_cmd} from the current project. - -This sets @code{main} only if it has not been set yet. - -@item Run -Executes the main program in a shell, displayed in a separate Emacs -buffer. This runs @code{run_cmd} from the current project. The -execution buffer allows for interactive input/output. - -To modify the run command, in particular to provide or change the -command line arguments, type @kbd{C-u} before invoking the command. - -This command is not available for a cross-compilation toolchain. - -@end table -It is important when using these commands to understand how -@code{main} is used and changed. - -Build runs 'gnatmake' on the main unit. During a typical edit/compile -session, this is the only command you need to invoke, which is why it -is bound to @kbd{C-c C-c}. It will compile all files needed by the -main unit, and display compilation errors in any of them. - -Note that Build can be invoked from any Ada buffer; typically you will -be fixing errors in files other than the main, but you don't have to -switch back to the main to invoke the compiler again. - -Novices and students typically work on single-file Ada projects. In -this case, @kbd{C-c C-m} will normally be the only command needed; it -will build the current file, rather than the last-built main. - -There are three ways to change @code{main}: - -@enumerate -@item -Invoke @samp{Ada | Set main and Build}, which sets @code{main} to -the current file. - -@item -Invoke @samp{Ada | Project | Edit}, edit @code{main} and -@code{main}, and click @samp{[save]} - -@item -Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} - -@end enumerate - -@node Compiler errors -@section Compiler errors - -The @code{Check file}, @code{Compile file}, and @code{Build} commands -all place compilation errors in a separate buffer named -@file{*compilation*}. - -Each line in this buffer will become active: you can simply click on -it with the middle button of the mouse, or move point to it and press -@key{RET}. Emacs will then display the relevant source file and put -point on the line and column where the error was found. - -You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs -will jump to the first error. If you press that key again, it will -move you to the second error, and so on. - -Some error messages might also include references to other files. These -references are also clickable in the same way, or put point after the -line number and press @key{RET}. - -@node Project files -@chapter Project files - -An Emacs Ada mode project file specifies what directories hold sources -for your project, and allows you to customize the compilation commands -and other things on a per-project basis. - -Note that Ada mode project files @file{*.adp} are different than GNAT -compiler project files @file{*.gpr}. However, Emacs Ada mode can use a -GNAT project file to specify the project directories. If no -other customization is needed, a GNAT project file can be used without -an Emacs Ada mode project file. - -@menu -* Project File Overview:: -* GUI Editor:: -* Project file variables:: -@end menu - -@node Project File Overview -@section Project File Overview - -Project files have a simple syntax; they may be edited directly. Each -line specifies a project variable name and its value, separated by ``='': -@example -src_dir=/Projects/my_project/src_1 -src_dir=/Projects/my_project/src_2 -@end example - -Some variables (like @code{src_dir}) are lists; multiple occurrences -are concatenated. - -There must be no space between the variable name and ``='', and no -trailing spaces. - -Alternately, a GUI editor for project files is available (@pxref{GUI -Editor}). It uses Emacs widgets, similar to Emacs customize. - -The GUI editor also provides a convenient way to view current project -settings, if they have been modified using menu commands rather than -by editing the project file. - -After the first Ada mode build command is invoked, there is always a -current project file, given by the lisp variable -@code{ada-prj-default-project-file}. Currently, the only way to show -the current project file is to invoke the GUI editor. - -To find the project file the first time, Ada mode uses the following -search algorithm: - -@itemize @bullet -@item -If @code{ada-prj-default-project-file} is set, use that. - -@item -Otherwise, search for a file in the current directory with -the same base name as the Ada file, but extension given by -@code{ada-prj-file-extension} (default @code{".adp"}). - -@item -If not found, search for @file{*.adp} in the current directory; if -several are found, prompt the user to select one. - -@item -If none are found, use @file{default.adp} in the current directory (even -if it does not exist). - -@end itemize - -This algorithm always sets @code{ada-prj-default-project-file}, even -when the file does not actually exist. - -To change the project file before or after the first one is found, -invoke @samp{Ada | Project | Load ...}. - -Or, in lisp, evaluate @code{(ada-set-default-project-file "/path/file.adp")}. -This sets @code{ada-prj-default-project-file}, and reads the project file. - -You can also specify a GNAT project file to @samp{Ada | Project | Load -...} or @code{ada-set-default-project-file}. Emacs Ada mode checks the -file extension; if it is @code{.gpr}, the file is treated as a GNAT -project file. Any other extension is treated as an Emacs Ada mode -project file. - -@node GUI Editor -@section GUI Editor - -The project file editor is invoked with the menu @samp{Ada | Projects -| Edit}. - -Once in the buffer for editing the project file, you can save your -modification using the @samp{[save]} button at the bottom of the -buffer, or the @kbd{C-x C-s} binding. To cancel your modifications, -kill the buffer or click on the @samp{[cancel]} button. - -@node Project file variables -@section Project file variables - -The following variables can be defined in a project file; some can -also be defined in lisp variables. - -To set a project variable that is a list, specify each element of the -list on a separate line in the project file. - -Any project variable can be referenced in other project variables, -using a shell-like notation. For instance, if the variable -@code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the -@code{comp_opt} variable will be substituted when @code{comp_cmd} is -used. - -In addition, process environment variables can be referenced using the -same syntax, or the normal @code{$var} syntax. - -Most project variables have defaults that can be changed by setting -lisp variables; the table below identifies the lisp variable for each -project variable. Lisp variables corresponding to project variables -that are lists are lisp lists. - -In general, project variables are evaluated when referenced in -Emacs Ada mode commands. Relative file paths are expanded to -absolute relative to @code{$@{build_dir@}}. - -Here is the list of variables. In the default values, the current -directory @code{"."} is the project file directory. - -@table @asis -@c defined in ada-default-prj-properties; alphabetical order - -@item @code{ada_project_path_sep} [default: @code{":" or ";"}] -Path separator for @code{ADA_PROJECT_PATH}. It defaults to the correct -value for a native implementation of GNAT for the current operating -system. The user must override this when using Windows native GNAT -with Cygwin Emacs, and perhaps in other cases. - -Lisp variable: @code{ada-prj-ada-project-path-sep}. - -@item @code{ada_project_path} [default: @code{""}] -A list of directories to search for GNAT project files. - -If set, the @code{ADA_PROJECT_PATH} process environment variable is -set to this value in the Emacs process when the Emacs Ada mode project -is selected via menu @samp{Ada | Project | Load}. - -For @code{ada_project_path}, relative file paths are expanded to -absolute when the Emacs Ada project file is read, rather than when the -project file is selected. - -For example if the project file is in the directory -@file{/home/myproject}, the environment variable @code{GDS_ROOT} is -set to @code{/home/shared}, and the project file contains: -@example -ada_project_path_sep=: -ada_project_path=$GDS_ROOT/makerules -ada_project_path=../opentoken -@end example -then as a result the environment variable @code{ADA_PROJECT_PATH} will -be set to @code{"/home/shared/makerules:/home/opentoken/"}. - -The default value is not the current value of this environment -variable, because that will typically have been set by another -project, and will therefore be incorrect for this project. - -If you have the environment variable set correctly for all of your -projects, you do not need to set this project variable. - -@item @code{bind_opt} [default: @code{""}] -Holds user binder options; used in the default build commands. - -Lisp variable: @code{ada-prj-default-bind-opt}. - -@item @code{build_dir} [default: @code{"."}] -The compile commands will be issued in this directory. - -@item @code{casing} [default: @code{("~/.emacs_case_exceptions")} -List of files containing casing exceptions. See the help on -@code{ada-case-exception-file} for more info. -@c FIXME: section on case exceptions - -Lisp variable: @code{ada-case-exception-file}. - -@item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] -Command used to syntax check a single file. -The name of the file is substituted for @code{full_current}. - -Lisp variable: @code{ada-prj-default-check-cmd} - -@item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] -Command used to compile a single file. -The name of the file is substituted for @code{full_current}. - -Lisp variable: @code{ada-prj-default-comp-cmd}. - -@item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}] -Holds user compiler options; used in the default compile commands. The -default value tells gnatmake to generate library files for -cross-referencing even when there are errors. - -If source code for the project is in multiple directories, the -appropriate compiler options must be added here. @ref{Set source -search path} for examples of this. Alternately, GNAT project files may -be used; @ref{Use GNAT project file}. - -Lisp variable: @code{ada-prj-default-comp-opt}. - -@item @code{cross_prefix} [default: @code{""}] -Name of target machine in a cross-compilation environment. Used in -default compile and build commands. - -@item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}] -Command used to debug the application - -Lisp variable: @code{ada-prj-default-debugger}. - -@item @code{debug_post_cmd} [default: @code{""}] -Command executed after @code{debug_cmd}. - -@item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}] -Command executed before @code{debug_cmd}. - -@item @code{gnatfind_opt} [default: @code{"-rf"}] -Holds user gnatfind options; used in the default find commands. - -Lisp variable: @code{ada-prj-gnatfind-switches}. - -@item @code{gnatmake_opt} [default: @code{"-g"}] -Holds user gnatmake options; used in the default build commands. - -Lisp variable: @code{ada-prj-default-gnatmake-opt}. - -@item @code{gpr_file} [default: @code{""}] -Specify GNAT project file. - -If set, the source and object directories specified in the GNAT -project file are appended to @code{src_dir} and @code{obj_dir}. This -allows specifying Ada source directories with a GNAT project file, and -other source directories with the Emacs project file. - -In addition, @code{-P@{gpr_file@}} is added to the project variable -@code{gnatmake_opt} whenever it is referenced. With the default -project variables, this passes the project file to all gnatmake -commands. - -Lisp variable: @code{ada-prj-default-gpr-file}. - -@c FIXME: add gnatstub-opts - -@item @code{link_opt} [default: @code{""}] -Holds user linker options; used in the default build commands. - -Lisp variable: @code{ada-prj-default-link-opt}. - -@item @code{main} [default: current file] -Specifies the name of the executable file for the project; used in the -default build commands. - -@item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}] -Command used to build the application. - -Lisp variable: @code{ada-prj-default-make-cmd}. - -@item @code{obj_dir} [default: @code{"."}] -A list of directories to search for library files. Ada mode searches -this list for the @samp{.ali} files generated by GNAT that contain -cross-reference information. - -The compiler commands must place the @samp{.ali} files in one of these -directories; the default commands do that. - -@item @code{remote_machine} [default: @code{""}] -Name of the machine to log into before issuing the compile and build -commands. If this variable is empty, the command will be run on the -local machine. - -@item @code{run_cmd} [default: @code{"./$@{main@}"}] -Command used to run the application. - -@item @code{src_dir} [default: @code{"."}] -A list of directories to search for source files, both for compile -commands and source navigation. - -@end table - -@node Compiling Examples -@chapter Compiling Examples - -We present several small projects, and walk thru the process of -compiling, linking, and running them. - -The first example illustrates more Ada mode features than the others; -you should work thru that example before doing the others. - -All of these examples assume you are using GNAT. - -The source for these examples is available on the Emacs Ada mode -website mentioned in @xref{Installation}. - -@menu -* No project files:: Just menus -* Set compiler options:: A basic Ada mode project file -* Set source search path:: Source in multiple directories -* Use GNAT project file:: -* Use multiple GNAT project files:: -@end menu - -@node No project files -@section No project files -This example uses no project files. - -First, create a directory @file{Example_1}, containing: - -@file{hello.adb}: - -@example -with Ada.Text_IO; -procedure Hello -is begin - Put_Line("Hello from hello.adb"); -end Hello; -@end example - -Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate -compiler error handling. - -@file{hello_2.adb}: - -@example -with Hello_Pkg; -procedure Hello_2 -is begin - Hello_Pkg.Say_Hello; -end Hello_2; -@end example - -This file has no errors. - -@file{hello_pkg.ads}: - -@example -package Hello_Pkg is - procedure Say_Hello; -end Hello_Pkg; -@end example - -This file has no errors. - -@file{hello_pkg.adb}: - -@example -with Ada.Text_IO; -package Hello_Pkg is - procedure Say_Hello - is begin - Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; -end Hello_Pkg; -@end example - -Yes, this is missing the keyword @code{body}; another compiler error -example. - -In buffer @file{hello.adb}, invoke @samp{Ada | Check file}. You should -get a @file{*compilation*} buffer containing something like (the -directory paths will be different): - -@smallexample -cd c:/Examples/Example_1/ -gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ -gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb -hello.adb:4:04: "Put_Line" is not visible -hello.adb:4:04: non-visible declaration at a-textio.ads:264 -hello.adb:4:04: non-visible declaration at a-textio.ads:260 -gnatmake: "c:/Examples/Example_1/hello.adb" compilation error -@end smallexample - -If you have enabled font-lock, the lines with actual errors (starting -with @file{hello.adb}) are highlighted, with the file name in red. - -Now type @kbd{C-x `} (on a PC keyboard, @key{`} is next to @key{1}). -Or you can click the middle mouse button on the first error line. The -compilation buffer scrolls to put the first error on the top line, and -point is put at the place of the error in the @file{hello.adb} buffer. - -To fix the error, change the line to be - -@example - Ada.Text_IO.Put_Line ("hello from hello.adb"); -@end example - -Now invoke @samp{Ada | Show main}; this displays @samp{Ada mode main: hello}. - -Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build}. You are -prompted to save the file (if you haven't already). Then the -compilation buffer is displayed again, containing: - -@example -cd c:/Examples/Example_1/ -gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatq -gnatQ hello.adb -gnatbind -x hello.ali -gnatlink hello.ali -o hello.exe -g -@end example - -The compilation has succeeded without errors; @file{hello.exe} now -exists in the same directory as @file{hello.adb}. - -Now invoke @samp{Ada | Run}. A @file{*run*} buffer is displayed, -containing - -@example -Hello from hello.adb - -Process run finished -@end example - -That completes the first part of this example. - -Now we will compile a multi-file project. Open the file -@file{hello_2.adb}, and invoke @samp{Ada | Set main and Build}. This -finds an error in @file{hello_pkg.adb}: - -@example -cd c:/Examples/Example_1/ -gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatq -gnatQ hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "hello_pkg.adb" compilation error -@end example - -This demonstrates that gnatmake finds the files needed by the main -program. However, it cannot find files in a different directory, -unless you use an Emacs Ada mode project file to specify the other directories; -@xref{Set source search path}, or a GNAT project file; @ref{Use GNAT -project file}. - -Invoke @samp{Ada | Show main}; this displays @file{Ada mode main: hello_2}. - -Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}: - -@example -package body Hello_Pkg is -@end example - -Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build}. -gnatmake successfully builds @file{hello_2}. This demonstrates that -Emacs has remembered the main file, in the project variable -@code{main}, and used it for the Build command. - -Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Run}. -The @file{*run*} buffer displays @code{Hello from hello_pkg.adb}. - -One final point. If you switch back to buffer @file{hello.adb}, and -invoke @samp{Ada | Run}, @file{hello_2.exe} will be run. That is -because @code{main} is still set to @code{hello_2}, as you can -see when you invoke @samp{Ada | Project | Edit}. - -There are three ways to change @code{main}: - -@enumerate -@item -Invoke @samp{Ada | Set main and Build}, which sets @code{main} to -the current file. - -@item -Invoke @samp{Ada | Project | Edit}, edit @code{main}, and click @samp{[save]} - -@item -Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} - -@end enumerate - -@node Set compiler options -@section Set compiler options - -This example illustrates using an Emacs Ada mode project file to set a -compiler option. - -If you have files from @file{Example_1} open in Emacs, you should -close them so you don't get confused. Use menu @samp{File | Close -(current buffer)}. - -In directory @file{Example_2}, create these files: - -@file{hello.adb}: - -@example -with Ada.Text_IO; -procedure Hello -is begin - Put_Line("Hello from hello.adb"); -end Hello; -@end example - -This is the same as @file{hello.adb} from @file{Example_1}. It has two -errors; missing ``use Ada.Text_IO;'', and no space between -@code{Put_Line} and its argument list. - -@file{hello.adp}: - -@example -comp_opt=-gnatyt -@end example - -This tells the GNAT compiler to check for token spacing; in -particular, there must be a space preceding a parenthesis. - -In buffer @file{hello.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_2/hello.adp}. - -Then, again in buffer @file{hello.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @file{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_2/ -gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs -gcc -c -g -gnatyt hello.adb -hello.adb:4:04: "Put_Line" is not visible -hello.adb:4:04: non-visible declaration at a-textio.ads:264 -hello.adb:4:04: non-visible declaration at a-textio.ads:260 -hello.adb:4:12: (style) space required -gnatmake: "hello.adb" compilation error -@end example - -Compare this to the compiler output in @ref{No project files}; the -gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by -@code{-cargs -gnaty}, and an additional error is reported in -@file{hello.adb} on line 4. This shows that @file{hello.adp} is being -used to set the compiler options. - -Fixing the error, linking and running the code proceed as in @ref{No -project files}. - -@node Set source search path -@section Set source search path - -In this example, we show how to deal with files in more than one -directory. We start with the same code as in @ref{No project files}; -create those files (with the errors present) - -Create the directory @file{Example_3}, containing: - -@file{hello_pkg.ads}: - -@example -package Hello_Pkg is - procedure Say_Hello; -end Hello_Pkg; -@end example - -@file{hello_pkg.adb}: - -@example -with Ada.Text_IO; -package Hello_Pkg is - procedure Say_Hello - is begin - Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; -end Hello_Pkg; -@end example - -These are the same files from example 1; @file{hello_pkg.adb} has an -error on line 2. - -In addition, create a directory @file{Example_3/Other}, containing these files: - -@file{Other/hello_3.adb}: - -@example -with Hello_Pkg; -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello_3 -is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_3"); -end Hello_3; -@end example - -There are no errors in this file. - -@file{Other/other.adp}: - -@example -src_dir=.. -comp_opt=-I.. -@end example - -Note that there must be no trailing spaces. - -In buffer @file{hello_3.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_3/Other/other.adp}. - -Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @file{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_3/Other/ -gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs -gcc -c -g -I.. hello_3.adb -gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error -@end example - -Compare the @code{-cargs} option to the compiler output in @ref{Set -compiler options}; this shows that @file{other.adp} is being used to -set the compiler options. - -Move to the error with @kbd{C-x `}. Ada mode searches the list of -directories given by @code{src_dir} for the file mentioned in the -compiler error message. - -Fixing the error, linking and running the code proceed as in @ref{No -project files}. - -@node Use GNAT project file -@section Use GNAT project file - -In this example, we show how to use a GNAT project file, with no Ada -mode project file. - -Create the directory @file{Example_4}, containing: - -@file{hello_pkg.ads}: - -@example -package Hello_Pkg is - procedure Say_Hello; -end Hello_Pkg; -@end example - -@file{hello_pkg.adb}: - -@example -with Ada.Text_IO; -package Hello_Pkg is - procedure Say_Hello - is begin - Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; -end Hello_Pkg; -@end example - -These are the same files from example 1; @file{hello_pkg.adb} has an -error on line 2. - -In addition, create a directory @file{Example_4/Gnat_Project}, -containing these files: - -@file{Gnat_Project/hello_4.adb}: - -@example -with Hello_Pkg; -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello_4 -is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_4"); -end Hello_4; -@end example - -There are no errors in this file. - -@file{Gnat_Project/hello_4.gpr}: - -@example -Project Hello_4 is - for Source_Dirs use (".", ".."); -end Hello_4; -@end example - -In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_4/Gnat_Project/hello_4.gpr}. - -Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @file{*compilation*} buffer containing -something like (the directory paths will be different): - -@smallexample -cd c:/Examples/Example_4/Gnat_Project/ -gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb -gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error -@end smallexample - -Compare the @code{gcc} options to the compiler output in @ref{Set -compiler options}; this shows that @file{hello_4.gpr} is being used to -set the compiler options. - -Fixing the error, linking and running the code proceed as in @ref{No -project files}. - -@node Use multiple GNAT project files -@section Use multiple GNAT project files - -In this example, we show how to use multiple GNAT project files, -specifying the GNAT project search path in an Ada mode project file. - -Create the directory @file{Example_4} as specified in @ref{Use GNAT -project file}. - -Create the directory @file{Example_5}, containing: - -@file{hello_5.adb}: - -@example -with Hello_Pkg; -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello_5 -is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_5"); -end Hello_5; -@end example - -There are no errors in this file. - -@file{hello_5.adp}: - -@example -ada_project_path=../Example_4/Gnat_Project -gpr_file=hello_5.gpr -@end example - -@file{hello_5.gpr}: - -@example -with "hello_4"; -Project Hello_5 is - for Source_Dirs use ("."); - package Compiler is - for Default_Switches ("Ada") use ("-g", "-gnatyt"); - end Compiler; -end Hello_5; -@end example - -In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_5/hello_5.adp}. - -Then, again in @file{hello_5.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @file{*compilation*} buffer containing -something like (the directory paths will be different): - -@smallexample -cd c:/Examples/Example_5/ -gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb -gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error -@end smallexample - -Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown, -demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being -used to set the compilation search path. - -@node Moving Through Ada Code -@chapter Moving Through Ada Code - -There are several easy to use commands to navigate through Ada code. All -these functions are available through the Ada menu, and you can also -use the following key bindings or the command names. Some of these -menu entries are available only if the GNAT compiler is used, since -the implementation relies on the GNAT cross-referencing information. - -@table @kbd -@item M-C-e -@findex ada-next-procedure -Move to the next function/procedure/task, which ever comes next -(@code{ada-next-procedure}). -@item M-C-a -@findex ada-previous-procedure -Move to previous function/procedure/task -(@code{ada-previous-procedure}). -@item M-x ada-next-package -@findex ada-next-package -Move to next package. -@item M-x ada-previous-package -@findex ada-previous-package -Move to previous package. -@item C-c C-a -@findex ada-move-to-start -Move to matching start of @code{end} (@code{ada-move-to-start}). If -point is at the end of a subprogram, this command jumps to the -corresponding @code{begin} if the user option -@code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to -the subprogram declaration. -@item C-c C-e -@findex ada-move-to-end -Move point to end of current block (@code{ada-move-to-end}). -@item C-c o -Switch between corresponding spec and body file -(@code{ff-find-other-file}). If point is in a subprogram, position -point on the corresponding declaration or body in the other file. -@item C-c c-d -@findex ada-goto-declaration -Move from any reference to its declaration, for from a declaration to -its body (for procedures, tasks, private and incomplete types). -@item C-c C-r -@findex ada-find-references -Runs the @file{gnatfind} command to search for all references to the -identifier surrounding point (@code{ada-find-references}). Use -@kbd{C-x `} (@code{next-error}) to visit each reference (as for -compilation errors). -@end table - -If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs -will try to run GNAT for you whenever cross-reference information is -needed, and is older than the current source file. - -@node Identifier completion -@chapter Identifier completion - -Emacs and Ada mode provide two general ways for the completion of -identifiers. This is an easy way to type faster: you just have to type -the first few letters of an identifiers, and then loop through all the -possible completions. - -The first method is general for Emacs. It works by parsing all open -files for possible completions. - -For instance, if the words @samp{my_identifier}, @samp{my_subprogram} -are the only words starting with @samp{my} in any of the opened files, -then you will have this scenario: - -@example -You type: my@kbd{M-/} -Emacs inserts: @samp{my_identifier} -If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with -@samp{my_subprogram}. -Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}. -@end example - -This is a very fast way to do completion, and the casing of words will -also be respected. - -The second method (@kbd{C-@key{TAB}}) is specific to Ada mode and the GNAT -compiler. Emacs will search the cross-information for possible -completions. - -The main advantage is that this completion is more accurate: only -existing identifier will be suggested. - -On the other hand, this completion is a little bit slower and requires -that you have compiled your file at least once since you created that -identifier. - -@table @kbd -@item C-@key{TAB} -@findex ada-complete-identifier -Complete current identifier using cross-reference information. -@item M-/ -Complete identifier using buffer information (not Ada-specific). -@end table - -@node Automatic Smart Indentation -@chapter Automatic Smart Indentation - -Ada mode comes with a full set of rules for automatic indentation. You -can also configure the indentation, via the following variables: - -@table @asis -@item @code{ada-broken-indent} (default value: 2) -Number of columns to indent the continuation of a broken line. - -@item @code{ada-indent} (default value: 3) -Number of columns for default indentation. - -@item @code{ada-indent-record-rel-type} (default value: 3) -Indentation for @code{record} relative to @code{type} or @code{use}. - -@item @code{ada-indent-return} (default value: 0) -Indentation for @code{return} relative to @code{function} (if -@code{ada-indent-return} is greater than 0), or the open parenthesis -(if @code{ada-indent-return} is negative or 0). Note that in the second -case, when there is no open parenthesis, the indentation is done -relative to @code{function} with the value of @code{ada-broken-indent}. - -@item @code{ada-label-indent} (default value: -4) -Number of columns to indent a label. - -@item @code{ada-stmt-end-indent} (default value: 0) -Number of columns to indent a statement @code{end} keyword on a separate line. - -@item @code{ada-when-indent} (default value: 3) -Indentation for @code{when} relative to @code{exception} or @code{case}. - -@item @code{ada-indent-is-separate} (default value: t) -Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line. - -@item @code{ada-indent-to-open-paren} (default value: t) -Non-@code{nil} means indent according to the innermost open parenthesis. - -@item @code{ada-indent-after-return} (default value: t) -Non-@code{nil} means that the current line will also be re-indented -before inserting a newline, when you press @key{RET}. -@end table - -Most of the time, the indentation will be automatic, i.e., when you -press @key{RET}, the cursor will move to the correct column on the -next line. - -You can also indent single lines, or the current region, with @key{TAB}. - -Another mode of indentation exists that helps you to set up your -indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do -the following: - -@itemize @bullet -@item -Reindent the current line, as @key{TAB} would do. -@item -Temporarily move the cursor to a reference line, i.e., the line that -was used to calculate the current indentation. -@item -Display in the message window the name of the variable that provided -the offset for the indentation. -@end itemize - -The exact indentation of the current line is the same as the one for the -reference line, plus an offset given by the variable. - -@table @kbd -@item @key{TAB} -Indent the current line or the current region. -@item C-M-\ -Indent lines in the current region. -@item C-c @key{TAB} -Indent the current line and display the name of the variable used for -indentation. -@end table - -@node Formatting Parameter Lists -@chapter Formatting Parameter Lists - -@table @kbd -@item C-c C-f -@findex ada-format-paramlist -Format the parameter list (@code{ada-format-paramlist}). -@end table - -This aligns the declarations on the colon (@samp{:}) separating -argument names and argument types, and aligns the @code{in}, -@code{out} and @code{in out} keywords. - -@node Automatic Casing -@chapter Automatic Casing - -Casing of identifiers, attributes and keywords is automatically -performed while typing when the variable @code{ada-auto-case} is set. -Every time you press a word separator, the previous word is -automatically cased. - -You can customize the automatic casing differently for keywords, -attributes and identifiers. The relevant variables are the following: -@code{ada-case-keyword}, @code{ada-case-attribute} and -@code{ada-case-identifier}. - -All these variables can have one of the following values: - -@table @code -@item downcase-word -The word will be lowercase. For instance @code{My_vARIable} is -converted to @code{my_variable}. - -@item upcase-word -The word will be uppercase. For instance @code{My_vARIable} is -converted to @code{MY_VARIABLE}. - -@item ada-capitalize-word -The first letter and each letter following an underscore (@samp{_}) -are uppercase, others are lowercase. For instance @code{My_vARIable} -is converted to @code{My_Variable}. - -@item ada-loose-case-word -Characters after an underscore @samp{_} character are uppercase, -others are not modified. For instance @code{My_vARIable} is converted -to @code{My_VARIable}. -@end table - -Ada mode allows you to define exceptions to these rules, in a file -specified by the variable @code{ada-case-exception-file} -(default @file{~/.emacs_case_exceptions}). Each line in this file -specifies the casing of one word or word fragment. Comments may be -included, separated from the word by a space. - -If the word starts with an asterisk (@key{*}), it defines the casing -as a word fragment (or ``substring''); part of a word between two -underscores or word boundary. - -For example: - -@example -DOD Department of Defense -*IO -GNAT The GNAT compiler from Ada Core Technologies -@end example - -The word fragment @code{*IO} applies to any word containing ``_io''; -@code{Text_IO}, @code{Hardware_IO}, etc. - -@findex ada-create-case-exception -There are two ways to add new items to this file: you can simply edit -it as you would edit any text file. Or you can position point on the -word you want to add, and select menu @samp{Ada | Edit | Create Case -Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}). -The word will automatically be added to the current list of exceptions -and to the file. - -To define a word fragment case exception, select the word fragment, -then select menu @samp{Ada | Edit | Create Case Exception Substring}. - -It is sometimes useful to have multiple exception files around (for -instance, one could be the standard Ada acronyms, the second some -company specific exceptions, and the last one some project specific -exceptions). If you set up the variable @code{ada-case-exception-file} -as a list of files, each of them will be parsed and used in your emacs -session. However, when you save a new exception through the menu, as -described above, the new exception will be added to the first file in -the list. - -@table @kbd -@item C-c C-b -@findex ada-adjust-case-buffer -Adjust case in the whole buffer (@code{ada-adjust-case-buffer}). -@item C-c C-y -Create a new entry in the exception dictionary, with the word under -the cursor (@code{ada-create-case-exception}) -@item C-c C-t -@findex ada-case-read-exceptions -Rereads the exception dictionary from the file -@code{ada-case-exception-file} (@code{ada-case-read-exceptions}). -@end table - -@node Statement Templates -@chapter Statement Templates - -Templates are defined for most Ada statements, using the Emacs -``skeleton'' package. They can be inserted in the buffer using the -following commands: - -@table @kbd -@item C-c t b -@findex ada-exception-block -exception Block (@code{ada-exception-block}). -@item C-c t c -@findex ada-case -case (@code{ada-case}). -@item C-c t d -@findex ada-declare-block -declare Block (@code{ada-declare-block}). -@item C-c t e -@findex ada-else -else (@code{ada-else}). -@item C-c t f -@findex ada-for-loop -for Loop (@code{ada-for-loop}). -@item C-c t h -@findex ada-header -Header (@code{ada-header}). -@item C-c t i -@findex ada-if -if (@code{ada-if}). -@item C-c t k -@findex ada-package-body -package Body (@code{ada-package-body}). -@item C-c t l -@findex ada-loop -loop (@code{ada-loop}). -@item C-c p -@findex ada-subprogram-body -subprogram body (@code{ada-subprogram-body}). -@item C-c t t -@findex ada-task-body -task Body (@code{ada-task-body}). -@item C-c t w -@findex ada-while -while Loop (@code{ada-while}). -@item C-c t u -@findex ada-use -use (@code{ada-use}). -@item C-c t x -@findex ada-exit -exit (@code{ada-exit}). -@item C-c t C-a -@findex ada-array -array (@code{ada-array}). -@item C-c t C-e -@findex ada-elsif -elsif (@code{ada-elsif}). -@item C-c t C-f -@findex ada-function-spec -function Spec (@code{ada-function-spec}). -@item C-c t C-k -@findex ada-package-spec -package Spec (@code{ada-package-spec}). -@item C-c t C-p -@findex ada-procedure-spec -procedure Spec (@code{ada-package-spec}. -@item C-c t C-r -@findex ada-record -record (@code{ada-record}). -@item C-c t C-s -@findex ada-subtype -subtype (@code{ada-subtype}). -@item C-c t C-t -@findex ada-task-spec -task Spec (@code{ada-task-spec}). -@item C-c t C-u -@findex ada-with -with (@code{ada-with}). -@item C-c t C-v -@findex ada-private -private (@code{ada-private}). -@item C-c t C-w -@findex ada-when -when (@code{ada-when}). -@item C-c t C-x -@findex ada-exception -exception (@code{ada-exception}). -@item C-c t C-y -@findex ada-type -type (@code{ada-type}). -@end table - -@node Comment Handling -@chapter Comment Handling - -By default, comment lines get indented like Ada code. There are a few -additional functions to handle comments: - -@table @kbd -@item M-; -Start a comment in default column. -@item M-j -Continue comment on next line. -@item C-c ; -Comment the selected region (add @samp{--} at the beginning of lines). -@item C-c : -Uncomment the selected region -@item M-q -autofill the current comment. -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index - -@printindex fn - -@bye diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi deleted file mode 100644 index 2de4cfdab7f..00000000000 --- a/doc/misc/auth.texi +++ /dev/null @@ -1,540 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@include gnus-overrides.texi - -@set VERSION 0.3 - -@setfilename ../../info/auth -@settitle Emacs auth-source Library @value{VERSION} -@documentencoding UTF-8 - -@copying -This file describes the Emacs auth-source library. - -Copyright @copyright{} 2008--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs lisp libraries -@direntry -* Auth-source: (auth). The Emacs auth-source library. -@end direntry - -@titlepage -@ifset WEBHACKDEVEL -@title Emacs auth-source Library (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Emacs auth-source Library -@end ifclear -@author by Ted Zlatanov -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs auth-source -This manual describes the Emacs auth-source library. - -It is a way for multiple applications to share a single configuration -(in Emacs and in files) for user convenience. - -@insertcopying - -@menu -* Overview:: Overview of the auth-source library. -* Help for users:: -* Secret Service API:: -* Help for developers:: -* GnuPG and EasyPG Assistant Configuration:: -* GNU Free Documentation License:: The license for this documentation. -* Index:: -* Function Index:: -* Variable Index:: -@end menu -@end ifnottex - -@node Overview -@chapter Overview - -The auth-source library is simply a way for Emacs and Gnus, among -others, to answer the old burning question ``What are my user name and -password?'' - -(This is different from the old question about burning ``Where is the -fire extinguisher, please?''.) - -The auth-source library supports more than just the user name or the -password (known as the secret). - -Similarly, the auth-source library supports multiple storage backend, -currently either the classic ``netrc'' backend, examples of which you -can see later in this document, or the Secret Service API@. This is -done with EIEIO-based backends and you can write your own if you want. - -@node Help for users -@chapter Help for users - -``Netrc'' files are a de facto standard. They look like this: -@example -machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} -@end example - -The @code{machine} is the server (either a DNS name or an IP address). -It's known as @var{:host} in @code{auth-source-search} queries. You -can also use @code{host}. - -The @code{port} is the connection port or protocol. It's known as -@var{:port} in @code{auth-source-search} queries. - -The @code{user} is the user name. It's known as @var{:user} in -@code{auth-source-search} queries. You can also use @code{login} and -@code{account}. - -Spaces are always OK as far as auth-source is concerned (but other -programs may not like them). Just put the data in quotes, escaping -quotes as you'd expect with @samp{\}. - -All these are optional. You could just say (but we don't recommend -it, we're just showing that it's possible) - -@example -password @var{mypassword} -@end example - -to use the same password everywhere. Again, @emph{DO NOT DO THIS} or -you will be pwned as the kids say. - -``Netrc'' files are usually called @file{.authinfo} or @file{.netrc}; -nowadays @file{.authinfo} seems to be more popular and the auth-source -library encourages this confusion by accepting both, as you'll see -later. - -If you have problems with the search, set @code{auth-source-debug} to -@code{'trivia} and see what host, port, and user the library is -checking in the @file{*Messages*} buffer. Ditto for any other -problems, your first step is always to see what's being checked. The -second step, of course, is to write a blog entry about it and wait for -the answer in the comments. - -You can customize the variable @code{auth-sources}. The following may -be needed if you are using an older version of Emacs or if the -auth-source library is not loaded for some other reason. - -@lisp -(require 'auth-source) ;; probably not necessary -(customize-variable 'auth-sources) ;; optional, do it once -@end lisp - -@defvar auth-sources - -The @code{auth-sources} variable tells the auth-source library where -your netrc files or Secret Service API collection items live for a -particular host and protocol. While you can get fancy, the default -and simplest configuration is: - -@lisp -;;; old default: required :host and :port, not needed anymore -(setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t))) -;;; mostly equivalent (see below about fallbacks) but shorter: -(setq auth-sources '((:source "~/.authinfo.gpg"))) -;;; even shorter and the @emph{default}: -(setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc")) -;;; use the Secrets API @var{Login} collection -;;; (@pxref{Secret Service API}) -(setq auth-sources '("secrets:Login")) -@end lisp - -By adding multiple entries to @code{auth-sources} with a particular -host or protocol, you can have specific netrc files for that host or -protocol. Usually this is unnecessary but may make sense if you have -shared netrc files or some other unusual setup (90% of Emacs users -have unusual setups and the remaining 10% are @emph{really} unusual). - -Here's a mixed example using two sources: - -@lisp -(setq auth-sources '((:source (:secrets default) - :host "myserver" :user "joe") - "~/.authinfo.gpg")) -@end lisp - -@end defvar - -If you don't customize @code{auth-sources}, you'll have to live with -the defaults: the unencrypted netrc file @file{~/.authinfo} will be -used for any host and any port. - -If that fails, any host and any port are looked up in the netrc file -@file{~/.authinfo.gpg}, which is a GnuPG encrypted file (@pxref{GnuPG -and EasyPG Assistant Configuration}). - -Finally, the unencrypted netrc file @file{~/.netrc} will be used for -any host and any port. - -The typical netrc line example is without a port. - -@example -machine YOURMACHINE login YOU password YOURPASSWORD -@end example - -This will match any authentication port. Simple, right? But what if -there's a SMTP server on port 433 of that machine that needs a -different password from the IMAP server? - -@example -machine YOURMACHINE login YOU password SMTPPASSWORD port 433 -machine YOURMACHINE login YOU password GENERALPASSWORD -@end example - -For url-auth authentication (HTTP/HTTPS), you need to put this in your -netrc file: - -@example -machine yourmachine.com:80 port http login testuser password testpass -@end example - -This will match any realm and authentication method (basic or digest) -over HTTP@. HTTPS is set up similarly. If you want finer controls, -explore the url-auth source code and variables. - -For Tramp authentication, use: - -@example -machine yourmachine.com port scp login testuser password testpass -@end example - -Note that the port denotes the Tramp connection method. When you -don't use a port entry, you match any Tramp method, as explained -earlier. Since Tramp has about 88 connection methods, this may be -necessary if you have an unusual (see earlier comment on those) setup. - -@node Secret Service API -@chapter Secret Service API - -The @dfn{Secret Service API} is a standard from -@uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org} -to securely store passwords and other confidential information. This -API is implemented by system daemons such as the GNOME Keyring and the -KDE Wallet (these are GNOME and KDE packages respectively and should -be available on most modern GNU/Linux systems). - -The auth-source library uses the @file{secrets.el} library to connect -through the Secret Service API@. You can also use that library in -other packages, it's not exclusive to auth-source. - -@defvar secrets-enabled -After loading @file{secrets.el}, a non-@code{nil} value of this -variable indicates the existence of a daemon providing the Secret -Service API. -@end defvar - -@deffn Command secrets-show-secrets -This command shows all collections, items, and their attributes. -@end deffn - -The atomic objects managed by the Secret Service API are @dfn{secret -items}, which contain things an application wishes to store securely, -like a password. Secret items have a label (a name), the @dfn{secret} -(which is the string we want, like a password), and a set of lookup -attributes. The attributes can be used to search and retrieve a -secret item at a later date. - -Secret items are grouped in @dfn{collections}. A collection is -sometimes called a @samp{keyring} or @samp{wallet} in GNOME Keyring -and KDE Wallet but it's the same thing, a group of secrets. -Collections are personal and protected so only the owner can open them. - -The most common collection is called @code{"login"}. - -A collection can have an alias. The alias @code{"default"} is -commonly used so the clients don't have to know the specific name of -the collection they open. Other aliases are not supported yet. -Since aliases are globally accessible, set the @code{"default"} alias -only when you're sure it's appropriate. - -@defun secrets-list-collections -This function returns all the collection names as a list. -@end defun - -@defun secrets-set-alias collection alias -Set @var{alias} as alias of collection labeled @var{collection}. -Currently only the alias @code{"default"} is supported. -@end defun - -@defun secrets-get-alias alias -Return the collection name @var{alias} is referencing to. -Currently only the alias @code{"default"} is supported. -@end defun - -Collections can be created and deleted by the functions -@code{secrets-create-collection} and @code{secrets-delete-collection}. -Usually, this is not done from within Emacs. Do not delete standard -collections such as @code{"login"}. - -The special collection @code{"session"} exists for the lifetime of the -corresponding client session (in our case, Emacs's lifetime). It is -created automatically when Emacs uses the Secret Service interface and -it is deleted when Emacs is killed. Therefore, it can be used to -store and retrieve secret items temporarily. The @code{"session"} -collection is better than a persistent collection when the secret -items should not live longer than Emacs. The session collection can -be specified either by the string @code{"session"}, or by @code{nil}, -whenever a collection parameter is needed in the following functions. - -@defun secrets-list-items collection -Returns all the item labels of @var{collection} as a list. -@end defun - -@defun secrets-create-item collection item password &rest attributes -This function creates a new item in @var{collection} with label -@var{item} and password @var{password}. @var{attributes} are -key-value pairs set for the created item. The keys are keyword -symbols, starting with a colon. Example: - -@example -;;; The session "session", the label is "my item" -;;; and the secret (password) is "geheim" -(secrets-create-item "session" "my item" "geheim" - :method "sudo" :user "joe" :host "remote-host") -@end example -@end defun - -@defun secrets-get-secret collection item -Return the secret of item labeled @var{item} in @var{collection}. -If there is no such item, return @code{nil}. -@end defun - -@defun secrets-delete-item collection item -This function deletes item @var{item} in @var{collection}. -@end defun - -The lookup attributes, which are specified during creation of a -secret item, must be a key-value pair. Keys are keyword symbols, -starting with a colon; values are strings. They can be retrieved -from a given secret item and they can be used for searching of items. - -@defun secrets-get-attribute collection item attribute -Returns the value of key @var{attribute} of item labeled @var{item} in -@var{collection}. If there is no such item, or the item doesn't own -this key, the function returns @code{nil}. -@end defun - -@defun secrets-get-attributes collection item -Return the lookup attributes of item labeled @var{item} in -@var{collection}. If there is no such item, or the item has no -attributes, it returns @code{nil}. Example: - -@example -(secrets-get-attributes "session" "my item") - @result{} ((:user . "joe") (:host ."remote-host")) -@end example -@end defun - -@defun secrets-search-items collection &rest attributes -Search for the items in @var{collection} with matching -@var{attributes}. The @var{attributes} are key-value pairs, as used -in @code{secrets-create-item}. Example: - -@example -(secrets-search-items "session" :user "joe") - @result{} ("my item" "another item") -@end example -@end defun - -The auth-source library uses the @file{secrets.el} library and thus -the Secret Service API when you specify a source matching -@code{"secrets:COLLECTION"}. For instance, you could use -@code{"secrets:session"} to use the @code{"session"} collection, open only -for the lifetime of Emacs. Or you could use @code{"secrets:Login"} to -open the @code{"Login"} collection. As a special case, you can use the -symbol @code{default} in @code{auth-sources} (not a string, but a -symbol) to specify the @code{"default"} alias. Here is a contrived -example that sets @code{auth-sources} to search three collections and -then fall back to @file{~/.authinfo.gpg}. - -@example -(setq auth-sources '(default - "secrets:session" - "secrets:Login" - "~/.authinfo.gpg")) -@end example - -@node Help for developers -@chapter Help for developers - -The auth-source library lets you control logging output easily. - -@defvar auth-source-debug -Set this variable to @code{'trivia} to see lots of output in -@file{*Messages*}, or set it to a function that behaves like -@code{message} to do your own logging. -@end defvar - -The auth-source library only has a few functions for external use. - -@defun auth-source-search &rest spec &key type max host user port secret require create delete &allow-other-keys -This function searches (or modifies) authentication backends according -to @var{spec}. See the function's doc-string for details. -@c TODO more details. -@end defun - -Let's take a look at an example of using @code{auth-source-search} -from Gnus's @code{nnimap.el}. - -@example -(defun nnimap-credentials (address ports) - (let* ((auth-source-creation-prompts - '((user . "IMAP user at %h: ") - (secret . "IMAP password for %u@@%h: "))) - (found (nth 0 (auth-source-search :max 1 - :host address - :port ports - :require '(:user :secret) - :create t)))) - (if found - (list (plist-get found :user) - (let ((secret (plist-get found :secret))) - (if (functionp secret) - (funcall secret) - secret)) - (plist-get found :save-function)) - nil))) -@end example - -This call requires the user and password (secret) to be in the -results. It also requests that an entry be created if it doesn't -exist already. While the created entry is being assembled, the shown -prompts will be used to interact with the user. The caller can also -pass data in @code{auth-source-creation-defaults} to supply defaults -for any of the prompts. - -Note that the password needs to be evaluated if it's a function. It's -wrapped in a function to provide some security. - -Later, after a successful login, @code{nnimap.el} calls the -@code{:save-function} like so: - -@example -(when (functionp (nth 2 credentials)) - (funcall (nth 2 credentials))) -@end example - -This will work whether the @code{:save-function} was provided or not. -@code{:save-function} will be provided only when a new entry was -created, so this effectively says ``after a successful login, save the -authentication information we just used, if it was newly created.'' - -After the first time it's called, the @code{:save-function} will not -run again (but it will log something if you have set -@code{auth-source-debug} to @code{'trivia}). This is so it won't ask -the same question again, which is annoying. This is so it won't ask -the same question again, which is annoying. This is so it won't ask -the same question again, which is annoying. - -So the responsibility of the API user that specified @code{:create t} -is to call the @code{:save-function} if it's provided. - -@defun auth-source-delete &rest spec &key delete &allow-other-keys -This function deletes entries matching @var{spec} from the -authentication backends. It returns the entries that were deleted. -The backend may not actually delete the entries. -@end defun - -@defun auth-source-forget spec -This function forgets any cached data that exactly matches @var{spec}. -It returns @code{t} if it forget some data, and @code{nil} if no -matching data was found. -@end defun - -@defun auth-source-forget+ &rest spec &allow-other-keys -This function forgets any cached data matching @var{spec}. -It returns the number of items forgotten. -@end defun - -@node GnuPG and EasyPG Assistant Configuration -@appendix GnuPG and EasyPG Assistant Configuration - -If the @code{auth-sources} variable contains @file{~/.authinfo.gpg} -before @file{~/.authinfo}, the auth-source library will try to -read the GnuPG encrypted @file{.gpg} file first, before -the unencrypted file. - -In Emacs 23 or later there is an option @code{auto-encryption-mode} to -automatically decrypt @file{*.gpg} files. It is enabled by default. -If you are using earlier versions of Emacs, you will need: - -@lisp -(require 'epa-file) -(epa-file-enable) -@end lisp - -If you want your GnuPG passwords to be cached, set up @code{gpg-agent} -or EasyPG Assistant -(@pxref{Caching Passphrases, , Caching Passphrases, epa}). - -To quick start, here are some questions: - -@enumerate -@item -Do you use GnuPG version 2 instead of GnuPG version 1? -@item -Do you use symmetric encryption rather than public key encryption? -@item -Do you want to use gpg-agent? -@end enumerate - -Here are configurations depending on your answers: - -@multitable {111} {222} {333} {configuration configuration configuration} -@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration -@item Yes @tab Yes @tab Yes @tab Set up gpg-agent. -@item Yes @tab Yes @tab No @tab You can't, without gpg-agent. -@item Yes @tab No @tab Yes @tab Set up gpg-agent. -@item Yes @tab No @tab No @tab You can't, without gpg-agent. -@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. -@item No @tab Yes @tab No @tab Set up elisp passphrase cache. -@item No @tab No @tab Yes @tab Set up gpg-agent. -@item No @tab No @tab No @tab You can't, without gpg-agent. -@end multitable - -To set up gpg-agent, follow the instruction in GnuPG manual -(@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}). - -To set up elisp passphrase cache, set -@code{epa-file-cache-passphrase-for-symmetric-encryption}. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@node Function Index -@unnumbered Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye - -@c End: diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi deleted file mode 100644 index 3ddeb08a306..00000000000 --- a/doc/misc/autotype.texi +++ /dev/null @@ -1,669 +0,0 @@ -\input texinfo -@c This is an annex of the Emacs manual. -@c Author: Daniel Pfeiffer -@setfilename ../../info/autotype -@c @node Autotypist, Picture, Abbrevs, Top -@c @chapter Features for Automatic Typing -@settitle Features for Automatic Typing -@documentencoding UTF-8 -@c @cindex text -@c @cindex selfinserting text -@c @cindex autotypist - -@copying -Copyright @copyright{} 1994--1995, 1999, 2001--2014 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Autotype: (autotype). Convenient features for text that you enter - frequently in Emacs. -@end direntry - -@titlepage -@sp 10 - -@center @titlefont{Autotyping} -@sp 2 -@center Convenient features for text that you enter frequently in Emacs -@sp 2 -@center Daniel Pfeiffer -@center additions by Dave Love - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top Autotyping - - Under certain circumstances you will find yourself typing similar things -over and over again. This is especially true of form letters and programming -language constructs. Project-specific header comments, flow-control -constructs or magic numbers are essentially the same every time. Emacs has -various features for doing tedious and repetitive typing chores for you -in addition to the Abbrev features (@pxref{Abbrevs,,, emacs, The GNU Emacs Manual}). - - One solution is using skeletons, flexible rules that say what to -insert, and how to do it. Various programming language modes offer some -ready-to-use skeletons, and you can adapt them to suit your needs or -taste, or define new ones. - - Another feature is automatic insertion of what you want into empty files, -depending on the file-name or the mode as appropriate. You can have a file or -a skeleton inserted, or you can call a function. Then there is the -possibility to have Un*x interpreter scripts automatically take on a magic -number and be executable as soon as they are saved. Or you can have a -copyright notice's year updated, if necessary, every time you save a -file. Similarly for time stamps in the file. - - URLs can be inserted based on a word at point. Flexible templates can -be defined for inserting and navigating between text more generally. A -sort of meta-expansion facility can be used to try a set of alternative -completions and expansions of text at point. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Using Skeletons:: How to insert a skeleton into your text. -* Wrapping Skeletons:: Putting existing text within a skeleton. -* Skeletons as Abbrevs:: An alternative for issuing skeleton commands. -* Skeleton Language:: Making skeleton commands insert what you want. -* Inserting Pairs:: Typing one character and getting another - after point. -* Autoinserting:: Filling up empty files as soon as you visit them. -* Copyrights:: Inserting and updating copyrights. -* Executables:: Turning interpreter scripts into executables. -* Timestamps:: Updating dates and times in modified files. -* QuickURL:: Inserting URLs based on text at point. -* Tempo:: Flexible template insertion. -* Hippie Expand:: Expansion of text trying various methods. - -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: -* Command Index:: -* Variable Index:: -@end menu - - -@node Using Skeletons -@chapter Using Skeletons -@cindex skeletons -@cindex using skeletons - - When you want Emacs to insert a form letter or a typical construct of the -programming language you are using, skeletons are a means of accomplishing -this. Normally skeletons each have a command of their own, that, when called, -will insert the skeleton. These commands can be issued in the usual ways -(@pxref{Commands,,, emacs, The GNU Emacs Manual}). Modes that offer various skeletons will often -bind these to key-sequences on the @kbd{C-c} prefix, as well as having -an @cite{Insert} menu and maybe even predefined abbrevs for them -(@pxref{Skeletons as Abbrevs}). - - The simplest kind of skeleton will simply insert some text indented -according to the major mode and leave the cursor at a likely place in the -middle. Interactive skeletons may prompt you for a string that will be part -of the inserted text. - - Skeletons may ask for input several times. They even have a looping -mechanism in which you will be asked for input as long as you are willing to -furnish it. An example would be multiple ``else if'' conditions. You can -recognize this situation by a prompt ending in @key{RET}, @kbd{C-g} -or @kbd{C-h}. This -means that entering an empty string will simply assume that you are finished. -Typing quit on the other hand terminates the loop but also the rest of the -skeleton, e.g., an ``else'' clause is skipped. Only a syntactically necessary -termination still gets inserted. - - - -@node Wrapping Skeletons -@chapter Wrapping Skeletons Around Existing Text -@cindex wrapping skeletons - - Often you will find yourself with some code that for whatever reason -suddenly becomes conditional. Or you have written a bit of text and want to -put it in the middle of a form letter. Skeletons provide a means for -accomplishing this, and can even, in the case of programming languages, -reindent the wrapped code for you. - - Skeleton commands take an optional numeric prefix argument -(@pxref{Arguments,,, emacs, The GNU Emacs Manual}). This is interpreted in two different ways depending -on whether the prefix is positive, i.e., forwards oriented, or negative, -i.e., backwards oriented. - - A positive prefix means to wrap the skeleton around that many -following words. This is accomplished by putting the words there where -the point is normally left after that skeleton is inserted (@pxref{Using -Skeletons}). The point (@pxref{Point,,, emacs, The GNU Emacs Manual}) is left at the next -interesting spot in the skeleton instead. - - A negative prefix means to do something similar with that many previously -marked interregions (@pxref{Mark,,, emacs, The GNU Emacs Manual}). In the simplest case, if you type -@kbd{M--} just before issuing the skeleton command, that will wrap the -skeleton around the current region, just like a positive argument would have -wrapped it around a number of words. - - Smaller negative arguments will wrap that many interregions into successive -interesting spots within the skeleton, again leaving the point at the next one. -We speak about interregions rather than regions here, because we treat them in -the order they appear in the buffer, which coincides with successive regions -only if they were marked in order. - - That is, if you marked in alphabetical order the points A B C [] (where [] -represents the point) and call a skeleton command with @kbd{M-- 3}, you will -wrap the text from A to B into the first interesting spot of the skeleton, the -text from B to C into the next one, the text from C to the point into the -third one, and leave the point in the fourth one. If there are less marks in -the buffer, or if the skeleton defines less interesting points, the surplus is -ignored. - - If, on the other hand, you marked in alphabetical order the points [] A C B, -and call a skeleton command with @kbd{M-- 3}, you will wrap the text from -point to A, then the text from A to C and finally the text from C to B@. This -is done because the regions overlap and Emacs would be helplessly lost if it -tried to follow the order in which you marked these points. - - - -@node Skeletons as Abbrevs -@chapter Skeletons as Abbrev Expansions -@cindex skeletons as abbrevs - - Rather than use a key binding for every skeleton command, you can also -define an abbreviation (@pxref{Defining Abbrevs,,, emacs, The GNU Emacs Manual}) that will expand -(@pxref{Expanding Abbrevs,,, emacs, The GNU Emacs Manual}) into the skeleton. - - Say you want @samp{ifst} to be an abbreviation for the C language if -statement. You will tell Emacs that @samp{ifst} expands to the empty string -and then calls the skeleton command. In Emacs Lisp you can say something like -@code{(define-abbrev c-mode-abbrev-table "ifst" "" 'c-if)}. Or you can edit -the output from @kbd{M-x list-abbrevs} to make it look like this: - -@example -(c-mode-abbrev-table) -"if" 0 "" c-if -@end example - -@noindent -(Some blank lines of no semantic significance, and other abbrev tables, -have been omitted.) - - - -@node Skeleton Language -@chapter Skeleton Language -@cindex skeleton language - -@findex skeleton-insert - Skeletons are an shorthand extension to the Lisp language, where various -atoms directly perform either actions on the current buffer or rudimentary -flow control mechanisms. Skeletons are interpreted by the function -@code{skeleton-insert}. - - A skeleton is a list starting with an interactor, which is usually a -prompt-string, or @code{nil} when not needed, but can also be a Lisp -expression for complex read functions or for returning some calculated value. -The rest of the list are any number of elements as described in the following -table: - -@table @asis -@item @code{"@var{string}"}, @code{?@var{c}}, @code{?\@var{c}} -@vindex skeleton-transformation -Insert string or character. Literal strings and characters are passed through -@code{skeleton-transformation} when that is non-@code{nil}. -@item @code{?\n} -@c ??? something seems very wrong here. -Insert a newline and align under current line, but not if this is the -last element of a skeleton and the newline would be inserted at end of -line, or this is the first element and the newline would be inserted -at beginning of line. Use newline character @code{?\n} to prevent -alignment. Use @code{"\n"} as the first or last string element of a -skeleton to insert a newline unconditionally. -@item @code{_} -Interesting point. When wrapping skeletons around successive regions, they are -put at these places. Point is left at first @code{_} where nothing is wrapped. -@item @code{>} -Indent line according to major mode. When following element is @code{_}, and -there is a interregion that will be wrapped here, indent that interregion. -@item @code{&} -Logical and. If preceding element moved point, i.e., usually inserted -something, do following element. -@item @code{|} -Logical xor. If preceding element didn't move point, i.e., usually inserted -nothing, do following element. -@item @code{-@var{number}} -Delete preceding number characters. Depends on value of -@code{skeleton-untabify}. -@item @code{()} or @code{nil} -Ignored. -@item @var{lisp-expression} -Evaluated, and the return value is again interpreted as a skeleton element. -@item @code{str} -A special variable that, when evaluated the first time, usually prompts -for input according to the skeleton's interactor. It is then set to the -return value resulting from the interactor. Each subskeleton has its local -copy of this variable. -@item @code{v1}, @code{v2} -Skeleton-local user variables. -@item @code{'@var{expression}} -Evaluate following Lisp expression for its side-effect, but prevent it from -being interpreted as a skeleton element. -@item @var{skeleton} -Subskeletons are inserted recursively, not once, but as often as the user -enters something at the subskeletons interactor. Thus there must be a -@code{str} in the subskeleton. They can also be used non-interactively, when -prompt is a lisp-expression that returns successive list-elements. -@item @code{resume:} -Ignored. Execution resumes here if the user quits during skeleton -interpretation. -@item @code{quit} -A constant which is non-@code{nil} when the @code{resume:} section was entered -because the user quit. -@end table - -@findex skeleton-further-elements - Some modes also use other skeleton elements they themselves defined. For -example in shell script mode's skeletons you will find @code{<} which does a -rigid indentation backwards, or in CC mode's skeletons you find the -self-inserting elements @code{@{} and @code{@}}. These are defined by the -buffer-local variable @code{skeleton-further-elements} which is a list of -variables bound while interpreting a skeleton. - -@findex define-skeleton - The macro @code{define-skeleton} defines a command for interpreting a -skeleton. The first argument is the command name, the second is a -documentation string, and the rest is an interactor and any number of skeleton -elements together forming a skeleton. This skeleton is assigned to a variable -of the same name as the command and can thus be overridden from your -@file{~/.emacs} file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). - - - -@node Inserting Pairs -@chapter Inserting Matching Pairs of Characters -@cindex inserting pairs -@cindex pairs - - Various characters usually appear in pairs. When, for example, you insert -an open parenthesis, no matter whether you are programming or writing prose, -you will surely enter a closing one later. By entering both at the same time -and leaving the cursor in between, Emacs can guarantee you that such -parentheses are always balanced. And if you have a non-qwerty keyboard, where -typing some of the stranger programming language symbols makes you bend your -fingers backwards, this can be quite relieving too. - -@findex skeleton-pair-insert-maybe -@vindex skeleton-pair - This is done by binding the first key (@pxref{Rebinding,,, emacs, The GNU Emacs Manual}) of -the pair to @code{skeleton-pair-insert-maybe} instead of -@code{self-insert-command}. The ``maybe'' comes from the fact that -this at-first surprising behavior is initially turned off. To enable -it, you must set @code{skeleton-pair} to some non-@code{nil} value. -And even then, a positive argument (@pxref{Arguments,,, emacs, The GNU Emacs Manual}) will -make this key behave like a self-inserting key -(@pxref{Inserting Text,,, emacs, The GNU Emacs Manual}). - -@vindex skeleton-pair-on-word - While this breaks with the stated intention of always balancing pairs, it -turns out that one often doesn't want pairing to occur, when the following -character is part of a word. If you want pairing to occur even then, set -@code{skeleton-pair-on-word} to some non-@code{nil} value. - -@vindex skeleton-pair-alist - Pairing is possible for all visible characters. By default the -parenthesis @samp{(}, the square bracket @samp{[}, the brace -@samp{@{}, the pointed bracket @samp{<} and the backquote @samp{`} all -pair with the symmetrical character. All other characters pair -themselves. This behavior can be modified by the variable -@code{skeleton-pair-alist}. This is in fact an alist of skeletons -(@pxref{Skeleton Language}), with the first part of each sublist -matching the typed character. This is the position of the interactor, -but since pairs don't need the @code{str} element, this is ignored. - - Some modes have bound the command @code{skeleton-pair-insert-maybe} -to relevant keys. These modes also configure the pairs as -appropriate. For example, when typing english prose, you'd expect the -backquote (@samp{`}) to pair with the quote (@samp{'}), while in Shell -script mode it must pair to itself. They can also inhibit pairing in -certain contexts. For example an escaped character stands for itself. - - - -@node Autoinserting -@chapter Autoinserting Text in Empty Files -@cindex autoinserting - -@findex auto-insert - @kbd{M-x auto-insert} will put some predefined text at the beginning of -the buffer. The main application for this function, as its name suggests, -is to have it be called automatically every time an empty, and only an -empty file is visited. This is accomplished by putting @code{(add-hook -'find-file-hook 'auto-insert)} into your @file{~/.emacs} file -(@pxref{Init File,,, emacs, The GNU Emacs Manual}). - -@vindex auto-insert-alist - What gets inserted, if anything, is determined by the variable -@code{auto-insert-alist}. The @sc{car}s of this list are each either -a mode name, making an element applicable when a buffer is in that -mode. Or they can be a string, which is a regexp matched against the -buffer's file name. In that way different kinds of files that have -the same mode in Emacs can be distinguished. The @sc{car}s may also -be cons cells consisting of mode name or regexp as above and an -additional descriptive string. - - When a matching element is found, the @sc{cdr} says what to do. It may -be a string, which is a file name, whose contents are to be inserted, if -that file is found in the directory @code{auto-insert-directory} or under a -absolute file name. Or it can be a skeleton (@pxref{Skeleton Language}) to -be inserted. - - It can also be a function, which allows doing various things. The function -can simply insert some text, indeed, it can be skeleton command (@pxref{Using -Skeletons}). It can be a lambda function which will for example conditionally -call another function. Or it can even reset the mode for the buffer. If you -want to perform several such actions in order, you use a vector, i.e., several -of the above elements between square brackets (@samp{[@r{@dots{}}]}). - - By default C and C++ headers insert a definition of a symbol derived from -the filename to prevent multiple inclusions. C and C++ sources insert an -include of the header. Makefiles insert the file makefile.inc if it exists. - - TeX and bibTeX mode files insert the file tex-insert.tex if it exists, while -LaTeX mode files insert a typical @code{\documentclass} frame. Html -files insert a skeleton with the usual frame. - - Ada mode files call the Ada header skeleton command. Emacs lisp -source files insert the usual header, with a copyright of your -environment variable @env{$ORGANIZATION} or else the FSF, and prompt -for valid keywords describing the contents. Files in a @file{bin} -directory for which Emacs could determine no specialized mode -(@pxref{Choosing Modes,,, emacs, The GNU Emacs Manual}) are set to Shell script mode. - -@findex define-auto-insert - In Lisp (@pxref{Init File,,, emacs, The GNU Emacs Manual}) you can use the function -@code{define-auto-insert} to add to or modify -@code{auto-insert-alist}. See its documentation with @kbd{C-h f -define-auto-insert}. - -@vindex auto-insert - The variable @code{auto-insert} says what to do when @code{auto-insert} is -called non-interactively, e.g., when a newly found file is empty (see above): -@table @asis -@item @code{nil} -Do nothing. -@item @code{t} -Insert something if possible, i.e., there is a matching entry in -@code{auto-insert-alist}. -@item other -Insert something if possible, but mark as unmodified. -@end table - -@vindex auto-insert-query - The variable @code{auto-insert-query} controls whether to ask about -inserting something. When this is @code{nil}, inserting is only done with -@kbd{M-x auto-insert}. When this is @code{function}, you are queried -whenever @code{auto-insert} is called as a function, such as when Emacs -visits an empty file and you have set the above-mentioned hook. Otherwise -you are always queried. - -@vindex auto-insert-prompt - When querying, the variable @code{auto-insert-prompt}'s value is used as a -prompt for a y-or-n-type question. If this includes a @samp{%s} construct, -that is replaced by what caused the insertion rule to be chosen. This is -either a descriptive text, the mode-name of the buffer or the regular -expression that matched the filename. - - - -@node Copyrights -@chapter Inserting and Updating Copyrights -@cindex copyrights - -@findex copyright - @kbd{M-x copyright} is a skeleton inserting command, that adds a copyright -notice at the point. The ``by'' part is taken from your environment variable -@env{$ORGANIZATION} or if that isn't set you are prompted for it. If the -buffer has a comment syntax (@pxref{Comments,,, emacs, The GNU Emacs Manual}), this is inserted as a comment. - -@findex copyright-update -@vindex copyright-limit -@vindex copyright-current-year - @kbd{M-x copyright-update} looks for a copyright notice in the first -@code{copyright-limit} characters of the buffer and updates it when necessary. -The current year (variable @code{copyright-current-year}) is added to the -existing ones, in the same format as the preceding year, i.e., 1994, '94 or 94. -If a dash-separated year list up to last year is found, that is extended to -current year, else the year is added separated by a comma. Or it replaces -them when this is called with a prefix argument. If a header referring to a -wrong version of the GNU General Public License (@pxref{Copying,,, emacs, The GNU Emacs Manual}) is found, -that is updated too. - - An interesting application for this function is to have it be called -automatically every time a file is saved. This is accomplished by -putting @code{(add-hook 'before-save-hook 'copyright-update)} into -your @file{~/.emacs} file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). Alternative, -you can do @kbd{M-x customize-variable @key{RET} before-save-hook -@key{RET}}. @code{copyright-update} is conveniently listed as an -option in the customization buffer. - -@vindex copyright-query - The variable @code{copyright-query} controls whether to update the -copyright or whether to ask about it. When this is @code{nil} updating is -only done with @kbd{M-x copyright-update}. When this is @code{function} -you are queried whenever @code{copyright-update} is called as a function, -such as in the @code{before-save-hook} feature mentioned above. Otherwise -you are always queried. - - - -@node Executables -@chapter Making Interpreter Scripts Executable -@cindex executables - -@vindex executable-prefix -@vindex executable-chmod - Various interpreter modes such as Shell script mode or AWK mode will -automatically insert or update the buffer's magic number, a special -comment on the first line that makes the @code{exec} systemcall know -how to execute the script. To this end the script is automatically -made executable upon saving, with @code{executable-chmod} as argument -to the system @code{chmod} command. The magic number is prefixed by -the value of @code{executable-prefix}. - -@vindex executable-magicless-file-regexp - Any file whose name matches @code{executable-magicless-file-regexp} is not -furnished with a magic number, nor is it made executable. This is mainly -intended for resource files, which are only meant to be read in. - -@vindex executable-insert - The variable @code{executable-insert} says what to do when -@code{executable-set-magic} is called non-interactively, e.g., when file has no -or the wrong magic number: -@table @asis -@item @code{nil} -Do nothing. -@item @code{t} -Insert or update magic number. -@item other -Insert or update magic number, but mark as unmodified. -@end table - -@findex executable-set-magic -@vindex executable-query - The variable @code{executable-query} controls whether to ask about -inserting or updating the magic number. When this is @code{nil} updating -is only done with @kbd{M-x executable-set-magic}. When this is -@code{function} you are queried whenever @code{executable-set-magic} is -called as a function, such as when Emacs puts a buffer in Shell script -mode. Otherwise you are always queried. - -@findex executable-self-display - @kbd{M-x executable-self-display} adds a magic number to the buffer, which -will turn it into a self displaying text file, when called as a Un*x command. -The ``interpreter'' used is @code{executable-self-display} with argument -@samp{+2}. - -@node Timestamps -@chapter Maintaining Timestamps in Modified Files -@cindex timestamps - -@findex time-stamp -@vindex before-save-hook -The @code{time-stamp} command can be used to update automatically a -template in a file with a new time stamp every time you save the file. -Customize the hook @code{before-save-hook} to add the function -@code{time-stamp} to arrange this. It you use Custom to do this, -then @code{time-stamp} is conveniently listed as an option in the -customization buffer. - -@vindex time-stamp-active -@vindex time-stamp-format -@vindex time-stamp-start -The time stamp is updated only if the customizable variable -@code{time-stamp-active} is on, which it is by default; the command -@code{time-stamp-toggle-active} can be used to toggle it. The format of -the time stamp is set by the customizable variable -@code{time-stamp-format}. - -@vindex time-stamp-line-limit -@vindex time-stamp-end -@vindex time-stamp-count -@vindex time-stamp-inserts-lines -The variables @code{time-stamp-line-limit}, @code{time-stamp-start}, -@code{time-stamp-end}, @code{time-stamp-count}, and -@code{time-stamp-inserts-lines} control finding the template. Do not -change these in your init file or you will be incompatible with other -people's files. If you must change them, do so only in the local -variables section of the file itself. - -Normally the template must appear in the first 8 lines of a file and -look like one of the following: - -@example -Time-stamp: <> -Time-stamp: " " -@end example - -The time stamp is written between the brackets or quotes: - -@example -Time-stamp: <1998-02-18 10:20:51 gildea> -@end example - -@node QuickURL -@chapter QuickURL: Inserting URLs Based on Text at Point - -@vindex quickurl-url-file -@findex quickurl -@cindex URLs -@kbd{M-x quickurl} can be used to insert a URL into a buffer based on -the text at point. The URLs are stored in an external file defined by -the variable @code{quickurl-url-file} as a list of either cons cells of -the form @code{(@var{key} . @var{URL})} or -lists of the form @code{(@var{key} @var{URL} @var{comment})}. These -specify that @kbd{M-x quickurl} should insert @var{URL} if the word -@var{key} is at point, for example: - -@example -(("FSF" "http://www.fsf.org/" "The Free Software Foundation") - ("emacs" . "http://www.emacs.org/") - ("hagbard" "http://www.hagbard.demon.co.uk" "Hagbard's World")) -@end example - -@findex quickurl-add-url -@findex quickurl-list -@kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL} -pair. @kbd{M-x quickurl-list} provides interactive editing of the URL -list. - -@node Tempo -@chapter Tempo: Flexible Template Insertion - -@cindex templates -The Tempo package provides a simple way to define powerful templates, or -macros, if you wish. It is mainly intended for, but not limited to, -programmers to be used for creating shortcuts for editing -certain kinds of documents. - -@findex tempo-backward-mark -@findex tempo-forward-mark -A template is defined as a list of items to be inserted in the current -buffer at point. Some can be simple strings, while others can control -formatting or define special points of interest in the inserted text. -@kbd{M-x tempo-backward-mark} and @kbd{M-x tempo-forward-mark} can be -used to jump between such points. - -More flexible templates can be created by including Lisp symbols, which -will be evaluated as variables, or lists, which will be evaluated -as Lisp expressions. Automatic completion of specified tags to expanded -templates can be provided. - -@findex tempo-define-template -See the documentation for @code{tempo-define-template} for the different -items that can be used to define a tempo template with a command for -inserting it. - -See the commentary in @file{tempo.el} for more information on using the -Tempo package. - -@node Hippie Expand -@chapter `Hippie' Expansion - -@findex hippie-expand -@kindex M-/ -@vindex hippie-expand-try-functions-list -@kbd{M-x hippie-expand} is a single command providing a variety of -completions and expansions. Called repeatedly, it tries all possible -completions in succession. - -Which ones to try, and in which order, is determined by the contents of -the customizable option @code{hippie-expand-try-functions-list}. Much -customization of the expansion behavior can be made by changing the -order of, removing, or inserting new functions in this list. Given a -positive numeric argument, @kbd{M-x hippie-expand} jumps directly that -number of functions forward in this list. Given some other argument (a -negative argument or just @kbd{C-u}) it undoes the tried completion. - -See the commentary in @file{hippie-exp.el} for more information on the -possibilities. - -Typically you would bind @code{hippie-expand} to @kbd{M-/} with -@code{dabbrev-expand}, the standard binding of @kbd{M-/}, providing one -of the expansion possibilities. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@node Command Index -@unnumbered Command Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye diff --git a/doc/misc/bovine.texi b/doc/misc/bovine.texi deleted file mode 100644 index 2ac355f805f..00000000000 --- a/doc/misc/bovine.texi +++ /dev/null @@ -1,475 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/bovine -@set TITLE Bovine parser development -@set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim -@settitle @value{TITLE} -@documentencoding UTF-8 - -@c ************************************************************************* -@c @ Header -@c ************************************************************************* - -@c Merge all indexes into a single index for now. -@c We can always separate them later into two or more as needed. -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex ky cp -@syncodeindex pg cp -@syncodeindex tp cp - -@c @footnotestyle separate -@c @paragraphindent 2 -@c @@smallbook -@c %**end of header - -@copying -Copyright @copyright{} 1999--2004, 2012--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Bovine: (bovine). Semantic bovine parser development. -@end direntry - -@iftex -@finalout -@end iftex - -@c @setchapternewpage odd -@c @setchapternewpage off - -@titlepage -@sp 10 -@title @value{TITLE} -@author by @value{AUTHOR} -@page -@vskip 0pt plus 1 fill -@insertcopying -@end titlepage -@page - -@macro semantic{} -@i{Semantic} -@end macro - -@c ************************************************************************* -@c @ Document -@c ************************************************************************* -@contents - -@node top -@top @value{TITLE} - -The @dfn{bovine} parser is the original @semantic{} parser, and is an -implementation of an @acronym{LL} parser. It is good for simple -languages. It has many conveniences making grammar writing easy. The -conveniences make it less powerful than a Bison-like @acronym{LALR} -parser. For more information, @inforef{Top, The Wisent Parser Manual, -wisent}. - -Bovine @acronym{LL} grammars are stored in files with a @file{.by} -extension. When compiled, the contents is converted into a file of -the form @file{NAME-by.el}. This, in turn is byte compiled. -@inforef{top, Grammar Framework Manual, grammar-fw}. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Starting Rules:: The starting rules for the grammar. -* Bovine Grammar Rules:: Rules used to parse a language. -* Optional Lambda Expression:: Actions to take when a rule is matched. -* Bovine Examples:: Simple Samples. -* GNU Free Documentation License:: The license for this documentation. -@c * Index:: -@end menu - -@node Starting Rules -@chapter Starting Rules - -In Bison, one and only one nonterminal is designated as the ``start'' -symbol. In @semantic{}, one or more nonterminals can be designated as -the ``start'' symbol. They are declared following the @code{%start} -keyword separated by spaces. @inforef{start Decl, ,grammar-fw}. - -If no @code{%start} keyword is used in a grammar, then the very first -is used. Internally the first start nonterminal is targeted by the -reserved symbol @code{bovine-toplevel}, so it can be found by the -parser harness. - -To find locally defined variables, the local context handler needs to -parse the body of functional code. The @code{scopestart} declaration -specifies the name of a nonterminal used as the goal to parse a local -context, @inforef{scopestart Decl, ,grammar-fw}. Internally the -scopestart nonterminal is targeted by the reserved symbol -@code{bovine-inner-scope}, so it can be found by the parser harness. - -@node Bovine Grammar Rules -@chapter Bovine Grammar Rules - -The rules are what allow the compiler to create tags from a language -file. Once the setup is done in the prologue, you can start writing -rules. @inforef{Grammar Rules, ,grammar-fw}. - -@example -@var{result} : @var{components1} @var{optional-semantic-action1}) - | @var{components2} @var{optional-semantic-action2} - ; -@end example - -@var{result} is a nonterminal, that is a symbol synthesized in your grammar. -@var{components} is a list of elements that are to be matched if @var{result} -is to be made. @var{optional-semantic-action} is an optional sequence -of simplified Emacs Lisp expressions for concocting the parse tree. - -In bison, each time an element of @var{components} is found, it is -@dfn{shifted} onto the parser stack. (The stack of matched elements.) -When all @var{components}' elements have been matched, it is -@dfn{reduced} to @var{result}. @xref{Algorithm,,, bison, The GNU Bison Manual}. - -A particular @var{result} written into your grammar becomes -the parser's goal. It is designated by a @code{%start} statement -(@pxref{Starting Rules}). The value returned by the associated -@var{optional-semantic-action} is the parser's result. It should be -a tree of @semantic{} @dfn{tags}, @inforef{Semantic Tags, , -semantic-appdev}. - -@var{components} is made up of symbols. A symbol such as @code{FOO} -means that a syntactic token of class @code{FOO} must be matched. - -@menu -* How Lexical Tokens Match:: -* Grammar-to-Lisp Details:: -* Order of components in rules:: -@end menu - -@node How Lexical Tokens Match -@section How Lexical Tokens Match - -A lexical rule must be used to define how to match a lexical token. - -For instance: - -@example -%keyword FOO "foo" -@end example - -Means that @code{FOO} is a reserved language keyword, matched as such -by looking up into a keyword table, @inforef{keyword Decl, -,grammar-fw}. This is because @code{"foo"} will be converted to -@code{FOO} in the lexical analysis stage. Thus the symbol @code{FOO} -won't be available any other way. - -If we specify our token in this way: - -@example -%token FOO "foo" -@end example - -then @code{FOO} will match the string @code{"foo"} explicitly, but it -won't do so at the lexical level, allowing use of the text -@code{"foo"} in other forms of regular expressions. - -In that case, @code{FOO} is a @code{symbol}-type token. To match, a -@code{symbol} must first be encountered, and then it must -@code{string-match "foo"}. - -@table @strong -@item Caution: -Be especially careful to remember that @code{"foo"}, and more -generally the %token's match-value string, is a regular expression! -@end table - -Non symbol tokens are also allowed. For example: - -@example -%token PERIOD "[.]" - -filename : symbol PERIOD symbol - ; -@end example - -@code{PERIOD} is a @code{punctuation}-type token that will explicitly -match one period when used in the above rule. - -@table @strong -@item Please Note: -@code{symbol}, @code{punctuation}, etc., are predefined lexical token -types, based on the @dfn{syntax class}-character associations -currently in effect. -@end table - -@node Grammar-to-Lisp Details -@section Grammar-to-Lisp Details - -For the bovinator, lexical token matching patterns are @emph{inlined}. -When the grammar-to-lisp converter encounters a lexical token -declaration of the form: - -@example -%token <@var{type}> @var{token-name} @var{match-value} -@end example - -It substitutes every occurrences of @var{token-name} in rules, by its -expanded form: - -@example -@var{type} @var{match-value} -@end example - -For example: - -@example -%token MOOSE "moose" - -find_a_moose: MOOSE - ; -@end example - -Will generate this pseudo equivalent-rule: - -@example -find_a_moose: symbol "moose" ;; invalid syntax! - ; -@end example - -Thus, from the bovinator point of view, the @var{components} part of a -rule is made up of symbols and strings. A string in the mix means -that the previous symbol must have the additional constraint of -exactly matching it, as described in @ref{How Lexical Tokens Match}. - -@table @strong -@item Please Note: -For the bovinator, this task was mixed into the language definition to -simplify implementation, though Bison's technique is more efficient. -@end table - -@node Order of components in rules -@section Order of components in rules - -If a rule has multiple components, order is important, for example - -@example -headerfile : symbol PERIOD symbol - | symbol - ; -@end example - -would match @samp{foo.h} or the @acronym{C++} header @samp{foo}. -The bovine parser will first attempt to match the long form, and then -the short form. If they were in reverse order, then the long form -would never be tested. - -@c @xref{Default syntactic tokens}. - -@node Optional Lambda Expression -@chapter Optional Lambda Expressions - -The @acronym{OLE} (@dfn{Optional Lambda Expression}) is converted into -a bovine lambda. This lambda has special short-cuts to simplify -reading the semantic action definition. An @acronym{OLE} like this: - -@example -( $1 ) -@end example - -results in a lambda return which consists entirely of the string -or object found by matching the first (zeroth) element of match. -An @acronym{OLE} like this: - -@example -( ,(foo $1) ) -@end example - -executes @code{foo} on the first argument, and then splices its return -into the return list whereas: - -@example -( (foo $1) ) -@end example - -executes @code{foo}, and that is placed in the return list. - -Here are other things that can appear inline: - -@table @code -@item $1 -The first object matched. - -@item ,$1 -The first object spliced into the list (assuming it is a list from a -non-terminal). - -@item '$1 -The first object matched, placed in a list. I.e., @code{( $1 )}. - -@item foo -The symbol @code{foo} (exactly as displayed). - -@item (foo) -A function call to foo which is stuck into the return list. - -@item ,(foo) -A function call to foo which is spliced into the return list. - -@item '(foo) -A function call to foo which is stuck into the return list in a list. - -@item (EXPAND @var{$1} @var{nonterminal} @var{depth}) -A list starting with @code{EXPAND} performs a recursive parse on the -token passed to it (represented by @samp{$1} above.) The -@dfn{semantic list} is a common token to expand, as there are often -interesting things in the list. The @var{nonterminal} is a symbol in -your table which the bovinator will start with when parsing. -@var{nonterminal}'s definition is the same as any other nonterminal. -@var{depth} should be at least @samp{1} when descending into a -semantic list. - -@item (EXPANDFULL @var{$1} @var{nonterminal} @var{depth}) -Is like @code{EXPAND}, except that the parser will iterate over -@var{nonterminal} until there are no more matches. (The same way the -parser iterates over the starting rule (@pxref{Starting Rules}). This -lets you have much simpler rules in this specific case, and also lets -you have positional information in the returned tokens, and error -skipping. - -@item (ASSOC @var{symbol1} @var{value1} @var{symbol2} @var{value2} @dots{}) -This is used for creating an association list. Each @var{symbol} is -included in the list if the associated @var{value} is non-@code{nil}. -While the items are all listed explicitly, the created structure is an -association list of the form: - -@example -((@var{symbol1} . @var{value1}) (@var{symbol2} . @var{value2}) @dots{}) -@end example - -@item (TAG @var{name} @var{class} [@var{attributes}]) -This creates one tag in the current buffer. - -@table @var -@item name -Is a string that represents the tag in the language. - -@item class -Is the kind of tag being create, such as @code{function}, or -@code{variable}, though any symbol will work. - -@item attributes -Is an optional set of labeled values such as @code{:constant-flag t :parent -"parenttype"}. -@end table - -@item (TAG-VARIABLE @var{name} @var{type} @var{default-value} [@var{attributes}]) -@itemx (TAG-FUNCTION @var{name} @var{type} @var{arg-list} [@var{attributes}]) -@itemx (TAG-TYPE @var{name} @var{type} @var{members} @var{parents} [@var{attributes}]) -@itemx (TAG-INCLUDE @var{name} @var{system-flag} [@var{attributes}]) -@itemx (TAG-PACKAGE @var{name} @var{detail} [@var{attributes}]) -@itemx (TAG-CODE @var{name} @var{detail} [@var{attributes}]) -Create a tag with @var{name} of respectively the class -@code{variable}, @code{function}, @code{type}, @code{include}, -@code{package}, and @code{code}. -See @inforef{Creating Tags, , semantic-appdev} for the lisp -functions these translate into. -@end table - -If the symbol @code{%quotemode backquote} is specified, then use -@code{,@@} to splice a list in, and @code{,} to evaluate the expression. -This lets you send @code{$1} as a symbol into a list instead of having -it expanded inline. - -@node Bovine Examples -@chapter Examples - -The rule: - -@example -any-symbol: symbol - ; -@end example - -is equivalent to - -@example -any-symbol: symbol - ( $1 ) - ; -@end example - -which, if it matched the string @samp{"A"}, would return - -@example -( "A" ) -@end example - -If this rule were used like this: - -@example -%token EQUAL "=" -@dots{} -assign: any-symbol EQUAL any-symbol - ( $1 $3 ) - ; -@end example - -it would match @samp{"A=B"}, and return - -@example -( ("A") ("B") ) -@end example - -The letters @samp{A} and @samp{B} come back in lists because -@samp{any-symbol} is a nonterminal, not an actual lexical element. - -To get a better result with nonterminals, use @asis{,} to splice lists -in like this: - -@example -%token EQUAL "=" -@dots{} -assign: any-symbol EQUAL any-symbol - ( ,$1 ,$3 ) - ; -@end example - -which would return - -@example -( "A" "B" ) -@end example - -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@include doclicense.texi - -@c There is nothing to index at the moment. -@ignore -@node Index -@unnumbered Index -@printindex cp -@end ignore - -@iftex -@contents -@summarycontents -@end iftex - -@bye - -@c Following comments are for the benefit of ispell. - -@c LocalWords: bovinator inlined diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi deleted file mode 100644 index 56aa2d04a1a..00000000000 --- a/doc/misc/calc.texi +++ /dev/null @@ -1,37099 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header (This is for running Texinfo on a region.) -@c smallbook -@setfilename ../../info/calc -@c [title] -@settitle GNU Emacs Calc Manual -@documentencoding UTF-8 -@setchapternewpage odd -@comment %**end of header (This is for running Texinfo on a region.) - -@include emacsver.texi - -@c The following macros are used for conditional output for single lines. -@c @texline foo -@c `foo' will appear only in TeX output -@c @infoline foo -@c `foo' will appear only in non-TeX output - -@c @expr{expr} will typeset an expression; -@c $x$ in TeX, @samp{x} otherwise. - -@iftex -@macro texline -@end macro -@alias infoline=comment -@alias expr=math -@alias tfn=code -@alias mathit=expr -@alias summarykey=key -@macro cpi{} -@math{@pi{}} -@end macro -@macro cpiover{den} -@math{@pi/\den\} -@end macro -@end iftex - -@ifnottex -@alias texline=comment -@macro infoline{stuff} -\stuff\ -@end macro -@alias expr=samp -@alias tfn=t -@alias mathit=i -@macro summarykey{ky} -\ky\ -@end macro -@macro cpi{} -@expr{pi} -@end macro -@macro cpiover{den} -@expr{pi/\den\} -@end macro -@end ifnottex - - -@tex -% Suggested by Karl Berry -\gdef\!{\mskip-\thinmuskip} -@end tex - -@c Fix some other things specifically for this manual. -@iftex -@finalout -@mathcode`@:=`@: @c Make Calc fractions come out right in math mode -@tex -\gdef\coloneq{\mathrel{\mathord:\mathord=}} - -\gdef\beforedisplay{\vskip-10pt} -\gdef\afterdisplay{\vskip-5pt} -\gdef\beforedisplayh{\vskip-25pt} -\gdef\afterdisplayh{\vskip-10pt} -@end tex -@newdimen@kyvpos @kyvpos=0pt -@newdimen@kyhpos @kyhpos=0pt -@newcount@calcclubpenalty @calcclubpenalty=1000 -@ignore -@newcount@calcpageno -@newtoks@calcoldeverypar @calcoldeverypar=@everypar -@everypar={@calceverypar@the@calcoldeverypar} -@ifx@ninett@undefinedzzz@font@ninett=cmtt9@fi -@catcode`@\=0 \catcode`\@=11 -\r@ggedbottomtrue -\catcode`\@=0 @catcode`@\=@active -@end ignore -@end iftex - -@copying -@ifinfo -This file documents Calc, the GNU Emacs calculator. -@end ifinfo -@ifnotinfo -This file documents Calc, the GNU Emacs calculator, included with -GNU Emacs @value{EMACSVER}. -@end ifnotinfo - -Copyright @copyright{} 1990--1991, 2001--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being just ``GNU GENERAL PUBLIC LICENSE'', with the -Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the section -entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Calc: (calc). Advanced desk calculator and mathematical tool. -@end direntry - -@titlepage -@sp 6 -@center @titlefont{Calc Manual} -@sp 4 -@center GNU Emacs Calc -@c [volume] -@sp 5 -@center Dave Gillespie -@center daveg@@synaptics.com -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - - -@summarycontents - -@c [end] - -@contents - -@c [begin] -@ifnottex -@node Top, Getting Started, (dir), (dir) -@top The GNU Emacs Calculator - -@noindent -@dfn{Calc} is an advanced desk calculator and mathematical tool -written by Dave Gillespie that runs as part of the GNU Emacs environment. - -This manual, also written (mostly) by Dave Gillespie, is divided into -three major parts: ``Getting Started,'' the ``Calc Tutorial,'' and the -``Calc Reference.'' The Tutorial introduces all the major aspects of -Calculator use in an easy, hands-on way. The remainder of the manual is -a complete reference to the features of the Calculator. -@end ifnottex - -@ifinfo -For help in the Emacs Info system (which you are using to read this -file), type @kbd{?}. (You can also type @kbd{h} to run through a -longer Info tutorial.) -@end ifinfo - -@insertcopying - -@menu -* Getting Started:: General description and overview. -@ifinfo -* Interactive Tutorial:: -@end ifinfo -* Tutorial:: A step-by-step introduction for beginners. - -* Introduction:: Introduction to the Calc reference manual. -* Data Types:: Types of objects manipulated by Calc. -* Stack and Trail:: Manipulating the stack and trail buffers. -* Mode Settings:: Adjusting display format and other modes. -* Arithmetic:: Basic arithmetic functions. -* Scientific Functions:: Transcendentals and other scientific functions. -* Matrix Functions:: Operations on vectors and matrices. -* Algebra:: Manipulating expressions algebraically. -* Units:: Operations on numbers with units. -* Store and Recall:: Storing and recalling variables. -* Graphics:: Commands for making graphs of data. -* Kill and Yank:: Moving data into and out of Calc. -* Keypad Mode:: Operating Calc from a keypad. -* Embedded Mode:: Working with formulas embedded in a file. -* Programming:: Calc as a programmable calculator. - -* Copying:: How you can copy and share Calc. -* GNU Free Documentation License:: The license for this documentation. -* Customizing Calc:: Customizing Calc. -* Reporting Bugs:: How to report bugs and make suggestions. - -* Summary:: Summary of Calc commands and functions. - -* Key Index:: The standard Calc key sequences. -* Command Index:: The interactive Calc commands. -* Function Index:: Functions (in algebraic formulas). -* Concept Index:: General concepts. -* Variable Index:: Variables used by Calc (both user and internal). -* Lisp Function Index:: Internal Lisp math functions. -@end menu - -@ifinfo -@node Getting Started, Interactive Tutorial, Top, Top -@end ifinfo -@ifnotinfo -@node Getting Started, Tutorial, Top, Top -@end ifnotinfo -@chapter Getting Started -@noindent -This chapter provides a general overview of Calc, the GNU Emacs -Calculator: What it is, how to start it and how to exit from it, -and what are the various ways that it can be used. - -@menu -* What is Calc:: -* About This Manual:: -* Notations Used in This Manual:: -* Demonstration of Calc:: -* Using Calc:: -* History and Acknowledgments:: -@end menu - -@node What is Calc, About This Manual, Getting Started, Getting Started -@section What is Calc? - -@noindent -@dfn{Calc} is an advanced calculator and mathematical tool that runs as -part of the GNU Emacs environment. Very roughly based on the HP-28/48 -series of calculators, its many features include: - -@itemize @bullet -@item -Choice of algebraic or RPN (stack-based) entry of calculations. - -@item -Arbitrary precision integers and floating-point numbers. - -@item -Arithmetic on rational numbers, complex numbers (rectangular and polar), -error forms with standard deviations, open and closed intervals, vectors -and matrices, dates and times, infinities, sets, quantities with units, -and algebraic formulas. - -@item -Mathematical operations such as logarithms and trigonometric functions. - -@item -Programmer's features (bitwise operations, non-decimal numbers). - -@item -Financial functions such as future value and internal rate of return. - -@item -Number theoretical features such as prime factorization and arithmetic -modulo @var{m} for any @var{m}. - -@item -Algebraic manipulation features, including symbolic calculus. - -@item -Moving data to and from regular editing buffers. - -@item -Embedded mode for manipulating Calc formulas and data directly -inside any editing buffer. - -@item -Graphics using GNUPLOT, a versatile (and free) plotting program. - -@item -Easy programming using keyboard macros, algebraic formulas, -algebraic rewrite rules, or extended Emacs Lisp. -@end itemize - -Calc tries to include a little something for everyone; as a result it is -large and might be intimidating to the first-time user. If you plan to -use Calc only as a traditional desk calculator, all you really need to -read is the ``Getting Started'' chapter of this manual and possibly the -first few sections of the tutorial. As you become more comfortable with -the program you can learn its additional features. Calc does not -have the scope and depth of a fully-functional symbolic math package, -but Calc has the advantages of convenience, portability, and freedom. - -@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started -@section About This Manual - -@noindent -This document serves as a complete description of the GNU Emacs -Calculator. It works both as an introduction for novices and as -a reference for experienced users. While it helps to have some -experience with GNU Emacs in order to get the most out of Calc, -this manual ought to be readable even if you don't know or use Emacs -regularly. - -This manual is divided into three major parts: the ``Getting -Started'' chapter you are reading now, the Calc tutorial, and the Calc -reference manual. -@c [when-split] -@c This manual has been printed in two volumes, the @dfn{Tutorial} and the -@c @dfn{Reference}. Both volumes include a copy of the ``Getting Started'' -@c chapter. - -If you are in a hurry to use Calc, there is a brief ``demonstration'' -below which illustrates the major features of Calc in just a couple of -pages. If you don't have time to go through the full tutorial, this -will show you everything you need to know to begin. -@xref{Demonstration of Calc}. - -The tutorial chapter walks you through the various parts of Calc -with lots of hands-on examples and explanations. If you are new -to Calc and you have some time, try going through at least the -beginning of the tutorial. The tutorial includes about 70 exercises -with answers. These exercises give you some guided practice with -Calc, as well as pointing out some interesting and unusual ways -to use its features. - -The reference section discusses Calc in complete depth. You can read -the reference from start to finish if you want to learn every aspect -of Calc. Or, you can look in the table of contents or the Concept -Index to find the parts of the manual that discuss the things you -need to know. - -@c @cindex Marginal notes -Every Calc keyboard command is listed in the Calc Summary, and also -in the Key Index. Algebraic functions, @kbd{M-x} commands, and -variables also have their own indices. -@c @texline Each -@c @infoline In the printed manual, each -@c paragraph that is referenced in the Key or Function Index is marked -@c in the margin with its index entry. - -@c [fix-ref Help Commands] -You can access this manual on-line at any time within Calc by pressing -the @kbd{h i} key sequence. Outside of the Calc window, you can press -@kbd{C-x * i} to read the manual on-line. From within Calc the command -@kbd{h t} will jump directly to the Tutorial; from outside of Calc the -command @kbd{C-x * t} will jump to the Tutorial and start Calc if -necessary. Pressing @kbd{h s} or @kbd{C-x * s} will take you directly -to the Calc Summary. Within Calc, you can also go to the part of the -manual describing any Calc key, function, or variable using -@w{@kbd{h k}}, @kbd{h f}, or @kbd{h v}, respectively. @xref{Help Commands}. - -@ifnottex -The Calc manual can be printed, but because the manual is so large, you -should only make a printed copy if you really need it. To print the -manual, you will need the @TeX{} typesetting program (this is a free -program by Donald Knuth at Stanford University) as well as the -@file{texindex} program and @file{texinfo.tex} file, both of which can -be obtained from the FSF as part of the @code{texinfo} package. -To print the Calc manual in one huge tome, you will need the -source code to this manual, @file{calc.texi}, available as part of the -Emacs source. Once you have this file, type @kbd{texi2dvi calc.texi}. -Alternatively, change to the @file{man} subdirectory of the Emacs -source distribution, and type @kbd{make calc.dvi}. (Don't worry if you -get some ``overfull box'' warnings while @TeX{} runs.) -The result will be a device-independent output file called -@file{calc.dvi}, which you must print in whatever way is right -for your system. On many systems, the command is - -@example -lpr -d calc.dvi -@end example - -@noindent -or - -@example -dvips calc.dvi -@end example -@end ifnottex -@c Printed copies of this manual are also available from the Free Software -@c Foundation. - -@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started -@section Notations Used in This Manual - -@noindent -This section describes the various notations that are used -throughout the Calc manual. - -In keystroke sequences, uppercase letters mean you must hold down -the shift key while typing the letter. Keys pressed with Control -held down are shown as @kbd{C-x}. Keys pressed with Meta held down -are shown as @kbd{M-x}. Other notations are @key{RET} for the -Return key, @key{SPC} for the space bar, @key{TAB} for the Tab key, -@key{DEL} for the Delete key, and @key{LFD} for the Line-Feed key. -The @key{DEL} key is called Backspace on some keyboards, it is -whatever key you would use to correct a simple typing error when -regularly using Emacs. - -(If you don't have the @key{LFD} or @key{TAB} keys on your keyboard, -the @kbd{C-j} and @kbd{C-i} keys are equivalent to them, respectively. -If you don't have a Meta key, look for Alt or Extend Char. You can -also press @key{ESC} or @kbd{C-[} first to get the same effect, so -that @kbd{M-x}, @kbd{@key{ESC} x}, and @kbd{C-[ x} are all equivalent.) - -Sometimes the @key{RET} key is not shown when it is ``obvious'' -that you must press @key{RET} to proceed. For example, the @key{RET} -is usually omitted in key sequences like @kbd{M-x calc-keypad @key{RET}}. - -Commands are generally shown like this: @kbd{p} (@code{calc-precision}) -or @kbd{C-x * k} (@code{calc-keypad}). This means that the command is -normally used by pressing the @kbd{p} key or @kbd{C-x * k} key sequence, -but it also has the full-name equivalent shown, e.g., @kbd{M-x calc-precision}. - -Commands that correspond to functions in algebraic notation -are written: @kbd{C} (@code{calc-cos}) [@code{cos}]. This means -the @kbd{C} key is equivalent to @kbd{M-x calc-cos}, and that -the corresponding function in an algebraic-style formula would -be @samp{cos(@var{x})}. - -A few commands don't have key equivalents: @code{calc-sincos} -[@code{sincos}]. - -@node Demonstration of Calc, Using Calc, Notations Used in This Manual, Getting Started -@section A Demonstration of Calc - -@noindent -@cindex Demonstration of Calc -This section will show some typical small problems being solved with -Calc. The focus is more on demonstration than explanation, but -everything you see here will be covered more thoroughly in the -Tutorial. - -To begin, start Emacs if necessary (usually the command @code{emacs} -does this), and type @kbd{C-x * c} to start the -Calculator. (You can also use @kbd{M-x calc} if this doesn't work. -@xref{Starting Calc}, for various ways of starting the Calculator.) - -Be sure to type all the sample input exactly, especially noting the -difference between lower-case and upper-case letters. Remember, -@key{RET}, @key{TAB}, @key{DEL}, and @key{SPC} are the Return, Tab, -Delete, and Space keys. - -@strong{RPN calculation.} In RPN, you type the input number(s) first, -then the command to operate on the numbers. - -@noindent -Type @kbd{2 @key{RET} 3 + Q} to compute -@texline @math{\sqrt{2+3} = 2.2360679775}. -@infoline the square root of 2+3, which is 2.2360679775. - -@noindent -Type @kbd{P 2 ^} to compute -@texline @math{\pi^2 = 9.86960440109}. -@infoline the value of `pi' squared, 9.86960440109. - -@noindent -Type @key{TAB} to exchange the order of these two results. - -@noindent -Type @kbd{- I H S} to subtract these results and compute the Inverse -Hyperbolic sine of the difference, 2.72996136574. - -@noindent -Type @key{DEL} to erase this result. - -@strong{Algebraic calculation.} You can also enter calculations using -conventional ``algebraic'' notation. To enter an algebraic formula, -use the apostrophe key. - -@noindent -Type @kbd{' sqrt(2+3) @key{RET}} to compute -@texline @math{\sqrt{2+3}}. -@infoline the square root of 2+3. - -@noindent -Type @kbd{' pi^2 @key{RET}} to enter -@texline @math{\pi^2}. -@infoline `pi' squared. -To evaluate this symbolic formula as a number, type @kbd{=}. - -@noindent -Type @kbd{' arcsinh($ - $$) @key{RET}} to subtract the second-most-recent -result from the most-recent and compute the Inverse Hyperbolic sine. - -@strong{Keypad mode.} If you are using the X window system, press -@w{@kbd{C-x * k}} to get Keypad mode. (If you don't use X, skip to -the next section.) - -@noindent -Click on the @key{2}, @key{ENTER}, @key{3}, @key{+}, and @key{SQRT} -``buttons'' using your left mouse button. - -@noindent -Click on @key{PI}, @key{2}, and @tfn{y^x}. - -@noindent -Click on @key{INV}, then @key{ENTER} to swap the two results. - -@noindent -Click on @key{-}, @key{INV}, @key{HYP}, and @key{SIN}. - -@noindent -Click on @key{<-} to erase the result, then click @key{OFF} to turn -the Keypad Calculator off. - -@strong{Grabbing data.} Type @kbd{C-x * x} if necessary to exit Calc. -Now select the following numbers as an Emacs region: ``Mark'' the -front of the list by typing @kbd{C-@key{SPC}} or @kbd{C-@@} there, -then move to the other end of the list. (Either get this list from -the on-line copy of this manual, accessed by @w{@kbd{C-x * i}}, or just -type these numbers into a scratch file.) Now type @kbd{C-x * g} to -``grab'' these numbers into Calc. - -@example -@group -1.23 1.97 -1.6 2 -1.19 1.08 -@end group -@end example - -@noindent -The result @samp{[1.23, 1.97, 1.6, 2, 1.19, 1.08]} is a Calc ``vector.'' -Type @w{@kbd{V R +}} to compute the sum of these numbers. - -@noindent -Type @kbd{U} to Undo this command, then type @kbd{V R *} to compute -the product of the numbers. - -@noindent -You can also grab data as a rectangular matrix. Place the cursor on -the upper-leftmost @samp{1} and set the mark, then move to just after -the lower-right @samp{8} and press @kbd{C-x * r}. - -@noindent -Type @kbd{v t} to transpose this -@texline @math{3\times2} -@infoline 3x2 -matrix into a -@texline @math{2\times3} -@infoline 2x3 -matrix. Type @w{@kbd{v u}} to unpack the rows into two separate -vectors. Now type @w{@kbd{V R + @key{TAB} V R +}} to compute the sums -of the two original columns. (There is also a special -grab-and-sum-columns command, @kbd{C-x * :}.) - -@strong{Units conversion.} Units are entered algebraically. -Type @w{@kbd{' 43 mi/hr @key{RET}}} to enter the quantity 43 miles-per-hour. -Type @w{@kbd{u c km/hr @key{RET}}}. Type @w{@kbd{u c m/s @key{RET}}}. - -@strong{Date arithmetic.} Type @kbd{t N} to get the current date and -time. Type @kbd{90 +} to find the date 90 days from now. Type -@kbd{' <25 dec 87> @key{RET}} to enter a date, then @kbd{- 7 /} to see how -many weeks have passed since then. - -@strong{Algebra.} Algebraic entries can also include formulas -or equations involving variables. Type @kbd{@w{' [x + y} = a, x y = 1] @key{RET}} -to enter a pair of equations involving three variables. -(Note the leading apostrophe in this example; also, note that the space -in @samp{x y} is required.) Type @w{@kbd{a S x,y @key{RET}}} to solve -these equations for the variables @expr{x} and @expr{y}. - -@noindent -Type @kbd{d B} to view the solutions in more readable notation. -Type @w{@kbd{d C}} to view them in C language notation, @kbd{d T} -to view them in the notation for the @TeX{} typesetting system, -and @kbd{d L} to view them in the notation for the @LaTeX{} typesetting -system. Type @kbd{d N} to return to normal notation. - -@noindent -Type @kbd{7.5}, then @kbd{s l a @key{RET}} to let @expr{a = 7.5} in these formulas. -(That's the letter @kbd{l}, not the numeral @kbd{1}.) - -@ifnotinfo -@strong{Help functions.} You can read about any command in the on-line -manual. Type @kbd{C-x * c} to return to Calc after each of these -commands: @kbd{h k t N} to read about the @kbd{t N} command, -@kbd{h f sqrt @key{RET}} to read about the @code{sqrt} function, and -@kbd{h s} to read the Calc summary. -@end ifnotinfo -@ifinfo -@strong{Help functions.} You can read about any command in the on-line -manual. Remember to type the letter @kbd{l}, then @kbd{C-x * c}, to -return here after each of these commands: @w{@kbd{h k t N}} to read -about the @w{@kbd{t N}} command, @kbd{h f sqrt @key{RET}} to read about the -@code{sqrt} function, and @kbd{h s} to read the Calc summary. -@end ifinfo - -Press @key{DEL} repeatedly to remove any leftover results from the stack. -To exit from Calc, press @kbd{q} or @kbd{C-x * c} again. - -@node Using Calc, History and Acknowledgments, Demonstration of Calc, Getting Started -@section Using Calc - -@noindent -Calc has several user interfaces that are specialized for -different kinds of tasks. As well as Calc's standard interface, -there are Quick mode, Keypad mode, and Embedded mode. - -@menu -* Starting Calc:: -* The Standard Interface:: -* Quick Mode Overview:: -* Keypad Mode Overview:: -* Standalone Operation:: -* Embedded Mode Overview:: -* Other C-x * Commands:: -@end menu - -@node Starting Calc, The Standard Interface, Using Calc, Using Calc -@subsection Starting Calc - -@noindent -On most systems, you can type @kbd{C-x *} to start the Calculator. -The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch}, -which can be rebound if convenient (@pxref{Customizing Calc}). - -When you press @kbd{C-x *}, Emacs waits for you to press a second key to -complete the command. In this case, you will follow @kbd{C-x *} with a -letter (upper- or lower-case, it doesn't matter for @kbd{C-x *}) that says -which Calc interface you want to use. - -To get Calc's standard interface, type @kbd{C-x * c}. To get -Keypad mode, type @kbd{C-x * k}. Type @kbd{C-x * ?} to get a brief -list of the available options, and type a second @kbd{?} to get -a complete list. - -To ease typing, @kbd{C-x * *} also works to start Calc. It starts the -same interface (either @kbd{C-x * c} or @w{@kbd{C-x * k}}) that you last -used, selecting the @kbd{C-x * c} interface by default. - -If @kbd{C-x *} doesn't work for you, you can always type explicit -commands like @kbd{M-x calc} (for the standard user interface) or -@w{@kbd{M-x calc-keypad}} (for Keypad mode). First type @kbd{M-x} -(that's Meta with the letter @kbd{x}), then, at the prompt, -type the full command (like @kbd{calc-keypad}) and press Return. - -The same commands (like @kbd{C-x * c} or @kbd{C-x * *}) that start -the Calculator also turn it off if it is already on. - -@node The Standard Interface, Quick Mode Overview, Starting Calc, Using Calc -@subsection The Standard Calc Interface - -@noindent -@cindex Standard user interface -Calc's standard interface acts like a traditional RPN calculator, -operated by the normal Emacs keyboard. When you type @kbd{C-x * c} -to start the Calculator, the Emacs screen splits into two windows -with the file you were editing on top and Calc on the bottom. - -@smallexample -@group - -... ---**-Emacs: myfile (Fundamental)----All---------------------- ---- Emacs Calculator Mode --- |Emacs Calculator Trail -2: 17.3 | 17.3 -1: -5 | 3 - . | 2 - | 4 - | * 8 - | ->-5 - | ---%*-Calc: 12 Deg (Calculator)----All----- --%*- *Calc Trail* -@end group -@end smallexample - -In this figure, the mode-line for @file{myfile} has moved up and the -``Calculator'' window has appeared below it. As you can see, Calc -actually makes two windows side-by-side. The lefthand one is -called the @dfn{stack window} and the righthand one is called the -@dfn{trail window.} The stack holds the numbers involved in the -calculation you are currently performing. The trail holds a complete -record of all calculations you have done. In a desk calculator with -a printer, the trail corresponds to the paper tape that records what -you do. - -In this case, the trail shows that four numbers (17.3, 3, 2, and 4) -were first entered into the Calculator, then the 2 and 4 were -multiplied to get 8, then the 3 and 8 were subtracted to get @mathit{-5}. -(The @samp{>} symbol shows that this was the most recent calculation.) -The net result is the two numbers 17.3 and @mathit{-5} sitting on the stack. - -Most Calculator commands deal explicitly with the stack only, but -there is a set of commands that allow you to search back through -the trail and retrieve any previous result. - -Calc commands use the digits, letters, and punctuation keys. -Shifted (i.e., upper-case) letters are different from lowercase -letters. Some letters are @dfn{prefix} keys that begin two-letter -commands. For example, @kbd{e} means ``enter exponent'' and shifted -@kbd{E} means @expr{e^x}. With the @kbd{d} (``display modes'') prefix -the letter ``e'' takes on very different meanings: @kbd{d e} means -``engineering notation'' and @kbd{d E} means ``@dfn{eqn} language mode.'' - -There is nothing stopping you from switching out of the Calc -window and back into your editing window, say by using the Emacs -@w{@kbd{C-x o}} (@code{other-window}) command. When the cursor is -inside a regular window, Emacs acts just like normal. When the -cursor is in the Calc stack or trail windows, keys are interpreted -as Calc commands. - -When you quit by pressing @kbd{C-x * c} a second time, the Calculator -windows go away but the actual Stack and Trail are not gone, just -hidden. When you press @kbd{C-x * c} once again you will get the -same stack and trail contents you had when you last used the -Calculator. - -The Calculator does not remember its state between Emacs sessions. -Thus if you quit Emacs and start it again, @kbd{C-x * c} will give you -a fresh stack and trail. There is a command (@kbd{m m}) that lets -you save your favorite mode settings between sessions, though. -One of the things it saves is which user interface (standard or -Keypad) you last used; otherwise, a freshly started Emacs will -always treat @kbd{C-x * *} the same as @kbd{C-x * c}. - -The @kbd{q} key is another equivalent way to turn the Calculator off. - -If you type @kbd{C-x * b} first and then @kbd{C-x * c}, you get a -full-screen version of Calc (@code{full-calc}) in which the stack and -trail windows are still side-by-side but are now as tall as the whole -Emacs screen. When you press @kbd{q} or @kbd{C-x * c} again to quit, -the file you were editing before reappears. The @kbd{C-x * b} key -switches back and forth between ``big'' full-screen mode and the -normal partial-screen mode. - -Finally, @kbd{C-x * o} (@code{calc-other-window}) is like @kbd{C-x * c} -except that the Calc window is not selected. The buffer you were -editing before remains selected instead. If you are in a Calc window, -then @kbd{C-x * o} will switch you out of it, being careful not to -switch you to the Calc Trail window. So @kbd{C-x * o} is a handy -way to switch out of Calc momentarily to edit your file; you can then -type @kbd{C-x * c} to switch back into Calc when you are done. - -@node Quick Mode Overview, Keypad Mode Overview, The Standard Interface, Using Calc -@subsection Quick Mode (Overview) - -@noindent -@dfn{Quick mode} is a quick way to use Calc when you don't need the -full complexity of the stack and trail. To use it, type @kbd{C-x * q} -(@code{quick-calc}) in any regular editing buffer. - -Quick mode is very simple: It prompts you to type any formula in -standard algebraic notation (like @samp{4 - 2/3}) and then displays -the result at the bottom of the Emacs screen (@mathit{3.33333333333} -in this case). You are then back in the same editing buffer you -were in before, ready to continue editing or to type @kbd{C-x * q} -again to do another quick calculation. The result of the calculation -will also be in the Emacs ``kill ring'' so that a @kbd{C-y} command -at this point will yank the result into your editing buffer. - -Calc mode settings affect Quick mode, too, though you will have to -go into regular Calc (with @kbd{C-x * c}) to change the mode settings. - -@c [fix-ref Quick Calculator mode] -@xref{Quick Calculator}, for further information. - -@node Keypad Mode Overview, Standalone Operation, Quick Mode Overview, Using Calc -@subsection Keypad Mode (Overview) - -@noindent -@dfn{Keypad mode} is a mouse-based interface to the Calculator. -It is designed for use with terminals that support a mouse. If you -don't have a mouse, you will have to operate Keypad mode with your -arrow keys (which is probably more trouble than it's worth). - -Type @kbd{C-x * k} to turn Keypad mode on or off. Once again you -get two new windows, this time on the righthand side of the screen -instead of at the bottom. The upper window is the familiar Calc -Stack; the lower window is a picture of a typical calculator keypad. - -@tex -\dimen0=\pagetotal% -\advance \dimen0 by 24\baselineskip% -\ifdim \dimen0>\pagegoal \vfill\eject \fi% -\medskip -@end tex -@smallexample -@group -|--- Emacs Calculator Mode --- -|2: 17.3 -|1: -5 -| . -|--%*-Calc: 12 Deg (Calcul -|----+----+--Calc---+----+----1 -|FLR |CEIL|RND |TRNC|CLN2|FLT | -|----+----+----+----+----+----| -| LN |EXP | |ABS |IDIV|MOD | -|----+----+----+----+----+----| -|SIN |COS |TAN |SQRT|y^x |1/x | -|----+----+----+----+----+----| -| ENTER |+/- |EEX |UNDO| <- | -|-----+---+-+--+--+-+---++----| -| INV | 7 | 8 | 9 | / | -|-----+-----+-----+-----+-----| -| HYP | 4 | 5 | 6 | * | -|-----+-----+-----+-----+-----| -|EXEC | 1 | 2 | 3 | - | -|-----+-----+-----+-----+-----| -| OFF | 0 | . | PI | + | -|-----+-----+-----+-----+-----+ -@end group -@end smallexample - -Keypad mode is much easier for beginners to learn, because there -is no need to memorize lots of obscure key sequences. But not all -commands in regular Calc are available on the Keypad. You can -always switch the cursor into the Calc stack window to use -standard Calc commands if you need. Serious Calc users, though, -often find they prefer the standard interface over Keypad mode. - -To operate the Calculator, just click on the ``buttons'' of the -keypad using your left mouse button. To enter the two numbers -shown here you would click @w{@kbd{1 7 .@: 3 ENTER 5 +/- ENTER}}; to -add them together you would then click @kbd{+} (to get 12.3 on -the stack). - -If you click the right mouse button, the top three rows of the -keypad change to show other sets of commands, such as advanced -math functions, vector operations, and operations on binary -numbers. - -Because Keypad mode doesn't use the regular keyboard, Calc leaves -the cursor in your original editing buffer. You can type in -this buffer in the usual way while also clicking on the Calculator -keypad. One advantage of Keypad mode is that you don't need an -explicit command to switch between editing and calculating. - -If you press @kbd{C-x * b} first, you get a full-screen Keypad mode -(@code{full-calc-keypad}) with three windows: The keypad in the lower -left, the stack in the lower right, and the trail on top. - -@c [fix-ref Keypad Mode] -@xref{Keypad Mode}, for further information. - -@node Standalone Operation, Embedded Mode Overview, Keypad Mode Overview, Using Calc -@subsection Standalone Operation - -@noindent -@cindex Standalone Operation -If you are not in Emacs at the moment but you wish to use Calc, -you must start Emacs first. If all you want is to run Calc, you -can give the commands: - -@example -emacs -f full-calc -@end example - -@noindent -or - -@example -emacs -f full-calc-keypad -@end example - -@noindent -which run a full-screen Calculator (as if by @kbd{C-x * b C-x * c}) or -a full-screen X-based Calculator (as if by @kbd{C-x * b C-x * k}). -In standalone operation, quitting the Calculator (by pressing -@kbd{q} or clicking on the keypad @key{EXIT} button) quits Emacs -itself. - -@node Embedded Mode Overview, Other C-x * Commands, Standalone Operation, Using Calc -@subsection Embedded Mode (Overview) - -@noindent -@dfn{Embedded mode} is a way to use Calc directly from inside an -editing buffer. Suppose you have a formula written as part of a -document like this: - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is -@end group -@end smallexample - -@noindent -and you wish to have Calc compute and format the derivative for -you and store this derivative in the buffer automatically. To -do this with Embedded mode, first copy the formula down to where -you want the result to be, leaving a blank line before and after the -formula: - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is - - ln(ln(x)) -@end group -@end smallexample - -Now, move the cursor onto this new formula and press @kbd{C-x * e}. -Calc will read the formula (using the surrounding blank lines to tell -how much text to read), then push this formula (invisibly) onto the Calc -stack. The cursor will stay on the formula in the editing buffer, but -the line with the formula will now appear as it would on the Calc stack -(in this case, it will be left-aligned) and the buffer's mode line will -change to look like the Calc mode line (with mode indicators like -@samp{12 Deg} and so on). Even though you are still in your editing -buffer, the keyboard now acts like the Calc keyboard, and any new result -you get is copied from the stack back into the buffer. To take the -derivative, you would type @kbd{a d x @key{RET}}. - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is - -1 / x ln(x) -@end group -@end smallexample - -(Note that by default, Calc gives division lower precedence than multiplication, -so that @samp{1 / x ln(x)} is equivalent to @samp{1 / (x ln(x))}.) - -To make this look nicer, you might want to press @kbd{d =} to center -the formula, and even @kbd{d B} to use Big display mode. - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is -% [calc-mode: justify: center] -% [calc-mode: language: big] - - 1 - ------- - x ln(x) -@end group -@end smallexample - -Calc has added annotations to the file to help it remember the modes -that were used for this formula. They are formatted like comments -in the @TeX{} typesetting language, just in case you are using @TeX{} or -@LaTeX{}. (In this example @TeX{} is not being used, so you might want -to move these comments up to the top of the file or otherwise put them -out of the way.) - -As an extra flourish, we can add an equation number using a -righthand label: Type @kbd{d @} (1) @key{RET}}. - -@smallexample -@group -% [calc-mode: justify: center] -% [calc-mode: language: big] -% [calc-mode: right-label: " (1)"] - - 1 - ------- (1) - ln(x) x -@end group -@end smallexample - -To leave Embedded mode, type @kbd{C-x * e} again. The mode line -and keyboard will revert to the way they were before. - -The related command @kbd{C-x * w} operates on a single word, which -generally means a single number, inside text. It searches for an -expression which ``looks'' like a number containing the point. -Here's an example of its use (before you try this, remove the Calc -annotations or use a new buffer so that the extra settings in the -annotations don't take effect): - -@smallexample -A slope of one-third corresponds to an angle of 1 degrees. -@end smallexample - -Place the cursor on the @samp{1}, then type @kbd{C-x * w} to enable -Embedded mode on that number. Now type @kbd{3 /} (to get one-third), -and @kbd{I T} (the Inverse Tangent converts a slope into an angle), -then @w{@kbd{C-x * w}} again to exit Embedded mode. - -@smallexample -A slope of one-third corresponds to an angle of 18.4349488229 degrees. -@end smallexample - -@c [fix-ref Embedded Mode] -@xref{Embedded Mode}, for full details. - -@node Other C-x * Commands, , Embedded Mode Overview, Using Calc -@subsection Other @kbd{C-x *} Commands - -@noindent -Two more Calc-related commands are @kbd{C-x * g} and @kbd{C-x * r}, -which ``grab'' data from a selected region of a buffer into the -Calculator. The region is defined in the usual Emacs way, by -a ``mark'' placed at one end of the region, and the Emacs -cursor or ``point'' placed at the other. - -The @kbd{C-x * g} command reads the region in the usual left-to-right, -top-to-bottom order. The result is packaged into a Calc vector -of numbers and placed on the stack. Calc (in its standard -user interface) is then started. Type @kbd{v u} if you want -to unpack this vector into separate numbers on the stack. Also, -@kbd{C-u C-x * g} interprets the region as a single number or -formula. - -The @kbd{C-x * r} command reads a rectangle, with the point and -mark defining opposite corners of the rectangle. The result -is a matrix of numbers on the Calculator stack. - -Complementary to these is @kbd{C-x * y}, which ``yanks'' the -value at the top of the Calc stack back into an editing buffer. -If you type @w{@kbd{C-x * y}} while in such a buffer, the value is -yanked at the current position. If you type @kbd{C-x * y} while -in the Calc buffer, Calc makes an educated guess as to which -editing buffer you want to use. The Calc window does not have -to be visible in order to use this command, as long as there -is something on the Calc stack. - -Here, for reference, is the complete list of @kbd{C-x *} commands. -The shift, control, and meta keys are ignored for the keystroke -following @kbd{C-x *}. - -@noindent -Commands for turning Calc on and off: - -@table @kbd -@item * -Turn Calc on or off, employing the same user interface as last time. - -@item =, +, -, /, \, &, # -Alternatives for @kbd{*}. - -@item C -Turn Calc on or off using its standard bottom-of-the-screen -interface. If Calc is already turned on but the cursor is not -in the Calc window, move the cursor into the window. - -@item O -Same as @kbd{C}, but don't select the new Calc window. If -Calc is already turned on and the cursor is in the Calc window, -move it out of that window. - -@item B -Control whether @kbd{C-x * c} and @kbd{C-x * k} use the full screen. - -@item Q -Use Quick mode for a single short calculation. - -@item K -Turn Calc Keypad mode on or off. - -@item E -Turn Calc Embedded mode on or off at the current formula. - -@item J -Turn Calc Embedded mode on or off, select the interesting part. - -@item W -Turn Calc Embedded mode on or off at the current word (number). - -@item Z -Turn Calc on in a user-defined way, as defined by a @kbd{Z I} command. - -@item X -Quit Calc; turn off standard, Keypad, or Embedded mode if on. -(This is like @kbd{q} or @key{OFF} inside of Calc.) -@end table -@iftex -@sp 2 -@end iftex - -@noindent -Commands for moving data into and out of the Calculator: - -@table @kbd -@item G -Grab the region into the Calculator as a vector. - -@item R -Grab the rectangular region into the Calculator as a matrix. - -@item : -Grab the rectangular region and compute the sums of its columns. - -@item _ -Grab the rectangular region and compute the sums of its rows. - -@item Y -Yank a value from the Calculator into the current editing buffer. -@end table -@iftex -@sp 2 -@end iftex - -@noindent -Commands for use with Embedded mode: - -@table @kbd -@item A -``Activate'' the current buffer. Locate all formulas that -contain @samp{:=} or @samp{=>} symbols and record their locations -so that they can be updated automatically as variables are changed. - -@item D -Duplicate the current formula immediately below and select -the duplicate. - -@item F -Insert a new formula at the current point. - -@item N -Move the cursor to the next active formula in the buffer. - -@item P -Move the cursor to the previous active formula in the buffer. - -@item U -Update (i.e., as if by the @kbd{=} key) the formula at the current point. - -@item ` -Edit (as if by @code{calc-edit}) the formula at the current point. -@end table -@iftex -@sp 2 -@end iftex - -@noindent -Miscellaneous commands: - -@table @kbd -@item I -Run the Emacs Info system to read the Calc manual. -(This is the same as @kbd{h i} inside of Calc.) - -@item T -Run the Emacs Info system to read the Calc Tutorial. - -@item S -Run the Emacs Info system to read the Calc Summary. - -@item L -Load Calc entirely into memory. (Normally the various parts -are loaded only as they are needed.) - -@item M -Read a region of written keystroke names (like @kbd{C-n a b c @key{RET}}) -and record them as the current keyboard macro. - -@item 0 -(This is the ``zero'' digit key.) Reset the Calculator to -its initial state: Empty stack, and initial mode settings. -@end table - -@node History and Acknowledgments, , Using Calc, Getting Started -@section History and Acknowledgments - -@noindent -Calc was originally started as a two-week project to occupy a lull -in the author's schedule. Basically, a friend asked if I remembered -the value of -@texline @math{2^{32}}. -@infoline @expr{2^32}. -I didn't offhand, but I said, ``that's easy, just call up an -@code{xcalc}.'' @code{Xcalc} duly reported that the answer to our -question was @samp{4.294967e+09}---with no way to see the full ten -digits even though we knew they were there in the program's memory! I -was so annoyed, I vowed to write a calculator of my own, once and for -all. - -I chose Emacs Lisp, a) because I had always been curious about it -and b) because, being only a text editor extension language after -all, Emacs Lisp would surely reach its limits long before the project -got too far out of hand. - -To make a long story short, Emacs Lisp turned out to be a distressingly -solid implementation of Lisp, and the humble task of calculating -turned out to be more open-ended than one might have expected. - -Emacs Lisp didn't have built-in floating point math (now it does), so -this had to be simulated in software. In fact, Emacs integers would -only comfortably fit six decimal digits or so (at the time)---not -enough for a decent calculator. So I had to write my own -high-precision integer code as well, and once I had this I figured -that arbitrary-size integers were just as easy as large integers. -Arbitrary floating-point precision was the logical next step. Also, -since the large integer arithmetic was there anyway it seemed only -fair to give the user direct access to it, which in turn made it -practical to support fractions as well as floats. All these features -inspired me to look around for other data types that might be worth -having. - -Around this time, my friend Rick Koshi showed me his nifty new HP-28 -calculator. It allowed the user to manipulate formulas as well as -numerical quantities, and it could also operate on matrices. I -decided that these would be good for Calc to have, too. And once -things had gone this far, I figured I might as well take a look at -serious algebra systems for further ideas. Since these systems did -far more than I could ever hope to implement, I decided to focus on -rewrite rules and other programming features so that users could -implement what they needed for themselves. - -Rick complained that matrices were hard to read, so I put in code to -format them in a 2D style. Once these routines were in place, Big mode -was obligatory. Gee, what other language modes would be useful? - -Scott Hemphill and Allen Knutson, two friends with a strong mathematical -bent, contributed ideas and algorithms for a number of Calc features -including modulo forms, primality testing, and float-to-fraction conversion. - -Units were added at the eager insistence of Mass Sivilotti. Later, -Ulrich Mueller at CERN and Przemek Klosowski at NIST provided invaluable -expert assistance with the units table. As far as I can remember, the -idea of using algebraic formulas and variables to represent units dates -back to an ancient article in Byte magazine about muMath, an early -algebra system for microcomputers. - -Many people have contributed to Calc by reporting bugs and suggesting -features, large and small. A few deserve special mention: Tim Peters, -who helped develop the ideas that led to the selection commands, rewrite -rules, and many other algebra features; -@texline Fran\c{c}ois -@infoline Francois -Pinard, who contributed an early prototype of the Calc Summary appendix -as well as providing valuable suggestions in many other areas of Calc; -Carl Witty, whose eagle eyes discovered many typographical and factual -errors in the Calc manual; Tim Kay, who drove the development of -Embedded mode; Ove Ewerlid, who made many suggestions relating to the -algebra commands and contributed some code for polynomial operations; -Randal Schwartz, who suggested the @code{calc-eval} function; Juha -Sarlin, who first worked out how to split Calc into quickly-loading -parts; Bob Weiner, who helped immensely with the Lucid Emacs port; and -Robert J. Chassell, who suggested the Calc Tutorial and exercises as -well as many other things. - -@cindex Bibliography -@cindex Knuth, Art of Computer Programming -@cindex Numerical Recipes -@c Should these be expanded into more complete references? -Among the books used in the development of Calc were Knuth's @emph{Art -of Computer Programming} (especially volume II, @emph{Seminumerical -Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky, -and Vetterling; Bevington's @emph{Data Reduction and Error Analysis -for the Physical Sciences}; @emph{Concrete Mathematics} by Graham, -Knuth, and Patashnik; Steele's @emph{Common Lisp, the Language}; the -@emph{CRC Standard Math Tables} (William H. Beyer, ed.); and -Abramowitz and Stegun's venerable @emph{Handbook of Mathematical -Functions}. Also, of course, Calc could not have been written without -the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil Lewis and -Dan LaLiberte. - -Final thanks go to Richard Stallman, without whose fine implementations -of the Emacs editor, language, and environment, Calc would have been -finished in two weeks. - -@c [tutorial] - -@ifinfo -@c This node is accessed by the `C-x * t' command. -@node Interactive Tutorial, Tutorial, Getting Started, Top -@chapter Tutorial - -@noindent -Some brief instructions on using the Emacs Info system for this tutorial: - -Press the space bar and Delete keys to go forward and backward in a -section by screenfuls (or use the regular Emacs scrolling commands -for this). - -Press @kbd{n} or @kbd{p} to go to the Next or Previous section. -If the section has a @dfn{menu}, press a digit key like @kbd{1} -or @kbd{2} to go to a sub-section from the menu. Press @kbd{u} to -go back up from a sub-section to the menu it is part of. - -Exercises in the tutorial all have cross-references to the -appropriate page of the ``answers'' section. Press @kbd{f}, then -the exercise number, to see the answer to an exercise. After -you have followed a cross-reference, you can press the letter -@kbd{l} to return to where you were before. - -You can press @kbd{?} at any time for a brief summary of Info commands. - -Press the number @kbd{1} now to enter the first section of the Tutorial. - -@menu -* Tutorial:: -@end menu - -@node Tutorial, Introduction, Interactive Tutorial, Top -@end ifinfo -@ifnotinfo -@node Tutorial, Introduction, Getting Started, Top -@end ifnotinfo -@chapter Tutorial - -@noindent -This chapter explains how to use Calc and its many features, in -a step-by-step, tutorial way. You are encouraged to run Calc and -work along with the examples as you read (@pxref{Starting Calc}). -If you are already familiar with advanced calculators, you may wish -@c [not-split] -to skip on to the rest of this manual. -@c [when-split] -@c to skip on to volume II of this manual, the @dfn{Calc Reference}. - -@c [fix-ref Embedded Mode] -This tutorial describes the standard user interface of Calc only. -The Quick mode and Keypad mode interfaces are fairly -self-explanatory. @xref{Embedded Mode}, for a description of -the Embedded mode interface. - -The easiest way to read this tutorial on-line is to have two windows on -your Emacs screen, one with Calc and one with the Info system. Press -@kbd{C-x * t} to set this up; the on-line tutorial will be opened in the -current window and Calc will be started in another window. From the -Info window, the command @kbd{C-x * c} can be used to switch to the Calc -window and @kbd{C-x * o} can be used to switch back to the Info window. -(If you have a printed copy of the manual you can use that instead; in -that case you only need to press @kbd{C-x * c} to start Calc.) - -This tutorial is designed to be done in sequence. But the rest of this -manual does not assume you have gone through the tutorial. The tutorial -does not cover everything in the Calculator, but it touches on most -general areas. - -@ifnottex -You may wish to print out a copy of the Calc Summary and keep notes on -it as you learn Calc. @xref{About This Manual}, to see how to make a -printed summary. @xref{Summary}. -@end ifnottex -@iftex -The Calc Summary at the end of the reference manual includes some blank -space for your own use. You may wish to keep notes there as you learn -Calc. -@end iftex - -@menu -* Basic Tutorial:: -* Arithmetic Tutorial:: -* Vector/Matrix Tutorial:: -* Types Tutorial:: -* Algebra Tutorial:: -* Programming Tutorial:: - -* Answers to Exercises:: -@end menu - -@node Basic Tutorial, Arithmetic Tutorial, Tutorial, Tutorial -@section Basic Tutorial - -@noindent -In this section, we learn how RPN and algebraic-style calculations -work, how to undo and redo an operation done by mistake, and how -to control various modes of the Calculator. - -@menu -* RPN Tutorial:: Basic operations with the stack. -* Algebraic Tutorial:: Algebraic entry; variables. -* Undo Tutorial:: If you make a mistake: Undo and the trail. -* Modes Tutorial:: Common mode-setting commands. -@end menu - -@node RPN Tutorial, Algebraic Tutorial, Basic Tutorial, Basic Tutorial -@subsection RPN Calculations and the Stack - -@cindex RPN notation -@noindent -@ifnottex -Calc normally uses RPN notation. You may be familiar with the RPN -system from Hewlett-Packard calculators, FORTH, or PostScript. -(Reverse Polish Notation, RPN, is named after the Polish mathematician -Jan Lukasiewicz.) -@end ifnottex -@tex -Calc normally uses RPN notation. You may be familiar with the RPN -system from Hewlett-Packard calculators, FORTH, or PostScript. -(Reverse Polish Notation, RPN, is named after the Polish mathematician -Jan \L ukasiewicz.) -@end tex - -The central component of an RPN calculator is the @dfn{stack}. A -calculator stack is like a stack of dishes. New dishes (numbers) are -added at the top of the stack, and numbers are normally only removed -from the top of the stack. - -@cindex Operators -@cindex Operands -In an operation like @expr{2+3}, the 2 and 3 are called the @dfn{operands} -and the @expr{+} is the @dfn{operator}. In an RPN calculator you always -enter the operands first, then the operator. Each time you type a -number, Calc adds or @dfn{pushes} it onto the top of the Stack. -When you press an operator key like @kbd{+}, Calc @dfn{pops} the appropriate -number of operands from the stack and pushes back the result. - -Thus we could add the numbers 2 and 3 in an RPN calculator by typing: -@kbd{2 @key{RET} 3 @key{RET} +}. (The @key{RET} key, Return, corresponds to -the @key{ENTER} key on traditional RPN calculators.) Try this now if -you wish; type @kbd{C-x * c} to switch into the Calc window (you can type -@kbd{C-x * c} again or @kbd{C-x * o} to switch back to the Tutorial window). -The first four keystrokes ``push'' the numbers 2 and 3 onto the stack. -The @kbd{+} key ``pops'' the top two numbers from the stack, adds them, -and pushes the result (5) back onto the stack. Here's how the stack -will look at various points throughout the calculation: - -@smallexample -@group - . 1: 2 2: 2 1: 5 . - . 1: 3 . - . - - C-x * c 2 @key{RET} 3 @key{RET} + @key{DEL} -@end group -@end smallexample - -The @samp{.} symbol is a marker that represents the top of the stack. -Note that the ``top'' of the stack is really shown at the bottom of -the Stack window. This may seem backwards, but it turns out to be -less distracting in regular use. - -@cindex Stack levels -@cindex Levels of stack -The numbers @samp{1:} and @samp{2:} on the left are @dfn{stack level -numbers}. Old RPN calculators always had four stack levels called -@expr{x}, @expr{y}, @expr{z}, and @expr{t}. Calc's stack can grow -as large as you like, so it uses numbers instead of letters. Some -stack-manipulation commands accept a numeric argument that says -which stack level to work on. Normal commands like @kbd{+} always -work on the top few levels of the stack. - -@c [fix-ref Truncating the Stack] -The Stack buffer is just an Emacs buffer, and you can move around in -it using the regular Emacs motion commands. But no matter where the -cursor is, even if you have scrolled the @samp{.} marker out of -view, most Calc commands always move the cursor back down to level 1 -before doing anything. It is possible to move the @samp{.} marker -upwards through the stack, temporarily ``hiding'' some numbers from -commands like @kbd{+}. This is called @dfn{stack truncation} and -we will not cover it in this tutorial; @pxref{Truncating the Stack}, -if you are interested. - -You don't really need the second @key{RET} in @kbd{2 @key{RET} 3 -@key{RET} +}. That's because if you type any operator name or -other non-numeric key when you are entering a number, the Calculator -automatically enters that number and then does the requested command. -Thus @kbd{2 @key{RET} 3 +} will work just as well. - -Examples in this tutorial will often omit @key{RET} even when the -stack displays shown would only happen if you did press @key{RET}: - -@smallexample -@group -1: 2 2: 2 1: 5 - . 1: 3 . - . - - 2 @key{RET} 3 + -@end group -@end smallexample - -@noindent -Here, after pressing @kbd{3} the stack would really show @samp{1: 2} -with @samp{Calc:@: 3} in the minibuffer. In these situations, you can -press the optional @key{RET} to see the stack as the figure shows. - -(@bullet{}) @strong{Exercise 1.} (This tutorial will include exercises -at various points. Try them if you wish. Answers to all the exercises -are located at the end of the Tutorial chapter. Each exercise will -include a cross-reference to its particular answer. If you are -reading with the Emacs Info system, press @kbd{f} and the -exercise number to go to the answer, then the letter @kbd{l} to -return to where you were.) - -@noindent -Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2 -@key{RET} 3 @key{RET} 4 + * -} compute? (@samp{*} is the symbol for -multiplication.) Figure it out by hand, then try it with Calc to see -if you're right. @xref{RPN Answer 1, 1}. (@bullet{}) - -(@bullet{}) @strong{Exercise 2.} Compute -@texline @math{(2\times4) + (7\times9.5) + {5\over4}} -@infoline @expr{2*4 + 7*9.5 + 5/4} -using the stack. @xref{RPN Answer 2, 2}. (@bullet{}) - -The @key{DEL} key is called Backspace on some keyboards. It is -whatever key you would use to correct a simple typing error when -regularly using Emacs. The @key{DEL} key pops and throws away the -top value on the stack. (You can still get that value back from -the Trail if you should need it later on.) There are many places -in this tutorial where we assume you have used @key{DEL} to erase the -results of the previous example at the beginning of a new example. -In the few places where it is really important to use @key{DEL} to -clear away old results, the text will remind you to do so. - -(It won't hurt to let things accumulate on the stack, except that -whenever you give a display-mode-changing command Calc will have to -spend a long time reformatting such a large stack.) - -Since the @kbd{-} key is also an operator (it subtracts the top two -stack elements), how does one enter a negative number? Calc uses -the @kbd{_} (underscore) key to act like the minus sign in a number. -So, typing @kbd{-5 @key{RET}} won't work because the @kbd{-} key -will try to do a subtraction, but @kbd{_5 @key{RET}} works just fine. - -You can also press @kbd{n}, which means ``change sign.'' It changes -the number at the top of the stack (or the number being entered) -from positive to negative or vice-versa: @kbd{5 n @key{RET}}. - -@cindex Duplicating a stack entry -If you press @key{RET} when you're not entering a number, the effect -is to duplicate the top number on the stack. Consider this calculation: - -@smallexample -@group -1: 3 2: 3 1: 9 2: 9 1: 81 - . 1: 3 . 1: 9 . - . . - - 3 @key{RET} @key{RET} * @key{RET} * -@end group -@end smallexample - -@noindent -(Of course, an easier way to do this would be @kbd{3 @key{RET} 4 ^}, -to raise 3 to the fourth power.) - -The space-bar key (denoted @key{SPC} here) performs the same function -as @key{RET}; you could replace all three occurrences of @key{RET} in -the above example with @key{SPC} and the effect would be the same. - -@cindex Exchanging stack entries -Another stack manipulation key is @key{TAB}. This exchanges the top -two stack entries. Suppose you have computed @kbd{2 @key{RET} 3 +} -to get 5, and then you realize what you really wanted to compute -was @expr{20 / (2+3)}. - -@smallexample -@group -1: 5 2: 5 2: 20 1: 4 - . 1: 20 1: 5 . - . . - - 2 @key{RET} 3 + 20 @key{TAB} / -@end group -@end smallexample - -@noindent -Planning ahead, the calculation would have gone like this: - -@smallexample -@group -1: 20 2: 20 3: 20 2: 20 1: 4 - . 1: 2 2: 2 1: 5 . - . 1: 3 . - . - - 20 @key{RET} 2 @key{RET} 3 + / -@end group -@end smallexample - -A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type -@key{TAB}). It rotates the top three elements of the stack upward, -bringing the object in level 3 to the top. - -@smallexample -@group -1: 10 2: 10 3: 10 3: 20 3: 30 - . 1: 20 2: 20 2: 30 2: 10 - . 1: 30 1: 10 1: 20 - . . . - - 10 @key{RET} 20 @key{RET} 30 @key{RET} M-@key{TAB} M-@key{TAB} -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 3.} Suppose the numbers 10, 20, and 30 are -on the stack. Figure out how to add one to the number in level 2 -without affecting the rest of the stack. Also figure out how to add -one to the number in level 3. @xref{RPN Answer 3, 3}. (@bullet{}) - -Operations like @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, and @kbd{^} pop two -arguments from the stack and push a result. Operations like @kbd{n} and -@kbd{Q} (square root) pop a single number and push the result. You can -think of them as simply operating on the top element of the stack. - -@smallexample -@group -1: 3 1: 9 2: 9 1: 25 1: 5 - . . 1: 16 . . - . - - 3 @key{RET} @key{RET} * 4 @key{RET} @key{RET} * + Q -@end group -@end smallexample - -@noindent -(Note that capital @kbd{Q} means to hold down the Shift key while -typing @kbd{q}. Remember, plain unshifted @kbd{q} is the Quit command.) - -@cindex Pythagorean Theorem -Here we've used the Pythagorean Theorem to determine the hypotenuse of a -right triangle. Calc actually has a built-in command for that called -@kbd{f h}, but let's suppose we can't remember the necessary keystrokes. -We can still enter it by its full name using @kbd{M-x} notation: - -@smallexample -@group -1: 3 2: 3 1: 5 - . 1: 4 . - . - - 3 @key{RET} 4 @key{RET} M-x calc-hypot -@end group -@end smallexample - -All Calculator commands begin with the word @samp{calc-}. Since it -gets tiring to type this, Calc provides an @kbd{x} key which is just -like the regular Emacs @kbd{M-x} key except that it types the @samp{calc-} -prefix for you: - -@smallexample -@group -1: 3 2: 3 1: 5 - . 1: 4 . - . - - 3 @key{RET} 4 @key{RET} x hypot -@end group -@end smallexample - -What happens if you take the square root of a negative number? - -@smallexample -@group -1: 4 1: -4 1: (0, 2) - . . . - - 4 @key{RET} n Q -@end group -@end smallexample - -@noindent -The notation @expr{(a, b)} represents a complex number. -Complex numbers are more traditionally written @expr{a + b i}; -Calc can display in this format, too, but for now we'll stick to the -@expr{(a, b)} notation. - -If you don't know how complex numbers work, you can safely ignore this -feature. Complex numbers only arise from operations that would be -errors in a calculator that didn't have complex numbers. (For example, -taking the square root or logarithm of a negative number produces a -complex result.) - -Complex numbers are entered in the notation shown. The @kbd{(} and -@kbd{,} and @kbd{)} keys manipulate ``incomplete complex numbers.'' - -@smallexample -@group -1: ( ... 2: ( ... 1: (2, ... 1: (2, ... 1: (2, 3) - . 1: 2 . 3 . - . . - - ( 2 , 3 ) -@end group -@end smallexample - -You can perform calculations while entering parts of incomplete objects. -However, an incomplete object cannot actually participate in a calculation: - -@smallexample -@group -1: ( ... 2: ( ... 3: ( ... 1: ( ... 1: ( ... - . 1: 2 2: 2 5 5 - . 1: 3 . . - . - (error) - ( 2 @key{RET} 3 + + -@end group -@end smallexample - -@noindent -Adding 5 to an incomplete object makes no sense, so the last command -produces an error message and leaves the stack the same. - -Incomplete objects can't participate in arithmetic, but they can be -moved around by the regular stack commands. - -@smallexample -@group -2: 2 3: 2 3: 3 1: ( ... 1: (2, 3) -1: 3 2: 3 2: ( ... 2 . - . 1: ( ... 1: 2 3 - . . . - -2 @key{RET} 3 @key{RET} ( M-@key{TAB} M-@key{TAB} ) -@end group -@end smallexample - -@noindent -Note that the @kbd{,} (comma) key did not have to be used here. -When you press @kbd{)} all the stack entries between the incomplete -entry and the top are collected, so there's never really a reason -to use the comma. It's up to you. - -(@bullet{}) @strong{Exercise 4.} To enter the complex number @expr{(2, 3)}, -your friend Joe typed @kbd{( 2 , @key{SPC} 3 )}. What happened? -(Joe thought of a clever way to correct his mistake in only two -keystrokes, but it didn't quite work. Try it to find out why.) -@xref{RPN Answer 4, 4}. (@bullet{}) - -Vectors are entered the same way as complex numbers, but with square -brackets in place of parentheses. We'll meet vectors again later in -the tutorial. - -Any Emacs command can be given a @dfn{numeric prefix argument} by -typing a series of @key{META}-digits beforehand. If @key{META} is -awkward for you, you can instead type @kbd{C-u} followed by the -necessary digits. Numeric prefix arguments can be negative, as in -@kbd{M-- M-3 M-5} or @w{@kbd{C-u - 3 5}}. Calc commands use numeric -prefix arguments in a variety of ways. For example, a numeric prefix -on the @kbd{+} operator adds any number of stack entries at once: - -@smallexample -@group -1: 10 2: 10 3: 10 3: 10 1: 60 - . 1: 20 2: 20 2: 20 . - . 1: 30 1: 30 - . . - - 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u 3 + -@end group -@end smallexample - -For stack manipulation commands like @key{RET}, a positive numeric -prefix argument operates on the top @var{n} stack entries at once. A -negative argument operates on the entry in level @var{n} only. An -argument of zero operates on the entire stack. In this example, we copy -the second-to-top element of the stack: - -@smallexample -@group -1: 10 2: 10 3: 10 3: 10 4: 10 - . 1: 20 2: 20 2: 20 3: 20 - . 1: 30 1: 30 2: 30 - . . 1: 20 - . - - 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u -2 @key{RET} -@end group -@end smallexample - -@cindex Clearing the stack -@cindex Emptying the stack -Another common idiom is @kbd{M-0 @key{DEL}}, which clears the stack. -(The @kbd{M-0} numeric prefix tells @key{DEL} to operate on the -entire stack.) - -@node Algebraic Tutorial, Undo Tutorial, RPN Tutorial, Basic Tutorial -@subsection Algebraic-Style Calculations - -@noindent -If you are not used to RPN notation, you may prefer to operate the -Calculator in Algebraic mode, which is closer to the way -non-RPN calculators work. In Algebraic mode, you enter formulas -in traditional @expr{2+3} notation. - -@strong{Notice:} Calc gives @samp{/} lower precedence than @samp{*}, so -that @samp{a/b*c} is interpreted as @samp{a/(b*c)}; this is not -standard across all computer languages. See below for details. - -You don't really need any special ``mode'' to enter algebraic formulas. -You can enter a formula at any time by pressing the apostrophe (@kbd{'}) -key. Answer the prompt with the desired formula, then press @key{RET}. -The formula is evaluated and the result is pushed onto the RPN stack. -If you don't want to think in RPN at all, you can enter your whole -computation as a formula, read the result from the stack, then press -@key{DEL} to delete it from the stack. - -Try pressing the apostrophe key, then @kbd{2+3+4}, then @key{RET}. -The result should be the number 9. - -Algebraic formulas use the operators @samp{+}, @samp{-}, @samp{*}, -@samp{/}, and @samp{^}. You can use parentheses to make the order -of evaluation clear. In the absence of parentheses, @samp{^} is -evaluated first, then @samp{*}, then @samp{/}, then finally -@samp{+} and @samp{-}. For example, the expression - -@example -2 + 3*4*5 / 6*7^8 - 9 -@end example - -@noindent -is equivalent to - -@example -2 + ((3*4*5) / (6*(7^8)) - 9 -@end example - -@noindent -or, in large mathematical notation, - -@ifnottex -@example -@group - 3 * 4 * 5 -2 + --------- - 9 - 8 - 6 * 7 -@end group -@end example -@end ifnottex -@tex -\beforedisplay -$$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$ -\afterdisplay -@end tex - -@noindent -The result of this expression will be the number @mathit{-6.99999826533}. - -Calc's order of evaluation is the same as for most computer languages, -except that @samp{*} binds more strongly than @samp{/}, as the above -example shows. As in normal mathematical notation, the @samp{*} symbol -can often be omitted: @samp{2 a} is the same as @samp{2*a}. - -Operators at the same level are evaluated from left to right, except -that @samp{^} is evaluated from right to left. Thus, @samp{2-3-4} is -equivalent to @samp{(2-3)-4} or @mathit{-5}, whereas @samp{2^3^4} is equivalent -to @samp{2^(3^4)} (a very large integer; try it!). - -If you tire of typing the apostrophe all the time, there is -Algebraic mode, where Calc automatically senses -when you are about to type an algebraic expression. To enter this -mode, press the two letters @w{@kbd{m a}}. (An @samp{Alg} indicator -should appear in the Calc window's mode line.) - -Press @kbd{m a}, then @kbd{2+3+4} with no apostrophe, then @key{RET}. - -In Algebraic mode, when you press any key that would normally begin -entering a number (such as a digit, a decimal point, or the @kbd{_} -key), or if you press @kbd{(} or @kbd{[}, Calc automatically begins -an algebraic entry. - -Functions which do not have operator symbols like @samp{+} and @samp{*} -must be entered in formulas using function-call notation. For example, -the function name corresponding to the square-root key @kbd{Q} is -@code{sqrt}. To compute a square root in a formula, you would use -the notation @samp{sqrt(@var{x})}. - -Press the apostrophe, then type @kbd{sqrt(5*2) - 3}. The result should -be @expr{0.16227766017}. - -Note that if the formula begins with a function name, you need to use -the apostrophe even if you are in Algebraic mode. If you type @kbd{arcsin} -out of the blue, the @kbd{a r} will be taken as an Algebraic Rewrite -command, and the @kbd{csin} will be taken as the name of the rewrite -rule to use! - -Some people prefer to enter complex numbers and vectors in algebraic -form because they find RPN entry with incomplete objects to be too -distracting, even though they otherwise use Calc as an RPN calculator. - -Still in Algebraic mode, type: - -@smallexample -@group -1: (2, 3) 2: (2, 3) 1: (8, -1) 2: (8, -1) 1: (9, -1) - . 1: (1, -2) . 1: 1 . - . . - - (2,3) @key{RET} (1,-2) @key{RET} * 1 @key{RET} + -@end group -@end smallexample - -Algebraic mode allows us to enter complex numbers without pressing -an apostrophe first, but it also means we need to press @key{RET} -after every entry, even for a simple number like @expr{1}. - -(You can type @kbd{C-u m a} to enable a special Incomplete Algebraic -mode in which the @kbd{(} and @kbd{[} keys use algebraic entry even -though regular numeric keys still use RPN numeric entry. There is also -Total Algebraic mode, started by typing @kbd{m t}, in which all -normal keys begin algebraic entry. You must then use the @key{META} key -to type Calc commands: @kbd{M-m t} to get back out of Total Algebraic -mode, @kbd{M-q} to quit, etc.) - -If you're still in Algebraic mode, press @kbd{m a} again to turn it off. - -Actual non-RPN calculators use a mixture of algebraic and RPN styles. -In general, operators of two numbers (like @kbd{+} and @kbd{*}) -use algebraic form, but operators of one number (like @kbd{n} and @kbd{Q}) -use RPN form. Also, a non-RPN calculator allows you to see the -intermediate results of a calculation as you go along. You can -accomplish this in Calc by performing your calculation as a series -of algebraic entries, using the @kbd{$} sign to tie them together. -In an algebraic formula, @kbd{$} represents the number on the top -of the stack. Here, we perform the calculation -@texline @math{\sqrt{2\times4+1}}, -@infoline @expr{sqrt(2*4+1)}, -which on a traditional calculator would be done by pressing -@kbd{2 * 4 + 1 =} and then the square-root key. - -@smallexample -@group -1: 8 1: 9 1: 3 - . . . - - ' 2*4 @key{RET} $+1 @key{RET} Q -@end group -@end smallexample - -@noindent -Notice that we didn't need to press an apostrophe for the @kbd{$+1}, -because the dollar sign always begins an algebraic entry. - -(@bullet{}) @strong{Exercise 1.} How could you get the same effect as -pressing @kbd{Q} but using an algebraic entry instead? How about -if the @kbd{Q} key on your keyboard were broken? -@xref{Algebraic Answer 1, 1}. (@bullet{}) - -The notations @kbd{$$}, @kbd{$$$}, and so on stand for higher stack -entries. For example, @kbd{' $$+$ @key{RET}} is just like typing @kbd{+}. - -Algebraic formulas can include @dfn{variables}. To store in a -variable, press @kbd{s s}, then type the variable name, then press -@key{RET}. (There are actually two flavors of store command: -@kbd{s s} stores a number in a variable but also leaves the number -on the stack, while @w{@kbd{s t}} removes a number from the stack and -stores it in the variable.) A variable name should consist of one -or more letters or digits, beginning with a letter. - -@smallexample -@group -1: 17 . 1: a + a^2 1: 306 - . . . - - 17 s t a @key{RET} ' a+a^2 @key{RET} = -@end group -@end smallexample - -@noindent -The @kbd{=} key @dfn{evaluates} a formula by replacing all its -variables by the values that were stored in them. - -For RPN calculations, you can recall a variable's value on the -stack either by entering its name as a formula and pressing @kbd{=}, -or by using the @kbd{s r} command. - -@smallexample -@group -1: 17 2: 17 3: 17 2: 17 1: 306 - . 1: 17 2: 17 1: 289 . - . 1: 2 . - . - - s r a @key{RET} ' a @key{RET} = 2 ^ + -@end group -@end smallexample - -If you press a single digit for a variable name (as in @kbd{s t 3}, you -get one of ten @dfn{quick variables} @code{q0} through @code{q9}. -They are ``quick'' simply because you don't have to type the letter -@code{q} or the @key{RET} after their names. In fact, you can type -simply @kbd{s 3} as a shorthand for @kbd{s s 3}, and likewise for -@kbd{t 3} and @w{@kbd{r 3}}. - -Any variables in an algebraic formula for which you have not stored -values are left alone, even when you evaluate the formula. - -@smallexample -@group -1: 2 a + 2 b 1: 2 b + 34 - . . - - ' 2a+2b @key{RET} = -@end group -@end smallexample - -Calls to function names which are undefined in Calc are also left -alone, as are calls for which the value is undefined. - -@smallexample -@group -1: log10(0) + log10(x) + log10(5, 6) + foo(3) + 2 - . - - ' log10(100) + log10(0) + log10(x) + log10(5,6) + foo(3) @key{RET} -@end group -@end smallexample - -@noindent -In this example, the first call to @code{log10} works, but the other -calls are not evaluated. In the second call, the logarithm is -undefined for that value of the argument; in the third, the argument -is symbolic, and in the fourth, there are too many arguments. In the -fifth case, there is no function called @code{foo}. You will see a -``Wrong number of arguments'' message referring to @samp{log10(5,6)}. -Press the @kbd{w} (``why'') key to see any other messages that may -have arisen from the last calculation. In this case you will get -``logarithm of zero,'' then ``number expected: @code{x}''. Calc -automatically displays the first message only if the message is -sufficiently important; for example, Calc considers ``wrong number -of arguments'' and ``logarithm of zero'' to be important enough to -report automatically, while a message like ``number expected: @code{x}'' -will only show up if you explicitly press the @kbd{w} key. - -(@bullet{}) @strong{Exercise 2.} Joe entered the formula @samp{2 x y}, -stored 5 in @code{x}, pressed @kbd{=}, and got the expected result, -@samp{10 y}. He then tried the same for the formula @samp{2 x (1+y)}, -expecting @samp{10 (1+y)}, but it didn't work. Why not? -@xref{Algebraic Answer 2, 2}. (@bullet{}) - -(@bullet{}) @strong{Exercise 3.} What result would you expect -@kbd{1 @key{RET} 0 /} to give? What if you then type @kbd{0 *}? -@xref{Algebraic Answer 3, 3}. (@bullet{}) - -One interesting way to work with variables is to use the -@dfn{evaluates-to} (@samp{=>}) operator. It works like this: -Enter a formula algebraically in the usual way, but follow -the formula with an @samp{=>} symbol. (There is also an @kbd{s =} -command which builds an @samp{=>} formula using the stack.) On -the stack, you will see two copies of the formula with an @samp{=>} -between them. The lefthand formula is exactly like you typed it; -the righthand formula has been evaluated as if by typing @kbd{=}. - -@smallexample -@group -2: 2 + 3 => 5 2: 2 + 3 => 5 -1: 2 a + 2 b => 34 + 2 b 1: 2 a + 2 b => 20 + 2 b - . . - -' 2+3 => @key{RET} ' 2a+2b @key{RET} s = 10 s t a @key{RET} -@end group -@end smallexample - -@noindent -Notice that the instant we stored a new value in @code{a}, all -@samp{=>} operators already on the stack that referred to @expr{a} -were updated to use the new value. With @samp{=>}, you can push a -set of formulas on the stack, then change the variables experimentally -to see the effects on the formulas' values. - -You can also ``unstore'' a variable when you are through with it: - -@smallexample -@group -2: 2 + 5 => 5 -1: 2 a + 2 b => 2 a + 2 b - . - - s u a @key{RET} -@end group -@end smallexample - -We will encounter formulas involving variables and functions again -when we discuss the algebra and calculus features of the Calculator. - -@node Undo Tutorial, Modes Tutorial, Algebraic Tutorial, Basic Tutorial -@subsection Undo and Redo - -@noindent -If you make a mistake, you can usually correct it by pressing shift-@kbd{U}, -the ``undo'' command. First, clear the stack (@kbd{M-0 @key{DEL}}) and exit -and restart Calc (@kbd{C-x * * C-x * *}) to make sure things start off -with a clean slate. Now: - -@smallexample -@group -1: 2 2: 2 1: 8 2: 2 1: 6 - . 1: 3 . 1: 3 . - . . - - 2 @key{RET} 3 ^ U * -@end group -@end smallexample - -You can undo any number of times. Calc keeps a complete record of -all you have done since you last opened the Calc window. After the -above example, you could type: - -@smallexample -@group -1: 6 2: 2 1: 2 . . - . 1: 3 . - . - (error) - U U U U -@end group -@end smallexample - -You can also type @kbd{D} to ``redo'' a command that you have undone -mistakenly. - -@smallexample -@group - . 1: 2 2: 2 1: 6 1: 6 - . 1: 3 . . - . - (error) - D D D D -@end group -@end smallexample - -@noindent -It was not possible to redo past the @expr{6}, since that was placed there -by something other than an undo command. - -@cindex Time travel -You can think of undo and redo as a sort of ``time machine.'' Press -@kbd{U} to go backward in time, @kbd{D} to go forward. If you go -backward and do something (like @kbd{*}) then, as any science fiction -reader knows, you have changed your future and you cannot go forward -again. Thus, the inability to redo past the @expr{6} even though there -was an earlier undo command. - -You can always recall an earlier result using the Trail. We've ignored -the trail so far, but it has been faithfully recording everything we -did since we loaded the Calculator. If the Trail is not displayed, -press @kbd{t d} now to turn it on. - -Let's try grabbing an earlier result. The @expr{8} we computed was -undone by a @kbd{U} command, and was lost even to Redo when we pressed -@kbd{*}, but it's still there in the trail. There should be a little -@samp{>} arrow (the @dfn{trail pointer}) resting on the last trail -entry. If there isn't, press @kbd{t ]} to reset the trail pointer. -Now, press @w{@kbd{t p}} to move the arrow onto the line containing -@expr{8}, and press @w{@kbd{t y}} to ``yank'' that number back onto the -stack. - -If you press @kbd{t ]} again, you will see that even our Yank command -went into the trail. - -Let's go further back in time. Earlier in the tutorial we computed -a huge integer using the formula @samp{2^3^4}. We don't remember -what it was, but the first digits were ``241''. Press @kbd{t r} -(which stands for trail-search-reverse), then type @kbd{241}. -The trail cursor will jump back to the next previous occurrence of -the string ``241'' in the trail. This is just a regular Emacs -incremental search; you can now press @kbd{C-s} or @kbd{C-r} to -continue the search forwards or backwards as you like. - -To finish the search, press @key{RET}. This halts the incremental -search and leaves the trail pointer at the thing we found. Now we -can type @kbd{t y} to yank that number onto the stack. If we hadn't -remembered the ``241'', we could simply have searched for @kbd{2^3^4}, -then pressed @kbd{@key{RET} t n} to halt and then move to the next item. - -You may have noticed that all the trail-related commands begin with -the letter @kbd{t}. (The store-and-recall commands, on the other hand, -all began with @kbd{s}.) Calc has so many commands that there aren't -enough keys for all of them, so various commands are grouped into -two-letter sequences where the first letter is called the @dfn{prefix} -key. If you type a prefix key by accident, you can press @kbd{C-g} -to cancel it. (In fact, you can press @kbd{C-g} to cancel almost -anything in Emacs.) To get help on a prefix key, press that key -followed by @kbd{?}. Some prefixes have several lines of help, -so you need to press @kbd{?} repeatedly to see them all. -You can also type @kbd{h h} to see all the help at once. - -Try pressing @kbd{t ?} now. You will see a line of the form, - -@smallexample -trail/time: Display; Fwd, Back; Next, Prev, Here, [, ]; Yank: [MORE] t- -@end smallexample - -@noindent -The word ``trail'' indicates that the @kbd{t} prefix key contains -trail-related commands. Each entry on the line shows one command, -with a single capital letter showing which letter you press to get -that command. We have used @kbd{t n}, @kbd{t p}, @kbd{t ]}, and -@kbd{t y} so far. The @samp{[MORE]} means you can press @kbd{?} -again to see more @kbd{t}-prefix commands. Notice that the commands -are roughly divided (by semicolons) into related groups. - -When you are in the help display for a prefix key, the prefix is -still active. If you press another key, like @kbd{y} for example, -it will be interpreted as a @kbd{t y} command. If all you wanted -was to look at the help messages, press @kbd{C-g} afterwards to cancel -the prefix. - -One more way to correct an error is by editing the stack entries. -The actual Stack buffer is marked read-only and must not be edited -directly, but you can press @kbd{`} (the backquote or accent grave) -to edit a stack entry. - -Try entering @samp{3.141439} now. If this is supposed to represent -@cpi{}, it's got several errors. Press @kbd{`} to edit this number. -Now use the normal Emacs cursor motion and editing keys to change -the second 4 to a 5, and to transpose the 3 and the 9. When you -press @key{RET}, the number on the stack will be replaced by your -new number. This works for formulas, vectors, and all other types -of values you can put on the stack. The @kbd{`} key also works -during entry of a number or algebraic formula. - -@node Modes Tutorial, , Undo Tutorial, Basic Tutorial -@subsection Mode-Setting Commands - -@noindent -Calc has many types of @dfn{modes} that affect the way it interprets -your commands or the way it displays data. We have already seen one -mode, namely Algebraic mode. There are many others, too; we'll -try some of the most common ones here. - -Perhaps the most fundamental mode in Calc is the current @dfn{precision}. -Notice the @samp{12} on the Calc window's mode line: - -@smallexample ---%*-Calc: 12 Deg (Calculator)----All------ -@end smallexample - -@noindent -Most of the symbols there are Emacs things you don't need to worry -about, but the @samp{12} and the @samp{Deg} are mode indicators. -The @samp{12} means that calculations should always be carried to -12 significant figures. That is why, when we type @kbd{1 @key{RET} 7 /}, -we get @expr{0.142857142857} with exactly 12 digits, not counting -leading and trailing zeros. - -You can set the precision to anything you like by pressing @kbd{p}, -then entering a suitable number. Try pressing @kbd{p 30 @key{RET}}, -then doing @kbd{1 @key{RET} 7 /} again: - -@smallexample -@group -1: 0.142857142857 -2: 0.142857142857142857142857142857 - . -@end group -@end smallexample - -Although the precision can be set arbitrarily high, Calc always -has to have @emph{some} value for the current precision. After -all, the true value @expr{1/7} is an infinitely repeating decimal; -Calc has to stop somewhere. - -Of course, calculations are slower the more digits you request. -Press @w{@kbd{p 12}} now to set the precision back down to the default. - -Calculations always use the current precision. For example, even -though we have a 30-digit value for @expr{1/7} on the stack, if -we use it in a calculation in 12-digit mode it will be rounded -down to 12 digits before it is used. Try it; press @key{RET} to -duplicate the number, then @w{@kbd{1 +}}. Notice that the @key{RET} -key didn't round the number, because it doesn't do any calculation. -But the instant we pressed @kbd{+}, the number was rounded down. - -@smallexample -@group -1: 0.142857142857 -2: 0.142857142857142857142857142857 -3: 1.14285714286 - . -@end group -@end smallexample - -@noindent -In fact, since we added a digit on the left, we had to lose one -digit on the right from even the 12-digit value of @expr{1/7}. - -How did we get more than 12 digits when we computed @samp{2^3^4}? The -answer is that Calc makes a distinction between @dfn{integers} and -@dfn{floating-point} numbers, or @dfn{floats}. An integer is a number -that does not contain a decimal point. There is no such thing as an -``infinitely repeating fraction integer,'' so Calc doesn't have to limit -itself. If you asked for @samp{2^10000} (don't try this!), you would -have to wait a long time but you would eventually get an exact answer. -If you ask for @samp{2.^10000}, you will quickly get an answer which is -correct only to 12 places. The decimal point tells Calc that it should -use floating-point arithmetic to get the answer, not exact integer -arithmetic. - -You can use the @kbd{F} (@code{calc-floor}) command to convert a -floating-point value to an integer, and @kbd{c f} (@code{calc-float}) -to convert an integer to floating-point form. - -Let's try entering that last calculation: - -@smallexample -@group -1: 2. 2: 2. 1: 1.99506311689e3010 - . 1: 10000 . - . - - 2.0 @key{RET} 10000 @key{RET} ^ -@end group -@end smallexample - -@noindent -@cindex Scientific notation, entry of -Notice the letter @samp{e} in there. It represents ``times ten to the -power of,'' and is used by Calc automatically whenever writing the -number out fully would introduce more extra zeros than you probably -want to see. You can enter numbers in this notation, too. - -@smallexample -@group -1: 2. 2: 2. 1: 1.99506311678e3010 - . 1: 10000. . - . - - 2.0 @key{RET} 1e4 @key{RET} ^ -@end group -@end smallexample - -@cindex Round-off errors -@noindent -Hey, the answer is different! Look closely at the middle columns -of the two examples. In the first, the stack contained the -exact integer @expr{10000}, but in the second it contained -a floating-point value with a decimal point. When you raise a -number to an integer power, Calc uses repeated squaring and -multiplication to get the answer. When you use a floating-point -power, Calc uses logarithms and exponentials. As you can see, -a slight error crept in during one of these methods. Which -one should we trust? Let's raise the precision a bit and find -out: - -@smallexample -@group - . 1: 2. 2: 2. 1: 1.995063116880828e3010 - . 1: 10000. . - . - - p 16 @key{RET} 2. @key{RET} 1e4 ^ p 12 @key{RET} -@end group -@end smallexample - -@noindent -@cindex Guard digits -Presumably, it doesn't matter whether we do this higher-precision -calculation using an integer or floating-point power, since we -have added enough ``guard digits'' to trust the first 12 digits -no matter what. And the verdict is@dots{} Integer powers were more -accurate; in fact, the result was only off by one unit in the -last place. - -@cindex Guard digits -Calc does many of its internal calculations to a slightly higher -precision, but it doesn't always bump the precision up enough. -In each case, Calc added about two digits of precision during -its calculation and then rounded back down to 12 digits -afterward. In one case, it was enough; in the other, it -wasn't. If you really need @var{x} digits of precision, it -never hurts to do the calculation with a few extra guard digits. - -What if we want guard digits but don't want to look at them? -We can set the @dfn{float format}. Calc supports four major -formats for floating-point numbers, called @dfn{normal}, -@dfn{fixed-point}, @dfn{scientific notation}, and @dfn{engineering -notation}. You get them by pressing @w{@kbd{d n}}, @kbd{d f}, -@kbd{d s}, and @kbd{d e}, respectively. In each case, you can -supply a numeric prefix argument which says how many digits -should be displayed. As an example, let's put a few numbers -onto the stack and try some different display modes. First, -use @kbd{M-0 @key{DEL}} to clear the stack, then enter the four -numbers shown here: - -@smallexample -@group -4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 -3: 12345. 3: 12300. 3: 1.2345e4 3: 1.23e4 3: 12345.000 -2: 123.45 2: 123. 2: 1.2345e2 2: 1.23e2 2: 123.450 -1: 12.345 1: 12.3 1: 1.2345e1 1: 1.23e1 1: 12.345 - . . . . . - - d n M-3 d n d s M-3 d s M-3 d f -@end group -@end smallexample - -@noindent -Notice that when we typed @kbd{M-3 d n}, the numbers were rounded down -to three significant digits, but then when we typed @kbd{d s} all -five significant figures reappeared. The float format does not -affect how numbers are stored, it only affects how they are -displayed. Only the current precision governs the actual rounding -of numbers in the Calculator's memory. - -Engineering notation, not shown here, is like scientific notation -except the exponent (the power-of-ten part) is always adjusted to be -a multiple of three (as in ``kilo,'' ``micro,'' etc.). As a result -there will be one, two, or three digits before the decimal point. - -Whenever you change a display-related mode, Calc redraws everything -in the stack. This may be slow if there are many things on the stack, -so Calc allows you to type shift-@kbd{H} before any mode command to -prevent it from updating the stack. Anything Calc displays after the -mode-changing command will appear in the new format. - -@smallexample -@group -4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 -3: 12345.000 3: 12345.000 3: 12345.000 3: 1.2345e4 3: 12345. -2: 123.450 2: 123.450 2: 1.2345e1 2: 1.2345e1 2: 123.45 -1: 12.345 1: 1.2345e1 1: 1.2345e2 1: 1.2345e2 1: 12.345 - . . . . . - - H d s @key{DEL} U @key{TAB} d @key{SPC} d n -@end group -@end smallexample - -@noindent -Here the @kbd{H d s} command changes to scientific notation but without -updating the screen. Deleting the top stack entry and undoing it back -causes it to show up in the new format; swapping the top two stack -entries reformats both entries. The @kbd{d @key{SPC}} command refreshes the -whole stack. The @kbd{d n} command changes back to the normal float -format; since it doesn't have an @kbd{H} prefix, it also updates all -the stack entries to be in @kbd{d n} format. - -Notice that the integer @expr{12345} was not affected by any -of the float formats. Integers are integers, and are always -displayed exactly. - -@cindex Large numbers, readability -Large integers have their own problems. Let's look back at -the result of @kbd{2^3^4}. - -@example -2417851639229258349412352 -@end example - -@noindent -Quick---how many digits does this have? Try typing @kbd{d g}: - -@example -2,417,851,639,229,258,349,412,352 -@end example - -@noindent -Now how many digits does this have? It's much easier to tell! -We can actually group digits into clumps of any size. Some -people prefer @kbd{M-5 d g}: - -@example -24178,51639,22925,83494,12352 -@end example - -Let's see what happens to floating-point numbers when they are grouped. -First, type @kbd{p 25 @key{RET}} to make sure we have enough precision -to get ourselves into trouble. Now, type @kbd{1e13 /}: - -@example -24,17851,63922.9258349412352 -@end example - -@noindent -The integer part is grouped but the fractional part isn't. Now try -@kbd{M-- M-5 d g} (that's meta-minus-sign, meta-five): - -@example -24,17851,63922.92583,49412,352 -@end example - -If you find it hard to tell the decimal point from the commas, try -changing the grouping character to a space with @kbd{d , @key{SPC}}: - -@example -24 17851 63922.92583 49412 352 -@end example - -Type @kbd{d , ,} to restore the normal grouping character, then -@kbd{d g} again to turn grouping off. Also, press @kbd{p 12} to -restore the default precision. - -Press @kbd{U} enough times to get the original big integer back. -(Notice that @kbd{U} does not undo each mode-setting command; if -you want to undo a mode-setting command, you have to do it yourself.) -Now, type @kbd{d r 16 @key{RET}}: - -@example -16#200000000000000000000 -@end example - -@noindent -The number is now displayed in @dfn{hexadecimal}, or ``base-16'' form. -Suddenly it looks pretty simple; this should be no surprise, since we -got this number by computing a power of two, and 16 is a power of 2. -In fact, we can use @w{@kbd{d r 2 @key{RET}}} to see it in actual binary -form: - -@example -2#1000000000000000000000000000000000000000000000000000000 @dots{} -@end example - -@noindent -We don't have enough space here to show all the zeros! They won't -fit on a typical screen, either, so you will have to use horizontal -scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the -stack window left and right by half its width. Another way to view -something large is to press @kbd{`} (back-quote) to edit the top of -stack in a separate window. (Press @kbd{C-c C-c} when you are done.) - -You can enter non-decimal numbers using the @kbd{#} symbol, too. -Let's see what the hexadecimal number @samp{5FE} looks like in -binary. Type @kbd{16#5FE} (the letters can be typed in upper or -lower case; they will always appear in upper case). It will also -help to turn grouping on with @kbd{d g}: - -@example -2#101,1111,1110 -@end example - -Notice that @kbd{d g} groups by fours by default if the display radix -is binary or hexadecimal, but by threes if it is decimal, octal, or any -other radix. - -Now let's see that number in decimal; type @kbd{d r 10}: - -@example -1,534 -@end example - -Numbers are not @emph{stored} with any particular radix attached. They're -just numbers; they can be entered in any radix, and are always displayed -in whatever radix you've chosen with @kbd{d r}. The current radix applies -to integers, fractions, and floats. - -@cindex Roundoff errors, in non-decimal numbers -(@bullet{}) @strong{Exercise 1.} Your friend Joe tried to enter one-third -as @samp{3#0.1} in @kbd{d r 3} mode with a precision of 12. He got -@samp{3#0.0222222...} (with 25 2's) in the display. When he multiplied -that by three, he got @samp{3#0.222222...} instead of the expected -@samp{3#1}. Next, Joe entered @samp{3#0.2} and, to his great relief, -saw @samp{3#0.2} on the screen. But when he typed @kbd{2 /}, he got -@samp{3#0.10000001} (some zeros omitted). What's going on here? -@xref{Modes Answer 1, 1}. (@bullet{}) - -@cindex Scientific notation, in non-decimal numbers -(@bullet{}) @strong{Exercise 2.} Scientific notation works in non-decimal -modes in the natural way (the exponent is a power of the radix instead of -a power of ten, although the exponent itself is always written in decimal). -Thus @samp{8#1.23e3 = 8#1230.0}. Suppose we have the hexadecimal number -@samp{f.e8f} times 16 to the 15th power: We write @samp{16#f.e8fe15}. -What is wrong with this picture? What could we write instead that would -work better? @xref{Modes Answer 2, 2}. (@bullet{}) - -The @kbd{m} prefix key has another set of modes, relating to the way -Calc interprets your inputs and does computations. Whereas @kbd{d}-prefix -modes generally affect the way things look, @kbd{m}-prefix modes affect -the way they are actually computed. - -The most popular @kbd{m}-prefix mode is the @dfn{angular mode}. Notice -the @samp{Deg} indicator in the mode line. This means that if you use -a command that interprets a number as an angle, it will assume the -angle is measured in degrees. For example, - -@smallexample -@group -1: 45 1: 0.707106781187 1: 0.500000000001 1: 0.5 - . . . . - - 45 S 2 ^ c 1 -@end group -@end smallexample - -@noindent -The shift-@kbd{S} command computes the sine of an angle. The sine -of 45 degrees is -@texline @math{\sqrt{2}/2}; -@infoline @expr{sqrt(2)/2}; -squaring this yields @expr{2/4 = 0.5}. However, there has been a slight -roundoff error because the representation of -@texline @math{\sqrt{2}/2} -@infoline @expr{sqrt(2)/2} -wasn't exact. The @kbd{c 1} command is a handy way to clean up numbers -in this case; it temporarily reduces the precision by one digit while it -re-rounds the number on the top of the stack. - -@cindex Roundoff errors, examples -(@bullet{}) @strong{Exercise 3.} Your friend Joe computed the sine -of 45 degrees as shown above, then, hoping to avoid an inexact -result, he increased the precision to 16 digits before squaring. -What happened? @xref{Modes Answer 3, 3}. (@bullet{}) - -To do this calculation in radians, we would type @kbd{m r} first. -(The indicator changes to @samp{Rad}.) 45 degrees corresponds to -@cpiover{4} radians. To get @cpi{}, press the @kbd{P} key. (Once -again, this is a shifted capital @kbd{P}. Remember, unshifted -@kbd{p} sets the precision.) - -@smallexample -@group -1: 3.14159265359 1: 0.785398163398 1: 0.707106781187 - . . . - - P 4 / m r S -@end group -@end smallexample - -Likewise, inverse trigonometric functions generate results in -either radians or degrees, depending on the current angular mode. - -@smallexample -@group -1: 0.707106781187 1: 0.785398163398 1: 45. - . . . - - .5 Q m r I S m d U I S -@end group -@end smallexample - -@noindent -Here we compute the Inverse Sine of -@texline @math{\sqrt{0.5}}, -@infoline @expr{sqrt(0.5)}, -first in radians, then in degrees. - -Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees -and vice-versa. - -@smallexample -@group -1: 45 1: 0.785398163397 1: 45. - . . . - - 45 c r c d -@end group -@end smallexample - -Another interesting mode is @dfn{Fraction mode}. Normally, -dividing two integers produces a floating-point result if the -quotient can't be expressed as an exact integer. Fraction mode -causes integer division to produce a fraction, i.e., a rational -number, instead. - -@smallexample -@group -2: 12 1: 1.33333333333 1: 4:3 -1: 9 . . - . - - 12 @key{RET} 9 / m f U / m f -@end group -@end smallexample - -@noindent -In the first case, we get an approximate floating-point result. -In the second case, we get an exact fractional result (four-thirds). - -You can enter a fraction at any time using @kbd{:} notation. -(Calc uses @kbd{:} instead of @kbd{/} as the fraction separator -because @kbd{/} is already used to divide the top two stack -elements.) Calculations involving fractions will always -produce exact fractional results; Fraction mode only says -what to do when dividing two integers. - -@cindex Fractions vs. floats -@cindex Floats vs. fractions -(@bullet{}) @strong{Exercise 4.} If fractional arithmetic is exact, -why would you ever use floating-point numbers instead? -@xref{Modes Answer 4, 4}. (@bullet{}) - -Typing @kbd{m f} doesn't change any existing values in the stack. -In the above example, we had to Undo the division and do it over -again when we changed to Fraction mode. But if you use the -evaluates-to operator you can get commands like @kbd{m f} to -recompute for you. - -@smallexample -@group -1: 12 / 9 => 1.33333333333 1: 12 / 9 => 1.333 1: 12 / 9 => 4:3 - . . . - - ' 12/9 => @key{RET} p 4 @key{RET} m f -@end group -@end smallexample - -@noindent -In this example, the righthand side of the @samp{=>} operator -on the stack is recomputed when we change the precision, then -again when we change to Fraction mode. All @samp{=>} expressions -on the stack are recomputed every time you change any mode that -might affect their values. - -@node Arithmetic Tutorial, Vector/Matrix Tutorial, Basic Tutorial, Tutorial -@section Arithmetic Tutorial - -@noindent -In this section, we explore the arithmetic and scientific functions -available in the Calculator. - -The standard arithmetic commands are @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, -and @kbd{^}. Each normally takes two numbers from the top of the stack -and pushes back a result. The @kbd{n} and @kbd{&} keys perform -change-sign and reciprocal operations, respectively. - -@smallexample -@group -1: 5 1: 0.2 1: 5. 1: -5. 1: 5. - . . . . . - - 5 & & n n -@end group -@end smallexample - -@cindex Binary operators -You can apply a ``binary operator'' like @kbd{+} across any number of -stack entries by giving it a numeric prefix. You can also apply it -pairwise to several stack elements along with the top one if you use -a negative prefix. - -@smallexample -@group -3: 2 1: 9 3: 2 4: 2 3: 12 -2: 3 . 2: 3 3: 3 2: 13 -1: 4 1: 4 2: 4 1: 14 - . . 1: 10 . - . - -2 @key{RET} 3 @key{RET} 4 M-3 + U 10 M-- M-3 + -@end group -@end smallexample - -@cindex Unary operators -You can apply a ``unary operator'' like @kbd{&} to the top @var{n} -stack entries with a numeric prefix, too. - -@smallexample -@group -3: 2 3: 0.5 3: 0.5 -2: 3 2: 0.333333333333 2: 3. -1: 4 1: 0.25 1: 4. - . . . - -2 @key{RET} 3 @key{RET} 4 M-3 & M-2 & -@end group -@end smallexample - -Notice that the results here are left in floating-point form. -We can convert them back to integers by pressing @kbd{F}, the -``floor'' function. This function rounds down to the next lower -integer. There is also @kbd{R}, which rounds to the nearest -integer. - -@smallexample -@group -7: 2. 7: 2 7: 2 -6: 2.4 6: 2 6: 2 -5: 2.5 5: 2 5: 3 -4: 2.6 4: 2 4: 3 -3: -2. 3: -2 3: -2 -2: -2.4 2: -3 2: -2 -1: -2.6 1: -3 1: -3 - . . . - - M-7 F U M-7 R -@end group -@end smallexample - -Since dividing-and-flooring (i.e., ``integer quotient'') is such a -common operation, Calc provides a special command for that purpose, the -backslash @kbd{\}. Another common arithmetic operator is @kbd{%}, which -computes the remainder that would arise from a @kbd{\} operation, i.e., -the ``modulo'' of two numbers. For example, - -@smallexample -@group -2: 1234 1: 12 2: 1234 1: 34 -1: 100 . 1: 100 . - . . - -1234 @key{RET} 100 \ U % -@end group -@end smallexample - -These commands actually work for any real numbers, not just integers. - -@smallexample -@group -2: 3.1415 1: 3 2: 3.1415 1: 0.1415 -1: 1 . 1: 1 . - . . - -3.1415 @key{RET} 1 \ U % -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 1.} The @kbd{\} command would appear to be a -frill, since you could always do the same thing with @kbd{/ F}. Think -of a situation where this is not true---@kbd{/ F} would be inadequate. -Now think of a way you could get around the problem if Calc didn't -provide a @kbd{\} command. @xref{Arithmetic Answer 1, 1}. (@bullet{}) - -We've already seen the @kbd{Q} (square root) and @kbd{S} (sine) -commands. Other commands along those lines are @kbd{C} (cosine), -@kbd{T} (tangent), @kbd{E} (@expr{e^x}) and @kbd{L} (natural -logarithm). These can be modified by the @kbd{I} (inverse) and -@kbd{H} (hyperbolic) prefix keys. - -Let's compute the sine and cosine of an angle, and verify the -identity -@texline @math{\sin^2x + \cos^2x = 1}. -@infoline @expr{sin(x)^2 + cos(x)^2 = 1}. -We'll arbitrarily pick @mathit{-64} degrees as a good value for @expr{x}. -With the angular mode set to degrees (type @w{@kbd{m d}}), do: - -@smallexample -@group -2: -64 2: -64 2: -0.89879 2: -0.89879 1: 1. -1: -64 1: -0.89879 1: -64 1: 0.43837 . - . . . . - - 64 n @key{RET} @key{RET} S @key{TAB} C f h -@end group -@end smallexample - -@noindent -(For brevity, we're showing only five digits of the results here. -You can of course do these calculations to any precision you like.) - -Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum -of squares, command. - -Another identity is -@texline @math{\displaystyle\tan x = {\sin x \over \cos x}}. -@infoline @expr{tan(x) = sin(x) / cos(x)}. -@smallexample -@group - -2: -0.89879 1: -2.0503 1: -64. -1: 0.43837 . . - . - - U / I T -@end group -@end smallexample - -A physical interpretation of this calculation is that if you move -@expr{0.89879} units downward and @expr{0.43837} units to the right, -your direction of motion is @mathit{-64} degrees from horizontal. Suppose -we move in the opposite direction, up and to the left: - -@smallexample -@group -2: -0.89879 2: 0.89879 1: -2.0503 1: -64. -1: 0.43837 1: -0.43837 . . - . . - - U U M-2 n / I T -@end group -@end smallexample - -@noindent -How can the angle be the same? The answer is that the @kbd{/} operation -loses information about the signs of its inputs. Because the quotient -is negative, we know exactly one of the inputs was negative, but we -can't tell which one. There is an @kbd{f T} [@code{arctan2}] function which -computes the inverse tangent of the quotient of a pair of numbers. -Since you feed it the two original numbers, it has enough information -to give you a full 360-degree answer. - -@smallexample -@group -2: 0.89879 1: 116. 3: 116. 2: 116. 1: 180. -1: -0.43837 . 2: -0.89879 1: -64. . - . 1: 0.43837 . - . - - U U f T M-@key{RET} M-2 n f T - -@end group -@end smallexample - -@noindent -The resulting angles differ by 180 degrees; in other words, they -point in opposite directions, just as we would expect. - -The @key{META}-@key{RET} we used in the third step is the -``last-arguments'' command. It is sort of like Undo, except that it -restores the arguments of the last command to the stack without removing -the command's result. It is useful in situations like this one, -where we need to do several operations on the same inputs. We could -have accomplished the same thing by using @kbd{M-2 @key{RET}} to duplicate -the top two stack elements right after the @kbd{U U}, then a pair of -@kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates. - -A similar identity is supposed to hold for hyperbolic sines and cosines, -except that it is the @emph{difference} -@texline @math{\cosh^2x - \sinh^2x} -@infoline @expr{cosh(x)^2 - sinh(x)^2} -that always equals one. Let's try to verify this identity. - -@smallexample -@group -2: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54 -1: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 - . . . . . - - 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^ -@end group -@end smallexample - -@noindent -@cindex Roundoff errors, examples -Something's obviously wrong, because when we subtract these numbers -the answer will clearly be zero! But if you think about it, if these -numbers @emph{did} differ by one, it would be in the 55th decimal -place. The difference we seek has been lost entirely to roundoff -error. - -We could verify this hypothesis by doing the actual calculation with, -say, 60 decimal places of precision. This will be slow, but not -enormously so. Try it if you wish; sure enough, the answer is -0.99999, reasonably close to 1. - -Of course, a more reasonable way to verify the identity is to use -a more reasonable value for @expr{x}! - -@cindex Common logarithm -Some Calculator commands use the Hyperbolic prefix for other purposes. -The logarithm and exponential functions, for example, work to the base -@expr{e} normally but use base-10 instead if you use the Hyperbolic -prefix. - -@smallexample -@group -1: 1000 1: 6.9077 1: 1000 1: 3 - . . . . - - 1000 L U H L -@end group -@end smallexample - -@noindent -First, we mistakenly compute a natural logarithm. Then we undo -and compute a common logarithm instead. - -The @kbd{B} key computes a general base-@var{b} logarithm for any -value of @var{b}. - -@smallexample -@group -2: 1000 1: 3 1: 1000. 2: 1000. 1: 6.9077 -1: 10 . . 1: 2.71828 . - . . - - 1000 @key{RET} 10 B H E H P B -@end group -@end smallexample - -@noindent -Here we first use @kbd{B} to compute the base-10 logarithm, then use -the ``hyperbolic'' exponential as a cheap hack to recover the number -1000, then use @kbd{B} again to compute the natural logarithm. Note -that @kbd{P} with the hyperbolic prefix pushes the constant @expr{e} -onto the stack. - -You may have noticed that both times we took the base-10 logarithm -of 1000, we got an exact integer result. Calc always tries to give -an exact rational result for calculations involving rational numbers -where possible. But when we used @kbd{H E}, the result was a -floating-point number for no apparent reason. In fact, if we had -computed @kbd{10 @key{RET} 3 ^} we @emph{would} have gotten an -exact integer 1000. But the @kbd{H E} command is rigged to generate -a floating-point result all of the time so that @kbd{1000 H E} will -not waste time computing a thousand-digit integer when all you -probably wanted was @samp{1e1000}. - -(@bullet{}) @strong{Exercise 2.} Find a pair of integer inputs to -the @kbd{B} command for which Calc could find an exact rational -result but doesn't. @xref{Arithmetic Answer 2, 2}. (@bullet{}) - -The Calculator also has a set of functions relating to combinatorics -and statistics. You may be familiar with the @dfn{factorial} function, -which computes the product of all the integers up to a given number. - -@smallexample -@group -1: 100 1: 93326215443... 1: 100. 1: 9.3326e157 - . . . . - - 100 ! U c f ! -@end group -@end smallexample - -@noindent -Recall, the @kbd{c f} command converts the integer or fraction at the -top of the stack to floating-point format. If you take the factorial -of a floating-point number, you get a floating-point result -accurate to the current precision. But if you give @kbd{!} an -exact integer, you get an exact integer result (158 digits long -in this case). - -If you take the factorial of a non-integer, Calc uses a generalized -factorial function defined in terms of Euler's Gamma function -@texline @math{\Gamma(n)} -@infoline @expr{gamma(n)} -(which is itself available as the @kbd{f g} command). - -@smallexample -@group -3: 4. 3: 24. 1: 5.5 1: 52.342777847 -2: 4.5 2: 52.3427777847 . . -1: 5. 1: 120. - . . - - M-3 ! M-0 @key{DEL} 5.5 f g -@end group -@end smallexample - -@noindent -Here we verify the identity -@texline @math{n! = \Gamma(n+1)}. -@infoline @expr{@var{n}!@: = gamma(@var{n}+1)}. - -The binomial coefficient @var{n}-choose-@var{m} -@texline or @math{\displaystyle {n \choose m}} -is defined by -@texline @math{\displaystyle {n! \over m! \, (n-m)!}} -@infoline @expr{n!@: / m!@: (n-m)!} -for all reals @expr{n} and @expr{m}. The intermediate results in this -formula can become quite large even if the final result is small; the -@kbd{k c} command computes a binomial coefficient in a way that avoids -large intermediate values. - -The @kbd{k} prefix key defines several common functions out of -combinatorics and number theory. Here we compute the binomial -coefficient 30-choose-20, then determine its prime factorization. - -@smallexample -@group -2: 30 1: 30045015 1: [3, 3, 5, 7, 11, 13, 23, 29] -1: 20 . . - . - - 30 @key{RET} 20 k c k f -@end group -@end smallexample - -@noindent -You can verify these prime factors by using @kbd{V R *} to multiply -together the elements of this vector. The result is the original -number, 30045015. - -@cindex Hash tables -Suppose a program you are writing needs a hash table with at least -10000 entries. It's best to use a prime number as the actual size -of a hash table. Calc can compute the next prime number after 10000: - -@smallexample -@group -1: 10000 1: 10007 1: 9973 - . . . - - 10000 k n I k n -@end group -@end smallexample - -@noindent -Just for kicks we've also computed the next prime @emph{less} than -10000. - -@c [fix-ref Financial Functions] -@xref{Financial Functions}, for a description of the Calculator -commands that deal with business and financial calculations (functions -like @code{pv}, @code{rate}, and @code{sln}). - -@c [fix-ref Binary Number Functions] -@xref{Binary Functions}, to read about the commands for operating -on binary numbers (like @code{and}, @code{xor}, and @code{lsh}). - -@node Vector/Matrix Tutorial, Types Tutorial, Arithmetic Tutorial, Tutorial -@section Vector/Matrix Tutorial - -@noindent -A @dfn{vector} is a list of numbers or other Calc data objects. -Calc provides a large set of commands that operate on vectors. Some -are familiar operations from vector analysis. Others simply treat -a vector as a list of objects. - -@menu -* Vector Analysis Tutorial:: -* Matrix Tutorial:: -* List Tutorial:: -@end menu - -@node Vector Analysis Tutorial, Matrix Tutorial, Vector/Matrix Tutorial, Vector/Matrix Tutorial -@subsection Vector Analysis - -@noindent -If you add two vectors, the result is a vector of the sums of the -elements, taken pairwise. - -@smallexample -@group -1: [1, 2, 3] 2: [1, 2, 3] 1: [8, 8, 3] - . 1: [7, 6, 0] . - . - - [1,2,3] s 1 [7 6 0] s 2 + -@end group -@end smallexample - -@noindent -Note that we can separate the vector elements with either commas or -spaces. This is true whether we are using incomplete vectors or -algebraic entry. The @kbd{s 1} and @kbd{s 2} commands save these -vectors so we can easily reuse them later. - -If you multiply two vectors, the result is the sum of the products -of the elements taken pairwise. This is called the @dfn{dot product} -of the vectors. - -@smallexample -@group -2: [1, 2, 3] 1: 19 -1: [7, 6, 0] . - . - - r 1 r 2 * -@end group -@end smallexample - -@cindex Dot product -The dot product of two vectors is equal to the product of their -lengths times the cosine of the angle between them. (Here the vector -is interpreted as a line from the origin @expr{(0,0,0)} to the -specified point in three-dimensional space.) The @kbd{A} -(absolute value) command can be used to compute the length of a -vector. - -@smallexample -@group -3: 19 3: 19 1: 0.550782 1: 56.579 -2: [1, 2, 3] 2: 3.741657 . . -1: [7, 6, 0] 1: 9.219544 - . . - - M-@key{RET} M-2 A * / I C -@end group -@end smallexample - -@noindent -First we recall the arguments to the dot product command, then -we compute the absolute values of the top two stack entries to -obtain the lengths of the vectors, then we divide the dot product -by the product of the lengths to get the cosine of the angle. -The inverse cosine finds that the angle between the vectors -is about 56 degrees. - -@cindex Cross product -@cindex Perpendicular vectors -The @dfn{cross product} of two vectors is a vector whose length -is the product of the lengths of the inputs times the sine of the -angle between them, and whose direction is perpendicular to both -input vectors. Unlike the dot product, the cross product is -defined only for three-dimensional vectors. Let's double-check -our computation of the angle using the cross product. - -@smallexample -@group -2: [1, 2, 3] 3: [-18, 21, -8] 1: [-0.52, 0.61, -0.23] 1: 56.579 -1: [7, 6, 0] 2: [1, 2, 3] . . - . 1: [7, 6, 0] - . - - r 1 r 2 V C s 3 M-@key{RET} M-2 A * / A I S -@end group -@end smallexample - -@noindent -First we recall the original vectors and compute their cross product, -which we also store for later reference. Now we divide the vector -by the product of the lengths of the original vectors. The length of -this vector should be the sine of the angle; sure enough, it is! - -@c [fix-ref General Mode Commands] -Vector-related commands generally begin with the @kbd{v} prefix key. -Some are uppercase letters and some are lowercase. To make it easier -to type these commands, the shift-@kbd{V} prefix key acts the same as -the @kbd{v} key. (@xref{General Mode Commands}, for a way to make all -prefix keys have this property.) - -If we take the dot product of two perpendicular vectors we expect -to get zero, since the cosine of 90 degrees is zero. Let's check -that the cross product is indeed perpendicular to both inputs: - -@smallexample -@group -2: [1, 2, 3] 1: 0 2: [7, 6, 0] 1: 0 -1: [-18, 21, -8] . 1: [-18, 21, -8] . - . . - - r 1 r 3 * @key{DEL} r 2 r 3 * -@end group -@end smallexample - -@cindex Normalizing a vector -@cindex Unit vectors -(@bullet{}) @strong{Exercise 1.} Given a vector on the top of the -stack, what keystrokes would you use to @dfn{normalize} the -vector, i.e., to reduce its length to one without changing its -direction? @xref{Vector Answer 1, 1}. (@bullet{}) - -(@bullet{}) @strong{Exercise 2.} Suppose a certain particle can be -at any of several positions along a ruler. You have a list of -those positions in the form of a vector, and another list of the -probabilities for the particle to be at the corresponding positions. -Find the average position of the particle. -@xref{Vector Answer 2, 2}. (@bullet{}) - -@node Matrix Tutorial, List Tutorial, Vector Analysis Tutorial, Vector/Matrix Tutorial -@subsection Matrices - -@noindent -A @dfn{matrix} is just a vector of vectors, all the same length. -This means you can enter a matrix using nested brackets. You can -also use the semicolon character to enter a matrix. We'll show -both methods here: - -@smallexample -@group -1: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] - [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] - . . - - [[1 2 3] [4 5 6]] ' [1 2 3; 4 5 6] @key{RET} -@end group -@end smallexample - -@noindent -We'll be using this matrix again, so type @kbd{s 4} to save it now. - -Note that semicolons work with incomplete vectors, but they work -better in algebraic entry. That's why we use the apostrophe in -the second example. - -When two matrices are multiplied, the lefthand matrix must have -the same number of columns as the righthand matrix has rows. -Row @expr{i}, column @expr{j} of the result is effectively the -dot product of row @expr{i} of the left matrix by column @expr{j} -of the right matrix. - -If we try to duplicate this matrix and multiply it by itself, -the dimensions are wrong and the multiplication cannot take place: - -@smallexample -@group -1: [ [ 1, 2, 3 ] * [ [ 1, 2, 3 ] - [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] - . - - @key{RET} * -@end group -@end smallexample - -@noindent -Though rather hard to read, this is a formula which shows the product -of two matrices. The @samp{*} function, having invalid arguments, has -been left in symbolic form. - -We can multiply the matrices if we @dfn{transpose} one of them first. - -@smallexample -@group -2: [ [ 1, 2, 3 ] 1: [ [ 14, 32 ] 1: [ [ 17, 22, 27 ] - [ 4, 5, 6 ] ] [ 32, 77 ] ] [ 22, 29, 36 ] -1: [ [ 1, 4 ] . [ 27, 36, 45 ] ] - [ 2, 5 ] . - [ 3, 6 ] ] - . - - U v t * U @key{TAB} * -@end group -@end smallexample - -Matrix multiplication is not commutative; indeed, switching the -order of the operands can even change the dimensions of the result -matrix, as happened here! - -If you multiply a plain vector by a matrix, it is treated as a -single row or column depending on which side of the matrix it is -on. The result is a plain vector which should also be interpreted -as a row or column as appropriate. - -@smallexample -@group -2: [ [ 1, 2, 3 ] 1: [14, 32] - [ 4, 5, 6 ] ] . -1: [1, 2, 3] - . - - r 4 r 1 * -@end group -@end smallexample - -Multiplying in the other order wouldn't work because the number of -rows in the matrix is different from the number of elements in the -vector. - -(@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows -of the above -@texline @math{2\times3} -@infoline 2x3 -matrix to get @expr{[6, 15]}. Now use @samp{*} to sum along the columns -to get @expr{[5, 7, 9]}. -@xref{Matrix Answer 1, 1}. (@bullet{}) - -@cindex Identity matrix -An @dfn{identity matrix} is a square matrix with ones along the -diagonal and zeros elsewhere. It has the property that multiplication -by an identity matrix, on the left or on the right, always produces -the original matrix. - -@smallexample -@group -1: [ [ 1, 2, 3 ] 2: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] - [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] - . 1: [ [ 1, 0, 0 ] . - [ 0, 1, 0 ] - [ 0, 0, 1 ] ] - . - - r 4 v i 3 @key{RET} * -@end group -@end smallexample - -If a matrix is square, it is often possible to find its @dfn{inverse}, -that is, a matrix which, when multiplied by the original matrix, yields -an identity matrix. The @kbd{&} (reciprocal) key also computes the -inverse of a matrix. - -@smallexample -@group -1: [ [ 1, 2, 3 ] 1: [ [ -2.4, 1.2, -0.2 ] - [ 4, 5, 6 ] [ 2.8, -1.4, 0.4 ] - [ 7, 6, 0 ] ] [ -0.73333, 0.53333, -0.2 ] ] - . . - - r 4 r 2 | s 5 & -@end group -@end smallexample - -@noindent -The vertical bar @kbd{|} @dfn{concatenates} numbers, vectors, and -matrices together. Here we have used it to add a new row onto -our matrix to make it square. - -We can multiply these two matrices in either order to get an identity. - -@smallexample -@group -1: [ [ 1., 0., 0. ] 1: [ [ 1., 0., 0. ] - [ 0., 1., 0. ] [ 0., 1., 0. ] - [ 0., 0., 1. ] ] [ 0., 0., 1. ] ] - . . - - M-@key{RET} * U @key{TAB} * -@end group -@end smallexample - -@cindex Systems of linear equations -@cindex Linear equations, systems of -Matrix inverses are related to systems of linear equations in algebra. -Suppose we had the following set of equations: - -@ifnottex -@group -@example - a + 2b + 3c = 6 - 4a + 5b + 6c = 2 - 7a + 6b = 3 -@end example -@end group -@end ifnottex -@tex -\beforedisplayh -$$ \openup1\jot \tabskip=0pt plus1fil -\halign to\displaywidth{\tabskip=0pt - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr - a&+&2b&+&3c&=6 \cr - 4a&+&5b&+&6c&=2 \cr - 7a&+&6b& & &=3 \cr} -$$ -\afterdisplayh -@end tex - -@noindent -This can be cast into the matrix equation, - -@ifnottex -@group -@example - [ [ 1, 2, 3 ] [ [ a ] [ [ 6 ] - [ 4, 5, 6 ] * [ b ] = [ 2 ] - [ 7, 6, 0 ] ] [ c ] ] [ 3 ] ] -@end example -@end group -@end ifnottex -@tex -\beforedisplay -$$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 } - \times - \pmatrix{ a \cr b \cr c } = \pmatrix{ 6 \cr 2 \cr 3 } -$$ -\afterdisplay -@end tex - -We can solve this system of equations by multiplying both sides by the -inverse of the matrix. Calc can do this all in one step: - -@smallexample -@group -2: [6, 2, 3] 1: [-12.6, 15.2, -3.93333] -1: [ [ 1, 2, 3 ] . - [ 4, 5, 6 ] - [ 7, 6, 0 ] ] - . - - [6,2,3] r 5 / -@end group -@end smallexample - -@noindent -The result is the @expr{[a, b, c]} vector that solves the equations. -(Dividing by a square matrix is equivalent to multiplying by its -inverse.) - -Let's verify this solution: - -@smallexample -@group -2: [ [ 1, 2, 3 ] 1: [6., 2., 3.] - [ 4, 5, 6 ] . - [ 7, 6, 0 ] ] -1: [-12.6, 15.2, -3.93333] - . - - r 5 @key{TAB} * -@end group -@end smallexample - -@noindent -Note that we had to be careful about the order in which we multiplied -the matrix and vector. If we multiplied in the other order, Calc would -assume the vector was a row vector in order to make the dimensions -come out right, and the answer would be incorrect. If you -don't feel safe letting Calc take either interpretation of your -vectors, use explicit -@texline @math{N\times1} -@infoline Nx1 -or -@texline @math{1\times N} -@infoline 1xN -matrices instead. In this case, you would enter the original column -vector as @samp{[[6], [2], [3]]} or @samp{[6; 2; 3]}. - -(@bullet{}) @strong{Exercise 2.} Algebraic entry allows you to make -vectors and matrices that include variables. Solve the following -system of equations to get expressions for @expr{x} and @expr{y} -in terms of @expr{a} and @expr{b}. - -@ifnottex -@group -@example - x + a y = 6 - x + b y = 10 -@end example -@end group -@end ifnottex -@tex -\beforedisplay -$$ \eqalign{ x &+ a y = 6 \cr - x &+ b y = 10} -$$ -\afterdisplay -@end tex - -@noindent -@xref{Matrix Answer 2, 2}. (@bullet{}) - -@cindex Least-squares for over-determined systems -@cindex Over-determined systems of equations -(@bullet{}) @strong{Exercise 3.} A system of equations is ``over-determined'' -if it has more equations than variables. It is often the case that -there are no values for the variables that will satisfy all the -equations at once, but it is still useful to find a set of values -which ``nearly'' satisfy all the equations. In terms of matrix equations, -you can't solve @expr{A X = B} directly because the matrix @expr{A} -is not square for an over-determined system. Matrix inversion works -only for square matrices. One common trick is to multiply both sides -on the left by the transpose of @expr{A}: -@ifnottex -@samp{trn(A)*A*X = trn(A)*B}. -@end ifnottex -@tex -$A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}. -@end tex -Now -@texline @math{A^T A} -@infoline @expr{trn(A)*A} -is a square matrix so a solution is possible. It turns out that the -@expr{X} vector you compute in this way will be a ``least-squares'' -solution, which can be regarded as the ``closest'' solution to the set -of equations. Use Calc to solve the following over-determined -system: - -@ifnottex -@group -@example - a + 2b + 3c = 6 - 4a + 5b + 6c = 2 - 7a + 6b = 3 - 2a + 4b + 6c = 11 -@end example -@end group -@end ifnottex -@tex -\beforedisplayh -$$ \openup1\jot \tabskip=0pt plus1fil -\halign to\displaywidth{\tabskip=0pt - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr - a&+&2b&+&3c&=6 \cr - 4a&+&5b&+&6c&=2 \cr - 7a&+&6b& & &=3 \cr - 2a&+&4b&+&6c&=11 \cr} -$$ -\afterdisplayh -@end tex - -@noindent -@xref{Matrix Answer 3, 3}. (@bullet{}) - -@node List Tutorial, , Matrix Tutorial, Vector/Matrix Tutorial -@subsection Vectors as Lists - -@noindent -@cindex Lists -Although Calc has a number of features for manipulating vectors and -matrices as mathematical objects, you can also treat vectors as -simple lists of values. For example, we saw that the @kbd{k f} -command returns a vector which is a list of the prime factors of a -number. - -You can pack and unpack stack entries into vectors: - -@smallexample -@group -3: 10 1: [10, 20, 30] 3: 10 -2: 20 . 2: 20 -1: 30 1: 30 - . . - - M-3 v p v u -@end group -@end smallexample - -You can also build vectors out of consecutive integers, or out -of many copies of a given value: - -@smallexample -@group -1: [1, 2, 3, 4] 2: [1, 2, 3, 4] 2: [1, 2, 3, 4] - . 1: 17 1: [17, 17, 17, 17] - . . - - v x 4 @key{RET} 17 v b 4 @key{RET} -@end group -@end smallexample - -You can apply an operator to every element of a vector using the -@dfn{map} command. - -@smallexample -@group -1: [17, 34, 51, 68] 1: [289, 1156, 2601, 4624] 1: [17, 34, 51, 68] - . . . - - V M * 2 V M ^ V M Q -@end group -@end smallexample - -@noindent -In the first step, we multiply the vector of integers by the vector -of 17's elementwise. In the second step, we raise each element to -the power two. (The general rule is that both operands must be -vectors of the same length, or else one must be a vector and the -other a plain number.) In the final step, we take the square root -of each element. - -(@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two -from -@texline @math{2^{-4}} -@infoline @expr{2^-4} -to @expr{2^4}. @xref{List Answer 1, 1}. (@bullet{}) - -You can also @dfn{reduce} a binary operator across a vector. -For example, reducing @samp{*} computes the product of all the -elements in the vector: - -@smallexample -@group -1: 123123 1: [3, 7, 11, 13, 41] 1: 123123 - . . . - - 123123 k f V R * -@end group -@end smallexample - -@noindent -In this example, we decompose 123123 into its prime factors, then -multiply those factors together again to yield the original number. - -We could compute a dot product ``by hand'' using mapping and -reduction: - -@smallexample -@group -2: [1, 2, 3] 1: [7, 12, 0] 1: 19 -1: [7, 6, 0] . . - . - - r 1 r 2 V M * V R + -@end group -@end smallexample - -@noindent -Recalling two vectors from the previous section, we compute the -sum of pairwise products of the elements to get the same answer -for the dot product as before. - -A slight variant of vector reduction is the @dfn{accumulate} operation, -@kbd{V U}. This produces a vector of the intermediate results from -a corresponding reduction. Here we compute a table of factorials: - -@smallexample -@group -1: [1, 2, 3, 4, 5, 6] 1: [1, 2, 6, 24, 120, 720] - . . - - v x 6 @key{RET} V U * -@end group -@end smallexample - -Calc allows vectors to grow as large as you like, although it gets -rather slow if vectors have more than about a hundred elements. -Actually, most of the time is spent formatting these large vectors -for display, not calculating on them. Try the following experiment -(if your computer is very fast you may need to substitute a larger -vector size). - -@smallexample -@group -1: [1, 2, 3, 4, ... 1: [2, 3, 4, 5, ... - . . - - v x 500 @key{RET} 1 V M + -@end group -@end smallexample - -Now press @kbd{v .} (the letter @kbd{v}, then a period) and try the -experiment again. In @kbd{v .} mode, long vectors are displayed -``abbreviated'' like this: - -@smallexample -@group -1: [1, 2, 3, ..., 500] 1: [2, 3, 4, ..., 501] - . . - - v x 500 @key{RET} 1 V M + -@end group -@end smallexample - -@noindent -(where now the @samp{...} is actually part of the Calc display). -You will find both operations are now much faster. But notice that -even in @w{@kbd{v .}} mode, the full vectors are still shown in the Trail. -Type @w{@kbd{t .}} to cause the trail to abbreviate as well, and try the -experiment one more time. Operations on long vectors are now quite -fast! (But of course if you use @kbd{t .} you will lose the ability -to get old vectors back using the @kbd{t y} command.) - -An easy way to view a full vector when @kbd{v .} mode is active is -to press @kbd{`} (back-quote) to edit the vector; editing always works -with the full, unabbreviated value. - -@cindex Least-squares for fitting a straight line -@cindex Fitting data to a line -@cindex Line, fitting data to -@cindex Data, extracting from buffers -@cindex Columns of data, extracting -As a larger example, let's try to fit a straight line to some data, -using the method of least squares. (Calc has a built-in command for -least-squares curve fitting, but we'll do it by hand here just to -practice working with vectors.) Suppose we have the following list -of values in a file we have loaded into Emacs: - -@smallexample - x y - --- --- - 1.34 0.234 - 1.41 0.298 - 1.49 0.402 - 1.56 0.412 - 1.64 0.466 - 1.73 0.473 - 1.82 0.601 - 1.91 0.519 - 2.01 0.603 - 2.11 0.637 - 2.22 0.645 - 2.33 0.705 - 2.45 0.917 - 2.58 1.009 - 2.71 0.971 - 2.85 1.062 - 3.00 1.148 - 3.15 1.157 - 3.32 1.354 -@end smallexample - -@noindent -If you are reading this tutorial in printed form, you will find it -easiest to press @kbd{C-x * i} to enter the on-line Info version of -the manual and find this table there. (Press @kbd{g}, then type -@kbd{List Tutorial}, to jump straight to this section.) - -Position the cursor at the upper-left corner of this table, just -to the left of the @expr{1.34}. Press @kbd{C-@@} to set the mark. -(On your system this may be @kbd{C-2}, @kbd{C-@key{SPC}}, or @kbd{NUL}.) -Now position the cursor to the lower-right, just after the @expr{1.354}. -You have now defined this region as an Emacs ``rectangle.'' Still -in the Info buffer, type @kbd{C-x * r}. This command -(@code{calc-grab-rectangle}) will pop you back into the Calculator, with -the contents of the rectangle you specified in the form of a matrix. - -@smallexample -@group -1: [ [ 1.34, 0.234 ] - [ 1.41, 0.298 ] - @dots{} -@end group -@end smallexample - -@noindent -(You may wish to use @kbd{v .} mode to abbreviate the display of this -large matrix.) - -We want to treat this as a pair of lists. The first step is to -transpose this matrix into a pair of rows. Remember, a matrix is -just a vector of vectors. So we can unpack the matrix into a pair -of row vectors on the stack. - -@smallexample -@group -1: [ [ 1.34, 1.41, 1.49, ... ] 2: [1.34, 1.41, 1.49, ... ] - [ 0.234, 0.298, 0.402, ... ] ] 1: [0.234, 0.298, 0.402, ... ] - . . - - v t v u -@end group -@end smallexample - -@noindent -Let's store these in quick variables 1 and 2, respectively. - -@smallexample -@group -1: [1.34, 1.41, 1.49, ... ] . - . - - t 2 t 1 -@end group -@end smallexample - -@noindent -(Recall that @kbd{t 2} is a variant of @kbd{s 2} that removes the -stored value from the stack.) - -In a least squares fit, the slope @expr{m} is given by the formula - -@ifnottex -@example -m = (N sum(x y) - sum(x) sum(y)) / (N sum(x^2) - sum(x)^2) -@end example -@end ifnottex -@tex -\beforedisplay -$$ m = {N \sum x y - \sum x \sum y \over - N \sum x^2 - \left( \sum x \right)^2} $$ -\afterdisplay -@end tex - -@noindent -where -@texline @math{\sum x} -@infoline @expr{sum(x)} -represents the sum of all the values of @expr{x}. While there is an -actual @code{sum} function in Calc, it's easier to sum a vector using a -simple reduction. First, let's compute the four different sums that -this formula uses. - -@smallexample -@group -1: 41.63 1: 98.0003 - . . - - r 1 V R + t 3 r 1 2 V M ^ V R + t 4 - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 13.613 1: 33.36554 - . . - - r 2 V R + t 5 r 1 r 2 V M * V R + t 6 -@end group -@end smallexample - -@ifnottex -@noindent -These are @samp{sum(x)}, @samp{sum(x^2)}, @samp{sum(y)}, and @samp{sum(x y)}, -respectively. (We could have used @kbd{*} to compute @samp{sum(x^2)} and -@samp{sum(x y)}.) -@end ifnottex -@tex -These are $\sum x$, $\sum x^2$, $\sum y$, and $\sum x y$, -respectively. (We could have used \kbd{*} to compute $\sum x^2$ and -$\sum x y$.) -@end tex - -Finally, we also need @expr{N}, the number of data points. This is just -the length of either of our lists. - -@smallexample -@group -1: 19 - . - - r 1 v l t 7 -@end group -@end smallexample - -@noindent -(That's @kbd{v} followed by a lower-case @kbd{l}.) - -Now we grind through the formula: - -@smallexample -@group -1: 633.94526 2: 633.94526 1: 67.23607 - . 1: 566.70919 . - . - - r 7 r 6 * r 3 r 5 * - - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 67.23607 3: 67.23607 2: 67.23607 1: 0.52141679 -1: 1862.0057 2: 1862.0057 1: 128.9488 . - . 1: 1733.0569 . - . - - r 7 r 4 * r 3 2 ^ - / t 8 -@end group -@end smallexample - -That gives us the slope @expr{m}. The y-intercept @expr{b} can now -be found with the simple formula, - -@ifnottex -@example -b = (sum(y) - m sum(x)) / N -@end example -@end ifnottex -@tex -\beforedisplay -$$ b = {\sum y - m \sum x \over N} $$ -\afterdisplay -\vskip10pt -@end tex - -@smallexample -@group -1: 13.613 2: 13.613 1: -8.09358 1: -0.425978 - . 1: 21.70658 . . - . - - r 5 r 8 r 3 * - r 7 / t 9 -@end group -@end smallexample - -Let's ``plot'' this straight line approximation, -@texline @math{y \approx m x + b}, -@infoline @expr{m x + b}, -and compare it with the original data. - -@smallexample -@group -1: [0.699, 0.735, ... ] 1: [0.273, 0.309, ... ] - . . - - r 1 r 8 * r 9 + s 0 -@end group -@end smallexample - -@noindent -Notice that multiplying a vector by a constant, and adding a constant -to a vector, can be done without mapping commands since these are -common operations from vector algebra. As far as Calc is concerned, -we've just been doing geometry in 19-dimensional space! - -We can subtract this vector from our original @expr{y} vector to get -a feel for the error of our fit. Let's find the maximum error: - -@smallexample -@group -1: [0.0387, 0.0112, ... ] 1: [0.0387, 0.0112, ... ] 1: 0.0897 - . . . - - r 2 - V M A V R X -@end group -@end smallexample - -@noindent -First we compute a vector of differences, then we take the absolute -values of these differences, then we reduce the @code{max} function -across the vector. (The @code{max} function is on the two-key sequence -@kbd{f x}; because it is so common to use @code{max} in a vector -operation, the letters @kbd{X} and @kbd{N} are also accepted for -@code{max} and @code{min} in this context. In general, you answer -the @kbd{V M} or @kbd{V R} prompt with the actual key sequence that -invokes the function you want. You could have typed @kbd{V R f x} or -even @kbd{V R x max @key{RET}} if you had preferred.) - -If your system has the GNUPLOT program, you can see graphs of your -data and your straight line to see how well they match. (If you have -GNUPLOT 3.0 or higher, the following instructions will work regardless -of the kind of display you have. Some GNUPLOT 2.0, non-X-windows systems -may require additional steps to view the graphs.) - -Let's start by plotting the original data. Recall the ``@var{x}'' and ``@var{y}'' -vectors onto the stack and press @kbd{g f}. This ``fast'' graphing -command does everything you need to do for simple, straightforward -plotting of data. - -@smallexample -@group -2: [1.34, 1.41, 1.49, ... ] -1: [0.234, 0.298, 0.402, ... ] - . - - r 1 r 2 g f -@end group -@end smallexample - -If all goes well, you will shortly get a new window containing a graph -of the data. (If not, contact your GNUPLOT or Calc installer to find -out what went wrong.) In the X window system, this will be a separate -graphics window. For other kinds of displays, the default is to -display the graph in Emacs itself using rough character graphics. -Press @kbd{q} when you are done viewing the character graphics. - -Next, let's add the line we got from our least-squares fit. -@ifinfo -(If you are reading this tutorial on-line while running Calc, typing -@kbd{g a} may cause the tutorial to disappear from its window and be -replaced by a buffer named @file{*Gnuplot Commands*}. The tutorial -will reappear when you terminate GNUPLOT by typing @kbd{g q}.) -@end ifinfo - -@smallexample -@group -2: [1.34, 1.41, 1.49, ... ] -1: [0.273, 0.309, 0.351, ... ] - . - - @key{DEL} r 0 g a g p -@end group -@end smallexample - -It's not very useful to get symbols to mark the data points on this -second curve; you can type @kbd{g S g p} to remove them. Type @kbd{g q} -when you are done to remove the X graphics window and terminate GNUPLOT. - -(@bullet{}) @strong{Exercise 2.} An earlier exercise showed how to do -least squares fitting to a general system of equations. Our 19 data -points are really 19 equations of the form @expr{y_i = m x_i + b} for -different pairs of @expr{(x_i,y_i)}. Use the matrix-transpose method -to solve for @expr{m} and @expr{b}, duplicating the above result. -@xref{List Answer 2, 2}. (@bullet{}) - -@cindex Geometric mean -(@bullet{}) @strong{Exercise 3.} If the input data do not form a -rectangle, you can use @w{@kbd{C-x * g}} (@code{calc-grab-region}) -to grab the data the way Emacs normally works with regions---it reads -left-to-right, top-to-bottom, treating line breaks the same as spaces. -Use this command to find the geometric mean of the following numbers. -(The geometric mean is the @var{n}th root of the product of @var{n} numbers.) - -@example -2.3 6 22 15.1 7 - 15 14 7.5 - 2.5 -@end example - -@noindent -The @kbd{C-x * g} command accepts numbers separated by spaces or commas, -with or without surrounding vector brackets. -@xref{List Answer 3, 3}. (@bullet{}) - -@ifnottex -As another example, a theorem about binomial coefficients tells -us that the alternating sum of binomial coefficients -@var{n}-choose-0 minus @var{n}-choose-1 plus @var{n}-choose-2, and so -on up to @var{n}-choose-@var{n}, -always comes out to zero. Let's verify this -for @expr{n=6}. -@end ifnottex -@tex -As another example, a theorem about binomial coefficients tells -us that the alternating sum of binomial coefficients -${n \choose 0} - {n \choose 1} + {n \choose 2} - \cdots \pm {n \choose n}$ -always comes out to zero. Let's verify this -for \cite{n=6}. -@end tex - -@smallexample -@group -1: [1, 2, 3, 4, 5, 6, 7] 1: [0, 1, 2, 3, 4, 5, 6] - . . - - v x 7 @key{RET} 1 - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, -6, 15, -20, 15, -6, 1] 1: 0 - . . - - V M ' (-1)^$ choose(6,$) @key{RET} V R + -@end group -@end smallexample - -The @kbd{V M '} command prompts you to enter any algebraic expression -to define the function to map over the vector. The symbol @samp{$} -inside this expression represents the argument to the function. -The Calculator applies this formula to each element of the vector, -substituting each element's value for the @samp{$} sign(s) in turn. - -To define a two-argument function, use @samp{$$} for the first -argument and @samp{$} for the second: @kbd{V M ' $$-$ @key{RET}} is -equivalent to @kbd{V M -}. This is analogous to regular algebraic -entry, where @samp{$$} would refer to the next-to-top stack entry -and @samp{$} would refer to the top stack entry, and @kbd{' $$-$ @key{RET}} -would act exactly like @kbd{-}. - -Notice that the @kbd{V M '} command has recorded two things in the -trail: The result, as usual, and also a funny-looking thing marked -@samp{oper} that represents the operator function you typed in. -The function is enclosed in @samp{< >} brackets, and the argument is -denoted by a @samp{#} sign. If there were several arguments, they -would be shown as @samp{#1}, @samp{#2}, and so on. (For example, -@kbd{V M ' $$-$} will put the function @samp{<#1 - #2>} on the -trail.) This object is a ``nameless function''; you can use nameless -@w{@samp{< >}} notation to answer the @kbd{V M '} prompt if you like. -Nameless function notation has the interesting, occasionally useful -property that a nameless function is not actually evaluated until -it is used. For example, @kbd{V M ' $+random(2.0)} evaluates -@samp{random(2.0)} once and adds that random number to all elements -of the vector, but @kbd{V M ' <#+random(2.0)>} evaluates the -@samp{random(2.0)} separately for each vector element. - -Another group of operators that are often useful with @kbd{V M} are -the relational operators: @kbd{a =}, for example, compares two numbers -and gives the result 1 if they are equal, or 0 if not. Similarly, -@w{@kbd{a <}} checks for one number being less than another. - -Other useful vector operations include @kbd{v v}, to reverse a -vector end-for-end; @kbd{V S}, to sort the elements of a vector -into increasing order; and @kbd{v r} and @w{@kbd{v c}}, to extract -one row or column of a matrix, or (in both cases) to extract one -element of a plain vector. With a negative argument, @kbd{v r} -and @kbd{v c} instead delete one row, column, or vector element. - -@cindex Divisor functions -(@bullet{}) @strong{Exercise 4.} The @expr{k}th @dfn{divisor function} -@tex -$\sigma_k(n)$ -@end tex -is the sum of the @expr{k}th powers of all the divisors of an -integer @expr{n}. Figure out a method for computing the divisor -function for reasonably small values of @expr{n}. As a test, -the 0th and 1st divisor functions of 30 are 8 and 72, respectively. -@xref{List Answer 4, 4}. (@bullet{}) - -@cindex Square-free numbers -@cindex Duplicate values in a list -(@bullet{}) @strong{Exercise 5.} The @kbd{k f} command produces a -list of prime factors for a number. Sometimes it is important to -know that a number is @dfn{square-free}, i.e., that no prime occurs -more than once in its list of prime factors. Find a sequence of -keystrokes to tell if a number is square-free; your method should -leave 1 on the stack if it is, or 0 if it isn't. -@xref{List Answer 5, 5}. (@bullet{}) - -@cindex Triangular lists -(@bullet{}) @strong{Exercise 6.} Build a list of lists that looks -like the following diagram. (You may wish to use the @kbd{v /} -command to enable multi-line display of vectors.) - -@smallexample -@group -1: [ [1], - [1, 2], - [1, 2, 3], - [1, 2, 3, 4], - [1, 2, 3, 4, 5], - [1, 2, 3, 4, 5, 6] ] -@end group -@end smallexample - -@noindent -@xref{List Answer 6, 6}. (@bullet{}) - -(@bullet{}) @strong{Exercise 7.} Build the following list of lists. - -@smallexample -@group -1: [ [0], - [1, 2], - [3, 4, 5], - [6, 7, 8, 9], - [10, 11, 12, 13, 14], - [15, 16, 17, 18, 19, 20] ] -@end group -@end smallexample - -@noindent -@xref{List Answer 7, 7}. (@bullet{}) - -@cindex Maximizing a function over a list of values -@c [fix-ref Numerical Solutions] -(@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's -@texline @math{J_1(x)} -@infoline @expr{J1} -function @samp{besJ(1,x)} for @expr{x} from 0 to 5 in steps of 0.25. -Find the value of @expr{x} (from among the above set of values) for -which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method, -i.e., just reading along the list by hand to find the largest value -is not allowed! (There is an @kbd{a X} command which does this kind -of thing automatically; @pxref{Numerical Solutions}.) -@xref{List Answer 8, 8}. (@bullet{}) - -@cindex Digits, vectors of -(@bullet{}) @strong{Exercise 9.} You are given an integer in the range -@texline @math{0 \le N < 10^m} -@infoline @expr{0 <= N < 10^m} -for @expr{m=12} (i.e., an integer of less than -twelve digits). Convert this integer into a vector of @expr{m} -digits, each in the range from 0 to 9. In vector-of-digits notation, -add one to this integer to produce a vector of @expr{m+1} digits -(since there could be a carry out of the most significant digit). -Convert this vector back into a regular integer. A good integer -to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{}) - -(@bullet{}) @strong{Exercise 10.} Your friend Joe tried to use -@kbd{V R a =} to test if all numbers in a list were equal. What -happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{}) - -(@bullet{}) @strong{Exercise 11.} The area of a circle of radius one -is @cpi{}. The area of the -@texline @math{2\times2} -@infoline 2x2 -square that encloses that circle is 4. So if we throw @var{n} darts at -random points in the square, about @cpiover{4} of them will land inside -the circle. This gives us an entertaining way to estimate the value of -@cpi{}. The @w{@kbd{k r}} -command picks a random number between zero and the value on the stack. -We could get a random floating-point number between @mathit{-1} and 1 by typing -@w{@kbd{2.0 k r 1 -}}. Build a vector of 100 random @expr{(x,y)} points in -this square, then use vector mapping and reduction to count how many -points lie inside the unit circle. Hint: Use the @kbd{v b} command. -@xref{List Answer 11, 11}. (@bullet{}) - -@cindex Matchstick problem -(@bullet{}) @strong{Exercise 12.} The @dfn{matchstick problem} provides -another way to calculate @cpi{}. Say you have an infinite field -of vertical lines with a spacing of one inch. Toss a one-inch matchstick -onto the field. The probability that the matchstick will land crossing -a line turns out to be -@texline @math{2/\pi}. -@infoline @expr{2/pi}. -Toss 100 matchsticks to estimate @cpi{}. (If you want still more fun, -the probability that the GCD (@w{@kbd{k g}}) of two large integers is -one turns out to be -@texline @math{6/\pi^2}. -@infoline @expr{6/pi^2}. -That provides yet another way to estimate @cpi{}.) -@xref{List Answer 12, 12}. (@bullet{}) - -(@bullet{}) @strong{Exercise 13.} An algebraic entry of a string in -double-quote marks, @samp{"hello"}, creates a vector of the numerical -(ASCII) codes of the characters (here, @expr{[104, 101, 108, 108, 111]}). -Sometimes it is convenient to compute a @dfn{hash code} of a string, -which is just an integer that represents the value of that string. -Two equal strings have the same hash code; two different strings -@dfn{probably} have different hash codes. (For example, Calc has -over 400 function names, but Emacs can quickly find the definition for -any given name because it has sorted the functions into ``buckets'' by -their hash codes. Sometimes a few names will hash into the same bucket, -but it is easier to search among a few names than among all the names.) -One popular hash function is computed as follows: First set @expr{h = 0}. -Then, for each character from the string in turn, set @expr{h = 3h + c_i} -where @expr{c_i} is the character's ASCII code. If we have 511 buckets, -we then take the hash code modulo 511 to get the bucket number. Develop a -simple command or commands for converting string vectors into hash codes. -The hash code for @samp{"Testing, 1, 2, 3"} is 1960915098, which modulo -511 is 121. @xref{List Answer 13, 13}. (@bullet{}) - -(@bullet{}) @strong{Exercise 14.} The @kbd{H V R} and @kbd{H V U} -commands do nested function evaluations. @kbd{H V U} takes a starting -value and a number of steps @var{n} from the stack; it then applies the -function you give to the starting value 0, 1, 2, up to @var{n} times -and returns a vector of the results. Use this command to create a -``random walk'' of 50 steps. Start with the two-dimensional point -@expr{(0,0)}; then take one step a random distance between @mathit{-1} and 1 -in both @expr{x} and @expr{y}; then take another step, and so on. Use the -@kbd{g f} command to display this random walk. Now modify your random -walk to walk a unit distance, but in a random direction, at each step. -(Hint: The @code{sincos} function returns a vector of the cosine and -sine of an angle.) @xref{List Answer 14, 14}. (@bullet{}) - -@node Types Tutorial, Algebra Tutorial, Vector/Matrix Tutorial, Tutorial -@section Types Tutorial - -@noindent -Calc understands a variety of data types as well as simple numbers. -In this section, we'll experiment with each of these types in turn. - -The numbers we've been using so far have mainly been either @dfn{integers} -or @dfn{floats}. We saw that floats are usually a good approximation to -the mathematical concept of real numbers, but they are only approximations -and are susceptible to roundoff error. Calc also supports @dfn{fractions}, -which can exactly represent any rational number. - -@smallexample -@group -1: 3628800 2: 3628800 1: 518400:7 1: 518414:7 1: 7:518414 - . 1: 49 . . . - . - - 10 ! 49 @key{RET} : 2 + & -@end group -@end smallexample - -@noindent -The @kbd{:} command divides two integers to get a fraction; @kbd{/} -would normally divide integers to get a floating-point result. -Notice we had to type @key{RET} between the @kbd{49} and the @kbd{:} -since the @kbd{:} would otherwise be interpreted as part of a -fraction beginning with 49. - -You can convert between floating-point and fractional format using -@kbd{c f} and @kbd{c F}: - -@smallexample -@group -1: 1.35027217629e-5 1: 7:518414 - . . - - c f c F -@end group -@end smallexample - -The @kbd{c F} command replaces a floating-point number with the -``simplest'' fraction whose floating-point representation is the -same, to within the current precision. - -@smallexample -@group -1: 3.14159265359 1: 1146408:364913 1: 3.1416 1: 355:113 - . . . . - - P c F @key{DEL} p 5 @key{RET} P c F -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 1.} A calculation has produced the -result 1.26508260337. You suspect it is the square root of the -product of @cpi{} and some rational number. Is it? (Be sure -to allow for roundoff error!) @xref{Types Answer 1, 1}. (@bullet{}) - -@dfn{Complex numbers} can be stored in both rectangular and polar form. - -@smallexample -@group -1: -9 1: (0, 3) 1: (3; 90.) 1: (6; 90.) 1: (2.4495; 45.) - . . . . . - - 9 n Q c p 2 * Q -@end group -@end smallexample - -@noindent -The square root of @mathit{-9} is by default rendered in rectangular form -(@w{@expr{0 + 3i}}), but we can convert it to polar form (3 with a -phase angle of 90 degrees). All the usual arithmetic and scientific -operations are defined on both types of complex numbers. - -Another generalized kind of number is @dfn{infinity}. Infinity -isn't really a number, but it can sometimes be treated like one. -Calc uses the symbol @code{inf} to represent positive infinity, -i.e., a value greater than any real number. Naturally, you can -also write @samp{-inf} for minus infinity, a value less than any -real number. The word @code{inf} can only be input using -algebraic entry. - -@smallexample -@group -2: inf 2: -inf 2: -inf 2: -inf 1: nan -1: -17 1: -inf 1: -inf 1: inf . - . . . . - -' inf @key{RET} 17 n * @key{RET} 72 + A + -@end group -@end smallexample - -@noindent -Since infinity is infinitely large, multiplying it by any finite -number (like @mathit{-17}) has no effect, except that since @mathit{-17} -is negative, it changes a plus infinity to a minus infinity. -(``A huge positive number, multiplied by @mathit{-17}, yields a huge -negative number.'') Adding any finite number to infinity also -leaves it unchanged. Taking an absolute value gives us plus -infinity again. Finally, we add this plus infinity to the minus -infinity we had earlier. If you work it out, you might expect -the answer to be @mathit{-72} for this. But the 72 has been completely -lost next to the infinities; by the time we compute @w{@samp{inf - inf}} -the finite difference between them, if any, is undetectable. -So we say the result is @dfn{indeterminate}, which Calc writes -with the symbol @code{nan} (for Not A Number). - -Dividing by zero is normally treated as an error, but you can get -Calc to write an answer in terms of infinity by pressing @kbd{m i} -to turn on Infinite mode. - -@smallexample -@group -3: nan 2: nan 2: nan 2: nan 1: nan -2: 1 1: 1 / 0 1: uinf 1: uinf . -1: 0 . . . - . - - 1 @key{RET} 0 / m i U / 17 n * + -@end group -@end smallexample - -@noindent -Dividing by zero normally is left unevaluated, but after @kbd{m i} -it instead gives an infinite result. The answer is actually -@code{uinf}, ``undirected infinity.'' If you look at a graph of -@expr{1 / x} around @w{@expr{x = 0}}, you'll see that it goes toward -plus infinity as you approach zero from above, but toward minus -infinity as you approach from below. Since we said only @expr{1 / 0}, -Calc knows that the answer is infinite but not in which direction. -That's what @code{uinf} means. Notice that multiplying @code{uinf} -by a negative number still leaves plain @code{uinf}; there's no -point in saying @samp{-uinf} because the sign of @code{uinf} is -unknown anyway. Finally, we add @code{uinf} to our @code{nan}, -yielding @code{nan} again. It's easy to see that, because -@code{nan} means ``totally unknown'' while @code{uinf} means -``unknown sign but known to be infinite,'' the more mysterious -@code{nan} wins out when it is combined with @code{uinf}, or, for -that matter, with anything else. - -(@bullet{}) @strong{Exercise 2.} Predict what Calc will answer -for each of these formulas: @samp{inf / inf}, @samp{exp(inf)}, -@samp{exp(-inf)}, @samp{sqrt(-inf)}, @samp{sqrt(uinf)}, -@samp{abs(uinf)}, @samp{ln(0)}. -@xref{Types Answer 2, 2}. (@bullet{}) - -(@bullet{}) @strong{Exercise 3.} We saw that @samp{inf - inf = nan}, -which stands for an unknown value. Can @code{nan} stand for -a complex number? Can it stand for infinity? -@xref{Types Answer 3, 3}. (@bullet{}) - -@dfn{HMS forms} represent a value in terms of hours, minutes, and -seconds. - -@smallexample -@group -1: 2@@ 30' 0" 1: 3@@ 30' 0" 2: 3@@ 30' 0" 1: 2. - . . 1: 1@@ 45' 0." . - . - - 2@@ 30' @key{RET} 1 + @key{RET} 2 / / -@end group -@end smallexample - -HMS forms can also be used to hold angles in degrees, minutes, and -seconds. - -@smallexample -@group -1: 0.5 1: 26.56505 1: 26@@ 33' 54.18" 1: 0.44721 - . . . . - - 0.5 I T c h S -@end group -@end smallexample - -@noindent -First we convert the inverse tangent of 0.5 to degrees-minutes-seconds -form, then we take the sine of that angle. Note that the trigonometric -functions will accept HMS forms directly as input. - -@cindex Beatles -(@bullet{}) @strong{Exercise 4.} The Beatles' @emph{Abbey Road} is -47 minutes and 26 seconds long, and contains 17 songs. What is the -average length of a song on @emph{Abbey Road}? If the Extended Disco -Version of @emph{Abbey Road} added 20 seconds to the length of each -song, how long would the album be? @xref{Types Answer 4, 4}. (@bullet{}) - -A @dfn{date form} represents a date, or a date and time. Dates must -be entered using algebraic entry. Date forms are surrounded by -@samp{< >} symbols; most standard formats for dates are recognized. - -@smallexample -@group -2: 1: 2.25 -1: <6:00pm Thu Jan 10, 1991> . - . - -' <13 Jan 1991>, <1/10/91, 6pm> @key{RET} - -@end group -@end smallexample - -@noindent -In this example, we enter two dates, then subtract to find the -number of days between them. It is also possible to add an -HMS form or a number (of days) to a date form to get another -date form. - -@smallexample -@group -1: <4:45:59pm Mon Jan 14, 1991> 1: <2:50:59am Thu Jan 17, 1991> - . . - - t N 2 + 10@@ 5' + -@end group -@end smallexample - -@c [fix-ref Date Arithmetic] -@noindent -The @kbd{t N} (``now'') command pushes the current date and time on the -stack; then we add two days, ten hours and five minutes to the date and -time. Other date-and-time related commands include @kbd{t J}, which -does Julian day conversions, @kbd{t W}, which finds the beginning of -the week in which a date form lies, and @kbd{t I}, which increments a -date by one or several months. @xref{Date Arithmetic}, for more. - -(@bullet{}) @strong{Exercise 5.} How many days until the next -Friday the 13th? @xref{Types Answer 5, 5}. (@bullet{}) - -(@bullet{}) @strong{Exercise 6.} How many leap years will there be -between now and the year 10001 AD@? @xref{Types Answer 6, 6}. (@bullet{}) - -@cindex Slope and angle of a line -@cindex Angle and slope of a line -An @dfn{error form} represents a mean value with an attached standard -deviation, or error estimate. Suppose our measurements indicate that -a certain telephone pole is about 30 meters away, with an estimated -error of 1 meter, and 8 meters tall, with an estimated error of 0.2 -meters. What is the slope of a line from here to the top of the -pole, and what is the equivalent angle in degrees? - -@smallexample -@group -1: 8 +/- 0.2 2: 8 +/- 0.2 1: 0.266 +/- 0.011 1: 14.93 +/- 0.594 - . 1: 30 +/- 1 . . - . - - 8 p .2 @key{RET} 30 p 1 / I T -@end group -@end smallexample - -@noindent -This means that the angle is about 15 degrees, and, assuming our -original error estimates were valid standard deviations, there is about -a 60% chance that the result is correct within 0.59 degrees. - -@cindex Torus, volume of -(@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is -@texline @math{2 \pi^2 R r^2} -@infoline @w{@expr{2 pi^2 R r^2}} -where @expr{R} is the radius of the circle that -defines the center of the tube and @expr{r} is the radius of the tube -itself. Suppose @expr{R} is 20 cm and @expr{r} is 4 cm, each known to -within 5 percent. What is the volume and the relative uncertainty of -the volume? @xref{Types Answer 7, 7}. (@bullet{}) - -An @dfn{interval form} represents a range of values. While an -error form is best for making statistical estimates, intervals give -you exact bounds on an answer. Suppose we additionally know that -our telephone pole is definitely between 28 and 31 meters away, -and that it is between 7.7 and 8.1 meters tall. - -@smallexample -@group -1: [7.7 .. 8.1] 2: [7.7 .. 8.1] 1: [0.24 .. 0.28] 1: [13.9 .. 16.1] - . 1: [28 .. 31] . . - . - - [ 7.7 .. 8.1 ] [ 28 .. 31 ] / I T -@end group -@end smallexample - -@noindent -If our bounds were correct, then the angle to the top of the pole -is sure to lie in the range shown. - -The square brackets around these intervals indicate that the endpoints -themselves are allowable values. In other words, the distance to the -telephone pole is between 28 and 31, @emph{inclusive}. You can also -make an interval that is exclusive of its endpoints by writing -parentheses instead of square brackets. You can even make an interval -which is inclusive (``closed'') on one end and exclusive (``open'') on -the other. - -@smallexample -@group -1: [1 .. 10) 1: (0.1 .. 1] 2: (0.1 .. 1] 1: (0.2 .. 3) - . . 1: [2 .. 3) . - . - - [ 1 .. 10 ) & [ 2 .. 3 ) * -@end group -@end smallexample - -@noindent -The Calculator automatically keeps track of which end values should -be open and which should be closed. You can also make infinite or -semi-infinite intervals by using @samp{-inf} or @samp{inf} for one -or both endpoints. - -(@bullet{}) @strong{Exercise 8.} What answer would you expect from -@samp{@w{1 /} @w{(0 .. 10)}}? What about @samp{@w{1 /} @w{(-10 .. 0)}}? What -about @samp{@w{1 /} @w{[0 .. 10]}} (where the interval actually includes -zero)? What about @samp{@w{1 /} @w{(-10 .. 10)}}? -@xref{Types Answer 8, 8}. (@bullet{}) - -(@bullet{}) @strong{Exercise 9.} Two easy ways of squaring a number -are @kbd{@key{RET} *} and @w{@kbd{2 ^}}. Normally these produce the same -answer. Would you expect this still to hold true for interval forms? -If not, which of these will result in a larger interval? -@xref{Types Answer 9, 9}. (@bullet{}) - -A @dfn{modulo form} is used for performing arithmetic modulo @var{m}. -For example, arithmetic involving time is generally done modulo 12 -or 24 hours. - -@smallexample -@group -1: 17 mod 24 1: 3 mod 24 1: 21 mod 24 1: 9 mod 24 - . . . . - - 17 M 24 @key{RET} 10 + n 5 / -@end group -@end smallexample - -@noindent -In this last step, Calc has divided by 5 modulo 24; i.e., it has found a -new number which, when multiplied by 5 modulo 24, produces the original -number, 21. If @var{m} is prime and the divisor is not a multiple of -@var{m}, it is always possible to find such a number. For non-prime -@var{m} like 24, it is only sometimes possible. - -@smallexample -@group -1: 10 mod 24 1: 16 mod 24 1: 1000000... 1: 16 - . . . . - - 10 M 24 @key{RET} 100 ^ 10 @key{RET} 100 ^ 24 % -@end group -@end smallexample - -@noindent -These two calculations get the same answer, but the first one is -much more efficient because it avoids the huge intermediate value -that arises in the second one. - -@cindex Fermat, primality test of -(@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat -says that -@texline @math{x^{n-1} \bmod n = 1} -@infoline @expr{x^(n-1) mod n = 1} -if @expr{n} is a prime number and @expr{x} is an integer less than -@expr{n}. If @expr{n} is @emph{not} a prime number, this will -@emph{not} be true for most values of @expr{x}. Thus we can test -informally if a number is prime by trying this formula for several -values of @expr{x}. Use this test to tell whether the following numbers -are prime: 811749613, 15485863. @xref{Types Answer 10, 10}. (@bullet{}) - -It is possible to use HMS forms as parts of error forms, intervals, -modulo forms, or as the phase part of a polar complex number. -For example, the @code{calc-time} command pushes the current time -of day on the stack as an HMS/modulo form. - -@smallexample -@group -1: 17@@ 34' 45" mod 24@@ 0' 0" 1: 6@@ 22' 15" mod 24@@ 0' 0" - . . - - x time @key{RET} n -@end group -@end smallexample - -@noindent -This calculation tells me it is six hours and 22 minutes until midnight. - -(@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year -is about -@texline @math{\pi \times 10^7} -@infoline @w{@expr{pi * 10^7}} -seconds. What time will it be that many seconds from right now? -@xref{Types Answer 11, 11}. (@bullet{}) - -(@bullet{}) @strong{Exercise 12.} You are preparing to order packaging -for the CD release of the Extended Disco Version of @emph{Abbey Road}. -You are told that the songs will actually be anywhere from 20 to 60 -seconds longer than the originals. One CD can hold about 75 minutes -of music. Should you order single or double packages? -@xref{Types Answer 12, 12}. (@bullet{}) - -Another kind of data the Calculator can manipulate is numbers with -@dfn{units}. This isn't strictly a new data type; it's simply an -application of algebraic expressions, where we use variables with -suggestive names like @samp{cm} and @samp{in} to represent units -like centimeters and inches. - -@smallexample -@group -1: 2 in 1: 5.08 cm 1: 0.027778 fath 1: 0.0508 m - . . . . - - ' 2in @key{RET} u c cm @key{RET} u c fath @key{RET} u b -@end group -@end smallexample - -@noindent -We enter the quantity ``2 inches'' (actually an algebraic expression -which means two times the variable @samp{in}), then we convert it -first to centimeters, then to fathoms, then finally to ``base'' units, -which in this case means meters. - -@smallexample -@group -1: 9 acre 1: 3 sqrt(acre) 1: 190.84 m 1: 190.84 m + 30 cm - . . . . - - ' 9 acre @key{RET} Q u s ' $+30 cm @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 191.14 m 1: 36536.3046 m^2 1: 365363046 cm^2 - . . . - - u s 2 ^ u c cgs -@end group -@end smallexample - -@noindent -Since units expressions are really just formulas, taking the square -root of @samp{acre} is undefined. After all, @code{acre} might be an -algebraic variable that you will someday assign a value. We use the -``units-simplify'' command to simplify the expression with variables -being interpreted as unit names. - -In the final step, we have converted not to a particular unit, but to a -units system. The ``cgs'' system uses centimeters instead of meters -as its standard unit of length. - -There is a wide variety of units defined in the Calculator. - -@smallexample -@group -1: 55 mph 1: 88.5139 kph 1: 88.5139 km / hr 1: 8.201407e-8 c - . . . . - - ' 55 mph @key{RET} u c kph @key{RET} u c km/hr @key{RET} u c c @key{RET} -@end group -@end smallexample - -@noindent -We express a speed first in miles per hour, then in kilometers per -hour, then again using a slightly more explicit notation, then -finally in terms of fractions of the speed of light. - -Temperature conversions are a bit more tricky. There are two ways to -interpret ``20 degrees Fahrenheit''---it could mean an actual -temperature, or it could mean a change in temperature. For normal -units there is no difference, but temperature units have an offset -as well as a scale factor and so there must be two explicit commands -for them. - -@smallexample -@group -1: 20 degF 1: 11.1111 degC 1: -6.666 degC - . . . . - - ' 20 degF @key{RET} u c degC @key{RET} U u t degC @key{RET} -@end group -@end smallexample - -@noindent -First we convert a change of 20 degrees Fahrenheit into an equivalent -change in degrees Celsius (or Centigrade). Then, we convert the -absolute temperature 20 degrees Fahrenheit into Celsius. - -For simple unit conversions, you can put a plain number on the stack. -Then @kbd{u c} and @kbd{u t} will prompt for both old and new units. -When you use this method, you're responsible for remembering which -numbers are in which units: - -@smallexample -@group -1: 55 1: 88.5139 1: 8.201407e-8 - . . . - - 55 u c mph @key{RET} kph @key{RET} u c km/hr @key{RET} c @key{RET} -@end group -@end smallexample - -To see a complete list of built-in units, type @kbd{u v}. Press -@w{@kbd{C-x * c}} again to re-enter the Calculator when you're done looking -at the units table. - -(@bullet{}) @strong{Exercise 13.} How many seconds are there really -in a year? @xref{Types Answer 13, 13}. (@bullet{}) - -@cindex Speed of light -(@bullet{}) @strong{Exercise 14.} Supercomputer designs are limited by -the speed of light (and of electricity, which is nearly as fast). -Suppose a computer has a 4.1 ns (nanosecond) clock cycle, and its -cabinet is one meter across. Is speed of light going to be a -significant factor in its design? @xref{Types Answer 14, 14}. (@bullet{}) - -(@bullet{}) @strong{Exercise 15.} Sam the Slug normally travels about -five yards in an hour. He has obtained a supply of Power Pills; each -Power Pill he eats doubles his speed. How many Power Pills can he -swallow and still travel legally on most US highways? -@xref{Types Answer 15, 15}. (@bullet{}) - -@node Algebra Tutorial, Programming Tutorial, Types Tutorial, Tutorial -@section Algebra and Calculus Tutorial - -@noindent -This section shows how to use Calc's algebra facilities to solve -equations, do simple calculus problems, and manipulate algebraic -formulas. - -@menu -* Basic Algebra Tutorial:: -* Rewrites Tutorial:: -@end menu - -@node Basic Algebra Tutorial, Rewrites Tutorial, Algebra Tutorial, Algebra Tutorial -@subsection Basic Algebra - -@noindent -If you enter a formula in Algebraic mode that refers to variables, -the formula itself is pushed onto the stack. You can manipulate -formulas as regular data objects. - -@smallexample -@group -1: 2 x^2 - 6 1: 6 - 2 x^2 1: (3 x^2 + y) (6 - 2 x^2) - . . . - - ' 2x^2-6 @key{RET} n ' 3x^2+y @key{RET} * -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 1.} Do @kbd{' x @key{RET} Q 2 ^} and -@kbd{' x @key{RET} 2 ^ Q} both wind up with the same result (@samp{x})? -Why or why not? @xref{Algebra Answer 1, 1}. (@bullet{}) - -There are also commands for doing common algebraic operations on -formulas. Continuing with the formula from the last example, - -@smallexample -@group -1: 18 x^2 - 6 x^4 + 6 y - 2 y x^2 1: (18 - 2 y) x^2 - 6 x^4 + 6 y - . . - - a x a c x @key{RET} -@end group -@end smallexample - -@noindent -First we ``expand'' using the distributive law, then we ``collect'' -terms involving like powers of @expr{x}. - -Let's find the value of this expression when @expr{x} is 2 and @expr{y} -is one-half. - -@smallexample -@group -1: 17 x^2 - 6 x^4 + 3 1: -25 - . . - - 1:2 s l y @key{RET} 2 s l x @key{RET} -@end group -@end smallexample - -@noindent -The @kbd{s l} command means ``let''; it takes a number from the top of -the stack and temporarily assigns it as the value of the variable -you specify. It then evaluates (as if by the @kbd{=} key) the -next expression on the stack. After this command, the variable goes -back to its original value, if any. - -(An earlier exercise in this tutorial involved storing a value in the -variable @code{x}; if this value is still there, you will have to -unstore it with @kbd{s u x @key{RET}} before the above example will work -properly.) - -@cindex Maximum of a function using Calculus -Let's find the maximum value of our original expression when @expr{y} -is one-half and @expr{x} ranges over all possible values. We can -do this by taking the derivative with respect to @expr{x} and examining -values of @expr{x} for which the derivative is zero. If the second -derivative of the function at that value of @expr{x} is negative, -the function has a local maximum there. - -@smallexample -@group -1: 17 x^2 - 6 x^4 + 3 1: 34 x - 24 x^3 - . . - - U @key{DEL} s 1 a d x @key{RET} s 2 -@end group -@end smallexample - -@noindent -Well, the derivative is clearly zero when @expr{x} is zero. To find -the other root(s), let's divide through by @expr{x} and then solve: - -@smallexample -@group -1: (34 x - 24 x^3) / x 1: 34 - 24 x^2 - . . - - ' x @key{RET} / a x - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 0.70588 x^2 = 1 1: x = 1.19023 - . . - - 0 a = s 3 a S x @key{RET} -@end group -@end smallexample - -@noindent -Now we compute the second derivative and plug in our values of @expr{x}: - -@smallexample -@group -1: 1.19023 2: 1.19023 2: 1.19023 - . 1: 34 x - 24 x^3 1: 34 - 72 x^2 - . . - - a . r 2 a d x @key{RET} s 4 -@end group -@end smallexample - -@noindent -(The @kbd{a .} command extracts just the righthand side of an equation. -Another method would have been to use @kbd{v u} to unpack the equation -@w{@samp{x = 1.19}} to @samp{x} and @samp{1.19}, then use @kbd{M-- M-2 @key{DEL}} -to delete the @samp{x}.) - -@smallexample -@group -2: 34 - 72 x^2 1: -68. 2: 34 - 72 x^2 1: 34 -1: 1.19023 . 1: 0 . - . . - - @key{TAB} s l x @key{RET} U @key{DEL} 0 s l x @key{RET} -@end group -@end smallexample - -@noindent -The first of these second derivatives is negative, so we know the function -has a maximum value at @expr{x = 1.19023}. (The function also has a -local @emph{minimum} at @expr{x = 0}.) - -When we solved for @expr{x}, we got only one value even though -@expr{0.70588 x^2 = 1} is a quadratic equation that ought to have -two solutions. The reason is that @w{@kbd{a S}} normally returns a -single ``principal'' solution. If it needs to come up with an -arbitrary sign (as occurs in the quadratic formula) it picks @expr{+}. -If it needs an arbitrary integer, it picks zero. We can get a full -solution by pressing @kbd{H} (the Hyperbolic flag) before @kbd{a S}. - -@smallexample -@group -1: 0.70588 x^2 = 1 1: x = 1.19023 s1 1: x = -1.19023 - . . . - - r 3 H a S x @key{RET} s 5 1 n s l s1 @key{RET} -@end group -@end smallexample - -@noindent -Calc has invented the variable @samp{s1} to represent an unknown sign; -it is supposed to be either @mathit{+1} or @mathit{-1}. Here we have used -the ``let'' command to evaluate the expression when the sign is negative. -If we plugged this into our second derivative we would get the same, -negative, answer, so @expr{x = -1.19023} is also a maximum. - -To find the actual maximum value, we must plug our two values of @expr{x} -into the original formula. - -@smallexample -@group -2: 17 x^2 - 6 x^4 + 3 1: 24.08333 s1^2 - 12.04166 s1^4 + 3 -1: x = 1.19023 s1 . - . - - r 1 r 5 s l @key{RET} -@end group -@end smallexample - -@noindent -(Here we see another way to use @kbd{s l}; if its input is an equation -with a variable on the lefthand side, then @kbd{s l} treats the equation -like an assignment to that variable if you don't give a variable name.) - -It's clear that this will have the same value for either sign of -@code{s1}, but let's work it out anyway, just for the exercise: - -@smallexample -@group -2: [-1, 1] 1: [15.04166, 15.04166] -1: 24.08333 s1^2 ... . - . - - [ 1 n , 1 ] @key{TAB} V M $ @key{RET} -@end group -@end smallexample - -@noindent -Here we have used a vector mapping operation to evaluate the function -at several values of @samp{s1} at once. @kbd{V M $} is like @kbd{V M '} -except that it takes the formula from the top of the stack. The -formula is interpreted as a function to apply across the vector at the -next-to-top stack level. Since a formula on the stack can't contain -@samp{$} signs, Calc assumes the variables in the formula stand for -different arguments. It prompts you for an @dfn{argument list}, giving -the list of all variables in the formula in alphabetical order as the -default list. In this case the default is @samp{(s1)}, which is just -what we want so we simply press @key{RET} at the prompt. - -If there had been several different values, we could have used -@w{@kbd{V R X}} to find the global maximum. - -Calc has a built-in @kbd{a P} command that solves an equation using -@w{@kbd{H a S}} and returns a vector of all the solutions. It simply -automates the job we just did by hand. Applied to our original -cubic polynomial, it would produce the vector of solutions -@expr{[1.19023, -1.19023, 0]}. (There is also an @kbd{a X} command -which finds a local maximum of a function. It uses a numerical search -method rather than examining the derivatives, and thus requires you -to provide some kind of initial guess to show it where to look.) - -(@bullet{}) @strong{Exercise 2.} Given a vector of the roots of a -polynomial (such as the output of an @kbd{a P} command), what -sequence of commands would you use to reconstruct the original -polynomial? (The answer will be unique to within a constant -multiple; choose the solution where the leading coefficient is one.) -@xref{Algebra Answer 2, 2}. (@bullet{}) - -The @kbd{m s} command enables Symbolic mode, in which formulas -like @samp{sqrt(5)} that can't be evaluated exactly are left in -symbolic form rather than giving a floating-point approximate answer. -Fraction mode (@kbd{m f}) is also useful when doing algebra. - -@smallexample -@group -2: 34 x - 24 x^3 2: 34 x - 24 x^3 -1: 34 x - 24 x^3 1: [sqrt(51) / 6, sqrt(51) / -6, 0] - . . - - r 2 @key{RET} m s m f a P x @key{RET} -@end group -@end smallexample - -One more mode that makes reading formulas easier is Big mode. - -@smallexample -@group - 3 -2: 34 x - 24 x - - ____ ____ - V 51 V 51 -1: [-----, -----, 0] - 6 -6 - - . - - d B -@end group -@end smallexample - -Here things like powers, square roots, and quotients and fractions -are displayed in a two-dimensional pictorial form. Calc has other -language modes as well, such as C mode, FORTRAN mode, @TeX{} mode -and @LaTeX{} mode. - -@smallexample -@group -2: 34*x - 24*pow(x, 3) 2: 34*x - 24*x**3 -1: @{sqrt(51) / 6, sqrt(51) / -6, 0@} 1: /sqrt(51) / 6, sqrt(51) / -6, 0/ - . . - - d C d F - -@end group -@end smallexample -@noindent -@smallexample -@group -3: 34 x - 24 x^3 -2: [@{\sqrt@{51@} \over 6@}, @{\sqrt@{51@} \over -6@}, 0] -1: @{2 \over 3@} \sqrt@{5@} - . - - d T ' 2 \sqrt@{5@} \over 3 @key{RET} -@end group -@end smallexample - -@noindent -As you can see, language modes affect both entry and display of -formulas. They affect such things as the names used for built-in -functions, the set of arithmetic operators and their precedences, -and notations for vectors and matrices. - -Notice that @samp{sqrt(51)} may cause problems with older -implementations of C and FORTRAN, which would require something more -like @samp{sqrt(51.0)}. It is always wise to check over the formulas -produced by the various language modes to make sure they are fully -correct. - -Type @kbd{m s}, @kbd{m f}, and @kbd{d N} to reset these modes. (You -may prefer to remain in Big mode, but all the examples in the tutorial -are shown in normal mode.) - -@cindex Area under a curve -What is the area under the portion of this curve from @expr{x = 1} to @expr{2}? -This is simply the integral of the function: - -@smallexample -@group -1: 17 x^2 - 6 x^4 + 3 1: 5.6666 x^3 - 1.2 x^5 + 3 x - . . - - r 1 a i x -@end group -@end smallexample - -@noindent -We want to evaluate this at our two values for @expr{x} and subtract. -One way to do it is again with vector mapping and reduction: - -@smallexample -@group -2: [2, 1] 1: [12.93333, 7.46666] 1: 5.46666 -1: 5.6666 x^3 ... . . - - [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @expr{y} -of -@texline @math{x \sin \pi x} -@infoline @w{@expr{x sin(pi x)}} -(where the sine is calculated in radians). Find the values of the -integral for integers @expr{y} from 1 to 5. @xref{Algebra Answer 3, -3}. (@bullet{}) - -Calc's integrator can do many simple integrals symbolically, but many -others are beyond its capabilities. Suppose we wish to find the area -under the curve -@texline @math{\sin x \ln x} -@infoline @expr{sin(x) ln(x)} -over the same range of @expr{x}. If you entered this formula and typed -@kbd{a i x @key{RET}} (don't bother to try this), Calc would work for a -long time but would be unable to find a solution. In fact, there is no -closed-form solution to this integral. Now what do we do? - -@cindex Integration, numerical -@cindex Numerical integration -One approach would be to do the integral numerically. It is not hard -to do this by hand using vector mapping and reduction. It is rather -slow, though, since the sine and logarithm functions take a long time. -We can save some time by reducing the working precision. - -@smallexample -@group -3: 10 1: [1, 1.1, 1.2, ... , 1.8, 1.9] -2: 1 . -1: 0.1 - . - - 10 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x -@end group -@end smallexample - -@noindent -(Note that we have used the extended version of @kbd{v x}; we could -also have used plain @kbd{v x} as follows: @kbd{v x 10 @key{RET} 9 + .1 *}.) - -@smallexample -@group -2: [1, 1.1, ... ] 1: [0., 0.084941, 0.16993, ... ] -1: ln(x) sin(x) . - . - - ' sin(x) ln(x) @key{RET} s 1 m r p 5 @key{RET} V M $ @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 3.4195 0.34195 - . . - - V R + 0.1 * -@end group -@end smallexample - -@noindent -(If you got wildly different results, did you remember to switch -to Radians mode?) - -Here we have divided the curve into ten segments of equal width; -approximating these segments as rectangular boxes (i.e., assuming -the curve is nearly flat at that resolution), we compute the areas -of the boxes (height times width), then sum the areas. (It is -faster to sum first, then multiply by the width, since the width -is the same for every box.) - -The true value of this integral turns out to be about 0.374, so -we're not doing too well. Let's try another approach. - -@smallexample -@group -1: ln(x) sin(x) 1: 0.84147 x + 0.11957 (x - 1)^2 - ... - . . - - r 1 a t x=1 @key{RET} 4 @key{RET} -@end group -@end smallexample - -@noindent -Here we have computed the Taylor series expansion of the function -about the point @expr{x=1}. We can now integrate this polynomial -approximation, since polynomials are easy to integrate. - -@smallexample -@group -1: 0.42074 x^2 + ... 1: [-0.0446, -0.42073] 1: 0.3761 - . . . - - a i x @key{RET} [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - -@end group -@end smallexample - -@noindent -Better! By increasing the precision and/or asking for more terms -in the Taylor series, we can get a result as accurate as we like. -(Taylor series converge better away from singularities in the -function such as the one at @code{ln(0)}, so it would also help to -expand the series about the points @expr{x=2} or @expr{x=1.5} instead -of @expr{x=1}.) - -@cindex Simpson's rule -@cindex Integration by Simpson's rule -(@bullet{}) @strong{Exercise 4.} Our first method approximated the -curve by stairsteps of width 0.1; the total area was then the sum -of the areas of the rectangles under these stairsteps. Our second -method approximated the function by a polynomial, which turned out -to be a better approximation than stairsteps. A third method is -@dfn{Simpson's rule}, which is like the stairstep method except -that the steps are not required to be flat. Simpson's rule boils -down to the formula, - -@ifnottex -@example -(h/3) * (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + ... - + 2 f(a+(n-2)*h) + 4 f(a+(n-1)*h) + f(a+n*h)) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \displaylines{ - \qquad {h \over 3} (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + \cdots - \hfill \cr \hfill {} + 2 f(a+(n-2)h) + 4 f(a+(n-1)h) + f(a+n h)) \qquad -} $$ -\afterdisplay -@end tex - -@noindent -where @expr{n} (which must be even) is the number of slices and @expr{h} -is the width of each slice. These are 10 and 0.1 in our example. -For reference, here is the corresponding formula for the stairstep -method: - -@ifnottex -@example -h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ... - + f(a+(n-2)*h) + f(a+(n-1)*h)) -@end example -@end ifnottex -@tex -\beforedisplay -$$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots - + f(a+(n-2)h) + f(a+(n-1)h)) $$ -\afterdisplay -@end tex - -Compute the integral from 1 to 2 of -@texline @math{\sin x \ln x} -@infoline @expr{sin(x) ln(x)} -using Simpson's rule with 10 slices. -@xref{Algebra Answer 4, 4}. (@bullet{}) - -Calc has a built-in @kbd{a I} command for doing numerical integration. -It uses @dfn{Romberg's method}, which is a more sophisticated cousin -of Simpson's rule. In particular, it knows how to keep refining the -result until the current precision is satisfied. - -@c [fix-ref Selecting Sub-Formulas] -Aside from the commands we've seen so far, Calc also provides a -large set of commands for operating on parts of formulas. You -indicate the desired sub-formula by placing the cursor on any part -of the formula before giving a @dfn{selection} command. Selections won't -be covered in the tutorial; @pxref{Selecting Subformulas}, for -details and examples. - -@c hard exercise: simplify (2^(n r) - 2^(r*(n - 1))) / (2^r - 1) 2^(n - 1) -@c to 2^((n-1)*(r-1)). - -@node Rewrites Tutorial, , Basic Algebra Tutorial, Algebra Tutorial -@subsection Rewrite Rules - -@noindent -No matter how many built-in commands Calc provided for doing algebra, -there would always be something you wanted to do that Calc didn't have -in its repertoire. So Calc also provides a @dfn{rewrite rule} system -that you can use to define your own algebraic manipulations. - -Suppose we want to simplify this trigonometric formula: - -@smallexample -@group -1: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 - . - - ' 2sec(x)^2/tan(x)^2 - 2/tan(x)^2 @key{RET} s 1 -@end group -@end smallexample - -@noindent -If we were simplifying this by hand, we'd probably combine over the common -denominator. The @kbd{a n} algebra command will do this, but we'll do -it with a rewrite rule just for practice. - -Rewrite rules are written with the @samp{:=} symbol. - -@smallexample -@group -1: (2 sec(x)^2 - 2) / tan(x)^2 - . - - a r a/x + b/x := (a+b)/x @key{RET} -@end group -@end smallexample - -@noindent -(The ``assignment operator'' @samp{:=} has several uses in Calc. All -by itself the formula @samp{a/x + b/x := (a+b)/x} doesn't do anything, -but when it is given to the @kbd{a r} command, that command interprets -it as a rewrite rule.) - -The lefthand side, @samp{a/x + b/x}, is called the @dfn{pattern} of the -rewrite rule. Calc searches the formula on the stack for parts that -match the pattern. Variables in a rewrite pattern are called -@dfn{meta-variables}, and when matching the pattern each meta-variable -can match any sub-formula. Here, the meta-variable @samp{a} matched -the expression @samp{2 sec(x)^2}, the meta-variable @samp{b} matched -the constant @samp{-2} and the meta-variable @samp{x} matched -the expression @samp{tan(x)^2}. - -This rule points out several interesting features of rewrite patterns. -First, if a meta-variable appears several times in a pattern, it must -match the same thing everywhere. This rule detects common denominators -because the same meta-variable @samp{x} is used in both of the -denominators. - -Second, meta-variable names are independent from variables in the -target formula. Notice that the meta-variable @samp{x} here matches -the subformula @samp{tan(x)^2}; Calc never confuses the two meanings of -@samp{x}. - -And third, rewrite patterns know a little bit about the algebraic -properties of formulas. The pattern called for a sum of two quotients; -Calc was able to match a difference of two quotients by matching -@samp{a = 2 sec(x)^2}, @samp{b = -2}, and @samp{x = tan(x)^2}. - -When the pattern part of a rewrite rule matches a part of the formula, -that part is replaced by the righthand side with all the meta-variables -substituted with the things they matched. So the result is -@samp{(2 sec(x)^2 - 2) / tan(x)^2}. - -@c [fix-ref Algebraic Properties of Rewrite Rules] -We could just as easily have written @samp{a/x - b/x := (a-b)/x} for -the rule. It would have worked just the same in all cases. (If we -really wanted the rule to apply only to @samp{+} or only to @samp{-}, -we could have used the @code{plain} symbol. @xref{Algebraic Properties -of Rewrite Rules}, for some examples of this.) - -One more rewrite will complete the job. We want to use the identity -@samp{tan(x)^2 + 1 = sec(x)^2}, but of course we must first rearrange -the identity in a way that matches our formula. The obvious rule -would be @samp{@w{2 sec(x)^2 - 2} := 2 tan(x)^2}, but a little thought shows -that the rule @samp{sec(x)^2 := 1 + tan(x)^2} will also work. The -latter rule has a more general pattern so it will work in many other -situations, too. - -@smallexample -@group -1: 2 - . - - a r sec(x)^2 := 1 + tan(x)^2 @key{RET} -@end group -@end smallexample - -You may ask, what's the point of using the most general rule if you -have to type it in every time anyway? The answer is that Calc allows -you to store a rewrite rule in a variable, then give the variable -name in the @kbd{a r} command. In fact, this is the preferred way to -use rewrites. For one, if you need a rule once you'll most likely -need it again later. Also, if the rule doesn't work quite right you -can simply Undo, edit the variable, and run the rule again without -having to retype it. - -@smallexample -@group -' a/x + b/x := (a+b)/x @key{RET} s t merge @key{RET} -' sec(x)^2 := 1 + tan(x)^2 @key{RET} s t secsqr @key{RET} - -1: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 1: 2 - . . - - r 1 a r merge @key{RET} a r secsqr @key{RET} -@end group -@end smallexample - -To edit a variable, type @kbd{s e} and the variable name, use regular -Emacs editing commands as necessary, then type @kbd{C-c C-c} to store -the edited value back into the variable. -You can also use @w{@kbd{s e}} to create a new variable if you wish. - -Notice that the first time you use each rule, Calc puts up a ``compiling'' -message briefly. The pattern matcher converts rules into a special -optimized pattern-matching language rather than using them directly. -This allows @kbd{a r} to apply even rather complicated rules very -efficiently. If the rule is stored in a variable, Calc compiles it -only once and stores the compiled form along with the variable. That's -another good reason to store your rules in variables rather than -entering them on the fly. - -(@bullet{}) @strong{Exercise 1.} Type @kbd{m s} to get Symbolic -mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}. -Using a rewrite rule, simplify this formula by multiplying the top and -bottom by the conjugate @w{@samp{1 - sqrt(2)}}. The result will have -to be expanded by the distributive law; do this with another -rewrite. @xref{Rewrites Answer 1, 1}. (@bullet{}) - -The @kbd{a r} command can also accept a vector of rewrite rules, or -a variable containing a vector of rules. - -@smallexample -@group -1: [merge, secsqr] 1: [a/x + b/x := (a + b)/x, ... ] - . . - - ' [merge,sinsqr] @key{RET} = - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 2 sec(x)^2 / tan(x)^2 - 2 / tan(x)^2 1: 2 - . . - - s t trig @key{RET} r 1 a r trig @key{RET} -@end group -@end smallexample - -@c [fix-ref Nested Formulas with Rewrite Rules] -Calc tries all the rules you give against all parts of the formula, -repeating until no further change is possible. (The exact order in -which things are tried is rather complex, but for simple rules like -the ones we've used here the order doesn't really matter. -@xref{Nested Formulas with Rewrite Rules}.) - -Calc actually repeats only up to 100 times, just in case your rule set -has gotten into an infinite loop. You can give a numeric prefix argument -to @kbd{a r} to specify any limit. In particular, @kbd{M-1 a r} does -only one rewrite at a time. - -@smallexample -@group -1: (2 sec(x)^2 - 2) / tan(x)^2 1: 2 - . . - - r 1 M-1 a r trig @key{RET} M-1 a r trig @key{RET} -@end group -@end smallexample - -You can type @kbd{M-0 a r} if you want no limit at all on the number -of rewrites that occur. - -Rewrite rules can also be @dfn{conditional}. Simply follow the rule -with a @samp{::} symbol and the desired condition. For example, - -@smallexample -@group -1: sin(x + 2 pi) + sin(x + 3 pi) + sin(x + 4 pi) - . - - ' sin(x+2pi) + sin(x+3pi) + sin(x+4pi) @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: sin(x + 3 pi) + 2 sin(x) - . - - a r sin(a + k pi) := sin(a) :: k % 2 = 0 @key{RET} -@end group -@end smallexample - -@noindent -(Recall, @samp{k % 2} is the remainder from dividing @samp{k} by 2, -which will be zero only when @samp{k} is an even integer.) - -An interesting point is that the variable @samp{pi} was matched -literally rather than acting as a meta-variable. -This is because it is a special-constant variable. The special -constants @samp{e}, @samp{i}, @samp{phi}, and so on also match literally. -A common error with rewrite -rules is to write, say, @samp{f(a,b,c,d,e) := g(a+b+c+d+e)}, expecting -to match any @samp{f} with five arguments but in fact matching -only when the fifth argument is literally @samp{e}! - -@cindex Fibonacci numbers -@ignore -@starindex -@end ignore -@tindex fib -Rewrite rules provide an interesting way to define your own functions. -Suppose we want to define @samp{fib(n)} to produce the @var{n}th -Fibonacci number. The first two Fibonacci numbers are each 1; -later numbers are formed by summing the two preceding numbers in -the sequence. This is easy to express in a set of three rules: - -@smallexample -@group -' [fib(1) := 1, fib(2) := 1, fib(n) := fib(n-1) + fib(n-2)] @key{RET} s t fib - -1: fib(7) 1: 13 - . . - - ' fib(7) @key{RET} a r fib @key{RET} -@end group -@end smallexample - -One thing that is guaranteed about the order that rewrites are tried -is that, for any given subformula, earlier rules in the rule set will -be tried for that subformula before later ones. So even though the -first and third rules both match @samp{fib(1)}, we know the first will -be used preferentially. - -This rule set has one dangerous bug: Suppose we apply it to the -formula @samp{fib(x)}? (Don't actually try this.) The third rule -will match @samp{fib(x)} and replace it with @w{@samp{fib(x-1) + fib(x-2)}}. -Each of these will then be replaced to get @samp{fib(x-2) + 2 fib(x-3) + -fib(x-4)}, and so on, expanding forever. What we really want is to apply -the third rule only when @samp{n} is an integer greater than two. Type -@w{@kbd{s e fib @key{RET}}}, then edit the third rule to: - -@smallexample -fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 -@end smallexample - -@noindent -Now: - -@smallexample -@group -1: fib(6) + fib(x) + fib(0) 1: fib(x) + fib(0) + 8 - . . - - ' fib(6)+fib(x)+fib(0) @key{RET} a r fib @key{RET} -@end group -@end smallexample - -@noindent -We've created a new function, @code{fib}, and a new command, -@w{@kbd{a r fib @key{RET}}}, which means ``evaluate all @code{fib} calls in -this formula.'' To make things easier still, we can tell Calc to -apply these rules automatically by storing them in the special -variable @code{EvalRules}. - -@smallexample -@group -1: [fib(1) := ...] . 1: [8, 13] - . . - - s r fib @key{RET} s t EvalRules @key{RET} ' [fib(6), fib(7)] @key{RET} -@end group -@end smallexample - -It turns out that this rule set has the problem that it does far -more work than it needs to when @samp{n} is large. Consider the -first few steps of the computation of @samp{fib(6)}: - -@smallexample -@group -fib(6) = -fib(5) + fib(4) = -fib(4) + fib(3) + fib(3) + fib(2) = -fib(3) + fib(2) + fib(2) + fib(1) + fib(2) + fib(1) + 1 = ... -@end group -@end smallexample - -@noindent -Note that @samp{fib(3)} appears three times here. Unless Calc's -algebraic simplifier notices the multiple @samp{fib(3)}s and combines -them (and, as it happens, it doesn't), this rule set does lots of -needless recomputation. To cure the problem, type @code{s e EvalRules} -to edit the rules (or just @kbd{s E}, a shorthand command for editing -@code{EvalRules}) and add another condition: - -@smallexample -fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 :: remember -@end smallexample - -@noindent -If a @samp{:: remember} condition appears anywhere in a rule, then if -that rule succeeds Calc will add another rule that describes that match -to the front of the rule set. (Remembering works in any rule set, but -for technical reasons it is most effective in @code{EvalRules}.) For -example, if the rule rewrites @samp{fib(7)} to something that evaluates -to 13, then the rule @samp{fib(7) := 13} will be added to the rule set. - -Type @kbd{' fib(8) @key{RET}} to compute the eighth Fibonacci number, then -type @kbd{s E} again to see what has happened to the rule set. - -With the @code{remember} feature, our rule set can now compute -@samp{fib(@var{n})} in just @var{n} steps. In the process it builds -up a table of all Fibonacci numbers up to @var{n}. After we have -computed the result for a particular @var{n}, we can get it back -(and the results for all smaller @var{n}) later in just one step. - -All Calc operations will run somewhat slower whenever @code{EvalRules} -contains any rules. You should type @kbd{s u EvalRules @key{RET}} now to -un-store the variable. - -(@bullet{}) @strong{Exercise 2.} Sometimes it is possible to reformulate -a problem to reduce the amount of recursion necessary to solve it. -Create a rule that, in about @var{n} simple steps and without recourse -to the @code{remember} option, replaces @samp{fib(@var{n}, 1, 1)} with -@samp{fib(1, @var{x}, @var{y})} where @var{x} and @var{y} are the -@var{n}th and @var{n+1}st Fibonacci numbers, respectively. This rule is -rather clunky to use, so add a couple more rules to make the ``user -interface'' the same as for our first version: enter @samp{fib(@var{n})}, -get back a plain number. @xref{Rewrites Answer 2, 2}. (@bullet{}) - -There are many more things that rewrites can do. For example, there -are @samp{&&&} and @samp{|||} pattern operators that create ``and'' -and ``or'' combinations of rules. As one really simple example, we -could combine our first two Fibonacci rules thusly: - -@example -[fib(1 ||| 2) := 1, fib(n) := ... ] -@end example - -@noindent -That means ``@code{fib} of something matching either 1 or 2 rewrites -to 1.'' - -You can also make meta-variables optional by enclosing them in @code{opt}. -For example, the pattern @samp{a + b x} matches @samp{2 + 3 x} but not -@samp{2 + x} or @samp{3 x} or @samp{x}. The pattern @samp{opt(a) + opt(b) x} -matches all of these forms, filling in a default of zero for @samp{a} -and one for @samp{b}. - -(@bullet{}) @strong{Exercise 3.} Your friend Joe had @samp{2 + 3 x} -on the stack and tried to use the rule -@samp{opt(a) + opt(b) x := f(a, b, x)}. What happened? -@xref{Rewrites Answer 3, 3}. (@bullet{}) - -(@bullet{}) @strong{Exercise 4.} Starting with a positive integer @expr{a}, -divide @expr{a} by two if it is even, otherwise compute @expr{3 a + 1}. -Now repeat this step over and over. A famous unproved conjecture -is that for any starting @expr{a}, the sequence always eventually -reaches 1. Given the formula @samp{seq(@var{a}, 0)}, write a set of -rules that convert this into @samp{seq(1, @var{n})} where @var{n} -is the number of steps it took the sequence to reach the value 1. -Now enhance the rules to accept @samp{seq(@var{a})} as a starting -configuration, and to stop with just the number @var{n} by itself. -Now make the result be a vector of values in the sequence, from @var{a} -to 1. (The formula @samp{@var{x}|@var{y}} appends the vectors @var{x} -and @var{y}.) For example, rewriting @samp{seq(6)} should yield the -vector @expr{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. -@xref{Rewrites Answer 4, 4}. (@bullet{}) - -(@bullet{}) @strong{Exercise 5.} Define, using rewrite rules, a function -@samp{nterms(@var{x})} that returns the number of terms in the sum -@var{x}, or 1 if @var{x} is not a sum. (A @dfn{sum} for our purposes -is one or more non-sum terms separated by @samp{+} or @samp{-} signs, -so that @expr{2 - 3 (x + y) + x y} is a sum of three terms.) -@xref{Rewrites Answer 5, 5}. (@bullet{}) - -(@bullet{}) @strong{Exercise 6.} A Taylor series for a function is an -infinite series that exactly equals the value of that function at -values of @expr{x} near zero. - -@ifnottex -@example -cos(x) = 1 - x^2 / 2! + x^4 / 4! - x^6 / 6! + ... -@end example -@end ifnottex -@tex -\beforedisplay -$$ \cos x = 1 - {x^2 \over 2!} + {x^4 \over 4!} - {x^6 \over 6!} + \cdots $$ -\afterdisplay -@end tex - -The @kbd{a t} command produces a @dfn{truncated Taylor series} which -is obtained by dropping all the terms higher than, say, @expr{x^2}. -Calc represents the truncated Taylor series as a polynomial in @expr{x}. -Mathematicians often write a truncated series using a ``big-O'' notation -that records what was the lowest term that was truncated. - -@ifnottex -@example -cos(x) = 1 - x^2 / 2! + O(x^3) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \cos x = 1 - {x^2 \over 2!} + O(x^3) $$ -\afterdisplay -@end tex - -@noindent -The meaning of @expr{O(x^3)} is ``a quantity which is negligibly small -if @expr{x^3} is considered negligibly small as @expr{x} goes to zero.'' - -The exercise is to create rewrite rules that simplify sums and products of -power series represented as @samp{@var{polynomial} + O(@var{var}^@var{n})}. -For example, given @samp{1 - x^2 / 2 + O(x^3)} and @samp{x - x^3 / 6 + O(x^4)} -on the stack, we want to be able to type @kbd{*} and get the result -@samp{x - 2:3 x^3 + O(x^4)}. Don't worry if the terms of the sum are -rearranged. (This one is rather tricky; the solution at the end of -this chapter uses 6 rewrite rules. Hint: The @samp{constant(x)} -condition tests whether @samp{x} is a number.) @xref{Rewrites Answer -6, 6}. (@bullet{}) - -Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}. -What happens? (Be sure to remove this rule afterward, or you might get -a nasty surprise when you use Calc to balance your checkbook!) - -@xref{Rewrite Rules}, for the whole story on rewrite rules. - -@node Programming Tutorial, Answers to Exercises, Algebra Tutorial, Tutorial -@section Programming Tutorial - -@noindent -The Calculator is written entirely in Emacs Lisp, a highly extensible -language. If you know Lisp, you can program the Calculator to do -anything you like. Rewrite rules also work as a powerful programming -system. But Lisp and rewrite rules take a while to master, and often -all you want to do is define a new function or repeat a command a few -times. Calc has features that allow you to do these things easily. - -One very limited form of programming is defining your own functions. -Calc's @kbd{Z F} command allows you to define a function name and -key sequence to correspond to any formula. Programming commands use -the shift-@kbd{Z} prefix; the user commands they create use the lower -case @kbd{z} prefix. - -@smallexample -@group -1: x + x^2 / 2 + x^3 / 6 + 1 1: x + x^2 / 2 + x^3 / 6 + 1 - . . - - ' 1 + x + x^2/2! + x^3/3! @key{RET} Z F e myexp @key{RET} @key{RET} @key{RET} y -@end group -@end smallexample - -This polynomial is a Taylor series approximation to @samp{exp(x)}. -The @kbd{Z F} command asks a number of questions. The above answers -say that the key sequence for our function should be @kbd{z e}; the -@kbd{M-x} equivalent should be @code{calc-myexp}; the name of the -function in algebraic formulas should also be @code{myexp}; the -default argument list @samp{(x)} is acceptable; and finally @kbd{y} -answers the question ``leave it in symbolic form for non-constant -arguments?'' - -@smallexample -@group -1: 1.3495 2: 1.3495 3: 1.3495 - . 1: 1.34986 2: 1.34986 - . 1: myexp(a + 1) - . - - .3 z e .3 E ' a+1 @key{RET} z e -@end group -@end smallexample - -@noindent -First we call our new @code{exp} approximation with 0.3 as an -argument, and compare it with the true @code{exp} function. Then -we note that, as requested, if we try to give @kbd{z e} an -argument that isn't a plain number, it leaves the @code{myexp} -function call in symbolic form. If we had answered @kbd{n} to the -final question, @samp{myexp(a + 1)} would have evaluated by plugging -in @samp{a + 1} for @samp{x} in the defining formula. - -@cindex Sine integral Si(x) -@ignore -@starindex -@end ignore -@tindex Si -(@bullet{}) @strong{Exercise 1.} The ``sine integral'' function -@texline @math{{\rm Si}(x)} -@infoline @expr{Si(x)} -is defined as the integral of @samp{sin(t)/t} for -@expr{t = 0} to @expr{x} in radians. (It was invented because this -integral has no solution in terms of basic functions; if you give it -to Calc's @kbd{a i} command, it will ponder it for a long time and then -give up.) We can use the numerical integration command, however, -which in algebraic notation is written like @samp{ninteg(f(t), t, 0, x)} -with any integrand @samp{f(t)}. Define a @kbd{z s} command and -@code{Si} function that implement this. You will need to edit the -default argument list a bit. As a test, @samp{Si(1)} should return -0.946083. (If you don't get this answer, you might want to check that -Calc is in Radians mode. Also, @code{ninteg} will run a lot faster if -you reduce the precision to, say, six digits beforehand.) -@xref{Programming Answer 1, 1}. (@bullet{}) - -The simplest way to do real ``programming'' of Emacs is to define a -@dfn{keyboard macro}. A keyboard macro is simply a sequence of -keystrokes which Emacs has stored away and can play back on demand. -For example, if you find yourself typing @kbd{H a S x @key{RET}} often, -you may wish to program a keyboard macro to type this for you. - -@smallexample -@group -1: y = sqrt(x) 1: x = y^2 - . . - - ' y=sqrt(x) @key{RET} C-x ( H a S x @key{RET} C-x ) - -1: y = cos(x) 1: x = s1 arccos(y) + 2 n1 pi - . . - - ' y=cos(x) @key{RET} X -@end group -@end smallexample - -@noindent -When you type @kbd{C-x (}, Emacs begins recording. But it is also -still ready to execute your keystrokes, so you're really ``training'' -Emacs by walking it through the procedure once. When you type -@w{@kbd{C-x )}}, the macro is recorded. You can now type @kbd{X} to -re-execute the same keystrokes. - -You can give a name to your macro by typing @kbd{Z K}. - -@smallexample -@group -1: . 1: y = x^4 1: x = s2 sqrt(s1 sqrt(y)) - . . - - Z K x @key{RET} ' y=x^4 @key{RET} z x -@end group -@end smallexample - -@noindent -Notice that we use shift-@kbd{Z} to define the command, and lower-case -@kbd{z} to call it up. - -Keyboard macros can call other macros. - -@smallexample -@group -1: abs(x) 1: x = s1 y 1: 2 / x 1: x = 2 / y - . . . . - - ' abs(x) @key{RET} C-x ( ' y @key{RET} a = z x C-x ) ' 2/x @key{RET} X -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 2.} Define a keyboard macro to negate -the item in level 3 of the stack, without disturbing the rest of -the stack. @xref{Programming Answer 2, 2}. (@bullet{}) - -(@bullet{}) @strong{Exercise 3.} Define keyboard macros to compute -the following functions: - -@enumerate -@item -Compute -@texline @math{\displaystyle{\sin x \over x}}, -@infoline @expr{sin(x) / x}, -where @expr{x} is the number on the top of the stack. - -@item -Compute the base-@expr{b} logarithm, just like the @kbd{B} key except -the arguments are taken in the opposite order. - -@item -Produce a vector of integers from 1 to the integer on the top of -the stack. -@end enumerate -@noindent -@xref{Programming Answer 3, 3}. (@bullet{}) - -(@bullet{}) @strong{Exercise 4.} Define a keyboard macro to compute -the average (mean) value of a list of numbers. -@xref{Programming Answer 4, 4}. (@bullet{}) - -In many programs, some of the steps must execute several times. -Calc has @dfn{looping} commands that allow this. Loops are useful -inside keyboard macros, but actually work at any time. - -@smallexample -@group -1: x^6 2: x^6 1: 360 x^2 - . 1: 4 . - . - - ' x^6 @key{RET} 4 Z < a d x @key{RET} Z > -@end group -@end smallexample - -@noindent -Here we have computed the fourth derivative of @expr{x^6} by -enclosing a derivative command in a ``repeat loop'' structure. -This structure pops a repeat count from the stack, then -executes the body of the loop that many times. - -If you make a mistake while entering the body of the loop, -type @w{@kbd{Z C-g}} to cancel the loop command. - -@cindex Fibonacci numbers -Here's another example: - -@smallexample -@group -3: 1 2: 10946 -2: 1 1: 17711 -1: 20 . - . - -1 @key{RET} @key{RET} 20 Z < @key{TAB} C-j + Z > -@end group -@end smallexample - -@noindent -The numbers in levels 2 and 1 should be the 21st and 22nd Fibonacci -numbers, respectively. (To see what's going on, try a few repetitions -of the loop body by hand; @kbd{C-j}, also on the Line-Feed or @key{LFD} -key if you have one, makes a copy of the number in level 2.) - -@cindex Golden ratio -@cindex Phi, golden ratio -A fascinating property of the Fibonacci numbers is that the @expr{n}th -Fibonacci number can be found directly by computing -@texline @math{\phi^n / \sqrt{5}} -@infoline @expr{phi^n / sqrt(5)} -and then rounding to the nearest integer, where -@texline @math{\phi} (``phi''), -@infoline @expr{phi}, -the ``golden ratio,'' is -@texline @math{(1 + \sqrt{5}) / 2}. -@infoline @expr{(1 + sqrt(5)) / 2}. -(For convenience, this constant is available from the @code{phi} -variable, or the @kbd{I H P} command.) - -@smallexample -@group -1: 1.61803 1: 24476.0000409 1: 10945.9999817 1: 10946 - . . . . - - I H P 21 ^ 5 Q / R -@end group -@end smallexample - -@cindex Continued fractions -(@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction} -representation of -@texline @math{\phi} -@infoline @expr{phi} -is -@texline @math{1 + 1/(1 + 1/(1 + 1/( \ldots )))}. -@infoline @expr{1 + 1/(1 + 1/(1 + 1/( ...@: )))}. -We can compute an approximate value by carrying this however far -and then replacing the innermost -@texline @math{1/( \ldots )} -@infoline @expr{1/( ...@: )} -by 1. Approximate -@texline @math{\phi} -@infoline @expr{phi} -using a twenty-term continued fraction. -@xref{Programming Answer 5, 5}. (@bullet{}) - -(@bullet{}) @strong{Exercise 6.} Linear recurrences like the one for -Fibonacci numbers can be expressed in terms of matrices. Given a -vector @w{@expr{[a, b]}} determine a matrix which, when multiplied by this -vector, produces the vector @expr{[b, c]}, where @expr{a}, @expr{b} and -@expr{c} are three successive Fibonacci numbers. Now write a program -that, given an integer @expr{n}, computes the @expr{n}th Fibonacci number -using matrix arithmetic. @xref{Programming Answer 6, 6}. (@bullet{}) - -@cindex Harmonic numbers -A more sophisticated kind of loop is the @dfn{for} loop. Suppose -we wish to compute the 20th ``harmonic'' number, which is equal to -the sum of the reciprocals of the integers from 1 to 20. - -@smallexample -@group -3: 0 1: 3.597739 -2: 1 . -1: 20 - . - -0 @key{RET} 1 @key{RET} 20 Z ( & + 1 Z ) -@end group -@end smallexample - -@noindent -The ``for'' loop pops two numbers, the lower and upper limits, then -repeats the body of the loop as an internal counter increases from -the lower limit to the upper one. Just before executing the loop -body, it pushes the current loop counter. When the loop body -finishes, it pops the ``step,'' i.e., the amount by which to -increment the loop counter. As you can see, our loop always -uses a step of one. - -This harmonic number function uses the stack to hold the running -total as well as for the various loop housekeeping functions. If -you find this disorienting, you can sum in a variable instead: - -@smallexample -@group -1: 0 2: 1 . 1: 3.597739 - . 1: 20 . - . - - 0 t 7 1 @key{RET} 20 Z ( & s + 7 1 Z ) r 7 -@end group -@end smallexample - -@noindent -The @kbd{s +} command adds the top-of-stack into the value in a -variable (and removes that value from the stack). - -It's worth noting that many jobs that call for a ``for'' loop can -also be done more easily by Calc's high-level operations. Two -other ways to compute harmonic numbers are to use vector mapping -and reduction (@kbd{v x 20}, then @w{@kbd{V M &}}, then @kbd{V R +}), -or to use the summation command @kbd{a +}. Both of these are -probably easier than using loops. However, there are some -situations where loops really are the way to go: - -(@bullet{}) @strong{Exercise 7.} Use a ``for'' loop to find the first -harmonic number which is greater than 4.0. -@xref{Programming Answer 7, 7}. (@bullet{}) - -Of course, if we're going to be using variables in our programs, -we have to worry about the programs clobbering values that the -caller was keeping in those same variables. This is easy to -fix, though: - -@smallexample -@group - . 1: 0.6667 1: 0.6667 3: 0.6667 - . . 2: 3.597739 - 1: 0.6667 - . - - Z ` p 4 @key{RET} 2 @key{RET} 3 / s 7 s s a @key{RET} Z ' r 7 s r a @key{RET} -@end group -@end smallexample - -@noindent -When we type @kbd{Z `} (that's a back-quote character), Calc saves -its mode settings and the contents of the ten ``quick variables'' -for later reference. When we type @kbd{Z '} (that's an apostrophe -now), Calc restores those saved values. Thus the @kbd{p 4} and -@kbd{s 7} commands have no effect outside this sequence. Wrapping -this around the body of a keyboard macro ensures that it doesn't -interfere with what the user of the macro was doing. Notice that -the contents of the stack, and the values of named variables, -survive past the @kbd{Z '} command. - -@cindex Bernoulli numbers, approximate -The @dfn{Bernoulli numbers} are a sequence with the interesting -property that all of the odd Bernoulli numbers are zero, and the -even ones, while difficult to compute, can be roughly approximated -by the formula -@texline @math{\displaystyle{2 n! \over (2 \pi)^n}}. -@infoline @expr{2 n!@: / (2 pi)^n}. -Let's write a keyboard macro to compute (approximate) Bernoulli numbers. -(Calc has a command, @kbd{k b}, to compute exact Bernoulli numbers, but -this command is very slow for large @expr{n} since the higher Bernoulli -numbers are very large fractions.) - -@smallexample -@group -1: 10 1: 0.0756823 - . . - - 10 C-x ( @key{RET} 2 % Z [ @key{DEL} 0 Z : ' 2 $! / (2 pi)^$ @key{RET} = Z ] C-x ) -@end group -@end smallexample - -@noindent -You can read @kbd{Z [} as ``then,'' @kbd{Z :} as ``else,'' and -@kbd{Z ]} as ``end-if.'' There is no need for an explicit ``if'' -command. For the purposes of @w{@kbd{Z [}}, the condition is ``true'' -if the value it pops from the stack is a nonzero number, or ``false'' -if it pops zero or something that is not a number (like a formula). -Here we take our integer argument modulo 2; this will be nonzero -if we're asking for an odd Bernoulli number. - -The actual tenth Bernoulli number is @expr{5/66}. - -@smallexample -@group -3: 0.0756823 1: 0 1: 0.25305 1: 0 1: 1.16659 -2: 5:66 . . . . -1: 0.0757575 - . - -10 k b @key{RET} c f M-0 @key{DEL} 11 X @key{DEL} 12 X @key{DEL} 13 X @key{DEL} 14 X -@end group -@end smallexample - -Just to exercise loops a bit more, let's compute a table of even -Bernoulli numbers. - -@smallexample -@group -3: [] 1: [0.10132, 0.03079, 0.02340, 0.033197, ...] -2: 2 . -1: 30 - . - - [ ] 2 @key{RET} 30 Z ( X | 2 Z ) -@end group -@end smallexample - -@noindent -The vertical-bar @kbd{|} is the vector-concatenation command. When -we execute it, the list we are building will be in stack level 2 -(initially this is an empty list), and the next Bernoulli number -will be in level 1. The effect is to append the Bernoulli number -onto the end of the list. (To create a table of exact fractional -Bernoulli numbers, just replace @kbd{X} with @kbd{k b} in the above -sequence of keystrokes.) - -With loops and conditionals, you can program essentially anything -in Calc. One other command that makes looping easier is @kbd{Z /}, -which takes a condition from the stack and breaks out of the enclosing -loop if the condition is true (non-zero). You can use this to make -``while'' and ``until'' style loops. - -If you make a mistake when entering a keyboard macro, you can edit -it using @kbd{Z E}. First, you must attach it to a key with @kbd{Z K}. -One technique is to enter a throwaway dummy definition for the macro, -then enter the real one in the edit command. - -@smallexample -@group -1: 3 1: 3 Calc Macro Edit Mode. - . . Original keys: 1 2 + - - 1 ;; calc digits - RET ;; calc-enter - 2 ;; calc digits - + ;; calc-plus - -C-x ( 1 @key{RET} 2 + C-x ) Z K h @key{RET} Z E h -@end group -@end smallexample - -@noindent -A keyboard macro is stored as a pure keystroke sequence. The -@file{edmacro} package (invoked by @kbd{Z E}) scans along the -macro and tries to decode it back into human-readable steps. -Descriptions of the keystrokes are given as comments, which begin with -@samp{;;}, and which are ignored when the edited macro is saved. -Spaces and line breaks are also ignored when the edited macro is saved. -To enter a space into the macro, type @code{SPC}. All the special -characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL}, -and @code{NUL} must be written in all uppercase, as must the prefixes -@code{C-} and @code{M-}. - -Let's edit in a new definition, for computing harmonic numbers. -First, erase the four lines of the old definition. Then, type -in the new definition (or use Emacs @kbd{M-w} and @kbd{C-y} commands -to copy it from this page of the Info file; you can of course skip -typing the comments, which begin with @samp{;;}). - -@smallexample -Z` ;; calc-kbd-push (Save local values) -0 ;; calc digits (Push a zero onto the stack) -st ;; calc-store-into (Store it in the following variable) -1 ;; calc quick variable (Quick variable q1) -1 ;; calc digits (Initial value for the loop) -TAB ;; calc-roll-down (Swap initial and final) -Z( ;; calc-kbd-for (Begin the "for" loop) -& ;; calc-inv (Take the reciprocal) -s+ ;; calc-store-plus (Add to the following variable) -1 ;; calc quick variable (Quick variable q1) -1 ;; calc digits (The loop step is 1) -Z) ;; calc-kbd-end-for (End the "for" loop) -sr ;; calc-recall (Recall the final accumulated value) -1 ;; calc quick variable (Quick variable q1) -Z' ;; calc-kbd-pop (Restore values) -@end smallexample - -@noindent -Press @kbd{C-c C-c} to finish editing and return to the Calculator. - -@smallexample -@group -1: 20 1: 3.597739 - . . - - 20 z h -@end group -@end smallexample - -The @file{edmacro} package defines a handy @code{read-kbd-macro} command -which reads the current region of the current buffer as a sequence of -keystroke names, and defines that sequence on the @kbd{X} -(and @kbd{C-x e}) key. Because this is so useful, Calc puts this -command on the @kbd{C-x * m} key. Try reading in this macro in the -following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at -one end of the text below, then type @kbd{C-x * m} at the other. - -@example -@group -Z ` 0 t 1 - 1 TAB - Z ( & s + 1 1 Z ) - r 1 -Z ' -@end group -@end example - -(@bullet{}) @strong{Exercise 8.} A general algorithm for solving -equations numerically is @dfn{Newton's Method}. Given the equation -@expr{f(x) = 0} for any function @expr{f}, and an initial guess -@expr{x_0} which is reasonably close to the desired solution, apply -this formula over and over: - -@ifnottex -@example -new_x = x - f(x)/f'(x) -@end example -@end ifnottex -@tex -\beforedisplay -$$ x_{\rm new} = x - {f(x) \over f^{\prime}(x)} $$ -\afterdisplay -@end tex - -@noindent -where @expr{f'(x)} is the derivative of @expr{f}. The @expr{x} -values will quickly converge to a solution, i.e., eventually -@texline @math{x_{\rm new}} -@infoline @expr{new_x} -and @expr{x} will be equal to within the limits -of the current precision. Write a program which takes a formula -involving the variable @expr{x}, and an initial guess @expr{x_0}, -on the stack, and produces a value of @expr{x} for which the formula -is zero. Use it to find a solution of -@texline @math{\sin(\cos x) = 0.5} -@infoline @expr{sin(cos(x)) = 0.5} -near @expr{x = 4.5}. (Use angles measured in radians.) Note that -the built-in @w{@kbd{a R}} (@code{calc-find-root}) command uses Newton's -method when it is able. @xref{Programming Answer 8, 8}. (@bullet{}) - -@cindex Digamma function -@cindex Gamma constant, Euler's -@cindex Euler's gamma constant -(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function -@texline @math{\psi(z) (``psi'')} -@infoline @expr{psi(z)} -is defined as the derivative of -@texline @math{\ln \Gamma(z)}. -@infoline @expr{ln(gamma(z))}. -For large values of @expr{z}, it can be approximated by the infinite sum - -@ifnottex -@example -psi(z) ~= ln(z) - 1/2z - sum(bern(2 n) / 2 n z^(2 n), n, 1, inf) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \psi(z) \approx \ln z - {1\over2z} - - \sum_{n=1}^\infty {\code{bern}(2 n) \over 2 n z^{2n}} -$$ -\afterdisplay -@end tex - -@noindent -where -@texline @math{\sum} -@infoline @expr{sum} -represents the sum over @expr{n} from 1 to infinity -(or to some limit high enough to give the desired accuracy), and -the @code{bern} function produces (exact) Bernoulli numbers. -While this sum is not guaranteed to converge, in practice it is safe. -An interesting mathematical constant is Euler's gamma, which is equal -to about 0.5772. One way to compute it is by the formula, -@texline @math{\gamma = -\psi(1)}. -@infoline @expr{gamma = -psi(1)}. -Unfortunately, 1 isn't a large enough argument -for the above formula to work (5 is a much safer value for @expr{z}). -Fortunately, we can compute -@texline @math{\psi(1)} -@infoline @expr{psi(1)} -from -@texline @math{\psi(5)} -@infoline @expr{psi(5)} -using the recurrence -@texline @math{\psi(z+1) = \psi(z) + {1 \over z}}. -@infoline @expr{psi(z+1) = psi(z) + 1/z}. -Your task: Develop a program to compute -@texline @math{\psi(z)}; -@infoline @expr{psi(z)}; -it should ``pump up'' @expr{z} -if necessary to be greater than 5, then use the above summation -formula. Use looping commands to compute the sum. Use your function -to compute -@texline @math{\gamma} -@infoline @expr{gamma} -to twelve decimal places. (Calc has a built-in command -for Euler's constant, @kbd{I P}, which you can use to check your answer.) -@xref{Programming Answer 9, 9}. (@bullet{}) - -@cindex Polynomial, list of coefficients -(@bullet{}) @strong{Exercise 10.} Given a polynomial in @expr{x} and -a number @expr{m} on the stack, where the polynomial is of degree -@expr{m} or less (i.e., does not have any terms higher than @expr{x^m}), -write a program to convert the polynomial into a list-of-coefficients -notation. For example, @expr{5 x^4 + (x + 1)^2} with @expr{m = 6} -should produce the list @expr{[1, 2, 1, 0, 5, 0, 0]}. Also develop -a way to convert from this form back to the standard algebraic form. -@xref{Programming Answer 10, 10}. (@bullet{}) - -@cindex Recursion -(@bullet{}) @strong{Exercise 11.} The @dfn{Stirling numbers of the -first kind} are defined by the recurrences, - -@ifnottex -@example -s(n,n) = 1 for n >= 0, -s(n,0) = 0 for n > 0, -s(n+1,m) = s(n,m-1) - n s(n,m) for n >= m >= 1. -@end example -@end ifnottex -@tex -\beforedisplay -$$ \eqalign{ s(n,n) &= 1 \qquad \hbox{for } n \ge 0, \cr - s(n,0) &= 0 \qquad \hbox{for } n > 0, \cr - s(n+1,m) &= s(n,m-1) - n \, s(n,m) \qquad - \hbox{for } n \ge m \ge 1.} -$$ -\afterdisplay -\vskip5pt -(These numbers are also sometimes written $\displaystyle{n \brack m}$.) -@end tex - -This can be implemented using a @dfn{recursive} program in Calc; the -program must invoke itself in order to calculate the two righthand -terms in the general formula. Since it always invokes itself with -``simpler'' arguments, it's easy to see that it must eventually finish -the computation. Recursion is a little difficult with Emacs keyboard -macros since the macro is executed before its definition is complete. -So here's the recommended strategy: Create a ``dummy macro'' and assign -it to a key with, e.g., @kbd{Z K s}. Now enter the true definition, -using the @kbd{z s} command to call itself recursively, then assign it -to the same key with @kbd{Z K s}. Now the @kbd{z s} command will run -the complete recursive program. (Another way is to use @w{@kbd{Z E}} -or @kbd{C-x * m} (@code{read-kbd-macro}) to read the whole macro at once, -thus avoiding the ``training'' phase.) The task: Write a program -that computes Stirling numbers of the first kind, given @expr{n} and -@expr{m} on the stack. Test it with @emph{small} inputs like -@expr{s(4,2)}. (There is a built-in command for Stirling numbers, -@kbd{k s}, which you can use to check your answers.) -@xref{Programming Answer 11, 11}. (@bullet{}) - -The programming commands we've seen in this part of the tutorial -are low-level, general-purpose operations. Often you will find -that a higher-level function, such as vector mapping or rewrite -rules, will do the job much more easily than a detailed, step-by-step -program can: - -(@bullet{}) @strong{Exercise 12.} Write another program for -computing Stirling numbers of the first kind, this time using -rewrite rules. Once again, @expr{n} and @expr{m} should be taken -from the stack. @xref{Programming Answer 12, 12}. (@bullet{}) - -@example - -@end example -This ends the tutorial section of the Calc manual. Now you know enough -about Calc to use it effectively for many kinds of calculations. But -Calc has many features that were not even touched upon in this tutorial. -@c [not-split] -The rest of this manual tells the whole story. -@c [when-split] -@c Volume II of this manual, the @dfn{Calc Reference}, tells the whole story. - -@page -@node Answers to Exercises, , Programming Tutorial, Tutorial -@section Answers to Exercises - -@noindent -This section includes answers to all the exercises in the Calc tutorial. - -@menu -* RPN Answer 1:: 1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * - -* RPN Answer 2:: 2*4 + 7*9.5 + 5/4 -* RPN Answer 3:: Operating on levels 2 and 3 -* RPN Answer 4:: Joe's complex problems -* Algebraic Answer 1:: Simulating Q command -* Algebraic Answer 2:: Joe's algebraic woes -* Algebraic Answer 3:: 1 / 0 -* Modes Answer 1:: 3#0.1 = 3#0.0222222? -* Modes Answer 2:: 16#f.e8fe15 -* Modes Answer 3:: Joe's rounding bug -* Modes Answer 4:: Why floating point? -* Arithmetic Answer 1:: Why the \ command? -* Arithmetic Answer 2:: Tripping up the B command -* Vector Answer 1:: Normalizing a vector -* Vector Answer 2:: Average position -* Matrix Answer 1:: Row and column sums -* Matrix Answer 2:: Symbolic system of equations -* Matrix Answer 3:: Over-determined system -* List Answer 1:: Powers of two -* List Answer 2:: Least-squares fit with matrices -* List Answer 3:: Geometric mean -* List Answer 4:: Divisor function -* List Answer 5:: Duplicate factors -* List Answer 6:: Triangular list -* List Answer 7:: Another triangular list -* List Answer 8:: Maximum of Bessel function -* List Answer 9:: Integers the hard way -* List Answer 10:: All elements equal -* List Answer 11:: Estimating pi with darts -* List Answer 12:: Estimating pi with matchsticks -* List Answer 13:: Hash codes -* List Answer 14:: Random walk -* Types Answer 1:: Square root of pi times rational -* Types Answer 2:: Infinities -* Types Answer 3:: What can "nan" be? -* Types Answer 4:: Abbey Road -* Types Answer 5:: Friday the 13th -* Types Answer 6:: Leap years -* Types Answer 7:: Erroneous donut -* Types Answer 8:: Dividing intervals -* Types Answer 9:: Squaring intervals -* Types Answer 10:: Fermat's primality test -* Types Answer 11:: pi * 10^7 seconds -* Types Answer 12:: Abbey Road on CD -* Types Answer 13:: Not quite pi * 10^7 seconds -* Types Answer 14:: Supercomputers and c -* Types Answer 15:: Sam the Slug -* Algebra Answer 1:: Squares and square roots -* Algebra Answer 2:: Building polynomial from roots -* Algebra Answer 3:: Integral of x sin(pi x) -* Algebra Answer 4:: Simpson's rule -* Rewrites Answer 1:: Multiplying by conjugate -* Rewrites Answer 2:: Alternative fib rule -* Rewrites Answer 3:: Rewriting opt(a) + opt(b) x -* Rewrites Answer 4:: Sequence of integers -* Rewrites Answer 5:: Number of terms in sum -* Rewrites Answer 6:: Truncated Taylor series -* Programming Answer 1:: Fresnel's C(x) -* Programming Answer 2:: Negate third stack element -* Programming Answer 3:: Compute sin(x) / x, etc. -* Programming Answer 4:: Average value of a list -* Programming Answer 5:: Continued fraction phi -* Programming Answer 6:: Matrix Fibonacci numbers -* Programming Answer 7:: Harmonic number greater than 4 -* Programming Answer 8:: Newton's method -* Programming Answer 9:: Digamma function -* Programming Answer 10:: Unpacking a polynomial -* Programming Answer 11:: Recursive Stirling numbers -* Programming Answer 12:: Stirling numbers with rewrites -@end menu - -@c The following kludgery prevents the individual answers from -@c being entered on the table of contents. -@tex -\global\let\oldwrite=\write -\gdef\skipwrite#1#2{\let\write=\oldwrite} -\global\let\oldchapternofonts=\chapternofonts -\gdef\chapternofonts{\let\write=\skipwrite\oldchapternofonts} -@end tex - -@node RPN Answer 1, RPN Answer 2, Answers to Exercises, Answers to Exercises -@subsection RPN Tutorial Exercise 1 - -@noindent -@kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -} - -The result is -@texline @math{1 - (2 \times (3 + 4)) = -13}. -@infoline @expr{1 - (2 * (3 + 4)) = -13}. - -@node RPN Answer 2, RPN Answer 3, RPN Answer 1, Answers to Exercises -@subsection RPN Tutorial Exercise 2 - -@noindent -@texline @math{2\times4 + 7\times9.5 + {5\over4} = 75.75} -@infoline @expr{2*4 + 7*9.5 + 5/4 = 75.75} - -After computing the intermediate term -@texline @math{2\times4 = 8}, -@infoline @expr{2*4 = 8}, -you can leave that result on the stack while you compute the second -term. With both of these results waiting on the stack you can then -compute the final term, then press @kbd{+ +} to add everything up. - -@smallexample -@group -2: 2 1: 8 3: 8 2: 8 -1: 4 . 2: 7 1: 66.5 - . 1: 9.5 . - . - - 2 @key{RET} 4 * 7 @key{RET} 9.5 * - -@end group -@end smallexample -@noindent -@smallexample -@group -4: 8 3: 8 2: 8 1: 75.75 -3: 66.5 2: 66.5 1: 67.75 . -2: 5 1: 1.25 . -1: 4 . - . - - 5 @key{RET} 4 / + + -@end group -@end smallexample - -Alternatively, you could add the first two terms before going on -with the third term. - -@smallexample -@group -2: 8 1: 74.5 3: 74.5 2: 74.5 1: 75.75 -1: 66.5 . 2: 5 1: 1.25 . - . 1: 4 . - . - - ... + 5 @key{RET} 4 / + -@end group -@end smallexample - -On an old-style RPN calculator this second method would have the -advantage of using only three stack levels. But since Calc's stack -can grow arbitrarily large this isn't really an issue. Which method -you choose is purely a matter of taste. - -@node RPN Answer 3, RPN Answer 4, RPN Answer 2, Answers to Exercises -@subsection RPN Tutorial Exercise 3 - -@noindent -The @key{TAB} key provides a way to operate on the number in level 2. - -@smallexample -@group -3: 10 3: 10 4: 10 3: 10 3: 10 -2: 20 2: 30 3: 30 2: 30 2: 21 -1: 30 1: 20 2: 20 1: 21 1: 30 - . . 1: 1 . . - . - - @key{TAB} 1 + @key{TAB} -@end group -@end smallexample - -Similarly, @kbd{M-@key{TAB}} gives you access to the number in level 3. - -@smallexample -@group -3: 10 3: 21 3: 21 3: 30 3: 11 -2: 21 2: 30 2: 30 2: 11 2: 21 -1: 30 1: 10 1: 11 1: 21 1: 30 - . . . . . - - M-@key{TAB} 1 + M-@key{TAB} M-@key{TAB} -@end group -@end smallexample - -@node RPN Answer 4, Algebraic Answer 1, RPN Answer 3, Answers to Exercises -@subsection RPN Tutorial Exercise 4 - -@noindent -Either @kbd{( 2 , 3 )} or @kbd{( 2 @key{SPC} 3 )} would have worked, -but using both the comma and the space at once yields: - -@smallexample -@group -1: ( ... 2: ( ... 1: (2, ... 2: (2, ... 2: (2, ... - . 1: 2 . 1: (2, ... 1: (2, 3) - . . . - - ( 2 , @key{SPC} 3 ) -@end group -@end smallexample - -Joe probably tried to type @kbd{@key{TAB} @key{DEL}} to swap the -extra incomplete object to the top of the stack and delete it. -But a feature of Calc is that @key{DEL} on an incomplete object -deletes just one component out of that object, so he had to press -@key{DEL} twice to finish the job. - -@smallexample -@group -2: (2, ... 2: (2, 3) 2: (2, 3) 1: (2, 3) -1: (2, 3) 1: (2, ... 1: ( ... . - . . . - - @key{TAB} @key{DEL} @key{DEL} -@end group -@end smallexample - -(As it turns out, deleting the second-to-top stack entry happens often -enough that Calc provides a special key, @kbd{M-@key{DEL}}, to do just that. -@kbd{M-@key{DEL}} is just like @kbd{@key{TAB} @key{DEL}}, except that it doesn't exhibit -the ``feature'' that tripped poor Joe.) - -@node Algebraic Answer 1, Algebraic Answer 2, RPN Answer 4, Answers to Exercises -@subsection Algebraic Entry Tutorial Exercise 1 - -@noindent -Type @kbd{' sqrt($) @key{RET}}. - -If the @kbd{Q} key is broken, you could use @kbd{' $^0.5 @key{RET}}. -Or, RPN style, @kbd{0.5 ^}. - -(Actually, @samp{$^1:2}, using the fraction one-half as the power, is -a closer equivalent, since @samp{9^0.5} yields @expr{3.0} whereas -@samp{sqrt(9)} and @samp{9^1:2} yield the exact integer @expr{3}.) - -@node Algebraic Answer 2, Algebraic Answer 3, Algebraic Answer 1, Answers to Exercises -@subsection Algebraic Entry Tutorial Exercise 2 - -@noindent -In the formula @samp{2 x (1+y)}, @samp{x} was interpreted as a function -name with @samp{1+y} as its argument. Assigning a value to a variable -has no relation to a function by the same name. Joe needed to use an -explicit @samp{*} symbol here: @samp{2 x*(1+y)}. - -@node Algebraic Answer 3, Modes Answer 1, Algebraic Answer 2, Answers to Exercises -@subsection Algebraic Entry Tutorial Exercise 3 - -@noindent -The result from @kbd{1 @key{RET} 0 /} will be the formula @expr{1 / 0}. -The ``function'' @samp{/} cannot be evaluated when its second argument -is zero, so it is left in symbolic form. When you now type @kbd{0 *}, -the result will be zero because Calc uses the general rule that ``zero -times anything is zero.'' - -@c [fix-ref Infinities] -The @kbd{m i} command enables an @dfn{Infinite mode} in which @expr{1 / 0} -results in a special symbol that represents ``infinity.'' If you -multiply infinity by zero, Calc uses another special new symbol to -show that the answer is ``indeterminate.'' @xref{Infinities}, for -further discussion of infinite and indeterminate values. - -@node Modes Answer 1, Modes Answer 2, Algebraic Answer 3, Answers to Exercises -@subsection Modes Tutorial Exercise 1 - -@noindent -Calc always stores its numbers in decimal, so even though one-third has -an exact base-3 representation (@samp{3#0.1}), it is still stored as -0.3333333 (chopped off after 12 or however many decimal digits) inside -the calculator's memory. When this inexact number is converted back -to base 3 for display, it may still be slightly inexact. When we -multiply this number by 3, we get 0.999999, also an inexact value. - -When Calc displays a number in base 3, it has to decide how many digits -to show. If the current precision is 12 (decimal) digits, that corresponds -to @samp{12 / log10(3) = 25.15} base-3 digits. Because 25.15 is not an -exact integer, Calc shows only 25 digits, with the result that stored -numbers carry a little bit of extra information that may not show up on -the screen. When Joe entered @samp{3#0.2}, the stored number 0.666666 -happened to round to a pleasing value when it lost that last 0.15 of a -digit, but it was still inexact in Calc's memory. When he divided by 2, -he still got the dreaded inexact value 0.333333. (Actually, he divided -0.666667 by 2 to get 0.333334, which is why he got something a little -higher than @code{3#0.1} instead of a little lower.) - -If Joe didn't want to be bothered with all this, he could have typed -@kbd{M-24 d n} to display with one less digit than the default. (If -you give @kbd{d n} a negative argument, it uses default-minus-that, -so @kbd{M-- d n} would be an easier way to get the same effect.) Those -inexact results would still be lurking there, but they would now be -rounded to nice, natural-looking values for display purposes. (Remember, -@samp{0.022222} in base 3 is like @samp{0.099999} in base 10; rounding -off one digit will round the number up to @samp{0.1}.) Depending on the -nature of your work, this hiding of the inexactness may be a benefit or -a danger. With the @kbd{d n} command, Calc gives you the choice. - -Incidentally, another consequence of all this is that if you type -@kbd{M-30 d n} to display more digits than are ``really there,'' -you'll see garbage digits at the end of the number. (In decimal -display mode, with decimally-stored numbers, these garbage digits are -always zero so they vanish and you don't notice them.) Because Calc -rounds off that 0.15 digit, there is the danger that two numbers could -be slightly different internally but still look the same. If you feel -uneasy about this, set the @kbd{d n} precision to be a little higher -than normal; you'll get ugly garbage digits, but you'll always be able -to tell two distinct numbers apart. - -An interesting side note is that most computers store their -floating-point numbers in binary, and convert to decimal for display. -Thus everyday programs have the same problem: Decimal 0.1 cannot be -represented exactly in binary (try it: @kbd{0.1 d 2}), so @samp{0.1 * 10} -comes out as an inexact approximation to 1 on some machines (though -they generally arrange to hide it from you by rounding off one digit as -we did above). Because Calc works in decimal instead of binary, you can -be sure that numbers that look exact @emph{are} exact as long as you stay -in decimal display mode. - -It's not hard to show that any number that can be represented exactly -in binary, octal, or hexadecimal is also exact in decimal, so the kinds -of problems we saw in this exercise are likely to be severe only when -you use a relatively unusual radix like 3. - -@node Modes Answer 2, Modes Answer 3, Modes Answer 1, Answers to Exercises -@subsection Modes Tutorial Exercise 2 - -If the radix is 15 or higher, we can't use the letter @samp{e} to mark -the exponent because @samp{e} is interpreted as a digit. When Calc -needs to display scientific notation in a high radix, it writes -@samp{16#F.E8F*16.^15}. You can enter a number like this as an -algebraic entry. Also, pressing @kbd{e} without any digits before it -normally types @kbd{1e}, but in a high radix it types @kbd{16.^} and -puts you in algebraic entry: @kbd{16#f.e8f @key{RET} e 15 @key{RET} *} is another -way to enter this number. - -The reason Calc puts a decimal point in the @samp{16.^} is to prevent -huge integers from being generated if the exponent is large (consider -@samp{16#1.23*16^1000}, where we compute @samp{16^1000} as a giant -exact integer and then throw away most of the digits when we multiply -it by the floating-point @samp{16#1.23}). While this wouldn't normally -matter for display purposes, it could give you a nasty surprise if you -copied that number into a file and later moved it back into Calc. - -@node Modes Answer 3, Modes Answer 4, Modes Answer 2, Answers to Exercises -@subsection Modes Tutorial Exercise 3 - -@noindent -The answer he got was @expr{0.5000000000006399}. - -The problem is not that the square operation is inexact, but that the -sine of 45 that was already on the stack was accurate to only 12 places. -Arbitrary-precision calculations still only give answers as good as -their inputs. - -The real problem is that there is no 12-digit number which, when -squared, comes out to 0.5 exactly. The @kbd{f [} and @kbd{f ]} -commands decrease or increase a number by one unit in the last -place (according to the current precision). They are useful for -determining facts like this. - -@smallexample -@group -1: 0.707106781187 1: 0.500000000001 - . . - - 45 S 2 ^ - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 0.707106781187 1: 0.707106781186 1: 0.499999999999 - . . . - - U @key{DEL} f [ 2 ^ -@end group -@end smallexample - -A high-precision calculation must be carried out in high precision -all the way. The only number in the original problem which was known -exactly was the quantity 45 degrees, so the precision must be raised -before anything is done after the number 45 has been entered in order -for the higher precision to be meaningful. - -@node Modes Answer 4, Arithmetic Answer 1, Modes Answer 3, Answers to Exercises -@subsection Modes Tutorial Exercise 4 - -@noindent -Many calculations involve real-world quantities, like the width and -height of a piece of wood or the volume of a jar. Such quantities -can't be measured exactly anyway, and if the data that is input to -a calculation is inexact, doing exact arithmetic on it is a waste -of time. - -Fractions become unwieldy after too many calculations have been -done with them. For example, the sum of the reciprocals of the -integers from 1 to 10 is 7381:2520. The sum from 1 to 30 is -9304682830147:2329089562800. After a point it will take a long -time to add even one more term to this sum, but a floating-point -calculation of the sum will not have this problem. - -Also, rational numbers cannot express the results of all calculations. -There is no fractional form for the square root of two, so if you type -@w{@kbd{2 Q}}, Calc has no choice but to give you a floating-point answer. - -@node Arithmetic Answer 1, Arithmetic Answer 2, Modes Answer 4, Answers to Exercises -@subsection Arithmetic Tutorial Exercise 1 - -@noindent -Dividing two integers that are larger than the current precision may -give a floating-point result that is inaccurate even when rounded -down to an integer. Consider @expr{123456789 / 2} when the current -precision is 6 digits. The true answer is @expr{61728394.5}, but -with a precision of 6 this will be rounded to -@texline @math{12345700.0/2.0 = 61728500.0}. -@infoline @expr{12345700.@: / 2.@: = 61728500.}. -The result, when converted to an integer, will be off by 106. - -Here are two solutions: Raise the precision enough that the -floating-point round-off error is strictly to the right of the -decimal point. Or, convert to Fraction mode so that @expr{123456789 / 2} -produces the exact fraction @expr{123456789:2}, which can be rounded -down by the @kbd{F} command without ever switching to floating-point -format. - -@node Arithmetic Answer 2, Vector Answer 1, Arithmetic Answer 1, Answers to Exercises -@subsection Arithmetic Tutorial Exercise 2 - -@noindent -@kbd{27 @key{RET} 9 B} could give the exact result @expr{3:2}, but it -does a floating-point calculation instead and produces @expr{1.5}. - -Calc will find an exact result for a logarithm if the result is an integer -or (when in Fraction mode) the reciprocal of an integer. But there is -no efficient way to search the space of all possible rational numbers -for an exact answer, so Calc doesn't try. - -@node Vector Answer 1, Vector Answer 2, Arithmetic Answer 2, Answers to Exercises -@subsection Vector Tutorial Exercise 1 - -@noindent -Duplicate the vector, compute its length, then divide the vector -by its length: @kbd{@key{RET} A /}. - -@smallexample -@group -1: [1, 2, 3] 2: [1, 2, 3] 1: [0.27, 0.53, 0.80] 1: 1. - . 1: 3.74165738677 . . - . - - r 1 @key{RET} A / A -@end group -@end smallexample - -The final @kbd{A} command shows that the normalized vector does -indeed have unit length. - -@node Vector Answer 2, Matrix Answer 1, Vector Answer 1, Answers to Exercises -@subsection Vector Tutorial Exercise 2 - -@noindent -The average position is equal to the sum of the products of the -positions times their corresponding probabilities. This is the -definition of the dot product operation. So all you need to do -is to put the two vectors on the stack and press @kbd{*}. - -@node Matrix Answer 1, Matrix Answer 2, Vector Answer 2, Answers to Exercises -@subsection Matrix Tutorial Exercise 1 - -@noindent -The trick is to multiply by a vector of ones. Use @kbd{r 4 [1 1 1] *} to -get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum. - -@node Matrix Answer 2, Matrix Answer 3, Matrix Answer 1, Answers to Exercises -@subsection Matrix Tutorial Exercise 2 - -@ifnottex -@example -@group - x + a y = 6 - x + b y = 10 -@end group -@end example -@end ifnottex -@tex -\beforedisplay -$$ \eqalign{ x &+ a y = 6 \cr - x &+ b y = 10} -$$ -\afterdisplay -@end tex - -Just enter the righthand side vector, then divide by the lefthand side -matrix as usual. - -@smallexample -@group -1: [6, 10] 2: [6, 10] 1: [4 a / (a - b) + 6, 4 / (b - a) ] - . 1: [ [ 1, a ] . - [ 1, b ] ] - . - -' [6 10] @key{RET} ' [1 a; 1 b] @key{RET} / -@end group -@end smallexample - -This can be made more readable using @kbd{d B} to enable Big display -mode: - -@smallexample -@group - 4 a 4 -1: [----- + 6, -----] - a - b b - a -@end group -@end smallexample - -Type @kbd{d N} to return to Normal display mode afterwards. - -@node Matrix Answer 3, List Answer 1, Matrix Answer 2, Answers to Exercises -@subsection Matrix Tutorial Exercise 3 - -@noindent -To solve -@texline @math{A^T A \, X = A^T B}, -@infoline @expr{trn(A) * A * X = trn(A) * B}, -first we compute -@texline @math{A' = A^T A} -@infoline @expr{A2 = trn(A) * A} -and -@texline @math{B' = A^T B}; -@infoline @expr{B2 = trn(A) * B}; -now, we have a system -@texline @math{A' X = B'} -@infoline @expr{A2 * X = B2} -which we can solve using Calc's @samp{/} command. - -@ifnottex -@example -@group - a + 2b + 3c = 6 - 4a + 5b + 6c = 2 - 7a + 6b = 3 - 2a + 4b + 6c = 11 -@end group -@end example -@end ifnottex -@tex -\beforedisplayh -$$ \openup1\jot \tabskip=0pt plus1fil -\halign to\displaywidth{\tabskip=0pt - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr - a&+&2b&+&3c&=6 \cr - 4a&+&5b&+&6c&=2 \cr - 7a&+&6b& & &=3 \cr - 2a&+&4b&+&6c&=11 \cr} -$$ -\afterdisplayh -@end tex - -The first step is to enter the coefficient matrix. We'll store it in -quick variable number 7 for later reference. Next, we compute the -@texline @math{B'} -@infoline @expr{B2} -vector. - -@smallexample -@group -1: [ [ 1, 2, 3 ] 2: [ [ 1, 4, 7, 2 ] 1: [57, 84, 96] - [ 4, 5, 6 ] [ 2, 5, 6, 4 ] . - [ 7, 6, 0 ] [ 3, 6, 0, 6 ] ] - [ 2, 4, 6 ] ] 1: [6, 2, 3, 11] - . . - -' [1 2 3; 4 5 6; 7 6 0; 2 4 6] @key{RET} s 7 v t [6 2 3 11] * -@end group -@end smallexample - -@noindent -Now we compute the matrix -@texline @math{A'} -@infoline @expr{A2} -and divide. - -@smallexample -@group -2: [57, 84, 96] 1: [-11.64, 14.08, -3.64] -1: [ [ 70, 72, 39 ] . - [ 72, 81, 60 ] - [ 39, 60, 81 ] ] - . - - r 7 v t r 7 * / -@end group -@end smallexample - -@noindent -(The actual computed answer will be slightly inexact due to -round-off error.) - -Notice that the answers are similar to those for the -@texline @math{3\times3} -@infoline 3x3 -system solved in the text. That's because the fourth equation that was -added to the system is almost identical to the first one multiplied -by two. (If it were identical, we would have gotten the exact same -answer since the -@texline @math{4\times3} -@infoline 4x3 -system would be equivalent to the original -@texline @math{3\times3} -@infoline 3x3 -system.) - -Since the first and fourth equations aren't quite equivalent, they -can't both be satisfied at once. Let's plug our answers back into -the original system of equations to see how well they match. - -@smallexample -@group -2: [-11.64, 14.08, -3.64] 1: [5.6, 2., 3., 11.2] -1: [ [ 1, 2, 3 ] . - [ 4, 5, 6 ] - [ 7, 6, 0 ] - [ 2, 4, 6 ] ] - . - - r 7 @key{TAB} * -@end group -@end smallexample - -@noindent -This is reasonably close to our original @expr{B} vector, -@expr{[6, 2, 3, 11]}. - -@node List Answer 1, List Answer 2, Matrix Answer 3, Answers to Exercises -@subsection List Tutorial Exercise 1 - -@noindent -We can use @kbd{v x} to build a vector of integers. This needs to be -adjusted to get the range of integers we desire. Mapping @samp{-} -across the vector will accomplish this, although it turns out the -plain @samp{-} key will work just as well. - -@smallexample -@group -2: 2 2: 2 -1: [1, 2, 3, 4, 5, 6, 7, 8, 9] 1: [-4, -3, -2, -1, 0, 1, 2, 3, 4] - . . - - 2 v x 9 @key{RET} 5 V M - or 5 - -@end group -@end smallexample - -@noindent -Now we use @kbd{V M ^} to map the exponentiation operator across the -vector. - -@smallexample -@group -1: [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16] - . - - V M ^ -@end group -@end smallexample - -@node List Answer 2, List Answer 3, List Answer 1, Answers to Exercises -@subsection List Tutorial Exercise 2 - -@noindent -Given @expr{x} and @expr{y} vectors in quick variables 1 and 2 as before, -the first job is to form the matrix that describes the problem. - -@ifnottex -@example - m*x + b*1 = y -@end example -@end ifnottex -@tex -\beforedisplay -$$ m \times x + b \times 1 = y $$ -\afterdisplay -@end tex - -Thus we want a -@texline @math{19\times2} -@infoline 19x2 -matrix with our @expr{x} vector as one column and -ones as the other column. So, first we build the column of ones, then -we combine the two columns to form our @expr{A} matrix. - -@smallexample -@group -2: [1.34, 1.41, 1.49, ... ] 1: [ [ 1.34, 1 ] -1: [1, 1, 1, ...] [ 1.41, 1 ] - . [ 1.49, 1 ] - @dots{} - - r 1 1 v b 19 @key{RET} M-2 v p v t s 3 -@end group -@end smallexample - -@noindent -Now we compute -@texline @math{A^T y} -@infoline @expr{trn(A) * y} -and -@texline @math{A^T A} -@infoline @expr{trn(A) * A} -and divide. - -@smallexample -@group -1: [33.36554, 13.613] 2: [33.36554, 13.613] - . 1: [ [ 98.0003, 41.63 ] - [ 41.63, 19 ] ] - . - - v t r 2 * r 3 v t r 3 * -@end group -@end smallexample - -@noindent -(Hey, those numbers look familiar!) - -@smallexample -@group -1: [0.52141679, -0.425978] - . - - / -@end group -@end smallexample - -Since we were solving equations of the form -@texline @math{m \times x + b \times 1 = y}, -@infoline @expr{m*x + b*1 = y}, -these numbers should be @expr{m} and @expr{b}, respectively. Sure -enough, they agree exactly with the result computed using @kbd{V M} and -@kbd{V R}! - -The moral of this story: @kbd{V M} and @kbd{V R} will probably solve -your problem, but there is often an easier way using the higher-level -arithmetic functions! - -@c [fix-ref Curve Fitting] -In fact, there is a built-in @kbd{a F} command that does least-squares -fits. @xref{Curve Fitting}. - -@node List Answer 3, List Answer 4, List Answer 2, Answers to Exercises -@subsection List Tutorial Exercise 3 - -@noindent -Move to one end of the list and press @kbd{C-@@} (or @kbd{C-@key{SPC}} or -whatever) to set the mark, then move to the other end of the list -and type @w{@kbd{C-x * g}}. - -@smallexample -@group -1: [2.3, 6, 22, 15.1, 7, 15, 14, 7.5, 2.5] - . -@end group -@end smallexample - -To make things interesting, let's assume we don't know at a glance -how many numbers are in this list. Then we could type: - -@smallexample -@group -2: [2.3, 6, 22, ... ] 2: [2.3, 6, 22, ... ] -1: [2.3, 6, 22, ... ] 1: 126356422.5 - . . - - @key{RET} V R * - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 126356422.5 2: 126356422.5 1: 7.94652913734 -1: [2.3, 6, 22, ... ] 1: 9 . - . . - - @key{TAB} v l I ^ -@end group -@end smallexample - -@noindent -(The @kbd{I ^} command computes the @var{n}th root of a number. -You could also type @kbd{& ^} to take the reciprocal of 9 and -then raise the number to that power.) - -@node List Answer 4, List Answer 5, List Answer 3, Answers to Exercises -@subsection List Tutorial Exercise 4 - -@noindent -A number @expr{j} is a divisor of @expr{n} if -@texline @math{n \mathbin{\hbox{\code{\%}}} j = 0}. -@infoline @samp{n % j = 0}. -The first step is to get a vector that identifies the divisors. - -@smallexample -@group -2: 30 2: [0, 0, 0, 2, ...] 1: [1, 1, 1, 0, ...] -1: [1, 2, 3, 4, ...] 1: 0 . - . . - - 30 @key{RET} v x 30 @key{RET} s 1 V M % 0 V M a = s 2 -@end group -@end smallexample - -@noindent -This vector has 1's marking divisors of 30 and 0's marking non-divisors. - -The zeroth divisor function is just the total number of divisors. -The first divisor function is the sum of the divisors. - -@smallexample -@group -1: 8 3: 8 2: 8 2: 8 - 2: [1, 2, 3, 4, ...] 1: [1, 2, 3, 0, ...] 1: 72 - 1: [1, 1, 1, 0, ...] . . - . - - V R + r 1 r 2 V M * V R + -@end group -@end smallexample - -@noindent -Once again, the last two steps just compute a dot product for which -a simple @kbd{*} would have worked equally well. - -@node List Answer 5, List Answer 6, List Answer 4, Answers to Exercises -@subsection List Tutorial Exercise 5 - -@noindent -The obvious first step is to obtain the list of factors with @kbd{k f}. -This list will always be in sorted order, so if there are duplicates -they will be right next to each other. A suitable method is to compare -the list with a copy of itself shifted over by one. - -@smallexample -@group -1: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19, 0] - . 1: [3, 7, 7, 7, 19, 0] 1: [0, 3, 7, 7, 7, 19] - . . - - 19551 k f @key{RET} 0 | @key{TAB} 0 @key{TAB} | - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0, 0, 1, 1, 0, 0] 1: 2 1: 0 - . . . - - V M a = V R + 0 a = -@end group -@end smallexample - -@noindent -Note that we have to arrange for both vectors to have the same length -so that the mapping operation works; no prime factor will ever be -zero, so adding zeros on the left and right is safe. From then on -the job is pretty straightforward. - -Incidentally, Calc provides the -@texline @dfn{M@"obius} @math{\mu} -@infoline @dfn{Moebius mu} -function which is zero if and only if its argument is square-free. It -would be a much more convenient way to do the above test in practice. - -@node List Answer 6, List Answer 7, List Answer 5, Answers to Exercises -@subsection List Tutorial Exercise 6 - -@noindent -First use @kbd{v x 6 @key{RET}} to get a list of integers, then @kbd{V M v x} -to get a list of lists of integers! - -@node List Answer 7, List Answer 8, List Answer 6, Answers to Exercises -@subsection List Tutorial Exercise 7 - -@noindent -Here's one solution. First, compute the triangular list from the previous -exercise and type @kbd{1 -} to subtract one from all the elements. - -@smallexample -@group -1: [ [0], - [0, 1], - [0, 1, 2], - @dots{} - - 1 - -@end group -@end smallexample - -The numbers down the lefthand edge of the list we desire are called -the ``triangular numbers'' (now you know why!). The @expr{n}th -triangular number is the sum of the integers from 1 to @expr{n}, and -can be computed directly by the formula -@texline @math{n (n+1) \over 2}. -@infoline @expr{n * (n+1) / 2}. - -@smallexample -@group -2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] -1: [0, 1, 2, 3, 4, 5] 1: [0, 1, 3, 6, 10, 15] - . . - - v x 6 @key{RET} 1 - V M ' $ ($+1)/2 @key{RET} -@end group -@end smallexample - -@noindent -Adding this list to the above list of lists produces the desired -result: - -@smallexample -@group -1: [ [0], - [1, 2], - [3, 4, 5], - [6, 7, 8, 9], - [10, 11, 12, 13, 14], - [15, 16, 17, 18, 19, 20] ] - . - - V M + -@end group -@end smallexample - -If we did not know the formula for triangular numbers, we could have -computed them using a @kbd{V U +} command. We could also have -gotten them the hard way by mapping a reduction across the original -triangular list. - -@smallexample -@group -2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] -1: [ [0], [0, 1], ... ] 1: [0, 1, 3, 6, 10, 15] - . . - - @key{RET} V M V R + -@end group -@end smallexample - -@noindent -(This means ``map a @kbd{V R +} command across the vector,'' and -since each element of the main vector is itself a small vector, -@kbd{V R +} computes the sum of its elements.) - -@node List Answer 8, List Answer 9, List Answer 7, Answers to Exercises -@subsection List Tutorial Exercise 8 - -@noindent -The first step is to build a list of values of @expr{x}. - -@smallexample -@group -1: [1, 2, 3, ..., 21] 1: [0, 1, 2, ..., 20] 1: [0, 0.25, 0.5, ..., 5] - . . . - - v x 21 @key{RET} 1 - 4 / s 1 -@end group -@end smallexample - -Next, we compute the Bessel function values. - -@smallexample -@group -1: [0., 0.124, 0.242, ..., -0.328] - . - - V M ' besJ(1,$) @key{RET} -@end group -@end smallexample - -@noindent -(Another way to do this would be @kbd{1 @key{TAB} V M f j}.) - -A way to isolate the maximum value is to compute the maximum using -@kbd{V R X}, then compare all the Bessel values with that maximum. - -@smallexample -@group -2: [0., 0.124, 0.242, ... ] 1: [0, 0, 0, ... ] 2: [0, 0, 0, ... ] -1: 0.5801562 . 1: 1 - . . - - @key{RET} V R X V M a = @key{RET} V R + @key{DEL} -@end group -@end smallexample - -@noindent -It's a good idea to verify, as in the last step above, that only -one value is equal to the maximum. (After all, a plot of -@texline @math{\sin x} -@infoline @expr{sin(x)} -might have many points all equal to the maximum value, 1.) - -The vector we have now has a single 1 in the position that indicates -the maximum value of @expr{x}. Now it is a simple matter to convert -this back into the corresponding value itself. - -@smallexample -@group -2: [0, 0, 0, ... ] 1: [0, 0., 0., ... ] 1: 1.75 -1: [0, 0.25, 0.5, ... ] . . - . - - r 1 V M * V R + -@end group -@end smallexample - -If @kbd{a =} had produced more than one @expr{1} value, this method -would have given the sum of all maximum @expr{x} values; not very -useful! In this case we could have used @kbd{v m} (@code{calc-mask-vector}) -instead. This command deletes all elements of a ``data'' vector that -correspond to zeros in a ``mask'' vector, leaving us with, in this -example, a vector of maximum @expr{x} values. - -The built-in @kbd{a X} command maximizes a function using more -efficient methods. Just for illustration, let's use @kbd{a X} -to maximize @samp{besJ(1,x)} over this same interval. - -@smallexample -@group -2: besJ(1, x) 1: [1.84115, 0.581865] -1: [0 .. 5] . - . - -' besJ(1,x), [0..5] @key{RET} a X x @key{RET} -@end group -@end smallexample - -@noindent -The output from @kbd{a X} is a vector containing the value of @expr{x} -that maximizes the function, and the function's value at that maximum. -As you can see, our simple search got quite close to the right answer. - -@node List Answer 9, List Answer 10, List Answer 8, Answers to Exercises -@subsection List Tutorial Exercise 9 - -@noindent -Step one is to convert our integer into vector notation. - -@smallexample -@group -1: 25129925999 3: 25129925999 - . 2: 10 - 1: [11, 10, 9, ..., 1, 0] - . - - 25129925999 @key{RET} 10 @key{RET} 12 @key{RET} v x 12 @key{RET} - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 25129925999 1: [0, 2, 25, 251, 2512, ... ] -2: [100000000000, ... ] . - . - - V M ^ s 1 V M \ -@end group -@end smallexample - -@noindent -(Recall, the @kbd{\} command computes an integer quotient.) - -@smallexample -@group -1: [0, 2, 5, 1, 2, 9, 9, 2, 5, 9, 9, 9] - . - - 10 V M % s 2 -@end group -@end smallexample - -Next we must increment this number. This involves adding one to -the last digit, plus handling carries. There is a carry to the -left out of a digit if that digit is a nine and all the digits to -the right of it are nines. - -@smallexample -@group -1: [0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1] 1: [1, 1, 1, 0, 0, 1, ... ] - . . - - 9 V M a = v v - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, 1, 1, 0, 0, 0, ... ] 1: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1] - . . - - V U * v v 1 | -@end group -@end smallexample - -@noindent -Accumulating @kbd{*} across a vector of ones and zeros will preserve -only the initial run of ones. These are the carries into all digits -except the rightmost digit. Concatenating a one on the right takes -care of aligning the carries properly, and also adding one to the -rightmost digit. - -@smallexample -@group -2: [0, 0, 0, 0, ... ] 1: [0, 0, 2, 5, 1, 2, 9, 9, 2, 6, 0, 0, 0] -1: [0, 0, 2, 5, ... ] . - . - - 0 r 2 | V M + 10 V M % -@end group -@end smallexample - -@noindent -Here we have concatenated 0 to the @emph{left} of the original number; -this takes care of shifting the carries by one with respect to the -digits that generated them. - -Finally, we must convert this list back into an integer. - -@smallexample -@group -3: [0, 0, 2, 5, ... ] 2: [0, 0, 2, 5, ... ] -2: 1000000000000 1: [1000000000000, 100000000000, ... ] -1: [100000000000, ... ] . - . - - 10 @key{RET} 12 ^ r 1 | - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0, 0, 20000000000, 5000000000, ... ] 1: 25129926000 - . . - - V M * V R + -@end group -@end smallexample - -@noindent -Another way to do this final step would be to reduce the formula -@w{@samp{10 $$ + $}} across the vector of digits. - -@smallexample -@group -1: [0, 0, 2, 5, ... ] 1: 25129926000 - . . - - V R ' 10 $$ + $ @key{RET} -@end group -@end smallexample - -@node List Answer 10, List Answer 11, List Answer 9, Answers to Exercises -@subsection List Tutorial Exercise 10 - -@noindent -For the list @expr{[a, b, c, d]}, the result is @expr{((a = b) = c) = d}, -which will compare @expr{a} and @expr{b} to produce a 1 or 0, which is -then compared with @expr{c} to produce another 1 or 0, which is then -compared with @expr{d}. This is not at all what Joe wanted. - -Here's a more correct method: - -@smallexample -@group -1: [7, 7, 7, 8, 7] 2: [7, 7, 7, 8, 7] - . 1: 7 - . - - ' [7,7,7,8,7] @key{RET} @key{RET} v r 1 @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, 1, 1, 0, 1] 1: 0 - . . - - V M a = V R * -@end group -@end smallexample - -@node List Answer 11, List Answer 12, List Answer 10, Answers to Exercises -@subsection List Tutorial Exercise 11 - -@noindent -The circle of unit radius consists of those points @expr{(x,y)} for which -@expr{x^2 + y^2 < 1}. We start by generating a vector of @expr{x^2} -and a vector of @expr{y^2}. - -We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} -commands. - -@smallexample -@group -2: [2., 2., ..., 2.] 2: [2., 2., ..., 2.] -1: [2., 2., ..., 2.] 1: [1.16, 1.98, ..., 0.81] - . . - - v . t . 2. v b 100 @key{RET} @key{RET} V M k r - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [2., 2., ..., 2.] 1: [0.026, 0.96, ..., 0.036] -1: [0.026, 0.96, ..., 0.036] 2: [0.53, 0.81, ..., 0.094] - . . - - 1 - 2 V M ^ @key{TAB} V M k r 1 - 2 V M ^ -@end group -@end smallexample - -Now we sum the @expr{x^2} and @expr{y^2} values, compare with 1 to -get a vector of 1/0 truth values, then sum the truth values. - -@smallexample -@group -1: [0.56, 1.78, ..., 0.13] 1: [1, 0, ..., 1] 1: 84 - . . . - - + 1 V M a < V R + -@end group -@end smallexample - -@noindent -The ratio @expr{84/100} should approximate the ratio @cpiover{4}. - -@smallexample -@group -1: 0.84 1: 3.36 2: 3.36 1: 1.0695 - . . 1: 3.14159 . - - 100 / 4 * P / -@end group -@end smallexample - -@noindent -Our estimate, 3.36, is off by about 7%. We could get a better estimate -by taking more points (say, 1000), but it's clear that this method is -not very efficient! - -(Naturally, since this example uses random numbers your own answer -will be slightly different from the one shown here!) - -If you typed @kbd{v .} and @kbd{t .} before, type them again to -return to full-sized display of vectors. - -@node List Answer 12, List Answer 13, List Answer 11, Answers to Exercises -@subsection List Tutorial Exercise 12 - -@noindent -This problem can be made a lot easier by taking advantage of some -symmetries. First of all, after some thought it's clear that the -@expr{y} axis can be ignored altogether. Just pick a random @expr{x} -component for one end of the match, pick a random direction -@texline @math{\theta}, -@infoline @expr{theta}, -and see if @expr{x} and -@texline @math{x + \cos \theta} -@infoline @expr{x + cos(theta)} -(which is the @expr{x} coordinate of the other endpoint) cross a line. -The lines are at integer coordinates, so this happens when the two -numbers surround an integer. - -Since the two endpoints are equivalent, we may as well choose the leftmost -of the two endpoints as @expr{x}. Then @expr{theta} is an angle pointing -to the right, in the range -90 to 90 degrees. (We could use radians, but -it would feel like cheating to refer to @cpiover{2} radians while trying -to estimate @cpi{}!) - -In fact, since the field of lines is infinite we can choose the -coordinates 0 and 1 for the lines on either side of the leftmost -endpoint. The rightmost endpoint will be between 0 and 1 if the -match does not cross a line, or between 1 and 2 if it does. So: -Pick random @expr{x} and -@texline @math{\theta}, -@infoline @expr{theta}, -compute -@texline @math{x + \cos \theta}, -@infoline @expr{x + cos(theta)}, -and count how many of the results are greater than one. Simple! - -We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} -commands. - -@smallexample -@group -1: [0.52, 0.71, ..., 0.72] 2: [0.52, 0.71, ..., 0.72] - . 1: [78.4, 64.5, ..., -42.9] - . - -v . t . 1. v b 100 @key{RET} V M k r 180. v b 100 @key{RET} V M k r 90 - -@end group -@end smallexample - -@noindent -(The next step may be slow, depending on the speed of your computer.) - -@smallexample -@group -2: [0.52, 0.71, ..., 0.72] 1: [0.72, 1.14, ..., 1.45] -1: [0.20, 0.43, ..., 0.73] . - . - - m d V M C + - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0, 1, ..., 1] 1: 0.64 1: 3.125 - . . . - - 1 V M a > V R + 100 / 2 @key{TAB} / -@end group -@end smallexample - -Let's try the third method, too. We'll use random integers up to -one million. The @kbd{k r} command with an integer argument picks -a random integer. - -@smallexample -@group -2: [1000000, 1000000, ..., 1000000] 2: [78489, 527587, ..., 814975] -1: [1000000, 1000000, ..., 1000000] 1: [324014, 358783, ..., 955450] - . . - - 1000000 v b 100 @key{RET} @key{RET} V M k r @key{TAB} V M k r - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, 1, ..., 25] 1: [1, 1, ..., 0] 1: 0.56 - . . . - - V M k g 1 V M a = V R + 100 / - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 10.714 1: 3.273 - . . - - 6 @key{TAB} / Q -@end group -@end smallexample - -For a proof of this property of the GCD function, see section 4.5.2, -exercise 10, of Knuth's @emph{Art of Computer Programming}, volume II. - -If you typed @kbd{v .} and @kbd{t .} before, type them again to -return to full-sized display of vectors. - -@node List Answer 13, List Answer 14, List Answer 12, Answers to Exercises -@subsection List Tutorial Exercise 13 - -@noindent -First, we put the string on the stack as a vector of ASCII codes. - -@smallexample -@group -1: [84, 101, 115, ..., 51] - . - - "Testing, 1, 2, 3 @key{RET} -@end group -@end smallexample - -@noindent -Note that the @kbd{"} key, like @kbd{$}, initiates algebraic entry so -there was no need to type an apostrophe. Also, Calc didn't mind that -we omitted the closing @kbd{"}. (The same goes for all closing delimiters -like @kbd{)} and @kbd{]} at the end of a formula. - -We'll show two different approaches here. In the first, we note that -if the input vector is @expr{[a, b, c, d]}, then the hash code is -@expr{3 (3 (3a + b) + c) + d = 27a + 9b + 3c + d}. In other words, -it's a sum of descending powers of three times the ASCII codes. - -@smallexample -@group -2: [84, 101, 115, ..., 51] 2: [84, 101, 115, ..., 51] -1: 16 1: [15, 14, 13, ..., 0] - . . - - @key{RET} v l v x 16 @key{RET} - - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [84, 101, 115, ..., 51] 1: 1960915098 1: 121 -1: [14348907, ..., 1] . . - . - - 3 @key{TAB} V M ^ * 511 % -@end group -@end smallexample - -@noindent -Once again, @kbd{*} elegantly summarizes most of the computation. -But there's an even more elegant approach: Reduce the formula -@kbd{3 $$ + $} across the vector. Recall that this represents a -function of two arguments that computes its first argument times three -plus its second argument. - -@smallexample -@group -1: [84, 101, 115, ..., 51] 1: 1960915098 - . . - - "Testing, 1, 2, 3 @key{RET} V R ' 3$$+$ @key{RET} -@end group -@end smallexample - -@noindent -If you did the decimal arithmetic exercise, this will be familiar. -Basically, we're turning a base-3 vector of digits into an integer, -except that our ``digits'' are much larger than real digits. - -Instead of typing @kbd{511 %} again to reduce the result, we can be -cleverer still and notice that rather than computing a huge integer -and taking the modulo at the end, we can take the modulo at each step -without affecting the result. While this means there are more -arithmetic operations, the numbers we operate on remain small so -the operations are faster. - -@smallexample -@group -1: [84, 101, 115, ..., 51] 1: 121 - . . - - "Testing, 1, 2, 3 @key{RET} V R ' (3$$+$)%511 @key{RET} -@end group -@end smallexample - -Why does this work? Think about a two-step computation: -@w{@expr{3 (3a + b) + c}}. Taking a result modulo 511 basically means -subtracting off enough 511's to put the result in the desired range. -So the result when we take the modulo after every step is, - -@ifnottex -@example -3 (3 a + b - 511 m) + c - 511 n -@end example -@end ifnottex -@tex -\beforedisplay -$$ 3 (3 a + b - 511 m) + c - 511 n $$ -\afterdisplay -@end tex - -@noindent -for some suitable integers @expr{m} and @expr{n}. Expanding out by -the distributive law yields - -@ifnottex -@example -9 a + 3 b + c - 511*3 m - 511 n -@end example -@end ifnottex -@tex -\beforedisplay -$$ 9 a + 3 b + c - 511\times3 m - 511 n $$ -\afterdisplay -@end tex - -@noindent -The @expr{m} term in the latter formula is redundant because any -contribution it makes could just as easily be made by the @expr{n} -term. So we can take it out to get an equivalent formula with -@expr{n' = 3m + n}, - -@ifnottex -@example -9 a + 3 b + c - 511 n' -@end example -@end ifnottex -@tex -\beforedisplay -$$ 9 a + 3 b + c - 511 n^{\prime} $$ -\afterdisplay -@end tex - -@noindent -which is just the formula for taking the modulo only at the end of -the calculation. Therefore the two methods are essentially the same. - -Later in the tutorial we will encounter @dfn{modulo forms}, which -basically automate the idea of reducing every intermediate result -modulo some value @var{m}. - -@node List Answer 14, Types Answer 1, List Answer 13, Answers to Exercises -@subsection List Tutorial Exercise 14 - -We want to use @kbd{H V U} to nest a function which adds a random -step to an @expr{(x,y)} coordinate. The function is a bit long, but -otherwise the problem is quite straightforward. - -@smallexample -@group -2: [0, 0] 1: [ [ 0, 0 ] -1: 50 [ 0.4288, -0.1695 ] - . [ -0.4787, -0.9027 ] - ... - - [0,0] 50 H V U ' <# + [random(2.0)-1, random(2.0)-1]> @key{RET} -@end group -@end smallexample - -Just as the text recommended, we used @samp{< >} nameless function -notation to keep the two @code{random} calls from being evaluated -before nesting even begins. - -We now have a vector of @expr{[x, y]} sub-vectors, which by Calc's -rules acts like a matrix. We can transpose this matrix and unpack -to get a pair of vectors, @expr{x} and @expr{y}, suitable for graphing. - -@smallexample -@group -2: [ 0, 0.4288, -0.4787, ... ] -1: [ 0, -0.1696, -0.9027, ... ] - . - - v t v u g f -@end group -@end smallexample - -Incidentally, because the @expr{x} and @expr{y} are completely -independent in this case, we could have done two separate commands -to create our @expr{x} and @expr{y} vectors of numbers directly. - -To make a random walk of unit steps, we note that @code{sincos} of -a random direction exactly gives us an @expr{[x, y]} step of unit -length; in fact, the new nesting function is even briefer, though -we might want to lower the precision a bit for it. - -@smallexample -@group -2: [0, 0] 1: [ [ 0, 0 ] -1: 50 [ 0.1318, 0.9912 ] - . [ -0.5965, 0.3061 ] - ... - - [0,0] 50 m d p 6 @key{RET} H V U ' <# + sincos(random(360.0))> @key{RET} -@end group -@end smallexample - -Another @kbd{v t v u g f} sequence will graph this new random walk. - -An interesting twist on these random walk functions would be to use -complex numbers instead of 2-vectors to represent points on the plane. -In the first example, we'd use something like @samp{random + random*(0,1)}, -and in the second we could use polar complex numbers with random phase -angles. (This exercise was first suggested in this form by Randal -Schwartz.) - -@node Types Answer 1, Types Answer 2, List Answer 14, Answers to Exercises -@subsection Types Tutorial Exercise 1 - -@noindent -If the number is the square root of @cpi{} times a rational number, -then its square, divided by @cpi{}, should be a rational number. - -@smallexample -@group -1: 1.26508260337 1: 0.509433962268 1: 2486645810:4881193627 - . . . - - 2 ^ P / c F -@end group -@end smallexample - -@noindent -Technically speaking this is a rational number, but not one that is -likely to have arisen in the original problem. More likely, it just -happens to be the fraction which most closely represents some -irrational number to within 12 digits. - -But perhaps our result was not quite exact. Let's reduce the -precision slightly and try again: - -@smallexample -@group -1: 0.509433962268 1: 27:53 - . . - - U p 10 @key{RET} c F -@end group -@end smallexample - -@noindent -Aha! It's unlikely that an irrational number would equal a fraction -this simple to within ten digits, so our original number was probably -@texline @math{\sqrt{27 \pi / 53}}. -@infoline @expr{sqrt(27 pi / 53)}. - -Notice that we didn't need to re-round the number when we reduced the -precision. Remember, arithmetic operations always round their inputs -to the current precision before they begin. - -@node Types Answer 2, Types Answer 3, Types Answer 1, Answers to Exercises -@subsection Types Tutorial Exercise 2 - -@noindent -@samp{inf / inf = nan}. Perhaps @samp{1} is the ``obvious'' answer. -But if @w{@samp{17 inf = inf}}, then @samp{17 inf / inf = inf / inf = 17}, too. - -@samp{exp(inf) = inf}. It's tempting to say that the exponential -of infinity must be ``bigger'' than ``regular'' infinity, but as -far as Calc is concerned all infinities are the same size. -In other words, as @expr{x} goes to infinity, @expr{e^x} also goes -to infinity, but the fact the @expr{e^x} grows much faster than -@expr{x} is not relevant here. - -@samp{exp(-inf) = 0}. Here we have a finite answer even though -the input is infinite. - -@samp{sqrt(-inf) = (0, 1) inf}. Remember that @expr{(0, 1)} -represents the imaginary number @expr{i}. Here's a derivation: -@samp{sqrt(-inf) = @w{sqrt((-1) * inf)} = sqrt(-1) * sqrt(inf)}. -The first part is, by definition, @expr{i}; the second is @code{inf} -because, once again, all infinities are the same size. - -@samp{sqrt(uinf) = uinf}. In fact, we do know something about the -direction because @code{sqrt} is defined to return a value in the -right half of the complex plane. But Calc has no notation for this, -so it settles for the conservative answer @code{uinf}. - -@samp{abs(uinf) = inf}. No matter which direction @expr{x} points, -@samp{abs(x)} always points along the positive real axis. - -@samp{ln(0) = -inf}. Here we have an infinite answer to a finite -input. As in the @expr{1 / 0} case, Calc will only use infinities -here if you have turned on Infinite mode. Otherwise, it will -treat @samp{ln(0)} as an error. - -@node Types Answer 3, Types Answer 4, Types Answer 2, Answers to Exercises -@subsection Types Tutorial Exercise 3 - -@noindent -We can make @samp{inf - inf} be any real number we like, say, -@expr{a}, just by claiming that we added @expr{a} to the first -infinity but not to the second. This is just as true for complex -values of @expr{a}, so @code{nan} can stand for a complex number. -(And, similarly, @code{uinf} can stand for an infinity that points -in any direction in the complex plane, such as @samp{(0, 1) inf}). - -In fact, we can multiply the first @code{inf} by two. Surely -@w{@samp{2 inf - inf = inf}}, but also @samp{2 inf - inf = inf - inf = nan}. -So @code{nan} can even stand for infinity. Obviously it's just -as easy to make it stand for minus infinity as for plus infinity. - -The moral of this story is that ``infinity'' is a slippery fish -indeed, and Calc tries to handle it by having a very simple model -for infinities (only the direction counts, not the ``size''); but -Calc is careful to write @code{nan} any time this simple model is -unable to tell what the true answer is. - -@node Types Answer 4, Types Answer 5, Types Answer 3, Answers to Exercises -@subsection Types Tutorial Exercise 4 - -@smallexample -@group -2: 0@@ 47' 26" 1: 0@@ 2' 47.411765" -1: 17 . - . - - 0@@ 47' 26" @key{RET} 17 / -@end group -@end smallexample - -@noindent -The average song length is two minutes and 47.4 seconds. - -@smallexample -@group -2: 0@@ 2' 47.411765" 1: 0@@ 3' 7.411765" 1: 0@@ 53' 6.000005" -1: 0@@ 0' 20" . . - . - - 20" + 17 * -@end group -@end smallexample - -@noindent -The album would be 53 minutes and 6 seconds long. - -@node Types Answer 5, Types Answer 6, Types Answer 4, Answers to Exercises -@subsection Types Tutorial Exercise 5 - -@noindent -Let's suppose it's January 14, 1991. The easiest thing to do is -to keep trying 13ths of months until Calc reports a Friday. -We can do this by manually entering dates, or by using @kbd{t I}: - -@smallexample -@group -1: 1: 1: - . . . - - ' <2/13> @key{RET} @key{DEL} ' <3/13> @key{RET} t I -@end group -@end smallexample - -@noindent -(Calc assumes the current year if you don't say otherwise.) - -This is getting tedious---we can keep advancing the date by typing -@kbd{t I} over and over again, but let's automate the job by using -vector mapping. The @kbd{t I} command actually takes a second -``how-many-months'' argument, which defaults to one. This -argument is exactly what we want to map over: - -@smallexample -@group -2: 1: [, , -1: [1, 2, 3, 4, 5, 6] , , - . , ] - . - - v x 6 @key{RET} V M t I -@end group -@end smallexample - -@noindent -Et voil@`a, September 13, 1991 is a Friday. - -@smallexample -@group -1: 242 - . - -' - @key{RET} -@end group -@end smallexample - -@noindent -And the answer to our original question: 242 days to go. - -@node Types Answer 6, Types Answer 7, Types Answer 5, Answers to Exercises -@subsection Types Tutorial Exercise 6 - -@noindent -The full rule for leap years is that they occur in every year divisible -by four, except that they don't occur in years divisible by 100, except -that they @emph{do} in years divisible by 400. We could work out the -answer by carefully counting the years divisible by four and the -exceptions, but there is a much simpler way that works even if we -don't know the leap year rule. - -Let's assume the present year is 1991. Years have 365 days, except -that leap years (whenever they occur) have 366 days. So let's count -the number of days between now and then, and compare that to the -number of years times 365. The number of extra days we find must be -equal to the number of leap years there were. - -@smallexample -@group -1: 2: 1: 2925593 - . 1: . - . - - ' @key{RET} ' @key{RET} - - -@end group -@end smallexample -@noindent -@smallexample -@group -3: 2925593 2: 2925593 2: 2925593 1: 1943 -2: 10001 1: 8010 1: 2923650 . -1: 1991 . . - . - - 10001 @key{RET} 1991 - 365 * - -@end group -@end smallexample - -@c [fix-ref Date Forms] -@noindent -There will be 1943 leap years before the year 10001. (Assuming, -of course, that the algorithm for computing leap years remains -unchanged for that long. @xref{Date Forms}, for some interesting -background information in that regard.) - -@node Types Answer 7, Types Answer 8, Types Answer 6, Answers to Exercises -@subsection Types Tutorial Exercise 7 - -@noindent -The relative errors must be converted to absolute errors so that -@samp{+/-} notation may be used. - -@smallexample -@group -1: 1. 2: 1. - . 1: 0.2 - . - - 20 @key{RET} .05 * 4 @key{RET} .05 * -@end group -@end smallexample - -Now we simply chug through the formula. - -@smallexample -@group -1: 19.7392088022 1: 394.78 +/- 19.739 1: 6316.5 +/- 706.21 - . . . - - 2 P 2 ^ * 20 p 1 * 4 p .2 @key{RET} 2 ^ * -@end group -@end smallexample - -It turns out the @kbd{v u} command will unpack an error form as -well as a vector. This saves us some retyping of numbers. - -@smallexample -@group -3: 6316.5 +/- 706.21 2: 6316.5 +/- 706.21 -2: 6316.5 1: 0.1118 -1: 706.21 . - . - - @key{RET} v u @key{TAB} / -@end group -@end smallexample - -@noindent -Thus the volume is 6316 cubic centimeters, within about 11 percent. - -@node Types Answer 8, Types Answer 9, Types Answer 7, Answers to Exercises -@subsection Types Tutorial Exercise 8 - -@noindent -The first answer is pretty simple: @samp{1 / (0 .. 10) = (0.1 .. inf)}. -Since a number in the interval @samp{(0 .. 10)} can get arbitrarily -close to zero, its reciprocal can get arbitrarily large, so the answer -is an interval that effectively means, ``any number greater than 0.1'' -but with no upper bound. - -The second answer, similarly, is @samp{1 / (-10 .. 0) = (-inf .. -0.1)}. - -Calc normally treats division by zero as an error, so that the formula -@w{@samp{1 / 0}} is left unsimplified. Our third problem, -@w{@samp{1 / [0 .. 10]}}, also (potentially) divides by zero because zero -is now a member of the interval. So Calc leaves this one unevaluated, too. - -If you turn on Infinite mode by pressing @kbd{m i}, you will -instead get the answer @samp{[0.1 .. inf]}, which includes infinity -as a possible value. - -The fourth calculation, @samp{1 / (-10 .. 10)}, has the same problem. -Zero is buried inside the interval, but it's still a possible value. -It's not hard to see that the actual result of @samp{1 / (-10 .. 10)} -will be either greater than @mathit{0.1}, or less than @mathit{-0.1}. Thus -the interval goes from minus infinity to plus infinity, with a ``hole'' -in it from @mathit{-0.1} to @mathit{0.1}. Calc doesn't have any way to -represent this, so it just reports @samp{[-inf .. inf]} as the answer. -It may be disappointing to hear ``the answer lies somewhere between -minus infinity and plus infinity, inclusive,'' but that's the best -that interval arithmetic can do in this case. - -@node Types Answer 9, Types Answer 10, Types Answer 8, Answers to Exercises -@subsection Types Tutorial Exercise 9 - -@smallexample -@group -1: [-3 .. 3] 2: [-3 .. 3] 2: [0 .. 9] - . 1: [0 .. 9] 1: [-9 .. 9] - . . - - [ 3 n .. 3 ] @key{RET} 2 ^ @key{TAB} @key{RET} * -@end group -@end smallexample - -@noindent -In the first case the result says, ``if a number is between @mathit{-3} and -3, its square is between 0 and 9.'' The second case says, ``the product -of two numbers each between @mathit{-3} and 3 is between @mathit{-9} and 9.'' - -An interval form is not a number; it is a symbol that can stand for -many different numbers. Two identical-looking interval forms can stand -for different numbers. - -The same issue arises when you try to square an error form. - -@node Types Answer 10, Types Answer 11, Types Answer 9, Answers to Exercises -@subsection Types Tutorial Exercise 10 - -@noindent -Testing the first number, we might arbitrarily choose 17 for @expr{x}. - -@smallexample -@group -1: 17 mod 811749613 2: 17 mod 811749613 1: 533694123 mod 811749613 - . 811749612 . - . - - 17 M 811749613 @key{RET} 811749612 ^ -@end group -@end smallexample - -@noindent -Since 533694123 is (considerably) different from 1, the number 811749613 -must not be prime. - -It's awkward to type the number in twice as we did above. There are -various ways to avoid this, and algebraic entry is one. In fact, using -a vector mapping operation we can perform several tests at once. Let's -use this method to test the second number. - -@smallexample -@group -2: [17, 42, 100000] 1: [1 mod 15485863, 1 mod ... ] -1: 15485863 . - . - - [17 42 100000] 15485863 @key{RET} V M ' ($$ mod $)^($-1) @key{RET} -@end group -@end smallexample - -@noindent -The result is three ones (modulo @expr{n}), so it's very probable that -15485863 is prime. (In fact, this number is the millionth prime.) - -Note that the functions @samp{($$^($-1)) mod $} or @samp{$$^($-1) % $} -would have been hopelessly inefficient, since they would have calculated -the power using full integer arithmetic. - -Calc has a @kbd{k p} command that does primality testing. For small -numbers it does an exact test; for large numbers it uses a variant -of the Fermat test we used here. You can use @kbd{k p} repeatedly -to prove that a large integer is prime with any desired probability. - -@node Types Answer 11, Types Answer 12, Types Answer 10, Answers to Exercises -@subsection Types Tutorial Exercise 11 - -@noindent -There are several ways to insert a calculated number into an HMS form. -One way to convert a number of seconds to an HMS form is simply to -multiply the number by an HMS form representing one second: - -@smallexample -@group -1: 31415926.5359 2: 31415926.5359 1: 8726@@ 38' 46.5359" - . 1: 0@@ 0' 1" . - . - - P 1e7 * 0@@ 0' 1" * - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 8726@@ 38' 46.5359" 1: 6@@ 6' 2.5359" mod 24@@ 0' 0" -1: 15@@ 27' 16" mod 24@@ 0' 0" . - . - - x time @key{RET} + -@end group -@end smallexample - -@noindent -It will be just after six in the morning. - -The algebraic @code{hms} function can also be used to build an -HMS form: - -@smallexample -@group -1: hms(0, 0, 10000000. pi) 1: 8726@@ 38' 46.5359" - . . - - ' hms(0, 0, 1e7 pi) @key{RET} = -@end group -@end smallexample - -@noindent -The @kbd{=} key is necessary to evaluate the symbol @samp{pi} to -the actual number 3.14159... - -@node Types Answer 12, Types Answer 13, Types Answer 11, Answers to Exercises -@subsection Types Tutorial Exercise 12 - -@noindent -As we recall, there are 17 songs of about 2 minutes and 47 seconds -each. - -@smallexample -@group -2: 0@@ 2' 47" 1: [0@@ 3' 7" .. 0@@ 3' 47"] -1: [0@@ 0' 20" .. 0@@ 1' 0"] . - . - - [ 0@@ 20" .. 0@@ 1' ] + - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0@@ 52' 59." .. 1@@ 4' 19."] - . - - 17 * -@end group -@end smallexample - -@noindent -No matter how long it is, the album will fit nicely on one CD. - -@node Types Answer 13, Types Answer 14, Types Answer 12, Answers to Exercises -@subsection Types Tutorial Exercise 13 - -@noindent -Type @kbd{' 1 yr @key{RET} u c s @key{RET}}. The answer is 31557600 seconds. - -@node Types Answer 14, Types Answer 15, Types Answer 13, Answers to Exercises -@subsection Types Tutorial Exercise 14 - -@noindent -How long will it take for a signal to get from one end of the computer -to the other? - -@smallexample -@group -1: m / c 1: 3.3356 ns - . . - - ' 1 m / c @key{RET} u c ns @key{RET} -@end group -@end smallexample - -@noindent -(Recall, @samp{c} is a ``unit'' corresponding to the speed of light.) - -@smallexample -@group -1: 3.3356 ns 1: 0.81356 -2: 4.1 ns . - . - - ' 4.1 ns @key{RET} / -@end group -@end smallexample - -@noindent -Thus a signal could take up to 81 percent of a clock cycle just to -go from one place to another inside the computer, assuming the signal -could actually attain the full speed of light. Pretty tight! - -@node Types Answer 15, Algebra Answer 1, Types Answer 14, Answers to Exercises -@subsection Types Tutorial Exercise 15 - -@noindent -The speed limit is 55 miles per hour on most highways. We want to -find the ratio of Sam's speed to the US speed limit. - -@smallexample -@group -1: 55 mph 2: 55 mph 3: 11 hr mph / yd - . 1: 5 yd / hr . - . - - ' 55 mph @key{RET} ' 5 yd/hr @key{RET} / -@end group -@end smallexample - -The @kbd{u s} command cancels out these units to get a plain -number. Now we take the logarithm base two to find the final -answer, assuming that each successive pill doubles his speed. - -@smallexample -@group -1: 19360. 2: 19360. 1: 14.24 - . 1: 2 . - . - - u s 2 B -@end group -@end smallexample - -@noindent -Thus Sam can take up to 14 pills without a worry. - -@node Algebra Answer 1, Algebra Answer 2, Types Answer 15, Answers to Exercises -@subsection Algebra Tutorial Exercise 1 - -@noindent -@c [fix-ref Declarations] -The result @samp{sqrt(x)^2} is simplified back to @expr{x} by the -Calculator, but @samp{sqrt(x^2)} is not. (Consider what happens -if @w{@expr{x = -4}}.) If @expr{x} is real, this formula could be -simplified to @samp{abs(x)}, but for general complex arguments even -that is not safe. (@xref{Declarations}, for a way to tell Calc -that @expr{x} is known to be real.) - -@node Algebra Answer 2, Algebra Answer 3, Algebra Answer 1, Answers to Exercises -@subsection Algebra Tutorial Exercise 2 - -@noindent -Suppose our roots are @expr{[a, b, c]}. We want a polynomial which -is zero when @expr{x} is any of these values. The trivial polynomial -@expr{x-a} is zero when @expr{x=a}, so the product @expr{(x-a)(x-b)(x-c)} -will do the job. We can use @kbd{a c x} to write this in a more -familiar form. - -@smallexample -@group -1: 34 x - 24 x^3 1: [1.19023, -1.19023, 0] - . . - - r 2 a P x @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [x - 1.19023, x + 1.19023, x] 1: x*(x + 1.19023) (x - 1.19023) - . . - - V M ' x-$ @key{RET} V R * - -@end group -@end smallexample -@noindent -@smallexample -@group -1: x^3 - 1.41666 x 1: 34 x - 24 x^3 - . . - - a c x @key{RET} 24 n * a x -@end group -@end smallexample - -@noindent -Sure enough, our answer (multiplied by a suitable constant) is the -same as the original polynomial. - -@node Algebra Answer 3, Algebra Answer 4, Algebra Answer 2, Answers to Exercises -@subsection Algebra Tutorial Exercise 3 - -@smallexample -@group -1: x sin(pi x) 1: sin(pi x) / pi^2 - x cos(pi x) / pi - . . - - ' x sin(pi x) @key{RET} m r a i x @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [y, 1] -2: sin(pi x) / pi^2 - x cos(pi x) / pi - . - - ' [y,1] @key{RET} @key{TAB} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [sin(pi y) / pi^2 - y cos(pi y) / pi, 1 / pi] - . - - V M $ @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: sin(pi y) / pi^2 - y cos(pi y) / pi - 1 / pi - . - - V R - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: sin(3.14159 y) / 9.8696 - y cos(3.14159 y) / 3.14159 - 0.3183 - . - - = - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0., -0.95493, 0.63662, -1.5915, 1.2732] - . - - v x 5 @key{RET} @key{TAB} V M $ @key{RET} -@end group -@end smallexample - -@node Algebra Answer 4, Rewrites Answer 1, Algebra Answer 3, Answers to Exercises -@subsection Algebra Tutorial Exercise 4 - -@noindent -The hard part is that @kbd{V R +} is no longer sufficient to add up all -the contributions from the slices, since the slices have varying -coefficients. So first we must come up with a vector of these -coefficients. Here's one way: - -@smallexample -@group -2: -1 2: 3 1: [4, 2, ..., 4] -1: [1, 2, ..., 9] 1: [-1, 1, ..., -1] . - . . - - 1 n v x 9 @key{RET} V M ^ 3 @key{TAB} - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [4, 2, ..., 4, 1] 1: [1, 4, 2, ..., 4, 1] - . . - - 1 | 1 @key{TAB} | -@end group -@end smallexample - -@noindent -Now we compute the function values. Note that for this method we need -eleven values, including both endpoints of the desired interval. - -@smallexample -@group -2: [1, 4, 2, ..., 4, 1] -1: [1, 1.1, 1.2, ... , 1.8, 1.9, 2.] - . - - 11 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [1, 4, 2, ..., 4, 1] -1: [0., 0.084941, 0.16993, ... ] - . - - ' sin(x) ln(x) @key{RET} m r p 5 @key{RET} V M $ @key{RET} -@end group -@end smallexample - -@noindent -Once again this calls for @kbd{V M * V R +}; a simple @kbd{*} does the -same thing. - -@smallexample -@group -1: 11.22 1: 1.122 1: 0.374 - . . . - - * .1 * 3 / -@end group -@end smallexample - -@noindent -Wow! That's even better than the result from the Taylor series method. - -@node Rewrites Answer 1, Rewrites Answer 2, Algebra Answer 4, Answers to Exercises -@subsection Rewrites Tutorial Exercise 1 - -@noindent -We'll use Big mode to make the formulas more readable. - -@smallexample -@group - ___ - V 2 + 2 -1: (2 + sqrt(2)) / (1 + sqrt(2)) 1: --------- - . ___ - V 2 + 1 - - . - - ' (2+sqrt(2)) / (1+sqrt(2)) @key{RET} d B -@end group -@end smallexample - -@noindent -Multiplying by the conjugate helps because @expr{(a+b) (a-b) = a^2 - b^2}. - -@smallexample -@group - ___ ___ -1: (2 + V 2 ) (V 2 - 1) - . - - a r a/(b+c) := a*(b-c) / (b^2-c^2) @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group - ___ -1: V 2 - . - - a r a*(b+c) := a*b + a*c -@end group -@end smallexample - -@noindent -(We could have used @kbd{a x} instead of a rewrite rule for the -second step.) - -The multiply-by-conjugate rule turns out to be useful in many -different circumstances, such as when the denominator involves -sines and cosines or the imaginary constant @code{i}. - -@node Rewrites Answer 2, Rewrites Answer 3, Rewrites Answer 1, Answers to Exercises -@subsection Rewrites Tutorial Exercise 2 - -@noindent -Here is the rule set: - -@smallexample -@group -[ fib(n) := fib(n, 1, 1) :: integer(n) :: n >= 1, - fib(1, x, y) := x, - fib(n, x, y) := fib(n-1, y, x+y) ] -@end group -@end smallexample - -@noindent -The first rule turns a one-argument @code{fib} that people like to write -into a three-argument @code{fib} that makes computation easier. The -second rule converts back from three-argument form once the computation -is done. The third rule does the computation itself. It basically -says that if @expr{x} and @expr{y} are two consecutive Fibonacci numbers, -then @expr{y} and @expr{x+y} are the next (overlapping) pair of Fibonacci -numbers. - -Notice that because the number @expr{n} was ``validated'' by the -conditions on the first rule, there is no need to put conditions on -the other rules because the rule set would never get that far unless -the input were valid. That further speeds computation, since no -extra conditions need to be checked at every step. - -Actually, a user with a nasty sense of humor could enter a bad -three-argument @code{fib} call directly, say, @samp{fib(0, 1, 1)}, -which would get the rules into an infinite loop. One thing that would -help keep this from happening by accident would be to use something like -@samp{ZzFib} instead of @code{fib} as the name of the three-argument -function. - -@node Rewrites Answer 3, Rewrites Answer 4, Rewrites Answer 2, Answers to Exercises -@subsection Rewrites Tutorial Exercise 3 - -@noindent -He got an infinite loop. First, Calc did as expected and rewrote -@w{@samp{2 + 3 x}} to @samp{f(2, 3, x)}. Then it looked for ways to -apply the rule again, and found that @samp{f(2, 3, x)} looks like -@samp{a + b x} with @w{@samp{a = 0}} and @samp{b = 1}, so it rewrote to -@samp{f(0, 1, f(2, 3, x))}. It then wrapped another @samp{f(0, 1, ...)} -around that, and so on, ad infinitum. Joe should have used @kbd{M-1 a r} -to make sure the rule applied only once. - -(Actually, even the first step didn't work as he expected. What Calc -really gives for @kbd{M-1 a r} in this situation is @samp{f(3 x, 1, 2)}, -treating 2 as the ``variable,'' and @samp{3 x} as a constant being added -to it. While this may seem odd, it's just as valid a solution as the -``obvious'' one. One way to fix this would be to add the condition -@samp{:: variable(x)} to the rule, to make sure the thing that matches -@samp{x} is indeed a variable, or to change @samp{x} to @samp{quote(x)} -on the lefthand side, so that the rule matches the actual variable -@samp{x} rather than letting @samp{x} stand for something else.) - -@node Rewrites Answer 4, Rewrites Answer 5, Rewrites Answer 3, Answers to Exercises -@subsection Rewrites Tutorial Exercise 4 - -@noindent -@ignore -@starindex -@end ignore -@tindex seq -Here is a suitable set of rules to solve the first part of the problem: - -@smallexample -@group -[ seq(n, c) := seq(n/2, c+1) :: n%2 = 0, - seq(n, c) := seq(3n+1, c+1) :: n%2 = 1 :: n > 1 ] -@end group -@end smallexample - -Given the initial formula @samp{seq(6, 0)}, application of these -rules produces the following sequence of formulas: - -@example -seq( 3, 1) -seq(10, 2) -seq( 5, 3) -seq(16, 4) -seq( 8, 5) -seq( 4, 6) -seq( 2, 7) -seq( 1, 8) -@end example - -@noindent -whereupon neither of the rules match, and rewriting stops. - -We can pretty this up a bit with a couple more rules: - -@smallexample -@group -[ seq(n) := seq(n, 0), - seq(1, c) := c, - ... ] -@end group -@end smallexample - -@noindent -Now, given @samp{seq(6)} as the starting configuration, we get 8 -as the result. - -The change to return a vector is quite simple: - -@smallexample -@group -[ seq(n) := seq(n, []) :: integer(n) :: n > 0, - seq(1, v) := v | 1, - seq(n, v) := seq(n/2, v | n) :: n%2 = 0, - seq(n, v) := seq(3n+1, v | n) :: n%2 = 1 ] -@end group -@end smallexample - -@noindent -Given @samp{seq(6)}, the result is @samp{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. - -Notice that the @expr{n > 1} guard is no longer necessary on the last -rule since the @expr{n = 1} case is now detected by another rule. -But a guard has been added to the initial rule to make sure the -initial value is suitable before the computation begins. - -While still a good idea, this guard is not as vitally important as it -was for the @code{fib} function, since calling, say, @samp{seq(x, [])} -will not get into an infinite loop. Calc will not be able to prove -the symbol @samp{x} is either even or odd, so none of the rules will -apply and the rewrites will stop right away. - -@node Rewrites Answer 5, Rewrites Answer 6, Rewrites Answer 4, Answers to Exercises -@subsection Rewrites Tutorial Exercise 5 - -@noindent -@ignore -@starindex -@end ignore -@tindex nterms -If @expr{x} is the sum @expr{a + b}, then `@tfn{nterms(}@var{x}@tfn{)}' must -be `@tfn{nterms(}@var{a}@tfn{)}' plus `@tfn{nterms(}@var{b}@tfn{)}'. If @expr{x} -is not a sum, then `@tfn{nterms(}@var{x}@tfn{)}' = 1. - -@smallexample -@group -[ nterms(a + b) := nterms(a) + nterms(b), - nterms(x) := 1 ] -@end group -@end smallexample - -@noindent -Here we have taken advantage of the fact that earlier rules always -match before later rules; @samp{nterms(x)} will only be tried if we -already know that @samp{x} is not a sum. - -@node Rewrites Answer 6, Programming Answer 1, Rewrites Answer 5, Answers to Exercises -@subsection Rewrites Tutorial Exercise 6 - -@noindent -Here is a rule set that will do the job: - -@smallexample -@group -[ a*(b + c) := a*b + a*c, - opt(a) O(x^n) + opt(b) O(x^m) := O(x^n) :: n <= m - :: constant(a) :: constant(b), - opt(a) O(x^n) + opt(b) x^m := O(x^n) :: n <= m - :: constant(a) :: constant(b), - a O(x^n) := O(x^n) :: constant(a), - x^opt(m) O(x^n) := O(x^(n+m)), - O(x^n) O(x^m) := O(x^(n+m)) ] -@end group -@end smallexample - -If we really want the @kbd{+} and @kbd{*} keys to operate naturally -on power series, we should put these rules in @code{EvalRules}. For -testing purposes, it is better to put them in a different variable, -say, @code{O}, first. - -The first rule just expands products of sums so that the rest of the -rules can assume they have an expanded-out polynomial to work with. -Note that this rule does not mention @samp{O} at all, so it will -apply to any product-of-sum it encounters---this rule may surprise -you if you put it into @code{EvalRules}! - -In the second rule, the sum of two O's is changed to the smaller O@. -The optional constant coefficients are there mostly so that -@samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled -as well as @samp{O(x^2) + O(x^3)}. - -The third rule absorbs higher powers of @samp{x} into O's. - -The fourth rule says that a constant times a negligible quantity -is still negligible. (This rule will also match @samp{O(x^3) / 4}, -with @samp{a = 1/4}.) - -The fifth rule rewrites, for example, @samp{x^2 O(x^3)} to @samp{O(x^5)}. -(It is easy to see that if one of these forms is negligible, the other -is, too.) Notice the @samp{x^opt(m)} to pick up terms like -@w{@samp{x O(x^3)}}. Optional powers will match @samp{x} as @samp{x^1} -but not 1 as @samp{x^0}. This turns out to be exactly what we want here. - -The sixth rule is the corresponding rule for products of two O's. - -Another way to solve this problem would be to create a new ``data type'' -that represents truncated power series. We might represent these as -function calls @samp{series(@var{coefs}, @var{x})} where @var{coefs} is -a vector of coefficients for @expr{x^0}, @expr{x^1}, @expr{x^2}, and so -on. Rules would exist for sums and products of such @code{series} -objects, and as an optional convenience could also know how to combine a -@code{series} object with a normal polynomial. (With this, and with a -rule that rewrites @samp{O(x^n)} to the equivalent @code{series} form, -you could still enter power series in exactly the same notation as -before.) Operations on such objects would probably be more efficient, -although the objects would be a bit harder to read. - -@c [fix-ref Compositions] -Some other symbolic math programs provide a power series data type -similar to this. Mathematica, for example, has an object that looks -like @samp{PowerSeries[@var{x}, @var{x0}, @var{coefs}, @var{nmin}, -@var{nmax}, @var{den}]}, where @var{x0} is the point about which the -power series is taken (we've been assuming this was always zero), -and @var{nmin}, @var{nmax}, and @var{den} allow pseudo-power-series -with fractional or negative powers. Also, the @code{PowerSeries} -objects have a special display format that makes them look like -@samp{2 x^2 + O(x^4)} when they are printed out. (@xref{Compositions}, -for a way to do this in Calc, although for something as involved as -this it would probably be better to write the formatting routine -in Lisp.) - -@node Programming Answer 1, Programming Answer 2, Rewrites Answer 6, Answers to Exercises -@subsection Programming Tutorial Exercise 1 - -@noindent -Just enter the formula @samp{ninteg(sin(t)/t, t, 0, x)}, type -@kbd{Z F}, and answer the questions. Since this formula contains two -variables, the default argument list will be @samp{(t x)}. We want to -change this to @samp{(x)} since @expr{t} is really a dummy variable -to be used within @code{ninteg}. - -The exact keystrokes are @kbd{Z F s Si @key{RET} @key{RET} C-b C-b @key{DEL} @key{DEL} @key{RET} y}. -(The @kbd{C-b C-b @key{DEL} @key{DEL}} are what fix the argument list.) - -@node Programming Answer 2, Programming Answer 3, Programming Answer 1, Answers to Exercises -@subsection Programming Tutorial Exercise 2 - -@noindent -One way is to move the number to the top of the stack, operate on -it, then move it back: @kbd{C-x ( M-@key{TAB} n M-@key{TAB} M-@key{TAB} C-x )}. - -Another way is to negate the top three stack entries, then negate -again the top two stack entries: @kbd{C-x ( M-3 n M-2 n C-x )}. - -Finally, it turns out that a negative prefix argument causes a -command like @kbd{n} to operate on the specified stack entry only, -which is just what we want: @kbd{C-x ( M-- 3 n C-x )}. - -Just for kicks, let's also do it algebraically: -@w{@kbd{C-x ( ' -$$$, $$, $ @key{RET} C-x )}}. - -@node Programming Answer 3, Programming Answer 4, Programming Answer 2, Answers to Exercises -@subsection Programming Tutorial Exercise 3 - -@noindent -Each of these functions can be computed using the stack, or using -algebraic entry, whichever way you prefer: - -@noindent -Computing -@texline @math{\displaystyle{\sin x \over x}}: -@infoline @expr{sin(x) / x}: - -Using the stack: @kbd{C-x ( @key{RET} S @key{TAB} / C-x )}. - -Using algebraic entry: @kbd{C-x ( ' sin($)/$ @key{RET} C-x )}. - -@noindent -Computing the logarithm: - -Using the stack: @kbd{C-x ( @key{TAB} B C-x )} - -Using algebraic entry: @kbd{C-x ( ' log($,$$) @key{RET} C-x )}. - -@noindent -Computing the vector of integers: - -Using the stack: @kbd{C-x ( 1 @key{RET} 1 C-u v x C-x )}. (Recall that -@kbd{C-u v x} takes the vector size, starting value, and increment -from the stack.) - -Alternatively: @kbd{C-x ( ~ v x C-x )}. (The @kbd{~} key pops a -number from the stack and uses it as the prefix argument for the -next command.) - -Using algebraic entry: @kbd{C-x ( ' index($) @key{RET} C-x )}. - -@node Programming Answer 4, Programming Answer 5, Programming Answer 3, Answers to Exercises -@subsection Programming Tutorial Exercise 4 - -@noindent -Here's one way: @kbd{C-x ( @key{RET} V R + @key{TAB} v l / C-x )}. - -@node Programming Answer 5, Programming Answer 6, Programming Answer 4, Answers to Exercises -@subsection Programming Tutorial Exercise 5 - -@smallexample -@group -2: 1 1: 1.61803398502 2: 1.61803398502 -1: 20 . 1: 1.61803398875 - . . - - 1 @key{RET} 20 Z < & 1 + Z > I H P -@end group -@end smallexample - -@noindent -This answer is quite accurate. - -@node Programming Answer 6, Programming Answer 7, Programming Answer 5, Answers to Exercises -@subsection Programming Tutorial Exercise 6 - -@noindent -Here is the matrix: - -@example -[ [ 0, 1 ] * [a, b] = [b, a + b] - [ 1, 1 ] ] -@end example - -@noindent -Thus @samp{[0, 1; 1, 1]^n * [1, 1]} computes Fibonacci numbers @expr{n+1} -and @expr{n+2}. Here's one program that does the job: - -@example -C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] @key{RET} v u @key{DEL} C-x ) -@end example - -@noindent -This program is quite efficient because Calc knows how to raise a -matrix (or other value) to the power @expr{n} in only -@texline @math{\log_2 n} -@infoline @expr{log(n,2)} -steps. For example, this program can compute the 1000th Fibonacci -number (a 209-digit integer!) in about 10 steps; even though the -@kbd{Z < ... Z >} solution had much simpler steps, it would have -required so many steps that it would not have been practical. - -@node Programming Answer 7, Programming Answer 8, Programming Answer 6, Answers to Exercises -@subsection Programming Tutorial Exercise 7 - -@noindent -The trick here is to compute the harmonic numbers differently, so that -the loop counter itself accumulates the sum of reciprocals. We use -a separate variable to hold the integer counter. - -@smallexample -@group -1: 1 2: 1 1: . - . 1: 4 - . - - 1 t 1 1 @key{RET} 4 Z ( t 2 r 1 1 + s 1 & Z ) -@end group -@end smallexample - -@noindent -The body of the loop goes as follows: First save the harmonic sum -so far in variable 2. Then delete it from the stack; the for loop -itself will take care of remembering it for us. Next, recall the -count from variable 1, add one to it, and feed its reciprocal to -the for loop to use as the step value. The for loop will increase -the ``loop counter'' by that amount and keep going until the -loop counter exceeds 4. - -@smallexample -@group -2: 31 3: 31 -1: 3.99498713092 2: 3.99498713092 - . 1: 4.02724519544 - . - - r 1 r 2 @key{RET} 31 & + -@end group -@end smallexample - -Thus we find that the 30th harmonic number is 3.99, and the 31st -harmonic number is 4.02. - -@node Programming Answer 8, Programming Answer 9, Programming Answer 7, Answers to Exercises -@subsection Programming Tutorial Exercise 8 - -@noindent -The first step is to compute the derivative @expr{f'(x)} and thus -the formula -@texline @math{\displaystyle{x - {f(x) \over f'(x)}}}. -@infoline @expr{x - f(x)/f'(x)}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @w{@kbd{C-x * m}} to load it from there. While you are -entering a @kbd{Z ` Z '} body in a macro, Calc simply collects -keystrokes without executing them. In the following diagrams we'll -pretend Calc actually executed the keystrokes as you typed them, -just for purposes of illustration.) - -@smallexample -@group -2: sin(cos(x)) - 0.5 3: 4.5 -1: 4.5 2: sin(cos(x)) - 0.5 - . 1: -(sin(x) cos(cos(x))) - . - -' sin(cos(x))-0.5 @key{RET} 4.5 m r C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 4.5 -1: x + (sin(cos(x)) - 0.5) / sin(x) cos(cos(x)) - . - - / ' x @key{RET} @key{TAB} - t 1 -@end group -@end smallexample - -Now, we enter the loop. We'll use a repeat loop with a 20-repetition -limit just in case the method fails to converge for some reason. -(Normally, the @w{@kbd{Z /}} command will stop the loop before all 20 -repetitions are done.) - -@smallexample -@group -1: 4.5 3: 4.5 2: 4.5 - . 2: x + (sin(cos(x)) ... 1: 5.24196456928 - 1: 4.5 . - . - - 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} -@end group -@end smallexample - -This is the new guess for @expr{x}. Now we compare it with the -old one to see if we've converged. - -@smallexample -@group -3: 5.24196 2: 5.24196 1: 5.24196 1: 5.26345856348 -2: 5.24196 1: 0 . . -1: 4.5 . - . - - @key{RET} M-@key{TAB} a = Z / Z > Z ' C-x ) -@end group -@end smallexample - -The loop converges in just a few steps to this value. To check -the result, we can simply substitute it back into the equation. - -@smallexample -@group -2: 5.26345856348 -1: 0.499999999997 - . - - @key{RET} ' sin(cos($)) @key{RET} -@end group -@end smallexample - -Let's test the new definition again: - -@smallexample -@group -2: x^2 - 9 1: 3. -1: 1 . - . - - ' x^2-9 @key{RET} 1 X -@end group -@end smallexample - -Once again, here's the full Newton's Method definition: - -@example -@group -C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} / ' x @key{RET} @key{TAB} - t 1 - 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} - @key{RET} M-@key{TAB} a = Z / - Z > - Z ' -C-x ) -@end group -@end example - -@c [fix-ref Nesting and Fixed Points] -It turns out that Calc has a built-in command for applying a formula -repeatedly until it converges to a number. @xref{Nesting and Fixed Points}, -to see how to use it. - -@c [fix-ref Root Finding] -Also, of course, @kbd{a R} is a built-in command that uses Newton's -method (among others) to look for numerical solutions to any equation. -@xref{Root Finding}. - -@node Programming Answer 9, Programming Answer 10, Programming Answer 8, Answers to Exercises -@subsection Programming Tutorial Exercise 9 - -@noindent -The first step is to adjust @expr{z} to be greater than 5. A simple -``for'' loop will do the job here. If @expr{z} is less than 5, we -reduce the problem using -@texline @math{\psi(z) = \psi(z+1) - 1/z}. -@infoline @expr{psi(z) = psi(z+1) - 1/z}. We go -on to compute -@texline @math{\psi(z+1)}, -@infoline @expr{psi(z+1)}, -and remember to add back a factor of @expr{-1/z} when we're done. This -step is repeated until @expr{z > 5}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @w{@kbd{C-x * m}} to load it from there. While you are -entering a @kbd{Z ` Z '} body in a macro, Calc simply collects -keystrokes without executing them. In the following diagrams we'll -pretend Calc actually executed the keystrokes as you typed them, -just for purposes of illustration.) - -@smallexample -@group -1: 1. 1: 1. - . . - - 1.0 @key{RET} C-x ( Z ` s 1 0 t 2 -@end group -@end smallexample - -Here, variable 1 holds @expr{z} and variable 2 holds the adjustment -factor. If @expr{z < 5}, we use a loop to increase it. - -(By the way, we started with @samp{1.0} instead of the integer 1 because -otherwise the calculation below will try to do exact fractional arithmetic, -and will never converge because fractions compare equal only if they -are exactly equal, not just equal to within the current precision.) - -@smallexample -@group -3: 1. 2: 1. 1: 6. -2: 1. 1: 1 . -1: 5 . - . - - @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] -@end group -@end smallexample - -Now we compute the initial part of the sum: -@texline @math{\ln z - {1 \over 2z}} -@infoline @expr{ln(z) - 1/2z} -minus the adjustment factor. - -@smallexample -@group -2: 1.79175946923 2: 1.7084261359 1: -0.57490719743 -1: 0.0833333333333 1: 2.28333333333 . - . . - - L r 1 2 * & - r 2 - -@end group -@end smallexample - -Now we evaluate the series. We'll use another ``for'' loop counting -up the value of @expr{2 n}. (Calc does have a summation command, -@kbd{a +}, but we'll use loops just to get more practice with them.) - -@smallexample -@group -3: -0.5749 3: -0.5749 4: -0.5749 2: -0.5749 -2: 2 2: 1:6 3: 1:6 1: 2.3148e-3 -1: 40 1: 2 2: 2 . - . . 1: 36. - . - - 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / - -@end group -@end smallexample -@noindent -@smallexample -@group -3: -0.5749 3: -0.5772 2: -0.5772 1: -0.577215664892 -2: -0.5749 2: -0.5772 1: 0 . -1: 2.3148e-3 1: -0.5749 . - . . - - @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / 2 Z ) Z ' C-x ) -@end group -@end smallexample - -This is the value of -@texline @math{-\gamma}, -@infoline @expr{- gamma}, -with a slight bit of roundoff error. To get a full 12 digits, let's use -a higher precision: - -@smallexample -@group -2: -0.577215664892 2: -0.577215664892 -1: 1. 1: -0.577215664901532 - - 1. @key{RET} p 16 @key{RET} X -@end group -@end smallexample - -Here's the complete sequence of keystrokes: - -@example -@group -C-x ( Z ` s 1 0 t 2 - @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] - L r 1 2 * & - r 2 - - 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / - @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / - 2 Z ) - Z ' -C-x ) -@end group -@end example - -@node Programming Answer 10, Programming Answer 11, Programming Answer 9, Answers to Exercises -@subsection Programming Tutorial Exercise 10 - -@noindent -Taking the derivative of a term of the form @expr{x^n} will produce -a term like -@texline @math{n x^{n-1}}. -@infoline @expr{n x^(n-1)}. -Taking the derivative of a constant -produces zero. From this it is easy to see that the @expr{n}th -derivative of a polynomial, evaluated at @expr{x = 0}, will equal the -coefficient on the @expr{x^n} term times @expr{n!}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @w{@kbd{C-x * m}} to load it from there. While you are -entering a @kbd{Z ` Z '} body in a macro, Calc simply collects -keystrokes without executing them. In the following diagrams we'll -pretend Calc actually executed the keystrokes as you typed them, -just for purposes of illustration.) - -@smallexample -@group -2: 5 x^4 + (x + 1)^2 3: 5 x^4 + (x + 1)^2 -1: 6 2: 0 - . 1: 6 - . - - ' 5 x^4 + (x+1)^2 @key{RET} 6 C-x ( Z ` [ ] t 1 0 @key{TAB} -@end group -@end smallexample - -@noindent -Variable 1 will accumulate the vector of coefficients. - -@smallexample -@group -2: 0 3: 0 2: 5 x^4 + ... -1: 5 x^4 + ... 2: 5 x^4 + ... 1: 1 - . 1: 1 . - . - - Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 -@end group -@end smallexample - -@noindent -Note that @kbd{s | 1} appends the top-of-stack value to the vector -in a variable; it is completely analogous to @kbd{s + 1}. We could -have written instead, @kbd{r 1 @key{TAB} | t 1}. - -@smallexample -@group -1: 20 x^3 + 2 x + 2 1: 0 1: [1, 2, 1, 0, 5, 0, 0] - . . . - - a d x @key{RET} 1 Z ) @key{DEL} r 1 Z ' C-x ) -@end group -@end smallexample - -To convert back, a simple method is just to map the coefficients -against a table of powers of @expr{x}. - -@smallexample -@group -2: [1, 2, 1, 0, 5, 0, 0] 2: [1, 2, 1, 0, 5, 0, 0] -1: 6 1: [0, 1, 2, 3, 4, 5, 6] - . . - - 6 @key{RET} 1 + 0 @key{RET} 1 C-u v x - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [1, 2, 1, 0, 5, 0, 0] 2: 1 + 2 x + x^2 + 5 x^4 -1: [1, x, x^2, x^3, ... ] . - . - - ' x @key{RET} @key{TAB} V M ^ * -@end group -@end smallexample - -Once again, here are the whole polynomial to/from vector programs: - -@example -@group -C-x ( Z ` [ ] t 1 0 @key{TAB} - Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 - a d x @key{RET} - 1 Z ) r 1 - Z ' -C-x ) - -C-x ( 1 + 0 @key{RET} 1 C-u v x ' x @key{RET} @key{TAB} V M ^ * C-x ) -@end group -@end example - -@node Programming Answer 11, Programming Answer 12, Programming Answer 10, Answers to Exercises -@subsection Programming Tutorial Exercise 11 - -@noindent -First we define a dummy program to go on the @kbd{z s} key. The true -@w{@kbd{z s}} key is supposed to take two numbers from the stack and -return one number, so @key{DEL} as a dummy definition will make -sure the stack comes out right. - -@smallexample -@group -2: 4 1: 4 2: 4 -1: 2 . 1: 2 - . . - - 4 @key{RET} 2 C-x ( @key{DEL} C-x ) Z K s @key{RET} 2 -@end group -@end smallexample - -The last step replaces the 2 that was eaten during the creation -of the dummy @kbd{z s} command. Now we move on to the real -definition. The recurrence needs to be rewritten slightly, -to the form @expr{s(n,m) = s(n-1,m-1) - (n-1) s(n-1,m)}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @kbd{C-x * m} to load it from there.) - -@smallexample -@group -2: 4 4: 4 3: 4 2: 4 -1: 2 3: 2 2: 2 1: 2 - . 2: 4 1: 0 . - 1: 2 . - . - - C-x ( M-2 @key{RET} a = Z [ @key{DEL} @key{DEL} 1 Z : - -@end group -@end smallexample -@noindent -@smallexample -@group -4: 4 2: 4 2: 3 4: 3 4: 3 3: 3 -3: 2 1: 2 1: 2 3: 2 3: 2 2: 2 -2: 2 . . 2: 3 2: 3 1: 3 -1: 0 1: 2 1: 1 . - . . . - - @key{RET} 0 a = Z [ @key{DEL} @key{DEL} 0 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s -@end group -@end smallexample - -@noindent -(Note that the value 3 that our dummy @kbd{z s} produces is not correct; -it is merely a placeholder that will do just as well for now.) - -@smallexample -@group -3: 3 4: 3 3: 3 2: 3 1: -6 -2: 3 3: 3 2: 3 1: 9 . -1: 2 2: 3 1: 3 . - . 1: 2 . - . - - M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: -6 2: 4 1: 11 2: 11 - . 1: 2 . 1: 11 - . . - - Z ] Z ] C-x ) Z K s @key{RET} @key{DEL} 4 @key{RET} 2 z s M-@key{RET} k s -@end group -@end smallexample - -Even though the result that we got during the definition was highly -bogus, once the definition is complete the @kbd{z s} command gets -the right answers. - -Here's the full program once again: - -@example -@group -C-x ( M-2 @key{RET} a = - Z [ @key{DEL} @key{DEL} 1 - Z : @key{RET} 0 a = - Z [ @key{DEL} @key{DEL} 0 - Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s - M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - - Z ] - Z ] -C-x ) -@end group -@end example - -You can read this definition using @kbd{C-x * m} (@code{read-kbd-macro}) -followed by @kbd{Z K s}, without having to make a dummy definition -first, because @code{read-kbd-macro} doesn't need to execute the -definition as it reads it in. For this reason, @code{C-x * m} is often -the easiest way to create recursive programs in Calc. - -@node Programming Answer 12, , Programming Answer 11, Answers to Exercises -@subsection Programming Tutorial Exercise 12 - -@noindent -This turns out to be a much easier way to solve the problem. Let's -denote Stirling numbers as calls of the function @samp{s}. - -First, we store the rewrite rules corresponding to the definition of -Stirling numbers in a convenient variable: - -@smallexample -s e StirlingRules @key{RET} -[ s(n,n) := 1 :: n >= 0, - s(n,0) := 0 :: n > 0, - s(n,m) := s(n-1,m-1) - (n-1) s(n-1,m) :: n >= m :: m >= 1 ] -C-c C-c -@end smallexample - -Now, it's just a matter of applying the rules: - -@smallexample -@group -2: 4 1: s(4, 2) 1: 11 -1: 2 . . - . - - 4 @key{RET} 2 C-x ( ' s($$,$) @key{RET} a r StirlingRules @key{RET} C-x ) -@end group -@end smallexample - -As in the case of the @code{fib} rules, it would be useful to put these -rules in @code{EvalRules} and to add a @samp{:: remember} condition to -the last rule. - -@c This ends the table-of-contents kludge from above: -@tex -\global\let\chapternofonts=\oldchapternofonts -@end tex - -@c [reference] - -@node Introduction, Data Types, Tutorial, Top -@chapter Introduction - -@noindent -This chapter is the beginning of the Calc reference manual. -It covers basic concepts such as the stack, algebraic and -numeric entry, undo, numeric prefix arguments, etc. - -@c [when-split] -@c (Chapter 2, the Tutorial, has been printed in a separate volume.) - -@menu -* Basic Commands:: -* Help Commands:: -* Stack Basics:: -* Numeric Entry:: -* Algebraic Entry:: -* Quick Calculator:: -* Prefix Arguments:: -* Undo:: -* Error Messages:: -* Multiple Calculators:: -* Troubleshooting Commands:: -@end menu - -@node Basic Commands, Help Commands, Introduction, Introduction -@section Basic Commands - -@noindent -@pindex calc -@pindex calc-mode -@cindex Starting the Calculator -@cindex Running the Calculator -To start the Calculator in its standard interface, type @kbd{M-x calc}. -By default this creates a pair of small windows, @file{*Calculator*} -and @file{*Calc Trail*}. The former displays the contents of the -Calculator stack and is manipulated exclusively through Calc commands. -It is possible (though not usually necessary) to create several Calc -mode buffers each of which has an independent stack, undo list, and -mode settings. There is exactly one Calc Trail buffer; it records a -list of the results of all calculations that have been done. The -Calc Trail buffer uses a variant of Calc mode, so Calculator commands -still work when the trail buffer's window is selected. It is possible -to turn the trail window off, but the @file{*Calc Trail*} buffer itself -still exists and is updated silently. @xref{Trail Commands}. - -@kindex C-x * c -@kindex C-x * * -@ignore -@mindex @null -@end ignore -In most installations, the @kbd{C-x * c} key sequence is a more -convenient way to start the Calculator. Also, @kbd{C-x * *} -is a synonym for @kbd{C-x * c} unless you last used Calc -in its Keypad mode. - -@kindex x -@kindex M-x -@pindex calc-execute-extended-command -Most Calc commands use one or two keystrokes. Lower- and upper-case -letters are distinct. Commands may also be entered in full @kbd{M-x} form; -for some commands this is the only form. As a convenience, the @kbd{x} -key (@code{calc-execute-extended-command}) -is like @kbd{M-x} except that it enters the initial string @samp{calc-} -for you. For example, the following key sequences are equivalent: -@kbd{S}, @kbd{M-x calc-sin @key{RET}}, @kbd{x sin @key{RET}}. - -Although Calc is designed to be used from the keyboard, some of -Calc's more common commands are available from a menu. In the menu, the -arguments to the functions are given by referring to their stack level -numbers. - -@cindex Extensions module -@cindex @file{calc-ext} module -The Calculator exists in many parts. When you type @kbd{C-x * c}, the -Emacs ``auto-load'' mechanism will bring in only the first part, which -contains the basic arithmetic functions. The other parts will be -auto-loaded the first time you use the more advanced commands like trig -functions or matrix operations. This is done to improve the response time -of the Calculator in the common case when all you need to do is a -little arithmetic. If for some reason the Calculator fails to load an -extension module automatically, you can force it to load all the -extensions by using the @kbd{C-x * L} (@code{calc-load-everything}) -command. @xref{Mode Settings}. - -If you type @kbd{M-x calc} or @kbd{C-x * c} with any numeric prefix argument, -the Calculator is loaded if necessary, but it is not actually started. -If the argument is positive, the @file{calc-ext} extensions are also -loaded if necessary. User-written Lisp code that wishes to make use -of Calc's arithmetic routines can use @samp{(calc 0)} or @samp{(calc 1)} -to auto-load the Calculator. - -@kindex C-x * b -@pindex full-calc -If you type @kbd{C-x * b}, then next time you use @kbd{C-x * c} you -will get a Calculator that uses the full height of the Emacs screen. -When full-screen mode is on, @kbd{C-x * c} runs the @code{full-calc} -command instead of @code{calc}. From the Unix shell you can type -@samp{emacs -f full-calc} to start a new Emacs specifically for use -as a calculator. When Calc is started from the Emacs command line -like this, Calc's normal ``quit'' commands actually quit Emacs itself. - -@kindex C-x * o -@pindex calc-other-window -The @kbd{C-x * o} command is like @kbd{C-x * c} except that the Calc -window is not actually selected. If you are already in the Calc -window, @kbd{C-x * o} switches you out of it. (The regular Emacs -@kbd{C-x o} command would also work for this, but it has a -tendency to drop you into the Calc Trail window instead, which -@kbd{C-x * o} takes care not to do.) - -@ignore -@mindex C-x * q -@end ignore -For one quick calculation, you can type @kbd{C-x * q} (@code{quick-calc}) -which prompts you for a formula (like @samp{2+3/4}). The result is -displayed at the bottom of the Emacs screen without ever creating -any special Calculator windows. @xref{Quick Calculator}. - -@ignore -@mindex C-x * k -@end ignore -Finally, if you are using the X window system you may want to try -@kbd{C-x * k} (@code{calc-keypad}) which runs Calc with a -``calculator keypad'' picture as well as a stack display. Click on -the keys with the mouse to operate the calculator. @xref{Keypad Mode}. - -@kindex q -@pindex calc-quit -@cindex Quitting the Calculator -@cindex Exiting the Calculator -The @kbd{q} key (@code{calc-quit}) exits Calc mode and closes the -Calculator's window(s). It does not delete the Calculator buffers. -If you type @kbd{M-x calc} again, the Calculator will reappear with the -contents of the stack intact. Typing @kbd{C-x * c} or @kbd{C-x * *} -again from inside the Calculator buffer is equivalent to executing -@code{calc-quit}; you can think of @kbd{C-x * *} as toggling the -Calculator on and off. - -@kindex C-x * x -The @kbd{C-x * x} command also turns the Calculator off, no matter which -user interface (standard, Keypad, or Embedded) is currently active. -It also cancels @code{calc-edit} mode if used from there. - -@kindex d @key{SPC} -@pindex calc-refresh -@cindex Refreshing a garbled display -@cindex Garbled displays, refreshing -The @kbd{d @key{SPC}} key sequence (@code{calc-refresh}) redraws the contents -of the Calculator buffer from memory. Use this if the contents of the -buffer have been damaged somehow. - -@ignore -@mindex o -@end ignore -The @kbd{o} key (@code{calc-realign}) moves the cursor back to its -``home'' position at the bottom of the Calculator buffer. - -@kindex < -@kindex > -@pindex calc-scroll-left -@pindex calc-scroll-right -@cindex Horizontal scrolling -@cindex Scrolling -@cindex Wide text, scrolling -The @kbd{<} and @kbd{>} keys are bound to @code{calc-scroll-left} and -@code{calc-scroll-right}. These are just like the normal horizontal -scrolling commands except that they scroll one half-screen at a time by -default. (Calc formats its output to fit within the bounds of the -window whenever it can.) - -@kindex @{ -@kindex @} -@pindex calc-scroll-down -@pindex calc-scroll-up -@cindex Vertical scrolling -The @kbd{@{} and @kbd{@}} keys are bound to @code{calc-scroll-down} -and @code{calc-scroll-up}. They scroll up or down by one-half the -height of the Calc window. - -@kindex C-x * 0 -@pindex calc-reset -The @kbd{C-x * 0} command (@code{calc-reset}; that's @kbd{C-x *} followed -by a zero) resets the Calculator to its initial state. This clears -the stack, resets all the modes to their initial values (the values -that were saved with @kbd{m m} (@code{calc-save-modes})), clears the -caches (@pxref{Caches}), and so on. (It does @emph{not} erase the -values of any variables.) With an argument of 0, Calc will be reset to -its default state; namely, the modes will be given their default values. -With a positive prefix argument, @kbd{C-x * 0} preserves the contents of -the stack but resets everything else to its initial state; with a -negative prefix argument, @kbd{C-x * 0} preserves the contents of the -stack but resets everything else to its default state. - -@node Help Commands, Stack Basics, Basic Commands, Introduction -@section Help Commands - -@noindent -@cindex Help commands -@kindex ? -@kindex a ? -@kindex b ? -@kindex c ? -@kindex d ? -@kindex f ? -@kindex g ? -@kindex j ? -@kindex k ? -@kindex m ? -@kindex r ? -@kindex s ? -@kindex t ? -@kindex u ? -@kindex v ? -@kindex V ? -@kindex z ? -@kindex Z ? -@pindex calc-help -The @kbd{?} key (@code{calc-help}) displays a series of brief help messages. -Some keys (such as @kbd{b} and @kbd{d}) are prefix keys, like Emacs's -@key{ESC} and @kbd{C-x} prefixes. You can type -@kbd{?} after a prefix to see a list of commands beginning with that -prefix. (If the message includes @samp{[MORE]}, press @kbd{?} again -to see additional commands for that prefix.) - -@kindex h h -@pindex calc-full-help -The @kbd{h h} (@code{calc-full-help}) command displays all the @kbd{?} -responses at once. When printed, this makes a nice, compact (three pages) -summary of Calc keystrokes. - -In general, the @kbd{h} key prefix introduces various commands that -provide help within Calc. Many of the @kbd{h} key functions are -Calc-specific analogues to the @kbd{C-h} functions for Emacs help. - -@kindex h i -@kindex C-x * i -@kindex i -@pindex calc-info -The @kbd{h i} (@code{calc-info}) command runs the Emacs Info system -to read this manual on-line. This is basically the same as typing -@kbd{C-h i} (the regular way to run the Info system), then, if Info -is not already in the Calc manual, selecting the beginning of the -manual. The @kbd{C-x * i} command is another way to read the Calc -manual; it is different from @kbd{h i} in that it works any time, -not just inside Calc. The plain @kbd{i} key is also equivalent to -@kbd{h i}, though this key is obsolete and may be replaced with a -different command in a future version of Calc. - -@kindex h t -@kindex C-x * t -@pindex calc-tutorial -The @kbd{h t} (@code{calc-tutorial}) command runs the Info system on -the Tutorial section of the Calc manual. It is like @kbd{h i}, -except that it selects the starting node of the tutorial rather -than the beginning of the whole manual. (It actually selects the -node ``Interactive Tutorial'' which tells a few things about -using the Info system before going on to the actual tutorial.) -The @kbd{C-x * t} key is equivalent to @kbd{h t} (but it works at -all times). - -@kindex h s -@kindex C-x * s -@pindex calc-info-summary -The @kbd{h s} (@code{calc-info-summary}) command runs the Info system -on the Summary node of the Calc manual. @xref{Summary}. The @kbd{C-x * s} -key is equivalent to @kbd{h s}. - -@kindex h k -@pindex calc-describe-key -The @kbd{h k} (@code{calc-describe-key}) command looks up a key -sequence in the Calc manual. For example, @kbd{h k H a S} looks -up the documentation on the @kbd{H a S} (@code{calc-solve-for}) -command. This works by looking up the textual description of -the key(s) in the Key Index of the manual, then jumping to the -node indicated by the index. - -Most Calc commands do not have traditional Emacs documentation -strings, since the @kbd{h k} command is both more convenient and -more instructive. This means the regular Emacs @kbd{C-h k} -(@code{describe-key}) command will not be useful for Calc keystrokes. - -@kindex h c -@pindex calc-describe-key-briefly -The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a -key sequence and displays a brief one-line description of it at -the bottom of the screen. It looks for the key sequence in the -Summary node of the Calc manual; if it doesn't find the sequence -there, it acts just like its regular Emacs counterpart @kbd{C-h c} -(@code{describe-key-briefly}). For example, @kbd{h c H a S} -gives the description: - -@smallexample -H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes) -@end smallexample - -@noindent -which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for} -takes a value @expr{a} from the stack, prompts for a value @expr{v}, -then applies the algebraic function @code{fsolve} to these values. -The @samp{?=notes} message means you can now type @kbd{?} to see -additional notes from the summary that apply to this command. - -@kindex h f -@pindex calc-describe-function -The @kbd{h f} (@code{calc-describe-function}) command looks up an -algebraic function or a command name in the Calc manual. Enter an -algebraic function name to look up that function in the Function -Index or enter a command name beginning with @samp{calc-} to look it -up in the Command Index. This command will also look up operator -symbols that can appear in algebraic formulas, like @samp{%} and -@samp{=>}. - -@kindex h v -@pindex calc-describe-variable -The @kbd{h v} (@code{calc-describe-variable}) command looks up a -variable in the Calc manual. Enter a variable name like @code{pi} or -@code{PlotRejects}. - -@kindex h b -@pindex describe-bindings -The @kbd{h b} (@code{calc-describe-bindings}) command is just like -@kbd{C-h b}, except that only local (Calc-related) key bindings are -listed. - -@kindex h n -The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays -the ``news'' or change history of Emacs, and jumps to the most recent -portion concerning Calc (if present). For older history, see the file -@file{etc/CALC-NEWS} in the Emacs distribution. - -@kindex h C-c -@kindex h C-d -@kindex h C-w -The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying, -distribution, and warranty information about Calc. These work by -pulling up the appropriate parts of the ``Copying'' or ``Reporting -Bugs'' sections of the manual. - -@node Stack Basics, Numeric Entry, Help Commands, Introduction -@section Stack Basics - -@noindent -@cindex Stack basics -@c [fix-tut RPN Calculations and the Stack] -Calc uses RPN notation. If you are not familiar with RPN, @pxref{RPN -Tutorial}. - -To add the numbers 1 and 2 in Calc you would type the keys: -@kbd{1 @key{RET} 2 +}. -(@key{RET} corresponds to the @key{ENTER} key on most calculators.) -The first three keystrokes ``push'' the numbers 1 and 2 onto the stack. The -@kbd{+} key always ``pops'' the top two numbers from the stack, adds them, -and pushes the result (3) back onto the stack. This number is ready for -further calculations: @kbd{5 -} pushes 5 onto the stack, then pops the -3 and 5, subtracts them, and pushes the result (@mathit{-2}). - -Note that the ``top'' of the stack actually appears at the @emph{bottom} -of the buffer. A line containing a single @samp{.} character signifies -the end of the buffer; Calculator commands operate on the number(s) -directly above this line. The @kbd{d t} (@code{calc-truncate-stack}) -command allows you to move the @samp{.} marker up and down in the stack; -@pxref{Truncating the Stack}. - -@kindex d l -@pindex calc-line-numbering -Stack elements are numbered consecutively, with number 1 being the top of -the stack. These line numbers are ordinarily displayed on the lefthand side -of the window. The @kbd{d l} (@code{calc-line-numbering}) command controls -whether these numbers appear. (Line numbers may be turned off since they -slow the Calculator down a bit and also clutter the display.) - -@kindex o -@pindex calc-realign -The unshifted letter @kbd{o} (@code{calc-realign}) command repositions -the cursor to its top-of-stack ``home'' position. It also undoes any -horizontal scrolling in the window. If you give it a numeric prefix -argument, it instead moves the cursor to the specified stack element. - -The @key{RET} (or equivalent @key{SPC}) key is only required to separate -two consecutive numbers. -(After all, if you typed @kbd{1 2} by themselves the Calculator -would enter the number 12.) If you press @key{RET} or @key{SPC} @emph{not} -right after typing a number, the key duplicates the number on the top of -the stack. @kbd{@key{RET} *} is thus a handy way to square a number. - -The @key{DEL} key pops and throws away the top number on the stack. -The @key{TAB} key swaps the top two objects on the stack. -@xref{Stack and Trail}, for descriptions of these and other stack-related -commands. - -@node Numeric Entry, Algebraic Entry, Stack Basics, Introduction -@section Numeric Entry - -@noindent -@kindex 0-9 -@kindex . -@kindex e -@cindex Numeric entry -@cindex Entering numbers -Pressing a digit or other numeric key begins numeric entry using the -minibuffer. The number is pushed on the stack when you press the @key{RET} -or @key{SPC} keys. If you press any other non-numeric key, the number is -pushed onto the stack and the appropriate operation is performed. If -you press a numeric key which is not valid, the key is ignored. - -@cindex Minus signs -@cindex Negative numbers, entering -@kindex _ -There are three different concepts corresponding to the word ``minus,'' -typified by @expr{a-b} (subtraction), @expr{-x} -(change-sign), and @expr{-5} (negative number). Calc uses three -different keys for these operations, respectively: -@kbd{-}, @kbd{n}, and @kbd{_} (the underscore). The @kbd{-} key subtracts -the two numbers on the top of the stack. The @kbd{n} key changes the sign -of the number on the top of the stack or the number currently being entered. -The @kbd{_} key begins entry of a negative number or changes the sign of -the number currently being entered. The following sequences all enter the -number @mathit{-5} onto the stack: @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}}, -@kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}. - -Some other keys are active during numeric entry, such as @kbd{#} for -non-decimal numbers, @kbd{:} for fractions, and @kbd{@@} for HMS forms. -These notations are described later in this manual with the corresponding -data types. @xref{Data Types}. - -During numeric entry, the only editing key available is @key{DEL}. - -@node Algebraic Entry, Quick Calculator, Numeric Entry, Introduction -@section Algebraic Entry - -@noindent -@kindex ' -@pindex calc-algebraic-entry -@cindex Algebraic notation -@cindex Formulas, entering -The @kbd{'} (@code{calc-algebraic-entry}) command can be used to enter -calculations in algebraic form. This is accomplished by typing the -apostrophe key, ', followed by the expression in standard format: - -@example -' 2+3*4 @key{RET}. -@end example - -@noindent -This will compute -@texline @math{2+(3\times4) = 14} -@infoline @expr{2+(3*4) = 14} -and push it on the stack. If you wish you can -ignore the RPN aspect of Calc altogether and simply enter algebraic -expressions in this way. You may want to use @key{DEL} every so often to -clear previous results off the stack. - -You can press the apostrophe key during normal numeric entry to switch -the half-entered number into Algebraic entry mode. One reason to do -this would be to fix a typo, as the full Emacs cursor motion and editing -keys are available during algebraic entry but not during numeric entry. - -In the same vein, during either numeric or algebraic entry you can -press @kbd{`} (backquote) to switch to @code{calc-edit} mode, where -you complete your half-finished entry in a separate buffer. -@xref{Editing Stack Entries}. - -@kindex m a -@pindex calc-algebraic-mode -@cindex Algebraic Mode -If you prefer algebraic entry, you can use the command @kbd{m a} -(@code{calc-algebraic-mode}) to set Algebraic mode. In this mode, -digits and other keys that would normally start numeric entry instead -start full algebraic entry; as long as your formula begins with a digit -you can omit the apostrophe. Open parentheses and square brackets also -begin algebraic entry. You can still do RPN calculations in this mode, -but you will have to press @key{RET} to terminate every number: -@kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same -thing as @kbd{2*3+4 @key{RET}}. - -@cindex Incomplete Algebraic Mode -If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a} -command, it enables Incomplete Algebraic mode; this is like regular -Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys -only. Numeric keys still begin a numeric entry in this mode. - -@kindex m t -@pindex calc-total-algebraic-mode -@cindex Total Algebraic Mode -The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even -stronger algebraic-entry mode, in which @emph{all} regular letter and -punctuation keys begin algebraic entry. Use this if you prefer typing -@w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of -@kbd{a f}, and so on. To type regular Calc commands when you are in -Total Algebraic mode, hold down the @key{META} key. Thus @kbd{M-q} -is the command to quit Calc, @kbd{M-p} sets the precision, and -@kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns Total Algebraic -mode back off again. Meta keys also terminate algebraic entry, so -that @kbd{2+3 M-S} is equivalent to @kbd{2+3 @key{RET} M-S}. The symbol -@samp{Alg*} will appear in the mode line whenever you are in this mode. - -Pressing @kbd{'} (the apostrophe) a second time re-enters the previous -algebraic formula. You can then use the normal Emacs editing keys to -modify this formula to your liking before pressing @key{RET}. - -@kindex $ -@cindex Formulas, referring to stack -Within a formula entered from the keyboard, the symbol @kbd{$} -represents the number on the top of the stack. If an entered formula -contains any @kbd{$} characters, the Calculator replaces the top of -stack with that formula rather than simply pushing the formula onto the -stack. Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2 -@key{RET}} replaces it with 6. Note that the @kbd{$} key always -initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the -first character in the new formula. - -Higher stack elements can be accessed from an entered formula with the -symbols @kbd{$$}, @kbd{$$$}, and so on. The number of stack elements -removed (to be replaced by the entered values) equals the number of dollar -signs in the longest such symbol in the formula. For example, @samp{$$+$$$} -adds the second and third stack elements, replacing the top three elements -with the answer. (All information about the top stack element is thus lost -since no single @samp{$} appears in this formula.) - -A slightly different way to refer to stack elements is with a dollar -sign followed by a number: @samp{$1}, @samp{$2}, and so on are much -like @samp{$}, @samp{$$}, etc., except that stack entries referred -to numerically are not replaced by the algebraic entry. That is, while -@samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5 -on the stack and pushes an additional 6. - -If a sequence of formulas are entered separated by commas, each formula -is pushed onto the stack in turn. For example, @samp{1,2,3} pushes -those three numbers onto the stack (leaving the 3 at the top), and -@samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6. Also, -@samp{$,$$} exchanges the top two elements of the stack, just like the -@key{TAB} key. - -You can finish an algebraic entry with @kbd{M-=} or @kbd{M-@key{RET}} instead -of @key{RET}. This uses @kbd{=} to evaluate the variables in each -formula that goes onto the stack. (Thus @kbd{' pi @key{RET}} pushes -the variable @samp{pi}, but @kbd{' pi M-@key{RET}} pushes 3.1415.) - -If you finish your algebraic entry by pressing @key{LFD} (or @kbd{C-j}) -instead of @key{RET}, Calc disables simplification -(as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry -is being pushed on the stack. Thus @kbd{' 1+2 @key{RET}} pushes 3 -on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @expr{1+2}; -you might then press @kbd{=} when it is time to evaluate this formula. - -@node Quick Calculator, Prefix Arguments, Algebraic Entry, Introduction -@section ``Quick Calculator'' Mode - -@noindent -@kindex C-x * q -@pindex quick-calc -@cindex Quick Calculator -There is another way to invoke the Calculator if all you need to do -is make one or two quick calculations. Type @kbd{C-x * q} (or -@kbd{M-x quick-calc}), then type any formula as an algebraic entry. -The Calculator will compute the result and display it in the echo -area, without ever actually putting up a Calc window. - -You can use the @kbd{$} character in a Quick Calculator formula to -refer to the previous Quick Calculator result. Older results are -not retained; the Quick Calculator has no effect on the full -Calculator's stack or trail. If you compute a result and then -forget what it was, just run @code{C-x * q} again and enter -@samp{$} as the formula. - -If this is the first time you have used the Calculator in this Emacs -session, the @kbd{C-x * q} command will create the @file{*Calculator*} -buffer and perform all the usual initializations; it simply will -refrain from putting that buffer up in a new window. The Quick -Calculator refers to the @file{*Calculator*} buffer for all mode -settings. Thus, for example, to set the precision that the Quick -Calculator uses, simply run the full Calculator momentarily and use -the regular @kbd{p} command. - -If you use @code{C-x * q} from inside the Calculator buffer, the -effect is the same as pressing the apostrophe key (algebraic entry). - -The result of a Quick calculation is placed in the Emacs ``kill ring'' -as well as being displayed. A subsequent @kbd{C-y} command will -yank the result into the editing buffer. You can also use this -to yank the result into the next @kbd{C-x * q} input line as a more -explicit alternative to @kbd{$} notation, or to yank the result -into the Calculator stack after typing @kbd{C-x * c}. - -If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead -of @key{RET}, the result is inserted immediately into the current -buffer rather than going into the kill ring. - -Quick Calculator results are actually evaluated as if by the @kbd{=} -key (which replaces variable names by their stored values, if any). -If the formula you enter is an assignment to a variable using the -@samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1}, -then the result of the evaluation is stored in that Calc variable. -@xref{Store and Recall}. - -If the result is an integer and the current display radix is decimal, -the number will also be displayed in hex, octal and binary formats. If -the integer is in the range from 1 to 126, it will also be displayed as -an ASCII character. - -For example, the quoted character @samp{"x"} produces the vector -result @samp{[120]} (because 120 is the ASCII code of the lower-case -`x'; @pxref{Strings}). Since this is a vector, not an integer, it -is displayed only according to the current mode settings. But -running Quick Calc again and entering @samp{120} will produce the -result @samp{120 (16#78, 8#170, x)} which shows the number in its -decimal, hexadecimal, octal, and ASCII forms. - -Please note that the Quick Calculator is not any faster at loading -or computing the answer than the full Calculator; the name ``quick'' -merely refers to the fact that it's much less hassle to use for -small calculations. - -@node Prefix Arguments, Undo, Quick Calculator, Introduction -@section Numeric Prefix Arguments - -@noindent -Many Calculator commands use numeric prefix arguments. Some, such as -@kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of -the prefix argument or use a default if you don't use a prefix. -Others (like @kbd{d f} (@code{calc-fix-notation})) require an argument -and prompt for a number if you don't give one as a prefix. - -As a rule, stack-manipulation commands accept a numeric prefix argument -which is interpreted as an index into the stack. A positive argument -operates on the top @var{n} stack entries; a negative argument operates -on the @var{n}th stack entry in isolation; and a zero argument operates -on the entire stack. - -Most commands that perform computations (such as the arithmetic and -scientific functions) accept a numeric prefix argument that allows the -operation to be applied across many stack elements. For unary operations -(that is, functions of one argument like absolute value or complex -conjugate), a positive prefix argument applies that function to the top -@var{n} stack entries simultaneously, and a negative argument applies it -to the @var{n}th stack entry only. For binary operations (functions of -two arguments like addition, GCD, and vector concatenation), a positive -prefix argument ``reduces'' the function across the top @var{n} -stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries; -@pxref{Reducing and Mapping}), and a negative argument maps the next-to-top -@var{n} stack elements with the top stack element as a second argument -(for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements). -This feature is not available for operations which use the numeric prefix -argument for some other purpose. - -Numeric prefixes are specified the same way as always in Emacs: Press -a sequence of @key{META}-digits, or press @key{ESC} followed by digits, -or press @kbd{C-u} followed by digits. Some commands treat plain -@kbd{C-u} (without any actual digits) specially. - -@kindex ~ -@pindex calc-num-prefix -You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the -top of the stack and enter it as the numeric prefix for the next command. -For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate -(silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2 -to the fourth power and set the precision to that value. - -Conversely, if you have typed a numeric prefix argument the @kbd{~} key -pushes it onto the stack in the form of an integer. - -@node Undo, Error Messages, Prefix Arguments, Introduction -@section Undoing Mistakes - -@noindent -@kindex U -@kindex C-_ -@pindex calc-undo -@cindex Mistakes, undoing -@cindex Undoing mistakes -@cindex Errors, undoing -The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation. -If that operation added or dropped objects from the stack, those objects -are removed or restored. If it was a ``store'' operation, you are -queried whether or not to restore the variable to its original value. -The @kbd{U} key may be pressed any number of times to undo successively -farther back in time; with a numeric prefix argument it undoes a -specified number of operations. When the Calculator is quit, as with -the @kbd{q} (@code{calc-quit}) command, the undo history will be -truncated to the length of the customizable variable -@code{calc-undo-length} (@pxref{Customizing Calc}), which by default -is @expr{100}. (Recall that @kbd{C-x * c} is synonymous with -@code{calc-quit} while inside the Calculator; this also truncates the -undo history.) - -Currently the mode-setting commands (like @code{calc-precision}) are not -undoable. You can undo past a point where you changed a mode, but you -will need to reset the mode yourself. - -@kindex D -@pindex calc-redo -@cindex Redoing after an Undo -The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was -mistakenly undone. Pressing @kbd{U} with a negative prefix argument is -equivalent to executing @code{calc-redo}. You can redo any number of -times, up to the number of recent consecutive undo commands. Redo -information is cleared whenever you give any command that adds new undo -information, i.e., if you undo, then enter a number on the stack or make -any other change, then it will be too late to redo. - -@kindex M-@key{RET} -@pindex calc-last-args -@cindex Last-arguments feature -@cindex Arguments, restoring -The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that -it restores the arguments of the most recent command onto the stack; -however, it does not remove the result of that command. Given a numeric -prefix argument, this command applies to the @expr{n}th most recent -command which removed items from the stack; it pushes those items back -onto the stack. - -The @kbd{K} (@code{calc-keep-args}) command provides a related function -to @kbd{M-@key{RET}}. @xref{Stack and Trail}. - -It is also possible to recall previous results or inputs using the trail. -@xref{Trail Commands}. - -The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}. - -@node Error Messages, Multiple Calculators, Undo, Introduction -@section Error Messages - -@noindent -@kindex w -@pindex calc-why -@cindex Errors, messages -@cindex Why did an error occur? -Many situations that would produce an error message in other calculators -simply create unsimplified formulas in the Emacs Calculator. For example, -@kbd{1 @key{RET} 0 /} pushes the formula @expr{1 / 0}; @w{@kbd{0 L}} pushes -the formula @samp{ln(0)}. Floating-point overflow and underflow are also -reasons for this to happen. - -When a function call must be left in symbolic form, Calc usually -produces a message explaining why. Messages that are probably -surprising or indicative of user errors are displayed automatically. -Other messages are simply kept in Calc's memory and are displayed only -if you type @kbd{w} (@code{calc-why}). You can also press @kbd{w} if -the same computation results in several messages. (The first message -will end with @samp{[w=more]} in this case.) - -@kindex d w -@pindex calc-auto-why -The @kbd{d w} (@code{calc-auto-why}) command controls when error messages -are displayed automatically. (Calc effectively presses @kbd{w} for you -after your computation finishes.) By default, this occurs only for -``important'' messages. The other possible modes are to report -@emph{all} messages automatically, or to report none automatically (so -that you must always press @kbd{w} yourself to see the messages). - -@node Multiple Calculators, Troubleshooting Commands, Error Messages, Introduction -@section Multiple Calculators - -@noindent -@pindex another-calc -It is possible to have any number of Calc mode buffers at once. -Usually this is done by executing @kbd{M-x another-calc}, which -is similar to @kbd{C-x * c} except that if a @file{*Calculator*} -buffer already exists, a new, independent one with a name of the -form @file{*Calculator*<@var{n}>} is created. You can also use the -command @code{calc-mode} to put any buffer into Calculator mode, but -this would ordinarily never be done. - -The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer; -it only closes its window. Use @kbd{M-x kill-buffer} to destroy a -Calculator buffer. - -Each Calculator buffer keeps its own stack, undo list, and mode settings -such as precision, angular mode, and display formats. In Emacs terms, -variables such as @code{calc-stack} are buffer-local variables. The -global default values of these variables are used only when a new -Calculator buffer is created. The @code{calc-quit} command saves -the stack and mode settings of the buffer being quit as the new defaults. - -There is only one trail buffer, @file{*Calc Trail*}, used by all -Calculator buffers. - -@node Troubleshooting Commands, , Multiple Calculators, Introduction -@section Troubleshooting Commands - -@noindent -This section describes commands you can use in case a computation -incorrectly fails or gives the wrong answer. - -@xref{Reporting Bugs}, if you find a problem that appears to be due -to a bug or deficiency in Calc. - -@menu -* Autoloading Problems:: -* Recursion Depth:: -* Caches:: -* Debugging Calc:: -@end menu - -@node Autoloading Problems, Recursion Depth, Troubleshooting Commands, Troubleshooting Commands -@subsection Autoloading Problems - -@noindent -The Calc program is split into many component files; components are -loaded automatically as you use various commands that require them. -Occasionally Calc may lose track of when a certain component is -necessary; typically this means you will type a command and it won't -work because some function you've never heard of was undefined. - -@kindex C-x * L -@pindex calc-load-everything -If this happens, the easiest workaround is to type @kbd{C-x * L} -(@code{calc-load-everything}) to force all the parts of Calc to be -loaded right away. This will cause Emacs to take up a lot more -memory than it would otherwise, but it's guaranteed to fix the problem. - -@node Recursion Depth, Caches, Autoloading Problems, Troubleshooting Commands -@subsection Recursion Depth - -@noindent -@kindex M -@kindex I M -@pindex calc-more-recursion-depth -@pindex calc-less-recursion-depth -@cindex Recursion depth -@cindex ``Computation got stuck'' message -@cindex @code{max-lisp-eval-depth} -@cindex @code{max-specpdl-size} -Calc uses recursion in many of its calculations. Emacs Lisp keeps a -variable @code{max-lisp-eval-depth} which limits the amount of recursion -possible in an attempt to recover from program bugs. If a calculation -ever halts incorrectly with the message ``Computation got stuck or -ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth}) -to increase this limit. (Of course, this will not help if the -calculation really did get stuck due to some problem inside Calc.) - -The limit is always increased (multiplied) by a factor of two. There -is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which -decreases this limit by a factor of two, down to a minimum value of 200. -The default value is 1000. - -These commands also double or halve @code{max-specpdl-size}, another -internal Lisp recursion limit. The minimum value for this limit is 600. - -@node Caches, Debugging Calc, Recursion Depth, Troubleshooting Commands -@subsection Caches - -@noindent -@cindex Caches -@cindex Flushing caches -Calc saves certain values after they have been computed once. For -example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the -constant @cpi{} to about 20 decimal places; if the current precision -is greater than this, it will recompute @cpi{} using a series -approximation. This value will not need to be recomputed ever again -unless you raise the precision still further. Many operations such as -logarithms and sines make use of similarly cached values such as -@cpiover{4} and -@texline @math{\ln 2}. -@infoline @expr{ln(2)}. -The visible effect of caching is that -high-precision computations may seem to do extra work the first time. -Other things cached include powers of two (for the binary arithmetic -functions), matrix inverses and determinants, symbolic integrals, and -data points computed by the graphing commands. - -@pindex calc-flush-caches -If you suspect a Calculator cache has become corrupt, you can use the -@code{calc-flush-caches} command to reset all caches to the empty state. -(This should only be necessary in the event of bugs in the Calculator.) -The @kbd{C-x * 0} (with the zero key) command also resets caches along -with all other aspects of the Calculator's state. - -@node Debugging Calc, , Caches, Troubleshooting Commands -@subsection Debugging Calc - -@noindent -A few commands exist to help in the debugging of Calc commands. -@xref{Programming}, to see the various ways that you can write -your own Calc commands. - -@kindex Z T -@pindex calc-timing -The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode -in which the timing of slow commands is reported in the Trail. -Any Calc command that takes two seconds or longer writes a line -to the Trail showing how many seconds it took. This value is -accurate only to within one second. - -All steps of executing a command are included; in particular, time -taken to format the result for display in the stack and trail is -counted. Some prompts also count time taken waiting for them to -be answered, while others do not; this depends on the exact -implementation of the command. For best results, if you are timing -a sequence that includes prompts or multiple commands, define a -keyboard macro to run the whole sequence at once. Calc's @kbd{X} -command (@pxref{Keyboard Macros}) will then report the time taken -to execute the whole macro. - -Another advantage of the @kbd{X} command is that while it is -executing, the stack and trail are not updated from step to step. -So if you expect the output of your test sequence to leave a result -that may take a long time to format and you don't wish to count -this formatting time, end your sequence with a @key{DEL} keystroke -to clear the result from the stack. When you run the sequence with -@kbd{X}, Calc will never bother to format the large result. - -Another thing @kbd{Z T} does is to increase the Emacs variable -@code{gc-cons-threshold} to a much higher value (two million; the -usual default in Calc is 250,000) for the duration of each command. -This generally prevents garbage collection during the timing of -the command, though it may cause your Emacs process to grow -abnormally large. (Garbage collection time is a major unpredictable -factor in the timing of Emacs operations.) - -Another command that is useful when debugging your own Lisp -extensions to Calc is @kbd{M-x calc-pass-errors}, which disables -the error handler that changes the ``@code{max-lisp-eval-depth} -exceeded'' message to the much more friendly ``Computation got -stuck or ran too long.'' This handler interferes with the Emacs -Lisp debugger's @code{debug-on-error} mode. Errors are reported -in the handler itself rather than at the true location of the -error. After you have executed @code{calc-pass-errors}, Lisp -errors will be reported correctly but the user-friendly message -will be lost. - -@node Data Types, Stack and Trail, Introduction, Top -@chapter Data Types - -@noindent -This chapter discusses the various types of objects that can be placed -on the Calculator stack, how they are displayed, and how they are -entered. (@xref{Data Type Formats}, for information on how these data -types are represented as underlying Lisp objects.) - -Integers, fractions, and floats are various ways of describing real -numbers. HMS forms also for many purposes act as real numbers. These -types can be combined to form complex numbers, modulo forms, error forms, -or interval forms. (But these last four types cannot be combined -arbitrarily: error forms may not contain modulo forms, for example.) -Finally, all these types of numbers may be combined into vectors, -matrices, or algebraic formulas. - -@menu -* Integers:: The most basic data type. -* Fractions:: This and above are called @dfn{rationals}. -* Floats:: This and above are called @dfn{reals}. -* Complex Numbers:: This and above are called @dfn{numbers}. -* Infinities:: -* Vectors and Matrices:: -* Strings:: -* HMS Forms:: -* Date Forms:: -* Modulo Forms:: -* Error Forms:: -* Interval Forms:: -* Incomplete Objects:: -* Variables:: -* Formulas:: -@end menu - -@node Integers, Fractions, Data Types, Data Types -@section Integers - -@noindent -@cindex Integers -The Calculator stores integers to arbitrary precision. Addition, -subtraction, and multiplication of integers always yields an exact -integer result. (If the result of a division or exponentiation of -integers is not an integer, it is expressed in fractional or -floating-point form according to the current Fraction mode. -@xref{Fraction Mode}.) - -A decimal integer is represented as an optional sign followed by a -sequence of digits. Grouping (@pxref{Grouping Digits}) can be used to -insert a comma at every third digit for display purposes, but you -must not type commas during the entry of numbers. - -@kindex # -A non-decimal integer is represented as an optional sign, a radix -between 2 and 36, a @samp{#} symbol, and one or more digits. For radix 11 -and above, the letters A through Z (upper- or lower-case) count as -digits and do not terminate numeric entry mode. @xref{Radix Modes}, for how -to set the default radix for display of integers. Numbers of any radix -may be entered at any time. If you press @kbd{#} at the beginning of a -number, the current display radix is used. - -@node Fractions, Floats, Integers, Data Types -@section Fractions - -@noindent -@cindex Fractions -A @dfn{fraction} is a ratio of two integers. Fractions are traditionally -written ``2/3'' but Calc uses the notation @samp{2:3}. (The @kbd{/} key -performs RPN division; the following two sequences push the number -@samp{2:3} on the stack: @kbd{2 :@: 3 @key{RET}}, or @kbd{2 @key{RET} 3 /} -assuming Fraction mode has been enabled.) -When the Calculator produces a fractional result it always reduces it to -simplest form, which may in fact be an integer. - -Fractions may also be entered in a three-part form, where @samp{2:3:4} -represents two-and-three-quarters. @xref{Fraction Formats}, for fraction -display formats. - -Non-decimal fractions are entered and displayed as -@samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part -form). The numerator and denominator always use the same radix. - -@node Floats, Complex Numbers, Fractions, Data Types -@section Floats - -@noindent -@cindex Floating-point numbers -A floating-point number or @dfn{float} is a number stored in scientific -notation. The number of significant digits in the fractional part is -governed by the current floating precision (@pxref{Precision}). The -range of acceptable values is from -@texline @math{10^{-3999999}} -@infoline @expr{10^-3999999} -(inclusive) to -@texline @math{10^{4000000}} -@infoline @expr{10^4000000} -(exclusive), plus the corresponding negative values and zero. - -Calculations that would exceed the allowable range of values (such -as @samp{exp(exp(20))}) are left in symbolic form by Calc. The -messages ``floating-point overflow'' or ``floating-point underflow'' -indicate that during the calculation a number would have been produced -that was too large or too close to zero, respectively, to be represented -by Calc. This does not necessarily mean the final result would have -overflowed, just that an overflow occurred while computing the result. -(In fact, it could report an underflow even though the final result -would have overflowed!) - -If a rational number and a float are mixed in a calculation, the result -will in general be expressed as a float. Commands that require an integer -value (such as @kbd{k g} [@code{gcd}]) will also accept integer-valued -floats, i.e., floating-point numbers with nothing after the decimal point. - -Floats are identified by the presence of a decimal point and/or an -exponent. In general a float consists of an optional sign, digits -including an optional decimal point, and an optional exponent consisting -of an @samp{e}, an optional sign, and up to seven exponent digits. -For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power, -or 0.235. - -Floating-point numbers are normally displayed in decimal notation with -all significant figures shown. Exceedingly large or small numbers are -displayed in scientific notation. Various other display options are -available. @xref{Float Formats}. - -@cindex Accuracy of calculations -Floating-point numbers are stored in decimal, not binary. The result -of each operation is rounded to the nearest value representable in the -number of significant digits specified by the current precision, -rounding away from zero in the case of a tie. Thus (in the default -display mode) what you see is exactly what you get. Some operations such -as square roots and transcendental functions are performed with several -digits of extra precision and then rounded down, in an effort to make the -final result accurate to the full requested precision. However, -accuracy is not rigorously guaranteed. If you suspect the validity of a -result, try doing the same calculation in a higher precision. The -Calculator's arithmetic is not intended to be IEEE-conformant in any -way. - -While floats are always @emph{stored} in decimal, they can be entered -and displayed in any radix just like integers and fractions. Since a -float that is entered in a radix other that 10 will be converted to -decimal, the number that Calc stores may not be exactly the number that -was entered, it will be the closest decimal approximation given the -current precision. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}} -is a floating-point number whose digits are in the specified radix. -Note that the @samp{.} is more aptly referred to as a ``radix point'' -than as a decimal point in this case. The number @samp{8#123.4567} is -defined as @samp{8#1234567 * 8^-4}. If the radix is 14 or less, you can -use @samp{e} notation to write a non-decimal number in scientific -notation. The exponent is written in decimal, and is considered to be a -power of the radix: @samp{8#1234567e-4}. If the radix is 15 or above, -the letter @samp{e} is a digit, so scientific notation must be written -out, e.g., @samp{16#123.4567*16^2}. The first two exercises of the -Modes Tutorial explore some of the properties of non-decimal floats. - -@node Complex Numbers, Infinities, Floats, Data Types -@section Complex Numbers - -@noindent -@cindex Complex numbers -There are two supported formats for complex numbers: rectangular and -polar. The default format is rectangular, displayed in the form -@samp{(@var{real},@var{imag})} where @var{real} is the real part and -@var{imag} is the imaginary part, each of which may be any real number. -Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i} -notation; @pxref{Complex Formats}. - -Polar complex numbers are displayed in the form -@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}' -@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}' -where @var{r} is the nonnegative magnitude and -@texline @math{\theta} -@infoline @var{theta} -is the argument or phase angle. The range of -@texline @math{\theta} -@infoline @var{theta} -depends on the current angular mode (@pxref{Angular Modes}); it is -generally between @mathit{-180} and @mathit{+180} degrees or the equivalent range -in radians. - -Complex numbers are entered in stages using incomplete objects. -@xref{Incomplete Objects}. - -Operations on rectangular complex numbers yield rectangular complex -results, and similarly for polar complex numbers. Where the two types -are mixed, or where new complex numbers arise (as for the square root of -a negative real), the current @dfn{Polar mode} is used to determine the -type. @xref{Polar Mode}. - -A complex result in which the imaginary part is zero (or the phase angle -is 0 or 180 degrees or @cpi{} radians) is automatically converted to a real -number. - -@node Infinities, Vectors and Matrices, Complex Numbers, Data Types -@section Infinities - -@noindent -@cindex Infinity -@cindex @code{inf} variable -@cindex @code{uinf} variable -@cindex @code{nan} variable -@vindex inf -@vindex uinf -@vindex nan -The word @code{inf} represents the mathematical concept of @dfn{infinity}. -Calc actually has three slightly different infinity-like values: -@code{inf}, @code{uinf}, and @code{nan}. These are just regular -variable names (@pxref{Variables}); you should avoid using these -names for your own variables because Calc gives them special -treatment. Infinities, like all variable names, are normally -entered using algebraic entry. - -Mathematically speaking, it is not rigorously correct to treat -``infinity'' as if it were a number, but mathematicians often do -so informally. When they say that @samp{1 / inf = 0}, what they -really mean is that @expr{1 / x}, as @expr{x} becomes larger and -larger, becomes arbitrarily close to zero. So you can imagine -that if @expr{x} got ``all the way to infinity,'' then @expr{1 / x} -would go all the way to zero. Similarly, when they say that -@samp{exp(inf) = inf}, they mean that -@texline @math{e^x} -@infoline @expr{exp(x)} -grows without bound as @expr{x} grows. The symbol @samp{-inf} likewise -stands for an infinitely negative real value; for example, we say that -@samp{exp(-inf) = 0}. You can have an infinity pointing in any -direction on the complex plane: @samp{sqrt(-inf) = i inf}. - -The same concept of limits can be used to define @expr{1 / 0}. We -really want the value that @expr{1 / x} approaches as @expr{x} -approaches zero. But if all we have is @expr{1 / 0}, we can't -tell which direction @expr{x} was coming from. If @expr{x} was -positive and decreasing toward zero, then we should say that -@samp{1 / 0 = inf}. But if @expr{x} was negative and increasing -toward zero, the answer is @samp{1 / 0 = -inf}. In fact, @expr{x} -could be an imaginary number, giving the answer @samp{i inf} or -@samp{-i inf}. Calc uses the special symbol @samp{uinf} to mean -@dfn{undirected infinity}, i.e., a value which is infinitely -large but with an unknown sign (or direction on the complex plane). - -Calc actually has three modes that say how infinities are handled. -Normally, infinities never arise from calculations that didn't -already have them. Thus, @expr{1 / 0} is treated simply as an -error and left unevaluated. The @kbd{m i} (@code{calc-infinite-mode}) -command (@pxref{Infinite Mode}) enables a mode in which -@expr{1 / 0} evaluates to @code{uinf} instead. There is also -an alternative type of infinite mode which says to treat zeros -as if they were positive, so that @samp{1 / 0 = inf}. While this -is less mathematically correct, it may be the answer you want in -some cases. - -Since all infinities are ``as large'' as all others, Calc simplifies, -e.g., @samp{5 inf} to @samp{inf}. Another example is -@samp{5 - inf = -inf}, where the @samp{-inf} is so large that -adding a finite number like five to it does not affect it. -Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes -that variables like @code{a} always stand for finite quantities. -Just to show that infinities really are all the same size, -note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's -notation. - -It's not so easy to define certain formulas like @samp{0 * inf} and -@samp{inf / inf}. Depending on where these zeros and infinities -came from, the answer could be literally anything. The latter -formula could be the limit of @expr{x / x} (giving a result of one), -or @expr{2 x / x} (giving two), or @expr{x^2 / x} (giving @code{inf}), -or @expr{x / x^2} (giving zero). Calc uses the symbol @code{nan} -to represent such an @dfn{indeterminate} value. (The name ``nan'' -comes from analogy with the ``NAN'' concept of IEEE standard -arithmetic; it stands for ``Not A Number.'' This is somewhat of a -misnomer, since @code{nan} @emph{does} stand for some number or -infinity, it's just that @emph{which} number it stands for -cannot be determined.) In Calc's notation, @samp{0 * inf = nan} -and @samp{inf / inf = nan}. A few other common indeterminate -expressions are @samp{inf - inf} and @samp{inf ^ 0}. Also, -@samp{0 / 0 = nan} if you have turned on Infinite mode -(as described above). - -Infinities are especially useful as parts of @dfn{intervals}. -@xref{Interval Forms}. - -@node Vectors and Matrices, Strings, Infinities, Data Types -@section Vectors and Matrices - -@noindent -@cindex Vectors -@cindex Plain vectors -@cindex Matrices -The @dfn{vector} data type is flexible and general. A vector is simply a -list of zero or more data objects. When these objects are numbers, the -whole is a vector in the mathematical sense. When these objects are -themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}. -A vector which is not a matrix is referred to here as a @dfn{plain vector}. - -A vector is displayed as a list of values separated by commas and enclosed -in square brackets: @samp{[1, 2, 3]}. Thus the following is a 2 row by -3 column matrix: @samp{[[1, 2, 3], [4, 5, 6]]}. Vectors, like complex -numbers, are entered as incomplete objects. @xref{Incomplete Objects}. -During algebraic entry, vectors are entered all at once in the usual -brackets-and-commas form. Matrices may be entered algebraically as nested -vectors, or using the shortcut notation @w{@samp{[1, 2, 3; 4, 5, 6]}}, -with rows separated by semicolons. The commas may usually be omitted -when entering vectors: @samp{[1 2 3]}. Curly braces may be used in -place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in -this case. - -Traditional vector and matrix arithmetic is also supported; -@pxref{Basic Arithmetic} and @pxref{Matrix Functions}. -Many other operations are applied to vectors element-wise. For example, -the complex conjugate of a vector is a vector of the complex conjugates -of its elements. - -@ignore -@starindex -@end ignore -@tindex vec -Algebraic functions for building vectors include @samp{vec(a, b, c)} -to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an -@texline @math{n\times m} -@infoline @var{n}x@var{m} -matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers -from 1 to @samp{n}. - -@node Strings, HMS Forms, Vectors and Matrices, Data Types -@section Strings - -@noindent -@kindex " -@cindex Strings -@cindex Character strings -Character strings are not a special data type in the Calculator. -Rather, a string is represented simply as a vector all of whose -elements are integers in the range 0 to 255 (ASCII codes). You can -enter a string at any time by pressing the @kbd{"} key. Quotation -marks and backslashes are written @samp{\"} and @samp{\\}, respectively, -inside strings. Other notations introduced by backslashes are: - -@example -@group -\a 7 \^@@ 0 -\b 8 \^a-z 1-26 -\e 27 \^[ 27 -\f 12 \^\\ 28 -\n 10 \^] 29 -\r 13 \^^ 30 -\t 9 \^_ 31 - \^? 127 -@end group -@end example - -@noindent -Finally, a backslash followed by three octal digits produces any -character from its ASCII code. - -@kindex d " -@pindex calc-display-strings -Strings are normally displayed in vector-of-integers form. The -@w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in -which any vectors of small integers are displayed as quoted strings -instead. - -The backslash notations shown above are also used for displaying -strings. Characters 128 and above are not translated by Calc; unless -you have an Emacs modified for 8-bit fonts, these will show up in -backslash-octal-digits notation. For characters below 32, and -for character 127, Calc uses the backslash-letter combination if -there is one, or otherwise uses a @samp{\^} sequence. - -The only Calc feature that uses strings is @dfn{compositions}; -@pxref{Compositions}. Strings also provide a convenient -way to do conversions between ASCII characters and integers. - -@ignore -@starindex -@end ignore -@tindex string -There is a @code{string} function which provides a different display -format for strings. Basically, @samp{string(@var{s})}, where @var{s} -is a vector of integers in the proper range, is displayed as the -corresponding string of characters with no surrounding quotation -marks or other modifications. Thus @samp{string("ABC")} (or -@samp{string([65 66 67])}) will look like @samp{ABC} on the stack. -This happens regardless of whether @w{@kbd{d "}} has been used. The -only way to turn it off is to use @kbd{d U} (unformatted language -mode) which will display @samp{string("ABC")} instead. - -Control characters are displayed somewhat differently by @code{string}. -Characters below 32, and character 127, are shown using @samp{^} notation -(same as shown above, but without the backslash). The quote and -backslash characters are left alone, as are characters 128 and above. - -@ignore -@starindex -@end ignore -@tindex bstring -The @code{bstring} function is just like @code{string} except that -the resulting string is breakable across multiple lines if it doesn't -fit all on one line. Potential break points occur at every space -character in the string. - -@node HMS Forms, Date Forms, Strings, Data Types -@section HMS Forms - -@noindent -@cindex Hours-minutes-seconds forms -@cindex Degrees-minutes-seconds forms -@dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular -argument, the interpretation is Degrees-Minutes-Seconds. All functions -that operate on angles accept HMS forms. These are interpreted as -degrees regardless of the current angular mode. It is also possible to -use HMS as the angular mode so that calculated angles are expressed in -degrees, minutes, and seconds. - -@kindex @@ -@ignore -@mindex @null -@end ignore -@kindex ' (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex " (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex h (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex o (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex m (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex s (HMS forms) -The default format for HMS values is -@samp{@var{hours}@@ @var{mins}' @var{secs}"}. During entry, the letters -@samp{h} (for ``hours'') or -@samp{o} (approximating the ``degrees'' symbol) are accepted as well as -@samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is -accepted in place of @samp{"}. -The @var{hours} value is an integer (or integer-valued float). -The @var{mins} value is an integer or integer-valued float between 0 and 59. -The @var{secs} value is a real number between 0 (inclusive) and 60 -(exclusive). A positive HMS form is interpreted as @var{hours} + -@var{mins}/60 + @var{secs}/3600. A negative HMS form is interpreted -as @mathit{- @var{hours}} @mathit{-} @var{mins}/60 @mathit{-} @var{secs}/3600. -Display format for HMS forms is quite flexible. @xref{HMS Formats}. - -HMS forms can be added and subtracted. When they are added to numbers, -the numbers are interpreted according to the current angular mode. HMS -forms can also be multiplied and divided by real numbers. Dividing -two HMS forms produces a real-valued ratio of the two angles. - -@pindex calc-time -@cindex Time of day -Just for kicks, @kbd{M-x calc-time} pushes the current time of day on -the stack as an HMS form. - -@node Date Forms, Modulo Forms, HMS Forms, Data Types -@section Date Forms - -@noindent -@cindex Date forms -A @dfn{date form} represents a date and possibly an associated time. -Simple date arithmetic is supported: Adding a number to a date -produces a new date shifted by that many days; adding an HMS form to -a date shifts it by that many hours. Subtracting two date forms -computes the number of days between them (represented as a simple -number). Many other operations, such as multiplying two date forms, -are nonsensical and are not allowed by Calc. - -Date forms are entered and displayed enclosed in @samp{< >} brackets. -The default format is, e.g., @samp{} for dates, -or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times. -Input is flexible; date forms can be entered in any of the usual -notations for dates and times. @xref{Date Formats}. - -Date forms are stored internally as numbers, specifically the number -of days since midnight on the morning of December 31 of the year 1 BC@. -If the internal number is an integer, the form represents a date only; -if the internal number is a fraction or float, the form represents -a date and time. For example, @samp{<6:00am Thu Jan 10, 1991>} -is represented by the number 726842.25. The standard precision of -12 decimal digits is enough to ensure that a (reasonable) date and -time can be stored without roundoff error. - -If the current precision is greater than 12, date forms will keep -additional digits in the seconds position. For example, if the -precision is 15, the seconds will keep three digits after the -decimal point. Decreasing the precision below 12 may cause the -time part of a date form to become inaccurate. This can also happen -if astronomically high years are used, though this will not be an -issue in everyday (or even everymillennium) use. Note that date -forms without times are stored as exact integers, so roundoff is -never an issue for them. - -You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u} -(@code{calc-unpack}) commands to get at the numerical representation -of a date form. @xref{Packing and Unpacking}. - -Date forms can go arbitrarily far into the future or past. Negative -year numbers represent years BC@. There is no ``year 0''; the day -before @samp{} is @samp{}. These are -days 1 and 0 respectively in Calc's internal numbering scheme. The -Gregorian calendar is used for all dates, including dates before the -Gregorian calendar was invented (although that can be configured; see -below). Thus Calc's use of the day number @mathit{-10000} to -represent August 15, 28 BC should be taken with a grain of salt. - -@cindex Julian calendar -@cindex Gregorian calendar -Some historical background: The Julian calendar was created by -Julius Caesar in the year 46 BC as an attempt to fix the confusion -caused by the irregular Roman calendar that was used before that time. -The Julian calendar introduced an extra day in all years divisible by -four. After some initial confusion, the calendar was adopted around -the year we call 8 AD@. Some centuries later it became -apparent that the Julian year of 365.25 days was itself not quite -right. In 1582 Pope Gregory XIII introduced the Gregorian calendar, -which added the new rule that years divisible by 100, but not by 400, -were not to be considered leap years despite being divisible by four. -Many countries delayed adoption of the Gregorian calendar -because of religious differences. For example, Great Britain and the -British colonies switched to the Gregorian calendar in September -1752, when the Julian calendar was eleven days behind the -Gregorian calendar. That year in Britain, the day after September 2 -was September 14. To take another example, Russia did not adopt the -Gregorian calendar until 1918, and that year in Russia the day after -January 31 was February 14. Calc's reckoning therefore matches English -practice starting in 1752 and Russian practice starting in 1918, but -disagrees with earlier dates in both countries. - -When the Julian calendar was introduced, it had January 1 as the first -day of the year. By the Middle Ages, many European countries -had changed the beginning of a new year to a different date, often to -a religious festival. Almost all countries reverted to using January 1 -as the beginning of the year by the time they adopted the Gregorian -calendar. - -Some calendars attempt to mimic the historical situation by using the -Gregorian calendar for recent dates and the Julian calendar for older -dates. The @code{cal} program in most Unix implementations does this, -for example. While January 1 wasn't always the beginning of a calendar -year, these hybrid calendars still use January 1 as the beginning of -the year even for older dates. The customizable variable -@code{calc-gregorian-switch} (@pxref{Customizing Calc}) can be set to -have Calc's date forms switch from the Julian to Gregorian calendar at -any specified date. - -Today's timekeepers introduce an occasional ``leap second''. -These do not occur regularly and Calc does not take these minor -effects into account. (If it did, it would have to report a -non-integer number of days between, say, -@samp{<12:00am Mon Jan 1, 1900>} and -@samp{<12:00am Sat Jan 1, 2000>}.) - -@cindex Julian day counting -Another day counting system in common use is, confusingly, also called -``Julian.'' Julian days go from noon to noon. The Julian day number -is the numbers of days since 12:00 noon (GMT) on November 24, 4714 BC -in the Gregorian calendar (i.e., January 1, 4713 BC in the Julian -calendar). In Calc's scheme (in GMT) the Julian day origin is -@mathit{-1721422.5}, because Calc starts at midnight instead of noon. -Thus to convert a Calc date code obtained by unpacking a -date form into a Julian day number, simply add 1721422.5 after -compensating for the time zone difference. The built-in @kbd{t J} -command performs this conversion for you. - -The Julian day number is based on the Julian cycle, which was invented -in 1583 by Joseph Justus Scaliger. Scaliger named it the Julian cycle -since it involves the Julian calendar, but some have suggested that -Scaliger named it in honor of his father, Julius Caesar Scaliger. The -Julian cycle is based on three other cycles: the indiction cycle, the -Metonic cycle, and the solar cycle. The indiction cycle is a 15 year -cycle originally used by the Romans for tax purposes but later used to -date medieval documents. The Metonic cycle is a 19 year cycle; 19 -years is close to being a common multiple of a solar year and a lunar -month, and so every 19 years the phases of the moon will occur on the -same days of the year. The solar cycle is a 28 year cycle; the Julian -calendar repeats itself every 28 years. The smallest time period -which contains multiples of all three cycles is the least common -multiple of 15 years, 19 years and 28 years, which (since they're -pairwise relatively prime) is -@texline @math{15\times 19\times 28 = 7980} years. -@infoline 15*19*28 = 7980 years. -This is the length of a Julian cycle. Working backwards, the previous -year in which all three cycles began was 4713 BC, and so Scaliger -chose that year as the beginning of a Julian cycle. Since at the time -there were no historical records from before 4713 BC, using this year -as a starting point had the advantage of avoiding negative year -numbers. In 1849, the astronomer John Herschel (son of William -Herschel) suggested using the number of days since the beginning of -the Julian cycle as an astronomical dating system; this idea was taken -up by other astronomers. (At the time, noon was the start of the -astronomical day. Herschel originally suggested counting the days -since Jan 1, 4713 BC at noon Alexandria time; this was later amended to -noon GMT@.) Julian day numbering is largely used in astronomy. - -@cindex Unix time format -The Unix operating system measures time as an integer number of -seconds since midnight, Jan 1, 1970. To convert a Calc date -value into a Unix time stamp, first subtract 719164 (the code -for @samp{}), then multiply by 86400 (the number of -seconds in a day) and press @kbd{R} to round to the nearest -integer. If you have a date form, you can simply subtract the -day @samp{} instead of unpacking and subtracting -719164. Likewise, divide by 86400 and add @samp{} -to convert from Unix time to a Calc date form. (Note that -Unix normally maintains the time in the GMT time zone; you may -need to subtract five hours to get New York time, or eight hours -for California time. The same is usually true of Julian day -counts.) The built-in @kbd{t U} command performs these -conversions. - -@node Modulo Forms, Error Forms, Date Forms, Data Types -@section Modulo Forms - -@noindent -@cindex Modulo forms -A @dfn{modulo form} is a real number which is taken modulo (i.e., within -an integer multiple of) some value @var{M}. Arithmetic modulo @var{M} -often arises in number theory. Modulo forms are written -`@var{a} @tfn{mod} @var{M}', -where @var{a} and @var{M} are real numbers or HMS forms, and -@texline @math{0 \le a < M}. -@infoline @expr{0 <= a < @var{M}}. -In many applications @expr{a} and @expr{M} will be -integers but this is not required. - -@ignore -@mindex M -@end ignore -@kindex M (modulo forms) -@ignore -@mindex mod -@end ignore -@tindex mod (operator) -To create a modulo form during numeric entry, press the shift-@kbd{M} -key to enter the word @samp{mod}. As a special convenience, pressing -shift-@kbd{M} a second time automatically enters the value of @expr{M} -that was most recently used before. During algebraic entry, either -type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}). -Once again, pressing this a second time enters the current modulo. - -Modulo forms are not to be confused with the modulo operator @samp{%}. -The expression @samp{27 % 10} means to compute 27 modulo 10 to produce -the result 7. Further computations treat this 7 as just a regular integer. -The expression @samp{27 mod 10} produces the result @samp{7 mod 10}; -further computations with this value are again reduced modulo 10 so that -the result always lies in the desired range. - -When two modulo forms with identical @expr{M}'s are added or multiplied, -the Calculator simply adds or multiplies the values, then reduces modulo -@expr{M}. If one argument is a modulo form and the other a plain number, -the plain number is treated like a compatible modulo form. It is also -possible to raise modulo forms to powers; the result is the value raised -to the power, then reduced modulo @expr{M}. (When all values involved -are integers, this calculation is done much more efficiently than -actually computing the power and then reducing.) - -@cindex Modulo division -Two modulo forms `@var{a} @tfn{mod} @var{M}' and `@var{b} @tfn{mod} @var{M}' -can be divided if @expr{a}, @expr{b}, and @expr{M} are all -integers. The result is the modulo form which, when multiplied by -`@var{b} @tfn{mod} @var{M}', produces `@var{a} @tfn{mod} @var{M}'. If -there is no solution to this equation (which can happen only when -@expr{M} is non-prime), or if any of the arguments are non-integers, the -division is left in symbolic form. Other operations, such as square -roots, are not yet supported for modulo forms. (Note that, although -@w{`@tfn{(}@var{a} @tfn{mod} @var{M}@tfn{)^.5}'} will compute a ``modulo square root'' -in the sense of reducing -@texline @math{\sqrt a} -@infoline @expr{sqrt(a)} -modulo @expr{M}, this is not a useful definition from the -number-theoretical point of view.) - -It is possible to mix HMS forms and modulo forms. For example, an -HMS form modulo 24 could be used to manipulate clock times; an HMS -form modulo 360 would be suitable for angles. Making the modulo @expr{M} -also be an HMS form eliminates troubles that would arise if the angular -mode were inadvertently set to Radians, in which case -@w{@samp{2@@ 0' 0" mod 24}} would be interpreted as two degrees modulo -24 radians! - -Modulo forms cannot have variables or formulas for components. If you -enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus -to each of the coefficients: @samp{(1 mod 5) x + (2 mod 5)}. - -You can use @kbd{v p} and @kbd{%} to modify modulo forms. -@xref{Packing and Unpacking}. @xref{Basic Arithmetic}. - -@ignore -@starindex -@end ignore -@tindex makemod -The algebraic function @samp{makemod(a, m)} builds the modulo form -@w{@samp{a mod m}}. - -@node Error Forms, Interval Forms, Modulo Forms, Data Types -@section Error Forms - -@noindent -@cindex Error forms -@cindex Standard deviations -An @dfn{error form} is a number with an associated standard -deviation, as in @samp{2.3 +/- 0.12}. The notation -@texline `@var{x} @tfn{+/-} @math{\sigma}' -@infoline `@var{x} @tfn{+/-} sigma' -stands for an uncertain value which follows -a normal or Gaussian distribution of mean @expr{x} and standard -deviation or ``error'' -@texline @math{\sigma}. -@infoline @expr{sigma}. -Both the mean and the error can be either numbers or -formulas. Generally these are real numbers but the mean may also be -complex. If the error is negative or complex, it is changed to its -absolute value. An error form with zero error is converted to a -regular number by the Calculator. - -All arithmetic and transcendental functions accept error forms as input. -Operations on the mean-value part work just like operations on regular -numbers. The error part for any function @expr{f(x)} (such as -@texline @math{\sin x} -@infoline @expr{sin(x)}) -is defined by the error of @expr{x} times the derivative of @expr{f} -evaluated at the mean value of @expr{x}. For a two-argument function -@expr{f(x,y)} (such as addition) the error is the square root of the sum -of the squares of the errors due to @expr{x} and @expr{y}. -@tex -$$ \eqalign{ - f(x \hbox{\code{ +/- }} \sigma) - &= f(x) \hbox{\code{ +/- }} \sigma \left| {df(x) \over dx} \right| \cr - f(x \hbox{\code{ +/- }} \sigma_x, y \hbox{\code{ +/- }} \sigma_y) - &= f(x,y) \hbox{\code{ +/- }} - \sqrt{\left(\sigma_x \left| {\partial f(x,y) \over \partial x} - \right| \right)^2 - +\left(\sigma_y \left| {\partial f(x,y) \over \partial y} - \right| \right)^2 } \cr -} $$ -@end tex -Note that this -definition assumes the errors in @expr{x} and @expr{y} are uncorrelated. -A side effect of this definition is that @samp{(2 +/- 1) * (2 +/- 1)} -is not the same as @samp{(2 +/- 1)^2}; the former represents the product -of two independent values which happen to have the same probability -distributions, and the latter is the product of one random value with itself. -The former will produce an answer with less error, since on the average -the two independent errors can be expected to cancel out. - -Consult a good text on error analysis for a discussion of the proper use -of standard deviations. Actual errors often are neither Gaussian-distributed -nor uncorrelated, and the above formulas are valid only when errors -are small. As an example, the error arising from -@texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}' -@infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}' -is -@texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. -@infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. -When @expr{x} is close to zero, -@texline @math{\cos x} -@infoline @expr{cos(x)} -is close to one so the error in the sine is close to -@texline @math{\sigma}; -@infoline @expr{sigma}; -this makes sense, since -@texline @math{\sin x} -@infoline @expr{sin(x)} -is approximately @expr{x} near zero, so a given error in @expr{x} will -produce about the same error in the sine. Likewise, near 90 degrees -@texline @math{\cos x} -@infoline @expr{cos(x)} -is nearly zero and so the computed error is -small: The sine curve is nearly flat in that region, so an error in @expr{x} -has relatively little effect on the value of -@texline @math{\sin x}. -@infoline @expr{sin(x)}. -However, consider @samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so -Calc will report zero error! We get an obviously wrong result because -we have violated the small-error approximation underlying the error -analysis. If the error in @expr{x} had been small, the error in -@texline @math{\sin x} -@infoline @expr{sin(x)} -would indeed have been negligible. - -@ignore -@mindex p -@end ignore -@kindex p (error forms) -@tindex +/- -To enter an error form during regular numeric entry, use the @kbd{p} -(``plus-or-minus'') key to type the @samp{+/-} symbol. (If you try actually -typing @samp{+/-} the @kbd{+} key will be interpreted as the Calculator's -@kbd{+} command!) Within an algebraic formula, you can press @kbd{M-+} to -type the @samp{+/-} symbol, or type it out by hand. - -Error forms and complex numbers can be mixed; the formulas shown above -are used for complex numbers, too; note that if the error part evaluates -to a complex number its absolute value (or the square root of the sum of -the squares of the absolute values of the two error contributions) is -used. Mathematically, this corresponds to a radially symmetric Gaussian -distribution of numbers on the complex plane. However, note that Calc -considers an error form with real components to represent a real number, -not a complex distribution around a real mean. - -Error forms may also be composed of HMS forms. For best results, both -the mean and the error should be HMS forms if either one is. - -@ignore -@starindex -@end ignore -@tindex sdev -The algebraic function @samp{sdev(a, b)} builds the error form @samp{a +/- b}. - -@node Interval Forms, Incomplete Objects, Error Forms, Data Types -@section Interval Forms - -@noindent -@cindex Interval forms -An @dfn{interval} is a subset of consecutive real numbers. For example, -the interval @samp{[2 ..@: 4]} represents all the numbers from 2 to 4, -inclusive. If you multiply it by the interval @samp{[0.5 ..@: 2]} you -obtain @samp{[1 ..@: 8]}. This calculation represents the fact that if -you multiply some number in the range @samp{[2 ..@: 4]} by some other -number in the range @samp{[0.5 ..@: 2]}, your result will lie in the range -from 1 to 8. Interval arithmetic is used to get a worst-case estimate -of the possible range of values a computation will produce, given the -set of possible values of the input. - -@ifnottex -Calc supports several varieties of intervals, including @dfn{closed} -intervals of the type shown above, @dfn{open} intervals such as -@samp{(2 ..@: 4)}, which represents the range of numbers from 2 to 4 -@emph{exclusive}, and @dfn{semi-open} intervals in which one end -uses a round parenthesis and the other a square bracket. In mathematical -terms, -@samp{[2 ..@: 4]} means @expr{2 <= x <= 4}, whereas -@samp{[2 ..@: 4)} represents @expr{2 <= x < 4}, -@samp{(2 ..@: 4]} represents @expr{2 < x <= 4}, and -@samp{(2 ..@: 4)} represents @expr{2 < x < 4}. -@end ifnottex -@tex -Calc supports several varieties of intervals, including \dfn{closed} -intervals of the type shown above, \dfn{open} intervals such as -\samp{(2 ..\: 4)}, which represents the range of numbers from 2 to 4 -\emph{exclusive}, and \dfn{semi-open} intervals in which one end -uses a round parenthesis and the other a square bracket. In mathematical -terms, -$$ \eqalign{ - [2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 \le x \le 4 \cr - [2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 \le x < 4 \cr - (2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 < x \le 4 \cr - (2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 < x < 4 \cr -} $$ -@end tex - -The lower and upper limits of an interval must be either real numbers -(or HMS or date forms), or symbolic expressions which are assumed to be -real-valued, or @samp{-inf} and @samp{inf}. In general the lower limit -must be less than the upper limit. A closed interval containing only -one value, @samp{[3 ..@: 3]}, is converted to a plain number (3) -automatically. An interval containing no values at all (such as -@samp{[3 ..@: 2]} or @samp{[2 ..@: 2)}) can be represented but is not -guaranteed to behave well when used in arithmetic. Note that the -interval @samp{[3 .. inf)} represents all real numbers greater than -or equal to 3, and @samp{(-inf .. inf)} represents all real numbers. -In fact, @samp{[-inf .. inf]} represents all real numbers including -the real infinities. - -Intervals are entered in the notation shown here, either as algebraic -formulas, or using incomplete forms. (@xref{Incomplete Objects}.) -In algebraic formulas, multiple periods in a row are collected from -left to right, so that @samp{1...1e2} is interpreted as @samp{1.0 ..@: 1e2} -rather than @samp{1 ..@: 0.1e2}. Add spaces or zeros if you want to -get the other interpretation. If you omit the lower or upper limit, -a default of @samp{-inf} or @samp{inf} (respectively) is furnished. - -Infinite mode also affects operations on intervals -(@pxref{Infinities}). Calc will always introduce an open infinity, -as in @samp{1 / (0 .. 2] = [0.5 .. inf)}. But closed infinities, -@w{@samp{1 / [0 .. 2] = [0.5 .. inf]}}, arise only in Infinite mode; -otherwise they are left unevaluated. Note that the ``direction'' of -a zero is not an issue in this case since the zero is always assumed -to be continuous with the rest of the interval. For intervals that -contain zero inside them Calc is forced to give the result, -@samp{1 / (-2 .. 2) = [-inf .. inf]}. - -While it may seem that intervals and error forms are similar, they are -based on entirely different concepts of inexact quantities. An error -form -@texline `@var{x} @tfn{+/-} @math{\sigma}' -@infoline `@var{x} @tfn{+/-} @var{sigma}' -means a variable is random, and its value could -be anything but is ``probably'' within one -@texline @math{\sigma} -@infoline @var{sigma} -of the mean value @expr{x}. An interval -`@tfn{[}@var{a} @tfn{..@:} @var{b}@tfn{]}' means a -variable's value is unknown, but guaranteed to lie in the specified -range. Error forms are statistical or ``average case'' approximations; -interval arithmetic tends to produce ``worst case'' bounds on an -answer. - -Intervals may not contain complex numbers, but they may contain -HMS forms or date forms. - -@xref{Set Operations}, for commands that interpret interval forms -as subsets of the set of real numbers. - -@ignore -@starindex -@end ignore -@tindex intv -The algebraic function @samp{intv(n, a, b)} builds an interval form -from @samp{a} to @samp{b}; @samp{n} is an integer code which must -be 0 for @samp{(..)}, 1 for @samp{(..]}, 2 for @samp{[..)}, or -3 for @samp{[..]}. - -Please note that in fully rigorous interval arithmetic, care would be -taken to make sure that the computation of the lower bound rounds toward -minus infinity, while upper bound computations round toward plus -infinity. Calc's arithmetic always uses a round-to-nearest mode, -which means that roundoff errors could creep into an interval -calculation to produce intervals slightly smaller than they ought to -be. For example, entering @samp{[1..2]} and pressing @kbd{Q 2 ^} -should yield the interval @samp{[1..2]} again, but in fact it yields the -(slightly too small) interval @samp{[1..1.9999999]} due to roundoff -error. - -@node Incomplete Objects, Variables, Interval Forms, Data Types -@section Incomplete Objects - -@noindent -@ignore -@mindex [ ] -@end ignore -@kindex [ -@ignore -@mindex ( ) -@end ignore -@kindex ( -@kindex , -@ignore -@mindex @null -@end ignore -@kindex ] -@ignore -@mindex @null -@end ignore -@kindex ) -@cindex Incomplete vectors -@cindex Incomplete complex numbers -@cindex Incomplete interval forms -When @kbd{(} or @kbd{[} is typed to begin entering a complex number or -vector, respectively, the effect is to push an @dfn{incomplete} complex -number or vector onto the stack. The @kbd{,} key adds the value(s) at -the top of the stack onto the current incomplete object. The @kbd{)} -and @kbd{]} keys ``close'' the incomplete object after adding any values -on the top of the stack in front of the incomplete object. - -As a result, the sequence of keystrokes @kbd{[ 2 , 3 @key{RET} 2 * , 9 ]} -pushes the vector @samp{[2, 6, 9]} onto the stack. Likewise, @kbd{( 1 , 2 Q )} -pushes the complex number @samp{(1, 1.414)} (approximately). - -If several values lie on the stack in front of the incomplete object, -all are collected and appended to the object. Thus the @kbd{,} key -is redundant: @kbd{[ 2 @key{RET} 3 @key{RET} 2 * 9 ]}. Some people -prefer the equivalent @key{SPC} key to @key{RET}. - -As a special case, typing @kbd{,} immediately after @kbd{(}, @kbd{[}, or -@kbd{,} adds a zero or duplicates the preceding value in the list being -formed. Typing @key{DEL} during incomplete entry removes the last item -from the list. - -@kindex ; -The @kbd{;} key is used in the same way as @kbd{,} to create polar complex -numbers: @kbd{( 1 ; 2 )}. When entering a vector, @kbd{;} is useful for -creating a matrix. In particular, @kbd{[ [ 1 , 2 ; 3 , 4 ; 5 , 6 ] ]} is -equivalent to @kbd{[ [ 1 , 2 ] , [ 3 , 4 ] , [ 5 , 6 ] ]}. - -@kindex .. -@pindex calc-dots -Incomplete entry is also used to enter intervals. For example, -@kbd{[ 2 ..@: 4 )} enters a semi-open interval. Note that when you type -the first period, it will be interpreted as a decimal point, but when -you type a second period immediately afterward, it is re-interpreted as -part of the interval symbol. Typing @kbd{..} corresponds to executing -the @code{calc-dots} command. - -If you find incomplete entry distracting, you may wish to enter vectors -and complex numbers as algebraic formulas by pressing the apostrophe key. - -@node Variables, Formulas, Incomplete Objects, Data Types -@section Variables - -@noindent -@cindex Variables, in formulas -A @dfn{variable} is somewhere between a storage register on a conventional -calculator, and a variable in a programming language. (In fact, a Calc -variable is really just an Emacs Lisp variable that contains a Calc number -or formula.) A variable's name is normally composed of letters and digits. -Calc also allows apostrophes and @code{#} signs in variable names. -(The Calc variable @code{foo} corresponds to the Emacs Lisp variable -@code{var-foo}, but unless you access the variable from within Emacs -Lisp, you don't need to worry about it. Variable names in algebraic -formulas implicitly have @samp{var-} prefixed to their names. The -@samp{#} character in variable names used in algebraic formulas -corresponds to a dash @samp{-} in the Lisp variable name. If the name -contains any dashes, the prefix @samp{var-} is @emph{not} automatically -added. Thus the two formulas @samp{foo + 1} and @samp{var#foo + 1} both -refer to the same variable.) - -In a command that takes a variable name, you can either type the full -name of a variable, or type a single digit to use one of the special -convenience variables @code{q0} through @code{q9}. For example, -@kbd{3 s s 2} stores the number 3 in variable @code{q2}, and -@w{@kbd{3 s s foo @key{RET}}} stores that number in variable -@code{foo}. - -To push a variable itself (as opposed to the variable's value) on the -stack, enter its name as an algebraic expression using the apostrophe -(@key{'}) key. - -@kindex = -@pindex calc-evaluate -@cindex Evaluation of variables in a formula -@cindex Variables, evaluation -@cindex Formulas, evaluation -The @kbd{=} (@code{calc-evaluate}) key ``evaluates'' a formula by -replacing all variables in the formula which have been given values by a -@code{calc-store} or @code{calc-let} command by their stored values. -Other variables are left alone. Thus a variable that has not been -stored acts like an abstract variable in algebra; a variable that has -been stored acts more like a register in a traditional calculator. -With a positive numeric prefix argument, @kbd{=} evaluates the top -@var{n} stack entries; with a negative argument, @kbd{=} evaluates -the @var{n}th stack entry. - -@cindex @code{e} variable -@cindex @code{pi} variable -@cindex @code{i} variable -@cindex @code{phi} variable -@cindex @code{gamma} variable -@vindex e -@vindex pi -@vindex i -@vindex phi -@vindex gamma -A few variables are called @dfn{special constants}. Their names are -@samp{e}, @samp{pi}, @samp{i}, @samp{phi}, and @samp{gamma}. -(@xref{Scientific Functions}.) When they are evaluated with @kbd{=}, -their values are calculated if necessary according to the current precision -or complex polar mode. If you wish to use these symbols for other purposes, -simply undefine or redefine them using @code{calc-store}. - -The variables @samp{inf}, @samp{uinf}, and @samp{nan} stand for -infinite or indeterminate values. It's best not to use them as -regular variables, since Calc uses special algebraic rules when -it manipulates them. Calc displays a warning message if you store -a value into any of these special variables. - -@xref{Store and Recall}, for a discussion of commands dealing with variables. - -@node Formulas, , Variables, Data Types -@section Formulas - -@noindent -@cindex Formulas -@cindex Expressions -@cindex Operators in formulas -@cindex Precedence of operators -When you press the apostrophe key you may enter any expression or formula -in algebraic form. (Calc uses the terms ``expression'' and ``formula'' -interchangeably.) An expression is built up of numbers, variable names, -and function calls, combined with various arithmetic operators. -Parentheses may -be used to indicate grouping. Spaces are ignored within formulas, except -that spaces are not permitted within variable names or numbers. -Arithmetic operators, in order from highest to lowest precedence, and -with their equivalent function names, are: - -@samp{_} [@code{subscr}] (subscripts); - -postfix @samp{%} [@code{percent}] (as in @samp{25% = 0.25}); - -prefix @samp{!} [@code{lnot}] (logical ``not,'' as in @samp{!x}); - -@samp{+/-} [@code{sdev}] (the standard deviation symbol) and -@samp{mod} [@code{makemod}] (the symbol for modulo forms); - -postfix @samp{!} [@code{fact}] (factorial, as in @samp{n!}) -and postfix @samp{!!} [@code{dfact}] (double factorial); - -@samp{^} [@code{pow}] (raised-to-the-power-of); - -prefix @samp{+} and @samp{-} [@code{neg}] (as in @samp{-x}); - -@samp{*} [@code{mul}]; - -@samp{/} [@code{div}], @samp{%} [@code{mod}] (modulo), and -@samp{\} [@code{idiv}] (integer division); - -infix @samp{+} [@code{add}] and @samp{-} [@code{sub}] (as in @samp{x-y}); - -@samp{|} [@code{vconcat}] (vector concatenation); - -relations @samp{=} [@code{eq}], @samp{!=} [@code{neq}], @samp{<} [@code{lt}], -@samp{>} [@code{gt}], @samp{<=} [@code{leq}], and @samp{>=} [@code{geq}]; - -@samp{&&} [@code{land}] (logical ``and''); - -@samp{||} [@code{lor}] (logical ``or''); - -the C-style ``if'' operator @samp{a?b:c} [@code{if}]; - -@samp{!!!} [@code{pnot}] (rewrite pattern ``not''); - -@samp{&&&} [@code{pand}] (rewrite pattern ``and''); - -@samp{|||} [@code{por}] (rewrite pattern ``or''); - -@samp{:=} [@code{assign}] (for assignments and rewrite rules); - -@samp{::} [@code{condition}] (rewrite pattern condition); - -@samp{=>} [@code{evalto}]. - -Note that, unlike in usual computer notation, multiplication binds more -strongly than division: @samp{a*b/c*d} is equivalent to -@texline @math{a b \over c d}. -@infoline @expr{(a*b)/(c*d)}. - -@cindex Multiplication, implicit -@cindex Implicit multiplication -The multiplication sign @samp{*} may be omitted in many cases. In particular, -if the righthand side is a number, variable name, or parenthesized -expression, the @samp{*} may be omitted. Implicit multiplication has the -same precedence as the explicit @samp{*} operator. The one exception to -the rule is that a variable name followed by a parenthesized expression, -as in @samp{f(x)}, -is interpreted as a function call, not an implicit @samp{*}. In many -cases you must use a space if you omit the @samp{*}: @samp{2a} is the -same as @samp{2*a}, and @samp{a b} is the same as @samp{a*b}, but @samp{ab} -is a variable called @code{ab}, @emph{not} the product of @samp{a} and -@samp{b}! Also note that @samp{f (x)} is still a function call. - -@cindex Implicit comma in vectors -The rules are slightly different for vectors written with square brackets. -In vectors, the space character is interpreted (like the comma) as a -separator of elements of the vector. Thus @w{@samp{[ 2a b+c d ]}} is -equivalent to @samp{[2*a, b+c, d]}, whereas @samp{2a b+c d} is equivalent -to @samp{2*a*b + c*d}. -Note that spaces around the brackets, and around explicit commas, are -ignored. To force spaces to be interpreted as multiplication you can -enclose a formula in parentheses as in @samp{[(a b) 2(c d)]}, which is -interpreted as @samp{[a*b, 2*c*d]}. An implicit comma is also inserted -between @samp{][}, as in the matrix @samp{[[1 2][3 4]]}. - -Vectors that contain commas (not embedded within nested parentheses or -brackets) do not treat spaces specially: @samp{[a b, 2 c d]} is a vector -of two elements. Also, if it would be an error to treat spaces as -separators, but not otherwise, then Calc will ignore spaces: -@w{@samp{[a - b]}} is a vector of one element, but @w{@samp{[a -b]}} is -a vector of two elements. Finally, vectors entered with curly braces -instead of square brackets do not give spaces any special treatment. -When Calc displays a vector that does not contain any commas, it will -insert parentheses if necessary to make the meaning clear: -@w{@samp{[(a b)]}}. - -The expression @samp{5%-2} is ambiguous; is this five-percent minus two, -or five modulo minus-two? Calc always interprets the leftmost symbol as -an infix operator preferentially (modulo, in this case), so you would -need to write @samp{(5%)-2} to get the former interpretation. - -@cindex Function call notation -A function call is, e.g., @samp{sin(1+x)}. (The Calc algebraic function -@code{foo} corresponds to the Emacs Lisp function @code{calcFunc-foo}, -but unless you access the function from within Emacs Lisp, you don't -need to worry about it.) Most mathematical Calculator commands like -@code{calc-sin} have function equivalents like @code{sin}. -If no Lisp function is defined for a function called by a formula, the -call is left as it is during algebraic manipulation: @samp{f(x+y)} is -left alone. Beware that many innocent-looking short names like @code{in} -and @code{re} have predefined meanings which could surprise you; however, -single letters or single letters followed by digits are always safe to -use for your own function names. @xref{Function Index}. - -In the documentation for particular commands, the notation @kbd{H S} -(@code{calc-sinh}) [@code{sinh}] means that the key sequence @kbd{H S}, the -command @kbd{M-x calc-sinh}, and the algebraic function @code{sinh(x)} all -represent the same operation. - -Commands that interpret (``parse'') text as algebraic formulas include -algebraic entry (@kbd{'}), editing commands like @kbd{`} which parse -the contents of the editing buffer when you finish, the @kbd{C-x * g} -and @w{@kbd{C-x * r}} commands, the @kbd{C-y} command, the X window system -``paste'' mouse operation, and Embedded mode. All of these operations -use the same rules for parsing formulas; in particular, language modes -(@pxref{Language Modes}) affect them all in the same way. - -When you read a large amount of text into the Calculator (say a vector -which represents a big set of rewrite rules; @pxref{Rewrite Rules}), -you may wish to include comments in the text. Calc's formula parser -ignores the symbol @samp{%%} and anything following it on a line: - -@example -[ a + b, %% the sum of "a" and "b" - c + d, - %% last line is coming up: - e + f ] -@end example - -@noindent -This is parsed exactly the same as @samp{[ a + b, c + d, e + f ]}. - -@xref{Syntax Tables}, for a way to create your own operators and other -input notations. @xref{Compositions}, for a way to create new display -formats. - -@xref{Algebra}, for commands for manipulating formulas symbolically. - -@node Stack and Trail, Mode Settings, Data Types, Top -@chapter Stack and Trail Commands - -@noindent -This chapter describes the Calc commands for manipulating objects on the -stack and in the trail buffer. (These commands operate on objects of any -type, such as numbers, vectors, formulas, and incomplete objects.) - -@menu -* Stack Manipulation:: -* Editing Stack Entries:: -* Trail Commands:: -* Keep Arguments:: -@end menu - -@node Stack Manipulation, Editing Stack Entries, Stack and Trail, Stack and Trail -@section Stack Manipulation Commands - -@noindent -@kindex @key{RET} -@kindex @key{SPC} -@pindex calc-enter -@cindex Duplicating stack entries -To duplicate the top object on the stack, press @key{RET} or @key{SPC} -(two equivalent keys for the @code{calc-enter} command). -Given a positive numeric prefix argument, these commands duplicate -several elements at the top of the stack. -Given a negative argument, -these commands duplicate the specified element of the stack. -Given an argument of zero, they duplicate the entire stack. -For example, with @samp{10 20 30} on the stack, -@key{RET} creates @samp{10 20 30 30}, -@kbd{C-u 2 @key{RET}} creates @samp{10 20 30 20 30}, -@kbd{C-u - 2 @key{RET}} creates @samp{10 20 30 20}, and -@kbd{C-u 0 @key{RET}} creates @samp{10 20 30 10 20 30}. - -@kindex @key{LFD} -@pindex calc-over -The @key{LFD} (@code{calc-over}) command (on a key marked Line-Feed if you -have it, else on @kbd{C-j}) is like @code{calc-enter} -except that the sign of the numeric prefix argument is interpreted -oppositely. Also, with no prefix argument the default argument is 2. -Thus with @samp{10 20 30} on the stack, @key{LFD} and @kbd{C-u 2 @key{LFD}} -are both equivalent to @kbd{C-u - 2 @key{RET}}, producing -@samp{10 20 30 20}. - -@kindex @key{DEL} -@kindex C-d -@pindex calc-pop -@cindex Removing stack entries -@cindex Deleting stack entries -To remove the top element from the stack, press @key{DEL} (@code{calc-pop}). -The @kbd{C-d} key is a synonym for @key{DEL}. -(If the top element is an incomplete object with at least one element, the -last element is removed from it.) Given a positive numeric prefix argument, -several elements are removed. Given a negative argument, the specified -element of the stack is deleted. Given an argument of zero, the entire -stack is emptied. -For example, with @samp{10 20 30} on the stack, -@key{DEL} leaves @samp{10 20}, -@kbd{C-u 2 @key{DEL}} leaves @samp{10}, -@kbd{C-u - 2 @key{DEL}} leaves @samp{10 30}, and -@kbd{C-u 0 @key{DEL}} leaves an empty stack. - -@kindex M-@key{DEL} -@pindex calc-pop-above -The @kbd{M-@key{DEL}} (@code{calc-pop-above}) command is to @key{DEL} what -@key{LFD} is to @key{RET}: It interprets the sign of the numeric -prefix argument in the opposite way, and the default argument is 2. -Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element, -leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes -the third stack element. - -The above commands do not depend on the location of the cursor. -If the customizable variable @code{calc-context-sensitive-enter} is -non-@code{nil} (@pxref{Customizing Calc}), these commands will become -context sensitive. For example, instead of duplicating the top of the stack, -@key{RET} will copy the element at the cursor to the top of the -stack. With a positive numeric prefix, a copy of the element at the -cursor and the appropriate number of preceding elements will be placed -at the top of the stack. A negative prefix will still duplicate the -specified element of the stack regardless of the cursor position. -Similarly, @key{DEL} will remove the corresponding elements from the -stack. - -@kindex @key{TAB} -@pindex calc-roll-down -To exchange the top two elements of the stack, press @key{TAB} -(@code{calc-roll-down}). Given a positive numeric prefix argument, the -specified number of elements at the top of the stack are rotated downward. -Given a negative argument, the entire stack is rotated downward the specified -number of times. Given an argument of zero, the entire stack is reversed -top-for-bottom. -For example, with @samp{10 20 30 40 50} on the stack, -@key{TAB} creates @samp{10 20 30 50 40}, -@kbd{C-u 3 @key{TAB}} creates @samp{10 20 50 30 40}, -@kbd{C-u - 2 @key{TAB}} creates @samp{40 50 10 20 30}, and -@kbd{C-u 0 @key{TAB}} creates @samp{50 40 30 20 10}. - -@kindex M-@key{TAB} -@pindex calc-roll-up -The command @kbd{M-@key{TAB}} (@code{calc-roll-up}) is analogous to @key{TAB} -except that it rotates upward instead of downward. Also, the default -with no prefix argument is to rotate the top 3 elements. -For example, with @samp{10 20 30 40 50} on the stack, -@kbd{M-@key{TAB}} creates @samp{10 20 40 50 30}, -@kbd{C-u 4 M-@key{TAB}} creates @samp{10 30 40 50 20}, -@kbd{C-u - 2 M-@key{TAB}} creates @samp{30 40 50 10 20}, and -@kbd{C-u 0 M-@key{TAB}} creates @samp{50 40 30 20 10}. - -A good way to view the operation of @key{TAB} and @kbd{M-@key{TAB}} is in -terms of moving a particular element to a new position in the stack. -With a positive argument @var{n}, @key{TAB} moves the top stack -element down to level @var{n}, making room for it by pulling all the -intervening stack elements toward the top. @kbd{M-@key{TAB}} moves the -element at level @var{n} up to the top. (Compare with @key{LFD}, -which copies instead of moving the element in level @var{n}.) - -With a negative argument @mathit{-@var{n}}, @key{TAB} rotates the stack -to move the object in level @var{n} to the deepest place in the -stack, and the object in level @mathit{@var{n}+1} to the top. @kbd{M-@key{TAB}} -rotates the deepest stack element to be in level @var{n}, also -putting the top stack element in level @mathit{@var{n}+1}. - -@xref{Selecting Subformulas}, for a way to apply these commands to -any portion of a vector or formula on the stack. - -@kindex C-xC-t -@pindex calc-transpose-lines -@cindex Moving stack entries -The command @kbd{C-x C-t} (@code{calc-transpose-lines}) will transpose -the stack object determined by the point with the stack object at the -next higher level. For example, with @samp{10 20 30 40 50} on the -stack and the point on the line containing @samp{30}, @kbd{C-x C-t} -creates @samp{10 20 40 30 50}. More generally, @kbd{C-x C-t} acts on -the stack objects determined by the current point (and mark) similar -to how the text-mode command @code{transpose-lines} acts on -lines. With argument @var{n}, @kbd{C-x C-t} will move the stack object -at the level above the current point and move it past N other objects; -for example, with @samp{10 20 30 40 50} on the stack and the point on -the line containing @samp{30}, @kbd{C-u 2 C-x C-t} creates -@samp{10 40 20 30 50}. With an argument of 0, @kbd{C-x C-t} will switch -the stack objects at the levels determined by the point and the mark. - -@node Editing Stack Entries, Trail Commands, Stack Manipulation, Stack and Trail -@section Editing Stack Entries - -@noindent -@kindex ` -@pindex calc-edit -@pindex calc-edit-finish -@cindex Editing the stack with Emacs -The @kbd{`} (@code{calc-edit}) command creates a temporary buffer -(@file{*Calc Edit*}) for editing the top-of-stack value using regular -Emacs commands. Note that @kbd{`} is a backquote, not a quote. With a -numeric prefix argument, it edits the specified number of stack entries -at once. (An argument of zero edits the entire stack; a negative -argument edits one specific stack entry.) - -When you are done editing, press @kbd{C-c C-c} to finish and return -to Calc. The @key{RET} and @key{LFD} keys also work to finish most -sorts of editing, though in some cases Calc leaves @key{RET} with its -usual meaning (``insert a newline'') if it's a situation where you -might want to insert new lines into the editing buffer. - -When you finish editing, the Calculator parses the lines of text in -the @file{*Calc Edit*} buffer as numbers or formulas, replaces the -original stack elements in the original buffer with these new values, -then kills the @file{*Calc Edit*} buffer. The original Calculator buffer -continues to exist during editing, but for best results you should be -careful not to change it until you have finished the edit. You can -also cancel the edit by killing the buffer with @kbd{C-x k}. - -The formula is normally reevaluated as it is put onto the stack. -For example, editing @samp{a + 2} to @samp{3 + 2} and pressing -@kbd{C-c C-c} will push 5 on the stack. If you use @key{LFD} to -finish, Calc will put the result on the stack without evaluating it. - -If you give a prefix argument to @kbd{C-c C-c}, -Calc will not kill the @file{*Calc Edit*} buffer. You can switch -back to that buffer and continue editing if you wish. However, you -should understand that if you initiated the edit with @kbd{`}, the -@kbd{C-c C-c} operation will be programmed to replace the top of the -stack with the new edited value, and it will do this even if you have -rearranged the stack in the meanwhile. This is not so much of a problem -with other editing commands, though, such as @kbd{s e} -(@code{calc-edit-variable}; @pxref{Operations on Variables}). - -If the @code{calc-edit} command involves more than one stack entry, -each line of the @file{*Calc Edit*} buffer is interpreted as a -separate formula. Otherwise, the entire buffer is interpreted as -one formula, with line breaks ignored. (You can use @kbd{C-o} or -@kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.) - -The @kbd{`} key also works during numeric or algebraic entry. The -text entered so far is moved to the @file{*Calc Edit*} buffer for -more extensive editing than is convenient in the minibuffer. - -@node Trail Commands, Keep Arguments, Editing Stack Entries, Stack and Trail -@section Trail Commands - -@noindent -@cindex Trail buffer -The commands for manipulating the Calc Trail buffer are two-key sequences -beginning with the @kbd{t} prefix. - -@kindex t d -@pindex calc-trail-display -The @kbd{t d} (@code{calc-trail-display}) command turns display of the -trail on and off. Normally the trail display is toggled on if it was off, -off if it was on. With a numeric prefix of zero, this command always -turns the trail off; with a prefix of one, it always turns the trail on. -The other trail-manipulation commands described here automatically turn -the trail on. Note that when the trail is off values are still recorded -there; they are simply not displayed. To set Emacs to turn the trail -off by default, type @kbd{t d} and then save the mode settings with -@kbd{m m} (@code{calc-save-modes}). - -@kindex t i -@pindex calc-trail-in -@kindex t o -@pindex calc-trail-out -The @kbd{t i} (@code{calc-trail-in}) and @kbd{t o} -(@code{calc-trail-out}) commands switch the cursor into and out of the -Calc Trail window. In practice they are rarely used, since the commands -shown below are a more convenient way to move around in the -trail, and they work ``by remote control'' when the cursor is still -in the Calculator window. - -@cindex Trail pointer -There is a @dfn{trail pointer} which selects some entry of the trail at -any given time. The trail pointer looks like a @samp{>} symbol right -before the selected number. The following commands operate on the -trail pointer in various ways. - -@kindex t y -@pindex calc-trail-yank -@cindex Retrieving previous results -The @kbd{t y} (@code{calc-trail-yank}) command reads the selected value in -the trail and pushes it onto the Calculator stack. It allows you to -re-use any previously computed value without retyping. With a numeric -prefix argument @var{n}, it yanks the value @var{n} lines above the current -trail pointer. - -@kindex t < -@pindex calc-trail-scroll-left -@kindex t > -@pindex calc-trail-scroll-right -The @kbd{t <} (@code{calc-trail-scroll-left}) and @kbd{t >} -(@code{calc-trail-scroll-right}) commands horizontally scroll the trail -window left or right by one half of its width. - -@kindex t n -@pindex calc-trail-next -@kindex t p -@pindex calc-trail-previous -@kindex t f -@pindex calc-trail-forward -@kindex t b -@pindex calc-trail-backward -The @kbd{t n} (@code{calc-trail-next}) and @kbd{t p} -(@code{calc-trail-previous)} commands move the trail pointer down or up -one line. The @kbd{t f} (@code{calc-trail-forward}) and @kbd{t b} -(@code{calc-trail-backward}) commands move the trail pointer down or up -one screenful at a time. All of these commands accept numeric prefix -arguments to move several lines or screenfuls at a time. - -@kindex t [ -@pindex calc-trail-first -@kindex t ] -@pindex calc-trail-last -@kindex t h -@pindex calc-trail-here -The @kbd{t [} (@code{calc-trail-first}) and @kbd{t ]} -(@code{calc-trail-last}) commands move the trail pointer to the first or -last line of the trail. The @kbd{t h} (@code{calc-trail-here}) command -moves the trail pointer to the cursor position; unlike the other trail -commands, @kbd{t h} works only when Calc Trail is the selected window. - -@kindex t s -@pindex calc-trail-isearch-forward -@kindex t r -@pindex calc-trail-isearch-backward -@ifnottex -The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} -(@code{calc-trail-isearch-backward}) commands perform an incremental -search forward or backward through the trail. You can press @key{RET} -to terminate the search; the trail pointer moves to the current line. -If you cancel the search with @kbd{C-g}, the trail pointer stays where -it was when the search began. -@end ifnottex -@tex -The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} -(@code{calc-trail-isearch-backward}) com\-mands perform an incremental -search forward or backward through the trail. You can press @key{RET} -to terminate the search; the trail pointer moves to the current line. -If you cancel the search with @kbd{C-g}, the trail pointer stays where -it was when the search began. -@end tex - -@kindex t m -@pindex calc-trail-marker -The @kbd{t m} (@code{calc-trail-marker}) command allows you to enter a -line of text of your own choosing into the trail. The text is inserted -after the line containing the trail pointer; this usually means it is -added to the end of the trail. Trail markers are useful mainly as the -targets for later incremental searches in the trail. - -@kindex t k -@pindex calc-trail-kill -The @kbd{t k} (@code{calc-trail-kill}) command removes the selected line -from the trail. The line is saved in the Emacs kill ring suitable for -yanking into another buffer, but it is not easy to yank the text back -into the trail buffer. With a numeric prefix argument, this command -kills the @var{n} lines below or above the selected one. - -The @kbd{t .} (@code{calc-full-trail-vectors}) command is described -elsewhere; @pxref{Vector and Matrix Formats}. - -@node Keep Arguments, , Trail Commands, Stack and Trail -@section Keep Arguments - -@noindent -@kindex K -@pindex calc-keep-args -The @kbd{K} (@code{calc-keep-args}) command acts like a prefix for -the following command. It prevents that command from removing its -arguments from the stack. For example, after @kbd{2 @key{RET} 3 +}, -the stack contains the sole number 5, but after @kbd{2 @key{RET} 3 K +}, -the stack contains the arguments and the result: @samp{2 3 5}. - -With the exception of keyboard macros, this works for all commands that -take arguments off the stack. (To avoid potentially unpleasant behavior, -a @kbd{K} prefix before a keyboard macro will be ignored. A @kbd{K} -prefix called @emph{within} the keyboard macro will still take effect.) -As another example, @kbd{K a s} simplifies a formula, pushing the -simplified version of the formula onto the stack after the original -formula (rather than replacing the original formula). Note that you -could get the same effect by typing @kbd{@key{RET} a s}, copying the -formula and then simplifying the copy. One difference is that for a very -large formula the time taken to format the intermediate copy in -@kbd{@key{RET} a s} could be noticeable; @kbd{K a s} would avoid this -extra work. - -Even stack manipulation commands are affected. @key{TAB} works by -popping two values and pushing them back in the opposite order, -so @kbd{2 @key{RET} 3 K @key{TAB}} produces @samp{2 3 3 2}. - -A few Calc commands provide other ways of doing the same thing. -For example, @kbd{' sin($)} replaces the number on the stack with -its sine using algebraic entry; to push the sine and keep the -original argument you could use either @kbd{' sin($1)} or -@kbd{K ' sin($)}. @xref{Algebraic Entry}. Also, the @kbd{s s} -command is effectively the same as @kbd{K s t}. @xref{Storing Variables}. - -If you execute a command and then decide you really wanted to keep -the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}). -This command pushes the last arguments that were popped by any command -onto the stack. Note that the order of things on the stack will be -different than with @kbd{K}: @kbd{2 @key{RET} 3 + M-@key{RET}} leaves -@samp{5 2 3} on the stack instead of @samp{2 3 5}. @xref{Undo}. - -@node Mode Settings, Arithmetic, Stack and Trail, Top -@chapter Mode Settings - -@noindent -This chapter describes commands that set modes in the Calculator. -They do not affect the contents of the stack, although they may change -the @emph{appearance} or @emph{interpretation} of the stack's contents. - -@menu -* General Mode Commands:: -* Precision:: -* Inverse and Hyperbolic:: -* Calculation Modes:: -* Simplification Modes:: -* Declarations:: -* Display Modes:: -* Language Modes:: -* Modes Variable:: -* Calc Mode Line:: -@end menu - -@node General Mode Commands, Precision, Mode Settings, Mode Settings -@section General Mode Commands - -@noindent -@kindex m m -@pindex calc-save-modes -@cindex Continuous memory -@cindex Saving mode settings -@cindex Permanent mode settings -@cindex Calc init file, mode settings -You can save all of the current mode settings in your Calc init file -(the file given by the variable @code{calc-settings-file}, typically -@file{~/.emacs.d/calc.el}) with the @kbd{m m} (@code{calc-save-modes}) -command. This will cause Emacs to reestablish these modes each time -it starts up. The modes saved in the file include everything -controlled by the @kbd{m} and @kbd{d} prefix keys, the current -precision and binary word size, whether or not the trail is displayed, -the current height of the Calc window, and more. The current -interface (used when you type @kbd{C-x * *}) is also saved. If there -were already saved mode settings in the file, they are replaced. -Otherwise, the new mode information is appended to the end of the -file. - -@kindex m R -@pindex calc-mode-record-mode -The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to -record all the mode settings (as if by pressing @kbd{m m}) every -time a mode setting changes. If the modes are saved this way, then this -``automatic mode recording'' mode is also saved. -Type @kbd{m R} again to disable this method of recording the mode -settings. To turn it off permanently, the @kbd{m m} command will also be -necessary. (If Embedded mode is enabled, other options for recording -the modes are available; @pxref{Mode Settings in Embedded Mode}.) - -@kindex m F -@pindex calc-settings-file-name -The @kbd{m F} (@code{calc-settings-file-name}) command allows you to -choose a different file than the current value of @code{calc-settings-file} -for @kbd{m m}, @kbd{Z P}, and similar commands to save permanent information. -You are prompted for a file name. All Calc modes are then reset to -their default values, then settings from the file you named are loaded -if this file exists, and this file becomes the one that Calc will -use in the future for commands like @kbd{m m}. The default settings -file name is @file{~/.emacs.d/calc.el}. You can see the current file name by -giving a blank response to the @kbd{m F} prompt. See also the -discussion of the @code{calc-settings-file} variable; @pxref{Customizing Calc}. - -If the file name you give is your user init file (typically -@file{~/.emacs}), @kbd{m F} will not automatically load the new file. This -is because your user init file may contain other things you don't want -to reread. You can give -a numeric prefix argument of 1 to @kbd{m F} to force it to read the -file no matter what. Conversely, an argument of @mathit{-1} tells -@kbd{m F} @emph{not} to read the new file. An argument of 2 or @mathit{-2} -tells @kbd{m F} not to reset the modes to their defaults beforehand, -which is useful if you intend your new file to have a variant of the -modes present in the file you were using before. - -@kindex m x -@pindex calc-always-load-extensions -The @kbd{m x} (@code{calc-always-load-extensions}) command enables a mode -in which the first use of Calc loads the entire program, including all -extensions modules. Otherwise, the extensions modules will not be loaded -until the various advanced Calc features are used. Since this mode only -has effect when Calc is first loaded, @kbd{m x} is usually followed by -@kbd{m m} to make the mode-setting permanent. To load all of Calc just -once, rather than always in the future, you can press @kbd{C-x * L}. - -@kindex m S -@pindex calc-shift-prefix -The @kbd{m S} (@code{calc-shift-prefix}) command enables a mode in which -all of Calc's letter prefix keys may be typed shifted as well as unshifted. -If you are typing, say, @kbd{a S} (@code{calc-solve-for}) quite often -you might find it easier to turn this mode on so that you can type -@kbd{A S} instead. When this mode is enabled, the commands that used to -be on those single shifted letters (e.g., @kbd{A} (@code{calc-abs})) can -now be invoked by pressing the shifted letter twice: @kbd{A A}. Note -that the @kbd{v} prefix key always works both shifted and unshifted, and -the @kbd{z} and @kbd{Z} prefix keys are always distinct. Also, the @kbd{h} -prefix is not affected by this mode. Press @kbd{m S} again to disable -shifted-prefix mode. - -@node Precision, Inverse and Hyperbolic, General Mode Commands, Mode Settings -@section Precision - -@noindent -@kindex p -@pindex calc-precision -@cindex Precision of calculations -The @kbd{p} (@code{calc-precision}) command controls the precision to -which floating-point calculations are carried. The precision must be -at least 3 digits and may be arbitrarily high, within the limits of -memory and time. This affects only floats: Integer and rational -calculations are always carried out with as many digits as necessary. - -The @kbd{p} key prompts for the current precision. If you wish you -can instead give the precision as a numeric prefix argument. - -Many internal calculations are carried to one or two digits higher -precision than normal. Results are rounded down afterward to the -current precision. Unless a special display mode has been selected, -floats are always displayed with their full stored precision, i.e., -what you see is what you get. Reducing the current precision does not -round values already on the stack, but those values will be rounded -down before being used in any calculation. The @kbd{c 0} through -@kbd{c 9} commands (@pxref{Conversions}) can be used to round an -existing value to a new precision. - -@cindex Accuracy of calculations -It is important to distinguish the concepts of @dfn{precision} and -@dfn{accuracy}. In the normal usage of these words, the number -123.4567 has a precision of 7 digits but an accuracy of 4 digits. -The precision is the total number of digits not counting leading -or trailing zeros (regardless of the position of the decimal point). -The accuracy is simply the number of digits after the decimal point -(again not counting trailing zeros). In Calc you control the precision, -not the accuracy of computations. If you were to set the accuracy -instead, then calculations like @samp{exp(100)} would generate many -more digits than you would typically need, while @samp{exp(-100)} would -probably round to zero! In Calc, both these computations give you -exactly 12 (or the requested number of) significant digits. - -The only Calc features that deal with accuracy instead of precision -are fixed-point display mode for floats (@kbd{d f}; @pxref{Float Formats}), -and the rounding functions like @code{floor} and @code{round} -(@pxref{Integer Truncation}). Also, @kbd{c 0} through @kbd{c 9} -deal with both precision and accuracy depending on the magnitudes -of the numbers involved. - -If you need to work with a particular fixed accuracy (say, dollars and -cents with two digits after the decimal point), one solution is to work -with integers and an ``implied'' decimal point. For example, $8.99 -divided by 6 would be entered @kbd{899 @key{RET} 6 /}, yielding 149.833 -(actually $1.49833 with our implied decimal point); pressing @kbd{R} -would round this to 150 cents, i.e., $1.50. - -@xref{Floats}, for still more on floating-point precision and related -issues. - -@node Inverse and Hyperbolic, Calculation Modes, Precision, Mode Settings -@section Inverse and Hyperbolic Flags - -@noindent -@kindex I -@pindex calc-inverse -There is no single-key equivalent to the @code{calc-arcsin} function. -Instead, you must first press @kbd{I} (@code{calc-inverse}) to set -the @dfn{Inverse Flag}, then press @kbd{S} (@code{calc-sin}). -The @kbd{I} key actually toggles the Inverse Flag. When this flag -is set, the word @samp{Inv} appears in the mode line. - -@kindex H -@pindex calc-hyperbolic -Likewise, the @kbd{H} key (@code{calc-hyperbolic}) sets or clears the -Hyperbolic Flag, which transforms @code{calc-sin} into @code{calc-sinh}. -If both of these flags are set at once, the effect will be -@code{calc-arcsinh}. (The Hyperbolic flag is also used by some -non-trigonometric commands; for example @kbd{H L} computes a base-10, -instead of base-@mathit{e}, logarithm.) - -Command names like @code{calc-arcsin} are provided for completeness, and -may be executed with @kbd{x} or @kbd{M-x}. Their effect is simply to -toggle the Inverse and/or Hyperbolic flags and then execute the -corresponding base command (@code{calc-sin} in this case). - -@kindex O -@pindex calc-option -The @kbd{O} key (@code{calc-option}) sets another flag, the -@dfn{Option Flag}, which also can alter the subsequent Calc command in -various ways. - -The Inverse, Hyperbolic and Option flags apply only to the next -Calculator command, after which they are automatically cleared. (They -are also cleared if the next keystroke is not a Calc command.) Digits -you type after @kbd{I}, @kbd{H} or @kbd{O} (or @kbd{K}) are treated as -prefix arguments for the next command, not as numeric entries. The -same is true of @kbd{C-u}, but not of the minus sign (@kbd{K -} means -to subtract and keep arguments). - -Another Calc prefix flag, @kbd{K} (keep-arguments), is discussed -elsewhere. @xref{Keep Arguments}. - -@node Calculation Modes, Simplification Modes, Inverse and Hyperbolic, Mode Settings -@section Calculation Modes - -@noindent -The commands in this section are two-key sequences beginning with -the @kbd{m} prefix. (That's the letter @kbd{m}, not the @key{META} key.) -The @samp{m a} (@code{calc-algebraic-mode}) command is described elsewhere -(@pxref{Algebraic Entry}). - -@menu -* Angular Modes:: -* Polar Mode:: -* Fraction Mode:: -* Infinite Mode:: -* Symbolic Mode:: -* Matrix Mode:: -* Automatic Recomputation:: -* Working Message:: -@end menu - -@node Angular Modes, Polar Mode, Calculation Modes, Calculation Modes -@subsection Angular Modes - -@noindent -@cindex Angular mode -The Calculator supports three notations for angles: radians, degrees, -and degrees-minutes-seconds. When a number is presented to a function -like @code{sin} that requires an angle, the current angular mode is -used to interpret the number as either radians or degrees. If an HMS -form is presented to @code{sin}, it is always interpreted as -degrees-minutes-seconds. - -Functions that compute angles produce a number in radians, a number in -degrees, or an HMS form depending on the current angular mode. If the -result is a complex number and the current mode is HMS, the number is -instead expressed in degrees. (Complex-number calculations would -normally be done in Radians mode, though. Complex numbers are converted -to degrees by calculating the complex result in radians and then -multiplying by 180 over @cpi{}.) - -@kindex m r -@pindex calc-radians-mode -@kindex m d -@pindex calc-degrees-mode -@kindex m h -@pindex calc-hms-mode -The @kbd{m r} (@code{calc-radians-mode}), @kbd{m d} (@code{calc-degrees-mode}), -and @kbd{m h} (@code{calc-hms-mode}) commands control the angular mode. -The current angular mode is displayed on the Emacs mode line. -The default angular mode is Degrees. - -@node Polar Mode, Fraction Mode, Angular Modes, Calculation Modes -@subsection Polar Mode - -@noindent -@cindex Polar mode -The Calculator normally ``prefers'' rectangular complex numbers in the -sense that rectangular form is used when the proper form can not be -decided from the input. This might happen by multiplying a rectangular -number by a polar one, by taking the square root of a negative real -number, or by entering @kbd{( 2 @key{SPC} 3 )}. - -@kindex m p -@pindex calc-polar-mode -The @kbd{m p} (@code{calc-polar-mode}) command toggles complex-number -preference between rectangular and polar forms. In Polar mode, all -of the above example situations would produce polar complex numbers. - -@node Fraction Mode, Infinite Mode, Polar Mode, Calculation Modes -@subsection Fraction Mode - -@noindent -@cindex Fraction mode -@cindex Division of integers -Division of two integers normally yields a floating-point number if the -result cannot be expressed as an integer. In some cases you would -rather get an exact fractional answer. One way to accomplish this is -to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which -divides the two integers on the top of the stack to produce a fraction: -@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though -@kbd{6 @key{RET} 4 /} produces @expr{1.5}. - -@kindex m f -@pindex calc-frac-mode -To set the Calculator to produce fractional results for normal integer -divisions, use the @kbd{m f} (@code{calc-frac-mode}) command. -For example, @expr{8/4} produces @expr{2} in either mode, -but @expr{6/4} produces @expr{3:2} in Fraction mode, @expr{1.5} in -Float mode. - -At any time you can use @kbd{c f} (@code{calc-float}) to convert a -fraction to a float, or @kbd{c F} (@code{calc-fraction}) to convert a -float to a fraction. @xref{Conversions}. - -@node Infinite Mode, Symbolic Mode, Fraction Mode, Calculation Modes -@subsection Infinite Mode - -@noindent -@cindex Infinite mode -The Calculator normally treats results like @expr{1 / 0} as errors; -formulas like this are left in unsimplified form. But Calc can be -put into a mode where such calculations instead produce ``infinite'' -results. - -@kindex m i -@pindex calc-infinite-mode -The @kbd{m i} (@code{calc-infinite-mode}) command turns this mode -on and off. When the mode is off, infinities do not arise except -in calculations that already had infinities as inputs. (One exception -is that infinite open intervals like @samp{[0 .. inf)} can be -generated; however, intervals closed at infinity (@samp{[0 .. inf]}) -will not be generated when Infinite mode is off.) - -With Infinite mode turned on, @samp{1 / 0} will generate @code{uinf}, -an undirected infinity. @xref{Infinities}, for a discussion of the -difference between @code{inf} and @code{uinf}. Also, @expr{0 / 0} -evaluates to @code{nan}, the ``indeterminate'' symbol. Various other -functions can also return infinities in this mode; for example, -@samp{ln(0) = -inf}, and @samp{gamma(-7) = uinf}. Once again, -note that @samp{exp(inf) = inf} regardless of Infinite mode because -this calculation has infinity as an input. - -@cindex Positive Infinite mode -The @kbd{m i} command with a numeric prefix argument of zero, -i.e., @kbd{C-u 0 m i}, turns on a Positive Infinite mode in -which zero is treated as positive instead of being directionless. -Thus, @samp{1 / 0 = inf} and @samp{-1 / 0 = -inf} in this mode. -Note that zero never actually has a sign in Calc; there are no -separate representations for @mathit{+0} and @mathit{-0}. Positive -Infinite mode merely changes the interpretation given to the -single symbol, @samp{0}. One consequence of this is that, while -you might expect @samp{1 / -0 = -inf}, actually @samp{1 / -0} -is equivalent to @samp{1 / 0}, which is equal to positive @code{inf}. - -@node Symbolic Mode, Matrix Mode, Infinite Mode, Calculation Modes -@subsection Symbolic Mode - -@noindent -@cindex Symbolic mode -@cindex Inexact results -Calculations are normally performed numerically wherever possible. -For example, the @code{calc-sqrt} command, or @code{sqrt} function in an -algebraic expression, produces a numeric answer if the argument is a -number or a symbolic expression if the argument is an expression: -@kbd{2 Q} pushes 1.4142 but @kbd{@key{'} x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}. - -@kindex m s -@pindex calc-symbolic-mode -In @dfn{Symbolic mode}, controlled by the @kbd{m s} (@code{calc-symbolic-mode}) -command, functions which would produce inexact, irrational results are -left in symbolic form. Thus @kbd{16 Q} pushes 4, but @kbd{2 Q} pushes -@samp{sqrt(2)}. - -@kindex N -@pindex calc-eval-num -The shift-@kbd{N} (@code{calc-eval-num}) command evaluates numerically -the expression at the top of the stack, by temporarily disabling -@code{calc-symbolic-mode} and executing @kbd{=} (@code{calc-evaluate}). -Given a numeric prefix argument, it also -sets the floating-point precision to the specified value for the duration -of the command. - -To evaluate a formula numerically without expanding the variables it -contains, you can use the key sequence @kbd{m s a v m s} (this uses -@code{calc-alg-evaluate}, which resimplifies but doesn't evaluate -variables.) - -@node Matrix Mode, Automatic Recomputation, Symbolic Mode, Calculation Modes -@subsection Matrix and Scalar Modes - -@noindent -@cindex Matrix mode -@cindex Scalar mode -Calc sometimes makes assumptions during algebraic manipulation that -are awkward or incorrect when vectors and matrices are involved. -Calc has two modes, @dfn{Matrix mode} and @dfn{Scalar mode}, which -modify its behavior around vectors in useful ways. - -@kindex m v -@pindex calc-matrix-mode -Press @kbd{m v} (@code{calc-matrix-mode}) once to enter Matrix mode. -In this mode, all objects are assumed to be matrices unless provably -otherwise. One major effect is that Calc will no longer consider -multiplication to be commutative. (Recall that in matrix arithmetic, -@samp{A*B} is not the same as @samp{B*A}.) This assumption affects -rewrite rules and algebraic simplification. Another effect of this -mode is that calculations that would normally produce constants like -0 and 1 (e.g., @expr{a - a} and @expr{a / a}, respectively) will now -produce function calls that represent ``generic'' zero or identity -matrices: @samp{idn(0)}, @samp{idn(1)}. The @code{idn} function -@samp{idn(@var{a},@var{n})} returns @var{a} times an @var{n}x@var{n} -identity matrix; if @var{n} is omitted, it doesn't know what -dimension to use and so the @code{idn} call remains in symbolic -form. However, if this generic identity matrix is later combined -with a matrix whose size is known, it will be converted into -a true identity matrix of the appropriate size. On the other hand, -if it is combined with a scalar (as in @samp{idn(1) + 2}), Calc -will assume it really was a scalar after all and produce, e.g., 3. - -Press @kbd{m v} a second time to get Scalar mode. Here, objects are -assumed @emph{not} to be vectors or matrices unless provably so. -For example, normally adding a variable to a vector, as in -@samp{[x, y, z] + a}, will leave the sum in symbolic form because -as far as Calc knows, @samp{a} could represent either a number or -another 3-vector. In Scalar mode, @samp{a} is assumed to be a -non-vector, and the addition is evaluated to @samp{[x+a, y+a, z+a]}. - -Press @kbd{m v} a third time to return to the normal mode of operation. - -If you press @kbd{m v} with a numeric prefix argument @var{n}, you -get a special ``dimensioned'' Matrix mode in which matrices of -unknown size are assumed to be @var{n}x@var{n} square matrices. -Then, the function call @samp{idn(1)} will expand into an actual -matrix rather than representing a ``generic'' matrix. Simply typing -@kbd{C-u m v} will get you a square Matrix mode, in which matrices of -unknown size are assumed to be square matrices of unspecified size. - -@cindex Declaring scalar variables -Of course these modes are approximations to the true state of -affairs, which is probably that some quantities will be matrices -and others will be scalars. One solution is to ``declare'' -certain variables or functions to be scalar-valued. -@xref{Declarations}, to see how to make declarations in Calc. - -There is nothing stopping you from declaring a variable to be -scalar and then storing a matrix in it; however, if you do, the -results you get from Calc may not be valid. Suppose you let Calc -get the result @samp{[x+a, y+a, z+a]} shown above, and then stored -@samp{[1, 2, 3]} in @samp{a}. The result would not be the same as -for @samp{[x, y, z] + [1, 2, 3]}, but that's because you have broken -your earlier promise to Calc that @samp{a} would be scalar. - -Another way to mix scalars and matrices is to use selections -(@pxref{Selecting Subformulas}). Use Matrix mode when operating on -your formula normally; then, to apply Scalar mode to a certain part -of the formula without affecting the rest just select that part, -change into Scalar mode and press @kbd{=} to resimplify the part -under this mode, then change back to Matrix mode before deselecting. - -@node Automatic Recomputation, Working Message, Matrix Mode, Calculation Modes -@subsection Automatic Recomputation - -@noindent -The @dfn{evaluates-to} operator, @samp{=>}, has the special -property that any @samp{=>} formulas on the stack are recomputed -whenever variable values or mode settings that might affect them -are changed. @xref{Evaluates-To Operator}. - -@kindex m C -@pindex calc-auto-recompute -The @kbd{m C} (@code{calc-auto-recompute}) command turns this -automatic recomputation on and off. If you turn it off, Calc will -not update @samp{=>} operators on the stack (nor those in the -attached Embedded mode buffer, if there is one). They will not -be updated unless you explicitly do so by pressing @kbd{=} or until -you press @kbd{m C} to turn recomputation back on. (While automatic -recomputation is off, you can think of @kbd{m C m C} as a command -to update all @samp{=>} operators while leaving recomputation off.) - -To update @samp{=>} operators in an Embedded buffer while -automatic recomputation is off, use @w{@kbd{C-x * u}}. -@xref{Embedded Mode}. - -@node Working Message, , Automatic Recomputation, Calculation Modes -@subsection Working Messages - -@noindent -@cindex Performance -@cindex Working messages -Since the Calculator is written entirely in Emacs Lisp, which is not -designed for heavy numerical work, many operations are quite slow. -The Calculator normally displays the message @samp{Working...} in the -echo area during any command that may be slow. In addition, iterative -operations such as square roots and trigonometric functions display the -intermediate result at each step. Both of these types of messages can -be disabled if you find them distracting. - -@kindex m w -@pindex calc-working -Type @kbd{m w} (@code{calc-working}) with a numeric prefix of 0 to -disable all ``working'' messages. Use a numeric prefix of 1 to enable -only the plain @samp{Working...} message. Use a numeric prefix of 2 to -see intermediate results as well. With no numeric prefix this displays -the current mode. - -While it may seem that the ``working'' messages will slow Calc down -considerably, experiments have shown that their impact is actually -quite small. But if your terminal is slow you may find that it helps -to turn the messages off. - -@node Simplification Modes, Declarations, Calculation Modes, Mode Settings -@section Simplification Modes - -@noindent -The current @dfn{simplification mode} controls how numbers and formulas -are ``normalized'' when being taken from or pushed onto the stack. -Some normalizations are unavoidable, such as rounding floating-point -results to the current precision, and reducing fractions to simplest -form. Others, such as simplifying a formula like @expr{a+a} (or @expr{2+3}), -are done automatically but can be turned off when necessary. - -When you press a key like @kbd{+} when @expr{2} and @expr{3} are on the -stack, Calc pops these numbers, normalizes them, creates the formula -@expr{2+3}, normalizes it, and pushes the result. Of course the standard -rules for normalizing @expr{2+3} will produce the result @expr{5}. - -Simplification mode commands consist of the lower-case @kbd{m} prefix key -followed by a shifted letter. - -@kindex m O -@pindex calc-no-simplify-mode -The @kbd{m O} (@code{calc-no-simplify-mode}) command turns off all optional -simplifications. These would leave a formula like @expr{2+3} alone. In -fact, nothing except simple numbers are ever affected by normalization -in this mode. Explicit simplification commands, such as @kbd{=} or -@kbd{a s}, can still be given to simplify any formulas. -@xref{Algebraic Definitions}, for a sample use of -No-Simplification mode. - - -@kindex m N -@pindex calc-num-simplify-mode -The @kbd{m N} (@code{calc-num-simplify-mode}) command turns off simplification -of any formulas except those for which all arguments are constants. For -example, @expr{1+2} is simplified to @expr{3}, and @expr{a+(2-2)} is -simplified to @expr{a+0} but no further, since one argument of the sum -is not a constant. Unfortunately, @expr{(a+2)-2} is @emph{not} simplified -because the top-level @samp{-} operator's arguments are not both -constant numbers (one of them is the formula @expr{a+2}). -A constant is a number or other numeric object (such as a constant -error form or modulo form), or a vector all of whose -elements are constant. - -@kindex m I -@pindex calc-basic-simplify-mode -The @kbd{m I} (@code{calc-basic-simplify-mode}) command does some basic -simplifications for all formulas. This includes many easy and -fast algebraic simplifications such as @expr{a+0} to @expr{a}, and -@expr{a + 2 a} to @expr{3 a}, as well as evaluating functions like -@expr{@tfn{deriv}(x^2, x)} to @expr{2 x}. - -@kindex m B -@pindex calc-bin-simplify-mode -The @kbd{m B} (@code{calc-bin-simplify-mode}) mode applies the basic -simplifications to a result and then, if the result is an integer, -uses the @kbd{b c} (@code{calc-clip}) command to clip the integer according -to the current binary word size. @xref{Binary Functions}. Real numbers -are rounded to the nearest integer and then clipped; other kinds of -results (after the basic simplifications) are left alone. - -@kindex m A -@pindex calc-alg-simplify-mode -The @kbd{m A} (@code{calc-alg-simplify-mode}) mode does standard -algebraic simplifications. @xref{Algebraic Simplifications}. - -@kindex m E -@pindex calc-ext-simplify-mode -The @kbd{m E} (@code{calc-ext-simplify-mode}) mode does ``extended'', or -``unsafe'', algebraic simplification. @xref{Unsafe Simplifications}. - -@kindex m U -@pindex calc-units-simplify-mode -The @kbd{m U} (@code{calc-units-simplify-mode}) mode does units -simplification. @xref{Simplification of Units}. These include the -algebraic simplifications, plus variable names which -are identifiable as unit names (like @samp{mm} for ``millimeters'') -are simplified with their unit definitions in mind. - -A common technique is to set the simplification mode down to the lowest -amount of simplification you will allow to be applied automatically, then -use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to -perform higher types of simplifications on demand. -@node Declarations, Display Modes, Simplification Modes, Mode Settings -@section Declarations - -@noindent -A @dfn{declaration} is a statement you make that promises you will -use a certain variable or function in a restricted way. This may -give Calc the freedom to do things that it couldn't do if it had to -take the fully general situation into account. - -@menu -* Declaration Basics:: -* Kinds of Declarations:: -* Functions for Declarations:: -@end menu - -@node Declaration Basics, Kinds of Declarations, Declarations, Declarations -@subsection Declaration Basics - -@noindent -@kindex s d -@pindex calc-declare-variable -The @kbd{s d} (@code{calc-declare-variable}) command is the easiest -way to make a declaration for a variable. This command prompts for -the variable name, then prompts for the declaration. The default -at the declaration prompt is the previous declaration, if any. -You can edit this declaration, or press @kbd{C-k} to erase it and -type a new declaration. (Or, erase it and press @key{RET} to clear -the declaration, effectively ``undeclaring'' the variable.) - -A declaration is in general a vector of @dfn{type symbols} and -@dfn{range} values. If there is only one type symbol or range value, -you can write it directly rather than enclosing it in a vector. -For example, @kbd{s d foo @key{RET} real @key{RET}} declares @code{foo} to -be a real number, and @kbd{s d bar @key{RET} [int, const, [1..6]] @key{RET}} -declares @code{bar} to be a constant integer between 1 and 6. -(Actually, you can omit the outermost brackets and Calc will -provide them for you: @kbd{s d bar @key{RET} int, const, [1..6] @key{RET}}.) - -@cindex @code{Decls} variable -@vindex Decls -Declarations in Calc are kept in a special variable called @code{Decls}. -This variable encodes the set of all outstanding declarations in -the form of a matrix. Each row has two elements: A variable or -vector of variables declared by that row, and the declaration -specifier as described above. You can use the @kbd{s D} command to -edit this variable if you wish to see all the declarations at once. -@xref{Operations on Variables}, for a description of this command -and the @kbd{s p} command that allows you to save your declarations -permanently if you wish. - -Items being declared can also be function calls. The arguments in -the call are ignored; the effect is to say that this function returns -values of the declared type for any valid arguments. The @kbd{s d} -command declares only variables, so if you wish to make a function -declaration you will have to edit the @code{Decls} matrix yourself. - -For example, the declaration matrix - -@smallexample -@group -[ [ foo, real ] - [ [j, k, n], int ] - [ f(1,2,3), [0 .. inf) ] ] -@end group -@end smallexample - -@noindent -declares that @code{foo} represents a real number, @code{j}, @code{k} -and @code{n} represent integers, and the function @code{f} always -returns a real number in the interval shown. - -@vindex All -If there is a declaration for the variable @code{All}, then that -declaration applies to all variables that are not otherwise declared. -It does not apply to function names. For example, using the row -@samp{[All, real]} says that all your variables are real unless they -are explicitly declared without @code{real} in some other row. -The @kbd{s d} command declares @code{All} if you give a blank -response to the variable-name prompt. - -@node Kinds of Declarations, Functions for Declarations, Declaration Basics, Declarations -@subsection Kinds of Declarations - -@noindent -The type-specifier part of a declaration (that is, the second prompt -in the @kbd{s d} command) can be a type symbol, an interval, or a -vector consisting of zero or more type symbols followed by zero or -more intervals or numbers that represent the set of possible values -for the variable. - -@smallexample -@group -[ [ a, [1, 2, 3, 4, 5] ] - [ b, [1 .. 5] ] - [ c, [int, 1 .. 5] ] ] -@end group -@end smallexample - -Here @code{a} is declared to contain one of the five integers shown; -@code{b} is any number in the interval from 1 to 5 (any real number -since we haven't specified), and @code{c} is any integer in that -interval. Thus the declarations for @code{a} and @code{c} are -nearly equivalent (see below). - -The type-specifier can be the empty vector @samp{[]} to say that -nothing is known about a given variable's value. This is the same -as not declaring the variable at all except that it overrides any -@code{All} declaration which would otherwise apply. - -The initial value of @code{Decls} is the empty vector @samp{[]}. -If @code{Decls} has no stored value or if the value stored in it -is not valid, it is ignored and there are no declarations as far -as Calc is concerned. (The @kbd{s d} command will replace such a -malformed value with a fresh empty matrix, @samp{[]}, before recording -the new declaration.) Unrecognized type symbols are ignored. - -The following type symbols describe what sorts of numbers will be -stored in a variable: - -@table @code -@item int -Integers. -@item numint -Numerical integers. (Integers or integer-valued floats.) -@item frac -Fractions. (Rational numbers which are not integers.) -@item rat -Rational numbers. (Either integers or fractions.) -@item float -Floating-point numbers. -@item real -Real numbers. (Integers, fractions, or floats. Actually, -intervals and error forms with real components also count as -reals here.) -@item pos -Positive real numbers. (Strictly greater than zero.) -@item nonneg -Nonnegative real numbers. (Greater than or equal to zero.) -@item number -Numbers. (Real or complex.) -@end table - -Calc uses this information to determine when certain simplifications -of formulas are safe. For example, @samp{(x^y)^z} cannot be -simplified to @samp{x^(y z)} in general; for example, -@samp{((-3)^2)^1:2} is 3, but @samp{(-3)^(2*1:2) = (-3)^1} is @mathit{-3}. -However, this simplification @emph{is} safe if @code{z} is known -to be an integer, or if @code{x} is known to be a nonnegative -real number. If you have given declarations that allow Calc to -deduce either of these facts, Calc will perform this simplification -of the formula. - -Calc can apply a certain amount of logic when using declarations. -For example, @samp{(x^y)^(2n+1)} will be simplified if @code{n} -has been declared @code{int}; Calc knows that an integer times an -integer, plus an integer, must always be an integer. (In fact, -Calc would simplify @samp{(-x)^(2n+1)} to @samp{-(x^(2n+1))} since -it is able to determine that @samp{2n+1} must be an odd integer.) - -Similarly, @samp{(abs(x)^y)^z} will be simplified to @samp{abs(x)^(y z)} -because Calc knows that the @code{abs} function always returns a -nonnegative real. If you had a @code{myabs} function that also had -this property, you could get Calc to recognize it by adding the row -@samp{[myabs(), nonneg]} to the @code{Decls} matrix. - -One instance of this simplification is @samp{sqrt(x^2)} (since the -@code{sqrt} function is effectively a one-half power). Normally -Calc leaves this formula alone. After the command -@kbd{s d x @key{RET} real @key{RET}}, however, it can simplify the formula to -@samp{abs(x)}. And after @kbd{s d x @key{RET} nonneg @key{RET}}, Calc can -simplify this formula all the way to @samp{x}. - -If there are any intervals or real numbers in the type specifier, -they comprise the set of possible values that the variable or -function being declared can have. In particular, the type symbol -@code{real} is effectively the same as the range @samp{[-inf .. inf]} -(note that infinity is included in the range of possible values); -@code{pos} is the same as @samp{(0 .. inf]}, and @code{nonneg} is -the same as @samp{[0 .. inf]}. Saying @samp{[real, [-5 .. 5]]} is -redundant because the fact that the variable is real can be -deduced just from the interval, but @samp{[int, [-5 .. 5]]} and -@samp{[rat, [-5 .. 5]]} are useful combinations. - -Note that the vector of intervals or numbers is in the same format -used by Calc's set-manipulation commands. @xref{Set Operations}. - -The type specifier @samp{[1, 2, 3]} is equivalent to -@samp{[numint, 1, 2, 3]}, @emph{not} to @samp{[int, 1, 2, 3]}. -In other words, the range of possible values means only that -the variable's value must be numerically equal to a number in -that range, but not that it must be equal in type as well. -Calc's set operations act the same way; @samp{in(2, [1., 2., 3.])} -and @samp{in(1.5, [1:2, 3:2, 5:2])} both report ``true.'' - -If you use a conflicting combination of type specifiers, the -results are unpredictable. An example is @samp{[pos, [0 .. 5]]}, -where the interval does not lie in the range described by the -type symbol. - -``Real'' declarations mostly affect simplifications involving powers -like the one described above. Another case where they are used -is in the @kbd{a P} command which returns a list of all roots of a -polynomial; if the variable has been declared real, only the real -roots (if any) will be included in the list. - -``Integer'' declarations are used for simplifications which are valid -only when certain values are integers (such as @samp{(x^y)^z} -shown above). - -Calc's algebraic simplifications also make use of declarations when -simplifying equations and inequalities. They will cancel @code{x} -from both sides of @samp{a x = b x} only if it is sure @code{x} -is non-zero, say, because it has a @code{pos} declaration. -To declare specifically that @code{x} is real and non-zero, -use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the -current notation to say that @code{x} is nonzero but not necessarily -real.) The @kbd{a e} command does ``unsafe'' simplifications, -including canceling @samp{x} from the equation when @samp{x} is -not known to be nonzero. - -Another set of type symbols distinguish between scalars and vectors. - -@table @code -@item scalar -The value is not a vector. -@item vector -The value is a vector. -@item matrix -The value is a matrix (a rectangular vector of vectors). -@item sqmatrix -The value is a square matrix. -@end table - -These type symbols can be combined with the other type symbols -described above; @samp{[int, matrix]} describes an object which -is a matrix of integers. - -Scalar/vector declarations are used to determine whether certain -algebraic operations are safe. For example, @samp{[a, b, c] + x} -is normally not simplified to @samp{[a + x, b + x, c + x]}, but -it will be if @code{x} has been declared @code{scalar}. On the -other hand, multiplication is usually assumed to be commutative, -but the terms in @samp{x y} will never be exchanged if both @code{x} -and @code{y} are known to be vectors or matrices. (Calc currently -never distinguishes between @code{vector} and @code{matrix} -declarations.) - -@xref{Matrix Mode}, for a discussion of Matrix mode and -Scalar mode, which are similar to declaring @samp{[All, matrix]} -or @samp{[All, scalar]} but much more convenient. - -One more type symbol that is recognized is used with the @kbd{H a d} -command for taking total derivatives of a formula. @xref{Calculus}. - -@table @code -@item const -The value is a constant with respect to other variables. -@end table - -Calc does not check the declarations for a variable when you store -a value in it. However, storing @mathit{-3.5} in a variable that has -been declared @code{pos}, @code{int}, or @code{matrix} may have -unexpected effects; Calc may evaluate @samp{sqrt(x^2)} to @expr{3.5} -if it substitutes the value first, or to @expr{-3.5} if @code{x} -was declared @code{pos} and the formula @samp{sqrt(x^2)} is -simplified to @samp{x} before the value is substituted. Before -using a variable for a new purpose, it is best to use @kbd{s d} -or @kbd{s D} to check to make sure you don't still have an old -declaration for the variable that will conflict with its new meaning. - -@node Functions for Declarations, , Kinds of Declarations, Declarations -@subsection Functions for Declarations - -@noindent -Calc has a set of functions for accessing the current declarations -in a convenient manner. These functions return 1 if the argument -can be shown to have the specified property, or 0 if the argument -can be shown @emph{not} to have that property; otherwise they are -left unevaluated. These functions are suitable for use with rewrite -rules (@pxref{Conditional Rewrite Rules}) or programming constructs -(@pxref{Conditionals in Macros}). They can be entered only using -algebraic notation. @xref{Logical Operations}, for functions -that perform other tests not related to declarations. - -For example, @samp{dint(17)} returns 1 because 17 is an integer, as -do @samp{dint(n)} and @samp{dint(2 n - 3)} if @code{n} has been declared -@code{int}, but @samp{dint(2.5)} and @samp{dint(n + 0.5)} return 0. -Calc consults knowledge of its own built-in functions as well as your -own declarations: @samp{dint(floor(x))} returns 1. - -@ignore -@starindex -@end ignore -@tindex dint -@ignore -@starindex -@end ignore -@tindex dnumint -@ignore -@starindex -@end ignore -@tindex dnatnum -The @code{dint} function checks if its argument is an integer. -The @code{dnatnum} function checks if its argument is a natural -number, i.e., a nonnegative integer. The @code{dnumint} function -checks if its argument is numerically an integer, i.e., either an -integer or an integer-valued float. Note that these and the other -data type functions also accept vectors or matrices composed of -suitable elements, and that real infinities @samp{inf} and @samp{-inf} -are considered to be integers for the purposes of these functions. - -@ignore -@starindex -@end ignore -@tindex drat -The @code{drat} function checks if its argument is rational, i.e., -an integer or fraction. Infinities count as rational, but intervals -and error forms do not. - -@ignore -@starindex -@end ignore -@tindex dreal -The @code{dreal} function checks if its argument is real. This -includes integers, fractions, floats, real error forms, and intervals. - -@ignore -@starindex -@end ignore -@tindex dimag -The @code{dimag} function checks if its argument is imaginary, -i.e., is mathematically equal to a real number times @expr{i}. - -@ignore -@starindex -@end ignore -@tindex dpos -@ignore -@starindex -@end ignore -@tindex dneg -@ignore -@starindex -@end ignore -@tindex dnonneg -The @code{dpos} function checks for positive (but nonzero) reals. -The @code{dneg} function checks for negative reals. The @code{dnonneg} -function checks for nonnegative reals, i.e., reals greater than or -equal to zero. Note that Calc's algebraic simplifications, which are -effectively applied to all conditions in rewrite rules, can simplify -an expression like @expr{x > 0} to 1 or 0 using @code{dpos}. -So the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg} -are rarely necessary. - -@ignore -@starindex -@end ignore -@tindex dnonzero -The @code{dnonzero} function checks that its argument is nonzero. -This includes all nonzero real or complex numbers, all intervals that -do not include zero, all nonzero modulo forms, vectors all of whose -elements are nonzero, and variables or formulas whose values can be -deduced to be nonzero. It does not include error forms, since they -represent values which could be anything including zero. (This is -also the set of objects considered ``true'' in conditional contexts.) - -@ignore -@starindex -@end ignore -@tindex deven -@ignore -@starindex -@end ignore -@tindex dodd -The @code{deven} function returns 1 if its argument is known to be -an even integer (or integer-valued float); it returns 0 if its argument -is known not to be even (because it is known to be odd or a non-integer). -Calc's algebraic simplifications use this to simplify a test of the form -@samp{x % 2 = 0}. There is also an analogous @code{dodd} function. - -@ignore -@starindex -@end ignore -@tindex drange -The @code{drange} function returns a set (an interval or a vector -of intervals and/or numbers; @pxref{Set Operations}) that describes -the set of possible values of its argument. If the argument is -a variable or a function with a declaration, the range is copied -from the declaration. Otherwise, the possible signs of the -expression are determined using a method similar to @code{dpos}, -etc., and a suitable set like @samp{[0 .. inf]} is returned. If -the expression is not provably real, the @code{drange} function -remains unevaluated. - -@ignore -@starindex -@end ignore -@tindex dscalar -The @code{dscalar} function returns 1 if its argument is provably -scalar, or 0 if its argument is provably non-scalar. It is left -unevaluated if this cannot be determined. (If Matrix mode or Scalar -mode is in effect, this function returns 1 or 0, respectively, -if it has no other information.) When Calc interprets a condition -(say, in a rewrite rule) it considers an unevaluated formula to be -``false.'' Thus, @samp{dscalar(a)} is ``true'' only if @code{a} is -provably scalar, and @samp{!dscalar(a)} is ``true'' only if @code{a} -is provably non-scalar; both are ``false'' if there is insufficient -information to tell. - -@node Display Modes, Language Modes, Declarations, Mode Settings -@section Display Modes - -@noindent -The commands in this section are two-key sequences beginning with the -@kbd{d} prefix. The @kbd{d l} (@code{calc-line-numbering}) and @kbd{d b} -(@code{calc-line-breaking}) commands are described elsewhere; -@pxref{Stack Basics} and @pxref{Normal Language Modes}, respectively. -Display formats for vectors and matrices are also covered elsewhere; -@pxref{Vector and Matrix Formats}. - -One thing all display modes have in common is their treatment of the -@kbd{H} prefix. This prefix causes any mode command that would normally -refresh the stack to leave the stack display alone. The word ``Dirty'' -will appear in the mode line when Calc thinks the stack display may not -reflect the latest mode settings. - -@kindex d @key{RET} -@pindex calc-refresh-top -The @kbd{d @key{RET}} (@code{calc-refresh-top}) command reformats the -top stack entry according to all the current modes. Positive prefix -arguments reformat the top @var{n} entries; negative prefix arguments -reformat the specified entry, and a prefix of zero is equivalent to -@kbd{d @key{SPC}} (@code{calc-refresh}), which reformats the entire stack. -For example, @kbd{H d s M-2 d @key{RET}} changes to scientific notation -but reformats only the top two stack entries in the new mode. - -The @kbd{I} prefix has another effect on the display modes. The mode -is set only temporarily; the top stack entry is reformatted according -to that mode, then the original mode setting is restored. In other -words, @kbd{I d s} is equivalent to @kbd{H d s d @key{RET} H d (@var{old mode})}. - -@menu -* Radix Modes:: -* Grouping Digits:: -* Float Formats:: -* Complex Formats:: -* Fraction Formats:: -* HMS Formats:: -* Date Formats:: -* Truncating the Stack:: -* Justification:: -* Labels:: -@end menu - -@node Radix Modes, Grouping Digits, Display Modes, Display Modes -@subsection Radix Modes - -@noindent -@cindex Radix display -@cindex Non-decimal numbers -@cindex Decimal and non-decimal numbers -Calc normally displays numbers in decimal (@dfn{base-10} or @dfn{radix-10}) -notation. Calc can actually display in any radix from two (binary) to 36. -When the radix is above 10, the letters @code{A} to @code{Z} are used as -digits. When entering such a number, letter keys are interpreted as -potential digits rather than terminating numeric entry mode. - -@kindex d 2 -@kindex d 8 -@kindex d 6 -@kindex d 0 -@cindex Hexadecimal integers -@cindex Octal integers -The key sequences @kbd{d 2}, @kbd{d 8}, @kbd{d 6}, and @kbd{d 0} select -binary, octal, hexadecimal, and decimal as the current display radix, -respectively. Numbers can always be entered in any radix, though the -current radix is used as a default if you press @kbd{#} without any initial -digits. A number entered without a @kbd{#} is @emph{always} interpreted -as decimal. - -@kindex d r -@pindex calc-radix -To set the radix generally, use @kbd{d r} (@code{calc-radix}) and enter -an integer from 2 to 36. You can specify the radix as a numeric prefix -argument; otherwise you will be prompted for it. - -@kindex d z -@pindex calc-leading-zeros -@cindex Leading zeros -Integers normally are displayed with however many digits are necessary to -represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros}) -command causes integers to be padded out with leading zeros according to the -current binary word size. (@xref{Binary Functions}, for a discussion of -word size.) If the absolute value of the word size is @expr{w}, all integers -are displayed with at least enough digits to represent -@texline @math{2^w-1} -@infoline @expr{(2^w)-1} -in the current radix. (Larger integers will still be displayed in their -entirety.) - -@cindex Two's complements -Calc can display @expr{w}-bit integers using two's complement -notation, although this is most useful with the binary, octal and -hexadecimal display modes. This option is selected by using the -@kbd{O} option prefix before setting the display radix, and a negative word -size might be appropriate (@pxref{Binary Functions}). In two's -complement notation, the integers in the (nearly) symmetric interval -from -@texline @math{-2^{w-1}} -@infoline @expr{-2^(w-1)} -to -@texline @math{2^{w-1}-1} -@infoline @expr{2^(w-1)-1} -are represented by the integers from @expr{0} to @expr{2^w-1}: -the integers from @expr{0} to -@texline @math{2^{w-1}-1} -@infoline @expr{2^(w-1)-1} -are represented by themselves and the integers from -@texline @math{-2^{w-1}} -@infoline @expr{-2^(w-1)} -to @expr{-1} are represented by the integers from -@texline @math{2^{w-1}} -@infoline @expr{2^(w-1)} -to @expr{2^w-1} (the integer @expr{k} is represented by @expr{k+2^w}). -Calc will display a two's complement integer by the radix (either -@expr{2}, @expr{8} or @expr{16}), two @kbd{#} symbols, and then its -representation (including any leading zeros necessary to include all -@expr{w} bits). In a two's complement display mode, numbers that -are not displayed in two's complement notation (i.e., that aren't -integers from -@texline @math{-2^{w-1}} -@infoline @expr{-2^(w-1)} -to -@c ( -@texline @math{2^{w-1}-1}) -@infoline @expr{2^(w-1)-1}) -will be represented using Calc's usual notation (in the appropriate -radix). - -@node Grouping Digits, Float Formats, Radix Modes, Display Modes -@subsection Grouping Digits - -@noindent -@kindex d g -@pindex calc-group-digits -@cindex Grouping digits -@cindex Digit grouping -Long numbers can be hard to read if they have too many digits. For -example, the factorial of 30 is 33 digits long! Press @kbd{d g} -(@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits -are displayed in clumps of 3 or 4 (depending on the current radix) -separated by commas. - -The @kbd{d g} command toggles grouping on and off. -With a numeric prefix of 0, this command displays the current state of -the grouping flag; with an argument of minus one it disables grouping; -with a positive argument @expr{N} it enables grouping on every @expr{N} -digits. For floating-point numbers, grouping normally occurs only -before the decimal point. A negative prefix argument @expr{-N} enables -grouping every @expr{N} digits both before and after the decimal point. - -@kindex d , -@pindex calc-group-char -The @kbd{d ,} (@code{calc-group-char}) command allows you to choose any -character as the grouping separator. The default is the comma character. -If you find it difficult to read vectors of large integers grouped with -commas, you may wish to use spaces or some other character instead. -This command takes the next character you type, whatever it is, and -uses it as the digit separator. As a special case, @kbd{d , \} selects -@samp{\,} (@TeX{}'s thin-space symbol) as the digit separator. - -Please note that grouped numbers will not generally be parsed correctly -if re-read in textual form, say by the use of @kbd{C-x * y} and @kbd{C-x * g}. -(@xref{Kill and Yank}, for details on these commands.) One exception is -the @samp{\,} separator, which doesn't interfere with parsing because it -is ignored by @TeX{} language mode. - -@node Float Formats, Complex Formats, Grouping Digits, Display Modes -@subsection Float Formats - -@noindent -Floating-point quantities are normally displayed in standard decimal -form, with scientific notation used if the exponent is especially high -or low. All significant digits are normally displayed. The commands -in this section allow you to choose among several alternative display -formats for floats. - -@kindex d n -@pindex calc-normal-notation -The @kbd{d n} (@code{calc-normal-notation}) command selects the normal -display format. All significant figures in a number are displayed. -With a positive numeric prefix, numbers are rounded if necessary to -that number of significant digits. With a negative numerix prefix, -the specified number of significant digits less than the current -precision is used. (Thus @kbd{C-u -2 d n} displays 10 digits if the -current precision is 12.) - -@kindex d f -@pindex calc-fix-notation -The @kbd{d f} (@code{calc-fix-notation}) command selects fixed-point -notation. The numeric argument is the number of digits after the -decimal point, zero or more. This format will relax into scientific -notation if a nonzero number would otherwise have been rounded all the -way to zero. Specifying a negative number of digits is the same as -for a positive number, except that small nonzero numbers will be rounded -to zero rather than switching to scientific notation. - -@kindex d s -@pindex calc-sci-notation -@cindex Scientific notation, display of -The @kbd{d s} (@code{calc-sci-notation}) command selects scientific -notation. A positive argument sets the number of significant figures -displayed, of which one will be before and the rest after the decimal -point. A negative argument works the same as for @kbd{d n} format. -The default is to display all significant digits. - -@kindex d e -@pindex calc-eng-notation -@cindex Engineering notation, display of -The @kbd{d e} (@code{calc-eng-notation}) command selects engineering -notation. This is similar to scientific notation except that the -exponent is rounded down to a multiple of three, with from one to three -digits before the decimal point. An optional numeric prefix sets the -number of significant digits to display, as for @kbd{d s}. - -It is important to distinguish between the current @emph{precision} and -the current @emph{display format}. After the commands @kbd{C-u 10 p} -and @kbd{C-u 6 d n} the Calculator computes all results to ten -significant figures but displays only six. (In fact, intermediate -calculations are often carried to one or two more significant figures, -but values placed on the stack will be rounded down to ten figures.) -Numbers are never actually rounded to the display precision for storage, -except by commands like @kbd{C-k} and @kbd{C-x * y} which operate on the -actual displayed text in the Calculator buffer. - -@kindex d . -@pindex calc-point-char -The @kbd{d .} (@code{calc-point-char}) command selects the character used -as a decimal point. Normally this is a period; users in some countries -may wish to change this to a comma. Note that this is only a display -style; on entry, periods must always be used to denote floating-point -numbers, and commas to separate elements in a list. - -@node Complex Formats, Fraction Formats, Float Formats, Display Modes -@subsection Complex Formats - -@noindent -@kindex d c -@pindex calc-complex-notation -There are three supported notations for complex numbers in rectangular -form. The default is as a pair of real numbers enclosed in parentheses -and separated by a comma: @samp{(a,b)}. The @kbd{d c} -(@code{calc-complex-notation}) command selects this style. - -@kindex d i -@pindex calc-i-notation -@kindex d j -@pindex calc-j-notation -The other notations are @kbd{d i} (@code{calc-i-notation}), in which -numbers are displayed in @samp{a+bi} form, and @kbd{d j} -(@code{calc-j-notation}) which displays the form @samp{a+bj} preferred -in some disciplines. - -@cindex @code{i} variable -@vindex i -Complex numbers are normally entered in @samp{(a,b)} format. -If you enter @samp{2+3i} as an algebraic formula, it will be stored as -the formula @samp{2 + 3 * i}. However, if you use @kbd{=} to evaluate -this formula and you have not changed the variable @samp{i}, the @samp{i} -will be interpreted as @samp{(0,1)} and the formula will be simplified -to @samp{(2,3)}. Other commands (like @code{calc-sin}) will @emph{not} -interpret the formula @samp{2 + 3 * i} as a complex number. -@xref{Variables}, under ``special constants.'' - -@node Fraction Formats, HMS Formats, Complex Formats, Display Modes -@subsection Fraction Formats - -@noindent -@kindex d o -@pindex calc-over-notation -Display of fractional numbers is controlled by the @kbd{d o} -(@code{calc-over-notation}) command. By default, a number like -eight thirds is displayed in the form @samp{8:3}. The @kbd{d o} command -prompts for a one- or two-character format. If you give one character, -that character is used as the fraction separator. Common separators are -@samp{:} and @samp{/}. (During input of numbers, the @kbd{:} key must be -used regardless of the display format; in particular, the @kbd{/} is used -for RPN-style division, @emph{not} for entering fractions.) - -If you give two characters, fractions use ``integer-plus-fractional-part'' -notation. For example, the format @samp{+/} would display eight thirds -as @samp{2+2/3}. If two colons are present in a number being entered, -the number is interpreted in this form (so that the entries @kbd{2:2:3} -and @kbd{8:3} are equivalent). - -It is also possible to follow the one- or two-character format with -a number. For example: @samp{:10} or @samp{+/3}. In this case, -Calc adjusts all fractions that are displayed to have the specified -denominator, if possible. Otherwise it adjusts the denominator to -be a multiple of the specified value. For example, in @samp{:6} mode -the fraction @expr{1:6} will be unaffected, but @expr{2:3} will be -displayed as @expr{4:6}, @expr{1:2} will be displayed as @expr{3:6}, -and @expr{1:8} will be displayed as @expr{3:24}. Integers are also -affected by this mode: 3 is displayed as @expr{18:6}. Note that the -format @samp{:1} writes fractions the same as @samp{:}, but it writes -integers as @expr{n:1}. - -The fraction format does not affect the way fractions or integers are -stored, only the way they appear on the screen. The fraction format -never affects floats. - -@node HMS Formats, Date Formats, Fraction Formats, Display Modes -@subsection HMS Formats - -@noindent -@kindex d h -@pindex calc-hms-notation -The @kbd{d h} (@code{calc-hms-notation}) command controls the display of -HMS (hours-minutes-seconds) forms. It prompts for a string which -consists basically of an ``hours'' marker, optional punctuation, a -``minutes'' marker, more optional punctuation, and a ``seconds'' marker. -Punctuation is zero or more spaces, commas, or semicolons. The hours -marker is one or more non-punctuation characters. The minutes and -seconds markers must be single non-punctuation characters. - -The default HMS format is @samp{@@ ' "}, producing HMS values of the form -@samp{23@@ 30' 15.75"}. The format @samp{deg, ms} would display this same -value as @samp{23deg, 30m15.75s}. During numeric entry, the @kbd{h} or @kbd{o} -keys are recognized as synonyms for @kbd{@@} regardless of display format. -The @kbd{m} and @kbd{s} keys are recognized as synonyms for @kbd{'} and -@kbd{"}, respectively, but only if an @kbd{@@} (or @kbd{h} or @kbd{o}) has -already been typed; otherwise, they have their usual meanings -(@kbd{m-} prefix and @kbd{s-} prefix). Thus, @kbd{5 "}, @kbd{0 @@ 5 "}, and -@kbd{0 h 5 s} are some of the ways to enter the quantity ``five seconds.'' -The @kbd{'} key is recognized as ``minutes'' only if @kbd{@@} (or @kbd{h} or -@kbd{o}) has already been pressed; otherwise it means to switch to algebraic -entry. - -@node Date Formats, Truncating the Stack, HMS Formats, Display Modes -@subsection Date Formats - -@noindent -@kindex d d -@pindex calc-date-notation -The @kbd{d d} (@code{calc-date-notation}) command controls the display -of date forms (@pxref{Date Forms}). It prompts for a string which -contains letters that represent the various parts of a date and time. -To show which parts should be omitted when the form represents a pure -date with no time, parts of the string can be enclosed in @samp{< >} -marks. If you don't include @samp{< >} markers in the format, Calc -guesses at which parts, if any, should be omitted when formatting -pure dates. - -The default format is: @samp{Www Mmm D, YYYY}. -An example string in this format is @samp{3:32pm Wed Jan 9, 1991}. -If you enter a blank format string, this default format is -reestablished. - -Calc uses @samp{< >} notation for nameless functions as well as for -dates. @xref{Specifying Operators}. To avoid confusion with nameless -functions, your date formats should avoid using the @samp{#} character. - -@menu -* ISO 8601:: -* Date Formatting Codes:: -* Free-Form Dates:: -* Standard Date Formats:: -@end menu - -@node ISO 8601, Date Formatting Codes, Date Formats, Date Formats -@subsubsection ISO 8601 - -@noindent -@cindex ISO 8601 -The same date can be written down in different formats and Calc tries -to allow you to choose your preferred format. Some common formats are -ambiguous, however; for example, 10/11/2012 means October 11, -2012 in the United States but it means November 10, 2012 in -Europe. To help avoid such ambiguities, the International Organization -for Standardization (ISO) provides the ISO 8601 standard, which -provides three different but easily distinguishable and unambiguous -ways to represent a date. - -The ISO 8601 calendar date representation is - -@example - @var{YYYY}-@var{MM}-@var{DD} -@end example - -@noindent -where @var{YYYY} is the four digit year, @var{MM} is the two-digit month -number (01 for January to 12 for December), and @var{DD} is the -two-digit day of the month (01 to 31). (Note that @var{YYYY} does not -correspond to Calc's date formatting code, which will be introduced -later.) The year, which should be padded with zeros to ensure it has at -least four digits, is the Gregorian year, except that the year before -0001 (1 AD) is the year 0000 (1 BC). The date October 11, 2012 is -written 2012-10-11 in this representation and November 10, 2012 is -written 2012-11-10. - -The ISO 8601 ordinal date representation is - -@example - @var{YYYY}-@var{DDD} -@end example - -@noindent -where @var{YYYY} is the year, as above, and @var{DDD} is the day of the year. -The date December 31, 2011 is written 2011-365 in this representation -and January 1, 2012 is written 2012-001. - -The ISO 8601 week date representation is - -@example - @var{YYYY}-W@var{ww}-@var{D} -@end example - -@noindent -where @var{YYYY} is the ISO week-numbering year, @var{ww} is the two -digit week number (preceded by a literal ``W''), and @var{D} is the day -of the week (1 for Monday through 7 for Sunday). The ISO week-numbering -year is based on the Gregorian year but can differ slightly. The first -week of an ISO week-numbering year is the week with the Gregorian year's -first Thursday in it (equivalently, the week containing January 4); -any day of that week (Monday through Sunday) is part of the same ISO -week-numbering year, any day from the previous week is part of the -previous year. For example, January 4, 2013 is on a Friday, and so -the first week for the ISO week-numbering year 2013 starts on -Monday, December 31, 2012. The day December 31, 2012 is then part of the -Gregorian year 2012 but ISO week-numbering year 2013. In the week -date representation, this week goes from 2013-W01-1 (December 31, -2012) to 2013-W01-7 (January 6, 2013). - -All three ISO 8601 representations arrange the numbers from most -significant to least significant; as well as being unambiguous -representations, they are easy to sort since chronological order in -this formats corresponds to lexicographical order. The hyphens are -sometimes omitted. - -The ISO 8601 standard uses a 24 hour clock; a particular time is -represented by @var{hh}:@var{mm}:@var{ss} where @var{hh} is the -two-digit hour (from 00 to 24), @var{mm} is the two-digit minute (from -00 to 59) and @var{ss} is the two-digit second. The seconds or minutes -and seconds can be omitted, and decimals can be added. If a date with a -time is represented, they should be separated by a literal ``T'', so noon -on December 13, 2012 can be represented as 2012-12-13T12:00. - -@node Date Formatting Codes, Free-Form Dates, ISO 8601, Date Formats -@subsubsection Date Formatting Codes - -@noindent -When displaying a date, the current date format is used. All -characters except for letters and @samp{<} and @samp{>} are -copied literally when dates are formatted. The portion between -@samp{< >} markers is omitted for pure dates, or included for -date/time forms. Letters are interpreted according to the table -below. - -When dates are read in during algebraic entry, Calc first tries to -match the input string to the current format either with or without -the time part. The punctuation characters (including spaces) must -match exactly; letter fields must correspond to suitable text in -the input. If this doesn't work, Calc checks if the input is a -simple number; if so, the number is interpreted as a number of days -since Dec 31, 1 BC@. Otherwise, Calc tries a much more relaxed and -flexible algorithm which is described in the next section. - -Weekday names are ignored during reading. - -Two-digit year numbers are interpreted as lying in the range -from 1941 to 2039. Years outside that range are always -entered and displayed in full. Year numbers with a leading -@samp{+} sign are always interpreted exactly, allowing the -entry and display of the years 1 through 99 AD. - -Here is a complete list of the formatting codes for dates: - -@table @asis -@item Y -Year: ``91'' for 1991, ``7'' for 2007, ``+23'' for 23 AD. -@item YY -Year: ``91'' for 1991, ``07'' for 2007, ``+23'' for 23 AD. -@item BY -Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD. -@item YYY -Year: ``1991'' for 1991, ``23'' for 23 AD. -@item YYYY -Year: ``1991'' for 1991, ``+23'' for 23 AD. -@item ZYYY -Year: ``1991'' for 1991, ``0023'' for 23 AD, ``0000'' for 1 BC. -@item IYYY -Year: ISO 8601 week-numbering year. -@item aa -Year: ``ad'' or blank. -@item AA -Year: ``AD'' or blank. -@item aaa -Year: ``ad '' or blank. (Note trailing space.) -@item AAA -Year: ``AD '' or blank. -@item aaaa -Year: ``a.d.@:'' or blank. -@item AAAA -Year: ``A.D.'' or blank. -@item bb -Year: ``bc'' or blank. -@item BB -Year: ``BC'' or blank. -@item bbb -Year: `` bc'' or blank. (Note leading space.) -@item BBB -Year: `` BC'' or blank. -@item bbbb -Year: ``b.c.@:'' or blank. -@item BBBB -Year: ``B.C.'' or blank. -@item M -Month: ``8'' for August. -@item MM -Month: ``08'' for August. -@item BM -Month: `` 8'' for August. -@item MMM -Month: ``AUG'' for August. -@item Mmm -Month: ``Aug'' for August. -@item mmm -Month: ``aug'' for August. -@item MMMM -Month: ``AUGUST'' for August. -@item Mmmm -Month: ``August'' for August. -@item D -Day: ``7'' for 7th day of month. -@item DD -Day: ``07'' for 7th day of month. -@item BD -Day: `` 7'' for 7th day of month. -@item W -Weekday: ``0'' for Sunday, ``6'' for Saturday. -@item w -Weekday: ``1'' for Monday, ``7'' for Sunday. -@item WWW -Weekday: ``SUN'' for Sunday. -@item Www -Weekday: ``Sun'' for Sunday. -@item www -Weekday: ``sun'' for Sunday. -@item WWWW -Weekday: ``SUNDAY'' for Sunday. -@item Wwww -Weekday: ``Sunday'' for Sunday. -@item Iww -Week number: ISO 8601 week number, ``W01'' for week 1. -@item d -Day of year: ``34'' for Feb. 3. -@item ddd -Day of year: ``034'' for Feb. 3. -@item bdd -Day of year: `` 34'' for Feb. 3. -@item T -Letter: Literal ``T''. -@item h -Hour: ``5'' for 5 AM; ``17'' for 5 PM. -@item hh -Hour: ``05'' for 5 AM; ``17'' for 5 PM. -@item bh -Hour: `` 5'' for 5 AM; ``17'' for 5 PM. -@item H -Hour: ``5'' for 5 AM and 5 PM. -@item HH -Hour: ``05'' for 5 AM and 5 PM. -@item BH -Hour: `` 5'' for 5 AM and 5 PM. -@item p -AM/PM: ``a'' or ``p''. -@item P -AM/PM: ``A'' or ``P''. -@item pp -AM/PM: ``am'' or ``pm''. -@item PP -AM/PM: ``AM'' or ``PM''. -@item pppp -AM/PM: ``a.m.@:'' or ``p.m.''. -@item PPPP -AM/PM: ``A.M.'' or ``P.M.''. -@item m -Minutes: ``7'' for 7. -@item mm -Minutes: ``07'' for 7. -@item bm -Minutes: `` 7'' for 7. -@item s -Seconds: ``7'' for 7; ``7.23'' for 7.23. -@item ss -Seconds: ``07'' for 7; ``07.23'' for 7.23. -@item bs -Seconds: `` 7'' for 7; `` 7.23'' for 7.23. -@item SS -Optional seconds: ``07'' for 7; blank for 0. -@item BS -Optional seconds: `` 7'' for 7; blank for 0. -@item N -Numeric date/time: ``726842.25'' for 6:00am Wed Jan 9, 1991. -@item n -Numeric date: ``726842'' for any time on Wed Jan 9, 1991. -@item J -Julian date/time: ``2448265.75'' for 6:00am Wed Jan 9, 1991. -@item j -Julian date: ``2448266'' for any time on Wed Jan 9, 1991. -@item U -Unix time: ``663400800'' for 6:00am Wed Jan 9, 1991. -@item X -Brackets suppression. An ``X'' at the front of the format -causes the surrounding @w{@samp{< >}} delimiters to be omitted -when formatting dates. Note that the brackets are still -required for algebraic entry. -@end table - -If ``SS'' or ``BS'' (optional seconds) is preceded by a colon, the -colon is also omitted if the seconds part is zero. - -If ``bb,'' ``bbb'' or ``bbbb'' or their upper-case equivalents -appear in the format, then negative year numbers are displayed -without a minus sign. Note that ``aa'' and ``bb'' are mutually -exclusive. Some typical usages would be @samp{YYYY AABB}; -@samp{AAAYYYYBBB}; @samp{YYYYBBB}. - -The formats ``YY,'' ``YYYY,'' ``MM,'' ``DD,'' ``ddd,'' ``hh,'' ``HH,'' -``mm,'' ``ss,'' and ``SS'' actually match any number of digits during -reading unless several of these codes are strung together with no -punctuation in between, in which case the input must have exactly as -many digits as there are letters in the format. - -The ``j,'' ``J,'' and ``U'' formats do not make any time zone -adjustment. They effectively use @samp{julian(x,0)} and -@samp{unixtime(x,0)} to make the conversion; @pxref{Date Arithmetic}. - -@node Free-Form Dates, Standard Date Formats, Date Formatting Codes, Date Formats -@subsubsection Free-Form Dates - -@noindent -When reading a date form during algebraic entry, Calc falls back -on the algorithm described here if the input does not exactly -match the current date format. This algorithm generally -``does the right thing'' and you don't have to worry about it, -but it is described here in full detail for the curious. - -Calc does not distinguish between upper- and lower-case letters -while interpreting dates. - -First, the time portion, if present, is located somewhere in the -text and then removed. The remaining text is then interpreted as -the date. - -A time is of the form @samp{hh:mm:ss}, possibly with the seconds -part omitted and possibly with an AM/PM indicator added to indicate -12-hour time. If the AM/PM is present, the minutes may also be -omitted. The AM/PM part may be any of the words @samp{am}, -@samp{pm}, @samp{noon}, or @samp{midnight}; each of these may be -abbreviated to one letter, and the alternate forms @samp{a.m.}, -@samp{p.m.}, and @samp{mid} are also understood. Obviously -@samp{noon} and @samp{midnight} are allowed only on 12:00:00. -The words @samp{noon}, @samp{mid}, and @samp{midnight} are also -recognized with no number attached. Midnight will represent the -beginning of a day. - -If there is no AM/PM indicator, the time is interpreted in 24-hour -format. - -When reading the date portion, Calc first checks to see if it is an -ISO 8601 week-numbering date; if the string contains an integer -representing the year, a ``W'' followed by two digits for the week -number, and an integer from 1 to 7 representing the weekday (in that -order), then all other characters are ignored and this information -determines the date. Otherwise, all words and numbers are isolated -from the string; other characters are ignored. All words must be -either month names or day-of-week names (the latter of which are -ignored). Names can be written in full or as three-letter -abbreviations. - -Large numbers, or numbers with @samp{+} or @samp{-} signs, -are interpreted as years. If one of the other numbers is -greater than 12, then that must be the day and the remaining -number in the input is therefore the month. Otherwise, Calc -assumes the month, day and year are in the same order that they -appear in the current date format. If the year is omitted, the -current year is taken from the system clock. - -If there are too many or too few numbers, or any unrecognizable -words, then the input is rejected. - -If there are any large numbers (of five digits or more) other than -the year, they are ignored on the assumption that they are something -like Julian dates that were included along with the traditional -date components when the date was formatted. - -One of the words @samp{ad}, @samp{a.d.}, @samp{bc}, or @samp{b.c.} -may optionally be used; the latter two are equivalent to a -minus sign on the year value. - -If you always enter a four-digit year, and use a name instead -of a number for the month, there is no danger of ambiguity. - -@node Standard Date Formats, , Free-Form Dates, Date Formats -@subsubsection Standard Date Formats - -@noindent -There are actually ten standard date formats, numbered 0 through 9. -Entering a blank line at the @kbd{d d} command's prompt gives -you format number 1, Calc's usual format. You can enter any digit -to select the other formats. - -To create your own standard date formats, give a numeric prefix -argument from 0 to 9 to the @w{@kbd{d d}} command. The format you -enter will be recorded as the new standard format of that -number, as well as becoming the new current date format. -You can save your formats permanently with the @w{@kbd{m m}} -command (@pxref{Mode Settings}). - -@table @asis -@item 0 -@samp{N} (Numerical format) -@item 1 -@samp{Www Mmm D, YYYY} (American format) -@item 2 -@samp{D Mmm YYYY<, h:mm:SS>} (European format) -@item 3 -@samp{Www Mmm BD< hh:mm:ss> YYYY} (Unix written date format) -@item 4 -@samp{M/D/Y< H:mm:SSpp>} (American slashed format) -@item 5 -@samp{D.M.Y< h:mm:SS>} (European dotted format) -@item 6 -@samp{M-D-Y< H:mm:SSpp>} (American dashed format) -@item 7 -@samp{D-M-Y< h:mm:SS>} (European dashed format) -@item 8 -@samp{j<, h:mm:ss>} (Julian day plus time) -@item 9 -@samp{YYddd< hh:mm:ss>} (Year-day format) -@item 10 -@samp{ZYYY-MM-DD Www< hh:mm>} (Org mode format) -@item 11 -@samp{IYYY-Iww-w} (ISO 8601 week numbering format) -@end table - -@node Truncating the Stack, Justification, Date Formats, Display Modes -@subsection Truncating the Stack - -@noindent -@kindex d t -@pindex calc-truncate-stack -@cindex Truncating the stack -@cindex Narrowing the stack -The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@: -line that marks the top-of-stack up or down in the Calculator buffer. -The number right above that line is considered to the be at the top of -the stack. Any numbers below that line are ``hidden'' from all stack -operations (although still visible to the user). This is similar to the -Emacs ``narrowing'' feature, except that the values below the @samp{.} -are @emph{visible}, just temporarily frozen. This feature allows you to -keep several independent calculations running at once in different parts -of the stack, or to apply a certain command to an element buried deep in -the stack. - -Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor -is on. Thus, this line and all those below it become hidden. To un-hide -these lines, move down to the end of the buffer and press @w{@kbd{d t}}. -With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the -bottom @expr{n} values in the buffer. With a negative argument, it hides -all but the top @expr{n} values. With an argument of zero, it hides zero -values, i.e., moves the @samp{.} all the way down to the bottom. - -@kindex d [ -@pindex calc-truncate-up -@kindex d ] -@pindex calc-truncate-down -The @kbd{d [} (@code{calc-truncate-up}) and @kbd{d ]} -(@code{calc-truncate-down}) commands move the @samp{.} up or down one -line at a time (or several lines with a prefix argument). - -@node Justification, Labels, Truncating the Stack, Display Modes -@subsection Justification - -@noindent -@kindex d < -@pindex calc-left-justify -@kindex d = -@pindex calc-center-justify -@kindex d > -@pindex calc-right-justify -Values on the stack are normally left-justified in the window. You can -control this arrangement by typing @kbd{d <} (@code{calc-left-justify}), -@kbd{d >} (@code{calc-right-justify}), or @kbd{d =} -(@code{calc-center-justify}). For example, in Right-Justification mode, -stack entries are displayed flush-right against the right edge of the -window. - -If you change the width of the Calculator window you may have to type -@kbd{d @key{SPC}} (@code{calc-refresh}) to re-align right-justified or centered -text. - -Right-justification is especially useful together with fixed-point -notation (see @code{d f}; @code{calc-fix-notation}). With these modes -together, the decimal points on numbers will always line up. - -With a numeric prefix argument, the justification commands give you -a little extra control over the display. The argument specifies the -horizontal ``origin'' of a display line. It is also possible to -specify a maximum line width using the @kbd{d b} command (@pxref{Normal -Language Modes}). For reference, the precise rules for formatting and -breaking lines are given below. Notice that the interaction between -origin and line width is slightly different in each justification -mode. - -In Left-Justified mode, the line is indented by a number of spaces -given by the origin (default zero). If the result is longer than the -maximum line width, if given, or too wide to fit in the Calc window -otherwise, then it is broken into lines which will fit; each broken -line is indented to the origin. - -In Right-Justified mode, lines are shifted right so that the rightmost -character is just before the origin, or just before the current -window width if no origin was specified. If the line is too long -for this, then it is broken; the current line width is used, if -specified, or else the origin is used as a width if that is -specified, or else the line is broken to fit in the window. - -In Centering mode, the origin is the column number of the center of -each stack entry. If a line width is specified, lines will not be -allowed to go past that width; Calc will either indent less or -break the lines if necessary. If no origin is specified, half the -line width or Calc window width is used. - -Note that, in each case, if line numbering is enabled the display -is indented an additional four spaces to make room for the line -number. The width of the line number is taken into account when -positioning according to the current Calc window width, but not -when positioning by explicit origins and widths. In the latter -case, the display is formatted as specified, and then uniformly -shifted over four spaces to fit the line numbers. - -@node Labels, , Justification, Display Modes -@subsection Labels - -@noindent -@kindex d @{ -@pindex calc-left-label -The @kbd{d @{} (@code{calc-left-label}) command prompts for a string, -then displays that string to the left of every stack entry. If the -entries are left-justified (@pxref{Justification}), then they will -appear immediately after the label (unless you specified an origin -greater than the length of the label). If the entries are centered -or right-justified, the label appears on the far left and does not -affect the horizontal position of the stack entry. - -Give a blank string (with @kbd{d @{ @key{RET}}) to turn the label off. - -@kindex d @} -@pindex calc-right-label -The @kbd{d @}} (@code{calc-right-label}) command similarly adds a -label on the righthand side. It does not affect positioning of -the stack entries unless they are right-justified. Also, if both -a line width and an origin are given in Right-Justified mode, the -stack entry is justified to the origin and the righthand label is -justified to the line width. - -One application of labels would be to add equation numbers to -formulas you are manipulating in Calc and then copying into a -document (possibly using Embedded mode). The equations would -typically be centered, and the equation numbers would be on the -left or right as you prefer. - -@node Language Modes, Modes Variable, Display Modes, Mode Settings -@section Language Modes - -@noindent -The commands in this section change Calc to use a different notation for -entry and display of formulas, corresponding to the conventions of some -other common language such as Pascal or @LaTeX{}. Objects displayed on the -stack or yanked from the Calculator to an editing buffer will be formatted -in the current language; objects entered in algebraic entry or yanked from -another buffer will be interpreted according to the current language. - -The current language has no effect on things written to or read from the -trail buffer, nor does it affect numeric entry. Only algebraic entry is -affected. You can make even algebraic entry ignore the current language -and use the standard notation by giving a numeric prefix, e.g., @kbd{C-u '}. - -For example, suppose the formula @samp{2*a[1] + atan(a[2])} occurs in a C -program; elsewhere in the program you need the derivatives of this formula -with respect to @samp{a[1]} and @samp{a[2]}. First, type @kbd{d C} -to switch to C notation. Now use @code{C-u C-x * g} to grab the formula -into the Calculator, @kbd{a d a[1] @key{RET}} to differentiate with respect -to the first variable, and @kbd{C-x * y} to yank the formula for the derivative -back into your C program. Press @kbd{U} to undo the differentiation and -repeat with @kbd{a d a[2] @key{RET}} for the other derivative. - -Without being switched into C mode first, Calc would have misinterpreted -the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that -@code{atan} was equivalent to Calc's built-in @code{arctan} function, -and would have written the formula back with notations (like implicit -multiplication) which would not have been valid for a C program. - -As another example, suppose you are maintaining a C program and a @LaTeX{} -document, each of which needs a copy of the same formula. You can grab the -formula from the program in C mode, switch to @LaTeX{} mode, and yank the -formula into the document in @LaTeX{} math-mode format. - -Language modes are selected by typing the letter @kbd{d} followed by a -shifted letter key. - -@menu -* Normal Language Modes:: -* C FORTRAN Pascal:: -* TeX and LaTeX Language Modes:: -* Eqn Language Mode:: -* Yacas Language Mode:: -* Maxima Language Mode:: -* Giac Language Mode:: -* Mathematica Language Mode:: -* Maple Language Mode:: -* Compositions:: -* Syntax Tables:: -@end menu - -@node Normal Language Modes, C FORTRAN Pascal, Language Modes, Language Modes -@subsection Normal Language Modes - -@noindent -@kindex d N -@pindex calc-normal-language -The @kbd{d N} (@code{calc-normal-language}) command selects the usual -notation for Calc formulas, as described in the rest of this manual. -Matrices are displayed in a multi-line tabular format, but all other -objects are written in linear form, as they would be typed from the -keyboard. - -@kindex d O -@pindex calc-flat-language -@cindex Matrix display -The @kbd{d O} (@code{calc-flat-language}) command selects a language -identical with the normal one, except that matrices are written in -one-line form along with everything else. In some applications this -form may be more suitable for yanking data into other buffers. - -@kindex d b -@pindex calc-line-breaking -@cindex Line breaking -@cindex Breaking up long lines -Even in one-line mode, long formulas or vectors will still be split -across multiple lines if they exceed the width of the Calculator window. -The @kbd{d b} (@code{calc-line-breaking}) command turns this line-breaking -feature on and off. (It works independently of the current language.) -If you give a numeric prefix argument of five or greater to the @kbd{d b} -command, that argument will specify the line width used when breaking -long lines. - -@kindex d B -@pindex calc-big-language -The @kbd{d B} (@code{calc-big-language}) command selects a language -which uses textual approximations to various mathematical notations, -such as powers, quotients, and square roots: - -@example - ____________ - | a + 1 2 - | ----- + c -\| b -@end example - -@noindent -in place of @samp{sqrt((a+1)/b + c^2)}. - -Subscripts like @samp{a_i} are displayed as actual subscripts in Big -mode. Double subscripts, @samp{a_i_j} (@samp{subscr(subscr(a, i), j)}) -are displayed as @samp{a} with subscripts separated by commas: -@samp{i, j}. They must still be entered in the usual underscore -notation. - -One slight ambiguity of Big notation is that - -@example - 3 -- - - 4 -@end example - -@noindent -can represent either the negative rational number @expr{-3:4}, or the -actual expression @samp{-(3/4)}; but the latter formula would normally -never be displayed because it would immediately be evaluated to -@expr{-3:4} or @expr{-0.75}, so this ambiguity is not a problem in -typical use. - -Non-decimal numbers are displayed with subscripts. Thus there is no -way to tell the difference between @samp{16#C2} and @samp{C2_16}, -though generally you will know which interpretation is correct. -Logarithms @samp{log(x,b)} and @samp{log10(x)} also use subscripts -in Big mode. - -In Big mode, stack entries often take up several lines. To aid -readability, stack entries are separated by a blank line in this mode. -You may find it useful to expand the Calc window's height using -@kbd{C-x ^} (@code{enlarge-window}) or to make the Calc window the only -one on the screen with @kbd{C-x 1} (@code{delete-other-windows}). - -Long lines are currently not rearranged to fit the window width in -Big mode, so you may need to use the @kbd{<} and @kbd{>} keys -to scroll across a wide formula. For really big formulas, you may -even need to use @kbd{@{} and @kbd{@}} to scroll up and down. - -@kindex d U -@pindex calc-unformatted-language -The @kbd{d U} (@code{calc-unformatted-language}) command altogether disables -the use of operator notation in formulas. In this mode, the formula -shown above would be displayed: - -@example -sqrt(add(div(add(a, 1), b), pow(c, 2))) -@end example - -These four modes differ only in display format, not in the format -expected for algebraic entry. The standard Calc operators work in -all four modes, and unformatted notation works in any language mode -(except that Mathematica mode expects square brackets instead of -parentheses). - -@node C FORTRAN Pascal, TeX and LaTeX Language Modes, Normal Language Modes, Language Modes -@subsection C, FORTRAN, and Pascal Modes - -@noindent -@kindex d C -@pindex calc-c-language -@cindex C language -The @kbd{d C} (@code{calc-c-language}) command selects the conventions -of the C language for display and entry of formulas. This differs from -the normal language mode in a variety of (mostly minor) ways. In -particular, C language operators and operator precedences are used in -place of Calc's usual ones. For example, @samp{a^b} means @samp{xor(a,b)} -in C mode; a value raised to a power is written as a function call, -@samp{pow(a,b)}. - -In C mode, vectors and matrices use curly braces instead of brackets. -Octal and hexadecimal values are written with leading @samp{0} or @samp{0x} -rather than using the @samp{#} symbol. Array subscripting is -translated into @code{subscr} calls, so that @samp{a[i]} in C -mode is the same as @samp{a_i} in Normal mode. Assignments -turn into the @code{assign} function, which Calc normally displays -using the @samp{:=} symbol. - -The variables @code{pi} and @code{e} would be displayed @samp{pi} -and @samp{e} in Normal mode, but in C mode they are displayed as -@samp{M_PI} and @samp{M_E}, corresponding to the names of constants -typically provided in the @file{} header. Functions whose -names are different in C are translated automatically for entry and -display purposes. For example, entering @samp{asin(x)} will push the -formula @samp{arcsin(x)} onto the stack; this formula will be displayed -as @samp{asin(x)} as long as C mode is in effect. - -@kindex d P -@pindex calc-pascal-language -@cindex Pascal language -The @kbd{d P} (@code{calc-pascal-language}) command selects Pascal -conventions. Like C mode, Pascal mode interprets array brackets and uses -a different table of operators. Hexadecimal numbers are entered and -displayed with a preceding dollar sign. (Thus the regular meaning of -@kbd{$2} during algebraic entry does not work in Pascal mode, though -@kbd{$} (and @kbd{$$}, etc.)@: not followed by digits works the same as -always.) No special provisions are made for other non-decimal numbers, -vectors, and so on, since there is no universally accepted standard way -of handling these in Pascal. - -@kindex d F -@pindex calc-fortran-language -@cindex FORTRAN language -The @kbd{d F} (@code{calc-fortran-language}) command selects FORTRAN -conventions. Various function names are transformed into FORTRAN -equivalents. Vectors are written as @samp{/1, 2, 3/}, and may be -entered this way or using square brackets. Since FORTRAN uses round -parentheses for both function calls and array subscripts, Calc displays -both in the same way; @samp{a(i)} is interpreted as a function call -upon reading, and subscripts must be entered as @samp{subscr(a, i)}. -If the variable @code{a} has been declared to have type -@code{vector} or @code{matrix}, however, then @samp{a(i)} will be -parsed as a subscript. (@xref{Declarations}.) Usually it doesn't -matter, though; if you enter the subscript expression @samp{a(i)} and -Calc interprets it as a function call, you'll never know the difference -unless you switch to another language mode or replace @code{a} with an -actual vector (or unless @code{a} happens to be the name of a built-in -function!). - -Underscores are allowed in variable and function names in all of these -language modes. The underscore here is equivalent to the @samp{#} in -Normal mode, or to hyphens in the underlying Emacs Lisp variable names. - -FORTRAN and Pascal modes normally do not adjust the case of letters in -formulas. Most built-in Calc names use lower-case letters. If you use a -positive numeric prefix argument with @kbd{d P} or @kbd{d F}, these -modes will use upper-case letters exclusively for display, and will -convert to lower-case on input. With a negative prefix, these modes -convert to lower-case for display and input. - -@node TeX and LaTeX Language Modes, Eqn Language Mode, C FORTRAN Pascal, Language Modes -@subsection @TeX{} and @LaTeX{} Language Modes - -@noindent -@kindex d T -@pindex calc-tex-language -@cindex TeX language -@kindex d L -@pindex calc-latex-language -@cindex LaTeX language -The @kbd{d T} (@code{calc-tex-language}) command selects the conventions -of ``math mode'' in Donald Knuth's @TeX{} typesetting language, -and the @kbd{d L} (@code{calc-latex-language}) command selects the -conventions of ``math mode'' in @LaTeX{}, a typesetting language that -uses @TeX{} as its formatting engine. Calc's @LaTeX{} language mode can -read any formula that the @TeX{} language mode can, although @LaTeX{} -mode may display it differently. - -Formulas are entered and displayed in the appropriate notation; -@texline @math{\sin(a/b)} -@infoline @expr{sin(a/b)} -will appear as @samp{\sin\left( @{a \over b@} \right)} in @TeX{} mode and -@samp{\sin\left(\frac@{a@}@{b@}\right)} in @LaTeX{} mode. -Math formulas are often enclosed by @samp{$ $} signs in @TeX{} and -@LaTeX{}; these should be omitted when interfacing with Calc. To Calc, -the @samp{$} sign has the same meaning it always does in algebraic -formulas (a reference to an existing entry on the stack). - -Complex numbers are displayed as in @samp{3 + 4i}. Fractions and -quotients are written using @code{\over} in @TeX{} mode (as in -@code{@{a \over b@}}) and @code{\frac} in @LaTeX{} mode (as in -@code{\frac@{a@}@{b@}}); binomial coefficients are written with -@code{\choose} in @TeX{} mode (as in @code{@{a \choose b@}}) and -@code{\binom} in @LaTeX{} mode (as in @code{\binom@{a@}@{b@}}). -Interval forms are written with @code{\ldots}, and error forms are -written with @code{\pm}. Absolute values are written as in -@samp{|x + 1|}, and the floor and ceiling functions are written with -@code{\lfloor}, @code{\rfloor}, etc. The words @code{\left} and -@code{\right} are ignored when reading formulas in @TeX{} and @LaTeX{} -modes. Both @code{inf} and @code{uinf} are written as @code{\infty}; -when read, @code{\infty} always translates to @code{inf}. - -Function calls are written the usual way, with the function name followed -by the arguments in parentheses. However, functions for which @TeX{} -and @LaTeX{} have special names (like @code{\sin}) will use curly braces -instead of parentheses for very simple arguments. During input, curly -braces and parentheses work equally well for grouping, but when the -document is formatted the curly braces will be invisible. Thus the -printed result is -@texline @math{\sin{2 x}} -@infoline @expr{sin 2x} -but -@texline @math{\sin(2 + x)}. -@infoline @expr{sin(2 + x)}. - -The @TeX{} specific unit names (@pxref{Predefined Units}) will not use -the @samp{tex} prefix; the unit name for a @TeX{} point will be -@samp{pt} instead of @samp{texpt}, for example. - -Function and variable names not treated specially by @TeX{} and @LaTeX{} -are simply written out as-is, which will cause them to come out in -italic letters in the printed document. If you invoke @kbd{d T} or -@kbd{d L} with a positive numeric prefix argument, names of more than -one character will instead be enclosed in a protective commands that -will prevent them from being typeset in the math italics; they will be -written @samp{\hbox@{@var{name}@}} in @TeX{} mode and -@samp{\text@{@var{name}@}} in @LaTeX{} mode. The -@samp{\hbox@{ @}} and @samp{\text@{ @}} notations are ignored during -reading. If you use a negative prefix argument, such function names are -written @samp{\@var{name}}, and function names that begin with @code{\} during -reading have the @code{\} removed. (Note that in this mode, long -variable names are still written with @code{\hbox} or @code{\text}. -However, you can always make an actual variable name like @code{\bar} in -any @TeX{} mode.) - -During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced -by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and -@code{\bmatrix}. In @LaTeX{} mode this also applies to -@samp{\begin@{matrix@} ... \end@{matrix@}}, -@samp{\begin@{bmatrix@} ... \end@{bmatrix@}}, -@samp{\begin@{pmatrix@} ... \end@{pmatrix@}}, as well as -@samp{\begin@{smallmatrix@} ... \end@{smallmatrix@}}. -The symbol @samp{&} is interpreted as a comma, -and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons. -During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}} -format in @TeX{} mode and in -@samp{\begin@{pmatrix@} a & b \\ c & d \end@{pmatrix@}} format in -@LaTeX{} mode; you may need to edit this afterwards to change to your -preferred matrix form. If you invoke @kbd{d T} or @kbd{d L} with an -argument of 2 or -2, then matrices will be displayed in two-dimensional -form, such as - -@example -\begin@{pmatrix@} -a & b \\ -c & d -\end@{pmatrix@} -@end example - -@noindent -This may be convenient for isolated matrices, but could lead to -expressions being displayed like - -@example -\begin@{pmatrix@} \times x -a & b \\ -c & d -\end@{pmatrix@} -@end example - -@noindent -While this wouldn't bother Calc, it is incorrect @LaTeX{}. -(Similarly for @TeX{}.) - -Accents like @code{\tilde} and @code{\bar} translate into function -calls internally (@samp{tilde(x)}, @samp{bar(x)}). The @code{\underline} -sequence is treated as an accent. The @code{\vec} accent corresponds -to the function name @code{Vec}, because @code{vec} is the name of -a built-in Calc function. The following table shows the accents -in Calc, @TeX{}, @LaTeX{} and @dfn{eqn} (described in the next section): - -@ignore -@iftex -@begingroup -@let@calcindexershow=@calcindexernoshow @c Suppress marginal notes -@let@calcindexersh=@calcindexernoshow -@end iftex -@starindex -@end ignore -@tindex acute -@ignore -@starindex -@end ignore -@tindex Acute -@ignore -@starindex -@end ignore -@tindex bar -@ignore -@starindex -@end ignore -@tindex Bar -@ignore -@starindex -@end ignore -@tindex breve -@ignore -@starindex -@end ignore -@tindex Breve -@ignore -@starindex -@end ignore -@tindex check -@ignore -@starindex -@end ignore -@tindex Check -@ignore -@starindex -@end ignore -@tindex dddot -@ignore -@starindex -@end ignore -@tindex ddddot -@ignore -@starindex -@end ignore -@tindex dot -@ignore -@starindex -@end ignore -@tindex Dot -@ignore -@starindex -@end ignore -@tindex dotdot -@ignore -@starindex -@end ignore -@tindex DotDot -@ignore -@starindex -@end ignore -@tindex dyad -@ignore -@starindex -@end ignore -@tindex grave -@ignore -@starindex -@end ignore -@tindex Grave -@ignore -@starindex -@end ignore -@tindex hat -@ignore -@starindex -@end ignore -@tindex Hat -@ignore -@starindex -@end ignore -@tindex Prime -@ignore -@starindex -@end ignore -@tindex tilde -@ignore -@starindex -@end ignore -@tindex Tilde -@ignore -@starindex -@end ignore -@tindex under -@ignore -@starindex -@end ignore -@tindex Vec -@ignore -@starindex -@end ignore -@tindex VEC -@ignore -@iftex -@endgroup -@end iftex -@end ignore -@example -Calc TeX LaTeX eqn ----- --- ----- --- -acute \acute \acute -Acute \Acute -bar \bar \bar bar -Bar \Bar -breve \breve \breve -Breve \Breve -check \check \check -Check \Check -dddot \dddot -ddddot \ddddot -dot \dot \dot dot -Dot \Dot -dotdot \ddot \ddot dotdot -DotDot \Ddot -dyad dyad -grave \grave \grave -Grave \Grave -hat \hat \hat hat -Hat \Hat -Prime prime -tilde \tilde \tilde tilde -Tilde \Tilde -under \underline \underline under -Vec \vec \vec vec -VEC \Vec -@end example - -The @samp{=>} (evaluates-to) operator appears as a @code{\to} symbol: -@samp{@{@var{a} \to @var{b}@}}. @TeX{} defines @code{\to} as an -alias for @code{\rightarrow}. However, if the @samp{=>} is the -top-level expression being formatted, a slightly different notation -is used: @samp{\evalto @var{a} \to @var{b}}. The @code{\evalto} -word is ignored by Calc's input routines, and is undefined in @TeX{}. -You will typically want to include one of the following definitions -at the top of a @TeX{} file that uses @code{\evalto}: - -@example -\def\evalto@{@} -\def\evalto#1\to@{@} -@end example - -The first definition formats evaluates-to operators in the usual -way. The second causes only the @var{b} part to appear in the -printed document; the @var{a} part and the arrow are hidden. -Another definition you may wish to use is @samp{\let\to=\Rightarrow} -which causes @code{\to} to appear more like Calc's @samp{=>} symbol. -@xref{Evaluates-To Operator}, for a discussion of @code{evalto}. - -The complete set of @TeX{} control sequences that are ignored during -reading is: - -@example -\hbox \mbox \text \left \right -\, \> \: \; \! \quad \qquad \hfil \hfill -\displaystyle \textstyle \dsize \tsize -\scriptstyle \scriptscriptstyle \ssize \ssize -\rm \bf \it \sl \roman \bold \italic \slanted -\cal \mit \Cal \Bbb \frak \goth -\evalto -@end example - -Note that, because these symbols are ignored, reading a @TeX{} or -@LaTeX{} formula into Calc and writing it back out may lose spacing and -font information. - -Also, the ``discretionary multiplication sign'' @samp{\*} is read -the same as @samp{*}. - -@ifnottex -The @TeX{} version of this manual includes some printed examples at the -end of this section. -@end ifnottex -@iftex -Here are some examples of how various Calc formulas are formatted in @TeX{}: - -@example -@group -sin(a^2 / b_i) -\sin\left( {a^2 \over b_i} \right) -@end group -@end example -@tex -$$ \sin\left( a^2 \over b_i \right) $$ -@end tex -@sp 1 - -@example -@group -[(3, 4), 3:4, 3 +/- 4, [3 .. inf)] -[3 + 4i, @{3 \over 4@}, 3 \pm 4, [3 \ldots \infty)] -@end group -@end example -@tex -$$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$ -@end tex -@sp 1 - -@example -@group -[abs(a), abs(a / b), floor(a), ceil(a / b)] -[|a|, \left| a \over b \right|, - \lfloor a \rfloor, \left\lceil a \over b \right\rceil] -@end group -@end example -@tex -$$ [|a|, \left| a \over b \right|, - \lfloor a \rfloor, \left\lceil a \over b \right\rceil] $$ -@end tex -@sp 1 - -@example -@group -[sin(a), sin(2 a), sin(2 + a), sin(a / b)] -[\sin@{a@}, \sin@{2 a@}, \sin(2 + a), - \sin\left( @{a \over b@} \right)] -@end group -@end example -@tex -$$ [\sin{a}, \sin{2 a}, \sin(2 + a), \sin\left( {a \over b} \right)] $$ -@end tex -@sp 2 - -First with plain @kbd{d T}, then with @kbd{C-u d T}, then finally with -@kbd{C-u - d T} (using the example definition -@samp{\def\foo#1@{\tilde F(#1)@}}: - -@example -@group -[f(a), foo(bar), sin(pi)] -[f(a), foo(bar), \sin{\pi}] -[f(a), \hbox@{foo@}(\hbox@{bar@}), \sin@{\pi@}] -[f(a), \foo@{\hbox@{bar@}@}, \sin@{\pi@}] -@end group -@end example -@tex -$$ [f(a), foo(bar), \sin{\pi}] $$ -$$ [f(a), \hbox{foo}(\hbox{bar}), \sin{\pi}] $$ -$$ [f(a), \tilde F(\hbox{bar}), \sin{\pi}] $$ -@end tex -@sp 2 - -First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}: - -@example -@group -2 + 3 => 5 -\evalto 2 + 3 \to 5 -@end group -@end example -@tex -$$ 2 + 3 \to 5 $$ -$$ 5 $$ -@end tex -@sp 2 - -First with standard @code{\to}, then with @samp{\let\to\Rightarrow}: - -@example -@group -[2 + 3 => 5, a / 2 => (b + c) / 2] -[@{2 + 3 \to 5@}, @{@{a \over 2@} \to @{b + c \over 2@}@}] -@end group -@end example -@tex -$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$ -{\let\to\Rightarrow -$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$} -@end tex -@sp 2 - -Matrices normally, then changing @code{\matrix} to @code{\pmatrix}: - -@example -@group -[ [ a / b, 0 ], [ 0, 2^(x + 1) ] ] -\matrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} -\pmatrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} -@end group -@end example -@tex -$$ \matrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ -$$ \pmatrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ -@end tex -@sp 2 -@end iftex - -@node Eqn Language Mode, Yacas Language Mode, TeX and LaTeX Language Modes, Language Modes -@subsection Eqn Language Mode - -@noindent -@kindex d E -@pindex calc-eqn-language -@dfn{Eqn} is another popular formatter for math formulas. It is -designed for use with the TROFF text formatter, and comes standard -with many versions of Unix. The @kbd{d E} (@code{calc-eqn-language}) -command selects @dfn{eqn} notation. - -The @dfn{eqn} language's main idiosyncrasy is that whitespace plays -a significant part in the parsing of the language. For example, -@samp{sqrt x+1 + y} treats @samp{x+1} as the argument of the -@code{sqrt} operator. @dfn{Eqn} also understands more conventional -grouping using curly braces: @samp{sqrt@{x+1@} + y}. Braces are -required only when the argument contains spaces. - -In Calc's @dfn{eqn} mode, however, curly braces are required to -delimit arguments of operators like @code{sqrt}. The first of the -above examples would treat only the @samp{x} as the argument of -@code{sqrt}, and in fact @samp{sin x+1} would be interpreted as -@samp{sin * x + 1}, because @code{sin} is not a special operator -in the @dfn{eqn} language. If you always surround the argument -with curly braces, Calc will never misunderstand. - -Calc also understands parentheses as grouping characters. Another -peculiarity of @dfn{eqn}'s syntax makes it advisable to separate -words with spaces from any surrounding characters that aren't curly -braces, so Calc writes @samp{sin ( x + y )} in @dfn{eqn} mode. -(The spaces around @code{sin} are important to make @dfn{eqn} -recognize that @code{sin} should be typeset in a roman font, and -the spaces around @code{x} and @code{y} are a good idea just in -case the @dfn{eqn} document has defined special meanings for these -names, too.) - -Powers and subscripts are written with the @code{sub} and @code{sup} -operators, respectively. Note that the caret symbol @samp{^} is -treated the same as a space in @dfn{eqn} mode, as is the @samp{~} -symbol (these are used to introduce spaces of various widths into -the typeset output of @dfn{eqn}). - -As in @LaTeX{} mode, Calc's formatter omits parentheses around the -arguments of functions like @code{ln} and @code{sin} if they are -``simple-looking''; in this case Calc surrounds the argument with -braces, separated by a @samp{~} from the function name: @samp{sin~@{x@}}. - -Font change codes (like @samp{roman @var{x}}) and positioning codes -(like @samp{~} and @samp{down @var{n} @var{x}}) are ignored by the -@dfn{eqn} reader. Also ignored are the words @code{left}, @code{right}, -@code{mark}, and @code{lineup}. Quotation marks in @dfn{eqn} mode input -are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to -@samp{sqrt @{1+x@}}; this is only an approximation to the true meaning -of quotes in @dfn{eqn}, but it is good enough for most uses. - -Accent codes (@samp{@var{x} dot}) are handled by treating them as -function calls (@samp{dot(@var{x})}) internally. -@xref{TeX and LaTeX Language Modes}, for a table of these accent -functions. The @code{prime} accent is treated specially if it occurs on -a variable or function name: @samp{f prime prime @w{( x prime )}} is -stored internally as @samp{f'@w{'}(x')}. For example, taking the -derivative of @samp{f(2 x)} with @kbd{a d x} will produce @samp{2 f'(2 -x)}, which @dfn{eqn} mode will display as @samp{2 f prime ( 2 x )}. - -Assignments are written with the @samp{<-} (left-arrow) symbol, -and @code{evalto} operators are written with @samp{->} or -@samp{evalto ... ->} (@pxref{TeX and LaTeX Language Modes}, for a discussion -of this). The regular Calc symbols @samp{:=} and @samp{=>} are also -recognized for these operators during reading. - -Vectors in @dfn{eqn} mode use regular Calc square brackets, but -matrices are formatted as @samp{matrix @{ ccol @{ a above b @} ... @}}. -The words @code{lcol} and @code{rcol} are recognized as synonyms -for @code{ccol} during input, and are generated instead of @code{ccol} -if the matrix justification mode so specifies. - -@node Yacas Language Mode, Maxima Language Mode, Eqn Language Mode, Language Modes -@subsection Yacas Language Mode - -@noindent -@kindex d Y -@pindex calc-yacas-language -@cindex Yacas language -The @kbd{d Y} (@code{calc-yacas-language}) command selects the -conventions of Yacas, a free computer algebra system. While the -operators and functions in Yacas are similar to those of Calc, the names -of built-in functions in Yacas are capitalized. The Calc formula -@samp{sin(2 x)}, for example, is entered and displayed @samp{Sin(2 x)} -in Yacas mode, and `@samp{arcsin(x^2)} is @samp{ArcSin(x^2)} in Yacas -mode. Complex numbers are written are written @samp{3 + 4 I}. -The standard special constants are written @code{Pi}, @code{E}, -@code{I}, @code{GoldenRatio} and @code{Gamma}. @code{Infinity} -represents both @code{inf} and @code{uinf}, and @code{Undefined} -represents @code{nan}. - -Certain operators on functions, such as @code{D} for differentiation -and @code{Integrate} for integration, take a prefix form in Yacas. For -example, the derivative of @w{@samp{e^x sin(x)}} can be computed with -@w{@samp{D(x) Exp(x)*Sin(x)}}. - -Other notable differences between Yacas and standard Calc expressions -are that vectors and matrices use curly braces in Yacas, and subscripts -use square brackets. If, for example, @samp{A} represents the list -@samp{@{a,2,c,4@}}, then @samp{A[3]} would equal @samp{c}. - - -@node Maxima Language Mode, Giac Language Mode, Yacas Language Mode, Language Modes -@subsection Maxima Language Mode - -@noindent -@kindex d X -@pindex calc-maxima-language -@cindex Maxima language -The @kbd{d X} (@code{calc-maxima-language}) command selects the -conventions of Maxima, another free computer algebra system. The -function names in Maxima are similar, but not always identical, to Calc. -For example, instead of @samp{arcsin(x)}, Maxima will use -@samp{asin(x)}. Complex numbers are written @samp{3 + 4 %i}. The -standard special constants are written @code{%pi}, @code{%e}, -@code{%i}, @code{%phi} and @code{%gamma}. In Maxima, @code{inf} means -the same as in Calc, but @code{infinity} represents Calc's @code{uinf}. - -Underscores as well as percent signs are allowed in function and -variable names in Maxima mode. The underscore again is equivalent to -the @samp{#} in Normal mode, and the percent sign is equivalent to -@samp{o'o}. - -Maxima uses square brackets for lists and vectors, and matrices are -written as calls to the function @code{matrix}, given the row vectors of -the matrix as arguments. Square brackets are also used as subscripts. - -@node Giac Language Mode, Mathematica Language Mode, Maxima Language Mode, Language Modes -@subsection Giac Language Mode - -@noindent -@kindex d A -@pindex calc-giac-language -@cindex Giac language -The @kbd{d A} (@code{calc-giac-language}) command selects the -conventions of Giac, another free computer algebra system. The function -names in Giac are similar to Maxima. Complex numbers are written -@samp{3 + 4 i}. The standard special constants in Giac are the same as -in Calc, except that @code{infinity} represents both Calc's @code{inf} -and @code{uinf}. - -Underscores are allowed in function and variable names in Giac mode. -Brackets are used for subscripts. In Giac, indexing of lists begins at -0, instead of 1 as in Calc. So if @samp{A} represents the list -@samp{[a,2,c,4]}, then @samp{A[2]} would equal @samp{c}. In general, -@samp{A[n]} in Giac mode corresponds to @samp{A_(n+1)} in Normal mode. - -The Giac interval notation @samp{2 .. 3} has no surrounding brackets; -Calc reads @samp{2 .. 3} as the closed interval @samp{[2 .. 3]} and -writes any kind of interval as @samp{2 .. 3}. This means you cannot see -the difference between an open and a closed interval while in Giac mode. - -@node Mathematica Language Mode, Maple Language Mode, Giac Language Mode, Language Modes -@subsection Mathematica Language Mode - -@noindent -@kindex d M -@pindex calc-mathematica-language -@cindex Mathematica language -The @kbd{d M} (@code{calc-mathematica-language}) command selects the -conventions of Mathematica. Notable differences in Mathematica mode -are that the names of built-in functions are capitalized, and function -calls use square brackets instead of parentheses. Thus the Calc -formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in -Mathematica mode. - -Vectors and matrices use curly braces in Mathematica. Complex numbers -are written @samp{3 + 4 I}. The standard special constants in Calc are -written @code{Pi}, @code{E}, @code{I}, @code{GoldenRatio}, @code{EulerGamma}, -@code{Infinity}, @code{ComplexInfinity}, and @code{Indeterminate} in -Mathematica mode. -Non-decimal numbers are written, e.g., @samp{16^^7fff}. Floating-point -numbers in scientific notation are written @samp{1.23*10.^3}. -Subscripts use double square brackets: @samp{a[[i]]}. - -@node Maple Language Mode, Compositions, Mathematica Language Mode, Language Modes -@subsection Maple Language Mode - -@noindent -@kindex d W -@pindex calc-maple-language -@cindex Maple language -The @kbd{d W} (@code{calc-maple-language}) command selects the -conventions of Maple. - -Maple's language is much like C@. Underscores are allowed in symbol -names; square brackets are used for subscripts; explicit @samp{*}s for -multiplications are required. Use either @samp{^} or @samp{**} to -denote powers. - -Maple uses square brackets for lists and curly braces for sets. Calc -interprets both notations as vectors, and displays vectors with square -brackets. This means Maple sets will be converted to lists when they -pass through Calc. As a special case, matrices are written as calls -to the function @code{matrix}, given a list of lists as the argument, -and can be read in this form or with all-capitals @code{MATRIX}. - -The Maple interval notation @samp{2 .. 3} is like Giac's interval -notation, and is handled the same by Calc. - -Maple writes complex numbers as @samp{3 + 4*I}. Its special constants -are @code{Pi}, @code{E}, @code{I}, and @code{infinity} (all three of -@code{inf}, @code{uinf}, and @code{nan} display as @code{infinity}). -Floating-point numbers are written @samp{1.23*10.^3}. - -Among things not currently handled by Calc's Maple mode are the -various quote symbols, procedures and functional operators, and -inert (@samp{&}) operators. - -@node Compositions, Syntax Tables, Maple Language Mode, Language Modes -@subsection Compositions - -@noindent -@cindex Compositions -There are several @dfn{composition functions} which allow you to get -displays in a variety of formats similar to those in Big language -mode. Most of these functions do not evaluate to anything; they are -placeholders which are left in symbolic form by Calc's evaluator but -are recognized by Calc's display formatting routines. - -Two of these, @code{string} and @code{bstring}, are described elsewhere. -@xref{Strings}. For example, @samp{string("ABC")} is displayed as -@samp{ABC}. When viewed on the stack it will be indistinguishable from -the variable @code{ABC}, but internally it will be stored as -@samp{string([65, 66, 67])} and can still be manipulated this way; for -example, the selection and vector commands @kbd{j 1 v v j u} would -select the vector portion of this object and reverse the elements, then -deselect to reveal a string whose characters had been reversed. - -The composition functions do the same thing in all language modes -(although their components will of course be formatted in the current -language mode). The one exception is Unformatted mode (@kbd{d U}), -which does not give the composition functions any special treatment. -The functions are discussed here because of their relationship to -the language modes. - -@menu -* Composition Basics:: -* Horizontal Compositions:: -* Vertical Compositions:: -* Other Compositions:: -* Information about Compositions:: -* User-Defined Compositions:: -@end menu - -@node Composition Basics, Horizontal Compositions, Compositions, Compositions -@subsubsection Composition Basics - -@noindent -Compositions are generally formed by stacking formulas together -horizontally or vertically in various ways. Those formulas are -themselves compositions. @TeX{} users will find this analogous -to @TeX{}'s ``boxes.'' Each multi-line composition has a -@dfn{baseline}; horizontal compositions use the baselines to -decide how formulas should be positioned relative to one another. -For example, in the Big mode formula - -@example -@group - 2 - a + b -17 + ------ - c -@end group -@end example - -@noindent -the second term of the sum is four lines tall and has line three as -its baseline. Thus when the term is combined with 17, line three -is placed on the same level as the baseline of 17. - -@tex -\bigskip -@end tex - -Another important composition concept is @dfn{precedence}. This is -an integer that represents the binding strength of various operators. -For example, @samp{*} has higher precedence (195) than @samp{+} (180), -which means that @samp{(a * b) + c} will be formatted without the -parentheses, but @samp{a * (b + c)} will keep the parentheses. - -The operator table used by normal and Big language modes has the -following precedences: - -@example -_ 1200 @r{(subscripts)} -% 1100 @r{(as in n}%@r{)} -! 1000 @r{(as in }!@r{n)} -mod 400 -+/- 300 -!! 210 @r{(as in n}!!@r{)} -! 210 @r{(as in n}!@r{)} -^ 200 -- 197 @r{(as in }-@r{n)} -* 195 @r{(or implicit multiplication)} -/ % \ 190 -+ - 180 @r{(as in a}+@r{b)} -| 170 -< = 160 @r{(and other relations)} -&& 110 -|| 100 -? : 90 -!!! 85 -&&& 80 -||| 75 -:= 50 -:: 45 -=> 40 -@end example - -The general rule is that if an operator with precedence @expr{n} -occurs as an argument to an operator with precedence @expr{m}, then -the argument is enclosed in parentheses if @expr{n < m}. Top-level -expressions and expressions which are function arguments, vector -components, etc., are formatted with precedence zero (so that they -normally never get additional parentheses). - -For binary left-associative operators like @samp{+}, the righthand -argument is actually formatted with one-higher precedence than shown -in the table. This makes sure @samp{(a + b) + c} omits the parentheses, -but the unnatural form @samp{a + (b + c)} keeps its parentheses. -Right-associative operators like @samp{^} format the lefthand argument -with one-higher precedence. - -@ignore -@starindex -@end ignore -@tindex cprec -The @code{cprec} function formats an expression with an arbitrary -precedence. For example, @samp{cprec(abc, 185)} will combine into -sums and products as follows: @samp{7 + abc}, @samp{7 (abc)} (because -this @code{cprec} form has higher precedence than addition, but lower -precedence than multiplication). - -@tex -\bigskip -@end tex - -A final composition issue is @dfn{line breaking}. Calc uses two -different strategies for ``flat'' and ``non-flat'' compositions. -A non-flat composition is anything that appears on multiple lines -(not counting line breaking). Examples would be matrices and Big -mode powers and quotients. Non-flat compositions are displayed -exactly as specified. If they come out wider than the current -window, you must use horizontal scrolling (@kbd{<} and @kbd{>}) to -view them. - -Flat compositions, on the other hand, will be broken across several -lines if they are too wide to fit the window. Certain points in a -composition are noted internally as @dfn{break points}. Calc's -general strategy is to fill each line as much as possible, then to -move down to the next line starting at the first break point that -didn't fit. However, the line breaker understands the hierarchical -structure of formulas. It will not break an ``inner'' formula if -it can use an earlier break point from an ``outer'' formula instead. -For example, a vector of sums might be formatted as: - -@example -@group -[ a + b + c, d + e + f, - g + h + i, j + k + l, m ] -@end group -@end example - -@noindent -If the @samp{m} can fit, then so, it seems, could the @samp{g}. -But Calc prefers to break at the comma since the comma is part -of a ``more outer'' formula. Calc would break at a plus sign -only if it had to, say, if the very first sum in the vector had -itself been too large to fit. - -Of the composition functions described below, only @code{choriz} -generates break points. The @code{bstring} function (@pxref{Strings}) -also generates breakable items: A break point is added after every -space (or group of spaces) except for spaces at the very beginning or -end of the string. - -Composition functions themselves count as levels in the formula -hierarchy, so a @code{choriz} that is a component of a larger -@code{choriz} will be less likely to be broken. As a special case, -if a @code{bstring} occurs as a component of a @code{choriz} or -@code{choriz}-like object (such as a vector or a list of arguments -in a function call), then the break points in that @code{bstring} -will be on the same level as the break points of the surrounding -object. - -@node Horizontal Compositions, Vertical Compositions, Composition Basics, Compositions -@subsubsection Horizontal Compositions - -@noindent -@ignore -@starindex -@end ignore -@tindex choriz -The @code{choriz} function takes a vector of objects and composes -them horizontally. For example, @samp{choriz([17, a b/c, d])} formats -as @w{@samp{17a b / cd}} in Normal language mode, or as - -@example -@group - a b -17---d - c -@end group -@end example - -@noindent -in Big language mode. This is actually one case of the general -function @samp{choriz(@var{vec}, @var{sep}, @var{prec})}, where -either or both of @var{sep} and @var{prec} may be omitted. -@var{Prec} gives the @dfn{precedence} to use when formatting -each of the components of @var{vec}. The default precedence is -the precedence from the surrounding environment. - -@var{Sep} is a string (i.e., a vector of character codes as might -be entered with @code{" "} notation) which should separate components -of the composition. Also, if @var{sep} is given, the line breaker -will allow lines to be broken after each occurrence of @var{sep}. -If @var{sep} is omitted, the composition will not be breakable -(unless any of its component compositions are breakable). - -For example, @samp{2 choriz([a, b c, d = e], " + ", 180)} is -formatted as @samp{2 a + b c + (d = e)}. To get the @code{choriz} -to have precedence 180 ``outwards'' as well as ``inwards,'' -enclose it in a @code{cprec} form: @samp{2 cprec(choriz(...), 180)} -formats as @samp{2 (a + b c + (d = e))}. - -The baseline of a horizontal composition is the same as the -baselines of the component compositions, which are all aligned. - -@node Vertical Compositions, Other Compositions, Horizontal Compositions, Compositions -@subsubsection Vertical Compositions - -@noindent -@ignore -@starindex -@end ignore -@tindex cvert -The @code{cvert} function makes a vertical composition. Each -component of the vector is centered in a column. The baseline of -the result is by default the top line of the resulting composition. -For example, @samp{f(cvert([a, bb, ccc]), cvert([a^2 + 1, b^2]))} -formats in Big mode as - -@example -@group -f( a , 2 ) - bb a + 1 - ccc 2 - b -@end group -@end example - -@ignore -@starindex -@end ignore -@tindex cbase -There are several special composition functions that work only as -components of a vertical composition. The @code{cbase} function -controls the baseline of the vertical composition; the baseline -will be the same as the baseline of whatever component is enclosed -in @code{cbase}. Thus @samp{f(cvert([a, cbase(bb), ccc]), -cvert([a^2 + 1, cbase(b^2)]))} displays as - -@example -@group - 2 - a + 1 - a 2 -f(bb , b ) - ccc -@end group -@end example - -@ignore -@starindex -@end ignore -@tindex ctbase -@ignore -@starindex -@end ignore -@tindex cbbase -There are also @code{ctbase} and @code{cbbase} functions which -make the baseline of the vertical composition equal to the top -or bottom line (rather than the baseline) of that component. -Thus @samp{cvert([cbase(a / b)]) + cvert([ctbase(a / b)]) + -cvert([cbbase(a / b)])} gives - -@example -@group - a -a - -- + a + b -b - - b -@end group -@end example - -There should be only one @code{cbase}, @code{ctbase}, or @code{cbbase} -function in a given vertical composition. These functions can also -be written with no arguments: @samp{ctbase()} is a zero-height object -which means the baseline is the top line of the following item, and -@samp{cbbase()} means the baseline is the bottom line of the preceding -item. - -@ignore -@starindex -@end ignore -@tindex crule -The @code{crule} function builds a ``rule,'' or horizontal line, -across a vertical composition. By itself @samp{crule()} uses @samp{-} -characters to build the rule. You can specify any other character, -e.g., @samp{crule("=")}. The argument must be a character code or -vector of exactly one character code. It is repeated to match the -width of the widest item in the stack. For example, a quotient -with a thick line is @samp{cvert([a + 1, cbase(crule("=")), b^2])}: - -@example -@group -a + 1 -===== - 2 - b -@end group -@end example - -@ignore -@starindex -@end ignore -@tindex clvert -@ignore -@starindex -@end ignore -@tindex crvert -Finally, the functions @code{clvert} and @code{crvert} act exactly -like @code{cvert} except that the items are left- or right-justified -in the stack. Thus @samp{clvert([a, bb, ccc]) + crvert([a, bb, ccc])} -gives: - -@example -@group -a + a -bb bb -ccc ccc -@end group -@end example - -Like @code{choriz}, the vertical compositions accept a second argument -which gives the precedence to use when formatting the components. -Vertical compositions do not support separator strings. - -@node Other Compositions, Information about Compositions, Vertical Compositions, Compositions -@subsubsection Other Compositions - -@noindent -@ignore -@starindex -@end ignore -@tindex csup -The @code{csup} function builds a superscripted expression. For -example, @samp{csup(a, b)} looks the same as @samp{a^b} does in Big -language mode. This is essentially a horizontal composition of -@samp{a} and @samp{b}, where @samp{b} is shifted up so that its -bottom line is one above the baseline. - -@ignore -@starindex -@end ignore -@tindex csub -Likewise, the @code{csub} function builds a subscripted expression. -This shifts @samp{b} down so that its top line is one below the -bottom line of @samp{a} (note that this is not quite analogous to -@code{csup}). Other arrangements can be obtained by using -@code{choriz} and @code{cvert} directly. - -@ignore -@starindex -@end ignore -@tindex cflat -The @code{cflat} function formats its argument in ``flat'' mode, -as obtained by @samp{d O}, if the current language mode is normal -or Big. It has no effect in other language modes. For example, -@samp{a^(b/c)} is formatted by Big mode like @samp{csup(a, cflat(b/c))} -to improve its readability. - -@ignore -@starindex -@end ignore -@tindex cspace -The @code{cspace} function creates horizontal space. For example, -@samp{cspace(4)} is effectively the same as @samp{string(" ")}. -A second string (i.e., vector of characters) argument is repeated -instead of the space character. For example, @samp{cspace(4, "ab")} -looks like @samp{abababab}. If the second argument is not a string, -it is formatted in the normal way and then several copies of that -are composed together: @samp{cspace(4, a^2)} yields - -@example -@group - 2 2 2 2 -a a a a -@end group -@end example - -@noindent -If the number argument is zero, this is a zero-width object. - -@ignore -@starindex -@end ignore -@tindex cvspace -The @code{cvspace} function creates vertical space, or a vertical -stack of copies of a certain string or formatted object. The -baseline is the center line of the resulting stack. A numerical -argument of zero will produce an object which contributes zero -height if used in a vertical composition. - -@ignore -@starindex -@end ignore -@tindex ctspace -@ignore -@starindex -@end ignore -@tindex cbspace -There are also @code{ctspace} and @code{cbspace} functions which -create vertical space with the baseline the same as the baseline -of the top or bottom copy, respectively, of the second argument. -Thus @samp{cvspace(2, a/b) + ctspace(2, a/b) + cbspace(2, a/b)} -displays as: - -@example -@group - a - - -a b -- a a -b + - + - -a b b -- a -b - - b -@end group -@end example - -@node Information about Compositions, User-Defined Compositions, Other Compositions, Compositions -@subsubsection Information about Compositions - -@noindent -The functions in this section are actual functions; they compose their -arguments according to the current language and other display modes, -then return a certain measurement of the composition as an integer. - -@ignore -@starindex -@end ignore -@tindex cwidth -The @code{cwidth} function measures the width, in characters, of a -composition. For example, @samp{cwidth(a + b)} is 5, and -@samp{cwidth(a / b)} is 5 in Normal mode, 1 in Big mode, and 11 in -@TeX{} mode (for @samp{@{a \over b@}}). The argument may involve -the composition functions described in this section. - -@ignore -@starindex -@end ignore -@tindex cheight -The @code{cheight} function measures the height of a composition. -This is the total number of lines in the argument's printed form. - -@ignore -@starindex -@end ignore -@tindex cascent -@ignore -@starindex -@end ignore -@tindex cdescent -The functions @code{cascent} and @code{cdescent} measure the amount -of the height that is above (and including) the baseline, or below -the baseline, respectively. Thus @samp{cascent(@var{x}) + cdescent(@var{x})} -always equals @samp{cheight(@var{x})}. For a one-line formula like -@samp{a + b}, @code{cascent} returns 1 and @code{cdescent} returns 0. -For @samp{a / b} in Big mode, @code{cascent} returns 2 and @code{cdescent} -returns 1. The only formula for which @code{cascent} will return zero -is @samp{cvspace(0)} or equivalents. - -@node User-Defined Compositions, , Information about Compositions, Compositions -@subsubsection User-Defined Compositions - -@noindent -@kindex Z C -@pindex calc-user-define-composition -The @kbd{Z C} (@code{calc-user-define-composition}) command lets you -define the display format for any algebraic function. You provide a -formula containing a certain number of argument variables on the stack. -Any time Calc formats a call to the specified function in the current -language mode and with that number of arguments, Calc effectively -replaces the function call with that formula with the arguments -replaced. - -Calc builds the default argument list by sorting all the variable names -that appear in the formula into alphabetical order. You can edit this -argument list before pressing @key{RET} if you wish. Any variables in -the formula that do not appear in the argument list will be displayed -literally; any arguments that do not appear in the formula will not -affect the display at all. - -You can define formats for built-in functions, for functions you have -defined with @kbd{Z F} (@pxref{Algebraic Definitions}), or for functions -which have no definitions but are being used as purely syntactic objects. -You can define different formats for each language mode, and for each -number of arguments, using a succession of @kbd{Z C} commands. When -Calc formats a function call, it first searches for a format defined -for the current language mode (and number of arguments); if there is -none, it uses the format defined for the Normal language mode. If -neither format exists, Calc uses its built-in standard format for that -function (usually just @samp{@var{func}(@var{args})}). - -If you execute @kbd{Z C} with the number 0 on the stack instead of a -formula, any defined formats for the function in the current language -mode will be removed. The function will revert to its standard format. - -For example, the default format for the binomial coefficient function -@samp{choose(n, m)} in the Big language mode is - -@example -@group - n -( ) - m -@end group -@end example - -@noindent -You might prefer the notation, - -@example -@group - C -n m -@end group -@end example - -@noindent -To define this notation, first make sure you are in Big mode, -then put the formula - -@smallexample -choriz([cvert([cvspace(1), n]), C, cvert([cvspace(1), m])]) -@end smallexample - -@noindent -on the stack and type @kbd{Z C}. Answer the first prompt with -@code{choose}. The second prompt will be the default argument list -of @samp{(C m n)}. Edit this list to be @samp{(n m)} and press -@key{RET}. Now, try it out: For example, turn simplification -off with @kbd{m O} and enter @samp{choose(a,b) + choose(7,3)} -as an algebraic entry. - -@example -@group - C + C -a b 7 3 -@end group -@end example - -As another example, let's define the usual notation for Stirling -numbers of the first kind, @samp{stir1(n, m)}. This is just like -the regular format for binomial coefficients but with square brackets -instead of parentheses. - -@smallexample -choriz([string("["), cvert([n, cbase(cvspace(1)), m]), string("]")]) -@end smallexample - -Now type @kbd{Z C stir1 @key{RET}}, edit the argument list to -@samp{(n m)}, and type @key{RET}. - -The formula provided to @kbd{Z C} usually will involve composition -functions, but it doesn't have to. Putting the formula @samp{a + b + c} -onto the stack and typing @kbd{Z C foo @key{RET} @key{RET}} would define -the function @samp{foo(x,y,z)} to display like @samp{x + y + z}. -This ``sum'' will act exactly like a real sum for all formatting -purposes (it will be parenthesized the same, and so on). However -it will be computationally unrelated to a sum. For example, the -formula @samp{2 * foo(1, 2, 3)} will display as @samp{2 (1 + 2 + 3)}. -Operator precedences have caused the ``sum'' to be written in -parentheses, but the arguments have not actually been summed. -(Generally a display format like this would be undesirable, since -it can easily be confused with a real sum.) - -The special function @code{eval} can be used inside a @kbd{Z C} -composition formula to cause all or part of the formula to be -evaluated at display time. For example, if the formula is -@samp{a + eval(b + c)}, then @samp{foo(1, 2, 3)} will be displayed -as @samp{1 + 5}. Evaluation will use the default simplifications, -regardless of the current simplification mode. There are also -@code{evalsimp} and @code{evalextsimp} which simplify as if by -@kbd{a s} and @kbd{a e} (respectively). Note that these ``functions'' -operate only in the context of composition formulas (and also in -rewrite rules, where they serve a similar purpose; @pxref{Rewrite -Rules}). On the stack, a call to @code{eval} will be left in -symbolic form. - -It is not a good idea to use @code{eval} except as a last resort. -It can cause the display of formulas to be extremely slow. For -example, while @samp{eval(a + b)} might seem quite fast and simple, -there are several situations where it could be slow. For example, -@samp{a} and/or @samp{b} could be polar complex numbers, in which -case doing the sum requires trigonometry. Or, @samp{a} could be -the factorial @samp{fact(100)} which is unevaluated because you -have typed @kbd{m O}; @code{eval} will evaluate it anyway to -produce a large, unwieldy integer. - -You can save your display formats permanently using the @kbd{Z P} -command (@pxref{Creating User Keys}). - -@node Syntax Tables, , Compositions, Language Modes -@subsection Syntax Tables - -@noindent -@cindex Syntax tables -@cindex Parsing formulas, customized -Syntax tables do for input what compositions do for output: They -allow you to teach custom notations to Calc's formula parser. -Calc keeps a separate syntax table for each language mode. - -(Note that the Calc ``syntax tables'' discussed here are completely -unrelated to the syntax tables described in the Emacs manual.) - -@kindex Z S -@pindex calc-edit-user-syntax -The @kbd{Z S} (@code{calc-edit-user-syntax}) command edits the -syntax table for the current language mode. If you want your -syntax to work in any language, define it in the Normal language -mode. Type @kbd{C-c C-c} to finish editing the syntax table, or -@kbd{C-x k} to cancel the edit. The @kbd{m m} command saves all -the syntax tables along with the other mode settings; -@pxref{General Mode Commands}. - -@menu -* Syntax Table Basics:: -* Precedence in Syntax Tables:: -* Advanced Syntax Patterns:: -* Conditional Syntax Rules:: -@end menu - -@node Syntax Table Basics, Precedence in Syntax Tables, Syntax Tables, Syntax Tables -@subsubsection Syntax Table Basics - -@noindent -@dfn{Parsing} is the process of converting a raw string of characters, -such as you would type in during algebraic entry, into a Calc formula. -Calc's parser works in two stages. First, the input is broken down -into @dfn{tokens}, such as words, numbers, and punctuation symbols -like @samp{+}, @samp{:=}, and @samp{+/-}. Space between tokens is -ignored (except when it serves to separate adjacent words). Next, -the parser matches this string of tokens against various built-in -syntactic patterns, such as ``an expression followed by @samp{+} -followed by another expression'' or ``a name followed by @samp{(}, -zero or more expressions separated by commas, and @samp{)}.'' - -A @dfn{syntax table} is a list of user-defined @dfn{syntax rules}, -which allow you to specify new patterns to define your own -favorite input notations. Calc's parser always checks the syntax -table for the current language mode, then the table for the Normal -language mode, before it uses its built-in rules to parse an -algebraic formula you have entered. Each syntax rule should go on -its own line; it consists of a @dfn{pattern}, a @samp{:=} symbol, -and a Calc formula with an optional @dfn{condition}. (Syntax rules -resemble algebraic rewrite rules, but the notation for patterns is -completely different.) - -A syntax pattern is a list of tokens, separated by spaces. -Except for a few special symbols, tokens in syntax patterns are -matched literally, from left to right. For example, the rule, - -@example -foo ( ) := 2+3 -@end example - -@noindent -would cause Calc to parse the formula @samp{4+foo()*5} as if it -were @samp{4+(2+3)*5}. Notice that the parentheses were written -as two separate tokens in the rule. As a result, the rule works -for both @samp{foo()} and @w{@samp{foo ( )}}. If we had written -the rule as @samp{foo () := 2+3}, then Calc would treat @samp{()} -as a single, indivisible token, so that @w{@samp{foo( )}} would -not be recognized by the rule. (It would be parsed as a regular -zero-argument function call instead.) In fact, this rule would -also make trouble for the rest of Calc's parser: An unrelated -formula like @samp{bar()} would now be tokenized into @samp{bar ()} -instead of @samp{bar ( )}, so that the standard parser for function -calls would no longer recognize it! - -While it is possible to make a token with a mixture of letters -and punctuation symbols, this is not recommended. It is better to -break it into several tokens, as we did with @samp{foo()} above. - -The symbol @samp{#} in a syntax pattern matches any Calc expression. -On the righthand side, the things that matched the @samp{#}s can -be referred to as @samp{#1}, @samp{#2}, and so on (where @samp{#1} -matches the leftmost @samp{#} in the pattern). For example, these -rules match a user-defined function, prefix operator, infix operator, -and postfix operator, respectively: - -@example -foo ( # ) := myfunc(#1) -foo # := myprefix(#1) -# foo # := myinfix(#1,#2) -# foo := mypostfix(#1) -@end example - -Thus @samp{foo(3)} will parse as @samp{myfunc(3)}, and @samp{2+3 foo} -will parse as @samp{mypostfix(2+3)}. - -It is important to write the first two rules in the order shown, -because Calc tries rules in order from first to last. If the -pattern @samp{foo #} came first, it would match anything that could -match the @samp{foo ( # )} rule, since an expression in parentheses -is itself a valid expression. Thus the @w{@samp{foo ( # )}} rule would -never get to match anything. Likewise, the last two rules must be -written in the order shown or else @samp{3 foo 4} will be parsed as -@samp{mypostfix(3) * 4}. (Of course, the best way to avoid these -ambiguities is not to use the same symbol in more than one way at -the same time! In case you're not convinced, try the following -exercise: How will the above rules parse the input @samp{foo(3,4)}, -if at all? Work it out for yourself, then try it in Calc and see.) - -Calc is quite flexible about what sorts of patterns are allowed. -The only rule is that every pattern must begin with a literal -token (like @samp{foo} in the first two patterns above), or with -a @samp{#} followed by a literal token (as in the last two -patterns). After that, any mixture is allowed, although putting -two @samp{#}s in a row will not be very useful since two -expressions with nothing between them will be parsed as one -expression that uses implicit multiplication. - -As a more practical example, Maple uses the notation -@samp{sum(a(i), i=1..10)} for sums, which Calc's Maple mode doesn't -recognize at present. To handle this syntax, we simply add the -rule, - -@example -sum ( # , # = # .. # ) := sum(#1,#2,#3,#4) -@end example - -@noindent -to the Maple mode syntax table. As another example, C mode can't -read assignment operators like @samp{++} and @samp{*=}. We can -define these operators quite easily: - -@example -# *= # := muleq(#1,#2) -# ++ := postinc(#1) -++ # := preinc(#1) -@end example - -@noindent -To complete the job, we would use corresponding composition functions -and @kbd{Z C} to cause these functions to display in their respective -Maple and C notations. (Note that the C example ignores issues of -operator precedence, which are discussed in the next section.) - -You can enclose any token in quotes to prevent its usual -interpretation in syntax patterns: - -@example -# ":=" # := becomes(#1,#2) -@end example - -Quotes also allow you to include spaces in a token, although once -again it is generally better to use two tokens than one token with -an embedded space. To include an actual quotation mark in a quoted -token, precede it with a backslash. (This also works to include -backslashes in tokens.) - -@example -# "bad token" # "/\"\\" # := silly(#1,#2,#3) -@end example - -@noindent -This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}. - -The token @kbd{#} has a predefined meaning in Calc's formula parser; -it is not valid to use @samp{"#"} in a syntax rule. However, longer -tokens that include the @samp{#} character are allowed. Also, while -@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in -the syntax table will prevent those characters from working in their -usual ways (referring to stack entries and quoting strings, -respectively). - -Finally, the notation @samp{%%} anywhere in a syntax table causes -the rest of the line to be ignored as a comment. - -@node Precedence in Syntax Tables, Advanced Syntax Patterns, Syntax Table Basics, Syntax Tables -@subsubsection Precedence - -@noindent -Different operators are generally assigned different @dfn{precedences}. -By default, an operator defined by a rule like - -@example -# foo # := foo(#1,#2) -@end example - -@noindent -will have an extremely low precedence, so that @samp{2*3+4 foo 5 == 6} -will be parsed as @samp{(2*3+4) foo (5 == 6)}. To change the -precedence of an operator, use the notation @samp{#/@var{p}} in -place of @samp{#}, where @var{p} is an integer precedence level. -For example, 185 lies between the precedences for @samp{+} and -@samp{*}, so if we change this rule to - -@example -#/185 foo #/186 := foo(#1,#2) -@end example - -@noindent -then @samp{2+3 foo 4*5} will be parsed as @samp{2+(3 foo (4*5))}. -Also, because we've given the righthand expression slightly higher -precedence, our new operator will be left-associative: -@samp{1 foo 2 foo 3} will be parsed as @samp{(1 foo 2) foo 3}. -By raising the precedence of the lefthand expression instead, we -can create a right-associative operator. - -@xref{Composition Basics}, for a table of precedences of the -standard Calc operators. For the precedences of operators in other -language modes, look in the Calc source file @file{calc-lang.el}. - -@node Advanced Syntax Patterns, Conditional Syntax Rules, Precedence in Syntax Tables, Syntax Tables -@subsubsection Advanced Syntax Patterns - -@noindent -To match a function with a variable number of arguments, you could -write - -@example -foo ( # ) := myfunc(#1) -foo ( # , # ) := myfunc(#1,#2) -foo ( # , # , # ) := myfunc(#1,#2,#3) -@end example - -@noindent -but this isn't very elegant. To match variable numbers of items, -Calc uses some notations inspired regular expressions and the -``extended BNF'' style used by some language designers. - -@example -foo ( @{ # @}*, ) := apply(myfunc,#1) -@end example - -The token @samp{@{} introduces a repeated or optional portion. -One of the three tokens @samp{@}*}, @samp{@}+}, or @samp{@}?} -ends the portion. These will match zero or more, one or more, -or zero or one copies of the enclosed pattern, respectively. -In addition, @samp{@}*} and @samp{@}+} can be followed by a -separator token (with no space in between, as shown above). -Thus @samp{@{ # @}*,} matches nothing, or one expression, or -several expressions separated by commas. - -A complete @samp{@{ ... @}} item matches as a vector of the -items that matched inside it. For example, the above rule will -match @samp{foo(1,2,3)} to get @samp{apply(myfunc,[1,2,3])}. -The Calc @code{apply} function takes a function name and a vector -of arguments and builds a call to the function with those -arguments, so the net result is the formula @samp{myfunc(1,2,3)}. - -If the body of a @samp{@{ ... @}} contains several @samp{#}s -(or nested @samp{@{ ... @}} constructs), then the items will be -strung together into the resulting vector. If the body -does not contain anything but literal tokens, the result will -always be an empty vector. - -@example -foo ( @{ # , # @}+, ) := bar(#1) -foo ( @{ @{ # @}*, @}*; ) := matrix(#1) -@end example - -@noindent -will parse @samp{foo(1, 2, 3, 4)} as @samp{bar([1, 2, 3, 4])}, and -@samp{foo(1, 2; 3, 4)} as @samp{matrix([[1, 2], [3, 4]])}. Also, after -some thought it's easy to see how this pair of rules will parse -@samp{foo(1, 2, 3)} as @samp{matrix([[1, 2, 3]])}, since the first -rule will only match an even number of arguments. The rule - -@example -foo ( # @{ , # , # @}? ) := bar(#1,#2) -@end example - -@noindent -will parse @samp{foo(2,3,4)} as @samp{bar(2,[3,4])}, and -@samp{foo(2)} as @samp{bar(2,[])}. - -The notation @samp{@{ ... @}?.} (note the trailing period) works -just the same as regular @samp{@{ ... @}?}, except that it does not -count as an argument; the following two rules are equivalent: - -@example -foo ( # , @{ also @}? # ) := bar(#1,#3) -foo ( # , @{ also @}?. # ) := bar(#1,#2) -@end example - -@noindent -Note that in the first case the optional text counts as @samp{#2}, -which will always be an empty vector, but in the second case no -empty vector is produced. - -Another variant is @samp{@{ ... @}?$}, which means the body is -optional only at the end of the input formula. All built-in syntax -rules in Calc use this for closing delimiters, so that during -algebraic entry you can type @kbd{[sqrt(2), sqrt(3 @key{RET}}, omitting -the closing parenthesis and bracket. Calc does this automatically -for trailing @samp{)}, @samp{]}, and @samp{>} tokens in syntax -rules, but you can use @samp{@{ ... @}?$} explicitly to get -this effect with any token (such as @samp{"@}"} or @samp{end}). -Like @samp{@{ ... @}?.}, this notation does not count as an -argument. Conversely, you can use quotes, as in @samp{")"}, to -prevent a closing-delimiter token from being automatically treated -as optional. - -Calc's parser does not have full backtracking, which means some -patterns will not work as you might expect: - -@example -foo ( @{ # , @}? # , # ) := bar(#1,#2,#3) -@end example - -@noindent -Here we are trying to make the first argument optional, so that -@samp{foo(2,3)} parses as @samp{bar([],2,3)}. Unfortunately, Calc -first tries to match @samp{2,} against the optional part of the -pattern, finds a match, and so goes ahead to match the rest of the -pattern. Later on it will fail to match the second comma, but it -doesn't know how to go back and try the other alternative at that -point. One way to get around this would be to use two rules: - -@example -foo ( # , # , # ) := bar([#1],#2,#3) -foo ( # , # ) := bar([],#1,#2) -@end example - -More precisely, when Calc wants to match an optional or repeated -part of a pattern, it scans forward attempting to match that part. -If it reaches the end of the optional part without failing, it -``finalizes'' its choice and proceeds. If it fails, though, it -backs up and tries the other alternative. Thus Calc has ``partial'' -backtracking. A fully backtracking parser would go on to make sure -the rest of the pattern matched before finalizing the choice. - -@node Conditional Syntax Rules, , Advanced Syntax Patterns, Syntax Tables -@subsubsection Conditional Syntax Rules - -@noindent -It is possible to attach a @dfn{condition} to a syntax rule. For -example, the rules - -@example -foo ( # ) := ifoo(#1) :: integer(#1) -foo ( # ) := gfoo(#1) -@end example - -@noindent -will parse @samp{foo(3)} as @samp{ifoo(3)}, but will parse -@samp{foo(3.5)} and @samp{foo(x)} as calls to @code{gfoo}. Any -number of conditions may be attached; all must be true for the -rule to succeed. A condition is ``true'' if it evaluates to a -nonzero number. @xref{Logical Operations}, for a list of Calc -functions like @code{integer} that perform logical tests. - -The exact sequence of events is as follows: When Calc tries a -rule, it first matches the pattern as usual. It then substitutes -@samp{#1}, @samp{#2}, etc., in the conditions, if any. Next, the -conditions are simplified and evaluated in order from left to right, -using the algebraic simplifications (@pxref{Simplifying Formulas}). -Each result is true if it is a nonzero number, or an expression -that can be proven to be nonzero (@pxref{Declarations}). If the -results of all conditions are true, the expression (such as -@samp{ifoo(#1)}) has its @samp{#}s substituted, and that is the -result of the parse. If the result of any condition is false, Calc -goes on to try the next rule in the syntax table. - -Syntax rules also support @code{let} conditions, which operate in -exactly the same way as they do in algebraic rewrite rules. -@xref{Other Features of Rewrite Rules}, for details. A @code{let} -condition is always true, but as a side effect it defines a -variable which can be used in later conditions, and also in the -expression after the @samp{:=} sign: - -@example -foo ( # ) := hifoo(x) :: let(x := #1 + 0.5) :: dnumint(x) -@end example - -@noindent -The @code{dnumint} function tests if a value is numerically an -integer, i.e., either a true integer or an integer-valued float. -This rule will parse @code{foo} with a half-integer argument, -like @samp{foo(3.5)}, to a call like @samp{hifoo(4.)}. - -The lefthand side of a syntax rule @code{let} must be a simple -variable, not the arbitrary pattern that is allowed in rewrite -rules. - -The @code{matches} function is also treated specially in syntax -rule conditions (again, in the same way as in rewrite rules). -@xref{Matching Commands}. If the matching pattern contains -meta-variables, then those meta-variables may be used in later -conditions and in the result expression. The arguments to -@code{matches} are not evaluated in this situation. - -@example -sum ( # , # ) := sum(#1,a,b,c) :: matches(#2, a=[b..c]) -@end example - -@noindent -This is another way to implement the Maple mode @code{sum} notation. -In this approach, we allow @samp{#2} to equal the whole expression -@samp{i=1..10}. Then, we use @code{matches} to break it apart into -its components. If the expression turns out not to match the pattern, -the syntax rule will fail. Note that @kbd{Z S} always uses Calc's -Normal language mode for editing expressions in syntax rules, so we -must use regular Calc notation for the interval @samp{[b..c]} that -will correspond to the Maple mode interval @samp{1..10}. - -@node Modes Variable, Calc Mode Line, Language Modes, Mode Settings -@section The @code{Modes} Variable - -@noindent -@kindex m g -@pindex calc-get-modes -The @kbd{m g} (@code{calc-get-modes}) command pushes onto the stack -a vector of numbers that describes the various mode settings that -are in effect. With a numeric prefix argument, it pushes only the -@var{n}th mode, i.e., the @var{n}th element of this vector. Keyboard -macros can use the @kbd{m g} command to modify their behavior based -on the current mode settings. - -@cindex @code{Modes} variable -@vindex Modes -The modes vector is also available in the special variable -@code{Modes}. In other words, @kbd{m g} is like @kbd{s r Modes @key{RET}}. -It will not work to store into this variable; in fact, if you do, -@code{Modes} will cease to track the current modes. (The @kbd{m g} -command will continue to work, however.) - -In general, each number in this vector is suitable as a numeric -prefix argument to the associated mode-setting command. (Recall -that the @kbd{~} key takes a number from the stack and gives it as -a numeric prefix to the next command.) - -The elements of the modes vector are as follows: - -@enumerate -@item -Current precision. Default is 12; associated command is @kbd{p}. - -@item -Binary word size. Default is 32; associated command is @kbd{b w}. - -@item -Stack size (not counting the value about to be pushed by @kbd{m g}). -This is zero if @kbd{m g} is executed with an empty stack. - -@item -Number radix. Default is 10; command is @kbd{d r}. - -@item -Floating-point format. This is the number of digits, plus the -constant 0 for normal notation, 10000 for scientific notation, -20000 for engineering notation, or 30000 for fixed-point notation. -These codes are acceptable as prefix arguments to the @kbd{d n} -command, but note that this may lose information: For example, -@kbd{d s} and @kbd{C-u 12 d s} have similar (but not quite -identical) effects if the current precision is 12, but they both -produce a code of 10012, which will be treated by @kbd{d n} as -@kbd{C-u 12 d s}. If the precision then changes, the float format -will still be frozen at 12 significant figures. - -@item -Angular mode. Default is 1 (degrees). Other values are 2 (radians) -and 3 (HMS). The @kbd{m d} command accepts these prefixes. - -@item -Symbolic mode. Value is 0 or 1; default is 0. Command is @kbd{m s}. - -@item -Fraction mode. Value is 0 or 1; default is 0. Command is @kbd{m f}. - -@item -Polar mode. Value is 0 (rectangular) or 1 (polar); default is 0. -Command is @kbd{m p}. - -@item -Matrix/Scalar mode. Default value is @mathit{-1}. Value is 0 for Scalar -mode, @mathit{-2} for Matrix mode, @mathit{-3} for square Matrix mode, -or @var{N} for -@texline @math{N\times N} -@infoline @var{N}x@var{N} -Matrix mode. Command is @kbd{m v}. - -@item -Simplification mode. Default is 1. Value is @mathit{-1} for off (@kbd{m O}), -0 for @kbd{m N}, 2 for @kbd{m B}, 3 for @kbd{m A}, 4 for @kbd{m E}, -or 5 for @w{@kbd{m U}}. The @kbd{m D} command accepts these prefixes. - -@item -Infinite mode. Default is @mathit{-1} (off). Value is 1 if the mode is on, -or 0 if the mode is on with positive zeros. Command is @kbd{m i}. -@end enumerate - -For example, the sequence @kbd{M-1 m g @key{RET} 2 + ~ p} increases the -precision by two, leaving a copy of the old precision on the stack. -Later, @kbd{~ p} will restore the original precision using that -stack value. (This sequence might be especially useful inside a -keyboard macro.) - -As another example, @kbd{M-3 m g 1 - ~ @key{DEL}} deletes all but the -oldest (bottommost) stack entry. - -Yet another example: The HP-48 ``round'' command rounds a number -to the current displayed precision. You could roughly emulate this -in Calc with the sequence @kbd{M-5 m g 10000 % ~ c c}. (This -would not work for fixed-point mode, but it wouldn't be hard to -do a full emulation with the help of the @kbd{Z [} and @kbd{Z ]} -programming commands. @xref{Conditionals in Macros}.) - -@node Calc Mode Line, , Modes Variable, Mode Settings -@section The Calc Mode Line - -@noindent -@cindex Mode line indicators -This section is a summary of all symbols that can appear on the -Calc mode line, the highlighted bar that appears under the Calc -stack window (or under an editing window in Embedded mode). - -The basic mode line format is: - -@example ---%*-Calc: 12 Deg @var{other modes} (Calculator) -@end example - -The @samp{%*} indicates that the buffer is ``read-only''; it shows that -regular Emacs commands are not allowed to edit the stack buffer -as if it were text. - -The word @samp{Calc:} changes to @samp{CalcEmbed:} if Embedded mode -is enabled. The words after this describe the various Calc modes -that are in effect. - -The first mode is always the current precision, an integer. -The second mode is always the angular mode, either @code{Deg}, -@code{Rad}, or @code{Hms}. - -Here is a complete list of the remaining symbols that can appear -on the mode line: - -@table @code -@item Alg -Algebraic mode (@kbd{m a}; @pxref{Algebraic Entry}). - -@item Alg[( -Incomplete algebraic mode (@kbd{C-u m a}). - -@item Alg* -Total algebraic mode (@kbd{m t}). - -@item Symb -Symbolic mode (@kbd{m s}; @pxref{Symbolic Mode}). - -@item Matrix -Matrix mode (@kbd{m v}; @pxref{Matrix Mode}). - -@item Matrix@var{n} -Dimensioned Matrix mode (@kbd{C-u @var{n} m v}; @pxref{Matrix Mode}). - -@item SqMatrix -Square Matrix mode (@kbd{C-u m v}; @pxref{Matrix Mode}). - -@item Scalar -Scalar mode (@kbd{m v}; @pxref{Matrix Mode}). - -@item Polar -Polar complex mode (@kbd{m p}; @pxref{Polar Mode}). - -@item Frac -Fraction mode (@kbd{m f}; @pxref{Fraction Mode}). - -@item Inf -Infinite mode (@kbd{m i}; @pxref{Infinite Mode}). - -@item +Inf -Positive Infinite mode (@kbd{C-u 0 m i}). - -@item NoSimp -Default simplifications off (@kbd{m O}; @pxref{Simplification Modes}). - -@item NumSimp -Default simplifications for numeric arguments only (@kbd{m N}). - -@item BinSimp@var{w} -Binary-integer simplification mode; word size @var{w} (@kbd{m B}, @kbd{b w}). - -@item BasicSimp -Basic simplification mode (@kbd{m I}). - -@item ExtSimp -Extended algebraic simplification mode (@kbd{m E}). - -@item UnitSimp -Units simplification mode (@kbd{m U}). - -@item Bin -Current radix is 2 (@kbd{d 2}; @pxref{Radix Modes}). - -@item Oct -Current radix is 8 (@kbd{d 8}). - -@item Hex -Current radix is 16 (@kbd{d 6}). - -@item Radix@var{n} -Current radix is @var{n} (@kbd{d r}). - -@item Zero -Leading zeros (@kbd{d z}; @pxref{Radix Modes}). - -@item Big -Big language mode (@kbd{d B}; @pxref{Normal Language Modes}). - -@item Flat -One-line normal language mode (@kbd{d O}). - -@item Unform -Unformatted language mode (@kbd{d U}). - -@item C -C language mode (@kbd{d C}; @pxref{C FORTRAN Pascal}). - -@item Pascal -Pascal language mode (@kbd{d P}). - -@item Fortran -FORTRAN language mode (@kbd{d F}). - -@item TeX -@TeX{} language mode (@kbd{d T}; @pxref{TeX and LaTeX Language Modes}). - -@item LaTeX -@LaTeX{} language mode (@kbd{d L}; @pxref{TeX and LaTeX Language Modes}). - -@item Eqn -@dfn{Eqn} language mode (@kbd{d E}; @pxref{Eqn Language Mode}). - -@item Math -Mathematica language mode (@kbd{d M}; @pxref{Mathematica Language Mode}). - -@item Maple -Maple language mode (@kbd{d W}; @pxref{Maple Language Mode}). - -@item Norm@var{n} -Normal float mode with @var{n} digits (@kbd{d n}; @pxref{Float Formats}). - -@item Fix@var{n} -Fixed point mode with @var{n} digits after the point (@kbd{d f}). - -@item Sci -Scientific notation mode (@kbd{d s}). - -@item Sci@var{n} -Scientific notation with @var{n} digits (@kbd{d s}). - -@item Eng -Engineering notation mode (@kbd{d e}). - -@item Eng@var{n} -Engineering notation with @var{n} digits (@kbd{d e}). - -@item Left@var{n} -Left-justified display indented by @var{n} (@kbd{d <}; @pxref{Justification}). - -@item Right -Right-justified display (@kbd{d >}). - -@item Right@var{n} -Right-justified display with width @var{n} (@kbd{d >}). - -@item Center -Centered display (@kbd{d =}). - -@item Center@var{n} -Centered display with center column @var{n} (@kbd{d =}). - -@item Wid@var{n} -Line breaking with width @var{n} (@kbd{d b}; @pxref{Normal Language Modes}). - -@item Wide -No line breaking (@kbd{d b}). - -@item Break -Selections show deep structure (@kbd{j b}; @pxref{Making Selections}). - -@item Save -Record modes in @file{~/.emacs.d/calc.el} (@kbd{m R}; @pxref{General Mode Commands}). - -@item Local -Record modes in Embedded buffer (@kbd{m R}). - -@item LocEdit -Record modes as editing-only in Embedded buffer (@kbd{m R}). - -@item LocPerm -Record modes as permanent-only in Embedded buffer (@kbd{m R}). - -@item Global -Record modes as global in Embedded buffer (@kbd{m R}). - -@item Manual -Automatic recomputation turned off (@kbd{m C}; @pxref{Automatic -Recomputation}). - -@item Graph -GNUPLOT process is alive in background (@pxref{Graphics}). - -@item Sel -Top-of-stack has a selection (Embedded only; @pxref{Making Selections}). - -@item Dirty -The stack display may not be up-to-date (@pxref{Display Modes}). - -@item Inv -``Inverse'' prefix was pressed (@kbd{I}; @pxref{Inverse and Hyperbolic}). - -@item Hyp -``Hyperbolic'' prefix was pressed (@kbd{H}). - -@item Keep -``Keep-arguments'' prefix was pressed (@kbd{K}). - -@item Narrow -Stack is truncated (@kbd{d t}; @pxref{Truncating the Stack}). -@end table - -In addition, the symbols @code{Active} and @code{~Active} can appear -as minor modes on an Embedded buffer's mode line. @xref{Embedded Mode}. - -@node Arithmetic, Scientific Functions, Mode Settings, Top -@chapter Arithmetic Functions - -@noindent -This chapter describes the Calc commands for doing simple calculations -on numbers, such as addition, absolute value, and square roots. These -commands work by removing the top one or two values from the stack, -performing the desired operation, and pushing the result back onto the -stack. If the operation cannot be performed, the result pushed is a -formula instead of a number, such as @samp{2/0} (because division by zero -is invalid) or @samp{sqrt(x)} (because the argument @samp{x} is a formula). - -Most of the commands described here can be invoked by a single keystroke. -Some of the more obscure ones are two-letter sequences beginning with -the @kbd{f} (``functions'') prefix key. - -@xref{Prefix Arguments}, for a discussion of the effect of numeric -prefix arguments on commands in this chapter which do not otherwise -interpret a prefix argument. - -@menu -* Basic Arithmetic:: -* Integer Truncation:: -* Complex Number Functions:: -* Conversions:: -* Date Arithmetic:: -* Financial Functions:: -* Binary Functions:: -@end menu - -@node Basic Arithmetic, Integer Truncation, Arithmetic, Arithmetic -@section Basic Arithmetic - -@noindent -@kindex + -@pindex calc-plus -@ignore -@mindex @null -@end ignore -@tindex + -The @kbd{+} (@code{calc-plus}) command adds two numbers. The numbers may -be any of the standard Calc data types. The resulting sum is pushed back -onto the stack. - -If both arguments of @kbd{+} are vectors or matrices (of matching dimensions), -the result is a vector or matrix sum. If one argument is a vector and the -other a scalar (i.e., a non-vector), the scalar is added to each of the -elements of the vector to form a new vector. If the scalar is not a -number, the operation is left in symbolic form: Suppose you added @samp{x} -to the vector @samp{[1,2]}. You may want the result @samp{[1+x,2+x]}, or -you may plan to substitute a 2-vector for @samp{x} in the future. Since -the Calculator can't tell which interpretation you want, it makes the -safest assumption. @xref{Reducing and Mapping}, for a way to add @samp{x} -to every element of a vector. - -If either argument of @kbd{+} is a complex number, the result will in general -be complex. If one argument is in rectangular form and the other polar, -the current Polar mode determines the form of the result. If Symbolic -mode is enabled, the sum may be left as a formula if the necessary -conversions for polar addition are non-trivial. - -If both arguments of @kbd{+} are HMS forms, the forms are added according to -the usual conventions of hours-minutes-seconds notation. If one argument -is an HMS form and the other is a number, that number is converted from -degrees or radians (depending on the current Angular mode) to HMS format -and then the two HMS forms are added. - -If one argument of @kbd{+} is a date form, the other can be either a -real number, which advances the date by a certain number of days, or -an HMS form, which advances the date by a certain amount of time. -Subtracting two date forms yields the number of days between them. -Adding two date forms is meaningless, but Calc interprets it as the -subtraction of one date form and the negative of the other. (The -negative of a date form can be understood by remembering that dates -are stored as the number of days before or after Jan 1, 1 AD.) - -If both arguments of @kbd{+} are error forms, the result is an error form -with an appropriately computed standard deviation. If one argument is an -error form and the other is a number, the number is taken to have zero error. -Error forms may have symbolic formulas as their mean and/or error parts; -adding these will produce a symbolic error form result. However, adding an -error form to a plain symbolic formula (as in @samp{(a +/- b) + c}) will not -work, for the same reasons just mentioned for vectors. Instead you must -write @samp{(a +/- b) + (c +/- 0)}. - -If both arguments of @kbd{+} are modulo forms with equal values of @expr{M}, -or if one argument is a modulo form and the other a plain number, the -result is a modulo form which represents the sum, modulo @expr{M}, of -the two values. - -If both arguments of @kbd{+} are intervals, the result is an interval -which describes all possible sums of the possible input values. If -one argument is a plain number, it is treated as the interval -@w{@samp{[x ..@: x]}}. - -If one argument of @kbd{+} is an infinity and the other is not, the -result is that same infinity. If both arguments are infinite and in -the same direction, the result is the same infinity, but if they are -infinite in different directions the result is @code{nan}. - -@kindex - -@pindex calc-minus -@ignore -@mindex @null -@end ignore -@tindex - -The @kbd{-} (@code{calc-minus}) command subtracts two values. The top -number on the stack is subtracted from the one behind it, so that the -computation @kbd{5 @key{RET} 2 -} produces 3, not @mathit{-3}. All options -available for @kbd{+} are available for @kbd{-} as well. - -@kindex * -@pindex calc-times -@ignore -@mindex @null -@end ignore -@tindex * -The @kbd{*} (@code{calc-times}) command multiplies two numbers. If one -argument is a vector and the other a scalar, the scalar is multiplied by -the elements of the vector to produce a new vector. If both arguments -are vectors, the interpretation depends on the dimensions of the -vectors: If both arguments are matrices, a matrix multiplication is -done. If one argument is a matrix and the other a plain vector, the -vector is interpreted as a row vector or column vector, whichever is -dimensionally correct. If both arguments are plain vectors, the result -is a single scalar number which is the dot product of the two vectors. - -If one argument of @kbd{*} is an HMS form and the other a number, the -HMS form is multiplied by that amount. It is an error to multiply two -HMS forms together, or to attempt any multiplication involving date -forms. Error forms, modulo forms, and intervals can be multiplied; -see the comments for addition of those forms. When two error forms -or intervals are multiplied they are considered to be statistically -independent; thus, @samp{[-2 ..@: 3] * [-2 ..@: 3]} is @samp{[-6 ..@: 9]}, -whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}. - -@kindex / -@pindex calc-divide -@ignore -@mindex @null -@end ignore -@tindex / -The @kbd{/} (@code{calc-divide}) command divides two numbers. - -When combining multiplication and division in an algebraic formula, it -is good style to use parentheses to distinguish between possible -interpretations; the expression @samp{a/b*c} should be written -@samp{(a/b)*c} or @samp{a/(b*c)}, as appropriate. Without the -parentheses, Calc will interpret @samp{a/b*c} as @samp{a/(b*c)}, since -in algebraic entry Calc gives division a lower precedence than -multiplication. (This is not standard across all computer languages, and -Calc may change the precedence depending on the language mode being used. -@xref{Language Modes}.) This default ordering can be changed by setting -the customizable variable @code{calc-multiplication-has-precedence} to -@code{nil} (@pxref{Customizing Calc}); this will give multiplication and -division equal precedences. Note that Calc's default choice of -precedence allows @samp{a b / c d} to be used as a shortcut for -@smallexample -@group -a b ----. -c d -@end group -@end smallexample - -When dividing a scalar @expr{B} by a square matrix @expr{A}, the -computation performed is @expr{B} times the inverse of @expr{A}. This -also occurs if @expr{B} is itself a vector or matrix, in which case the -effect is to solve the set of linear equations represented by @expr{B}. -If @expr{B} is a matrix with the same number of rows as @expr{A}, or a -plain vector (which is interpreted here as a column vector), then the -equation @expr{A X = B} is solved for the vector or matrix @expr{X}. -Otherwise, if @expr{B} is a non-square matrix with the same number of -@emph{columns} as @expr{A}, the equation @expr{X A = B} is solved. If -you wish a vector @expr{B} to be interpreted as a row vector to be -solved as @expr{X A = B}, make it into a one-row matrix with @kbd{C-u 1 -v p} first. To force a left-handed solution with a square matrix -@expr{B}, transpose @expr{A} and @expr{B} before dividing, then -transpose the result. - -HMS forms can be divided by real numbers or by other HMS forms. Error -forms can be divided in any combination of ways. Modulo forms where both -values and the modulo are integers can be divided to get an integer modulo -form result. Intervals can be divided; dividing by an interval that -encompasses zero or has zero as a limit will result in an infinite -interval. - -@kindex ^ -@pindex calc-power -@ignore -@mindex @null -@end ignore -@tindex ^ -The @kbd{^} (@code{calc-power}) command raises a number to a power. If -the power is an integer, an exact result is computed using repeated -multiplications. For non-integer powers, Calc uses Newton's method or -logarithms and exponentials. Square matrices can be raised to integer -powers. If either argument is an error (or interval or modulo) form, -the result is also an error (or interval or modulo) form. - -@kindex I ^ -@tindex nroot -If you press the @kbd{I} (inverse) key first, the @kbd{I ^} command -computes an Nth root: @kbd{125 @key{RET} 3 I ^} computes the number 5. -(This is entirely equivalent to @kbd{125 @key{RET} 1:3 ^}.) - -@kindex \ -@pindex calc-idiv -@tindex idiv -@ignore -@mindex @null -@end ignore -@tindex \ -The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack -to produce an integer result. It is equivalent to dividing with -@key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit -more convenient and efficient. Also, since it is an all-integer -operation when the arguments are integers, it avoids problems that -@kbd{/ F} would have with floating-point roundoff. - -@kindex % -@pindex calc-mod -@ignore -@mindex @null -@end ignore -@tindex % -The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'') -operation. Mathematically, @samp{a%b = a - (a\b)*b}, and is defined -for all real numbers @expr{a} and @expr{b} (except @expr{b=0}). For -positive @expr{b}, the result will always be between 0 (inclusive) and -@expr{b} (exclusive). Modulo does not work for HMS forms and error forms. -If @expr{a} is a modulo form, its modulo is changed to @expr{b}, which -must be positive real number. - -@kindex : -@pindex calc-fdiv -@tindex fdiv -The @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command -divides the two integers on the top of the stack to produce a fractional -result. This is a convenient shorthand for enabling Fraction mode (with -@kbd{m f}) temporarily and using @samp{/}. Note that during numeric entry -the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6 -you would have to type @kbd{8 @key{RET} 6 @key{RET} :}. (Of course, in -this case, it would be much easier simply to enter the fraction directly -as @kbd{8:6 @key{RET}}!) - -@kindex n -@pindex calc-change-sign -The @kbd{n} (@code{calc-change-sign}) command negates the number on the top -of the stack. It works on numbers, vectors and matrices, HMS forms, date -forms, error forms, intervals, and modulo forms. - -@kindex A -@pindex calc-abs -@tindex abs -The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute -value of a number. The result of @code{abs} is always a nonnegative -real number: With a complex argument, it computes the complex magnitude. -With a vector or matrix argument, it computes the Frobenius norm, i.e., -the square root of the sum of the squares of the absolute values of the -elements. The absolute value of an error form is defined by replacing -the mean part with its absolute value and leaving the error part the same. -The absolute value of a modulo form is undefined. The absolute value of -an interval is defined in the obvious way. - -@kindex f A -@pindex calc-abssqr -@tindex abssqr -The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the -absolute value squared of a number, vector or matrix, or error form. - -@kindex f s -@pindex calc-sign -@tindex sign -The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its -argument is positive, @mathit{-1} if its argument is negative, or 0 if its -argument is zero. In algebraic form, you can also write @samp{sign(a,x)} -which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or -zero depending on the sign of @samp{a}. - -@kindex & -@pindex calc-inv -@tindex inv -@cindex Reciprocal -The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the -reciprocal of a number, i.e., @expr{1 / x}. Operating on a square -matrix, it computes the inverse of that matrix. - -@kindex Q -@pindex calc-sqrt -@tindex sqrt -The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square -root of a number. For a negative real argument, the result will be a -complex number whose form is determined by the current Polar mode. - -@kindex f h -@pindex calc-hypot -@tindex hypot -The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square -root of the sum of the squares of two numbers. That is, @samp{hypot(a,b)} -is the length of the hypotenuse of a right triangle with sides @expr{a} -and @expr{b}. If the arguments are complex numbers, their squared -magnitudes are used. - -@kindex f Q -@pindex calc-isqrt -@tindex isqrt -The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the -integer square root of an integer. This is the true square root of the -number, rounded down to an integer. For example, @samp{isqrt(10)} -produces 3. Note that, like @kbd{\} [@code{idiv}], this uses exact -integer arithmetic throughout to avoid roundoff problems. If the input -is a floating-point number or other non-integer value, this is exactly -the same as @samp{floor(sqrt(x))}. - -@kindex f n -@kindex f x -@pindex calc-min -@tindex min -@pindex calc-max -@tindex max -The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max}) -[@code{max}] commands take the minimum or maximum of two real numbers, -respectively. These commands also work on HMS forms, date forms, -intervals, and infinities. (In algebraic expressions, these functions -take any number of arguments and return the maximum or minimum among -all the arguments.) - -@kindex f M -@kindex f X -@pindex calc-mant-part -@tindex mant -@pindex calc-xpon-part -@tindex xpon -The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts -the ``mantissa'' part @expr{m} of its floating-point argument; @kbd{f X} -(@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part -@expr{e}. The original number is equal to -@texline @math{m \times 10^e}, -@infoline @expr{m * 10^e}, -where @expr{m} is in the interval @samp{[1.0 ..@: 10.0)} except that -@expr{m=e=0} if the original number is zero. For integers -and fractions, @code{mant} returns the number unchanged and @code{xpon} -returns zero. The @kbd{v u} (@code{calc-unpack}) command can also be -used to ``unpack'' a floating-point number; this produces an integer -mantissa and exponent, with the constraint that the mantissa is not -a multiple of ten (again except for the @expr{m=e=0} case). - -@kindex f S -@pindex calc-scale-float -@tindex scf -The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number -by a given power of ten. Thus, @samp{scf(mant(x), xpon(x)) = x} for any -real @samp{x}. The second argument must be an integer, but the first -may actually be any numeric value. For example, @samp{scf(5,-2) = 0.05} -or @samp{1:20} depending on the current Fraction mode. - -@kindex f [ -@kindex f ] -@pindex calc-decrement -@pindex calc-increment -@tindex decr -@tindex incr -The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]} -(@code{calc-increment}) [@code{incr}] functions decrease or increase -a number by one unit. For integers, the effect is obvious. For -floating-point numbers, the change is by one unit in the last place. -For example, incrementing @samp{12.3456} when the current precision -is 6 digits yields @samp{12.3457}. If the current precision had been -8 digits, the result would have been @samp{12.345601}. Incrementing -@samp{0.0} produces -@texline @math{10^{-p}}, -@infoline @expr{10^-p}, -where @expr{p} is the current -precision. These operations are defined only on integers and floats. -With numeric prefix arguments, they change the number by @expr{n} units. - -Note that incrementing followed by decrementing, or vice-versa, will -almost but not quite always cancel out. Suppose the precision is -6 digits and the number @samp{9.99999} is on the stack. Incrementing -will produce @samp{10.0000}; decrementing will produce @samp{9.9999}. -One digit has been dropped. This is an unavoidable consequence of the -way floating-point numbers work. - -Incrementing a date/time form adjusts it by a certain number of seconds. -Incrementing a pure date form adjusts it by a certain number of days. - -@node Integer Truncation, Complex Number Functions, Basic Arithmetic, Arithmetic -@section Integer Truncation - -@noindent -There are four commands for truncating a real number to an integer, -differing mainly in their treatment of negative numbers. All of these -commands have the property that if the argument is an integer, the result -is the same integer. An integer-valued floating-point argument is converted -to integer form. - -If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be -expressed as an integer-valued floating-point number. - -@cindex Integer part of a number -@kindex F -@pindex calc-floor -@tindex floor -@tindex ffloor -@ignore -@mindex @null -@end ignore -@kindex H F -The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command -truncates a real number to the next lower integer, i.e., toward minus -infinity. Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces -@mathit{-4}. - -@kindex I F -@pindex calc-ceiling -@tindex ceil -@tindex fceil -@ignore -@mindex @null -@end ignore -@kindex H I F -The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}] -command truncates toward positive infinity. Thus @kbd{3.6 I F} produces -4, and @kbd{_3.6 I F} produces @mathit{-3}. - -@kindex R -@pindex calc-round -@tindex round -@tindex fround -@ignore -@mindex @null -@end ignore -@kindex H R -The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command -rounds to the nearest integer. When the fractional part is .5 exactly, -this command rounds away from zero. (All other rounding in the -Calculator uses this convention as well.) Thus @kbd{3.5 R} produces 4 -but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @mathit{-4}. - -@kindex I R -@pindex calc-trunc -@tindex trunc -@tindex ftrunc -@ignore -@mindex @null -@end ignore -@kindex H I R -The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}] -command truncates toward zero. In other words, it ``chops off'' -everything after the decimal point. Thus @kbd{3.6 I R} produces 3 and -@kbd{_3.6 I R} produces @mathit{-3}. - -These functions may not be applied meaningfully to error forms, but they -do work for intervals. As a convenience, applying @code{floor} to a -modulo form floors the value part of the form. Applied to a vector, -these functions operate on all elements of the vector one by one. -Applied to a date form, they operate on the internal numerical -representation of dates, converting a date/time form into a pure date. - -@ignore -@starindex -@end ignore -@tindex rounde -@ignore -@starindex -@end ignore -@tindex roundu -@ignore -@starindex -@end ignore -@tindex frounde -@ignore -@starindex -@end ignore -@tindex froundu -There are two more rounding functions which can only be entered in -algebraic notation. The @code{roundu} function is like @code{round} -except that it rounds up, toward plus infinity, when the fractional -part is .5. This distinction matters only for negative arguments. -Also, @code{rounde} rounds to an even number in the case of a tie, -rounding up or down as necessary. For example, @samp{rounde(3.5)} and -@samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6. -The advantage of round-to-even is that the net error due to rounding -after a long calculation tends to cancel out to zero. An important -subtle point here is that the number being fed to @code{rounde} will -already have been rounded to the current precision before @code{rounde} -begins. For example, @samp{rounde(2.500001)} with a current precision -of 6 will incorrectly, or at least surprisingly, yield 2 because the -argument will first have been rounded down to @expr{2.5} (which -@code{rounde} sees as an exact tie between 2 and 3). - -Each of these functions, when written in algebraic formulas, allows -a second argument which specifies the number of digits after the -decimal point to keep. For example, @samp{round(123.4567, 2)} will -produce the answer 123.46, and @samp{round(123.4567, -1)} will -produce 120 (i.e., the cutoff is one digit to the @emph{left} of -the decimal point). A second argument of zero is equivalent to -no second argument at all. - -@cindex Fractional part of a number -To compute the fractional part of a number (i.e., the amount which, when -added to `@tfn{floor(}@var{n}@tfn{)}', will produce @var{n}) just take @var{n} -modulo 1 using the @code{%} command. - -Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm), -and @kbd{f Q} (integer square root) commands, which are analogous to -@kbd{/}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer -arguments and return the result rounded down to an integer. - -@node Complex Number Functions, Conversions, Integer Truncation, Arithmetic -@section Complex Number Functions - -@noindent -@kindex J -@pindex calc-conj -@tindex conj -The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the -complex conjugate of a number. For complex number @expr{a+bi}, the -complex conjugate is @expr{a-bi}. If the argument is a real number, -this command leaves it the same. If the argument is a vector or matrix, -this command replaces each element by its complex conjugate. - -@kindex G -@pindex calc-argument -@tindex arg -The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the -``argument'' or polar angle of a complex number. For a number in polar -notation, this is simply the second component of the pair -@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'. -@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'. -The result is expressed according to the current angular mode and will -be in the range @mathit{-180} degrees (exclusive) to @mathit{+180} degrees -(inclusive), or the equivalent range in radians. - -@pindex calc-imaginary -The @code{calc-imaginary} command multiplies the number on the -top of the stack by the imaginary number @expr{i = (0,1)}. This -command is not normally bound to a key in Calc, but it is available -on the @key{IMAG} button in Keypad mode. - -@kindex f r -@pindex calc-re -@tindex re -The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number -by its real part. This command has no effect on real numbers. (As an -added convenience, @code{re} applied to a modulo form extracts -the value part.) - -@kindex f i -@pindex calc-im -@tindex im -The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number -by its imaginary part; real numbers are converted to zero. With a vector -or matrix argument, these functions operate element-wise. - -@ignore -@mindex v p -@end ignore -@kindex v p (complex) -@kindex V p (complex) -@pindex calc-pack -The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on -the stack into a composite object such as a complex number. With -a prefix argument of @mathit{-1}, it produces a rectangular complex number; -with an argument of @mathit{-2}, it produces a polar complex number. -(Also, @pxref{Building Vectors}.) - -@ignore -@mindex v u -@end ignore -@kindex v u (complex) -@kindex V u (complex) -@pindex calc-unpack -The @kbd{v u} (@code{calc-unpack}) command takes the complex number -(or other composite object) on the top of the stack and unpacks it -into its separate components. - -@node Conversions, Date Arithmetic, Complex Number Functions, Arithmetic -@section Conversions - -@noindent -The commands described in this section convert numbers from one form -to another; they are two-key sequences beginning with the letter @kbd{c}. - -@kindex c f -@pindex calc-float -@tindex pfloat -The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the -number on the top of the stack to floating-point form. For example, -@expr{23} is converted to @expr{23.0}, @expr{3:2} is converted to -@expr{1.5}, and @expr{2.3} is left the same. If the value is a composite -object such as a complex number or vector, each of the components is -converted to floating-point. If the value is a formula, all numbers -in the formula are converted to floating-point. Note that depending -on the current floating-point precision, conversion to floating-point -format may lose information. - -As a special exception, integers which appear as powers or subscripts -are not floated by @kbd{c f}. If you really want to float a power, -you can use a @kbd{j s} command to select the power followed by @kbd{c f}. -Because @kbd{c f} cannot examine the formula outside of the selection, -it does not notice that the thing being floated is a power. -@xref{Selecting Subformulas}. - -The normal @kbd{c f} command is ``pervasive'' in the sense that it -applies to all numbers throughout the formula. The @code{pfloat} -algebraic function never stays around in a formula; @samp{pfloat(a + 1)} -changes to @samp{a + 1.0} as soon as it is evaluated. - -@kindex H c f -@tindex float -With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates -only on the number or vector of numbers at the top level of its -argument. Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)} -is left unevaluated because its argument is not a number. - -You should use @kbd{H c f} if you wish to guarantee that the final -value, once all the variables have been assigned, is a float; you -would use @kbd{c f} if you wish to do the conversion on the numbers -that appear right now. - -@kindex c F -@pindex calc-fraction -@tindex pfrac -The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a -floating-point number into a fractional approximation. By default, it -produces a fraction whose decimal representation is the same as the -input number, to within the current precision. You can also give a -numeric prefix argument to specify a tolerance, either directly, or, -if the prefix argument is zero, by using the number on top of the stack -as the tolerance. If the tolerance is a positive integer, the fraction -is correct to within that many significant figures. If the tolerance is -a non-positive integer, it specifies how many digits fewer than the current -precision to use. If the tolerance is a floating-point number, the -fraction is correct to within that absolute amount. - -@kindex H c F -@tindex frac -The @code{pfrac} function is pervasive, like @code{pfloat}. -There is also a non-pervasive version, @kbd{H c F} [@code{frac}], -which is analogous to @kbd{H c f} discussed above. - -@kindex c d -@pindex calc-to-degrees -@tindex deg -The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a -number into degrees form. The value on the top of the stack may be an -HMS form (interpreted as degrees-minutes-seconds), or a real number which -will be interpreted in radians regardless of the current angular mode. - -@kindex c r -@pindex calc-to-radians -@tindex rad -The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an -HMS form or angle in degrees into an angle in radians. - -@kindex c h -@pindex calc-to-hms -@tindex hms -The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real -number, interpreted according to the current angular mode, to an HMS -form describing the same angle. In algebraic notation, the @code{hms} -function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}. -(The three-argument version is independent of the current angular mode.) - -@pindex calc-from-hms -The @code{calc-from-hms} command converts the HMS form on the top of the -stack into a real number according to the current angular mode. - -@kindex c p -@kindex I c p -@pindex calc-polar -@tindex polar -@tindex rect -The @kbd{c p} (@code{calc-polar}) command converts the complex number on -the top of the stack from polar to rectangular form, or from rectangular -to polar form, whichever is appropriate. Real numbers are left the same. -This command is equivalent to the @code{rect} or @code{polar} -functions in algebraic formulas, depending on the direction of -conversion. (It uses @code{polar}, except that if the argument is -already a polar complex number, it uses @code{rect} instead. The -@kbd{I c p} command always uses @code{rect}.) - -@kindex c c -@pindex calc-clean -@tindex pclean -The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the -number on the top of the stack. Floating point numbers are re-rounded -according to the current precision. Polar numbers whose angular -components have strayed from the @mathit{-180} to @mathit{+180} degree range -are normalized. (Note that results will be undesirable if the current -angular mode is different from the one under which the number was -produced!) Integers and fractions are generally unaffected by this -operation. Vectors and formulas are cleaned by cleaning each component -number (i.e., pervasively). - -If the simplification mode is set below basic simplification, it is raised -for the purposes of this command. Thus, @kbd{c c} applies the basic -simplifications even if their automatic application is disabled. -@xref{Simplification Modes}. - -@cindex Roundoff errors, correcting -A numeric prefix argument to @kbd{c c} sets the floating-point precision -to that value for the duration of the command. A positive prefix (of at -least 3) sets the precision to the specified value; a negative or zero -prefix decreases the precision by the specified amount. - -@kindex c 0-9 -@pindex calc-clean-num -The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent -to @kbd{c c} with the corresponding negative prefix argument. If roundoff -errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one -decimal place often conveniently does the trick. - -The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0} -through @kbd{c 9} commands, also ``clip'' very small floating-point -numbers to zero. If the exponent is less than or equal to the negative -of the specified precision, the number is changed to 0.0. For example, -if the current precision is 12, then @kbd{c 2} changes the vector -@samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0, 0]}. -Numbers this small generally arise from roundoff noise. - -If the numbers you are using really are legitimately this small, -you should avoid using the @kbd{c 0} through @kbd{c 9} commands. -(The plain @kbd{c c} command rounds to the current precision but -does not clip small numbers.) - -One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with -a prefix argument, is that integer-valued floats are converted to -plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]} -produces @samp{[1, 1.5, 2, 2.5, 3]}. This is not done for huge -numbers (@samp{1e100} is technically an integer-valued float, but -you wouldn't want it automatically converted to a 100-digit integer). - -@kindex H c 0-9 -@kindex H c c -@tindex clean -With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9} -operate non-pervasively [@code{clean}]. - -@node Date Arithmetic, Financial Functions, Conversions, Arithmetic -@section Date Arithmetic - -@noindent -@cindex Date arithmetic, additional functions -The commands described in this section perform various conversions -and calculations involving date forms (@pxref{Date Forms}). They -use the @kbd{t} (for time/date) prefix key followed by shifted -letters. - -The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-} -commands. In particular, adding a number to a date form advances the -date form by a certain number of days; adding an HMS form to a date -form advances the date by a certain amount of time; and subtracting two -date forms produces a difference measured in days. The commands -described here provide additional, more specialized operations on dates. - -Many of these commands accept a numeric prefix argument; if you give -plain @kbd{C-u} as the prefix, these commands will instead take the -additional argument from the top of the stack. - -@menu -* Date Conversions:: -* Date Functions:: -* Time Zones:: -* Business Days:: -@end menu - -@node Date Conversions, Date Functions, Date Arithmetic, Date Arithmetic -@subsection Date Conversions - -@noindent -@kindex t D -@pindex calc-date -@tindex date -The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a -date form into a number, measured in days since Jan 1, 1 AD@. The -result will be an integer if @var{date} is a pure date form, or a -fraction or float if @var{date} is a date/time form. Or, if its -argument is a number, it converts this number into a date form. - -With a numeric prefix argument, @kbd{t D} takes that many objects -(up to six) from the top of the stack and interprets them in one -of the following ways: - -The @samp{date(@var{year}, @var{month}, @var{day})} function -builds a pure date form out of the specified year, month, and -day, which must all be integers. @var{Year} is a year number, -such as 1991 (@emph{not} the same as 91!). @var{Month} must be -an integer in the range 1 to 12; @var{day} must be in the range -1 to 31. If the specified month has fewer than 31 days and -@var{day} is too large, the equivalent day in the following -month will be used. - -The @samp{date(@var{month}, @var{day})} function builds a -pure date form using the current year, as determined by the -real-time clock. - -The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})} -function builds a date/time form using an @var{hms} form. - -The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour}, -@var{minute}, @var{second})} function builds a date/time form. -@var{hour} should be an integer in the range 0 to 23; -@var{minute} should be an integer in the range 0 to 59; -@var{second} should be any real number in the range @samp{[0 .. 60)}. -The last two arguments default to zero if omitted. - -@kindex t J -@pindex calc-julian -@tindex julian -@cindex Julian day counts, conversions -The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts -a date form into a Julian day count, which is the number of days -since noon (GMT) on Jan 1, 4713 BC@. A pure date is converted to an -integer Julian count representing noon of that day. A date/time form -is converted to an exact floating-point Julian count, adjusted to -interpret the date form in the current time zone but the Julian -day count in Greenwich Mean Time. A numeric prefix argument allows -you to specify the time zone; @pxref{Time Zones}. Use a prefix of -zero to suppress the time zone adjustment. Note that pure date forms -are never time-zone adjusted. - -This command can also do the opposite conversion, from a Julian day -count (either an integer day, or a floating-point day and time in -the GMT zone), into a pure date form or a date/time form in the -current or specified time zone. - -@kindex t U -@pindex calc-unix-time -@tindex unixtime -@cindex Unix time format, conversions -The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command -converts a date form into a Unix time value, which is the number of -seconds since midnight on Jan 1, 1970, or vice-versa. The numeric result -will be an integer if the current precision is 12 or less; for higher -precision, the result may be a float with (@var{precision}@minus{}12) -digits after the decimal. Just as for @kbd{t J}, the numeric time -is interpreted in the GMT time zone and the date form is interpreted -in the current or specified zone. Some systems use Unix-like -numbering but with the local time zone; give a prefix of zero to -suppress the adjustment if so. - -@kindex t C -@pindex calc-convert-time-zones -@tindex tzconv -@cindex Time Zones, converting between -The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}] -command converts a date form from one time zone to another. You -are prompted for each time zone name in turn; you can answer with -any suitable Calc time zone expression (@pxref{Time Zones}). -If you answer either prompt with a blank line, the local time -zone is used for that prompt. You can also answer the first -prompt with @kbd{$} to take the two time zone names from the -stack (and the date to be converted from the third stack level). - -@node Date Functions, Business Days, Date Conversions, Date Arithmetic -@subsection Date Functions - -@noindent -@kindex t N -@pindex calc-now -@tindex now -The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the -current date and time on the stack as a date form. The time is -reported in terms of the specified time zone; with no numeric prefix -argument, @kbd{t N} reports for the current time zone. - -@kindex t P -@pindex calc-date-part -The @kbd{t P} (@code{calc-date-part}) command extracts one part -of a date form. The prefix argument specifies the part; with no -argument, this command prompts for a part code from 1 to 9. -The various part codes are described in the following paragraphs. - -@tindex year -The @kbd{M-1 t P} [@code{year}] function extracts the year number -from a date form as an integer, e.g., 1991. This and the -following functions will also accept a real number for an -argument, which is interpreted as a standard Calc day number. -Note that this function will never return zero, since the year -1 BC immediately precedes the year 1 AD. - -@tindex month -The @kbd{M-2 t P} [@code{month}] function extracts the month number -from a date form as an integer in the range 1 to 12. - -@tindex day -The @kbd{M-3 t P} [@code{day}] function extracts the day number -from a date form as an integer in the range 1 to 31. - -@tindex hour -The @kbd{M-4 t P} [@code{hour}] function extracts the hour from -a date form as an integer in the range 0 (midnight) to 23. Note -that 24-hour time is always used. This returns zero for a pure -date form. This function (and the following two) also accept -HMS forms as input. - -@tindex minute -The @kbd{M-5 t P} [@code{minute}] function extracts the minute -from a date form as an integer in the range 0 to 59. - -@tindex second -The @kbd{M-6 t P} [@code{second}] function extracts the second -from a date form. If the current precision is 12 or less, -the result is an integer in the range 0 to 59. For higher -precision, the result may instead be a floating-point number. - -@tindex weekday -The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday -number from a date form as an integer in the range 0 (Sunday) -to 6 (Saturday). - -@tindex yearday -The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year -number from a date form as an integer in the range 1 (January 1) -to 366 (December 31 of a leap year). - -@tindex time -The @kbd{M-9 t P} [@code{time}] function extracts the time portion -of a date form as an HMS form. This returns @samp{0@@ 0' 0"} -for a pure date form. - -@kindex t M -@pindex calc-new-month -@tindex newmonth -The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command -computes a new date form that represents the first day of the month -specified by the input date. The result is always a pure date -form; only the year and month numbers of the input are retained. -With a numeric prefix argument @var{n} in the range from 1 to 31, -@kbd{t M} computes the @var{n}th day of the month. (If @var{n} -is greater than the actual number of days in the month, or if -@var{n} is zero, the last day of the month is used.) - -@kindex t Y -@pindex calc-new-year -@tindex newyear -The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command -computes a new pure date form that represents the first day of -the year specified by the input. The month, day, and time -of the input date form are lost. With a numeric prefix argument -@var{n} in the range from 1 to 366, @kbd{t Y} computes the -@var{n}th day of the year (366 is treated as 365 in non-leap -years). A prefix argument of 0 computes the last day of the -year (December 31). A negative prefix argument from @mathit{-1} to -@mathit{-12} computes the first day of the @var{n}th month of the year. - -@kindex t W -@pindex calc-new-week -@tindex newweek -The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command -computes a new pure date form that represents the Sunday on or before -the input date. With a numeric prefix argument, it can be made to -use any day of the week as the starting day; the argument must be in -the range from 0 (Sunday) to 6 (Saturday). This function always -subtracts between 0 and 6 days from the input date. - -Here's an example use of @code{newweek}: Find the date of the next -Wednesday after a given date. Using @kbd{M-3 t W} or @samp{newweek(d, 3)} -will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)} -will give you the following Wednesday. A further look at the definition -of @code{newweek} shows that if the input date is itself a Wednesday, -this formula will return the Wednesday one week in the future. An -exercise for the reader is to modify this formula to yield the same day -if the input is already a Wednesday. Another interesting exercise is -to preserve the time-of-day portion of the input (@code{newweek} resets -the time to midnight; hint: how can @code{newweek} be defined in terms -of the @code{weekday} function?). - -@ignore -@starindex -@end ignore -@tindex pwday -The @samp{pwday(@var{date})} function (not on any key) computes the -day-of-month number of the Sunday on or before @var{date}. With -two arguments, @samp{pwday(@var{date}, @var{day})} computes the day -number of the Sunday on or before day number @var{day} of the month -specified by @var{date}. The @var{day} must be in the range from -7 to 31; if the day number is greater than the actual number of days -in the month, the true number of days is used instead. Thus -@samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and -@samp{pwday(@var{date}, 31)} finds the last Sunday of the month. -With a third @var{weekday} argument, @code{pwday} can be made to look -for any day of the week instead of Sunday. - -@kindex t I -@pindex calc-inc-month -@tindex incmonth -The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command -increases a date form by one month, or by an arbitrary number of -months specified by a numeric prefix argument. The time portion, -if any, of the date form stays the same. The day also stays the -same, except that if the new month has fewer days the day -number may be reduced to lie in the valid range. For example, -@samp{incmonth()} produces @samp{}. -Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give -the same results (@samp{} versus @samp{} -in this case). - -@ignore -@starindex -@end ignore -@tindex incyear -The @samp{incyear(@var{date}, @var{step})} function increases -a date form by the specified number of years, which may be -any positive or negative integer. Note that @samp{incyear(d, n)} -is equivalent to @w{@samp{incmonth(d, 12*n)}}, but these do not have -simple equivalents in terms of day arithmetic because -months and years have varying lengths. If the @var{step} -argument is omitted, 1 year is assumed. There is no keyboard -command for this function; use @kbd{C-u 12 t I} instead. - -There is no @code{newday} function at all because @kbd{F} [@code{floor}] -serves this purpose. Similarly, instead of @code{incday} and -@code{incweek} simply use @expr{d + n} or @expr{d + 7 n}. - -@xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command -which can adjust a date/time form by a certain number of seconds. - -@node Business Days, Time Zones, Date Functions, Date Arithmetic -@subsection Business Days - -@noindent -Often time is measured in ``business days'' or ``working days,'' -where weekends and holidays are skipped. Calc's normal date -arithmetic functions use calendar days, so that subtracting two -consecutive Mondays will yield a difference of 7 days. By contrast, -subtracting two consecutive Mondays would yield 5 business days -(assuming two-day weekends and the absence of holidays). - -@kindex t + -@kindex t - -@tindex badd -@tindex bsub -@pindex calc-business-days-plus -@pindex calc-business-days-minus -The @kbd{t +} (@code{calc-business-days-plus}) [@code{badd}] -and @kbd{t -} (@code{calc-business-days-minus}) [@code{bsub}] -commands perform arithmetic using business days. For @kbd{t +}, -one argument must be a date form and the other must be a real -number (positive or negative). If the number is not an integer, -then a certain amount of time is added as well as a number of -days; for example, adding 0.5 business days to a time in Friday -evening will produce a time in Monday morning. It is also -possible to add an HMS form; adding @samp{12@@ 0' 0"} also adds -half a business day. For @kbd{t -}, the arguments are either a -date form and a number or HMS form, or two date forms, in which -case the result is the number of business days between the two -dates. - -@cindex @code{Holidays} variable -@vindex Holidays -By default, Calc considers any day that is not a Saturday or -Sunday to be a business day. You can define any number of -additional holidays by editing the variable @code{Holidays}. -(There is an @w{@kbd{s H}} convenience command for editing this -variable.) Initially, @code{Holidays} contains the vector -@samp{[sat, sun]}. Entries in the @code{Holidays} vector may -be any of the following kinds of objects: - -@itemize @bullet -@item -Date forms (pure dates, not date/time forms). These specify -particular days which are to be treated as holidays. - -@item -Intervals of date forms. These specify a range of days, all of -which are holidays (e.g., Christmas week). @xref{Interval Forms}. - -@item -Nested vectors of date forms. Each date form in the vector is -considered to be a holiday. - -@item -Any Calc formula which evaluates to one of the above three things. -If the formula involves the variable @expr{y}, it stands for a -yearly repeating holiday; @expr{y} will take on various year -numbers like 1992. For example, @samp{date(y, 12, 25)} specifies -Christmas day, and @samp{newweek(date(y, 11, 7), 4) + 21} specifies -Thanksgiving (which is held on the fourth Thursday of November). -If the formula involves the variable @expr{m}, that variable -takes on month numbers from 1 to 12: @samp{date(y, m, 15)} is -a holiday that takes place on the 15th of every month. - -@item -A weekday name, such as @code{sat} or @code{sun}. This is really -a variable whose name is a three-letter, lower-case day name. - -@item -An interval of year numbers (integers). This specifies the span of -years over which this holiday list is to be considered valid. Any -business-day arithmetic that goes outside this range will result -in an error message. Use this if you are including an explicit -list of holidays, rather than a formula to generate them, and you -want to make sure you don't accidentally go beyond the last point -where the holidays you entered are complete. If there is no -limiting interval in the @code{Holidays} vector, the default -@samp{[1 .. 2737]} is used. (This is the absolute range of years -for which Calc's business-day algorithms will operate.) - -@item -An interval of HMS forms. This specifies the span of hours that -are to be considered one business day. For example, if this -range is @samp{[9@@ 0' 0" .. 17@@ 0' 0"]} (i.e., 9am to 5pm), then -the business day is only eight hours long, so that @kbd{1.5 t +} -on @samp{<4:00pm Fri Dec 13, 1991>} will add one business day and -four business hours to produce @samp{<12:00pm Tue Dec 17, 1991>}. -Likewise, @kbd{t -} will now express differences in time as -fractions of an eight-hour day. Times before 9am will be treated -as 9am by business date arithmetic, and times at or after 5pm will -be treated as 4:59:59pm. If there is no HMS interval in @code{Holidays}, -the full 24-hour day @samp{[0@ 0' 0" .. 24@ 0' 0"]} is assumed. -(Regardless of the type of bounds you specify, the interval is -treated as inclusive on the low end and exclusive on the high end, -so that the work day goes from 9am up to, but not including, 5pm.) -@end itemize - -If the @code{Holidays} vector is empty, then @kbd{t +} and -@kbd{t -} will act just like @kbd{+} and @kbd{-} because there will -then be no difference between business days and calendar days. - -Calc expands the intervals and formulas you give into a complete -list of holidays for internal use. This is done mainly to make -sure it can detect multiple holidays. (For example, -@samp{} is both New Year's Day and a Sunday, but -Calc's algorithms take care to count it only once when figuring -the number of holidays between two dates.) - -Since the complete list of holidays for all the years from 1 to -2737 would be huge, Calc actually computes only the part of the -list between the smallest and largest years that have been involved -in business-day calculations so far. Normally, you won't have to -worry about this. Keep in mind, however, that if you do one -calculation for 1992, and another for 1792, even if both involve -only a small range of years, Calc will still work out all the -holidays that fall in that 200-year span. - -If you add a (positive) number of days to a date form that falls on a -weekend or holiday, the date form is treated as if it were the most -recent business day. (Thus adding one business day to a Friday, -Saturday, or Sunday will all yield the following Monday.) If you -subtract a number of days from a weekend or holiday, the date is -effectively on the following business day. (So subtracting one business -day from Saturday, Sunday, or Monday yields the preceding Friday.) The -difference between two dates one or both of which fall on holidays -equals the number of actual business days between them. These -conventions are consistent in the sense that, if you add @var{n} -business days to any date, the difference between the result and the -original date will come out to @var{n} business days. (It can't be -completely consistent though; a subtraction followed by an addition -might come out a bit differently, since @kbd{t +} is incapable of -producing a date that falls on a weekend or holiday.) - -@ignore -@starindex -@end ignore -@tindex holiday -There is a @code{holiday} function, not on any keys, that takes -any date form and returns 1 if that date falls on a weekend or -holiday, as defined in @code{Holidays}, or 0 if the date is a -business day. - -@node Time Zones, , Business Days, Date Arithmetic -@subsection Time Zones - -@noindent -@cindex Time zones -@cindex Daylight saving time -Time zones and daylight saving time are a complicated business. -The conversions to and from Julian and Unix-style dates automatically -compute the correct time zone and daylight saving adjustment to use, -provided they can figure out this information. This section describes -Calc's time zone adjustment algorithm in detail, in case you want to -do conversions in different time zones or in case Calc's algorithms -can't determine the right correction to use. - -Adjustments for time zones and daylight saving time are done by -@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other -commands. In particular, @samp{ - } evaluates -to exactly 30 days even though there is a daylight-saving -transition in between. This is also true for Julian pure dates: -@samp{julian() - julian()}. But Julian -and Unix date/times will adjust for daylight saving time: using Calc's -default daylight saving time rule (see the explanation below), -@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)} -evaluates to @samp{29.95833} (that's 29 days and 23 hours) -because one hour was lost when daylight saving commenced on -April 7, 1991. - -In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})} -computes the actual number of 24-hour periods between two dates, whereas -@samp{@var{date1} - @var{date2}} computes the number of calendar -days between two dates without taking daylight saving into account. - -@pindex calc-time-zone -@ignore -@starindex -@end ignore -@tindex tzone -The @code{calc-time-zone} [@code{tzone}] command converts the time -zone specified by its numeric prefix argument into a number of -seconds difference from Greenwich mean time (GMT). If the argument -is a number, the result is simply that value multiplied by 3600. -Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If -Daylight Saving time is in effect, one hour should be subtracted from -the normal difference. - -If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other -date arithmetic commands that include a time zone argument) takes the -zone argument from the top of the stack. (In the case of @kbd{t J} -and @kbd{t U}, the normal argument is then taken from the second-to-top -stack position.) This allows you to give a non-integer time zone -adjustment. The time-zone argument can also be an HMS form, or -it can be a variable which is a time zone name in upper- or lower-case. -For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)} -(for Pacific standard and daylight saving times, respectively). - -North American and European time zone names are defined as follows; -note that for each time zone there is one name for standard time, -another for daylight saving time, and a third for ``generalized'' time -in which the daylight saving adjustment is computed from context. - -@smallexample -@group -YST PST MST CST EST AST NST GMT WET MET MEZ - 9 8 7 6 5 4 3.5 0 -1 -2 -2 - -YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ - 8 7 6 5 4 3 2.5 -1 -2 -3 -3 - -YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ -9/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3 -@end group -@end smallexample - -@vindex math-tzone-names -To define time zone names that do not appear in the above table, -you must modify the Lisp variable @code{math-tzone-names}. This -is a list of lists describing the different time zone names; its -structure is best explained by an example. The three entries for -Pacific Time look like this: - -@smallexample -@group -( ( "PST" 8 0 ) ; Name as an upper-case string, then standard - ( "PDT" 8 -1 ) ; adjustment, then daylight saving adjustment. - ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone. -@end group -@end smallexample - -@cindex @code{TimeZone} variable -@vindex TimeZone -With no arguments, @code{calc-time-zone} or @samp{tzone()} will by -default get the time zone and daylight saving information from the -calendar (@pxref{Daylight Saving,Calendar/Diary,The Calendar and the Diary, -emacs,The GNU Emacs Manual}). To use a different time zone, or if the -calendar does not give the desired result, you can set the Calc variable -@code{TimeZone} (which is by default @code{nil}) to an appropriate -time zone name. (The easiest way to do this is to edit the -@code{TimeZone} variable using Calc's @kbd{s T} command, then use the -@kbd{s p} (@code{calc-permanent-variable}) command to save the value of -@code{TimeZone} permanently.) -If the time zone given by @code{TimeZone} is a generalized time zone, -e.g., @code{EGT}, Calc examines the date being converted to tell whether -to use standard or daylight saving time. But if the current time zone -is explicit, e.g., @code{EST} or @code{EDT}, then that adjustment is -used exactly and Calc's daylight saving algorithm is not consulted. -The special time zone name @code{local} -is equivalent to no argument; i.e., it uses the information obtained -from the calendar. - -The @kbd{t J} and @code{t U} commands with no numeric prefix -arguments do the same thing as @samp{tzone()}; namely, use the -information from the calendar if @code{TimeZone} is @code{nil}, -otherwise use the time zone given by @code{TimeZone}. - -@vindex math-daylight-savings-hook -@findex math-std-daylight-savings -When Calc computes the daylight saving information itself (i.e., when -the @code{TimeZone} variable is set), it will by default consider -daylight saving time to begin at 2 a.m.@: on the second Sunday of March -(for years from 2007 on) or on the last Sunday in April (for years -before 2007), and to end at 2 a.m.@: on the first Sunday of -November. (for years from 2007 on) or the last Sunday in October (for -years before 2007). These are the rules that have been in effect in -much of North America since 1966 and take into account the rule change -that began in 2007. If you are in a country that uses different rules -for computing daylight saving time, you have two choices: Write your own -daylight saving hook, or control time zones explicitly by setting the -@code{TimeZone} variable and/or always giving a time-zone argument for -the conversion functions. - -The Lisp variable @code{math-daylight-savings-hook} holds the -name of a function that is used to compute the daylight saving -adjustment for a given date. The default is -@code{math-std-daylight-savings}, which computes an adjustment -(either 0 or @mathit{-1}) using the North American rules given above. - -The daylight saving hook function is called with four arguments: -The date, as a floating-point number in standard Calc format; -a six-element list of the date decomposed into year, month, day, -hour, minute, and second, respectively; a string which contains -the generalized time zone name in upper-case, e.g., @code{"WEGT"}; -and a special adjustment to be applied to the hour value when -converting into a generalized time zone (see below). - -@findex math-prev-weekday-in-month -The Lisp function @code{math-prev-weekday-in-month} is useful for -daylight saving computations. This is an internal version of -the user-level @code{pwday} function described in the previous -section. It takes four arguments: The floating-point date value, -the corresponding six-element date list, the day-of-month number, -and the weekday number (0--6). - -The default daylight saving hook ignores the time zone name, but a -more sophisticated hook could use different algorithms for different -time zones. It would also be possible to use different algorithms -depending on the year number, but the default hook always uses the -algorithm for 1987 and later. Here is a listing of the default -daylight saving hook: - -@smallexample -(defun math-std-daylight-savings (date dt zone bump) - (cond ((< (nth 1 dt) 4) 0) - ((= (nth 1 dt) 4) - (let ((sunday (math-prev-weekday-in-month date dt 7 0))) - (cond ((< (nth 2 dt) sunday) 0) - ((= (nth 2 dt) sunday) - (if (>= (nth 3 dt) (+ 3 bump)) -1 0)) - (t -1)))) - ((< (nth 1 dt) 10) -1) - ((= (nth 1 dt) 10) - (let ((sunday (math-prev-weekday-in-month date dt 31 0))) - (cond ((< (nth 2 dt) sunday) -1) - ((= (nth 2 dt) sunday) - (if (>= (nth 3 dt) (+ 2 bump)) 0 -1)) - (t 0)))) - (t 0)) -) -@end smallexample - -@noindent -The @code{bump} parameter is equal to zero when Calc is converting -from a date form in a generalized time zone into a GMT date value. -It is @mathit{-1} when Calc is converting in the other direction. The -adjustments shown above ensure that the conversion behaves correctly -and reasonably around the 2 a.m.@: transition in each direction. - -There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the -beginning of daylight saving time; converting a date/time form that -falls in this hour results in a time value for the following hour, -from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the -hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time -form that falls in this hour results in a time value for the first -manifestation of that time (@emph{not} the one that occurs one hour -later). - -If @code{math-daylight-savings-hook} is @code{nil}, then the -daylight saving adjustment is always taken to be zero. - -In algebraic formulas, @samp{tzone(@var{zone}, @var{date})} -computes the time zone adjustment for a given zone name at a -given date. The @var{date} is ignored unless @var{zone} is a -generalized time zone. If @var{date} is a date form, the -daylight saving computation is applied to it as it appears. -If @var{date} is a numeric date value, it is adjusted for the -daylight-saving version of @var{zone} before being given to -the daylight saving hook. This odd-sounding rule ensures -that the daylight-saving computation is always done in -local time, not in the GMT time that a numeric @var{date} -is typically represented in. - -@ignore -@starindex -@end ignore -@tindex dsadj -The @samp{dsadj(@var{date}, @var{zone})} function computes the -daylight saving adjustment that is appropriate for @var{date} in -time zone @var{zone}. If @var{zone} is explicitly in or not in -daylight saving time (e.g., @code{PDT} or @code{PST}) the -@var{date} is ignored. If @var{zone} is a generalized time zone, -the algorithms described above are used. If @var{zone} is omitted, -the computation is done for the current time zone. - -@node Financial Functions, Binary Functions, Date Arithmetic, Arithmetic -@section Financial Functions - -@noindent -Calc's financial or business functions use the @kbd{b} prefix -key followed by a shifted letter. (The @kbd{b} prefix followed by -a lower-case letter is used for operations on binary numbers.) - -Note that the rate and the number of intervals given to these -functions must be on the same time scale, e.g., both months or -both years. Mixing an annual interest rate with a time expressed -in months will give you very wrong answers! - -It is wise to compute these functions to a higher precision than -you really need, just to make sure your answer is correct to the -last penny; also, you may wish to check the definitions at the end -of this section to make sure the functions have the meaning you expect. - -@menu -* Percentages:: -* Future Value:: -* Present Value:: -* Related Financial Functions:: -* Depreciation Functions:: -* Definitions of Financial Functions:: -@end menu - -@node Percentages, Future Value, Financial Functions, Financial Functions -@subsection Percentages - -@kindex M-% -@pindex calc-percent -@tindex % -@tindex percent -The @kbd{M-%} (@code{calc-percent}) command takes a percentage value, -say 5.4, and converts it to an equivalent actual number. For example, -@kbd{5.4 M-%} enters 0.054 on the stack. (That's the @key{META} or -@key{ESC} key combined with @kbd{%}.) - -Actually, @kbd{M-%} creates a formula of the form @samp{5.4%}. -You can enter @samp{5.4%} yourself during algebraic entry. The -@samp{%} operator simply means, ``the preceding value divided by -100.'' The @samp{%} operator has very high precedence, so that -@samp{1+8%} is interpreted as @samp{1+(8%)}, not as @samp{(1+8)%}. -(The @samp{%} operator is just a postfix notation for the -@code{percent} function, just like @samp{20!} is the notation for -@samp{fact(20)}, or twenty-factorial.) - -The formula @samp{5.4%} would normally evaluate immediately to -0.054, but the @kbd{M-%} command suppresses evaluation as it puts -the formula onto the stack. However, the next Calc command that -uses the formula @samp{5.4%} will evaluate it as its first step. -The net effect is that you get to look at @samp{5.4%} on the stack, -but Calc commands see it as @samp{0.054}, which is what they expect. - -In particular, @samp{5.4%} and @samp{0.054} are suitable values -for the @var{rate} arguments of the various financial functions, -but the number @samp{5.4} is probably @emph{not} suitable---it -represents a rate of 540 percent! - -The key sequence @kbd{M-% *} effectively means ``percent-of.'' -For example, @kbd{68 @key{RET} 25 M-% *} computes 17, which is 25% of -68 (and also 68% of 25, which comes out to the same thing). - -@kindex c % -@pindex calc-convert-percent -The @kbd{c %} (@code{calc-convert-percent}) command converts the -value on the top of the stack from numeric to percentage form. -For example, if 0.08 is on the stack, @kbd{c %} converts it to -@samp{8%}. The quantity is the same, it's just represented -differently. (Contrast this with @kbd{M-%}, which would convert -this number to @samp{0.08%}.) The @kbd{=} key is a convenient way -to convert a formula like @samp{8%} back to numeric form, 0.08. - -To compute what percentage one quantity is of another quantity, -use @kbd{/ c %}. For example, @w{@kbd{17 @key{RET} 68 / c %}} displays -@samp{25%}. - -@kindex b % -@pindex calc-percent-change -@tindex relch -The @kbd{b %} (@code{calc-percent-change}) [@code{relch}] command -calculates the percentage change from one number to another. -For example, @kbd{40 @key{RET} 50 b %} produces the answer @samp{25%}, -since 50 is 25% larger than 40. A negative result represents a -decrease: @kbd{50 @key{RET} 40 b %} produces @samp{-20%}, since 40 is -20% smaller than 50. (The answers are different in magnitude -because, in the first case, we're increasing by 25% of 40, but -in the second case, we're decreasing by 20% of 50.) The effect -of @kbd{40 @key{RET} 50 b %} is to compute @expr{(50-40)/40}, converting -the answer to percentage form as if by @kbd{c %}. - -@node Future Value, Present Value, Percentages, Financial Functions -@subsection Future Value - -@noindent -@kindex b F -@pindex calc-fin-fv -@tindex fv -The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes -the future value of an investment. It takes three arguments -from the stack: @samp{fv(@var{rate}, @var{n}, @var{payment})}. -If you give payments of @var{payment} every year for @var{n} -years, and the money you have paid earns interest at @var{rate} per -year, then this function tells you what your investment would be -worth at the end of the period. (The actual interval doesn't -have to be years, as long as @var{n} and @var{rate} are expressed -in terms of the same intervals.) This function assumes payments -occur at the @emph{end} of each interval. - -@kindex I b F -@tindex fvb -The @kbd{I b F} [@code{fvb}] command does the same computation, -but assuming your payments are at the beginning of each interval. -Suppose you plan to deposit $1000 per year in a savings account -earning 5.4% interest, starting right now. How much will be -in the account after five years? @code{fvb(5.4%, 5, 1000) = 5870.73}. -Thus you will have earned $870 worth of interest over the years. -Using the stack, this calculation would have been -@kbd{5.4 M-% 5 @key{RET} 1000 I b F}. Note that the rate is expressed -as a number between 0 and 1, @emph{not} as a percentage. - -@kindex H b F -@tindex fvl -The @kbd{H b F} [@code{fvl}] command computes the future value -of an initial lump sum investment. Suppose you could deposit -those five thousand dollars in the bank right now; how much would -they be worth in five years? @code{fvl(5.4%, 5, 5000) = 6503.89}. - -The algebraic functions @code{fv} and @code{fvb} accept an optional -fourth argument, which is used as an initial lump sum in the sense -of @code{fvl}. In other words, @code{fv(@var{rate}, @var{n}, -@var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment}) -+ fvl(@var{rate}, @var{n}, @var{initial})}. - -To illustrate the relationships between these functions, we could -do the @code{fvb} calculation ``by hand'' using @code{fvl}. The -final balance will be the sum of the contributions of our five -deposits at various times. The first deposit earns interest for -five years: @code{fvl(5.4%, 5, 1000) = 1300.78}. The second -deposit only earns interest for four years: @code{fvl(5.4%, 4, 1000) = -1234.13}. And so on down to the last deposit, which earns one -year's interest: @code{fvl(5.4%, 1, 1000) = 1054.00}. The sum of -these five values is, sure enough, $5870.73, just as was computed -by @code{fvb} directly. - -What does @code{fv(5.4%, 5, 1000) = 5569.96} mean? The payments -are now at the ends of the periods. The end of one year is the same -as the beginning of the next, so what this really means is that we've -lost the payment at year zero (which contributed $1300.78), but we're -now counting the payment at year five (which, since it didn't have -a chance to earn interest, counts as $1000). Indeed, @expr{5569.96 = -5870.73 - 1300.78 + 1000} (give or take a bit of roundoff error). - -@node Present Value, Related Financial Functions, Future Value, Financial Functions -@subsection Present Value - -@noindent -@kindex b P -@pindex calc-fin-pv -@tindex pv -The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes -the present value of an investment. Like @code{fv}, it takes -three arguments: @code{pv(@var{rate}, @var{n}, @var{payment})}. -It computes the present value of a series of regular payments. -Suppose you have the chance to make an investment that will -pay $2000 per year over the next four years; as you receive -these payments you can put them in the bank at 9% interest. -You want to know whether it is better to make the investment, or -to keep the money in the bank where it earns 9% interest right -from the start. The calculation @code{pv(9%, 4, 2000)} gives the -result 6479.44. If your initial investment must be less than this, -say, $6000, then the investment is worthwhile. But if you had to -put up $7000, then it would be better just to leave it in the bank. - -Here is the interpretation of the result of @code{pv}: You are -trying to compare the return from the investment you are -considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with -the return from leaving the money in the bank, which is -@code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money -you would have to put up in advance. The @code{pv} function -finds the break-even point, @expr{x = 6479.44}, at which -@code{fvl(9%, 4, 6479.44)} is also equal to 9146.26. This is -the largest amount you should be willing to invest. - -@kindex I b P -@tindex pvb -The @kbd{I b P} [@code{pvb}] command solves the same problem, -but with payments occurring at the beginning of each interval. -It has the same relationship to @code{fvb} as @code{pv} has -to @code{fv}. For example @code{pvb(9%, 4, 2000) = 7062.59}, -a larger number than @code{pv} produced because we get to start -earning interest on the return from our investment sooner. - -@kindex H b P -@tindex pvl -The @kbd{H b P} [@code{pvl}] command computes the present value of -an investment that will pay off in one lump sum at the end of the -period. For example, if we get our $8000 all at the end of the -four years, @code{pvl(9%, 4, 8000) = 5667.40}. This is much -less than @code{pv} reported, because we don't earn any interest -on the return from this investment. Note that @code{pvl} and -@code{fvl} are simple inverses: @code{fvl(9%, 4, 5667.40) = 8000}. - -You can give an optional fourth lump-sum argument to @code{pv} -and @code{pvb}; this is handled in exactly the same way as the -fourth argument for @code{fv} and @code{fvb}. - -@kindex b N -@pindex calc-fin-npv -@tindex npv -The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes -the net present value of a series of irregular investments. -The first argument is the interest rate. The second argument is -a vector which represents the expected return from the investment -at the end of each interval. For example, if the rate represents -a yearly interest rate, then the vector elements are the return -from the first year, second year, and so on. - -Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}. -Obviously this function is more interesting when the payments are -not all the same! - -The @code{npv} function can actually have two or more arguments. -Multiple arguments are interpreted in the same way as for the -vector statistical functions like @code{vsum}. -@xref{Single-Variable Statistics}. Basically, if there are several -payment arguments, each either a vector or a plain number, all these -values are collected left-to-right into the complete list of payments. -A numeric prefix argument on the @kbd{b N} command says how many -payment values or vectors to take from the stack. - -@kindex I b N -@tindex npvb -The @kbd{I b N} [@code{npvb}] command computes the net present -value where payments occur at the beginning of each interval -rather than at the end. - -@node Related Financial Functions, Depreciation Functions, Present Value, Financial Functions -@subsection Related Financial Functions - -@noindent -The functions in this section are basically inverses of the -present value functions with respect to the various arguments. - -@kindex b M -@pindex calc-fin-pmt -@tindex pmt -The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes -the amount of periodic payment necessary to amortize a loan. -Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the -value of @var{payment} such that @code{pv(@var{rate}, @var{n}, -@var{payment}) = @var{amount}}. - -@kindex I b M -@tindex pmtb -The @kbd{I b M} [@code{pmtb}] command does the same computation -but using @code{pvb} instead of @code{pv}. Like @code{pv} and -@code{pvb}, these functions can also take a fourth argument which -represents an initial lump-sum investment. - -@kindex H b M -The @kbd{H b M} key just invokes the @code{fvl} function, which is -the inverse of @code{pvl}. There is no explicit @code{pmtl} function. - -@kindex b # -@pindex calc-fin-nper -@tindex nper -The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes -the number of regular payments necessary to amortize a loan. -Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals -the value of @var{n} such that @code{pv(@var{rate}, @var{n}, -@var{payment}) = @var{amount}}. If @var{payment} is too small -ever to amortize a loan for @var{amount} at interest rate @var{rate}, -the @code{nper} function is left in symbolic form. - -@kindex I b # -@tindex nperb -The @kbd{I b #} [@code{nperb}] command does the same computation -but using @code{pvb} instead of @code{pv}. You can give a fourth -lump-sum argument to these functions, but the computation will be -rather slow in the four-argument case. - -@kindex H b # -@tindex nperl -The @kbd{H b #} [@code{nperl}] command does the same computation -using @code{pvl}. By exchanging @var{payment} and @var{amount} you -can also get the solution for @code{fvl}. For example, -@code{nperl(8%, 2000, 1000) = 9.006}, so if you place $1000 in a -bank account earning 8%, it will take nine years to grow to $2000. - -@kindex b T -@pindex calc-fin-rate -@tindex rate -The @kbd{b T} (@code{calc-fin-rate}) [@code{rate}] command computes -the rate of return on an investment. This is also an inverse of @code{pv}: -@code{rate(@var{n}, @var{payment}, @var{amount})} computes the value of -@var{rate} such that @code{pv(@var{rate}, @var{n}, @var{payment}) = -@var{amount}}. The result is expressed as a formula like @samp{6.3%}. - -@kindex I b T -@kindex H b T -@tindex rateb -@tindex ratel -The @kbd{I b T} [@code{rateb}] and @kbd{H b T} [@code{ratel}] -commands solve the analogous equations with @code{pvb} or @code{pvl} -in place of @code{pv}. Also, @code{rate} and @code{rateb} can -accept an optional fourth argument just like @code{pv} and @code{pvb}. -To redo the above example from a different perspective, -@code{ratel(9, 2000, 1000) = 8.00597%}, which says you will need an -interest rate of 8% in order to double your account in nine years. - -@kindex b I -@pindex calc-fin-irr -@tindex irr -The @kbd{b I} (@code{calc-fin-irr}) [@code{irr}] command is the -analogous function to @code{rate} but for net present value. -Its argument is a vector of payments. Thus @code{irr(@var{payments})} -computes the @var{rate} such that @code{npv(@var{rate}, @var{payments}) = 0}; -this rate is known as the @dfn{internal rate of return}. - -@kindex I b I -@tindex irrb -The @kbd{I b I} [@code{irrb}] command computes the internal rate of -return assuming payments occur at the beginning of each period. - -@node Depreciation Functions, Definitions of Financial Functions, Related Financial Functions, Financial Functions -@subsection Depreciation Functions - -@noindent -The functions in this section calculate @dfn{depreciation}, which is -the amount of value that a possession loses over time. These functions -are characterized by three parameters: @var{cost}, the original cost -of the asset; @var{salvage}, the value the asset will have at the end -of its expected ``useful life''; and @var{life}, the number of years -(or other periods) of the expected useful life. - -There are several methods for calculating depreciation that differ in -the way they spread the depreciation over the lifetime of the asset. - -@kindex b S -@pindex calc-fin-sln -@tindex sln -The @kbd{b S} (@code{calc-fin-sln}) [@code{sln}] command computes the -``straight-line'' depreciation. In this method, the asset depreciates -by the same amount every year (or period). For example, -@samp{sln(12000, 2000, 5)} returns 2000. The asset costs $12000 -initially and will be worth $2000 after five years; it loses $2000 -per year. - -@kindex b Y -@pindex calc-fin-syd -@tindex syd -The @kbd{b Y} (@code{calc-fin-syd}) [@code{syd}] command computes the -accelerated ``sum-of-years'-digits'' depreciation. Here the depreciation -is higher during the early years of the asset's life. Since the -depreciation is different each year, @kbd{b Y} takes a fourth @var{period} -parameter which specifies which year is requested, from 1 to @var{life}. -If @var{period} is outside this range, the @code{syd} function will -return zero. - -@kindex b D -@pindex calc-fin-ddb -@tindex ddb -The @kbd{b D} (@code{calc-fin-ddb}) [@code{ddb}] command computes an -accelerated depreciation using the double-declining balance method. -It also takes a fourth @var{period} parameter. - -For symmetry, the @code{sln} function will accept a @var{period} -parameter as well, although it will ignore its value except that the -return value will as usual be zero if @var{period} is out of range. - -For example, pushing the vector @expr{[1,2,3,4,5]} (perhaps with @kbd{v x 5}) -and then mapping @kbd{V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$), -ddb(12000,2000,5,$)] @key{RET}} produces a matrix that allows us to compare -the three depreciation methods: - -@example -@group -[ [ 2000, 3333, 4800 ] - [ 2000, 2667, 2880 ] - [ 2000, 2000, 1728 ] - [ 2000, 1333, 592 ] - [ 2000, 667, 0 ] ] -@end group -@end example - -@noindent -(Values have been rounded to nearest integers in this figure.) -We see that @code{sln} depreciates by the same amount each year, -@kbd{syd} depreciates more at the beginning and less at the end, -and @kbd{ddb} weights the depreciation even more toward the beginning. - -Summing columns with @kbd{V R : +} yields @expr{[10000, 10000, 10000]}; -the total depreciation in any method is (by definition) the -difference between the cost and the salvage value. - -@node Definitions of Financial Functions, , Depreciation Functions, Financial Functions -@subsection Definitions - -@noindent -For your reference, here are the actual formulas used to compute -Calc's financial functions. - -Calc will not evaluate a financial function unless the @var{rate} or -@var{n} argument is known. However, @var{payment} or @var{amount} can -be a variable. Calc expands these functions according to the -formulas below for symbolic arguments only when you use the @kbd{a "} -(@code{calc-expand-formula}) command, or when taking derivatives or -integrals or solving equations involving the functions. - -@ifnottex -These formulas are shown using the conventions of Big display -mode (@kbd{d B}); for example, the formula for @code{fv} written -linearly is @samp{pmt * ((1 + rate)^n) - 1) / rate}. - -@example - n - (1 + rate) - 1 -fv(rate, n, pmt) = pmt * --------------- - rate - - n - ((1 + rate) - 1) (1 + rate) -fvb(rate, n, pmt) = pmt * ---------------------------- - rate - - n -fvl(rate, n, pmt) = pmt * (1 + rate) - - -n - 1 - (1 + rate) -pv(rate, n, pmt) = pmt * ---------------- - rate - - -n - (1 - (1 + rate) ) (1 + rate) -pvb(rate, n, pmt) = pmt * ----------------------------- - rate - - -n -pvl(rate, n, pmt) = pmt * (1 + rate) - - -1 -2 -3 -npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate) - - -1 -2 -npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate) - - -n - (amt - x * (1 + rate) ) * rate -pmt(rate, n, amt, x) = ------------------------------- - -n - 1 - (1 + rate) - - -n - (amt - x * (1 + rate) ) * rate -pmtb(rate, n, amt, x) = ------------------------------- - -n - (1 - (1 + rate) ) (1 + rate) - - amt * rate -nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate) - pmt - - amt * rate -nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate) - pmt * (1 + rate) - - amt -nperl(rate, pmt, amt) = - log(---, 1 + rate) - pmt - - 1/n - pmt -ratel(n, pmt, amt) = ------ - 1 - 1/n - amt - - cost - salv -sln(cost, salv, life) = ----------- - life - - (cost - salv) * (life - per + 1) -syd(cost, salv, life, per) = -------------------------------- - life * (life + 1) / 2 - - book * 2 -ddb(cost, salv, life, per) = --------, book = cost - depreciation so far - life -@end example -@end ifnottex -@tex -$$ \code{fv}(r, n, p) = p { (1 + r)^n - 1 \over r } $$ -$$ \code{fvb}(r, n, p) = p { ((1 + r)^n - 1) (1 + r) \over r } $$ -$$ \code{fvl}(r, n, p) = p (1 + r)^n $$ -$$ \code{pv}(r, n, p) = p { 1 - (1 + r)^{-n} \over r } $$ -$$ \code{pvb}(r, n, p) = p { (1 - (1 + r)^{-n}) (1 + r) \over r } $$ -$$ \code{pvl}(r, n, p) = p (1 + r)^{-n} $$ -$$ \code{npv}(r, [a,b,c]) = a (1 + r)^{-1} + b (1 + r)^{-2} + c (1 + r)^{-3} $$ -$$ \code{npvb}(r, [a,b,c]) = a + b (1 + r)^{-1} + c (1 + r)^{-2} $$ -$$ \code{pmt}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 1 - (1 + r)^{-n} }$$ -$$ \code{pmtb}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over - (1 - (1 + r)^{-n}) (1 + r) } $$ -$$ \code{nper}(r, p, a) = -\code{log}(1 - { a r \over p }, 1 + r) $$ -$$ \code{nperb}(r, p, a) = -\code{log}(1 - { a r \over p (1 + r) }, 1 + r) $$ -$$ \code{nperl}(r, p, a) = -\code{log}({a \over p}, 1 + r) $$ -$$ \code{ratel}(n, p, a) = { p^{1/n} \over a^{1/n} } - 1 $$ -$$ \code{sln}(c, s, l) = { c - s \over l } $$ -$$ \code{syd}(c, s, l, p) = { (c - s) (l - p + 1) \over l (l+1) / 2 } $$ -$$ \code{ddb}(c, s, l, p) = { 2 (c - \hbox{depreciation so far}) \over l } $$ -@end tex - -@noindent -In @code{pmt} and @code{pmtb}, @expr{x=0} if omitted. - -These functions accept any numeric objects, including error forms, -intervals, and even (though not very usefully) complex numbers. The -above formulas specify exactly the behavior of these functions with -all sorts of inputs. - -Note that if the first argument to the @code{log} in @code{nper} is -negative, @code{nper} leaves itself in symbolic form rather than -returning a (financially meaningless) complex number. - -@samp{rate(num, pmt, amt)} solves the equation -@samp{pv(rate, num, pmt) = amt} for @samp{rate} using @kbd{H a R} -(@code{calc-find-root}), with the interval @samp{[.01% .. 100%]} -for an initial guess. The @code{rateb} function is the same except -that it uses @code{pvb}. Note that @code{ratel} can be solved -directly; its formula is shown in the above list. - -Similarly, @samp{irr(pmts)} solves the equation @samp{npv(rate, pmts) = 0} -for @samp{rate}. - -If you give a fourth argument to @code{nper} or @code{nperb}, Calc -will also use @kbd{H a R} to solve the equation using an initial -guess interval of @samp{[0 .. 100]}. - -A fourth argument to @code{fv} simply sums the two components -calculated from the above formulas for @code{fv} and @code{fvl}. -The same is true of @code{fvb}, @code{pv}, and @code{pvb}. - -The @kbd{ddb} function is computed iteratively; the ``book'' value -starts out equal to @var{cost}, and decreases according to the above -formula for the specified number of periods. If the book value -would decrease below @var{salvage}, it only decreases to @var{salvage} -and the depreciation is zero for all subsequent periods. The @code{ddb} -function returns the amount the book value decreased in the specified -period. - -@node Binary Functions, , Financial Functions, Arithmetic -@section Binary Number Functions - -@noindent -The commands in this chapter all use two-letter sequences beginning with -the @kbd{b} prefix. - -@cindex Binary numbers -The ``binary'' operations actually work regardless of the currently -displayed radix, although their results make the most sense in a radix -like 2, 8, or 16 (as obtained by the @kbd{d 2}, @kbd{d 8}, or @w{@kbd{d 6}} -commands, respectively). You may also wish to enable display of leading -zeros with @kbd{d z}. @xref{Radix Modes}. - -@cindex Word size for binary operations -The Calculator maintains a current @dfn{word size} @expr{w}, an -arbitrary positive or negative integer. For a positive word size, all -of the binary operations described here operate modulo @expr{2^w}. In -particular, negative arguments are converted to positive integers modulo -@expr{2^w} by all binary functions. - -If the word size is negative, binary operations produce twos-complement -integers from -@texline @math{-2^{-w-1}} -@infoline @expr{-(2^(-w-1))} -to -@texline @math{2^{-w-1}-1} -@infoline @expr{2^(-w-1)-1} -inclusive. Either mode accepts inputs in any range; the sign of -@expr{w} affects only the results produced. - -@kindex b c -@pindex calc-clip -@tindex clip -The @kbd{b c} (@code{calc-clip}) -[@code{clip}] command can be used to clip a number by reducing it modulo -@expr{2^w}. The commands described in this chapter automatically clip -their results to the current word size. Note that other operations like -addition do not use the current word size, since integer addition -generally is not ``binary.'' (However, @pxref{Simplification Modes}, -@code{calc-bin-simplify-mode}.) For example, with a word size of 8 -bits @kbd{b c} converts a number to the range 0 to 255; with a word -size of @mathit{-8} @kbd{b c} converts to the range @mathit{-128} to 127. - -@kindex b w -@pindex calc-word-size -The default word size is 32 bits. All operations except the shifts and -rotates allow you to specify a different word size for that one -operation by giving a numeric prefix argument: @kbd{C-u 8 b c} clips the -top of stack to the range 0 to 255 regardless of the current word size. -To set the word size permanently, use @kbd{b w} (@code{calc-word-size}). -This command displays a prompt with the current word size; press @key{RET} -immediately to keep this word size, or type a new word size at the prompt. - -When the binary operations are written in symbolic form, they take an -optional second (or third) word-size parameter. When a formula like -@samp{and(a,b)} is finally evaluated, the word size current at that time -will be used, but when @samp{and(a,b,-8)} is evaluated, a word size of -@mathit{-8} will always be used. A symbolic binary function will be left -in symbolic form unless the all of its argument(s) are integers or -integer-valued floats. - -If either or both arguments are modulo forms for which @expr{M} is a -power of two, that power of two is taken as the word size unless a -numeric prefix argument overrides it. The current word size is never -consulted when modulo-power-of-two forms are involved. - -@kindex b a -@pindex calc-and -@tindex and -The @kbd{b a} (@code{calc-and}) [@code{and}] command computes the bitwise -AND of the two numbers on the top of the stack. In other words, for each -of the @expr{w} binary digits of the two numbers (pairwise), the corresponding -bit of the result is 1 if and only if both input bits are 1: -@samp{and(2#1100, 2#1010) = 2#1000}. - -@kindex b o -@pindex calc-or -@tindex or -The @kbd{b o} (@code{calc-or}) [@code{or}] command computes the bitwise -inclusive OR of two numbers. A bit is 1 if either of the input bits, or -both, are 1: @samp{or(2#1100, 2#1010) = 2#1110}. - -@kindex b x -@pindex calc-xor -@tindex xor -The @kbd{b x} (@code{calc-xor}) [@code{xor}] command computes the bitwise -exclusive OR of two numbers. A bit is 1 if exactly one of the input bits -is 1: @samp{xor(2#1100, 2#1010) = 2#0110}. - -@kindex b d -@pindex calc-diff -@tindex diff -The @kbd{b d} (@code{calc-diff}) [@code{diff}] command computes the bitwise -difference of two numbers; this is defined by @samp{diff(a,b) = and(a,not(b))}, -so that @samp{diff(2#1100, 2#1010) = 2#0100}. - -@kindex b n -@pindex calc-not -@tindex not -The @kbd{b n} (@code{calc-not}) [@code{not}] command computes the bitwise -NOT of a number. A bit is 1 if the input bit is 0 and vice-versa. - -@kindex b l -@pindex calc-lshift-binary -@tindex lsh -The @kbd{b l} (@code{calc-lshift-binary}) [@code{lsh}] command shifts a -number left by one bit, or by the number of bits specified in the numeric -prefix argument. A negative prefix argument performs a logical right shift, -in which zeros are shifted in on the left. In symbolic form, @samp{lsh(a)} -is short for @samp{lsh(a,1)}, which in turn is short for @samp{lsh(a,n,w)}. -Bits shifted ``off the end,'' according to the current word size, are lost. - -@kindex H b l -@kindex H b r -@ignore -@mindex @idots -@end ignore -@kindex H b L -@ignore -@mindex @null -@end ignore -@kindex H b R -@ignore -@mindex @null -@end ignore -@kindex H b t -The @kbd{H b l} command also does a left shift, but it takes two arguments -from the stack (the value to shift, and, at top-of-stack, the number of -bits to shift). This version interprets the prefix argument just like -the regular binary operations, i.e., as a word size. The Hyperbolic flag -has a similar effect on the rest of the binary shift and rotate commands. - -@kindex b r -@pindex calc-rshift-binary -@tindex rsh -The @kbd{b r} (@code{calc-rshift-binary}) [@code{rsh}] command shifts a -number right by one bit, or by the number of bits specified in the numeric -prefix argument: @samp{rsh(a,n) = lsh(a,-n)}. - -@kindex b L -@pindex calc-lshift-arith -@tindex ash -The @kbd{b L} (@code{calc-lshift-arith}) [@code{ash}] command shifts a -number left. It is analogous to @code{lsh}, except that if the shift -is rightward (the prefix argument is negative), an arithmetic shift -is performed as described below. - -@kindex b R -@pindex calc-rshift-arith -@tindex rash -The @kbd{b R} (@code{calc-rshift-arith}) [@code{rash}] command performs -an ``arithmetic'' shift to the right, in which the leftmost bit (according -to the current word size) is duplicated rather than shifting in zeros. -This corresponds to dividing by a power of two where the input is interpreted -as a signed, twos-complement number. (The distinction between the @samp{rsh} -and @samp{rash} operations is totally independent from whether the word -size is positive or negative.) With a negative prefix argument, this -performs a standard left shift. - -@kindex b t -@pindex calc-rotate-binary -@tindex rot -The @kbd{b t} (@code{calc-rotate-binary}) [@code{rot}] command rotates a -number one bit to the left. The leftmost bit (according to the current -word size) is dropped off the left and shifted in on the right. With a -numeric prefix argument, the number is rotated that many bits to the left -or right. - -@xref{Set Operations}, for the @kbd{b p} and @kbd{b u} commands that -pack and unpack binary integers into sets. (For example, @kbd{b u} -unpacks the number @samp{2#11001} to the set of bit-numbers -@samp{[0, 3, 4]}.) Type @kbd{b u V #} to count the number of ``1'' -bits in a binary integer. - -Another interesting use of the set representation of binary integers -is to reverse the bits in, say, a 32-bit integer. Type @kbd{b u} to -unpack; type @kbd{31 @key{TAB} -} to replace each bit-number in the set -with 31 minus that bit-number; type @kbd{b p} to pack the set back -into a binary integer. - -@node Scientific Functions, Matrix Functions, Arithmetic, Top -@chapter Scientific Functions - -@noindent -The functions described here perform trigonometric and other transcendental -calculations. They generally produce floating-point answers correct to the -full current precision. The @kbd{H} (Hyperbolic) and @kbd{I} (Inverse) -flag keys must be used to get some of these functions from the keyboard. - -@kindex P -@pindex calc-pi -@cindex @code{pi} variable -@vindex pi -@kindex H P -@cindex @code{e} variable -@vindex e -@kindex I P -@cindex @code{gamma} variable -@vindex gamma -@cindex Gamma constant, Euler's -@cindex Euler's gamma constant -@kindex H I P -@cindex @code{phi} variable -@cindex Phi, golden ratio -@cindex Golden ratio -One miscellaneous command is shift-@kbd{P} (@code{calc-pi}), which pushes -the value of @cpi{} (at the current precision) onto the stack. With the -Hyperbolic flag, it pushes the value @expr{e}, the base of natural logarithms. -With the Inverse flag, it pushes Euler's constant -@texline @math{\gamma} -@infoline @expr{gamma} -(about 0.5772). With both Inverse and Hyperbolic, it -pushes the ``golden ratio'' -@texline @math{\phi} -@infoline @expr{phi} -(about 1.618). (At present, Euler's constant is not available -to unlimited precision; Calc knows only the first 100 digits.) -In Symbolic mode, these commands push the -actual variables @samp{pi}, @samp{e}, @samp{gamma}, and @samp{phi}, -respectively, instead of their values; @pxref{Symbolic Mode}. - -@ignore -@mindex Q -@end ignore -@ignore -@mindex I Q -@end ignore -@kindex I Q -@tindex sqr -The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] function is described elsewhere; -@pxref{Basic Arithmetic}. With the Inverse flag [@code{sqr}], this command -computes the square of the argument. - -@xref{Prefix Arguments}, for a discussion of the effect of numeric -prefix arguments on commands in this chapter which do not otherwise -interpret a prefix argument. - -@menu -* Logarithmic Functions:: -* Trigonometric and Hyperbolic Functions:: -* Advanced Math Functions:: -* Branch Cuts:: -* Random Numbers:: -* Combinatorial Functions:: -* Probability Distribution Functions:: -@end menu - -@node Logarithmic Functions, Trigonometric and Hyperbolic Functions, Scientific Functions, Scientific Functions -@section Logarithmic Functions - -@noindent -@kindex L -@pindex calc-ln -@tindex ln -@ignore -@mindex @null -@end ignore -@kindex I E -The shift-@kbd{L} (@code{calc-ln}) [@code{ln}] command computes the natural -logarithm of the real or complex number on the top of the stack. With -the Inverse flag it computes the exponential function instead, although -this is redundant with the @kbd{E} command. - -@kindex E -@pindex calc-exp -@tindex exp -@ignore -@mindex @null -@end ignore -@kindex I L -The shift-@kbd{E} (@code{calc-exp}) [@code{exp}] command computes the -exponential, i.e., @expr{e} raised to the power of the number on the stack. -The meanings of the Inverse and Hyperbolic flags follow from those for -the @code{calc-ln} command. - -@kindex H L -@kindex H E -@pindex calc-log10 -@tindex log10 -@tindex exp10 -@ignore -@mindex @null -@end ignore -@kindex H I L -@ignore -@mindex @null -@end ignore -@kindex H I E -The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common -(base-10) logarithm of a number. (With the Inverse flag [@code{exp10}], -it raises ten to a given power.) Note that the common logarithm of a -complex number is computed by taking the natural logarithm and dividing -by -@texline @math{\ln10}. -@infoline @expr{ln(10)}. - -@kindex B -@kindex I B -@pindex calc-log -@tindex log -@tindex alog -The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm -to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since -@texline @math{2^{10} = 1024}. -@infoline @expr{2^10 = 1024}. -In certain cases like @samp{log(3,9)}, the result -will be either @expr{1:2} or @expr{0.5} depending on the current Fraction -mode setting. With the Inverse flag [@code{alog}], this command is -similar to @kbd{^} except that the order of the arguments is reversed. - -@kindex f I -@pindex calc-ilog -@tindex ilog -The @kbd{f I} (@code{calc-ilog}) [@code{ilog}] command computes the -integer logarithm of a number to any base. The number and the base must -themselves be positive integers. This is the true logarithm, rounded -down to an integer. Thus @kbd{ilog(x,10)} is 3 for all @expr{x} in the -range from 1000 to 9999. If both arguments are positive integers, exact -integer arithmetic is used; otherwise, this is equivalent to -@samp{floor(log(x,b))}. - -@kindex f E -@pindex calc-expm1 -@tindex expm1 -The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes -@texline @math{e^x - 1}, -@infoline @expr{exp(x)-1}, -but using an algorithm that produces a more accurate -answer when the result is close to zero, i.e., when -@texline @math{e^x} -@infoline @expr{exp(x)} -is close to one. - -@kindex f L -@pindex calc-lnp1 -@tindex lnp1 -The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes -@texline @math{\ln(x+1)}, -@infoline @expr{ln(x+1)}, -producing a more accurate answer when @expr{x} is close to zero. - -@node Trigonometric and Hyperbolic Functions, Advanced Math Functions, Logarithmic Functions, Scientific Functions -@section Trigonometric/Hyperbolic Functions - -@noindent -@kindex S -@pindex calc-sin -@tindex sin -The shift-@kbd{S} (@code{calc-sin}) [@code{sin}] command computes the sine -of an angle or complex number. If the input is an HMS form, it is interpreted -as degrees-minutes-seconds; otherwise, the input is interpreted according -to the current angular mode. It is best to use Radians mode when operating -on complex numbers. - -Calc's ``units'' mechanism includes angular units like @code{deg}, -@code{rad}, and @code{grad}. While @samp{sin(45 deg)} is not evaluated -all the time, the @kbd{u s} (@code{calc-simplify-units}) command will -simplify @samp{sin(45 deg)} by taking the sine of 45 degrees, regardless -of the current angular mode. @xref{Basic Operations on Units}. - -Also, the symbolic variable @code{pi} is not ordinarily recognized in -arguments to trigonometric functions, as in @samp{sin(3 pi / 4)}, but -the default algebraic simplifications recognize many such -formulas when the current angular mode is Radians @emph{and} Symbolic -mode is enabled; this example would be replaced by @samp{sqrt(2) / 2}. -@xref{Symbolic Mode}. Beware, this simplification occurs even if you -have stored a different value in the variable @samp{pi}; this is one -reason why changing built-in variables is a bad idea. Arguments of -the form @expr{x} plus a multiple of @cpiover{2} are also simplified. -Calc includes similar formulas for @code{cos} and @code{tan}. - -Calc's algebraic simplifications know all angles which are integer multiples of -@cpiover{12}, @cpiover{10}, or @cpiover{8} radians. In Degrees mode, -analogous simplifications occur for integer multiples of 15 or 18 -degrees, and for arguments plus multiples of 90 degrees. - -@kindex I S -@pindex calc-arcsin -@tindex arcsin -With the Inverse flag, @code{calc-sin} computes an arcsine. This is also -available as the @code{calc-arcsin} command or @code{arcsin} algebraic -function. The returned argument is converted to degrees, radians, or HMS -notation depending on the current angular mode. - -@kindex H S -@pindex calc-sinh -@tindex sinh -@kindex H I S -@pindex calc-arcsinh -@tindex arcsinh -With the Hyperbolic flag, @code{calc-sin} computes the hyperbolic -sine, also available as @code{calc-sinh} [@code{sinh}]. With the -Hyperbolic and Inverse flags, it computes the hyperbolic arcsine -(@code{calc-arcsinh}) [@code{arcsinh}]. - -@kindex C -@pindex calc-cos -@tindex cos -@ignore -@mindex @idots -@end ignore -@kindex I C -@pindex calc-arccos -@ignore -@mindex @null -@end ignore -@tindex arccos -@ignore -@mindex @null -@end ignore -@kindex H C -@pindex calc-cosh -@ignore -@mindex @null -@end ignore -@tindex cosh -@ignore -@mindex @null -@end ignore -@kindex H I C -@pindex calc-arccosh -@ignore -@mindex @null -@end ignore -@tindex arccosh -@ignore -@mindex @null -@end ignore -@kindex T -@pindex calc-tan -@ignore -@mindex @null -@end ignore -@tindex tan -@ignore -@mindex @null -@end ignore -@kindex I T -@pindex calc-arctan -@ignore -@mindex @null -@end ignore -@tindex arctan -@ignore -@mindex @null -@end ignore -@kindex H T -@pindex calc-tanh -@ignore -@mindex @null -@end ignore -@tindex tanh -@ignore -@mindex @null -@end ignore -@kindex H I T -@pindex calc-arctanh -@ignore -@mindex @null -@end ignore -@tindex arctanh -The shift-@kbd{C} (@code{calc-cos}) [@code{cos}] command computes the cosine -of an angle or complex number, and shift-@kbd{T} (@code{calc-tan}) [@code{tan}] -computes the tangent, along with all the various inverse and hyperbolic -variants of these functions. - -@kindex f T -@pindex calc-arctan2 -@tindex arctan2 -The @kbd{f T} (@code{calc-arctan2}) [@code{arctan2}] command takes two -numbers from the stack and computes the arc tangent of their ratio. The -result is in the full range from @mathit{-180} (exclusive) to @mathit{+180} -(inclusive) degrees, or the analogous range in radians. A similar -result would be obtained with @kbd{/} followed by @kbd{I T}, but the -value would only be in the range from @mathit{-90} to @mathit{+90} degrees -since the division loses information about the signs of the two -components, and an error might result from an explicit division by zero -which @code{arctan2} would avoid. By (arbitrary) definition, -@samp{arctan2(0,0)=0}. - -@pindex calc-sincos -@ignore -@starindex -@end ignore -@tindex sincos -@ignore -@starindex -@end ignore -@ignore -@mindex arc@idots -@end ignore -@tindex arcsincos -The @code{calc-sincos} [@code{sincos}] command computes the sine and -cosine of a number, returning them as a vector of the form -@samp{[@var{cos}, @var{sin}]}. -With the Inverse flag [@code{arcsincos}], this command takes a two-element -vector as an argument and computes @code{arctan2} of the elements. -(This command does not accept the Hyperbolic flag.) - -@pindex calc-sec -@tindex sec -@pindex calc-csc -@tindex csc -@pindex calc-cot -@tindex cot -@pindex calc-sech -@tindex sech -@pindex calc-csch -@tindex csch -@pindex calc-coth -@tindex coth -The remaining trigonometric functions, @code{calc-sec} [@code{sec}], -@code{calc-csc} [@code{csc}] and @code{calc-cot} [@code{cot}], are also -available. With the Hyperbolic flag, these compute their hyperbolic -counterparts, which are also available separately as @code{calc-sech} -[@code{sech}], @code{calc-csch} [@code{csch}] and @code{calc-coth} -[@code{coth}]. (These commands do not accept the Inverse flag.) - -@node Advanced Math Functions, Branch Cuts, Trigonometric and Hyperbolic Functions, Scientific Functions -@section Advanced Mathematical Functions - -@noindent -Calc can compute a variety of less common functions that arise in -various branches of mathematics. All of the functions described in -this section allow arbitrary complex arguments and, except as noted, -will work to arbitrarily large precision. They can not at present -handle error forms or intervals as arguments. - -NOTE: These functions are still experimental. In particular, their -accuracy is not guaranteed in all domains. It is advisable to set the -current precision comfortably higher than you actually need when -using these functions. Also, these functions may be impractically -slow for some values of the arguments. - -@kindex f g -@pindex calc-gamma -@tindex gamma -The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler -gamma function. For positive integer arguments, this is related to the -factorial function: @samp{gamma(n+1) = fact(n)}. For general complex -arguments the gamma function can be defined by the following definite -integral: -@texline @math{\Gamma(a) = \int_0^\infty t^{a-1} e^t dt}. -@infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}. -(The actual implementation uses far more efficient computational methods.) - -@kindex f G -@tindex gammaP -@ignore -@mindex @idots -@end ignore -@kindex I f G -@ignore -@mindex @null -@end ignore -@kindex H f G -@ignore -@mindex @null -@end ignore -@kindex H I f G -@pindex calc-inc-gamma -@ignore -@mindex @null -@end ignore -@tindex gammaQ -@ignore -@mindex @null -@end ignore -@tindex gammag -@ignore -@mindex @null -@end ignore -@tindex gammaG -The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes -the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by -the integral, -@texline @math{P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)}. -@infoline @expr{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}. -This implies that @samp{gammaP(a,inf) = 1} for any @expr{a} (see the -definition of the normal gamma function). - -Several other varieties of incomplete gamma function are defined. -The complement of @expr{P(a,x)}, called @expr{Q(a,x) = 1-P(a,x)} by -some authors, is computed by the @kbd{I f G} [@code{gammaQ}] command. -You can think of this as taking the other half of the integral, from -@expr{x} to infinity. - -@ifnottex -The functions corresponding to the integrals that define @expr{P(a,x)} -and @expr{Q(a,x)} but without the normalizing @expr{1/gamma(a)} -factor are called @expr{g(a,x)} and @expr{G(a,x)}, respectively -(where @expr{g} and @expr{G} represent the lower- and upper-case Greek -letter gamma). You can obtain these using the @kbd{H f G} [@code{gammag}] -and @kbd{H I f G} [@code{gammaG}] commands. -@end ifnottex -@tex -The functions corresponding to the integrals that define $P(a,x)$ -and $Q(a,x)$ but without the normalizing $1/\Gamma(a)$ -factor are called $\gamma(a,x)$ and $\Gamma(a,x)$, respectively. -You can obtain these using the \kbd{H f G} [\code{gammag}] and -\kbd{I H f G} [\code{gammaG}] commands. -@end tex - -@kindex f b -@pindex calc-beta -@tindex beta -The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the -Euler beta function, which is defined in terms of the gamma function as -@texline @math{B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)}, -@infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)}, -or by -@texline @math{B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}. -@infoline @expr{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}. - -@kindex f B -@kindex H f B -@pindex calc-inc-beta -@tindex betaI -@tindex betaB -The @kbd{f B} (@code{calc-inc-beta}) [@code{betaI}] command computes -the incomplete beta function @expr{I(x,a,b)}. It is defined by -@texline @math{I(x,a,b) = \left( \int_0^x t^{a-1} (1-t)^{b-1} dt \right) / B(a,b)}. -@infoline @expr{betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)}. -Once again, the @kbd{H} (hyperbolic) prefix gives the corresponding -un-normalized version [@code{betaB}]. - -@kindex f e -@kindex I f e -@pindex calc-erf -@tindex erf -@tindex erfc -The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the -error function -@texline @math{\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt}. -@infoline @expr{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}. -The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}] -is the corresponding integral from @samp{x} to infinity; the sum -@texline @math{\hbox{erf}(x) + \hbox{erfc}(x) = 1}. -@infoline @expr{erf(x) + erfc(x) = 1}. - -@kindex f j -@kindex f y -@pindex calc-bessel-J -@pindex calc-bessel-Y -@tindex besJ -@tindex besY -The @kbd{f j} (@code{calc-bessel-J}) [@code{besJ}] and @kbd{f y} -(@code{calc-bessel-Y}) [@code{besY}] commands compute the Bessel -functions of the first and second kinds, respectively. -In @samp{besJ(n,x)} and @samp{besY(n,x)} the ``order'' parameter -@expr{n} is often an integer, but is not required to be one. -Calc's implementation of the Bessel functions currently limits the -precision to 8 digits, and may not be exact even to that precision. -Use with care! - -@node Branch Cuts, Random Numbers, Advanced Math Functions, Scientific Functions -@section Branch Cuts and Principal Values - -@noindent -@cindex Branch cuts -@cindex Principal values -All of the logarithmic, trigonometric, and other scientific functions are -defined for complex numbers as well as for reals. -This section describes the values -returned in cases where the general result is a family of possible values. -Calc follows section 12.5.3 of Steele's @dfn{Common Lisp, the Language}, -second edition, in these matters. This section will describe each -function briefly; for a more detailed discussion (including some nifty -diagrams), consult Steele's book. - -Note that the branch cuts for @code{arctan} and @code{arctanh} were -changed between the first and second editions of Steele. Recent -versions of Calc follow the second edition. - -The new branch cuts exactly match those of the HP-28/48 calculators. -They also match those of Mathematica 1.2, except that Mathematica's -@code{arctan} cut is always in the right half of the complex plane, -and its @code{arctanh} cut is always in the top half of the plane. -Calc's cuts are continuous with quadrants I and III for @code{arctan}, -or II and IV for @code{arctanh}. - -Note: The current implementations of these functions with complex arguments -are designed with proper behavior around the branch cuts in mind, @emph{not} -efficiency or accuracy. You may need to increase the floating precision -and wait a while to get suitable answers from them. - -For @samp{sqrt(a+bi)}: When @expr{a<0} and @expr{b} is small but positive -or zero, the result is close to the @expr{+i} axis. For @expr{b} small and -negative, the result is close to the @expr{-i} axis. The result always lies -in the right half of the complex plane. - -For @samp{ln(a+bi)}: The real part is defined as @samp{ln(abs(a+bi))}. -The imaginary part is defined as @samp{arg(a+bi) = arctan2(b,a)}. -Thus the branch cuts for @code{sqrt} and @code{ln} both lie on the -negative real axis. - -The following table describes these branch cuts in another way. -If the real and imaginary parts of @expr{z} are as shown, then -the real and imaginary parts of @expr{f(z)} will be as shown. -Here @code{eps} stands for a small positive value; each -occurrence of @code{eps} may stand for a different small value. - -@smallexample - z sqrt(z) ln(z) ----------------------------------------- - +, 0 +, 0 any, 0 - -, 0 0, + any, pi - -, +eps +eps, + +eps, + - -, -eps +eps, - +eps, - -@end smallexample - -For @samp{z1^z2}: This is defined by @samp{exp(ln(z1)*z2)}. -One interesting consequence of this is that @samp{(-8)^1:3} does -not evaluate to @mathit{-2} as you might expect, but to the complex -number @expr{(1., 1.732)}. Both of these are valid cube roots -of @mathit{-8} (as is @expr{(1., -1.732)}); Calc chooses a perhaps -less-obvious root for the sake of mathematical consistency. - -For @samp{arcsin(z)}: This is defined by @samp{-i*ln(i*z + sqrt(1-z^2))}. -The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. - -For @samp{arccos(z)}: This is defined by @samp{-i*ln(z + i*sqrt(1-z^2))}, -or equivalently by @samp{pi/2 - arcsin(z)}. The branch cuts are on -the real axis, less than @mathit{-1} and greater than 1. - -For @samp{arctan(z)}: This is defined by -@samp{(ln(1+i*z) - ln(1-i*z)) / (2*i)}. The branch cuts are on the -imaginary axis, below @expr{-i} and above @expr{i}. - -For @samp{arcsinh(z)}: This is defined by @samp{ln(z + sqrt(1+z^2))}. -The branch cuts are on the imaginary axis, below @expr{-i} and -above @expr{i}. - -For @samp{arccosh(z)}: This is defined by -@samp{ln(z + (z+1)*sqrt((z-1)/(z+1)))}. The branch cut is on the -real axis less than 1. - -For @samp{arctanh(z)}: This is defined by @samp{(ln(1+z) - ln(1-z)) / 2}. -The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. - -The following tables for @code{arcsin}, @code{arccos}, and -@code{arctan} assume the current angular mode is Radians. The -hyperbolic functions operate independently of the angular mode. - -@smallexample - z arcsin(z) arccos(z) -------------------------------------------------------- - (-1..1), 0 (-pi/2..pi/2), 0 (0..pi), 0 - (-1..1), +eps (-pi/2..pi/2), +eps (0..pi), -eps - (-1..1), -eps (-pi/2..pi/2), -eps (0..pi), +eps - <-1, 0 -pi/2, + pi, - - <-1, +eps -pi/2 + eps, + pi - eps, - - <-1, -eps -pi/2 + eps, - pi - eps, + - >1, 0 pi/2, - 0, + - >1, +eps pi/2 - eps, + +eps, - - >1, -eps pi/2 - eps, - +eps, + -@end smallexample - -@smallexample - z arccosh(z) arctanh(z) ------------------------------------------------------ - (-1..1), 0 0, (0..pi) any, 0 - (-1..1), +eps +eps, (0..pi) any, +eps - (-1..1), -eps +eps, (-pi..0) any, -eps - <-1, 0 +, pi -, pi/2 - <-1, +eps +, pi - eps -, pi/2 - eps - <-1, -eps +, -pi + eps -, -pi/2 + eps - >1, 0 +, 0 +, -pi/2 - >1, +eps +, +eps +, pi/2 - eps - >1, -eps +, -eps +, -pi/2 + eps -@end smallexample - -@smallexample - z arcsinh(z) arctan(z) ------------------------------------------------------ - 0, (-1..1) 0, (-pi/2..pi/2) 0, any - 0, <-1 -, -pi/2 -pi/2, - - +eps, <-1 +, -pi/2 + eps pi/2 - eps, - - -eps, <-1 -, -pi/2 + eps -pi/2 + eps, - - 0, >1 +, pi/2 pi/2, + - +eps, >1 +, pi/2 - eps pi/2 - eps, + - -eps, >1 -, pi/2 - eps -pi/2 + eps, + -@end smallexample - -Finally, the following identities help to illustrate the relationship -between the complex trigonometric and hyperbolic functions. They -are valid everywhere, including on the branch cuts. - -@smallexample -sin(i*z) = i*sinh(z) arcsin(i*z) = i*arcsinh(z) -cos(i*z) = cosh(z) arcsinh(i*z) = i*arcsin(z) -tan(i*z) = i*tanh(z) arctan(i*z) = i*arctanh(z) -sinh(i*z) = i*sin(z) cosh(i*z) = cos(z) -@end smallexample - -The ``advanced math'' functions (gamma, Bessel, etc.@:) are also defined -for general complex arguments, but their branch cuts and principal values -are not rigorously specified at present. - -@node Random Numbers, Combinatorial Functions, Branch Cuts, Scientific Functions -@section Random Numbers - -@noindent -@kindex k r -@pindex calc-random -@tindex random -The @kbd{k r} (@code{calc-random}) [@code{random}] command produces -random numbers of various sorts. - -Given a positive numeric prefix argument @expr{M}, it produces a random -integer @expr{N} in the range -@texline @math{0 \le N < M}. -@infoline @expr{0 <= N < M}. -Each possible value @expr{N} appears with equal probability. - -With no numeric prefix argument, the @kbd{k r} command takes its argument -from the stack instead. Once again, if this is a positive integer @expr{M} -the result is a random integer less than @expr{M}. However, note that -while numeric prefix arguments are limited to six digits or so, an @expr{M} -taken from the stack can be arbitrarily large. If @expr{M} is negative, -the result is a random integer in the range -@texline @math{M < N \le 0}. -@infoline @expr{M < N <= 0}. - -If the value on the stack is a floating-point number @expr{M}, the result -is a random floating-point number @expr{N} in the range -@texline @math{0 \le N < M} -@infoline @expr{0 <= N < M} -or -@texline @math{M < N \le 0}, -@infoline @expr{M < N <= 0}, -according to the sign of @expr{M}. - -If @expr{M} is zero, the result is a Gaussian-distributed random real -number; the distribution has a mean of zero and a standard deviation -of one. The algorithm used generates random numbers in pairs; thus, -every other call to this function will be especially fast. - -If @expr{M} is an error form -@texline @math{m} @code{+/-} @math{\sigma} -@infoline @samp{m +/- s} -where @var{m} and -@texline @math{\sigma} -@infoline @var{s} -are both real numbers, the result uses a Gaussian distribution with mean -@var{m} and standard deviation -@texline @math{\sigma}. -@infoline @var{s}. - -If @expr{M} is an interval form, the lower and upper bounds specify the -acceptable limits of the random numbers. If both bounds are integers, -the result is a random integer in the specified range. If either bound -is floating-point, the result is a random real number in the specified -range. If the interval is open at either end, the result will be sure -not to equal that end value. (This makes a big difference for integer -intervals, but for floating-point intervals it's relatively minor: -with a precision of 6, @samp{random([1.0..2.0))} will return any of one -million numbers from 1.00000 to 1.99999; @samp{random([1.0..2.0])} may -additionally return 2.00000, but the probability of this happening is -extremely small.) - -If @expr{M} is a vector, the result is one element taken at random from -the vector. All elements of the vector are given equal probabilities. - -@vindex RandSeed -The sequence of numbers produced by @kbd{k r} is completely random by -default, i.e., the sequence is seeded each time you start Calc using -the current time and other information. You can get a reproducible -sequence by storing a particular ``seed value'' in the Calc variable -@code{RandSeed}. Any integer will do for a seed; integers of from 1 -to 12 digits are good. If you later store a different integer into -@code{RandSeed}, Calc will switch to a different pseudo-random -sequence. If you ``unstore'' @code{RandSeed}, Calc will re-seed itself -from the current time. If you store the same integer that you used -before back into @code{RandSeed}, you will get the exact same sequence -of random numbers as before. - -@pindex calc-rrandom -The @code{calc-rrandom} command (not on any key) produces a random real -number between zero and one. It is equivalent to @samp{random(1.0)}. - -@kindex k a -@pindex calc-random-again -The @kbd{k a} (@code{calc-random-again}) command produces another random -number, re-using the most recent value of @expr{M}. With a numeric -prefix argument @var{n}, it produces @var{n} more random numbers using -that value of @expr{M}. - -@kindex k h -@pindex calc-shuffle -@tindex shuffle -The @kbd{k h} (@code{calc-shuffle}) command produces a vector of several -random values with no duplicates. The value on the top of the stack -specifies the set from which the random values are drawn, and may be any -of the @expr{M} formats described above. The numeric prefix argument -gives the length of the desired list. (If you do not provide a numeric -prefix argument, the length of the list is taken from the top of the -stack, and @expr{M} from second-to-top.) - -If @expr{M} is a floating-point number, zero, or an error form (so -that the random values are being drawn from the set of real numbers) -there is little practical difference between using @kbd{k h} and using -@kbd{k r} several times. But if the set of possible values consists -of just a few integers, or the elements of a vector, then there is -a very real chance that multiple @kbd{k r}'s will produce the same -number more than once. The @kbd{k h} command produces a vector whose -elements are always distinct. (Actually, there is a slight exception: -If @expr{M} is a vector, no given vector element will be drawn more -than once, but if several elements of @expr{M} are equal, they may -each make it into the result vector.) - -One use of @kbd{k h} is to rearrange a list at random. This happens -if the prefix argument is equal to the number of values in the list: -@kbd{[1, 1.5, 2, 2.5, 3] 5 k h} might produce the permuted list -@samp{[2.5, 1, 1.5, 3, 2]}. As a convenient feature, if the argument -@var{n} is negative it is replaced by the size of the set represented -by @expr{M}. Naturally, this is allowed only when @expr{M} specifies -a small discrete set of possibilities. - -To do the equivalent of @kbd{k h} but with duplications allowed, -given @expr{M} on the stack and with @var{n} just entered as a numeric -prefix, use @kbd{v b} to build a vector of copies of @expr{M}, then use -@kbd{V M k r} to ``map'' the normal @kbd{k r} function over the -elements of this vector. @xref{Matrix Functions}. - -@menu -* Random Number Generator:: (Complete description of Calc's algorithm) -@end menu - -@node Random Number Generator, , Random Numbers, Random Numbers -@subsection Random Number Generator - -Calc's random number generator uses several methods to ensure that -the numbers it produces are highly random. Knuth's @emph{Art of -Computer Programming}, Volume II, contains a thorough description -of the theory of random number generators and their measurement and -characterization. - -If @code{RandSeed} has no stored value, Calc calls Emacs's built-in -@code{random} function to get a stream of random numbers, which it -then treats in various ways to avoid problems inherent in the simple -random number generators that many systems use to implement @code{random}. - -When Calc's random number generator is first invoked, it ``seeds'' -the low-level random sequence using the time of day, so that the -random number sequence will be different every time you use Calc. - -Since Emacs Lisp doesn't specify the range of values that will be -returned by its @code{random} function, Calc exercises the function -several times to estimate the range. When Calc subsequently uses -the @code{random} function, it takes only 10 bits of the result -near the most-significant end. (It avoids at least the bottom -four bits, preferably more, and also tries to avoid the top two -bits.) This strategy works well with the linear congruential -generators that are typically used to implement @code{random}. - -If @code{RandSeed} contains an integer, Calc uses this integer to -seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A, -computing -@texline @math{X_{n-55} - X_{n-24}}. -@infoline @expr{X_n-55 - X_n-24}). -This method expands the seed -value into a large table which is maintained internally; the variable -@code{RandSeed} is changed from, e.g., 42 to the vector @expr{[42]} -to indicate that the seed has been absorbed into this table. When -@code{RandSeed} contains a vector, @kbd{k r} and related commands -continue to use the same internal table as last time. There is no -way to extract the complete state of the random number generator -so that you can restart it from any point; you can only restart it -from the same initial seed value. A simple way to restart from the -same seed is to type @kbd{s r RandSeed} to get the seed vector, -@kbd{v u} to unpack it back into a number, then @kbd{s t RandSeed} -to reseed the generator with that number. - -Calc uses a ``shuffling'' method as described in algorithm 3.2.2B -of Knuth. It fills a table with 13 random 10-bit numbers. Then, -to generate a new random number, it uses the previous number to -index into the table, picks the value it finds there as the new -random number, then replaces that table entry with a new value -obtained from a call to the base random number generator (either -the additive congruential generator or the @code{random} function -supplied by the system). If there are any flaws in the base -generator, shuffling will tend to even them out. But if the system -provides an excellent @code{random} function, shuffling will not -damage its randomness. - -To create a random integer of a certain number of digits, Calc -builds the integer three decimal digits at a time. For each group -of three digits, Calc calls its 10-bit shuffling random number generator -(which returns a value from 0 to 1023); if the random value is 1000 -or more, Calc throws it out and tries again until it gets a suitable -value. - -To create a random floating-point number with precision @var{p}, Calc -simply creates a random @var{p}-digit integer and multiplies by -@texline @math{10^{-p}}. -@infoline @expr{10^-p}. -The resulting random numbers should be very clean, but note -that relatively small numbers will have few significant random digits. -In other words, with a precision of 12, you will occasionally get -numbers on the order of -@texline @math{10^{-9}} -@infoline @expr{10^-9} -or -@texline @math{10^{-10}}, -@infoline @expr{10^-10}, -but those numbers will only have two or three random digits since they -correspond to small integers times -@texline @math{10^{-12}}. -@infoline @expr{10^-12}. - -To create a random integer in the interval @samp{[0 .. @var{m})}, Calc -counts the digits in @var{m}, creates a random integer with three -additional digits, then reduces modulo @var{m}. Unless @var{m} is a -power of ten the resulting values will be very slightly biased toward -the lower numbers, but this bias will be less than 0.1%. (For example, -if @var{m} is 42, Calc will reduce a random integer less than 100000 -modulo 42 to get a result less than 42. It is easy to show that the -numbers 40 and 41 will be only 2380/2381 as likely to result from this -modulo operation as numbers 39 and below.) If @var{m} is a power of -ten, however, the numbers should be completely unbiased. - -The Gaussian random numbers generated by @samp{random(0.0)} use the -``polar'' method described in Knuth section 3.4.1C@. This method -generates a pair of Gaussian random numbers at a time, so only every -other call to @samp{random(0.0)} will require significant calculations. - -@node Combinatorial Functions, Probability Distribution Functions, Random Numbers, Scientific Functions -@section Combinatorial Functions - -@noindent -Commands relating to combinatorics and number theory begin with the -@kbd{k} key prefix. - -@kindex k g -@pindex calc-gcd -@tindex gcd -The @kbd{k g} (@code{calc-gcd}) [@code{gcd}] command computes the -Greatest Common Divisor of two integers. It also accepts fractions; -the GCD of two fractions is defined by taking the GCD of the -numerators, and the LCM of the denominators. This definition is -consistent with the idea that @samp{a / gcd(a,x)} should yield an -integer for any @samp{a} and @samp{x}. For other types of arguments, -the operation is left in symbolic form. - -@kindex k l -@pindex calc-lcm -@tindex lcm -The @kbd{k l} (@code{calc-lcm}) [@code{lcm}] command computes the -Least Common Multiple of two integers or fractions. The product of -the LCM and GCD of two numbers is equal to the product of the -numbers. - -@kindex k E -@pindex calc-extended-gcd -@tindex egcd -The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes -the GCD of two integers @expr{x} and @expr{y} and returns a vector -@expr{[g, a, b]} where -@texline @math{g = \gcd(x,y) = a x + b y}. -@infoline @expr{g = gcd(x,y) = a x + b y}. - -@kindex ! -@pindex calc-factorial -@tindex fact -@ignore -@mindex @null -@end ignore -@tindex ! -The @kbd{!} (@code{calc-factorial}) [@code{fact}] command computes the -factorial of the number at the top of the stack. If the number is an -integer, the result is an exact integer. If the number is an -integer-valued float, the result is a floating-point approximation. If -the number is a non-integral real number, the generalized factorial is used, -as defined by the Euler Gamma function. Please note that computation of -large factorials can be slow; using floating-point format will help -since fewer digits must be maintained. The same is true of many of -the commands in this section. - -@kindex k d -@pindex calc-double-factorial -@tindex dfact -@ignore -@mindex @null -@end ignore -@tindex !! -The @kbd{k d} (@code{calc-double-factorial}) [@code{dfact}] command -computes the ``double factorial'' of an integer. For an even integer, -this is the product of even integers from 2 to @expr{N}. For an odd -integer, this is the product of odd integers from 3 to @expr{N}. If -the argument is an integer-valued float, the result is a floating-point -approximation. This function is undefined for negative even integers. -The notation @expr{N!!} is also recognized for double factorials. - -@kindex k c -@pindex calc-choose -@tindex choose -The @kbd{k c} (@code{calc-choose}) [@code{choose}] command computes the -binomial coefficient @expr{N}-choose-@expr{M}, where @expr{M} is the number -on the top of the stack and @expr{N} is second-to-top. If both arguments -are integers, the result is an exact integer. Otherwise, the result is a -floating-point approximation. The binomial coefficient is defined for all -real numbers by -@texline @math{N! \over M! (N-M)!\,}. -@infoline @expr{N! / M! (N-M)!}. - -@kindex H k c -@pindex calc-perm -@tindex perm -@ifnottex -The @kbd{H k c} (@code{calc-perm}) [@code{perm}] command computes the -number-of-permutations function @expr{N! / (N-M)!}. -@end ifnottex -@tex -The \kbd{H k c} (\code{calc-perm}) [\code{perm}] command computes the -number-of-perm\-utations function $N! \over (N-M)!\,$. -@end tex - -@kindex k b -@kindex H k b -@pindex calc-bernoulli-number -@tindex bern -The @kbd{k b} (@code{calc-bernoulli-number}) [@code{bern}] command -computes a given Bernoulli number. The value at the top of the stack -is a nonnegative integer @expr{n} that specifies which Bernoulli number -is desired. The @kbd{H k b} command computes a Bernoulli polynomial, -taking @expr{n} from the second-to-top position and @expr{x} from the -top of the stack. If @expr{x} is a variable or formula the result is -a polynomial in @expr{x}; if @expr{x} is a number the result is a number. - -@kindex k e -@kindex H k e -@pindex calc-euler-number -@tindex euler -The @kbd{k e} (@code{calc-euler-number}) [@code{euler}] command similarly -computes an Euler number, and @w{@kbd{H k e}} computes an Euler polynomial. -Bernoulli and Euler numbers occur in the Taylor expansions of several -functions. - -@kindex k s -@kindex H k s -@pindex calc-stirling-number -@tindex stir1 -@tindex stir2 -The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command -computes a Stirling number of the first -@texline kind@tie{}@math{n \brack m}, -@infoline kind, -given two integers @expr{n} and @expr{m} on the stack. The @kbd{H k s} -[@code{stir2}] command computes a Stirling number of the second -@texline kind@tie{}@math{n \brace m}. -@infoline kind. -These are the number of @expr{m}-cycle permutations of @expr{n} objects, -and the number of ways to partition @expr{n} objects into @expr{m} -non-empty sets, respectively. - -@kindex k p -@pindex calc-prime-test -@cindex Primes -The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on -the top of the stack is prime. For integers less than eight million, the -answer is always exact and reasonably fast. For larger integers, a -probabilistic method is used (see Knuth vol. II, section 4.5.4, algorithm P). -The number is first checked against small prime factors (up to 13). Then, -any number of iterations of the algorithm are performed. Each step either -discovers that the number is non-prime, or substantially increases the -certainty that the number is prime. After a few steps, the chance that -a number was mistakenly described as prime will be less than one percent. -(Indeed, this is a worst-case estimate of the probability; in practice -even a single iteration is quite reliable.) After the @kbd{k p} command, -the number will be reported as definitely prime or non-prime if possible, -or otherwise ``probably'' prime with a certain probability of error. - -@ignore -@starindex -@end ignore -@tindex prime -The normal @kbd{k p} command performs one iteration of the primality -test. Pressing @kbd{k p} repeatedly for the same integer will perform -additional iterations. Also, @kbd{k p} with a numeric prefix performs -the specified number of iterations. There is also an algebraic function -@samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @expr{n} -is (probably) prime and 0 if not. - -@kindex k f -@pindex calc-prime-factors -@tindex prfac -The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command -attempts to decompose an integer into its prime factors. For numbers up -to 25 million, the answer is exact although it may take some time. The -result is a vector of the prime factors in increasing order. For larger -inputs, prime factors above 5000 may not be found, in which case the -last number in the vector will be an unfactored integer greater than 25 -million (with a warning message). For negative integers, the first -element of the list will be @mathit{-1}. For inputs @mathit{-1}, @mathit{0}, and -@mathit{1}, the result is a list of the same number. - -@kindex k n -@pindex calc-next-prime -@ignore -@mindex nextpr@idots -@end ignore -@tindex nextprime -The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds -the next prime above a given number. Essentially, it searches by calling -@code{calc-prime-test} on successive integers until it finds one that -passes the test. This is quite fast for integers less than eight million, -but once the probabilistic test comes into play the search may be rather -slow. Ordinarily this command stops for any prime that passes one iteration -of the primality test. With a numeric prefix argument, a number must pass -the specified number of iterations before the search stops. (This only -matters when searching above eight million.) You can always use additional -@kbd{k p} commands to increase your certainty that the number is indeed -prime. - -@kindex I k n -@pindex calc-prev-prime -@ignore -@mindex prevpr@idots -@end ignore -@tindex prevprime -The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command -analogously finds the next prime less than a given number. - -@kindex k t -@pindex calc-totient -@tindex totient -The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the -Euler ``totient'' -@texline function@tie{}@math{\phi(n)}, -@infoline function, -the number of integers less than @expr{n} which -are relatively prime to @expr{n}. - -@kindex k m -@pindex calc-moebius -@tindex moebius -The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the -@texline M@"obius @math{\mu} -@infoline Moebius ``mu'' -function. If the input number is a product of @expr{k} -distinct factors, this is @expr{(-1)^k}. If the input number has any -duplicate factors (i.e., can be divided by the same prime more than once), -the result is zero. - -@node Probability Distribution Functions, , Combinatorial Functions, Scientific Functions -@section Probability Distribution Functions - -@noindent -The functions in this section compute various probability distributions. -For continuous distributions, this is the integral of the probability -density function from @expr{x} to infinity. (These are the ``upper -tail'' distribution functions; there are also corresponding ``lower -tail'' functions which integrate from minus infinity to @expr{x}.) -For discrete distributions, the upper tail function gives the sum -from @expr{x} to infinity; the lower tail function gives the sum -from minus infinity up to, but not including,@w{ }@expr{x}. - -To integrate from @expr{x} to @expr{y}, just use the distribution -function twice and subtract. For example, the probability that a -Gaussian random variable with mean 2 and standard deviation 1 will -lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)} -(``the probability that it is greater than 2.5, but not greater than 2.8''), -or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}. - -@kindex k B -@kindex I k B -@pindex calc-utpb -@tindex utpb -@tindex ltpb -The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the -binomial distribution. Push the parameters @var{n}, @var{p}, and -then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the -probability that an event will occur @var{x} or more times out -of @var{n} trials, if its probability of occurring in any given -trial is @var{p}. The @kbd{I k B} [@code{ltpb}] function is -the probability that the event will occur fewer than @var{x} times. - -The other probability distribution functions similarly take the -form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}] -and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters -@var{x}. The arguments to the algebraic functions are the value of -the random variable first, then whatever other parameters define the -distribution. Note these are among the few Calc functions where the -order of the arguments in algebraic form differs from the order of -arguments as found on the stack. (The random variable comes last on -the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5 -k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to -recover the original arguments but substitute a new value for @expr{x}.) - -@kindex k C -@pindex calc-utpc -@tindex utpc -@ignore -@mindex @idots -@end ignore -@kindex I k C -@ignore -@mindex @null -@end ignore -@tindex ltpc -The @samp{utpc(x,v)} function uses the chi-square distribution with -@texline @math{\nu} -@infoline @expr{v} -degrees of freedom. It is the probability that a model is -correct if its chi-square statistic is @expr{x}. - -@kindex k F -@pindex calc-utpf -@tindex utpf -@ignore -@mindex @idots -@end ignore -@kindex I k F -@ignore -@mindex @null -@end ignore -@tindex ltpf -The @samp{utpf(F,v1,v2)} function uses the F distribution, used in -various statistical tests. The parameters -@texline @math{\nu_1} -@infoline @expr{v1} -and -@texline @math{\nu_2} -@infoline @expr{v2} -are the degrees of freedom in the numerator and denominator, -respectively, used in computing the statistic @expr{F}. - -@kindex k N -@pindex calc-utpn -@tindex utpn -@ignore -@mindex @idots -@end ignore -@kindex I k N -@ignore -@mindex @null -@end ignore -@tindex ltpn -The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution -with mean @expr{m} and standard deviation -@texline @math{\sigma}. -@infoline @expr{s}. -It is the probability that such a normal-distributed random variable -would exceed @expr{x}. - -@kindex k P -@pindex calc-utpp -@tindex utpp -@ignore -@mindex @idots -@end ignore -@kindex I k P -@ignore -@mindex @null -@end ignore -@tindex ltpp -The @samp{utpp(n,x)} function uses a Poisson distribution with -mean @expr{x}. It is the probability that @expr{n} or more such -Poisson random events will occur. - -@kindex k T -@pindex calc-ltpt -@tindex utpt -@ignore -@mindex @idots -@end ignore -@kindex I k T -@ignore -@mindex @null -@end ignore -@tindex ltpt -The @samp{utpt(t,v)} function uses the Student's ``t'' distribution -with -@texline @math{\nu} -@infoline @expr{v} -degrees of freedom. It is the probability that a -t-distributed random variable will be greater than @expr{t}. -(Note: This computes the distribution function -@texline @math{A(t|\nu)} -@infoline @expr{A(t|v)} -where -@texline @math{A(0|\nu) = 1} -@infoline @expr{A(0|v) = 1} -and -@texline @math{A(\infty|\nu) \to 0}. -@infoline @expr{A(inf|v) -> 0}. -The @code{UTPT} operation on the HP-48 uses a different definition which -returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.) - -While Calc does not provide inverses of the probability distribution -functions, the @kbd{a R} command can be used to solve for the inverse. -Since the distribution functions are monotonic, @kbd{a R} is guaranteed -to be able to find a solution given any initial guess. -@xref{Numerical Solutions}. - -@node Matrix Functions, Algebra, Scientific Functions, Top -@chapter Vector/Matrix Functions - -@noindent -Many of the commands described here begin with the @kbd{v} prefix. -(For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.) -The commands usually apply to both plain vectors and matrices; some -apply only to matrices or only to square matrices. If the argument -has the wrong dimensions the operation is left in symbolic form. - -Vectors are entered and displayed using @samp{[a,b,c]} notation. -Matrices are vectors of which all elements are vectors of equal length. -(Though none of the standard Calc commands use this concept, a -three-dimensional matrix or rank-3 tensor could be defined as a -vector of matrices, and so on.) - -@menu -* Packing and Unpacking:: -* Building Vectors:: -* Extracting Elements:: -* Manipulating Vectors:: -* Vector and Matrix Arithmetic:: -* Set Operations:: -* Statistical Operations:: -* Reducing and Mapping:: -* Vector and Matrix Formats:: -@end menu - -@node Packing and Unpacking, Building Vectors, Matrix Functions, Matrix Functions -@section Packing and Unpacking - -@noindent -Calc's ``pack'' and ``unpack'' commands collect stack entries to build -composite objects such as vectors and complex numbers. They are -described in this chapter because they are most often used to build -vectors. - -@kindex v p -@kindex V p -@pindex calc-pack -The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several -elements from the stack into a matrix, complex number, HMS form, error -form, etc. It uses a numeric prefix argument to specify the kind of -object to be built; this argument is referred to as the ``packing mode.'' -If the packing mode is a nonnegative integer, a vector of that -length is created. For example, @kbd{C-u 5 v p} will pop the top -five stack elements and push back a single vector of those five -elements. (@kbd{C-u 0 v p} simply creates an empty vector.) - -The same effect can be had by pressing @kbd{[} to push an incomplete -vector on the stack, using @key{TAB} (@code{calc-roll-down}) to sneak -the incomplete object up past a certain number of elements, and -then pressing @kbd{]} to complete the vector. - -Negative packing modes create other kinds of composite objects: - -@table @cite -@item -1 -Two values are collected to build a complex number. For example, -@kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number -@expr{(5, 7)}. The result is always a rectangular complex -number. The two input values must both be real numbers, -i.e., integers, fractions, or floats. If they are not, Calc -will instead build a formula like @samp{a + (0, 1) b}. (The -other packing modes also create a symbolic answer if the -components are not suitable.) - -@item -2 -Two values are collected to build a polar complex number. -The first is the magnitude; the second is the phase expressed -in either degrees or radians according to the current angular -mode. - -@item -3 -Three values are collected into an HMS form. The first -two values (hours and minutes) must be integers or -integer-valued floats. The third value may be any real -number. - -@item -4 -Two values are collected into an error form. The inputs -may be real numbers or formulas. - -@item -5 -Two values are collected into a modulo form. The inputs -must be real numbers. - -@item -6 -Two values are collected into the interval @samp{[a .. b]}. -The inputs may be real numbers, HMS or date forms, or formulas. - -@item -7 -Two values are collected into the interval @samp{[a .. b)}. - -@item -8 -Two values are collected into the interval @samp{(a .. b]}. - -@item -9 -Two values are collected into the interval @samp{(a .. b)}. - -@item -10 -Two integer values are collected into a fraction. - -@item -11 -Two values are collected into a floating-point number. -The first is the mantissa; the second, which must be an -integer, is the exponent. The result is the mantissa -times ten to the power of the exponent. - -@item -12 -This is treated the same as @mathit{-11} by the @kbd{v p} command. -When unpacking, @mathit{-12} specifies that a floating-point mantissa -is desired. - -@item -13 -A real number is converted into a date form. - -@item -14 -Three numbers (year, month, day) are packed into a pure date form. - -@item -15 -Six numbers are packed into a date/time form. -@end table - -With any of the two-input negative packing modes, either or both -of the inputs may be vectors. If both are vectors of the same -length, the result is another vector made by packing corresponding -elements of the input vectors. If one input is a vector and the -other is a plain number, the number is packed along with each vector -element to produce a new vector. For example, @kbd{C-u -4 v p} -could be used to convert a vector of numbers and a vector of errors -into a single vector of error forms; @kbd{C-u -5 v p} could convert -a vector of numbers and a single number @var{M} into a vector of -numbers modulo @var{M}. - -If you don't give a prefix argument to @kbd{v p}, it takes -the packing mode from the top of the stack. The elements to -be packed then begin at stack level 2. Thus -@kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to -enter the error form @samp{1 +/- 2}. - -If the packing mode taken from the stack is a vector, the result is a -matrix with the dimensions specified by the elements of the vector, -which must each be integers. For example, if the packing mode is -@samp{[2, 3]}, then six numbers will be taken from the stack and -returned in the form @samp{[@w{[a, b, c]}, [d, e, f]]}. - -If any elements of the vector are negative, other kinds of -packing are done at that level as described above. For -example, @samp{[2, 3, -4]} takes 12 objects and creates a -@texline @math{2\times3} -@infoline 2x3 -matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}. -Also, @samp{[-4, -10]} will convert four integers into an -error form consisting of two fractions: @samp{a:b +/- c:d}. - -@ignore -@starindex -@end ignore -@tindex pack -There is an equivalent algebraic function, -@samp{pack(@var{mode}, @var{items})} where @var{mode} is a -packing mode (an integer or a vector of integers) and @var{items} -is a vector of objects to be packed (re-packed, really) according -to that mode. For example, @samp{pack([3, -4], [a,b,c,d,e,f])} -yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}. The function is -left in symbolic form if the packing mode is invalid, or if the -number of data items does not match the number of items required -by the mode. - -@kindex v u -@kindex V u -@pindex calc-unpack -The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex -number, HMS form, or other composite object on the top of the stack and -``unpacks'' it, pushing each of its elements onto the stack as separate -objects. Thus, it is the ``inverse'' of @kbd{v p}. If the value -at the top of the stack is a formula, @kbd{v u} unpacks it by pushing -each of the arguments of the top-level operator onto the stack. - -You can optionally give a numeric prefix argument to @kbd{v u} -to specify an explicit (un)packing mode. If the packing mode is -negative and the input is actually a vector or matrix, the result -will be two or more similar vectors or matrices of the elements. -For example, given the vector @samp{[@w{a +/- b}, c^2, d +/- 7]}, -the result of @kbd{C-u -4 v u} will be the two vectors -@samp{[a, c^2, d]} and @w{@samp{[b, 0, 7]}}. - -Note that the prefix argument can have an effect even when the input is -not a vector. For example, if the input is the number @mathit{-5}, then -@kbd{c-u -1 v u} yields @mathit{-5} and 0 (the components of @mathit{-5} -when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5 -and 180 (assuming Degrees mode); and @kbd{C-u -10 v u} yields @mathit{-5} -and 1 (the numerator and denominator of @mathit{-5}, viewed as a rational -number). Plain @kbd{v u} with this input would complain that the input -is not a composite object. - -Unpacking mode @mathit{-11} converts a float into an integer mantissa and -an integer exponent, where the mantissa is not divisible by 10 -(except that 0.0 is represented by a mantissa and exponent of 0). -Unpacking mode @mathit{-12} converts a float into a floating-point mantissa -and integer exponent, where the mantissa (for non-zero numbers) -is guaranteed to lie in the range [1 .. 10). In both cases, -the mantissa is shifted left or right (and the exponent adjusted -to compensate) in order to satisfy these constraints. - -Positive unpacking modes are treated differently than for @kbd{v p}. -A mode of 1 is much like plain @kbd{v u} with no prefix argument, -except that in addition to the components of the input object, -a suitable packing mode to re-pack the object is also pushed. -Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the -original object. - -A mode of 2 unpacks two levels of the object; the resulting -re-packing mode will be a vector of length 2. This might be used -to unpack a matrix, say, or a vector of error forms. Higher -unpacking modes unpack the input even more deeply. - -@ignore -@starindex -@end ignore -@tindex unpack -There are two algebraic functions analogous to @kbd{v u}. -The @samp{unpack(@var{mode}, @var{item})} function unpacks the -@var{item} using the given @var{mode}, returning the result as -a vector of components. Here the @var{mode} must be an -integer, not a vector. For example, @samp{unpack(-4, a +/- b)} -returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}. - -@ignore -@starindex -@end ignore -@tindex unpackt -The @code{unpackt} function is like @code{unpack} but instead -of returning a simple vector of items, it returns a vector of -two things: The mode, and the vector of items. For example, -@samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]}, -and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}. -The identity for re-building the original object is -@samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}. (The -@code{apply} function builds a function call given the function -name and a vector of arguments.) - -@cindex Numerator of a fraction, extracting -Subscript notation is a useful way to extract a particular part -of an object. For example, to get the numerator of a rational -number, you can use @samp{unpack(-10, @var{x})_1}. - -@node Building Vectors, Extracting Elements, Packing and Unpacking, Matrix Functions -@section Building Vectors - -@noindent -Vectors and matrices can be added, -subtracted, multiplied, and divided; @pxref{Basic Arithmetic}. - -@kindex | -@pindex calc-concat -@ignore -@mindex @null -@end ignore -@tindex | -The @kbd{|} (@code{calc-concat}) [@code{vconcat}] command ``concatenates'' two vectors -into one. For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack -will contain the single vector @samp{[1, 2, 3, 4]}. If the arguments -are matrices, the rows of the first matrix are concatenated with the -rows of the second. (In other words, two matrices are just two vectors -of row-vectors as far as @kbd{|} is concerned.) - -If either argument to @kbd{|} is a scalar (a non-vector), it is treated -like a one-element vector for purposes of concatenation: @kbd{1 [ 2 , 3 ] |} -produces the vector @samp{[1, 2, 3]}. Likewise, if one argument is a -matrix and the other is a plain vector, the vector is treated as a -one-row matrix. - -@kindex H | -@tindex append -The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates -two vectors without any special cases. Both inputs must be vectors. -Whether or not they are matrices is not taken into account. If either -argument is a scalar, the @code{append} function is left in symbolic form. -See also @code{cons} and @code{rcons} below. - -@kindex I | -@kindex H I | -The @kbd{I |} and @kbd{H I |} commands are similar, but they use their -two stack arguments in the opposite order. Thus @kbd{I |} is equivalent -to @kbd{@key{TAB} |}, but possibly more convenient and also a bit faster. - -@kindex v d -@kindex V d -@pindex calc-diag -@tindex diag -The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal -square matrix. The optional numeric prefix gives the number of rows -and columns in the matrix. If the value at the top of the stack is a -vector, the elements of the vector are used as the diagonal elements; the -prefix, if specified, must match the size of the vector. If the value on -the stack is a scalar, it is used for each element on the diagonal, and -the prefix argument is required. - -To build a constant square matrix, e.g., a -@texline @math{3\times3} -@infoline 3x3 -matrix filled with ones, use @kbd{0 M-3 v d 1 +}, i.e., build a zero -matrix first and then add a constant value to that matrix. (Another -alternative would be to use @kbd{v b} and @kbd{v a}; see below.) - -@kindex v i -@kindex V i -@pindex calc-ident -@tindex idn -The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity -matrix of the specified size. It is a convenient form of @kbd{v d} -where the diagonal element is always one. If no prefix argument is given, -this command prompts for one. - -In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)}, -except that @expr{a} is required to be a scalar (non-vector) quantity. -If @expr{n} is omitted, @samp{idn(a)} represents @expr{a} times an -identity matrix of unknown size. Calc can operate algebraically on -such generic identity matrices, and if one is combined with a matrix -whose size is known, it is converted automatically to an identity -matrix of a suitable matching size. The @kbd{v i} command with an -argument of zero creates a generic identity matrix, @samp{idn(1)}. -Note that in dimensioned Matrix mode (@pxref{Matrix Mode}), generic -identity matrices are immediately expanded to the current default -dimensions. - -@kindex v x -@kindex V x -@pindex calc-index -@tindex index -The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector -of consecutive integers from 1 to @var{n}, where @var{n} is the numeric -prefix argument. If you do not provide a prefix argument, you will be -prompted to enter a suitable number. If @var{n} is negative, the result -is a vector of negative integers from @var{n} to @mathit{-1}. - -With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes -three values from the stack: @var{n}, @var{start}, and @var{incr} (with -@var{incr} at top-of-stack). Counting starts at @var{start} and increases -by @var{incr} for successive vector elements. If @var{start} or @var{n} -is in floating-point format, the resulting vector elements will also be -floats. Note that @var{start} and @var{incr} may in fact be any kind -of numbers or formulas. - -When @var{start} and @var{incr} are specified, a negative @var{n} has a -different interpretation: It causes a geometric instead of arithmetic -sequence to be generated. For example, @samp{index(-3, a, b)} produces -@samp{[a, a b, a b^2]}. If you omit @var{incr} in the algebraic form, -@samp{index(@var{n}, @var{start})}, the default value for @var{incr} -is one for positive @var{n} or two for negative @var{n}. - -@kindex v b -@kindex V b -@pindex calc-build-vector -@tindex cvec -The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a -vector of @var{n} copies of the value on the top of the stack, where @var{n} -is the numeric prefix argument. In algebraic formulas, @samp{cvec(x,n,m)} -can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}. -(Interactively, just use @kbd{v b} twice: once to build a row, then again -to build a matrix of copies of that row.) - -@kindex v h -@kindex V h -@kindex I v h -@kindex I V h -@pindex calc-head -@pindex calc-tail -@tindex head -@tindex tail -The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first -element of a vector. The @kbd{I v h} (@code{calc-tail}) [@code{tail}] -function returns the vector with its first element removed. In both -cases, the argument must be a non-empty vector. - -@kindex v k -@kindex V k -@pindex calc-cons -@tindex cons -The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h} -and a vector @var{t} from the stack, and produces the vector whose head is -@var{h} and whose tail is @var{t}. This is similar to @kbd{|}, except -if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors -whereas @code{cons} will insert @var{h} at the front of the vector @var{t}. - -@kindex H v h -@kindex H V h -@tindex rhead -@ignore -@mindex @idots -@end ignore -@kindex H I v h -@kindex H I V h -@ignore -@mindex @null -@end ignore -@kindex H v k -@kindex H V k -@ignore -@mindex @null -@end ignore -@tindex rtail -@ignore -@mindex @null -@end ignore -@tindex rcons -Each of these three functions also accepts the Hyperbolic flag [@code{rhead}, -@code{rtail}, @code{rcons}] in which case @var{t} instead represents -the @emph{last} single element of the vector, with @var{h} -representing the remainder of the vector. Thus the vector -@samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}. -Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]}, -@samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}. - -@node Extracting Elements, Manipulating Vectors, Building Vectors, Matrix Functions -@section Extracting Vector Elements - -@noindent -@kindex v r -@kindex V r -@pindex calc-mrow -@tindex mrow -The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of -the matrix on the top of the stack, or one element of the plain vector on -the top of the stack. The row or element is specified by the numeric -prefix argument; the default is to prompt for the row or element number. -The matrix or vector is replaced by the specified row or element in the -form of a vector or scalar, respectively. - -@cindex Permutations, applying -With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of -the element or row from the top of the stack, and the vector or matrix -from the second-to-top position. If the index is itself a vector of -integers, the result is a vector of the corresponding elements of the -input vector, or a matrix of the corresponding rows of the input matrix. -This command can be used to obtain any permutation of a vector. - -With @kbd{C-u}, if the index is an interval form with integer components, -it is interpreted as a range of indices and the corresponding subvector or -submatrix is returned. - -@cindex Subscript notation -@kindex a _ -@pindex calc-subscript -@tindex subscr -@tindex _ -Subscript notation in algebraic formulas (@samp{a_b}) stands for the -Calc function @code{subscr}, which is synonymous with @code{mrow}. -Thus, @samp{[x, y, z]_k} produces @expr{x}, @expr{y}, or @expr{z} if -@expr{k} is one, two, or three, respectively. A double subscript -(@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will -access the element at row @expr{i}, column @expr{j} of a matrix. -The @kbd{a _} (@code{calc-subscript}) command creates a subscript -formula @samp{a_b} out of two stack entries. (It is on the @kbd{a} -``algebra'' prefix because subscripted variables are often used -purely as an algebraic notation.) - -@tindex mrrow -Given a negative prefix argument, @kbd{v r} instead deletes one row or -element from the matrix or vector on the top of the stack. Thus -@kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r} -replaces the matrix with the same matrix with its second row removed. -In algebraic form this function is called @code{mrrow}. - -@tindex getdiag -Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements -of a square matrix in the form of a vector. In algebraic form this -function is called @code{getdiag}. - -@kindex v c -@kindex V c -@pindex calc-mcol -@tindex mcol -@tindex mrcol -The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is -the analogous operation on columns of a matrix. Given a plain vector -it extracts (or removes) one element, just like @kbd{v r}. If the -index in @kbd{C-u v c} is an interval or vector and the argument is a -matrix, the result is a submatrix with only the specified columns -retained (and possibly permuted in the case of a vector index). - -To extract a matrix element at a given row and column, use @kbd{v r} to -extract the row as a vector, then @kbd{v c} to extract the column element -from that vector. In algebraic formulas, it is often more convenient to -use subscript notation: @samp{m_i_j} gives row @expr{i}, column @expr{j} -of matrix @expr{m}. - -@kindex v s -@kindex V s -@pindex calc-subvector -@tindex subvec -The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts -a subvector of a vector. The arguments are the vector, the starting -index, and the ending index, with the ending index in the top-of-stack -position. The starting index indicates the first element of the vector -to take. The ending index indicates the first element @emph{past} the -range to be taken. Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces -the subvector @samp{[b, c]}. You could get the same result using -@samp{mrow([a, b, c, d, e], @w{[2 .. 4)})}. - -If either the start or the end index is zero or negative, it is -interpreted as relative to the end of the vector. Thus -@samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}. In -the algebraic form, the end index can be omitted in which case it -is taken as zero, i.e., elements from the starting element to the -end of the vector are used. The infinity symbol, @code{inf}, also -has this effect when used as the ending index. - -@kindex I v s -@kindex I V s -@tindex rsubvec -With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector -from a vector. The arguments are interpreted the same as for the -normal @kbd{v s} command. Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)} -produces @samp{[a, d, e]}. It is always true that @code{subvec} and -@code{rsubvec} return complementary parts of the input vector. - -@xref{Selecting Subformulas}, for an alternative way to operate on -vectors one element at a time. - -@node Manipulating Vectors, Vector and Matrix Arithmetic, Extracting Elements, Matrix Functions -@section Manipulating Vectors - -@noindent -@kindex v l -@kindex V l -@pindex calc-vlength -@tindex vlen -The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the -length of a vector. The length of a non-vector is considered to be zero. -Note that matrices are just vectors of vectors for the purposes of this -command. - -@kindex H v l -@kindex H V l -@tindex mdims -With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector -of the dimensions of a vector, matrix, or higher-order object. For -example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since -its argument is a -@texline @math{2\times3} -@infoline 2x3 -matrix. - -@kindex v f -@kindex V f -@pindex calc-vector-find -@tindex find -The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches -along a vector for the first element equal to a given target. The target -is on the top of the stack; the vector is in the second-to-top position. -If a match is found, the result is the index of the matching element. -Otherwise, the result is zero. The numeric prefix argument, if given, -allows you to select any starting index for the search. - -@kindex v a -@kindex V a -@pindex calc-arrange-vector -@tindex arrange -@cindex Arranging a matrix -@cindex Reshaping a matrix -@cindex Flattening a matrix -The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command -rearranges a vector to have a certain number of columns and rows. The -numeric prefix argument specifies the number of columns; if you do not -provide an argument, you will be prompted for the number of columns. -The vector or matrix on the top of the stack is @dfn{flattened} into a -plain vector. If the number of columns is nonzero, this vector is -then formed into a matrix by taking successive groups of @var{n} elements. -If the number of columns does not evenly divide the number of elements -in the vector, the last row will be short and the result will not be -suitable for use as a matrix. For example, with the matrix -@samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces -@samp{[[1, 2, 3, 4]]} (a -@texline @math{1\times4} -@infoline 1x4 -matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a -@texline @math{4\times1} -@infoline 4x1 -matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original -@texline @math{2\times2} -@infoline 2x2 -matrix), @w{@kbd{v a 3}} produces @samp{[[1, 2, 3], [4]]} (not a -matrix), and @kbd{v a 0} produces the flattened list -@samp{[1, 2, @w{3, 4}]}. - -@cindex Sorting data -@kindex v S -@kindex V S -@kindex I v S -@kindex I V S -@pindex calc-sort -@tindex sort -@tindex rsort -The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of -a vector into increasing order. Real numbers, real infinities, and -constant interval forms come first in this ordering; next come other -kinds of numbers, then variables (in alphabetical order), then finally -come formulas and other kinds of objects; these are sorted according -to a kind of lexicographic ordering with the useful property that -one vector is less or greater than another if the first corresponding -unequal elements are less or greater, respectively. Since quoted strings -are stored by Calc internally as vectors of ASCII character codes -(@pxref{Strings}), this means vectors of strings are also sorted into -alphabetical order by this command. - -The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order. - -@cindex Permutation, inverse of -@cindex Inverse of permutation -@cindex Index tables -@cindex Rank tables -@kindex v G -@kindex V G -@kindex I v G -@kindex I V G -@pindex calc-grade -@tindex grade -@tindex rgrade -The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command -produces an index table or permutation vector which, if applied to the -input vector (as the index of @kbd{C-u v r}, say), would sort the vector. -A permutation vector is just a vector of integers from 1 to @var{n}, where -each integer occurs exactly once. One application of this is to sort a -matrix of data rows using one column as the sort key; extract that column, -grade it with @kbd{V G}, then use the result to reorder the original matrix -with @kbd{C-u v r}. Another interesting property of the @code{V G} command -is that, if the input is itself a permutation vector, the result will -be the inverse of the permutation. The inverse of an index table is -a rank table, whose @var{k}th element says where the @var{k}th original -vector element will rest when the vector is sorted. To get a rank -table, just use @kbd{V G V G}. - -With the Inverse flag, @kbd{I V G} produces an index table that would -sort the input into decreasing order. Note that @kbd{V S} and @kbd{V G} -use a ``stable'' sorting algorithm, i.e., any two elements which are equal -will not be moved out of their original order. Generally there is no way -to tell with @kbd{V S}, since two elements which are equal look the same, -but with @kbd{V G} this can be an important issue. In the matrix-of-rows -example, suppose you have names and telephone numbers as two columns and -you wish to sort by phone number primarily, and by name when the numbers -are equal. You can sort the data matrix by names first, and then again -by phone numbers. Because the sort is stable, any two rows with equal -phone numbers will remain sorted by name even after the second sort. - -@cindex Histograms -@kindex v H -@kindex V H -@pindex calc-histogram -@ignore -@mindex histo@idots -@end ignore -@tindex histogram -The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a -histogram of a vector of numbers. Vector elements are assumed to be -integers or real numbers in the range [0..@var{n}) for some ``number of -bins'' @var{n}, which is the numeric prefix argument given to the -command. The result is a vector of @var{n} counts of how many times -each value appeared in the original vector. Non-integers in the input -are rounded down to integers. Any vector elements outside the specified -range are ignored. (You can tell if elements have been ignored by noting -that the counts in the result vector don't add up to the length of the -input vector.) - -If no prefix is given, then you will be prompted for a vector which -will be used to determine the bins. (If a positive integer is given at -this prompt, it will be still treated as if it were given as a -prefix.) Each bin will consist of the interval of numbers closest to -the corresponding number of this new vector; if the vector -@expr{[a, b, c, ...]} is entered at the prompt, the bins will be -@expr{(-inf, (a+b)/2]}, @expr{((a+b)/2, (b+c)/2]}, etc. The result of -this command will be a vector counting how many elements of the -original vector are in each bin. - -The result will then be a vector with the same length as this new vector; -each element of the new vector will be replaced by the number of -elements of the original vector which are closest to it. - -@kindex H v H -@kindex H V H -With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack. -The second-to-top vector is the list of numbers as before. The top -vector is an equal-sized list of ``weights'' to attach to the elements -of the data vector. For example, if the first data element is 4.2 and -the first weight is 10, then 10 will be added to bin 4 of the result -vector. Without the hyperbolic flag, every element has a weight of one. - -@kindex v t -@kindex V t -@pindex calc-transpose -@tindex trn -The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes -the transpose of the matrix at the top of the stack. If the argument -is a plain vector, it is treated as a row vector and transposed into -a one-column matrix. - -@kindex v v -@kindex V v -@pindex calc-reverse-vector -@tindex rev -The @kbd{v v} (@code{calc-reverse-vector}) [@code{rev}] command reverses -a vector end-for-end. Given a matrix, it reverses the order of the rows. -(To reverse the columns instead, just use @kbd{v t v v v t}. The same -principle can be used to apply other vector commands to the columns of -a matrix.) - -@kindex v m -@kindex V m -@pindex calc-mask-vector -@tindex vmask -The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses -one vector as a mask to extract elements of another vector. The mask -is in the second-to-top position; the target vector is on the top of -the stack. These vectors must have the same length. The result is -the same as the target vector, but with all elements which correspond -to zeros in the mask vector deleted. Thus, for example, -@samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}. -@xref{Logical Operations}. - -@kindex v e -@kindex V e -@pindex calc-expand-vector -@tindex vexp -The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command -expands a vector according to another mask vector. The result is a -vector the same length as the mask, but with nonzero elements replaced -by successive elements from the target vector. The length of the target -vector is normally the number of nonzero elements in the mask. If the -target vector is longer, its last few elements are lost. If the target -vector is shorter, the last few nonzero mask elements are left -unreplaced in the result. Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])} -produces @samp{[a, 0, b, 0, 7]}. - -@kindex H v e -@kindex H V e -With the Hyperbolic flag, @kbd{H v e} takes a filler value from the -top of the stack; the mask and target vectors come from the third and -second elements of the stack. This filler is used where the mask is -zero: @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces -@samp{[a, z, c, z, 7]}. If the filler value is itself a vector, -then successive values are taken from it, so that the effect is to -interleave two vectors according to the mask: -@samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces -@samp{[a, x, b, 7, y, 0]}. - -Another variation on the masking idea is to combine @samp{[a, b, c, d, e]} -with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}. -You can accomplish this with @kbd{V M a &}, mapping the logical ``and'' -operation across the two vectors. @xref{Logical Operations}. Note that -the @code{? :} operation also discussed there allows other types of -masking using vectors. - -@node Vector and Matrix Arithmetic, Set Operations, Manipulating Vectors, Matrix Functions -@section Vector and Matrix Arithmetic - -@noindent -Basic arithmetic operations like addition and multiplication are defined -for vectors and matrices as well as for numbers. Division of matrices, in -the sense of multiplying by the inverse, is supported. (Division by a -matrix actually uses LU-decomposition for greater accuracy and speed.) -@xref{Basic Arithmetic}. - -The following functions are applied element-wise if their arguments are -vectors or matrices: @code{change-sign}, @code{conj}, @code{arg}, -@code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean}, -@code{float}, @code{frac}. @xref{Function Index}. - -@kindex v J -@kindex V J -@pindex calc-conj-transpose -@tindex ctrn -The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes -the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}. - -@ignore -@mindex A -@end ignore -@kindex A (vectors) -@pindex calc-abs (vectors) -@ignore -@mindex abs -@end ignore -@tindex abs (vectors) -The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the -Frobenius norm of a vector or matrix argument. This is the square -root of the sum of the squares of the absolute values of the -elements of the vector or matrix. If the vector is interpreted as -a point in two- or three-dimensional space, this is the distance -from that point to the origin. - -@kindex v n -@kindex V n -@pindex calc-rnorm -@tindex rnorm -The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes the -infinity-norm of a vector, or the row norm of a matrix. For a plain -vector, this is the maximum of the absolute values of the elements. For -a matrix, this is the maximum of the row-absolute-value-sums, i.e., of -the sums of the absolute values of the elements along the various rows. - -@kindex v N -@kindex V N -@pindex calc-cnorm -@tindex cnorm -The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes -the one-norm of a vector, or column norm of a matrix. For a plain -vector, this is the sum of the absolute values of the elements. -For a matrix, this is the maximum of the column-absolute-value-sums. -General @expr{k}-norms for @expr{k} other than one or infinity are -not provided. However, the 2-norm (or Frobenius norm) is provided for -vectors by the @kbd{A} (@code{calc-abs}) command. - -@kindex v C -@kindex V C -@pindex calc-cross -@tindex cross -The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the -right-handed cross product of two vectors, each of which must have -exactly three elements. - -@ignore -@mindex & -@end ignore -@kindex & (matrices) -@pindex calc-inv (matrices) -@ignore -@mindex inv -@end ignore -@tindex inv (matrices) -The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the -inverse of a square matrix. If the matrix is singular, the inverse -operation is left in symbolic form. Matrix inverses are recorded so -that once an inverse (or determinant) of a particular matrix has been -computed, the inverse and determinant of the matrix can be recomputed -quickly in the future. - -If the argument to @kbd{&} is a plain number @expr{x}, this -command simply computes @expr{1/x}. This is okay, because the -@samp{/} operator also does a matrix inversion when dividing one -by a matrix. - -@kindex v D -@kindex V D -@pindex calc-mdet -@tindex det -The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the -determinant of a square matrix. - -@kindex v L -@kindex V L -@pindex calc-mlud -@tindex lud -The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the -LU decomposition of a matrix. The result is a list of three matrices -which, when multiplied together left-to-right, form the original matrix. -The first is a permutation matrix that arises from pivoting in the -algorithm, the second is lower-triangular with ones on the diagonal, -and the third is upper-triangular. - -@kindex v T -@kindex V T -@pindex calc-mtrace -@tindex tr -The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the -trace of a square matrix. This is defined as the sum of the diagonal -elements of the matrix. - -@kindex v K -@kindex V K -@pindex calc-kron -@tindex kron -The @kbd{V K} (@code{calc-kron}) [@code{kron}] command computes -the Kronecker product of two matrices. - -@node Set Operations, Statistical Operations, Vector and Matrix Arithmetic, Matrix Functions -@section Set Operations using Vectors - -@noindent -@cindex Sets, as vectors -Calc includes several commands which interpret vectors as @dfn{sets} of -objects. A set is a collection of objects; any given object can appear -only once in the set. Calc stores sets as vectors of objects in -sorted order. Objects in a Calc set can be any of the usual things, -such as numbers, variables, or formulas. Two set elements are considered -equal if they are identical, except that numerically equal numbers like -the integer 4 and the float 4.0 are considered equal even though they -are not ``identical.'' Variables are treated like plain symbols without -attached values by the set operations; subtracting the set @samp{[b]} -from @samp{[a, b]} always yields the set @samp{[a]} even though if -the variables @samp{a} and @samp{b} both equaled 17, you might -expect the answer @samp{[]}. - -If a set contains interval forms, then it is assumed to be a set of -real numbers. In this case, all set operations require the elements -of the set to be only things that are allowed in intervals: Real -numbers, plus and minus infinity, HMS forms, and date forms. If -there are variables or other non-real objects present in a real set, -all set operations on it will be left in unevaluated form. - -If the input to a set operation is a plain number or interval form -@var{a}, it is treated like the one-element vector @samp{[@var{a}]}. -The result is always a vector, except that if the set consists of a -single interval, the interval itself is returned instead. - -@xref{Logical Operations}, for the @code{in} function which tests if -a certain value is a member of a given set. To test if the set @expr{A} -is a subset of the set @expr{B}, use @samp{vdiff(A, B) = []}. - -@kindex v + -@kindex V + -@pindex calc-remove-duplicates -@tindex rdup -The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command -converts an arbitrary vector into set notation. It works by sorting -the vector as if by @kbd{V S}, then removing duplicates. (For example, -@kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then -reduced to @samp{[4, 5, a]}). Overlapping intervals are merged as -necessary. You rarely need to use @kbd{V +} explicitly, since all the -other set-based commands apply @kbd{V +} to their inputs before using -them. - -@kindex v V -@kindex V V -@pindex calc-set-union -@tindex vunion -The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes -the union of two sets. An object is in the union of two sets if and -only if it is in either (or both) of the input sets. (You could -accomplish the same thing by concatenating the sets with @kbd{|}, -then using @kbd{V +}.) - -@kindex v ^ -@kindex V ^ -@pindex calc-set-intersect -@tindex vint -The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes -the intersection of two sets. An object is in the intersection if -and only if it is in both of the input sets. Thus if the input -sets are disjoint, i.e., if they share no common elements, the result -will be the empty vector @samp{[]}. Note that the characters @kbd{V} -and @kbd{^} were chosen to be close to the conventional mathematical -notation for set -@texline union@tie{}(@math{A \cup B}) -@infoline union -and -@texline intersection@tie{}(@math{A \cap B}). -@infoline intersection. - -@kindex v - -@kindex V - -@pindex calc-set-difference -@tindex vdiff -The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes -the difference between two sets. An object is in the difference -@expr{A - B} if and only if it is in @expr{A} but not in @expr{B}. -Thus subtracting @samp{[y,z]} from a set will remove the elements -@samp{y} and @samp{z} if they are present. You can also think of this -as a general @dfn{set complement} operator; if @expr{A} is the set of -all possible values, then @expr{A - B} is the ``complement'' of @expr{B}. -Obviously this is only practical if the set of all possible values in -your problem is small enough to list in a Calc vector (or simple -enough to express in a few intervals). - -@kindex v X -@kindex V X -@pindex calc-set-xor -@tindex vxor -The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes -the ``exclusive-or,'' or ``symmetric difference'' of two sets. -An object is in the symmetric difference of two sets if and only -if it is in one, but @emph{not} both, of the sets. Objects that -occur in both sets ``cancel out.'' - -@kindex v ~ -@kindex V ~ -@pindex calc-set-complement -@tindex vcompl -The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command -computes the complement of a set with respect to the real numbers. -Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}. -For example, @samp{vcompl([2, (3 .. 4]])} evaluates to -@samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}. - -@kindex v F -@kindex V F -@pindex calc-set-floor -@tindex vfloor -The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command -reinterprets a set as a set of integers. Any non-integer values, -and intervals that do not enclose any integers, are removed. Open -intervals are converted to equivalent closed intervals. Successive -integers are converted into intervals of integers. For example, the -complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted -the complement with respect to the set of integers you could type -@kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}. - -@kindex v E -@kindex V E -@pindex calc-set-enumerate -@tindex venum -The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command -converts a set of integers into an explicit vector. Intervals in -the set are expanded out to lists of all integers encompassed by -the intervals. This only works for finite sets (i.e., sets which -do not involve @samp{-inf} or @samp{inf}). - -@kindex v : -@kindex V : -@pindex calc-set-span -@tindex vspan -The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any -set of reals into an interval form that encompasses all its elements. -The lower limit will be the smallest element in the set; the upper -limit will be the largest element. For an empty set, @samp{vspan([])} -returns the empty interval @w{@samp{[0 .. 0)}}. - -@kindex v # -@kindex V # -@pindex calc-set-cardinality -@tindex vcard -The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts -the number of integers in a set. The result is the length of the vector -that would be produced by @kbd{V E}, although the computation is much -more efficient than actually producing that vector. - -@cindex Sets, as binary numbers -Another representation for sets that may be more appropriate in some -cases is binary numbers. If you are dealing with sets of integers -in the range 0 to 49, you can use a 50-bit binary number where a -particular bit is 1 if the corresponding element is in the set. -@xref{Binary Functions}, for a list of commands that operate on -binary numbers. Note that many of the above set operations have -direct equivalents in binary arithmetic: @kbd{b o} (@code{calc-or}), -@kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}), -@kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}), -respectively. You can use whatever representation for sets is most -convenient to you. - -@kindex b p -@kindex b u -@pindex calc-pack-bits -@pindex calc-unpack-bits -@tindex vpack -@tindex vunpack -The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command -converts an integer that represents a set in binary into a set -in vector/interval notation. For example, @samp{vunpack(67)} -returns @samp{[[0 .. 1], 6]}. If the input is negative, the set -it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}. -Use @kbd{V E} afterwards to expand intervals to individual -values if you wish. Note that this command uses the @kbd{b} -(binary) prefix key. - -The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command -converts the other way, from a vector or interval representing -a set of nonnegative integers into a binary integer describing -the same set. The set may include positive infinity, but must -not include any negative numbers. The input is interpreted as a -set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware -that a simple input like @samp{[100]} can result in a huge integer -representation -@texline (@math{2^{100}}, a 31-digit integer, in this case). -@infoline (@expr{2^100}, a 31-digit integer, in this case). - -@node Statistical Operations, Reducing and Mapping, Set Operations, Matrix Functions -@section Statistical Operations on Vectors - -@noindent -@cindex Statistical functions -The commands in this section take vectors as arguments and compute -various statistical measures on the data stored in the vectors. The -references used in the definitions of these functions are Bevington's -@emph{Data Reduction and Error Analysis for the Physical Sciences}, -and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and -Vetterling. - -The statistical commands use the @kbd{u} prefix key followed by -a shifted letter or other character. - -@xref{Manipulating Vectors}, for a description of @kbd{V H} -(@code{calc-histogram}). - -@xref{Curve Fitting}, for the @kbd{a F} command for doing -least-squares fits to statistical data. - -@xref{Probability Distribution Functions}, for several common -probability distribution functions. - -@menu -* Single-Variable Statistics:: -* Paired-Sample Statistics:: -@end menu - -@node Single-Variable Statistics, Paired-Sample Statistics, Statistical Operations, Statistical Operations -@subsection Single-Variable Statistics - -@noindent -These functions do various statistical computations on single -vectors. Given a numeric prefix argument, they actually pop -@var{n} objects from the stack and combine them into a data -vector. Each object may be either a number or a vector; if a -vector, any sub-vectors inside it are ``flattened'' as if by -@kbd{v a 0}; @pxref{Manipulating Vectors}. By default one object -is popped, which (in order to be useful) is usually a vector. - -If an argument is a variable name, and the value stored in that -variable is a vector, then the stored vector is used. This method -has the advantage that if your data vector is large, you can avoid -the slow process of manipulating it directly on the stack. - -These functions are left in symbolic form if any of their arguments -are not numbers or vectors, e.g., if an argument is a formula, or -a non-vector variable. However, formulas embedded within vector -arguments are accepted; the result is a symbolic representation -of the computation, based on the assumption that the formula does -not itself represent a vector. All varieties of numbers such as -error forms and interval forms are acceptable. - -Some of the functions in this section also accept a single error form -or interval as an argument. They then describe a property of the -normal or uniform (respectively) statistical distribution described -by the argument. The arguments are interpreted in the same way as -the @var{M} argument of the random number function @kbd{k r}. In -particular, an interval with integer limits is considered an integer -distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}. -An interval with at least one floating-point limit is a continuous -distribution: @samp{[2.0 .. 6.0)} is @emph{not} the same as -@samp{[2.0 .. 5.0]}! - -@kindex u # -@pindex calc-vector-count -@tindex vcount -The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command -computes the number of data values represented by the inputs. -For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7. -If the argument is a single vector with no sub-vectors, this -simply computes the length of the vector. - -@kindex u + -@kindex u * -@pindex calc-vector-sum -@pindex calc-vector-prod -@tindex vsum -@tindex vprod -@cindex Summations (statistical) -The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command -computes the sum of the data values. The @kbd{u *} -(@code{calc-vector-prod}) [@code{vprod}] command computes the -product of the data values. If the input is a single flat vector, -these are the same as @kbd{V R +} and @kbd{V R *} -(@pxref{Reducing and Mapping}). - -@kindex u X -@kindex u N -@pindex calc-vector-max -@pindex calc-vector-min -@tindex vmax -@tindex vmin -The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command -computes the maximum of the data values, and the @kbd{u N} -(@code{calc-vector-min}) [@code{vmin}] command computes the minimum. -If the argument is an interval, this finds the minimum or maximum -value in the interval. (Note that @samp{vmax([2..6)) = 5} as -described above.) If the argument is an error form, this returns -plus or minus infinity. - -@kindex u M -@pindex calc-vector-mean -@tindex vmean -@cindex Mean of data values -The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command -computes the average (arithmetic mean) of the data values. -If the inputs are error forms -@texline @math{x \pm \sigma}, -@infoline @samp{x +/- s}, -this is the weighted mean of the @expr{x} values with weights -@texline @math{1 /\sigma^2}. -@infoline @expr{1 / s^2}. -@tex -$$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over - \displaystyle \sum { 1 \over \sigma_i^2 } } $$ -@end tex -If the inputs are not error forms, this is simply the sum of the -values divided by the count of the values. - -Note that a plain number can be considered an error form with -error -@texline @math{\sigma = 0}. -@infoline @expr{s = 0}. -If the input to @kbd{u M} is a mixture of -plain numbers and error forms, the result is the mean of the -plain numbers, ignoring all values with non-zero errors. (By the -above definitions it's clear that a plain number effectively -has an infinite weight, next to which an error form with a finite -weight is completely negligible.) - -This function also works for distributions (error forms or -intervals). The mean of an error form `@var{a} @tfn{+/-} @var{b}' is simply -@expr{a}. The mean of an interval is the mean of the minimum -and maximum values of the interval. - -@kindex I u M -@pindex calc-vector-mean-error -@tindex vmeane -The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}] -command computes the mean of the data points expressed as an -error form. This includes the estimated error associated with -the mean. If the inputs are error forms, the error is the square -root of the reciprocal of the sum of the reciprocals of the squares -of the input errors. (I.e., the variance is the reciprocal of the -sum of the reciprocals of the variances.) -@tex -$$ \sigma_\mu^2 = {1 \over \displaystyle \sum {1 \over \sigma_i^2}} $$ -@end tex -If the inputs are plain -numbers, the error is equal to the standard deviation of the values -divided by the square root of the number of values. (This works -out to be equivalent to calculating the standard deviation and -then assuming each value's error is equal to this standard -deviation.) -@tex -$$ \sigma_\mu^2 = {\sigma^2 \over N} $$ -@end tex - -@kindex H u M -@pindex calc-vector-median -@tindex vmedian -@cindex Median of data values -The @kbd{H u M} (@code{calc-vector-median}) [@code{vmedian}] -command computes the median of the data values. The values are -first sorted into numerical order; the median is the middle -value after sorting. (If the number of data values is even, -the median is taken to be the average of the two middle values.) -The median function is different from the other functions in -this section in that the arguments must all be real numbers; -variables are not accepted even when nested inside vectors. -(Otherwise it is not possible to sort the data values.) If -any of the input values are error forms, their error parts are -ignored. - -The median function also accepts distributions. For both normal -(error form) and uniform (interval) distributions, the median is -the same as the mean. - -@kindex H I u M -@pindex calc-vector-harmonic-mean -@tindex vhmean -@cindex Harmonic mean -The @kbd{H I u M} (@code{calc-vector-harmonic-mean}) [@code{vhmean}] -command computes the harmonic mean of the data values. This is -defined as the reciprocal of the arithmetic mean of the reciprocals -of the values. -@tex -$$ { N \over \displaystyle \sum {1 \over x_i} } $$ -@end tex - -@kindex u G -@pindex calc-vector-geometric-mean -@tindex vgmean -@cindex Geometric mean -The @kbd{u G} (@code{calc-vector-geometric-mean}) [@code{vgmean}] -command computes the geometric mean of the data values. This -is the @var{n}th root of the product of the values. This is also -equal to the @code{exp} of the arithmetic mean of the logarithms -of the data values. -@tex -$$ \exp \left ( \sum { \ln x_i } \right ) = - \left ( \prod { x_i } \right)^{1 / N} $$ -@end tex - -@kindex H u G -@tindex agmean -The @kbd{H u G} [@code{agmean}] command computes the ``arithmetic-geometric -mean'' of two numbers taken from the stack. This is computed by -replacing the two numbers with their arithmetic mean and geometric -mean, then repeating until the two values converge. -@tex -$$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$ -@end tex - -@c @cindex Root-mean-square -@c Another commonly used mean, the RMS (root-mean-square), can be computed -@c for a vector of numbers simply by using the @kbd{A} command. - -@kindex u S -@pindex calc-vector-sdev -@tindex vsdev -@cindex Standard deviation -@cindex Sample statistics -The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command -computes the standard -@texline deviation@tie{}@math{\sigma} -@infoline deviation -of the data values. If the values are error forms, the errors are used -as weights just as for @kbd{u M}. This is the @emph{sample} standard -deviation, whose value is the square root of the sum of the squares of -the differences between the values and the mean of the @expr{N} values, -divided by @expr{N-1}. -@tex -$$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$ -@end tex - -This function also applies to distributions. The standard deviation -of a single error form is simply the error part. The standard deviation -of a continuous interval happens to equal the difference between the -limits, divided by -@texline @math{\sqrt{12}}. -@infoline @expr{sqrt(12)}. -The standard deviation of an integer interval is the same as the -standard deviation of a vector of those integers. - -@kindex I u S -@pindex calc-vector-pop-sdev -@tindex vpsdev -@cindex Population statistics -The @kbd{I u S} (@code{calc-vector-pop-sdev}) [@code{vpsdev}] -command computes the @emph{population} standard deviation. -It is defined by the same formula as above but dividing -by @expr{N} instead of by @expr{N-1}. The population standard -deviation is used when the input represents the entire set of -data values in the distribution; the sample standard deviation -is used when the input represents a sample of the set of all -data values, so that the mean computed from the input is itself -only an estimate of the true mean. -@tex -$$ \sigma^2 = {1 \over N} \sum (x_i - \mu)^2 $$ -@end tex - -For error forms and continuous intervals, @code{vpsdev} works -exactly like @code{vsdev}. For integer intervals, it computes the -population standard deviation of the equivalent vector of integers. - -@kindex H u S -@kindex H I u S -@pindex calc-vector-variance -@pindex calc-vector-pop-variance -@tindex vvar -@tindex vpvar -@cindex Variance of data values -The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and -@kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}] -commands compute the variance of the data values. The variance -is the -@texline square@tie{}@math{\sigma^2} -@infoline square -of the standard deviation, i.e., the sum of the -squares of the deviations of the data values from the mean. -(This definition also applies when the argument is a distribution.) - -@ignore -@starindex -@end ignore -@tindex vflat -The @code{vflat} algebraic function returns a vector of its -arguments, interpreted in the same way as the other functions -in this section. For example, @samp{vflat(1, [2, [3, 4]], 5)} -returns @samp{[1, 2, 3, 4, 5]}. - -@node Paired-Sample Statistics, , Single-Variable Statistics, Statistical Operations -@subsection Paired-Sample Statistics - -@noindent -The functions in this section take two arguments, which must be -vectors of equal size. The vectors are each flattened in the same -way as by the single-variable statistical functions. Given a numeric -prefix argument of 1, these functions instead take one object from -the stack, which must be an -@texline @math{N\times2} -@infoline Nx2 -matrix of data values. Once again, variable names can be used in place -of actual vectors and matrices. - -@kindex u C -@pindex calc-vector-covariance -@tindex vcov -@cindex Covariance -The @kbd{u C} (@code{calc-vector-covariance}) [@code{vcov}] command -computes the sample covariance of two vectors. The covariance -of vectors @var{x} and @var{y} is the sum of the products of the -differences between the elements of @var{x} and the mean of @var{x} -times the differences between the corresponding elements of @var{y} -and the mean of @var{y}, all divided by @expr{N-1}. Note that -the variance of a vector is just the covariance of the vector -with itself. Once again, if the inputs are error forms the -errors are used as weight factors. If both @var{x} and @var{y} -are composed of error forms, the error for a given data point -is taken as the square root of the sum of the squares of the two -input errors. -@tex -$$ \sigma_{x\!y}^2 = {1 \over N-1} \sum (x_i - \mu_x) (y_i - \mu_y) $$ -$$ \sigma_{x\!y}^2 = - {\displaystyle {1 \over N-1} - \sum {(x_i - \mu_x) (y_i - \mu_y) \over \sigma_i^2} - \over \displaystyle {1 \over N} \sum {1 \over \sigma_i^2}} -$$ -@end tex - -@kindex I u C -@pindex calc-vector-pop-covariance -@tindex vpcov -The @kbd{I u C} (@code{calc-vector-pop-covariance}) [@code{vpcov}] -command computes the population covariance, which is the same as the -sample covariance computed by @kbd{u C} except dividing by @expr{N} -instead of @expr{N-1}. - -@kindex H u C -@pindex calc-vector-correlation -@tindex vcorr -@cindex Correlation coefficient -@cindex Linear correlation -The @kbd{H u C} (@code{calc-vector-correlation}) [@code{vcorr}] -command computes the linear correlation coefficient of two vectors. -This is defined by the covariance of the vectors divided by the -product of their standard deviations. (There is no difference -between sample or population statistics here.) -@tex -$$ r_{x\!y} = { \sigma_{x\!y}^2 \over \sigma_x^2 \sigma_y^2 } $$ -@end tex - -@node Reducing and Mapping, Vector and Matrix Formats, Statistical Operations, Matrix Functions -@section Reducing and Mapping Vectors - -@noindent -The commands in this section allow for more general operations on the -elements of vectors. - -@kindex v A -@kindex V A -@pindex calc-apply -@tindex apply -The simplest of these operations is @kbd{V A} (@code{calc-apply}) -[@code{apply}], which applies a given operator to the elements of a vector. -For example, applying the hypothetical function @code{f} to the vector -@w{@samp{[1, 2, 3]}} would produce the function call @samp{f(1, 2, 3)}. -Applying the @code{+} function to the vector @samp{[a, b]} gives -@samp{a + b}. Applying @code{+} to the vector @samp{[a, b, c]} is an -error, since the @code{+} function expects exactly two arguments. - -While @kbd{V A} is useful in some cases, you will usually find that either -@kbd{V R} or @kbd{V M}, described below, is closer to what you want. - -@menu -* Specifying Operators:: -* Mapping:: -* Reducing:: -* Nesting and Fixed Points:: -* Generalized Products:: -@end menu - -@node Specifying Operators, Mapping, Reducing and Mapping, Reducing and Mapping -@subsection Specifying Operators - -@noindent -Commands in this section (like @kbd{V A}) prompt you to press the key -corresponding to the desired operator. Press @kbd{?} for a partial -list of the available operators. Generally, an operator is any key or -sequence of keys that would normally take one or more arguments from -the stack and replace them with a result. For example, @kbd{V A H C} -uses the hyperbolic cosine operator, @code{cosh}. (Since @code{cosh} -expects one argument, @kbd{V A H C} requires a vector with a single -element as its argument.) - -You can press @kbd{x} at the operator prompt to select any algebraic -function by name to use as the operator. This includes functions you -have defined yourself using the @kbd{Z F} command. (@xref{Algebraic -Definitions}.) If you give a name for which no function has been -defined, the result is left in symbolic form, as in @samp{f(1, 2, 3)}. -Calc will prompt for the number of arguments the function takes if it -can't figure it out on its own (say, because you named a function that -is currently undefined). It is also possible to type a digit key before -the function name to specify the number of arguments, e.g., -@kbd{V M 3 x f @key{RET}} calls @code{f} with three arguments even if it -looks like it ought to have only two. This technique may be necessary -if the function allows a variable number of arguments. For example, -the @kbd{v e} [@code{vexp}] function accepts two or three arguments; -if you want to map with the three-argument version, you will have to -type @kbd{V M 3 v e}. - -It is also possible to apply any formula to a vector by treating that -formula as a function. When prompted for the operator to use, press -@kbd{'} (the apostrophe) and type your formula as an algebraic entry. -You will then be prompted for the argument list, which defaults to a -list of all variables that appear in the formula, sorted into alphabetic -order. For example, suppose you enter the formula @w{@samp{x + 2y^x}}. -The default argument list would be @samp{(x y)}, which means that if -this function is applied to the arguments @samp{[3, 10]} the result will -be @samp{3 + 2*10^3}. (If you plan to use a certain formula in this -way often, you might consider defining it as a function with @kbd{Z F}.) - -Another way to specify the arguments to the formula you enter is with -@kbd{$}, @kbd{$$}, and so on. For example, @kbd{V A ' $$ + 2$^$$} -has the same effect as the previous example. The argument list is -automatically taken to be @samp{($$ $)}. (The order of the arguments -may seem backwards, but it is analogous to the way normal algebraic -entry interacts with the stack.) - -If you press @kbd{$} at the operator prompt, the effect is similar to -the apostrophe except that the relevant formula is taken from top-of-stack -instead. The actual vector arguments of the @kbd{V A $} or related command -then start at the second-to-top stack position. You will still be -prompted for an argument list. - -@cindex Nameless functions -@cindex Generic functions -A function can be written without a name using the notation @samp{<#1 - #2>}, -which means ``a function of two arguments that computes the first -argument minus the second argument.'' The symbols @samp{#1} and @samp{#2} -are placeholders for the arguments. You can use any names for these -placeholders if you wish, by including an argument list followed by a -colon: @samp{}. When you type @kbd{V A ' $$ + 2$^$$ @key{RET}}, -Calc builds the nameless function @samp{<#1 + 2 #2^#1>} as the function -to map across the vectors. When you type @kbd{V A ' x + 2y^x @key{RET} @key{RET}}, -Calc builds the nameless function @w{@samp{}}. In both -cases, Calc also writes the nameless function to the Trail so that you -can get it back later if you wish. - -If there is only one argument, you can write @samp{#} in place of @samp{#1}. -(Note that @samp{< >} notation is also used for date forms. Calc tells -that @samp{<@var{stuff}>} is a nameless function by the presence of -@samp{#} signs inside @var{stuff}, or by the fact that @var{stuff} -begins with a list of variables followed by a colon.) - -You can type a nameless function directly to @kbd{V A '}, or put one on -the stack and use it with @w{@kbd{V A $}}. Calc will not prompt for an -argument list in this case, since the nameless function specifies the -argument list as well as the function itself. In @kbd{V A '}, you can -omit the @samp{< >} marks if you use @samp{#} notation for the arguments, -so that @kbd{V A ' #1+#2 @key{RET}} is the same as @kbd{V A ' <#1+#2> @key{RET}}, -which in turn is the same as @kbd{V A ' $$+$ @key{RET}}. - -@cindex Lambda expressions -@ignore -@starindex -@end ignore -@tindex lambda -The internal format for @samp{} is @samp{lambda(x, y, x + y)}. -(The word @code{lambda} derives from Lisp notation and the theory of -functions.) The internal format for @samp{<#1 + #2>} is @samp{lambda(ArgA, -ArgB, ArgA + ArgB)}. Note that there is no actual Calc function called -@code{lambda}; the whole point is that the @code{lambda} expression is -used in its symbolic form, not evaluated for an answer until it is applied -to specific arguments by a command like @kbd{V A} or @kbd{V M}. - -(Actually, @code{lambda} does have one special property: Its arguments -are never evaluated; for example, putting @samp{<(2/3) #>} on the stack -will not simplify the @samp{2/3} until the nameless function is actually -called.) - -@tindex add -@tindex sub -@ignore -@mindex @idots -@end ignore -@tindex mul -@ignore -@mindex @null -@end ignore -@tindex div -@ignore -@mindex @null -@end ignore -@tindex pow -@ignore -@mindex @null -@end ignore -@tindex neg -@ignore -@mindex @null -@end ignore -@tindex mod -@ignore -@mindex @null -@end ignore -@tindex vconcat -As usual, commands like @kbd{V A} have algebraic function name equivalents. -For example, @kbd{V A k g} with an argument of @samp{v} is equivalent to -@samp{apply(gcd, v)}. The first argument specifies the operator name, -and is either a variable whose name is the same as the function name, -or a nameless function like @samp{<#^3+1>}. Operators that are normally -written as algebraic symbols have the names @code{add}, @code{sub}, -@code{mul}, @code{div}, @code{pow}, @code{neg}, @code{mod}, and -@code{vconcat}. - -@ignore -@starindex -@end ignore -@tindex call -The @code{call} function builds a function call out of several arguments: -@samp{call(gcd, x, y)} is the same as @samp{apply(gcd, [x, y])}, which -in turn is the same as @samp{gcd(x, y)}. The first argument of @code{call}, -like the other functions described here, may be either a variable naming a -function, or a nameless function (@samp{call(<#1+2#2>, x, y)} is the same -as @samp{x + 2y}). - -(Experts will notice that it's not quite proper to use a variable to name -a function, since the name @code{gcd} corresponds to the Lisp variable -@code{var-gcd} but to the Lisp function @code{calcFunc-gcd}. Calc -automatically makes this translation, so you don't have to worry -about it.) - -@node Mapping, Reducing, Specifying Operators, Reducing and Mapping -@subsection Mapping - -@noindent -@kindex v M -@kindex V M -@pindex calc-map -@tindex map -The @kbd{V M} (@code{calc-map}) [@code{map}] command applies a given -operator elementwise to one or more vectors. For example, mapping -@code{A} [@code{abs}] produces a vector of the absolute values of the -elements in the input vector. Mapping @code{+} pops two vectors from -the stack, which must be of equal length, and produces a vector of the -pairwise sums of the elements. If either argument is a non-vector, it -is duplicated for each element of the other vector. For example, -@kbd{[1,2,3] 2 V M ^} squares the elements of the specified vector. -With the 2 listed first, it would have computed a vector of powers of -two. Mapping a user-defined function pops as many arguments from the -stack as the function requires. If you give an undefined name, you will -be prompted for the number of arguments to use. - -If any argument to @kbd{V M} is a matrix, the operator is normally mapped -across all elements of the matrix. For example, given the matrix -@expr{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to -produce another -@texline @math{3\times2} -@infoline 3x2 -matrix, @expr{[[1, 2, 3], [4, 5, 6]]}. - -@tindex mapr -The command @kbd{V M _} [@code{mapr}] (i.e., type an underscore at the -operator prompt) maps by rows instead. For example, @kbd{V M _ A} views -the above matrix as a vector of two 3-element row vectors. It produces -a new vector which contains the absolute values of those row vectors, -namely @expr{[3.74, 8.77]}. (Recall, the absolute value of a vector is -defined as the square root of the sum of the squares of the elements.) -Some operators accept vectors and return new vectors; for example, -@kbd{v v} reverses a vector, so @kbd{V M _ v v} would reverse each row -of the matrix to get a new matrix, @expr{[[3, -2, 1], [-6, 5, -4]]}. - -Sometimes a vector of vectors (representing, say, strings, sets, or lists) -happens to look like a matrix. If so, remember to use @kbd{V M _} if you -want to map a function across the whole strings or sets rather than across -their individual elements. - -@tindex mapc -The command @kbd{V M :} [@code{mapc}] maps by columns. Basically, it -transposes the input matrix, maps by rows, and then, if the result is a -matrix, transposes again. For example, @kbd{V M : A} takes the absolute -values of the three columns of the matrix, treating each as a 2-vector, -and @kbd{V M : v v} reverses the columns to get the matrix -@expr{[[-4, 5, -6], [1, -2, 3]]}. - -(The symbols @kbd{_} and @kbd{:} were chosen because they had row-like -and column-like appearances, and were not already taken by useful -operators. Also, they appear shifted on most keyboards so they are easy -to type after @kbd{V M}.) - -The @kbd{_} and @kbd{:} modifiers have no effect on arguments that are -not matrices (so if none of the arguments are matrices, they have no -effect at all). If some of the arguments are matrices and others are -plain numbers, the plain numbers are held constant for all rows of the -matrix (so that @kbd{2 V M _ ^} squares every row of a matrix; squaring -a vector takes a dot product of the vector with itself). - -If some of the arguments are vectors with the same lengths as the -rows (for @kbd{V M _}) or columns (for @kbd{V M :}) of the matrix -arguments, those vectors are also held constant for every row or -column. - -Sometimes it is useful to specify another mapping command as the operator -to use with @kbd{V M}. For example, @kbd{V M _ V A +} applies @kbd{V A +} -to each row of the input matrix, which in turn adds the two values on that -row. If you give another vector-operator command as the operator for -@kbd{V M}, it automatically uses map-by-rows mode if you don't specify -otherwise; thus @kbd{V M V A +} is equivalent to @kbd{V M _ V A +}. (If -you really want to map-by-elements another mapping command, you can use -a triple-nested mapping command: @kbd{V M V M V A +} means to map -@kbd{V M V A +} over the rows of the matrix; in turn, @kbd{V A +} is -mapped over the elements of each row.) - -@tindex mapa -@tindex mapd -Previous versions of Calc had ``map across'' and ``map down'' modes -that are now considered obsolete; the old ``map across'' is now simply -@kbd{V M V A}, and ``map down'' is now @kbd{V M : V A}. The algebraic -functions @code{mapa} and @code{mapd} are still supported, though. -Note also that, while the old mapping modes were persistent (once you -set the mode, it would apply to later mapping commands until you reset -it), the new @kbd{:} and @kbd{_} modifiers apply only to the current -mapping command. The default @kbd{V M} always means map-by-elements. - -@xref{Algebraic Manipulation}, for the @kbd{a M} command, which is like -@kbd{V M} but for equations and inequalities instead of vectors. -@xref{Storing Variables}, for the @kbd{s m} command which modifies a -variable's stored value using a @kbd{V M}-like operator. - -@node Reducing, Nesting and Fixed Points, Mapping, Reducing and Mapping -@subsection Reducing - -@noindent -@kindex v R -@kindex V R -@pindex calc-reduce -@tindex reduce -The @kbd{V R} (@code{calc-reduce}) [@code{reduce}] command applies a given -binary operator across all the elements of a vector. A binary operator is -a function such as @code{+} or @code{max} which takes two arguments. For -example, reducing @code{+} over a vector computes the sum of the elements -of the vector. Reducing @code{-} computes the first element minus each of -the remaining elements. Reducing @code{max} computes the maximum element -and so on. In general, reducing @code{f} over the vector @samp{[a, b, c, d]} -produces @samp{f(f(f(a, b), c), d)}. - -@kindex I v R -@kindex I V R -@tindex rreduce -The @kbd{I V R} [@code{rreduce}] command is similar to @kbd{V R} except -that works from right to left through the vector. For example, plain -@kbd{V R -} on the vector @samp{[a, b, c, d]} produces @samp{a - b - c - d} -but @kbd{I V R -} on the same vector produces @samp{a - (b - (c - d))}, -or @samp{a - b + c - d}. This ``alternating sum'' occurs frequently -in power series expansions. - -@kindex v U -@kindex V U -@tindex accum -The @kbd{V U} (@code{calc-accumulate}) [@code{accum}] command does an -accumulation operation. Here Calc does the corresponding reduction -operation, but instead of producing only the final result, it produces -a vector of all the intermediate results. Accumulating @code{+} over -the vector @samp{[a, b, c, d]} produces the vector -@samp{[a, a + b, a + b + c, a + b + c + d]}. - -@kindex I v U -@kindex I V U -@tindex raccum -The @kbd{I V U} [@code{raccum}] command does a right-to-left accumulation. -For example, @kbd{I V U -} on the vector @samp{[a, b, c, d]} produces the -vector @samp{[a - b + c - d, b - c + d, c - d, d]}. - -@tindex reducea -@tindex rreducea -@tindex reduced -@tindex rreduced -As for @kbd{V M}, @kbd{V R} normally reduces a matrix elementwise. For -example, given the matrix @expr{[[a, b, c], [d, e, f]]}, @kbd{V R +} will -compute @expr{a + b + c + d + e + f}. You can type @kbd{V R _} or -@kbd{V R :} to modify this behavior. The @kbd{V R _} [@code{reducea}] -command reduces ``across'' the matrix; it reduces each row of the matrix -as a vector, then collects the results. Thus @kbd{V R _ +} of this -matrix would produce @expr{[a + b + c, d + e + f]}. Similarly, @kbd{V R :} -[@code{reduced}] reduces down; @kbd{V R : +} would produce @expr{[a + d, -b + e, c + f]}. - -@tindex reducer -@tindex rreducer -There is a third ``by rows'' mode for reduction that is occasionally -useful; @kbd{V R =} [@code{reducer}] simply reduces the operator over -the rows of the matrix themselves. Thus @kbd{V R = +} on the above -matrix would get the same result as @kbd{V R : +}, since adding two -row vectors is equivalent to adding their elements. But @kbd{V R = *} -would multiply the two rows (to get a single number, their dot product), -while @kbd{V R : *} would produce a vector of the products of the columns. - -These three matrix reduction modes work with @kbd{V R} and @kbd{I V R}, -but they are not currently supported with @kbd{V U} or @kbd{I V U}. - -@tindex reducec -@tindex rreducec -The obsolete reduce-by-columns function, @code{reducec}, is still -supported but there is no way to get it through the @kbd{V R} command. - -The commands @kbd{C-x * :} and @kbd{C-x * _} are equivalent to typing -@kbd{C-x * r} to grab a rectangle of data into Calc, and then typing -@kbd{V R : +} or @kbd{V R _ +}, respectively, to sum the columns or -rows of the matrix. @xref{Grabbing From Buffers}. - -@node Nesting and Fixed Points, Generalized Products, Reducing, Reducing and Mapping -@subsection Nesting and Fixed Points - -@noindent -@kindex H v R -@kindex H V R -@tindex nest -The @kbd{H V R} [@code{nest}] command applies a function to a given -argument repeatedly. It takes two values, @samp{a} and @samp{n}, from -the stack, where @samp{n} must be an integer. It then applies the -function nested @samp{n} times; if the function is @samp{f} and @samp{n} -is 3, the result is @samp{f(f(f(a)))}. The number @samp{n} may be -negative if Calc knows an inverse for the function @samp{f}; for -example, @samp{nest(sin, a, -2)} returns @samp{arcsin(arcsin(a))}. - -@kindex H v U -@kindex H V U -@tindex anest -The @kbd{H V U} [@code{anest}] command is an accumulating version of -@code{nest}: It returns a vector of @samp{n+1} values, e.g., -@samp{[a, f(a), f(f(a)), f(f(f(a)))]}. If @samp{n} is negative and -@samp{F} is the inverse of @samp{f}, then the result is of the -form @samp{[a, F(a), F(F(a)), F(F(F(a)))]}. - -@kindex H I v R -@kindex H I V R -@tindex fixp -@cindex Fixed points -The @kbd{H I V R} [@code{fixp}] command is like @kbd{H V R}, except -that it takes only an @samp{a} value from the stack; the function is -applied until it reaches a ``fixed point,'' i.e., until the result -no longer changes. - -@kindex H I v U -@kindex H I V U -@tindex afixp -The @kbd{H I V U} [@code{afixp}] command is an accumulating @code{fixp}. -The first element of the return vector will be the initial value @samp{a}; -the last element will be the final result that would have been returned -by @code{fixp}. - -For example, 0.739085 is a fixed point of the cosine function (in radians): -@samp{cos(0.739085) = 0.739085}. You can find this value by putting, say, -1.0 on the stack and typing @kbd{H I V U C}. (We use the accumulating -version so we can see the intermediate results: @samp{[1, 0.540302, 0.857553, -0.65329, ...]}. With a precision of six, this command will take 36 steps -to converge to 0.739085.) - -Newton's method for finding roots is a classic example of iteration -to a fixed point. To find the square root of five starting with an -initial guess, Newton's method would look for a fixed point of the -function @samp{(x + 5/x) / 2}. Putting a guess of 1 on the stack -and typing @kbd{H I V R ' ($ + 5/$)/2 @key{RET}} quickly yields the result -2.23607. This is equivalent to using the @kbd{a R} (@code{calc-find-root}) -command to find a root of the equation @samp{x^2 = 5}. - -These examples used numbers for @samp{a} values. Calc keeps applying -the function until two successive results are equal to within the -current precision. For complex numbers, both the real parts and the -imaginary parts must be equal to within the current precision. If -@samp{a} is a formula (say, a variable name), then the function is -applied until two successive results are exactly the same formula. -It is up to you to ensure that the function will eventually converge; -if it doesn't, you may have to press @kbd{C-g} to stop the Calculator. - -The algebraic @code{fixp} function takes two optional arguments, @samp{n} -and @samp{tol}. The first is the maximum number of steps to be allowed, -and must be either an integer or the symbol @samp{inf} (infinity, the -default). The second is a convergence tolerance. If a tolerance is -specified, all results during the calculation must be numbers, not -formulas, and the iteration stops when the magnitude of the difference -between two successive results is less than or equal to the tolerance. -(This implies that a tolerance of zero iterates until the results are -exactly equal.) - -Putting it all together, @samp{fixp(<(# + A/#)/2>, B, 20, 1e-10)} -computes the square root of @samp{A} given the initial guess @samp{B}, -stopping when the result is correct within the specified tolerance, or -when 20 steps have been taken, whichever is sooner. - -@node Generalized Products, , Nesting and Fixed Points, Reducing and Mapping -@subsection Generalized Products - -@kindex v O -@kindex V O -@pindex calc-outer-product -@tindex outer -The @kbd{V O} (@code{calc-outer-product}) [@code{outer}] command applies -a given binary operator to all possible pairs of elements from two -vectors, to produce a matrix. For example, @kbd{V O *} with @samp{[a, b]} -and @samp{[x, y, z]} on the stack produces a multiplication table: -@samp{[[a x, a y, a z], [b x, b y, b z]]}. Element @var{r},@var{c} of -the result matrix is obtained by applying the operator to element @var{r} -of the lefthand vector and element @var{c} of the righthand vector. - -@kindex v I -@kindex V I -@pindex calc-inner-product -@tindex inner -The @kbd{V I} (@code{calc-inner-product}) [@code{inner}] command computes -the generalized inner product of two vectors or matrices, given a -``multiplicative'' operator and an ``additive'' operator. These can each -actually be any binary operators; if they are @samp{*} and @samp{+}, -respectively, the result is a standard matrix multiplication. Element -@var{r},@var{c} of the result matrix is obtained by mapping the -multiplicative operator across row @var{r} of the lefthand matrix and -column @var{c} of the righthand matrix, and then reducing with the additive -operator. Just as for the standard @kbd{*} command, this can also do a -vector-matrix or matrix-vector inner product, or a vector-vector -generalized dot product. - -Since @kbd{V I} requires two operators, it prompts twice. In each case, -you can use any of the usual methods for entering the operator. If you -use @kbd{$} twice to take both operator formulas from the stack, the -first (multiplicative) operator is taken from the top of the stack -and the second (additive) operator is taken from second-to-top. - -@node Vector and Matrix Formats, , Reducing and Mapping, Matrix Functions -@section Vector and Matrix Display Formats - -@noindent -Commands for controlling vector and matrix display use the @kbd{v} prefix -instead of the usual @kbd{d} prefix. But they are display modes; in -particular, they are influenced by the @kbd{I} and @kbd{H} prefix keys -in the same way (@pxref{Display Modes}). Matrix display is also -influenced by the @kbd{d O} (@code{calc-flat-language}) mode; -@pxref{Normal Language Modes}. - -@kindex v < -@kindex V < -@pindex calc-matrix-left-justify -@kindex v = -@kindex V = -@pindex calc-matrix-center-justify -@kindex v > -@kindex V > -@pindex calc-matrix-right-justify -The commands @kbd{v <} (@code{calc-matrix-left-justify}), @kbd{v >} -(@code{calc-matrix-right-justify}), and @w{@kbd{v =}} -(@code{calc-matrix-center-justify}) control whether matrix elements -are justified to the left, right, or center of their columns. - -@kindex v [ -@kindex V [ -@pindex calc-vector-brackets -@kindex v @{ -@kindex V @{ -@pindex calc-vector-braces -@kindex v ( -@kindex V ( -@pindex calc-vector-parens -The @kbd{v [} (@code{calc-vector-brackets}) command turns the square -brackets that surround vectors and matrices displayed in the stack on -and off. The @kbd{v @{} (@code{calc-vector-braces}) and @kbd{v (} -(@code{calc-vector-parens}) commands use curly braces or parentheses, -respectively, instead of square brackets. For example, @kbd{v @{} might -be used in preparation for yanking a matrix into a buffer running -Mathematica. (In fact, the Mathematica language mode uses this mode; -@pxref{Mathematica Language Mode}.) Note that, regardless of the -display mode, either brackets or braces may be used to enter vectors, -and parentheses may never be used for this purpose. - -@kindex V ] -@kindex v ] -@kindex V ) -@kindex v ) -@kindex V @} -@kindex v @} -@pindex calc-matrix-brackets -The @kbd{v ]} (@code{calc-matrix-brackets}) command controls the -``big'' style display of matrices, for matrices which have more than -one row. It prompts for a string of code letters; currently -implemented letters are @code{R}, which enables brackets on each row -of the matrix; @code{O}, which enables outer brackets in opposite -corners of the matrix; and @code{C}, which enables commas or -semicolons at the ends of all rows but the last. The default format -is @samp{RO}. (Before Calc 2.00, the format was fixed at @samp{ROC}.) -Here are some example matrices: - -@example -@group -[ [ 123, 0, 0 ] [ [ 123, 0, 0 ], - [ 0, 123, 0 ] [ 0, 123, 0 ], - [ 0, 0, 123 ] ] [ 0, 0, 123 ] ] - - RO ROC - -@end group -@end example -@noindent -@example -@group - [ 123, 0, 0 [ 123, 0, 0 ; - 0, 123, 0 0, 123, 0 ; - 0, 0, 123 ] 0, 0, 123 ] - - O OC - -@end group -@end example -@noindent -@example -@group - [ 123, 0, 0 ] 123, 0, 0 - [ 0, 123, 0 ] 0, 123, 0 - [ 0, 0, 123 ] 0, 0, 123 - - R @r{blank} -@end group -@end example - -@noindent -Note that of the formats shown here, @samp{RO}, @samp{ROC}, and -@samp{OC} are all recognized as matrices during reading, while -the others are useful for display only. - -@kindex v , -@kindex V , -@pindex calc-vector-commas -The @kbd{v ,} (@code{calc-vector-commas}) command turns commas on and -off in vector and matrix display. - -In vectors of length one, and in all vectors when commas have been -turned off, Calc adds extra parentheses around formulas that might -otherwise be ambiguous. For example, @samp{[a b]} could be a vector -of the one formula @samp{a b}, or it could be a vector of two -variables with commas turned off. Calc will display the former -case as @samp{[(a b)]}. You can disable these extra parentheses -(to make the output less cluttered at the expense of allowing some -ambiguity) by adding the letter @code{P} to the control string you -give to @kbd{v ]} (as described above). - -@kindex v . -@kindex V . -@pindex calc-full-vectors -The @kbd{v .} (@code{calc-full-vectors}) command turns abbreviated -display of long vectors on and off. In this mode, vectors of six -or more elements, or matrices of six or more rows or columns, will -be displayed in an abbreviated form that displays only the first -three elements and the last element: @samp{[a, b, c, ..., z]}. -When very large vectors are involved this will substantially -improve Calc's display speed. - -@kindex t . -@pindex calc-full-trail-vectors -The @kbd{t .} (@code{calc-full-trail-vectors}) command controls a -similar mode for recording vectors in the Trail. If you turn on -this mode, vectors of six or more elements and matrices of six or -more rows or columns will be abbreviated when they are put in the -Trail. The @kbd{t y} (@code{calc-trail-yank}) command will be -unable to recover those vectors. If you are working with very -large vectors, this mode will improve the speed of all operations -that involve the trail. - -@kindex v / -@kindex V / -@pindex calc-break-vectors -The @kbd{v /} (@code{calc-break-vectors}) command turns multi-line -vector display on and off. Normally, matrices are displayed with one -row per line but all other types of vectors are displayed in a single -line. This mode causes all vectors, whether matrices or not, to be -displayed with a single element per line. Sub-vectors within the -vectors will still use the normal linear form. - -@node Algebra, Units, Matrix Functions, Top -@chapter Algebra - -@noindent -This section covers the Calc features that help you work with -algebraic formulas. First, the general sub-formula selection -mechanism is described; this works in conjunction with any Calc -commands. Then, commands for specific algebraic operations are -described. Finally, the flexible @dfn{rewrite rule} mechanism -is discussed. - -The algebraic commands use the @kbd{a} key prefix; selection -commands use the @kbd{j} (for ``just a letter that wasn't used -for anything else'') prefix. - -@xref{Editing Stack Entries}, to see how to manipulate formulas -using regular Emacs editing commands. - -When doing algebraic work, you may find several of the Calculator's -modes to be helpful, including Algebraic Simplification mode (@kbd{m A}) -or No-Simplification mode (@kbd{m O}), -Algebraic entry mode (@kbd{m a}), Fraction mode (@kbd{m f}), and -Symbolic mode (@kbd{m s}). @xref{Mode Settings}, for discussions -of these modes. You may also wish to select Big display mode (@kbd{d B}). -@xref{Normal Language Modes}. - -@menu -* Selecting Subformulas:: -* Algebraic Manipulation:: -* Simplifying Formulas:: -* Polynomials:: -* Calculus:: -* Solving Equations:: -* Numerical Solutions:: -* Curve Fitting:: -* Summations:: -* Logical Operations:: -* Rewrite Rules:: -@end menu - -@node Selecting Subformulas, Algebraic Manipulation, Algebra, Algebra -@section Selecting Sub-Formulas - -@noindent -@cindex Selections -@cindex Sub-formulas -@cindex Parts of formulas -When working with an algebraic formula it is often necessary to -manipulate a portion of the formula rather than the formula as a -whole. Calc allows you to ``select'' a portion of any formula on -the stack. Commands which would normally operate on that stack -entry will now operate only on the sub-formula, leaving the -surrounding part of the stack entry alone. - -One common non-algebraic use for selection involves vectors. To work -on one element of a vector in-place, simply select that element as a -``sub-formula'' of the vector. - -@menu -* Making Selections:: -* Changing Selections:: -* Displaying Selections:: -* Operating on Selections:: -* Rearranging with Selections:: -@end menu - -@node Making Selections, Changing Selections, Selecting Subformulas, Selecting Subformulas -@subsection Making Selections - -@noindent -@kindex j s -@pindex calc-select-here -To select a sub-formula, move the Emacs cursor to any character in that -sub-formula, and press @w{@kbd{j s}} (@code{calc-select-here}). Calc will -highlight the smallest portion of the formula that contains that -character. By default the sub-formula is highlighted by blanking out -all of the rest of the formula with dots. Selection works in any -display mode but is perhaps easiest in Big mode (@kbd{d B}). -Suppose you enter the following formula: - -@smallexample -@group - 3 ___ - (a + b) + V c -1: --------------- - 2 x + 1 -@end group -@end smallexample - -@noindent -(by typing @kbd{' ((a+b)^3 + sqrt(c)) / (2x+1)}). If you move the -cursor to the letter @samp{b} and press @w{@kbd{j s}}, the display changes -to - -@smallexample -@group - . ... - .. . b. . . . -1* ............... - . . . . -@end group -@end smallexample - -@noindent -Every character not part of the sub-formula @samp{b} has been changed -to a dot. (If the customizable variable -@code{calc-highlight-selections-with-faces} is non-@code{nil}, then the characters -not part of the sub-formula are de-emphasized by using a less -noticeable face instead of using dots. @pxref{Displaying Selections}.) -The @samp{*} next to the line number is to remind you that -the formula has a portion of it selected. (In this case, it's very -obvious, but it might not always be. If Embedded mode is enabled, -the word @samp{Sel} also appears in the mode line because the stack -may not be visible. @pxref{Embedded Mode}.) - -If you had instead placed the cursor on the parenthesis immediately to -the right of the @samp{b}, the selection would have been: - -@smallexample -@group - . ... - (a + b) . . . -1* ............... - . . . . -@end group -@end smallexample - -@noindent -The portion selected is always large enough to be considered a complete -formula all by itself, so selecting the parenthesis selects the whole -formula that it encloses. Putting the cursor on the @samp{+} sign -would have had the same effect. - -(Strictly speaking, the Emacs cursor is really the manifestation of -the Emacs ``point,'' which is a position @emph{between} two characters -in the buffer. So purists would say that Calc selects the smallest -sub-formula which contains the character to the right of ``point.'') - -If you supply a numeric prefix argument @var{n}, the selection is -expanded to the @var{n}th enclosing sub-formula. Thus, positioning -the cursor on the @samp{b} and typing @kbd{C-u 1 j s} will select -@samp{a + b}; typing @kbd{C-u 2 j s} will select @samp{(a + b)^3}, -and so on. - -If the cursor is not on any part of the formula, or if you give a -numeric prefix that is too large, the entire formula is selected. - -If the cursor is on the @samp{.} line that marks the top of the stack -(i.e., its normal ``rest position''), this command selects the entire -formula at stack level 1. Most selection commands similarly operate -on the formula at the top of the stack if you haven't positioned the -cursor on any stack entry. - -@kindex j a -@pindex calc-select-additional -The @kbd{j a} (@code{calc-select-additional}) command enlarges the -current selection to encompass the cursor. To select the smallest -sub-formula defined by two different points, move to the first and -press @kbd{j s}, then move to the other and press @kbd{j a}. This -is roughly analogous to using @kbd{C-@@} (@code{set-mark-command}) to -select the two ends of a region of text during normal Emacs editing. - -@kindex j o -@pindex calc-select-once -The @kbd{j o} (@code{calc-select-once}) command selects a formula in -exactly the same way as @kbd{j s}, except that the selection will -last only as long as the next command that uses it. For example, -@kbd{j o 1 +} is a handy way to add one to the sub-formula indicated -by the cursor. - -(A somewhat more precise definition: The @kbd{j o} command sets a flag -such that the next command involving selected stack entries will clear -the selections on those stack entries afterwards. All other selection -commands except @kbd{j a} and @kbd{j O} clear this flag.) - -@kindex j S -@kindex j O -@pindex calc-select-here-maybe -@pindex calc-select-once-maybe -The @kbd{j S} (@code{calc-select-here-maybe}) and @kbd{j O} -(@code{calc-select-once-maybe}) commands are equivalent to @kbd{j s} -and @kbd{j o}, respectively, except that if the formula already -has a selection they have no effect. This is analogous to the -behavior of some commands such as @kbd{j r} (@code{calc-rewrite-selection}; -@pxref{Selections with Rewrite Rules}) and is mainly intended to be -used in keyboard macros that implement your own selection-oriented -commands. - -Selection of sub-formulas normally treats associative terms like -@samp{a + b - c + d} and @samp{x * y * z} as single levels of the formula. -If you place the cursor anywhere inside @samp{a + b - c + d} except -on one of the variable names and use @kbd{j s}, you will select the -entire four-term sum. - -@kindex j b -@pindex calc-break-selections -The @kbd{j b} (@code{calc-break-selections}) command controls a mode -in which the ``deep structure'' of these associative formulas shows -through. Calc actually stores the above formulas as -@samp{((a + b) - c) + d} and @samp{x * (y * z)}. (Note that for certain -obscure reasons, by default Calc treats multiplication as -right-associative.) Once you have enabled @kbd{j b} mode, selecting -with the cursor on the @samp{-} sign would only select the @samp{a + b - -c} portion, which makes sense when the deep structure of the sum is -considered. There is no way to select the @samp{b - c + d} portion; -although this might initially look like just as legitimate a sub-formula -as @samp{a + b - c}, the deep structure shows that it isn't. The @kbd{d -U} command can be used to view the deep structure of any formula -(@pxref{Normal Language Modes}). - -When @kbd{j b} mode has not been enabled, the deep structure is -generally hidden by the selection commands---what you see is what -you get. - -@kindex j u -@pindex calc-unselect -The @kbd{j u} (@code{calc-unselect}) command unselects the formula -that the cursor is on. If there was no selection in the formula, -this command has no effect. With a numeric prefix argument, it -unselects the @var{n}th stack element rather than using the cursor -position. - -@kindex j c -@pindex calc-clear-selections -The @kbd{j c} (@code{calc-clear-selections}) command unselects all -stack elements. - -@node Changing Selections, Displaying Selections, Making Selections, Selecting Subformulas -@subsection Changing Selections - -@noindent -@kindex j m -@pindex calc-select-more -Once you have selected a sub-formula, you can expand it using the -@w{@kbd{j m}} (@code{calc-select-more}) command. If @samp{a + b} is -selected, pressing @w{@kbd{j m}} repeatedly works as follows: - -@smallexample -@group - 3 ... 3 ___ 3 ___ - (a + b) . . . (a + b) + V c (a + b) + V c -1* ............... 1* ............... 1* --------------- - . . . . . . . . 2 x + 1 -@end group -@end smallexample - -@noindent -In the last example, the entire formula is selected. This is roughly -the same as having no selection at all, but because there are subtle -differences the @samp{*} character is still there on the line number. - -With a numeric prefix argument @var{n}, @kbd{j m} expands @var{n} -times (or until the entire formula is selected). Note that @kbd{j s} -with argument @var{n} is equivalent to plain @kbd{j s} followed by -@kbd{j m} with argument @var{n}. If @w{@kbd{j m}} is used when there -is no current selection, it is equivalent to @w{@kbd{j s}}. - -Even though @kbd{j m} does not explicitly use the location of the -cursor within the formula, it nevertheless uses the cursor to determine -which stack element to operate on. As usual, @kbd{j m} when the cursor -is not on any stack element operates on the top stack element. - -@kindex j l -@pindex calc-select-less -The @kbd{j l} (@code{calc-select-less}) command reduces the current -selection around the cursor position. That is, it selects the -immediate sub-formula of the current selection which contains the -cursor, the opposite of @kbd{j m}. If the cursor is not inside the -current selection, the command de-selects the formula. - -@kindex j 1-9 -@pindex calc-select-part -The @kbd{j 1} through @kbd{j 9} (@code{calc-select-part}) commands -select the @var{n}th sub-formula of the current selection. They are -like @kbd{j l} (@code{calc-select-less}) except they use counting -rather than the cursor position to decide which sub-formula to select. -For example, if the current selection is @kbd{a + b + c} or -@kbd{f(a, b, c)} or @kbd{[a, b, c]}, then @kbd{j 1} selects @samp{a}, -@kbd{j 2} selects @samp{b}, and @kbd{j 3} selects @samp{c}; in each of -these cases, @kbd{j 4} through @kbd{j 9} would be errors. - -If there is no current selection, @kbd{j 1} through @kbd{j 9} select -the @var{n}th top-level sub-formula. (In other words, they act as if -the entire stack entry were selected first.) To select the @var{n}th -sub-formula where @var{n} is greater than nine, you must instead invoke -@w{@kbd{j 1}} with @var{n} as a numeric prefix argument. - -@kindex j n -@kindex j p -@pindex calc-select-next -@pindex calc-select-previous -The @kbd{j n} (@code{calc-select-next}) and @kbd{j p} -(@code{calc-select-previous}) commands change the current selection -to the next or previous sub-formula at the same level. For example, -if @samp{b} is selected in @w{@samp{2 + a*b*c + x}}, then @kbd{j n} -selects @samp{c}. Further @kbd{j n} commands would be in error because, -even though there is something to the right of @samp{c} (namely, @samp{x}), -it is not at the same level; in this case, it is not a term of the -same product as @samp{b} and @samp{c}. However, @kbd{j m} (to select -the whole product @samp{a*b*c} as a term of the sum) followed by -@w{@kbd{j n}} would successfully select the @samp{x}. - -Similarly, @kbd{j p} moves the selection from the @samp{b} in this -sample formula to the @samp{a}. Both commands accept numeric prefix -arguments to move several steps at a time. - -It is interesting to compare Calc's selection commands with the -Emacs Info system's commands for navigating through hierarchically -organized documentation. Calc's @kbd{j n} command is completely -analogous to Info's @kbd{n} command. Likewise, @kbd{j p} maps to -@kbd{p}, @kbd{j 2} maps to @kbd{2}, and Info's @kbd{u} is like @kbd{j m}. -(Note that @kbd{j u} stands for @code{calc-unselect}, not ``up''.) -The Info @kbd{m} command is somewhat similar to Calc's @kbd{j s} and -@kbd{j l}; in each case, you can jump directly to a sub-component -of the hierarchy simply by pointing to it with the cursor. - -@node Displaying Selections, Operating on Selections, Changing Selections, Selecting Subformulas -@subsection Displaying Selections - -@noindent -@kindex j d -@pindex calc-show-selections -@vindex calc-highlight-selections-with-faces -@vindex calc-selected-face -@vindex calc-nonselected-face -The @kbd{j d} (@code{calc-show-selections}) command controls how -selected sub-formulas are displayed. One of the alternatives is -illustrated in the above examples; if we press @kbd{j d} we switch -to the other style in which the selected portion itself is obscured -by @samp{#} signs: - -@smallexample -@group - 3 ... # ___ - (a + b) . . . ## # ## + V c -1* ............... 1* --------------- - . . . . 2 x + 1 -@end group -@end smallexample -If the customizable variable -@code{calc-highlight-selections-with-faces} is non-@code{nil}, then the -non-selected portion of the formula will be de-emphasized by using a -less noticeable face (@code{calc-nonselected-face}) instead of dots -and the selected sub-formula will be highlighted by using a more -noticeable face (@code{calc-selected-face}) instead of @samp{#} -signs. (@pxref{Customizing Calc}.) - -@node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas -@subsection Operating on Selections - -@noindent -Once a selection is made, all Calc commands that manipulate items -on the stack will operate on the selected portions of the items -instead. (Note that several stack elements may have selections -at once, though there can be only one selection at a time in any -given stack element.) - -@kindex j e -@pindex calc-enable-selections -The @kbd{j e} (@code{calc-enable-selections}) command disables the -effect that selections have on Calc commands. The current selections -still exist, but Calc commands operate on whole stack elements anyway. -This mode can be identified by the fact that the @samp{*} markers on -the line numbers are gone, even though selections are visible. To -reactivate the selections, press @kbd{j e} again. - -To extract a sub-formula as a new formula, simply select the -sub-formula and press @key{RET}. This normally duplicates the top -stack element; here it duplicates only the selected portion of that -element. - -To replace a sub-formula with something different, you can enter the -new value onto the stack and press @key{TAB}. This normally exchanges -the top two stack elements; here it swaps the value you entered into -the selected portion of the formula, returning the old selected -portion to the top of the stack. - -@smallexample -@group - 3 ... ... ___ - (a + b) . . . 17 x y . . . 17 x y + V c -2* ............... 2* ............. 2: ------------- - . . . . . . . . 2 x + 1 - - 3 3 -1: 17 x y 1: (a + b) 1: (a + b) -@end group -@end smallexample - -In this example we select a sub-formula of our original example, -enter a new formula, @key{TAB} it into place, then deselect to see -the complete, edited formula. - -If you want to swap whole formulas around even though they contain -selections, just use @kbd{j e} before and after. - -@kindex j ' -@pindex calc-enter-selection -The @kbd{j '} (@code{calc-enter-selection}) command is another way -to replace a selected sub-formula. This command does an algebraic -entry just like the regular @kbd{'} key. When you press @key{RET}, -the formula you type replaces the original selection. You can use -the @samp{$} symbol in the formula to refer to the original -selection. If there is no selection in the formula under the cursor, -the cursor is used to make a temporary selection for the purposes of -the command. Thus, to change a term of a formula, all you have to -do is move the Emacs cursor to that term and press @kbd{j '}. - -@kindex j ` -@pindex calc-edit-selection -The @kbd{j `} (@code{calc-edit-selection}) command is a similar -analogue of the @kbd{`} (@code{calc-edit}) command. It edits the -selected sub-formula in a separate buffer. If there is no -selection, it edits the sub-formula indicated by the cursor. - -To delete a sub-formula, press @key{DEL}. This generally replaces -the sub-formula with the constant zero, but in a few suitable contexts -it uses the constant one instead. The @key{DEL} key automatically -deselects and re-simplifies the entire formula afterwards. Thus: - -@smallexample -@group - ### - 17 x y + # # 17 x y 17 # y 17 y -1* ------------- 1: ------- 1* ------- 1: ------- - 2 x + 1 2 x + 1 2 x + 1 2 x + 1 -@end group -@end smallexample - -In this example, we first delete the @samp{sqrt(c)} term; Calc -accomplishes this by replacing @samp{sqrt(c)} with zero and -resimplifying. We then delete the @kbd{x} in the numerator; -since this is part of a product, Calc replaces it with @samp{1} -and resimplifies. - -If you select an element of a vector and press @key{DEL}, that -element is deleted from the vector. If you delete one side of -an equation or inequality, only the opposite side remains. - -@kindex j @key{DEL} -@pindex calc-del-selection -The @kbd{j @key{DEL}} (@code{calc-del-selection}) command is like -@key{DEL} but with the auto-selecting behavior of @kbd{j '} and -@kbd{j `}. It deletes the selected portion of the formula -indicated by the cursor, or, in the absence of a selection, it -deletes the sub-formula indicated by the cursor position. - -@kindex j @key{RET} -@pindex calc-grab-selection -(There is also an auto-selecting @kbd{j @key{RET}} (@code{calc-copy-selection}) -command.) - -Normal arithmetic operations also apply to sub-formulas. Here we -select the denominator, press @kbd{5 -} to subtract five from the -denominator, press @kbd{n} to negate the denominator, then -press @kbd{Q} to take the square root. - -@smallexample -@group - .. . .. . .. . .. . -1* ....... 1* ....... 1* ....... 1* .......... - 2 x + 1 2 x - 4 4 - 2 x _________ - V 4 - 2 x -@end group -@end smallexample - -Certain types of operations on selections are not allowed. For -example, for an arithmetic function like @kbd{-} no more than one of -the arguments may be a selected sub-formula. (As the above example -shows, the result of the subtraction is spliced back into the argument -which had the selection; if there were more than one selection involved, -this would not be well-defined.) If you try to subtract two selections, -the command will abort with an error message. - -Operations on sub-formulas sometimes leave the formula as a whole -in an ``un-natural'' state. Consider negating the @samp{2 x} term -of our sample formula by selecting it and pressing @kbd{n} -(@code{calc-change-sign}). - -@smallexample -@group - .. . .. . -1* .......... 1* ........... - ......... .......... - . . . 2 x . . . -2 x -@end group -@end smallexample - -Unselecting the sub-formula reveals that the minus sign, which would -normally have canceled out with the subtraction automatically, has -not been able to do so because the subtraction was not part of the -selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing -any other mathematical operation on the whole formula will cause it -to be simplified. - -@smallexample -@group - 17 y 17 y -1: ----------- 1: ---------- - __________ _________ - V 4 - -2 x V 4 + 2 x -@end group -@end smallexample - -@node Rearranging with Selections, , Operating on Selections, Selecting Subformulas -@subsection Rearranging Formulas using Selections - -@noindent -@kindex j R -@pindex calc-commute-right -The @kbd{j R} (@code{calc-commute-right}) command moves the selected -sub-formula to the right in its surrounding formula. Generally the -selection is one term of a sum or product; the sum or product is -rearranged according to the commutative laws of algebra. - -As with @kbd{j '} and @kbd{j @key{DEL}}, the term under the cursor is used -if there is no selection in the current formula. All commands described -in this section share this property. In this example, we place the -cursor on the @samp{a} and type @kbd{j R}, then repeat. - -@smallexample -1: a + b - c 1: b + a - c 1: b - c + a -@end smallexample - -@noindent -Note that in the final step above, the @samp{a} is switched with -the @samp{c} but the signs are adjusted accordingly. When moving -terms of sums and products, @kbd{j R} will never change the -mathematical meaning of the formula. - -The selected term may also be an element of a vector or an argument -of a function. The term is exchanged with the one to its right. -In this case, the ``meaning'' of the vector or function may of -course be drastically changed. - -@smallexample -1: [a, b, c] 1: [b, a, c] 1: [b, c, a] - -1: f(a, b, c) 1: f(b, a, c) 1: f(b, c, a) -@end smallexample - -@kindex j L -@pindex calc-commute-left -The @kbd{j L} (@code{calc-commute-left}) command is like @kbd{j R} -except that it swaps the selected term with the one to its left. - -With numeric prefix arguments, these commands move the selected -term several steps at a time. It is an error to try to move a -term left or right past the end of its enclosing formula. -With numeric prefix arguments of zero, these commands move the -selected term as far as possible in the given direction. - -@kindex j D -@pindex calc-sel-distribute -The @kbd{j D} (@code{calc-sel-distribute}) command mixes the selected -sum or product into the surrounding formula using the distributive -law. For example, in @samp{a * (b - c)} with the @samp{b - c} -selected, the result is @samp{a b - a c}. This also distributes -products or quotients into surrounding powers, and can also do -transformations like @samp{exp(a + b)} to @samp{exp(a) exp(b)}, -where @samp{a + b} is the selected term, and @samp{ln(a ^ b)} -to @samp{ln(a) b}, where @samp{a ^ b} is the selected term. - -For multiple-term sums or products, @kbd{j D} takes off one term -at a time: @samp{a * (b + c - d)} goes to @samp{a * (c - d) + a b} -with the @samp{c - d} selected so that you can type @kbd{j D} -repeatedly to expand completely. The @kbd{j D} command allows a -numeric prefix argument which specifies the maximum number of -times to expand at once; the default is one time only. - -@vindex DistribRules -The @kbd{j D} command is implemented using rewrite rules. -@xref{Selections with Rewrite Rules}. The rules are stored in -the Calc variable @code{DistribRules}. A convenient way to view -these rules is to use @kbd{s e} (@code{calc-edit-variable}) which -displays and edits the stored value of a variable. Press @kbd{C-c C-c} -to return from editing mode; be careful not to make any actual changes -or else you will affect the behavior of future @kbd{j D} commands! - -To extend @kbd{j D} to handle new cases, just edit @code{DistribRules} -as described above. You can then use the @kbd{s p} command to save -this variable's value permanently for future Calc sessions. -@xref{Operations on Variables}. - -@kindex j M -@pindex calc-sel-merge -@vindex MergeRules -The @kbd{j M} (@code{calc-sel-merge}) command is the complement -of @kbd{j D}; given @samp{a b - a c} with either @samp{a b} or -@samp{a c} selected, the result is @samp{a * (b - c)}. Once -again, @kbd{j M} can also merge calls to functions like @code{exp} -and @code{ln}; examine the variable @code{MergeRules} to see all -the relevant rules. - -@kindex j C -@pindex calc-sel-commute -@vindex CommuteRules -The @kbd{j C} (@code{calc-sel-commute}) command swaps the arguments -of the selected sum, product, or equation. It always behaves as -if @kbd{j b} mode were in effect, i.e., the sum @samp{a + b + c} is -treated as the nested sums @samp{(a + b) + c} by this command. -If you put the cursor on the first @samp{+}, the result is -@samp{(b + a) + c}; if you put the cursor on the second @samp{+}, the -result is @samp{c + (a + b)} (which the default simplifications -will rearrange to @samp{(c + a) + b}). The relevant rules are stored -in the variable @code{CommuteRules}. - -You may need to turn default simplifications off (with the @kbd{m O} -command) in order to get the full benefit of @kbd{j C}. For example, -commuting @samp{a - b} produces @samp{-b + a}, but the default -simplifications will ``simplify'' this right back to @samp{a - b} if -you don't turn them off. The same is true of some of the other -manipulations described in this section. - -@kindex j N -@pindex calc-sel-negate -@vindex NegateRules -The @kbd{j N} (@code{calc-sel-negate}) command replaces the selected -term with the negative of that term, then adjusts the surrounding -formula in order to preserve the meaning. For example, given -@samp{exp(a - b)} where @samp{a - b} is selected, the result is -@samp{1 / exp(b - a)}. By contrast, selecting a term and using the -regular @kbd{n} (@code{calc-change-sign}) command negates the -term without adjusting the surroundings, thus changing the meaning -of the formula as a whole. The rules variable is @code{NegateRules}. - -@kindex j & -@pindex calc-sel-invert -@vindex InvertRules -The @kbd{j &} (@code{calc-sel-invert}) command is similar to @kbd{j N} -except it takes the reciprocal of the selected term. For example, -given @samp{a - ln(b)} with @samp{b} selected, the result is -@samp{a + ln(1/b)}. The rules variable is @code{InvertRules}. - -@kindex j E -@pindex calc-sel-jump-equals -@vindex JumpRules -The @kbd{j E} (@code{calc-sel-jump-equals}) command moves the -selected term from one side of an equation to the other. Given -@samp{a + b = c + d} with @samp{c} selected, the result is -@samp{a + b - c = d}. This command also works if the selected -term is part of a @samp{*}, @samp{/}, or @samp{^} formula. The -relevant rules variable is @code{JumpRules}. - -@kindex j I -@kindex H j I -@pindex calc-sel-isolate -The @kbd{j I} (@code{calc-sel-isolate}) command isolates the -selected term on its side of an equation. It uses the @kbd{a S} -(@code{calc-solve-for}) command to solve the equation, and the -Hyperbolic flag affects it in the same way. @xref{Solving Equations}. -When it applies, @kbd{j I} is often easier to use than @kbd{j E}. -It understands more rules of algebra, and works for inequalities -as well as equations. - -@kindex j * -@kindex j / -@pindex calc-sel-mult-both-sides -@pindex calc-sel-div-both-sides -The @kbd{j *} (@code{calc-sel-mult-both-sides}) command prompts for a -formula using algebraic entry, then multiplies both sides of the -selected quotient or equation by that formula. It performs the -default algebraic simplifications before re-forming the -quotient or equation. You can suppress this simplification by -providing a prefix argument: @kbd{C-u j *}. There is also a @kbd{j /} -(@code{calc-sel-div-both-sides}) which is similar to @kbd{j *} but -dividing instead of multiplying by the factor you enter. - -If the selection is a quotient with numerator 1, then Calc's default -simplifications would normally cancel the new factors. To prevent -this, when the @kbd{j *} command is used on a selection whose numerator is -1 or -1, the denominator is expanded at the top level using the -distributive law (as if using the @kbd{C-u 1 a x} command). Suppose the -formula on the stack is @samp{1 / (a + 1)} and you wish to multiplying the -top and bottom by @samp{a - 1}. Calc's default simplifications would -normally change the result @samp{(a - 1) /(a + 1) (a - 1)} back -to the original form by cancellation; when @kbd{j *} is used, Calc -expands the denominator to @samp{a (a - 1) + a - 1} to prevent this. - -If you wish the @kbd{j *} command to completely expand the denominator -of a quotient you can call it with a zero prefix: @kbd{C-u 0 j *}. For -example, if the formula on the stack is @samp{1 / (sqrt(a) + 1)}, you may -wish to eliminate the square root in the denominator by multiplying -the top and bottom by @samp{sqrt(a) - 1}. If you did this simply by using -a simple @kbd{j *} command, you would get -@samp{(sqrt(a)-1)/ (sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1)}. Instead, -you would probably want to use @kbd{C-u 0 j *}, which would expand the -bottom and give you the desired result @samp{(sqrt(a)-1)/(a-1)}. More -generally, if @kbd{j *} is called with an argument of a positive -integer @var{n}, then the denominator of the expression will be -expanded @var{n} times (as if with the @kbd{C-u @var{n} a x} command). - -If the selection is an inequality, @kbd{j *} and @kbd{j /} will -accept any factor, but will warn unless they can prove the factor -is either positive or negative. (In the latter case the direction -of the inequality will be switched appropriately.) @xref{Declarations}, -for ways to inform Calc that a given variable is positive or -negative. If Calc can't tell for sure what the sign of the factor -will be, it will assume it is positive and display a warning -message. - -For selections that are not quotients, equations, or inequalities, -these commands pull out a multiplicative factor: They divide (or -multiply) by the entered formula, simplify, then multiply (or divide) -back by the formula. - -@kindex j + -@kindex j - -@pindex calc-sel-add-both-sides -@pindex calc-sel-sub-both-sides -The @kbd{j +} (@code{calc-sel-add-both-sides}) and @kbd{j -} -(@code{calc-sel-sub-both-sides}) commands analogously add to or -subtract from both sides of an equation or inequality. For other -types of selections, they extract an additive factor. A numeric -prefix argument suppresses simplification of the intermediate -results. - -@kindex j U -@pindex calc-sel-unpack -The @kbd{j U} (@code{calc-sel-unpack}) command replaces the -selected function call with its argument. For example, given -@samp{a + sin(x^2)} with @samp{sin(x^2)} selected, the result -is @samp{a + x^2}. (The @samp{x^2} will remain selected; if you -wanted to change the @code{sin} to @code{cos}, just press @kbd{C} -now to take the cosine of the selected part.) - -@kindex j v -@pindex calc-sel-evaluate -The @kbd{j v} (@code{calc-sel-evaluate}) command performs the -basic simplifications on the selected sub-formula. -These simplifications would normally be done automatically -on all results, but may have been partially inhibited by -previous selection-related operations, or turned off altogether -by the @kbd{m O} command. This command is just an auto-selecting -version of the @w{@kbd{a v}} command (@pxref{Algebraic Manipulation}). - -With a numeric prefix argument of 2, @kbd{C-u 2 j v} applies -the default algebraic simplifications to the selected -sub-formula. With a prefix argument of 3 or more, e.g., @kbd{C-u j v} -applies the @kbd{a e} (@code{calc-simplify-extended}) command. -@xref{Simplifying Formulas}. With a negative prefix argument -it simplifies at the top level only, just as with @kbd{a v}. -Here the ``top'' level refers to the top level of the selected -sub-formula. - -@kindex j " -@pindex calc-sel-expand-formula -The @kbd{j "} (@code{calc-sel-expand-formula}) command is to @kbd{a "} -(@pxref{Algebraic Manipulation}) what @kbd{j v} is to @kbd{a v}. - -You can use the @kbd{j r} (@code{calc-rewrite-selection}) command -to define other algebraic operations on sub-formulas. @xref{Rewrite Rules}. - -@node Algebraic Manipulation, Simplifying Formulas, Selecting Subformulas, Algebra -@section Algebraic Manipulation - -@noindent -The commands in this section perform general-purpose algebraic -manipulations. They work on the whole formula at the top of the -stack (unless, of course, you have made a selection in that -formula). - -Many algebra commands prompt for a variable name or formula. If you -answer the prompt with a blank line, the variable or formula is taken -from top-of-stack, and the normal argument for the command is taken -from the second-to-top stack level. - -@kindex a v -@pindex calc-alg-evaluate -The @kbd{a v} (@code{calc-alg-evaluate}) command performs the normal -default simplifications on a formula; for example, @samp{a - -b} is -changed to @samp{a + b}. These simplifications are normally done -automatically on all Calc results, so this command is useful only if -you have turned default simplifications off with an @kbd{m O} -command. @xref{Simplification Modes}. - -It is often more convenient to type @kbd{=}, which is like @kbd{a v} -but which also substitutes stored values for variables in the formula. -Use @kbd{a v} if you want the variables to ignore their stored values. - -If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies -using Calc's algebraic simplifications; @pxref{Simplifying Formulas}. -If you give a numeric prefix of 3 or more, it uses Extended -Simplification mode (@kbd{a e}). - -If you give a negative prefix argument @mathit{-1}, @mathit{-2}, or @mathit{-3}, -it simplifies in the corresponding mode but only works on the top-level -function call of the formula. For example, @samp{(2 + 3) * (2 + 3)} will -simplify to @samp{(2 + 3)^2}, without simplifying the sub-formulas -@samp{2 + 3}. As another example, typing @kbd{V R +} to sum the vector -@samp{[1, 2, 3, 4]} produces the formula @samp{reduce(add, [1, 2, 3, 4])} -in No-Simplify mode. Using @kbd{a v} will evaluate this all the way to -10; using @kbd{C-u - a v} will evaluate it only to @samp{1 + 2 + 3 + 4}. -(@xref{Reducing and Mapping}.) - -@tindex evalv -@tindex evalvn -The @kbd{=} command corresponds to the @code{evalv} function, and -the related @kbd{N} command, which is like @kbd{=} but temporarily -disables Symbolic mode (@kbd{m s}) during the evaluation, corresponds -to the @code{evalvn} function. (These commands interpret their prefix -arguments differently than @kbd{a v}; @kbd{=} treats the prefix as -the number of stack elements to evaluate at once, and @kbd{N} treats -it as a temporary different working precision.) - -The @code{evalvn} function can take an alternate working precision -as an optional second argument. This argument can be either an -integer, to set the precision absolutely, or a vector containing -a single integer, to adjust the precision relative to the current -precision. Note that @code{evalvn} with a larger than current -precision will do the calculation at this higher precision, but the -result will as usual be rounded back down to the current precision -afterward. For example, @samp{evalvn(pi - 3.1415)} at a precision -of 12 will return @samp{9.265359e-5}; @samp{evalvn(pi - 3.1415, 30)} -will return @samp{9.26535897932e-5} (computing a 25-digit result which -is then rounded down to 12); and @samp{evalvn(pi - 3.1415, [-2])} -will return @samp{9.2654e-5}. - -@kindex a " -@pindex calc-expand-formula -The @kbd{a "} (@code{calc-expand-formula}) command expands functions -into their defining formulas wherever possible. For example, -@samp{deg(x^2)} is changed to @samp{180 x^2 / pi}. Most functions, -like @code{sin} and @code{gcd}, are not defined by simple formulas -and so are unaffected by this command. One important class of -functions which @emph{can} be expanded is the user-defined functions -created by the @kbd{Z F} command. @xref{Algebraic Definitions}. -Other functions which @kbd{a "} can expand include the probability -distribution functions, most of the financial functions, and the -hyperbolic and inverse hyperbolic functions. A numeric prefix argument -affects @kbd{a "} in the same way as it does @kbd{a v}: A positive -argument expands all functions in the formula and then simplifies in -various ways; a negative argument expands and simplifies only the -top-level function call. - -@kindex a M -@pindex calc-map-equation -@tindex mapeq -The @kbd{a M} (@code{calc-map-equation}) [@code{mapeq}] command applies -a given function or operator to one or more equations. It is analogous -to @kbd{V M}, which operates on vectors instead of equations. -@pxref{Reducing and Mapping}. For example, @kbd{a M S} changes -@samp{x = y+1} to @samp{sin(x) = sin(y+1)}, and @kbd{a M +} with -@samp{x = y+1} and @expr{6} on the stack produces @samp{x+6 = y+7}. -With two equations on the stack, @kbd{a M +} would add the lefthand -sides together and the righthand sides together to get the two -respective sides of a new equation. - -Mapping also works on inequalities. Mapping two similar inequalities -produces another inequality of the same type. Mapping an inequality -with an equation produces an inequality of the same type. Mapping a -@samp{<=} with a @samp{<} or @samp{!=} (not-equal) produces a @samp{<}. -If inequalities with opposite direction (e.g., @samp{<} and @samp{>}) -are mapped, the direction of the second inequality is reversed to -match the first: Using @kbd{a M +} on @samp{a < b} and @samp{a > 2} -reverses the latter to get @samp{2 < a}, which then allows the -combination @samp{a + 2 < b + a}, which the algebraic simplifications -can reduce to @samp{2 < b}. - -Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate -or invert an inequality will reverse the direction of the inequality. -Other adjustments to inequalities are @emph{not} done automatically; -@kbd{a M S} will change @w{@samp{x < y}} to @samp{sin(x) < sin(y)} even -though this is not true for all values of the variables. - -@kindex H a M -@tindex mapeqp -With the Hyperbolic flag, @kbd{H a M} [@code{mapeqp}] does a plain -mapping operation without reversing the direction of any inequalities. -Thus, @kbd{H a M &} would change @kbd{x > 2} to @kbd{1/x > 0.5}. -(This change is mathematically incorrect, but perhaps you were -fixing an inequality which was already incorrect.) - -@kindex I a M -@tindex mapeqr -With the Inverse flag, @kbd{I a M} [@code{mapeqr}] always reverses -the direction of the inequality. You might use @kbd{I a M C} to -change @samp{x < y} to @samp{cos(x) > cos(y)} if you know you are -working with small positive angles. - -@kindex a b -@pindex calc-substitute -@tindex subst -The @kbd{a b} (@code{calc-substitute}) [@code{subst}] command substitutes -all occurrences -of some variable or sub-expression of an expression with a new -sub-expression. For example, substituting @samp{sin(x)} with @samp{cos(y)} -in @samp{2 sin(x)^2 + x sin(x) + sin(2 x)} produces -@samp{2 cos(y)^2 + x cos(y) + @w{sin(2 x)}}. -Note that this is a purely structural substitution; the lone @samp{x} and -the @samp{sin(2 x)} stayed the same because they did not look like -@samp{sin(x)}. @xref{Rewrite Rules}, for a more general method for -doing substitutions. - -The @kbd{a b} command normally prompts for two formulas, the old -one and the new one. If you enter a blank line for the first -prompt, all three arguments are taken from the stack (new, then old, -then target expression). If you type an old formula but then enter a -blank line for the new one, the new formula is taken from top-of-stack -and the target from second-to-top. If you answer both prompts, the -target is taken from top-of-stack as usual. - -Note that @kbd{a b} has no understanding of commutativity or -associativity. The pattern @samp{x+y} will not match the formula -@samp{y+x}. Also, @samp{y+z} will not match inside the formula @samp{x+y+z} -because the @samp{+} operator is left-associative, so the ``deep -structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U} -(@code{calc-unformatted-language}) mode to see the true structure of -a formula. The rewrite rule mechanism, discussed later, does not have -these limitations. - -As an algebraic function, @code{subst} takes three arguments: -Target expression, old, new. Note that @code{subst} is always -evaluated immediately, even if its arguments are variables, so if -you wish to put a call to @code{subst} onto the stack you must -turn the default simplifications off first (with @kbd{m O}). - -@node Simplifying Formulas, Polynomials, Algebraic Manipulation, Algebra -@section Simplifying Formulas - -@noindent -@kindex a s -@kindex I a s -@kindex H a s -@pindex calc-simplify -@tindex simplify - -The sections below describe all the various kinds of -simplifications Calc provides in full detail. None of Calc's -simplification commands are designed to pull rabbits out of hats; -they simply apply certain specific rules to put formulas into -less redundant or more pleasing forms. Serious algebra in Calc -must be done manually, usually with a combination of selections -and rewrite rules. @xref{Rearranging with Selections}. -@xref{Rewrite Rules}. - -@xref{Simplification Modes}, for commands to control what level of -simplification occurs automatically. Normally the algebraic -simplifications described below occur. If you have turned on a -simplification mode which does not do these algebraic simplifications, -you can still apply them to a formula with the @kbd{a s} -(@code{calc-simplify}) [@code{simplify}] command. - -There are some simplifications that, while sometimes useful, are never -done automatically. For example, the @kbd{I} prefix can be given to -@kbd{a s}; the @kbd{I a s} command will change any trigonometric -function to the appropriate combination of @samp{sin}s and @samp{cos}s -before simplifying. This can be useful in simplifying even mildly -complicated trigonometric expressions. For example, while the algebraic -simplifications can reduce @samp{sin(x) csc(x)} to @samp{1}, they will not -simplify @samp{sin(x)^2 csc(x)}. The command @kbd{I a s} can be used to -simplify this latter expression; it will transform @samp{sin(x)^2 -csc(x)} into @samp{sin(x)}. However, @kbd{I a s} will also perform -some ``simplifications'' which may not be desired; for example, it -will transform @samp{tan(x)^2} into @samp{sin(x)^2 / cos(x)^2}. The -Hyperbolic prefix @kbd{H} can be used similarly; the @kbd{H a s} will -replace any hyperbolic functions in the formula with the appropriate -combinations of @samp{sinh}s and @samp{cosh}s before simplifying. - - -@menu -* Basic Simplifications:: -* Algebraic Simplifications:: -* Unsafe Simplifications:: -* Simplification of Units:: -@end menu - -@node Basic Simplifications, Algebraic Simplifications, Simplifying Formulas, Simplifying Formulas -@subsection Basic Simplifications - -@noindent -@cindex Basic simplifications -This section describes basic simplifications which Calc performs in many -situations. For example, both binary simplifications and algebraic -simplifications begin by performing these basic simplifications. You -can type @kbd{m I} to restrict the simplifications done on the stack to -these simplifications. - -The most basic simplification is the evaluation of functions. -For example, @expr{2 + 3} is evaluated to @expr{5}, and @expr{@tfn{sqrt}(9)} -is evaluated to @expr{3}. Evaluation does not occur if the arguments -to a function are somehow of the wrong type @expr{@tfn{tan}([2,3,4])}), -range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}), -or if the function name is not recognized (@expr{@tfn{f}(5)}), or if -Symbolic mode (@pxref{Symbolic Mode}) prevents evaluation -(@expr{@tfn{sqrt}(2)}). - -Calc simplifies (evaluates) the arguments to a function before it -simplifies the function itself. Thus @expr{@tfn{sqrt}(5+4)} is -simplified to @expr{@tfn{sqrt}(9)} before the @code{sqrt} function -itself is applied. There are very few exceptions to this rule: -@code{quote}, @code{lambda}, and @code{condition} (the @code{::} -operator) do not evaluate their arguments, @code{if} (the @code{? :} -operator) does not evaluate all of its arguments, and @code{evalto} -does not evaluate its lefthand argument. - -Most commands apply at least these basic simplifications to all -arguments they take from the stack, perform a particular operation, -then simplify the result before pushing it back on the stack. In the -common special case of regular arithmetic commands like @kbd{+} and -@kbd{Q} [@code{sqrt}], the arguments are simply popped from the stack -and collected into a suitable function call, which is then simplified -(the arguments being simplified first as part of the process, as -described above). - -Even the basic set of simplifications are too numerous to describe -completely here, but this section will describe the ones that apply to the -major arithmetic operators. This list will be rather technical in -nature, and will probably be interesting to you only if you are -a serious user of Calc's algebra facilities. - -@tex -\bigskip -@end tex - -As well as the simplifications described here, if you have stored -any rewrite rules in the variable @code{EvalRules} then these rules -will also be applied before any of the basic simplifications. -@xref{Automatic Rewrites}, for details. - -@tex -\bigskip -@end tex - -And now, on with the basic simplifications: - -Arithmetic operators like @kbd{+} and @kbd{*} always take two -arguments in Calc's internal form. Sums and products of three or -more terms are arranged by the associative law of algebra into -a left-associative form for sums, @expr{((a + b) + c) + d}, and -(by default) a right-associative form for products, -@expr{a * (b * (c * d))}. Formulas like @expr{(a + b) + (c + d)} are -rearranged to left-associative form, though this rarely matters since -Calc's algebra commands are designed to hide the inner structure of sums -and products as much as possible. Sums and products in their proper -associative form will be written without parentheses in the examples -below. - -Sums and products are @emph{not} rearranged according to the -commutative law (@expr{a + b} to @expr{b + a}) except in a few -special cases described below. Some algebra programs always -rearrange terms into a canonical order, which enables them to -see that @expr{a b + b a} can be simplified to @expr{2 a b}. -If you are using Basic Simplification mode, Calc assumes you have put -the terms into the order you want and generally leaves that order alone, -with the consequence that formulas like the above will only be -simplified if you explicitly give the @kbd{a s} command. -@xref{Algebraic Simplifications}. - -Differences @expr{a - b} are treated like sums @expr{a + (-b)} -for purposes of simplification; one of the default simplifications -is to rewrite @expr{a + (-b)} or @expr{(-b) + a}, where @expr{-b} -represents a ``negative-looking'' term, into @expr{a - b} form. -``Negative-looking'' means negative numbers, negated formulas like -@expr{-x}, and products or quotients in which either term is -negative-looking. - -Other simplifications involving negation are @expr{-(-x)} to @expr{x}; -@expr{-(a b)} or @expr{-(a/b)} where either @expr{a} or @expr{b} is -negative-looking, simplified by negating that term, or else where -@expr{a} or @expr{b} is any number, by negating that number; -@expr{-(a + b)} to @expr{-a - b}, and @expr{-(b - a)} to @expr{a - b}. -(This, and rewriting @expr{(-b) + a} to @expr{a - b}, are the only -cases where the order of terms in a sum is changed by the default -simplifications.) - -The distributive law is used to simplify sums in some cases: -@expr{a x + b x} to @expr{(a + b) x}, where @expr{a} represents -a number or an implicit 1 or @mathit{-1} (as in @expr{x} or @expr{-x}) -and similarly for @expr{b}. Use the @kbd{a c}, @w{@kbd{a f}}, or -@kbd{j M} commands to merge sums with non-numeric coefficients -using the distributive law. - -The distributive law is only used for sums of two terms, or -for adjacent terms in a larger sum. Thus @expr{a + b + b + c} -is simplified to @expr{a + 2 b + c}, but @expr{a + b + c + b} -is not simplified. The reason is that comparing all terms of a -sum with one another would require time proportional to the -square of the number of terms; Calc omits potentially slow -operations like this in basic simplification mode. - -Finally, @expr{a + 0} and @expr{0 + a} are simplified to @expr{a}. -A consequence of the above rules is that @expr{0 - a} is simplified -to @expr{-a}. - -@tex -\bigskip -@end tex - -The products @expr{1 a} and @expr{a 1} are simplified to @expr{a}; -@expr{(-1) a} and @expr{a (-1)} are simplified to @expr{-a}; -@expr{0 a} and @expr{a 0} are simplified to @expr{0}, except that -in Matrix mode where @expr{a} is not provably scalar the result -is the generic zero matrix @samp{idn(0)}, and that if @expr{a} is -infinite the result is @samp{nan}. - -Also, @expr{(-a) b} and @expr{a (-b)} are simplified to @expr{-(a b)}, -where this occurs for negated formulas but not for regular negative -numbers. - -Products are commuted only to move numbers to the front: -@expr{a b 2} is commuted to @expr{2 a b}. - -The product @expr{a (b + c)} is distributed over the sum only if -@expr{a} and at least one of @expr{b} and @expr{c} are numbers: -@expr{2 (x + 3)} goes to @expr{2 x + 6}. The formula -@expr{(-a) (b - c)}, where @expr{-a} is a negative number, is -rewritten to @expr{a (c - b)}. - -The distributive law of products and powers is used for adjacent -terms of the product: @expr{x^a x^b} goes to -@texline @math{x^{a+b}} -@infoline @expr{x^(a+b)} -where @expr{a} is a number, or an implicit 1 (as in @expr{x}), -or the implicit one-half of @expr{@tfn{sqrt}(x)}, and similarly for -@expr{b}. The result is written using @samp{sqrt} or @samp{1/sqrt} -if the sum of the powers is @expr{1/2} or @expr{-1/2}, respectively. -If the sum of the powers is zero, the product is simplified to -@expr{1} or to @samp{idn(1)} if Matrix mode is enabled. - -The product of a negative power times anything but another negative -power is changed to use division: -@texline @math{x^{-2} y} -@infoline @expr{x^(-2) y} -goes to @expr{y / x^2} unless Matrix mode is -in effect and neither @expr{x} nor @expr{y} are scalar (in which -case it is considered unsafe to rearrange the order of the terms). - -Finally, @expr{a (b/c)} is rewritten to @expr{(a b)/c}, and also -@expr{(a/b) c} is changed to @expr{(a c)/b} unless in Matrix mode. - -@tex -\bigskip -@end tex - -Simplifications for quotients are analogous to those for products. -The quotient @expr{0 / x} is simplified to @expr{0}, with the same -exceptions that were noted for @expr{0 x}. Likewise, @expr{x / 1} -and @expr{x / (-1)} are simplified to @expr{x} and @expr{-x}, -respectively. - -The quotient @expr{x / 0} is left unsimplified or changed to an -infinite quantity, as directed by the current infinite mode. -@xref{Infinite Mode}. - -The expression -@texline @math{a / b^{-c}} -@infoline @expr{a / b^(-c)} -is changed to @expr{a b^c}, where @expr{-c} is any negative-looking -power. Also, @expr{1 / b^c} is changed to -@texline @math{b^{-c}} -@infoline @expr{b^(-c)} -for any power @expr{c}. - -Also, @expr{(-a) / b} and @expr{a / (-b)} go to @expr{-(a/b)}; -@expr{(a/b) / c} goes to @expr{a / (b c)}; and @expr{a / (b/c)} -goes to @expr{(a c) / b} unless Matrix mode prevents this -rearrangement. Similarly, @expr{a / (b:c)} is simplified to -@expr{(c:b) a} for any fraction @expr{b:c}. - -The distributive law is applied to @expr{(a + b) / c} only if -@expr{c} and at least one of @expr{a} and @expr{b} are numbers. -Quotients of powers and square roots are distributed just as -described for multiplication. - -Quotients of products cancel only in the leading terms of the -numerator and denominator. In other words, @expr{a x b / a y b} -is canceled to @expr{x b / y b} but not to @expr{x / y}. Once -again this is because full cancellation can be slow; use @kbd{a s} -to cancel all terms of the quotient. - -Quotients of negative-looking values are simplified according -to @expr{(-a) / (-b)} to @expr{a / b}, @expr{(-a) / (b - c)} -to @expr{a / (c - b)}, and @expr{(a - b) / (-c)} to @expr{(b - a) / c}. - -@tex -\bigskip -@end tex - -The formula @expr{x^0} is simplified to @expr{1}, or to @samp{idn(1)} -in Matrix mode. The formula @expr{0^x} is simplified to @expr{0} -unless @expr{x} is a negative number, complex number or zero. -If @expr{x} is negative, complex or @expr{0.0}, @expr{0^x} is an -infinity or an unsimplified formula according to the current infinite -mode. The expression @expr{0^0} is simplified to @expr{1}. - -Powers of products or quotients @expr{(a b)^c}, @expr{(a/b)^c} -are distributed to @expr{a^c b^c}, @expr{a^c / b^c} only if @expr{c} -is an integer, or if either @expr{a} or @expr{b} are nonnegative -real numbers. Powers of powers @expr{(a^b)^c} are simplified to -@texline @math{a^{b c}} -@infoline @expr{a^(b c)} -only when @expr{c} is an integer and @expr{b c} also -evaluates to an integer. Without these restrictions these simplifications -would not be safe because of problems with principal values. -(In other words, -@texline @math{((-3)^{1/2})^2} -@infoline @expr{((-3)^1:2)^2} -is safe to simplify, but -@texline @math{((-3)^2)^{1/2}} -@infoline @expr{((-3)^2)^1:2} -is not.) @xref{Declarations}, for ways to inform Calc that your -variables satisfy these requirements. - -As a special case of this rule, @expr{@tfn{sqrt}(x)^n} is simplified to -@texline @math{x^{n/2}} -@infoline @expr{x^(n/2)} -only for even integers @expr{n}. - -If @expr{a} is known to be real, @expr{b} is an even integer, and -@expr{c} is a half- or quarter-integer, then @expr{(a^b)^c} is -simplified to @expr{@tfn{abs}(a^(b c))}. - -Also, @expr{(-a)^b} is simplified to @expr{a^b} if @expr{b} is an -even integer, or to @expr{-(a^b)} if @expr{b} is an odd integer, -for any negative-looking expression @expr{-a}. - -Square roots @expr{@tfn{sqrt}(x)} generally act like one-half powers -@texline @math{x^{1:2}} -@infoline @expr{x^1:2} -for the purposes of the above-listed simplifications. - -Also, note that -@texline @math{1 / x^{1:2}} -@infoline @expr{1 / x^1:2} -is changed to -@texline @math{x^{-1:2}}, -@infoline @expr{x^(-1:2)}, -but @expr{1 / @tfn{sqrt}(x)} is left alone. - -@tex -\bigskip -@end tex - -Generic identity matrices (@pxref{Matrix Mode}) are simplified by the -following rules: @expr{@tfn{idn}(a) + b} to @expr{a + b} if @expr{b} -is provably scalar, or expanded out if @expr{b} is a matrix; -@expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)}; -@expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to -@expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b} -if @expr{a} is provably non-scalar; @expr{@tfn{idn}(a) @tfn{idn}(b)} to -@expr{@tfn{idn}(a b)}; analogous simplifications for quotients involving -@code{idn}; and @expr{@tfn{idn}(a)^n} to @expr{@tfn{idn}(a^n)} where -@expr{n} is an integer. - -@tex -\bigskip -@end tex - -The @code{floor} function and other integer truncation functions -vanish if the argument is provably integer-valued, so that -@expr{@tfn{floor}(@tfn{round}(x))} simplifies to @expr{@tfn{round}(x)}. -Also, combinations of @code{float}, @code{floor} and its friends, -and @code{ffloor} and its friends, are simplified in appropriate -ways. @xref{Integer Truncation}. - -The expression @expr{@tfn{abs}(-x)} changes to @expr{@tfn{abs}(x)}. -The expression @expr{@tfn{abs}(@tfn{abs}(x))} changes to -@expr{@tfn{abs}(x)}; in fact, @expr{@tfn{abs}(x)} changes to @expr{x} or -@expr{-x} if @expr{x} is provably nonnegative or nonpositive -(@pxref{Declarations}). - -While most functions do not recognize the variable @code{i} as an -imaginary number, the @code{arg} function does handle the two cases -@expr{@tfn{arg}(@tfn{i})} and @expr{@tfn{arg}(-@tfn{i})} just for convenience. - -The expression @expr{@tfn{conj}(@tfn{conj}(x))} simplifies to @expr{x}. -Various other expressions involving @code{conj}, @code{re}, and -@code{im} are simplified, especially if some of the arguments are -provably real or involve the constant @code{i}. For example, -@expr{@tfn{conj}(a + b i)} is changed to -@expr{@tfn{conj}(a) - @tfn{conj}(b) i}, or to @expr{a - b i} if @expr{a} -and @expr{b} are known to be real. - -Functions like @code{sin} and @code{arctan} generally don't have -any default simplifications beyond simply evaluating the functions -for suitable numeric arguments and infinity. The algebraic -simplifications described in the next section do provide some -simplifications for these functions, though. - -One important simplification that does occur is that -@expr{@tfn{ln}(@tfn{e})} is simplified to 1, and @expr{@tfn{ln}(@tfn{e}^x)} is -simplified to @expr{x} for any @expr{x}. This occurs even if you have -stored a different value in the Calc variable @samp{e}; but this would -be a bad idea in any case if you were also using natural logarithms! - -Among the logical functions, @tfn{!(@var{a} <= @var{b})} changes to -@tfn{@var{a} > @var{b}} and so on. Equations and inequalities where both sides -are either negative-looking or zero are simplified by negating both sides -and reversing the inequality. While it might seem reasonable to simplify -@expr{!!x} to @expr{x}, this would not be valid in general because -@expr{!!2} is 1, not 2. - -Most other Calc functions have few if any basic simplifications -defined, aside of course from evaluation when the arguments are -suitable numbers. - -@node Algebraic Simplifications, Unsafe Simplifications, Basic Simplifications, Simplifying Formulas -@subsection Algebraic Simplifications - -@noindent -@cindex Algebraic simplifications -@kindex a s -@kindex m A -This section describes all simplifications that are performed by -the algebraic simplification mode, which is the default simplification -mode. If you have switched to a different simplification mode, you can -switch back with the @kbd{m A} command. Even in other simplification -modes, the @kbd{a s} command will use these algebraic simplifications to -simplify the formula. - -There is a variable, @code{AlgSimpRules}, in which you can put rewrites -to be applied. Its use is analogous to @code{EvalRules}, -but without the special restrictions. Basically, the simplifier does -@samp{@w{a r} AlgSimpRules} with an infinite repeat count on the whole -expression being simplified, then it traverses the expression applying -the built-in rules described below. If the result is different from -the original expression, the process repeats with the basic -simplifications (including @code{EvalRules}), then @code{AlgSimpRules}, -then the built-in simplifications, and so on. - -@tex -\bigskip -@end tex - -Sums are simplified in two ways. Constant terms are commuted to the -end of the sum, so that @expr{a + 2 + b} changes to @expr{a + b + 2}. -The only exception is that a constant will not be commuted away -from the first position of a difference, i.e., @expr{2 - x} is not -commuted to @expr{-x + 2}. - -Also, terms of sums are combined by the distributive law, as in -@expr{x + y + 2 x} to @expr{y + 3 x}. This always occurs for -adjacent terms, but Calc's algebraic simplifications compare all pairs -of terms including non-adjacent ones. - -@tex -\bigskip -@end tex - -Products are sorted into a canonical order using the commutative -law. For example, @expr{b c a} is commuted to @expr{a b c}. -This allows easier comparison of products; for example, the basic -simplifications will not change @expr{x y + y x} to @expr{2 x y}, -but the algebraic simplifications; it first rewrites the sum to -@expr{x y + x y} which can then be recognized as a sum of identical -terms. - -The canonical ordering used to sort terms of products has the -property that real-valued numbers, interval forms and infinities -come first, and are sorted into increasing order. The @kbd{V S} -command uses the same ordering when sorting a vector. - -Sorting of terms of products is inhibited when Matrix mode is -turned on; in this case, Calc will never exchange the order of -two terms unless it knows at least one of the terms is a scalar. - -Products of powers are distributed by comparing all pairs of -terms, using the same method that the default simplifications -use for adjacent terms of products. - -Even though sums are not sorted, the commutative law is still -taken into account when terms of a product are being compared. -Thus @expr{(x + y) (y + x)} will be simplified to @expr{(x + y)^2}. -A subtle point is that @expr{(x - y) (y - x)} will @emph{not} -be simplified to @expr{-(x - y)^2}; Calc does not notice that -one term can be written as a constant times the other, even if -that constant is @mathit{-1}. - -A fraction times any expression, @expr{(a:b) x}, is changed to -a quotient involving integers: @expr{a x / b}. This is not -done for floating-point numbers like @expr{0.5}, however. This -is one reason why you may find it convenient to turn Fraction mode -on while doing algebra; @pxref{Fraction Mode}. - -@tex -\bigskip -@end tex - -Quotients are simplified by comparing all terms in the numerator -with all terms in the denominator for possible cancellation using -the distributive law. For example, @expr{a x^2 b / c x^3 d} will -cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}. -(The terms in the denominator will then be rearranged to @expr{c d x} -as described above.) If there is any common integer or fractional -factor in the numerator and denominator, it is canceled out; -for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}. - -Non-constant common factors are not found even by algebraic -simplifications. To cancel the factor @expr{a} in -@expr{(a x + a) / a^2} you could first use @kbd{j M} on the product -@expr{a x} to Merge the numerator to @expr{a (1+x)}, which can then be -simplified successfully. - -@tex -\bigskip -@end tex - -Integer powers of the variable @code{i} are simplified according -to the identity @expr{i^2 = -1}. If you store a new value other -than the complex number @expr{(0,1)} in @code{i}, this simplification -will no longer occur. This is not done by the basic -simplifications; in case someone (unwisely) wants to use the name -@code{i} for a variable unrelated to complex numbers, they can use -basic simplification mode. - -Square roots of integer or rational arguments are simplified in -several ways. (Note that these will be left unevaluated only in -Symbolic mode.) First, square integer or rational factors are -pulled out so that @expr{@tfn{sqrt}(8)} is rewritten as -@texline @math{2\,@tfn{sqrt}(2)}. -@infoline @expr{2 sqrt(2)}. -Conceptually speaking this implies factoring the argument into primes -and moving pairs of primes out of the square root, but for reasons of -efficiency Calc only looks for primes up to 29. - -Square roots in the denominator of a quotient are moved to the -numerator: @expr{1 / @tfn{sqrt}(3)} changes to @expr{@tfn{sqrt}(3) / 3}. -The same effect occurs for the square root of a fraction: -@expr{@tfn{sqrt}(2:3)} changes to @expr{@tfn{sqrt}(6) / 3}. - -@tex -\bigskip -@end tex - -The @code{%} (modulo) operator is simplified in several ways -when the modulus @expr{M} is a positive real number. First, if -the argument is of the form @expr{x + n} for some real number -@expr{n}, then @expr{n} is itself reduced modulo @expr{M}. For -example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}. - -If the argument is multiplied by a constant, and this constant -has a common integer divisor with the modulus, then this factor is -canceled out. For example, @samp{12 x % 15} is changed to -@samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15} -is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may -not seem ``simpler,'' they allow Calc to discover useful information -about modulo forms in the presence of declarations. - -If the modulus is 1, then Calc can use @code{int} declarations to -evaluate the expression. For example, the idiom @samp{x % 2} is -often used to check whether a number is odd or even. As described -above, @w{@samp{2 n % 2}} and @samp{(2 n + 1) % 2} are simplified to -@samp{2 (n % 1)} and @samp{2 ((n + 1:2) % 1)}, respectively; Calc -can simplify these to 0 and 1 (respectively) if @code{n} has been -declared to be an integer. - -@tex -\bigskip -@end tex - -Trigonometric functions are simplified in several ways. Whenever a -products of two trigonometric functions can be replaced by a single -function, the replacement is made; for example, -@expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}. -Reciprocals of trigonometric functions are replaced by their reciprocal -function; for example, @expr{1/@tfn{sec}(x)} is simplified to -@expr{@tfn{cos}(x)}. The corresponding simplifications for the -hyperbolic functions are also handled. - -Trigonometric functions of their inverse functions are -simplified. The expression @expr{@tfn{sin}(@tfn{arcsin}(x))} is -simplified to @expr{x}, and similarly for @code{cos} and @code{tan}. -Trigonometric functions of inverses of different trigonometric -functions can also be simplified, as in @expr{@tfn{sin}(@tfn{arccos}(x))} -to @expr{@tfn{sqrt}(1 - x^2)}. - -If the argument to @code{sin} is negative-looking, it is simplified to -@expr{-@tfn{sin}(x)}, and similarly for @code{cos} and @code{tan}. -Finally, certain special values of the argument are recognized; -@pxref{Trigonometric and Hyperbolic Functions}. - -Hyperbolic functions of their inverses and of negative-looking -arguments are also handled, as are exponentials of inverse -hyperbolic functions. - -No simplifications for inverse trigonometric and hyperbolic -functions are known, except for negative arguments of @code{arcsin}, -@code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that -@expr{@tfn{arcsin}(@tfn{sin}(x))} can @emph{not} safely change to -@expr{x}, since this only correct within an integer multiple of -@texline @math{2 \pi} -@infoline @expr{2 pi} -radians or 360 degrees. However, @expr{@tfn{arcsinh}(@tfn{sinh}(x))} is -simplified to @expr{x} if @expr{x} is known to be real. - -Several simplifications that apply to logarithms and exponentials -are that @expr{@tfn{exp}(@tfn{ln}(x))}, -@texline @tfn{e}@math{^{\ln(x)}}, -@infoline @expr{e^@tfn{ln}(x)}, -and -@texline @math{10^{{\rm log10}(x)}} -@infoline @expr{10^@tfn{log10}(x)} -all reduce to @expr{x}. Also, @expr{@tfn{ln}(@tfn{exp}(x))}, etc., can -reduce to @expr{x} if @expr{x} is provably real. The form -@expr{@tfn{exp}(x)^y} is simplified to @expr{@tfn{exp}(x y)}. If @expr{x} -is a suitable multiple of -@texline @math{\pi i} -@infoline @expr{pi i} -(as described above for the trigonometric functions), then -@expr{@tfn{exp}(x)} or @expr{e^x} will be expanded. Finally, -@expr{@tfn{ln}(x)} is simplified to a form involving @code{pi} and -@code{i} where @expr{x} is provably negative, positive imaginary, or -negative imaginary. - -The error functions @code{erf} and @code{erfc} are simplified when -their arguments are negative-looking or are calls to the @code{conj} -function. - -@tex -\bigskip -@end tex - -Equations and inequalities are simplified by canceling factors -of products, quotients, or sums on both sides. Inequalities -change sign if a negative multiplicative factor is canceled. -Non-constant multiplicative factors as in @expr{a b = a c} are -canceled from equations only if they are provably nonzero (generally -because they were declared so; @pxref{Declarations}). Factors -are canceled from inequalities only if they are nonzero and their -sign is known. - -Simplification also replaces an equation or inequality with -1 or 0 (``true'' or ``false'') if it can through the use of -declarations. If @expr{x} is declared to be an integer greater -than 5, then @expr{x < 3}, @expr{x = 3}, and @expr{x = 7.5} are -all simplified to 0, but @expr{x > 3} is simplified to 1. -By a similar analysis, @expr{abs(x) >= 0} is simplified to 1, -as is @expr{x^2 >= 0} if @expr{x} is known to be real. - -@node Unsafe Simplifications, Simplification of Units, Algebraic Simplifications, Simplifying Formulas -@subsection ``Unsafe'' Simplifications - -@noindent -@cindex Unsafe simplifications -@cindex Extended simplification -@kindex a e -@kindex m E -@pindex calc-simplify-extended -@ignore -@mindex esimpl@idots -@end ignore -@tindex esimplify -Calc is capable of performing some simplifications which may sometimes -be desired but which are not ``safe'' in all cases. The @kbd{a e} -(@code{calc-simplify-extended}) [@code{esimplify}] command -applies the algebraic simplifications as well as these extended, or -``unsafe'', simplifications. Use this only if you know the values in -your formula lie in the restricted ranges for which these -simplifications are valid. You can use Extended Simplification mode -(@kbd{m E}) to have these simplifications done automatically. - -The symbolic integrator uses these extended simplifications; one effect -of this is that the integrator's results must be used with caution. -Where an integral table will often attach conditions like ``for positive -@expr{a} only,'' Calc (like most other symbolic integration programs) -will simply produce an unqualified result. - -Because @kbd{a e}'s simplifications are unsafe, it is sometimes better -to type @kbd{C-u -3 a v}, which does extended simplification only -on the top level of the formula without affecting the sub-formulas. -In fact, @kbd{C-u -3 j v} allows you to target extended simplification -to any specific part of a formula. - -The variable @code{ExtSimpRules} contains rewrites to be applied when -the extended simplifications are used. These are applied in addition to -@code{EvalRules} and @code{AlgSimpRules}. (The @kbd{a r AlgSimpRules} -step described above is simply followed by an @kbd{a r ExtSimpRules} step.) - -Following is a complete list of the ``unsafe'' simplifications. - -@tex -\bigskip -@end tex - -Inverse trigonometric or hyperbolic functions, called with their -corresponding non-inverse functions as arguments, are simplified. -For example, @expr{@tfn{arcsin}(@tfn{sin}(x))} changes -to @expr{x}. Also, @expr{@tfn{arcsin}(@tfn{cos}(x))} and -@expr{@tfn{arccos}(@tfn{sin}(x))} both change to @expr{@tfn{pi}/2 - x}. -These simplifications are unsafe because they are valid only for -values of @expr{x} in a certain range; outside that range, values -are folded down to the 360-degree range that the inverse trigonometric -functions always produce. - -Powers of powers @expr{(x^a)^b} are simplified to -@texline @math{x^{a b}} -@infoline @expr{x^(a b)} -for all @expr{a} and @expr{b}. These results will be valid only -in a restricted range of @expr{x}; for example, in -@texline @math{(x^2)^{1:2}} -@infoline @expr{(x^2)^1:2} -the powers cancel to get @expr{x}, which is valid for positive values -of @expr{x} but not for negative or complex values. - -Similarly, @expr{@tfn{sqrt}(x^a)} and @expr{@tfn{sqrt}(x)^a} are both -simplified (possibly unsafely) to -@texline @math{x^{a/2}}. -@infoline @expr{x^(a/2)}. - -Forms like @expr{@tfn{sqrt}(1 - sin(x)^2)} are simplified to, e.g., -@expr{@tfn{cos}(x)}. Calc has identities of this sort for @code{sin}, -@code{cos}, @code{tan}, @code{sinh}, and @code{cosh}. - -Arguments of square roots are partially factored to look for -squared terms that can be extracted. For example, -@expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to -@expr{a b @tfn{sqrt}(a+b)}. - -The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))}, -@expr{@tfn{ln}(@tfn{e}^x)}, and @expr{@tfn{log10}(10^x)} to @expr{x} are also -unsafe because of problems with principal values (although these -simplifications are safe if @expr{x} is known to be real). - -Common factors are canceled from products on both sides of an -equation, even if those factors may be zero: @expr{a x / b x} -to @expr{a / b}. Such factors are never canceled from -inequalities: Even the extended simplifications are not bold enough to -reduce @expr{a x < b x} to @expr{a < b} (or @expr{a > b}, depending -on whether you believe @expr{x} is positive or negative). -The @kbd{a M /} command can be used to divide a factor out of -both sides of an inequality. - -@node Simplification of Units, , Unsafe Simplifications, Simplifying Formulas -@subsection Simplification of Units - -@noindent -The simplifications described in this section (as well as the algebraic -simplifications) are applied when units need to be simplified. They can -be applied using the @kbd{u s} (@code{calc-simplify-units}) command, or -will be done automatically in Units Simplification mode (@kbd{m U}). -@xref{Basic Operations on Units}. - -The variable @code{UnitSimpRules} contains rewrites to be applied by -units simplifications. These are applied in addition to @code{EvalRules} -and @code{AlgSimpRules}. - -Scalar mode is automatically put into effect when simplifying units. -@xref{Matrix Mode}. - -Sums @expr{a + b} involving units are simplified by extracting the -units of @expr{a} as if by the @kbd{u x} command (call the result -@expr{u_a}), then simplifying the expression @expr{b / u_a} -using @kbd{u b} and @kbd{u s}. If the result has units then the sum -is inconsistent and is left alone. Otherwise, it is rewritten -in terms of the units @expr{u_a}. - -If units auto-ranging mode is enabled, products or quotients in -which the first argument is a number which is out of range for the -leading unit are modified accordingly. - -When canceling and combining units in products and quotients, -Calc accounts for unit names that differ only in the prefix letter. -For example, @samp{2 km m} is simplified to @samp{2000 m^2}. -However, compatible but different units like @code{ft} and @code{in} -are not combined in this way. - -Quotients @expr{a / b} are simplified in three additional ways. First, -if @expr{b} is a number or a product beginning with a number, Calc -computes the reciprocal of this number and moves it to the numerator. - -Second, for each pair of unit names from the numerator and denominator -of a quotient, if the units are compatible (e.g., they are both -units of area) then they are replaced by the ratio between those -units. For example, in @samp{3 s in N / kg cm} the units -@samp{in / cm} will be replaced by @expr{2.54}. - -Third, if the units in the quotient exactly cancel out, so that -a @kbd{u b} command on the quotient would produce a dimensionless -number for an answer, then the quotient simplifies to that number. - -For powers and square roots, the ``unsafe'' simplifications -@expr{(a b)^c} to @expr{a^c b^c}, @expr{(a/b)^c} to @expr{a^c / b^c}, -and @expr{(a^b)^c} to -@texline @math{a^{b c}} -@infoline @expr{a^(b c)} -are done if the powers are real numbers. (These are safe in the context -of units because all numbers involved can reasonably be assumed to be -real.) - -Also, if a unit name is raised to a fractional power, and the -base units in that unit name all occur to powers which are a -multiple of the denominator of the power, then the unit name -is expanded out into its base units, which can then be simplified -according to the previous paragraph. For example, @samp{acre^1.5} -is simplified by noting that @expr{1.5 = 3:2}, that @samp{acre} -is defined in terms of @samp{m^2}, and that the 2 in the power of -@code{m} is a multiple of 2 in @expr{3:2}. Thus, @code{acre^1.5} is -replaced by approximately -@texline @math{(4046 m^2)^{1.5}} -@infoline @expr{(4046 m^2)^1.5}, -which is then changed to -@texline @math{4046^{1.5} \, (m^2)^{1.5}}, -@infoline @expr{4046^1.5 (m^2)^1.5}, -then to @expr{257440 m^3}. - -The functions @code{float}, @code{frac}, @code{clean}, @code{abs}, -as well as @code{floor} and the other integer truncation functions, -applied to unit names or products or quotients involving units, are -simplified. For example, @samp{round(1.6 in)} is changed to -@samp{round(1.6) round(in)}; the lefthand term evaluates to 2, -and the righthand term simplifies to @code{in}. - -The functions @code{sin}, @code{cos}, and @code{tan} with arguments -that have angular units like @code{rad} or @code{arcmin} are -simplified by converting to base units (radians), then evaluating -with the angular mode temporarily set to radians. - -@node Polynomials, Calculus, Simplifying Formulas, Algebra -@section Polynomials - -A @dfn{polynomial} is a sum of terms which are coefficients times -various powers of a ``base'' variable. For example, @expr{2 x^2 + 3 x - 4} -is a polynomial in @expr{x}. Some formulas can be considered -polynomials in several different variables: @expr{1 + 2 x + 3 y + 4 x y^2} -is a polynomial in both @expr{x} and @expr{y}. Polynomial coefficients -are often numbers, but they may in general be any formulas not -involving the base variable. - -@kindex a f -@pindex calc-factor -@tindex factor -The @kbd{a f} (@code{calc-factor}) [@code{factor}] command factors a -polynomial into a product of terms. For example, the polynomial -@expr{x^3 + 2 x^2 + x} is factored into @samp{x*(x+1)^2}. As another -example, @expr{a c + b d + b c + a d} is factored into the product -@expr{(a + b) (c + d)}. - -Calc currently has three algorithms for factoring. Formulas which are -linear in several variables, such as the second example above, are -merged according to the distributive law. Formulas which are -polynomials in a single variable, with constant integer or fractional -coefficients, are factored into irreducible linear and/or quadratic -terms. The first example above factors into three linear terms -(@expr{x}, @expr{x+1}, and @expr{x+1} again). Finally, formulas -which do not fit the above criteria are handled by the algebraic -rewrite mechanism. - -Calc's polynomial factorization algorithm works by using the general -root-finding command (@w{@kbd{a P}}) to solve for the roots of the -polynomial. It then looks for roots which are rational numbers -or complex-conjugate pairs, and converts these into linear and -quadratic terms, respectively. Because it uses floating-point -arithmetic, it may be unable to find terms that involve large -integers (whose number of digits approaches the current precision). -Also, irreducible factors of degree higher than quadratic are not -found, and polynomials in more than one variable are not treated. -(A more robust factorization algorithm may be included in a future -version of Calc.) - -@vindex FactorRules -@ignore -@starindex -@end ignore -@tindex thecoefs -@ignore -@starindex -@end ignore -@ignore -@mindex @idots -@end ignore -@tindex thefactors -The rewrite-based factorization method uses rules stored in the variable -@code{FactorRules}. @xref{Rewrite Rules}, for a discussion of the -operation of rewrite rules. The default @code{FactorRules} are able -to factor quadratic forms symbolically into two linear terms, -@expr{(a x + b) (c x + d)}. You can edit these rules to include other -cases if you wish. To use the rules, Calc builds the formula -@samp{thecoefs(x, [a, b, c, ...])} where @code{x} is the polynomial -base variable and @code{a}, @code{b}, etc., are polynomial coefficients -(which may be numbers or formulas). The constant term is written first, -i.e., in the @code{a} position. When the rules complete, they should have -changed the formula into the form @samp{thefactors(x, [f1, f2, f3, ...])} -where each @code{fi} should be a factored term, e.g., @samp{x - ai}. -Calc then multiplies these terms together to get the complete -factored form of the polynomial. If the rules do not change the -@code{thecoefs} call to a @code{thefactors} call, @kbd{a f} leaves the -polynomial alone on the assumption that it is unfactorable. (Note that -the function names @code{thecoefs} and @code{thefactors} are used only -as placeholders; there are no actual Calc functions by those names.) - -@kindex H a f -@tindex factors -The @kbd{H a f} [@code{factors}] command also factors a polynomial, -but it returns a list of factors instead of an expression which is the -product of the factors. Each factor is represented by a sub-vector -of the factor, and the power with which it appears. For example, -@expr{x^5 + x^4 - 33 x^3 + 63 x^2} factors to @expr{(x + 7) x^2 (x - 3)^2} -in @kbd{a f}, or to @expr{[ [x, 2], [x+7, 1], [x-3, 2] ]} in @kbd{H a f}. -If there is an overall numeric factor, it always comes first in the list. -The functions @code{factor} and @code{factors} allow a second argument -when written in algebraic form; @samp{factor(x,v)} factors @expr{x} with -respect to the specific variable @expr{v}. The default is to factor with -respect to all the variables that appear in @expr{x}. - -@kindex a c -@pindex calc-collect -@tindex collect -The @kbd{a c} (@code{calc-collect}) [@code{collect}] command rearranges a -formula as a -polynomial in a given variable, ordered in decreasing powers of that -variable. For example, given @expr{1 + 2 x + 3 y + 4 x y^2} on -the stack, @kbd{a c x} would produce @expr{(2 + 4 y^2) x + (1 + 3 y)}, -and @kbd{a c y} would produce @expr{(4 x) y^2 + 3 y + (1 + 2 x)}. -The polynomial will be expanded out using the distributive law as -necessary: Collecting @expr{x} in @expr{(x - 1)^3} produces -@expr{x^3 - 3 x^2 + 3 x - 1}. Terms not involving @expr{x} will -not be expanded. - -The ``variable'' you specify at the prompt can actually be any -expression: @kbd{a c ln(x+1)} will collect together all terms multiplied -by @samp{ln(x+1)} or integer powers thereof. If @samp{x} also appears -in the formula in a context other than @samp{ln(x+1)}, @kbd{a c} will -treat those occurrences as unrelated to @samp{ln(x+1)}, i.e., as constants. - -@kindex a x -@pindex calc-expand -@tindex expand -The @kbd{a x} (@code{calc-expand}) [@code{expand}] command expands an -expression by applying the distributive law everywhere. It applies to -products, quotients, and powers involving sums. By default, it fully -distributes all parts of the expression. With a numeric prefix argument, -the distributive law is applied only the specified number of times, then -the partially expanded expression is left on the stack. - -The @kbd{a x} and @kbd{j D} commands are somewhat redundant. Use -@kbd{a x} if you want to expand all products of sums in your formula. -Use @kbd{j D} if you want to expand a particular specified term of -the formula. There is an exactly analogous correspondence between -@kbd{a f} and @kbd{j M}. (The @kbd{j D} and @kbd{j M} commands -also know many other kinds of expansions, such as -@samp{exp(a + b) = exp(a) exp(b)}, which @kbd{a x} and @kbd{a f} -do not do.) - -Calc's automatic simplifications will sometimes reverse a partial -expansion. For example, the first step in expanding @expr{(x+1)^3} is -to write @expr{(x+1) (x+1)^2}. If @kbd{a x} stops there and tries -to put this formula onto the stack, though, Calc will automatically -simplify it back to @expr{(x+1)^3} form. The solution is to turn -simplification off first (@pxref{Simplification Modes}), or to run -@kbd{a x} without a numeric prefix argument so that it expands all -the way in one step. - -@kindex a a -@pindex calc-apart -@tindex apart -The @kbd{a a} (@code{calc-apart}) [@code{apart}] command expands a -rational function by partial fractions. A rational function is the -quotient of two polynomials; @code{apart} pulls this apart into a -sum of rational functions with simple denominators. In algebraic -notation, the @code{apart} function allows a second argument that -specifies which variable to use as the ``base''; by default, Calc -chooses the base variable automatically. - -@kindex a n -@pindex calc-normalize-rat -@tindex nrat -The @kbd{a n} (@code{calc-normalize-rat}) [@code{nrat}] command -attempts to arrange a formula into a quotient of two polynomials. -For example, given @expr{1 + (a + b/c) / d}, the result would be -@expr{(b + a c + c d) / c d}. The quotient is reduced, so that -@kbd{a n} will simplify @expr{(x^2 + 2x + 1) / (x^2 - 1)} by dividing -out the common factor @expr{x + 1}, yielding @expr{(x + 1) / (x - 1)}. - -@kindex a \ -@pindex calc-poly-div -@tindex pdiv -The @kbd{a \} (@code{calc-poly-div}) [@code{pdiv}] command divides -two polynomials @expr{u} and @expr{v}, yielding a new polynomial -@expr{q}. If several variables occur in the inputs, the inputs are -considered multivariate polynomials. (Calc divides by the variable -with the largest power in @expr{u} first, or, in the case of equal -powers, chooses the variables in alphabetical order.) For example, -dividing @expr{x^2 + 3 x + 2} by @expr{x + 2} yields @expr{x + 1}. -The remainder from the division, if any, is reported at the bottom -of the screen and is also placed in the Trail along with the quotient. - -Using @code{pdiv} in algebraic notation, you can specify the particular -variable to be used as the base: @code{pdiv(@var{a},@var{b},@var{x})}. -If @code{pdiv} is given only two arguments (as is always the case with -the @kbd{a \} command), then it does a multivariate division as outlined -above. - -@kindex a % -@pindex calc-poly-rem -@tindex prem -The @kbd{a %} (@code{calc-poly-rem}) [@code{prem}] command divides -two polynomials and keeps the remainder @expr{r}. The quotient -@expr{q} is discarded. For any formulas @expr{a} and @expr{b}, the -results of @kbd{a \} and @kbd{a %} satisfy @expr{a = q b + r}. -(This is analogous to plain @kbd{\} and @kbd{%}, which compute the -integer quotient and remainder from dividing two numbers.) - -@kindex a / -@kindex H a / -@pindex calc-poly-div-rem -@tindex pdivrem -@tindex pdivide -The @kbd{a /} (@code{calc-poly-div-rem}) [@code{pdivrem}] command -divides two polynomials and reports both the quotient and the -remainder as a vector @expr{[q, r]}. The @kbd{H a /} [@code{pdivide}] -command divides two polynomials and constructs the formula -@expr{q + r/b} on the stack. (Naturally if the remainder is zero, -this will immediately simplify to @expr{q}.) - -@kindex a g -@pindex calc-poly-gcd -@tindex pgcd -The @kbd{a g} (@code{calc-poly-gcd}) [@code{pgcd}] command computes -the greatest common divisor of two polynomials. (The GCD actually -is unique only to within a constant multiplier; Calc attempts to -choose a GCD which will be unsurprising.) For example, the @kbd{a n} -command uses @kbd{a g} to take the GCD of the numerator and denominator -of a quotient, then divides each by the result using @kbd{a \}. (The -definition of GCD ensures that this division can take place without -leaving a remainder.) - -While the polynomials used in operations like @kbd{a /} and @kbd{a g} -often have integer coefficients, this is not required. Calc can also -deal with polynomials over the rationals or floating-point reals. -Polynomials with modulo-form coefficients are also useful in many -applications; if you enter @samp{(x^2 + 3 x - 1) mod 5}, Calc -automatically transforms this into a polynomial over the field of -integers mod 5: @samp{(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)}. - -Congratulations and thanks go to Ove Ewerlid -(@code{ewerlid@@mizar.DoCS.UU.SE}), who contributed many of the -polynomial routines used in the above commands. - -@xref{Decomposing Polynomials}, for several useful functions for -extracting the individual coefficients of a polynomial. - -@node Calculus, Solving Equations, Polynomials, Algebra -@section Calculus - -@noindent -The following calculus commands do not automatically simplify their -inputs or outputs using @code{calc-simplify}. You may find it helps -to do this by hand by typing @kbd{a s} or @kbd{a e}. It may also help -to use @kbd{a x} and/or @kbd{a c} to arrange a result in the most -readable way. - -@menu -* Differentiation:: -* Integration:: -* Customizing the Integrator:: -* Numerical Integration:: -* Taylor Series:: -@end menu - -@node Differentiation, Integration, Calculus, Calculus -@subsection Differentiation - -@noindent -@kindex a d -@kindex H a d -@pindex calc-derivative -@tindex deriv -@tindex tderiv -The @kbd{a d} (@code{calc-derivative}) [@code{deriv}] command computes -the derivative of the expression on the top of the stack with respect to -some variable, which it will prompt you to enter. Normally, variables -in the formula other than the specified differentiation variable are -considered constant, i.e., @samp{deriv(y,x)} is reduced to zero. With -the Hyperbolic flag, the @code{tderiv} (total derivative) operation is used -instead, in which derivatives of variables are not reduced to zero -unless those variables are known to be ``constant,'' i.e., independent -of any other variables. (The built-in special variables like @code{pi} -are considered constant, as are variables that have been declared -@code{const}; @pxref{Declarations}.) - -With a numeric prefix argument @var{n}, this command computes the -@var{n}th derivative. - -When working with trigonometric functions, it is best to switch to -Radians mode first (with @w{@kbd{m r}}). The derivative of @samp{sin(x)} -in degrees is @samp{(pi/180) cos(x)}, probably not the expected -answer! - -If you use the @code{deriv} function directly in an algebraic formula, -you can write @samp{deriv(f,x,x0)} which represents the derivative -of @expr{f} with respect to @expr{x}, evaluated at the point -@texline @math{x=x_0}. -@infoline @expr{x=x0}. - -If the formula being differentiated contains functions which Calc does -not know, the derivatives of those functions are produced by adding -primes (apostrophe characters). For example, @samp{deriv(f(2x), x)} -produces @samp{2 f'(2 x)}, where the function @code{f'} represents the -derivative of @code{f}. - -For functions you have defined with the @kbd{Z F} command, Calc expands -the functions according to their defining formulas unless you have -also defined @code{f'} suitably. For example, suppose we define -@samp{sinc(x) = sin(x)/x} using @kbd{Z F}. If we then differentiate -the formula @samp{sinc(2 x)}, the formula will be expanded to -@samp{sin(2 x) / (2 x)} and differentiated. However, if we also -define @samp{sinc'(x) = dsinc(x)}, say, then Calc will write the -result as @samp{2 dsinc(2 x)}. @xref{Algebraic Definitions}. - -For multi-argument functions @samp{f(x,y,z)}, the derivative with respect -to the first argument is written @samp{f'(x,y,z)}; derivatives with -respect to the other arguments are @samp{f'2(x,y,z)} and @samp{f'3(x,y,z)}. -Various higher-order derivatives can be formed in the obvious way, e.g., -@samp{f'@var{}'(x)} (the second derivative of @code{f}) or -@samp{f'@var{}'2'3(x,y,z)} (@code{f} differentiated with respect to each -argument once). - -@node Integration, Customizing the Integrator, Differentiation, Calculus -@subsection Integration - -@noindent -@kindex a i -@pindex calc-integral -@tindex integ -The @kbd{a i} (@code{calc-integral}) [@code{integ}] command computes the -indefinite integral of the expression on the top of the stack with -respect to a prompted-for variable. The integrator is not guaranteed to -work for all integrable functions, but it is able to integrate several -large classes of formulas. In particular, any polynomial or rational -function (a polynomial divided by a polynomial) is acceptable. -(Rational functions don't have to be in explicit quotient form, however; -@texline @math{x/(1+x^{-2})} -@infoline @expr{x/(1+x^-2)} -is not strictly a quotient of polynomials, but it is equivalent to -@expr{x^3/(x^2+1)}, which is.) Also, square roots of terms involving -@expr{x} and @expr{x^2} may appear in rational functions being -integrated. Finally, rational functions involving trigonometric or -hyperbolic functions can be integrated. - -With an argument (@kbd{C-u a i}), this command will compute the definite -integral of the expression on top of the stack. In this case, the -command will again prompt for an integration variable, then prompt for a -lower limit and an upper limit. - -@ifnottex -If you use the @code{integ} function directly in an algebraic formula, -you can also write @samp{integ(f,x,v)} which expresses the resulting -indefinite integral in terms of variable @code{v} instead of @code{x}. -With four arguments, @samp{integ(f(x),x,a,b)} represents a definite -integral from @code{a} to @code{b}. -@end ifnottex -@tex -If you use the @code{integ} function directly in an algebraic formula, -you can also write @samp{integ(f,x,v)} which expresses the resulting -indefinite integral in terms of variable @code{v} instead of @code{x}. -With four arguments, @samp{integ(f(x),x,a,b)} represents a definite -integral $\int_a^b f(x) \, dx$. -@end tex - -Please note that the current implementation of Calc's integrator sometimes -produces results that are significantly more complex than they need to -be. For example, the integral Calc finds for -@texline @math{1/(x+\sqrt{x^2+1})} -@infoline @expr{1/(x+sqrt(x^2+1))} -is several times more complicated than the answer Mathematica -returns for the same input, although the two forms are numerically -equivalent. Also, any indefinite integral should be considered to have -an arbitrary constant of integration added to it, although Calc does not -write an explicit constant of integration in its result. For example, -Calc's solution for -@texline @math{1/(1+\tan x)} -@infoline @expr{1/(1+tan(x))} -differs from the solution given in the @emph{CRC Math Tables} by a -constant factor of -@texline @math{\pi i / 2} -@infoline @expr{pi i / 2}, -due to a different choice of constant of integration. - -The Calculator remembers all the integrals it has done. If conditions -change in a way that would invalidate the old integrals, say, a switch -from Degrees to Radians mode, then they will be thrown out. If you -suspect this is not happening when it should, use the -@code{calc-flush-caches} command; @pxref{Caches}. - -@vindex IntegLimit -Calc normally will pursue integration by substitution or integration by -parts up to 3 nested times before abandoning an approach as fruitless. -If the integrator is taking too long, you can lower this limit by storing -a number (like 2) in the variable @code{IntegLimit}. (The @kbd{s I} -command is a convenient way to edit @code{IntegLimit}.) If this variable -has no stored value or does not contain a nonnegative integer, a limit -of 3 is used. The lower this limit is, the greater the chance that Calc -will be unable to integrate a function it could otherwise handle. Raising -this limit allows the Calculator to solve more integrals, though the time -it takes may grow exponentially. You can monitor the integrator's actions -by creating an Emacs buffer called @file{*Trace*}. If such a buffer -exists, the @kbd{a i} command will write a log of its actions there. - -If you want to manipulate integrals in a purely symbolic way, you can -set the integration nesting limit to 0 to prevent all but fast -table-lookup solutions of integrals. You might then wish to define -rewrite rules for integration by parts, various kinds of substitutions, -and so on. @xref{Rewrite Rules}. - -@node Customizing the Integrator, Numerical Integration, Integration, Calculus -@subsection Customizing the Integrator - -@noindent -@vindex IntegRules -Calc has two built-in rewrite rules called @code{IntegRules} and -@code{IntegAfterRules} which you can edit to define new integration -methods. @xref{Rewrite Rules}. At each step of the integration process, -Calc wraps the current integrand in a call to the fictitious function -@samp{integtry(@var{expr},@var{var})}, where @var{expr} is the -integrand and @var{var} is the integration variable. If your rules -rewrite this to be a plain formula (not a call to @code{integtry}), then -Calc will use this formula as the integral of @var{expr}. For example, -the rule @samp{integtry(mysin(x),x) := -mycos(x)} would define a rule to -integrate a function @code{mysin} that acts like the sine function. -Then, putting @samp{4 mysin(2y+1)} on the stack and typing @kbd{a i y} -will produce the integral @samp{-2 mycos(2y+1)}. Note that Calc has -automatically made various transformations on the integral to allow it -to use your rule; integral tables generally give rules for -@samp{mysin(a x + b)}, but you don't need to use this much generality -in your @code{IntegRules}. - -@cindex Exponential integral Ei(x) -@ignore -@starindex -@end ignore -@tindex Ei -As a more serious example, the expression @samp{exp(x)/x} cannot be -integrated in terms of the standard functions, so the ``exponential -integral'' function -@texline @math{{\rm Ei}(x)} -@infoline @expr{Ei(x)} -was invented to describe it. -We can get Calc to do this integral in terms of a made-up @code{Ei} -function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]} -to @code{IntegRules}. Now entering @samp{exp(2x)/x} on the stack -and typing @kbd{a i x} yields @samp{Ei(2 x)}. This new rule will -work with Calc's various built-in integration methods (such as -integration by substitution) to solve a variety of other problems -involving @code{Ei}: For example, now Calc will also be able to -integrate @samp{exp(exp(x))} and @samp{ln(ln(x))} (to get @samp{Ei(exp(x))} -and @samp{x ln(ln(x)) - Ei(ln(x))}, respectively). - -Your rule may do further integration by calling @code{integ}. For -example, @samp{integtry(twice(u),x) := twice(integ(u))} allows Calc -to integrate @samp{twice(sin(x))} to get @samp{twice(-cos(x))}. -Note that @code{integ} was called with only one argument. This notation -is allowed only within @code{IntegRules}; it means ``integrate this -with respect to the same integration variable.'' If Calc is unable -to integrate @code{u}, the integration that invoked @code{IntegRules} -also fails. Thus integrating @samp{twice(f(x))} fails, returning the -unevaluated integral @samp{integ(twice(f(x)), x)}. It is still valid -to call @code{integ} with two or more arguments, however; in this case, -if @code{u} is not integrable, @code{twice} itself will still be -integrated: If the above rule is changed to @samp{... := twice(integ(u,x))}, -then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}. - -If a rule instead produces the formula @samp{integsubst(@var{sexpr}, -@var{svar})}, either replacing the top-level @code{integtry} call or -nested anywhere inside the expression, then Calc will apply the -substitution @samp{@var{u} = @var{sexpr}(@var{svar})} to try to -integrate the original @var{expr}. For example, the rule -@samp{sqrt(a) := integsubst(sqrt(x),x)} says that if Calc ever finds -a square root in the integrand, it should attempt the substitution -@samp{u = sqrt(x)}. (This particular rule is unnecessary because -Calc always tries ``obvious'' substitutions where @var{sexpr} actually -appears in the integrand.) The variable @var{svar} may be the same -as the @var{var} that appeared in the call to @code{integtry}, but -it need not be. - -When integrating according to an @code{integsubst}, Calc uses the -equation solver to find the inverse of @var{sexpr} (if the integrand -refers to @var{var} anywhere except in subexpressions that exactly -match @var{sexpr}). It uses the differentiator to find the derivative -of @var{sexpr} and/or its inverse (it has two methods that use one -derivative or the other). You can also specify these items by adding -extra arguments to the @code{integsubst} your rules construct; the -general form is @samp{integsubst(@var{sexpr}, @var{svar}, @var{sinv}, -@var{sprime})}, where @var{sinv} is the inverse of @var{sexpr} (still -written as a function of @var{svar}), and @var{sprime} is the -derivative of @var{sexpr} with respect to @var{svar}. If you don't -specify these things, and Calc is not able to work them out on its -own with the information it knows, then your substitution rule will -work only in very specific, simple cases. - -Calc applies @code{IntegRules} as if by @kbd{C-u 1 a r IntegRules}; -in other words, Calc stops rewriting as soon as any rule in your rule -set succeeds. (If it weren't for this, the @samp{integsubst(sqrt(x),x)} -example above would keep on adding layers of @code{integsubst} calls -forever!) - -@vindex IntegSimpRules -Another set of rules, stored in @code{IntegSimpRules}, are applied -every time the integrator uses algebraic simplifications to simplify an -intermediate result. For example, putting the rule -@samp{twice(x) := 2 x} into @code{IntegSimpRules} would tell Calc to -convert the @code{twice} function into a form it knows whenever -integration is attempted. - -One more way to influence the integrator is to define a function with -the @kbd{Z F} command (@pxref{Algebraic Definitions}). Calc's -integrator automatically expands such functions according to their -defining formulas, even if you originally asked for the function to -be left unevaluated for symbolic arguments. (Certain other Calc -systems, such as the differentiator and the equation solver, also -do this.) - -@vindex IntegAfterRules -Sometimes Calc is able to find a solution to your integral, but it -expresses the result in a way that is unnecessarily complicated. If -this happens, you can either use @code{integsubst} as described -above to try to hint at a more direct path to the desired result, or -you can use @code{IntegAfterRules}. This is an extra rule set that -runs after the main integrator returns its result; basically, Calc does -an @kbd{a r IntegAfterRules} on the result before showing it to you. -(It also does algebraic simplifications, without @code{IntegSimpRules}, -after that to further simplify the result.) For example, Calc's integrator -sometimes produces expressions of the form @samp{ln(1+x) - ln(1-x)}; -the default @code{IntegAfterRules} rewrite this into the more readable -form @samp{2 arctanh(x)}. Note that, unlike @code{IntegRules}, -@code{IntegSimpRules} and @code{IntegAfterRules} are applied any number -of times until no further changes are possible. Rewriting by -@code{IntegAfterRules} occurs only after the main integrator has -finished, not at every step as for @code{IntegRules} and -@code{IntegSimpRules}. - -@node Numerical Integration, Taylor Series, Customizing the Integrator, Calculus -@subsection Numerical Integration - -@noindent -@kindex a I -@pindex calc-num-integral -@tindex ninteg -If you want a purely numerical answer to an integration problem, you can -use the @kbd{a I} (@code{calc-num-integral}) [@code{ninteg}] command. This -command prompts for an integration variable, a lower limit, and an -upper limit. Except for the integration variable, all other variables -that appear in the integrand formula must have stored values. (A stored -value, if any, for the integration variable itself is ignored.) - -Numerical integration works by evaluating your formula at many points in -the specified interval. Calc uses an ``open Romberg'' method; this means -that it does not evaluate the formula actually at the endpoints (so that -it is safe to integrate @samp{sin(x)/x} from zero, for example). Also, -the Romberg method works especially well when the function being -integrated is fairly smooth. If the function is not smooth, Calc will -have to evaluate it at quite a few points before it can accurately -determine the value of the integral. - -Integration is much faster when the current precision is small. It is -best to set the precision to the smallest acceptable number of digits -before you use @kbd{a I}. If Calc appears to be taking too long, press -@kbd{C-g} to halt it and try a lower precision. If Calc still appears -to need hundreds of evaluations, check to make sure your function is -well-behaved in the specified interval. - -It is possible for the lower integration limit to be @samp{-inf} (minus -infinity). Likewise, the upper limit may be plus infinity. Calc -internally transforms the integral into an equivalent one with finite -limits. However, integration to or across singularities is not supported: -The integral of @samp{1/sqrt(x)} from 0 to 1 exists (it can be found -by Calc's symbolic integrator, for example), but @kbd{a I} will fail -because the integrand goes to infinity at one of the endpoints. - -@node Taylor Series, , Numerical Integration, Calculus -@subsection Taylor Series - -@noindent -@kindex a t -@pindex calc-taylor -@tindex taylor -The @kbd{a t} (@code{calc-taylor}) [@code{taylor}] command computes a -power series expansion or Taylor series of a function. You specify the -variable and the desired number of terms. You may give an expression of -the form @samp{@var{var} = @var{a}} or @samp{@var{var} - @var{a}} instead -of just a variable to produce a Taylor expansion about the point @var{a}. -You may specify the number of terms with a numeric prefix argument; -otherwise the command will prompt you for the number of terms. Note that -many series expansions have coefficients of zero for some terms, so you -may appear to get fewer terms than you asked for. - -If the @kbd{a i} command is unable to find a symbolic integral for a -function, you can get an approximation by integrating the function's -Taylor series. - -@node Solving Equations, Numerical Solutions, Calculus, Algebra -@section Solving Equations - -@noindent -@kindex a S -@pindex calc-solve-for -@tindex solve -@cindex Equations, solving -@cindex Solving equations -The @kbd{a S} (@code{calc-solve-for}) [@code{solve}] command rearranges -an equation to solve for a specific variable. An equation is an -expression of the form @expr{L = R}. For example, the command @kbd{a S x} -will rearrange @expr{y = 3x + 6} to the form, @expr{x = y/3 - 2}. If the -input is not an equation, it is treated like an equation of the -form @expr{X = 0}. - -This command also works for inequalities, as in @expr{y < 3x + 6}. -Some inequalities cannot be solved where the analogous equation could -be; for example, solving -@texline @math{a < b \, c} -@infoline @expr{a < b c} -for @expr{b} is impossible -without knowing the sign of @expr{c}. In this case, @kbd{a S} will -produce the result -@texline @math{b \mathbin{\hbox{\code{!=}}} a/c} -@infoline @expr{b != a/c} -(using the not-equal-to operator) to signify that the direction of the -inequality is now unknown. The inequality -@texline @math{a \le b \, c} -@infoline @expr{a <= b c} -is not even partially solved. @xref{Declarations}, for a way to tell -Calc that the signs of the variables in a formula are in fact known. - -Two useful commands for working with the result of @kbd{a S} are -@kbd{a .} (@pxref{Logical Operations}), which converts @expr{x = y/3 - 2} -to @expr{y/3 - 2}, and @kbd{s l} (@pxref{Let Command}) which evaluates -another formula with @expr{x} set equal to @expr{y/3 - 2}. - -@menu -* Multiple Solutions:: -* Solving Systems of Equations:: -* Decomposing Polynomials:: -@end menu - -@node Multiple Solutions, Solving Systems of Equations, Solving Equations, Solving Equations -@subsection Multiple Solutions - -@noindent -@kindex H a S -@tindex fsolve -Some equations have more than one solution. The Hyperbolic flag -(@code{H a S}) [@code{fsolve}] tells the solver to report the fully -general family of solutions. It will invent variables @code{n1}, -@code{n2}, @dots{}, which represent independent arbitrary integers, and -@code{s1}, @code{s2}, @dots{}, which represent independent arbitrary -signs (either @mathit{+1} or @mathit{-1}). If you don't use the Hyperbolic -flag, Calc will use zero in place of all arbitrary integers, and plus -one in place of all arbitrary signs. Note that variables like @code{n1} -and @code{s1} are not given any special interpretation in Calc except by -the equation solver itself. As usual, you can use the @w{@kbd{s l}} -(@code{calc-let}) command to obtain solutions for various actual values -of these variables. - -For example, @kbd{' x^2 = y @key{RET} H a S x @key{RET}} solves to -get @samp{x = s1 sqrt(y)}, indicating that the two solutions to the -equation are @samp{sqrt(y)} and @samp{-sqrt(y)}. Another way to -think about it is that the square-root operation is really a -two-valued function; since every Calc function must return a -single result, @code{sqrt} chooses to return the positive result. -Then @kbd{H a S} doctors this result using @code{s1} to indicate -the full set of possible values of the mathematical square-root. - -There is a similar phenomenon going the other direction: Suppose -we solve @samp{sqrt(y) = x} for @code{y}. Calc squares both sides -to get @samp{y = x^2}. This is correct, except that it introduces -some dubious solutions. Consider solving @samp{sqrt(y) = -3}: -Calc will report @expr{y = 9} as a valid solution, which is true -in the mathematical sense of square-root, but false (there is no -solution) for the actual Calc positive-valued @code{sqrt}. This -happens for both @kbd{a S} and @kbd{H a S}. - -@cindex @code{GenCount} variable -@vindex GenCount -@ignore -@starindex -@end ignore -@tindex an -@ignore -@starindex -@end ignore -@tindex as -If you store a positive integer in the Calc variable @code{GenCount}, -then Calc will generate formulas of the form @samp{as(@var{n})} for -arbitrary signs, and @samp{an(@var{n})} for arbitrary integers, -where @var{n} represents successive values taken by incrementing -@code{GenCount} by one. While the normal arbitrary sign and -integer symbols start over at @code{s1} and @code{n1} with each -new Calc command, the @code{GenCount} approach will give each -arbitrary value a name that is unique throughout the entire Calc -session. Also, the arbitrary values are function calls instead -of variables, which is advantageous in some cases. For example, -you can make a rewrite rule that recognizes all arbitrary signs -using a pattern like @samp{as(n)}. The @kbd{s l} command only works -on variables, but you can use the @kbd{a b} (@code{calc-substitute}) -command to substitute actual values for function calls like @samp{as(3)}. - -The @kbd{s G} (@code{calc-edit-GenCount}) command is a convenient -way to create or edit this variable. Press @kbd{C-c C-c} to finish. - -If you have not stored a value in @code{GenCount}, or if the value -in that variable is not a positive integer, the regular -@code{s1}/@code{n1} notation is used. - -@kindex I a S -@kindex H I a S -@tindex finv -@tindex ffinv -With the Inverse flag, @kbd{I a S} [@code{finv}] treats the expression -on top of the stack as a function of the specified variable and solves -to find the inverse function, written in terms of the same variable. -For example, @kbd{I a S x} inverts @expr{2x + 6} to @expr{x/2 - 3}. -You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a -fully general inverse, as described above. - -@kindex a P -@pindex calc-poly-roots -@tindex roots -Some equations, specifically polynomials, have a known, finite number -of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}] -command uses @kbd{H a S} to solve an equation in general form, then, for -all arbitrary-sign variables like @code{s1}, and all arbitrary-integer -variables like @code{n1} for which @code{n1} only usefully varies over -a finite range, it expands these variables out to all their possible -values. The results are collected into a vector, which is returned. -For example, @samp{roots(x^4 = 1, x)} returns the four solutions -@samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree -polynomial will always have @var{n} roots on the complex plane. -(If you have given a @code{real} declaration for the solution -variable, then only the real-valued solutions, if any, will be -reported; @pxref{Declarations}.) - -Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver -symbolic solutions if the polynomial has symbolic coefficients. Also -note that Calc's solver is not able to get exact symbolic solutions -to all polynomials. Polynomials containing powers up to @expr{x^4} -can always be solved exactly; polynomials of higher degree sometimes -can be: @expr{x^6 + x^3 + 1} is converted to @expr{(x^3)^2 + (x^3) + 1}, -which can be solved for @expr{x^3} using the quadratic equation, and then -for @expr{x} by taking cube roots. But in many cases, like -@expr{x^6 + x + 1}, Calc does not know how to rewrite the polynomial -into a form it can solve. The @kbd{a P} command can still deliver a -list of numerical roots, however, provided that Symbolic mode (@kbd{m s}) -is not turned on. (If you work with Symbolic mode on, recall that the -@kbd{N} (@code{calc-eval-num}) key is a handy way to reevaluate the -formula on the stack with Symbolic mode temporarily off.) Naturally, -@kbd{a P} can only provide numerical roots if the polynomial coefficients -are all numbers (real or complex). - -@node Solving Systems of Equations, Decomposing Polynomials, Multiple Solutions, Solving Equations -@subsection Solving Systems of Equations - -@noindent -@cindex Systems of equations, symbolic -You can also use the commands described above to solve systems of -simultaneous equations. Just create a vector of equations, then -specify a vector of variables for which to solve. (You can omit -the surrounding brackets when entering the vector of variables -at the prompt.) - -For example, putting @samp{[x + y = a, x - y = b]} on the stack -and typing @kbd{a S x,y @key{RET}} produces the vector of solutions -@samp{[x = a - (a-b)/2, y = (a-b)/2]}. The result vector will -have the same length as the variables vector, and the variables -will be listed in the same order there. Note that the solutions -are not always simplified as far as possible; the solution for -@expr{x} here could be improved by an application of the @kbd{a n} -command. - -Calc's algorithm works by trying to eliminate one variable at a -time by solving one of the equations for that variable and then -substituting into the other equations. Calc will try all the -possibilities, but you can speed things up by noting that Calc -first tries to eliminate the first variable with the first -equation, then the second variable with the second equation, -and so on. It also helps to put the simpler (e.g., more linear) -equations toward the front of the list. Calc's algorithm will -solve any system of linear equations, and also many kinds of -nonlinear systems. - -@ignore -@starindex -@end ignore -@tindex elim -Normally there will be as many variables as equations. If you -give fewer variables than equations (an ``over-determined'' system -of equations), Calc will find a partial solution. For example, -typing @kbd{a S y @key{RET}} with the above system of equations -would produce @samp{[y = a - x]}. There are now several ways to -express this solution in terms of the original variables; Calc uses -the first one that it finds. You can control the choice by adding -variable specifiers of the form @samp{elim(@var{v})} to the -variables list. This says that @var{v} should be eliminated from -the equations; the variable will not appear at all in the solution. -For example, typing @kbd{a S y,elim(x)} would yield -@samp{[y = a - (b+a)/2]}. - -If the variables list contains only @code{elim} specifiers, -Calc simply eliminates those variables from the equations -and then returns the resulting set of equations. For example, -@kbd{a S elim(x)} produces @samp{[a - 2 y = b]}. Every variable -eliminated will reduce the number of equations in the system -by one. - -Again, @kbd{a S} gives you one solution to the system of -equations. If there are several solutions, you can use @kbd{H a S} -to get a general family of solutions, or, if there is a finite -number of solutions, you can use @kbd{a P} to get a list. (In -the latter case, the result will take the form of a matrix where -the rows are different solutions and the columns correspond to the -variables you requested.) - -Another way to deal with certain kinds of overdetermined systems of -equations is the @kbd{a F} command, which does least-squares fitting -to satisfy the equations. @xref{Curve Fitting}. - -@node Decomposing Polynomials, , Solving Systems of Equations, Solving Equations -@subsection Decomposing Polynomials - -@noindent -@ignore -@starindex -@end ignore -@tindex poly -The @code{poly} function takes a polynomial and a variable as -arguments, and returns a vector of polynomial coefficients (constant -coefficient first). For example, @samp{poly(x^3 + 2 x, x)} returns -@expr{[0, 2, 0, 1]}. If the input is not a polynomial in @expr{x}, -the call to @code{poly} is left in symbolic form. If the input does -not involve the variable @expr{x}, the input is returned in a list -of length one, representing a polynomial with only a constant -coefficient. The call @samp{poly(x, x)} returns the vector @expr{[0, 1]}. -The last element of the returned vector is guaranteed to be nonzero; -note that @samp{poly(0, x)} returns the empty vector @expr{[]}. -Note also that @expr{x} may actually be any formula; for example, -@samp{poly(sin(x)^2 - sin(x) + 3, sin(x))} returns @expr{[3, -1, 1]}. - -@cindex Coefficients of polynomial -@cindex Degree of polynomial -To get the @expr{x^k} coefficient of polynomial @expr{p}, use -@samp{poly(p, x)_(k+1)}. To get the degree of polynomial @expr{p}, -use @samp{vlen(poly(p, x)) - 1}. For example, @samp{poly((x+1)^4, x)} -returns @samp{[1, 4, 6, 4, 1]}, so @samp{poly((x+1)^4, x)_(2+1)} -gives the @expr{x^2} coefficient of this polynomial, 6. - -@ignore -@starindex -@end ignore -@tindex gpoly -One important feature of the solver is its ability to recognize -formulas which are ``essentially'' polynomials. This ability is -made available to the user through the @code{gpoly} function, which -is used just like @code{poly}: @samp{gpoly(@var{expr}, @var{var})}. -If @var{expr} is a polynomial in some term which includes @var{var}, then -this function will return a vector @samp{[@var{x}, @var{c}, @var{a}]} -where @var{x} is the term that depends on @var{var}, @var{c} is a -vector of polynomial coefficients (like the one returned by @code{poly}), -and @var{a} is a multiplier which is usually 1. Basically, -@samp{@var{expr} = @var{a}*(@var{c}_1 + @var{c}_2 @var{x} + -@var{c}_3 @var{x}^2 + ...)}. The last element of @var{c} is -guaranteed to be non-zero, and @var{c} will not equal @samp{[1]} -(i.e., the trivial decomposition @var{expr} = @var{x} is not -considered a polynomial). One side effect is that @samp{gpoly(x, x)} -and @samp{gpoly(6, x)}, both of which might be expected to recognize -their arguments as polynomials, will not because the decomposition -is considered trivial. - -For example, @samp{gpoly((x-2)^2, x)} returns @samp{[x, [4, -4, 1], 1]}, -since the expanded form of this polynomial is @expr{4 - 4 x + x^2}. - -The term @var{x} may itself be a polynomial in @var{var}. This is -done to reduce the size of the @var{c} vector. For example, -@samp{gpoly(x^4 + x^2 - 1, x)} returns @samp{[x^2, [-1, 1, 1], 1]}, -since a quadratic polynomial in @expr{x^2} is easier to solve than -a quartic polynomial in @expr{x}. - -A few more examples of the kinds of polynomials @code{gpoly} can -discover: - -@smallexample -sin(x) - 1 [sin(x), [-1, 1], 1] -x + 1/x - 1 [x, [1, -1, 1], 1/x] -x + 1/x [x^2, [1, 1], 1/x] -x^3 + 2 x [x^2, [2, 1], x] -x + x^2:3 + sqrt(x) [x^1:6, [1, 1, 0, 1], x^1:2] -x^(2a) + 2 x^a + 5 [x^a, [5, 2, 1], 1] -(exp(-x) + exp(x)) / 2 [e^(2 x), [0.5, 0.5], e^-x] -@end smallexample - -The @code{poly} and @code{gpoly} functions accept a third integer argument -which specifies the largest degree of polynomial that is acceptable. -If this is @expr{n}, then only @var{c} vectors of length @expr{n+1} -or less will be returned. Otherwise, the @code{poly} or @code{gpoly} -call will remain in symbolic form. For example, the equation solver -can handle quartics and smaller polynomials, so it calls -@samp{gpoly(@var{expr}, @var{var}, 4)} to discover whether @var{expr} -can be treated by its linear, quadratic, cubic, or quartic formulas. - -@ignore -@starindex -@end ignore -@tindex pdeg -The @code{pdeg} function computes the degree of a polynomial; -@samp{pdeg(p,x)} is the highest power of @code{x} that appears in -@code{p}. This is the same as @samp{vlen(poly(p,x))-1}, but is -much more efficient. If @code{p} is constant with respect to @code{x}, -then @samp{pdeg(p,x) = 0}. If @code{p} is not a polynomial in @code{x} -(e.g., @samp{pdeg(2 cos(x), x)}, the function remains unevaluated. -It is possible to omit the second argument @code{x}, in which case -@samp{pdeg(p)} returns the highest total degree of any term of the -polynomial, counting all variables that appear in @code{p}. Note -that @code{pdeg(c) = pdeg(c,x) = 0} for any nonzero constant @code{c}; -the degree of the constant zero is considered to be @code{-inf} -(minus infinity). - -@ignore -@starindex -@end ignore -@tindex plead -The @code{plead} function finds the leading term of a polynomial. -Thus @samp{plead(p,x)} is equivalent to @samp{poly(p,x)_vlen(poly(p,x))}, -though again more efficient. In particular, @samp{plead((2x+1)^10, x)} -returns 1024 without expanding out the list of coefficients. The -value of @code{plead(p,x)} will be zero only if @expr{p = 0}. - -@ignore -@starindex -@end ignore -@tindex pcont -The @code{pcont} function finds the @dfn{content} of a polynomial. This -is the greatest common divisor of all the coefficients of the polynomial. -With two arguments, @code{pcont(p,x)} effectively uses @samp{poly(p,x)} -to get a list of coefficients, then uses @code{pgcd} (the polynomial -GCD function) to combine these into an answer. For example, -@samp{pcont(4 x y^2 + 6 x^2 y, x)} is @samp{2 y}. The content is -basically the ``biggest'' polynomial that can be divided into @code{p} -exactly. The sign of the content is the same as the sign of the leading -coefficient. - -With only one argument, @samp{pcont(p)} computes the numerical -content of the polynomial, i.e., the @code{gcd} of the numerical -coefficients of all the terms in the formula. Note that @code{gcd} -is defined on rational numbers as well as integers; it computes -the @code{gcd} of the numerators and the @code{lcm} of the -denominators. Thus @samp{pcont(4:3 x y^2 + 6 x^2 y)} returns 2:3. -Dividing the polynomial by this number will clear all the -denominators, as well as dividing by any common content in the -numerators. The numerical content of a polynomial is negative only -if all the coefficients in the polynomial are negative. - -@ignore -@starindex -@end ignore -@tindex pprim -The @code{pprim} function finds the @dfn{primitive part} of a -polynomial, which is simply the polynomial divided (using @code{pdiv} -if necessary) by its content. If the input polynomial has rational -coefficients, the result will have integer coefficients in simplest -terms. - -@node Numerical Solutions, Curve Fitting, Solving Equations, Algebra -@section Numerical Solutions - -@noindent -Not all equations can be solved symbolically. The commands in this -section use numerical algorithms that can find a solution to a specific -instance of an equation to any desired accuracy. Note that the -numerical commands are slower than their algebraic cousins; it is a -good idea to try @kbd{a S} before resorting to these commands. - -(@xref{Curve Fitting}, for some other, more specialized, operations -on numerical data.) - -@menu -* Root Finding:: -* Minimization:: -* Numerical Systems of Equations:: -@end menu - -@node Root Finding, Minimization, Numerical Solutions, Numerical Solutions -@subsection Root Finding - -@noindent -@kindex a R -@pindex calc-find-root -@tindex root -@cindex Newton's method -@cindex Roots of equations -@cindex Numerical root-finding -The @kbd{a R} (@code{calc-find-root}) [@code{root}] command finds a -numerical solution (or @dfn{root}) of an equation. (This command treats -inequalities the same as equations. If the input is any other kind -of formula, it is interpreted as an equation of the form @expr{X = 0}.) - -The @kbd{a R} command requires an initial guess on the top of the -stack, and a formula in the second-to-top position. It prompts for a -solution variable, which must appear in the formula. All other variables -that appear in the formula must have assigned values, i.e., when -a value is assigned to the solution variable and the formula is -evaluated with @kbd{=}, it should evaluate to a number. Any assigned -value for the solution variable itself is ignored and unaffected by -this command. - -When the command completes, the initial guess is replaced on the stack -by a vector of two numbers: The value of the solution variable that -solves the equation, and the difference between the lefthand and -righthand sides of the equation at that value. Ordinarily, the second -number will be zero or very nearly zero. (Note that Calc uses a -slightly higher precision while finding the root, and thus the second -number may be slightly different from the value you would compute from -the equation yourself.) - -The @kbd{v h} (@code{calc-head}) command is a handy way to extract -the first element of the result vector, discarding the error term. - -The initial guess can be a real number, in which case Calc searches -for a real solution near that number, or a complex number, in which -case Calc searches the whole complex plane near that number for a -solution, or it can be an interval form which restricts the search -to real numbers inside that interval. - -Calc tries to use @kbd{a d} to take the derivative of the equation. -If this succeeds, it uses Newton's method. If the equation is not -differentiable Calc uses a bisection method. (If Newton's method -appears to be going astray, Calc switches over to bisection if it -can, or otherwise gives up. In this case it may help to try again -with a slightly different initial guess.) If the initial guess is a -complex number, the function must be differentiable. - -If the formula (or the difference between the sides of an equation) -is negative at one end of the interval you specify and positive at -the other end, the root finder is guaranteed to find a root. -Otherwise, Calc subdivides the interval into small parts looking for -positive and negative values to bracket the root. When your guess is -an interval, Calc will not look outside that interval for a root. - -@kindex H a R -@tindex wroot -The @kbd{H a R} [@code{wroot}] command is similar to @kbd{a R}, except -that if the initial guess is an interval for which the function has -the same sign at both ends, then rather than subdividing the interval -Calc attempts to widen it to enclose a root. Use this mode if -you are not sure if the function has a root in your interval. - -If the function is not differentiable, and you give a simple number -instead of an interval as your initial guess, Calc uses this widening -process even if you did not type the Hyperbolic flag. (If the function -@emph{is} differentiable, Calc uses Newton's method which does not -require a bounding interval in order to work.) - -If Calc leaves the @code{root} or @code{wroot} function in symbolic -form on the stack, it will normally display an explanation for why -no root was found. If you miss this explanation, press @kbd{w} -(@code{calc-why}) to get it back. - -@node Minimization, Numerical Systems of Equations, Root Finding, Numerical Solutions -@subsection Minimization - -@noindent -@kindex a N -@kindex H a N -@kindex a X -@kindex H a X -@pindex calc-find-minimum -@pindex calc-find-maximum -@tindex minimize -@tindex maximize -@cindex Minimization, numerical -The @kbd{a N} (@code{calc-find-minimum}) [@code{minimize}] command -finds a minimum value for a formula. It is very similar in operation -to @kbd{a R} (@code{calc-find-root}): You give the formula and an initial -guess on the stack, and are prompted for the name of a variable. The guess -may be either a number near the desired minimum, or an interval enclosing -the desired minimum. The function returns a vector containing the -value of the variable which minimizes the formula's value, along -with the minimum value itself. - -Note that this command looks for a @emph{local} minimum. Many functions -have more than one minimum; some, like -@texline @math{x \sin x}, -@infoline @expr{x sin(x)}, -have infinitely many. In fact, there is no easy way to define the -``global'' minimum of -@texline @math{x \sin x} -@infoline @expr{x sin(x)} -but Calc can still locate any particular local minimum -for you. Calc basically goes downhill from the initial guess until it -finds a point at which the function's value is greater both to the left -and to the right. Calc does not use derivatives when minimizing a function. - -If your initial guess is an interval and it looks like the minimum -occurs at one or the other endpoint of the interval, Calc will return -that endpoint only if that endpoint is closed; thus, minimizing @expr{17 x} -over @expr{[2..3]} will return @expr{[2, 38]}, but minimizing over -@expr{(2..3]} would report no minimum found. In general, you should -use closed intervals to find literally the minimum value in that -range of @expr{x}, or open intervals to find the local minimum, if -any, that happens to lie in that range. - -Most functions are smooth and flat near their minimum values. Because -of this flatness, if the current precision is, say, 12 digits, the -variable can only be determined meaningfully to about six digits. Thus -you should set the precision to twice as many digits as you need in your -answer. - -@ignore -@mindex wmin@idots -@end ignore -@tindex wminimize -@ignore -@mindex wmax@idots -@end ignore -@tindex wmaximize -The @kbd{H a N} [@code{wminimize}] command, analogously to @kbd{H a R}, -expands the guess interval to enclose a minimum rather than requiring -that the minimum lie inside the interval you supply. - -The @kbd{a X} (@code{calc-find-maximum}) [@code{maximize}] and -@kbd{H a X} [@code{wmaximize}] commands effectively minimize the -negative of the formula you supply. - -The formula must evaluate to a real number at all points inside the -interval (or near the initial guess if the guess is a number). If -the initial guess is a complex number the variable will be minimized -over the complex numbers; if it is real or an interval it will -be minimized over the reals. - -@node Numerical Systems of Equations, , Minimization, Numerical Solutions -@subsection Systems of Equations - -@noindent -@cindex Systems of equations, numerical -The @kbd{a R} command can also solve systems of equations. In this -case, the equation should instead be a vector of equations, the -guess should instead be a vector of numbers (intervals are not -supported), and the variable should be a vector of variables. You -can omit the brackets while entering the list of variables. Each -equation must be differentiable by each variable for this mode to -work. The result will be a vector of two vectors: The variable -values that solved the system of equations, and the differences -between the sides of the equations with those variable values. -There must be the same number of equations as variables. Since -only plain numbers are allowed as guesses, the Hyperbolic flag has -no effect when solving a system of equations. - -It is also possible to minimize over many variables with @kbd{a N} -(or maximize with @kbd{a X}). Once again the variable name should -be replaced by a vector of variables, and the initial guess should -be an equal-sized vector of initial guesses. But, unlike the case of -multidimensional @kbd{a R}, the formula being minimized should -still be a single formula, @emph{not} a vector. Beware that -multidimensional minimization is currently @emph{very} slow. - -@node Curve Fitting, Summations, Numerical Solutions, Algebra -@section Curve Fitting - -@noindent -The @kbd{a F} command fits a set of data to a @dfn{model formula}, -such as @expr{y = m x + b} where @expr{m} and @expr{b} are parameters -to be determined. For a typical set of measured data there will be -no single @expr{m} and @expr{b} that exactly fit the data; in this -case, Calc chooses values of the parameters that provide the closest -possible fit. The model formula can be entered in various ways after -the key sequence @kbd{a F} is pressed. - -If the letter @kbd{P} is pressed after @kbd{a F} but before the model -description is entered, the data as well as the model formula will be -plotted after the formula is determined. This will be indicated by a -``P'' in the minibuffer after the help message. - -@menu -* Linear Fits:: -* Polynomial and Multilinear Fits:: -* Error Estimates for Fits:: -* Standard Nonlinear Models:: -* Curve Fitting Details:: -* Interpolation:: -@end menu - -@node Linear Fits, Polynomial and Multilinear Fits, Curve Fitting, Curve Fitting -@subsection Linear Fits - -@noindent -@kindex a F -@pindex calc-curve-fit -@tindex fit -@cindex Linear regression -@cindex Least-squares fits -The @kbd{a F} (@code{calc-curve-fit}) [@code{fit}] command attempts -to fit a set of data (@expr{x} and @expr{y} vectors of numbers) to a -straight line, polynomial, or other function of @expr{x}. For the -moment we will consider only the case of fitting to a line, and we -will ignore the issue of whether or not the model was in fact a good -fit for the data. - -In a standard linear least-squares fit, we have a set of @expr{(x,y)} -data points that we wish to fit to the model @expr{y = m x + b} -by adjusting the parameters @expr{m} and @expr{b} to make the @expr{y} -values calculated from the formula be as close as possible to the actual -@expr{y} values in the data set. (In a polynomial fit, the model is -instead, say, @expr{y = a x^3 + b x^2 + c x + d}. In a multilinear fit, -we have data points of the form @expr{(x_1,x_2,x_3,y)} and our model is -@expr{y = a x_1 + b x_2 + c x_3 + d}. These will be discussed later.) - -In the model formula, variables like @expr{x} and @expr{x_2} are called -the @dfn{independent variables}, and @expr{y} is the @dfn{dependent -variable}. Variables like @expr{m}, @expr{a}, and @expr{b} are called -the @dfn{parameters} of the model. - -The @kbd{a F} command takes the data set to be fitted from the stack. -By default, it expects the data in the form of a matrix. For example, -for a linear or polynomial fit, this would be a -@texline @math{2\times N} -@infoline 2xN -matrix where the first row is a list of @expr{x} values and the second -row has the corresponding @expr{y} values. For the multilinear fit -shown above, the matrix would have four rows (@expr{x_1}, @expr{x_2}, -@expr{x_3}, and @expr{y}, respectively). - -If you happen to have an -@texline @math{N\times2} -@infoline Nx2 -matrix instead of a -@texline @math{2\times N} -@infoline 2xN -matrix, just press @kbd{v t} first to transpose the matrix. - -After you type @kbd{a F}, Calc prompts you to select a model. For a -linear fit, press the digit @kbd{1}. - -Calc then prompts for you to name the variables. By default it chooses -high letters like @expr{x} and @expr{y} for independent variables and -low letters like @expr{a} and @expr{b} for parameters. (The dependent -variable doesn't need a name.) The two kinds of variables are separated -by a semicolon. Since you generally care more about the names of the -independent variables than of the parameters, Calc also allows you to -name only those and let the parameters use default names. - -For example, suppose the data matrix - -@ifnottex -@example -@group -[ [ 1, 2, 3, 4, 5 ] - [ 5, 7, 9, 11, 13 ] ] -@end group -@end example -@end ifnottex -@tex -\beforedisplay -$$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr - 5 & 7 & 9 & 11 & 13 } -$$ -\afterdisplay -@end tex - -@noindent -is on the stack and we wish to do a simple linear fit. Type -@kbd{a F}, then @kbd{1} for the model, then @key{RET} to use -the default names. The result will be the formula @expr{3. + 2. x} -on the stack. Calc has created the model expression @kbd{a + b x}, -then found the optimal values of @expr{a} and @expr{b} to fit the -data. (In this case, it was able to find an exact fit.) Calc then -substituted those values for @expr{a} and @expr{b} in the model -formula. - -The @kbd{a F} command puts two entries in the trail. One is, as -always, a copy of the result that went to the stack; the other is -a vector of the actual parameter values, written as equations: -@expr{[a = 3, b = 2]}, in case you'd rather read them in a list -than pick them out of the formula. (You can type @kbd{t y} -to move this vector to the stack; see @ref{Trail Commands}. - -Specifying a different independent variable name will affect the -resulting formula: @kbd{a F 1 k @key{RET}} produces @kbd{3 + 2 k}. -Changing the parameter names (say, @kbd{a F 1 k;b,m @key{RET}}) will affect -the equations that go into the trail. - -@tex -\bigskip -@end tex - -To see what happens when the fit is not exact, we could change -the number 13 in the data matrix to 14 and try the fit again. -The result is: - -@example -2.6 + 2.2 x -@end example - -Evaluating this formula, say with @kbd{v x 5 @key{RET} @key{TAB} V M $ @key{RET}}, shows -a reasonably close match to the y-values in the data. - -@example -[4.8, 7., 9.2, 11.4, 13.6] -@end example - -Since there is no line which passes through all the @var{n} data points, -Calc has chosen a line that best approximates the data points using -the method of least squares. The idea is to define the @dfn{chi-square} -error measure - -@ifnottex -@example -chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$ -\afterdisplay -@end tex - -@noindent -which is clearly zero if @expr{a + b x} exactly fits all data points, -and increases as various @expr{a + b x_i} values fail to match the -corresponding @expr{y_i} values. There are several reasons why the -summand is squared, one of them being to ensure that -@texline @math{\chi^2 \ge 0}. -@infoline @expr{chi^2 >= 0}. -Least-squares fitting simply chooses the values of @expr{a} and @expr{b} -for which the error -@texline @math{\chi^2} -@infoline @expr{chi^2} -is as small as possible. - -Other kinds of models do the same thing but with a different model -formula in place of @expr{a + b x_i}. - -@tex -\bigskip -@end tex - -A numeric prefix argument causes the @kbd{a F} command to take the -data in some other form than one big matrix. A positive argument @var{n} -will take @var{N} items from the stack, corresponding to the @var{n} rows -of a data matrix. In the linear case, @var{n} must be 2 since there -is always one independent variable and one dependent variable. - -A prefix of zero or plain @kbd{C-u} is a compromise; Calc takes two -items from the stack, an @var{n}-row matrix of @expr{x} values, and a -vector of @expr{y} values. If there is only one independent variable, -the @expr{x} values can be either a one-row matrix or a plain vector, -in which case the @kbd{C-u} prefix is the same as a @w{@kbd{C-u 2}} prefix. - -@node Polynomial and Multilinear Fits, Error Estimates for Fits, Linear Fits, Curve Fitting -@subsection Polynomial and Multilinear Fits - -@noindent -To fit the data to higher-order polynomials, just type one of the -digits @kbd{2} through @kbd{9} when prompted for a model. For example, -we could fit the original data matrix from the previous section -(with 13, not 14) to a parabola instead of a line by typing -@kbd{a F 2 @key{RET}}. - -@example -2.00000000001 x - 1.5e-12 x^2 + 2.99999999999 -@end example - -Note that since the constant and linear terms are enough to fit the -data exactly, it's no surprise that Calc chose a tiny contribution -for @expr{x^2}. (The fact that it's not exactly zero is due only -to roundoff error. Since our data are exact integers, we could get -an exact answer by typing @kbd{m f} first to get Fraction mode. -Then the @expr{x^2} term would vanish altogether. Usually, though, -the data being fitted will be approximate floats so Fraction mode -won't help.) - -Doing the @kbd{a F 2} fit on the data set with 14 instead of 13 -gives a much larger @expr{x^2} contribution, as Calc bends the -line slightly to improve the fit. - -@example -0.142857142855 x^2 + 1.34285714287 x + 3.59999999998 -@end example - -An important result from the theory of polynomial fitting is that it -is always possible to fit @var{n} data points exactly using a polynomial -of degree @mathit{@var{n}-1}, sometimes called an @dfn{interpolating polynomial}. -Using the modified (14) data matrix, a model number of 4 gives -a polynomial that exactly matches all five data points: - -@example -0.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4. -@end example - -The actual coefficients we get with a precision of 12, like -@expr{0.0416666663588}, clearly suffer from loss of precision. -It is a good idea to increase the working precision to several -digits beyond what you need when you do a fitting operation. -Or, if your data are exact, use Fraction mode to get exact -results. - -You can type @kbd{i} instead of a digit at the model prompt to fit -the data exactly to a polynomial. This just counts the number of -columns of the data matrix to choose the degree of the polynomial -automatically. - -Fitting data ``exactly'' to high-degree polynomials is not always -a good idea, though. High-degree polynomials have a tendency to -wiggle uncontrollably in between the fitting data points. Also, -if the exact-fit polynomial is going to be used to interpolate or -extrapolate the data, it is numerically better to use the @kbd{a p} -command described below. @xref{Interpolation}. - -@tex -\bigskip -@end tex - -Another generalization of the linear model is to assume the -@expr{y} values are a sum of linear contributions from several -@expr{x} values. This is a @dfn{multilinear} fit, and it is also -selected by the @kbd{1} digit key. (Calc decides whether the fit -is linear or multilinear by counting the rows in the data matrix.) - -Given the data matrix, - -@example -@group -[ [ 1, 2, 3, 4, 5 ] - [ 7, 2, 3, 5, 2 ] - [ 14.5, 15, 18.5, 22.5, 24 ] ] -@end group -@end example - -@noindent -the command @kbd{a F 1 @key{RET}} will call the first row @expr{x} and the -second row @expr{y}, and will fit the values in the third row to the -model @expr{a + b x + c y}. - -@example -8. + 3. x + 0.5 y -@end example - -Calc can do multilinear fits with any number of independent variables -(i.e., with any number of data rows). - -@tex -\bigskip -@end tex - -Yet another variation is @dfn{homogeneous} linear models, in which -the constant term is known to be zero. In the linear case, this -means the model formula is simply @expr{a x}; in the multilinear -case, the model might be @expr{a x + b y + c z}; and in the polynomial -case, the model could be @expr{a x + b x^2 + c x^3}. You can get -a homogeneous linear or multilinear model by pressing the letter -@kbd{h} followed by a regular model key, like @kbd{1} or @kbd{2}. -This will be indicated by an ``h'' in the minibuffer after the help -message. - -It is certainly possible to have other constrained linear models, -like @expr{2.3 + a x} or @expr{a - 4 x}. While there is no single -key to select models like these, a later section shows how to enter -any desired model by hand. In the first case, for example, you -would enter @kbd{a F ' 2.3 + a x}. - -Another class of models that will work but must be entered by hand -are multinomial fits, e.g., @expr{a + b x + c y + d x^2 + e y^2 + f x y}. - -@node Error Estimates for Fits, Standard Nonlinear Models, Polynomial and Multilinear Fits, Curve Fitting -@subsection Error Estimates for Fits - -@noindent -@kindex H a F -@tindex efit -With the Hyperbolic flag, @kbd{H a F} [@code{efit}] performs the same -fitting operation as @kbd{a F}, but reports the coefficients as error -forms instead of plain numbers. Fitting our two data matrices (first -with 13, then with 14) to a line with @kbd{H a F} gives the results, - -@example -3. + 2. x -2.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x -@end example - -In the first case the estimated errors are zero because the linear -fit is perfect. In the second case, the errors are nonzero but -moderately small, because the data are still very close to linear. - -It is also possible for the @emph{input} to a fitting operation to -contain error forms. The data values must either all include errors -or all be plain numbers. Error forms can go anywhere but generally -go on the numbers in the last row of the data matrix. If the last -row contains error forms -@texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}', -@infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}', -then the -@texline @math{\chi^2} -@infoline @expr{chi^2} -statistic is now, - -@ifnottex -@example -chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \chi^2 = \sum_{i=1}^N \left(y_i - (a + b x_i) \over \sigma_i\right)^2 $$ -\afterdisplay -@end tex - -@noindent -so that data points with larger error estimates contribute less to -the fitting operation. - -If there are error forms on other rows of the data matrix, all the -errors for a given data point are combined; the square root of the -sum of the squares of the errors forms the -@texline @math{\sigma_i} -@infoline @expr{sigma_i} -used for the data point. - -Both @kbd{a F} and @kbd{H a F} can accept error forms in the input -matrix, although if you are concerned about error analysis you will -probably use @kbd{H a F} so that the output also contains error -estimates. - -If the input contains error forms but all the -@texline @math{\sigma_i} -@infoline @expr{sigma_i} -values are the same, it is easy to see that the resulting fitted model -will be the same as if the input did not have error forms at all -@texline (@math{\chi^2} -@infoline (@expr{chi^2} -is simply scaled uniformly by -@texline @math{1 / \sigma^2}, -@infoline @expr{1 / sigma^2}, -which doesn't affect where it has a minimum). But there @emph{will} be -a difference in the estimated errors of the coefficients reported by -@kbd{H a F}. - -Consult any text on statistical modeling of data for a discussion -of where these error estimates come from and how they should be -interpreted. - -@tex -\bigskip -@end tex - -@kindex I a F -@tindex xfit -With the Inverse flag, @kbd{I a F} [@code{xfit}] produces even more -information. The result is a vector of six items: - -@enumerate -@item -The model formula with error forms for its coefficients or -parameters. This is the result that @kbd{H a F} would have -produced. - -@item -A vector of ``raw'' parameter values for the model. These are the -polynomial coefficients or other parameters as plain numbers, in the -same order as the parameters appeared in the final prompt of the -@kbd{I a F} command. For polynomials of degree @expr{d}, this vector -will have length @expr{M = d+1} with the constant term first. - -@item -The covariance matrix @expr{C} computed from the fit. This is -an @var{m}x@var{m} symmetric matrix; the diagonal elements -@texline @math{C_{jj}} -@infoline @expr{C_j_j} -are the variances -@texline @math{\sigma_j^2} -@infoline @expr{sigma_j^2} -of the parameters. The other elements are covariances -@texline @math{\sigma_{ij}^2} -@infoline @expr{sigma_i_j^2} -that describe the correlation between pairs of parameters. (A related -set of numbers, the @dfn{linear correlation coefficients} -@texline @math{r_{ij}}, -@infoline @expr{r_i_j}, -are defined as -@texline @math{\sigma_{ij}^2 / \sigma_i \, \sigma_j}.) -@infoline @expr{sigma_i_j^2 / sigma_i sigma_j}.) - -@item -A vector of @expr{M} ``parameter filter'' functions whose -meanings are described below. If no filters are necessary this -will instead be an empty vector; this is always the case for the -polynomial and multilinear fits described so far. - -@item -The value of -@texline @math{\chi^2} -@infoline @expr{chi^2} -for the fit, calculated by the formulas shown above. This gives a -measure of the quality of the fit; statisticians consider -@texline @math{\chi^2 \approx N - M} -@infoline @expr{chi^2 = N - M} -to indicate a moderately good fit (where again @expr{N} is the number of -data points and @expr{M} is the number of parameters). - -@item -A measure of goodness of fit expressed as a probability @expr{Q}. -This is computed from the @code{utpc} probability distribution -function using -@texline @math{\chi^2} -@infoline @expr{chi^2} -with @expr{N - M} degrees of freedom. A -value of 0.5 implies a good fit; some texts recommend that often -@expr{Q = 0.1} or even 0.001 can signify an acceptable fit. In -particular, -@texline @math{\chi^2} -@infoline @expr{chi^2} -statistics assume the errors in your inputs -follow a normal (Gaussian) distribution; if they don't, you may -have to accept smaller values of @expr{Q}. - -The @expr{Q} value is computed only if the input included error -estimates. Otherwise, Calc will report the symbol @code{nan} -for @expr{Q}. The reason is that in this case the -@texline @math{\chi^2} -@infoline @expr{chi^2} -value has effectively been used to estimate the original errors -in the input, and thus there is no redundant information left -over to use for a confidence test. -@end enumerate - -@node Standard Nonlinear Models, Curve Fitting Details, Error Estimates for Fits, Curve Fitting -@subsection Standard Nonlinear Models - -@noindent -The @kbd{a F} command also accepts other kinds of models besides -lines and polynomials. Some common models have quick single-key -abbreviations; others must be entered by hand as algebraic formulas. - -Here is a complete list of the standard models recognized by @kbd{a F}: - -@table @kbd -@item 1 -Linear or multilinear. @mathit{a + b x + c y + d z}. -@item 2-9 -Polynomials. @mathit{a + b x + c x^2 + d x^3}. -@item e -Exponential. @mathit{a} @tfn{exp}@mathit{(b x)} @tfn{exp}@mathit{(c y)}. -@item E -Base-10 exponential. @mathit{a} @tfn{10^}@mathit{(b x)} @tfn{10^}@mathit{(c y)}. -@item x -Exponential (alternate notation). @tfn{exp}@mathit{(a + b x + c y)}. -@item X -Base-10 exponential (alternate). @tfn{10^}@mathit{(a + b x + c y)}. -@item l -Logarithmic. @mathit{a + b} @tfn{ln}@mathit{(x) + c} @tfn{ln}@mathit{(y)}. -@item L -Base-10 logarithmic. @mathit{a + b} @tfn{log10}@mathit{(x) + c} @tfn{log10}@mathit{(y)}. -@item ^ -General exponential. @mathit{a b^x c^y}. -@item p -Power law. @mathit{a x^b y^c}. -@item q -Quadratic. @mathit{a + b (x-c)^2 + d (x-e)^2}. -@item g -Gaussian. -@texline @math{{a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)}. -@infoline @mathit{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}. -@item s -Logistic @emph{s} curve. -@texline @math{a/(1+e^{b(x-c)})}. -@infoline @mathit{a/(1 + exp(b (x - c)))}. -@item b -Logistic bell curve. -@texline @math{ae^{b(x-c)}/(1+e^{b(x-c)})^2}. -@infoline @mathit{a exp(b (x - c))/(1 + exp(b (x - c)))^2}. -@item o -Hubbert linearization. -@texline @math{{y \over x} = a(1-x/b)}. -@infoline @mathit{(y/x) = a (1 - x/b)}. -@end table - -All of these models are used in the usual way; just press the appropriate -letter at the model prompt, and choose variable names if you wish. The -result will be a formula as shown in the above table, with the best-fit -values of the parameters substituted. (You may find it easier to read -the parameter values from the vector that is placed in the trail.) - -All models except Gaussian, logistics, Hubbert and polynomials can -generalize as shown to any number of independent variables. Also, all -the built-in models except for the logistic and Hubbert curves have an -additive or multiplicative parameter shown as @expr{a} in the above table -which can be replaced by zero or one, as appropriate, by typing @kbd{h} -before the model key. - -Note that many of these models are essentially equivalent, but express -the parameters slightly differently. For example, @expr{a b^x} and -the other two exponential models are all algebraic rearrangements of -each other. Also, the ``quadratic'' model is just a degree-2 polynomial -with the parameters expressed differently. Use whichever form best -matches the problem. - -The HP-28/48 calculators support four different models for curve -fitting, called @code{LIN}, @code{LOG}, @code{EXP}, and @code{PWR}. -These correspond to Calc models @samp{a + b x}, @samp{a + b ln(x)}, -@samp{a exp(b x)}, and @samp{a x^b}, respectively. In each case, -@expr{a} is what the HP-48 identifies as the ``intercept,'' and -@expr{b} is what it calls the ``slope.'' - -@tex -\bigskip -@end tex - -If the model you want doesn't appear on this list, press @kbd{'} -(the apostrophe key) at the model prompt to enter any algebraic -formula, such as @kbd{m x - b}, as the model. (Not all models -will work, though---see the next section for details.) - -The model can also be an equation like @expr{y = m x + b}. -In this case, Calc thinks of all the rows of the data matrix on -equal terms; this model effectively has two parameters -(@expr{m} and @expr{b}) and two independent variables (@expr{x} -and @expr{y}), with no ``dependent'' variables. Model equations -do not need to take this @expr{y =} form. For example, the -implicit line equation @expr{a x + b y = 1} works fine as a -model. - -When you enter a model, Calc makes an alphabetical list of all -the variables that appear in the model. These are used for the -default parameters, independent variables, and dependent variable -(in that order). If you enter a plain formula (not an equation), -Calc assumes the dependent variable does not appear in the formula -and thus does not need a name. - -For example, if the model formula has the variables @expr{a,mu,sigma,t,x}, -and the data matrix has three rows (meaning two independent variables), -Calc will use @expr{a,mu,sigma} as the default parameters, and the -data rows will be named @expr{t} and @expr{x}, respectively. If you -enter an equation instead of a plain formula, Calc will use @expr{a,mu} -as the parameters, and @expr{sigma,t,x} as the three independent -variables. - -You can, of course, override these choices by entering something -different at the prompt. If you leave some variables out of the list, -those variables must have stored values and those stored values will -be used as constants in the model. (Stored values for the parameters -and independent variables are ignored by the @kbd{a F} command.) -If you list only independent variables, all the remaining variables -in the model formula will become parameters. - -If there are @kbd{$} signs in the model you type, they will stand -for parameters and all other variables (in alphabetical order) -will be independent. Use @kbd{$} for one parameter, @kbd{$$} for -another, and so on. Thus @kbd{$ x + $$} is another way to describe -a linear model. - -If you type a @kbd{$} instead of @kbd{'} at the model prompt itself, -Calc will take the model formula from the stack. (The data must then -appear at the second stack level.) The same conventions are used to -choose which variables in the formula are independent by default and -which are parameters. - -Models taken from the stack can also be expressed as vectors of -two or three elements, @expr{[@var{model}, @var{vars}]} or -@expr{[@var{model}, @var{vars}, @var{params}]}. Each of @var{vars} -and @var{params} may be either a variable or a vector of variables. -(If @var{params} is omitted, all variables in @var{model} except -those listed as @var{vars} are parameters.) - -When you enter a model manually with @kbd{'}, Calc puts a 3-vector -describing the model in the trail so you can get it back if you wish. - -@tex -\bigskip -@end tex - -@vindex Model1 -@vindex Model2 -Finally, you can store a model in one of the Calc variables -@code{Model1} or @code{Model2}, then use this model by typing -@kbd{a F u} or @kbd{a F U} (respectively). The value stored in -the variable can be any of the formats that @kbd{a F $} would -accept for a model on the stack. - -@tex -\bigskip -@end tex - -Calc uses the principal values of inverse functions like @code{ln} -and @code{arcsin} when doing fits. For example, when you enter -the model @samp{y = sin(a t + b)} Calc actually uses the easier -form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always -returns results in the range from @mathit{-90} to 90 degrees (or the -equivalent range in radians). Suppose you had data that you -believed to represent roughly three oscillations of a sine wave, -so that the argument of the sine might go from zero to -@texline @math{3\times360} -@infoline @mathit{3*360} -degrees. -The above model would appear to be a good way to determine the -true frequency and phase of the sine wave, but in practice it -would fail utterly. The righthand side of the actual model -@samp{arcsin(y) = a t + b} will grow smoothly with @expr{t}, but -the lefthand side will bounce back and forth between @mathit{-90} and 90. -No values of @expr{a} and @expr{b} can make the two sides match, -even approximately. - -There is no good solution to this problem at present. You could -restrict your data to small enough ranges so that the above problem -doesn't occur (i.e., not straddling any peaks in the sine wave). -Or, in this case, you could use a totally different method such as -Fourier analysis, which is beyond the scope of the @kbd{a F} command. -(Unfortunately, Calc does not currently have any facilities for -taking Fourier and related transforms.) - -@node Curve Fitting Details, Interpolation, Standard Nonlinear Models, Curve Fitting -@subsection Curve Fitting Details - -@noindent -Calc's internal least-squares fitter can only handle multilinear -models. More precisely, it can handle any model of the form -@expr{a f(x,y,z) + b g(x,y,z) + c h(x,y,z)}, where @expr{a,b,c} -are the parameters and @expr{x,y,z} are the independent variables -(of course there can be any number of each, not just three). - -In a simple multilinear or polynomial fit, it is easy to see how -to convert the model into this form. For example, if the model -is @expr{a + b x + c x^2}, then @expr{f(x) = 1}, @expr{g(x) = x}, -and @expr{h(x) = x^2} are suitable functions. - -For most other models, Calc uses a variety of algebraic manipulations -to try to put the problem into the form - -@smallexample -Y(x,y,z) = A(a,b,c) F(x,y,z) + B(a,b,c) G(x,y,z) + C(a,b,c) H(x,y,z) -@end smallexample - -@noindent -where @expr{Y,A,B,C,F,G,H} are arbitrary functions. It computes -@expr{Y}, @expr{F}, @expr{G}, and @expr{H} for all the data points, -does a standard linear fit to find the values of @expr{A}, @expr{B}, -and @expr{C}, then uses the equation solver to solve for @expr{a,b,c} -in terms of @expr{A,B,C}. - -A remarkable number of models can be cast into this general form. -We'll look at two examples here to see how it works. The power-law -model @expr{y = a x^b} with two independent variables and two parameters -can be rewritten as follows: - -@example -y = a x^b -y = a exp(b ln(x)) -y = exp(ln(a) + b ln(x)) -ln(y) = ln(a) + b ln(x) -@end example - -@noindent -which matches the desired form with -@texline @math{Y = \ln(y)}, -@infoline @expr{Y = ln(y)}, -@texline @math{A = \ln(a)}, -@infoline @expr{A = ln(a)}, -@expr{F = 1}, @expr{B = b}, and -@texline @math{G = \ln(x)}. -@infoline @expr{G = ln(x)}. -Calc thus computes the logarithms of your @expr{y} and @expr{x} values, -does a linear fit for @expr{A} and @expr{B}, then solves to get -@texline @math{a = \exp(A)} -@infoline @expr{a = exp(A)} -and @expr{b = B}. - -Another interesting example is the ``quadratic'' model, which can -be handled by expanding according to the distributive law. - -@example -y = a + b*(x - c)^2 -y = a + b c^2 - 2 b c x + b x^2 -@end example - -@noindent -which matches with @expr{Y = y}, @expr{A = a + b c^2}, @expr{F = 1}, -@expr{B = -2 b c}, @expr{G = x} (the @mathit{-2} factor could just as easily -have been put into @expr{G} instead of @expr{B}), @expr{C = b}, and -@expr{H = x^2}. - -The Gaussian model looks quite complicated, but a closer examination -shows that it's actually similar to the quadratic model but with an -exponential that can be brought to the top and moved into @expr{Y}. - -The logistic models cannot be put into general linear form. For these -models, and the Hubbert linearization, Calc computes a rough -approximation for the parameters, then uses the Levenberg-Marquardt -iterative method to refine the approximations. - -Another model that cannot be put into general linear -form is a Gaussian with a constant background added on, i.e., -@expr{d} + the regular Gaussian formula. If you have a model like -this, your best bet is to replace enough of your parameters with -constants to make the model linearizable, then adjust the constants -manually by doing a series of fits. You can compare the fits by -graphing them, by examining the goodness-of-fit measures returned by -@kbd{I a F}, or by some other method suitable to your application. -Note that some models can be linearized in several ways. The -Gaussian-plus-@var{d} model can be linearized by setting @expr{d} -(the background) to a constant, or by setting @expr{b} (the standard -deviation) and @expr{c} (the mean) to constants. - -To fit a model with constants substituted for some parameters, just -store suitable values in those parameter variables, then omit them -from the list of parameters when you answer the variables prompt. - -@tex -\bigskip -@end tex - -A last desperate step would be to use the general-purpose -@code{minimize} function rather than @code{fit}. After all, both -functions solve the problem of minimizing an expression (the -@texline @math{\chi^2} -@infoline @expr{chi^2} -sum) by adjusting certain parameters in the expression. The @kbd{a F} -command is able to use a vastly more efficient algorithm due to its -special knowledge about linear chi-square sums, but the @kbd{a N} -command can do the same thing by brute force. - -A compromise would be to pick out a few parameters without which the -fit is linearizable, and use @code{minimize} on a call to @code{fit} -which efficiently takes care of the rest of the parameters. The thing -to be minimized would be the value of -@texline @math{\chi^2} -@infoline @expr{chi^2} -returned as the fifth result of the @code{xfit} function: - -@smallexample -minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess) -@end smallexample - -@noindent -where @code{gaus} represents the Gaussian model with background, -@code{data} represents the data matrix, and @code{guess} represents -the initial guess for @expr{d} that @code{minimize} requires. -This operation will only be, shall we say, extraordinarily slow -rather than astronomically slow (as would be the case if @code{minimize} -were used by itself to solve the problem). - -@tex -\bigskip -@end tex - -The @kbd{I a F} [@code{xfit}] command is somewhat trickier when -nonlinear models are used. The second item in the result is the -vector of ``raw'' parameters @expr{A}, @expr{B}, @expr{C}. The -covariance matrix is written in terms of those raw parameters. -The fifth item is a vector of @dfn{filter} expressions. This -is the empty vector @samp{[]} if the raw parameters were the same -as the requested parameters, i.e., if @expr{A = a}, @expr{B = b}, -and so on (which is always true if the model is already linear -in the parameters as written, e.g., for polynomial fits). If the -parameters had to be rearranged, the fifth item is instead a vector -of one formula per parameter in the original model. The raw -parameters are expressed in these ``filter'' formulas as -@samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} for @expr{B}, -and so on. - -When Calc needs to modify the model to return the result, it replaces -@samp{fitdummy(1)} in all the filters with the first item in the raw -parameters list, and so on for the other raw parameters, then -evaluates the resulting filter formulas to get the actual parameter -values to be substituted into the original model. In the case of -@kbd{H a F} and @kbd{I a F} where the parameters must be error forms, -Calc uses the square roots of the diagonal entries of the covariance -matrix as error values for the raw parameters, then lets Calc's -standard error-form arithmetic take it from there. - -If you use @kbd{I a F} with a nonlinear model, be sure to remember -that the covariance matrix is in terms of the raw parameters, -@emph{not} the actual requested parameters. It's up to you to -figure out how to interpret the covariances in the presence of -nontrivial filter functions. - -Things are also complicated when the input contains error forms. -Suppose there are three independent and dependent variables, @expr{x}, -@expr{y}, and @expr{z}, one or more of which are error forms in the -data. Calc combines all the error values by taking the square root -of the sum of the squares of the errors. It then changes @expr{x} -and @expr{y} to be plain numbers, and makes @expr{z} into an error -form with this combined error. The @expr{Y(x,y,z)} part of the -linearized model is evaluated, and the result should be an error -form. The error part of that result is used for -@texline @math{\sigma_i} -@infoline @expr{sigma_i} -for the data point. If for some reason @expr{Y(x,y,z)} does not return -an error form, the combined error from @expr{z} is used directly for -@texline @math{\sigma_i}. -@infoline @expr{sigma_i}. -Finally, @expr{z} is also stripped of its error -for use in computing @expr{F(x,y,z)}, @expr{G(x,y,z)} and so on; -the righthand side of the linearized model is computed in regular -arithmetic with no error forms. - -(While these rules may seem complicated, they are designed to do -the most reasonable thing in the typical case that @expr{Y(x,y,z)} -depends only on the dependent variable @expr{z}, and in fact is -often simply equal to @expr{z}. For common cases like polynomials -and multilinear models, the combined error is simply used as the -@texline @math{\sigma} -@infoline @expr{sigma} -for the data point with no further ado.) - -@tex -\bigskip -@end tex - -@vindex FitRules -It may be the case that the model you wish to use is linearizable, -but Calc's built-in rules are unable to figure it out. Calc uses -its algebraic rewrite mechanism to linearize a model. The rewrite -rules are kept in the variable @code{FitRules}. You can edit this -variable using the @kbd{s e FitRules} command; in fact, there is -a special @kbd{s F} command just for editing @code{FitRules}. -@xref{Operations on Variables}. - -@xref{Rewrite Rules}, for a discussion of rewrite rules. - -@ignore -@starindex -@end ignore -@tindex fitvar -@ignore -@starindex -@end ignore -@ignore -@mindex @idots -@end ignore -@tindex fitparam -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex fitmodel -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex fitsystem -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex fitdummy -Calc uses @code{FitRules} as follows. First, it converts the model -to an equation if necessary and encloses the model equation in a -call to the function @code{fitmodel} (which is not actually a defined -function in Calc; it is only used as a placeholder by the rewrite rules). -Parameter variables are renamed to function calls @samp{fitparam(1)}, -@samp{fitparam(2)}, and so on, and independent variables are renamed -to @samp{fitvar(1)}, @samp{fitvar(2)}, etc. The dependent variable -is the highest-numbered @code{fitvar}. For example, the power law -model @expr{a x^b} is converted to @expr{y = a x^b}, then to - -@smallexample -@group -fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2)) -@end group -@end smallexample - -Calc then applies the rewrites as if by @samp{C-u 0 a r FitRules}. -(The zero prefix means that rewriting should continue until no further -changes are possible.) - -When rewriting is complete, the @code{fitmodel} call should have -been replaced by a @code{fitsystem} call that looks like this: - -@example -fitsystem(@var{Y}, @var{FGH}, @var{abc}) -@end example - -@noindent -where @var{Y} is a formula that describes the function @expr{Y(x,y,z)}, -@var{FGH} is the vector of formulas @expr{[F(x,y,z), G(x,y,z), H(x,y,z)]}, -and @var{abc} is the vector of parameter filters which refer to the -raw parameters as @samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} -for @expr{B}, etc. While the number of raw parameters (the length of -the @var{FGH} vector) is usually the same as the number of original -parameters (the length of the @var{abc} vector), this is not required. - -The power law model eventually boils down to - -@smallexample -@group -fitsystem(ln(fitvar(2)), - [1, ln(fitvar(1))], - [exp(fitdummy(1)), fitdummy(2)]) -@end group -@end smallexample - -The actual implementation of @code{FitRules} is complicated; it -proceeds in four phases. First, common rearrangements are done -to try to bring linear terms together and to isolate functions like -@code{exp} and @code{ln} either all the way ``out'' (so that they -can be put into @var{Y}) or all the way ``in'' (so that they can -be put into @var{abc} or @var{FGH}). In particular, all -non-constant powers are converted to logs-and-exponentials form, -and the distributive law is used to expand products of sums. -Quotients are rewritten to use the @samp{fitinv} function, where -@samp{fitinv(x)} represents @expr{1/x} while the @code{FitRules} -are operating. (The use of @code{fitinv} makes recognition of -linear-looking forms easier.) If you modify @code{FitRules}, you -will probably only need to modify the rules for this phase. - -Phase two, whose rules can actually also apply during phases one -and three, first rewrites @code{fitmodel} to a two-argument -form @samp{fitmodel(@var{Y}, @var{model})}, where @var{Y} is -initially zero and @var{model} has been changed from @expr{a=b} -to @expr{a-b} form. It then tries to peel off invertible functions -from the outside of @var{model} and put them into @var{Y} instead, -calling the equation solver to invert the functions. Finally, when -this is no longer possible, the @code{fitmodel} is changed to a -four-argument @code{fitsystem}, where the fourth argument is -@var{model} and the @var{FGH} and @var{abc} vectors are initially -empty. (The last vector is really @var{ABC}, corresponding to -raw parameters, for now.) - -Phase three converts a sum of items in the @var{model} to a sum -of @samp{fitpart(@var{a}, @var{b}, @var{c})} terms which represent -terms @samp{@var{a}*@var{b}*@var{c}} of the sum, where @var{a} -is all factors that do not involve any variables, @var{b} is all -factors that involve only parameters, and @var{c} is the factors -that involve only independent variables. (If this decomposition -is not possible, the rule set will not complete and Calc will -complain that the model is too complex.) Then @code{fitpart}s -with equal @var{b} or @var{c} components are merged back together -using the distributive law in order to minimize the number of -raw parameters needed. - -Phase four moves the @code{fitpart} terms into the @var{FGH} and -@var{ABC} vectors. Also, some of the algebraic expansions that -were done in phase 1 are undone now to make the formulas more -computationally efficient. Finally, it calls the solver one more -time to convert the @var{ABC} vector to an @var{abc} vector, and -removes the fourth @var{model} argument (which by now will be zero) -to obtain the three-argument @code{fitsystem} that the linear -least-squares solver wants to see. - -@ignore -@starindex -@end ignore -@ignore -@mindex hasfit@idots -@end ignore -@tindex hasfitparams -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex hasfitvars -Two functions which are useful in connection with @code{FitRules} -are @samp{hasfitparams(x)} and @samp{hasfitvars(x)}, which check -whether @expr{x} refers to any parameters or independent variables, -respectively. Specifically, these functions return ``true'' if the -argument contains any @code{fitparam} (or @code{fitvar}) function -calls, and ``false'' otherwise. (Recall that ``true'' means a -nonzero number, and ``false'' means zero. The actual nonzero number -returned is the largest @var{n} from all the @samp{fitparam(@var{n})}s -or @samp{fitvar(@var{n})}s, respectively, that appear in the formula.) - -@tex -\bigskip -@end tex - -The @code{fit} function in algebraic notation normally takes four -arguments, @samp{fit(@var{model}, @var{vars}, @var{params}, @var{data})}, -where @var{model} is the model formula as it would be typed after -@kbd{a F '}, @var{vars} is the independent variable or a vector of -independent variables, @var{params} likewise gives the parameter(s), -and @var{data} is the data matrix. Note that the length of @var{vars} -must be equal to the number of rows in @var{data} if @var{model} is -an equation, or one less than the number of rows if @var{model} is -a plain formula. (Actually, a name for the dependent variable is -allowed but will be ignored in the plain-formula case.) - -If @var{params} is omitted, the parameters are all variables in -@var{model} except those that appear in @var{vars}. If @var{vars} -is also omitted, Calc sorts all the variables that appear in -@var{model} alphabetically and uses the higher ones for @var{vars} -and the lower ones for @var{params}. - -Alternatively, @samp{fit(@var{modelvec}, @var{data})} is allowed -where @var{modelvec} is a 2- or 3-vector describing the model -and variables, as discussed previously. - -If Calc is unable to do the fit, the @code{fit} function is left -in symbolic form, ordinarily with an explanatory message. The -message will be ``Model expression is too complex'' if the -linearizer was unable to put the model into the required form. - -The @code{efit} (corresponding to @kbd{H a F}) and @code{xfit} -(for @kbd{I a F}) functions are completely analogous. - -@node Interpolation, , Curve Fitting Details, Curve Fitting -@subsection Polynomial Interpolation - -@kindex a p -@pindex calc-poly-interp -@tindex polint -The @kbd{a p} (@code{calc-poly-interp}) [@code{polint}] command does -a polynomial interpolation at a particular @expr{x} value. It takes -two arguments from the stack: A data matrix of the sort used by -@kbd{a F}, and a single number which represents the desired @expr{x} -value. Calc effectively does an exact polynomial fit as if by @kbd{a F i}, -then substitutes the @expr{x} value into the result in order to get an -approximate @expr{y} value based on the fit. (Calc does not actually -use @kbd{a F i}, however; it uses a direct method which is both more -efficient and more numerically stable.) - -The result of @kbd{a p} is actually a vector of two values: The @expr{y} -value approximation, and an error measure @expr{dy} that reflects Calc's -estimation of the probable error of the approximation at that value of -@expr{x}. If the input @expr{x} is equal to any of the @expr{x} values -in the data matrix, the output @expr{y} will be the corresponding @expr{y} -value from the matrix, and the output @expr{dy} will be exactly zero. - -A prefix argument of 2 causes @kbd{a p} to take separate x- and -y-vectors from the stack instead of one data matrix. - -If @expr{x} is a vector of numbers, @kbd{a p} will return a matrix of -interpolated results for each of those @expr{x} values. (The matrix will -have two columns, the @expr{y} values and the @expr{dy} values.) -If @expr{x} is a formula instead of a number, the @code{polint} function -remains in symbolic form; use the @kbd{a "} command to expand it out to -a formula that describes the fit in symbolic terms. - -In all cases, the @kbd{a p} command leaves the data vectors or matrix -on the stack. Only the @expr{x} value is replaced by the result. - -@kindex H a p -@tindex ratint -The @kbd{H a p} [@code{ratint}] command does a rational function -interpolation. It is used exactly like @kbd{a p}, except that it -uses as its model the quotient of two polynomials. If there are -@expr{N} data points, the numerator and denominator polynomials will -each have degree @expr{N/2} (if @expr{N} is odd, the denominator will -have degree one higher than the numerator). - -Rational approximations have the advantage that they can accurately -describe functions that have poles (points at which the function's value -goes to infinity, so that the denominator polynomial of the approximation -goes to zero). If @expr{x} corresponds to a pole of the fitted rational -function, then the result will be a division by zero. If Infinite mode -is enabled, the result will be @samp{[uinf, uinf]}. - -There is no way to get the actual coefficients of the rational function -used by @kbd{H a p}. (The algorithm never generates these coefficients -explicitly, and quotients of polynomials are beyond @w{@kbd{a F}}'s -capabilities to fit.) - -@node Summations, Logical Operations, Curve Fitting, Algebra -@section Summations - -@noindent -@cindex Summation of a series -@kindex a + -@pindex calc-summation -@tindex sum -The @kbd{a +} (@code{calc-summation}) [@code{sum}] command computes -the sum of a formula over a certain range of index values. The formula -is taken from the top of the stack; the command prompts for the -name of the summation index variable, the lower limit of the -sum (any formula), and the upper limit of the sum. If you -enter a blank line at any of these prompts, that prompt and -any later ones are answered by reading additional elements from -the stack. Thus, @kbd{' k^2 @key{RET} ' k @key{RET} 1 @key{RET} 5 @key{RET} a + @key{RET}} -produces the result 55. -@tex -$$ \sum_{k=1}^5 k^2 = 55 $$ -@end tex - -The choice of index variable is arbitrary, but it's best not to -use a variable with a stored value. In particular, while -@code{i} is often a favorite index variable, it should be avoided -in Calc because @code{i} has the imaginary constant @expr{(0, 1)} -as a value. If you pressed @kbd{=} on a sum over @code{i}, it would -be changed to a nonsensical sum over the ``variable'' @expr{(0, 1)}! -If you really want to use @code{i} as an index variable, use -@w{@kbd{s u i @key{RET}}} first to ``unstore'' this variable. -(@xref{Storing Variables}.) - -A numeric prefix argument steps the index by that amount rather -than by one. Thus @kbd{' a_k @key{RET} C-u -2 a + k @key{RET} 10 @key{RET} 0 @key{RET}} -yields @samp{a_10 + a_8 + a_6 + a_4 + a_2 + a_0}. A prefix -argument of plain @kbd{C-u} causes @kbd{a +} to prompt for the -step value, in which case you can enter any formula or enter -a blank line to take the step value from the stack. With the -@kbd{C-u} prefix, @kbd{a +} can take up to five arguments from -the stack: The formula, the variable, the lower limit, the -upper limit, and (at the top of the stack), the step value. - -Calc knows how to do certain sums in closed form. For example, -@samp{sum(6 k^2, k, 1, n) = @w{2 n^3} + 3 n^2 + n}. In particular, -this is possible if the formula being summed is polynomial or -exponential in the index variable. Sums of logarithms are -transformed into logarithms of products. Sums of trigonometric -and hyperbolic functions are transformed to sums of exponentials -and then done in closed form. Also, of course, sums in which the -lower and upper limits are both numbers can always be evaluated -just by grinding them out, although Calc will use closed forms -whenever it can for the sake of efficiency. - -The notation for sums in algebraic formulas is -@samp{sum(@var{expr}, @var{var}, @var{low}, @var{high}, @var{step})}. -If @var{step} is omitted, it defaults to one. If @var{high} is -omitted, @var{low} is actually the upper limit and the lower limit -is one. If @var{low} is also omitted, the limits are @samp{-inf} -and @samp{inf}, respectively. - -Infinite sums can sometimes be evaluated: @samp{sum(.5^k, k, 1, inf)} -returns @expr{1}. This is done by evaluating the sum in closed -form (to @samp{1. - 0.5^n} in this case), then evaluating this -formula with @code{n} set to @code{inf}. Calc's usual rules -for ``infinite'' arithmetic can find the answer from there. If -infinite arithmetic yields a @samp{nan}, or if the sum cannot be -solved in closed form, Calc leaves the @code{sum} function in -symbolic form. @xref{Infinities}. - -As a special feature, if the limits are infinite (or omitted, as -described above) but the formula includes vectors subscripted by -expressions that involve the iteration variable, Calc narrows -the limits to include only the range of integers which result in -valid subscripts for the vector. For example, the sum -@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}. - -The limits of a sum do not need to be integers. For example, -@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}. -Calc computes the number of iterations using the formula -@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must, -after algebraic simplification, evaluate to an integer. - -If the number of iterations according to the above formula does -not come out to an integer, the sum is invalid and will be left -in symbolic form. However, closed forms are still supplied, and -you are on your honor not to misuse the resulting formulas by -substituting mismatched bounds into them. For example, -@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and -evaluate the closed form solution for the limits 1 and 10 to get -the rather dubious answer, 29.25. - -If the lower limit is greater than the upper limit (assuming a -positive step size), the result is generally zero. However, -Calc only guarantees a zero result when the upper limit is -exactly one step less than the lower limit, i.e., if the number -of iterations is @mathit{-1}. Thus @samp{sum(f(k), k, n, n-1)} is zero -but the sum from @samp{n} to @samp{n-2} may report a nonzero value -if Calc used a closed form solution. - -Calc's logical predicates like @expr{a < b} return 1 for ``true'' -and 0 for ``false.'' @xref{Logical Operations}. This can be -used to advantage for building conditional sums. For example, -@samp{sum(prime(k)*k^2, k, 1, 20)} is the sum of the squares of all -prime numbers from 1 to 20; the @code{prime} predicate returns 1 if -its argument is prime and 0 otherwise. You can read this expression -as ``the sum of @expr{k^2}, where @expr{k} is prime.'' Indeed, -@samp{sum(prime(k)*k^2, k)} would represent the sum of @emph{all} primes -squared, since the limits default to plus and minus infinity, but -there are no such sums that Calc's built-in rules can do in -closed form. - -As another example, @samp{sum((k != k_0) * f(k), k, 1, n)} is the -sum of @expr{f(k)} for all @expr{k} from 1 to @expr{n}, excluding -one value @expr{k_0}. Slightly more tricky is the summand -@samp{(k != k_0) / (k - k_0)}, which is an attempt to describe -the sum of all @expr{1/(k-k_0)} except at @expr{k = k_0}, where -this would be a division by zero. But at @expr{k = k_0}, this -formula works out to the indeterminate form @expr{0 / 0}, which -Calc will not assume is zero. Better would be to use -@samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does -an ``if-then-else'' test: This expression says, ``if -@texline @math{k \ne k_0}, -@infoline @expr{k != k_0}, -then @expr{1/(k-k_0)}, else zero.'' Now the formula @expr{1/(k-k_0)} -will not even be evaluated by Calc when @expr{k = k_0}. - -@cindex Alternating sums -@kindex a - -@pindex calc-alt-summation -@tindex asum -The @kbd{a -} (@code{calc-alt-summation}) [@code{asum}] command -computes an alternating sum. Successive terms of the sequence -are given alternating signs, with the first term (corresponding -to the lower index value) being positive. Alternating sums -are converted to normal sums with an extra term of the form -@samp{(-1)^(k-@var{low})}. This formula is adjusted appropriately -if the step value is other than one. For example, the Taylor -series for the sine function is @samp{asum(x^k / k!, k, 1, inf, 2)}. -(Calc cannot evaluate this infinite series, but it can approximate -it if you replace @code{inf} with any particular odd number.) -Calc converts this series to a regular sum with a step of one, -namely @samp{sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)}. - -@cindex Product of a sequence -@kindex a * -@pindex calc-product -@tindex prod -The @kbd{a *} (@code{calc-product}) [@code{prod}] command is -the analogous way to take a product of many terms. Calc also knows -some closed forms for products, such as @samp{prod(k, k, 1, n) = n!}. -Conditional products can be written @samp{prod(k^prime(k), k, 1, n)} -or @samp{prod(prime(k) ? k : 1, k, 1, n)}. - -@kindex a T -@pindex calc-tabulate -@tindex table -The @kbd{a T} (@code{calc-tabulate}) [@code{table}] command -evaluates a formula at a series of iterated index values, just -like @code{sum} and @code{prod}, but its result is simply a -vector of the results. For example, @samp{table(a_i, i, 1, 7, 2)} -produces @samp{[a_1, a_3, a_5, a_7]}. - -@node Logical Operations, Rewrite Rules, Summations, Algebra -@section Logical Operations - -@noindent -The following commands and algebraic functions return true/false values, -where 1 represents ``true'' and 0 represents ``false.'' In cases where -a truth value is required (such as for the condition part of a rewrite -rule, or as the condition for a @w{@kbd{Z [ Z ]}} control structure), any -nonzero value is accepted to mean ``true.'' (Specifically, anything -for which @code{dnonzero} returns 1 is ``true,'' and anything for -which @code{dnonzero} returns 0 or cannot decide is assumed ``false.'' -Note that this means that @w{@kbd{Z [ Z ]}} will execute the ``then'' -portion if its condition is provably true, but it will execute the -``else'' portion for any condition like @expr{a = b} that is not -provably true, even if it might be true. Algebraic functions that -have conditions as arguments, like @code{? :} and @code{&&}, remain -unevaluated if the condition is neither provably true nor provably -false. @xref{Declarations}.) - -@kindex a = -@pindex calc-equal-to -@tindex eq -@tindex = -@tindex == -The @kbd{a =} (@code{calc-equal-to}) command, or @samp{eq(a,b)} function -(which can also be written @samp{a = b} or @samp{a == b} in an algebraic -formula) is true if @expr{a} and @expr{b} are equal, either because they -are identical expressions, or because they are numbers which are -numerically equal. (Thus the integer 1 is considered equal to the float -1.0.) If the equality of @expr{a} and @expr{b} cannot be determined, -the comparison is left in symbolic form. Note that as a command, this -operation pops two values from the stack and pushes back either a 1 or -a 0, or a formula @samp{a = b} if the values' equality cannot be determined. - -Many Calc commands use @samp{=} formulas to represent @dfn{equations}. -For example, the @kbd{a S} (@code{calc-solve-for}) command rearranges -an equation to solve for a given variable. The @kbd{a M} -(@code{calc-map-equation}) command can be used to apply any -function to both sides of an equation; for example, @kbd{2 a M *} -multiplies both sides of the equation by two. Note that just -@kbd{2 *} would not do the same thing; it would produce the formula -@samp{2 (a = b)} which represents 2 if the equality is true or -zero if not. - -The @code{eq} function with more than two arguments (e.g., @kbd{C-u 3 a =} -or @samp{a = b = c}) tests if all of its arguments are equal. In -algebraic notation, the @samp{=} operator is unusual in that it is -neither left- nor right-associative: @samp{a = b = c} is not the -same as @samp{(a = b) = c} or @samp{a = (b = c)} (which each compare -one variable with the 1 or 0 that results from comparing two other -variables). - -@kindex a # -@pindex calc-not-equal-to -@tindex neq -@tindex != -The @kbd{a #} (@code{calc-not-equal-to}) command, or @samp{neq(a,b)} or -@samp{a != b} function, is true if @expr{a} and @expr{b} are not equal. -This also works with more than two arguments; @samp{a != b != c != d} -tests that all four of @expr{a}, @expr{b}, @expr{c}, and @expr{d} are -distinct numbers. - -@kindex a < -@tindex lt -@ignore -@mindex @idots -@end ignore -@kindex a > -@ignore -@mindex @null -@end ignore -@kindex a [ -@ignore -@mindex @null -@end ignore -@kindex a ] -@pindex calc-less-than -@pindex calc-greater-than -@pindex calc-less-equal -@pindex calc-greater-equal -@ignore -@mindex @null -@end ignore -@tindex gt -@ignore -@mindex @null -@end ignore -@tindex leq -@ignore -@mindex @null -@end ignore -@tindex geq -@ignore -@mindex @null -@end ignore -@tindex < -@ignore -@mindex @null -@end ignore -@tindex > -@ignore -@mindex @null -@end ignore -@tindex <= -@ignore -@mindex @null -@end ignore -@tindex >= -The @kbd{a <} (@code{calc-less-than}) [@samp{lt(a,b)} or @samp{a < b}] -operation is true if @expr{a} is less than @expr{b}. Similar functions -are @kbd{a >} (@code{calc-greater-than}) [@samp{gt(a,b)} or @samp{a > b}], -@kbd{a [} (@code{calc-less-equal}) [@samp{leq(a,b)} or @samp{a <= b}], and -@kbd{a ]} (@code{calc-greater-equal}) [@samp{geq(a,b)} or @samp{a >= b}]. - -While the inequality functions like @code{lt} do not accept more -than two arguments, the syntax @w{@samp{a <= b < c}} is translated to an -equivalent expression involving intervals: @samp{b in [a .. c)}. -(See the description of @code{in} below.) All four combinations -of @samp{<} and @samp{<=} are allowed, or any of the four combinations -of @samp{>} and @samp{>=}. Four-argument constructions like -@samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that -involve both equations and inequalities, are not allowed. - -@kindex a . -@pindex calc-remove-equal -@tindex rmeq -The @kbd{a .} (@code{calc-remove-equal}) [@code{rmeq}] command extracts -the righthand side of the equation or inequality on the top of the -stack. It also works elementwise on vectors. For example, if -@samp{[x = 2.34, y = z / 2]} is on the stack, then @kbd{a .} produces -@samp{[2.34, z / 2]}. As a special case, if the righthand side is a -variable and the lefthand side is a number (as in @samp{2.34 = x}), then -Calc keeps the lefthand side instead. Finally, this command works with -assignments @samp{x := 2.34} as well as equations, always taking the -righthand side, and for @samp{=>} (evaluates-to) operators, always -taking the lefthand side. - -@kindex a & -@pindex calc-logical-and -@tindex land -@tindex && -The @kbd{a &} (@code{calc-logical-and}) [@samp{land(a,b)} or @samp{a && b}] -function is true if both of its arguments are true, i.e., are -non-zero numbers. In this case, the result will be either @expr{a} or -@expr{b}, chosen arbitrarily. If either argument is zero, the result is -zero. Otherwise, the formula is left in symbolic form. - -@kindex a | -@pindex calc-logical-or -@tindex lor -@tindex || -The @kbd{a |} (@code{calc-logical-or}) [@samp{lor(a,b)} or @samp{a || b}] -function is true if either or both of its arguments are true (nonzero). -The result is whichever argument was nonzero, choosing arbitrarily if both -are nonzero. If both @expr{a} and @expr{b} are zero, the result is -zero. - -@kindex a ! -@pindex calc-logical-not -@tindex lnot -@tindex ! -The @kbd{a !} (@code{calc-logical-not}) [@samp{lnot(a)} or @samp{!@: a}] -function is true if @expr{a} is false (zero), or false if @expr{a} is -true (nonzero). It is left in symbolic form if @expr{a} is not a -number. - -@kindex a : -@pindex calc-logical-if -@tindex if -@ignore -@mindex ? : -@end ignore -@tindex ? -@ignore -@mindex @null -@end ignore -@tindex : -@cindex Arguments, not evaluated -The @kbd{a :} (@code{calc-logical-if}) [@samp{if(a,b,c)} or @samp{a ? b :@: c}] -function is equal to either @expr{b} or @expr{c} if @expr{a} is a nonzero -number or zero, respectively. If @expr{a} is not a number, the test is -left in symbolic form and neither @expr{b} nor @expr{c} is evaluated in -any way. In algebraic formulas, this is one of the few Calc functions -whose arguments are not automatically evaluated when the function itself -is evaluated. The others are @code{lambda}, @code{quote}, and -@code{condition}. - -One minor surprise to watch out for is that the formula @samp{a?3:4} -will not work because the @samp{3:4} is parsed as a fraction instead of -as three separate symbols. Type something like @samp{a ? 3 : 4} or -@samp{a?(3):4} instead. - -As a special case, if @expr{a} evaluates to a vector, then both @expr{b} -and @expr{c} are evaluated; the result is a vector of the same length -as @expr{a} whose elements are chosen from corresponding elements of -@expr{b} and @expr{c} according to whether each element of @expr{a} -is zero or nonzero. Each of @expr{b} and @expr{c} must be either a -vector of the same length as @expr{a}, or a non-vector which is matched -with all elements of @expr{a}. - -@kindex a @{ -@pindex calc-in-set -@tindex in -The @kbd{a @{} (@code{calc-in-set}) [@samp{in(a,b)}] function is true if -the number @expr{a} is in the set of numbers represented by @expr{b}. -If @expr{b} is an interval form, @expr{a} must be one of the values -encompassed by the interval. If @expr{b} is a vector, @expr{a} must be -equal to one of the elements of the vector. (If any vector elements are -intervals, @expr{a} must be in any of the intervals.) If @expr{b} is a -plain number, @expr{a} must be numerically equal to @expr{b}. -@xref{Set Operations}, for a group of commands that manipulate sets -of this sort. - -@ignore -@starindex -@end ignore -@tindex typeof -The @samp{typeof(a)} function produces an integer or variable which -characterizes @expr{a}. If @expr{a} is a number, vector, or variable, -the result will be one of the following numbers: - -@example - 1 Integer - 2 Fraction - 3 Floating-point number - 4 HMS form - 5 Rectangular complex number - 6 Polar complex number - 7 Error form - 8 Interval form - 9 Modulo form -10 Date-only form -11 Date/time form -12 Infinity (inf, uinf, or nan) -100 Variable -101 Vector (but not a matrix) -102 Matrix -@end example - -Otherwise, @expr{a} is a formula, and the result is a variable which -represents the name of the top-level function call. - -@ignore -@starindex -@end ignore -@tindex integer -@ignore -@starindex -@end ignore -@tindex real -@ignore -@starindex -@end ignore -@tindex constant -The @samp{integer(a)} function returns true if @expr{a} is an integer. -The @samp{real(a)} function -is true if @expr{a} is a real number, either integer, fraction, or -float. The @samp{constant(a)} function returns true if @expr{a} is -any of the objects for which @code{typeof} would produce an integer -code result except for variables, and provided that the components of -an object like a vector or error form are themselves constant. -Note that infinities do not satisfy any of these tests, nor do -special constants like @code{pi} and @code{e}. - -@xref{Declarations}, for a set of similar functions that recognize -formulas as well as actual numbers. For example, @samp{dint(floor(x))} -is true because @samp{floor(x)} is provably integer-valued, but -@samp{integer(floor(x))} does not because @samp{floor(x)} is not -literally an integer constant. - -@ignore -@starindex -@end ignore -@tindex refers -The @samp{refers(a,b)} function is true if the variable (or sub-expression) -@expr{b} appears in @expr{a}, or false otherwise. Unlike the other -tests described here, this function returns a definite ``no'' answer -even if its arguments are still in symbolic form. The only case where -@code{refers} will be left unevaluated is if @expr{a} is a plain -variable (different from @expr{b}). - -@ignore -@starindex -@end ignore -@tindex negative -The @samp{negative(a)} function returns true if @expr{a} ``looks'' negative, -because it is a negative number, because it is of the form @expr{-x}, -or because it is a product or quotient with a term that looks negative. -This is most useful in rewrite rules. Beware that @samp{negative(a)} -evaluates to 1 or 0 for @emph{any} argument @expr{a}, so it can only -be stored in a formula if the default simplifications are turned off -first with @kbd{m O} (or if it appears in an unevaluated context such -as a rewrite rule condition). - -@ignore -@starindex -@end ignore -@tindex variable -The @samp{variable(a)} function is true if @expr{a} is a variable, -or false if not. If @expr{a} is a function call, this test is left -in symbolic form. Built-in variables like @code{pi} and @code{inf} -are considered variables like any others by this test. - -@ignore -@starindex -@end ignore -@tindex nonvar -The @samp{nonvar(a)} function is true if @expr{a} is a non-variable. -If its argument is a variable it is left unsimplified; it never -actually returns zero. However, since Calc's condition-testing -commands consider ``false'' anything not provably true, this is -often good enough. - -@ignore -@starindex -@end ignore -@tindex lin -@ignore -@starindex -@end ignore -@tindex linnt -@ignore -@starindex -@end ignore -@tindex islin -@ignore -@starindex -@end ignore -@tindex islinnt -@cindex Linearity testing -The functions @code{lin}, @code{linnt}, @code{islin}, and @code{islinnt} -check if an expression is ``linear,'' i.e., can be written in the form -@expr{a + b x} for some constants @expr{a} and @expr{b}, and some -variable or subformula @expr{x}. The function @samp{islin(f,x)} checks -if formula @expr{f} is linear in @expr{x}, returning 1 if so. For -example, @samp{islin(x,x)}, @samp{islin(-x,x)}, @samp{islin(3,x)}, and -@samp{islin(x y / 3 - 2, x)} all return 1. The @samp{lin(f,x)} function -is similar, except that instead of returning 1 it returns the vector -@expr{[a, b, x]}. For the above examples, this vector would be -@expr{[0, 1, x]}, @expr{[0, -1, x]}, @expr{[3, 0, x]}, and -@expr{[-2, y/3, x]}, respectively. Both @code{lin} and @code{islin} -generally remain unevaluated for expressions which are not linear, -e.g., @samp{lin(2 x^2, x)} and @samp{lin(sin(x), x)}. The second -argument can also be a formula; @samp{islin(2 + 3 sin(x), sin(x))} -returns true. - -The @code{linnt} and @code{islinnt} functions perform a similar check, -but require a ``non-trivial'' linear form, which means that the -@expr{b} coefficient must be non-zero. For example, @samp{lin(2,x)} -returns @expr{[2, 0, x]} and @samp{lin(y,x)} returns @expr{[y, 0, x]}, -but @samp{linnt(2,x)} and @samp{linnt(y,x)} are left unevaluated -(in other words, these formulas are considered to be only ``trivially'' -linear in @expr{x}). - -All four linearity-testing functions allow you to omit the second -argument, in which case the input may be linear in any non-constant -formula. Here, the @expr{a=0}, @expr{b=1} case is also considered -trivial, and only constant values for @expr{a} and @expr{b} are -recognized. Thus, @samp{lin(2 x y)} returns @expr{[0, 2, x y]}, -@samp{lin(2 - x y)} returns @expr{[2, -1, x y]}, and @samp{lin(x y)} -returns @expr{[0, 1, x y]}. The @code{linnt} function would allow the -first two cases but not the third. Also, neither @code{lin} nor -@code{linnt} accept plain constants as linear in the one-argument -case: @samp{islin(2,x)} is true, but @samp{islin(2)} is false. - -@ignore -@starindex -@end ignore -@tindex istrue -The @samp{istrue(a)} function returns 1 if @expr{a} is a nonzero -number or provably nonzero formula, or 0 if @expr{a} is anything else. -Calls to @code{istrue} can only be manipulated if @kbd{m O} mode is -used to make sure they are not evaluated prematurely. (Note that -declarations are used when deciding whether a formula is true; -@code{istrue} returns 1 when @code{dnonzero} would return 1, and -it returns 0 when @code{dnonzero} would return 0 or leave itself -in symbolic form.) - -@node Rewrite Rules, , Logical Operations, Algebra -@section Rewrite Rules - -@noindent -@cindex Rewrite rules -@cindex Transformations -@cindex Pattern matching -@kindex a r -@pindex calc-rewrite -@tindex rewrite -The @kbd{a r} (@code{calc-rewrite}) [@code{rewrite}] command makes -substitutions in a formula according to a specified pattern or patterns -known as @dfn{rewrite rules}. Whereas @kbd{a b} (@code{calc-substitute}) -matches literally, so that substituting @samp{sin(x)} with @samp{cos(x)} -matches only the @code{sin} function applied to the variable @code{x}, -rewrite rules match general kinds of formulas; rewriting using the rule -@samp{sin(x) := cos(x)} matches @code{sin} of any argument and replaces -it with @code{cos} of that same argument. The only significance of the -name @code{x} is that the same name is used on both sides of the rule. - -Rewrite rules rearrange formulas already in Calc's memory. -@xref{Syntax Tables}, to read about @dfn{syntax rules}, which are -similar to algebraic rewrite rules but operate when new algebraic -entries are being parsed, converting strings of characters into -Calc formulas. - -@menu -* Entering Rewrite Rules:: -* Basic Rewrite Rules:: -* Conditional Rewrite Rules:: -* Algebraic Properties of Rewrite Rules:: -* Other Features of Rewrite Rules:: -* Composing Patterns in Rewrite Rules:: -* Nested Formulas with Rewrite Rules:: -* Multi-Phase Rewrite Rules:: -* Selections with Rewrite Rules:: -* Matching Commands:: -* Automatic Rewrites:: -* Debugging Rewrites:: -* Examples of Rewrite Rules:: -@end menu - -@node Entering Rewrite Rules, Basic Rewrite Rules, Rewrite Rules, Rewrite Rules -@subsection Entering Rewrite Rules - -@noindent -Rewrite rules normally use the ``assignment'' operator -@samp{@var{old} := @var{new}}. -This operator is equivalent to the function call @samp{assign(old, new)}. -The @code{assign} function is undefined by itself in Calc, so an -assignment formula such as a rewrite rule will be left alone by ordinary -Calc commands. But certain commands, like the rewrite system, interpret -assignments in special ways. - -For example, the rule @samp{sin(x)^2 := 1-cos(x)^2} says to replace -every occurrence of the sine of something, squared, with one minus the -square of the cosine of that same thing. All by itself as a formula -on the stack it does nothing, but when given to the @kbd{a r} command -it turns that command into a sine-squared-to-cosine-squared converter. - -To specify a set of rules to be applied all at once, make a vector of -rules. - -When @kbd{a r} prompts you to enter the rewrite rules, you can answer -in several ways: - -@enumerate -@item -With a rule: @kbd{f(x) := g(x) @key{RET}}. -@item -With a vector of rules: @kbd{[f1(x) := g1(x), f2(x) := g2(x)] @key{RET}}. -(You can omit the enclosing square brackets if you wish.) -@item -With the name of a variable that contains the rule or rules vector: -@kbd{myrules @key{RET}}. -@item -With any formula except a rule, a vector, or a variable name; this -will be interpreted as the @var{old} half of a rewrite rule, -and you will be prompted a second time for the @var{new} half: -@kbd{f(x) @key{RET} g(x) @key{RET}}. -@item -With a blank line, in which case the rule, rules vector, or variable -will be taken from the top of the stack (and the formula to be -rewritten will come from the second-to-top position). -@end enumerate - -If you enter the rules directly (as opposed to using rules stored -in a variable), those rules will be put into the Trail so that you -can retrieve them later. @xref{Trail Commands}. - -It is most convenient to store rules you use often in a variable and -invoke them by giving the variable name. The @kbd{s e} -(@code{calc-edit-variable}) command is an easy way to create or edit a -rule set stored in a variable. You may also wish to use @kbd{s p} -(@code{calc-permanent-variable}) to save your rules permanently; -@pxref{Operations on Variables}. - -Rewrite rules are compiled into a special internal form for faster -matching. If you enter a rule set directly it must be recompiled -every time. If you store the rules in a variable and refer to them -through that variable, they will be compiled once and saved away -along with the variable for later reference. This is another good -reason to store your rules in a variable. - -Calc also accepts an obsolete notation for rules, as vectors -@samp{[@var{old}, @var{new}]}. But because it is easily confused with a -vector of two rules, the use of this notation is no longer recommended. - -@node Basic Rewrite Rules, Conditional Rewrite Rules, Entering Rewrite Rules, Rewrite Rules -@subsection Basic Rewrite Rules - -@noindent -To match a particular formula @expr{x} with a particular rewrite rule -@samp{@var{old} := @var{new}}, Calc compares the structure of @expr{x} with -the structure of @var{old}. Variables that appear in @var{old} are -treated as @dfn{meta-variables}; the corresponding positions in @expr{x} -may contain any sub-formulas. For example, the pattern @samp{f(x,y)} -would match the expression @samp{f(12, a+1)} with the meta-variable -@samp{x} corresponding to 12 and with @samp{y} corresponding to -@samp{a+1}. However, this pattern would not match @samp{f(12)} or -@samp{g(12, a+1)}, since there is no assignment of the meta-variables -that will make the pattern match these expressions. Notice that if -the pattern is a single meta-variable, it will match any expression. - -If a given meta-variable appears more than once in @var{old}, the -corresponding sub-formulas of @expr{x} must be identical. Thus -the pattern @samp{f(x,x)} would match @samp{f(12, 12)} and -@samp{f(a+1, a+1)} but not @samp{f(12, a+1)} or @samp{f(a+b, b+a)}. -(@xref{Conditional Rewrite Rules}, for a way to match the latter.) - -Things other than variables must match exactly between the pattern -and the target formula. To match a particular variable exactly, use -the pseudo-function @samp{quote(v)} in the pattern. For example, the -pattern @samp{x+quote(y)} matches @samp{x+y}, @samp{2+y}, or -@samp{sin(a)+y}. - -The special variable names @samp{e}, @samp{pi}, @samp{i}, @samp{phi}, -@samp{gamma}, @samp{inf}, @samp{uinf}, and @samp{nan} always match -literally. Thus the pattern @samp{sin(d + e + f)} acts exactly like -@samp{sin(d + quote(e) + f)}. - -If the @var{old} pattern is found to match a given formula, that -formula is replaced by @var{new}, where any occurrences in @var{new} -of meta-variables from the pattern are replaced with the sub-formulas -that they matched. Thus, applying the rule @samp{f(x,y) := g(y+x,x)} -to @samp{f(12, a+1)} would produce @samp{g(a+13, 12)}. - -The normal @kbd{a r} command applies rewrite rules over and over -throughout the target formula until no further changes are possible -(up to a limit of 100 times). Use @kbd{C-u 1 a r} to make only one -change at a time. - -@node Conditional Rewrite Rules, Algebraic Properties of Rewrite Rules, Basic Rewrite Rules, Rewrite Rules -@subsection Conditional Rewrite Rules - -@noindent -A rewrite rule can also be @dfn{conditional}, written in the form -@samp{@var{old} := @var{new} :: @var{cond}}. (There is also the obsolete -form @samp{[@var{old}, @var{new}, @var{cond}]}.) If a @var{cond} part -is present in the -rule, this is an additional condition that must be satisfied before -the rule is accepted. Once @var{old} has been successfully matched -to the target expression, @var{cond} is evaluated (with all the -meta-variables substituted for the values they matched) and simplified -with Calc's algebraic simplifications. If the result is a nonzero -number or any other object known to be nonzero (@pxref{Declarations}), -the rule is accepted. If the result is zero or if it is a symbolic -formula that is not known to be nonzero, the rule is rejected. -@xref{Logical Operations}, for a number of functions that return -1 or 0 according to the results of various tests. - -For example, the formula @samp{n > 0} simplifies to 1 or 0 if @expr{n} -is replaced by a positive or nonpositive number, respectively (or if -@expr{n} has been declared to be positive or nonpositive). Thus, -the rule @samp{f(x,y) := g(y+x,x) :: x+y > 0} would apply to -@samp{f(0, 4)} but not to @samp{f(-3, 2)} or @samp{f(12, a+1)} -(assuming no outstanding declarations for @expr{a}). In the case of -@samp{f(-3, 2)}, the condition can be shown not to be satisfied; in -the case of @samp{f(12, a+1)}, the condition merely cannot be shown -to be satisfied, but that is enough to reject the rule. - -While Calc will use declarations to reason about variables in the -formula being rewritten, declarations do not apply to meta-variables. -For example, the rule @samp{f(a) := g(a+1)} will match for any values -of @samp{a}, such as complex numbers, vectors, or formulas, even if -@samp{a} has been declared to be real or scalar. If you want the -meta-variable @samp{a} to match only literal real numbers, use -@samp{f(a) := g(a+1) :: real(a)}. If you want @samp{a} to match only -reals and formulas which are provably real, use @samp{dreal(a)} as -the condition. - -The @samp{::} operator is a shorthand for the @code{condition} -function; @samp{@var{old} := @var{new} :: @var{cond}} is equivalent to -the formula @samp{condition(assign(@var{old}, @var{new}), @var{cond})}. - -If you have several conditions, you can use @samp{... :: c1 :: c2 :: c3} -or @samp{... :: c1 && c2 && c3}. The two are entirely equivalent. - -It is also possible to embed conditions inside the pattern: -@samp{f(x :: x>0, y) := g(y+x, x)}. This is purely a notational -convenience, though; where a condition appears in a rule has no -effect on when it is tested. The rewrite-rule compiler automatically -decides when it is best to test each condition while a rule is being -matched. - -Certain conditions are handled as special cases by the rewrite rule -system and are tested very efficiently: Where @expr{x} is any -meta-variable, these conditions are @samp{integer(x)}, @samp{real(x)}, -@samp{constant(x)}, @samp{negative(x)}, @samp{x >= y} where @expr{y} -is either a constant or another meta-variable and @samp{>=} may be -replaced by any of the six relational operators, and @samp{x % a = b} -where @expr{a} and @expr{b} are constants. Other conditions, like -@samp{x >= y+1} or @samp{dreal(x)}, will be less efficient to check -since Calc must bring the whole evaluator and simplifier into play. - -An interesting property of @samp{::} is that neither of its arguments -will be touched by Calc's default simplifications. This is important -because conditions often are expressions that cannot safely be -evaluated early. For example, the @code{typeof} function never -remains in symbolic form; entering @samp{typeof(a)} will put the -number 100 (the type code for variables like @samp{a}) on the stack. -But putting the condition @samp{... :: typeof(a) = 6} on the stack -is safe since @samp{::} prevents the @code{typeof} from being -evaluated until the condition is actually used by the rewrite system. - -Since @samp{::} protects its lefthand side, too, you can use a dummy -condition to protect a rule that must itself not evaluate early. -For example, it's not safe to put @samp{a(f,x) := apply(f, [x])} on -the stack because it will immediately evaluate to @samp{a(f,x) := f(x)}, -where the meta-variable-ness of @code{f} on the righthand side has been -lost. But @samp{a(f,x) := apply(f, [x]) :: 1} is safe, and of course -the condition @samp{1} is always true (nonzero) so it has no effect on -the functioning of the rule. (The rewrite compiler will ensure that -it doesn't even impact the speed of matching the rule.) - -@node Algebraic Properties of Rewrite Rules, Other Features of Rewrite Rules, Conditional Rewrite Rules, Rewrite Rules -@subsection Algebraic Properties of Rewrite Rules - -@noindent -The rewrite mechanism understands the algebraic properties of functions -like @samp{+} and @samp{*}. In particular, pattern matching takes -the associativity and commutativity of the following functions into -account: - -@smallexample -+ - * = != && || and or xor vint vunion vxor gcd lcm max min beta -@end smallexample - -For example, the rewrite rule: - -@example -a x + b x := (a + b) x -@end example - -@noindent -will match formulas of the form, - -@example -a x + b x, x a + x b, a x + x b, x a + b x -@end example - -Rewrites also understand the relationship between the @samp{+} and @samp{-} -operators. The above rewrite rule will also match the formulas, - -@example -a x - b x, x a - x b, a x - x b, x a - b x -@end example - -@noindent -by matching @samp{b} in the pattern to @samp{-b} from the formula. - -Applied to a sum of many terms like @samp{r + a x + s + b x + t}, this -pattern will check all pairs of terms for possible matches. The rewrite -will take whichever suitable pair it discovers first. - -In general, a pattern using an associative operator like @samp{a + b} -will try @var{2 n} different ways to match a sum of @var{n} terms -like @samp{x + y + z - w}. First, @samp{a} is matched against each -of @samp{x}, @samp{y}, @samp{z}, and @samp{-w} in turn, with @samp{b} -being matched to the remainders @samp{y + z - w}, @samp{x + z - w}, etc. -If none of these succeed, then @samp{b} is matched against each of the -four terms with @samp{a} matching the remainder. Half-and-half matches, -like @samp{(x + y) + (z - w)}, are not tried. - -Note that @samp{*} is not commutative when applied to matrices, but -rewrite rules pretend that it is. If you type @kbd{m v} to enable -Matrix mode (@pxref{Matrix Mode}), rewrite rules will match @samp{*} -literally, ignoring its usual commutativity property. (In the -current implementation, the associativity also vanishes---it is as -if the pattern had been enclosed in a @code{plain} marker; see below.) -If you are applying rewrites to formulas with matrices, it's best to -enable Matrix mode first to prevent algebraically incorrect rewrites -from occurring. - -The pattern @samp{-x} will actually match any expression. For example, -the rule - -@example -f(-x) := -f(x) -@end example - -@noindent -will rewrite @samp{f(a)} to @samp{-f(-a)}. To avoid this, either use -a @code{plain} marker as described below, or add a @samp{negative(x)} -condition. The @code{negative} function is true if its argument -``looks'' negative, for example, because it is a negative number or -because it is a formula like @samp{-x}. The new rule using this -condition is: - -@example -f(x) := -f(-x) :: negative(x) @r{or, equivalently,} -f(-x) := -f(x) :: negative(-x) -@end example - -In the same way, the pattern @samp{x - y} will match the sum @samp{a + b} -by matching @samp{y} to @samp{-b}. - -The pattern @samp{a b} will also match the formula @samp{x/y} if -@samp{y} is a number. Thus the rule @samp{a x + @w{b x} := (a+b) x} -will also convert @samp{a x + x / 2} to @samp{(a + 0.5) x} (or -@samp{(a + 1:2) x}, depending on the current fraction mode). - -Calc will @emph{not} take other liberties with @samp{*}, @samp{/}, and -@samp{^}. For example, the pattern @samp{f(a b)} will not match -@samp{f(x^2)}, and @samp{f(a + b)} will not match @samp{f(2 x)}, even -though conceivably these patterns could match with @samp{a = b = x}. -Nor will @samp{f(a b)} match @samp{f(x / y)} if @samp{y} is not a -constant, even though it could be considered to match with @samp{a = x} -and @samp{b = 1/y}. The reasons are partly for efficiency, and partly -because while few mathematical operations are substantively different -for addition and subtraction, often it is preferable to treat the cases -of multiplication, division, and integer powers separately. - -Even more subtle is the rule set - -@example -[ f(a) + f(b) := f(a + b), -f(a) := f(-a) ] -@end example - -@noindent -attempting to match @samp{f(x) - f(y)}. You might think that Calc -will view this subtraction as @samp{f(x) + (-f(y))} and then apply -the above two rules in turn, but actually this will not work because -Calc only does this when considering rules for @samp{+} (like the -first rule in this set). So it will see first that @samp{f(x) + (-f(y))} -does not match @samp{f(a) + f(b)} for any assignments of the -meta-variables, and then it will see that @samp{f(x) - f(y)} does -not match @samp{-f(a)} for any assignment of @samp{a}. Because Calc -tries only one rule at a time, it will not be able to rewrite -@samp{f(x) - f(y)} with this rule set. An explicit @samp{f(a) - f(b)} -rule will have to be added. - -Another thing patterns will @emph{not} do is break up complex numbers. -The pattern @samp{myconj(a + @w{b i)} := a - b i} will work for formulas -involving the special constant @samp{i} (such as @samp{3 - 4 i}), but -it will not match actual complex numbers like @samp{(3, -4)}. A version -of the above rule for complex numbers would be - -@example -myconj(a) := re(a) - im(a) (0,1) :: im(a) != 0 -@end example - -@noindent -(Because the @code{re} and @code{im} functions understand the properties -of the special constant @samp{i}, this rule will also work for -@samp{3 - 4 i}. In fact, this particular rule would probably be better -without the @samp{im(a) != 0} condition, since if @samp{im(a) = 0} the -righthand side of the rule will still give the correct answer for the -conjugate of a real number.) - -It is also possible to specify optional arguments in patterns. The rule - -@example -opt(a) x + opt(b) (x^opt(c) + opt(d)) := f(a, b, c, d) -@end example - -@noindent -will match the formula - -@example -5 (x^2 - 4) + 3 x -@end example - -@noindent -in a fairly straightforward manner, but it will also match reduced -formulas like - -@example -x + x^2, 2(x + 1) - x, x + x -@end example - -@noindent -producing, respectively, - -@example -f(1, 1, 2, 0), f(-1, 2, 1, 1), f(1, 1, 1, 0) -@end example - -(The latter two formulas can be entered only if default simplifications -have been turned off with @kbd{m O}.) - -The default value for a term of a sum is zero. The default value -for a part of a product, for a power, or for the denominator of a -quotient, is one. Also, @samp{-x} matches the pattern @samp{opt(a) b} -with @samp{a = -1}. - -In particular, the distributive-law rule can be refined to - -@example -opt(a) x + opt(b) x := (a + b) x -@end example - -@noindent -so that it will convert, e.g., @samp{a x - x}, to @samp{(a - 1) x}. - -The pattern @samp{opt(a) + opt(b) x} matches almost any formulas which -are linear in @samp{x}. You can also use the @code{lin} and @code{islin} -functions with rewrite conditions to test for this; @pxref{Logical -Operations}. These functions are not as convenient to use in rewrite -rules, but they recognize more kinds of formulas as linear: -@samp{x/z} is considered linear with @expr{b = 1/z} by @code{lin}, -but it will not match the above pattern because that pattern calls -for a multiplication, not a division. - -As another example, the obvious rule to replace @samp{sin(x)^2 + cos(x)^2} -by 1, - -@example -sin(x)^2 + cos(x)^2 := 1 -@end example - -@noindent -misses many cases because the sine and cosine may both be multiplied by -an equal factor. Here's a more successful rule: - -@example -opt(a) sin(x)^2 + opt(a) cos(x)^2 := a -@end example - -Note that this rule will @emph{not} match @samp{sin(x)^2 + 6 cos(x)^2} -because one @expr{a} would have ``matched'' 1 while the other matched 6. - -Calc automatically converts a rule like - -@example -f(x-1, x) := g(x) -@end example - -@noindent -into the form - -@example -f(temp, x) := g(x) :: temp = x-1 -@end example - -@noindent -(where @code{temp} stands for a new, invented meta-variable that -doesn't actually have a name). This modified rule will successfully -match @samp{f(6, 7)}, binding @samp{temp} and @samp{x} to 6 and 7, -respectively, then verifying that they differ by one even though -@samp{6} does not superficially look like @samp{x-1}. - -However, Calc does not solve equations to interpret a rule. The -following rule, - -@example -f(x-1, x+1) := g(x) -@end example - -@noindent -will not work. That is, it will match @samp{f(a - 1 + b, a + 1 + b)} -but not @samp{f(6, 8)}. Calc always interprets at least one occurrence -of a variable by literal matching. If the variable appears ``isolated'' -then Calc is smart enough to use it for literal matching. But in this -last example, Calc is forced to rewrite the rule to @samp{f(x-1, temp) -:= g(x) :: temp = x+1} where the @samp{x-1} term must correspond to an -actual ``something-minus-one'' in the target formula. - -A successful way to write this would be @samp{f(x, x+2) := g(x+1)}. -You could make this resemble the original form more closely by using -@code{let} notation, which is described in the next section: - -@example -f(xm1, x+1) := g(x) :: let(x := xm1+1) -@end example - -Calc does this rewriting or ``conditionalizing'' for any sub-pattern -which involves only the functions in the following list, operating -only on constants and meta-variables which have already been matched -elsewhere in the pattern. When matching a function call, Calc is -careful to match arguments which are plain variables before arguments -which are calls to any of the functions below, so that a pattern like -@samp{f(x-1, x)} can be conditionalized even though the isolated -@samp{x} comes after the @samp{x-1}. - -@smallexample -+ - * / \ % ^ abs sign round rounde roundu trunc floor ceil -max min re im conj arg -@end smallexample - -You can suppress all of the special treatments described in this -section by surrounding a function call with a @code{plain} marker. -This marker causes the function call which is its argument to be -matched literally, without regard to commutativity, associativity, -negation, or conditionalization. When you use @code{plain}, the -``deep structure'' of the formula being matched can show through. -For example, - -@example -plain(a - a b) := f(a, b) -@end example - -@noindent -will match only literal subtractions. However, the @code{plain} -marker does not affect its arguments' arguments. In this case, -commutativity and associativity is still considered while matching -the @w{@samp{a b}} sub-pattern, so the whole pattern will match -@samp{x - y x} as well as @samp{x - x y}. We could go still -further and use - -@example -plain(a - plain(a b)) := f(a, b) -@end example - -@noindent -which would do a completely strict match for the pattern. - -By contrast, the @code{quote} marker means that not only the -function name but also the arguments must be literally the same. -The above pattern will match @samp{x - x y} but - -@example -quote(a - a b) := f(a, b) -@end example - -@noindent -will match only the single formula @samp{a - a b}. Also, - -@example -quote(a - quote(a b)) := f(a, b) -@end example - -@noindent -will match only @samp{a - quote(a b)}---probably not the desired -effect! - -A certain amount of algebra is also done when substituting the -meta-variables on the righthand side of a rule. For example, -in the rule - -@example -a + f(b) := f(a + b) -@end example - -@noindent -matching @samp{f(x) - y} would produce @samp{f((-y) + x)} if -taken literally, but the rewrite mechanism will simplify the -righthand side to @samp{f(x - y)} automatically. (Of course, -the default simplifications would do this anyway, so this -special simplification is only noticeable if you have turned the -default simplifications off.) This rewriting is done only when -a meta-variable expands to a ``negative-looking'' expression. -If this simplification is not desirable, you can use a @code{plain} -marker on the righthand side: - -@example -a + f(b) := f(plain(a + b)) -@end example - -@noindent -In this example, we are still allowing the pattern-matcher to -use all the algebra it can muster, but the righthand side will -always simplify to a literal addition like @samp{f((-y) + x)}. - -@node Other Features of Rewrite Rules, Composing Patterns in Rewrite Rules, Algebraic Properties of Rewrite Rules, Rewrite Rules -@subsection Other Features of Rewrite Rules - -@noindent -Certain ``function names'' serve as markers in rewrite rules. -Here is a complete list of these markers. First are listed the -markers that work inside a pattern; then come the markers that -work in the righthand side of a rule. - -@ignore -@starindex -@end ignore -@tindex import -One kind of marker, @samp{import(x)}, takes the place of a whole -rule. Here @expr{x} is the name of a variable containing another -rule set; those rules are ``spliced into'' the rule set that -imports them. For example, if @samp{[f(a+b) := f(a) + f(b), -f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF}, -then the rule set @samp{[f(0) := 0, import(linearF)]} will apply -all three rules. It is possible to modify the imported rules -slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports -the rule set @expr{x} with all occurrences of -@texline @math{v_1}, -@infoline @expr{v1}, -as either a variable name or a function name, replaced with -@texline @math{x_1} -@infoline @expr{x1} -and so on. (If -@texline @math{v_1} -@infoline @expr{v1} -is used as a function name, then -@texline @math{x_1} -@infoline @expr{x1} -must be either a function name itself or a @w{@samp{< >}} nameless -function; @pxref{Specifying Operators}.) For example, @samp{[g(0) := 0, -import(linearF, f, g)]} applies the linearity rules to the function -@samp{g} instead of @samp{f}. Imports can be nested, but the -import-with-renaming feature may fail to rename sub-imports properly. - -The special functions allowed in patterns are: - -@table @samp -@item quote(x) -@ignore -@starindex -@end ignore -@tindex quote -This pattern matches exactly @expr{x}; variable names in @expr{x} are -not interpreted as meta-variables. The only flexibility is that -numbers are compared for numeric equality, so that the pattern -@samp{f(quote(12))} will match both @samp{f(12)} and @samp{f(12.0)}. -(Numbers are always treated this way by the rewrite mechanism: -The rule @samp{f(x,x) := g(x)} will match @samp{f(12, 12.0)}. -The rewrite may produce either @samp{g(12)} or @samp{g(12.0)} -as a result in this case.) - -@item plain(x) -@ignore -@starindex -@end ignore -@tindex plain -Here @expr{x} must be a function call @samp{f(x1,x2,@dots{})}. This -pattern matches a call to function @expr{f} with the specified -argument patterns. No special knowledge of the properties of the -function @expr{f} is used in this case; @samp{+} is not commutative or -associative. Unlike @code{quote}, the arguments @samp{x1,x2,@dots{}} -are treated as patterns. If you wish them to be treated ``plainly'' -as well, you must enclose them with more @code{plain} markers: -@samp{plain(plain(@w{-a}) + plain(b c))}. - -@item opt(x,def) -@ignore -@starindex -@end ignore -@tindex opt -Here @expr{x} must be a variable name. This must appear as an -argument to a function or an element of a vector; it specifies that -the argument or element is optional. -As an argument to @samp{+}, @samp{-}, @samp{*}, @samp{&&}, or @samp{||}, -or as the second argument to @samp{/} or @samp{^}, the value @var{def} -may be omitted. The pattern @samp{x + opt(y)} matches a sum by -binding one summand to @expr{x} and the other to @expr{y}, and it -matches anything else by binding the whole expression to @expr{x} and -zero to @expr{y}. The other operators above work similarly. - -For general miscellaneous functions, the default value @code{def} -must be specified. Optional arguments are dropped starting with -the rightmost one during matching. For example, the pattern -@samp{f(opt(a,0), b, opt(c,b))} will match @samp{f(b)}, @samp{f(a,b)}, -or @samp{f(a,b,c)}. Default values of zero and @expr{b} are -supplied in this example for the omitted arguments. Note that -the literal variable @expr{b} will be the default in the latter -case, @emph{not} the value that matched the meta-variable @expr{b}. -In other words, the default @var{def} is effectively quoted. - -@item condition(x,c) -@ignore -@starindex -@end ignore -@tindex condition -@tindex :: -This matches the pattern @expr{x}, with the attached condition -@expr{c}. It is the same as @samp{x :: c}. - -@item pand(x,y) -@ignore -@starindex -@end ignore -@tindex pand -@tindex &&& -This matches anything that matches both pattern @expr{x} and -pattern @expr{y}. It is the same as @samp{x &&& y}. -@pxref{Composing Patterns in Rewrite Rules}. - -@item por(x,y) -@ignore -@starindex -@end ignore -@tindex por -@tindex ||| -This matches anything that matches either pattern @expr{x} or -pattern @expr{y}. It is the same as @w{@samp{x ||| y}}. - -@item pnot(x) -@ignore -@starindex -@end ignore -@tindex pnot -@tindex !!! -This matches anything that does not match pattern @expr{x}. -It is the same as @samp{!!! x}. - -@item cons(h,t) -@ignore -@mindex cons -@end ignore -@tindex cons (rewrites) -This matches any vector of one or more elements. The first -element is matched to @expr{h}; a vector of the remaining -elements is matched to @expr{t}. Note that vectors of fixed -length can also be matched as actual vectors: The rule -@samp{cons(a,cons(b,[])) := cons(a+b,[])} is equivalent -to the rule @samp{[a,b] := [a+b]}. - -@item rcons(t,h) -@ignore -@mindex rcons -@end ignore -@tindex rcons (rewrites) -This is like @code{cons}, except that the @emph{last} element -is matched to @expr{h}, with the remaining elements matched -to @expr{t}. - -@item apply(f,args) -@ignore -@mindex apply -@end ignore -@tindex apply (rewrites) -This matches any function call. The name of the function, in -the form of a variable, is matched to @expr{f}. The arguments -of the function, as a vector of zero or more objects, are -matched to @samp{args}. Constants, variables, and vectors -do @emph{not} match an @code{apply} pattern. For example, -@samp{apply(f,x)} matches any function call, @samp{apply(quote(f),x)} -matches any call to the function @samp{f}, @samp{apply(f,[a,b])} -matches any function call with exactly two arguments, and -@samp{apply(quote(f), cons(a,cons(b,x)))} matches any call -to the function @samp{f} with two or more arguments. Another -way to implement the latter, if the rest of the rule does not -need to refer to the first two arguments of @samp{f} by name, -would be @samp{apply(quote(f), x :: vlen(x) >= 2)}. -Here's a more interesting sample use of @code{apply}: - -@example -apply(f,[x+n]) := n + apply(f,[x]) - :: in(f, [floor,ceil,round,trunc]) :: integer(n) -@end example - -Note, however, that this will be slower to match than a rule -set with four separate rules. The reason is that Calc sorts -the rules of a rule set according to top-level function name; -if the top-level function is @code{apply}, Calc must try the -rule for every single formula and sub-formula. If the top-level -function in the pattern is, say, @code{floor}, then Calc invokes -the rule only for sub-formulas which are calls to @code{floor}. - -Formulas normally written with operators like @code{+} are still -considered function calls: @code{apply(f,x)} matches @samp{a+b} -with @samp{f = add}, @samp{x = [a,b]}. - -You must use @code{apply} for meta-variables with function names -on both sides of a rewrite rule: @samp{apply(f, [x]) := f(x+1)} -is @emph{not} correct, because it rewrites @samp{spam(6)} into -@samp{f(7)}. The righthand side should be @samp{apply(f, [x+1])}. -Also note that you will have to use No-Simplify mode (@kbd{m O}) -when entering this rule so that the @code{apply} isn't -evaluated immediately to get the new rule @samp{f(x) := f(x+1)}. -Or, use @kbd{s e} to enter the rule without going through the stack, -or enter the rule as @samp{apply(f, [x]) := apply(f, [x+1]) @w{:: 1}}. -@xref{Conditional Rewrite Rules}. - -@item select(x) -@ignore -@starindex -@end ignore -@tindex select -This is used for applying rules to formulas with selections; -@pxref{Selections with Rewrite Rules}. -@end table - -Special functions for the righthand sides of rules are: - -@table @samp -@item quote(x) -The notation @samp{quote(x)} is changed to @samp{x} when the -righthand side is used. As far as the rewrite rule is concerned, -@code{quote} is invisible. However, @code{quote} has the special -property in Calc that its argument is not evaluated. Thus, -while it will not work to put the rule @samp{t(a) := typeof(a)} -on the stack because @samp{typeof(a)} is evaluated immediately -to produce @samp{t(a) := 100}, you can use @code{quote} to -protect the righthand side: @samp{t(a) := quote(typeof(a))}. -(@xref{Conditional Rewrite Rules}, for another trick for -protecting rules from evaluation.) - -@item plain(x) -Special properties of and simplifications for the function call -@expr{x} are not used. One interesting case where @code{plain} -is useful is the rule, @samp{q(x) := quote(x)}, trying to expand a -shorthand notation for the @code{quote} function. This rule will -not work as shown; instead of replacing @samp{q(foo)} with -@samp{quote(foo)}, it will replace it with @samp{foo}! The correct -rule would be @samp{q(x) := plain(quote(x))}. - -@item cons(h,t) -Where @expr{t} is a vector, this is converted into an expanded -vector during rewrite processing. Note that @code{cons} is a regular -Calc function which normally does this anyway; the only way @code{cons} -is treated specially by rewrites is that @code{cons} on the righthand -side of a rule will be evaluated even if default simplifications -have been turned off. - -@item rcons(t,h) -Analogous to @code{cons} except putting @expr{h} at the @emph{end} of -the vector @expr{t}. - -@item apply(f,args) -Where @expr{f} is a variable and @var{args} is a vector, this -is converted to a function call. Once again, note that @code{apply} -is also a regular Calc function. - -@item eval(x) -@ignore -@starindex -@end ignore -@tindex eval -The formula @expr{x} is handled in the usual way, then the -default simplifications are applied to it even if they have -been turned off normally. This allows you to treat any function -similarly to the way @code{cons} and @code{apply} are always -treated. However, there is a slight difference: @samp{cons(2+3, [])} -with default simplifications off will be converted to @samp{[2+3]}, -whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}. - -@item evalsimp(x) -@ignore -@starindex -@end ignore -@tindex evalsimp -The formula @expr{x} has meta-variables substituted in the usual -way, then algebraically simplified. - -@item evalextsimp(x) -@ignore -@starindex -@end ignore -@tindex evalextsimp -The formula @expr{x} has meta-variables substituted in the normal -way, then ``extendedly'' simplified as if by the @kbd{a e} command. - -@item select(x) -@xref{Selections with Rewrite Rules}. -@end table - -There are also some special functions you can use in conditions. - -@table @samp -@item let(v := x) -@ignore -@starindex -@end ignore -@tindex let -The expression @expr{x} is evaluated with meta-variables substituted. -The algebraic simplifications are @emph{not} applied by -default, but @expr{x} can include calls to @code{evalsimp} or -@code{evalextsimp} as described above to invoke higher levels -of simplification. The result of @expr{x} is then bound to the -meta-variable @expr{v}. As usual, if this meta-variable has already -been matched to something else the two values must be equal; if the -meta-variable is new then it is bound to the result of the expression. -This variable can then appear in later conditions, and on the righthand -side of the rule. -In fact, @expr{v} may be any pattern in which case the result of -evaluating @expr{x} is matched to that pattern, binding any -meta-variables that appear in that pattern. Note that @code{let} -can only appear by itself as a condition, or as one term of an -@samp{&&} which is a whole condition: It cannot be inside -an @samp{||} term or otherwise buried. - -The alternate, equivalent form @samp{let(v, x)} is also recognized. -Note that the use of @samp{:=} by @code{let}, while still being -assignment-like in character, is unrelated to the use of @samp{:=} -in the main part of a rewrite rule. - -As an example, @samp{f(a) := g(ia) :: let(ia := 1/a) :: constant(ia)} -replaces @samp{f(a)} with @samp{g} of the inverse of @samp{a}, if -that inverse exists and is constant. For example, if @samp{a} is a -singular matrix the operation @samp{1/a} is left unsimplified and -@samp{constant(ia)} fails, but if @samp{a} is an invertible matrix -then the rule succeeds. Without @code{let} there would be no way -to express this rule that didn't have to invert the matrix twice. -Note that, because the meta-variable @samp{ia} is otherwise unbound -in this rule, the @code{let} condition itself always ``succeeds'' -because no matter what @samp{1/a} evaluates to, it can successfully -be bound to @code{ia}. - -Here's another example, for integrating cosines of linear -terms: @samp{myint(cos(y),x) := sin(y)/b :: let([a,b,x] := lin(y,x))}. -The @code{lin} function returns a 3-vector if its argument is linear, -or leaves itself unevaluated if not. But an unevaluated @code{lin} -call will not match the 3-vector on the lefthand side of the @code{let}, -so this @code{let} both verifies that @code{y} is linear, and binds -the coefficients @code{a} and @code{b} for use elsewhere in the rule. -(It would have been possible to use @samp{sin(a x + b)/b} for the -righthand side instead, but using @samp{sin(y)/b} avoids gratuitous -rearrangement of the argument of the sine.) - -@ignore -@starindex -@end ignore -@tindex ierf -Similarly, here is a rule that implements an inverse-@code{erf} -function. It uses @code{root} to search for a solution. If -@code{root} succeeds, it will return a vector of two numbers -where the first number is the desired solution. If no solution -is found, @code{root} remains in symbolic form. So we use -@code{let} to check that the result was indeed a vector. - -@example -ierf(x) := y :: let([y,z] := root(erf(a) = x, a, .5)) -@end example - -@item matches(v,p) -The meta-variable @var{v}, which must already have been matched -to something elsewhere in the rule, is compared against pattern -@var{p}. Since @code{matches} is a standard Calc function, it -can appear anywhere in a condition. But if it appears alone or -as a term of a top-level @samp{&&}, then you get the special -extra feature that meta-variables which are bound to things -inside @var{p} can be used elsewhere in the surrounding rewrite -rule. - -The only real difference between @samp{let(p := v)} and -@samp{matches(v, p)} is that the former evaluates @samp{v} using -the default simplifications, while the latter does not. - -@item remember -@vindex remember -This is actually a variable, not a function. If @code{remember} -appears as a condition in a rule, then when that rule succeeds -the original expression and rewritten expression are added to the -front of the rule set that contained the rule. If the rule set -was not stored in a variable, @code{remember} is ignored. The -lefthand side is enclosed in @code{quote} in the added rule if it -contains any variables. - -For example, the rule @samp{f(n) := n f(n-1) :: remember} applied -to @samp{f(7)} will add the rule @samp{f(7) := 7 f(6)} to the front -of the rule set. The rule set @code{EvalRules} works slightly -differently: There, the evaluation of @samp{f(6)} will complete before -the result is added to the rule set, in this case as @samp{f(7) := 5040}. -Thus @code{remember} is most useful inside @code{EvalRules}. - -It is up to you to ensure that the optimization performed by -@code{remember} is safe. For example, the rule @samp{foo(n) := n -:: evalv(eatfoo) > 0 :: remember} is a bad idea (@code{evalv} is -the function equivalent of the @kbd{=} command); if the variable -@code{eatfoo} ever contains 1, rules like @samp{foo(7) := 7} will -be added to the rule set and will continue to operate even if -@code{eatfoo} is later changed to 0. - -@item remember(c) -@ignore -@starindex -@end ignore -@tindex remember -Remember the match as described above, but only if condition @expr{c} -is true. For example, @samp{remember(n % 4 = 0)} in the above factorial -rule remembers only every fourth result. Note that @samp{remember(1)} -is equivalent to @samp{remember}, and @samp{remember(0)} has no effect. -@end table - -@node Composing Patterns in Rewrite Rules, Nested Formulas with Rewrite Rules, Other Features of Rewrite Rules, Rewrite Rules -@subsection Composing Patterns in Rewrite Rules - -@noindent -There are three operators, @samp{&&&}, @samp{|||}, and @samp{!!!}, -that combine rewrite patterns to make larger patterns. The -combinations are ``and,'' ``or,'' and ``not,'' respectively, and -these operators are the pattern equivalents of @samp{&&}, @samp{||} -and @samp{!} (which operate on zero-or-nonzero logical values). - -Note that @samp{&&&}, @samp{|||}, and @samp{!!!} are left in symbolic -form by all regular Calc features; they have special meaning only in -the context of rewrite rule patterns. - -The pattern @samp{@var{p1} &&& @var{p2}} matches anything that -matches both @var{p1} and @var{p2}. One especially useful case is -when one of @var{p1} or @var{p2} is a meta-variable. For example, -here is a rule that operates on error forms: - -@example -f(x &&& a +/- b, x) := g(x) -@end example - -This does the same thing, but is arguably simpler than, the rule - -@example -f(a +/- b, a +/- b) := g(a +/- b) -@end example - -@ignore -@starindex -@end ignore -@tindex ends -Here's another interesting example: - -@example -ends(cons(a, x) &&& rcons(y, b)) := [a, b] -@end example - -@noindent -which effectively clips out the middle of a vector leaving just -the first and last elements. This rule will change a one-element -vector @samp{[a]} to @samp{[a, a]}. The similar rule - -@example -ends(cons(a, rcons(y, b))) := [a, b] -@end example - -@noindent -would do the same thing except that it would fail to match a -one-element vector. - -@tex -\bigskip -@end tex - -The pattern @samp{@var{p1} ||| @var{p2}} matches anything that -matches either @var{p1} or @var{p2}. Calc first tries matching -against @var{p1}; if that fails, it goes on to try @var{p2}. - -@ignore -@starindex -@end ignore -@tindex curve -A simple example of @samp{|||} is - -@example -curve(inf ||| -inf) := 0 -@end example - -@noindent -which converts both @samp{curve(inf)} and @samp{curve(-inf)} to zero. - -Here is a larger example: - -@example -log(a, b) ||| (ln(a) :: let(b := e)) := mylog(a, b) -@end example - -This matches both generalized and natural logarithms in a single rule. -Note that the @samp{::} term must be enclosed in parentheses because -that operator has lower precedence than @samp{|||} or @samp{:=}. - -(In practice this rule would probably include a third alternative, -omitted here for brevity, to take care of @code{log10}.) - -While Calc generally treats interior conditions exactly the same as -conditions on the outside of a rule, it does guarantee that if all the -variables in the condition are special names like @code{e}, or already -bound in the pattern to which the condition is attached (say, if -@samp{a} had appeared in this condition), then Calc will process this -condition right after matching the pattern to the left of the @samp{::}. -Thus, we know that @samp{b} will be bound to @samp{e} only if the -@code{ln} branch of the @samp{|||} was taken. - -Note that this rule was careful to bind the same set of meta-variables -on both sides of the @samp{|||}. Calc does not check this, but if -you bind a certain meta-variable only in one branch and then use that -meta-variable elsewhere in the rule, results are unpredictable: - -@example -f(a,b) ||| g(b) := h(a,b) -@end example - -Here if the pattern matches @samp{g(17)}, Calc makes no promises about -the value that will be substituted for @samp{a} on the righthand side. - -@tex -\bigskip -@end tex - -The pattern @samp{!!! @var{pat}} matches anything that does not -match @var{pat}. Any meta-variables that are bound while matching -@var{pat} remain unbound outside of @var{pat}. - -For example, - -@example -f(x &&& !!! a +/- b, !!![]) := g(x) -@end example - -@noindent -converts @code{f} whose first argument is anything @emph{except} an -error form, and whose second argument is not the empty vector, into -a similar call to @code{g} (but without the second argument). - -If we know that the second argument will be a vector (empty or not), -then an equivalent rule would be: - -@example -f(x, y) := g(x) :: typeof(x) != 7 :: vlen(y) > 0 -@end example - -@noindent -where of course 7 is the @code{typeof} code for error forms. -Another final condition, that works for any kind of @samp{y}, -would be @samp{!istrue(y == [])}. (The @code{istrue} function -returns an explicit 0 if its argument was left in symbolic form; -plain @samp{!(y == [])} or @samp{y != []} would not work to replace -@samp{!!![]} since these would be left unsimplified, and thus cause -the rule to fail, if @samp{y} was something like a variable name.) - -It is possible for a @samp{!!!} to refer to meta-variables bound -elsewhere in the pattern. For example, - -@example -f(a, !!!a) := g(a) -@end example - -@noindent -matches any call to @code{f} with different arguments, changing -this to @code{g} with only the first argument. - -If a function call is to be matched and one of the argument patterns -contains a @samp{!!!} somewhere inside it, that argument will be -matched last. Thus - -@example -f(!!!a, a) := g(a) -@end example - -@noindent -will be careful to bind @samp{a} to the second argument of @code{f} -before testing the first argument. If Calc had tried to match the -first argument of @code{f} first, the results would have been -disastrous: since @code{a} was unbound so far, the pattern @samp{a} -would have matched anything at all, and the pattern @samp{!!!a} -therefore would @emph{not} have matched anything at all! - -@node Nested Formulas with Rewrite Rules, Multi-Phase Rewrite Rules, Composing Patterns in Rewrite Rules, Rewrite Rules -@subsection Nested Formulas with Rewrite Rules - -@noindent -When @kbd{a r} (@code{calc-rewrite}) is used, it takes an expression from -the top of the stack and attempts to match any of the specified rules -to any part of the expression, starting with the whole expression -and then, if that fails, trying deeper and deeper sub-expressions. -For each part of the expression, the rules are tried in the order -they appear in the rules vector. The first rule to match the first -sub-expression wins; it replaces the matched sub-expression according -to the @var{new} part of the rule. - -Often, the rule set will match and change the formula several times. -The top-level formula is first matched and substituted repeatedly until -it no longer matches the pattern; then, sub-formulas are tried, and -so on. Once every part of the formula has gotten its chance, the -rewrite mechanism starts over again with the top-level formula -(in case a substitution of one of its arguments has caused it again -to match). This continues until no further matches can be made -anywhere in the formula. - -It is possible for a rule set to get into an infinite loop. The -most obvious case, replacing a formula with itself, is not a problem -because a rule is not considered to ``succeed'' unless the righthand -side actually comes out to something different than the original -formula or sub-formula that was matched. But if you accidentally -had both @samp{ln(a b) := ln(a) + ln(b)} and the reverse -@samp{ln(a) + ln(b) := ln(a b)} in your rule set, Calc would -run forever switching a formula back and forth between the two -forms. - -To avoid disaster, Calc normally stops after 100 changes have been -made to the formula. This will be enough for most multiple rewrites, -but it will keep an endless loop of rewrites from locking up the -computer forever. (On most systems, you can also type @kbd{C-g} to -halt any Emacs command prematurely.) - -To change this limit, give a positive numeric prefix argument. -In particular, @kbd{M-1 a r} applies only one rewrite at a time, -useful when you are first testing your rule (or just if repeated -rewriting is not what is called for by your application). - -@ignore -@starindex -@end ignore -@ignore -@mindex iter@idots -@end ignore -@tindex iterations -You can also put a ``function call'' @samp{iterations(@var{n})} -in place of a rule anywhere in your rules vector (but usually at -the top). Then, @var{n} will be used instead of 100 as the default -number of iterations for this rule set. You can use -@samp{iterations(inf)} if you want no iteration limit by default. -A prefix argument will override the @code{iterations} limit in the -rule set. - -@example -[ iterations(1), - f(x) := f(x+1) ] -@end example - -More precisely, the limit controls the number of ``iterations,'' -where each iteration is a successful matching of a rule pattern whose -righthand side, after substituting meta-variables and applying the -default simplifications, is different from the original sub-formula -that was matched. - -A prefix argument of zero sets the limit to infinity. Use with caution! - -Given a negative numeric prefix argument, @kbd{a r} will match and -substitute the top-level expression up to that many times, but -will not attempt to match the rules to any sub-expressions. - -In a formula, @code{rewrite(@var{expr}, @var{rules}, @var{n})} -does a rewriting operation. Here @var{expr} is the expression -being rewritten, @var{rules} is the rule, vector of rules, or -variable containing the rules, and @var{n} is the optional -iteration limit, which may be a positive integer, a negative -integer, or @samp{inf} or @samp{-inf}. If @var{n} is omitted -the @code{iterations} value from the rule set is used; if both -are omitted, 100 is used. - -@node Multi-Phase Rewrite Rules, Selections with Rewrite Rules, Nested Formulas with Rewrite Rules, Rewrite Rules -@subsection Multi-Phase Rewrite Rules - -@noindent -It is possible to separate a rewrite rule set into several @dfn{phases}. -During each phase, certain rules will be enabled while certain others -will be disabled. A @dfn{phase schedule} controls the order in which -phases occur during the rewriting process. - -@ignore -@starindex -@end ignore -@tindex phase -@vindex all -If a call to the marker function @code{phase} appears in the rules -vector in place of a rule, all rules following that point will be -members of the phase(s) identified in the arguments to @code{phase}. -Phases are given integer numbers. The markers @samp{phase()} and -@samp{phase(all)} both mean the following rules belong to all phases; -this is the default at the start of the rule set. - -If you do not explicitly schedule the phases, Calc sorts all phase -numbers that appear in the rule set and executes the phases in -ascending order. For example, the rule set - -@example -@group -[ f0(x) := g0(x), - phase(1), - f1(x) := g1(x), - phase(2), - f2(x) := g2(x), - phase(3), - f3(x) := g3(x), - phase(1,2), - f4(x) := g4(x) ] -@end group -@end example - -@noindent -has three phases, 1 through 3. Phase 1 consists of the @code{f0}, -@code{f1}, and @code{f4} rules (in that order). Phase 2 consists of -@code{f0}, @code{f2}, and @code{f4}. Phase 3 consists of @code{f0} -and @code{f3}. - -When Calc rewrites a formula using this rule set, it first rewrites -the formula using only the phase 1 rules until no further changes are -possible. Then it switches to the phase 2 rule set and continues -until no further changes occur, then finally rewrites with phase 3. -When no more phase 3 rules apply, rewriting finishes. (This is -assuming @kbd{a r} with a large enough prefix argument to allow the -rewriting to run to completion; the sequence just described stops -early if the number of iterations specified in the prefix argument, -100 by default, is reached.) - -During each phase, Calc descends through the nested levels of the -formula as described previously. (@xref{Nested Formulas with Rewrite -Rules}.) Rewriting starts at the top of the formula, then works its -way down to the parts, then goes back to the top and works down again. -The phase 2 rules do not begin until no phase 1 rules apply anywhere -in the formula. - -@ignore -@starindex -@end ignore -@tindex schedule -A @code{schedule} marker appearing in the rule set (anywhere, but -conventionally at the top) changes the default schedule of phases. -In the simplest case, @code{schedule} has a sequence of phase numbers -for arguments; each phase number is invoked in turn until the -arguments to @code{schedule} are exhausted. Thus adding -@samp{schedule(3,2,1)} at the top of the above rule set would -reverse the order of the phases; @samp{schedule(1,2,3)} would have -no effect since this is the default schedule; and @samp{schedule(1,2,1,3)} -would give phase 1 a second chance after phase 2 has completed, before -moving on to phase 3. - -Any argument to @code{schedule} can instead be a vector of phase -numbers (or even of sub-vectors). Then the sub-sequence of phases -described by the vector are tried repeatedly until no change occurs -in any phase in the sequence. For example, @samp{schedule([1, 2], 3)} -tries phase 1, then phase 2, then, if either phase made any changes -to the formula, repeats these two phases until they can make no -further progress. Finally, it goes on to phase 3 for finishing -touches. - -Also, items in @code{schedule} can be variable names as well as -numbers. A variable name is interpreted as the name of a function -to call on the whole formula. For example, @samp{schedule(1, simplify)} -says to apply the phase-1 rules (presumably, all of them), then to -call @code{simplify} which is the function name equivalent of @kbd{a s}. -Likewise, @samp{schedule([1, simplify])} says to alternate between -phase 1 and @kbd{a s} until no further changes occur. - -Phases can be used purely to improve efficiency; if it is known that -a certain group of rules will apply only at the beginning of rewriting, -and a certain other group will apply only at the end, then rewriting -will be faster if these groups are identified as separate phases. -Once the phase 1 rules are done, Calc can put them aside and no longer -spend any time on them while it works on phase 2. - -There are also some problems that can only be solved with several -rewrite phases. For a real-world example of a multi-phase rule set, -examine the set @code{FitRules}, which is used by the curve-fitting -command to convert a model expression to linear form. -@xref{Curve Fitting Details}. This set is divided into four phases. -The first phase rewrites certain kinds of expressions to be more -easily linearizable, but less computationally efficient. After the -linear components have been picked out, the final phase includes the -opposite rewrites to put each component back into an efficient form. -If both sets of rules were included in one big phase, Calc could get -into an infinite loop going back and forth between the two forms. - -Elsewhere in @code{FitRules}, the components are first isolated, -then recombined where possible to reduce the complexity of the linear -fit, then finally packaged one component at a time into vectors. -If the packaging rules were allowed to begin before the recombining -rules were finished, some components might be put away into vectors -before they had a chance to recombine. By putting these rules in -two separate phases, this problem is neatly avoided. - -@node Selections with Rewrite Rules, Matching Commands, Multi-Phase Rewrite Rules, Rewrite Rules -@subsection Selections with Rewrite Rules - -@noindent -If a sub-formula of the current formula is selected (as by @kbd{j s}; -@pxref{Selecting Subformulas}), the @kbd{a r} (@code{calc-rewrite}) -command applies only to that sub-formula. Together with a negative -prefix argument, you can use this fact to apply a rewrite to one -specific part of a formula without affecting any other parts. - -@kindex j r -@pindex calc-rewrite-selection -The @kbd{j r} (@code{calc-rewrite-selection}) command allows more -sophisticated operations on selections. This command prompts for -the rules in the same way as @kbd{a r}, but it then applies those -rules to the whole formula in question even though a sub-formula -of it has been selected. However, the selected sub-formula will -first have been surrounded by a @samp{select( )} function call. -(Calc's evaluator does not understand the function name @code{select}; -this is only a tag used by the @kbd{j r} command.) - -For example, suppose the formula on the stack is @samp{2 (a + b)^2} -and the sub-formula @samp{a + b} is selected. This formula will -be rewritten to @samp{2 select(a + b)^2} and then the rewrite -rules will be applied in the usual way. The rewrite rules can -include references to @code{select} to tell where in the pattern -the selected sub-formula should appear. - -If there is still exactly one @samp{select( )} function call in -the formula after rewriting is done, it indicates which part of -the formula should be selected afterwards. Otherwise, the -formula will be unselected. - -You can make @kbd{j r} act much like @kbd{a r} by enclosing both parts -of the rewrite rule with @samp{select()}. However, @kbd{j r} -allows you to use the current selection in more flexible ways. -Suppose you wished to make a rule which removed the exponent from -the selected term; the rule @samp{select(a)^x := select(a)} would -work. In the above example, it would rewrite @samp{2 select(a + b)^2} -to @samp{2 select(a + b)}. This would then be returned to the -stack as @samp{2 (a + b)} with the @samp{a + b} selected. - -The @kbd{j r} command uses one iteration by default, unlike -@kbd{a r} which defaults to 100 iterations. A numeric prefix -argument affects @kbd{j r} in the same way as @kbd{a r}. -@xref{Nested Formulas with Rewrite Rules}. - -As with other selection commands, @kbd{j r} operates on the stack -entry that contains the cursor. (If the cursor is on the top-of-stack -@samp{.} marker, it works as if the cursor were on the formula -at stack level 1.) - -If you don't specify a set of rules, the rules are taken from the -top of the stack, just as with @kbd{a r}. In this case, the -cursor must indicate stack entry 2 or above as the formula to be -rewritten (otherwise the same formula would be used as both the -target and the rewrite rules). - -If the indicated formula has no selection, the cursor position within -the formula temporarily selects a sub-formula for the purposes of this -command. If the cursor is not on any sub-formula (e.g., it is in -the line-number area to the left of the formula), the @samp{select( )} -markers are ignored by the rewrite mechanism and the rules are allowed -to apply anywhere in the formula. - -As a special feature, the normal @kbd{a r} command also ignores -@samp{select( )} calls in rewrite rules. For example, if you used the -above rule @samp{select(a)^x := select(a)} with @kbd{a r}, it would apply -the rule as if it were @samp{a^x := a}. Thus, you can write general -purpose rules with @samp{select( )} hints inside them so that they -will ``do the right thing'' in both @kbd{a r} and @kbd{j r}, -both with and without selections. - -@node Matching Commands, Automatic Rewrites, Selections with Rewrite Rules, Rewrite Rules -@subsection Matching Commands - -@noindent -@kindex a m -@pindex calc-match -@tindex match -The @kbd{a m} (@code{calc-match}) [@code{match}] function takes a -vector of formulas and a rewrite-rule-style pattern, and produces -a vector of all formulas which match the pattern. The command -prompts you to enter the pattern; as for @kbd{a r}, you can enter -a single pattern (i.e., a formula with meta-variables), or a -vector of patterns, or a variable which contains patterns, or -you can give a blank response in which case the patterns are taken -from the top of the stack. The pattern set will be compiled once -and saved if it is stored in a variable. If there are several -patterns in the set, vector elements are kept if they match any -of the patterns. - -For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])} -will return @samp{[x+y, x-y, x+y+z]}. - -The @code{import} mechanism is not available for pattern sets. - -The @kbd{a m} command can also be used to extract all vector elements -which satisfy any condition: The pattern @samp{x :: x>0} will select -all the positive vector elements. - -@kindex I a m -@tindex matchnot -With the Inverse flag [@code{matchnot}], this command extracts all -vector elements which do @emph{not} match the given pattern. - -@ignore -@starindex -@end ignore -@tindex matches -There is also a function @samp{matches(@var{x}, @var{p})} which -evaluates to 1 if expression @var{x} matches pattern @var{p}, or -to 0 otherwise. This is sometimes useful for including into the -conditional clauses of other rewrite rules. - -@ignore -@starindex -@end ignore -@tindex vmatches -The function @code{vmatches} is just like @code{matches}, except -that if the match succeeds it returns a vector of assignments to -the meta-variables instead of the number 1. For example, -@samp{vmatches(f(1,2), f(a,b))} returns @samp{[a := 1, b := 2]}. -If the match fails, the function returns the number 0. - -@node Automatic Rewrites, Debugging Rewrites, Matching Commands, Rewrite Rules -@subsection Automatic Rewrites - -@noindent -@cindex @code{EvalRules} variable -@vindex EvalRules -It is possible to get Calc to apply a set of rewrite rules on all -results, effectively adding to the built-in set of default -simplifications. To do this, simply store your rule set in the -variable @code{EvalRules}. There is a convenient @kbd{s E} command -for editing @code{EvalRules}; @pxref{Operations on Variables}. - -For example, suppose you want @samp{sin(a + b)} to be expanded out -to @samp{sin(b) cos(a) + cos(b) sin(a)} wherever it appears, and -similarly for @samp{cos(a + b)}. The corresponding rewrite rule -set would be, - -@smallexample -@group -[ sin(a + b) := cos(a) sin(b) + sin(a) cos(b), - cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ] -@end group -@end smallexample - -To apply these manually, you could put them in a variable called -@code{trigexp} and then use @kbd{a r trigexp} every time you wanted -to expand trig functions. But if instead you store them in the -variable @code{EvalRules}, they will automatically be applied to all -sines and cosines of sums. Then, with @samp{2 x} and @samp{45} on -the stack, typing @kbd{+ S} will (assuming Degrees mode) result in -@samp{0.7071 sin(2 x) + 0.7071 cos(2 x)} automatically. - -As each level of a formula is evaluated, the rules from -@code{EvalRules} are applied before the default simplifications. -Rewriting continues until no further @code{EvalRules} apply. -Note that this is different from the usual order of application of -rewrite rules: @code{EvalRules} works from the bottom up, simplifying -the arguments to a function before the function itself, while @kbd{a r} -applies rules from the top down. - -Because the @code{EvalRules} are tried first, you can use them to -override the normal behavior of any built-in Calc function. - -It is important not to write a rule that will get into an infinite -loop. For example, the rule set @samp{[f(0) := 1, f(n) := n f(n-1)]} -appears to be a good definition of a factorial function, but it is -unsafe. Imagine what happens if @samp{f(2.5)} is simplified. Calc -will continue to subtract 1 from this argument forever without reaching -zero. A safer second rule would be @samp{f(n) := n f(n-1) :: n>0}. -Another dangerous rule is @samp{g(x, y) := g(y, x)}. Rewriting -@samp{g(2, 4)}, this would bounce back and forth between that and -@samp{g(4, 2)} forever. If an infinite loop in @code{EvalRules} -occurs, Emacs will eventually stop with a ``Computation got stuck -or ran too long'' message. - -Another subtle difference between @code{EvalRules} and regular rewrites -concerns rules that rewrite a formula into an identical formula. For -example, @samp{f(n) := f(floor(n))} ``fails to match'' when @expr{n} is -already an integer. But in @code{EvalRules} this case is detected only -if the righthand side literally becomes the original formula before any -further simplification. This means that @samp{f(n) := f(floor(n))} will -get into an infinite loop if it occurs in @code{EvalRules}. Calc will -replace @samp{f(6)} with @samp{f(floor(6))}, which is different from -@samp{f(6)}, so it will consider the rule to have matched and will -continue simplifying that formula; first the argument is simplified -to get @samp{f(6)}, then the rule matches again to get @samp{f(floor(6))} -again, ad infinitum. A much safer rule would check its argument first, -say, with @samp{f(n) := f(floor(n)) :: !dint(n)}. - -(What really happens is that the rewrite mechanism substitutes the -meta-variables in the righthand side of a rule, compares to see if the -result is the same as the original formula and fails if so, then uses -the default simplifications to simplify the result and compares again -(and again fails if the formula has simplified back to its original -form). The only special wrinkle for the @code{EvalRules} is that the -same rules will come back into play when the default simplifications -are used. What Calc wants to do is build @samp{f(floor(6))}, see that -this is different from the original formula, simplify to @samp{f(6)}, -see that this is the same as the original formula, and thus halt the -rewriting. But while simplifying, @samp{f(6)} will again trigger -the same @code{EvalRules} rule and Calc will get into a loop inside -the rewrite mechanism itself.) - -The @code{phase}, @code{schedule}, and @code{iterations} markers do -not work in @code{EvalRules}. If the rule set is divided into phases, -only the phase 1 rules are applied, and the schedule is ignored. -The rules are always repeated as many times as possible. - -The @code{EvalRules} are applied to all function calls in a formula, -but not to numbers (and other number-like objects like error forms), -nor to vectors or individual variable names. (Though they will apply -to @emph{components} of vectors and error forms when appropriate.) You -might try to make a variable @code{phihat} which automatically expands -to its definition without the need to press @kbd{=} by writing the -rule @samp{quote(phihat) := (1-sqrt(5))/2}, but unfortunately this rule -will not work as part of @code{EvalRules}. - -Finally, another limitation is that Calc sometimes calls its built-in -functions directly rather than going through the default simplifications. -When it does this, @code{EvalRules} will not be able to override those -functions. For example, when you take the absolute value of the complex -number @expr{(2, 3)}, Calc computes @samp{sqrt(2*2 + 3*3)} by calling -the multiplication, addition, and square root functions directly rather -than applying the default simplifications to this formula. So an -@code{EvalRules} rule that (perversely) rewrites @samp{sqrt(13) := 6} -would not apply. (However, if you put Calc into Symbolic mode so that -@samp{sqrt(13)} will be left in symbolic form by the built-in square -root function, your rule will be able to apply. But if the complex -number were @expr{(3,4)}, so that @samp{sqrt(25)} must be calculated, -then Symbolic mode will not help because @samp{sqrt(25)} can be -evaluated exactly to 5.) - -One subtle restriction that normally only manifests itself with -@code{EvalRules} is that while a given rewrite rule is in the process -of being checked, that same rule cannot be recursively applied. Calc -effectively removes the rule from its rule set while checking the rule, -then puts it back once the match succeeds or fails. (The technical -reason for this is that compiled pattern programs are not reentrant.) -For example, consider the rule @samp{foo(x) := x :: foo(x/2) > 0} -attempting to match @samp{foo(8)}. This rule will be inactive while -the condition @samp{foo(4) > 0} is checked, even though it might be -an integral part of evaluating that condition. Note that this is not -a problem for the more usual recursive type of rule, such as -@samp{foo(x) := foo(x/2)}, because there the rule has succeeded and -been reactivated by the time the righthand side is evaluated. - -If @code{EvalRules} has no stored value (its default state), or if -anything but a vector is stored in it, then it is ignored. - -Even though Calc's rewrite mechanism is designed to compare rewrite -rules to formulas as quickly as possible, storing rules in -@code{EvalRules} may make Calc run substantially slower. This is -particularly true of rules where the top-level call is a commonly used -function, or is not fixed. The rule @samp{f(n) := n f(n-1) :: n>0} will -only activate the rewrite mechanism for calls to the function @code{f}, -but @samp{lg(n) + lg(m) := lg(n m)} will check every @samp{+} operator. - -@smallexample -apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: in(f, [ln, log10]) -@end smallexample - -@noindent -may seem more ``efficient'' than two separate rules for @code{ln} and -@code{log10}, but actually it is vastly less efficient because rules -with @code{apply} as the top-level pattern must be tested against -@emph{every} function call that is simplified. - -@cindex @code{AlgSimpRules} variable -@vindex AlgSimpRules -Suppose you want @samp{sin(a + b)} to be expanded out not all the time, -but only when algebraic simplifications are used to simplify the -formula. The variable @code{AlgSimpRules} holds rules for this purpose. -The @kbd{a s} command will apply @code{EvalRules} and -@code{AlgSimpRules} to the formula, as well as all of its built-in -simplifications. - -Most of the special limitations for @code{EvalRules} don't apply to -@code{AlgSimpRules}. Calc simply does an @kbd{a r AlgSimpRules} -command with an infinite repeat count as the first step of algebraic -simplifications. It then applies its own built-in simplifications -throughout the formula, and then repeats these two steps (along with -applying the default simplifications) until no further changes are -possible. - -@cindex @code{ExtSimpRules} variable -@cindex @code{UnitSimpRules} variable -@vindex ExtSimpRules -@vindex UnitSimpRules -There are also @code{ExtSimpRules} and @code{UnitSimpRules} variables -that are used by @kbd{a e} and @kbd{u s}, respectively; these commands -also apply @code{EvalRules} and @code{AlgSimpRules}. The variable -@code{IntegSimpRules} contains simplification rules that are used -only during integration by @kbd{a i}. - -@node Debugging Rewrites, Examples of Rewrite Rules, Automatic Rewrites, Rewrite Rules -@subsection Debugging Rewrites - -@noindent -If a buffer named @file{*Trace*} exists, the rewrite mechanism will -record some useful information there as it operates. The original -formula is written there, as is the result of each successful rewrite, -and the final result of the rewriting. All phase changes are also -noted. - -Calc always appends to @file{*Trace*}. You must empty this buffer -yourself periodically if it is in danger of growing unwieldy. - -Note that the rewriting mechanism is substantially slower when the -@file{*Trace*} buffer exists, even if the buffer is not visible on -the screen. Once you are done, you will probably want to kill this -buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in -existence and forget about it, all your future rewrite commands will -be needlessly slow. - -@node Examples of Rewrite Rules, , Debugging Rewrites, Rewrite Rules -@subsection Examples of Rewrite Rules - -@noindent -Returning to the example of substituting the pattern -@samp{sin(x)^2 + cos(x)^2} with 1, we saw that the rule -@samp{opt(a) sin(x)^2 + opt(a) cos(x)^2 := a} does a good job of -finding suitable cases. Another solution would be to use the rule -@samp{cos(x)^2 := 1 - sin(x)^2}, followed by algebraic simplification -if necessary. This rule will be the most effective way to do the job, -but at the expense of making some changes that you might not desire. - -Another algebraic rewrite rule is @samp{exp(x+y) := exp(x) exp(y)}. -To make this work with the @w{@kbd{j r}} command so that it can be -easily targeted to a particular exponential in a large formula, -you might wish to write the rule as @samp{select(exp(x+y)) := -select(exp(x) exp(y))}. The @samp{select} markers will be -ignored by the regular @kbd{a r} command -(@pxref{Selections with Rewrite Rules}). - -A surprisingly useful rewrite rule is @samp{a/(b-c) := a*(b+c)/(b^2-c^2)}. -This will simplify the formula whenever @expr{b} and/or @expr{c} can -be made simpler by squaring. For example, applying this rule to -@samp{2 / (sqrt(2) + 3)} yields @samp{6:7 - 2:7 sqrt(2)} (assuming -Symbolic mode has been enabled to keep the square root from being -evaluated to a floating-point approximation). This rule is also -useful when working with symbolic complex numbers, e.g., -@samp{(a + b i) / (c + d i)}. - -As another example, we could define our own ``triangular numbers'' function -with the rules @samp{[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]}. Enter -this vector and store it in a variable: @kbd{@w{s t} trirules}. Now, given -a suitable formula like @samp{tri(5)} on the stack, type @samp{a r trirules} -to apply these rules repeatedly. After six applications, @kbd{a r} will -stop with 15 on the stack. Once these rules are debugged, it would probably -be most useful to add them to @code{EvalRules} so that Calc will evaluate -the new @code{tri} function automatically. We could then use @kbd{Z K} on -the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies -@code{tri} to the value on the top of the stack. @xref{Programming}. - -@cindex Quaternions -The following rule set, contributed by -@texline Fran\c cois -@infoline Francois -Pinard, implements @dfn{quaternions}, a generalization of the concept of -complex numbers. Quaternions have four components, and are here -represented by function calls @samp{quat(@var{w}, [@var{x}, @var{y}, -@var{z}])} with ``real part'' @var{w} and the three ``imaginary'' parts -collected into a vector. Various arithmetical operations on quaternions -are supported. To use these rules, either add them to @code{EvalRules}, -or create a command based on @kbd{a r} for simplifying quaternion -formulas. A convenient way to enter quaternions would be a command -defined by a keyboard macro containing: @kbd{' quat($$$$, [$$$, $$, $]) -@key{RET}}. - -@smallexample -[ quat(w, x, y, z) := quat(w, [x, y, z]), - quat(w, [0, 0, 0]) := w, - abs(quat(w, v)) := hypot(w, v), - -quat(w, v) := quat(-w, -v), - r + quat(w, v) := quat(r + w, v) :: real(r), - r - quat(w, v) := quat(r - w, -v) :: real(r), - quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2), - r * quat(w, v) := quat(r * w, r * v) :: real(r), - plain(quat(w1, v1) * quat(w2, v2)) - := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)), - quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r), - z / quat(w, v) := z * quatinv(quat(w, v)), - quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2), - quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v), - quat(w, v)^k := quatsqr(quat(w, v)^(k / 2)) - :: integer(k) :: k > 0 :: k % 2 = 0, - quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v) - :: integer(k) :: k > 2, - quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ] -@end smallexample - -Quaternions, like matrices, have non-commutative multiplication. -In other words, @expr{q1 * q2 = q2 * q1} is not necessarily true if -@expr{q1} and @expr{q2} are @code{quat} forms. The @samp{quat*quat} -rule above uses @code{plain} to prevent Calc from rearranging the -product. It may also be wise to add the line @samp{[quat(), matrix]} -to the @code{Decls} matrix, to ensure that Calc's other algebraic -operations will not rearrange a quaternion product. @xref{Declarations}. - -These rules also accept a four-argument @code{quat} form, converting -it to the preferred form in the first rule. If you would rather see -results in the four-argument form, just append the two items -@samp{phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)} to the end -of the rule set. (But remember that multi-phase rule sets don't work -in @code{EvalRules}.) - -@node Units, Store and Recall, Algebra, Top -@chapter Operating on Units - -@noindent -One special interpretation of algebraic formulas is as numbers with units. -For example, the formula @samp{5 m / s^2} can be read ``five meters -per second squared.'' The commands in this chapter help you -manipulate units expressions in this form. Units-related commands -begin with the @kbd{u} prefix key. - -@menu -* Basic Operations on Units:: -* The Units Table:: -* Predefined Units:: -* User-Defined Units:: -* Logarithmic Units:: -* Musical Notes:: -@end menu - -@node Basic Operations on Units, The Units Table, Units, Units -@section Basic Operations on Units - -@noindent -A @dfn{units expression} is a formula which is basically a number -multiplied and/or divided by one or more @dfn{unit names}, which may -optionally be raised to integer powers. Actually, the value part need not -be a number; any product or quotient involving unit names is a units -expression. Many of the units commands will also accept any formula, -where the command applies to all units expressions which appear in the -formula. - -A unit name is a variable whose name appears in the @dfn{unit table}, -or a variable whose name is a prefix character like @samp{k} (for ``kilo'') -or @samp{u} (for ``micro'') followed by a name in the unit table. -A substantial table of built-in units is provided with Calc; -@pxref{Predefined Units}. You can also define your own unit names; -@pxref{User-Defined Units}. - -Note that if the value part of a units expression is exactly @samp{1}, -it will be removed by the Calculator's automatic algebra routines: The -formula @samp{1 mm} is ``simplified'' to @samp{mm}. This is only a -display anomaly, however; @samp{mm} will work just fine as a -representation of one millimeter. - -You may find that Algebraic mode (@pxref{Algebraic Entry}) makes working -with units expressions easier. Otherwise, you will have to remember -to hit the apostrophe key every time you wish to enter units. - -@kindex u s -@pindex calc-simplify-units -@ignore -@mindex usimpl@idots -@end ignore -@tindex usimplify -The @kbd{u s} (@code{calc-simplify-units}) [@code{usimplify}] command -simplifies a units -expression. It uses Calc's algebraic simplifications to simplify the -expression first as a regular algebraic formula; it then looks for -features that can be further simplified by converting one object's units -to be compatible with another's. For example, @samp{5 m + 23 mm} will -simplify to @samp{5.023 m}. When different but compatible units are -added, the righthand term's units are converted to match those of the -lefthand term. @xref{Simplification Modes}, for a way to have this done -automatically at all times. - -Units simplification also handles quotients of two units with the same -dimensionality, as in @w{@samp{2 in s/L cm}} to @samp{5.08 s/L}; fractional -powers of unit expressions, as in @samp{sqrt(9 mm^2)} to @samp{3 mm} and -@samp{sqrt(9 acre)} to a quantity in meters; and @code{floor}, -@code{ceil}, @code{round}, @code{rounde}, @code{roundu}, @code{trunc}, -@code{float}, @code{frac}, @code{abs}, and @code{clean} -applied to units expressions, in which case -the operation in question is applied only to the numeric part of the -expression. Finally, trigonometric functions of quantities with units -of angle are evaluated, regardless of the current angular mode. - -@kindex u c -@pindex calc-convert-units -The @kbd{u c} (@code{calc-convert-units}) command converts a units -expression to new, compatible units. For example, given the units -expression @samp{55 mph}, typing @kbd{u c m/s @key{RET}} produces -@samp{24.5872 m/s}. If you have previously converted a units expression -with the same type of units (in this case, distance over time), you will -be offered the previous choice of new units as a default. Continuing -the above example, entering the units expression @samp{100 km/hr} and -typing @kbd{u c @key{RET}} (without specifying new units) produces -@samp{27.7777777778 m/s}. - -@kindex u t -@pindex calc-convert-temperature -@cindex Temperature conversion -The @kbd{u c} command treats temperature units (like @samp{degC} and -@samp{K}) as relative temperatures. For example, @kbd{u c} converts -@samp{10 degC} to @samp{18 degF}: A change of 10 degrees Celsius -corresponds to a change of 18 degrees Fahrenheit. To convert absolute -temperatures, you can use the @kbd{u t} -(@code{calc-convert-temperature}) command. The value on the stack -must be a simple units expression with units of temperature only. -This command would convert @samp{10 degC} to @samp{50 degF}, the -equivalent temperature on the Fahrenheit scale. - -While many of Calc's conversion factors are exact, some are necessarily -approximate. If Calc is in fraction mode (@pxref{Fraction Mode}), then -unit conversions will try to give exact, rational conversions, but it -isn't always possible. Given @samp{55 mph} in fraction mode, typing -@kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example, -while typing @kbd{u c au/yr @key{RET}} produces -@samp{5.18665819999e-3 au/yr}. - -If the units you request are inconsistent with the original units, the -number will be converted into your units times whatever ``remainder'' -units are left over. (This can be disabled; @pxref{Customizing Calc}.) -For example, converting @samp{55 mph} into acres -produces @samp{6.08e-3 acre / m s}. (Recall that multiplication binds -more strongly than division in Calc formulas, so the units here are -acres per meter-second.) Remainder units are expressed in terms of -``fundamental'' units like @samp{m} and @samp{s}, regardless of the -input units. - -One special exception is that if you specify a single unit name, and -a compatible unit appears somewhere in the units expression, then -that compatible unit will be converted to the new unit and the -remaining units in the expression will be left alone. For example, -given the input @samp{980 cm/s^2}, the command @kbd{u c ms} will -change the @samp{s} to @samp{ms} to get @samp{9.8e-4 cm/ms^2}. -The ``remainder unit'' @samp{cm} is left alone rather than being -changed to the base unit @samp{m}. - -You can use explicit unit conversion instead of the @kbd{u s} command -to gain more control over the units of the result of an expression. -For example, given @samp{5 m + 23 mm}, you can type @kbd{u c m} or -@kbd{u c mm} to express the result in either meters or millimeters. -(For that matter, you could type @kbd{u c fath} to express the result -in fathoms, if you preferred!) - -In place of a specific set of units, you can also enter one of the -units system names @code{si}, @code{mks} (equivalent), or @code{cgs}. -For example, @kbd{u c si @key{RET}} converts the expression into -International System of Units (SI) base units. Also, @kbd{u c base} -converts to Calc's base units, which are the same as @code{si} units -except that @code{base} uses @samp{g} as the fundamental unit of mass -whereas @code{si} uses @samp{kg}. - -@cindex Composite units -The @kbd{u c} command also accepts @dfn{composite units}, which -are expressed as the sum of several compatible unit names. For -example, converting @samp{30.5 in} to units @samp{mi+ft+in} (miles, -feet, and inches) produces @samp{2 ft + 6.5 in}. Calc first -sorts the unit names into order of decreasing relative size. -It then accounts for as much of the input quantity as it can -using an integer number times the largest unit, then moves on -to the next smaller unit, and so on. Only the smallest unit -may have a non-integer amount attached in the result. A few -standard unit names exist for common combinations, such as -@code{mfi} for @samp{mi+ft+in}, and @code{tpo} for @samp{ton+lb+oz}. -Composite units are expanded as if by @kbd{a x}, so that -@samp{(ft+in)/hr} is first converted to @samp{ft/hr+in/hr}. - -If the value on the stack does not contain any units, @kbd{u c} will -prompt first for the old units which this value should be considered -to have, then for the new units. (If the value on the stack can be -simplified so that it doesn't contain any units, like @samp{ft/in} can -be simplified to 12, then @kbd{u c} will still prompt for both old -units and new units. Assuming the old and new units you give are -consistent with each other, the result also will not contain any -units. For example, @kbd{@w{u c} cm @key{RET} in @key{RET}} converts -the number 2 on the stack to 5.08. - -@kindex u b -@pindex calc-base-units -The @kbd{u b} (@code{calc-base-units}) command is shorthand for -@kbd{u c base}; it converts the units expression on the top of the -stack into @code{base} units. If @kbd{u s} does not simplify a -units expression as far as you would like, try @kbd{u b}. - -Like the @kbd{u c} command, the @kbd{u b} command treats temperature -units as relative temperatures. - -@kindex u r -@pindex calc-remove-units -@kindex u x -@pindex calc-extract-units -The @kbd{u r} (@code{calc-remove-units}) command removes units from the -formula at the top of the stack. The @kbd{u x} -(@code{calc-extract-units}) command extracts only the units portion of a -formula. These commands essentially replace every term of the formula -that does or doesn't (respectively) look like a unit name by the -constant 1, then resimplify the formula. - -@kindex u a -@pindex calc-autorange-units -The @kbd{u a} (@code{calc-autorange-units}) command turns on and off a -mode in which unit prefixes like @code{k} (``kilo'') are automatically -applied to keep the numeric part of a units expression in a reasonable -range. This mode affects @kbd{u s} and all units conversion commands -except @kbd{u b}. For example, with autoranging on, @samp{12345 Hz} -will be simplified to @samp{12.345 kHz}. Autoranging is useful for -some kinds of units (like @code{Hz} and @code{m}), but is probably -undesirable for non-metric units like @code{ft} and @code{tbsp}. -(Composite units are more appropriate for those; see above.) - -Autoranging always applies the prefix to the leftmost unit name. -Calc chooses the largest prefix that causes the number to be greater -than or equal to 1.0. Thus an increasing sequence of adjusted times -would be @samp{1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks}. -Generally the rule of thumb is that the number will be adjusted -to be in the interval @samp{[1 .. 1000)}, although there are several -exceptions to this rule. First, if the unit has a power then this -is not possible; @samp{0.1 s^2} simplifies to @samp{100000 ms^2}. -Second, the ``centi-'' prefix is allowed to form @code{cm} (centimeters), -but will not apply to other units. The ``deci-,'' ``deka-,'' and -``hecto-'' prefixes are never used. Thus the allowable interval is -@samp{[1 .. 10)} for millimeters and @samp{[1 .. 100)} for centimeters. -Finally, a prefix will not be added to a unit if the resulting name -is also the actual name of another unit; @samp{1e-15 t} would normally -be considered a ``femto-ton,'' but it is written as @samp{1000 at} -(1000 atto-tons) instead because @code{ft} would be confused with feet. - -@node The Units Table, Predefined Units, Basic Operations on Units, Units -@section The Units Table - -@noindent -@kindex u v -@pindex calc-enter-units-table -The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table -in another buffer called @file{*Units Table*}. Each entry in this table -gives the unit name as it would appear in an expression, the definition -of the unit in terms of simpler units, and a full name or description of -the unit. Fundamental units are defined as themselves; these are the -units produced by the @kbd{u b} command. The fundamental units are -meters, seconds, grams, kelvins, amperes, candelas, moles, radians, -and steradians. - -The Units Table buffer also displays the Unit Prefix Table. Note that -two prefixes, ``kilo'' and ``hecto,'' accept either upper- or lower-case -prefix letters. @samp{Meg} is also accepted as a synonym for the @samp{M} -prefix. Whenever a unit name can be interpreted as either a built-in name -or a prefix followed by another built-in name, the former interpretation -wins. For example, @samp{2 pt} means two pints, not two pico-tons. - -The Units Table buffer, once created, is not rebuilt unless you define -new units. To force the buffer to be rebuilt, give any numeric prefix -argument to @kbd{u v}. - -@kindex u V -@pindex calc-view-units-table -The @kbd{u V} (@code{calc-view-units-table}) command is like @kbd{u v} except -that the cursor is not moved into the Units Table buffer. You can -type @kbd{u V} again to remove the Units Table from the display. To -return from the Units Table buffer after a @kbd{u v}, type @kbd{C-x * c} -again or use the regular Emacs @w{@kbd{C-x o}} (@code{other-window}) -command. You can also kill the buffer with @kbd{C-x k} if you wish; -the actual units table is safely stored inside the Calculator. - -@kindex u g -@pindex calc-get-unit-definition -The @kbd{u g} (@code{calc-get-unit-definition}) command retrieves a unit's -defining expression and pushes it onto the Calculator stack. For example, -@kbd{u g in} will produce the expression @samp{2.54 cm}. This is the -same definition for the unit that would appear in the Units Table buffer. -Note that this command works only for actual unit names; @kbd{u g km} -will report that no such unit exists, for example, because @code{km} is -really the unit @code{m} with a @code{k} (``kilo'') prefix. To see a -definition of a unit in terms of base units, it is easier to push the -unit name on the stack and then reduce it to base units with @kbd{u b}. - -@kindex u e -@pindex calc-explain-units -The @kbd{u e} (@code{calc-explain-units}) command displays an English -description of the units of the expression on the stack. For example, -for the expression @samp{62 km^2 g / s^2 mol K}, the description is -``Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin).'' This -command uses the English descriptions that appear in the righthand -column of the Units Table. - -@node Predefined Units, User-Defined Units, The Units Table, Units -@section Predefined Units - -@noindent -The definitions of many units have changed over the years. For example, -the meter was originally defined in 1791 as one ten-millionth of the -distance from the equator to the north pole. In order to be more -precise, the definition was adjusted several times, and now a meter is -defined as the distance that light will travel in a vacuum in -1/299792458 of a second; consequently, the speed of light in a -vacuum is exactly 299792458 m/s. Many other units have been -redefined in terms of fundamental physical processes; a second, for -example, is currently defined as 9192631770 periods of a certain -radiation related to the cesium-133 atom. The only SI unit that is not -based on a fundamental physical process (although there are efforts to -change this) is the kilogram, which was originally defined as the mass -of one liter of water, but is now defined as the mass of the -international prototype of the kilogram (IPK), a cylinder of platinum-iridium -kept at the Bureau international des poids et mesures in S@`evres, -France. (There are several copies of the IPK throughout the world.) -The British imperial units, once defined in terms of physical objects, -were redefined in 1963 in terms of SI units. The US customary units, -which were the same as British units until the British imperial system -was created in 1824, were also defined in terms of the SI units in 1893. -Because of these redefinitions, conversions between metric, British -Imperial, and US customary units can often be done precisely. - -Since the exact definitions of many kinds of units have evolved over the -years, and since certain countries sometimes have local differences in -their definitions, it is a good idea to examine Calc's definition of a -unit before depending on its exact value. For example, there are three -different units for gallons, corresponding to the US (@code{gal}), -Canadian (@code{galC}), and British (@code{galUK}) definitions. Also, -note that @code{oz} is a standard ounce of mass, @code{ozt} is a Troy -ounce, and @code{ozfl} is a fluid ounce. - -The temperature units corresponding to degrees Kelvin and Centigrade -(Celsius) are the same in this table, since most units commands treat -temperatures as being relative. The @code{calc-convert-temperature} -command has special rules for handling the different absolute magnitudes -of the various temperature scales. - -The unit of volume ``liters'' can be referred to by either the lower-case -@code{l} or the upper-case @code{L}. - -The unit @code{A} stands for Amperes; the name @code{Ang} is used -@tex -for \AA ngstroms. -@end tex -@ifnottex -for Angstroms. -@end ifnottex - -The unit @code{pt} stands for pints; the name @code{point} stands for -a typographical point, defined by @samp{72 point = 1 in}. This is -slightly different than the point defined by the American Typefounder's -Association in 1886, but the point used by Calc has become standard -largely due to its use by the PostScript page description language. -There is also @code{texpt}, which stands for a printer's point as -defined by the @TeX{} typesetting system: @samp{72.27 texpt = 1 in}. -Other units used by @TeX{} are available; they are @code{texpc} (a pica), -@code{texbp} (a ``big point'', equal to a standard point which is larger -than the point used by @TeX{}), @code{texdd} (a Didot point), -@code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point, -all dimensions representable in @TeX{} are multiples of this value). - -When Calc is using the @TeX{} or @LaTeX{} language mode (@pxref{TeX -and LaTeX Language Modes}), the @TeX{} specific unit names will not -use the @samp{tex} prefix; the unit name for a @TeX{} point will be -@samp{pt} instead of @samp{texpt}, for example. To avoid conflicts, -the unit names for pint and parsec will simply be @samp{pint} and -@samp{parsec} instead of @samp{pt} and @samp{pc}. - - -The unit @code{e} stands for the elementary (electron) unit of charge; -because algebra command could mistake this for the special constant -@expr{e}, Calc provides the alternate unit name @code{ech} which is -preferable to @code{e}. - -The name @code{g} stands for one gram of mass; there is also @code{gf}, -one gram of force. (Likewise for @kbd{lb}, pounds, and @kbd{lbf}.) -Meanwhile, one ``@expr{g}'' of acceleration is denoted @code{ga}. - -The unit @code{ton} is a U.S. ton of @samp{2000 lb}, and @code{t} is -a metric ton of @samp{1000 kg}. - -The names @code{s} (or @code{sec}) and @code{min} refer to units of -time; @code{arcsec} and @code{arcmin} are units of angle. - -Some ``units'' are really physical constants; for example, @code{c} -represents the speed of light, and @code{h} represents Planck's -constant. You can use these just like other units: converting -@samp{.5 c} to @samp{m/s} expresses one-half the speed of light in -meters per second. You can also use this merely as a handy reference; -the @kbd{u g} command gets the definition of one of these constants -in its normal terms, and @kbd{u b} expresses the definition in base -units. - -Two units, @code{pi} and @code{alpha} (the fine structure constant, -approximately @mathit{1/137}) are dimensionless. The units simplification -commands simply treat these names as equivalent to their corresponding -values. However you can, for example, use @kbd{u c} to convert a pure -number into multiples of the fine structure constant, or @kbd{u b} to -convert this back into a pure number. (When @kbd{u c} prompts for the -``old units,'' just enter a blank line to signify that the value -really is unitless.) - -@c Describe angular units, luminosity vs. steradians problem. - -@node User-Defined Units, Logarithmic Units, Predefined Units, Units -@section User-Defined Units - -@noindent -Calc provides ways to get quick access to your selected ``favorite'' -units, as well as ways to define your own new units. - -@kindex u 0-9 -@pindex calc-quick-units -@vindex Units -@cindex @code{Units} variable -@cindex Quick units -To select your favorite units, store a vector of unit names or -expressions in the Calc variable @code{Units}. The @kbd{u 1} -through @kbd{u 9} commands (@code{calc-quick-units}) provide access -to these units. If the value on the top of the stack is a plain -number (with no units attached), then @kbd{u 1} gives it the -specified units. (Basically, it multiplies the number by the -first item in the @code{Units} vector.) If the number on the -stack @emph{does} have units, then @kbd{u 1} converts that number -to the new units. For example, suppose the vector @samp{[in, ft]} -is stored in @code{Units}. Then @kbd{30 u 1} will create the -expression @samp{30 in}, and @kbd{u 2} will convert that expression -to @samp{2.5 ft}. - -The @kbd{u 0} command accesses the tenth element of @code{Units}. -Only ten quick units may be defined at a time. If the @code{Units} -variable has no stored value (the default), or if its value is not -a vector, then the quick-units commands will not function. The -@kbd{s U} command is a convenient way to edit the @code{Units} -variable; @pxref{Operations on Variables}. - -@kindex u d -@pindex calc-define-unit -@cindex User-defined units -The @kbd{u d} (@code{calc-define-unit}) command records the units -expression on the top of the stack as the definition for a new, -user-defined unit. For example, putting @samp{16.5 ft} on the stack and -typing @kbd{u d rod} defines the new unit @samp{rod} to be equivalent to -16.5 feet. The unit conversion and simplification commands will now -treat @code{rod} just like any other unit of length. You will also be -prompted for an optional English description of the unit, which will -appear in the Units Table. If you wish the definition of this unit to -be displayed in a special way in the Units Table buffer (such as with an -asterisk to indicate an approximate value), then you can call this -command with an argument, @kbd{C-u u d}; you will then also be prompted -for a string that will be used to display the definition. - -@kindex u u -@pindex calc-undefine-unit -The @kbd{u u} (@code{calc-undefine-unit}) command removes a user-defined -unit. It is not possible to remove one of the predefined units, -however. - -If you define a unit with an existing unit name, your new definition -will replace the original definition of that unit. If the unit was a -predefined unit, the old definition will not be replaced, only -``shadowed.'' The built-in definition will reappear if you later use -@kbd{u u} to remove the shadowing definition. - -To create a new fundamental unit, use either 1 or the unit name itself -as the defining expression. Otherwise the expression can involve any -other units that you like (except for composite units like @samp{mfi}). -You can create a new composite unit with a sum of other units as the -defining expression. The next unit operation like @kbd{u c} or @kbd{u v} -will rebuild the internal unit table incorporating your modifications. -Note that erroneous definitions (such as two units defined in terms of -each other) will not be detected until the unit table is next rebuilt; -@kbd{u v} is a convenient way to force this to happen. - -Temperature units are treated specially inside the Calculator; it is not -possible to create user-defined temperature units. - -@kindex u p -@pindex calc-permanent-units -@cindex Calc init file, user-defined units -The @kbd{u p} (@code{calc-permanent-units}) command stores the user-defined -units in your Calc init file (the file given by the variable -@code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so that the -units will still be available in subsequent Emacs sessions. If there -was already a set of user-defined units in your Calc init file, it -is replaced by the new set. (@xref{General Mode Commands}, for a way to -tell Calc to use a different file for the Calc init file.) - -@node Logarithmic Units, Musical Notes, User-Defined Units, Units -@section Logarithmic Units - -The units @code{dB} (decibels) and @code{Np} (nepers) are logarithmic -units which are manipulated differently than standard units. Calc -provides commands to work with these logarithmic units. - -Decibels and nepers are used to measure power quantities as well as -field quantities (quantities whose squares are proportional to power); -these two types of quantities are handled slightly different from each -other. By default the Calc commands work as if power quantities are -being used; with the @kbd{H} prefix the Calc commands work as if field -quantities are being used. - -The decibel level of a power -@infoline @math{P1}, -@texline @math{P_1}, -relative to a reference power -@infoline @math{P0}, -@texline @math{P_0}, -is defined to be -@infoline @math{10 log10(P1/P0) dB}. -@texline @math{10 \log_{10}(P_{1}/P_{0}) {\rm dB}}. -(The factor of 10 is because a decibel, as its name implies, is -one-tenth of a bel. The bel, named after Alexander Graham Bell, was -considered to be too large of a unit and was effectively replaced by -the decibel.) If @math{F} is a field quantity with power -@math{P=k F^2}, then a reference quantity of -@infoline @math{F0} -@texline @math{F_0} -would correspond to a power of -@infoline @math{P0=k F0^2}. -@texline @math{P_{0}=kF_{0}^2}. -If -@infoline @math{P1=k F1^2}, -@texline @math{P_{1}=kF_{1}^2}, -then - -@ifnottex -@example -10 log10(P1/P0) = 10 log10(F1^2/F0^2) = 20 log10(F1/F0). -@end example -@end ifnottex -@tex -$$ 10 \log_{10}(P_1/P_0) = 10 \log_{10}(F_1^2/F_0^2) = 20 -\log_{10}(F_1/F_0)$$ -@end tex - -@noindent -In order to get the same decibel level regardless of whether a field -quantity or the corresponding power quantity is used, the decibel -level of a field quantity -@infoline @math{F1}, -@texline @math{F_1}, -relative to a reference -@infoline @math{F0}, -@texline @math{F_0}, -is defined as -@infoline @math{20 log10(F1/F0) dB}. -@texline @math{20 \log_{10}(F_{1}/F_{0}) {\rm dB}}. -For example, the decibel value of a sound pressure level of -@infoline @math{60 uPa} -@texline @math{60 \mu{\rm Pa}} -relative to -@infoline @math{20 uPa} -@texline @math{20 \mu{\rm Pa}} -(the threshold of human hearing) is -@infoline @math{20 log10(60 uPa/ 20 uPa) dB = 20 log10(3) dB}, -@texline @math{20 \log_{10}(60 \mu{\rm Pa}/20 \mu{\rm Pa}) {\rm dB} = 20 \log_{10}(3) {\rm dB}}, -which is about -@infoline @math{9.54 dB}. -@texline @math{9.54 {\rm dB}}. -Note that in taking the ratio, the original units cancel and so these -logarithmic units are dimensionless. - -Nepers (named after John Napier, who is credited with inventing the -logarithm) are similar to bels except they use natural logarithms instead -of common logarithms. The neper level of a power -@infoline @math{P1}, -@texline @math{P_1}, -relative to a reference power -@infoline @math{P0}, -@texline @math{P_0}, -is -@infoline @math{(1/2) ln(P1/P0) Np}. -@texline @math{(1/2) \ln(P_1/P_0) {\rm Np}}. -The neper level of a field -@infoline @math{F1}, -@texline @math{F_1}, -relative to a reference field -@infoline @math{F0}, -@texline @math{F_0}, -is -@infoline @math{ln(F1/F0) Np}. -@texline @math{\ln(F_1/F_0) {\rm Np}}. - -@vindex calc-lu-power-reference -@vindex calc-lu-field-reference -For power quantities, Calc uses -@infoline @math{1 mW} -@texline @math{1 {\rm mW}} -as the default reference quantity; this default can be changed by changing -the value of the customizable variable -@code{calc-lu-power-reference} (@pxref{Customizing Calc}). -For field quantities, Calc uses -@infoline @math{20 uPa} -@texline @math{20 \mu{\rm Pa}} -as the default reference quantity; this is the value used in acoustics -which is where decibels are commonly encountered. This default can be -changed by changing the value of the customizable variable -@code{calc-lu-field-reference} (@pxref{Customizing Calc}). A -non-default reference quantity will be read from the stack if the -capital @kbd{O} prefix is used. - -@kindex l q -@pindex calc-lu-quant -@tindex lupquant -@tindex lufquant -The @kbd{l q} (@code{calc-lu-quant}) [@code{lupquant}] -command computes the power quantity corresponding to a given number of -logarithmic units. With the capital @kbd{O} prefix, @kbd{O l q}, the -reference level will be read from the top of the stack. (In an -algebraic formula, @code{lupquant} can be given an optional second -argument which will be used for the reference level.) For example, -@code{20 dB @key{RET} l q} will return @code{100 mW}; -@code{20 dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}. -The @kbd{H l q} [@code{lufquant}] command behaves like @kbd{l q} but -computes field quantities instead of power quantities. - -@kindex l d -@pindex calc-db -@tindex dbpower -@tindex dbfield -@kindex l n -@pindex calc-np -@tindex nppower -@tindex npfield -The @kbd{l d} (@code{calc-db}) [@code{dbpower}] command will compute -the decibel level of a power quantity using the default reference -level; @kbd{H l d} [@code{dbfield}] will compute the decibel level of -a field quantity. The commands @kbd{l n} (@code{calc-np}) -[@code{nppower}] and @kbd{H l n} [@code{npfield}] will similarly -compute neper levels. With the capital @kbd{O} prefix these commands -will read a reference level from the stack; in an algebraic formula -the reference level can be given as an optional second argument. - -@kindex l + -@pindex calc-lu-plus -@tindex lupadd -@tindex lufadd -@kindex l - -@pindex calc-lu-minus -@tindex lupsub -@tindex lufsub -@kindex l * -@pindex calc-lu-times -@tindex lupmul -@tindex lufmul -@kindex l / -@pindex calc-lu-divide -@tindex lupdiv -@tindex lufdiv -The sum of two power or field quantities doesn't correspond to the sum -of the corresponding decibel or neper levels. If the powers -corresponding to decibel levels -@infoline @math{D1} -@texline @math{D_1} -and -@infoline @math{D2} -@texline @math{D_2} -are added, the corresponding decibel level ``sum'' will be - -@ifnottex -@example - 10 log10(10^(D1/10) + 10^(D2/10)) dB. -@end example -@end ifnottex -@tex -$$ 10 \log_{10}(10^{D_1/10} + 10^{D_2/10}) {\rm dB}.$$ -@end tex - -@noindent -When field quantities are combined, it often means the corresponding -powers are added and so the above formula might be used. In -acoustics, for example, the sound pressure level is a field quantity -and so the decibels are often defined using the field formula, but the -sound pressure levels are combined as the sound power levels, and so -the above formula should be used. If two field quantities themselves -are added, the new decibel level will be - -@ifnottex -@example - 20 log10(10^(D1/20) + 10^(D2/20)) dB. -@end example -@end ifnottex -@tex -$$ 20 \log_{10}(10^{D_1/20} + 10^{D_2/20}) {\rm dB}.$$ -@end tex - -@noindent -If the power corresponding to @math{D} dB is multiplied by a number @math{N}, -then the corresponding decibel level will be - -@ifnottex -@example - D + 10 log10(N) dB, -@end example -@end ifnottex -@tex -$$ D + 10 \log_{10}(N) {\rm dB},$$ -@end tex - -@noindent -if a field quantity is multiplied by @math{N} the corresponding decibel level -will be - -@ifnottex -@example - D + 20 log10(N) dB. -@end example -@end ifnottex -@tex -$$ D + 20 \log_{10}(N) {\rm dB}.$$ -@end tex - -@noindent -There are similar formulas for combining nepers. The @kbd{l +} -(@code{calc-lu-plus}) [@code{lupadd}] command will ``add'' two -logarithmic unit power levels this way; with the @kbd{H} prefix, -@kbd{H l +} [@code{lufadd}] will add logarithmic unit field levels. -Similarly, logarithmic units can be ``subtracted'' with @kbd{l -} -(@code{calc-lu-minus}) [@code{lupsub}] or @kbd{H l -} [@code{lufsub}]. -The @kbd{l *} (@code{calc-lu-times}) [@code{lupmul}] and @kbd{H l *} -[@code{lufmul}] commands will ``multiply'' a logarithmic unit by a -number; the @kbd{l /} (@code{calc-lu-divide}) [@code{lupdiv}] and -@kbd{H l /} [@code{lufdiv}] commands will ``divide'' a logarithmic -unit by a number. Note that the reference quantities don't play a role -in this arithmetic. - -@node Musical Notes, , Logarithmic Units, Units -@section Musical Notes - -Calc can convert between musical notes and their associated -frequencies. Notes can be given using either scientific pitch -notation or midi numbers. Since these note systems are basically -logarithmic scales, Calc uses the @kbd{l} prefix for functions -operating on notes. - -Scientific pitch notation refers to a note by giving a letter -A through G, possibly followed by a flat or sharp) with a subscript -indicating an octave number. Each octave starts with C and ends with -B and -@c increasing each note by a semitone will result -@c in the sequence @expr{C}, @expr{C} sharp, @expr{D}, @expr{E} flat, @expr{E}, -@c @expr{F}, @expr{F} sharp, @expr{G}, @expr{A} flat, @expr{A}, @expr{B} -@c flat and @expr{B}. -the octave numbered 0 was chosen to correspond to the lowest -audible frequency. Using this system, middle C (about 261.625 Hz) -corresponds to the note @expr{C} in octave 4 and is denoted -@expr{C_4}. Any frequency can be described by giving a note plus an -offset in cents (where a cent is a ratio of frequencies so that a -semitone consists of 100 cents). - -The midi note number system assigns numbers to notes so that -@expr{C_(-1)} corresponds to the midi note number 0 and @expr{G_9} -corresponds to the midi note number 127. A midi controller can have -up to 128 keys and each midi note number from 0 to 127 corresponds to -a possible key. - -@kindex l s -@pindex calc-spn -@tindex spn -The @kbd{l s} (@code{calc-spn}) [@code{spn}] command converts either -a frequency or a midi number to scientific pitch notation. For -example, @code{500 Hz} gets converted to -@code{B_4 + 21.3094853649 cents} and @code{84} to @code{C_6}. - - -@kindex l m -@pindex calc-midi -@tindex midi -The @kbd{l m} (@code{calc-midi}) [@code{midi}] command converts either -a frequency or a note given in scientific pitch notation to the -corresponding midi number. For example, @code{C_6} gets converted to 84 -and @code{440 Hz} to 69. - -@kindex l f -@pindex calc-freq -@tindex freq -The @kbd{l f} (@code{calc-freq}) [@code{freq}] command converts either -either a midi number or a note given in scientific pitch notation to -the corresponding frequency. For example, @code{Asharp_2 + 30 cents} -gets converted to @code{118.578040134 Hz} and @code{55} to -@code{195.99771799 Hz}. - -Since the frequencies of notes are not usually given exactly (and are -typically irrational), the customizable variable -@code{calc-note-threshold} determines how close (in cents) a frequency -needs to be to a note to be recognized as that note -(@pxref{Customizing Calc}). This variable has a default value of -@code{1}. For example, middle @var{C} is approximately -@expr{261.625565302 Hz}; this frequency is often shortened to -@expr{261.625 Hz}. Without @code{calc-note-threshold} (or a value of -@expr{0}), Calc would convert @code{261.625 Hz} to scientific pitch -notation @code{B_3 + 99.9962592773 cents}; with the default value of -@code{1}, Calc converts @code{261.625 Hz} to @code{C_4}. - - - -@node Store and Recall, Graphics, Units, Top -@chapter Storing and Recalling - -@noindent -Calculator variables are really just Lisp variables that contain numbers -or formulas in a form that Calc can understand. The commands in this -section allow you to manipulate variables conveniently. Commands related -to variables use the @kbd{s} prefix key. - -@menu -* Storing Variables:: -* Recalling Variables:: -* Operations on Variables:: -* Let Command:: -* Evaluates-To Operator:: -@end menu - -@node Storing Variables, Recalling Variables, Store and Recall, Store and Recall -@section Storing Variables - -@noindent -@kindex s s -@pindex calc-store -@cindex Storing variables -@cindex Quick variables -@vindex q0 -@vindex q9 -The @kbd{s s} (@code{calc-store}) command stores the value at the top of -the stack into a specified variable. It prompts you to enter the -name of the variable. If you press a single digit, the value is stored -immediately in one of the ``quick'' variables @code{q0} through -@code{q9}. Or you can enter any variable name. - -@kindex s t -@pindex calc-store-into -The @kbd{s s} command leaves the stored value on the stack. There is -also an @kbd{s t} (@code{calc-store-into}) command, which removes a -value from the stack and stores it in a variable. - -If the top of stack value is an equation @samp{a = 7} or assignment -@samp{a := 7} with a variable on the lefthand side, then Calc will -assign that variable with that value by default, i.e., if you type -@kbd{s s @key{RET}} or @kbd{s t @key{RET}}. In this example, the -value 7 would be stored in the variable @samp{a}. (If you do type -a variable name at the prompt, the top-of-stack value is stored in -its entirety, even if it is an equation: @samp{s s b @key{RET}} -with @samp{a := 7} on the stack stores @samp{a := 7} in @code{b}.) - -In fact, the top of stack value can be a vector of equations or -assignments with different variables on their lefthand sides; the -default will be to store all the variables with their corresponding -righthand sides simultaneously. - -It is also possible to type an equation or assignment directly at -the prompt for the @kbd{s s} or @kbd{s t} command: @kbd{s s foo = 7}. -In this case the expression to the right of the @kbd{=} or @kbd{:=} -symbol is evaluated as if by the @kbd{=} command, and that value is -stored in the variable. No value is taken from the stack; @kbd{s s} -and @kbd{s t} are equivalent when used in this way. - -@kindex s 0-9 -@kindex t 0-9 -The prefix keys @kbd{s} and @kbd{t} may be followed immediately by a -digit; @kbd{s 9} is equivalent to @kbd{s s 9}, and @kbd{t 9} is -equivalent to @kbd{s t 9}. (The @kbd{t} prefix is otherwise used -for trail and time/date commands.) - -@kindex s + -@kindex s - -@ignore -@mindex @idots -@end ignore -@kindex s * -@ignore -@mindex @null -@end ignore -@kindex s / -@ignore -@mindex @null -@end ignore -@kindex s ^ -@ignore -@mindex @null -@end ignore -@kindex s | -@ignore -@mindex @null -@end ignore -@kindex s n -@ignore -@mindex @null -@end ignore -@kindex s & -@ignore -@mindex @null -@end ignore -@kindex s [ -@ignore -@mindex @null -@end ignore -@kindex s ] -@pindex calc-store-plus -@pindex calc-store-minus -@pindex calc-store-times -@pindex calc-store-div -@pindex calc-store-power -@pindex calc-store-concat -@pindex calc-store-neg -@pindex calc-store-inv -@pindex calc-store-decr -@pindex calc-store-incr -There are also several ``arithmetic store'' commands. For example, -@kbd{s +} removes a value from the stack and adds it to the specified -variable. The other arithmetic stores are @kbd{s -}, @kbd{s *}, @kbd{s /}, -@kbd{s ^}, and @w{@kbd{s |}} (vector concatenation), plus @kbd{s n} and -@kbd{s &} which negate or invert the value in a variable, and @w{@kbd{s [}} -and @kbd{s ]} which decrease or increase a variable by one. - -All the arithmetic stores accept the Inverse prefix to reverse the -order of the operands. If @expr{v} represents the contents of the -variable, and @expr{a} is the value drawn from the stack, then regular -@w{@kbd{s -}} assigns -@texline @math{v \coloneq v - a}, -@infoline @expr{v := v - a}, -but @kbd{I s -} assigns -@texline @math{v \coloneq a - v}. -@infoline @expr{v := a - v}. -While @kbd{I s *} might seem pointless, it is -useful if matrix multiplication is involved. Actually, all the -arithmetic stores use formulas designed to behave usefully both -forwards and backwards: - -@example -@group -s + v := v + a v := a + v -s - v := v - a v := a - v -s * v := v * a v := a * v -s / v := v / a v := a / v -s ^ v := v ^ a v := a ^ v -s | v := v | a v := a | v -s n v := v / (-1) v := (-1) / v -s & v := v ^ (-1) v := (-1) ^ v -s [ v := v - 1 v := 1 - v -s ] v := v - (-1) v := (-1) - v -@end group -@end example - -In the last four cases, a numeric prefix argument will be used in -place of the number one. (For example, @kbd{M-2 s ]} increases -a variable by 2, and @kbd{M-2 I s ]} replaces a variable by -minus-two minus the variable. - -The first six arithmetic stores can also be typed @kbd{s t +}, @kbd{s t -}, -etc. The commands @kbd{s s +}, @kbd{s s -}, and so on are analogous -arithmetic stores that don't remove the value @expr{a} from the stack. - -All arithmetic stores report the new value of the variable in the -Trail for your information. They signal an error if the variable -previously had no stored value. If default simplifications have been -turned off, the arithmetic stores temporarily turn them on for numeric -arguments only (i.e., they temporarily do an @kbd{m N} command). -@xref{Simplification Modes}. Large vectors put in the trail by -these commands always use abbreviated (@kbd{t .}) mode. - -@kindex s m -@pindex calc-store-map -The @kbd{s m} command is a general way to adjust a variable's value -using any Calc function. It is a ``mapping'' command analogous to -@kbd{V M}, @kbd{V R}, etc. @xref{Reducing and Mapping}, to see -how to specify a function for a mapping command. Basically, -all you do is type the Calc command key that would invoke that -function normally. For example, @kbd{s m n} applies the @kbd{n} -key to negate the contents of the variable, so @kbd{s m n} is -equivalent to @kbd{s n}. Also, @kbd{s m Q} takes the square root -of the value stored in a variable, @kbd{s m v v} uses @kbd{v v} to -reverse the vector stored in the variable, and @kbd{s m H I S} -takes the hyperbolic arcsine of the variable contents. - -If the mapping function takes two or more arguments, the additional -arguments are taken from the stack; the old value of the variable -is provided as the first argument. Thus @kbd{s m -} with @expr{a} -on the stack computes @expr{v - a}, just like @kbd{s -}. With the -Inverse prefix, the variable's original value becomes the @emph{last} -argument instead of the first. Thus @kbd{I s m -} is also -equivalent to @kbd{I s -}. - -@kindex s x -@pindex calc-store-exchange -The @kbd{s x} (@code{calc-store-exchange}) command exchanges the value -of a variable with the value on the top of the stack. Naturally, the -variable must already have a stored value for this to work. - -You can type an equation or assignment at the @kbd{s x} prompt. The -command @kbd{s x a=6} takes no values from the stack; instead, it -pushes the old value of @samp{a} on the stack and stores @samp{a = 6}. - -@kindex s u -@pindex calc-unstore -@cindex Void variables -@cindex Un-storing variables -Until you store something in them, most variables are ``void,'' that is, -they contain no value at all. If they appear in an algebraic formula -they will be left alone even if you press @kbd{=} (@code{calc-evaluate}). -The @kbd{s u} (@code{calc-unstore}) command returns a variable to the -void state. - -@kindex s c -@pindex calc-copy-variable -The @kbd{s c} (@code{calc-copy-variable}) command copies the stored -value of one variable to another. One way it differs from a simple -@kbd{s r} followed by an @kbd{s t} (aside from saving keystrokes) is -that the value never goes on the stack and thus is never rounded, -evaluated, or simplified in any way; it is not even rounded down to the -current precision. - -The only variables with predefined values are the ``special constants'' -@code{pi}, @code{e}, @code{i}, @code{phi}, and @code{gamma}. You are free -to unstore these variables or to store new values into them if you like, -although some of the algebraic-manipulation functions may assume these -variables represent their standard values. Calc displays a warning if -you change the value of one of these variables, or of one of the other -special variables @code{inf}, @code{uinf}, and @code{nan} (which are -normally void). - -Note that @code{pi} doesn't actually have 3.14159265359 stored in it, -but rather a special magic value that evaluates to @cpi{} at the current -precision. Likewise @code{e}, @code{i}, and @code{phi} evaluate -according to the current precision or polar mode. If you recall a value -from @code{pi} and store it back, this magic property will be lost. The -magic property is preserved, however, when a variable is copied with -@kbd{s c}. - -@kindex s k -@pindex calc-copy-special-constant -If one of the ``special constants'' is redefined (or undefined) so that -it no longer has its magic property, the property can be restored with -@kbd{s k} (@code{calc-copy-special-constant}). This command will prompt -for a special constant and a variable to store it in, and so a special -constant can be stored in any variable. Here, the special constant that -you enter doesn't depend on the value of the corresponding variable; -@code{pi} will represent 3.14159@dots{} regardless of what is currently -stored in the Calc variable @code{pi}. If one of the other special -variables, @code{inf}, @code{uinf} or @code{nan}, is given a value, its -original behavior can be restored by voiding it with @kbd{s u}. - -@node Recalling Variables, Operations on Variables, Storing Variables, Store and Recall -@section Recalling Variables - -@noindent -@kindex s r -@pindex calc-recall -@cindex Recalling variables -The most straightforward way to extract the stored value from a variable -is to use the @kbd{s r} (@code{calc-recall}) command. This command prompts -for a variable name (similarly to @code{calc-store}), looks up the value -of the specified variable, and pushes that value onto the stack. It is -an error to try to recall a void variable. - -It is also possible to recall the value from a variable by evaluating a -formula containing that variable. For example, @kbd{' a @key{RET} =} is -the same as @kbd{s r a @key{RET}} except that if the variable is void, the -former will simply leave the formula @samp{a} on the stack whereas the -latter will produce an error message. - -@kindex r 0-9 -The @kbd{r} prefix may be followed by a digit, so that @kbd{r 9} is -equivalent to @kbd{s r 9}. - -@node Operations on Variables, Let Command, Recalling Variables, Store and Recall -@section Other Operations on Variables - -@noindent -@kindex s e -@pindex calc-edit-variable -The @kbd{s e} (@code{calc-edit-variable}) command edits the stored -value of a variable without ever putting that value on the stack -or simplifying or evaluating the value. It prompts for the name of -the variable to edit. If the variable has no stored value, the -editing buffer will start out empty. If the editing buffer is -empty when you press @kbd{C-c C-c} to finish, the variable will -be made void. @xref{Editing Stack Entries}, for a general -description of editing. - -The @kbd{s e} command is especially useful for creating and editing -rewrite rules which are stored in variables. Sometimes these rules -contain formulas which must not be evaluated until the rules are -actually used. (For example, they may refer to @samp{deriv(x,y)}, -where @code{x} will someday become some expression involving @code{y}; -if you let Calc evaluate the rule while you are defining it, Calc will -replace @samp{deriv(x,y)} with 0 because the formula @code{x} does -not itself refer to @code{y}.) By contrast, recalling the variable, -editing with @kbd{`}, and storing will evaluate the variable's value -as a side effect of putting the value on the stack. - -@kindex s A -@kindex s D -@ignore -@mindex @idots -@end ignore -@kindex s E -@ignore -@mindex @null -@end ignore -@kindex s F -@ignore -@mindex @null -@end ignore -@kindex s G -@ignore -@mindex @null -@end ignore -@kindex s H -@ignore -@mindex @null -@end ignore -@kindex s I -@ignore -@mindex @null -@end ignore -@kindex s L -@ignore -@mindex @null -@end ignore -@kindex s P -@ignore -@mindex @null -@end ignore -@kindex s R -@ignore -@mindex @null -@end ignore -@kindex s T -@ignore -@mindex @null -@end ignore -@kindex s U -@ignore -@mindex @null -@end ignore -@kindex s X -@pindex calc-store-AlgSimpRules -@pindex calc-store-Decls -@pindex calc-store-EvalRules -@pindex calc-store-FitRules -@pindex calc-store-GenCount -@pindex calc-store-Holidays -@pindex calc-store-IntegLimit -@pindex calc-store-LineStyles -@pindex calc-store-PointStyles -@pindex calc-store-PlotRejects -@pindex calc-store-TimeZone -@pindex calc-store-Units -@pindex calc-store-ExtSimpRules -There are several special-purpose variable-editing commands that -use the @kbd{s} prefix followed by a shifted letter: - -@table @kbd -@item s A -Edit @code{AlgSimpRules}. @xref{Algebraic Simplifications}. -@item s D -Edit @code{Decls}. @xref{Declarations}. -@item s E -Edit @code{EvalRules}. @xref{Basic Simplifications}. -@item s F -Edit @code{FitRules}. @xref{Curve Fitting}. -@item s G -Edit @code{GenCount}. @xref{Solving Equations}. -@item s H -Edit @code{Holidays}. @xref{Business Days}. -@item s I -Edit @code{IntegLimit}. @xref{Calculus}. -@item s L -Edit @code{LineStyles}. @xref{Graphics}. -@item s P -Edit @code{PointStyles}. @xref{Graphics}. -@item s R -Edit @code{PlotRejects}. @xref{Graphics}. -@item s T -Edit @code{TimeZone}. @xref{Time Zones}. -@item s U -Edit @code{Units}. @xref{User-Defined Units}. -@item s X -Edit @code{ExtSimpRules}. @xref{Unsafe Simplifications}. -@end table - -These commands are just versions of @kbd{s e} that use fixed variable -names rather than prompting for the variable name. - -@kindex s p -@pindex calc-permanent-variable -@cindex Storing variables -@cindex Permanent variables -@cindex Calc init file, variables -The @kbd{s p} (@code{calc-permanent-variable}) command saves a -variable's value permanently in your Calc init file (the file given by -the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}), so -that its value will still be available in future Emacs sessions. You -can re-execute @w{@kbd{s p}} later on to update the saved value, but the -only way to remove a saved variable is to edit your calc init file -by hand. (@xref{General Mode Commands}, for a way to tell Calc to -use a different file for the Calc init file.) - -If you do not specify the name of a variable to save (i.e., -@kbd{s p @key{RET}}), all Calc variables with defined values -are saved except for the special constants @code{pi}, @code{e}, -@code{i}, @code{phi}, and @code{gamma}; the variables @code{TimeZone} -and @code{PlotRejects}; -@code{FitRules}, @code{DistribRules}, and other built-in rewrite -rules; and @code{PlotData@var{n}} variables generated -by the graphics commands. (You can still save these variables by -explicitly naming them in an @kbd{s p} command.) - -@kindex s i -@pindex calc-insert-variables -The @kbd{s i} (@code{calc-insert-variables}) command writes -the values of all Calc variables into a specified buffer. -The variables are written with the prefix @code{var-} in the form of -Lisp @code{setq} commands -which store the values in string form. You can place these commands -in your Calc init file (or @file{.emacs}) if you wish, though in this case it -would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i} -omits the same set of variables as @w{@kbd{s p @key{RET}}}; the difference -is that @kbd{s i} will store the variables in any buffer, and it also -stores in a more human-readable format.) - -@node Let Command, Evaluates-To Operator, Operations on Variables, Store and Recall -@section The Let Command - -@noindent -@kindex s l -@pindex calc-let -@cindex Variables, temporary assignment -@cindex Temporary assignment to variables -If you have an expression like @samp{a+b^2} on the stack and you wish to -compute its value where @expr{b=3}, you can simply store 3 in @expr{b} and -then press @kbd{=} to reevaluate the formula. This has the side-effect -of leaving the stored value of 3 in @expr{b} for future operations. - -The @kbd{s l} (@code{calc-let}) command evaluates a formula under a -@emph{temporary} assignment of a variable. It stores the value on the -top of the stack into the specified variable, then evaluates the -second-to-top stack entry, then restores the original value (or lack of one) -in the variable. Thus after @kbd{'@w{ }a+b^2 @key{RET} 3 s l b @key{RET}}, -the stack will contain the formula @samp{a + 9}. The subsequent command -@kbd{@w{5 s l a} @key{RET}} will replace this formula with the number 14. -The variables @samp{a} and @samp{b} are not permanently affected in any way -by these commands. - -The value on the top of the stack may be an equation or assignment, or -a vector of equations or assignments, in which case the default will be -analogous to the case of @kbd{s t @key{RET}}. @xref{Storing Variables}. - -Also, you can answer the variable-name prompt with an equation or -assignment: @kbd{s l b=3 @key{RET}} is the same as storing 3 on the stack -and typing @kbd{s l b @key{RET}}. - -The @kbd{a b} (@code{calc-substitute}) command is another way to substitute -a variable with a value in a formula. It does an actual substitution -rather than temporarily assigning the variable and evaluating. For -example, letting @expr{n=2} in @samp{f(n pi)} with @kbd{a b} will -produce @samp{f(2 pi)}, whereas @kbd{s l} would give @samp{f(6.28)} -since the evaluation step will also evaluate @code{pi}. - -@node Evaluates-To Operator, , Let Command, Store and Recall -@section The Evaluates-To Operator - -@noindent -@tindex evalto -@tindex => -@cindex Evaluates-to operator -@cindex @samp{=>} operator -The special algebraic symbol @samp{=>} is known as the @dfn{evaluates-to -operator}. (It will show up as an @code{evalto} function call in -other language modes like Pascal and @LaTeX{}.) This is a binary -operator, that is, it has a lefthand and a righthand argument, -although it can be entered with the righthand argument omitted. - -A formula like @samp{@var{a} => @var{b}} is evaluated by Calc as -follows: First, @var{a} is not simplified or modified in any -way. The previous value of argument @var{b} is thrown away; the -formula @var{a} is then copied and evaluated as if by the @kbd{=} -command according to all current modes and stored variable values, -and the result is installed as the new value of @var{b}. - -For example, suppose you enter the algebraic formula @samp{2 + 3 => 17}. -The number 17 is ignored, and the lefthand argument is left in its -unevaluated form; the result is the formula @samp{2 + 3 => 5}. - -@kindex s = -@pindex calc-evalto -You can enter an @samp{=>} formula either directly using algebraic -entry (in which case the righthand side may be omitted since it is -going to be replaced right away anyhow), or by using the @kbd{s =} -(@code{calc-evalto}) command, which takes @var{a} from the stack -and replaces it with @samp{@var{a} => @var{b}}. - -Calc keeps track of all @samp{=>} operators on the stack, and -recomputes them whenever anything changes that might affect their -values, i.e., a mode setting or variable value. This occurs only -if the @samp{=>} operator is at the top level of the formula, or -if it is part of a top-level vector. In other words, pushing -@samp{2 + (a => 17)} will change the 17 to the actual value of -@samp{a} when you enter the formula, but the result will not be -dynamically updated when @samp{a} is changed later because the -@samp{=>} operator is buried inside a sum. However, a vector -of @samp{=>} operators will be recomputed, since it is convenient -to push a vector like @samp{[a =>, b =>, c =>]} on the stack to -make a concise display of all the variables in your problem. -(Another way to do this would be to use @samp{[a, b, c] =>}, -which provides a slightly different format of display. You -can use whichever you find easiest to read.) - -@kindex m C -@pindex calc-auto-recompute -The @kbd{m C} (@code{calc-auto-recompute}) command allows you to -turn this automatic recomputation on or off. If you turn -recomputation off, you must explicitly recompute an @samp{=>} -operator on the stack in one of the usual ways, such as by -pressing @kbd{=}. Turning recomputation off temporarily can save -a lot of time if you will be changing several modes or variables -before you look at the @samp{=>} entries again. - -Most commands are not especially useful with @samp{=>} operators -as arguments. For example, given @samp{x + 2 => 17}, it won't -work to type @kbd{1 +} to get @samp{x + 3 => 18}. If you want -to operate on the lefthand side of the @samp{=>} operator on -the top of the stack, type @kbd{j 1} (that's the digit ``one'') -to select the lefthand side, execute your commands, then type -@kbd{j u} to unselect. - -All current modes apply when an @samp{=>} operator is computed, -including the current simplification mode. Recall that the -formula @samp{arcsin(sin(x))} will not be handled by Calc's algebraic -simplifications, but Calc's unsafe simplifications will reduce it to -@samp{x}. If you enter @samp{arcsin(sin(x)) =>} normally, the result -will be @samp{arcsin(sin(x)) => arcsin(sin(x))}. If you change to -Extended Simplification mode, the result will be -@samp{arcsin(sin(x)) => x}. However, just pressing @kbd{a e} -once will have no effect on @samp{arcsin(sin(x)) => arcsin(sin(x))}, -because the righthand side depends only on the lefthand side -and the current mode settings, and the lefthand side is not -affected by commands like @kbd{a e}. - -The ``let'' command (@kbd{s l}) has an interesting interaction -with the @samp{=>} operator. The @kbd{s l} command evaluates the -second-to-top stack entry with the top stack entry supplying -a temporary value for a given variable. As you might expect, -if that stack entry is an @samp{=>} operator its righthand -side will temporarily show this value for the variable. In -fact, all @samp{=>}s on the stack will be updated if they refer -to that variable. But this change is temporary in the sense -that the next command that causes Calc to look at those stack -entries will make them revert to the old variable value. - -@smallexample -@group -2: a => a 2: a => 17 2: a => a -1: a + 1 => a + 1 1: a + 1 => 18 1: a + 1 => a + 1 - . . . - - 17 s l a @key{RET} p 8 @key{RET} -@end group -@end smallexample - -Here the @kbd{p 8} command changes the current precision, -thus causing the @samp{=>} forms to be recomputed after the -influence of the ``let'' is gone. The @kbd{d @key{SPC}} command -(@code{calc-refresh}) is a handy way to force the @samp{=>} -operators on the stack to be recomputed without any other -side effects. - -@kindex s : -@pindex calc-assign -@tindex assign -@tindex := -Embedded mode also uses @samp{=>} operators. In Embedded mode, -the lefthand side of an @samp{=>} operator can refer to variables -assigned elsewhere in the file by @samp{:=} operators. The -assignment operator @samp{a := 17} does not actually do anything -by itself. But Embedded mode recognizes it and marks it as a sort -of file-local definition of the variable. You can enter @samp{:=} -operators in Algebraic mode, or by using the @kbd{s :} -(@code{calc-assign}) [@code{assign}] command which takes a variable -and value from the stack and replaces them with an assignment. - -@xref{TeX and LaTeX Language Modes}, for the way @samp{=>} appears in -@TeX{} language output. The @dfn{eqn} mode gives similar -treatment to @samp{=>}. - -@node Graphics, Kill and Yank, Store and Recall, Top -@chapter Graphics - -@noindent -The commands for graphing data begin with the @kbd{g} prefix key. Calc -uses GNUPLOT 2.0 or later to do graphics. These commands will only work -if GNUPLOT is available on your system. (While GNUPLOT sounds like -a relative of GNU Emacs, it is actually completely unrelated. -However, it is free software. It can be obtained from -@samp{http://www.gnuplot.info}.) - -@vindex calc-gnuplot-name -If you have GNUPLOT installed on your system but Calc is unable to -find it, you may need to set the @code{calc-gnuplot-name} variable in -your Calc init file or @file{.emacs}. You may also need to set some -Lisp variables to show Calc how to run GNUPLOT on your system; these -are described under @kbd{g D} and @kbd{g O} below. If you are using -the X window system or MS-Windows, Calc will configure GNUPLOT for you -automatically. If you have GNUPLOT 3.0 or later and you are using a -Unix or GNU system without X, Calc will configure GNUPLOT to display -graphs using simple character graphics that will work on any -Posix-compatible terminal. - -@menu -* Basic Graphics:: -* Three Dimensional Graphics:: -* Managing Curves:: -* Graphics Options:: -* Devices:: -@end menu - -@node Basic Graphics, Three Dimensional Graphics, Graphics, Graphics -@section Basic Graphics - -@noindent -@kindex g f -@pindex calc-graph-fast -The easiest graphics command is @kbd{g f} (@code{calc-graph-fast}). -This command takes two vectors of equal length from the stack. -The vector at the top of the stack represents the ``y'' values of -the various data points. The vector in the second-to-top position -represents the corresponding ``x'' values. This command runs -GNUPLOT (if it has not already been started by previous graphing -commands) and displays the set of data points. The points will -be connected by lines, and there will also be some kind of symbol -to indicate the points themselves. - -The ``x'' entry may instead be an interval form, in which case suitable -``x'' values are interpolated between the minimum and maximum values of -the interval (whether the interval is open or closed is ignored). - -The ``x'' entry may also be a number, in which case Calc uses the -sequence of ``x'' values @expr{x}, @expr{x+1}, @expr{x+2}, etc. -(Generally the number 0 or 1 would be used for @expr{x} in this case.) - -The ``y'' entry may be any formula instead of a vector. Calc effectively -uses @kbd{N} (@code{calc-eval-num}) to evaluate variables in the formula; -the result of this must be a formula in a single (unassigned) variable. -The formula is plotted with this variable taking on the various ``x'' -values. Graphs of formulas by default use lines without symbols at the -computed data points. Note that if neither ``x'' nor ``y'' is a vector, -Calc guesses at a reasonable number of data points to use. See the -@kbd{g N} command below. (The ``x'' values must be either a vector -or an interval if ``y'' is a formula.) - -@ignore -@starindex -@end ignore -@tindex xy -If ``y'' is (or evaluates to) a formula of the form -@samp{xy(@var{x}, @var{y})} then the result is a -parametric plot. The two arguments of the fictitious @code{xy} function -are used as the ``x'' and ``y'' coordinates of the curve, respectively. -In this case the ``x'' vector or interval you specified is not directly -visible in the graph. For example, if ``x'' is the interval @samp{[0..360]} -and ``y'' is the formula @samp{xy(sin(t), cos(t))}, the resulting graph -will be a circle. - -Also, ``x'' and ``y'' may each be variable names, in which case Calc -looks for suitable vectors, intervals, or formulas stored in those -variables. - -The ``x'' and ``y'' values for the data points (as pulled from the vectors, -calculated from the formulas, or interpolated from the intervals) should -be real numbers (integers, fractions, or floats). One exception to this -is that the ``y'' entry can consist of a vector of numbers combined with -error forms, in which case the points will be plotted with the -appropriate error bars. Other than this, if either the ``x'' -value or the ``y'' value of a given data point is not a real number, that -data point will be omitted from the graph. The points on either side -of the invalid point will @emph{not} be connected by a line. - -See the documentation for @kbd{g a} below for a description of the way -numeric prefix arguments affect @kbd{g f}. - -@cindex @code{PlotRejects} variable -@vindex PlotRejects -If you store an empty vector in the variable @code{PlotRejects} -(i.e., @kbd{[ ] s t PlotRejects}), Calc will append information to -this vector for every data point which was rejected because its -``x'' or ``y'' values were not real numbers. The result will be -a matrix where each row holds the curve number, data point number, -``x'' value, and ``y'' value for a rejected data point. -@xref{Evaluates-To Operator}, for a handy way to keep tabs on the -current value of @code{PlotRejects}. @xref{Operations on Variables}, -for the @kbd{s R} command which is another easy way to examine -@code{PlotRejects}. - -@kindex g c -@pindex calc-graph-clear -To clear the graphics display, type @kbd{g c} (@code{calc-graph-clear}). -If the GNUPLOT output device is an X window, the window will go away. -Effects on other kinds of output devices will vary. You don't need -to use @kbd{g c} if you don't want to---if you give another @kbd{g f} -or @kbd{g p} command later on, it will reuse the existing graphics -window if there is one. - -@node Three Dimensional Graphics, Managing Curves, Basic Graphics, Graphics -@section Three-Dimensional Graphics - -@kindex g F -@pindex calc-graph-fast-3d -The @kbd{g F} (@code{calc-graph-fast-3d}) command makes a three-dimensional -graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0, -you will see a GNUPLOT error message if you try this command. - -The @kbd{g F} command takes three values from the stack, called ``x'', -``y'', and ``z'', respectively. As was the case for 2D graphs, there -are several options for these values. - -In the first case, ``x'' and ``y'' are each vectors (not necessarily of -the same length); either or both may instead be interval forms. The -``z'' value must be a matrix with the same number of rows as elements -in ``x'', and the same number of columns as elements in ``y''. The -result is a surface plot where -@texline @math{z_{ij}} -@infoline @expr{z_ij} -is the height of the point -at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will -be displayed from a certain default viewpoint; you can change this -viewpoint by adding a @samp{set view} to the @file{*Gnuplot Commands*} -buffer as described later. See the GNUPLOT documentation for a -description of the @samp{set view} command. - -Each point in the matrix will be displayed as a dot in the graph, -and these points will be connected by a grid of lines (@dfn{isolines}). - -In the second case, ``x'', ``y'', and ``z'' are all vectors of equal -length. The resulting graph displays a 3D line instead of a surface, -where the coordinates of points along the line are successive triplets -of values from the input vectors. - -In the third case, ``x'' and ``y'' are vectors or interval forms, and -``z'' is any formula involving two variables (not counting variables -with assigned values). These variables are sorted into alphabetical -order; the first takes on values from ``x'' and the second takes on -values from ``y'' to form a matrix of results that are graphed as a -3D surface. - -@ignore -@starindex -@end ignore -@tindex xyz -If the ``z'' formula evaluates to a call to the fictitious function -@samp{xyz(@var{x}, @var{y}, @var{z})}, then the result is a -``parametric surface.'' In this case, the axes of the graph are -taken from the @var{x} and @var{y} values in these calls, and the -``x'' and ``y'' values from the input vectors or intervals are used only -to specify the range of inputs to the formula. For example, plotting -@samp{[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))} -will draw a sphere. (Since the default resolution for 3D plots is -5 steps in each of ``x'' and ``y'', this will draw a very crude -sphere. You could use the @kbd{g N} command, described below, to -increase this resolution, or specify the ``x'' and ``y'' values as -vectors with more than 5 elements. - -It is also possible to have a function in a regular @kbd{g f} plot -evaluate to an @code{xyz} call. Since @kbd{g f} plots a line, not -a surface, the result will be a 3D parametric line. For example, -@samp{[[0..720], xyz(sin(x), cos(x), x)]} will plot two turns of a -helix (a three-dimensional spiral). - -As for @kbd{g f}, each of ``x'', ``y'', and ``z'' may instead be -variables containing the relevant data. - -@node Managing Curves, Graphics Options, Three Dimensional Graphics, Graphics -@section Managing Curves - -@noindent -The @kbd{g f} command is really shorthand for the following commands: -@kbd{C-u g d g a g p}. Likewise, @w{@kbd{g F}} is shorthand for -@kbd{C-u g d g A g p}. You can gain more control over your graph -by using these commands directly. - -@kindex g a -@pindex calc-graph-add -The @kbd{g a} (@code{calc-graph-add}) command adds the ``curve'' -represented by the two values on the top of the stack to the current -graph. You can have any number of curves in the same graph. When -you give the @kbd{g p} command, all the curves will be drawn superimposed -on the same axes. - -The @kbd{g a} command (and many others that affect the current graph) -will cause a special buffer, @file{*Gnuplot Commands*}, to be displayed -in another window. This buffer is a template of the commands that will -be sent to GNUPLOT when it is time to draw the graph. The first -@kbd{g a} command adds a @code{plot} command to this buffer. Succeeding -@kbd{g a} commands add extra curves onto that @code{plot} command. -Other graph-related commands put other GNUPLOT commands into this -buffer. In normal usage you never need to work with this buffer -directly, but you can if you wish. The only constraint is that there -must be only one @code{plot} command, and it must be the last command -in the buffer. If you want to save and later restore a complete graph -configuration, you can use regular Emacs commands to save and restore -the contents of the @file{*Gnuplot Commands*} buffer. - -@vindex PlotData1 -@vindex PlotData2 -If the values on the stack are not variable names, @kbd{g a} will invent -variable names for them (of the form @samp{PlotData@var{n}}) and store -the values in those variables. The ``x'' and ``y'' variables are what -go into the @code{plot} command in the template. If you add a curve -that uses a certain variable and then later change that variable, you -can replot the graph without having to delete and re-add the curve. -That's because the variable name, not the vector, interval or formula -itself, is what was added by @kbd{g a}. - -A numeric prefix argument on @kbd{g a} or @kbd{g f} changes the way -stack entries are interpreted as curves. With a positive prefix -argument @expr{n}, the top @expr{n} stack entries are ``y'' values -for @expr{n} different curves which share a common ``x'' value in -the @expr{n+1}st stack entry. (Thus @kbd{g a} with no prefix -argument is equivalent to @kbd{C-u 1 g a}.) - -A prefix of zero or plain @kbd{C-u} means to take two stack entries, -``x'' and ``y'' as usual, but to interpret ``y'' as a vector of -``y'' values for several curves that share a common ``x''. - -A negative prefix argument tells Calc to read @expr{n} vectors from -the stack; each vector @expr{[x, y]} describes an independent curve. -This is the only form of @kbd{g a} that creates several curves at once -that don't have common ``x'' values. (Of course, the range of ``x'' -values covered by all the curves ought to be roughly the same if -they are to look nice on the same graph.) - -For example, to plot -@texline @math{\sin n x} -@infoline @expr{sin(n x)} -for integers @expr{n} -from 1 to 5, you could use @kbd{v x} to create a vector of integers -(@expr{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)} -across this vector. The resulting vector of formulas is suitable -for use as the ``y'' argument to a @kbd{C-u g a} or @kbd{C-u g f} -command. - -@kindex g A -@pindex calc-graph-add-3d -The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve -to the graph. It is not valid to intermix 2D and 3D curves in a -single graph. This command takes three arguments, ``x'', ``y'', -and ``z'', from the stack. With a positive prefix @expr{n}, it -takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n} -separate ``z''s). With a zero prefix, it takes three stack entries -but the ``z'' entry is a vector of curve values. With a negative -prefix @expr{-n}, it takes @expr{n} vectors of the form @expr{[x, y, z]}. -The @kbd{g A} command works by adding a @code{splot} (surface-plot) -command to the @file{*Gnuplot Commands*} buffer. - -(Although @kbd{g a} adds a 2D @code{plot} command to the -@file{*Gnuplot Commands*} buffer, Calc changes this to @code{splot} -before sending it to GNUPLOT if it notices that the data points are -evaluating to @code{xyz} calls. It will not work to mix 2D and 3D -@kbd{g a} curves in a single graph, although Calc does not currently -check for this.) - -@kindex g d -@pindex calc-graph-delete -The @kbd{g d} (@code{calc-graph-delete}) command deletes the most -recently added curve from the graph. It has no effect if there are -no curves in the graph. With a numeric prefix argument of any kind, -it deletes all of the curves from the graph. - -@kindex g H -@pindex calc-graph-hide -The @kbd{g H} (@code{calc-graph-hide}) command ``hides'' or ``unhides'' -the most recently added curve. A hidden curve will not appear in -the actual plot, but information about it such as its name and line and -point styles will be retained. - -@kindex g j -@pindex calc-graph-juggle -The @kbd{g j} (@code{calc-graph-juggle}) command moves the curve -at the end of the list (the ``most recently added curve'') to the -front of the list. The next-most-recent curve is thus exposed for -@w{@kbd{g d}} or similar commands to use. With @kbd{g j} you can work -with any curve in the graph even though curve-related commands only -affect the last curve in the list. - -@kindex g p -@pindex calc-graph-plot -The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw -the graph described in the @file{*Gnuplot Commands*} buffer. Any -GNUPLOT parameters which are not defined by commands in this buffer -are reset to their default values. The variables named in the @code{plot} -command are written to a temporary data file and the variable names -are then replaced by the file name in the template. The resulting -plotting commands are fed to the GNUPLOT program. See the documentation -for the GNUPLOT program for more specific information. All temporary -files are removed when Emacs or GNUPLOT exits. - -If you give a formula for ``y'', Calc will remember all the values that -it calculates for the formula so that later plots can reuse these values. -Calc throws out these saved values when you change any circumstances -that may affect the data, such as switching from Degrees to Radians -mode, or changing the value of a parameter in the formula. You can -force Calc to recompute the data from scratch by giving a negative -numeric prefix argument to @kbd{g p}. - -Calc uses a fairly rough step size when graphing formulas over intervals. -This is to ensure quick response. You can ``refine'' a plot by giving -a positive numeric prefix argument to @kbd{g p}. Calc goes through -the data points it has computed and saved from previous plots of the -function, and computes and inserts a new data point midway between -each of the existing points. You can refine a plot any number of times, -but beware that the amount of calculation involved doubles each time. - -Calc does not remember computed values for 3D graphs. This means the -numerix prefix argument, if any, to @kbd{g p} is effectively ignored if -the current graph is three-dimensional. - -@kindex g P -@pindex calc-graph-print -The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p}, -except that it sends the output to a printer instead of to the -screen. More precisely, @kbd{g p} looks for @samp{set terminal} -or @samp{set output} commands in the @file{*Gnuplot Commands*} buffer; -lacking these it uses the default settings. However, @kbd{g P} -ignores @samp{set terminal} and @samp{set output} commands and -uses a different set of default values. All of these values are -controlled by the @kbd{g D} and @kbd{g O} commands discussed below. -Provided everything is set up properly, @kbd{g p} will plot to -the screen unless you have specified otherwise and @kbd{g P} will -always plot to the printer. - -@node Graphics Options, Devices, Managing Curves, Graphics -@section Graphics Options - -@noindent -@kindex g g -@pindex calc-graph-grid -The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid'' -on and off. It is off by default; tick marks appear only at the -edges of the graph. With the grid turned on, dotted lines appear -across the graph at each tick mark. Note that this command only -changes the setting in @file{*Gnuplot Commands*}; to see the effects -of the change you must give another @kbd{g p} command. - -@kindex g b -@pindex calc-graph-border -The @kbd{g b} (@code{calc-graph-border}) command turns the border -(the box that surrounds the graph) on and off. It is on by default. -This command will only work with GNUPLOT 3.0 and later versions. - -@kindex g k -@pindex calc-graph-key -The @kbd{g k} (@code{calc-graph-key}) command turns the ``key'' -on and off. The key is a chart in the corner of the graph that -shows the correspondence between curves and line styles. It is -off by default, and is only really useful if you have several -curves on the same graph. - -@kindex g N -@pindex calc-graph-num-points -The @kbd{g N} (@code{calc-graph-num-points}) command allows you -to select the number of data points in the graph. This only affects -curves where neither ``x'' nor ``y'' is specified as a vector. -Enter a blank line to revert to the default value (initially 15). -With no prefix argument, this command affects only the current graph. -With a positive prefix argument this command changes or, if you enter -a blank line, displays the default number of points used for all -graphs created by @kbd{g a} that don't specify the resolution explicitly. -With a negative prefix argument, this command changes or displays -the default value (initially 5) used for 3D graphs created by @kbd{g A}. -Note that a 3D setting of 5 means that a total of @expr{5^2 = 25} points -will be computed for the surface. - -Data values in the graph of a function are normally computed to a -precision of five digits, regardless of the current precision at the -time. This is usually more than adequate, but there are cases where -it will not be. For example, plotting @expr{1 + x} with @expr{x} in the -interval @samp{[0 ..@: 1e-6]} will round all the data points down -to 1.0! Putting the command @samp{set precision @var{n}} in the -@file{*Gnuplot Commands*} buffer will cause the data to be computed -at precision @var{n} instead of 5. Since this is such a rare case, -there is no keystroke-based command to set the precision. - -@kindex g h -@pindex calc-graph-header -The @kbd{g h} (@code{calc-graph-header}) command sets the title -for the graph. This will show up centered above the graph. -The default title is blank (no title). - -@kindex g n -@pindex calc-graph-name -The @kbd{g n} (@code{calc-graph-name}) command sets the title of an -individual curve. Like the other curve-manipulating commands, it -affects the most recently added curve, i.e., the last curve on the -list in the @file{*Gnuplot Commands*} buffer. To set the title of -the other curves you must first juggle them to the end of the list -with @kbd{g j}, or edit the @file{*Gnuplot Commands*} buffer by hand. -Curve titles appear in the key; if the key is turned off they are -not used. - -@kindex g t -@kindex g T -@pindex calc-graph-title-x -@pindex calc-graph-title-y -The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T} -(@code{calc-graph-title-y}) commands set the titles on the ``x'' -and ``y'' axes, respectively. These titles appear next to the -tick marks on the left and bottom edges of the graph, respectively. -Calc does not have commands to control the tick marks themselves, -but you can edit them into the @file{*Gnuplot Commands*} buffer if -you wish. See the GNUPLOT documentation for details. - -@kindex g r -@kindex g R -@pindex calc-graph-range-x -@pindex calc-graph-range-y -The @kbd{g r} (@code{calc-graph-range-x}) and @kbd{g R} -(@code{calc-graph-range-y}) commands set the range of values on the -``x'' and ``y'' axes, respectively. You are prompted to enter a -suitable range. This should be either a pair of numbers of the -form, @samp{@var{min}:@var{max}}, or a blank line to revert to the -default behavior of setting the range based on the range of values -in the data, or @samp{$} to take the range from the top of the stack. -Ranges on the stack can be represented as either interval forms or -vectors: @samp{[@var{min} ..@: @var{max}]} or @samp{[@var{min}, @var{max}]}. - -@kindex g l -@kindex g L -@pindex calc-graph-log-x -@pindex calc-graph-log-y -The @kbd{g l} (@code{calc-graph-log-x}) and @kbd{g L} (@code{calc-graph-log-y}) -commands allow you to set either or both of the axes of the graph to -be logarithmic instead of linear. - -@kindex g C-l -@kindex g C-r -@kindex g C-t -@pindex calc-graph-log-z -@pindex calc-graph-range-z -@pindex calc-graph-title-z -For 3D plots, @kbd{g C-t}, @kbd{g C-r}, and @kbd{g C-l} (those are -letters with the Control key held down) are the corresponding commands -for the ``z'' axis. - -@kindex g z -@kindex g Z -@pindex calc-graph-zero-x -@pindex calc-graph-zero-y -The @kbd{g z} (@code{calc-graph-zero-x}) and @kbd{g Z} -(@code{calc-graph-zero-y}) commands control whether a dotted line is -drawn to indicate the ``x'' and/or ``y'' zero axes. (These are the same -dotted lines that would be drawn there anyway if you used @kbd{g g} to -turn the ``grid'' feature on.) Zero-axis lines are on by default, and -may be turned off only in GNUPLOT 3.0 and later versions. They are -not available for 3D plots. - -@kindex g s -@pindex calc-graph-line-style -The @kbd{g s} (@code{calc-graph-line-style}) command turns the connecting -lines on or off for the most recently added curve, and optionally selects -the style of lines to be used for that curve. Plain @kbd{g s} simply -toggles the lines on and off. With a numeric prefix argument, @kbd{g s} -turns lines on and sets a particular line style. Line style numbers -start at one and their meanings vary depending on the output device. -GNUPLOT guarantees that there will be at least six different line styles -available for any device. - -@kindex g S -@pindex calc-graph-point-style -The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns -the symbols at the data points on or off, or sets the point style. -If you turn both lines and points off, the data points will show as -tiny dots. If the ``y'' values being plotted contain error forms and -the connecting lines are turned off, then this command will also turn -the error bars on or off. - -@cindex @code{LineStyles} variable -@cindex @code{PointStyles} variable -@vindex LineStyles -@vindex PointStyles -Another way to specify curve styles is with the @code{LineStyles} and -@code{PointStyles} variables. These variables initially have no stored -values, but if you store a vector of integers in one of these variables, -the @kbd{g a} and @kbd{g f} commands will use those style numbers -instead of the defaults for new curves that are added to the graph. -An entry should be a positive integer for a specific style, or 0 to let -the style be chosen automatically, or @mathit{-1} to turn off lines or points -altogether. If there are more curves than elements in the vector, the -last few curves will continue to have the default styles. Of course, -you can later use @kbd{g s} and @kbd{g S} to change any of these styles. - -For example, @kbd{'[2 -1 3] @key{RET} s t LineStyles} causes the first curve -to have lines in style number 2, the second curve to have no connecting -lines, and the third curve to have lines in style 3. Point styles will -still be assigned automatically, but you could store another vector in -@code{PointStyles} to define them, too. - -@node Devices, , Graphics Options, Graphics -@section Graphical Devices - -@noindent -@kindex g D -@pindex calc-graph-device -The @kbd{g D} (@code{calc-graph-device}) command sets the device name -(or ``terminal name'' in GNUPLOT lingo) to be used by @kbd{g p} commands -on this graph. It does not affect the permanent default device name. -If you enter a blank name, the device name reverts to the default. -Enter @samp{?} to see a list of supported devices. - -With a positive numeric prefix argument, @kbd{g D} instead sets -the default device name, used by all plots in the future which do -not override it with a plain @kbd{g D} command. If you enter a -blank line this command shows you the current default. The special -name @code{default} signifies that Calc should choose @code{x11} if -the X window system is in use (as indicated by the presence of a -@code{DISPLAY} environment variable), @code{windows} on MS-Windows, or -otherwise @code{dumb} under GNUPLOT 3.0 and later, or -@code{postscript} under GNUPLOT 2.0. This is the initial default -value. - -The @code{dumb} device is an interface to ``dumb terminals,'' i.e., -terminals with no special graphics facilities. It writes a crude -picture of the graph composed of characters like @code{-} and @code{|} -to a buffer called @file{*Gnuplot Trail*}, which Calc then displays. -The graph is made the same size as the Emacs screen, which on most -dumb terminals will be -@texline @math{80\times24} -@infoline 80x24 -characters. The graph is displayed in -an Emacs ``recursive edit''; type @kbd{q} or @kbd{C-c C-c} to exit -the recursive edit and return to Calc. Note that the @code{dumb} -device is present only in GNUPLOT 3.0 and later versions. - -The word @code{dumb} may be followed by two numbers separated by -spaces. These are the desired width and height of the graph in -characters. Also, the device name @code{big} is like @code{dumb} -but creates a graph four times the width and height of the Emacs -screen. You will then have to scroll around to view the entire -graph. In the @file{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL}, -@kbd{<}, and @kbd{>} are defined to scroll by one screenful in each -of the four directions. - -With a negative numeric prefix argument, @kbd{g D} sets or displays -the device name used by @kbd{g P} (@code{calc-graph-print}). This -is initially @code{postscript}. If you don't have a PostScript -printer, you may decide once again to use @code{dumb} to create a -plot on any text-only printer. - -@kindex g O -@pindex calc-graph-output -The @kbd{g O} (@code{calc-graph-output}) command sets the name of the -output file used by GNUPLOT@. For some devices, notably @code{x11} and -@code{windows}, there is no output file and this information is not -used. Many other ``devices'' are really file formats like -@code{postscript}; in these cases the output in the desired format -goes into the file you name with @kbd{g O}. Type @kbd{g O stdout -@key{RET}} to set GNUPLOT to write to its standard output stream, -i.e., to @file{*Gnuplot Trail*}. This is the default setting. - -Another special output name is @code{tty}, which means that GNUPLOT -is going to write graphics commands directly to its standard output, -which you wish Emacs to pass through to your terminal. Tektronix -graphics terminals, among other devices, operate this way. Calc does -this by telling GNUPLOT to write to a temporary file, then running a -sub-shell executing the command @samp{cat tempfile >/dev/tty}. On -typical Unix systems, this will copy the temporary file directly to -the terminal, bypassing Emacs entirely. You will have to type @kbd{C-l} -to Emacs afterwards to refresh the screen. - -Once again, @kbd{g O} with a positive or negative prefix argument -sets the default or printer output file names, respectively. In each -case you can specify @code{auto}, which causes Calc to invent a temporary -file name for each @kbd{g p} (or @kbd{g P}) command. This temporary file -will be deleted once it has been displayed or printed. If the output file -name is not @code{auto}, the file is not automatically deleted. - -The default and printer devices and output files can be saved -permanently by the @kbd{m m} (@code{calc-save-modes}) command. The -default number of data points (see @kbd{g N}) and the X geometry -(see @kbd{g X}) are also saved. Other graph information is @emph{not} -saved; you can save a graph's configuration simply by saving the contents -of the @file{*Gnuplot Commands*} buffer. - -@vindex calc-gnuplot-plot-command -@vindex calc-gnuplot-default-device -@vindex calc-gnuplot-default-output -@vindex calc-gnuplot-print-command -@vindex calc-gnuplot-print-device -@vindex calc-gnuplot-print-output -You may wish to configure the default and -printer devices and output files for the whole system. The relevant -Lisp variables are @code{calc-gnuplot-default-device} and @code{-output}, -and @code{calc-gnuplot-print-device} and @code{-output}. The output -file names must be either strings as described above, or Lisp -expressions which are evaluated on the fly to get the output file names. - -Other important Lisp variables are @code{calc-gnuplot-plot-command} and -@code{calc-gnuplot-print-command}, which give the system commands to -display or print the output of GNUPLOT, respectively. These may be -@code{nil} if no command is necessary, or strings which can include -@samp{%s} to signify the name of the file to be displayed or printed. -Or, these variables may contain Lisp expressions which are evaluated -to display or print the output. These variables are customizable -(@pxref{Customizing Calc}). - -@kindex g x -@pindex calc-graph-display -The @kbd{g x} (@code{calc-graph-display}) command lets you specify -on which X window system display your graphs should be drawn. Enter -a blank line to see the current display name. This command has no -effect unless the current device is @code{x11}. - -@kindex g X -@pindex calc-graph-geometry -The @kbd{g X} (@code{calc-graph-geometry}) command is a similar -command for specifying the position and size of the X window. -The normal value is @code{default}, which generally means your -window manager will let you place the window interactively. -Entering @samp{800x500+0+0} would create an 800-by-500 pixel -window in the upper-left corner of the screen. This command has no -effect if the current device is @code{windows}. - -The buffer called @file{*Gnuplot Trail*} holds a transcript of the -session with GNUPLOT@. This shows the commands Calc has ``typed'' to -GNUPLOT and the responses it has received. Calc tries to notice when an -error message has appeared here and display the buffer for you when -this happens. You can check this buffer yourself if you suspect -something has gone wrong@footnote{ -On MS-Windows, due to the peculiarities of how the Windows version of -GNUPLOT (called @command{wgnuplot}) works, the GNUPLOT responses are -not communicated back to Calc. Instead, you need to look them up in -the GNUPLOT command window that is displayed as in normal interactive -usage of GNUPLOT. -}. - -@kindex g C -@pindex calc-graph-command -The @kbd{g C} (@code{calc-graph-command}) command prompts you to -enter any line of text, then simply sends that line to the current -GNUPLOT process. The @file{*Gnuplot Trail*} buffer looks deceptively -like a Shell buffer but you can't type commands in it yourself. -Instead, you must use @kbd{g C} for this purpose. - -@kindex g v -@kindex g V -@pindex calc-graph-view-commands -@pindex calc-graph-view-trail -The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V} -(@code{calc-graph-view-trail}) commands display the @file{*Gnuplot Commands*} -and @file{*Gnuplot Trail*} buffers, respectively, in another window. -This happens automatically when Calc thinks there is something you -will want to see in either of these buffers. If you type @kbd{g v} -or @kbd{g V} when the relevant buffer is already displayed, the -buffer is hidden again. (Note that on MS-Windows, the @file{*Gnuplot -Trail*} buffer will usually show nothing of interest, because -GNUPLOT's responses are not communicated back to Calc.) - -One reason to use @kbd{g v} is to add your own commands to the -@file{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use -@kbd{C-x o} to switch into that window. For example, GNUPLOT has -@samp{set label} and @samp{set arrow} commands that allow you to -annotate your plots. Since Calc doesn't understand these commands, -you have to add them to the @file{*Gnuplot Commands*} buffer -yourself, then use @w{@kbd{g p}} to replot using these new commands. Note -that your commands must appear @emph{before} the @code{plot} command. -To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}. -You may have to type @kbd{g C @key{RET}} a few times to clear the -``press return for more'' or ``subtopic of @dots{}'' requests. -Note that Calc always sends commands (like @samp{set nolabel}) to -reset all plotting parameters to the defaults before each plot, so -to delete a label all you need to do is delete the @samp{set label} -line you added (or comment it out with @samp{#}) and then replot -with @kbd{g p}. - -@kindex g q -@pindex calc-graph-quit -You can use @kbd{g q} (@code{calc-graph-quit}) to kill the GNUPLOT -process that is running. The next graphing command you give will -start a fresh GNUPLOT process. The word @samp{Graph} appears in -the Calc window's mode line whenever a GNUPLOT process is currently -running. The GNUPLOT process is automatically killed when you -exit Emacs if you haven't killed it manually by then. - -@kindex g K -@pindex calc-graph-kill -The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q} -except that it also views the @file{*Gnuplot Trail*} buffer so that -you can see the process being killed. This is better if you are -killing GNUPLOT because you think it has gotten stuck. - -@node Kill and Yank, Keypad Mode, Graphics, Top -@chapter Kill and Yank Functions - -@noindent -The commands in this chapter move information between the Calculator and -other Emacs editing buffers. - -In many cases Embedded mode is an easier and more natural way to -work with Calc from a regular editing buffer. @xref{Embedded Mode}. - -@menu -* Killing From Stack:: -* Yanking Into Stack:: -* Saving Into Registers:: -* Inserting From Registers:: -* Grabbing From Buffers:: -* Yanking Into Buffers:: -* X Cut and Paste:: -@end menu - -@node Killing From Stack, Yanking Into Stack, Kill and Yank, Kill and Yank -@section Killing from the Stack - -@noindent -@kindex C-k -@pindex calc-kill -@kindex M-k -@pindex calc-copy-as-kill -@kindex C-w -@pindex calc-kill-region -@kindex M-w -@pindex calc-copy-region-as-kill -@kindex M-C-w -@cindex Kill ring -@dfn{Kill} commands are Emacs commands that insert text into the ``kill -ring,'' from which it can later be ``yanked'' by a @kbd{C-y} command. -Three common kill commands in normal Emacs are @kbd{C-k}, which kills -one line, @kbd{C-w}, which kills the region between mark and point, and -@kbd{M-w}, which puts the region into the kill ring without actually -deleting it. All of these commands work in the Calculator, too, -although in the Calculator they operate on whole stack entries, so they -``round up'' the specified region to encompass full lines. (To copy -only parts of lines, the @kbd{M-C-w} command in the Calculator will copy -the region to the kill ring without any ``rounding up'', just like the -@kbd{M-w} command in normal Emacs.) Also, @kbd{M-k} has been provided -to complete the set; it puts the current line into the kill ring without -deleting anything. - -The kill commands are unusual in that they pay attention to the location -of the cursor in the Calculator buffer. If the cursor is on or below -the bottom line, the kill commands operate on the top of the stack. -Otherwise, they operate on whatever stack element the cursor is on. The -text is copied into the kill ring exactly as it appears on the screen, -including line numbers if they are enabled. - -A numeric prefix argument to @kbd{C-k} or @kbd{M-k} affects the number -of lines killed. A positive argument kills the current line and @expr{n-1} -lines below it. A negative argument kills the @expr{-n} lines above the -current line. Again this mirrors the behavior of the standard Emacs -@kbd{C-k} command. Although a whole line is always deleted, @kbd{C-k} -with no argument copies only the number itself into the kill ring, whereas -@kbd{C-k} with a prefix argument of 1 copies the number with its trailing -newline. - -@node Yanking Into Stack, Saving Into Registers, Killing From Stack, Kill and Yank -@section Yanking into the Stack - -@noindent -@kindex C-y -@pindex calc-yank -The @kbd{C-y} command yanks the most recently killed text back into the -Calculator. It pushes this value onto the top of the stack regardless of -the cursor position. In general it re-parses the killed text as a number -or formula (or a list of these separated by commas or newlines). However if -the thing being yanked is something that was just killed from the Calculator -itself, its full internal structure is yanked. For example, if you have -set the floating-point display mode to show only four significant digits, -then killing and re-yanking 3.14159 (which displays as 3.142) will yank the -full 3.14159, even though yanking it into any other buffer would yank the -number in its displayed form, 3.142. (Since the default display modes -show all objects to their full precision, this feature normally makes no -difference.) - -@node Saving Into Registers, Inserting From Registers, Yanking Into Stack, Kill and Yank -@section Saving into Registers - -@noindent -@kindex r s -@pindex calc-copy-to-register -@pindex calc-prepend-to-register -@pindex calc-append-to-register -@cindex Registers -An alternative to killing and yanking stack entries is using -registers in Calc. Saving stack entries in registers is like -saving text in normal Emacs registers; although, like Calc's kill -commands, register commands always operate on whole stack -entries. - -Registers in Calc are places to store stack entries for later use; -each register is indexed by a single character. To store the current -region (rounded up, of course, to include full stack entries) into a -register, use the command @kbd{r s} (@code{calc-copy-to-register}). -You will then be prompted for a register to use, the next character -you type will be the index for the register. To store the region in -register @var{r}, the full command will be @kbd{r s @var{r}}. With an -argument, @kbd{C-u r s @var{r}}, the region being copied to the -register will be deleted from the Calc buffer. - -It is possible to add additional stack entries to a register. The -command @kbd{M-x calc-append-to-register} will prompt for a register, -then add the stack entries in the region to the end of the register -contents. The command @kbd{M-x calc-prepend-to-register} will -similarly prompt for a register and add the stack entries in the -region to the beginning of the register contents. Both commands take -@kbd{C-u} arguments, which will cause the region to be deleted after being -added to the register. - -@node Inserting From Registers, Grabbing From Buffers, Saving Into Registers, Kill and Yank -@section Inserting from Registers -@noindent -@kindex r i -@pindex calc-insert-register -The command @kbd{r i} (@code{calc-insert-register}) will prompt for a -register, then insert the contents of that register into the -Calculator. If the contents of the register were placed there from -within Calc, then the full internal structure of the contents will be -inserted into the Calculator, otherwise whatever text is in the -register is reparsed and then inserted into the Calculator. - -@node Grabbing From Buffers, Yanking Into Buffers, Inserting From Registers, Kill and Yank -@section Grabbing from Other Buffers - -@noindent -@kindex C-x * g -@pindex calc-grab-region -The @kbd{C-x * g} (@code{calc-grab-region}) command takes the text between -point and mark in the current buffer and attempts to parse it as a -vector of values. Basically, it wraps the text in vector brackets -@samp{[ ]} unless the text already is enclosed in vector brackets, -then reads the text as if it were an algebraic entry. The contents -of the vector may be numbers, formulas, or any other Calc objects. -If the @kbd{C-x * g} command works successfully, it does an automatic -@kbd{C-x * c} to enter the Calculator buffer. - -A numeric prefix argument grabs the specified number of lines around -point, ignoring the mark. A positive prefix grabs from point to the -@expr{n}th following newline (so that @kbd{M-1 C-x * g} grabs from point -to the end of the current line); a negative prefix grabs from point -back to the @expr{n+1}st preceding newline. In these cases the text -that is grabbed is exactly the same as the text that @kbd{C-k} would -delete given that prefix argument. - -A prefix of zero grabs the current line; point may be anywhere on the -line. - -A plain @kbd{C-u} prefix interprets the region between point and mark -as a single number or formula rather than a vector. For example, -@kbd{C-x * g} on the text @samp{2 a b} produces the vector of three -values @samp{[2, a, b]}, but @kbd{C-u C-x * g} on the same region -reads a formula which is a product of three things: @samp{2 a b}. -(The text @samp{a + b}, on the other hand, will be grabbed as a -vector of one element by plain @kbd{C-x * g} because the interpretation -@samp{[a, +, b]} would be a syntax error.) - -If a different language has been specified (@pxref{Language Modes}), -the grabbed text will be interpreted according to that language. - -@kindex C-x * r -@pindex calc-grab-rectangle -The @kbd{C-x * r} (@code{calc-grab-rectangle}) command takes the text between -point and mark and attempts to parse it as a matrix. If point and mark -are both in the leftmost column, the lines in between are parsed in their -entirety. Otherwise, point and mark define the corners of a rectangle -whose contents are parsed. - -Each line of the grabbed area becomes a row of the matrix. The result -will actually be a vector of vectors, which Calc will treat as a matrix -only if every row contains the same number of values. - -If a line contains a portion surrounded by square brackets (or curly -braces), that portion is interpreted as a vector which becomes a row -of the matrix. Any text surrounding the bracketed portion on the line -is ignored. - -Otherwise, the entire line is interpreted as a row vector as if it -were surrounded by square brackets. Leading line numbers (in the -format used in the Calc stack buffer) are ignored. If you wish to -force this interpretation (even if the line contains bracketed -portions), give a negative numeric prefix argument to the -@kbd{C-x * r} command. - -If you give a numeric prefix argument of zero or plain @kbd{C-u}, each -line is instead interpreted as a single formula which is converted into -a one-element vector. Thus the result of @kbd{C-u C-x * r} will be a -one-column matrix. For example, suppose one line of the data is the -expression @samp{2 a}. A plain @w{@kbd{C-x * r}} will interpret this as -@samp{[2 a]}, which in turn is read as a two-element vector that forms -one row of the matrix. But a @kbd{C-u C-x * r} will interpret this row -as @samp{[2*a]}. - -If you give a positive numeric prefix argument @var{n}, then each line -will be split up into columns of width @var{n}; each column is parsed -separately as a matrix element. If a line contained -@w{@samp{2 +/- 3 4 +/- 5}}, then grabbing with a prefix argument of 8 -would correctly split the line into two error forms. - -@xref{Matrix Functions}, to see how to pull the matrix apart into its -constituent rows and columns. (If it is a -@texline @math{1\times1} -@infoline 1x1 -matrix, just hit @kbd{v u} (@code{calc-unpack}) twice.) - -@kindex C-x * : -@kindex C-x * _ -@pindex calc-grab-sum-across -@pindex calc-grab-sum-down -@cindex Summing rows and columns of data -The @kbd{C-x * :} (@code{calc-grab-sum-down}) command is a handy way to -grab a rectangle of data and sum its columns. It is equivalent to -typing @kbd{C-x * r}, followed by @kbd{V R : +} (the vector reduction -command that sums the columns of a matrix; @pxref{Reducing}). The -result of the command will be a vector of numbers, one for each column -in the input data. The @kbd{C-x * _} (@code{calc-grab-sum-across}) command -similarly grabs a rectangle and sums its rows by executing @w{@kbd{V R _ +}}. - -As well as being more convenient, @kbd{C-x * :} and @kbd{C-x * _} are also -much faster because they don't actually place the grabbed vector on -the stack. In a @kbd{C-x * r V R : +} sequence, formatting the vector -for display on the stack takes a large fraction of the total time -(unless you have planned ahead and used @kbd{v .} and @kbd{t .} modes). - -For example, suppose we have a column of numbers in a file which we -wish to sum. Go to one corner of the column and press @kbd{C-@@} to -set the mark; go to the other corner and type @kbd{C-x * :}. Since there -is only one column, the result will be a vector of one number, the sum. -(You can type @kbd{v u} to unpack this vector into a plain number if -you want to do further arithmetic with it.) - -To compute the product of the column of numbers, we would have to do -it ``by hand'' since there's no special grab-and-multiply command. -Use @kbd{C-x * r} to grab the column of numbers into the calculator in -the form of a column matrix. The statistics command @kbd{u *} is a -handy way to find the product of a vector or matrix of numbers. -@xref{Statistical Operations}. Another approach would be to use -an explicit column reduction command, @kbd{V R : *}. - -@node Yanking Into Buffers, X Cut and Paste, Grabbing From Buffers, Kill and Yank -@section Yanking into Other Buffers - -@noindent -@kindex y -@pindex calc-copy-to-buffer -The plain @kbd{y} (@code{calc-copy-to-buffer}) command inserts the number -at the top of the stack into the most recently used normal editing buffer. -(More specifically, this is the most recently used buffer which is displayed -in a window and whose name does not begin with @samp{*}. If there is no -such buffer, this is the most recently used buffer except for Calculator -and Calc Trail buffers.) The number is inserted exactly as it appears and -without a newline. (If line-numbering is enabled, the line number is -normally not included.) The number is @emph{not} removed from the stack. - -With a prefix argument, @kbd{y} inserts several numbers, one per line. -A positive argument inserts the specified number of values from the top -of the stack. A negative argument inserts the @expr{n}th value from the -top of the stack. An argument of zero inserts the entire stack. Note -that @kbd{y} with an argument of 1 is slightly different from @kbd{y} -with no argument; the former always copies full lines, whereas the -latter strips off the trailing newline. - -With a lone @kbd{C-u} as a prefix argument, @kbd{y} @emph{replaces} the -region in the other buffer with the yanked text, then quits the -Calculator, leaving you in that buffer. A typical use would be to use -@kbd{C-x * g} to read a region of data into the Calculator, operate on the -data to produce a new matrix, then type @kbd{C-u y} to replace the -original data with the new data. One might wish to alter the matrix -display style (@pxref{Vector and Matrix Formats}) or change the current -display language (@pxref{Language Modes}) before doing this. Also, note -that this command replaces a linear region of text (as grabbed by -@kbd{C-x * g}), not a rectangle (as grabbed by @kbd{C-x * r}). - -If the editing buffer is in overwrite (as opposed to insert) mode, -and the @kbd{C-u} prefix was not used, then the yanked number will -overwrite the characters following point rather than being inserted -before those characters. The usual conventions of overwrite mode -are observed; for example, characters will be inserted at the end of -a line rather than overflowing onto the next line. Yanking a multi-line -object such as a matrix in overwrite mode overwrites the next @var{n} -lines in the buffer, lengthening or shortening each line as necessary. -Finally, if the thing being yanked is a simple integer or floating-point -number (like @samp{-1.2345e-3}) and the characters following point also -make up such a number, then Calc will replace that number with the new -number, lengthening or shortening as necessary. The concept of -``overwrite mode'' has thus been generalized from overwriting characters -to overwriting one complete number with another. - -@kindex C-x * y -The @kbd{C-x * y} key sequence is equivalent to @kbd{y} except that -it can be typed anywhere, not just in Calc. This provides an easy -way to guarantee that Calc knows which editing buffer you want to use! - -@node X Cut and Paste, , Yanking Into Buffers, Kill and Yank -@section X Cut and Paste - -@noindent -If you are using Emacs with the X window system, there is an easier -way to move small amounts of data into and out of the calculator: -Use the mouse-oriented cut and paste facilities of X. - -The default bindings for a three-button mouse cause the left button -to move the Emacs cursor to the given place, the right button to -select the text between the cursor and the clicked location, and -the middle button to yank the selection into the buffer at the -clicked location. So, if you have a Calc window and an editing -window on your Emacs screen, you can use left-click/right-click -to select a number, vector, or formula from one window, then -middle-click to paste that value into the other window. When you -paste text into the Calc window, Calc interprets it as an algebraic -entry. It doesn't matter where you click in the Calc window; the -new value is always pushed onto the top of the stack. - -The @code{xterm} program that is typically used for general-purpose -shell windows in X interprets the mouse buttons in the same way. -So you can use the mouse to move data between Calc and any other -Unix program. One nice feature of @code{xterm} is that a double -left-click selects one word, and a triple left-click selects a -whole line. So you can usually transfer a single number into Calc -just by double-clicking on it in the shell, then middle-clicking -in the Calc window. - -@node Keypad Mode, Embedded Mode, Kill and Yank, Top -@chapter Keypad Mode - -@noindent -@kindex C-x * k -@pindex calc-keypad -The @kbd{C-x * k} (@code{calc-keypad}) command starts the Calculator -and displays a picture of a calculator-style keypad. If you are using -the X window system, you can click on any of the ``keys'' in the -keypad using the left mouse button to operate the calculator. -The original window remains the selected window; in Keypad mode -you can type in your file while simultaneously performing -calculations with the mouse. - -@pindex full-calc-keypad -If you have used @kbd{C-x * b} first, @kbd{C-x * k} instead invokes -the @code{full-calc-keypad} command, which takes over the whole -Emacs screen and displays the keypad, the Calc stack, and the Calc -trail all at once. This mode would normally be used when running -Calc standalone (@pxref{Standalone Operation}). - -If you aren't using the X window system, you must switch into -the @file{*Calc Keypad*} window, place the cursor on the desired -``key,'' and type @key{SPC} or @key{RET}. If you think this -is easier than using Calc normally, go right ahead. - -Calc commands are more or less the same in Keypad mode. Certain -keypad keys differ slightly from the corresponding normal Calc -keystrokes; all such deviations are described below. - -Keypad mode includes many more commands than will fit on the keypad -at once. Click the right mouse button [@code{calc-keypad-menu}] -to switch to the next menu. The bottom five rows of the keypad -stay the same; the top three rows change to a new set of commands. -To return to earlier menus, click the middle mouse button -[@code{calc-keypad-menu-back}] or simply advance through the menus -until you wrap around. Typing @key{TAB} inside the keypad window -is equivalent to clicking the right mouse button there. - -You can always click the @key{EXEC} button and type any normal -Calc key sequence. This is equivalent to switching into the -Calc buffer, typing the keys, then switching back to your -original buffer. - -@menu -* Keypad Main Menu:: -* Keypad Functions Menu:: -* Keypad Binary Menu:: -* Keypad Vectors Menu:: -* Keypad Modes Menu:: -@end menu - -@node Keypad Main Menu, Keypad Functions Menu, Keypad Mode, Keypad Mode -@section Main Menu - -@smallexample -@group -|----+----+--Calc---+----+----1 -|FLR |CEIL|RND |TRNC|CLN2|FLT | -|----+----+----+----+----+----| -| LN |EXP | |ABS |IDIV|MOD | -|----+----+----+----+----+----| -|SIN |COS |TAN |SQRT|y^x |1/x | -|----+----+----+----+----+----| -| ENTER |+/- |EEX |UNDO| <- | -|-----+---+-+--+--+-+---++----| -| INV | 7 | 8 | 9 | / | -|-----+-----+-----+-----+-----| -| HYP | 4 | 5 | 6 | * | -|-----+-----+-----+-----+-----| -|EXEC | 1 | 2 | 3 | - | -|-----+-----+-----+-----+-----| -| OFF | 0 | . | PI | + | -|-----+-----+-----+-----+-----+ -@end group -@end smallexample - -@noindent -This is the menu that appears the first time you start Keypad mode. -It will show up in a vertical window on the right side of your screen. -Above this menu is the traditional Calc stack display. On a 24-line -screen you will be able to see the top three stack entries. - -The ten digit keys, decimal point, and @key{EEX} key are used for -entering numbers in the obvious way. @key{EEX} begins entry of an -exponent in scientific notation. Just as with regular Calc, the -number is pushed onto the stack as soon as you press @key{ENTER} -or any other function key. - -The @key{+/-} key corresponds to normal Calc's @kbd{n} key. During -numeric entry it changes the sign of the number or of the exponent. -At other times it changes the sign of the number on the top of the -stack. - -The @key{INV} and @key{HYP} keys modify other keys. As well as -having the effects described elsewhere in this manual, Keypad mode -defines several other ``inverse'' operations. These are described -below and in the following sections. - -The @key{ENTER} key finishes the current numeric entry, or otherwise -duplicates the top entry on the stack. - -The @key{UNDO} key undoes the most recent Calc operation. -@kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is -``last arguments'' (@kbd{M-@key{RET}}). - -The @key{<-} key acts as a ``backspace'' during numeric entry. -At other times it removes the top stack entry. @kbd{INV <-} -clears the entire stack. @kbd{HYP <-} takes an integer from -the stack, then removes that many additional stack elements. - -The @key{EXEC} key prompts you to enter any keystroke sequence -that would normally work in Calc mode. This can include a -numeric prefix if you wish. It is also possible simply to -switch into the Calc window and type commands in it; there is -nothing ``magic'' about this window when Keypad mode is active. - -The other keys in this display perform their obvious calculator -functions. @key{CLN2} rounds the top-of-stack by temporarily -reducing the precision by 2 digits. @key{FLT} converts an -integer or fraction on the top of the stack to floating-point. - -The @key{INV} and @key{HYP} keys combined with several of these keys -give you access to some common functions even if the appropriate menu -is not displayed. Obviously you don't need to learn these keys -unless you find yourself wasting time switching among the menus. - -@table @kbd -@item INV +/- -is the same as @key{1/x}. -@item INV + -is the same as @key{SQRT}. -@item INV - -is the same as @key{CONJ}. -@item INV * -is the same as @key{y^x}. -@item INV / -is the same as @key{INV y^x} (the @expr{x}th root of @expr{y}). -@item HYP/INV 1 -are the same as @key{SIN} / @kbd{INV SIN}. -@item HYP/INV 2 -are the same as @key{COS} / @kbd{INV COS}. -@item HYP/INV 3 -are the same as @key{TAN} / @kbd{INV TAN}. -@item INV/HYP 4 -are the same as @key{LN} / @kbd{HYP LN}. -@item INV/HYP 5 -are the same as @key{EXP} / @kbd{HYP EXP}. -@item INV 6 -is the same as @key{ABS}. -@item INV 7 -is the same as @key{RND} (@code{calc-round}). -@item INV 8 -is the same as @key{CLN2}. -@item INV 9 -is the same as @key{FLT} (@code{calc-float}). -@item INV 0 -is the same as @key{IMAG}. -@item INV . -is the same as @key{PREC}. -@item INV ENTER -is the same as @key{SWAP}. -@item HYP ENTER -is the same as @key{RLL3}. -@item INV HYP ENTER -is the same as @key{OVER}. -@item HYP +/- -packs the top two stack entries as an error form. -@item HYP EEX -packs the top two stack entries as a modulo form. -@item INV EEX -creates an interval form; this removes an integer which is one -of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed -by the two limits of the interval. -@end table - -The @kbd{OFF} key turns Calc off; typing @kbd{C-x * k} or @kbd{C-x * *} -again has the same effect. This is analogous to typing @kbd{q} or -hitting @kbd{C-x * c} again in the normal calculator. If Calc is -running standalone (the @code{full-calc-keypad} command appeared in the -command line that started Emacs), then @kbd{OFF} is replaced with -@kbd{EXIT}; clicking on this actually exits Emacs itself. - -@node Keypad Functions Menu, Keypad Binary Menu, Keypad Main Menu, Keypad Mode -@section Functions Menu - -@smallexample -@group -|----+----+----+----+----+----2 -|IGAM|BETA|IBET|ERF |BESJ|BESY| -|----+----+----+----+----+----| -|IMAG|CONJ| RE |ATN2|RAND|RAGN| -|----+----+----+----+----+----| -|GCD |FACT|DFCT|BNOM|PERM|NXTP| -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -This menu provides various operations from the @kbd{f} and @kbd{k} -prefix keys. - -@key{IMAG} multiplies the number on the stack by the imaginary -number @expr{i = (0, 1)}. - -@key{RE} extracts the real part a complex number. @kbd{INV RE} -extracts the imaginary part. - -@key{RAND} takes a number from the top of the stack and computes -a random number greater than or equal to zero but less than that -number. (@xref{Random Numbers}.) @key{RAGN} is the ``random -again'' command; it computes another random number using the -same limit as last time. - -@key{INV GCD} computes the LCM (least common multiple) function. - -@key{INV FACT} is the gamma function. -@texline @math{\Gamma(x) = (x-1)!}. -@infoline @expr{gamma(x) = (x-1)!}. - -@key{PERM} is the number-of-permutations function, which is on the -@kbd{H k c} key in normal Calc. - -@key{NXTP} finds the next prime after a number. @kbd{INV NXTP} -finds the previous prime. - -@node Keypad Binary Menu, Keypad Vectors Menu, Keypad Functions Menu, Keypad Mode -@section Binary Menu - -@smallexample -@group -|----+----+----+----+----+----3 -|AND | OR |XOR |NOT |LSH |RSH | -|----+----+----+----+----+----| -|DEC |HEX |OCT |BIN |WSIZ|ARSH| -|----+----+----+----+----+----| -| A | B | C | D | E | F | -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -The keys in this menu perform operations on binary integers. -Note that both logical and arithmetic right-shifts are provided. -@key{INV LSH} rotates one bit to the left. - -The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}. -The ``clip'' function (normally on @w{@kbd{b c}}) is on @key{INV NOT}. - -The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the -current radix for display and entry of numbers: Decimal, hexadecimal, -octal, or binary. The six letter keys @key{A} through @key{F} are used -for entering hexadecimal numbers. - -The @key{WSIZ} key displays the current word size for binary operations -and allows you to enter a new word size. You can respond to the prompt -using either the keyboard or the digits and @key{ENTER} from the keypad. -The initial word size is 32 bits. - -@node Keypad Vectors Menu, Keypad Modes Menu, Keypad Binary Menu, Keypad Mode -@section Vectors Menu - -@smallexample -@group -|----+----+----+----+----+----4 -|SUM |PROD|MAX |MAP*|MAP^|MAP$| -|----+----+----+----+----+----| -|MINV|MDET|MTRN|IDNT|CRSS|"x" | -|----+----+----+----+----+----| -|PACK|UNPK|INDX|BLD |LEN |... | -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -The keys in this menu operate on vectors and matrices. - -@key{PACK} removes an integer @var{n} from the top of the stack; -the next @var{n} stack elements are removed and packed into a vector, -which is replaced onto the stack. Thus the sequence -@kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector -@samp{[1, 3, 5]} onto the stack. To enter a matrix, build each row -on the stack as a vector, then use a final @key{PACK} to collect the -rows into a matrix. - -@key{UNPK} unpacks the vector on the stack, pushing each of its -components separately. - -@key{INDX} removes an integer @var{n}, then builds a vector of -integers from 1 to @var{n}. @kbd{INV INDX} takes three numbers -from the stack: The vector size @var{n}, the starting number, -and the increment. @kbd{BLD} takes an integer @var{n} and any -value @var{x} and builds a vector of @var{n} copies of @var{x}. - -@key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n} -identity matrix. - -@key{LEN} replaces a vector by its length, an integer. - -@key{...} turns on or off ``abbreviated'' display mode for large vectors. - -@key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix -inverse, determinant, and transpose, and vector cross product. - -@key{SUM} replaces a vector by the sum of its elements. It is -equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}). -@key{PROD} computes the product of the elements of a vector, and -@key{MAX} computes the maximum of all the elements of a vector. - -@key{INV SUM} computes the alternating sum of the first element -minus the second, plus the third, minus the fourth, and so on. -@key{INV MAX} computes the minimum of the vector elements. - -@key{HYP SUM} computes the mean of the vector elements. -@key{HYP PROD} computes the sample standard deviation. -@key{HYP MAX} computes the median. - -@key{MAP*} multiplies two vectors elementwise. It is equivalent -to the @kbd{V M *} command. @key{MAP^} computes powers elementwise. -The arguments must be vectors of equal length, or one must be a vector -and the other must be a plain number. For example, @kbd{2 MAP^} squares -all the elements of a vector. - -@key{MAP$} maps the formula on the top of the stack across the -vector in the second-to-top position. If the formula contains -several variables, Calc takes that many vectors starting at the -second-to-top position and matches them to the variables in -alphabetical order. The result is a vector of the same size as -the input vectors, whose elements are the formula evaluated with -the variables set to the various sets of numbers in those vectors. -For example, you could simulate @key{MAP^} using @key{MAP$} with -the formula @samp{x^y}. - -The @kbd{"x"} key pushes the variable name @expr{x} onto the -stack. To build the formula @expr{x^2 + 6}, you would use the -key sequence @kbd{"x" 2 y^x 6 +}. This formula would then be -suitable for use with the @key{MAP$} key described above. -With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the -@kbd{"x"} key pushes the variable names @expr{y}, @expr{z}, and -@expr{t}, respectively. - -@node Keypad Modes Menu, , Keypad Vectors Menu, Keypad Mode -@section Modes Menu - -@smallexample -@group -|----+----+----+----+----+----5 -|FLT |FIX |SCI |ENG |GRP | | -|----+----+----+----+----+----| -|RAD |DEG |FRAC|POLR|SYMB|PREC| -|----+----+----+----+----+----| -|SWAP|RLL3|RLL4|OVER|STO |RCL | -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -The keys in this menu manipulate modes, variables, and the stack. - -The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select -floating-point, fixed-point, scientific, or engineering notation. -@key{FIX} displays two digits after the decimal by default; the -others display full precision. With the @key{INV} prefix, these -keys pop a number-of-digits argument from the stack. - -The @key{GRP} key turns grouping of digits with commas on or off. -@kbd{INV GRP} enables grouping to the right of the decimal point as -well as to the left. - -The @key{RAD} and @key{DEG} keys switch between radians and degrees -for trigonometric functions. - -The @key{FRAC} key turns Fraction mode on or off. This affects -whether commands like @kbd{/} with integer arguments produce -fractional or floating-point results. - -The @key{POLR} key turns Polar mode on or off, determining whether -polar or rectangular complex numbers are used by default. - -The @key{SYMB} key turns Symbolic mode on or off, in which -operations that would produce inexact floating-point results -are left unevaluated as algebraic formulas. - -The @key{PREC} key selects the current precision. Answer with -the keyboard or with the keypad digit and @key{ENTER} keys. - -The @key{SWAP} key exchanges the top two stack elements. -The @key{RLL3} key rotates the top three stack elements upwards. -The @key{RLL4} key rotates the top four stack elements upwards. -The @key{OVER} key duplicates the second-to-top stack element. - -The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and -@kbd{s r} in regular Calc. @xref{Store and Recall}. Click the -@key{STO} or @key{RCL} key, then one of the ten digits. (Named -variables are not available in Keypad mode.) You can also use, -for example, @kbd{STO + 3} to add to register 3. - -@node Embedded Mode, Programming, Keypad Mode, Top -@chapter Embedded Mode - -@noindent -Embedded mode in Calc provides an alternative to copying numbers -and formulas back and forth between editing buffers and the Calc -stack. In Embedded mode, your editing buffer becomes temporarily -linked to the stack and this copying is taken care of automatically. - -@menu -* Basic Embedded Mode:: -* More About Embedded Mode:: -* Assignments in Embedded Mode:: -* Mode Settings in Embedded Mode:: -* Customizing Embedded Mode:: -@end menu - -@node Basic Embedded Mode, More About Embedded Mode, Embedded Mode, Embedded Mode -@section Basic Embedded Mode - -@noindent -@kindex C-x * e -@pindex calc-embedded -To enter Embedded mode, position the Emacs point (cursor) on a -formula in any buffer and press @kbd{C-x * e} (@code{calc-embedded}). -Note that @kbd{C-x * e} is not to be used in the Calc stack buffer -like most Calc commands, but rather in regular editing buffers that -are visiting your own files. - -Calc will try to guess an appropriate language based on the major mode -of the editing buffer. (@xref{Language Modes}.) If the current buffer is -in @code{latex-mode}, for example, Calc will set its language to @LaTeX{}. -Similarly, Calc will use @TeX{} language for @code{tex-mode}, -@code{plain-tex-mode} and @code{context-mode}, C language for -@code{c-mode} and @code{c++-mode}, FORTRAN language for -@code{fortran-mode} and @code{f90-mode}, Pascal for @code{pascal-mode}, -and eqn for @code{nroff-mode} (@pxref{Customizing Calc}). -These can be overridden with Calc's mode -changing commands (@pxref{Mode Settings in Embedded Mode}). If no -suitable language is available, Calc will continue with its current language. - -Calc normally scans backward and forward in the buffer for the -nearest opening and closing @dfn{formula delimiters}. The simplest -delimiters are blank lines. Other delimiters that Embedded mode -understands are: - -@enumerate -@item -The @TeX{} and @LaTeX{} math delimiters @samp{$ $}, @samp{$$ $$}, -@samp{\[ \]}, and @samp{\( \)}; -@item -Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); -@item -Lines beginning with @samp{@@} (Texinfo delimiters). -@item -Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); -@item -Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. -@end enumerate - -@xref{Customizing Embedded Mode}, to see how to make Calc recognize -your own favorite delimiters. Delimiters like @samp{$ $} can appear -on their own separate lines or in-line with the formula. - -If you give a positive or negative numeric prefix argument, Calc -instead uses the current point as one end of the formula, and includes -that many lines forward or backward (respectively, including the current -line). Explicit delimiters are not necessary in this case. - -With a prefix argument of zero, Calc uses the current region (delimited -by point and mark) instead of formula delimiters. With a prefix -argument of @kbd{C-u} only, Calc uses the current line as the formula. - -@kindex C-x * w -@pindex calc-embedded-word -The @kbd{C-x * w} (@code{calc-embedded-word}) command will start Embedded -mode on the current ``word''; in this case Calc will scan for the first -non-numeric character (i.e., the first character that is not a digit, -sign, decimal point, or upper- or lower-case @samp{e}) forward and -backward to delimit the formula. - -When you enable Embedded mode for a formula, Calc reads the text -between the delimiters and tries to interpret it as a Calc formula. -Calc can generally identify @TeX{} formulas and -Big-style formulas even if the language mode is wrong. If Calc -can't make sense of the formula, it beeps and refuses to enter -Embedded mode. But if the current language is wrong, Calc can -sometimes parse the formula successfully (but incorrectly); -for example, the C expression @samp{atan(a[1])} can be parsed -in Normal language mode, but the @code{atan} won't correspond to -the built-in @code{arctan} function, and the @samp{a[1]} will be -interpreted as @samp{a} times the vector @samp{[1]}! - -If you press @kbd{C-x * e} or @kbd{C-x * w} to activate an embedded -formula which is blank, say with the cursor on the space between -the two delimiters @samp{$ $}, Calc will immediately prompt for -an algebraic entry. - -Only one formula in one buffer can be enabled at a time. If you -move to another area of the current buffer and give Calc commands, -Calc turns Embedded mode off for the old formula and then tries -to restart Embedded mode at the new position. Other buffers are -not affected by Embedded mode. - -When Embedded mode begins, Calc pushes the current formula onto -the stack. No Calc stack window is created; however, Calc copies -the top-of-stack position into the original buffer at all times. -You can create a Calc window by hand with @kbd{C-x * o} if you -find you need to see the entire stack. - -For example, typing @kbd{C-x * e} while somewhere in the formula -@samp{n>2} in the following line enables Embedded mode on that -inequality: - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$. -@end example - -@noindent -The formula @expr{n>2} will be pushed onto the Calc stack, and -the top of stack will be copied back into the editing buffer. -This means that spaces will appear around the @samp{>} symbol -to match Calc's usual display style: - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$. -@end example - -@noindent -No spaces have appeared around the @samp{+} sign because it's -in a different formula, one which we have not yet touched with -Embedded mode. - -Now that Embedded mode is enabled, keys you type in this buffer -are interpreted as Calc commands. At this point we might use -the ``commute'' command @kbd{j C} to reverse the inequality. -This is a selection-based command for which we first need to -move the cursor onto the operator (@samp{>} in this case) that -needs to be commuted. - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$. -@end example - -The @kbd{C-x * o} command is a useful way to open a Calc window -without actually selecting that window. Giving this command -verifies that @samp{2 < n} is also on the Calc stack. Typing -@kbd{17 @key{RET}} would produce: - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $17$. -@end example - -@noindent -with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB} -at this point will exchange the two stack values and restore -@samp{2 < n} to the embedded formula. Even though you can't -normally see the stack in Embedded mode, it is still there and -it still operates in the same way. But, as with old-fashioned -RPN calculators, you can only see the value at the top of the -stack at any given time (unless you use @kbd{C-x * o}). - -Typing @kbd{C-x * e} again turns Embedded mode off. The Calc -window reveals that the formula @w{@samp{2 < n}} is automatically -removed from the stack, but the @samp{17} is not. Entering -Embedded mode always pushes one thing onto the stack, and -leaving Embedded mode always removes one thing. Anything else -that happens on the stack is entirely your business as far as -Embedded mode is concerned. - -If you press @kbd{C-x * e} in the wrong place by accident, it is -possible that Calc will be able to parse the nearby text as a -formula and will mangle that text in an attempt to redisplay it -``properly'' in the current language mode. If this happens, -press @kbd{C-x * e} again to exit Embedded mode, then give the -regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put -the text back the way it was before Calc edited it. Note that Calc's -own Undo command (typed before you turn Embedded mode back off) -will not do you any good, because as far as Calc is concerned -you haven't done anything with this formula yet. - -@node More About Embedded Mode, Assignments in Embedded Mode, Basic Embedded Mode, Embedded Mode -@section More About Embedded Mode - -@noindent -When Embedded mode ``activates'' a formula, i.e., when it examines -the formula for the first time since the buffer was created or -loaded, Calc tries to sense the language in which the formula was -written. If the formula contains any @LaTeX{}-like @samp{\} sequences, -it is parsed (i.e., read) in @LaTeX{} mode. If the formula appears to -be written in multi-line Big mode, it is parsed in Big mode. Otherwise, -it is parsed according to the current language mode. - -Note that Calc does not change the current language mode according -the formula it reads in. Even though it can read a @LaTeX{} formula when -not in @LaTeX{} mode, it will immediately rewrite this formula using -whatever language mode is in effect. - -@tex -\bigskip -@end tex - -@kindex d p -@pindex calc-show-plain -Calc's parser is unable to read certain kinds of formulas. For -example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can -specify matrix display styles which the parser is unable to -recognize as matrices. The @kbd{d p} (@code{calc-show-plain}) -command turns on a mode in which a ``plain'' version of a -formula is placed in front of the fully-formatted version. -When Calc reads a formula that has such a plain version in -front, it reads the plain version and ignores the formatted -version. - -Plain formulas are preceded and followed by @samp{%%%} signs -by default. This notation has the advantage that the @samp{%} -character begins a comment in @TeX{} and @LaTeX{}, so if your formula is -embedded in a @TeX{} or @LaTeX{} document its plain version will be -invisible in the final printed copy. Certain major modes have different -delimiters to ensure that the ``plain'' version will be -in a comment for those modes, also. -See @ref{Customizing Embedded Mode} to see how to change the ``plain'' -formula delimiters. - -There are several notations which Calc's parser for ``big'' -formatted formulas can't yet recognize. In particular, it can't -read the large symbols for @code{sum}, @code{prod}, and @code{integ}, -and it can't handle @samp{=>} with the righthand argument omitted. -Also, Calc won't recognize special formats you have defined with -the @kbd{Z C} command (@pxref{User-Defined Compositions}). In -these cases it is important to use ``plain'' mode to make sure -Calc will be able to read your formula later. - -Another example where ``plain'' mode is important is if you have -specified a float mode with few digits of precision. Normally -any digits that are computed but not displayed will simply be -lost when you save and re-load your embedded buffer, but ``plain'' -mode allows you to make sure that the complete number is present -in the file as well as the rounded-down number. - -@tex -\bigskip -@end tex - -Embedded buffers remember active formulas for as long as they -exist in Emacs memory. Suppose you have an embedded formula -which is @cpi{} to the normal 12 decimal places, and then -type @w{@kbd{C-u 5 d n}} to display only five decimal places. -If you then type @kbd{d n}, all 12 places reappear because the -full number is still there on the Calc stack. More surprisingly, -even if you exit Embedded mode and later re-enter it for that -formula, typing @kbd{d n} will restore all 12 places because -each buffer remembers all its active formulas. However, if you -save the buffer in a file and reload it in a new Emacs session, -all non-displayed digits will have been lost unless you used -``plain'' mode. - -@tex -\bigskip -@end tex - -In some applications of Embedded mode, you will want to have a -sequence of copies of a formula that show its evolution as you -work on it. For example, you might want to have a sequence -like this in your file (elaborating here on the example from -the ``Getting Started'' chapter): - -@smallexample -The derivative of - - ln(ln(x)) - -is - - @r{(the derivative of }ln(ln(x))@r{)} - -whose value at x = 2 is - - @r{(the value)} - -and at x = 3 is - - @r{(the value)} -@end smallexample - -@kindex C-x * d -@pindex calc-embedded-duplicate -The @kbd{C-x * d} (@code{calc-embedded-duplicate}) command is a -handy way to make sequences like this. If you type @kbd{C-x * d}, -the formula under the cursor (which may or may not have Embedded -mode enabled for it at the time) is copied immediately below and -Embedded mode is then enabled for that copy. - -For this example, you would start with just - -@smallexample -The derivative of - - ln(ln(x)) -@end smallexample - -@noindent -and press @kbd{C-x * d} with the cursor on this formula. The result -is - -@smallexample -The derivative of - - ln(ln(x)) - - - ln(ln(x)) -@end smallexample - -@noindent -with the second copy of the formula enabled in Embedded mode. -You can now press @kbd{a d x @key{RET}} to take the derivative, and -@kbd{C-x * d C-x * d} to make two more copies of the derivative. -To complete the computations, type @kbd{3 s l x @key{RET}} to evaluate -the last formula, then move up to the second-to-last formula -and type @kbd{2 s l x @key{RET}}. - -Finally, you would want to press @kbd{C-x * e} to exit Embedded -mode, then go up and insert the necessary text in between the -various formulas and numbers. - -@tex -\bigskip -@end tex - -@kindex C-x * f -@kindex C-x * ' -@pindex calc-embedded-new-formula -The @kbd{C-x * f} (@code{calc-embedded-new-formula}) command -creates a new embedded formula at the current point. It inserts -some default delimiters, which are usually just blank lines, -and then does an algebraic entry to get the formula (which is -then enabled for Embedded mode). This is just shorthand for -typing the delimiters yourself, positioning the cursor between -the new delimiters, and pressing @kbd{C-x * e}. The key sequence -@kbd{C-x * '} is equivalent to @kbd{C-x * f}. - -@kindex C-x * n -@kindex C-x * p -@pindex calc-embedded-next -@pindex calc-embedded-previous -The @kbd{C-x * n} (@code{calc-embedded-next}) and @kbd{C-x * p} -(@code{calc-embedded-previous}) commands move the cursor to the -next or previous active embedded formula in the buffer. They -can take positive or negative prefix arguments to move by several -formulas. Note that these commands do not actually examine the -text of the buffer looking for formulas; they only see formulas -which have previously been activated in Embedded mode. In fact, -@kbd{C-x * n} and @kbd{C-x * p} are a useful way to tell which -embedded formulas are currently active. Also, note that these -commands do not enable Embedded mode on the next or previous -formula, they just move the cursor. - -@kindex C-x * ` -@pindex calc-embedded-edit -The @kbd{C-x * `} (@code{calc-embedded-edit}) command edits the -embedded formula at the current point as if by @kbd{`} (@code{calc-edit}). -Embedded mode does not have to be enabled for this to work. Press -@kbd{C-c C-c} to finish the edit, or @kbd{C-x k} to cancel. - -@node Assignments in Embedded Mode, Mode Settings in Embedded Mode, More About Embedded Mode, Embedded Mode -@section Assignments in Embedded Mode - -@noindent -The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators -are especially useful in Embedded mode. They allow you to make -a definition in one formula, then refer to that definition in -other formulas embedded in the same buffer. - -An embedded formula which is an assignment to a variable, as in - -@example -foo := 5 -@end example - -@noindent -records @expr{5} as the stored value of @code{foo} for the -purposes of Embedded mode operations in the current buffer. It -does @emph{not} actually store @expr{5} as the ``global'' value -of @code{foo}, however. Regular Calc operations, and Embedded -formulas in other buffers, will not see this assignment. - -One way to use this assigned value is simply to create an -Embedded formula elsewhere that refers to @code{foo}, and to press -@kbd{=} in that formula. However, this permanently replaces the -@code{foo} in the formula with its current value. More interesting -is to use @samp{=>} elsewhere: - -@example -foo + 7 => 12 -@end example - -@xref{Evaluates-To Operator}, for a general discussion of @samp{=>}. - -If you move back and change the assignment to @code{foo}, any -@samp{=>} formulas which refer to it are automatically updated. - -@example -foo := 17 - -foo + 7 => 24 -@end example - -The obvious question then is, @emph{how} can one easily change the -assignment to @code{foo}? If you simply select the formula in -Embedded mode and type 17, the assignment itself will be replaced -by the 17. The effect on the other formula will be that the -variable @code{foo} becomes unassigned: - -@example -17 - -foo + 7 => foo + 7 -@end example - -The right thing to do is first to use a selection command (@kbd{j 2} -will do the trick) to select the righthand side of the assignment. -Then, @kbd{17 @key{TAB} @key{DEL}} will swap the 17 into place (@pxref{Selecting -Subformulas}, to see how this works). - -@kindex C-x * j -@pindex calc-embedded-select -The @kbd{C-x * j} (@code{calc-embedded-select}) command provides an -easy way to operate on assignments. It is just like @kbd{C-x * e}, -except that if the enabled formula is an assignment, it uses -@kbd{j 2} to select the righthand side. If the enabled formula -is an evaluates-to, it uses @kbd{j 1} to select the lefthand side. -A formula can also be a combination of both: - -@example -bar := foo + 3 => 20 -@end example - -@noindent -in which case @kbd{C-x * j} will select the middle part (@samp{foo + 3}). - -The formula is automatically deselected when you leave Embedded -mode. - -@kindex C-x * u -@pindex calc-embedded-update-formula -Another way to change the assignment to @code{foo} would simply be -to edit the number using regular Emacs editing rather than Embedded -mode. Then, we have to find a way to get Embedded mode to notice -the change. The @kbd{C-x * u} (@code{calc-embedded-update-formula}) -command is a convenient way to do this. - -@example -foo := 6 - -foo + 7 => 13 -@end example - -Pressing @kbd{C-x * u} is much like pressing @kbd{C-x * e = C-x * e}, that -is, temporarily enabling Embedded mode for the formula under the -cursor and then evaluating it with @kbd{=}. But @kbd{C-x * u} does -not actually use @kbd{C-x * e}, and in fact another formula somewhere -else can be enabled in Embedded mode while you use @kbd{C-x * u} and -that formula will not be disturbed. - -With a numeric prefix argument, @kbd{C-x * u} updates all active -@samp{=>} formulas in the buffer. Formulas which have not yet -been activated in Embedded mode, and formulas which do not have -@samp{=>} as their top-level operator, are not affected by this. -(This is useful only if you have used @kbd{m C}; see below.) - -With a plain @kbd{C-u} prefix, @kbd{C-u C-x * u} updates only in the -region between mark and point rather than in the whole buffer. - -@kbd{C-x * u} is also a handy way to activate a formula, such as an -@samp{=>} formula that has freshly been typed in or loaded from a -file. - -@kindex C-x * a -@pindex calc-embedded-activate -The @kbd{C-x * a} (@code{calc-embedded-activate}) command scans -through the current buffer and activates all embedded formulas -that contain @samp{:=} or @samp{=>} symbols. This does not mean -that Embedded mode is actually turned on, but only that the -formulas' positions are registered with Embedded mode so that -the @samp{=>} values can be properly updated as assignments are -changed. - -It is a good idea to type @kbd{C-x * a} right after loading a file -that uses embedded @samp{=>} operators. Emacs includes a nifty -``buffer-local variables'' feature that you can use to do this -automatically. The idea is to place near the end of your file -a few lines that look like this: - -@example ---- Local Variables: --- ---- eval:(calc-embedded-activate) --- ---- End: --- -@end example - -@noindent -where the leading and trailing @samp{---} can be replaced by -any suitable strings (which must be the same on all three lines) -or omitted altogether; in a @TeX{} or @LaTeX{} file, @samp{%} would be a good -leading string and no trailing string would be necessary. In a -C program, @samp{/*} and @samp{*/} would be good leading and -trailing strings. - -When Emacs loads a file into memory, it checks for a Local Variables -section like this one at the end of the file. If it finds this -section, it does the specified things (in this case, running -@kbd{C-x * a} automatically) before editing of the file begins. -The Local Variables section must be within 3000 characters of the -end of the file for Emacs to find it, and it must be in the last -page of the file if the file has any page separators. -@xref{File Variables, , Local Variables in Files, emacs, the -Emacs manual}. - -Note that @kbd{C-x * a} does not update the formulas it finds. -To do this, type, say, @kbd{M-1 C-x * u} after @w{@kbd{C-x * a}}. -Generally this should not be a problem, though, because the -formulas will have been up-to-date already when the file was -saved. - -Normally, @kbd{C-x * a} activates all the formulas it finds, but -any previous active formulas remain active as well. With a -positive numeric prefix argument, @kbd{C-x * a} first deactivates -all current active formulas, then actives the ones it finds in -its scan of the buffer. With a negative prefix argument, -@kbd{C-x * a} simply deactivates all formulas. - -Embedded mode has two symbols, @samp{Active} and @samp{~Active}, -which it puts next to the major mode name in a buffer's mode line. -It puts @samp{Active} if it has reason to believe that all -formulas in the buffer are active, because you have typed @kbd{C-x * a} -and Calc has not since had to deactivate any formulas (which can -happen if Calc goes to update an @samp{=>} formula somewhere because -a variable changed, and finds that the formula is no longer there -due to some kind of editing outside of Embedded mode). Calc puts -@samp{~Active} in the mode line if some, but probably not all, -formulas in the buffer are active. This happens if you activate -a few formulas one at a time but never use @kbd{C-x * a}, or if you -used @kbd{C-x * a} but then Calc had to deactivate a formula -because it lost track of it. If neither of these symbols appears -in the mode line, no embedded formulas are active in the buffer -(e.g., before Embedded mode has been used, or after a @kbd{M-- C-x * a}). - -Embedded formulas can refer to assignments both before and after them -in the buffer. If there are several assignments to a variable, the -nearest preceding assignment is used if there is one, otherwise the -following assignment is used. - -@example -x => 1 - -x := 1 - -x => 1 - -x := 2 - -x => 2 -@end example - -As well as simple variables, you can also assign to subscript -expressions of the form @samp{@var{var}_@var{number}} (as in -@code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}). -Assignments to other kinds of objects can be represented by Calc, -but the automatic linkage between assignments and references works -only for plain variables and these two kinds of subscript expressions. - -If there are no assignments to a given variable, the global -stored value for the variable is used (@pxref{Storing Variables}), -or, if no value is stored, the variable is left in symbolic form. -Note that global stored values will be lost when the file is saved -and loaded in a later Emacs session, unless you have used the -@kbd{s p} (@code{calc-permanent-variable}) command to save them; -@pxref{Operations on Variables}. - -The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic -recomputation of @samp{=>} forms on and off. If you turn automatic -recomputation off, you will have to use @kbd{C-x * u} to update these -formulas manually after an assignment has been changed. If you -plan to change several assignments at once, it may be more efficient -to type @kbd{m C}, change all the assignments, then use @kbd{M-1 C-x * u} -to update the entire buffer afterwards. The @kbd{m C} command also -controls @samp{=>} formulas on the stack; @pxref{Evaluates-To -Operator}. When you turn automatic recomputation back on, the -stack will be updated but the Embedded buffer will not; you must -use @kbd{C-x * u} to update the buffer by hand. - -@node Mode Settings in Embedded Mode, Customizing Embedded Mode, Assignments in Embedded Mode, Embedded Mode -@section Mode Settings in Embedded Mode - -@kindex m e -@pindex calc-embedded-preserve-modes -@noindent -The mode settings can be changed while Calc is in embedded mode, but -by default they will revert to their original values when embedded mode -is ended. However, the modes saved when the mode-recording mode is -@code{Save} (see below) and the modes in effect when the @kbd{m e} -(@code{calc-embedded-preserve-modes}) command is given -will be preserved when embedded mode is ended. - -Embedded mode has a rather complicated mechanism for handling mode -settings in Embedded formulas. It is possible to put annotations -in the file that specify mode settings either global to the entire -file or local to a particular formula or formulas. In the latter -case, different modes can be specified for use when a formula -is the enabled Embedded mode formula. - -When you give any mode-setting command, like @kbd{m f} (for Fraction -mode) or @kbd{d s} (for scientific notation), Embedded mode adds -a line like the following one to the file just before the opening -delimiter of the formula. - -@example -% [calc-mode: fractions: t] -% [calc-mode: float-format: (sci 0)] -@end example - -When Calc interprets an embedded formula, it scans the text before -the formula for mode-setting annotations like these and sets the -Calc buffer to match these modes. Modes not explicitly described -in the file are not changed. Calc scans all the way to the top of -the file, or up to a line of the form - -@example -% [calc-defaults] -@end example - -@noindent -which you can insert at strategic places in the file if this backward -scan is getting too slow, or just to provide a barrier between one -``zone'' of mode settings and another. - -If the file contains several annotations for the same mode, the -closest one before the formula is used. Annotations after the -formula are never used (except for global annotations, described -below). - -The scan does not look for the leading @samp{% }, only for the -square brackets and the text they enclose. In fact, the leading -characters are different for different major modes. You can edit the -mode annotations to a style that works better in context if you wish. -@xref{Customizing Embedded Mode}, to see how to change the style -that Calc uses when it generates the annotations. You can write -mode annotations into the file yourself if you know the syntax; -the easiest way to find the syntax for a given mode is to let -Calc write the annotation for it once and see what it does. - -If you give a mode-changing command for a mode that already has -a suitable annotation just above the current formula, Calc will -modify that annotation rather than generating a new, conflicting -one. - -Mode annotations have three parts, separated by colons. (Spaces -after the colons are optional.) The first identifies the kind -of mode setting, the second is a name for the mode itself, and -the third is the value in the form of a Lisp symbol, number, -or list. Annotations with unrecognizable text in the first or -second parts are ignored. The third part is not checked to make -sure the value is of a valid type or range; if you write an -annotation by hand, be sure to give a proper value or results -will be unpredictable. Mode-setting annotations are case-sensitive. - -While Embedded mode is enabled, the word @code{Local} appears in -the mode line. This is to show that mode setting commands generate -annotations that are ``local'' to the current formula or set of -formulas. The @kbd{m R} (@code{calc-mode-record-mode}) command -causes Calc to generate different kinds of annotations. Pressing -@kbd{m R} repeatedly cycles through the possible modes. - -@code{LocEdit} and @code{LocPerm} modes generate annotations -that look like this, respectively: - -@example -% [calc-edit-mode: float-format: (sci 0)] -% [calc-perm-mode: float-format: (sci 5)] -@end example - -The first kind of annotation will be used only while a formula -is enabled in Embedded mode. The second kind will be used only -when the formula is @emph{not} enabled. (Whether the formula -is ``active'' or not, i.e., whether Calc has seen this formula -yet, is not relevant here.) - -@code{Global} mode generates an annotation like this at the end -of the file: - -@example -% [calc-global-mode: fractions t] -@end example - -Global mode annotations affect all formulas throughout the file, -and may appear anywhere in the file. This allows you to tuck your -mode annotations somewhere out of the way, say, on a new page of -the file, as long as those mode settings are suitable for all -formulas in the file. - -Enabling a formula with @kbd{C-x * e} causes a fresh scan for local -mode annotations; you will have to use this after adding annotations -above a formula by hand to get the formula to notice them. Updating -a formula with @kbd{C-x * u} will also re-scan the local modes, but -global modes are only re-scanned by @kbd{C-x * a}. - -Another way that modes can get out of date is if you add a local -mode annotation to a formula that has another formula after it. -In this example, we have used the @kbd{d s} command while the -first of the two embedded formulas is active. But the second -formula has not changed its style to match, even though by the -rules of reading annotations the @samp{(sci 0)} applies to it, too. - -@example -% [calc-mode: float-format: (sci 0)] -1.23e2 - -456. -@end example - -We would have to go down to the other formula and press @kbd{C-x * u} -on it in order to get it to notice the new annotation. - -Two more mode-recording modes selectable by @kbd{m R} are available -which are also available outside of Embedded mode. -(@pxref{General Mode Commands}.) They are @code{Save}, in which mode -settings are recorded permanently in your Calc init file (the file given -by the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}) -rather than by annotating the current document, and no-recording -mode (where there is no symbol like @code{Save} or @code{Local} in -the mode line), in which mode-changing commands do not leave any -annotations at all. - -When Embedded mode is not enabled, mode-recording modes except -for @code{Save} have no effect. - -@node Customizing Embedded Mode, , Mode Settings in Embedded Mode, Embedded Mode -@section Customizing Embedded Mode - -@noindent -You can modify Embedded mode's behavior by setting various Lisp -variables described here. These variables are customizable -(@pxref{Customizing Calc}), or you can use @kbd{M-x set-variable} -or @kbd{M-x edit-options} to adjust a variable on the fly. -(Another possibility would be to use a file-local variable annotation at -the end of the file; -@pxref{File Variables, , Local Variables in Files, emacs, the Emacs manual}.) -Many of the variables given mentioned here can be set to depend on the -major mode of the editing buffer (@pxref{Customizing Calc}). - -@vindex calc-embedded-open-formula -The @code{calc-embedded-open-formula} variable holds a regular -expression for the opening delimiter of a formula. @xref{Regexp Search, -, Regular Expression Search, emacs, the Emacs manual}, to see -how regular expressions work. Basically, a regular expression is a -pattern that Calc can search for. A regular expression that considers -blank lines, @samp{$}, and @samp{$$} to be opening delimiters is -@code{"\\`\\|^\n\\|\\$\\$?"}. Just in case the meaning of this -regular expression is not completely plain, let's go through it -in detail. - -The surrounding @samp{" "} marks quote the text between them as a -Lisp string. If you left them off, @code{set-variable} or -@code{edit-options} would try to read the regular expression as a -Lisp program. - -The most obvious property of this regular expression is that it -contains indecently many backslashes. There are actually two levels -of backslash usage going on here. First, when Lisp reads a quoted -string, all pairs of characters beginning with a backslash are -interpreted as special characters. Here, @code{\n} changes to a -new-line character, and @code{\\} changes to a single backslash. -So the actual regular expression seen by Calc is -@samp{\`\|^ @r{(newline)} \|\$\$?}. - -Regular expressions also consider pairs beginning with backslash -to have special meanings. Sometimes the backslash is used to quote -a character that otherwise would have a special meaning in a regular -expression, like @samp{$}, which normally means ``end-of-line,'' -or @samp{?}, which means that the preceding item is optional. So -@samp{\$\$?} matches either one or two dollar signs. - -The other codes in this regular expression are @samp{^}, which matches -``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`}, -which matches ``beginning-of-buffer.'' So the whole pattern means -that a formula begins at the beginning of the buffer, or on a newline -that occurs at the beginning of a line (i.e., a blank line), or at -one or two dollar signs. - -The default value of @code{calc-embedded-open-formula} looks just -like this example, with several more alternatives added on to -recognize various other common kinds of delimiters. - -By the way, the reason to use @samp{^\n} rather than @samp{^$} -or @samp{\n\n}, which also would appear to match blank lines, -is that the former expression actually ``consumes'' only one -newline character as @emph{part of} the delimiter, whereas the -latter expressions consume zero or two newlines, respectively. -The former choice gives the most natural behavior when Calc -must operate on a whole formula including its delimiters. - -See the Emacs manual for complete details on regular expressions. -But just for your convenience, here is a list of all characters -which must be quoted with backslash (like @samp{\$}) to avoid -some special interpretation: @samp{. * + ? [ ] ^ $ \}. (Note -the backslash in this list; for example, to match @samp{\[} you -must use @code{"\\\\\\["}. An exercise for the reader is to -account for each of these six backslashes!) - -@vindex calc-embedded-close-formula -The @code{calc-embedded-close-formula} variable holds a regular -expression for the closing delimiter of a formula. A closing -regular expression to match the above example would be -@code{"\\'\\|\n$\\|\\$\\$?"}. This is almost the same as the -other one, except it now uses @samp{\'} (``end-of-buffer'') and -@samp{\n$} (newline occurring at end of line, yet another way -of describing a blank line that is more appropriate for this -case). - -@vindex calc-embedded-word-regexp -The @code{calc-embedded-word-regexp} variable holds a regular expression -used to define an expression to look for (a ``word'') when you type -@kbd{C-x * w} to enable Embedded mode. - -@vindex calc-embedded-open-plain -The @code{calc-embedded-open-plain} variable is a string which -begins a ``plain'' formula written in front of the formatted -formula when @kbd{d p} mode is turned on. Note that this is an -actual string, not a regular expression, because Calc must be able -to write this string into a buffer as well as to recognize it. -The default string is @code{"%%% "} (note the trailing space), but may -be different for certain major modes. - -@vindex calc-embedded-close-plain -The @code{calc-embedded-close-plain} variable is a string which -ends a ``plain'' formula. The default is @code{" %%%\n"}, but may be -different for different major modes. Without -the trailing newline here, the first line of a Big mode formula -that followed might be shifted over with respect to the other lines. - -@vindex calc-embedded-open-new-formula -The @code{calc-embedded-open-new-formula} variable is a string -which is inserted at the front of a new formula when you type -@kbd{C-x * f}. Its default value is @code{"\n\n"}. If this -string begins with a newline character and the @kbd{C-x * f} is -typed at the beginning of a line, @kbd{C-x * f} will skip this -first newline to avoid introducing unnecessary blank lines in -the file. - -@vindex calc-embedded-close-new-formula -The @code{calc-embedded-close-new-formula} variable is the corresponding -string which is inserted at the end of a new formula. Its default -value is also @code{"\n\n"}. The final newline is omitted by -@w{@kbd{C-x * f}} if typed at the end of a line. (It follows that if -@kbd{C-x * f} is typed on a blank line, both a leading opening -newline and a trailing closing newline are omitted.) - -@vindex calc-embedded-announce-formula -The @code{calc-embedded-announce-formula} variable is a regular -expression which is sure to be followed by an embedded formula. -The @kbd{C-x * a} command searches for this pattern as well as for -@samp{=>} and @samp{:=} operators. Note that @kbd{C-x * a} will -not activate just anything surrounded by formula delimiters; after -all, blank lines are considered formula delimiters by default! -But if your language includes a delimiter which can only occur -actually in front of a formula, you can take advantage of it here. -The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, but may be -different for different major modes. -This pattern will check for @samp{%Embed} followed by any number of -lines beginning with @samp{%} and a space. This last is important to -make Calc consider mode annotations part of the pattern, so that the -formula's opening delimiter really is sure to follow the pattern. - -@vindex calc-embedded-open-mode -The @code{calc-embedded-open-mode} variable is a string (not a -regular expression) which should precede a mode annotation. -Calc never scans for this string; Calc always looks for the -annotation itself. But this is the string that is inserted before -the opening bracket when Calc adds an annotation on its own. -The default is @code{"% "}, but may be different for different major -modes. - -@vindex calc-embedded-close-mode -The @code{calc-embedded-close-mode} variable is a string which -follows a mode annotation written by Calc. Its default value -is simply a newline, @code{"\n"}, but may be different for different -major modes. If you change this, it is a good idea still to end with a -newline so that mode annotations will appear on lines by themselves. - -@node Programming, Copying, Embedded Mode, Top -@chapter Programming - -@noindent -There are several ways to ``program'' the Emacs Calculator, depending -on the nature of the problem you need to solve. - -@enumerate -@item -@dfn{Keyboard macros} allow you to record a sequence of keystrokes -and play them back at a later time. This is just the standard Emacs -keyboard macro mechanism, dressed up with a few more features such -as loops and conditionals. - -@item -@dfn{Algebraic definitions} allow you to use any formula to define a -new function. This function can then be used in algebraic formulas or -as an interactive command. - -@item -@dfn{Rewrite rules} are discussed in the section on algebra commands. -@xref{Rewrite Rules}. If you put your rewrite rules in the variable -@code{EvalRules}, they will be applied automatically to all Calc -results in just the same way as an internal ``rule'' is applied to -evaluate @samp{sqrt(9)} to 3 and so on. @xref{Automatic Rewrites}. - -@item -@dfn{Lisp} is the programming language that Calc (and most of Emacs) -is written in. If the above techniques aren't powerful enough, you -can write Lisp functions to do anything that built-in Calc commands -can do. Lisp code is also somewhat faster than keyboard macros or -rewrite rules. -@end enumerate - -@kindex z -Programming features are available through the @kbd{z} and @kbd{Z} -prefix keys. New commands that you define are two-key sequences -beginning with @kbd{z}. Commands for managing these definitions -use the shift-@kbd{Z} prefix. (The @kbd{Z T} (@code{calc-timing}) -command is described elsewhere; @pxref{Troubleshooting Commands}. -The @kbd{Z C} (@code{calc-user-define-composition}) command is also -described elsewhere; @pxref{User-Defined Compositions}.) - -@menu -* Creating User Keys:: -* Keyboard Macros:: -* Invocation Macros:: -* Algebraic Definitions:: -* Lisp Definitions:: -@end menu - -@node Creating User Keys, Keyboard Macros, Programming, Programming -@section Creating User Keys - -@noindent -@kindex Z D -@pindex calc-user-define -Any Calculator command may be bound to a key using the @kbd{Z D} -(@code{calc-user-define}) command. Actually, it is bound to a two-key -sequence beginning with the lower-case @kbd{z} prefix. - -The @kbd{Z D} command first prompts for the key to define. For example, -press @kbd{Z D a} to define the new key sequence @kbd{z a}. You are then -prompted for the name of the Calculator command that this key should -run. For example, the @code{calc-sincos} command is not normally -available on a key. Typing @kbd{Z D s sincos @key{RET}} programs the -@kbd{z s} key sequence to run @code{calc-sincos}. This definition will remain -in effect for the rest of this Emacs session, or until you redefine -@kbd{z s} to be something else. - -You can actually bind any Emacs command to a @kbd{z} key sequence by -backspacing over the @samp{calc-} when you are prompted for the command name. - -As with any other prefix key, you can type @kbd{z ?} to see a list of -all the two-key sequences you have defined that start with @kbd{z}. -Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined. - -User keys are typically letters, but may in fact be any key. -(@key{META}-keys are not permitted, nor are a terminal's special -function keys which generate multi-character sequences when pressed.) -You can define different commands on the shifted and unshifted versions -of a letter if you wish. - -@kindex Z U -@pindex calc-user-undefine -The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key. -For example, the key sequence @kbd{Z U s} will undefine the @code{sincos} -key we defined above. - -@kindex Z P -@pindex calc-user-define-permanent -@cindex Storing user definitions -@cindex Permanent user definitions -@cindex Calc init file, user-defined commands -The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key -binding permanent so that it will remain in effect even in future Emacs -sessions. (It does this by adding a suitable bit of Lisp code into -your Calc init file; that is, the file given by the variable -@code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}.) For example, -@kbd{Z P s} would register our @code{sincos} command permanently. If -you later wish to unregister this command you must edit your Calc init -file by hand. (@xref{General Mode Commands}, for a way to tell Calc to -use a different file for the Calc init file.) - -The @kbd{Z P} command also saves the user definition, if any, for the -command bound to the key. After @kbd{Z F} and @kbd{Z C}, a given user -key could invoke a command, which in turn calls an algebraic function, -which might have one or more special display formats. A single @kbd{Z P} -command will save all of these definitions. -To save an algebraic function, type @kbd{'} (the apostrophe) -when prompted for a key, and type the function name. To save a command -without its key binding, type @kbd{M-x} and enter a function name. (The -@samp{calc-} prefix will automatically be inserted for you.) -(If the command you give implies a function, the function will be saved, -and if the function has any display formats, those will be saved, but -not the other way around: Saving a function will not save any commands -or key bindings associated with the function.) - -@kindex Z E -@pindex calc-user-define-edit -@cindex Editing user definitions -The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition -of a user key. This works for keys that have been defined by either -keyboard macros or formulas; further details are contained in the relevant -following sections. - -@node Keyboard Macros, Invocation Macros, Creating User Keys, Programming -@section Programming with Keyboard Macros - -@noindent -@kindex X -@cindex Programming with keyboard macros -@cindex Keyboard macros -The easiest way to ``program'' the Emacs Calculator is to use standard -keyboard macros. Press @w{@kbd{C-x (}} to begin recording a macro. From -this point on, keystrokes you type will be saved away as well as -performing their usual functions. Press @kbd{C-x )} to end recording. -Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to -execute your keyboard macro by replaying the recorded keystrokes. -@xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further -information. - -When you use @kbd{X} to invoke a keyboard macro, the entire macro is -treated as a single command by the undo and trail features. The stack -display buffer is not updated during macro execution, but is instead -fixed up once the macro completes. Thus, commands defined with keyboard -macros are convenient and efficient. The @kbd{C-x e} command, on the -other hand, invokes the keyboard macro with no special treatment: Each -command in the macro will record its own undo information and trail entry, -and update the stack buffer accordingly. If your macro uses features -outside of Calc's control to operate on the contents of the Calc stack -buffer, or if it includes Undo, Redo, or last-arguments commands, you -must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date -at all times. You could also consider using @kbd{K} (@code{calc-keep-args}) -instead of @kbd{M-@key{RET}} (@code{calc-last-args}). - -Calc extends the standard Emacs keyboard macros in several ways. -Keyboard macros can be used to create user-defined commands. Keyboard -macros can include conditional and iteration structures, somewhat -analogous to those provided by a traditional programmable calculator. - -@menu -* Naming Keyboard Macros:: -* Conditionals in Macros:: -* Loops in Macros:: -* Local Values in Macros:: -* Queries in Macros:: -@end menu - -@node Naming Keyboard Macros, Conditionals in Macros, Keyboard Macros, Keyboard Macros -@subsection Naming Keyboard Macros - -@noindent -@kindex Z K -@pindex calc-user-define-kbd-macro -Once you have defined a keyboard macro, you can bind it to a @kbd{z} -key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command. -This command prompts first for a key, then for a command name. For -example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will -define a keyboard macro which negates the top two numbers on the stack -(@key{TAB} swaps the top two stack elements). Now you can type -@kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key -sequence. The default command name (if you answer the second prompt with -just the @key{RET} key as in this example) will be something like -@samp{calc-User-n}. The keyboard macro will now be available as both -@kbd{z n} and @kbd{M-x calc-User-n}. You can backspace and enter a more -descriptive command name if you wish. - -Macros defined by @kbd{Z K} act like single commands; they are executed -in the same way as by the @kbd{X} key. If you wish to define the macro -as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}), -give a negative prefix argument to @kbd{Z K}. - -Once you have bound your keyboard macro to a key, you can use -@kbd{Z P} to register it permanently with Emacs. @xref{Creating User Keys}. - -@cindex Keyboard macros, editing -The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has -been defined by a keyboard macro tries to use the @code{edmacro} package -edit the macro. Type @kbd{C-c C-c} to finish editing and update -the definition stored on the key, or, to cancel the edit, kill the -buffer with @kbd{C-x k}. -The special characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, -@code{DEL}, and @code{NUL} must be entered as these three character -sequences, written in all uppercase, as must the prefixes @code{C-} and -@code{M-}. Spaces and line breaks are ignored. Other characters are -copied verbatim into the keyboard macro. Basically, the notation is the -same as is used in all of this manual's examples, except that the manual -takes some liberties with spaces: When we say @kbd{' [1 2 3] @key{RET}}, -we take it for granted that it is clear we really mean -@kbd{' [1 @key{SPC} 2 @key{SPC} 3] @key{RET}}. - -@kindex C-x * m -@pindex read-kbd-macro -The @kbd{C-x * m} (@code{read-kbd-macro}) command reads an Emacs ``region'' -of spelled-out keystrokes and defines it as the current keyboard macro. -It is a convenient way to define a keyboard macro that has been stored -in a file, or to define a macro without executing it at the same time. - -@node Conditionals in Macros, Loops in Macros, Naming Keyboard Macros, Keyboard Macros -@subsection Conditionals in Keyboard Macros - -@noindent -@kindex Z [ -@kindex Z ] -@pindex calc-kbd-if -@pindex calc-kbd-else -@pindex calc-kbd-else-if -@pindex calc-kbd-end-if -@cindex Conditional structures -The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if}) -commands allow you to put simple tests in a keyboard macro. When Calc -sees the @kbd{Z [}, it pops an object from the stack and, if the object is -a non-zero value, continues executing keystrokes. But if the object is -zero, or if it is not provably nonzero, Calc skips ahead to the matching -@kbd{Z ]} keystroke. @xref{Logical Operations}, for a set of commands for -performing tests which conveniently produce 1 for true and 0 for false. - -For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value -function in the form of a keyboard macro. This macro duplicates the -number on the top of the stack, pushes zero and compares using @kbd{a <} -(@code{calc-less-than}), then, if the number was less than zero, -executes @kbd{n} (@code{calc-change-sign}). Otherwise, the change-sign -command is skipped. - -To program this macro, type @kbd{C-x (}, type the above sequence of -keystrokes, then type @kbd{C-x )}. Note that the keystrokes will be -executed while you are making the definition as well as when you later -re-execute the macro by typing @kbd{X}. Thus you should make sure a -suitable number is on the stack before defining the macro so that you -don't get a stack-underflow error during the definition process. - -Conditionals can be nested arbitrarily. However, there should be exactly -one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro. - -@kindex Z : -The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between -two keystroke sequences. The general format is @kbd{@var{cond} Z [ -@var{then-part} Z : @var{else-part} Z ]}. If @var{cond} is true -(i.e., if the top of stack contains a non-zero number after @var{cond} -has been executed), the @var{then-part} will be executed and the -@var{else-part} will be skipped. Otherwise, the @var{then-part} will -be skipped and the @var{else-part} will be executed. - -@kindex Z | -The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose -between any number of alternatives. For example, -@kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z : -@var{part3} Z ]} will execute @var{part1} if @var{cond1} is true, -otherwise it will execute @var{part2} if @var{cond2} is true, otherwise -it will execute @var{part3}. - -More precisely, @kbd{Z [} pops a number and conditionally skips to the -next matching @kbd{Z :} or @kbd{Z ]} key. @w{@kbd{Z ]}} has no effect when -actually executed. @kbd{Z :} skips to the next matching @kbd{Z ]}. -@kbd{Z |} pops a number and conditionally skips to the next matching -@kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally -equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |} -does not. - -Calc's conditional and looping constructs work by scanning the -keyboard macro for occurrences of character sequences like @samp{Z:} -and @samp{Z]}. One side-effect of this is that if you use these -constructs you must be careful that these character pairs do not -occur by accident in other parts of the macros. Since Calc rarely -uses shift-@kbd{Z} for any purpose except as a prefix character, this -is not likely to be a problem. Another side-effect is that it will -not work to define your own custom key bindings for these commands. -Only the standard shift-@kbd{Z} bindings will work correctly. - -@kindex Z C-g -If Calc gets stuck while skipping characters during the definition of a -macro, type @kbd{Z C-g} to cancel the definition. (Typing plain @kbd{C-g} -actually adds a @kbd{C-g} keystroke to the macro.) - -@node Loops in Macros, Local Values in Macros, Conditionals in Macros, Keyboard Macros -@subsection Loops in Keyboard Macros - -@noindent -@kindex Z < -@kindex Z > -@pindex calc-kbd-repeat -@pindex calc-kbd-end-repeat -@cindex Looping structures -@cindex Iterative structures -The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >} -(@code{calc-kbd-end-repeat}) commands pop a number from the stack, -which must be an integer, then repeat the keystrokes between the brackets -the specified number of times. If the integer is zero or negative, the -body is skipped altogether. For example, @kbd{1 @key{TAB} Z < 2 * Z >} -computes two to a nonnegative integer power. First, we push 1 on the -stack and then swap the integer argument back to the top. The @kbd{Z <} -pops that argument leaving the 1 back on top of the stack. Then, we -repeat a multiply-by-two step however many times. - -Once again, the keyboard macro is executed as it is being entered. -In this case it is especially important to set up reasonable initial -conditions before making the definition: Suppose the integer 1000 just -happened to be sitting on the stack before we typed the above definition! -Another approach is to enter a harmless dummy definition for the macro, -then go back and edit in the real one with a @kbd{Z E} command. Yet -another approach is to type the macro as written-out keystroke names -in a buffer, then use @kbd{C-x * m} (@code{read-kbd-macro}) to read the -macro. - -@kindex Z / -@pindex calc-break -The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out -of a keyboard macro loop prematurely. It pops an object from the stack; -if that object is true (a non-zero number), control jumps out of the -innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues -after the @kbd{Z >}. If the object is false, the @kbd{Z /} has no -effect. Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;} -in the C language. - -@kindex Z ( -@kindex Z ) -@pindex calc-kbd-for -@pindex calc-kbd-end-for -The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for}) -commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the -value of the counter available inside the loop. The general layout is -@kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}. The @kbd{Z (} -command pops initial and final values from the stack. It then creates -a temporary internal counter and initializes it with the value @var{init}. -The @kbd{Z (} command then repeatedly pushes the counter value onto the -stack and executes @var{body} and @var{step}, adding @var{step} to the -counter each time until the loop finishes. - -@cindex Summations (by keyboard macros) -By default, the loop finishes when the counter becomes greater than (or -less than) @var{final}, assuming @var{initial} is less than (greater -than) @var{final}. If @var{initial} is equal to @var{final}, the body -executes exactly once. The body of the loop always executes at least -once. For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the -squares of the integers from 1 to 10, in steps of 1. - -If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is -forced to use upward-counting conventions. In this case, if @var{initial} -is greater than @var{final} the body will not be executed at all. -Note that @var{step} may still be negative in this loop; the prefix -argument merely constrains the loop-finished test. Likewise, a prefix -argument of @mathit{-1} forces downward-counting conventions. - -@kindex Z @{ -@kindex Z @} -@pindex calc-kbd-loop -@pindex calc-kbd-end-loop -The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}} -(@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and -@kbd{Z >}, except that they do not pop a count from the stack---they -effectively create an infinite loop. Every @kbd{Z @{} @dots{} @kbd{Z @}} -loop ought to include at least one @kbd{Z /} to make sure the loop -doesn't run forever. (If any error message occurs which causes Emacs -to beep, the keyboard macro will also be halted; this is a standard -feature of Emacs. You can also generally press @kbd{C-g} to halt a -running keyboard macro, although not all versions of Unix support -this feature.) - -The conditional and looping constructs are not actually tied to -keyboard macros, but they are most often used in that context. -For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push -ten copies of 23 onto the stack. This can be typed ``live'' just -as easily as in a macro definition. - -@xref{Conditionals in Macros}, for some additional notes about -conditional and looping commands. - -@node Local Values in Macros, Queries in Macros, Loops in Macros, Keyboard Macros -@subsection Local Values in Macros - -@noindent -@cindex Local variables -@cindex Restoring saved modes -Keyboard macros sometimes want to operate under known conditions -without affecting surrounding conditions. For example, a keyboard -macro may wish to turn on Fraction mode, or set a particular -precision, independent of the user's normal setting for those -modes. - -@kindex Z ` -@kindex Z ' -@pindex calc-kbd-push -@pindex calc-kbd-pop -Macros also sometimes need to use local variables. Assignments to -local variables inside the macro should not affect any variables -outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '} -(@code{calc-kbd-pop}) commands give you both of these capabilities. - -When you type @kbd{Z `} (with a backquote or accent grave character), -the values of various mode settings are saved away. The ten ``quick'' -variables @code{q0} through @code{q9} are also saved. When -you type @w{@kbd{Z '}} (with an apostrophe), these values are restored. -Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested. - -If a keyboard macro halts due to an error in between a @kbd{Z `} and -a @kbd{Z '}, the saved values will be restored correctly even though -the macro never reaches the @kbd{Z '} command. Thus you can use -@kbd{Z `} and @kbd{Z '} without having to worry about what happens -in exceptional conditions. - -If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts -you into a ``recursive edit.'' You can tell you are in a recursive -edit because there will be extra square brackets in the mode line, -as in @samp{[(Calculator)]}. These brackets will go away when you -type the matching @kbd{Z '} command. The modes and quick variables -will be saved and restored in just the same way as if actual keyboard -macros were involved. - -The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision -and binary word size, the angular mode (Deg, Rad, or HMS), the -simplification mode, Algebraic mode, Symbolic mode, Infinite mode, -Matrix or Scalar mode, Fraction mode, and the current complex mode -(Polar or Rectangular). The ten ``quick'' variables' values (or lack -thereof) are also saved. - -Most mode-setting commands act as toggles, but with a numeric prefix -they force the mode either on (positive prefix) or off (negative -or zero prefix). Since you don't know what the environment might -be when you invoke your macro, it's best to use prefix arguments -for all mode-setting commands inside the macro. - -In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes -listed above to their default values. As usual, the matching @kbd{Z '} -will restore the modes to their settings from before the @kbd{C-u Z `}. -Also, @w{@kbd{Z `}} with a negative prefix argument resets the algebraic mode -to its default (off) but leaves the other modes the same as they were -outside the construct. - -The contents of the stack and trail, values of non-quick variables, and -other settings such as the language mode and the various display modes, -are @emph{not} affected by @kbd{Z `} and @kbd{Z '}. - -@node Queries in Macros, , Local Values in Macros, Keyboard Macros -@subsection Queries in Keyboard Macros - -@c @noindent -@c @kindex Z = -@c @pindex calc-kbd-report -@c The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative -@c message including the value on the top of the stack. You are prompted -@c to enter a string. That string, along with the top-of-stack value, -@c is displayed unless @kbd{m w} (@code{calc-working}) has been used -@c to turn such messages off. - -@noindent -@kindex Z # -@pindex calc-kbd-query -The @kbd{Z #} (@code{calc-kbd-query}) command prompts for an algebraic -entry which takes its input from the keyboard, even during macro -execution. All the normal conventions of algebraic input, including the -use of @kbd{$} characters, are supported. The prompt message itself is -taken from the top of the stack, and so must be entered (as a string) -before the @kbd{Z #} command. (Recall, as a string it can be entered by -pressing the @kbd{"} key and will appear as a vector when it is put on -the stack. The prompt message is only put on the stack to provide a -prompt for the @kbd{Z #} command; it will not play any role in any -subsequent calculations.) This command allows your keyboard macros to -accept numbers or formulas as interactive input. - -As an example, -@kbd{2 @key{RET} "Power: " @key{RET} Z # 3 @key{RET} ^} will prompt for -input with ``Power: '' in the minibuffer, then return 2 to the provided -power. (The response to the prompt that's given, 3 in this example, -will not be part of the macro.) - -@xref{Keyboard Macro Query, , , emacs, the Emacs Manual}, for a description of -@kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept -keyboard input during a keyboard macro. In particular, you can use -@kbd{C-x q} to enter a recursive edit, which allows the user to perform -any Calculator operations interactively before pressing @kbd{C-M-c} to -return control to the keyboard macro. - -@node Invocation Macros, Algebraic Definitions, Keyboard Macros, Programming -@section Invocation Macros - -@kindex C-x * z -@kindex Z I -@pindex calc-user-invocation -@pindex calc-user-define-invocation -Calc provides one special keyboard macro, called up by @kbd{C-x * z} -(@code{calc-user-invocation}), that is intended to allow you to define -your own special way of starting Calc. To define this ``invocation -macro,'' create the macro in the usual way with @kbd{C-x (} and -@kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}). -There is only one invocation macro, so you don't need to type any -additional letters after @kbd{Z I}. From now on, you can type -@kbd{C-x * z} at any time to execute your invocation macro. - -For example, suppose you find yourself often grabbing rectangles of -numbers into Calc and multiplying their columns. You can do this -by typing @kbd{C-x * r} to grab, and @kbd{V R : *} to multiply columns. -To make this into an invocation macro, just type @kbd{C-x ( C-x * r -V R : * C-x )}, then @kbd{Z I}. Then, to multiply a rectangle of data, -just mark the data in its buffer in the usual way and type @kbd{C-x * z}. - -Invocation macros are treated like regular Emacs keyboard macros; -all the special features described above for @kbd{Z K}-style macros -do not apply. @kbd{C-x * z} is just like @kbd{C-x e}, except that it -uses the macro that was last stored by @kbd{Z I}. (In fact, the -macro does not even have to have anything to do with Calc!) - -The @kbd{m m} command saves the last invocation macro defined by -@kbd{Z I} along with all the other Calc mode settings. -@xref{General Mode Commands}. - -@node Algebraic Definitions, Lisp Definitions, Invocation Macros, Programming -@section Programming with Formulas - -@noindent -@kindex Z F -@pindex calc-user-define-formula -@cindex Programming with algebraic formulas -Another way to create a new Calculator command uses algebraic formulas. -The @kbd{Z F} (@code{calc-user-define-formula}) command stores the -formula at the top of the stack as the definition for a key. This -command prompts for five things: The key, the command name, the function -name, the argument list, and the behavior of the command when given -non-numeric arguments. - -For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula -@samp{a + 2*b} onto the stack. We now type @kbd{Z F m} to define this -formula on the @kbd{z m} key sequence. The next prompt is for a command -name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form -for the new command. If you simply press @key{RET}, a default name like -@code{calc-User-m} will be constructed. In our example, suppose we enter -@kbd{spam @key{RET}} to define the new command as @code{calc-spam}. - -If you want to give the formula a long-style name only, you can press -@key{SPC} or @key{RET} when asked which single key to use. For example -@kbd{Z F @key{RET} spam @key{RET}} defines the new command as -@kbd{M-x calc-spam}, with no keyboard equivalent. - -The third prompt is for an algebraic function name. The default is to -use the same name as the command name but without the @samp{calc-} -prefix. (If this is of the form @samp{User-m}, the hyphen is removed so -it won't be taken for a minus sign in algebraic formulas.) -This is the name you will use if you want to enter your -new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}. -Then the new function can be invoked by pushing two numbers on the -stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic -formula @samp{yow(x,y)}. - -The fourth prompt is for the function's argument list. This is used to -associate values on the stack with the variables that appear in the formula. -The default is a list of all variables which appear in the formula, sorted -into alphabetical order. In our case, the default would be @samp{(a b)}. -This means that, when the user types @kbd{z m}, the Calculator will remove -two numbers from the stack, substitute these numbers for @samp{a} and -@samp{b} (respectively) in the formula, then simplify the formula and -push the result on the stack. In other words, @kbd{10 @key{RET} 100 z m} -would replace the 10 and 100 on the stack with the number 210, which is -@expr{a + 2 b} with @expr{a=10} and @expr{b=100}. Likewise, the formula -@samp{yow(10, 100)} will be evaluated by substituting @expr{a=10} and -@expr{b=100} in the definition. - -You can rearrange the order of the names before pressing @key{RET} to -control which stack positions go to which variables in the formula. If -you remove a variable from the argument list, that variable will be left -in symbolic form by the command. Thus using an argument list of @samp{(b)} -for our function would cause @kbd{10 z m} to replace the 10 on the stack -with the formula @samp{a + 20}. If we had used an argument list of -@samp{(b a)}, the result with inputs 10 and 100 would have been 120. - -You can also put a nameless function on the stack instead of just a -formula, as in @samp{}. @xref{Specifying Operators}. -In this example, the command will be defined by the formula @samp{a + 2 b} -using the argument list @samp{(a b)}. - -The final prompt is a y-or-n question concerning what to do if symbolic -arguments are given to your function. If you answer @kbd{y}, then -executing @kbd{z m} (using the original argument list @samp{(a b)}) with -arguments @expr{10} and @expr{x} will leave the function in symbolic -form, i.e., @samp{yow(10,x)}. On the other hand, if you answer @kbd{n}, -then the formula will always be expanded, even for non-constant -arguments: @samp{10 + 2 x}. If you never plan to feed algebraic -formulas to your new function, it doesn't matter how you answer this -question. - -If you answered @kbd{y} to this question you can still cause a function -call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}). -Also, Calc will expand the function if necessary when you take a -derivative or integral or solve an equation involving the function. - -@kindex Z G -@pindex calc-get-user-defn -Once you have defined a formula on a key, you can retrieve this formula -with the @kbd{Z G} (@code{calc-user-define-get-defn}) command. Press a -key, and this command pushes the formula that was used to define that -key onto the stack. Actually, it pushes a nameless function that -specifies both the argument list and the defining formula. You will get -an error message if the key is undefined, or if the key was not defined -by a @kbd{Z F} command. - -The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has -been defined by a formula uses a variant of the @code{calc-edit} command -to edit the defining formula. Press @kbd{C-c C-c} to finish editing and -store the new formula back in the definition, or kill the buffer with -@kbd{C-x k} to -cancel the edit. (The argument list and other properties of the -definition are unchanged; to adjust the argument list, you can use -@kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and -then re-execute the @kbd{Z F} command.) - -As usual, the @kbd{Z P} command records your definition permanently. -In this case it will permanently record all three of the relevant -definitions: the key, the command, and the function. - -You may find it useful to turn off the default simplifications with -@kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be -used as a function definition. For example, the formula @samp{deriv(a^2,v)} -which might be used to define a new function @samp{dsqr(a,v)} will be -``simplified'' to 0 immediately upon entry since @code{deriv} considers -@expr{a} to be constant with respect to @expr{v}. Turning off -default simplifications cures this problem: The definition will be stored -in symbolic form without ever activating the @code{deriv} function. Press -@kbd{m D} to turn the default simplifications back on afterwards. - -@node Lisp Definitions, , Algebraic Definitions, Programming -@section Programming with Lisp - -@noindent -The Calculator can be programmed quite extensively in Lisp. All you -do is write a normal Lisp function definition, but with @code{defmath} -in place of @code{defun}. This has the same form as @code{defun}, but it -automagically replaces calls to standard Lisp functions like @code{+} and -@code{zerop} with calls to the corresponding functions in Calc's own library. -Thus you can write natural-looking Lisp code which operates on all of the -standard Calculator data types. You can then use @kbd{Z D} if you wish to -bind your new command to a @kbd{z}-prefix key sequence. The @kbd{Z E} command -will not edit a Lisp-based definition. - -Emacs Lisp is described in the GNU Emacs Lisp Reference Manual. This section -assumes a familiarity with Lisp programming concepts; if you do not know -Lisp, you may find keyboard macros or rewrite rules to be an easier way -to program the Calculator. - -This section first discusses ways to write commands, functions, or -small programs to be executed inside of Calc. Then it discusses how -your own separate programs are able to call Calc from the outside. -Finally, there is a list of internal Calc functions and data structures -for the true Lisp enthusiast. - -@menu -* Defining Functions:: -* Defining Simple Commands:: -* Defining Stack Commands:: -* Argument Qualifiers:: -* Example Definitions:: - -* Calling Calc from Your Programs:: -* Internals:: -@end menu - -@node Defining Functions, Defining Simple Commands, Lisp Definitions, Lisp Definitions -@subsection Defining New Functions - -@noindent -@findex defmath -The @code{defmath} function (actually a Lisp macro) is like @code{defun} -except that code in the body of the definition can make use of the full -range of Calculator data types. The prefix @samp{calcFunc-} is added -to the specified name to get the actual Lisp function name. As a simple -example, - -@example -(defmath myfact (n) - (if (> n 0) - (* n (myfact (1- n))) - 1)) -@end example - -@noindent -This actually expands to the code, - -@example -(defun calcFunc-myfact (n) - (if (math-posp n) - (math-mul n (calcFunc-myfact (math-add n -1))) - 1)) -@end example - -@noindent -This function can be used in algebraic expressions, e.g., @samp{myfact(5)}. - -The @samp{myfact} function as it is defined above has the bug that an -expression @samp{myfact(a+b)} will be simplified to 1 because the -formula @samp{a+b} is not considered to be @code{posp}. A robust -factorial function would be written along the following lines: - -@smallexample -(defmath myfact (n) - (if (> n 0) - (* n (myfact (1- n))) - (if (= n 0) - 1 - nil))) ; this could be simplified as: (and (= n 0) 1) -@end smallexample - -If a function returns @code{nil}, it is left unsimplified by the Calculator -(except that its arguments will be simplified). Thus, @samp{myfact(a+1+2)} -will be simplified to @samp{myfact(a+3)} but no further. Beware that every -time the Calculator reexamines this formula it will attempt to resimplify -it, so your function ought to detect the returning-@code{nil} case as -efficiently as possible. - -The following standard Lisp functions are treated by @code{defmath}: -@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or -@code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=}, -@code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor}, -@code{logandc2}, @code{lognot}. Also, @code{~=} is an abbreviation for -@code{math-nearly-equal}, which is useful in implementing Taylor series. - -For other functions @var{func}, if a function by the name -@samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the -name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself -is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is -used on the assumption that this is a to-be-defined math function. Also, if -the function name is quoted as in @samp{('integerp a)} the function name is -always used exactly as written (but not quoted). - -Variable names have @samp{var-} prepended to them unless they appear in -the function's argument list or in an enclosing @code{let}, @code{let*}, -@code{for}, or @code{foreach} form, -or their names already contain a @samp{-} character. Thus a reference to -@samp{foo} is the same as a reference to @samp{var-foo}. - -A few other Lisp extensions are available in @code{defmath} definitions: - -@itemize @bullet -@item -The @code{elt} function accepts any number of index variables. -Note that Calc vectors are stored as Lisp lists whose first -element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields -the second element of vector @code{v}, and @samp{(elt m i j)} -yields one element of a Calc matrix. - -@item -The @code{setq} function has been extended to act like the Common -Lisp @code{setf} function. (The name @code{setf} is recognized as -a synonym of @code{setq}.) Specifically, the first argument of -@code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form, -in which case the effect is to store into the specified -element of a list. Thus, @samp{(setq (elt m i j) x)} stores @expr{x} -into one element of a matrix. - -@item -A @code{for} looping construct is available. For example, -@samp{(for ((i 0 10)) body)} executes @code{body} once for each -binding of @expr{i} from zero to 10. This is like a @code{let} -form in that @expr{i} is temporarily bound to the loop count -without disturbing its value outside the @code{for} construct. -Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)}, -are also available. For each value of @expr{i} from zero to 10, -@expr{j} counts from 0 to @expr{i-1} in steps of two. Note that -@code{for} has the same general outline as @code{let*}, except -that each element of the header is a list of three or four -things, not just two. - -@item -The @code{foreach} construct loops over elements of a list. -For example, @samp{(foreach ((x (cdr v))) body)} executes -@code{body} with @expr{x} bound to each element of Calc vector -@expr{v} in turn. The purpose of @code{cdr} here is to skip over -the initial @code{vec} symbol in the vector. - -@item -The @code{break} function breaks out of the innermost enclosing -@code{while}, @code{for}, or @code{foreach} loop. If given a -value, as in @samp{(break x)}, this value is returned by the -loop. (Lisp loops otherwise always return @code{nil}.) - -@item -The @code{return} function prematurely returns from the enclosing -function. For example, @samp{(return (+ x y))} returns @expr{x+y} -as the value of a function. You can use @code{return} anywhere -inside the body of the function. -@end itemize - -Non-integer numbers (and extremely large integers) cannot be included -directly into a @code{defmath} definition. This is because the Lisp -reader will fail to parse them long before @code{defmath} ever gets control. -Instead, use the notation, @samp{:"3.1415"}. In fact, any algebraic -formula can go between the quotes. For example, - -@smallexample -(defmath sqexp (x) ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5) - (and (numberp x) - (exp :"x * 0.5"))) -@end smallexample - -expands to - -@smallexample -(defun calcFunc-sqexp (x) - (and (math-numberp x) - (calcFunc-exp (math-mul x '(float 5 -1))))) -@end smallexample - -Note the use of @code{numberp} as a guard to ensure that the argument is -a number first, returning @code{nil} if not. The exponential function -could itself have been included in the expression, if we had preferred: -@samp{:"exp(x * 0.5)"}. As another example, the multiplication-and-recursion -step of @code{myfact} could have been written - -@example -:"n * myfact(n-1)" -@end example - -A good place to put your @code{defmath} commands is your Calc init file -(the file given by @code{calc-settings-file}, typically -@file{~/.emacs.d/calc.el}), which will not be loaded until Calc starts. -If a file named @file{.emacs} exists in your home directory, Emacs reads -and executes the Lisp forms in this file as it starts up. While it may -seem reasonable to put your favorite @code{defmath} commands there, -this has the unfortunate side-effect that parts of the Calculator must be -loaded in to process the @code{defmath} commands whether or not you will -actually use the Calculator! If you want to put the @code{defmath} -commands there (for example, if you redefine @code{calc-settings-file} -to be @file{.emacs}), a better effect can be had by writing - -@example -(put 'calc-define 'thing '(progn - (defmath ... ) - (defmath ... ) -)) -@end example - -@noindent -@vindex calc-define -The @code{put} function adds a @dfn{property} to a symbol. Each Lisp -symbol has a list of properties associated with it. Here we add a -property with a name of @code{thing} and a @samp{(progn ...)} form as -its value. When Calc starts up, and at the start of every Calc command, -the property list for the symbol @code{calc-define} is checked and the -values of any properties found are evaluated as Lisp forms. The -properties are removed as they are evaluated. The property names -(like @code{thing}) are not used; you should choose something like the -name of your project so as not to conflict with other properties. - -The net effect is that you can put the above code in your @file{.emacs} -file and it will not be executed until Calc is loaded. Or, you can put -that same code in another file which you load by hand either before or -after Calc itself is loaded. - -The properties of @code{calc-define} are evaluated in the same order -that they were added. They can assume that the Calc modules @file{calc.el}, -@file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and -that the @file{*Calculator*} buffer will be the current buffer. - -If your @code{calc-define} property only defines algebraic functions, -you can be sure that it will have been evaluated before Calc tries to -call your function, even if the file defining the property is loaded -after Calc is loaded. But if the property defines commands or key -sequences, it may not be evaluated soon enough. (Suppose it defines the -new command @code{tweak-calc}; the user can load your file, then type -@kbd{M-x tweak-calc} before Calc has had chance to do anything.) To -protect against this situation, you can put - -@example -(run-hooks 'calc-check-defines) -@end example - -@findex calc-check-defines -@noindent -at the end of your file. The @code{calc-check-defines} function is what -looks for and evaluates properties on @code{calc-define}; @code{run-hooks} -has the advantage that it is quietly ignored if @code{calc-check-defines} -is not yet defined because Calc has not yet been loaded. - -Examples of things that ought to be enclosed in a @code{calc-define} -property are @code{defmath} calls, @code{define-key} calls that modify -the Calc key map, and any calls that redefine things defined inside Calc. -Ordinary @code{defun}s need not be enclosed with @code{calc-define}. - -@node Defining Simple Commands, Defining Stack Commands, Defining Functions, Lisp Definitions -@subsection Defining New Simple Commands - -@noindent -@findex interactive -If a @code{defmath} form contains an @code{interactive} clause, it defines -a Calculator command. Actually such a @code{defmath} results in @emph{two} -function definitions: One, a @samp{calcFunc-} function as was just described, -with the @code{interactive} clause removed. Two, a @samp{calc-} function -with a suitable @code{interactive} clause and some sort of wrapper to make -the command work in the Calc environment. - -In the simple case, the @code{interactive} clause has the same form as -for normal Emacs Lisp commands: - -@smallexample -(defmath increase-precision (delta) - "Increase precision by DELTA." ; This is the "documentation string" - (interactive "p") ; Register this as a M-x-able command - (setq calc-internal-prec (+ calc-internal-prec delta))) -@end smallexample - -This expands to the pair of definitions, - -@smallexample -(defun calc-increase-precision (delta) - "Increase precision by DELTA." - (interactive "p") - (calc-wrapper - (setq calc-internal-prec (math-add calc-internal-prec delta)))) - -(defun calcFunc-increase-precision (delta) - "Increase precision by DELTA." - (setq calc-internal-prec (math-add calc-internal-prec delta))) -@end smallexample - -@noindent -where in this case the latter function would never really be used! Note -that since the Calculator stores small integers as plain Lisp integers, -the @code{math-add} function will work just as well as the native -@code{+} even when the intent is to operate on native Lisp integers. - -@findex calc-wrapper -The @samp{calc-wrapper} call invokes a macro which surrounds the body of -the function with code that looks roughly like this: - -@smallexample -(let ((calc-command-flags nil)) - (unwind-protect - (save-current-buffer - (calc-select-buffer) - @emph{body of function} - @emph{renumber stack} - @emph{clear} Working @emph{message}) - @emph{realign cursor and window} - @emph{clear Inverse, Hyperbolic, and Keep Args flags} - @emph{update Emacs mode line})) -@end smallexample - -@findex calc-select-buffer -The @code{calc-select-buffer} function selects the @file{*Calculator*} -buffer if necessary, say, because the command was invoked from inside -the @file{*Calc Trail*} window. - -@findex calc-set-command-flag -You can call, for example, @code{(calc-set-command-flag 'no-align)} to -set the above-mentioned command flags. Calc routines recognize the -following command flags: - -@table @code -@item renum-stack -Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered -after this command completes. This is set by routines like -@code{calc-push}. - -@item clear-message -Calc should call @samp{(message "")} if this command completes normally -(to clear a ``Working@dots{}'' message out of the echo area). - -@item no-align -Do not move the cursor back to the @samp{.} top-of-stack marker. - -@item position-point -Use the variables @code{calc-position-point-line} and -@code{calc-position-point-column} to position the cursor after -this command finishes. - -@item keep-flags -Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag}, -and @code{calc-keep-args-flag} at the end of this command. - -@item do-edit -Switch to buffer @file{*Calc Edit*} after this command. - -@item hold-trail -Do not move trail pointer to end of trail when something is recorded -there. -@end table - -@kindex Y -@kindex Y ? -@vindex calc-Y-help-msgs -Calc reserves a special prefix key, shift-@kbd{Y}, for user-written -extensions to Calc. There are no built-in commands that work with -this prefix key; you must call @code{define-key} from Lisp (probably -from inside a @code{calc-define} property) to add to it. Initially only -@kbd{Y ?} is defined; it takes help messages from a list of strings -(initially @code{nil}) in the variable @code{calc-Y-help-msgs}. All -other undefined keys except for @kbd{Y} are reserved for use by -future versions of Calc. - -If you are writing a Calc enhancement which you expect to give to -others, it is best to minimize the number of @kbd{Y}-key sequences -you use. In fact, if you have more than one key sequence you should -consider defining three-key sequences with a @kbd{Y}, then a key that -stands for your package, then a third key for the particular command -within your package. - -Users may wish to install several Calc enhancements, and it is possible -that several enhancements will choose to use the same key. In the -example below, a variable @code{inc-prec-base-key} has been defined -to contain the key that identifies the @code{inc-prec} package. Its -value is initially @code{"P"}, but a user can change this variable -if necessary without having to modify the file. - -Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I} -command that increases the precision, and a @kbd{Y P D} command that -decreases the precision. - -@smallexample -;;; Increase and decrease Calc precision. Dave Gillespie, 5/31/91. -;; (Include copyright or copyleft stuff here.) - -(defvar inc-prec-base-key "P" - "Base key for inc-prec.el commands.") - -(put 'calc-define 'inc-prec '(progn - -(define-key calc-mode-map (format "Y%sI" inc-prec-base-key) - 'increase-precision) -(define-key calc-mode-map (format "Y%sD" inc-prec-base-key) - 'decrease-precision) - -(setq calc-Y-help-msgs - (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key) - calc-Y-help-msgs)) - -(defmath increase-precision (delta) - "Increase precision by DELTA." - (interactive "p") - (setq calc-internal-prec (+ calc-internal-prec delta))) - -(defmath decrease-precision (delta) - "Decrease precision by DELTA." - (interactive "p") - (setq calc-internal-prec (- calc-internal-prec delta))) - -)) ; end of calc-define property - -(run-hooks 'calc-check-defines) -@end smallexample - -@node Defining Stack Commands, Argument Qualifiers, Defining Simple Commands, Lisp Definitions -@subsection Defining New Stack-Based Commands - -@noindent -To define a new computational command which takes and/or leaves arguments -on the stack, a special form of @code{interactive} clause is used. - -@example -(interactive @var{num} @var{tag}) -@end example - -@noindent -where @var{num} is an integer, and @var{tag} is a string. The effect is -to pop @var{num} values off the stack, resimplify them by calling -@code{calc-normalize}, and hand them to your function according to the -function's argument list. Your function may include @code{&optional} and -@code{&rest} parameters, so long as calling the function with @var{num} -parameters is valid. - -Your function must return either a number or a formula in a form -acceptable to Calc, or a list of such numbers or formulas. These value(s) -are pushed onto the stack when the function completes. They are also -recorded in the Calc Trail buffer on a line beginning with @var{tag}, -a string of (normally) four characters or less. If you omit @var{tag} -or use @code{nil} as a tag, the result is not recorded in the trail. - -As an example, the definition - -@smallexample -(defmath myfact (n) - "Compute the factorial of the integer at the top of the stack." - (interactive 1 "fact") - (if (> n 0) - (* n (myfact (1- n))) - (and (= n 0) 1))) -@end smallexample - -@noindent -is a version of the factorial function shown previously which can be used -as a command as well as an algebraic function. It expands to - -@smallexample -(defun calc-myfact () - "Compute the factorial of the integer at the top of the stack." - (interactive) - (calc-slow-wrapper - (calc-enter-result 1 "fact" - (cons 'calcFunc-myfact (calc-top-list-n 1))))) - -(defun calcFunc-myfact (n) - "Compute the factorial of the integer at the top of the stack." - (if (math-posp n) - (math-mul n (calcFunc-myfact (math-add n -1))) - (and (math-zerop n) 1))) -@end smallexample - -@findex calc-slow-wrapper -The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper} -that automatically puts up a @samp{Working...} message before the -computation begins. (This message can be turned off by the user -with an @kbd{m w} (@code{calc-working}) command.) - -@findex calc-top-list-n -The @code{calc-top-list-n} function returns a list of the specified number -of values from the top of the stack. It resimplifies each value by -calling @code{calc-normalize}. If its argument is zero it returns an -empty list. It does not actually remove these values from the stack. - -@findex calc-enter-result -The @code{calc-enter-result} function takes an integer @var{num} and string -@var{tag} as described above, plus a third argument which is either a -Calculator data object or a list of such objects. These objects are -resimplified and pushed onto the stack after popping the specified number -of values from the stack. If @var{tag} is non-@code{nil}, the values -being pushed are also recorded in the trail. - -Note that if @code{calcFunc-myfact} returns @code{nil} this represents -``leave the function in symbolic form.'' To return an actual empty list, -in the sense that @code{calc-enter-result} will push zero elements back -onto the stack, you should return the special value @samp{'(nil)}, a list -containing the single symbol @code{nil}. - -The @code{interactive} declaration can actually contain a limited -Emacs-style code string as well which comes just before @var{num} and -@var{tag}. Currently the only Emacs code supported is @samp{"p"}, as in - -@example -(defmath foo (a b &optional c) - (interactive "p" 2 "foo") - @var{body}) -@end example - -In this example, the command @code{calc-foo} will evaluate the expression -@samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if -executed with a numeric prefix argument of @expr{n}. - -The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"} -code as used with @code{defun}). It uses the numeric prefix argument as the -number of objects to remove from the stack and pass to the function. -In this case, the integer @var{num} serves as a default number of -arguments to be used when no prefix is supplied. - -@node Argument Qualifiers, Example Definitions, Defining Stack Commands, Lisp Definitions -@subsection Argument Qualifiers - -@noindent -Anywhere a parameter name can appear in the parameter list you can also use -an @dfn{argument qualifier}. Thus the general form of a definition is: - -@example -(defmath @var{name} (@var{param} @var{param...} - &optional @var{param} @var{param...} - &rest @var{param}) - @var{body}) -@end example - -@noindent -where each @var{param} is either a symbol or a list of the form - -@example -(@var{qual} @var{param}) -@end example - -The following qualifiers are recognized: - -@table @samp -@item complete -@findex complete -The argument must not be an incomplete vector, interval, or complex number. -(This is rarely needed since the Calculator itself will never call your -function with an incomplete argument. But there is nothing stopping your -own Lisp code from calling your function with an incomplete argument.) - -@item integer -@findex integer -The argument must be an integer. If it is an integer-valued float -it will be accepted but converted to integer form. Non-integers and -formulas are rejected. - -@item natnum -@findex natnum -Like @samp{integer}, but the argument must be non-negative. - -@item fixnum -@findex fixnum -Like @samp{integer}, but the argument must fit into a native Lisp integer, -which on most systems means less than 2^23 in absolute value. The -argument is converted into Lisp-integer form if necessary. - -@item float -@findex float -The argument is converted to floating-point format if it is a number or -vector. If it is a formula it is left alone. (The argument is never -actually rejected by this qualifier.) - -@item @var{pred} -The argument must satisfy predicate @var{pred}, which is one of the -standard Calculator predicates. @xref{Predicates}. - -@item not-@var{pred} -The argument must @emph{not} satisfy predicate @var{pred}. -@end table - -For example, - -@example -(defmath foo (a (constp (not-matrixp b)) &optional (float c) - &rest (integer d)) - @var{body}) -@end example - -@noindent -expands to - -@example -(defun calcFunc-foo (a b &optional c &rest d) - (and (math-matrixp b) - (math-reject-arg b 'not-matrixp)) - (or (math-constp b) - (math-reject-arg b 'constp)) - (and c (setq c (math-check-float c))) - (setq d (mapcar 'math-check-integer d)) - @var{body}) -@end example - -@noindent -which performs the necessary checks and conversions before executing the -body of the function. - -@node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions -@subsection Example Definitions - -@noindent -This section includes some Lisp programming examples on a larger scale. -These programs make use of some of the Calculator's internal functions; -@pxref{Internals}. - -@menu -* Bit Counting Example:: -* Sine Example:: -@end menu - -@node Bit Counting Example, Sine Example, Example Definitions, Example Definitions -@subsubsection Bit-Counting - -@noindent -@ignore -@starindex -@end ignore -@tindex bcount -Calc does not include a built-in function for counting the number of -``one'' bits in a binary integer. It's easy to invent one using @kbd{b u} -to convert the integer to a set, and @kbd{V #} to count the elements of -that set; let's write a function that counts the bits without having to -create an intermediate set. - -@smallexample -(defmath bcount ((natnum n)) - (interactive 1 "bcnt") - (let ((count 0)) - (while (> n 0) - (if (oddp n) - (setq count (1+ count))) - (setq n (lsh n -1))) - count)) -@end smallexample - -@noindent -When this is expanded by @code{defmath}, it will become the following -Emacs Lisp function: - -@smallexample -(defun calcFunc-bcount (n) - (setq n (math-check-natnum n)) - (let ((count 0)) - (while (math-posp n) - (if (math-oddp n) - (setq count (math-add count 1))) - (setq n (calcFunc-lsh n -1))) - count)) -@end smallexample - -If the input numbers are large, this function involves a fair amount -of arithmetic. A binary right shift is essentially a division by two; -recall that Calc stores integers in decimal form so bit shifts must -involve actual division. - -To gain a bit more efficiency, we could divide the integer into -@var{n}-bit chunks, each of which can be handled quickly because -they fit into Lisp integers. It turns out that Calc's arithmetic -routines are especially fast when dividing by an integer less than -1000, so we can set @var{n = 9} bits and use repeated division by 512: - -@smallexample -(defmath bcount ((natnum n)) - (interactive 1 "bcnt") - (let ((count 0)) - (while (not (fixnump n)) - (let ((qr (idivmod n 512))) - (setq count (+ count (bcount-fixnum (cdr qr))) - n (car qr)))) - (+ count (bcount-fixnum n)))) - -(defun bcount-fixnum (n) - (let ((count 0)) - (while (> n 0) - (setq count (+ count (logand n 1)) - n (lsh n -1))) - count)) -@end smallexample - -@noindent -Note that the second function uses @code{defun}, not @code{defmath}. -Because this function deals only with native Lisp integers (``fixnums''), -it can use the actual Emacs @code{+} and related functions rather -than the slower but more general Calc equivalents which @code{defmath} -uses. - -The @code{idivmod} function does an integer division, returning both -the quotient and the remainder at once. Again, note that while it -might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are -more efficient ways to split off the bottom nine bits of @code{n}, -actually they are less efficient because each operation is really -a division by 512 in disguise; @code{idivmod} allows us to do the -same thing with a single division by 512. - -@node Sine Example, , Bit Counting Example, Example Definitions -@subsubsection The Sine Function - -@noindent -@ignore -@starindex -@end ignore -@tindex mysin -A somewhat limited sine function could be defined as follows, using the -well-known Taylor series expansion for -@texline @math{\sin x}: -@infoline @samp{sin(x)}: - -@smallexample -(defmath mysin ((float (anglep x))) - (interactive 1 "mysn") - (setq x (to-radians x)) ; Convert from current angular mode. - (let ((sum x) ; Initial term of Taylor expansion of sin. - newsum - (nfact 1) ; "nfact" equals "n" factorial at all times. - (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2. - (for ((n 3 100 2)) ; Upper limit of 100 is a good precaution. - (working "mysin" sum) ; Display "Working" message, if enabled. - (setq nfact (* nfact (1- n) n) - x (* x xnegsqr) - newsum (+ sum (/ x nfact))) - (if (~= newsum sum) ; If newsum is "nearly equal to" sum, - (break)) ; then we are done. - (setq sum newsum)) - sum)) -@end smallexample - -The actual @code{sin} function in Calc works by first reducing the problem -to a sine or cosine of a nonnegative number less than @cpiover{4}. This -ensures that the Taylor series will converge quickly. Also, the calculation -is carried out with two extra digits of precision to guard against cumulative -round-off in @samp{sum}. Finally, complex arguments are allowed and handled -by a separate algorithm. - -@smallexample -(defmath mysin ((float (scalarp x))) - (interactive 1 "mysn") - (setq x (to-radians x)) ; Convert from current angular mode. - (with-extra-prec 2 ; Evaluate with extra precision. - (cond ((complexp x) - (mysin-complex x)) - ((< x 0) - (- (mysin-raw (- x))) ; Always call mysin-raw with x >= 0. - (t (mysin-raw x)))))) - -(defmath mysin-raw (x) - (cond ((>= x 7) - (mysin-raw (% x (two-pi)))) ; Now x < 7. - ((> x (pi-over-2)) - (- (mysin-raw (- x (pi))))) ; Now -pi/2 <= x <= pi/2. - ((> x (pi-over-4)) - (mycos-raw (- x (pi-over-2)))) ; Now -pi/2 <= x <= pi/4. - ((< x (- (pi-over-4))) - (- (mycos-raw (+ x (pi-over-2))))) ; Now -pi/4 <= x <= pi/4, - (t (mysin-series x)))) ; so the series will be efficient. -@end smallexample - -@noindent -where @code{mysin-complex} is an appropriate function to handle complex -numbers, @code{mysin-series} is the routine to compute the sine Taylor -series as before, and @code{mycos-raw} is a function analogous to -@code{mysin-raw} for cosines. - -The strategy is to ensure that @expr{x} is nonnegative before calling -@code{mysin-raw}. This function then recursively reduces its argument -to a suitable range, namely, plus-or-minus @cpiover{4}. Note that each -test, and particularly the first comparison against 7, is designed so -that small roundoff errors cannot produce an infinite loop. (Suppose -we compared with @samp{(two-pi)} instead; if due to roundoff problems -the modulo operator ever returned @samp{(two-pi)} exactly, an infinite -recursion could result!) We use modulo only for arguments that will -clearly get reduced, knowing that the next rule will catch any reductions -that this rule misses. - -If a program is being written for general use, it is important to code -it carefully as shown in this second example. For quick-and-dirty programs, -when you know that your own use of the sine function will never encounter -a large argument, a simpler program like the first one shown is fine. - -@node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions -@subsection Calling Calc from Your Lisp Programs - -@noindent -A later section (@pxref{Internals}) gives a full description of -Calc's internal Lisp functions. It's not hard to call Calc from -inside your programs, but the number of these functions can be daunting. -So Calc provides one special ``programmer-friendly'' function called -@code{calc-eval} that can be made to do just about everything you -need. It's not as fast as the low-level Calc functions, but it's -much simpler to use! - -It may seem that @code{calc-eval} itself has a daunting number of -options, but they all stem from one simple operation. - -In its simplest manifestation, @samp{(calc-eval "1+2")} parses the -string @code{"1+2"} as if it were a Calc algebraic entry and returns -the result formatted as a string: @code{"3"}. - -Since @code{calc-eval} is on the list of recommended @code{autoload} -functions, you don't need to make any special preparations to load -Calc before calling @code{calc-eval} the first time. Calc will be -loaded and initialized for you. - -All the Calc modes that are currently in effect will be used when -evaluating the expression and formatting the result. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Additional Arguments to @code{calc-eval} - -@noindent -If the input string parses to a list of expressions, Calc returns -the results separated by @code{", "}. You can specify a different -separator by giving a second string argument to @code{calc-eval}: -@samp{(calc-eval "1+2,3+4" ";")} returns @code{"3;7"}. - -The ``separator'' can also be any of several Lisp symbols which -request other behaviors from @code{calc-eval}. These are discussed -one by one below. - -You can give additional arguments to be substituted for -@samp{$}, @samp{$$}, and so on in the main expression. For -example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the -expression @code{"7/(1+1)"} to yield the result @code{"3.5"} -(assuming Fraction mode is not in effect). Note the @code{nil} -used as a placeholder for the item-separator argument. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Error Handling - -@noindent -If @code{calc-eval} encounters an error, it returns a list containing -the character position of the error, plus a suitable message as a -string. Note that @samp{1 / 0} is @emph{not} an error by Calc's -standards; it simply returns the string @code{"1 / 0"} which is the -division left in symbolic form. But @samp{(calc-eval "1/")} will -return the list @samp{(2 "Expected a number")}. - -If you bind the variable @code{calc-eval-error} to @code{t} -using a @code{let} form surrounding the call to @code{calc-eval}, -errors instead call the Emacs @code{error} function which aborts -to the Emacs command loop with a beep and an error message. - -If you bind this variable to the symbol @code{string}, error messages -are returned as strings instead of lists. The character position is -ignored. - -As a courtesy to other Lisp code which may be using Calc, be sure -to bind @code{calc-eval-error} using @code{let} rather than changing -it permanently with @code{setq}. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Numbers Only - -@noindent -Sometimes it is preferable to treat @samp{1 / 0} as an error -rather than returning a symbolic result. If you pass the symbol -@code{num} as the second argument to @code{calc-eval}, results -that are not constants are treated as errors. The error message -reported is the first @code{calc-why} message if there is one, -or otherwise ``Number expected.'' - -A result is ``constant'' if it is a number, vector, or other -object that does not include variables or function calls. If it -is a vector, the components must themselves be constants. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Default Modes - -@noindent -If the first argument to @code{calc-eval} is a list whose first -element is a formula string, then @code{calc-eval} sets all the -various Calc modes to their default values while the formula is -evaluated and formatted. For example, the precision is set to 12 -digits, digit grouping is turned off, and the Normal language -mode is used. - -This same principle applies to the other options discussed below. -If the first argument would normally be @var{x}, then it can also -be the list @samp{(@var{x})} to use the default mode settings. - -If there are other elements in the list, they are taken as -variable-name/value pairs which override the default mode -settings. Look at the documentation at the front of the -@file{calc.el} file to find the names of the Lisp variables for -the various modes. The mode settings are restored to their -original values when @code{calc-eval} is done. - -For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)} -computes the sum of two numbers, requiring a numeric result, and -using default mode settings except that the precision is 8 instead -of the default of 12. - -It's usually best to use this form of @code{calc-eval} unless your -program actually considers the interaction with Calc's mode settings -to be a feature. This will avoid all sorts of potential ``gotchas''; -consider what happens with @samp{(calc-eval "sqrt(2)" 'num)} -when the user has left Calc in Symbolic mode or No-Simplify mode. - -As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")} -checks if the number in string @expr{a} is less than the one in -string @expr{b}. Without using a list, the integer 1 might -come out in a variety of formats which would be hard to test for -conveniently: @code{"1"}, @code{"8#1"}, @code{"00001"}. (But -see ``Predicates'' mode, below.) - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Raw Numbers - -@noindent -Normally all input and output for @code{calc-eval} is done with strings. -You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)} -in place of @samp{(+ a b)}, but this is very inefficient since the -numbers must be converted to and from string format as they are passed -from one @code{calc-eval} to the next. - -If the separator is the symbol @code{raw}, the result will be returned -as a raw Calc data structure rather than a string. You can read about -how these objects look in the following sections, but usually you can -treat them as ``black box'' objects with no important internal -structure. - -There is also a @code{rawnum} symbol, which is a combination of -@code{raw} (returning a raw Calc object) and @code{num} (signaling -an error if that object is not a constant). - -You can pass a raw Calc object to @code{calc-eval} in place of a -string, either as the formula itself or as one of the @samp{$} -arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an -addition function that operates on raw Calc objects. Of course -in this case it would be easier to call the low-level @code{math-add} -function in Calc, if you can remember its name. - -In particular, note that a plain Lisp integer is acceptable to Calc -as a raw object. (All Lisp integers are accepted on input, but -integers of more than six decimal digits are converted to ``big-integer'' -form for output. @xref{Data Type Formats}.) - -When it comes time to display the object, just use @samp{(calc-eval a)} -to format it as a string. - -It is an error if the input expression evaluates to a list of -values. The separator symbol @code{list} is like @code{raw} -except that it returns a list of one or more raw Calc objects. - -Note that a Lisp string is not a valid Calc object, nor is a list -containing a string. Thus you can still safely distinguish all the -various kinds of error returns discussed above. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Predicates - -@noindent -If the separator symbol is @code{pred}, the result of the formula is -treated as a true/false value; @code{calc-eval} returns @code{t} or -@code{nil}, respectively. A value is considered ``true'' if it is a -non-zero number, or false if it is zero or if it is not a number. - -For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether -one value is less than another. - -As usual, it is also possible for @code{calc-eval} to return one of -the error indicators described above. Lisp will interpret such an -indicator as ``true'' if you don't check for it explicitly. If you -wish to have an error register as ``false'', use something like -@samp{(eq (calc-eval ...) t)}. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Variable Values - -@noindent -Variables in the formula passed to @code{calc-eval} are not normally -replaced by their values. If you wish this, you can use the -@code{evalv} function (@pxref{Algebraic Manipulation}). For example, -if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable -@code{var-a}), then @samp{(calc-eval "a+pi")} will return the -formula @code{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")} -will return @code{"7.14159265359"}. - -To store in a Calc variable, just use @code{setq} to store in the -corresponding Lisp variable. (This is obtained by prepending -@samp{var-} to the Calc variable name.) Calc routines will -understand either string or raw form values stored in variables, -although raw data objects are much more efficient. For example, -to increment the Calc variable @code{a}: - -@example -(setq var-a (calc-eval "evalv(a+1)" 'raw)) -@end example - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Stack Access - -@noindent -If the separator symbol is @code{push}, the formula argument is -evaluated (with possible @samp{$} expansions, as usual). The -result is pushed onto the Calc stack. The return value is @code{nil} -(unless there is an error from evaluating the formula, in which -case the return value depends on @code{calc-eval-error} in the -usual way). - -If the separator symbol is @code{pop}, the first argument to -@code{calc-eval} must be an integer instead of a string. That -many values are popped from the stack and thrown away. A negative -argument deletes the entry at that stack level. The return value -is the number of elements remaining in the stack after popping; -@samp{(calc-eval 0 'pop)} is a good way to measure the size of -the stack. - -If the separator symbol is @code{top}, the first argument to -@code{calc-eval} must again be an integer. The value at that -stack level is formatted as a string and returned. Thus -@samp{(calc-eval 1 'top)} returns the top-of-stack value. If the -integer is out of range, @code{nil} is returned. - -The separator symbol @code{rawtop} is just like @code{top} except -that the stack entry is returned as a raw Calc object instead of -as a string. - -In all of these cases the first argument can be made a list in -order to force the default mode settings, as described above. -Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the -second-to-top stack entry, formatted as a string using the default -instead of current display modes, except that the radix is -hexadecimal instead of decimal. - -It is, of course, polite to put the Calc stack back the way you -found it when you are done, unless the user of your program is -actually expecting it to affect the stack. - -Note that you do not actually have to switch into the @file{*Calculator*} -buffer in order to use @code{calc-eval}; it temporarily switches into -the stack buffer if necessary. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Keyboard Macros - -@noindent -If the separator symbol is @code{macro}, the first argument must be a -string of characters which Calc can execute as a sequence of keystrokes. -This switches into the Calc buffer for the duration of the macro. -For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the -vector @samp{[1,2,3,4,5]} on the stack and then replaces it -with the sum of those numbers. Note that @samp{\r} is the Lisp -notation for the carriage-return, @key{RET}, character. - -If your keyboard macro wishes to pop the stack, @samp{\C-d} is -safer than @samp{\177} (the @key{DEL} character) because some -installations may have switched the meanings of @key{DEL} and -@kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for -``pop-stack'' regardless of key mapping. - -If you provide a third argument to @code{calc-eval}, evaluation -of the keyboard macro will leave a record in the Trail using -that argument as a tag string. Normally the Trail is unaffected. - -The return value in this case is always @code{nil}. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Lisp Evaluation - -@noindent -Finally, if the separator symbol is @code{eval}, then the Lisp -@code{eval} function is called on the first argument, which must -be a Lisp expression rather than a Calc formula. Remember to -quote the expression so that it is not evaluated until inside -@code{calc-eval}. - -The difference from plain @code{eval} is that @code{calc-eval} -switches to the Calc buffer before evaluating the expression. -For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)} -will correctly affect the buffer-local Calc precision variable. - -An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}. -This is evaluating a call to the function that is normally invoked -by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.'' -Note that this function will leave a message in the echo area as -a side effect. Also, all Calc functions switch to the Calc buffer -automatically if not invoked from there, so the above call is -also equivalent to @samp{(calc-precision 17)} by itself. -In all cases, Calc uses @code{save-excursion} to switch back to -your original buffer when it is done. - -As usual the first argument can be a list that begins with a Lisp -expression to use default instead of current mode settings. - -The result of @code{calc-eval} in this usage is just the result -returned by the evaluated Lisp expression. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Example - -@noindent -@findex convert-temp -Here is a sample Emacs command that uses @code{calc-eval}. Suppose -you have a document with lots of references to temperatures on the -Fahrenheit scale, say ``98.6 F'', and you wish to convert these -references to Centigrade. The following command does this conversion. -Place the Emacs cursor right after the letter ``F'' and invoke the -command to change ``98.6 F'' to ``37 C''. Or, if the temperature is -already in Centigrade form, the command changes it back to Fahrenheit. - -@example -(defun convert-temp () - (interactive) - (save-excursion - (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)") - (let* ((top1 (match-beginning 1)) - (bot1 (match-end 1)) - (number (buffer-substring top1 bot1)) - (top2 (match-beginning 2)) - (bot2 (match-end 2)) - (type (buffer-substring top2 bot2))) - (if (equal type "F") - (setq type "C" - number (calc-eval "($ - 32)*5/9" nil number)) - (setq type "F" - number (calc-eval "$*9/5 + 32" nil number))) - (goto-char top2) - (delete-region top2 bot2) - (insert-before-markers type) - (goto-char top1) - (delete-region top1 bot1) - (if (string-match "\\.$" number) ; change "37." to "37" - (setq number (substring number 0 -1))) - (insert number)))) -@end example - -Note the use of @code{insert-before-markers} when changing between -``F'' and ``C'', so that the character winds up before the cursor -instead of after it. - -@node Internals, , Calling Calc from Your Programs, Lisp Definitions -@subsection Calculator Internals - -@noindent -This section describes the Lisp functions defined by the Calculator that -may be of use to user-written Calculator programs (as described in the -rest of this chapter). These functions are shown by their names as they -conventionally appear in @code{defmath}. Their full Lisp names are -generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their -apparent names. (Names that begin with @samp{calc-} are already in -their full Lisp form.) You can use the actual full names instead if you -prefer them, or if you are calling these functions from regular Lisp. - -The functions described here are scattered throughout the various -Calc component files. Note that @file{calc.el} includes @code{autoload}s -for only a few component files; when Calc wants to call an advanced -function it calls @samp{(calc-extensions)} first; this function -autoloads @file{calc-ext.el}, which in turn autoloads all the functions -in the remaining component files. - -Because @code{defmath} itself uses the extensions, user-written code -generally always executes with the extensions already loaded, so -normally you can use any Calc function and be confident that it will -be autoloaded for you when necessary. If you are doing something -special, check carefully to make sure each function you are using is -from @file{calc.el} or its components, and call @samp{(calc-extensions)} -before using any function based in @file{calc-ext.el} if you can't -prove this file will already be loaded. - -@menu -* Data Type Formats:: -* Interactive Lisp Functions:: -* Stack Lisp Functions:: -* Predicates:: -* Computational Lisp Functions:: -* Vector Lisp Functions:: -* Symbolic Lisp Functions:: -* Formatting Lisp Functions:: -* Hooks:: -@end menu - -@node Data Type Formats, Interactive Lisp Functions, Internals, Internals -@subsubsection Data Type Formats - -@noindent -Integers are stored in either of two ways, depending on their magnitude. -Integers less than one million in absolute value are stored as standard -Lisp integers. This is the only storage format for Calc data objects -which is not a Lisp list. - -Large integers are stored as lists of the form @samp{(bigpos @var{d0} -@var{d1} @var{d2} @dots{})} for sufficiently large positive integers -(where ``sufficiently large'' depends on the machine), or -@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative -integers. Each @var{d} is a base-@expr{10^n} ``digit'' (where again, -@expr{n} depends on the machine), a Lisp integer from 0 to -99@dots{}9. The least significant digit is @var{d0}; the last digit, -@var{dn}, which is always nonzero, is the most significant digit. For -example, the integer @mathit{-12345678} might be stored as -@samp{(bigneg 678 345 12)}. - -The distinction between small and large integers is entirely hidden from -the user. In @code{defmath} definitions, the Lisp predicate @code{integerp} -returns true for either kind of integer, and in general both big and small -integers are accepted anywhere the word ``integer'' is used in this manual. -If the distinction must be made, native Lisp integers are called @dfn{fixnums} -and large integers are called @dfn{bignums}. - -Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})} -where @var{n} is an integer (big or small) numerator, @var{d} is an -integer denominator greater than one, and @var{n} and @var{d} are relatively -prime. Note that fractions where @var{d} is one are automatically converted -to plain integers by all math routines; fractions where @var{d} is negative -are normalized by negating the numerator and denominator. - -Floating-point numbers are stored in the form, @samp{(float @var{mant} -@var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than -@samp{10^@var{p}} in absolute value (@var{p} represents the current -precision), and @var{exp} (the ``exponent'') is a fixnum. The value of -the float is @samp{@var{mant} * 10^@var{exp}}. For example, the number -@mathit{-3.14} is stored as @samp{(float -314 -2) = -314*10^-2}. Other constraints -are that the number 0.0 is always stored as @samp{(float 0 0)}, and, -except for the 0.0 case, the rightmost base-10 digit of @var{mant} is -always nonzero. (If the rightmost digit is zero, the number is -rearranged by dividing @var{mant} by ten and incrementing @var{exp}.) - -Rectangular complex numbers are stored in the form @samp{(cplx @var{re} -@var{im})}, where @var{re} and @var{im} are each real numbers, either -integers, fractions, or floats. The value is @samp{@var{re} + @var{im}i}. -The @var{im} part is nonzero; complex numbers with zero imaginary -components are converted to real numbers automatically. - -Polar complex numbers are stored in the form @samp{(polar @var{r} -@var{theta})}, where @var{r} is a positive real value and @var{theta} -is a real value or HMS form representing an angle. This angle is -usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees, -or @samp{(-pi ..@: pi)} radians, according to the current angular mode. -If the angle is 0 the value is converted to a real number automatically. -(If the angle is 180 degrees, the value is usually also converted to a -negative real number.) - -Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m} -@var{s})}, where @var{h} is an integer or an integer-valued float (i.e., -a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued -float in the range @w{@samp{[0 ..@: 60)}}, and @var{s} is any real number -in the range @samp{[0 ..@: 60)}. - -Date forms are stored as @samp{(date @var{n})}, where @var{n} is -a real number that counts days since midnight on the morning of -January 1, 1 AD@. If @var{n} is an integer, this is a pure date -form. If @var{n} is a fraction or float, this is a date/time form. - -Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a -positive real number or HMS form, and @var{n} is a real number or HMS -form in the range @samp{[0 ..@: @var{m})}. - -Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x} -is the mean value and @var{sigma} is the standard deviation. Each -component is either a number, an HMS form, or a symbolic object -(a variable or function call). If @var{sigma} is zero, the value is -converted to a plain real number. If @var{sigma} is negative or -complex, it is automatically normalized to be a positive real. - -Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})}, -where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and -@var{hi} are real numbers, HMS forms, or symbolic objects. The @var{mask} -is a binary integer where 1 represents the fact that the interval is -closed on the high end, and 2 represents the fact that it is closed on -the low end. (Thus 3 represents a fully closed interval.) The interval -@w{@samp{(intv 3 @var{x} @var{x})}} is converted to the plain number @var{x}; -intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask} -represent empty intervals. If @var{hi} is less than @var{lo}, the interval -is converted to a standard empty interval by replacing @var{hi} with @var{lo}. - -Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1} -is the first element of the vector, @var{v2} is the second, and so on. -An empty vector is stored as @samp{(vec)}. A matrix is simply a vector -where all @var{v}'s are themselves vectors of equal lengths. Note that -Calc vectors are unrelated to the Emacs Lisp ``vector'' type, which is -generally unused by Calc data structures. - -Variables are stored as @samp{(var @var{name} @var{sym})}, where -@var{name} is a Lisp symbol whose print name is used as the visible name -of the variable, and @var{sym} is a Lisp symbol in which the variable's -value is actually stored. Thus, @samp{(var pi var-pi)} represents the -special constant @samp{pi}. Almost always, the form is @samp{(var -@var{v} var-@var{v})}. If the variable name was entered with @code{#} -signs (which are converted to hyphens internally), the form is -@samp{(var @var{u} @var{v})}, where @var{u} is a symbol whose name -contains @code{#} characters, and @var{v} is a symbol that contains -@code{-} characters instead. The value of a variable is the Calc -object stored in its @var{sym} symbol's value cell. If the symbol's -value cell is void or if it contains @code{nil}, the variable has no -value. Special constants have the form @samp{(special-const -@var{value})} stored in their value cell, where @var{value} is a formula -which is evaluated when the constant's value is requested. Variables -which represent units are not stored in any special way; they are units -only because their names appear in the units table. If the value -cell contains a string, it is parsed to get the variable's value when -the variable is used. - -A Lisp list with any other symbol as the first element is a function call. -The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^}, -and @code{|} represent special binary operators; these lists are always -of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the -sub-formula on the lefthand side and @var{rhs} is the sub-formula on the -right. The symbol @code{neg} represents unary negation; this list is always -of the form @samp{(neg @var{arg})}. Any other symbol @var{func} represents a -function that would be displayed in function-call notation; the symbol -@var{func} is in general always of the form @samp{calcFunc-@var{name}}. -The function cell of the symbol @var{func} should contain a Lisp function -for evaluating a call to @var{func}. This function is passed the remaining -elements of the list (themselves already evaluated) as arguments; such -functions should return @code{nil} or call @code{reject-arg} to signify -that they should be left in symbolic form, or they should return a Calc -object which represents their value, or a list of such objects if they -wish to return multiple values. (The latter case is allowed only for -functions which are the outer-level call in an expression whose value is -about to be pushed on the stack; this feature is considered obsolete -and is not used by any built-in Calc functions.) - -@node Interactive Lisp Functions, Stack Lisp Functions, Data Type Formats, Internals -@subsubsection Interactive Functions - -@noindent -The functions described here are used in implementing interactive Calc -commands. Note that this list is not exhaustive! If there is an -existing command that behaves similarly to the one you want to define, -you may find helpful tricks by checking the source code for that command. - -@defun calc-set-command-flag flag -Set the command flag @var{flag}. This is generally a Lisp symbol, but -may in fact be anything. The effect is to add @var{flag} to the list -stored in the variable @code{calc-command-flags}, unless it is already -there. @xref{Defining Simple Commands}. -@end defun - -@defun calc-clear-command-flag flag -If @var{flag} appears among the list of currently-set command flags, -remove it from that list. -@end defun - -@defun calc-record-undo rec -Add the ``undo record'' @var{rec} to the list of steps to take if the -current operation should need to be undone. Stack push and pop functions -automatically call @code{calc-record-undo}, so the kinds of undo records -you might need to create take the form @samp{(set @var{sym} @var{value})}, -which says that the Lisp variable @var{sym} was changed and had previously -contained @var{value}; @samp{(store @var{var} @var{value})} which says that -the Calc variable @var{var} (a string which is the name of the symbol that -contains the variable's value) was stored and its previous value was -@var{value} (either a Calc data object, or @code{nil} if the variable was -previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})}, -which means that to undo requires calling the function @samp{(@var{undo} -@var{args} @dots{})} and, if the undo is later redone, calling -@samp{(@var{redo} @var{args} @dots{})}. -@end defun - -@defun calc-record-why msg args -Record the error or warning message @var{msg}, which is normally a string. -This message will be replayed if the user types @kbd{w} (@code{calc-why}); -if the message string begins with a @samp{*}, it is considered important -enough to display even if the user doesn't type @kbd{w}. If one or more -@var{args} are present, the displayed message will be of the form, -@samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are -formatted on the assumption that they are either strings or Calc objects of -some sort. If @var{msg} is a symbol, it is the name of a Calc predicate -(such as @code{integerp} or @code{numvecp}) which the arguments did not -satisfy; it is expanded to a suitable string such as ``Expected an -integer.'' The @code{reject-arg} function calls @code{calc-record-why} -automatically; @pxref{Predicates}. -@end defun - -@defun calc-is-inverse -This predicate returns true if the current command is inverse, -i.e., if the Inverse (@kbd{I} key) flag was set. -@end defun - -@defun calc-is-hyperbolic -This predicate is the analogous function for the @kbd{H} key. -@end defun - -@node Stack Lisp Functions, Predicates, Interactive Lisp Functions, Internals -@subsubsection Stack-Oriented Functions - -@noindent -The functions described here perform various operations on the Calc -stack and trail. They are to be used in interactive Calc commands. - -@defun calc-push-list vals n -Push the Calc objects in list @var{vals} onto the stack at stack level -@var{n}. If @var{n} is omitted it defaults to 1, so that the elements -are pushed at the top of the stack. If @var{n} is greater than 1, the -elements will be inserted into the stack so that the last element will -end up at level @var{n}, the next-to-last at level @var{n}+1, etc. -The elements of @var{vals} are assumed to be valid Calc objects, and -are not evaluated, rounded, or renormalized in any way. If @var{vals} -is an empty list, nothing happens. - -The stack elements are pushed without any sub-formula selections. -You can give an optional third argument to this function, which must -be a list the same size as @var{vals} of selections. Each selection -must be @code{eq} to some sub-formula of the corresponding formula -in @var{vals}, or @code{nil} if that formula should have no selection. -@end defun - -@defun calc-top-list n m -Return a list of the @var{n} objects starting at level @var{m} of the -stack. If @var{m} is omitted it defaults to 1, so that the elements are -taken from the top of the stack. If @var{n} is omitted, it also -defaults to 1, so that the top stack element (in the form of a -one-element list) is returned. If @var{m} is greater than 1, the -@var{m}th stack element will be at the end of the list, the @var{m}+1st -element will be next-to-last, etc. If @var{n} or @var{m} are out of -range, the command is aborted with a suitable error message. If @var{n} -is zero, the function returns an empty list. The stack elements are not -evaluated, rounded, or renormalized. - -If any stack elements contain selections, and selections have not -been disabled by the @kbd{j e} (@code{calc-enable-selections}) command, -this function returns the selected portions rather than the entire -stack elements. It can be given a third ``selection-mode'' argument -which selects other behaviors. If it is the symbol @code{t}, then -a selection in any of the requested stack elements produces an -``invalid operation on selections'' error. If it is the symbol @code{full}, -the whole stack entry is always returned regardless of selections. -If it is the symbol @code{sel}, the selected portion is always returned, -or @code{nil} if there is no selection. (This mode ignores the @kbd{j e} -command.) If the symbol is @code{entry}, the complete stack entry in -list form is returned; the first element of this list will be the whole -formula, and the third element will be the selection (or @code{nil}). -@end defun - -@defun calc-pop-stack n m -Remove the specified elements from the stack. The parameters @var{n} -and @var{m} are defined the same as for @code{calc-top-list}. The return -value of @code{calc-pop-stack} is uninteresting. - -If there are any selected sub-formulas among the popped elements, and -@kbd{j e} has not been used to disable selections, this produces an -error without changing the stack. If you supply an optional third -argument of @code{t}, the stack elements are popped even if they -contain selections. -@end defun - -@defun calc-record-list vals tag -This function records one or more results in the trail. The @var{vals} -are a list of strings or Calc objects. The @var{tag} is the four-character -tag string to identify the values. If @var{tag} is omitted, a blank tag -will be used. -@end defun - -@defun calc-normalize n -This function takes a Calc object and ``normalizes'' it. At the very -least this involves re-rounding floating-point values according to the -current precision and other similar jobs. Also, unless the user has -selected No-Simplify mode (@pxref{Simplification Modes}), this involves -actually evaluating a formula object by executing the function calls -it contains, and possibly also doing algebraic simplification, etc. -@end defun - -@defun calc-top-list-n n m -This function is identical to @code{calc-top-list}, except that it calls -@code{calc-normalize} on the values that it takes from the stack. They -are also passed through @code{check-complete}, so that incomplete -objects will be rejected with an error message. All computational -commands should use this in preference to @code{calc-top-list}; the only -standard Calc commands that operate on the stack without normalizing -are stack management commands like @code{calc-enter} and @code{calc-roll-up}. -This function accepts the same optional selection-mode argument as -@code{calc-top-list}. -@end defun - -@defun calc-top-n m -This function is a convenient form of @code{calc-top-list-n} in which only -a single element of the stack is taken and returned, rather than a list -of elements. This also accepts an optional selection-mode argument. -@end defun - -@defun calc-enter-result n tag vals -This function is a convenient interface to most of the above functions. -The @var{vals} argument should be either a single Calc object, or a list -of Calc objects; the object or objects are normalized, and the top @var{n} -stack entries are replaced by the normalized objects. If @var{tag} is -non-@code{nil}, the normalized objects are also recorded in the trail. -A typical stack-based computational command would take the form, - -@smallexample -(calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func} - (calc-top-list-n @var{n}))) -@end smallexample - -If any of the @var{n} stack elements replaced contain sub-formula -selections, and selections have not been disabled by @kbd{j e}, -this function takes one of two courses of action. If @var{n} is -equal to the number of elements in @var{vals}, then each element of -@var{vals} is spliced into the corresponding selection; this is what -happens when you use the @key{TAB} key, or when you use a unary -arithmetic operation like @code{sqrt}. If @var{vals} has only one -element but @var{n} is greater than one, there must be only one -selection among the top @var{n} stack elements; the element from -@var{vals} is spliced into that selection. This is what happens when -you use a binary arithmetic operation like @kbd{+}. Any other -combination of @var{n} and @var{vals} is an error when selections -are present. -@end defun - -@defun calc-unary-op tag func arg -This function implements a unary operator that allows a numeric prefix -argument to apply the operator over many stack entries. If the prefix -argument @var{arg} is @code{nil}, this uses @code{calc-enter-result} -as outlined above. Otherwise, it maps the function over several stack -elements; @pxref{Prefix Arguments}. For example, - -@smallexample -(defun calc-zeta (arg) - (interactive "P") - (calc-unary-op "zeta" 'calcFunc-zeta arg)) -@end smallexample -@end defun - -@defun calc-binary-op tag func arg ident unary -This function implements a binary operator, analogously to -@code{calc-unary-op}. The optional @var{ident} and @var{unary} -arguments specify the behavior when the prefix argument is zero or -one, respectively. If the prefix is zero, the value @var{ident} -is pushed onto the stack, if specified, otherwise an error message -is displayed. If the prefix is one, the unary function @var{unary} -is applied to the top stack element, or, if @var{unary} is not -specified, nothing happens. When the argument is two or more, -the binary function @var{func} is reduced across the top @var{arg} -stack elements; when the argument is negative, the function is -mapped between the next-to-top @mathit{-@var{arg}} stack elements and the -top element. -@end defun - -@defun calc-stack-size -Return the number of elements on the stack as an integer. This count -does not include elements that have been temporarily hidden by stack -truncation; @pxref{Truncating the Stack}. -@end defun - -@defun calc-cursor-stack-index n -Move the point to the @var{n}th stack entry. If @var{n} is zero, this -will be the @samp{.} line. If @var{n} is from 1 to the current stack size, -this will be the beginning of the first line of that stack entry's display. -If line numbers are enabled, this will move to the first character of the -line number, not the stack entry itself. -@end defun - -@defun calc-substack-height n -Return the number of lines between the beginning of the @var{n}th stack -entry and the bottom of the buffer. If @var{n} is zero, this -will be one (assuming no stack truncation). If all stack entries are -one line long (i.e., no matrices are displayed), the return value will -be equal @var{n}+1 as long as @var{n} is in range. (Note that in Big -mode, the return value includes the blank lines that separate stack -entries.) -@end defun - -@defun calc-refresh -Erase the @file{*Calculator*} buffer and reformat its contents from memory. -This must be called after changing any parameter, such as the current -display radix, which might change the appearance of existing stack -entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing -is suppressed, but a flag is set so that the entire stack will be refreshed -rather than just the top few elements when the macro finishes.) -@end defun - -@node Predicates, Computational Lisp Functions, Stack Lisp Functions, Internals -@subsubsection Predicates - -@noindent -The functions described here are predicates, that is, they return a -true/false value where @code{nil} means false and anything else means -true. These predicates are expanded by @code{defmath}, for example, -from @code{zerop} to @code{math-zerop}. In many cases they correspond -to native Lisp functions by the same name, but are extended to cover -the full range of Calc data types. - -@defun zerop x -Returns true if @var{x} is numerically zero, in any of the Calc data -types. (Note that for some types, such as error forms and intervals, -it never makes sense to return true.) In @code{defmath}, the expression -@samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)}, -and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}. -@end defun - -@defun negp x -Returns true if @var{x} is negative. This accepts negative real numbers -of various types, negative HMS and date forms, and intervals in which -all included values are negative. In @code{defmath}, the expression -@samp{(< x 0)} will automatically be converted to @samp{(math-negp x)}, -and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}. -@end defun - -@defun posp x -Returns true if @var{x} is positive (and non-zero). For complex -numbers, none of these three predicates will return true. -@end defun - -@defun looks-negp x -Returns true if @var{x} is ``negative-looking.'' This returns true if -@var{x} is a negative number, or a formula with a leading minus sign -such as @samp{-a/b}. In other words, this is an object which can be -made simpler by calling @code{(- @var{x})}. -@end defun - -@defun integerp x -Returns true if @var{x} is an integer of any size. -@end defun - -@defun fixnump x -Returns true if @var{x} is a native Lisp integer. -@end defun - -@defun natnump x -Returns true if @var{x} is a nonnegative integer of any size. -@end defun - -@defun fixnatnump x -Returns true if @var{x} is a nonnegative Lisp integer. -@end defun - -@defun num-integerp x -Returns true if @var{x} is numerically an integer, i.e., either a -true integer or a float with no significant digits to the right of -the decimal point. -@end defun - -@defun messy-integerp x -Returns true if @var{x} is numerically, but not literally, an integer. -A value is @code{num-integerp} if it is @code{integerp} or -@code{messy-integerp} (but it is never both at once). -@end defun - -@defun num-natnump x -Returns true if @var{x} is numerically a nonnegative integer. -@end defun - -@defun evenp x -Returns true if @var{x} is an even integer. -@end defun - -@defun looks-evenp x -Returns true if @var{x} is an even integer, or a formula with a leading -multiplicative coefficient which is an even integer. -@end defun - -@defun oddp x -Returns true if @var{x} is an odd integer. -@end defun - -@defun ratp x -Returns true if @var{x} is a rational number, i.e., an integer or a -fraction. -@end defun - -@defun realp x -Returns true if @var{x} is a real number, i.e., an integer, fraction, -or floating-point number. -@end defun - -@defun anglep x -Returns true if @var{x} is a real number or HMS form. -@end defun - -@defun floatp x -Returns true if @var{x} is a float, or a complex number, error form, -interval, date form, or modulo form in which at least one component -is a float. -@end defun - -@defun complexp x -Returns true if @var{x} is a rectangular or polar complex number -(but not a real number). -@end defun - -@defun rect-complexp x -Returns true if @var{x} is a rectangular complex number. -@end defun - -@defun polar-complexp x -Returns true if @var{x} is a polar complex number. -@end defun - -@defun numberp x -Returns true if @var{x} is a real number or a complex number. -@end defun - -@defun scalarp x -Returns true if @var{x} is a real or complex number or an HMS form. -@end defun - -@defun vectorp x -Returns true if @var{x} is a vector (this simply checks if its argument -is a list whose first element is the symbol @code{vec}). -@end defun - -@defun numvecp x -Returns true if @var{x} is a number or vector. -@end defun - -@defun matrixp x -Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors, -all of the same size. -@end defun - -@defun square-matrixp x -Returns true if @var{x} is a square matrix. -@end defun - -@defun objectp x -Returns true if @var{x} is any numeric Calc object, including real and -complex numbers, HMS forms, date forms, error forms, intervals, and -modulo forms. (Note that error forms and intervals may include formulas -as their components; see @code{constp} below.) -@end defun - -@defun objvecp x -Returns true if @var{x} is an object or a vector. This also accepts -incomplete objects, but it rejects variables and formulas (except as -mentioned above for @code{objectp}). -@end defun - -@defun primp x -Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object, -i.e., one whose components cannot be regarded as sub-formulas. This -includes variables, and all @code{objectp} types except error forms -and intervals. -@end defun - -@defun constp x -Returns true if @var{x} is constant, i.e., a real or complex number, -HMS form, date form, or error form, interval, or vector all of whose -components are @code{constp}. -@end defun - -@defun lessp x y -Returns true if @var{x} is numerically less than @var{y}. Returns false -if @var{x} is greater than or equal to @var{y}, or if the order is -undefined or cannot be determined. Generally speaking, this works -by checking whether @samp{@var{x} - @var{y}} is @code{negp}. In -@code{defmath}, the expression @samp{(< x y)} will automatically be -converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=}, -and @code{>=} are similarly converted in terms of @code{lessp}. -@end defun - -@defun beforep x y -Returns true if @var{x} comes before @var{y} in a canonical ordering -of Calc objects. If @var{x} and @var{y} are both real numbers, this -will be the same as @code{lessp}. But whereas @code{lessp} considers -other types of objects to be unordered, @code{beforep} puts any two -objects into a definite, consistent order. The @code{beforep} -function is used by the @kbd{V S} vector-sorting command, and also -by Calc's algebraic simplifications to put the terms of a product into -canonical order: This allows @samp{x y + y x} to be simplified easily to -@samp{2 x y}. -@end defun - -@defun equal x y -This is the standard Lisp @code{equal} predicate; it returns true if -@var{x} and @var{y} are structurally identical. This is the usual way -to compare numbers for equality, but note that @code{equal} will treat -0 and 0.0 as different. -@end defun - -@defun math-equal x y -Returns true if @var{x} and @var{y} are numerically equal, either because -they are @code{equal}, or because their difference is @code{zerop}. In -@code{defmath}, the expression @samp{(= x y)} will automatically be -converted to @samp{(math-equal x y)}. -@end defun - -@defun equal-int x n -Returns true if @var{x} and @var{n} are numerically equal, where @var{n} -is a fixnum which is not a multiple of 10. This will automatically be -used by @code{defmath} in place of the more general @code{math-equal} -whenever possible. -@end defun - -@defun nearly-equal x y -Returns true if @var{x} and @var{y}, as floating-point numbers, are -equal except possibly in the last decimal place. For example, -314.159 and 314.166 are considered nearly equal if the current -precision is 6 (since they differ by 7 units), but not if the current -precision is 7 (since they differ by 70 units). Most functions which -use series expansions use @code{with-extra-prec} to evaluate the -series with 2 extra digits of precision, then use @code{nearly-equal} -to decide when the series has converged; this guards against cumulative -error in the series evaluation without doing extra work which would be -lost when the result is rounded back down to the current precision. -In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}. -The @var{x} and @var{y} can be numbers of any kind, including complex. -@end defun - -@defun nearly-zerop x y -Returns true if @var{x} is nearly zero, compared to @var{y}. This -checks whether @var{x} plus @var{y} would by be @code{nearly-equal} -to @var{y} itself, to within the current precision, in other words, -if adding @var{x} to @var{y} would have a negligible effect on @var{y} -due to roundoff error. @var{X} may be a real or complex number, but -@var{y} must be real. -@end defun - -@defun is-true x -Return true if the formula @var{x} represents a true value in -Calc, not Lisp, terms. It tests if @var{x} is a non-zero number -or a provably non-zero formula. -@end defun - -@defun reject-arg val pred -Abort the current function evaluation due to unacceptable argument values. -This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a -Lisp error which @code{normalize} will trap. The net effect is that the -function call which led here will be left in symbolic form. -@end defun - -@defun inexact-value -If Symbolic mode is enabled, this will signal an error that causes -@code{normalize} to leave the formula in symbolic form, with the message -``Inexact result.'' (This function has no effect when not in Symbolic mode.) -Note that if your function calls @samp{(sin 5)} in Symbolic mode, the -@code{sin} function will call @code{inexact-value}, which will cause your -function to be left unsimplified. You may instead wish to call -@samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic mode will -return the formula @samp{sin(5)} to your function. -@end defun - -@defun overflow -This signals an error that will be reported as a floating-point overflow. -@end defun - -@defun underflow -This signals a floating-point underflow. -@end defun - -@node Computational Lisp Functions, Vector Lisp Functions, Predicates, Internals -@subsubsection Computational Functions - -@noindent -The functions described here do the actual computational work of the -Calculator. In addition to these, note that any function described in -the main body of this manual may be called from Lisp; for example, if -the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command, -this means @code{calc-sqrt} is an interactive stack-based square-root -command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt}) -is the actual Lisp function for taking square roots. - -The functions @code{math-add}, @code{math-sub}, @code{math-mul}, -@code{math-div}, @code{math-mod}, and @code{math-neg} are not included -in this list, since @code{defmath} allows you to write native Lisp -@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-}, -respectively, instead. - -@defun normalize val -(Full form: @code{math-normalize}.) -Reduce the value @var{val} to standard form. For example, if @var{val} -is a fixnum, it will be converted to a bignum if it is too large, and -if @var{val} is a bignum it will be normalized by clipping off trailing -(i.e., most-significant) zero digits and converting to a fixnum if it is -small. All the various data types are similarly converted to their standard -forms. Variables are left alone, but function calls are actually evaluated -in formulas. For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will -return 6. - -If a function call fails, because the function is void or has the wrong -number of parameters, or because it returns @code{nil} or calls -@code{reject-arg} or @code{inexact-result}, @code{normalize} returns -the formula still in symbolic form. - -If the current simplification mode is ``none'' or ``numeric arguments -only,'' @code{normalize} will act appropriately. However, the more -powerful simplification modes (like Algebraic Simplification) are -not handled by @code{normalize}. They are handled by @code{calc-normalize}, -which calls @code{normalize} and possibly some other routines, such -as @code{simplify} or @code{simplify-units}. Programs generally will -never call @code{calc-normalize} except when popping or pushing values -on the stack. -@end defun - -@defun evaluate-expr expr -Replace all variables in @var{expr} that have values with their values, -then use @code{normalize} to simplify the result. This is what happens -when you press the @kbd{=} key interactively. -@end defun - -@defmac with-extra-prec n body -Evaluate the Lisp forms in @var{body} with precision increased by @var{n} -digits. This is a macro which expands to - -@smallexample -(math-normalize - (let ((calc-internal-prec (+ calc-internal-prec @var{n}))) - @var{body})) -@end smallexample - -The surrounding call to @code{math-normalize} causes a floating-point -result to be rounded down to the original precision afterwards. This -is important because some arithmetic operations assume a number's -mantissa contains no more digits than the current precision allows. -@end defmac - -@defun make-frac n d -Build a fraction @samp{@var{n}:@var{d}}. This is equivalent to calling -@samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient. -@end defun - -@defun make-float mant exp -Build a floating-point value out of @var{mant} and @var{exp}, both -of which are arbitrary integers. This function will return a -properly normalized float value, or signal an overflow or underflow -if @var{exp} is out of range. -@end defun - -@defun make-sdev x sigma -Build an error form out of @var{x} and the absolute value of @var{sigma}. -If @var{sigma} is zero, the result is the number @var{x} directly. -If @var{sigma} is negative or complex, its absolute value is used. -If @var{x} or @var{sigma} is not a valid type of object for use in -error forms, this calls @code{reject-arg}. -@end defun - -@defun make-intv mask lo hi -Build an interval form out of @var{mask} (which is assumed to be an -integer from 0 to 3), and the limits @var{lo} and @var{hi}. If -@var{lo} is greater than @var{hi}, an empty interval form is returned. -This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable. -@end defun - -@defun sort-intv mask lo hi -Build an interval form, similar to @code{make-intv}, except that if -@var{lo} is less than @var{hi} they are simply exchanged, and the -bits of @var{mask} are swapped accordingly. -@end defun - -@defun make-mod n m -Build a modulo form out of @var{n} and the modulus @var{m}. Since modulo -forms do not allow formulas as their components, if @var{n} or @var{m} -is not a real number or HMS form the result will be a formula which -is a call to @code{makemod}, the algebraic version of this function. -@end defun - -@defun float x -Convert @var{x} to floating-point form. Integers and fractions are -converted to numerically equivalent floats; components of complex -numbers, vectors, HMS forms, date forms, error forms, intervals, and -modulo forms are recursively floated. If the argument is a variable -or formula, this calls @code{reject-arg}. -@end defun - -@defun compare x y -Compare the numbers @var{x} and @var{y}, and return @mathit{-1} if -@samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})}, -0 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is -undefined or cannot be determined. -@end defun - -@defun numdigs n -Return the number of digits of integer @var{n}, effectively -@samp{ceil(log10(@var{n}))}, but much more efficient. Zero is -considered to have zero digits. -@end defun - -@defun scale-int x n -Shift integer @var{x} left @var{n} decimal digits, or right @mathit{-@var{n}} -digits with truncation toward zero. -@end defun - -@defun scale-rounding x n -Like @code{scale-int}, except that a right shift rounds to the nearest -integer rather than truncating. -@end defun - -@defun fixnum n -Return the integer @var{n} as a fixnum, i.e., a native Lisp integer. -If @var{n} is outside the permissible range for Lisp integers (usually -24 binary bits) the result is undefined. -@end defun - -@defun sqr x -Compute the square of @var{x}; short for @samp{(* @var{x} @var{x})}. -@end defun - -@defun quotient x y -Divide integer @var{x} by integer @var{y}; return an integer quotient -and discard the remainder. If @var{x} or @var{y} is negative, the -direction of rounding is undefined. -@end defun - -@defun idiv x y -Perform an integer division; if @var{x} and @var{y} are both nonnegative -integers, this uses the @code{quotient} function, otherwise it computes -@samp{floor(@var{x}/@var{y})}. Thus the result is well-defined but -slower than for @code{quotient}. -@end defun - -@defun imod x y -Divide integer @var{x} by integer @var{y}; return the integer remainder -and discard the quotient. Like @code{quotient}, this works only for -integer arguments and is not well-defined for negative arguments. -For a more well-defined result, use @samp{(% @var{x} @var{y})}. -@end defun - -@defun idivmod x y -Divide integer @var{x} by integer @var{y}; return a cons cell whose -@code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr} -is @samp{(imod @var{x} @var{y})}. -@end defun - -@defun pow x y -Compute @var{x} to the power @var{y}. In @code{defmath} code, this can -also be written @samp{(^ @var{x} @var{y})} or -@w{@samp{(expt @var{x} @var{y})}}. -@end defun - -@defun abs-approx x -Compute a fast approximation to the absolute value of @var{x}. For -example, for a rectangular complex number the result is the sum of -the absolute values of the components. -@end defun - -@findex e -@findex gamma-const -@findex ln-2 -@findex ln-10 -@findex phi -@findex pi-over-2 -@findex pi-over-4 -@findex pi-over-180 -@findex sqrt-two-pi -@findex sqrt-e -@findex two-pi -@defun pi -The function @samp{(pi)} computes @samp{pi} to the current precision. -Other related constant-generating functions are @code{two-pi}, -@code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi}, -@code{e}, @code{sqrt-e}, @code{ln-2}, @code{ln-10}, @code{phi} and -@code{gamma-const}. Each function returns a floating-point value in the -current precision, and each uses caching so that all calls after the -first are essentially free. -@end defun - -@defmac math-defcache @var{func} @var{initial} @var{form} -This macro, usually used as a top-level call like @code{defun} or -@code{defvar}, defines a new cached constant analogous to @code{pi}, etc. -It defines a function @code{func} which returns the requested value; -if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})} -form which serves as an initial value for the cache. If @var{func} -is called when the cache is empty or does not have enough digits to -satisfy the current precision, the Lisp expression @var{form} is evaluated -with the current precision increased by four, and the result minus its -two least significant digits is stored in the cache. For example, -calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34 -digits, rounds it down to 32 digits for future use, then rounds it -again to 30 digits for use in the present request. -@end defmac - -@findex half-circle -@findex quarter-circle -@defun full-circle symb -If the current angular mode is Degrees or HMS, this function returns the -integer 360. In Radians mode, this function returns either the -corresponding value in radians to the current precision, or the formula -@samp{2*pi}, depending on the Symbolic mode. There are also similar -function @code{half-circle} and @code{quarter-circle}. -@end defun - -@defun power-of-2 n -Compute two to the integer power @var{n}, as a (potentially very large) -integer. Powers of two are cached, so only the first call for a -particular @var{n} is expensive. -@end defun - -@defun integer-log2 n -Compute the base-2 logarithm of @var{n}, which must be an integer which -is a power of two. If @var{n} is not a power of two, this function will -return @code{nil}. -@end defun - -@defun div-mod a b m -Divide @var{a} by @var{b}, modulo @var{m}. This returns @code{nil} if -there is no solution, or if any of the arguments are not integers. -@end defun - -@defun pow-mod a b m -Compute @var{a} to the power @var{b}, modulo @var{m}. If @var{a}, -@var{b}, and @var{m} are integers, this uses an especially efficient -algorithm. Otherwise, it simply computes @samp{(% (^ a b) m)}. -@end defun - -@defun isqrt n -Compute the integer square root of @var{n}. This is the square root -of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}. -If @var{n} is itself an integer, the computation is especially efficient. -@end defun - -@defun to-hms a ang -Convert the argument @var{a} into an HMS form. If @var{ang} is specified, -it is the angular mode in which to interpret @var{a}, either @code{deg} -or @code{rad}. Otherwise, the current angular mode is used. If @var{a} -is already an HMS form it is returned as-is. -@end defun - -@defun from-hms a ang -Convert the HMS form @var{a} into a real number. If @var{ang} is specified, -it is the angular mode in which to express the result, otherwise the -current angular mode is used. If @var{a} is already a real number, it -is returned as-is. -@end defun - -@defun to-radians a -Convert the number or HMS form @var{a} to radians from the current -angular mode. -@end defun - -@defun from-radians a -Convert the number @var{a} from radians to the current angular mode. -If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}. -@end defun - -@defun to-radians-2 a -Like @code{to-radians}, except that in Symbolic mode a degrees to -radians conversion yields a formula like @samp{@var{a}*pi/180}. -@end defun - -@defun from-radians-2 a -Like @code{from-radians}, except that in Symbolic mode a radians to -degrees conversion yields a formula like @samp{@var{a}*180/pi}. -@end defun - -@defun random-digit -Produce a random base-1000 digit in the range 0 to 999. -@end defun - -@defun random-digits n -Produce a random @var{n}-digit integer; this will be an integer -in the interval @samp{[0, 10^@var{n})}. -@end defun - -@defun random-float -Produce a random float in the interval @samp{[0, 1)}. -@end defun - -@defun prime-test n iters -Determine whether the integer @var{n} is prime. Return a list which has -one of these forms: @samp{(nil @var{f})} means the number is non-prime -because it was found to be divisible by @var{f}; @samp{(nil)} means it -was found to be non-prime by table look-up (so no factors are known); -@samp{(nil unknown)} means it is definitely non-prime but no factors -are known because @var{n} was large enough that Fermat's probabilistic -test had to be used; @samp{(t)} means the number is definitely prime; -and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i} -iterations, is @var{p} percent sure that the number is prime. The -@var{iters} parameter is the number of Fermat iterations to use, in the -case that this is necessary. If @code{prime-test} returns ``maybe,'' -you can call it again with the same @var{n} to get a greater certainty; -@code{prime-test} remembers where it left off. -@end defun - -@defun to-simple-fraction f -If @var{f} is a floating-point number which can be represented exactly -as a small rational number. return that number, else return @var{f}. -For example, 0.75 would be converted to 3:4. This function is very -fast. -@end defun - -@defun to-fraction f tol -Find a rational approximation to floating-point number @var{f} to within -a specified tolerance @var{tol}; this corresponds to the algebraic -function @code{frac}, and can be rather slow. -@end defun - -@defun quarter-integer n -If @var{n} is an integer or integer-valued float, this function -returns zero. If @var{n} is a half-integer (i.e., an integer plus -@mathit{1:2} or 0.5), it returns 2. If @var{n} is a quarter-integer, -it returns 1 or 3. If @var{n} is anything else, this function -returns @code{nil}. -@end defun - -@node Vector Lisp Functions, Symbolic Lisp Functions, Computational Lisp Functions, Internals -@subsubsection Vector Functions - -@noindent -The functions described here perform various operations on vectors and -matrices. - -@defun math-concat x y -Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}} -in a symbolic formula. @xref{Building Vectors}. -@end defun - -@defun vec-length v -Return the length of vector @var{v}. If @var{v} is not a vector, the -result is zero. If @var{v} is a matrix, this returns the number of -rows in the matrix. -@end defun - -@defun mat-dimens m -Determine the dimensions of vector or matrix @var{m}. If @var{m} is not -a vector, the result is an empty list. If @var{m} is a plain vector -but not a matrix, the result is a one-element list containing the length -of the vector. If @var{m} is a matrix with @var{r} rows and @var{c} columns, -the result is the list @samp{(@var{r} @var{c})}. Higher-order tensors -produce lists of more than two dimensions. Note that the object -@samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size, -and is treated by this and other Calc routines as a plain vector of two -elements. -@end defun - -@defun dimension-error -Abort the current function with a message of ``Dimension error.'' -The Calculator will leave the function being evaluated in symbolic -form; this is really just a special case of @code{reject-arg}. -@end defun - -@defun build-vector args -Return a Calc vector with @var{args} as elements. -For example, @samp{(build-vector 1 2 3)} returns the Calc vector -@samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}. -@end defun - -@defun make-vec obj dims -Return a Calc vector or matrix all of whose elements are equal to -@var{obj}. For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix -filled with 27's. -@end defun - -@defun row-matrix v -If @var{v} is a plain vector, convert it into a row matrix, i.e., -a matrix whose single row is @var{v}. If @var{v} is already a matrix, -leave it alone. -@end defun - -@defun col-matrix v -If @var{v} is a plain vector, convert it into a column matrix, i.e., a -matrix with each element of @var{v} as a separate row. If @var{v} is -already a matrix, leave it alone. -@end defun - -@defun map-vec f v -Map the Lisp function @var{f} over the Calc vector @var{v}. For example, -@samp{(map-vec 'math-floor v)} returns a vector of the floored components -of vector @var{v}. -@end defun - -@defun map-vec-2 f a b -Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}. -If @var{a} and @var{b} are vectors of equal length, the result is a -vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})} -for each pair of elements @var{ai} and @var{bi}. If either @var{a} or -@var{b} is a scalar, it is matched with each value of the other vector. -For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v} -with each element increased by one. Note that using @samp{'+} would not -work here, since @code{defmath} does not expand function names everywhere, -just where they are in the function position of a Lisp expression. -@end defun - -@defun reduce-vec f v -Reduce the function @var{f} over the vector @var{v}. For example, if -@var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}. -If @var{v} is a matrix, this reduces over the rows of @var{v}. -@end defun - -@defun reduce-cols f m -Reduce the function @var{f} over the columns of matrix @var{m}. For -example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result -is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}. -@end defun - -@defun mat-row m n -Return the @var{n}th row of matrix @var{m}. This is equivalent to -@samp{(elt m n)}. For a slower but safer version, use @code{mrow}. -(@xref{Extracting Elements}.) -@end defun - -@defun mat-col m n -Return the @var{n}th column of matrix @var{m}, in the form of a vector. -The arguments are not checked for correctness. -@end defun - -@defun mat-less-row m n -Return a copy of matrix @var{m} with its @var{n}th row deleted. The -number @var{n} must be in range from 1 to the number of rows in @var{m}. -@end defun - -@defun mat-less-col m n -Return a copy of matrix @var{m} with its @var{n}th column deleted. -@end defun - -@defun transpose m -Return the transpose of matrix @var{m}. -@end defun - -@defun flatten-vector v -Flatten nested vector @var{v} into a vector of scalars. For example, -if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}. -@end defun - -@defun copy-matrix m -If @var{m} is a matrix, return a copy of @var{m}. This maps -@code{copy-sequence} over the rows of @var{m}; in Lisp terms, each -element of the result matrix will be @code{eq} to the corresponding -element of @var{m}, but none of the @code{cons} cells that make up -the structure of the matrix will be @code{eq}. If @var{m} is a plain -vector, this is the same as @code{copy-sequence}. -@end defun - -@defun swap-rows m r1 r2 -Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place. In -other words, unlike most of the other functions described here, this -function changes @var{m} itself rather than building up a new result -matrix. The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)} -is true, with the side effect of exchanging the first two rows of -@var{m}. -@end defun - -@node Symbolic Lisp Functions, Formatting Lisp Functions, Vector Lisp Functions, Internals -@subsubsection Symbolic Functions - -@noindent -The functions described here operate on symbolic formulas in the -Calculator. - -@defun calc-prepare-selection num -Prepare a stack entry for selection operations. If @var{num} is -omitted, the stack entry containing the cursor is used; otherwise, -it is the number of the stack entry to use. This function stores -useful information about the current stack entry into a set of -variables. @code{calc-selection-cache-num} contains the number of -the stack entry involved (equal to @var{num} if you specified it); -@code{calc-selection-cache-entry} contains the stack entry as a -list (such as @code{calc-top-list} would return with @code{entry} -as the selection mode); and @code{calc-selection-cache-comp} contains -a special ``tagged'' composition (@pxref{Formatting Lisp Functions}) -which allows Calc to relate cursor positions in the buffer with -their corresponding sub-formulas. - -A slight complication arises in the selection mechanism because -formulas may contain small integers. For example, in the vector -@samp{[1, 2, 1]} the first and last elements are @code{eq} to each -other; selections are recorded as the actual Lisp object that -appears somewhere in the tree of the whole formula, but storing -@code{1} would falsely select both @code{1}'s in the vector. So -@code{calc-prepare-selection} also checks the stack entry and -replaces any plain integers with ``complex number'' lists of the form -@samp{(cplx @var{n} 0)}. This list will be displayed the same as a -plain @var{n} and the change will be completely invisible to the -user, but it will guarantee that no two sub-formulas of the stack -entry will be @code{eq} to each other. Next time the stack entry -is involved in a computation, @code{calc-normalize} will replace -these lists with plain numbers again, again invisibly to the user. -@end defun - -@defun calc-encase-atoms x -This modifies the formula @var{x} to ensure that each part of the -formula is a unique atom, using the @samp{(cplx @var{n} 0)} trick -described above. This function may use @code{setcar} to modify -the formula in-place. -@end defun - -@defun calc-find-selected-part -Find the smallest sub-formula of the current formula that contains -the cursor. This assumes @code{calc-prepare-selection} has been -called already. If the cursor is not actually on any part of the -formula, this returns @code{nil}. -@end defun - -@defun calc-change-current-selection selection -Change the currently prepared stack element's selection to -@var{selection}, which should be @code{eq} to some sub-formula -of the stack element, or @code{nil} to unselect the formula. -The stack element's appearance in the Calc buffer is adjusted -to reflect the new selection. -@end defun - -@defun calc-find-nth-part expr n -Return the @var{n}th sub-formula of @var{expr}. This function is used -by the selection commands, and (unless @kbd{j b} has been used) treats -sums and products as flat many-element formulas. Thus if @var{expr} -is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with -@var{n} equal to four will return @samp{d}. -@end defun - -@defun calc-find-parent-formula expr part -Return the sub-formula of @var{expr} which immediately contains -@var{part}. If @var{expr} is @samp{a*b + (c+1)*d} and @var{part} -is @code{eq} to the @samp{c+1} term of @var{expr}, then this function -will return @samp{(c+1)*d}. If @var{part} turns out not to be a -sub-formula of @var{expr}, the function returns @code{nil}. If -@var{part} is @code{eq} to @var{expr}, the function returns @code{t}. -This function does not take associativity into account. -@end defun - -@defun calc-find-assoc-parent-formula expr part -This is the same as @code{calc-find-parent-formula}, except that -(unless @kbd{j b} has been used) it continues widening the selection -to contain a complete level of the formula. Given @samp{a} from -@samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will -return @samp{a + b} but @code{calc-find-assoc-parent-formula} will -return the whole expression. -@end defun - -@defun calc-grow-assoc-formula expr part -This expands sub-formula @var{part} of @var{expr} to encompass a -complete level of the formula. If @var{part} and its immediate -parent are not compatible associative operators, or if @kbd{j b} -has been used, this simply returns @var{part}. -@end defun - -@defun calc-find-sub-formula expr part -This finds the immediate sub-formula of @var{expr} which contains -@var{part}. It returns an index @var{n} such that -@samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}. -If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}. -If @var{part} is @code{eq} to @var{expr}, it returns @code{t}. This -function does not take associativity into account. -@end defun - -@defun calc-replace-sub-formula expr old new -This function returns a copy of formula @var{expr}, with the -sub-formula that is @code{eq} to @var{old} replaced by @var{new}. -@end defun - -@defun simplify expr -Simplify the expression @var{expr} by applying Calc's algebraic -simplifications. This always returns a copy of the expression; the -structure @var{expr} points to remains unchanged in memory. - -More precisely, here is what @code{simplify} does: The expression is -first normalized and evaluated by calling @code{normalize}. If any -@code{AlgSimpRules} have been defined, they are then applied. Then -the expression is traversed in a depth-first, bottom-up fashion; at -each level, any simplifications that can be made are made until no -further changes are possible. Once the entire formula has been -traversed in this way, it is compared with the original formula (from -before the call to @code{normalize}) and, if it has changed, -the entire procedure is repeated (starting with @code{normalize}) -until no further changes occur. Usually only two iterations are -needed: one to simplify the formula, and another to verify that no -further simplifications were possible. -@end defun - -@defun simplify-extended expr -Simplify the expression @var{expr}, with additional rules enabled that -help do a more thorough job, while not being entirely ``safe'' in all -circumstances. (For example, this mode will simplify @samp{sqrt(x^2)} -to @samp{x}, which is only valid when @var{x} is positive.) This is -implemented by temporarily binding the variable @code{math-living-dangerously} -to @code{t} (using a @code{let} form) and calling @code{simplify}. -Dangerous simplification rules are written to check this variable -before taking any action. -@end defun - -@defun simplify-units expr -Simplify the expression @var{expr}, treating variable names as units -whenever possible. This works by binding the variable -@code{math-simplifying-units} to @code{t} while calling @code{simplify}. -@end defun - -@defmac math-defsimplify funcs body -Register a new simplification rule; this is normally called as a top-level -form, like @code{defun} or @code{defmath}. If @var{funcs} is a symbol -(like @code{+} or @code{calcFunc-sqrt}), this simplification rule is -applied to the formulas which are calls to the specified function. Or, -@var{funcs} can be a list of such symbols; the rule applies to all -functions on the list. The @var{body} is written like the body of a -function with a single argument called @code{expr}. The body will be -executed with @code{expr} bound to a formula which is a call to one of -the functions @var{funcs}. If the function body returns @code{nil}, or -if it returns a result @code{equal} to the original @code{expr}, it is -ignored and Calc goes on to try the next simplification rule that applies. -If the function body returns something different, that new formula is -substituted for @var{expr} in the original formula. - -At each point in the formula, rules are tried in the order of the -original calls to @code{math-defsimplify}; the search stops after the -first rule that makes a change. Thus later rules for that same -function will not have a chance to trigger until the next iteration -of the main @code{simplify} loop. - -Note that, since @code{defmath} is not being used here, @var{body} must -be written in true Lisp code without the conveniences that @code{defmath} -provides. If you prefer, you can have @var{body} simply call another -function (defined with @code{defmath}) which does the real work. - -The arguments of a function call will already have been simplified -before any rules for the call itself are invoked. Since a new argument -list is consed up when this happens, this means that the rule's body is -allowed to rearrange the function's arguments destructively if that is -convenient. Here is a typical example of a simplification rule: - -@smallexample -(math-defsimplify calcFunc-arcsinh - (or (and (math-looks-negp (nth 1 expr)) - (math-neg (list 'calcFunc-arcsinh - (math-neg (nth 1 expr))))) - (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh) - (or math-living-dangerously - (math-known-realp (nth 1 (nth 1 expr)))) - (nth 1 (nth 1 expr))))) -@end smallexample - -This is really a pair of rules written with one @code{math-defsimplify} -for convenience; the first replaces @samp{arcsinh(-x)} with -@samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x}, -replaces @samp{arcsinh(sinh(x))} with @samp{x}. -@end defmac - -@defun common-constant-factor expr -Check @var{expr} to see if it is a sum of terms all multiplied by the -same rational value. If so, return this value. If not, return @code{nil}. -For example, if called on @samp{6x + 9y + 12z}, it would return 3, since -3 is a common factor of all the terms. -@end defun - -@defun cancel-common-factor expr factor -Assuming @var{expr} is a sum with @var{factor} as a common factor, -divide each term of the sum by @var{factor}. This is done by -destructively modifying parts of @var{expr}, on the assumption that -it is being used by a simplification rule (where such things are -allowed; see above). For example, consider this built-in rule for -square roots: - -@smallexample -(math-defsimplify calcFunc-sqrt - (let ((fac (math-common-constant-factor (nth 1 expr)))) - (and fac (not (eq fac 1)) - (math-mul (math-normalize (list 'calcFunc-sqrt fac)) - (math-normalize - (list 'calcFunc-sqrt - (math-cancel-common-factor - (nth 1 expr) fac))))))) -@end smallexample -@end defun - -@defun frac-gcd a b -Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be -rational numbers. This is the fraction composed of the GCD of the -numerators of @var{a} and @var{b}, over the GCD of the denominators. -It is used by @code{common-constant-factor}. Note that the standard -@code{gcd} function uses the LCM to combine the denominators. -@end defun - -@defun map-tree func expr many -Try applying Lisp function @var{func} to various sub-expressions of -@var{expr}. Initially, call @var{func} with @var{expr} itself as an -argument. If this returns an expression which is not @code{equal} to -@var{expr}, apply @var{func} again until eventually it does return -@var{expr} with no changes. Then, if @var{expr} is a function call, -recursively apply @var{func} to each of the arguments. This keeps going -until no changes occur anywhere in the expression; this final expression -is returned by @code{map-tree}. Note that, unlike simplification rules, -@var{func} functions may @emph{not} make destructive changes to -@var{expr}. If a third argument @var{many} is provided, it is an -integer which says how many times @var{func} may be applied; the -default, as described above, is infinitely many times. -@end defun - -@defun compile-rewrites rules -Compile the rewrite rule set specified by @var{rules}, which should -be a formula that is either a vector or a variable name. If the latter, -the compiled rules are saved so that later @code{compile-rules} calls -for that same variable can return immediately. If there are problems -with the rules, this function calls @code{error} with a suitable -message. -@end defun - -@defun apply-rewrites expr crules heads -Apply the compiled rewrite rule set @var{crules} to the expression -@var{expr}. This will make only one rewrite and only checks at the -top level of the expression. The result @code{nil} if no rules -matched, or if the only rules that matched did not actually change -the expression. The @var{heads} argument is optional; if is given, -it should be a list of all function names that (may) appear in -@var{expr}. The rewrite compiler tags each rule with the -rarest-looking function name in the rule; if you specify @var{heads}, -@code{apply-rewrites} can use this information to narrow its search -down to just a few rules in the rule set. -@end defun - -@defun rewrite-heads expr -Compute a @var{heads} list for @var{expr} suitable for use with -@code{apply-rewrites}, as discussed above. -@end defun - -@defun rewrite expr rules many -This is an all-in-one rewrite function. It compiles the rule set -specified by @var{rules}, then uses @code{map-tree} to apply the -rules throughout @var{expr} up to @var{many} (default infinity) -times. -@end defun - -@defun match-patterns pat vec not-flag -Given a Calc vector @var{vec} and an uncompiled pattern set or -pattern set variable @var{pat}, this function returns a new vector -of all elements of @var{vec} which do (or don't, if @var{not-flag} is -non-@code{nil}) match any of the patterns in @var{pat}. -@end defun - -@defun deriv expr var value symb -Compute the derivative of @var{expr} with respect to variable @var{var} -(which may actually be any sub-expression). If @var{value} is specified, -the derivative is evaluated at the value of @var{var}; otherwise, the -derivative is left in terms of @var{var}. If the expression contains -functions for which no derivative formula is known, new derivative -functions are invented by adding primes to the names; @pxref{Calculus}. -However, if @var{symb} is non-@code{nil}, the presence of nondifferentiable -functions in @var{expr} instead cancels the whole differentiation, and -@code{deriv} returns @code{nil} instead. - -Derivatives of an @var{n}-argument function can be defined by -adding a @code{math-derivative-@var{n}} property to the property list -of the symbol for the function's derivative, which will be the -function name followed by an apostrophe. The value of the property -should be a Lisp function; it is called with the same arguments as the -original function call that is being differentiated. It should return -a formula for the derivative. For example, the derivative of @code{ln} -is defined by - -@smallexample -(put 'calcFunc-ln\' 'math-derivative-1 - (function (lambda (u) (math-div 1 u)))) -@end smallexample - -The two-argument @code{log} function has two derivatives, -@smallexample -(put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx - (function (lambda (x b) ... ))) -(put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db - (function (lambda (x b) ... ))) -@end smallexample -@end defun - -@defun tderiv expr var value symb -Compute the total derivative of @var{expr}. This is the same as -@code{deriv}, except that variables other than @var{var} are not -assumed to be constant with respect to @var{var}. -@end defun - -@defun integ expr var low high -Compute the integral of @var{expr} with respect to @var{var}. -@xref{Calculus}, for further details. -@end defun - -@defmac math-defintegral funcs body -Define a rule for integrating a function or functions of one argument; -this macro is very similar in format to @code{math-defsimplify}. -The main difference is that here @var{body} is the body of a function -with a single argument @code{u} which is bound to the argument to the -function being integrated, not the function call itself. Also, the -variable of integration is available as @code{math-integ-var}. If -evaluation of the integral requires doing further integrals, the body -should call @samp{(math-integral @var{x})} to find the integral of -@var{x} with respect to @code{math-integ-var}; this function returns -@code{nil} if the integral could not be done. Some examples: - -@smallexample -(math-defintegral calcFunc-conj - (let ((int (math-integral u))) - (and int - (list 'calcFunc-conj int)))) - -(math-defintegral calcFunc-cos - (and (equal u math-integ-var) - (math-from-radians-2 (list 'calcFunc-sin u)))) -@end smallexample - -In the @code{cos} example, we define only the integral of @samp{cos(x) dx}, -relying on the general integration-by-substitution facility to handle -cosines of more complicated arguments. An integration rule should return -@code{nil} if it can't do the integral; if several rules are defined for -the same function, they are tried in order until one returns a non-@code{nil} -result. -@end defmac - -@defmac math-defintegral-2 funcs body -Define a rule for integrating a function or functions of two arguments. -This is exactly analogous to @code{math-defintegral}, except that @var{body} -is written as the body of a function with two arguments, @var{u} and -@var{v}. -@end defmac - -@defun solve-for lhs rhs var full -Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating -the variable @var{var} on the lefthand side; return the resulting righthand -side, or @code{nil} if the equation cannot be solved. The variable -@var{var} must appear at least once in @var{lhs} or @var{rhs}. Note that -the return value is a formula which does not contain @var{var}; this is -different from the user-level @code{solve} and @code{finv} functions, -which return a rearranged equation or a functional inverse, respectively. -If @var{full} is non-@code{nil}, a full solution including dummy signs -and dummy integers will be produced. User-defined inverses are provided -as properties in a manner similar to derivatives: - -@smallexample -(put 'calcFunc-ln 'math-inverse - (function (lambda (x) (list 'calcFunc-exp x)))) -@end smallexample - -This function can call @samp{(math-solve-get-sign @var{x})} to create -a new arbitrary sign variable, returning @var{x} times that sign, and -@samp{(math-solve-get-int @var{x})} to create a new arbitrary integer -variable multiplied by @var{x}. These functions simply return @var{x} -if the caller requested a non-``full'' solution. -@end defun - -@defun solve-eqn expr var full -This version of @code{solve-for} takes an expression which will -typically be an equation or inequality. (If it is not, it will be -interpreted as the equation @samp{@var{expr} = 0}.) It returns an -equation or inequality, or @code{nil} if no solution could be found. -@end defun - -@defun solve-system exprs vars full -This function solves a system of equations. Generally, @var{exprs} -and @var{vars} will be vectors of equal length. -@xref{Solving Systems of Equations}, for other options. -@end defun - -@defun expr-contains expr var -Returns a non-@code{nil} value if @var{var} occurs as a subexpression -of @var{expr}. - -This function might seem at first to be identical to -@code{calc-find-sub-formula}. The key difference is that -@code{expr-contains} uses @code{equal} to test for matches, whereas -@code{calc-find-sub-formula} uses @code{eq}. In the formula -@samp{f(a, a)}, the two @samp{a}s will be @code{equal} but not -@code{eq} to each other. -@end defun - -@defun expr-contains-count expr var -Returns the number of occurrences of @var{var} as a subexpression -of @var{expr}, or @code{nil} if there are no occurrences. -@end defun - -@defun expr-depends expr var -Returns true if @var{expr} refers to any variable the occurs in @var{var}. -In other words, it checks if @var{expr} and @var{var} have any variables -in common. -@end defun - -@defun expr-contains-vars expr -Return true if @var{expr} contains any variables, or @code{nil} if @var{expr} -contains only constants and functions with constant arguments. -@end defun - -@defun expr-subst expr old new -Returns a copy of @var{expr}, with all occurrences of @var{old} replaced -by @var{new}. This treats @code{lambda} forms specially with respect -to the dummy argument variables, so that the effect is always to return -@var{expr} evaluated at @var{old} = @var{new}. -@end defun - -@defun multi-subst expr old new -This is like @code{expr-subst}, except that @var{old} and @var{new} -are lists of expressions to be substituted simultaneously. If one -list is shorter than the other, trailing elements of the longer list -are ignored. -@end defun - -@defun expr-weight expr -Returns the ``weight'' of @var{expr}, basically a count of the total -number of objects and function calls that appear in @var{expr}. For -``primitive'' objects, this will be one. -@end defun - -@defun expr-height expr -Returns the ``height'' of @var{expr}, which is the deepest level to -which function calls are nested. (Note that @samp{@var{a} + @var{b}} -counts as a function call.) For primitive objects, this returns zero. -@end defun - -@defun polynomial-p expr var -Check if @var{expr} is a polynomial in variable (or sub-expression) -@var{var}. If so, return the degree of the polynomial, that is, the -highest power of @var{var} that appears in @var{expr}. For example, -for @samp{(x^2 + 3)^3 + 4} this would return 6. This function returns -@code{nil} unless @var{expr}, when expanded out by @kbd{a x} -(@code{calc-expand}), would consist of a sum of terms in which @var{var} -appears only raised to nonnegative integer powers. Note that if -@var{var} does not occur in @var{expr}, then @var{expr} is considered -a polynomial of degree 0. -@end defun - -@defun is-polynomial expr var degree loose -Check if @var{expr} is a polynomial in variable or sub-expression -@var{var}, and, if so, return a list representation of the polynomial -where the elements of the list are coefficients of successive powers of -@var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the -list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would -produce the list @samp{(1 2 1)}. The highest element of the list will -be non-zero, with the special exception that if @var{expr} is the -constant zero, the returned value will be @samp{(0)}. Return @code{nil} -if @var{expr} is not a polynomial in @var{var}. If @var{degree} is -specified, this will not consider polynomials of degree higher than that -value. This is a good precaution because otherwise an input of -@samp{(x+1)^1000} will cause a huge coefficient list to be built. If -@var{loose} is non-@code{nil}, then a looser definition of a polynomial -is used in which coefficients are no longer required not to depend on -@var{var}, but are only required not to take the form of polynomials -themselves. For example, @samp{sin(x) x^2 + cos(x)} is a loose -polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin -x))}. The result will never be @code{nil} in loose mode, since any -expression can be interpreted as a ``constant'' loose polynomial. -@end defun - -@defun polynomial-base expr pred -Check if @var{expr} is a polynomial in any variable that occurs in it; -if so, return that variable. (If @var{expr} is a multivariate polynomial, -this chooses one variable arbitrarily.) If @var{pred} is specified, it should -be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})}, -and which should return true if @code{mpb-top-expr} (a global name for -the original @var{expr}) is a suitable polynomial in @var{subexpr}. -The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})}; -you can use @var{pred} to specify additional conditions. Or, you could -have @var{pred} build up a list of every suitable @var{subexpr} that -is found. -@end defun - -@defun poly-simplify poly -Simplify polynomial coefficient list @var{poly} by (destructively) -clipping off trailing zeros. -@end defun - -@defun poly-mix a ac b bc -Mix two polynomial lists @var{a} and @var{b} (in the form returned by -@code{is-polynomial}) in a linear combination with coefficient expressions -@var{ac} and @var{bc}. The result is a (not necessarily simplified) -polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}. -@end defun - -@defun poly-mul a b -Multiply two polynomial coefficient lists @var{a} and @var{b}. The -result will be in simplified form if the inputs were simplified. -@end defun - -@defun build-polynomial-expr poly var -Construct a Calc formula which represents the polynomial coefficient -list @var{poly} applied to variable @var{var}. The @kbd{a c} -(@code{calc-collect}) command uses @code{is-polynomial} to turn an -expression into a coefficient list, then @code{build-polynomial-expr} -to turn the list back into an expression in regular form. -@end defun - -@defun check-unit-name var -Check if @var{var} is a variable which can be interpreted as a unit -name. If so, return the units table entry for that unit. This -will be a list whose first element is the unit name (not counting -prefix characters) as a symbol and whose second element is the -Calc expression which defines the unit. (Refer to the Calc sources -for details on the remaining elements of this list.) If @var{var} -is not a variable or is not a unit name, return @code{nil}. -@end defun - -@defun units-in-expr-p expr sub-exprs -Return true if @var{expr} contains any variables which can be -interpreted as units. If @var{sub-exprs} is @code{t}, the entire -expression is searched. If @var{sub-exprs} is @code{nil}, this -checks whether @var{expr} is directly a units expression. -@end defun - -@defun single-units-in-expr-p expr -Check whether @var{expr} contains exactly one units variable. If so, -return the units table entry for the variable. If @var{expr} does -not contain any units, return @code{nil}. If @var{expr} contains -two or more units, return the symbol @code{wrong}. -@end defun - -@defun to-standard-units expr which -Convert units expression @var{expr} to base units. If @var{which} -is @code{nil}, use Calc's native base units. Otherwise, @var{which} -can specify a units system, which is a list of two-element lists, -where the first element is a Calc base symbol name and the second -is an expression to substitute for it. -@end defun - -@defun remove-units expr -Return a copy of @var{expr} with all units variables replaced by ones. -This expression is generally normalized before use. -@end defun - -@defun extract-units expr -Return a copy of @var{expr} with everything but units variables replaced -by ones. -@end defun - -@node Formatting Lisp Functions, Hooks, Symbolic Lisp Functions, Internals -@subsubsection I/O and Formatting Functions - -@noindent -The functions described here are responsible for parsing and formatting -Calc numbers and formulas. - -@defun calc-eval str sep arg1 arg2 @dots{} -This is the simplest interface to the Calculator from another Lisp program. -@xref{Calling Calc from Your Programs}. -@end defun - -@defun read-number str -If string @var{str} contains a valid Calc number, either integer, -fraction, float, or HMS form, this function parses and returns that -number. Otherwise, it returns @code{nil}. -@end defun - -@defun read-expr str -Read an algebraic expression from string @var{str}. If @var{str} does -not have the form of a valid expression, return a list of the form -@samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index -into @var{str} of the general location of the error, and @var{msg} is -a string describing the problem. -@end defun - -@defun read-exprs str -Read a list of expressions separated by commas, and return it as a -Lisp list. If an error occurs in any expressions, an error list as -shown above is returned instead. -@end defun - -@defun calc-do-alg-entry initial prompt no-norm -Read an algebraic formula or formulas using the minibuffer. All -conventions of regular algebraic entry are observed. The return value -is a list of Calc formulas; there will be more than one if the user -entered a list of values separated by commas. The result is @code{nil} -if the user presses Return with a blank line. If @var{initial} is -given, it is a string which the minibuffer will initially contain. -If @var{prompt} is given, it is the prompt string to use; the default -is ``Algebraic:''. If @var{no-norm} is @code{t}, the formulas will -be returned exactly as parsed; otherwise, they will be passed through -@code{calc-normalize} first. - -To support the use of @kbd{$} characters in the algebraic entry, use -@code{let} to bind @code{calc-dollar-values} to a list of the values -to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind -@code{calc-dollar-used} to 0. Upon return, @code{calc-dollar-used} -will have been changed to the highest number of consecutive @kbd{$}s -that actually appeared in the input. -@end defun - -@defun format-number a -Convert the real or complex number or HMS form @var{a} to string form. -@end defun - -@defun format-flat-expr a prec -Convert the arbitrary Calc number or formula @var{a} to string form, -in the style used by the trail buffer and the @code{calc-edit} command. -This is a simple format designed -mostly to guarantee the string is of a form that can be re-parsed by -@code{read-expr}. Most formatting modes, such as digit grouping, -complex number format, and point character, are ignored to ensure the -result will be re-readable. The @var{prec} parameter is normally 0; if -you pass a large integer like 1000 instead, the expression will be -surrounded by parentheses unless it is a plain number or variable name. -@end defun - -@defun format-nice-expr a width -This is like @code{format-flat-expr} (with @var{prec} equal to 0), -except that newlines will be inserted to keep lines down to the -specified @var{width}, and vectors that look like matrices or rewrite -rules are written in a pseudo-matrix format. The @code{calc-edit} -command uses this when only one stack entry is being edited. -@end defun - -@defun format-value a width -Convert the Calc number or formula @var{a} to string form, using the -format seen in the stack buffer. Beware the string returned may -not be re-readable by @code{read-expr}, for example, because of digit -grouping. Multi-line objects like matrices produce strings that -contain newline characters to separate the lines. The @var{w} -parameter, if given, is the target window size for which to format -the expressions. If @var{w} is omitted, the width of the Calculator -window is used. -@end defun - -@defun compose-expr a prec -Format the Calc number or formula @var{a} according to the current -language mode, returning a ``composition.'' To learn about the -structure of compositions, see the comments in the Calc source code. -You can specify the format of a given type of function call by putting -a @code{math-compose-@var{lang}} property on the function's symbol, -whose value is a Lisp function that takes @var{a} and @var{prec} as -arguments and returns a composition. Here @var{lang} is a language -mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal}, -@code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}. -In Big mode, Calc actually tries @code{math-compose-big} first, then -tries @code{math-compose-normal}. If this property does not exist, -or if the function returns @code{nil}, the function is written in the -normal function-call notation for that language. -@end defun - -@defun composition-to-string c w -Convert a composition structure returned by @code{compose-expr} into -a string. Multi-line compositions convert to strings containing -newline characters. The target window size is given by @var{w}. -The @code{format-value} function basically calls @code{compose-expr} -followed by @code{composition-to-string}. -@end defun - -@defun comp-width c -Compute the width in characters of composition @var{c}. -@end defun - -@defun comp-height c -Compute the height in lines of composition @var{c}. -@end defun - -@defun comp-ascent c -Compute the portion of the height of composition @var{c} which is on or -above the baseline. For a one-line composition, this will be one. -@end defun - -@defun comp-descent c -Compute the portion of the height of composition @var{c} which is below -the baseline. For a one-line composition, this will be zero. -@end defun - -@defun comp-first-char c -If composition @var{c} is a ``flat'' composition, return the first -(leftmost) character of the composition as an integer. Otherwise, -return @code{nil}. -@end defun - -@defun comp-last-char c -If composition @var{c} is a ``flat'' composition, return the last -(rightmost) character, otherwise return @code{nil}. -@end defun - -@comment @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals -@comment @subsubsection Lisp Variables -@comment -@comment @noindent -@comment (This section is currently unfinished.) - -@node Hooks, , Formatting Lisp Functions, Internals -@subsubsection Hooks - -@noindent -Hooks are variables which contain Lisp functions (or lists of functions) -which are called at various times. Calc defines a number of hooks -that help you to customize it in various ways. Calc uses the Lisp -function @code{run-hooks} to invoke the hooks shown below. Several -other customization-related variables are also described here. - -@defvar calc-load-hook -This hook is called at the end of @file{calc.el}, after the file has -been loaded, before any functions in it have been called, but after -@code{calc-mode-map} and similar variables have been set up. -@end defvar - -@defvar calc-ext-load-hook -This hook is called at the end of @file{calc-ext.el}. -@end defvar - -@defvar calc-start-hook -This hook is called as the last step in a @kbd{M-x calc} command. -At this point, the Calc buffer has been created and initialized if -necessary, the Calc window and trail window have been created, -and the ``Welcome to Calc'' message has been displayed. -@end defvar - -@defvar calc-mode-hook -This hook is called when the Calc buffer is being created. Usually -this will only happen once per Emacs session. The hook is called -after Emacs has switched to the new buffer, the mode-settings file -has been read if necessary, and all other buffer-local variables -have been set up. After this hook returns, Calc will perform a -@code{calc-refresh} operation, set up the mode line display, then -evaluate any deferred @code{calc-define} properties that have not -been evaluated yet. -@end defvar - -@defvar calc-trail-mode-hook -This hook is called when the Calc Trail buffer is being created. -It is called as the very last step of setting up the Trail buffer. -Like @code{calc-mode-hook}, this will normally happen only once -per Emacs session. -@end defvar - -@defvar calc-end-hook -This hook is called by @code{calc-quit}, generally because the user -presses @kbd{q} or @kbd{C-x * c} while in Calc. The Calc buffer will -be the current buffer. The hook is called as the very first -step, before the Calc window is destroyed. -@end defvar - -@defvar calc-window-hook -If this hook is non-@code{nil}, it is called to create the Calc window. -Upon return, this new Calc window should be the current window. -(The Calc buffer will already be the current buffer when the -hook is called.) If the hook is not defined, Calc will -generally use @code{split-window}, @code{set-window-buffer}, -and @code{select-window} to create the Calc window. -@end defvar - -@defvar calc-trail-window-hook -If this hook is non-@code{nil}, it is called to create the Calc Trail -window. The variable @code{calc-trail-buffer} will contain the buffer -which the window should use. Unlike @code{calc-window-hook}, this hook -must @emph{not} switch into the new window. -@end defvar - -@defvar calc-embedded-mode-hook -This hook is called the first time that Embedded mode is entered. -@end defvar - -@defvar calc-embedded-new-buffer-hook -This hook is called each time that Embedded mode is entered in a -new buffer. -@end defvar - -@defvar calc-embedded-new-formula-hook -This hook is called each time that Embedded mode is enabled for a -new formula. -@end defvar - -@defvar calc-edit-mode-hook -This hook is called by @code{calc-edit} (and the other ``edit'' -commands) when the temporary editing buffer is being created. -The buffer will have been selected and set up to be in -@code{calc-edit-mode}, but will not yet have been filled with -text. (In fact it may still have leftover text from a previous -@code{calc-edit} command.) -@end defvar - -@defvar calc-mode-save-hook -This hook is called by the @code{calc-save-modes} command, -after Calc's own mode features have been inserted into the -Calc init file and just before the ``End of mode settings'' -message is inserted. -@end defvar - -@defvar calc-reset-hook -This hook is called after @kbd{C-x * 0} (@code{calc-reset}) has -reset all modes. The Calc buffer will be the current buffer. -@end defvar - -@defvar calc-other-modes -This variable contains a list of strings. The strings are -concatenated at the end of the modes portion of the Calc -mode line (after standard modes such as ``Deg'', ``Inv'' and -``Hyp''). Each string should be a short, single word followed -by a space. The variable is @code{nil} by default. -@end defvar - -@defvar calc-mode-map -This is the keymap that is used by Calc mode. The best time -to adjust it is probably in a @code{calc-mode-hook}. If the -Calc extensions package (@file{calc-ext.el}) has not yet been -loaded, many of these keys will be bound to @code{calc-missing-key}, -which is a command that loads the extensions package and -``retypes'' the key. If your @code{calc-mode-hook} rebinds -one of these keys, it will probably be overridden when the -extensions are loaded. -@end defvar - -@defvar calc-digit-map -This is the keymap that is used during numeric entry. Numeric -entry uses the minibuffer, but this map binds every non-numeric -key to @code{calcDigit-nondigit} which generally calls -@code{exit-minibuffer} and ``retypes'' the key. -@end defvar - -@defvar calc-alg-ent-map -This is the keymap that is used during algebraic entry. This is -mostly a copy of @code{minibuffer-local-map}. -@end defvar - -@defvar calc-store-var-map -This is the keymap that is used during entry of variable names for -commands like @code{calc-store} and @code{calc-recall}. This is -mostly a copy of @code{minibuffer-local-completion-map}. -@end defvar - -@defvar calc-edit-mode-map -This is the (sparse) keymap used by @code{calc-edit} and other -temporary editing commands. It binds @key{RET}, @key{LFD}, -and @kbd{C-c C-c} to @code{calc-edit-finish}. -@end defvar - -@defvar calc-mode-var-list -This is a list of variables which are saved by @code{calc-save-modes}. -Each entry is a list of two items, the variable (as a Lisp symbol) -and its default value. When modes are being saved, each variable -is compared with its default value (using @code{equal}) and any -non-default variables are written out. -@end defvar - -@defvar calc-local-var-list -This is a list of variables which should be buffer-local to the -Calc buffer. Each entry is a variable name (as a Lisp symbol). -These variables also have their default values manipulated by -the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}. -Since @code{calc-mode-hook} is called after this list has been -used the first time, your hook should add a variable to the -list and also call @code{make-local-variable} itself. -@end defvar - -@node Copying, GNU Free Documentation License, Programming, Top -@appendix GNU GENERAL PUBLIC LICENSE -@include gpl.texi - -@node GNU Free Documentation License, Customizing Calc, Copying, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Customizing Calc, Reporting Bugs, GNU Free Documentation License, Top -@appendix Customizing Calc - -The usual prefix for Calc is the key sequence @kbd{C-x *}. If you wish -to use a different prefix, you can put - -@example -(global-set-key "NEWPREFIX" 'calc-dispatch) -@end example - -@noindent -in your .emacs file. -(@xref{Key Bindings,,Customizing Key Bindings,emacs, -The GNU Emacs Manual}, for more information on binding keys.) -A convenient way to start Calc is with @kbd{C-x * *}; to make it equally -convenient for users who use a different prefix, the prefix can be -followed by @kbd{=}, @kbd{&}, @kbd{#}, @kbd{\}, @kbd{/}, @kbd{+} or -@kbd{-} as well as @kbd{*} to start Calc, and so in many cases the last -character of the prefix can simply be typed twice. - -Calc is controlled by many variables, most of which can be reset -from within Calc. Some variables are less involved with actual -calculation and can be set outside of Calc using Emacs's -customization facilities. These variables are listed below. -Typing @kbd{M-x customize-variable RET @var{variable-name} RET} -will bring up a buffer in which the variable's value can be redefined. -Typing @kbd{M-x customize-group RET calc RET} will bring up a buffer which -contains all of Calc's customizable variables. (These variables can -also be reset by putting the appropriate lines in your .emacs file; -@xref{Init File, ,Init File, emacs, The GNU Emacs Manual}.) - -Some of the customizable variables are regular expressions. A regular -expression is basically a pattern that Calc can search for. -See @ref{Regexp Search,, Regular Expression Search, emacs, The GNU Emacs Manual} -to see how regular expressions work. - -@defvar calc-settings-file -The variable @code{calc-settings-file} holds the file name in -which commands like @kbd{m m} and @kbd{Z P} store ``permanent'' -definitions. -If @code{calc-settings-file} is not your user init file (typically -@file{~/.emacs}) and if the variable @code{calc-loaded-settings-file} is -@code{nil}, then Calc will automatically load your settings file (if it -exists) the first time Calc is invoked. - -The default value for this variable is @code{"~/.emacs.d/calc.el"} -unless the file @file{~/.calc.el} exists, in which case the default -value will be @code{"~/.calc.el"}. -@end defvar - -@defvar calc-gnuplot-name -See @ref{Graphics}.@* -The variable @code{calc-gnuplot-name} should be the name of the -GNUPLOT program (a string). If you have GNUPLOT installed on your -system but Calc is unable to find it, you may need to set this -variable. You may also need to set some Lisp variables to show Calc how -to run GNUPLOT on your system, see @ref{Devices, ,Graphical Devices} . -The default value of @code{calc-gnuplot-name} is @code{"gnuplot"}. -@end defvar - -@defvar calc-gnuplot-plot-command -@defvarx calc-gnuplot-print-command -See @ref{Devices, ,Graphical Devices}.@* -The variables @code{calc-gnuplot-plot-command} and -@code{calc-gnuplot-print-command} represent system commands to -display and print the output of GNUPLOT, respectively. These may be -@code{nil} if no command is necessary, or strings which can include -@samp{%s} to signify the name of the file to be displayed or printed. -Or, these variables may contain Lisp expressions which are evaluated -to display or print the output. - -The default value of @code{calc-gnuplot-plot-command} is @code{nil}, -and the default value of @code{calc-gnuplot-print-command} is -@code{"lp %s"}. -@end defvar - -@defvar calc-language-alist -See @ref{Basic Embedded Mode}.@* -The variable @code{calc-language-alist} controls the languages that -Calc will associate with major modes. When Calc embedded mode is -enabled, it will try to use the current major mode to -determine what language should be used. (This can be overridden using -Calc's mode changing commands, @xref{Mode Settings in Embedded Mode}.) -The variable @code{calc-language-alist} consists of a list of pairs of -the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example, -@code{(latex-mode . latex)} is one such pair. If Calc embedded is -activated in a buffer whose major mode is @var{MAJOR-MODE}, it will set itself -to use the language @var{LANGUAGE}. - -The default value of @code{calc-language-alist} is -@example - ((latex-mode . latex) - (tex-mode . tex) - (plain-tex-mode . tex) - (context-mode . tex) - (nroff-mode . eqn) - (pascal-mode . pascal) - (c-mode . c) - (c++-mode . c) - (fortran-mode . fortran) - (f90-mode . fortran)) -@end example -@end defvar - -@defvar calc-embedded-announce-formula -@defvarx calc-embedded-announce-formula-alist -See @ref{Customizing Embedded Mode}.@* -The variable @code{calc-embedded-announce-formula} helps determine -what formulas @kbd{C-x * a} will activate in a buffer. It is a -regular expression, and when activating embedded formulas with -@kbd{C-x * a}, it will tell Calc that what follows is a formula to be -activated. (Calc also uses other patterns to find formulas, such as -@samp{=>} and @samp{:=}.) - -The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which checks -for @samp{%Embed} followed by any number of lines beginning with -@samp{%} and a space. - -The variable @code{calc-embedded-announce-formula-alist} is used to -set @code{calc-embedded-announce-formula} to different regular -expressions depending on the major mode of the editing buffer. -It consists of a list of pairs of the form @code{(@var{MAJOR-MODE} . -@var{REGEXP})}, and its default value is -@example - ((c++-mode . "//Embed\n\\(// .*\n\\)*") - (c-mode . "/\\*Embed\\*/\n\\(/\\* .*\\*/\n\\)*") - (f90-mode . "!Embed\n\\(! .*\n\\)*") - (fortran-mode . "C Embed\n\\(C .*\n\\)*") - (html-helper-mode . "\n\\(\n\\)*") - (html-mode . "\n\\(\n\\)*") - (nroff-mode . "\\\\\"Embed\n\\(\\\\\" .*\n\\)*") - (pascal-mode . "@{Embed@}\n\\(@{.*@}\n\\)*") - (sgml-mode . "\n\\(\n\\)*") - (xml-mode . "\n\\(\n\\)*") - (texinfo-mode . "@@c Embed\n\\(@@c .*\n\\)*")) -@end example -Any major modes added to @code{calc-embedded-announce-formula-alist} -should also be added to @code{calc-embedded-open-close-plain-alist} -and @code{calc-embedded-open-close-mode-alist}. -@end defvar - -@defvar calc-embedded-open-formula -@defvarx calc-embedded-close-formula -@defvarx calc-embedded-open-close-formula-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-formula} and -@code{calc-embedded-close-formula} control the region that Calc will -activate as a formula when Embedded mode is entered with @kbd{C-x * e}. -They are regular expressions; -Calc normally scans backward and forward in the buffer for the -nearest text matching these regular expressions to be the ``formula -delimiters''. - -The simplest delimiters are blank lines. Other delimiters that -Embedded mode understands by default are: -@enumerate -@item -The @TeX{} and @LaTeX{} math delimiters @samp{$ $}, @samp{$$ $$}, -@samp{\[ \]}, and @samp{\( \)}; -@item -Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); -@item -Lines beginning with @samp{@@} (Texinfo delimiters). -@item -Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); -@item -Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. -@end enumerate - -The variable @code{calc-embedded-open-close-formula-alist} is used to -set @code{calc-embedded-open-formula} and -@code{calc-embedded-close-formula} to different regular -expressions depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-FORMULA-REGEXP} -@var{CLOSE-FORMULA-REGEXP})}, and its default value is -@code{nil}. -@end defvar - -@defvar calc-embedded-word-regexp -@defvarx calc-embedded-word-regexp-alist -See @ref{Customizing Embedded Mode}.@* -The variable @code{calc-embedded-word-regexp} determines the expression -that Calc will activate when Embedded mode is entered with @kbd{C-x * -w}. It is a regular expressions. - -The default value of @code{calc-embedded-word-regexp} is -@code{"[-+]?[0-9]+\\(\\.[0-9]+\\)?\\([eE][-+]?[0-9]+\\)?"}. - -The variable @code{calc-embedded-word-regexp-alist} is used to -set @code{calc-embedded-word-regexp} to a different regular -expression depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{WORD-REGEXP})}, and its default value is -@code{nil}. -@end defvar - -@defvar calc-embedded-open-plain -@defvarx calc-embedded-close-plain -@defvarx calc-embedded-open-close-plain-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-plain} and -@code{calc-embedded-open-plain} are used to delimit ``plain'' -formulas. Note that these are actual strings, not regular -expressions, because Calc must be able to write these string into a -buffer as well as to recognize them. - -The default string for @code{calc-embedded-open-plain} is -@code{"%%% "}, note the trailing space. The default string for -@code{calc-embedded-close-plain} is @code{" %%%\n"}, without -the trailing newline here, the first line of a Big mode formula -that followed might be shifted over with respect to the other lines. - -The variable @code{calc-embedded-open-close-plain-alist} is used to -set @code{calc-embedded-open-plain} and -@code{calc-embedded-close-plain} to different strings -depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-PLAIN-STRING} -@var{CLOSE-PLAIN-STRING})}, and its default value is -@example - ((c++-mode "// %% " " %%\n") - (c-mode "/* %% " " %% */\n") - (f90-mode "! %% " " %%\n") - (fortran-mode "C %% " " %%\n") - (html-helper-mode "\n") - (html-mode "\n") - (nroff-mode "\\\" %% " " %%\n") - (pascal-mode "@{%% " " %%@}\n") - (sgml-mode "\n") - (xml-mode "\n") - (texinfo-mode "@@c %% " " %%\n")) -@end example -Any major modes added to @code{calc-embedded-open-close-plain-alist} -should also be added to @code{calc-embedded-announce-formula-alist} -and @code{calc-embedded-open-close-mode-alist}. -@end defvar - -@defvar calc-embedded-open-new-formula -@defvarx calc-embedded-close-new-formula -@defvarx calc-embedded-open-close-new-formula-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-new-formula} and -@code{calc-embedded-close-new-formula} are strings which are -inserted before and after a new formula when you type @kbd{C-x * f}. - -The default value of @code{calc-embedded-open-new-formula} is -@code{"\n\n"}. If this string begins with a newline character and the -@kbd{C-x * f} is typed at the beginning of a line, @kbd{C-x * f} will skip -this first newline to avoid introducing unnecessary blank lines in the -file. The default value of @code{calc-embedded-close-new-formula} is -also @code{"\n\n"}. The final newline is omitted by @w{@kbd{C-x * f}} -if typed at the end of a line. (It follows that if @kbd{C-x * f} is -typed on a blank line, both a leading opening newline and a trailing -closing newline are omitted.) - -The variable @code{calc-embedded-open-close-new-formula-alist} is used to -set @code{calc-embedded-open-new-formula} and -@code{calc-embedded-close-new-formula} to different strings -depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-NEW-FORMULA-STRING} -@var{CLOSE-NEW-FORMULA-STRING})}, and its default value is -@code{nil}. -@end defvar - -@defvar calc-embedded-open-mode -@defvarx calc-embedded-close-mode -@defvarx calc-embedded-open-close-mode-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-mode} and -@code{calc-embedded-close-mode} are strings which Calc will place before -and after any mode annotations that it inserts. Calc never scans for -these strings; Calc always looks for the annotation itself, so it is not -necessary to add them to user-written annotations. - -The default value of @code{calc-embedded-open-mode} is @code{"% "} -and the default value of @code{calc-embedded-close-mode} is -@code{"\n"}. -If you change the value of @code{calc-embedded-close-mode}, it is a good -idea still to end with a newline so that mode annotations will appear on -lines by themselves. - -The variable @code{calc-embedded-open-close-mode-alist} is used to -set @code{calc-embedded-open-mode} and -@code{calc-embedded-close-mode} to different strings -expressions depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-MODE-STRING} -@var{CLOSE-MODE-STRING})}, and its default value is -@example - ((c++-mode "// " "\n") - (c-mode "/* " " */\n") - (f90-mode "! " "\n") - (fortran-mode "C " "\n") - (html-helper-mode "\n") - (html-mode "\n") - (nroff-mode "\\\" " "\n") - (pascal-mode "@{ " " @}\n") - (sgml-mode "\n") - (xml-mode "\n") - (texinfo-mode "@@c " "\n")) -@end example -Any major modes added to @code{calc-embedded-open-close-mode-alist} -should also be added to @code{calc-embedded-announce-formula-alist} -and @code{calc-embedded-open-close-plain-alist}. -@end defvar - -@defvar calc-lu-power-reference -@defvarx calc-lu-field-reference -See @ref{Logarithmic Units}.@* -The variables @code{calc-lu-power-reference} and -@code{calc-lu-field-reference} are unit expressions (written as -strings) which Calc will use as reference quantities for logarithmic -units. - -The default value of @code{calc-lu-power-reference} is @code{"mW"} -and the default value of @code{calc-lu-field-reference} is -@code{"20 uPa"}. -@end defvar - -@defvar calc-note-threshold -See @ref{Musical Notes}.@* -The variable @code{calc-note-threshold} is a number (written as a -string) which determines how close (in cents) a frequency needs to be -to a note to be recognized as that note. - -The default value of @code{calc-note-threshold} is 1. -@end defvar - -@defvar calc-highlight-selections-with-faces -@defvarx calc-selected-face -@defvarx calc-nonselected-face -See @ref{Displaying Selections}.@* -The variable @code{calc-highlight-selections-with-faces} -determines how selected sub-formulas are distinguished. -If @code{calc-highlight-selections-with-faces} is nil, then -a selected sub-formula is distinguished either by changing every -character not part of the sub-formula with a dot or by changing every -character in the sub-formula with a @samp{#} sign. -If @code{calc-highlight-selections-with-faces} is t, -then a selected sub-formula is distinguished either by displaying the -non-selected portion of the formula with @code{calc-nonselected-face} -or by displaying the selected sub-formula with -@code{calc-nonselected-face}. -@end defvar - -@defvar calc-multiplication-has-precedence -The variable @code{calc-multiplication-has-precedence} determines -whether multiplication has precedence over division in algebraic -formulas in normal language modes. If -@code{calc-multiplication-has-precedence} is non-@code{nil}, then -multiplication has precedence (and, for certain obscure reasons, is -right associative), and so for example @samp{a/b*c} will be interpreted -as @samp{a/(b*c)}. If @code{calc-multiplication-has-precedence} is -@code{nil}, then multiplication has the same precedence as division -(and, like division, is left associative), and so for example -@samp{a/b*c} will be interpreted as @samp{(a/b)*c}. The default value -of @code{calc-multiplication-has-precedence} is @code{t}. -@end defvar - -@defvar calc-ensure-consistent-units -When converting units, the variable @code{calc-ensure-consistent-units} -determines whether or not the target units need to be consistent with the -original units. If @code{calc-ensure-consistent-units} is @code{nil}, then -the target units don't need to have the same dimensions as the original units; -for example, converting @samp{100 ft/s} to @samp{m} will produce @samp{30.48 m/s}. -If @code{calc-ensure-consistent-units} is non-@code{nil}, then the target units -need to have the same dimensions as the original units; for example, converting -@samp{100 ft/s} to @samp{m} will result in an error, since @samp{ft/s} and @samp{m} -have different dimensions. The default value of @code{calc-ensure-consistent-units} -is @code{nil}. -@end defvar - -@defvar calc-context-sensitive-enter -The commands @code{calc-enter} and @code{calc-pop} will typically -duplicate the top of the stack. If -@code{calc-context-sensitive-enter} is non-@code{nil}, then the -@code{calc-enter} will copy the element at the cursor to the -top of the stack and @code{calc-pop} will delete the element at the -cursor. The default value of @code{calc-context-sensitive-enter} is -@code{nil}. -@end defvar - -@defvar calc-undo-length -The variable @code{calc-undo-length} determines the number of undo -steps that Calc will keep track of when @code{calc-quit} is called. -If @code{calc-undo-length} is a non-negative integer, then this is the -number of undo steps that will be preserved; if -@code{calc-undo-length} has any other value, then all undo steps will -be preserved. The default value of @code{calc-undo-length} is @expr{100}. -@end defvar - -@defvar calc-gregorian-switch -See @ref{Date Forms}.@* -The variable @code{calc-gregorian-switch} is either a list of integers -@code{(@var{YEAR} @var{MONTH} @var{DAY})} or @code{nil}. -If it is @code{nil}, then Calc's date forms always represent Gregorian dates. -Otherwise, @code{calc-gregorian-switch} represents the date that the -calendar switches from Julian dates to Gregorian dates; -@code{(@var{YEAR} @var{MONTH} @var{DAY})} will be the first Gregorian -date. The customization buffer will offer several standard dates to -choose from, or the user can enter their own date. - -The default value of @code{calc-gregorian-switch} is @code{nil}. -@end defvar - -@node Reporting Bugs, Summary, Customizing Calc, Top -@appendix Reporting Bugs - -@noindent -If you find a bug in Calc, send e-mail to Jay Belanger, - -@example -jay.p.belanger@@gmail.com -@end example - -@noindent -There is an automatic command @kbd{M-x report-calc-bug} which helps -you to report bugs. This command prompts you for a brief subject -line, then leaves you in a mail editing buffer. Type @kbd{C-c C-c} to -send your mail. Make sure your subject line indicates that you are -reporting a Calc bug; this command sends mail to the maintainer's -regular mailbox. - -If you have suggestions for additional features for Calc, please send -them. Some have dared to suggest that Calc is already top-heavy with -features; this obviously cannot be the case, so if you have ideas, send -them right in. - -At the front of the source file, @file{calc.el}, is a list of ideas for -future work. If any enthusiastic souls wish to take it upon themselves -to work on these, please send a message (using @kbd{M-x report-calc-bug}) -so any efforts can be coordinated. - -The latest version of Calc is available from Savannah, in the Emacs -repository. See @uref{http://savannah.gnu.org/projects/emacs}. - -@c [summary] -@node Summary, Key Index, Reporting Bugs, Top -@appendix Calc Summary - -@noindent -This section includes a complete list of Calc keystroke commands. -Each line lists the stack entries used by the command (top-of-stack -last), the keystrokes themselves, the prompts asked by the command, -and the result of the command (also with top-of-stack last). -The result is expressed using the equivalent algebraic function. -Commands which put no results on the stack show the full @kbd{M-x} -command name in that position. Numbers preceding the result or -command name refer to notes at the end. - -Algebraic functions and @kbd{M-x} commands that don't have corresponding -keystrokes are not listed in this summary. -@xref{Command Index}. @xref{Function Index}. - -@iftex -@begingroup -@tex -\vskip-2\baselineskip \null -\gdef\sumrow#1{\sumrowx#1\relax}% -\gdef\sumrowx#1\:#2\:#3\:#4\:#5\:#6\relax{% -\leavevmode% -{\smallfonts -\hbox to5em{\sl\hss#1}% -\hbox to5em{\tt#2\hss}% -\hbox to4em{\sl#3\hss}% -\hbox to5em{\rm\hss#4}% -\thinspace% -{\tt#5}% -{\sl#6}% -}}% -\gdef\sumlpar{{\rm(}}% -\gdef\sumrpar{{\rm)}}% -\gdef\sumcomma{{\rm,\thinspace}}% -\gdef\sumexcl{{\rm!}}% -\gdef\sumbreak{\vskip-2.5\baselineskip\goodbreak}% -\gdef\minus#1{{\tt-}}% -@end tex -@let@:=@sumsep -@let@r=@sumrow -@catcode`@(=@active @let(=@sumlpar -@catcode`@)=@active @let)=@sumrpar -@catcode`@,=@active @let,=@sumcomma -@catcode`@!=@active @let!=@sumexcl -@end iftex -@format -@iftex -@advance@baselineskip-2.5pt -@let@c@sumbreak -@end iftex -@r{ @: C-x * a @: @: 33 @:calc-embedded-activate@:} -@r{ @: C-x * b @: @: @:calc-big-or-small@:} -@r{ @: C-x * c @: @: @:calc@:} -@r{ @: C-x * d @: @: @:calc-embedded-duplicate@:} -@r{ @: C-x * e @: @: 34 @:calc-embedded@:} -@r{ @: C-x * f @:formula @: @:calc-embedded-new-formula@:} -@r{ @: C-x * g @: @: 35 @:calc-grab-region@:} -@r{ @: C-x * i @: @: @:calc-info@:} -@r{ @: C-x * j @: @: @:calc-embedded-select@:} -@r{ @: C-x * k @: @: @:calc-keypad@:} -@r{ @: C-x * l @: @: @:calc-load-everything@:} -@r{ @: C-x * m @: @: @:read-kbd-macro@:} -@r{ @: C-x * n @: @: 4 @:calc-embedded-next@:} -@r{ @: C-x * o @: @: @:calc-other-window@:} -@r{ @: C-x * p @: @: 4 @:calc-embedded-previous@:} -@r{ @: C-x * q @:formula @: @:quick-calc@:} -@r{ @: C-x * r @: @: 36 @:calc-grab-rectangle@:} -@r{ @: C-x * s @: @: @:calc-info-summary@:} -@r{ @: C-x * t @: @: @:calc-tutorial@:} -@r{ @: C-x * u @: @: @:calc-embedded-update-formula@:} -@r{ @: C-x * w @: @: @:calc-embedded-word@:} -@r{ @: C-x * x @: @: @:calc-quit@:} -@r{ @: C-x * y @: @:1,28,49 @:calc-copy-to-buffer@:} -@r{ @: C-x * z @: @: @:calc-user-invocation@:} -@r{ @: C-x * : @: @: 36 @:calc-grab-sum-down@:} -@r{ @: C-x * _ @: @: 36 @:calc-grab-sum-across@:} -@r{ @: C-x * ` @:editing @: 30 @:calc-embedded-edit@:} -@r{ @: C-x * 0 @:(zero) @: @:calc-reset@:} - -@c -@r{ @: 0-9 @:number @: @:@:number} -@r{ @: . @:number @: @:@:0.number} -@r{ @: _ @:number @: @:-@:number} -@r{ @: e @:number @: @:@:1e number} -@r{ @: # @:number @: @:@:current-radix@tfn{#}number} -@r{ @: P @:(in number) @: @:+/-@:} -@r{ @: M @:(in number) @: @:mod@:} -@r{ @: @@ ' " @: (in number)@: @:@:HMS form} -@r{ @: h m s @: (in number)@: @:@:HMS form} - -@c -@r{ @: ' @:formula @: 37,46 @:@:formula} -@r{ @: $ @:formula @: 37,46 @:$@:formula} -@r{ @: " @:string @: 37,46 @:@:string} - -@c -@r{ a b@: + @: @: 2 @:add@:(a,b) a+b} -@r{ a b@: - @: @: 2 @:sub@:(a,b) a@minus{}b} -@r{ a b@: * @: @: 2 @:mul@:(a,b) a b, a*b} -@r{ a b@: / @: @: 2 @:div@:(a,b) a/b} -@r{ a b@: ^ @: @: 2 @:pow@:(a,b) a^b} -@r{ a b@: I ^ @: @: 2 @:nroot@:(a,b) a^(1/b)} -@r{ a b@: % @: @: 2 @:mod@:(a,b) a%b} -@r{ a b@: \ @: @: 2 @:idiv@:(a,b) a\b} -@r{ a b@: : @: @: 2 @:fdiv@:(a,b)} -@r{ a b@: | @: @: 2 @:vconcat@:(a,b) a|b} -@r{ a b@: I | @: @: @:vconcat@:(b,a) b|a} -@r{ a b@: H | @: @: 2 @:append@:(a,b)} -@r{ a b@: I H | @: @: @:append@:(b,a)} -@r{ a@: & @: @: 1 @:inv@:(a) 1/a} -@r{ a@: ! @: @: 1 @:fact@:(a) a!} -@r{ a@: = @: @: 1 @:evalv@:(a)} -@r{ a@: M-% @: @: @:percent@:(a) a%} - -@c -@r{ ... a@: @summarykey{RET} @: @: 1 @:@:... a a} -@r{ ... a@: @summarykey{SPC} @: @: 1 @:@:... a a} -@r{... a b@: @summarykey{TAB} @: @: 3 @:@:... b a} -@r{. a b c@: M-@summarykey{TAB} @: @: 3 @:@:... b c a} -@r{... a b@: @summarykey{LFD} @: @: 1 @:@:... a b a} -@r{ ... a@: @summarykey{DEL} @: @: 1 @:@:...} -@r{... a b@: M-@summarykey{DEL} @: @: 1 @:@:... b} -@r{ @: M-@summarykey{RET} @: @: 4 @:calc-last-args@:} -@r{ a@: ` @:editing @: 1,30 @:calc-edit@:} - -@c -@r{ ... a@: C-d @: @: 1 @:@:...} -@r{ @: C-k @: @: 27 @:calc-kill@:} -@r{ @: C-w @: @: 27 @:calc-kill-region@:} -@r{ @: C-y @: @: @:calc-yank@:} -@r{ @: C-_ @: @: 4 @:calc-undo@:} -@r{ @: M-k @: @: 27 @:calc-copy-as-kill@:} -@r{ @: M-w @: @: 27 @:calc-copy-region-as-kill@:} - -@c -@r{ @: [ @: @: @:@:[...} -@r{[.. a b@: ] @: @: @:@:[a,b]} -@r{ @: ( @: @: @:@:(...} -@r{(.. a b@: ) @: @: @:@:(a,b)} -@r{ @: , @: @: @:@:vector or rect complex} -@r{ @: ; @: @: @:@:matrix or polar complex} -@r{ @: .. @: @: @:@:interval} - -@c -@r{ @: ~ @: @: @:calc-num-prefix@:} -@r{ @: < @: @: 4 @:calc-scroll-left@:} -@r{ @: > @: @: 4 @:calc-scroll-right@:} -@r{ @: @{ @: @: 4 @:calc-scroll-down@:} -@r{ @: @} @: @: 4 @:calc-scroll-up@:} -@r{ @: ? @: @: @:calc-help@:} - -@c -@r{ a@: n @: @: 1 @:neg@:(a) @minus{}a} -@r{ @: o @: @: 4 @:calc-realign@:} -@r{ @: p @:precision @: 31 @:calc-precision@:} -@r{ @: q @: @: @:calc-quit@:} -@r{ @: w @: @: @:calc-why@:} -@r{ @: x @:command @: @:M-x calc-@:command} -@r{ a@: y @: @:1,28,49 @:calc-copy-to-buffer@:} - -@c -@r{ a@: A @: @: 1 @:abs@:(a)} -@r{ a b@: B @: @: 2 @:log@:(a,b)} -@r{ a b@: I B @: @: 2 @:alog@:(a,b) b^a} -@r{ a@: C @: @: 1 @:cos@:(a)} -@r{ a@: I C @: @: 1 @:arccos@:(a)} -@r{ a@: H C @: @: 1 @:cosh@:(a)} -@r{ a@: I H C @: @: 1 @:arccosh@:(a)} -@r{ @: D @: @: 4 @:calc-redo@:} -@r{ a@: E @: @: 1 @:exp@:(a)} -@r{ a@: H E @: @: 1 @:exp10@:(a) 10.^a} -@r{ a@: F @: @: 1,11 @:floor@:(a,d)} -@r{ a@: I F @: @: 1,11 @:ceil@:(a,d)} -@r{ a@: H F @: @: 1,11 @:ffloor@:(a,d)} -@r{ a@: I H F @: @: 1,11 @:fceil@:(a,d)} -@r{ a@: G @: @: 1 @:arg@:(a)} -@r{ @: H @:command @: 32 @:@:Hyperbolic} -@r{ @: I @:command @: 32 @:@:Inverse} -@r{ a@: J @: @: 1 @:conj@:(a)} -@r{ @: K @:command @: 32 @:@:Keep-args} -@r{ a@: L @: @: 1 @:ln@:(a)} -@r{ a@: H L @: @: 1 @:log10@:(a)} -@r{ @: M @: @: @:calc-more-recursion-depth@:} -@r{ @: I M @: @: @:calc-less-recursion-depth@:} -@r{ a@: N @: @: 5 @:evalvn@:(a)} -@r{ @: O @:command @: 32 @:@:Option} -@r{ @: P @: @: @:@:pi} -@r{ @: I P @: @: @:@:gamma} -@r{ @: H P @: @: @:@:e} -@r{ @: I H P @: @: @:@:phi} -@r{ a@: Q @: @: 1 @:sqrt@:(a)} -@r{ a@: I Q @: @: 1 @:sqr@:(a) a^2} -@r{ a@: R @: @: 1,11 @:round@:(a,d)} -@r{ a@: I R @: @: 1,11 @:trunc@:(a,d)} -@r{ a@: H R @: @: 1,11 @:fround@:(a,d)} -@r{ a@: I H R @: @: 1,11 @:ftrunc@:(a,d)} -@r{ a@: S @: @: 1 @:sin@:(a)} -@r{ a@: I S @: @: 1 @:arcsin@:(a)} -@r{ a@: H S @: @: 1 @:sinh@:(a)} -@r{ a@: I H S @: @: 1 @:arcsinh@:(a)} -@r{ a@: T @: @: 1 @:tan@:(a)} -@r{ a@: I T @: @: 1 @:arctan@:(a)} -@r{ a@: H T @: @: 1 @:tanh@:(a)} -@r{ a@: I H T @: @: 1 @:arctanh@:(a)} -@r{ @: U @: @: 4 @:calc-undo@:} -@r{ @: X @: @: 4 @:calc-call-last-kbd-macro@:} - -@c -@r{ a b@: a = @: @: 2 @:eq@:(a,b) a=b} -@r{ a b@: a # @: @: 2 @:neq@:(a,b) a!=b} -@r{ a b@: a < @: @: 2 @:lt@:(a,b) a @: @: 2 @:gt@:(a,b) a>b} -@r{ a b@: a [ @: @: 2 @:leq@:(a,b) a<=b} -@r{ a b@: a ] @: @: 2 @:geq@:(a,b) a>=b} -@r{ a b@: a @{ @: @: 2 @:in@:(a,b)} -@r{ a b@: a & @: @: 2,45 @:land@:(a,b) a&&b} -@r{ a b@: a | @: @: 2,45 @:lor@:(a,b) a||b} -@r{ a@: a ! @: @: 1,45 @:lnot@:(a) !a} -@r{ a b c@: a : @: @: 45 @:if@:(a,b,c) a?b:c} -@r{ a@: a . @: @: 1 @:rmeq@:(a)} -@r{ a@: a " @: @: 7,8 @:calc-expand-formula@:} - -@c -@r{ a@: a + @:i, l, h @: 6,38 @:sum@:(a,i,l,h)} -@r{ a@: a - @:i, l, h @: 6,38 @:asum@:(a,i,l,h)} -@r{ a@: a * @:i, l, h @: 6,38 @:prod@:(a,i,l,h)} -@r{ a b@: a _ @: @: 2 @:subscr@:(a,b) a_b} - -@c -@r{ a b@: a \ @: @: 2 @:pdiv@:(a,b)} -@r{ a b@: a % @: @: 2 @:prem@:(a,b)} -@r{ a b@: a / @: @: 2 @:pdivrem@:(a,b) [q,r]} -@r{ a b@: H a / @: @: 2 @:pdivide@:(a,b) q+r/b} - -@c -@r{ a@: a a @: @: 1 @:apart@:(a)} -@r{ a@: a b @:old, new @: 38 @:subst@:(a,old,new)} -@r{ a@: a c @:v @: 38 @:collect@:(a,v)} -@r{ a@: a d @:v @: 4,38 @:deriv@:(a,v)} -@r{ a@: H a d @:v @: 4,38 @:tderiv@:(a,v)} -@r{ a@: a e @: @: @:esimplify@:(a)} -@r{ a@: a f @: @: 1 @:factor@:(a)} -@r{ a@: H a f @: @: 1 @:factors@:(a)} -@r{ a b@: a g @: @: 2 @:pgcd@:(a,b)} -@r{ a@: a i @:v @: 38 @:integ@:(a,v)} -@r{ a@: a m @:pats @: 38 @:match@:(a,pats)} -@r{ a@: I a m @:pats @: 38 @:matchnot@:(a,pats)} -@r{ data x@: a p @: @: 28 @:polint@:(data,x)} -@r{ data x@: H a p @: @: 28 @:ratint@:(data,x)} -@r{ a@: a n @: @: 1 @:nrat@:(a)} -@r{ a@: a r @:rules @:4,8,38 @:rewrite@:(a,rules,n)} -@r{ a@: a s @: @: @:simplify@:(a)} -@r{ a@: a t @:v, n @: 31,39 @:taylor@:(a,v,n)} -@r{ a@: a v @: @: 7,8 @:calc-alg-evaluate@:} -@r{ a@: a x @: @: 4,8 @:expand@:(a)} - -@c -@r{ data@: a F @:model, vars @: 48 @:fit@:(m,iv,pv,data)} -@r{ data@: I a F @:model, vars @: 48 @:xfit@:(m,iv,pv,data)} -@r{ data@: H a F @:model, vars @: 48 @:efit@:(m,iv,pv,data)} -@r{ a@: a I @:v, l, h @: 38 @:ninteg@:(a,v,l,h)} -@r{ a b@: a M @:op @: 22 @:mapeq@:(op,a,b)} -@r{ a b@: I a M @:op @: 22 @:mapeqr@:(op,a,b)} -@r{ a b@: H a M @:op @: 22 @:mapeqp@:(op,a,b)} -@r{ a g@: a N @:v @: 38 @:minimize@:(a,v,g)} -@r{ a g@: H a N @:v @: 38 @:wminimize@:(a,v,g)} -@r{ a@: a P @:v @: 38 @:roots@:(a,v)} -@r{ a g@: a R @:v @: 38 @:root@:(a,v,g)} -@r{ a g@: H a R @:v @: 38 @:wroot@:(a,v,g)} -@r{ a@: a S @:v @: 38 @:solve@:(a,v)} -@r{ a@: I a S @:v @: 38 @:finv@:(a,v)} -@r{ a@: H a S @:v @: 38 @:fsolve@:(a,v)} -@r{ a@: I H a S @:v @: 38 @:ffinv@:(a,v)} -@r{ a@: a T @:i, l, h @: 6,38 @:table@:(a,i,l,h)} -@r{ a g@: a X @:v @: 38 @:maximize@:(a,v,g)} -@r{ a g@: H a X @:v @: 38 @:wmaximize@:(a,v,g)} - -@c -@r{ a b@: b a @: @: 9 @:and@:(a,b,w)} -@r{ a@: b c @: @: 9 @:clip@:(a,w)} -@r{ a b@: b d @: @: 9 @:diff@:(a,b,w)} -@r{ a@: b l @: @: 10 @:lsh@:(a,n,w)} -@r{ a n@: H b l @: @: 9 @:lsh@:(a,n,w)} -@r{ a@: b n @: @: 9 @:not@:(a,w)} -@r{ a b@: b o @: @: 9 @:or@:(a,b,w)} -@r{ v@: b p @: @: 1 @:vpack@:(v)} -@r{ a@: b r @: @: 10 @:rsh@:(a,n,w)} -@r{ a n@: H b r @: @: 9 @:rsh@:(a,n,w)} -@r{ a@: b t @: @: 10 @:rot@:(a,n,w)} -@r{ a n@: H b t @: @: 9 @:rot@:(a,n,w)} -@r{ a@: b u @: @: 1 @:vunpack@:(a)} -@r{ @: b w @:w @: 9,50 @:calc-word-size@:} -@r{ a b@: b x @: @: 9 @:xor@:(a,b,w)} - -@c -@r{c s l p@: b D @: @: @:ddb@:(c,s,l,p)} -@r{ r n p@: b F @: @: @:fv@:(r,n,p)} -@r{ r n p@: I b F @: @: @:fvb@:(r,n,p)} -@r{ r n p@: H b F @: @: @:fvl@:(r,n,p)} -@r{ v@: b I @: @: 19 @:irr@:(v)} -@r{ v@: I b I @: @: 19 @:irrb@:(v)} -@r{ a@: b L @: @: 10 @:ash@:(a,n,w)} -@r{ a n@: H b L @: @: 9 @:ash@:(a,n,w)} -@r{ r n a@: b M @: @: @:pmt@:(r,n,a)} -@r{ r n a@: I b M @: @: @:pmtb@:(r,n,a)} -@r{ r n a@: H b M @: @: @:pmtl@:(r,n,a)} -@r{ r v@: b N @: @: 19 @:npv@:(r,v)} -@r{ r v@: I b N @: @: 19 @:npvb@:(r,v)} -@r{ r n p@: b P @: @: @:pv@:(r,n,p)} -@r{ r n p@: I b P @: @: @:pvb@:(r,n,p)} -@r{ r n p@: H b P @: @: @:pvl@:(r,n,p)} -@r{ a@: b R @: @: 10 @:rash@:(a,n,w)} -@r{ a n@: H b R @: @: 9 @:rash@:(a,n,w)} -@r{ c s l@: b S @: @: @:sln@:(c,s,l)} -@r{ n p a@: b T @: @: @:rate@:(n,p,a)} -@r{ n p a@: I b T @: @: @:rateb@:(n,p,a)} -@r{ n p a@: H b T @: @: @:ratel@:(n,p,a)} -@r{c s l p@: b Y @: @: @:syd@:(c,s,l,p)} - -@r{ r p a@: b # @: @: @:nper@:(r,p,a)} -@r{ r p a@: I b # @: @: @:nperb@:(r,p,a)} -@r{ r p a@: H b # @: @: @:nperl@:(r,p,a)} -@r{ a b@: b % @: @: @:relch@:(a,b)} - -@c -@r{ a@: c c @: @: 5 @:pclean@:(a,p)} -@r{ a@: c 0-9 @: @: @:pclean@:(a,p)} -@r{ a@: H c c @: @: 5 @:clean@:(a,p)} -@r{ a@: H c 0-9 @: @: @:clean@:(a,p)} -@r{ a@: c d @: @: 1 @:deg@:(a)} -@r{ a@: c f @: @: 1 @:pfloat@:(a)} -@r{ a@: H c f @: @: 1 @:float@:(a)} -@r{ a@: c h @: @: 1 @:hms@:(a)} -@r{ a@: c p @: @: @:polar@:(a)} -@r{ a@: I c p @: @: @:rect@:(a)} -@r{ a@: c r @: @: 1 @:rad@:(a)} - -@c -@r{ a@: c F @: @: 5 @:pfrac@:(a,p)} -@r{ a@: H c F @: @: 5 @:frac@:(a,p)} - -@c -@r{ a@: c % @: @: @:percent@:(a*100)} - -@c -@r{ @: d . @:char @: 50 @:calc-point-char@:} -@r{ @: d , @:char @: 50 @:calc-group-char@:} -@r{ @: d < @: @: 13,50 @:calc-left-justify@:} -@r{ @: d = @: @: 13,50 @:calc-center-justify@:} -@r{ @: d > @: @: 13,50 @:calc-right-justify@:} -@r{ @: d @{ @:label @: 50 @:calc-left-label@:} -@r{ @: d @} @:label @: 50 @:calc-right-label@:} -@r{ @: d [ @: @: 4 @:calc-truncate-up@:} -@r{ @: d ] @: @: 4 @:calc-truncate-down@:} -@r{ @: d " @: @: 12,50 @:calc-display-strings@:} -@r{ @: d @summarykey{SPC} @: @: @:calc-refresh@:} -@r{ @: d @summarykey{RET} @: @: 1 @:calc-refresh-top@:} - -@c -@r{ @: d 0 @: @: 50 @:calc-decimal-radix@:} -@r{ @: d 2 @: @: 50 @:calc-binary-radix@:} -@r{ @: d 6 @: @: 50 @:calc-hex-radix@:} -@r{ @: d 8 @: @: 50 @:calc-octal-radix@:} - -@c -@r{ @: d b @: @:12,13,50 @:calc-line-breaking@:} -@r{ @: d c @: @: 50 @:calc-complex-notation@:} -@r{ @: d d @:format @: 50 @:calc-date-notation@:} -@r{ @: d e @: @: 5,50 @:calc-eng-notation@:} -@r{ @: d f @:num @: 31,50 @:calc-fix-notation@:} -@r{ @: d g @: @:12,13,50 @:calc-group-digits@:} -@r{ @: d h @:format @: 50 @:calc-hms-notation@:} -@r{ @: d i @: @: 50 @:calc-i-notation@:} -@r{ @: d j @: @: 50 @:calc-j-notation@:} -@r{ @: d l @: @: 12,50 @:calc-line-numbering@:} -@r{ @: d n @: @: 5,50 @:calc-normal-notation@:} -@r{ @: d o @:format @: 50 @:calc-over-notation@:} -@r{ @: d p @: @: 12,50 @:calc-show-plain@:} -@r{ @: d r @:radix @: 31,50 @:calc-radix@:} -@r{ @: d s @: @: 5,50 @:calc-sci-notation@:} -@r{ @: d t @: @: 27 @:calc-truncate-stack@:} -@r{ @: d w @: @: 12,13 @:calc-auto-why@:} -@r{ @: d z @: @: 12,50 @:calc-leading-zeros@:} - -@c -@r{ @: d B @: @: 50 @:calc-big-language@:} -@r{ @: d C @: @: 50 @:calc-c-language@:} -@r{ @: d E @: @: 50 @:calc-eqn-language@:} -@r{ @: d F @: @: 50 @:calc-fortran-language@:} -@r{ @: d M @: @: 50 @:calc-mathematica-language@:} -@r{ @: d N @: @: 50 @:calc-normal-language@:} -@r{ @: d O @: @: 50 @:calc-flat-language@:} -@r{ @: d P @: @: 50 @:calc-pascal-language@:} -@r{ @: d T @: @: 50 @:calc-tex-language@:} -@r{ @: d L @: @: 50 @:calc-latex-language@:} -@r{ @: d U @: @: 50 @:calc-unformatted-language@:} -@r{ @: d W @: @: 50 @:calc-maple-language@:} - -@c -@r{ a@: f [ @: @: 4 @:decr@:(a,n)} -@r{ a@: f ] @: @: 4 @:incr@:(a,n)} - -@c -@r{ a b@: f b @: @: 2 @:beta@:(a,b)} -@r{ a@: f e @: @: 1 @:erf@:(a)} -@r{ a@: I f e @: @: 1 @:erfc@:(a)} -@r{ a@: f g @: @: 1 @:gamma@:(a)} -@r{ a b@: f h @: @: 2 @:hypot@:(a,b)} -@r{ a@: f i @: @: 1 @:im@:(a)} -@r{ n a@: f j @: @: 2 @:besJ@:(n,a)} -@r{ a b@: f n @: @: 2 @:min@:(a,b)} -@r{ a@: f r @: @: 1 @:re@:(a)} -@r{ a@: f s @: @: 1 @:sign@:(a)} -@r{ a b@: f x @: @: 2 @:max@:(a,b)} -@r{ n a@: f y @: @: 2 @:besY@:(n,a)} - -@c -@r{ a@: f A @: @: 1 @:abssqr@:(a)} -@r{ x a b@: f B @: @: @:betaI@:(x,a,b)} -@r{ x a b@: H f B @: @: @:betaB@:(x,a,b)} -@r{ a@: f E @: @: 1 @:expm1@:(a)} -@r{ a x@: f G @: @: 2 @:gammaP@:(a,x)} -@r{ a x@: I f G @: @: 2 @:gammaQ@:(a,x)} -@r{ a x@: H f G @: @: 2 @:gammag@:(a,x)} -@r{ a x@: I H f G @: @: 2 @:gammaG@:(a,x)} -@r{ a b@: f I @: @: 2 @:ilog@:(a,b)} -@r{ a b@: I f I @: @: 2 @:alog@:(a,b) b^a} -@r{ a@: f L @: @: 1 @:lnp1@:(a)} -@r{ a@: f M @: @: 1 @:mant@:(a)} -@r{ a@: f Q @: @: 1 @:isqrt@:(a)} -@r{ a@: I f Q @: @: 1 @:sqr@:(a) a^2} -@r{ a n@: f S @: @: 2 @:scf@:(a,n)} -@r{ y x@: f T @: @: @:arctan2@:(y,x)} -@r{ a@: f X @: @: 1 @:xpon@:(a)} - -@c -@r{ x y@: g a @: @: 28,40 @:calc-graph-add@:} -@r{ @: g b @: @: 12 @:calc-graph-border@:} -@r{ @: g c @: @: @:calc-graph-clear@:} -@r{ @: g d @: @: 41 @:calc-graph-delete@:} -@r{ x y@: g f @: @: 28,40 @:calc-graph-fast@:} -@r{ @: g g @: @: 12 @:calc-graph-grid@:} -@r{ @: g h @:title @: @:calc-graph-header@:} -@r{ @: g j @: @: 4 @:calc-graph-juggle@:} -@r{ @: g k @: @: 12 @:calc-graph-key@:} -@r{ @: g l @: @: 12 @:calc-graph-log-x@:} -@r{ @: g n @:name @: @:calc-graph-name@:} -@r{ @: g p @: @: 42 @:calc-graph-plot@:} -@r{ @: g q @: @: @:calc-graph-quit@:} -@r{ @: g r @:range @: @:calc-graph-range-x@:} -@r{ @: g s @: @: 12,13 @:calc-graph-line-style@:} -@r{ @: g t @:title @: @:calc-graph-title-x@:} -@r{ @: g v @: @: @:calc-graph-view-commands@:} -@r{ @: g x @:display @: @:calc-graph-display@:} -@r{ @: g z @: @: 12 @:calc-graph-zero-x@:} - -@c -@r{ x y z@: g A @: @: 28,40 @:calc-graph-add-3d@:} -@r{ @: g C @:command @: @:calc-graph-command@:} -@r{ @: g D @:device @: 43,44 @:calc-graph-device@:} -@r{ x y z@: g F @: @: 28,40 @:calc-graph-fast-3d@:} -@r{ @: g H @: @: 12 @:calc-graph-hide@:} -@r{ @: g K @: @: @:calc-graph-kill@:} -@r{ @: g L @: @: 12 @:calc-graph-log-y@:} -@r{ @: g N @:number @: 43,51 @:calc-graph-num-points@:} -@r{ @: g O @:filename @: 43,44 @:calc-graph-output@:} -@r{ @: g P @: @: 42 @:calc-graph-print@:} -@r{ @: g R @:range @: @:calc-graph-range-y@:} -@r{ @: g S @: @: 12,13 @:calc-graph-point-style@:} -@r{ @: g T @:title @: @:calc-graph-title-y@:} -@r{ @: g V @: @: @:calc-graph-view-trail@:} -@r{ @: g X @:format @: @:calc-graph-geometry@:} -@r{ @: g Z @: @: 12 @:calc-graph-zero-y@:} - -@c -@r{ @: g C-l @: @: 12 @:calc-graph-log-z@:} -@r{ @: g C-r @:range @: @:calc-graph-range-z@:} -@r{ @: g C-t @:title @: @:calc-graph-title-z@:} - -@c -@r{ @: h b @: @: @:calc-describe-bindings@:} -@r{ @: h c @:key @: @:calc-describe-key-briefly@:} -@r{ @: h f @:function @: @:calc-describe-function@:} -@r{ @: h h @: @: @:calc-full-help@:} -@r{ @: h i @: @: @:calc-info@:} -@r{ @: h k @:key @: @:calc-describe-key@:} -@r{ @: h n @: @: @:calc-view-news@:} -@r{ @: h s @: @: @:calc-info-summary@:} -@r{ @: h t @: @: @:calc-tutorial@:} -@r{ @: h v @:var @: @:calc-describe-variable@:} - -@c -@r{ @: j 1-9 @: @: @:calc-select-part@:} -@r{ @: j @summarykey{RET} @: @: 27 @:calc-copy-selection@:} -@r{ @: j @summarykey{DEL} @: @: 27 @:calc-del-selection@:} -@r{ @: j ' @:formula @: 27 @:calc-enter-selection@:} -@r{ @: j ` @:editing @: 27,30 @:calc-edit-selection@:} -@r{ @: j " @: @: 7,27 @:calc-sel-expand-formula@:} - -@c -@r{ @: j + @:formula @: 27 @:calc-sel-add-both-sides@:} -@r{ @: j - @:formula @: 27 @:calc-sel-sub-both-sides@:} -@r{ @: j * @:formula @: 27 @:calc-sel-mul-both-sides@:} -@r{ @: j / @:formula @: 27 @:calc-sel-div-both-sides@:} -@r{ @: j & @: @: 27 @:calc-sel-invert@:} - -@c -@r{ @: j a @: @: 27 @:calc-select-additional@:} -@r{ @: j b @: @: 12 @:calc-break-selections@:} -@r{ @: j c @: @: @:calc-clear-selections@:} -@r{ @: j d @: @: 12,50 @:calc-show-selections@:} -@r{ @: j e @: @: 12 @:calc-enable-selections@:} -@r{ @: j l @: @: 4,27 @:calc-select-less@:} -@r{ @: j m @: @: 4,27 @:calc-select-more@:} -@r{ @: j n @: @: 4 @:calc-select-next@:} -@r{ @: j o @: @: 4,27 @:calc-select-once@:} -@r{ @: j p @: @: 4 @:calc-select-previous@:} -@r{ @: j r @:rules @:4,8,27 @:calc-rewrite-selection@:} -@r{ @: j s @: @: 4,27 @:calc-select-here@:} -@r{ @: j u @: @: 27 @:calc-unselect@:} -@r{ @: j v @: @: 7,27 @:calc-sel-evaluate@:} - -@c -@r{ @: j C @: @: 27 @:calc-sel-commute@:} -@r{ @: j D @: @: 4,27 @:calc-sel-distribute@:} -@r{ @: j E @: @: 27 @:calc-sel-jump-equals@:} -@r{ @: j I @: @: 27 @:calc-sel-isolate@:} -@r{ @: H j I @: @: 27 @:calc-sel-isolate@: (full)} -@r{ @: j L @: @: 4,27 @:calc-commute-left@:} -@r{ @: j M @: @: 27 @:calc-sel-merge@:} -@r{ @: j N @: @: 27 @:calc-sel-negate@:} -@r{ @: j O @: @: 4,27 @:calc-select-once-maybe@:} -@r{ @: j R @: @: 4,27 @:calc-commute-right@:} -@r{ @: j S @: @: 4,27 @:calc-select-here-maybe@:} -@r{ @: j U @: @: 27 @:calc-sel-unpack@:} - -@c -@r{ @: k a @: @: @:calc-random-again@:} -@r{ n@: k b @: @: 1 @:bern@:(n)} -@r{ n x@: H k b @: @: 2 @:bern@:(n,x)} -@r{ n m@: k c @: @: 2 @:choose@:(n,m)} -@r{ n m@: H k c @: @: 2 @:perm@:(n,m)} -@r{ n@: k d @: @: 1 @:dfact@:(n) n!!} -@r{ n@: k e @: @: 1 @:euler@:(n)} -@r{ n x@: H k e @: @: 2 @:euler@:(n,x)} -@r{ n@: k f @: @: 4 @:prfac@:(n)} -@r{ n m@: k g @: @: 2 @:gcd@:(n,m)} -@r{ m n@: k h @: @: 14 @:shuffle@:(n,m)} -@r{ n m@: k l @: @: 2 @:lcm@:(n,m)} -@r{ n@: k m @: @: 1 @:moebius@:(n)} -@r{ n@: k n @: @: 4 @:nextprime@:(n)} -@r{ n@: I k n @: @: 4 @:prevprime@:(n)} -@r{ n@: k p @: @: 4,28 @:calc-prime-test@:} -@r{ m@: k r @: @: 14 @:random@:(m)} -@r{ n m@: k s @: @: 2 @:stir1@:(n,m)} -@r{ n m@: H k s @: @: 2 @:stir2@:(n,m)} -@r{ n@: k t @: @: 1 @:totient@:(n)} - -@c -@r{ n p x@: k B @: @: @:utpb@:(x,n,p)} -@r{ n p x@: I k B @: @: @:ltpb@:(x,n,p)} -@r{ v x@: k C @: @: @:utpc@:(x,v)} -@r{ v x@: I k C @: @: @:ltpc@:(x,v)} -@r{ n m@: k E @: @: @:egcd@:(n,m)} -@r{v1 v2 x@: k F @: @: @:utpf@:(x,v1,v2)} -@r{v1 v2 x@: I k F @: @: @:ltpf@:(x,v1,v2)} -@r{ m s x@: k N @: @: @:utpn@:(x,m,s)} -@r{ m s x@: I k N @: @: @:ltpn@:(x,m,s)} -@r{ m x@: k P @: @: @:utpp@:(x,m)} -@r{ m x@: I k P @: @: @:ltpp@:(x,m)} -@r{ v x@: k T @: @: @:utpt@:(x,v)} -@r{ v x@: I k T @: @: @:ltpt@:(x,v)} - -@c -@r{ a b@: l + @: @: @:lupadd@:(a,b)} -@r{ a b@: H l + @: @: @:lufadd@:(a,b)} -@r{ a b@: l - @: @: @:lupsub@:(a,b)} -@r{ a b@: H l - @: @: @:lufsub@:(a,b)} -@r{ a b@: l * @: @: @:lupmul@:(a,b)} -@r{ a b@: H l * @: @: @:lufmul@:(a,b)} -@r{ a b@: l / @: @: @:lupdiv@:(a,b)} -@r{ a b@: H l / @: @: @:lufdiv@:(a,b)} -@r{ a@: l d @: @: @:dbpower@:(a)} -@r{ a b@: O l d @: @: @:dbpower@:(a,b)} -@r{ a@: H l d @: @: @:dbfield@:(a)} -@r{ a b@: O H l d @: @: @:dbfield@:(a,b)} -@r{ a@: l n @: @: @:nppower@:(a)} -@r{ a b@: O l n @: @: @:nppower@:(a,b)} -@r{ a@: H l n @: @: @:npfield@:(a)} -@r{ a b@: O H l n @: @: @:npfield@:(a,b)} -@r{ a@: l q @: @: @:lupquant@:(a)} -@r{ a b@: O l q @: @: @:lupquant@:(a,b)} -@r{ a@: H l q @: @: @:lufquant@:(a)} -@r{ a b@: O H l q @: @: @:lufquant@:(a,b)} -@r{ a@: l s @: @: @:spn@:(a)} -@r{ a@: l m @: @: @:midi@:(a)} -@r{ a@: l f @: @: @:freq@:(a)} - -@c -@r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:} -@r{ @: m d @: @: @:calc-degrees-mode@:} -@r{ @: m e @: @: @:calc-embedded-preserve-modes@:} -@r{ @: m f @: @: 12 @:calc-frac-mode@:} -@r{ @: m g @: @: 52 @:calc-get-modes@:} -@r{ @: m h @: @: @:calc-hms-mode@:} -@r{ @: m i @: @: 12,13 @:calc-infinite-mode@:} -@r{ @: m m @: @: @:calc-save-modes@:} -@r{ @: m p @: @: 12 @:calc-polar-mode@:} -@r{ @: m r @: @: @:calc-radians-mode@:} -@r{ @: m s @: @: 12 @:calc-symbolic-mode@:} -@r{ @: m t @: @: 12 @:calc-total-algebraic-mode@:} -@r{ @: m v @: @: 12,13 @:calc-matrix-mode@:} -@r{ @: m w @: @: 13 @:calc-working@:} -@r{ @: m x @: @: @:calc-always-load-extensions@:} - -@c -@r{ @: m A @: @: 12 @:calc-alg-simplify-mode@:} -@r{ @: m B @: @: 12 @:calc-bin-simplify-mode@:} -@r{ @: m C @: @: 12 @:calc-auto-recompute@:} -@r{ @: m D @: @: @:calc-default-simplify-mode@:} -@r{ @: m E @: @: 12 @:calc-ext-simplify-mode@:} -@r{ @: m F @:filename @: 13 @:calc-settings-file-name@:} -@r{ @: m N @: @: 12 @:calc-num-simplify-mode@:} -@r{ @: m O @: @: 12 @:calc-no-simplify-mode@:} -@r{ @: m R @: @: 12,13 @:calc-mode-record-mode@:} -@r{ @: m S @: @: 12 @:calc-shift-prefix@:} -@r{ @: m U @: @: 12 @:calc-units-simplify-mode@:} - -@c -@r{ @: r s @:register @: 27 @:calc-copy-to-register@:} -@r{ @: r i @:register @: @:calc-insert-register@:} - -@c -@r{ @: s c @:var1, var2 @: 29 @:calc-copy-variable@:} -@r{ @: s d @:var, decl @: @:calc-declare-variable@:} -@r{ @: s e @:var, editing @: 29,30 @:calc-edit-variable@:} -@r{ @: s i @:buffer @: @:calc-insert-variables@:} -@r{ @: s k @:const, var @: 29 @:calc-copy-special-constant@:} -@r{ a b@: s l @:var @: 29 @:@:a (letting var=b)} -@r{ a ...@: s m @:op, var @: 22,29 @:calc-store-map@:} -@r{ @: s n @:var @: 29,47 @:calc-store-neg@: (v/-1)} -@r{ @: s p @:var @: 29 @:calc-permanent-variable@:} -@r{ @: s r @:var @: 29 @:@:v (recalled value)} -@r{ @: r 0-9 @: @: @:calc-recall-quick@:} -@r{ a@: s s @:var @: 28,29 @:calc-store@:} -@r{ a@: s 0-9 @: @: @:calc-store-quick@:} -@r{ a@: s t @:var @: 29 @:calc-store-into@:} -@r{ a@: t 0-9 @: @: @:calc-store-into-quick@:} -@r{ @: s u @:var @: 29 @:calc-unstore@:} -@r{ a@: s x @:var @: 29 @:calc-store-exchange@:} - -@c -@r{ @: s A @:editing @: 30 @:calc-edit-AlgSimpRules@:} -@r{ @: s D @:editing @: 30 @:calc-edit-Decls@:} -@r{ @: s E @:editing @: 30 @:calc-edit-EvalRules@:} -@r{ @: s F @:editing @: 30 @:calc-edit-FitRules@:} -@r{ @: s G @:editing @: 30 @:calc-edit-GenCount@:} -@r{ @: s H @:editing @: 30 @:calc-edit-Holidays@:} -@r{ @: s I @:editing @: 30 @:calc-edit-IntegLimit@:} -@r{ @: s L @:editing @: 30 @:calc-edit-LineStyles@:} -@r{ @: s P @:editing @: 30 @:calc-edit-PointStyles@:} -@r{ @: s R @:editing @: 30 @:calc-edit-PlotRejects@:} -@r{ @: s T @:editing @: 30 @:calc-edit-TimeZone@:} -@r{ @: s U @:editing @: 30 @:calc-edit-Units@:} -@r{ @: s X @:editing @: 30 @:calc-edit-ExtSimpRules@:} - -@c -@r{ a@: s + @:var @: 29,47 @:calc-store-plus@: (v+a)} -@r{ a@: s - @:var @: 29,47 @:calc-store-minus@: (v-a)} -@r{ a@: s * @:var @: 29,47 @:calc-store-times@: (v*a)} -@r{ a@: s / @:var @: 29,47 @:calc-store-div@: (v/a)} -@r{ a@: s ^ @:var @: 29,47 @:calc-store-power@: (v^a)} -@r{ a@: s | @:var @: 29,47 @:calc-store-concat@: (v|a)} -@r{ @: s & @:var @: 29,47 @:calc-store-inv@: (v^-1)} -@r{ @: s [ @:var @: 29,47 @:calc-store-decr@: (v-1)} -@r{ @: s ] @:var @: 29,47 @:calc-store-incr@: (v-(-1))} -@r{ a b@: s : @: @: 2 @:assign@:(a,b) a @tfn{:=} b} -@r{ a@: s = @: @: 1 @:evalto@:(a,b) a @tfn{=>}} - -@c -@r{ @: t [ @: @: 4 @:calc-trail-first@:} -@r{ @: t ] @: @: 4 @:calc-trail-last@:} -@r{ @: t < @: @: 4 @:calc-trail-scroll-left@:} -@r{ @: t > @: @: 4 @:calc-trail-scroll-right@:} -@r{ @: t . @: @: 12 @:calc-full-trail-vectors@:} - -@c -@r{ @: t b @: @: 4 @:calc-trail-backward@:} -@r{ @: t d @: @: 12,50 @:calc-trail-display@:} -@r{ @: t f @: @: 4 @:calc-trail-forward@:} -@r{ @: t h @: @: @:calc-trail-here@:} -@r{ @: t i @: @: @:calc-trail-in@:} -@r{ @: t k @: @: 4 @:calc-trail-kill@:} -@r{ @: t m @:string @: @:calc-trail-marker@:} -@r{ @: t n @: @: 4 @:calc-trail-next@:} -@r{ @: t o @: @: @:calc-trail-out@:} -@r{ @: t p @: @: 4 @:calc-trail-previous@:} -@r{ @: t r @:string @: @:calc-trail-isearch-backward@:} -@r{ @: t s @:string @: @:calc-trail-isearch-forward@:} -@r{ @: t y @: @: 4 @:calc-trail-yank@:} - -@c -@r{ d@: t C @:oz, nz @: @:tzconv@:(d,oz,nz)} -@r{d oz nz@: t C @:$ @: @:tzconv@:(d,oz,nz)} -@r{ d@: t D @: @: 15 @:date@:(d)} -@r{ d@: t I @: @: 4 @:incmonth@:(d,n)} -@r{ d@: t J @: @: 16 @:julian@:(d,z)} -@r{ d@: t M @: @: 17 @:newmonth@:(d,n)} -@r{ @: t N @: @: 16 @:now@:(z)} -@r{ d@: t P @:1 @: 31 @:year@:(d)} -@r{ d@: t P @:2 @: 31 @:month@:(d)} -@r{ d@: t P @:3 @: 31 @:day@:(d)} -@r{ d@: t P @:4 @: 31 @:hour@:(d)} -@r{ d@: t P @:5 @: 31 @:minute@:(d)} -@r{ d@: t P @:6 @: 31 @:second@:(d)} -@r{ d@: t P @:7 @: 31 @:weekday@:(d)} -@r{ d@: t P @:8 @: 31 @:yearday@:(d)} -@r{ d@: t P @:9 @: 31 @:time@:(d)} -@r{ d@: t U @: @: 16 @:unixtime@:(d,z)} -@r{ d@: t W @: @: 17 @:newweek@:(d,w)} -@r{ d@: t Y @: @: 17 @:newyear@:(d,n)} - -@c -@r{ a b@: t + @: @: 2 @:badd@:(a,b)} -@r{ a b@: t - @: @: 2 @:bsub@:(a,b)} - -@c -@r{ @: u a @: @: 12 @:calc-autorange-units@:} -@r{ a@: u b @: @: @:calc-base-units@:} -@r{ a@: u c @:units @: 18 @:calc-convert-units@:} -@r{ defn@: u d @:unit, descr @: @:calc-define-unit@:} -@r{ @: u e @: @: @:calc-explain-units@:} -@r{ @: u g @:unit @: @:calc-get-unit-definition@:} -@r{ @: u p @: @: @:calc-permanent-units@:} -@r{ a@: u r @: @: @:calc-remove-units@:} -@r{ a@: u s @: @: @:usimplify@:(a)} -@r{ a@: u t @:units @: 18 @:calc-convert-temperature@:} -@r{ @: u u @:unit @: @:calc-undefine-unit@:} -@r{ @: u v @: @: @:calc-enter-units-table@:} -@r{ a@: u x @: @: @:calc-extract-units@:} -@r{ a@: u 0-9 @: @: @:calc-quick-units@:} - -@c -@r{ v1 v2@: u C @: @: 20 @:vcov@:(v1,v2)} -@r{ v1 v2@: I u C @: @: 20 @:vpcov@:(v1,v2)} -@r{ v1 v2@: H u C @: @: 20 @:vcorr@:(v1,v2)} -@r{ v@: u G @: @: 19 @:vgmean@:(v)} -@r{ a b@: H u G @: @: 2 @:agmean@:(a,b)} -@r{ v@: u M @: @: 19 @:vmean@:(v)} -@r{ v@: I u M @: @: 19 @:vmeane@:(v)} -@r{ v@: H u M @: @: 19 @:vmedian@:(v)} -@r{ v@: I H u M @: @: 19 @:vhmean@:(v)} -@r{ v@: u N @: @: 19 @:vmin@:(v)} -@r{ v@: u S @: @: 19 @:vsdev@:(v)} -@r{ v@: I u S @: @: 19 @:vpsdev@:(v)} -@r{ v@: H u S @: @: 19 @:vvar@:(v)} -@r{ v@: I H u S @: @: 19 @:vpvar@:(v)} -@r{ @: u V @: @: @:calc-view-units-table@:} -@r{ v@: u X @: @: 19 @:vmax@:(v)} - -@c -@r{ v@: u + @: @: 19 @:vsum@:(v)} -@r{ v@: u * @: @: 19 @:vprod@:(v)} -@r{ v@: u # @: @: 19 @:vcount@:(v)} - -@c -@r{ @: V ( @: @: 50 @:calc-vector-parens@:} -@r{ @: V @{ @: @: 50 @:calc-vector-braces@:} -@r{ @: V [ @: @: 50 @:calc-vector-brackets@:} -@r{ @: V ] @:ROCP @: 50 @:calc-matrix-brackets@:} -@r{ @: V , @: @: 50 @:calc-vector-commas@:} -@r{ @: V < @: @: 50 @:calc-matrix-left-justify@:} -@r{ @: V = @: @: 50 @:calc-matrix-center-justify@:} -@r{ @: V > @: @: 50 @:calc-matrix-right-justify@:} -@r{ @: V / @: @: 12,50 @:calc-break-vectors@:} -@r{ @: V . @: @: 12,50 @:calc-full-vectors@:} - -@c -@r{ s t@: V ^ @: @: 2 @:vint@:(s,t)} -@r{ s t@: V - @: @: 2 @:vdiff@:(s,t)} -@r{ s@: V ~ @: @: 1 @:vcompl@:(s)} -@r{ s@: V # @: @: 1 @:vcard@:(s)} -@r{ s@: V : @: @: 1 @:vspan@:(s)} -@r{ s@: V + @: @: 1 @:rdup@:(s)} - -@c -@r{ m@: V & @: @: 1 @:inv@:(m) 1/m} - -@c -@r{ v@: v a @:n @: @:arrange@:(v,n)} -@r{ a@: v b @:n @: @:cvec@:(a,n)} -@r{ v@: v c @:n >0 @: 21,31 @:mcol@:(v,n)} -@r{ v@: v c @:n <0 @: 31 @:mrcol@:(v,-n)} -@r{ m@: v c @:0 @: 31 @:getdiag@:(m)} -@r{ v@: v d @: @: 25 @:diag@:(v,n)} -@r{ v m@: v e @: @: 2 @:vexp@:(v,m)} -@r{ v m f@: H v e @: @: 2 @:vexp@:(v,m,f)} -@r{ v a@: v f @: @: 26 @:find@:(v,a,n)} -@r{ v@: v h @: @: 1 @:head@:(v)} -@r{ v@: I v h @: @: 1 @:tail@:(v)} -@r{ v@: H v h @: @: 1 @:rhead@:(v)} -@r{ v@: I H v h @: @: 1 @:rtail@:(v)} -@r{ @: v i @:n @: 31 @:idn@:(1,n)} -@r{ @: v i @:0 @: 31 @:idn@:(1)} -@r{ h t@: v k @: @: 2 @:cons@:(h,t)} -@r{ h t@: H v k @: @: 2 @:rcons@:(h,t)} -@r{ v@: v l @: @: 1 @:vlen@:(v)} -@r{ v@: H v l @: @: 1 @:mdims@:(v)} -@r{ v m@: v m @: @: 2 @:vmask@:(v,m)} -@r{ v@: v n @: @: 1 @:rnorm@:(v)} -@r{ a b c@: v p @: @: 24 @:calc-pack@:} -@r{ v@: v r @:n >0 @: 21,31 @:mrow@:(v,n)} -@r{ v@: v r @:n <0 @: 31 @:mrrow@:(v,-n)} -@r{ m@: v r @:0 @: 31 @:getdiag@:(m)} -@r{ v i j@: v s @: @: @:subvec@:(v,i,j)} -@r{ v i j@: I v s @: @: @:rsubvec@:(v,i,j)} -@r{ m@: v t @: @: 1 @:trn@:(m)} -@r{ v@: v u @: @: 24 @:calc-unpack@:} -@r{ v@: v v @: @: 1 @:rev@:(v)} -@r{ @: v x @:n @: 31 @:index@:(n)} -@r{ n s i@: C-u v x @: @: @:index@:(n,s,i)} - -@c -@r{ v@: V A @:op @: 22 @:apply@:(op,v)} -@r{ v1 v2@: V C @: @: 2 @:cross@:(v1,v2)} -@r{ m@: V D @: @: 1 @:det@:(m)} -@r{ s@: V E @: @: 1 @:venum@:(s)} -@r{ s@: V F @: @: 1 @:vfloor@:(s)} -@r{ v@: V G @: @: @:grade@:(v)} -@r{ v@: I V G @: @: @:rgrade@:(v)} -@r{ v@: V H @:n @: 31 @:histogram@:(v,n)} -@r{ v w@: H V H @:n @: 31 @:histogram@:(v,w,n)} -@r{ v1 v2@: V I @:mop aop @: 22 @:inner@:(mop,aop,v1,v2)} -@r{ m@: V J @: @: 1 @:ctrn@:(m)} -@r{ m1 m2@: V K @: @: @:kron@:(m1,m2)} -@r{ m@: V L @: @: 1 @:lud@:(m)} -@r{ v@: V M @:op @: 22,23 @:map@:(op,v)} -@r{ v@: V N @: @: 1 @:cnorm@:(v)} -@r{ v1 v2@: V O @:op @: 22 @:outer@:(op,v1,v2)} -@r{ v@: V R @:op @: 22,23 @:reduce@:(op,v)} -@r{ v@: I V R @:op @: 22,23 @:rreduce@:(op,v)} -@r{ a n@: H V R @:op @: 22 @:nest@:(op,a,n)} -@r{ a@: I H V R @:op @: 22 @:fixp@:(op,a)} -@r{ v@: V S @: @: @:sort@:(v)} -@r{ v@: I V S @: @: @:rsort@:(v)} -@r{ m@: V T @: @: 1 @:tr@:(m)} -@r{ v@: V U @:op @: 22 @:accum@:(op,v)} -@r{ v@: I V U @:op @: 22 @:raccum@:(op,v)} -@r{ a n@: H V U @:op @: 22 @:anest@:(op,a,n)} -@r{ a@: I H V U @:op @: 22 @:afixp@:(op,a)} -@r{ s t@: V V @: @: 2 @:vunion@:(s,t)} -@r{ s t@: V X @: @: 2 @:vxor@:(s,t)} - -@c -@r{ @: Y @: @: @:@:user commands} - -@c -@r{ @: z @: @: @:@:user commands} - -@c -@r{ c@: Z [ @: @: 45 @:calc-kbd-if@:} -@r{ c@: Z | @: @: 45 @:calc-kbd-else-if@:} -@r{ @: Z : @: @: @:calc-kbd-else@:} -@r{ @: Z ] @: @: @:calc-kbd-end-if@:} - -@c -@r{ @: Z @{ @: @: 4 @:calc-kbd-loop@:} -@r{ c@: Z / @: @: 45 @:calc-kbd-break@:} -@r{ @: Z @} @: @: @:calc-kbd-end-loop@:} -@r{ n@: Z < @: @: @:calc-kbd-repeat@:} -@r{ @: Z > @: @: @:calc-kbd-end-repeat@:} -@r{ n m@: Z ( @: @: @:calc-kbd-for@:} -@r{ s@: Z ) @: @: @:calc-kbd-end-for@:} - -@c -@r{ @: Z C-g @: @: @:@:cancel if/loop command} - -@c -@r{ @: Z ` @: @: @:calc-kbd-push@:} -@r{ @: Z ' @: @: @:calc-kbd-pop@:} -@r{ @: Z # @: @: @:calc-kbd-query@:} - -@c -@r{ comp@: Z C @:func, args @: 50 @:calc-user-define-composition@:} -@r{ @: Z D @:key, command @: @:calc-user-define@:} -@r{ @: Z E @:key, editing @: 30 @:calc-user-define-edit@:} -@r{ defn@: Z F @:k, c, f, a, n@: 28 @:calc-user-define-formula@:} -@r{ @: Z G @:key @: @:calc-get-user-defn@:} -@r{ @: Z I @: @: @:calc-user-define-invocation@:} -@r{ @: Z K @:key, command @: @:calc-user-define-kbd-macro@:} -@r{ @: Z P @:key @: @:calc-user-define-permanent@:} -@r{ @: Z S @: @: 30 @:calc-edit-user-syntax@:} -@r{ @: Z T @: @: 12 @:calc-timing@:} -@r{ @: Z U @:key @: @:calc-user-undefine@:} - -@end format - -@noindent -NOTES - -@enumerate -@c 1 -@item -Positive prefix arguments apply to @expr{n} stack entries. -Negative prefix arguments apply to the @expr{-n}th stack entry. -A prefix of zero applies to the entire stack. (For @key{LFD} and -@kbd{M-@key{DEL}}, the meaning of the sign is reversed.) - -@c 2 -@item -Positive prefix arguments apply to @expr{n} stack entries. -Negative prefix arguments apply to the top stack entry -and the next @expr{-n} stack entries. - -@c 3 -@item -Positive prefix arguments rotate top @expr{n} stack entries by one. -Negative prefix arguments rotate the entire stack by @expr{-n}. -A prefix of zero reverses the entire stack. - -@c 4 -@item -Prefix argument specifies a repeat count or distance. - -@c 5 -@item -Positive prefix arguments specify a precision @expr{p}. -Negative prefix arguments reduce the current precision by @expr{-p}. - -@c 6 -@item -A prefix argument is interpreted as an additional step-size parameter. -A plain @kbd{C-u} prefix means to prompt for the step size. - -@c 7 -@item -A prefix argument specifies simplification level and depth. -1=Basic simplifications, 2=Algebraic simplifications, 3=Extended simplifications - -@c 8 -@item -A negative prefix operates only on the top level of the input formula. - -@c 9 -@item -Positive prefix arguments specify a word size of @expr{w} bits, unsigned. -Negative prefix arguments specify a word size of @expr{w} bits, signed. - -@c 10 -@item -Prefix arguments specify the shift amount @expr{n}. The @expr{w} argument -cannot be specified in the keyboard version of this command. - -@c 11 -@item -From the keyboard, @expr{d} is omitted and defaults to zero. - -@c 12 -@item -Mode is toggled; a positive prefix always sets the mode, and a negative -prefix always clears the mode. - -@c 13 -@item -Some prefix argument values provide special variations of the mode. - -@c 14 -@item -A prefix argument, if any, is used for @expr{m} instead of taking -@expr{m} from the stack. @expr{M} may take any of these values: -@iftex -{@advance@tableindent10pt -@end iftex -@table @asis -@item Integer -Random integer in the interval @expr{[0 .. m)}. -@item Float -Random floating-point number in the interval @expr{[0 .. m)}. -@item 0.0 -Gaussian with mean 1 and standard deviation 0. -@item Error form -Gaussian with specified mean and standard deviation. -@item Interval -Random integer or floating-point number in that interval. -@item Vector -Random element from the vector. -@end table -@iftex -} -@end iftex - -@c 15 -@item -A prefix argument from 1 to 6 specifies number of date components -to remove from the stack. @xref{Date Conversions}. - -@c 16 -@item -A prefix argument specifies a time zone; @kbd{C-u} says to take the -time zone number or name from the top of the stack. @xref{Time Zones}. - -@c 17 -@item -A prefix argument specifies a day number (0--6, 0--31, or 0--366). - -@c 18 -@item -If the input has no units, you will be prompted for both the old and -the new units. - -@c 19 -@item -With a prefix argument, collect that many stack entries to form the -input data set. Each entry may be a single value or a vector of values. - -@c 20 -@item -With a prefix argument of 1, take a single -@texline @var{n}@math{\times2} -@infoline @mathit{@var{N}x2} -matrix from the stack instead of two separate data vectors. - -@c 21 -@item -The row or column number @expr{n} may be given as a numeric prefix -argument instead. A plain @kbd{C-u} prefix says to take @expr{n} -from the top of the stack. If @expr{n} is a vector or interval, -a subvector/submatrix of the input is created. - -@c 22 -@item -The @expr{op} prompt can be answered with the key sequence for the -desired function, or with @kbd{x} or @kbd{z} followed by a function name, -or with @kbd{$} to take a formula from the top of the stack, or with -@kbd{'} and a typed formula. In the last two cases, the formula may -be a nameless function like @samp{<#1+#2>} or @samp{}, or it -may include @kbd{$}, @kbd{$$}, etc. (where @kbd{$} will correspond to the -last argument of the created function), or otherwise you will be -prompted for an argument list. The number of vectors popped from the -stack by @kbd{V M} depends on the number of arguments of the function. - -@c 23 -@item -One of the mapping direction keys @kbd{_} (horizontal, i.e., map -by rows or reduce across), @kbd{:} (vertical, i.e., map by columns or -reduce down), or @kbd{=} (map or reduce by rows) may be used before -entering @expr{op}; these modify the function name by adding the letter -@code{r} for ``rows,'' @code{c} for ``columns,'' @code{a} for ``across,'' -or @code{d} for ``down.'' - -@c 24 -@item -The prefix argument specifies a packing mode. A nonnegative mode -is the number of items (for @kbd{v p}) or the number of levels -(for @kbd{v u}). A negative mode is as described below. With no -prefix argument, the mode is taken from the top of the stack and -may be an integer or a vector of integers. -@iftex -{@advance@tableindent-20pt -@end iftex -@table @cite -@item -1 -(@var{2}) Rectangular complex number. -@item -2 -(@var{2}) Polar complex number. -@item -3 -(@var{3}) HMS form. -@item -4 -(@var{2}) Error form. -@item -5 -(@var{2}) Modulo form. -@item -6 -(@var{2}) Closed interval. -@item -7 -(@var{2}) Closed .. open interval. -@item -8 -(@var{2}) Open .. closed interval. -@item -9 -(@var{2}) Open interval. -@item -10 -(@var{2}) Fraction. -@item -11 -(@var{2}) Float with integer mantissa. -@item -12 -(@var{2}) Float with mantissa in @expr{[1 .. 10)}. -@item -13 -(@var{1}) Date form (using date numbers). -@item -14 -(@var{3}) Date form (using year, month, day). -@item -15 -(@var{6}) Date form (using year, month, day, hour, minute, second). -@end table -@iftex -} -@end iftex - -@c 25 -@item -A prefix argument specifies the size @expr{n} of the matrix. With no -prefix argument, @expr{n} is omitted and the size is inferred from -the input vector. - -@c 26 -@item -The prefix argument specifies the starting position @expr{n} (default 1). - -@c 27 -@item -Cursor position within stack buffer affects this command. - -@c 28 -@item -Arguments are not actually removed from the stack by this command. - -@c 29 -@item -Variable name may be a single digit or a full name. - -@c 30 -@item -Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or -@key{LFD}, or in some cases @key{RET}) to finish the edit, or kill the -buffer with @kbd{C-x k} to cancel the edit. The @key{LFD} key prevents evaluation -of the result of the edit. - -@c 31 -@item -The number prompted for can also be provided as a prefix argument. - -@c 32 -@item -Press this key a second time to cancel the prefix. - -@c 33 -@item -With a negative prefix, deactivate all formulas. With a positive -prefix, deactivate and then reactivate from scratch. - -@c 34 -@item -Default is to scan for nearest formula delimiter symbols. With a -prefix of zero, formula is delimited by mark and point. With a -non-zero prefix, formula is delimited by scanning forward or -backward by that many lines. - -@c 35 -@item -Parse the region between point and mark as a vector. A nonzero prefix -parses @var{n} lines before or after point as a vector. A zero prefix -parses the current line as a vector. A @kbd{C-u} prefix parses the -region between point and mark as a single formula. - -@c 36 -@item -Parse the rectangle defined by point and mark as a matrix. A positive -prefix @var{n} divides the rectangle into columns of width @var{n}. -A zero or @kbd{C-u} prefix parses each line as one formula. A negative -prefix suppresses special treatment of bracketed portions of a line. - -@c 37 -@item -A numeric prefix causes the current language mode to be ignored. - -@c 38 -@item -Responding to a prompt with a blank line answers that and all -later prompts by popping additional stack entries. - -@c 39 -@item -Answer for @expr{v} may also be of the form @expr{v = v_0} or -@expr{v - v_0}. - -@c 40 -@item -With a positive prefix argument, stack contains many @expr{y}'s and one -common @expr{x}. With a zero prefix, stack contains a vector of -@expr{y}s and a common @expr{x}. With a negative prefix, stack -contains many @expr{[x,y]} vectors. (For 3D plots, substitute -@expr{z} for @expr{y} and @expr{x,y} for @expr{x}.) - -@c 41 -@item -With any prefix argument, all curves in the graph are deleted. - -@c 42 -@item -With a positive prefix, refines an existing plot with more data points. -With a negative prefix, forces recomputation of the plot data. - -@c 43 -@item -With any prefix argument, set the default value instead of the -value for this graph. - -@c 44 -@item -With a negative prefix argument, set the value for the printer. - -@c 45 -@item -Condition is considered ``true'' if it is a nonzero real or complex -number, or a formula whose value is known to be nonzero; it is ``false'' -otherwise. - -@c 46 -@item -Several formulas separated by commas are pushed as multiple stack -entries. Trailing @kbd{)}, @kbd{]}, @kbd{@}}, @kbd{>}, and @kbd{"} -delimiters may be omitted. The notation @kbd{$$$} refers to the value -in stack level three, and causes the formula to replace the top three -stack levels. The notation @kbd{$3} refers to stack level three without -causing that value to be removed from the stack. Use @key{LFD} in place -of @key{RET} to prevent evaluation; use @kbd{M-=} in place of @key{RET} -to evaluate variables. - -@c 47 -@item -The variable is replaced by the formula shown on the right. The -Inverse flag reverses the order of the operands, e.g., @kbd{I s - x} -assigns -@texline @math{x \coloneq a-x}. -@infoline @expr{x := a-x}. - -@c 48 -@item -Press @kbd{?} repeatedly to see how to choose a model. Answer the -variables prompt with @expr{iv} or @expr{iv;pv} to specify -independent and parameter variables. A positive prefix argument -takes @mathit{@var{n}+1} vectors from the stack; a zero prefix takes a matrix -and a vector from the stack. - -@c 49 -@item -With a plain @kbd{C-u} prefix, replace the current region of the -destination buffer with the yanked text instead of inserting. - -@c 50 -@item -All stack entries are reformatted; the @kbd{H} prefix inhibits this. -The @kbd{I} prefix sets the mode temporarily, redraws the top stack -entry, then restores the original setting of the mode. - -@c 51 -@item -A negative prefix sets the default 3D resolution instead of the -default 2D resolution. - -@c 52 -@item -This grabs a vector of the form [@var{prec}, @var{wsize}, @var{ssize}, -@var{radix}, @var{flfmt}, @var{ang}, @var{frac}, @var{symb}, @var{polar}, -@var{matrix}, @var{simp}, @var{inf}]. A prefix argument from 1 to 12 -grabs the @var{n}th mode value only. -@end enumerate - -@iftex -(Space is provided below for you to keep your own written notes.) -@page -@endgroup -@end iftex - - -@c [end-summary] - -@node Key Index, Command Index, Summary, Top -@unnumbered Index of Key Sequences - -@printindex ky - -@node Command Index, Function Index, Key Index, Top -@unnumbered Index of Calculator Commands - -Since all Calculator commands begin with the prefix @samp{calc-}, the -@kbd{x} key has been provided as a variant of @kbd{M-x} which automatically -types @samp{calc-} for you. Thus, @kbd{x last-args} is short for -@kbd{M-x calc-last-args}. - -@printindex pg - -@node Function Index, Concept Index, Command Index, Top -@unnumbered Index of Algebraic Functions - -This is a list of built-in functions and operators usable in algebraic -expressions. Their full Lisp names are derived by adding the prefix -@samp{calcFunc-}, as in @code{calcFunc-sqrt}. -@iftex -All functions except those noted with ``*'' have corresponding -Calc keystrokes and can also be found in the Calc Summary. -@end iftex - -@printindex tp - -@node Concept Index, Variable Index, Function Index, Top -@unnumbered Concept Index - -@printindex cp - -@node Variable Index, Lisp Function Index, Concept Index, Top -@unnumbered Index of Variables - -The variables in this list that do not contain dashes are accessible -as Calc variables. Add a @samp{var-} prefix to get the name of the -corresponding Lisp variable. - -The remaining variables are Lisp variables suitable for @code{setq}ing -in your Calc init file or @file{.emacs} file. - -@printindex vr - -@node Lisp Function Index, , Variable Index, Top -@unnumbered Index of Lisp Math Functions - -The following functions are meant to be used with @code{defmath}, not -@code{defun} definitions. For names that do not start with @samp{calc-}, -the corresponding full Lisp name is derived by adding a prefix of -@samp{math-}. - -@printindex fn - -@bye diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi deleted file mode 100644 index cbb49e00efa..00000000000 --- a/doc/misc/cc-mode.texi +++ /dev/null @@ -1,7243 +0,0 @@ -\input texinfo -@c Notes to self regarding line handling: -@c -@c Empty lines are often significant before @end directives; avoid them. -@c -@c Empty lines before and after @example directives are significant in -@c info output but not in TeX. Empty lines inside @example directives -@c are significant. - -@c Conventions for formatting examples: -@c o If the example contains empty lines then put the surrounding empty -@c lines inside the @example directives. Put them outside otherwise. -@c o Use @group inside the example only if it shows indentation where -@c the relation between lines inside is relevant. -@c o Format line number columns like this: -@c 1: foo -@c 2: bar -@c ^ one space -@c ^^ two columns, right alignment -@c o Check line lengths in TeX output; they can typically be no longer -@c than 70 chars, 60 if the paragraph is indented. - -@comment TBD: Document the finer details of statement anchoring? - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment %**start of header (This is for running Texinfo on a region) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment How to make the various output formats: -@comment (Thanks to Robert Chassell for supplying this information.) -@comment Note that Texinfo 4.7 (or later) is needed. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ignore -In each of the following pairs of commands, the first generates a -version with cross references pointing to the GNU Emacs manuals, -the second with them pointing to the XEmacs manuals. - ## Info output - makeinfo cc-mode.texi - makeinfo -DXEMACS cc-mode.texi - - ## DVI output - ## You may need to set up the environment variable TEXINPUTS so - ## that tex can find the file texinfo.tex - See the tex - ## manpage. - texi2dvi cc-mode.texi - texi2dvi -t "@set XEMACS " cc-mode.texi - - ## HTML output. (The --no-split parameter is optional) - makeinfo --html --no-split cc-mode.texi - makeinfo --html --no-split -DXEMACS cc-mode.texi - - ## Plain text output - makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ - --no-headers --output=cc-mode.txt cc-mode.texi - makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ - --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi - - ## DocBook output - makeinfo --docbook --no-split --paragraph-indent=0 \ - cc-mode.texi - makeinfo --docbook --no-split --paragraph-indent=0 \ - -DXEMACS cc-mode.texi - - ## XML output - makeinfo --xml --no-split --paragraph-indent=0 \ - cc-mode.texi - makeinfo --xml --no-split --paragraph-indent=0 \ - -DXEMACS cc-mode.texi - - #### (You must be in the same directory as the viewed file.) - - ## View DVI output - xdvi cc-mode.dvi & - - ## View HTML output - mozilla cc-mode.html -@end ignore - -@comment No overfull hbox marks in the dvi file. -@finalout - -@setfilename ../../info/ccmode -@settitle CC Mode Manual -@documentencoding UTF-8 -@footnotestyle end - -@c The following four macros generate the filenames and titles of the -@c main (X)Emacs manual and the Elisp/Lispref manual. Leave the -@c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it -@c to generate an XEmacs version, e.g., with -@c "makeinfo -DXEMACS cc-mode.texi". -@ifset XEMACS -@macro emacsman -xemacs -@end macro -@macro emacsmantitle -XEmacs User's Manual -@end macro -@macro lispref -lispref -@end macro -@macro lispreftitle -XEmacs Lisp Reference Manual -@end macro -@end ifset - -@ifclear XEMACS -@macro emacsman -emacs -@end macro -@macro emacsmantitle -GNU Emacs Manual -@end macro -@macro lispref -elisp -@end macro -@macro lispreftitle -GNU Emacs Lisp Reference Manual -@end macro -@end ifclear - - -@macro ccmode -CC Mode -@end macro - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment @setchapternewpage odd !! we don't want blank pages !! -@comment %**end of header (This is for running Texinfo on a region) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment -@comment Texinfo manual for CC Mode -@comment Generated from the original README file by Krishna Padmasola -@comment -@comment -@comment Authors: -@comment Barry A. Warsaw -@comment Martin Stjernholm -@comment Alan Mackenzie -@comment -@comment Maintained by Martin Stjernholm and Alan Mackenzie -@comment -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@comment Define an index for syntactic symbols. -@defindex ss - -@comment Combine key, syntactic symbol and concept indices into one. -@syncodeindex ss cp -@syncodeindex ky cp - -@copying -This manual is for CC Mode in Emacs. - -Copyright @copyright{} 1995--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@comment Info directory entry for use by install-info. The indentation -@comment here is by request from the FSF folks. -@dircategory Emacs editing modes -@direntry -* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, - Java, Pike, AWK, and CORBA IDL code. -@end direntry - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment TeX title page -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@titlepage -@sp 10 - -@center @titlefont{CC Mode 5.32} -@sp 2 -@center A GNU Emacs mode for editing C and C-like languages -@sp 2 -@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie - -@page -@vskip 0pt plus 1filll -@insertcopying - -This manual was generated from cc-mode.texi, which is distributed with Emacs, -or can be downloaded from @url{http://savannah.gnu.org/projects/emacs/}. -@end titlepage - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment The Top node contains the master menu for the Info file. -@comment This appears only in the Info file, not the printed manual. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@summarycontents -@contents - -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up - -@ifnottex -@top @ccmode{} - -@ccmode{} is a GNU Emacs mode for editing files containing C, C++, -Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike -and AWK code. It provides syntax-based indentation, font locking, and -has several handy commands and some minor modes to make the editing -easier. It does not provide tools to look up and navigate between -functions, classes, etc.; there are other packages for that. - -@insertcopying -@end ifnottex - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@menu -* Introduction:: -* Overview:: -* Getting Started:: -* Commands:: -* Font Locking:: -* Config Basics:: -* Custom Filling and Breaking:: -* Custom Auto-newlines:: -* Clean-ups:: -* Indentation Engine Basics:: -* Customizing Indentation:: -* Custom Macros:: -* Odds and Ends:: -* Sample Init File:: -* Performance Issues:: -* Limitations and Known Bugs:: -* FAQ:: -* Updating CC Mode:: -* Mailing Lists and Bug Reports:: -* GNU Free Documentation License:: -* Command and Function Index:: -* Variable Index:: -* Concept and Key Index:: - -@detailmenu - --- The Detailed Node Listing --- - -Commands - -* Indentation Commands:: -* Comment Commands:: -* Movement Commands:: -* Filling and Breaking:: -* Minor Modes:: -* Electric Keys:: -* Auto-newlines:: -* Hungry WS Deletion:: -* Subword Movement:: -* Other Commands:: - -Font Locking - -* Font Locking Preliminaries:: -* Faces:: -* Doc Comments:: -* AWK Mode Font Locking:: - -Configuration Basics - -* CC Hooks:: -* Style Variables:: -* Styles:: - -Styles - -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* Guessing the Style:: -* File Styles:: - -Customizing Auto-newlines - -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semicolons and Commas:: - -Hanging Braces - -* Custom Braces:: - -Indentation Engine Basics - -* Syntactic Analysis:: -* Syntactic Symbols:: -* Indentation Calculation:: - -Syntactic Symbols - -* Function Symbols:: -* Class Symbols:: -* Conditional Construct Symbols:: -* Switch Statement Symbols:: -* Brace List Symbols:: -* External Scope Symbols:: -* Paren List Symbols:: -* Literal Symbols:: -* Multiline Macro Symbols:: -* Objective-C Method Symbols:: -* Java Symbols:: -* Statement Block Symbols:: -* K&R Symbols:: - -Customizing Indentation - -* c-offsets-alist:: -* Interactive Customization:: -* Line-Up Functions:: -* Custom Line-Up:: -* Other Indentation:: - -Line-Up Functions - -* Brace/Paren Line-Up:: -* List Line-Up:: -* Operator Line-Up:: -* Comment Line-Up:: -* Misc Line-Up:: - -Customizing Macros - -* Macro Backslashes:: -* Macros with ;:: - -@end detailmenu -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Introduction, Overview, Top, Top -@comment node-name, next, previous, up -@chapter Introduction -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex BOCM -@cindex history -@cindex awk-mode.el -@cindex c-mode.el -@cindex c++-mode.el - -Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C, -C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and -CIDL), Pike and AWK code. This incarnation of the mode is descended -from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM -@t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been -maintaining since 1992, and @file{awk-mode.el}, a long neglected mode -in the (X)Emacs base. - -Late in 1997, Martin Stjernholm joined Barry on the @ccmode{} -Maintainers Team, and implemented the Pike support. In 2000 Martin -took over as the sole maintainer. In 2001 Alan Mackenzie joined the -team, implementing AWK support in version 5.30. @ccmode{} did not -originally contain the font lock support for its languages; that -was added in version 5.30. - -This manual describes @ccmode{} -@comment The following line must appear on its own, so that the -version 5.32. -@comment Release.py script can update the version number automatically - -@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, -Java, CORBA's Interface Definition Language, Pike@footnote{A C-like -scripting language with its roots in the LPC language used in some MUD -engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this -way, you can easily set up consistent font locking and coding styles for -use in editing all of these languages, although AWK is not yet as -uniformly integrated as the other languages. - -@findex c-mode -@findex c++-mode -@findex objc-mode -@findex java-mode -@findex idl-mode -@findex pike-mode -@findex awk-mode -Note that the name of this package is ``@ccmode{}'', but there is no top -level @code{cc-mode} entry point. All of the variables, commands, and -functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and -@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, -@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are -provided. This package is intended to be a replacement for -@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}. - -A special word of thanks goes to Krishna Padmasola for his work in -converting the original @file{README} file to Texinfo format. I'd -also like to thank all the @ccmode{} victims who help enormously -during the early beta stages of @ccmode{}'s development. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Overview, Getting Started, Introduction, Top -@comment node-name, next, previous, up@cindex organization of the manual -@chapter Overview of the Manual -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@noindent -The manual starts with several introductory chapters (including this -one). - -@noindent -The next chunk of the manual describes the day to day @emph{use} of -@ccmode{} (as contrasted with how to customize it). - -@itemize @bullet -@item -The chapter ``Commands'' describes in detail how to use (nearly) all -of @ccmode{}'s features. There are extensive cross-references from -here to the corresponding sections later in the manual which tell you -how to customize these features. - -@item -``Font Locking'' describes how ``syntax highlighting'' is applied to -your buffers. It is mainly background information and can be skipped -over at a first reading. -@end itemize - -@noindent -The next chunk of the manual describes how to @emph{customize} -@ccmode{}. Typically, an overview of a topic is given at the chapter -level, then the sections and subsections describe the material in -increasing detail. - -@itemize @bullet -@item -The chapter ``Configuration Basics'' tells you @emph{how} to write -customizations: whether in hooks, in styles, in both, or in neither, -depending on your needs. It describes the @ccmode{} style system and -lists the standard styles that @ccmode{} supplies. - -@item -The next few chapters describe in detail how to customize the various -features of @ccmode{}. - -@item -Finally, there is a sample @file{.emacs} fragment, which might help you -in creating your own customization. -@end itemize - -@noindent -The manual ends with ``this and that'', things that don't fit cleanly -into any of the previous chunks. - -@itemize @bullet -@item -Two chapters discuss the performance of @ccmode{} and known -bugs/limitations. - -@item -The FAQ contains a list of common problems and questions. - -@item -The next two chapters tell you how to get in touch with the @ccmode{} -project: whether for updating @ccmode{} or submitting bug reports. -@end itemize - -@noindent -Finally, there are the customary indices. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Getting Started, Commands, Overview, Top -@comment node-name, next, previous, up -@chapter Getting Started -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you got this version of @ccmode{} with Emacs or XEmacs, it should -work just fine right out of the box. Note however that you might not -have the latest @ccmode{} release and might want to upgrade your copy -(see below). - -You should probably start by skimming through the entire Commands chapter -(@pxref{Commands}) to get an overview of @ccmode{}'s capabilities. - -After trying out some commands, you may dislike some aspects of -@ccmode{}'s default configuration. Here is an outline of how to -change some of the settings that newcomers to @ccmode{} most often -want to change: - -@table @asis -@item c-basic-offset -This Lisp variable holds an integer, the number of columns @ccmode{} -indents nested code. To set this value to 6, customize -@code{c-basic-offset} or put this into your @file{.emacs}: - -@example -(setq c-basic-offset 6) -@end example - -@item The (indentation) style -The basic ``shape'' of indentation created by @ccmode{}---by default, -this is @code{gnu} style (except for Java and AWK buffers). A list of -the available styles and their descriptions can be found in -@ref{Built-in Styles}. A complete specification of the @ccmode{} -style system, including how to create your own style, can be found in -the chapter @ref{Styles}. To set your style to @code{linux}, either -customize @code{c-default-style} or put this into your @file{.emacs}: - -@example -(setq c-default-style '((java-mode . "java") - (awk-mode . "awk") - (other . "linux"))) -@end example - -@item Electric Indentation -Normally, when you type ``punctuation'' characters such as @samp{;} or -@samp{@{}, @ccmode{} instantly reindents the current line. This can -be disconcerting until you get used to it. To disable @dfn{electric -indentation} in the current buffer, type @kbd{C-c C-l}. Type the same -thing to enable it again. To have electric indentation disabled by -default, put the following into your @file{.emacs} file@footnote{There -is no ``easy customization'' facility for making this change.}: - -@example -(setq-default c-electric-flag nil) -@end example - -@noindent -Details of this and other similar ``Minor Modes'' appear in the -section @ref{Minor Modes}. - -@item Making the @key{RET} key indent the new line -The standard Emacs binding for @key{RET} just adds a new line. If you -want it to reindent the new line as well, rebind the key. Note that -the action of rebinding would fail if the pertinent keymap didn't yet -exist---we thus need to delay the action until after @ccmode{} has -been loaded. Put the following code into your @file{.emacs}: - -@example -(defun my-make-CR-do-indent () - (define-key c-mode-base-map "\C-m" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-make-CR-do-indent) -@end example - -@noindent -This example demonstrates the use of a very powerful @ccmode{} (and -Emacs) facility, the hook. The use of @ccmode{}'s hooks is described -in @ref{CC Hooks}. -@end table - -All these settings should occur in your @file{.emacs} @emph{before} -any @ccmode{} buffers get loaded---in particular, before any call of -@code{desktop-read}. - -As you get to know the mode better, you may want to make more -ambitious changes to your configuration. For this, you should start -reading the chapter @ref{Config Basics}. - -If you are upgrading an existing @ccmode{} installation, please see -the @file{README} file for installation details. In particular, if -you are going to be editing AWK files, @file{README} describes how to -configure your (X)Emacs so that @ccmode{} will supersede the obsolete -@code{awk-mode.el} which might have been supplied with your (X)Emacs. -@ccmode{} might not work with older versions of Emacs or XEmacs. See -the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net} -for the latest information on Emacs version and package compatibility -(@pxref{Updating CC Mode}). - -@deffn Command c-version -@findex version (c-) -You can find out what version of @ccmode{} you are using by visiting a C -file and entering @kbd{M-x c-version RET}. You should see this message in -the echo area: - -@example -Using CC Mode version 5.XX -@end example - -@noindent -where @samp{XX} is the minor release number. -@end deffn - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Commands, Font Locking, Getting Started, Top -@comment node-name, next, previous, up -@chapter Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This chapter specifies all of CC Mode's commands, and thus contains -nearly everything you need to know to @emph{use} @ccmode{} (as -contrasted with configuring it). @dfn{Commands} here means both -control key sequences and @dfn{electric keys}, these being characters -such as @samp{;} which, as well as inserting themselves into the -buffer, also do other things. - -You might well want to review -@ifset XEMACS -@ref{Lists,,,@emacsman{}, @emacsmantitle{}}, -@end ifset -@ifclear XEMACS -@ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}}, -@end ifclear -which describes commands for moving around brace and parenthesis -structures. - - -@menu -* Indentation Commands:: -* Comment Commands:: -* Movement Commands:: -* Filling and Breaking:: -* Minor Modes:: -* Electric Keys:: -* Auto-newlines:: -* Hungry WS Deletion:: -* Subword Movement:: -* Other Commands:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Commands, Comment Commands, Commands, Commands -@comment node-name, next, previous,up -@section Indentation Commands -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The following commands reindent C constructs. Note that when you -change your coding style, either interactively or through some other -means, your file does @emph{not} automatically get reindented. You -will need to execute one of the following commands to see the effects -of your changes. - -@cindex GNU indent program -Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} -(@pxref{Custom Auto-newlines}) only affect how on-the-fly code is -formatted. Changing the ``hanginess'' of a brace and then -reindenting, will not move the brace to a different line. For this, -you're better off getting an external program like GNU @code{indent}, -which will rearrange brace location, amongst other things. - -Preprocessor directives are handled as syntactic whitespace from other -code, i.e., they can be interspersed anywhere without affecting the -indentation of the surrounding code, just like comments. - -The code inside macro definitions is, by default, still analyzed -syntactically so that you get relative indentation there just as you'd -get if the same code was outside a macro. However, since there is no -hint about the syntactic context, i.e., whether the macro expands to an -expression, to some statements, or perhaps to whole functions, the -syntactic recognition can be wrong. @ccmode{} manages to figure it -out correctly most of the time, though. - -Some macros, when invoked, ''have their own semicolon''. To get the -next line indented correctly, rather than as a continuation line, -@xref{Macros with ;}. - -Reindenting large sections of code can take a long time. When -@ccmode{} reindents a region of code, it is essentially equivalent to -hitting @key{TAB} on every line of the region. - -These commands indent code: - -@table @asis -@item @kbd{@key{TAB}} (@code{c-indent-command}) -@kindex TAB -@findex c-indent-command -@findex indent-command (c-) -This command indents the current line. That is all you need to know -about it for normal use. - -@code{c-indent-command} does different things, depending on the -setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine -Basics}): - -@itemize @bullet -@item -When it's non-@code{nil} (which it normally is), the command indents -the line according to its syntactic context. With a prefix argument -(@kbd{C-u @key{TAB}}), it will re-indent the entire -expression@footnote{this is only useful for a line starting with a -comment opener or an opening brace, parenthesis, or string quote.} -that begins at the line's left margin. - -@item -When it's @code{nil}, the command indents the line by an extra -@code{c-basic-offset} columns. A prefix argument acts as a -multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1, -removing @code{c-basic-offset} columns from the indentation. -@end itemize - -The precise behavior is modified by several variables: With -@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace -in some circumstances---@code{c-insert-tab-function} then defines -precisely what sort of ``whitespace'' this will be. Set the standard -Emacs variable @code{indent-tabs-mode} to @code{t} if you want real -@samp{tab} characters to be used in the indentation, to @code{nil} if -you want only spaces. @xref{Just Spaces,,,@emacsman{}, -@emacsmantitle{}}. - -@defopt c-tab-always-indent -@vindex tab-always-indent (c-) -@cindex literal -This variable modifies how @key{TAB} operates. -@itemize @bullet -@item -When it is @code{t} (the default), @key{TAB} simply indents the -current line. -@item -When it is @code{nil}, @key{TAB} (re)indents the line only if point is -to the left of the first non-whitespace character on the line. -Otherwise it inserts some whitespace (a tab or an equivalent number of -spaces; see below) at point. -@item -With some other value, the line is reindented. Additionally, if point -is within a string or comment, some whitespace is inserted. -@end itemize -@end defopt - -@defopt c-insert-tab-function -@vindex insert-tab-function (c-) -@findex tab-to-tab-stop -When ``some whitespace'' is inserted as described above, what actually -happens is that the function stored in @code{c-insert-tab-function} is -called. Normally, this is @code{insert-tab}, which inserts a real tab -character or the equivalent number of spaces (depending on -@code{indent-tabs-mode}). Some people, however, set -@code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get -hard tab stops when indenting. -@end defopt -@end table - -@noindent -The kind of indentation the next five commands do depends on the -setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine -Basics}): -@itemize @bullet -@item -when it is non-@code{nil} (the default), the commands indent lines -according to their syntactic context; -@item -when it is @code{nil}, they just indent each line the same amount as -the previous non-blank line. The commands that indent a region aren't -very useful in this case. -@end itemize - -@table @asis -@item @kbd{C-M-q} (@code{c-indent-exp}) -@kindex C-M-q -@findex c-indent-exp -@findex indent-exp (c-) -Indents an entire balanced brace or parenthesis expression. Note that -point must be on the opening brace or parenthesis of the expression -you want to indent. - -@item @kbd{C-c C-q} (@code{c-indent-defun}) -@kindex C-c C-q -@findex c-indent-defun -@findex indent-defun (c-) -Indents the entire top-level function, class or macro definition -encompassing point. It leaves point unchanged. This function can't be -used to reindent a nested brace construct, such as a nested class or -function, or a Java method. The top-level construct being reindented -must be complete, i.e., it must have both a beginning brace and an ending -brace. - -@item @kbd{C-M-\} (@code{indent-region}) -@kindex C-M-\ -@findex indent-region -Indents an arbitrary region of code. This is a standard Emacs command, -tailored for C code in a @ccmode{} buffer. Note, of course, that point -and mark must delineate the region you want to indent. - -@item @kbd{C-M-h} (@code{c-mark-function}) -@kindex C-M-h -@findex c-mark-function -@findex mark-function (c-) -While not strictly an indentation command, this is useful for marking -the current top-level function or class definition as the current -region. As with @code{c-indent-defun}, this command operates on -top-level constructs, and can't be used to mark say, a Java method. -@end table - -These variables are also useful when indenting code: - -@defopt indent-tabs-mode -This is a standard Emacs variable that controls how line indentation -is composed. When it's non-@code{nil}, tabs can be used in a line's -indentation, otherwise only spaces are used. -@end defopt - -@defopt c-progress-interval -@vindex progress-interval (c-) -When indenting large regions of code, this variable controls how often a -progress message is displayed. Set this variable to @code{nil} to -inhibit the progress messages, or set it to an integer which is how -often (in seconds) progress messages are to be displayed. -@end defopt - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Comment Commands, Movement Commands, Indentation Commands, Commands -@comment node-name, next, previous, up -@section Comment Commands -@cindex comments (insertion of) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@table @asis -@item @kbd{C-c C-c} (@code{comment-region}) -@kindex C-c C-c -@findex comment-region -This command comments out the lines that start in the region. With a -negative argument, it does the opposite: it deletes the comment -delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU -Emacs Manual}, for fuller details. @code{comment-region} isn't -actually part of @ccmode{}; it is given a @ccmode{} binding for -convenience. - -@item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.}) -@kindex M-; -@findex comment-dwim -@findex indent-for-comment -Insert a comment at the end of the current line, if none is there -already. Then reindent the comment according to @code{comment-column} -@ifclear XEMACS -(@pxref{Options for Comments,,, emacs, GNU Emacs Manual}) -@end ifclear -@ifset XEMACS -(@pxref{Comments,,, xemacs, XEmacs User's Manual}) -@end ifset -and the variables below. Finally, position the point after the -comment starter. @kbd{C-u M-;} kills any comment on the current line, -together with any whitespace before it. This is a standard Emacs -command, but @ccmode{} enhances it a bit with two variables: - -@defopt c-indent-comment-alist -@vindex indent-comment-alist (c-) -@vindex comment-column -This style variable allows you to vary the column that @kbd{M-;} puts -the comment at, depending on what sort of code is on the line, and -possibly the indentation of any similar comment on the preceding line. -It is an association list that maps different types of lines to -actions describing how they should be handled. If a certain line type -isn't present on the list then the line is indented to the column -specified by @code{comment-column}. - -See the documentation string for a full description of this -variable (use @kbd{C-h v c-indent-comment-alist}). -@end defopt - -@defopt c-indent-comments-syntactically-p -@vindex indent-comments-syntactically-p (c-) -Normally, when this style variable is @code{nil}, @kbd{M-;} will -indent comment-only lines according to @code{c-indent-comment-alist}, -just as it does with lines where other code precede the comments. -However, if you want it to act just like @key{TAB} for comment-only -lines you can get that by setting -@code{c-indent-comments-syntactically-p} to non-@code{nil}. - -If @code{c-indent-comments-syntactically-p} is non-@code{nil} then -@code{c-indent-comment-alist} won't be consulted at all for comment-only -lines. -@end defopt -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Movement Commands, Filling and Breaking, Comment Commands, Commands -@comment node-name, next, previous, up -@section Movement Commands -@cindex movement -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} contains some useful commands for moving around in C code. - -@table @asis -@item @kbd{C-M-a} (@code{c-beginning-of-defun}) -@itemx @kbd{C-M-e} (@code{c-end-of-defun}) -@findex c-beginning-of-defun -@findex c-end-of-defun -@vindex c-defun-tactic -@vindex defun-tactic (c-) - -Move to the beginning or end of the current or next function. Other -constructs (such as a structs or classes) which have a brace block -also count as ``functions'' here. To move over several functions, you -can give these commands a repeat count. - -The start of a function is at its header. The end of the function is -after its closing brace, or after the semicolon of a construct (such -as a @code{struct}) which doesn't end at the brace. These two -commands try to leave point at the beginning of a line near the actual -start or end of the function. This occasionally causes point not to -move at all. - -By default, these commands will recognize functions contained within a -@dfn{declaration scope} such as a C++ @code{class} or @code{namespace} -construct, should the point start inside it. If @ccmode fails to find -function beginnings or ends inside the current declaration scope, it -will search the enclosing scopes. If you want @ccmode to recognize -functions only at the top level@footnote{this was @ccmode{}'s -behavior prior to version 5.32.}, set @code{c-defun-tactic} to -@code{t}. - -These functions are analogous to the Emacs built-in commands -@code{beginning-of-defun} and @code{end-of-defun}, except they -eliminate the constraint that the top-level opening brace of the defun -must be in column zero. See @ref{Defuns,,,@emacsman{}, -@emacsmantitle{}}, for more information. - -@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun}) -@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun}) -@kindex C-M-a (AWK Mode) -@kindex C-M-e (AWK Mode) -@findex c-awk-beginning-of-defun -@findex awk-beginning-of-defun (c-) -@findex c-awk-end-of-defun -@findex awk-end-of-defun (c-) -Move to the beginning or end of the current or next AWK defun. These -commands can take prefix-arguments, their functionality being entirely -equivalent to @code{beginning-of-defun} and @code{end-of-defun}. - -AWK Mode @dfn{defuns} are either pattern/action pairs (either of which -might be implicit) or user defined functions. Having the @samp{@{} and -@samp{@}} (if there are any) in column zero, as is suggested for some -modes, is neither necessary nor helpful in AWK mode. - -@item @kbd{M-a} (@code{c-beginning-of-statement}) -@itemx @kbd{M-e} (@code{c-end-of-statement}) -@kindex M-a -@kindex M-e -@findex c-beginning-of-statement -@findex c-end-of-statement -@findex beginning-of-statement (c-) -@findex end-of-statement (c-) -Move to the beginning or end of the innermost C statement. If point -is already there, move to the next beginning or end of a statement, -even if that means moving into a block. (Use @kbd{C-M-b} or -@kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n} -means move over @var{n} statements. - -If point is within or next to a comment or a string which spans more -than one line, these commands move by sentences instead of statements. - -When called from a program, these functions take three optional -arguments: the repetition count, a buffer position limit which is the -farthest back to search for the syntactic context, and a flag saying -whether to do sentence motion in or near comments and multiline -strings. - -@item @kbd{C-c C-u} (@code{c-up-conditional}) -@kindex C-c C-u -@findex c-up-conditional -@findex up-conditional (c-) -Move back to the containing preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move forward to the end of the containing preprocessor -conditional. - -@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the -function stops at them when going backward, but not when going -forward. - -This key sequence is not bound in AWK Mode, which doesn't have -preprocessor statements. - -@item @kbd{M-x c-up-conditional-with-else} -@findex c-up-conditional-with-else -@findex up-conditional-with-else (c-) -A variety of @code{c-up-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. - -@item @kbd{M-x c-down-conditional} -@findex c-down-conditional -@findex down-conditional (c-) -Move forward into the next nested preprocessor conditional, leaving -the mark behind. A prefix argument acts as a repeat count. With a -negative argument, move backward into the previous nested preprocessor -conditional. - -@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the -function stops at them when going forward, but not when going backward. - -@item @kbd{M-x c-down-conditional-with-else} -@findex c-down-conditional-with-else -@findex down-conditional-with-else (c-) -A variety of @code{c-down-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. - -@item @kbd{C-c C-p} (@code{c-backward-conditional}) -@itemx @kbd{C-c C-n} (@code{c-forward-conditional}) -@kindex C-c C-p -@kindex C-c C-n -@findex c-backward-conditional -@findex c-forward-conditional -@findex backward-conditional (c-) -@findex forward-conditional (c-) -Move backward or forward across a preprocessor conditional, leaving -the mark behind. A prefix argument acts as a repeat count. With a -negative argument, move in the opposite direction. - -These key sequences are not bound in AWK Mode, which doesn't have -preprocessor statements. - -@item @kbd{M-x c-backward-into-nomenclature} -@itemx @kbd{M-x c-forward-into-nomenclature} -@findex c-backward-into-nomenclature -@findex c-forward-into-nomenclature -@findex backward-into-nomenclature (c-) -@findex forward-into-nomenclature (c-) -A popular programming style, especially for object-oriented languages -such as C++ is to write symbols in a mixed case format, where the -first letter of each word is capitalized, and not separated by -underscores. E.g., @samp{SymbolsWithMixedCaseAndNoUnderlines}. - -These commands move backward or forward to the beginning of the next -capitalized word. With prefix argument @var{n}, move @var{n} times. -If @var{n} is negative, move in the opposite direction. - -Note that these two commands have been superseded by -@code{subword-mode}, which you should use instead. @xref{Subword -Movement}. They might be removed from a future release of @ccmode{}. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Filling and Breaking, Minor Modes, Movement Commands, Commands -@comment node-name, next, previous, up -@section Filling and Line Breaking Commands -@cindex text filling -@cindex line breaking -@cindex comment handling -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since there's a lot of normal text in comments and string literals, -@ccmode{} provides features to edit these like in text mode. The goal -is to do it seamlessly, i.e., you can use auto fill mode, sentence and -paragraph movement, paragraph filling, adaptive filling etc. wherever -there's a piece of normal text without having to think much about it. -@ccmode{} keeps the indentation, fixes suitable comment line prefixes, -and so on. - -You can configure the exact way comments get filled and broken, and -where Emacs does auto-filling (see @pxref{Custom Filling and -Breaking}). Typically, the style system (@pxref{Styles}) will have -set this up for you, so you probably won't have to bother. - -@findex auto-fill-mode -@cindex Auto Fill mode -@cindex paragraph filling -Line breaks are by default handled (almost) the same regardless of -whether they are made by auto fill mode (@pxref{Auto -Fill,,,@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g., with -@kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In -string literals, the new line gets the same indentation as the -previous nonempty line.@footnote{You can change this default by -setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols} -and @pxref{Customizing Indentation})}. - -@table @asis -@item @kbd{M-q} (@code{c-fill-paragraph}) -@kindex M-q -@findex c-fill-paragraph -@findex fill-paragraph (c-) -@cindex Javadoc markup -@cindex Pike autodoc markup -This command fills multiline string literals and both block -and line style comments. In Java buffers, the Javadoc markup words -are recognized as paragraph starters. The line oriented Pike autodoc -markup words are recognized in the same way in Pike mode. - -The formatting of the starters (@code{/*}) and enders (@code{*/}) of -block comments are kept as they were before the filling. I.e., if -either the starter or ender were on a line of its own, then it stays -on its own line; conversely, if the delimiter has comment text on its -line, it keeps at least one word of that text with it on the line. - -This command is the replacement for @code{fill-paragraph} in @ccmode{} -buffers. - -@item @kbd{M-j} (@code{c-indent-new-comment-line}) -@kindex M-j -@findex c-indent-new-comment-line -@findex indent-new-comment-line (c-) -This breaks the current line at point and indents the new line. If -point was in a comment, the new line gets the proper comment line -prefix. If point was inside a macro, a backslash is inserted before -the line break. It is the replacement for -@code{indent-new-comment-line}. - -@item @kbd{M-x c-context-line-break} -@findex c-context-line-break -@findex context-line-break (c-) -Insert a line break suitable to the context: If the point is inside a -comment, the new line gets the suitable indentation and comment line -prefix like @code{c-indent-new-comment-line}. In normal code it's -indented like @code{newline-and-indent} would do. In macros it acts -like @code{newline-and-indent} but additionally inserts and optionally -aligns the line ending backslash so that the macro remains unbroken. -@xref{Custom Macros}, for details about the backslash alignment. In a -string, a backslash is inserted only if the string is within a -macro@footnote{In GCC, unescaped line breaks within strings are -valid.}. - -This function is not bound to a key by default, but it's intended to be -used on the @kbd{RET} key. If you like the behavior of -@code{newline-and-indent} on @kbd{RET}, you should consider switching to -this function. @xref{Sample Init File}. - -@item @kbd{M-x c-context-open-line} -@findex c-context-open-line -@findex context-open-line (c-) -This is to @kbd{C-o} (@kbd{M-x open-line}) as -@code{c-context-line-break} is to @kbd{RET}. I.e., it works just like -@code{c-context-line-break} but leaves the point before the inserted -line break. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Minor Modes, Electric Keys, Filling and Breaking, Commands -@comment node-name, next, previous, up -@section Minor Modes -@cindex Minor Modes -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} contains several minor-mode-like features that you might -find useful while writing new code or editing old code: - -@table @asis -@item electric mode -When this is enabled, certain visible characters cause reformatting as -they are typed. This is normally helpful, but can be a nuisance when -editing chaotically formatted code. It can also be disconcerting, -especially for users who are new to @ccmode{}. -@item auto-newline mode -This automatically inserts newlines where you'd probably want to type -them yourself, e.g., after typing @samp{@}}s. Its action is suppressed -when electric mode is disabled. -@item hungry-delete mode -This lets you delete a contiguous block of whitespace with a single -key: for example, the newline and indentation just inserted by -auto-newline when you want to back up and write a comment after the -last statement. -@item subword mode -This mode makes basic word movement commands like @kbd{M-f} -(@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the -parts of sillycapsed symbols as different words. -E.g., @samp{NSGraphicsContext} is treated as three words @samp{NS}, -@samp{Graphics}, and @samp{Context}. -@item syntactic-indentation mode -When this is enabled (which it normally is), indentation commands such -as @kbd{C-j} indent lines of code according to their syntactic -structure. Otherwise, a line is simply indented to the same level as -the previous one and @kbd{@key{TAB}} adjusts the indentation in steps -of `c-basic-offset'. -@end table - -Full details on how these minor modes work are at @ref{Electric Keys}, -@ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement}, -and @ref{Indentation Engine Basics}. - -You can toggle each of these minor modes on and off, and you can -configure @ccmode{} so that it starts up with your favorite -combination of them (@pxref{Sample Init File}). By default, when -you initialize a buffer, electric mode and syntactic-indentation mode -are enabled but the other three modes are disabled. - -@ccmode{} displays the current state of the first four of these minor -modes on the modeline by appending letters to the major mode's name, -one letter for each enabled minor mode: @samp{l} for electric mode, -@samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and -@samp{w} for subword mode. If all these modes were enabled, you'd see -@samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of -the language in question for the other languages @ccmode{} supports.}. - -Here are the commands to toggle these modes: - -@table @asis -@item @kbd{C-c C-l} (@code{c-toggle-electric-state}) -@kindex C-c C-l -@findex c-toggle-electric-state -@findex toggle-electric-state (c-) -Toggle electric minor mode. When the command turns the mode off, it -also suppresses auto-newline mode. - -@item @kbd{C-c C-a} (@code{c-toggle-auto-newline}) -@kindex C-c C-a -@findex c-toggle-auto-newline -@findex toggle-auto-newline (c-) -Toggle auto-newline minor mode. When the command turns the mode on, -it also enables electric minor mode. - -@item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.} -@findex c-toggle-hungry-state -@findex toggle-hungry-state (c-) -Toggle hungry-delete minor mode. - -@item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.} -@findex c-toggle-auto-hungry-state -@findex toggle-auto-hungry-state (c-) -Toggle both auto-newline and hungry delete minor modes. - -@item @kbd{C-c C-w} (@code{M-x subword-mode}) -@kindex C-c C-w -@findex subword-mode -Toggle subword mode. - -@item @kbd{M-x c-toggle-syntactic-indentation} -@findex c-toggle-syntactic-indentation -@findex toggle-syntactic-indentation (c-) -Toggle syntactic-indentation mode. -@end table - -Common to all the toggle functions above is that if they are called -programmatically, they take an optional numerical argument. A -positive value will turn on the minor mode (or both of them in the -case of @code{c-toggle-auto-hungry-state}) and a negative value will -turn it (or them) off. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Electric Keys, Auto-newlines, Minor Modes, Commands -@comment node-name, next, previous, up -@section Electric Keys and Keywords -@cindex electric characters -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Most punctuation keys provide @dfn{electric} behavior: as well as -inserting themselves they perform some other action, such as -reindenting the line. This reindentation saves you from having to -reindent a line manually after typing, say, a @samp{@}}. A few -keywords, such as @code{else}, also trigger electric action. - -You can inhibit the electric behavior described here by disabling -electric minor mode (@pxref{Minor Modes}). - -Common to all these keys is that they only behave electrically when -used in normal code (as contrasted with getting typed in a string -literal or comment). Those which cause re-indentation do so only when -@code{c-syntactic-indentation} has a non-@code{nil} value (which it -does by default). - -These keys and keywords are: -@c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more -@c like a bug in the code than a bug in this document. It'll get -@c fixed in the code sometime. - -@table @kbd -@item # -@kindex # -@findex c-electric-pound -@findex electric-pound (c-) -@vindex c-electric-pound-behavior -@vindex electric-pound-behavior (c-) -Pound (bound to @code{c-electric-pound}) is electric when typed as the -first non-whitespace character on a line and not within a macro -definition. In this case, the variable @code{c-electric-pound-behavior} -is consulted for the electric behavior. This variable takes a list -value, although the only element currently defined is @code{alignleft}, -which tells this command to force the @samp{#} character into column -zero. This is useful for entering preprocessor macro definitions. - -Pound is not electric in AWK buffers, where @samp{#} starts a comment, -and is bound to @code{self-insert-command} like any typical printable -character. -@c ACM, 2004/8/24: Change this (and the code) to do AWK comment -@c reindentation. - -@item * -@kindex * -@itemx / -@kindex / -@findex c-electric-star -@findex electric-star (c-) -@findex c-electric-slash -@findex electric-slash (c-) -A star (bound to @code{c-electric-star}) or a slash -(@code{c-electric-slash}) causes reindentation when you type it as the -second component of a C style block comment opener (@samp{/*}) or a -C++ line comment opener (@samp{//}) respectively, but only if the -comment opener is the first thing on the line (i.e., there's only -whitespace before it). - -Additionally, you can configure @ccmode{} so that typing a slash at -the start of a line within a block comment will terminate the -comment. You don't need to have electric minor mode enabled to get -this behavior. @xref{Clean-ups}. - -In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not -electric. - -@item < -@kindex < -@itemx > -@kindex > -@findex c-electric-lt-gt -@findex electric-lt-gt (c-) -A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is -electric in two circumstances: when it is an angle bracket in a C++ -@samp{template} declaration (and similar constructs in other -languages) and when it is the second of two @kbd{<} or @kbd{>} -characters in a C++ style stream operator. In either case, the line -is reindented. Angle brackets in C @samp{#include} directives are not -electric. - -@item ( -@kindex ( -@itemx ) -@kindex ) -@findex c-electric-paren -@findex electric-paren (c-) -The normal parenthesis characters @samp{(} and @samp{)} (bound to -@code{c-electric-paren}) reindent the current line. This is useful -for getting the closing parenthesis of an argument list aligned -automatically. - -You can also configure @ccmode{} to insert a space automatically -between a function name and the @samp{(} you've just typed, and to -remove it automatically after typing @samp{)}, should the argument -list be empty. You don't need to have electric minor mode enabled to -get these actions. @xref{Clean-ups}. - -@item @{ -@kindex @{ -@itemx @} -@kindex @} -@findex c-electric-brace -@findex electric-brace (c-) -Typing a brace (bound to @code{c-electric-brace}) reindents the -current line. Also, one or more newlines might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. -Additionally, you can configure @ccmode{} to compact excess whitespace -inserted by auto-newline mode in certain circumstances. -@xref{Clean-ups}. - -@item : -@kindex : -@findex c-electric-colon -@findex electric-colon (c-) -Typing a colon (bound to @code{c-electric-colon}) reindents the -current line. Additionally, one or more newlines might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. If you -type a second colon immediately after such an auto-newline, by default -the whitespace between the two colons is removed, leaving a C++ scope -operator. @xref{Clean-ups}. - -If you prefer, you can insert @samp{::} in a single operation, -avoiding all these spurious reindentations, newlines, and clean-ups. -@xref{Other Commands}. - -@item ; -@kindex ; -@itemx , -@kindex , -@findex c-electric-semi&comma -@findex electric-semi&comma (c-) -Typing a semicolon or comma (bound to @code{c-electric-semi&comma}) -reindents the current line. Also, a newline might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. -Additionally, you can configure @ccmode{} so that when auto-newline -has inserted whitespace after a @samp{@}}, it will be removed again -when you type a semicolon or comma just after it. @xref{Clean-ups}. - -@end table - -@deffn Command c-electric-continued-statement -@findex electric-continued-statement (c-) - -Certain keywords are electric, causing reindentation when they are -preceded only by whitespace on the line. The keywords are those that -continue an earlier statement instead of starting a new one: -@code{else}, @code{while}, @code{catch} (only in C++ and Java) and -@code{finally} (only in Java). - -An example: - -@example -@group -for (i = 0; i < 17; i++) - if (a[i]) - res += a[i]->offset; -else -@end group -@end example - -Here, the @code{else} should be indented like the preceding @code{if}, -since it continues that statement. @ccmode{} will automatically -reindent it after the @code{else} has been typed in full, since only -then is it possible to decide whether it's a new statement or a -continuation of the preceding @code{if}. - -@vindex abbrev-mode -@findex abbrev-mode -@cindex Abbrev mode -@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,,@emacsman{}, @emacsmantitle{}}) -to accomplish this. It's therefore turned on by default in all language -modes except IDL mode, since CORBA IDL doesn't have any statements. -@end deffn - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands -@comment node-name, next, previous, up -@section Auto-newline Insertion -@cindex auto-newline -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor -Modes}), @ccmode{} inserts newlines for you automatically (in certain -syntactic contexts) when you type a left or right brace, a colon, a -semicolon, or a comma. Sometimes a newline appears before the -character you type, sometimes after it, sometimes both. - -Auto-newline only triggers when the following conditions hold: - -@itemize @bullet -@item -Auto-newline minor mode is enabled, as evidenced by the indicator -@samp{a} after the mode name on the modeline (e.g., @samp{C/a} or -@samp{C/la}). - -@item -The character was typed at the end of a line, or with only whitespace -after it, and possibly a @samp{\} escaping the newline. - -@item -The character is not on its own line already. (This applies only to -insertion of a newline @emph{before} the character.) - -@item -@cindex literal -@cindex syntactic whitespace -The character was not typed inside of a literal @footnote{A -@dfn{literal} is defined as any comment, string, or preprocessor macro -definition. These constructs are also known as @dfn{syntactic -whitespace} since they are usually ignored when scanning C code.}. - -@item -No numeric argument was supplied to the command (i.e., it was typed as -normal, with no @kbd{C-u} prefix). -@end itemize - -You can configure the precise circumstances in which newlines get -inserted (see @pxref{Custom Auto-newlines}). Typically, the style -system (@pxref{Styles}) will have set this up for you, so you probably -won't have to bother. - -Sometimes @ccmode{} inserts an auto-newline where you don't want one, -such as after a @samp{@}} when you're about to type a @samp{;}. -Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can -activate an appropriate @dfn{clean-up}, which will remove the excess -whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a -full description. See also @ref{Electric Keys} for a summary of -clean-ups listed by key. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands -@comment node-name, next, previous, up -@section Hungry Deletion of Whitespace -@cindex hungry-deletion -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you want to delete an entire block of whitespace at point, you can -use @dfn{hungry deletion}. This deletes all the contiguous whitespace -either before point or after point in a single operation. -``Whitespace'' here includes tabs and newlines, but not comments or -preprocessor commands. Hungry deletion can markedly cut down on the -number of times you have to hit deletion keys when, for example, -you've made a mistake on the preceding line and have already pressed -@kbd{C-j}. - -Hungry deletion is a simple feature that some people find extremely -useful. In fact, you might find yourself wanting it in @strong{all} -your editing modes! - -Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the -backspace key'' and @dfn{@key{DELETE}} means ``the forward delete -key''. This is discussed in more detail below. - -There are two different ways you can use hungry deletion: - -@table @asis -@item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d} -Here you toggle Hungry Delete minor mode with @kbd{M-x -c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command -was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding -for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This -makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry -deletion. - -@table @asis -@item @kbd{@key{DEL}} (@code{c-electric-backspace}) -@kindex DEL -@findex c-electric-backspace -@findex electric-backspace (c-) -This command is run by default when you hit the @kbd{DEL} key. When -hungry delete mode is enabled, it deletes any amount of whitespace in -the backwards direction. Otherwise, or when used with a prefix -argument or in a literal (@pxref{Auto-newlines}), the command just -deletes backwards in the usual way. (More precisely, it calls the -function contained in the variable @code{c-backspace-function}, -passing it the prefix argument, if any.) - -@item @code{c-backspace-function} -@vindex c-backspace-function -@vindex backspace-function (c-) -@findex backward-delete-char-untabify -Hook that gets called by @code{c-electric-backspace} when it doesn't -do an ``electric'' deletion of the preceding whitespace. The default -value is @code{backward-delete-char-untabify} -(@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which -deletes a single character. - -@item @kbd{C-d} (@code{c-electric-delete-forward}) -@kindex C-d -@findex c-electric-delete-forward -@findex electric-delete-forward (c-) -This function, which is bound to @kbd{C-d} by default, works just like -@code{c-electric-backspace} but in the forward direction. When it -doesn't do an ``electric'' deletion of the following whitespace, it -just does @code{delete-char}, more or less. (Strictly speaking, it -calls the function in @code{c-delete-function} with the prefix -argument.) - -@item @code{c-delete-function} -@vindex c-delete-function -@vindex delete-function (c-) -@findex delete-char -Hook that gets called by @code{c-electric-delete-forward} when it -doesn't do an ``electric'' deletion of the following whitespace. The -default value is @code{delete-char}. -@end table - -@item Using Distinct Bindings -The other (newer and recommended) way to use hungry deletion is to -perform @code{c-hungry-delete-backwards} and -@code{c-hungry-delete-forward} directly through their key sequences -rather than using the minor mode toggling. - -@table @asis -@item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.} -@kindex C-c C- -@kindex C-c -@kindex C-c C-DEL -@kindex C-c DEL -@findex c-hungry-delete-backwards -@findex hungry-delete-backwards (c-) -Delete any amount of whitespace in the backwards direction (regardless -whether hungry-delete mode is enabled or not). This command is bound -to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more -natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at -a character terminal. - -@item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward}) -@kindex C-c C-d -@kindex C-c C- -@kindex C-c -@findex c-hungry-delete-forward -@findex hungry-delete-forward (c-) -Delete any amount of whitespace in the forward direction (regardless -whether hungry-delete mode is enabled or not). This command is bound -to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the -same reason as for @key{DEL} above. -@end table -@end table - -@kindex -@kindex - -When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we -actually do so without connecting them to the physical keys commonly -known as @key{Backspace} and @key{Delete}. The default bindings to -those two keys depends on the flavor of (X)Emacs you are using. - -@findex c-electric-delete -@findex electric-delete (c-) -@findex c-hungry-delete -@findex hungry-delete (c-) -@vindex delete-key-deletes-forward -In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to -@code{c-electric-backspace} and the @key{Delete} key is bound to -@code{c-electric-delete}. You control the direction it deletes in by -setting the variable @code{delete-key-deletes-forward}, a standard -XEmacs variable. -@c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...). -When this variable is non-@code{nil}, @code{c-electric-delete} will do -forward deletion with @code{c-electric-delete-forward}, otherwise it -does backward deletion with @code{c-electric-backspace}. Similarly, -@kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to -@code{c-hungry-delete} which is controlled in the same way by -@code{delete-key-deletes-forward}. - -@findex normal-erase-is-backspace-mode - -Emacs 21 and later automatically binds @key{Backspace} and -@key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment, -and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}} -etc. If you need to change the bindings through -@code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt -its extended bindings accordingly. - -In earlier (X)Emacs versions, @ccmode{} doesn't bind either -@key{Backspace} or @key{Delete} directly. Only the key codes -@kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings -to map the physical keys to them. You might need to modify this -yourself if the defaults are unsuitable. - -Getting your @key{Backspace} and @key{Delete} keys properly set up can -sometimes be tricky. The information in @ref{DEL Does Not -Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having -trouble with this in GNU Emacs. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Subword Movement, Other Commands, Hungry WS Deletion, Commands -@comment node-name, next, previous, up -@section Subword Movement and Editing -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex nomenclature -@cindex subword -In spite of the GNU Coding Standards, it is popular to name a symbol -by mixing uppercase and lowercase letters, e.g., @samp{GtkWidget}, -@samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call -these mixed case symbols @dfn{nomenclatures}. Also, each capitalized -(or completely uppercase) part of a nomenclature is called a -@dfn{subword}. Here are some examples: - -@multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}} -@c This could be converted to @headitem when we require Texinfo 4.7 -@iftex -@item @b{Nomenclature} - @tab @b{Subwords} -@end iftex -@ifnottex -@item Nomenclature - @tab Subwords -@item --------------------------------------------------------- -@end ifnottex -@item @samp{GtkWindow} - @tab @samp{Gtk} and @samp{Window} -@item @samp{EmacsFrameClass} - @tab @samp{Emacs}, @samp{Frame}, and @samp{Class} -@item @samp{NSGraphicsContext} - @tab @samp{NS}, @samp{Graphics}, and @samp{Context} -@end multitable - -The subword minor mode replaces the basic word oriented movement and -editing commands with variants that recognize subwords in a -nomenclature and treat them as separate words: - -@findex c-forward-subword -@findex forward-subword (c-) -@findex c-backward-subword -@findex backward-subword (c-) -@findex c-mark-subword -@findex mark-subword (c-) -@findex c-kill-subword -@findex kill-subword (c-) -@findex c-backward-kill-subword -@findex backward-kill-subword (c-) -@findex c-transpose-subwords -@findex transpose-subwords (c-) -@findex c-capitalize-subword -@findex capitalize-subword (c-) -@findex c-upcase-subword -@findex upcase-subword (c-) -@findex c-downcase-subword -@findex downcase-subword (c-) -@multitable @columnfractions .20 .40 .40 -@c This could be converted to @headitem when we require Texinfo 4.7 -@iftex -@item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command} -@end iftex -@ifnottex -@item Key @tab Word oriented command @tab Subword oriented command -@item ---------------------------------------------------------------------------- -@end ifnottex -@item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword} -@item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword} -@item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword} -@item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword} -@item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword} -@item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords} -@item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword} -@item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword} -@item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword} -@end multitable - -Note that if you have changed the key bindings for the word oriented -commands in your @file{.emacs} or a similar place, the keys you have -configured are also used for the corresponding subword oriented -commands. - -Type @kbd{C-c C-w} to toggle subword mode on and off. To make the -mode turn on automatically, put the following code in your -@file{.emacs}: - -@example -(add-hook 'c-mode-common-hook - (lambda () (subword-mode 1))) -@end example - -As a bonus, you can also use @code{subword-mode} in non-@ccmode{} -buffers by typing @kbd{M-x subword-mode}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Commands, , Subword Movement, Commands -@comment node-name, next, previous, up -@section Other Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here are the various other commands that didn't fit anywhere else: - -@table @asis -@item @kbd{C-c .} (@code{c-set-style}) -@kindex C-c . -@findex c-set-style -@findex set-style (c-) -Switch to the specified style in the current buffer. Use like this: - -@example -@kbd{C-c . @var{style-name} @key{RET}} -@end example - -You can use the @key{TAB} in the normal way to do completion on the -style name. Note that all style names are case insensitive, even the -ones you define yourself. - -Setting a style in this way does @emph{not} automatically reindent your -file. For commands that you can use to view the effect of your changes, -see @ref{Indentation Commands} and @ref{Filling and Breaking}. - -For details of the @ccmode{} style system, see @ref{Styles}. -@item @kbd{C-c :} (@code{c-scope-operator}) -@kindex C-c : -@findex c-scope-operator -@findex scope-operator (c-) -In C++, it is also sometimes desirable to insert the double-colon scope -operator without performing the electric behavior of colon insertion. -@kbd{C-c :} does just this. - -@item @kbd{C-c C-\} (@code{c-backslash-region}) -@kindex C-c C-\ -@findex c-backslash-region -@findex backslash-region (c-) -This function inserts and aligns or deletes end-of-line backslashes in -the current region. These are typically used in multi-line macros. - -With no prefix argument, it inserts any missing backslashes and aligns -them according to the @code{c-backslash-column} and -@code{c-backslash-max-column} variables. With a prefix argument, it -deletes any backslashes. - -The function does not modify blank lines at the start of the region. If -the region ends at the start of a line, it always deletes the backslash -(if any) at the end of the previous line. - -To customize the precise workings of this command, @ref{Custom Macros}. -@end table - -@noindent -The recommended line breaking function, @code{c-context-line-break} -(@pxref{Filling and Breaking}), is especially nice if you edit -multiline macros frequently. When used inside a macro, it -automatically inserts and adjusts the mandatory backslash at the end -of the line to keep the macro together, and it leaves the point at the -right indentation column for the code. Thus you can write code inside -macros almost exactly as you can elsewhere, without having to bother -with the trailing backslashes. - -@table @asis -@item @kbd{C-c C-e} (@code{c-macro-expand}) -@kindex C-c C-e -@findex c-macro-expand -@findex macro-expand (c-) -This command expands C, C++, Objective C or Pike macros in the region, -using an appropriate external preprocessor program. Normally it -displays its output in a temporary buffer, but if you give it a prefix -arg (with @kbd{C-u C-c C-e}) it will overwrite the original region -with the expansion. - -The command does not work in any of the other modes, and the key -sequence is not bound in these other modes. - -@code{c-macro-expand} isn't actually part of @ccmode{}, even though it -is bound to a @ccmode{} key sequence. If you need help setting it up -or have other problems with it, you can either read its source code or -ask for help in the standard (X)Emacs forums. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Font Locking, Config Basics, Commands, Top -@comment node-name, next, previous, up -@chapter Font Locking -@cindex font locking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex Font Lock mode - -@ccmode{} provides font locking for its supported languages by -supplying patterns for use with Font Lock mode. This means that you -get distinct faces on the various syntactic parts such as comments, -strings, keywords and types, which is very helpful in telling them -apart at a glance and discovering syntactic errors. @xref{Font -Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in -@ccmode{} buffers. - -@strong{Please note:} The font locking in AWK mode is currently not -integrated with the rest of @ccmode{}. Only the last section of this -chapter, @ref{AWK Mode Font Locking}, applies to AWK@. The other -sections apply to the other languages. - -@menu -* Font Locking Preliminaries:: -* Faces:: -* Doc Comments:: -* AWK Mode Font Locking:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Font Locking Preliminaries, Faces, Font Locking, Font Locking -@comment node-name, next, previous, up -@section Font Locking Preliminaries -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The font locking for most of the @ccmode{} languages were provided -directly by the Font Lock package prior to version 5.30 of @ccmode{}. -In the transition to @ccmode{} the patterns have been reworked -completely and are applied uniformly across all the languages except AWK -mode, just like the indentation rules (although each language still has -some peculiarities of its own, of course). Since the languages -previously had completely separate font locking patterns, this means -that it's a bit different in most languages now. - -The main goal for the font locking in @ccmode{} is accuracy, to provide -a dependable aid in recognizing the various constructs. Some, like -strings and comments, are easy to recognize while others, like -declarations and types, can be very tricky. @ccmode{} can go to great -lengths to recognize declarations and casts correctly, especially when -the types aren't recognized by standard patterns. This is a fairly -demanding analysis which can be slow on older hardware, and it can -therefore be disabled by choosing a lower decoration level with the -variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,, -emacs, GNU Emacs Manual}). - -@vindex font-lock-maximum-decoration - -The decoration levels are used as follows: - -@enumerate -@comment 1 -@item -Minimal font locking: Fontify only comments, strings and preprocessor -directives (in the languages that use cpp). - -@comment 2 -@item -Fast font locking: In addition to level 1, fontify keywords, simple -types and declarations that are easy to recognize. The variables -@code{*-font-lock-extra-types} (where @samp{*} is the name of the -language) are used to recognize types (see below). Documentation -comments like Javadoc are fontified according to -@code{c-doc-comment-style} (@pxref{Doc Comments}). - -Use this if you think the font locking is too slow. It's the closest -corresponding level to level 3 in the old font lock patterns. - -@comment 3 -@item -Accurate font locking: Like level 2 but uses a different approach that -can recognize types and declarations much more accurately. The -@code{*-font-lock-extra-types} variables are still used, but user -defined types are recognized correctly anyway in most cases. Therefore -those variables should be fairly restrictive and not contain patterns -that are uncertain. - -@cindex Lazy Lock mode -@cindex Just-in-time Lock mode - -This level is designed for fairly modern hardware and a font lock -support mode like Lazy Lock or Just-in-time Lock mode that only -fontifies the parts that are actually shown. Fontifying the whole -buffer at once can easily get bothersomely slow even on contemporary -hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}. -@end enumerate - -@cindex user defined types -@cindex types, user defined - -Since user defined types are hard to recognize you can provide -additional regexps to match those you use: - -@defopt c-font-lock-extra-types -@defoptx c++-font-lock-extra-types -@defoptx objc-font-lock-extra-types -@defoptx java-font-lock-extra-types -@defoptx idl-font-lock-extra-types -@defoptx pike-font-lock-extra-types -For each language there's a variable @code{*-font-lock-extra-types}, -where @samp{*} stands for the language in question. It contains a list -of regexps that matches identifiers that should be recognized as types, -e.g., @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t} -as is customary in C code. Each regexp should not match more than a -single identifier. - -The default values contain regexps for many types in standard runtime -libraries that are otherwise difficult to recognize, and patterns for -standard type naming conventions like the @samp{_t} suffix in C and C++. -Java, Objective-C and Pike have as a convention to start class names -with capitals, so there are patterns for that in those languages. - -Despite the names of these variables, they are not only used for -fontification but in other places as well where @ccmode{} needs to -recognize types. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Faces, Doc Comments, Font Locking Preliminaries, Font Locking -@comment node-name, next, previous, up -@section Faces -@cindex faces -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} attempts to use the standard faces for programming languages -in accordance with their intended purposes as far as possible. No extra -faces are currently provided, with the exception of a replacement face -@code{c-invalid-face} for emacsen that don't provide -@code{font-lock-warning-face}. - -@itemize @bullet -@item -@vindex font-lock-comment-face -Normal comments are fontified in @code{font-lock-comment-face}. - -@item -@vindex font-lock-doc-face -@vindex font-lock-doc-string-face -@vindex font-lock-comment-face -Comments that are recognized as documentation (@pxref{Doc Comments}) -get @code{font-lock-doc-face} (Emacs) or -@code{font-lock-doc-string-face} (XEmacs) if those faces exist. If -they don't then @code{font-lock-comment-face} is used. - -@item -@vindex font-lock-string-face -String and character literals are fontified in -@code{font-lock-string-face}. - -@item -@vindex font-lock-keyword-face -Keywords are fontified with @code{font-lock-keyword-face}. - -@item -@vindex font-lock-function-name-face -@code{font-lock-function-name-face} is used for function names in -declarations and definitions, and classes in those contexts. It's also -used for preprocessor defines with arguments. - -@item -@vindex font-lock-variable-name-face -Variables in declarations and definitions, and other identifiers in such -variable contexts, get @code{font-lock-variable-name-face}. It's also -used for preprocessor defines without arguments. - -@item -@vindex font-lock-constant-face -@vindex font-lock-reference-face -Builtin constants are fontified in @code{font-lock-constant-face} if it -exists, @code{font-lock-reference-face} otherwise. As opposed to the -preceding two faces, this is used on the names in expressions, and it's -not used in declarations, even if there happen to be a @samp{const} in -them somewhere. - -@item -@vindex font-lock-type-face -@code{font-lock-type-face} is put on types (both predefined and user -defined) and classes in type contexts. - -@item -@vindex font-lock-constant-face -@vindex font-lock-reference-face -Label identifiers get @code{font-lock-constant-face} if it exists, -@code{font-lock-reference-face} otherwise. - -@item -Name qualifiers and identifiers for scope constructs are fontified like -labels. - -@item -Special markup inside documentation comments are also fontified like -labels. - -@item -@vindex font-lock-preprocessor-face -@vindex font-lock-builtin-face -@vindex font-lock-reference-face -Preprocessor directives get @code{font-lock-preprocessor-face} if it -exists (i.e., XEmacs). In Emacs they get @code{font-lock-builtin-face} -or @code{font-lock-reference-face}, for lack of a closer equivalent. - -@item -@vindex font-lock-warning-face -@vindex c-invalid-face -@vindex invalid-face (c-) -Some kinds of syntactic errors are fontified with -@code{font-lock-warning-face} in Emacs. In older XEmacs versions -there's no corresponding standard face, so there a special -@code{c-invalid-face} is used, which is defined to stand out sharply by -default. - -Note that it's not used for @samp{#error} or @samp{#warning} directives, -since those aren't syntactic errors in themselves. -@end itemize - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Doc Comments, AWK Mode Font Locking, Faces, Font Locking -@comment node-name, next, previous, up -@section Documentation Comments -@cindex documentation comments -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -There are various tools to supply documentation in the source as -specially structured comments, e.g., the standard Javadoc tool in Java. -@ccmode{} provides an extensible mechanism to fontify such comments and -the special markup inside them. - -@defopt c-doc-comment-style -@vindex doc-comment-style (c-) -This is a style variable that specifies which documentation comment -style to recognize, e.g., @code{javadoc} for Javadoc comments. - -The value may also be a list of styles, in which case all of them are -recognized simultaneously (presumably with markup cues that don't -conflict). - -The value may also be an association list to specify different comment -styles for different languages. The symbol for the major mode is then -looked up in the alist, and the value of that element is interpreted as -above if found. If it isn't found then the symbol `other' is looked up -and its value is used instead. - -The default value for @code{c-doc-comment-style} is -@w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}. - -Note that @ccmode{} uses this variable to set other variables that -handle fontification etc. That's done at mode initialization or when -you switch to a style which sets this variable. Thus, if you change it -in some other way, e.g., interactively in a CC Mode buffer, you will need -to do @kbd{M-x java-mode} (or whatever mode you're currently using) to -reinitialize. - -@findex c-setup-doc-comment-style -@findex setup-doc-comment-style (c-) -Note also that when @ccmode{} starts up, the other variables are -modified before the mode hooks are run. If you change this variable in -a mode hook, you'll have to call @code{c-setup-doc-comment-style} -afterwards to redo that work. -@end defopt - -@ccmode{} currently provides handing of the following doc comment -styles: - -@table @code -@item javadoc -@cindex Javadoc markup -Javadoc comments, the standard tool in Java. - -@item autodoc -@cindex Pike autodoc markup -For Pike autodoc markup, the standard in Pike. - -@item gtkdoc -@cindex GtkDoc markup -For GtkDoc markup, widely used in the Gnome community. -@end table - -The above is by no means complete. If you'd like to see support for -other doc comment styles, please let us know (@pxref{Mailing Lists and -Bug Reports}). - -You can also write your own doc comment fontification support to use -with @code{c-doc-comment-style}: Supply a variable or function -@code{*-font-lock-keywords} where @samp{*} is the name you want to use -in @code{c-doc-comment-style}. If it's a variable, it's prepended to -@code{font-lock-keywords}. If it's a function, it's called at mode -initialization and the result is prepended. For an example, see -@code{javadoc-font-lock-keywords} in @file{cc-fonts.el}. - -If you add support for another doc comment style, please consider -contributing it: send a note to @email{bug-cc-mode@@gnu.org}. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node AWK Mode Font Locking, , Doc Comments, Font Locking -@comment node-name, next, previous, up -@section AWK Mode Font Locking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The general appearance of font-locking in AWK mode is much like in any -other programming mode. @xref{Faces for Font Lock,,,elisp, GNU Emacs -Lisp Reference Manual}. - -The following faces are, however, used in a non-standard fashion in -AWK mode: - -@table @asis -@item @code{font-lock-variable-name-face} -This face was intended for variable declarations. Since variables are -not declared in AWK, this face is used instead for AWK system -variables (such as @code{NF}) and ``Special File Names'' (such as -@code{"/dev/stderr"}). - -@item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs) -This face is normally used for preprocessor directives in @ccmode{}. -There are no such things in AWK, so this face is used instead for -standard functions (such as @code{match}). - -@item @code{font-lock-string-face} -As well as being used for strings, including localizable strings, -(delimited by @samp{"} and @samp{_"}), this face is also used for AWK -regular expressions (delimited by @samp{/}). - -@item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs) -This face highlights the following syntactically invalid AWK -constructs: - -@itemize @bullet -@item -An unterminated string or regular expression. Here the opening -delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in -@code{font-lock-warning-face}. This is most noticeable when typing in a -new string/regular expression into a buffer, when the warning-face -serves as a continual reminder to terminate the construct. - -AWK mode fontifies unterminated strings/regular expressions -differently from other modes: Only the text up to the end of the line -is fontified as a string (escaped newlines being handled correctly), -rather than the text up to the next string quote. - -@item -A space between the function name and opening parenthesis when calling -a user function. The last character of the function name and the -opening parenthesis are highlighted. This font-locking rule will -spuriously highlight a valid concatenation expression where an -identifier precedes a parenthesized expression. Unfortunately. - -@item -Whitespace following the @samp{\} in what otherwise looks like an -escaped newline. The @samp{\} is highlighted. -@end itemize -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Config Basics, Custom Filling and Breaking, Font Locking, Top -@comment node-name, next, previous, up -@chapter Configuration Basics -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex Emacs Initialization File -@cindex Configuration -You configure @ccmode{} by setting Lisp variables and calling (and -perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't -difficult.}, which is usually done by adding code to an Emacs -initialization file. This file might be @file{site-start.el} or -@file{.emacs} or @file{init.el} or @file{default.el} or perhaps some -other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For -the sake of conciseness, we just call this file ``your @file{.emacs}'' -throughout the rest of the manual. - -Several of these variables (currently 16), are known collectively as -@dfn{style variables}. @ccmode{} provides a special mechanism, known -as @dfn{styles} to make it easier to set these variables as a group, -to ``inherit'' settings from one style into another, and so on. Style -variables remain ordinary Lisp variables, whose values can be read and -changed independently of the style system. @xref{Style Variables}. - -There are several ways you can write the code, depending on the -precise effect you want---they are described further down on this page. -If you are new to @ccmode{}, we suggest you begin with the simplest -method, ``Top-level commands or the customization interface''. - -If you make conflicting settings in several of these ways, the way -that takes precedence is the one that appears latest in this list: -@itemize @w{} -@item -@table @asis -@item Style -@itemx File Style@footnote{In earlier versions of @ccmode{}, a File Style setting took precedence over any other setting apart from a File Local Variable setting.} -@itemx Top-level command or ``customization interface'' -@itemx Hook -@itemx File Local Variable setting -@end table -@end itemize - -Here is a summary of the different ways of writing your configuration -settings: - -@table @asis -@item Top-level commands or the ``customization interface'' -Most simply, you can write @code{setq} and similar commands at the top -level of your @file{.emacs} file. When you load a @ccmode{} buffer, -it initializes its configuration from these global values (at least, -for those settings you have given values to), so it makes sense to -have these @code{setq} commands run @emph{before} @ccmode{} is first -initialized---in particular, before any call to @code{desktop-read} -(@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For -example, you might set c-basic-offset thus: - -@example -(setq c-basic-offset 4) -@end example - -You can use the more user friendly Customization interface instead, -but this manual does not cover in detail how that works. To do this, -start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}. -@xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}. -@c The following note really belongs in the Emacs manual. -Emacs normally writes the customizations at the end of your -@file{.emacs} file. If you use @code{desktop-read}, you should edit -your @file{.emacs} to place the call to @code{desktop-read} @emph{after} -the customizations. - -The first initialization of @ccmode{} puts a snapshot of the -configuration settings into the special style @code{user}. -@xref{Built-in Styles}. - -For basic use of Emacs, either of these ways of configuring is -adequate. However, the settings are then the same in all @ccmode{} -buffers and it can be clumsy to communicate them between programmers. -For more flexibility, you'll want to use one (or both) of @ccmode{}'s -more sophisticated facilities, hooks and styles. - -@item Hooks -An Emacs @dfn{hook} is a place to put Lisp functions that you want -Emacs to execute later in specific circumstances. -@xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main -hook and a language-specific hook for each language it supports; any -functions you put onto these hooks get executed as the last part of a -buffer's initialization. Typically you put most of your customization -within the main hook, and use the language-specific hooks to vary the -customization settings between language modes. For example, if you -wanted different (non-standard) values of @code{c-basic-offset} in C -Mode and Java Mode buffers, you could do it like this: - -@example -@group -(defun my-c-mode-hook () - (setq c-basic-offset 3)) -(add-hook 'c-mode-hook 'my-c-mode-hook) - -(defun my-java-mode-hook () - (setq c-basic-offset 6)) -(add-hook 'java-mode-hook 'my-java-mode-hook) -@end group -@end example - -See @ref{CC Hooks} for more details on the use of @ccmode{} hooks. - -@item Styles -A @ccmode{} @dfn{style} is a coherent collection of customizations -with a name. At any time, exactly one style is active in each -@ccmode{} buffer, either the one you have selected or a default. -@ccmode{} is delivered with several existing styles. Additionally, -you can create your own styles, possibly based on these existing -styles. If you worked in a programming team called the ``Free -Group'', which had its own coding standards, you might well have this -in your @file{.emacs} file: - -@example -(setq c-default-style '((java-mode . "java") - (awk-mode . "awk") - (other . "free-group-style"))) -@end example - -See @ref{Styles} for fuller details on using @ccmode{} styles and how -to create them. - -@item File Local Variable setting -A @dfn{file local variable setting} is a setting which applies to an -individual source file. You put this in a @dfn{local variables list}, -a special block at the end of the source file (@pxref{Specifying File -Variables,,,@emacsman{}}). - -@item File Styles -A @dfn{file style} is a rarely used variant of the ``style'' mechanism -described above, which applies to an individual source file. -@xref{File Styles}. You use this by setting certain special variables -in a local variables list (@pxref{Specifying File -Variables,,,@emacsman{}}). - -@item Hooks with Styles -For ultimate flexibility, you can use hooks and styles together. For -example, if your team were developing a product which required a -Linux driver, you'd probably want to use the ``linux'' style for the -driver, and your own team's style for the rest of the code. You -could achieve this with code like this in your @file{.emacs}: - -@example -@group -(defun my-c-mode-hook () - (c-set-style - (if (and (buffer-file-name) - (string-match "/usr/src/linux" (buffer-file-name))) - "linux" - "free-group-style"))) -(add-hook 'c-mode-hook 'my-c-mode-hook) -@end group -@end example - -In a programming team, a hook is a also a good place for each member -to put his own personal preferences. For example, you might be the -only person in your team who likes Auto-newline minor mode. You could -have it enabled by default by placing the following in your -@file{.emacs}: - -@example -@group -(defun my-turn-on-auto-newline () - (c-toggle-auto-newline 1)) -(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline) -@end group -@end example -@end table - -@menu -* CC Hooks:: -* Style Variables:: -* Styles:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node CC Hooks, Style Variables, Config Basics, Config Basics -@comment node-name, next, previous, up -@section Hooks -@cindex mode hooks -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@c The node name is "CC Hooks" rather than "Hooks" because of a bug in -@c some older versions of Info, e.g., the info.el in GNU Emacs 21.3. -@c If you go to "Config Basics" and hit on the xref to "CC -@c Hooks" the function Info-follow-reference searches for "*Note: CC -@c Hooks" from the beginning of the page. If this node were instead -@c named "Hooks", that search would spuriously find "*Note: -@c Hooks(elisp)" and go to the wrong node. - -@ccmode{} provides several hooks that you can use to customize the -mode for your coding style. The main hook is -@code{c-mode-common-hook}; typically, you'll put the bulk of your -customizations here. In addition, each language mode has its own -hook, allowing you to fine tune your settings individually for the -different @ccmode{} languages, and there is a package initialization -hook. Finally, there is @code{c-special-indent-hook}, which enables -you to solve anomalous indentation problems. It is described in -@ref{Other Indentation}, not here. All these hooks adhere to the -standard Emacs conventions. - -When you open a buffer, @ccmode{} first initializes it with the -currently active style (@pxref{Styles}). Then it calls -@code{c-mode-common-hook}, and finally it calls the language-specific -hook. Thus, any style settings done in these hooks will override -those set by @code{c-default-style}. - -@defvar c-initialization-hook -@vindex initialization-hook (c-) -Hook run only once per Emacs session, when @ccmode{} is initialized. -This is a good place to change key bindings (or add new ones) in any -of the @ccmode{} key maps. @xref{Sample Init File}. -@end defvar - -@defvar c-mode-common-hook -@vindex mode-common-hook (c-) -Common hook across all languages. It's run immediately before the -language specific hook. -@end defvar - -@defvar c-mode-hook -@defvarx c++-mode-hook -@defvarx objc-mode-hook -@defvarx java-mode-hook -@defvarx idl-mode-hook -@defvarx pike-mode-hook -@defvarx awk-mode-hook -The language specific mode hooks. The appropriate one is run as the -last thing when you enter that language mode. -@end defvar - -Although these hooks are variables defined in @ccmode{}, you can give -them values before @ccmode{}'s code is loaded---indeed, this is the -only way to use @code{c-initialization-hook}. Their values aren't -overwritten when @ccmode{} gets loaded. - -Here's a simplified example of what you can add to your @file{.emacs} -file to do things whenever any @ccmode{} language is edited. See the -Emacs manuals for more information on customizing Emacs via hooks. -@xref{Sample Init File}, for a more complete sample @file{.emacs} -file. - -@example -(defun my-c-mode-common-hook () - ;; my customizations for all of c-mode and related modes - (no-case-fold-search) - ) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end example - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Style Variables, Styles, CC Hooks, Config Basics -@comment node-name, next, previous, up -@section Style Variables -@cindex styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex style variables -The variables that @ccmode{}'s style system control are called -@dfn{style variables}. Note that style variables are ordinary Lisp -variables, which the style system initializes; you can change their -values at any time (e.g., in a hook function). The style system can -also set other variables, to some extent. @xref{Styles}. - -@dfn{Style variables} are handled specially in several ways: - -@itemize @bullet -@item -Style variables are by default buffer-local variables. However, they -can instead be made global by setting -@code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is -initialized. - -@item -@vindex c-old-style-variable-behavior -@vindex old-style-variable-behavior (c-) -The default global binding of any style variable (with two exceptions -- see below) is the special symbol @code{set-from-style}. When the -style system initializes a buffer-local copy of a style variable for a -@ccmode{} buffer, if its global binding is still that symbol then it -will be set from the current style. Otherwise it will retain its -global default@footnote{This is a big change from versions of -@ccmode{} earlier than 5.26, where such settings would get overridden -by the style system unless special precautions were taken. That was -changed since it was counterintuitive and confusing, especially to -novice users. If your configuration depends on the old overriding -behavior, you can set the variable -@code{c-old-style-variable-behavior} to non-@code{nil}.}. This -``otherwise'' happens, for example, when you've set the variable with -@code{setq} at the top level of your @file{.emacs} (@pxref{Config -Basics}). - -@item -The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is -an association list with an element for each syntactic symbol. It's -handled a little differently from the other style variables. It's -default global binding is the empty list @code{nil}, rather than -@code{set-from-style}. Before the style system is initialized, you -can add individual elements to @code{c-offsets-alist} by calling -@code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set -other style variables with @code{setq}. Those elements will then -prevail when the style system later initializes a buffer-local copy of -@code{c-offsets-alist}. - -@item -The style variable @code{c-special-indent-hook} is also handled in a -special way. Styles can only add functions to this hook, not remove -them, so any global settings you put on it are always -preserved@footnote{This did not change in version 5.26.}. The value -you give this variable in a style definition can be either a function -or a list of functions. - -@item -The global bindings of the style variables get captured in the special -@code{user} style when the style system is first initialized. -@xref{Built-in Styles}, for details. -@end itemize - -The style variables are:@* -@code{c-indent-comment-alist}, -@code{c-indent-comments-syntactically-p} (@pxref{Indentation -Commands});@* -@code{c-doc-comment-style} (@pxref{Doc Comments});@* -@code{c-block-comment-prefix}, @code{c-comment-prefix-regexp} -(@pxref{Custom Filling and Breaking});@* -@code{c-hanging-braces-alist} (@pxref{Hanging Braces});@* -@code{c-hanging-colons-alist} (@pxref{Hanging Colons});@* -@code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and -Commas});@* -@code{c-cleanup-list} (@pxref{Clean-ups});@* -@code{c-basic-offset} (@pxref{Customizing Indentation});@* -@code{c-offsets-alist} (@pxref{c-offsets-alist});@* -@code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@* -@code{c-special-indent-hook}, @code{c-label-minimum-indentation} -(@pxref{Other Indentation});@* -@code{c-backslash-column}, @code{c-backslash-max-column} -(@pxref{Custom Macros}). - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Styles, , Style Variables, Config Basics -@comment node-name, next, previous, up -@section Styles -@cindex styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -By @dfn{style} we mean the layout of the code---things like how many -columns to indent a block of code, whether an opening brace gets -indented to the level of the code it encloses, or of the construct -that introduces it, or ``hangs'' at the end of a line. - -Most people only need to edit code formatted in just a few well-defined -and consistent styles. For example, their organization might impose a -``blessed'' style that all its programmers must conform to. Similarly, -people who work on GNU software will have to use the GNU coding style. -Some shops are more lenient, allowing a variety of coding styles, and as -programmers come and go, there could be a number of styles in use. For -this reason, @ccmode{} makes it convenient for you to set up logical -groupings of customizations called @dfn{styles}, associate a single name -for any particular style, and pretty easily start editing new or -existing code using these styles. - -As an alternative to writing a style definition yourself, you can have -@ccmode{} @dfn{guess} (at least part of) your style by looking at an -already formatted piece of your code, @ref{Guessing the Style}. - -@menu -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* Guessing the Style:: -* File Styles:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Built-in Styles, Choosing a Style, Styles, Styles -@comment node-name, next, previous, up -@subsection Built-in Styles -@cindex styles, built-in -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you're lucky, one of @ccmode{}'s built-in styles might be just -what you're looking for. These are: - -@table @code -@item gnu -@cindex GNU style -Coding style blessed by the Free Software Foundation -for C code in GNU programs. - -@item k&r -@cindex K&R style -The classic Kernighan and Ritchie style for C code. - -@item bsd -@cindex BSD style -Also known as ``Allman style'' after Eric Allman. - -@item whitesmith -@cindex Whitesmith style -Popularized by the examples that came with Whitesmiths C, an early -commercial C compiler. - -@item stroustrup -@cindex Stroustrup style -The classic Stroustrup style for C++ code. - -@item ellemtel -@cindex Ellemtel style -Popular C++ coding standards as defined by ``Programming in C++, Rules -and Recommendations,'' Erik Nyquist and Mats Henricson, -Ellemtel@footnote{This document is available at -@uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other -places.}. -@c N.B. This URL was still valid at 2005/8/28 (ACM). - -@item linux -@cindex Linux style -C coding standard for Linux (the kernel). - -@item python -@cindex Python style -C coding standard for Python extension modules@footnote{Python is a -high level scripting language with a C/C++ foreign function interface. -For more information, see @uref{http://www.python.org/}.}. - -@item java -@cindex Java style -The style for editing Java code. Note that the default -value for @code{c-default-style} installs this style when you enter -@code{java-mode}. - -@item awk -@cindex AWK style -The style for editing AWK code. Note that the default value for -@code{c-default-style} installs this style when you enter -@code{awk-mode}. - -@item user -@cindex User style -This is a special style created by you. It consists of the factory -defaults for all the style variables as modified by the customizations -you do either with the Customization interface or by writing -@code{setq}s and @code{c-set-offset}s at the top level of your -@file{.emacs} file (@pxref{Config Basics}). The style system creates -this style as part of its initialization and doesn't modify it -afterwards. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Choosing a Style, Adding Styles, Built-in Styles, Styles -@comment node-name, next, previous, up -@subsection Choosing a Style -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -When you create a new buffer, its style will be set from -@code{c-default-style}. The factory default is the style @code{gnu}, -except in Java and AWK modes where it's @code{java} and @code{awk}. - -Remember that if you set a style variable with the Customization -interface or at the top level of your @file{.emacs} file before the -style system is initialized (@pxref{Config Basics}), this setting will -override the one that the style system would have given the variable. - -To set a buffer's style interactively, use the command @kbd{C-c .} -(@pxref{Other Commands}). To set it from a file's local variable -list, @ref{File Styles}. - -@defopt c-default-style -@vindex default-style (c-) -This variable specifies which style to install by default in new -buffers. It takes either a style name string, or an association list -of major mode symbols to style names: - -@enumerate -@item -When @code{c-default-style} is a string, it must be an existing style -name. This style is then used for all modes. - -@item -When @code{c-default-style} is an association list, the mode language -is looked up to find a style name string. - -@item -If @code{c-default-style} is an association list where the mode -language mode isn't found then the special symbol @samp{other} is -looked up. If it's found then the associated style is used. - -@item -If @samp{other} is not found then the @samp{gnu} style is used. -@end enumerate - -In all cases, the style described in @code{c-default-style} is installed -@emph{before} the language hooks are run, so you can always override -this setting by including an explicit call to @code{c-set-style} in your -language mode hook, or in @code{c-mode-common-hook}. - -The standard value of @code{c-default-style} is @w{@code{((java-mode -. "java") (awk-mode . "awk") (other . "gnu"))}}. -@end defopt - -@defvar c-indentation-style -@vindex indentation-style (c-) -This variable always contains the buffer's current style name, as a -string. -@end defvar - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Adding Styles, Guessing the Style, Choosing a Style, Styles -@comment node-name, next, previous, up -@subsection Adding and Amending Styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If none of the built-in styles is appropriate, you'll probably want to -create a new @dfn{style definition}, possibly based on an existing -style. To do this, put the new style's settings into a list with the -following format; the list can then be passed as an argument to the -function @code{c-add-style}. You can see an example of a style -definition in @ref{Sample Init File}. - -@cindex style definition -@c @defvr {List} style definition -@table @asis -@item Structure of a Style Definition List -([@var{base-style}] [(@var{variable} . @var{value}) @dots{}]) - -Optional @var{base-style}, if present, must be a string which is the -name of the @dfn{base style} from which this style inherits. At most -one @var{base-style} is allowed in a style definition. If -@var{base-style} is not specified, the style inherits from the table -of factory default values@footnote{This table is stored internally in -the variable c-fallback-style.} instead. All styles eventually -inherit from this internal table. Style loops generate errors. The -list of pre-existing styles can be seen in @ref{Built-in Styles}. - -The dotted pairs (@var{variable} . @var{value}) each consist of a -variable and the value it is to be set to when the style is later -activated.@footnote{Note that if the variable has been given a value -by the Customization interface or a @code{setq} at the top level of -your @file{.emacs}, this value will override the one the style system -tries to give it. @xref{Config Basics}.} The variable can be either a -@ccmode{} style variable or an arbitrary Emacs variable. In the -latter case, it is @emph{not} made buffer-local by the @ccmode{} style -system. -@c @end defvr - -Two variables are treated specially in the dotted pair list: - -@table @code -@item c-offsets-alist -The value is in turn a list of dotted pairs of the form - -@example -(@r{@var{syntactic-symbol}} . @r{@var{offset}}) -@end example - -as described in @ref{c-offsets-alist}. These are passed to -@code{c-set-offset} so there is no need to set every syntactic symbol -in your style, only those that are different from the inherited style. - -@item c-special-indent-hook -The value is added to @code{c-special-indent-hook} using -@code{add-hook}, so any functions already on it are kept. If the value -is a list, each element of the list is added with @code{add-hook}. -@end table -@end table - -Styles are kept in the @code{c-style-alist} variable, but you -should never modify this variable directly. Instead, @ccmode{} -provides the function @code{c-add-style} for this purpose. - -@defun c-add-style stylename description &optional set-p -@findex add-style (c-) -Add or update a style called @var{stylename}, a string. -@var{description} is the new style definition in the form described -above. If @var{stylename} already exists in @code{c-style-alist} then -it is replaced by @var{description}. (Note, this replacement is -total. The old style is @emph{not} merged into the new one.) -Otherwise, a new style is added. - -If the optional @var{set-p} is non-@code{nil} then the new style is -applied to the current buffer as well. The use of this facility is -deprecated and it might be removed from @ccmode{} in a future release. -You should use @code{c-set-style} instead. - -The sample @file{.emacs} file provides a concrete example of how a new -style can be added and automatically set. @xref{Sample Init File}. -@end defun - -@defvar c-style-alist -@vindex style-alist (c-) -This is the variable that holds the definitions for the styles. It -should not be changed directly; use @code{c-add-style} instead. -@end defvar - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Guessing the Style, File Styles, Adding Styles, Styles -@comment node-name, next, previous, up -@subsection Guessing the Style -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Instead of specifying a style, you can get @ccmode{} to @dfn{guess} -your style by examining an already formatted code buffer. @ccmode{} -then determines the ''most frequent'' offset (@pxref{c-offsets-alist}) -for each of the syntactic symbols (@pxref{Indentation Engine Basics}) -encountered in the buffer, and the ''most frequent'' value of -c-basic-offset (@pxref{Customizing Indentation}), then merges the -current style with these ''guesses'' to form a new style. This -combined style is known as the @dfn{guessed style}. - -To do this, call @code{c-guess} (or one of the other 5 guessing -commands) on your sample buffer. The analysis of your code may take -some time. - -You can then set the guessed style in any @ccmode{} buffer with -@code{c-guess-install}. You can display the style with -@code{c-guess-view}, and preserve it by copying it into your -@file{.emacs} for future use, preferably after editing it. - -@table @asis -@item @kbd{M-x c-guess-no-install} -@itemx @kbd{M-x c-guess-buffer-no-install} -@itemx @kbd{M-x c-guess-region-no-install} -@findex c-guess-no-install -@findex c-guess-buffer-no-install -@findex c-guess-region-no-install -@findex guess-no-install (c-) -@findex guess-buffer-no-install (c-) -@findex guess-region-no-install (c-) -These commands analyze a part of the current buffer and guess the -style from it. - -The part of the buffer examined is either the region -(@code{c-guess-region-no-install}), the entire buffer -(@code{c-guess-buffer-no-install}), or the first -@code{c-guess-region-max} bytes (@code{c-guess-no-install}). - -Each of these commands can be given an optional prefix argument. This -instructs @ccmode{} to combine the new guesses with the current -guesses before forming the guessed style. -@end table - -@table @asis -@item @kbd{M-x c-guess} -@itemx @kbd{M-x c-guess-buffer} -@itemx @kbd{M-x c-guess-region} -@findex c-guess -@findex c-guess-buffer -@findex c-guess-region -@findex guess (c-) -@findex guess-buffer (c-) -@findex guess-region (c-) -These commands analyze a part of the current buffer, guess the style -from it, then install the guessed style on the buffer. The guessed -style is given a name based on the buffer's absolute file name, and -you can then set this style on any @ccmode{} buffer with @kbd{C-c .}. - -The part of the buffer examined is either the region -(@code{c-guess-region}), the entire buffer (@code{c-guess-buffer}), or -the first @code{c-guess-region-max} bytes (@code{c-guess}). - -Each of these commands can be given an optional prefix argument. This -instructs @ccmode{} to combine the new guesses with the current -guesses before forming the guessed style. -@end table - -@defopt c-guess-region-max -@vindex guess-region-max (c-) -This variable, default 50000, is the size in bytes of the buffer -portion examined by c-guess and c-guess-no-install. If set to -@code{nil}, the entire buffer is examined. -@end defopt - -@defopt c-guess-offset-threshold -@vindex guess-offset-threshold (c-) -This variable, default 10, is the maximum offset, either outwards or -inwards, which will be taken into account by the analysis process. -Any offset bigger than this will be ignored. For no limit, set this -variable to a large number. -@end defopt - -@table @asis -@item @kbd{M-x c-guess-install} -@findex c-guess-install -@findex guess-install (c-) - -Set the current buffer's style to the guessed style. This prompts you -to enter an optional new style name to give to the guessed style. By -default, this name is based on the buffer's absolute file name. You -can then use this style like any other. - -@item @kbd{M-x c-guess-view} -@findex c-guess-view -@findex guess-view (c-) -Display the most recently guessed style in a temporary buffer. This -display is in the form of a @code{c-add-style} form (@pxref{Adding -Styles}) which can be easily copied to your @file{.emacs}. You will -probably want to edit it first. - -The display of the guessed style contains these elements: - -@table @asis -@item Placeholder Name -You should replace this with a style name of your own. -@item Parent Style -The style current when the guessing began, from which the guessed -style inherits (@pxref{Config Basics}) the settings which weren't -guessed. -@item Guessed Offsets -These are the core result of the guessing process. Each of them is -marked by a comment. -@item Inherited Offsets -These are syntactic offsets which have been taken over from the parent -style. To avoid possible future conflicts, you should remove either -these offsets or the parent style name. -@end table -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node File Styles, , Guessing the Style, Styles -@comment node-name, next, previous, up -@subsection File Styles -@cindex styles, file local -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex file local variables - -The Emacs manual describes how you can customize certain variables on a -per-file basis by including a @dfn{file local variable} block at the end -of the file (@pxref{File Variables,, Local Variables in Files,@emacsman{}, -@emacsmantitle{}}). - -So far, you've only seen a functional interface for setting styles in -@ccmode{}, and this can't be used here. @ccmode{} fills the gap by -providing two variables for use in a file's local variable list. -Don't use them anywhere else! These allow you to customize the style -on a per-file basis: - -@defvar c-file-style -@vindex file-style (c-) -Set this variable to a style name string in the Local Variables list. -From now on, when you visit the file, @ccmode{} will automatically set -the file's style to this one using @code{c-set-style}. -@end defvar - -@defvar c-file-offsets -@vindex file-offsets (c-) -Set this variable (in the Local Variables list) to an association list -of the same format as @code{c-offsets-alist}. From now on, when you -visit the file, @ccmode{} will automatically institute these offsets -using @code{c-set-offset}. -@end defvar - -Note that file style settings (i.e., @code{c-file-style}) are applied -before file offset settings -(i.e., @code{c-file-offsets})@footnote{Also, if either of these are set -in a file's local variable section, all the style variable values are -made local to that buffer, even if -@code{c-style-variables-are-local-p} is @code{nil}. Since this -variable is virtually always non-@code{nil} anyhow, you're unlikely to -notice this effect.}. - -If you set any variable by the file local variables mechanism, that -setting takes priority over all other settings, even those in your -mode hooks (@pxref{CC Hooks}). Any individual setting of a variable -will override one made through @code{c-file-style} or -@code{c-file-offsets}. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top -@comment node-name, next, previous, up -@chapter Customizing Filling and Line Breaking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since there's a lot of normal text in comments and string literals, -@ccmode{} provides features to edit these like in text mode. It does -this by hooking in on the different line breaking functions and tuning -relevant variables as necessary. - -@vindex c-comment-prefix-regexp -@vindex comment-prefix-regexp (c-) -@cindex comment line prefix -@vindex comment-start -@vindex comment-end -@vindex comment-start-skip -@vindex paragraph-start -@vindex paragraph-separate -@vindex paragraph-ignore-fill-prefix -@vindex adaptive-fill-mode -@vindex adaptive-fill-regexp -@vindex adaptive-fill-first-line-regexp -To make Emacs recognize comments and treat text in them as normal -paragraphs, @ccmode{} makes several standard -variables@footnote{@code{comment-start}, @code{comment-end}, -@code{comment-start-skip}, @code{paragraph-start}, -@code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, -@code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and -@code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them -according to the language syntax and the comment line prefix. - -@defopt c-comment-prefix-regexp -@vindex comment-prefix-regexp (c-) -This style variable contains the regexp used to recognize the -@dfn{comment line prefix}, which is the line decoration that starts -every line in a comment. The variable is either the comment line -prefix itself, or (more usually) an association list with different -values for different languages. The symbol for the major mode is -looked up in the alist to get the regexp for the language, and if it -isn't found then the special symbol @samp{other} is looked up instead. - -When a comment line gets divided by @kbd{M-j} or the like, @ccmode{} -inserts the comment line prefix from a neighboring line at the start -of the new line. The default value of c-comment-prefix-regexp is -@samp{//+\\|\\**}, which matches C++ style line comments like - -@example -// blah blah -@end example - -@noindent -with two or more slashes in front of them, and the second and -subsequent lines of C style block comments like - -@example -@group -/* - * blah blah - */ -@end group -@end example - -@noindent -with zero or more stars at the beginning of every line. If you change -this variable, please make sure it still matches the comment starter -(i.e., @code{//}) of line comments @emph{and} the line prefix inside -block comments. - -@findex c-setup-paragraph-variables -@findex setup-paragraph-variables (c-) -Also note that since @ccmode{} uses the value of -@code{c-comment-prefix-regexp} to set up several other variables at -mode initialization, there won't be any effect if you just change it -inside a @ccmode{} buffer. You need to call the command -@code{c-setup-paragraph-variables} too, to update those other -variables. That's also the case if you modify -@code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will -already have set up these variables before calling the hook. -@end defopt - -In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt -the line prefix from the other lines in the comment. - -@vindex adaptive-fill-mode -@cindex Adaptive Fill mode -@ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU -Emacs Manual}) to make Emacs correctly keep the line prefix when -filling paragraphs. That also makes Emacs preserve the text -indentation @emph{inside} the comment line prefix. E.g., in the -following comment, both paragraphs will be filled with the left -margins of the texts kept intact: - -@example -@group -/* Make a balanced b-tree of the nodes in the incoming - * stream. But, to quote the famous words of Donald E. - * Knuth, - * - * Beware of bugs in the above code; I have only - * proved it correct, not tried it. - */ -@end group -@end example - -@findex c-setup-filladapt -@findex setup-filladapt (c-) -@findex filladapt-mode -@vindex filladapt-mode -@cindex Filladapt mode -It's also possible to use other adaptive filling packages, notably Kyle -E. Jones' Filladapt package@footnote{It's available from -@uref{http://www.wonderworks.com/}. As of version 2.12, it does however -lack a feature that makes it work suboptimally when -@code{c-comment-prefix-regexp} matches the empty string (which it does -by default). A patch for that is available from -@uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.}, -@c 2005/11/22: The above is still believed to be the case. -which handles things like bulleted lists nicely. There's a convenience -function @code{c-setup-filladapt} that tunes the relevant variables in -Filladapt for use in @ccmode{}. Call it from a mode hook, e.g., with -something like this in your @file{.emacs}: - -@example -(defun my-c-mode-common-hook () - (c-setup-filladapt) - (filladapt-mode 1)) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end example - -@defopt c-block-comment-prefix -@vindex block-comment-prefix (c-) -@vindex c-comment-continuation-stars -@vindex comment-continuation-stars (c-) -Normally the comment line prefix inserted for a new line inside a -comment is deduced from other lines in it. However there's one -situation when there's no hint about what the prefix should look like, -namely when a block comment is broken for the first time. This style -variable@footnote{In versions before 5.26, this variable was called -@code{c-comment-continuation-stars}. As a compatibility measure, -@ccmode{} still uses the value on that variable if it's set.} is used -then as the comment prefix. It defaults to @samp{* -}@footnote{Actually, this default setting of -@code{c-block-comment-prefix} typically gets overridden by the default -style @code{gnu}, which sets it to blank. You can see the line -splitting effect described here by setting a different style, -e.g., @code{k&r} @xref{Choosing a Style}.}, which makes a comment - -@example -/* Got O(n^2) here, which is a Bad Thing. */ -@end example - -@noindent -break into - -@example -@group -/* Got O(n^2) here, which - * is a Bad Thing. */ -@end group -@end example - -Note that it won't work to adjust the indentation by putting leading -spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the -normal indentation engine to indent the line. Thus, the right way to -fix the indentation is by customizing the @code{c} syntactic symbol. It -defaults to @code{c-lineup-C-comments}, which handles the indentation of -most common comment styles, see @ref{Line-Up Functions}. -@end defopt - -@defopt c-ignore-auto-fill -@vindex ignore-auto-fill (c-) -When auto fill mode is enabled, @ccmode{} can selectively ignore it -depending on the context the line break would occur in, e.g., to never -break a line automatically inside a string literal. This variable -takes a list of symbols for the different contexts where auto-filling -never should occur: - -@table @code -@item string -Inside a string or character literal. -@item c -Inside a C style block comment. -@item c++ -Inside a C++ style line comment. -@item cpp -Inside a preprocessor directive. -@item code -Anywhere else, i.e., in normal code. -@end table - -By default, @code{c-ignore-auto-fill} is set to @code{(string cpp -code)}, which means that when auto-fill mode is activated, -auto-filling only occurs in comments. In literals, it's often -desirable to have explicit control over newlines. In preprocessor -directives, the necessary @samp{\} escape character before the newline -is not automatically inserted, so an automatic line break would -produce invalid code. In normal code, line breaks are normally -dictated by some logical structure in the code rather than the last -whitespace character, so automatic line breaks there will produce poor -results in the current implementation. -@end defopt - -@vindex comment-multi-line -If inside a comment and @code{comment-multi-line} (@pxref{Auto -Fill,,,@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the -indentation and -line prefix are preserved. If inside a comment and -@code{comment-multi-line} is @code{nil}, a new comment of the same -type is started on the next line and indented as appropriate for -comments. - -Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at -startup. The reason is that @kbd{M-j} could otherwise produce sequences -of single line block comments for texts that should logically be treated -as one comment, and the rest of the paragraph handling code -(e.g., @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to -inconsistent behavior. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top -@comment node-name, next, previous, up -@chapter Customizing Auto-newlines -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} determines whether to insert auto-newlines in two basically -different ways, depending on the character just typed: - -@table @asis -@item Braces and Colons -@ccmode{} first determines the syntactic context of the brace or colon -(@pxref{Syntactic Symbols}), then looks for a corresponding element in -an alist. This element specifies where to put newlines: this is any -combination of before and after the brace or colon. If no alist -element is found, newlines are inserted both before and after a brace, -but none are inserted around a colon. See @ref{Hanging Braces} and -@ref{Hanging Colons}. - -@item Semicolons and Commas -The variable @code{c-hanging-semi&comma-criteria} contains a list of -functions which determine whether to insert a newline after a newly -typed semicolon or comma. @xref{Hanging Semicolons and Commas}. -@end table - -The names of these configuration variables contain @samp{hanging} -because they let you @dfn{hang} the pertinent characters. A character -which introduces a C construct is said to @dfn{hang on the right} when -it appears at the end of a line after other code, being separated by a -line break from the construct it introduces, like the opening brace in: - -@example -@group -while (i < MAX) @{ - total += entry[i]; - entry [i++] = 0; -@} -@end group -@end example - -@noindent -A character @dfn{hangs on the left} when it appears at the start of -the line after the construct it closes off, like the above closing -brace. - -The next chapter, ``Clean-ups'', describes how to configure @ccmode{} -to remove these automatically added newlines in certain specific -circumstances. @xref{Clean-ups}. - -@menu -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semicolons and Commas:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Braces -@cindex hanging braces -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -To specify which kinds of braces you want auto-newlines put around, -you set the style variable @code{c-hanging-braces-alist}. Its -structure and semantics are described in this section. Details of how -to set it up, and its relationship to CC Mode's style system are given -in @ref{Style Variables}. - -Say you wanted an auto-newline after (but not before) the following -@samp{@{}: - -@example -if (foo < 17) @{ -@end example - -@noindent -First you need to find the @dfn{syntactic context} of the brace---type -a @key{RET} before the brace to get it on a line of its -own@footnote{Also insert a @samp{\} at the end of the previous line if -you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you -something like: - -@example -((substatement-open 1061)) -@end example - -@noindent -So here you need to put the entry @code{(substatement-open . (after))} -into @code{c-hanging-braces-alist}. - -If you don't want any auto-newlines for a particular syntactic symbol, -put this into @code{c-hanging-braces-alist}: - -@example -(brace-entry-open) -@end example - -If some brace syntactic symbol is not in @code{c-hanging-brace-alist}, -its entry is taken by default as @code{(before after)}---insert a -newline both before and after the brace. In place of a -``before/after'' list you can specify a function in this alist---this -is useful when the auto newlines depend on the code around the brace. - -@defopt c-hanging-braces-alist -@vindex hanging-braces-alist (c-) - -This variable is an association list which maps syntactic symbols to -lists of places to insert a newline. @xref{Association -Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the -syntactic symbol, the associated value is either @code{nil}, a list, -or a function. - -@table @asis -@item The Key: the syntactic symbol -The syntactic symbols that are useful as keys in this list are -@code{brace-list-intro}, @code{statement-cont}, -@code{inexpr-class-open}, @code{inexpr-class-close}, and all the -@code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols}, -for a more detailed description of these syntactic symbols, except for -@code{inexpr-class-open} and @code{inexpr-class-close}, which aren't -actual syntactic symbols. Elements with any other value as a key get -ignored. - -The braces of anonymous inner classes in Java are given the special -symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that -they can be distinguished from the braces of normal classes@footnote{The -braces of anonymous classes produce a combination of -@code{inexpr-class}, and @code{class-open} or @code{class-close} in -normal indentation analysis.}. - -Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})}, -@samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace -lists in this regard, even though they do for normal indentation -purposes. It's currently not possible to set automatic newlines on -these constructs. - -@item The associated value: the ``ACTION'' list or function -The value associated with each syntactic symbol in this association -list is called an @var{action}, which can be either a list or a -function which returns a list. @xref{Custom Braces}, for how to use -a function as a brace hanging @var{action}. - -The list @var{action} (or the list returned by @var{action} when it's -a function) contains some combination of the symbols @code{before} and -@code{after}, directing @ccmode{} where to put newlines in -relationship to the brace being inserted. Thus, if the list contains -only the symbol @code{after}, then the brace hangs on the right side -of the line, as in: - -@example -// here, open braces always `hang' -void spam( int i ) @{ - if( i == 7 ) @{ - dosomething(i); - @} -@} -@end example - -When the list contains both @code{after} and @code{before}, the braces -will appear on a line by themselves, as shown by the close braces in -the above example. The list can also be empty, in which case newlines -are added neither before nor after the brace. -@end table - -If a syntactic symbol is missing entirely from -@code{c-hanging-braces-alist}, it's treated in the same way as an -@var{action} with a list containing @code{before} and @code{after}, so -that braces by default end up on their own line. - -For example, the default value of @code{c-hanging-braces-alist} is: - -@example -((brace-list-open) - (brace-entry-open) - (statement-cont) - (substatement-open after) - (block-close . c-snug-do-while) - (extern-lang-open after) - (namespace-open after) - (module-open after) - (composition-open after) - (inexpr-class-open after) - (inexpr-class-close before)) -@end example - -@noindent which says that @code{brace-list-open}, -@code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists -inside statements, such as initializers for static array variables -inside functions in C, are recognized as @code{statement-cont}. All -normal substatement blocks are recognized with other symbols.} braces -should both hang on the right side and allow subsequent text to follow -on the same line as the brace. Also, @code{substatement-open}, -@code{extern-lang-open}, and @code{inexpr-class-open} braces should hang -on the right side, but subsequent text should follow on the next line. -The opposite holds for @code{inexpr-class-close} braces; they won't -hang, but the following text continues on the same line. Here, in the -@code{block-close} entry, you also see an example of using a function as -an @var{action}. In all other cases, braces are put on a line by -themselves. -@end defopt - -@menu -* Custom Braces:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Braces, , Hanging Braces, Hanging Braces -@comment node-name, next, previous, up -@subsection Custom Brace Hanging -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@vindex c-hanging-braces-alist -@vindex hanging-braces-alist (c-) -@cindex action functions -Syntactic symbols aren't the only place where you can customize -@ccmode{} with the lisp equivalent of callback functions. Remember -that @var{action}s are usually a list containing some combination of -the symbols @code{before} and @code{after} (@pxref{Hanging Braces}). -For more flexibility, you can instead specify brace ``hanginess'' by -giving a syntactic symbol an @dfn{action function} in -@code{c-hanging-braces-alist}; this function determines the -``hanginess'' of a brace, usually by looking at the code near it. - -@cindex customization, brace hanging -An action function is called with two arguments: the syntactic symbol -for the brace (e.g., @code{substatement-open}), and the buffer position -where the brace has been inserted. Point is undefined on entry to an -action function, but the function must preserve it (e.g., by using -@code{save-excursion}). The return value should be a list containing -some combination of @code{before} and @code{after}, including neither -of them (i.e., @code{nil}). - -@defvar c-syntactic-context -@vindex syntactic-context (c-) -During the call to the indentation or brace hanging @var{action} -function, this variable is bound to the full syntactic analysis list. -This might be, for example, @samp{((block-close 73))}. Don't ever -give @code{c-syntactic-context} a value yourself---this would disrupt -the proper functioning of @ccmode{}. - -This variable is also bound in three other circumstances: -(i)@w{ }when calling a c-hanging-semi&comma-criteria function -(@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a -line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a -c-special-indent-hook function (@pxref{Other Indentation}). -@end defvar - -As an example, @ccmode{} itself uses this feature to dynamically -determine the hanginess of braces which close ``do-while'' -constructs: - -@example -void do_list( int count, char** atleast_one_string ) -@{ - int i=0; - do @{ - handle_string( atleast_one_string[i] ); - i++; - @} while( i < count ); -@} -@end example - -@ccmode{} assigns the @code{block-close} syntactic symbol to the -brace that closes the @code{do} construct, and normally we'd like the -line that follows a @code{block-close} brace to begin on a separate -line. However, with ``do-while'' constructs, we want the -@code{while} clause to follow the closing brace. To do this, we -associate the @code{block-close} symbol with the @var{action} function -@code{c-snug-do-while}: - -@example -(defun c-snug-do-while (syntax pos) - "Dynamically calculate brace hanginess for do-while statements." - (save-excursion - (let (langelem) - (if (and (eq syntax 'block-close) - (setq langelem (assq 'block-close c-syntactic-context)) - (progn (goto-char (cdr langelem)) - (if (= (following-char) ?@{) - (forward-sexp -1)) - (looking-at "\\[^_]"))) - '(before) - '(before after))))) -@end example - -@findex c-snug-do-while -@findex snug-do-while (c-) -This function simply looks to see if the brace closes a ``do-while'' -clause and if so, returns the list @samp{(before)} indicating -that a newline should be inserted before the brace, but not after it. -In all other cases, it returns the list @samp{(before after)} so -that the brace appears on a line by itself. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Colons -@cindex hanging colons -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex customization, colon hanging -@vindex c-hanging-colons-alist -@vindex hanging-colons-alist (c-) - -Using a mechanism similar to brace hanging (@pxref{Hanging Braces}), -colons can also be made to hang using the style variable -@code{c-hanging-colons-alist}: when a colon is typed, @ccmode -determines its syntactic context, looks this up in the alist -@code{c-changing-colons-alist} and inserts up to two newlines -accordingly. Here, however, If @ccmode fails to find an entry for a -syntactic symbol in the alist, no newlines are inserted around the -newly typed colon. - -@defopt c-hanging-colons-alist -@vindex hanging-colons-alist (c-) - -@table @asis -@item The Key: the syntactic symbol -The syntactic symbols appropriate as keys in this association list -are: @code{case-label}, @code{label}, @code{access-label}, -@code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic -Symbols}. Elements with any other value as a key get ignored. - -@item The associated value: the ``ACTION'' list -The @var{action} here is simply a list containing a combination of the -symbols @code{before} and @code{after}. Unlike in -@code{c-hanging-braces-alist}, functions as @var{actions} are not -supported; there doesn't seem to be any need for them. -@end table -@end defopt - -In C++, double-colons are used as a scope operator but because these -colons always appear right next to each other, newlines before and after -them are controlled by a different mechanism, called @dfn{clean-ups} in -@ccmode{}. @xref{Clean-ups}, for details. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Semicolons and Commas -@cindex hanging semicolons -@cindex hanging commas -@cindex customization, semicolon newlines -@cindex customization, comma newlines -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@defopt c-hanging-semi&comma-criteria -@vindex hanging-semi&comma-criteria (c-) -This style variable takes a list of functions; these get called when -you type a semicolon or comma. The functions are called in order -without arguments. When these functions are entered, point is just -after the newly inserted @samp{;} or @samp{,} and they must preserve -point (e.g., by using @code{save-excursion}). During the call, the -variable @code{c-syntactic-context} is bound to the syntactic context -of the current line@footnote{This was first introduced in @ccmode{} -5.31.} @pxref{Custom Braces}. These functions don't insert newlines -themselves, rather they direct @ccmode{} whether or not to do so. -They should return one of the following values: - -@table @code -@item t -A newline is to be inserted after the @samp{;} or @samp{,}, and no -more functions from the list are to be called. -@item stop -No more functions from the list are to be called, and no newline is to -be inserted. -@item nil -No determination has been made, and the next function in the list is -to be called. -@end table - -Note that auto-newlines are never inserted @emph{before} a semicolon -or comma. If every function in the list is called without a -determination being made, then no newline is added. - -In AWK mode, this variable is set by default to @code{nil}. In the -other modes, the default value is a list containing a single function, -@code{c-semi&comma-inside-parenlist}. This inserts newlines after all -semicolons, apart from those separating @code{for}-clause statements. -@end defopt - -@defun c-semi&comma-no-newlines-before-nonblanks -@findex semi&comma-no-newlines-before-nonblanks (c-) -This is an example of a criteria function, provided by @ccmode{}. It -prevents newlines from being inserted after semicolons when there is a -non-blank following line. Otherwise, it makes no determination. To -use, add this function to the front of the -@code{c-hanging-semi&comma-criteria} list. - -@example -(defun c-semi&comma-no-newlines-before-nonblanks () - (save-excursion - (if (and (eq last-command-char ?\;) - (zerop (forward-line 1)) - (not (looking-at "^[ \t]*$"))) - 'stop - nil))) -@end example -@end defun - -@defun c-semi&comma-inside-parenlist -@findex semi&comma-inside-parenlist (c-) -@defunx c-semi&comma-no-newlines-for-oneline-inliners -@findex semi&comma-no-newlines-for-oneline-inliners (c-) -The function @code{c-semi&comma-inside-parenlist} is what prevents -newlines from being inserted inside the parenthesis list of @code{for} -statements. In addition to -@code{c-semi&comma-no-newlines-before-nonblanks} described above, -@ccmode{} also comes with the criteria function -@code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses -newlines after semicolons inside one-line inline method definitions -(e.g., in C++ or Java). -@end defun - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top -@comment node-name, next, previous, up -@chapter Clean-ups -@cindex clean-ups -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add) -whitespace in specific circumstances and are complementary to colon -and brace hanging. You enable a clean-up by adding its symbol into -@code{c-cleanup-list}, e.g., like this: - -@example -(add-to-list 'c-cleanup-list 'space-before-funcall) -@end example - -On the surface, it would seem that clean-ups overlap the functionality -provided by the @code{c-hanging-*-alist} variables. Clean-ups, -however, are used to adjust code ``after-the-fact'', i.e., to adjust -the whitespace in constructs later than when they were typed. - -Most of the clean-ups remove automatically inserted newlines, and are -only active when auto-newline minor mode is turned on. Others will -work all the time. Note that clean-ups are only performed when there -is nothing but whitespace appearing between the individual components -of the construct, and (apart from @code{comment-close-slash}) when the -construct does not occur within a literal (@pxref{Auto-newlines}). - -@defopt c-cleanup-list -@vindex cleanup-list (c-) -@cindex literal - -You configure @ccmode{}'s clean-ups by setting the style variable -@code{c-cleanup-list}, which is a list of clean-up symbols. By -default, @ccmode{} cleans up only the @code{scope-operator} construct, -which is necessary for proper C++ support. -@end defopt - -These are the clean-ups that are only active when electric and -auto-newline minor modes are enabled: - -@c TBD: Would like to use some sort of @deffoo here; @table indents a -@c bit too much in dvi output. -@table @code -@item brace-else-brace -Clean up @samp{@} else @{} constructs by placing the entire construct on -a single line. Clean up occurs when the open brace after the -@samp{else} is typed. So for example, this: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} - else - @{ -@end group -@end example - -@noindent -appears like this after the last open brace is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else @{ -@end group -@end example - -@item brace-elseif-brace -Similar to the @code{brace-else-brace} clean-up, but this cleans up -@samp{@} else if (...) @{} constructs. For example: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} - else if( i==3 ) - @{ -@end group -@end example - -@noindent -appears like this after the last open parenthesis is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( -@end group -@end example - -@noindent -and like this after the last open brace is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( i==3 ) @{ -@end group -@end example - -@item brace-catch-brace -Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch -(...) @{} in C++ and Java mode. - -@item empty-defun-braces -Clean up braces following a top-level function or class definition that -contains no body. Clean up occurs when the closing brace is typed. -Thus the following: - -@example -@group -class Spam -@{ -@} -@end group -@end example - -@noindent -is transformed into this when the close brace is typed: - -@example -@group -class Spam -@{@} -@end group -@end example - -@item defun-close-semi -Clean up the terminating semicolon on top-level function or class -definitions when they follow a close brace. Clean up occurs when the -semicolon is typed. So for example, the following: - -@example -@group -class Spam -@{ -... -@} -; -@end group -@end example - -@noindent -is transformed into this when the semicolon is typed: - -@example -@group -class Spam -@{ -... -@}; -@end group -@end example - -@item list-close-comma -Clean up commas following braces in array and aggregate initializers. -Clean up occurs when the comma is typed. The space before the comma -is zapped just like the space before the semicolon in -@code{defun-close-semi}. - -@item scope-operator -Clean up double colons which might designate a C++ scope operator split -across multiple lines@footnote{Certain C++ constructs introduce -ambiguous situations, so @code{scope-operator} clean-ups might not -always be correct. This usually only occurs when scoped identifiers -appear in switch label tags.}. Clean up occurs when the second colon is -typed. You will always want @code{scope-operator} in the -@code{c-cleanup-list} when you are editing C++ code. - -@item one-liner-defun -Clean up a single line of code enclosed by defun braces by removing -the whitespace before and after the code. The clean-up happens when -the closing brace is typed. If the variable -@code{c-max-one-liner-length} is set, the cleanup is only done if the -resulting line would be no longer than the value of that variable. - -For example, consider this AWK code: - -@example -@group -BEGIN @{ - FS = "\t" # use as a field separator -@} -@end group -@end example - -@noindent -It gets compacted to the following when the closing brace is typed: - -@example -@group -BEGIN @{FS = "\t"@} # use as a field separator -@end group -@end example - -@defopt c-max-one-liner-length -@vindex max-one-liner-length (c-) -The maximum length of the resulting line for which the clean-up -@code{one-liner-defun} will be triggered. This length is that of the entire -line, including any leading whitespace and any trailing comment. Its -default value is 80. If the value is zero or @code{nil}, no limit -applies. -@end defopt -@end table - -The following clean-ups are always active when they occur on -@code{c-cleanup-list}, regardless of whether Electric minor mode or -Auto-newline minor mode are enabled: - -@table @code -@item space-before-funcall -Insert a space between the function name and the opening parenthesis -of a function call. This produces function calls in the style -mandated by the GNU coding standards, e.g., @samp{signal@w{ }(SIGINT, -SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening -parenthesis is typed. This clean-up should never be active in AWK -Mode, since such a space is syntactically invalid for user defined -functions. - -@item compact-empty-funcall -Clean up any space between the function name and the opening parenthesis -of a function call that has no arguments. This is typically used -together with @code{space-before-funcall} if you prefer the GNU function -call style for functions with arguments but think it looks ugly when -it's only an empty parenthesis pair. I.e., you will get @samp{signal -(SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the -closing parenthesis is typed. - -@item comment-close-slash -When inside a block comment, terminate the comment when you type a slash -at the beginning of a line (i.e., immediately after the comment prefix). -This clean-up removes whitespace preceding the slash and if needed, -inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this -situation if you just want a literal @samp{/} inserted. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top -@comment node-name, next, previous, up -@chapter Indentation Engine Basics -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This chapter will briefly cover how @ccmode{} indents lines of code. -It is helpful to understand the indentation model being used so that -you will know how to customize @ccmode{} for your personal coding -style. All the details are in @ref{Customizing Indentation}. - -@ccmode{} has an indentation engine that provides a flexible and -general mechanism for customizing indentation. When @ccmode{} indents -a line of code, it separates its calculations into two steps: - -@enumerate -@item -@cindex syntactic symbol -@cindex anchor position -It analyzes the line to determine its @dfn{syntactic symbol(s)} (the -kind of language construct it's looking at) and its @dfn{anchor -position} (the position earlier in the file that @ccmode{} will indent -the line relative to). The anchor position might be the location of -an opening brace in the previous line, for example. @xref{Syntactic -Analysis}. -@item -@cindex offsets -@cindex indentation offset specifications -It looks up the syntactic symbol(s) in the configuration to get the -corresponding @dfn{offset(s)}. The symbol @code{+}, which means -``indent this line one more level'' is a typical offset. @ccmode{} -then applies these offset(s) to the anchor position, giving the -indentation for the line. The different sorts of offsets are -described in @ref{c-offsets-alist}. -@end enumerate - -In exceptional circumstances, the syntax directed indentation -described here may be a nuisance rather than a help. You can disable -it by setting @code{c-syntactic-indentation} to @code{nil}. (To set -the variable interactively, @ref{Minor Modes}). - -@defopt c-syntactic-indentation -@vindex syntactic-indentation (c-) -When this is non-@code{nil} (which it is by default), the indentation -of code is done according to its syntactic structure. When it's -@code{nil}, every line is just indented to the same level as the -previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the -indentation in steps of @code{c-basic-offset}. The current style -(@pxref{Config Basics}) then has no effect on indentation, nor do any -of the variables associated with indentation, not even -@code{c-special-indent-hook}. -@end defopt - -@menu -* Syntactic Analysis:: -* Syntactic Symbols:: -* Indentation Calculation:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics -@comment node-name, next, previous, up -@section Syntactic Analysis -@cindex syntactic analysis -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex syntactic element -@cindex syntactic context -The first thing @ccmode{} does when indenting a line of code, is to -analyze the line, determining the @dfn{syntactic context} of the -(first) construct on that line. It's a list of @dfn{syntactic -elements}, where each syntactic element in turn is a list@footnote{In -@ccmode 5.28 and earlier, a syntactic element was a dotted pair; the -cons was the syntactic symbol and the cdr was the anchor position. -For compatibility's sake, the parameter passed to a line-up function -still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a -brief and typical example: - -@example -((defun-block-intro 1959)) -@end example - -@cindex syntactic symbol -@noindent -The first thing inside each syntactic element is always a -@dfn{syntactic symbol}. It describes the kind of construct that was -recognized, e.g., @code{statement}, @code{substatement}, -@code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, -for a complete list of currently recognized syntactic symbols and -their semantics. The remaining entries are various data associated -with the recognized construct; there might be zero or more. - -@cindex anchor position -Conceptually, a line of code is always indented relative to some -position higher up in the buffer (typically the indentation of the -previous line). That position is the @dfn{anchor position} in the -syntactic element. If there is an entry after the syntactic symbol in -the syntactic element list then it's either @code{nil} or that anchor position. - -Here is an example. Suppose we had the following code as the only thing -in a C++ buffer @footnote{The line numbers in this and future examples -don't actually appear in the buffer, of course!}: - -@example - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} -@end example - -@noindent -We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to -report what the syntactic analysis is for the current line: - -@table @asis -@item @kbd{C-c C-s} (@code{c-show-syntactic-information}) -@kindex C-c C-s -@findex c-show-syntactic-information -@findex show-syntactic-information (c-) -This command calculates the syntactic analysis of the current line and -displays it in the minibuffer. The command also highlights the anchor -position(s). -@end table - - Running this command on line 4 of this example, we'd see in the echo -area@footnote{With a universal argument (i.e., @kbd{C-u C-c C-s}) the -analysis is inserted into the buffer as a comment on the current -line.}: - -@example -((statement 35)) -@end example - -@noindent -and the @samp{i} of @code{int} on line 3 would be highlighted. This -tells us that the line is a statement and it is indented relative to -buffer position 35, the highlighted position. If you were to move -point to line 3 and hit @kbd{C-c C-s}, you would see: - -@example -((defun-block-intro 29)) -@end example - -@noindent -This indicates that the @samp{int} line is the first statement in a top -level function block, and is indented relative to buffer position 29, -which is the brace just after the function header. - -Here's another example: - -@example - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end example - -@noindent -Hitting @kbd{C-c C-s} on line 4 gives us: - -@example -((substatement-open 46)) -@end example - -@cindex substatement -@cindex substatement block -@noindent -which tells us that this is a brace that @emph{opens} a substatement -block. @footnote{A @dfn{substatement} is the line after a -conditional statement, such as @code{if}, @code{else}, @code{while}, -@code{do}, @code{switch}, etc. A @dfn{substatement -block} is a brace block following one of these conditional statements.} - -@cindex comment-only line -Syntactic contexts can contain more than one element, and syntactic -elements need not have anchor positions. The most common example of -this is a @dfn{comment-only line}: - -@example - 1: void draw_list( List& drawables ) - 2: @{ - 3: // call the virtual draw() method on each element in list - 4: for( int i=0; i < drawables.count(), ++i ) - 5: @{ - 6: drawables[i].draw(); - 7: @} - 8: @} -@end example - -@noindent -Hitting @kbd{C-c C-s} on line 3 of this example gives: - -@example -((comment-intro) (defun-block-intro 46)) -@end example - -@noindent -and you can see that the syntactic context contains two syntactic -elements. Notice that the first element, @samp{(comment-intro)}, has no -anchor position. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics -@comment node-name, next, previous, up -@section Syntactic Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex syntactic symbols, brief list -@vindex c-offsets-alist -@vindex offsets-alist (c-) -This section is a complete list of the syntactic symbols which appear -in the @code{c-offsets-alist} style variable, along with brief -descriptions. The previous section (@pxref{Syntactic Analysis}) -states what syntactic symbols are and how the indentation engine uses -them. - -More detailed descriptions of these symbols, together with snippets of -source code to which they apply, appear in the examples in the -subsections below. Note that, in the interests of brevity, the anchor -position associated with most syntactic symbols is @emph{not} -specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent -line---this highlights the anchor position. - -@ssindex -open symbols -@ssindex -close symbols -@ssindex -block-intro symbols -The syntactic symbols which indicate brace constructs follow a general -naming convention. When a line begins with an open or close brace, -its syntactic symbol will contain the suffix @code{-open} or -@code{-close} respectively. The first line within the brace block -construct will contain the suffix @code{-block-intro}. - -@ssindex -intro symbols -@ssindex -cont symbols -In constructs which can span several lines, a distinction is usually -made between the first line that introduces the construct and the -lines that continue it. The syntactic symbols that indicate these -lines will contain the suffixes @code{-intro} or @code{-cont} -respectively. - -The best way to understand how all this works is by looking at some -examples. Remember that you can see the syntax of any source code -line by using @kbd{C-c C-s}. - -@table @code -@item string -Inside a multiline string. @ref{Literal Symbols}. -@item c -Inside a multiline C style block comment. @ref{Literal Symbols}. -@item defun-open -Brace that opens a top-level function definition. @ref{Function -Symbols}. -@item defun-close -Brace that closes a top-level function definition. @ref{Function -Symbols}. -@item defun-block-intro -The first line in a top-level defun. @ref{Function Symbols}. -@item class-open -Brace that opens a class definition. @ref{Class Symbols}. -@item class-close -Brace that closes a class definition. @ref{Class Symbols}. -@item inline-open -Brace that opens an in-class inline method. @ref{Class Symbols}. -@item inline-close -Brace that closes an in-class inline method. @ref{Class Symbols}. -@item func-decl-cont -The region between a function definition's argument list and the -function opening brace (excluding K&R argument declarations). In C, -you cannot put anything but whitespace and comments in this region, -however in C++ and Java, @code{throws} declarations and other things -can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not -@c go somewhere better?} -@item knr-argdecl-intro -First line of a K&R C argument declaration. @ref{K&R Symbols}. -@item knr-argdecl -Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}. -@item topmost-intro -The first line in a ``topmost'' definition. @ref{Function Symbols}. -@item topmost-intro-cont -Topmost definition continuation lines. This is only used in the parts -that aren't covered by other symbols such as @code{func-decl-cont} and -@code{knr-argdecl}. @ref{Function Symbols}. -@item annotation-top-cont -Topmost definition continuation lines where all previous items are -annotations. @ref{Java Symbols}. -@item member-init-intro -First line in a member initialization list. @ref{Class Symbols}. -@item member-init-cont -Subsequent member initialization list lines. @ref{Class Symbols}. -@item inher-intro -First line of a multiple inheritance list. @ref{Class Symbols}. -@item inher-cont -Subsequent multiple inheritance lines. @ref{Class Symbols}. -@item block-open -Statement block open brace. @ref{Literal Symbols}. -@item block-close -Statement block close brace. @ref{Conditional Construct Symbols}. -@item brace-list-open -Open brace of an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-close -Close brace of an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-intro -First line in an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-entry -Subsequent lines in an enum or static array list. @ref{Brace List -Symbols}. -@item brace-entry-open -Subsequent lines in an enum or static array list where the line begins -with an open brace. @ref{Brace List Symbols}. -@item statement -A statement. @ref{Function Symbols}. -@item statement-cont -A continuation of a statement. @ref{Function Symbols}. -@item annotation-var-cont -A continuation of a statement where all previous items are -annotations. @ref{Java Symbols}. -@item statement-block-intro -The first line in a new statement block. @ref{Conditional Construct -Symbols}. -@item statement-case-intro -The first line in a case block. @ref{Switch Statement Symbols}. -@item statement-case-open -The first line in a case block that starts with a brace. @ref{Switch -Statement Symbols}. -@item substatement -The first line after a conditional or loop construct. -@ref{Conditional Construct Symbols}. -@item substatement-open -The brace that opens a substatement block. @ref{Conditional Construct -Symbols}. -@item substatement-label -The first line after a conditional or loop construct if it's a label. -@ref{Conditional Construct Symbols}. -@item case-label -A label in a @code{switch} block. @ref{Switch Statement Symbols}. -@item access-label -C++ access control label. @ref{Class Symbols}. -@item label -Any other label. @ref{Literal Symbols}. -@item do-while-closure -The @code{while} line that ends a @code{do}-@code{while} construct. -@ref{Conditional Construct Symbols}. -@item else-clause -The @code{else} line of an @code{if}-@code{else} construct. -@ref{Conditional Construct Symbols}. -@item catch-clause -The @code{catch} or @code{finally} (in Java) line of a -@code{try}-@code{catch} construct. @ref{Conditional Construct -Symbols}. -@item comment-intro -A line containing only a comment introduction. @ref{Literal Symbols}. -@item arglist-intro -The first line in an argument list. @ref{Paren List Symbols}. -@item arglist-cont -Subsequent argument list lines when no arguments follow on the same -line as the arglist opening paren. @ref{Paren List Symbols}. -@item arglist-cont-nonempty -Subsequent argument list lines when at least one argument follows on -the same line as the arglist opening paren. @ref{Paren List Symbols}. -@item arglist-close -The solo close paren of an argument list. @ref{Paren List Symbols}. -@item stream-op -Lines continuing a stream operator (C++ only). @ref{Literal -Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?} -@item inclass -The line is nested inside a class definition. @ref{Class Symbols}. -@item cpp-macro -The start of a preprocessor macro definition. @ref{Literal Symbols}. -@item cpp-define-intro -The first line inside a multiline preprocessor macro if -@code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro -Symbols}. -@item cpp-macro-cont -All lines inside multiline preprocessor macros if -@code{c-syntactic-indentation-in-macros} is @code{nil}. -@ref{Multiline Macro Symbols}. -@item friend -A C++ friend declaration. @ref{Class Symbols}. -@item objc-method-intro -The first line of an Objective-C method definition. @ref{Objective-C -Method Symbols}. -@item objc-method-args-cont -Lines continuing an Objective-C method definition. @ref{Objective-C -Method Symbols}. -@item objc-method-call-cont -Lines continuing an Objective-C method call. @ref{Objective-C Method -Symbols}. -@item extern-lang-open -Brace that opens an @code{extern} block (e.g., @code{extern "C" -@{...@}}). @ref{External Scope Symbols}. -@item extern-lang-close -Brace that closes an @code{extern} block. @ref{External Scope -Symbols}. -@item inextern-lang -Analogous to @code{inclass} syntactic symbol, but used inside -@code{extern} blocks. @ref{External Scope Symbols}. -@item namespace-open -@itemx namespace-close -@itemx innamespace -These are analogous to the three @code{extern-lang} symbols above, but -are returned for C++ namespace blocks. @ref{External Scope Symbols}. -@item module-open -@itemx module-close -@itemx inmodule -Analogous to the above, but for CORBA IDL @code{module} blocks. -@ref{External Scope Symbols}. -@item composition-open -@itemx composition-close -@itemx incomposition -Analogous to the above, but for CORBA CIDL @code{composition} blocks. -@ref{External Scope Symbols}. -@item template-args-cont -C++ template argument list continuations. @ref{Class Symbols}. -@item inlambda -Analogous to @code{inclass} syntactic symbol, but used inside lambda -(i.e., anonymous) functions. Only used in Pike mode. @ref{Statement -Block Symbols}. -@item lambda-intro-cont -Lines continuing the header of a lambda function, i.e., between the -@code{lambda} keyword and the function body. Only used in Pike mode. -@ref{Statement Block Symbols}. -@item inexpr-statement -A statement block inside an expression. The gcc C and C++ extension -for this is recognized. It's also used for the special functions that -take a statement block as an argument in Pike. @ref{Statement Block -Symbols}. -@item inexpr-class -A class definition inside an expression. This is used for anonymous -classes in Java. It's also used for anonymous array initializers in -Java. @ref{Java Symbols}. -@end table - -@menu -* Function Symbols:: -* Class Symbols:: -* Conditional Construct Symbols:: -* Switch Statement Symbols:: -* Brace List Symbols:: -* External Scope Symbols:: -* Paren List Symbols:: -* Literal Symbols:: -* Multiline Macro Symbols:: -* Objective-C Method Symbols:: -* Java Symbols:: -* Statement Block Symbols:: -* K&R Symbols:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Function Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This example shows a typical function declaration. - -@example - 1: void - 2: swap( int& a, int& b ) - 3: @{ - 4: int tmp = a; - 5: a = b; - 6: b = tmp; - 7: int ignored = - 8: a + b; - 9: @} -@end example - -@ssindex topmost-intro -@ssindex topmost-intro-cont -@ssindex defun-open -@ssindex defun-close -@ssindex defun-block-intro -Line 1 shows a @code{topmost-intro} since it is the first line that -introduces a top-level construct. Line 2 is a continuation of the -top-level construct introduction so it has the syntax -@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is -the brace that opens a top-level function definition. Line 9 is the -corresponding -@code{defun-close} since it contains the brace that closes the top-level -function definition. Line 4 is a @code{defun-block-intro}, i.e., it is -the first line of a brace-block, enclosed in a -top-level function definition. - -@ssindex statement -@ssindex statement-cont -Lines 5, 6, and 7 are all given @code{statement} syntax since there -isn't much special about them. Note however that line 8 is given -@code{statement-cont} syntax since it continues the statement begun -on the previous line. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Class related Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here's an example which illustrates some C++ class syntactic symbols: - -@example - 1: class Bass - 2: : public Guitar, - 3: public Amplifiable - 4: @{ - 5: public: - 6: Bass() - 7: : eString( new BassString( 0.105 )), - 8: aString( new BassString( 0.085 )), - 9: dString( new BassString( 0.065 )), -10: gString( new BassString( 0.045 )) -11: @{ -12: eString.tune( 'E' ); -13: aString.tune( 'A' ); -14: dString.tune( 'D' ); -15: gString.tune( 'G' ); -16: @} -17: friend class Luthier; -18: @}; -@end example - -@ssindex class-open -@ssindex class-close -As in the previous example, line 1 has the @code{topmost-intro} syntax. -Here however, the brace that opens a C++ class definition on line 4 is -assigned the @code{class-open} syntax. Note that in C++, classes, -structs, and unions are essentially equivalent syntactically (and are -very similar semantically), so replacing the @code{class} keyword in the -example above with @code{struct} or @code{union} would still result in a -syntax of @code{class-open} for line 4 @footnote{This is the case even -for C and Objective-C@. For consistency, structs in all supported -languages are syntactically equivalent to classes. Note however that -the keyword @code{class} is meaningless in C and Objective-C.}. -Similarly, line 18 is assigned @code{class-close} syntax. - -@ssindex inher-intro -@ssindex inher-cont -Line 2 introduces the inheritance list for the class so it is assigned -the @code{inher-intro} syntax, and line 3, which continues the -inheritance list is given @code{inher-cont} syntax. - -@ssindex access-label -@ssindex inclass -Hitting @kbd{C-c C-s} on line 5 shows the following analysis: - -@example -((inclass 58) (access-label 58)) -@end example - -@noindent -The primary syntactic symbol for this line is @code{access-label} as -this is a label keyword that specifies access protection in C++. However, -because this line is also a top-level construct inside a class -definition, the analysis actually shows two syntactic symbols. The -other syntactic symbol assigned to this line is @code{inclass}. -Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} -syntax: - -@example -((inclass 58) (topmost-intro 60)) -@end example - -@ssindex member-init-intro -@ssindex member-init-cont -Line 7 introduces a C++ member initialization list and as such is given -@code{member-init-intro} syntax. Note that in this case it is -@emph{not} assigned @code{inclass} since this is not considered a -top-level construct. Lines 8 through 10 are all assigned -@code{member-init-cont} since they continue the member initialization -list started on line 7. - -@cindex in-class inline methods -@ssindex inline-open -@ssindex inline-close -Line 11's analysis is a bit more complicated: - -@example -((inclass 58) (inline-open)) -@end example - -This line is assigned a syntax of both @code{inline-open} and -@code{inclass} because it opens an @dfn{in-class} C++ inline method -definition. This is distinct from, but related to, the C++ notion of an -inline function in that its definition occurs inside an enclosing class -definition, which in C++ implies that the function should be inlined. -However, if the definition of the @code{Bass} constructor appeared -outside the class definition, the construct would be given the -@code{defun-open} syntax, even if the keyword @code{inline} appeared -before the method name, as in: - -@example - 1: class Bass - 2: : public Guitar, - 3: public Amplifiable - 4: @{ - 5: public: - 6: Bass(); - 7: @}; - 8: - 9: inline -10: Bass::Bass() -11: : eString( new BassString( 0.105 )), -12: aString( new BassString( 0.085 )), -13: dString( new BassString( 0.065 )), -14: gString( new BassString( 0.045 )) -15: @{ -16: eString.tune( 'E' ); -17: aString.tune( 'A' ); -18: dString.tune( 'D' ); -19: gString.tune( 'G' ); -20: @} -@end example - -@ssindex friend -Returning to the previous example, line 16 is given @code{inline-close} -syntax, while line 12 is given @code{defun-block-open} syntax, and lines -13 through 15 are all given @code{statement} syntax. Line 17 is -interesting in that its syntactic analysis list contains three -elements: - -@example -((inclass 58) (topmost-intro 380) (friend)) -@end example - -The @code{friend} and @code{inline-open} syntactic symbols are -modifiers that do not have anchor positions. - -@ssindex template-args-cont -Template definitions introduce yet another syntactic symbol: - -@example - 1: ThingManager framework_callbacks; -@end example - -Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 -are both analyzed as @code{template-args-cont} lines. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Conditional Construct Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here is a (totally contrived) example which illustrates how syntax is -assigned to various conditional constructs: - -@example - 1: void spam( int index ) - 2: @{ - 3: for( int i=0; i 0 ); -15: @} -@end example - -Only the lines that illustrate new syntactic symbols will be discussed. - -@ssindex substatement-open -@ssindex statement-block-intro -@ssindex block-close -Line 4 has a brace which opens a conditional's substatement block. It -is thus assigned @code{substatement-open} syntax, and since line 5 is -the first line in the substatement block, it is assigned -@code{statement-block-intro} syntax. Line 10 contains the brace -that closes the inner substatement block, and is therefore given the -syntax @code{block-close}@footnote{@code{block-open} is used only for -``free-standing'' blocks, and is somewhat rare (@pxref{Literal -Symbols} for an example.)}. Line 13 is treated the same way. - -@ssindex substatement -Lines 6 and 9 are also substatements of conditionals, but since they -don't start blocks they are given @code{substatement} syntax -instead of @code{substatement-open}. - -@ssindex substatement-label -Line 8 contains a label, which is normally given @code{label} syntax. -This one is however a bit special since it's between a conditional and -its substatement. It's analyzed as @code{substatement-label} to let you -handle this rather odd case differently from normal labels. - -@ssindex else-clause -@ssindex catch-clause -Line 7 start with an @code{else} that matches the @code{if} statement on -line 5. It is therefore given the @code{else-clause} syntax and is -anchored on the matching @code{if}. The @code{try}-@code{catch} -constructs in C++ and Java are treated this way too, except that -@code{catch} and (in Java) @code{finally}, are marked with -@code{catch-clause}. - -@ssindex do-while-closure -The @code{while} construct on line 14 that closes a @code{do} -conditional is given the special syntax @code{do-while-closure} if it -appears on a line by itself. Note that if the @code{while} appeared on -the same line as the preceding close brace, that line would still have -@code{block-close} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Switch Statement Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Switch statements have their own set of syntactic symbols. Here's an -example: - -@example - 1: void spam( enum Ingredient i ) - 2: @{ - 3: switch( i ) @{ - 4: case Ham: - 5: be_a_pig(); - 6: break; - 7: case Salt: - 8: drink_some_water(); - 9: break; -10: default: -11: @{ -12: what_is_it(); -13: break; -14: @} -15: @} -14: @} -@end example - -@ssindex case-label -@ssindex statement-case-intro -@ssindex statement-case-open -Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, -while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 -is treated slightly differently since it contains a brace that opens a -block; it is given @code{statement-case-open} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Brace List Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex brace lists -There are a set of syntactic symbols that are used to recognize -constructs inside of brace lists. A brace list is defined as an -@code{enum} or aggregate initializer list, such as might statically -initialize an array of structs. The three special aggregate constructs -in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as -brace lists too. An example: - -@example - 1: static char* ingredients[] = - 2: @{ - 3: "Ham", - 4: "Salt", - 5: NULL - 6: @}; -@end example - -@ssindex brace-list-open -@ssindex brace-list-intro -@ssindex brace-list-close -@ssindex brace-list-entry -Following convention, line 2 in this example is assigned -@code{brace-list-open} syntax, and line 3 is assigned -@code{brace-list-intro} syntax. Likewise, line 6 is assigned -@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned -@code{brace-list-entry} syntax, as would all subsequent lines in this -initializer list. - -@ssindex brace-entry-open -Your static initializer might be initializing nested structures, for -example: - -@example - 1: struct intpairs[] = - 2: @{ - 3: @{ 1, 2 @}, - 4: @{ - 5: 3, - 6: 4 - 7: @} - 8: @{ 1, - 9: 2 @}, -10: @{ 3, 4 @} -11: @}; -@end example - -Here, you've already seen the analysis of lines 1, 2, 3, and 11. On -line 4, things get interesting; this line is assigned -@code{brace-entry-open} syntactic symbol because it's a bracelist entry -line that starts with an open brace. Lines 5 and 6 (and line 9) are -pretty standard, and line 7 is a @code{brace-list-close} as you'd -expect. Once again, line 8 is assigned as @code{brace-entry-open} as is -line 10. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection External Scope Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -External language definition blocks also have their own syntactic -symbols. In this example: - -@example - 1: extern "C" - 2: @{ - 3: int thing_one( int ); - 4: int thing_two( double ); - 5: @} -@end example - -@ssindex extern-lang-open -@ssindex extern-lang-close -@ssindex inextern-lang -@ssindex inclass -@noindent -line 2 is given the @code{extern-lang-open} syntax, while line 5 is given -the @code{extern-lang-close} syntax. The analysis for line 3 yields: - -@example -((inextern-lang) (topmost-intro 14)) -@end example - -@noindent -where @code{inextern-lang} is a modifier similar in purpose to -@code{inclass}. - -There are various other top level blocks like @code{extern}, and they -are all treated in the same way except that the symbols are named after -the keyword that introduces the block. E.g., C++ namespace blocks get -the three symbols @code{namespace-open}, @code{namespace-close} and -@code{innamespace}. The currently recognized top level blocks are: - -@table @asis -@item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang} -@code{extern} blocks in C and C++.@footnote{These should logically be -named @code{extern-open}, @code{extern-close} and @code{inextern}, but -that isn't the case for historical reasons.} - -@item @code{namespace-open}, @code{namespace-close}, @code{innamespace} -@ssindex namespace-open -@ssindex namespace-close -@ssindex innamespace -@code{namespace} blocks in C++. - -@item @code{module-open}, @code{module-close}, @code{inmodule} -@ssindex module-open -@ssindex module-close -@ssindex inmodule -@code{module} blocks in CORBA IDL. - -@item @code{composition-open}, @code{composition-close}, @code{incomposition} -@ssindex composition-open -@ssindex composition-close -@ssindex incomposition -@code{composition} blocks in CORBA CIDL. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Parenthesis (Argument) List Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -A number of syntactic symbols are associated with parenthesis lists, -a.k.a argument lists, as found in function declarations and function -calls. This example illustrates these: - -@example - 1: void a_function( int line1, - 2: int line2 ); - 3: - 4: void a_longer_function( - 5: int line1, - 6: int line2 - 7: ); - 8: - 9: void call_them( int line1, int line2 ) -10: @{ -11: a_function( -12: line1, -13: line2 -14: ); -15: -16: a_longer_function( line1, -17: line2 ); -18: @} -@end example - -@ssindex arglist-intro -@ssindex arglist-close -Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are -the first line following the open parenthesis, and lines 7 and 14 are -assigned @code{arglist-close} syntax since they contain the parenthesis -that closes the argument list. - -@ssindex arglist-cont-nonempty -@ssindex arglist-cont -Lines that continue argument lists can be assigned one of two syntactic -symbols. For example, Lines 2 and 17 -are assigned @code{arglist-cont-nonempty} syntax. What this means -is that they continue an argument list, but that the line containing the -parenthesis that opens the list is @emph{not empty} following the open -parenthesis. Contrast this against lines 6 and 13 which are assigned -@code{arglist-cont} syntax. This is because the parenthesis that opens -their argument lists is the last character on that line. - -Syntactic elements with @code{arglist-intro}, -@code{arglist-cont-nonempty}, and @code{arglist-close} contain two -buffer positions: the anchor position (the beginning of the -declaration or statement) and the position of the open parenthesis. -The latter position can be used in a line-up function (@pxref{Line-Up -Functions}). - -Note that there is no @code{arglist-open} syntax. This is because any -parenthesis that opens an argument list, appearing on a separate line, -is assigned the @code{statement-cont} syntax instead. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Comment String Label and Macro Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -A few miscellaneous syntactic symbols that haven't been previously -covered are illustrated by this C++ example: - -@example - 1: void Bass::play( int volume ) - 2: const - 3: @{ - 4: /* this line starts a multiline - 5: * comment. This line should get `c' syntax */ - 6: - 7: char* a_multiline_string = "This line starts a multiline \ - 8: string. This line should get `string' syntax."; - 9: -10: note: -11: @{ -12: #ifdef LOCK -13: Lock acquire(); -14: #endif // LOCK -15: slap_pop(); -16: cout << "I played " -17: << "a note\n"; -18: @} -19: @} -@end example - -The lines to note in this example include: - -@itemize @bullet -@item -@ssindex func-decl-cont -Line 2 is assigned the @code{func-decl-cont} syntax. - -@item -@ssindex comment-intro -Line 4 is assigned both @code{defun-block-intro} @emph{and} -@code{comment-intro} syntax. A syntactic element with -@code{comment-intro} has no anchor point. It is always accompanied -by another syntactic element which does have one. - -@item -@ssindex c -Line 5 is assigned @code{c} syntax. - -@item -@cindex syntactic whitespace -Line 6 which, even though it contains nothing but whitespace, is -assigned @code{defun-block-intro}. Note that the appearance of the -comment on lines 4 and 5 do not cause line 6 to be assigned -@code{statement} syntax because comments are considered to be -@dfn{syntactic whitespace}, which are ignored when analyzing -code. - -@item -@ssindex string -Line 8 is assigned @code{string} syntax. - -@item -@ssindex label -Line 10 is assigned @code{label} syntax. - -@item -@ssindex block-open -Line 11 is assigned @code{block-open} as well as @code{statement} -syntax. A @code{block-open} syntactic element doesn't have an anchor -position, since it always appears with another syntactic element which -does have one. - -@item -@ssindex cpp-macro -Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the -normal syntactic symbols (@code{statement-block-intro} and -@code{statement}, respectively). Normally @code{cpp-macro} is -configured to cancel out the normal syntactic context to make all -preprocessor directives stick to the first column, but that's easily -changed if you want preprocessor directives to be indented like the rest -of the code. Like @code{comment-intro}, a syntactic element with -@code{cpp-macro} doesn't contain an anchor position. - -@item -@ssindex stream-op -Line 17 is assigned @code{stream-op} syntax. -@end itemize - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Multiline Macro Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex multiline macros -@cindex syntactic whitespace -@ssindex cpp-define-intro -@ssindex cpp-macro-cont -Multiline preprocessor macro definitions are normally handled just like -other code, i.e., the lines inside them are indented according to the -syntactic analysis of the preceding lines inside the macro. The first -line inside a macro definition (i.e., the line after the starting line of -the cpp directive itself) gets @code{cpp-define-intro}. In this example: - -@example - 1: #define LIST_LOOP(cons, listp) \ - 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ - 3: if (!CONSP (cons)) \ - 4: signal_error ("Invalid list format", listp); \ - 5: else -@end example - -@noindent -line 1 is given the syntactic symbol @code{cpp-macro}. The first line -of a cpp directive is always given that symbol. Line 2 is given -@code{cpp-define-intro}, so that you can give the macro body as a whole -some extra indentation. Lines 3 through 5 are then analyzed as normal -code, i.e., @code{substatement} on lines 3 and 4, and @code{else-clause} -on line 5. - -The syntactic analysis inside macros can be turned off with -@code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In -that case, lines 2 through 5 would all be given @code{cpp-macro-cont} -with an anchor position pointing to the @code{#} which starts the cpp -directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed -macros.}. - -@xref{Custom Macros}, for more info about the treatment of macros. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Objective-C Method Symbols, Java Symbols, Multiline Macro Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Objective-C Method Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -In Objective-C buffers, there are three additional syntactic symbols -assigned to various message calling constructs. Here's an example -illustrating these: - -@example - 1: - (void)setDelegate:anObject - 2: withStuff:stuff - 3: @{ - 4: [delegate masterWillRebind:self - 5: toDelegate:anObject - 6: withExtraStuff:stuff]; - 7: @} -@end example - -@ssindex objc-method-intro -@ssindex objc-method-args-cont -@ssindex objc-method-call-cont -Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is -assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both -assigned @code{objc-method-call-cont} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Java Symbols, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Java Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Java has a concept of anonymous classes which can look something like -this: - -@example - 1: @@Test - 2: public void watch(Observable o) @{ - 3: @@NonNull - 4: Observer obs = new Observer() @{ - 5: public void update(Observable o, Object arg) @{ - 6: history.addElement(arg); - 7: @} - 8: @}; - 9: o.addObserver(obs); - 10: @} -@end example - -@ssindex inexpr-class -The brace following the @code{new} operator opens the anonymous class. -Lines 5 and 8 are assigned the @code{inexpr-class} syntax, besides the -@code{inclass} symbol used in normal classes. Thus, the class will be -indented just like a normal class, with the added indentation given to -@code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't -have an anchor position. - -@ssindex annotation-top-cont -@ssindex annotation-var-cont -Line 2 is assigned the @code{annotation-top-cont} syntax, due to it being a -continuation of a topmost introduction with an annotation symbol preceding -the current line. Similarly, line 4 is assigned the @code{annotation-var-cont} -syntax due to it being a continuation of a variable declaration where preceding -the declaration is an annotation. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Statement Block Symbols, K&R Symbols, Java Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Statement Block Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -There are a few occasions where a statement block might be used inside -an expression. One is in C or C++ code using the gcc extension for -this, e.g.: - -@example - 1: int res = (@{ - 2: int y = foo (); int z; - 3: if (y > 0) z = y; else z = - y; - 4: z; - 5: @}); -@end example - -@ssindex inexpr-statement -Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the -symbols they'd get in a normal block. Therefore, the indentation put on -@code{inexpr-statement} is added to the normal statement block -indentation. An @code{inexpr-statement} syntactic element doesn't -contain an anchor position. - -In Pike code, there are a few other situations where blocks occur inside -statements, as illustrated here: - -@example - 1: array itgob() - 2: @{ - 3: string s = map (backtrace()[-2][3..], - 4: lambda - 5: (mixed arg) - 6: @{ - 7: return sprintf ("%t", arg); - 8: @}) * ", " + "\n"; - 9: return catch @{ -10: write (s + "\n"); -11: @}; -12: @} -@end example - -@ssindex inlambda -@ssindex lambda-intro-cont -Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes -by the @code{lambda} keyword. If the function argument list is put -on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} -syntax. The function body is handled as an inline method body, with the -addition of the @code{inlambda} syntactic symbol. This means that line -6 gets @code{inlambda} and @code{inline-open}, and line 8 gets -@code{inline-close}@footnote{You might wonder why it doesn't get -@code{inlambda} too. It's because the closing brace is relative to the -opening brace, which stands on its own line in this example. If the -opening brace was hanging on the previous line, then the closing brace -would get the @code{inlambda} syntax too to be indented correctly.}. - -@ssindex inexpr-statement -On line 9, @code{catch} is a special function taking a statement block -as its argument. The block is handled as an in-expression statement -with the @code{inexpr-statement} syntax, just like the gcc extended C -example above. The other similar special function, @code{gauge}, is -handled like this too. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node K&R Symbols, , Statement Block Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection K&R Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ssindex knr-argdecl-intro -@ssindex knr-argdecl -Two other syntactic symbols can appear in old style, non-prototyped C -code @footnote{a.k.a.@: K&R C, or Kernighan & Ritchie C}: - -@example - 1: int add_three_integers(a, b, c) - 2: int a; - 3: int b; - 4: int c; - 5: @{ - 6: return a + b + c; - 7: @} -@end example - -Here, line 2 is the first line in an argument declaration list and so is -given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines -(i.e., lines 3 and 4 in this example), are given @code{knr-argdecl} -syntax. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics -@comment node-name, next, previous, up -@section Indentation Calculation -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Indentation for a line is calculated from the syntactic context -(@pxref{Syntactic Analysis}). - -First, a buffer position is found whose column will be the base for the -indentation calculation. It's the anchor position in the first -syntactic element that provides one that is used. If no syntactic -element has an anchor position then column zero is used. - -Second, the syntactic symbols in each syntactic element are looked up -in the @code{c-offsets-alist} style variable -(@pxref{c-offsets-alist}), which is an association list of syntactic -symbols and the offsets to apply for those symbols. These offsets are -added together with the base column to produce the new indentation -column. - -Let's use our two code examples above to see how this works. Here is -our first example again: - -@example - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} -@end example - -Let's say point is on line 3 and we hit the @key{TAB} key to reindent -the line. The syntactic context for that line is: - -@example -((defun-block-intro 29)) -@end example - -@noindent -Since buffer position 29 is the first and only anchor position in the -list, @ccmode{} goes there and asks for the current column. This brace -is in column zero, so @ccmode{} uses @samp{0} as the base column. - -Next, @ccmode{} looks up @code{defun-block-intro} in the -@code{c-offsets-alist} style variable. Let's say it finds the value -@samp{4}; it adds this to the base column @samp{0}, yielding a running -total indentation of 4 spaces. - -Since there is only one syntactic element on the list for this line, -indentation calculation is complete, and the total indentation for the -line is 4 spaces. - -Here's another example: - -@example - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end example - -If we were to hit @kbd{TAB} on line 4 in the above example, the same -basic process is performed, despite the differences in the syntactic -context. The context for this line is: - -@example -((substatement-open 46)) -@end example - -Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in -@code{if} on line 3. This character is in the fourth column on that -line so the base column is @samp{4}. Then @ccmode{} looks up the -@code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it -finds the value @samp{4}. It's added with the base column and yields an -indentation for the line of 8 spaces. - -Simple, huh? - -Actually, it's a bit more complicated than that since the entries on -@code{c-offsets-alist} can be much more than plain offsets. -@xref{c-offsets-alist}, for the full story. - -Anyway, the mode usually just does The Right Thing without you having to -think about it in this much detail. But when customizing indentation, -it's helpful to understand the general indentation model being used. - -As you configure @ccmode{}, you might want to set the variable -@code{c-echo-syntactic-information-p} to non-@code{nil} so that the -syntactic context and calculated offset always is echoed in the -minibuffer when you hit @kbd{TAB}. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top -@comment node-name, next, previous, up -@chapter Customizing Indentation -@cindex customization, indentation -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The principal variable for customizing indentation is the style -variable @code{c-offsets-alist}, which gives an @dfn{offset} (an -indentation rule) for each syntactic symbol. Its structure and -semantics are completely described in @ref{c-offsets-alist}. The -various ways you can set the variable, including the use of the -@ccmode{} style system, are described in @ref{Config Basics} and its -sections, in particular @ref{Style Variables}. - -The simplest and most used kind of ``offset'' setting in -@code{c-offsets-alist} is in terms of multiples of -@code{c-basic-offset}: - -@defopt c-basic-offset -@vindex basic-offset (c-) -This style variable holds the basic offset between indentation levels. -It's factory default is 4, but all the built-in styles set it -themselves, to some value between 2 (for @code{gnu} style) and 8 (for -@code{bsd}, @code{linux}, and @code{python} styles). -@end defopt - -The most flexible ``offset'' setting you can make in -@code{c-offsets-alist} is a line-up function (or even a list of them), -either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one -you write yourself (@pxref{Custom Line-Up}). - -Finally, in @ref{Other Indentation} you'll find the tool of last -resort: a hook which is called after a line has been indented. You -can install functions here to make ad-hoc adjustments to any line's -indentation. - -@menu -* c-offsets-alist:: -* Interactive Customization:: -* Line-Up Functions:: -* Custom Line-Up:: -* Other Indentation:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation -@comment node-name, next, previous, up -@section c-offsets-alist -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This section explains the structure and semantics of the style -variable @code{c-offsets-alist}, the principal variable for configuring -indentation. Details of how to set it up, and its relationship to -@ccmode{}'s style system are given in @ref{Style Variables}. - -@defopt c-offsets-alist -@vindex offsets-alist (c-) -This is an alist which associates an offset with each syntactic -symbol. This @dfn{offset} is a rule specifying how to indent a line -whose syntactic context matches the symbol. @xref{Syntactic -Analysis}. - -Note that the buffer-local binding of this alist in a @ccmode{} buffer -contains an entry for @emph{every} syntactic symbol. Its global -binding and its settings within style specifications usually contain -only a few entries. @xref{Style Variables}. - -The offset specification associated with any particular syntactic -symbol can be an integer, a variable name, a vector, a function or -lambda expression, a list, or one of the following special symbols: -@code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The -meanings of these values are described in detail below. - -Here is an example fragment of a @code{c-offsets-alist}, showing some -of these kinds of offsets: - -@example -((statement . 0) - (substatement . +) - (cpp-macro . [0]) - (topmost-intro-cont . c-lineup-topmost-intro-cont) - (statement-block-intro . (add c-lineup-whitesmith-in-block - c-indent-multi-line-block)) - @dots{} -@*) -@end example -@end defopt - -@deffn Command c-set-offset (@kbd{C-c C-o}) -@findex set-offset (c-) -@kindex C-c C-o -This command changes the entry for a syntactic symbol in the current -binding of @code{c-offsets-alist}, or it inserts a new entry if there -isn't already one for that syntactic symbol. - -You can use @code{c-set-offsets} interactively within a @ccmode{} -buffer to make experimental changes to your indentation settings. -@kbd{C-c C-o} prompts you for the syntactic symbol to change -(defaulting to that of the current line) and the new offset -(defaulting to the current offset). - -@code{c-set-offsets} takes two arguments when used programmatically: -@var{symbol}, the syntactic element symbol to change and @var{offset}, -the new offset for that syntactic element. You can call the command -in your @file{.emacs} to change the global binding of -@code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a -hook function to make changes from the current style. @ccmode{} -itself uses this function when initializing styles. -@end deffn - -@cindex offset specification -The ``offset specifications'' in @code{c-offsets-alist} can be any of -the following: - -@table @asis -@item An integer -The integer specifies a relative offset. All relative -offsets@footnote{The syntactic context @code{@w{((defun-block-intro -2724) (comment-intro))}} would likely have two relative offsets.} will -be added together and used to calculate the indentation relative to an -anchor position earlier in the buffer. @xref{Indentation -Calculation}, for details. Most of the time, it's probably better to -use one of the special symbols like @code{+} than an integer (apart -from zero). - -@item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/} -These special symbols describe a relative offset in multiples of -@code{c-basic-offset}: - -By defining a style's indentation in terms of @code{c-basic-offset}, -you can change the amount of whitespace given to an indentation level -while maintaining the same basic shape of your code. Here are the -values that the special symbols correspond to: - -@table @code -@item + -@code{c-basic-offset} times 1 -@item - -@code{c-basic-offset} times @minus{}1 -@item ++ -@code{c-basic-offset} times 2 -@item -- -@code{c-basic-offset} times @minus{}2 -@item * -@code{c-basic-offset} times 0.5 -@item / -@code{c-basic-offset} times @minus{}0.5 -@end table - -@item A vector -The first element of the vector, an integer, sets the absolute -indentation column. This will override any previously calculated -indentation, but won't override relative indentation calculated from -syntactic elements later on in the syntactic context of the line being -indented. @xref{Indentation Calculation}. Any elements in the vector -beyond the first will be ignored. - -@item A function or lambda expression -The function will be called and its return value will in turn be -evaluated as an offset specification. Functions are useful when more -context than just the syntactic symbol is needed to get the desired -indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for -details about them. - -@item A symbol with a variable binding -If the symbol also has a function binding, the function takes -precedence over the variable. Otherwise the value of the variable is -used. It must be an integer (which is used as relative offset) or a -vector (an absolute offset). - -@item A list -The offset can also be a list containing several offset -specifications; these are evaluated recursively and combined. A list -is typically only useful when some of the offsets are line-up -functions. A common strategy is calling a sequence of functions in -turn until one of them recognizes that it is appropriate for the -source line and returns a non-@code{nil} value. - -@code{nil} values are always ignored when the offsets are combined. -The first element of the list specifies the method of combining the -non-@code{nil} offsets from the remaining elements: - -@table @code -@item first -Use the first offset that doesn't evaluate to @code{nil}. Subsequent -elements of the list don't get evaluated. -@item min -Use the minimum of all the offsets. All must be either relative or -absolute; they can't be mixed. -@item max -Use the maximum of all the offsets. All must be either relative or -absolute; they can't be mixed. -@item add -Add all the evaluated offsets together. Exactly one of them may be -absolute, in which case the result is absolute. Any relative offsets -that preceded the absolute one in the list will be ignored in that case. -@end table - -As a compatibility measure, if the first element is none of the above -then it too will be taken as an offset specification and the whole list -will be combined according to the method @code{first}. -@end table - -@vindex c-strict-syntax-p -@vindex strict-syntax-p (c-) -If an offset specification evaluates to @code{nil}, then a relative -offset of 0 (zero) is used@footnote{There is however a variable -@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an -error to be signaled in that case. It's now considered obsolete since -it doesn't work well with some of the alignment functions that return -@code{nil} instead of zero. You should therefore leave -@code{c-strict-syntax-p} set to @code{nil}.}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation -@comment node-name, next, previous, up -@section Interactive Customization -@cindex customization, interactive -@cindex interactive customization -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -As an example of how to customize indentation, let's change the -style of this example@footnote{In this and subsequent examples, the -original code is formatted using the @samp{gnu} style unless otherwise -indicated. @xref{Styles}.}: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -@noindent -to: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -In other words, we want to change the indentation of braces that open a -block following a condition so that the braces line up under the -conditional, instead of being indented. Notice that the construct we -want to change starts on line 4. To change the indentation of a line, -we need to see which syntactic symbols affect the offset calculations -for that line. Hitting @kbd{C-c C-s} on line 4 yields: - -@example -((substatement-open 44)) -@end example - -@noindent -so we know that to change the offset of the open brace, we need to -change the indentation for the @code{substatement-open} syntactic -symbol. - -To do this interactively, just hit @kbd{C-c C-o}. This prompts -you for the syntactic symbol to change, providing a reasonable default. -In this case, the default is @code{substatement-open}, which is just the -syntactic symbol we want to change! - -After you hit return, @ccmode{} will then prompt you for the new -offset value, with the old value as the default. The default in this -case is @samp{+}, but we want no extra indentation so enter -@samp{0} and @kbd{RET}. This will associate the offset 0 with the -syntactic symbol @code{substatement-open}. - -To check your changes quickly, just hit @kbd{C-c C-q} -(@code{c-indent-defun}) to reindent the entire function. The example -should now look like: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -Notice how just changing the open brace offset on line 4 is all we -needed to do. Since the other affected lines are indented relative to -line 4, they are automatically indented the way you'd expect. For more -complicated examples, this might not always work. The general approach -to take is to always start adjusting offsets for lines higher up in the -file, then reindent and see if any following lines need further -adjustments. - -@c Move this bit to "Styles" (2005/10/7) -@deffn Command c-set-offset symbol offset -@findex set-offset (c-) -@kindex C-c C-o -This is the command bound to @kbd{C-c C-o}. It provides a convenient -way to set offsets on @code{c-offsets-alist} both interactively (see -the example above) and from your mode hook. - -It takes two arguments when used programmatically: @var{symbol} is the -syntactic element symbol to change and @var{offset} is the new offset -for that syntactic element. -@end deffn -@c End of MOVE THIS BIT. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation -@comment node-name, next, previous, up -@section Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex line-up function -@cindex indentation function -Often there are cases when a simple offset setting on a syntactic -symbol isn't enough to get the desired indentation---for example, you -might want to line up a closing parenthesis with the matching opening -one rather than indenting relative to its ``anchor point''. @ccmode{} -provides this flexibility with @dfn{line-up functions}. - -The way you associate a line-up function with a syntactic symbol is -described in @ref{c-offsets-alist}. @ccmode{} comes with many -predefined line-up functions for common situations. If none of these -does what you want, you can write your own. @xref{Custom Line-Up}. -Sometimes, it is easier to tweak the standard indentation by adding a -function to @code{c-special-indent-hook} (@pxref{Other Indentation}). - -The line-up functions haven't been adapted for AWK buffers or tested -with them. Some of them might work serendipitously. There shouldn't be -any problems writing custom line-up functions for AWK mode. - -The calling convention for line-up functions is described fully in -@ref{Custom Line-Up}. Roughly speaking, the return value is either an -offset itself (such as @code{+} or @code{[0]}) or it's @code{nil}, -meaning ``this function is inappropriate in this case; try a -different one''. @xref{c-offsets-alist}. - -The subsections below describe all the standard line-up functions, -categorized by the sort of token the lining-up centers around. For -each of these functions there is a ``works with'' list that indicates -which syntactic symbols the function is intended to be used with. - -@macro workswith -@emph{Works with:@ } -@end macro -@ifinfo -@unmacro workswith -@macro workswith -Works with: -@end macro -@end ifinfo - -@macro sssTBasicOffset -<--> @i{c-basic-offset}@c -@end macro - -@macro sssTsssTBasicOffset -<--><--> @i{c-basic-offset}@c -@end macro - -@macro hereFn{func} -<- @i{\func\}@c -@end macro - -@c The TeX backend seems to insert extra spaces around the argument. :P -@iftex -@unmacro hereFn -@macro hereFn{func} -<-@i{\func\}@c -@end macro -@end iftex - -@menu -* Brace/Paren Line-Up:: -* List Line-Up:: -* Operator Line-Up:: -* Comment Line-Up:: -* Misc Line-Up:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions -@comment node-name, next, previous, up -@subsection Brace and Parenthesis Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for braces, -parentheses and statements within brace blocks. - -@defun c-lineup-close-paren -@findex lineup-close-paren (c-) -Line up the closing paren under its corresponding open paren if the -open paren is followed by code. If the open paren ends its line, no -indentation is added. E.g.: - -@example -@group -main (int, - char ** - ) @hereFn{c-lineup-close-paren} -@end group -@end example - -@noindent -and - -@example -@group -main ( - int, char ** -) @hereFn{c-lineup-close-paren} -@end group -@end example - -As a special case, if a brace block is opened at the same line as the -open parenthesis of the argument list, the indentation is -@code{c-basic-offset} instead of the open paren column. See -@code{c-lineup-arglist} for further discussion of this ``DWIM'' measure. - -@workswith All @code{*-close} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@anchor{c-lineup-arglist-close-under-paren} -@defun c-lineup-arglist-close-under-paren -@findex lineup-arglist-close-under-paren (c-) -Set your @code{arglist-close} syntactic symbol to this line-up function -so that parentheses that close argument lists will line up under the -parenthesis that opened the argument list. It can also be used with -@code{arglist-cont} and @code{arglist-cont-nonempty} to line up all -lines inside a parenthesis under the open paren. - -As a special case, if a brace block is opened at the same line as the -open parenthesis of the argument list, the indentation is -@code{c-basic-offset} only. See @code{c-lineup-arglist} for further -discussion of this ``DWIM'' measure. - -@workswith Almost all symbols, but are typically most useful on -@code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and -@code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-indent-one-line-block -@findex indent-one-line-block (c-) -Indent a one line block @code{c-basic-offset} extra. E.g.: - -@example -@group -if (n > 0) - @{m+=n; n=0;@} @hereFn{c-indent-one-line-block} -@sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -if (n > 0) -@{ @hereFn{c-indent-one-line-block} - m+=n; n=0; -@} -@end group -@end example - -The block may be surrounded by any kind of parenthesis characters. -@code{nil} is returned if the line doesn't start with a one line block, -which makes the function usable in list expressions. - -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-indent-multi-line-block -@findex indent-multi-line-block (c-) -Indent a multiline block @code{c-basic-offset} extra. E.g.: - -@example -@group -int *foo[] = @{ - NULL, - @{17@}, @hereFn{c-indent-multi-line-block} -@end group -@end example - -@noindent -and - -@example -@group -int *foo[] = @{ - NULL, - @{ @hereFn{c-indent-multi-line-block} - 17 - @}, - @sssTBasicOffset{} -@end group -@end example - -The block may be surrounded by any kind of parenthesis characters. -@code{nil} is returned if the line doesn't start with a multiline -block, which makes the function usable in list expressions. - -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-runin-statements -@findex lineup-runin-statements (c-) -Line up statements for coding standards which place the first statement -in a block on the same line as the block opening brace@footnote{Run-in -style doesn't really work too well. You might need to write your own -custom line-up functions to better support this style.}. E.g.: - -@example -@group -int main() -@{ puts ("Hello!"); - return 0; @hereFn{c-lineup-runin-statements} -@} -@end group -@end example - -If there is no statement after the opening brace to align with, -@code{nil} is returned. This makes the function usable in list -expressions. - -@workswith The @code{statement} syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-inexpr-block -@findex lineup-inexpr-block (c-) -This can be used with the in-expression block symbols to indent the -whole block to the column where the construct is started. E.g., for Java -anonymous classes, this lines up the class under the @samp{new} keyword, -and in Pike it lines up the lambda function body under the @samp{lambda} -keyword. Returns @code{nil} if the block isn't part of such a -construct. - -@workswith @code{inlambda}, @code{inexpr-statement}, -@code{inexpr-class}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-after-whitesmith-blocks -@findex lineup-after-whitesmith-blocks (c-) -Compensate for Whitesmith style indentation of blocks. Due to the way -@ccmode{} calculates anchor positions for normal lines inside blocks, -this function is necessary for those lines to get correct Whitesmith -style indentation. Consider the following examples: - -@example -@group -int foo() - @{ - a; - x; @hereFn{c-lineup-after-whitesmith-blocks} -@end group -@end example - -@example -@group -int foo() - @{ - @{ - a; - @} - x; @hereFn{c-lineup-after-whitesmith-blocks} -@end group -@end example - -The fact that the line with @code{x} is preceded by a Whitesmith style -indented block in the latter case and not the first should not affect -its indentation. But since CC Mode in cases like this uses the -indentation of the preceding statement as anchor position, the @code{x} -would in the second case be indented too much if the offset for -@code{statement} was set simply to zero. - -This lineup function corrects for this situation by detecting if the -anchor position is at an open paren character. In that case, it instead -indents relative to the surrounding block just like -@code{c-lineup-whitesmith-in-block}. - -@workswith @code{brace-list-entry}, @code{brace-entry-open}, -@code{statement}, @code{arglist-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-whitesmith-in-block -@findex lineup-whitesmith-in-block (c-) -Line up lines inside a block in Whitesmith style. It's done in a way -that works both when the opening brace hangs and when it doesn't. E.g.: - -@example -@group -something - @{ - foo; @hereFn{c-lineup-whitesmith-in-block} - @} -@end group -@end example - -@noindent -and - -@example -@group -something @{ - foo; @hereFn{c-lineup-whitesmith-in-block} - @} -@sssTBasicOffset{} -@end group -@end example - -In the first case the indentation is kept unchanged, in the second -@code{c-basic-offset} is added. - -@workswith @code{defun-close}, @code{defun-block-intro}, -@code{inline-close}, @code{block-close}, @code{brace-list-close}, -@code{brace-list-intro}, @code{statement-block-intro}, -@code{arglist-intro}, @code{arglist-cont-nonempty}, -@code{arglist-close}, and all @code{in*} symbols, e.g., @code{inclass} -and @code{inextern-lang}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection List Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for lines which -form lists of items, usually separated by commas. - -The function @ref{c-lineup-arglist-close-under-paren}, which is mainly -for indenting a close parenthesis, is also useful for the lines -contained within parentheses. - -@defun c-lineup-arglist -@findex lineup-arglist (c-) -Line up the current argument line under the first argument. - -As a special case, if an argument on the same line as the open -parenthesis starts with a brace block opener, the indentation is -@code{c-basic-offset} only. This is intended as a ``DWIM'' measure in -cases like macros that contain statement blocks, e.g.: - -@example -@group -A_VERY_LONG_MACRO_NAME (@{ - some (code, with + long, lines * in[it]); - @}); -@sssTBasicOffset{} -@end group -@end example - -This is motivated partly because it's more in line with how code -blocks are handled, and partly since it approximates the behavior of -earlier CC Mode versions, which due to inaccurate analysis tended to -indent such cases this way. - -@workswith @code{arglist-cont-nonempty}, @code{arglist-close}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-arglist-intro-after-paren -@findex lineup-arglist-intro-after-paren (c-) -Line up a line to just after the open paren of the surrounding paren or -brace block. - -@workswith @code{defun-block-intro}, @code{brace-list-intro}, -@code{statement-block-intro}, @code{statement-case-intro}, -@code{arglist-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-multi-inher -@findex lineup-multi-inher (c-) -Line up the classes in C++ multiple inheritance clauses and member -initializers under each other. E.g.: - -@example -@group -Foo::Foo (int a, int b): - Cyphr (a), - Bar (b) @hereFn{c-lineup-multi-inher} -@end group -@end example - -@noindent -and - -@example -@group -class Foo - : public Cyphr, - public Bar @hereFn{c-lineup-multi-inher} -@end group -@end example - -@noindent -and - -@example -@group -Foo::Foo (int a, int b) - : Cyphr (a) - , Bar (b) @hereFn{c-lineup-multi-inher} -@end group -@end example - -@workswith @code{inher-cont}, @code{member-init-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-java-inher -@findex lineup-java-inher (c-) -Line up Java implements and extends declarations. If class names -follow on the same line as the @samp{implements}/@samp{extends} -keyword, they are lined up under each other. Otherwise, they are -indented by adding @code{c-basic-offset} to the column of the keyword. -E.g.: - -@example -@group -class Foo - extends - Bar @hereFn{c-lineup-java-inher} - @sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -class Foo - extends Cyphr, - Bar @hereFn{c-lineup-java-inher} -@end group -@end example - -@workswith @code{inher-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-java-throws -@findex lineup-java-throws (c-) -Line up Java throws declarations. If exception names follow on the -same line as the throws keyword, they are lined up under each other. -Otherwise, they are indented by adding @code{c-basic-offset} to the -column of the @samp{throws} keyword. The @samp{throws} keyword itself -is also indented by @code{c-basic-offset} from the function declaration -start if it doesn't hang. E.g.: - -@example -@group -int foo() - throws @hereFn{c-lineup-java-throws} - Bar @hereFn{c-lineup-java-throws} -@sssTsssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -int foo() throws Cyphr, - Bar, @hereFn{c-lineup-java-throws} - Vlod @hereFn{c-lineup-java-throws} -@end group -@end example - -@workswith @code{func-decl-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-template-args -@findex lineup-template-args (c-) -Line up the arguments of a template argument list under each other, but -only in the case where the first argument is on the same line as the -opening @samp{<}. - -To allow this function to be used in a list expression, @code{nil} is -returned if there's no template argument on the first line. - -@workswith @code{template-args-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-call -@findex lineup-ObjC-method-call (c-) -For Objective-C code, line up selector args as Emacs Lisp mode does -with function args: go to the position right after the message receiver, -and if you are at the end of the line, indent the current line -c-basic-offset columns from the opening bracket; otherwise you are -looking at the first character of the first method call argument, so -lineup the current line with it. - -@workswith @code{objc-method-call-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-args -@findex lineup-ObjC-method-args (c-) -For Objective-C code, line up the colons that separate args. The colon -on the current line is aligned with the one on the first line. - -@workswith @code{objc-method-args-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-args-2 -@findex lineup-ObjC-method-args-2 (c-) -Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on -the current line with the colon on the previous line. - -@workswith @code{objc-method-args-cont}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Operator Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for lines which -start with an operator, by lining it up with something on the previous -line. - -@defun c-lineup-argcont -@findex lineup-argcont (c-) -Line up a continued argument. E.g.: - -@example -@group -foo (xyz, aaa + bbb + ccc - + ddd + eee + fff); @hereFn{c-lineup-argcont} -@end group -@end example - -Only continuation lines like this are touched, @code{nil} is returned on -lines which are the start of an argument. - -Within a gcc @code{asm} block, @code{:} is recognized as an argument -separator, but of course only between operand specifications, not in the -expressions for the operands. - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-arglist-operators -@findex lineup-arglist-operators (c-) -Line up lines starting with an infix operator under the open paren. -Return @code{nil} on lines that don't start with an operator, to leave -those cases to other line-up functions. Example: - -@example -@group -if ( x < 10 - || at_limit (x, @hereFn{c-lineup-arglist-operators} - list) @hereFn{c-lineup-arglist-operators@r{ returns nil}} - ) -@end group -@end example - -Since this function doesn't do anything for lines without an infix -operator you typically want to use it together with some other lineup -settings, e.g., as follows (the @code{arglist-close} setting is just a -suggestion to get a consistent style): - -@example -(c-set-offset 'arglist-cont - '(c-lineup-arglist-operators 0)) -(c-set-offset 'arglist-cont-nonempty - '(c-lineup-arglist-operators c-lineup-arglist)) -(c-set-offset 'arglist-close - '(c-lineup-arglist-close-under-paren)) -@end example - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-assignments -@findex lineup-assignments (c-) -Line up the current line after the assignment operator on the first line -in the statement. If there isn't any, return @code{nil} to allow stacking with -other line-up functions. If the current line contains an assignment -operator too, try to align it with the first one. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. - -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-math -@findex lineup-math (c-) -Like @code{c-lineup-assignments} but indent with @code{c-basic-offset} -if no assignment operator was found on the first line. I.e., this -function is the same as specifying a list @code{(c-lineup-assignments -+)}. It's provided for compatibility with old configurations. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-cascaded-calls -@findex lineup-cascaded-calls (c-) -Line up ``cascaded calls'' under each other. If the line begins with -@code{->} or @code{.} and the preceding line ends with one or more -function calls preceded by the same token, then the arrow is lined up -with the first of those tokens. E.g.: - -@example -@group -r = proc->add(17)->add(18) - ->add(19) + @hereFn{c-lineup-cascaded-calls} - offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}} -@end group -@end example - -In any other situation @code{nil} is returned to allow use in list -expressions. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-streamop -@findex lineup-streamop (c-) -Line up C++ stream operators (i.e., @samp{<<} and @samp{>>}). - -@workswith @code{stream-op}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-string-cont -@findex lineup-string-cont (c-) -Line up a continued string under the one it continues. A continued -string in this sense is where a string literal follows directly after -another one. E.g.: - -@example -@group -result = prefix + "A message " - "string."; @hereFn{c-lineup-string-cont} -@end group -@end example - -@code{nil} is returned in other situations, to allow stacking with other -lineup functions. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Comment Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The lineup functions here calculate the indentation for several types -of comment structure. - -@defun c-lineup-C-comments -@findex lineup-C-comments (c-) -Line up C block comment continuation lines. Various heuristics are used -to handle most of the common comment styles. Some examples: - -@example -@group -/* /** /* - * text * text text - */ */ */ -@end group -@end example - -@example -@group -/* text /* /** - text ** text ** text -*/ */ */ -@end group -@end example - -@example -@group -/************************************************** - * text - *************************************************/ -@end group -@end example - -@vindex comment-start-skip -@example -@group -/************************************************** - Free form text comments: - In comments with a long delimiter line at the - start, the indentation is kept unchanged for lines - that start with an empty comment line prefix. The - delimiter line is whatever matches the - @code{comment-start-skip} regexp. -**************************************************/ -@end group -@end example - -The style variable @code{c-comment-prefix-regexp} is used to recognize -the comment line prefix, e.g., the @samp{*} that usually starts every -line inside a comment. - -@workswith The @code{c} syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-comment -@findex lineup-comment (c-) -Line up a comment-only line according to the style variable -@code{c-comment-only-line-offset}. If the comment is lined up with a -comment starter on the previous line, that alignment is preserved. - -@defopt c-comment-only-line-offset -@vindex comment-only-line-offset (c-) -This style variable specifies the extra offset for the line. It can -contain an integer or a cons cell of the form - -@example -(@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}}) -@end example - -@noindent -where @var{non-anchored-offset} is the amount of offset given to -non-column-zero anchored lines, and @var{anchored-offset} is the amount -of offset to give column-zero anchored lines. Just an integer as value -is equivalent to @code{(@r{@var{value}} . -1000)}. -@end defopt - -@workswith @code{comment-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-knr-region-comment -@findex lineup-knr-region-comment (c-) -Line up a comment in the ``K&R region'' with the declaration. That is -the region between the function or class header and the beginning of the -block. E.g.: - -@example -@group -int main() -/* Called at startup. */ @hereFn{c-lineup-knr-region-comment} -@{ - return 0; -@} -@end group -@end example - -Return @code{nil} if called in any other situation, to be useful in list -expressions. - -@workswith @code{comment-intro}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Misc Line-Up, , Comment Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Miscellaneous Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here are the odds and ends which didn't fit into -any earlier category. - -@defun c-lineup-dont-change -@findex lineup-dont-change (c-) -This lineup function makes the line stay at whatever indentation it -already has; think of it as an identity function for lineups. - -@workswith Any syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-cpp-define -@findex lineup-cpp-define (c-) -Line up macro continuation lines according to the indentation of the -construct preceding the macro. E.g.: - -@example -@group -const char msg[] = @hereFn{@r{The beginning of the preceding construct.}} - \"Some text.\"; - -#define X(A, B) \ -do @{ \ @hereFn{c-lineup-cpp-define} - printf (A, B); \ -@} while (0) -@end group -@end example - -@noindent -and: - -@example -@group -int dribble() @{ - if (!running) @hereFn{@r{The beginning of the preceding construct.}} - error(\"Not running!\"); - -#define X(A, B) \ - do @{ \ @hereFn{c-lineup-cpp-define} - printf (A, B); \ - @} while (0) -@end group -@end example - -If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the -function returns the relative indentation to the macro start line to -allow accumulation with other offsets. E.g., in the following cases, -@code{cpp-define-intro} is combined with the -@code{statement-block-intro} that comes from the @samp{do @{} that hangs -on the @samp{#define} line: - -@example -@group -const char msg[] = - \"Some text.\"; - -#define X(A, B) do @{ \ - printf (A, B); \ @hereFn{c-lineup-cpp-define} - this->refs++; \ -@} while (0) @hereFn{c-lineup-cpp-define} -@end group -@end example - -@noindent -and: - -@example -@group -int dribble() @{ - if (!running) - error(\"Not running!\"); - -#define X(A, B) do @{ \ - printf (A, B); \ @hereFn{c-lineup-cpp-define} - this->refs++; \ - @} while (0) @hereFn{c-lineup-cpp-define} -@end group -@end example - -The relative indentation returned by @code{c-lineup-cpp-define} is zero -and two, respectively, on the two lines in each of these examples. They -are then added to the two column indentation that -@code{statement-block-intro} gives in both cases here. - -If the relative indentation is zero, then @code{nil} is returned -instead. That is useful in a list expression to specify the default -indentation on the top level. - -If @code{c-syntactic-indentation-in-macros} is @code{nil} then this -function keeps the current indentation, except for empty lines (ignoring -the ending backslash) where it takes the indentation from the closest -preceding nonempty line in the macro. If there's no such line in the -macro then the indentation is taken from the construct preceding it, as -described above. - -@workswith @code{cpp-define-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-gcc-asm-reg -@findex lineup-gcc-asm-reg (c-) -Line up a gcc asm register under one on a previous line. - -@example -@group - asm ("foo %1, %0\n" - "bar %0, %1" - : "=r" (w), - "=r" (x) - : "0" (y), - "1" (z)); -@end group -@end example - -The @samp{x} line is aligned to the text after the @samp{:} on the -@samp{w} line, and similarly @samp{z} under @samp{y}. - -This is done only in an @samp{asm} or @samp{__asm__} block, and only to -those lines mentioned. Anywhere else @code{nil} is returned. The usual -arrangement is to have this routine as an extra feature at the start of -arglist lineups, e.g.: - -@example -(c-lineup-gcc-asm-reg c-lineup-arglist) -@end example - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-topmost-intro-cont -@findex lineup-topmost-intro-cont (c-) -Line up declaration continuation lines zero or one indentation -step@footnote{This function is mainly provided to mimic the behavior of -CC Mode 5.28 and earlier where this case wasn't handled consistently so -that those lines could be analyzed as either topmost-intro-cont or -statement-cont. It's used for @code{topmost-intro-cont} by default, but -you might consider using @code{+} instead.}. For lines preceding a -definition, zero is used. For other lines, @code{c-basic-offset} is -added to the indentation. E.g.: - -@example -@group -int -neg (int i) @hereFn{c-lineup-topmost-intro-cont} -@{ - return -i; -@} -@end group -@end example - -@noindent -and - -@example -@group -struct -larch @hereFn{c-lineup-topmost-intro-cont} -@{ - double height; -@} - the_larch, @hereFn{c-lineup-topmost-intro-cont} - another_larch; @hereFn{c-lineup-topmost-intro-cont} -@sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -struct larch -the_larch, @hereFn{c-lineup-topmost-intro-cont} - another_larch; @hereFn{c-lineup-topmost-intro-cont} -@end group -@end example - -@workswith @code{topmost-intro-cont}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation -@comment node-name, next, previous, up -@section Custom Line-Up Functions -@cindex customization, indentation functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The most flexible way to customize indentation is by writing custom -line-up functions, and associating them with specific syntactic -symbols (@pxref{c-offsets-alist}). Depending on the effect you want, -it might be better to write a @code{c-special-indent-hook} function -rather than a line-up function (@pxref{Other Indentation}). - -@ccmode{} comes with an extensive set of predefined line-up functions, -not all of which are used by the default styles. So there's a good -chance the function you want already exists. @xref{Line-Up -Functions}, for a list of them. If you write your own line-up -function, it's probably a good idea to start working from one of these -predefined functions, which can be found in the file -@file{cc-align.el}. If you have written a line-up function that you -think is generally useful, you're very welcome to contribute it; -please contact @email{bug-cc-mode@@gnu.org}. - - Line-up functions are passed a single argument, the syntactic -element (see below). At the time of the call, point will be somewhere -on the line being indented. The return value is a -@code{c-offsets-alist} offset specification: for example, an integer, -a symbol such as @code{+}, a vector, @code{nil}@footnote{Returning -@code{nil} is useful when the offset specification for a syntactic -element is a list containing the line-up function -(@pxref{c-offsets-alist}).}, or even another line-up function. Full -details of these are in @ref{c-offsets-alist}. - -Line-up functions must not move point or change the content of the -buffer (except temporarily). They are however allowed to do -@dfn{hidden buffer changes}, i.e., setting text properties for caching -purposes etc. Buffer undo recording is disabled while they run. - -The syntactic element passed as the parameter to a line-up function is -a cons cell of the form - -@example -(@r{@var{syntactic-symbol}} . @r{@var{anchor-position}}) -@end example - -@noindent -@c FIXME!!! The following sentence might be better omitted, since the -@c information is in the cross reference "Syntactic Analysis". 2005/10/2. -where @var{syntactic-symbol} is the symbol that the function was -called for, and @var{anchor-position} is the anchor position (if any) -for the construct that triggered the syntactic symbol -(@pxref{Syntactic Analysis}). This cons cell is how the syntactic -element of a line used to be represented in @ccmode{} 5.28 and -earlier. Line-up functions are still passed this cons cell, so as to -preserve compatibility with older configurations. In the future, we -may decide to convert to using the full list format---you can prepare -your setup for this by using the access functions -(@code{c-langelem-sym}, etc.)@: described below. - -@vindex c-syntactic-element -@vindex syntactic-element (c-) -@vindex c-syntactic-context -@vindex syntactic-context (c-) -Some syntactic symbols, e.g., @code{arglist-cont-nonempty}, have more -info in the syntactic element: typically other positions that can be -interesting besides the anchor position. That info can't be accessed -through the passed argument, which is a cons cell. Instead, you can -get this information from the variable @code{c-syntactic-element}, -which is dynamically bound to the complete syntactic element. The -variable @code{c-syntactic-context} might also be useful: it gets -dynamically bound to the complete syntactic context. @xref{Custom -Braces}. - -@ccmode{} provides a few functions to access parts of syntactic -elements in a more abstract way. Besides making the code easier to -read, they also hide the difference between the old cons cell form -used in the line-up function argument and the new list form used in -@code{c-syntactic-element} and everywhere else. The functions are: - -@defun c-langelem-sym langelem -@findex langelem-sym (c-) -Return the syntactic symbol in @var{langelem}. -@end defun - -@defun c-langelem-pos langelem -@findex langelem-pos (c-) -Return the anchor position in @var{langelem}, or @code{nil} if there is none. -@end defun - -@defun c-langelem-col langelem &optional preserve-point -@findex langelem-col (c-) -Return the column of the anchor position in @var{langelem}. Also move -the point to that position unless @var{preserve-point} is -non-@code{nil}. -@end defun - -@defun c-langelem-2nd-pos langelem -@findex langelem-2nd-pos (c-) -Return the secondary position in @var{langelem}, or @code{nil} if there -is none. - -Note that the return value of this function is always @code{nil} if -@var{langelem} is in the old cons cell form. Thus this function is -only meaningful when used on syntactic elements taken from -@code{c-syntactic-element} or @code{c-syntactic-context}. -@end defun - -Custom line-up functions can be as simple or as complex as you like, and -any syntactic symbol that appears in @code{c-offsets-alist} can have a -custom line-up function associated with it. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Indentation, , Custom Line-Up, Customizing Indentation -@comment node-name, next, previous, up -@section Other Special Indentations -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -To configure macros which you invoke without a terminating @samp{;}, -see @xref{Macros with ;}. - -Here are the remaining odds and ends regarding indentation: - -@defopt c-label-minimum-indentation -@vindex label-minimum-indentation (c-) -In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is -imposed on lines inside code blocks. This minimum indentation is -controlled by this style variable. The default value is 1. - -@findex c-gnu-impose-minimum -@findex gnu-impose-minimum (c-) -It's the function @code{c-gnu-impose-minimum} that enforces this minimum -indentation. It must be present on @code{c-special-indent-hook} to -work. -@end defopt - -@defopt c-special-indent-hook -@vindex special-indent-hook (c-) -This style variable is a standard hook variable that is called after -every line is indented by @ccmode{}. It is called only if -@code{c-syntactic-indentation} is non-@code{nil} (which it is by -default (@pxref{Indentation Engine Basics})). You can put a function -on this hook to do any special indentation or ad hoc line adjustments -your style dictates, such as adding extra indentation to constructors -or destructor declarations in a class definition, etc. Sometimes it -is better to write a custom Line-up Function instead (@pxref{Custom -Line-Up}). - -When the indentation engine calls this hook, the variable -@code{c-syntactic-context} is bound to the current syntactic context -(i.e., what you would get by typing @kbd{C-c C-s} on the source line. -@xref{Custom Braces}.). Note that you should not change point or mark -inside a @code{c-special-indent-hook} function, i.e., you'll probably -want to wrap your function in a @code{save-excursion}@footnote{The -numerical value returned by @code{point} will change if you change the -indentation of the line within a @code{save-excursion} form, but point -itself will still be over the same piece of text.}. - -Setting @code{c-special-indent-hook} in style definitions is handled -slightly differently from other variables---A style can only add -functions to this hook, not remove them. @xref{Style Variables}. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Macros, Odds and Ends, Customizing Indentation, Top -@comment node-name, next, previous, up -@chapter Customizing Macros -@cindex macros -@cindex preprocessor directives -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Preprocessor macros in C, C++, and Objective C (introduced by -@code{#define}) have a syntax different from the main language---for -example, a macro declaration is not terminated by a semicolon, and if -it is more than a line long, line breaks in it must be escaped with -backslashes. @ccmode{} has some commands to manipulate these, see -@ref{Macro Backslashes}. - -Normally, the lines in a multi-line macro are indented relative to -each other as though they were code. You can suppress this behavior -by setting the following user option: - -@defopt c-syntactic-indentation-in-macros -@vindex syntactic-indentation-in-macros (c-) -Enable syntactic analysis inside macros, which is the default. If this -is @code{nil}, all lines inside macro definitions are analyzed as -@code{cpp-macro-cont}. -@end defopt - -Because a macro can expand into anything at all, near where one is -invoked @ccmode{} can only indent and fontify code heuristically. -Sometimes it gets it wrong. Usually you should try to design your -macros so that they ''look like ordinary code'' when you invoke them. -However, one situation is so common that @ccmode{} handles it -specially: that is when certain macros needn't (or mustn't) be -followed by a @samp{;}. You need to configure @ccmode{} to handle -these macros properly, see @ref{Macros with ;}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@menu -* Macro Backslashes:: -* Macros with ;:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Macro Backslashes, Macros with ;, Custom Macros, Custom Macros -@comment node-name, next, previous, up -@section Customizing Macro Backslashes -@cindex @code{#define} -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} provides some tools to help keep the line continuation -backslashes in macros neat and tidy. Their precise action is -customized with these variables: - -@defopt c-backslash-column -@vindex backslash-column (c-) -@defoptx c-backslash-max-column -@vindex backslash-max-column (c-) -These variables control the alignment columns for line continuation -backslashes in multiline macros. They are used by the functions that -automatically insert or align such backslashes, -e.g., @code{c-backslash-region} and @code{c-context-line-break}. - -@code{c-backslash-column} specifies the minimum column for the -backslashes. If any line in the macro goes past this column, then the -next tab stop (i.e., next multiple of @code{tab-width}) in that line is -used as the alignment column for all the backslashes, so that they -remain in a single column. However, if any lines go past -@code{c-backslash-max-column} then the backslashes in the rest of the -macro will be kept at that column, so that the lines which are too -long ``stick out'' instead. - -Don't ever set these variables to @code{nil}. If you want to disable -the automatic alignment of backslashes, use -@code{c-auto-align-backslashes}. -@end defopt - -@defopt c-auto-align-backslashes -@vindex auto-align-backslashes (c-) -Align automatically inserted line continuation backslashes if -non-@code{nil}. When line continuation backslashes are inserted -automatically for line breaks in multiline macros, e.g., by -@code{c-context-line-break}, they are aligned with the other -backslashes in the same macro if this flag is set. - -If @code{c-auto-align-backslashes} is @code{nil}, automatically -inserted backslashes are preceded by a single space, and backslashes -get aligned only when you explicitly invoke the command -@code{c-backslash-region} (@kbd{C-c C-\}). -@end defopt - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Macros with ;, , Macro Backslashes, Custom Macros -@comment node-name, next, previous, up -@section Macros with semicolons -@cindex macros with semicolons -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Macros which needn't (or mustn't) be followed by a semicolon when you -invoke them, @dfn{macros with semicolons}, are very common. These can -cause @ccmode{} to parse the next line wrongly as a -@code{statement-cont} (@pxref{Function Symbols}) and thus mis-indent -it. - -You can prevent this by specifying which macros have semicolons. It -doesn't matter whether or not such a macro has a parameter list: - -@defopt c-macro-names-with-semicolon -@vindex macro-names-with-semicolon (c-) -This buffer-local variable specifies which macros have semicolons. -After setting its value, you need to call -@code{c-make-macro-with-semi-re} for it to take effect. It should be -set to one of these values: - -@table @asis -@item nil -There are no macros with semicolons. -@item a list of strings -Each string is the name of a macro with a semicolon. Only valid -@code{#define} names are allowed here. For example, to set the -default value, you could write the following into your @file{.emacs}: - -@example -(setq c-macro-names-with-semicolon - '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS")) -@end example - -@item a regular expression -This matches each symbol which is a macro with a semicolon. It must -not match any string which isn't a valid @code{#define} name. For -example: - -@example -(setq c-macro-names-with-semicolon - "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>") -@end example -@end table -@end defopt - -@defun c-make-macro-with-semi-re -@findex make-macro-with-semi-re (c-) -Call this (non-interactive) function, which sets internal variables, -each time you change the value of -@code{c-macro-names-with-semicolon}. It takes no arguments, and its -return value has no meaning. This function is called by @ccmode{}'s -initialization code. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Odds and Ends, Sample Init File, Custom Macros, Top -@comment node-name, next, previous, up -@chapter Odds and Ends -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The stuff that didn't fit in anywhere else is documented here. - -@defopt c-require-final-newline -@vindex require-final-newline (c-) -Controls whether a final newline is enforced when the file is saved. -The value is an association list that for each language mode specifies -the value to give to @code{require-final-newline} (@pxref{Saving -Buffers,,,@lispref{}, @lispreftitle{}}) at mode initialization. If a -language isn't present on the association list, CC Mode won't touch -@code{require-final-newline} in buffers for that language. - -The default is to set @code{require-final-newline} to @code{t} in the -languages that mandate that source files should end with newlines. -These are C, C++ and Objective-C. -@end defopt - -@defopt c-echo-syntactic-information-p -@vindex echo-syntactic-information-p (c-) -If non-@code{nil}, the syntactic analysis for the current line is shown -in the echo area when it's indented (unless -@code{c-syntactic-indentation} is @code{nil}). That's useful when -finding out which syntactic symbols to modify to get the indentation you -want. -@end defopt - -@defopt c-report-syntactic-errors -@vindex report-syntactic-errors (c-) -If non-@code{nil}, certain syntactic errors are reported with a ding and -a message, for example when an @code{else} is indented for which there -is no corresponding @code{if}. - -Note however that @ccmode{} doesn't make any special effort to check for -syntactic errors; that's the job of the compiler. The reason it can -report cases like the one above is that it can't find the correct -anchoring position to indent the line in that case. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Sample Init File, Performance Issues, Odds and Ends, Top -@comment node-name, next, previous, up -@appendix Sample Init File -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here's a sample .emacs file fragment that might help you along the way. -Just copy this region and paste it into your .emacs file. You might want -to change some of the actual values. - -@verbatim -;; Make a non-standard key binding. We can put this in -;; c-mode-base-map because c-mode-map, c++-mode-map, and so on, -;; inherit from it. -(defun my-c-initialization-hook () - (define-key c-mode-base-map "\C-m" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-c-initialization-hook) - -;; offset customizations not in my-c-style -;; This will take precedence over any setting of the syntactic symbol -;; made by a style. -(setq c-offsets-alist '((member-init-intro . ++))) - -;; Create my personal style. -(defconst my-c-style - '((c-tab-always-indent . t) - (c-comment-only-line-offset . 4) - (c-hanging-braces-alist . ((substatement-open after) - (brace-list-open))) - (c-hanging-colons-alist . ((member-init-intro before) - (inher-intro) - (case-label after) - (label after) - (access-label after))) - (c-cleanup-list . (scope-operator - empty-defun-braces - defun-close-semi)) - (c-offsets-alist . ((arglist-close . c-lineup-arglist) - (substatement-open . 0) - (case-label . 4) - (block-open . 0) - (knr-argdecl-intro . -))) - (c-echo-syntactic-information-p . t)) - "My C Programming Style") -(c-add-style "PERSONAL" my-c-style) - -;; Customizations for all modes in CC Mode. -(defun my-c-mode-common-hook () - ;; set my personal style for the current buffer - (c-set-style "PERSONAL") - ;; other customizations - (setq tab-width 8 - ;; this will make sure spaces are used instead of tabs - indent-tabs-mode nil) - ;; we like auto-newline, but not hungry-delete - (c-toggle-auto-newline 1)) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end verbatim - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Performance Issues, Limitations and Known Bugs, Sample Init File, Top -@comment node-name, next, previous, up -@chapter Performance Issues -@cindex performance -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here. - -C and its derivative languages are highly complex creatures. Often, -ambiguous code situations arise that require @ccmode{} to scan large -portions of the buffer to determine syntactic context. Such -pathological code can cause @ccmode{} to perform fairly badly. This -section gives some insight in how @ccmode{} operates, how that interacts -with some coding styles, and what you can use to improve performance. - -The overall goal is that @ccmode{} shouldn't be overly slow (i.e., take -more than a fraction of a second) in any interactive operation. -I.e., it's tuned to limit the maximum response time in single operations, -which is sometimes at the expense of batch-like operations like -reindenting whole blocks. If you find that @ccmode{} gradually gets -slower and slower in certain situations, perhaps as the file grows in -size or as the macro or comment you're editing gets bigger, then chances -are that something isn't working right. You should consider reporting -it, unless it's something that's mentioned in this section. - -Because @ccmode{} has to scan the buffer backwards from the current -insertion point, and because C's syntax is fairly difficult to parse in -the backwards direction, @ccmode{} often tries to find the nearest -position higher up in the buffer from which to begin a forward scan -(it's typically an opening or closing parenthesis of some kind). The -farther this position is from the current insertion point, the slower it -gets. - -@findex beginning-of-defun -In earlier versions of @ccmode{}, we used to recommend putting the -opening brace of a top-level construct@footnote{E.g., a function in C, -or outermost class definition in C++ or Java.} into the leftmost -column. Earlier still, this used to be a rigid Emacs constraint, as -embodied in the @code{beginning-of-defun} function. @ccmode now -caches syntactic information much better, so that the delay caused by -searching for such a brace when it's not in column 0 is minimal, -except perhaps when you've just moved a long way inside the file. - -@findex defun-prompt-regexp -@vindex c-Java-defun-prompt-regexp -@vindex Java-defun-prompt-regexp (c-) -A special note about @code{defun-prompt-regexp} in Java mode: The common -style is to hang the opening braces of functions and classes on the -right side of the line, and that doesn't work well with the Emacs -approach. @ccmode{} comes with a constant -@code{c-Java-defun-prompt-regexp} which tries to define a regular -expression usable for this style, but there are problems with it. In -some cases it can cause @code{beginning-of-defun} to hang@footnote{This -has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, -it is not used by default, but if you feel adventurous, you can set -@code{defun-prompt-regexp} to it in your mode hook. In any event, -setting and relying on @code{defun-prompt-regexp} will definitely slow -things down because (X)Emacs will be doing regular expression searches a -lot, so you'll probably be taking a hit either way! - -@ccmode{} maintains a cache of the opening parentheses of the blocks -surrounding the point, and it adapts that cache as the point is moved -around. That means that in bad cases it can take noticeable time to -indent a line in a new surrounding, but after that it gets fast as long -as the point isn't moved far off. The farther the point is moved, the -less useful is the cache. Since editing typically is done in ``chunks'' -rather than on single lines far apart from each other, the cache -typically gives good performance even when the code doesn't fit the -Emacs approach to finding the defun starts. - -@vindex c-enable-xemacs-performance-kludge-p -@vindex enable-xemacs-performance-kludge-p (c-) -XEmacs users can set the variable -@code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This -tells @ccmode{} to use XEmacs-specific built-in functions which, in some -circumstances, can locate the top-most opening brace much more quickly than -@code{beginning-of-defun}. Preliminary testing has shown that for -styles where these braces are hung (e.g., most JDK-derived Java styles), -this hack can improve performance of the core syntax parsing routines -from 3 to 60 times. However, for styles which @emph{do} conform to -Emacs's recommended style of putting top-level braces in column zero, -this hack can degrade performance by about as much. Thus this variable -is set to @code{nil} by default, since the Emacs-friendly styles should -be more common (and encouraged!). Note that this variable has no effect -in Emacs since the necessary built-in functions don't exist (in Emacs -22.1 as of this writing in February 2007). - -Text properties are used to speed up skipping over syntactic whitespace, -i.e., comments and preprocessor directives. Indenting a line after a -huge macro definition can be slow the first time, but after that the -text properties are in place and it should be fast (even after you've -edited other parts of the file and then moved back). - -Font locking can be a CPU hog, especially the font locking done on -decoration level 3 which tries to be very accurate. Note that that -level is designed to be used with a font lock support mode that only -fontifies the text that's actually shown, i.e., Lazy Lock or Just-in-time -Lock mode, so make sure you use one of them. Fontification of a whole -buffer with some thousand lines can often take over a minute. That is -a known weakness; the idea is that it never should happen. - -The most effective way to speed up font locking is to reduce the -decoration level to 2 by setting @code{font-lock-maximum-decoration} -appropriately. That level is designed to be as pretty as possible -without sacrificing performance. @xref{Font Locking Preliminaries}, for -more info. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Limitations and Known Bugs, FAQ, Performance Issues, Top -@comment node-name, next, previous, up -@chapter Limitations and Known Bugs -@cindex limitations -@cindex bugs -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@itemize @bullet -@item -@ccmode{} doesn't support trigraphs. (These are character sequences -such as @samp{??(}, which represents @samp{[}. They date from a time -when some character sets didn't have all the characters that C needs, -and are now utterly obsolete.) - -@item -There is no way to apply auto newline settings (@pxref{Auto-newlines}) -on already typed lines. That's only a feature to ease interactive -editing. - -To generalize this issue a bit: @ccmode{} is not intended to be used as -a reformatter for old code in some more or less batch-like way. With -the exception of some functions like @code{c-indent-region}, it's only -geared to be used interactively to edit new code. There's currently no -intention to change this goal. - -If you want to reformat old code, you're probably better off using some -other tool instead, e.g., @ref{Top, , GNU indent, indent, The `indent' -Manual}, which has more powerful reformatting capabilities than -@ccmode{}. - -@item -The support for C++ templates (in angle brackets) is not yet complete. -When a non-nested template is used in a declaration, @ccmode{} indents -it and font-locks it OK@. Templates used in expressions, and nested -templates do not fare so well. Sometimes a workaround is to refontify -the expression after typing the closing @samp{>}. - -@item -In a @dfn{k&r region} (the part of an old-fashioned C function -declaration which specifies the types of its parameters, coming -between the parameter list and the opening brace), there should be at -most 20 top-level parenthesis and bracket pairs. This limit has been -imposed for performance reasons. If it is violated, the source file -might be incorrectly indented or fontified. - -@item -On loading @ccmode{}, sometimes this error message appears: - -@example -File mode specification error: (void-variable c-font-lock-keywords-3) -@end example - -This is due to a bug in the function @code{eval-after-load} in some -versions of (X)Emacs. It can manifest itself when there is a symbolic -link in the path of the directory which contains (X)Emacs. As a -workaround, put the following into your @file{.emacs} file, fairly -early on: - -@example -(defun my-load-cc-fonts () - (require "cc-fonts")) -(add-hook 'c-initialization-hook 'my-load-cc-fonts) -@end example -@end itemize - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node FAQ, Updating CC Mode, Limitations and Known Bugs, Top -@comment node-name, next, previous, up -@appendix Frequently Asked Questions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@itemize @bullet -@item -@emph{How can I change the indent level from 4 spaces to 2 spaces?} - -Set the variable @code{c-basic-offset}. @xref{Getting Started}. - -@item -@kindex RET -@kindex C-j -@emph{Why does/doesn't the @kbd{RET} key indent the new line?} - -Emacs's convention used to be that @kbd{RET} just adds a newline, and that -@kbd{C-j} adds a newline and indents it. In Emacs-24.4, this convention was -reversed. - -If you use an older Emacs and you want @kbd{RET} do this -too, add this to your @code{c-initialization-hook}: - -@example -(define-key c-mode-base-map "\C-m" 'c-context-line-break) -@end example - -@xref{Getting Started}. This was a very common question. - -@item -@emph{How do I stop my code jumping all over the place when I type?} - -Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting -Started}. - -@item -@kindex C-x h -@kindex C-M-\ -@emph{How do I reindent the whole file?} - -Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit -@kbd{C-M-\}. @xref{Indentation Commands}. - -@item -@kindex C-M-q -@kindex C-M-u -@emph{How do I reindent the current block?} - -First move to the brace which opens the block with @kbd{C-M-u}, then -reindent that expression with @kbd{C-M-q}. @xref{Indentation -Commands}. - -@item -@emph{I put @code{(c-set-offset 'substatement-open 0)} in my -@file{.emacs} file but I get an error saying that @code{c-set-offset}'s -function definition is void. What's wrong?} - -This means that @ccmode{} hasn't yet been loaded into your Emacs -session by the time the @code{c-set-offset} call is reached, most -likely because @ccmode{} is being autoloaded. Instead of putting the -@code{c-set-offset} line in your top-level @file{.emacs} file, put it -in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply -modify @code{c-offsets-alist} directly: - -@example -(setq c-offsets-alist '((substatement-open . 0))) -@end example - -@item -@cindex open paren in column zero -@emph{I have an open paren character at column zero inside a comment or -multiline string literal, and it causes the fontification and/or -indentation to go haywire. What gives?} - -It's due to the ad-hoc rule in (X)Emacs that such open parens always -start defuns (which translates to functions, classes, namespaces or any -other top-level block constructs in the @ccmode{} languages). -@ifset XEMACS -@xref{Defuns,,, xemacs, XEmacs User's Manual}, for details. -@end ifset -@ifclear XEMACS -@xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details -(@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual). -@end ifclear - -This heuristic is built into the core syntax analysis routines in -(X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs -21.1 it became possible to turn it off@footnote{Using the variable -@code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so -there since it's got its own system to keep track of blocks. - -@end itemize - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top -@comment node-name, next, previous, up -@appendix Getting the Latest CC Mode Release -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} has been standard with all versions of Emacs since 19.34 and -of XEmacs since 19.16. - -@cindex web site -Due to release schedule skew, it is likely that all of these Emacsen -have old versions of @ccmode{} and so should be upgraded. Access to the -@ccmode{} source code, as well as more detailed information on Emacsen -compatibility, etc. are all available on the web site: - -@quotation -@uref{http://cc-mode.sourceforge.net/} -@end quotation - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top -@comment node-name, next, previous, up -@appendix Mailing Lists and Submitting Bug Reports -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@kindex C-c C-b -@findex c-submit-bug-report -@findex submit-bug-report (c-) -To report bugs, use the @kbd{C-c C-b} (bound to -@code{c-submit-bug-report}) command. This provides vital information -we need to reproduce your problem. Make sure you include a concise, -but complete code example. Please try to boil your example down to -just the essential code needed to reproduce the problem, and include -an exact recipe of steps needed to expose the bug. Be especially sure -to include any code that appears @emph{before} your bug example, if -you think it might affect our ability to reproduce it. - -Please try to produce the problem in an Emacs instance without any -customizations loaded (i.e., start it with the @samp{-q --no-site-file} -arguments). If it works correctly there, the problem might be caused -by faulty customizations in either your own or your site -configuration. In that case, we'd appreciate it if you isolate the -Emacs Lisp code that triggers the bug and include it in your report. - -@cindex bug report mailing list -Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can -also send other questions and suggestions (kudos? @t{;-)} to that -address. It's a mailing list which you can join or browse an archive -of; see the web site at @uref{http://cc-mode.sourceforge.net/} for -further details. - -@cindex announcement mailing list -If you want to get announcements of new @ccmode{} releases, send the -word @emph{subscribe} in the body of a message to -@email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible -to subscribe from the web site too. Announcements will also be posted -to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs}, -@code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++}, -@code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools}, -@code{comp.lang.idl}, and @code{comp.lang.awk}. -@c There is no newsgroup for Pike. :-( - - -@node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@c Removed the tentative node "Mode Initialization" from here, 2005/8/27. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Command and Function Index, Variable Index, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Command and Function Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since most @ccmode{} commands are prepended with the string -@samp{c-}, each appears under its @code{c-@var{thing}} name and its -@code{@var{thing} (c-)} name. -@iftex -@sp 2 -@end iftex -@printindex fn - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Variable Index, Concept and Key Index, Command and Function Index, Top -@comment node-name, next, previous, up -@unnumbered Variable Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since most @ccmode{} variables are prepended with the string -@samp{c-}, each appears under its @code{c-@var{thing}} name and its -@code{@var{thing} (c-)} name. -@iftex -@sp 2 -@end iftex -@printindex vr - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Concept and Key Index, , Variable Index, Top -@comment node-name, next, previous, up -@unnumbered Concept and Key Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@printindex cp - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment Epilogue. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@bye diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi deleted file mode 100644 index 4eb8508fd3c..00000000000 --- a/doc/misc/cl.texi +++ /dev/null @@ -1,5150 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/cl -@settitle Common Lisp Extensions -@documentencoding UTF-8 -@include emacsver.texi - -@copying -This file documents the GNU Emacs Common Lisp emulation package. - -Copyright @copyright{} 1993, 2001--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs lisp libraries -@direntry -* CL: (cl). Partial Common Lisp support for Emacs Lisp. -@end direntry - -@finalout - -@titlepage -@sp 6 -@center @titlefont{Common Lisp Extensions} -@sp 4 -@center For GNU Emacs Lisp -@sp 1 -@center as distributed with Emacs @value{EMACSVER} -@sp 5 -@center Dave Gillespie -@center daveg@@synaptics.com -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top GNU Emacs Common Lisp Emulation - -@insertcopying -@end ifnottex - -@menu -* Overview:: Basics, usage, organization, naming conventions. -* Program Structure:: Arglists, @code{cl-eval-when}. -* Predicates:: Type predicates and equality predicates. -* Control Structure:: Assignment, conditionals, blocks, looping. -* Macros:: Destructuring, compiler macros. -* Declarations:: @code{cl-proclaim}, @code{cl-declare}, etc. -* Symbols:: Property lists, creating symbols. -* Numbers:: Predicates, functions, random numbers. -* Sequences:: Mapping, functions, searching, sorting. -* Lists:: Functions, substitution, sets, associations. -* Structures:: @code{cl-defstruct}. -* Assertions:: Assertions and type checking. - -Appendices -* Efficiency Concerns:: Hints and techniques. -* Common Lisp Compatibility:: All known differences with Steele. -* Porting Common Lisp:: Hints for porting Common Lisp code. -* Obsolete Features:: Obsolete features. -* GNU Free Documentation License:: The license for this documentation. - -Indexes -* Function Index:: An entry for each documented function. -* Variable Index:: An entry for each documented variable. -@end menu - -@node Overview -@chapter Overview - -@noindent -This document describes a set of Emacs Lisp facilities borrowed from -Common Lisp. All the facilities are described here in detail. While -this document does not assume any prior knowledge of Common Lisp, it -does assume a basic familiarity with Emacs Lisp. - -Common Lisp is a huge language, and Common Lisp systems tend to be -massive and extremely complex. Emacs Lisp, by contrast, is rather -minimalist in the choice of Lisp features it offers the programmer. -As Emacs Lisp programmers have grown in number, and the applications -they write have grown more ambitious, it has become clear that Emacs -Lisp could benefit from many of the conveniences of Common Lisp. - -The @dfn{CL} package adds a number of Common Lisp functions and -control structures to Emacs Lisp. While not a 100% complete -implementation of Common Lisp, it adds enough functionality -to make Emacs Lisp programming significantly more convenient. - -Some Common Lisp features have been omitted from this package -for various reasons: - -@itemize @bullet -@item -Some features are too complex or bulky relative to their benefit -to Emacs Lisp programmers. CLOS and Common Lisp streams are fine -examples of this group. (The separate package EIEIO implements -a subset of CLOS functionality. @xref{Top, , Introduction, eieio, EIEIO}.) - -@item -Other features cannot be implemented without modification to the -Emacs Lisp interpreter itself, such as multiple return values, -case-insensitive symbols, and complex numbers. -This package generally makes no attempt to emulate these features. - -@end itemize - -This package was originally written by Dave Gillespie, -@file{daveg@@synaptics.com}, as a total rewrite of an earlier 1986 -@file{cl.el} package by Cesar Quiroz. Care has been taken to ensure -that each function is defined efficiently, concisely, and with minimal -impact on the rest of the Emacs environment. Stefan Monnier added the -file @file{cl-lib.el} and rationalized the namespace for Emacs 24.3. - -@menu -* Usage:: How to use this package. -* Organization:: The package's component files. -* Naming Conventions:: Notes on function names. -@end menu - -@node Usage -@section Usage - -@noindent -This package is distributed with Emacs, so there is no need -to install any additional files in order to start using it. Lisp code -that uses features from this package should simply include at -the beginning: - -@example -(require 'cl-lib) -@end example - -@noindent -You may wish to add such a statement to your init file, if you -make frequent use of features from this package. - -@node Organization -@section Organization - -@noindent -The Common Lisp package is organized into four main files: - -@table @file -@item cl-lib.el -This is the main file, which contains basic functions -and information about the package. This file is relatively compact. - -@item cl-extra.el -This file contains the larger, more complex or unusual functions. -It is kept separate so that packages which only want to use Common -Lisp fundamentals like the @code{cl-incf} function won't need to pay -the overhead of loading the more advanced functions. - -@item cl-seq.el -This file contains most of the advanced functions for operating -on sequences or lists, such as @code{cl-delete-if} and @code{cl-assoc}. - -@item cl-macs.el -This file contains the features that are macros instead of functions. -Macros expand when the caller is compiled, not when it is run, so the -macros generally only need to be present when the byte-compiler is -running (or when the macros are used in uncompiled code). Most of the -macros of this package are isolated in @file{cl-macs.el} so that they -won't take up memory unless you are compiling. -@end table - -The file @file{cl-lib.el} includes all necessary @code{autoload} -commands for the functions and macros in the other three files. -All you have to do is @code{(require 'cl-lib)}, and @file{cl-lib.el} -will take care of pulling in the other files when they are -needed. - -There is another file, @file{cl.el}, which was the main entry point to -this package prior to Emacs 24.3. Nowadays, it is replaced by -@file{cl-lib.el}. The two provide the same features (in most cases), -but use different function names (in fact, @file{cl.el} mainly just -defines aliases to the @file{cl-lib.el} definitions). Where -@file{cl-lib.el} defines a function called, for example, -@code{cl-incf}, @file{cl.el} uses the same name but without the -@samp{cl-} prefix, e.g., @code{incf} in this example. There are a few -exceptions to this. First, functions such as @code{cl-defun} where -the unprefixed version was already used for a standard Emacs Lisp -function. In such cases, the @file{cl.el} version adds a @samp{*} -suffix, e.g., @code{defun*}. Second, there are some obsolete features -that are only implemented in @file{cl.el}, not in @file{cl-lib.el}, -because they are replaced by other standard Emacs Lisp features. -Finally, in a very few cases the old @file{cl.el} versions do not -behave in exactly the same way as the @file{cl-lib.el} versions. -@xref{Obsolete Features}. -@c There is also cl-mapc, which was called cl-mapc even before cl-lib.el. -@c But not autoloaded, so maybe not much used? - -Since the old @file{cl.el} does not use a clean namespace, Emacs has a -policy that packages distributed with Emacs must not load @code{cl} at -run time. (It is ok for them to load @code{cl} at @emph{compile} -time, with @code{eval-when-compile}, and use the macros it provides.) -There is no such restriction on the use of @code{cl-lib}. New code -should use @code{cl-lib} rather than @code{cl}. - -There is one more file, @file{cl-compat.el}, which defines some -routines from the older Quiroz @file{cl.el} package that are not otherwise -present in the new package. This file is obsolete and should not be -used in new code. - -@node Naming Conventions -@section Naming Conventions - -@noindent -Except where noted, all functions defined by this package have the -same calling conventions as their Common Lisp counterparts, and -names that are those of Common Lisp plus a @samp{cl-} prefix. - -Internal function and variable names in the package are prefixed -by @code{cl--}. Here is a complete list of functions prefixed by -@code{cl-} that were @emph{not} taken from Common Lisp: - -@example -cl-callf cl-callf2 cl-defsubst -cl-letf cl-letf* -@end example - -@c This is not uninteresting I suppose, but is of zero practical relevance -@c to the user, and seems like a hostage to changing implementation details. -The following simple functions and macros are defined in @file{cl-lib.el}; -they do not cause other components like @file{cl-extra} to be loaded. - -@example -cl-evenp cl-oddp cl-minusp -cl-plusp cl-endp cl-subst -cl-copy-list cl-list* cl-ldiff -cl-rest cl-decf [1] cl-incf [1] -cl-acons cl-adjoin [2] cl-pairlis -cl-pushnew [1,2] cl-declaim cl-proclaim -cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth -cl-mapcar [3] -@end example - -@noindent -[1] Only when @var{place} is a plain variable name. - -@noindent -[2] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified, -and @code{:key} is not used. - -@noindent -[3] Only for one sequence argument or two list arguments. - -@node Program Structure -@chapter Program Structure - -@noindent -This section describes features of this package that have to -do with programs as a whole: advanced argument lists for functions, -and the @code{cl-eval-when} construct. - -@menu -* Argument Lists:: @code{&key}, @code{&aux}, @code{cl-defun}, @code{cl-defmacro}. -* Time of Evaluation:: The @code{cl-eval-when} construct. -@end menu - -@node Argument Lists -@section Argument Lists -@cindex &key -@cindex &aux - -@noindent -Emacs Lisp's notation for argument lists of functions is a subset of -the Common Lisp notation. As well as the familiar @code{&optional} -and @code{&rest} markers, Common Lisp allows you to specify default -values for optional arguments, and it provides the additional markers -@code{&key} and @code{&aux}. - -Since argument parsing is built-in to Emacs, there is no way for -this package to implement Common Lisp argument lists seamlessly. -Instead, this package defines alternates for several Lisp forms -which you must use if you need Common Lisp argument lists. - -@defmac cl-defun name arglist body@dots{} -This form is identical to the regular @code{defun} form, except -that @var{arglist} is allowed to be a full Common Lisp argument -list. Also, the function body is enclosed in an implicit block -called @var{name}; @pxref{Blocks and Exits}. -@end defmac - -@defmac cl-defsubst name arglist body@dots{} -This is just like @code{cl-defun}, except that the function that -is defined is automatically proclaimed @code{inline}, i.e., -calls to it may be expanded into in-line code by the byte compiler. -This is analogous to the @code{defsubst} form; -@code{cl-defsubst} uses a different method (compiler macros) which -works in all versions of Emacs, and also generates somewhat more -@c For some examples, -@c see http://lists.gnu.org/archive/html/emacs-devel/2012-11/msg00009.html -efficient inline expansions. In particular, @code{cl-defsubst} -arranges for the processing of keyword arguments, default values, -etc., to be done at compile-time whenever possible. -@end defmac - -@defmac cl-defmacro name arglist body@dots{} -This is identical to the regular @code{defmacro} form, -except that @var{arglist} is allowed to be a full Common Lisp -argument list. The @code{&environment} keyword is supported as -described in Steele's book @cite{Common Lisp, the Language}. -The @code{&whole} keyword is supported only -within destructured lists (see below); top-level @code{&whole} -cannot be implemented with the current Emacs Lisp interpreter. -The macro expander body is enclosed in an implicit block called -@var{name}. -@end defmac - -@defmac cl-function symbol-or-lambda -This is identical to the regular @code{function} form, -except that if the argument is a @code{lambda} form then that -form may use a full Common Lisp argument list. -@end defmac - -Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined -in this package that include @var{arglist}s in their syntax allow -full Common Lisp argument lists. - -Note that it is @emph{not} necessary to use @code{cl-defun} in -order to have access to most CL features in your function. -These features are always present; @code{cl-defun}'s only -difference from @code{defun} is its more flexible argument -lists and its implicit block. - -The full form of a Common Lisp argument list is - -@example -(@var{var}@dots{} - &optional (@var{var} @var{initform} @var{svar})@dots{} - &rest @var{var} - &key ((@var{keyword} @var{var}) @var{initform} @var{svar})@dots{} - &aux (@var{var} @var{initform})@dots{}) -@end example - -Each of the five argument list sections is optional. The @var{svar}, -@var{initform}, and @var{keyword} parts are optional; if they are -omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}. - -The first section consists of zero or more @dfn{required} arguments. -These arguments must always be specified in a call to the function; -there is no difference between Emacs Lisp and Common Lisp as far as -required arguments are concerned. - -The second section consists of @dfn{optional} arguments. These -arguments may be specified in the function call; if they are not, -@var{initform} specifies the default value used for the argument. -(No @var{initform} means to use @code{nil} as the default.) The -@var{initform} is evaluated with the bindings for the preceding -arguments already established; @code{(a &optional (b (1+ a)))} -matches one or two arguments, with the second argument defaulting -to one plus the first argument. If the @var{svar} is specified, -it is an auxiliary variable which is bound to @code{t} if the optional -argument was specified, or to @code{nil} if the argument was omitted. -If you don't use an @var{svar}, then there will be no way for your -function to tell whether it was called with no argument, or with -the default value passed explicitly as an argument. - -The third section consists of a single @dfn{rest} argument. If -more arguments were passed to the function than are accounted for -by the required and optional arguments, those extra arguments are -collected into a list and bound to the ``rest'' argument variable. -Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp. -Common Lisp accepts @code{&body} as a synonym for @code{&rest} in -macro contexts; this package accepts it all the time. - -The fourth section consists of @dfn{keyword} arguments. These -are optional arguments which are specified by name rather than -positionally in the argument list. For example, - -@example -(cl-defun foo (a &optional b &key c d (e 17))) -@end example - -@noindent -defines a function which may be called with one, two, or more -arguments. The first two arguments are bound to @code{a} and -@code{b} in the usual way. The remaining arguments must be -pairs of the form @code{:c}, @code{:d}, or @code{:e} followed -by the value to be bound to the corresponding argument variable. -(Symbols whose names begin with a colon are called @dfn{keywords}, -and they are self-quoting in the same way as @code{nil} and -@code{t}.) - -For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five -arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword -appears more than once in the function call, the first occurrence -takes precedence over the later ones. Note that it is not possible -to specify keyword arguments without specifying the optional -argument @code{b} as well, since @code{(foo 1 :c 2)} would bind -@code{b} to the keyword @code{:c}, then signal an error because -@code{2} is not a valid keyword. - -You can also explicitly specify the keyword argument; it need not be -simply the variable name prefixed with a colon. For example, - -@example -(cl-defun bar (&key (a 1) ((baz b) 4))) -@end example - -@noindent - -specifies a keyword @code{:a} that sets the variable @code{a} with -default value 1, as well as a keyword @code{baz} that sets the -variable @code{b} with default value 4. In this case, because -@code{baz} is not self-quoting, you must quote it explicitly in the -function call, like this: - -@example -(bar :a 10 'baz 42) -@end example - -Ordinarily, it is an error to pass an unrecognized keyword to -a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask -Lisp to ignore unrecognized keywords, either by adding the -marker @code{&allow-other-keys} after the keyword section -of the argument list, or by specifying an @code{:allow-other-keys} -argument in the call whose value is non-@code{nil}. If the -function uses both @code{&rest} and @code{&key} at the same time, -the ``rest'' argument is bound to the keyword list as it appears -in the call. For example: - -@example -(cl-defun find-thing (thing &rest rest &key need &allow-other-keys) - (or (apply 'cl-member thing thing-list :allow-other-keys t rest) - (if need (error "Thing not found")))) -@end example - -@noindent -This function takes a @code{:need} keyword argument, but also -accepts other keyword arguments which are passed on to the -@code{cl-member} function. @code{allow-other-keys} is used to -keep both @code{find-thing} and @code{cl-member} from complaining -about each others' keywords in the arguments. - -The fifth section of the argument list consists of @dfn{auxiliary -variables}. These are not really arguments at all, but simply -variables which are bound to @code{nil} or to the specified -@var{initforms} during execution of the function. There is no -difference between the following two functions, except for a -matter of stylistic taste: - -@example -(cl-defun foo (a b &aux (c (+ a b)) d) - @var{body}) - -(cl-defun foo (a b) - (let ((c (+ a b)) d) - @var{body})) -@end example - -@cindex destructuring, in argument list -Argument lists support @dfn{destructuring}. In Common Lisp, -destructuring is only allowed with @code{defmacro}; this package -allows it with @code{cl-defun} and other argument lists as well. -In destructuring, any argument variable (@var{var} in the above -example) can be replaced by a list of variables, or more generally, -a recursive argument list. The corresponding argument value must -be a list whose elements match this recursive argument list. -For example: - -@example -(cl-defmacro dolist ((var listform &optional resultform) - &rest body) - @dots{}) -@end example - -This says that the first argument of @code{dolist} must be a list -of two or three items; if there are other arguments as well as this -list, they are stored in @code{body}. All features allowed in -regular argument lists are allowed in these recursive argument lists. -In addition, the clause @samp{&whole @var{var}} is allowed at the -front of a recursive argument list. It binds @var{var} to the -whole list being matched; thus @code{(&whole all a b)} matches -a list of two things, with @code{a} bound to the first thing, -@code{b} bound to the second thing, and @code{all} bound to the -list itself. (Common Lisp allows @code{&whole} in top-level -@code{defmacro} argument lists as well, but Emacs Lisp does not -support this usage.) - -One last feature of destructuring is that the argument list may be -dotted, so that the argument list @code{(a b . c)} is functionally -equivalent to @code{(a b &rest c)}. - -If the optimization quality @code{safety} is set to 0 -(@pxref{Declarations}), error checking for wrong number of -arguments and invalid keyword arguments is disabled. By default, -argument lists are rigorously checked. - -@node Time of Evaluation -@section Time of Evaluation - -@noindent -Normally, the byte-compiler does not actually execute the forms in -a file it compiles. For example, if a file contains @code{(setq foo t)}, -the act of compiling it will not actually set @code{foo} to @code{t}. -This is true even if the @code{setq} was a top-level form (i.e., not -enclosed in a @code{defun} or other form). Sometimes, though, you -would like to have certain top-level forms evaluated at compile-time. -For example, the compiler effectively evaluates @code{defmacro} forms -at compile-time so that later parts of the file can refer to the -macros that are defined. - -@defmac cl-eval-when (situations@dots{}) forms@dots{} -This form controls when the body @var{forms} are evaluated. -The @var{situations} list may contain any set of the symbols -@code{compile}, @code{load}, and @code{eval} (or their long-winded -ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel}, -and @code{:execute}). - -The @code{cl-eval-when} form is handled differently depending on -whether or not it is being compiled as a top-level form. -Specifically, it gets special treatment if it is being compiled -by a command such as @code{byte-compile-file} which compiles files -or buffers of code, and it appears either literally at the -top level of the file or inside a top-level @code{progn}. - -For compiled top-level @code{cl-eval-when}s, the body @var{forms} are -executed at compile-time if @code{compile} is in the @var{situations} -list, and the @var{forms} are written out to the file (to be executed -at load-time) if @code{load} is in the @var{situations} list. - -For non-compiled-top-level forms, only the @code{eval} situation is -relevant. (This includes forms executed by the interpreter, forms -compiled with @code{byte-compile} rather than @code{byte-compile-file}, -and non-top-level forms.) The @code{cl-eval-when} acts like a -@code{progn} if @code{eval} is specified, and like @code{nil} -(ignoring the body @var{forms}) if not. - -The rules become more subtle when @code{cl-eval-when}s are nested; -consult Steele (second edition) for the gruesome details (and -some gruesome examples). - -Some simple examples: - -@example -;; Top-level forms in foo.el: -(cl-eval-when (compile) (setq foo1 'bar)) -(cl-eval-when (load) (setq foo2 'bar)) -(cl-eval-when (compile load) (setq foo3 'bar)) -(cl-eval-when (eval) (setq foo4 'bar)) -(cl-eval-when (eval compile) (setq foo5 'bar)) -(cl-eval-when (eval load) (setq foo6 'bar)) -(cl-eval-when (eval compile load) (setq foo7 'bar)) -@end example - -When @file{foo.el} is compiled, these variables will be set during -the compilation itself: - -@example -foo1 foo3 foo5 foo7 ; `compile' -@end example - -When @file{foo.elc} is loaded, these variables will be set: - -@example -foo2 foo3 foo6 foo7 ; `load' -@end example - -And if @file{foo.el} is loaded uncompiled, these variables will -be set: - -@example -foo4 foo5 foo6 foo7 ; `eval' -@end example - -If these seven @code{cl-eval-when}s had been, say, inside a @code{defun}, -then the first three would have been equivalent to @code{nil} and the -last four would have been equivalent to the corresponding @code{setq}s. - -Note that @code{(cl-eval-when (load eval) @dots{})} is equivalent -to @code{(progn @dots{})} in all contexts. The compiler treats -certain top-level forms, like @code{defmacro} (sort-of) and -@code{require}, as if they were wrapped in @code{(cl-eval-when -(compile load eval) @dots{})}. -@end defmac - -Emacs includes two special forms related to @code{cl-eval-when}. -@xref{Eval During Compile,,,elisp,GNU Emacs Lisp Reference Manual}. -One of these, @code{eval-when-compile}, is not quite equivalent to -any @code{cl-eval-when} construct and is described below. - -The other form, @code{(eval-and-compile @dots{})}, is exactly -equivalent to @samp{(cl-eval-when (compile load eval) @dots{})}. - -@defmac eval-when-compile forms@dots{} -The @var{forms} are evaluated at compile-time; at execution time, -this form acts like a quoted constant of the resulting value. Used -at top-level, @code{eval-when-compile} is just like @samp{eval-when -(compile eval)}. In other contexts, @code{eval-when-compile} -allows code to be evaluated once at compile-time for efficiency -or other reasons. - -This form is similar to the @samp{#.} syntax of true Common Lisp. -@end defmac - -@defmac cl-load-time-value form -The @var{form} is evaluated at load-time; at execution time, -this form acts like a quoted constant of the resulting value. - -Early Common Lisp had a @samp{#,} syntax that was similar to -this, but ANSI Common Lisp replaced it with @code{load-time-value} -and gave it more well-defined semantics. - -In a compiled file, @code{cl-load-time-value} arranges for @var{form} -to be evaluated when the @file{.elc} file is loaded and then used -as if it were a quoted constant. In code compiled by -@code{byte-compile} rather than @code{byte-compile-file}, the -effect is identical to @code{eval-when-compile}. In uncompiled -code, both @code{eval-when-compile} and @code{cl-load-time-value} -act exactly like @code{progn}. - -@example -(defun report () - (insert "This function was executed on: " - (current-time-string) - ", compiled on: " - (eval-when-compile (current-time-string)) - ;; or '#.(current-time-string) in real Common Lisp - ", and loaded on: " - (cl-load-time-value (current-time-string)))) -@end example - -@noindent -Byte-compiled, the above defun will result in the following code -(or its compiled equivalent, of course) in the @file{.elc} file: - -@example -(setq --temp-- (current-time-string)) -(defun report () - (insert "This function was executed on: " - (current-time-string) - ", compiled on: " - '"Wed Oct 31 16:32:28 2012" - ", and loaded on: " - --temp--)) -@end example -@end defmac - -@node Predicates -@chapter Predicates - -@noindent -This section describes functions for testing whether various -facts are true or false. - -@menu -* Type Predicates:: @code{cl-typep}, @code{cl-deftype}, and @code{cl-coerce}. -* Equality Predicates:: @code{cl-equalp}. -@end menu - -@node Type Predicates -@section Type Predicates - -@defun cl-typep object type -Check if @var{object} is of type @var{type}, where @var{type} is a -(quoted) type name of the sort used by Common Lisp. For example, -@code{(cl-typep foo 'integer)} is equivalent to @code{(integerp foo)}. -@end defun - -The @var{type} argument to the above function is either a symbol -or a list beginning with a symbol. - -@itemize @bullet -@item -If the type name is a symbol, Emacs appends @samp{-p} to the -symbol name to form the name of a predicate function for testing -the type. (Built-in predicates whose names end in @samp{p} rather -than @samp{-p} are used when appropriate.) - -@item -The type symbol @code{t} stands for the union of all types. -@code{(cl-typep @var{object} t)} is always true. Likewise, the -type symbol @code{nil} stands for nothing at all, and -@code{(cl-typep @var{object} nil)} is always false. - -@item -The type symbol @code{null} represents the symbol @code{nil}. -Thus @code{(cl-typep @var{object} 'null)} is equivalent to -@code{(null @var{object})}. - -@item -The type symbol @code{atom} represents all objects that are not cons -cells. Thus @code{(cl-typep @var{object} 'atom)} is equivalent to -@code{(atom @var{object})}. - -@item -The type symbol @code{real} is a synonym for @code{number}, and -@code{fixnum} is a synonym for @code{integer}. - -@item -The type symbols @code{character} and @code{string-char} match -integers in the range from 0 to 255. - -@item -The type list @code{(integer @var{low} @var{high})} represents all -integers between @var{low} and @var{high}, inclusive. Either bound -may be a list of a single integer to specify an exclusive limit, -or a @code{*} to specify no limit. The type @code{(integer * *)} -is thus equivalent to @code{integer}. - -@item -Likewise, lists beginning with @code{float}, @code{real}, or -@code{number} represent numbers of that type falling in a particular -range. - -@item -Lists beginning with @code{and}, @code{or}, and @code{not} form -combinations of types. For example, @code{(or integer (float 0 *))} -represents all objects that are integers or non-negative floats. - -@item -Lists beginning with @code{member} or @code{cl-member} represent -objects @code{eql} to any of the following values. For example, -@code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)}, -and @code{(member nil)} is equivalent to @code{null}. - -@item -Lists of the form @code{(satisfies @var{predicate})} represent -all objects for which @var{predicate} returns true when called -with that object as an argument. -@end itemize - -The following function and macro (not technically predicates) are -related to @code{cl-typep}. - -@defun cl-coerce object type -This function attempts to convert @var{object} to the specified -@var{type}. If @var{object} is already of that type as determined by -@code{cl-typep}, it is simply returned. Otherwise, certain types of -conversions will be made: If @var{type} is any sequence type -(@code{string}, @code{list}, etc.)@: then @var{object} will be -converted to that type if possible. If @var{type} is -@code{character}, then strings of length one and symbols with -one-character names can be coerced. If @var{type} is @code{float}, -then integers can be coerced in versions of Emacs that support -floats. In all other circumstances, @code{cl-coerce} signals an -error. -@end defun - -@defmac cl-deftype name arglist forms@dots{} -This macro defines a new type called @var{name}. It is similar -to @code{defmacro} in many ways; when @var{name} is encountered -as a type name, the body @var{forms} are evaluated and should -return a type specifier that is equivalent to the type. The -@var{arglist} is a Common Lisp argument list of the sort accepted -by @code{cl-defmacro}. The type specifier @samp{(@var{name} @var{args}@dots{})} -is expanded by calling the expander with those arguments; the type -symbol @samp{@var{name}} is expanded by calling the expander with -no arguments. The @var{arglist} is processed the same as for -@code{cl-defmacro} except that optional arguments without explicit -defaults use @code{*} instead of @code{nil} as the ``default'' -default. Some examples: - -@example -(cl-deftype null () '(satisfies null)) ; predefined -(cl-deftype list () '(or null cons)) ; predefined -(cl-deftype unsigned-byte (&optional bits) - (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) -(unsigned-byte 8) @equiv{} (integer 0 255) -(unsigned-byte) @equiv{} (integer 0 *) -unsigned-byte @equiv{} (integer 0 *) -@end example - -@noindent -The last example shows how the Common Lisp @code{unsigned-byte} -type specifier could be implemented if desired; this package does -not implement @code{unsigned-byte} by default. -@end defmac - -The @code{cl-typecase} (@pxref{Conditionals}) and @code{cl-check-type} -(@pxref{Assertions}) macros also use type names. The @code{cl-map}, -@code{cl-concatenate}, and @code{cl-merge} functions take type-name -arguments to specify the type of sequence to return. @xref{Sequences}. - -@node Equality Predicates -@section Equality Predicates - -@noindent -This package defines the Common Lisp predicate @code{cl-equalp}. - -@defun cl-equalp a b -This function is a more flexible version of @code{equal}. In -particular, it compares strings case-insensitively, and it compares -numbers without regard to type (so that @code{(cl-equalp 3 3.0)} is -true). Vectors and conses are compared recursively. All other -objects are compared as if by @code{equal}. - -This function differs from Common Lisp @code{equalp} in several -respects. First, Common Lisp's @code{equalp} also compares -@emph{characters} case-insensitively, which would be impractical -in this package since Emacs does not distinguish between integers -and characters. In keeping with the idea that strings are less -vector-like in Emacs Lisp, this package's @code{cl-equalp} also will -not compare strings against vectors of integers. -@end defun - -Also note that the Common Lisp functions @code{member} and @code{assoc} -use @code{eql} to compare elements, whereas Emacs Lisp follows the -MacLisp tradition and uses @code{equal} for these two functions. -The functions @code{cl-member} and @code{cl-assoc} use @code{eql}, -as in Common Lisp. The standard Emacs Lisp functions @code{memq} and -@code{assq} use @code{eq}, and the standard @code{memql} uses @code{eql}. - -@node Control Structure -@chapter Control Structure - -@noindent -The features described in the following sections implement -various advanced control structures, including extensions to the -standard @code{setf} facility, and a number of looping and conditional -constructs. - -@menu -* Assignment:: The @code{cl-psetq} form. -* Generalized Variables:: Extensions to generalized variables. -* Variable Bindings:: @code{cl-progv}, @code{cl-flet}, @code{cl-macrolet}. -* Conditionals:: @code{cl-case}, @code{cl-typecase}. -* Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}. -* Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}. -* Loop Facility:: The Common Lisp @code{loop} macro. -* Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc. -@end menu - -@node Assignment -@section Assignment - -@noindent -The @code{cl-psetq} form is just like @code{setq}, except that multiple -assignments are done in parallel rather than sequentially. - -@defmac cl-psetq [symbol form]@dots{} -This special form (actually a macro) is used to assign to several -variables simultaneously. Given only one @var{symbol} and @var{form}, -it has the same effect as @code{setq}. Given several @var{symbol} -and @var{form} pairs, it evaluates all the @var{form}s in advance -and then stores the corresponding variables afterwards. - -@example -(setq x 2 y 3) -(setq x (+ x y) y (* x y)) -x - @result{} 5 -y ; @r{@code{y} was computed after @code{x} was set.} - @result{} 15 -(setq x 2 y 3) -(cl-psetq x (+ x y) y (* x y)) -x - @result{} 5 -y ; @r{@code{y} was computed before @code{x} was set.} - @result{} 6 -@end example - -The simplest use of @code{cl-psetq} is @code{(cl-psetq x y y x)}, which -exchanges the values of two variables. (The @code{cl-rotatef} form -provides an even more convenient way to swap two variables; -@pxref{Modify Macros}.) - -@code{cl-psetq} always returns @code{nil}. -@end defmac - -@node Generalized Variables -@section Generalized Variables - -A @dfn{generalized variable} or @dfn{place form} is one of the many -places in Lisp memory where values can be stored. The simplest place -form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, -elements of arrays, properties of symbols, and many other locations -are also places where Lisp values are stored. For basic information, -@pxref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}. -This package provides several additional features related to -generalized variables. - -@menu -* Setf Extensions:: Additional @code{setf} places. -* Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{cl-letf}, @code{cl-callf}, etc. -@end menu - -@node Setf Extensions -@subsection Setf Extensions - -Several standard (e.g., @code{car}) and Emacs-specific -(e.g., @code{window-point}) Lisp functions are @code{setf}-able by default. -This package defines @code{setf} handlers for several additional functions: - -@itemize -@item -Functions from this package: -@example -cl-rest cl-subseq cl-get cl-getf -cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth -@end example - -@noindent -Note that for @code{cl-getf} (as for @code{nthcdr}), the list argument -of the function must itself be a valid @var{place} form. - -@item -General Emacs Lisp functions: -@example -buffer-file-name getenv -buffer-modified-p global-key-binding -buffer-name local-key-binding -buffer-string mark -buffer-substring mark-marker -current-buffer marker-position -current-case-table mouse-position -current-column point -current-global-map point-marker -current-input-mode point-max -current-local-map point-min -current-window-configuration read-mouse-position -default-file-modes screen-height -documentation-property screen-width -face-background selected-window -face-background-pixmap selected-screen -face-font selected-frame -face-foreground standard-case-table -face-underline-p syntax-table -file-modes visited-file-modtime -frame-height window-height -frame-parameters window-width -frame-visible-p x-get-secondary-selection -frame-width x-get-selection -get-register -@end example - -Most of these have directly corresponding ``set'' functions, like -@code{use-local-map} for @code{current-local-map}, or @code{goto-char} -for @code{point}. A few, like @code{point-min}, expand to longer -sequences of code when they are used with @code{setf} -(@code{(narrow-to-region x (point-max))} in this case). - -@item -A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, -where @var{subplace} is itself a valid generalized variable whose -current value is a string, and where the value stored is also a -string. The new string is spliced into the specified part of the -destination string. For example: - -@example -(setq a (list "hello" "world")) - @result{} ("hello" "world") -(cadr a) - @result{} "world" -(substring (cadr a) 2 4) - @result{} "rl" -(setf (substring (cadr a) 2 4) "o") - @result{} "o" -(cadr a) - @result{} "wood" -a - @result{} ("hello" "wood") -@end example - -The generalized variable @code{buffer-substring}, listed above, -also works in this way by replacing a portion of the current buffer. - -@c FIXME? Also `eq'? (see cl-lib.el) - -@c Currently commented out in cl.el. -@ignore -@item -A call of the form @code{(apply '@var{func} @dots{})} or -@code{(apply (function @var{func}) @dots{})}, where @var{func} -is a @code{setf}-able function whose store function is ``suitable'' -in the sense described in Steele's book; since none of the standard -Emacs place functions are suitable in this sense, this feature is -only interesting when used with places you define yourself with -@code{define-setf-method} or the long form of @code{defsetf}. -@xref{Obsolete Setf Customization}. -@end ignore - -@c FIXME? Is this still true? -@item -A macro call, in which case the macro is expanded and @code{setf} -is applied to the resulting form. -@end itemize - -@c FIXME should this be in lispref? It seems self-evident. -@c Contrast with the cl-incf example later on. -@c Here it really only serves as a contrast to wrong-order. -The @code{setf} macro takes care to evaluate all subforms in -the proper left-to-right order; for example, - -@example -(setf (aref vec (cl-incf i)) i) -@end example - -@noindent -looks like it will evaluate @code{(cl-incf i)} exactly once, before the -following access to @code{i}; the @code{setf} expander will insert -temporary variables as necessary to ensure that it does in fact work -this way no matter what setf-method is defined for @code{aref}. -(In this case, @code{aset} would be used and no such steps would -be necessary since @code{aset} takes its arguments in a convenient -order.) - -However, if the @var{place} form is a macro which explicitly -evaluates its arguments in an unusual order, this unusual order -will be preserved. Adapting an example from Steele, given - -@example -(defmacro wrong-order (x y) (list 'aref y x)) -@end example - -@noindent -the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will -evaluate @var{b} first, then @var{a}, just as in an actual call -to @code{wrong-order}. - -@node Modify Macros -@subsection Modify Macros - -@noindent -This package defines a number of macros that operate on generalized -variables. Many are interesting and useful even when the @var{place} -is just a variable name. - -@defmac cl-psetf [place form]@dots{} -This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}: -When several @var{place}s and @var{form}s are involved, the -assignments take place in parallel rather than sequentially. -Specifically, all subforms are evaluated from left to right, then -all the assignments are done (in an undefined order). -@end defmac - -@defmac cl-incf place &optional x -This macro increments the number stored in @var{place} by one, or -by @var{x} if specified. The incremented value is returned. For -example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and -@code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}. - -As with @code{setf}, care is taken to preserve the ``apparent'' order -of evaluation. For example, - -@example -(cl-incf (aref vec (cl-incf i))) -@end example - -@noindent -appears to increment @code{i} once, then increment the element of -@code{vec} addressed by @code{i}; this is indeed exactly what it -does, which means the above form is @emph{not} equivalent to the -``obvious'' expansion, - -@example -(setf (aref vec (cl-incf i)) - (1+ (aref vec (cl-incf i)))) ; wrong! -@end example - -@noindent -but rather to something more like - -@example -(let ((temp (cl-incf i))) - (setf (aref vec temp) (1+ (aref vec temp)))) -@end example - -@noindent -Again, all of this is taken care of automatically by @code{cl-incf} and -the other generalized-variable macros. - -As a more Emacs-specific example of @code{cl-incf}, the expression -@code{(cl-incf (point) @var{n})} is essentially equivalent to -@code{(forward-char @var{n})}. -@end defmac - -@defmac cl-decf place &optional x -This macro decrements the number stored in @var{place} by one, or -by @var{x} if specified. -@end defmac - -@defmac cl-pushnew x place @t{&key :test :test-not :key} -This macro inserts @var{x} at the front of the list stored in -@var{place}, but only if @var{x} was not @code{eql} to any -existing element of the list. The optional keyword arguments -are interpreted in the same way as for @code{cl-adjoin}. -@xref{Lists as Sets}. -@end defmac - -@defmac cl-shiftf place@dots{} newvalue -This macro shifts the @var{place}s left by one, shifting in the -value of @var{newvalue} (which may be any Lisp expression, not just -a generalized variable), and returning the value shifted out of -the first @var{place}. Thus, @code{(cl-shiftf @var{a} @var{b} @var{c} -@var{d})} is equivalent to - -@example -(prog1 - @var{a} - (cl-psetf @var{a} @var{b} - @var{b} @var{c} - @var{c} @var{d})) -@end example - -@noindent -except that the subforms of @var{a}, @var{b}, and @var{c} are actually -evaluated only once each and in the apparent order. -@end defmac - -@defmac cl-rotatef place@dots{} -This macro rotates the @var{place}s left by one in circular fashion. -Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to - -@example -(cl-psetf @var{a} @var{b} - @var{b} @var{c} - @var{c} @var{d} - @var{d} @var{a}) -@end example - -@noindent -except for the evaluation of subforms. @code{cl-rotatef} always -returns @code{nil}. Note that @code{(cl-rotatef @var{a} @var{b})} -conveniently exchanges @var{a} and @var{b}. -@end defmac - -The following macros were invented for this package; they have no -analogues in Common Lisp. - -@defmac cl-letf (bindings@dots{}) forms@dots{} -This macro is analogous to @code{let}, but for generalized variables -rather than just symbols. Each @var{binding} should be of the form -@code{(@var{place} @var{value})}; the original contents of the -@var{place}s are saved, the @var{value}s are stored in them, and -then the body @var{form}s are executed. Afterwards, the @var{places} -are set back to their original saved contents. This cleanup happens -even if the @var{form}s exit irregularly due to a @code{throw} or an -error. - -For example, - -@example -(cl-letf (((point) (point-min)) - (a 17)) - @dots{}) -@end example - -@noindent -moves point in the current buffer to the beginning of the buffer, -and also binds @code{a} to 17 (as if by a normal @code{let}, since -@code{a} is just a regular variable). After the body exits, @code{a} -is set back to its original value and point is moved back to its -original position. - -Note that @code{cl-letf} on @code{(point)} is not quite like a -@code{save-excursion}, as the latter effectively saves a marker -which tracks insertions and deletions in the buffer. Actually, -a @code{cl-letf} of @code{(point-marker)} is much closer to this -behavior. (@code{point} and @code{point-marker} are equivalent -as @code{setf} places; each will accept either an integer or a -marker as the stored value.) - -Since generalized variables look like lists, @code{let}'s shorthand -of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would -be ambiguous in @code{cl-letf} and is not allowed. - -However, a @var{binding} specifier may be a one-element list -@samp{(@var{place})}, which is similar to @samp{(@var{place} -@var{place})}. In other words, the @var{place} is not disturbed -on entry to the body, and the only effect of the @code{cl-letf} is -to restore the original value of @var{place} afterwards. -@c I suspect this may no longer be true; either way it's -@c implementation detail and so not essential to document. -@ignore -(The redundant access-and-store suggested by the @code{(@var{place} -@var{place})} example does not actually occur.) -@end ignore - -Note that in this case, and in fact almost every case, @var{place} -must have a well-defined value outside the @code{cl-letf} body. -There is essentially only one exception to this, which is @var{place} -a plain variable with a specified @var{value} (such as @code{(a 17)} -in the above example). -@c See http://debbugs.gnu.org/12758 -@c Some or all of this was true for cl.el, but not for cl-lib.el. -@ignore -The only exceptions are plain variables and calls to -@code{symbol-value} and @code{symbol-function}. If the symbol is not -bound on entry, it is simply made unbound by @code{makunbound} or -@code{fmakunbound} on exit. -@end ignore -@end defmac - -@defmac cl-letf* (bindings@dots{}) forms@dots{} -This macro is to @code{cl-letf} what @code{let*} is to @code{let}: -It does the bindings in sequential rather than parallel order. -@end defmac - -@defmac cl-callf @var{function} @var{place} @var{args}@dots{} -This is the ``generic'' modify macro. It calls @var{function}, -which should be an unquoted function name, macro name, or lambda. -It passes @var{place} and @var{args} as arguments, and assigns the -result back to @var{place}. For example, @code{(cl-incf @var{place} -@var{n})} is the same as @code{(cl-callf + @var{place} @var{n})}. -Some more examples: - -@example -(cl-callf abs my-number) -(cl-callf concat (buffer-name) "<" (number-to-string n) ">") -(cl-callf cl-union happy-people (list joe bob) :test 'same-person) -@end example - -Note again that @code{cl-callf} is an extension to standard Common Lisp. -@end defmac - -@defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} -This macro is like @code{cl-callf}, except that @var{place} is -the @emph{second} argument of @var{function} rather than the -first. For example, @code{(push @var{x} @var{place})} is -equivalent to @code{(cl-callf2 cons @var{x} @var{place})}. -@end defmac - -The @code{cl-callf} and @code{cl-callf2} macros serve as building -blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}. -The @code{cl-letf} and @code{cl-letf*} macros are used in the processing -of symbol macros; @pxref{Macro Bindings}. - - -@node Variable Bindings -@section Variable Bindings - -@noindent -These Lisp forms make bindings to variables and function names, -analogous to Lisp's built-in @code{let} form. - -@xref{Modify Macros}, for the @code{cl-letf} and @code{cl-letf*} forms which -are also related to variable bindings. - -@menu -* Dynamic Bindings:: The @code{cl-progv} form. -* Function Bindings:: @code{cl-flet} and @code{cl-labels}. -* Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}. -@end menu - -@node Dynamic Bindings -@subsection Dynamic Bindings - -@noindent -The standard @code{let} form binds variables whose names are known -at compile-time. The @code{cl-progv} form provides an easy way to -bind variables whose names are computed at run-time. - -@defmac cl-progv symbols values forms@dots{} -This form establishes @code{let}-style variable bindings on a -set of variables computed at run-time. The expressions -@var{symbols} and @var{values} are evaluated, and must return lists -of symbols and values, respectively. The symbols are bound to the -corresponding values for the duration of the body @var{form}s. -If @var{values} is shorter than @var{symbols}, the last few symbols -are bound to @code{nil}. -If @var{symbols} is shorter than @var{values}, the excess values -are ignored. -@end defmac - -@node Function Bindings -@subsection Function Bindings - -@noindent -These forms make @code{let}-like bindings to functions instead -of variables. - -@defmac cl-flet (bindings@dots{}) forms@dots{} -This form establishes @code{let}-style bindings on the function -cells of symbols rather than on the value cells. Each @var{binding} -must be a list of the form @samp{(@var{name} @var{arglist} -@var{forms}@dots{})}, which defines a function exactly as if -it were a @code{cl-defun} form. The function @var{name} is defined -accordingly but only within the body of the @code{cl-flet}, hiding any external -definition if applicable. - -The bindings are lexical in scope. This means that all references to -the named functions must appear physically within the body of the -@code{cl-flet} form. - -Functions defined by @code{cl-flet} may use the full Common Lisp -argument notation supported by @code{cl-defun}; also, the function -body is enclosed in an implicit block as if by @code{cl-defun}. -@xref{Program Structure}. - -Note that the @file{cl.el} version of this macro behaves slightly -differently. In particular, its binding is dynamic rather than -lexical. @xref{Obsolete Macros}. -@end defmac - -@defmac cl-labels (bindings@dots{}) forms@dots{} -The @code{cl-labels} form is like @code{cl-flet}, except that -the function bindings can be recursive. The scoping is lexical, -but you can only capture functions in closures if -@code{lexical-binding} is @code{t}. -@xref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}, and -@ref{Using Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}. - -Lexical scoping means that all references to the named -functions must appear physically within the body of the -@code{cl-labels} form. References may appear both in the body -@var{forms} of @code{cl-labels} itself, and in the bodies of -the functions themselves. Thus, @code{cl-labels} can define -local recursive functions, or mutually-recursive sets of functions. - -A ``reference'' to a function name is either a call to that -function, or a use of its name quoted by @code{quote} or -@code{function} to be passed on to, say, @code{mapcar}. - -Note that the @file{cl.el} version of this macro behaves slightly -differently. @xref{Obsolete Macros}. -@end defmac - -@node Macro Bindings -@subsection Macro Bindings - -@noindent -These forms create local macros and ``symbol macros''. - -@defmac cl-macrolet (bindings@dots{}) forms@dots{} -This form is analogous to @code{cl-flet}, but for macros instead of -functions. Each @var{binding} is a list of the same form as the -arguments to @code{cl-defmacro} (i.e., a macro name, argument list, -and macro-expander forms). The macro is defined accordingly for -use within the body of the @code{cl-macrolet}. - -Because of the nature of macros, @code{cl-macrolet} is always lexically -scoped. The @code{cl-macrolet} binding will -affect only calls that appear physically within the body -@var{forms}, possibly after expansion of other macros in the -body. -@end defmac - -@defmac cl-symbol-macrolet (bindings@dots{}) forms@dots{} -This form creates @dfn{symbol macros}, which are macros that look -like variable references rather than function calls. Each -@var{binding} is a list @samp{(@var{var} @var{expansion})}; -any reference to @var{var} within the body @var{forms} is -replaced by @var{expansion}. - -@example -(setq bar '(5 . 9)) -(cl-symbol-macrolet ((foo (car bar))) - (cl-incf foo)) -bar - @result{} (6 . 9) -@end example - -A @code{setq} of a symbol macro is treated the same as a @code{setf}. -I.e., @code{(setq foo 4)} in the above would be equivalent to -@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}. - -Likewise, a @code{let} or @code{let*} binding a symbol macro is -treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true -Common Lisp, where the rules of lexical scoping cause a @code{let} -binding to shadow a @code{symbol-macrolet} binding. In this package, -such shadowing does not occur, even when @code{lexical-binding} is -@c See http://debbugs.gnu.org/12119 -@code{t}. (This behavior predates the addition of lexical binding to -Emacs Lisp, and may change in future to respect @code{lexical-binding}.) -At present in this package, only @code{lexical-let} and -@code{lexical-let*} will shadow a symbol macro. @xref{Obsolete -Lexical Binding}. - -There is no analogue of @code{defmacro} for symbol macros; all symbol -macros are local. A typical use of @code{cl-symbol-macrolet} is in the -expansion of another macro: - -@example -(cl-defmacro my-dolist ((x list) &rest body) - (let ((var (cl-gensym))) - (list 'cl-loop 'for var 'on list 'do - (cl-list* 'cl-symbol-macrolet - (list (list x (list 'car var))) - body)))) - -(setq mylist '(1 2 3 4)) -(my-dolist (x mylist) (cl-incf x)) -mylist - @result{} (2 3 4 5) -@end example - -@noindent -In this example, the @code{my-dolist} macro is similar to @code{dolist} -(@pxref{Iteration}) except that the variable @code{x} becomes a true -reference onto the elements of the list. The @code{my-dolist} call -shown here expands to - -@example -(cl-loop for G1234 on mylist do - (cl-symbol-macrolet ((x (car G1234))) - (cl-incf x))) -@end example - -@noindent -which in turn expands to - -@example -(cl-loop for G1234 on mylist do (cl-incf (car G1234))) -@end example - -@xref{Loop Facility}, for a description of the @code{cl-loop} macro. -This package defines a nonstandard @code{in-ref} loop clause that -works much like @code{my-dolist}. -@end defmac - -@node Conditionals -@section Conditionals - -@noindent -These conditional forms augment Emacs Lisp's simple @code{if}, -@code{and}, @code{or}, and @code{cond} forms. - -@defmac cl-case keyform clause@dots{} -This macro evaluates @var{keyform}, then compares it with the key -values listed in the various @var{clause}s. Whichever clause matches -the key is executed; comparison is done by @code{eql}. If no clause -matches, the @code{cl-case} form returns @code{nil}. The clauses are -of the form - -@example -(@var{keylist} @var{body-forms}@dots{}) -@end example - -@noindent -where @var{keylist} is a list of key values. If there is exactly -one value, and it is not a cons cell or the symbol @code{nil} or -@code{t}, then it can be used by itself as a @var{keylist} without -being enclosed in a list. All key values in the @code{cl-case} form -must be distinct. The final clauses may use @code{t} in place of -a @var{keylist} to indicate a default clause that should be taken -if none of the other clauses match. (The symbol @code{otherwise} -is also recognized in place of @code{t}. To make a clause that -matches the actual symbol @code{t}, @code{nil}, or @code{otherwise}, -enclose the symbol in a list.) - -For example, this expression reads a keystroke, then does one of -four things depending on whether it is an @samp{a}, a @samp{b}, -a @key{RET} or @kbd{C-j}, or anything else. - -@example -(cl-case (read-char) - (?a (do-a-thing)) - (?b (do-b-thing)) - ((?\r ?\n) (do-ret-thing)) - (t (do-other-thing))) -@end example -@end defmac - -@defmac cl-ecase keyform clause@dots{} -This macro is just like @code{cl-case}, except that if the key does -not match any of the clauses, an error is signaled rather than -simply returning @code{nil}. -@end defmac - -@defmac cl-typecase keyform clause@dots{} -This macro is a version of @code{cl-case} that checks for types -rather than values. Each @var{clause} is of the form -@samp{(@var{type} @var{body}@dots{})}. @xref{Type Predicates}, -for a description of type specifiers. For example, - -@example -(cl-typecase x - (integer (munch-integer x)) - (float (munch-float x)) - (string (munch-integer (string-to-int x))) - (t (munch-anything x))) -@end example - -The type specifier @code{t} matches any type of object; the word -@code{otherwise} is also allowed. To make one clause match any of -several types, use an @code{(or @dots{})} type specifier. -@end defmac - -@defmac cl-etypecase keyform clause@dots{} -This macro is just like @code{cl-typecase}, except that if the key does -not match any of the clauses, an error is signaled rather than -simply returning @code{nil}. -@end defmac - -@node Blocks and Exits -@section Blocks and Exits -@cindex block - -@noindent -Common Lisp @dfn{blocks} provide a non-local exit mechanism very -similar to @code{catch} and @code{throw}, with lexical scoping. -This package actually implements @code{cl-block} -in terms of @code{catch}; however, the lexical scoping allows the -byte-compiler to omit the costly @code{catch} step if the -body of the block does not actually @code{cl-return-from} the block. - -@defmac cl-block name forms@dots{} -The @var{forms} are evaluated as if by a @code{progn}. However, -if any of the @var{forms} execute @code{(cl-return-from @var{name})}, -they will jump out and return directly from the @code{cl-block} form. -The @code{cl-block} returns the result of the last @var{form} unless -a @code{cl-return-from} occurs. - -The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to -the @code{catch}/@code{throw} mechanism. The main differences are -that block @var{name}s are unevaluated symbols, rather than forms -(such as quoted symbols) that evaluate to a tag at run-time; and -also that blocks are always lexically scoped. -In a dynamically scoped @code{catch}, functions called from the -@code{catch} body can also @code{throw} to the @code{catch}. This -is not an option for @code{cl-block}, where -the @code{cl-return-from} referring to a block name must appear -physically within the @var{forms} that make up the body of the block. -They may not appear within other called functions, although they may -appear within macro expansions or @code{lambda}s in the body. Block -names and @code{catch} names form independent name-spaces. - -In true Common Lisp, @code{defun} and @code{defmacro} surround -the function or expander bodies with implicit blocks with the -same name as the function or macro. This does not occur in Emacs -Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro} -forms, which do create the implicit block. - -The Common Lisp looping constructs defined by this package, -such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks -just as in Common Lisp. - -Because they are implemented in terms of Emacs Lisp's @code{catch} -and @code{throw}, blocks have the same overhead as actual -@code{catch} constructs (roughly two function calls). However, -the byte compiler will optimize away the @code{catch} -if the block does -not in fact contain any @code{cl-return} or @code{cl-return-from} calls -that jump to it. This means that @code{cl-do} loops and @code{cl-defun} -functions that don't use @code{cl-return} don't pay the overhead to -support it. -@end defmac - -@defmac cl-return-from name [result] -This macro returns from the block named @var{name}, which must be -an (unevaluated) symbol. If a @var{result} form is specified, it -is evaluated to produce the result returned from the @code{block}. -Otherwise, @code{nil} is returned. -@end defmac - -@defmac cl-return [result] -This macro is exactly like @code{(cl-return-from nil @var{result})}. -Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose -themselves in @code{nil} blocks. -@end defmac - -@c FIXME? Maybe this should be in a separate section? -@defmac cl-tagbody &rest labels-or-statements -This macro executes statements while allowing for control transfer to -user-defined labels. Each element of @var{labels-or-statements} can -be either a label (an integer or a symbol), or a cons-cell -(a statement). This distinction is made before macroexpansion. -Statements are executed in sequence, discarding any return value. -Any statement can transfer control at any time to the statements that follow -one of the labels with the special form @code{(go @var{label})}. -Labels have lexical scope and dynamic extent. -@end defmac - - -@node Iteration -@section Iteration - -@noindent -The macros described here provide more sophisticated, high-level -looping constructs to complement Emacs Lisp's basic loop forms -(@pxref{Iteration,,,elisp,GNU Emacs Lisp Reference Manual}). - -@defmac cl-loop forms@dots{} -This package supports both the simple, old-style meaning of -@code{loop} and the extremely powerful and flexible feature known as -the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced -facility is discussed in the following section; @pxref{Loop Facility}. -The simple form of @code{loop} is described here. - -If @code{cl-loop} is followed by zero or more Lisp expressions, -then @code{(cl-loop @var{exprs}@dots{})} simply creates an infinite -loop executing the expressions over and over. The loop is -enclosed in an implicit @code{nil} block. Thus, - -@example -(cl-loop (foo) (if (no-more) (return 72)) (bar)) -@end example - -@noindent -is exactly equivalent to - -@example -(cl-block nil (while t (foo) (if (no-more) (return 72)) (bar))) -@end example - -If any of the expressions are plain symbols, the loop is instead -interpreted as a Loop Macro specification as described later. -(This is not a restriction in practice, since a plain symbol -in the above notation would simply access and throw away the -value of a variable.) -@end defmac - -@defmac cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} -This macro creates a general iterative loop. Each @var{spec} is -of the form - -@example -(@var{var} [@var{init} [@var{step}]]) -@end example - -The loop works as follows: First, each @var{var} is bound to the -associated @var{init} value as if by a @code{let} form. Then, in -each iteration of the loop, the @var{end-test} is evaluated; if -true, the loop is finished. Otherwise, the body @var{forms} are -evaluated, then each @var{var} is set to the associated @var{step} -expression (as if by a @code{cl-psetq} form) and the next iteration -begins. Once the @var{end-test} becomes true, the @var{result} -forms are evaluated (with the @var{var}s still bound to their -values) to produce the result returned by @code{cl-do}. - -The entire @code{cl-do} loop is enclosed in an implicit @code{nil} -block, so that you can use @code{(cl-return)} to break out of the -loop at any time. - -If there are no @var{result} forms, the loop returns @code{nil}. -If a given @var{var} has no @var{step} form, it is bound to its -@var{init} value but not otherwise modified during the @code{cl-do} -loop (unless the code explicitly modifies it); this case is just -a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})} -around the loop. If @var{init} is also omitted it defaults to -@code{nil}, and in this case a plain @samp{@var{var}} can be used -in place of @samp{(@var{var})}, again following the analogy with -@code{let}. - -This example (from Steele) illustrates a loop that applies the -function @code{f} to successive pairs of values from the lists -@code{foo} and @code{bar}; it is equivalent to the call -@code{(cl-mapcar 'f foo bar)}. Note that this loop has no body -@var{forms} at all, performing all its work as side effects of -the rest of the loop. - -@example -(cl-do ((x foo (cdr x)) - (y bar (cdr y)) - (z nil (cons (f (car x) (car y)) z))) - ((or (null x) (null y)) - (nreverse z))) -@end example -@end defmac - -@defmac cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} -This is to @code{cl-do} what @code{let*} is to @code{let}. In -particular, the initial values are bound as if by @code{let*} -rather than @code{let}, and the steps are assigned as if by -@code{setq} rather than @code{cl-psetq}. - -Here is another way to write the above loop: - -@example -(cl-do* ((xp foo (cdr xp)) - (yp bar (cdr yp)) - (x (car xp) (car xp)) - (y (car yp) (car yp)) - z) - ((or (null xp) (null yp)) - (nreverse z)) - (push (f x y) z)) -@end example -@end defmac - -@defmac cl-dolist (var list [result]) forms@dots{} -This is exactly like the standard Emacs Lisp macro @code{dolist}, -but surrounds the loop with an implicit @code{nil} block. -@end defmac - -@defmac cl-dotimes (var count [result]) forms@dots{} -This is exactly like the standard Emacs Lisp macro @code{dotimes}, -but surrounds the loop with an implicit @code{nil} block. -The body is executed with @var{var} bound to the integers -from zero (inclusive) to @var{count} (exclusive), in turn. Then -@c FIXME lispref does not state this part explicitly, could move this there. -the @code{result} form is evaluated with @var{var} bound to the total -number of iterations that were done (i.e., @code{(max 0 @var{count})}) -to get the return value for the loop form. -@end defmac - -@defmac cl-do-symbols (var [obarray [result]]) forms@dots{} -This loop iterates over all interned symbols. If @var{obarray} -is specified and is not @code{nil}, it loops over all symbols in -that obarray. For each symbol, the body @var{forms} are evaluated -with @var{var} bound to that symbol. The symbols are visited in -an unspecified order. Afterward the @var{result} form, if any, -is evaluated (with @var{var} bound to @code{nil}) to get the return -value. The loop is surrounded by an implicit @code{nil} block. -@end defmac - -@defmac cl-do-all-symbols (var [result]) forms@dots{} -This is identical to @code{cl-do-symbols} except that the @var{obarray} -argument is omitted; it always iterates over the default obarray. -@end defmac - -@xref{Mapping over Sequences}, for some more functions for -iterating over vectors or lists. - -@node Loop Facility -@section Loop Facility - -@noindent -A common complaint with Lisp's traditional looping constructs was -that they were either too simple and limited, such as @code{dotimes} -or @code{while}, or too unreadable and obscure, like Common Lisp's -@code{do} loop. - -To remedy this, Common Lisp added a construct called the ``Loop -Facility'' or ``@code{loop} macro'', with an easy-to-use but very -powerful and expressive syntax. - -@menu -* Loop Basics:: The @code{cl-loop} macro, basic clause structure. -* Loop Examples:: Working examples of the @code{cl-loop} macro. -* For Clauses:: Clauses introduced by @code{for} or @code{as}. -* Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc. -* Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc. -* Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally}. -@end menu - -@node Loop Basics -@subsection Loop Basics - -@noindent -The @code{cl-loop} macro essentially creates a mini-language within -Lisp that is specially tailored for describing loops. While this -language is a little strange-looking by the standards of regular Lisp, -it turns out to be very easy to learn and well-suited to its purpose. - -Since @code{cl-loop} is a macro, all parsing of the loop language -takes place at byte-compile time; compiled @code{cl-loop}s are just -as efficient as the equivalent @code{while} loops written longhand. - -@defmac cl-loop clauses@dots{} -A loop construct consists of a series of @var{clause}s, each -introduced by a symbol like @code{for} or @code{do}. Clauses -are simply strung together in the argument list of @code{cl-loop}, -with minimal extra parentheses. The various types of clauses -specify initializations, such as the binding of temporary -variables, actions to be taken in the loop, stepping actions, -and final cleanup. - -Common Lisp specifies a certain general order of clauses in a -loop: - -@example -(loop @var{name-clause} - @var{var-clauses}@dots{} - @var{action-clauses}@dots{}) -@end example - -The @var{name-clause} optionally gives a name to the implicit -block that surrounds the loop. By default, the implicit block -is named @code{nil}. The @var{var-clauses} specify what -variables should be bound during the loop, and how they should -be modified or iterated throughout the course of the loop. The -@var{action-clauses} are things to be done during the loop, such -as computing, collecting, and returning values. - -The Emacs version of the @code{cl-loop} macro is less restrictive about -the order of clauses, but things will behave most predictably if -you put the variable-binding clauses @code{with}, @code{for}, and -@code{repeat} before the action clauses. As in Common Lisp, -@code{initially} and @code{finally} clauses can go anywhere. - -Loops generally return @code{nil} by default, but you can cause -them to return a value by using an accumulation clause like -@code{collect}, an end-test clause like @code{always}, or an -explicit @code{return} clause to jump out of the implicit block. -(Because the loop body is enclosed in an implicit block, you can -also use regular Lisp @code{cl-return} or @code{cl-return-from} to -break out of the loop.) -@end defmac - -The following sections give some examples of the loop macro in -action, and describe the particular loop clauses in great detail. -Consult the second edition of Steele for additional discussion -and examples. - -@node Loop Examples -@subsection Loop Examples - -@noindent -Before listing the full set of clauses that are allowed, let's -look at a few example loops just to get a feel for the @code{cl-loop} -language. - -@example -(cl-loop for buf in (buffer-list) - collect (buffer-file-name buf)) -@end example - -@noindent -This loop iterates over all Emacs buffers, using the list -returned by @code{buffer-list}. For each buffer @var{buf}, -it calls @code{buffer-file-name} and collects the results into -a list, which is then returned from the @code{cl-loop} construct. -The result is a list of the file names of all the buffers in -Emacs's memory. The words @code{for}, @code{in}, and @code{collect} -are reserved words in the @code{cl-loop} language. - -@example -(cl-loop repeat 20 do (insert "Yowsa\n")) -@end example - -@noindent -This loop inserts the phrase ``Yowsa'' twenty times in the -current buffer. - -@example -(cl-loop until (eobp) do (munch-line) (forward-line 1)) -@end example - -@noindent -This loop calls @code{munch-line} on every line until the end -of the buffer. If point is already at the end of the buffer, -the loop exits immediately. - -@example -(cl-loop do (munch-line) until (eobp) do (forward-line 1)) -@end example - -@noindent -This loop is similar to the above one, except that @code{munch-line} -is always called at least once. - -@example -(cl-loop for x from 1 to 100 - for y = (* x x) - until (>= y 729) - finally return (list x (= y 729))) -@end example - -@noindent -This more complicated loop searches for a number @code{x} whose -square is 729. For safety's sake it only examines @code{x} -values up to 100; dropping the phrase @samp{to 100} would -cause the loop to count upwards with no limit. The second -@code{for} clause defines @code{y} to be the square of @code{x} -within the loop; the expression after the @code{=} sign is -reevaluated each time through the loop. The @code{until} -clause gives a condition for terminating the loop, and the -@code{finally} clause says what to do when the loop finishes. -(This particular example was written less concisely than it -could have been, just for the sake of illustration.) - -Note that even though this loop contains three clauses (two -@code{for}s and an @code{until}) that would have been enough to -define loops all by themselves, it still creates a single loop -rather than some sort of triple-nested loop. You must explicitly -nest your @code{cl-loop} constructs if you want nested loops. - -@node For Clauses -@subsection For Clauses - -@noindent -Most loops are governed by one or more @code{for} clauses. -A @code{for} clause simultaneously describes variables to be -bound, how those variables are to be stepped during the loop, -and usually an end condition based on those variables. - -The word @code{as} is a synonym for the word @code{for}. This -word is followed by a variable name, then a word like @code{from} -or @code{across} that describes the kind of iteration desired. -In Common Lisp, the phrase @code{being the} sometimes precedes -the type of iteration; in this package both @code{being} and -@code{the} are optional. The word @code{each} is a synonym -for @code{the}, and the word that follows it may be singular -or plural: @samp{for x being the elements of y} or -@samp{for x being each element of y}. Which form you use -is purely a matter of style. - -The variable is bound around the loop as if by @code{let}: - -@example -(setq i 'happy) -(cl-loop for i from 1 to 10 do (do-something-with i)) -i - @result{} happy -@end example - -@table @code -@item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3} -This type of @code{for} clause creates a counting loop. Each of -the three sub-terms is optional, though there must be at least one -term so that the clause is marked as a counting clause. - -The three expressions are the starting value, the ending value, and -the step value, respectively, of the variable. The loop counts -upwards by default (@var{expr3} must be positive), from @var{expr1} -to @var{expr2} inclusively. If you omit the @code{from} term, the -loop counts from zero; if you omit the @code{to} term, the loop -counts forever without stopping (unless stopped by some other -loop clause, of course); if you omit the @code{by} term, the loop -counts in steps of one. - -You can replace the word @code{from} with @code{upfrom} or -@code{downfrom} to indicate the direction of the loop. Likewise, -you can replace @code{to} with @code{upto} or @code{downto}. -For example, @samp{for x from 5 downto 1} executes five times -with @code{x} taking on the integers from 5 down to 1 in turn. -Also, you can replace @code{to} with @code{below} or @code{above}, -which are like @code{upto} and @code{downto} respectively except -that they are exclusive rather than inclusive limits: - -@example -(cl-loop for x to 10 collect x) - @result{} (0 1 2 3 4 5 6 7 8 9 10) -(cl-loop for x below 10 collect x) - @result{} (0 1 2 3 4 5 6 7 8 9) -@end example - -The @code{by} value is always positive, even for downward-counting -loops. Some sort of @code{from} value is required for downward -loops; @samp{for x downto 5} is not a valid loop clause all by -itself. - -@item for @var{var} in @var{list} by @var{function} -This clause iterates @var{var} over all the elements of @var{list}, -in turn. If you specify the @code{by} term, then @var{function} -is used to traverse the list instead of @code{cdr}; it must be a -function taking one argument. For example: - -@example -(cl-loop for x in '(1 2 3 4 5 6) collect (* x x)) - @result{} (1 4 9 16 25 36) -(cl-loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x)) - @result{} (1 9 25) -@end example - -@item for @var{var} on @var{list} by @var{function} -This clause iterates @var{var} over all the cons cells of @var{list}. - -@example -(cl-loop for x on '(1 2 3 4) collect x) - @result{} ((1 2 3 4) (2 3 4) (3 4) (4)) -@end example - -With @code{by}, there is no real reason that the @code{on} expression -must be a list. For example: - -@example -(cl-loop for x on first-animal by 'next-animal collect x) -@end example - -@noindent -where @code{(next-animal x)} takes an ``animal'' @var{x} and returns -the next in the (assumed) sequence of animals, or @code{nil} if -@var{x} was the last animal in the sequence. - -@item for @var{var} in-ref @var{list} by @var{function} -This is like a regular @code{in} clause, but @var{var} becomes -a @code{setf}-able ``reference'' onto the elements of the list -rather than just a temporary variable. For example, - -@example -(cl-loop for x in-ref my-list do (cl-incf x)) -@end example - -@noindent -increments every element of @code{my-list} in place. This clause -is an extension to standard Common Lisp. - -@item for @var{var} across @var{array} -This clause iterates @var{var} over all the elements of @var{array}, -which may be a vector or a string. - -@example -(cl-loop for x across "aeiou" - do (use-vowel (char-to-string x))) -@end example - -@item for @var{var} across-ref @var{array} -This clause iterates over an array, with @var{var} a @code{setf}-able -reference onto the elements; see @code{in-ref} above. - -@item for @var{var} being the elements of @var{sequence} -This clause iterates over the elements of @var{sequence}, which may -be a list, vector, or string. Since the type must be determined -at run-time, this is somewhat less efficient than @code{in} or -@code{across}. The clause may be followed by the additional term -@samp{using (index @var{var2})} to cause @var{var2} to be bound to -the successive indices (starting at 0) of the elements. - -This clause type is taken from older versions of the @code{loop} macro, -and is not present in modern Common Lisp. The @samp{using (sequence @dots{})} -term of the older macros is not supported. - -@item for @var{var} being the elements of-ref @var{sequence} -This clause iterates over a sequence, with @var{var} a @code{setf}-able -reference onto the elements; see @code{in-ref} above. - -@item for @var{var} being the symbols [of @var{obarray}] -This clause iterates over symbols, either over all interned symbols -or over all symbols in @var{obarray}. The loop is executed with -@var{var} bound to each symbol in turn. The symbols are visited in -an unspecified order. - -As an example, - -@example -(cl-loop for sym being the symbols - when (fboundp sym) - when (string-match "^map" (symbol-name sym)) - collect sym) -@end example - -@noindent -returns a list of all the functions whose names begin with @samp{map}. - -The Common Lisp words @code{external-symbols} and @code{present-symbols} -are also recognized but are equivalent to @code{symbols} in Emacs Lisp. - -Due to a minor implementation restriction, it will not work to have -more than one @code{for} clause iterating over symbols, hash tables, -keymaps, overlays, or intervals in a given @code{cl-loop}. Fortunately, -it would rarely if ever be useful to do so. It @emph{is} valid to mix -one of these types of clauses with other clauses like @code{for @dots{} to} -or @code{while}. - -@item for @var{var} being the hash-keys of @var{hash-table} -@itemx for @var{var} being the hash-values of @var{hash-table} -This clause iterates over the entries in @var{hash-table} with -@var{var} bound to each key, or value. A @samp{using} clause can bind -a second variable to the opposite part. - -@example -(cl-loop for k being the hash-keys of h - using (hash-values v) - do - (message "key %S -> value %S" k v)) -@end example - -@item for @var{var} being the key-codes of @var{keymap} -@itemx for @var{var} being the key-bindings of @var{keymap} -This clause iterates over the entries in @var{keymap}. -The iteration does not enter nested keymaps but does enter inherited -(parent) keymaps. -A @code{using} clause can access both the codes and the bindings -together. - -@example -(cl-loop for c being the key-codes of (current-local-map) - using (key-bindings b) - do - (message "key %S -> binding %S" c b)) -@end example - - -@item for @var{var} being the key-seqs of @var{keymap} -This clause iterates over all key sequences defined by @var{keymap} -and its nested keymaps, where @var{var} takes on values which are -vectors. The strings or vectors -are reused for each iteration, so you must copy them if you wish to keep -them permanently. You can add a @samp{using (key-bindings @dots{})} -clause to get the command bindings as well. - -@item for @var{var} being the overlays [of @var{buffer}] @dots{} -This clause iterates over the ``overlays'' of a buffer -(the clause @code{extents} is synonymous -with @code{overlays}). If the @code{of} term is omitted, the current -buffer is used. -This clause also accepts optional @samp{from @var{pos}} and -@samp{to @var{pos}} terms, limiting the clause to overlays which -overlap the specified region. - -@item for @var{var} being the intervals [of @var{buffer}] @dots{} -This clause iterates over all intervals of a buffer with constant -text properties. The variable @var{var} will be bound to conses -of start and end positions, where one start position is always equal -to the previous end position. The clause allows @code{of}, -@code{from}, @code{to}, and @code{property} terms, where the latter -term restricts the search to just the specified property. The -@code{of} term may specify either a buffer or a string. - -@item for @var{var} being the frames -This clause iterates over all Emacs frames. The clause @code{screens} is -a synonym for @code{frames}. The frames are visited in -@code{next-frame} order starting from @code{selected-frame}. - -@item for @var{var} being the windows [of @var{frame}] -This clause iterates over the windows (in the Emacs sense) of -the current frame, or of the specified @var{frame}. It visits windows -in @code{next-window} order starting from @code{selected-window} -(or @code{frame-selected-window} if you specify @var{frame}). -This clause treats the minibuffer window in the same way as -@code{next-window} does. For greater flexibility, consider using -@code{walk-windows} instead. - -@item for @var{var} being the buffers -This clause iterates over all buffers in Emacs. It is equivalent -to @samp{for @var{var} in (buffer-list)}. - -@item for @var{var} = @var{expr1} then @var{expr2} -This clause does a general iteration. The first time through -the loop, @var{var} will be bound to @var{expr1}. On the second -and successive iterations it will be set by evaluating @var{expr2} -(which may refer to the old value of @var{var}). For example, -these two loops are effectively the same: - -@example -(cl-loop for x on my-list by 'cddr do @dots{}) -(cl-loop for x = my-list then (cddr x) while x do @dots{}) -@end example - -Note that this type of @code{for} clause does not imply any sort -of terminating condition; the above example combines it with a -@code{while} clause to tell when to end the loop. - -If you omit the @code{then} term, @var{expr1} is used both for -the initial setting and for successive settings: - -@example -(cl-loop for x = (random) when (> x 0) return x) -@end example - -@noindent -This loop keeps taking random numbers from the @code{(random)} -function until it gets a positive one, which it then returns. -@end table - -If you include several @code{for} clauses in a row, they are -treated sequentially (as if by @code{let*} and @code{setq}). -You can instead use the word @code{and} to link the clauses, -in which case they are processed in parallel (as if by @code{let} -and @code{cl-psetq}). - -@example -(cl-loop for x below 5 for y = nil then x collect (list x y)) - @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4)) -(cl-loop for x below 5 and y = nil then x collect (list x y)) - @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3)) -@end example - -@noindent -In the first loop, @code{y} is set based on the value of @code{x} -that was just set by the previous clause; in the second loop, -@code{x} and @code{y} are set simultaneously so @code{y} is set -based on the value of @code{x} left over from the previous time -through the loop. - -@cindex destructuring, in cl-loop -Another feature of the @code{cl-loop} macro is @emph{destructuring}, -similar in concept to the destructuring provided by @code{defmacro} -(@pxref{Argument Lists}). -The @var{var} part of any @code{for} clause can be given as a list -of variables instead of a single variable. The values produced -during loop execution must be lists; the values in the lists are -stored in the corresponding variables. - -@example -(cl-loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y)) - @result{} (5 9 13) -@end example - -In loop destructuring, if there are more values than variables -the trailing values are ignored, and if there are more variables -than values the trailing variables get the value @code{nil}. -If @code{nil} is used as a variable name, the corresponding -values are ignored. Destructuring may be nested, and dotted -lists of variables like @code{(x . y)} are allowed, so for example -to process an alist - -@example -(cl-loop for (key . value) in '((a . 1) (b . 2)) - collect value) - @result{} (1 2) -@end example - -@node Iteration Clauses -@subsection Iteration Clauses - -@noindent -Aside from @code{for} clauses, there are several other loop clauses -that control the way the loop operates. They might be used by -themselves, or in conjunction with one or more @code{for} clauses. - -@table @code -@item repeat @var{integer} -This clause simply counts up to the specified number using an -internal temporary variable. The loops - -@example -(cl-loop repeat (1+ n) do @dots{}) -(cl-loop for temp to n do @dots{}) -@end example - -@noindent -are identical except that the second one forces you to choose -a name for a variable you aren't actually going to use. - -@item while @var{condition} -This clause stops the loop when the specified condition (any Lisp -expression) becomes @code{nil}. For example, the following two -loops are equivalent, except for the implicit @code{nil} block -that surrounds the second one: - -@example -(while @var{cond} @var{forms}@dots{}) -(cl-loop while @var{cond} do @var{forms}@dots{}) -@end example - -@item until @var{condition} -This clause stops the loop when the specified condition is true, -i.e., non-@code{nil}. - -@item always @var{condition} -This clause stops the loop when the specified condition is @code{nil}. -Unlike @code{while}, it stops the loop using @code{return nil} so that -the @code{finally} clauses are not executed. If all the conditions -were non-@code{nil}, the loop returns @code{t}: - -@example -(if (cl-loop for size in size-list always (> size 10)) - (some-big-sizes) - (no-big-sizes)) -@end example - -@item never @var{condition} -This clause is like @code{always}, except that the loop returns -@code{t} if any conditions were false, or @code{nil} otherwise. - -@item thereis @var{condition} -This clause stops the loop when the specified form is non-@code{nil}; -in this case, it returns that non-@code{nil} value. If all the -values were @code{nil}, the loop returns @code{nil}. -@end table - -@node Accumulation Clauses -@subsection Accumulation Clauses - -@noindent -These clauses cause the loop to accumulate information about the -specified Lisp @var{form}. The accumulated result is returned -from the loop unless overridden, say, by a @code{return} clause. - -@table @code -@item collect @var{form} -This clause collects the values of @var{form} into a list. Several -examples of @code{collect} appear elsewhere in this manual. - -The word @code{collecting} is a synonym for @code{collect}, and -likewise for the other accumulation clauses. - -@item append @var{form} -This clause collects lists of values into a result list using -@code{append}. - -@item nconc @var{form} -This clause collects lists of values into a result list by -destructively modifying the lists rather than copying them. - -@item concat @var{form} -This clause concatenates the values of the specified @var{form} -into a string. (It and the following clause are extensions to -standard Common Lisp.) - -@item vconcat @var{form} -This clause concatenates the values of the specified @var{form} -into a vector. - -@item count @var{form} -This clause counts the number of times the specified @var{form} -evaluates to a non-@code{nil} value. - -@item sum @var{form} -This clause accumulates the sum of the values of the specified -@var{form}, which must evaluate to a number. - -@item maximize @var{form} -This clause accumulates the maximum value of the specified @var{form}, -which must evaluate to a number. The return value is undefined if -@code{maximize} is executed zero times. - -@item minimize @var{form} -This clause accumulates the minimum value of the specified @var{form}. -@end table - -Accumulation clauses can be followed by @samp{into @var{var}} to -cause the data to be collected into variable @var{var} (which is -automatically @code{let}-bound during the loop) rather than an -unnamed temporary variable. Also, @code{into} accumulations do -not automatically imply a return value. The loop must use some -explicit mechanism, such as @code{finally return}, to return -the accumulated result. - -It is valid for several accumulation clauses of the same type to -accumulate into the same place. From Steele: - -@example -(cl-loop for name in '(fred sue alice joe june) - for kids in '((bob ken) () () (kris sunshine) ()) - collect name - append kids) - @result{} (fred bob ken sue alice joe kris sunshine june) -@end example - -@node Other Clauses -@subsection Other Clauses - -@noindent -This section describes the remaining loop clauses. - -@table @code -@item with @var{var} = @var{value} -This clause binds a variable to a value around the loop, but -otherwise leaves the variable alone during the loop. The following -loops are basically equivalent: - -@example -(cl-loop with x = 17 do @dots{}) -(let ((x 17)) (cl-loop do @dots{})) -(cl-loop for x = 17 then x do @dots{}) -@end example - -Naturally, the variable @var{var} might be used for some purpose -in the rest of the loop. For example: - -@example -(cl-loop for x in my-list with res = nil do (push x res) - finally return res) -@end example - -This loop inserts the elements of @code{my-list} at the front of -a new list being accumulated in @code{res}, then returns the -list @code{res} at the end of the loop. The effect is similar -to that of a @code{collect} clause, but the list gets reversed -by virtue of the fact that elements are being pushed onto the -front of @code{res} rather than the end. - -If you omit the @code{=} term, the variable is initialized to -@code{nil}. (Thus the @samp{= nil} in the above example is -unnecessary.) - -Bindings made by @code{with} are sequential by default, as if -by @code{let*}. Just like @code{for} clauses, @code{with} clauses -can be linked with @code{and} to cause the bindings to be made by -@code{let} instead. - -@item if @var{condition} @var{clause} -This clause executes the following loop clause only if the specified -condition is true. The following @var{clause} should be an accumulation, -@code{do}, @code{return}, @code{if}, or @code{unless} clause. -Several clauses may be linked by separating them with @code{and}. -These clauses may be followed by @code{else} and a clause or clauses -to execute if the condition was false. The whole construct may -optionally be followed by the word @code{end} (which may be used to -disambiguate an @code{else} or @code{and} in a nested @code{if}). - -The actual non-@code{nil} value of the condition form is available -by the name @code{it} in the ``then'' part. For example: - -@example -(setq funny-numbers '(6 13 -1)) - @result{} (6 13 -1) -(cl-loop for x below 10 - if (cl-oddp x) - collect x into odds - and if (memq x funny-numbers) return (cdr it) end - else - collect x into evens - finally return (vector odds evens)) - @result{} [(1 3 5 7 9) (0 2 4 6 8)] -(setq funny-numbers '(6 7 13 -1)) - @result{} (6 7 13 -1) -(cl-loop <@r{same thing again}>) - @result{} (13 -1) -@end example - -Note the use of @code{and} to put two clauses into the ``then'' -part, one of which is itself an @code{if} clause. Note also that -@code{end}, while normally optional, was necessary here to make -it clear that the @code{else} refers to the outermost @code{if} -clause. In the first case, the loop returns a vector of lists -of the odd and even values of @var{x}. In the second case, the -odd number 7 is one of the @code{funny-numbers} so the loop -returns early; the actual returned value is based on the result -of the @code{memq} call. - -@item when @var{condition} @var{clause} -This clause is just a synonym for @code{if}. - -@item unless @var{condition} @var{clause} -The @code{unless} clause is just like @code{if} except that the -sense of the condition is reversed. - -@item named @var{name} -This clause gives a name other than @code{nil} to the implicit -block surrounding the loop. The @var{name} is the symbol to be -used as the block name. - -@item initially [do] @var{forms}@dots{} -This keyword introduces one or more Lisp forms which will be -executed before the loop itself begins (but after any variables -requested by @code{for} or @code{with} have been bound to their -initial values). @code{initially} clauses can appear anywhere; -if there are several, they are executed in the order they appear -in the loop. The keyword @code{do} is optional. - -@item finally [do] @var{forms}@dots{} -This introduces Lisp forms which will be executed after the loop -finishes (say, on request of a @code{for} or @code{while}). -@code{initially} and @code{finally} clauses may appear anywhere -in the loop construct, but they are executed (in the specified -order) at the beginning or end, respectively, of the loop. - -@item finally return @var{form} -This says that @var{form} should be executed after the loop -is done to obtain a return value. (Without this, or some other -clause like @code{collect} or @code{return}, the loop will simply -return @code{nil}.) Variables bound by @code{for}, @code{with}, -or @code{into} will still contain their final values when @var{form} -is executed. - -@item do @var{forms}@dots{} -The word @code{do} may be followed by any number of Lisp expressions -which are executed as an implicit @code{progn} in the body of the -loop. Many of the examples in this section illustrate the use of -@code{do}. - -@item return @var{form} -This clause causes the loop to return immediately. The following -Lisp form is evaluated to give the return value of the loop -form. The @code{finally} clauses, if any, are not executed. -Of course, @code{return} is generally used inside an @code{if} or -@code{unless}, as its use in a top-level loop clause would mean -the loop would never get to ``loop'' more than once. - -The clause @samp{return @var{form}} is equivalent to -@samp{do (cl-return @var{form})} (or @code{cl-return-from} if the loop -was named). The @code{return} clause is implemented a bit more -efficiently, though. -@end table - -While there is no high-level way to add user extensions to @code{cl-loop}, -this package does offer two properties called @code{cl-loop-handler} -and @code{cl-loop-for-handler} which are functions to be called when a -given symbol is encountered as a top-level loop clause or @code{for} -clause, respectively. Consult the source code in file -@file{cl-macs.el} for details. - -This package's @code{cl-loop} macro is compatible with that of Common -Lisp, except that a few features are not implemented: @code{loop-finish} -and data-type specifiers. Naturally, the @code{for} clauses that -iterate over keymaps, overlays, intervals, frames, windows, and -buffers are Emacs-specific extensions. - -@node Multiple Values -@section Multiple Values - -@noindent -Common Lisp functions can return zero or more results. Emacs Lisp -functions, by contrast, always return exactly one result. This -package makes no attempt to emulate Common Lisp multiple return -values; Emacs versions of Common Lisp functions that return more -than one value either return just the first value (as in -@code{cl-compiler-macroexpand}) or return a list of values. -This package @emph{does} define placeholders -for the Common Lisp functions that work with multiple values, but -in Emacs Lisp these functions simply operate on lists instead. -The @code{cl-values} form, for example, is a synonym for @code{list} -in Emacs. - -@defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{} -This form evaluates @var{values-form}, which must return a list of -values. It then binds the @var{var}s to these respective values, -as if by @code{let}, and then executes the body @var{forms}. -If there are more @var{var}s than values, the extra @var{var}s -are bound to @code{nil}. If there are fewer @var{var}s than -values, the excess values are ignored. -@end defmac - -@defmac cl-multiple-value-setq (var@dots{}) form -This form evaluates @var{form}, which must return a list of values. -It then sets the @var{var}s to these respective values, as if by -@code{setq}. Extra @var{var}s or values are treated the same as -in @code{cl-multiple-value-bind}. -@end defmac - -Since a perfect emulation is not feasible in Emacs Lisp, this -package opts to keep it as simple and predictable as possible. - -@node Macros -@chapter Macros - -@noindent -This package implements the various Common Lisp features of -@code{defmacro}, such as destructuring, @code{&environment}, -and @code{&body}. Top-level @code{&whole} is not implemented -for @code{defmacro} due to technical difficulties. -@xref{Argument Lists}. - -Destructuring is made available to the user by way of the -following macro: - -@defmac cl-destructuring-bind arglist expr forms@dots{} -This macro expands to code that executes @var{forms}, with -the variables in @var{arglist} bound to the list of values -returned by @var{expr}. The @var{arglist} can include all -the features allowed for @code{cl-defmacro} argument lists, -including destructuring. (The @code{&environment} keyword -is not allowed.) The macro expansion will signal an error -if @var{expr} returns a list of the wrong number of arguments -or with incorrect keyword arguments. -@end defmac - -@cindex compiler macros -@cindex define compiler macros -This package also includes the Common Lisp @code{define-compiler-macro} -facility, which allows you to define compile-time expansions and -optimizations for your functions. - -@defmac cl-define-compiler-macro name arglist forms@dots{} -This form is similar to @code{defmacro}, except that it only expands -calls to @var{name} at compile-time; calls processed by the Lisp -interpreter are not expanded, nor are they expanded by the -@code{macroexpand} function. - -The argument list may begin with a @code{&whole} keyword and a -variable. This variable is bound to the macro-call form itself, -i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}. -If the macro expander returns this form unchanged, then the -compiler treats it as a normal function call. This allows -compiler macros to work as optimizers for special cases of a -function, leaving complicated cases alone. - -For example, here is a simplified version of a definition that -appears as a standard part of this package: - -@example -(cl-define-compiler-macro cl-member (&whole form a list &rest keys) - (if (and (null keys) - (eq (car-safe a) 'quote) - (not (floatp (cadr a)))) - (list 'memq a list) - form)) -@end example - -@noindent -This definition causes @code{(cl-member @var{a} @var{list})} to change -to a call to the faster @code{memq} in the common case where @var{a} -is a non-floating-point constant; if @var{a} is anything else, or -if there are any keyword arguments in the call, then the original -@code{cl-member} call is left intact. (The actual compiler macro -for @code{cl-member} optimizes a number of other cases, including -common @code{:test} predicates.) -@end defmac - -@defun cl-compiler-macroexpand form -This function is analogous to @code{macroexpand}, except that it -expands compiler macros rather than regular macros. It returns -@var{form} unchanged if it is not a call to a function for which -a compiler macro has been defined, or if that compiler macro -decided to punt by returning its @code{&whole} argument. Like -@code{macroexpand}, it expands repeatedly until it reaches a form -for which no further expansion is possible. -@end defun - -@xref{Macro Bindings}, for descriptions of the @code{cl-macrolet} -and @code{cl-symbol-macrolet} forms for making ``local'' macro -definitions. - -@node Declarations -@chapter Declarations - -@noindent -Common Lisp includes a complex and powerful ``declaration'' -mechanism that allows you to give the compiler special hints -about the types of data that will be stored in particular variables, -and about the ways those variables and functions will be used. This -package defines versions of all the Common Lisp declaration forms: -@code{declare}, @code{locally}, @code{proclaim}, @code{declaim}, -and @code{the}. - -Most of the Common Lisp declarations are not currently useful in Emacs -Lisp. For example, the byte-code system provides little -opportunity to benefit from type information. -@ignore -and @code{special} declarations are redundant in a fully -dynamically-scoped Lisp. -@end ignore -A few declarations are meaningful when byte compiler optimizations -are enabled, as they are by the default. Otherwise these -declarations will effectively be ignored. - -@defun cl-proclaim decl-spec -This function records a ``global'' declaration specified by -@var{decl-spec}. Since @code{cl-proclaim} is a function, @var{decl-spec} -is evaluated and thus should normally be quoted. -@end defun - -@defmac cl-declaim decl-specs@dots{} -This macro is like @code{cl-proclaim}, except that it takes any number -of @var{decl-spec} arguments, and the arguments are unevaluated and -unquoted. The @code{cl-declaim} macro also puts @code{(cl-eval-when -(compile load eval) @dots{})} around the declarations so that they will -be registered at compile-time as well as at run-time. (This is vital, -since normally the declarations are meant to influence the way the -compiler treats the rest of the file that contains the @code{cl-declaim} -form.) -@end defmac - -@defmac cl-declare decl-specs@dots{} -This macro is used to make declarations within functions and other -code. Common Lisp allows declarations in various locations, generally -at the beginning of any of the many ``implicit @code{progn}s'' -throughout Lisp syntax, such as function bodies, @code{let} bodies, -etc. Currently the only declaration understood by @code{cl-declare} -is @code{special}. -@end defmac - -@defmac cl-locally declarations@dots{} forms@dots{} -In this package, @code{cl-locally} is no different from @code{progn}. -@end defmac - -@defmac cl-the type form -Type information provided by @code{cl-the} is ignored in this package; -in other words, @code{(cl-the @var{type} @var{form})} is equivalent to -@var{form}. Future byte-compiler optimizations may make use of this -information. - -For example, @code{mapcar} can map over both lists and arrays. It is -hard for the compiler to expand @code{mapcar} into an in-line loop -unless it knows whether the sequence will be a list or an array ahead -of time. With @code{(mapcar 'car (cl-the vector foo))}, a future -compiler would have enough information to expand the loop in-line. -For now, Emacs Lisp will treat the above code as exactly equivalent -to @code{(mapcar 'car foo)}. -@end defmac - -Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or -@code{cl-declare} should be a list beginning with a symbol that says -what kind of declaration it is. This package currently understands -@code{special}, @code{inline}, @code{notinline}, @code{optimize}, -and @code{warn} declarations. (The @code{warn} declaration is an -extension of standard Common Lisp.) Other Common Lisp declarations, -such as @code{type} and @code{ftype}, are silently ignored. - -@table @code -@item special -@c FIXME ? -Since all variables in Emacs Lisp are ``special'' (in the Common -Lisp sense), @code{special} declarations are only advisory. They -simply tell the byte compiler that the specified -variables are intentionally being referred to without being -bound in the body of the function. The compiler normally emits -warnings for such references, since they could be typographical -errors for references to local variables. - -The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is -equivalent to @code{(defvar @var{var1}) (defvar @var{var2})}. - -In top-level contexts, it is generally better to write -@code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))}, -since @code{defvar} makes your intentions clearer. - -@item inline -The @code{inline} @var{decl-spec} lists one or more functions -whose bodies should be expanded ``in-line'' into calling functions -whenever the compiler is able to arrange for it. For example, -the function @code{cl-acons} is declared @code{inline} -by this package so that the form @code{(cl-acons @var{key} @var{value} -@var{alist})} will -expand directly into @code{(cons (cons @var{key} @var{value}) @var{alist})} -when it is called in user functions, so as to save function calls. - -The following declarations are all equivalent. Note that the -@code{defsubst} form is a convenient way to define a function -and declare it inline all at once. - -@example -(cl-declaim (inline foo bar)) -(cl-eval-when (compile load eval) - (cl-proclaim '(inline foo bar))) -(defsubst foo (@dots{}) @dots{}) ; instead of defun -@end example - -@strong{Please note:} this declaration remains in effect after the -containing source file is done. It is correct to use it to -request that a function you have defined should be inlined, -but it is impolite to use it to request inlining of an external -function. - -In Common Lisp, it is possible to use @code{(declare (inline @dots{}))} -before a particular call to a function to cause just that call to -be inlined; the current byte compilers provide no way to implement -this, so @code{(cl-declare (inline @dots{}))} is currently ignored by -this package. - -@item notinline -The @code{notinline} declaration lists functions which should -not be inlined after all; it cancels a previous @code{inline} -declaration. - -@item optimize -This declaration controls how much optimization is performed by -the compiler. - -The word @code{optimize} is followed by any number of lists like -@code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several -optimization ``qualities''; this package ignores all but @code{speed} -and @code{safety}. The value of a quality should be an integer from -0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''. -The default level for both qualities is 1. - -In this package, the @code{speed} quality is tied to the @code{byte-optimize} -flag, which is set to @code{nil} for @code{(speed 0)} and to -@code{t} for higher settings; and the @code{safety} quality is -tied to the @code{byte-compile-delete-errors} flag, which is -set to @code{nil} for @code{(safety 3)} and to @code{t} for all -lower settings. (The latter flag controls whether the compiler -is allowed to optimize out code whose only side-effect could -be to signal an error, e.g., rewriting @code{(progn foo bar)} to -@code{bar} when it is not known whether @code{foo} will be bound -at run-time.) - -Note that even compiling with @code{(safety 0)}, the Emacs -byte-code system provides sufficient checking to prevent real -harm from being done. For example, barring serious bugs in -Emacs itself, Emacs will not crash with a segmentation fault -just because of an error in a fully-optimized Lisp program. - -The @code{optimize} declaration is normally used in a top-level -@code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows -it to be used with @code{declare} to set the level of optimization -locally for a given form, but this will not work correctly with the -current byte-compiler. (The @code{cl-declare} -will set the new optimization level, but that level will not -automatically be unset after the enclosing form is done.) - -@item warn -This declaration controls what sorts of warnings are generated -by the byte compiler. The word @code{warn} is followed by any -number of ``warning qualities'', similar in form to optimization -qualities. The currently supported warning types are -@code{redefine}, @code{callargs}, @code{unresolved}, and -@code{free-vars}; in the current system, a value of 0 will -disable these warnings and any higher value will enable them. -See the documentation of the variable @code{byte-compile-warnings} -for more details. -@end table - -@node Symbols -@chapter Symbols - -@noindent -This package defines several symbol-related features that were -missing from Emacs Lisp. - -@menu -* Property Lists:: @code{cl-get}, @code{cl-remprop}, @code{cl-getf}, @code{cl-remf}. -* Creating Symbols:: @code{cl-gensym}, @code{cl-gentemp}. -@end menu - -@node Property Lists -@section Property Lists - -@noindent -These functions augment the standard Emacs Lisp functions @code{get} -and @code{put} for operating on properties attached to symbols. -There are also functions for working with property lists as -first-class data structures not attached to particular symbols. - -@defun cl-get symbol property &optional default -This function is like @code{get}, except that if the property is -not found, the @var{default} argument provides the return value. -(The Emacs Lisp @code{get} function always uses @code{nil} as -the default; this package's @code{cl-get} is equivalent to Common -Lisp's @code{get}.) - -The @code{cl-get} function is @code{setf}-able; when used in this -fashion, the @var{default} argument is allowed but ignored. -@end defun - -@defun cl-remprop symbol property -This function removes the entry for @var{property} from the property -list of @var{symbol}. It returns a true value if the property was -indeed found and removed, or @code{nil} if there was no such property. -(This function was probably omitted from Emacs originally because, -since @code{get} did not allow a @var{default}, it was very difficult -to distinguish between a missing property and a property whose value -was @code{nil}; thus, setting a property to @code{nil} was close -enough to @code{cl-remprop} for most purposes.) -@end defun - -@defun cl-getf place property &optional default -This function scans the list @var{place} as if it were a property -list, i.e., a list of alternating property names and values. If -an even-numbered element of @var{place} is found which is @code{eq} -to @var{property}, the following odd-numbered element is returned. -Otherwise, @var{default} is returned (or @code{nil} if no default -is given). - -In particular, - -@example -(get sym prop) @equiv{} (cl-getf (symbol-plist sym) prop) -@end example - -It is valid to use @code{cl-getf} as a @code{setf} place, in which case -its @var{place} argument must itself be a valid @code{setf} place. -The @var{default} argument, if any, is ignored in this context. -The effect is to change (via @code{setcar}) the value cell in the -list that corresponds to @var{property}, or to cons a new property-value -pair onto the list if the property is not yet present. - -@example -(put sym prop val) @equiv{} (setf (cl-getf (symbol-plist sym) prop) val) -@end example - -The @code{get} and @code{cl-get} functions are also @code{setf}-able. -The fact that @code{default} is ignored can sometimes be useful: - -@example -(cl-incf (cl-get 'foo 'usage-count 0)) -@end example - -Here, symbol @code{foo}'s @code{usage-count} property is incremented -if it exists, or set to 1 (an incremented 0) otherwise. - -When not used as a @code{setf} form, @code{cl-getf} is just a regular -function and its @var{place} argument can actually be any Lisp -expression. -@end defun - -@defmac cl-remf place property -This macro removes the property-value pair for @var{property} from -the property list stored at @var{place}, which is any @code{setf}-able -place expression. It returns true if the property was found. Note -that if @var{property} happens to be first on the list, this will -effectively do a @code{(setf @var{place} (cddr @var{place}))}, -whereas if it occurs later, this simply uses @code{setcdr} to splice -out the property and value cells. -@end defmac - -@node Creating Symbols -@section Creating Symbols - -@noindent -These functions create unique symbols, typically for use as -temporary variables. - -@defun cl-gensym &optional x -This function creates a new, uninterned symbol (using @code{make-symbol}) -with a unique name. (The name of an uninterned symbol is relevant -only if the symbol is printed.) By default, the name is generated -from an increasing sequence of numbers, @samp{G1000}, @samp{G1001}, -@samp{G1002}, etc. If the optional argument @var{x} is a string, that -string is used as a prefix instead of @samp{G}. Uninterned symbols -are used in macro expansions for temporary variables, to ensure that -their names will not conflict with ``real'' variables in the user's -code. - -(Internally, the variable @code{cl--gensym-counter} holds the counter -used to generate names. It is incremented after each use. In Common -Lisp this is initialized with 0, but this package initializes it with -a random time-dependent value to avoid trouble when two files that -each used @code{cl-gensym} in their compilation are loaded together. -Uninterned symbols become interned when the compiler writes them out -to a file and the Emacs loader loads them, so their names have to be -treated a bit more carefully than in Common Lisp where uninterned -symbols remain uninterned after loading.) -@end defun - -@defun cl-gentemp &optional x -This function is like @code{cl-gensym}, except that it produces a new -@emph{interned} symbol. If the symbol that is generated already -exists, the function keeps incrementing the counter and trying -again until a new symbol is generated. -@end defun - -This package automatically creates all keywords that are called for by -@code{&key} argument specifiers, and discourages the use of keywords -as data unrelated to keyword arguments, so the related function -@code{defkeyword} (to create self-quoting keyword symbols) is not -provided. - -@node Numbers -@chapter Numbers - -@noindent -This section defines a few simple Common Lisp operations on numbers -that were left out of Emacs Lisp. - -@menu -* Predicates on Numbers:: @code{cl-plusp}, @code{cl-oddp}, etc. -* Numerical Functions:: @code{cl-floor}, @code{cl-ceiling}, etc. -* Random Numbers:: @code{cl-random}, @code{cl-make-random-state}. -* Implementation Parameters:: @code{cl-most-positive-float}, etc. -@end menu - -@node Predicates on Numbers -@section Predicates on Numbers - -@noindent -These functions return @code{t} if the specified condition is -true of the numerical argument, or @code{nil} otherwise. - -@defun cl-plusp number -This predicate tests whether @var{number} is positive. It is an -error if the argument is not a number. -@end defun - -@defun cl-minusp number -This predicate tests whether @var{number} is negative. It is an -error if the argument is not a number. -@end defun - -@defun cl-oddp integer -This predicate tests whether @var{integer} is odd. It is an -error if the argument is not an integer. -@end defun - -@defun cl-evenp integer -This predicate tests whether @var{integer} is even. It is an -error if the argument is not an integer. -@end defun - -@node Numerical Functions -@section Numerical Functions - -@noindent -These functions perform various arithmetic operations on numbers. - -@defun cl-gcd &rest integers -This function returns the Greatest Common Divisor of the arguments. -For one argument, it returns the absolute value of that argument. -For zero arguments, it returns zero. -@end defun - -@defun cl-lcm &rest integers -This function returns the Least Common Multiple of the arguments. -For one argument, it returns the absolute value of that argument. -For zero arguments, it returns one. -@end defun - -@defun cl-isqrt integer -This function computes the ``integer square root'' of its integer -argument, i.e., the greatest integer less than or equal to the true -square root of the argument. -@end defun - -@defun cl-floor number &optional divisor -With one argument, @code{cl-floor} returns a list of two numbers: -The argument rounded down (toward minus infinity) to an integer, -and the ``remainder'' which would have to be added back to the -first return value to yield the argument again. If the argument -is an integer @var{x}, the result is always the list @code{(@var{x} 0)}. -If the argument is a floating-point number, the first -result is a Lisp integer and the second is a Lisp float between -0 (inclusive) and 1 (exclusive). - -With two arguments, @code{cl-floor} divides @var{number} by -@var{divisor}, and returns the floor of the quotient and the -corresponding remainder as a list of two numbers. If -@code{(cl-floor @var{x} @var{y})} returns @code{(@var{q} @var{r})}, -then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r} -between 0 (inclusive) and @var{r} (exclusive). Also, note -that @code{(cl-floor @var{x})} is exactly equivalent to -@code{(cl-floor @var{x} 1)}. - -This function is entirely compatible with Common Lisp's @code{floor} -function, except that it returns the two results in a list since -Emacs Lisp does not support multiple-valued functions. -@end defun - -@defun cl-ceiling number &optional divisor -This function implements the Common Lisp @code{ceiling} function, -which is analogous to @code{floor} except that it rounds the -argument or quotient of the arguments up toward plus infinity. -The remainder will be between 0 and minus @var{r}. -@end defun - -@defun cl-truncate number &optional divisor -This function implements the Common Lisp @code{truncate} function, -which is analogous to @code{floor} except that it rounds the -argument or quotient of the arguments toward zero. Thus it is -equivalent to @code{cl-floor} if the argument or quotient is -positive, or to @code{cl-ceiling} otherwise. The remainder has -the same sign as @var{number}. -@end defun - -@defun cl-round number &optional divisor -This function implements the Common Lisp @code{round} function, -which is analogous to @code{floor} except that it rounds the -argument or quotient of the arguments to the nearest integer. -In the case of a tie (the argument or quotient is exactly -halfway between two integers), it rounds to the even integer. -@end defun - -@defun cl-mod number divisor -This function returns the same value as the second return value -of @code{cl-floor}. -@end defun - -@defun cl-rem number divisor -This function returns the same value as the second return value -of @code{cl-truncate}. -@end defun - -@node Random Numbers -@section Random Numbers - -@noindent -This package also provides an implementation of the Common Lisp -random number generator. It uses its own additive-congruential -algorithm, which is much more likely to give statistically clean -@c FIXME? Still true? -random numbers than the simple generators supplied by many -operating systems. - -@defun cl-random number &optional state -This function returns a random nonnegative number less than -@var{number}, and of the same type (either integer or floating-point). -The @var{state} argument should be a @code{random-state} object -that holds the state of the random number generator. The -function modifies this state object as a side effect. If -@var{state} is omitted, it defaults to the internal variable -@code{cl--random-state}, which contains a pre-initialized -default @code{random-state} object. (Since any number of programs in -the Emacs process may be accessing @code{cl--random-state} in -interleaved fashion, the sequence generated from this will be -irreproducible for all intents and purposes.) -@end defun - -@defun cl-make-random-state &optional state -This function creates or copies a @code{random-state} object. -If @var{state} is omitted or @code{nil}, it returns a new copy of -@code{cl--random-state}. This is a copy in the sense that future -sequences of calls to @code{(cl-random @var{n})} and -@code{(cl-random @var{n} @var{s})} (where @var{s} is the new -random-state object) will return identical sequences of random -numbers. - -If @var{state} is a @code{random-state} object, this function -returns a copy of that object. If @var{state} is @code{t}, this -function returns a new @code{random-state} object seeded from the -date and time. As an extension to Common Lisp, @var{state} may also -be an integer in which case the new object is seeded from that -integer; each different integer seed will result in a completely -different sequence of random numbers. - -It is valid to print a @code{random-state} object to a buffer or -file and later read it back with @code{read}. If a program wishes -to use a sequence of pseudo-random numbers which can be reproduced -later for debugging, it can call @code{(cl-make-random-state t)} to -get a new sequence, then print this sequence to a file. When the -program is later rerun, it can read the original run's random-state -from the file. -@end defun - -@defun cl-random-state-p object -This predicate returns @code{t} if @var{object} is a -@code{random-state} object, or @code{nil} otherwise. -@end defun - -@node Implementation Parameters -@section Implementation Parameters - -@noindent -This package defines several useful constants having to do with -floating-point numbers. - -It determines their values by exercising the computer's -floating-point arithmetic in various ways. Because this operation -might be slow, the code for initializing them is kept in a separate -function that must be called before the parameters can be used. - -@defun cl-float-limits -This function makes sure that the Common Lisp floating-point parameters -like @code{cl-most-positive-float} have been initialized. Until it is -called, these parameters will be @code{nil}. -@c If this version of Emacs does not support floats, the parameters will -@c remain @code{nil}. -If the parameters have already been initialized, the function returns -immediately. - -The algorithm makes assumptions that will be valid for almost all -machines, but will fail if the machine's arithmetic is extremely -unusual, e.g., decimal. -@end defun - -Since true Common Lisp supports up to four different floating-point -precisions, it has families of constants like -@code{most-positive-single-float}, @code{most-positive-double-float}, -@code{most-positive-long-float}, and so on. Emacs has only one -floating-point precision, so this package omits the precision word -from the constants' names. - -@defvar cl-most-positive-float -This constant equals the largest value a Lisp float can hold. -For those systems whose arithmetic supports infinities, this is -the largest @emph{finite} value. For IEEE machines, the value -is approximately @code{1.79e+308}. -@end defvar - -@defvar cl-most-negative-float -This constant equals the most negative value a Lisp float can hold. -(It is assumed to be equal to @code{(- cl-most-positive-float)}.) -@end defvar - -@defvar cl-least-positive-float -This constant equals the smallest Lisp float value greater than zero. -For IEEE machines, it is about @code{4.94e-324} if denormals are -supported or @code{2.22e-308} if not. -@end defvar - -@defvar cl-least-positive-normalized-float -This constant equals the smallest @emph{normalized} Lisp float greater -than zero, i.e., the smallest value for which IEEE denormalization -will not result in a loss of precision. For IEEE machines, this -value is about @code{2.22e-308}. For machines that do not support -the concept of denormalization and gradual underflow, this constant -will always equal @code{cl-least-positive-float}. -@end defvar - -@defvar cl-least-negative-float -This constant is the negative counterpart of @code{cl-least-positive-float}. -@end defvar - -@defvar cl-least-negative-normalized-float -This constant is the negative counterpart of -@code{cl-least-positive-normalized-float}. -@end defvar - -@defvar cl-float-epsilon -This constant is the smallest positive Lisp float that can be added -to 1.0 to produce a distinct value. Adding a smaller number to 1.0 -will yield 1.0 again due to roundoff. For IEEE machines, epsilon -is about @code{2.22e-16}. -@end defvar - -@defvar cl-float-negative-epsilon -This is the smallest positive value that can be subtracted from -1.0 to produce a distinct value. For IEEE machines, it is about -@code{1.11e-16}. -@end defvar - -@node Sequences -@chapter Sequences - -@noindent -Common Lisp defines a number of functions that operate on -@dfn{sequences}, which are either lists, strings, or vectors. -Emacs Lisp includes a few of these, notably @code{elt} and -@code{length}; this package defines most of the rest. - -@menu -* Sequence Basics:: Arguments shared by all sequence functions. -* Mapping over Sequences:: @code{cl-mapcar}, @code{cl-map}, @code{cl-maplist}, etc. -* Sequence Functions:: @code{cl-subseq}, @code{cl-remove}, @code{cl-substitute}, etc. -* Searching Sequences:: @code{cl-find}, @code{cl-count}, @code{cl-search}, etc. -* Sorting Sequences:: @code{cl-sort}, @code{cl-stable-sort}, @code{cl-merge}. -@end menu - -@node Sequence Basics -@section Sequence Basics - -@noindent -Many of the sequence functions take keyword arguments; @pxref{Argument -Lists}. All keyword arguments are optional and, if specified, -may appear in any order. - -The @code{:key} argument should be passed either @code{nil}, or a -function of one argument. This key function is used as a filter -through which the elements of the sequence are seen; for example, -@code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}. -It searches for an element of the list whose @sc{car} equals -@code{x}, rather than for an element which equals @code{x} itself. -If @code{:key} is omitted or @code{nil}, the filter is effectively -the identity function. - -The @code{:test} and @code{:test-not} arguments should be either -@code{nil}, or functions of two arguments. The test function is -used to compare two sequence elements, or to compare a search value -with sequence elements. (The two values are passed to the test -function in the same order as the original sequence function -arguments from which they are derived, or, if they both come from -the same sequence, in the same order as they appear in that sequence.) -The @code{:test} argument specifies a function which must return -true (non-@code{nil}) to indicate a match; instead, you may use -@code{:test-not} to give a function which returns @emph{false} to -indicate a match. The default test function is @code{eql}. - -Many functions that take @var{item} and @code{:test} or @code{:test-not} -arguments also come in @code{-if} and @code{-if-not} varieties, -where a @var{predicate} function is passed instead of @var{item}, -and sequence elements match if the predicate returns true on them -(or false in the case of @code{-if-not}). For example: - -@example -(cl-remove 0 seq :test '=) @equiv{} (cl-remove-if 'zerop seq) -@end example - -@noindent -to remove all zeros from sequence @code{seq}. - -Some operations can work on a subsequence of the argument sequence; -these function take @code{:start} and @code{:end} arguments, which -default to zero and the length of the sequence, respectively. -Only elements between @var{start} (inclusive) and @var{end} -(exclusive) are affected by the operation. The @var{end} argument -may be passed @code{nil} to signify the length of the sequence; -otherwise, both @var{start} and @var{end} must be integers, with -@code{0 <= @var{start} <= @var{end} <= (length @var{seq})}. -If the function takes two sequence arguments, the limits are -defined by keywords @code{:start1} and @code{:end1} for the first, -and @code{:start2} and @code{:end2} for the second. - -A few functions accept a @code{:from-end} argument, which, if -non-@code{nil}, causes the operation to go from right-to-left -through the sequence instead of left-to-right, and a @code{:count} -argument, which specifies an integer maximum number of elements -to be removed or otherwise processed. - -The sequence functions make no guarantees about the order in -which the @code{:test}, @code{:test-not}, and @code{:key} functions -are called on various elements. Therefore, it is a bad idea to depend -on side effects of these functions. For example, @code{:from-end} -may cause the sequence to be scanned actually in reverse, or it may -be scanned forwards but computing a result ``as if'' it were scanned -backwards. (Some functions, like @code{cl-mapcar} and @code{cl-every}, -@emph{do} specify exactly the order in which the function is called -so side effects are perfectly acceptable in those cases.) - -Strings may contain ``text properties'' as well -as character data. Except as noted, it is undefined whether or -not text properties are preserved by sequence functions. For -example, @code{(cl-remove ?A @var{str})} may or may not preserve -the properties of the characters copied from @var{str} into the -result. - -@node Mapping over Sequences -@section Mapping over Sequences - -@noindent -These functions ``map'' the function you specify over the elements -of lists or arrays. They are all variations on the theme of the -built-in function @code{mapcar}. - -@defun cl-mapcar function seq &rest more-seqs -This function calls @var{function} on successive parallel sets of -elements from its argument sequences. Given a single @var{seq} -argument it is equivalent to @code{mapcar}; given @var{n} sequences, -it calls the function with the first elements of each of the sequences -as the @var{n} arguments to yield the first element of the result -list, then with the second elements, and so on. The mapping stops as -soon as the shortest sequence runs out. The argument sequences may -be any mixture of lists, strings, and vectors; the return sequence -is always a list. - -Common Lisp's @code{mapcar} accepts multiple arguments but works -only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence -argument. This package's @code{cl-mapcar} works as a compatible -superset of both. -@end defun - -@defun cl-map result-type function seq &rest more-seqs -This function maps @var{function} over the argument sequences, -just like @code{cl-mapcar}, but it returns a sequence of type -@var{result-type} rather than a list. @var{result-type} must -be one of the following symbols: @code{vector}, @code{string}, -@code{list} (in which case the effect is the same as for -@code{cl-mapcar}), or @code{nil} (in which case the results are -thrown away and @code{cl-map} returns @code{nil}). -@end defun - -@defun cl-maplist function list &rest more-lists -This function calls @var{function} on each of its argument lists, -then on the @sc{cdr}s of those lists, and so on, until the -shortest list runs out. The results are returned in the form -of a list. Thus, @code{cl-maplist} is like @code{cl-mapcar} except -that it passes in the list pointers themselves rather than the -@sc{car}s of the advancing pointers. -@end defun - -@defun cl-mapc function seq &rest more-seqs -This function is like @code{cl-mapcar}, except that the values returned -by @var{function} are ignored and thrown away rather than being -collected into a list. The return value of @code{cl-mapc} is @var{seq}, -the first sequence. This function is more general than the Emacs -primitive @code{mapc}. (Note that this function is called -@code{cl-mapc} even in @file{cl.el}, rather than @code{mapc*} as you -might expect.) -@c http://debbugs.gnu.org/6575 -@end defun - -@defun cl-mapl function list &rest more-lists -This function is like @code{cl-maplist}, except that it throws away -the values returned by @var{function}. -@end defun - -@defun cl-mapcan function seq &rest more-seqs -This function is like @code{cl-mapcar}, except that it concatenates -the return values (which must be lists) using @code{nconc}, -rather than simply collecting them into a list. -@end defun - -@defun cl-mapcon function list &rest more-lists -This function is like @code{cl-maplist}, except that it concatenates -the return values using @code{nconc}. -@end defun - -@defun cl-some predicate seq &rest more-seqs -This function calls @var{predicate} on each element of @var{seq} -in turn; if @var{predicate} returns a non-@code{nil} value, -@code{cl-some} returns that value, otherwise it returns @code{nil}. -Given several sequence arguments, it steps through the sequences -in parallel until the shortest one runs out, just as in -@code{cl-mapcar}. You can rely on the left-to-right order in which -the elements are visited, and on the fact that mapping stops -immediately as soon as @var{predicate} returns non-@code{nil}. -@end defun - -@defun cl-every predicate seq &rest more-seqs -This function calls @var{predicate} on each element of the sequence(s) -in turn; it returns @code{nil} as soon as @var{predicate} returns -@code{nil} for any element, or @code{t} if the predicate was true -for all elements. -@end defun - -@defun cl-notany predicate seq &rest more-seqs -This function calls @var{predicate} on each element of the sequence(s) -in turn; it returns @code{nil} as soon as @var{predicate} returns -a non-@code{nil} value for any element, or @code{t} if the predicate -was @code{nil} for all elements. -@end defun - -@defun cl-notevery predicate seq &rest more-seqs -This function calls @var{predicate} on each element of the sequence(s) -in turn; it returns a non-@code{nil} value as soon as @var{predicate} -returns @code{nil} for any element, or @code{t} if the predicate was -true for all elements. -@end defun - -@defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key} -This function combines the elements of @var{seq} using an associative -binary operation. Suppose @var{function} is @code{*} and @var{seq} is -the list @code{(2 3 4 5)}. The first two elements of the list are -combined with @code{(* 2 3) = 6}; this is combined with the next -element, @code{(* 6 4) = 24}, and that is combined with the final -element: @code{(* 24 5) = 120}. Note that the @code{*} function happens -to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as -an explicit call to @code{cl-reduce}. - -If @code{:from-end} is true, the reduction is right-associative instead -of left-associative: - -@example -(cl-reduce '- '(1 2 3 4)) - @equiv{} (- (- (- 1 2) 3) 4) @result{} -8 -(cl-reduce '- '(1 2 3 4) :from-end t) - @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2 -@end example - -If @code{:key} is specified, it is a function of one argument, which -is called on each of the sequence elements in turn. - -If @code{:initial-value} is specified, it is effectively added to the -front (or rear in the case of @code{:from-end}) of the sequence. -The @code{:key} function is @emph{not} applied to the initial value. - -If the sequence, including the initial value, has exactly one element -then that element is returned without ever calling @var{function}. -If the sequence is empty (and there is no initial value), then -@var{function} is called with no arguments to obtain the return value. -@end defun - -All of these mapping operations can be expressed conveniently in -terms of the @code{cl-loop} macro. In compiled code, @code{cl-loop} will -be faster since it generates the loop as in-line code with no -function calls. - -@node Sequence Functions -@section Sequence Functions - -@noindent -This section describes a number of Common Lisp functions for -operating on sequences. - -@defun cl-subseq sequence start &optional end -This function returns a given subsequence of the argument -@var{sequence}, which may be a list, string, or vector. -The indices @var{start} and @var{end} must be in range, and -@var{start} must be no greater than @var{end}. If @var{end} -is omitted, it defaults to the length of the sequence. The -return value is always a copy; it does not share structure -with @var{sequence}. - -As an extension to Common Lisp, @var{start} and/or @var{end} -may be negative, in which case they represent a distance back -from the end of the sequence. This is for compatibility with -Emacs's @code{substring} function. Note that @code{cl-subseq} is -the @emph{only} sequence function that allows negative -@var{start} and @var{end}. - -You can use @code{setf} on a @code{cl-subseq} form to replace a -specified range of elements with elements from another sequence. -The replacement is done as if by @code{cl-replace}, described below. -@end defun - -@defun cl-concatenate result-type &rest seqs -This function concatenates the argument sequences together to -form a result sequence of type @var{result-type}, one of the -symbols @code{vector}, @code{string}, or @code{list}. The -arguments are always copied, even in cases such as -@code{(cl-concatenate 'list '(1 2 3))} where the result is -identical to an argument. -@end defun - -@defun cl-fill seq item @t{&key :start :end} -This function fills the elements of the sequence (or the specified -part of the sequence) with the value @var{item}. -@end defun - -@defun cl-replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2} -This function copies part of @var{seq2} into part of @var{seq1}. -The sequence @var{seq1} is not stretched or resized; the amount -of data copied is simply the shorter of the source and destination -(sub)sequences. The function returns @var{seq1}. - -If @var{seq1} and @var{seq2} are @code{eq}, then the replacement -will work correctly even if the regions indicated by the start -and end arguments overlap. However, if @var{seq1} and @var{seq2} -are lists that share storage but are not @code{eq}, and the -start and end arguments specify overlapping regions, the effect -is undefined. -@end defun - -@defun cl-remove item seq @t{&key :test :test-not :key :count :start :end :from-end} -This returns a copy of @var{seq} with all elements matching -@var{item} removed. The result may share storage with or be -@code{eq} to @var{seq} in some circumstances, but the original -@var{seq} will not be modified. The @code{:test}, @code{:test-not}, -and @code{:key} arguments define the matching test that is used; -by default, elements @code{eql} to @var{item} are removed. The -@code{:count} argument specifies the maximum number of matching -elements that can be removed (only the leftmost @var{count} matches -are removed). The @code{:start} and @code{:end} arguments specify -a region in @var{seq} in which elements will be removed; elements -outside that region are not matched or removed. The @code{:from-end} -argument, if true, says that elements should be deleted from the -end of the sequence rather than the beginning (this matters only -if @var{count} was also specified). -@end defun - -@defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end} -This deletes all elements of @var{seq} that match @var{item}. -It is a destructive operation. Since Emacs Lisp does not support -stretchable strings or vectors, this is the same as @code{cl-remove} -for those sequence types. On lists, @code{cl-remove} will copy the -list if necessary to preserve the original list, whereas -@code{cl-delete} will splice out parts of the argument list. -Compare @code{append} and @code{nconc}, which are analogous -non-destructive and destructive list operations in Emacs Lisp. -@end defun - -@findex cl-remove-if -@findex cl-remove-if-not -@findex cl-delete-if -@findex cl-delete-if-not -The predicate-oriented functions @code{cl-remove-if}, @code{cl-remove-if-not}, -@code{cl-delete-if}, and @code{cl-delete-if-not} are defined similarly. - -@defun cl-remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end} -This function returns a copy of @var{seq} with duplicate elements -removed. Specifically, if two elements from the sequence match -according to the @code{:test}, @code{:test-not}, and @code{:key} -arguments, only the rightmost one is retained. If @code{:from-end} -is true, the leftmost one is retained instead. If @code{:start} or -@code{:end} is specified, only elements within that subsequence are -examined or removed. -@end defun - -@defun cl-delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end} -This function deletes duplicate elements from @var{seq}. It is -a destructive version of @code{cl-remove-duplicates}. -@end defun - -@defun cl-substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} -This function returns a copy of @var{seq}, with all elements -matching @var{old} replaced with @var{new}. The @code{:count}, -@code{:start}, @code{:end}, and @code{:from-end} arguments may be -used to limit the number of substitutions made. -@end defun - -@defun cl-nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} -This is a destructive version of @code{cl-substitute}; it performs -the substitution using @code{setcar} or @code{aset} rather than -by returning a changed copy of the sequence. -@end defun - -@findex cl-substitute-if -@findex cl-substitute-if-not -@findex cl-nsubstitute-if -@findex cl-nsubstitute-if-not -The functions @code{cl-substitute-if}, @code{cl-substitute-if-not}, -@code{cl-nsubstitute-if}, and @code{cl-nsubstitute-if-not} are defined -similarly. For these, a @var{predicate} is given in place of the -@var{old} argument. - -@node Searching Sequences -@section Searching Sequences - -@noindent -These functions search for elements or subsequences in a sequence. -(See also @code{cl-member} and @code{cl-assoc}; @pxref{Lists}.) - -@defun cl-find item seq @t{&key :test :test-not :key :start :end :from-end} -This function searches @var{seq} for an element matching @var{item}. -If it finds a match, it returns the matching element. Otherwise, -it returns @code{nil}. It returns the leftmost match, unless -@code{:from-end} is true, in which case it returns the rightmost -match. The @code{:start} and @code{:end} arguments may be used to -limit the range of elements that are searched. -@end defun - -@defun cl-position item seq @t{&key :test :test-not :key :start :end :from-end} -This function is like @code{cl-find}, except that it returns the -integer position in the sequence of the matching item rather than -the item itself. The position is relative to the start of the -sequence as a whole, even if @code{:start} is non-zero. The function -returns @code{nil} if no matching element was found. -@end defun - -@defun cl-count item seq @t{&key :test :test-not :key :start :end} -This function returns the number of elements of @var{seq} which -match @var{item}. The result is always a nonnegative integer. -@end defun - -@findex cl-find-if -@findex cl-find-if-not -@findex cl-position-if -@findex cl-position-if-not -@findex cl-count-if -@findex cl-count-if-not -The @code{cl-find-if}, @code{cl-find-if-not}, @code{cl-position-if}, -@code{cl-position-if-not}, @code{cl-count-if}, and @code{cl-count-if-not} -functions are defined similarly. - -@defun cl-mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end} -This function compares the specified parts of @var{seq1} and -@var{seq2}. If they are the same length and the corresponding -elements match (according to @code{:test}, @code{:test-not}, -and @code{:key}), the function returns @code{nil}. If there is -a mismatch, the function returns the index (relative to @var{seq1}) -of the first mismatching element. This will be the leftmost pair of -elements that do not match, or the position at which the shorter of -the two otherwise-matching sequences runs out. - -If @code{:from-end} is true, then the elements are compared from right -to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}. -If the sequences differ, then one plus the index of the rightmost -difference (relative to @var{seq1}) is returned. - -An interesting example is @code{(cl-mismatch str1 str2 :key 'upcase)}, -which compares two strings case-insensitively. -@end defun - -@defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2} -This function searches @var{seq2} for a subsequence that matches -@var{seq1} (or part of it specified by @code{:start1} and -@code{:end1}). Only matches that fall entirely within the region -defined by @code{:start2} and @code{:end2} will be considered. -The return value is the index of the leftmost element of the -leftmost match, relative to the start of @var{seq2}, or @code{nil} -if no matches were found. If @code{:from-end} is true, the -function finds the @emph{rightmost} matching subsequence. -@end defun - -@node Sorting Sequences -@section Sorting Sequences - -@defun cl-sort seq predicate @t{&key :key} -This function sorts @var{seq} into increasing order as determined -by using @var{predicate} to compare pairs of elements. @var{predicate} -should return true (non-@code{nil}) if and only if its first argument -is less than (not equal to) its second argument. For example, -@code{<} and @code{string-lessp} are suitable predicate functions -for sorting numbers and strings, respectively; @code{>} would sort -numbers into decreasing rather than increasing order. - -This function differs from Emacs's built-in @code{sort} in that it -can operate on any type of sequence, not just lists. Also, it -accepts a @code{:key} argument, which is used to preprocess data -fed to the @var{predicate} function. For example, - -@example -(setq data (cl-sort data 'string-lessp :key 'downcase)) -@end example - -@noindent -sorts @var{data}, a sequence of strings, into increasing alphabetical -order without regard to case. A @code{:key} function of @code{car} -would be useful for sorting association lists. It should only be a -simple accessor though, since it's used heavily in the current -implementation. - -The @code{cl-sort} function is destructive; it sorts lists by actually -rearranging the @sc{cdr} pointers in suitable fashion. -@end defun - -@defun cl-stable-sort seq predicate @t{&key :key} -This function sorts @var{seq} @dfn{stably}, meaning two elements -which are equal in terms of @var{predicate} are guaranteed not to -be rearranged out of their original order by the sort. - -In practice, @code{cl-sort} and @code{cl-stable-sort} are equivalent -in Emacs Lisp because the underlying @code{sort} function is -stable by default. However, this package reserves the right to -use non-stable methods for @code{cl-sort} in the future. -@end defun - -@defun cl-merge type seq1 seq2 predicate @t{&key :key} -This function merges two sequences @var{seq1} and @var{seq2} by -interleaving their elements. The result sequence, of type @var{type} -(in the sense of @code{cl-concatenate}), has length equal to the sum -of the lengths of the two input sequences. The sequences may be -modified destructively. Order of elements within @var{seq1} and -@var{seq2} is preserved in the interleaving; elements of the two -sequences are compared by @var{predicate} (in the sense of -@code{sort}) and the lesser element goes first in the result. -When elements are equal, those from @var{seq1} precede those from -@var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are -both sorted according to @var{predicate}, then the result will be -a merged sequence which is (stably) sorted according to -@var{predicate}. -@end defun - -@node Lists -@chapter Lists - -@noindent -The functions described here operate on lists. - -@menu -* List Functions:: @code{cl-caddr}, @code{cl-first}, @code{cl-list*}, etc. -* Substitution of Expressions:: @code{cl-subst}, @code{cl-sublis}, etc. -* Lists as Sets:: @code{cl-member}, @code{cl-adjoin}, @code{cl-union}, etc. -* Association Lists:: @code{cl-assoc}, @code{cl-acons}, @code{cl-pairlis}, etc. -@end menu - -@node List Functions -@section List Functions - -@noindent -This section describes a number of simple operations on lists, -i.e., chains of cons cells. - -@defun cl-caddr x -This function is equivalent to @code{(car (cdr (cdr @var{x})))}. -Likewise, this package defines all 24 @code{c@var{xxx}r} functions -where @var{xxx} is up to four @samp{a}s and/or @samp{d}s. -All of these functions are @code{setf}-able, and calls to them -are expanded inline by the byte-compiler for maximum efficiency. -@end defun - -@defun cl-first x -This function is a synonym for @code{(car @var{x})}. Likewise, -the functions @code{cl-second}, @code{cl-third}, @dots{}, through -@code{cl-tenth} return the given element of the list @var{x}. -@end defun - -@defun cl-rest x -This function is a synonym for @code{(cdr @var{x})}. -@end defun - -@defun cl-endp x -Common Lisp defines this function to act like @code{null}, but -signaling an error if @code{x} is neither a @code{nil} nor a -cons cell. This package simply defines @code{cl-endp} as a synonym -for @code{null}. -@end defun - -@defun cl-list-length x -This function returns the length of list @var{x}, exactly like -@code{(length @var{x})}, except that if @var{x} is a circular -list (where the @sc{cdr}-chain forms a loop rather than terminating -with @code{nil}), this function returns @code{nil}. (The regular -@code{length} function would get stuck if given a circular list. -See also the @code{safe-length} function.) -@end defun - -@defun cl-list* arg &rest others -This function constructs a list of its arguments. The final -argument becomes the @sc{cdr} of the last cell constructed. -Thus, @code{(cl-list* @var{a} @var{b} @var{c})} is equivalent to -@code{(cons @var{a} (cons @var{b} @var{c}))}, and -@code{(cl-list* @var{a} @var{b} nil)} is equivalent to -@code{(list @var{a} @var{b})}. -@end defun - -@defun cl-ldiff list sublist -If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to -one of the cons cells of @var{list}, then this function returns -a copy of the part of @var{list} up to but not including -@var{sublist}. For example, @code{(cl-ldiff x (cddr x))} returns -the first two elements of the list @code{x}. The result is a -copy; the original @var{list} is not modified. If @var{sublist} -is not a sublist of @var{list}, a copy of the entire @var{list} -is returned. -@end defun - -@defun cl-copy-list list -This function returns a copy of the list @var{list}. It copies -dotted lists like @code{(1 2 . 3)} correctly. -@end defun - -@defun cl-tree-equal x y @t{&key :test :test-not :key} -This function compares two trees of cons cells. If @var{x} and -@var{y} are both cons cells, their @sc{car}s and @sc{cdr}s are -compared recursively. If neither @var{x} nor @var{y} is a cons -cell, they are compared by @code{eql}, or according to the -specified test. The @code{:key} function, if specified, is -applied to the elements of both trees. @xref{Sequences}. -@end defun - -@node Substitution of Expressions -@section Substitution of Expressions - -@noindent -These functions substitute elements throughout a tree of cons -cells. (@xref{Sequence Functions}, for the @code{cl-substitute} -function, which works on just the top-level elements of a list.) - -@defun cl-subst new old tree @t{&key :test :test-not :key} -This function substitutes occurrences of @var{old} with @var{new} -in @var{tree}, a tree of cons cells. It returns a substituted -tree, which will be a copy except that it may share storage with -the argument @var{tree} in parts where no substitutions occurred. -The original @var{tree} is not modified. This function recurses -on, and compares against @var{old}, both @sc{car}s and @sc{cdr}s -of the component cons cells. If @var{old} is itself a cons cell, -then matching cells in the tree are substituted as usual without -recursively substituting in that cell. Comparisons with @var{old} -are done according to the specified test (@code{eql} by default). -The @code{:key} function is applied to the elements of the tree -but not to @var{old}. -@end defun - -@defun cl-nsubst new old tree @t{&key :test :test-not :key} -This function is like @code{cl-subst}, except that it works by -destructive modification (by @code{setcar} or @code{setcdr}) -rather than copying. -@end defun - -@findex cl-subst-if -@findex cl-subst-if-not -@findex cl-nsubst-if -@findex cl-nsubst-if-not -The @code{cl-subst-if}, @code{cl-subst-if-not}, @code{cl-nsubst-if}, and -@code{cl-nsubst-if-not} functions are defined similarly. - -@defun cl-sublis alist tree @t{&key :test :test-not :key} -This function is like @code{cl-subst}, except that it takes an -association list @var{alist} of @var{old}-@var{new} pairs. -Each element of the tree (after applying the @code{:key} -function, if any), is compared with the @sc{car}s of -@var{alist}; if it matches, it is replaced by the corresponding -@sc{cdr}. -@end defun - -@defun cl-nsublis alist tree @t{&key :test :test-not :key} -This is a destructive version of @code{cl-sublis}. -@end defun - -@node Lists as Sets -@section Lists as Sets - -@noindent -These functions perform operations on lists that represent sets -of elements. - -@defun cl-member item list @t{&key :test :test-not :key} -This function searches @var{list} for an element matching @var{item}. -If a match is found, it returns the cons cell whose @sc{car} was -the matching element. Otherwise, it returns @code{nil}. Elements -are compared by @code{eql} by default; you can use the @code{:test}, -@code{:test-not}, and @code{:key} arguments to modify this behavior. -@xref{Sequences}. - -The standard Emacs lisp function @code{member} uses @code{equal} for -comparisons; it is equivalent to @code{(cl-member @var{item} @var{list} -:test 'equal)}. With no keyword arguments, @code{cl-member} is -equivalent to @code{memq}. -@end defun - -@findex cl-member-if -@findex cl-member-if-not -The @code{cl-member-if} and @code{cl-member-if-not} functions -analogously search for elements that satisfy a given predicate. - -@defun cl-tailp sublist list -This function returns @code{t} if @var{sublist} is a sublist of -@var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to -any of its @sc{cdr}s. -@end defun - -@defun cl-adjoin item list @t{&key :test :test-not :key} -This function conses @var{item} onto the front of @var{list}, -like @code{(cons @var{item} @var{list})}, but only if @var{item} -is not already present on the list (as determined by @code{cl-member}). -If a @code{:key} argument is specified, it is applied to -@var{item} as well as to the elements of @var{list} during -the search, on the reasoning that @var{item} is ``about'' to -become part of the list. -@end defun - -@defun cl-union list1 list2 @t{&key :test :test-not :key} -This function combines two lists that represent sets of items, -returning a list that represents the union of those two sets. -The resulting list contains all items that appear in @var{list1} -or @var{list2}, and no others. If an item appears in both -@var{list1} and @var{list2} it is copied only once. If -an item is duplicated in @var{list1} or @var{list2}, it is -undefined whether or not that duplication will survive in the -result list. The order of elements in the result list is also -undefined. -@end defun - -@defun cl-nunion list1 list2 @t{&key :test :test-not :key} -This is a destructive version of @code{cl-union}; rather than copying, -it tries to reuse the storage of the argument lists if possible. -@end defun - -@defun cl-intersection list1 list2 @t{&key :test :test-not :key} -This function computes the intersection of the sets represented -by @var{list1} and @var{list2}. It returns the list of items -that appear in both @var{list1} and @var{list2}. -@end defun - -@defun cl-nintersection list1 list2 @t{&key :test :test-not :key} -This is a destructive version of @code{cl-intersection}. It -tries to reuse storage of @var{list1} rather than copying. -It does @emph{not} reuse the storage of @var{list2}. -@end defun - -@defun cl-set-difference list1 list2 @t{&key :test :test-not :key} -This function computes the ``set difference'' of @var{list1} -and @var{list2}, i.e., the set of elements that appear in -@var{list1} but @emph{not} in @var{list2}. -@end defun - -@defun cl-nset-difference list1 list2 @t{&key :test :test-not :key} -This is a destructive @code{cl-set-difference}, which will try -to reuse @var{list1} if possible. -@end defun - -@defun cl-set-exclusive-or list1 list2 @t{&key :test :test-not :key} -This function computes the ``set exclusive or'' of @var{list1} -and @var{list2}, i.e., the set of elements that appear in -exactly one of @var{list1} and @var{list2}. -@end defun - -@defun cl-nset-exclusive-or list1 list2 @t{&key :test :test-not :key} -This is a destructive @code{cl-set-exclusive-or}, which will try -to reuse @var{list1} and @var{list2} if possible. -@end defun - -@defun cl-subsetp list1 list2 @t{&key :test :test-not :key} -This function checks whether @var{list1} represents a subset -of @var{list2}, i.e., whether every element of @var{list1} -also appears in @var{list2}. -@end defun - -@node Association Lists -@section Association Lists - -@noindent -An @dfn{association list} is a list representing a mapping from -one set of values to another; any list whose elements are cons -cells is an association list. - -@defun cl-assoc item a-list @t{&key :test :test-not :key} -This function searches the association list @var{a-list} for an -element whose @sc{car} matches (in the sense of @code{:test}, -@code{:test-not}, and @code{:key}, or by comparison with @code{eql}) -a given @var{item}. It returns the matching element, if any, -otherwise @code{nil}. It ignores elements of @var{a-list} that -are not cons cells. (This corresponds to the behavior of -@code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's -@code{assoc} ignores @code{nil}s but considers any other non-cons -elements of @var{a-list} to be an error.) -@end defun - -@defun cl-rassoc item a-list @t{&key :test :test-not :key} -This function searches for an element whose @sc{cdr} matches -@var{item}. If @var{a-list} represents a mapping, this applies -the inverse of the mapping to @var{item}. -@end defun - -@findex cl-assoc-if -@findex cl-assoc-if-not -@findex cl-rassoc-if -@findex cl-rassoc-if-not -The @code{cl-assoc-if}, @code{cl-assoc-if-not}, @code{cl-rassoc-if}, -and @code{cl-rassoc-if-not} functions are defined similarly. - -Two simple functions for constructing association lists are: - -@defun cl-acons key value alist -This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}. -@end defun - -@defun cl-pairlis keys values &optional alist -This is equivalent to @code{(nconc (cl-mapcar 'cons @var{keys} @var{values}) -@var{alist})}. -@end defun - -@node Structures -@chapter Structures - -@noindent -The Common Lisp @dfn{structure} mechanism provides a general way -to define data types similar to C's @code{struct} types. A -structure is a Lisp object containing some number of @dfn{slots}, -each of which can hold any Lisp data object. Functions are -provided for accessing and setting the slots, creating or copying -structure objects, and recognizing objects of a particular structure -type. - -In true Common Lisp, each structure type is a new type distinct -from all existing Lisp types. Since the underlying Emacs Lisp -system provides no way to create new distinct types, this package -implements structures as vectors (or lists upon request) with a -special ``tag'' symbol to identify them. - -@defmac cl-defstruct name slots@dots{} -The @code{cl-defstruct} form defines a new structure type called -@var{name}, with the specified @var{slots}. (The @var{slots} -may begin with a string which documents the structure type.) -In the simplest case, @var{name} and each of the @var{slots} -are symbols. For example, - -@example -(cl-defstruct person name age sex) -@end example - -@noindent -defines a struct type called @code{person} that contains three -slots. Given a @code{person} object @var{p}, you can access those -slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, -and @code{(person-sex @var{p})}. You can also change these slots by -using @code{setf} on any of these place forms, for example: - -@example -(cl-incf (person-age birthday-boy)) -@end example - -You can create a new @code{person} by calling @code{make-person}, -which takes keyword arguments @code{:name}, @code{:age}, and -@code{:sex} to specify the initial values of these slots in the -new object. (Omitting any of these arguments leaves the corresponding -slot ``undefined'', according to the Common Lisp standard; in Emacs -Lisp, such uninitialized slots are filled with @code{nil}.) - -Given a @code{person}, @code{(copy-person @var{p})} makes a new -object of the same type whose slots are @code{eq} to those of @var{p}. - -Given any Lisp object @var{x}, @code{(person-p @var{x})} returns -true if @var{x} looks like a @code{person}, and false otherwise. (Again, -in Common Lisp this predicate would be exact; in Emacs Lisp the -best it can do is verify that @var{x} is a vector of the correct -length that starts with the correct tag symbol.) - -Accessors like @code{person-name} normally check their arguments -(effectively using @code{person-p}) and signal an error if the -argument is the wrong type. This check is affected by -@code{(optimize (safety @dots{}))} declarations. Safety level 1, -the default, uses a somewhat optimized check that will detect all -incorrect arguments, but may use an uninformative error message -(e.g., ``expected a vector'' instead of ``expected a @code{person}''). -Safety level 0 omits all checks except as provided by the underlying -@code{aref} call; safety levels 2 and 3 do rigorous checking that will -always print a descriptive error message for incorrect inputs. -@xref{Declarations}. - -@example -(setq dave (make-person :name "Dave" :sex 'male)) - @result{} [cl-struct-person "Dave" nil male] -(setq other (copy-person dave)) - @result{} [cl-struct-person "Dave" nil male] -(eq dave other) - @result{} nil -(eq (person-name dave) (person-name other)) - @result{} t -(person-p dave) - @result{} t -(person-p [1 2 3 4]) - @result{} nil -(person-p "Bogus") - @result{} nil -(person-p '[cl-struct-person counterfeit person object]) - @result{} t -@end example - -In general, @var{name} is either a name symbol or a list of a name -symbol followed by any number of @dfn{struct options}; each @var{slot} -is either a slot symbol or a list of the form @samp{(@var{slot-name} -@var{default-value} @var{slot-options}@dots{})}. The @var{default-value} -is a Lisp form that is evaluated any time an instance of the -structure type is created without specifying that slot's value. - -Common Lisp defines several slot options, but the only one -implemented in this package is @code{:read-only}. A non-@code{nil} -value for this option means the slot should not be @code{setf}-able; -the slot's value is determined when the object is created and does -not change afterward. - -@example -(cl-defstruct person - (name nil :read-only t) - age - (sex 'unknown)) -@end example - -Any slot options other than @code{:read-only} are ignored. - -For obscure historical reasons, structure options take a different -form than slot options. A structure option is either a keyword -symbol, or a list beginning with a keyword symbol possibly followed -by arguments. (By contrast, slot options are key-value pairs not -enclosed in lists.) - -@example -(cl-defstruct (person (:constructor create-person) - (:type list) - :named) - name age sex) -@end example - -The following structure options are recognized. - -@table @code -@item :conc-name -The argument is a symbol whose print name is used as the prefix for -the names of slot accessor functions. The default is the name of -the struct type followed by a hyphen. The option @code{(:conc-name p-)} -would change this prefix to @code{p-}. Specifying @code{nil} as an -argument means no prefix, so that the slot names themselves are used -to name the accessor functions. - -@item :constructor -In the simple case, this option takes one argument which is an -alternate name to use for the constructor function. The default -is @code{make-@var{name}}, e.g., @code{make-person}. The above -example changes this to @code{create-person}. Specifying @code{nil} -as an argument means that no standard constructor should be -generated at all. - -In the full form of this option, the constructor name is followed -by an arbitrary argument list. @xref{Program Structure}, for a -description of the format of Common Lisp argument lists. All -options, such as @code{&rest} and @code{&key}, are supported. -The argument names should match the slot names; each slot is -initialized from the corresponding argument. Slots whose names -do not appear in the argument list are initialized based on the -@var{default-value} in their slot descriptor. Also, @code{&optional} -and @code{&key} arguments that don't specify defaults take their -defaults from the slot descriptor. It is valid to include arguments -that don't correspond to slot names; these are useful if they are -referred to in the defaults for optional, keyword, or @code{&aux} -arguments that @emph{do} correspond to slots. - -You can specify any number of full-format @code{:constructor} -options on a structure. The default constructor is still generated -as well unless you disable it with a simple-format @code{:constructor} -option. - -@example -(cl-defstruct - (person - (:constructor nil) ; no default constructor - (:constructor new-person - (name sex &optional (age 0))) - (:constructor new-hound (&key (name "Rover") - (dog-years 0) - &aux (age (* 7 dog-years)) - (sex 'canine)))) - name age sex) -@end example - -The first constructor here takes its arguments positionally rather -than by keyword. (In official Common Lisp terminology, constructors -that work By Order of Arguments instead of by keyword are called -``BOA constructors''. No, I'm not making this up.) For example, -@code{(new-person "Jane" 'female)} generates a person whose slots -are @code{"Jane"}, 0, and @code{female}, respectively. - -The second constructor takes two keyword arguments, @code{:name}, -which initializes the @code{name} slot and defaults to @code{"Rover"}, -and @code{:dog-years}, which does not itself correspond to a slot -but which is used to initialize the @code{age} slot. The @code{sex} -slot is forced to the symbol @code{canine} with no syntax for -overriding it. - -@item :copier -The argument is an alternate name for the copier function for -this type. The default is @code{copy-@var{name}}. @code{nil} -means not to generate a copier function. (In this implementation, -all copier functions are simply synonyms for @code{copy-sequence}.) - -@item :predicate -The argument is an alternate name for the predicate that recognizes -objects of this type. The default is @code{@var{name}-p}. @code{nil} -means not to generate a predicate function. (If the @code{:type} -option is used without the @code{:named} option, no predicate is -ever generated.) - -In true Common Lisp, @code{typep} is always able to recognize a -structure object even if @code{:predicate} was used. In this -package, @code{cl-typep} simply looks for a function called -@code{@var{typename}-p}, so it will work for structure types -only if they used the default predicate name. - -@item :include -This option implements a very limited form of C++-style inheritance. -The argument is the name of another structure type previously -created with @code{cl-defstruct}. The effect is to cause the new -structure type to inherit all of the included structure's slots -(plus, of course, any new slots described by this struct's slot -descriptors). The new structure is considered a ``specialization'' -of the included one. In fact, the predicate and slot accessors -for the included type will also accept objects of the new type. - -If there are extra arguments to the @code{:include} option after -the included-structure name, these options are treated as replacement -slot descriptors for slots in the included structure, possibly with -modified default values. Borrowing an example from Steele: - -@example -(cl-defstruct person name (age 0) sex) - @result{} person -(cl-defstruct (astronaut (:include person (age 45))) - helmet-size - (favorite-beverage 'tang)) - @result{} astronaut - -(setq joe (make-person :name "Joe")) - @result{} [cl-struct-person "Joe" 0 nil] -(setq buzz (make-astronaut :name "Buzz")) - @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang] - -(list (person-p joe) (person-p buzz)) - @result{} (t t) -(list (astronaut-p joe) (astronaut-p buzz)) - @result{} (nil t) - -(person-name buzz) - @result{} "Buzz" -(astronaut-name joe) - @result{} error: "astronaut-name accessing a non-astronaut" -@end example - -Thus, if @code{astronaut} is a specialization of @code{person}, -then every @code{astronaut} is also a @code{person} (but not the -other way around). Every @code{astronaut} includes all the slots -of a @code{person}, plus extra slots that are specific to -astronauts. Operations that work on people (like @code{person-name}) -work on astronauts just like other people. - -@item :print-function -In full Common Lisp, this option allows you to specify a function -that is called to print an instance of the structure type. The -Emacs Lisp system offers no hooks into the Lisp printer which would -allow for such a feature, so this package simply ignores -@code{:print-function}. - -@item :type -The argument should be one of the symbols @code{vector} or @code{list}. -This tells which underlying Lisp data type should be used to implement -the new structure type. Vectors are used by default, but -@code{(:type list)} will cause structure objects to be stored as -lists instead. - -The vector representation for structure objects has the advantage -that all structure slots can be accessed quickly, although creating -vectors is a bit slower in Emacs Lisp. Lists are easier to create, -but take a relatively long time accessing the later slots. - -@item :named -This option, which takes no arguments, causes a characteristic ``tag'' -symbol to be stored at the front of the structure object. Using -@code{:type} without also using @code{:named} will result in a -structure type stored as plain vectors or lists with no identifying -features. - -The default, if you don't specify @code{:type} explicitly, is to -use named vectors. Therefore, @code{:named} is only useful in -conjunction with @code{:type}. - -@example -(cl-defstruct (person1) name age sex) -(cl-defstruct (person2 (:type list) :named) name age sex) -(cl-defstruct (person3 (:type list)) name age sex) - -(setq p1 (make-person1)) - @result{} [cl-struct-person1 nil nil nil] -(setq p2 (make-person2)) - @result{} (person2 nil nil nil) -(setq p3 (make-person3)) - @result{} (nil nil nil) - -(person1-p p1) - @result{} t -(person2-p p2) - @result{} t -(person3-p p3) - @result{} error: function person3-p undefined -@end example - -Since unnamed structures don't have tags, @code{cl-defstruct} is not -able to make a useful predicate for recognizing them. Also, -accessors like @code{person3-name} will be generated but they -will not be able to do any type checking. The @code{person3-name} -function, for example, will simply be a synonym for @code{car} in -this case. By contrast, @code{person2-name} is able to verify -that its argument is indeed a @code{person2} object before -proceeding. - -@item :initial-offset -The argument must be a nonnegative integer. It specifies a -number of slots to be left ``empty'' at the front of the -structure. If the structure is named, the tag appears at the -specified position in the list or vector; otherwise, the first -slot appears at that position. Earlier positions are filled -with @code{nil} by the constructors and ignored otherwise. If -the type @code{:include}s another type, then @code{:initial-offset} -specifies a number of slots to be skipped between the last slot -of the included type and the first new slot. -@end table -@end defmac - -Except as noted, the @code{cl-defstruct} facility of this package is -entirely compatible with that of Common Lisp. - -@node Assertions -@chapter Assertions and Errors - -@noindent -This section describes two macros that test @dfn{assertions}, i.e., -conditions which must be true if the program is operating correctly. -Assertions never add to the behavior of a Lisp program; they simply -make ``sanity checks'' to make sure everything is as it should be. - -If the optimization property @code{speed} has been set to 3, and -@code{safety} is less than 3, then the byte-compiler will optimize -away the following assertions. Because assertions might be optimized -away, it is a bad idea for them to include side-effects. - -@defmac cl-assert test-form [show-args string args@dots{}] -This form verifies that @var{test-form} is true (i.e., evaluates to -a non-@code{nil} value). If so, it returns @code{nil}. If the test -is not satisfied, @code{cl-assert} signals an error. - -A default error message will be supplied which includes @var{test-form}. -You can specify a different error message by including a @var{string} -argument plus optional extra arguments. Those arguments are simply -passed to @code{error} to signal the error. - -If the optional second argument @var{show-args} is @code{t} instead -of @code{nil}, then the error message (with or without @var{string}) -will also include all non-constant arguments of the top-level -@var{form}. For example: - -@example -(cl-assert (> x 10) t "x is too small: %d") -@end example - -This usage of @var{show-args} is an extension to Common Lisp. In -true Common Lisp, the second argument gives a list of @var{places} -which can be @code{setf}'d by the user before continuing from the -error. Since Emacs Lisp does not support continuable errors, it -makes no sense to specify @var{places}. -@end defmac - -@defmac cl-check-type form type [string] -This form verifies that @var{form} evaluates to a value of type -@var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type} -signals a @code{wrong-type-argument} error. The default error message -lists the erroneous value along with @var{type} and @var{form} -themselves. If @var{string} is specified, it is included in the -error message in place of @var{type}. For example: - -@example -(cl-check-type x (integer 1 *) "a positive integer") -@end example - -@xref{Type Predicates}, for a description of the type specifiers -that may be used for @var{type}. - -Note that in Common Lisp, the first argument to @code{check-type} -must be a @var{place} suitable for use by @code{setf}, because -@code{check-type} signals a continuable error that allows the -user to modify @var{place}. -@end defmac - -@node Efficiency Concerns -@appendix Efficiency Concerns - -@appendixsec Macros - -@noindent -Many of the advanced features of this package, such as @code{cl-defun}, -@code{cl-loop}, etc., are implemented as Lisp macros. In -byte-compiled code, these complex notations will be expanded into -equivalent Lisp code which is simple and efficient. For example, -the form - -@example -(cl-incf i n) -@end example - -@noindent -is expanded at compile-time to the Lisp form - -@example -(setq i (+ i n)) -@end example - -@noindent -which is the most efficient ways of doing this operation -in Lisp. Thus, there is no performance penalty for using the more -readable @code{cl-incf} form in your compiled code. - -@emph{Interpreted} code, on the other hand, must expand these macros -every time they are executed. For this reason it is strongly -recommended that code making heavy use of macros be compiled. -A loop using @code{cl-incf} a hundred times will execute considerably -faster if compiled, and will also garbage-collect less because the -macro expansion will not have to be generated, used, and thrown away a -hundred times. - -You can find out how a macro expands by using the -@code{cl-prettyexpand} function. - -@defun cl-prettyexpand form &optional full -This function takes a single Lisp form as an argument and inserts -a nicely formatted copy of it in the current buffer (which must be -in Lisp mode so that indentation works properly). It also expands -all Lisp macros that appear in the form. The easiest way to use -this function is to go to the @file{*scratch*} buffer and type, say, - -@example -(cl-prettyexpand '(cl-loop for x below 10 collect x)) -@end example - -@noindent -and type @kbd{C-x C-e} immediately after the closing parenthesis; -an expansion similar to: - -@example -(cl-block nil - (let* ((x 0) - (G1004 nil)) - (while (< x 10) - (setq G1004 (cons x G1004)) - (setq x (+ x 1))) - (nreverse G1004))) -@end example - -@noindent -will be inserted into the buffer. (The @code{cl-block} macro is -expanded differently in the interpreter and compiler, so -@code{cl-prettyexpand} just leaves it alone. The temporary -variable @code{G1004} was created by @code{cl-gensym}.) - -If the optional argument @var{full} is true, then @emph{all} -macros are expanded, including @code{cl-block}, @code{cl-eval-when}, -and compiler macros. Expansion is done as if @var{form} were -a top-level form in a file being compiled. - -@c FIXME none of these examples are still applicable. -@ignore -For example, - -@example -(cl-prettyexpand '(cl-pushnew 'x list)) - @print{} (setq list (cl-adjoin 'x list)) -(cl-prettyexpand '(cl-pushnew 'x list) t) - @print{} (setq list (if (memq 'x list) list (cons 'x list))) -(cl-prettyexpand '(caddr (cl-member 'a list)) t) - @print{} (car (cdr (cdr (memq 'a list)))) -@end example -@end ignore - -Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all -have built-in compiler macros to optimize them in common cases. -@end defun - -@appendixsec Error Checking - -@noindent -Common Lisp compliance has in general not been sacrificed for the -sake of efficiency. A few exceptions have been made for cases -where substantial gains were possible at the expense of marginal -incompatibility. - -The Common Lisp standard (as embodied in Steele's book) uses the -phrase ``it is an error if'' to indicate a situation that is not -supposed to arise in complying programs; implementations are strongly -encouraged but not required to signal an error in these situations. -This package sometimes omits such error checking in the interest of -compactness and efficiency. For example, @code{cl-do} variable -specifiers are supposed to be lists of one, two, or three forms; -extra forms are ignored by this package rather than signaling a -syntax error. The @code{cl-endp} function is simply a synonym for -@code{null} in this package. Functions taking keyword arguments -will accept an odd number of arguments, treating the trailing -keyword as if it were followed by the value @code{nil}. - -Argument lists (as processed by @code{cl-defun} and friends) -@emph{are} checked rigorously except for the minor point just -mentioned; in particular, keyword arguments are checked for -validity, and @code{&allow-other-keys} and @code{:allow-other-keys} -are fully implemented. Keyword validity checking is slightly -time consuming (though not too bad in byte-compiled code); -you can use @code{&allow-other-keys} to omit this check. Functions -defined in this package such as @code{cl-find} and @code{cl-member} -do check their keyword arguments for validity. - -@appendixsec Compiler Optimizations - -@noindent -Changing the value of @code{byte-optimize} from the default @code{t} -is highly discouraged; many of the Common -Lisp macros emit -code that can be improved by optimization. In particular, -@code{cl-block}s (whether explicit or implicit in constructs like -@code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the -byte-compiler removes @code{cl-block}s that are not actually -referenced by @code{cl-return} or @code{cl-return-from} inside the block. - -@node Common Lisp Compatibility -@appendix Common Lisp Compatibility - -@noindent -The following is a list of all known incompatibilities between this -package and Common Lisp as documented in Steele (2nd edition). - -The word @code{cl-defun} is required instead of @code{defun} in order -to use extended Common Lisp argument lists in a function. Likewise, -@code{cl-defmacro} and @code{cl-function} are versions of those forms -which understand full-featured argument lists. The @code{&whole} -keyword does not work in @code{cl-defmacro} argument lists (except -inside recursive argument lists). - -The @code{equal} predicate does not distinguish -between IEEE floating-point plus and minus zero. The @code{cl-equalp} -predicate has several differences with Common Lisp; @pxref{Predicates}. - -The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols} -with no @var{obarray} argument. In Common Lisp, this form would -iterate over all symbols in all packages. Since Emacs obarrays -are not a first-class package mechanism, there is no way for -@code{cl-do-all-symbols} to locate any but the default obarray. - -The @code{cl-loop} macro is complete except that @code{loop-finish} -and type specifiers are unimplemented. - -The multiple-value return facility treats lists as multiple -values, since Emacs Lisp cannot support multiple return values -directly. The macros will be compatible with Common Lisp if -@code{cl-values} or @code{cl-values-list} is always used to return to -a @code{cl-multiple-value-bind} or other multiple-value receiver; -if @code{cl-values} is used without @code{cl-multiple-value-@dots{}} -or vice-versa the effect will be different from Common Lisp. - -Many Common Lisp declarations are ignored, and others match -the Common Lisp standard in concept but not in detail. For -example, local @code{special} declarations, which are purely -advisory in Emacs Lisp, do not rigorously obey the scoping rules -set down in Steele's book. - -The variable @code{cl--gensym-counter} starts out with a pseudo-random -value rather than with zero. This is to cope with the fact that -generated symbols become interned when they are written to and -loaded back from a file. - -The @code{cl-defstruct} facility is compatible, except that structures -are of type @code{:type vector :named} by default rather than some -special, distinct type. Also, the @code{:type} slot option is ignored. - -The second argument of @code{cl-check-type} is treated differently. - -@node Porting Common Lisp -@appendix Porting Common Lisp - -@noindent -This package is meant to be used as an extension to Emacs Lisp, -not as an Emacs implementation of true Common Lisp. Some of the -remaining differences between Emacs Lisp and Common Lisp make it -difficult to port large Common Lisp applications to Emacs. For -one, some of the features in this package are not fully compliant -with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there -are also quite a few features that this package does not provide -at all. Here are some major omissions that you will want to watch out -for when bringing Common Lisp code into Emacs. - -@itemize @bullet -@item -Case-insensitivity. Symbols in Common Lisp are case-insensitive -by default. Some programs refer to a function or variable as -@code{foo} in one place and @code{Foo} or @code{FOO} in another. -Emacs Lisp will treat these as three distinct symbols. - -Some Common Lisp code is written entirely in upper case. While Emacs -is happy to let the program's own functions and variables use -this convention, calls to Lisp builtins like @code{if} and -@code{defun} will have to be changed to lower case. - -@item -Lexical scoping. In Common Lisp, function arguments and @code{let} -bindings apply only to references physically within their bodies (or -within macro expansions in their bodies). Traditionally, Emacs Lisp -uses @dfn{dynamic scoping} wherein a binding to a variable is visible -even inside functions called from the body. -@xref{Dynamic Binding,,,elisp,GNU Emacs Lisp Reference Manual}. -Lexical binding is available since Emacs 24.1, so be sure to set -@code{lexical-binding} to @code{t} if you need to emulate this aspect -of Common Lisp. @xref{Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}. - -Here is an example of a Common Lisp code fragment that would fail in -Emacs Lisp if @code{lexical-binding} were set to @code{nil}: - -@example -(defun map-odd-elements (func list) - (loop for x in list - for flag = t then (not flag) - collect (if flag x (funcall func x)))) - -(defun add-odd-elements (list x) - (map-odd-elements (lambda (a) (+ a x)) list)) -@end example - -@noindent -With lexical binding, the two functions' usages of @code{x} are -completely independent. With dynamic binding, the binding to @code{x} -made by @code{add-odd-elements} will have been hidden by the binding -in @code{map-odd-elements} by the time the @code{(+ a x)} function is -called. - -Internally, this package uses lexical binding so that such problems do -not occur. @xref{Obsolete Lexical Binding}, for a description of the obsolete -@code{lexical-let} form that emulates a Common Lisp-style lexical -binding when dynamic binding is in use. - -@item -Reader macros. Common Lisp includes a second type of macro that -works at the level of individual characters. For example, Common -Lisp implements the quote notation by a reader macro called @code{'}, -whereas Emacs Lisp's parser just treats quote as a special case. -Some Lisp packages use reader macros to create special syntaxes -for themselves, which the Emacs parser is incapable of reading. - -@item -Other syntactic features. Common Lisp provides a number of -notations beginning with @code{#} that the Emacs Lisp parser -won't understand. For example, @samp{#| @dots{} |#} is an -alternate comment notation, and @samp{#+lucid (foo)} tells -the parser to ignore the @code{(foo)} except in Lucid Common -Lisp. - -@item -Packages. In Common Lisp, symbols are divided into @dfn{packages}. -Symbols that are Lisp built-ins are typically stored in one package; -symbols that are vendor extensions are put in another, and each -application program would have a package for its own symbols. -Certain symbols are ``exported'' by a package and others are -internal; certain packages ``use'' or import the exported symbols -of other packages. To access symbols that would not normally be -visible due to this importing and exporting, Common Lisp provides -a syntax like @code{package:symbol} or @code{package::symbol}. - -Emacs Lisp has a single namespace for all interned symbols, and -then uses a naming convention of putting a prefix like @code{cl-} -in front of the name. Some Emacs packages adopt the Common Lisp-like -convention of using @code{cl:} or @code{cl::} as the prefix. -However, the Emacs parser does not understand colons and just -treats them as part of the symbol name. Thus, while @code{mapcar} -and @code{lisp:mapcar} may refer to the same symbol in Common -Lisp, they are totally distinct in Emacs Lisp. Common Lisp -programs that refer to a symbol by the full name sometimes -and the short name other times will not port cleanly to Emacs. - -Emacs Lisp does have a concept of ``obarrays'', which are -package-like collections of symbols, but this feature is not -strong enough to be used as a true package mechanism. - -@item -The @code{format} function is quite different between Common -Lisp and Emacs Lisp. It takes an additional ``destination'' -argument before the format string. A destination of @code{nil} -means to format to a string as in Emacs Lisp; a destination -of @code{t} means to write to the terminal (similar to -@code{message} in Emacs). Also, format control strings are -utterly different; @code{~} is used instead of @code{%} to -introduce format codes, and the set of available codes is -much richer. There are no notations like @code{\n} for -string literals; instead, @code{format} is used with the -``newline'' format code, @code{~%}. More advanced formatting -codes provide such features as paragraph filling, case -conversion, and even loops and conditionals. - -While it would have been possible to implement most of Common -Lisp @code{format} in this package (under the name @code{cl-format}, -of course), it was not deemed worthwhile. It would have required -a huge amount of code to implement even a decent subset of -@code{format}, yet the functionality it would provide over -Emacs Lisp's @code{format} would rarely be useful. - -@item -Vector constants use square brackets in Emacs Lisp, but -@code{#(a b c)} notation in Common Lisp. To further complicate -matters, Emacs has its own @code{#(} notation for -something entirely different---strings with properties. - -@item -Characters are distinct from integers in Common Lisp. The notation -for character constants is also different: @code{#\A} in Common Lisp -where Emacs Lisp uses @code{?A}. Also, @code{string=} and -@code{string-equal} are synonyms in Emacs Lisp, whereas the latter is -case-insensitive in Common Lisp. - -@item -Data types. Some Common Lisp data types do not exist in Emacs -Lisp. Rational numbers and complex numbers are not present, -nor are large integers (all integers are ``fixnums''). All -arrays are one-dimensional. There are no readtables or pathnames; -streams are a set of existing data types rather than a new data -type of their own. Hash tables, random-states, structures, and -packages (obarrays) are built from Lisp vectors or lists rather -than being distinct types. - -@item -The Common Lisp Object System (CLOS) is not implemented, -nor is the Common Lisp Condition System. However, the EIEIO package -(@pxref{Top, , Introduction, eieio, EIEIO}) does implement some -CLOS functionality. - -@item -Common Lisp features that are completely redundant with Emacs -Lisp features of a different name generally have not been -implemented. For example, Common Lisp writes @code{defconstant} -where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list} -takes its arguments in different ways in the two Lisps but does -exactly the same thing, so this package has not bothered to -implement a Common Lisp-style @code{make-list}. - -@item -A few more notable Common Lisp features not included in this -package: @code{compiler-let}, @code{tagbody}, @code{prog}, -@code{ldb/dpb}, @code{parse-integer}, @code{cerror}. - -@item -Recursion. While recursion works in Emacs Lisp just like it -does in Common Lisp, various details of the Emacs Lisp system -and compiler make recursion much less efficient than it is in -most Lisps. Some schools of thought prefer to use recursion -in Lisp over other techniques; they would sum a list of -numbers using something like - -@example -(defun sum-list (list) - (if list - (+ (car list) (sum-list (cdr list))) - 0)) -@end example - -@noindent -where a more iteratively-minded programmer might write one of -these forms: - -@example -(let ((total 0)) (dolist (x my-list) (incf total x)) total) -(loop for x in my-list sum x) -@end example - -While this would be mainly a stylistic choice in most Common Lisps, -in Emacs Lisp you should be aware that the iterative forms are -much faster than recursion. Also, Lisp programmers will want to -note that the current Emacs Lisp compiler does not optimize tail -recursion. -@end itemize - -@node Obsolete Features -@appendix Obsolete Features - -This section describes some features of the package that are obsolete -and should not be used in new code. They are either only provided by -the old @file{cl.el} entry point, not by the newer @file{cl-lib.el}; -or where versions with a @samp{cl-} prefix do exist they do not behave -in exactly the same way. - -@menu -* Obsolete Lexical Binding:: An approximation of lexical binding. -* Obsolete Macros:: Obsolete macros. -* Obsolete Setf Customization:: Obsolete ways to customize setf. -@end menu - -@node Obsolete Lexical Binding -@appendixsec Obsolete Lexical Binding - -The following macros are extensions to Common Lisp, where all bindings -are lexical unless declared otherwise. These features are likewise -obsolete since the introduction of true lexical binding in Emacs 24.1. - -@defmac lexical-let (bindings@dots{}) forms@dots{} -This form is exactly like @code{let} except that the bindings it -establishes are purely lexical. -@end defmac - -@c FIXME remove this and refer to elisp manual. -@c Maybe merge some stuff from here to there? -@noindent -Lexical bindings are similar to local variables in a language like C: -Only the code physically within the body of the @code{lexical-let} -(after macro expansion) may refer to the bound variables. - -@example -(setq a 5) -(defun foo (b) (+ a b)) -(let ((a 2)) (foo a)) - @result{} 4 -(lexical-let ((a 2)) (foo a)) - @result{} 7 -@end example - -@noindent -In this example, a regular @code{let} binding of @code{a} actually -makes a temporary change to the global variable @code{a}, so @code{foo} -is able to see the binding of @code{a} to 2. But @code{lexical-let} -actually creates a distinct local variable @code{a} for use within its -body, without any effect on the global variable of the same name. - -The most important use of lexical bindings is to create @dfn{closures}. -A closure is a function object that refers to an outside lexical -variable (@pxref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}). -For example: - -@example -(defun make-adder (n) - (lexical-let ((n n)) - (function (lambda (m) (+ n m))))) -(setq add17 (make-adder 17)) -(funcall add17 4) - @result{} 21 -@end example - -@noindent -The call @code{(make-adder 17)} returns a function object which adds -17 to its argument. If @code{let} had been used instead of -@code{lexical-let}, the function object would have referred to the -global @code{n}, which would have been bound to 17 only during the -call to @code{make-adder} itself. - -@example -(defun make-counter () - (lexical-let ((n 0)) - (cl-function (lambda (&optional (m 1)) (cl-incf n m))))) -(setq count-1 (make-counter)) -(funcall count-1 3) - @result{} 3 -(funcall count-1 14) - @result{} 17 -(setq count-2 (make-counter)) -(funcall count-2 5) - @result{} 5 -(funcall count-1 2) - @result{} 19 -(funcall count-2) - @result{} 6 -@end example - -@noindent -Here we see that each call to @code{make-counter} creates a distinct -local variable @code{n}, which serves as a private counter for the -function object that is returned. - -Closed-over lexical variables persist until the last reference to -them goes away, just like all other Lisp objects. For example, -@code{count-2} refers to a function object which refers to an -instance of the variable @code{n}; this is the only reference -to that variable, so after @code{(setq count-2 nil)} the garbage -collector would be able to delete this instance of @code{n}. -Of course, if a @code{lexical-let} does not actually create any -closures, then the lexical variables are free as soon as the -@code{lexical-let} returns. - -Many closures are used only during the extent of the bindings they -refer to; these are known as ``downward funargs'' in Lisp parlance. -When a closure is used in this way, regular Emacs Lisp dynamic -bindings suffice and will be more efficient than @code{lexical-let} -closures: - -@example -(defun add-to-list (x list) - (mapcar (lambda (y) (+ x y))) list) -(add-to-list 7 '(1 2 5)) - @result{} (8 9 12) -@end example - -@noindent -Since this lambda is only used while @code{x} is still bound, -it is not necessary to make a true closure out of it. - -You can use @code{defun} or @code{flet} inside a @code{lexical-let} -to create a named closure. If several closures are created in the -body of a single @code{lexical-let}, they all close over the same -instance of the lexical variable. - -@defmac lexical-let* (bindings@dots{}) forms@dots{} -This form is just like @code{lexical-let}, except that the bindings -are made sequentially in the manner of @code{let*}. -@end defmac - -@node Obsolete Macros -@appendixsec Obsolete Macros - -The following macros are obsolete, and are replaced by versions with -a @samp{cl-} prefix that do not behave in exactly the same way. -Consequently, the @file{cl.el} versions are not simply aliases to the -@file{cl-lib.el} versions. - -@defmac flet (bindings@dots{}) forms@dots{} -This macro is replaced by @code{cl-flet} (@pxref{Function Bindings}), -which behaves the same way as Common Lisp's @code{flet}. -This @code{flet} takes the same arguments as @code{cl-flet}, but does -not behave in precisely the same way. - -While @code{flet} in Common Lisp establishes a lexical function -binding, this @code{flet} makes a dynamic binding (it dates from a -time before Emacs had lexical binding). The result is -that @code{flet} affects indirect calls to a function as well as calls -directly inside the @code{flet} form itself. - -This will even work on Emacs primitives, although note that some calls -to primitive functions internal to Emacs are made without going -through the symbol's function cell, and so will not be affected by -@code{flet}. For example, - -@example -(flet ((message (&rest args) (push args saved-msgs))) - (do-something)) -@end example - -This code attempts to replace the built-in function @code{message} -with a function that simply saves the messages in a list rather -than displaying them. The original definition of @code{message} -will be restored after @code{do-something} exits. This code will -work fine on messages generated by other Lisp code, but messages -generated directly inside Emacs will not be caught since they make -direct C-language calls to the message routines rather than going -through the Lisp @code{message} function. - -For those cases where the dynamic scoping of @code{flet} is desired, -@code{cl-flet} is clearly not a substitute. The most direct replacement would -be instead to use @code{cl-letf} to temporarily rebind @code{(symbol-function -'@var{fun})}. But in most cases, a better substitute is to use an advice, such -as: - -@example -(defvar my-fun-advice-enable nil) -(add-advice '@var{fun} :around - (lambda (orig &rest args) - (if my-fun-advice-enable (do-something) - (apply orig args)))) -@end example - -so that you can then replace the @code{flet} with a simple dynamically scoped -binding of @code{my-fun-advice-enable}. - -@c Bug#411. -Note that many primitives (e.g., @code{+}) have special byte-compile handling. -Attempts to redefine such functions using @code{flet}, @code{cl-letf}, or an -advice will fail when byte-compiled. -@c Or cl-flet. -@c In such cases, use @code{labels} instead. -@end defmac - -@defmac labels (bindings@dots{}) forms@dots{} -This macro is replaced by @code{cl-labels} (@pxref{Function Bindings}), -which behaves the same way as Common Lisp's @code{labels}. -This @code{labels} takes the same arguments as @code{cl-labels}, but -does not behave in precisely the same way. - -This version of @code{labels} uses the obsolete @code{lexical-let} -form (@pxref{Obsolete Lexical Binding}), rather than the true -lexical binding that @code{cl-labels} uses. -@end defmac - -@node Obsolete Setf Customization -@appendixsec Obsolete Ways to Customize Setf - -Common Lisp defines three macros, @code{define-modify-macro}, -@code{defsetf}, and @code{define-setf-method}, that allow the -user to extend generalized variables in various ways. -In Emacs, these are obsolete, replaced by various features of -@file{gv.el} in Emacs 24.3. -@xref{Adding Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}. - - -@defmac define-modify-macro name arglist function [doc-string] -This macro defines a ``read-modify-write'' macro similar to -@code{cl-incf} and @code{cl-decf}. You can replace this macro -with @code{gv-letplace}. - -The macro @var{name} is defined to take a @var{place} argument -followed by additional arguments described by @var{arglist}. The call - -@example -(@var{name} @var{place} @var{args}@dots{}) -@end example - -@noindent -will be expanded to - -@example -(cl-callf @var{func} @var{place} @var{args}@dots{}) -@end example - -@noindent -which in turn is roughly equivalent to - -@example -(setf @var{place} (@var{func} @var{place} @var{args}@dots{})) -@end example - -For example: - -@example -(define-modify-macro incf (&optional (n 1)) +) -(define-modify-macro concatf (&rest args) concat) -@end example - -Note that @code{&key} is not allowed in @var{arglist}, but -@code{&rest} is sufficient to pass keywords on to the function. - -Most of the modify macros defined by Common Lisp do not exactly -follow the pattern of @code{define-modify-macro}. For example, -@code{push} takes its arguments in the wrong order, and @code{pop} -is completely irregular. - -The above @code{incf} example could be written using -@code{gv-letplace} as: -@example -(defmacro incf (place &optional n) - (gv-letplace (getter setter) place - (macroexp-let2 nil v (or n 1) - (funcall setter `(+ ,v ,getter))))) -@end example -@ignore -(defmacro concatf (place &rest args) - (gv-letplace (getter setter) place - (macroexp-let2 nil v (mapconcat 'identity args "") - (funcall setter `(concat ,getter ,v))))) -@end ignore -@end defmac - -@defmac defsetf access-fn update-fn -This is the simpler of two @code{defsetf} forms, and is -replaced by @code{gv-define-simple-setter}. - -With @var{access-fn} the name of a function that accesses a place, -this declares @var{update-fn} to be the corresponding store function. -From now on, - -@example -(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value}) -@end example - -@noindent -will be expanded to - -@example -(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value}) -@end example - -@noindent -The @var{update-fn} is required to be either a true function, or -a macro that evaluates its arguments in a function-like way. Also, -the @var{update-fn} is expected to return @var{value} as its result. -Otherwise, the above expansion would not obey the rules for the way -@code{setf} is supposed to behave. - -As a special (non-Common-Lisp) extension, a third argument of @code{t} -to @code{defsetf} says that the return value of @code{update-fn} is -not suitable, so that the above @code{setf} should be expanded to -something more like - -@example -(let ((temp @var{value})) - (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp) - temp) -@end example - -Some examples are: - -@example -(defsetf car setcar) -(defsetf buffer-name rename-buffer t) -@end example - -These translate directly to @code{gv-define-simple-setter}: - -@example -(gv-define-simple-setter car setcar) -(gv-define-simple-setter buffer-name rename-buffer t) -@end example -@end defmac - -@defmac defsetf access-fn arglist (store-var) forms@dots{} -This is the second, more complex, form of @code{defsetf}. -It can be replaced by @code{gv-define-setter}. - -This form of @code{defsetf} is rather like @code{defmacro} except for -the additional @var{store-var} argument. The @var{forms} should -return a Lisp form that stores the value of @var{store-var} into the -generalized variable formed by a call to @var{access-fn} with -arguments described by @var{arglist}. The @var{forms} may begin with -a string which documents the @code{setf} method (analogous to the doc -string that appears at the front of a function). - -For example, the simple form of @code{defsetf} is shorthand for - -@example -(defsetf @var{access-fn} (&rest args) (store) - (append '(@var{update-fn}) args (list store))) -@end example - -The Lisp form that is returned can access the arguments from -@var{arglist} and @var{store-var} in an unrestricted fashion; -macros like @code{cl-incf} that invoke this -setf-method will insert temporary variables as needed to make -sure the apparent order of evaluation is preserved. - -Another standard example: - -@example -(defsetf nth (n x) (store) - `(setcar (nthcdr ,n ,x) ,store)) -@end example - -You could write this using @code{gv-define-setter} as: - -@example -(gv-define-setter nth (store n x) - `(setcar (nthcdr ,n ,x) ,store)) -@end example -@end defmac - -@defmac define-setf-method access-fn arglist forms@dots{} -This is the most general way to create new place forms. You can -replace this by @code{gv-define-setter} or @code{gv-define-expander}. - -When a @code{setf} to @var{access-fn} with arguments described by -@var{arglist} is expanded, the @var{forms} are evaluated and must -return a list of five items: - -@enumerate -@item -A list of @dfn{temporary variables}. - -@item -A list of @dfn{value forms} corresponding to the temporary variables -above. The temporary variables will be bound to these value forms -as the first step of any operation on the generalized variable. - -@item -A list of exactly one @dfn{store variable} (generally obtained -from a call to @code{gensym}). - -@item -A Lisp form that stores the contents of the store variable into -the generalized variable, assuming the temporaries have been -bound as described above. - -@item -A Lisp form that accesses the contents of the generalized variable, -assuming the temporaries have been bound. -@end enumerate - -This is exactly like the Common Lisp macro of the same name, -except that the method returns a list of five values rather -than the five values themselves, since Emacs Lisp does not -support Common Lisp's notion of multiple return values. -(Note that the @code{setf} implementation provided by @file{gv.el} -does not use this five item format. Its use here is only for -backwards compatibility.) - -Once again, the @var{forms} may begin with a documentation string. - -A setf-method should be maximally conservative with regard to -temporary variables. In the setf-methods generated by -@code{defsetf}, the second return value is simply the list of -arguments in the place form, and the first return value is a -list of a corresponding number of temporary variables generated -@c FIXME I don't think this is true anymore. -by @code{cl-gensym}. Macros like @code{cl-incf} that -use this setf-method will optimize away most temporaries that -turn out to be unnecessary, so there is little reason for the -setf-method itself to optimize. -@end defmac - -@c Removed in Emacs 24.3, not possible to make a compatible replacement. -@ignore -@defun get-setf-method place &optional env -This function returns the setf-method for @var{place}, by -invoking the definition previously recorded by @code{defsetf} -or @code{define-setf-method}. The result is a list of five -values as described above. You can use this function to build -your own @code{cl-incf}-like modify macros. - -The argument @var{env} specifies the ``environment'' to be -passed on to @code{macroexpand} if @code{get-setf-method} should -need to expand a macro in @var{place}. It should come from -an @code{&environment} argument to the macro or setf-method -that called @code{get-setf-method}. -@end defun -@end ignore - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Function Index - -@printindex fn - -@node Variable Index -@unnumbered Variable Index - -@printindex vr - -@bye diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi deleted file mode 100644 index 4c63ecddb7d..00000000000 --- a/doc/misc/dbus.texi +++ /dev/null @@ -1,2041 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/dbus -@c %**start of header -@settitle Using of D-Bus -@documentencoding UTF-8 -@c @setchapternewpage odd -@c %**end of header - -@syncodeindex vr cp -@syncodeindex fn cp - -@copying -Copyright @copyright{} 2007--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs lisp libraries -@direntry -* D-Bus: (dbus). Using D-Bus in Emacs. -@end direntry - -@titlepage -@title Using D-Bus in Emacs -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - - -@contents - - -@node Top, Overview, (dir), (dir) -@top D-Bus integration in Emacs - -This manual documents an API for usage of D-Bus in Emacs. D-Bus is a -message bus system, a simple way for applications to talk to one -another. An overview of D-Bus can be found at -@uref{http://dbus.freedesktop.org/}. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: An overview of D-Bus. -* Inspection:: Inspection of D-Bus services. -* Type Conversion:: Mapping Lisp types and D-Bus types. -* Synchronous Methods:: Calling methods in a blocking way. -* Asynchronous Methods:: Calling methods non-blocking. -* Receiving Method Calls:: Offering own methods. -* Signals:: Sending and receiving signals. -* Alternative Buses:: Alternative buses and environments. -* Errors and Events:: Errors and events. -* Index:: Index including concepts, functions, variables. - -* GNU Free Documentation License:: The license for this documentation. -@end menu - - -@node Overview -@chapter An overview of D-Bus -@cindex overview - -D-Bus is an inter-process communication mechanism for applications -residing on the same host. The communication is based on -@dfn{messages}. Data in the messages is carried in a structured way, -it is not just a byte stream. - -The communication is connection oriented to two kinds of message -buses: a so called @dfn{system bus}, and a @dfn{session bus}. On a -given machine, there is always one single system bus for miscellaneous -system-wide communication, like changing of hardware configuration. -On the other hand, the session bus is always related to a single -user's session. - -Every client application, which is connected to a bus, registers under -a @dfn{unique name} at the bus. This name is used for identifying the -client application. Such a unique name starts always with a colon, -and looks like @samp{:1.42}. - -Additionally, a client application can register itself to a so called -@dfn{known name}, which is a series of identifiers separated by dots, -as in @samp{org.gnu.Emacs}. If several applications register to the -same known name, these registrations are queued, and only the first -application which has registered for the known name is reachable via -this name. If this application disconnects from the bus, the next -queued unique name becomes the owner of this known name. - -An application can install one or several objects under its name. -Such objects are identified by an @dfn{object path}, which looks -similar to paths in a filesystem. An example of such an object path -could be @samp{/org/gnu/Emacs/}. - -Applications might send a request to an object, that means sending a -message with some data as input parameters, and receiving a message -from that object with the result of this message, the output -parameters. Such a request is called @dfn{method} in D-Bus. - -The other form of communication are @dfn{signals}. The underlying -message is emitted from an object and will be received by all other -applications which have registered for such a signal. - -All methods and signals an object supports are called @dfn{interface} -of the object. Interfaces are specified under a hierarchical name in -D-Bus; an object can support several interfaces. Such an interface -name could be @samp{org.gnu.Emacs.TextEditor} or -@samp{org.gnu.Emacs.FileManager}. - - -@node Inspection -@chapter Inspection of D-Bus services. -@cindex inspection - -@menu -* Version:: Determining the D-Bus version. -* Bus names:: Discovering D-Bus names. -* Introspection:: Knowing the details of D-Bus services. -* Nodes and Interfaces:: Detecting object paths and interfaces. -* Methods and Signal:: Applying the functionality. -* Properties and Annotations:: What else to know about interfaces. -* Arguments and Signatures:: The final details. -@end menu - - -@node Version -@section D-Bus version. - -D-Bus has evolved over the years. New features have been added with -new D-Bus versions. There are two variables, which allow to determine -the used D-Bus version. - -@defvar dbus-compiled-version -This variable, a string, determines the version of D-Bus Emacs is -compiled against. If it cannot be determined the value is @code{nil}. -@end defvar - -@defvar dbus-runtime-version -The other D-Bus version to be checked is the version of D-Bus Emacs -runs with. This string can be different from @code{dbus-compiled-version}. -It is also @code{nil}, if it cannot be determined at runtime. -@end defvar - - -@node Bus names -@section Bus names. - -There are several basic functions which inspect the buses for -registered names. Internally they use the basic interface -@samp{org.freedesktop.DBus}, which is supported by all objects of a bus. - -@defun dbus-list-activatable-names &optional bus -This function returns the D-Bus service names, which can be activated -for @var{bus}. It must be either the symbol @code{:system} (the -default) or the symbol @code{:session}. An activatable service is -described in a service registration file. Under GNU/Linux, such files -are located at @file{/usr/share/dbus-1/system-services/} (for the -@code{:system} bus) or @file{/usr/share/dbus-1/services/}. An -activatable service is not necessarily registered at @var{bus} at already. - -The result is a list of strings, which is @code{nil} when there are no -activatable service names at all. Example: - -@lisp -;; Check, whether the document viewer can be accessed via D-Bus. -(member "org.gnome.evince.Daemon" - (dbus-list-activatable-names :session)) -@end lisp -@end defun - -@defun dbus-list-names bus -All service names, which are registered at D-Bus @var{bus}, are -returned. The result is a list of strings, which is @code{nil} when -there are no registered service names at all. Well known names are -strings like @samp{org.freedesktop.DBus}. Names starting with -@samp{:} are unique names for services. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. -@end defun - -@defun dbus-list-known-names bus -Retrieves all registered services which correspond to a known name in @var{bus}. -A service has a known name if it doesn't start with @samp{:}. The -result is a list of strings, which is @code{nil} when there are no -known names at all. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. -@end defun - -@defun dbus-list-queued-owners bus service -For a given service, registered at D-Bus @var{bus} under the name -@var{service}, all queued unique names are returned. The result is a -list of strings, or @code{nil} when there are no queued names for -@var{service} at all. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a known service name as -string. -@end defun - -@defun dbus-get-name-owner bus service -For a given service, registered at D-Bus @var{bus} under the name -@var{service}, the unique name of the name owner is returned. The -result is a string, or @code{nil} when there exist no name owner of -@var{service}. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a known service name as -string. -@end defun - -@defun dbus-ping bus service &optional timeout -Check whether the service name @var{service} is registered at D-Bus -@var{bus}. @var{service} might not have been started yet, it is -autostarted if possible. The result is either @code{t} or @code{nil}. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a string. @var{timeout}, a -nonnegative integer, specifies the maximum number of milliseconds -@code{dbus-ping} must return. The default value is 25,000. Example: - -@lisp -(message - "%s screensaver on board." - (cond - ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome") - ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE") - (t "No"))) -@end lisp - -If it shall be checked whether @var{service} is already running -without autostarting it, one shall apply - -@lisp -(member service (dbus-list-known-names bus)) -@end lisp -@end defun - -@defun dbus-get-unique-name bus -The unique name, under which Emacs is registered at D-Bus @var{bus}, -is returned as string. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. -@end defun - - -@node Introspection -@section Knowing the details of D-Bus services. - -D-Bus services publish their interfaces. This can be retrieved and -analyzed during runtime, in order to understand the used -implementation. - -The resulting introspection data are in XML format. The root -introspection element is always a @code{node} element. It might have -a @code{name} attribute, which denotes the (absolute) object path an -interface is introspected. - -The root @code{node} element may have @code{node} and @code{interface} -children. A child @code{node} element must have a @code{name} -attribute, this case it is the relative object path to the root -@code{node} element. - -An @code{interface} element has just one attribute, @code{name}, which -is the full name of that interface. The default interface -@samp{org.freedesktop.DBus.Introspectable} is always present. Example: - -@example - - - @dots{} - - - @dots{} - - - @dots{} - - - @dots{} - - - - - - -@end example - -Children of an @code{interface} element can be @code{method}, -@code{signal} and @code{property} elements. A @code{method} element -stands for a D-Bus method of the surrounding interface. The element -itself has a @code{name} attribute, showing the method name. Children -elements @code{arg} stand for the arguments of a method. Example: - -@example - - - - - - - - - - - - - -@end example - -@code{arg} elements can have the attributes @code{name}, @code{type} -and @code{direction}. The @code{name} attribute is optional. The -@code{type} attribute stands for the @dfn{signature} of the argument -in D-Bus. For a discussion of D-Bus types and their Lisp -representation see @ref{Type Conversion}.@footnote{D-Bus signatures -are explained in the D-Bus specification -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.} -The @code{direction} attribute of an @code{arg} element can be only -@samp{in} or @samp{out}; in case it is omitted, it defaults to -@samp{in}. - -A @code{signal} element of an @code{interface} has a similar -structure. The @code{direction} attribute of an @code{arg} child -element can be only @samp{out} here; which is also the default value. -Example: - -@example - - - - -@end example - -A @code{property} element has no @code{arg} child -element. It just has the attributes @code{name}, @code{type} and -@code{access}, which are all mandatory. The @code{access} attribute -allows the values @samp{readwrite}, @samp{read}, and @samp{write}. -Example: - -@example - -@end example - -@code{annotation} elements can be children of @code{interface}, -@code{method}, @code{signal}, and @code{property} elements. Unlike -properties, which can change their values during lifetime of a D-Bus -object, annotations are static. Often they are used for code -generators of D-Bus language bindings. Example: - -@example - -@end example - -Annotations have just @code{name} and @code{value} attributes, both -must be strings. - -@defun dbus-introspect bus service path -This function returns all interfaces and sub-nodes of @var{service}, -registered at object path @var{path} at bus @var{bus}. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a known service name, and -@var{path} must be a valid object path. The last two parameters are -strings. The result, the introspection data, is a string in XML -format. Example: - -@lisp -(dbus-introspect - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer") - -@result{} " - - - - - - @dots{} - - - - - - @dots{} - " -@end lisp - -This example informs us, that the service @samp{org.freedesktop.Hal} -at object path @samp{/org/freedesktop/Hal/devices/computer} offers the -interface @samp{org.freedesktop.Hal.Device} (and 2 other interfaces -not documented here). This interface contains the method -@samp{GetAllProperties}, which needs no input parameters, but returns -as output parameter an array of dictionary entries (key-value pairs). -Every dictionary entry has a string as key, and a variant as value. - -The interface offers also a signal, which returns 2 parameters: an -integer, and an array consisting of elements which are a struct of a -string and 2 boolean values.@footnote{ The interfaces of the service -@samp{org.freedesktop.Hal} are described in -@c Previous link is gone. Since HAL is now obsolete, this URL -@c (unchanged in ~ 4 years) feels like it might go too... -@uref{http://people.freedesktop.org/~dkukawka/hal-spec-git/hal-spec.html#interfaces, -the HAL specification}.} -@end defun - -@defun dbus-introspect-xml bus service path -This function has the same intention as function -@code{dbus-introspect}. The returned value is a parsed XML tree, -which can be used for further analysis. Example: - -@lisp -(dbus-introspect-xml - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main") - -@result{} (node ((name . "/org/freedesktop/xesam/searcher/main")) - (interface ((name . "org.freedesktop.xesam.Search")) - (method ((name . "GetHitData")) - (arg ((name . "search") (type . "s") (direction . "in"))) - (arg ((name . "hit_ids") (type . "au") (direction . "in"))) - (arg ((name . "fields") (type . "as") (direction . "in"))) - (arg ((name . "hit_data") (type . "aav") (direction . "out"))) - ) - @dots{} - (signal ((name . "HitsAdded")) - (arg ((name . "search") (type . "s"))) - (arg ((name . "count") (type . "u"))) - ) - ) - @dots{} - ) -@end lisp -@end defun - -@defun dbus-introspect-get-attribute object attribute -It returns the @var{attribute} value of a D-Bus introspection -@var{object}. @var{object} can be every subtree of a parsed XML tree -as retrieved with @code{dbus-introspect-xml}. @var{attribute} must be -a string according to the attribute names in the D-Bus specification. -Example: - -@lisp -(dbus-introspect-get-attribute - (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends" - "/org/freedesktop/SystemToolsBackends/UsersConfig") - "name") - -@result{} "/org/freedesktop/SystemToolsBackends/UsersConfig" -@end lisp - -If @var{object} has no @var{attribute}, the function returns -@code{nil}. -@end defun - - -@node Nodes and Interfaces -@section Detecting object paths and interfaces. - -The first elements, to be introspected for a D-Bus object, are further -object paths and interfaces. - -@defun dbus-introspect-get-node-names bus service path -All node names of @var{service} in D-Bus @var{bus} at object path -@var{path} are returned as list of strings. Example: - -@lisp -(dbus-introspect-get-node-names - :session "org.gnome.seahorse" "/org/gnome/seahorse") - -@result{} ("crypto" "keys") -@end lisp - -The node names stand for further object paths of the D-Bus -@var{service}, relative to @var{path}. In the example, -@samp{/org/gnome/seahorse/crypto} and @samp{/org/gnome/seahorse/keys} -are also object paths of the D-Bus service @samp{org.gnome.seahorse}. -@end defun - -@defun dbus-introspect-get-all-nodes bus service path -This function returns all node names of @var{service} in D-Bus -@var{bus} at object path @var{path}. It returns a list of strings -with all object paths of @var{service}, starting at @var{path}. -Example: - -@lisp -(dbus-introspect-get-all-nodes :session "org.gnome.seahorse" "/") - -@result{} ("/" "/org" "/org/gnome" "/org/gnome/seahorse" - "/org/gnome/seahorse/crypto" - "/org/gnome/seahorse/keys" - "/org/gnome/seahorse/keys/openpgp" - "/org/gnome/seahorse/keys/openpgp/local" - "/org/gnome/seahorse/keys/openssh" - "/org/gnome/seahorse/keys/openssh/local") -@end lisp -@end defun - -@defun dbus-introspect-get-interface-names bus service path -There will be returned a list strings of all interface names of -@var{service} in D-Bus @var{bus} at object path @var{path}. This list -will contain the default interface @samp{org.freedesktop.DBus.Introspectable}. - -Another default interface is @samp{org.freedesktop.DBus.Properties}. -If present, @code{interface} elements can also have @code{property} -children. Example: - -@lisp -(dbus-introspect-get-interface-names - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer") - -@result{} ("org.freedesktop.DBus.Introspectable" - "org.freedesktop.Hal.Device" - "org.freedesktop.Hal.Device.SystemPowerManagement" - "org.freedesktop.Hal.Device.CPUFreq") -@end lisp -@end defun - -@defun dbus-introspect-get-interface bus service path interface -Return @var{interface} of @var{service} in D-Bus @var{bus} at object -path @var{path}. The return value is an XML element. @var{interface} -must be a string, element of the list returned by -@code{dbus-introspect-get-interface-names}. Example: - -@lisp -(dbus-introspect-get-interface - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search") - -@result{} (interface ((name . "org.freedesktop.xesam.Search")) - (method ((name . "GetHitData")) - (arg ((name . "search") (type . "s") (direction . "in"))) - (arg ((name . "hit_ids") (type . "au") (direction . "in"))) - (arg ((name . "fields") (type . "as") (direction . "in"))) - (arg ((name . "hit_data") (type . "aav") (direction . "out"))) - ) - @dots{} - (signal ((name . "HitsAdded")) - (arg ((name . "search") (type . "s"))) - (arg ((name . "count") (type . "u"))) - ) - ) -@end lisp -@end defun - -@noindent -With these functions, it is possible to retrieve all introspection -data from a running system: - -@lisp -(with-current-buffer (switch-to-buffer "*introspect*") - (erase-buffer) - (dolist (service (dbus-list-known-names :session)) - (dolist (path (dbus-introspect-get-all-nodes :session service "/")) - ;; We want to introspect only elements, which have more than - ;; the default interface "org.freedesktop.DBus.Introspectable". - (when (delete - "org.freedesktop.DBus.Introspectable" - (dbus-introspect-get-interface-names :session service path)) - (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path) - (dbus-introspect :session service path)) - (redisplay t))))) -@end lisp - - -@node Methods and Signal -@section Applying the functionality. - -Methods and signals are the communication means to D-Bus. The -following functions return their specifications. - -@defun dbus-introspect-get-method-names bus service path interface -Return a list of strings of all method names of @var{interface} of -@var{service} in D-Bus @var{bus} at object path @var{path}. Example: - -@lisp -(dbus-introspect-get-method-names - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search") - -@result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession" - "CloseSession" "GetHitData" "SetProperty" "NewSearch" - "GetProperty" "CloseSearch") -@end lisp -@end defun - -@defun dbus-introspect-get-method bus service path interface method -This function returns @var{method} of @var{interface} as XML element. -It must be located at @var{service} in D-Bus @var{bus} at object path -@var{path}. @var{method} must be a string, element of the list -returned by @code{dbus-introspect-get-method-names}. Example: - -@lisp -(dbus-introspect-get-method - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData") - -@result{} (method ((name . "GetHitData")) - (arg ((name . "search") (type . "s") (direction . "in"))) - (arg ((name . "hit_ids") (type . "au") (direction . "in"))) - (arg ((name . "fields") (type . "as") (direction . "in"))) - (arg ((name . "hit_data") (type . "aav") (direction . "out"))) - ) -@end lisp -@end defun - -@defun dbus-introspect-get-signal-names bus service path interface -Return a list of strings of all signal names of @var{interface} of -@var{service} in D-Bus @var{bus} at object path @var{path}. Example: - -@lisp -(dbus-introspect-get-signal-names - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search") - -@result{} ("StateChanged" "SearchDone" "HitsModified" - "HitsRemoved" "HitsAdded") -@end lisp -@end defun - -@defun dbus-introspect-get-signal bus service path interface signal -This function returns @var{signal} of @var{interface} as XML element. -It must be located at @var{service} in D-Bus @var{bus} at object path -@var{path}. @var{signal} must be a string, element of the list -returned by @code{dbus-introspect-get-signal-names}. Example: - -@lisp -(dbus-introspect-get-signal - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "HitsAdded") - -@result{} (signal ((name . "HitsAdded")) - (arg ((name . "search") (type . "s"))) - (arg ((name . "count") (type . "u"))) - ) -@end lisp -@end defun - - -@node Properties and Annotations -@section What else to know about interfaces. - -Interfaces can have properties. These can be exposed via the -@samp{org.freedesktop.DBus.Properties} interface@footnote{See -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}. -That is, properties can be retrieved and changed during lifetime of an -element. - -A generalized interface is -@samp{org.freedesktop.DBus.Objectmanager}@footnote{See -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager}}, -which returns objects, their interfaces and properties for a given -service in just one call. - -Annotations, on the other hand, are static values for an element. -Often, they are used to instruct generators, how to generate code from -the interface for a given language binding. - -@defun dbus-introspect-get-property-names bus service path interface -Return a list of strings with all property names of @var{interface} of -@var{service} in D-Bus @var{bus} at object path @var{path}. Example: - -@lisp -(dbus-introspect-get-property-names - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client") - -@result{} ("Status") -@end lisp - -If an interface declares properties, the corresponding element supports -also the @samp{org.freedesktop.DBus.Properties} interface. -@end defun - -@defun dbus-introspect-get-property bus service path interface property -This function returns @var{property} of @var{interface} as XML element. -It must be located at @var{service} in D-Bus @var{bus} at object path -@var{path}. @var{property} must be a string, element of the list -returned by @code{dbus-introspect-get-property-names}. - -A @var{property} value can be retrieved by the function -@code{dbus-introspect-get-attribute}. Example: - -@lisp -(dbus-introspect-get-property - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client" "Status") - -@result{} (property ((access . "read") (type . "u") (name . "Status"))) - -(dbus-introspect-get-attribute - (dbus-introspect-get-property - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client" "Status") - "access") - -@result{} "read" -@end lisp -@end defun - -@defun dbus-get-property bus service path interface property -This function returns the value of @var{property} of @var{interface}. -It will be checked at @var{bus}, @var{service}, @var{path}. The -result can be any valid D-Bus value, or @code{nil} if there is no -@var{property}. Example: - -@lisp -(dbus-get-property - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client" "Status") - -@result{} 4 -@end lisp -@end defun - -@defun dbus-set-property bus service path interface property value -Set value of @var{property} of @var{interface} to @var{value}. It -will be checked at @var{bus}, @var{service}, @var{path}. When the -value has been set successful, the result is @var{value}. Otherwise, -@code{nil} is returned. Example: - -@lisp -(dbus-set-property - :session "org.kde.kaccess" "/MainApplication" - "com.trolltech.Qt.QApplication" "doubleClickInterval" 500) - -@result{} 500 -@end lisp -@end defun - -@defun dbus-get-all-properties bus service path interface -This function returns all properties of @var{interface}. It will be -checked at @var{bus}, @var{service}, @var{path}. The result is a list -of cons. Every cons contains the name of the property, and its value. -If there are no properties, @code{nil} is returned. Example: - -@lisp -(dbus-get-all-properties - :session "org.kde.kaccess" "/MainApplication" - "com.trolltech.Qt.QApplication") - -@result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500) - ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3) - ("globalStrut" 0 0) ("startDragTime" . 500) - ("startDragDistance" . 4) ("quitOnLastWindowClosed" . t) - ("styleSheet" . "")) -@end lisp -@end defun - -@defun dbus-get-all-managed-objects bus service path -This function returns all objects at @var{bus}, @var{service}, -@var{path}, and the children of @var{path}. The result is a list of -objects. Every object is a cons of an existing path name, and the -list of available interface objects. An interface object is another -cons, which car is the interface name, and the cdr is the list of -properties as returned by @code{dbus-get-all-properties} for that path -and interface. Example: - -@lisp -(dbus-get-all-managed-objects - :session "org.gnome.SettingsDaemon" "/") - -@result{} (("/org/gnome/SettingsDaemon/MediaKeys" - ("org.gnome.SettingsDaemon.MediaKeys") - ("org.freedesktop.DBus.Peer") - ("org.freedesktop.DBus.Introspectable") - ("org.freedesktop.DBus.Properties") - ("org.freedesktop.DBus.ObjectManager")) - ("/org/gnome/SettingsDaemon/Power" - ("org.gnome.SettingsDaemon.Power.Keyboard") - ("org.gnome.SettingsDaemon.Power.Screen") - ("org.gnome.SettingsDaemon.Power" - ("Icon" . ". GThemedIcon battery-full-charged-symbolic ") - ("Tooltip" . "Laptop battery is charged")) - ("org.freedesktop.DBus.Peer") - ("org.freedesktop.DBus.Introspectable") - ("org.freedesktop.DBus.Properties") - ("org.freedesktop.DBus.ObjectManager")) - @dots{}) -@end lisp - -If possible, @samp{org.freedesktop.DBus.ObjectManager.GetManagedObjects} -is used for retrieving the information. Otherwise, the information -is collected via @samp{org.freedesktop.DBus.Introspectable.Introspect} -and @samp{org.freedesktop.DBus.Properties.GetAll}, which is slow. - -An overview of all existing object paths, their interfaces and -properties could be retrieved by the following code: - -@lisp -(with-current-buffer (switch-to-buffer "*objectmanager*") - (erase-buffer) - (let (result) - (dolist (service (dbus-list-known-names :session) result) - (message "%s" service) - (add-to-list - 'result - (cons service - (dbus-get-all-managed-objects :session service "/")))) - (insert (message "%s" (pp result))) - (redisplay t))) -@end lisp -@end defun - -@defun dbus-introspect-get-annotation-names bus service path interface &optional name -Return a list of all annotation names as list of strings. If -@var{name} is @code{nil}, the annotations are children of -@var{interface}, otherwise @var{name} must be a @code{method}, -@code{signal}, or @code{property} XML element, where the annotations -belong to. Example: - -@lisp -(dbus-introspect-get-annotation-names - :session "de.berlios.Pinot" "/de/berlios/Pinot" - "de.berlios.Pinot" "GetStatistics") - -@result{} ("de.berlios.Pinot.GetStatistics") -@end lisp - -Default annotation names@footnote{See -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format}} -are - -@table @samp -@item org.freedesktop.DBus.Deprecated -Whether or not the entity is deprecated; defaults to @code{nil} - -@item org.freedesktop.DBus.GLib.CSymbol -The C symbol; may be used for @code{methods} and @code{interfaces} - -@item org.freedesktop.DBus.Method.NoReply -If set, don't expect a reply to the @code{method} call; defaults to @code{nil} -@end table -@end defun - -@defun dbus-introspect-get-annotation bus service path interface name annotation -Return annotation @var{ANNOTATION} as XML object. If @var{name} is -@code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise -@var{name} must be the name of a @code{method}, @code{signal}, or -@code{property} XML element, where the @var{ANNOTATION} belongs to. - -An attribute value can be retrieved by -@code{dbus-introspect-get-attribute}. Example: - -@lisp -(dbus-introspect-get-annotation - :session "de.berlios.Pinot" "/de/berlios/Pinot" - "de.berlios.Pinot" "GetStatistics" - "de.berlios.Pinot.GetStatistics") - -@result{} (annotation ((name . "de.berlios.Pinot.GetStatistics") - (value . "pinotDBus"))) - -(dbus-introspect-get-attribute - (dbus-introspect-get-annotation - :session "de.berlios.Pinot" "/de/berlios/Pinot" - "de.berlios.Pinot" "GetStatistics" - "de.berlios.Pinot.GetStatistics") - "value") - -@result{} "pinotDBus" -@end lisp -@end defun - - -@node Arguments and Signatures -@section The final details. - -Methods and signals have arguments. They are described in the -@code{arg} XML elements. - -@defun dbus-introspect-get-argument-names bus service path interface name -Return a list of all argument names as list of strings. @var{name} -must be a @code{method} or @code{signal} XML element. Example: - -@lisp -(dbus-introspect-get-argument-names - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData") - -@result{} ("search" "hit_ids" "fields" "hit_data") -@end lisp - -Argument names are optional; the function can return @code{nil} -therefore, even if the method or signal has arguments. -@end defun - -@defun dbus-introspect-get-argument bus service path interface name arg -Return argument @var{ARG} as XML object. @var{name} -must be a @code{method} or @code{signal} XML element. Example: - -@lisp -(dbus-introspect-get-argument - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData" "search") - -@result{} (arg ((name . "search") (type . "s") (direction . "in"))) -@end lisp -@end defun - -@defun dbus-introspect-get-signature bus service path interface name &optional direction -Return signature of a @code{method} or @code{signal}, represented by -@var{name}, as string. - -If @var{name} is a @code{method}, @var{direction} can be either -@samp{in} or @samp{out}. If @var{direction} is @code{nil}, @samp{in} -is assumed. - -If @var{name} is a @code{signal}, and @var{direction} is -non-@code{nil}, @var{direction} must be @samp{out}. Example: - -@lisp -(dbus-introspect-get-signature - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData" "in") - -@result{} "sauas" - -(dbus-introspect-get-signature - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "HitsAdded") - -@result{} "su" -@end lisp -@end defun - - -@node Type Conversion -@chapter Mapping Lisp types and D-Bus types. -@cindex type conversion - -D-Bus method calls and signals accept usually several arguments as -parameters, either as input parameter, or as output parameter. Every -argument belongs to a D-Bus type. - -Such arguments must be mapped between the value encoded as a D-Bus -type, and the corresponding type of Lisp objects. The mapping is -applied Lisp object @expansion{} D-Bus type for input parameters, and -D-Bus type @expansion{} Lisp object for output parameters. - - -@section Input parameters. - -Input parameters for D-Bus methods and signals occur as arguments of a -Lisp function call. The following mapping to D-Bus types is -applied, when the corresponding D-Bus message is created: - -@example -@multitable {negative integer} {@expansion{}} {DBUS_TYPE_BOOLEAN} -@item Lisp type @tab @tab D-Bus type -@item -@item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN -@item natural number @tab @expansion{} @tab DBUS_TYPE_UINT32 -@item negative integer @tab @expansion{} @tab DBUS_TYPE_INT32 -@item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE -@item string @tab @expansion{} @tab DBUS_TYPE_STRING -@item list @tab @expansion{} @tab DBUS_TYPE_ARRAY -@end multitable -@end example - -Other Lisp objects, like symbols or hash tables, are not accepted as -input parameters. - -If it is necessary to use another D-Bus type, a corresponding type -symbol can be prepended to the corresponding Lisp object. Basic D-Bus -types are represented by the type symbols @code{:byte}, -@code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32}, -@code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double}, -@code{:string}, @code{:object-path}, @code{:signature} and -@code{:unix-fd}. - -@noindent -Example: - -@lisp -(dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING}) -@end lisp - -is equivalent to - -@lisp -(dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING}) -@end lisp - -but different to - -@lisp -(dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING}) -@end lisp - -The value for a byte D-Bus type can be any integer in the range 0 -through 255. If a character is used as argument, modifiers -represented outside this range are stripped of. For example, -@code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to -@code{:byte ?\C-x} or @code{:byte ?\M-\C-x}. - -Signed and unsigned integer D-Bus types expect a corresponding integer -value. If the value does not fit Emacs's integer range, it is also -possible to use an equivalent floating point number. - -A D-Bus compound type is always represented as a list. The @sc{car} -of this list can be the type symbol @code{:array}, @code{:variant}, -@code{:struct} or @code{:dict-entry}, which would result in a -corresponding D-Bus container. @code{:array} is optional, because -this is the default compound D-Bus type for a list. - -The objects being elements of the list are checked according to the -D-Bus compound type rules. - -@itemize -@item An array must contain only elements of the same D-Bus type. It -can be empty. - -@item A variant must contain only one single element. - -@item A dictionary entry must be element of an array, and it must -contain only a key-value pair of two elements, with a basic D-Bus type -key. - -@item There is no restriction for structs. -@end itemize - -If an empty array needs an element D-Bus type other than string, it -can contain exactly one element of D-Bus type @code{:signature}. The -value of this element (a string) is used as the signature of the -elements of this array. Example: - -@lisp -(dbus-call-method - :session "org.freedesktop.Notifications" - "/org/freedesktop/Notifications" - "org.freedesktop.Notifications" "Notify" - "GNU Emacs" ;; Application name. - 0 ;; No replacement of other notifications. - "" ;; No icon. - "Notification summary" ;; Summary. - (format ;; Body. - "This is a test notification, raised from\n%S" (emacs-version)) - '(:array) ;; No actions (empty array of strings). - '(:array :signature "@{sv@}") ;; No hints - ;; (empty array of dictionary entries). - :int32 -1) ;; Default timeout. - -@result{} 3 -@end lisp - -@defun dbus-string-to-byte-array string -Sometimes, D-Bus methods require as input parameter an array of bytes, -instead of a string. If it is guaranteed, that @var{string} is an -UTF8 string, this function performs the conversion. Example: - -@lisp -(dbus-string-to-byte-array "/etc/hosts") - -@result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47 - :byte 104 :byte 111 :byte 115 :byte 116 :byte 115) -@end lisp -@end defun - -@defun dbus-escape-as-identifier string -Escape an arbitrary @var{string} so it follows the rules for a C -identifier. The escaped string can be used as object path component, -interface element component, bus name component or member name in -D-Bus. - -The escaping consists of replacing all non-alphanumerics, and the -first character if it's a digit, with an underscore and two -lower-case hex digits. As a special case, "" is escaped to -"_". Example: - -@lisp -(dbus-escape-as-identifier "0123abc_xyz\x01\xff") - -@result{} "_30123abc_5fxyz_01_ff" -@end lisp -@end defun - - -@section Output parameters. - -Output parameters of D-Bus methods and signals are mapped to Lisp -objects. - -@example -@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float} -@item D-Bus type @tab @tab Lisp type -@item -@item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil} -@item DBUS_TYPE_BYTE @tab @expansion{} @tab natural number -@item DBUS_TYPE_UINT16 @tab @expansion{} @tab natural number -@item DBUS_TYPE_INT16 @tab @expansion{} @tab integer -@item DBUS_TYPE_UINT32 @tab @expansion{} @tab natural number or float -@item DBUS_TYPE_UNIX_FD @tab @expansion{} @tab natural number or float -@item DBUS_TYPE_INT32 @tab @expansion{} @tab integer or float -@item DBUS_TYPE_UINT64 @tab @expansion{} @tab natural number or float -@item DBUS_TYPE_INT64 @tab @expansion{} @tab integer or float -@item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float -@item DBUS_TYPE_STRING @tab @expansion{} @tab string -@item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string -@item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string -@item DBUS_TYPE_ARRAY @tab @expansion{} @tab list -@item DBUS_TYPE_VARIANT @tab @expansion{} @tab list -@item DBUS_TYPE_STRUCT @tab @expansion{} @tab list -@item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list -@end multitable -@end example - -A float object in case of @code{DBUS_TYPE_UINT32}, -@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64}, -@code{DBUS_TYPE_INT64} and @code{DBUS_TYPE_UNIX_FD} is returned, when -the C value exceeds the Emacs number size range. - -The resulting list of the last 4 D-Bus compound types contains as -elements the elements of the D-Bus container, mapped according to the -same rules. - -The signal @code{PropertyModified}, discussed as example in -@ref{Inspection}, would offer as Lisp data the following object -(@var{BOOL} stands here for either @code{nil} or @code{t}): - -@lisp -(@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) -@end lisp - -@defun dbus-byte-array-to-string byte-array &optional multibyte -If a D-Bus method or signal returns an array of bytes, which are known -to represent an UTF8 string, this function converts @var{byte-array} -to the corresponding string. The string is unibyte encoded, unless -@var{multibyte} is non-@code{nil}. Example: - -@lisp -(dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115)) - -@result{} "/etc/hosts" -@end lisp -@end defun - -@defun dbus-unescape-from-identifier string -Retrieve the original string from the encoded @var{string} as unibyte -string. @var{string} must have been encoded with -@code{dbus-escape-as-identifier}. Example: - -@lisp -(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff") - -@result{} "0123abc_xyz\x01\xff" -@end lisp - -If the original string used in @code{dbus-escape-as-identifier} is a -multibyte string, it cannot be expected that this function returns -that string: - -@lisp -(string-equal - (dbus-unescape-from-identifier - (dbus-escape-as-identifier "Grüß Göttin")) - "Grüß Göttin") - -@result{} nil -@end lisp - - -@end defun - - -@node Synchronous Methods -@chapter Calling methods in a blocking way. -@cindex method calls, synchronous -@cindex synchronous method calls - -Methods can be called synchronously (@dfn{blocking}) or asynchronously -(@dfn{non-blocking}). - -At D-Bus level, a method call consist of two messages: one message -which carries the input parameters to the object owning the method to -be called, and a reply message returning the resulting output -parameters from the object. - -@defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args -This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is -either the symbol @code{:system} or the symbol @code{:session}. - -@var{service} is the D-Bus service name to be used. @var{path} is the -D-Bus object path, @var{service} is registered at. @var{interface} is -an interface offered by @var{service}. It must provide @var{method}. - -If the parameter @code{:timeout} is given, the following integer -@var{timeout} specifies the maximum number of milliseconds the method -call must return. The default value is 25,000. If the method call -doesn't return in time, a D-Bus error is raised (@pxref{Errors and -Events}). - -All other arguments args are passed to @var{method} as arguments. -They are converted into D-Bus types as described in @ref{Type -Conversion}. - -The function returns the resulting values of @var{method} as a list of -Lisp objects, according to the type conversion rules described in -@ref{Type Conversion}. Example: - -@lisp -(dbus-call-method - :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp" - "org.gnome.seahorse.Keys" "GetKeyField" - "openpgp:657984B8C7A966DD" "simple-name") - -@result{} (t ("Philip R. Zimmermann")) -@end lisp - -If the result of the method call is just one value, the converted Lisp -object is returned instead of a list containing this single Lisp -object. Example: - -@lisp -(dbus-call-method - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer" - "org.freedesktop.Hal.Device" "GetPropertyString" - "system.kernel.machine") - -@result{} "i686" -@end lisp - -With the @code{dbus-introspect} function it is possible to explore the -interfaces of @samp{org.freedesktop.Hal} service. It offers the -interfaces @samp{org.freedesktop.Hal.Manager} for the object at the -path @samp{/org/freedesktop/Hal/Manager} as well as the interface -@samp{org.freedesktop.Hal.Device} for all objects prefixed with the -path @samp{/org/freedesktop/Hal/devices}. With the methods -@samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to -emulate the @code{lshal} command on GNU/Linux systems: - -@lisp -(dolist (device - (dbus-call-method - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/Manager" - "org.freedesktop.Hal.Manager" "GetAllDevices")) - (message "\nudi = %s" device) - (dolist (properties - (dbus-call-method - :system "org.freedesktop.Hal" device - "org.freedesktop.Hal.Device" "GetAllProperties")) - (message " %s = %S" - (car properties) (or (caar (cdr properties)) "")))) - -@print{} "udi = /org/freedesktop/Hal/devices/computer - info.addons = (\"hald-addon-acpi\") - info.bus = \"unknown\" - info.product = \"Computer\" - info.subsystem = \"unknown\" - info.udi = \"/org/freedesktop/Hal/devices/computer\" - linux.sysfs_path_device = \"(none)\" - power_management.acpi.linux.version = \"20051216\" - power_management.can_suspend_to_disk = t - power_management.can_suspend_to_ram = \"\" - power_management.type = \"acpi\" - smbios.bios.release_date = \"11/07/2001\" - system.chassis.manufacturer = \"COMPAL\" - system.chassis.type = \"Notebook\" - system.firmware.release_date = \"03/19/2005\" - @dots{}" -@end lisp -@end defun - - -@node Asynchronous Methods -@chapter Calling methods non-blocking. -@cindex method calls, asynchronous -@cindex asynchronous method calls - -@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args -This function calls @var{method} on the D-Bus @var{bus} -asynchronously. @var{bus} is either the symbol @code{:system} or the -symbol @code{:session}. - -@var{service} is the D-Bus service name to be used. @var{path} is the -D-Bus object path, @var{service} is registered at. @var{interface} is -an interface offered by @var{service}. It must provide @var{method}. - -@var{handler} is a Lisp function, which is called when the -corresponding return message has arrived. If @var{handler} is -@code{nil}, no return message will be expected. - -If the parameter @code{:timeout} is given, the following integer -@var{timeout} specifies the maximum number of milliseconds a reply -message must arrive. The default value is 25,000. If there is no -reply message in time, a D-Bus error is raised (@pxref{Errors and -Events}). - -All other arguments args are passed to @var{method} as arguments. -They are converted into D-Bus types as described in @ref{Type -Conversion}. - -If @var{handler} is a Lisp function, the function returns a key into -the hash table @code{dbus-registered-objects-table}. The -corresponding entry in the hash table is removed, when the return -message has been arrived, and @var{handler} is called. Example: - -@lisp -(dbus-call-method-asynchronously - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer" - "org.freedesktop.Hal.Device" "GetPropertyString" 'message - "system.kernel.machine") - -@result{} (:serial :system 2) - -@print{} i686 -@end lisp -@end defun - - -@node Receiving Method Calls -@chapter Offering own methods. -@cindex method calls, returning -@cindex returning method calls - -In order to register methods on the D-Bus, Emacs has to request a well -known name on the D-Bus under which it will be available for other -clients. Names on the D-Bus can be registered and unregistered using -the following functions: - -@defun dbus-register-service bus service &rest flags -Register the known name @var{service} on D-Bus @var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the service name to be registered on the D-Bus. It -must be a known name. - -@var{flags} is a subset of the following keywords: - -@itemize -@item @code{:allow-replacement}: Allow another service to become the primary -owner if requested. - -@item @code{:replace-existing}: Request to replace the current primary owner. - -@item @code{:do-not-queue}: If we can not become the primary owner do not -place us in the queue. -@end itemize - -One of the following keywords is returned: - -@itemize - -@item @code{:primary-owner}: We have become the primary owner of the name -@var{service}. - -@item @code{:in-queue}: We could not become the primary owner and -have been placed in the queue. - -@item @code{:exists}: We already are in the queue. - -@item @code{:already-owner}: We already are the primary -owner. -@end itemize -@end defun - -@defun dbus-unregister-service bus service -Unregister all objects from D-Bus @var{bus}, registered by Emacs for -@var{service}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name of the D-Bus. It must be a -known name. Emacs releases its association to @var{service} from -D-Bus. - -One of the following keywords is returned: - -@itemize -@item @code{:released}: We successfully released the name @var{service}. -@item @code{:non-existent}: The name @var{service} does not exist on the bus. -@item @code{:not-owner}: We are not an owner of the name @var{service}. -@end itemize -@end defun - -When a name has been chosen, Emacs can offer own methods, which can be -called by other applications. These methods could be an -implementation of an interface of a well known service, like -@samp{org.freedesktop.TextEditor}. - -It could be also an implementation of an own interface. In this case, -the service name must be @samp{org.gnu.Emacs}. The object path shall -begin with @samp{/org/gnu/Emacs/@strong{Application}}, and the -interface name shall be @code{org.gnu.Emacs.@strong{Application}}. -@samp{@strong{Application}} is the name of the application which -provides the interface. - -@deffn Constant dbus-service-emacs -The well known service name @samp{org.gnu.Emacs} of Emacs. -@end deffn - -@deffn Constant dbus-path-emacs -The object path namespace @samp{/org/gnu/Emacs} used by Emacs. -@end deffn - -@deffn Constant dbus-interface-emacs -The interface namespace @code{org.gnu.Emacs} used by Emacs. -@end deffn - -@defun dbus-register-method bus service path interface method handler dont-register-service -With this function, an application registers @var{method} on the D-Bus -@var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name of the D-Bus object -@var{method} is registered for. It must be a known name (See -discussion of @var{dont-register-service} below). - -@var{path} is the D-Bus object path @var{service} is registered (See -discussion of @var{dont-register-service} below). - -@var{interface} is the interface offered by @var{service}. It must -provide @var{method}. - -@var{handler} is a Lisp function to be called when a @var{method} call -is received. It must accept as arguments the input arguments of -@var{method}. @var{handler} should return a list, whose elements are -to be used as arguments for the reply message of @var{method}. This -list can be composed like the input parameters in @ref{Type -Conversion}. - -If @var{handler} wants to return just one Lisp object and it is not a -cons cell, @var{handler} can return this object directly, instead of -returning a list containing the object. - -In case @var{handler} shall return a reply message with an empty -argument list, @var{handler} must return the symbol @code{:ignore}. - -When @var{dont-register-service} is non-@code{nil}, the known name -@var{service} is not registered. This means that other D-Bus clients -have no way of noticing the newly registered method. When interfaces -are constructed incrementally by adding single methods or properties -at a time, @var{dont-register-service} can be used to prevent other -clients from discovering the still incomplete interface. - -The default D-Bus timeout when waiting for a message reply is 25 -seconds. This value could be even smaller, depending on the calling -client. Therefore, @var{handler} shall not last longer than -absolutely necessary. - -@code{dbus-register-method} returns a Lisp object, which can be used -as argument in @code{dbus-unregister-object} for removing the -registration for @var{method}. Example: - -@lisp -(defun my-dbus-method-handler (filename) - (let (result) - (if (find-file filename) - (setq result '(:boolean t)) - (setq result '(:boolean nil))) - result)) - -@result{} my-dbus-method-handler - -(dbus-register-method - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "OpenFile" - 'my-dbus-method-handler) - -@result{} ((:method :session "org.freedesktop.TextEditor" "OpenFile") - ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - my-dbus-method-handler)) -@end lisp - -If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile} -from another D-Bus application with a filename as parameter, the file -is opened in Emacs, and the method returns either @var{true} or -@var{false}, indicating the success of the method. As test tool one -could use the command line tool @code{dbus-send} in a shell: - -@example -# dbus-send --session --print-reply \ - --dest="org.freedesktop.TextEditor" \ - "/org/freedesktop/TextEditor" \ - "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts" - -@print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2 - boolean true -@end example - -You can indicate an error by raising the Emacs signal -@code{dbus-error}. The handler above could be changed like this: - -@lisp -(defun my-dbus-method-handler (&rest args) - (unless (and (= (length args) 1) (stringp (car args))) - (signal 'dbus-error (list (format "Wrong argument list: %S" args)))) - (condition-case err - (find-file (car args)) - (error (signal 'dbus-error (cdr err)))) - t) - -@result{} my-dbus-method-handler -@end lisp - -The test runs then - -@example -# dbus-send --session --print-reply \ - --dest="org.freedesktop.TextEditor" \ - "/org/freedesktop/TextEditor" \ - "org.freedesktop.TextEditor.OpenFile" \ - string:"/etc/hosts" string:"/etc/passwd" - -@print{} Error org.freedesktop.DBus.Error.Failed: - Wrong argument list: ("/etc/hosts" "/etc/passwd") -@end example -@end defun - -@defun dbus-register-property bus service path interface property access value &optional emits-signal dont-register-service -With this function, an application declares a @var{property} on the D-Bus -@var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name of the D-Bus. It must be a -known name. - -@var{path} is the D-Bus object path @var{service} is registered (See -discussion of @var{dont-register-service} below). - -@var{interface} is the name of the interface used at @var{path}, -@var{property} is the name of the property of @var{interface}. - -@var{access} indicates, whether the property can be changed by other -services via D-Bus. It must be either the symbol @code{:read} or -@code{:readwrite}. @var{value} is the initial value of the property, -it can be of any valid type (see @code{dbus-call-method} for details). - -If @var{property} already exists on @var{path}, it will be -overwritten. For properties with access type @code{:read} this is the -only way to change their values. Properties with access type -@code{:readwrite} can be changed by @code{dbus-set-property}. - -The interface @samp{org.freedesktop.DBus.Properties} is added to -@var{path}, including a default handler for the @samp{Get}, -@samp{GetAll} and @samp{Set} methods of this interface. When -@var{emits-signal} is non-@code{nil}, the signal -@samp{PropertiesChanged} is sent when the property is changed by -@code{dbus-set-property}. - -When @var{dont-register-service} is non-@code{nil}, the known name -@var{service} is not registered. This means that other D-Bus clients -have no way of noticing the newly registered method. When interfaces -are constructed incrementally by adding single methods or properties -at a time, @var{dont-register-service} can be used to prevent other -clients from discovering the still incomplete interface. - -@noindent Example: - -@lisp -(dbus-register-property - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "name" :read "GNU Emacs") - -@result{} ((:property :session "org.freedesktop.TextEditor" "name") - ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor")) - -(dbus-register-property - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "version" :readwrite emacs-version t) - -@result{} ((:property :session "org.freedesktop.TextEditor" "version") - ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor")) -@end lisp - -Other D-Bus applications can read the property via the default methods -@samp{org.freedesktop.DBus.Properties.Get} and -@samp{org.freedesktop.DBus.Properties.GetAll}. Testing is also -possible via the command line tool @code{dbus-send} in a shell: - -@example -# dbus-send --session --print-reply \ - --dest="org.freedesktop.TextEditor" \ - "/org/freedesktop/TextEditor" \ - "org.freedesktop.DBus.Properties.GetAll" \ - string:"org.freedesktop.TextEditor" - -@print{} method return sender=:1.22 -> dest=:1.23 reply_serial=3 - array [ - dict entry( - string "name" - variant string "GNU Emacs" - ) - dict entry( - string "version" - variant string "23.1.50.5" - ) - ] -@end example - -It is also possible, to apply the @code{dbus-get-property}, -@code{dbus-get-all-properties} and @code{dbus-set-property} functions -(@pxref{Properties and Annotations}). - -@lisp -(dbus-set-property - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "version" "23.1.50") - -@result{} "23.1.50" - -(dbus-get-property - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "version") - -@result{} "23.1.50" -@end lisp -@end defun - -@defun dbus-unregister-object object -Unregister @var{object} from the D-Bus. @var{object} must be the -result of a preceding @code{dbus-register-method}, -@code{dbus-register-property} or @code{dbus-register-signal} call -(@pxref{Signals}). It returns @code{t} if @var{object} has been -unregistered, @code{nil} otherwise. - -When @var{object} identifies the last method or property, which is -registered for the respective service, Emacs releases its association -to the service from D-Bus. -@end defun - - -@node Signals -@chapter Sending and receiving signals. -@cindex signals - -Signals are one way messages. They carry input parameters, which are -received by all objects which have registered for such a signal. - -@defun dbus-send-signal bus service path interface signal &rest args -This function is similar to @code{dbus-call-method}. The difference -is, that there are no returning output parameters. - -The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is -either the symbol @code{:system} or the symbol @code{:session}. It -doesn't matter whether another object has registered for @var{signal}. - -Signals can be unicast or broadcast messages. For broadcast messages, -@var{service} must be @code{nil}. Otherwise, @var{service} is the -D-Bus service name the signal is sent to as unicast -message.@footnote{For backward compatibility, a broadcast message is -also emitted if @var{service} is the known or unique name Emacs is -registered at D-Bus @var{bus}.} @var{path} is the D-Bus object path -@var{signal} is sent from. @var{interface} is an interface available -at @var{path}. It must provide @var{signal}. - -All other arguments args are passed to @var{signal} as arguments. -They are converted into D-Bus types as described in @ref{Type -Conversion}. Example: - -@lisp -(dbus-send-signal - :session nil dbus-path-emacs - (concat dbus-interface-emacs ".FileManager") "FileModified" - "/home/albinus/.emacs") -@end lisp -@end defun - -@defun dbus-register-signal bus service path interface signal handler &rest args -With this function, an application registers for a signal on the D-Bus -@var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name used by the sending D-Bus -object. It can be either a known name or the unique name of the D-Bus -object sending the signal. A known name will be mapped onto the -unique name of the object, owning @var{service} at registration time. -When the corresponding D-Bus object disappears, signals won't be -received any longer. - -@var{path} is the corresponding D-Bus object path, @var{service} is -registered at. @var{interface} is an interface offered by -@var{service}. It must provide @var{signal}. - -@var{service}, @var{path}, @var{interface} and @var{signal} can be -@code{nil}. This is interpreted as a wildcard for the respective -argument. - -@var{handler} is a Lisp function to be called when the @var{signal} is -received. It must accept as arguments the output parameters -@var{signal} is sending. - -The remaining arguments @var{args} can be keywords or keyword string -pairs.@footnote{For backward compatibility, the arguments @var{args} -can also be just strings. They stand for the respective arguments of -@var{signal} in their order, and are used for filtering as well. A -@code{nil} argument might be used to preserve the order.} The meaning -is as follows: - -@itemize -@item @code{:argN} @var{string}:@* -@code{:pathN} @var{string}:@* -This stands for the Nth argument of the signal. @code{:pathN} -arguments can be used for object path wildcard matches as specified by -D-Bus, while an @code{:argN} argument requires an exact match. - -@item @code{:arg-namespace} @var{string}:@* -Register for the signals, which first argument defines the service or -interface namespace @var{string}. - -@item @code{:path-namespace} @var{string}:@* -Register for the object path namespace @var{string}. All signals sent -from an object path, which has @var{string} as the preceding string, -are matched. This requires @var{path} to be @code{nil}. - -@item @code{:eavesdrop}:@* -Register for unicast signals which are not directed to the D-Bus -object Emacs is registered at D-Bus BUS, if the security policy of BUS -allows this. Otherwise, this argument is ignored. -@end itemize - -@code{dbus-register-signal} returns a Lisp object, which can be used -as argument in @code{dbus-unregister-object} for removing the -registration for @var{signal}. Example: - -@lisp -(defun my-dbus-signal-handler (device) - (message "Device %s added" device)) - -@result{} my-dbus-signal-handler - -(dbus-register-signal - :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" - "org.freedesktop.Hal.Manager" "DeviceAdded" - 'my-dbus-signal-handler) - -@result{} ((:signal :system "org.freedesktop.Hal.Manager" "DeviceAdded") - ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" - my-signal-handler)) -@end lisp - -As we know from the introspection data of interface -@samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded} -provides one single parameter, which is mapped into a Lisp string. -The callback function @code{my-dbus-signal-handler} must define one -single string argument therefore. Plugging an USB device to your -machine, when registered for signal @samp{DeviceAdded}, will show you -which objects the GNU/Linux @code{hal} daemon adds. - -Some of the match rules have been added to a later version of D-Bus. -In order to test the availability of such features, you could register -for a dummy signal, and check the result: - -@lisp -(dbus-ignore-errors - (dbus-register-signal - :system nil nil nil nil 'ignore :path-namespace "/invalid/path")) - -@result{} nil -@end lisp -@end defun - - -@node Alternative Buses -@chapter Alternative buses and environments. -@cindex bus names -@cindex UNIX domain socket -@cindex TCP/IP socket - -Until now, we have spoken about the system and the session buses, -which are the default buses to be connected to. However, it is -possible to connect to any bus, from which the address is known. This -is a UNIX domain or TCP/IP socket. Everywhere, where a @var{bus} is -mentioned as argument of a function (the symbol @code{:system} or the -symbol @code{:session}), this address can be used instead. The -connection to this bus must be initialized first. - -@defun dbus-init-bus bus &optional private -Establish the connection to D-Bus @var{bus}. - -@var{bus} can be either the symbol @code{:system} or the symbol -@code{:session}, or it can be a string denoting the address of the -corresponding bus. For the system and session buses, this function -is called when loading @file{dbus.el}, there is no need to call it -again. - -The function returns a number, which counts the connections this Emacs -session has established to the @var{bus} under the same unique name -(see @code{dbus-get-unique-name}). It depends on the libraries Emacs -is linked with, and on the environment Emacs is running. For example, -if Emacs is linked with the gtk toolkit, and it runs in a GTK-aware -environment like Gnome, another connection might already be -established. - -When @var{private} is non-@code{nil}, a new connection is established -instead of reusing an existing one. It results in a new unique name -at the bus. This can be used, if it is necessary to distinguish from -another connection used in the same Emacs process, like the one -established by GTK+. It should be used with care for at least the -@code{:system} and @code{:session} buses, because other Emacs Lisp -packages might already use this connection to those buses. - -Example: You initialize a connection to the AT-SPI bus on your host: - -@lisp -(setq my-bus - (dbus-call-method - :session "org.a11y.Bus" "/org/a11y/bus" - "org.a11y.Bus" "GetAddress")) - -@result{} "unix:abstract=/tmp/dbus-2yzWHOCdSD,guid=a490dd26625870ca1298b6e10000fd7f" - -;; If Emacs is built with gtk support, and you run in a GTK enabled -;; environment (like a GNOME session), the initialization reuses the -;; connection established by GTK's atk bindings. -(dbus-init-bus my-bus) - -@result{} 2 - -(dbus-get-unique-name my-bus) - -@result{} ":1.19" - -;; Open a new connection to the same bus. This obsoletes the -;; previous one. -(dbus-init-bus my-bus 'private) - -@result{} 1 - -(dbus-get-unique-name my-bus) - -@result{} ":1.20" -@end lisp - -D-Bus addresses can specify different transport. A possible address -could be based on TCP/IP sockets, see next example. However, it -depends on the bus daemon configuration, which transport is supported. -@end defun - -@defun dbus-setenv bus variable value -Set the value of the @var{bus} environment variable @var{variable} to -@var{value}. - -@var{bus} is either a Lisp symbol, @code{:system} or @code{:session}, -or a string denoting the bus address. Both @var{variable} and -@var{value} should be strings. - -Normally, services inherit the environment of the bus daemon. This -function adds to or modifies that environment when activating services. - -Some bus instances, such as @code{:system}, may disable setting the -environment. In such cases, or if this feature is not available in -older D-Bus versions, a @code{dbus-error} error is raised. - -As an example, it might be desirable to start X11 enabled services on -a remote host's bus on the same X11 server the local Emacs is -running. This could be achieved by - -@lisp -(setq my-bus "unix:host=example.gnu.org,port=4711") - -@result{} "unix:host=example.gnu.org,port=4711" - -(dbus-init-bus my-bus) - -@result{} 1 - -(dbus-setenv my-bus "DISPLAY" (getenv "DISPLAY")) - -@result{} nil -@end lisp -@end defun - - -@node Errors and Events -@chapter Errors and events. -@cindex debugging -@cindex errors -@cindex events - -The internal actions can be traced by running in a debug mode. - -@defvar dbus-debug -If this variable is non-@code{nil}, D-Bus specific debug messages are raised. -@end defvar - -Input parameters of @code{dbus-call-method}, -@code{dbus-call-method-asynchronously}, @code{dbus-send-signal}, -@code{dbus-register-method}, @code{dbus-register-property} and -@code{dbus-register-signal} are checked for correct D-Bus types. If -there is a type mismatch, the Lisp error @code{wrong-type-argument} -@code{D-Bus ARG} is raised. - -All errors raised by D-Bus are signaled with the error symbol -@code{dbus-error}. If possible, error messages from D-Bus are -appended to the @code{dbus-error}. - -@defspec dbus-ignore-errors forms@dots{} -This executes @var{forms} exactly like a @code{progn}, except that -@code{dbus-error} errors are ignored during the @var{forms}. These -errors can be made visible when @code{dbus-debug} is set to @code{t}. -@end defspec - -Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc -Events, , , elisp}. They are retrieved only, when Emacs runs in -interactive mode. The generated event has this form: - -@lisp -(dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler} - &rest @var{args}) -@end lisp - -@var{bus} identifies the D-Bus the message is coming from. It is -either the symbol @code{:system} or the symbol @code{:session}. - -@var{type} is the D-Bus message type which has caused the event. It -can be @code{dbus-message-type-invalid}, -@code{dbus-message-type-method-call}, -@code{dbus-message-type-method-return}, -@code{dbus-message-type-error}, or @code{dbus-message-type-signal}. -@var{serial} is the serial number of the received D-Bus message. - -@var{service} and @var{path} are the unique name and the object path -of the D-Bus object emitting the message. @var{interface} and -@var{member} denote the message which has been sent. - -@var{handler} is the callback function which has been registered for -this message (see @pxref{Signals}). When a @code{dbus-event} event -arrives, @var{handler} is called with @var{args} as arguments. - -In order to inspect the @code{dbus-event} data, you could extend the -definition of the callback function in @ref{Signals}: - -@lisp -(defun my-dbus-signal-handler (&rest args) - (message "my-dbus-signal-handler: %S" last-input-event)) -@end lisp - -There exist convenience functions which could be called inside a -callback function in order to retrieve the information from the event. - -@defun dbus-event-bus-name event -Returns the bus name @var{event} is coming from. -The result is either the symbol @code{:system} or the symbol @code{:session}. -@end defun - -@defun dbus-event-message-type event -Returns the message type of the corresponding D-Bus message. The -result is a natural number. -@end defun - -@defun dbus-event-serial-number event -Returns the serial number of the corresponding D-Bus message. -The result is a natural number. -@end defun - -@defun dbus-event-service-name event -Returns the unique name of the D-Bus object @var{event} is coming from. -@end defun - -@defun dbus-event-path-name event -Returns the object path of the D-Bus object @var{event} is coming from. -@end defun - -@defun dbus-event-interface-name event -Returns the interface name of the D-Bus object @var{event} is coming from. -@end defun - -@defun dbus-event-member-name event -Returns the member name of the D-Bus object @var{event} is coming -from. It is either a signal name or a method name. -@end defun - -D-Bus errors are not propagated during event handling, because it is -usually not desired. D-Bus errors in events can be made visible by -setting the variable @code{dbus-debug} to @code{t}. They can also be -handled by a hook function. - -@defvar dbus-event-error-functions -This hook variable keeps a list of functions, which are called when a -D-Bus error happens in the event handler. Every function must accept -two arguments, the event and the error variable caught in -@code{condition-case} by @code{dbus-error}. - -Such functions can be used the adapt the error signal to be raised. -Example: - -@lisp -(defun my-dbus-event-error-handler (event error) - (when (string-equal (concat dbus-interface-emacs ".FileManager") - (dbus-event-interface-name event)) - (message "my-dbus-event-error-handler: %S %S" event error) - (signal 'file-error (cdr error)))) - -(add-hook 'dbus-event-error-functions 'my-dbus-event-error-handler) -@end lisp -@end defvar - -Hook functions shall take into account, that there might be other -D-Bus applications running. Therefore, they shall check carefully, -whether a given D-Bus error is related to them. - - -@node Index -@unnumbered Index - -@printindex cp - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi deleted file mode 100644 index fe40c5e300f..00000000000 --- a/doc/misc/dired-x.texi +++ /dev/null @@ -1,1112 +0,0 @@ -\input texinfo @comment -*-texinfo-*- - -@c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs -@c -@c Author: Sebastian Kremer -@c Lawrence R. Dodd -@c [Dodd's address no longer valid.] - -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/dired-x -@settitle Dired Extra User's Manual -@documentencoding UTF-8 - -@include emacsver.texi - -@iftex -@finalout -@end iftex -@c @setchapternewpage odd % For book style double sided manual. -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -Copyright @copyright{} 1994--1995, 1999, 2001--2014 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Dired-X: (dired-x). Dired Extra Features. -@end direntry - -@c @smallbook -@tex -\overfullrule=0pt -%\global\baselineskip 30pt % For printing in double spaces -@end tex - -@titlepage -@sp 6 -@center @titlefont{Dired Extra} -@sp 2 -@center @titlefont{For The GNU Emacs} -@sp 1 -@center @titlefont{Directory Editor} -@sp 4 -@center Lawrence R@. Dodd -@c @center @t{dodd@@roebling.poly.edu} -@sp 5 -@center (Based on @file{dired.texi} by Sebastian Kremer ) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - - -@ifnottex - -@node Top -@top Dired Extra - -@noindent -This documents the ``extra'' features for GNU Emacs's Dired Mode that are -provided by the file @file{dired-x.el}. - -@itemize @bullet - -@item -Based on @file{dired.texi} by Sebastian Kremer - -@item -For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}. - -@end itemize - -@insertcopying - -@menu -* Introduction:: -* Installation:: -* Omitting Files in Dired:: -* Local Variables:: -* Shell Command Guessing:: -* Virtual Dired:: -* Advanced Mark Commands:: -* Multiple Dired Directories:: -* Find File At Point:: -* Miscellaneous Commands:: -* Bugs:: - -* GNU Free Documentation License:: -* Concept Index:: -* Command Index:: -* Key Index:: -* Variable Index:: - -@end menu - -@end ifnottex - -@node Introduction -@chapter Introduction - -This documents some @emph{extra} features for GNU Emacs's Dired Mode -that are provided by @file{dired-x.el} (derived from Sebastian Kremer's -original @file{dired-x.el}). - -@ifnottex -@menu -* Features:: -* Technical Details:: -@end menu -@end ifnottex - -@node Features -@section Features -@cindex Features - -Some features provided by Dired Extra: - -@enumerate -@item -Omitting uninteresting files from Dired listing -(@pxref{Omitting Files in Dired}). -@item -Guessing shell commands in Dired buffers -(@pxref{Shell Command Guessing}). -@item -Running Dired command in non-Dired buffers -(@pxref{Virtual Dired}). -@item -Finding a file mentioned in a buffer -(@pxref{Find File At Point}). -@item -Commands using file marking -(@pxref{Advanced Mark Commands}). -@end enumerate - -@noindent -@file{dired-x.el} binds some functions to keys in Dired Mode (@pxref{Key -Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to -@code{dired-jump} (@pxref{Miscellaneous Commands}). Optionally, it -also binds @kbd{C-x C-f} and @kbd{C-x 4 C-f} to -@code{dired-x-find-file} and @code{dired-x-find-file-other-window}, -respectively (@pxref{Find File At Point}). - -@node Technical Details -@section Technical Details -@cindex Modified functions -@cindex @file{dired-aux.el} - -When @file{dired-x.el} is loaded, some standard Dired functions from -@file{dired.el} and @file{dired-aux.el} offer additional features. -@code{dired-add-entry} obeys Dired Omit mode (@pxref{Omitting Files in -Dired}), if it is active. @code{dired-find-buffer-nocreate} and -@code{dired-initial-position} respect the value of -@code{dired-find-subdir} (@pxref{Miscellaneous Commands}). -@code{dired-clean-up-after-deletion} respects the value of -@code{dired-clean-up-buffers-too}. @code{dired-read-shell-command} uses -@code{dired-guess-shell-command} (@pxref{Shell Command Guessing}) to -offer a smarter default command. - -@node Installation -@chapter Installation - -@noindent -This manual describes the Dired features provided by the file -@file{dired-x.el}. To take advantage of these features, you must load the -file and (optionally) set some variables. - -@noindent -In your @file{~/.emacs} file, or in the system-wide initialization file -@file{default.el} in the @file{site-lisp} directory, put - -@example -(add-hook 'dired-load-hook - (lambda () - (load "dired-x") - ;; Set dired-x global variables here. For example: - ;; (setq dired-guess-shell-gnutar "gtar") - ;; (setq dired-x-hands-off-my-keys nil) - )) -(add-hook 'dired-mode-hook - (lambda () - ;; Set dired-x buffer-local variables here. For example: - ;; (dired-omit-mode 1) - )) -@end example - -@noindent -This will load @file{dired-x.el} when Dired is first invoked (for example, -when you first type @kbd{C-x d}). - -@ifnottex -@menu -* Optional Installation Dired Jump:: -* Optional Installation File At Point:: -@end menu -@end ifnottex - -@node Optional Installation Dired Jump -@section Optional Installation Dired Jump - -@cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window} - -In order to have @code{dired-jump} and @code{dired-jump-other-window} -(@pxref{Miscellaneous Commands}) work @emph{before} @code{dired} and -@code{dired-x} have been properly loaded you should set-up an autoload -for these functions. In your @file{.emacs} file put - -@example -(autoload 'dired-jump "dired-x" - "Jump to Dired buffer corresponding to current buffer." t) - -(autoload 'dired-jump-other-window "dired-x" - "Like \\[dired-jump] (dired-jump) but in other window." t) - -(define-key global-map "\C-x\C-j" 'dired-jump) -(define-key global-map "\C-x4\C-j" 'dired-jump-other-window) -@end example - -@node Optional Installation File At Point -@section Optional Installation File At Point - -@cindex Binding @code{dired-x-find-file} -If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over -@code{find-file} (@pxref{Find File At Point}), then you will need to set -@code{dired-x-hands-off-my-keys}. To do this, either set it -@emph{before} @file{dired-x.el} is loaded, or use @kbd{M-x customize-variable}, -or call @code{dired-x-bind-find-file} after changing the value. - -@example -(add-hook 'dired-load-hook - (lambda () - ;; Bind dired-x-find-file. - (setq dired-x-hands-off-my-keys nil) - (load "dired-x") - )) -@end example - -@node Omitting Files in Dired -@chapter Omitting Files in Dired - -@cindex Omitting Files in Dired -@cindex Uninteresting files -@dfn{Omitting} a file means removing it from the directory listing. Omitting -is useful for keeping Dired buffers free of ``uninteresting'' files (for -instance, auto-save, auxiliary, backup, and revision control files) so that -the user can concentrate on the interesting files. Like hidden files, omitted -files are never seen by Dired. Omitting differs from hiding in several -respects: - -@itemize @bullet - -@item -Omitting works on individual files, not on directories; an entire directory -cannot be omitted (though each of its files could be). - -@item -Omitting is wholesale; if omitting is turned on for a Dired buffer, then all -uninteresting files listed in that buffer are omitted. The user does not omit -(or unomit) files one at a time. - -@item -Omitting can be automatic; uninteresting file lines in the buffer can be -removed before the user ever sees them. - -@item -Marked files are never omitted. -@end itemize - -@table @kbd -@item C-x M-o -@kindex C-x M-o -@findex dired-omit-mode -(@code{dired-omit-mode}) Toggle between displaying and omitting -``uninteresting'' files. -@item * O -@kindex * O -@findex dired-mark-omitted -(@code{dired-mark-omitted}) Mark ``uninteresting'' files. -@end table - -@noindent -In order to make Dired Omit work you first need to load @file{dired-x.el} -inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate -@code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}). - -@ifnottex -@menu -* Omitting Variables:: -* Omitting Examples:: -* Omitting Technical:: -@end menu -@end ifnottex - -@node Omitting Variables -@section Omitting Variables - -@cindex Customizing file omitting -The following variables can be used to customize omitting. - -@table @code - -@vindex dired-omit-mode -@item dired-omit-mode - -Default: @code{nil} - -@cindex How to make omitting the default in Dired -If non-@code{nil}, ``uninteresting'' files are not listed. -Uninteresting files are those whose files whose names match regexp -@code{dired-omit-files}, plus those ending with extensions in -@code{dired-omit-extensions}. @kbd{C-x M-o} (@code{dired-omit-mode}) -toggles its value, which is buffer-local. Put - -@example -(dired-omit-mode 1) -@end example - -@noindent -inside your @code{dired-mode-hook} to have omitting initially turned on in -@emph{every} Dired buffer (@pxref{Installation}). You can then use -@kbd{C-x M-o} to unomit in that buffer. - -To enable omitting automatically only in certain directories you can add -a directory local setting -(@pxref{Directory Variables,,,emacs,The Gnu Emacs manual}) for Dired mode - -@example -((dired-mode . ((dired-omit-mode . t)))) -@end example - -@noindent -to a @file{.dir-locals.el} file in that directory. You can use the -command @code{add-dir-local-variable} to do this. - -@vindex dired-omit-files -@item dired-omit-files - -Default: @code{"^#\\|\\.$"} - -Files whose names match this buffer-local regexp will not be displayed. -This only has effect when @code{dired-omit-mode}'s value is @code{t}. - -The default value omits the special directories @file{.} and @file{..} and -autosave files (plus other files ending in @file{.}) (@pxref{Omitting Examples}). - -@vindex dired-omit-extensions -@item dired-omit-extensions - -Default: The elements of @code{completion-ignored-extensions}, -@code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions} -and @code{dired-texinfo-unclean-extensions}. - -If non-@code{nil}, a list of extensions (strings) to omit from Dired listings. -Its format is the same as that of @code{completion-ignored-extensions}. - -@vindex dired-omit-localp -@item dired-omit-localp - -Default: @code{no-dir} - -The @var{localp} argument @code{dired-omit-expunge} passes to -@code{dired-get-filename}. If it is @code{no-dir}, omitting is much faster, -but you can only match against the non-directory part of the file name. Set it -to @code{nil} if you need to match the whole file name or @code{t} to match the -file name relative to the buffer's top-level directory. - -@item dired-omit-marker-char -@vindex dired-omit-marker-char -@cindex Omitting additional files -Default: @kbd{C-o} - -Temporary marker used by Dired to implement omitting. Should never be used -as marker by the user or other packages. There is one exception to this rule: -by adding - -@example -(setq dired-mark-keys "\C-o") -;; i.e., the value of dired-omit-marker-char -;; (which is not defined yet) -@end example - -@noindent -to your @file{~/.emacs}, you can bind the @kbd{C-o} key to insert a -@kbd{C-o} marker, thus causing these files to be omitted in addition to the -usually omitted files. Unfortunately the files you omitted manually this way -will show up again after reverting the buffer, unlike the others. - -@end table - -@node Omitting Examples -@section Examples of Omitting Various File Types - -@itemize @bullet - -@item -@cindex RCS files, how to omit them in Dired -@cindex Omitting RCS files in Dired -If you wish to avoid seeing RCS files and the @file{RCS} directory, then put - -@example -(setq dired-omit-files - (concat dired-omit-files "\\|^RCS$\\|,v$")) -@end example - -@noindent -in the @code{dired-load-hook} (@pxref{Installation}). This assumes -@code{dired-omit-localp} has its default value of @code{no-dir} to make the -@code{^}-anchored matches work. As a slower alternative, with -@code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of -@code{^} in the regexp. - -@item -@cindex Tib files, how to omit them in Dired -@cindex Omitting tib files in Dired -If you use @code{tib}, the bibliography program for use with @TeX{} and -@LaTeX{}, and you -want to omit the @file{INDEX} and the @file{*-t.tex} files, then put - -@example -(setq dired-omit-files - (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$")) -@end example - -@noindent -in the @code{dired-load-hook} (@pxref{Installation}). - -@item -@cindex Dot files, how to omit them in Dired -@cindex Omitting dot files in Dired -If you do not wish to see @samp{dot} files (files starting with a @file{.}), -then put - -@example -(setq dired-omit-files - (concat dired-omit-files "\\|^\\..+$")) -@end example - -@noindent -in the @code{dired-load-hook} (@pxref{Installation}). (Of course, a -better way to achieve this particular goal is simply to omit @samp{-a} from -@code{dired-listing-switches}.) - -@end itemize - -@node Omitting Technical -@section Some Technical Details of Omitting - -Loading @file{dired-x.el} will install Dired Omit by putting -@code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will -call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} -in your @code{dired-mode-hook}. - -@node Local Variables -@chapter Local Variables for Dired Directories - -@cindex Local Variables for Dired Directories -@vindex dired-local-variables-file -@vindex dired-enable-local-variables -@noindent -This Dired-X feature is obsolete as of Emacs 24.1. The standard Emacs -directory local variables mechanism (@pxref{Directory -Variables,,,emacs,The Gnu Emacs manual}) replaces it. For an example of -the new mechanisms, @pxref{Omitting Variables}. - -When Dired visits a directory, it looks for a file whose name is the -value of variable @code{dired-local-variables-file} (default: @file{.dired}). -If such a file is found, Dired will temporarily insert it into the Dired -buffer and run @code{hack-local-variables}. - -@noindent -For example, if the user puts - -@example -Local Variables: -dired-actual-switches: "-lat" -dired-omit-mode: t -End: -@end example - -@noindent -into a file called @file{.dired} in a directory then when that directory is -viewed it will be - -@enumerate -@item -sorted by date -@item -omitted automatically -@end enumerate - -@noindent -You can set @code{dired-local-variables-file} to @code{nil} to suppress this. -The value of @code{dired-enable-local-variables} controls if and how these -local variables are read. This variable exists so that it may override the -default value of @code{enable-local-variables}. - -@noindent -Please see the GNU Emacs Manual to learn more about local variables. -@xref{File Variables,Local Variables in Files,Local Variables in -Files,emacs,The GNU Emacs Manual}. - -@noindent -The following variables affect Dired Local Variables - -@table @code -@vindex dired-local-variables-file -@item dired-local-variables-file -Default: @code{".dired"} - -If non-@code{nil}, file name for local variables for Dired. If Dired finds a -file with that name in the current directory, it will temporarily insert it -into the Dired buffer and run @code{hack-local-variables}. - -@vindex dired-enable-local-variables -@item dired-enable-local-variables -Default: @code{t} - -Controls the use of local-variables lists in Dired. This variable -temporarily overrides the value of @code{enable-local-variables} when -the Dired Local Variables are hacked. It takes the same values as that -variable. A value of @code{nil} means to ignore any Dired Local Variables. -@end table - -@node Shell Command Guessing -@chapter Shell Command Guessing -@cindex Guessing shell commands for files. - -Based upon the name of a file, Dired tries to guess what shell -command you might want to apply to it. For example, if you have point -on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess -you want to @samp{tar xvf} it and suggest that as the default shell -command. - -The default is mentioned in brackets and you can type @kbd{M-n} to get -the default into the minibuffer and then edit it, e.g., to change -@samp{tar xvf} to @samp{tar tvf}. If there are several commands for a given -file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type -@kbd{M-n} several times to see each of the matching commands. - -Dired only tries to guess a command for a single file, never for a list -of marked files. - -@table @code -@item dired-guess-shell-alist-default -@vindex dired-guess-shell-alist-default -Predefined rules for shell commands. Set this to @code{nil} to turn guessing off. -The elements of @code{dired-guess-shell-alist-user} (defined by the -user) will override these rules. - -@item dired-guess-shell-alist-user -@vindex dired-guess-shell-alist-user -If non-@code{nil}, a user-defined alist of file regexps and their suggested -commands. These rules take precedence over the predefined rules in the -variable @code{dired-guess-shell-alist-default} (to which they are prepended) -when @code{dired-do-shell-command} is run). - -Each element of the alist looks like - -@example -(@var{regexp} @var{command}@dots{}) -@end example - -@noindent -where each @var{command} can either be a string or a Lisp expression -that evaluates to a string. If several commands are given, all of -them will temporarily be pushed onto the history. - -If @samp{*} in the shell command, that means to substitute the file -name. - -You can set this variable in your @file{~/.emacs}. For example, -to add rules for @samp{.foo} and @samp{.bar} file extensions, write - -@example -(setq dired-guess-shell-alist-user - (list - (list "\\.foo$" "@var{foo-command}");; fixed rule - ;; possibly more rules... - (list "\\.bar$";; rule with condition test - '(if @var{condition} - "@var{bar-command-1}" - "@var{bar-command-2}")))) -@end example - -@noindent -This will override any predefined rules for the same extensions. - -@item dired-guess-shell-case-fold-search -@vindex dired-guess-shell-case-fold-search -Default: @code{t} - -Non-@code{nil} means @code{dired-guess-shell-alist-default} and -@code{dired-guess-shell-alist-user} are matched case-insensitively. - -@item dired-guess-shell-gnutar -@vindex dired-guess-shell-gnutar -@cindex Passing GNU Tar its @samp{z} switch. -Default: @code{nil} - -If non-@code{nil}, this is the name of the GNU Tar executable (e.g., -@samp{tar} or @samp{gnutar}). GNU Tar's @samp{z} switch is used for -compressed tar files. -If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is -then used. - -@item dired-guess-shell-gzip-quiet -@vindex dired-guess-shell-gzip-quiet -@cindex @code{gzip} -Default: @code{t} - -A non-@code{nil} value means that @samp{-q} is passed to @code{gzip} -overriding a verbose option in the @env{GZIP} environment variable. - -@item dired-guess-shell-znew-switches nil -@vindex dired-guess-shell-znew-switches nil -@cindex @code{znew} -Default: @code{nil} - -A string of switches passed to @code{znew}. An example is -@samp{-K} which will make @code{znew} keep a @file{.Z} file when it is -smaller than the @file{.gz} file. - -@item dired-shell-command-history nil -@vindex dired-shell-command-history nil - -History list for commands that read dired-shell commands. -@end table - -@node Virtual Dired -@chapter Virtual Dired - -@cindex Virtual Dired -@cindex Perusing @code{ls} listings -@cindex @code{ls} listings, how to peruse them in Dired -Using @dfn{Virtual Dired} means putting a buffer with Dired-like -contents in Dired mode. The files described by the buffer contents need -not actually exist. This is useful if you want to peruse an @samp{ls -lR} -output file, for example one you got from an FTP server. You can use -all motion commands usually available in Dired. You can also use -it to save a Dired buffer in a file and resume it in a later session. - -@findex dired-virtual -@kindex g -@findex dired-virtual-revert -Type @kbd{M-x dired-virtual} to put the current buffer into virtual -Dired mode. You will be prompted for the top level directory of this -buffer, with a default value guessed from the buffer contents. To -convert the virtual to a real Dired buffer again, type @kbd{g} (which -calls @code{dired-virtual-revert}) in the virtual Dired buffer and -answer @samp{y}. You don't have to do this, though: you can relist -single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory -headerline, leaving the buffer in virtual Dired mode all the time. - -@findex dired-virtual-mode -@vindex auto-mode-alist -The function @samp{dired-virtual-mode} is specially designed to turn on -virtual Dired mode from the @code{auto-mode-alist}. To edit all -@file{*.dired} files automatically in virtual Dired mode, put this into your -@file{~/.emacs}: - -@example -(setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode) - auto-mode-alist)) -@end example - -@noindent -The regexp is a bit more complicated than usual to exclude @file{.dired} -local-variable files. - -@node Advanced Mark Commands -@chapter Advanced Mark Commands - -@table @kbd -@item F -@kindex F -@cindex Visiting several files at once -@cindex Simultaneous visiting of several files -@findex dired-do-find-marked-files -(@code{dired-do-find-marked-files}) Find all marked files at once displaying -them simultaneously. If optional @var{noselect} is non-@code{nil} then just -find the -files but do not select. If you want to keep the Dired buffer displayed, type -@kbd{C-x 2} first. If you want just the marked files displayed and nothing -else, type @kbd{C-x 1} first. - -The current window is split across all files marked, as evenly as possible. -Remaining lines go to the bottom-most window. The number of files that can be -displayed this way is restricted by the height of the current window and the -variable @code{window-min-height}. -@end table - -@table @code -@item dired-mark-extension -@findex dired-mark-extension -Mark all files with a certain extension for use in later commands. A @samp{.} -is not automatically prepended to the string entered, you must type it -explicitly. - -When called from Lisp, @var{extension} may also be a list of extensions -and an optional argument @var{marker-char} specifies the marker used. - -@item dired-flag-extension -@findex dired-flag-extension -Flag all files with a certain extension for deletion. A @samp{.} is -@emph{not} automatically prepended to the string entered. -@end table - -@ifnottex -@menu -* Advanced Cleaning Functions:: -* Advanced Cleaning Variables:: -* Special Marking Function:: -@end menu -@end ifnottex - -@node Advanced Cleaning Functions -@section Advanced Cleaning Functions - -@table @code -@item dired-clean-patch -@findex dired-clean-patch -Flag dispensable files created by the @samp{patch} program for deletion. See -variable @code{dired-patch-unclean-extensions}. - -@item dired-clean-tex -@findex dired-clean-tex -Flag dispensable files created by @TeX{}, @LaTeX{}, and @samp{texinfo} for -deletion. See the following variables (@pxref{Advanced Cleaning Variables}): - -@itemize @bullet -@item -@code{dired-tex-unclean-extensions} -@item -@code{dired-texinfo-unclean-extensions} -@item -@code{dired-latex-unclean-extensions} -@item -@code{dired-bibtex-unclean-extensions} -@end itemize - -@item dired-very-clean-tex -@findex dired-very-clean-tex -Flag dispensable files created by @TeX{}, @LaTeX{}, @samp{texinfo}, -and @file{*.dvi} files for deletion. -@end table - -@node Advanced Cleaning Variables -@section Advanced Cleaning Variables - -@noindent Variables used by the above cleaning commands (and in the default value for -variable @code{dired-omit-extensions}, @pxref{Omitting Variables}) - -@table @code -@item dired-patch-unclean-extensions -@vindex dired-patch-unclean-extensions -Default: @code{(".rej" ".orig")} - -List of extensions of dispensable files created by the @samp{patch} program. - -@item dired-tex-unclean-extensions -@vindex dired-tex-unclean-extensions -Default: @code{(".toc" ".log" ".aux")} - -List of extensions of dispensable files created by @TeX{}. - -@item dired-texinfo-unclean-extensions -@vindex dired-texinfo-unclean-extensions -Default: @code{(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"} -@code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")} - -List of extensions of dispensable files created by @samp{texinfo}. - -@item dired-latex-unclean-extensions -@vindex dired-latex-unclean-extensions -Default: @code{(".idx" ".lof" ".lot" ".glo")} - -List of extensions of dispensable files created by @LaTeX{}. - -@item dired-bibtex-unclean-extensions -@vindex dired-bibtex-unclean-extensions -Default: @code{(".blg" ".bbl")} - -List of extensions of dispensable files created by Bib@TeX{}. -@end table - -@node Special Marking Function -@section Special Marking Function - -@table @kbd -@item M-( -@kindex M-( -@findex dired-mark-sexp -@cindex Lisp expression, marking files with in Dired -@cindex Mark file by Lisp expression -(@code{dired-mark-sexp}) Mark files for which @var{predicate} returns -non-@code{nil}. With a prefix argument, unflag those files instead. - -The @var{predicate} is a Lisp expression that can refer to the following -symbols: -@table @code -@item inode -[@i{integer}] the inode of the file (only for @samp{ls -i} output) -@item s -[@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or, -with @samp{-k}, in KBytes) -@item mode -[@i{string}] file permission bits, e.g., @samp{-rw-r--r--} -@item nlink -[@i{integer}] number of links to file -@item uid -[@i{string}] owner -@item gid -[@i{string}] group (If the gid is not displayed by @samp{ls}, this -will still be set (to the same as uid)) -@item size -[@i{integer}] file size in bytes -@item time -[@i{string}] the time that @samp{ls} displays, e.g., @samp{Feb 12 14:17} -@item name -[@i{string}] the name of the file -@item sym -[@i{string}] if file is a symbolic link, the linked-to name, else @code{""} -@end table - -@noindent -For example, use -@example -(equal 0 size) -@end example -to mark all zero length files. - -To find out all not yet compiled Emacs Lisp files in a directory, Dired -all @file{.el} files in the lisp directory using the wildcard -@samp{*.el}. Then use @kbd{M-(} with -@example -(not (file-exists-p (concat name "c"))) -@end example -to mark all @file{.el} files without a corresponding @file{.elc} file. - -@end table - -@node Multiple Dired Directories -@chapter Multiple Dired Directories and Non-Dired Commands - -@cindex Multiple Dired directories -@cindex Working directory -An Emacs buffer can have but one working directory, stored in the -buffer-local variable @code{default-directory}. A Dired buffer may have -several subdirectories inserted, but it still has only one working -directory: that of the top-level Dired directory in that buffer. For -some commands it is appropriate that they use the current Dired -directory instead of @code{default-directory}, e.g., @code{find-file} and -@code{compile}. - -@findex dired-smart-shell-command -@findex shell-command -@kindex M-! -The command @code{dired-smart-shell-command}, bound to @kbd{M-!} in -Dired buffers, is like @code{shell-command}, but it runs with -@code{default-directory} bound to the current Dired directory. - -@node Find File At Point -@chapter Find File At Point -@cindex Visiting a file mentioned in a buffer -@cindex Finding a file at point - -@file{dired-x} provides a method of visiting or editing a file mentioned in -the buffer you are viewing (e.g., a mail buffer, a news article, a -@file{README} file, etc.)@: or to test if that file exists. You can then modify -this in the minibuffer after snatching the file name. - -When installed @file{dired-x} will substitute @code{dired-x-find-file} for -@code{find-file} (normally bound to @kbd{C-x C-f}) and -@code{dired-x-find-file-other-window} for @code{find-file-other-window} -(normally bound to @kbd{C-x 4 C-f}). - -In order to use this feature, you will need to set -@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook} -(@pxref{Optional Installation File At Point}). - -@table @code -@item dired-x-find-file -@findex dired-x-find-file -@kindex C-x C-f - -@code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound -to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which -case it will use the file name at point as a guess for the file to visit. - -For example, if the buffer you were reading contained the words - -@example -Available via anonymous ftp in - - /roebling.poly.edu:/pub/lisp/crypt++.el.gz -@end example - -@noindent -then you could move your cursor to the line containing the ftp address and -type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument). The -minibuffer would read - -@example -Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz -@end example - -@noindent -with the point after the last @code{/}. If you hit @key{RET}, emacs will visit -the file at that address. This also works with files on your own computer. - -@item dired-x-find-file-other-window -@findex dired-x-find-file-other-window -@kindex C-x 4 C-f - -@code{dired-x-find-file-other-window} behaves exactly like -@code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a -prefix argument is used. See @code{dired-x-find-file} for more information. - -@item dired-x-hands-off-my-keys -@vindex dired-x-hands-off-my-keys -If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind -@code{dired-x-find-file} over @code{find-file} on keyboard. Similarly, it -should not bind @code{dired-x-find-file-other-window} over -@code{find-file-other-window}. If you change this variable after -@file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}. The -default value of this variable is @code{t}; by default, the binding is not -done. See @xref{Optional Installation File At Point}. - -@item dired-x-bind-find-file -@findex dired-x-bind-find-file -A function, which can be called interactively or in your @file{~/.emacs} file, -that uses the value of @code{dired-x-hands-off-my-keys} to determine if -@code{dired-x-find-file} should be bound over @code{find-file} and -@code{dired-x-find-file-other-window} bound over -@code{find-file-other-window}. See @xref{Optional Installation File At Point}. -@end table - -@node Miscellaneous Commands -@chapter Miscellaneous Commands - -Miscellaneous features not fitting anywhere else: - -@table @code -@item dired-find-subdir -@vindex dired-find-subdir -Default: @code{nil} - -If non-@code{nil}, Dired does not make a new buffer for a directory if it can -be found (perhaps as subdirectory) in some existing Dired buffer. - -If there are several Dired buffers for a directory, the most recently -used is chosen. - -Dired avoids switching to the current buffer, so that if you have a -normal and a wildcard buffer for the same directory, @kbd{C-x d RET} -will toggle between those two. -@end table - -@table @kbd -@findex dired-goto-subdir -@kindex M-G -@item M-G -(@code{dired-goto-subdir}) Go to the header line of an inserted directory. -This command reads its argument, with completion derived from the names of the -inserted subdirectories. -@end table - -@table @code - -@item dired-jump -@findex dired-jump -@kindex C-x C-j -@cindex Jumping to Dired listing containing file. -Bound to @kbd{C-x C-j}. Jump back to Dired: If in a file, edit the current -directory and move to file's line. If in Dired already, pop up a level and -go to old directory's line. In case the proper Dired file line cannot be -found, refresh the Dired buffer and try again. - -@item dired-jump-other-window -@findex dired-jump-other-window -@kindex C-x 4 C-j -Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window. - -These functions can be autoloaded so they work even though @file{dired-x.el} -has not been loaded yet (@pxref{Optional Installation Dired Jump}). - -@vindex dired-bind-jump -If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be -bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to -@kbd{C-x 4 C-j}. - -@item dired-vm -@cindex Reading mail. -@kindex V -@findex dired-vm -Bound to @kbd{V} if @code{dired-bind-vm} is @code{t}. Run VM on this -file (assumed to be a UNIX mail folder). - -@vindex dired-vm-read-only-folders -If you give this command a prefix argument, it will visit the folder -read-only. - -If the variable @code{dired-vm-read-only-folders} is @code{t}, -@code{dired-vm} will visit all folders read-only. If it is neither -@code{nil} nor @code{t}, e.g., the symbol @code{if-file-read-only}, only -files not writable by you are visited read-only. - -@vindex dired-bind-vm -If the variable @code{dired-bind-vm} is @code{t}, @code{dired-vm} will be bound -to @kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound. - -@item dired-rmail -@cindex Reading mail. -@findex dired-rmail -Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this -file (assumed to be mail folder in Rmail format). - -@item dired-info -@kindex I -@cindex Running info. -@findex dired-info -Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info -format). - -@vindex dired-bind-info -If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will -not be bound to @kbd{I}. - -@item dired-man -@cindex Running man. -@kindex N -@findex dired-man -Bound to @kbd{N}. Run man on this file (assumed to be a file in @code{nroff} -format). - -@vindex dired-bind-man -If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not -be bound to @kbd{N}. - -@item dired-do-relsymlink -@cindex Relative symbolic links. -@kindex Y -@findex dired-do-relsymlink -Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a -directory, or make a relative symbolic link to the current file. This creates -relative symbolic links like - -@example - foo -> ../bar/foo -@end example - -@noindent -not absolute ones like - -@example - foo -> /ugly/path/that/may/change/any/day/bar/foo -@end example - -@item dired-do-relsymlink-regexp -@kindex %Y -@findex dired-do-relsymlink-regexp -Bound to @kbd{%Y}. Relative symlink all marked files containing -@var{regexp} to @var{newname}. See functions -@code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more -info. -@end table - -@node Bugs -@chapter Bugs -@cindex Bugs - -@noindent -If you encounter a bug in this package, or wish to suggest an -enhancement, then please use @kbd{M-x report-emacs-bug} to report it. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@node Command Index -@unnumbered Function Index -@printindex fn - -@node Key Index -@unnumbered Key Index -@printindex ky - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye diff --git a/doc/misc/doclicense.texi b/doc/misc/doclicense.texi deleted file mode 100644 index 9c3bbe56e91..00000000000 --- a/doc/misc/doclicense.texi +++ /dev/null @@ -1,505 +0,0 @@ -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, La@TeX{} input -format, SGML or XML using a publicly available -DTD, and standard-conforming simple HTML, -PostScript or PDF designed for human modification. Examples -of transparent image formats include PNG, XCF and -JPG@. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, SGML or -XML for which the DTD and/or processing tools are -not generally available, and the machine-generated HTML, -PostScript or PDF produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.''@: line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: diff --git a/doc/misc/ebrowse.texi b/doc/misc/ebrowse.texi deleted file mode 100644 index 9ff3e28e99d..00000000000 --- a/doc/misc/ebrowse.texi +++ /dev/null @@ -1,1418 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@comment %**start of header -@setfilename ../../info/ebrowse -@settitle A Class Browser for C++ -@documentencoding UTF-8 -@setchapternewpage odd -@syncodeindex fn cp -@comment %**end of header - -@copying -This file documents Ebrowse, a C++ class browser for GNU Emacs. - -Copyright @copyright{} 2000--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Ebrowse: (ebrowse). A C++ class browser for Emacs. -@end direntry - -@titlepage -@title Ebrowse User's Manual -@sp 4 -@subtitle Ebrowse/Emacs -@sp 5 -@author Gerd Moellmann -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Ebrowse - -You can browse C++ class hierarchies from within Emacs by using -Ebrowse. - -@insertcopying -@end ifnottex - -@menu -* Overview:: What is it and how does it work? -* Generating browser files:: How to process C++ source files -* Loading a Tree:: How to start browsing -* Tree Buffers:: Traversing class hierarchies -* Member Buffers:: Looking at member information -* Tags-like Functions:: Finding members from source files -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: An entry for each concept defined -@end menu - - - - -@node Overview -@chapter Introduction - -When working in software projects using C++, I frequently missed -software support for two things: - -@itemize @bullet -@item -When you get a new class library, or you have to work on source code you -haven't written yourself (or written sufficiently long ago), you need a -tool to let you navigate class hierarchies and investigate -features of the software. Without such a tool you often end up -@command{grep}ing through dozens or even hundreds of files. - -@item -Once you are productive, it would be nice to have a tool that knows your -sources and can help you while you are editing source code. Imagine to -be able to jump to the definition of an identifier while you are -editing, or something that can complete long identifier names because it -knows what identifiers are defined in your program@dots{}. -@end itemize - -The design of Ebrowse reflects these two needs. - -How does it work? - -@cindex parser for C++ sources -A fast parser written in C is used to process C++ source files. -The parser generates a data base containing information about classes, -members, global functions, defines, types etc.@: found in the sources. - -The second part of Ebrowse is a Lisp program. This program reads -the data base generated by the parser. It displays its contents in -various forms and allows you to perform operations on it, or do -something with the help of the knowledge contained in the data base. - -@cindex major modes, of Ebrowse buffers -@dfn{Navigational} use of Ebrowse is centered around two -types of buffers which define their own major modes: - -@cindex tree buffer -@dfn{Tree buffers} are used to view class hierarchies in tree form. -They allow you to quickly find classes, find or view class declarations, -perform operations like query replace on sets of your source files, and -finally tree buffers are used to produce the second buffer form---member -buffers. @xref{Tree Buffers}. - -@cindex member buffer -Members are displayed in @dfn{member buffers}. Ebrowse -distinguishes between six different types of members; each type is -displayed as a member list of its own: - -@itemize @bullet -@item -Instance member variables; - -@item -Instance member functions; - -@item -Static member variables; - -@item -Static member functions; - -@item -Friends/Defines. The list of defines is contained in the friends -list of the pseudo-class @samp{*Globals*}; - -@item -Types (@code{enum}s, and @code{typedef}s defined with class -scope). -@end itemize - -You can switch member buffers from one list to another, or to another -class. You can include inherited members in the display, you can set -filters that remove categories of members from the display, and most -importantly you can find or view member declarations and definitions -with a keystroke. @xref{Member Buffers}. - -These two buffer types and the commands they provide support the -navigational use of the browser. The second form resembles Emacs's Tags -package for C and other procedural languages. Ebrowse's commands of -this type are not confined to special buffers; they are most often used -while you are editing your source code. - -To list just a subset of what you can use the Tags part of Ebrowse for: - -@itemize @bullet -@item -Jump to the definition or declaration of an identifier in your source -code, with an electric position stack that lets you easily navigate -back and forth. - -@item -Complete identifiers in your source with a completion list containing -identifiers from your source code only. - -@item -Perform search and query replace operations over some or all of your -source files. - -@item -Show all identifiers matching a regular expression---and jump to one of -them, if you like. -@end itemize - - - - -@node Generating browser files -@chapter Processing Source Files - -@cindex @command{ebrowse}, the program -@cindex class data base creation -Before you can start browsing a class hierarchy, you must run the parser -@command{ebrowse} on your source files in order to generate a Lisp data -base describing your program. - -@cindex command line for @command{ebrowse} -The operation of @command{ebrowse} can be tailored with command line -options. Under normal circumstances it suffices to let the parser use -its default settings. If you want to do that, call it with a command -line like: - -@example -ebrowse *.h *.cc -@end example - -@noindent -or, if your shell doesn't allow all the file names to be specified on -the command line, - -@example -ebrowse --files=@var{file} -@end example - -@noindent -where @var{file} contains the names of the files to be parsed, one -per line. - -@findex --help -When invoked with option @samp{--help}, @command{ebrowse} prints a list of -available command line options. - -@menu -* Input files:: Specifying which files to parse -* Output file:: Changing the output file name -* Structs and unions:: Omitting @code{struct}s and @code{union}s -* Matching:: Setting regular expression lengths -* Verbosity:: Getting feedback for lengthy operations -@end menu - - - - -@comment name, next, prev, up -@node Input files -@section Specifying Input Files - -@table @samp -@cindex input files, for @command{ebrowse} -@item file -Each file name on the command line tells @command{ebrowse} to parse -that file. - -@cindex response files -@findex --files -@item --files=@var{file} -This command line switch specifies that @var{file} contains a list of -file names to parse. Each line in @var{file} must contain one file -name. More than one option of this kind is allowed. You might, for -instance, want to use one file for header files, and another for source -files. - -@cindex standard input, specifying input files -@item standard input -When @command{ebrowse} finds no file names on the command line, and no -@samp{--file} option is specified, it reads file names from standard -input. This is sometimes convenient when @command{ebrowse} is used as part -of a command pipe. - -@findex --search-path -@item --search-path=@var{paths} -This option lets you specify search paths for your input files. -@var{paths} is a list of directory names, separated from each other by a -either a colon or a semicolon, depending on the operating system. -@end table - -@cindex header files -@cindex friend functions -It is generally a good idea to specify input files so that header files -are parsed before source files. This facilitates the parser's work of -properly identifying friend functions of a class. - - - -@comment name, next, prev, up -@node Output file -@section Changing the Output File Name - -@table @samp -@cindex output file name -@findex --output-file -@cindex @file{BROWSE} file -@item --output-file=@var{file} -This option instructs @command{ebrowse} to generate a Lisp data base with -name @var{file}. By default, the data base is named @file{BROWSE}, and -is written in the directory in which @command{ebrowse} is invoked. - -If you regularly use data base names different from the default, you -might want to add this to your init file: - -@lisp -(add-to-list 'auto-mode-alist '(@var{NAME} . ebrowse-tree-mode)) -@end lisp - -@noindent -where @var{NAME} is the Lisp data base name you are using. - -@findex --append -@cindex appending output to class data base -@item --append -By default, each run of @command{ebrowse} erases the old contents of the -output file when writing to it. You can instruct @command{ebrowse} to -append its output to an existing file produced by @command{ebrowse} -with this command line option. -@end table - - - - -@comment name, next, prev, up -@node Structs and unions -@section Structs and Unions -@cindex structs -@cindex unions - -@table @samp -@findex --no-structs-or-unions -@item --no-structs-or-unions -This switch suppresses all classes in the data base declared as -@code{struct} or @code{union} in the output. - -This is mainly useful when you are converting an existing -C program to C++, and do not want to see the old C structs in a class -tree. -@end table - - - - -@comment name, next, prev, up -@node Matching -@section Regular Expressions - -@cindex regular expressions, recording -The parser @command{ebrowse} normally writes regular expressions to its -output file that help the Lisp part of Ebrowse to find functions, -variables etc.@: in their source files. - -You can instruct @command{ebrowse} to omit these regular expressions by -calling it with the command line switch @samp{--no-regexps}. - -When you do this, the Lisp part of Ebrowse tries to guess, from member -or class names, suitable regular expressions to locate that class or -member in source files. This works fine in most cases, but the -automatic generation of regular expressions can be too weak if unusual -coding styles are used. - -@table @samp -@findex --no-regexps -@item --no-regexps -This option turns off regular expression recording. - -@findex --min-regexp-length -@cindex minimum regexp length for recording -@item --min-regexp-length=@var{n} -The number @var{n} following this option specifies the minimum length of -the regular expressions recorded to match class and member declarations -and definitions. The default value is set at compilation time of -@command{ebrowse}. - -The smaller the minimum length, the higher the probability that -Ebrowse will find a wrong match. The larger the value, the -larger the output file and therefore the memory consumption once the -file is read from Emacs. - -@findex --max-regexp-length -@cindex maximum regexp length for recording -@item --max-regexp-length=@var{n} -The number following this option specifies the maximum length of the -regular expressions used to match class and member declarations and -definitions. The default value is set at compilation time of -@command{ebrowse}. - -The larger the maximum length, the higher the probability that the -browser will find a correct match, but the larger the value the larger -the output file and therefore the memory consumption once the data is -read. As a second effect, the larger the regular expression, the higher -the probability that it will no longer match after editing the file. -@end table - - - - -@node Verbosity -@section Verbose Mode -@cindex verbose operation - -@table @samp -@findex --verbose -@item --verbose -When this option is specified on the command line, @command{ebrowse} prints -a period for each file parsed, and it displays a @samp{+} for each -class written to the output file. - -@findex --very-verbose -@item --very-verbose -This option makes @command{ebrowse} print out the names of the files and -the names of the classes seen. -@end table - - - - -@node Loading a Tree -@chapter Starting to Browse -@cindex loading -@cindex browsing - -You start browsing a class hierarchy parsed by @command{ebrowse} by just -finding the @file{BROWSE} file with @kbd{C-x C-f}. - -An example of a tree buffer display is shown below. - -@example -| Collection -| IndexedCollection -| Array -| FixedArray -| Set -| Dictionary -@end example - -@cindex mouse highlight in tree buffers -When you run Emacs on a display which supports colors and the mouse, you -will notice that certain areas in the tree buffer are highlighted -when you move the mouse over them. This highlight marks mouse-sensitive -regions in the buffer. Please notice the help strings in the echo area -when the mouse moves over a sensitive region. - -@cindex context menu -A click with @kbd{Mouse-3} on a mouse-sensitive region opens a context -menu. In addition to this, each buffer also has a buffer-specific menu -that is opened with a click with @kbd{Mouse-3} somewhere in the buffer -where no highlight is displayed. - - - -@comment **************************************************************** -@comment *** -@comment *** TREE BUFFERS -@comment *** -@comment **************************************************************** - -@node Tree Buffers -@chapter Tree Buffers -@cindex tree buffer mode -@cindex class trees - -Class trees are displayed in @dfn{tree buffers} which install their own -major mode. Most Emacs keys work in tree buffers in the usual way, -e.g., you can move around in the buffer with the usual @kbd{C-f}, -@kbd{C-v} etc., or you can search with @kbd{C-s}. - -Tree-specific commands are bound to simple keystrokes, similar to -@code{Gnus}. You can take a look at the key bindings by entering -@kbd{?} which calls @code{M-x describe-mode} in both tree and member -buffers. - -@menu -* Source Display:: Viewing and finding a class declaration -* Member Display:: Showing members, switching to member buffers -* Go to Class:: Finding a class -* Quitting:: Discarding and burying the tree buffer -* File Name Display:: Showing file names in the tree -* Expanding and Collapsing:: Expanding and collapsing branches -* Tree Indentation:: Changing the tree indentation -* Killing Classes:: Removing class from the tree -* Saving a Tree:: Saving a modified tree -* Statistics:: Displaying class tree statistics -* Marking Classes:: Marking and unmarking classes -@end menu - - - -@node Source Display -@section Viewing and Finding Class Declarations -@cindex viewing, class -@cindex finding a class -@cindex class declaration - -You can view or find a class declaration when the cursor is on a class -name. - -@table @kbd -@item @key{SPC} -This command views the class declaration if the database -contains information about it. If you don't parse the entire source -you are working on, some classes will only be known to exist but the -location of their declarations and definitions will not be known. - -@item @key{RET} -Works like @kbd{SPC}, except that it finds the class -declaration rather than viewing it, so that it is ready for -editing. -@end table - -The same functionality is available from the menu opened with -@kbd{Mouse-3} on the class name. - - - - -@node Member Display -@section Displaying Members -@cindex @file{*Members*} buffer -@cindex @samp{*Globals*} -@cindex freezing a member buffer -@cindex member lists, in tree buffers - -Ebrowse distinguishes six different kinds of members, each of -which is displayed as a separate @dfn{member list}: instance variables, -instance functions, static variables, static functions, friend -functions, and types. - -Each of these lists can be displayed in a member buffer with a command -starting with @kbd{L} when the cursor is on a class name. By default, -there is only one member buffer named @dfn{*Members*} that is reused -each time you display a member list---this has proven to be more -practical than to clutter up the buffer list with dozens of member -buffers. - -If you want to display more than one member list at a time you can -@dfn{freeze} its member buffer. Freezing a member buffer prevents it -from being overwritten the next time you display a member list. You can -toggle this buffer status at any time. - -Every member list display command in the tree buffer can be used with a -prefix argument (@kbd{C-u}). Without a prefix argument, the command will -pop to a member buffer displaying the member list. With prefix argument, -the member buffer will additionally be @dfn{frozen}. - -@table @kbd -@cindex instance member variables, list -@item L v -This command displays the list of instance member variables. - -@cindex static variables, list -@item L V -Display the list of static variables. - -@cindex friend functions, list -@item L d -Display the list of friend functions. This list is used for defines if -you are viewing the class @samp{*Globals*} which is a place holder for -global symbols. - -@cindex member functions, list -@item L f -Display the list of member functions. - -@cindex static member functions, list -@item L F -Display the list of static member functions. - -@cindex types, list -@item L t -Display a list of types. -@end table - -These lists are also available from the class' context menu invoked with -@kbd{Mouse-3} on the class name. - - - - -@node Go to Class -@section Finding a Class -@cindex locate class -@cindex expanding branches -@cindex class location - -@table @kbd -@cindex search for class -@item / -This command reads a class name from the minibuffer with completion and -positions the cursor on the class in the class tree. - -If the branch of the class tree containing the class searched for is -currently collapsed, the class itself and all its base classes are -recursively made visible. (See also @ref{Expanding and -Collapsing}.) - -This function is also available from the tree buffer's context menu. - -@item n -Repeat the last search done with @kbd{/}. Each tree buffer has its own -local copy of the regular expression last searched in it. -@end table - - - - -@node Quitting -@section Burying a Tree Buffer -@cindex burying tree buffer - -@table @kbd -@item q -Is a synonym for @kbd{M-x bury-buffer}. -@end table - - - - -@node File Name Display -@section Displaying File Names - -@table @kbd -@cindex file names in tree buffers -@item T f -This command toggles the display of file names in a tree buffer. If -file name display is switched on, the names of the files containing the -class declaration are shown to the right of the class names. If the -file is not known, the string @samp{unknown} is displayed. - -This command is also provided in the tree buffer's context menu. - -@item s -Display file names for the current line, or for the number of lines -given by a prefix argument. -@end table - -Here is an example of a tree buffer with file names displayed. - -@example -| Collection (unknown) -| IndexedCollection (indexedcltn.h) -| Array (array.h) -| FixedArray (fixedarray.h) -| Set (set.h) -| Dictionary (dict.h) -@end example - - -@node Expanding and Collapsing -@section Expanding and Collapsing a Tree -@cindex expand tree branch -@cindex collapse tree branch -@cindex branches of class tree -@cindex class tree, collapse or expand - -You can expand and collapse parts of a tree to reduce the complexity of -large class hierarchies. Expanding or collapsing branches of a tree has -no impact on the functionality of other commands, like @kbd{/}. (See -also @ref{Go to Class}.) - -Collapsed branches are indicated with an ellipsis following the class -name like in the example below. - -@example -| Collection -| IndexedCollection... -| Set -| Dictionary -@end example - -@table @kbd -@item - -This command collapses the branch of the tree starting at the class the -cursor is on. - -@item + -This command expands the branch of the tree starting at the class the -cursor is on. Both commands for collapsing and expanding branches are -also available from the class' object menu. - -@item * -This command expands all collapsed branches in the tree. -@end table - - - - -@node Tree Indentation -@section Changing the Tree Indentation -@cindex tree indentation -@cindex indentation of the tree - -@table @kbd -@item T w -This command reads a new indentation width from the minibuffer and -redisplays the tree buffer with the new indentation It is also -available from the tree buffer's context menu. -@end table - - - - -@node Killing Classes -@section Removing Classes from the Tree -@cindex killing classes -@cindex class, remove from tree - -@table @kbd -@item C-k -This command removes the class the cursor is on and all its derived -classes from the tree. The user is asked for confirmation before the -deletion is actually performed. -@end table - - - - -@node Saving a Tree -@section Saving a Tree -@cindex save tree to a file -@cindex tree, save to a file -@cindex class tree, save to a file - -@table @kbd -@item C-x C-s -This command writes a class tree to the file from which it was read. -This is useful after classes have been deleted from a tree. - -@item C-x C-w -Writes the tree to a file whose name is read from the minibuffer. -@end table - - - - -@node Statistics -@section Statistics -@cindex statistics for a tree -@cindex tree statistics -@cindex class statistics - -@table @kbd -@item x -Display statistics for the tree, like number of classes in it, number of -member functions, etc. This command can also be found in the buffer's -context menu. -@end table - - - - -@node Marking Classes -@section Marking Classes -@cindex marking classes -@cindex operations on marked classes - -Classes can be marked for operations similar to the standard Emacs -commands @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} (see -also @xref{Tags-like Functions}.) - -@table @kbd -@cindex toggle mark -@item M t -Toggle the mark of the line point is in or for as many lines as given by -a prefix command. This command can also be found in the class' context -menu. - -@cindex unmark all -@item M a -Unmark all classes. With prefix argument @kbd{C-u}, mark all classes in -the tree. Since this command operates on the whole buffer, it can also be -found in the buffer's object menu. -@end table - -Marked classes are displayed with an @code{>} in column one of the tree -display, like in the following example - -@example -|> Collection -| IndexedCollection... -|> Set -| Dictionary -@end example - - - - -@c **************************************************************** -@c *** -@c *** MEMBER BUFFERS -@c *** -@c **************************************************************** - -@node Member Buffers -@chapter Member Buffers -@cindex members -@cindex member buffer mode - -@cindex class members, types -@cindex types of class members -@dfn{Member buffers} are used to operate on lists of members of a class. -Ebrowse distinguishes six kinds of lists: - -@itemize @bullet -@item -Instance variables (normal member variables); -@item -Instance functions (normal member functions); -@item -Static variables; -@item -Static member functions; -@item -Friend functions; -@item -Types (@code{enum}s and @code{typedef}s defined with class scope. -Nested classes will be shown in the class tree like normal classes. -@end itemize - -Like tree buffers, member buffers install their own major mode. Also -like in tree buffers, menus are provided for certain areas in the -buffer: members, classes, and the buffer itself. - -@menu -* Switching Member Lists:: Choosing which members to display -* Finding/Viewing:: Modifying source code -* Inherited Members:: Display of Inherited Members -* Searching Members:: Finding members in member buffer -* Switching to Tree:: Going back to the tree buffer -* Filters:: Selective member display -* Attributes:: Display of @code{virtual} etc. -* Long and Short Display:: Comprehensive and verbose display -* Regexp Display:: Showing matching regular expressions -* Switching Classes:: Displaying another class -* Killing/Burying:: Getting rid of the member buffer -* Column Width:: Display style -* Redisplay:: Redrawing the member list -* Getting Help:: How to get help for key bindings -@end menu - - - - -@node Switching Member Lists -@section Switching Member Lists -@cindex member lists, in member buffers -@cindex static members -@cindex friends -@cindex types -@cindex defines - -@table @kbd -@cindex next member list -@item L n -This command switches the member buffer display to the next member list. - -@cindex previous member list -@item L p -This command switches the member buffer display to the previous member -list. - -@item L f -Switch to the list of member functions. - -@cindex static -@item L F -Switch to the list of static member functions. - -@item L v -Switch to the list of member variables. - -@item L V -Switch to the list of static member variables. - -@item L d -Switch to the list of friends or defines. - -@item L t -Switch to the list of types. -@end table - -Both commands cycle through the member list. - -Most of the commands are also available from the member buffer's -context menu. - - - - -@node Finding/Viewing -@section Finding and Viewing Member Source -@cindex finding members, in member buffers -@cindex viewing members, in member buffers -@cindex member definitions, in member buffers -@cindex member declarations, in member buffers -@cindex definition of a member, in member buffers -@cindex declaration of a member, in member buffers - -@table @kbd -@item @key{RET} -This command finds the definition of the member the cursor is on. -Finding involves roughly the same as the standard Emacs tags facility -does---loading the file and searching for a regular expression matching -the member. - -@item f -This command finds the declaration of the member the cursor is on. - -@item @key{SPC} -This is the same command as @kbd{RET}, but views the member definition -instead of finding the member's source file. - -@item v -This is the same command as @kbd{f}, but views the member's declaration -instead of finding the file the declaration is in. -@end table - -You can install a hook function to perform actions after a member or -class declaration or definition has been found, or when it is not found. - -All the commands described above can also be found in the context menu -displayed when clicking @kbd{Mouse-2} on a member name. - - - - -@node Inherited Members -@section Display of Inherited Members -@cindex superclasses, members -@cindex base classes, members -@cindex inherited members - -@table @kbd -@item D b -This command toggles the display of inherited members in the member -buffer. This is also in the buffer's context menu. -@end table - - - - -@node Searching Members -@section Searching Members -@cindex searching members - -@table @kbd -@item G v -Position the cursor on a member whose name is read from the minibuffer; -only members shown in the current member buffer appear in the completion -list. - -@item G m -Like the above command, but all members for the current class appear in -the completion list. If necessary, the current member list is switched -to the one containing the member. - -With a prefix argument (@kbd{C-u}), all members in the class tree, -i.e., all members the browser knows about appear in the completion -list. The member display will be switched to the class and member list -containing the member. - -@item G n -Repeat the last member search. -@end table - -Look into the buffer's context menu for a convenient way to do this with -a mouse. - - - -@node Switching to Tree -@section Switching to Tree Buffer -@cindex tree buffer, switch to -@cindex buffer switching -@cindex switching buffers - -@table @kbd -@item @key{TAB} -Pop up the tree buffer to which the member buffer belongs. - -@item t -Do the same as @key{TAB} but also position the cursor on the class -displayed in the member buffer. -@end table - - - - -@node Filters -@section Filters -@cindex filters - -@table @kbd -@cindex @code{public} members -@item F a u -This command toggles the display of @code{public} members. The -@samp{a} stands for `access'. - -@cindex @code{protected} members -@item F a o -This command toggles the display of @code{protected} members. - -@cindex @code{private} members -@item F a i -This command toggles the display of @code{private} members. - -@cindex @code{virtual} members -@item F v -This command toggles the display of @code{virtual} members. - -@cindex @code{inline} members -@item F i -This command toggles the display of @code{inline} members. - -@cindex @code{const} members -@item F c -This command toggles the display of @code{const} members. - -@cindex pure virtual members -@item F p -This command toggles the display of pure virtual members. - -@cindex remove filters -@item F r -This command removes all filters. -@end table - -These commands are also found in the buffer's context menu. - - - - -@node Attributes -@section Displaying Member Attributes -@cindex attributes -@cindex member attribute display - -@table @kbd -@item D a -Toggle the display of member attributes (default is on). - -The nine member attributes Ebrowse knows about are displayed -as a list a single-characters flags enclosed in angle brackets in front -the of the member's name. A @samp{-} at a given position means that -the attribute is false. The list of attributes from left to right is - -@table @samp -@cindex @code{template} attribute -@item T -The member is a template. - -@cindex @code{extern "C"} attribute -@item C -The member is declared @code{extern "C"}. - -@cindex @code{virtual} attribute -@item v -Means the member is declared @code{virtual}. - -@cindex @code{inline} -@item i -The member is declared @code{inline}. - -@cindex @code{const} attribute -@item c -The member is @code{const}. - -@cindex pure virtual function attribute -@item 0 -The member is a pure virtual function. - -@cindex @code{mutable} attribute -@item m -The member is declared @code{mutable}. - -@cindex @code{explicit} attribute -@item e -The member is declared @code{explicit}. - -@item t -The member is a function with a throw list. -@end table -@end table - -This command is also in the buffer's context menu. - - - -@node Long and Short Display -@section Long and Short Member Display -@cindex display form -@cindex long display -@cindex short display - -@table @kbd -@item D l -This command toggles the member buffer between short and long display -form. The short display form displays member names, only: - -@example -| isEmpty contains hasMember create -| storeSize hash isEqual restoreGuts -| saveGuts -@end example - -The long display shows one member per line with member name and regular -expressions matching the member (if known): - -@example -| isEmpty Bool isEmpty () const... -| hash unsigned hash () const... -| isEqual int isEqual (... -@end example - -Regular expressions will only be displayed when the Lisp database has -not been produced with the @command{ebrowse} option @samp{--no-regexps}. -@xref{Matching, --no-regexps, Regular Expressions}. -@end table - - - - -@node Regexp Display -@section Display of Regular Expressions -@cindex regular expression display - -@table @kbd -@item D r -This command toggles the long display form from displaying the regular -expressions matching the member declarations to those expressions -matching member definitions. -@end table - -Regular expressions will only be displayed when the Lisp database has -not been produced with the @command{ebrowse} option @samp{--no-regexps}, -see @ref{Matching, --no-regexps, Regular Expressions}. - - - - -@node Switching Classes -@section Displaying Another Class -@cindex base class, display -@cindex derived class, display -@cindex superclass, display -@cindex subclass, display -@cindex class display - -@table @kbd -@item C c -This command lets you switch the member buffer to another class. It -reads the name of the new class from the minibuffer with completion. - -@item C b -This is the same command as @kbd{C c} but restricts the classes shown in -the completion list to immediate base classes, only. If only one base -class exists, this one is immediately shown in the minibuffer. - -@item C d -Same as @kbd{C b}, but for derived classes. - -@item C p -Switch to the previous class in the class hierarchy on the same level as -the class currently displayed. - -@item C n -Switch to the next sibling of the class in the class tree. -@end table - - - - -@node Killing/Burying -@section Burying a Member Buffer -@cindex burying member buffers - -@table @kbd -@item q -This command is a synonym for @kbd{M-x bury-buffer}. -@end table - - - - -@node Column Width -@section Setting the Column Width -@cindex column width -@cindex member indentation -@cindex indentation, member - -@table @kbd -@item D w -This command sets the column width depending on the display form used -(long or short display). -@end table - - - - -@node Redisplay -@section Forced Redisplay -@cindex redisplay of member buffers - -@table @kbd -@item C-l -This command forces a redisplay of the member buffer. If the width -of the window displaying the member buffer is changed this command -redraws the member list with the appropriate column widths and number of -columns. -@end table - - - - -@node Getting Help -@section Getting Help -@cindex help - -@table @kbd -@item ? -This key is bound to @code{describe-mode}. -@end table - - - - -@comment ************************************************************** -@comment *** TAGS LIKE FUNCTIONS -@comment ************************************************************** - -@node Tags-like Functions -@chapter Tags-like Functions - -Ebrowse provides tags functions similar to those of the standard -Emacs Tags facility, but better suited to the needs of C++ programmers. - -@menu -* Finding and Viewing:: Going to a member declaration/definition -* Position Stack:: Moving to previous locations -* Search & Replace:: Searching and replacing over class tree files -* Members in Files:: Listing all members in a given file -* Apropos:: Listing members matching a regular expression -* Symbol Completion:: Completing names while editing -* Member Buffer Display:: Quickly display a member buffer for some - identifier -@end menu - - - -@node Finding and Viewing -@section Finding and Viewing Members -@cindex finding class member, in C++ source -@cindex viewing class member, in C++ source -@cindex tags -@cindex member definition, finding, in C++ source -@cindex member declaration, finding, in C++ source - -The functions in this section are similar to those described in -@ref{Source Display}, and also in @ref{Finding/Viewing}, except that -they work in a C++ source buffer, not in member and tree buffers created -by Ebrowse. - -@table @kbd -@item C-c C-m f -Find the definition of the member around point. If you invoke this -function with a prefix argument, the declaration is searched. - -If more than one class contains a member with the given name you can -select the class with completion. If there is a scope declaration in -front of the member name, this class name is used as initial input for -the completion. - -@item C-c C-m F -Find the declaration of the member around point. - -@item C-c C-m v -View the definition of the member around point. - -@item C-c C-m V -View the declaration of the member around point. - -@item C-c C-m 4 f -Find a member's definition in another window. - -@item C-c C-m 4 F -Find a member's declaration in another window. - -@item C-c C-m 4 v -View a member's definition in another window. - -@item C-c C-m 4 V -View a member's declaration in another window. - -@item C-c C-m 5 f -Find a member's definition in another frame. - -@item C-c C-m 5 F -Find a member's declaration in another frame. - -@item C-c C-m 5 v -View a member's definition in another frame. - -@item C-c C-m 5 V -View a member's declaration in another frame. -@end table - - - -@node Position Stack -@section The Position Stack -@cindex position stack - -When jumping to a member declaration or definition with one of -Ebrowse's commands, the position from where you performed the -jump and the position where you jumped to are recorded in a -@dfn{position stack}. There are several ways in which you can quickly -move to positions in the stack: - -@table @kbd -@cindex return to original position -@item C-c C-m - -This command sets point to the previous position in the position stack. -Directly after you performed a jump, this will put you back to the -position where you came from. - -The stack is not popped, i.e., you can always switch back and forth -between positions in the stack. To avoid letting the stack grow to -infinite size there is a maximum number of positions defined. When this -number is reached, older positions are discarded when new positions are -pushed on the stack. - -@item C-c C-m + -This command moves forward in the position stack, setting point to -the next position stored in the position stack. - -@item C-c C-m p -Displays an electric buffer showing all positions saved in the stack. -You can select a position by pressing @kbd{SPC} in a line. You can -view a position with @kbd{v}. -@end table - - - - -@node Search & Replace -@section Searching and Replacing -@cindex searching multiple C++ files -@cindex replacing in multiple C++ files -@cindex restart tags-operation - -Ebrowse allows you to perform operations on all or a subset of the files -mentioned in a class tree. When you invoke one of the following -functions and more than one class tree is loaded, you must choose a -class tree to use from an electric tree menu. If the selected tree -contains marked classes, the following commands operate on the files -mentioned in the marked classes only. Otherwise all files in the class -tree are used. - -@table @kbd -@item C-c C-m s -This function performs a regular expression search in the chosen set of -files. - -@item C-c C-m u -This command performs a search for calls of a given member which is -selected in the usual way with completion. - -@item C-c C-m % -Perform a query replace over the set of files. - -@item C-c C-m , -All three operations above stop when finding a match. You can restart -the operation with this command. - -@item C-c C-m n -This restarts the last tags operation with the next file in the list. -@end table - - - - -@node Members in Files -@section Members in Files -@cindex files -@cindex members in file, listing -@cindex list class members in a file -@cindex file, members - -The command @kbd{C-c C-m l}, lists all members in a given file. The file -name is read from the minibuffer with completion. - - - - -@node Apropos -@section Member Apropos -@cindex apropos on class members -@cindex members, matching regexp - -The command @kbd{C-c C-m a} can be used to display all members matching a -given regular expression. This command can be very useful if you -remember only part of a member name, and not its beginning. - -A special buffer is popped up containing all identifiers matching the -regular expression, and what kind of symbol it is (e.g., a member -function, or a type). You can then switch to this buffer, and use the -command @kbd{C-c C-m f}, for example, to jump to a specific member. - - - - -@node Symbol Completion -@section Symbol Completion -@cindex completion -@cindex symbol completion - -The command @kbd{C-c C-m @key{TAB}} completes the symbol in front of point. - - - - -@node Member Buffer Display -@section Quick Member Display -@cindex member buffer, for member at point - -You can quickly display a member buffer containing the member the cursor -in on with the command @kbd{C-c C-m m}. - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@bye diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi deleted file mode 100644 index 89e576b8c25..00000000000 --- a/doc/misc/ede.texi +++ /dev/null @@ -1,4283 +0,0 @@ -\input texinfo -@setfilename ../../info/ede -@settitle Emacs Development Environment -@documentencoding UTF-8 - -@copying -This file describes EDE, the Emacs Development Environment. - -Copyright @copyright{} 1998--2001, 2004--2005, 2008--2014 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* EDE: (ede). The Emacs Development Environment. -@end direntry - -@titlepage -@center @titlefont{EDE (The Emacs Development Environment)} -@sp 4 -@center by Eric Ludlam -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage -@page - -@macro cedet{} -@i{CEDET} -@end macro - -@macro semantic{} -@i{Semantic} -@end macro - -@macro srecode{} -@i{SRecode} -@end macro - -@macro eieio{} -@i{EIEIO} -@end macro - -@macro ede{} -@i{EDE} -@end macro - -@macro cogre{} -@i{COGRE} -@end macro - -@macro speedbar{} -@i{Speedbar} -@end macro - -@contents - -@node Top, EDE Project Concepts, (dir), (dir) -@top EDE -@comment node-name, next, previous, up - -@ede{} is the Emacs Development Environment: an Emacs extension that -simplifies building and debugging programs in Emacs. It attempts to -emulate a typical IDE (Integrated Development Environment). @ede{} -can manage or create your makefiles and other building environment -duties, allowing you to concentrate on writing code rather than -support files. It aims to make it much easier for new programmers to -learn and adopt GNU ways of doing things. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* EDE Project Concepts:: @ede{} Project Concepts -* EDE Mode:: Turning on @ede{} mode. -* Quick Start:: Quick start to building a project. -* Creating a project:: Creating a project. -* Modifying your project:: Adding and removing files and targets. -* Building and Debugging:: Initiating a build or debug session. -* Miscellaneous commands:: Other project related commands. -* Extending EDE:: Programming and extending @ede{}. -* GNU Free Documentation License:: The license for this documentation. -@end menu - -@node EDE Project Concepts, EDE Mode, Top, Top -@chapter @ede{} Project Concepts - -@ede{} is a generic interface for managing projects. It specifies a -single set of menus and keybindings, while supporting multiple ways to -express a project via a build system. - -In the subsequent chapters, we will describe the different project -types (@pxref{Creating a project}), as well as the commands to build -and debug projects (@pxref{Building and Debugging}). - -In @ede{}, a project hierarchy matches a directory hierarchy. The -project's topmost directory is called the @dfn{project root}, and its -subdirectories are @dfn{subprojects}. - -Each project can contain multiple @dfn{targets}. A target, at the -simplest level, is a named collection of files within a project. A -target can specify two different types of information: - -@enumerate -@item -A collection of files to be added to a distribution (e.g., a tarball -that you intend to distribute to others). - -@item -A collection of files that can be built into something else (e.g., a -program or compiled documentation). -@end enumerate - -Lastly, @ede{} provides a way for other tools to easily learn file -associations. For example, a program might need to restrict some sort -of search to files in a single target, or to discover the location of -documentation or interface files. @ede{} can provide this -information. - -@node EDE Mode, Quick Start, EDE Project Concepts, Top -@chapter @ede{} Mode - -@ede{} is implemented as a minor mode, which augments other modes such -as C mode, and Texinfo mode. You can enable @ede{} for all buffers by -running the command @code{global-ede-mode}, or by putting this in your -init file: - -@example -(global-ede-mode t) -@end example - -Activating @ede{} adds a menu named @samp{Development} to the menu -bar. This menu provides several menu items for high-level @ede{} -commands. These menu items, and their corresponding keybindings, are -independent of the type of project you are actually working on. - -@node Quick Start, Creating a project, EDE Mode, Top -@chapter Quick Start - -Once you have @ede{} enabled, you can create a project. This chapter -provides an example C++ project that will create Automake files for -compilation. - -@section Step 1: Create root directory - -First, lets create a directory for our project. For this example, -we'll start with something in @file{/tmp}. - -@example -C-x C-f /tmp/myproject/README RET -M-x make-directory RET RET -@end example - -Now put some plain text in your README file to start. - -Now, lets create the project: - -@example -M-x ede-new RET Automake RET myproject RET -@end example - - -Nothing visible happened, but if you use @code{dired} to look at the -directory, you should see this: - -@example - /tmp/myproject: - total used in directory 32 available 166643476 - drwxr-xr-x 2 zappo users 4096 2012-02-23 22:10 . - drwxrwxrwt 73 root root 20480 2012-02-23 22:10 .. - -rw-r--r-- 1 zappo users 195 2012-02-23 22:10 Project.ede - -rw-r--r-- 1 zappo users 10 2012-02-23 22:09 README -@end example - -@section Step 2: Create Subdirectories and Files - -We'll make a more complex project, so use dired to create some more -directories using the @kbd{+} key, and typing in new directories: - -@example -+ include RET -+ src RET -@end example - -Now I'll short-cut in this tutorial. Create the following files: - -@file{include/myproj.hh} -@example -/** myproj.hh --- - */ - -#ifndef myproj_hh -#define myproj_hh 1 - -#define IMPORTANT_MACRO 1 - -int my_lib_function(); - -#endif // myproj_hh -@end example - - -@file{src/main.cpp} -@example -/** main.cpp --- - */ - -#include -#include "myproj.hh" - -int main() @{ - -@} - -#ifdef IMPORTANT_MACRO -int my_fcn() @{ - -@} -#endif -@end example - -@file{src/mylib.cpp} -@example -/** mylib.cpp --- - * - * Shared Library to build - */ - -int my_lib_function() @{ - -@} -@end example - -@section Step 3: Create subprojects - -@ede{} needs subdirectories to also have projects in them. You can -now create those projects. - -With @file{main.cpp} as your current buffer, type: - -@example -M-x ede-new RET Automake RET src RET -@end example - -and in @file{myproj.hh} as your current buffer, type: - -@example -M-x ede-new RET Automake RET include RET -@end example - -These steps effectively only create the Project.ede file in which you -will start adding targets. - -@section Step 4: Create targets - -In order to build a program, you must have targets in your @ede{} -Projects. You can create targets either from a buffer, or from a -@code{dired} directory buffer. - -Note: If for some reason a directory list buffer, or file does not have the -@samp{Project} menu item, or if @ede{} keybindings don't work, just -use @kbd{M-x revert-buffer RET} to force a refresh. Sometimes -creating a new project doesn't restart buffers correctly. - -Lets start with the header file. In @file{include/myproj.hh}, you -could use the menu, but we will now start using the @ede{} command prefix -which is @kbd{C-c .}. - -@example -C-c . t includes RET miscellaneous RET y -@end example - - -This creates a misc target for holding your includes, and then adds -myproj.hh to the target. Automake (the tool) has better ways to do -this, but for this project, it is sufficient. - -Next, visit the @file{src} directory using dired. There should be a -@samp{Project} menu. You can create a new target with - -@example -. t myprogram RET program RET -@end example - -Note that @kbd{. t} is a command for creating a target. This command -is also in the menu. This will create a target that will build a -program. If you want, visit @file{Project.ede} to see the structure -built so far. - -Next, place the cursor on @file{main.cpp}, and use @kbd{. a} to add -that file to your target. - -@example -. a myprogram RET -@end example - -Note that these prompts often have completion, so you can just press -@kbd{TAB} to complete the name @file{myprogram}. - -If you had many files to add to the same target, you could mark them -all in your dired buffer, and add them all at the same time. - -Next, do the same for the library by placing the cursor on @file{mylib.cpp}. - -@example -. t mylib RET sharedobject RET -. a mylib RET -@end example - -@section Step 5: Compile, and fail - -Next, we'll try to compile the project, but we aren't done yet, so it -won't work right away. - -Visit @file{/tmp/myproject/Project.ede}. We're starting here because -we don't have any program files in this directory yet. Now we can use -the compile command: - -@example -C-c . C -@end example - -Because this is the very first time, it will create a bunch of files -for you that are required by Automake. It will then use automake to -build the support infrastructure it needs. This step is skipped if -you choose just a @file{Makefile} build system. - -After the Automake init, it runs compile. You will immediately -discover the error in main.cpp can't find @file{myproj.hh}. We need -to go fix this. - -@section Step 6: Customizing your project - -To fix the failed compile, we need to add -@file{/tmp/myproject/include} to the include path. - -Visit @file{main.cpp}. - -@example -M-x customize-project RET -@end example - -Select the @samp{[Settings]} subgroup of options. Under -@samp{Variable :} click @samp{[INS]}. At this point, you need to be -somewhat savvy with Automake. Add a variable named @samp{CPPFLAGS}, -and set the value to @samp{../include}. - -You should see something like this: - -@example -Variables : -[INS] [DEL] Cons-cell: - Name: AM_CPPFLAGS - Value: -I../include -[INS] -Variables to set in this Makefile. -@end example - -Click @samp{[Apply]}. Feel free to visit @file{Project.ede} to see -how it changed the config file. - -Compile the whole project again with @kbd{C-c . C} from -@file{main.cpp}. It should now compile. - -@section Step 7: Shared library dependency - -Note: Supporting shared libraries for Automake in this way is easy, -but doing so from a project of type Makefile is a bit tricky. If you -are creating shared libraries too, stick to Automake projects. - -Next, lets add a dependency from @file{main.cpp} on our shared -library. To do that, update main like this: - -@example -int main() @{ - - my_lib_function(); - -@} -@end example - -Now compile with: - -@example -C-c . c -@end example - -where the lower case @kbd{c} compiles just that target. You should -see an error. - -This time, we need to add a dependency from @file{main.cpp} on our shared -library. To do that, we need to customize our target instead of the -project. This is because variables such as the include path are -treated globally, whereas dependencies for a target are target specific. - -@example -M-x customize-target RET -@end example - -On the first page, you will see an Ldlibs-local section. Add mylib to -it by first clicking @samp{[INS]}, and they adding the library. It -should look like this: - -@example -Ldlibs-Local : -[INS] [DEL] Local Library: libmylib.la -[INS] -Libraries that are part of this project. [Hide Rest] -The full path to these libraries should be specified, such as: -../lib/libMylib.la or ../ar/myArchive.a -@end example - -You will also see other variables for library related flags and system -libraries if you need them. Click @samp{[Accept]}, and from -@file{main.cpp}, again compile the whole project to force all -dependent elements to compile: - -@example -C-c . C -@end example - -@section Step 8: Run your program - -You can run your program directly from @ede{}. - -@example -C-c . R RET RET -@end example - -If your program takes command line arguments, you can type them in -when it offers the command line you want to use to run your program. - -@node Creating a project, Modifying your project, Quick Start, Top -@chapter Creating a project - -To create a new project, first visit a file that you want to include -in that project. If you have a hierarchy of directories, first visit -a file in the topmost directory. From this buffer, type @kbd{M-x -ede-new}, or click on the @samp{Create Project} item in the -@samp{Development} menu. - -The @command{ede-new} command prompts for the type of project you -would like to create. Each project type has its own benefits or -language specific enhancements. Not all projects that @ede{} supports -also allow creating a new project. Projects such as @code{emacs} -or @code{linux} are designed to recognize existing projects only. -Project types such as @samp{Make} and @samp{Automake} do support -creating new project types with @command{ede-new}. - -@itemize -@item -For the @samp{Make} project type, @ede{} creates a @dfn{project file}, -called @file{Project.ede}, in each project directory. Information -about the project is stored in this file. This project autogenerates -a @file{Makefile}. - -@item -For the @samp{Automake} project type, @ede{} creates a -@file{Project.ede} project file similar to a @samp{Make} project. -Unlike a @samp{Make} project, this project autogenerates a -@file{Makefile.am} file. @ede{} handles the Automake bootstrapping -routines, which import and maintain a @file{configure.am} script and -other required files. -@end itemize - -A subproject is merely a project in a subdirectory of another project. -You can create a subproject by using the @command{ede-new} command (or -the @samp{Create Project} menu item), while visiting a buffer in a -subdirectory of the project root. This new project is automatically -added to the parent project, and will be automatically loaded when -@ede{} reads the parent project. - -When using a project command that involves a makefile, @ede{} uses -the top-most project's makefile as a starting place for the build. How -the toplevel project handles subprojects in the build process is -dependent on that project's type. - -@node Modifying your project, Building and Debugging, Creating a project, Top -@chapter Modifying your project - -In this chapter, we describe the generic features for manipulating -projects, including the targets and files within them. Subsequent -chapters, which describe specific project types, will provide more -detailed information about exactly what these features do. - -@menu -* Add/Remove target:: -* Add/Remove files:: -* Customize Features:: -* Project Local Variables:: -* EDE Project Features:: -@end menu - -@node Add/Remove target, Add/Remove files, Modifying your project, Modifying your project -@section Add/Remove target - -To create a new target, type @kbd{C-c . t} (@code{ede-new-target}) or -use the @samp{Add Target} menu item in the @samp{Project Options} -submenu. This prompts for a target name, and adds the current buffer -to that target. - -The @command{ede-new-target} command also prompts for a @dfn{target -type}. Each target type has its own build process and class of files -that it will accept. - -To remove a target from the project, type @kbd{M-x ede-delete-target}, -or use the @samp{Remove Target} menu item in the @samp{Project -Options} submenu. - -@node Add/Remove files, Customize Features, Add/Remove target, Modifying your project -@section Add/Remove files - -To add the current file to an existing target, type @kbd{C-c . a} -(@code{ede-add-file}), or use the @samp{Add File} menu item in the -@samp{Target Options} submenu. - -You can add a file to more than one target; this is OK. - -To remove the current file from a target, type @kbd{C-c . d} -(@code{ede-remove-file}), or use the @samp{Remove File} menu item -in the @samp{Target Options} submenu. If the file belongs to multiple -targets, this command prompts for each target it could be removed -from. - -While working in a project, if you visit a file that is not part of an -existing target, @ede{} automatically prompts for a target. If you do -not wish to add the file to any target, you can choose @samp{none}. -You can customize this behavior with the variable -@command{ede-auto-add-method}. - -@node Customize Features, Project Local Variables, Add/Remove files, Modifying your project -@section Customize Features - -A project, and its targets, are objects using the @samp{EIEIO} object -system. @xref{Top,,,eieio,EIEIO manual}. These objects have data -fields containing important information related to your work. - -If the high-level functions aren't enough, you can tweak all -user-customizable fields at any time by running the command -@command{customize-project} or @command{customize-target}. This loads -the current project or target into a customization buffer, where you -can tweak individual slots. This is usually necessary for complex -projects. - -Some project modes do not have a project file, but directly read a -Makefile or other existing file. Instead of directly editing the -object, you can edit the file by typing @kbd{C-c . e} -(@code{ede-edit-file-target}). You should ``rescan'' the project -afterwards (@pxref{Miscellaneous commands}). - -@node Project Local Variables, EDE Project Features, Customize Features, Modifying your project -@section Project Local Variables - -EDE projects can store and manager project local variables. The -variables are stored in the project, and will be restored when a -project reloads. - -Projects which are not stored on disk WILL NOT restore your project -local variables later. - -You can use @ref{Customize Features} to of the project to edit the -project local variables. They are under the 'Settings' group as -``Project Local Variables''. - -You can also use @kbd{M-x ede-set} to set a new variable local in the -mini buffer. - -In multi-level projects such as Automake and Make generating projects, -project local variables are installed from both the TOP most project, -and the local directory's project. In that way, you can have some -variables across your whole project, and some specific to a -subdirectory. - -You can use project local variables to set any Emacs variable so that -buffers belonging to different projects can have different settings. - -NOTE: When you use project-local variables with @ref{ede-cpp-root}, -the format is an association list. For example: - -@example -(ede-cpp-root-project "SOMENAME" - :file "/dir/to/some/file" - :local-variables - '((grep-command . "grep -nHi -e ") - (compile-command . "make -f MyCustomMakefile all"))) -@end example - -@node EDE Project Features, , Project Local Variables, Modifying your project -@section EDE Project Features - -This section details user facing features of an @ede{} @samp{Make} -style project. An @samp{Automake} project has similar options (but a -direct Automake project does not). - -To modify any of the specific features mentioned here, you need to -customize the project or target with @command{customize-project} or -@command{customize-target}. - -When you are customizing, you are directly manipulating slot values in -@eieio{} objects. @xref{Extending EDE}, if you are interested in -additional details. - -@menu -* Changing Compilers and Flags:: -* Configurations:: -@end menu - -@node Changing Compilers and Flags, Configurations, EDE Project Features, EDE Project Features -@subsection Changing Compilers and Flags - -Targets that build stuff need compilers. To change compilers, you -need to customize the desired target. - -In the @samp{[Make]} section, you can choose a new compiler or linker -from the list. If a linker you need is not available, you will need -to create a new one. @xref{Compiler and Linker objects}. - -If an existing compiler or linker is close, but you need to modify -some flag set such as adding an include path you will need to add a -configuration variable. - -To start, you should create the basic setup, and construct a makefile -with @command{ede-proj-regenerate}. Look in the @file{Makefile} to -see what commands are inserted. Once you have determined the variable -you need to modify, you can add a configuration for it. -@xref{Configurations}. - -@node Configurations, , Changing Compilers and Flags, EDE Project Features -@subsection Configurations - -Configurations specify different ways to build a project. For -example, you may configure a project to be in ``debug'' mode, or -perhaps in ``release'' mode. - -The project, and each target type all have a slot named -@code{configuration-variables}. To add new variables to a -configuration find this slot in the custom buffer, and insert a new -configuration. Name it either ``debug'' or ``release'', then insert -some number of name/value pairs to it. - -You can have any number of valid configurations too. To add a new -configuration, customize your project. Work in the @samp{[Settings]} -block for ``configurations''. Add a new named configuration here. - -To switch between different active configurations, modify the -``configuration default'' slot. - -@node Building and Debugging, Miscellaneous commands, Modifying your project, Top -@chapter Building and Debugging - -@ede{} provides the following ``project-aware'' compilation and -debugging commands: - -@table @kbd -@item C-c . c -Compile the current target (@code{ede-compile-target}). -@item C-c . C -Compile the entire project (@code{ede-compile-project}). -@item c-c . D -Debug the current target (@code{ede-debug-target}). -@item M-x ede-make-dist -Build a distribution file for your project. -@end table - -These commands are also available from the @samp{Development} menu. - -@node Miscellaneous commands, Extending EDE, Building and Debugging, Top -@chapter Miscellaneous commands - -If you opt to go in and edit @ede{} project files directly---for -instance, by using @kbd{C-c . e} (@pxref{Customize Features})---you -must then ``rescan'' the project files to update the internal data -structures. To rescan the current project, type @kbd{C-c . g} -(@code{ede-rescan-toplevel}). - -@ede{} can help you find files in your project, via the command -@kbd{C-c . f} (@code{ede-find-file}). This prompts for a file name; -you need not specify the directory. EDE then tries to visit a file -with that name somewhere in your project. - -@ede{} can use external tools to help with file finding. To do this, -customize @code{ede-locate-setup-options}. - -@defvar ede-locate-setup-options -@anchor{ede-locate-setup-options} -List of locate objects to try out by default. -Listed in order of preference. If the first item cannot be used in -a particular project, then the next one is tried. -It is always assumed that @dfn{ede-locate-base} is at end of the list. -@end defvar - -@ede{} also provides a project display mode for the speedbar -(@pxref{Speedbar,,,emacs,GNU Emacs Manual}). This allows you to view -your source files as they are structured in your project: as a -hierarchical tree, grouped according to target. - -To activate the speedbar in this mode, type @kbd{C-c . s} -(@code{ede-speedbar}). - -@menu -* Make and Automake projects:: Project types of @samp{ede-project} -* Automake direct projects:: Project interface on hand-written automake files. -* Simple projects:: Projects @ede{} doesn't manage. -@end menu - -@node Make and Automake projects, Automake direct projects, Miscellaneous commands, Miscellaneous commands -@section Make and Automake projects - -A project of @samp{ede-project} type creates a file called -@file{Project.ede} in every project directory. This is used to track -your configuration information. If you configure this project to be -in @samp{Makefile} mode, then this project will autogenerate a -@file{Makefile}. If you configure it in @samp{Automake} mode a -@file{Makefile.am} file will be created. The automake bootstrapping -routines will also import and maintain a configure.am script and a -host of other files required by Automake. - -@node Automake direct projects, Simple projects, Make and Automake projects, Miscellaneous commands -@section Automake direct projects - -The project type that reads @file{Makefile.am} directly is derived -from the sources of the original @file{project-am.el} mode that was -distributed independently. This mode eventually became @ede{}. The -@samp{project-am} project will read existing automake files, but will -not generate them automatically, or create new ones. As such, it is -useful as a browsing tool, or as maintenance in managing file lists. - -@node Simple projects, , Automake direct projects, Miscellaneous commands -@section Simple Projects - -There is a wide array of simple projects. In this case a simple -project is one that detects, or is directed to identify a directory as -belonging to a project, but doesn't provide many features of a typical -@ede{} project. Having the project however allows tools such as -@semantic{} to find sources and perform project level completions. - - -@menu -* ede-cpp-root:: This project marks the root of a C/C++ code project. -* ede-emacs:: A project for working with Emacs. -* ede-linux:: A project for working with Linux kernels. -* ede-generic-project:: A project type for wrapping build systems with EDE. -* Custom Locate:: Customizing how to locate files in a simple project -@end menu - -@node ede-cpp-root, ede-emacs, Simple projects, Simple projects -@subsection ede-cpp-root - -The @code{ede-cpp-root} project type allows you to create a single -object with no save-file in your @file{.emacs} file. It allows @ede{} -to provide the @semantic{} package with the ability to find header -files quickly. - -The @code{ede-cpp-root} class knows a few things about C++ projects, -such as the prevalence of "include" directories, and typical -file-layout stuff. If this isn't sufficient, you can subclass -@code{ede-cpp-root-project} and add your own tweaks in just a few -lines. See the end of this file for an example. - -In the most basic case, add this to your @file{.emacs} file, modifying -appropriate bits as needed. - -@example -(ede-cpp-root-project "SOMENAME" :file "/dir/to/some/file") -@end example - -Replace @var{SOMENAME} with whatever name you want, and the filename -to an actual file at the root of your project. It might be a -Makefile, a README file. Whatever. It doesn't matter. It's just a -key to hang the rest of @ede{} off of. - -The most likely reason to create this project, is to speed up -searching for includes files, or to simplify bootstrapping @semantic{}'s -ability to find files without much user interaction. In conjunction -with @semantic{} completion, having a short include path is key. You can -override the default include path and system include path like this: - -@example -(ede-cpp-root-project "NAME" :file "FILENAME" - :include-path '( "/include" "../include" "/c/include" ) - :system-include-path '( "/usr/include/c++/3.2.2/" ) - :compile-command "make compile" - :spp-table '( ("MOOSE" . "") - ("CONST" . "const") ) ) -@end example - - In this case each item in the include path list is searched. If the -directory starts with "/", then that expands to the project root -directory. If a directory does not start with "/", then it is -relative to the default-directory of the current buffer when the file -name is expanded. - - The include path only affects C/C++ header files. Use the slot -@code{:header-match-regexp} to change it. - -The @code{:system-include-path} allows you to specify full directory -names to include directories where system header files can be found. -These will be applied to files in this project only. - -With @code{:compile-command} you can provide a command which should be -run when calling @code{ede-compile-project}. - -The @code{:spp-table} provides a list of project specific #define -style macros that are unique to this project, passed in to the -compiler on the command line, or are in special headers. -See the @code{semantic-lex-c-preprocessor-symbol-map} for more -on how to format this entry. - -If there is a single file in your project, you can instead set the -@code{:spp-files} to a list of file names relative to the root of your -project. Specifying this is like setting the variable -@code{semantic-lex-c-preprocessor-symbol-file} in semantic. - -If you want to override the file-finding tool with your own -function you can do this: - -@example -(ede-cpp-root-project "NAME" :file "FILENAME" :locate-fcn 'MYFCN) -@end example - -Where @var{MYFCN} is a symbol for a function. The locate function can -be used in place of @code{ede-expand-filename} so you can quickly -customize your custom target to use specialized local routines instead -of the default @ede{} routines. The function symbol must take two -arguments: - -@table @var -@item NAME -The name of the file to find. -@item DIR -The directory root for this cpp-root project. -@end table - -When creating a project with @code{ede-cpp-root}, you can get -additional configurations via @ref{Project Local Variables}. Be aware -that the format for project local variables is an association list. -You cannot use @kbd{M-x ede-set} and have your project local variables -persist between sessions. - -If the cpp-root project style is right for you, but you want a dynamic -loader, instead of hard-coding path name values in your @file{.emacs}, you -can do that too, but you will need to write some lisp code. - -To do that, you need to add an entry to the -@code{ede-project-class-files} list, and also provide two functions to -teach @ede{} how to load your project pattern - -It would look like this: - -@example -(defun MY-FILE-FOR-DIR (&optional dir) - "Return a full file name to the project file stored in DIR." - - ) - -(defun MY-ROOT-FCN () - "Return the root fcn for `default-directory'" - ;; You might be able to use `ede-cpp-root-project-root' - ;; and not write this at all. - ) - -(defun MY-LOAD (dir) - "Load a project of type `cpp-root' for the directory DIR. -Return nil if there isn't one." - ;; Use your preferred construction method here. - (ede-cpp-root-project "NAME" :file (expand-file-name "FILE" dir) - :locate-fcn 'MYFCN) - ) - -(add-to-list 'ede-project-class-files - (ede-project-autoload "cpp-root" - :name "CPP ROOT" - :file 'ede-cpp-root - :proj-file 'MY-FILE-FOR-DIR - :proj-root 'MY-ROOT-FCN - :load-type 'MY-LOAD - :class-sym 'ede-cpp-root) - t) -@end example - -This example only creates an auto-loader, and does not create a new kind -of project. - -@xref{ede-cpp-root-project}, for details about the class that defines -the @code{ede-cpp-root} project type. - -@node ede-emacs, ede-linux, ede-cpp-root, Simple projects -@subsection ede-emacs - -The @code{ede-emacs} project automatically identifies an Emacs source -tree, and enables EDE project mode for it. - -It pre-populates the C Preprocessor symbol map for correct parsing, -and has an optimized include file identification function. - -@node ede-linux, ede-generic-project, ede-emacs, Simple projects -@subsection ede-linux - -The @code{ede-linux} project will automatically identify a Linux -Kernel source tree, and enable EDE project mode for it. - -It pre-populates the C Preprocessor symbol map for reasonable parsing, -and has an optimized include file identification function. - -Through the variables @code{project-linux-build-directory-default} and -@code{project-linux-architecture-default}, you can set the build -directory and its architecture, respectively. The default is to assume that -the build happens in the source directory and to auto-detect the -architecture; if the auto-detection fails, you will be asked. - -@node ede-generic-project, Custom Locate, ede-linux, Simple projects -@subsection ede-generic-project - -The @code{ede-generic-project} is a project system that makes it easy -to wrap up different kinds of build systems as an EDE project. -Projects such as @ref{ede-emacs} require coding skills to create. -Generic projects also require writing Emacs Lisp code, but the -requirements are minimal. You can then use -@command{customize-project} to configure build commands, includes, and -other options for that project. The configuration is saved in -@file{EDEConfig.el}. - -Generic projects are disabled by default because they have the -potential to interfere with other projects. To use the generic -project system to start detecting projects, you need to enable it. - -@deffn Command ede-enable-generic-projects -Enable generic project loaders. - -This enables generic loaders for projects that are detected using -either a @file{Makefile}, @file{SConstruct}, or @file{CMakeLists}. - -You do not need to use this command if you create your own generic -project type. -@end deffn - -If you want to create your own generic project loader, you need to -define your own project and target classes, and create an autoloader. -The example for Makefiles looks like this: - -@example -;;; MAKEFILE - -(defclass ede-generic-makefile-project (ede-generic-project) - ((buildfile :initform "Makefile") - ) - "Generic Project for makefiles.") - -(defmethod ede-generic-setup-configuration ((proj ede-generic-makefile-project) config) - "Setup a configuration for Make." - (oset config build-command "make -k") - (oset config debug-command "gdb ") - ) - -(ede-generic-new-autoloader "generic-makefile" "Make" - "Makefile" 'ede-generic-makefile-project) -@end example - -This example project will detect any directory with the file -@file{Makefile} in it as belonging to this project type. -Customization of the project will allow you to make build and debug -commands more precise. - -@node Custom Locate, , ede-generic-project, Simple projects -@subsection Custom Locate - -The various simple project styles all have one major drawback, which -is that the files in the project are not completely known to EDE@. -When the EDE API is used to try and file files by some reference name -in the project, then that could fail. - -@ede{} can therefore use some external locate commands, such as the unix -``locate'' command, or ``GNU Global''. - -Configuration of the tool you want to use such as @code{locate}, or -@code{global} will need to be done without the aid of @ede{}. Once -configured, however, @ede{} can use it. - -To enable one of these tools, set the variable -@code{ede-locate-setup-options} with the names of different locate -objects. @ref{Miscellaneous commands}. - -Configure this in your @file{.emacs} before loading in CEDET or EDE@. -If you want to add support for GNU Global, your configuration would -look like this: - -@example -(setq ede-locate-setup-options '(ede-locate-global ede-locate-base)) -@end example - -That way, when a search needs to be done, it will first try using -GLOBAL@. If global is not available for that directory, then it will -revert to the base locate object. The base object always fails to -find a file. - -You can add your own locate tool but subclassing from -@code{ede-locate-base}. The subclass should also implement two -methods. See the code in @file{ede-locate.el} for GNU Global as a -simple example. - -@@TODO - Add ID Utils and CScope examples - -More on idutils and cscope is in the CEDET manual, and they each have -their own section. - -@node Extending EDE, GNU Free Documentation License, Miscellaneous commands, Top -@chapter Extending @ede{} - -This chapter is intended for users who want to write new parts or fix -bugs in @ede{}. A knowledge of Emacs Lisp, and some @eieio{}(CLOS) is -required. - -@ede{} uses @eieio{}, the CLOS package for Emacs, to define two object -superclasses, specifically the PROJECT and TARGET@. All commands in -@ede{} are usually meant to address the current project, or current -target. - -All specific projects in @ede{} derive subclasses of the @ede{} -superclasses. In this way, specific behaviors such as how a project -is saved, or how a target is compiled can be customized by a project -author in detail. @ede{} communicates to these project objects via an -API using methods. The commands you use in @ede{} mode are high-level -functional wrappers over these methods. @xref{Top,,, eieio, EIEIO manual}. For -details on using @eieio{} to extending classes, and writing methods. - -If you intend to extend @ede{}, it is most likely that a new target type is -needed in one of the existing project types. The rest of this chapter -will discuss extending the @code{ede-project} class, and it's targets. -See @file{project-am.el} for basic details on adding targets to it. - -For the @code{ede-project} type, the core target class is called -@code{ede-proj-target}. Inheriting from this will give you everything -you need to start, including adding your sources into the makefile. If -you also need additional rules in the makefile, you will want to inherit -from @code{ede-proj-target-makefile} instead. You may want to also add -new fields to track important information. - -If you are building currently unsupported code into a program or shared -library, it is unlikely you need a new target at all. Instead you -would need to create a new compiler or linker object that compiles -source code of the desired type. @ref{Compiler and Linker objects}. - -Once your new class exists, you will want to fill in some basic methods. -See the @file{ede-skel.el} file for examples of these. The files -@file{ede-proj-info.el} and @file{ede-proj-elisp.el} are two interesting -examples. - -@menu -* Development Overview:: -* Detecting a Project:: -* User interface methods:: Methods associated with keybindings -* Base project methods:: The most basic methods on @ede{} objects. -* Sourcecode objects:: Defining new sourcecode classes. -* Compiler and Linker objects:: Defining new compilers and linkers. -* Project:: Details of project classes. -* Targets:: Details of target classes. -* Sourcecode:: Details of source code classes. -* Compilers:: Details of compiler classes. -@end menu - -@node Development Overview, Detecting a Project, Extending EDE, Extending EDE -@section Development Overview - -@ede{} is made up of a series of classes implemented with @eieio{}. -These classes define an interface that can be used to create different -types of projects. - -@ede{} defines two superclasses which are @code{ede-project} and -@code{ede-target}. All commands in @ede{} are usually meant to -address the current project, or current target. - -All specific projects in @ede{} derive subclasses of the @ede{} superclasses. -In this way, specific behaviors such as how a project is saved, or how a -target is compiled can be customized by a project author in detail. @ede{} -communicates to these project objects via an API using methods. The -commands you use in @ede{} mode are high-level functional wrappers over -these methods. - -Some example project types are: - -@table @code -@item project-am -Automake project which reads existing Automake files. -@item ede-proj-project -This project type will create @file{Makefiles}, -or @file{Makefile.am} files to compile your project. -@item ede-linux -This project type will detect linux source trees. -@item ede-emacs -This project will detect an Emacs source tree. -@end table - -There are several other project types as well. - -The first class you need to know to create a new project type is -@code{ede-project-autoload}. New instances of this class are needed -to define how Emacs associates different files/buffers with different -project types. All the autoloads are kept in the variable -@code{ede-project-class-files}. - -The next most important class to know is @code{ede-project}. This is -the baseclass defines how all projects behave. The basic pattern for -a project is that there is one project per directory, and the topmost -project or directory defines the project as a whole. - -Key features of @code{ede-project} are things like name and version -number. It also holds a list of @code{ede-target} objects and a list -of sub projects, or more @code{ede-project} objects. - -New project types must subclass @code{ede-project} to add special -behavior. New project types also need to subclass @code{ede-target} to -add specialty behavior. - -In this way, the common @ede{} interface is designed to work against -@code{ede-project}, and thus all subclasses. - -@code{ede-project} subclasses @code{ede-project-placeholder}. This is -the minimum necessary project needed to be cached between runs of -Emacs. This way, Emacs can track all projects ever seen, without -loading those projects into memory. - -Here is a high-level UML diagram for the @ede{} system created with @cogre{}.. - -@example -+-----------------------+ +-----------------------+ -| | |ede-project-placeholder| -|ede-project-class-files| +-----------------------+ -| | +-----------------------+ -+-----------------------+ +-----------------------+ - /\ ^ - \/ /_\ - | | - +--------------------+ +-----------+ +----------+ - |ede-project-autoload| |ede-project| |ede-target| - +--------------------+<>--------------+-----------+<>-------+----------+ - +--------------------+ +-----------+ +----------+ - +--------------------+ +-----------+ +----------+ - ^ - /_\ - | - +---------------------+-----------------+ - | | | - | | | - | | | - +----------------+ +-------------------+ +---------+ - |ede-proj-project| |project-am-makefile| |ede-emacs| - +----------------+ +-------------------+ +---------+ - +----------------+ +-------------------+ +---------+ - +----------------+ +-------------------+ +---------+ -@end example - - -@node Detecting a Project, User interface methods, Development Overview, Extending EDE -@section Detecting a Project - -Project detection happens with the list of @code{ede-project-autoload} -instances stored in @code{ede-project-class-files}. The full project -detection scheme works like this: - -@table @asis -@item Step 1: -@code{find-file-hook} calls @code{ede-turn-on-hook} on BUFFER. -@item Step 2: -@code{ede-turn-on-hook} turns on @code{ede-minor-mode} -@item Step 3: -@code{ede-minor-mode} looks to see if BUFFER is associated with any -open projects. If not, it calls @code{ede-load-project-file} to find -a project associated with the current directory BUFFER is in. -@item Step 4: -@code{ede-minor-mode} associates the found project with the current -buffer with a series of variables, such as @code{ede-object}, and -@code{ede-object-project} and @code{ede-object-root-project}. -@end table - -Once a buffer is associated, @ede{} minor mode commands will operate -on that buffer. - -The function @code{ede-load-project-file} is at the heart of detecting -projects, and it works by looping over all the known project autoload -types in @code{ede-project-autoload} using the utility -@code{ede-directory-project-p}. - -The function @code{ede-directory-project-p} will call -@code{ede-dir-to-projectfile} on every @code{ede-project-autoload} -until one of them returns true. The method -@code{ede-dir-to-projectfile} in turn gets the @code{:proj-file} slot -from the autoload. If it is a string (i.e., a project file name), it -checks to see if that exists in BUFFER's directory. If it is a -function, then it calls that function and expects it to return a file -name or @code{nil}. If the file exists, then this directory is assumed to be -part of a project, and @code{ede-directory-project-p} returns the -instance of @code{ede-project-autoload} that matched. - -If the current directory contains the file @code{.ede-ignore} then -that directory is automatically assumed to contain no projects, even -if there is a matching pattern. Use this type of file in a directory -that may contain many other sub projects, but still has a Makefile of -some sort. - -If the current directory is a project, then @ede{} scans upwards till -it finds the top of the project. It does this by calling -@code{ede-toplevel-project}. If this hasn't already been discovered, -the directories as scanned upward one at a time until a directory with -no project is found. The last found project becomes the project -root. If the found instance of @code{ede-project-autoload} has a -valid @code{proj-root} slot value, then that function is called instead -of scanning the project by hand. Some project types have a short-cut -for determining the root of a project, so this comes in handy. - -Getting back to @code{ede-load-project-file}, this now has an instance -of @code{ede-project-autoload}. It uses the @code{load-type} slot to -both autoload in the project type, and to create a new instance of the -project type found for the root of the project. That project is added -to the global list of all projects. All subprojects are then created -and assembled into the project data structures. - - -@node User interface methods, Base project methods, Detecting a Project, Extending EDE -@section User interface methods - -These methods are core behaviors associated with user commands. -If you do not implement a method, there is a reasonable default that -may do what you need. - -@table @code -@item project-add-file -Add a file to your project. Override this if you want to put new -sources into different fields depending on extension, or other details. -@item project-remove-file -Reverse of project-add-file. -@item project-compile-target -Override this if you want to do something special when the user -"compiles" this target. -@item project-debug-target -What to do when a user wants to debug your target. -@item project-update-version -Easily update the version number of your project. -@item project-edit-file-target -Edit the file the project's information is stored in. -@item project-new-target -Create a new target in a project. -@item project-delete-target -Delete a target from a project. -@item project-make-dist -Make a distribution (tar archive) of the project. -@item project-rescan -Rescan a project file, changing the data in the existing objects. -@end table - -@node Base project methods, Sourcecode objects, User interface methods, Extending EDE -@section Base project methods - -These methods are important for querying base information from project -and target types: - -@table @code -@item ede-name -Return a string that is the name of this target. -@item ede-target-name -Return a string that is the name of the target used by a Make system. -@item ede-description -A brief description of the project or target. This is currently used -by the @samp{ede-speedbar} interface. -@item ede-want-file-p -Return non-@code{nil} if a target will accept a given file. -It is generally unnecessary to override this. See the section on source -code. -@item ede-buffer-mine -Return non-@code{nil} if a buffer belongs to this target. Used during -association when a file is loaded. It is generally unnecessary to -override this unless you keep auxiliary files. -@end table - -These methods are used by the semantic package extensions. -@xref{Top,,, semantic, Semantic manual}. - -@table @code -@item ede-buffer-header-file -Return a header file belonging to a given buffer. Prototypes are place -there when appropriate -@item ede-buffer-documentation-files -Return the documentation file information about this file would be -stored in. -@item ede-documentation -List all documentation a project or target is responsible for. -@end table - -@node Sourcecode objects, Compiler and Linker objects, Base project methods, Extending EDE -@section Sourcecode objects - -@ede{} projects track source file / target associates via source code -objects. The definitions for this is in @file{ede-source.el}. A source -code object contains methods that know how to identify a file as being -of that class, (i.e., a C file ends with @file{.c}). Some targets can -handle many different types of sources which must all be compiled -together. For example, a mixed C and C++ program would have -instantiations of both sourcecode types. - -When a target needs to know if it will accept a source file, it -references its list of source code objects. These objects then make -that decision. - -Source code objects are stored in the target objects as a list of -symbols, where the symbol's value is the object. This enables the -project save file mechanism to work. - -Here is an example for an instantiation of an Emacs Lisp source code object: - -@example -(defvar ede-source-emacs - (ede-sourcecode "ede-emacs-source" - :name "Emacs Lisp" - :sourcepattern "\\.el$" - :garbagepattern '("*.elc")) - "Emacs Lisp source code definition.") -@end example - -If you want to recycle parts of an existing sourcecode object, you can -clone the original, and then just tweak the parts that are different. -For example: - -@example -(defvar ede-source-emacs-autoload - (clone ede-source-emacs "ede-source-emacs-autoload" - :name "Emacs Lisp Autoload" - :sourcepattern "-loaddefs\\.el") - "Emacs Lisp autoload source code.") -@end example - -In this case, the garbage pattern is the same. - -@xref{Sourcecode}. - -@node Compiler and Linker objects, Project, Sourcecode objects, Extending EDE -@section Compiler and Linker objects - -In order for a target to create a @file{Makefile}, it must know how to -compile the sources into the program or desired data file, and -possibly link them together. - -A compiler object instantiation is used to associate a given target -with a given source code type. Some targets can handle many types of -sources, and thus has many compilers available to it. Some targets -may have multiple compilers for a given type of source code. - -@ede{} will examine the actual source files in a target, cross reference -that against the compiler list to come up with the final set of -compilers that will be inserted into the Makefile. - -Compiler instantiations must also insert variables specifying the -compiler it plans to use, in addition to creating Automake settings for -@file{configure.ac} when appropriate. - -Compiler objects are stored in the target objects as a list of -symbols, where the symbols value is the object. This enables the -project output mechanism to work more efficiently. - -Targets will also have a special "compiler" slot which lets a user -explicitly choose the compiler they want to use. - -Here is an example for texinfo: - -@example -(defvar ede-makeinfo-compiler - (ede-compiler - "ede-makeinfo-compiler" - :name "makeinfo" - :variables '(("MAKEINFO" . "makeinfo")) - :commands '("makeinfo -o $@ $<") - :autoconf '(("AC_CHECK_PROG" . "MAKEINFO, makeinfo")) - :sourcetype '(ede-makeinfo-source) - ) - "Compile texinfo files into info files.") -@end example - -@xref{Compilers}. - -When creating compiler instantiations, it may be useful to @code{clone} -an existing compiler variable. Cloning allows you to only modify -parts of the original, while keeping the rest of the same. -Modification of the original will result in the clone also being -changed for shared value slots. - -The second important object is the linker class. The linker is similar -to the compiler, except several compilers might be used to create some -object files, and only one linker is used to link those objects together. - -See @file{ede-proj-obj.el} for examples of the combination. - -@defindex pj -@defindex tg -@defindex sc -@defindex cm - -@node Project, Targets, Compiler and Linker objects, Extending EDE -@section Project - -@menu -* ede-project-placeholder:: -* ede-project:: -* ede-cpp-root-project:: -* ede-simple-project:: -* ede-simple-base-project:: -* ede-proj-project:: -* project-am-makefile:: -* ede-step-project:: -@end menu - -@node ede-project-placeholder, ede-project, Project, Project -@subsection ede-project-placeholder -@pjindex ede-project-placeholder - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item ede-project-placeholder -@table @asis -@item Children: -@w{@xref{ede-project}.} -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :name -Type: @code{string} @* -Default Value: @code{"Untitled"} - -The name used when generating distribution files. - -@item :version -Type: @code{string} @* -Default Value: @code{"1.0"} - -The version number used when distributing files. - -@item :directory -Type: @code{string} - -Directory this project is associated with. - -@item :file -Type: @code{string} - -File name where this project is stored. - -@end table - -@end table - -@subsubsection Specialized Methods - -@deffn Method ede--project-inode :AFTER proj -Get the inode of the directory project @var{PROJ} is in. -@end deffn - -@deffn Method ede-project-root :AFTER this -If a project knows it's root, return it here. -Allows for one-project-object-for-a-tree type systems. -@end deffn - -@deffn Method ede-find-subproject-for-directory :AFTER proj dir -Find a subproject of @var{PROJ} that corresponds to @var{DIR}. -@end deffn - -@deffn Method ede-project-root-directory :AFTER this &optional file -If a project knows it's root, return it here. -Allows for one-project-object-for-a-tree type systems. -Optional @var{FILE} is the file to test. It is ignored in preference -of the anchor file for the project. -@end deffn - -@deffn Method ede-project-force-load :AFTER this -Make sure the placeholder @var{THIS} is replaced with the real thing. -Return the new object created in its place. -@end deffn - -@deffn Method project-interactive-select-target :AFTER this prompt -Make sure placeholder @var{THIS} is replaced with the real thing, and pass through. -@end deffn - -@deffn Method project-add-file :AFTER this file -Make sure placeholder @var{THIS} is replaced with the real thing, and pass through. -@end deffn - -@node ede-project, ede-cpp-root-project, ede-project-placeholder, Project -@subsection ede-project -@pjindex ede-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item ede-project -@table @asis -@item Children: -@w{@xref{ede-cpp-root-project},} @w{ede-emacs-project,} @w{ede-linux-project,} @w{ede-maven-project,} @w{@xref{ede-simple-project},} @w{@xref{ede-simple-base-project},} @w{@xref{ede-proj-project},} @w{@xref{project-am-makefile},} @w{@xref{ede-step-project}.} -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :targets -Type: @code{list} - -List of top level targets in this project. - -@item :tool-cache -Type: @code{list} - -List of tool cache configurations in this project. -This allows any tool to create, manage, and persist project-specific settings. - -@item :web-site-url -Type: @code{string} @* - -URL to this projects web site. -This is a URL to be sent to a web site for documentation. - -@item :web-site-directory @* - -A directory where web pages can be found by Emacs. -For remote locations use a path compatible with ange-ftp or EFS@. -You can also use TRAMP for use with rcp & scp. - -@item :web-site-file @* - -A file which contains the home page for this project. -This file can be relative to slot @code{web-site-directory}. -This can be a local file, use ange-ftp, EFS, or TRAMP. - -@item :ftp-site -Type: @code{string} @* - -FTP site where this project's distribution can be found. -This FTP site should be in Emacs form, as needed by @code{ange-ftp}, but can -also be of a form used by TRAMP for use with scp, or rcp. - -@item :ftp-upload-site -Type: @code{string} @* - -FTP Site to upload new distributions to. -This FTP site should be in Emacs form as needed by @code{ange-ftp}. -If this slot is @code{nil}, then use @code{ftp-site} instead. - -@item :configurations -Type: @code{list} @* -Default Value: @code{("debug" "release")} - -List of available configuration types. -Individual target/project types can form associations between a configuration, -and target specific elements such as build variables. - -@item :configuration-default @* -Default Value: @code{"debug"} - -The default configuration. - -@item :local-variables @* -Default Value: @code{nil} - -Project local variables - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-preprocessor-map :AFTER this -Get the pre-processor map for project @var{THIS}. -@end deffn - -@deffn Method ede-subproject-relative-path :AFTER proj &optional parent-in -Get a path name for @var{PROJ} which is relative to the parent project. -If PARENT is specified, then be relative to the PARENT project. -Specifying PARENT is useful for sub-sub projects relative to the root project. -@end deffn - -@deffn Method eieio-speedbar-description :AFTER obj -Provide a speedbar description for @var{OBJ}. -@end deffn - -@deffn Method ede-map-any-target-p :AFTER this proc -For project @var{THIS}, map @var{PROC} to all targets and return if any non-@code{nil}. -Return the first non-@code{nil} value returned by @var{PROC}. -@end deffn - -@deffn Method ede-map-subprojects :AFTER this proc -For object @var{THIS}, execute @var{PROC} on all direct subprojects. -This function does not apply @var{PROC} to sub-sub projects. -See also @dfn{ede-map-all-subprojects}. -@end deffn - -@deffn Method ede-convert-path :AFTER this path -Convert path in a standard way for a given project. -Default to making it project relative. -Argument @var{THIS} is the project to convert @var{PATH} to. -@end deffn - -@deffn Method ede-name :AFTER this -Return a short-name for @var{THIS} project file. -Do this by extracting the lowest directory name. -@end deffn - -@deffn Method ede-set-project-variables :AFTER project &optional buffer -Set variables local to @var{PROJECT} in @var{BUFFER}. -@end deffn - -@deffn Method eieio-speedbar-derive-line-path :AFTER obj &optional depth -Return the path to @var{OBJ}. -Optional @var{DEPTH} is the depth we start at. -@end deffn - -@deffn Method ede-map-all-subprojects :AFTER this allproc -For object @var{THIS}, execute PROC on @var{THIS} and all subprojects. -This function also applies PROC to sub-sub projects. -See also @dfn{ede-map-subprojects}. -@end deffn - -@deffn Method project-update-version :AFTER ot -The @code{:version} of the project @var{OT} has been updated. -Handle saving, or other detail. -@end deffn - -@deffn Method ede-buffer-header-file :AFTER this buffer -Return @code{nil}, projects don't have header files. -@end deffn - -@deffn Method ede-buffer-documentation-files :AFTER this buffer -Return all documentation in project @var{THIS} based on @var{BUFFER}. -@end deffn - -@deffn Method ede-map-targets :AFTER this proc -For object @var{THIS}, execute @var{PROC} on all targets. -@end deffn - -@deffn Method ede-buffer-mine :AFTER this buffer -Return non-@code{nil} if object @var{THIS} lays claim to the file in @var{BUFFER}. -@end deffn - -@deffn Method ede-object-keybindings :BEFORE this -Retrieves the slot @code{keybindings} from an object of class @code{ede-project} -@end deffn - -@deffn Method ede-description :AFTER this -Return a description suitable for the minibuffer about @var{THIS}. -@end deffn - -@deffn Method eieio-speedbar-object-children :AFTER this -Return the list of speedbar display children for @var{THIS}. -@end deffn - -@deffn Method project-make-dist :AFTER this -Build a distribution for the project based on @var{THIS} project. -@end deffn - -@deffn Method ede-system-include-path :AFTER this -Get the system include path used by project @var{THIS}. -@end deffn - -@deffn Method project-new-target-custom :AFTER proj -Create a new target. It is up to the project @var{PROJ} to get the name. -@end deffn - -@deffn Method ede-subproject-p :AFTER proj -Return non-@code{nil} if @var{PROJ} is a sub project. -@end deffn - -@deffn Method ede-expand-filename :AFTER this filename &optional force -Return a fully qualified file name based on project @var{THIS}. -@var{FILENAME} should be just a filename which occurs in a directory controlled -by this project. -Optional argument @var{FORCE} forces the default filename to be provided even if it -doesn't exist. -@end deffn - -@deffn Method ede-menu-items-build :AFTER obj &optional current -Return a list of menu items for building project @var{OBJ}. -If optional argument @var{CURRENT} is non-@code{nil}, return sub-menu code. -@end deffn - -@deffn Method ede-update-version-in-source :AFTER this version -Change occurrences of a version string in sources. -In project @var{THIS}, cycle over all targets to give them a chance to set -their sources to @var{VERSION}. -@end deffn - -@deffn Method project-new-target :AFTER proj &rest args -Create a new target. It is up to the project @var{PROJ} to get the name. -@end deffn - -@deffn Method project-compile-project :AFTER obj &optional command -Compile the entire current project @var{OBJ}. -Argument @var{COMMAND} is the command to use when compiling. -@end deffn - -@deffn Method eieio-speedbar-object-buttonname :AFTER object -Return a string to use as a speedbar button for @var{OBJECT}. -@end deffn - -@deffn Method ede-map-project-buffers :AFTER this proc -For @var{THIS}, execute @var{PROC} on all buffers belonging to @var{THIS}. -@end deffn - -@deffn Method ede-expand-filename-impl :AFTER this filename &optional force -Return a fully qualified file name based on project @var{THIS}. -@var{FILENAME} should be just a filename which occurs in a directory controlled -by this project. -Optional argument @var{FORCE} forces the default filename to be provided even if it -doesn't exist. -@end deffn - -@deffn Method eieio-done-customizing :AFTER proj -Call this when a user finishes customizing @var{PROJ}. -@end deffn - -@deffn Method ede-html-documentation :AFTER this -Return a list of HTML files provided by project @var{THIS}. -@end deffn - -@deffn Method ede-documentation :AFTER this -Return a list of files that provides documentation. -Documentation is not for object @var{THIS}, but is provided by @var{THIS} for other -files in the project. -@end deffn - -@deffn Method project-interactive-select-target :AFTER this prompt -Interactively query for a target that exists in project @var{THIS}. -Argument @var{PROMPT} is the prompt to use when querying the user for a target. -@end deffn - -@deffn Method ede-target-in-project-p :AFTER proj target -Is @var{PROJ} the parent of @var{TARGET}? -If @var{TARGET} belongs to a subproject, return that project file. -@end deffn - -@deffn Method ede-find-target :AFTER proj buffer -Fetch the target in @var{PROJ} belonging to @var{BUFFER} or @code{nil}. -@end deffn - -@deffn Method ede-add-subproject :AFTER proj-a proj-b -Add into @var{PROJ-A}, the subproject @var{PROJ-B}. -@end deffn - -@deffn Method ede-commit-project :AFTER proj -Commit any change to @var{PROJ} to its file. -@end deffn - -@deffn Method project-dist-files :AFTER this -Return a list of files that constitutes a distribution of @var{THIS} project. -@end deffn - -@deffn Method ede-object-menu :BEFORE this -Retrieves the slot @code{menu} from an object of class @code{ede-project} -@end deffn - -@deffn Method ede-commit-local-variables :AFTER proj -Commit change to local variables in @var{PROJ}. -@end deffn - -@node ede-cpp-root-project, ede-simple-project, ede-project, Project -@subsection ede-cpp-root-project -@pjindex ede-cpp-root-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-cpp-root-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - -This class implements the @code{ede-cpp-root} project type. -@xref{ede-cpp-root}, for information about using this project type. - -@table @asis -@item Slots: - -@table @code -@item :include-path -Type: @code{list} @* -Default Value: @code{(quote ("/include" "../include/"))} - -The default locate function expands filenames within a project. -If a header file (.h, .hh, etc.)@: name is expanded, and -the @code{:locate-fcn} slot is @code{nil}, then the include path is checked -first, and other directories are ignored. For very large -projects, this optimization can save a lot of time. - -Directory names in the path can be relative to the current -buffer's @code{default-directory} (not starting with a /). Directories -that are relative to the project's root should start with a /, such -as "/include", meaning the directory @code{include} off the project root -directory. - -@item :system-include-path -Type: @code{list} @* -Default Value: @code{nil} - -The system include path for files in this project. -C files initialized in an ede-cpp-root-project have their semantic -system include path set to this value. If this is @code{nil}, then the -semantic path is not modified. - -@item :spp-table -Type: @code{list} @* -Default Value: @code{nil} - -C Preprocessor macros for your files. -Preprocessor symbols will be used while parsing your files. -These macros might be passed in through the command line compiler, or -are critical symbols derived from header files. Providing header files -macro values through this slot improves accuracy and performance. -Use `:spp-files' to use these files directly. - -@item :spp-files -Type: @code{list} @* -Default Value: @code{nil} - -C header file with Preprocessor macros for your files. -The PreProcessor symbols appearing in these files will be used while -parsing files in this project. -See @code{semantic-lex-c-preprocessor-symbol-map} for more on how this works. - -@item :header-match-regexp -Type: @code{string} @* -Default Value: @code{"\\.\\(h\\(h\\|xx\\|pp\\|\\+\\+\\)?\\|H\\)$\\|\\<\\w+$"} - -Regexp used to identify C/C++ header files. - -@item :locate-fcn -Type: @code{(or null function)} @* -Default Value: @code{nil} - -The locate function can be used in place of -@dfn{ede-expand-filename} so you can quickly customize your custom target -to use specialized local routines instead of the EDE routines. -The function symbol must take two arguments: - NAME - The name of the file to find. - DIR - The directory root for this cpp-root project. - -It should return the fully qualified file name passed in from NAME@. -If that file does not exist, it should return @code{nil}. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method initialize-instance :AFTER this &rest fields -Make sure the @code{:file} is fully expanded. -@end deffn - -@deffn Method ede-preprocessor-map :AFTER this -Get the pre-processor map for project @var{THIS}. -@end deffn - -@deffn Method ede-cpp-root-header-file-p :AFTER proj name -Non @code{nil} if in @var{PROJ} the filename @var{NAME} is a header. -@end deffn - -@deffn Method ede-system-include-path :AFTER this -Get the system include path used by project @var{THIS}. -@end deffn - -@deffn Method ede-expand-filename-impl :AFTER proj name -Within this project @var{PROJ}, find the file @var{NAME}. -This knows details about or source tree. -@end deffn - -@node ede-simple-project, ede-simple-base-project, ede-cpp-root-project, Project -@subsection ede-simple-project -@pjindex ede-simple-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-simple-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method ede-commit-project :AFTER proj -Commit any change to @var{PROJ} to its file. -@end deffn - -@node ede-simple-base-project, ede-proj-project, ede-simple-project, Project -@subsection ede-simple-base-project -@pjindex ede-simple-base-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-simple-base-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - - EDE Simple project base class. -This one project could control a tree of subdirectories. - -@table @asis -@end table - -@node ede-proj-project, project-am-makefile, ede-simple-base-project, Project -@subsection ede-proj-project -@pjindex ede-proj-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-proj-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :makefile-type -Type: @code{symbol} @* -Default Value: @code{Makefile} - -The type of Makefile to generate. -Can be one of @code{'Makefile}, 'Makefile.in, or 'Makefile.am. -If this value is NOT @code{'Makefile}, then that overrides the @code{:makefile} slot -in targets. - -@item :variables -Type: @code{list} @* -Default Value: @code{nil} - -Variables to set in this Makefile. - -@item :configuration-variables -Type: @code{list} @* -Default Value: @code{("debug" (("DEBUG" . "1")))} - -Makefile variables to use in different configurations. -These variables are used in the makefile when a configuration becomes active. - -@item :inference-rules @* -Default Value: @code{nil} - -Inference rules to add to the makefile. - -@item :include-file @* -Default Value: @code{nil} - -Additional files to include. -These files can contain additional rules, variables, and customizations. - -@item :automatic-dependencies -Type: @code{boolean} @* -Default Value: @code{t} - -Non-@code{nil} to do implement automatic dependencies in the Makefile. - -@item :metasubproject -Type: @code{boolean} @* -Default Value: @code{nil} - -Non-@code{nil} if this is a metasubproject. -Usually, a subproject is determined by a parent project. If multiple top level -projects are grouped into a large project not maintained by EDE, then you need -to set this to non-@code{nil}. The only effect is that the @code{dist} rule will then avoid -making a tar file. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-create :AFTER this mfilename -Create a Makefile for all Makefile targets in @var{THIS}. -@var{MFILENAME} is the makefile to generate. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-tags :AFTER this targets -Insert into the current location rules to make recursive TAGS files. -Argument @var{THIS} is the project to create tags for. -Argument @var{TARGETS} are the targets we should depend on for TAGS. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this -Insert variables needed by target @var{THIS}. -@end deffn - -@deffn Method project-make-dist :AFTER this -Build a distribution for the project based on @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-rules :AFTER this -Insert distribution rules for @var{THIS} in a Makefile, such as CLEAN and DIST. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert any symbols that the DIST rule should depend on. -Argument @var{THIS} is the project that should insert stuff. -@end deffn - -@deffn Method ede-proj-makefile-insert-subproj-rules :AFTER this -Insert a rule for the project @var{THIS} which should be a subproject. -@end deffn - -@deffn Method ede-proj-makefile-create-maybe :AFTER this mfilename -Create a Makefile for all Makefile targets in @var{THIS} if needed. -@var{MFILENAME} is the makefile to generate. -@end deffn - -@deffn Method ede-proj-configure-test-required-file :AFTER this file -For project @var{THIS}, test that the file @var{FILE} exists, or create it. -@end deffn - -@deffn Method ede-proj-setup-buildenvironment :AFTER this &optional force -Setup the build environment for project @var{THIS}. -Handles the Makefile, or a Makefile.am configure.ac combination. -Optional argument @var{FORCE} will force items to be regenerated. -@end deffn - -@deffn Method ede-proj-makefile-garbage-patterns :AFTER this -Return a list of patterns that are considered garbage to @var{THIS}. -These are removed with make clean. -@end deffn - -@deffn Method ede-proj-configure-synchronize :AFTER this -Synchronize what we know about project @var{THIS} into configure.ac. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables-new :AFTER this -Insert variables needed by target @var{THIS}. - -NOTE: Not yet in use! This is part of an SRecode conversion of - EDE that is in progress. -@end deffn - -@deffn Method ede-proj-makefile-configuration-variables :AFTER this configuration -Return a list of configuration variables from @var{THIS}. -Use @var{CONFIGURATION} as the current configuration to query. -@end deffn - -@deffn Method eieio-done-customizing :AFTER proj -Call this when a user finishes customizing this object. -Argument @var{PROJ} is the project to save. -@end deffn - -@deffn Method ede-proj-configure-recreate :AFTER this -Delete project @var{THIS}'s configure script and start over. -@end deffn - -@deffn Method ede-proj-makefile-insert-user-rules :AFTER this -Insert user specified rules needed by @var{THIS} target. -This is different from @dfn{ede-proj-makefile-insert-rules} in that this -function won't create the building rules which are auto created with -automake. -@end deffn - -@deffn Method ede-proj-dist-makefile :AFTER this -Return the name of the Makefile with the DIST target in it for @var{THIS}. -@end deffn - -@deffn Method ede-proj-configure-file :AFTER this -The configure.ac script used by project @var{THIS}. -@end deffn - -@deffn Method ede-commit-project :AFTER proj -Commit any change to @var{PROJ} to its file. -@end deffn - -@deffn Method project-dist-files :AFTER this -Return a list of files that constitutes a distribution of @var{THIS} project. -@end deffn - -@deffn Method ede-commit-local-variables :AFTER proj -Commit change to local variables in @var{PROJ}. -@end deffn - -@node project-am-makefile, ede-step-project, ede-proj-project, Project -@subsection project-am-makefile -@pjindex project-am-makefile - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item project-am-makefile -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-subtree :AFTER ampf subdir -Return the sub project in @var{AMPF} specified by @var{SUBDIR}. -@end deffn - -@deffn Method project-targets-for-file :AFTER proj -Return a list of targets the project @var{PROJ}. -@end deffn - -@deffn Method project-new-target :AFTER proj &optional name type -Create a new target named @var{NAME}. -Argument @var{TYPE} is the type of target to insert. This is a string -matching something in @code{project-am-type-alist} or type class symbol. -Despite the fact that this is a method, it depends on the current -buffer being in order to provide a smart default target type. -@end deffn - -@node ede-step-project, , project-am-makefile, Project -@subsection ede-step-project -@pjindex ede-step-project - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-project-placeholder}.} -@table @code -@item @w{@xref{ede-project}.} -@table @code -@item ede-step-project -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :init-variables -Type: @code{list} @* -Default Value: @code{nil} - -Variables to set in this Makefile, at top of file. - -@item :additional-variables -Type: @code{(or null list)} @* -Default Value: @code{nil} - -Arbitrary variables needed from this project. -It is safe to leave this blank. - -@item :additional-rules -Type: @code{(or null list)} @* -Default Value: @code{nil} - -Arbitrary rules and dependencies needed to make this target. -It is safe to leave this blank. - -@item :installation-domain -Type: @code{symbol} @* -Default Value: @code{user} - -Installation domain specification. -The variable GNUSTEP_INSTALLATION_DOMAIN is set at this value. - -@item :preamble -Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.preamble"))} - -The auxiliary makefile for additional variables. -Included just before the specific target files. - -@item :postamble -Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.postamble"))} - -The auxiliary makefile for additional rules. -Included just after the specific target files. - -@item :metasubproject -Type: @code{boolean} @* -Default Value: @code{nil} - -Non-@code{nil} if this is a metasubproject. -Usually, a subproject is determined by a parent project. If multiple top level -projects are grouped into a large project not maintained by EDE, then you need -to set this to non-@code{nil}. The only effect is that the @code{dist} rule will then avoid -making a tar file. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-create :AFTER this mfilename -Create a GNUmakefile for all Makefile targets in @var{THIS}. -@var{MFILENAME} is the makefile to generate. -@end deffn - -@deffn Method project-make-dist :AFTER this -Build a distribution for the project based on @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-create-maybe :AFTER this mfilename -Create a Makefile for all Makefile targets in @var{THIS} if needed. -@var{MFILENAME} is the makefile to generate. -@end deffn - -@deffn Method ede-proj-setup-buildenvironment :AFTER this &optional force -Setup the build environment for project @var{THIS}. -Handles the Makefile, or a Makefile.am configure.ac combination. -Optional argument @var{FORCE} will force items to be regenerated. -@end deffn - -@deffn Method eieio-done-customizing :AFTER proj -Call this when a user finishes customizing this object. -Argument @var{PROJ} is the project to save. -@end deffn - -@deffn Method ede-proj-dist-makefile :AFTER this -Return the name of the Makefile with the DIST target in it for @var{THIS}. -@end deffn - -@deffn Method ede-commit-project :AFTER proj -Commit any change to @var{PROJ} to its file. -@end deffn - -@deffn Method project-dist-files :AFTER this -Return a list of files that constitutes a distribution of @var{THIS} project. -@end deffn - -@deffn Method ede-commit-local-variables :AFTER proj -Commit change to local variables in @var{PROJ}. -@end deffn - -@node Targets, Sourcecode, Project, Extending EDE -@section Targets - -@menu -* ede-target:: -* ede-proj-target:: -* ede-proj-target-makefile:: -* semantic-ede-proj-target-grammar:: -* ede-proj-target-makefile-objectcode:: -* ede-proj-target-makefile-archive:: -* ede-proj-target-makefile-program:: -* ede-proj-target-makefile-shared-object:: -* ede-proj-target-elisp:: -* ede-proj-target-elisp-autoloads:: -* ede-proj-target-makefile-miscelaneous:: -* ede-proj-target-makefile-info:: -* ede-proj-target-scheme:: -* project-am-target:: -* project-am-objectcode:: -* project-am-program:: -* project-am-header-noinst:: -* project-am-header-inst:: -* project-am-lisp:: -* project-am-texinfo:: -* project-am-man:: -@end menu - - -@node ede-target, ede-proj-target, Targets, Targets -@subsection ede-target -@tgindex ede-target - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item ede-target -@table @asis -@item Children: -@w{ede-cpp-root-target,} @w{ede-emacs-target-c,} @w{ede-emacs-target-el,} @w{ede-emacs-target-misc,} @w{ede-linux-target-c,} @w{ede-linux-target-misc,} @w{ede-maven-target-java,} @w{ede-maven-target-c,} @w{ede-maven-target-misc,} @w{ede-simple-target,} @w{@xref{ede-proj-target},} @w{@xref{project-am-target}.} -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :name -Type: @code{string} - -Name of this target. - -@item :path -Type: @code{string} - -The path to the sources of this target. -Relative to the path of the project it belongs to. - -@item :source -Type: @code{list} @* -Default Value: @code{nil} - -Source files in this target. - -@item :versionsource -Type: @code{list} @* -Default Value: @code{nil} - -Source files with a version string in them. -These files are checked for a version string whenever the EDE version -of the master project is changed. When strings are found, the version -previously there is updated. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-preprocessor-map :AFTER this -Get the pre-processor map for project @var{THIS}. -@end deffn - -@deffn Method eieio-speedbar-description :AFTER obj -Provide a speedbar description for @var{OBJ}. -@end deffn - -@deffn Method project-compile-target :AFTER obj &optional command -Compile the current target @var{OBJ}. -Argument @var{COMMAND} is the command to use for compiling the target. -@end deffn - -@deffn Method project-debug-target :AFTER obj -Run the current project target @var{OBJ} in a debugger. -@end deffn - -@deffn Method ede-convert-path :AFTER this path -Convert path in a standard way for a given project. -Default to making it project relative. -Argument @var{THIS} is the project to convert @var{PATH} to. -@end deffn - -@deffn Method ede-name :AFTER this -Return the name of @var{THIS} targt. -@end deffn - -@deffn Method ede-target-buffer-in-sourcelist :AFTER this buffer source -Return non-@code{nil} if object @var{THIS} is in @var{BUFFER} to a @var{SOURCE} list. -Handles complex path issues. -@end deffn - -@deffn Method eieio-speedbar-derive-line-path :AFTER obj &optional depth -Return the path to @var{OBJ}. -Optional @var{DEPTH} is the depth we start at. -@end deffn - -@deffn Method ede-buffer-header-file :AFTER this buffer -There are no default header files in EDE@. -Do a quick check to see if there is a Header tag in this buffer. -@end deffn - -@deffn Method project-remove-file :AFTER ot fnnd -Remove the current buffer from project target @var{OT}. -Argument @var{FNND} is an argument. -@end deffn - -@deffn Method ede-buffer-documentation-files :AFTER this buffer -Check for some documentation files for @var{THIS}. -Also do a quick check to see if there is a Documentation tag in this @var{BUFFER}. -@end deffn - -@deffn Method ede-map-target-buffers :AFTER this proc -For @var{THIS}, execute @var{PROC} on all buffers belonging to @var{THIS}. -@end deffn - -@deffn Method eieio-speedbar-child-description :AFTER obj -Provide a speedbar description for a plain-child of @var{OBJ}. -A plain child is a child element which is not an EIEIO object. -@end deffn - -@deffn Method ede-object-keybindings :BEFORE this -Retrieves the slot @code{keybindings} from an object of class @code{ede-target} -@end deffn - -@deffn Method ede-description :AFTER this -Return a description suitable for the minibuffer about @var{THIS}. -@end deffn - -@deffn Method eieio-speedbar-object-children :AFTER this -Return the list of speedbar display children for @var{THIS}. -@end deffn - -@deffn Method ede-system-include-path :AFTER this -Get the system include path used by project @var{THIS}. -@end deffn - -@deffn Method ede-object-sourcecode :BEFORE this -Retrieves the slot @code{sourcetype} from an object of class @code{ede-target} -@end deffn - -@deffn Method ede-expand-filename :AFTER this filename &optional force -Return a fully qualified file name based on target @var{THIS}. -@var{FILENAME} should be a filename which occurs in a directory in which @var{THIS} works. -Optional argument @var{FORCE} forces the default filename to be provided even if it -doesn't exist. -@end deffn - -@deffn Method ede-menu-items-build :AFTER obj &optional current -Return a list of menu items for building target @var{OBJ}. -If optional argument @var{CURRENT} is non-@code{nil}, return sub-menu code. -@end deffn - -@deffn Method ede-want-file-p :AFTER this file -Return non-@code{nil} if @var{THIS} target wants @var{FILE}. -@end deffn - -@deffn Method ede-update-version-in-source :AFTER this version -In sources for @var{THIS}, change version numbers to @var{VERSION}. -@end deffn - -@deffn Method project-delete-target :AFTER ot -Delete the current target @var{OT} from it's parent project. -@end deffn - -@deffn Method ede-target-sourcecode :AFTER this -Return the sourcecode objects which @var{THIS} permits. -@end deffn - -@deffn Method eieio-speedbar-child-make-tag-lines :AFTER this depth -Create a speedbar tag line for a child of @var{THIS}. -It has depth @var{DEPTH}. -@end deffn - -@deffn Method eieio-speedbar-object-buttonname :AFTER object -Return a string to use as a speedbar button for @var{OBJECT}. -@end deffn - -@deffn Method eieio-done-customizing :AFTER target -Call this when a user finishes customizing @var{TARGET}. -@end deffn - -@deffn Method project-edit-file-target :AFTER ot -Edit the target @var{OT} associated w/ this file. -@end deffn - -@deffn Method ede-documentation :AFTER this -Return a list of files that provides documentation. -Documentation is not for object @var{THIS}, but is provided by @var{THIS} for other -files in the project. -@end deffn - -@deffn Method ede-want-file-source-p :AFTER this file -Return non-@code{nil} if @var{THIS} target wants @var{FILE}. -@end deffn - -@deffn Method ede-want-file-auxiliary-p :AFTER this file -Return non-@code{nil} if @var{THIS} target wants @var{FILE}. -@end deffn - -@deffn Method project-add-file :AFTER ot file -Add the current buffer into project project target @var{OT}. -Argument @var{FILE} is the file to add. -@end deffn - -@deffn Method ede-target-name :AFTER this -Return the name of @var{THIS} target, suitable for make or debug style commands. -@end deffn - -@deffn Method ede-object-menu :BEFORE this -Retrieves the slot @code{menu} from an object of class @code{ede-target} -@end deffn - -@node ede-proj-target, ede-proj-target-makefile, ede-target, Targets -@subsection ede-proj-target -@tgindex ede-proj-target - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item ede-proj-target -@table @asis -@item Children: -@w{@xref{ede-proj-target-makefile},} @w{ede-proj-target-aux,} @w{@xref{ede-proj-target-scheme}.} -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :name -Type: @code{string} - -Name of this target. - -@item :path -Type: @code{string} - -The path to the sources of this target. -Relative to the path of the project it belongs to. - -@item :auxsource -Type: @code{list} @* -Default Value: @code{nil} - -Auxiliary source files included in this target. -Each of these is considered equivalent to a source file, but it is not -distributed, and each should have a corresponding rule to build it. - -@item :compiler -Type: @code{(or null symbol)} @* -Default Value: @code{nil} - -The compiler to be used to compile this object. -This should be a symbol, which contains the object defining the compiler. -This enables save/restore to do so by name, permitting the sharing -of these compiler resources, and global customization thereof. - -@item :linker -Type: @code{(or null symbol)} @* -Default Value: @code{nil} - -The linker to be used to link compiled sources for this object. -This should be a symbol, which contains the object defining the linker. -This enables save/restore to do so by name, permitting the sharing -of these linker resources, and global customization thereof. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method project-compile-target :AFTER obj &optional command -Compile the current target @var{OBJ}. -Argument @var{COMMAND} is the command to use for compiling the target. -@end deffn - -@deffn Method project-debug-target :AFTER obj -Run the current project target @var{OBJ} in a debugger. -@end deffn - -@deffn Method ede-proj-configure-add-missing :AFTER this -Query if any files needed by @var{THIS} provided by automake are missing. -Results in --add-missing being passed to automake. -@end deffn - -@deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accommodate @var{THIS}. -By flushing, remove any cruft that may be in the file. Subsequent -calls to @dfn{ede-proj-tweak-autoconf} can restore items removed by flush. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method project-remove-file :AFTER target file -For @var{TARGET}, remove @var{FILE}. -@var{FILE} must be massaged by @dfn{ede-convert-path}. -@end deffn - -@deffn Method ede-proj-configure-create-missing :AFTER this -Add any missing files for @var{THIS} by creating them. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this &optional moresource -Insert variables needed by target @var{THIS}. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-post-variables :AFTER this -Insert variables needed by target @var{THIS} in Makefile.am after SOURCES. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert any symbols that the DIST rule should depend on. -Argument @var{THIS} is the target that should insert stuff. -@end deffn - -@deffn Method ede-proj-linkers :AFTER obj -List of linkers being used by @var{OBJ}. -If the @code{linker} slot is empty, concoct one on a first match found -basis for any given type from the @code{availablelinkers} slot. -Otherwise, return the @code{linker} slot. -Converts all symbols into the objects to be used. -@end deffn - -@deffn Method ede-proj-makefile-garbage-patterns :AFTER this -Return a list of patterns that are considered garbage to @var{THIS}. -These are removed with make clean. -@end deffn - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-proj-compilers :AFTER obj -List of compilers being used by @var{OBJ}. -If the @code{compiler} slot is empty, concoct one on a first match found -basis for any given type from the @code{availablecompilers} slot. -Otherwise, return the @code{compiler} slot. -Converts all symbols into the objects to be used. -@end deffn - -@deffn Method project-delete-target :AFTER this -Delete the current target @var{THIS} from it's parent project. -@end deffn - -@deffn Method ede-proj-makefile-target-name :AFTER this -Return the name of the main target for @var{THIS} target. -@end deffn - -@deffn Method eieio-done-customizing :AFTER target -Call this when a user finishes customizing this object. -Argument @var{TARGET} is the project we are completing customization on. -@end deffn - -@deffn Method ede-proj-makefile-insert-user-rules :AFTER this -Insert user specified rules needed by @var{THIS} target. -@end deffn - -@deffn Method project-add-file :AFTER this file -Add to target @var{THIS} the current buffer represented as @var{FILE}. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-pre-variables :AFTER this -Insert variables needed by target @var{THIS} in Makefile.am before SOURCES. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-filepatterns :AFTER this -Insert any symbols that the DIST rule should depend on. -Argument @var{THIS} is the target that should insert stuff. -@end deffn - -@deffn Method ede-proj-makefile-dependency-files :AFTER this -Return a list of source files to convert to dependencies. -Argument @var{THIS} is the target to get sources from. -@end deffn - -@deffn Method ede-proj-makefile-insert-source-variables :AFTER this &optional moresource -Insert the source variables needed by @var{THIS}. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -@end deffn - - -@node ede-proj-target-makefile, semantic-ede-proj-target-grammar, ede-proj-target, Targets -@subsection ede-proj-target-makefile -@tgindex ede-proj-target-makefile - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item ede-proj-target-makefile -@table @asis -@item Children: -@w{@xref{semantic-ede-proj-target-grammar},} @w{@xref{ede-proj-target-makefile-objectcode},} @w{@xref{ede-proj-target-elisp},} @w{@xref{ede-proj-target-makefile-miscelaneous},} @w{@xref{ede-proj-target-makefile-info}.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :makefile -Type: @code{string} @* -Default Value: @code{"Makefile"} - -File name of generated Makefile. - -@item :partofall -Type: @code{boolean} @* -Default Value: @code{t} - -Non @code{nil} means the rule created is part of the all target. -Setting this to @code{nil} creates the rule to build this item, but does not -include it in the ALL`all:' rule. - -@item :configuration-variables -Type: @code{list} @* -Default Value: @code{nil} - -Makefile variables appended to use in different configurations. -These variables are used in the makefile when a configuration becomes active. -Target variables are always renamed such as foo_CFLAGS, then included into -commands where the variable would usually appear. - -@item :rules -Type: @code{list} @* -Default Value: @code{nil} - -Arbitrary rules and dependencies needed to make this target. -It is safe to leave this blank. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-dependencies :AFTER this -Return a string representing the dependencies for @var{THIS}. -Some compilers only use the first element in the dependencies, others -have a list of intermediates (object files), and others don't care. -This allows customization of how these elements appear. -@end deffn - -@deffn Method project-compile-target :AFTER obj &optional command -Compile the current target program @var{OBJ}. -Optional argument @var{COMMAND} is the s the alternate command to use. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this &optional moresource -Insert variables needed by target @var{THIS}. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -@end deffn - -@deffn Method ede-proj-makefile-insert-commands :AFTER this -Insert the commands needed by target @var{THIS}. -For targets, insert the commands needed by the chosen compiler. -@end deffn - -@deffn Method ede-proj-makefile-configuration-variables :AFTER this configuration -Return a list of configuration variables from @var{THIS}. -Use @var{CONFIGURATION} as the current configuration to query. -@end deffn - -@node semantic-ede-proj-target-grammar, ede-proj-target-makefile-objectcode, ede-proj-target-makefile, Targets -@subsection semantic-ede-proj-target-grammar -@tgindex semantic-ede-proj-target-grammar - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item semantic-ede-proj-target-grammar -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-compile-target :AFTER obj -Compile all sources in a Lisp target @var{OBJ}. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method ede-buffer-mine :AFTER this buffer -Return @code{t} if object @var{THIS} lays claim to the file in @var{BUFFER}. -Lays claim to all -by.el, and -wy.el files. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert dist dependencies, or intermediate targets. -This makes sure that all grammar lisp files are created before the dist -runs, so they are always up to date. -Argument @var{THIS} is the target that should insert stuff. -@end deffn - - -@node ede-proj-target-makefile-objectcode, ede-proj-target-makefile-archive, semantic-ede-proj-target-grammar, Targets -@subsection ede-proj-target-makefile-objectcode -@tgindex ede-proj-target-makefile-objectcode - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item ede-proj-target-makefile-objectcode -@table @asis -@item Children: -@w{@xref{ede-proj-target-makefile-archive},} @w{@xref{ede-proj-target-makefile-program}.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :configuration-variables -Type: @code{list} @* -Default Value: @code{("debug" ("CFLAGS" . "-g") ("LDFLAGS" . "-g"))} - -@xref{ede-proj-target-makefile}. -@end table -@end table -@subsubsection Specialized Methods - -@deffn Method ede-buffer-header-file :AFTER this buffer -There are no default header files. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this &optional moresource -Insert variables needed by target @var{THIS}. -Optional argument @var{MORESOURCE} is not used. -@end deffn - -@deffn Method ede-proj-makefile-dependency-files :AFTER this -Return a list of source files to convert to dependencies. -Argument @var{THIS} is the target to get sources from. -@end deffn - - -@node ede-proj-target-makefile-archive, ede-proj-target-makefile-program, ede-proj-target-makefile-objectcode, Targets -@subsection ede-proj-target-makefile-archive -@tgindex ede-proj-target-makefile-archive - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item @w{@xref{ede-proj-target-makefile-objectcode}.} -@table @code -@item ede-proj-target-makefile-archive -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Create the make rule needed to create an archive for @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-insert-source-variables :PRIMARY this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -We aren't actually inserting SOURCE details, but this is used by the -Makefile.am generator, so use it to add this important bin program. -@end deffn - - -@node ede-proj-target-makefile-program, ede-proj-target-makefile-shared-object, ede-proj-target-makefile-archive, Targets -@subsection ede-proj-target-makefile-program -@tgindex ede-proj-target-makefile-program - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item @w{@xref{ede-proj-target-makefile-objectcode}.} -@table @code -@item ede-proj-target-makefile-program -@table @asis -@item Children: -@w{@xref{ede-proj-target-makefile-shared-object}.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :ldlibs -Type: @code{list} @* -Default Value: @code{nil} - -Libraries, such as "m" or "Xt" which this program depends on. -The linker flag "-l" is automatically prepended. Do not include a "lib" -prefix, or a ".so" suffix. - -Note: Currently only used for Automake projects. - -@item :ldflags -Type: @code{list} @* -Default Value: @code{nil} - -Additional flags to add when linking this target. -Use ldlibs to add addition libraries. Use this to specify specific -options to the linker. - -Note: Not currently used. This bug needs to be fixed. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method project-debug-target :AFTER obj -Debug a program target @var{OBJ}. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed by @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-post-variables :AFTER this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-pre-variables :AFTER this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -@end deffn - - -@node ede-proj-target-makefile-shared-object, ede-proj-target-elisp, ede-proj-target-makefile-program, Targets -@subsection ede-proj-target-makefile-shared-object -@tgindex ede-proj-target-makefile-shared-object - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item @w{@xref{ede-proj-target-makefile-objectcode}.} -@table @code -@item @w{@xref{ede-proj-target-makefile-program}.} -@table @code -@item ede-proj-target-makefile-shared-object -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method ede-proj-configure-add-missing :AFTER this -Query if any files needed by @var{THIS} provided by automake are missing. -Results in --add-missing being passed to automake. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-post-variables :AFTER this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -We need to override -program which has an LDADD element. -@end deffn - -@deffn Method ede-proj-makefile-target-name :AFTER this -Return the name of the main target for @var{THIS} target. -@end deffn - -@deffn Method ede-proj-makefile-insert-automake-pre-variables :AFTER this -Insert bin_PROGRAMS variables needed by target @var{THIS}. -We aren't actually inserting SOURCE details, but this is used by the -Makefile.am generator, so use it to add this important bin program. -@end deffn - - -@node ede-proj-target-elisp, ede-proj-target-elisp-autoloads, ede-proj-target-makefile-shared-object, Targets -@subsection ede-proj-target-elisp -@tgindex ede-proj-target-elisp - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item ede-proj-target-elisp -@table @asis -@item Children: -@w{@xref{ede-proj-target-elisp-autoloads}.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :aux-packages -Type: @code{list} @* -Default Value: @code{nil} - -Additional packages needed. -There should only be one toplevel package per auxiliary tool needed. -These packages location is found, and added to the compile time -load path. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method project-compile-target :AFTER obj -Compile all sources in a Lisp target @var{OBJ}. -Bonus: Return a cons cell: (COMPILED . UPTODATE). -@end deffn - -@deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-buffer-mine :AFTER this buffer -Return @code{t} if object @var{THIS} lays claim to the file in @var{BUFFER}. -Lays claim to all .elc files that match .el files in this target. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-update-version-in-source :AFTER this version -In a Lisp file, updated a version string for @var{THIS} to @var{VERSION}. -There are standards in Elisp files specifying how the version string -is found, such as a @code{-version} variable, or the standard header. -@end deffn - -@node ede-proj-target-elisp-autoloads, ede-proj-target-makefile-miscelaneous, ede-proj-target-elisp, Targets -@subsection ede-proj-target-elisp-autoloads -@tgindex ede-proj-target-elisp-autoloads - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item @w{@xref{ede-proj-target-elisp}.} -@table @code -@item ede-proj-target-elisp-autoloads -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :aux-packages -Type: @code{list} @* -Default Value: @code{("cedet-autogen")} - -@xref{ede-proj-target-elisp}. -@item :autoload-file -Type: @code{string} @* -Default Value: @code{"loaddefs.el"} - -The file that autoload definitions are placed in. -There should be one load defs file for a given package. The load defs are created -for all Emacs Lisp sources that exist in the directory of the created target. - -@item :autoload-dirs -Type: @code{list} @* -Default Value: @code{nil} - -The directories to scan for autoload definitions. -If @code{nil} defaults to the current directory. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-dependencies :AFTER this -Return a string representing the dependencies for @var{THIS}. -Always return an empty string for an autoloads generator. -@end deffn - -@deffn Method project-compile-target :AFTER obj -Create or update the autoload target. -@end deffn - -@deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-buffer-mine :AFTER this buffer -Return @code{t} if object @var{THIS} lays claim to the file in @var{BUFFER}. -Lays claim to all .elc files that match .el files in this target. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert any symbols that the DIST rule should depend on. -Emacs Lisp autoload files ship the generated .el files. -Argument @var{THIS} is the target which needs to insert an info file. -@end deffn - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-update-version-in-source :AFTER this version -In a Lisp file, updated a version string for @var{THIS} to @var{VERSION}. -There are standards in Elisp files specifying how the version string -is found, such as a @code{-version} variable, or the standard header. -@end deffn - -@deffn Method ede-proj-compilers :AFTER obj -List of compilers being used by @var{OBJ}. -If the @code{compiler} slot is empty, get the car of the compilers list. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-filepatterns :AFTER this -Insert any symbols that the DIST rule should distribute. -Emacs Lisp autoload files ship the generated .el files. -Argument @var{THIS} is the target which needs to insert an info file. -@end deffn - -@deffn Method ede-proj-makefile-insert-source-variables :AFTER this &optional moresource -Insert the source variables needed by @var{THIS}. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -@end deffn - - -@node ede-proj-target-makefile-miscelaneous, ede-proj-target-makefile-info, ede-proj-target-elisp-autoloads, Targets -@subsection ede-proj-target-makefile-miscelaneous -@tgindex ede-proj-target-makefile-miscelaneous - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item ede-proj-target-makefile-miscelaneous -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :submakefile -Type: @code{string} @* -Default Value: @code{""} - -Miscellaneous sources which have a specialized makefile. -The sub-makefile is used to build this target. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Create the make rule needed to create an archive for @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-dependency-files :AFTER this -Return a list of files which @var{THIS} target depends on. -@end deffn - - -@node ede-proj-target-makefile-info, ede-proj-target-scheme, ede-proj-target-makefile-miscelaneous, Targets -@subsection ede-proj-target-makefile-info -@tgindex ede-proj-target-makefile-info - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item @w{@xref{ede-proj-target-makefile}.} -@table @code -@item ede-proj-target-makefile-info -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :mainmenu -Type: @code{string} @* -Default Value: @code{""} - -The main menu resides in this file. -All other sources should be included independently. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-configure-add-missing :AFTER this -Query if any files needed by @var{THIS} provided by automake are missing. -Results in --add-missing being passed to automake. -@end deffn - -@deffn Method object-write :AFTER this -Before committing any change to @var{THIS}, make sure the mainmenu is first. -@end deffn - -@deffn Method ede-proj-makefile-sourcevar :AFTER this -Return the variable name for @var{THIS}'s sources. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-dependencies :AFTER this -Insert any symbols that the DIST rule should depend on. -Texinfo files want to insert generated `.info' files. -Argument @var{THIS} is the target which needs to insert an info file. -@end deffn - -@deffn Method ede-proj-makefile-target-name :AFTER this -Return the name of the main target for @var{THIS} target. -@end deffn - -@deffn Method ede-documentation :AFTER this -Return a list of files that provides documentation. -Documentation is not for object @var{THIS}, but is provided by @var{THIS} for other -files in the project. -@end deffn - -@deffn Method ede-proj-makefile-insert-dist-filepatterns :AFTER this -Insert any symbols that the DIST rule should depend on. -Texinfo files want to insert generated `.info' files. -Argument @var{THIS} is the target which needs to insert an info file. -@end deffn - -@deffn Method ede-proj-makefile-insert-source-variables :AFTER this &optional moresource -Insert the source variables needed by @var{THIS} info target. -Optional argument @var{MORESOURCE} is a list of additional sources to add to the -sources variable. -Does the usual for Makefile mode, but splits source into two variables -when working in Automake mode. -@end deffn - -@node ede-proj-target-scheme, project-am-target, ede-proj-target-makefile-info, Targets -@subsection ede-proj-target-scheme -@tgindex ede-proj-target-scheme - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{ede-proj-target}.} -@table @code -@item ede-proj-target-scheme -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :interpreter -Type: @code{string} @* -Default Value: @code{"guile"} - -The preferred interpreter for this code. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - - -@node project-am-target, project-am-objectcode, ede-proj-target-scheme, Targets -@subsection project-am-target -@tgindex project-am-target - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item project-am-target -@table @asis -@item Children: -@w{@xref{project-am-objectcode},} @w{project-am-header,} @w{@xref{project-am-lisp},} @w{@xref{project-am-texinfo},} @w{@xref{project-am-man}.} -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-compile-target-command :AFTER this -Default target to use when compiling a given target. -@end deffn - -@deffn Method project-make-dist :AFTER this -Run the current project in the debugger. -@end deffn - -@deffn Method project-edit-file-target :AFTER obj -Edit the target associated w/ this file. -@end deffn - -@node project-am-objectcode, project-am-program, project-am-target, Targets -@subsection project-am-objectcode -@tgindex project-am-objectcode - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item project-am-objectcode -@table @asis -@item Children: -@w{@xref{project-am-program},} @w{project-am-lib.} -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object type. -@end deffn - -@deffn Method project-debug-target :AFTER obj -Run the current project target in a debugger. -@end deffn - -@deffn Method project-compile-target-command :AFTER this -Default target to use when compiling an object code target. -@end deffn - -@deffn Method ede-buffer-header-file :AFTER this buffer -There are no default header files. -@end deffn - -@node project-am-program, project-am-header-noinst, project-am-objectcode, Targets -@subsection project-am-program -@tgindex project-am-program - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item @w{@xref{project-am-objectcode}.} -@table @code -@item project-am-program -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :ldadd @* -Default Value: @code{nil} - -Additional LD args. -@end table -@end table - -@node project-am-header-noinst, project-am-header-inst, project-am-program, Targets -@subsection project-am-header-noinst -@tgindex project-am-header-noinst - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item @w{project-am-header.} -@table @code -@item project-am-header-noinst -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object. -@end deffn - -@node project-am-header-inst, project-am-lisp, project-am-header-noinst, Targets -@subsection project-am-header-inst -@tgindex project-am-header-inst - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item @w{project-am-header.} -@table @code -@item project-am-header-inst -No children -@end table -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object. -@end deffn - -@node project-am-lisp, project-am-texinfo, project-am-header-inst, Targets -@subsection project-am-lisp -@tgindex project-am-lisp - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item project-am-lisp -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object. -@end deffn - -@node project-am-texinfo, project-am-man, project-am-lisp, Targets -@subsection project-am-texinfo -@tgindex project-am-texinfo - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item project-am-texinfo -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :include @* -Default Value: @code{nil} - -Additional texinfo included in this one. - -@end table -@end table -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object type. -@end deffn - -@deffn Method project-compile-target-command :AFTER this -Default target to use when compiling a texinfo file. -@end deffn - -@deffn Method ede-documentation :AFTER this -Return a list of files that provides documentation. -Documentation is not for object @var{THIS}, but is provided by @var{THIS} for other -files in the project. -@end deffn - -@node project-am-man, , project-am-texinfo, Targets -@comment node-name, next, previous, up -@subsection project-am-man -@tgindex project-am-man - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-speedbar -@table @code -@item eieio-speedbar-directory-button -@table @code -@item @w{@xref{ede-target}.} -@table @code -@item @w{@xref{project-am-target}.} -@table @code -@item project-am-man -No children -@end table -@end table -@end table -@end table -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method project-am-macro :AFTER this -Return the default macro to 'edit' for this object type. -@end deffn - -@node Sourcecode, Compilers, Targets, Extending EDE -@section Sourcecode - -The source code type is an object designed to associated files with -targets. - -@menu -* ede-sourcecode:: -@end menu - - -@node ede-sourcecode, , Sourcecode, Sourcecode -@subsection ede-sourcecode -@scindex ede-sourcecode - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item ede-sourcecode -No children -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :parent-instance -Type: @code{eieio-instance-inheritor-child} - -The parent of this instance. -If a slot of this class is reference, and is unbound, then the parent -is checked for a value. - -@item :name -Type: @code{string} - -The name of this type of source code. -Such as "C" or "Emacs Lisp" - -@item :sourcepattern -Type: @code{string} @* -Default Value: @code{".*"} - -Emacs regex matching sourcecode this target accepts. - -@item :auxsourcepattern -Type: @code{(or null string)} @* -Default Value: @code{nil} - -Emacs regex matching auxiliary source code this target accepts. -Aux source are source code files needed for compilation, which are not compiled -themselves. - -@item :enable-subdirectories -Type: @code{boolean} @* -Default Value: @code{nil} - -Non @code{nil} if this sourcecode type uses subdirectores. -If sourcecode always lives near the target creating it, this should be nil. -If sourcecode can, or typically lives in a subdirectory of the owning -target, set this to t. - -@item :garbagepattern -Type: @code{list} @* -Default Value: @code{nil} - -Shell file regex matching files considered as garbage. -This is a list of items added to an @code{rm} command when executing a @code{clean} -type directive. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-want-any-files-p :AFTER this filenames -Return non-@code{nil} if @var{THIS} will accept any files in @var{FILENAMES}. -@end deffn - -@deffn Method ede-want-any-source-files-p :AFTER this filenames -Return non-@code{nil} if @var{THIS} will accept any source files in @var{FILENAMES}. -@end deffn - -@deffn Method ede-want-any-auxiliary-files-p :AFTER this filenames -Return non-@code{nil} if @var{THIS} will accept any aux files in @var{FILENAMES}. -@end deffn - -@deffn Method ede-buffer-header-file :AFTER this filename -Return a list of file names of header files for @var{THIS} with @var{FILENAME}. -Used to guess header files, but uses the auxsource regular expression. -@end deffn - -@deffn Method ede-want-file-p :AFTER this filename -Return non-@code{nil} if sourcecode definition @var{THIS} will take @var{FILENAME}. -@end deffn - -@deffn Method ede-want-file-source-p :AFTER this filename -Return non-@code{nil} if @var{THIS} will take @var{FILENAME} as an auxiliary . -@end deffn - -@deffn Method ede-want-file-auxiliary-p :AFTER this filename -Return non-@code{nil} if @var{THIS} will take @var{FILENAME} as an auxiliary . -@end deffn - -@node Compilers, , Sourcecode, Extending EDE -@section Compilers - -The compiler object is designed to associate source code with -compilers. The target then references the compilers it can use. -When the makefile is created, this object type knows how to create -compile commands. - -@menu -* ede-compilation-program:: -* ede-compiler:: -* ede-object-compiler:: -* ede-linker:: -@end menu - - -@node ede-compilation-program, ede-compiler, Compilers, Compilers -@subsection ede-compilation-program -@cmindex ede-compilation-program - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item ede-compilation-program -@table @asis -@item Children: -@w{@xref{ede-compiler},} @w{@xref{ede-linker}.} -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :parent-instance -Type: @code{eieio-instance-inheritor-child} - -The parent of this instance. -If a slot of this class is reference, and is unbound, then the parent -is checked for a value. - -@item :name -Type: @code{string} - -Name of this type of compiler. - -@item :variables -Type: @code{list} - -Variables needed in the Makefile for this compiler. -An assoc list where each element is (VARNAME . VALUE) where VARNAME -is a string, and VALUE is either a string, or a list of strings. -For example, GCC would define CC=gcc, and emacs would define EMACS=emacs. - -@item :sourcetype -Type: @code{list} - -A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle. -This is used to match target objects with the compilers and linkers -they can use, and which files this object is interested in. - -@item :rules -Type: @code{list} @* -Default Value: @code{nil} - -Auxiliary rules needed for this compiler to run. -For example, yacc/lex files need additional chain rules, or inferences. - -@item :commands -Type: @code{list} - -The commands used to execute this compiler. -The object which uses this compiler will place these commands after -it's rule definition. - -@item :autoconf -Type: @code{list} @* -Default Value: @code{nil} - -Autoconf function to call if this type of compiler is used. -When a project is in Automake mode, this defines the autoconf function to -call to initialize automake to use this compiler. -For example, there may be multiple C compilers, but they all probably -use the same autoconf form. - -@item :objectextention -Type: @code{string} - -A string which is the extension used for object files. -For example, C code uses .o on unix, and Emacs Lisp uses .elc. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-flush-autoconf :AFTER this -Flush the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-insert-rules :AFTER this -Insert rules needed for @var{THIS} compiler object. -@end deffn - -@deffn Method ede-proj-makefile-insert-variables :AFTER this -Insert variables needed by the compiler @var{THIS}. -@end deffn - -@deffn Method ede-proj-makefile-insert-commands :AFTER this -Insert the commands needed to use compiler @var{THIS}. -The object creating makefile rules must call this method for the -compiler it decides to use after inserting in the rule. -@end deffn - -@deffn Method ede-object-sourcecode :AFTER this -Retrieves the slot @code{sourcetype} from an object of class @code{ede-compilation-program} -@end deffn - -@deffn Method ede-proj-tweak-autoconf :AFTER this -Tweak the configure file (current buffer) to accommodate @var{THIS}. -@end deffn - - -@node ede-compiler, ede-object-compiler, ede-compilation-program, Compilers -@subsection ede-compiler -@cmindex ede-compiler - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item @w{@xref{ede-compilation-program}.} -@table @code -@item ede-compiler -@table @asis -@item Children: -@w{@xref{ede-object-compiler},} @w{semantic-ede-grammar-compiler-class.} -@end table - -@end table - -@end table - -@end table -@end table - - Create a new object with name NAME of class type ede-compiler - -@table @asis -@item Slots: - -@table @code -@item :parent-instance -Type: @code{eieio-instance-inheritor-child} - -The parent of this instance. -If a slot of this class is reference, and is unbound, then the parent -is checked for a value. - -@item :name -Type: @code{string} - -Name of this type of compiler. - -@item :variables -Type: @code{list} - -Variables needed in the Makefile for this compiler. -An assoc list where each element is (VARNAME . VALUE) where VARNAME -is a string, and VALUE is either a string, or a list of strings. -For example, GCC would define CC=gcc, and emacs would define EMACS=emacs. - -@item :sourcetype -Type: @code{list} - -A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle. -This is used to match target objects with the compilers and linkers -they can use, and which files this object is interested in. - -@item :commands -Type: @code{list} - -The commands used to execute this compiler. -The object which uses this compiler will place these commands after -it's rule definition. - -@item :objectextention -Type: @code{string} - -A string which is the extension used for object files. -For example, C code uses .o on unix, and Emacs Lisp uses .elc. - -@item :makedepends -Type: @code{boolean} @* -Default Value: @code{nil} - -Non-@code{nil} if this compiler can make dependencies. - -@item :uselinker -Type: @code{boolean} @* -Default Value: @code{nil} - -Non-@code{nil} if this compiler creates code that can be linked. -This requires that the containing target also define a list of available -linkers that can be used. - -@end table - -@end table -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-insert-object-variables :AFTER this targetname sourcefiles -Insert an OBJ variable to specify object code to be generated for @var{THIS}. -The name of the target is @var{TARGETNAME} as a string. @var{SOURCEFILES} is the list of -files to be objectified. -Not all compilers do this. -@end deffn - -@deffn Method ede-compiler-intermediate-objects-p :AFTER this -Return non-@code{nil} if @var{THIS} has intermediate object files. -If this compiler creates code that can be linked together, -then the object files created by the compiler are considered intermediate. -@end deffn - -@deffn Method ede-compiler-intermediate-object-variable :AFTER this targetname -Return a string based on @var{THIS} representing a make object variable. -@var{TARGETNAME} is the name of the target that these objects belong to. -@end deffn - - -@node ede-object-compiler, ede-linker, ede-compiler, Compilers -@subsection ede-object-compiler -@cmindex ede-object-compiler - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item @w{@xref{ede-compilation-program}.} -@table @code -@item @w{@xref{ede-compiler}.} -@table @code -@item ede-object-compiler -No children -@end table -@end table -@end table -@end table -@end table - -@table @asis -@item Slots: - -@table @code -@item :uselinker -Type: @code{boolean} @* -Default Value: @code{t} - -@xref{ede-compiler}. -@item :dependencyvar -Type: @code{list} - -A variable dedicated to dependency generation. -@end table -@end table - -@subsubsection Specialized Methods - -@deffn Method ede-proj-makefile-insert-variables :AFTER this -Insert variables needed by the compiler @var{THIS}. -@end deffn - -@node ede-linker, , ede-object-compiler, Compilers -@subsection ede-linker -@cmindex ede-linker - -@table @asis -@item Inheritance Tree: -@table @code -@item eieio-instance-inheritor -@table @code -@item @w{@xref{ede-compilation-program}.} -@table @code -@item ede-linker -No children -@end table - -@end table - -@end table -@end table - - Create a new object with name NAME of class type ede-linker - -@table @asis -@item Slots: - -@table @code -@item :name -Type: @code{string} - -Name of this type of compiler. - -@item :variables -Type: @code{list} - -Variables needed in the Makefile for this compiler. -An assoc list where each element is (VARNAME . VALUE) where VARNAME -is a string, and VALUE is either a string, or a list of strings. -For example, GCC would define CC=gcc, and emacs would define EMACS=emacs. - -@item :sourcetype -Type: @code{list} - -A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle. -This is used to match target objects with the compilers and linkers -they can use, and which files this object is interested in. - -@item :commands -Type: @code{list} - -The commands used to execute this compiler. -The object which uses this compiler will place these commands after -it's rule definition. - -@item :objectextention -Type: @code{string} - -A string which is the extension used for object files. -For example, C code uses .o on unix, and Emacs Lisp uses .elc. - -@end table -@end table - -@node GNU Free Documentation License, , Extending EDE, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi deleted file mode 100644 index ea4bcc8f5b9..00000000000 --- a/doc/misc/ediff.texi +++ /dev/null @@ -1,2534 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c documentation for Ediff -@c Written by Michael Kifer - -@comment %**start of header (This is for running Texinfo on a region.) - -@comment Using ediff.info instead of ediff in setfilename breaks DOS. -@comment @setfilename ediff -@comment @setfilename ediff.info -@setfilename ../../info/ediff - -@settitle Ediff User's Manual -@documentencoding UTF-8 -@synindex vr cp -@synindex fn cp -@synindex pg cp -@synindex ky cp - -@iftex -@finalout -@end iftex -@c @smallbook -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -This file documents Ediff, a comprehensive visual interface to Unix diff -and patch utilities. - -Copyright @copyright{} 1995--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Ediff: (ediff). A visual interface for comparing and - merging programs. -@end direntry - -@titlepage -@title Ediff User's Manual -@sp 4 -@subtitle Ediff version 2.81.2 -@sp 1 -@subtitle November 2008 -@sp 5 -@author Michael Kifer -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top Ediff - -@insertcopying - -@menu -* Introduction:: About Ediff. -* Major Entry Points:: How to use Ediff. -* Session Commands:: Ediff commands used within a session. -* Registry of Ediff Sessions:: Keeping track of multiple Ediff sessions. -* Session Groups:: Comparing and merging directories. -* Remote and Compressed Files:: You may want to know about this. -* Customization:: How to make Ediff work the way YOU want. -* Credits:: Thanks to those who helped. -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - -@node Introduction -@chapter Introduction - -@cindex Comparing files and buffers -@cindex Merging files and buffers -@cindex Patching files and buffers -@cindex Finding differences - -Ediff provides a convenient way for simultaneous browsing through -the differences between a pair (or a triple) of files or buffers -(which are called @samp{variants} for our purposes). The -files being compared, file-A, file-B, and file-C (if applicable) are -shown in separate windows (side by side, one above the another, or in -separate frames), and the differences are highlighted as you step -through them. You can also copy difference regions from one buffer to -another (and recover old differences if you change your mind). - -Another powerful feature is the ability to merge a pair of files into a -third buffer. Merging with an ancestor file is also supported. -Furthermore, Ediff is equipped with directory-level capabilities that -allow the user to conveniently launch browsing or merging sessions on -groups of files in two (or three) different directories. - -In addition, Ediff can apply a patch to a file and then let you step through -both files, the patched and the original one, simultaneously, -difference-by-difference. You can even apply a patch right out of a mail -buffer, i.e., patches received by mail don't even have to be saved. Since -Ediff lets you copy differences between variants, you can, in effect, apply -patches selectively (i.e., you can copy a difference region from -@file{file.orig} to @file{file}, thereby undoing any particular patch that -you don't like). - -Ediff even understands multi-file patches and can apply them interactively! -(Ediff can recognize multi-file patches only if they are in the context -format or GNU unified format. All other patches are treated as 1-file -patches. Ediff is [hopefully] using the same algorithm as @code{patch} to -determine which files need to be patched.) - -Ediff is aware of version control, which lets you compare -files with their older versions. Ediff also works with remote and -compressed files, automatically ftp'ing them over and uncompressing them. -@xref{Remote and Compressed Files}, for details. - -This package builds upon ideas borrowed from Emerge, and several of Ediff's -functions are adaptations from Emerge. Although Ediff subsumes and greatly -extends Emerge, much of the functionality in Ediff is influenced by Emerge. -The architecture and the interface are, of course, drastically different. - -@node Major Entry Points -@chapter Major Entry Points - -When Ediff starts up, it displays a small control window, which accepts the -Ediff commands, and two or three windows displaying the files to be compared -or merged. The control window can be in its own small frame or it can be -part of a bigger frame that displays other buffers. In any case, it is -important that the control window be active (i.e., be the one receiving the -keystrokes) when you use Ediff. You can switch to other Emacs buffers at -will and even edit the files currently being compared with Ediff and then -switch back to Ediff at any time by activating the appropriate Emacs windows. - -Ediff can be invoked interactively using the following functions, which can -be run either from the minibuffer or from the menu bar. In the menu bar, -all Ediff's entry points belong to three submenus of the Tools menu: -Compare, Merge, and Apply Patch. - -@table @code -@item ediff-files -@itemx ediff -@findex ediff-files -@findex ediff -Compare two files. - -@item ediff-backup -@findex ediff-backup -Compare a file with its backup. If there are several numerical backups, use -the latest. If the file is itself a backup, then compare it with its -original. - -@item ediff-current-file -@findex ediff-current-file -Compare the buffer with its file on disk. This function can be used as a -safe version of @code{revert-buffer}. - -@item ediff-buffers -@findex ediff-buffers -Compare two buffers. - -@item ediff-files3 -@itemx ediff3 -@findex ediff-files3 -@findex ediff3 -Compare three files. - -@item ediff-buffers3 -@findex ediff-buffers3 -Compare three buffers. - -@item edirs -@itemx ediff-directories -@findex edirs -@findex ediff-directories - Compare files common to two directories. -@item edirs3 -@itemx ediff-directories3 -@findex edirs3 -@findex ediff-directories3 - Compare files common to three directories. -@item edir-revisions -@itemx ediff-directory-revisions -@findex ediff-directory-revisions -@findex edir-revisions - Compare versions of files in a given directory. Ediff selects only the -files that are under version control. -@item edir-merge-revisions -@itemx ediff-merge-directory-revisions -@findex edir-merge-revisions -@findex ediff-merge-directory-revisions - Merge versions of files in a given directory. Ediff selects only the -files that are under version control. -@item edir-merge-revisions-with-ancestor -@itemx ediff-merge-directory-revisions-with-ancestor -@findex edir-merge-revisions-with-ancestor -@findex ediff-merge-directory-revisions-with-ancestor - Merge versions of files in a given directory using other versions as -ancestors. Ediff selects only the files that are under version control. - -@item ediff-windows-wordwise -@findex ediff-windows-wordwise -Compare windows word-by-word. - -@item ediff-windows-linewise -@findex ediff-windows-linewise -Compare windows line-by-line. - -@item ediff-regions-wordwise -@findex ediff-regions-wordwise -Compare regions word-by-word. The regions can come from the same buffer -and they can even overlap. You will be asked to specify the buffers that -contain the regions, which you want to compare. For each buffer, you will -also be asked to mark the regions to be compared. Pay attention to the -messages that appear in the minibuffer. - -@item ediff-regions-linewise -@findex ediff-regions-linewise -Similar to @code{ediff-windows-linewise}, but compares the regions -line-by-line. See @code{ediff-windows-linewise} for more details. - -@item ediff-revision -@findex ediff-revision - Compare versions of the current buffer, if the buffer is visiting - a file under version control. - -@item ediff-patch-file -@itemx epatch -@findex ediff-patch-file -@findex epatch - -Patch a file or multiple files, then compare. If the patch applies to just -one file, Ediff will invoke a regular comparison session. If it is a -multi-file patch, then a session group interface will be used and the user -will be able to patch the files selectively. @xref{Session Groups}, for -more details. - -Since the patch might be in a buffer or a file, you will be asked which is -the case. To avoid this extra prompt, you can invoke this command with a -prefix argument. With an odd prefix argument, Ediff assumes the patch -is in a file; with an even argument, a buffer is assumed. - -Note that @code{ediff-patch-file} will actually use the @code{patch} -utility to change the original files on disk. This is not that -dangerous, since you will always have the original contents of the file -saved in another file that has the extension @file{.orig}. -Furthermore, if the file is under version control, then you can always back -out to one of the previous versions (see the section on Version Control in -the Emacs manual). - -@code{ediff-patch-file} is careful about versions control: if the file -to be patched is checked in, then Ediff will offer to check it out, because -failing to do so may result in the loss of the changes when the file is -checked out the next time. - -If you don't intend to modify the file via the patch and just want to see -what the patch is all about (and decide later), then -@code{ediff-patch-buffer} might be a better choice. - -@item ediff-patch-buffer -@itemx epatch-buffer -@findex ediff-patch-buffer -@findex epatch-buffer -Patch a buffer, then compare. The buffer being patched and the file visited -by that buffer (if any) is @emph{not} modified. The result of the patch -appears in some other buffer that has the name ending with @emph{_patched}. - -This function would refuse to apply a multifile patch to a buffer. Use -@code{ediff-patch-file} for that (and when you want the original file to be -modified by the @code{patch} utility). - -Since the patch might be in a buffer or a file, you will be asked which is -the case. To avoid this extra prompt, you can invoke this command with a -prefix argument. With an odd prefix argument, Ediff assumes the patch -is in a file; with an even argument, a buffer is assumed. - -@item ediff-merge-files -@itemx ediff-merge -@findex ediff-merge-files -@findex ediff-merge -Merge two files. - -@item ediff-merge-files-with-ancestor -@itemx ediff-merge-with-ancestor -@findex ediff-merge-files-with-ancestor -@findex ediff-merge-with-ancestor -Like @code{ediff-merge}, but with a third ancestor file. - -@item ediff-merge-buffers -@findex ediff-merge-buffers -Merge two buffers. - -@item ediff-merge-buffers-with-ancestor -@findex ediff-merge-buffers-with-ancestor -Same but with ancestor. - - -@item edirs-merge -@itemx ediff-merge-directories -@findex edirs-merge -@findex ediff-merge-directories - Merge files common to two directories. -@item edirs-merge-with-ancestor -@itemx ediff-merge-directories-with-ancestor -@findex edirs-merge-with-ancestor -@findex ediff-merge-directories-with-ancestor - Same but using files in a third directory as ancestors. - If a pair of files doesn't have an ancestor in the ancestor-directory, you - will still be able to merge them without the ancestor. - -@item ediff-merge-revisions -@findex ediff-merge-revisions -Merge two versions of the file visited by the current buffer. - -@item ediff-merge-revisions-with-ancestor -@findex ediff-merge-revisions-with-ancestor -Same but with ancestor. - -@item ediff-documentation -@findex ediff-documentation -Brings up this manual. - -@item ediff-show-registry -@itemx eregistry -Brings up Ediff session registry. This feature enables you to quickly find -and restart active Ediff sessions. -@end table - -When the above functions are invoked, the user is prompted for all the -necessary information---typically the files or buffers to compare, merge, or -patch. Ediff tries to be smart about these prompts. For instance, in -comparing/merging files, it will offer the visible buffers as defaults. In -prompting for files, if the user enters a directory, the previously input -file name will be appended to that directory. In addition, if the variable -@code{ediff-use-last-dir} is not @code{nil}, Ediff will offer -previously entered directories as defaults (which will be maintained -separately for each type of file, A, B, or C). -@vindex @code{ediff-use-last-dir} - -All the above functions use the POSIX @code{diff} or @code{diff3} programs -to find differences between two files. They process the @code{diff} output -and display it in a convenient form. At present, Ediff understands only -the plain output from diff. Options such as @samp{-c} are not supported, -nor is the format produced by incompatible file comparison programs such as -the VMS version of @code{diff}. - -The functions @code{ediff-files}, @code{ediff-buffers}, -@code{ediff-files3}, @code{ediff-buffers3} first display the coarse, -line-based difference regions, as reported by the @code{diff} program. The -total number of difference regions and the current difference number are -always displayed in the mode line of the control window. - -Since @code{diff} may report fairly large chunks of text as being different, -even though the difference may be localized to just a few words or even -to the white space or line breaks, Ediff further @emph{refines} the -regions to indicate which exact words differ. If the only difference is -in the white space and line breaks, Ediff says so. - -On a color display, fine differences are highlighted with color; on a -monochrome display, they are underlined. @xref{Highlighting Difference -Regions}, for information on how to customize this. - -The commands @code{ediff-windows-wordwise}, -@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and -@code{ediff-regions-linewise} do comparison on parts of existing Emacs -buffers. The commands @code{ediff-windows-wordwise} and -@code{ediff-regions-wordwise} are intended for relatively small segments -of buffers (e.g., up to 100 lines, depending on the speed of your machine), -as they perform comparison on the basis of words rather than lines. -(Word-wise comparison of large chunks of text can be slow.) - -To compare large regions, use @code{ediff-regions-linewise}. This -command displays differences much like @code{ediff-files} and -@code{ediff-buffers}. - -The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a -patch to a file or a buffer and then run Ediff on the appropriate -files/buffers, displaying the difference regions. - -The entry points @code{ediff-directories}, @code{ediff-merge-directories}, -etc., provide a convenient interface for comparing and merging files in -different directories. The user is presented with Dired-like interface from -which one can run a group of related Ediff sessions. - -For files under version control, @code{ediff-revision} lets you compare -the file visited by the current buffer to one of its checked-in versions. -You can also compare two checked-in versions of the visited file. -Moreover, the functions @code{ediff-directory-revisions}, -@code{ediff-merge-directory-revisions}, etc., let you run a group of -related Ediff sessions by taking a directory and comparing (or merging) -versions of files in that directory. - -@node Session Commands -@chapter Session Commands - -All Ediff commands are displayed in a Quick Help window, unless you type -@kbd{?} to shrink the window to just one line. You can redisplay the help -window by typing @kbd{?} again. The Quick Help commands are detailed below. - -Many Ediff commands take numeric prefix arguments. For instance, if you -type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}), -Ediff moves to the third difference region. Typing 3 and then @kbd{a} -(@code{ediff-diff-to-diff}) copies the 3rd difference region from variant A -to variant B@. Likewise, 4 followed by @kbd{ra} restores the 4th difference -region in buffer A (if it was previously written over via the command -@kbd{a}). - -Some commands take negative prefix arguments as well. For instance, typing -@kbd{-} and then @kbd{j} will make the last difference region -current. Typing @kbd{-2} then @kbd{j} makes the penultimate difference -region current, etc. - -Without the prefix argument, all commands operate on the currently -selected difference region. You can make any difference region -current using the various commands explained below. - -For some commands, the actual value of the prefix argument is -immaterial. However, if supplied, the prefix argument may modify the -command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}). - -@menu -* Quick Help Commands:: Frequently used commands. -* Other Session Commands:: Commands that are not bound to keys. -@end menu - -@node Quick Help Commands -@section Quick Help Commands -@cindex command help -@cindex important commands - -@table @kbd -@item ? -@kindex ? -Toggles the Ediff Quick Help window ON and OFF. -@item G -@kindex G -Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer. - -@item E -@kindex E -Brings up the top node of this manual, where you can find further -information on the various Ediff functions and advanced issues, such as -customization, session groups, etc. - -@item v -@kindex v -Scrolls up buffers A and B (and buffer C where appropriate) in a -coordinated fashion. -@item V -@kindex V -Scrolls the buffers down. - -@item < -@kindex < -Scrolls the buffers to the left simultaneously. -@item > -@kindex > -Scrolls buffers to the right. - -@item wd -@kindex wd -Saves the output from the diff utility, for further reference. - -With prefix argument, saves the plain output from @code{diff} (see -@code{ediff-diff-program} and @code{ediff-diff-options}). Without the -argument, it saves customized @code{diff} output (see -@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if -it is available. - -@item wa -@kindex wa -Saves buffer A, if it was modified. -@item wb -@kindex wb -Saves buffer B, if it was modified. -@item wc -@kindex wc -Saves buffer C, if it was modified (if you are in a session that -compares three files simultaneously). - -@item a -@kindex a -@emph{In comparison sessions:} -Copies the current difference region (or the region specified as the prefix -to this command) from buffer A to buffer B@. -Ediff saves the old contents of buffer B's region; it can -be restored via the command @kbd{rb}, which see. - -@emph{In merge sessions:} -Copies the current difference region (or the region specified as the prefix -to this command) from buffer A to the merge buffer. The old contents of -this region in buffer C can be restored via the command @kbd{r}. - -@item b -@kindex b -Works similarly, but copies the current difference region from buffer B to -buffer A (in @emph{comparison sessions}) or the merge buffer (in -@emph{merge sessions}). - -Ediff saves the old contents of the difference region copied over; it can -be reinstated via the command @kbd{ra} in comparison sessions and -@kbd{r} in merge sessions. - -@item ab -@kindex ab -Copies the current difference region (or the region specified as the prefix -to this command) from buffer A to buffer B@. This (and the next five) -command is enabled only in sessions that compare three files -simultaneously. The old region in buffer B is saved and can be restored -via the command @kbd{rb}. -@item ac -@kindex ac -Copies the difference region from buffer A to buffer C@. -The old region in buffer C is saved and can be restored via the command -@kbd{rc}. -@item ba -@kindex ba -Copies the difference region from buffer B to buffer A@. -The old region in buffer A is saved and can be restored via the command -@kbd{ra}. -@item bc -@kindex bc -Copies the difference region from buffer B to buffer C@. -The command @kbd{rc} undoes this. -@item ca -@kindex ca -Copies the difference region from buffer C to buffer A@. -The command @kbd{ra} undoes this. -@item cb -@kindex cb -Copies the difference region from buffer C to buffer B@. -The command @kbd{rb} undoes this. - -@item p -@itemx DEL -@kindex p -@kindex DEL -Makes the previous difference region current. -@item n -@itemx SPC -@kindex n -@kindex SPC -Makes the next difference region current. - -@item j -@itemx -j -@itemx Nj -@kindex j -Makes the very first difference region current. - -@kbd{-j} makes the last region current. Typing a number, N, and then `j' -makes the difference region N current. Typing @minus{}N (a negative number) then -`j' makes current the region Last @minus{} N. - -@item ga -@kindex ga -Makes current the difference region closest to the position of the point in -buffer A. - -However, with a prefix argument, Ediff would position all variants -around the area indicated by the current point in buffer A: if -the point is inside a difference region, then the variants will be -positioned at this difference region. If the point is not in any difference -region, then it is in an area where all variants agree with each other. In -this case, the variants will be positioned so that each would display this -area (of agreement). -@item gb -@kindex gb -Makes current the difference region closest to the position of the point in -buffer B. - -With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B. -@item gc -@kindex gc -@emph{In merge sessions:} -makes current the difference region closest to the point in the merge buffer. - -@emph{In 3-file comparison sessions:} -makes current the region closest to the point in buffer C. - -With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C. - -@item ! -@kindex ! -Recomputes the difference regions, bringing them up to date. This is often -needed because it is common to do all sorts of editing during Ediff -sessions, so after a while, the highlighted difference regions may no -longer reflect the actual differences among the buffers. - -@item * -@kindex * -Forces refinement of the current difference region, which highlights the exact -words of disagreement among the buffers. With a negative prefix argument, -unhighlights the current region. - -Forceful refinement may be needed if Ediff encounters a difference region -that is larger than @code{ediff-auto-refine-limit}. In this situation, -Ediff doesn't do automatic refinement in order to improve response time. -(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still -works there. However, the only useful piece of information it can tell you -is whether or not the difference regions disagree only in the amount of -white space.) - -This command is also useful when the highlighted fine differences are -no longer current, due to user editing. - -@item m -@kindex m -Displays the current Ediff session in a frame as wide as the physical -display. This is useful when comparing files side-by-side. Typing `m' again -restores the original size of the frame. - -@item | -@kindex | -Toggles the horizontal/vertical split of the Ediff display. Horizontal -split is convenient when it is possible to compare files -side-by-side. If the frame in which files are displayed is too narrow -and lines are cut off, typing @kbd{m} may help some. - -@item @@ -@kindex @@ -Toggles auto-refinement of difference regions (i.e., automatic highlighting -of the exact words that differ among the variants). Auto-refinement is -turned off on devices where Emacs doesn't support highlighting. - -On slow machines, it may be advantageous to turn auto-refinement off. The -user can always forcefully refine specific difference regions by typing -@kbd{*}. - -@item h -@kindex h -Cycles between full highlighting, the mode where fine differences are not -highlighted (but computed), and the mode where highlighting is done with -@acronym{ASCII} strings. The latter is not really recommended, unless on a dumb TTY. - -@item r -@kindex r -Restores the old contents of the region in the merge buffer. -(If you copied a difference region from buffer A or B into the merge buffer -using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the -region in case you change your mind.) - -This command is enabled in merge sessions only. - -@item ra -@kindex ra -Restores the old contents of the current difference region in buffer A, -which was previously saved when the user invoked one of these commands: -@kbd{b}, @kbd{ba}, @kbd{ca}, which see. This command is enabled in -comparison sessions only. -@item rb -@kindex rb -Restores the old contents of the current difference region in buffer B, -which was previously saved when the user invoked one of these commands: -@kbd{a}, @kbd{ab}, @kbd{cb}, which see. This command is enabled in -comparison sessions only. -@item rc -@kindex rc -Restores the old contents of the current difference region in buffer C, -which was previously saved when the user invoked one of these commands: -@kbd{ac}, @kbd{bc}, which see. This command is enabled in 3-file -comparison sessions only. - -@item ## -@kindex ## -Tell Ediff to skip over regions that disagree among themselves only in the -amount of white space and line breaks. - -Even though such regions will be skipped over, you can still jump to any -one of them by typing the region number and then `j'. Typing @kbd{##} -again puts Ediff back in the original state. - -@item #c -@kindex #c -@vindex ediff-ignore-case-option -@vindex ediff-ignore-case-option3 -@vindex ediff-ignore-case -Toggle case sensitivity in the diff program. All diffs are recomputed. -Case sensitivity is controlled by the variables -@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, -and @code{ediff-ignore-case}, which are explained elsewhere. - -@item #h -@itemx #f -@kindex #f -@kindex #h -Ediff works hard to ameliorate the effects of boredom in the workplace... - -Quite often differences are due to identical replacements (e.g., the word -`foo' is replaced with the word `bar' everywhere). If the number of regions -with such boring differences exceeds your tolerance threshold, you may be -tempted to tell Ediff to skip these regions altogether (you will still be able -to jump to them via the command @kbd{j}). The above commands, @kbd{#h} -and @kbd{#f}, may well save your day! - -@kbd{#h} prompts you to specify regular expressions for each -variant. Difference regions where each variant's region matches the -corresponding regular expression will be skipped from then on. (You can -also tell Ediff to skip regions where at least one variant matches its -regular expression.) - -@kbd{#f} does dual job: it focuses on regions that match the corresponding -regular expressions. All other regions will be skipped -over. @xref{Selective Browsing}, for more. - -@item A -@kindex A -Toggles the read-only property in buffer A@. -If file A is under version control and is checked in, it is checked out -(with your permission). -@item B -@kindex B -Toggles the read-only property in buffer B@. -If file B is under version control and is checked in, it is checked out. -@item C -@kindex C -Toggles the read-only property in buffer C (in 3-file comparison sessions). -If file C is under version control and is checked in, it is checked out. - -@item ~ -@kindex ~ -Swaps the windows where buffers A and B are displayed. If you are comparing -three buffers at once, then this command would rotate the windows among -buffers A, B, and C. - -@item i -@kindex i -Displays all kinds of useful data about the current Ediff session. -@item D -@kindex D -Runs @code{ediff-custom-diff-program} on the variants and displays the -buffer containing the output. This is useful when you must send the output -to your Mom. - -With a prefix argument, displays the plain @code{diff} output. -@xref{Patch and Diff Programs}, for details. - -@item R -@kindex R -Displays a list of currently active Ediff sessions---the Ediff Registry. -You can then restart any of these sessions by either clicking on a session -record or by putting the cursor over it and then typing the return key. - -(Some poor souls leave so many active Ediff sessions around that they lose -track of them completely... The `R' command is designed to save these -people from the recently discovered Ediff Proficiency Syndrome.) - -Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff -Control Panel. If you don't have a control panel handy, type this in the -minibuffer: @kbd{M-x eregistry}. @xref{Registry of Ediff Sessions}. - -@item M -@kindex M -Shows the session group buffer that invoked the current Ediff session. -@xref{Session Groups}, for more information on session groups. - -@item z -@kindex z -Suspends the current Ediff session. (If you develop a condition known as -Repetitive Ediff Injury---a serious but curable illness---you must change -your current activity. This command tries hard to hide all Ediff-related -buffers.) - -The easiest way to resume a suspended Ediff session is through the registry -of active sessions. @xref{Registry of Ediff Sessions}, for details. -@item q -@kindex q -Terminates this Ediff session. With a prefix argument (e.g.,@kbd{1q}), asks -if you also want to delete the buffers of the variants. -Modified files and the results of merges are never deleted. - -@item % -@kindex % -Toggles narrowing in Ediff buffers. Ediff buffers may be narrowed if you -are comparing only parts of these buffers via the commands -@code{ediff-windows-*} and @code{ediff-regions-*}, which see. - -@item C-l -@kindex C-l -Restores the usual Ediff window setup. This is the quickest way to resume -an Ediff session, but it works only if the control panel of that session is -visible. - -@item $$ -@kindex $$ -While merging with an ancestor file, Ediff is determined to reduce user's -wear and tear by saving him and her much of unproductive, repetitive -typing. If it notices that, say, file A's difference region is identical to -the same difference region in the ancestor file, then the merge buffer will -automatically get the difference region taken from buffer B@. The rationale -is that this difference region in buffer A is as old as that in the -ancestor buffer, so the contents of that region in buffer B represents real -change. - -You may want to ignore such `obvious' merges and concentrate on difference -regions where both files `clash' with the ancestor, since this means that -two different people have been changing this region independently and they -had different ideas on how to do this. - -The above command does this for you by skipping the regions where only one -of the variants clashes with the ancestor but the other variant agrees with -it. Typing @kbd{$$} again undoes this setting. - -@item $* -@kindex $* -When merging files with large number of differences, it is sometimes -convenient to be able to skip the difference regions for which you already -decided which variant is most appropriate. Typing @kbd{$*} will accomplish -precisely this. - -To be more precise, this toggles the check for whether the current merge is -identical to its default setting, as originally decided by Ediff. For -instance, if Ediff is merging according to the `combined' policy, then the -merge region is skipped over if it is different from the combination of the -regions in buffers A and B@. (Warning: swapping buffers A and B will confuse -things in this respect.) If the merge region is marked as `prefer-A' then -this region will be skipped if it differs from the current difference -region in buffer A, etc. - -@item / -@kindex / -Displays the ancestor file during merges. -@item & -@kindex & -In some situations, such as when one of the files agrees with the ancestor file -on a difference region and the other doesn't, Ediff knows what to do: it copies -the current difference region from the second buffer into the merge buffer. - -In other cases, the right course of action is not that clearcut, and Ediff -would use a default action. The above command changes the default action. -The default action can be @samp{default-A} (choose the region from buffer -A), @samp{default-B} (choose the region from buffer B), or @samp{combined} -(combine the regions from the two buffers). -@xref{Merging and diff3}, for further details. - -The command @kbd{&} also affects the regions in the merge buffers that have -@samp{default-A}, @samp{default-B}, or @samp{combined} status, provided -they weren't changed with respect to the original. For instance, if such a -region has the status @samp{default-A} then changing the default action to -@samp{default-B} will also replace this merge-buffer's region with the -corresponding region from buffer B. - -@item s -@kindex s -Causes the merge window shrink to its minimum size, thereby exposing as much -of the variant buffers as possible. Typing `s' again restores -the original size of that window. - -With a positive prefix argument, this command enlarges the merge window. -E.g., @kbd{4s} increases the size of the window by about 4 lines, if -possible. With a negative numeric argument, the size of the merge window -shrinks by that many lines, if possible. Thus, @kbd{-s} shrinks the window -by about 1 line and @kbd{-3s} by about 3 lines. - -This command is intended only for temporary viewing; therefore, Ediff -restores window C to its original size whenever it makes any other change -in the window configuration. However, redisplaying (@kbd{C-l}) or jumping -to another difference does not affect window C's size. - -The split between the merge window and the variant windows is controlled by -the variable @code{ediff-merge-window-share}, which see. - -@item + -@kindex + -Combines the difference regions from buffers A and B and copies the -result into the merge buffer. @xref{Merging and diff3}, and the -variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}. - - -@item = -@kindex = -You may run into situations when a large chunk of text in one file has been -edited and then moved to a different place in another file. In such a case, -these two chunks of text are unlikely to belong to the same difference -region, so the refinement feature of Ediff will not be able to tell you -what exactly differs inside these chunks. Since eyeballing large pieces of -text is contrary to human nature, Ediff has a special command to help -reduce the risk of developing a cataract. - -In other situations, the currently highlighted region might be big and you -might want to reconcile of them interactively. - -All of this can be done with the above command, @kbd{=}, which -compares regions within Ediff buffers. Typing @kbd{=} creates a -child Ediff session for comparing regions in buffers A, B, or -C as follows. - -First, you will be asked whether you want to compare the fine differences -between the currently highlighted buffers on a word-by-word basis. If you -accept, a child Ediff session will start using the currently highlighted -regions. Ediff will let you step over the differences word-wise. - -If you reject the offer, you will be asked to select regions of your choice. - -@emph{If you are comparing 2 files or buffers:} -Ediff will ask you to select regions in buffers A and B. - -@emph{If you are comparing 3 files or buffers simultaneously:} Ediff will -ask you to choose buffers and then select regions inside those buffers. - -@emph{If you are merging files or buffers (with or without ancestor):} -Ediff will ask you to choose which buffer (A or B) to compare with the -merge buffer and then select regions in those buffers. - -@end table - -@node Other Session Commands -@section Other Session Commands - -The following commands can be invoked from within any Ediff session, -although some of them are not bound to a key. - -@table @code -@item eregistry -@itemx ediff-show-registry -@findex eregistry -@findex ediff-show-registry -This command brings up the registry of active Ediff sessions. Ediff -registry is a device that can be used to resume any active Ediff session -(which may have been postponed because the user switched to some other -activity). This command is also useful for switching between multiple -active Ediff sessions that are run at the same time. The function -@code{eregistry} is an alias for @code{ediff-show-registry}. -@xref{Registry of Ediff Sessions}, for more information on this registry. - -@item ediff-toggle-multiframe -@findex ediff-toggle-multiframe -Changes the display from the multi-frame mode (where the quick help window -is in a separate frame) to the single-frame mode (where all Ediff buffers -share the same frame), and vice versa. See -@code{ediff-window-setup-function} for details on how to make either of -these modes the default one. - -This function can also be invoked from the Menubar. However, in some -cases, the change will take place only after you execute one of the Ediff -commands, such as going to the next difference or redisplaying. - -@item ediff-toggle-use-toolbar -@findex ediff-toggle-use-toolbar -Available in XEmacs only. The Ediff toolbar provides quick access to some -of the common Ediff functions. This function toggles the display of the -toolbar. If invoked from the menubar, the function may take sometimes -effect only after you execute an Ediff command, such as going to the next -difference. - -@item ediff-use-toolbar-p -@vindex ediff-use-toolbar-p -The use of the toolbar can also be specified via the variable -@code{ediff-use-toolbar-p} (default is @code{t}). This variable can be set -only in @file{.emacs}: do @strong{not} change it interactively. Use the -function @code{ediff-toggle-use-toolbar} instead. - -@item ediff-revert-buffers-then-recompute-diffs -@findex ediff-revert-buffers-then-recompute-diffs -This command reverts the buffers you are comparing and recomputes their -differences. It is useful when, after making changes, you decided to -make a fresh start, or if at some point you changed the files being -compared but want to discard any changes to comparison buffers that were -done since then. - -This command normally asks for confirmation before reverting files. -With a prefix argument, it reverts files without asking. - - -@item ediff-profile -@findex ediff-profile -Ediff has an admittedly primitive (but useful) facility for profiling -Ediff's commands. It is meant for Ediff maintenance---specifically, for -making it run faster. The function @code{ediff-profile} toggles -profiling of ediff commands. -@end table - -@node Registry of Ediff Sessions -@chapter Registry of Ediff Sessions - -Ediff maintains a registry of all its invocations that are -still @emph{active}. This feature is very convenient for switching among -active Ediff sessions or for quickly restarting a suspended Ediff session. - -The focal point of this activity is a buffer -called @emph{*Ediff Registry*}. You can display this buffer by typing -@kbd{R} in any Ediff Control Buffer or Session Group Buffer -(@pxref{Session Groups}), or by typing -@kbd{M-x eregistry} into the Minibuffer. -The latter would be the fastest way to bring up the registry -buffer if no control or group buffer is displayed in any of the visible -Emacs windows. -If you are in a habit of running multiple long Ediff sessions and often need to -suspend, resume, or switch between them, it may be a good idea to have the -registry buffer permanently displayed in a separate, dedicated window. - -The registry buffer has several convenient key bindings. -For instance, clicking mouse button 2 or typing -@kbd{RET} or @kbd{v} over any session record resumes that session. -Session records in the registry buffer provide a fairly complete -description of each session, so it is usually easy to identify the right -session to resume. - -Other useful commands are bound to @kbd{SPC} (next registry record) -and @kbd{DEL} (previous registry record). There are other commands as well, -but you don't need to memorize them, since they are listed at the top of -the registry buffer. - -@node Session Groups -@chapter Session Groups - -Several major entries of Ediff perform comparison and merging on -directories. On entering @code{ediff-directories}, -@code{ediff-directories3}, -@code{ediff-merge-directories}, -@code{ediff-merge-directories-with-ancestor}, -@code{ediff-directory-revisions}, -@code{ediff-merge-directory-revisions}, or -@code{ediff-merge-directory-revisions-with-ancestor}, -the user is presented with a -Dired-like buffer that lists files common to the directories involved along -with their sizes. (The list of common files can be further filtered through -a regular expression, which the user is prompted for.) We call this buffer -@emph{Session Group Panel} because all Ediff sessions associated with the -listed files will have this buffer as a common focal point. - -Clicking button 2 or typing @kbd{RET} or @kbd{v} over a -record describing files invokes Ediff in the appropriate mode on these -files. You can come back to the session group buffer associated with a -particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of -that invocation. - -Many commands are available in the session group buffer; some are -applicable only to certain types of work. The relevant commands are always -listed at the top of each session group buffer, so there is no need to -memorize them. - -In directory comparison or merging, a session group panel displays only the -files common to all directories involved. The differences are kept in a -separate @emph{directory difference buffer} and are conveniently displayed -by typing @kbd{D} to the corresponding session group panel. Thus, as an -added benefit, Ediff can be used to compare the contents of up to three -directories. - -@cindex Directory difference buffer -Sometimes it is desirable to copy some files from one directory to another -without exiting Ediff. The @emph{directory difference buffer}, which is -displayed by typing @kbd{D} as discussed above, can be used for this -purpose. If a file is, say, in Ediff's Directory A, but is missing in -Ediff's Directory B (Ediff will refuse to override existing files), then -typing @kbd{C} or clicking mouse button 2 over that file (which must be -displayed in directory difference buffer) will copy that file from -Directory A to Directory B. - -Session records in session group panels are also marked with @kbd{+}, for -active sessions, and with @kbd{-}, for finished sessions. - -Sometimes, it is convenient to exclude certain sessions from a group. -Usually this happens when the user doesn't intend to run Ediff of certain -files in the group, and the corresponding session records just add clutter -to the session group buffer. To help alleviate this problem, the user can -type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to -actually hide the marked sessions. There actions are reversible: with a -prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x} -brings the hidden sessions into the view (@kbd{x} doesn't unmark them, -though, so the user has to explicitly unmark the sessions of interest). - -Group sessions also understand the command @kbd{m}, which marks sessions -for future operations (other than hiding) on a group of sessions. At present, -the only such group-level operation is the creation of a multi-file patch. - -@vindex ediff-autostore-merges -For group sessions created to merge files, Ediff can store all merges -automatically in a directory. The user is asked to specify such directory -if the value of @code{ediff-autostore-merges} is non-@code{nil}. If the value is -@code{nil}, nothing is done to the merge buffers---it will be the user's -responsibility to save them. If the value is @code{t}, the user will be -asked where to save the merge buffers in all merge jobs, even those that do -not originate from a session group. It the value is neither @code{nil} nor -@code{t}, the merge buffer is saved @emph{only} if this merge session was -invoked from a session group. This behavior is implemented in the function -@code{ediff-maybe-save-and-delete-merge}, which is a hook in -@code{ediff-quit-merge-hook}. The user can supply a different hook, if -necessary. - -The variable @code{ediff-autostore-merges} is buffer-local, so it can be -set on a per-buffer basis. Therefore, use @code{setq-default} to change -this variable globally. - -@cindex Multi-file patches -A multi-file patch is a concatenated output of several runs of the Unix -@code{diff} command (some versions of @code{diff} let you create a -multi-file patch in just one run). Ediff facilitates creation of -multi-file patches as follows. If you are in a session group buffer -created in response to @code{ediff-directories} or -@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the -desired Ediff sessions and then type @kbd{P} to create a -multi-file patch of those marked sessions. -Ediff will then display a buffer containing the patch. -The patch is generated by invoking @code{diff} on all marked individual -sessions (represented by files) and session groups (represented by -directories). Ediff will also recursively descend into any @emph{unmarked} -session group and will search for marked sessions there. In this way, you -can create multi-file patches that span file subtrees that grow out of -any given directory. - -In an @code{ediff-directories} session, it is enough to just mark the -requisite sessions. In @code{ediff-directory-revisions} revisions, the -marked sessions must also be active, or else Ediff will refuse to produce a -multi-file patch. This is because, in the latter-style sessions, there are -many ways to create diff output, and it is easier to handle by running -Ediff on the inactive sessions. - -Last, but not least, by typing @kbd{==}, you can quickly find out which -sessions have identical entries, so you won't have to run Ediff on those -sessions. This, however, works only on local, uncompressed files. -For compressed or remote files, this command won't report anything. -Likewise, you can use @kbd{=h} to mark sessions with identical entries -for hiding or, with @kbd{=m}, for further operations. - -The comparison operations @kbd{==}, @kbd{=h}, and @kbd{=m} can recurse into -subdirectories to see if they have identical contents (so the user will not -need to descend into those subdirectories manually). These commands ask the -user whether or not to do a recursive descent. - - - -@node Remote and Compressed Files -@chapter Remote and Compressed Files - -Ediff works with remote, compressed, and encrypted files. Ediff -supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el} -and @file{crypt++.el}, but it may work with other similar packages as -well. This means that you can compare files residing on another -machine, or you can apply a patch to a file on another machine. Even -the patch itself can be a remote file! - -When patching compressed or remote files, Ediff does not rename the source -file (unlike what the @code{patch} utility would usually do). Instead, the -source file retains its name and the result of applying the patch is placed -in a temporary file that has the suffix @file{_patched} attached. -Generally, this applies to files that are handled using black magic, such -as special file handlers (ange-ftp and some compression and encryption -packages also use this method). - -Regular files are treated by the @code{patch} utility in the usual manner, -i.e., the original is renamed into @file{source-name.orig} and the result -of the patch is placed into the file source-name (@file{_orig} is used -on systems like DOS, etc.). - -@node Customization -@chapter Customization - -Ediff has a rather self-explanatory interface, and in most cases you -won't need to change anything. However, should the need arise, there are -extensive facilities for changing the default behavior. - -Most of the customization can be done by setting various variables in the -@file{.emacs} file. Some customization (mostly window-related -customization and faces) can be done by putting appropriate lines in -@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use. - -With respect to the latter, please note that the X resource -for Ediff customization is `Ediff', @emph{not} `emacs'. -@xref{Window and Frame Configuration}, -@xref{Highlighting Difference Regions}, for further details. Please also -refer to Emacs manual for the information on how to set Emacs X resources. - -@menu -* Hooks:: Customization via the hooks. -* Quick Help Customization:: How to customize Ediff's quick help feature. -* Window and Frame Configuration:: Controlling the way Ediff displays things. -* Selective Browsing:: Advanced browsing through difference regions. -* Highlighting Difference Regions:: Controlling highlighting. -* Narrowing:: Comparing regions, windows, etc. -* Refinement of Difference Regions:: How to control the refinement process. -* Patch and Diff Programs:: Changing the utilities that compute differences - and apply patches. -* Merging and diff3:: How to customize Ediff in its Merge Mode. -* Support for Version Control:: Changing the version control package. - You are not likely to do that. -* Customizing the Mode Line:: Changing the look of the mode line in Ediff. -* Miscellaneous:: Other customization. -* Notes on Heavy-duty Customization:: Customization for the gurus. -@end menu - -@node Hooks -@section Hooks - -The bulk of customization can be done via the following hooks: - -@table @code -@item ediff-load-hook -@vindex ediff-load-hook -This hook can be used to change defaults after Ediff is loaded. - -@item ediff-before-setup-hook -@vindex ediff-before-setup-hook -Hook that is run just before Ediff rearranges windows to its liking. -Can be used to save windows configuration. - -@item ediff-keymap-setup-hook -@vindex ediff-keymap-setup-hook -@vindex ediff-mode-map -This hook can be used to alter bindings in Ediff's keymap, -@code{ediff-mode-map}. These hooks are -run right after the default bindings are set but before -@code{ediff-load-hook}. The regular user needs not be concerned with this -hook---it is provided for implementers of other Emacs packages built on top -of Ediff. - -@item ediff-before-setup-windows-hook -@itemx ediff-after-setup-windows-hook -@vindex ediff-before-setup-windows-hook -@vindex ediff-after-setup-windows-hook -These two hooks are called before and after Ediff sets up its window -configuration. These hooks are run each time Ediff rearranges windows to -its liking. This happens whenever it detects that the user changed the -windows setup. - -@item ediff-suspend-hook -@itemx ediff-quit-hook -@vindex ediff-suspend-hook -@vindex ediff-quit-hook -These two hooks are run when you suspend or quit Ediff. They can be -used to set desired window configurations, delete files Ediff didn't -want to clean up after exiting, etc. - -By default, @code{ediff-quit-hook} holds one hook function, -@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in -most cases. You probably won't want to change it, but you might -want to add other hook functions. - -Keep in mind that hooks executing before @code{ediff-cleanup-mess} start -in @code{ediff-control-buffer;} they should also leave -@code{ediff-control-buffer} as the current buffer when they finish. -Hooks that are executed after @code{ediff-cleanup-mess} should expect -the current buffer be either buffer A or buffer B@. -@code{ediff-cleanup-mess} doesn't kill the buffers being compared or -merged (see @code{ediff-cleanup-hook}, below). - -@item ediff-cleanup-hook -@vindex ediff-cleanup-hook -This hook is run just before @code{ediff-quit-hook}. This is a good -place to do various cleanups, such as deleting the variant buffers. -Ediff provides a function, @code{ediff-janitor}, as one such possible -hook, which you can add to @code{ediff-cleanup-hook} with -@code{add-hook}. - -@findex ediff-janitor -This function kills buffers A, B, and, possibly, C, if these buffers aren't -modified. In merge jobs, buffer C is never deleted. However, the side -effect of using this function is that you may not be able to compare the -same buffer in two separate Ediff sessions: quitting one of them will -delete this buffer in another session as well. - -@item ediff-quit-merge-hook -@vindex ediff-quit-merge-hook -@vindex ediff-autostore-merges -@findex ediff-maybe-save-and-delete-merge -This hook is called when Ediff quits a merge job. By default, the value is -@code{ediff-maybe-save-and-delete-merge}, which is a function that attempts -to save the merge buffer according to the value of -@code{ediff-autostore-merges}, as described later. - -@item ediff-before-setup-control-frame-hook -@itemx ediff-after-setup-control-frame-hook -@vindex ediff-before-setup-control-frame-hook -@vindex ediff-after-setup-control-frame-hook -These two hooks run before and after Ediff sets up the control frame. -They can be used to relocate Ediff control frame when Ediff runs in a -multiframe mode (i.e., when the control buffer is in its own dedicated -frame). Be aware that many variables that drive Ediff are local to -Ediff Control Panel (@code{ediff-control-buffer}), which requires -special care in writing these hooks. Take a look at -@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to -see what's involved. - -@item ediff-startup-hook -@vindex ediff-startup-hook -This hook is run at the end of Ediff startup. - -@item ediff-select-hook -@vindex ediff-select-hook -This hook is run after Ediff selects the next difference region. - -@item ediff-unselect-hook -@vindex ediff-unselect-hook -This hook is run after Ediff unselects the current difference region. - -@item ediff-prepare-buffer-hook -@vindex ediff-prepare-buffer-hook -This hook is run for each Ediff buffer (A, B, C) right after the buffer -is arranged. - -@item ediff-display-help-hook -@vindex ediff-display-help-hook -Ediff runs this hook each time after setting up the help message. It -can be used to alter the help message for custom packages that run on -top of Ediff. - -@item ediff-mode-hook -@vindex ediff-mode-hook -This hook is run just after Ediff mode is set up in the control -buffer. This is done before any Ediff window is created. You can use it to -set local variables that alter the look of the display. - -@item ediff-registry-setup-hook -@vindex ediff-registry-setup-hook -Hooks run after setting up the registry for all active Ediff session. -@xref{Session Groups}, for details. -@item ediff-before-session-group-setup-hook -@vindex ediff-before-session-group-setup-hook -Hooks run before setting up a control panel for a group of related Ediff -sessions. Can be used, for example, to save window configuration to restore -later. -@item ediff-after-session-group-setup-hook -@vindex ediff-after-session-group-setup-hook -Hooks run after setting up a control panel for a group of related Ediff -sessions. @xref{Session Groups}, for details. -@item ediff-quit-session-group-hook -@vindex ediff-quit-session-group-hook -Hooks run just before exiting a session group. -@item ediff-meta-buffer-keymap-setup-hook -@vindex ediff-meta-buffer-keymap-setup-hook -@vindex ediff-meta-buffer-map -Hooks run just after setting up the @code{ediff-meta-buffer-map}, the -map that controls key bindings in the meta buffer. Since -@code{ediff-meta-buffer-map} is a local variable, you can set different -bindings for different kinds of meta buffers. -@end table - -@node Quick Help Customization -@section Quick Help Customization -@vindex ediff-use-long-help-message -@vindex ediff-control-buffer -@vindex ediff-startup-hook -@vindex ediff-help-message - -Ediff provides quick help using its control panel window. Since this window -takes a fair share of the screen real estate, you can toggle it off by -typing @kbd{?}. The control window will then shrink to just one line and a -mode line, displaying a short help message. - -The variable @code{ediff-use-long-help-message} tells Ediff whether -you use the short message or the long one. By default, it -is set to @code{nil}, meaning that the short message is used. -Set this to @code{t}, if you want Ediff to use the long -message by default. This property can always be changed interactively, by -typing @kbd{?} into Ediff Control Buffer. - -If you want to change the appearance of the help message on a per-buffer -basis, you must use @code{ediff-startup-hook} to change the value of -the variable @code{ediff-help-message}, which is local to -@code{ediff-control-buffer}. - -@node Window and Frame Configuration -@section Window and Frame Configuration - -On a non-windowing display, Ediff sets things up in one frame, splitting -it between a small control window and the windows for buffers A, B, and C@. -The split between these windows can be horizontal or -vertical, which can be changed interactively by typing @kbd{|} while the -cursor is in the control window. - -On a window display, Ediff sets up a dedicated frame for Ediff Control -Panel and then it chooses windows as follows: If one of the buffers -is invisible, it is displayed in the currently selected frame. If -a buffer is visible, it is displayed in the frame where it is visible. -If, according to the above criteria, the two buffers fall into the same -frame, then so be it---the frame will be shared by the two. The same -algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p} -(@code{ediff-previous-difference}), @kbd{n} -(@code{ediff-next-difference}), etc. - -The above behavior also depends on whether the current frame is splittable, -dedicated, etc. Unfortunately, the margin of this book is too narrow to -present the details of this remarkable algorithm. - -The upshot of all this is that you can compare buffers in one frame or -in different frames. The former is done by default, while the latter can -be achieved by arranging buffers A, B (and C, if applicable) to be seen in -different frames. Ediff respects these arrangements, automatically -adapting itself to the multi-frame mode. - -Ediff uses the following variables to set up its control panel -(a.k.a.@: control buffer, a.k.a.@: quick help window): - -@table @code -@item ediff-control-frame-parameters -@vindex ediff-control-frame-parameters -You can change or augment this variable including the font, color, -etc. The X resource name of Ediff Control Panel frames is @samp{Ediff}. Under -X-windows, you can use this name to set up preferences in your -@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in -use. Usually this is preferable to changing -@code{ediff-control-frame-parameters} directly. For instance, you can -specify in @file{~/.Xdefaults} the color of the control frame -using the resource @samp{Ediff*background}. - -In general, any X resource pertaining the control frame can be reached -via the prefix @code{Ediff*}. - -@item ediff-control-frame-position-function -@vindex ediff-control-frame-position-function -The preferred way of specifying the position of the control frame is by -setting the variable @code{ediff-control-frame-position-function} to an -appropriate function. -The default value of this variable is -@code{ediff-make-frame-position}. This function places the control frame in -the vicinity of the North-East corner of the frame displaying buffer A. - -@findex ediff-make-frame-position -@end table - -The following variables can be used to adjust the location produced by -@code{ediff-make-frame-position} and for related customization. - -@table @code -@item ediff-narrow-control-frame-leftward-shift -@vindex ediff-narrow-control-frame-leftward-shift -Specifies the number of characters for shifting -the control frame from the rightmost edge of frame A when the control -frame is displayed as a small window. - -@item ediff-wide-control-frame-rightward-shift -@vindex ediff-wide-control-frame-rightward-shift -Specifies the rightward shift of the control frame -from the left edge of frame A when the control frame shows the full -menu of options. - -@item ediff-control-frame-upward-shift -@vindex ediff-control-frame-upward-shift -Specifies the number of pixels for the upward shift -of the control frame. - -@item ediff-prefer-iconified-control-frame -@vindex ediff-prefer-iconified-control-frame -If this variable is @code{t}, the control frame becomes iconified -automatically when you toggle the quick help message off. This saves -valuable real estate on the screen. Toggling help back will deiconify -the control frame. - -To start Ediff with an iconified Control Panel, you should set this -variable to @code{t} and @code{ediff-prefer-long-help-message} to -@code{nil} (@pxref{Quick Help Customization}). This behavior is useful -only if icons are allowed to accept keyboard input (which depends on the -window manager and other factors). -@end table - -@findex ediff-setup-windows -To make more creative changes in the way Ediff sets up windows, you can -rewrite the function @code{ediff-setup-windows}. However, we believe -that detaching Ediff Control Panel from the rest and making it into a -separate frame offers an important opportunity by allowing you to -iconify that frame. The icon will usually accept all of the Ediff -commands, but will free up valuable real estate on your screen (this may -depend on your window manager, though). - -The following variable controls how windows are set up: - -@table @code -@item ediff-window-setup-function -@vindex ediff-window-setup-function -The multiframe setup is done by the -@code{ediff-setup-windows-multiframe} function, which is the default on -windowing displays. The plain setup, one where all windows are always -in one frame, is done by @code{ediff-setup-windows-plain}, which is the -default on a non-windowing display (or in an xterm window). In fact, -under Emacs, you can switch freely between these two setups by executing -the command @code{ediff-toggle-multiframe} using the Minibuffer of the -Menubar. -@findex ediff-setup-windows-multiframe -@findex ediff-setup-windows-plain -@findex ediff-toggle-multiframe - -If you don't like any of these setups, write your own function. See the -documentation for @code{ediff-window-setup-function} for the basic -guidelines. However, writing window setups is not easy, so you should -first take a close look at @code{ediff-setup-windows-plain} and -@code{ediff-setup-windows-multiframe}. -@end table - -You can run multiple Ediff sessions at once, by invoking Ediff several -times without exiting previous Ediff sessions. Different sessions -may even operate on the same pair of files. - -Each session has its own Ediff Control Panel and all the regarding a -particular session is local to the associated control panel buffer. You -can switch between sessions by suspending one session and then switching -to another control panel. (Different control panel buffers are -distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.) - -@node Selective Browsing -@section Selective Browsing - -Sometimes it is convenient to be able to step through only some difference -regions, those that match certain regular expressions, and to ignore all -others. On other occasions, you may want to ignore difference regions that -match some regular expressions, and to look only at the rest. - -The commands @kbd{#f} and @kbd{#h} let you do precisely this. - -Typing @kbd{#f} lets you specify regular expressions that match difference -regions you want to focus on. -We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and -@var{regexp-C}. -Ediff will then start stepping through only those difference regions -where the region in buffer A matches @var{regexp-A} and/or the region in -buffer B matches @var{regexp-B}, etc. Whether `and' or `or' will be used -depends on how you respond to a question. - -When scanning difference regions for the aforesaid regular expressions, -Ediff narrows the buffers to those regions. This means that you can use -the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end -of the difference regions. - -On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting -regions. That is, if a difference region in buffer A matches -@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B} -and (if applicable) buffer C's region matches @var{regexp-C}, then the -region will be ignored by the commands @kbd{n}/@key{SPC} -(@code{ediff-next-difference}) and @kbd{p}/@key{DEL} -(@code{ediff-previous-difference}) commands. - -Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off. - -Note that selective browsing affects only @code{ediff-next-difference} -and @code{ediff-previous-difference}, i.e., the commands -@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}. @kbd{#f} and @kbd{#h} do not -change the position of the point in the buffers. And you can still jump -directly (using @kbd{j}) to any numbered -difference. - -Users can supply their own functions to specify how Ediff should do -selective browsing. To change the default Ediff function, add a function to -@code{ediff-load-hook} which will do the following assignments: - -@example -(setq ediff-hide-regexp-matches-function 'your-hide-function) -(setq ediff-focus-on-regexp-matches-function 'your-focus-function) -@end example - -@strong{Useful hint}: To specify a regexp that matches everything, don't -simply type @key{RET} in response to a prompt. Typing @key{RET} tells Ediff -to accept the default value, which may not be what you want. Instead, you -should enter something like @key{^} or @key{$}. These match every -line. - -You can use the status command, @kbd{i}, to find out whether -selective browsing is currently in effect. - -The regular expressions you specified are kept in the local variables -@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B}, -@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A}, -@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}. Their default value -is the empty string (i.e., nothing is hidden or focused on). To change the -default, set these variables in @file{.emacs} using @code{setq-default}. - -In addition to the ability to ignore regions that match regular -expressions, Ediff can be ordered to start skipping over certain -``uninteresting'' difference regions. This is controlled by the following -variable: - -@table @code -@item ediff-ignore-similar-regions -@vindex ediff-ignore-similar-regions -If @code{t}, causes Ediff to skip over "uninteresting" difference regions, -which are the regions where the variants differ only in the amount of the -white space and newlines. This feature can be toggled on/off interactively, -via the command @kbd{##}. -@end table - -@strong{Please note:} in order for this feature to work, auto-refining of -difference regions must be on, since otherwise Ediff won't know if there -are fine differences between regions. On devices where Emacs can display -faces, auto-refining is a default, but it is not turned on by default on -text-only terminals. In that case, you must explicitly turn auto-refining -on (such as, by typing @kbd{@@}). - -@strong{Reassurance:} If many such uninteresting regions appear in a row, -Ediff may take a long time to skip over them because it has to compute fine -differences of all intermediate regions. This delay does not indicate any -problem. - -@vindex ediff-ignore-case-option -@vindex ediff-ignore-case-option3 -@vindex ediff-ignore-case -Finally, Ediff can be told to ignore the case of the letters. This behavior -can be toggled with @kbd{#c} and it is controlled with three variables: -@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, and -@code{ediff-ignore-case}. - -The variable @code{ediff-ignore-case-option} specifies the option to pass -to the diff program for comparing two files or buffers. For GNU -@code{diff}, this option is @code{"-i"}. The variable -@code{ediff-ignore-case-option3} specifies the option to pass to the -@code{diff3} program in order to make it case-insensitive. GNU @code{diff3} -does not have such an option, so when merging or comparing three files with -this program, ignoring the letter case is not supported. - -The variable @code{ediff-ignore-case} controls whether Ediff starts out by -ignoring letter case or not. It can be set in @file{.emacs} using -@code{setq-default}. - -When case sensitivity is toggled, all difference -regions are recomputed. - -@node Highlighting Difference Regions -@section Highlighting Difference Regions - -The following variables control the way Ediff highlights difference -regions: - -@table @code -@item ediff-before-flag-bol -@itemx ediff-after-flag-eol -@itemx ediff-before-flag-mol -@itemx ediff-after-flag-mol -@vindex ediff-before-flag-bol -@vindex ediff-after-flag-eol -@vindex ediff-before-flag-mol -@vindex ediff-after-flag-mol -These variables hold strings that Ediff uses to mark the beginning and the -end of the differences found in files A, B, and C on devices where Emacs -cannot display faces. Ediff uses different flags to highlight regions that -begin/end at the beginning/end of a line or in a middle of a line. - -@item ediff-current-diff-face-A -@itemx ediff-current-diff-face-B -@itemx ediff-current-diff-face-C -@vindex ediff-current-diff-face-A -@vindex ediff-current-diff-face-B -@vindex ediff-current-diff-face-C -Ediff uses these faces to highlight current differences on devices where -Emacs can display faces. These and subsequently described faces can be set -either in @file{.emacs} or in @file{.Xdefaults}. The X resource for Ediff -is @samp{Ediff}, @emph{not} @samp{emacs}. Please refer to Emacs manual for -the information on how to set X resources. -@item ediff-fine-diff-face-A -@itemx ediff-fine-diff-face-B -@itemx ediff-fine-diff-face-C -@vindex ediff-fine-diff-face-A -@vindex ediff-fine-diff-face-B -@vindex ediff-fine-diff-face-C -Ediff uses these faces to show the fine differences between the current -differences regions in buffers A, B, and C, respectively. - -@item ediff-even-diff-face-A -@itemx ediff-even-diff-face-B -@itemx ediff-even-diff-face-C -@itemx ediff-odd-diff-face-A -@itemx ediff-odd-diff-face-B -@itemx ediff-odd-diff-face-C -@vindex ediff-even-diff-face-A -@vindex ediff-even-diff-face-B -@vindex ediff-even-diff-face-C -@vindex ediff-odd-diff-face-A -@vindex ediff-odd-diff-face-B -@vindex ediff-odd-diff-face-C -Non-current difference regions are displayed using these alternating -faces. The odd and the even faces are actually identical on monochrome -displays, because without colors options are limited. -So, Ediff uses italics to highlight non-current differences. - -@item ediff-force-faces -@vindex ediff-force-faces -Ediff generally can detect when Emacs is running on a device where it can -use highlighting with faces. However, if it fails to determine that faces -can be used, the user can set this variable to @code{t} to make sure that -Ediff uses faces to highlight differences. - -@item ediff-highlight-all-diffs -@vindex ediff-highlight-all-diffs -Indicates whether---on a windowing display---Ediff should highlight -differences using inserted strings (as on text-only terminals) or using -colors and highlighting. Normally, Ediff highlights all differences, but -the selected difference is highlighted more visibly. One can cycle through -various modes of highlighting by typing @kbd{h}. By default, Ediff starts -in the mode where all difference regions are highlighted. If you prefer to -start in the mode where unselected differences are not highlighted, you -should set @code{ediff-highlight-all-diffs} to @code{nil}. Type @kbd{h} to -restore highlighting for all differences. - -Ediff lets you switch between the two modes of highlighting. That is, -you can switch interactively from highlighting using faces to -highlighting using string flags, and back. Of course, switching has -effect only under a windowing system. On a text-only terminal or in an -xterm window, the only available option is highlighting with strings. -@end table - -@noindent -If you want to change the default settings for @code{ediff-force-faces} and -@code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff is -loaded. - -You can also change the defaults for the faces used to highlight the -difference regions. There are two ways to do this. The simplest and the -preferred way is to use the customization widget accessible from the -menubar. Ediff's customization group is located under "Tools", which in -turn is under "Programming". The faces that are used to highlight -difference regions are located in the "Highlighting" subgroup of the Ediff -customization group. - -The second, much more arcane, method to change default faces is to include -some Lisp code in @file{~/.emacs}. For instance, - -@example -(setq ediff-current-diff-face-A - (copy-face 'bold-italic 'ediff-current-diff-face-A)) -@end example - -@noindent -would use the pre-defined face @code{bold-italic} to highlight the current -difference region in buffer A (this face is not a good choice, by the way). - -If you are unhappy with just @emph{some} of the aspects of the default -faces, you can modify them when Ediff is being loaded using -@code{ediff-load-hook}. For instance: - -@smallexample -(add-hook 'ediff-load-hook - (lambda () - (set-face-foreground - ediff-current-diff-face-B "blue") - (set-face-background - ediff-current-diff-face-B "red") - (make-face-italic - ediff-current-diff-face-B))) -@end smallexample - -@strong{Please note:} to set Ediff's faces, use only @code{copy-face} -or @code{set/make-face-@dots{}} as shown above. Emacs's low-level -face-manipulation functions should be avoided. - -@node Narrowing -@section Narrowing - -If buffers being compared are narrowed at the time of invocation of -Ediff, @code{ediff-buffers} will preserve the narrowing range. However, -if @code{ediff-files} is invoked on the files visited by these buffers, -that would widen the buffers, since this command is defined to compare the -entire files. - -Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, or -the corresponding @samp{-wordwise} commands, narrows the variants to the -particular regions being compared. The original accessible ranges are -restored when you quit Ediff. During the command, you can toggle this -narrowing on and off with the @kbd{%} command. - -These two variables control this narrowing behavior: - -@table @code -@item ediff-start-narrowed -@vindex ediff-start-narrowed -If @code{t}, Ediff narrows the display to the appropriate range when it -is invoked with an @samp{ediff-regions@dots{}} or -@samp{ediff-windows@dots{}} command. If @code{nil}, these commands do -not automatically narrow, but you can still toggle narrowing on and off -by typing @kbd{%}. - -@item ediff-quit-widened -@vindex ediff-quit-widened -Controls whether on quitting Ediff should restore the accessible range -that existed before the current invocation. -@end table - -@node Refinement of Difference Regions -@section Refinement of Difference Regions - -Ediff has variables to control the way fine differences are -highlighted. This feature gives you control over the process of refinement. -Note that refinement ignores spaces, tabs, and newlines. - -@table @code -@item ediff-auto-refine -@vindex ediff-auto-refine -This variable controls whether fine differences within regions are -highlighted automatically (``auto-refining''). The default is yes -(@samp{on}). - -On a slow machine, automatic refinement may be painful. In that case, -you can turn auto-refining on or off interactively by typing -@kbd{@@}. You can also turn off display of refining that has -already been done. - -When auto-refining is off, fine differences are shown only for regions -for which these differences have been computed and saved before. If -auto-refining and display of refining are both turned off, fine -differences are not shown at all. - -Typing @kbd{*} computes and displays fine differences for the current -difference region, regardless of whether auto-refining is turned on. - -@item ediff-auto-refine-limit -@vindex ediff-auto-refine-limit -If auto-refining is on, this variable limits the size of the regions to -be auto-refined. This guards against the possible slowdown that may be -caused by extraordinary large difference regions. - -You can always refine the current region by typing @kbd{*}. - -@item ediff-forward-word-function -@vindex ediff-forward-word-function -This variable controls how fine differences are computed. The -value must be a Lisp function that determines how the current difference -region should be split into words. - -@vindex ediff-diff-program -@vindex ediff-forward-word-function -@findex ediff-forward-word -Fine differences are computed by first splitting the current difference -region into words and then passing the result to -@code{ediff-diff-program}. For the default forward word function (which is -@code{ediff-forward-word}), a word is a string consisting of letters, -@samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits, -or a string consisting of symbols that are neither space, nor a letter. - -This default behavior is controlled by four variables: @code{ediff-word-1}, -..., @code{ediff-word-4}. See the on-line documentation for these variables -and for the function @code{ediff-forward-word} for an explanation of how to -modify these variables. -@vindex ediff-word-1 -@vindex ediff-word-2 -@vindex ediff-word-3 -@vindex ediff-word-4 -@end table - -Sometimes, when a region has too many differences between the variants, -highlighting of fine differences is inconvenient, especially on -color displays. If that is the case, type @kbd{*} with a negative -prefix argument. This unhighlights fine differences for the current -region. - -To unhighlight fine differences in all difference regions, use the -command @kbd{@@}. Repeated typing of this key cycles through three -different states: auto-refining, no-auto-refining, and no-highlighting -of fine differences. - -@node Patch and Diff Programs -@section Patch and Diff Programs - -This section describes variables that specify the programs to be used for -applying patches and for computing the main difference regions (not the -fine difference regions): - -@table @code -@item ediff-diff-program -@itemx ediff-diff3-program -@vindex ediff-patch-program -@vindex ediff-diff-program -@vindex ediff-diff3-program -These variables specify the programs to use to produce differences -and do patching. - -@item ediff-diff-options -@itemx ediff-diff3-options -@vindex ediff-patch-options -@vindex ediff-diff-options -@vindex ediff-diff3-options -These variables specify the options to pass to the above utilities. - -In @code{ediff-diff-options}, it may be useful to specify options -such as @samp{-w} that ignore certain kinds of changes. However, -Ediff does not let you use the option @samp{-c}, as it doesn't recognize this -format yet. - -@item ediff-coding-system-for-read -@vindex ediff-coding-system-for-read -This variable specifies the coding system to use when reading the output -that the programs @code{diff3} and @code{diff} send to Emacs. The default -is @code{raw-text}, and this should work fine in Unix and in most -cases under Windows NT/95/98/2000. There are @code{diff} programs -for which the default option doesn't work under Windows. In such cases, -@code{raw-text-dos} might work. If not, you will have to experiment with -other coding systems or use GNU diff. - -@item ediff-patch-program -The program to use to apply patches. Since there are certain -incompatibilities between the different versions of the patch program, the -best way to stay out of trouble is to use a GNU-compatible version. -Otherwise, you may have to tune the values of the variables -@code{ediff-patch-options}, @code{ediff-backup-specs}, and -@code{ediff-backup-extension} as described below. -@item ediff-patch-options -Options to pass to @code{ediff-patch-program}. - -Note: the `-b' and `-z' options should be specified in -`ediff-backup-specs', not in @code{ediff-patch-options}. - -It is recommended to pass the `-f' option to the patch program, so it won't -ask questions. However, some implementations don't accept this option, in -which case the default value of this variable should be changed. - -@item ediff-backup-extension -Backup extension used by the patch program. Must be specified, even if -@code{ediff-backup-specs} is given. -@item ediff-backup-specs -Backup directives to pass to the patch program. -Ediff requires that the old version of the file (before applying the patch) -is saved in a file named @file{the-patch-file.extension}. Usually -`extension' is `.orig', but this can be changed by the user, and may also be -system-dependent. Therefore, Ediff needs to know the backup extension used -by the patch program. - -Some versions of the patch program let the user specify `-b backup-extension'. -Other versions only permit `-b', which (usually) assumes the extension `.orig'. -Yet others force you to use `-z'. - -Note that both `ediff-backup-extension' and `ediff-backup-specs' must be -properly set. If your patch program takes the option `-b', but not -`-b extension', the variable `ediff-backup-extension' must still -be set so Ediff will know which extension to use. - -@item ediff-custom-diff-program -@itemx ediff-custom-diff-options -@vindex ediff-custom-diff-program -@vindex ediff-custom-diff-options -@findex ediff-save-buffer -Because Ediff limits the options you may want to pass to the @code{diff} -program, it partially makes up for this drawback by letting you save the -output from @code{diff} in your preferred format, which is specified via -the above two variables. - -The output generated by @code{ediff-custom-diff-program} (which doesn't -even have to be a standard-style @code{diff}!)@: is not used by Ediff. It is -provided exclusively so that you can -refer to -it later, send it over email, etc. For instance, after reviewing the -differences, you may want to send context differences to a colleague. -Since Ediff ignores the @samp{-c} option in -@code{ediff-diff-program}, you would have to run @code{diff -c} separately -just to produce the list of differences. Fortunately, -@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options} -eliminate this nuisance by keeping a copy of a difference list in the -desired format in a buffer that can be displayed via the command @kbd{D}. - -@item ediff-patch-default-directory -@vindex ediff-patch-default-directory -Specifies the default directory to look for patches. - -@end table - -@noindent -@strong{Warning:} Ediff does not support the output format of VMS -@code{diff}. Instead, make sure you are using some implementation of POSIX -@code{diff}, such as @code{gnudiff}. - -@node Merging and diff3 -@section Merging and diff3 - -Ediff supports three-way comparison via the functions @code{ediff-files3} and -@code{ediff-buffers3}. The interface is the same as for two-way comparison. -In three-way comparison and merging, Ediff reports if any two difference -regions are identical. For instance, if the current region in buffer A -is the same as the region in buffer C, then the mode line of buffer A will -display @samp{[=diff(C)]} and the mode line of buffer C will display -@samp{[=diff(A)]}. - -Merging is done according to the following algorithm. - -If a difference region in one of the buffers, say B, differs from the ancestor -file while the region in the other buffer, A, doesn't, then the merge buffer, -C, gets B's region. Similarly when buffer A's region differs from -the ancestor and B's doesn't, A's region is used. - -@vindex ediff-default-variant -If both regions in buffers A and B differ from the ancestor file, Ediff -chooses the region according to the value of the variable -@code{ediff-default-variant}. If its value is @code{default-A} then A's -region is chosen. If it is @code{default-B} then B's region is chosen. -If it is @code{combined} then the region in buffer C will look like -this: - -@comment Use @set to avoid triggering merge conflict detectors like CVS. -@set seven-left <<<<<<< -@set seven-right >>>>>>> -@example -@value{seven-left} variant A -the difference region from buffer A -@value{seven-right} variant B -the difference region from buffer B -####### Ancestor -the difference region from the ancestor buffer, if available -======= end -@end example - -The above is the default template for the combined region. The user can -customize this template using the variable -@code{ediff-combination-pattern}. - -@vindex ediff-combination-pattern -The variable @code{ediff-combination-pattern} specifies the template that -determines how the combined merged region looks like. The template is -represented as a list of the form @code{(STRING1 Symbol1 STRING2 Symbol2 -STRING3 Symbol3 STRING4)}. The symbols here must be atoms of the form -@code{A}, @code{B}, or @code{Ancestor}. They determine the order in which -the corresponding difference regions (from buffers A, B, and the ancestor -buffer) are displayed in the merged region of buffer C@. The strings in the -template determine the text that separates the aforesaid regions. The -default template is - -@smallexample -("@value{seven-left} variant A" A "@value{seven-right} variant B" B - "####### Ancestor" Ancestor "======= end") -@end smallexample - -@noindent -(this is one long line) and the corresponding combined region is shown -above. The order in which the regions are shown (and the separator -strings) can be changed by changing the above template. It is even -possible to add or delete region specifiers in this template (although -the only possibly useful such modification seems to be the deletion of -the ancestor). - -In addition to the state of the difference, Ediff displays the state of the -merge for each region. If a difference came from buffer A by default -(because both regions A and B were different from the ancestor and -@code{ediff-default-variant} was set to @code{default-A}) then -@samp{[=diff(A) default-A]} is displayed in the mode line. If the -difference in buffer C came, say, from buffer B because the difference -region in that buffer differs from the ancestor, but the region in buffer A -does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is -displayed. The indicators default-A/B and prefer-A/B are inspired by -Emerge and have the same meaning. - -Another indicator of the state of merge is @samp{combined}. It appears -with any difference region in buffer C that was obtained by combining -the difference regions in buffers A and B as explained above. - -In addition to the state of merge and state of difference indicators, while -merging with an ancestor file or buffer, Ediff informs the user when the -current difference region in the (normally invisible) ancestor buffer is -empty via the @emph{AncestorEmpty} indicator. This helps determine if the -changes made to the original in variants A and B represent pure insertion -or deletion of text: if the mode line shows @emph{AncestorEmpty} and the -corresponding region in buffers A or B is not empty, this means that new -text was inserted. If this indicator is not present and the difference -regions in buffers A or B are non-empty, this means that text was -modified. Otherwise, the original text was deleted. - -Although the ancestor buffer is normally invisible, Ediff maintains -difference regions there and advances the current difference region -accordingly. All highlighting of difference regions is provided in the -ancestor buffer, except for the fine differences. Therefore, if desired, the -user can put the ancestor buffer in a separate frame and watch it -there. However, on a TTY, only one frame can be visible at any given time, -and Ediff doesn't support any single-frame window configuration where all -buffers, including the ancestor buffer, would be visible. However, the -ancestor buffer can be displayed by typing @kbd{/} to the control -window. (Type @kbd{C-l} to hide it again.) - -Note that the state-of-difference indicators @samp{=diff(A)} and -@samp{=diff(B)} above are not redundant, even in the presence of a -state-of-merge indicator. In fact, the two serve different purposes. - -For instance, if the mode line displays @samp{=diff(B) prefer(B)} and -you copy a difference region from buffer A to buffer C then -@samp{=diff(B)} will change to @samp{diff-A} and the mode line will -display @samp{=diff(A) prefer-B}. This indicates that the difference -region in buffer C is identical to that in buffer A, but originally -buffer C's region came from buffer B@. This is useful to know because -you can recover the original difference region in buffer C by typing -@kbd{r}. - - -Ediff never changes the state-of-merge indicator, except in response to -the @kbd{!} command (see below), in which case the indicator is lost. -On the other hand, the state-of-difference indicator is changed -automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r}, -@kbd{+}. - -The @kbd{!} command loses the information about origins of the regions -in the merge buffer (default-A, prefer-B, or combined). This is because -recomputing differences in this case means running @code{diff3} on -buffers A, B, and the merge buffer, not on the ancestor buffer. (It -makes no sense to recompute differences using the ancestor file, since -in the merging mode Ediff assumes that you have not edited buffers A and -B, but that you may have edited buffer C, and these changes are to be -preserved.) Since some difference regions may disappear as a result of -editing buffer C and others may arise, there is generally no simple way -to tell where the various regions in the merge buffer came from. - -In three-way comparison, Ediff tries to disregard regions that consist -entirely of white space. For instance, if, say, the current region in -buffer A consists of the white space only (or if it is empty), Ediff will -not take it into account for the purpose of computing fine differences. The -result is that Ediff can provide a better visual information regarding the -actual fine differences in the non-white regions in buffers B and -C@. Moreover, if the regions in buffers B and C differ in the white space -only, then a message to this effect will be displayed. - -@vindex ediff-merge-window-share -In the merge mode, the share of the split between window C (the window -displaying the merge-buffer) and the windows displaying buffers A and B -is controlled by the variable @code{ediff-merge-window-share}. Its -default value is 0.5. To make the merge-buffer window smaller, reduce -this amount. - -We don't recommend increasing the size of the merge-window to more than -half the frame (i.e., to increase the value of -@code{ediff-merge-window-share}) to more than 0.5, since it would be -hard to see the contents of buffers A and B. - -You can temporarily shrink the merge window to just one line by -typing @kbd{s}. This change is temporary, until Ediff finds a reason to -redraw the screen. Typing @kbd{s} again restores the original window size. - -With a positive prefix argument, the @kbd{s} command will make the merge -window slightly taller. This change is persistent. With `@kbd{-}' or -with a negative prefix argument, the command @kbd{s} makes the merge -window slightly shorter. This change also persistent. - -@vindex ediff-show-clashes-only -Ediff lets you automatically ignore the regions where only one of the -buffers A and B disagrees with the ancestor. To do this, set the -variable @code{ediff-show-clashes-only} to non-@code{nil}. - -You can toggle this feature interactively by typing @kbd{$$}. - -Note that this variable affects only the show next/previous difference -commands. You can still jump directly to any difference region directly -using the command @kbd{j} (with a prefix argument specifying the difference -number). - -@vindex ediff-autostore-merges -@vindex ediff-quit-merge-hook -@findex ediff-maybe-save-and-delete-merge -The variable @code{ediff-autostore-merges} controls what happens to the -merge buffer when Ediff quits. If the value is @code{nil}, nothing is done -to the merge buffer---it will be the user's responsibility to save it. -If the value is @code{t}, the user will be asked where to save the buffer -and whether to delete it afterwards. It the value is neither @code{nil} nor -@code{t}, the merge buffer is saved @emph{only} if this merge session was -invoked from a group of related Ediff session, such as those that result -from @code{ediff-merge-directories}, -@code{ediff-merge-directory-revisions}, etc. -@xref{Session Groups}. This behavior is implemented in the function -@code{ediff-maybe-save-and-delete-merge}, which is a hook in -@code{ediff-quit-merge-hook}. The user can supply a different hook, if -necessary. - -The variable @code{ediff-autostore-merges} is buffer-local, so it can be -set in a per-buffer manner. Therefore, use @code{setq-default} to globally -change this variable. - -@vindex ediff-merge-filename-prefix -When merge buffers are saved automatically as directed by -@code{ediff-autostore-merges}, Ediff attaches a prefix to each file, as -specified by the variable @code{ediff-merge-filename-prefix}. The default -is @code{merge_}, but this can be changed by the user. - -@node Support for Version Control -@section Support for Version Control - - -Ediff supports version control and lets you compare versions of files -visited by Emacs buffers via the function @code{ediff-revision}. This -feature is controlled by the following variables: - -@table @code -@item ediff-version-control-package -@vindex ediff-version-control-package -A symbol. The default is @samp{vc}. - -If you are like most Emacs users, Ediff will use VC as the version control -package. This is the standard Emacs interface to RCS, CVS, and SCCS. - -However, if your needs are better served by other interfaces, you will -have to tell Ediff which version control package you are using, e.g., -@example -(setq ediff-version-control-package 'rcs) -@end example - -Apart from the standard @file{vc.el}, Ediff supports three other interfaces -to version control: @file{rcs.el}, @file{pcl-cvs.el} (recently renamed -pcvs.el), and @file{generic-sc.el}. The package @file{rcs.el} is written -by Sebastian Kremer and is available as -@example -@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z} -@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z} -@end example -@pindex @file{vc.el} -@pindex @file{rcs.el} -@pindex @file{pcl-cvs.el} -@pindex @file{generic-sc.el} -@end table - -Ediff's interface to the above packages allows the user to compare the -versions of the current buffer or to merge them (with or without an -ancestor-version). These operations can also be performed on directories -containing files under version control. - -In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function -@code{run-ediff-from-cvs-buffer}---see the documentation string for this -function. - -@node Customizing the Mode Line -@section Customizing the Mode Line - -When Ediff is running, the mode line of @samp{Ediff Control Panel} -buffer shows the current difference number and the total number of -difference regions in the two files. - -The mode line of the buffers being compared displays the type of the -buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name. -Ediff tries to be intelligent in choosing the mode line buffer -identification. In particular, it works well with the -@file{uniquify.el} and @file{mode-line.el} packages (which improve on -the default way in which Emacs displays buffer identification). If you -don't like the way Ediff changes the mode line, you can use -@code{ediff-prepare-buffer-hook} to modify the mode line. -@vindex ediff-prepare-buffer-hook -@pindex @file{uniquify.el} -@pindex @file{mode-line.el} - -@node Miscellaneous -@section Miscellaneous - -Here are a few other variables for customizing Ediff: - -@table @code -@item ediff-split-window-function -@vindex ediff-split-window-function -Controls the way you want the window be split between file-A and file-B -(and file-C, if applicable). It defaults to the vertical split -(@code{split-window-vertically}, but you can set it to -@code{split-window-horizontally}, if you so wish. -Ediff also lets you switch from vertical to horizontal split and back -interactively. - -Note that if Ediff detects that all the buffers it compares are displayed in -separate frames, it assumes that the user wants them to be so displayed -and stops splitting windows. Instead, it arranges for each buffer to -be displayed in a separate frame. You can switch to the one-frame mode -by hiding one of the buffers A/B/C. - -You can also swap the windows where buffers are displayed by typing -@kbd{~}. - -@item ediff-merge-split-window-function -@vindex ediff-merge-split-window-function -Controls how windows are -split between buffers A and B in the merge mode. -This variable is like @code{ediff-split-window-function}, but it defaults -to @code{split-window-horizontally} instead of -@code{split-window-vertically}. - -@item ediff-make-wide-display-function -@vindex ediff-make-wide-display-function -The value is a function to be called to widen the frame for displaying -the Ediff buffers. See the on-line documentation for -@code{ediff-make-wide-display-function} for details. It is also -recommended to look into the source of the default function -@code{ediff-make-wide-display}. - -You can toggle wide/regular display by typing @kbd{m}. In the wide -display mode, buffers A, B (and C, when applicable) are displayed in a -single frame that is as wide as the entire workstation screen. This is -useful when files are compared side-by-side. By default, the display is -widened without changing its height. - -@item ediff-use-last-dir -@vindex ediff-use-last-dir -Controls the way Ediff presents the -default directory when it prompts the user for files to compare. If -@code{nil}, -Ediff uses the default directory of the current buffer when it -prompts the user for file names. Otherwise, it will use the -directories it had previously used for files A, B, or C, respectively. - -@item ediff-no-emacs-help-in-control-buffer -@vindex ediff-no-emacs-help-in-control-buffer -If @code{t}, makes @kbd{C-h} -behave like the @key{DEL} key, i.e., it will move you back to the previous -difference rather than invoking help. This is useful when, in an xterm -window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is -positioned more conveniently than the @key{DEL} key. - -@item ediff-toggle-read-only-function -@vindex ediff-toggle-read-only-function -This variable's value is a function that Ediff uses to toggle -the read-only property in its buffers. - -The default function that Ediff uses simply toggles the read-only property, -unless the file is under version control. For a checked-in file under -version control, Ediff first tries to check the file out. - -@item ediff-make-buffers-readonly-at-startup nil -@vindex ediff-make-buffers-readonly-at-startup -If @code{t}, all variant buffers are made read-only at Ediff startup. - -@item ediff-keep-variants -@vindex @code{ediff-keep-variants} -The default is @code{t}, meaning that the buffers being compared or merged will -be preserved when Ediff quits. Setting this to @code{nil} causes Ediff to -offer the user a chance to delete these buffers (if they are not modified). -Supplying a prefix argument to the quit command (@code{q}) temporarily -reverses the meaning of this variable. This is convenient when the user -prefers one of the behaviors most of the time, but occasionally needs the -other behavior. - -However, Ediff temporarily resets this variable to @code{t} if it is -invoked via one of the "buffer" jobs, such as @code{ediff-buffers}. -This is because it is all too easy to lose a day's work otherwise. -Besides, in a "buffer" job, the variant buffers have already been loaded -prior to starting Ediff, so Ediff just preserves status quo here. - -Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants -unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks). - -@item ediff-keep-tmp-versions -@vindex @code{ediff-keep-tmp-versions} -Default is @code{nil}. If @code{t}, the versions of the files being -compared or merged using operations such as @code{ediff-revision} or -@code{ediff-merge-revisions} are not deleted on exit. The normal action is -to clean up and delete these version files. - -@item ediff-grab-mouse -@vindex @code{ediff-grab-mouse} -Default is @code{t}. Normally, Ediff grabs mouse and puts it in its -control frame. This is useful since the user can be sure that when he -needs to type an Ediff command the focus will be in an appropriate Ediff's -frame. However, some users prefer to move the mouse by themselves. The -above variable, if set to @code{maybe}, will prevent Ediff from grabbing -the mouse in many situations, usually after commands that may take more -time than usual. In other situation, Ediff will continue grabbing the mouse -and putting it where it believes is appropriate. If the value is -@code{nil}, then mouse is entirely user's responsibility. -Try different settings and see which one is for you. -@end table - - -@node Notes on Heavy-duty Customization -@section Notes on Heavy-duty Customization - -Some users need to customize Ediff in rather sophisticated ways, which -requires different defaults for different kinds of files (e.g., SGML, -etc.). Ediff supports this kind of customization in several ways. First, -most customization variables are buffer-local. Those that aren't are -usually accessible from within Ediff Control Panel, so one can make them -local to the panel by calling make-local-variable from within -@code{ediff-startup-hook}. - -Second, the function @code{ediff-setup} accepts an optional sixth -argument which has the form @code{((@var{var-name-1} .@: @var{val-1}) -(@var{var-name-2} .@: @var{val-2}) @dots{})}. The function -@code{ediff-setup} sets the variables in the list to the respective -values, locally in the Ediff control buffer. This is an easy way to -throw in custom variables (which usually should be buffer-local) that -can then be tested in various hooks. - -Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set -properly in this case, as some things in Ediff depend on this. - -Finally, if you want custom-tailored help messages, you can set the -variables @code{ediff-brief-help-message-function} and -@code{ediff-long-help-message-function} -to functions that return help strings. -@vindex ediff-startup-hook -@findex ediff-setup -@vindex ediff-job-name -@vindex ediff-word-mode -@vindex ediff-brief-help-message-function -@vindex ediff-long-help-message-function - -When customizing Ediff, some other variables are useful, although they are -not user-definable. They are local to the Ediff control buffer, so this -buffer must be current when you access these variables. The control buffer -is accessible via the variable @code{ediff-control-buffer}, which is also -local to that buffer. It is usually used for checking if the current buffer -is also the control buffer. - -Other variables of interest are: -@table @code -@item ediff-buffer-A -The first of the data buffers being compared. - -@item ediff-buffer-B -The second of the data buffers being compared. - -@item ediff-buffer-C -In three-way comparisons, this is the third buffer being compared. -In merging, this is the merge buffer. -In two-way comparison, this variable is @code{nil}. - -@item ediff-window-A -The window displaying buffer A@. If buffer A is not visible, this variable -is @code{nil} or it may be a dead window. - -@item ediff-window-B -The window displaying buffer B. - -@item ediff-window-C -The window displaying buffer C, if any. - -@item ediff-control-frame -A dedicated frame displaying the control buffer, if it exists. It is -non-@code{nil} only if Ediff uses the multiframe display, i.e., when -the control buffer is in its own frame. -@end table - -@node Credits -@chapter Credits - -Ediff was written by Michael Kifer . It was inspired -by emerge.el written by Dale R. Worley . An idea due to -Boris Goldowsky made it possible to highlight -fine differences in Ediff buffers. Alastair Burt -ported Ediff to XEmacs, Eric Freudenthal -made it work with VC, Marc Paquette wrote the -toolbar support package for Ediff, and Hrvoje Niksic -adapted it to the Emacs customization package. - -Many people provided help with bug reports, feature suggestions, and advice. -Without them, Ediff would not be nearly as useful as it is today. -Here is a hopefully full list of contributors: - -@example -Adrian Aichner (aichner at ecf.teradyne.com), -Drew Adams (drew.adams at oracle.com), -Steve Baur (steve at xemacs.org), -Neal Becker (neal at ctd.comsat.com), -E. Jay Berkenbilt (ejb at ql.org), -Lennart Borgman (ennart.borgman at gmail.com) -Alastair Burt (burt at dfki.uni-kl.de), -Paul Bibilo (peb at delcam.co.uk), -Kevin Broadey (KevinB at bartley.demon.co.uk), -Harald Boegeholz (hwb at machnix.mathematik.uni-stuttgart.de), -Bradley A. Bosch (brad at lachman.com), -Michael D. Carney (carney at ltx-tr.com), -Jin S. Choi (jin at atype.com), -Scott Cummings (cummings at adc.com), -Albert Dvornik (bert at mit.edu), -Eric Eide (eeide at asylum.cs.utah.edu), -Paul Eggert (eggert at twinsun.com), -Urban Engberg (ue at cci.dk), -Kevin Esler (esler at ch.hp.com), -Robert Estes (estes at ece.ucdavis.edu), -Jay Finger (jayf at microsoft.com), -Xavier Fornari (xavier at europe.cma.fr), -Eric Freudenthal (freudent at jan.ultra.nyu.edu), -Job Ganzevoort (Job.Ganzevoort at cwi.nl), -Felix Heinrich Gatzemeier (felix.g at tzemeier.info), -Boris Goldowsky (boris at cs.rochester.edu), -Allan Gottlieb (gottlieb at allan.ultra.nyu.edu), -Aaron Gross (aaron at bfr.co.il), -Thorbjoern Hansen (thorbjoern.hansen at mchp.siemens.de), -Marcus Harnisch (marcus_harnisch at mint-tech.com), -Steven E. Harris (seh at panix.com), -Aaron S. Hawley (Aaron.Hawley at uvm.edu), -Xiaoli Huang (hxl at epic.com), -Andreas Jaeger (aj at suse.de), -Lars Magne Ingebrigtsen (larsi at ifi.uio.no), -Larry Gouge (larry at itginc.com), -Karl Heuer (kwzh at gnu.org), -(irvine at lks.csi.com), -(jaffe at chipmunk.cita.utoronto.ca), -David Karr (dkarr at nmo.gtegsc.com), -Norbert Kiesel (norbert at i3.informatik.rwth-aachen.de), -Steffen Kilb (skilb at gmx.net), -Leigh L Klotz (klotz at adoc.xerox.com), -Fritz Knabe (Fritz.Knabe at ecrc.de), -Heinz Knutzen (hk at informatik.uni-kiel.d400.de), -Andrew Koenig (ark at research.att.com), -Hannu Koivisto (azure at iki.fi), -Ken Laprade (laprade at dw3f.ess.harris.com), -Will C Lauer (wcl at cadre.com), -Richard Levitte (levitte at e.kth.se), -Mike Long (mike.long at analog.com), -Dave Love (d.love at dl.ac.uk), -Martin Maechler (maechler at stat.math.ethz.ch), -Simon Marshall (simon at gnu.org), -Paul C. Meuse (pmeuse at delcomsys.com), -Richard Mlynarik (mly at adoc.xerox.com), -Stefan Monnier (monnier at cs.yale.edu), -Chris Murphy (murphycm at sun.aston.ac.uk), -Erik Naggum (erik at naggum.no), -Eyvind Ness (Eyvind.Ness at hrp.no), -Ray Nickson (nickson at cs.uq.oz.au), -Dan Nicolaescu (dann at ics.uci.edu), -David Petchey (petchey_david at jpmorgan.com), -Benjamin Pierce (benjamin.pierce at cl.cam.ac.uk), -Francois Pinard (pinard at iro.umontreal.ca), -Tibor Polgar (tlp00 at spg.amdahl.com), -David Prince (dave0d at fegs.co.uk), -Paul Raines (raines at slac.stanford.edu), -Stefan Reicher (xsteve at riic.at), -Charles Rich (rich at merl.com), -Bill Richter (richter at math.nwu.edu), -C.S. Roberson (roberson at aur.alcatel.com), -Kevin Rodgers (kevin.rodgers at ihs.com), -Sandy Rutherford (sandy at ibm550.sissa.it), -Heribert Schuetz (schuetz at ecrc.de), -Andy Scott (ascott at pcocd2.intel.com), -Axel Seibert (axel at tumbolia.ppp.informatik.uni-muenchen.de), -Vin Shelton (acs at xemacs.org), -Scott O. Sherman (Scott.Sherman at mci.com), -Nikolaj Schumacher (n_schumacher at web.de), -Richard Stallman (rms at gnu.org), -Richard Stanton (stanton at haas.berkeley.edu), -Sam Steingold (sds at goems.com), -Ake Stenhoff (etxaksf at aom.ericsson.se), -Stig (stig at hackvan.com), -Peter Stout (Peter_Stout at cs.cmu.edu), -Chuck Thompson (cthomp at cs.uiuc.edu), -Ray Tomlinson (tomlinso at bbn.com), -Raymond Toy (toy at rtp.ericsson.se), -Stephen J. Turnbull (stephen at xemacs.org), -Jan Vroonhof (vroonhof at math.ethz.ch), -Colin Walters (walters at cis.ohio-state.edu), -Philippe Waroquiers (philippe.waroquiers at eurocontrol.be), -Klaus Weber (gizmo at zork.north.de), -Ben Wing (ben at xemacs.org), -Tom Wurgler (twurgler at goodyear.com), -Steve Youngs (youngs at xemacs.org), -Ilya Zakharevich (ilya at math.ohio-state.edu), -Eli Zaretskii (eliz at is.elta.co.il) -@end example - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Index -@unnumbered Index -@printindex cp - -@bye diff --git a/doc/misc/edt.texi b/doc/misc/edt.texi deleted file mode 100644 index 6e066220020..00000000000 --- a/doc/misc/edt.texi +++ /dev/null @@ -1,944 +0,0 @@ -\input texinfo -@setfilename ../../info/edt -@settitle EDT Emulation for Emacs -@documentencoding UTF-8 - -@copying -This file documents the EDT emulation package for Emacs. - -Copyright @copyright{} 1986, 1992, 1994--1995, 1999--2014 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* EDT: (edt). An Emacs emulation of the EDT editor. -@end direntry - -@titlepage -@title EDT Emulation User's Manual -@author Kevin Gallagher -@author @email{Kevin.Gallagher@@boeing.com} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs EDT emulation -This manual describes the Emacs EDT package, which provides emulation -of DEC's EDT editor. - -@insertcopying -@end ifnottex - -@menu -* Overview:: Overview of the EDT package. -* Supported terminals:: Terminals/keyboards that are supported. -* Starting emulation:: How to get started. -* Platform-specific notes:: Notes specific to certain platforms. -* Differences:: How does this EDT emulation differ from real EDT? -* Highlights:: Some highlights, and comparisons to the - original Emacs EDT emulation. -* Customizing:: Customizing emulation. -* GNU Free Documentation License:: The license for this manual. -@end menu - -@node Overview -@chapter Overview of the EDT Package - -This manual describes version 4.0 of the EDT Emulation for Emacs. -It comes with special functions which replicate nearly all of -EDT's keypad mode behavior. It sets up default keypad and function key -bindings which closely match those found in EDT@. Support is provided so -that users may reconfigure most keypad and function key bindings to -their own liking. - -Version 4.0 contains several enhancements (@pxref{Changes}). - -@menu -* Quick start:: How to begin using EDT. -* Changes:: What's new in version 4.0. -* Goals:: The aims of this package. -@end menu - -@node Quick start -@section How to Begin Using EDT - -To start the EDT Emulation, first start Emacs and then enter @kbd{M-x -edt-emulation-on} to begin the emulation. After initialization is -complete, the following message will appear below the status line -informing you that the emulation has been enabled: ``Default EDT keymap -active''. - - You can have the EDT Emulation start up automatically, each time you -initiate an Emacs session, by adding the following line to your -@file{.emacs} file: - -@example -(add-hook 'emacs-startup-hook 'edt-emulation-on) -@end example - -@noindent @strong{Important:} Be sure to read the rest of this manual. -It contains very useful information on how the EDT Emulation behaves and -how to customize it to your liking. - -@noindent The EDT emulation consists of the following files: - -@itemize - -@item -@file{edt.texi}---This manual. - -@item -@file{edt-user.el}---An example customization file. - -@item -@file{edt.el}---EDT emulation functions and default configuration. - -@item -@file{edt-lk201.el}---Built-in support for DEC LK-201 keyboards. - -@item -@file{edt-vt100.el}---Built-in support for DEC VT-100 (and above) terminals. - -@item -@file{edt-pc.el}---Built-in support for PC 101 Keyboards under MS-DOS. - -@item -@file{edt-mapper.el}---Create an EDT LK-201 map file for keyboards -without built-in support. - -@end itemize - -@node Changes -@section What's New in Version 4.0 - -Version 4.0 contains the following enhancements: - -@enumerate - -@item -Scroll margins at the top and bottom of the window are now supported. -(The design was copied from @file{tpu-extras.el}.) By default, this -feature is enabled with the top margin set to 10% of the window and the -bottom margin set to 15% of the window. To change these settings, you -can invoke the function @code{edt-set-scroll-margins} in your -@file{.emacs} file. For example, the following line - -@example -(edt-set-scroll-margins "20%" "25%") -@end example - -@noindent sets the top margin to 20% of the window and the bottom margin -to 25% of the window. To disable this feature, set each margin to 0%. -You can also invoke @code{edt-set-scroll-margins} interactively while -EDT Emulation is active to change the settings for that session. - -@strong{Please note:} Another way to set the scroll margins is to use -the Emacs customization feature to set the following two variables -directly: @code{edt-top-scroll-margin} and @code{edt-bottom-scroll-margin}. - -Enter the Emacs @code{customize} command. First select the -@samp{Editing} group and then select the @samp{Emulations} group. -Finally, select the @samp{Edt} group and follow the directions. - -@item -The @samp{SUBS} command is now supported and bound to @kbd{GOLD-Enter} -by default. (This design was copied from @file{tpu-edt.el}.) Note, in -earlier versions of EDT Emulation, @kbd{GOLD-Enter} was assigned to the -Emacs function @code{query-replace}. The binding of -@code{query-replace} has been moved to @kbd{GOLD-/}. If you prefer to -restore @code{query-replace} to @kbd{GOLD-Enter}, then use an EDT user -customization file, @file{edt-user.el}, to do this -(@pxref{Customizing}). - -@item -EDT Emulation now also works in XEmacs, including the highlighting of -selected text. - -@item -If you access a workstation using an X Server, observe that the -initialization file generated by @file{edt-mapper.el} will now contain -the name of the X Server vendor. This is a convenience for those who -have access to their Unix account from more than one type of X Server. -Since different X Servers typically require different EDT emulation -initialization files, @file{edt-mapper.el} will now generate these -different initialization files and save them with different names. -Then, the correct initialization file for the particular X server in use -is loaded correctly automatically. - -@item -Also, @file{edt-mapper.el} is now capable of binding an @acronym{ASCII} -key sequence, providing the @acronym{ASCII} key sequence prefix is -already known by Emacs to be a prefix. As a result of providing this -support, some terminal/keyboard/window system configurations, which -don't have a complete set of sensible function key bindings built into -Emacs in @code{function-key-map}, can still be configured for use with -EDT Emulation. (Note: In a few rare circumstances this does not work -properly. In particular, it does not work if a subset of the leading -@acronym{ASCII} characters in a key sequence are recognized by Emacs as -having an existing binding. For example, if the keypad 7 (@key{KP7}) -key generates the sequence @samp{Ow} and @samp{O} is already -bound to a function, pressing @key{KP7} when told to do so by -@file{edt-mapper.el} will result in @file{edt-mapper.el} incorrectly -mapping @samp{O} to @key{KP7} and @samp{w} to @key{KP8}. If -something like this happens to you, it is probably a bug in the support -for your keyboard within Emacs @strong{or} a bug in the Unix -termcap/terminfo support for your terminal @strong{or} a bug in the -terminal emulation software you are using.) - -@item -The @code{edt-quit} function (bound to @kbd{GOLD-q} by default) has been -modified to warn the user when file-related buffer modifications exist. -It now cautions the user that those modifications will be lost if the -user quits without saving those buffers. - -@end enumerate - -@node Goals -@section The Aims of this Package - -@enumerate - -@item -Emulate EDT Keypad Mode commands closely so that current EDT users will -find that it easy and comfortable to use Emacs with a small learning -curve. - -@item -Make it easy for a user to customize EDT emulation key bindings without -knowing much about Emacs Lisp. - -@item -Make it easy to switch between the original EDT default bindings and the -user's customized EDT bindings, without having to exit Emacs. - -@item -Provide support for some TPU/EVE functions not supported in EDT. - -@item -Provide an easy way to restore @strong{all} original Emacs key bindings, -just as they existed before the EDT emulation was first invoked. - -@item -Support Emacs and XEmacs 19 and higher. - -@item -Supports highlighting of marked text within the EDT emulation on all -platforms on which Emacs supports highlighting of marked text. - -@item -Handle terminal configuration interactively for most terminal -configurations, when the emulation is invoked for the first time. - -@item -Support a PC AT keyboard under MS-DOS. - -@end enumerate - -@node Supported terminals -@chapter Terminals/Keyboards that are Supported - -Keyboards used under a Window System are supported via the -@code{edt-mapper} function. The first time you invoke the emulation -under a window system, the @code{edt-mapper} function is run -automatically and the user is prompted to identify which keys the -emulation is to use for the standard keypad and function keys EDT -expects (e.g., @key{PF1}, @key{PF2}, @key{KP0}, @key{KP1}, @key{F1}, -@key{F2}, etc.). This configuration is saved to disk read each time the -emulation is invoked. - -In character oriented connections not running a window manager, built-in -support for the following terminals/keyboards is provided: - -@enumerate - -@item -DEC VT-100 series and higher. This includes well behaved VT clones and -emulators. If you are using a VT series terminal, be sure that the -@env{TERM} environment variable is set properly before invoking emacs. - -@item -PC AT keyboard under MS-DOS. - -@end enumerate - -Be sure to read @ref{Platform-specific notes} to see if those notes -apply to you. - -@node Starting emulation -@chapter How to Get Started - -Start up Emacs and enter @kbd{M-x edt-emulation-on} to begin the -emulation. After initialization is complete, the following message will -appear below the status line informing you that the emulation has been -enabled: ``Default EDT keymap active''. - -You can have the EDT Emulation start up automatically, each time you -initiate an Emacs session, by adding the following line to your -@file{.emacs} file: - -@example -(add-hook 'emacs-startup-hook 'edt-emulation-on) -@end example - -A reference sheet is included (later on) listing the default EDT -Emulation key bindings. This sheet is also accessible on line from -within Emacs by pressing @key{PF2}, @kbd{GOLD-H}, or @samp{HELP} (when -in the EDT Default Mode). - -It is easy to customize key bindings in the EDT Emulation -(@pxref{Customizing}). Customizations are placed in a file called -@file{edt-user.el}. The Emacs @file{etc/} directory contains an -example. If @file{edt-user.el} is found in your Emacs load path -during EDT Emulation initialization, then the following message will -appear below the status line indicating that the emulation has been -enabled, enhanced by your own customizations: ``User EDT custom keymap -active''. - -Once enabled, it is easy to switch back and forth between your -customized EDT Emulation key bindings and the default EDT Emulation key -bindings. (Look at the binding to @kbd{GOLD-Z} in the sample -@file{edt-user.el} file.) It is also easy to turn off the emulation -(via the command @code{edt-emulation-off}). Doing so completely -restores the original key bindings in effect just prior to invoking the -emulation. - -Emacs binds keys to @acronym{ASCII} control characters and so does the -real EDT@. Where EDT key bindings and Emacs key bindings conflict, -the default Emacs key bindings are retained by the EDT emulation by -default. If you are a diehard EDT user you may not like this. The -@ref{Control keys} section explains how to change this so that the EDT -bindings to @acronym{ASCII} control characters override the default -Emacs bindings. - -@node Platform-specific notes -@chapter Notes Specific to Certain Platforms - -@menu -* Sun workstations:: Sun workstations running X. -* MS-DOS:: PC users running MS-DOS. -* GNU/Linux:: PC users running GNU/Linux. -* Unix:: Using @key{NumLock} for the @key{PF1} key on Unix systems. -@end menu - -@node Sun workstations -@section Sun Workstations Running X - -Some earlier Sun keyboards do not have arrow keys separate from the -keypad keys. It is difficult to emulate the full EDT keypad and still -retain use of the arrow keys on such keyboards. - -The Sun Type 5 and other more recent Sun keyboards, however, do have -separate arrow keys. This makes them candidates for setting up a -reasonable EDT keypad emulation. - -Depending upon the configuration of the version of X installed on your -system, you may find the default X keynames for the keypad keys don't -permit Emacs to interpret some or all the keypad keys as something other -than arrow keys, numeric keys, @key{Home}, @key{PageUp}, etc. Both Sun -and HP have been particularly guilty of making bizarre keysym -assignments to the keypad keys. - -In most cases, the X Windows command, @code{xmodmap}, can be used to -correct the problem. Here's a sample @file{.xmodmaprc} file which -corrects this problem on one Sun workstation configuration using an -older SunOS release configured with a Sun Type 5 keyboard: - -@example -! File: .xmodmaprc -! -! Set up Sun Type 5 keypad for use with the Emacs EDT Emulation -! -keycode 53 = KP_Divide -keycode 54 = KP_Multiply -keycode 57 = KP_Decimal -keycode 75 = KP_7 -keycode 76 = KP_8 -keycode 77 = KP_9 -keycode 78 = KP_Subtract -keycode 97 = KP_Enter -keycode 98 = KP_4 -keycode 99 = KP_5 -keycode 100 = KP_6 -keycode 101 = KP_0 -keycode 105 = F24 -keycode 119 = KP_1 -keycode 120 = KP_2 -keycode 121 = KP_3 -keycode 132 = KP_Add -@end example - -If @file{edt-mapper.el} does not recognize your keypad keys as unique -keys, use the command @samp{xmodmap -pke} to get a listing of the actual -key codes and the keysyms mapped to them and then generate you own -custom @file{.xmodmaprc} similar to the one above. - -Next, feed @file{.xmodmaprc} to the @code{xmodmap} command and all the -Sun Type 5 keypad keys will now be configurable for the emulation of an -LK-201 keypad (less the @key{,} key). In this example, the line - -@example -keycode 105 = F24 -@end example - -@noindent changes the X Windows name of the keypad @key{NumLock} key to -be known internally as the @key{F24} key. Doing so permits it to be -configured to behave as the @key{PF1} (@key{GOLD}) key. - -The side effect of this change is that you will no longer have a -@key{NumLock} key. If you are using other software under X which -requires a @key{NumLock} key, then examine your keyboard and look for -one you don't use and redefine it to be the @key{NumLock} key. -Basically, you need to clear the @key{NumLock} key from being assigned -as a modifier, assign it to the key of your choice, and then add it back -as a modifier. (@ref{Unix} for further help on how to do this.) - -@node MS-DOS -@section PC Users Running MS-DOS - -By default, F1 is configured to emulate the @key{PF1} (@key{GOLD}) key. -But @key{NumLock} can be used instead if you load a freeware TSR -distributed with MS-Kermit, call @samp{gold.com}. This was once -distributed in a file called @file{gold22.zip} and came with the source -code as well as a loadable binary image. (See @file{edt-pc.el} in the -Emacs @file{lisp/emulation} directory for more information.) - -@node GNU/Linux -@section PC Users Running GNU/Linux - -The default X server configuration varies from distribution to -distribution and release to release of GNU/Linux. If your system fails -to recognize the keypad keys as distinct keys, change the NumLock state, -turning it on or off, as the case may be, then try again. If this -doesn't solve your problem, you may have to modify the X keysym mappings -with @code{xmodmap}. - -On one distribution on an Intel PC, the following @file{.xmodmaprc} set -things up nicely. - -@example -! File: .xmodmaprc -! -! Set up PC keypad under GNU/Linux for the Emacs EDT Emulation -! -clear mod2 -keycode 77 = F12 -keycode 96 = Num_Lock Pointer_EnableKeys -add mod2 = Num_Lock -@end example - -In this example, after feeding the file to the @code{xmodmap} command, -the PC @key{NumLock} keypad key will be configurable for the emulation -of the @key{PF1} key. The PC keypad can now emulate an LK-201 keypad -(less the comma key), the standard keyboard supplied with DEC terminals -VT-200 and above. This @file{.xmodmaprc} file switches the role of the -@key{F12} and @key{NumLock} keys. It has been tested on RedHat -GNU/Linux 5.2. Other versions of GNU/Linux may require different -keycodes. (@ref{Unix} for further help on how to do this.) - -@strong{Please note:} Remember, it may be necessary to have @key{NumLock} in -one position (ON) or the other (OFF) for the PC keypad to emulate the -LK-201 keypad properly. - -@node Unix -@section General Notes on Using @key{NumLock} for the @key{PF1} Key on Unix Systems - -Making the physical @key{NumLock} key available for use in the EDT Emulation -requires some modification to the default X Window settings. Since the -keycode assignments vary from system to system, some investigation is -needed to see how to do this on a particular system. - -You will need to look at the output generated by @code{xmodmap} invoked -with the "-pm" switch. For example, on RedHat GNU/Linux 5.2 on a PC, we -get the following output when running @samp{xmodmap -pm}: - -@example -xmodmap: up to 2 keys per modifier, (keycodes in parentheses): - -shift Shift_L (0x32), Shift_R (0x3e) -lock Caps_Lock (0x42) -control Control_L (0x25), Control_R (0x6d) -mod1 Alt_L (0x40), Alt_R (0x71) -mod2 Num_Lock (0x4d) -mod3 -mod4 -mod5 Scroll_Lock (0x4e) -@end example - -@noindent Note that Num_Lock is assigned to the modifier @samp{mod2}. This is -what hides Num_Lock from being seen by Emacs. - -Now, @samp{xmodmap -pke} yields: - -@example - . - . - . -keycode 77 = Num_Lock Pointer_EnableKeys - . - . - . -keycode 96 = F12 - . - . - . -@end example - -@noindent So, in RedHat GNU/Linux 5.2 on a PC, Num_Lock generates keycode 77. -The following steps are taken: - -@enumerate -@item -clear the assignment of Num_Lock to mod2; -@item -swap the keycodes assigned to F12 and Num_Lock; -@item -assign Num_Lock back to mod2. -@end enumerate - -@noindent The @file{.xmodmaprc} file looks like this: - -@example -! File: .xmodmaprc -! -! Set up PC keypad under GNU/Linux for the Emacs EDT Emulation -! -clear mod2 -keycode 77 = F12 -keycode 96 = Num_Lock Pointer_EnableKeys -add mod2 = Num_Lock -@end example - -So, after executing @samp{xmodmap .xmodmaprc}, a press of the physical -@key{F12} key looks like a Num_Lock keypress to X@. Also, a press of the -physical @key{NumLock} key looks like a press of the @key{F12} key to X. - -Now, @file{edt-mapper.el} will see @samp{f12} when the physical -@key{NumLock} key is pressed, allowing the @key{NumLock} key to be used -as the EDT @key{PF1} (@key{GOLD}) key. - -@node Differences -@chapter How Does this EDT Emulation Differ from Real EDT? - -In general, you will find that this emulation of EDT replicates most, -but not all, of EDT's most used Keypad Mode editing functions and -behavior. It is not perfect, but most EDT users who have tried the -emulation agree that it is quite good enough to make it easy for -die-hard EDT users to move over to using Emacs. - -Here's a list of the most important differences between EDT and this GNU -Emacs EDT Emulation. The list is short but you must be aware of these -differences if you are to use the EDT Emulation effectively. - -@enumerate - -@item -Entering repeat counts works a little differently than in EDT. - -EDT allows users to enter a repeat count before entering a command that -accepts repeat counts. For example, when using the real EDT, pressing -these three keys in sequence, @kbd{GOLD 5 KP1}, will move the cursor in -the current direction 5 words. This does @strong{not} work in Emacs! - -Emacs provides two ways to enter repeat counts and neither involves -using the @key{GOLD} key. First, repeat counts can be entered in Emacs -by using the @key{ESC} key. For example, pressing these keys in -sequence, @kbd{ESC 1 0 KP1}, will move the cursor in the current -direction 10 words. Second, Emacs provides another command called -@code{universal-argument} that can be used to do the same thing. -Normally, in Emacs has this bound to @kbd{C-u}. - -@item -EDT's line mode commands and nokeypad mode commands are @strong{not} -supported (with one important exception; see item 8 in -@ref{Highlights}). Although, at first, this may seem like a big -omission, the set of built-in Emacs commands provides a much richer set -of capabilities which more than make up for this omission. - -To enter Emacs commands not bound to keys, you can press @kbd{GOLD KP7} -or the @key{DO} key. Emacs will display its own command prompt "M-x". -This stands for the keypress @kbd{Meta-x}, where @key{Meta} is a special -shift key. The @key{Alt} key is often mapped to behave as a @key{Meta} -key. So, you can also invoke this prompt by pressing @kbd{Meta-x}. -Typing the sequence @kbd{ESC x} will also invoke the prompt. - -@item -Selected text is highlighted @strong{only} on systems where Emacs -supports the highlighting of text. - -@item -Just like in TPU/EVE, the @key{ENTER} key is @strong{not} used to -terminate input when the editor prompts you for input. The @key{RETURN} -key is used, instead. (@key{KP4} and @key{KP5} (the direction keys) do -terminate input for the @samp{FIND} command, just like in EDT, however.) - -@end enumerate - -@node Highlights -@chapter Some Highlights, and Comparisons to the Original Emacs EDT Emulation - -@enumerate - -@item -The EDT define key command is supported (@code{edt-define-key}) and is -bound to @kbd{C-k} in the default EDT mode when EDT control sequence -bindings are enabled, or when the sample @file{edt-user.el} -customization file is used. The TPU/EVE learn command is supported but -not bound to a key in the default EDT mode but is bound in the sample -@file{edt-user.el} file. - -Unlike the TPU/EVE learn command, which uses one key to begin the learn -sequence, @kbd{C-l}, and another command to remember the sequence, -@kbd{C-r}, this version of the learn command (@code{edt-learn}) serves -as a toggle to both begin and to remember the learn sequence. - -Many users who change the meaning of a key with the define key and the -learn commands, would like to be able to restore the original key -binding without having to quit and restart emacs. So a restore key -command is provided to do just that. When invoked, it prompts you to -press the key to which you wish the last replaced key definition -restored. It is bound to @kbd{GOLD C-k} in the default EDT mode when -EDT control sequence bindings are enabled or the sample -@file{edt-user.el} customization file is used. - -@item -Direction support is fully supported. - -@item -All original Emacs bindings are fully restored when EDT emulation is -turned off. So, if a fellow worker comes over to your terminal to help -you with a software problem, for example, and is completely confused by -your EDT emulation bindings, just enter the command, -@code{edt-emulation-off}, at the @samp{M-x} prompt and the original -Emacs bindings will be restored. To resume the EDT emulation, just -enter @code{edt-emulation-on}. - -@item -User custom EDT bindings are kept separate from the default EDT -bindings. One can toggle back and forth between the custom EDT bindings -and default EDT bindings. - -@item -The Emacs functions in @file{edt.el} attempt to emulate, where -practical, the exact behavior of the corresponding EDT keypad mode -commands. In a few cases, the emulation is not exact, but we hope you -will agree it is close enough. In a very few cases, we chose to use the -Emacs way of handling things. As mentioned earlier, we do not emulate -the EDT @samp{SUBS} command. Instead, we chose to use the Emacs -@code{query-replace} function, which we find to be easier to use. - -@item -Emacs uses the regexp assigned to @code{page-delimiter} to determine -what marks a page break. This is normally @samp{^\f}, which causes the -@code{edt-page} command to ignore form feeds not located at the -beginning of a line. To emulate the EDT @samp{PAGE} command exactly, -page-delimiter is set to @samp{\f} when EDT emulation is turned on, and -restored to @samp{^\f} when EDT emulation is turned off. But, since -some users prefer the Emacs definition of a page break, or may wish to -preserve a customized definition of page break, one can override the EDT -definition by placing - -@example -(setq edt-keep-current-page-delimiter t) -@end example - -@noindent in your @file{.emacs} file. Or, you can used the Emacs customize -command to change its setting. - -@item -The EDT definition of a section of a terminal window is hardwired to be -16 lines of its one-and-only 24-line window (the EDT @samp{SECT} command -bound to @key{KP8}). That's two-thirds of the window at a time. Since -Emacs, like TPU/EVE, can handle multiple windows of sizes of other than -24 lines, the definition of section used here has been modified to -two-thirds of the current window. (There is also an -@code{edt-scroll-window} function which you may prefer over the -@samp{SECT} emulation.) - -@item -Cursor movement and deletion involving word entities is identical to -EDT@. This, above all else, gives the die-hard EDT user a sense of being -at home. Also, an emulation of EDT's @samp{SET ENTITY WORD} command is -provided, for those users who like to customize movement by a word at a -time to their own liking. - -@item -EDT's @samp{FIND} and @samp{FNDNXT} are supported. - -@item -EDT's @samp{APPEND}, @samp{REPLACE}, and @samp{SUBS} commands are supported. - -@item -@samp{CHNGCASE} is supported. It works on individual characters or -selected text, if @samp{SELECT} is active. In addition, two new -commands are provided: @code{edt-lowercase} and @code{edt-uppercase}. -They work on individual @strong{words} or selected text, if -@samp{SELECT} is active. - -@item -Form feed and tab insert commands are supported. - -@item -A new command, @code{edt-duplicate-word}, is provided. If you -experiment with it, you might find it to be surprisingly useful and may -wonder how you ever got along without it! It is assigned to @kbd{C-j} -in the sample @file{edt-user.el} customization file. - -@item -TPU/EVE's Rectangular Cut and Paste functions (originally from the -EVE-Plus package) are supported. But unlike the TPU/EVE versions, these -here support both insert and overwrite modes. The seven rectangular -functions are bound to @key{F7}, @key{F8}, @kbd{GOLD-F8}, @key{F9}, -@kbd{GOLD-F9}, @key{F10}, and @kbd{GOLD-F10} in the default EDT mode. - -@item -The original EDT emulation package set up many default regular and GOLD -bindings. We tried to preserve most (but not all!) of these, so users -of the original emulation package will feel more at home. - -Nevertheless, there are still many GOLD key sequences which are not -bound to any functions. These are prime candidates to use for your own -customizations. - -Also, there are several commands in @file{edt.el} not bound to any key. -So, you will find it worthwhile to look through @file{edt.el} for -functions you may wish to add to your personal customized bindings. - -@item -The VT200/VT300 series terminals steal the function keys @key{F1} to -@key{F5} for their own use. These do not generate signals which are -sent to the host. So, @file{edt.el} does not assign any default -bindings to @key{F1} through @key{F5}. - -In addition, our VT220 terminals generate an interrupt when the @key{F6} -key is pressed (@samp{^C} or @samp{^Y}, can't remember which) and not -the character sequence documented in the manual. So, binding Emacs -commands to @key{F6} will not work if your terminal behaves the same -way. - -@item -The VT220 terminal has no @key{ESC}, @key{BS}, nor @key{LF} keys, as -does a VT100. So the default EDT bindings adopt the standard DEC -convention of having the @key{F11}, @key{F12}, and @key{F13} keys, on a -VT200 series (and above) terminal, assigned to the same EDT functions -that are bound to @key{ESC}, @key{BS}, and @key{LF} on a VT100 terminal. - -@item -Each user, through the use of a private @file{edt-user.el} file, can -customize, very easily, personal EDT emulation bindings. - -@item -The EDT @samp{SELECT} and @samp{RESET} functions are supported. -However, unlike EDT, pressing @samp{RESET} to cancel text selection does -@strong{not} reset the existing setting of the current direction. - -We also provide a TPU/EVE like version of the single @samp{SELECT/RESET} -function, called @code{edt-toggle-select}, which makes the EDT -@samp{SELECT} function into a toggle on/off switch. That is, if -selection is on, pressing @samp{SELECT} again turns selection off -(cancels selection). This function is used in the sample -@file{edt-user.el} customization file. - -@item -EDT scroll margins are supported, but are disabled by default. -(@ref{Scroll margins} for instructions on how to enable them.) - -@end enumerate - -@node Customizing -@chapter Customizing Emulation - -Most EDT users, at one time or another, make some custom key bindings, -or use someone else's custom key bindings, which they come to depend -upon just as if they were built-in bindings. This EDT Emulation for GNU -Emacs is designed to make it easy to customize bindings. - -If you wish to customize the EDT Emulation to use some of your own key -bindings, you need to make a private version of @file{edt-user.el} in -your own private lisp directory. The Emacs @file{etc/} directory -contains an example for you to use as a template and for ideas. -@c This seems to be untrue. -@ignore -There are two sample files @file{edt-user.el1} and @file{edt-user.el2} -for you to use as templates and for ideas. Look at @file{edt-user.el1} -first. Unless you will be using two or more very different types of -terminals on the same system, you need not look at @file{edt-user.el2}. -@end ignore - -First, you need to have your own private lisp directory, say -@file{~/lisp}, and you should add it to the Emacs load path. - -@strong{Please note:} A few sites have different load-path requirements, -so the above directions may need some modification if your site has such -special needs. - -@menu -* Init file:: Creating your own @file{edt-user.el} file. -* Words:: Specifying word entities. -* Control keys:: Enabling EDT control key sequence bindings. -* Scroll margins:: Setting scroll margins. -@end menu - -@node Init file -@section Creating your own @file{edt-user.el} File - -A sample @file{edt-user.el} file is provided in the Emacs @file{etc/} -directory. You should use it as a guide to learn how you can customize -EDT emulation bindings to your own liking. Names used to identify the -set of LK-201 keypad and function keys are: - -@example -Keypad Keys: - PF1 PF2 PF3 PF4 - KP7 KP8 KP9 KP- - KP4 KP5 KP6 KP, - KP1 KP2 KP3 - KP0 KPP KPE -@end example - -@example -Arrow Keys: - LEFT RIGHT DOWN UP -@end example - -@example -Function Keys: - F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 - HELP DO F17 F18 F19 F20 - - FIND INSERT REMOVE - SELECT PREVIOUS NEXT -@end example - -Note: Many VT-200 terminals, and above, steal function keys @key{F1} -through @key{F5} for terminal setup control and don't send anything to -the host if pressed. So customizing bindings to these keys may not work -for you. - -There are three basic functions that do the EDT emulation custom -bindings: @code{edt-bind-key}, @code{edt-bind-gold-key}, and -@code{edt-bind-function-key}. - -The first two are for binding functions to keys which are standard -across most keyboards. This makes them keyboard independent, making it -possible to define these key bindings for all terminals in the file -@file{edt.el}. - -The first, @code{edt-bind-key}, is used typically to bind emacs commands -to control keys, although some people use it to bind commands to other -keys, as well. (For example, some people use it to bind the VT200 -seldom used back-tick key (@samp{`}) to the function @samp{ESC-prefix} -so it will behave like an @key{ESC} key.) The second function, -@code{edt-bind-gold-key}, is used to bind emacs commands to gold key -sequences involving alpha-numeric keys, special character keys, and -control keys. - -The third function, @code{edt-bind-function-key}, is terminal dependent -and is defined in a terminal specific file (see @file{edt-vt100.el} for -example). It is used to bind emacs commands to LK-201 function keys, to -keypad keys, and to gold sequences of those keys. - -@node Words -@section Specifying Word Entities - -The variable @code{edt-word-entities} is used to emulate EDT's @samp{SET -ENTITY WORD} command. It contains a list of characters to be treated as -words in themselves. If the user does not define -@code{edt-word-entities} in his/her @file{.emacs} file, then it is set -up with the EDT default containing only @key{TAB}. - -The characters are stored in the list by their numerical values, not as -strings. Emacs supports several ways to specify the numerical value of -a character. One method is to use the question mark: @samp{?A} means -the numerical value for @samp{A}, @samp{?/} means the numerical value -for @samp{/}, and so on. Several unprintable characters have special -representations: - -@example -?\b specifies BS, C-h -?\t specifies TAB, C-i -?\n specifies LFD, C-j -?\v specifies VTAB, C-k -?\f specifies FF, C-l -?\r specifies CR, C-m -?\e specifies ESC, C-[ -?\\ specifies \ -@end example - -Here are some examples: - -@example -(setq edt-word-entities '(?\t ?- ?/)) ; specifies TAB, - , and / -(setq edt-word-entities '(?\t) ; specifies TAB, the default -@end example - -@noindent You can also specify characters by their decimal ascii values: - -@example -(setq edt-word-entities '(9 45 47)) ; specifies TAB, - , and / -@end example - -@node Control keys -@section Enabling EDT Control Key Sequence Bindings - -Where EDT key bindings and Emacs key bindings conflict, the default -Emacs key bindings are retained by default. Some diehard EDT users -may not like this. So, if the variable -@code{edt-use-EDT-control-key-bindings} is set to true in a user's -@file{.emacs} file, then the default EDT Emulation mode will enable most -of the original EDT control key sequence bindings. If you wish to do -this, add the following line to your @file{.emacs} file: - -@example -(setq edt-use-EDT-control-key-bindings t) -@end example - -@node Scroll margins -@section Setting Scroll Margins - -Scroll margins at the top and bottom of the window are now supported. -(The design was copied from @file{tpu-extras.el}.) By default, this -feature is enabled with the top margin set to 10% of the window and the -bottom margin set to 15% of the window. To change these settings, you -can invoke the function @code{edt-set-scroll-margins} in your -@file{.emacs} file. For example, the following line - -@example -(edt-set-scroll-margins "20%" "25%") -@end example - -@noindent sets the top margin to 20% of the window and the bottom margin -to 25% of the window. To disable this feature, set each margin to 0%. -You can also invoke @code{edt-set-scroll-margins} interactively while -EDT Emulation is active to change the settings for that session. - -@strong{Please note:} Another way to set the scroll margins is to use -the Emacs customization feature to set the following two variables -directly: @code{edt-top-scroll-margin} and @code{edt-bottom-scroll-margin}. - -Enter the Emacs @code{customize} command. First select the -@samp{Editing} group and then select the @samp{Emulations} group. -Finally, select the @samp{Edt} group and follow the directions. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi deleted file mode 100644 index 937fae26907..00000000000 --- a/doc/misc/eieio.texi +++ /dev/null @@ -1,1911 +0,0 @@ -\input texinfo -@setfilename ../../info/eieio -@set TITLE Enhanced Implementation of Emacs Interpreted Objects -@set AUTHOR Eric M. Ludlam -@settitle @value{TITLE} -@documentencoding UTF-8 - -@c ************************************************************************* -@c @ Header -@c ************************************************************************* - -@copying -This manual documents EIEIO, an object framework for Emacs Lisp. - -Copyright @copyright{} 2007--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* EIEIO: (eieio). An objects system for Emacs Lisp. -@end direntry - -@titlepage -@center @titlefont{@value{TITLE}} -@sp 4 -@center by @value{AUTHOR} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@macro eieio{} -@i{EIEIO} -@end macro - -@node Top -@top EIEIO - -@eieio{} (``Enhanced Implementation of Emacs Interpreted Objects'') -provides an Object Oriented layer for Emacs Lisp, following the basic -concepts of the Common Lisp Object System (CLOS). It provides a -framework for writing object-oriented applications in Emacs. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Quick Start:: Quick start for EIEIO. -* Introduction:: Why use @eieio{}? Basic overview, samples list. -* Building Classes:: How to write new class structures. -* Making New Objects:: How to construct new objects. -* Accessing Slots:: How to access a slot. -* Writing Methods:: How to write a method. -* Method Invocation:: How methods are invoked. -* Predicates:: Class-p, Object-p, etc-p. -* Association Lists:: List of objects as association lists. -* Customizing:: Customizing objects. -* Introspection:: Looking inside a class. -* Base Classes:: Additional classes you can inherit from. -* Browsing:: Browsing your class lists. -* Class Values:: Displaying information about a class or object. -* Default Superclass:: The root superclasses. -* Signals:: When you make errors. -* Naming Conventions:: Name your objects in an Emacs friendly way. -* CLOS compatibility:: What are the differences? -* Wish List:: Things about EIEIO that could be improved. -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -@end menu - -@node Quick Start -@chapter Quick Start - -@eieio{} provides an Object Oriented layer for Emacs Lisp. You can -use @eieio{} to create classes, methods for those classes, and -instances of classes. - -Here is a simple example of a class named @code{record}, containing -three slots named @code{name}, @code{birthday}, and @code{phone}: - -@example -(defclass record () ; No superclasses - ((name :initarg :name - :initform "" - :type string - :custom string - :documentation "The name of a person.") - (birthday :initarg :birthday - :initform "Jan 1, 1970" - :custom string - :type string - :documentation "The person's birthday.") - (phone :initarg :phone - :initform "" - :documentation "Phone number.")) - "A single record for tracking people I know.") -@end example - -Each class can have methods, which are defined like this: - -@example -(defmethod call-record ((rec record) &optional scriptname) - "Dial the phone for the record REC. -Execute the program SCRIPTNAME to dial the phone." - (message "Dialing the phone for %s" (oref rec name)) - (shell-command (concat (or scriptname "dialphone.sh") - " " - (oref rec phone)))) -@end example - -@noindent -In this example, the first argument to @code{call-record} is a list, -of the form (@var{varname} @var{classname}). @var{varname} is the -name of the variable used for the first argument; @var{classname} is -the name of the class that is expected as the first argument for this -method. - -@eieio{} dispatches methods based on the type of the first argument. -You can have multiple methods with the same name for different classes -of object. When the @code{call-record} method is called, the first -argument is examined to determine the class of that argument, and the -method matching the input type is then executed. - -Once the behavior of a class is defined, you can create a new -object of type @code{record}. Objects are created by calling the -constructor. The constructor is a function with the same name as your -class which returns a new instance of that class. Here is an example: - -@example -(setq rec (record "Eric" :name "Eric" :birthday "June" :phone "555-5555")) -@end example - -@noindent -The first argument is the name given to this instance. Each instance -is given a name, so different instances can be easily distinguished -when debugging. - -It can be a bit repetitive to also have a :name slot. To avoid doing -this, it is sometimes handy to use the base class @code{eieio-named}. -@xref{eieio-named}. - -Calling methods on an object is a lot like calling any function. The -first argument should be an object of a class which has had this -method defined for it. In this example it would look like this: - -@example -(call-record rec) -@end example - -@noindent -or - -@example -(call-record rec "my-call-script") -@end example - -In these examples, @eieio{} automatically examines the class of -@code{rec}, and ensures that the method defined above is called. If -@code{rec} is some other class lacking a @code{call-record} method, or -some other data type, Emacs signals a @code{no-method-definition} -error. @ref{Signals}. - -@node Introduction -@chapter Introduction - -First off, please note that this manual cannot serve as a complete -introduction to object oriented programming and generic functions in -LISP. Although EIEIO is not a complete implementation of the Common -Lisp Object System (CLOS) and also differs from it in several aspects, -it follows the same basic concepts. Therefore, it is highly -recommended to learn those from a textbook or tutorial first, -especially if you only know OOP from languages like C++ or Java. If -on the other hand you are already familiar with CLOS, you should be -aware that @eieio{} does not implement the full CLOS specification and -also differs in some other aspects which are mentioned below (also -@pxref{CLOS compatibility}). - -@eieio{} supports the following features: - -@enumerate -@item -A structured framework for the creation of basic classes with attributes -and methods using singular inheritance similar to CLOS. -@item -Type checking, and slot unbinding. -@item -Method definitions similar to CLOS. -@item -Simple and complex class browsers. -@item -Edebug support for methods. -@item -Imenu updates. -@item -Byte compilation support of methods. -@item -Help system extensions for classes and methods. -@item -Several base classes for interesting tasks. -@item -Simple test suite. -@item -Public and private classifications for slots (extensions to CLOS) -@item -Customization support in a class (extension to CLOS) -@end enumerate - -Due to restrictions in the Emacs Lisp language, CLOS cannot be -completely supported, and a few functions have been added in place of -setf. Here are some important CLOS features that @eieio{} presently -lacks: - -@table @asis - -@item Method dispatch -EIEO does not support method dispatch for built-in types and multiple -arguments types. In other words, method dispatch only looks at the -first argument, and this one must be an @eieio{} type. - -@item Support for metaclasses -There is just one default metaclass, @code{eieio-default-superclass}, -and you cannot define your own. The @code{:metaclass} tag in -@code{defclass} is ignored. Also, functions like `find-class', which -should return instances of the metaclass, behave differently in -@eieio{} in that they return symbols or plain structures instead. - -@item EQL specialization -EIEIO does not support it. - -@item @code{:around} method tag -This CLOS method tag is non-functional. - -@item :default-initargs in @code{defclass} -Each slot has an @code{:initarg} tag, so this is not really necessary. - -@item Mock object initializers -Each class contains a mock object used for fast initialization of -instantiated objects. Using functions with side effects on object slot -values can potentially cause modifications in the mock object. @eieio{} -should use a deep copy but currently does not. - -@end table - -@node Building Classes -@chapter Building Classes - -A @dfn{class} is a definition for organizing data and methods -together. An @eieio{} class has structures similar to the classes -found in other object-oriented (OO) languages. - -To create a new class, use the @code{defclass} macro: - -@defmac defclass class-name superclass-list slot-list &rest options-and-doc - -Create a new class named @var{class-name}. The class is represented -by a self-referential symbol with the name @var{class-name}. @eieio{} -stores the structure of the class as a symbol property of -@var{class-name} (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp -Reference Manual}). - -The @var{class-name} symbol's variable documentation string is a -modified version of the doc string found in @var{options-and-doc}. -Each time a method is defined, the symbol's documentation string is -updated to include the methods documentation as well. - -The parent classes for @var{class-name} is @var{superclass-list}. -Each element of @var{superclass-list} must be a class. These classes -are the parents of the class being created. Every slot that appears -in each parent class is replicated in the new class. - -If two parents share the same slot name, the parent which appears in -the @var{superclass-list} first sets the tags for that slot. If the -new class has a slot with the same name as the parent, the new slot -overrides the parent's slot. - -When overriding a slot, some slot attributes cannot be overridden -because they break basic OO rules. You cannot override @code{:type} -or @code{:protection}. -@end defmac - -@noindent -Whenever defclass is used to create a new class, two predicates are -created for it, named @code{@var{CLASS-NAME}-p} and -@code{@var{CLASS-NAME}-child-p}: - -@defun CLASS-NAME-p object -Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}. -@end defun - -@defun CLASS-NAME-child-p object -Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}, -or is of a subclass of @var{CLASS-NAME}. -@end defun - -@defvar eieio-error-unsupported-class-tags -If non-@code{nil}, @code{defclass} signals an error if a tag in a slot -specifier is unsupported. - -This option is here to support programs written with older versions of -@eieio{}, which did not produce such errors. -@end defvar - -@menu -* Inheritance:: How to specify parents classes. -* Slot Options:: How to specify features of a slot. -* Class Options:: How to specify features for this class. -@end menu - -@node Inheritance -@section Inheritance - -@dfn{Inheritance} is a basic feature of an object-oriented language. -In @eieio{}, a defined class specifies the super classes from which it -inherits by using the second argument to @code{defclass}. Here is an -example: - -@example -(defclass my-baseclass () - ((slot-A :initarg :slot-A) - (slot-B :initarg :slot-B)) - "My Baseclass.") -@end example - -@noindent -To subclass from @code{my-baseclass}, we specify it in the superclass -list: - -@example -(defclass my-subclass (my-baseclass) - ((specific-slot-A :initarg specific-slot-A) - ) - "My subclass of my-baseclass") -@end example - -@indent -Instances of @code{my-subclass} will inherit @code{slot-A} and -@code{slot-B}, in addition to having @code{specific-slot-A} from the -declaration of @code{my-subclass}. - -@eieio{} also supports multiple inheritance. Suppose we define a -second baseclass, perhaps an ``interface'' class, like this: - -@example -(defclass my-interface () - ((interface-slot :initarg :interface-slot)) - "An interface to special behavior." - :abstract t) -@end example - -@noindent -The interface class defines a special @code{interface-slot}, and also -specifies itself as abstract. Abstract classes cannot be -instantiated. It is not required to make interfaces abstract, but it -is a good programming practice. - -We can now modify our definition of @code{my-subclass} to use this -interface class, together with our original base class: - -@example -(defclass my-subclass (my-baseclass my-interface) - ((specific-slot-A :initarg specific-slot-A) - ) - "My subclass of my-baseclass") -@end example - -@noindent -With this, @code{my-subclass} also has @code{interface-slot}. - -If @code{my-baseclass} and @code{my-interface} had slots with the same -name, then the superclass showing up in the list first defines the -slot attributes. - -Inheritance in @eieio{} is more than just combining different slots. -It is also important in method invocation. @ref{Methods}. - -If a method is called on an instance of @code{my-subclass}, and that -method only has an implementation on @code{my-baseclass}, or perhaps -@code{my-interface}, then the implementation for the baseclass is -called. - -If there is a method implementation for @code{my-subclass}, and -another in @code{my-baseclass}, the implementation for -@code{my-subclass} can call up to the superclass as well. - -@node Slot Options -@section Slot Options - -The @var{slot-list} argument to @code{defclass} is a list of elements -where each element defines one slot. Each slot is a list of the form - -@example - (SLOT-NAME :TAG1 ATTRIB-VALUE1 - :TAG2 ATTRIB-VALUE2 - :TAGN ATTRIB-VALUEN) -@end example - -@noindent -where @var{SLOT-NAME} is a symbol that will be used to refer to the -slot. @var{:TAG} is a symbol that describes a feature to be set -on the slot. @var{ATTRIB-VALUE} is a lisp expression that will be -used for @var{:TAG}. - -Valid tags are: - -@table @code -@item :initarg -A symbol that can be used in the argument list of the constructor to -specify a value for the new instance being created. - -A good symbol to use for initarg is one that starts with a colon @code{:}. - -The slot specified like this: -@example - (myslot :initarg :myslot) -@end example -could then be initialized to the number 1 like this: -@example - (myobject "name" :myslot 1) -@end example - -@xref{Making New Objects}. - -@item :initform -A expression used as the default value for this slot. - -If @code{:initform} is left out, that slot defaults to being unbound. -It is an error to reference an unbound slot, so if you need -slots to always be in a bound state, you should always use an -@code{:initform} specifier. - -Use @code{slot-boundp} to test if a slot is unbound -(@pxref{Predicates}). Use @code{slot-makeunbound} to set a slot to -being unbound after giving it a value (@pxref{Accessing Slots}). - -The value passed to initform is automatically quoted. Thus, -@example -:initform (1 2 3) -@end example -appears as the specified list in the default object. -A symbol that is a function like this: -@example -:initform + -@end example -will set the initial value as that symbol. - -After a class has been created with @code{defclass}, you can change -that default value with @code{oset-default}. @ref{Accessing Slots}. - -@item :type -An unquoted type specifier used to validate data set into this slot. -@xref{Type Predicates,,,cl,Common Lisp Extensions}. -Here are some examples: - @table @code - @item symbol - A symbol. - @item number - A number type - @item my-class-name - An object of your class type. - @item (or null symbol) - A symbol, or @code{nil}. - @end table - -@item :allocation -Either :class or :instance (defaults to :instance) used to -specify how data is stored. Slots stored per instance have unique -values for each object. Slots stored per class have shared values for -each object. If one object changes a :class allocated slot, then all -objects for that class gain the new value. - -@item :documentation -Documentation detailing the use of this slot. This documentation is -exposed when the user describes a class, and during customization of an -object. - -@item :accessor -Name of a generic function which can be used to fetch the value of this slot. -You can call this function later on your object and retrieve the value -of the slot. - -This options is in the CLOS spec, but is not fully compliant in @eieio{}. - -@item :writer -Name of a generic function which will write this slot. - -This options is in the CLOS spec, but is not fully compliant in @eieio{}. - -@item :reader -Name of a generic function which will read this slot. - -This options is in the CLOS spec, but is not fully compliant in @eieio{}. - -@item :custom -A custom :type specifier used when editing an object of this type. -See documentation for @code{defcustom} for details. This specifier is -equivalent to the :type spec of a @code{defcustom} call. - -This options is specific to Emacs, and is not in the CLOS spec. - -@item :label -When customizing an object, the value of :label will be used instead -of the slot name. This enables better descriptions of the data than -would usually be afforded. - -This options is specific to Emacs, and is not in the CLOS spec. - -@item :group -Similar to @code{defcustom}'s :group command, this organizes different -slots in an object into groups. When customizing an object, only the -slots belonging to a specific group need be worked with, simplifying the -size of the display. - -This options is specific to Emacs, and is not in the CLOS spec. - -@item :printer -This routine takes a symbol which is a function name. The function -should accept one argument. The argument is the value from the slot -to be printed. The function in @code{object-write} will write the -slot value out to a printable form on @code{standard-output}. - -The output format MUST be something that could in turn be interpreted -with @code{read} such that the object can be brought back in from the -output stream. Thus, if you wanted to output a symbol, you would need -to quote the symbol. If you wanted to run a function on load, you -can output the code to do the construction of the value. - -@item :protection -When using a slot referencing function such as @code{slot-value}, and -the value behind @var{slot} is private or protected, then the current -scope of operation must be within a method of the calling object. - -Valid values are: - -@table @code -@item :public -Access this slot from any scope. -@item :protected -Access this slot only from methods of the same class or a child class. -@item :private -Access this slot only from methods of the same class. -@end table - -This options is specific to Emacs, and is not in the CLOS spec. - -@end table - -@node Class Options -@section Class Options - -In the @var{options-and-doc} arguments to @code{defclass}, the -following class options may be specified: - -@table @code -@item :documentation -A documentation string for this class. - -If an Emacs-style documentation string is also provided, then this -option is ignored. An Emacs-style documentation string is not -prefixed by the @code{:documentation} tag, and appears after the list -of slots, and before the options. - -@item :allow-nil-initform -If this option is non-@code{nil}, and the @code{:initform} is @code{nil}, but -the @code{:type} is specifies something such as @code{string} then allow -this to pass. The default is to have this option be off. This is -implemented as an alternative to unbound slots. - -This options is specific to Emacs, and is not in the CLOS spec. - -@item :abstract -A class which is @code{:abstract} cannot be instantiated, and instead -is used to define an interface which subclasses should implement. - -This option is specific to Emacs, and is not in the CLOS spec. - -@item :custom-groups -This is a list of groups that can be customized within this class. This -slot is auto-generated when a class is created and need not be -specified. It can be retrieved with the @code{class-option} command, -however, to see what groups are available. - -This option is specific to Emacs, and is not in the CLOS spec. - -@item :method-invocation-order -This controls the order in which method resolution occurs for -@code{:primary} methods in cases of multiple inheritance. The order -affects which method is called first in a tree, and if -@code{call-next-method} is used, it controls the order in which the -stack of methods are run. - -Valid values are: - -@table @code -@item :breadth-first -Search for methods in the class hierarchy in breadth first order. -This is the default. -@item :depth-first -Search for methods in the class hierarchy in a depth first order. -@item :c3 -Searches for methods in a linearized way that most closely matches -what CLOS does when a monotonic class structure is defined. -@end table - -@xref{Method Invocation}, for more on method invocation order. - -@item :metaclass -Unsupported CLOS option. Enables the use of a different base class other -than @code{standard-class}. - -@item :default-initargs -Unsupported CLOS option. Specifies a list of initargs to be used when -creating new objects. As far as I can tell, this duplicates the -function of @code{:initform}. -@end table - -@xref{CLOS compatibility}, for more details on CLOS tags versus -@eieio{}-specific tags. - -@node Making New Objects -@chapter Making New Objects - -Suppose we have a simple class is defined, such as: - -@example -(defclass record () - ( ) "Doc String") -@end example - -@noindent -It is now possible to create objects of that class type. - -Calling @code{defclass} has defined two new functions. One is the -constructor @var{record}, and the other is the predicate, -@var{record}-p. - -@defun record object-name &rest slots - -This creates and returns a new object. This object is not assigned to -anything, and will be garbage collected if not saved. This object -will be given the string name @var{object-name}. There can be -multiple objects of the same name, but the name slot provides a handy -way to keep track of your objects. @var{slots} is just all the slots -you wish to preset. Any slot set as such @emph{will not} get its -default value, and any side effects from a slot's @code{:initform} -that may be a function will not occur. - -An example pair would appear simply as @code{:value 1}. Of course you -can do any valid Lispy thing you want with it, such as -@code{:value (if (boundp 'special-symbol) special-symbol nil)} - -Example of creating an object from a class: - -@example -(record "test" :value 3 :reference nil) -@end example - -@end defun - -To create an object from a class symbol, use @code{make-instance}. - -@defun make-instance class &rest initargs -@anchor{make-instance} -Make a new instance of @var{class} based on @var{initargs}. -@var{class} is a class symbol. For example: - -@example - (make-instance 'foo) -@end example - - @var{initargs} is a property list with keywords based on the @code{:initarg} -for each slot. For example: - -@example - (make-instance @code{'foo} @code{:slot1} value1 @code{:slotN} valueN) -@end example - -Compatibility note: - -If the first element of @var{initargs} is a string, it is used as the -name of the class. - -In @eieio{}, the class' constructor requires a name for use when printing. -@dfn{make-instance} in CLOS doesn't use names the way Emacs does, so the -class is used as the name slot instead when @var{initargs} doesn't start with -a string. -@end defun - -@node Accessing Slots -@chapter Accessing Slots - -There are several ways to access slot values in an object. The naming -and argument-order conventions are similar to those used for -referencing vectors (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference -Manual}). - -@defmac oset object slot value -This macro sets the value behind @var{slot} to @var{value} in -@var{object}. It returns @var{value}. -@end defmac - -@defmac oset-default class slot value -This macro sets the @code{:initform} for @var{slot} in @var{class} to -@var{value}. - -This allows the user to set both public and private defaults after the -class has been constructed, and provides a way to configure the -default behavior of packages built with classes (the same way -@code{setq-default} does for buffer-local variables). - -For example, if a user wanted all @code{data-objects} (@pxref{Building -Classes}) to inform a special object of his own devising when they -changed, this can be arranged by simply executing this bit of code: - -@example -(oset-default data-object reference (list my-special-object)) -@end example -@end defmac - -@defmac oref obj slot -@anchor{oref} -Retrieve the value stored in @var{obj} in the slot named by @var{slot}. -Slot is the name of the slot when created by @dfn{defclass} or the label -created by the @code{:initarg} tag. -@end defmac - -@defmac oref-default obj slot -@anchor{oref-default} -Gets the default value of @var{obj} (maybe a class) for @var{slot}. -The default value is the value installed in a class with the @code{:initform} -tag. @var{slot} can be the slot name, or the tag specified by the @code{:initarg} -tag in the @dfn{defclass} call. -@end defmac - -The following accessors are defined by CLOS to reference or modify -slot values, and use the previously mentioned set/ref routines. - -@defun slot-value object slot -@anchor{slot-value} -This function retrieves the value of @var{slot} from @var{object}. -Unlike @code{oref}, the symbol for @var{slot} must be quoted. -@end defun - -@defun set-slot-value object slot value -@anchor{set-slot-value} -This is not a CLOS function, but is meant to mirror @code{slot-value} if -you don't want to use the cl package's @code{setf} function. This -function sets the value of @var{slot} from @var{object}. Unlike -@code{oset}, the symbol for @var{slot} must be quoted. -@end defun - -@defun slot-makeunbound object slot -This function unbinds @var{slot} in @var{object}. Referencing an -unbound slot can signal an error. -@end defun - -@defun object-add-to-list object slot item &optional append -@anchor{object-add-to-list} -In OBJECT's @var{slot}, add @var{item} to the list of elements. -Optional argument @var{append} indicates we need to append to the list. -If @var{item} already exists in the list in @var{slot}, then it is not added. -Comparison is done with @dfn{equal} through the @dfn{member} function call. -If @var{slot} is unbound, bind it to the list containing @var{item}. -@end defun - -@defun object-remove-from-list object slot item -@anchor{object-remove-from-list} -In OBJECT's @var{slot}, remove occurrences of @var{item}. -Deletion is done with @dfn{delete}, which deletes by side effect -and comparisons are done with @dfn{equal}. -If @var{slot} is unbound, do nothing. -@end defun - -@defun with-slots spec-list object &rest body -@anchor{with-slots} -Bind @var{spec-list} lexically to slot values in @var{object}, and execute @var{body}. -This establishes a lexical environment for referring to the slots in -the instance named by the given slot-names as though they were -variables. Within such a context the value of the slot can be -specified by using its slot name, as if it were a lexically bound -variable. Both setf and setq can be used to set the value of the -slot. - -@var{spec-list} is of a form similar to @dfn{let}. For example: - -@example - ((VAR1 SLOT1) - SLOT2 - SLOTN - (VARN+1 SLOTN+1)) -@end example - -Where each @var{var} is the local variable given to the associated -@var{slot}. A slot specified without a variable name is given a -variable name of the same name as the slot. - -@example -(defclass myclass () (x :initarg 1)) -(setq mc (make-instance 'myclass)) -(with-slots (x) mc x) => 1 -(with-slots ((something x)) mc something) => 1 -@end example -@end defun - -@node Writing Methods -@chapter Writing Methods - -Writing a method in @eieio{} is similar to writing a function. The -differences are that there are some extra options and there can be -multiple definitions under the same function symbol. - -Where a method defines an implementation for a particular data type, a -@dfn{generic method} accepts any argument, but contains no code. It -is used to provide the dispatching to the defined methods. A generic -method has no body, and is merely a symbol upon which methods are -attached. It also provides the base documentation for what methods -with that name do. - -@menu -* Generics:: -* Methods:: -* Static Methods:: -@end menu - -@node Generics -@section Generics - -Each @eieio{} method has one corresponding generic. This generic -provides a function binding and the base documentation for the method -symbol (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp Reference -Manual}). - -@defmac defgeneric method arglist [doc-string] -This macro turns the (unquoted) symbol @var{method} into a function. -@var{arglist} is the default list of arguments to use (not implemented -yet). @var{doc-string} is the documentation used for this symbol. - -A generic function acts as a placeholder for methods. There is no -need to call @code{defgeneric} yourself, as @code{defmethod} will call -it if necessary. Currently the argument list is unused. - -@code{defgeneric} signals an error if you attempt to turn an existing -Emacs Lisp function into a generic function. - -You can also create a generic method with @code{defmethod} -(@pxref{Methods}). When a method is created and there is no generic -method in place with that name, then a new generic will be created, -and the new method will use it. -@end defmac - -In CLOS, a generic call also be used to provide an argument list and -dispatch precedence for all the arguments. In @eieio{}, dispatching -only occurs for the first argument, so the @var{arglist} is not used. - -@node Methods -@section Methods - -A method is a function that is executed if the first argument passed -to it matches the method's class. Different @eieio{} classes may -share the same method names. - -Methods are created with the @code{defmethod} macro, which is similar -to @code{defun}. - -@defmac defmethod method [:before | :primary | :after | :static ] arglist [doc-string] forms - -@var{method} is the name of the function to create. - -@code{:before} and @code{:after} specify execution order (i.e., when -this form is called). If neither of these symbols are present, the -default priority is used (before @code{:after} and after -@code{:before}); this default priority is represented in CLOS as -@code{:primary}. - -@b{Note:} The @code{:BEFORE}, @code{:PRIMARY}, @code{:AFTER}, and -@code{:STATIC} method tags were in all capital letters in previous -versions of @eieio{}. - -@var{arglist} is the list of arguments to this method. The first -argument in this list---and @emph{only} the first argument---may have -a type specifier (see the example below). If no type specifier is -supplied, the method applies to any object. - -@var{doc-string} is the documentation attached to the implementation. -All method doc-strings are incorporated into the generic method's -function documentation. - -@var{forms} is the body of the function. - -@end defmac - -@noindent -In the following example, we create a method @code{mymethod} for the -@code{classname} class: - -@example -(defmethod mymethod ((obj classname) secondarg) - "Doc string" ) -@end example - -@noindent -This method only executes if the @var{obj} argument passed to it is an -@eieio{} object of class @code{classname}. - -A method with no type specifier is a @dfn{default method}. If a given -class has no implementation, then the default method is called when -that method is used on a given object of that class. - -Only one default method per execution specifier (@code{:before}, -@code{:primary}, or @code{:after}) is allowed. If two -@code{defmethod}s appear with @var{arglist}s lacking a type specifier, -and having the same execution specifier, then the first implementation -is replaced. - -When a method is called on an object, but there is no method specified -for that object, but there is a method specified for object's parent -class, the parent class' method is called. If there is a method -defined for both, only the child's method is called. A child method -may call a parent's method using @code{call-next-method}, described -below. - -If multiple methods and default methods are defined for the same -method and class, they are executed in this order: - -@enumerate -@item method :before -@item default :before -@item method :primary -@item default :primary -@item method :after -@item default :after -@end enumerate - -If no methods exist, Emacs signals a @code{no-method-definition} -error. @xref{Signals}. - -@defun call-next-method &rest replacement-args -@anchor{call-next-method} - -This function calls the superclass method from a subclass method. -This is the ``next method'' specified in the current method list. - -If @var{replacement-args} is non-@code{nil}, then use them instead of -@code{eieio-generic-call-arglst}. At the top level, the generic -argument list is passed in. - -Use @code{next-method-p} to find out if there is a next method to -call. -@end defun - -@defun next-method-p -@anchor{next-method-p} -Non-@code{nil} if there is a next method. -Returns a list of lambda expressions which is the @code{next-method} -order. -@end defun - -At present, @eieio{} does not implement all the features of CLOS: - -@enumerate -@item -There is currently no @code{:around} tag. -@item -CLOS allows multiple sets of type-cast arguments, but @eieio{} only -allows the first argument to be cast. -@end enumerate - -@node Static Methods -@section Static Methods - -Static methods do not depend on an object instance, but instead -operate on an object's class. You can create a static method by using -the @code{:static} key with @code{defmethod}. - -Do not treat the first argument of a @code{:static} method as an -object unless you test it first. Use the functions -@code{oref-default} or @code{oset-default} which will work on a class, -or on the class of an object. - -A Class' @code{constructor} method is defined as a @code{:static} -method. - -@b{Note:} The @code{:static} keyword is unique to @eieio{}. - -@c TODO - Write some more about static methods here - -@node Method Invocation -@chapter Method Invocation - -When classes are defined, you can specify the -@code{:method-invocation-order}. This is a feature specific to EIEIO. - -This controls the order in which method resolution occurs for -@code{:primary} methods in cases of multiple inheritance. The order -affects which method is called first in a tree, and if -@code{call-next-method} is used, it controls the order in which the -stack of methods are run. - -The original EIEIO order turned out to be broken for multiple -inheritance, but some programs depended on it. As such this option -was added when the default invocation order was fixed to something -that made more sense in that case. - -Valid values are: - -@table @code -@item :breadth-first -Search for methods in the class hierarchy in breadth first order. -This is the default. -@item :depth-first -Search for methods in the class hierarchy in a depth first order. -@item :c3 -Searches for methods in a linearized way that most closely matches -what CLOS does when a monotonic class structure is defined. - -This is derived from the Dylan language documents by -Kim Barrett et al.: A Monotonic Superclass Linearization for Dylan -Retrieved from: http://192.220.96.201/dylan/linearization-oopsla96.html -@end table - -@node Predicates -@chapter Predicates and Utilities - -Now that we know how to create classes, access slots, and define -methods, it might be useful to verify that everything is doing ok. To -help with this a plethora of predicates have been created. - -@defun find-class symbol &optional errorp -@anchor{find-class} -Return the class that @var{symbol} represents. -If there is no class, @code{nil} is returned if @var{errorp} is @code{nil}. -If @var{errorp} is non-@code{nil}, @code{wrong-argument-type} is signaled. -@end defun - -@defun class-p class -@anchor{class-p} -Return @code{t} if @var{class} is a valid class vector. -@var{class} is a symbol. -@end defun - -@defun slot-exists-p object-or-class slot -@anchor{slot-exists-p} -Non-@code{nil} if @var{object-or-class} has @var{slot}. -@end defun - -@defun slot-boundp object slot -@anchor{slot-boundp} -Non-@code{nil} if OBJECT's @var{slot} is bound. -Setting a slot's value makes it bound. Calling @dfn{slot-makeunbound} will -make a slot unbound. -@var{object} can be an instance or a class. -@end defun - -@defun eieio-class-name class -Return a string of the form @samp{#} which should look -similar to other Lisp objects like buffers and processes. Printing a -class results only in a symbol. -@end defun - -@defun class-option class option -Return the value in @var{CLASS} of a given @var{OPTION}. -For example: - -@example -(class-option eieio-default-superclass :documentation) -@end example - -Will fetch the documentation string for @code{eieio-default-superclass}. -@end defun - -@defun class-constructor class -Return a symbol used as a constructor for @var{class}. The -constructor is a function used to create new instances of -@var{CLASS}. This function provides a way to make an object of a class -without knowing what it is. This is not a part of CLOS. -@end defun - -@defun eieio-object-name obj -Return a string of the form @samp{#} for @var{obj}. -This should look like Lisp symbols from other parts of Emacs such as -buffers and processes, and is shorter and cleaner than printing the -object's vector. It is more useful to use @code{object-print} to get -and object's print form, as this allows the object to add extra display -information into the symbol. -@end defun - -@defun eieio-object-class obj -Returns the class symbol from @var{obj}. -@end defun - -@defun eieio--object-class obj -Same as @code{eieio-object-class} except this is a macro, and no -type-checking is performed. -@end defun - -@defun eieio-object-class-name obj -Returns the symbol of @var{obj}'s class. -@end defun - -@defun eieio-class-parents class -Returns the direct parents class of @var{class}. Returns @code{nil} if -it is a superclass. -@end defun - -@defun eieio-class-parents-fast class -Just like @code{eieio-class-parents} except it is a macro and no type checking -is performed. -@end defun - -@defun eieio-class-parent class -Deprecated function which returns the first parent of @var{class}. -@end defun - -@defun eieio-class-children class -Return the list of classes inheriting from @var{class}. -@end defun - -@defun eieio-class-children-fast class -Just like @code{eieio-class-children}, but with no checks. -@end defun - -@defun same-class-p obj class -Returns @code{t} if @var{obj}'s class is the same as @var{class}. -@end defun - -@defun same-class-fast-p obj class -Same as @code{same-class-p} except this is a macro and no type checking -is performed. -@end defun - -@defun object-of-class-p obj class -Returns @code{t} if @var{obj} inherits anything from @var{class}. This -is different from @code{same-class-p} because it checks for inheritance. -@end defun - -@defun child-of-class-p child class -Returns @code{t} if @var{child} is a subclass of @var{class}. -@end defun - -@defun generic-p method-symbol -Returns @code{t} if @code{method-symbol} is a generic function, as -opposed to a regular Emacs Lisp function. -@end defun - -@node Association Lists -@chapter Association Lists - -Lisp offers the concept of association lists, with primitives such as -@code{assoc} used to access them. The following functions can be used -to manage association lists of @eieio{} objects: - -@defun object-assoc key slot list -@anchor{object-assoc} -Return an object if @var{key} is @dfn{equal} to SLOT's value of an object in @var{list}. -@var{list} is a list of objects whose slots are searched. -Objects in @var{list} do not need to have a slot named @var{slot}, nor does -@var{slot} need to be bound. If these errors occur, those objects will -be ignored. -@end defun - - -@defun object-assoc-list slot list -Return an association list generated by extracting @var{slot} from all -objects in @var{list}. For each element of @var{list} the @code{car} is -the value of @var{slot}, and the @code{cdr} is the object it was -extracted from. This is useful for generating completion tables. -@end defun - -@defun eieio-build-class-alist &optional base-class -Returns an alist of all currently defined classes. This alist is -suitable for completion lists used by interactive functions to select a -class. The optional argument @var{base-class} allows the programmer to -select only a subset of classes which includes @var{base-class} and -all its subclasses. -@end defun - -@node Customizing -@chapter Customizing Objects - -@eieio{} supports the Custom facility through two new widget types. -If a variable is declared as type @code{object}, then full editing of -slots via the widgets is made possible. This should be used -carefully, however, because modified objects are cloned, so if there -are other references to these objects, they will no longer be linked -together. - -If you want in place editing of objects, use the following methods: - -@defun eieio-customize-object object -Create a custom buffer and insert a widget for editing @var{object}. At -the end, an @code{Apply} and @code{Reset} button are available. This -will edit the object "in place" so references to it are also changed. -There is no effort to prevent multiple edits of a singular object, so -care must be taken by the user of this function. -@end defun - -@defun eieio-custom-widget-insert object flags -This method inserts an edit object into the current buffer in place. -It is implemented as @code{(widget-create 'object-edit :value object)}. -This method is provided as a locale for adding tracking, or -specializing the widget insert procedure for any object. -@end defun - -To define a slot with an object in it, use the @code{object} tag. This -widget type will be automatically converted to @code{object-edit} if you -do in place editing of you object. - -If you want to have additional actions taken when a user clicks on the -@code{Apply} button, then overload the method @code{eieio-done-customizing}. -This method does nothing by default, but that may change in the future. -This would be the best way to make your objects persistent when using -in-place editing. - -@section Widget extension - -When widgets are being created, one new widget extension has been added, -called the @code{:slotofchoices}. When this occurs in a widget -definition, all elements after it are removed, and the slot is specifies -is queried and converted into a series of constants. - -@example -(choice (const :tag "None" nil) - :slotofchoices morestuff) -@end example - -and if the slot @code{morestuff} contains @code{(sym1 sym2 sym3)}, the -above example is converted into: - -@example -(choice (const :tag "None" nil) - (const sym1) - (const sym2) - (const sym3)) -@end example - -This is useful when a given item needs to be selected from a list of -items defined in this second slot. - -@node Introspection -@chapter Introspection - -Introspection permits a programmer to peek at the contents of a class -without any previous knowledge of that class. While @eieio{} implements -objects on top of vectors, and thus everything is technically visible, -some functions have been provided. None of these functions are a part -of CLOS. - -@defun object-slots obj -Return the list of public slots for @var{obj}. -@end defun - -@defun class-slot-initarg class slot -For the given @var{class} return the :initarg associated with -@var{slot}. Not all slots have initargs, so the return value can be -@code{nil}. -@end defun - -@node Base Classes -@chapter Base Classes - -All defined classes, if created with no specified parent class, -inherit from a special class called @code{eieio-default-superclass}. -@xref{Default Superclass}. - -Often, it is more convenient to inherit from one of the other base -classes provided by @eieio{}, which have useful pre-defined -properties. (Since @eieio{} supports multiple inheritance, you can -even inherit from more than one of these classes at once.) - -@menu -* eieio-instance-inheritor:: Enable value inheritance between instances. -* eieio-instance-tracker:: Enable self tracking instances. -* eieio-singleton:: Only one instance of a given class. -* eieio-persistent:: Enable persistence for a class. -* eieio-named:: Use the object name as a :name slot. -* eieio-speedbar:: Enable speedbar support in your objects. -@end menu - -@node eieio-instance-inheritor -@section @code{eieio-instance-inheritor} - -This class is defined in the package @file{eieio-base}. - -Instance inheritance is a mechanism whereby the value of a slot in -object instance can reference the parent instance. If the parent's slot -value is changed, then the child instance is also changed. If the -child's slot is set, then the parent's slot is not modified. - -@deftp {Class} eieio-instance-inheritor parent-instance -A class whose instances are enabled with instance inheritance. -The @var{parent-instance} slot indicates the instance which is -considered the parent of the current instance. Default is @code{nil}. -@end deftp - -@cindex clone -To use this class, inherit from it with your own class. -To make a new instance that inherits from and existing instance of your -class, use the @code{clone} method with additional parameters -to specify local values. - -@cindex slot-unbound -The @code{eieio-instance-inheritor} class works by causing cloned -objects to have all slots unbound. This class' @code{slot-unbound} -method will cause references to unbound slots to be redirected to the -parent instance. If the parent slot is also unbound, then -@code{slot-unbound} will signal an error named @code{slot-unbound}. - -@node eieio-instance-tracker -@section @code{eieio-instance-tracker} - -This class is defined in the package @file{eieio-base}. - -Sometimes it is useful to keep a master list of all instances of a given -class. The class @code{eieio-instance-tracker} performs this task. - -@deftp {Class} eieio-instance-tracker tracker-symbol -Enable instance tracking for this class. -The slot @var{tracker-symbol} should be initialized in inheritors of -this class to a symbol created with @code{defvar}. This symbol will -serve as the variable used as a master list of all objects of the given -class. -@end deftp - -@defmethod eieio-instance-tracker initialize-instance obj slot -This method is defined as an @code{:after} method. -It adds new instances to the master list. Do not overload this method -unless you use @code{call-next-method.} -@end defmethod - -@defmethod eieio-instance-tracker delete-instance obj -Remove @var{obj} from the master list of instances of this class. -This may let the garbage collector nab this instance. -@end defmethod - -@deffn eieio-instance-tracker-find key slot list-symbol -This convenience function lets you find instances. @var{key} is the -value to search for. @var{slot} is the slot to compare @var{KEY} -against. The function @code{equal} is used for comparison. -The parameter @var{list-symbol} is the variable symbol which contains the -list of objects to be searched. -@end deffn - -@node eieio-singleton -@section @code{eieio-singleton} - -This class is defined in the package @file{eieio-base}. - -@deftp {Class} eieio-singleton -Inheriting from the singleton class will guarantee that there will -only ever be one instance of this class. Multiple calls to -@code{make-instance} will always return the same object. -@end deftp - -@node eieio-persistent -@section @code{eieio-persistent} - -This class is defined in the package @file{eieio-base}. - -If you want an object, or set of objects to be persistent, meaning the -slot values are important to keep saved between sessions, then you will -want your top level object to inherit from @code{eieio-persistent}. - -To make sure your persistent object can be moved, make sure all file -names stored to disk are made relative with -@code{eieio-persistent-path-relative}. - -@deftp {Class} eieio-persistent file file-header-line -Enables persistence for instances of this class. -Slot @var{file} with initarg @code{:file} is the file name in which this -object will be saved. -Class allocated slot @var{file-header-line} is used with method -@code{object-write} as a header comment. -@end deftp - -All objects can write themselves to a file, but persistent objects have -several additional methods that aid in maintaining them. - -@defmethod eieio-persistent eieio-persistent-save obj &optional file -Write the object @var{obj} to its file. -If optional argument @var{file} is specified, use that file name -instead. -@end defmethod - -@defmethod eieio-persistent eieio-persistent-path-relative obj file -Return a file name derived from @var{file} which is relative to the -stored location of @var{OBJ}. This method should be used to convert -file names so that they are relative to the save file, making any system -of files movable from one location to another. -@end defmethod - -@defmethod eieio-persistent object-write obj &optional comment -Like @code{object-write} for @code{standard-object}, but will derive -a header line comment from the class allocated slot if one is not -provided. -@end defmethod - -@defun eieio-persistent-read filename &optional class allow-subclass -Read a persistent object from @var{filename}, and return it. -Signal an error if the object in @var{FILENAME} is not a constructor -for @var{CLASS}. Optional @var{allow-subclass} says that it is ok for -@code{eieio-persistent-read} to load in subclasses of class instead of -being pedantic. -@end defun - -@node eieio-named -@section @code{eieio-named} - -This class is defined in the package @file{eieio-base}. - -@deftp {Class} eieio-named -Object with a name. -Name storage already occurs in an object. This object provides get/set -access to it. -@end deftp - -@node eieio-speedbar -@section @code{eieio-speedbar} - -This class is in package @file{eieio-speedbar}. - -If a series of class instances map to a tree structure, it is possible -to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}. -Inheriting from these classes will enable a speedbar major display mode -with a minimum of effort. - -@deftp {Class} eieio-speedbar buttontype buttonface -Enables base speedbar display for a class. -@cindex speedbar-make-tag-line -The slot @var{buttontype} is any of the symbols allowed by the -function @code{speedbar-make-tag-line} for the @var{exp-button-type} -argument @xref{Extending,,,speedbar}. -The slot @var{buttonface} is the face to use for the text of the string -displayed in speedbar. -The slots @var{buttontype} and @var{buttonface} are class allocated -slots, and do not take up space in your instances. -@end deftp - -@deftp {Class} eieio-speedbar-directory-button buttontype buttonface -This class inherits from @code{eieio-speedbar} and initializes -@var{buttontype} and @var{buttonface} to appear as directory level lines. -@end deftp - -@deftp {Class} eieio-speedbar-file-button buttontype buttonface -This class inherits from @code{eieio-speedbar} and initializes -@var{buttontype} and @var{buttonface} to appear as file level lines. -@end deftp - -To use these classes, inherit from one of them in you class. You can -use multiple inheritance with them safely. To customize your class for -speedbar display, override the default values for @var{buttontype} and -@var{buttonface} to get the desired effects. - -Useful methods to define for your new class include: - -@defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth -Return a string representing a directory associated with an instance -of @var{obj}. @var{depth} can be used to index how many levels of -indentation have been opened by the user where @var{obj} is shown. -@end defmethod - - -@defmethod eieio-speedbar eieio-speedbar-description obj -Return a string description of @var{OBJ}. -This is shown in the minibuffer or tooltip when the mouse hovers over -this instance in speedbar. -@end defmethod - -@defmethod eieio-speedbar eieio-speedbar-child-description obj -Return a string representing a description of a child node of @var{obj} -when that child is not an object. It is often useful to just use -item info helper functions such as @code{speedbar-item-info-file-helper}. -@end defmethod - -@defmethod eieio-speedbar eieio-speedbar-object-buttonname obj -Return a string which is the text displayed in speedbar for @var{obj}. -@end defmethod - -@defmethod eieio-speedbar eieio-speedbar-object-children obj -Return a list of children of @var{obj}. -@end defmethod - -@defmethod eieio-speedbar eieio-speedbar-child-make-tag-lines obj depth -This method inserts a list of speedbar tag lines for @var{obj} to -represent its children. Implement this method for your class -if your children are not objects themselves. You still need to -implement @code{eieio-speedbar-object-children}. - -In this method, use techniques specified in the Speedbar manual. -@xref{Extending,,,speedbar}. -@end defmethod - -Some other functions you will need to learn to use are: - -@deffn eieio-speedbar-create make-map key-map menu name toplevelfn -Register your object display mode with speedbar. -@var{make-map} is a function which initialized you keymap. -@var{key-map} is a symbol you keymap is installed into. -@var{menu} is an easy menu vector representing menu items specific to your -object display. -@var{name} is a short string to use as a name identifying you mode. -@var{toplevelfn} is a function called which must return a list of -objects representing those in the instance system you wish to browse in -speedbar. - -Read the Extending chapter in the speedbar manual for more information -on how speedbar modes work -@xref{Extending,,,speedbar}. -@end deffn - -@node Browsing -@chapter Browsing class trees - -The command @kbd{M-x eieio-browse} displays a buffer listing all the -currently loaded classes in Emacs. The classes are listed in an -indented tree structure, starting from @code{eieio-default-superclass} -(@pxref{Default Superclass}). - -With a prefix argument, this command prompts for a class name; it then -lists only that class and its subclasses. - -Here is a sample tree from our current example: - -@example -eieio-default-superclass - +--data-object - +--data-object-symbol -@end example - -Note: new classes are consed into the inheritance lists, so the tree -comes out upside-down. - -@node Class Values -@chapter Class Values - -You can use the normal @code{describe-function} command to retrieve -information about a class. Running it on constructors will show a -full description of the generated class. If you call it on a generic -function, all implementations of that generic function will be listed, -together with links through which you can directly jump to the source. - -@node Default Superclass -@chapter Default Superclass - -All defined classes, if created with no specified parent class, will -inherit from a special class stored in -@code{eieio-default-superclass}. This superclass is quite simple, but -with it, certain default methods or attributes can be added to all -objects. In CLOS, this would be named @code{STANDARD-CLASS}, and that -symbol is an alias to @code{eieio-default-superclass}. - -Currently, the default superclass is defined as follows: - -@example -(defclass eieio-default-superclass nil - nil - "Default parent class for classes with no specified parent class. -Its slots are automatically adopted by classes with no specified -parents. This class is not stored in the `parent' slot of a class vector." - :abstract t) -@end example - -The default superclass implements several methods providing a default -behavior for all objects created by @eieio{}. - -@menu -* Initialization:: How objects are initialized -* Basic Methods:: Clone, print, and write -* Signal Handling:: Methods for managing signals. -@end menu - -@node Initialization -@section Initialization - -When creating an object of any type, you can use its constructor, or -@code{make-instance}. This, in turns calls the method -@code{initialize-instance}, which then calls the method -@code{shared-initialize}. - -These methods are all implemented on the default superclass so you do -not need to write them yourself, unless you need to override one of -their behaviors. - -Users should not need to call @code{initialize-instance} or -@code{shared-initialize}, as these are used by @code{make-instance} to -initialize the object. They are instead provided so that users can -augment these behaviors. - -@defun initialize-instance obj &rest slots -Initialize @var{obj}. Sets slots of @var{obj} with @var{slots} which -is a list of name/value pairs. These are actually just passed to -@code{shared-initialize}. -@end defun - -@defun shared-initialize obj &rest slots -Sets slots of @var{obj} with @var{slots} which is a list of name/value -pairs. - -This is called from the default @code{constructor}. -@end defun - -@node Basic Methods -@section Basic Methods - -Additional useful methods defined on the base subclass are: - -@defun clone obj &rest params -@anchor{clone} -Make a copy of @var{obj}, and then apply @var{params}. -@var{params} is a parameter list of the same form as @var{initialize-instance} -which are applied to change the object. When overloading @dfn{clone}, be -sure to call @dfn{call-next-method} first and modify the returned object. -@end defun - -@defun object-print this &rest strings -@anchor{object-print} -Pretty printer for object @var{this}. Call function @dfn{eieio-object-name} with @var{strings}. -The default method for printing object @var{this} is to use the -function @dfn{eieio-object-name}. - -It is sometimes useful to put a summary of the object into the -default # string when using eieio browsing tools. - -Implement this function and specify @var{strings} in a call to -@dfn{call-next-method} to provide additional summary information. -When passing in extra strings from child classes, always remember -to prepend a space. - -@example -(defclass data-object () - (value) - "Object containing one data slot.") - -(defmethod object-print ((this data-object) &optional strings) - "Return a string with a summary of the data object as part of the name." - (apply 'call-next-method this - (cons (format " value: %s" (render this)) strings))) -@end example - -Here is what some output could look like: -@example -(object-print test-object) - => # -@end example -@end defun - -@defun object-write obj &optional comment -Write @var{obj} onto a stream in a readable fashion. The resulting -output will be Lisp code which can be used with @code{read} and -@code{eval} to recover the object. Only slots with @code{:initarg}s -are written to the stream. -@end defun - -@node Signal Handling -@section Signal Handling - -The default superclass defines methods for managing error conditions. -These methods all throw a signal for a particular error condition. - -By implementing one of these methods for a class, you can change the -behavior that occurs during one of these error cases, or even ignore -the error by providing some behavior. - -@defun slot-missing object slot-name operation &optional new-value -@anchor{slot-missing} -Method invoked when an attempt to access a slot in @var{object} fails. -@var{slot-name} is the name of the failed slot, @var{operation} is the type of access -that was requested, and optional @var{new-value} is the value that was desired -to be set. - -This method is called from @code{oref}, @code{oset}, and other functions which -directly reference slots in EIEIO objects. - -The default method signals an error of type @code{invalid-slot-name}. -@xref{Signals}. - -You may override this behavior, but it is not expected to return in the -current implementation. - -This function takes arguments in a different order than in CLOS. -@end defun - -@defun slot-unbound object class slot-name fn -@anchor{slot-unbound} -Slot unbound is invoked during an attempt to reference an unbound slot. -@var{object} is the instance of the object being reference. @var{class} is the -class of @var{object}, and @var{slot-name} is the offending slot. This function -throws the signal @code{unbound-slot}. You can overload this function and -return the value to use in place of the unbound value. -Argument @var{fn} is the function signaling this error. -Use @dfn{slot-boundp} to determine if a slot is bound or not. - -In @var{clos}, the argument list is (@var{class} @var{object} @var{slot-name}), but -@var{eieio} can only dispatch on the first argument, so the first two are swapped. -@end defun - -@defun no-applicable-method object method &rest args -@anchor{no-applicable-method} -Called if there are no implementations for @var{object} in @var{method}. -@var{object} is the object which has no method implementation. -@var{args} are the arguments that were passed to @var{method}. - -Implement this for a class to block this signal. The return -value becomes the return value of the original method call. -@end defun - -@defun no-next-method object &rest args -@anchor{no-next-method} -Called from @dfn{call-next-method} when no additional methods are available. -@var{object} is othe object being called on @dfn{call-next-method}. -@var{args} are the arguments it is called by. -This method signals @dfn{no-next-method} by default. Override this -method to not throw an error, and its return value becomes the -return value of @dfn{call-next-method}. -@end defun - -@node Signals -@chapter Signals - -There are new condition names (signals) that can be caught when using -@eieio{}. - -@deffn Signal invalid-slot-name obj-or-class slot -This signal is called when an attempt to reference a slot in an -@var{obj-or-class} is made, and the @var{slot} is not defined for -it. -@end deffn - -@deffn Signal no-method-definition method arguments -This signal is called when @var{method} is called, with @var{arguments} -and nothing is resolved. This occurs when @var{method} has been -defined, but the arguments make it impossible for @eieio{} to determine -which method body to run. - -To prevent this signal from occurring in your class, implement the -method @code{no-applicable-method} for your class. This method is -called when to throw this signal, so implementing this for your class -allows you block the signal, and perform some work. -@end deffn - -@deffn Signal no-next-method class arguments -This signal is called if the function @code{call-next-method} is called -and there is no next method to be called. - -Overload the method @code{no-next-method} to protect against this signal. -@end deffn - -@deffn Signal invalid-slot-type slot spec value -This signal is called when an attempt to set @var{slot} is made, and -@var{value} doesn't match the specified type @var{spec}. - -In @eieio{}, this is also used if a slot specifier has an invalid value -during a @code{defclass}. -@end deffn - -@deffn Signal unbound-slot object class slot -This signal is called when an attempt to reference @var{slot} in -@var{object} is made, and that instance is currently unbound. -@end deffn - -@node Naming Conventions -@chapter Naming Conventions - -@xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference -Manual}, for a description of Emacs Lisp programming conventions. -These conventions help ensure that Emacs packages work nicely one -another, so an @eieio{}-based program should follow them. Here are -some conventions that apply specifically to @eieio{}-based programs: - -@itemize - -@item Come up with a package prefix that is relatively short. Prefix -all classes, and methods with your prefix. This is a standard -convention for functions and variables in Emacs. - -@item Do not prefix method names with the class name. All methods in -@eieio{} are ``virtual'', and are dynamically dispatched. Anyone can -override your methods at any time. Your methods should be prefixed -with your package name. - -@item Do not prefix slots in your class. The slots are always locally -scoped to your class, and need no prefixing. - -@item If your library inherits from other libraries of classes, you -must ``require'' that library with the @code{require} command. - -@end itemize - -@node CLOS compatibility -@chapter CLOS compatibility - -Currently, the following functions should behave almost as expected from -CLOS. - -@table @code - -@item defclass -All slot keywords are available but not all work correctly. -Slot keyword differences are: - -@table @asis - -@item :reader, and :writer tags -Create methods that signal errors instead of creating an unqualified -method. You can still create new ones to do its business. - -@item :accessor -This should create an unqualified method to access a slot, but -instead pre-builds a method that gets the slot's value. - -@item :type -Specifier uses the @code{typep} function from the @file{cl} -package. @xref{Type Predicates,,,cl,Common Lisp Extensions}. -It therefore has the same issues as that package. Extensions include -the ability to provide object names. -@end table - -defclass also supports class options, but does not currently use values -of @code{:metaclass}, and @code{:default-initargs}. - -@item make-instance -Make instance works as expected, however it just uses the @eieio{} instance -creator automatically generated when a new class is created. -@xref{Making New Objects}. - -@item defgeneric -Creates the desired symbol, and accepts all of the expected arguments -except @code{:around}. - -@item defmethod -Calls defgeneric, and accepts most of the expected arguments. Only -the first argument to the created method may have a type specifier. -To type cast against a class, the class must exist before defmethod is -called. In addition, the @code{:around} tag is not supported. - -@item call-next-method -Inside a method, calls the next available method up the inheritance tree -for the given object. This is different than that found in CLOS because -in @eieio{} this function accepts replacement arguments. This permits -subclasses to modify arguments as they are passed up the tree. If no -arguments are given, the expected CLOS behavior is used. -@item setf -If the common-lisp subsystem is loaded, the setf parameters are also -loaded so the form @code{(setf (slot-value object slot) t)} should -work. -@end table - -CLOS supports the @code{describe} command, but @eieio{} provides -support for using the standard @code{describe-function} command on a -constructor or generic function. - -When creating a new class (@pxref{Building Classes}) there are several -new keywords supported by @eieio{}. - -In @eieio{} tags are in lower case, not mixed case. - -@node Wish List -@chapter Wish List - -@eieio{} is an incomplete implementation of CLOS@. Finding ways to -improve the compatibility would help make CLOS style programs run -better in Emacs. - -Some important compatibility features that would be good to add are: - -@enumerate -@item -Support for metaclasses and EQL specialization. -@item -@code{:around} method key. -@item -Method dispatch for built-in types. -@item -Method dispatch for multiple argument typing. -@item -Improve integration with the @file{cl} package. -@end enumerate - -There are also improvements to be made to allow @eieio{} to operate -better in the Emacs environment. - -@enumerate -@item -Allow subclassing of Emacs built-in types, such as faces, markers, and -buffers. -@item -Allow method overloading of method-like functions in Emacs. -@end enumerate - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Function Index - -@printindex fn - -@contents -@bye diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi deleted file mode 100644 index bc054ac76b0..00000000000 --- a/doc/misc/emacs-gnutls.texi +++ /dev/null @@ -1,215 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@set VERSION 0.3 - -@setfilename ../../info/emacs-gnutls -@settitle Emacs GnuTLS Integration @value{VERSION} -@documentencoding UTF-8 - -@copying -This file describes the Emacs GnuTLS integration. - -Copyright @copyright{} 2012--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* Emacs GnuTLS: (emacs-gnutls). The Emacs GnuTLS integration. -@end direntry - -@titlepage -@title Emacs GnuTLS Integration -@author by Ted Zlatanov -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs GnuTLS -This manual describes the Emacs GnuTLS integration. - -GnuTLS is a library that establishes encrypted @acronym{SSL} or -@acronym{TLS} connections. Emacs supports it through the -@file{gnutls.c} and @file{gnutls.h} C files and the @file{gnutls.el} -Emacs Lisp library. - -@insertcopying - -@menu -* Overview:: Overview of the GnuTLS integration. -* Help For Users:: -* Help For Developers:: -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -* Variable Index:: -@end menu -@end ifnottex - -@node Overview -@chapter Overview - -The GnuTLS library is an optional add-on for Emacs. Through it, any -Emacs Lisp program can establish encrypted network connections that -use @dfn{Secure Socket Layer} (@acronym{SSL}) and @dfn{Transport Layer -Security} (@acronym{TLS}) protocols. The process of using -@acronym{SSL} and @acronym{TLS} in establishing connections is as -automated and transparent as possible. - -The user has only a few customization options currently: the log -level, priority string, trustfile list, and the minimum number of bits -to be used in Diffie-Hellman key exchange. Rumors that every Emacs -library requires at least 83 customizable variables are thus proven -false. - -@node Help For Users -@chapter Help For Users - -From the user's perspective, there's nothing to the GnuTLS -integration. It Just Works for any Emacs Lisp code that uses -@code{open-protocol-stream} or @code{open-network-stream} -(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference -Manual}). The two functions are equivalent, the first one being an -alias of the second. - -There's one way to find out if GnuTLS is available, by calling -@code{gnutls-available-p}. This is a little bit trickier on the W32 -(Windows) platform, but if you have the GnuTLS DLLs (available from -@url{http://sourceforge.net/projects/ezwinports/files/} thanks to Eli -Zaretskii) in the same directory as Emacs, you should be OK. - -@defun gnutls-available-p -This function returns @code{t} if GnuTLS is available in this instance of Emacs. -@end defun - -Oh, but sometimes things go wrong. Budgets aren't balanced, -television ads lie, and even TLS and SSL connections can fail to work -properly. Well, there's something to be done in the last case. - -@defvar gnutls-log-level -The @code{gnutls-log-level} variable sets the log level. 1 is -verbose. 2 is very verbose. 5 is crazy. Crazy! Set it to 1 or 2 -and look in the @file{*Messages*} buffer for the debugging -information. -@end defvar - -@defvar gnutls-algorithm-priority -The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority -string. This is global, not per host name (although -@code{gnutls-negotiate} supports a priority string per connection so -it could be done if needed). The priority string syntax is in the -@uref{http://www.gnu.org/software/gnutls/documentation.html, GnuTLS -documentation}. -@end defvar - -@defvar gnutls-trustfiles -The @code{gnutls-trustfiles} variable is a list of trustfiles -(certificates for the issuing authorities). This is global, not per -host name (although @code{gnutls-negotiate} supports a trustfile per -connection so it could be done if needed). The trustfiles can be in -PEM or DER format and examples can be found in most Unix -distributions. By default four locations are tried in this order: -@file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu, Gentoo -and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for Fedora -and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse; -@file{/usr/ssl/certs/ca-bundle.crt} for Cygwin. You can easily -customize @code{gnutls-trustfiles} to be something else, but let us -know if you do, so we can make the change to benefit the other users -of that platform. -@end defvar - -@defvar gnutls-verify-error -The @code{gnutls-verify-error} variable allows you to verify SSL/TLS -server certificates for all connections or by host name. It defaults -to @code{nil} for now but will likely be changed to @code{t} later, -meaning that all certificates will be verified. - -There are two checks available currently, that the certificate has -been issued by a trusted authority as defined by -@code{gnutls-trustfiles}, and that the hostname matches the -certificate. @code{t} enables both checks, but you can enable them -individually as well with @code{:trustfiles} and @code{:hostname} -instead. - -Because of the low-level interactions with the GnuTLS library, there -is no way currently to ask if a certificate can be accepted. You have -to look in the @file{*Messages*} buffer. -@end defvar - -@defvar gnutls-min-prime-bits -The @code{gnutls-min-prime-bits} variable is a pretty exotic -customization for cases where you want to refuse handshakes with keys -under a specific size. If you don't know for sure that you need it, -you don't. Leave it @code{nil}. -@end defvar - -@node Help For Developers -@chapter Help For Developers - -The GnuTLS library is detected automatically at compile time. You -should see that it's enabled in the @code{configure} output. If not, -follow the standard procedure for finding out why a system library is -not picked up by the Emacs compilation. On the W32 (Windows) -platform, installing the DLLs with a recent build should be enough. - -Just use @code{open-protocol-stream} or @code{open-network-stream} -(the two are equivalent, the first one being an alias to the second). -You should not have to use the @file{gnutls.el} functions directly. -But you can test them with @code{open-gnutls-stream}. - -@defun open-gnutls-stream name buffer host service -This function creates a buffer connected to a specific @var{host} and -@var{service} (port number or service name). The parameters and their -syntax are the same as those given to @code{open-network-stream} -(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference -Manual}). The connection process is called @var{name} (made unique if -necessary). This function returns the connection process. - -@lisp -;; open a HTTPS connection -(open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https") - -;; open a IMAPS connection -(open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps") -@end lisp - -@end defun - -The function @code{gnutls-negotiate} is not generally useful and it -may change as needed, so please see @file{gnutls.el} for the details. - -@defun gnutls-negotiate spec -Please see @file{gnutls.el} for the @var{spec} details and for usage, -but do not rely on this function's interface if possible. -@end defun - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye - -@c End: diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi deleted file mode 100644 index 19cdd43882e..00000000000 --- a/doc/misc/emacs-mime.texi +++ /dev/null @@ -1,1893 +0,0 @@ -\input texinfo - -@include gnus-overrides.texi - -@setfilename ../../info/emacs-mime -@settitle Emacs MIME Manual -@synindex fn cp -@synindex vr cp -@synindex pg cp - -@copying -This file documents the Emacs MIME interface functionality. - -Copyright @copyright{} 1998--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@c Node ``Interface Functions'' uses non-ASCII characters -@documentencoding UTF-8 - -@dircategory Emacs lisp libraries -@direntry -* Emacs MIME: (emacs-mime). Emacs MIME de/composition library. -@end direntry -@iftex -@finalout -@end iftex -@setchapternewpage odd - -@titlepage -@ifset WEBHACKDEVEL -@title Emacs MIME Manual (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Emacs MIME Manual -@end ifclear - -@author by Lars Magne Ingebrigtsen -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top Emacs MIME - -This manual documents the libraries used to compose and display -@acronym{MIME} messages. - -This manual is directed at users who want to modify the behavior of -the @acronym{MIME} encoding/decoding process or want a more detailed -picture of how the Emacs @acronym{MIME} library works, and people who want -to write functions and commands that manipulate @acronym{MIME} elements. - -@acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}. -This standard is documented in a number of RFCs; mainly RFC2045 (Format -of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message -Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration -Procedures), RFC2049 (Conformance Criteria and Examples). It is highly -recommended that anyone who intends writing @acronym{MIME}-compliant software -read at least RFC2045 and RFC2047. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Decoding and Viewing:: A framework for decoding and viewing. -* Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts. -* Interface Functions:: An abstraction over the basic functions. -* Basic Functions:: Utility and basic parsing functions. -* Standards:: A summary of RFCs and working documents used. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Function and variable index. -@end menu - - -@node Decoding and Viewing -@chapter Decoding and Viewing - -This chapter deals with decoding and viewing @acronym{MIME} messages on a -higher level. - -The main idea is to first analyze a @acronym{MIME} article, and then allow -other programs to do things based on the list of @dfn{handles} that are -returned as a result of this analysis. - -@menu -* Dissection:: Analyzing a @acronym{MIME} message. -* Non-MIME:: Analyzing a non-@acronym{MIME} message. -* Handles:: Handle manipulations. -* Display:: Displaying handles. -* Display Customization:: Variables that affect display. -* Files and Directories:: Saving and naming attachments. -* New Viewers:: How to write your own viewers. -@end menu - - -@node Dissection -@section Dissection - -The @code{mm-dissect-buffer} is the function responsible for dissecting -a @acronym{MIME} article. If given a multipart message, it will recursively -descend the message, following the structure, and return a tree of -@acronym{MIME} handles that describes the structure of the message. - -@node Non-MIME -@section Non-MIME -@vindex mm-uu-configure-list - -Gnus also understands some non-@acronym{MIME} attachments, such as -postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp, -diff. Each of these features can be disabled by add an item into -@code{mm-uu-configure-list}. For example, - -@lisp -(require 'mm-uu) -(add-to-list 'mm-uu-configure-list '(pgp-signed . disabled)) -@end lisp - -@table @code -@item postscript -@findex postscript -PostScript file. - -@item uu -@findex uu -Uuencoded file. - -@item binhex -@findex binhex -Binhex encoded file. - -@item yenc -@findex yenc -Yenc encoded file. - -@item shar -@findex shar -Shar archive file. - -@item forward -@findex forward -Non-@acronym{MIME} forwarded message. - -@item gnatsweb -@findex gnatsweb -Gnatsweb attachment. - -@item pgp-signed -@findex pgp-signed -@acronym{PGP} signed clear text. - -@item pgp-encrypted -@findex pgp-encrypted -@acronym{PGP} encrypted clear text. - -@item pgp-key -@findex pgp-key -@acronym{PGP} public keys. - -@item emacs-sources -@findex emacs-sources -@vindex mm-uu-emacs-sources-regexp -Emacs source code. This item works only in the groups matching -@code{mm-uu-emacs-sources-regexp}. - -@item diff -@vindex diff -@vindex mm-uu-diff-groups-regexp -Patches. This is intended for groups where diffs of committed files -are automatically sent to. It only works in groups matching -@code{mm-uu-diff-groups-regexp}. - -@item verbatim-marks -@cindex verbatim-marks -Slrn-style verbatim marks. - -@item LaTeX -@cindex LaTeX -LaTeX documents. It only works in groups matching -@code{mm-uu-tex-groups-regexp}. - -@end table - -@cindex text/x-verbatim -@c Is @vindex suitable for a face? -@vindex mm-uu-extract -Some inlined non-@acronym{MIME} attachments are displayed using the face -@code{mm-uu-extract}. By default, no @acronym{MIME} button for these -parts is displayed. You can force displaying a button using @kbd{K b} -(@code{gnus-summary-display-buttonized}) or add @code{text/x-verbatim} -to @code{gnus-buttonized-mime-types}, @xref{MIME Commands, ,MIME -Commands, gnus, Gnus Manual}. - -@node Handles -@section Handles - -A @acronym{MIME} handle is a list that fully describes a @acronym{MIME} -component. - -The following macros can be used to access elements in a handle: - -@table @code -@item mm-handle-buffer -@findex mm-handle-buffer -Return the buffer that holds the contents of the undecoded @acronym{MIME} -part. - -@item mm-handle-type -@findex mm-handle-type -Return the parsed @code{Content-Type} of the part. - -@item mm-handle-encoding -@findex mm-handle-encoding -Return the @code{Content-Transfer-Encoding} of the part. - -@item mm-handle-undisplayer -@findex mm-handle-undisplayer -Return the object that can be used to remove the displayed part (if it -has been displayed). - -@item mm-handle-set-undisplayer -@findex mm-handle-set-undisplayer -Set the undisplayer object. - -@item mm-handle-disposition -@findex mm-handle-disposition -Return the parsed @code{Content-Disposition} of the part. - -@item mm-get-content-id -Returns the handle(s) referred to by @code{Content-ID}. - -@end table - - -@node Display -@section Display - -Functions for displaying, removing and saving. - -@table @code -@item mm-display-part -@findex mm-display-part -Display the part. - -@item mm-remove-part -@findex mm-remove-part -Remove the part (if it has been displayed). - -@item mm-inlinable-p -@findex mm-inlinable-p -Say whether a @acronym{MIME} type can be displayed inline. - -@item mm-automatic-display-p -@findex mm-automatic-display-p -Say whether a @acronym{MIME} type should be displayed automatically. - -@item mm-destroy-part -@findex mm-destroy-part -Free all resources occupied by a part. - -@item mm-save-part -@findex mm-save-part -Offer to save the part in a file. - -@item mm-pipe-part -@findex mm-pipe-part -Offer to pipe the part to some process. - -@item mm-interactively-view-part -@findex mm-interactively-view-part -Prompt for a mailcap method to use to view the part. - -@end table - - -@node Display Customization -@section Display Customization - -@table @code - -@item mm-inline-media-tests -@vindex mm-inline-media-tests -This is an alist where the key is a @acronym{MIME} type, the second element -is a function to display the part @dfn{inline} (i.e., inside Emacs), and -the third element is a form to be @code{eval}ed to say whether the part -can be displayed inline. - -This variable specifies whether a part @emph{can} be displayed inline, -and, if so, how to do it. It does not say whether parts are -@emph{actually} displayed inline. - -@item mm-inlined-types -@vindex mm-inlined-types -This, on the other hand, says what types are to be displayed inline, if -they satisfy the conditions set by the variable above. It's a list of -@acronym{MIME} media types. - -@item mm-automatic-display -@vindex mm-automatic-display -This is a list of types that are to be displayed ``automatically'', but -only if the above variable allows it. That is, only inlinable parts can -be displayed automatically. - -@item mm-automatic-external-display -@vindex mm-automatic-external-display -This is a list of types that will be displayed automatically in an -external viewer. - -@item mm-keep-viewer-alive-types -@vindex mm-keep-viewer-alive-types -This is a list of media types for which the external viewer will not -be killed when selecting a different article. - -@item mm-attachment-override-types -@vindex mm-attachment-override-types -Some @acronym{MIME} agents create parts that have a content-disposition of -@samp{attachment}. This variable allows overriding that disposition and -displaying the part inline. (Note that the disposition is only -overridden if we are able to, and want to, display the part inline.) - -@item mm-discouraged-alternatives -@vindex mm-discouraged-alternatives -List of @acronym{MIME} types that are discouraged when viewing -@samp{multipart/alternative}. Viewing agents are supposed to view the -last possible part of a message, as that is supposed to be the richest. -However, users may prefer other types instead, and this list says what -types are most unwanted. If, for instance, @samp{text/html} parts are -very unwanted, and @samp{text/richtext} parts are somewhat unwanted, -you could say something like: - -@lisp -(setq mm-discouraged-alternatives - '("text/html" "text/richtext") - mm-automatic-display - (remove "text/html" mm-automatic-display)) -@end lisp - -Adding @code{"image/.*"} might also be useful. Spammers use images as -the preferred part of @samp{multipart/alternative} messages, so you might -not notice there are other parts. See also -@code{gnus-buttonized-mime-types}, @ref{MIME Commands, ,MIME Commands, -gnus, Gnus Manual}. After adding @code{"multipart/alternative"} to -@code{gnus-buttonized-mime-types} you can choose manually which -alternative you'd like to view. For example, you can set those -variables like: - -@lisp -(setq gnus-buttonized-mime-types - '("multipart/alternative" "multipart/signed") - mm-discouraged-alternatives - '("text/html" "image/.*")) -@end lisp - -In this case, Gnus will display radio buttons for such a kind of spam -message as follows: - -@example -1. (*) multipart/alternative ( ) image/gif - -2. (*) text/plain ( ) text/html -@end example - -@item mm-inline-large-images -@vindex mm-inline-large-images -When displaying inline images that are larger than the window, Emacs -does not enable scrolling, which means that you cannot see the whole -image. To prevent this, the library tries to determine the image size -before displaying it inline, and if it doesn't fit the window, the -library will display it externally (e.g., with @samp{ImageMagick} or -@samp{xv}). Setting this variable to @code{t} disables this check and -makes the library display all inline images as inline, regardless of -their size. If you set this variable to @code{resize}, the image will -be displayed resized to fit in the window, if Emacs has the ability to -resize images. - -@item mm-inline-large-images-proportion -@vindex mm-inline-images-max-proportion -The proportion used when resizing large images. - -@item mm-inline-override-types -@vindex mm-inline-override-types -@code{mm-inlined-types} may include regular expressions, for example to -specify that all @samp{text/.*} parts be displayed inline. If a user -prefers to have a type that matches such a regular expression be treated -as an attachment, that can be accomplished by setting this variable to a -list containing that type. For example assuming @code{mm-inlined-types} -includes @samp{text/.*}, then including @samp{text/html} in this -variable will cause @samp{text/html} parts to be treated as attachments. - -@item mm-text-html-renderer -@vindex mm-text-html-renderer -This selects the function used to render @acronym{HTML}. The predefined -renderers are selected by the symbols @code{gnus-article-html}, @code{w3}, -@code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more -information about emacs-w3m}, @code{links}, @code{lynx}, -@code{w3m-standalone} or @code{html2text}. If @code{nil} use an -external viewer. You can also specify a function, which will be -called with a @acronym{MIME} handle as the argument. - -@item mm-inline-text-html-with-images -@vindex mm-inline-text-html-with-images -Some @acronym{HTML} mails might have the trick of spammers using -@samp{} tags. It is likely to be intended to verify whether you -have read the mail. You can prevent your personal information from -leaking by setting this option to @code{nil} (which is the default). -It is currently ignored by Emacs/w3. For emacs-w3m, you may use the -command @kbd{t} on the image anchor to show an image even if it is -@code{nil}.@footnote{The command @kbd{T} will load all images. If you -have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i} -or @kbd{I} instead.} - -@item mm-w3m-safe-url-regexp -@vindex mm-w3m-safe-url-regexp -A regular expression that matches safe URL names, i.e., URLs that are -unlikely to leak personal information when rendering @acronym{HTML} -email (the default value is @samp{\\`cid:}). If @code{nil} consider -all URLs safe. In Gnus, this will be overridden according to the value -of the variable @code{gnus-safe-html-newsgroups}, @xref{Various -Various, ,Various Various, gnus, Gnus Manual}. - -@item mm-inline-text-html-with-w3m-keymap -@vindex mm-inline-text-html-with-w3m-keymap -You can use emacs-w3m command keys in the inlined text/html part by -setting this option to non-@code{nil}. The default value is @code{t}. - -@item mm-external-terminal-program -@vindex mm-external-terminal-program -The program used to start an external terminal. - -@item mm-enable-external -@vindex mm-enable-external -Indicate whether external @acronym{MIME} handlers should be used. - -If @code{t}, all defined external @acronym{MIME} handlers are used. If -@code{nil}, files are saved to disk (@code{mailcap-save-binary-file}). -If it is the symbol @code{ask}, you are prompted before the external -@acronym{MIME} handler is invoked. - -When you launch an attachment through mailcap (@pxref{mailcap}) an -attempt is made to use a safe viewer with the safest options---this isn't -the case if you save it to disk and launch it in a different way -(command line or double-clicking). Anyhow, if you want to be sure not -to launch any external programs, set this variable to @code{nil} or -@code{ask}. - -@end table - -@node Files and Directories -@section Files and Directories - -@table @code - -@item mm-default-directory -@vindex mm-default-directory -The default directory for saving attachments. If @code{nil} use -@code{default-directory}. - -@item mm-tmp-directory -@vindex mm-tmp-directory -Directory for storing temporary files. - -@item mm-file-name-rewrite-functions -@vindex mm-file-name-rewrite-functions -A list of functions used for rewriting file names of @acronym{MIME} -parts. Each function is applied successively to the file name. -Ready-made functions include - -@table @code -@item mm-file-name-delete-control -@findex mm-file-name-delete-control -Delete all control characters. - -@item mm-file-name-delete-gotchas -@findex mm-file-name-delete-gotchas -Delete characters that could have unintended consequences when used -with flawed shell scripts, i.e., @samp{|}, @samp{>} and @samp{<}; and -@samp{-}, @samp{.} as the first character. - -@item mm-file-name-delete-whitespace -@findex mm-file-name-delete-whitespace -Remove all whitespace. - -@item mm-file-name-trim-whitespace -@findex mm-file-name-trim-whitespace -Remove leading and trailing whitespace. - -@item mm-file-name-collapse-whitespace -@findex mm-file-name-collapse-whitespace -Collapse multiple whitespace characters. - -@item mm-file-name-replace-whitespace -@findex mm-file-name-replace-whitespace -@vindex mm-file-name-replace-whitespace -Replace whitespace with underscores. Set the variable -@code{mm-file-name-replace-whitespace} to any other string if you do -not like underscores. -@end table - -The standard Emacs functions @code{capitalize}, @code{downcase}, -@code{upcase} and @code{upcase-initials} might also prove useful. - -@item mm-path-name-rewrite-functions -@vindex mm-path-name-rewrite-functions -List of functions used for rewriting the full file names of @acronym{MIME} -parts. This is used when viewing parts externally, and is meant for -transforming the absolute name so that non-compliant programs can find -the file where it's saved. - -@end table - -@node New Viewers -@section New Viewers - -Here's an example viewer for displaying @code{text/enriched} inline: - -@lisp -(defun mm-display-enriched-inline (handle) - (let (text) - (with-temp-buffer - (mm-insert-part handle) - (save-window-excursion - (enriched-decode (point-min) (point-max)) - (setq text (buffer-string)))) - (mm-insert-inline handle text))) -@end lisp - -We see that the function takes a @acronym{MIME} handle as its parameter. It -then goes to a temporary buffer, inserts the text of the part, does some -work on the text, stores the result, goes back to the buffer it was -called from and inserts the result. - -The two important helper functions here are @code{mm-insert-part} and -@code{mm-insert-inline}. The first function inserts the text of the -handle in the current buffer. It handles charset and/or content -transfer decoding. The second function just inserts whatever text you -tell it to insert, but it also sets things up so that the text can be -``undisplayed'' in a convenient manner. - - -@node Composing -@chapter Composing -@cindex Composing -@cindex MIME Composing -@cindex MML -@cindex MIME Meta Language - -Creating a @acronym{MIME} message is boring and non-trivial. Therefore, -a library called @code{mml} has been defined that parses a language -called @acronym{MML} (@acronym{MIME} Meta Language) and generates -@acronym{MIME} messages. - -@findex mml-generate-mime -The main interface function is @code{mml-generate-mime}. It will -examine the contents of the current (narrowed-to) buffer and return a -string containing the @acronym{MIME} message. - -@menu -* Simple MML Example:: An example @acronym{MML} document. -* MML Definition:: All valid @acronym{MML} elements. -* Advanced MML Example:: Another example @acronym{MML} document. -* Encoding Customization:: Variables that affect encoding. -* Charset Translation:: How charsets are mapped from @sc{mule} to @acronym{MIME}. -* Conversion:: Going from @acronym{MIME} to @acronym{MML} and vice versa. -* Flowed text:: Soft and hard newlines. -@end menu - - -@node Simple MML Example -@section Simple MML Example - -Here's a simple @samp{multipart/alternative}: - -@example -<#multipart type=alternative> -This is a plain text part. -<#part type=text/enriched> -
This is a centered enriched part
-<#/multipart> -@end example - -After running this through @code{mml-generate-mime}, we get this: - -@example -Content-Type: multipart/alternative; boundary="=-=-=" - - ---=-=-= - - -This is a plain text part. - ---=-=-= -Content-Type: text/enriched - - -
This is a centered enriched part
- ---=-=-=-- -@end example - - -@node MML Definition -@section MML Definition - -The @acronym{MML} language is very simple. It looks a bit like an SGML -application, but it's not. - -The main concept of @acronym{MML} is the @dfn{part}. Each part can be of a -different type or use a different charset. The way to delineate a part -is with a @samp{<#part ...>} tag. Multipart parts can be introduced -with the @samp{<#multipart ...>} tag. Parts are ended by the -@samp{<#/part>} or @samp{<#/multipart>} tags. Parts started with the -@samp{<#part ...>} tags are also closed by the next open tag. - -There's also the @samp{<#external ...>} tag. These introduce -@samp{external/message-body} parts. - -Each tag can contain zero or more parameters on the form -@samp{parameter=value}. The values may be enclosed in quotation marks, -but that's not necessary unless the value contains white space. So -@samp{filename=/home/user/#hello$^yes} is perfectly valid. - -The following parameters have meaning in @acronym{MML}; parameters that have no -meaning are ignored. The @acronym{MML} parameter names are the same as the -@acronym{MIME} parameter names; the things in the parentheses say which -header it will be used in. - -@table @samp -@item type -The @acronym{MIME} type of the part (@code{Content-Type}). - -@item filename -Use the contents of the file in the body of the part -(@code{Content-Disposition}). - -@item charset -The contents of the body of the part are to be encoded in the character -set specified (@code{Content-Type}). @xref{Charset Translation}. - -@item name -Might be used to suggest a file name if the part is to be saved -to a file (@code{Content-Type}). - -@item disposition -Valid values are @samp{inline} and @samp{attachment} -(@code{Content-Disposition}). - -@item encoding -Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and -@samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset -Translation}. - -@item description -A description of the part (@code{Content-Description}). - -@item creation-date -RFC822 date when the part was created (@code{Content-Disposition}). - -@item modification-date -RFC822 date when the part was modified (@code{Content-Disposition}). - -@item read-date -RFC822 date when the part was read (@code{Content-Disposition}). - -@item recipients -Who to encrypt/sign the part to. This field is used to override any -auto-detection based on the To/CC headers. - -@item sender -Identity used to sign the part. This field is used to override the -default key used. - -@item size -The size (in octets) of the part (@code{Content-Disposition}). - -@item sign -What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp} -or @code{pgpmime}) - -@item encrypt -What technology to encrypt this @acronym{MML} part with (@code{smime}, -@code{pgp} or @code{pgpmime}) - -@end table - -Parameters for @samp{text/plain}: - -@table @samp -@item format -Formatting parameter for the text, valid values include @samp{fixed} -(the default) and @samp{flowed}. Normally you do not specify this -manually, since it requires the textual body to be formatted in a -special way described in RFC 2646. @xref{Flowed text}. -@end table - -Parameters for @samp{application/octet-stream}: - -@table @samp -@item type -Type of the part; informal---meant for human readers -(@code{Content-Type}). -@end table - -Parameters for @samp{message/external-body}: - -@table @samp -@item access-type -A word indicating the supported access mechanism by which the file may -be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp}, -@samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.) - -@item expiration -The RFC822 date after which the file may no longer be fetched. -(@code{Content-Type}.) - -@item size -The size (in octets) of the file. (@code{Content-Type}.) - -@item permission -Valid values are @samp{read} and @samp{read-write} -(@code{Content-Type}). - -@end table - -Parameters for @samp{sign=smime}: - -@table @samp - -@item keyfile -File containing key and certificate for signer. - -@end table - -Parameters for @samp{encrypt=smime}: - -@table @samp - -@item certfile -File containing certificate for recipient. - -@end table - - -@node Advanced MML Example -@section Advanced MML Example - -Here's a complex multipart message. It's a @samp{multipart/mixed} that -contains many parts, one of which is a @samp{multipart/alternative}. - -@example -<#multipart type=mixed> -<#part type=image/jpeg filename=~/rms.jpg disposition=inline> -<#multipart type=alternative> -This is a plain text part. -<#part type=text/enriched name=enriched.txt> -
This is a centered enriched part
-<#/multipart> -This is a new plain text part. -<#part disposition=attachment> -This plain text part is an attachment. -<#/multipart> -@end example - -And this is the resulting @acronym{MIME} message: - -@example -Content-Type: multipart/mixed; boundary="=-=-=" - - ---=-=-= - - - ---=-=-= -Content-Type: image/jpeg; - filename="~/rms.jpg" -Content-Disposition: inline; - filename="~/rms.jpg" -Content-Transfer-Encoding: base64 - -/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof -Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA -AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR -BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF -RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip -qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB -AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI -AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E -sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m -2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw -5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc -L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw -34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm -tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn -7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC -pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm -jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q== - ---=-=-= -Content-Type: multipart/alternative; boundary="==-=-=" - - ---==-=-= - - -This is a plain text part. - ---==-=-= -Content-Type: text/enriched; - name="enriched.txt" - - -
This is a centered enriched part
- ---==-=-=-- - ---=-=-= - -This is a new plain text part. - ---=-=-= -Content-Disposition: attachment - - -This plain text part is an attachment. - ---=-=-=-- -@end example - -@node Encoding Customization -@section Encoding Customization - -@table @code - -@item mm-body-charset-encoding-alist -@vindex mm-body-charset-encoding-alist -Mapping from @acronym{MIME} charset to encoding to use. This variable is -usually used except, e.g., when other requirements force a specific -encoding (digitally signed messages require 7bit encodings). The -default is - -@lisp -((iso-2022-jp . 7bit) - (iso-2022-jp-2 . 7bit) - (utf-16 . base64) - (utf-16be . base64) - (utf-16le . base64)) -@end lisp - -As an example, if you do not want to have ISO-8859-1 characters -quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to -this variable. You can override this setting on a per-message basis -by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}). - -@item mm-coding-system-priorities -@vindex mm-coding-system-priorities -Prioritize coding systems to use for outgoing messages. The default -is @code{nil}, which means to use the defaults in Emacs, but is -@code{(iso-8859-1 iso-2022-jp utf-8)} when running Emacs in the Japanese -language environment. It is a list of coding system symbols (aliases of -coding systems are also allowed, use @kbd{M-x describe-coding-system} to -make sure you are specifying correct coding system names). For example, -if you have configured Emacs to prefer UTF-8, but wish that outgoing -messages should be sent in ISO-8859-1 if possible, you can set this -variable to @code{(iso-8859-1)}. You can override this setting on a -per-message basis by using the @code{charset} @acronym{MML} tag -(@pxref{MML Definition}). - -As different hierarchies prefer different charsets, you may want to set -@code{mm-coding-system-priorities} according to the hierarchy in Gnus. -Here's an example: - -@c Corrections about preferred charsets are welcome. de, fr and fj -@c should be correct, I don't know about the rest (so these are only -@c examples): -@lisp -(add-to-list 'gnus-newsgroup-variables 'mm-coding-system-priorities) -(setq gnus-parameters - (nconc - ;; Some charsets are just examples! - '(("^cn\\." ;; Chinese - (mm-coding-system-priorities - '(iso-8859-1 cn-big5 chinese-iso-7bit utf-8))) - ("^cz\\.\\|^pl\\." ;; Central and Eastern European - (mm-coding-system-priorities '(iso-8859-2 utf-8))) - ("^de\\." ;; German language - (mm-coding-system-priorities '(iso-8859-1 iso-8859-15 utf-8))) - ("^fr\\." ;; French - (mm-coding-system-priorities '(iso-8859-15 iso-8859-1 utf-8))) - ("^fj\\." ;; Japanese - (mm-coding-system-priorities - '(iso-8859-1 iso-2022-jp utf-8))) - ("^ru\\." ;; Cyrillic - (mm-coding-system-priorities - '(koi8-r iso-8859-5 iso-8859-1 utf-8)))) - gnus-parameters)) -@end lisp - -@item mm-content-transfer-encoding-defaults -@vindex mm-content-transfer-encoding-defaults -Mapping from @acronym{MIME} types to encoding to use. This variable is usually -used except, e.g., when other requirements force a safer encoding -(digitally signed messages require 7bit encoding). Besides the normal -@acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for -each case the most efficient of quoted-printable and base64 should be -used. - -@code{qp-or-base64} has another effect. It will fold long lines so that -MIME parts may not be broken by MTA@. So do @code{quoted-printable} and -@code{base64}. - -Note that it affects body encoding only when a part is a raw forwarded -message (which will be made by @code{gnus-summary-mail-forward} with the -arg 2 for example) or is neither the @samp{text/*} type nor the -@samp{message/*} type. Even though in those cases, you can override -this setting on a per-message basis by using the @code{encoding} -@acronym{MML} tag (@pxref{MML Definition}). - -@item mm-use-ultra-safe-encoding -@vindex mm-use-ultra-safe-encoding -When this is non-@code{nil}, it means that textual parts are encoded as -quoted-printable if they contain lines longer than 76 characters or -starting with "From " in the body. Non-7bit encodings (8bit, binary) -are generally disallowed. This reduce the probability that a non-8bit -clean MTA or MDA changes the message. This should never be set -directly, but bound by other functions when necessary (e.g., when -encoding messages that are to be digitally signed). - -@end table - -@node Charset Translation -@section Charset Translation -@cindex charsets - -During translation from @acronym{MML} to @acronym{MIME}, for each -@acronym{MIME} part which has been composed inside Emacs, an appropriate -charset has to be chosen. - -@vindex mail-parse-charset -If you are running a non-@sc{mule} Emacs, this process is simple: If the -part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset -given by @code{mail-parse-charset} (a symbol) is used. (Never set this -variable directly, though. If you want to change the default charset, -please consult the documentation of the package which you use to process -@acronym{MIME} messages. -@xref{Various Message Variables, , Various Message Variables, message, - Message Manual}, for example.) -If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is -used, of course. - -@cindex MULE -@cindex UTF-8 -@cindex Unicode -@vindex mm-mime-mule-charset-alist -Things are slightly more complicated when running Emacs with @sc{mule} -support. In this case, a list of the @sc{mule} charsets used in the -part is obtained, and the @sc{mule} charsets are translated to -@acronym{MIME} charsets by consulting the table provided by Emacs itself -or the variable @code{mm-mime-mule-charset-alist} for XEmacs. -If this results in a single @acronym{MIME} charset, this is used to encode -the part. But if the resulting list of @acronym{MIME} charsets contains more -than one element, two things can happen: If it is possible to encode the -part via UTF-8, this charset is used. (For this, Emacs must support -the @code{utf-8} coding system, and the part must consist entirely of -characters which have Unicode counterparts.) If UTF-8 is not available -for some reason, the part is split into several ones, so that each one -can be encoded with a single @acronym{MIME} charset. The part can only be -split at line boundaries, though---if more than one @acronym{MIME} charset is -required to encode a single line, it is not possible to encode the part. - -When running Emacs with @sc{mule} support, the preferences for which -coding system to use is inherited from Emacs itself. This means that -if Emacs is set up to prefer UTF-8, it will be used when encoding -messages. You can modify this by altering the -@code{mm-coding-system-priorities} variable though (@pxref{Encoding -Customization}). - -The charset to be used can be overridden by setting the @code{charset} -@acronym{MML} tag (@pxref{MML Definition}) when composing the message. - -The encoding of characters (quoted-printable, 8bit, etc.)@: is orthogonal -to the discussion here, and is controlled by the variables -@code{mm-body-charset-encoding-alist} and -@code{mm-content-transfer-encoding-defaults} (@pxref{Encoding -Customization}). - -@node Conversion -@section Conversion - -@findex mime-to-mml -A (multipart) @acronym{MIME} message can be converted to @acronym{MML} -with the @code{mime-to-mml} function. It works on the message in the -current buffer, and substitutes @acronym{MML} markup for @acronym{MIME} -boundaries. Non-textual parts do not have their contents in the buffer, -but instead have the contents in separate buffers that are referred to -from the @acronym{MML} tags. - -@findex mml-to-mime -An @acronym{MML} message can be converted back to @acronym{MIME} by the -@code{mml-to-mime} function. - -These functions are in certain senses ``lossy''---you will not get back -an identical message if you run @code{mime-to-mml} and then -@code{mml-to-mime}. Not only will trivial things like the order of the -headers differ, but the contents of the headers may also be different. -For instance, the original message may use base64 encoding on text, -while @code{mml-to-mime} may decide to use quoted-printable encoding, and -so on. - -In essence, however, these two functions should be the inverse of each -other. The resulting contents of the message should remain equivalent, -if not identical. - - -@node Flowed text -@section Flowed text -@cindex format=flowed - -The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines} -variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines, -emacs, Emacs Manual}) when encoding a message, and the -``format=flowed'' Content-Type parameter when decoding a message. - -On encoding text, regardless of @code{use-hard-newlines}, lines -terminated by soft newline characters are filled together and wrapped -after the column decided by @code{fill-flowed-encode-column}. -Quotation marks (matching @samp{^>* ?}) are respected. The variable -controls how the text will look in a client that does not support -flowed text, the default is to wrap after 66 characters. If hard -newline characters are not present in the buffer, no flow encoding -occurs. - -You can customize the value of the @code{mml-enable-flowed} variable -to enable or disable the flowed encoding usage when newline -characters are present in the buffer. - -On decoding flowed text, lines with soft newline characters are filled -together and wrapped after the column decided by -@code{fill-flowed-display-column}. The default is to wrap after -@code{fill-column}. - -@table @code -@item mm-fill-flowed -@vindex mm-fill-flowed -If non-@code{nil} a format=flowed article will be displayed flowed. -@end table - - -@node Interface Functions -@chapter Interface Functions -@cindex interface functions -@cindex mail-parse - -The @code{mail-parse} library is an abstraction over the actual -low-level libraries that are described in the next chapter. - -Standards change, and so programs have to change to fit in the new -mold. For instance, RFC2045 describes a syntax for the -@code{Content-Type} header that only allows @acronym{ASCII} characters in the -parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme -for continuation headers and non-@acronym{ASCII} characters. - -The traditional way to deal with this is just to update the library -functions to parse the new syntax. However, this is sometimes the wrong -thing to do. In some instances it may be vital to be able to understand -both the old syntax as well as the new syntax, and if there is only one -library, one must choose between the old version of the library and the -new version of the library. - -The Emacs @acronym{MIME} library takes a different tack. It defines a -series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} -and so on) that parses strictly according to the corresponding -standard. However, normal programs would not use the functions -provided by these libraries directly, but instead use the functions -provided by the @code{mail-parse} library. The functions in this -library are just aliases to the corresponding functions in the latest -low-level libraries. Using this scheme, programs get a consistent -interface they can use, and library developers are free to create -write code that handles new standards. - -The following functions are defined by this library: - -@table @code -@item mail-header-parse-content-type -@findex mail-header-parse-content-type -Parse a @code{Content-Type} header and return a list on the following -format: - -@lisp -("type/subtype" - (attribute1 . value1) - (attribute2 . value2) - ...) -@end lisp - -Here's an example: - -@example -(mail-header-parse-content-type - "image/gif; name=\"b980912.gif\"") -@result{} ("image/gif" (name . "b980912.gif")) -@end example - -@item mail-header-parse-content-disposition -@findex mail-header-parse-content-disposition -Parse a @code{Content-Disposition} header and return a list on the same -format as the function above. - -@item mail-content-type-get -@findex mail-content-type-get -Takes two parameters---a list on the format above, and an attribute. -Returns the value of the attribute. - -@example -(mail-content-type-get - '("image/gif" (name . "b980912.gif")) 'name) -@result{} "b980912.gif" -@end example - -@item mail-header-encode-parameter -@findex mail-header-encode-parameter -Takes a parameter string and returns an encoded version of the string. -This is used for parameters in headers like @code{Content-Type} and -@code{Content-Disposition}. - -@item mail-header-remove-comments -@findex mail-header-remove-comments -Return a comment-free version of a header. - -@example -(mail-header-remove-comments - "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") -@result{} "Gnus/5.070027 " -@end example - -@item mail-header-remove-whitespace -@findex mail-header-remove-whitespace -Remove linear white space from a header. Space inside quoted strings -and comments is preserved. - -@example -(mail-header-remove-whitespace - "image/gif; name=\"Name with spaces\"") -@result{} "image/gif;name=\"Name with spaces\"" -@end example - -@item mail-header-get-comment -@findex mail-header-get-comment -Return the last comment in a header. - -@example -(mail-header-get-comment - "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") -@result{} "Finnish Landrace" -@end example - -@item mail-header-parse-address -@findex mail-header-parse-address -Parse an address and return a list containing the mailbox and the -plaintext name. - -@example -(mail-header-parse-address - "Hrvoje Niksic ") -@result{} ("hniksic@@srce.hr" . "Hrvoje Niksic") -@end example - -@item mail-header-parse-addresses -@findex mail-header-parse-addresses -Parse a string with list of addresses and return a list of elements like -the one described above. - -@example -(mail-header-parse-addresses - "Hrvoje Niksic , Steinar Bang ") -@result{} (("hniksic@@srce.hr" . "Hrvoje Niksic") - ("sb@@metis.no" . "Steinar Bang")) -@end example - -@item mail-header-parse-date -@findex mail-header-parse-date -Parse a date string and return an Emacs time structure. - -@item mail-narrow-to-head -@findex mail-narrow-to-head -Narrow the buffer to the header section of the buffer. Point is placed -at the beginning of the narrowed buffer. - -@item mail-header-narrow-to-field -@findex mail-header-narrow-to-field -Narrow the buffer to the header under point. Understands continuation -headers. - -@item mail-header-fold-field -@findex mail-header-fold-field -Fold the header under point. - -@item mail-header-unfold-field -@findex mail-header-unfold-field -Unfold the header under point. - -@item mail-header-field-value -@findex mail-header-field-value -Return the value of the field under point. - -@item mail-encode-encoded-word-region -@findex mail-encode-encoded-word-region -Encode the non-@acronym{ASCII} words in the region. For instance, -@samp{Naïve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}. - -@item mail-encode-encoded-word-buffer -@findex mail-encode-encoded-word-buffer -Encode the non-@acronym{ASCII} words in the current buffer. This function is -meant to be called narrowed to the headers of a message. - -@item mail-encode-encoded-word-string -@findex mail-encode-encoded-word-string -Encode the words that need encoding in a string, and return the result. - -@example -(mail-encode-encoded-word-string - "This is naïve, baby") -@result{} "This is =?iso-8859-1?q?na=EFve,?= baby" -@end example - -@item mail-decode-encoded-word-region -@findex mail-decode-encoded-word-region -Decode the encoded words in the region. - -@item mail-decode-encoded-word-string -@findex mail-decode-encoded-word-string -Decode the encoded words in the string and return the result. - -@example -(mail-decode-encoded-word-string - "This is =?iso-8859-1?q?na=EFve,?= baby") -@result{} "This is naïve, baby" -@end example - -@end table - -Currently, @code{mail-parse} is an abstraction over @code{ietf-drums}, -@code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented -in the subsequent sections. - - - -@node Basic Functions -@chapter Basic Functions - -This chapter describes the basic, ground-level functions for parsing and -handling. Covered here is parsing @code{From} lines, removing comments -from header lines, decoding encoded words, parsing date headers and so -on. High-level functionality is dealt with in the first chapter -(@pxref{Decoding and Viewing}). - -@menu -* rfc2045:: Encoding @code{Content-Type} headers. -* rfc2231:: Parsing @code{Content-Type} headers. -* ietf-drums:: Handling mail headers defined by RFC822bis. -* rfc2047:: En/decoding encoded words in headers. -* time-date:: Functions for parsing dates and manipulating time. -* qp:: Quoted-Printable en/decoding. -* base64:: Base64 en/decoding. -* binhex:: Binhex decoding. -* uudecode:: Uuencode decoding. -* yenc:: Yenc decoding. -* rfc1843:: Decoding HZ-encoded text. -* mailcap:: How parts are displayed is specified by the @file{.mailcap} file -@end menu - - -@node rfc2045 -@section rfc2045 - -RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would -imagine that there would be a lot to implement. But there isn't, since -most of the implementation details are delegated to the subsequent -RFCs. - -So @file{rfc2045.el} has only a single function: - -@table @code -@item rfc2045-encode-string -@findex rfc2045-encode-string -Takes a parameter and a value and returns a @samp{PARAM=VALUE} string. -@var{value} will be quoted if there are non-safe characters in it. -@end table - - -@node rfc2231 -@section rfc2231 - -RFC2231 defines a syntax for the @code{Content-Type} and -@code{Content-Disposition} headers. Its snappy name is @dfn{MIME -Parameter Value and Encoded Word Extensions: Character Sets, Languages, -and Continuations}. - -In short, these headers look something like this: - -@example -Content-Type: application/x-stuff; - title*0*=us-ascii'en'This%20is%20even%20more%20; - title*1*=%2A%2A%2Afun%2A%2A%2A%20; - title*2="isn't it!" -@end example - -They usually aren't this bad, though. - -The following functions are defined by this library: - -@table @code -@item rfc2231-parse-string -@findex rfc2231-parse-string -Parse a @code{Content-Type} header and return a list describing its -elements. - -@example -(rfc2231-parse-string - "application/x-stuff; - title*0*=us-ascii'en'This%20is%20even%20more%20; - title*1*=%2A%2A%2Afun%2A%2A%2A%20; - title*2=\"isn't it!\"") -@result{} ("application/x-stuff" - (title . "This is even more ***fun*** isn't it!")) -@end example - -@item rfc2231-get-value -@findex rfc2231-get-value -Takes one of the lists on the format above and returns -the value of the specified attribute. - -@item rfc2231-encode-string -@findex rfc2231-encode-string -Encode a parameter in headers likes @code{Content-Type} and -@code{Content-Disposition}. - -@end table - - -@node ietf-drums -@section ietf-drums - -@dfn{drums} is an IETF working group that is working on the replacement -for RFC822. - -The functions provided by this library include: - -@table @code -@item ietf-drums-remove-comments -@findex ietf-drums-remove-comments -Remove the comments from the argument and return the results. - -@item ietf-drums-remove-whitespace -@findex ietf-drums-remove-whitespace -Remove linear white space from the string and return the results. -Spaces inside quoted strings and comments are left untouched. - -@item ietf-drums-get-comment -@findex ietf-drums-get-comment -Return the last most comment from the string. - -@item ietf-drums-parse-address -@findex ietf-drums-parse-address -Parse an address string and return a list that contains the mailbox and -the plain text name. - -@item ietf-drums-parse-addresses -@findex ietf-drums-parse-addresses -Parse a string that contains any number of comma-separated addresses and -return a list that contains mailbox/plain text pairs. - -@item ietf-drums-parse-date -@findex ietf-drums-parse-date -Parse a date string and return an Emacs time structure. - -@item ietf-drums-narrow-to-header -@findex ietf-drums-narrow-to-header -Narrow the buffer to the header section of the current buffer. - -@end table - - -@node rfc2047 -@section rfc2047 - -RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how -non-@acronym{ASCII} text in headers are to be encoded. This is actually rather -complicated, so a number of variables are necessary to tweak what this -library does. - -The following variables are tweakable: - -@table @code -@item rfc2047-header-encoding-alist -@vindex rfc2047-header-encoding-alist -This is an alist of header / encoding-type pairs. Its main purpose is -to prevent encoding of certain headers. - -The keys can either be header regexps, or @code{t}. - -The values can be @code{nil}, in which case the header(s) in question -won't be encoded, @code{mime}, which means that they will be encoded, or -@code{address-mime}, which means the header(s) will be encoded carefully -assuming they contain addresses. - -@item rfc2047-charset-encoding-alist -@vindex rfc2047-charset-encoding-alist -RFC2047 specifies two forms of encoding---@code{Q} (a -Quoted-Printable-like encoding) and @code{B} (base64). This alist -specifies which charset should use which encoding. - -@item rfc2047-encode-function-alist -@vindex rfc2047-encode-function-alist -This is an alist of encoding / function pairs. The encodings are -@code{Q}, @code{B} and @code{nil}. - -@item rfc2047-encoded-word-regexp -@vindex rfc2047-encoded-word-regexp -When decoding words, this library looks for matches to this regexp. - -@item rfc2047-encoded-word-regexp-loose -@vindex rfc2047-encoded-word-regexp-loose -This is a version from which the regexp for the Q encoding pattern of -@code{rfc2047-encoded-word-regexp} is made loose. - -@item rfc2047-encode-encoded-words -@vindex rfc2047-encode-encoded-words -The boolean variable specifies whether encoded words -(e.g., @samp{=?us-ascii?q?hello?=}) should be encoded again. -@code{rfc2047-encoded-word-regexp} is used to look for such words. - -@item rfc2047-allow-irregular-q-encoded-words -@vindex rfc2047-allow-irregular-q-encoded-words -The boolean variable specifies whether irregular Q encoded words -(e.g., @samp{=?us-ascii?q?hello??=}) should be decoded. If it is -non-@code{nil}, @code{rfc2047-encoded-word-regexp-loose} is used instead -of @code{rfc2047-encoded-word-regexp} to look for encoded words. - -@end table - -Those were the variables, and these are this functions: - -@table @code -@item rfc2047-narrow-to-field -@findex rfc2047-narrow-to-field -Narrow the buffer to the header on the current line. - -@item rfc2047-encode-message-header -@findex rfc2047-encode-message-header -Should be called narrowed to the header of a message. Encodes according -to @code{rfc2047-header-encoding-alist}. - -@item rfc2047-encode-region -@findex rfc2047-encode-region -Encodes all encodable words in the region specified. - -@item rfc2047-encode-string -@findex rfc2047-encode-string -Encode a string and return the results. - -@item rfc2047-decode-region -@findex rfc2047-decode-region -Decode the encoded words in the region. - -@item rfc2047-decode-string -@findex rfc2047-decode-string -Decode a string and return the results. - -@item rfc2047-encode-parameter -@findex rfc2047-encode-parameter -Encode a parameter in the RFC2047-like style. This is a substitution -for the @code{rfc2231-encode-string} function, that is the standard but -many mailers don't support it. @xref{rfc2231}. - -@end table - - -@node time-date -@section time-date - -While not really a part of the @acronym{MIME} library, it is convenient to -document this library here. It deals with parsing @code{Date} headers -and manipulating time. (Not by using tesseracts, though, I'm sorry to -say.) - -These functions convert between five formats: A date string, an Emacs -time structure, a decoded time list, a second number, and a day number. - -Here's a bunch of time/date/second/day examples: - -@example -(parse-time-string "Sat Sep 12 12:21:54 1998 +0200") -@result{} (54 21 12 12 9 1998 6 nil 7200) - -(date-to-time "Sat Sep 12 12:21:54 1998 +0200") -@result{} (13818 19266) - -(float-time '(13818 19266)) -@result{} 905595714.0 - -(seconds-to-time 905595714.0) -@result{} (13818 19266 0 0) - -(time-to-days '(13818 19266)) -@result{} 729644 - -(days-to-time 729644) -@result{} (961933 512) - -(time-since '(13818 19266)) -@result{} (6797 9607 984839 247000) - -(time-less-p '(13818 19266) '(13818 19145)) -@result{} nil - -(subtract-time '(13818 19266) '(13818 19145)) -@result{} (0 121) - -(days-between "Sat Sep 12 12:21:54 1998 +0200" - "Sat Sep 07 12:21:54 1998 +0200") -@result{} 5 - -(date-leap-year-p 2000) -@result{} t - -(time-to-day-in-year '(13818 19266)) -@result{} 255 - -(time-to-number-of-days - (time-since - (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) -@result{} 4314.095589286675 -@end example - -And finally, we have @code{safe-date-to-time}, which does the same as -@code{date-to-time}, but returns a zero time if the date is -syntactically malformed. - -The five data representations used are the following: - -@table @var -@item date -An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12 -12:21:54 1998 +0200"}. - -@item time -An internal Emacs time. For instance: @code{(13818 26466 0 0)}. - -@item seconds -A floating point representation of the internal Emacs time. For -instance: @code{905595714.0}. - -@item days -An integer number representing the number of days since 00000101. For -instance: @code{729644}. - -@item decoded time -A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t -7200)}. -@end table - -All the examples above represent the same moment. - -These are the functions available: - -@table @code -@item date-to-time -Take a date and return a time. - -@item float-time -Take a time and return seconds. (This is a built-in function.) - -@item seconds-to-time -Take seconds and return a time. - -@item time-to-days -Take a time and return days. - -@item days-to-time -Take days and return a time. - -@item date-to-day -Take a date and return days. - -@item time-to-number-of-days -Take a time and return the number of days that represents. - -@item safe-date-to-time -Take a date and return a time. If the date is not syntactically valid, -return a ``zero'' time. - -@item time-less-p -Take two times and say whether the first time is less (i.e., earlier) -than the second time. - -@item time-since -Take a time and return a time saying how long it was since that time. - -@item subtract-time -Take two times and subtract the second from the first. I.e., return -the time between the two times. - -@item days-between -Take two days and return the number of days between those two days. - -@item date-leap-year-p -Take a year number and say whether it's a leap year. - -@item time-to-day-in-year -Take a time and return the day number within the year that the time is -in. - -@end table - - -@node qp -@section qp - -This library deals with decoding and encoding Quoted-Printable text. - -Very briefly explained, qp encoding means translating all 8-bit -characters (and lots of control characters) into things that look like -@samp{=EF}; that is, an equal sign followed by the byte encoded as a hex -string. - -The following functions are defined by the library: - -@table @code -@item quoted-printable-decode-region -@findex quoted-printable-decode-region -QP-decode all the encoded text in the specified region. - -@item quoted-printable-decode-string -@findex quoted-printable-decode-string -Decode the QP-encoded text in a string and return the results. - -@item quoted-printable-encode-region -@findex quoted-printable-encode-region -QP-encode all the encodable characters in the specified region. The third -optional parameter @var{fold} specifies whether to fold long lines. -(Long here means 72.) - -@item quoted-printable-encode-string -@findex quoted-printable-encode-string -QP-encode all the encodable characters in a string and return the -results. - -@end table - - -@node base64 -@section base64 -@cindex base64 - -Base64 is an encoding that encodes three bytes into four characters, -thereby increasing the size by about 33%. The alphabet used for -encoding is very resistant to mangling during transit. - -The following functions are defined by this library: - -@table @code -@item base64-encode-region -@findex base64-encode-region -base64 encode the selected region. Return the length of the encoded -text. Optional third argument @var{no-line-break} means do not break -long lines into shorter lines. - -@item base64-encode-string -@findex base64-encode-string -base64 encode a string and return the result. - -@item base64-decode-region -@findex base64-decode-region -base64 decode the selected region. Return the length of the decoded -text. If the region can't be decoded, return @code{nil} and don't -modify the buffer. - -@item base64-decode-string -@findex base64-decode-string -base64 decode a string and return the result. If the string can't be -decoded, @code{nil} is returned. - -@end table - - -@node binhex -@section binhex -@cindex binhex -@cindex Apple -@cindex Macintosh - -@code{binhex} is an encoding that originated in Macintosh environments. -The following function is supplied to deal with these: - -@table @code -@item binhex-decode-region -@findex binhex-decode-region -Decode the encoded text in the region. If given a third parameter, only -decode the @code{binhex} header and return the filename. - -@end table - -@node uudecode -@section uudecode -@cindex uuencode -@cindex uudecode - -@code{uuencode} is probably still the most popular encoding of binaries -used on Usenet, although @code{base64} rules the mail world. - -The following function is supplied by this package: - -@table @code -@item uudecode-decode-region -@findex uudecode-decode-region -Decode the text in the region. -@end table - - -@node yenc -@section yenc -@cindex yenc - -@code{yenc} is used for encoding binaries on Usenet. The following -function is supplied by this package: - -@table @code -@item yenc-decode-region -@findex yenc-decode-region -Decode the encoded text in the region. - -@end table - - -@node rfc1843 -@section rfc1843 -@cindex rfc1843 -@cindex HZ -@cindex Chinese - -RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages. In -essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this: - -@example -This sentence is in @acronym{ASCII}. -The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye. -@end example - -Simple enough, and widely used in China. - -The following functions are available to handle this encoding: - -@table @code -@item rfc1843-decode-region -Decode HZ-encoded text in the region. - -@item rfc1843-decode-string -Decode a HZ-encoded string and return the result. - -@end table - - -@node mailcap -@section mailcap - -The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message -handlers and describes how elements are supposed to be displayed. -Here's an example file: - -@example -image/*; gimp -8 %s -audio/wav; wavplayer %s -application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc -@end example - -This says that all image files should be displayed with @code{gimp}, -that WAVE audio files should be played by @code{wavplayer}, and that -MS-WORD files should be inlined by @code{catdoc}. - -The @code{mailcap} library parses this file, and provides functions for -matching types. - -@table @code -@item mailcap-mime-data -@vindex mailcap-mime-data -This variable is an alist of alists containing backup viewing rules. - -@end table - -Interface functions: - -@table @code -@item mailcap-parse-mailcaps -@findex mailcap-parse-mailcaps -Parse the @file{~/.mailcap} file. - -@item mailcap-mime-info -Takes a @acronym{MIME} type as its argument and returns the matching viewer. - -@end table - - - - -@node Standards -@chapter Standards - -The Emacs @acronym{MIME} library implements handling of various elements -according to a (somewhat) large number of RFCs, drafts and standards -documents. This chapter lists the relevant ones. They can all be -fetched from @uref{http://quimby.gnus.org/notes/}. - -@table @dfn -@item RFC822 -@itemx STD11 -Standard for the Format of ARPA Internet Text Messages. - -@item RFC1036 -Standard for Interchange of USENET Messages - -@item RFC2045 -Format of Internet Message Bodies - -@item RFC2046 -Media Types - -@item RFC2047 -Message Header Extensions for Non-@acronym{ASCII} Text - -@item RFC2048 -Registration Procedures - -@item RFC2049 -Conformance Criteria and Examples - -@item RFC2231 -@acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets, -Languages, and Continuations - -@item RFC1843 -HZ---A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and -@acronym{ASCII} characters - -@item draft-ietf-drums-msg-fmt-05.txt -Draft for the successor of RFC822 - -@item RFC2112 -The @acronym{MIME} Multipart/Related Content-type - -@item RFC1892 -The Multipart/Report Content Type for the Reporting of Mail System -Administrative Messages - -@item RFC2183 -Communicating Presentation Information in Internet Messages: The -Content-Disposition Header Field - -@item RFC2646 -Documentation of the text/plain format parameter for flowed text. - -@end table - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index -@printindex cp - -@bye - - -@c Local Variables: -@c mode: texinfo -@c coding: utf-8 -@c End: diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi deleted file mode 100644 index 0632e735df0..00000000000 --- a/doc/misc/epa.texi +++ /dev/null @@ -1,516 +0,0 @@ -\input texinfo @c -*- mode: texinfo -*- -@c %**start of header -@setfilename ../../info/epa -@settitle EasyPG Assistant User's Manual -@documentencoding UTF-8 -@c %**end of header - -@set VERSION 1.0.0 - -@copying -This file describes EasyPG Assistant @value{VERSION}. - -Copyright @copyright{} 2007--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* EasyPG Assistant: (epa). An Emacs user interface to GNU Privacy Guard. -@end direntry - -@titlepage -@title EasyPG Assistant - -@author by Daiki Ueno -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top EasyPG Assistant user's manual - -EasyPG Assistant is an Emacs user interface to GNU Privacy Guard -(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}). - -EasyPG Assistant is a part of the package called EasyPG, an all-in-one -GnuPG interface for Emacs. EasyPG also contains the library interface -called EasyPG Library. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: -* Quick start:: -* Commands:: -* Caching Passphrases:: -* Bug Reports:: -* GNU Free Documentation License:: The license for this documentation. -* Key Index:: -* Function Index:: -* Variable Index:: -@end menu - -@node Overview -@chapter Overview - -EasyPG Assistant provides the following features. - -@itemize @bullet -@item Key management. -@item Cryptographic operations on regions. -@item Cryptographic operations on files. -@item Dired integration. -@item Mail-mode integration. -@item Automatic encryption/decryption of *.gpg files. -@end itemize - -@node Quick start -@chapter Quick start - -EasyPG Assistant commands are prefixed by @samp{epa-}. For example, - -@itemize @bullet -@item To browse your keyring, type @kbd{M-x epa-list-keys} - -@item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region} - -@item To encrypt a file, type @kbd{M-x epa-encrypt-file} -@end itemize - -EasyPG Assistant provides several cryptographic features which can be -integrated into other Emacs functionalities. For example, automatic -encryption/decryption of @file{*.gpg} files. - -@node Commands -@chapter Commands - -This chapter introduces various commands for typical use cases. - -@menu -* Key management:: -* Cryptographic operations on regions:: -* Cryptographic operations on files:: -* Dired integration:: -* Mail-mode integration:: -* Encrypting/decrypting gpg files:: -@end menu - -@node Key management -@section Key management -Probably the first step of using EasyPG Assistant is to browse your -keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg ---list-keys} from the command line. - -@deffn Command epa-list-keys name mode -Show all keys matched with @var{name} from the public keyring. -@end deffn - -@noindent -The output looks as follows. - -@example - u A5B6B2D4B15813FE Daiki Ueno -@end example - -@noindent -A character on the leftmost column indicates the trust level of the -key. If it is @samp{u}, the key is marked as ultimately trusted. The -second column is the key ID, and the rest is the user ID. - -You can move over entries by @key{TAB}. If you type @key{RET} or -click button1 on an entry, you will see more detailed information -about the key you selected. - -@example - u Daiki Ueno - u A5B6B2D4B15813FE 1024bits DSA - Created: 2001-10-09 - Expires: 2007-09-04 - Capabilities: sign certify - Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE - u 4447461B2A9BEA2D 2048bits ELGAMAL_E - Created: 2001-10-09 - Expires: 2007-09-04 - Capabilities: encrypt - Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D -@end example - -@noindent -To browse your private keyring, use @kbd{M-x epa-list-secret-keys}. - -@deffn Command epa-list-secret-keys name -Show all keys matched with @var{name} from the private keyring. -@end deffn - -@noindent -In @file{*Keys*} buffer, several commands are available. The common -use case is to export some keys to a file. To do that, type @kbd{m} -to select keys, type @kbd{o}, and then supply the filename. - -Below are other commands related to key management. Some of them take -a file as input/output, and others take the current region. - -@deffn Command epa-insert-keys keys -Insert selected @var{keys} after the point. It will let you select -keys before insertion. By default, it will encode keys in the OpenPGP -armor format. -@end deffn - -@deffn Command epa-import-keys file -Import keys from @var{file} to your keyring. -@end deffn - -@deffn Command epa-import-keys-region start end -Import keys from the current region between @var{start} and @var{end} -to your keyring. -@end deffn - -@deffn Command epa-import-armor-in-region start end -Import keys in the OpenPGP armor format in the current region between -@var{start} and @var{end}. The difference from -@code{epa-import-keys-region} is that -@code{epa-import-armor-in-region} searches armors in the region and -applies @code{epa-import-keys-region} to each of them. -@end deffn - -@deffn Command epa-delete-keys allow-secret -Delete selected keys. If @var{allow-secret} is non-@code{nil}, it -also delete the secret keys. -@end deffn - -@node Cryptographic operations on regions -@section Cryptographic operations on regions - -@deffn Command epa-decrypt-region start end -Decrypt the current region between @var{start} and @var{end}. It -replaces the region with the decrypted text. -@end deffn - -@deffn Command epa-decrypt-armor-in-region start end -Decrypt OpenPGP armors in the current region between @var{start} and -@var{end}. The difference from @code{epa-decrypt-region} is that -@code{epa-decrypt-armor-in-region} searches armors in the region -and applies @code{epa-decrypt-region} to each of them. That is, this -command does not alter the original text around armors. -@end deffn - -@deffn Command epa-verify-region start end -Verify the current region between @var{start} and @var{end}. It sends -the verification result to the minibuffer or a popup window. It -replaces the region with the signed text. -@end deffn - -@deffn Command epa-verify-cleartext-in-region -Verify OpenPGP cleartext blocks in the current region between -@var{start} and @var{end}. The difference from -@code{epa-verify-region} is that @code{epa-verify-cleartext-in-region} -searches OpenPGP cleartext blocks in the region and applies -@code{epa-verify-region} to each of them. That is, this command does -not alter the original text around OpenPGP cleartext blocks. -@end deffn - -@deffn Command epa-sign-region start end signers type -Sign the current region between @var{start} and @var{end}. By -default, it creates a cleartext signature. If a prefix argument is -given, it will let you select signing keys, and then a signature -type. -@end deffn - -@deffn Command epa-encrypt-region start end recipients sign signers -Encrypt the current region between @var{start} and @var{end}. It will -let you select recipients. If a prefix argument is given, it will -also ask you whether or not to sign the text before encryption and if -you answered yes, it will let you select the signing keys. -@end deffn - -@node Cryptographic operations on files -@section Cryptographic operations on files - -@deffn Command epa-decrypt-file file &optional output -Decrypt @var{file}. If you do not specify the name @var{output} to -use for the decrypted file, this function prompts for the value to use. -@end deffn - -@deffn Command epa-verify-file file -Verify @var{file}. -@end deffn - -@deffn Command epa-sign-file file signers type -Sign @var{file}. If a prefix argument is given, it will let you -select signing keys, and then a signature type. -@end deffn - -@deffn Command epa-encrypt-file file recipients -Encrypt @var{file}. It will let you select recipients. -@end deffn - -@node Dired integration -@section Dired integration - -EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to -easily do cryptographic operations on files. For example, - -@example -M-x dired -(mark some files) -: e (or M-x epa-dired-do-encrypt) -(select recipients by 'm' and click [OK]) -@end example - -@noindent -The following keys are assigned. - -@table @kbd -@item : d -@kindex @kbd{: d} -@findex epa-dired-do-decrypt -Decrypt marked files. - -@item : v -@kindex @kbd{: v} -@findex epa-dired-do-verify -Verify marked files. - -@item : s -@kindex @kbd{: s} -@findex epa-dired-do-sign -Sign marked files. - -@item : e -@kindex @kbd{: e} -@findex epa-dired-do-encrypt -Encrypt marked files. - -@end table - -@node Mail-mode integration -@section Mail-mode integration - -EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help -user compose inline OpenPGP messages. Inline OpenPGP is a traditional -style of sending signed/encrypted emails by embedding raw OpenPGP -blobs inside a message body, not using modern MIME format. - -NOTE: Inline OpenPGP is not recommended and you should consider to use -PGP/MIME@. See -@uref{http://josefsson.org/inline-openpgp-considered-harmful.html, -Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}. - -@noindent -Once @code{epa-mail-mode} is enabled, the following keys are assigned. -You can do it by @kbd{C-u 1 M-x epa-mail-mode} or through the Customize -interface. Try @kbd{M-x customize-variable epa-global-mail-mode}. - -@table @kbd -@item C-c C-e C-d and C-c C-e d -@kindex @kbd{C-c C-e C-d} -@kindex @kbd{C-c C-e d} -@findex epa-mail-decrypt -Decrypt OpenPGP armors in the current buffer. - -@item C-c C-e C-v and C-c C-e v -@kindex @kbd{C-c C-e C-v} -@kindex @kbd{C-c C-e v} -@findex epa-mail-verify -Verify OpenPGP cleartext signed messages in the current buffer. - -@item C-c C-e C-s and C-c C-e s -@kindex @kbd{C-c C-e C-s} -@kindex @kbd{C-c C-e s} -@findex epa-mail-sign -Compose a signed message from the current buffer. - -@item C-c C-e C-e and C-c C-e e -@kindex @kbd{C-c C-e C-e} -@kindex @kbd{C-c C-e e} -@findex epa-mail-encrypt -@vindex epa-mail-aliases -Compose an encrypted message from the current buffer. -By default it tries to build the recipient list from @samp{to}, -@samp{cc}, and @samp{bcc} fields of the mail header. To include your -key in the recipient list, use @samp{encrypt-to} option in -@file{~/.gnupg/gpg.conf}. This function translates recipient -addresses using the @code{epa-mail-aliases} list. You can also -use that option to ignore specific recipients for encryption purposes. - -@end table - -@node Encrypting/decrypting gpg files -@section Encrypting/decrypting gpg files -By default, every file whose name ends with @file{.gpg} will be -treated as encrypted. That is, when you open such a file, the -decrypted text is inserted in the buffer rather than encrypted one. -Similarly, when you save the buffer to a @file{foo.gpg} file, -encrypted data is written. - -The file name pattern for encrypted files can be controlled by -@var{epa-file-name-regexp}. - -@defvar epa-file-name-regexp -Regexp which matches filenames treated as encrypted. -@end defvar - -You can disable this behavior with @kbd{M-x epa-file-disable}, and -then get it back with @kbd{M-x epa-file-enable}. - -@deffn Command epa-file-disable -Disable automatic encryption/decryption of *.gpg files. -@end deffn - -@deffn Command epa-file-enable -Enable automatic encryption/decryption of *.gpg files. -@end deffn - -@noindent -By default, @code{epa-file} will try to use symmetric encryption, aka -password-based encryption. If you want to use public key encryption -instead, do @kbd{M-x epa-file-select-keys}, which will pops up the key -selection dialog. - -@deffn Command epa-file-select-keys -Select recipient keys to encrypt the currently visiting file with -public key encryption. -@end deffn - -You can also change the default behavior with the variable -@var{epa-file-select-keys}. - -@defvar epa-file-select-keys -Control whether or not to pop up the key selection dialog. -@end defvar - -For frequently visited files, it might be a good idea to tell Emacs -which encryption method should be used through @xref{File Variables, , -, emacs, the Emacs Manual}. Use the @code{epa-file-encrypt-to} local -variable for this. -@vindex epa-file-encrypt-to - -For example, if you want an Elisp file to be encrypted with a -public key associated with an email address @samp{ueno@@unixuser.org}, -add the following line to the beginning of the file. - -@cartouche -@lisp -;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*- -@end lisp -@end cartouche - -Instead, if you want the file always (regardless of the value of the -@code{epa-file-select-keys} variable) encrypted with symmetric -encryption, change the line as follows. - -@cartouche -@lisp -;; -*- epa-file-encrypt-to: nil -*- -@end lisp -@end cartouche - -Other variables which control the automatic encryption/decryption -behavior are below. - -@defvar epa-file-cache-passphrase-for-symmetric-encryption -If non-@code{nil}, cache passphrase for symmetric encryption. The -default value is @code{nil}. -@end defvar - -@defvar epa-file-inhibit-auto-save -If non-@code{nil}, disable auto-saving when opening an encrypted file. -The default value is @code{t}. -@end defvar - -@node Caching Passphrases -@chapter Caching Passphrases - -Typing passphrases is an irritating task if you frequently open and -close the same file. GnuPG and EasyPG Assistant provide mechanisms to -remember your passphrases. However, the configuration is a bit -confusing since it depends on your GnuPG installation (GnuPG version 1 or -GnuPG version 2), encryption method (symmetric or public key), and whether or -not you want to use gpg-agent. Here are some questions: - -@enumerate -@item Do you use GnuPG version 2 instead of GnuPG version 1? -@item Do you use symmetric encryption rather than public key encryption? -@item Do you want to use gpg-agent? -@end enumerate - -Here are configurations depending on your answers: - -@multitable {111} {222} {333} {configuration configuration configuration} -@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration -@item Yes @tab Yes @tab Yes @tab Set up gpg-agent. -@item Yes @tab Yes @tab No @tab You can't, without gpg-agent. -@item Yes @tab No @tab Yes @tab Set up gpg-agent. -@item Yes @tab No @tab No @tab You can't, without gpg-agent. -@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. -@item No @tab Yes @tab No @tab Set up elisp passphrase cache. -@item No @tab No @tab Yes @tab Set up gpg-agent. -@item No @tab No @tab No @tab You can't, without gpg-agent. -@end multitable - -To set up gpg-agent, follow the instruction in GnuPG manual. -@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}. - -To set up elisp passphrase cache, set -@code{epa-file-cache-passphrase-for-symmetric-encryption}. -@xref{Encrypting/decrypting gpg files}. - -@node Bug Reports -@chapter Bug Reports - -Bugs and problems with EasyPG Assistant are actively worked on by the -Emacs development team. Feature requests and suggestions are also -more than welcome. Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, , -Bugs, emacs, Reporting Bugs}. - -When submitting a bug report, please try to describe in excruciating -detail the steps required to reproduce the problem. Also try to -collect necessary information to fix the bug, such as: - -@itemize @bullet -@item the GnuPG version. Send the output of @samp{gpg --version}. -@item the GnuPG configuration. Send the contents of @file{~/.gnupg/gpg.conf}. -@end itemize - -Before reporting the bug, you should set @code{epg-debug} in the -@file{~/.emacs} file and repeat the bug. Then, include the contents -of the @file{ *epg-debug*} buffer. Note that the first letter of the -buffer name is a whitespace. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Key Index -@unnumbered Key Index -@printindex ky - -@node Function Index -@unnumbered Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye - -@c End: diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi deleted file mode 100644 index 4cb5eaed604..00000000000 --- a/doc/misc/erc.texi +++ /dev/null @@ -1,864 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/erc -@settitle ERC Manual -@syncodeindex fn cp -@include emacsver.texi -@documentencoding UTF-8 -@c %**end of header - -@copying -This manual is for ERC as distributed with Emacs @value{EMACSVER}. - -Copyright @copyright{} 2005--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' - -All Emacs Lisp code contained in this document may be used, distributed, -and modified without restriction. -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* ERC: (erc). Powerful and extensible IRC client for Emacs. -@end direntry - -@titlepage -@title ERC manual -@subtitle a full-featured IRC client -@subtitle for Emacs and XEmacs - -@c The following two commands -@c start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top ERC - -@insertcopying -@end ifnottex - -@menu -* Introduction:: What is ERC? -* Getting Started:: Quick Start guide to using ERC. -* Keystroke Summary:: Keystrokes used in ERC buffers. -* Modules:: Available modules for ERC. -* Advanced Usage:: Cool ways of using ERC. -* Getting Help and Reporting Bugs:: -* History:: The history of ERC. -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: Search for terms. - -@detailmenu - --- The Detailed Node Listing --- - -Getting Started - -* Sample Session:: Example of connecting to the #emacs channel -* Special Features:: Differences from standalone IRC clients - -Advanced Usage - -* Connecting:: Ways of connecting to an IRC server. -* Sample Configuration:: An example configuration file. -* Options:: Options that are available for ERC. - -@end detailmenu -@end menu - -@node Introduction -@chapter Introduction - -ERC is a powerful, modular, and extensible IRC client for Emacs. -It is distributed with Emacs since version 22.1. - -It comes with the following capabilities enabled by default. - -@itemize @bullet -@item Flood control -@item Timestamps -@item Join channels automatically -@item Buttonize URLs, nicknames, and other text -@item Wrap long lines -@item Highlight or remove IRC control characters -@item Highlight pals, fools, and other keywords -@item Detect netsplits -@item Complete nicknames and commands in a programmable fashion -@item Make displayed lines read-only -@item Input history -@item Track channel activity in the mode-line - -@end itemize - - -@node Getting Started -@chapter Getting Started -@cindex settings - -The command @kbd{M-x erc} will start ERC and prompt for the server to -connect to. - -If you want to place ERC settings in their own file, you can place them -in @file{~/.emacs.d/.ercrc.el}, creating it if necessary. - -If you would rather use the Customize interface to change how ERC works, -do @kbd{M-x customize-group RET erc RET}. In particular, ERC comes with -lots of modules that may be enabled or disabled; to select which ones -you want, do @kbd{M-x customize-variable RET erc-modules RET}. - -@menu -* Sample Session:: Example of connecting to the #emacs channel -* Special Features:: Differences from standalone IRC clients -@end menu - -@node Sample Session -@section Sample Session - -This is an example ERC session which shows how to connect to the #emacs -channel on Freenode. Another IRC channel on Freenode that may be of -interest is #erc, which is a channel where ERC users and developers hang -out. - -@itemize @bullet - -@item Connect to Freenode - -Run @kbd{M-x erc}. Use ``irc.freenode.net'' as the IRC server, ``6667'' -as the port, and choose a nickname. - -@item Get used to the interface - -Switch to the ``irc.freenode.net:6667'' buffer, if you're not already -there. You will see first some messages about checking for ident, and -then a bunch of other messages that describe the current IRC server. - -@item Join the #emacs channel - -In that buffer, type ``/join @key{SPC} #emacs'' and hit @kbd{RET}. Depending -on how you've set up ERC, either a new buffer for ``#emacs'' will be -displayed, or a new buffer called ``#emacs'' will be created in the -background. If the latter, switch to the ``#emacs'' buffer. You will -see the channel topic and a list of the people who are currently on the -channel. - -@item Register your nickname with Freenode - -If you would like to be able to talk with people privately on the -Freenode network, you will have to ``register'' your nickname. To do -so, switch to the ``irc.freenode.net:6667'' buffer and type ``/msg -NickServ register '', replacing ``'' with your -desired password. It should tell you that the operation was successful. - -@item Talk to people in the channel - -If you switch back to the ``#emacs'' buffer, you can type a message, and -everyone on the channel will see it. - -@item Open a query buffer to talk to someone - -If you want to talk with someone in private (this should usually not be -done for technical help, only for personal questions), type ``/query -'', replacing ``'' with the nickname of the person you would -like to talk to. Depending on how ERC is set up, you will either see a -new buffer with the name of the person, or such a buffer will be created -in the background and you will have to switch to it. Begin typing -messages, and you will be able to have a conversation. - -Note that if the other person is not registered, you will not be able to -talk with them. - -@end itemize - -@node Special Features -@section Special Features - -ERC has some features that distinguish it from some IRC clients. - -@itemize @bullet - -@item multiple channels and multiple servers - -Every channel is put in a separate buffer. Several IRC servers may be -connected to at the same time. - -@cindex query buffers -@item private message separation - -Private conversations are treated as channels, and are put into separate -buffers in Emacs. We call these ``query buffers''. - -@item highlighting - -Some occurrences of words can be highlighted, which makes it easier to -track different kinds of conversations. - -@item notification - -ERC can notify you that certain users are online. - -@item channel tracking - -Channels can be hidden and conversation continue in the background. You -are notified when something is said in such a channel that is not -currently visible. This makes it easy to get Real Work done while still -maintaining an IRC presence. - -@item nick completion - -ERC can complete words upon hitting @kbd{TAB}, which eases the writing -of nicknames in messages. - -@cindex history ring -@item history - -Past actions are kept in history rings for future use. To navigate a -history ring, hit @kbd{M-p} to go backwards and @kbd{M-n} to go -forwards. - -@item multiple languages - -Different channels and servers may have different language encodings. - -multiple languages. Please contact the Emacs developers -if you are interested in helping with the -translation effort. - -@item user scripting - -Users can load scripts (e.g., auto greeting scripts) when ERC starts up. - -It is also possible to make custom IRC commands, if you know a little -Emacs Lisp. Just make an Emacs Lisp function and call it -@code{erc-cmd-NEWCOMMAND}, where @code{NEWCOMMAND} is the name of the -new command in capital letters. - -@item auto reconnect - -If the connection goes away at some point, ERC will try to reconnect -automatically. If it fails to reconnect, and you want to try to -manually reestablish the connection at some later point, switch to an -ERC buffer and run the @code{/RECONNECT} command. - -@end itemize - - -@node Keystroke Summary -@chapter Keys Used in ERC -@cindex keystrokes - -This is a summary of keystrokes available in every ERC buffer. - -@table @kbd - -@item C-a or (`erc-bol') -Go to beginning of line or end of prompt. - -@item RET (`erc-send-current-line') -Send the current line - -@item TAB (`erc-complete-word') -If at prompt, complete the current word. -Otherwise, move to the next link or button. - -@item M-TAB (`ispell-complete-word') -Complete the given word, using ispell. - -@item C-c C-a (`erc-bol') -Go to beginning of line or end of prompt. - -@item C-c C-b (`erc-iswitchb') -Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to. - -@item C-c C-c (`erc-toggle-interpret-controls') -Toggle interpretation of control sequences in messages. - -@item C-c C-d (`erc-input-action') -Interactively input a user action and send it to IRC. - -@item C-c C-e (`erc-toggle-ctcp-autoresponse') -Toggle automatic CTCP replies (like VERSION and PING). - -@item C-c C-f (`erc-toggle-flood-control') -Toggle use of flood control on sent messages. - -@item C-c TAB (`erc-invite-only-mode') -Turn on the invite only mode (+i) for the current channel. - -@item C-c C-j (`erc-join-channel') -Join channel. If point is at the beginning of a channel name, use that -as default. - -@item C-c C-k (`erc-go-to-log-matches-buffer') -Interactively open an erc-log-matches buffer - -@item C-c C-l (`erc-save-buffer-in-logs') -Append buffer contents to the log file, if logging is enabled. - -@item C-c C-n (`erc-channel-names') -Run "/names #channel" in the current channel. - -@item C-c C-o (`erc-get-channel-mode-from-keypress') -Read a key sequence and call the corresponding channel mode function. -After doing @kbd{C-c C-o}, type in a channel mode letter. - -@kbd{C-g} means quit. -@kbd{RET} lets you type more than one mode at a time. -If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called. -If @kbd{k} is pressed, @code{erc-set-channel-key} gets called. -Anything else will be sent to `erc-toggle-channel-mode'. - -@item C-c C-p (`erc-part-from-channel') -Part from the current channel and prompt for a reason. - -@item C-c C-q (`erc-quit-server') -Disconnect from current server after prompting for reason. - -@item C-c C-r (`erc-remove-text-properties-region') -Clears the region (start,end) in object from all colors, etc. - -@item C-c C-t (`erc-set-topic') -Prompt for a topic for the current channel. - -@item C-c C-u (`erc-kill-input') -Kill current input line using `erc-bol' followed by `kill-line'. - -@end table - - -@node Modules -@chapter Modules -@cindex modules - -One way to add functionality to ERC is to customize which of its many -modules are loaded. - -There is a spiffy customize interface, which may be reached by typing -@kbd{M-x customize-option erc-modules RET}. Alternatively, set -@code{erc-modules} manually and then call @code{erc-update-modules}. - -The following is a list of available modules. - -@table @code - -@cindex modules, autoaway -@item autoaway -Set away status automatically - -@cindex modules, autojoin -@item autojoin -Join channels automatically - -@cindex modules, bbdb -@item bbdb -Integrate with the Big Brother Database - -@cindex modules, button -@item button -Buttonize URLs, nicknames, and other text - -@cindex modules, capab-identify -@item capab-identify -Mark unidentified users on freenode and other servers supporting CAPAB. - -@cindex modules, completion -@cindex modules, pcomplete -@item completion (aka pcomplete) -Complete nicknames and commands (programmable) - -@cindex modules, fill -@item fill -Wrap long lines - -@cindex modules, identd -@item identd -Launch an identd server on port 8113 - -@cindex modules, irccontrols -@item irccontrols -Highlight or remove IRC control characters - -@cindex modules, log -@item log -Save buffers in logs - -@cindex modules, match -@item match -Highlight pals, fools, and other keywords - -@cindex modules, menu -@item menu -Display a menu in ERC buffers - -@cindex modules, netsplit -@item netsplit -Detect netsplits - -@cindex modules, noncommands -@item noncommands -Don't display non-IRC commands after evaluation - -@cindex modules, notify -@item notify -Notify when the online status of certain users changes - -@cindex modules, notifications -@item notifications -Send you a notification when you get a private message, -or your nickname is mentioned - -@cindex modules, page -@item page -Process CTCP PAGE requests from IRC - -@cindex modules, readonly -@item readonly -Make displayed lines read-only - -@cindex modules, replace -@item replace -Replace text in messages - -@cindex modules, ring -@item ring -Enable an input history - -@cindex modules, scrolltobottom -@item scrolltobottom -Scroll to the bottom of the buffer - -@cindex modules, services -@item services -Identify to Nickserv (IRC Services) automatically - -@cindex modules, smiley -@item smiley -Convert smileys to pretty icons - -@cindex modules, sound -@item sound -Play sounds when you receive CTCP SOUND requests - -@cindex modules, spelling -@item spelling -Check spelling of messages - -@cindex modules, stamp -@item stamp -Add timestamps to messages - -@cindex modules, track -@item track -Track channel activity in the mode-line - -@cindex modules, truncate -@item truncate -Truncate buffers to a certain size - -@cindex modules, unmorse -@item unmorse -Translate morse code in messages - -@end table - -@c PRE5_4: Document every option of every module in its own subnode - - -@node Advanced Usage -@chapter Advanced Usage -@cindex advanced topics - -@menu -* Connecting:: Ways of connecting to an IRC server. -* Sample Configuration:: An example configuration file. -* Options:: Options that are available for ERC. -@end menu - -@node Connecting -@section Connecting to an IRC Server -@cindex connecting - -The easiest way to connect to an IRC server is to call @kbd{M-x erc}. -If you want to assign this function to a keystroke, the following will -help you figure out its parameters. - -@defun erc -Select connection parameters and run ERC@. -Non-interactively, it takes the following keyword arguments. - -@itemize @bullet -@item @var{server} -@item @var{port} -@item @var{nick} -@item @var{password} -@item @var{full-name} -@end itemize - -That is, if called with the following arguments, @var{server} and -@var{full-name} will be set to those values, whereas -@code{erc-compute-port}, @code{erc-compute-nick} and -@code{erc-compute-full-name} will be invoked for the values of the other -parameters. - -@example -(erc :server "irc.freenode.net" :full-name "Harry S Truman") -@end example -@end defun - -@subheading Server - -@defun erc-compute-server &optional server -Return an IRC server name. - -This tries a number of increasingly more default methods until a non-@code{nil} -value is found. - -@itemize @bullet -@item @var{server} (the argument passed to this function) -@item The @code{erc-server} option -@item The value of the IRCSERVER environment variable -@item The @code{erc-default-server} variable -@end itemize - -@end defun - -@defopt erc-server -IRC server to use if one is not provided. -@end defopt - -@subheading Port - -@defun erc-compute-port &optional port -Return a port for an IRC server. - -This tries a number of increasingly more default methods until a non-@code{nil} -value is found. - -@itemize @bullet -@item @var{port} (the argument passed to this function) -@item The @code{erc-port} option -@item The @code{erc-default-port} variable -@end itemize - -@end defun - -@defopt erc-port -IRC port to use if not specified. - -This can be either a string or a number. -@end defopt - -@subheading Nick - -@defun erc-compute-nick &optional nick -Return user's IRC nick. - -This tries a number of increasingly more default methods until a -non-@code{nil} value is found. - -@itemize -@item @var{nick} (the argument passed to this function) -@item The @code{erc-nick} option -@item The value of the IRCNICK environment variable -@item The result from the @code{user-login-name} function -@end itemize - -@end defun - -@defopt erc-nick -Nickname to use if one is not provided. - -This can be either a string, or a list of strings. -In the latter case, if the first nick in the list is already in use, -other nicks are tried in the list order. -@end defopt - -@defopt erc-nick-uniquifier -The string to append to the nick if it is already in use. -@end defopt - -@defopt erc-try-new-nick-p -If the nickname you chose isn't available, and this option is non-@code{nil}, -ERC should automatically attempt to connect with another nickname. - -You can manually set another nickname with the /NICK command. -@end defopt - -@subheading Password -@cindex password - -@defopt erc-prompt-for-password -If non-@code{nil} (the default), @kbd{M-x erc} prompts for a password. -@end defopt - -If you prefer, you can set this option to @code{nil} and use the -@code{auth-source} mechanism to store your password. For instance, if -you use @file{~/.authinfo} as your auth-source backend, then put -something like the following in that file: - -@example -machine irc.example.net login "#fsf" password sEcReT -@end example - -@noindent -ERC also consults @code{auth-source} to find any channel keys required -for the channels that you wish to autojoin, as specified by the -variable @code{erc-autojoin-channels-alist}. - -For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. - - -@subheading Full name - -@defun erc-compute-full-name &optional full-name -Return user's full name. - -This tries a number of increasingly more default methods until a -non-@code{nil} value is found. - -@itemize @bullet -@item @var{full-name} (the argument passed to this function) -@item The @code{erc-user-full-name} option -@item The value of the IRCNAME environment variable -@item The result from the @code{user-full-name} function -@end itemize - -@end defun - -@defopt erc-user-full-name -User full name. - -This can be either a string or a function to call. -@end defopt - -@node Sample Configuration -@section Sample Configuration -@cindex configuration, sample - -Here is an example of configuration settings for ERC@. This can go into -your Emacs configuration file. Everything after the @code{(require -'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}. - -@lisp -;;; Sample ERC configuration - -;; Add the ERC directory to load path -- you don't need this if you are -;; using the version of ERC that comes with Emacs -(add-to-list 'load-path "~/elisp/erc") - -;; Load ERC -(require 'erc) - -;; Load authentication info from an external source. Put sensitive -;; passwords and the like in here. -(load "~/.emacs.d/.erc-auth") - -;; This is an example of how to make a new command. Type "/uptime" to -;; use it. -(defun erc-cmd-UPTIME (&rest ignore) - "Display the uptime of the system, as well as some load-related -stuff, to the current ERC buffer." - (let ((uname-output - (replace-regexp-in-string - ", load average: " "] @{Load average@} [" - ;; Collapse spaces, remove - (replace-regexp-in-string - " +" " " - ;; Remove beginning and trailing whitespace - (replace-regexp-in-string - "^ +\\|[ \n]+$" "" - (shell-command-to-string "uptime")))))) - (erc-send-message - (concat "@{Uptime@} [" uname-output "]")))) - -;; This causes ERC to connect to the Freenode network upon hitting -;; C-c e f. Replace MYNICK with your IRC nick. -(global-set-key "\C-cef" (lambda () (interactive) - (erc :server "irc.freenode.net" :port "6667" - :nick "MYNICK"))) - -;; This causes ERC to connect to the IRC server on your own machine (if -;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC -;; nick. Often, people like to run bitlbee (http://bitlbee.org/) as an -;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with -;; people on those networks. -(global-set-key "\C-ceb" (lambda () (interactive) - (erc :server "localhost" :port "6667" - :nick "MYNICK"))) - -;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has -;; been commented out to avoid confusing new users. -;; (define-key erc-mode-map (kbd "RET") nil) -;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line) -;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line) - -;;; Options - -;; Join the #emacs and #erc channels whenever connecting to Freenode. -(setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc"))) - -;; Interpret mIRC-style color commands in IRC chats -(setq erc-interpret-mirc-color t) - -;; The following are commented out by default, but users of other -;; non-Emacs IRC clients might find them useful. -;; Kill buffers for channels after /part -;; (setq erc-kill-buffer-on-part t) -;; Kill buffers for private queries after quitting the server -;; (setq erc-kill-queries-on-quit t) -;; Kill buffers for server messages after quitting the server -;; (setq erc-kill-server-buffer-on-quit t) -@end lisp - -@node Options -@section Options -@cindex options - -@c PRE5_4: (Node) Document every ERC option (module options go in -@c previous chapter) - -This section is extremely incomplete. For now, the easiest way to -check out all the available options for ERC is to do -@kbd{M-x customize-group erc RET}. - -@defopt erc-hide-list -If non, @code{nil}, this is a list of IRC message types to hide, e.g.: - -@example -(setq erc-hide-list '("JOIN" "PART" "QUIT")) -@end example -@end defopt - -@defopt erc-lurker-hide-list -Like @code{erc-hide-list}, but only applies to messages sent by -lurkers. The function @code{erc-lurker-p} determines whether a given -nickname is considered a lurker. -@end defopt - - -@node Getting Help and Reporting Bugs -@chapter Getting Help and Reporting Bugs -@cindex help, getting -@cindex bugs, reporting - -After you have read this guide, if you still have questions about ERC, -or if you have bugs to report, there are several places you can go. - -@itemize @bullet - -@item -@uref{http://www.emacswiki.org/cgi-bin/wiki/ERC} is the -emacswiki.org page for ERC@. Anyone may add tips, hints, etc. to it. - -@item -You can ask questions about using ERC on the Emacs mailing list, -@uref{http://lists.gnu.org/mailman/listinfo/help-gnu-emacs}. - -@item -You can visit the IRC Freenode channel @samp{#emacs}. Many of the -contributors are frequently around and willing to answer your -questions. - -@item -To report a bug in ERC, use @kbd{M-x report-emacs-bug}. - -@end itemize - - -@node History -@chapter History -@cindex history, of ERC - -@c abel@@bfr.co.il, sergey.berezin@@cs.cmu.edu -ERC was originally written by Alexander L. Belikoff and Sergey Berezin. -They stopped development around -December 1999. Their last released version was ERC 2.0. - -P.S.: If one of the original developers of ERC reads this, we'd like to -receive additional information for this file and hear comments in -general. - -@itemize -@item 2001 - -@c mlang@@delysid.org, alex@@gnu.org -In June 2001, Mario Lang and Alex Schroeder -took over development and created a ERC Project at -@uref{http://sourceforge.net/projects/erc}. - -In reaction to a mail about the new ERC development effort, Sergey -Berezin said, ``First of all, I'm glad that my version of ERC is being -used out there. The thing is, I do not have free time and enough -incentive anymore to work on ERC, so I would be happy if you guys take -over the project entirely.'' - -So we happily hacked away on ERC, and soon after (September 2001) -released the next "stable" version, 2.1. - -Most of the development of the new ERC happened on #emacs on -irc.openprojects.net. Over time, many people contributed code, ideas, -bugfixes, and a lot of alpha/beta/gamma testing. - -See the @file{CREDITS} file for a list of contributors. - -@item 2003 - -ERC 3.0 was released. - -@item 2004 - -ERC 4.0 was released. - -@item 2005 - -@c mwolson@@gnu.org -ERC 5.0 was released. Michael Olson became -the release manager and eventually the maintainer. - -After some discussion between him and the Emacs developers, it was -decided to include ERC in Emacs. - -@item 2006 - -ERC 5.1 was released. It was subsequently included in Emacs 22. - -ERC became an official GNU project, and development moved to -@uref{http://sv.gnu.org/projects/erc}. We switched to using GNU Arch as -our revision control system. Our mailing list address changed as well. - -@item 2007 - -We switched to using git for our version control system. - -@item 2009+ - -Since about 2009, ERC is no longer developed as a separate project, but -is maintained as part of Emacs. - -@end itemize - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Index - -@printindex cp - -@bye diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi deleted file mode 100644 index ec1614c7140..00000000000 --- a/doc/misc/ert.texi +++ /dev/null @@ -1,879 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/ert -@settitle Emacs Lisp Regression Testing -@documentencoding UTF-8 -@c %**end of header - -@dircategory Emacs misc features -@direntry -* ERT: (ert). Emacs Lisp regression testing tool. -@end direntry - -@copying -Copyright @copyright{} 2008, 2010--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@titlepage -@title Emacs Lisp Regression Testing -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top ERT: Emacs Lisp Regression Testing - -@insertcopying - -ERT is a tool for automated testing in Emacs Lisp. Its main features -are facilities for defining tests, running them and reporting the -results, and for debugging test failures interactively. - -ERT is similar to tools for other environments such as JUnit, but has -unique features that take advantage of the dynamic and interactive -nature of Emacs. Despite its name, it works well both for test-driven -development (see -@url{http://en.wikipedia.org/wiki/Test-driven_development}) and for -traditional software development methods. - -@menu -* Introduction:: A simple example of an ERT test. -* How to Run Tests:: Run tests in Emacs or from the command line. -* How to Write Tests:: How to add tests to your Emacs Lisp code. -* How to Debug Tests:: What to do if a test fails. -* Extending ERT:: ERT is extensible in several ways. -* Other Testing Concepts:: Features not in ERT. -* GNU Free Documentation License:: The license for this documentation. - -@detailmenu - --- The Detailed Node Listing --- - -How to Run Tests - -* Running Tests Interactively:: Run tests in your current Emacs. -* Running Tests in Batch Mode:: Run tests in emacs -Q. -* Test Selectors:: Choose which tests to run. - -How to Write Tests - -* The @code{should} Macro:: A powerful way to express assertions. -* Expected Failures:: Tests for known bugs. -* Tests and Their Environment:: Don't depend on customizations; no side effects. -* Useful Techniques:: Some examples. - -How to Debug Tests - -* Understanding Explanations:: How ERT gives details on why an assertion failed. -* Interactive Debugging:: Tools available in the ERT results buffer. - -Extending ERT - -* Defining Explanation Functions:: Teach ERT about more predicates. -* Low-Level Functions for Working with Tests:: Use ERT's data for your purposes. - -Other Testing Concepts - -* Mocks and Stubs:: Stubbing out code that is irrelevant to the test. -* Fixtures and Test Suites:: How ERT differs from tools for other languages. - -Appendix - -* GNU Free Documentation License:: The license for this documentation. - -@end detailmenu -@end menu -@end ifnottex - -@node Introduction -@chapter Introduction - -ERT allows you to define @emph{tests} in addition to functions, -macros, variables, and the other usual Lisp constructs. Tests are -simply Lisp code: code that invokes other code and checks whether -it behaves as expected. - -ERT keeps track of the tests that are defined and provides convenient -commands to run them to verify whether the definitions that are -currently loaded in Emacs pass the tests. - -Some Lisp files have comments like the following (adapted from the -package @code{pp.el}): - -@lisp -;; (pp-to-string '(quote quote)) ; expected: "'quote" -;; (pp-to-string '((quote a) (quote b))) ; expected: "('a 'b)\n" -;; (pp-to-string '('a 'b)) ; same as above -@end lisp - -The code contained in these comments can be evaluated from time to -time to compare the output with the expected output. ERT formalizes -this and introduces a common convention, which simplifies Emacs -development, since programmers no longer have to manually find and -evaluate such comments. - -An ERT test definition equivalent to the above comments is this: - -@lisp -(ert-deftest pp-test-quote () - "Tests the rendering of `quote' symbols in `pp-to-string'." - (should (equal (pp-to-string '(quote quote)) "'quote")) - (should (equal (pp-to-string '((quote a) (quote b))) "('a 'b)\n")) - (should (equal (pp-to-string '('a 'b)) "('a 'b)\n"))) -@end lisp - -If you know @code{defun}, the syntax of @code{ert-deftest} should look -familiar: This example defines a test named @code{pp-test-quote} that -will pass if the three calls to @code{equal} all return non-@code{nil}. - -@code{should} is a macro with the same meaning as @code{cl-assert} but -better error reporting. @xref{The @code{should} Macro}. - -Each test should have a name that describes what functionality it tests. -Test names can be chosen arbitrarily---they are in a -namespace separate from functions and variables---but should follow -the usual Emacs Lisp convention of having a prefix that indicates -which package they belong to. Test names are displayed by ERT when -reporting failures and can be used when selecting which tests to run. - -The empty parentheses @code{()} in the first line don't currently have -any meaning and are reserved for future extension. They also make -the syntax of @code{ert-deftest} more similar to that of @code{defun}. - -The docstring describes what feature this test tests. When running -tests interactively, the first line of the docstring is displayed for -tests that fail, so it is good if the first line makes sense on its -own. - -The body of a test can be arbitrary Lisp code. It should have as few -side effects as possible; each test should be written to clean up -after itself, leaving Emacs in the same state as it was before the -test. Tests should clean up even if they fail. @xref{Tests and Their -Environment}. - - -@node How to Run Tests -@chapter How to Run Tests - -You can run tests either in the Emacs you are working in, or on the -command line in a separate Emacs process in batch mode (i.e., with no -user interface). The former mode is convenient during interactive -development, the latter is useful to make sure that tests pass -independently of your customizations; and it allows you to invoke -tests from makefiles, and to write scripts that run tests in several -different Emacs versions. - -@menu -* Running Tests Interactively:: Run tests in your current Emacs. -* Running Tests in Batch Mode:: Run tests in emacs -Q. -* Test Selectors:: Choose which tests to run. -@end menu - - -@node Running Tests Interactively -@section Running Tests Interactively - -You can run the tests that are currently defined in your Emacs with -the command @kbd{@kbd{M-x} ert @kbd{RET} t @kbd{RET}}. (For an -explanation of the @code{t} argument, @pxref{Test Selectors}.) ERT will pop -up a new buffer, the ERT results buffer, showing the results of the -tests run. It looks like this: - -@example -Selector: t -Passed: 31 -Skipped: 0 -Failed: 2 (2 unexpected) -Total: 33/33 - -Started at: 2008-09-11 08:39:25-0700 -Finished. -Finished at: 2008-09-11 08:39:27-0700 - -FF............................... - -F addition-test - (ert-test-failed - ((should - (= - (+ 1 2) - 4)) - :form - (= 3 4) - :value nil)) - -F list-test - (ert-test-failed - ((should - (equal - (list 'a 'b 'c) - '(a b d))) - :form - (equal - (a b c) - (a b d)) - :value nil :explanation - (list-elt 2 - (different-atoms c d)))) -@end example - -At the top, there is a summary of the results: we ran all tests defined -in the current Emacs (@code{Selector: t}), 31 of them passed, and 2 -failed unexpectedly. @xref{Expected Failures}, for an explanation of -the term @emph{unexpected} in this context. - -The line of dots and @code{F}s is a progress bar where each character -represents one test; it fills while the tests are running. A dot -means that the test passed, an @code{F} means that it failed. Below -the progress bar, ERT shows details about each test that had an -unexpected result. In the example above, there are two failures, both -due to failed @code{should} forms. @xref{Understanding Explanations}, -for more details. - -In the ERT results buffer, @kbd{TAB} and @kbd{S-TAB} cycle between -buttons. Each name of a function or macro in this buffer is a button; -moving point to it and typing @kbd{RET} jumps to its definition. - -Pressing @kbd{r} re-runs the test near point on its own. Pressing -@kbd{d} re-runs it with the debugger enabled. @kbd{.} jumps to the -definition of the test near point (@kbd{RET} has the same effect if -point is on the name of the test). On a failed test, @kbd{b} shows -the backtrace of the failure. - -@kbd{l} shows the list of @code{should} forms executed in the test. -If any messages were generated (with the Lisp function @code{message}) -in a test or any of the code that it invoked, @kbd{m} will show them. - -By default, long expressions in the failure details are abbreviated -using @code{print-length} and @code{print-level}. Pressing @kbd{L} -while point is on a test failure will increase the limits to show more -of the expression. - - -@node Running Tests in Batch Mode -@section Running Tests in Batch Mode - -ERT supports automated invocations from the command line or from -scripts or makefiles. There are two functions for this purpose, -@code{ert-run-tests-batch} and @code{ert-run-tests-batch-and-exit}. -They can be used like this: - -@example -emacs -batch -l ert -l my-tests.el -f ert-run-tests-batch-and-exit -@end example - -This command will start up Emacs in batch mode, load ERT, load -@code{my-tests.el}, and run all tests defined in it. It will exit -with a zero exit status if all tests passed, or nonzero if any tests -failed or if anything else went wrong. It will also print progress -messages and error diagnostics to standard output. - -If ERT is not part of your Emacs distribution, you may need to use -@code{-L /path/to/ert/} so that Emacs can find it. You may need -additional @code{-L} flags to ensure that @code{my-tests.el} and all the -files that it requires are on your @code{load-path}. - - -@node Test Selectors -@section Test Selectors - -Functions like @code{ert} accept a @emph{test selector}, a Lisp -expression specifying a set of tests. Test selector syntax is similar -to Common Lisp's type specifier syntax: - -@itemize -@item @code{nil} selects no tests. -@item @code{t} selects all tests. -@item @code{:new} selects all tests that have not been run yet. -@item @code{:failed} and @code{:passed} select tests according to their most recent result. -@item @code{:expected}, @code{:unexpected} select tests according to their most recent result. -@item A string is a regular expression that selects all tests with matching names. -@item A test (i.e., an object of @code{ert-test} data type) selects that test. -@item A symbol selects the test that the symbol names. -@item @code{(member TESTS...)} selects the elements of TESTS, a list of -tests or symbols naming tests. -@item @code{(eql TEST)} selects TEST, a test or a symbol naming a test. -@item @code{(and SELECTORS...)} selects the tests that match all SELECTORS. -@item @code{(or SELECTORS...)} selects the tests that match any SELECTOR. -@item @code{(not SELECTOR)} selects all tests that do not match SELECTOR. -@item @code{(tag TAG)} selects all tests that have TAG on their tags list. -(Tags are optional labels you can apply to tests when you define them.) -@item @code{(satisfies PREDICATE)} selects all tests that satisfy PREDICATE, -a function that takes a test as argument and returns non-@code{nil} if -it is selected. -@end itemize - -Selectors that are frequently useful when selecting tests to run -include @code{t} to run all tests that are currently defined in Emacs, -@code{"^foo-"} to run all tests in package @code{foo} (this assumes -that package @code{foo} uses the prefix @code{foo-} for its test names), -result-based selectors such as @code{(or :new :unexpected)} to -run all tests that have either not run yet or that had an unexpected -result in the last run, and tag-based selectors such as @code{(not -(tag :causes-redisplay))} to run all tests that are not tagged -@code{:causes-redisplay}. - - -@node How to Write Tests -@chapter How to Write Tests - -ERT lets you define tests in the same way you define functions. You -can type @code{ert-deftest} forms in a buffer and evaluate them there -with @code{eval-defun} or @code{compile-defun}, or you can save the -file and load it, optionally byte-compiling it first. - -Just like @code{find-function} is only able to find where a function -was defined if the function was loaded from a file, ERT is only able -to find where a test was defined if the test was loaded from a file. - - -@menu -* The @code{should} Macro:: A powerful way to express assertions. -* Expected Failures:: Tests for known bugs. -* Tests and Their Environment:: Don't depend on customizations; no side effects. -* Useful Techniques:: Some examples. -@end menu - -@node The @code{should} Macro -@section The @code{should} Macro - -Test bodies can include arbitrary code; but to be useful, they need to -check whether the code being tested (or @emph{code under test}) -does what it is supposed to do. The macro @code{should} is similar to -@code{cl-assert} from the cl package -(@pxref{Assertions,,, cl, Common Lisp Extensions}), -but analyzes its argument form and records information that ERT can -display to help debugging. - -This test definition - -@lisp -(ert-deftest addition-test () - (should (= (+ 1 2) 4))) -@end lisp - -will produce this output when run via @kbd{M-x ert}: - -@example -F addition-test - (ert-test-failed - ((should - (= - (+ 1 2) - 4)) - :form - (= 3 4) - :value nil)) -@end example - -In this example, @code{should} recorded the fact that (= (+ 1 2) 4) -reduced to (= 3 4) before it reduced to @code{nil}. When debugging why the -test failed, it helps to know that the function @code{+} returned 3 -here. ERT records the return value for any predicate called directly -within @code{should}. - -In addition to @code{should}, ERT provides @code{should-not}, which -checks that the predicate returns @code{nil}, and @code{should-error}, which -checks that the form called within it signals an error. An example -use of @code{should-error}: - -@lisp -(ert-deftest test-divide-by-zero () - (should-error (/ 1 0) - :type 'arith-error)) -@end lisp - -This checks that dividing one by zero signals an error of type -@code{arith-error}. The @code{:type} argument to @code{should-error} -is optional; if absent, any type of error is accepted. -@code{should-error} returns an error description of the error that was -signaled, to allow additional checks to be made. The error -description has the format @code{(ERROR-SYMBOL . DATA)}. - -There is no @code{should-not-error} macro since tests that signal an -error fail anyway, so @code{should-not-error} is effectively the -default. - -@xref{Understanding Explanations}, for more details on what -@code{should} reports. - - -@node Expected Failures -@section Expected Failures - -Some bugs are complicated to fix, or not very important, and are left as -@emph{known bugs}. If there is a test case that triggers the bug and -fails, ERT will alert you of this failure every time you run all -tests. For known bugs, this alert is a distraction. The way to -suppress it is to add @code{:expected-result :failed} to the test -definition: - -@lisp -(ert-deftest future-bug () - "Test `time-forward' with negative arguments. -Since this functionality isn't implemented, the test is known to fail." - :expected-result :failed - (time-forward -1)) -@end lisp - -ERT will still display a small @code{f} in the progress bar as a -reminder that there is a known bug, and will count the test as failed, -but it will be quiet about it otherwise. - -An alternative to marking the test as a known failure this way is to -delete the test. This is a good idea if there is no intent to fix it, -i.e., if the behavior that was formerly considered a bug has become an -accepted feature. - -In general, however, it can be useful to keep tests that are known to -fail. If someone wants to fix the bug, they will have a very good -starting point: an automated test case that reproduces the bug. This -makes it much easier to fix the bug, demonstrate that it is fixed, and -prevent future regressions. - -ERT displays the same kind of alerts for tests that pass unexpectedly -as it displays for unexpected failures. This way, if you make code -changes that happen to fix a bug that you weren't aware of, you will -know to remove the @code{:expected-result} clause of that test and -close the corresponding bug report, if any. - -Since @code{:expected-result} evaluates its argument when the test is -loaded, tests can be marked as known failures only on certain Emacs -versions, specific architectures, etc.: - -@lisp -(ert-deftest foo () - "A test that is expected to fail on Emacs 23 but succeed elsewhere." - :expected-result (if (string-match "GNU Emacs 23[.]" (emacs-version)) - :failed - :passed) - ...) -@end lisp - - -@node Tests and Their Environment -@section Tests and Their Environment - -Sometimes, it doesn't make sense to run a test due to missing -preconditions. A required Emacs feature might not be compiled in, the -function to be tested could call an external binary which might not be -available on the test machine, you name it. In this case, the macro -@code{skip-unless} could be used to skip the test: - -@lisp -(ert-deftest test-dbus () - "A test that checks D-BUS functionality." - (skip-unless (featurep 'dbusbind)) - ...) -@end lisp - -The outcome of running a test should not depend on the current state -of the environment, and each test should leave its environment in the -same state it found it in. In particular, a test should not depend on -any Emacs customization variables or hooks, and if it has to make any -changes to Emacs's state or state external to Emacs (such as the file -system), it should undo these changes before it returns, regardless of -whether it passed or failed. - -Tests should not depend on the environment because any such -dependencies can make the test brittle or lead to failures that occur -only under certain circumstances and are hard to reproduce. Of -course, the code under test may have settings that affect its -behavior. In that case, it is best to make the test @code{let}-bind -all such setting variables to set up a specific configuration for the -duration of the test. The test can also set up a number of different -configurations and run the code under test with each. - -Tests that have side effects on their environment should restore it to -its original state because any side effects that persist after the -test can disrupt the workflow of the programmer running the tests. If -the code under test has side effects on Emacs's current state, such as -on the current buffer or window configuration, the test should create -a temporary buffer for the code to manipulate (using -@code{with-temp-buffer}), or save and restore the window configuration -(using @code{save-window-excursion}), respectively. For aspects of -the state that can not be preserved with such macros, cleanup should -be performed with @code{unwind-protect}, to ensure that the cleanup -occurs even if the test fails. - -An exception to this are messages that the code under test prints with -@code{message} and similar logging; tests should not bother restoring -the @file{*Message*} buffer to its original state. - -The above guidelines imply that tests should avoid calling highly -customizable commands such as @code{find-file}, except, of course, if -such commands are what they want to test. The exact behavior of -@code{find-file} depends on many settings such as -@code{find-file-wildcards}, @code{enable-local-variables}, and -@code{auto-mode-alist}. It is difficult to write a meaningful test if -its behavior can be affected by so many external factors. Also, -@code{find-file} has side effects that are hard to predict and thus -hard to undo: It may create a new buffer or reuse an existing -buffer if one is already visiting the requested file; and it runs -@code{find-file-hook}, which can have arbitrary side effects. - -Instead, it is better to use lower-level mechanisms with simple and -predictable semantics like @code{with-temp-buffer}, @code{insert} or -@code{insert-file-contents-literally}, and to activate any desired mode -by calling the corresponding function directly, after binding the -hook variables to @code{nil}. This avoids the above problems. - - -@node Useful Techniques -@section Useful Techniques when Writing Tests - -Testing simple functions that have no side effects and no dependencies -on their environment is easy. Such tests often look like this: - -@lisp -(ert-deftest ert-test-mismatch () - (should (eql (ert--mismatch "" "") nil)) - (should (eql (ert--mismatch "" "a") 0)) - (should (eql (ert--mismatch "a" "a") nil)) - (should (eql (ert--mismatch "ab" "a") 1)) - (should (eql (ert--mismatch "Aa" "aA") 0)) - (should (eql (ert--mismatch '(a b c) '(a b d)) 2))) -@end lisp - -This test calls the function @code{ert--mismatch} several times with -various combinations of arguments and compares the return value to the -expected return value. (Some programmers prefer @code{(should (eql -EXPECTED ACTUAL))} over the @code{(should (eql ACTUAL EXPECTED))} -shown here. ERT works either way.) - -Here's a more complicated test: - -@lisp -(ert-deftest ert-test-record-backtrace () - (let ((test (make-ert-test :body (lambda () (ert-fail "foo"))))) - (let ((result (ert-run-test test))) - (should (ert-test-failed-p result)) - (with-temp-buffer - (ert--print-backtrace (ert-test-failed-backtrace result)) - (goto-char (point-min)) - (end-of-line) - (let ((first-line (buffer-substring-no-properties - (point-min) (point)))) - (should (equal first-line - " signal(ert-test-failed (\"foo\"))"))))))) -@end lisp - -This test creates a test object using @code{make-ert-test} whose body -will immediately signal failure. It then runs that test and asserts -that it fails. Then, it creates a temporary buffer and invokes -@code{ert--print-backtrace} to print the backtrace of the failed test -to the current buffer. Finally, it extracts the first line from the -buffer and asserts that it matches what we expect. It uses -@code{buffer-substring-no-properties} and @code{equal} to ignore text -properties; for a test that takes properties into account, -@code{buffer-substring} and @code{ert-equal-including-properties} -could be used instead. - -The reason why this test only checks the first line of the backtrace -is that the remainder of the backtrace is dependent on ERT's internals -as well as whether the code is running interpreted or compiled. By -looking only at the first line, the test checks a useful property---that -the backtrace correctly captures the call to @code{signal} that -results from the call to @code{ert-fail}---without being brittle. - -This example also shows that writing tests is much easier if the code -under test was structured with testing in mind. - -For example, if @code{ert-run-test} accepted only symbols that name -tests rather than test objects, the test would need a name for the -failing test, which would have to be a temporary symbol generated with -@code{make-symbol}, to avoid side effects on Emacs's state. Choosing -the right interface for @code{ert-run-tests} allows the test to be -simpler. - -Similarly, if @code{ert--print-backtrace} printed the backtrace to a -buffer with a fixed name rather than the current buffer, it would be -much harder for the test to undo the side effect. Of course, some -code somewhere needs to pick the buffer name. But that logic is -independent of the logic that prints backtraces, and keeping them in -separate functions allows us to test them independently. - -A lot of code that you will encounter in Emacs was not written with -testing in mind. Sometimes, the easiest way to write tests for such -code is to restructure the code slightly to provide better interfaces -for testing. Usually, this makes the interfaces easier to use as -well. - - -@node How to Debug Tests -@chapter How to Debug Tests - -This section describes how to use ERT's features to understand why -a test failed. - - -@menu -* Understanding Explanations:: How ERT gives details on why an assertion failed. -* Interactive Debugging:: Tools available in the ERT results buffer. -@end menu - - -@node Understanding Explanations -@section Understanding Explanations - -Failed @code{should} forms are reported like this: - -@example -F addition-test - (ert-test-failed - ((should - (= - (+ 1 2) - 4)) - :form - (= 3 4) - :value nil)) -@end example - -ERT shows what the @code{should} expression looked like and what -values its subexpressions had: The source code of the assertion was -@code{(should (= (+ 1 2) 4))}, which applied the function @code{=} to -the arguments @code{3} and @code{4}, resulting in the value -@code{nil}. In this case, the test is wrong; it should expect 3 -rather than 4. - -If a predicate like @code{equal} is used with @code{should}, ERT -provides a so-called @emph{explanation}: - -@example -F list-test - (ert-test-failed - ((should - (equal - (list 'a 'b 'c) - '(a b d))) - :form - (equal - (a b c) - (a b d)) - :value nil :explanation - (list-elt 2 - (different-atoms c d)))) -@end example - -In this case, the function @code{equal} was applied to the arguments -@code{(a b c)} and @code{(a b d)}. ERT's explanation shows that -the item at index 2 differs between the two lists; in one list, it is -the atom c, in the other, it is the atom d. - -In simple examples like the above, the explanation is unnecessary. -But in cases where the difference is not immediately apparent, it can -save time: - -@example -F test1 - (ert-test-failed - ((should - (equal x y)) - :form - (equal a a) - :value nil :explanation - (different-symbols-with-the-same-name a a))) -@end example - -ERT only provides explanations for predicates that have an explanation -function registered. @xref{Defining Explanation Functions}. - - -@node Interactive Debugging -@section Interactive Debugging - -Debugging failed tests essentially works the same way as debugging any -other problems with Lisp code. Here are a few tricks specific to -tests: - -@itemize -@item Re-run the failed test a few times to see if it fails in the same way -each time. It's good to find out whether the behavior is -deterministic before spending any time looking for a cause. In the -ERT results buffer, @kbd{r} re-runs the selected test. - -@item Use @kbd{.} to jump to the source code of the test to find out exactly -what it does. Perhaps the test is broken rather than the code -under test. - -@item If the test contains a series of @code{should} forms and you can't -tell which one failed, use @kbd{l}, which shows you the list of all -@code{should} forms executed during the test before it failed. - -@item Use @kbd{b} to view the backtrace. You can also use @kbd{d} to re-run -the test with debugging enabled, this will enter the debugger and show -the backtrace as well; but the top few frames shown there will not be -relevant to you since they are ERT's own debugger hook. @kbd{b} -strips them out, so it is more convenient. - -@item If the test or the code under testing prints messages using -@code{message}, use @kbd{m} to see what messages it printed before it -failed. This can be useful to figure out how far it got. - -@item You can instrument tests for debugging the same way you instrument -@code{defun}s for debugging: go to the source code of the test and -type @kbd{@kbd{C-u} @kbd{C-M-x}}. Then, go back to the ERT buffer and -re-run the test with @kbd{r} or @kbd{d}. - -@item If you have been editing and rearranging tests, it is possible that -ERT remembers an old test that you have since renamed or removed: -renamings or removals of definitions in the source code leave around a -stray definition under the old name in the running process (this is a -common problem in Lisp). In such a situation, hit @kbd{D} to let ERT -forget about the obsolete test. -@end itemize - - -@node Extending ERT -@chapter Extending ERT - -There are several ways to add functionality to ERT. - -@menu -* Defining Explanation Functions:: Teach ERT about more predicates. -* Low-Level Functions for Working with Tests:: Use ERT's data for your purposes. -@end menu - - -@node Defining Explanation Functions -@section Defining Explanation Functions - -The explanation function for a predicate is a function that takes the -same arguments as the predicate and returns an @emph{explanation}. -The explanation should explain why the predicate, when invoked with -the arguments given to the explanation function, returns the value -that it returns. The explanation can be any object but should have a -comprehensible printed representation. If the return value of the -predicate needs no explanation for a given list of arguments, the -explanation function should return @code{nil}. - -To associate an explanation function with a predicate, add the -property @code{ert-explainer} to the symbol that names the predicate. -The value of the property should be the symbol that names the -explanation function. - - -@node Low-Level Functions for Working with Tests -@section Low-Level Functions for Working with Tests - -Both @code{ert-run-tests-interactively} and @code{ert-run-tests-batch} -are implemented on top of the lower-level test handling code in the -sections of @file{ert.el} labeled ``Facilities for running a single test'', -``Test selectors'', and ``Facilities for running a whole set of tests''. - -If you want to write code that works with ERT tests, you should take a -look at this lower-level code. Symbols that start with @code{ert--} -are internal to ERT, whereas those that start with @code{ert-} are -meant to be usable by other code. But there is no mature API yet. - -Contributions to ERT are welcome. - - -@node Other Testing Concepts -@chapter Other Testing Concepts - -For information on mocks, stubs, fixtures, or test suites, see below. - - -@menu -* Mocks and Stubs:: Stubbing out code that is irrelevant to the test. -* Fixtures and Test Suites:: How ERT differs from tools for other languages. -@end menu - -@node Mocks and Stubs -@section Other Tools for Emacs Lisp - -Stubbing out functions or using so-called @emph{mocks} can make it -easier to write tests. See -@url{http://en.wikipedia.org/wiki/Mock_object} for an explanation of -the corresponding concepts in object-oriented languages. - -ERT does not have built-in support for mocks or stubs. The package -@code{el-mock} (see @url{http://www.emacswiki.org/emacs/el-mock.el}) -offers mocks for Emacs Lisp and can be used in conjunction with ERT. - - -@node Fixtures and Test Suites -@section Fixtures and Test Suites - -In many ways, ERT is similar to frameworks for other languages like -SUnit or JUnit. However, two features commonly found in such -frameworks are notably absent from ERT: fixtures and test suites. - -Fixtures are mainly used (e.g., in SUnit or JUnit) to provide an -environment for a set of tests, and consist of set-up and tear-down -functions. - -While fixtures are a useful syntactic simplification in other -languages, this does not apply to Lisp, where higher-order functions -and `unwind-protect' are available. One way to implement and use a -fixture in ERT is - -@lisp -(defun my-fixture (body) - (unwind-protect - (progn [set up] - (funcall body)) - [tear down])) - -(ert-deftest my-test () - (my-fixture - (lambda () - [test code]))) -@end lisp - -(Another way would be a @code{with-my-fixture} macro.) This solves -the set-up and tear-down part, and additionally allows any test -to use any combination of fixtures, so it is more flexible than what -other tools typically allow. - -If the test needs access to the environment the fixture sets up, the -fixture can be modified to pass arguments to the body. - -These are well-known Lisp techniques. Special syntax for them could -be added but would provide only a minor simplification. - -(If you are interested in such syntax, note that splitting set-up and -tear-down into separate functions, like *Unit tools usually do, makes -it impossible to establish dynamic `let' bindings as part of the -fixture. So, blindly imitating the way fixtures are implemented in -other languages would be counter-productive in Lisp.) - -The purpose of test suites is to group related tests together. - -The most common use of this is to run just the tests for one -particular module. Since symbol prefixes are the usual way of -separating module namespaces in Emacs Lisp, test selectors already -solve this by allowing regexp matching on test names; e.g., the -selector "^ert-" selects ERT's self-tests. - -Other uses include grouping tests by their expected execution time, -e.g., to run quick tests during interactive development and slow tests less -often. This can be achieved with the @code{:tag} argument to -@code{ert-deftest} and @code{tag} test selectors. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye - -@c LocalWords: ERT JUnit namespace docstring ERT's -@c LocalWords: backtrace makefiles workflow backtraces API SUnit -@c LocalWords: subexpressions diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi deleted file mode 100644 index e7c3c71afd8..00000000000 --- a/doc/misc/eshell.texi +++ /dev/null @@ -1,1231 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/eshell -@settitle Eshell: The Emacs Shell -@defindex cm -@synindex vr fn -@documentencoding UTF-8 -@c %**end of header - -@copying -This manual is for Eshell, the Emacs shell. - -Copyright @copyright{} 1999--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Eshell: (eshell). A command shell implemented in Emacs Lisp. -@end direntry - -@titlepage -@sp 4 -@c The title is printed in a large font. -@center @titlefont{User's Guide} -@sp 1 -@center @titlefont{to} -@sp 1 -@center @titlefont{Eshell: The Emacs Shell} -@ignore -@sp 2 -@center release 2.4 -@c -release- -@end ignore -@sp 3 -@center John Wiegley & Aidan Gauland -@c -date- - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c ================================================================ -@c The real text starts here -@c ================================================================ - -@ifnottex -@node Top -@top Eshell - -Eshell is a shell-like command interpreter implemented in Emacs Lisp. -It invokes no external processes except for those requested by the -user. It is intended to be an alternative to the IELM (@pxref{Lisp Interaction, Emacs Lisp Interaction, , emacs, The Emacs Editor}) -REPL for Emacs @emph{and} with an interface similar to command shells -such as @command{bash}, @command{zsh}, @command{rc}, or -@command{4dos}. -@c This manual is updated to release 2.4 of Eshell. - -@insertcopying -@end ifnottex - -@menu -* Introduction:: A brief introduction to the Emacs Shell. -* Commands:: -* Expansion:: -* Input/Output:: -* Extension modules:: -* Bugs and ideas:: Known problems, and future ideas. -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: -* Function and Variable Index:: -* Command Index:: -* Key Index:: -@end menu - -@node Introduction -@chapter Introduction -@section What is Eshell? -@cindex what is Eshell? -@cindex Eshell, what it is - -Eshell is a @dfn{command shell} written in Emacs Lisp. Everything it -does, it uses Emacs's facilities to do. This means that Eshell is as -portable as Emacs itself. It also means that cooperation with Lisp code -is natural and seamless. - -What is a command shell? To properly understand the role of a shell, -it's necessary to visualize what a computer does for you. Basically, a -computer is a tool; in order to use that tool, you must tell it what to -do---or give it ``commands.'' These commands take many forms, such as -clicking with a mouse on certain parts of the screen. But that is only -one form of command input. - -By far the most versatile way to express what you want the computer to -do is by using an abbreviated language called @dfn{script}. In -script, instead of telling the computer, ``list my files, please'', -one writes a standard abbreviated command word---@samp{ls}. Typing -@samp{ls} in a command shell is a script way of telling the computer -to list your files.@footnote{This is comparable to viewing the -contents of a folder using a graphical display.} - -The real flexibility of this approach is apparent only when you realize -that there are many, many different ways to list files. Perhaps you -want them sorted by name, sorted by date, in reverse order, or grouped -by type. Most graphical browsers have simple ways to express this. But -what about showing only a few files, or only files that meet a certain -criteria? In very complex and specific situations, the request becomes -too difficult to express using a mouse or pointing device. It is just -these kinds of requests that are easily solved using a command shell. - -For example, what if you want to list every Word file on your hard -drive, larger than 100 kilobytes in size, and which hasn't been looked -at in over six months? That is a good candidate list for deletion, when -you go to clean up your hard drive. But have you ever tried asking your -computer for such a list? There is no way to do it! At least, not -without using a command shell. - -The role of a command shell is to give you more control over what your -computer does for you. Not everyone needs this amount of control, and -it does come at a cost: Learning the necessary script commands to -express what you want done. A complicated query, such as the example -above, takes time to learn. But if you find yourself using your -computer frequently enough, it is more than worthwhile in the long run. -Any tool you use often deserves the time spent learning to master it. -@footnote{For the understandably curious, here is what that command -looks like: But don't let it fool you; once you know what's going on, -it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.} - -@section What Eshell is not -@cindex Eshell, what it is not -@cindex what Eshell is not -@cindex what isn't Eshell? - -Eshell is @emph{not} a replacement for system shells such as -@command{bash} or @command{zsh}. Use Eshell when you want to move -text between Emacs and external processes; if you only want to pipe -output from one external process to another (and then another, and so -on), use a system shell, because Emacs's IO system is buffer oriented, -not stream oriented, and is very inefficient at such tasks. If you -want to write shell scripts in Eshell, don't; either write an elisp -library or use a system shell. - -Some things Eshell just doesn't do well. It fills the niche between -IELM and your system shell, where the peculiar use-cases lie, and it -is less than ideal outside that niche. - -@menu -* Contributors to Eshell:: People who have helped out! -@end menu - -@node Contributors to Eshell -@section Contributors to Eshell -@cindex contributors -@cindex authors - -Contributions to Eshell are welcome. I have limited time to work on -this project, but I will gladly add any code you contribute to me to -this package. - -The following persons have made contributions to Eshell. - -@itemize @bullet -@item -Eli Zaretskii made it possible for Eshell to run without requiring -asynchronous subprocess support. This is important for MS-DOS, which -does not have such support. - -@item -Miles Bader contributed many fixes during the port to Emacs 21. - -@item -Stefan Monnier fixed the things which bothered him, which of course made -things better for all. - -@item -Gerd Moellmann also helped to contribute bug fixes during the initial -integration with Emacs 21. - -@item -Alex Schroeder contributed code for interactively querying the user -before overwriting files. - -@item -Sudish Joseph helped with some XEmacs compatibility issues. -@end itemize - -Apart from these, a lot of people have sent suggestions, ideas, -requests, bug reports and encouragement. Thanks a lot! Without you -there would be no new releases of Eshell. - -@node Commands -@chapter Commands - -In a command shell, everything is done by invoking commands. This -chapter covers command invocations in Eshell, including the command -history and invoking commands in a script file. - -@menu -* Invocation:: -* Arguments:: -* Built-ins:: -* Variables:: -* Aliases:: -* History:: -* Completion:: -* for loop:: -* Scripts:: -@end menu - -@node Invocation -@section Invocation -Unlike regular system shells, Eshell never invokes kernel functions -directly, such as @code{exec(3)}. Instead, it uses the Lisp functions -available in the Emacs Lisp library. It does this by transforming the -input line into a callable Lisp form.@footnote{To see the Lisp form that will be invoked, type: @samp{eshell-parse-command "echo hello"}} - -The command can be either an Elisp function or an external command. -Eshell looks first for an @ref{Aliases, alias} with the same name as the -command, then a @ref{Built-ins, built-in command} or a function with the -same name; if there is no match, it then tries to execute it as an -external command. - -The semicolon (@code{;}) can be used to separate multiple command -invocations on a single line. A command invocation followed by an -ampersand (@code{&}) will be run in the background. Eshell has no job -control, so you can not suspend or background the current process, or -bring a background process into the foreground. That said, background -processes invoked from Eshell can be controlled the same way as any -other background process in Emacs. - -@node Arguments -@section Arguments -Command arguments are passed to the functions as either strings or -numbers, depending on what the parser thinks they look like. If you -need to use a function that takes some other data type, you will need to -call it in an Elisp expression (which can also be used with -@ref{Expansion, expansions}). As with other shells, you can -escape special characters and spaces with the backslash (@code{\}) and -the single (@code{''}) and double (@code{""}) quotes. - -@node Built-ins - -@section Built-in commands -Several commands are built-in in Eshell. In order to call the -external variant of a built-in command @code{foo}, you could call -@code{*foo}. Usually, this should not be necessary. You can check -what will be applied by the @code{which} command: - -@example -~ $ which ls -eshell/ls is a compiled Lisp function in `em-ls.el' -~ $ which *ls -/bin/ls -@end example - -If you want to discard a given built-in command, you could declare an -alias, @ref{Aliases}. Example: - -@example -~ $ which sudo -eshell/sudo is a compiled Lisp function in `em-unix.el' -~ $ alias sudo '*sudo $*' -~ $ which sudo -sudo is an alias, defined as "*sudo $*" -@end example - -@vindex eshell-prefer-lisp-functions -If you would prefer to use the built-in commands instead of the external -commands, set @code{eshell-prefer-lisp-functions} to @code{t}. - -Some of the built-in commands have different behavior from their -external counterparts, and some have no external counterpart. Most of -these will print a usage message when given the @code{--help} option. - -@table @code - -@item addpath -@cmindex addpath -Adds a given path or set of paths to the PATH environment variable, or, -with no arguments, prints the current paths in this variable. - -@item alias -@cmindex alias -Define an alias (@pxref{Aliases}). This does not add it to the aliases -file. - -@item date -@cmindex date -Similar to, but slightly different from, the GNU Coreutils -@command{date} command. - -@item define -@cmindex define -Define a varalias. -@xref{Variable Aliases, , , elisp, The Emacs Lisp Reference Manual}. - -@item diff -@cmindex diff -Use Emacs's internal @code{diff} (not to be confused with -@code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs Manual}. - -@item grep -@cmindex grep -@itemx agrep -@cmindex agrep -@itemx egrep -@cmindex egrep -@itemx fgrep -@cmindex fgrep -@itemx glimpse -@cmindex glimpse -The @command{grep} commands are compatible with GNU @command{grep}, but -use Emacs's internal @code{grep} instead. - -@item info -@cmindex info -Same as the external @command{info} command, but uses Emacs's internal -Info reader. - -@item jobs -@cmindex jobs -List subprocesses of the Emacs process, if any, using the function -@code{list-processes}. - -@item kill -@cmindex kill -Kill processes. Takes a PID or a process object and an optional -signal specifier. - -@item listify -@cmindex listify -Eshell version of @code{list}. Allows you to create a list using Eshell -syntax, rather than Elisp syntax. For example, @samp{listify foo bar} -and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}. - -@item locate -@cmindex locate -Alias to Emacs's @code{locate} function, which simply runs the external -@command{locate} command and parses the results. -@xref{Dired and Find, , , emacs, The GNU Emacs Manual}. - -@item make -@cmindex make -Run @command{make} through @code{compile}. -@xref{Compilation, , , emacs, The GNU Emacs Manual}. - -@item occur -@cmindex occur -Alias to Emacs's @code{occur}. -@xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}. - -@item printnl -@cmindex printnl -Print the arguments separated by newlines. - -@item cd -@cmindex cd -This command changes the current working directory. Usually, it is -invoked as @samp{cd foo} where @file{foo} is the new working directory. -But @command{cd} knows about a few special arguments: - -When it receives no argument at all, it changes to the home directory. - -Giving the command @samp{cd -} changes back to the previous working -directory (this is the same as @samp{cd $-}). - -The command @samp{cd =} shows the directory stack. Each line is -numbered. - -With @samp{cd =foo}, Eshell searches the directory stack for a directory -matching the regular expression @samp{foo} and changes to that -directory. - -With @samp{cd -42}, you can access the directory stack by number. - -@item su -@cmindex su -@itemx sudo -@cmindex sudo -Uses TRAMP's @command{su} or @command{sudo} method @pxref{Inline methods, , , tramp} -to run a command via @command{su} or @command{sudo}. These commands -are in the eshell-tramp module, which is disabled by default. - -@end table - -@subsection Built-in variables -Eshell knows a few built-in variables: - -@table @code - -@item $+ -@vindex $+ -This variable always contains the current working directory. - -@item $- -@vindex $- -This variable always contains the previous working directory (the -current working directory from before the last @code{cd} command). - -@item $_ -@vindex $_ -It refers to the last argument of the last command. - -@item $$ -@vindex $$ -This is the result of the last command. In case of an external -command, it is @code{t} or @code{nil}. - -@item $? -@vindex $? -This variable contains the exit code of the last command (0 or 1 for -Lisp functions, based on successful completion). - -@end table - -@node Variables -@section Variables -Since Eshell is just an Emacs REPL@footnote{Read-Eval-Print Loop}, it -does not have its own scope, and simply stores variables the same you -would in an Elisp program. Eshell provides a command version of -@code{setq} for convenience. - -@node Aliases -@section Aliases - -Aliases are commands that expand to a longer input line. For example, -@command{ll} is a common alias for @code{ls -l}, and would be defined -with the command invocation @samp{alias ll ls -l}; with this defined, -running @samp{ll foo} in Eshell will actually run @samp{ls -l foo}. -Aliases defined (or deleted) by the @command{alias} command are -automatically written to the file named by @code{eshell-aliases-file}, -which you can also edit directly (although you will have to manually -reload it). - -@node History -@section History -@cmindex history -The @samp{history} command shows all commands kept in the history ring -as numbered list. If the history ring contains -@code{eshell-history-size} commands, those numbers change after every -command invocation, therefore the @samp{history} command shall be -applied before using the expansion mechanism with history numbers. - -The n-th entry of the history ring can be applied with the @samp{!n} -command. If @code{n} is negative, the entry is counted from the end -of the history ring. - -@samp{!foo} expands to the last command beginning with @code{foo}, and -@samp{!?foo} to the last command containing @code{foo}. The n-th -argument of the last command beginning with @code{foo} is accessible -by @code{!foo:n}. - -The history ring is loaded from a file at the start of every session, -and written back to the file at the end of every session. The file path -is specified in @code{eshell-history-file-name}. Unlike other shells, -such as Bash, Eshell can not be configured to keep a history ring of a -different size than that of the history file. - -Since the default buffer navigation and searching key-bindings are -still present in the Eshell buffer, the commands for history -navigation and searching are bound to different keys: - -@table @kbd -@item M-r -@itemx M-s -History I-search. - -@item M-p -@itemx M-n -Previous and next history line. If there is anything on the input -line when you run these commands, they will instead jump to the -precious or next line that begins with that string. -@end table - -@node Completion -@section Completion -Eshell uses the pcomplete package for programmable completion, similar -to that of other command shells. Argument completion differs depending -on the preceding command: for example, possible completions for -@command{rmdir} are only directories, while @command{rm} completions can -be directories @emph{and} files. Eshell provides predefined completions -for the built-in functions and some common external commands, and you -can define your own for any command. - -Eshell completion also works for lisp forms and glob patterns. If the -point is on a lisp form, then @key{TAB} will behave similarly to completion -in @code{elisp-mode} and @code{lisp-interaction-mode}. For glob -patterns, If there are few enough possible completions of the patterns, -they will be cycled when @key{TAB} is pressed, otherwise it will be removed -from the input line and the possible completions will be listed. - -If you want to see the entire list of possible completions when it's -below the cycling threshold, press @kbd{M-?}. - -@subsection pcomplete -Pcomplete, short for programmable completion, is the completion -library originally written for Eshell, but usable for command -completion@footnote{Command completion as opposed to code completion, -which is a beyond the scope of pcomplete.} in other modes. - -Completions are defined as functions (with @code{defun}) named -@code{pcomplete/COMMAND}, where @code{COMMAND} is the name of the -command for which this function provides completions; you can also name -the function @code{pcomplete/MAJOR-MODE/COMMAND} to define completions -for a specific major mode. - -@node for loop -@section @code{for} loop -Because Eshell commands can not (easily) be combined with lisp forms, -Eshell provides a command-oriented @command{for}-loop for convenience. -The syntax is as follows: - -@example -@code{for VAR in TOKENS @{ command invocation(s) @}} -@end example - -where @samp{TOKENS} is a space-separated sequence of values of -@var{VAR} for each iteration. This can even be the output of a -command if @samp{TOKENS} is replaced with @samp{@{ command invocation @}}. - -@node Scripts -@section Scripts -@cmindex source -@fnindex eshell-source-file -You can run Eshell scripts much like scripts for other shells; the main -difference is that since Eshell is not a system command, you have to run -it from within Emacs. An Eshell script is simply a file containing a -sequence of commands, as with almost any other shell script. Scripts -are invoked from Eshell with @command{source}, or from anywhere in Emacs -with @code{eshell-source-file}. - -@cmindex . -If you wish to load a script into your @emph{current} environment, -rather than in a subshell, use the @code{.} command. - -@node Expansion -@chapter Expansion -Expansion in a command shell is somewhat like macro expansion in macro -parsers (such as @command{cpp} and @command{m4}), but in a command -shell, they are less often used for constants, and usually for using -variables and string manipulation.@footnote{Eshell has no -string-manipulation expansions because the Elisp library already -provides many functions for this.} For example, @code{$var} on a line -expands to the value of the variable @code{var} when the line is -executed. Expansions are usually passed as arguments, but may also be -used as commands.@footnote{E.g., entering just @samp{$var} at the prompt -is equivalent to entering the value of @code{var} at the prompt.} - -@menu -* Dollars Expansion:: -* Globbing:: -@end menu - -@node Dollars Expansion -@section Dollars Expansion -Eshell has different @code{$} expansion syntax from other shells. There -are some similarities, but don't let these lull you into a false sense -of familiarity. - -@table @code - -@item $var -Expands to the value bound to @code{var}. This is the main way to use -variables in command invocations. - -@item $#var -Expands to the length of the value bound to @code{var}. Raises an error -if the value is not a sequence -(@pxref{Sequences Arrays Vectors, Sequences, , elisp, The Emacs Lisp Reference Manual}). - -@item $(lisp) -Expands to the result of evaluating the S-expression @code{(lisp)}. On -its own, this is identical to just @code{(lisp)}, but with the @code{$}, -it can be used in a string, such as @samp{/some/path/$(lisp).txt}. - -@item $@{command@} -Returns the output of @command{command}, which can be any valid Eshell -command invocation, and may even contain expansions. - -@item $var[i] -Expands to the @code{i}th element of the value bound to @code{var}. If -the value is a string, it will be split at whitespace to make it a list. -Again, raises an error if the value is not a sequence. - -@item $var[: i] -As above, but now splitting occurs at the colon character. - -@item $var[: i j] -As above, but instead of returning just a string, it now returns a list -of two strings. If the result is being interpolated into a larger -string, this list will be flattened into one big string, with each -element separated by a space. - -@item $var["\\\\" i] -Separate on backslash characters. Actually, the first argument -- if it -doesn't have the form of a number, or a plain variable name -- can be -any regular expression. So to split on numbers, use @samp{$var["[0-9]+" 10 20]}. - -@item $var[hello] -Calls @code{assoc} on @code{var} with @code{"hello"}, expecting it to be -an alist (@pxref{Association List Type, Association Lists, , elisp, -The Emacs Lisp Reference Manual}). - -@item $#var[hello] -Returns the length of the cdr of the element of @code{var} who car is equal -to @code{"hello"}. - -@end table - -@node Globbing -@section Globbing -Eshell's globbing syntax is very similar to that of Zsh. Users coming -from Bash can still use Bash-style globbing, as there are no -incompatibilities. Most globbing is pattern-based expansion, but there -is also predicate-based expansion. See -@ref{Filename Generation, , , zsh, The Z Shell Manual} -for full syntax. To customize the syntax and behavior of globbing in -Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs, -The GNU Emacs Manual}.} -groups ``eshell-glob'' and ``eshell-pred''. - -@node Input/Output -@chapter Input/Output -Since Eshell does not communicate with a terminal like most command -shells, IO is a little different. - -@section Visual Commands -If you try to run programs from within Eshell that are not -line-oriented, such as programs that use ncurses, you will just get -garbage output, since the Eshell buffer is not a terminal emulator. -Eshell solves this problem by running such programs in Emacs's -terminal emulator. - -Programs that need a terminal to display output properly are referred -to in this manual as ``visual commands,'' because they are not simply -line-oriented. You must tell Eshell which commands are visual, by -adding them to @code{eshell-visual-commands}; for commands that are -visual for only certain @emph{sub}-commands -- e.g. @samp{git log} but -not @samp{git status} -- use @code{eshell-visual-subcommands}; and for -commands that are visual only when passed certain options, use -@code{eshell-visual-options}. - -@section Redirection -Redirection is mostly the same in Eshell as it is in other command -shells. The output redirection operators @code{>} and @code{>>} as -well as pipes are supported, but there is not yet any support for -input redirection. Output can also be redirected to buffers, using -the @code{>>>} redirection operator, and Elisp functions, using -virtual devices. - -The buffer redirection operator, @code{>>>}, expects a buffer object -on the right-hand side, into which it inserts the output of the -left-hand side. e.g., @samp{echo hello >>> #} -inserts the string @code{"hello"} into the @file{*scratch*} buffer. - -@code{eshell-virtual-targets} is a list of mappings of virtual device -names to functions. Eshell comes with two virtual devices: -@file{/dev/kill}, which sends the text to the kill ring, and -@file{/dev/clip}, which sends text to the clipboard. - -You can, of course, define your own virtual targets. They are defined -by adding a list of the form @samp{("/dev/name" @var{function} @var{mode})} to -@code{eshell-virtual-targets}. The first element is the device name; -@var{function} may be either a lambda or a function name. If -@var{mode} is @code{nil}, then the function is the output function; if it is -non-@code{nil}, then the function is passed the redirection mode as a -symbol--@code{overwrite} for @code{>}, @code{append} for @code{>>}, or -@code{insert} for @code{>>>}--and the function is expected to return -the output function. - -The output function is called once on each line of output until -@code{nil} is passed, indicating end of output. - -@node Extension modules -@chapter Extension modules -Eshell provides a facility for defining extension modules so that they -can be disabled and enabled without having to unload and reload them, -and to provide a common parent Customize group for the -modules.@footnote{ERC provides a similar module facility.} An Eshell -module is defined the same as any other library but one requirement: the -module must define a Customize@footnote{@xref{Customization, , , -elisp, The Emacs Lisp Reference Manual}.} -group using @code{eshell-defgroup} (in place of @code{defgroup}) with -@code{eshell-module} as the parent group.@footnote{If the module has -no user-customizable options, then there is no need to define it as an -Eshell module.} You also need to load the following as shown: - -@example -(eval-when-compile - (require 'cl-lib) - (require 'esh-mode) - (require 'eshell)) - -(require 'esh-util) -@end example - -@menu -* Writing a module:: -* Module testing:: -* Directory handling:: -* Key rebinding:: -* Smart scrolling:: -* Terminal emulation:: -@end menu - -@node Writing a module -@section Writing a module - -@node Module testing -@section Module testing - -@node Directory handling -@section Directory handling - -@node Key rebinding -@section Key rebinding - -@node Smart scrolling -@section Smart scrolling - -@node Terminal emulation -@section Terminal emulation - -@node Bugs and ideas -@chapter Bugs and ideas -@cindex reporting bugs and ideas -@cindex bugs, how to report them -@cindex author, how to reach -@cindex email to the author -@cindex FAQ -@cindex problems, list of common -@cindex known bugs -@cindex bugs, known - -If you find a bug or misfeature, don't hesitate to report it, by -using @kbd{M-x report-emacs-bug}. The same applies to feature requests. -It is best to discuss one thing at a time. If you find several -unrelated bugs, please report them separately. - -@ignore -If you have ideas for improvements, or if you have written some -extensions to this package, I would like to hear from you. I hope you -find this package useful! -@end ignore - -Below is a list of some known problems with Eshell version 2.4.2, -which is the version included with Emacs 22. - -@table @asis -@item Documentation incomplete - -@item Differentiate between aliases and functions - -Allow for a Bash-compatible syntax, such as: - -@example -alias arg=blah -function arg () @{ blah $* @} -@end example - -@item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt - -In fact, piping to a process from a looping construct doesn't work in -general. If I change the call to @code{eshell-copy-handles} in -@code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems -to work, but the output occurs after the prompt is displayed. The whole -structured command thing is too complicated at present. - -@item Error with @command{bc} in @code{eshell-test} - -On some XEmacs system, the subprocess interaction test fails -inexplicably, although @command{bc} works fine at the command prompt. - -@item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+ - -In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that -multiple instances of the @file{*Help*} buffer can exist. - -@item Pcomplete sometimes gets stuck - -You press @key{TAB}, but no completions appear, even though the -directory has matching files. This behavior is rare. - -@item @samp{grep python $} doesn't work, but using @samp{*grep} does - -This happens because the @code{grep} Lisp function returns immediately, -and then the asynchronous @command{grep} process expects to examine the -temporary file, which has since been deleted. - -@item Problem with C-r repeating text - -If the text @emph{before point} reads "./run", and you type @kbd{C-r r u -n}, it will repeat the line for every character typed. - -@item Backspace doesn't scroll back after continuing (in smart mode) - -Hitting space during a process invocation, such as @command{make}, will -cause it to track the bottom of the output; but backspace no longer -scrolls back. - -@item It's not possible to fully @code{unload-feature} Eshell - -@item Menu support was removed, but never put back - -@item Using C-p and C-n with rebind gets into a locked state - -This happened a few times in Emacs 21, but has been irreproducible -since. - -@item If an interactive process is currently running, @kbd{M-!} doesn't work - -@item Use a timer instead of @code{sleep-for} when killing child processes - -@item Piping to a Lisp function is not supported - -Make it so that the Lisp command on the right of the pipe is repeatedly -called with the input strings as arguments. This will require changing -@code{eshell-do-pipeline} to handle non-process targets. - -@item Input redirection is not supported - -See the above entry. - -@item Problem running @command{less} without arguments on Windows - -The result in the Eshell buffer is: - -@example -Spawning child process: invalid argument -@end example - -Also a new @command{less} buffer was created with nothing in it@dots{} -(presumably this holds the output of @command{less}). - -If @command{less.exe} is invoked from the Eshell command line, the -expected output is written to the buffer. - -Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el -package and the supplied shell both use the @command{cmdproxy} program -for running shells. - -@item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp} - -@item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be - -@item @samp{mv @var{dir} @var{file}.tar} does not remove directories - -This is because the tar option --remove-files doesn't do so. Should it -be Eshell's job? - -@item Bind @code{standard-output} and @code{standard-error} - -This would be so that if a Lisp function calls @code{print}, everything -will happen as it should (albeit slowly). - -@item When an extension module fails to load, @samp{cd /} gives a Lisp error - -@item If a globbing pattern returns one match, should it be a list? - -@item Make sure syntax table is correct in Eshell mode - -So that @kbd{M-DEL} acts in a predictable manner, etc. - -@item Allow all Eshell buffers to share the same history and list-dir - -@item There is a problem with script commands that output to @file{/dev/null} - -If a script file, somewhere in the middle, uses @samp{> /dev/null}, -output from all subsequent commands is swallowed. - -@item Split up parsing of text after @samp{$} in @file{esh-var.el} - -Make it similar to the way that @file{esh-arg.el} is structured. -Then add parsing of @samp{$[?\n]}. - -@item After pressing @kbd{M-RET}, redisplay before running the next command - -@item Argument predicates and modifiers should work anywhere in a path - -@example -/usr/local/src/editors/vim $ vi **/CVS(/)/Root(.) -Invalid regexp: "Unmatched ( or \\(" -@end example - -With @command{zsh}, the glob above expands to all files named -@file{Root} in directories named @file{CVS}. - -@item Typing @samp{echo $@{locate locate@}/bin} results in a Lisp error - -Perhaps it should interpolate all permutations, and make that the -globbing result, since otherwise hitting return here will result in -``(list of filenames)/bin'', which is never valuable. Thus, one could -@command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}. -In that case, having an alias command name @command{glob} for -@command{identity} would be useful. - -@item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp - -@item Create @code{eshell-expand-file-name} - -This would use a data table to transform things such as @samp{~+}, -@samp{...}, etc. - -@item Abstract @file{em-smart.el} into @file{smart-scroll.el} - -It only really needs: to be hooked onto the output filter and the -pre-command hook, and to have the input-end and input-start markers. -And to know whether the last output group was ``successful.'' - -@item Allow for fully persisting the state of Eshell - -This would include: variables, history, buffer, input, dir stack, etc. - -@item Implement D as an argument predicate - -It means that files beginning with a dot should be included in the -glob match. - -@item A comma in a predicate list should mean OR - -At the moment, this is not supported. - -@item Error if a glob doesn't expand due to a predicate - -An error should be generated only if @code{eshell-error-if-no-glob} is -non-@code{nil}. - -@item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur - -@item Create @code{eshell-auto-accumulate-list} - -This is a list of commands for which, if the user presses @kbd{RET}, the -text is staged as the next Eshell command, rather than being sent to the -current interactive process. - -@item Display file and line number if an error occurs in a script - -@item @command{wait} doesn't work with process ids at the moment - -@item Enable the direct-to-process input code in @file{em-term.el} - -@item Problem with repeating @samp{echo $@{find /tmp@}} - -With smart display active, if @kbd{RET} is held down, after a while it -can't keep up anymore and starts outputting blank lines. It only -happens if an asynchronous process is involved@dots{} - -I think the problem is that @code{eshell-send-input} is resetting the -input target location, so that if the asynchronous process is not done -by the time the next @kbd{RET} is received, the input processor thinks -that the input is meant for the process; which, when smart display is -enabled, will be the text of the last command line! That is a bug in -itself. - -In holding down @kbd{RET} while an asynchronous process is running, -there will be a point in between termination of the process, and the -running of @code{eshell-post-command-hook}, which would cause -@code{eshell-send-input} to call @code{eshell-copy-old-input}, and then -process that text as a command to be run after the process. Perhaps -there should be a way of killing pending input between the death of the -process, and the @code{post-command-hook}. - -@item Allow for a more aggressive smart display mode - -Perhaps toggled by a command, that makes each output block a smart -display block. - -@item Create more meta variables - -@table @samp -@item $! -The reason for the failure of the last disk command, or the text of the -last Lisp error. - -@item $= -A special associate array, which can take references of the form -@samp{$=[REGEXP]}. It indexes into the directory ring. -@end table - -@item Eshell scripts can't execute in the background - -@item Support zsh's ``Parameter Expansion'' syntax, i.e., @samp{$@{@var{name}:-@var{val}@}} - -@item Write an @command{info} alias that can take arguments - -So that the user can enter @samp{info chmod}, for example. - -@item Create a mode @code{eshell-browse} - -It would treat the Eshell buffer as a outline. Collapsing the outline -hides all of the output text. Collapsing again would show only the -first command run in each directory - -@item Allow other revisions of a file to be referenced using @samp{file@{rev@}} - -This would be expanded by @code{eshell-expand-file-name} (see above). - -@item Print ``You have new mail'' when the ``Mail'' icon is turned on - -@item Implement @kbd{M-|} for Eshell - -@item Implement input redirection - -If it's a Lisp function, input redirection implies @command{xargs} (in a -way@dots{}). If input redirection is added, also update the -@code{file-name-quote-list}, and the delimiter list. - -@item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax - -With the handling of @emph{word} specified by an -@code{eshell-special-alist}. - -@item In @code{eshell-eval-using-options}, allow a @code{:complete} tag - -It would be used to provide completion rules for that command. Then the -macro will automagically define the completion function. - -@item For @code{eshell-command-on-region}, apply redirections to the result - -So that @samp{+ > 'blah} would cause the result of the @code{+} (using -input from the current region) to be inserting into the symbol -@code{blah}. - -If an external command is being invoked, the input is sent as standard -input, as if a @samp{cat |} had been invoked. - -If a Lisp command, or an alias, is invoked, then if the line has no -newline characters, it is divided by whitespace and passed as arguments -to the Lisp function. Otherwise, it is divided at the newline -characters. Thus, invoking @code{+} on a series of numbers will add -them; @code{min} would display the smallest figure, etc. - -@item Write @code{eshell-script-mode} as a minor mode - -It would provide syntax, abbrev, highlighting and indenting support like -@code{emacs-lisp-mode} and @code{shell-mode}. - -@item In the history mechanism, finish the Bash-style support - -This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate -from @samp{!:1*}. - -@item Support the -n command line option for @command{history} - -@item Implement @command{fc} in Lisp - -@item Specifying a frame as a redirection target should imply the currently active window's buffer - -@item Implement @samp{>@var{func-or-func-list}} - -This would allow for an ``output translators'', that take a function to -modify output with, and a target. Devise a syntax that works well with -pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase -regexp-quote)} or @samp{>'upcase}). - -@item Allow Eshell to read/write to/from standard input and output - -This would be optional, rather than always using the Eshell buffer. -This would allow it to be run from the command line (perhaps). - -@item Write a @command{help} command - -It would call subcommands with @option{--help}, or @option{-h} or -@option{/?}, as appropriate. - -@item Implement @command{stty} in Lisp - -@item Support @command{rc}'s matching operator, e.g., @samp{~ (@var{list}) @var{regexp}} - -@item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list} - -Using @command{bg} on a process that is already in the background does -nothing. Specifying redirection targets replaces (or adds) to the list -current being used. - -@item Have @command{jobs} print only the processes for the current shell - -@item How can Eshell learn if a background process has requested input? - -@item Support @samp{2>&1} and @samp{>&} and @samp{2>} and @samp{|&} - -The syntax table for parsing these should be customizable, such that the -user could change it to use rc syntax: @samp{>[2=1]}. - -@item Allow @samp{$_[-1]}, which would indicate the last element of the array - -@item Make @samp{$x[*]} equal to listing out the full contents of @samp{x} - -Return them as a list, so that @samp{$_[*]} is all the arguments of the -last command. - -@item Copy ANSI code handling from @file{term.el} into @file{em-term.el} - -Make it possible for the user to send char-by-char to the underlying -process. Ultimately, I should be able to move away from using term.el -altogether, since everything but the ANSI code handling is already part -of Eshell. Then, things would work correctly on MS-Windows as well -(which doesn't have @file{/bin/sh}, although @file{term.el} tries to use -it). - -@item Make the shell spawning commands be visual - -That is, make (@command{su}, @command{bash}, @command{telnet}, -@command{rlogin}, @command{rsh}, etc.)@: be part of -@code{eshell-visual-commands}. The only exception is if the shell is -being used to invoke a single command. Then, the behavior should be -based on what that command is. - -@item Create a smart viewing command named @command{open} - -This would search for some way to open its argument (similar to opening -a file in the Windows Explorer). - -@item Alias @command{read} to be the same as @command{open}, only read-only - -@item Write a @command{tail} command which uses @code{view-file} - -It would move point to the end of the buffer, and then turns on -auto-revert mode in that buffer at frequent intervals---and a -@command{head} alias which assumes an upper limit of -@code{eshell-maximum-line-length} characters per line. - -@item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search} - -@item Write mesh.c - -This would run Emacs with the appropriate arguments to invoke Eshell -only. That way, it could be listed as a login shell. - -@item Use an intangible @code{PS2} string for multi-line input prompts - -@item Auto-detect when a command is visual, by checking @code{TERMCAP} usage - -@item The first keypress after @kbd{M-x watson} triggers `eshell-send-input' - -@item Make @kbd{/} electric - -So that it automatically expands and corrects pathnames. Or make -pathname completion for Pcomplete auto-expand @samp{/u/i/std} to -@samp{/usr/include/std}. - -@item Write the @command{pushd} stack to disk along with @code{last-dir-ring} - -@item Add options to @code{eshell/cat} which would allow it to sort and uniq - -@item Implement @command{wc} in Lisp - -Add support for counting sentences, paragraphs, pages, etc. - -@item Once piping is added, implement @command{sort} and @command{uniq} in Lisp - -@item Implement @command{touch} in Lisp - -@item Implement @command{comm} in Lisp - -@item Implement an @command{epatch} command in Lisp - -This would call @code{ediff-patch-file}, or @code{ediff-patch-buffer}, -depending on its argument. - -@item Have an option such that @samp{ls -l} generates a dired buffer - -@item Write a version of @command{xargs} based on command rewriting - -That is, @samp{find X | xargs Y} would be indicated using @samp{Y -$@{find X@}}. Maybe @code{eshell-do-pipelines} could be changed to -perform this on-thy-fly rewriting. - -@item Write an alias for @command{less} that brings up a @code{view-mode} buffer - -Such that the user can press @key{SPC} and @key{DEL}, and then @key{q} -to return to Eshell. It would be equivalent to: -@samp{X > #; view-buffer #}. - -@item Make @code{eshell-mode} as much a full citizen as @code{shell-mode} - -Everywhere in Emacs where @code{shell-mode} is specially noticed, add -@code{eshell-mode} there. - -@item Permit the umask to be selectively set on a @command{cp} target - -@item Problem using @kbd{M-x eshell} after using @code{eshell-command} - -If the first thing that I do after entering Emacs is to run -@code{eshell-command} and invoke @command{ls}, and then use @kbd{M-x -eshell}, it doesn't display anything. - -@item @kbd{M-RET} during a long command (using smart display) doesn't work - -Since it keeps the cursor up where the command was invoked. - -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Concept Index - -@printindex cp - -@node Function and Variable Index -@unnumbered Function and Variable Index - -@printindex fn - -@node Command Index -@unnumbered Command Index - -@printindex cm - -@node Key Index -@unnumbered Key Index - -@printindex ky -@bye diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi deleted file mode 100644 index a54a37a72e6..00000000000 --- a/doc/misc/eudc.texi +++ /dev/null @@ -1,942 +0,0 @@ -\input texinfo.tex -@c %**start of header -@setfilename ../../info/eudc -@settitle Emacs Unified Directory Client (EUDC) Manual -@afourpaper -@documentencoding UTF-8 -@c %**end of header - -@copying -This file documents EUDC v1.30b. - -EUDC is the Emacs Unified Directory Client, a common interface to -directory servers using various protocols such as LDAP or the CCSO white -pages directory system (PH/QI) - -Copyright @copyright{} 1998, 2000--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* EUDC: (eudc). Emacs client for directory servers (LDAP, PH). -@end direntry - -@footnotestyle end - -@titlepage -@title EUDC Manual -@subtitle The Emacs Unified Directory Client -@author by Oscar Figueiredo -@code{1.30b} - -@page -@vskip 0pt plus 1fill -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs Unified Directory Client - -@insertcopying -@end ifnottex - -@menu -* Overview:: Summary of EUDC features -* Installation:: How to install EUDC -* Usage:: The various usage possibilities explained -* Credits:: Who's done what -* GNU Free Documentation License:: The license for this documentation. -* Command and Function Index:: -* Variables Index:: -@end menu - - - - - -@node Overview -@chapter Overview - -EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user -interface to access directory servers using different directory -protocols. - -Currently supported back-ends are: - -@itemize @bullet -@item -LDAP, Lightweight Directory Access Protocol -@item -CCSO PH/QI -@item -BBDB, Big Brother's Insidious Database -@end itemize - -The main features of the EUDC interface are: - -@itemize @bullet -@item -Queries using a customizable form -@item -Inline query expansion (for instance you can expand a name -to an email address in a mail message buffer using a server as an -address book) -@item -Multiple servers can be tried in turn until a match is found for an -inline query -@item -Fast minibuffer queries for email addresses and phone numbers -@item -Interface to BBDB to let you insert server records into your own BBDB database -(@pxref{Top,,BBDB,bbdb,BBDB Manual}) -@end itemize - -@menu -* LDAP:: What is LDAP ? -* CCSO PH/QI:: What is CCSO, PH, QI ? -* BBDB:: What is BBDB ? -@end menu - - - -@node LDAP -@section LDAP - -LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication -protocol for directory applications defined in RFC 1777. - -Quoted from RFC 1777: - -@quotation -[LDAP] is designed to provide access to the X.500 Directory while not -incurring the resource requirements of the Directory Access Protocol -(DAP). This protocol is specifically targeted at simple management -applications and browser applications that provide simple read/write -interactive access to the X.500 Directory, and is intended to be a -complement to the DAP itself. -@end quotation - -LDAP servers usually store (but are not limited to) information about -people such as their name, phone number, email address, office -location, etc@enddots{} More information about LDAP can be found at -@url{http://www.openldap.org/}. - -EUDC requires external support to access LDAP directory servers -(@pxref{LDAP Requirements}) - - -@node CCSO PH/QI -@section CCSO PH/QI - -The Central Computing Services Office (CCSO) of the University of -Illinois at Urbana Champaign created and freely distributed a -directory system that was used by many organizations in the 1990s. -The system records information about people such as their address, -phone number, email, academic information or any other details it was -configured to. Nowadays this system is not widely used. - -The system consists of two parts: a database server traditionally called -@samp{qi} and a command-line client called @samp{ph}. -@ignore -Until 2010, the code could be downloaded from -@url{http://www-dev.cites.uiuc.edu/ph/}. -@end ignore - -The original command-line @samp{ph} client that came with the -@samp{ph/qi} distribution provided additional features that are -not implemented in EUDC, like the possibility to communicate with the -server in login-mode, which made it possible to change records in the -database. - - -@node BBDB -@section BBDB - -BBDB is the @dfn{Big Brother's Insidious Database}, a package for Emacs -originally written by Jamie Zawinski which provides rolodex-like -database functionality featuring tight integration with the Emacs mail -and news readers. - -It is often used as an enhanced email address book. - -EUDC considers BBDB as a directory server back end just like LDAP or -PH/QI servers, though BBDB has no client/server protocol and thus always -resides locally on your machine. The point in this is not to offer an -alternate way to query your BBDB database (BBDB itself provides much -more flexible ways to do that), but rather to offer an interface to your -local directory that is consistent with the interface to external -directories (LDAP, PH/QI). This is particularly interesting when -performing queries on multiple servers. - -EUDC also offers a means to insert results from directory queries into -your own local BBDB (@pxref{Creating BBDB Records}) - -@node Installation -@chapter Installation - -Add the following to your @file{.emacs} init file: -@lisp -(require 'eudc) -@end lisp -This will install EUDC at startup. - -After installing EUDC you will find (the next time you launch Emacs) a -new @code{Directory Search} submenu in the @samp{Tools} menu that will -give you access to EUDC. - -You may also find it useful to add the following to your @file{.emacs} -initialization file to add a shortcut for email address expansion in -email composition buffers (@pxref{Inline Query Expansion}) - -@lisp -(eval-after-load - "message" - '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) -(eval-after-load - "sendmail" - '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) -@end lisp - -@menu -* LDAP Requirements:: EUDC needs external support for LDAP -@end menu - -@node LDAP Requirements -@section LDAP Requirements - -LDAP support is added by means of @file{ldap.el}, which is part of Emacs. -@file{ldap.el} needs an external command line utility named -@file{ldapsearch}, available as part of Open LDAP -(@url{http://www.openldap.org/}). - - -@node Usage -@chapter Usage - -This chapter describes the usage of EUDC@. Most functions and -customization options are available through the @samp{Directory Search} -submenu of the @samp{Tools} submenu. - -@menu -* Querying Servers:: How queries are performed and handled -* Query Form:: How to use and customize the query form -* Display of Query Results:: Controlling how query results are presented -* Inline Query Expansion:: How to use and customize inline queries -* The Server Hotlist:: How to use and manage the server hotlist -* Multi-server Queries:: How to query multiple servers successively -* Creating BBDB Records:: How to insert query results into your BBDB -* Server/Protocol Locals:: Customizing on a per server/protocol basis -@end menu - - -@node Querying Servers -@section Querying Servers - -EUDC's basic functionality is to let you query a directory server and -return the results back to you. There are several things you may want -to customize in this process. - - -@menu -* Selecting a Server:: The first thing to do -* Return Attributes:: Configuring what the server should return -* Duplicate Attributes:: What to do when records have duplicate attributes -@end menu - -@node Selecting a Server -@subsection Selecting a Server - -Before doing any query you will need to set the directory server. You -need to specify the name of the host machine running the server software -and the protocol to use. If you do not set the server in any fashion, -EUDC will ask you for one when you make your first query. - -You can set the server by selecting one from your hotlist of servers -(@pxref{The Server Hotlist}) available in the @samp{Server} submenu or -by selecting @samp{New Server} in that same menu. - -LDAP servers generally require some configuration before you can perform -queries on them. In particular, the @dfn{search base} must be -configured. If the server you select has no configured search base then -EUDC will propose you to configure it at this point. A customization -buffer will be displayed where you can edit the search base and other -parameters for the server. - -@defvar eudc-server -The name or IP address of the remote directory server. A TCP port number -may be specified by appending a colon and a number to the name of the -server. You will not need this unless your server runs on a port other -than the default (which depends on the protocol). -If the directory server resides on your own computer (which is the case -if you use the BBDB back end) then `localhost' is a reasonable value but -it will be ignored anyway. -@end defvar - -@defvar eudc-protocol -The directory protocol to use to query the server. Currently supported -protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}. -@end defvar - -@deffn Command eudc-set-server -This command accessible from @samp{New Server} submenu lets you specify a -new directory server and protocol. -@end deffn - -@node Return Attributes -@subsection Return Attributes - -Directory servers may be configured to return a default set of -attributes for each record matching a query if the query specifies none. -The variable @code{eudc-default-return-attributes} controls the return -attributes you want to see, if different from the server defaults. - -@defvar eudc-default-return-attributes -A list of the default attributes to extract from directory entries. If -set to the symbol @code{all} then all available attributes are -returned. A value of @code{nil}, the default, means to return the -default attributes as configured in the server. -@end defvar - -The server may return several matching records to a query. Some of the -records may however not contain all the attributes you requested. You can -discard those records. - -@defopt eudc-strict-return-matches -If non-@code{nil}, entries that do not contain all the requested return -attributes are ignored. Default is @code{t}. -@end defopt - -@node Duplicate Attributes -@subsection Duplicate Attributes - -Directory standards may authorize different instances of the same -attribute in a record. For instance the record of a person may contain -several email fields containing different email addresses. When using -a QI directory server this is difficult to distinguish from attributes -having multi-line values such as the postal address that may contain a -line for the street and another one for the zip code and city name. In -both cases, EUDC will consider the attribute duplicated. - -EUDC has several methods to deal with duplicated attributes. The -available methods are: - -@table @code -@item list -Makes a list with the different values of the duplicate attribute. The -record is returned with only one instance of the attribute with a list -of all the different values as a value. This is the default method that -is used to handle duplicate fields for which no other method has been -specified. -@item first -Discards all the duplicate values of the field keeping only the first -one. -@item concat -Concatenates the different values using a newline as a separator. The -record keeps only one instance of the field the value of which is a -single multi-line string. -@item duplicate -Duplicates the whole record into as many instances as there are different -values for the field. This is the default for the email field. Thus a -record containing 3 different email addresses is duplicated into three -different records each having a single email address. This is -particularly useful in combination with @code{select} as the method to -handle multiple matches in inline expansion queries (@pxref{Inline Query -Expansion}) because you are presented with the 3 addresses in a -selection buffer -@end table - -Because a method may not be applicable to all fields, the variable -@code{eudc-duplicate-attribute-handling-method} lets you specify either a -default method for all fields or a method for each individual field. - -@defvar eudc-duplicate-attribute-handling-method -A method to handle entries containing duplicate attributes. This is -either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol -@var{method}. The alist form of the variable associates a method to an -individual attribute name; the second form specifies a method applicable -to all attribute names. Available methods are: @code{list}, -@code{first}, @code{concat}, and @code{duplicate} (see above). The default is -@code{list}. -@end defvar - - - -@node Query Form -@section Query Form - -The simplest way to query your directory server is to use the query -form. You display the query form with the @samp{Query with Form} menu -item or by invoking the command @kbd{M-x eudc-query-form}. The attribute -names presented in this form are defined by the -@code{eudc-query-form-attributes} variable (unless a non-@code{nil} -argument is supplied to @code{eudc-query-form}). - -Since the different directory protocols to which EUDC interfaces may -use different names for equivalent attributes, EUDC defines its own set -of attribute names and a mapping between these names and their -protocol-specific equivalent through the variable -@code{eudc-protocol-attributes-translation-alist}. Names currently -defined by EUDC are @code{name}, @code{firstname}, @code{email} and -@code{phone}. - -@defvar eudc-query-form-attributes -@findex eudc-get-attribute-list -A list of attributes presented in the query form. Attribute names in -this list should be either EUDC attribute names or valid attribute -names. You can get a list of valid attribute names for the current -protocol with the @samp{List Valid Attribute Names} menu item or the -@kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name}, -@code{email} and @code{phone}. -@end defvar - -@deffn Command eudc-query-form get-fields-from-server -Display a form to query the directory server. If given a non-@code{nil} -argument the function first queries the server for the existing fields -and displays a corresponding form. Not all protocols may support a -non-@code{nil} argument here. -@end deffn - -Since the names of the fields may not be explicit enough or adapted to -be directly displayed as prompt strings in the form, the variable -@code{eudc-user-attribute-names-alist} lets you define more explicit -names for directory attribute names. This variable is ignored if -@code{eudc-use-raw-directory-names} is non-@code{nil}. - -@defvar eudc-user-attribute-names-alist -This is an alist of user-defined names for the directory attributes used in -query/response forms. Prompt strings for attributes that are not in this -alist are derived by splitting the attribute name at underscores and -capitalizing the individual words. -@end defvar - -@defvar eudc-use-raw-directory-names -If non-@code{nil}, use attributes names as defined in the directory. -Otherwise, directory query/response forms display the user attribute -names defined in @code{eudc-user-attribute-names-alist}. -@end defvar - -@node Display of Query Results -@section Display of Query Results - -Upon successful completion of a form query, EUDC will display a buffer -containing the results of the query. - -The fields that are returned for each record -are controlled by @code{eudc-default-return-attributes} (@pxref{Return -Attributes}). - -The display of each individual field can be performed by an arbitrary -function which allows specific processing for binary values, such as -images or audio samples, as well as values with semantics, such as -URLs. - -@defvar eudc-attribute-display-method-alist -An alist specifying methods to display attribute values. Each member of -the list is of the form @code{(@var{name} . @var{func})} where -@var{name} is a lowercased string naming a directory attribute -(translated according to @code{eudc-user-attribute-names-alist} if -@code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a -function that will be passed the corresponding attribute values for -display. -@end defvar - -This variable has protocol-local definitions (see @pxref{Server/Protocol -Locals}). For instance, it is defined as follows for LDAP: - -@lisp -(eudc-protocol-set 'eudc-attribute-display-method-alist - '(("jpegphoto" . eudc-display-jpeg-inline) - ("labeledurl" . eudc-display-url) - ("audio" . eudc-display-sound) - ("labeledurl" . eudc-display-url) - ("url" . eudc-display-url)) - 'ldap) -@end lisp - -EUDC provides a set of built-in functions to display binary value types: - -@defun eudc-display-generic-binary data -Display a button for unidentified binary @var{data}. -@end defun - -@defun eudc-display-url url -Display URL and make it clickable. -@end defun - -@defun eudc-display-sound data -Display a button to play the sound @var{data}. -@end defun - -@defun eudc-display-jpeg-inline data -Display the JPEG @var{data} inline at point if possible. -@end defun - -@defun eudc-display-jpeg-as-button data -Display a button for the JPEG @var{data}. -@end defun - -Right-clicking on a binary value button pops up a contextual menu with -options to process the value. Among these are saving the attribute -value to a file or sending it to an external viewer command. External -viewers should expect the value on their standard input and should -display it or perform arbitrary processing on it. Messages sent to -standard output are discarded. External viewers are listed in the -variable @code{eudc-external-viewers} which you can customize. - -@defvar eudc-external-viewers -This is a list of viewer program specifications. Each specification is -a list whose first element is a string naming the viewer for unique -identification, the second element is the executable program which -should be invoked and the following elements are arguments that should -be passed to the program. -@end defvar - - -@node Inline Query Expansion -@section Inline Query Expansion - -Inline query expansion is a powerful method to get completion from your -directory server. The most common usage is for expanding names to email -addresses in mail message buffers. The expansion is performed by the -command @kbd{M-x eudc-expand-inline} which is available from the -@samp{Expand Inline Query} menu item but can also be conveniently -bound to a key shortcut (@pxref{Installation}). The operation is -controlled by the variables @code{eudc-inline-expansion-format}, -@code{eudc-inline-query-format}, -@code{eudc-expanding-overwrites-query} and -@code{eudc-multiple-match-handling-method}. - -If the query fails for a server, other servers may be tried successively -until one of them finds a match (@pxref{Multi-server Queries}). - -@deffn Command eudc-expand-inline replace-p -Query the server and expand the query string before point. The query -string consists of the buffer substring from the point back to the -preceding comma, colon or beginning of -line. @code{eudc-inline-query-format} controls how individual words -are mapped onto directory attribute names. After querying the server -for the given string, the expansion specified by -@code{eudc-inline-expansion-format} is inserted in the buffer at -point. If @var{replace-p} is @code{t} then this expansion replaces the -query string in the buffer. If @code{eudc-expanding-overwrites-query} -is non-@code{nil} then the meaning of @var{replace-p} is negated. -@end deffn - -@defvar eudc-inline-query-format -Format of an inline expansion query. -This is actually a list of @var{format}s. A @var{format} is a list of -one or more EUDC attribute names. A @var{format} applies if it contains -as many attributes as individual words in the inline query string. If -several @var{format}s apply then they are tried in order until a match -is found. If @code{nil} all the words will be mapped onto the default -server/protocol attribute name (generally @code{name}). - -For instance, use the following -@lisp -(setq eudc-inline-query-format '((name) - (firstname) - (firstname name))) -@end lisp -@noindent -to indicate that single word expansion queries are to be considered as -surnames and if no match is found then they should be tried as first -names. Inline queries consisting of two words are considered as -consisting of a first name followed by a surname. If the query consists -of more than two words, then the first one is considered as the first -name and the remaining words are all considered as surname constituents. - -@var{format}s are in fact not limited to EUDC attribute names, you can -use server or protocol specific names in them. It may be safer if you -do so, to set the variable @code{eudc-inline-query-format} in a protocol -or server local fashion (see @pxref{Server/Protocol Locals}). - -For instance you could use the following to match up to three words -against the @code{cn} attribute of LDAP servers: -@lisp -(eudc-protocol-set 'eudc-inline-query-format - '((cn) - (cn cn) - (cn cn cn)) - 'ldap) -@end lisp -@end defvar - -@defvar eudc-inline-expansion-format -This variable lets you control exactly what is inserted into the buffer -upon an inline expansion request. It is a list whose first element is a -string passed to @code{format}. Remaining elements are symbols -corresponding to directory attribute names. The corresponding attribute -values are passed as additional arguments to @code{format}. Default is -@code{("%s" email)} but you may want to consider a value like @code{("%s -<%s>" name email)} -@end defvar - -@defvar eudc-multiple-match-handling-method -This variable controls what to do when multiple entries match a query -for an inline expansion. Possible values are: -@table @code -@item first -The first match is considered as being the only one, the others are -discarded. -@item select -A selection buffer pops up where you can choose a particular match. This -is the default value of the variable. -@item all -The expansion uses all records successively -@item abort -An error is signaled. The expansion aborts. -@end table - -Default is @code{select} -@end defvar - - - -@node The Server Hotlist -@section The Server Hotlist - -EUDC lets you maintain a list of frequently used servers so that you -can easily switch from one to another. This hotlist appears in the -@samp{Server} submenu. You select a server in this list by clicking on -its name. You can add the current server to the list with the command -@kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable -@code{eudc-server-hotlist} which is stored in and retrieved from the file -designated by @code{eudc-options-file}. EUDC also provides a facility to -edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}). - -The hotlist is also used to make queries on multiple servers -successively (@pxref{Multi-server Queries}). The order in which the -servers are tried is the order they appear in the hotlist, therefore it -is important to sort the hotlist appropriately. - -@deffn Command eudc-bookmark-server server -Add @var{server} to the hotlist of servers -@end deffn - -@deffn Command eudc-bookmark-current-server -Add the current server to the hotlist of servers -@end deffn - -@defvar eudc-options-file -The name of a file where EUDC stores its internal variables -(the hotlist and the current server). EUDC will try to load -that file upon initialization so, if you choose a file name -different from the defaults @file{~/.eudc-options}, be sure to set this -variable to the appropriate value @emph{before} EUDC is itself -loaded. -@end defvar - -@menu -* The Hotlist Edit Buffer:: An interactive hotlist editing facility -@end menu - -@node The Hotlist Edit Buffer -@subsection The Hotlist Edit Buffer - -The hotlist edit buffer offers a means to manage a list of frequently -used servers. Commands are available in the context pop-up menu -generally bound to the right mouse button. Those commands also have -equivalent key bindings. - -@deffn Command eudc-hotlist-add-server -Bound to @kbd{a}. -Add a new server to the hotlist on the line after point -@end deffn - -@deffn Command eudc-hotlist-delete-server -Bound to @kbd{d}. -Delete the server on the line point is on -@end deffn - -@deffn Command eudc-hotlist-select-server -Bound to @kbd{s}. -Select the server the point is on as the current directory server for -the next queries -@end deffn - -@deffn Command eudc-hotlist-transpose-servers -Bound to @kbd{t}. -Bubble up the server the point is on to the top of the list -@end deffn - -@deffn Command eudc-hotlist-quit-edit -Bound to @kbd{q}. -Save the changes and quit the hotlist edit buffer. Use @kbd{x} or -@kbd{M-x kill-buffer} to exit without saving. -@end deffn - - -@node Multi-server Queries -@section Multi-server Queries - -When using inline query expansion (@pxref{Inline Query Expansion}), EUDC -can try to query successively a sequence of directory servers until one -of them successfully finds a match for the query. - -@defvar eudc-inline-expansion-servers -This variable controls which servers are tried and in which order when -trying to perform an inline query. Possible values are: -@table @code -@item current-server -Only the current directory server is tried -@item hotlist -The servers in the hotlist are tried in order until one finds a match -for the query or `eudc-max-servers-to-query' is reached -@item server-then-hotlist -The current server then the servers in the hotlist are tried in the -order they appear in the hotlist until one of them finds a match or -`eudc-max-servers-to-query' is reached. This is the default. -@end table -@end defvar - -@defvar eudc-max-servers-to-query -This variable indicates the maximum number of servers to query when -performing a multi-server query. The default, @code{nil}, indicates -that all available servers should be tried. -@end defvar - - - -@node Creating BBDB Records -@section Creating BBDB Records - -@findex eudc-insert-record-at-point-into-bbdb -@findex eudc-try-bbdb-insert -With EUDC, you can automatically create BBDB records -(@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a -directory server. You do this by moving point to the appropriate -record in a query result display buffer and invoking the command -@kbd{M-x eudc-insert-record-at-point-into-bbdb} with the -keyboard binding @kbd{b}@footnote{This key binding does not actually -call @code{eudc-insert-record-at-point-into-bbdb} but uses -@code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC -cannot update an existing BBDB record and will signal an error if you -try to insert a record matching an existing one. - -@findex eudc-batch-export-records-to-bbdb -It is also possible to export to BBDB the whole batch of records -contained in the directory query result with the command -@kbd{M-x eudc-batch-export-records-to-bbdb}. - -Because directory systems may not enforce a strict record format, local -server installations may use different attribute names and have -different ways to organize the information. Furthermore BBDB has its own -record structure. For these reasons converting a record from its -external directory format to the BBDB format is a highly customizable -process. - -@defvar eudc-bbdb-conversion-alist -The value of this variable should be a symbol naming an alist defining a -mapping between BBDB field names onto directory attribute names records. -This is a protocol-local variable and is initialized upon protocol -switch (@pxref{Server/Protocol Locals}). The alist is made of cells of the -form @code{(@var{bbdb-field} . @var{spec-or-list})}. -@var{bbdb-field} is the name of a field -that must be defined in your BBDB environment (standard field names are -@code{name}, @code{company}, @code{net}, @code{phone}, @code{address} -and @code{notes}). -@var{spec-or-list} is either a single mapping specification or a list of -mapping specifications. Lists of mapping specifications are valid for -the @code{phone} and @code{address} BBDB fields only. @var{spec}s are -actually s-expressions which are evaluated as follows: - -@table @asis -@item a string -evaluates to itself -@item a symbol -evaluates to the symbol value. Symbols corresponding to directory -attribute names present in the record evaluate to the value of the field -in the record -@item a form -is evaluated as a function. The argument list may contain attribute -names which evaluate to the corresponding values in the record. The form -evaluation should return something appropriate for the particular -@var{bbdb-field} (see @code{bbdb-create-internal}). -@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as -convenience functions to parse phones and addresses. -@end table -@end defvar - -The default value of the PH-specific value of that variable is -@code{eudc-ph-bbdb-conversion-alist}: - -@lisp -((name . name) - (net . email) - (address . (eudc-bbdbify-address address "Address")) - (phone . ((eudc-bbdbify-phone phone "Phone") - (eudc-bbdbify-phone office_phone "Office Phone")))) -@end lisp - -This means that: - -@itemize @bullet -@item -the @code{name} field of the BBDB record gets its value -from the @code{name} attribute of the directory record -@item -the @code{net} field of the BBDB record gets its value -from the @code{email} attribute of the directory record -@item -the @code{address} field of the BBDB record is obtained by parsing the -@code{address} attribute of the directory record with the function -@code{eudc-bbdbify-address} -@item -two @code{phone} fields are created (when possible) in the BBDB record. -The first one has @cite{Phone} for location and its value is obtained by -parsing the @code{phone} attribute of the PH/QI record with the function -@code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location -its value is obtained by parsing the @code{office_phone} attribute of the -PH/QI record with the function @code{eudc-bbdbify-phone}. -@end itemize - -@defun eudc-bbdbify-phone phone location -This is a convenience function provided for use in -@code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector -compatible with @code{bbdb-create-internal}. @var{phone} is either a string -supposedly containing a phone number or a list of such strings which are -concatenated. @var{location} is used as the phone location for BBDB. -@end defun - -@defun eudc-bbdbify-address addr location -This is a convenience function provided for use in -@code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector -compatible with @code{bbdb-create-internal}. @var{addr} should be an -address string of no more than four lines or a list of lines. The last -line is searched for the zip code, city and state name. @var{location} -is used as the phone location for BBDB. -@end defun - -Note that only a subset of the attributes you selected with -@code{eudc-default-return-attributes} and that are actually displayed may -actually be inserted as part of the newly created BBDB record. - - -@node Server/Protocol Locals -@section Server/Protocol Locals - -EUDC can be customized independently for each server or directory -protocol. All variables can be given local bindings that are activated -when a particular server and/or protocol becomes active. This is much -like buffer-local bindings but on a per server or per protocol basis. - -@menu -* Manipulating local bindings:: Functions to set and query local bindings -@end menu - -@node Manipulating local bindings -@subsection Manipulating local bindings - -EUDC offers functions that let you set and query variables on a per -server or per protocol basis. - -The following predicates allow you to test the existence of -server/protocol local bindings for a particular variable. - -@defun eudc-server-local-variable-p var -Return non-@code{nil} if @var{var} has server-local bindings -@end defun - -@defun eudc-protocol-local-variable-p var -Return non-@code{nil} if @var{var} has protocol-local bindings -@end defun - -The following functions allow you to set the value of a variable with -various degrees of locality. - -@defun eudc-default-set var val -Set the EUDC default value of @var{var} to @var{val}. -The current binding of @var{var} (if local to the current server or -protocol) is not changed. -@end defun - -@defun eudc-protocol-set var val &optional protocol -Set the binding of @var{var} local to @var{protocol} to @var{val}. If -omitted, @var{protocol} defaults to the current value of -@code{eudc-protocol}. The current binding of @var{var} is changed only -if @var{protocol} is omitted. -@end defun - -@defun eudc-server-set var val &optional server -Set the binding of @var{var} local to @var{server} to @var{val}. If -omitted, @var{server} defaults to the current value of -@code{eudc-server}. The current binding of @var{var} is changed only if -@var{server} is omitted. -@end defun - -@defun eudc-set var val -Set the most local (server, protocol or default) binding of @var{var} to -@var{val}. The current binding of @var{var} is also set to @var{val}. -@end defun - -The following variables allow you to query the various bindings of a -variable (local or non-local). - -@defun eudc-variable-default-value var -Return the default binding of @var{var} (outside of a particular server -or protocol local binding). -Return @code{unbound} if @var{var} has no EUDC default value. -@end defun - -@defun eudc-variable-protocol-value var &optional protocol -Return the value of @var{var} local to @var{protocol}. Return -@code{unbound} if @var{var} has no value local to @var{protocol}. -@var{protocol} defaults to @code{eudc-protocol}. -@end defun - -@defun eudc-variable-server-value var [server] -Return the value of @var{var} local to @var{server}. -Return @code{unbound} if @var{var} has no value local to @var{server}. -@var{server} defaults to @code{eudc-server}. -@end defun - -Changing a protocol-local or server-local value of a variable has no -effect on its current value. The following command is used to -synchronize the current values of variables with their local values -given the current @code{eudc-server} and @code{eudc-protocol}: - -@defun eudc-update-local-variables -Update all EUDC variables according to their local settings. -@end defun - - - -@node Credits -@chapter Credits - -EUDC was written by Oscar Figueiredo based on @file{ph.el} by the -same author. - -Thanks to Soren Dayton for his suggestions, his enthusiasm and his help -in testing and proofreading the code and docs of @file{ph.el}. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Command and Function Index -@unnumbered Command and Function Index - -@printindex fn - -@node Variables Index -@unnumbered Variables Index - -@printindex vr - -@bye diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi deleted file mode 100644 index 827c35f02ef..00000000000 --- a/doc/misc/eww.texi +++ /dev/null @@ -1,236 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/eww -@settitle Emacs Web Wowser -@documentencoding UTF-8 -@c %**end of header - -@copying -This file documents the GNU Emacs Web Wowser (EWW) package. - -Copyright @copyright{} 2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* EWW: (eww). Emacs Web Wowser -@end direntry - -@finalout - -@titlepage -@title Emacs Web Wowser (EWW) -@subtitle A web browser for GNU Emacs. - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top EWW - -@insertcopying -@end ifnottex - -@menu -* Overview:: -* Basics:: -* Advanced:: - -Appendices -* History and Acknowledgments:: -* GNU Free Documentation License:: The license for this documentation. - -Indices -* Key Index:: -* Variable Index:: -* Lisp Function Index:: -* Concept Index:: -@end menu - -@node Overview -@chapter Overview -@dfn{EWW}, the Emacs Web Wowser, is a web browser for GNU Emacs. It -can load, parse, and display various web pages using @dfn{shr.el}. -However a GNU Emacs with @code{libxml2} support is required. - -@node Basics -@chapter Basic Usage - -@findex eww -@findex eww-open-file -@vindex eww-search-prefix -@cindex eww -@cindex Web Browsing - You can open a URL or search the web with the command @kbd{M-x eww}. -If the input doesn't look like a URL or domain name the web will be -searched via @code{eww-search-prefix}. The default search engine is -@url{https://duckduckgo.com, DuckDuckGo}. If you want to open a file -either prefix the file name with @code{file://} or use the command -@kbd{M-x eww-open-file}. - -@findex eww-quit -@findex eww-reload -@findex eww-copy-page-url -@kindex q -@kindex w -@kindex g - If loading the URL was successful the buffer @file{*eww*} is opened -and the web page is rendered in it. You can leave EWW by pressing -@kbd{q} or exit the browser by calling @kbd{eww-quit}. To reload the -web page hit @kbd{g} (@code{eww-reload}). Pressing @kbd{w} -(@code{eww-copy-page-url}) will copy the current URL to the kill ring. - -@findex eww-download -@vindex eww-download-directory -@kindex d -@cindex Download - A URL under the point can be downloaded with @kbd{d} -(@code{eww-download}). The file will be written to the directory -specified in @code{eww-download-directory} (Default: @file{~/Downloads/}). - -@findex eww-back-url -@findex eww-forward-url -@findex eww-list-histories -@kindex r -@kindex l -@kindex H -@cindex History - EWW remembers the URLs you have visited to allow you to go back and -forth between them. By pressing @kbd{l} (@code{eww-back-url}) you go -to the previous URL. You can go forward again with @kbd{r} -(@code{eww-forward-url}). If you want an overview of your browsing -history press @kbd{H} (@code{eww-list-histories}) to open the history -buffer @file{*eww history*}. The history is lost when EWW is quit. -If you want to remember websites you can use bookmarks. - -@findex eww-add-bookmark -@findex eww-list-bookmarks -@kindex b -@kindex B -@cindex Bookmarks - EWW allows you to @dfn{bookmark} URLs. Simply hit @kbd{b} -(@code{eww-add-bookmark}) to store a bookmark for the current website. -You can view stored bookmarks with @kbd{B} -(@code{eww-list-bookmarks}). This will open the bookmark buffer -@file{*eww bookmarks*}. - -@findex eww-browse-with-external-browser -@vindex shr-external-browser -@vindex eww-use-external-browser-for-content-type -@kindex & -@cindex External Browser - Although EWW and shr.el do their best to render webpages in GNU -Emacs some websites use features which can not be properly represented -or are not implemented (E.g., JavaScript). If you have trouble -viewing a website with EWW then hit @kbd{&} -(@code{eww-browse-with-external-browser}) inside the EWW buffer to -open the website in the external browser specified by -@code{shr-external-browser}. Some content types, such as video or -audio content, do not make sense to display in GNU Emacs at all. You -can tell EWW to open specific content automatically in an external -browser by customizing -@code{eww-use-external-browser-for-content-type}. - -@node Advanced -@chapter Advanced - -@findex eww-view-source -@kindex v -@cindex Viewing Source - You can view the source of a website with @kbd{v} -(@code{eww-view-source}). This will open a new buffer -@file{*eww-source*} and insert the source. The buffer will be set to -@code{html-mode} if available. - -@findex url-cookie-list -@kindex C -@cindex Cookies - EWW handles cookies through the @ref{Top, url package, ,url}. -You can list existing cookies with @kbd{C} (@code{url-cookie-list}). -For details about the Cookie handling @xref{Cookies,,,url}. - -@vindex eww-header-line-format -@cindex Header - The header line of the EWW buffer can be changed by customizing -@code{eww-header-line-format}. The format replaces @code{%t} with the -title of the website and @code{%u} with the URL. - -@c @vindex shr-bullet -@c @vindex shr-hr-line -@c @vindex eww-form-checkbox-selected-symbol -@c @vindex eww-form-checkbox-symbol -@c EWW and the rendering engine shr.el use ASCII characters to -@c represent some graphical elements, such as bullet points -@c (@code{shr-bullet}), check boxes -@c (@code{eww-form-checkbox-selected-symbol} and -@c @code{eww-form-checkbox-symbol}), and horizontal rules -@c @code{shr-hr-line}). Depending on your fonts these characters can be -@c replaced by Unicode glyphs to achieve better looking results. - -@vindex shr-max-image-proportion -@vindex shr-blocked-images -@cindex Image Display - Loading random images from the web can be problematic due to their -size or content. By customizing @code{shr-max-image-proportion} you -can set the maximal image proportion in relation to the window they -are displayed in. E.g., 0.7 means an image is allowed to take up 70% -of the width and height. If Emacs supports image scaling (ImageMagick -support required) then larger images are scaled down. You can block -specific images completely by customizing @code{shr-blocked-images}. - -@node History and Acknowledgments -@appendix History and Acknowledgments - -EWW was originally written by Lars Ingebrigtsen, known for his work on -Gnus. He started writing an Emacs HTML rendering library, -@code{shr.el}, to read blogs in Gnus. He eventually added a web -browser front end and HTML form support. Which resulted in EWW, the -Emacs Web Wowser. EWW was announced on 16 June 2013: -@url{http://lars.ingebrigtsen.no/2013/06/16/eww/}. - -EWW was then moved from the Gnus repository to GNU Emacs and several -developers started contributing to it as well. - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Key Index -@unnumbered Key Index - -@printindex ky - -@node Variable Index -@unnumbered Variable Index - -@printindex vr - -@node Lisp Function Index -@unnumbered Function Index - -@printindex fn - -@node Concept Index -@unnumbered Concept Index - -@printindex cp - - -@bye diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi deleted file mode 100644 index 761056a69a5..00000000000 --- a/doc/misc/flymake.texi +++ /dev/null @@ -1,787 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../../info/flymake -@set VERSION 0.3 -@set UPDATED April 2004 -@settitle GNU Flymake @value{VERSION} -@syncodeindex pg cp -@documentencoding UTF-8 -@comment %**end of header - -@copying -This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), -which is a universal on-the-fly syntax checker for GNU Emacs. - -Copyright @copyright{} 2004--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Flymake: (flymake). A universal on-the-fly syntax checker. -@end direntry - -@titlepage -@title GNU Flymake -@subtitle for version @value{VERSION}, @value{UPDATED} -@author Pavel Kobiakov(@email{pk_at_work@@yahoo.com}) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top GNU Flymake -@insertcopying -@end ifnottex - -@menu -* Overview of Flymake:: -* Installing Flymake:: -* Using Flymake:: -* Configuring Flymake:: -* Flymake Implementation:: -* GNU Free Documentation License:: -* Index:: -@end menu - -@node Overview of Flymake -@chapter Overview -@cindex Overview of Flymake - -Flymake is a universal on-the-fly syntax checker implemented as an -Emacs minor mode. Flymake runs the pre-configured syntax check tool -(compiler for C++ files, @code{perl} for perl files, etc.)@: in the -background, passing it a temporary copy of the current buffer, and -parses the output for known error/warning message patterns. Flymake -then highlights erroneous lines (i.e., lines for which at least one -error or warning has been reported by the syntax check tool), and -displays an overall buffer status in the mode line. Status information -displayed by Flymake contains total number of errors and warnings -reported for the buffer during the last syntax check. - -@code{flymake-goto-next-error} and @code{flymake-goto-prev-error} -functions allow for easy navigation to the next/previous erroneous -line, respectively. - -Calling @code{flymake-display-err-menu-for-current-line} will popup a -menu containing error messages reported by the syntax check tool for -the current line. Errors/warnings belonging to another file, such as a -@code{.h} header file included by a @code{.c} file, are shown in the -current buffer as belonging to the first line. Menu items for such -messages also contain a filename and a line number. Selecting such a -menu item will automatically open the file and jump to the line with -error. - -Syntax check is done ``on-the-fly''. It is started whenever - -@itemize @bullet -@item buffer is loaded -@item a newline character is added to the buffer -@item some changes were made to the buffer more than @code{0.5} seconds ago (the -delay is configurable). -@end itemize - -Flymake is a universal syntax checker in the sense that it's easily -extended to support new syntax check tools and error message -patterns. @xref{Configuring Flymake}. - -@node Installing Flymake -@chapter Installing -@cindex Installing Flymake - - -Flymake is packaged in a single file, @code{flymake.el}. - -To install/update Flymake, place @code{flymake.el} to a directory -somewhere on Emacs load path. You might also want to byte-compile -@code{flymake.el} to improve performance. - -Also, place the following line in the @code{.emacs} file. - -@lisp -(require 'flymake) -@end lisp - -You might also map the most frequently used Flymake functions, such as -@code{flymake-goto-next-error}, to some keyboard shortcuts: - -@lisp -(global-set-key [f3] 'flymake-display-err-menu-for-current-line) -(global-set-key [f4] 'flymake-goto-next-error) -@end lisp - -@node Using Flymake -@chapter Using Flymake -@cindex Using Flymake - -@menu -* Flymake mode:: -* Running the syntax check:: -* Navigating to error lines:: -* Viewing error messages:: -* Syntax check statuses:: -* Troubleshooting:: -@end menu - -@node Flymake mode -@section Flymake mode -@cindex flymake-mode - -Flymake is an Emacs minor mode. To use Flymake, you -must first activate @code{flymake-mode} by using the -@code{flymake-mode} function. - -Instead of manually activating @code{flymake-mode}, you can configure -Flymake to automatically enable @code{flymake-mode} upon opening any -file for which syntax check is possible. To do so, place the following -line in @code{.emacs}: - -@lisp -(add-hook 'find-file-hook 'flymake-find-file-hook) -@end lisp - -@node Running the syntax check -@section Running the syntax check -@cindex Manually starting the syntax check - -When @code{flymake-mode} is active, syntax check is started -automatically on any of the three conditions mentioned above. Syntax -check can also be started manually by using the -@code{flymake-start-syntax-check-for-current-buffer} function. This -can be used, for example, when changes were made to some other buffer -affecting the current buffer. - -@node Navigating to error lines -@section Navigating to error lines -@cindex Navigating to error lines - -After syntax check is completed, lines for which at least one error or -warning has been reported are highlighted, and total number of errors -and warning is shown in the mode line. Use the following functions to -navigate the highlighted lines. - -@multitable @columnfractions 0.25 0.75 - -@item @code{flymake-goto-next-error} -@tab Moves point to the next erroneous line, if any. - -@item @code{flymake-goto-prev-error} -@tab Moves point to the previous erroneous line. - -@end multitable - -These functions treat erroneous lines as a linked list. Therefore, -@code{flymake-goto-next-error} will go to the first erroneous line -when invoked in the end of the buffer. - -@node Viewing error messages -@section Viewing error messages -@cindex Viewing error messages - -To view error messages belonging to the current line, use the -@code{flymake-display-err-menu-for-current-line} function. If there's -at least one error or warning reported for the current line, this -function will display a popup menu with error/warning texts. -Selecting the menu item whose error belongs to another file brings -forward that file with the help of the -@code{flymake-goto-file-and-line} function. - -@node Syntax check statuses -@section Syntax check statuses -@cindex Syntax check statuses - -After syntax check is finished, its status is displayed in the mode line. -The following statuses are defined. - -@multitable @columnfractions 0.25 0.75 -@item Flymake* or Flymake:E/W* -@tab Flymake is currently running. For the second case, E/W contains the -error and warning count for the previous run. - -@item Flymake -@tab Syntax check is not running. Usually this means syntax check was -successfully passed (no errors, no warnings). Other possibilities are: -syntax check was killed as a result of executing -@code{flymake-compile}, or syntax check cannot start as compilation -is currently in progress. - -@item Flymake:E/W -@tab Number of errors/warnings found by the syntax check process. - -@item Flymake:! -@tab Flymake was unable to find master file for the current buffer. -@end multitable - -The following errors cause a warning message and switch flymake mode -OFF for the buffer. - -@multitable @columnfractions 0.25 0.75 -@item CFGERR -@tab Syntax check process returned nonzero exit code, but no -errors/warnings were reported. This indicates a possible configuration -error (for example, no suitable error message patterns for the -syntax check tool). - -@item NOMASTER -@tab Flymake was unable to find master file for the current buffer. - -@item NOMK -@tab Flymake was unable to find a suitable buildfile for the current buffer. - -@item PROCERR -@tab Flymake was unable to launch a syntax check process. -@end multitable - - -@node Troubleshooting -@section Troubleshooting -@cindex Logging -@cindex Troubleshooting - -Flymake uses a simple logging facility for indicating important points -in the control flow. The logging facility sends logging messages to -the @file{*Messages*} buffer. The information logged can be used for -resolving various problems related to Flymake. - -Logging output is controlled by the @code{flymake-log-level} -variable. @code{3} is the most verbose level, and @code{-1} switches -logging off. - -@node Configuring Flymake -@chapter Configuring and Extending Flymake -@cindex Configuring and Extending Flymake - -@menu -* Customizable variables:: -* Adding support for a new syntax check tool:: -@end menu - -Flymake was designed to be easily extended for supporting new syntax -check tools and error message patterns. - -@node Customizable variables -@section Customizable variables -@cindex Customizable variables - -This section summarizes variables used for Flymake -configuration. - -@table @code -@item flymake-log-level -Controls logging output, see @ref{Troubleshooting}. - -@item flymake-allowed-file-name-masks -A list of @code{(filename-regexp, init-function, cleanup-function -getfname-function)} for configuring syntax check tools. @xref{Adding -support for a new syntax check tool}. - -@ignore -@item flymake-buildfile-dirs -A list of directories (relative paths) for searching a -buildfile. @xref{Locating the buildfile}. -@end ignore - -@item flymake-master-file-dirs -A list of directories for searching a master file. @xref{Locating a -master file}. - -@item flymake-get-project-include-dirs-function -A function used for obtaining a list of project include dirs (C/C++ -specific). @xref{Getting the include directories}. - -@item flymake-master-file-count-limit -@itemx flymake-check-file-limit -Used when looking for a master file. @xref{Locating a master file}. - -@item flymake-err-line-patterns -Patterns for error/warning messages in the form @code{(regexp file-idx -line-idx col-idx err-text-idx)}. @xref{Parsing the output}. - -@item flymake-warning-predicate -Predicate to classify error text as warning. @xref{Parsing the output}. - -@item flymake-compilation-prevents-syntax-check -A flag indicating whether compilation and syntax check of the same -file cannot be run simultaneously. - -@item flymake-no-changes-timeout -If any changes are made to the buffer, syntax check is automatically -started after @code{flymake-no-changes-timeout} seconds. - -@item flymake-gui-warnings-enabled -A boolean flag indicating whether Flymake will show message boxes for -non-recoverable errors. If @code{flymake-gui-warnings-enabled} is -@code{nil}, these errors will only be logged to the @file{*Messages*} -buffer. - -@item flymake-start-syntax-check-on-newline -A boolean flag indicating whether to start syntax check after a -newline character is added to the buffer. - -@item flymake-errline -A custom face for highlighting lines for which at least one error has -been reported. - -@item flymake-warnline -A custom face for highlighting lines for which at least one warning -and no errors have been reported. - -@item flymake-error-bitmap -A bitmap used in the fringe to mark lines for which an error has -been reported. - -@item flymake-warning-bitmap -A bitmap used in the fringe to mark lines for which a warning has -been reported. - -@item flymake-fringe-indicator-position -Which fringe (if any) should show the warning/error bitmaps. - -@end table - -@node Adding support for a new syntax check tool -@section Adding support for a new syntax check tool -@cindex Adding support for a new syntax check tool - -@menu -* Example---Configuring a tool called directly:: -* Example---Configuring a tool called via make:: -@end menu - -Syntax check tools are configured using the -@code{flymake-allowed-file-name-masks} list. Each item of this list -has the following format: - -@lisp -(filename-regexp, init-function, cleanup-function, getfname-function) -@end lisp - -@table @code -@item filename-regexp -This field is used as a key for locating init/cleanup/getfname -functions for the buffer. Items in -@code{flymake-allowed-file-name-masks} are searched sequentially. The -first item with @code{filename-regexp} matching buffer filename is -selected. If no match is found, @code{flymake-mode} is switched off. - -@item init-function -@code{init-function} is required to initialize the syntax check, -usually by creating a temporary copy of the buffer contents. The -function must return @code{(list cmd-name arg-list)}. If -@code{init-function} returns null, syntax check is aborted, by -@code{flymake-mode} is not switched off. - -@item cleanup-function -@code{cleanup-function} is called after the syntax check process is -complete and should take care of proper deinitialization, which is -usually deleting a temporary copy created by the @code{init-function}. - -@item getfname-function -This function is used for translating filenames reported by the syntax -check tool into ``real'' filenames. Filenames reported by the tool -will be different from the real ones, as actually the tool works with -the temporary copy. In most cases, the default implementation -provided by Flymake, @code{flymake-get-real-file-name}, can be used as -@code{getfname-function}. - -@end table - -To add support for a new syntax check tool, write corresponding -@code{init-function}, and, optionally @code{cleanup-function} and -@code{getfname-function}. If the format of error messages reported by -the new tool is not yet supported by Flymake, add a new entry to -the @code{flymake-err-line-patterns} list. - -The following sections contain some examples of configuring Flymake -support for various syntax check tools. - -@node Example---Configuring a tool called directly -@subsection Example---Configuring a tool called directly -@cindex Adding support for perl - -In this example, we will add support for @code{perl} as a syntax check -tool. @code{perl} supports the @code{-c} option which does syntax -checking. - -First, we write the @code{init-function}: - -@lisp -(defun flymake-perl-init () - (let* ((temp-file (flymake-init-create-temp-buffer-copy - 'flymake-create-temp-inplace)) - (local-file (file-relative-name - temp-file - (file-name-directory buffer-file-name)))) - (list "perl" (list "-wc " local-file)))) -@end lisp - -@code{flymake-perl-init} creates a temporary copy of the buffer -contents with the help of -@code{flymake-init-create-temp-buffer-copy}, and builds an appropriate -command line. - -Next, we add a new entry to the -@code{flymake-allowed-file-name-masks}: - -@lisp -(setq flymake-allowed-file-name-masks - (cons '(".+\\.pl$" - flymake-perl-init - flymake-simple-cleanup - flymake-get-real-file-name) - flymake-allowed-file-name-masks)) -@end lisp - -Note that we use standard @code{cleanup-function} and -@code{getfname-function}. - -Finally, we add an entry to @code{flymake-err-line-patterns}: - -@lisp -(setq flymake-err-line-patterns - (cons '("\\(.*\\) at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]" - 2 3 nil 1) - flymake-err-line-patterns)) -@end lisp - -@node Example---Configuring a tool called via make -@subsection Example---Configuring a tool called via make -@cindex Adding support for C (gcc+make) - -In this example we will add support for C files syntax checked by -@command{gcc} called via @command{make}. - -We're not required to write any new functions, as Flymake already has -functions for @command{make}. We just add a new entry to the -@code{flymake-allowed-file-name-masks}: - -@lisp -(setq flymake-allowed-file-name-masks - (cons '(".+\\.c$" - flymake-simple-make-init - flymake-simple-cleanup - flymake-get-real-file-name) - flymake-allowed-file-name-masks)) -@end lisp - -@code{flymake-simple-make-init} builds the following @command{make} -command line: - -@lisp -(list "make" - (list "-s" "-C" - base-dir - (concat "CHK_SOURCES=" source) - "SYNTAX_CHECK_MODE=1" - "check-syntax")) -@end lisp - -@code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}. - -Thus, @code{Makefile} must contain the @code{check-syntax} target. In -our case this target might look like this: - -@verbatim -check-syntax: - gcc -o /dev/null -S ${CHK_SOURCES} -@end verbatim - -@noindent -The format of error messages reported by @command{gcc} is already -supported by Flymake, so we don't have to add a new entry to -@code{flymake-err-line-patterns}. Note that if you are using -Automake, you may want to replace @code{gcc} with the standard -Automake variable @code{COMPILE}: - -@verbatim -check-syntax: - $(COMPILE) -o /dev/null -S ${CHK_SOURCES} -@end verbatim - -@node Flymake Implementation -@chapter Flymake Implementation -@cindex Implementation details - -@menu -* Determining whether syntax check is possible:: -* Making a temporary copy:: -* Locating a master file:: -* Getting the include directories:: -* Locating the buildfile:: -* Starting the syntax check process:: -* Parsing the output:: -* Highlighting erroneous lines:: -* Interaction with other modes:: -@end menu - -Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}. -Flymake first determines whether it is able to do syntax -check. It then saves a copy of the buffer in a temporary file in the -buffer's directory (or in the system temp directory, for java -files), creates a syntax check command and launches a process with -this command. The output is parsed using a list of error message patterns, -and error information (file name, line number, type and text) is -saved. After the process has finished, Flymake highlights erroneous -lines in the buffer using the accumulated error information. - -@node Determining whether syntax check is possible -@section Determining whether syntax check is possible -@cindex Syntax check models -@cindex Master file - -Syntax check is considered possible if there's an entry in -@code{flymake-allowed-file-name-masks} matching buffer's filename and -its @code{init-function} returns non-@code{nil} value. - -Two syntax check modes are distinguished: - -@enumerate - -@item -Buffer can be syntax checked in a standalone fashion, that is, the -file (its temporary copy, in fact) can be passed over to the compiler to -do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java) -sources. - -@item -Buffer can be syntax checked, but additional file, called master file, -is required to perform this operation. A master file is a file that -includes the current file, so that running a syntax check tool on it -will also check syntax in the current file. Examples are C/C++ (.h, -.hpp) headers. - -@end enumerate - -These modes are handled inside init/cleanup/getfname functions, see -@ref{Adding support for a new syntax check tool}. - -Flymake contains implementations of all functionality required to -support different syntax check modes described above (making temporary -copies, finding master files, etc.), as well as some tool-specific -(routines for Make, Ant, etc.)@: code. - - -@node Making a temporary copy -@section Making a temporary copy -@cindex Temporary copy of the buffer -@cindex Master file - -After the possibility of the syntax check has been determined, a -temporary copy of the current buffer is made so that the most recent -unsaved changes could be seen by the syntax check tool. Making a copy -is quite straightforward in a standalone case (mode @code{1}), as it's -just saving buffer contents to a temporary file. - -Things get trickier, however, when master file is involved, as it -requires to - -@itemize @bullet -@item locate a master file -@item patch it to include the current file using its new (temporary) -name. -@end itemize - -Locating a master file is discussed in the following section. - -Patching just changes all appropriate lines of the master file so that they -use the new (temporary) name of the current file. For example, suppose current -file name is @code{file.h}, the master file is @code{file.cpp}, and -it includes current file via @code{#include "file.h"}. Current file's copy -is saved to file @code{file_flymake.h}, so the include line must be -changed to @code{#include "file_flymake.h"}. Finally, patched master file -is saved to @code{file_flymake_master.cpp}, and the last one is passed to -the syntax check tool. - -@node Locating a master file -@section Locating a master file -@cindex Master file - -Master file is located in two steps. - -First, a list of possible master files is built. A simple name -matching is used to find the files. For a C++ header @code{file.h}, -Flymake searches for all @code{.cpp} files in the directories whose relative paths are -stored in a customizable variable @code{flymake-master-file-dirs}, which -usually contains something like @code{("." "./src")}. No more than -@code{flymake-master-file-count-limit} entries is added to the master file -list. The list is then sorted to move files with names @code{file.cpp} to -the top. - -Next, each master file in a list is checked to contain the appropriate -include directives. No more than @code{flymake-check-file-limit} of each -file are parsed. - -For @code{file.h}, the include directives to look for are -@code{#include "file.h"}, @code{#include "../file.h"}, etc. Each -include is checked against a list of include directories -(see @ref{Getting the include directories}) to be sure it points to the -correct @code{file.h}. - -First matching master file found stops the search. The master file is then -patched and saved to disk. In case no master file is found, syntax check is -aborted, and corresponding status (!) is reported in the mode line. - -@node Getting the include directories -@section Getting the include directories -@cindex Include directories (C/C++ specific) - -Two sets of include directories are distinguished: system include directories -and project include directories. The former is just the contents of the -@code{INCLUDE} environment variable. The latter is not so easy to obtain, -and the way it can be obtained can vary greatly for different projects. -Therefore, a customizable variable -@code{flymake-get-project-include-dirs-function} is used to provide the -way to implement the desired behavior. - -The default implementation, @code{flymake-get-project-include-dirs-imp}, -uses a @command{make} call. This requires a correct base directory, that is, a -directory containing a correct @file{Makefile}, to be determined. - -As obtaining the project include directories might be a costly operation, its -return value is cached in the hash table. The cache is cleared in the beginning -of every syntax check attempt. - -@node Locating the buildfile -@section Locating the buildfile -@cindex Locating the buildfile -@cindex buildfile, locating -@cindex Makefile, locating - -Flymake can be configured to use different tools for performing syntax -checks. For example, it can use direct compiler call to syntax check a perl -script or a call to @command{make} for a more complicated case of a -@code{C/C++} source. The general idea is that simple files, like perl -scripts and html pages, can be checked by directly invoking a -corresponding tool. Files that are usually more complex and generally -used as part of larger projects, might require non-trivial options to -be passed to the syntax check tool, like include directories for -C++. The latter files are syntax checked using some build tool, like -Make or Ant. - -All Make configuration data is usually stored in a file called -@code{Makefile}. To allow for future extensions, flymake uses a notion of -buildfile to reference the 'project configuration' file. - -Special function, @code{flymake-find-buildfile} is provided for locating buildfiles. -Searching for a buildfile is done in a manner similar to that of searching -for possible master files. -@ignore -A customizable variable -@code{flymake-buildfile-dirs} holds a list of relative paths to the -buildfile. They are checked sequentially until a buildfile is found. -@end ignore -In case there's no build file, syntax check is aborted. - -Buildfile values are also cached. - -@node Starting the syntax check process -@section Starting the syntax check process -@cindex Syntax check process - -The command line (command name and the list of arguments) for launching a process is returned by the -initialization function. Flymake then just calls @code{start-process} -to start an asynchronous process and configures a process filter and -sentinel, which are used for processing the output of the syntax check -tool. - -@node Parsing the output -@section Parsing the output -@cindex Parsing the output - -The output generated by the syntax check tool is parsed in the process -filter/sentinel using the error message patterns stored in the -@code{flymake-err-line-patterns} variable. This variable contains a -list of items of the form @code{(regexp file-idx line-idx -err-text-idx)}, used to determine whether a particular line is an -error message and extract file name, line number and error text, -respectively. Error type (error/warning) is also guessed by matching -error text with the '@code{^[wW]arning}' pattern. Anything that was not -classified as a warning is considered an error. Type is then used to -sort error menu items, which shows error messages first. - -Flymake is also able to interpret error message patterns missing err-text-idx -information. This is done by merely taking the rest of the matched line -(@code{(substring line (match-end 0))}) as error text. This trick allows -to make use of a huge collection of error message line patterns from -@code{compile.el}. All these error patterns are appended to -the end of @code{flymake-err-line-patterns}. - -The error information obtained is saved in a buffer local -variable. The buffer for which the process output belongs is -determined from the process-id@w{}->@w{}buffer mapping updated -after every process launch/exit. - -@node Highlighting erroneous lines -@section Highlighting erroneous lines -@cindex Erroneous lines, faces - -Highlighting is implemented with overlays and happens in the process -sentinel, after calling the cleanup function. Two customizable faces -are used: @code{flymake-errline} and -@code{flymake-warnline}. Errors belonging outside the current -buffer are considered to belong to line 1 of the current buffer. - -@c This manual does not use vindex. -@c @vindex flymake-fringe-indicator-position -@c @vindex flymake-error-bitmap -@c @vindex flymake-warning-bitmap -If the option @code{flymake-fringe-indicator-position} is non-@code{nil}, -errors and warnings are also highlighted in the left or right fringe, -using the bitmaps specified by @code{flymake-error-bitmap} -and @code{flymake-warning-bitmap}. - -@node Interaction with other modes -@section Interaction with other modes -@cindex Interaction with other modes -@cindex Interaction with compile mode - -The only mode flymake currently knows about is @code{compile}. - -Flymake can be configured to not start syntax check if it thinks the -compilation is in progress. The check is made by the -@code{flymake-compilation-is-running}, which tests the -@code{compilation-in-progress} variable. The reason why this might be -useful is saving CPU time in case both syntax check and compilation -are very CPU intensive. The original reason for adding this feature, -though, was working around a locking problem with MS Visual C++ -compiler. - -Flymake also provides an alternative command for starting compilation, -@code{flymake-compile}: - -@lisp -(defun flymake-compile () - "Kill all flymake syntax checks then start compilation." - (interactive) - (flymake-stop-all-syntax-checks) - (call-interactively 'compile)) -@end lisp - -It just kills all the active syntax check processes before calling -@code{compile}. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index - -@printindex cp - -@bye diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi deleted file mode 100644 index 8ea470d2da8..00000000000 --- a/doc/misc/forms.texi +++ /dev/null @@ -1,978 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c documentation for forms-mode -@c Written by Johan Vromans, and edited by Richard Stallman - -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/forms -@settitle Forms Mode User's Manual -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex ky cp -@iftex -@finalout -@setchapternewpage odd -@end iftex -@c @smallbook -@comment %**end of header (This is for running Texinfo on a region.) -@documentencoding UTF-8 - -@copying -This file documents Forms mode, a form-editing major mode for GNU Emacs. - -Copyright @copyright{} 1989, 1997, 2001--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Forms: (forms). Emacs package for editing data bases - by filling in forms. -@end direntry - -@titlepage -@sp 6 -@center @titlefont{Forms Mode User's Manual} -@sp 4 -@center Forms-Mode version 2 -@sp 1 -@center for GNU Emacs 22.1 -@sp 1 -@center April 2007 -@sp 5 -@center Johan Vromans -@center @i{jvromans@@squirrel.nl} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Forms Mode - -Forms mode is an Emacs major mode for working with simple textual data -bases in a forms-oriented manner. In Forms mode, the information in -these files is presented in an Emacs window in a user-defined format, -one record at a time. The user can view records or modify their -contents. - -Forms mode is not a simple major mode, but requires two files to do its -job: a control file and a data file. The data file holds the -actual data to be presented. The control file describes -how to present it. - -@insertcopying - -@menu -* Forms Example:: An example: editing the password data base. -* Entering and Exiting Forms Mode:: - How to visit a file in Forms mode. -* Forms Commands:: Special commands to use while in Forms mode. -* Data File Format:: How to format the data file. -* Control File Format:: How to control forms mode. -* Format Description:: How to define the forms layout. -* Modifying Forms Contents:: How to modify. -* Miscellaneous:: Forms mode messages and other remarks. -* Error Messages:: List of error messages forms mode can produce. -* Long Example:: A more complex control file example. -* Credits:: Thanks everyone. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Index to this manual. -@end menu -@end ifnottex - -@node Forms Example -@chapter Forms Example - -Let's illustrate Forms mode with an example. Suppose you are looking at -the @file{/etc/passwd} file, and the screen looks like this: - -@example -====== /etc/passwd ====== - -User : root Uid: 0 Gid: 1 - -Name : Super User - -Home : / - -Shell: /bin/sh -@end example - -As you can see, the familiar fields from the entry for the super user -are all there, but instead of being colon-separated on one single line, -they make up a forms. - -The contents of the forms consist of the contents of the fields of the -record (e.g., @samp{root}, @samp{0}, @samp{1}, @samp{Super User}) -interspersed with normal text (e.g., @samp{User : }, @samp{Uid: }). - -If you modify the contents of the fields, Forms mode will analyze your -changes and update the file appropriately. You cannot modify the -interspersed explanatory text (unless you go to some trouble about it), -because that is marked read-only (@pxref{Text Properties,,, elisp, The -Emacs Lisp Reference Manual}). - -The Forms mode control file specifies the relationship between the -format of @file{/etc/passwd} and what appears on the screen in Forms -mode. @xref{Control File Format}. - -@node Entering and Exiting Forms Mode -@chapter Entering and Exiting Forms Mode - -@table @kbd -@findex forms-find-file -@item M-x forms-find-file @key{RET} @var{control-file} @key{RET} -Visit a database using Forms mode. Specify the name of the -@strong{control file}, not the data file! - -@findex forms-find-file-other-window -@item M-x forms-find-file-other-window @key{RET} @var{control-file} @key{RET} -Similar, but displays the file in another window. -@end table - -The command @code{forms-find-file} evaluates the file -@var{control-file}, and also visits it in Forms mode. What you see in -its buffer is not the contents of this file, but rather a single record -of the corresponding data file that is visited in its own buffer. So -there are two buffers involved in Forms mode: the @dfn{forms buffer} -that is initially used to visit the control file and that shows the -records being browsed, and the @dfn{data buffer} that holds the data -file being visited. The latter buffer is normally not visible. - -Initially, the first record is displayed in the forms buffer. -The mode line displays the major mode name @samp{Forms}, followed by the -minor mode @samp{View} if the data base is read-only. The number of the -current record (@var{n}) and the total number of records in the -file(@var{t}) are shown in the mode line as @samp{@var{n}/@var{t}}. For -example: - -@example ---%%-Emacs: passwd-demo (Forms View 1/54)----All------- -@end example - -If the buffer is not read-only, you may change the buffer to modify the -fields in the record. When you move to a different record, the contents -of the buffer are parsed using the specifications in -@code{forms-format-list}, and the data file is updated. If the record -has fields that aren't included in the display, they are not changed. - -@vindex forms-mode-hook -Entering Forms mode runs the normal hook @code{forms-mode-hook} to -perform user-defined customization. - -To save any modified data, you can use @kbd{C-x C-s} -(@code{forms-save-buffer}). This does not save the forms buffer (which would -be rather useless), but instead saves the buffer visiting the data file. - -To terminate Forms mode, you can use @kbd{C-x C-s} (@code{forms-save-buffer}) -and then kill the forms buffer. However, the data buffer will still -remain. If this is not desired, you have to kill this buffer too. - -@node Forms Commands -@chapter Forms Commands - -The commands of Forms mode belong to the @kbd{C-c} prefix, with one -exception: @key{TAB}, which moves to the next field. Forms mode uses -different key maps for normal mode and read-only mode. In read-only -Forms mode, you can access most of the commands without the @kbd{C-c} -prefix, but you must type ordinary letters instead of control -characters; for example, type @kbd{n} instead of @kbd{C-c C-n}. - -If your Emacs has been built with X-toolkit support, Forms mode will -provide its own menu with a number of Forms mode commands. - -@table @kbd -@findex forms-next-record -@kindex C-c C-n -@item C-c C-n -Show the next record (@code{forms-next-record}). With a numeric -argument @var{n}, show the @var{n}th next record. - -@findex forms-prev-record -@kindex C-c C-p -@item C-c C-p -Show the previous record (@code{forms-prev-record}). With a numeric -argument @var{n}, show the @var{n}th previous record. - -@findex forms-jump-record -@kindex C-c C-l -@item C-c C-l -Jump to a record by number (@code{forms-jump-record}). Specify -the record number with a numeric argument. - -@findex forms-first-record -@kindex C-c < -@item C-c < -Jump to the first record (@code{forms-first-record}). - -@findex forms-last-record -@kindex C-c > -@item C-c > -Jump to the last record (@code{forms-last-record}). This command also -recalculates the number of records in the data file. - -@findex forms-next-field -@kindex TAB -@item @key{TAB} -@kindex C-c TAB -@itemx C-c @key{TAB} -Jump to the next field in the current record (@code{forms-next-field}). -With a numeric argument @var{n}, jump forward @var{n} fields. If this command -would move past the last field, it wraps around to the first field. - -@findex forms-toggle-read-only -@kindex C-c C-q -@item C-c C-q -Toggles read-only mode (@code{forms-toggle-read-only}). In read-only -Forms mode, you cannot edit the fields; most Forms mode commands can be -accessed without the prefix @kbd{C-c} if you use the normal letter -instead (for example, type @kbd{n} instead of @kbd{C-c C-n}). In edit -mode, you can edit the fields and thus change the contents of the data -base; you must begin Forms mode commands with @code{C-c}. Switching -to edit mode is allowed only if you have write access to the data file. - -@findex forms-insert-record -@kindex C-c C-o -@item C-c C-o -Create a new record and insert it before the current record -(@code{forms-insert-record}). It starts out with empty (or default) -contents for its fields; you can then edit the fields. With a numeric -argument, the new record is created @emph{after} the current one. -See also @code{forms-modified-record-filter} in @ref{Modifying Forms -Contents}. - -@findex forms-delete-record -@kindex C-c C-k -@item C-c C-k -Delete the current record (@code{forms-delete-record}). You are -prompted for confirmation before the record is deleted unless a numeric -argument has been provided. - -@findex forms-search-forward -@kindex C-c C-s @var{regexp} @key{RET} -@item C-c C-s @var{regexp} @key{RET} -Search forward for @var{regexp} in all records following this one -(@code{forms-search-forward}). If found, this record is shown. -If you give an empty argument, the previous regexp is used again. - -@findex forms-search-backward -@kindex C-c C-r @var{regexp} @key{RET} -@item C-c C-r @var{regexp} @key{RET} -Search backward for @var{regexp} in all records following this one -(@code{forms-search-backward}). If found, this record is shown. -If you give an empty argument, the previous regexp is used again. - -@ignore -@findex forms-exit -@kindex C-c C-x -@item C-c C-x -Terminate Forms mode processing (@code{forms-exit}). The data file is -saved if it has been modified. - -@findex forms-exit-no-save -@item M-x forms-exit-no-save -Terminates forms mode processing without saving modified data first. -@end ignore - -@findex forms-prev-field -@item M-x forms-prev-field -Similar to @code{forms-next-field} but moves backwards. - -@findex forms-save-buffer -@item M-x forms-save-buffer -@kindex C-x C-s -@itemx C-x C-s -Forms mode replacement for @code{save-buffer}. When executed in the -forms buffer it will save the contents of the (modified) data buffer -instead. In Forms mode this function will be bound to @kbd{C-x C-s}. - -@findex forms-print -@item M-x forms-print -This command can be used to make a formatted print -of the contents of the data file. - -@end table - -In addition the command @kbd{M-x revert-buffer} is useful in Forms mode -just as in other modes. - -@ignore -@vindex forms-forms-scroll -@findex scroll-up -@findex scroll-down -If the variable @code{forms-forms-scrolls} is set to a value other -than @code{nil} (which it is, by default), the Emacs functions -@code{scroll-up} and @code{scroll-down} will perform a -@code{forms-next-record} and @code{forms-prev-record} when in forms -mode. So you can use your favorite page commands to page through the -data file. - -@vindex forms-forms-jump -@findex beginning-of-buffer -@findex end-of-buffer -Likewise, if the variable @code{forms-forms-jump} is not @code{nil} -(which it is, by default), Emacs functions @code{beginning-of-buffer} -and @code{end-of-buffer} will perform @code{forms-first-record} and -@code{forms-last-record} when in forms mode. -@end ignore - -The following function key definitions are set up in Forms mode -(whether read-only or not): - -@table @kbd -@kindex next -@item next -forms-next-record - -@kindex prior -@item prior -forms-prev-record - -@kindex begin -@item begin -forms-first-record - -@kindex end -@item end -forms-last-record - -@kindex S-Tab -@findex forms-prev-field -@item S-Tab -forms-prev-field -@end table - -@node Data File Format -@chapter Data File Format - -@cindex record -@cindex field -@vindex forms-field-sep -Files for use with Forms mode are very simple---each @dfn{record} -(usually one line) forms the contents of one form. Each record consists -of a number of @dfn{fields}, which are separated by the value of the -string @code{forms-field-sep}, which is @code{"\t"} (a Tab) by default. - -@vindex forms-read-file-filter -@vindex forms-write-file-filter -If the format of the data file is not suitable enough you can define the -filter functions @code{forms-read-file-filter} and -@code{forms-write-file-filter}. @code{forms-read-file-filter} is called -when the data file is read from disk into the data buffer. It operates -on the data buffer, ignoring read-only protections. When the data file -is saved to disk @code{forms-write-file-filter} is called to cancel the -effects of @code{forms-read-file-filter}. After being saved, -@code{forms-read-file-filter} is called again to prepare the data buffer -for further processing. - -@cindex pseudo-newline -@vindex forms-multi-line -Fields may contain text which shows up in the forms in multiple lines. -These lines are separated in the field using a ``pseudo-newline'' -character which is defined by the value of the string -@code{forms-multi-line}. Its default value is @code{"\^k"} (a Control-K -character). If it is -set to @code{nil}, multiple line fields are prohibited. - -If the data file does not exist, it is automatically created. - -@node Control File Format -@chapter Control File Format - -@cindex control file -The Forms mode @dfn{control file} serves two purposes. First, it names -the data file to use, and defines its format and properties. Second, -the Emacs buffer it occupies is used by Forms mode to display the forms. - -The contents of the control file are evaluated as a Lisp program. It -should set the following Lisp variables to suitable values: - -@table @code -@vindex forms-file -@item forms-file -This variable specifies the name of the data file. Example: - -@example -(setq forms-file "my/data-file") -@end example - -If the control file doesn't set @code{forms-file}, Forms mode -reports an error. - -@vindex forms-format-list -@item forms-format-list -This variable describes the way the fields of the record are formatted on -the screen. For details, see @ref{Format Description}. - -@vindex forms-number-of-fields -@item forms-number-of-fields -This variable holds the number of fields in each record of the data -file. Example: - -@example -(setq forms-number-of-fields 10) -@end example -@end table - -If the control file does not set @code{forms-format-list} a default -format is used. In this situation, Forms mode will deduce the number of -fields from the data file providing this file exists and -@code{forms-number-of-records} has not been set in the control file. - -The control file can optionally set the following additional Forms mode -variables. Most of them have default values that are good for most -applications. - -@table @code -@vindex forms-field-sep -@item forms-field-sep -This variable may be used to designate the string which separates the -fields in the records of the data file. If not set, it defaults to the -string @code{"\t"} (a Tab character). Example: - -@example -(setq forms-field-sep "\t") -@end example - -@vindex forms-read-only -@item forms-read-only -If the value is non-@code{nil}, the data file is treated read-only. (Forms -mode also treats the data file as read-only if you don't have access to -write it.) Example: - -@example -(set forms-read-only t) -@end example - -@vindex forms-multi-line -@item forms-multi-line -This variable specifies the @dfn{pseudo newline} separator that allows -multi-line fields. This separator goes between the ``lines'' within a -field---thus, the field doesn't really contain multiple lines, but it -appears that way when displayed in Forms mode. If the value is -@code{nil}, multi-line text fields are prohibited. The pseudo newline -must not be a character contained in @code{forms-field-sep}. - -The default value is @code{"\^k"}, the character Control-K@. Example: - -@example -(setq forms-multi-line "\^k") -@end example - -@ignore -@vindex forms-forms-scroll -@item forms-forms-scroll -@xref{Forms Mode Commands}, for details. - -@vindex forms-forms-jump -@item forms-forms-jump -@xref{Forms Mode Commands}, for details. -@end ignore - -@findex forms-read-file-filter -@item forms-read-file-filter -This variable holds the name of a function to be called after the data -file has been read in. This can be used to transform the contents of the -data file into a format more suitable for forms processing. -If it is @code{nil}, no function is called. For example, to maintain a -gzipped database: - -@example -(defun gzip-read-file-filter () - (shell-command-on-region (point-min) (point-max) - "gzip -d" t t)) -(setq forms-read-file-filter 'gzip-read-file-filter) -@end example - -@findex forms-write-file-filter -@item forms-write-file-filter -This variable holds the name of a function to be called before writing -out the contents of the data file. -This can be used to undo the effects of @code{forms-read-file-filter}. -If it is @code{nil}, no function is called. Example: - -@example -(defun gzip-write-file-filter () - (make-variable-buffer-local 'require-final-newline) - (setq require-final-newline nil) - (shell-command-on-region (point-min) (point-max) - "gzip" t t)) -(setq forms-write-file-filter 'gzip-write-file-filter) -@end example - -@findex forms-new-record-filter -@item forms-new-record-filter -This variable holds a function to be called whenever a new record is created -to supply default values for fields. If it is @code{nil}, no function is -called. -@xref{Modifying Forms Contents}, for details. - -@findex forms-modified-record-filter -@item forms-modified-record-filter -This variable holds a function to be called whenever a record is -modified, just before updating the Forms data file. If it is -@code{nil}, no function is called. -@xref{Modifying Forms Contents}, for details. - -@findex forms-insert-after -@item forms-insert-after -If this variable is not @code{nil}, new records are created @emph{after} the -current record. Also, upon visiting a file, the initial position will be -at the last record instead of the first one. - -@findex forms-check-number-of-fields -@item forms-check-number-of-fields -Normally each record is checked to contain the correct number of fields. -Under certain circumstances, this can be undesirable. -If this variable is set to @code{nil}, these checks will be bypassed. -@end table - -@node Format Description -@chapter The Format Description - -@vindex forms-format-list - The variable @code{forms-format-list} specifies the format of the data -in the data file, and how to convert the data for display in Forms mode. -Its value must be a list of Forms mode @dfn{formatting elements}, each -of which can be a string, a number, a Lisp list, or a Lisp symbol that -evaluates to one of those. The formatting elements are processed in the -order they appear in the list. - -@table @var -@item string -A string formatting element is inserted in the forms ``as is,'' as text -that the user cannot alter. - -@item number -A number element selects a field of the record. The contents of this -field are inserted in the display at this point. Field numbers count -starting from 1 (one). - -@item list -A formatting element that is a list specifies a function call. This -function is called every time a record is displayed, and its result, -which must be a string, is inserted in the display text. The function -should do nothing but returning a string. - -@vindex forms-fields -The function you call can access the fields of the record as a list in -the variable -@code{forms-fields}. - -@item symbol -A symbol used as a formatting element should evaluate to a string, number, -or list; the value is interpreted as a formatting element, as described -above. -@end table - -If a record does not contain the number of fields as specified in -@code{forms-number-of-fields}, a warning message will be printed. Excess -fields are ignored, missing fields are set to empty. - -The control file which displays @file{/etc/passwd} file as demonstrated -in the beginning of this manual might look as follows: - -@example -;; @r{This demo visits @file{/etc/passwd}.} - -(setq forms-file "/etc/passwd") -(setq forms-number-of-fields 7) -(setq forms-read-only t) ; @r{to make sure} -(setq forms-field-sep ":") -;; @r{Don't allow multi-line fields.} -(setq forms-multi-line nil) - -(setq forms-format-list - (list - "====== /etc/passwd ======\n\n" - "User : " 1 - " Uid: " 3 - " Gid: " 4 - "\n\n" - "Name : " 5 - "\n\n" - "Home : " 6 - "\n\n" - "Shell: " 7 - "\n")) -@end example - -When you construct the value of @code{forms-format-list}, you should -usually either quote the whole value, like this, - -@example -(setq forms-format-list - '( - "====== " forms-file " ======\n\n" - "User : " 1 - (make-string 20 ?-) - @dots{} - )) -@end example - -@noindent -or quote the elements which are lists, like this: - -@example -(setq forms-format-list - (list - "====== " forms-file " ======\n\n" - "User : " 1 - '(make-string 20 ?-) - @dots{} - )) -@end example - -Forms mode validates the contents of @code{forms-format-list} when you -visit a database. If there are errors, processing is aborted with an -error message which includes a descriptive text. @xref{Error Messages}, -for a detailed list of error messages. - -If no @code{forms-format-list} is specified, Forms mode will supply a -default format list. This list contains the name of the file being -visited, and a simple label for each field indicating the field number. - -@node Modifying Forms Contents -@chapter Modifying The Forms Contents - -If @code{forms-read-only} is @code{nil}, the user can modify the fields -and records of the database. - -All normal editing commands are available for editing the contents of the -displayed record. You cannot delete or modify the fixed, explanatory -text that comes from string formatting elements, but you can modify the -actual field contents. - -@ignore -@c This is for the Emacs 18 version only. -If the contents of the forms cannot be recognized properly, this is -signaled using a descriptive text. @xref{Error Messages}, for more info. -The cursor will indicate the last part of the forms which was -successfully parsed. It's important to avoid entering field contents -that would cause confusion with the field-separating fixed text. -@end ignore - -If the variable @code{forms-modified-record-filter} is non-@code{nil}, -it is called as a function before the new data is written to the data -file. The function receives one argument, a vector that contains the -contents of the fields of the record. - -The function can refer to fields with @code{aref} and modify them with -@code{aset}. The first field has number 1 (one); thus, element 0 of the -vector is not used. The function should return the same vector it was -passed; the (possibly modified) contents of the vector determine what is -actually written in the file. Here is an example: - -@example -(defun my-modified-record-filter (record) - ;; @r{Modify second field.} - (aset record 2 (current-time-string)) - ;; @r{Return the field vector.} - record) - -(setq forms-modified-record-filter 'my-modified-record-filter) -@end example - -If the variable @code{forms-new-record-filter} is non-@code{nil}, its -value is a function to be called to fill in default values for the -fields of a new record. The function is passed a vector of empty -strings, one for each field; it should return the same vector, with -the desired field values stored in it. Fields are numbered starting -from 1 (one). Example: - -@example -(defun my-new-record-filter (fields) - (aset fields 5 (login-name)) - (aset fields 1 (current-time-string)) - fields) - -(setq forms-new-record-filter 'my-new-record-filter) -@end example - -@node Miscellaneous -@chapter Miscellaneous - -@vindex forms-version -The global variable @code{forms-version} holds the version information -of the Forms mode software. - -@findex forms-enumerate -It is very convenient to use symbolic names for the fields in a record. -The function @code{forms-enumerate} provides an elegant means to define -a series of variables whose values are consecutive integers. The -function returns the highest number used, so it can be used to set -@code{forms-number-of-fields} also. For example: - -@example -(setq forms-number-of-fields - (forms-enumerate - '(field1 field2 field3 @dots{}))) -@end example - -This sets @code{field1} to 1, @code{field2} to 2, and so on. - -Care has been taken to keep the Forms mode variables buffer-local, so it -is possible to visit multiple files in Forms mode simultaneously, even -if they have different properties. - -@findex forms-mode -If you have visited the control file in normal fashion with -@code{find-file} or a like command, you can switch to Forms mode with -the command @code{M-x forms-mode}. If you put @samp{-*- forms -*-} in -the first line of the control file, then visiting it enables Forms mode -automatically. But this makes it hard to edit the control file itself, -so you'd better think twice before using this. - -The default format for the data file, using @code{"\t"} to separate -fields and @code{"\^k"} to separate lines within a field, matches the -file format of some popular database programs, e.g., FileMaker. So -@code{forms-mode} can decrease the need to use proprietary software. - -@node Error Messages -@chapter Error Messages - -This section describes all error messages which can be generated by -forms mode. Error messages that result from parsing the control file -all start with the text @samp{Forms control file error}. Messages -generated while analyzing the definition of @code{forms-format-list} -start with @samp{Forms format error}. - -@table @code -@item Forms control file error: `forms-file' has not been set -The variable @code{forms-file} was not set by the control file. - -@item Forms control file error: `forms-number-of-fields' has not been set -The variable @code{forms-number-of-fields} was not set by the control -file. - -@item Forms control file error: `forms-number-of-fields' must be a number > 0 -The variable @code{forms-number-of-fields} did not contain a positive -number. - -@item Forms control file error: `forms-field-sep' is not a string -@itemx Forms control file error: `forms-multi-line' must be nil or a one-character string -The variable @code{forms-multi-line} was set to something other than -@code{nil} or a single-character string. - -@item Forms control file error: `forms-multi-line' is equal to 'forms-field-sep' -The variable @code{forms-multi-line} may not be equal to -@code{forms-field-sep} for this would make it impossible to distinguish -fields and the lines in the fields. - -@item Forms control file error: `forms-new-record-filter' is not a function -@itemx Forms control file error: `forms-modified-record-filter' is not a function -The variable has been set to something else than a function. - -@item Forms control file error: `forms-format-list' is not a list -The variable @code{forms-format-list} was not set to a Lisp list -by the control file. - -@item Forms format error: field number @var{xx} out of range 1..@var{nn} -A field number was supplied in @code{forms-format-list} with a value of -@var{xx}, which was not greater than zero and smaller than or equal to -the number of fields in the forms, @var{nn}. - -@item Forms format error: @var{fun} is not a function -The first element of a list which is an element of -@code{forms-format-list} was not a valid Lisp function. - -@item Forms format error: invalid element @var{xx} -A list element was supplied in @code{forms-format-list} which was not a -string, number or list. - -@ignore -@c This applies to Emacs 18 only. -@c Error messages generated while a modified form is being analyzed. - -@item Parse error: not looking at `...' -When re-parsing the contents of a forms, the text shown could not -be found. - -@item Parse error: cannot find `...' -When re-parsing the contents of a forms, the text shown, which -separates two fields, could not be found. - -@item Parse error: cannot parse adjacent fields @var{xx} and @var{yy} -Fields @var{xx} and @var{yy} were not separated by text, so could not be -parsed again. -@end ignore - -@item Warning: this record has @var{xx} fields instead of @var{yy} -The number of fields in this record in the data file did not match -@code{forms-number-of-fields}. Missing fields will be made empty. - -@item Multi-line fields in this record - update refused! -The current record contains newline characters, hence can not be written -back to the data file, for it would corrupt it. Probably you inserted a -newline in a field, while @code{forms-multi-line} was @code{nil}. - -@item Field separator occurs in record - update refused! -The current record contains the field separator string inside one of the -fields. It can not be written back to the data file, for it would -corrupt it. Probably you inserted the field separator string in a field. - -@item Record number @var{xx} out of range 1..@var{yy} -A jump was made to non-existing record @var{xx}. @var{yy} denotes the -number of records in the file. - -@item Stuck at record @var{xx} -An internal error prevented a specific record from being retrieved. - -@item No write access to @code{"}@var{file}@code{"} -An attempt was made to enable edit mode on a file that has been write -protected. - -@item Search failed: @var{regexp} -The @var{regexp} could not be found in the data file. Forward searching -is done from the current location until the end of the file, then -retrying from the beginning of the file until the current location. -Backward searching is done from the current location until the beginning -of the file, then retrying from the end of the file until the current -location. - -@item Wrapped -A search completed successfully after wrapping around. - -@item Warning: number of records changed to @var{nn} -Forms mode's idea of the number of records has been adjusted to the -number of records actually present in the data file. - -@item Problem saving buffers? -An error occurred while saving the data file buffer. Most likely, Emacs -did ask to confirm deleting the buffer because it had been modified, and -you said `no'. -@end table - -@node Long Example -@chapter Long Example - -The following example exploits most of the features of Forms mode. -This example is included in the distribution as file @file{etc/forms/forms-d2.el}. - -@example -;; demo2 -- demo forms-mode -*- emacs-lisp -*- - -;; @r{This sample forms exploit most of the features of forms mode.} - -;; @r{Set the name of the data file.} -(setq forms-file - (expand-file-name "forms/forms-d2.dat" data-directory)) - -;; @r{Use @code{forms-enumerate} to set field names and number thereof.} -(setq forms-number-of-fields - (forms-enumerate - '(arch-newsgroup ; 1 - arch-volume ; 2 - arch-issue ; and ... - arch-article ; ... so - arch-shortname ; ... ... on - arch-parts - arch-from - arch-longname - arch-keywords - arch-date - arch-remarks))) - -;; @r{The following functions are used by this form for layout purposes.} -;; -(defun arch-tocol (target &optional fill) - "Produces a string to skip to column TARGET. -Prepends newline if needed. -The optional FILL should be a character, used to fill to the column." - (if (null fill) - (setq fill ? )) - (if (< target (current-column)) - (concat "\n" (make-string target fill)) - (make-string (- target (current-column)) fill))) -;; -(defun arch-rj (target field &optional fill) - "Produces a string to skip to column TARGET\ - minus the width of field FIELD. -Prepends newline if needed. -The optional FILL should be a character, -used to fill to the column." - (arch-tocol (- target (length (nth field forms-fields))) fill)) - -;; @r{Record filters.} -;; -(defun new-record-filter (the-record) - "Form a new record with some defaults." - (aset the-record arch-from (user-full-name)) - (aset the-record arch-date (current-time-string)) - the-record) ; return it -(setq forms-new-record-filter 'new-record-filter) - -;; @r{The format list.} -(setq forms-format-list - (list - "====== Public Domain Software Archive ======\n\n" - arch-shortname - " - " arch-longname - "\n\n" - "Article: " arch-newsgroup - "/" arch-article - " " - '(arch-tocol 40) - "Issue: " arch-issue - " " - '(arch-rj 73 10) - "Date: " arch-date - "\n\n" - "Submitted by: " arch-from - "\n" - '(arch-tocol 79 ?-) - "\n" - "Keywords: " arch-keywords - "\n\n" - "Parts: " arch-parts - "\n\n====== Remarks ======\n\n" - arch-remarks - )) - -;; @r{That's all, folks!} -@end example - -@node Credits -@chapter Credits - -Bug fixes and other useful suggestions were supplied by -Harald Hanche-Olsen (@code{hanche@@imf.unit.no}), -@code{cwitty@@portia.stanford.edu}, -Jonathan I. Kamens, -Per Cederqvist (@code{ceder@@signum.se}), -Michael Lipka (@code{lipka@@lip.hanse.de}), -Andy Piper (@code{ajp@@eng.cam.ac.uk}), -Frederic Pierresteguy (@code{F.Pierresteguy@@frcl.bull.fr}), -Ignatios Souvatzis -and Richard Stallman (@code{rms@@gnu.org}). - -This documentation was slightly inspired by the documentation of ``rolo -mode'' by Paul Davis at Schlumberger Cambridge Research -(@code{davis%scrsu1%sdr.slb.com@@relay.cs.net}). - -None of this would have been possible without GNU Emacs of the Free -Software Foundation. Thanks, Richard! - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@bye diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi deleted file mode 100644 index 44cc29b9c39..00000000000 --- a/doc/misc/gnus-coding.texi +++ /dev/null @@ -1,392 +0,0 @@ -\input texinfo - -@setfilename gnus-coding -@settitle Gnus Coding Style and Maintenance Guide -@documentencoding UTF-8 -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex pg cp - -@copying -Copyright @copyright{} 2004--2005, 2007--2014 Free Software -Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - - -@titlepage -@title Gnus Coding Style and Maintenance Guide - -@author by Reiner Steib - -@insertcopying -@end titlepage - -@c Obviously this is only a very rudimentary draft. We put it in the -@c repository anyway hoping that it might annoy someone enough to fix -@c it. ;-) Fixing only a paragraph also is appreciated. - -@ifnottex -@node Top -@top Gnus Coding Style and Maintenance Guide -This manual describes @dots{} - -@insertcopying -@end ifnottex - -@menu -* Gnus Coding Style:: Gnus Coding Style -* Gnus Maintenance Guide:: Gnus Maintenance Guide -* GNU Free Documentation License:: The license for this documentation. -@end menu - -@c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader} - -@node Gnus Coding Style -@chapter Gnus Coding Style -@section Dependencies - -The Gnus distribution contains a lot of libraries that have been written -for Gnus and used intensively for Gnus. But many of those libraries are -useful on their own. E.g., other Emacs Lisp packages might use the -@acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME -Manual}. - -@subsection General purpose libraries - -@table @file - -@item netrc.el -@file{.netrc} parsing functionality. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item format-spec.el -Functions for formatting arbitrary formatting strings. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item hex-util.el -Functions to encode/decode hexadecimal string. -@c As of 2007-08-25... -There are no Gnus dependencies in these files. -@end table - -@subsection Encryption and security - -@table @file -@item encrypt.el -File encryption routines -@c As of 2005-10-25... -There are no Gnus dependencies in this file. - -@item password.el -Read passwords from user, possibly using a password cache. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item tls.el -TLS/SSL support via wrapper around GnuTLS -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item pgg*.el -Glue for the various PGP implementations. -@c As of 2005-10-21... -There are no Gnus dependencies in these files. - -@item sha1.el -SHA1 Secure Hash Algorithm. -@c As of 2007-08-25... -There are no Gnus dependencies in these files. -@end table - -@subsection Networking - -@table @file -@item dig.el -Domain Name System dig interface. -@c As of 2005-10-21... -There are no serious Gnus dependencies in this file. Uses -@code{gnus-run-mode-hooks} (a wrapper function). - -@item dns.el, dns-mode.el -Domain Name Service lookups. -@c As of 2005-10-21... -There are no Gnus dependencies in these files. -@end table - -@subsection Mail and News related RFCs - -@table @file -@item pop3.el -Post Office Protocol (RFC 1460) interface. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item imap.el -@acronym{IMAP} library. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item ietf-drums.el -Functions for parsing RFC822bis headers. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item rfc1843.el -HZ (rfc1843) decoding. HZ is a data format for exchanging files of -arbitrarily mixed Chinese and @acronym{ASCII} characters. -@c As of 2005-10-21... -@code{rfc1843-gnus-setup} seem to be useful only for Gnus. Maybe this -function should be relocated to remove dependencies on Gnus. Other -minor dependencies: @code{gnus-newsgroup-name} could be eliminated by -using an optional argument to @code{rfc1843-decode-article-body}. - -@item rfc2045.el -Functions for decoding rfc2045 headers -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@item rfc2047.el -Functions for encoding and decoding rfc2047 messages -@c As of 2007-08-25... -There are no Gnus dependencies in these files. -@c -Only a couple of tests for gnusy symbols. - -@item rfc2104.el -RFC2104 Hashed Message Authentication Codes -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@item rfc2231.el -Functions for decoding rfc2231 headers -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@item flow-fill.el -Interpret RFC2646 "flowed" text. -@c As of 2005-10-27... -There are no Gnus dependencies in this file. - -@item uudecode.el -Elisp native uudecode. -@c As of 2005-12-06... -There are no Gnus dependencies in this file. -@c ... but the custom group is gnus-extract. - -@item canlock.el -Functions for Cancel-Lock feature -@c Cf. draft-ietf-usefor-cancel-lock-01.txt -@c Although this draft has expired, Canlock-Lock revived in 2007 when -@c major news providers (e.g., news.individual.org) started to use it. -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@end table - -@subsection message - -All message composition from Gnus (both mail and news) takes place in -Message mode buffers. Message mode is intended to be a replacement for -Emacs mail mode. There should be no Gnus dependencies in -@file{message.el}. Alas it is not anymore. Patches and suggestions to -remove the dependencies are welcome. - -@c message.el requires nnheader which requires gnus-util. - -@subsection Emacs @acronym{MIME} - -The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME} -functionality for Emacs. - -@acronym{MML} (@acronym{MIME} Meta Language) is supposed to be -independent from Gnus. Alas it is not anymore. Patches and suggestions -to remove the dependencies are welcome. - -@subsection Gnus backends - -The files @file{nn*.el} provide functionality for accessing NNTP -(@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back -ends (probably @file{nnml.el}, @file{nnfolder.el} and -@file{nnmaildir.el} are the most widely used mail back ends). - -@c mm-uu requires nnheader which requires gnus-util. message.el also -@c requires nnheader. - - -@section Compatibility - -No Gnus and Gnus 5.10.10 and up should work on: -@itemize @bullet -@item -Emacs 21.1 and up. -@item -XEmacs 21.4 and up. -@end itemize - -Gnus 5.10.8 and below should work on: -@itemize @bullet -@item -Emacs 20.7 and up. -@item -XEmacs 21.1 and up. -@end itemize - -@node Gnus Maintenance Guide -@chapter Gnus Maintenance Guide - -@section Stable and development versions - -The development of Gnus normally is done on the Git repository trunk -as of April 19, 2010 (formerly it was done in CVS; the repository is -at http://git.gnus.org), i.e., there are no separate branches to -develop and test new features. Most of the time, the trunk is -developed quite actively with more or less daily changes. Only after -a new major release, e.g., 5.10.1, there's usually a feature period of -several months. After the release of Gnus 5.10.6 the development of -new features started again on the trunk while the 5.10 series is -continued on the stable branch (v5-10) from which more stable releases -will be done when needed (5.10.8, @dots{}). @ref{Gnus Development, -,Gnus Development, gnus, The Gnus Newsreader} - -Stable releases of Gnus finally become part of Emacs. E.g., Gnus 5.8 -became a part of Emacs 21 (relabeled to Gnus 5.9). The 5.10 series -became part of Emacs 22 as Gnus 5.11. - -@section Syncing - -@c Some MIDs related to this follow. Use http://thread.gmane.org/MID -@c (and click on the subject) to get the thread on Gmane. - -@c Some quotes from Miles Bader follow... - -@c -@c - -In the past, the inclusion of Gnus into Emacs was quite cumbersome. For -each change made to Gnus in Emacs repository, it had to be checked that -it was applied to the new Gnus version, too. Else, bug fixes done in -Emacs repository might have been lost. - -With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus -gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus -CVS semi-automatically. - -After Emacs moved to bzr and Gnus moved to git, Katsumi Yamaoka has -taken over the chore of keeping Emacs and Gnus in sync. In general, -changes made to one repository will usually be replicated in the other -within a few days. - -Basically the idea is that the gateway will cause all common files in -Emacs and Gnus v5-13 to be identical except when there's a very good -reason (e.g., the Gnus version string in Emacs says @samp{5.11}, but -the v5-13 version string remains @samp{5.13.x}). Furthermore, all -changes in these files in either Emacs or the v5-13 branch will be -installed into the Gnus git trunk, again except where there's a good -reason. - -@c (typically so far the only exception has been that the changes -@c already exist in the trunk in modified form). -Because of this, when the next major version of Gnus will be included in -Emacs, it should be very easy---just plonk in the files from the Gnus -trunk without worrying about lost changes from the Emacs tree. - -The effect of this is that as hacker, you should generally only have to -make changes in one place: - -@itemize -@item -If it's a file which is thought of as being outside of Gnus (e.g., the -new @file{encrypt.el}), you should probably make the change in the Emacs -tree, and it will show up in the Gnus tree a few days later. - -If you don't have Emacs bzr access (or it's inconvenient), you can -change such a file in the v5-10 branch, and it should propagate to Emacs -bzr---however, it will get some extra scrutiny (by Miles) to see if the -changes are possibly controversial and need discussion on the mailing -list. Many changes are obvious bug-fixes however, so often there won't -be any problem. - -@item -If it's to a Gnus file, and it's important enough that it should be part -of Emacs and the v5-10 branch, then you can make the change on the v5-10 -branch, and it will go into Emacs bzr and the Gnus git trunk (a few days -later). The most prominent examples for such changes are bug-fixed -including improvements on the documentation. - -If you know that there will be conflicts (perhaps because the affected -source code is different in v5-10 and the Gnus git trunk), then you can -install your change in both places, and when I try to sync them, there -will be a conflict---however, since in most such cases there would be a -conflict @emph{anyway}, it's often easier for me to resolve it simply if -I see two @samp{identical} changes, and can just choose the proper one, -rather than having to actually fix the code. - -@item -For general Gnus development changes, of course you just make the -change on the Gnus Git trunk and it goes into Emacs a few years -later... :-) - -@end itemize - -Of course in any case, if you just can't wait for me to sync your -change, you can commit it in more than one place and probably there will -be no problem; usually the changes are textually identical anyway, so -can be easily resolved automatically (sometimes I notice silly things in -such multiple commits, like whitespace differences, and unify those ;-). - - -@c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to -@c require more manual work. - -@c By default I sync about once a week. I also try to follow any Gnus -@c threads on the mailing lists and make sure any changes being discussed -@c are kept more up-to-date (so say 1-2 days delay for "topical" changes). - -@c - -@c BTW, just to add even more verbose explanation about the syncing thing: - -@section Miscellanea - -@heading @file{GNUS-NEWS} - -Starting from No Gnus, the @file{GNUS-NEWS} is created from -@file{texi/gnus-news.texi}. Don't edit @file{GNUS-NEWS}. Edit -@file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the -@file{texi} directory and commit @file{GNUS-NEWS} and -@file{texi/gnus-news.texi}. - -@heading Conventions for version information in defcustoms - -For new customizable variables introduced in Oort Gnus (including the -v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} (including the -comment) or, e.g., @code{:version "22.2" ;; Gnus 5.10.10} if the feature -was added for Emacs 22.2 and Gnus 5.10.10. -@c -If the variable is new in No Gnus use @code{:version "23.1" ;; No Gnus}. - -The same applies for customizable variables when its default value was -changed. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@c Local Variables: -@c mode: texinfo -@c coding: utf-8 -@c End: diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi deleted file mode 100644 index 7bb89fdf029..00000000000 --- a/doc/misc/gnus-faq.texi +++ /dev/null @@ -1,2293 +0,0 @@ -@c \input texinfo @c -*-texinfo-*- -@c Uncomment 1st line before texing this file alone. -@c %**start of header -@c Copyright (C) 1995, 2001-2014 Free Software Foundation, Inc. -@c -@c @setfilename gnus-faq.info -@c @settitle Frequently Asked Questions -@c @documentencoding UTF-8 -@c %**end of header -@c - -@node Frequently Asked Questions -@section Frequently Asked Questions - -@menu -* FAQ - Changes:: -* FAQ - Introduction:: About Gnus and this FAQ. -* FAQ 1 - Installation FAQ:: Installation of Gnus. -* FAQ 2 - Startup / Group buffer:: Start up questions and the - first buffer Gnus shows you. -* FAQ 3 - Getting Messages:: Making Gnus read your mail - and news. -* FAQ 4 - Reading messages:: How to efficiently read - messages. -* FAQ 5 - Composing messages:: Composing mails or Usenet - postings. -* FAQ 6 - Old messages:: Importing, archiving, - searching and deleting messages. -* FAQ 7 - Gnus in a dial-up environment:: Reading mail and news while - offline. -* FAQ 8 - Getting help:: When this FAQ isn't enough. -* FAQ 9 - Tuning Gnus:: How to make Gnus faster. -* FAQ - Glossary:: Terms used in the FAQ - explained. -@end menu - -@subheading Abstract - -This is the new Gnus Frequently Asked Questions list. - -Please submit features and suggestions to the -@email{ding@@gnus.org, ding list}. - -@node FAQ - Changes -@subsection Changes - - - -@itemize @bullet - -@item -2008-06-15: Adjust for message-fill-column. Add x-face-file. -Clarify difference between ding and gnu.emacs.gnus. Remove -reference to discontinued service. - -@item -2006-04-15: Added tip on how to delete sent buffer on exit. -@end itemize - -@node FAQ - Introduction -@subsection Introduction - -This is the Gnus Frequently Asked Questions list. - -Gnus is a Usenet Newsreader and Electronic Mail User Agent implemented -as a part of Emacs. It's been around in some form for almost a decade -now, and has been distributed as a standard part of Emacs for much of -that time. Gnus 5 is the latest (and greatest) incarnation. The -original version was called GNUS, and was written by Masanobu UMEDA@. -When autumn crept up in '94, Lars Magne Ingebrigtsen grew bored and -decided to rewrite Gnus. - -Its biggest strength is the fact that it is extremely -customizable. It is somewhat intimidating at first glance, but -most of the complexity can be ignored until you're ready to take -advantage of it. If you receive a reasonable volume of e-mail -(you're on various mailing lists), or you would like to read -high-volume mailing lists but cannot keep up with them, or read -high volume newsgroups or are just bored, then Gnus is what you -want. - -This FAQ was maintained by Justin Sheehy until March 2002. He -would like to thank Steve Baur and Per Abrahamsen for doing a wonderful -job with this FAQ before him. We would like to do the same: thanks, -Justin! - -This version is much nicer than the unofficial hypertext -versions that are archived at Utrecht, Oxford, Smart Pages, Ohio -State, and other FAQ archives. See the resources question below -if you want information on obtaining it in another format. - -The information contained here was compiled with the assistance -of the Gnus development mailing list, and any errors or -misprints are the Gnus team's fault, sorry. - -@node FAQ 1 - Installation FAQ -@subsection Installation FAQ - -@menu -* FAQ 1-1:: What is the latest version of Gnus? -* FAQ 1-2:: What's new in 5.10? -* FAQ 1-3:: Where and how to get Gnus? -* FAQ 1-4:: What to do with the tarball now? -* FAQ 1-5:: I sometimes read references to No Gnus and Oort Gnus, - what are those? -* FAQ 1-6:: Which version of Emacs do I need? -* FAQ 1-7:: How do I run Gnus on both Emacs and XEmacs? -@end menu - -@node FAQ 1-1 -@subsubheading Question 1.1 - -What is the latest version of Gnus? - -@subsubheading Answer - -Jingle please: Gnus 5.10 is released, get it while it's -hot! As well as the step in version number is rather -small, Gnus 5.10 has tons of new features which you -shouldn't miss. The current release (5.13) should be at -least as stable as the latest release of the 5.8 series. - -@node FAQ 1-2 -@subsubheading Question 1.2 - -What's new in 5.10? - -@subsubheading Answer - -First of all, you should have a look into the file -GNUS-NEWS in the toplevel directory of the Gnus tarball, -there the most important changes are listed. Here's a -short list of the changes I find especially -important/interesting: - -@itemize @bullet - -@item -Major rewrite of the Gnus agent, Gnus agent is now -active by default. - -@item -Many new article washing functions for dealing with -ugly formatted articles. - -@item -Anti Spam features. - -@item -Message-utils now included in Gnus. - -@item -New format specifiers for summary lines, e.g., %B for -a complex trn-style thread tree. -@end itemize - -@node FAQ 1-3 -@subsubheading Question 1.3 - -Where and how to get Gnus? - -@subsubheading Answer - -Gnus is released independent from releases of Emacs and XEmacs. -Therefore, the version bundled with Emacs or the version in XEmacs's -package system might not be up to date (e.g., Gnus 5.9 bundled with Emacs -21 is outdated). -You can get the latest released version of Gnus from -@uref{http://www.gnus.org/dist/gnus.tar.gz} -or via anonymous FTP from -@uref{ftp://ftp.gnus.org/pub/gnus/gnus.tar.gz}. - -@node FAQ 1-4 -@subsubheading Question 1.4 - -What to do with the tarball now? - -@subsubheading Answer - -Untar it via @samp{tar xvzf gnus.tar.gz} and do the common -@samp{./configure; make; make install} circle. -(under MS-Windows either get the Cygwin environment from -@uref{http://www.cygwin.com} -which allows you to do what's described above or unpack the -tarball with some packer (e.g., Winace from -@uref{http://www.winace.com}) -and use the batch-file make.bat included in the tarball to install -Gnus.) If you don't want to (or aren't allowed to) install Gnus -system-wide, you can install it in your home directory and add the -following lines to your ~/.xemacs/init.el or ~/.emacs: - -@example -(add-to-list 'load-path "/path/to/gnus/lisp") -(if (featurep 'xemacs) - (add-to-list 'Info-directory-list "/path/to/gnus/texi/") - (add-to-list 'Info-default-directory-list "/path/to/gnus/texi/")) -@end example -@noindent - -Make sure that you don't have any Gnus related stuff -before this line, on MS Windows use something like -"C:/path/to/lisp" (yes, "/"). - -@node FAQ 1-5 -@subsubheading Question 1.5 - -I sometimes read references to No Gnus and Oort Gnus, -what are those? - -@subsubheading Answer - -Oort Gnus was the name of the development version of -Gnus, which became Gnus 5.10 in autumn 2003. No Gnus is -the name of the current development version which will -once become Gnus 5.12 or Gnus 6. (If you're wondering why -not 5.11, the odd version numbers are normally used for -the Gnus versions bundled with Emacs) - -@node FAQ 1-6 -@subsubheading Question 1.6 - -Which version of Emacs do I need? - -@subsubheading Answer - -Gnus 5.13 requires an Emacs version that is greater than or equal -to Emacs 23.1 or XEmacs 21.1, although there are some features that -only work on Emacs 24. - -@node FAQ 1-7 -@subsubheading Question 1.7 - -How do I run Gnus on both Emacs and XEmacs? - -@subsubheading Answer - -You can't use the same copy of Gnus in both as the Lisp -files are byte-compiled to a format which is different -depending on which Emacs did the compilation. Get one copy -of Gnus for Emacs and one for XEmacs. - -@node FAQ 2 - Startup / Group buffer -@subsection Startup / Group buffer - -@menu -* FAQ 2-1:: Every time I start Gnus I get a message "Gnus auto-save - file exists. Do you want to read it?", what does this mean and - how to prevent it? -* FAQ 2-2:: Gnus doesn't remember which groups I'm subscribed to, - what's this? -* FAQ 2-3:: How to change the format of the lines in Group buffer? -* FAQ 2-4:: My group buffer becomes a bit crowded, is there a way to - sort my groups into categories so I can easier browse through - them? -* FAQ 2-5:: How to manually sort the groups in Group buffer? How to - sort the groups in a topic? -@end menu - -@node FAQ 2-1 -@subsubheading Question 2.1 - -Every time I start Gnus I get a message "Gnus auto-save -file exists. Do you want to read it?", what does this mean -and how to prevent it? - -@subsubheading Answer - -This message means that the last time you used Gnus, it -wasn't properly exited and therefore couldn't write its -information to disk (e.g., which messages you read), you -are now asked if you want to restore that information -from the auto-save file. - -To prevent this message make sure you exit Gnus -via @samp{q} in group buffer instead of -just killing Emacs. - -@node FAQ 2-2 -@subsubheading Question 2.2 - -Gnus doesn't remember which groups I'm subscribed to, -what's this? - -@subsubheading Answer - -You get the message described in the q/a pair above while -starting Gnus, right? It's an other symptom for the same -problem, so read the answer above. - -@node FAQ 2-3 -@subsubheading Question 2.3 - -How to change the format of the lines in Group buffer? - -@subsubheading Answer - -You've got to tweak the value of the variable -gnus-group-line-format. See the manual node "Group Line -Specification" for information on how to do this. An -example for this (guess from whose .gnus :-)): - -@example -(setq gnus-group-line-format "%P%M%S[%5t]%5y : %(%g%)\n") -@end example -@noindent - -@node FAQ 2-4 -@subsubheading Question 2.4 - -My group buffer becomes a bit crowded, is there a way to -sort my groups into categories so I can easier browse -through them? - -@subsubheading Answer - -Gnus offers the topic mode, it allows you to sort your -groups in, well, topics, e.g., all groups dealing with -Linux under the topic linux, all dealing with music under -the topic music and all dealing with scottish music under -the topic scottish which is a subtopic of music. - -To enter topic mode, just hit t while in Group buffer. Now -you can use @samp{T n} to create a topic -at point and @samp{T m} to move a group to -a specific topic. For more commands see the manual or the -menu. You might want to include the %P specifier at the -beginning of your gnus-group-line-format variable to have -the groups nicely indented. - -@node FAQ 2-5 -@subsubheading Question 2.5 - -How to manually sort the groups in Group buffer? How to -sort the groups in a topic? - -@subsubheading Answer - -Move point over the group you want to move and -hit @samp{C-k}, now move point to the -place where you want the group to be and -hit @samp{C-y}. - -@node FAQ 3 - Getting Messages -@subsection Getting Messages - -@menu -* FAQ 3-1:: I just installed Gnus, started it via @samp{M-x gnus} - but it only says "nntp (news) open error", what to do? -* FAQ 3-2:: I'm working under Windows and have no idea what - ~/.gnus.el means. -* FAQ 3-3:: My news server requires authentication, how to store - user name and password on disk? -* FAQ 3-4:: Gnus seems to start up OK, but I can't find out how to - subscribe to a group. -* FAQ 3-5:: Gnus doesn't show all groups / Gnus says I'm not allowed - to post on this server as well as I am, what's that? -* FAQ 3-6:: I want Gnus to fetch news from several servers, is this - possible? -* FAQ 3-7:: And how about local spool files? -* FAQ 3-8:: OK, reading news works now, but I want to be able to - read my mail with Gnus, too. How to do it? -* FAQ 3-9:: And what about IMAP? -* FAQ 3-10:: At the office we use one of those MS Exchange servers, - can I use Gnus to read my mail from it? -* FAQ 3-11:: Can I tell Gnus not to delete the mails on the server it - retrieves via POP3? -@end menu - -@node FAQ 3-1 -@subsubheading Question 3.1 - -I just installed Gnus, started it via -@samp{M-x gnus} -but it only says "nntp (news) open error", what to do? - -@subsubheading Answer - -You've got to tell Gnus where to fetch the news from. Read -the documentation for information on how to do this. As a -first start, put those lines in @file{~/.gnus.el}: - -@example -(setq gnus-select-method '(nntp "news.yourprovider.net")) -(setq user-mail-address "you@@yourprovider.net") -(setq user-full-name "Your Name") -@end example -@noindent - -@node FAQ 3-2 -@subsubheading Question 3.2 - -I'm working under Windows and have no idea what @file{~/.gnus.el} means. - -@subsubheading Answer - -The ~/ means the home directory where Gnus and Emacs look -for the configuration files. However, you don't really -need to know what this means, it suffices that Emacs knows -what it means :-) You can type -@samp{C-x C-f ~/.gnus.el RET } -(yes, with the forward slash, even on Windows), and -Emacs will open the right file for you. (It will most -likely be new, and thus empty.) -However, I'd discourage you from doing so, since the -directory Emacs chooses will most certainly not be what -you want, so let's do it the correct way. -The first thing you've got to do is to -create a suitable directory (no blanks in directory name -please), e.g., c:\myhome. Then you must set the environment -variable HOME to this directory. To do this under Windows 9x -or Me include the line - -@example -SET HOME=C:\myhome -@end example -@noindent - -in your autoexec.bat and reboot. Under NT, 2000 and XP, hit -Winkey+Pause/Break to enter system options (if it doesn't work, go -to Control Panel -> System -> Advanced). There you'll find the -possibility to set environment variables. Create a new one with -name HOME and value C:\myhome. Rebooting is not necessary. - -Now to create @file{~/.gnus.el}, say -@samp{C-x C-f ~/.gnus.el RET C-x C-s}. -in Emacs. - -@node FAQ 3-3 -@subsubheading Question 3.3 - -My news server requires authentication, how to store -user name and password on disk? - -@subsubheading Answer - -Create a file ~/.authinfo which includes for each server a line like this - -@example -machine news.yourprovider.net login YourUserName password YourPassword -@end example -@noindent -. -Make sure that the file isn't readable to others if you -work on a OS which is capable of doing so. (Under Unix -say -@example -chmod 600 ~/.authinfo -@end example -@noindent - -in a shell.) - -@node FAQ 3-4 -@subsubheading Question 3.4 - -Gnus seems to start up OK, but I can't find out how to -subscribe to a group. - -@subsubheading Answer - -If you know the name of the group say @samp{U -name.of.group RET} in group buffer (use the -tab-completion Luke). Otherwise hit ^ in group buffer, -this brings you to the server buffer. Now place point (the -cursor) over the server which carries the group you want, -hit @samp{RET}, move point to the group -you want to subscribe to and say @samp{u} -to subscribe to it. - -@node FAQ 3-5 -@subsubheading Question 3.5 - -Gnus doesn't show all groups / Gnus says I'm not allowed to -post on this server as well as I am, what's that? - -@subsubheading Answer - -Some providers allow restricted anonymous access and full -access only after authorization. To make Gnus send authinfo -to those servers append - -@example -force yes -@end example -@noindent - -to the line for those servers in ~/.authinfo. - -@node FAQ 3-6 -@subsubheading Question 3.6 - -I want Gnus to fetch news from several servers, is this possible? - -@subsubheading Answer - -Of course. You can specify more sources for articles in the -variable gnus-secondary-select-methods. Add something like -this in @file{~/.gnus.el}: - -@example -(add-to-list 'gnus-secondary-select-methods - '(nntp "news.yourSecondProvider.net")) -(add-to-list 'gnus-secondary-select-methods - '(nntp "news.yourThirdProvider.net")) -@end example -@noindent - -@node FAQ 3-7 -@subsubheading Question 3.7 - -And how about local spool files? - -@subsubheading Answer - -No problem, this is just one more select method called -nnspool, so you want this: - -@example -(add-to-list 'gnus-secondary-select-methods '(nnspool "")) -@end example -@noindent - -Or this if you don't want an NNTP Server as primary news source: - -@example -(setq gnus-select-method '(nnspool "")) -@end example -@noindent - -Gnus will look for the spool file in /usr/spool/news, if you -want something different, change the line above to something like this: - -@example -(add-to-list 'gnus-secondary-select-methods - '(nnspool "" - (nnspool-directory "/usr/local/myspoolddir"))) -@end example -@noindent - -This sets the spool directory for this server only. -You might have to specify more stuff like the program used -to post articles, see the Gnus manual on how to do this. - -@node FAQ 3-8 -@subsubheading Question 3.8 - -OK, reading news works now, but I want to be able to read my mail -with Gnus, too. How to do it? - -@subsubheading Answer - -That's a bit harder since there are many possible sources -for mail, many possible ways for storing mail and many -different ways for sending mail. The most common cases are -these: 1: You want to read your mail from a pop3 server and -send them directly to a SMTP Server 2: Some program like -fetchmail retrieves your mail and stores it on disk from -where Gnus shall read it. Outgoing mail is sent by -Sendmail, Postfix or some other MTA@. Sometimes, you even -need a combination of the above cases. - -However, the first thing to do is to tell Gnus in which way -it should store the mail, in Gnus terminology which back end -to use. Gnus supports many different back ends, the most -commonly used one is nnml. It stores every mail in one file -and is therefore quite fast. However you might prefer a one -file per group approach if your file system has problems with -many small files, the nnfolder back end is then probably the -choice for you. To use nnml add the following to @file{~/.gnus.el}: - -@example -(add-to-list 'gnus-secondary-select-methods '(nnml "")) -@end example -@noindent - -As you might have guessed, if you want nnfolder, it's - -@example -(add-to-list 'gnus-secondary-select-methods '(nnfolder "")) -@end example -@noindent - -Now we need to tell Gnus, where to get its mail from. If -it's a POP3 server, then you need something like this: - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources '(pop :server "pop.YourProvider.net" - :user "yourUserName" - :password "yourPassword"))) -@end example -@noindent - -Make sure @file{~/.gnus.el} isn't readable to others if you store -your password there. If you want to read your mail from a -traditional spool file on your local machine, it's - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources '(file :path "/path/to/spool/file")) -@end example -@noindent - -If it's a Maildir, with one file per message as used by -postfix, Qmail and (optionally) fetchmail it's - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources '(maildir :path "/path/to/Maildir/" - :subdirs ("cur" "new"))) -@end example -@noindent - -And finally if you want to read your mail from several files -in one directory, for example because procmail already split your -mail, it's - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources - '(directory :path "/path/to/procmail-dir/" - :suffix ".prcml"))) -@end example -@noindent - -Where :suffix ".prcml" tells Gnus only to use files with the -suffix .prcml. - -OK, now you only need to tell Gnus how to send mail. If you -want to send mail via sendmail (or whichever MTA is playing -the role of sendmail on your system), you don't need to do -anything. However, if you want to send your mail to an -SMTP Server you need the following in your @file{~/.gnus.el} - -@example -(setq send-mail-function 'smtpmail-send-it) -(setq message-send-mail-function 'smtpmail-send-it) -(setq smtpmail-default-smtp-server "smtp.yourProvider.net") -@end example -@noindent - -@node FAQ 3-9 -@subsubheading Question 3.9 - -And what about IMAP? - -@subsubheading Answer - -There are two ways of using IMAP with Gnus. The first one is -to use IMAP like POP3, that means Gnus fetches the mail from -the IMAP server and stores it on disk. If you want to do -this (you don't really want to do this) add the following to -@file{~/.gnus.el} - -@example -(add-to-list 'mail-sources '(imap :server "mail.mycorp.com" - :user "username" - :pass "password" - :stream network - :authentication login - :mailbox "INBOX" - :fetchflag "\\Seen")) -@end example -@noindent - -You might have to tweak the values for stream and/or -authentication, see the Gnus manual node "Mail Source -Specifiers" for possible values. - -If you want to use IMAP the way it's intended, you've got to -follow a different approach. You've got to add the nnimap -back end to your select method and give the information -about the server there. - -@example -(add-to-list 'gnus-secondary-select-methods - '(nnimap "Give the baby a name" - (nnimap-address "imap.yourProvider.net") - (nnimap-port 143) - (nnimap-list-pattern "archive.*"))) -@end example -@noindent - -Again, you might have to specify how to authenticate to the -server if Gnus can't guess the correct way, see the Manual -Node "IMAP" for detailed information. - -@node FAQ 3-10 -@subsubheading Question 3.10 - -At the office we use one of those MS Exchange servers, can I use -Gnus to read my mail from it? - -@subsubheading Answer - -Offer your administrator a pair of new running shoes for -activating IMAP on the server and follow the instructions -above. - -@node FAQ 3-11 -@subsubheading Question 3.11 - -Can I tell Gnus not to delete the mails on the server it -retrieves via POP3? - -@subsubheading Answer - -Yes, if the POP3 server supports the UIDL control (maybe almost servers -do it nowadays). To do that, add a @code{:leave VALUE} pair to each -POP3 mail source. See @pxref{Mail Source Specifiers} for VALUE. - -@node FAQ 4 - Reading messages -@subsection Reading messages - -@menu -* FAQ 4-1:: When I enter a group, all read messages are gone. How to - view them again? -* FAQ 4-2:: How to tell Gnus to show an important message every time - I enter a group, even when it's read? -* FAQ 4-3:: How to view the headers of a message? -* FAQ 4-4:: How to view the raw unformatted message? -* FAQ 4-5:: How can I change the headers Gnus displays by default at - the top of the article buffer? -* FAQ 4-6:: I'd like Gnus NOT to render HTML-mails but show me the - text part if it's available. How to do it? -* FAQ 4-7:: Can I use some other browser than w3 to render my - HTML-mails? -* FAQ 4-8:: Is there anything I can do to make poorly formatted - mails more readable? -* FAQ 4-9:: Is there a way to automatically ignore posts by specific - authors or with specific words in the subject? And can I - highlight more interesting ones in some way? -* FAQ 4-10:: How can I disable threading in some (e.g., mail-) groups, - or set other variables specific for some groups? -* FAQ 4-11:: Can I highlight messages written by me and follow-ups to - those? -* FAQ 4-12:: The number of total messages in a group which Gnus - displays in group buffer is by far to high, especially in mail - groups. Is this a bug? -* FAQ 4-13:: I don't like the layout of summary and article buffer, - how to change it? Perhaps even a three pane display? -* FAQ 4-14:: I don't like the way the Summary buffer looks, how to - tweak it? -* FAQ 4-15:: How to split incoming mails in several groups? -@end menu - -@node FAQ 4-1 -@subsubheading Question 4.1 - -When I enter a group, all read messages are gone. How to view them again? - -@subsubheading Answer - -If you enter the group by saying -@samp{RET} -in group buffer with point over the group, only unread and ticked messages are loaded. Say -@samp{C-u RET} -instead to load all available messages. If you want only the 300 newest say -@samp{C-u 300 RET} - -Loading only unread messages can be annoying if you have threaded view enabled, say - -@example -(setq gnus-fetch-old-headers 'some) -@end example -@noindent - -in @file{~/.gnus.el} to load enough old articles to prevent teared threads, replace 'some with @code{t} to load -all articles (Warning: Both settings enlarge the amount of data which is -fetched when you enter a group and slow down the process of entering a group). - -If you already use Gnus 5.10, you can say -@samp{/o N} -In summary buffer to load the last N messages, this feature is not available in 5.8.8 - -If you don't want all old messages, but the parent of the message you're just reading, -you can say @samp{^}, if you want to retrieve the whole thread -the message you're just reading belongs to, @samp{A T} is your friend. - -@node FAQ 4-2 -@subsubheading Question 4.2 - -How to tell Gnus to show an important message every time I -enter a group, even when it's read? - -@subsubheading Answer - -You can tick important messages. To do this hit -@samp{u} while point is in summary buffer -over the message. When you want to remove the mark, hit -either @samp{d} (this deletes the tick -mark and set's unread mark) or @samp{M c} -(which deletes all marks for the message). - -@node FAQ 4-3 -@subsubheading Question 4.3 - -How to view the headers of a message? - -@subsubheading Answer - -Say @samp{t} -to show all headers, one more -@samp{t} -hides them again. - -@node FAQ 4-4 -@subsubheading Question 4.4 - -How to view the raw unformatted message? - -@subsubheading Answer - -Say -@samp{C-u g} -to show the raw message -@samp{g} -returns to normal view. - -@node FAQ 4-5 -@subsubheading Question 4.5 - -How can I change the headers Gnus displays by default at -the top of the article buffer? - -@subsubheading Answer - -The variable gnus-visible-headers controls which headers -are shown, its value is a regular expression, header lines -which match it are shown. So if you want author, subject, -date, and if the header exists, Followup-To and MUA / NUA -say this in @file{~/.gnus.el}: - -@example -(setq gnus-visible-headers - '("^From" "^Subject" "^Date" "^Newsgroups" "^Followup-To" - "^User-Agent" "^X-Newsreader" "^X-Mailer")) -@end example -@noindent - -@node FAQ 4-6 -@subsubheading Question 4.6 - -I'd like Gnus NOT to render HTML-mails but show me the -text part if it's available. How to do it? - -@subsubheading Answer - -Say - -@example -(eval-after-load "mm-decode" - '(progn - (add-to-list 'mm-discouraged-alternatives "text/html") - (add-to-list 'mm-discouraged-alternatives "text/richtext"))) -@end example -@noindent - -in @file{~/.gnus.el}. If you don't want HTML rendered, even if there's no text alternative add - -@example -(setq mm-automatic-display (remove "text/html" mm-automatic-display)) -@end example -@noindent - -too. - -@node FAQ 4-7 -@subsubheading Question 4.7 - -Can I use some other browser than w3 to render my HTML-mails? - -@subsubheading Answer - -Only if you use Gnus 5.10 or younger. In this case you've got the -choice between w3, w3m, links, lynx and html2text, which -one is used can be specified in the variable -mm-text-html-renderer, so if you want links to render your -mail say - -@example -(setq mm-text-html-renderer 'links) -@end example -@noindent - -@node FAQ 4-8 -@subsubheading Question 4.8 - -Is there anything I can do to make poorly formatted mails -more readable? - -@subsubheading Answer - -Gnus offers you several functions to "wash" incoming mail, you can -find them if you browse through the menu, item -Article->Washing. The most interesting ones are probably "Wrap -long lines" (@samp{W w}), "Decode ROT13" -(@samp{W r}) and "Outlook Deuglify" which repairs -the dumb quoting used by many users of Microsoft products -(@samp{W Y f} gives you full deuglify. -See @samp{W Y C-h} or have a look at the menus for -other deuglifications). Outlook deuglify is only available since -Gnus 5.10. - -@node FAQ 4-9 -@subsubheading Question 4.9 - -Is there a way to automatically ignore posts by specific -authors or with specific words in the subject? And can I -highlight more interesting ones in some way? - -@subsubheading Answer - -You want Scoring. Scoring means, that you define rules -which assign each message an integer value. Depending on -the value the message is highlighted in summary buffer (if -it's high, say +2000) or automatically marked read (if the -value is low, say -800) or some other action happens. - -There are basically three ways of setting up rules which assign -the scoring-value to messages. The first and easiest way is to set -up rules based on the article you are just reading. Say you're -reading a message by a guy who always writes nonsense and you want -to ignore his messages in the future. Hit -@samp{L}, to set up a rule which lowers the score. -Now Gnus asks you which the criteria for lowering the Score shall -be. Hit @samp{?} twice to see all possibilities, -we want @samp{a} which means the author (the from -header). Now Gnus wants to know which kind of matching we want. -Hit either @samp{e} for an exact match or -@samp{s} for substring-match and delete afterwards -everything but the name to score down all authors with the given -name no matter which email address is used. Now you need to tell -Gnus when to apply the rule and how long it should last, hit -@samp{p} to apply the rule now and let it last -forever. If you want to raise the score instead of lowering it say -@samp{I} instead of @samp{L}. - -You can also set up rules by hand. To do this say @samp{V -f} in summary buffer. Then you are asked for the name -of the score file, it's name.of.group.SCORE for rules valid in -only one group or all.Score for rules valid in all groups. See the -Gnus manual for the exact syntax, basically it's one big list -whose elements are lists again. the first element of those lists -is the header to score on, then one more list with what to match, -which score to assign, when to expire the rule and how to do the -matching. If you find me very interesting, you could add the -following to your all.Score: - -@example -(("references" ("hschmi22.userfqdn.rz-online.de" 500 nil s)) - ("message-id" ("hschmi22.userfqdn.rz-online.de" 999 nil s))) -@end example -@noindent - -This would add 999 to the score of messages written by me -and 500 to the score of messages which are a (possibly -indirect) answer to a message written by me. Of course -nobody with a sane mind would do this :-) - -The third alternative is adaptive scoring. This means Gnus -watches you and tries to find out what you find -interesting and what annoying and sets up rules -which reflect this. Adaptive scoring can be a huge help -when reading high traffic groups. If you want to activate -adaptive scoring say - -@example -(setq gnus-use-adaptive-scoring t) -@end example -@noindent - -in @file{~/.gnus.el}. - -@node FAQ 4-10 -@subsubheading Question 4.10 - -How can I disable threading in some (e.g., mail-) groups, or -set other variables specific for some groups? - -@subsubheading Answer - -While in group buffer move point over the group and hit -@samp{G c}, this opens a buffer where you -can set options for the group. At the bottom of the buffer -you'll find an item that allows you to set variables -locally for the group. To disable threading enter -gnus-show-threads as name of variable and @code{nil} as -value. Hit button done at the top of the buffer when -you're ready. - -@node FAQ 4-11 -@subsubheading Question 4.11 - -Can I highlight messages written by me and follow-ups to -those? - -@subsubheading Answer - -Stop those "Can I ..." questions, the answer is always yes -in Gnus Country :-). It's a three step process: First we -make faces (specifications of how summary-line shall look -like) for those postings, then we'll give them some -special score and finally we'll tell Gnus to use the new -faces. - -@node FAQ 4-12 -@subsubheading Question 4.12 - -The number of total messages in a group which Gnus -displays in group buffer is by far to high, especially in -mail groups. Is this a bug? - -@subsubheading Answer - -No, that's a matter of design of Gnus, fixing this would -mean reimplementation of major parts of Gnus' -back ends. Gnus thinks "highest-article-number @minus{} -lowest-article-number = total-number-of-articles". This -works OK for Usenet groups, but if you delete and move -many messages in mail groups, this fails. To cure the -symptom, enter the group via @samp{C-u RET} -(this makes Gnus get all messages), then -hit @samp{M P b} to mark all messages and -then say @samp{B m name.of.group} to move -all messages to the group they have been in before, they -get new message numbers in this process and the count is -right again (until you delete and move your mail to other -groups again). - -@node FAQ 4-13 -@subsubheading Question 4.13 - -I don't like the layout of summary and article buffer, how -to change it? Perhaps even a three pane display? - -@subsubheading Answer - -You can control the windows configuration by calling the -function gnus-add-configuration. The syntax is a bit -complicated but explained very well in the manual node -"Window Layout". Some popular examples: - -Instead 25% summary 75% article buffer 35% summary and 65% -article (the 1.0 for article means "take the remaining -space"): - -@example -(gnus-add-configuration - '(article (vertical 1.0 (summary .35 point) (article 1.0)))) -@end example -@noindent - -A three pane layout, Group buffer on the left, summary -buffer top-right, article buffer bottom-right: - -@example -(gnus-add-configuration - '(article - (horizontal 1.0 - (vertical 25 - (group 1.0)) - (vertical 1.0 - (summary 0.25 point) - (article 1.0))))) -(gnus-add-configuration - '(summary - (horizontal 1.0 - (vertical 25 - (group 1.0)) - (vertical 1.0 - (summary 1.0 point))))) -@end example -@noindent - -@node FAQ 4-14 -@subsubheading Question 4.14 - -I don't like the way the Summary buffer looks, how to tweak it? - -@subsubheading Answer - -You've got to play around with the variable -gnus-summary-line-format. Its value is a string of -symbols which stand for things like author, date, subject -etc. A list of the available specifiers can be found in the -manual node "Summary Buffer Lines" and the often forgotten -node "Formatting Variables" and its sub-nodes. There -you'll find useful things like positioning the cursor and -tabulators which allow you a summary in table form, but -sadly hard tabulators are broken in 5.8.8. - -Since 5.10, Gnus offers you some very nice new specifiers, -e.g., %B which draws a thread-tree and %&user-date which -gives you a date where the details are dependent of the -articles age. Here's an example which uses both: - -@example -(setq gnus-summary-line-format ":%U%R %B %s %-60=|%4L |%-20,20f |%&user-date; \n") -@end example -@noindent - -resulting in: - -@example -:O Re: [Richard Stallman] rfc2047.el | 13 |Lars Magne Ingebrigt |Sat 23:06 -:O Re: Revival of the ding-patches list | 13 |Lars Magne Ingebrigt |Sat 23:12 -:R > Re: Find correct list of articles for a gro| 25 |Lars Magne Ingebrigt |Sat 23:16 -:O \-> ... | 21 |Kai Grossjohann | 0:01 -:R > Re: Cry for help: deuglify.el - moving stuf| 28 |Lars Magne Ingebrigt |Sat 23:34 -:O \-> ... | 115 |Raymond Scholz | 1:24 -:O \-> ... | 19 |Lars Magne Ingebrigt |15:33 -:O Slow mailing list | 13 |Lars Magne Ingebrigt |Sat 23:49 -:O Re: `@@' mark not documented | 13 |Lars Magne Ingebrigt |Sat 23:50 -:R > Re: Gnus still doesn't count messages prope| 23 |Lars Magne Ingebrigt |Sat 23:57 -:O \-> ... | 18 |Kai Grossjohann | 0:35 -:O \-> ... | 13 |Lars Magne Ingebrigt | 0:56 -@end example -@noindent - -@node FAQ 4-15 -@subsubheading Question 4.15 - -How to split incoming mails in several groups? - -@subsubheading Answer - -Gnus offers two possibilities for splitting mail, the easy -nnmail-split-methods and the more powerful Fancy Mail -Splitting. I'll only talk about the first one, refer to -the manual, node "Fancy Mail Splitting" for the latter. - -The value of nnmail-split-methods is a list, each element -is a list which stands for a splitting rule. Each rule has -the form "group where matching articles should go to", -"regular expression which has to be matched", the first -rule which matches wins. The last rule must always be a -general rule (regular expression .*) which denotes where -articles should go which don't match any other rule. If -the folder doesn't exist yet, it will be created as soon -as an article lands there. By default the mail will be -send to all groups whose rules match. If you -don't want that (you probably don't want), say - -@example -(setq nnmail-crosspost nil) -@end example -@noindent - -in @file{~/.gnus.el}. - -An example might be better than thousand words, so here's -my nnmail-split-methods. Note that I send duplicates in a -special group and that the default group is spam, since I -filter all mails out which are from some list I'm -subscribed to or which are addressed directly to me -before. Those rules kill about 80% of the Spam which -reaches me (Email addresses are changed to prevent spammers -from using them): - -@example -(setq nnmail-split-methods - '(("duplicates" "^Gnus-Warning:.*duplicate") - ("XEmacs-NT" "^\\(To:\\|CC:\\).*localpart@@xemacs.invalid.*") - ("Gnus-Tut" "^\\(To:\\|CC:\\).*localpart@@socha.invalid.*") - ("tcsh" "^\\(To:\\|CC:\\).*localpart@@mx.gw.invalid.*") - ("BAfH" "^\\(To:\\|CC:\\).*localpart@@.*uni-muenchen.invalid.*") - ("Hamster-src" "^\\(CC:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") - ("Tagesschau" "^From: tagesschau $") - ("Replies" "^\\(CC:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") - ("EK" "^From:.*\\(localpart@@privateprovider.invalid\\|localpart@@workplace.invalid\\).*") - ("Spam" "^Content-Type:.*\\(ks_c_5601-1987\\|EUC-KR\\|big5\\|iso-2022-jp\\).*") - ("Spam" "^Subject:.*\\(This really work\\|XINGA\\|ADV:\\|XXX\\|adult\\|sex\\).*") - ("Spam" "^Subject:.*\\(\=\?ks_c_5601-1987\?\\|\=\?euc-kr\?\\|\=\?big5\?\\).*") - ("Spam" "^X-Mailer:\\(.*BulkMailer.*\\|.*MIME::Lite.*\\|\\)") - ("Spam" "^X-Mailer:\\(.*CyberCreek Avalanche\\|.*http\:\/\/GetResponse\.com\\)") - ("Spam" "^From:.*\\(verizon\.net\\|prontomail\.com\\|money\\|ConsumerDirect\\).*") - ("Spam" "^Delivered-To: GMX delivery to spamtrap@@gmx.invalid$") - ("Spam" "^Received: from link2buy.com") - ("Spam" "^CC: .*azzrael@@t-online.invalid") - ("Spam" "^X-Mailer-Version: 1.50 BETA") - ("Uni" "^\\(CC:\\|To:\\).*localpart@@uni-koblenz.invalid.*") - ("Inbox" "^\\(CC:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|address@@two.invalid\\)") - ("Spam" ""))) -@end example -@noindent - -@node FAQ 5 - Composing messages -@subsection Composing messages - -@menu -* FAQ 5-1:: What are the basic commands I need to know for sending - mail and postings? -* FAQ 5-2:: How to enable automatic word-wrap when composing - messages? -* FAQ 5-3:: How to set stuff like From, Organization, Reply-To, - signature...? -* FAQ 5-4:: Can I set things like From, Signature etc. group based on - the group I post too? -* FAQ 5-5:: Is there a spell-checker? Perhaps even on-the-fly - spell-checking? -* FAQ 5-6:: Can I set the dictionary based on the group I'm posting - to? -* FAQ 5-7:: Is there some kind of address-book, so I needn't - remember all those email addresses? -* FAQ 5-8:: Sometimes I see little images at the top of article - buffer. What's that and how can I send one with my postings, - too? -* FAQ 5-9:: Sometimes I accidentally hit r instead of f in - newsgroups. Can Gnus warn me, when I'm replying by mail in - newsgroups? -* FAQ 5-10:: How to tell Gnus not to generate a sender header? -* FAQ 5-11:: I want Gnus to locally store copies of my send mail and - news, how to do it? -* FAQ 5-12:: I want Gnus to kill the buffer after successful sending - instead of keeping it alive as "Sent mail to...", how to do it? -* FAQ 5-13:: People tell me my Message-IDs are not correct, why - aren't they and how to fix it? -@end menu - -@node FAQ 5-1 -@subsubheading Question 5.1 - -What are the basic commands I need to know for sending mail and postings? - -@subsubheading Answer - -To start composing a new mail hit @samp{m} -either in Group or Summary buffer, for a posting, it's -either @samp{a} in Group buffer and -filling the Newsgroups header manually -or @samp{a} in the Summary buffer of the -group where the posting shall be send to. Replying by mail -is -@samp{r} if you don't want to cite the -author, or import the cited text manually and -@samp{R} to cite the text of the original -message. For a follow up to a newsgroup, it's -@samp{f} and @samp{F} -(analogously to @samp{r} and -@samp{R}). - -Enter new headers above the line saying "--text follows -this line--", enter the text below the line. When ready -hit @samp{C-c C-c}, to send the message, -if you want to finish it later hit @samp{C-c -C-d} to save it in the drafts group, where you -can start editing it again by saying @samp{D -e}. - -@node FAQ 5-2 -@subsubheading Question 5.2 - -How to enable automatic word-wrap when composing messages? - -@subsubheading Answer - -Starting from No Gnus, automatic word-wrap is already enabled by -default, see the variable message-fill-column. - -For other versions of Gnus, say - -@example -(unless (boundp 'message-fill-column) - (add-hook 'message-mode-hook - (lambda () - (setq fill-column 72) - (turn-on-auto-fill)))) -@end example -@noindent - -in @file{~/.gnus.el}. - -You can reformat a paragraph by hitting @samp{M-q} -(as usual). - -@node FAQ 5-3 -@subsubheading Question 5.3 - -How to set stuff like From, Organization, Reply-To, signature...? - -@subsubheading Answer - -There are other ways, but you should use posting styles -for this. (See below why). -This example should make the syntax clear: - -@example -(setq gnus-posting-styles - '((".*" - (name "Frank Schmitt") - (address "me@@there.invalid") - (organization "Hamme net, kren mer och nimmi") - (signature-file "~/.signature") - ("X-SampleHeader" "foobar") - (eval (setq some-variable "Foo bar"))))) -@end example -@noindent - -The ".*" means that this settings are the default ones -(see below), valid values for the first element of the -following lists are signature, signature-file, -organization, address, name or body. The attribute name -can also be a string. In that case, this will be used as -a header name, and the value will be inserted in the -headers of the article; if the value is @code{nil}, the header -name will be removed. You can also say (eval (foo bar)), -then the function foo will be evaluated with argument bar -and the result will be thrown away. - -@node FAQ 5-4 -@subsubheading Question 5.4 - -Can I set things like From, Signature etc group based on the group I post too? - -@subsubheading Answer - -That's the strength of posting styles. Before, we used ".*" -to set the default for all groups. You can use a regexp -like "^gmane" and the following settings are only applied -to postings you send to the gmane hierarchy, use -".*binaries" instead and they will be applied to postings -send to groups containing the string binaries in their -name etc. - -You can instead of specifying a regexp specify a function -which is evaluated, only if it returns true, the -corresponding settings take effect. Two interesting -candidates for this are message-news-p which returns t if -the current Group is a newsgroup and the corresponding -message-mail-p. - -Note that all forms that match are applied, that means in -the example below, when I post to -gmane.mail.spam.spamassassin.general, the settings under -".*" are applied and the settings under message-news-p and -those under "^gmane" and those under -"^gmane\\.mail\\.spam\\.spamassassin\\.general$". Because -of this put general settings at the top and specific ones -at the bottom. - -@example -(setq gnus-posting-styles - '((".*" ;;default - (name "Frank Schmitt") - (organization "Hamme net, kren mer och nimmi") - (signature-file "~/.signature")) - ((message-news-p) ;;Usenet news? - (address "mySpamTrap@@Frank-Schmitt.invalid") - (reply-to "hereRealRepliesOnlyPlease@@Frank-Schmitt.invalid")) - ((message-mail-p) ;;mail? - (address "usedForMails@@Frank-Schmitt.invalid")) - ("^gmane" ;;this is mail, too in fact - (address "usedForMails@@Frank-Schmitt.invalid") - (reply-to nil)) - ("^gmane\\.mail\\.spam\\.spamassassin\\.general$" - (eval (set (make-local-variable 'message-sendmail-envelope-from) - "Azzrael@@rz-online.de"))))) -@end example -@noindent - -@node FAQ 5-5 -@subsubheading Question 5.5 - -Is there a spell-checker? Perhaps even on-the-fly spell-checking? - -@subsubheading Answer - -You can use ispell.el to spell-check stuff in Emacs. So the -first thing to do is to make sure that you've got either -@uref{http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html, ispell} -or @uref{http://aspell.sourceforge.net/, aspell} -installed and in your Path. Then you need -@uref{http://www.kdstevens.com/~stevens/ispell-page.html, ispell.el} -and for on-the-fly spell-checking -@uref{http://www-sop.inria.fr/members/Manuel.Serrano/flyspell/flyspell.html, flyspell.el}. -Ispell.el is shipped with Emacs and available through the XEmacs package system, -flyspell.el is shipped with Emacs and part of XEmacs text-modes package which is -available through the package system, so there should be no need to install them -manually. - -Ispell.el assumes you use ispell, if you choose aspell say - -@example -(setq ispell-program-name "aspell") -@end example -@noindent - -in your Emacs configuration file. - -If you want your outgoing messages to be spell-checked, say - -@example -(add-hook 'message-send-hook 'ispell-message) -@end example -@noindent - -In your @file{~/.gnus.el}, if you prefer on-the-fly spell-checking say - -@example -(add-hook 'message-mode-hook (lambda () (flyspell-mode 1))) -@end example -@noindent - -@node FAQ 5-6 -@subsubheading Question 5.6 - -Can I set the dictionary based on the group I'm posting to? - -@subsubheading Answer - -Yes, say something like - -@example -(add-hook 'gnus-select-group-hook - (lambda () - (cond - ((string-match - "^de\\." (gnus-group-real-name gnus-newsgroup-name)) - (ispell-change-dictionary "deutsch8")) - (t - (ispell-change-dictionary "english"))))) -@end example -@noindent - -in @file{~/.gnus.el}. Change "^de\\." and "deutsch8" to something -that suits your needs. - -@node FAQ 5-7 -@subsubheading Question 5.7 - -Is there some kind of address-book, so I needn't remember -all those email addresses? - -@subsubheading Answer - -There's an very basic solution for this, mail aliases. -You can store your mail addresses in a ~/.mailrc file using a simple -alias syntax: - -@example -alias al "Al " -@end example -@noindent - -Then typing your alias (followed by a space or punctuation -character) on a To: or Cc: line in the message buffer will -cause Gnus to insert the full address for you. See the -node "Mail Aliases" in Message (not Gnus) manual for -details. - -However, what you really want is the Insidious Big Brother -Database bbdb. Get it through the XEmacs package system or from -@uref{http://bbdb.sourceforge.net/, bbdb's homepage}. -Now place the following in @file{~/.gnus.el}, to activate bbdb for Gnus: - -@example -(require 'bbdb) -(bbdb-initialize 'gnus 'message) -@end example -@noindent - -Now you probably want some general bbdb configuration, -place them in ~/.emacs: - -@example -(require 'bbdb) -;;If you don't live in Northern America, you should disable the -;;syntax check for telephone numbers by saying -(setq bbdb-north-american-phone-numbers-p nil) -;;Tell bbdb about your email address: -(setq bbdb-user-mail-names - (regexp-opt '("Your.Email@@here.invalid" - "Your.other@@mail.there.invalid"))) -;;cycling while completing email addresses -(setq bbdb-complete-name-allow-cycling t) -;;No popup-buffers -(setq bbdb-use-pop-up nil) -@end example -@noindent - -Now you should be ready to go. Say @samp{M-x bbdb RET -RET} to open a bbdb buffer showing all -entries. Say @samp{c} to create a new -entry, @samp{b} to search your BBDB and -@samp{C-o} to add a new field to an -entry. If you want to add a sender to the BBDB you can -also just hit `:' on the posting in the summary buffer and -you are done. When you now compose a new mail, -hit @samp{TAB} to cycle through know -recipients. - -@node FAQ 5-8 -@subsubheading Question 5.8 - -Sometimes I see little images at the top of article -buffer. What's that and how can I send one with my -postings, too? - -@subsubheading Answer - -Those images are called X-Faces. They are 48*48 pixel b/w -pictures, encoded in a header line. If you want to include -one in your posts, you've got to convert some image to a -X-Face. So fire up some image manipulation program (say -Gimp), open the image you want to include, cut out the -relevant part, reduce color depth to 1 bit, resize to -48*48 and save as bitmap. Now you should get the compface -package from -@uref{ftp://ftp.cs.indiana.edu:/pub/faces/, this site}. -and create the actual X-face by saying - -@example -cat file.xbm | xbm2ikon | compface > file.face -cat file.face | sed 's/\\/\\\\/g;s/\"/\\\"/g;' > file.face.quoted -@end example -@noindent - -If you can't use compface, there's an online X-face converter at -@uref{http://www.dairiki.org/xface/}. -If you use MS Windows, you could also use the WinFace program, -which used to be available from -@indicateurl{http://www.xs4all.nl/~walterln/winface/}. -Now you only have to tell Gnus to include the X-face in your postings by saying - -@example -(setq message-default-headers - (with-temp-buffer - (insert "X-Face: ") - (insert-file-contents "~/.xface") - (buffer-string))) -@end example -@noindent - -in @file{~/.gnus.el}. If you use Gnus 5.10, you can simply add an entry - -@example -(x-face-file "~/.xface") -@end example -@noindent - -to gnus-posting-styles. - -@node FAQ 5-9 -@subsubheading Question 5.9 - -Sometimes I accidentally hit r instead of f in -newsgroups. Can Gnus warn me, when I'm replying by mail in -newsgroups? - -@subsubheading Answer - -Put this in @file{~/.gnus.el}: - -@example -(setq gnus-confirm-mail-reply-to-news t) -@end example -@noindent - -if you already use Gnus 5.10, if you still use 5.8.8 or -5.9 try this instead: - -@example -(eval-after-load "gnus-msg" - '(unless (boundp 'gnus-confirm-mail-reply-to-news) - (defadvice gnus-summary-reply (around reply-in-news activate) - "Request confirmation when replying to news." - (interactive) - (when (or (not (gnus-news-group-p gnus-newsgroup-name)) - (y-or-n-p "Really reply by mail to article author? ")) - ad-do-it)))) -@end example -@noindent - -@node FAQ 5-10 -@subsubheading Question 5.10 - -How to tell Gnus not to generate a sender header? - -@subsubheading Answer - -Since 5.10 Gnus doesn't generate a sender header by -default. For older Gnus' try this in @file{~/.gnus.el}: - -@example -(eval-after-load "message" - '(add-to-list 'message-syntax-checks '(sender . disabled))) -@end example -@noindent - -@node FAQ 5-11 -@subsubheading Question 5.11 - -I want Gnus to locally store copies of my send mail and -news, how to do it? - -@subsubheading Answer - -You must set the variable gnus-message-archive-group to do -this. You can set it to a string giving the name of the -group where the copies shall go or like in the example -below use a function which is evaluated and which returns -the group to use. - -@example -(setq gnus-message-archive-group - '((if (message-news-p) - "nnml:Send-News" - "nnml:Send-Mail"))) -@end example -@noindent - -@node FAQ 5-12 -@subsubheading Question 5.12 - -I want Gnus to kill the buffer after successful sending instead of keeping -it alive as "Sent mail to...", how to do it? - -@subsubheading Answer - -Add this to your ~/.gnus: - -@example -(setq message-kill-buffer-on-exit t) -@end example -@noindent - -@node FAQ 5-13 -@subsubheading Question 5.13 - -People tell me my Message-IDs are not correct, why -aren't they and how to fix it? - -@subsubheading Answer - -The message-ID is an unique identifier for messages you -send. To make it unique, Gnus need to know which machine -name to put after the "@@". If the name of the machine -where Gnus is running isn't suitable (it probably isn't -at most private machines) you can tell Gnus what to use -by saying: - -@example -(setq message-user-fqdn "yourmachine.yourdomain.tld") -@end example -@noindent - -in @file{~/.gnus.el}. If you use Gnus 5.9 or earlier, you can use this -instead (works for newer versions as well): - -@example -(eval-after-load "message" - '(let ((fqdn "yourmachine.yourdomain.tld"));; <-- Edit this! - (if (boundp 'message-user-fqdn) - (setq message-user-fqdn fqdn) - (gnus-message 1 "Redefining `message-make-fqdn'.") - (defun message-make-fqdn () - "Return user's fully qualified domain name." - fqdn)))) -@end example -@noindent - -If you have no idea what to insert for -"yourmachine.yourdomain.tld", you've got several -choices. You can either ask your provider if he allows -you to use something like -yourUserName.userfqdn.provider.net, or you can use -somethingUnique.yourdomain.tld if you own the domain -yourdomain.tld, or you can register at a service which -gives private users a FQDN for free. - -Finally you can tell Gnus not to generate a Message-ID -for News at all (and letting the server do the job) by saying - -@example -(setq message-required-news-headers - (remove' Message-ID message-required-news-headers)) -@end example -@noindent - -you can also tell Gnus not to generate Message-IDs for mail by saying - -@example -(setq message-required-mail-headers - (remove' Message-ID message-required-mail-headers)) -@end example -@noindent - -, however some mail servers don't generate proper -Message-IDs, too, so test if your Mail Server behaves -correctly by sending yourself a Mail and looking at the Message-ID. - -@node FAQ 6 - Old messages -@subsection Old messages - -@menu -* FAQ 6-1:: How to import my old mail into Gnus? -* FAQ 6-2:: How to archive interesting messages? -* FAQ 6-3:: How to search for a specific message? -* FAQ 6-4:: How to get rid of old unwanted mail? -* FAQ 6-5:: I want that all read messages are expired (at least in - some groups). How to do it? -* FAQ 6-6:: I don't want expiration to delete my mails but to move - them to another group. -@end menu - -@node FAQ 6-1 -@subsubheading Question 6.1 - -How to import my old mail into Gnus? - -@subsubheading Answer - -The easiest way is to tell your old mail program to -export the messages in mbox format. Most Unix mailers -are able to do this, if you come from the MS Windows -world, you may find tools at -@uref{http://mbx2mbox.sourceforge.net/}. - -Now you've got to import this mbox file into Gnus. To do -this, create a nndoc group based on the mbox file by -saying @samp{G f /path/file.mbox RET} in -Group buffer. You now have read-only access to your -mail. If you want to import the messages to your normal -Gnus mail groups hierarchy, enter the nndoc group you've -just created by saying @samp{C-u RET} -(thus making sure all messages are retrieved), mark all -messages by saying @samp{M P b} and -either copy them to the desired group by saying -@samp{B c name.of.group RET} or send them -through nnmail-split-methods (respool them) by saying -@samp{B r}. - -@node FAQ 6-2 -@subsubheading Question 6.2 - -How to archive interesting messages? - -@subsubheading Answer - -If you stumble across an interesting message, say in -gnu.emacs.gnus and want to archive it there are several -solutions. The first and easiest is to save it to a file -by saying @samp{O f}. However, wouldn't -it be much more convenient to have more direct access to -the archived message from Gnus? If you say yes, put this -snippet by Frank Haun in -@file{~/.gnus.el}: - -@example -(defun my-archive-article (&optional n) - "Copies one or more article(s) to a corresponding `nnml:' group, e.g., -`gnus.ding' goes to `nnml:1.gnus.ding'. And `nnml:List-gnus.ding' goes -to `nnml:1.List-gnus-ding'. - -Use process marks or mark a region in the summary buffer to archive -more then one article." - (interactive "P") - (let ((archive-name - (format - "nnml:1.%s" - (if (featurep 'xemacs) - (replace-in-string gnus-newsgroup-name "^.*:" "") - (replace-regexp-in-string "^.*:" "" gnus-newsgroup-name))))) - (gnus-summary-copy-article n archive-name))) -@end example -@noindent - -You can now say @samp{M-x -my-archive-article} in summary buffer to -archive the article under the cursor in a nnml -group. (Change nnml to your preferred back end) - -Of course you can also make sure the cache is enabled by saying - -@example -(setq gnus-use-cache t) -@end example -@noindent - -then you only have to set either the tick or the dormant -mark for articles you want to keep, setting the read -mark will remove them from cache. - -@node FAQ 6-3 -@subsubheading Question 6.3 - -How to search for a specific message? - -@subsubheading Answer - -There are several ways for this, too. For a posting from -a Usenet group the easiest solution is probably to ask -@uref{http://groups.google.com, groups.google.com}, -if you found the posting there, tell Google to display -the raw message, look for the message-id, and say -@samp{M-^ the@@message.id RET} in a -summary buffer. -Since Gnus 5.10 there's also a Gnus interface for -groups.google.com which you can call with -@samp{G W}) in group buffer. - -Another idea which works for both mail and news groups -is to enter the group where the message you are -searching is and use the standard Emacs search -@samp{C-s}, it's smart enough to look at -articles in collapsed threads, too. If you want to -search bodies, too try @samp{M-s} -instead. Further on there are the -gnus-summary-limit-to-foo functions, which can help you, -too. - -Of course you can also use grep to search through your -local mail, but this is both slow for big archives and -inconvenient since you are not displaying the found mail -in Gnus. Here nnir comes into action. Nnir is a front end -to search engines like swish-e or swish++ and -others. You index your mail with one of those search -engines and with the help of nnir you can search through -the indexed mail and generate a temporary group with all -messages which met your search criteria. If this sounds -cool to you, get nnir.el from -@c FIXME Isn't this file in Gnus? -@ignore -@c Dead link 2013/7. -@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/} -or -@end ignore -@uref{ftp://ftp.is.informatik.uni-duisburg.de/pub/src/emacs/}. -Instructions on how to use it are at the top of the file. - -@node FAQ 6-4 -@subsubheading Question 6.4 - -How to get rid of old unwanted mail? - -@subsubheading Answer - -You can of course just mark the mail you don't need -anymore by saying @samp{#} with point -over the mail and then say @samp{B DEL} -to get rid of them forever. You could also instead of -actually deleting them, send them to a junk-group by -saying @samp{B m nnml:trash-bin} which -you clear from time to time, but both are not the intended -way in Gnus. - -In Gnus, we let mail expire like news expires on a news -server. That means you tell Gnus the message is -expirable (you tell Gnus "I don't need this mail -anymore") by saying @samp{E} with point -over the mail in summary buffer. Now when you leave the -group, Gnus looks at all messages which you marked as -expirable before and if they are old enough (default is -older than a week) they are deleted. - -@node FAQ 6-5 -@subsubheading Question 6.5 - -I want that all read messages are expired (at least in -some groups). How to do it? - -@subsubheading Answer - -If you want all read messages to be expired (e.g., in -mailing lists where there's an online archive), you've -got two choices: auto-expire and -total-expire. Auto-expire means, that every article -which has no marks set and is selected for reading is -marked as expirable, Gnus hits @samp{E} -for you every time you read a message. Total-expire -follows a slightly different approach, here all article -where the read mark is set are expirable. - -To activate auto-expire, include auto-expire in the -Group parameters for the group. (Hit @samp{G -c} in summary buffer with point over the -group to change group parameters). For total-expire add -total-expire to the group-parameters. - -Which method you choose is merely a matter of taste: -Auto-expire is faster, but it doesn't play together with -Adaptive Scoring, so if you want to use this feature, -you should use total-expire. - -If you want a message to be excluded from expiration in -a group where total or auto expire is active, set either -tick (hit @samp{u}) or dormant mark (hit -@samp{u}), when you use auto-expire, you -can also set the read mark (hit -@samp{d}). - -@node FAQ 6-6 -@subsubheading Question 6.6 - -I don't want expiration to delete my mails but to move them -to another group. - -@subsubheading Answer - -Say something like this in @file{~/.gnus.el}: - -@example -(setq nnmail-expiry-target "nnml:expired") -@end example -@noindent - -(If you want to change the value of nnmail-expiry-target -on a per group basis see the question "How can I disable -threading in some (e.g., mail-) groups, or set other -variables specific for some groups?") - -@node FAQ 7 - Gnus in a dial-up environment -@subsection Gnus in a dial-up environment - -@menu -* FAQ 7-1:: I don't have a permanent connection to the net, how can I - minimize the time I've got to be connected? -* FAQ 7-2:: So what was this thing about the Agent? -* FAQ 7-3:: I want to store article bodies on disk, too. How to do - it? -* FAQ 7-4:: How to tell Gnus not to try to send mails / postings - while I'm offline? -@end menu - -@node FAQ 7-1 -@subsubheading Question 7.1 - -I don't have a permanent connection to the net, how can -I minimize the time I've got to be connected? - -@subsubheading Answer - -You've got basically two options: Either you use the -Gnus Agent (see below) for this, or you can install -programs which fetch your news and mail to your local -disk and Gnus reads the stuff from your local -machine. - -If you want to follow the second approach, you need a -program which fetches news and offers them to Gnus, a -program which does the same for mail and a program which -receives the mail you write from Gnus and sends them -when you're online. - -Let's talk about Unix systems first: For the news part, -the easiest solution is a small nntp server like -@uref{http://www.leafnode.org/, Leafnode} or -@uref{http://infa.abo.fi/~patrik/sn/, sn}, -of course you can also install a full featured news -server like -@uref{http://www.isc.org/software/inn/, inn}. -Then you want to fetch your Mail, popular choices -are @uref{http://www.catb.org/~esr/fetchmail/, fetchmail} -and @uref{http://pyropus.ca/software/getmail/, getmail}. -You should tell those to write the mail to your disk and -Gnus to read it from there. Last but not least the mail -sending part: This can be done with every MTA like -@uref{http://www.sendmail.org/, sendmail}, -@uref{http://www.qmail.org/, postfix}, -@uref{http://www.exim.org/, exim} or -@uref{http://www.qmail.org/, qmail}. - -On windows boxes I'd vote for -@uref{http://www.tglsoft.de/, Hamster}, -it's a small freeware, open-source program which fetches -your mail and news from remote servers and offers them -to Gnus (or any other mail and/or news reader) via nntp -respectively POP3 or IMAP@. It also includes a smtp -server for receiving mails from Gnus. - -@node FAQ 7-2 -@subsubheading Question 7.2 - -So what was this thing about the Agent? - -@subsubheading Answer - -The Gnus agent is part of Gnus, it allows you to fetch -mail and news and store them on disk for reading them -later when you're offline. It kind of mimics offline -newsreaders like Forte Agent. If you want to use -the Agent place the following in @file{~/.gnus.el} if you are -still using 5.8.8 or 5.9 (it's the default since 5.10): - -@example -(setq gnus-agent t) -@end example -@noindent - -Now you've got to select the servers whose groups can be -stored locally. To do this, open the server buffer -(that is press @samp{^} while in the -group buffer). Now select a server by moving point to -the line naming that server. Finally, agentize the -server by typing @samp{J a}. If you -make a mistake, or change your mind, you can undo this -action by typing @samp{J r}. When -you're done, type 'q' to return to the group buffer. -Now the next time you enter a group on a agentized -server, the headers will be stored on disk and read from -there the next time you enter the group. - -@node FAQ 7-3 -@subsubheading Question 7.3 - -I want to store article bodies on disk, too. How to do it? - -@subsubheading Answer - -You can tell the agent to automatically fetch the bodies -of articles which fulfill certain predicates, this is -done in a special buffer which can be reached by -saying @samp{J c} in group -buffer. Please refer to the documentation for -information which predicates are possible and how -exactly to do it. - -Further on you can tell the agent manually which -articles to store on disk. There are two ways to do -this: Number one: In the summary buffer, process mark a -set of articles that shall be stored in the agent by -saying @samp{#} with point over the -article and then type @samp{J s}. The -other possibility is to set, again in the summary -buffer, downloadable (%) marks for the articles you -want by typing @samp{@@} with point over -the article and then typing @samp{J u}. -What's the difference? Well, process marks are erased as -soon as you exit the summary buffer while downloadable -marks are permanent. You can actually set downloadable -marks in several groups then use fetch session ('J s' in -the GROUP buffer) to fetch all of those articles. The -only downside is that fetch session also fetches all of -the headers for every selected group on an agentized -server. Depending on the volume of headers, the initial -fetch session could take hours. - -@node FAQ 7-4 -@subsubheading Question 7.4 - -How to tell Gnus not to try to send mails / postings -while I'm offline? - -@subsubheading Answer - -All you've got to do is to tell Gnus when you are online -(plugged) and when you are offline (unplugged), the rest -works automatically. You can toggle plugged/unplugged -state by saying @samp{J j} in group -buffer. To start Gnus unplugged say @samp{M-x -gnus-unplugged} instead of -@samp{M-x gnus}. Note that for this to -work, the agent must be active. - -@node FAQ 8 - Getting help -@subsection Getting help - -@menu -* FAQ 8-1:: How to find information and help inside Emacs? -* FAQ 8-2:: I can't find anything in the Gnus manual about X (e.g., - attachments, PGP, MIME...), is it not documented? -* FAQ 8-3:: Which websites should I know? -* FAQ 8-4:: Which mailing lists and newsgroups are there? -* FAQ 8-5:: Where to report bugs? -* FAQ 8-6:: I need real-time help, where to find it? -@end menu - -@node FAQ 8-1 -@subsubheading Question 8.1 - -How to find information and help inside Emacs? - -@subsubheading Answer - -The first stop should be the Gnus manual (Say -@samp{C-h i d m Gnus RET} to start the -Gnus manual, then walk through the menus or do a -full-text search with @samp{s}). Then -there are the general Emacs help commands starting with -C-h, type @samp{C-h ? ?} to get a list -of all available help commands and their meaning. Finally -@samp{M-x apropos-command} lets you -search through all available functions and @samp{M-x -apropos} searches the bound variables. - -@node FAQ 8-2 -@subsubheading Question 8.2 - -I can't find anything in the Gnus manual about X -(e.g., attachments, PGP, MIME...), is it not documented? - -@subsubheading Answer - -There's not only the Gnus manual but also the manuals for message, -emacs-mime, sieve, EasyPG Assistant, and pgg. Those packages are -distributed with Gnus and used by Gnus but aren't really part of core -Gnus, so they are documented in different info files, you should have -a look in those manuals, too. - -@node FAQ 8-3 -@subsubheading Question 8.3 - -Which websites should I know? - -@subsubheading Answer - -The most important one is the -@uref{http://www.gnus.org, official Gnus website}. - -Tell me about other sites which are interesting. - -@node FAQ 8-4 -@subsubheading Question 8.4 - -Which mailing lists and newsgroups are there? - -@subsubheading Answer - -There's the newsgroup gnu.emacs.gnus (also available as -@uref{http://dir.gmane.org/gmane.emacs.gnus.user, -gmane.emacs.gnus.user}) which deals with general Gnus -questions. If you have questions about development versions of -Gnus, you should better ask on the ding mailing list, see below. - -If you want to stay in the big8, -news.software.readers is also read by some Gnus -users (but chances for qualified help are much better in -the above groups). If you speak German, there's -de.comm.software.gnus. - -The ding mailing list (ding@@gnus.org) deals with development of -Gnus. You can read the ding list via NNTP, too under the name -@uref{http://dir.gmane.org/gmane.emacs.gnus.general, -gmane.emacs.gnus.general} from news.gmane.org. - -@node FAQ 8-5 -@subsubheading Question 8.5 - -Where to report bugs? - -@subsubheading Answer - -Say @samp{M-x gnus-bug}, this will start -a message to the -@email{bugs@@gnus.org, gnus bug mailing list} -including information about your environment which make -it easier to help you. - -@node FAQ 8-6 -@subsubheading Question 8.6 - -I need real-time help, where to find it? - -@subsubheading Answer - -Point your IRC client to irc.freenode.net, channel #gnus. - -@node FAQ 9 - Tuning Gnus -@subsection Tuning Gnus - -@menu -* FAQ 9-1:: Starting Gnus is really slow, how to speed it up? -* FAQ 9-2:: How to speed up the process of entering a group? -* FAQ 9-3:: Sending mail becomes slower and slower, what's up? -@end menu - -@node FAQ 9-1 -@subsubheading Question 9.1 - -Starting Gnus is really slow, how to speed it up? - -@subsubheading Answer - -The reason for this could be the way Gnus reads its -active file, see the node "The Active File" in the Gnus -manual for things you might try to speed the process up. -An other idea would be to byte compile your @file{~/.gnus.el} (say -@samp{M-x byte-compile-file RET ~/.gnus.el -RET} to do it). Finally, if you have require -statements in your .gnus, you could replace them with -eval-after-load, which loads the stuff not at startup -time, but when it's needed. Say you've got this in your -@file{~/.gnus.el}: - -@example -(require 'message) -(add-to-list 'message-syntax-checks '(sender . disabled)) -@end example -@noindent - -then as soon as you start Gnus, message.el is loaded. If -you replace it with - -@example -(eval-after-load "message" - '(add-to-list 'message-syntax-checks '(sender . disabled))) -@end example -@noindent - -it's loaded when it's needed. - -@node FAQ 9-2 -@subsubheading Question 9.2 - -How to speed up the process of entering a group? - -@subsubheading Answer - -A speed killer is setting the variable -gnus-fetch-old-headers to anything different from @code{nil}, -so don't do this if speed is an issue. To speed up -building of summary say - -@example -(gnus-compile) -@end example -@noindent - -at the bottom of your @file{~/.gnus.el}, this will make gnus -byte-compile things like -gnus-summary-line-format. -then you could increase the value of gc-cons-threshold -by saying something like - -@example -(setq gc-cons-threshold 3500000) -@end example -@noindent - -in ~/.emacs. If you don't care about width of CJK -characters or use Gnus 5.10 or younger together with a -recent GNU Emacs, you should say - -@example -(setq gnus-use-correct-string-widths nil) -@end example -@noindent - -in @file{~/.gnus.el} (thanks to Jesper harder for the last -two suggestions). Finally if you are still using 5.8.8 -or 5.9 and experience speed problems with summary -buffer generation, you definitely should update to -5.10 since there quite some work on improving it has -been done. - -@node FAQ 9-3 -@subsubheading Question 9.3 - -Sending mail becomes slower and slower, what's up? - -@subsubheading Answer - -The reason could be that you told Gnus to archive the -messages you wrote by setting -gnus-message-archive-group. Try to use a nnml group -instead of an archive group, this should bring you back -to normal speed. - -@node FAQ - Glossary -@subsection Glossary - -@table @dfn - -@item ~/.gnus.el -When the term @file{~/.gnus.el} is used it just means your Gnus -configuration file. You might as well call it @file{~/.gnus} or -specify another name. - -@item Back End -In Gnus terminology a back end is a virtual server, a layer -between core Gnus and the real NNTP-, POP3-, IMAP- or -whatever-server which offers Gnus a standardized interface -to functions like "get message", "get Headers" etc. - -@item Emacs -When the term Emacs is used in this FAQ, it means either GNU -Emacs or XEmacs. - -@item Message -In this FAQ message means a either a mail or a posting to a -Usenet Newsgroup or to some other fancy back end, no matter -of which kind it is. - -@item MUA -MUA is an acronym for Mail User Agent, it's the program you -use to read and write e-mails. - -@item NUA -NUA is an acronym for News User Agent, it's the program you -use to read and write Usenet news. - -@end table diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi deleted file mode 100644 index a48b1f1bc5b..00000000000 --- a/doc/misc/gnus-news.texi +++ /dev/null @@ -1,371 +0,0 @@ -@c -*-texinfo-*- - -@c Copyright (C) 2004-2014 Free Software Foundation, Inc. - -@c Permission is granted to anyone to make or distribute verbatim copies -@c of this document as received, in any medium, provided that the -@c copyright notice and this permission notice are preserved, -@c thus giving the recipient permission to redistribute in turn. - -@c Permission is granted to distribute modified versions -@c of this document, or of portions of it, -@c under the above conditions, provided also that they -@c carry prominent notices stating who last changed them. - -@c This file contains a list of news features Gnus. It is supposed to be -@c included in `gnus.texi'. `GNUS-NEWS' is automatically generated from -@c this file (see `gnus-news.el'). - -@itemize @bullet - -@item Supported Emacs versions -The following Emacs versions are supported by No Gnus: -@itemize @bullet - -@item Emacs 22 and up -@item XEmacs 21.4 -@item XEmacs 21.5 -@item SXEmacs - -@end itemize - -@item Installation changes - -@itemize @bullet -@item Upgrading from previous (stable) version if you have used No Gnus. - -If you have tried No Gnus (the unstable Gnus branch leading to this -release) but went back to a stable version, be careful when upgrading -to this version. In particular, you will probably want to remove the -@file{~/News/marks} directory (perhaps selectively), so that flags are -read from your @file{~/.newsrc.eld} instead of from the stale marks -file, where this release will store flags for nntp. See a later entry -for more information about nntp marks. Note that downgrading isn't -safe in general. - -@item Incompatibility when switching from Emacs 23 to Emacs 22 -In Emacs 23, Gnus uses Emacs's new internal coding system @code{utf-8-emacs} -for saving articles drafts and @file{~/.newsrc.eld}. These files may not -be read correctly in Emacs 22 and below. If you want to use Gnus across -different Emacs versions, you may set @code{mm-auto-save-coding-system} -to @code{emacs-mule}. -@c FIXME: Untested. (Or did anyone test it?) -@c Cf. http://thread.gmane.org/gmane.emacs.gnus.general/66251/focus=66344 - -@item Lisp files are now installed in @file{.../site-lisp/gnus/} by default. -It defaulted to @file{.../site-lisp/} formerly. In addition to this, -the new installer issues a warning if other Gnus installations which -will shadow the latest one are detected. You can then remove those -shadows manually or remove them using @code{make -remove-installed-shadows}. - -@item The installation directory name is allowed to have spaces and/or tabs. -@end itemize - -@item New packages and libraries within Gnus - -@itemize @bullet - -@item New version of @code{nnimap} - -@code{nnimap} has been reimplemented in a mostly-compatible way. See -the Gnus manual for a description of the new interface. In -particular, @code{nnimap-inbox} and the client side split method has -changed. - -@item Gnus includes the Emacs Lisp @acronym{SASL} library. - -This provides a clean @acronym{API} to @acronym{SASL} mechanisms from -within Emacs. The user visible aspects of this, compared to the earlier -situation, include support for @acronym{DIGEST}-@acronym{MD5} and -@acronym{NTLM}. @xref{Top, ,Emacs SASL, sasl, Emacs SASL}. - -@item ManageSieve connections uses the @acronym{SASL} library by default. - -The primary change this brings is support for @acronym{DIGEST-MD5} and -@acronym{NTLM}, when the server supports it. - -@item Gnus includes a password cache mechanism in password.el. - -It is enabled by default (see @code{password-cache}), with a short -timeout of 16 seconds (see @code{password-cache-expiry}). If -@acronym{PGG} is used as the @acronym{PGP} back end, the @acronym{PGP} -passphrase is managed by this mechanism. Passwords for ManageSieve -connections are managed by this mechanism, after querying the user -about whether to do so. - -@item Using EasyPG with Gnus -When EasyPG, is available, Gnus will use it instead of @acronym{PGG}. -EasyPG is an Emacs user interface to GNU Privacy Guard. @xref{Top, -,EasyPG Assistant user's manual, epa, EasyPG Assistant user's manual}. -EasyPG is included in Emacs 23 and available separately as well. -@end itemize - -@item Changes in group mode -@c ************************ - -@itemize @bullet - -@item -Symbols like @code{gcc-self} now have the same precedence rules in -@code{gnus-parameters} as other ``real'' variables: The last match -wins instead of the first match. - -@item -Old intermediate incoming mail files (@file{Incoming*}) are deleted -after a couple of days, not immediately. @xref{Mail Source -Customization}. -(New in Gnus 5.10.10 / No Gnus 0.8) -@c This entry is also present in the node "Oort Gnus". - -@end itemize - -@item Changes in summary and article mode - -@itemize @bullet - -@item There's now only one variable that determines how @acronym{HTML} -is rendered: @code{mm-text-html-renderer}. - -@item Gnus now supports sticky article buffers. Those are article buffers -that are not reused when you select another article. @xref{Sticky -Articles}. - -@c @item Bookmarks -@c FIXME: To be added - -@item Gnus can selectively display @samp{text/html} articles -with a WWW browser with @kbd{K H}. @xref{MIME Commands}. - -@c gnus-registry-marks -@c FIXME: To be added - -@item International host names (@acronym{IDNA}) can now be decoded -inside article bodies using @kbd{W i} -(@code{gnus-summary-idna-message}). This requires that GNU Libidn -(@url{http://www.gnu.org/software/libidn/}) has been installed. -@c FIXME: Also mention @code{message-use-idna}? - -@item The non-@acronym{ASCII} group names handling has been much -improved. The back ends that fully support non-@acronym{ASCII} group -names are now @code{nntp}, @code{nnml}, and @code{nnrss}. Also the -agent, the cache, and the marks features work with those back ends. -@xref{Non-ASCII Group Names}. - -@item Gnus now displays @acronym{DNS} master files sent as text/dns -using dns-mode. - -@item Gnus supports new limiting commands in the Summary buffer: -@kbd{/ r} (@code{gnus-summary-limit-to-replied}) and @kbd{/ R} -(@code{gnus-summary-limit-to-recipient}). @xref{Limiting}. - -@item You can now fetch all ticked articles from the server using -@kbd{Y t} (@code{gnus-summary-insert-ticked-articles}). @xref{Summary -Generation Commands}. - -@item Gnus supports a new sort command in the Summary buffer: -@kbd{C-c C-s C-t} (@code{gnus-summary-sort-by-recipient}). @xref{Summary -Sorting}. - -@item @acronym{S/MIME} now features @acronym{LDAP} user certificate searches. -You need to configure the server in @code{smime-ldap-host-list}. - -@item URLs inside Open@acronym{PGP} headers are retrieved and imported -to your PGP key ring when you click on them. - -@item -Picons can be displayed right from the textual address, see -@code{gnus-picon-style}. @xref{Picons}. - -@item @acronym{ANSI} @acronym{SGR} control sequences can be transformed -using @kbd{W A}. - -@acronym{ANSI} sequences are used in some Chinese hierarchies for -highlighting articles (@code{gnus-article-treat-ansi-sequences}). - -@item Gnus now MIME decodes articles even when they lack "MIME-Version" header. -This changes the default of @code{gnus-article-loose-mime}. - -@item @code{gnus-decay-scores} can be a regexp matching score files. -For example, set it to @samp{\\.ADAPT\\'} and only adaptive score files -will be decayed. @xref{Score Decays}. - -@item Strings prefixing to the @code{To} and @code{Newsgroup} headers in -summary lines when using @code{gnus-ignored-from-addresses} can be -customized with @code{gnus-summary-to-prefix} and -@code{gnus-summary-newsgroup-prefix}. @xref{To From Newsgroups}. - -@item You can replace @acronym{MIME} parts with external bodies. -See @code{gnus-mime-replace-part} and @code{gnus-article-replace-part}. -@xref{MIME Commands}, @ref{Using MIME}. - -@item -The option @code{mm-fill-flowed} can be used to disable treatment of -format=flowed messages. Also, flowed text is disabled when sending -inline @acronym{PGP} signed messages. @xref{Flowed text, ,Flowed text, -emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) -@c This entry is also present in the node "Oort Gnus". - -@item Now the new command @kbd{S W} -(@code{gnus-article-wide-reply-with-original}) for a wide reply in the -article buffer yanks a text that is in the active region, if it is set, -as well as the @kbd{R} (@code{gnus-article-reply-with-original}) command. -Note that the @kbd{R} command in the article buffer no longer accepts a -prefix argument, which was used to make it do a wide reply. -@xref{Article Keymap}. - -@item The new command @kbd{C-h b} -(@code{gnus-article-describe-bindings}) used in the article buffer now -shows not only the article commands but also the real summary commands -that are accessible from the article buffer. - -@end itemize - -@item Changes in Message mode - -@itemize @bullet -@item Gnus now defaults to saving all outgoing messages in per-month -nnfolder archives. - -@item Gnus now supports the ``hashcash'' client puzzle anti-spam mechanism. -Use @code{(setq message-generate-hashcash t)} to enable. -@xref{Hashcash}. - -@item You can now drag and drop attachments to the Message buffer. -See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. -@xref{MIME, ,MIME, message, Message Manual}. - -@item The option @code{message-yank-empty-prefix} now controls how -empty lines are prefixed in cited text. @xref{Insertion Variables, -,Insertion Variables, message, Message Manual}. - -@item Gnus uses narrowing to hide headers in Message buffers. -The @code{References} header is hidden by default. To make all -headers visible, use @code{(setq message-hidden-headers nil)}. -@xref{Message Headers, ,Message Headers, message, Message Manual}. - -@item You can highlight different levels of citations like in the -article buffer. See @code{gnus-message-highlight-citation}. - -@item @code{auto-fill-mode} is enabled by default in Message mode. -See @code{message-fill-column}. @xref{Various Message Variables, , -Message Headers, message, Message Manual}. - -@item You can now store signature files in a special directory -named @code{message-signature-directory}. - -@item The option @code{message-citation-line-format} controls the format -of the "Whomever writes:" line. You need to set -@code{message-citation-line-function} to -@code{message-insert-formatted-citation-line} as well. -@end itemize - -@item Changes in Browse Server mode - -@itemize @bullet -@item Gnus' sophisticated subscription methods are now available in -Browse Server buffers as well using the variable -@code{gnus-browse-subscribe-newsgroup-method}. - -@end itemize - - -@item Changes in back ends - -@itemize @bullet -@item The nntp back end stores article marks in @file{~/News/marks}. - -The directory can be changed using the (customizable) variable -@code{nntp-marks-directory}, and marks can be disabled using the -(back end) variable @code{nntp-marks-is-evil}. The advantage of this -is that you can copy @file{~/News/marks} (using rsync, scp or -whatever) to another Gnus installation, and it will realize what -articles you have read and marked. The data in @file{~/News/marks} -has priority over the same data in @file{~/.newsrc.eld}. - -@item -You can import and export your @acronym{RSS} subscriptions from -@acronym{OPML} files. @xref{RSS}. - -@item @acronym{IMAP} identity (@acronym{RFC} 2971) is supported. - -By default, Gnus does not send any information about itself, but you can -customize it using the variable @code{nnimap-id}. - -@item The @code{nnrss} back end now supports multilingual text. -Non-@acronym{ASCII} group names for the @code{nnrss} groups are also -supported. @xref{RSS}. - -@item Retrieving mail with @acronym{POP3} is supported over @acronym{SSL}/@acronym{TLS} and with StartTLS. - -@item The nnml back end allows other compression programs beside @file{gzip} -for compressed message files. @xref{Mail Spool}. - -@item The nnml back end supports group compaction. - -This feature, accessible via the functions -@code{gnus-group-compact-group} (@kbd{G z} in the group buffer) and -@code{gnus-server-compact-server} (@kbd{z} in the server buffer) -renumbers all articles in a group, starting from 1 and removing gaps. -As a consequence, you get a correct total article count (until -messages are deleted again). - -@c @item nnmairix.el -@c FIXME - -@c @item nnir.el -@c FIXME - -@end itemize - -@item Appearance -@c Maybe it's not worth to separate this from "Miscellaneous"? - -@itemize @bullet - -@item The tool bar has been updated to use GNOME icons. -You can also customize the tool bars: @kbd{M-x customize-apropos RET --tool-bar$} should get you started. (Only for Emacs, not in XEmacs.) -@c FIXME: Document this in the manual - -@item The tool bar icons are now (de)activated correctly -in the group buffer, see the variable @code{gnus-group-update-tool-bar}. -Its default value depends on your Emacs version. -@c FIXME: Document this in the manual - -@item You can change the location of XEmacs's toolbars in Gnus buffers. -See @code{gnus-use-toolbar} and @code{message-use-toolbar}. - -@end itemize - -@item Miscellaneous changes - -@itemize @bullet -@item Having edited the select-method for the foreign server in the -server buffer is immediately reflected to the subscription of the groups -which use the server in question. For instance, if you change -@code{nntp-via-address} into @samp{bar.example.com} from -@samp{foo.example.com}, Gnus will connect to the news host by way of the -intermediate host @samp{bar.example.com} from next time. - -@item The @file{all.SCORE} file can be edited from the group buffer -using @kbd{W e}. - -@item You can set @code{gnus-mark-copied-or-moved-articles-as-expirable} -to a non-@code{nil} value so that articles that have been read may be -marked as expirable automatically when copying or moving them to a group -that has auto-expire turned on. The default is @code{nil} and copying -and moving of articles behave as before; i.e., the expirable marks will -be unchanged except that the marks will be removed when copying or -moving articles to a group that has not turned auto-expire on. -@xref{Expiring Mail}. - -@item NoCeM support has been removed. - -@item Carpal mode has been removed. - -@end itemize - -@end itemize - -@c gnus-news.texi ends here. diff --git a/doc/misc/gnus-overrides.texi b/doc/misc/gnus-overrides.texi deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi deleted file mode 100644 index 8f1550942e9..00000000000 --- a/doc/misc/gnus.texi +++ /dev/null @@ -1,30657 +0,0 @@ -\input texinfo - -@include gnus-overrides.texi - -@setfilename ../../info/gnus -@settitle Gnus Manual -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex pg cp - -@documentencoding UTF-8 - -@copying -Copyright @copyright{} 1995--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@iftex -@iflatex -\documentclass[twoside,a4paper,openright,11pt]{book} -\usepackage[latin1]{inputenc} -\usepackage{pagestyle} -\usepackage{epsfig} -\usepackage{pixidx} -\input{gnusconfig.tex} - -\ifx\pdfoutput\undefined -\else -\usepackage[pdftex,bookmarks,colorlinks=true]{hyperref} -\usepackage{thumbpdf} -\pdfcompresslevel=9 -\fi - -\makeindex -\begin{document} - -% Adjust ../Makefile.in if you change the following line: -\newcommand{\gnusversionname}{Gnus v5.13} -\newcommand{\gnuschaptername}{} -\newcommand{\gnussectionname}{} - -\newcommand{\gnusbackslash}{/} - -\newcommand{\gnusref}[1]{``#1'' on page \pageref{#1}} -\ifx\pdfoutput\undefined -\newcommand{\gnusuref}[1]{\gnustt{#1}} -\else -\newcommand{\gnusuref}[1]{\href{#1}{\gnustt{#1}}} -\fi -\newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}} -\newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}} - -\newcommand{\gnuskindex}[1]{\index{#1}} -\newcommand{\gnusindex}[1]{\index{#1}} - -\newcommand{\gnustt}[1]{{\gnusselectttfont{}#1}} -\newcommand{\gnuscode}[1]{\gnustt{#1}} -\newcommand{\gnusasis}[1]{\gnustt{#1}} -\newcommand{\gnusurl}[1]{\gnustt{#1}} -\newcommand{\gnuscommand}[1]{\gnustt{#1}} -\newcommand{\gnusenv}[1]{\gnustt{#1}} -\newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\gnusselectttfont{}#1}''} -\newcommand{\gnuslisp}[1]{\gnustt{#1}} -\newcommand{\gnuskbd}[1]{`\gnustt{#1}'} -\newcommand{\gnuskey}[1]{`\gnustt{#1}'} -\newcommand{\gnusfile}[1]{`\gnustt{#1}'} -\newcommand{\gnusdfn}[1]{\textit{#1}} -\newcommand{\gnusi}[1]{\textit{#1}} -\newcommand{\gnusr}[1]{\textrm{#1}} -\newcommand{\gnusstrong}[1]{\textbf{#1}} -\newcommand{\gnusemph}[1]{\textit{#1}} -\newcommand{\gnusvar}[1]{{\fontsize{10pt}{10}\selectfont\textsl{\textsf{#1}}}} -\newcommand{\gnussc}[1]{\textsc{#1}} -\newcommand{\gnustitle}[1]{{\huge\textbf{#1}}} -\newcommand{\gnusversion}[1]{{\small\textit{#1}}} -\newcommand{\gnusauthor}[1]{{\large\textbf{#1}}} -\newcommand{\gnusresult}[1]{\gnustt{=> #1}} -\newcommand{\gnusacronym}[1]{\textsc{#1}} -\newcommand{\gnusemail}[1]{\textit{#1}} - -\newcommand{\gnusbullet}{{${\bullet}$}} -\newcommand{\gnusdollar}{\$} -\newcommand{\gnusampersand}{\&} -\newcommand{\gnuspercent}{\%} -\newcommand{\gnushash}{\#} -\newcommand{\gnushat}{\symbol{"5E}} -\newcommand{\gnusunderline}{\symbol{"5F}} -\newcommand{\gnusnot}{$\neg$} -\newcommand{\gnustilde}{\symbol{"7E}} -\newcommand{\gnusless}{{$<$}} -\newcommand{\gnusgreater}{{$>$}} -\newcommand{\gnusbraceleft}{{$>$}} -\newcommand{\gnusbraceright}{{$>$}} - -\newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head,height=1cm}}} -\newcommand{\gnusinteresting}{ -\marginpar[\mbox{}\hfill\gnushead]{\gnushead} -} - -\newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi} - -\newcommand{\gnuspagechapter}[1]{ -{\mbox{}} -} - -\newdimen{\gnusdimen} -\gnusdimen 0pt - -\newcommand{\gnuschapter}[2]{ -\gnuscleardoublepage -\ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi -\chapter{#2} -\renewcommand{\gnussectionname}{} -\renewcommand{\gnuschaptername}{#2} -\thispagestyle{empty} -\hspace*{-2cm} -\begin{picture}(500,500)(0,0) -\put(480,350){\makebox(0,0)[tr]{#1}} -\put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}} -\end{picture} -\clearpage -} - -\newcommand{\gnusfigure}[3]{ -\begin{figure} -\mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2) -#3 -\end{picture} -\caption{#1} -\end{figure} -} - -\newcommand{\gnusicon}[1]{ -\marginpar[\mbox{}\hfill\raisebox{-1.5cm}{\epsfig{figure=ps/#1-up,height=1.5cm}}]{\raisebox{-1cm}{\epsfig{figure=ps/#1-up,height=1cm}}} -} - -\newcommand{\gnuspicon}[1]{ -\margindex{\epsfig{figure=#1,width=2cm}} -} - -\newcommand{\gnusxface}[2]{ -\margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}} -} - -\newcommand{\gnussmiley}[2]{ -\margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}} -} - -\newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1} - -\newcommand{\gnussection}[1]{ -\renewcommand{\gnussectionname}{#1} -\section{#1} -} - -\newenvironment{codelist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{asislist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{kbdlist}% -{\begin{list}{}{ -\labelwidth=0cm -} -}{\end{list}} - -\newenvironment{dfnlist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{stronglist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{samplist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{varlist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{emphlist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newlength\gnusheadtextwidth -\setlength{\gnusheadtextwidth}{\headtextwidth} -\addtolength{\gnusheadtextwidth}{1cm} - -\newpagestyle{gnuspreamble}% -{ -{ -\ifodd\count0 -{ -\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}} -} -\else -{ -\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}} -} -} -\fi -} -} -{ -\ifodd\count0 -\mbox{} \hfill -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\else -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\hfill \mbox{} -\fi -} - -\newpagestyle{gnusindex}% -{ -{ -\ifodd\count0 -{ -\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}} -} -\else -{ -\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}} -} -\fi -} -} -{ -\ifodd\count0 -\mbox{} \hfill -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\else -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\hfill \mbox{} -\fi -} - -\newpagestyle{gnus}% -{ -{ -\ifodd\count0 -{ -\makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}} -} -\else -{ -\makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}} -} -\fi -} -} -{ -\ifodd\count0 -\mbox{} \hfill -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\else -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\hfill \mbox{} -\fi -} - -\pagenumbering{roman} -\pagestyle{gnuspreamble} - -@end iflatex -@end iftex - -@iftex -@iflatex - -\begin{titlepage} -{ - -%\addtolength{\oddsidemargin}{-5cm} -%\addtolength{\evensidemargin}{-5cm} -\parindent=0cm -\addtolength{\textheight}{2cm} - -\gnustitle{\gnustitlename}\hfill\gnusversion{\gnusversionname}\\ -\rule{15cm}{1mm}\\ -\vfill -\hspace*{0cm}\epsfig{figure=ps/gnus-big-logo,height=15cm} -\vfill -\rule{15cm}{1mm}\\ -\gnusauthor{by Lars Magne Ingebrigtsen} -\newpage -} - -\mbox{} -\vfill - -\thispagestyle{empty} - -@c @insertcopying -\newpage -\end{titlepage} -@end iflatex -@end iftex - -@dircategory Emacs network features -@direntry -* Gnus: (gnus). The newsreader Gnus. -@end direntry -@iftex -@finalout -@end iftex - - -@titlepage -@ifset WEBHACKDEVEL -@title Gnus Manual (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Gnus Manual -@end ifclear - -@author by Lars Magne Ingebrigtsen -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@node Top -@top The Gnus Newsreader - -@ifinfo - -You can read news (and mail) from within Emacs by using Gnus. The news -can be gotten by any nefarious means you can think of---@acronym{NNTP}, local -spool or your mbox file. All at the same time, if you want to push your -luck. - -@c Adjust ../Makefile.in if you change the following line: -This manual corresponds to Gnus v5.13 - -@ifnottex -@insertcopying -@end ifnottex - -@end ifinfo - -@iftex - -@iflatex -\tableofcontents -\gnuscleardoublepage -@end iflatex - -Gnus is the advanced, self-documenting, customizable, extensible -unreal-time newsreader for GNU Emacs. - -Oops. That sounds oddly familiar, so let's start over again to avoid -being accused of plagiarism: - -Gnus is a message-reading laboratory. It will let you look at just -about anything as if it were a newsgroup. You can read mail with it, -you can browse directories with it, you can @code{ftp} with it---you -can even read news with it! - -Gnus tries to empower people who read news the same way Emacs empowers -people who edit text. Gnus sets no limits to what the user should be -allowed to do. Users are encouraged to extend Gnus to make it behave -like they want it to behave. A program should not control people; -people should be empowered to do what they want by using (or abusing) -the program. - -@c Adjust ../Makefile.in if you change the following line: -This manual corresponds to Gnus v5.13 - -@heading Other related manuals -@itemize -@item Message manual: Composing messages -@item Emacs-MIME: Composing messages; @acronym{MIME}-specific parts. -@item Sieve: Managing Sieve scripts in Emacs. -@item EasyPG: @acronym{PGP/MIME} with Gnus. -@item SASL: @acronym{SASL} authentication in Emacs. -@end itemize - -@end iftex - -@menu -* Starting Up:: Finding news can be a pain. -* Group Buffer:: Selecting, subscribing and killing groups. -* Summary Buffer:: Reading, saving and posting articles. -* Article Buffer:: Displaying and handling articles. -* Composing Messages:: Information on sending mail and news. -* Select Methods:: Gnus reads all messages from various select methods. -* Scoring:: Assigning values to articles. -* Searching:: Mail and News search engines. -* Various:: General purpose settings. -* The End:: Farewell and goodbye. -* Appendices:: Terminology, Emacs intro, @acronym{FAQ}, History, Internals. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Variable, function and concept index. -* Key Index:: Key Index. - -@c Doesn't work right in html. -@c FIXME Do this in a more standard way. -@ifinfo -Other related manuals - -* Message:(message). Composing messages. -* Emacs-MIME:(emacs-mime). Composing messages; @acronym{MIME}-specific parts. -* Sieve:(sieve). Managing Sieve scripts in Emacs. -* EasyPG:(epa). @acronym{PGP/MIME} with Gnus. -* SASL:(sasl). @acronym{SASL} authentication in Emacs. -@end ifinfo - -@detailmenu - --- The Detailed Node Listing --- - -Starting Gnus - -* Finding the News:: Choosing a method for getting news. -* The Server is Down:: How can I read my mail then? -* Slave Gnusae:: You can have more than one Gnus active at a time. -* Fetching a Group:: Starting Gnus just to read a group. -* New Groups:: What is Gnus supposed to do with new groups? -* Changing Servers:: You may want to move from one server to another. -* Startup Files:: Those pesky startup files---@file{.newsrc}. -* Auto Save:: Recovering from a crash. -* The Active File:: Reading the active file over a slow line Takes Time. -* Startup Variables:: Other variables you might change. - -New Groups - -* Checking New Groups:: Determining what groups are new. -* Subscription Methods:: What Gnus should do with new groups. -* Filtering New Groups:: Making Gnus ignore certain new groups. - -Group Buffer - -* Group Buffer Format:: Information listed and how you can change it. -* Group Maneuvering:: Commands for moving in the group buffer. -* Selecting a Group:: Actually reading news. -* Subscription Commands:: Unsubscribing, killing, subscribing. -* Group Data:: Changing the info for a group. -* Group Levels:: Levels? What are those, then? -* Group Score:: A mechanism for finding out what groups you like. -* Marking Groups:: You can mark groups for later processing. -* Foreign Groups:: Creating and editing groups. -* Group Parameters:: Each group may have different parameters set. -* Listing Groups:: Gnus can list various subsets of the groups. -* Sorting Groups:: Re-arrange the group order. -* Group Maintenance:: Maintaining a tidy @file{.newsrc} file. -* Browse Foreign Server:: You can browse a server. See what it has to offer. -* Exiting Gnus:: Stop reading news and get some work done. -* Group Topics:: A folding group mode divided into topics. -* Non-ASCII Group Names:: Accessing groups of non-English names. -* Misc Group Stuff:: Other stuff that you can to do. - -Group Buffer Format - -* Group Line Specification:: Deciding how the group buffer is to look. -* Group Mode Line Specification:: The group buffer mode line. -* Group Highlighting:: Having nice colors in the group buffer. - -Group Topics - -* Topic Commands:: Interactive E-Z commands. -* Topic Variables:: How to customize the topics the Lisp Way. -* Topic Sorting:: Sorting each topic individually. -* Topic Topology:: A map of the world. -* Topic Parameters:: Parameters that apply to all groups in a topic. - -Misc Group Stuff - -* Scanning New Messages:: Asking Gnus to see whether new messages have arrived. -* Group Information:: Information and help on groups and Gnus. -* Group Timestamp:: Making Gnus keep track of when you last read a group. -* File Commands:: Reading and writing the Gnus files. -* Sieve Commands:: Managing Sieve scripts. - -Summary Buffer - -* Summary Buffer Format:: Deciding how the summary buffer is to look. -* Summary Maneuvering:: Moving around the summary buffer. -* Choosing Articles:: Reading articles. -* Paging the Article:: Scrolling the current article. -* Reply Followup and Post:: Posting articles. -* Delayed Articles:: Send articles at a later time. -* Marking Articles:: Marking articles as read, expirable, etc. -* Limiting:: You can limit the summary buffer. -* Threading:: How threads are made. -* Sorting the Summary Buffer:: How articles and threads are sorted. -* Asynchronous Fetching:: Gnus might be able to pre-fetch articles. -* Article Caching:: You may store articles in a cache. -* Persistent Articles:: Making articles expiry-resistant. -* Sticky Articles:: Article buffers that are not reused. -* Article Backlog:: Having already read articles hang around. -* Saving Articles:: Ways of customizing article saving. -* Decoding Articles:: Gnus can treat series of (uu)encoded articles. -* Article Treatment:: The article buffer can be mangled at will. -* MIME Commands:: Doing MIMEy things with the articles. -* Charsets:: Character set issues. -* Article Commands:: Doing various things with the article buffer. -* Summary Sorting:: Sorting the summary buffer in various ways. -* Finding the Parent:: No child support? Get the parent. -* Alternative Approaches:: Reading using non-default summaries. -* Tree Display:: A more visual display of threads. -* Mail Group Commands:: Some commands can only be used in mail groups. -* Various Summary Stuff:: What didn't fit anywhere else. -* Exiting the Summary Buffer:: Returning to the Group buffer, - or reselecting the current group. -* Crosspost Handling:: How crossposted articles are dealt with. -* Duplicate Suppression:: An alternative when crosspost handling fails. -* Security:: Decrypt and Verify. -* Mailing List:: Mailing list minor mode. - -Summary Buffer Format - -* Summary Buffer Lines:: You can specify how summary lines should look. -* To From Newsgroups:: How to not display your own name. -* Summary Buffer Mode Line:: You can say how the mode line should look. -* Summary Highlighting:: Making the summary buffer all pretty and nice. - -Choosing Articles - -* Choosing Commands:: Commands for choosing articles. -* Choosing Variables:: Variables that influence these commands. - -Reply, Followup and Post - -* Summary Mail Commands:: Sending mail. -* Summary Post Commands:: Sending news. -* Summary Message Commands:: Other Message-related commands. -* Canceling and Superseding:: - -Marking Articles - -* Unread Articles:: Marks for unread articles. -* Read Articles:: Marks for read articles. -* Other Marks:: Marks that do not affect readedness. -* Setting Marks:: How to set and remove marks. -* Generic Marking Commands:: How to customize the marking. -* Setting Process Marks:: How to mark articles for later processing. - -Threading - -* Customizing Threading:: Variables you can change to affect the threading. -* Thread Commands:: Thread based commands in the summary buffer. - -Customizing Threading - -* Loose Threads:: How Gnus gathers loose threads into bigger threads. -* Filling In Threads:: Making the threads displayed look fuller. -* More Threading:: Even more variables for fiddling with threads. -* Low-Level Threading:: You thought it was over@dots{} but you were wrong! - -Decoding Articles - -* Uuencoded Articles:: Uudecode articles. -* Shell Archives:: Unshar articles. -* PostScript Files:: Split PostScript. -* Other Files:: Plain save and binhex. -* Decoding Variables:: Variables for a happy decoding. -* Viewing Files:: You want to look at the result of the decoding? - -Decoding Variables - -* Rule Variables:: Variables that say how a file is to be viewed. -* Other Decode Variables:: Other decode variables. -* Uuencoding and Posting:: Variables for customizing uuencoding. - -Article Treatment - -* Article Highlighting:: You want to make the article look like fruit salad. -* Article Fontisizing:: Making emphasized text look nice. -* Article Hiding:: You also want to make certain info go away. -* Article Washing:: Lots of way-neat functions to make life better. -* Article Header:: Doing various header transformations. -* Article Buttons:: Click on URLs, Message-IDs, addresses and the like. -* Article Button Levels:: Controlling appearance of buttons. -* Article Date:: Grumble, UT! -* Article Display:: Display various stuff---X-Face, Picons, Smileys, Gravatars -* Article Signature:: What is a signature? -* Article Miscellanea:: Various other stuff. - -Alternative Approaches - -* Pick and Read:: First mark articles and then read them. -* Binary Groups:: Auto-decode all articles. - -Various Summary Stuff - -* Summary Group Information:: Information oriented commands. -* Searching for Articles:: Multiple article commands. -* Summary Generation Commands:: -* Really Various Summary Commands:: Those pesky non-conformant commands. - -Article Buffer - -* Hiding Headers:: Deciding what headers should be displayed. -* Using MIME:: Pushing articles through @acronym{MIME} before reading them. -* Customizing Articles:: Tailoring the look of the articles. -* Article Keymap:: Keystrokes available in the article buffer. -* Misc Article:: Other stuff. - -Composing Messages - -* Mail:: Mailing and replying. -* Posting Server:: What server should you post and mail via? -* POP before SMTP:: You cannot send a mail unless you read a mail. -* Mail and Post:: Mailing and posting at the same time. -* Archived Messages:: Where Gnus stores the messages you've sent. -* Posting Styles:: An easier way to specify who you are. -* Drafts:: Postponing messages and rejected messages. -* Rejected Articles:: What happens if the server doesn't like your article? -* Signing and encrypting:: How to compose secure messages. - -Select Methods - -* Server Buffer:: Making and editing virtual servers. -* Getting News:: Reading USENET news with Gnus. -* Using IMAP:: Reading mail from @acronym{IMAP}. -* Getting Mail:: Reading your personal mail with Gnus. -* Browsing the Web:: Getting messages from a plethora of Web sources. -* Other Sources:: Reading directories, files. -* Combined Groups:: Combining groups into one group. -* Email Based Diary:: Using mails to manage diary events in Gnus. -* Gnus Unplugged:: Reading news and mail offline. - -Server Buffer - -* Server Buffer Format:: You can customize the look of this buffer. -* Server Commands:: Commands to manipulate servers. -* Example Methods:: Examples server specifications. -* Creating a Virtual Server:: An example session. -* Server Variables:: Which variables to set. -* Servers and Methods:: You can use server names as select methods. -* Unavailable Servers:: Some servers you try to contact may be down. - -Getting News - -* NNTP:: Reading news from an @acronym{NNTP} server. -* News Spool:: Reading news from the local spool. - -@acronym{NNTP} - -* Direct Functions:: Connecting directly to the server. -* Indirect Functions:: Connecting indirectly to the server. -* Common Variables:: Understood by several connection functions. - -Getting Mail - -* Mail in a Newsreader:: Important introductory notes. -* Getting Started Reading Mail:: A simple cookbook example. -* Splitting Mail:: How to create mail groups. -* Mail Sources:: How to tell Gnus where to get mail from. -* Mail Back End Variables:: Variables for customizing mail handling. -* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. -* Group Mail Splitting:: Use group customize to drive mail splitting. -* Incorporating Old Mail:: What about the old mail you have? -* Expiring Mail:: Getting rid of unwanted mail. -* Washing Mail:: Removing cruft from the mail you get. -* Duplicates:: Dealing with duplicated mail. -* Not Reading Mail:: Using mail back ends for reading other files. -* Choosing a Mail Back End:: Gnus can read a variety of mail formats. - -Mail Sources - -* Mail Source Specifiers:: How to specify what a mail source is. -* Mail Source Customization:: Some variables that influence things. -* Fetching Mail:: Using the mail source specifiers. - -Choosing a Mail Back End - -* Unix Mail Box:: Using the (quite) standard Un*x mbox. -* Babyl:: Babyl was used by older versions of Rmail. -* Mail Spool:: Store your mail in a private spool? -* MH Spool:: An mhspool-like back end. -* Maildir:: Another one-file-per-message format. -* Mail Folders:: Having one file for each group. -* Comparing Mail Back Ends:: An in-depth looks at pros and cons. - -Browsing the Web - -* Archiving Mail:: -* Web Searches:: Creating groups from articles that match a string. -* RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. - -Other Sources - -* Directory Groups:: You can read a directory as if it was a newsgroup. -* Anything Groups:: Dired? Who needs dired? -* Document Groups:: Single files can be the basis of a group. -* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. -* The Empty Backend:: The backend that never has any news. - -Document Groups - -* Document Server Internals:: How to add your own document types. - -Combined Groups - -* Virtual Groups:: Combining articles from many groups. - -Email Based Diary - -* The NNDiary Back End:: Basic setup and usage. -* The Gnus Diary Library:: Utility toolkit on top of nndiary. -* Sending or Not Sending:: A final note on sending diary messages. - -The NNDiary Back End - -* Diary Messages:: What makes a message valid for nndiary. -* Running NNDiary:: NNDiary has two modes of operation. -* Customizing NNDiary:: Bells and whistles. - -The Gnus Diary Library - -* Diary Summary Line Format:: A nicer summary buffer line format. -* Diary Articles Sorting:: A nicer way to sort messages. -* Diary Headers Generation:: Not doing it manually. -* Diary Group Parameters:: Not handling them manually. - -Gnus Unplugged - -* Agent Basics:: How it all is supposed to work. -* Agent Categories:: How to tell the Gnus Agent what to download. -* Agent Commands:: New commands for all the buffers. -* Agent Visuals:: Ways that the agent may effect your summary buffer. -* Agent as Cache:: The Agent is a big cache too. -* Agent Expiry:: How to make old articles go away. -* Agent Regeneration:: How to recover from lost connections and other accidents. -* Agent and flags:: How the Agent maintains flags. -* Agent and IMAP:: How to use the Agent with @acronym{IMAP}. -* Outgoing Messages:: What happens when you post/mail something? -* Agent Variables:: Customizing is fun. -* Example Setup:: An example @file{~/.gnus.el} file for offline people. -* Batching Agents:: How to fetch news from a @code{cron} job. -* Agent Caveats:: What you think it'll do and what it does. - -Agent Categories - -* Category Syntax:: What a category looks like. -* Category Buffer:: A buffer for maintaining categories. -* Category Variables:: Customize'r'Us. - -Agent Commands - -* Group Agent Commands:: Configure groups and fetch their contents. -* Summary Agent Commands:: Manually select then fetch specific articles. -* Server Agent Commands:: Select the servers that are supported by the agent. - -Scoring - -* Summary Score Commands:: Adding score entries for the current group. -* Group Score Commands:: General score commands. -* Score Variables:: Customize your scoring. (My, what terminology). -* Score File Format:: What a score file may contain. -* Score File Editing:: You can edit score files by hand as well. -* Adaptive Scoring:: Big Sister Gnus knows what you read. -* Home Score File:: How to say where new score entries are to go. -* Followups To Yourself:: Having Gnus notice when people answer you. -* Scoring On Other Headers:: Scoring on non-standard headers. -* Scoring Tips:: How to score effectively. -* Reverse Scoring:: That problem child of old is not problem. -* Global Score Files:: Earth-spanning, ear-splitting score files. -* Kill Files:: They are still here, but they can be ignored. -* Converting Kill Files:: Translating kill files to score files. -* Advanced Scoring:: Using logical expressions to build score rules. -* Score Decays:: It can be useful to let scores wither away. - -Advanced Scoring - -* Advanced Scoring Syntax:: A definition. -* Advanced Scoring Examples:: What they look like. -* Advanced Scoring Tips:: Getting the most out of it. - -Searching - -* nnir:: Searching with various engines. -* nnmairix:: Searching with Mairix. - -nnir - -* What is nnir?:: What does nnir do. -* Basic Usage:: How to perform simple searches. -* Setting up nnir:: How to set up nnir. - -Setting up nnir - -* Associating Engines:: How to associate engines. - -Various - -* Process/Prefix:: A convention used by many treatment commands. -* Interactive:: Making Gnus ask you many questions. -* Symbolic Prefixes:: How to supply some Gnus functions with options. -* Formatting Variables:: You can specify what buffers should look like. -* Window Layout:: Configuring the Gnus buffer windows. -* Faces and Fonts:: How to change how faces look. -* Mode Lines:: Displaying information in the mode lines. -* Highlighting and Menus:: Making buffers look all nice and cozy. -* Daemons:: Gnus can do things behind your back. -* Undo:: Some actions can be undone. -* Predicate Specifiers:: Specifying predicates. -* Moderation:: What to do if you're a moderator. -* Image Enhancements:: Modern versions of Emacs/XEmacs can display images. -* Fuzzy Matching:: What's the big fuzz? -* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. -* Spam Package:: A package for filtering and processing spam. -* The Gnus Registry:: A package for tracking messages by Message-ID. -* Other modes:: Interaction with other modes. -* Various Various:: Things that are really various. - -Formatting Variables - -* Formatting Basics:: A formatting variable is basically a format string. -* Mode Line Formatting:: Some rules about mode line formatting variables. -* Advanced Formatting:: Modifying output in various ways. -* User-Defined Specs:: Having Gnus call your own functions. -* Formatting Fonts:: Making the formatting look colorful and nice. -* Positioning Point:: Moving point to a position after an operation. -* Tabulation:: Tabulating your output. -* Wide Characters:: Dealing with wide characters. - -Image Enhancements - -* X-Face:: Display a funky, teensy black-and-white image. -* Face:: Display a funkier, teensier colored image. -* Smileys:: Show all those happy faces the way they were - meant to be shown. -* Picons:: How to display pictures of what you're reading. -* Gravatars:: Display the avatar of people you read. -* XVarious:: Other XEmacsy Gnusey variables. - -Thwarting Email Spam - -* The problem of spam:: Some background, and some solutions -* Anti-Spam Basics:: Simple steps to reduce the amount of spam. -* SpamAssassin:: How to use external anti-spam tools. -* Hashcash:: Reduce spam by burning CPU time. - -Spam Package - -* Spam Package Introduction:: -* Filtering Incoming Mail:: -* Detecting Spam in Groups:: -* Spam and Ham Processors:: -* Spam Package Configuration Examples:: -* Spam Back Ends:: -* Extending the Spam package:: -* Spam Statistics Package:: - -Spam Statistics Package - -* Creating a spam-stat dictionary:: -* Splitting mail using spam-stat:: -* Low-level interface to the spam-stat dictionary:: - -Appendices - -* XEmacs:: Requirements for installing under XEmacs. -* History:: How Gnus got where it is today. -* On Writing Manuals:: Why this is not a beginner's guide. -* Terminology:: We use really difficult, like, words here. -* Customization:: Tailoring Gnus to your needs. -* Troubleshooting:: What you might try if things do not work. -* Gnus Reference Guide:: Rilly, rilly technical stuff. -* Emacs for Heathens:: A short introduction to Emacsian terms. -* Frequently Asked Questions:: The Gnus FAQ - -History - -* Gnus Versions:: What Gnus versions have been released. -* Why?:: What's the point of Gnus? -* Compatibility:: Just how compatible is Gnus with @sc{gnus}? -* Conformity:: Gnus tries to conform to all standards. -* Emacsen:: Gnus can be run on a few modern Emacsen. -* Gnus Development:: How Gnus is developed. -* Contributors:: Oodles of people. -* New Features:: Pointers to some of the new stuff in Gnus. - -New Features - -* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. -* September Gnus:: The Thing Formally Known As Gnus 5.2/5.3. -* Red Gnus:: Third time best---Gnus 5.4/5.5. -* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7. -* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9. -* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11. -* No Gnus:: Very punny. Gnus 5.12/5.13 -* Ma Gnus:: Celebrating 25 years of Gnus. - -Customization - -* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. -* Slow Terminal Connection:: You run a remote Emacs. -* Little Disk Space:: You feel that having large setup files is icky. -* Slow Machine:: You feel like buying a faster machine. - -Gnus Reference Guide - -* Gnus Utility Functions:: Common functions and variable to use. -* Back End Interface:: How Gnus communicates with the servers. -* Score File Syntax:: A BNF definition of the score file standard. -* Headers:: How Gnus stores headers internally. -* Ranges:: A handy format for storing mucho numbers. -* Group Info:: The group info format. -* Extended Interactive:: Symbolic prefixes and stuff. -* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. -* Various File Formats:: Formats of files that Gnus use. - -Back End Interface - -* Required Back End Functions:: Functions that must be implemented. -* Optional Back End Functions:: Functions that need not be implemented. -* Error Messaging:: How to get messages and report errors. -* Writing New Back Ends:: Extending old back ends. -* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end. -* Mail-like Back Ends:: Some tips on mail back ends. - -Various File Formats - -* Active File Format:: Information on articles and groups available. -* Newsgroups File Format:: Group descriptions. - -Emacs for Heathens - -* Keystrokes:: Entering text and executing commands. -* Emacs Lisp:: The built-in Emacs programming language. - -@end detailmenu -@end menu - -@node Starting Up -@chapter Starting Gnus -@cindex starting up - -If you haven't used Emacs much before using Gnus, read @ref{Emacs for -Heathens} first. - -@kindex M-x gnus -@findex gnus -If your system administrator has set things up properly, starting Gnus -and reading news is extremely easy---you just type @kbd{M-x gnus} in -your Emacs. If not, you should customize the variable -@code{gnus-select-method} as described in @ref{Finding the News}. For a -minimal setup for posting should also customize the variables -@code{user-full-name} and @code{user-mail-address}. - -@findex gnus-other-frame -@kindex M-x gnus-other-frame -If you want to start Gnus in a different frame, you can use the command -@kbd{M-x gnus-other-frame} instead. - -If things do not go smoothly at startup, you have to twiddle some -variables in your @file{~/.gnus.el} file. This file is similar to -@file{~/.emacs}, but is read when Gnus starts. - -If you puzzle at any terms used in this manual, please refer to the -terminology section (@pxref{Terminology}). - -@menu -* Finding the News:: Choosing a method for getting news. -* The Server is Down:: How can I read my mail then? -* Slave Gnusae:: You can have more than one Gnus active at a time. -* New Groups:: What is Gnus supposed to do with new groups? -* Changing Servers:: You may want to move from one server to another. -* Startup Files:: Those pesky startup files---@file{.newsrc}. -* Auto Save:: Recovering from a crash. -* The Active File:: Reading the active file over a slow line Takes Time. -* Startup Variables:: Other variables you might change. -@end menu - - -@node Finding the News -@section Finding the News -@cindex finding news - -First of all, you should know that there is a special buffer called -@file{*Server*} that lists all the servers Gnus knows about. You can -press @kbd{^} from the Group buffer to see it. In the Server buffer, -you can press @kbd{RET} on a defined server to see all the groups it -serves (subscribed or not!). You can also add or delete servers, edit -a foreign server's definition, agentize or de-agentize a server, and -do many other neat things. @xref{Server Buffer}. -@xref{Foreign Groups}. @xref{Agent Basics}. - -@vindex gnus-select-method -@c @head -The @code{gnus-select-method} variable says where Gnus should look for -news. This variable should be a list where the first element says -@dfn{how} and the second element says @dfn{where}. This method is your -native method. All groups not fetched with this method are -secondary or foreign groups. - -For instance, if the @samp{news.somewhere.edu} @acronym{NNTP} server is where -you want to get your daily dosage of news from, you'd say: - -@lisp -(setq gnus-select-method '(nntp "news.somewhere.edu")) -@end lisp - -If you want to read directly from the local spool, say: - -@lisp -(setq gnus-select-method '(nnspool "")) -@end lisp - -If you can use a local spool, you probably should, as it will almost -certainly be much faster. But do not use the local spool if your -server is running Leafnode (which is a simple, standalone private news -server); in this case, use @code{(nntp "localhost")}. - -@vindex gnus-nntpserver-file -@cindex NNTPSERVER -@cindex @acronym{NNTP} server -If this variable is not set, Gnus will take a look at the -@env{NNTPSERVER} environment variable. If that variable isn't set, -Gnus will see whether @code{gnus-nntpserver-file} -(@file{/etc/nntpserver} by default) has any opinions on the matter. -If that fails as well, Gnus will try to use the machine running Emacs -as an @acronym{NNTP} server. That's a long shot, though. - -@findex gnus-group-browse-foreign-server -@kindex B (Group) -However, if you use one @acronym{NNTP} server regularly and are just -interested in a couple of groups from a different server, you would be -better served by using the @kbd{B} command in the group buffer. It will -let you have a look at what groups are available, and you can subscribe -to any of the groups you want to. This also makes @file{.newsrc} -maintenance much tidier. @xref{Foreign Groups}. - -@vindex gnus-secondary-select-methods -@c @head -A slightly different approach to foreign groups is to set the -@code{gnus-secondary-select-methods} variable. The select methods -listed in this variable are in many ways just as native as the -@code{gnus-select-method} server. They will also be queried for active -files during startup (if that's required), and new newsgroups that -appear on these servers will be subscribed (or not) just as native -groups are. - -For instance, if you use the @code{nnmbox} back end to read your mail, -you would typically set this variable to - -@lisp -(setq gnus-secondary-select-methods '((nnmbox ""))) -@end lisp - - - -@node The Server is Down -@section The Server is Down -@cindex server errors - -If the default server is down, Gnus will understandably have some -problems starting. However, if you have some mail groups in addition to -the news groups, you may want to start Gnus anyway. - -Gnus, being the trusting sort of program, will ask whether to proceed -without a native select method if that server can't be contacted. This -will happen whether the server doesn't actually exist (i.e., you have -given the wrong address) or the server has just momentarily taken ill -for some reason or other. If you decide to continue and have no foreign -groups, you'll find it difficult to actually do anything in the group -buffer. But, hey, that's your problem. Blllrph! - -@findex gnus-no-server -@kindex M-x gnus-no-server -@c @head -If you know that the server is definitely down, or you just want to read -your mail without bothering with the server at all, you can use the -@code{gnus-no-server} command to start Gnus. That might come in handy -if you're in a hurry as well. This command will not attempt to contact -your primary server---instead, it will just activate all groups on level -1 and 2. (You should preferably keep no native groups on those two -levels.) Also @pxref{Group Levels}. - - -@node Slave Gnusae -@section Slave Gnusae -@cindex slave - -You might want to run more than one Emacs with more than one Gnus at the -same time. If you are using different @file{.newsrc} files (e.g., if you -are using the two different Gnusae to read from two different servers), -that is no problem whatsoever. You just do it. - -The problem appears when you want to run two Gnusae that use the same -@file{.newsrc} file. - -To work around that problem some, we here at the Think-Tank at the Gnus -Towers have come up with a new concept: @dfn{Masters} and -@dfn{slaves}. (We have applied for a patent on this concept, and have -taken out a copyright on those words. If you wish to use those words in -conjunction with each other, you have to send $1 per usage instance to -me. Usage of the patent (@dfn{Master/Slave Relationships In Computer -Applications}) will be much more expensive, of course.) - -@findex gnus-slave -Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or -however you do it). Each subsequent slave Gnusae should be started with -@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc} -files, but instead save @dfn{slave files} that contain information only -on what groups have been read in the slave session. When a master Gnus -starts, it will read (and delete) these slave files, incorporating all -information from them. (The slave files will be read in the sequence -they were created, so the latest changes will have precedence.) - -Information from the slave files has, of course, precedence over the -information in the normal (i.e., master) @file{.newsrc} file. - -If the @file{.newsrc*} files have not been saved in the master when the -slave starts, you may be prompted as to whether to read an auto-save -file. If you answer ``yes'', the unsaved changes to the master will be -incorporated into the slave. If you answer ``no'', the slave may see some -messages as unread that have been read in the master. - - - -@node New Groups -@section New Groups -@cindex new groups -@cindex subscription - -@vindex gnus-check-new-newsgroups -If you are satisfied that you really never want to see any new groups, -you can set @code{gnus-check-new-newsgroups} to @code{nil}. This will -also save you some time at startup. Even if this variable is -@code{nil}, you can always subscribe to the new groups just by pressing -@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable -is @code{ask-server} by default. If you set this variable to -@code{always}, then Gnus will query the back ends for new groups even -when you do the @kbd{g} command (@pxref{Scanning New Messages}). - -@menu -* Checking New Groups:: Determining what groups are new. -* Subscription Methods:: What Gnus should do with new groups. -* Filtering New Groups:: Making Gnus ignore certain new groups. -@end menu - - -@node Checking New Groups -@subsection Checking New Groups - -Gnus normally determines whether a group is new or not by comparing -the list of groups from the active file(s) with the lists of -subscribed and dead groups. This isn't a particularly fast method. -If @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will -ask the server for new groups since the last time. This is both -faster and cheaper. This also means that you can get rid of the list -of killed groups (@pxref{Group Levels}) altogether, so you may set -@code{gnus-save-killed-list} to @code{nil}, which will save time both -at startup, at exit, and all over. Saves disk space, too. Why isn't -this the default, then? Unfortunately, not all servers support this -command. - -I bet I know what you're thinking now: How do I find out whether my -server supports @code{ask-server}? No? Good, because I don't have a -fail-safe answer. I would suggest just setting this variable to -@code{ask-server} and see whether any new groups appear within the next -few days. If any do, then it works. If none do, then it doesn't -work. I could write a function to make Gnus guess whether the server -supports @code{ask-server}, but it would just be a guess. So I won't. -You could @code{telnet} to the server and say @code{HELP} and see -whether it lists @samp{NEWGROUPS} among the commands it understands. If -it does, then it might work. (But there are servers that lists -@samp{NEWGROUPS} without supporting the function properly.) - -This variable can also be a list of select methods. If so, Gnus will -issue an @code{ask-server} command to each of the select methods, and -subscribe them (or not) using the normal methods. This might be handy -if you are monitoring a few servers for new groups. A side effect is -that startup will take much longer, so you can meditate while waiting. -Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss. - - -@node Subscription Methods -@subsection Subscription Methods - -@vindex gnus-subscribe-newsgroup-method -What Gnus does when it encounters a new group is determined by the -@code{gnus-subscribe-newsgroup-method} variable. - -This variable should contain a function. This function will be called -with the name of the new group as the only parameter. - -Some handy pre-fab functions are: - -@table @code - -@item gnus-subscribe-zombies -@vindex gnus-subscribe-zombies -Make all new groups zombies (@pxref{Group Levels}). This is the -default. You can browse the zombies later (with @kbd{A z}) and either -kill them all off properly (with @kbd{S z}), or subscribe to them -(with @kbd{u}). - -@item gnus-subscribe-randomly -@vindex gnus-subscribe-randomly -Subscribe all new groups in arbitrary order. This really means that all -new groups will be added at ``the top'' of the group buffer. - -@item gnus-subscribe-alphabetically -@vindex gnus-subscribe-alphabetically -Subscribe all new groups in alphabetical order. - -@item gnus-subscribe-hierarchically -@vindex gnus-subscribe-hierarchically -Subscribe all new groups hierarchically. The difference between this -function and @code{gnus-subscribe-alphabetically} is slight. -@code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly -alphabetical fashion, while this function will enter groups into its -hierarchy. So if you want to have the @samp{rec} hierarchy before the -@samp{comp} hierarchy, this function will not mess that configuration -up. Or something like that. - -@item gnus-subscribe-interactively -@vindex gnus-subscribe-interactively -Subscribe new groups interactively. This means that Gnus will ask -you about @strong{all} new groups. The groups you choose to subscribe -to will be subscribed hierarchically. - -@item gnus-subscribe-killed -@vindex gnus-subscribe-killed -Kill all new groups. - -@item gnus-subscribe-topics -@vindex gnus-subscribe-topics -Put the groups into the topic that has a matching @code{subscribe} topic -parameter (@pxref{Topic Parameters}). For instance, a @code{subscribe} -topic parameter that looks like - -@example -"nnml" -@end example - -will mean that all groups that match that regex will be subscribed under -that topic. - -If no topics match the groups, the groups will be subscribed in the -top-level topic. - -@end table - -@vindex gnus-subscribe-hierarchical-interactive -A closely related variable is -@code{gnus-subscribe-hierarchical-interactive}. (That's quite a -mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a -hierarchical fashion whether to subscribe to new groups or not. Gnus -will ask you for each sub-hierarchy whether you want to descend the -hierarchy or not. - -One common mistake is to set the variable a few paragraphs above -(@code{gnus-subscribe-newsgroup-method}) to -@code{gnus-subscribe-hierarchical-interactive}. This is an error. This -will not work. This is ga-ga. So don't do it. - - -@node Filtering New Groups -@subsection Filtering New Groups - -A nice and portable way to control which new newsgroups should be -subscribed (or ignored) is to put an @dfn{options} line at the start of -the @file{.newsrc} file. Here's an example: - -@example -options -n !alt.all !rec.all sci.all -@end example - -@vindex gnus-subscribe-options-newsgroup-method -This line obviously belongs to a serious-minded intellectual scientific -person (or she may just be plain old boring), because it says that all -groups that have names beginning with @samp{alt} and @samp{rec} should -be ignored, and all groups with names beginning with @samp{sci} should -be subscribed. Gnus will not use the normal subscription method for -subscribing these groups. -@code{gnus-subscribe-options-newsgroup-method} is used instead. This -variable defaults to @code{gnus-subscribe-alphabetically}. - -The ``options -n'' format is very simplistic. The syntax above is all -that is supports: you can force-subscribe hierarchies, or you can -deny hierarchies, and that's it. - -@vindex gnus-options-not-subscribe -@vindex gnus-options-subscribe -If you don't want to mess with your @file{.newsrc} file, you can just -set the two variables @code{gnus-options-subscribe} and -@code{gnus-options-not-subscribe}. These two variables do exactly the -same as the @file{.newsrc} @samp{options -n} trick. Both are regexps, -and if the new group matches the former, it will be unconditionally -subscribed, and if it matches the latter, it will be ignored. - -@vindex gnus-auto-subscribed-groups -Yet another variable that meddles here is -@code{gnus-auto-subscribed-groups}. It works exactly like -@code{gnus-options-subscribe}, and is therefore really superfluous, -but I thought it would be nice to have two of these. This variable is -more meant for setting some ground rules, while the other variable is -used more for user fiddling. By default this variable makes all new -groups that come from mail back ends (@code{nnml}, @code{nnbabyl}, -@code{nnfolder}, @code{nnmbox}, @code{nnmh}, @code{nnimap}, and -@code{nnmaildir}) subscribed. If you don't like that, just set this -variable to @code{nil}. - -@vindex gnus-auto-subscribed-categories -As if that wasn't enough, @code{gnus-auto-subscribed-categories} also -allows you to specify that new groups should be subscribed based on the -category their select methods belong to. The default is @samp{(mail -post-mail)}, meaning that all new groups from mail-like backends -should be subscribed automatically. - -New groups that match these variables are subscribed using -@code{gnus-subscribe-options-newsgroup-method}. - - -@node Changing Servers -@section Changing Servers -@cindex changing servers - -Sometimes it is necessary to move from one @acronym{NNTP} server to another. -This happens very rarely, but perhaps you change jobs, or one server is -very flaky and you want to use another. - -Changing the server is pretty easy, right? You just change -@code{gnus-select-method} to point to the new server? - -@emph{Wrong!} - -Article numbers are not (in any way) kept synchronized between different -@acronym{NNTP} servers, and the only way Gnus keeps track of what articles -you have read is by keeping track of article numbers. So when you -change @code{gnus-select-method}, your @file{.newsrc} file becomes -worthless. - -@kindex M-x gnus-group-clear-data-on-native-groups -@findex gnus-group-clear-data-on-native-groups -You can use the @kbd{M-x gnus-group-clear-data-on-native-groups} -command to clear out all data that you have on your native groups. -Use with caution. - -@kindex M-x gnus-group-clear-data -@findex gnus-group-clear-data -Clear the data from the current group only---nix out marks and the -list of read articles (@code{gnus-group-clear-data}). - -After changing servers, you @strong{must} move the cache hierarchy away, -since the cached articles will have wrong article numbers, which will -affect which articles Gnus thinks are read. -@code{gnus-group-clear-data-on-native-groups} will ask you if you want -to have it done automatically; for @code{gnus-group-clear-data}, you -can use @kbd{M-x gnus-cache-move-cache} (but beware, it will move the -cache for all groups). - - -@node Startup Files -@section Startup Files -@cindex startup files -@cindex .newsrc -@cindex .newsrc.el -@cindex .newsrc.eld - -Most common Unix news readers use a shared startup file called -@file{.newsrc}. This file contains all the information about what -groups are subscribed, and which articles in these groups have been -read. - -Things got a bit more complicated with @sc{gnus}. In addition to -keeping the @file{.newsrc} file updated, it also used a file called -@file{.newsrc.el} for storing all the information that didn't fit into -the @file{.newsrc} file. (Actually, it also duplicated everything in -the @file{.newsrc} file.) @sc{gnus} would read whichever one of these -files was the most recently saved, which enabled people to swap between -@sc{gnus} and other newsreaders. - -That was kinda silly, so Gnus went one better: In addition to the -@file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called -@file{.newsrc.eld}. It will read whichever of these files that are most -recent, but it will never write a @file{.newsrc.el} file. You should -never delete the @file{.newsrc.eld} file---it contains much information -not stored in the @file{.newsrc} file. - -@vindex gnus-save-newsrc-file -@vindex gnus-read-newsrc-file -You can turn off writing the @file{.newsrc} file by setting -@code{gnus-save-newsrc-file} to @code{nil}, which means you can delete -the file and save some space, as well as exiting from Gnus faster. -However, this will make it impossible to use other newsreaders than -Gnus. But hey, who would want to, right? Similarly, setting -@code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the -@file{.newsrc} file and any @file{.newsrc-SERVER} files, which can be -convenient if you use a different news reader occasionally, and you -want to read a different subset of the available groups with that -news reader. - -@vindex gnus-save-killed-list -If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus -will not save the list of killed groups to the startup file. This will -save both time (when starting and quitting) and space (on disk). It -will also mean that Gnus has no record of what groups are new or old, -so the automatic new groups subscription methods become meaningless. -You should always set @code{gnus-check-new-newsgroups} to @code{nil} or -@code{ask-server} if you set this variable to @code{nil} (@pxref{New -Groups}). This variable can also be a regular expression. If that's -the case, remove all groups that do not match this regexp before -saving. This can be useful in certain obscure situations that involve -several servers where not all servers support @code{ask-server}. - -@vindex gnus-startup-file -@vindex gnus-backup-startup-file -@vindex version-control -The @code{gnus-startup-file} variable says where the startup files are. -The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup -file being whatever that one is, with a @samp{.eld} appended. -If you want to keep multiple numbered backups of this file, set -@code{gnus-backup-startup-file}. It respects the same values as the -@code{version-control} variable. - -@vindex gnus-save-newsrc-hook -@vindex gnus-save-quick-newsrc-hook -@vindex gnus-save-standard-newsrc-hook -@code{gnus-save-newsrc-hook} is called before saving any of the newsrc -files, while @code{gnus-save-quick-newsrc-hook} is called just before -saving the @file{.newsrc.eld} file, and -@code{gnus-save-standard-newsrc-hook} is called just before saving the -@file{.newsrc} file. The latter two are commonly used to turn version -control on or off. Version control is on by default when saving the -startup files. If you want to turn backup creation off, say something like: - -@lisp -(defun turn-off-backup () - (set (make-local-variable 'backup-inhibited) t)) - -(add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup) -(add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup) -@end lisp - -@vindex gnus-init-file -@vindex gnus-site-init-file -When Gnus starts, it will read the @code{gnus-site-init-file} -(@file{.../site-lisp/gnus-init} by default) and @code{gnus-init-file} -(@file{~/.gnus} by default) files. These are normal Emacs Lisp files -and can be used to avoid cluttering your @file{~/.emacs} and -@file{site-init} files with Gnus stuff. Gnus will also check for files -with the same names as these, but with @file{.elc} and @file{.el} -suffixes. In other words, if you have set @code{gnus-init-file} to -@file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el}, -and finally @file{~/.gnus} (in this order). If Emacs was invoked with -the @option{-q} or @option{--no-init-file} options (@pxref{Initial -Options, ,Initial Options, emacs, The Emacs Manual}), Gnus doesn't read -@code{gnus-init-file}. - - -@node Auto Save -@section Auto Save -@cindex dribble file -@cindex auto-save - -Whenever you do something that changes the Gnus data (reading articles, -catching up, killing/subscribing groups), the change is added to a -special @dfn{dribble buffer}. This buffer is auto-saved the normal -Emacs way. If your Emacs should crash before you have saved the -@file{.newsrc} files, all changes you have made can be recovered from -this file. - -If Gnus detects this file at startup, it will ask the user whether to -read it. The auto save file is deleted whenever the real startup file is -saved. - -@vindex gnus-use-dribble-file -If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and -maintain a dribble buffer. The default is @code{t}. - -@vindex gnus-dribble-directory -Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If -this variable is @code{nil}, which it is by default, Gnus will dribble -into the directory where the @file{.newsrc} file is located. (This is -normally the user's home directory.) The dribble file will get the same -file permissions as the @file{.newsrc} file. - -@vindex gnus-always-read-dribble-file -If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will -read the dribble file on startup without querying the user. - - -@node The Active File -@section The Active File -@cindex active file -@cindex ignored groups - -When Gnus starts, or indeed whenever it tries to determine whether new -articles have arrived, it reads the active file. This is a very large -file that lists all the active groups and articles on the server. - -@vindex gnus-ignored-newsgroups -Before examining the active file, Gnus deletes all lines that match the -regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject -any groups with bogus names, but you can use this variable to make Gnus -ignore hierarchies you aren't ever interested in. However, this is not -recommended. In fact, it's highly discouraged. Instead, @pxref{New -Groups} for an overview of other variables that can be used instead. - -@c This variable is -@c @code{nil} by default, and will slow down active file handling somewhat -@c if you set it to anything else. - -@vindex gnus-read-active-file -@c @head -The active file can be rather Huge, so if you have a slow network, you -can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from -reading the active file. This variable is @code{some} by default. - -Gnus will try to make do by getting information just on the groups that -you actually subscribe to. - -Note that if you subscribe to lots and lots of groups, setting this -variable to @code{nil} will probably make Gnus slower, not faster. At -present, having this variable @code{nil} will slow Gnus down -considerably, unless you read news over a 2400 baud modem. - -This variable can also have the value @code{some}. Gnus will then -attempt to read active info only on the subscribed groups. On some -servers this is quite fast (on sparkling, brand new INN servers that -support the @code{LIST ACTIVE group} command), on others this isn't fast -at all. In any case, @code{some} should be faster than @code{nil}, and -is certainly faster than @code{t} over slow lines. - -Some news servers (old versions of Leafnode and old versions of INN, for -instance) do not support the @code{LIST ACTIVE group}. For these -servers, @code{nil} is probably the most efficient value for this -variable. - -If this variable is @code{nil}, Gnus will ask for group info in total -lock-step, which isn't very fast. If it is @code{some} and you use an -@acronym{NNTP} server, Gnus will pump out commands as fast as it can, and -read all the replies in one swoop. This will normally result in better -performance, but if the server does not support the aforementioned -@code{LIST ACTIVE group} command, this isn't very nice to the server. - -If you think that starting up Gnus takes too long, try all the three -different values for this variable and see what works best for you. - -In any case, if you use @code{some} or @code{nil}, you should definitely -kill all groups that you aren't interested in to speed things up. - -Note that this variable also affects active file retrieval from -secondary select methods. - - -@node Startup Variables -@section Startup Variables - -@table @code - -@item gnus-load-hook -@vindex gnus-load-hook -A hook run while Gnus is being loaded. Note that this hook will -normally be run just once in each Emacs session, no matter how many -times you start Gnus. - -@item gnus-before-startup-hook -@vindex gnus-before-startup-hook -A hook called as the first thing when Gnus is started. - -@item gnus-before-resume-hook -@vindex gnus-before-resume-hook -A hook called as the first thing when Gnus is resumed after a suspend. - -@item gnus-startup-hook -@vindex gnus-startup-hook -A hook run as the very last thing after starting up Gnus - -@item gnus-started-hook -@vindex gnus-started-hook -A hook that is run as the very last thing after starting up Gnus -successfully. - -@item gnus-setup-news-hook -@vindex gnus-setup-news-hook -A hook that is run after reading the @file{.newsrc} file(s), but before -generating the group buffer. - -@item gnus-check-bogus-newsgroups -@vindex gnus-check-bogus-newsgroups -If non-@code{nil}, Gnus will check for and delete all bogus groups at -startup. A @dfn{bogus group} is a group that you have in your -@file{.newsrc} file, but doesn't exist on the news server. Checking for -bogus groups can take quite a while, so to save time and resources it's -best to leave this option off, and do the checking for bogus groups once -in a while from the group buffer instead (@pxref{Group Maintenance}). - -@item gnus-inhibit-startup-message -@vindex gnus-inhibit-startup-message -If non-@code{nil}, the startup message won't be displayed. That way, -your boss might not notice as easily that you are reading news instead -of doing your job. Note that this variable is used before -@file{~/.gnus.el} is loaded, so it should be set in @file{.emacs} instead. - -@item gnus-no-groups-message -@vindex gnus-no-groups-message -Message displayed by Gnus when no groups are available. - -@item gnus-use-backend-marks -@vindex gnus-use-backend-marks -If non-@code{nil}, Gnus will store article marks both in the -@file{.newsrc.eld} file and in the backends. This will slow down -group operation some. - -@end table - - -@node Group Buffer -@chapter Group Buffer -@cindex group buffer - -@c Alex Schroeder suggests to rearrange this as follows: -@c -@c ok, just save it for reference. I'll go to bed in a minute. -@c 1. Selecting a Group, 2. (new) Finding a Group, 3. Group Levels, -@c 4. Subscription Commands, 5. Group Maneuvering, 6. Group Data, -@c 7. Group Score, 8. Group Buffer Format -@c Group Levels should have more information on levels 5 to 9. I -@c suggest to split the 4th paragraph ("Gnus considers groups...") as follows: -@c First, "Gnus considers groups... (default 9)." -@c New, a table summarizing what levels 1 to 9 mean. -@c Third, "Gnus treats subscribed ... reasons of efficiency" -@c Then expand the next paragraph or add some more to it. -@c This short one sentence explains levels 1 and 2, therefore I understand -@c that I should keep important news at 3 and boring news at 4. -@c Say so! Then go on to explain why I should bother with levels 6 to 9. -@c Maybe keep those that you don't want to read temporarily at 6, -@c those that you never want to read at 8, those that offend your -@c human rights at 9... - - -The @dfn{group buffer} lists all (or parts) of the available groups. It -is the first buffer shown when Gnus starts, and will never be killed as -long as Gnus is active. - -@iftex -@iflatex -\gnusfigure{The Group Buffer}{320}{ -\put(75,50){\epsfig{figure=ps/group,height=9cm}} -\put(120,37){\makebox(0,0)[t]{Buffer name}} -\put(120,38){\vector(1,2){10}} -\put(40,60){\makebox(0,0)[r]{Mode line}} -\put(40,58){\vector(1,0){30}} -\put(200,28){\makebox(0,0)[t]{Native select method}} -\put(200,26){\vector(-1,2){15}} -} -@end iflatex -@end iftex - -@menu -* Group Buffer Format:: Information listed and how you can change it. -* Group Maneuvering:: Commands for moving in the group buffer. -* Selecting a Group:: Actually reading news. -* Subscription Commands:: Unsubscribing, killing, subscribing. -* Group Data:: Changing the info for a group. -* Group Levels:: Levels? What are those, then? -* Group Score:: A mechanism for finding out what groups you like. -* Marking Groups:: You can mark groups for later processing. -* Foreign Groups:: Creating and editing groups. -* Group Parameters:: Each group may have different parameters set. -* Listing Groups:: Gnus can list various subsets of the groups. -* Sorting Groups:: Re-arrange the group order. -* Group Maintenance:: Maintaining a tidy @file{.newsrc} file. -* Browse Foreign Server:: You can browse a server. See what it has to offer. -* Exiting Gnus:: Stop reading news and get some work done. -* Group Topics:: A folding group mode divided into topics. -* Non-ASCII Group Names:: Accessing groups of non-English names. -* Misc Group Stuff:: Other stuff that you can to do. -@end menu - - -@node Group Buffer Format -@section Group Buffer Format - -@menu -* Group Line Specification:: Deciding how the group buffer is to look. -* Group Mode Line Specification:: The group buffer mode line. -* Group Highlighting:: Having nice colors in the group buffer. -@end menu - -You can customize the Group Mode tool bar, see @kbd{M-x -customize-apropos RET gnus-group-tool-bar}. This feature is only -available in Emacs. - -The tool bar icons are now (de)activated correctly depending on the -cursor position. Therefore, moving around in the Group Buffer is -slower. You can disable this via the variable -@code{gnus-group-update-tool-bar}. Its default value depends on your -Emacs version. - -@node Group Line Specification -@subsection Group Line Specification -@cindex group buffer format - -The default format of the group buffer is nice and dull, but you can -make it as exciting and ugly as you feel like. - -Here's a couple of example group lines: - -@example - 25: news.announce.newusers - * 0: alt.fan.andrea-dworkin -@end example - -Quite simple, huh? - -You can see that there are 25 unread articles in -@samp{news.announce.newusers}. There are no unread articles, but some -ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little -asterisk at the beginning of the line?). - -@vindex gnus-group-line-format -You can change that format to whatever you want by fiddling with the -@code{gnus-group-line-format} variable. This variable works along the -lines of a @code{format} specification, which is pretty much the same as -a @code{printf} specifications, for those of you who use (feh!) C@. -@xref{Formatting Variables}. - -@samp{%M%S%5y:%B%(%g%)\n} is the value that produced those lines above. - -There should always be a colon on the line; the cursor always moves to -the colon after performing an operation. @xref{Positioning -Point}. Nothing else is required---not even the group name. All -displayed text is just window dressing, and is never examined by Gnus. -Gnus stores all real information it needs using text properties. - -(Note that if you make a really strange, wonderful, spreadsheet-like -layout, everybody will believe you are hard at work with the accounting -instead of wasting time reading news.) - -Here's a list of all available format characters: - -@table @samp - -@item M -An asterisk if the group only has marked articles. - -@item S -Whether the group is subscribed. - -@item L -Level of subscribedness. - -@item N -Number of unread articles. - -@item I -Number of dormant articles. - -@item T -Number of ticked articles. - -@item R -Number of read articles. - -@item U -Number of unseen articles. - -@item t -Estimated total number of articles. (This is really @var{max-number} -minus @var{min-number} plus 1.) - -Gnus uses this estimation because the @acronym{NNTP} protocol provides -efficient access to @var{max-number} and @var{min-number} but getting -the true unread message count is not possible efficiently. For -hysterical raisins, even the mail back ends, where the true number of -unread messages might be available efficiently, use the same limited -interface. To remove this restriction from Gnus means that the back -end interface has to be changed, which is not an easy job. - -The nnml backend (@pxref{Mail Spool}) has a feature called ``group -compaction'' which circumvents this deficiency: the idea is to -renumber all articles from 1, removing all gaps between numbers, hence -getting a correct total count. Other backends may support this in the -future. In order to keep your total article count relatively up to -date, you might want to compact your groups (or even directly your -server) from time to time. @xref{Misc Group Stuff}, @xref{Server Commands}. - -@item y -Number of unread, unticked, non-dormant articles. - -@item i -Number of ticked and dormant articles. - -@item g -Full group name. - -@item G -Group name. - -@item C -Group comment (@pxref{Group Parameters}) or group name if there is no -comment element in the group parameters. - -@item D -Newsgroup description. You need to read the group descriptions -before these will appear, and to do that, you either have to set -@code{gnus-read-active-file} or use the group buffer @kbd{M-d} -command. - -@item o -@samp{m} if moderated. - -@item O -@samp{(m)} if moderated. - -@item s -Select method. - -@item B -If the summary buffer for the group is open or not. - -@item n -Select from where. - -@item z -A string that looks like @samp{<%s:%n>} if a foreign select method is -used. - -@item P -Indentation based on the level of the topic (@pxref{Group Topics}). - -@item c -@vindex gnus-group-uncollapsed-levels -Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels} -variable says how many levels to leave at the end of the group name. -The default is 1---this will mean that group names like -@samp{gnu.emacs.gnus} will be shortened to @samp{g.e.gnus}. - -@item m -@vindex gnus-new-mail-mark -@cindex % -@samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to -the group lately. - -@item p -@samp{#} (@code{gnus-process-mark}) if the group is process marked. - -@item d -A string that says when you last read the group (@pxref{Group -Timestamp}). - -@item F -The disk space used by the articles fetched by both the cache and -agent. The value is automatically scaled to bytes(B), kilobytes(K), -megabytes(M), or gigabytes(G) to minimize the column width. A format -of %7F is sufficient for a fixed-width column. - -@item u -User defined specifier. The next character in the format string should -be a letter. Gnus will call the function -@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter -following @samp{%u}. The function will be passed a single dummy -parameter as argument. The function should return a string, which will -be inserted into the buffer just like information from any other -specifier. -@end table - -@cindex * -All the ``number-of'' specs will be filled with an asterisk (@samp{*}) -if no info is available---for instance, if it is a non-activated foreign -group, or a bogus native group. - - -@node Group Mode Line Specification -@subsection Group Mode Line Specification -@cindex group mode line - -@vindex gnus-group-mode-line-format -The mode line can be changed by setting -@code{gnus-group-mode-line-format} (@pxref{Mode Line Formatting}). It -doesn't understand that many format specifiers: - -@table @samp -@item S -The native news server. -@item M -The native select method. -@end table - - -@node Group Highlighting -@subsection Group Highlighting -@cindex highlighting -@cindex group highlighting - -@vindex gnus-group-highlight -Highlighting in the group buffer is controlled by the -@code{gnus-group-highlight} variable. This is an alist with elements -that look like @code{(@var{form} . @var{face})}. If @var{form} evaluates to -something non-@code{nil}, the @var{face} will be used on the line. - -Here's an example value for this variable that might look nice if the -background is dark: - -@lisp -(cond (window-system - (setq custom-background-mode 'light) - (defface my-group-face-1 - '((t (:foreground "Red" :bold t))) "First group face") - (defface my-group-face-2 - '((t (:foreground "DarkSeaGreen4" :bold t))) - "Second group face") - (defface my-group-face-3 - '((t (:foreground "Green4" :bold t))) "Third group face") - (defface my-group-face-4 - '((t (:foreground "SteelBlue" :bold t))) "Fourth group face") - (defface my-group-face-5 - '((t (:foreground "Blue" :bold t))) "Fifth group face"))) - -(setq gnus-group-highlight - '(((> unread 200) . my-group-face-1) - ((and (< level 3) (zerop unread)) . my-group-face-2) - ((< level 3) . my-group-face-3) - ((zerop unread) . my-group-face-4) - (t . my-group-face-5))) -@end lisp - -Also @pxref{Faces and Fonts}. - -Variables that are dynamically bound when the forms are evaluated -include: - -@table @code -@item group -The group name. -@item unread -The number of unread articles in the group. -@item method -The select method. -@item mailp -Whether the group is a mail group. -@item level -The level of the group. -@item score -The score of the group. -@item ticked -The number of ticked articles in the group. -@item total -The total number of articles in the group. Or rather, -@var{max-number} minus @var{min-number} plus one. -@item topic -When using the topic minor mode, this variable is bound to the current -topic being inserted. -@end table - -When the forms are @code{eval}ed, point is at the beginning of the line -of the group in question, so you can use many of the normal Gnus -functions for snarfing info on the group. - -@vindex gnus-group-update-hook -@findex gnus-group-highlight-line -@code{gnus-group-update-hook} is called when a group line is changed. -It will not be called when @code{gnus-visual} is @code{nil}. - - -@node Group Maneuvering -@section Group Maneuvering -@cindex group movement - -All movement commands understand the numeric prefix and will behave as -expected, hopefully. - -@table @kbd - -@item n -@kindex n (Group) -@findex gnus-group-next-unread-group -Go to the next group that has unread articles -(@code{gnus-group-next-unread-group}). - -@item p -@itemx DEL -@kindex DEL (Group) -@kindex p (Group) -@findex gnus-group-prev-unread-group -Go to the previous group that has unread articles -(@code{gnus-group-prev-unread-group}). - -@item N -@kindex N (Group) -@findex gnus-group-next-group -Go to the next group (@code{gnus-group-next-group}). - -@item P -@kindex P (Group) -@findex gnus-group-prev-group -Go to the previous group (@code{gnus-group-prev-group}). - -@item M-n -@kindex M-n (Group) -@findex gnus-group-next-unread-group-same-level -Go to the next unread group on the same (or lower) level -(@code{gnus-group-next-unread-group-same-level}). - -@item M-p -@kindex M-p (Group) -@findex gnus-group-prev-unread-group-same-level -Go to the previous unread group on the same (or lower) level -(@code{gnus-group-prev-unread-group-same-level}). -@end table - -Three commands for jumping to groups: - -@table @kbd - -@item j -@kindex j (Group) -@findex gnus-group-jump-to-group -Jump to a group (and make it visible if it isn't already) -(@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just -like living groups. - -@item , -@kindex , (Group) -@findex gnus-group-best-unread-group -Jump to the unread group with the lowest level -(@code{gnus-group-best-unread-group}). - -@item . -@kindex . (Group) -@findex gnus-group-first-unread-group -Jump to the first group with unread articles -(@code{gnus-group-first-unread-group}). -@end table - -@vindex gnus-group-goto-unread -If @code{gnus-group-goto-unread} is @code{nil}, all the movement -commands will move to the next group, not the next unread group. Even -the commands that say they move to the next unread group. The default -is @code{t}. - -@vindex gnus-summary-next-group-on-exit -If @code{gnus-summary-next-group-on-exit} is @code{t}, when a summary is -exited, the point in the group buffer is moved to the next unread group. -Otherwise, the point is set to the group just exited. The default is -@code{t}. - -@node Selecting a Group -@section Selecting a Group -@cindex group selection - -@table @kbd - -@item SPACE -@kindex SPACE (Group) -@findex gnus-group-read-group -Select the current group, switch to the summary buffer and display the -first unread article (@code{gnus-group-read-group}). If there are no -unread articles in the group, or if you give a non-numerical prefix to -this command, Gnus will offer to fetch all the old articles in this -group from the server. If you give a numerical prefix @var{n}, @var{n} -determines the number of articles Gnus will fetch. If @var{n} is -positive, Gnus fetches the @var{n} newest articles, if @var{n} is -negative, Gnus fetches the @code{abs(@var{n})} oldest articles. - -Thus, @kbd{SPC} enters the group normally, @kbd{C-u SPC} offers old -articles, @kbd{C-u 4 2 SPC} fetches the 42 newest articles, and @kbd{C-u -- 4 2 SPC} fetches the 42 oldest ones. - -When you are in the group (in the Summary buffer), you can type -@kbd{M-g} to fetch new articles, or @kbd{C-u M-g} to also show the old -ones. - -@item RET -@kindex RET (Group) -@findex gnus-group-select-group -Select the current group and switch to the summary buffer -(@code{gnus-group-select-group}). Takes the same arguments as -@code{gnus-group-read-group}---the only difference is that this command -does not display the first unread article automatically upon group -entry. - -@item M-RET -@kindex M-RET (Group) -@findex gnus-group-quick-select-group -This does the same as the command above, but tries to do it with the -minimum amount of fuzz (@code{gnus-group-quick-select-group}). No -scoring/killing will be performed, there will be no highlights and no -expunging. This might be useful if you're in a real hurry and have to -enter some humongous group. If you give a 0 prefix to this command -(i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer, -which is useful if you want to toggle threading before generating the -summary buffer (@pxref{Summary Generation Commands}). - -@item M-SPACE -@kindex M-SPACE (Group) -@findex gnus-group-visible-select-group -This is yet one more command that does the same as the @kbd{RET} -command, but this one does it without expunging and hiding dormants -(@code{gnus-group-visible-select-group}). - -@item C-M-RET -@kindex C-M-RET (Group) -@findex gnus-group-select-group-ephemerally -Finally, this command selects the current group ephemerally without -doing any processing of its contents -(@code{gnus-group-select-group-ephemerally}). Even threading has been -turned off. Everything you do in the group after selecting it in this -manner will have no permanent effects. - -@end table - -@vindex gnus-large-newsgroup -The @code{gnus-large-newsgroup} variable says what Gnus should -consider to be a big group. If it is @code{nil}, no groups are -considered big. The default value is 200. If the group has more -(unread and/or ticked) articles than this, Gnus will query the user -before entering the group. The user can then specify how many -articles should be fetched from the server. If the user specifies a -negative number (@var{-n}), the @var{n} oldest articles will be -fetched. If it is positive, the @var{n} articles that have arrived -most recently will be fetched. - -@vindex gnus-large-ephemeral-newsgroup -@code{gnus-large-ephemeral-newsgroup} is the same as -@code{gnus-large-newsgroup}, but is only used for ephemeral -newsgroups. - -@vindex gnus-newsgroup-maximum-articles -In groups in some news servers, there might be a big gap between a few -very old articles that will never be expired and the recent ones. In -such a case, the server will return the data like @code{(1 . 30000000)} -for the @code{LIST ACTIVE group} command, for example. Even if there -are actually only the articles 1--10 and 29999900--30000000, Gnus doesn't -know it at first and prepares for getting 30000000 articles. However, -it will consume hundreds megabytes of memories and might make Emacs get -stuck as the case may be. If you use such news servers, set the -variable @code{gnus-newsgroup-maximum-articles} to a positive number. -The value means that Gnus ignores articles other than this number of the -latest ones in every group. For instance, the value 10000 makes Gnus -get only the articles 29990001--30000000 (if the latest article number is -30000000 in a group). Note that setting this variable to a number might -prevent you from reading very old articles. The default value of the -variable @code{gnus-newsgroup-maximum-articles} is @code{nil}, which -means Gnus never ignores old articles. - -@vindex gnus-select-group-hook -@vindex gnus-auto-select-first -@vindex gnus-auto-select-subject -If @code{gnus-auto-select-first} is non-@code{nil}, select an article -automatically when entering a group with the @kbd{SPACE} command. -Which article this is controlled by the -@code{gnus-auto-select-subject} variable. Valid values for this -variable are: - -@table @code - -@item unread -Place point on the subject line of the first unread article. - -@item first -Place point on the subject line of the first article. - -@item unseen -Place point on the subject line of the first unseen article. - -@item unseen-or-unread -Place point on the subject line of the first unseen article, and if -there is no such article, place point on the subject line of the first -unread article. - -@item best -Place point on the subject line of the highest-scored unread article. - -@end table - -This variable can also be a function. In that case, that function -will be called to place point on a subject line. - -If you want to prevent automatic selection in some group (say, in a -binary group with Huge articles) you can set the -@code{gnus-auto-select-first} variable to @code{nil} in -@code{gnus-select-group-hook}, which is called when a group is -selected. - - -@node Subscription Commands -@section Subscription Commands -@cindex subscription - -The following commands allow for managing your subscriptions in the -Group buffer. If you want to subscribe to many groups, it's probably -more convenient to go to the @ref{Server Buffer}, and choose the -server there using @kbd{RET} or @kbd{SPC}. Then you'll have the -commands listed in @ref{Browse Foreign Server} at hand. - -@table @kbd - -@item S t -@itemx u -@kindex S t (Group) -@kindex u (Group) -@findex gnus-group-unsubscribe-current-group -@c @icon{gnus-group-unsubscribe} -Toggle subscription to the current group -(@code{gnus-group-unsubscribe-current-group}). - -@item S s -@itemx U -@kindex S s (Group) -@kindex U (Group) -@findex gnus-group-unsubscribe-group -Prompt for a group to subscribe, and then subscribe it. If it was -subscribed already, unsubscribe it instead -(@code{gnus-group-unsubscribe-group}). - -@item S k -@itemx C-k -@kindex S k (Group) -@kindex C-k (Group) -@findex gnus-group-kill-group -@c @icon{gnus-group-kill-group} -Kill the current group (@code{gnus-group-kill-group}). - -@item S y -@itemx C-y -@kindex S y (Group) -@kindex C-y (Group) -@findex gnus-group-yank-group -Yank the last killed group (@code{gnus-group-yank-group}). - -@item C-x C-t -@kindex C-x C-t (Group) -@findex gnus-group-transpose-groups -Transpose two groups (@code{gnus-group-transpose-groups}). This isn't -really a subscription command, but you can use it instead of a -kill-and-yank sequence sometimes. - -@item S w -@itemx C-w -@kindex S w (Group) -@kindex C-w (Group) -@findex gnus-group-kill-region -Kill all groups in the region (@code{gnus-group-kill-region}). - -@item S z -@kindex S z (Group) -@findex gnus-group-kill-all-zombies -Kill all zombie groups (@code{gnus-group-kill-all-zombies}). - -@item S C-k -@kindex S C-k (Group) -@findex gnus-group-kill-level -Kill all groups on a certain level (@code{gnus-group-kill-level}). -These groups can't be yanked back after killing, so this command should -be used with some caution. The only time where this command comes in -really handy is when you have a @file{.newsrc} with lots of unsubscribed -groups that you want to get rid off. @kbd{S C-k} on level 7 will -kill off all unsubscribed groups that do not have message numbers in the -@file{.newsrc} file. - -@end table - -Also @pxref{Group Levels}. - - -@node Group Data -@section Group Data - -@table @kbd - -@item c -@kindex c (Group) -@findex gnus-group-catchup-current -@vindex gnus-group-catchup-group-hook -@c @icon{gnus-group-catchup-current} -Mark all unticked articles in this group as read -(@code{gnus-group-catchup-current}). -@code{gnus-group-catchup-group-hook} is called when catching up a group from -the group buffer. - -@item C -@kindex C (Group) -@findex gnus-group-catchup-current-all -Mark all articles in this group, even the ticked ones, as read -(@code{gnus-group-catchup-current-all}). - -@item M-c -@kindex M-c (Group) -@findex gnus-group-clear-data -Clear the data from the current group---nix out marks and the list of -read articles (@code{gnus-group-clear-data}). - -@item M-x gnus-group-clear-data-on-native-groups -@kindex M-x gnus-group-clear-data-on-native-groups -@findex gnus-group-clear-data-on-native-groups -If you have switched from one @acronym{NNTP} server to another, all your marks -and read ranges have become worthless. You can use this command to -clear out all data that you have on your native groups. Use with -caution. - -@end table - - -@node Group Levels -@section Group Levels -@cindex group level -@cindex level - -All groups have a level of @dfn{subscribedness}. For instance, if a -group is on level 2, it is more subscribed than a group on level 5. You -can ask Gnus to just list groups on a given level or lower -(@pxref{Listing Groups}), or to just check for new articles in groups on -a given level or lower (@pxref{Scanning New Messages}). - -Remember: The higher the level of the group, the less important it is. - -@table @kbd - -@item S l -@kindex S l (Group) -@findex gnus-group-set-current-level -Set the level of the current group. If a numeric prefix is given, the -next @var{n} groups will have their levels set. The user will be -prompted for a level. -@end table - -@vindex gnus-level-killed -@vindex gnus-level-zombie -@vindex gnus-level-unsubscribed -@vindex gnus-level-subscribed -Gnus considers groups from levels 1 to -@code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed, -@code{gnus-level-subscribed} (exclusive) and -@code{gnus-level-unsubscribed} (inclusive) (default 7) to be -unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead) -(default 8) and @code{gnus-level-killed} to be killed (completely dead) -(default 9). Gnus treats subscribed and unsubscribed groups exactly the -same, but zombie and killed groups store no information on what articles -you have read, etc. This distinction between dead and living -groups isn't done because it is nice or clever, it is done purely for -reasons of efficiency. - -It is recommended that you keep all your mail groups (if any) on quite -low levels (e.g., 1 or 2). - -Maybe the following description of the default behavior of Gnus helps to -understand what these levels are all about. By default, Gnus shows you -subscribed nonempty groups, but by hitting @kbd{L} you can have it show -empty subscribed groups and unsubscribed groups, too. Type @kbd{l} to -go back to showing nonempty subscribed groups again. Thus, unsubscribed -groups are hidden, in a way. - -@cindex zombie groups -Zombie and killed groups are similar to unsubscribed groups in that they -are hidden by default. But they are different from subscribed and -unsubscribed groups in that Gnus doesn't ask the news server for -information (number of messages, number of unread messages) on zombie -and killed groups. Normally, you use @kbd{C-k} to kill the groups you -aren't interested in. If most groups are killed, Gnus is faster. - -Why does Gnus distinguish between zombie and killed groups? Well, when -a new group arrives on the server, Gnus by default makes it a zombie -group. This means that you are normally not bothered with new groups, -but you can type @kbd{A z} to get a list of all new groups. Subscribe -the ones you like and kill the ones you don't want. (@kbd{A k} shows a -list of killed groups.) - -If you want to play with the level variables, you should show some care. -Set them once, and don't touch them ever again. Better yet, don't touch -them at all unless you know exactly what you're doing. - -@vindex gnus-level-default-unsubscribed -@vindex gnus-level-default-subscribed -Two closely related variables are @code{gnus-level-default-subscribed} -(default 3) and @code{gnus-level-default-unsubscribed} (default 6), -which are the levels that new groups will be put on if they are -(un)subscribed. These two variables should, of course, be inside the -relevant valid ranges. - -@vindex gnus-keep-same-level -If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands -will only move to groups of the same level (or lower). In -particular, going from the last article in one group to the next group -will go to the next group of the same level (or lower). This might be -handy if you want to read the most important groups before you read the -rest. - -If this variable is @code{best}, Gnus will make the next newsgroup the -one with the best level. - -@vindex gnus-group-default-list-level -All groups with a level less than or equal to -@code{gnus-group-default-list-level} will be listed in the group buffer -by default. -This variable can also be a function. In that case, that function will -be called and the result will be used as value. - - -@vindex gnus-group-list-inactive-groups -If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active -groups will be listed along with the unread groups. This variable is -@code{t} by default. If it is @code{nil}, inactive groups won't be -listed. - -@vindex gnus-group-use-permanent-levels -If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you -give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will -use this level as the ``work'' level. - -@vindex gnus-activate-level -Gnus will normally just activate (i.e., query the server about) groups -on level @code{gnus-activate-level} or less. If you don't want to -activate unsubscribed groups, for instance, you might set this variable -to 5. The default is 6. - - -@node Group Score -@section Group Score -@cindex group score -@cindex group rank -@cindex rank - -You would normally keep important groups on high levels, but that scheme -is somewhat restrictive. Don't you wish you could have Gnus sort the -group buffer according to how often you read groups, perhaps? Within -reason? - -This is what @dfn{group score} is for. You can have Gnus assign a score -to each group through the mechanism described below. You can then sort -the group buffer based on this score. Alternatively, you can sort on -score and then level. (Taken together, the level and the score is -called the @dfn{rank} of the group. A group that is on level 4 and has -a score of 1 has a higher rank than a group on level 5 that has a score -of 300. (The level is the most significant part and the score is the -least significant part.)) - -@findex gnus-summary-bubble-group -If you want groups you read often to get higher scores than groups you -read seldom you can add the @code{gnus-summary-bubble-group} function to -the @code{gnus-summary-exit-hook} hook. This will result (after -sorting) in a bubbling sort of action. If you want to see that in -action after each summary exit, you can add -@code{gnus-group-sort-groups-by-rank} or -@code{gnus-group-sort-groups-by-score} to the same hook, but that will -slow things down somewhat. - - -@node Marking Groups -@section Marking Groups -@cindex marking groups - -If you want to perform some command on several groups, and they appear -subsequently in the group buffer, you would normally just give a -numerical prefix to the command. Most group commands will then do your -bidding on those groups. - -However, if the groups are not in sequential order, you can still -perform a command on several groups. You simply mark the groups first -with the process mark and then execute the command. - -@table @kbd - -@item # -@kindex # (Group) -@itemx M m -@kindex M m (Group) -@findex gnus-group-mark-group -Set the mark on the current group (@code{gnus-group-mark-group}). - -@item M-# -@kindex M-# (Group) -@itemx M u -@kindex M u (Group) -@findex gnus-group-unmark-group -Remove the mark from the current group -(@code{gnus-group-unmark-group}). - -@item M U -@kindex M U (Group) -@findex gnus-group-unmark-all-groups -Remove the mark from all groups (@code{gnus-group-unmark-all-groups}). - -@item M w -@kindex M w (Group) -@findex gnus-group-mark-region -Mark all groups between point and mark (@code{gnus-group-mark-region}). - -@item M b -@kindex M b (Group) -@findex gnus-group-mark-buffer -Mark all groups in the buffer (@code{gnus-group-mark-buffer}). - -@item M r -@kindex M r (Group) -@findex gnus-group-mark-regexp -Mark all groups that match some regular expression -(@code{gnus-group-mark-regexp}). -@end table - -Also @pxref{Process/Prefix}. - -@findex gnus-group-universal-argument -If you want to execute some command on all groups that have been marked -with the process mark, you can use the @kbd{M-&} -(@code{gnus-group-universal-argument}) command. It will prompt you for -the command to be executed. - - -@node Foreign Groups -@section Foreign Groups -@cindex foreign groups - -If you recall how to subscribe to servers (@pxref{Finding the News}) -you will remember that @code{gnus-secondary-select-methods} and -@code{gnus-select-method} let you write a definition in Emacs Lisp of -what servers you want to see when you start up. The alternate -approach is to use foreign servers and groups. ``Foreign'' here means -they are not coming from the select methods. All foreign server -configuration and subscriptions are stored only in the -@file{~/.newsrc.eld} file. - -Below are some group mode commands for making and editing general foreign -groups, as well as commands to ease the creation of a few -special-purpose groups. All these commands insert the newly created -groups under point---@code{gnus-subscribe-newsgroup-method} is not -consulted. - -Changes from the group editing commands are stored in -@file{~/.newsrc.eld} (@code{gnus-startup-file}). An alternative is the -variable @code{gnus-parameters}, @xref{Group Parameters}. - -@table @kbd - -@item G m -@kindex G m (Group) -@findex gnus-group-make-group -@cindex making groups -Make a new group (@code{gnus-group-make-group}). Gnus will prompt you -for a name, a method and possibly an @dfn{address}. For an easier way -to subscribe to @acronym{NNTP} groups (@pxref{Browse Foreign Server}). - -@item G M -@kindex G M (Group) -@findex gnus-group-read-ephemeral-group -Make an ephemeral group (@code{gnus-group-read-ephemeral-group}). Gnus -will prompt you for a name, a method and an @dfn{address}. - -@item G r -@kindex G r (Group) -@findex gnus-group-rename-group -@cindex renaming groups -Rename the current group to something else -(@code{gnus-group-rename-group}). This is valid only on some -groups---mail groups mostly. This command might very well be quite slow -on some back ends. - -@item G c -@kindex G c (Group) -@cindex customizing -@findex gnus-group-customize -Customize the group parameters (@code{gnus-group-customize}). - -@item G e -@kindex G e (Group) -@findex gnus-group-edit-group-method -@cindex renaming groups -Enter a buffer where you can edit the select method of the current -group (@code{gnus-group-edit-group-method}). - -@item G p -@kindex G p (Group) -@findex gnus-group-edit-group-parameters -Enter a buffer where you can edit the group parameters -(@code{gnus-group-edit-group-parameters}). - -@item G E -@kindex G E (Group) -@findex gnus-group-edit-group -Enter a buffer where you can edit the group info -(@code{gnus-group-edit-group}). - -@item G d -@kindex G d (Group) -@findex gnus-group-make-directory-group -@cindex nndir -Make a directory group (@pxref{Directory Groups}). You will be prompted -for a directory name (@code{gnus-group-make-directory-group}). - -@item G h -@kindex G h (Group) -@cindex help group -@findex gnus-group-make-help-group -Make the Gnus help group (@code{gnus-group-make-help-group}). - -@item G D -@kindex G D (Group) -@findex gnus-group-enter-directory -@cindex nneething -Read an arbitrary directory as if it were a newsgroup with the -@code{nneething} back end (@code{gnus-group-enter-directory}). -@xref{Anything Groups}. - -@item G f -@kindex G f (Group) -@findex gnus-group-make-doc-group -@cindex ClariNet Briefs -@cindex nndoc -Make a group based on some file or other -(@code{gnus-group-make-doc-group}). If you give a prefix to this -command, you will be prompted for a file name and a file type. -Currently supported types are @code{mbox}, @code{babyl}, -@code{digest}, @code{news}, @code{rnews}, @code{mmdf}, @code{forward}, -@code{rfc934}, @code{rfc822-forward}, @code{mime-parts}, -@code{standard-digest}, @code{slack-digest}, @code{clari-briefs}, -@code{nsmail}, @code{outlook}, @code{oe-dbx}, and @code{mailman}. If -you run this command without a prefix, Gnus will guess at the file -type. @xref{Document Groups}. - -@item G u -@kindex G u (Group) -@vindex gnus-useful-groups -@findex gnus-group-make-useful-group -Create one of the groups mentioned in @code{gnus-useful-groups} -(@code{gnus-group-make-useful-group}). - -@item G w -@kindex G w (Group) -@findex gnus-group-make-web-group -@cindex Google -@cindex nnweb -@cindex gmane -Make an ephemeral group based on a web search -(@code{gnus-group-make-web-group}). If you give a prefix to this -command, make a solid group instead. You will be prompted for the -search engine type and the search string. Valid search engine types -include @code{google}, @code{dejanews}, and @code{gmane}. -@xref{Web Searches}. - -If you use the @code{google} search engine, you can limit the search -to a particular group by using a match string like -@samp{shaving group:alt.sysadmin.recovery}. - -@item G R -@kindex G R (Group) -@findex gnus-group-make-rss-group -Make a group based on an @acronym{RSS} feed -(@code{gnus-group-make-rss-group}). You will be prompted for an URL@. -@xref{RSS}. - -@item G DEL -@kindex G DEL (Group) -@findex gnus-group-delete-group -This function will delete the current group -(@code{gnus-group-delete-group}). If given a prefix, this function will -actually delete all the articles in the group, and forcibly remove the -group itself from the face of the Earth. Use a prefix only if you are -absolutely sure of what you are doing. This command can't be used on -read-only groups (like @code{nntp} groups), though. - -@item G V -@kindex G V (Group) -@findex gnus-group-make-empty-virtual -Make a new, fresh, empty @code{nnvirtual} group -(@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}. - -@item G v -@kindex G v (Group) -@findex gnus-group-add-to-virtual -Add the current group to an @code{nnvirtual} group -(@code{gnus-group-add-to-virtual}). Uses the process/prefix convention. -@end table - -@xref{Select Methods}, for more information on the various select -methods. - -@vindex gnus-activate-foreign-newsgroups -If @code{gnus-activate-foreign-newsgroups} is a positive number, -Gnus will check all foreign groups with this level or lower at startup. -This might take quite a while, especially if you subscribe to lots of -groups from different @acronym{NNTP} servers. Also @pxref{Group Levels}; -@code{gnus-activate-level} also affects activation of foreign -newsgroups. - - -The following commands create ephemeral groups. They can be called not -only from the Group buffer, but in any Gnus buffer. - -@table @code -@item gnus-read-ephemeral-gmane-group -@findex gnus-read-ephemeral-gmane-group -@vindex gnus-gmane-group-download-format -Read an ephemeral group on Gmane.org. The articles are downloaded via -HTTP using the URL specified by @code{gnus-gmane-group-download-format}. -Gnus will prompt you for a group name, the start article number and an -the article range. - -@item gnus-read-ephemeral-gmane-group-url -@findex gnus-read-ephemeral-gmane-group-url -This command is similar to @code{gnus-read-ephemeral-gmane-group}, but -the group name and the article number and range are constructed from a -given @acronym{URL}. Supported @acronym{URL} formats include: -@indicateurl{http://thread.gmane.org/gmane.foo.bar/12300/focus=12399}, -@indicateurl{http://thread.gmane.org/gmane.foo.bar/12345/}, -@indicateurl{http://article.gmane.org/gmane.foo.bar/12345/}, -@indicateurl{http://permalink.gmane.org/gmane.foo.bar/12345/}, and -@indicateurl{http://news.gmane.org/group/gmane.foo.bar/thread=12345}. - -@item gnus-read-ephemeral-emacs-bug-group -@findex gnus-read-ephemeral-emacs-bug-group -Read an Emacs bug report in an ephemeral group. Gnus will prompt for a -bug number. The default is the number at point. The @acronym{URL} is -specified in @code{gnus-bug-group-download-format-alist}. - -@item gnus-read-ephemeral-debian-bug-group -@findex gnus-read-ephemeral-debian-bug-group -Read a Debian bug report in an ephemeral group. Analog to -@code{gnus-read-ephemeral-emacs-bug-group}. -@end table - -Some of these command are also useful for article buttons, @xref{Article -Buttons}. - -Here is an example: -@lisp -(require 'gnus-art) -(add-to-list - 'gnus-button-alist - '("#\\([0-9]+\\)\\>" 1 - (string-match "\\" (or gnus-newsgroup-name "")) - gnus-read-ephemeral-emacs-bug-group 1)) -@end lisp - - -@node Group Parameters -@section Group Parameters -@cindex group parameters - -The group parameters store information local to a particular group. - -Use the @kbd{G p} or the @kbd{G c} command to edit group parameters of a -group. (@kbd{G p} presents you with a Lisp-based interface, @kbd{G c} -presents you with a Customize-like interface. The latter helps avoid -silly Lisp errors.) You might also be interested in reading about topic -parameters (@pxref{Topic Parameters}). -Additionally, you can set group parameters via the -@code{gnus-parameters} variable, see below. - -Here's an example group parameter list: - -@example -((to-address . "ding@@gnus.org") - (auto-expire . t)) -@end example - -We see that each element consists of a ``dotted pair''---the thing before -the dot is the key, while the thing after the dot is the value. All the -parameters have this form @emph{except} local variable specs, which are -not dotted pairs, but proper lists. - -Some parameters have correspondent customizable variables, each of which -is an alist of regexps and values. - -The following group parameters can be used: - -@table @code -@item to-address -@cindex to-address -Address used by when doing followups and new posts. - -@example -(to-address . "some@@where.com") -@end example - -This is primarily useful in mail groups that represent closed mailing -lists---mailing lists where it's expected that everybody that writes to -the mailing list is subscribed to it. Since using this parameter -ensures that the mail only goes to the mailing list itself, it means -that members won't receive two copies of your followups. - -Using @code{to-address} will actually work whether the group is foreign -or not. Let's say there's a group on the server that is called -@samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten -the articles from a mail-to-news gateway. Posting directly to this -group is therefore impossible---you have to send mail to the mailing -list address instead. - -See also @code{gnus-parameter-to-address-alist}. - -@item to-list -@cindex to-list -Address used when doing @kbd{a} in that group. - -@example -(to-list . "some@@where.com") -@end example - -It is totally ignored -when doing a followup---except that if it is present in a news group, -you'll get mail group semantics when doing @kbd{f}. - -If you do an @kbd{a} command in a mail group and you have neither a -@code{to-list} group parameter nor a @code{to-address} group parameter, -then a @code{to-list} group parameter will be added automatically upon -sending the message if @code{gnus-add-to-list} is set to @code{t}. -@vindex gnus-add-to-list - -@findex gnus-mailing-list-mode -@cindex mail list groups -If this variable is set, @code{gnus-mailing-list-mode} is turned on when -entering summary buffer. - -See also @code{gnus-parameter-to-list-alist}. - -@anchor{subscribed} -@item subscribed -@cindex subscribed -@cindex Mail-Followup-To -@findex gnus-find-subscribed-addresses -If this parameter is set to @code{t}, Gnus will consider the -to-address and to-list parameters for this group as addresses of -mailing lists you are subscribed to. Giving Gnus this information is -(only) a first step in getting it to generate correct Mail-Followup-To -headers for your posts to these lists. The second step is to put the -following in your @file{.gnus.el} - -@lisp -(setq message-subscribed-address-functions - '(gnus-find-subscribed-addresses)) -@end lisp - -@xref{Mailing Lists, ,Mailing Lists, message, The Message Manual}, for -a complete treatment of available MFT support. - -@item visible -@cindex visible -If the group parameter list has the element @code{(visible . t)}, -that group will always be visible in the Group buffer, regardless -of whether it has any unread articles. - -This parameter cannot be set via @code{gnus-parameters}. See -@code{gnus-permanently-visible-groups} as an alternative. - -@item broken-reply-to -@cindex broken-reply-to -Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To} -headers in this group are to be ignored, and for the header to be hidden -if @code{reply-to} is part of @code{gnus-boring-article-headers}. This -can be useful if you're reading a mailing list group where the listserv -has inserted @code{Reply-To} headers that point back to the listserv -itself. That is broken behavior. So there! - -@item to-group -@cindex to-group -Elements like @code{(to-group . "some.group.name")} means that all -posts in that group will be sent to @code{some.group.name}. - -@item newsgroup -@cindex newsgroup -If you have @code{(newsgroup . t)} in the group parameter list, Gnus -will treat all responses as if they were responses to news articles. -This can be useful if you have a mail group that's really a mirror of a -news group. - -@item gcc-self -@cindex gcc-self -If @code{(gcc-self . t)} is present in the group parameter list, newly -composed messages will be @code{Gcc}'d to the current group. If -@code{(gcc-self . none)} is present, no @code{Gcc:} header will be -generated, if @code{(gcc-self . "string")} is present, this string will -be inserted literally as a @code{gcc} header. This parameter takes -precedence over any default @code{Gcc} rules as described later -(@pxref{Archived Messages}), with the exception for messages to resend. - -@strong{Caveat}: Adding @code{(gcc-self . t)} to the parameter list of -@code{nntp} groups (or the like) isn't valid. An @code{nntp} server -doesn't accept articles. - -@item auto-expire -@cindex auto-expire -@cindex expiring mail -If the group parameter has an element that looks like @code{(auto-expire -. t)}, all articles read will be marked as expirable. For an -alternative approach, @pxref{Expiring Mail}. - -See also @code{gnus-auto-expirable-newsgroups}. - -@item total-expire -@cindex total-expire -@cindex expiring mail -If the group parameter has an element that looks like -@code{(total-expire . t)}, all read articles will be put through the -expiry process, even if they are not marked as expirable. Use with -caution. Unread, ticked and dormant articles are not eligible for -expiry. - -See also @code{gnus-total-expirable-newsgroups}. - -@item expiry-wait -@cindex expiry-wait -@vindex nnmail-expiry-wait-function -If the group parameter has an element that looks like -@code{(expiry-wait . 10)}, this value will override any -@code{nnmail-expiry-wait} and @code{nnmail-expiry-wait-function} -(@pxref{Expiring Mail}) when expiring expirable messages. The value -can either be a number of days (not necessarily an integer) or the -symbols @code{never} or @code{immediate}. - -@item expiry-target -@cindex expiry-target -Where expired messages end up. This parameter overrides -@code{nnmail-expiry-target}. - -@item score-file -@cindex score file group parameter -Elements that look like @code{(score-file . "file")} will make -@file{file} into the current score file for the group in question. All -interactive score entries will be put into this file. - -@item adapt-file -@cindex adapt file group parameter -Elements that look like @code{(adapt-file . "file")} will make -@file{file} into the current adaptive file for the group in question. -All adaptive score entries will be put into this file. - -@item admin-address -@cindex admin-address -When unsubscribing from a mailing list you should never send the -unsubscription notice to the mailing list itself. Instead, you'd send -messages to the administrative address. This parameter allows you to -put the admin address somewhere convenient. - -@item display -@cindex display -Elements that look like @code{(display . MODE)} say which articles to -display on entering the group. Valid values are: - -@table @code -@item all -Display all articles, both read and unread. - -@item an integer -Display the last @var{integer} articles in the group. This is the same as -entering the group with @kbd{C-u @var{integer}}. - -@item default -Display the default visible articles, which normally includes unread and -ticked articles. - -@item an array -Display articles that satisfy a predicate. - -Here are some examples: - -@table @code -@item [unread] -Display only unread articles. - -@item [not expire] -Display everything except expirable articles. - -@item [and (not reply) (not expire)] -Display everything except expirable and articles you've already -responded to. -@end table - -The available operators are @code{not}, @code{and} and @code{or}. -Predicates include @code{tick}, @code{unsend}, @code{undownload}, -@code{unread}, @code{dormant}, @code{expire}, @code{reply}, -@code{killed}, @code{bookmark}, @code{score}, @code{save}, -@code{cache}, @code{forward}, and @code{unseen}. - -@end table - -The @code{display} parameter works by limiting the summary buffer to -the subset specified. You can pop the limit by using the @kbd{/ w} -command (@pxref{Limiting}). - -@item comment -@cindex comment -Elements that look like @code{(comment . "This is a comment")} are -arbitrary comments on the group. You can display comments in the -group line (@pxref{Group Line Specification}). - -@item charset -@cindex charset -Elements that look like @code{(charset . iso-8859-1)} will make -@code{iso-8859-1} the default charset; that is, the charset that will be -used for all articles that do not specify a charset. - -See also @code{gnus-group-charset-alist}. - -@item ignored-charsets -@cindex ignored-charset -Elements that look like @code{(ignored-charsets x-unknown iso-8859-1)} -will make @code{iso-8859-1} and @code{x-unknown} ignored; that is, the -default charset will be used for decoding articles. - -See also @code{gnus-group-ignored-charsets-alist}. - -@item posting-style -@cindex posting-style -You can store additional posting style information for this group -here (@pxref{Posting Styles}). The format is that of an entry in the -@code{gnus-posting-styles} alist, except that there's no regexp matching -the group name (of course). Style elements in this group parameter will -take precedence over the ones found in @code{gnus-posting-styles}. - -For instance, if you want a funky name and signature in this group only, -instead of hacking @code{gnus-posting-styles}, you could put something -like this in the group parameters: - -@example -(posting-style - (name "Funky Name") - ("X-Message-SMTP-Method" "smtp smtp.example.org 587") - ("X-My-Header" "Funky Value") - (signature "Funky Signature")) -@end example - -If you're using topics to organize your group buffer -(@pxref{Group Topics}), note that posting styles can also be set in -the topics parameters. Posting styles in topic parameters apply to all -groups in this topic. More precisely, the posting-style settings for a -group result from the hierarchical merging of all posting-style -entries in the parameters of this group and all the topics it belongs -to. - - -@item post-method -@cindex post-method -If it is set, the value is used as the method for posting message -instead of @code{gnus-post-method}. - -@item mail-source -@cindex mail-source -If it is set, and the setting of @code{mail-sources} includes a -@code{group} mail source (@pxref{Mail Sources}), the value is a -mail source for this group. - -@item banner -@cindex banner -An item like @code{(banner . @var{regexp})} causes any part of an article -that matches the regular expression @var{regexp} to be stripped. Instead of -@var{regexp}, you can also use the symbol @code{signature} which strips the -last signature or any of the elements of the alist -@code{gnus-article-banner-alist}. - -@item sieve -@cindex sieve -This parameter contains a Sieve test that should match incoming mail -that should be placed in this group. From this group parameter, a -Sieve @samp{IF} control structure is generated, having the test as the -condition and @samp{fileinto "group.name";} as the body. - -For example, if the @samp{INBOX.list.sieve} group has the @code{(sieve -address "sender" "sieve-admin@@extundo.com")} group parameter, when -translating the group parameter into a Sieve script (@pxref{Sieve -Commands}) the following Sieve code is generated: - -@example -if address "sender" "sieve-admin@@extundo.com" @{ - fileinto "INBOX.list.sieve"; -@} -@end example - -To generate tests for multiple email-addresses use a group parameter -like @code{(sieve address "sender" ("name@@one.org" else@@two.org"))}. -When generating a sieve script (@pxref{Sieve Commands}) Sieve code -like the following is generated: - -@example -if address "sender" ["name@@one.org", "else@@two.org"] @{ - fileinto "INBOX.list.sieve"; -@} -@end example - -You can also use regexp expansions in the rules: - -@example -(sieve header :regex "list-id" "") -@end example - -See @pxref{Sieve Commands} for commands and variables that might be of -interest in relation to the sieve parameter. - -The Sieve language is described in RFC 3028. @xref{Top, Emacs Sieve, -Top, sieve, Emacs Sieve}. - -@item (agent parameters) -If the agent has been enabled, you can set any of its parameters to -control the behavior of the agent in individual groups. See Agent -Parameters in @ref{Category Syntax}. Most users will choose to set -agent parameters in either an agent category or group topic to -minimize the configuration effort. - -@item (@var{variable} @var{form}) -You can use the group parameters to set variables local to the group you -are entering. If you want to turn threading off in @samp{news.answers}, -you could put @code{(gnus-show-threads nil)} in the group parameters of -that group. @code{gnus-show-threads} will be made into a local variable -in the summary buffer you enter, and the form @code{nil} will be -@code{eval}ed there. - -Note that this feature sets the variable locally to the summary buffer -if and only if @var{variable} has been bound as a variable. Otherwise, -only evaluating the form will take place. So, you may want to bind the -variable in advance using @code{defvar} or other if the result of the -form needs to be set to it. - -But some variables are evaluated in the article buffer, or in the -message buffer (of a reply or followup or otherwise newly created -message). As a workaround, it might help to add the variable in -question to @code{gnus-newsgroup-variables}. @xref{Various Summary -Stuff}. So if you want to set @code{message-from-style} via the group -parameters, then you may need the following statement elsewhere in your -@file{~/.gnus.el} file: - -@lisp -(add-to-list 'gnus-newsgroup-variables 'message-from-style) -@end lisp - -@vindex gnus-list-identifiers -A use for this feature is to remove a mailing list identifier tag in -the subject fields of articles. E.g., if the news group - -@example -nntp+news.gnus.org:gmane.text.docbook.apps -@end example - -has the tag @samp{DOC-BOOK-APPS:} in the subject of all articles, this -tag can be removed from the article subjects in the summary buffer for -the group by putting @code{(gnus-list-identifiers "DOCBOOK-APPS:")} -into the group parameters for the group. - -This can also be used as a group-specific hook function. If you want to -hear a beep when you enter a group, you could put something like -@code{(dummy-variable (ding))} in the parameters of that group. If -@code{dummy-variable} has been bound (see above), it will be set to the -(meaningless) result of the @code{(ding)} form. - -Alternatively, since the VARIABLE becomes local to the group, this -pattern can be used to temporarily change a hook. For example, if the -following is added to a group parameter - -@lisp -(gnus-summary-prepared-hook - (lambda nil (local-set-key "d" (local-key-binding "n")))) -@end lisp - -when the group is entered, the 'd' key will not mark the article as -expired. - -@end table - -@vindex gnus-parameters -Group parameters can be set via the @code{gnus-parameters} variable too. -But some variables, such as @code{visible}, have no effect (For this -case see @code{gnus-permanently-visible-groups} as an alternative.). -For example: - -@lisp -(setq gnus-parameters - '(("mail\\..*" - (gnus-show-threads nil) - (gnus-use-scoring nil) - (gnus-summary-line-format - "%U%R%z%I%(%[%d:%ub%-23,23f%]%) %s\n") - (gcc-self . t) - (display . all)) - - ("^nnimap:\\(foo.bar\\)$" - (to-group . "\\1")) - - ("mail\\.me" - (gnus-use-scoring t)) - - ("list\\..*" - (total-expire . t) - (broken-reply-to . t)))) -@end lisp - -All clauses that matches the group name will be used, but the last -setting ``wins''. So if you have two clauses that both match the -group name, and both set, say @code{display}, the last setting will -override the first. - -Parameters that are strings will be subjected to regexp substitution, -as the @code{to-group} example shows. - -@vindex gnus-parameters-case-fold-search -By default, whether comparing the group name and one of those regexps -specified in @code{gnus-parameters} is done in a case-sensitive manner -or a case-insensitive manner depends on the value of -@code{case-fold-search} at the time when the comparison is done. The -value of @code{case-fold-search} is typically @code{t}; it means, for -example, the element @code{("INBOX\\.FOO" (total-expire . t))} might be -applied to both the @samp{INBOX.FOO} group and the @samp{INBOX.foo} -group. If you want to make those regexps always case-sensitive, set the -value of the @code{gnus-parameters-case-fold-search} variable to -@code{nil}. Otherwise, set it to @code{t} if you want to compare them -always in a case-insensitive manner. - -You can define different sorting to different groups via -@code{gnus-parameters}. Here is an example to sort an @acronym{NNTP} -group by reverse date to see the latest news at the top and an -@acronym{RSS} group by subject. In this example, the first group is the -Debian daily news group @code{gmane.linux.debian.user.news} from -news.gmane.org. The @acronym{RSS} group corresponds to the Debian -weekly news RSS feed -@url{http://packages.debian.org/unstable/newpkg_main.en.rdf}, -@xref{RSS}. - -@lisp -(setq - gnus-parameters - '(("nntp.*gmane\\.debian\\.user\\.news" - (gnus-show-threads nil) - (gnus-article-sort-functions '((not gnus-article-sort-by-date))) - (gnus-use-adaptive-scoring nil) - (gnus-use-scoring nil)) - ("nnrss.*debian" - (gnus-show-threads nil) - (gnus-article-sort-functions 'gnus-article-sort-by-subject) - (gnus-use-adaptive-scoring nil) - (gnus-use-scoring t) - (gnus-score-find-score-files-function 'gnus-score-find-single) - (gnus-summary-line-format "%U%R%z%d %I%(%[ %s %]%)\n")))) -@end lisp - - -@node Listing Groups -@section Listing Groups -@cindex group listing - -These commands all list various slices of the groups available. - -@table @kbd - -@item l -@itemx A s -@kindex A s (Group) -@kindex l (Group) -@findex gnus-group-list-groups -List all groups that have unread articles -(@code{gnus-group-list-groups}). If the numeric prefix is used, this -command will list only groups of level ARG and lower. By default, it -only lists groups of level five (i.e., -@code{gnus-group-default-list-level}) or lower (i.e., just subscribed -groups). - -@item L -@itemx A u -@kindex A u (Group) -@kindex L (Group) -@findex gnus-group-list-all-groups -List all groups, whether they have unread articles or not -(@code{gnus-group-list-all-groups}). If the numeric prefix is used, -this command will list only groups of level ARG and lower. By default, -it lists groups of level seven or lower (i.e., just subscribed and -unsubscribed groups). - -@item A l -@kindex A l (Group) -@findex gnus-group-list-level -List all unread groups on a specific level -(@code{gnus-group-list-level}). If given a prefix, also list the groups -with no unread articles. - -@item A k -@kindex A k (Group) -@findex gnus-group-list-killed -List all killed groups (@code{gnus-group-list-killed}). If given a -prefix argument, really list all groups that are available, but aren't -currently (un)subscribed. This could entail reading the active file -from the server. - -@item A z -@kindex A z (Group) -@findex gnus-group-list-zombies -List all zombie groups (@code{gnus-group-list-zombies}). - -@item A m -@kindex A m (Group) -@findex gnus-group-list-matching -List all unread, subscribed groups with names that match a regexp -(@code{gnus-group-list-matching}). - -@item A M -@kindex A M (Group) -@findex gnus-group-list-all-matching -List groups that match a regexp (@code{gnus-group-list-all-matching}). - -@item A A -@kindex A A (Group) -@findex gnus-group-list-active -List absolutely all groups in the active file(s) of the -server(s) you are connected to (@code{gnus-group-list-active}). This -might very well take quite a while. It might actually be a better idea -to do a @kbd{A M} to list all matching, and just give @samp{.} as the -thing to match on. Also note that this command may list groups that -don't exist (yet)---these will be listed as if they were killed groups. -Take the output with some grains of salt. - -@item A a -@kindex A a (Group) -@findex gnus-group-apropos -List all groups that have names that match a regexp -(@code{gnus-group-apropos}). - -@item A d -@kindex A d (Group) -@findex gnus-group-description-apropos -List all groups that have names or descriptions that match a regexp -(@code{gnus-group-description-apropos}). - -@item A c -@kindex A c (Group) -@findex gnus-group-list-cached -List all groups with cached articles (@code{gnus-group-list-cached}). - -@item A ? -@kindex A ? (Group) -@findex gnus-group-list-dormant -List all groups with dormant articles (@code{gnus-group-list-dormant}). - -@item A ! -@kindex A ! (Group) -@findex gnus-group-list-ticked -List all groups with ticked articles (@code{gnus-group-list-ticked}). - -@item A / -@kindex A / (Group) -@findex gnus-group-list-limit -Further limit groups within the current selection -(@code{gnus-group-list-limit}). If you've first limited to groups -with dormant articles with @kbd{A ?}, you can then further limit with -@kbd{A / c}, which will then limit to groups with cached articles, -giving you the groups that have both dormant articles and cached -articles. - -@item A f -@kindex A f (Group) -@findex gnus-group-list-flush -Flush groups from the current selection (@code{gnus-group-list-flush}). - -@item A p -@kindex A p (Group) -@findex gnus-group-list-plus -List groups plus the current selection (@code{gnus-group-list-plus}). - -@end table - -@vindex gnus-permanently-visible-groups -@cindex visible group parameter -Groups that match the @code{gnus-permanently-visible-groups} regexp will -always be shown, whether they have unread articles or not. You can also -add the @code{visible} element to the group parameters in question to -get the same effect. - -@vindex gnus-list-groups-with-ticked-articles -Groups that have just ticked articles in it are normally listed in the -group buffer. If @code{gnus-list-groups-with-ticked-articles} is -@code{nil}, these groups will be treated just like totally empty -groups. It is @code{t} by default. - - -@node Sorting Groups -@section Sorting Groups -@cindex sorting groups - -@kindex C-c C-s (Group) -@findex gnus-group-sort-groups -@vindex gnus-group-sort-function -The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the -group buffer according to the function(s) given by the -@code{gnus-group-sort-function} variable. Available sorting functions -include: - -@table @code - -@item gnus-group-sort-by-alphabet -@findex gnus-group-sort-by-alphabet -Sort the group names alphabetically. This is the default. - -@item gnus-group-sort-by-real-name -@findex gnus-group-sort-by-real-name -Sort the group alphabetically on the real (unprefixed) group names. - -@item gnus-group-sort-by-level -@findex gnus-group-sort-by-level -Sort by group level. - -@item gnus-group-sort-by-score -@findex gnus-group-sort-by-score -Sort by group score. @xref{Group Score}. - -@item gnus-group-sort-by-rank -@findex gnus-group-sort-by-rank -Sort by group score and then the group level. The level and the score -are, when taken together, the group's @dfn{rank}. @xref{Group Score}. - -@item gnus-group-sort-by-unread -@findex gnus-group-sort-by-unread -Sort by number of unread articles. - -@item gnus-group-sort-by-method -@findex gnus-group-sort-by-method -Sort alphabetically on the select method. - -@item gnus-group-sort-by-server -@findex gnus-group-sort-by-server -Sort alphabetically on the Gnus server name. - - -@end table - -@code{gnus-group-sort-function} can also be a list of sorting -functions. In that case, the most significant sort key function must be -the last one. - - -There are also a number of commands for sorting directly according to -some sorting criteria: - -@table @kbd -@item G S a -@kindex G S a (Group) -@findex gnus-group-sort-groups-by-alphabet -Sort the group buffer alphabetically by group name -(@code{gnus-group-sort-groups-by-alphabet}). - -@item G S u -@kindex G S u (Group) -@findex gnus-group-sort-groups-by-unread -Sort the group buffer by the number of unread articles -(@code{gnus-group-sort-groups-by-unread}). - -@item G S l -@kindex G S l (Group) -@findex gnus-group-sort-groups-by-level -Sort the group buffer by group level -(@code{gnus-group-sort-groups-by-level}). - -@item G S v -@kindex G S v (Group) -@findex gnus-group-sort-groups-by-score -Sort the group buffer by group score -(@code{gnus-group-sort-groups-by-score}). @xref{Group Score}. - -@item G S r -@kindex G S r (Group) -@findex gnus-group-sort-groups-by-rank -Sort the group buffer by group rank -(@code{gnus-group-sort-groups-by-rank}). @xref{Group Score}. - -@item G S m -@kindex G S m (Group) -@findex gnus-group-sort-groups-by-method -Sort the group buffer alphabetically by back end name@* -(@code{gnus-group-sort-groups-by-method}). - -@item G S n -@kindex G S n (Group) -@findex gnus-group-sort-groups-by-real-name -Sort the group buffer alphabetically by real (unprefixed) group name -(@code{gnus-group-sort-groups-by-real-name}). - -@end table - -All the commands below obey the process/prefix convention -(@pxref{Process/Prefix}). - -When given a symbolic prefix (@pxref{Symbolic Prefixes}), all these -commands will sort in reverse order. - -You can also sort a subset of the groups: - -@table @kbd -@item G P a -@kindex G P a (Group) -@findex gnus-group-sort-selected-groups-by-alphabet -Sort the groups alphabetically by group name -(@code{gnus-group-sort-selected-groups-by-alphabet}). - -@item G P u -@kindex G P u (Group) -@findex gnus-group-sort-selected-groups-by-unread -Sort the groups by the number of unread articles -(@code{gnus-group-sort-selected-groups-by-unread}). - -@item G P l -@kindex G P l (Group) -@findex gnus-group-sort-selected-groups-by-level -Sort the groups by group level -(@code{gnus-group-sort-selected-groups-by-level}). - -@item G P v -@kindex G P v (Group) -@findex gnus-group-sort-selected-groups-by-score -Sort the groups by group score -(@code{gnus-group-sort-selected-groups-by-score}). @xref{Group Score}. - -@item G P r -@kindex G P r (Group) -@findex gnus-group-sort-selected-groups-by-rank -Sort the groups by group rank -(@code{gnus-group-sort-selected-groups-by-rank}). @xref{Group Score}. - -@item G P m -@kindex G P m (Group) -@findex gnus-group-sort-selected-groups-by-method -Sort the groups alphabetically by back end name@* -(@code{gnus-group-sort-selected-groups-by-method}). - -@item G P n -@kindex G P n (Group) -@findex gnus-group-sort-selected-groups-by-real-name -Sort the groups alphabetically by real (unprefixed) group name -(@code{gnus-group-sort-selected-groups-by-real-name}). - -@item G P s -@kindex G P s (Group) -@findex gnus-group-sort-selected-groups -Sort the groups according to @code{gnus-group-sort-function}. - -@end table - -And finally, note that you can use @kbd{C-k} and @kbd{C-y} to manually -move groups around. - - -@node Group Maintenance -@section Group Maintenance -@cindex bogus groups - -@table @kbd -@item b -@kindex b (Group) -@findex gnus-group-check-bogus-groups -Find bogus groups and delete them -(@code{gnus-group-check-bogus-groups}). - -@item F -@kindex F (Group) -@findex gnus-group-find-new-groups -Find new groups and process them (@code{gnus-group-find-new-groups}). -With 1 @kbd{C-u}, use the @code{ask-server} method to query the server -for new groups. With 2 @kbd{C-u}'s, use most complete method possible -to query the server for new groups, and subscribe the new groups as -zombies. - -@item C-c C-x -@kindex C-c C-x (Group) -@findex gnus-group-expire-articles -@cindex expiring mail -Run all expirable articles in the current group through the expiry -process (if any) (@code{gnus-group-expire-articles}). That is, delete -all expirable articles in the group that have been around for a while. -(@pxref{Expiring Mail}). - -@item C-c C-M-x -@kindex C-c C-M-x (Group) -@findex gnus-group-expire-all-groups -@cindex expiring mail -Run all expirable articles in all groups through the expiry process -(@code{gnus-group-expire-all-groups}). - -@end table - - -@node Browse Foreign Server -@section Browse Foreign Server -@cindex foreign servers -@cindex browsing servers - -@table @kbd -@item B -@kindex B (Group) -@findex gnus-group-browse-foreign-server -You will be queried for a select method and a server name. Gnus will -then attempt to contact this server and let you browse the groups there -(@code{gnus-group-browse-foreign-server}). -@end table - -@findex gnus-browse-mode -A new buffer with a list of available groups will appear. This buffer -will use the @code{gnus-browse-mode}. This buffer looks a bit (well, -a lot) like a normal group buffer. - -Here's a list of keystrokes available in the browse mode: - -@table @kbd -@item n -@kindex n (Browse) -@findex gnus-group-next-group -Go to the next group (@code{gnus-group-next-group}). - -@item p -@kindex p (Browse) -@findex gnus-group-prev-group -Go to the previous group (@code{gnus-group-prev-group}). - -@item SPACE -@kindex SPACE (Browse) -@findex gnus-browse-read-group -Enter the current group and display the first article -(@code{gnus-browse-read-group}). - -@item RET -@kindex RET (Browse) -@findex gnus-browse-select-group -Enter the current group (@code{gnus-browse-select-group}). - -@item u -@kindex u (Browse) -@findex gnus-browse-unsubscribe-current-group -@vindex gnus-browse-subscribe-newsgroup-method -Unsubscribe to the current group, or, as will be the case here, -subscribe to it (@code{gnus-browse-unsubscribe-current-group}). You -can affect the way the new group is entered into the Group buffer -using the variable @code{gnus-browse-subscribe-newsgroup-method}. See -@pxref{Subscription Methods} for available options. - -@item l -@itemx q -@kindex q (Browse) -@kindex l (Browse) -@findex gnus-browse-exit -Exit browse mode (@code{gnus-browse-exit}). - -@item d -@kindex d (Browse) -@findex gnus-browse-describe-group -Describe the current group (@code{gnus-browse-describe-group}). - -@item ? -@kindex ? (Browse) -@findex gnus-browse-describe-briefly -Describe browse mode briefly (well, there's not much to describe, is -there) (@code{gnus-browse-describe-briefly}). - -@item DEL -@kindex DEL (Browse) -@findex gnus-browse-delete-group -This function will delete the current group -(@code{gnus-browse-delete-group}). If given a prefix, this function -will actually delete all the articles in the group, and forcibly -remove the group itself from the face of the Earth. Use a prefix only -if you are absolutely sure of what you are doing. -@end table - - -@node Exiting Gnus -@section Exiting Gnus -@cindex exiting Gnus - -Yes, Gnus is ex(c)iting. - -@table @kbd -@item z -@kindex z (Group) -@findex gnus-group-suspend -Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus, -but it kills all buffers except the Group buffer. I'm not sure why this -is a gain, but then who am I to judge? - -@item q -@kindex q (Group) -@findex gnus-group-exit -@c @icon{gnus-group-exit} -Quit Gnus (@code{gnus-group-exit}). - -@item Q -@kindex Q (Group) -@findex gnus-group-quit -Quit Gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}). -The dribble file will be saved, though (@pxref{Auto Save}). -@end table - -@vindex gnus-exit-gnus-hook -@vindex gnus-suspend-gnus-hook -@vindex gnus-after-exiting-gnus-hook -@code{gnus-suspend-gnus-hook} is called when you suspend Gnus and -@code{gnus-exit-gnus-hook} is called when you quit Gnus, while -@code{gnus-after-exiting-gnus-hook} is called as the final item when -exiting Gnus. - -Note: - -@quotation -Miss Lisa Cannifax, while sitting in English class, felt her feet go -numbly heavy and herself fall into a hazy trance as the boy sitting -behind her drew repeated lines with his pencil across the back of her -plastic chair. -@end quotation - - -@node Group Topics -@section Group Topics -@cindex topics - -If you read lots and lots of groups, it might be convenient to group -them hierarchically according to topics. You put your Emacs groups over -here, your sex groups over there, and the rest (what, two groups or so?) -you put in some misc section that you never bother with anyway. You can -even group the Emacs sex groups as a sub-topic to either the Emacs -groups or the sex groups---or both! Go wild! - -@iftex -@iflatex -\gnusfigure{Group Topics}{400}{ -\put(75,50){\epsfig{figure=ps/group-topic,height=9cm}} -} -@end iflatex -@end iftex - -Here's an example: - -@example -Gnus - Emacs -- I wuw it! - 3: comp.emacs - 2: alt.religion.emacs - Naughty Emacs - 452: alt.sex.emacs - 0: comp.talk.emacs.recovery - Misc - 8: comp.binaries.fractals - 13: comp.sources.unix -@end example - -@findex gnus-topic-mode -@kindex t (Group) -To get this @emph{fab} functionality you simply turn on (ooh!) the -@code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This -is a toggling command.) - -Go ahead, just try it. I'll still be here when you get back. La de -dum@dots{} Nice tune, that@dots{} la la la@dots{} What, you're back? -Yes, and now press @kbd{l}. There. All your groups are now listed -under @samp{misc}. Doesn't that make you feel all warm and fuzzy? -Hot and bothered? - -If you want this permanently enabled, you should add that minor mode to -the hook for the group mode. Put the following line in your -@file{~/.gnus.el} file: - -@lisp -(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) -@end lisp - -@menu -* Topic Commands:: Interactive E-Z commands. -* Topic Variables:: How to customize the topics the Lisp Way. -* Topic Sorting:: Sorting each topic individually. -* Topic Topology:: A map of the world. -* Topic Parameters:: Parameters that apply to all groups in a topic. -@end menu - - -@node Topic Commands -@subsection Topic Commands -@cindex topic commands - -When the topic minor mode is turned on, a new @kbd{T} submap will be -available. In addition, a few of the standard keys change their -definitions slightly. - -In general, the following kinds of operations are possible on topics. -First of all, you want to create topics. Secondly, you want to put -groups in topics and to move them around until you have an order you -like. The third kind of operation is to show/hide parts of the whole -shebang. You might want to hide a topic including its subtopics and -groups, to get a better overview of the other groups. - -Here is a list of the basic keys that you might need to set up topics -the way you like. - -@table @kbd - -@item T n -@kindex T n (Topic) -@findex gnus-topic-create-topic -Prompt for a new topic name and create it -(@code{gnus-topic-create-topic}). - -@item T TAB -@itemx TAB -@kindex T TAB (Topic) -@kindex TAB (Topic) -@findex gnus-topic-indent -``Indent'' the current topic so that it becomes a sub-topic of the -previous topic (@code{gnus-topic-indent}). If given a prefix, -``un-indent'' the topic instead. - -@item M-TAB -@kindex M-TAB (Topic) -@findex gnus-topic-unindent -``Un-indent'' the current topic so that it becomes a sub-topic of the -parent of its current parent (@code{gnus-topic-unindent}). - -@end table - -The following two keys can be used to move groups and topics around. -They work like the well-known cut and paste. @kbd{C-k} is like cut and -@kbd{C-y} is like paste. Of course, this being Emacs, we use the terms -kill and yank rather than cut and paste. - -@table @kbd - -@item C-k -@kindex C-k (Topic) -@findex gnus-topic-kill-group -Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the -topic will be removed along with the topic. - -@item C-y -@kindex C-y (Topic) -@findex gnus-topic-yank-group -Yank the previously killed group or topic -(@code{gnus-topic-yank-group}). Note that all topics will be yanked -before all groups. - -So, to move a topic to the beginning of the list of topics, just hit -@kbd{C-k} on it. This is like the ``cut'' part of cut and paste. Then, -move the cursor to the beginning of the buffer (just below the ``Gnus'' -topic) and hit @kbd{C-y}. This is like the ``paste'' part of cut and -paste. Like I said---E-Z. - -You can use @kbd{C-k} and @kbd{C-y} on groups as well as on topics. So -you can move topics around as well as groups. - -@end table - -After setting up the topics the way you like them, you might wish to -hide a topic, or to show it again. That's why we have the following -key. - -@table @kbd - -@item RET -@kindex RET (Topic) -@findex gnus-topic-select-group -@itemx SPACE -Either select a group or fold a topic (@code{gnus-topic-select-group}). -When you perform this command on a group, you'll enter the group, as -usual. When done on a topic line, the topic will be folded (if it was -visible) or unfolded (if it was folded already). So it's basically a -toggling command on topics. In addition, if you give a numerical -prefix, group on that level (and lower) will be displayed. - -@end table - -Now for a list of other commands, in no particular order. - -@table @kbd - -@item T m -@kindex T m (Topic) -@findex gnus-topic-move-group -Move the current group to some other topic -(@code{gnus-topic-move-group}). This command uses the process/prefix -convention (@pxref{Process/Prefix}). - -@item T j -@kindex T j (Topic) -@findex gnus-topic-jump-to-topic -Go to a topic (@code{gnus-topic-jump-to-topic}). - -@item T c -@kindex T c (Topic) -@findex gnus-topic-copy-group -Copy the current group to some other topic -(@code{gnus-topic-copy-group}). This command uses the process/prefix -convention (@pxref{Process/Prefix}). - -@item T h -@kindex T h (Topic) -@findex gnus-topic-hide-topic -Hide the current topic (@code{gnus-topic-hide-topic}). If given -a prefix, hide the topic permanently. - -@item T s -@kindex T s (Topic) -@findex gnus-topic-show-topic -Show the current topic (@code{gnus-topic-show-topic}). If given -a prefix, show the topic permanently. - -@item T D -@kindex T D (Topic) -@findex gnus-topic-remove-group -Remove a group from the current topic (@code{gnus-topic-remove-group}). -This command is mainly useful if you have the same group in several -topics and wish to remove it from one of the topics. You may also -remove a group from all topics, but in that case, Gnus will add it to -the root topic the next time you start Gnus. In fact, all new groups -(which, naturally, don't belong to any topic) will show up in the root -topic. - -This command uses the process/prefix convention -(@pxref{Process/Prefix}). - -@item T M -@kindex T M (Topic) -@findex gnus-topic-move-matching -Move all groups that match some regular expression to a topic -(@code{gnus-topic-move-matching}). - -@item T C -@kindex T C (Topic) -@findex gnus-topic-copy-matching -Copy all groups that match some regular expression to a topic -(@code{gnus-topic-copy-matching}). - -@item T H -@kindex T H (Topic) -@findex gnus-topic-toggle-display-empty-topics -Toggle hiding empty topics -(@code{gnus-topic-toggle-display-empty-topics}). - -@item T # -@kindex T # (Topic) -@findex gnus-topic-mark-topic -Mark all groups in the current topic with the process mark -(@code{gnus-topic-mark-topic}). This command works recursively on -sub-topics unless given a prefix. - -@item T M-# -@kindex T M-# (Topic) -@findex gnus-topic-unmark-topic -Remove the process mark from all groups in the current topic -(@code{gnus-topic-unmark-topic}). This command works recursively on -sub-topics unless given a prefix. - -@item C-c C-x -@kindex C-c C-x (Topic) -@findex gnus-topic-expire-articles -@cindex expiring mail -Run all expirable articles in the current group or topic through the -expiry process (if any) -(@code{gnus-topic-expire-articles}). (@pxref{Expiring Mail}). - -@item T r -@kindex T r (Topic) -@findex gnus-topic-rename -Rename a topic (@code{gnus-topic-rename}). - -@item T DEL -@kindex T DEL (Topic) -@findex gnus-topic-delete -Delete an empty topic (@code{gnus-topic-delete}). - -@item A T -@kindex A T (Topic) -@findex gnus-topic-list-active -List all groups that Gnus knows about in a topics-ified way -(@code{gnus-topic-list-active}). - -@item T M-n -@kindex T M-n (Topic) -@findex gnus-topic-goto-next-topic -Go to the next topic (@code{gnus-topic-goto-next-topic}). - -@item T M-p -@kindex T M-p (Topic) -@findex gnus-topic-goto-previous-topic -Go to the previous topic (@code{gnus-topic-goto-previous-topic}). - -@item G p -@kindex G p (Topic) -@findex gnus-topic-edit-parameters -@cindex group parameters -@cindex topic parameters -@cindex parameters -Edit the topic parameters (@code{gnus-topic-edit-parameters}). -@xref{Topic Parameters}. - -@end table - - -@node Topic Variables -@subsection Topic Variables -@cindex topic variables - -The previous section told you how to tell Gnus which topics to display. -This section explains how to tell Gnus what to display about each topic. - -@vindex gnus-topic-line-format -The topic lines themselves are created according to the -@code{gnus-topic-line-format} variable (@pxref{Formatting Variables}). -Valid elements are: - -@table @samp -@item i -Indentation. -@item n -Topic name. -@item v -Visibility. -@item l -Level. -@item g -Number of groups in the topic. -@item a -Number of unread articles in the topic. -@item A -Number of unread articles in the topic and all its subtopics. -@end table - -@vindex gnus-topic-indent-level -Each sub-topic (and the groups in the sub-topics) will be indented with -@code{gnus-topic-indent-level} times the topic level number of spaces. -The default is 2. - -@vindex gnus-topic-mode-hook -@code{gnus-topic-mode-hook} is called in topic minor mode buffers. - -@vindex gnus-topic-display-empty-topics -The @code{gnus-topic-display-empty-topics} says whether to display even -topics that have no unread articles in them. The default is @code{t}. - - -@node Topic Sorting -@subsection Topic Sorting -@cindex topic sorting - -You can sort the groups in each topic individually with the following -commands: - - -@table @kbd -@item T S a -@kindex T S a (Topic) -@findex gnus-topic-sort-groups-by-alphabet -Sort the current topic alphabetically by group name -(@code{gnus-topic-sort-groups-by-alphabet}). - -@item T S u -@kindex T S u (Topic) -@findex gnus-topic-sort-groups-by-unread -Sort the current topic by the number of unread articles -(@code{gnus-topic-sort-groups-by-unread}). - -@item T S l -@kindex T S l (Topic) -@findex gnus-topic-sort-groups-by-level -Sort the current topic by group level -(@code{gnus-topic-sort-groups-by-level}). - -@item T S v -@kindex T S v (Topic) -@findex gnus-topic-sort-groups-by-score -Sort the current topic by group score -(@code{gnus-topic-sort-groups-by-score}). @xref{Group Score}. - -@item T S r -@kindex T S r (Topic) -@findex gnus-topic-sort-groups-by-rank -Sort the current topic by group rank -(@code{gnus-topic-sort-groups-by-rank}). @xref{Group Score}. - -@item T S m -@kindex T S m (Topic) -@findex gnus-topic-sort-groups-by-method -Sort the current topic alphabetically by back end name -(@code{gnus-topic-sort-groups-by-method}). - -@item T S e -@kindex T S e (Topic) -@findex gnus-topic-sort-groups-by-server -Sort the current topic alphabetically by server name -(@code{gnus-topic-sort-groups-by-server}). - -@item T S s -@kindex T S s (Topic) -@findex gnus-topic-sort-groups -Sort the current topic according to the function(s) given by the -@code{gnus-group-sort-function} variable -(@code{gnus-topic-sort-groups}). - -@end table - -When given a prefix argument, all these commands will sort in reverse -order. @xref{Sorting Groups}, for more information about group -sorting. - - -@node Topic Topology -@subsection Topic Topology -@cindex topic topology -@cindex topology - -So, let's have a look at an example group buffer: - -@example -@group -Gnus - Emacs -- I wuw it! - 3: comp.emacs - 2: alt.religion.emacs - Naughty Emacs - 452: alt.sex.emacs - 0: comp.talk.emacs.recovery - Misc - 8: comp.binaries.fractals - 13: comp.sources.unix -@end group -@end example - -So, here we have one top-level topic (@samp{Gnus}), two topics under -that, and one sub-topic under one of the sub-topics. (There is always -just one (1) top-level topic). This topology can be expressed as -follows: - -@lisp -(("Gnus" visible) - (("Emacs -- I wuw it!" visible) - (("Naughty Emacs" visible))) - (("Misc" visible))) -@end lisp - -@vindex gnus-topic-topology -This is in fact how the variable @code{gnus-topic-topology} would look -for the display above. That variable is saved in the @file{.newsrc.eld} -file, and shouldn't be messed with manually---unless you really want -to. Since this variable is read from the @file{.newsrc.eld} file, -setting it in any other startup files will have no effect. - -This topology shows what topics are sub-topics of what topics (right), -and which topics are visible. Two settings are currently -allowed---@code{visible} and @code{invisible}. - - -@node Topic Parameters -@subsection Topic Parameters -@cindex topic parameters - -All groups in a topic will inherit group parameters from the parent -(and ancestor) topic parameters. All valid group parameters are valid -topic parameters (@pxref{Group Parameters}). When the agent is -enabled, all agent parameters (See Agent Parameters in @ref{Category -Syntax}) are also valid topic parameters. - -In addition, the following parameters are only valid as topic -parameters: - -@table @code -@item subscribe -When subscribing new groups by topic (@pxref{Subscription Methods}), the -@code{subscribe} topic parameter says what groups go in what topic. Its -value should be a regexp to match the groups that should go in that -topic. - -@item subscribe-level -When subscribing new groups by topic (see the @code{subscribe} parameter), -the group will be subscribed with the level specified in the -@code{subscribe-level} instead of @code{gnus-level-default-subscribed}. - -@end table - -Group parameters (of course) override topic parameters, and topic -parameters in sub-topics override topic parameters in super-topics. You -know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a -verb, although you may feel free to disagree with me here.) - -@example -@group -Gnus - Emacs - 3: comp.emacs - 2: alt.religion.emacs - 452: alt.sex.emacs - Relief - 452: alt.sex.emacs - 0: comp.talk.emacs.recovery - Misc - 8: comp.binaries.fractals - 13: comp.sources.unix - 452: alt.sex.emacs -@end group -@end example - -The @samp{Emacs} topic has the topic parameter @code{(score-file -. "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter -@code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the -topic parameter @code{(score-file . "emacs.SCORE")}. In addition, -@* @samp{alt.religion.emacs} has the group parameter @code{(score-file -. "religion.SCORE")}. - -Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you -will get the @file{relief.SCORE} home score file. If you enter the same -group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home -score file. If you enter the group @samp{alt.religion.emacs}, you'll -get the @file{religion.SCORE} home score file. - -This seems rather simple and self-evident, doesn't it? Well, yes. But -there are some problems, especially with the @code{total-expiry} -parameter. Say you have a mail group in two topics; one with -@code{total-expiry} and one without. What happens when you do @kbd{M-x -gnus-expire-all-expirable-groups}? Gnus has no way of telling which one -of these topics you mean to expire articles from, so anything may -happen. In fact, I hereby declare that it is @dfn{undefined} what -happens. You just have to be careful if you do stuff like that. - - -@node Non-ASCII Group Names -@section Accessing groups of non-English names -@cindex non-ascii group names - -There are some news servers that provide groups of which the names are -expressed with their native languages in the world. For instance, in a -certain news server there are some newsgroups of which the names are -spelled in Chinese, where people are talking in Chinese. You can, of -course, subscribe to such news groups using Gnus. Currently Gnus -supports non-@acronym{ASCII} group names not only with the @code{nntp} -back end but also with the @code{nnml} back end and the @code{nnrss} -back end. - -Every such group name is encoded by a certain charset in the server -side (in an @acronym{NNTP} server its administrator determines the -charset, but for groups in the other back ends it is determined by you). -Gnus has to display the decoded ones for you in the group buffer and the -article buffer, and needs to use the encoded ones when communicating -with servers. However, Gnus doesn't know what charset is used for each -non-@acronym{ASCII} group name. The following two variables are just -the ones for telling Gnus what charset should be used for each group: - -@table @code -@item gnus-group-name-charset-method-alist -@vindex gnus-group-name-charset-method-alist -An alist of select methods and charsets. The default value is -@code{nil}. The names of groups in the server specified by that select -method are all supposed to use the corresponding charset. For example: - -@lisp -(setq gnus-group-name-charset-method-alist - '(((nntp "news.com.cn") . cn-gb-2312))) -@end lisp - -Charsets specified for groups with this variable are preferred to the -ones specified for the same groups with the -@code{gnus-group-name-charset-group-alist} variable (see below). - -A select method can be very long, like: - -@lisp -(nntp "gmane" - (nntp-address "news.gmane.org") - (nntp-end-of-line "\n") - (nntp-open-connection-function - nntp-open-via-rlogin-and-telnet) - (nntp-via-rlogin-command "ssh") - (nntp-via-rlogin-command-switches - ("-C" "-t" "-e" "none")) - (nntp-via-address @dots{})) -@end lisp - -In that case, you can truncate it into @code{(nntp "gmane")} in this -variable. That is, it is enough to contain only the back end name and -the server name. - -@item gnus-group-name-charset-group-alist -@cindex UTF-8 group names -@vindex gnus-group-name-charset-group-alist -An alist of regexp of group name and the charset for group names. -@code{((".*" . utf-8))} is the default value if UTF-8 is supported, -otherwise the default is @code{nil}. For example: - -@lisp -(setq gnus-group-name-charset-group-alist - '(("\\.com\\.cn:" . cn-gb-2312) - (".*" . utf-8))) -@end lisp - -Note that this variable is ignored if the match is made with -@code{gnus-group-name-charset-method-alist}. -@end table - -Those two variables are used also to determine the charset for encoding -and decoding non-@acronym{ASCII} group names that are in the back ends -other than @code{nntp}. It means that it is you who determine it. If -you do nothing, the charset used for group names in those back ends will -all be @code{utf-8} because of the last element of -@code{gnus-group-name-charset-group-alist}. - -There is one more important variable for non-@acronym{ASCII} group -names: - -@table @code -@item nnmail-pathname-coding-system -@vindex nnmail-pathname-coding-system -The value of this variable should be a coding system or @code{nil}. The -default is @code{nil} in Emacs, or is the aliasee of the coding system -named @code{file-name} (a certain coding system of which an alias is -@code{file-name}) in XEmacs. - -The @code{nnml} back end, the @code{nnrss} back end, the agent, and -the cache use non-@acronym{ASCII} group names in those files and -directories. This variable overrides the value of -@code{file-name-coding-system} which specifies the coding system used -when encoding and decoding those file names and directory names. - -In XEmacs (with the @code{mule} feature), @code{file-name-coding-system} -is the only means to specify the coding system used to encode and decode -file names. On the other hand, Emacs uses the value of -@code{default-file-name-coding-system} if @code{file-name-coding-system} -is @code{nil} or it is bound to the value of -@code{nnmail-pathname-coding-system} which is @code{nil}. - -Normally the value of @code{default-file-name-coding-system} in Emacs or -@code{nnmail-pathname-coding-system} in XEmacs is initialized according -to the locale, so you will need to do nothing if the value is suitable -to encode and decode non-@acronym{ASCII} group names. - -The value of this variable (or @code{default-file-name-coding-system}) -does not necessarily need to be the same value that is determined by -@code{gnus-group-name-charset-method-alist} and -@code{gnus-group-name-charset-group-alist}. - -If @code{default-file-name-coding-system} or this variable is -initialized by default to @code{iso-latin-1} for example, although you -want to subscribe to the groups spelled in Chinese, that is the most -typical case where you have to customize -@code{nnmail-pathname-coding-system}. The @code{utf-8} coding system is -a good candidate for it. Otherwise, you may change the locale in your -system so that @code{default-file-name-coding-system} or this variable -may be initialized to an appropriate value. -@end table - -Note that when you copy or move articles from a non-@acronym{ASCII} -group to another group, the charset used to encode and decode group -names should be the same in both groups. Otherwise the Newsgroups -header will be displayed incorrectly in the article buffer. - - -@node Misc Group Stuff -@section Misc Group Stuff - -@menu -* Scanning New Messages:: Asking Gnus to see whether new messages have arrived. -* Group Information:: Information and help on groups and Gnus. -* Group Timestamp:: Making Gnus keep track of when you last read a group. -* File Commands:: Reading and writing the Gnus files. -* Sieve Commands:: Managing Sieve scripts. -@end menu - -@table @kbd - -@item v -@kindex v (Group) -@cindex keys, reserved for users (Group) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. For example: - -@lisp -(define-key gnus-group-mode-map (kbd "v j d") - (lambda () - (interactive) - (gnus-group-jump-to-group "nndraft:drafts"))) -@end lisp - -On keys reserved for users in Emacs and on keybindings in general -@xref{Keymaps, Keymaps, , emacs, The Emacs Editor}. - -@item ^ -@kindex ^ (Group) -@findex gnus-group-enter-server-mode -Enter the server buffer (@code{gnus-group-enter-server-mode}). -@xref{Server Buffer}. - -@item a -@kindex a (Group) -@findex gnus-group-post-news -Start composing a message (a news by default) -(@code{gnus-group-post-news}). If given a prefix, post to the group -under the point. If the prefix is 1, prompt for a group to post to. -Contrary to what the name of this function suggests, the prepared -article might be a mail instead of a news, if a mail group is specified -with the prefix argument. @xref{Composing Messages}. - -@item m -@kindex m (Group) -@findex gnus-group-mail -Mail a message somewhere (@code{gnus-group-mail}). If given a prefix, -use the posting style of the group under the point. If the prefix is 1, -prompt for a group name to find the posting style. -@xref{Composing Messages}. - -@item i -@kindex i (Group) -@findex gnus-group-news -Start composing a news (@code{gnus-group-news}). If given a prefix, -post to the group under the point. If the prefix is 1, prompt -for group to post to. @xref{Composing Messages}. - -This function actually prepares a news even when using mail groups. -This is useful for ``posting'' messages to mail groups without actually -sending them over the network: they're just saved directly to the group -in question. The corresponding back end must have a request-post method -for this to work though. - -@item G z -@kindex G z (Group) -@findex gnus-group-compact-group - -Compact the group under point (@code{gnus-group-compact-group}). -Currently implemented only in nnml (@pxref{Mail Spool}). This removes -gaps between article numbers, hence getting a correct total article -count. - -@end table - -Variables for the group buffer: - -@table @code - -@item gnus-group-mode-hook -@vindex gnus-group-mode-hook -is called after the group buffer has been -created. - -@item gnus-group-prepare-hook -@vindex gnus-group-prepare-hook -is called after the group buffer is -generated. It may be used to modify the buffer in some strange, -unnatural way. - -@item gnus-group-prepared-hook -@vindex gnus-group-prepare-hook -is called as the very last thing after the group buffer has been -generated. It may be used to move point around, for instance. - -@item gnus-permanently-visible-groups -@vindex gnus-permanently-visible-groups -Groups matching this regexp will always be listed in the group buffer, -whether they are empty or not. - -@end table - -@node Scanning New Messages -@subsection Scanning New Messages -@cindex new messages -@cindex scanning new news - -@table @kbd - -@item g -@kindex g (Group) -@findex gnus-group-get-new-news -@c @icon{gnus-group-get-new-news} -Check the server(s) for new articles. If the numerical prefix is used, -this command will check only groups of level @var{arg} and lower -(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this -command will force a total re-reading of the active file(s) from the -back end(s). - -@item M-g -@kindex M-g (Group) -@findex gnus-group-get-new-news-this-group -@vindex gnus-goto-next-group-when-activating -@c @icon{gnus-group-get-new-news-this-group} -Check whether new articles have arrived in the current group -(@code{gnus-group-get-new-news-this-group}). -@code{gnus-goto-next-group-when-activating} says whether this command is -to move point to the next group or not. It is @code{t} by default. - -@findex gnus-activate-all-groups -@cindex activating groups -@item C-c M-g -@kindex C-c M-g (Group) -Activate absolutely all groups (@code{gnus-activate-all-groups}). - -@item R -@kindex R (Group) -@cindex restarting -@findex gnus-group-restart -Restart Gnus (@code{gnus-group-restart}). This saves the @file{.newsrc} -file(s), closes the connection to all servers, clears up all run-time -Gnus variables, and then starts Gnus all over again. - -@end table - -@vindex gnus-get-new-news-hook -@code{gnus-get-new-news-hook} is run just before checking for new news. - -@vindex gnus-after-getting-new-news-hook -@code{gnus-after-getting-new-news-hook} is run after checking for new -news. - - -@node Group Information -@subsection Group Information -@cindex group information -@cindex information on groups - -@table @kbd - - -@item H d -@itemx C-c C-d -@c @icon{gnus-group-describe-group} -@kindex H d (Group) -@kindex C-c C-d (Group) -@cindex describing groups -@cindex group description -@findex gnus-group-describe-group -Describe the current group (@code{gnus-group-describe-group}). If given -a prefix, force Gnus to re-read the description from the server. - -@item M-d -@kindex M-d (Group) -@findex gnus-group-describe-all-groups -Describe all groups (@code{gnus-group-describe-all-groups}). If given a -prefix, force Gnus to re-read the description file from the server. - -@item H v -@itemx V -@kindex V (Group) -@kindex H v (Group) -@cindex version -@findex gnus-version -Display current Gnus version numbers (@code{gnus-version}). - -@item ? -@kindex ? (Group) -@findex gnus-group-describe-briefly -Give a very short help message (@code{gnus-group-describe-briefly}). - -@item C-c C-i -@kindex C-c C-i (Group) -@cindex info -@cindex manual -@findex gnus-info-find-node -Go to the Gnus info node (@code{gnus-info-find-node}). -@end table - - -@node Group Timestamp -@subsection Group Timestamp -@cindex timestamps -@cindex group timestamps - -It can be convenient to let Gnus keep track of when you last read a -group. To set the ball rolling, you should add -@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}: - -@lisp -(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp) -@end lisp - -After doing this, each time you enter a group, it'll be recorded. - -This information can be displayed in various ways---the easiest is to -use the @samp{%d} spec in the group line format: - -@lisp -(setq gnus-group-line-format - "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n") -@end lisp - -This will result in lines looking like: - -@example -* 0: mail.ding 19961002T012943 - 0: custom 19961002T012713 -@end example - -As you can see, the date is displayed in compact ISO 8601 format. This -may be a bit too much, so to just display the date, you could say -something like: - -@lisp -(setq gnus-group-line-format - "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n") -@end lisp - -If you would like greater control of the time format, you can use a -user-defined format spec. Something like the following should do the -trick: - -@lisp -(setq gnus-group-line-format - "%M\%S\%p\%P\%5y: %(%-40,40g%) %ud\n") -(defun gnus-user-format-function-d (headers) - (let ((time (gnus-group-timestamp gnus-tmp-group))) - (if time - (format-time-string "%b %d %H:%M" time) - ""))) -@end lisp - -To see what variables are dynamically bound (like -@code{gnus-tmp-group}), you have to look at the source code. The -variable names aren't guaranteed to be stable over Gnus versions, -either. - - -@node File Commands -@subsection File Commands -@cindex file commands - -@table @kbd - -@item r -@kindex r (Group) -@findex gnus-group-read-init-file -@vindex gnus-init-file -@cindex reading init file -Re-read the init file (@code{gnus-init-file}, which defaults to -@file{~/.gnus.el}) (@code{gnus-group-read-init-file}). - -@item s -@kindex s (Group) -@findex gnus-group-save-newsrc -@cindex saving .newsrc -Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted) -(@code{gnus-group-save-newsrc}). If given a prefix, force saving the -file(s) whether Gnus thinks it is necessary or not. - -@c @item Z -@c @kindex Z (Group) -@c @findex gnus-group-clear-dribble -@c Clear the dribble buffer (@code{gnus-group-clear-dribble}). - -@end table - - -@node Sieve Commands -@subsection Sieve Commands -@cindex group sieve commands - -Sieve is a server-side mail filtering language. In Gnus you can use -the @code{sieve} group parameter (@pxref{Group Parameters}) to specify -sieve rules that should apply to each group. Gnus provides two -commands to translate all these group parameters into a proper Sieve -script that can be transferred to the server somehow. - -@vindex gnus-sieve-file -@vindex gnus-sieve-region-start -@vindex gnus-sieve-region-end -The generated Sieve script is placed in @code{gnus-sieve-file} (by -default @file{~/.sieve}). The Sieve code that Gnus generate is placed -between two delimiters, @code{gnus-sieve-region-start} and -@code{gnus-sieve-region-end}, so you may write additional Sieve code -outside these delimiters that will not be removed the next time you -regenerate the Sieve script. - -@vindex gnus-sieve-crosspost -The variable @code{gnus-sieve-crosspost} controls how the Sieve script -is generated. If it is non-@code{nil} (the default) articles is -placed in all groups that have matching rules, otherwise the article -is only placed in the group with the first matching rule. For -example, the group parameter @samp{(sieve address "sender" -"owner-ding@@hpc.uh.edu")} will generate the following piece of Sieve -code if @code{gnus-sieve-crosspost} is @code{nil}. (When -@code{gnus-sieve-crosspost} is non-@code{nil}, it looks the same -except that the line containing the call to @code{stop} is removed.) - -@example -if address "sender" "owner-ding@@hpc.uh.edu" @{ - fileinto "INBOX.ding"; - stop; -@} -@end example - -@xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}. - -@table @kbd - -@item D g -@kindex D g (Group) -@findex gnus-sieve-generate -@vindex gnus-sieve-file -@cindex generating sieve script -Regenerate a Sieve script from the @code{sieve} group parameters and -put you into the @code{gnus-sieve-file} without saving it. - -@item D u -@kindex D u (Group) -@findex gnus-sieve-update -@vindex gnus-sieve-file -@cindex updating sieve script -Regenerates the Gnus managed part of @code{gnus-sieve-file} using the -@code{sieve} group parameters, save the file and upload it to the -server using the @code{sieveshell} program. - -@end table - - -@node Summary Buffer -@chapter Summary Buffer -@cindex summary buffer - -A line for each article is displayed in the summary buffer. You can -move around, read articles, post articles and reply to articles. - -The most common way to a summary buffer is to select a group from the -group buffer (@pxref{Selecting a Group}). - -You can have as many summary buffers open as you wish. - -You can customize the Summary Mode tool bar, see @kbd{M-x -customize-apropos RET gnus-summary-tool-bar}. This feature is only -available in Emacs. - -@kindex v (Summary) -@cindex keys, reserved for users (Summary) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. For example: -@lisp -(define-key gnus-summary-mode-map (kbd "v -") "LrS") ;; lower subthread -@end lisp - -@menu -* Summary Buffer Format:: Deciding how the summary buffer is to look. -* Summary Maneuvering:: Moving around the summary buffer. -* Choosing Articles:: Reading articles. -* Paging the Article:: Scrolling the current article. -* Reply Followup and Post:: Posting articles. -* Delayed Articles:: Send articles at a later time. -* Marking Articles:: Marking articles as read, expirable, etc. -* Limiting:: You can limit the summary buffer. -* Threading:: How threads are made. -* Sorting the Summary Buffer:: How articles and threads are sorted. -* Asynchronous Fetching:: Gnus might be able to pre-fetch articles. -* Article Caching:: You may store articles in a cache. -* Persistent Articles:: Making articles expiry-resistant. -* Sticky Articles:: Article buffers that are not reused. -* Article Backlog:: Having already read articles hang around. -* Saving Articles:: Ways of customizing article saving. -* Decoding Articles:: Gnus can treat series of (uu)encoded articles. -* Article Treatment:: The article buffer can be mangled at will. -* MIME Commands:: Doing MIMEy things with the articles. -* Charsets:: Character set issues. -* Article Commands:: Doing various things with the article buffer. -* Summary Sorting:: Sorting the summary buffer in various ways. -* Finding the Parent:: No child support? Get the parent. -* Alternative Approaches:: Reading using non-default summaries. -* Tree Display:: A more visual display of threads. -* Mail Group Commands:: Some commands can only be used in mail groups. -* Various Summary Stuff:: What didn't fit anywhere else. -* Exiting the Summary Buffer:: Returning to the Group buffer, - or reselecting the current group. -* Crosspost Handling:: How crossposted articles are dealt with. -* Duplicate Suppression:: An alternative when crosspost handling fails. -* Security:: Decrypt and Verify. -* Mailing List:: Mailing list minor mode. -@end menu - - -@node Summary Buffer Format -@section Summary Buffer Format -@cindex summary buffer format - -@iftex -@iflatex -\gnusfigure{The Summary Buffer}{180}{ -\put(0,0){\epsfig{figure=ps/summary,width=7.5cm}} -\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-article,width=7.5cm}}} -} -@end iflatex -@end iftex - -@menu -* Summary Buffer Lines:: You can specify how summary lines should look. -* To From Newsgroups:: How to not display your own name. -* Summary Buffer Mode Line:: You can say how the mode line should look. -* Summary Highlighting:: Making the summary buffer all pretty and nice. -@end menu - -@findex mail-extract-address-components -@findex gnus-extract-address-components -@vindex gnus-extract-address-components -Gnus will use the value of the @code{gnus-extract-address-components} -variable as a function for getting the name and address parts of a -@code{From} header. Two pre-defined functions exist: -@code{gnus-extract-address-components}, which is the default, quite -fast, and too simplistic solution; and -@code{mail-extract-address-components}, which works very nicely, but is -slower. The default function will return the wrong answer in 5% of the -cases. If this is unacceptable to you, use the other function instead: - -@lisp -(setq gnus-extract-address-components - 'mail-extract-address-components) -@end lisp - -@vindex gnus-summary-same-subject -@code{gnus-summary-same-subject} is a string indicating that the current -article has the same subject as the previous. This string will be used -with those specs that require it. The default is @code{""}. - - -@node Summary Buffer Lines -@subsection Summary Buffer Lines - -@vindex gnus-summary-line-format -You can change the format of the lines in the summary buffer by changing -the @code{gnus-summary-line-format} variable. It works along the same -lines as a normal @code{format} string, with some extensions -(@pxref{Formatting Variables}). - -There should always be a colon or a point position marker on the line; -the cursor always moves to the point position marker or the colon after -performing an operation. (Of course, Gnus wouldn't be Gnus if it wasn't -possible to change this. Just write a new function -@code{gnus-goto-colon} which does whatever you like with the cursor.) -@xref{Positioning Point}. - -The default string is @samp{%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n}. - -The following format specification characters and extended format -specification(s) are understood: - -@table @samp -@item N -Article number. -@item S -Subject string. List identifiers stripped, -@code{gnus-list-identifiers}. @xref{Article Hiding}. -@item s -Subject if the article is the root of the thread or the previous article -had a different subject, @code{gnus-summary-same-subject} otherwise. -(@code{gnus-summary-same-subject} defaults to @code{""}.) -@item F -Full @code{From} header. -@item n -The name (from the @code{From} header). -@item f -The name, @code{To} header or the @code{Newsgroups} header (@pxref{To -From Newsgroups}). -@item a -The name (from the @code{From} header). This differs from the @code{n} -spec in that it uses the function designated by the -@code{gnus-extract-address-components} variable, which is slower, but -may be more thorough. -@item A -The address (from the @code{From} header). This works the same way as -the @code{a} spec. -@item L -Number of lines in the article. -@item c -Number of characters in the article. This specifier is not supported -in some methods (like nnfolder). -@item k -Pretty-printed version of the number of characters in the article; -for example, @samp{1.2k} or @samp{0.4M}. -@item I -Indentation based on thread level (@pxref{Customizing Threading}). -@item B -A complex trn-style thread tree, showing response-connecting trace -lines. A thread could be drawn like this: - -@example -> -+-> -| +-> -| | \-> -| | \-> -| \-> -+-> -\-> -@end example - -You can customize the appearance with the following options. Note -that it is possible to make the thread display look really neat by -replacing the default @acronym{ASCII} characters with graphic -line-drawing glyphs. -@table @code -@item gnus-sum-thread-tree-root -@vindex gnus-sum-thread-tree-root -Used for the root of a thread. If @code{nil}, use subject -instead. The default is @samp{> }. - -@item gnus-sum-thread-tree-false-root -@vindex gnus-sum-thread-tree-false-root -Used for the false root of a thread (@pxref{Loose Threads}). If -@code{nil}, use subject instead. The default is @samp{> }. - -@item gnus-sum-thread-tree-single-indent -@vindex gnus-sum-thread-tree-single-indent -Used for a thread with just one message. If @code{nil}, use subject -instead. The default is @samp{}. - -@item gnus-sum-thread-tree-vertical -@vindex gnus-sum-thread-tree-vertical -Used for drawing a vertical line. The default is @samp{| }. - -@item gnus-sum-thread-tree-indent -@vindex gnus-sum-thread-tree-indent -Used for indenting. The default is @samp{ }. - -@item gnus-sum-thread-tree-leaf-with-other -@vindex gnus-sum-thread-tree-leaf-with-other -Used for a leaf with brothers. The default is @samp{+-> }. - -@item gnus-sum-thread-tree-single-leaf -@vindex gnus-sum-thread-tree-single-leaf -Used for a leaf without brothers. The default is @samp{\-> } - -@end table - -@item T -Nothing if the article is a root and lots of spaces if it isn't (it -pushes everything after it off the screen). -@item [ -Opening bracket, which is normally @samp{[}, but can also be @samp{<} -for adopted articles (@pxref{Customizing Threading}). -@item ] -Closing bracket, which is normally @samp{]}, but can also be @samp{>} -for adopted articles. -@item > -One space for each thread level. -@item < -Twenty minus thread level spaces. -@item U -Unread. @xref{Read Articles}. - -@item R -This misleadingly named specifier is the @dfn{secondary mark}. This -mark will say whether the article has been replied to, has been cached, -or has been saved. @xref{Other Marks}. - -@item i -Score as a number (@pxref{Scoring}). -@item z -@vindex gnus-summary-zcore-fuzz -Zcore, @samp{+} if above the default level and @samp{-} if below the -default level. If the difference between -@code{gnus-summary-default-score} and the score is less than -@code{gnus-summary-zcore-fuzz}, this spec will not be used. -@item V -Total thread score. -@item x -@code{Xref}. -@item D -@code{Date}. -@item d -The @code{Date} in @code{DD-MMM} format. -@item o -The @code{Date} in @var{YYYYMMDD}@code{T}@var{HHMMSS} format. -@item M -@code{Message-ID}. -@item r -@code{References}. -@item t -Number of articles in the current sub-thread. Using this spec will slow -down summary buffer generation somewhat. -@item e -An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the -article has any children. -@item P -The line number. -@item O -Download mark. -@item * -Desired cursor position (instead of after first colon). -@item &user-date; -Age sensitive date format. Various date format is defined in -@code{gnus-user-date-format-alist}. -@item u -User defined specifier. The next character in the format string should -be a letter. Gnus will call the function -@code{gnus-user-format-function-@var{x}}, where @var{x} is the letter -following @samp{%u}. The function will be passed the current header as -argument. The function should return a string, which will be inserted -into the summary just like information from any other summary specifier. -@end table - -Text between @samp{%(} and @samp{%)} will be highlighted with -@code{gnus-mouse-face} when the mouse point is placed inside the area. -There can only be one such area. - -The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs -have to be handled with care. For reasons of efficiency, Gnus will -compute what column these characters will end up in, and ``hard-code'' -that. This means that it is invalid to have these specs after a -variable-length spec. Well, you might not be arrested, but your summary -buffer will look strange, which is bad enough. - -The smart choice is to have these specs as far to the left as possible. -(Isn't that the case with everything, though? But I digress.) - -This restriction may disappear in later versions of Gnus. - - -@node To From Newsgroups -@subsection To From Newsgroups -@cindex To -@cindex Newsgroups - -In some groups (particularly in archive groups), the @code{From} header -isn't very interesting, since all the articles there are written by -you. To display the information in the @code{To} or @code{Newsgroups} -headers instead, you need to decide three things: What information to -gather; where to display it; and when to display it. - -@enumerate -@item -@vindex gnus-extra-headers -The reading of extra header information is controlled by the -@code{gnus-extra-headers}. This is a list of header symbols. For -instance: - -@lisp -(setq gnus-extra-headers - '(To Newsgroups X-Newsreader)) -@end lisp - -This will result in Gnus trying to obtain these three headers, and -storing it in header structures for later easy retrieval. - -@item -@findex gnus-extra-header -The value of these extra headers can be accessed via the -@code{gnus-extra-header} function. Here's a format line spec that will -access the @code{X-Newsreader} header: - -@example -"%~(form (gnus-extra-header 'X-Newsreader))@@" -@end example - -@item -@vindex gnus-ignored-from-addresses -The @code{gnus-ignored-from-addresses} variable says when the @samp{%f} -summary line spec returns the @code{To}, @code{Newsreader} or -@code{From} header. If this regexp matches the contents of the -@code{From} header, the value of the @code{To} or @code{Newsreader} -headers are used instead. - -To distinguish regular articles from those where the @code{From} field -has been swapped, a string is prefixed to the @code{To} or -@code{Newsgroups} header in the summary line. By default the string is -@samp{-> } for @code{To} and @samp{=> } for @code{Newsgroups}, you can -customize these strings with @code{gnus-summary-to-prefix} and -@code{gnus-summary-newsgroup-prefix}. - -@end enumerate - -@vindex nnmail-extra-headers -A related variable is @code{nnmail-extra-headers}, which controls when -to include extra headers when generating overview (@acronym{NOV}) files. -If you have old overview files, you should regenerate them after -changing this variable, by entering the server buffer using @kbd{^}, -and then @kbd{g} on the appropriate mail server (e.g., nnml) to cause -regeneration. - -@vindex gnus-summary-line-format -You also have to instruct Gnus to display the data by changing the -@code{%n} spec to the @code{%f} spec in the -@code{gnus-summary-line-format} variable. - -In summary, you'd typically put something like the following in -@file{~/.gnus.el}: - -@lisp -(setq gnus-extra-headers - '(To Newsgroups)) -(setq nnmail-extra-headers gnus-extra-headers) -(setq gnus-summary-line-format - "%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n") -(setq gnus-ignored-from-addresses - "Your Name Here") -@end lisp - -(The values listed above are the default values in Gnus. Alter them -to fit your needs.) - -A note for news server administrators, or for users who wish to try to -convince their news server administrator to provide some additional -support: - -The above is mostly useful for mail groups, where you have control over -the @acronym{NOV} files that are created. However, if you can persuade your -nntp admin to add (in the usual implementation, notably INN): - -@example -Newsgroups:full -@end example - -to the end of her @file{overview.fmt} file, then you can use that just -as you would the extra headers from the mail groups. - - -@node Summary Buffer Mode Line -@subsection Summary Buffer Mode Line - -@vindex gnus-summary-mode-line-format -You can also change the format of the summary mode bar (@pxref{Mode Line -Formatting}). Set @code{gnus-summary-mode-line-format} to whatever you -like. The default is @samp{Gnus: %%b [%A] %Z}. - -Here are the elements you can play with: - -@table @samp -@item G -Group name. -@item p -Unprefixed group name. -@item A -Current article number. -@item z -Current article score. -@item V -Gnus version. -@item U -Number of unread articles in this group. -@item e -Number of unread articles in this group that aren't displayed in the -summary buffer. -@item Z -A string with the number of unread and unselected articles represented -either as @samp{<%U(+%e) more>} if there are both unread and unselected -articles, and just as @samp{<%U more>} if there are just unread articles -and no unselected ones. -@item g -Shortish group name. For instance, @samp{rec.arts.anime} will be -shortened to @samp{r.a.anime}. -@item S -Subject of the current article. -@item u -User-defined spec (@pxref{User-Defined Specs}). -@item s -Name of the current score file (@pxref{Scoring}). -@item d -Number of dormant articles (@pxref{Unread Articles}). -@item t -Number of ticked articles (@pxref{Unread Articles}). -@item r -Number of articles that have been marked as read in this session. -@item E -Number of articles expunged by the score files. -@end table - - -@node Summary Highlighting -@subsection Summary Highlighting - -@table @code - -@item gnus-visual-mark-article-hook -@vindex gnus-visual-mark-article-hook -This hook is run after selecting an article. It is meant to be used for -highlighting the article in some way. It is not run if -@code{gnus-visual} is @code{nil}. - -@item gnus-summary-update-hook -@vindex gnus-summary-update-hook -This hook is called when a summary line is changed. It is not run if -@code{gnus-visual} is @code{nil}. - -@item gnus-summary-selected-face -@vindex gnus-summary-selected-face -This is the face (or @dfn{font} as some people call it) used to -highlight the current article in the summary buffer. - -@item gnus-summary-highlight -@vindex gnus-summary-highlight -Summary lines are highlighted according to this variable, which is a -list where the elements are of the format @code{(@var{form} -. @var{face})}. If you would, for instance, like ticked articles to be -italic and high-scored articles to be bold, you could set this variable -to something like -@lisp -(((eq mark gnus-ticked-mark) . italic) - ((> score default) . bold)) -@end lisp -As you may have guessed, if @var{form} returns a non-@code{nil} value, -@var{face} will be applied to the line. -@end table - - -@node Summary Maneuvering -@section Summary Maneuvering -@cindex summary movement - -All the straight movement commands understand the numeric prefix and -behave pretty much as you'd expect. - -None of these commands select articles. - -@table @kbd -@item G M-n -@itemx M-n -@kindex M-n (Summary) -@kindex G M-n (Summary) -@findex gnus-summary-next-unread-subject -Go to the next summary line of an unread article -(@code{gnus-summary-next-unread-subject}). - -@item G M-p -@itemx M-p -@kindex M-p (Summary) -@kindex G M-p (Summary) -@findex gnus-summary-prev-unread-subject -Go to the previous summary line of an unread article -(@code{gnus-summary-prev-unread-subject}). - -@item G g -@kindex G g (Summary) -@findex gnus-summary-goto-subject -Ask for an article number and then go to the summary line of that article -without displaying the article (@code{gnus-summary-goto-subject}). -@end table - -If Gnus asks you to press a key to confirm going to the next group, you -can use the @kbd{C-n} and @kbd{C-p} keys to move around the group -buffer, searching for the next group to read without actually returning -to the group buffer. - -Variables related to summary movement: - -@table @code - -@vindex gnus-auto-select-next -@item gnus-auto-select-next -If you issue one of the movement commands (like @kbd{n}) and there are -no more unread articles after the current one, Gnus will offer to go to -the next group. If this variable is @code{t} and the next group is -empty, Gnus will exit summary mode and return to the group buffer. If -this variable is neither @code{t} nor @code{nil}, Gnus will select the -next group with unread articles. As a special case, if this variable -is @code{quietly}, Gnus will select the next group without asking for -confirmation. If this variable is @code{almost-quietly}, the same -will happen only if you are located on the last article in the group. -Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n} -command will go to the next group without confirmation. Also -@pxref{Group Levels}. - -@item gnus-auto-select-same -@vindex gnus-auto-select-same -If non-@code{nil}, all the movement commands will try to go to the next -article with the same subject as the current. (@dfn{Same} here might -mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit} -for details (@pxref{Customizing Threading}).) If there are no more -articles with the same subject, go to the first unread article. - -This variable is not particularly useful if you use a threaded display. - -@item gnus-summary-check-current -@vindex gnus-summary-check-current -If non-@code{nil}, all the ``unread'' movement commands will not proceed -to the next (or previous) article if the current article is unread. -Instead, they will choose the current article. - -@item gnus-auto-center-summary -@vindex gnus-auto-center-summary -If non-@code{nil}, Gnus will keep the point in the summary buffer -centered at all times. This makes things quite tidy, but if you have a -slow network connection, or simply do not like this un-Emacsism, you can -set this variable to @code{nil} to get the normal Emacs scrolling -action. This will also inhibit horizontal re-centering of the summary -buffer, which might make it more inconvenient to read extremely long -threads. - -This variable can also be a number. In that case, center the window at -the given number of lines from the top. - -@item gnus-summary-stop-at-end-of-message -@vindex gnus-summary-stop-at-end-of-message -If non-@code{nil}, don't go to the next article when hitting -@kbd{SPC}, and you're at the end of the article. - -@end table - - -@node Choosing Articles -@section Choosing Articles -@cindex selecting articles - -@menu -* Choosing Commands:: Commands for choosing articles. -* Choosing Variables:: Variables that influence these commands. -@end menu - - -@node Choosing Commands -@subsection Choosing Commands - -None of the following movement commands understand the numeric prefix, -and they all select and display an article. - -If you want to fetch new articles or redisplay the group, see -@ref{Exiting the Summary Buffer}. - -@table @kbd -@item SPACE -@kindex SPACE (Summary) -@findex gnus-summary-next-page -Select the current article, or, if that one's read already, the next -unread article (@code{gnus-summary-next-page}). - -If you have an article window open already and you press @kbd{SPACE} -again, the article will be scrolled. This lets you conveniently -@kbd{SPACE} through an entire newsgroup. @xref{Paging the Article}. - -@item G n -@itemx n -@kindex n (Summary) -@kindex G n (Summary) -@findex gnus-summary-next-unread-article -@c @icon{gnus-summary-next-unread} -Go to next unread article (@code{gnus-summary-next-unread-article}). - -@item G p -@itemx p -@kindex p (Summary) -@findex gnus-summary-prev-unread-article -@c @icon{gnus-summary-prev-unread} -Go to previous unread article (@code{gnus-summary-prev-unread-article}). - -@item G N -@itemx N -@kindex N (Summary) -@kindex G N (Summary) -@findex gnus-summary-next-article -Go to the next article (@code{gnus-summary-next-article}). - -@item G P -@itemx P -@kindex P (Summary) -@kindex G P (Summary) -@findex gnus-summary-prev-article -Go to the previous article (@code{gnus-summary-prev-article}). - -@item G C-n -@kindex G C-n (Summary) -@findex gnus-summary-next-same-subject -Go to the next article with the same subject -(@code{gnus-summary-next-same-subject}). - -@item G C-p -@kindex G C-p (Summary) -@findex gnus-summary-prev-same-subject -Go to the previous article with the same subject -(@code{gnus-summary-prev-same-subject}). - -@item G f -@itemx . -@kindex G f (Summary) -@kindex . (Summary) -@findex gnus-summary-first-unread-article -Go to the first unread article -(@code{gnus-summary-first-unread-article}). - -@item G b -@itemx , -@kindex G b (Summary) -@kindex , (Summary) -@findex gnus-summary-best-unread-article -Go to the unread article with the highest score -(@code{gnus-summary-best-unread-article}). If given a prefix argument, -go to the first unread article that has a score over the default score. - -@item G l -@itemx l -@kindex l (Summary) -@kindex G l (Summary) -@findex gnus-summary-goto-last-article -Go to the previous article read (@code{gnus-summary-goto-last-article}). - -@item G o -@kindex G o (Summary) -@findex gnus-summary-pop-article -@cindex history -@cindex article history -Pop an article off the summary history and go to this article -(@code{gnus-summary-pop-article}). This command differs from the -command above in that you can pop as many previous articles off the -history as you like, while @kbd{l} toggles the two last read articles. -For a somewhat related issue (if you use these commands a lot), -@pxref{Article Backlog}. - -@item G j -@itemx j -@kindex j (Summary) -@kindex G j (Summary) -@findex gnus-summary-goto-article -Ask for an article number or @code{Message-ID}, and then go to that -article (@code{gnus-summary-goto-article}). - -@end table - - -@node Choosing Variables -@subsection Choosing Variables - -Some variables relevant for moving and selecting articles: - -@table @code -@item gnus-auto-extend-newsgroup -@vindex gnus-auto-extend-newsgroup -All the movement commands will try to go to the previous (or next) -article, even if that article isn't displayed in the Summary buffer if -this variable is non-@code{nil}. Gnus will then fetch the article from -the server and display it in the article buffer. - -@item gnus-select-article-hook -@vindex gnus-select-article-hook -This hook is called whenever an article is selected. The default is -@code{nil}. If you would like each article to be saved in the Agent as -you read it, putting @code{gnus-agent-fetch-selected-article} on this -hook will do so. - -@item gnus-mark-article-hook -@vindex gnus-mark-article-hook -@findex gnus-summary-mark-unread-as-read -@findex gnus-summary-mark-read-and-unread-as-read -@findex gnus-unread-mark -This hook is called whenever an article is selected. It is intended to -be used for marking articles as read. The default value is -@code{gnus-summary-mark-read-and-unread-as-read}, and will change the -mark of almost any article you read to @code{gnus-read-mark}. The only -articles not affected by this function are ticked, dormant, and -expirable articles. If you'd instead like to just have unread articles -marked as read, you can use @code{gnus-summary-mark-unread-as-read} -instead. It will leave marks like @code{gnus-low-score-mark}, -@code{gnus-del-mark} (and so on) alone. - -@end table - - -@node Paging the Article -@section Scrolling the Article -@cindex article scrolling - -@table @kbd - -@item SPACE -@kindex SPACE (Summary) -@findex gnus-summary-next-page -Pressing @kbd{SPACE} will scroll the current article forward one page, -or, if you have come to the end of the current article, will choose the -next article (@code{gnus-summary-next-page}). - -@vindex gnus-article-boring-faces -@vindex gnus-article-skip-boring -If @code{gnus-article-skip-boring} is non-@code{nil} and the rest of -the article consists only of citations and signature, then it will be -skipped; the next article will be shown instead. You can customize -what is considered uninteresting with -@code{gnus-article-boring-faces}. You can manually view the article's -pages, no matter how boring, using @kbd{C-M-v}. - -@item DEL -@kindex DEL (Summary) -@findex gnus-summary-prev-page -Scroll the current article back one page (@code{gnus-summary-prev-page}). - -@item RET -@kindex RET (Summary) -@findex gnus-summary-scroll-up -Scroll the current article one line forward -(@code{gnus-summary-scroll-up}). - -@item M-RET -@kindex M-RET (Summary) -@findex gnus-summary-scroll-down -Scroll the current article one line backward -(@code{gnus-summary-scroll-down}). - -@item A g -@itemx g -@kindex A g (Summary) -@kindex g (Summary) -@findex gnus-summary-show-article -@vindex gnus-summary-show-article-charset-alist -(Re)fetch the current article (@code{gnus-summary-show-article}). If -given a prefix, show a completely ``raw'' article, just the way it -came from the server. If given a prefix twice (i.e., @kbd{C-u C-u -g'}), fetch the current article, but don't run any of the article -treatment functions. - -@cindex charset, view article with different charset -If given a numerical prefix, you can do semi-manual charset stuff. -@kbd{C-u 0 g cn-gb-2312 RET} will decode the message as if it were -encoded in the @code{cn-gb-2312} charset. If you have - -@lisp -(setq gnus-summary-show-article-charset-alist - '((1 . cn-gb-2312) - (2 . big5))) -@end lisp - -then you can say @kbd{C-u 1 g} to get the same effect. - -@item A < -@itemx < -@kindex < (Summary) -@kindex A < (Summary) -@findex gnus-summary-beginning-of-article -Scroll to the beginning of the article -(@code{gnus-summary-beginning-of-article}). - -@item A > -@itemx > -@kindex > (Summary) -@kindex A > (Summary) -@findex gnus-summary-end-of-article -Scroll to the end of the article (@code{gnus-summary-end-of-article}). - -@item A s -@itemx s -@kindex A s (Summary) -@kindex s (Summary) -@findex gnus-summary-isearch-article -Perform an isearch in the article buffer -(@code{gnus-summary-isearch-article}). - -@item h -@kindex h (Summary) -@findex gnus-summary-select-article-buffer -Select the article buffer (@code{gnus-summary-select-article-buffer}). - -@end table - - -@node Reply Followup and Post -@section Reply, Followup and Post - -@menu -* Summary Mail Commands:: Sending mail. -* Summary Post Commands:: Sending news. -* Summary Message Commands:: Other Message-related commands. -* Canceling and Superseding:: -@end menu - - -@node Summary Mail Commands -@subsection Summary Mail Commands -@cindex mail -@cindex composing mail - -Commands for composing a mail message: - -@table @kbd - -@item S r -@itemx r -@kindex S r (Summary) -@kindex r (Summary) -@findex gnus-summary-reply -@c @icon{gnus-summary-mail-reply} -@c @icon{gnus-summary-reply} -Mail a reply to the author of the current article -(@code{gnus-summary-reply}). - -@item S R -@itemx R -@kindex R (Summary) -@kindex S R (Summary) -@findex gnus-summary-reply-with-original -@c @icon{gnus-summary-reply-with-original} -Mail a reply to the author of the current article and include the -original message (@code{gnus-summary-reply-with-original}). This -command uses the process/prefix convention. - -@item S w -@kindex S w (Summary) -@findex gnus-summary-wide-reply -Mail a wide reply to the author of the current article -(@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that -goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers. If @code{Mail-Followup-To} is -present, that's used instead. - -@item S W -@kindex S W (Summary) -@findex gnus-summary-wide-reply-with-original -Mail a wide reply to the current article and include the original -message (@code{gnus-summary-wide-reply-with-original}). This command uses -the process/prefix convention, but only uses the headers from the -first article to determine the recipients. - -@item S L -@kindex S L (Summary) -@findex gnus-summary-reply-to-list-with-original -When replying to a message from a mailing list, send a reply to that -message to the mailing list, and include the original message -(@code{gnus-summary-reply-to-list-with-original}). - -@item S v -@kindex S v (Summary) -@findex gnus-summary-very-wide-reply -Mail a very wide reply to the author of the current article -(@code{gnus-summary-wide-reply}). A @dfn{very wide reply} is a reply -that goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers in all the process/prefixed -articles. This command uses the process/prefix convention. - -@item S V -@kindex S V (Summary) -@findex gnus-summary-very-wide-reply-with-original -Mail a very wide reply to the author of the current article and include the -original message (@code{gnus-summary-very-wide-reply-with-original}). This -command uses the process/prefix convention. - -@item S B r -@kindex S B r (Summary) -@findex gnus-summary-reply-broken-reply-to -Mail a reply to the author of the current article but ignore the -@code{Reply-To} field (@code{gnus-summary-reply-broken-reply-to}). -If you need this because a mailing list incorrectly sets a -@code{Reply-To} header pointing to the list, you probably want to set -the @code{broken-reply-to} group parameter instead, so things will work -correctly. @xref{Group Parameters}. - -@item S B R -@kindex S B R (Summary) -@findex gnus-summary-reply-broken-reply-to-with-original -Mail a reply to the author of the current article and include the -original message but ignore the @code{Reply-To} field -(@code{gnus-summary-reply-broken-reply-to-with-original}). - -@item S o m -@itemx C-c C-f -@kindex S o m (Summary) -@kindex C-c C-f (Summary) -@findex gnus-summary-mail-forward -@c @icon{gnus-summary-mail-forward} -Forward the current article to some other person -(@code{gnus-summary-mail-forward}). If no prefix is given, the message -is forwarded according to the value of (@code{message-forward-as-mime}) -and (@code{message-forward-show-mml}); if the prefix is 1, decode the -message and forward directly inline; if the prefix is 2, forward message -as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and -forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message -directly inline; otherwise, the message is forwarded as no prefix given -but use the flipped value of (@code{message-forward-as-mime}). By -default, the message is decoded and forwarded as an rfc822 @acronym{MIME} -section. - -@item S m -@itemx m -@kindex m (Summary) -@kindex S m (Summary) -@findex gnus-summary-mail-other-window -@c @icon{gnus-summary-mail-originate} -Prepare a mail (@code{gnus-summary-mail-other-window}). By default, use -the posting style of the current group. If given a prefix, disable that. -If the prefix is 1, prompt for a group name to find the posting style. - -@item S i -@kindex S i (Summary) -@findex gnus-summary-news-other-window -Prepare a news (@code{gnus-summary-news-other-window}). By default, -post to the current group. If given a prefix, disable that. If the -prefix is 1, prompt for a group to post to. - -This function actually prepares a news even when using mail groups. -This is useful for ``posting'' messages to mail groups without actually -sending them over the network: they're just saved directly to the group -in question. The corresponding back end must have a request-post method -for this to work though. - -@item S D b -@kindex S D b (Summary) -@findex gnus-summary-resend-bounced-mail -@cindex bouncing mail -If you have sent a mail, but the mail was bounced back to you for some -reason (wrong address, transient failure), you can use this command to -resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You -will be popped into a mail buffer where you can edit the headers before -sending the mail off again. If you give a prefix to this command, and -the bounced mail is a reply to some other mail, Gnus will try to fetch -that mail and display it for easy perusal of its headers. This might -very well fail, though. - -@item S D r -@kindex S D r (Summary) -@findex gnus-summary-resend-message -Not to be confused with the previous command, -@code{gnus-summary-resend-message} will prompt you for an address to -send the current message off to, and then send it to that place. The -headers of the message won't be altered---but lots of headers that say -@code{Resent-To}, @code{Resent-From} and so on will be added. This -means that you actually send a mail to someone that has a @code{To} -header that (probably) points to yourself. This will confuse people. -So, natcherly you'll only do that if you're really eVIl. - -This command is mainly used if you have several accounts and want to -ship a mail to a different account of yours. (If you're both -@code{root} and @code{postmaster} and get a mail for @code{postmaster} -to the @code{root} account, you may want to resend it to -@code{postmaster}. Ordnung muss sein! - -This command understands the process/prefix convention -(@pxref{Process/Prefix}). - -@item S D e -@kindex S D e (Summary) -@findex gnus-summary-resend-message-edit - -Like the previous command, but will allow you to edit the message as -if it were a new message before resending. - -@item S O m -@kindex S O m (Summary) -@findex gnus-uu-digest-mail-forward -Digest the current series (@pxref{Decoding Articles}) and forward the -result using mail (@code{gnus-uu-digest-mail-forward}). This command -uses the process/prefix convention (@pxref{Process/Prefix}). - -@item S M-c -@kindex S M-c (Summary) -@findex gnus-summary-mail-crosspost-complaint -@cindex crossposting -@cindex excessive crossposting -Send a complaint about excessive crossposting to the author of the -current article (@code{gnus-summary-mail-crosspost-complaint}). - -@findex gnus-crosspost-complaint -This command is provided as a way to fight back against the current -crossposting pandemic that's sweeping Usenet. It will compose a reply -using the @code{gnus-crosspost-complaint} variable as a preamble. This -command understands the process/prefix convention -(@pxref{Process/Prefix}) and will prompt you before sending each mail. - -@end table - -Also @xref{Header Commands, ,Header Commands, message, The Message -Manual}, for more information. - - -@node Summary Post Commands -@subsection Summary Post Commands -@cindex post -@cindex composing news - -Commands for posting a news article: - -@table @kbd -@item S p -@itemx a -@kindex a (Summary) -@kindex S p (Summary) -@findex gnus-summary-post-news -@c @icon{gnus-summary-post-news} -Prepare for posting an article (@code{gnus-summary-post-news}). By -default, post to the current group. If given a prefix, disable that. -If the prefix is 1, prompt for another group instead. - -@item S f -@itemx f -@kindex f (Summary) -@kindex S f (Summary) -@findex gnus-summary-followup -@c @icon{gnus-summary-followup} -Post a followup to the current article (@code{gnus-summary-followup}). - -@item S F -@itemx F -@kindex S F (Summary) -@kindex F (Summary) -@c @icon{gnus-summary-followup-with-original} -@findex gnus-summary-followup-with-original -Post a followup to the current article and include the original message -(@code{gnus-summary-followup-with-original}). This command uses the -process/prefix convention. - -@item S n -@kindex S n (Summary) -@findex gnus-summary-followup-to-mail -Post a followup to the current article via news, even if you got the -message through mail (@code{gnus-summary-followup-to-mail}). - -@item S N -@kindex S N (Summary) -@findex gnus-summary-followup-to-mail-with-original -Post a followup to the current article via news, even if you got the -message through mail and include the original message -(@code{gnus-summary-followup-to-mail-with-original}). This command uses -the process/prefix convention. - -@item S o p -@kindex S o p (Summary) -@findex gnus-summary-post-forward -Forward the current article to a newsgroup -(@code{gnus-summary-post-forward}). - If no prefix is given, the message is forwarded according to the value -of (@code{message-forward-as-mime}) and -(@code{message-forward-show-mml}); if the prefix is 1, decode the -message and forward directly inline; if the prefix is 2, forward message -as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and -forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message -directly inline; otherwise, the message is forwarded as no prefix given -but use the flipped value of (@code{message-forward-as-mime}). By -default, the message is decoded and forwarded as an rfc822 @acronym{MIME} section. - -@item S O p -@kindex S O p (Summary) -@findex gnus-uu-digest-post-forward -@cindex digests -@cindex making digests -Digest the current series and forward the result to a newsgroup -(@code{gnus-uu-digest-post-forward}). This command uses the -process/prefix convention. - -@item S u -@kindex S u (Summary) -@findex gnus-uu-post-news -@c @icon{gnus-uu-post-news} -Uuencode a file, split it into parts, and post it as a series -(@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}). -@end table - -Also @xref{Header Commands, ,Header Commands, message, The Message -Manual}, for more information. - - -@node Summary Message Commands -@subsection Summary Message Commands - -@table @kbd -@item S y -@kindex S y (Summary) -@findex gnus-summary-yank-message -Yank the current article into an already existing Message composition -buffer (@code{gnus-summary-yank-message}). This command prompts for -what message buffer you want to yank into, and understands the -process/prefix convention (@pxref{Process/Prefix}). - -@end table - - -@node Canceling and Superseding -@subsection Canceling Articles -@cindex canceling articles -@cindex superseding articles - -Have you ever written something, and then decided that you really, -really, really wish you hadn't posted that? - -Well, you can't cancel mail, but you can cancel posts. - -@findex gnus-summary-cancel-article -@kindex C (Summary) -@c @icon{gnus-summary-cancel-article} -Find the article you wish to cancel (you can only cancel your own -articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S -c} (@code{gnus-summary-cancel-article}). Your article will be -canceled---machines all over the world will be deleting your article. -This command uses the process/prefix convention (@pxref{Process/Prefix}). - -Be aware, however, that not all sites honor cancels, so your article may -live on here and there, while most sites will delete the article in -question. - -Gnus will use the ``current'' select method when canceling. If you -want to use the standard posting method, use the @samp{a} symbolic -prefix (@pxref{Symbolic Prefixes}). - -Gnus ensures that only you can cancel your own messages using a -@code{Cancel-Lock} header (@pxref{Canceling News, Canceling News, , -message, Message Manual}). - -If you discover that you have made some mistakes and want to do some -corrections, you can post a @dfn{superseding} article that will replace -your original article. - -@findex gnus-summary-supersede-article -@kindex S (Summary) -Go to the original article and press @kbd{S s} -(@code{gnus-summary-supersede-article}). You will be put in a buffer -where you can edit the article all you want before sending it off the -usual way. - -The same goes for superseding as for canceling, only more so: Some -sites do not honor superseding. On those sites, it will appear that you -have posted almost the same article twice. - -If you have just posted the article, and change your mind right away, -there is a trick you can use to cancel/supersede the article without -waiting for the article to appear on your site first. You simply return -to the post buffer (which is called @file{*sent ...*}). There you will -find the article you just posted, with all the headers intact. Change -the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes} -header by substituting one of those words for the word -@code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as -you would do normally. The previous article will be -canceled/superseded. - -Just remember, kids: There is no 'c' in 'supersede'. - -@node Delayed Articles -@section Delayed Articles -@cindex delayed sending -@cindex send delayed - -Sometimes, you might wish to delay the sending of a message. For -example, you might wish to arrange for a message to turn up just in time -to remind your about the birthday of your Significant Other. For this, -there is the @code{gnus-delay} package. Setup is simple: - -@lisp -(gnus-delay-initialize) -@end lisp - -@findex gnus-delay-article -Normally, to send a message you use the @kbd{C-c C-c} command from -Message mode. To delay a message, use @kbd{C-c C-j} -(@code{gnus-delay-article}) instead. This will ask you for how long the -message should be delayed. Possible answers are: - -@itemize @bullet -@item -A time span. Consists of an integer and a letter. For example, -@code{42d} means to delay for 42 days. Available letters are @code{m} -(minutes), @code{h} (hours), @code{d} (days), @code{w} (weeks), @code{M} -(months) and @code{Y} (years). - -@item -A specific date. Looks like @code{YYYY-MM-DD}. The message will be -delayed until that day, at a specific time (eight o'clock by default). -See also @code{gnus-delay-default-hour}. - -@item -A specific time of day. Given in @code{hh:mm} format, 24h, no am/pm -stuff. The deadline will be at that time today, except if that time has -already passed, then it's at the given time tomorrow. So if it's ten -o'clock in the morning and you specify @code{11:15}, then the deadline -is one hour and fifteen minutes hence. But if you specify @code{9:20}, -that means a time tomorrow. -@end itemize - -The action of the @code{gnus-delay-article} command is influenced by a -couple of variables: - -@table @code -@item gnus-delay-default-hour -@vindex gnus-delay-default-hour -When you specify a specific date, the message will be due on that hour -on the given date. Possible values are integers 0 through 23. - -@item gnus-delay-default-delay -@vindex gnus-delay-default-delay -This is a string and gives the default delay. It can be of any of the -formats described above. - -@item gnus-delay-group -@vindex gnus-delay-group -Delayed articles will be kept in this group on the drafts server until -they are due. You probably don't need to change this. The default -value is @code{"delayed"}. - -@item gnus-delay-header -@vindex gnus-delay-header -The deadline for each article will be stored in a header. This variable -is a string and gives the header name. You probably don't need to -change this. The default value is @code{"X-Gnus-Delayed"}. -@end table - -The way delaying works is like this: when you use the -@code{gnus-delay-article} command, you give a certain delay. Gnus -calculates the deadline of the message and stores it in the -@code{X-Gnus-Delayed} header and puts the message in the -@code{nndraft:delayed} group. - -@findex gnus-delay-send-queue -And whenever you get new news, Gnus looks through the group for articles -which are due and sends them. It uses the @code{gnus-delay-send-queue} -function for this. By default, this function is added to the hook -@code{gnus-get-new-news-hook}. But of course, you can change this. -Maybe you want to use the demon to send drafts? Just tell the demon to -execute the @code{gnus-delay-send-queue} function. - -@table @code -@item gnus-delay-initialize -@findex gnus-delay-initialize -By default, this function installs @code{gnus-delay-send-queue} in -@code{gnus-get-new-news-hook}. But it accepts the optional second -argument @code{no-check}. If it is non-@code{nil}, -@code{gnus-get-new-news-hook} is not changed. The optional first -argument is ignored. - -For example, @code{(gnus-delay-initialize nil t)} means to do nothing. -Presumably, you want to use the demon for sending due delayed articles. -Just don't forget to set that up :-) -@end table - -When delaying an article with @kbd{C-c C-j}, Message mode will -automatically add a @code{"Date"} header with the current time. In -many cases you probably want the @code{"Date"} header to reflect the -time the message is sent instead. To do this, you have to delete -@code{Date} from @code{message-draft-headers}. - - -@node Marking Articles -@section Marking Articles -@cindex article marking -@cindex article ticking -@cindex marks - -There are several marks you can set on an article. - -You have marks that decide the @dfn{readedness} (whoo, neato-keano -neologism ohoy!) of the article. Alphabetic marks generally mean -@dfn{read}, while non-alphabetic characters generally mean @dfn{unread}. - -In addition, you also have marks that do not affect readedness. - -@ifinfo -There's a plethora of commands for manipulating these marks. -@end ifinfo - -@menu -* Unread Articles:: Marks for unread articles. -* Read Articles:: Marks for read articles. -* Other Marks:: Marks that do not affect readedness. -* Setting Marks:: How to set and remove marks. -* Generic Marking Commands:: How to customize the marking. -* Setting Process Marks:: How to mark articles for later processing. -@end menu - - -@node Unread Articles -@subsection Unread Articles - -The following marks mark articles as (kinda) unread, in one form or -other. - -@table @samp -@item ! -@vindex gnus-ticked-mark -Marked as ticked (@code{gnus-ticked-mark}). - -@dfn{Ticked articles} are articles that will remain visible always. If -you see an article that you find interesting, or you want to put off -reading it, or replying to it, until sometime later, you'd typically -tick it. However, articles can be expired (from news servers by the -news server software, Gnus itself never expires ticked messages), so if -you want to keep an article forever, you'll have to make it persistent -(@pxref{Persistent Articles}). - -@item ? -@vindex gnus-dormant-mark -Marked as dormant (@code{gnus-dormant-mark}). - -@dfn{Dormant articles} will only appear in the summary buffer if there -are followups to it. If you want to see them even if they don't have -followups, you can use the @kbd{/ D} command (@pxref{Limiting}). -Otherwise (except for the visibility issue), they are just like ticked -messages. - -@item SPACE -@vindex gnus-unread-mark -Marked as unread (@code{gnus-unread-mark}). - -@dfn{Unread articles} are articles that haven't been read at all yet. -@end table - - -@node Read Articles -@subsection Read Articles -@cindex expirable mark - -All the following marks mark articles as read. - -@table @samp - -@item r -@vindex gnus-del-mark -These are articles that the user has marked as read with the @kbd{d} -command manually, more or less (@code{gnus-del-mark}). - -@item R -@vindex gnus-read-mark -Articles that have actually been read (@code{gnus-read-mark}). - -@item O -@vindex gnus-ancient-mark -Articles that were marked as read in previous sessions and are now -@dfn{old} (@code{gnus-ancient-mark}). - -@item K -@vindex gnus-killed-mark -Marked as killed (@code{gnus-killed-mark}). - -@item X -@vindex gnus-kill-file-mark -Marked as killed by kill files (@code{gnus-kill-file-mark}). - -@item Y -@vindex gnus-low-score-mark -Marked as read by having too low a score (@code{gnus-low-score-mark}). - -@item C -@vindex gnus-catchup-mark -Marked as read by a catchup (@code{gnus-catchup-mark}). - -@item G -@vindex gnus-canceled-mark -Canceled article (@code{gnus-canceled-mark}) - -@item Q -@vindex gnus-sparse-mark -Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing -Threading}. - -@item M -@vindex gnus-duplicate-mark -Article marked as read by duplicate suppression -(@code{gnus-duplicate-mark}). @xref{Duplicate Suppression}. - -@end table - -All these marks just mean that the article is marked as read, really. -They are interpreted differently when doing adaptive scoring, though. - -One more special mark, though: - -@table @samp -@item E -@vindex gnus-expirable-mark -Marked as expirable (@code{gnus-expirable-mark}). - -Marking articles as @dfn{expirable} (or have them marked as such -automatically) doesn't make much sense in normal groups---a user doesn't -control expiring of news articles, but in mail groups, for instance, -articles marked as @dfn{expirable} can be deleted by Gnus at -any time. -@end table - - -@node Other Marks -@subsection Other Marks -@cindex process mark -@cindex bookmarks - -There are some marks that have nothing to do with whether the article is -read or not. - -@itemize @bullet - -@item -You can set a bookmark in the current article. Say you are reading a -long thesis on cats' urinary tracts, and have to go home for dinner -before you've finished reading the thesis. You can then set a bookmark -in the article, and Gnus will jump to this bookmark the next time it -encounters the article. @xref{Setting Marks}. - -@item -@vindex gnus-replied-mark -All articles that you have replied to or made a followup to (i.e., have -answered) will be marked with an @samp{A} in the second column -(@code{gnus-replied-mark}). - -@item -@vindex gnus-forwarded-mark -All articles that you have forwarded will be marked with an @samp{F} in -the second column (@code{gnus-forwarded-mark}). - -@item -@vindex gnus-cached-mark -Articles stored in the article cache will be marked with an @samp{*} in -the second column (@code{gnus-cached-mark}). @xref{Article Caching}. - -@item -@vindex gnus-saved-mark -Articles ``saved'' (in some manner or other; not necessarily -religiously) are marked with an @samp{S} in the second column -(@code{gnus-saved-mark}). - -@item -@vindex gnus-unseen-mark -Articles that haven't been seen before in Gnus by the user are marked -with a @samp{.} in the second column (@code{gnus-unseen-mark}). - -@item -@vindex gnus-downloaded-mark -When using the Gnus agent (@pxref{Agent Basics}), articles may be -downloaded for unplugged (offline) viewing. If you are using the -@samp{%O} spec, these articles get the @samp{+} mark in that spec. -(The variable @code{gnus-downloaded-mark} controls which character to -use.) - -@item -@vindex gnus-undownloaded-mark -When using the Gnus agent (@pxref{Agent Basics}), some articles might -not have been downloaded. Such articles cannot be viewed while you -are unplugged (offline). If you are using the @samp{%O} spec, these -articles get the @samp{-} mark in that spec. (The variable -@code{gnus-undownloaded-mark} controls which character to use.) - -@item -@vindex gnus-downloadable-mark -The Gnus agent (@pxref{Agent Basics}) downloads some articles -automatically, but it is also possible to explicitly mark articles for -download, even if they would not be downloaded automatically. Such -explicitly-marked articles get the @samp{%} mark in the first column. -(The variable @code{gnus-downloadable-mark} controls which character to -use.) - -@item -@vindex gnus-not-empty-thread-mark -@vindex gnus-empty-thread-mark -If the @samp{%e} spec is used, the presence of threads or not will be -marked with @code{gnus-not-empty-thread-mark} and -@code{gnus-empty-thread-mark} in the third column, respectively. - -@item -@vindex gnus-process-mark -Finally we have the @dfn{process mark} (@code{gnus-process-mark}). A -variety of commands react to the presence of the process mark. For -instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view -all articles that have been marked with the process mark. Articles -marked with the process mark have a @samp{#} in the second column. - -@end itemize - -You might have noticed that most of these ``non-readedness'' marks -appear in the second column by default. So if you have a cached, saved, -replied article that you have process-marked, what will that look like? - -Nothing much. The precedence rules go as follows: process -> cache -> -replied -> saved. So if the article is in the cache and is replied, -you'll only see the cache mark and not the replied mark. - - -@node Setting Marks -@subsection Setting Marks -@cindex setting marks - -All the marking commands understand the numeric prefix. - -@table @kbd -@item M c -@itemx M-u -@kindex M c (Summary) -@kindex M-u (Summary) -@findex gnus-summary-clear-mark-forward -@cindex mark as unread -Clear all readedness-marks from the current article -(@code{gnus-summary-clear-mark-forward}). In other words, mark the -article as unread. - -@item M t -@itemx ! -@kindex ! (Summary) -@kindex M t (Summary) -@findex gnus-summary-tick-article-forward -Tick the current article (@code{gnus-summary-tick-article-forward}). -@xref{Article Caching}. - -@item M ? -@itemx ? -@kindex ? (Summary) -@kindex M ? (Summary) -@findex gnus-summary-mark-as-dormant -Mark the current article as dormant -(@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}. - -@item M d -@itemx d -@kindex M d (Summary) -@kindex d (Summary) -@findex gnus-summary-mark-as-read-forward -Mark the current article as read -(@code{gnus-summary-mark-as-read-forward}). - -@item D -@kindex D (Summary) -@findex gnus-summary-mark-as-read-backward -Mark the current article as read and move point to the previous line -(@code{gnus-summary-mark-as-read-backward}). - -@item M k -@itemx k -@kindex k (Summary) -@kindex M k (Summary) -@findex gnus-summary-kill-same-subject-and-select -Mark all articles that have the same subject as the current one as read, -and then select the next unread article -(@code{gnus-summary-kill-same-subject-and-select}). - -@item M K -@itemx C-k -@kindex M K (Summary) -@kindex C-k (Summary) -@findex gnus-summary-kill-same-subject -Mark all articles that have the same subject as the current one as read -(@code{gnus-summary-kill-same-subject}). - -@item M C -@kindex M C (Summary) -@findex gnus-summary-catchup -@c @icon{gnus-summary-catchup} -Mark all unread articles as read (@code{gnus-summary-catchup}). - -@item M C-c -@kindex M C-c (Summary) -@findex gnus-summary-catchup-all -Mark all articles in the group as read---even the ticked and dormant -articles (@code{gnus-summary-catchup-all}). - -@item M H -@kindex M H (Summary) -@findex gnus-summary-catchup-to-here -Catchup the current group to point (before the point) -(@code{gnus-summary-catchup-to-here}). - -@item M h -@kindex M h (Summary) -@findex gnus-summary-catchup-from-here -Catchup the current group from point (after the point) -(@code{gnus-summary-catchup-from-here}). - -@item C-w -@kindex C-w (Summary) -@findex gnus-summary-mark-region-as-read -Mark all articles between point and mark as read -(@code{gnus-summary-mark-region-as-read}). - -@item M V k -@kindex M V k (Summary) -@findex gnus-summary-kill-below -Kill all articles with scores below the default score (or below the -numeric prefix) (@code{gnus-summary-kill-below}). - -@item M e -@itemx E -@kindex M e (Summary) -@kindex E (Summary) -@findex gnus-summary-mark-as-expirable -Mark the current article as expirable -(@code{gnus-summary-mark-as-expirable}). - -@item M b -@kindex M b (Summary) -@findex gnus-summary-set-bookmark -Set a bookmark in the current article -(@code{gnus-summary-set-bookmark}). - -@item M B -@kindex M B (Summary) -@findex gnus-summary-remove-bookmark -Remove the bookmark from the current article -(@code{gnus-summary-remove-bookmark}). - -@item M V c -@kindex M V c (Summary) -@findex gnus-summary-clear-above -Clear all marks from articles with scores over the default score (or -over the numeric prefix) (@code{gnus-summary-clear-above}). - -@item M V u -@kindex M V u (Summary) -@findex gnus-summary-tick-above -Tick all articles with scores over the default score (or over the -numeric prefix) (@code{gnus-summary-tick-above}). - -@item M V m -@kindex M V m (Summary) -@findex gnus-summary-mark-above -Prompt for a mark, and mark all articles with scores over the default -score (or over the numeric prefix) with this mark -(@code{gnus-summary-clear-above}). -@end table - -@vindex gnus-summary-goto-unread -The @code{gnus-summary-goto-unread} variable controls what action should -be taken after setting a mark. If non-@code{nil}, point will move to -the next/previous unread article. If @code{nil}, point will just move -one line up or down. As a special case, if this variable is -@code{never}, all the marking commands as well as other commands (like -@kbd{SPACE}) will move to the next article, whether it is unread or not. -The default is @code{t}. - - -@node Generic Marking Commands -@subsection Generic Marking Commands - -Some people would like the command that ticks an article (@kbd{!}) to -go to the next article. Others would like it to go to the next unread -article. Yet others would like it to stay on the current article. -And even though I haven't heard of anybody wanting it to go to the -previous (unread) article, I'm sure there are people that want that as -well. - -Multiply these five behaviors with five different marking commands, and -you get a potentially complex set of variable to control what each -command should do. - -To sidestep that mess, Gnus provides commands that do all these -different things. They can be found on the @kbd{M M} map in the summary -buffer. Type @kbd{M M C-h} to see them all---there are too many of them -to list in this manual. - -While you can use these commands directly, most users would prefer -altering the summary mode keymap. For instance, if you would like the -@kbd{!} command to go to the next article instead of the next unread -article, you could say something like: - -@lisp -@group -(add-hook 'gnus-summary-mode-hook 'my-alter-summary-map) -(defun my-alter-summary-map () - (local-set-key "!" 'gnus-summary-put-mark-as-ticked-next)) -@end group -@end lisp - -@noindent -or - -@lisp -(defun my-alter-summary-map () - (local-set-key "!" "MM!n")) -@end lisp - - -@node Setting Process Marks -@subsection Setting Process Marks -@cindex setting process marks - -Process marks are displayed as @code{#} in the summary buffer, and are -used for marking articles in such a way that other commands will -process these articles. For instance, if you process mark four -articles and then use the @kbd{*} command, Gnus will enter these four -articles into the cache. For more information, -@pxref{Process/Prefix}. - -@table @kbd - -@item M P p -@itemx # -@kindex # (Summary) -@kindex M P p (Summary) -@findex gnus-summary-mark-as-processable -Mark the current article with the process mark -(@code{gnus-summary-mark-as-processable}). -@findex gnus-summary-unmark-as-processable - -@item M P u -@itemx M-# -@kindex M P u (Summary) -@kindex M-# (Summary) -Remove the process mark, if any, from the current article -(@code{gnus-summary-unmark-as-processable}). - -@item M P U -@kindex M P U (Summary) -@findex gnus-summary-unmark-all-processable -Remove the process mark from all articles -(@code{gnus-summary-unmark-all-processable}). - -@item M P i -@kindex M P i (Summary) -@findex gnus-uu-invert-processable -Invert the list of process marked articles -(@code{gnus-uu-invert-processable}). - -@item M P R -@kindex M P R (Summary) -@findex gnus-uu-mark-by-regexp -Mark articles that have a @code{Subject} header that matches a regular -expression (@code{gnus-uu-mark-by-regexp}). - -@item M P G -@kindex M P G (Summary) -@findex gnus-uu-unmark-by-regexp -Unmark articles that have a @code{Subject} header that matches a regular -expression (@code{gnus-uu-unmark-by-regexp}). - -@item M P r -@kindex M P r (Summary) -@findex gnus-uu-mark-region -Mark articles in region (@code{gnus-uu-mark-region}). - -@item M P g -@kindex M P g (Summary) -@findex gnus-uu-unmark-region -Unmark articles in region (@code{gnus-uu-unmark-region}). - -@item M P t -@kindex M P t (Summary) -@findex gnus-uu-mark-thread -Mark all articles in the current (sub)thread -(@code{gnus-uu-mark-thread}). - -@item M P T -@kindex M P T (Summary) -@findex gnus-uu-unmark-thread -Unmark all articles in the current (sub)thread -(@code{gnus-uu-unmark-thread}). - -@item M P v -@kindex M P v (Summary) -@findex gnus-uu-mark-over -Mark all articles that have a score above the prefix argument -(@code{gnus-uu-mark-over}). - -@item M P s -@kindex M P s (Summary) -@findex gnus-uu-mark-series -Mark all articles in the current series (@code{gnus-uu-mark-series}). - -@item M P S -@kindex M P S (Summary) -@findex gnus-uu-mark-sparse -Mark all series that have already had some articles marked -(@code{gnus-uu-mark-sparse}). - -@item M P a -@kindex M P a (Summary) -@findex gnus-uu-mark-all -Mark all articles in series order (@code{gnus-uu-mark-all}). - -@item M P b -@kindex M P b (Summary) -@findex gnus-uu-mark-buffer -Mark all articles in the buffer in the order they appear -(@code{gnus-uu-mark-buffer}). - -@item M P k -@kindex M P k (Summary) -@findex gnus-summary-kill-process-mark -Push the current process mark set onto the stack and unmark all articles -(@code{gnus-summary-kill-process-mark}). - -@item M P y -@kindex M P y (Summary) -@findex gnus-summary-yank-process-mark -Pop the previous process mark set from the stack and restore it -(@code{gnus-summary-yank-process-mark}). - -@item M P w -@kindex M P w (Summary) -@findex gnus-summary-save-process-mark -Push the current process mark set onto the stack -(@code{gnus-summary-save-process-mark}). - -@end table - -Also see the @kbd{&} command in @ref{Searching for Articles}, for how to -set process marks based on article body contents. - - -@node Limiting -@section Limiting -@cindex limiting - -It can be convenient to limit the summary buffer to just show some -subset of the articles currently in the group. The effect most limit -commands have is to remove a few (or many) articles from the summary -buffer. - -Limiting commands work on subsets of the articles already fetched from -the servers. These commands don't query the server for additional -articles. - -@table @kbd - -@item / / -@itemx / s -@kindex / / (Summary) -@findex gnus-summary-limit-to-subject -Limit the summary buffer to articles that match some subject -(@code{gnus-summary-limit-to-subject}). If given a prefix, exclude -matching articles. - -@item / a -@kindex / a (Summary) -@findex gnus-summary-limit-to-author -Limit the summary buffer to articles that match some author -(@code{gnus-summary-limit-to-author}). If given a prefix, exclude -matching articles. - -@item / R -@kindex / R (Summary) -@findex gnus-summary-limit-to-recipient -Limit the summary buffer to articles that match some recipient -(@code{gnus-summary-limit-to-recipient}). If given a prefix, exclude -matching articles. - -@item / A -@kindex / A (Summary) -@findex gnus-summary-limit-to-address -Limit the summary buffer to articles in which contents of From, To or Cc -header match a given address (@code{gnus-summary-limit-to-address}). If -given a prefix, exclude matching articles. - -@item / S -@kindex / S (Summary) -@findex gnus-summary-limit-to-singletons -Limit the summary buffer to articles that aren't part of any displayed -threads (@code{gnus-summary-limit-to-singletons}). If given a prefix, -limit to articles that are part of displayed threads. - -@item / x -@kindex / x (Summary) -@findex gnus-summary-limit-to-extra -Limit the summary buffer to articles that match one of the ``extra'' -headers (@pxref{To From Newsgroups}) -(@code{gnus-summary-limit-to-extra}). If given a prefix, exclude -matching articles. - -@item / u -@itemx x -@kindex / u (Summary) -@kindex x (Summary) -@findex gnus-summary-limit-to-unread -Limit the summary buffer to articles not marked as read -(@code{gnus-summary-limit-to-unread}). If given a prefix, limit the -buffer to articles strictly unread. This means that ticked and -dormant articles will also be excluded. - -@item / m -@kindex / m (Summary) -@findex gnus-summary-limit-to-marks -Ask for a mark and then limit to all articles that have been marked -with that mark (@code{gnus-summary-limit-to-marks}). - -@item / t -@kindex / t (Summary) -@findex gnus-summary-limit-to-age -Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days -(@code{gnus-summary-limit-to-age}). If given a prefix, limit to -articles younger than that number of days. - -@item / n -@kindex / n (Summary) -@findex gnus-summary-limit-to-articles -With prefix @samp{n}, limit the summary buffer to the next @samp{n} -articles. If not given a prefix, use the process marked articles -instead. (@code{gnus-summary-limit-to-articles}). - -@item / w -@kindex / w (Summary) -@findex gnus-summary-pop-limit -Pop the previous limit off the stack and restore it -(@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off -the stack. - -@item / . -@kindex / . (Summary) -@findex gnus-summary-limit-to-unseen -Limit the summary buffer to the unseen articles -(@code{gnus-summary-limit-to-unseen}). - -@item / v -@kindex / v (Summary) -@findex gnus-summary-limit-to-score -Limit the summary buffer to articles that have a score at or above some -score (@code{gnus-summary-limit-to-score}). - -@item / p -@kindex / p (Summary) -@findex gnus-summary-limit-to-display-predicate -Limit the summary buffer to articles that satisfy the @code{display} -group parameter predicate -(@code{gnus-summary-limit-to-display-predicate}). @xref{Group -Parameters}, for more on this predicate. - -@item / r -@kindex / r (Summary) -@findex gnus-summary-limit-to-replied -Limit the summary buffer to replied articles -(@code{gnus-summary-limit-to-replied}). If given a prefix, exclude -replied articles. - -@item / E -@itemx M S -@kindex M S (Summary) -@kindex / E (Summary) -@findex gnus-summary-limit-include-expunged -Include all expunged articles in the limit -(@code{gnus-summary-limit-include-expunged}). - -@item / D -@kindex / D (Summary) -@findex gnus-summary-limit-include-dormant -Include all dormant articles in the limit -(@code{gnus-summary-limit-include-dormant}). - -@item / * -@kindex / * (Summary) -@findex gnus-summary-limit-include-cached -Include all cached articles in the limit -(@code{gnus-summary-limit-include-cached}). - -@item / d -@kindex / d (Summary) -@findex gnus-summary-limit-exclude-dormant -Exclude all dormant articles from the limit -(@code{gnus-summary-limit-exclude-dormant}). - -@item / M -@kindex / M (Summary) -@findex gnus-summary-limit-exclude-marks -Exclude all marked articles (@code{gnus-summary-limit-exclude-marks}). - -@item / T -@kindex / T (Summary) -@findex gnus-summary-limit-include-thread -Include all the articles in the current thread in the limit. - -@item / c -@kindex / c (Summary) -@findex gnus-summary-limit-exclude-childless-dormant -Exclude all dormant articles that have no children from the limit@* -(@code{gnus-summary-limit-exclude-childless-dormant}). - -@item / C -@kindex / C (Summary) -@findex gnus-summary-limit-mark-excluded-as-read -Mark all excluded unread articles as read -(@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix, -also mark excluded ticked and dormant articles as read. - -@item / b -@kindex / b (Summary) -@findex gnus-summary-limit-to-bodies -Limit the summary buffer to articles that have bodies that match a -certain regexp (@code{gnus-summary-limit-to-bodies}). If given a -prefix, reverse the limit. This command is quite slow since it -requires selecting each article to find the matches. - -@item / h -@kindex / h (Summary) -@findex gnus-summary-limit-to-headers -Like the previous command, only limit to headers instead -(@code{gnus-summary-limit-to-headers}). - -@end table - - -The following commands aren't limiting commands, but use the @kbd{/} -prefix as well. - -@table @kbd -@item / N -@kindex / N (Summary) -@findex gnus-summary-insert-new-articles -Insert all new articles in the summary buffer. It scans for new emails -if @var{back-end}@code{-get-new-mail} is non-@code{nil}. - -@item / o -@kindex / o (Summary) -@findex gnus-summary-insert-old-articles -Insert all old articles in the summary buffer. If given a numbered -prefix, fetch this number of articles. - -@end table - - -@node Threading -@section Threading -@cindex threading -@cindex article threading - -Gnus threads articles by default. @dfn{To thread} is to put responses -to articles directly after the articles they respond to---in a -hierarchical fashion. - -Threading is done by looking at the @code{References} headers of the -articles. In a perfect world, this would be enough to build pretty -trees, but unfortunately, the @code{References} header is often broken -or simply missing. Weird news propagation exacerbates the problem, -so one has to employ other heuristics to get pleasing results. A -plethora of approaches exists, as detailed in horrible detail in -@ref{Customizing Threading}. - -First, a quick overview of the concepts: - -@table @dfn -@item root -The top-most article in a thread; the first article in the thread. - -@item thread -A tree-like article structure. - -@item sub-thread -A small(er) section of this tree-like structure. - -@item loose threads -Threads often lose their roots due to article expiry, or due to the root -already having been read in a previous session, and not displayed in the -summary buffer. We then typically have many sub-threads that really -belong to one thread, but are without connecting roots. These are -called loose threads. - -@item thread gathering -An attempt to gather loose threads into bigger threads. - -@item sparse threads -A thread where the missing articles have been ``guessed'' at, and are -displayed as empty lines in the summary buffer. - -@end table - - -@menu -* Customizing Threading:: Variables you can change to affect the threading. -* Thread Commands:: Thread based commands in the summary buffer. -@end menu - - -@node Customizing Threading -@subsection Customizing Threading -@cindex customizing threading - -@menu -* Loose Threads:: How Gnus gathers loose threads into bigger threads. -* Filling In Threads:: Making the threads displayed look fuller. -* More Threading:: Even more variables for fiddling with threads. -* Low-Level Threading:: You thought it was over@dots{} but you were wrong! -@end menu - - -@node Loose Threads -@subsubsection Loose Threads -@cindex < -@cindex > -@cindex loose threads - -@table @code -@item gnus-summary-make-false-root -@vindex gnus-summary-make-false-root -If non-@code{nil}, Gnus will gather all loose subtrees into one big tree -and create a dummy root at the top. (Wait a minute. Root at the top? -Yup.) Loose subtrees occur when the real root has expired, or you've -read or killed the root in a previous session. - -When there is no real root of a thread, Gnus will have to fudge -something. This variable says what fudging method Gnus should use. -There are four possible values: - -@iftex -@iflatex -\gnusfigure{The Summary Buffer}{390}{ -\put(0,0){\epsfig{figure=ps/summary-adopt,width=7.5cm}} -\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-empty,width=7.5cm}}} -\put(0,400){\makebox(0,0)[tl]{\epsfig{figure=ps/summary-none,width=7.5cm}}} -\put(445,400){\makebox(0,0)[tr]{\epsfig{figure=ps/summary-dummy,width=7.5cm}}} -} -@end iflatex -@end iftex - -@cindex adopting articles - -@table @code - -@item adopt -Gnus will make the first of the orphaned articles the parent. This -parent will adopt all the other articles. The adopted articles will be -marked as such by pointy brackets (@samp{<>}) instead of the standard -square brackets (@samp{[]}). This is the default method. - -@item dummy -@vindex gnus-summary-dummy-line-format -@vindex gnus-summary-make-false-root-always -Gnus will create a dummy summary line that will pretend to be the -parent. This dummy line does not correspond to any real article, so -selecting it will just select the first real article after the dummy -article. @code{gnus-summary-dummy-line-format} is used to specify the -format of the dummy roots. It accepts only one format spec: @samp{S}, -which is the subject of the article. @xref{Formatting Variables}. -If you want all threads to have a dummy root, even the non-gathered -ones, set @code{gnus-summary-make-false-root-always} to @code{t}. - -@item empty -Gnus won't actually make any article the parent, but simply leave the -subject field of all orphans except the first empty. (Actually, it will -use @code{gnus-summary-same-subject} as the subject (@pxref{Summary -Buffer Format}).) - -@item none -Don't make any article parent at all. Just gather the threads and -display them after one another. - -@item nil -Don't gather loose threads. -@end table - -@item gnus-summary-gather-subject-limit -@vindex gnus-summary-gather-subject-limit -Loose threads are gathered by comparing subjects of articles. If this -variable is @code{nil}, Gnus requires an exact match between the -subjects of the loose threads before gathering them into one big -super-thread. This might be too strict a requirement, what with the -presence of stupid newsreaders that chop off long subject lines. If -you think so, set this variable to, say, 20 to require that only the -first 20 characters of the subjects have to match. If you set this -variable to a really low number, you'll find that Gnus will gather -everything in sight into one thread, which isn't very helpful. - -@cindex fuzzy article gathering -If you set this variable to the special value @code{fuzzy}, Gnus will -use a fuzzy string comparison algorithm on the subjects (@pxref{Fuzzy -Matching}). - -@item gnus-simplify-subject-fuzzy-regexp -@vindex gnus-simplify-subject-fuzzy-regexp -This can either be a regular expression or list of regular expressions -that match strings that will be removed from subjects if fuzzy subject -simplification is used. - -@item gnus-simplify-ignored-prefixes -@vindex gnus-simplify-ignored-prefixes -If you set @code{gnus-summary-gather-subject-limit} to something as low -as 10, you might consider setting this variable to something sensible: - -@c Written by Michael Ernst -@lisp -(setq gnus-simplify-ignored-prefixes - (concat - "\\`\\[?\\(" - (mapconcat - 'identity - '("looking" - "wanted" "followup" "summary\\( of\\)?" - "help" "query" "problem" "question" - "answer" "reference" "announce" - "How can I" "How to" "Comparison of" - ;; ... - ) - "\\|") - "\\)\\s *\\(" - (mapconcat 'identity - '("for" "for reference" "with" "about") - "\\|") - "\\)?\\]?:?[ \t]*")) -@end lisp - -All words that match this regexp will be removed before comparing two -subjects. - -@item gnus-simplify-subject-functions -@vindex gnus-simplify-subject-functions -If non-@code{nil}, this variable overrides -@code{gnus-summary-gather-subject-limit}. This variable should be a -list of functions to apply to the @code{Subject} string iteratively to -arrive at the simplified version of the string. - -Useful functions to put in this list include: - -@table @code -@item gnus-simplify-subject-re -@findex gnus-simplify-subject-re -Strip the leading @samp{Re:}. - -@item gnus-simplify-subject-fuzzy -@findex gnus-simplify-subject-fuzzy -Simplify fuzzily. - -@item gnus-simplify-whitespace -@findex gnus-simplify-whitespace -Remove excessive whitespace. - -@item gnus-simplify-all-whitespace -@findex gnus-simplify-all-whitespace -Remove all whitespace. -@end table - -You may also write your own functions, of course. - - -@item gnus-summary-gather-exclude-subject -@vindex gnus-summary-gather-exclude-subject -Since loose thread gathering is done on subjects only, that might lead -to many false hits, especially with certain common subjects like -@samp{} and @samp{(none)}. To make the situation slightly better, -you can use the regexp @code{gnus-summary-gather-exclude-subject} to say -what subjects should be excluded from the gathering process.@* -The default is @samp{^ *$\\|^(none)$}. - -@item gnus-summary-thread-gathering-function -@vindex gnus-summary-thread-gathering-function -Gnus gathers threads by looking at @code{Subject} headers. This means -that totally unrelated articles may end up in the same ``thread'', which -is confusing. An alternate approach is to look at all the -@code{Message-ID}s in all the @code{References} headers to find matches. -This will ensure that no gathered threads ever include unrelated -articles, but it also means that people who have posted with broken -newsreaders won't be gathered properly. The choice is yours---plague or -cholera: - -@table @code -@item gnus-gather-threads-by-subject -@findex gnus-gather-threads-by-subject -This function is the default gathering function and looks at -@code{Subject}s exclusively. - -@item gnus-gather-threads-by-references -@findex gnus-gather-threads-by-references -This function looks at @code{References} headers exclusively. -@end table - -If you want to test gathering by @code{References}, you could say -something like: - -@lisp -(setq gnus-summary-thread-gathering-function - 'gnus-gather-threads-by-references) -@end lisp - -@end table - - -@node Filling In Threads -@subsubsection Filling In Threads - -@table @code -@item gnus-fetch-old-headers -@vindex gnus-fetch-old-headers -If non-@code{nil}, Gnus will attempt to build old threads by fetching -more old headers---headers to articles marked as read. If you would -like to display as few summary lines as possible, but still connect as -many loose threads as possible, you should set this variable to -@code{some} or a number. If you set it to a number, no more than that -number of extra old headers will be fetched. In either case, fetching -old headers only works if the back end you are using carries overview -files---this would normally be @code{nntp}, @code{nnspool}, -@code{nnml}, and @code{nnmaildir}. Also remember that if the root of -the thread has been expired by the server, there's not much Gnus can -do about that. - -This variable can also be set to @code{invisible}. This won't have any -visible effects, but is useful if you use the @kbd{A T} command a lot -(@pxref{Finding the Parent}). - -The server has to support @acronym{NOV} for any of this to work. - -@cindex Gmane, gnus-fetch-old-headers -This feature can seriously impact performance it ignores all locally -cached header entries. Setting it to @code{t} for groups for a server -that doesn't expire articles (such as news.gmane.org), leads to very -slow summary generation. - -@item gnus-fetch-old-ephemeral-headers -@vindex gnus-fetch-old-ephemeral-headers -Same as @code{gnus-fetch-old-headers}, but only used for ephemeral -newsgroups. - -@item gnus-build-sparse-threads -@vindex gnus-build-sparse-threads -Fetching old headers can be slow. A low-rent similar effect can be -gotten by setting this variable to @code{some}. Gnus will then look at -the complete @code{References} headers of all articles and try to string -together articles that belong in the same thread. This will leave -@dfn{gaps} in the threading display where Gnus guesses that an article -is missing from the thread. (These gaps appear like normal summary -lines. If you select a gap, Gnus will try to fetch the article in -question.) If this variable is @code{t}, Gnus will display all these -``gaps'' without regard for whether they are useful for completing the -thread or not. Finally, if this variable is @code{more}, Gnus won't cut -off sparse leaf nodes that don't lead anywhere. This variable is -@code{nil} by default. - -@item gnus-read-all-available-headers -@vindex gnus-read-all-available-headers -This is a rather obscure variable that few will find useful. It's -intended for those non-news newsgroups where the back end has to fetch -quite a lot to present the summary buffer, and where it's impossible to -go back to parents of articles. This is mostly the case in the -web-based groups. - -If you don't use those, then it's safe to leave this as the default -@code{nil}. If you want to use this variable, it should be a regexp -that matches the group name, or @code{t} for all groups. - -@end table - - -@node More Threading -@subsubsection More Threading - -@table @code -@item gnus-show-threads -@vindex gnus-show-threads -If this variable is @code{nil}, no threading will be done, and all of -the rest of the variables here will have no effect. Turning threading -off will speed group selection up a bit, but it is sure to make reading -slower and more awkward. - -@item gnus-thread-hide-subtree -@vindex gnus-thread-hide-subtree -If non-@code{nil}, all threads will be hidden when the summary buffer is -generated. - -This can also be a predicate specifier (@pxref{Predicate Specifiers}). -Available predicates are @code{gnus-article-unread-p} and -@code{gnus-article-unseen-p}. - -Here's an example: - -@lisp -(setq gnus-thread-hide-subtree - '(or gnus-article-unread-p - gnus-article-unseen-p)) -@end lisp - -(It's a pretty nonsensical example, since all unseen articles are also -unread, but you get my drift.) - - -@item gnus-thread-expunge-below -@vindex gnus-thread-expunge-below -All threads that have a total score (as defined by -@code{gnus-thread-score-function}) less than this number will be -expunged. This variable is @code{nil} by default, which means that no -threads are expunged. - -@item gnus-thread-hide-killed -@vindex gnus-thread-hide-killed -if you kill a thread and this variable is non-@code{nil}, the subtree -will be hidden. - -@item gnus-thread-ignore-subject -@vindex gnus-thread-ignore-subject -Sometimes somebody changes the subject in the middle of a thread. If -this variable is non-@code{nil}, which is the default, the subject -change is ignored. If it is @code{nil}, a change in the subject will -result in a new thread. - -@item gnus-thread-indent-level -@vindex gnus-thread-indent-level -This is a number that says how much each sub-thread should be indented. -The default is 4. - -@item gnus-sort-gathered-threads-function -@vindex gnus-sort-gathered-threads-function -Sometimes, particularly with mailing lists, the order in which mails -arrive locally is not necessarily the same as the order in which they -arrived on the mailing list. Consequently, when sorting sub-threads -using the default @code{gnus-thread-sort-by-number}, responses can end -up appearing before the article to which they are responding to. -Setting this variable to an alternate value -(e.g., @code{gnus-thread-sort-by-date}), in a group's parameters or in an -appropriate hook (e.g., @code{gnus-summary-generate-hook}) can produce a -more logical sub-thread ordering in such instances. - -@end table - - -@node Low-Level Threading -@subsubsection Low-Level Threading - -@table @code - -@item gnus-parse-headers-hook -@vindex gnus-parse-headers-hook -Hook run before parsing any headers. - -@item gnus-alter-header-function -@vindex gnus-alter-header-function -If non-@code{nil}, this function will be called to allow alteration of -article header structures. The function is called with one parameter, -the article header vector, which it may alter in any way. For instance, -if you have a mail-to-news gateway which alters the @code{Message-ID}s -in systematic ways (by adding prefixes and such), you can use this -variable to un-scramble the @code{Message-ID}s so that they are more -meaningful. Here's one example: - -@lisp -(setq gnus-alter-header-function 'my-alter-message-id) - -(defun my-alter-message-id (header) - (let ((id (mail-header-id header))) - (when (string-match - "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id) - (mail-header-set-id - (concat (match-string 1 id) "@@" (match-string 2 id)) - header)))) -@end lisp - -@end table - - -@node Thread Commands -@subsection Thread Commands -@cindex thread commands - -@table @kbd - -@item T k -@itemx C-M-k -@kindex T k (Summary) -@kindex C-M-k (Summary) -@findex gnus-summary-kill-thread -Mark all articles in the current (sub-)thread as read -(@code{gnus-summary-kill-thread}). If the prefix argument is positive, -remove all marks instead. If the prefix argument is negative, tick -articles instead. - -@item T l -@itemx C-M-l -@kindex T l (Summary) -@kindex C-M-l (Summary) -@findex gnus-summary-lower-thread -Lower the score of the current (sub-)thread -(@code{gnus-summary-lower-thread}). - -@item T i -@kindex T i (Summary) -@findex gnus-summary-raise-thread -Increase the score of the current (sub-)thread -(@code{gnus-summary-raise-thread}). - -@item T # -@kindex T # (Summary) -@findex gnus-uu-mark-thread -Set the process mark on the current (sub-)thread -(@code{gnus-uu-mark-thread}). - -@item T M-# -@kindex T M-# (Summary) -@findex gnus-uu-unmark-thread -Remove the process mark from the current (sub-)thread -(@code{gnus-uu-unmark-thread}). - -@item T T -@kindex T T (Summary) -@findex gnus-summary-toggle-threads -Toggle threading (@code{gnus-summary-toggle-threads}). - -@item T s -@kindex T s (Summary) -@findex gnus-summary-show-thread -Expose the (sub-)thread hidden under the current article, if any@* -(@code{gnus-summary-show-thread}). - -@item T h -@kindex T h (Summary) -@findex gnus-summary-hide-thread -Hide the current (sub-)thread (@code{gnus-summary-hide-thread}). - -@item T S -@kindex T S (Summary) -@findex gnus-summary-show-all-threads -Expose all hidden threads (@code{gnus-summary-show-all-threads}). - -@item T H -@kindex T H (Summary) -@findex gnus-summary-hide-all-threads -Hide all threads (@code{gnus-summary-hide-all-threads}). - -@item T t -@kindex T t (Summary) -@findex gnus-summary-rethread-current -Re-thread the current article's thread -(@code{gnus-summary-rethread-current}). This works even when the -summary buffer is otherwise unthreaded. - -@item T ^ -@kindex T ^ (Summary) -@findex gnus-summary-reparent-thread -Make the current article the child of the marked (or previous) article -(@code{gnus-summary-reparent-thread}). - -@item T M-^ -@kindex T M-^ (Summary) -@findex gnus-summary-reparent-children -Make the current article the parent of the marked articles -(@code{gnus-summary-reparent-children}). - -@end table - -The following commands are thread movement commands. They all -understand the numeric prefix. - -@table @kbd - -@item T n -@kindex T n (Summary) -@itemx C-M-f -@kindex C-M-n (Summary) -@itemx M-down -@kindex M-down (Summary) -@findex gnus-summary-next-thread -Go to the next thread (@code{gnus-summary-next-thread}). - -@item T p -@kindex T p (Summary) -@itemx C-M-b -@kindex C-M-p (Summary) -@itemx M-up -@kindex M-up (Summary) -@findex gnus-summary-prev-thread -Go to the previous thread (@code{gnus-summary-prev-thread}). - -@item T d -@kindex T d (Summary) -@findex gnus-summary-down-thread -Descend the thread (@code{gnus-summary-down-thread}). - -@item T u -@kindex T u (Summary) -@findex gnus-summary-up-thread -Ascend the thread (@code{gnus-summary-up-thread}). - -@item T o -@kindex T o (Summary) -@findex gnus-summary-top-thread -Go to the top of the thread (@code{gnus-summary-top-thread}). -@end table - -@vindex gnus-thread-operation-ignore-subject -If you ignore subject while threading, you'll naturally end up with -threads that have several different subjects in them. If you then issue -a command like @kbd{T k} (@code{gnus-summary-kill-thread}) you might not -wish to kill the entire thread, but just those parts of the thread that -have the same subject as the current article. If you like this idea, -you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it -is non-@code{nil} (which it is by default), subjects will be ignored -when doing thread commands. If this variable is @code{nil}, articles in -the same thread with different subjects will not be included in the -operation in question. If this variable is @code{fuzzy}, only articles -that have subjects fuzzily equal will be included (@pxref{Fuzzy -Matching}). - - -@node Sorting the Summary Buffer -@section Sorting the Summary Buffer - -@findex gnus-thread-sort-by-total-score -@findex gnus-thread-sort-by-date -@findex gnus-thread-sort-by-score -@findex gnus-thread-sort-by-subject -@findex gnus-thread-sort-by-author -@findex gnus-thread-sort-by-recipient -@findex gnus-thread-sort-by-number -@findex gnus-thread-sort-by-random -@vindex gnus-thread-sort-functions -@findex gnus-thread-sort-by-most-recent-number -@findex gnus-thread-sort-by-most-recent-date -If you are using a threaded summary display, you can sort the threads by -setting @code{gnus-thread-sort-functions}, which can be either a single -function, a list of functions, or a list containing functions and -@code{(not some-function)} elements. - -By default, sorting is done on article numbers. Ready-made sorting -predicate functions include @code{gnus-thread-sort-by-number}, -@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-recipient}, -@code{gnus-thread-sort-by-subject}, -@code{gnus-thread-sort-by-date}, -@code{gnus-thread-sort-by-score}, -@code{gnus-thread-sort-by-most-recent-number}, -@code{gnus-thread-sort-by-most-recent-date}, -@code{gnus-thread-sort-by-random} and -@code{gnus-thread-sort-by-total-score}. - -Each function takes two threads and returns non-@code{nil} if the first -thread should be sorted before the other. Note that sorting really is -normally done by looking only at the roots of each thread. Exceptions -to this rule are @code{gnus-thread-sort-by-most-recent-number} and -@code{gnus-thread-sort-by-most-recent-date}. - -If you use more than one function, the primary sort key should be the -last function in the list. You should probably always include -@code{gnus-thread-sort-by-number} in the list of sorting -functions---preferably first. This will ensure that threads that are -equal with respect to the other sort criteria will be displayed in -ascending article order. - -If you would like to sort by reverse score, then by subject, and finally -by number, you could do something like: - -@lisp -(setq gnus-thread-sort-functions - '(gnus-thread-sort-by-number - gnus-thread-sort-by-subject - (not gnus-thread-sort-by-total-score))) -@end lisp - -The threads that have highest score will be displayed first in the -summary buffer. When threads have the same score, they will be sorted -alphabetically. The threads that have the same score and the same -subject will be sorted by number, which is (normally) the sequence in -which the articles arrived. - -If you want to sort by score and then reverse arrival order, you could -say something like: - -@lisp -(setq gnus-thread-sort-functions - '((not gnus-thread-sort-by-number) - gnus-thread-sort-by-score)) -@end lisp - -By default, threads including their subthreads are sorted according to -the value of @code{gnus-thread-sort-functions}. By customizing -@code{gnus-subthread-sort-functions} you can define a custom sorting -order for subthreads. This allows for example to sort threads from -high score to low score in the summary buffer, but to have subthreads -still sorted chronologically from old to new without taking their -score into account. - -@vindex gnus-thread-score-function -The function in the @code{gnus-thread-score-function} variable (default -@code{+}) is used for calculating the total score of a thread. Useful -functions might be @code{max}, @code{min}, or squared means, or whatever -tickles your fancy. - -@findex gnus-article-sort-functions -@findex gnus-article-sort-by-date -@findex gnus-article-sort-by-most-recent-date -@findex gnus-article-sort-by-score -@findex gnus-article-sort-by-subject -@findex gnus-article-sort-by-author -@findex gnus-article-sort-by-random -@findex gnus-article-sort-by-number -@findex gnus-article-sort-by-most-recent-number -If you are using an unthreaded display for some strange reason or -other, you have to fiddle with the @code{gnus-article-sort-functions} -variable. It is very similar to the -@code{gnus-thread-sort-functions}, except that it uses slightly -different functions for article comparison. Available sorting -predicate functions are @code{gnus-article-sort-by-number}, -@code{gnus-article-sort-by-author}, -@code{gnus-article-sort-by-subject}, @code{gnus-article-sort-by-date}, -@code{gnus-article-sort-by-random}, and -@code{gnus-article-sort-by-score}. - -If you want to sort an unthreaded summary display by subject, you could -say something like: - -@lisp -(setq gnus-article-sort-functions - '(gnus-article-sort-by-number - gnus-article-sort-by-subject)) -@end lisp - -You can define group specific sorting via @code{gnus-parameters}, -@xref{Group Parameters}. - - -@node Asynchronous Fetching -@section Asynchronous Article Fetching -@cindex asynchronous article fetching -@cindex article pre-fetch -@cindex pre-fetch - -If you read your news from an @acronym{NNTP} server that's far away, the -network latencies may make reading articles a chore. You have to wait -for a while after pressing @kbd{n} to go to the next article before the -article appears. Why can't Gnus just go ahead and fetch the article -while you are reading the previous one? Why not, indeed. - -First, some caveats. There are some pitfalls to using asynchronous -article fetching, especially the way Gnus does it. - -Let's say you are reading article 1, which is short, and article 2 is -quite long, and you are not interested in reading that. Gnus does not -know this, so it goes ahead and fetches article 2. You decide to read -article 3, but since Gnus is in the process of fetching article 2, the -connection is blocked. - -To avoid these situations, Gnus will open two (count 'em two) -connections to the server. Some people may think this isn't a very nice -thing to do, but I don't see any real alternatives. Setting up that -extra connection takes some time, so Gnus startup will be slower. - -Gnus will fetch more articles than you will read. This will mean that -the link between your machine and the @acronym{NNTP} server will become more -loaded than if you didn't use article pre-fetch. The server itself will -also become more loaded---both with the extra article requests, and the -extra connection. - -Ok, so now you know that you shouldn't really use this thing@dots{} unless -you really want to. - -@vindex gnus-asynchronous -Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should -happen automatically. - -@vindex gnus-use-article-prefetch -You can control how many articles are to be pre-fetched by setting -@code{gnus-use-article-prefetch}. This is 30 by default, which means -that when you read an article in the group, the back end will pre-fetch -the next 30 articles. If this variable is @code{t}, the back end will -pre-fetch all the articles it can without bound. If it is -@code{nil}, no pre-fetching will be done. - -@vindex gnus-async-prefetch-article-p -@findex gnus-async-unread-p -There are probably some articles that you don't want to pre-fetch---read -articles, for instance. The @code{gnus-async-prefetch-article-p} -variable controls whether an article is to be pre-fetched. This -function should return non-@code{nil} when the article in question is -to be pre-fetched. The default is @code{gnus-async-unread-p}, which -returns @code{nil} on read articles. The function is called with an -article data structure as the only parameter. - -If, for instance, you wish to pre-fetch only unread articles shorter -than 100 lines, you could say something like: - -@lisp -(defun my-async-short-unread-p (data) - "Return non-nil for short, unread articles." - (and (gnus-data-unread-p data) - (< (mail-header-lines (gnus-data-header data)) - 100))) - -(setq gnus-async-prefetch-article-p 'my-async-short-unread-p) -@end lisp - -These functions will be called many, many times, so they should -preferably be short and sweet to avoid slowing down Gnus too much. -It's probably a good idea to byte-compile things like this. - -@vindex gnus-async-post-fetch-function -@findex gnus-html-prefetch-images -After an article has been prefetched, this -@code{gnus-async-post-fetch-function} will be called. The buffer will -be narrowed to the region of the article that was fetched. A useful -value would be @code{gnus-html-prefetch-images}, which will prefetch -and store images referenced in the article, so that you don't have to -wait for them to be fetched when you read the article. This is useful -for @acronym{HTML} messages that have external images. - -@vindex gnus-prefetched-article-deletion-strategy -Articles have to be removed from the asynch buffer sooner or later. The -@code{gnus-prefetched-article-deletion-strategy} says when to remove -articles. This is a list that may contain the following elements: - -@table @code -@item read -Remove articles when they are read. - -@item exit -Remove articles when exiting the group. -@end table - -The default value is @code{(read exit)}. - -@c @vindex gnus-use-header-prefetch -@c If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles -@c from the next group. - - -@node Article Caching -@section Article Caching -@cindex article caching -@cindex caching - -If you have an @emph{extremely} slow @acronym{NNTP} connection, you may -consider turning article caching on. Each article will then be stored -locally under your home directory. As you may surmise, this could -potentially use @emph{huge} amounts of disk space, as well as eat up all -your inodes so fast it will make your head swim. In vodka. - -Used carefully, though, it could be just an easier way to save articles. - -@vindex gnus-use-long-file-name -@vindex gnus-cache-directory -@vindex gnus-use-cache -To turn caching on, set @code{gnus-use-cache} to @code{t}. By default, -all articles ticked or marked as dormant will then be copied -over to your local cache (@code{gnus-cache-directory}). Whether this -cache is flat or hierarchical is controlled by the -@code{gnus-use-long-file-name} variable, as usual. - -When re-selecting a ticked or dormant article, it will be fetched from the -cache instead of from the server. As articles in your cache will never -expire, this might serve as a method of saving articles while still -keeping them where they belong. Just mark all articles you want to save -as dormant, and don't worry. - -When an article is marked as read, is it removed from the cache. - -@vindex gnus-cache-remove-articles -@vindex gnus-cache-enter-articles -The entering/removal of articles from the cache is controlled by the -@code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles} -variables. Both are lists of symbols. The first is @code{(ticked -dormant)} by default, meaning that ticked and dormant articles will be -put in the cache. The latter is @code{(read)} by default, meaning that -articles marked as read are removed from the cache. Possibly -symbols in these two lists are @code{ticked}, @code{dormant}, -@code{unread} and @code{read}. - -@findex gnus-jog-cache -So where does the massive article-fetching and storing come into the -picture? The @code{gnus-jog-cache} command will go through all -subscribed newsgroups, request all unread articles, score them, and -store them in the cache. You should only ever, ever ever ever, use this -command if 1) your connection to the @acronym{NNTP} server is really, really, -really slow and 2) you have a really, really, really huge disk. -Seriously. One way to cut down on the number of articles downloaded is -to score unwanted articles down and have them marked as read. They will -not then be downloaded by this command. - -@vindex gnus-uncacheable-groups -@vindex gnus-cacheable-groups -It is likely that you do not want caching on all groups. For instance, -if your @code{nnml} mail is located under your home directory, it makes no -sense to cache it somewhere else under your home directory. Unless you -feel that it's neat to use twice as much space. - -To limit the caching, you could set @code{gnus-cacheable-groups} to a -regexp of groups to cache, @samp{^nntp} for instance, or set the -@code{gnus-uncacheable-groups} regexp to @samp{^nnml}, for instance. -Both variables are @code{nil} by default. If a group matches both -variables, the group is not cached. - -@findex gnus-cache-generate-nov-databases -@findex gnus-cache-generate-active -@vindex gnus-cache-active-file -The cache stores information on what articles it contains in its active -file (@code{gnus-cache-active-file}). If this file (or any other parts -of the cache) becomes all messed up for some reason or other, Gnus -offers two functions that will try to set things right. @kbd{M-x -gnus-cache-generate-nov-databases} will (re)build all the @acronym{NOV} -files, and @kbd{gnus-cache-generate-active} will (re)generate the active -file. - -@findex gnus-cache-move-cache -@code{gnus-cache-move-cache} will move your whole -@code{gnus-cache-directory} to some other location. You get asked to -where, isn't that cool? - -@node Persistent Articles -@section Persistent Articles -@cindex persistent articles - -Closely related to article caching, we have @dfn{persistent articles}. -In fact, it's just a different way of looking at caching, and much more -useful in my opinion. - -Say you're reading a newsgroup, and you happen on to some valuable gem -that you want to keep and treasure forever. You'd normally just save it -(using one of the many saving commands) in some file. The problem with -that is that it's just, well, yucky. Ideally you'd prefer just having -the article remain in the group where you found it forever; untouched by -the expiry going on at the news server. - -This is what a @dfn{persistent article} is---an article that just won't -be deleted. It's implemented using the normal cache functions, but -you use two explicit commands for managing persistent articles: - -@table @kbd - -@item * -@kindex * (Summary) -@findex gnus-cache-enter-article -Make the current article persistent (@code{gnus-cache-enter-article}). - -@item M-* -@kindex M-* (Summary) -@findex gnus-cache-remove-article -Remove the current article from the persistent articles -(@code{gnus-cache-remove-article}). This will normally delete the -article. -@end table - -Both these commands understand the process/prefix convention. - -To avoid having all ticked articles (and stuff) entered into the cache, -you should set @code{gnus-use-cache} to @code{passive} if you're just -interested in persistent articles: - -@lisp -(setq gnus-use-cache 'passive) -@end lisp - -@node Sticky Articles -@section Sticky Articles -@cindex sticky articles - -When you select an article the current article buffer will be reused -according to the value of the variable -@code{gnus-single-article-buffer}. If its value is non-@code{nil} (the -default) all articles reuse the same article buffer. Else each group -has its own article buffer. - -This implies that it's not possible to have more than one article buffer -in a group at a time. But sometimes you might want to display all the -latest emails from your mother, your father, your aunt, your uncle and -your 17 cousins to coordinate the next Christmas party. - -That's where sticky articles come in handy. A sticky article buffer -basically is a normal article buffer, but it won't be reused when you -select another article. You can make an article sticky with: - -@table @kbd -@item A S -@kindex A S (Summary) -@findex gnus-sticky-article -Make the current article sticky. If a prefix arg is given, ask for a -name for this sticky article buffer. -@end table - -To close a sticky article buffer you can use these commands: - -@table @kbd -@item q -@kindex q (Article) -@findex bury-buffer -Puts this sticky article buffer at the end of the list of all buffers. - -@item k -@kindex k (Article) -@findex gnus-kill-sticky-article-buffer -Kills this sticky article buffer. -@end table - -To kill all sticky article buffers you can use: - -@defun gnus-kill-sticky-article-buffers ARG -Kill all sticky article buffers. -If a prefix ARG is given, ask for confirmation. -@end defun - -@node Article Backlog -@section Article Backlog -@cindex backlog -@cindex article backlog - -If you have a slow connection, but the idea of using caching seems -unappealing to you (and it is, really), you can help the situation some -by switching on the @dfn{backlog}. This is where Gnus will buffer -already read articles so that it doesn't have to re-fetch articles -you've already read. This only helps if you are in the habit of -re-selecting articles you've recently read, of course. If you never do -that, turning the backlog on will slow Gnus down a little bit, and -increase memory usage some. - -@vindex gnus-keep-backlog -If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store -at most @var{n} old articles in a buffer for later re-fetching. If this -variable is non-@code{nil} and is not a number, Gnus will store -@emph{all} read articles, which means that your Emacs will grow without -bound before exploding and taking your machine down with you. I put -that in there just to keep y'all on your toes. - -The default value is 20. - - -@node Saving Articles -@section Saving Articles -@cindex saving articles - -Gnus can save articles in a number of ways. Below is the documentation -for saving articles in a fairly straight-forward fashion (i.e., little -processing of the article is done before it is saved). For a different -approach (uudecoding, unsharing) you should use @code{gnus-uu} -(@pxref{Decoding Articles}). - -For the commands listed here, the target is a file. If you want to -save to a group, see the @kbd{B c} (@code{gnus-summary-copy-article}) -command (@pxref{Mail Group Commands}). - -@vindex gnus-save-all-headers -If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete -unwanted headers before saving the article. - -@vindex gnus-saved-headers -If the preceding variable is @code{nil}, all headers that match the -@code{gnus-saved-headers} regexp will be kept, while the rest will be -deleted before saving. - -@table @kbd - -@item O o -@itemx o -@kindex O o (Summary) -@kindex o (Summary) -@findex gnus-summary-save-article -@c @icon{gnus-summary-save-article} -Save the current article using the default article saver -(@code{gnus-summary-save-article}). - -@item O m -@kindex O m (Summary) -@findex gnus-summary-save-article-mail -Save the current article in a Unix mail box (mbox) file -(@code{gnus-summary-save-article-mail}). - -@item O r -@kindex O r (Summary) -@findex gnus-summary-save-article-rmail -Save the current article in Rmail format -(@code{gnus-summary-save-article-rmail}). This is mbox since Emacs 23, -Babyl in older versions. - -@item O f -@kindex O f (Summary) -@findex gnus-summary-save-article-file -@c @icon{gnus-summary-save-article-file} -Save the current article in plain file format -(@code{gnus-summary-save-article-file}). - -@item O F -@kindex O F (Summary) -@findex gnus-summary-write-article-file -Write the current article in plain file format, overwriting any previous -file contents (@code{gnus-summary-write-article-file}). - -@item O b -@kindex O b (Summary) -@findex gnus-summary-save-article-body-file -Save the current article body in plain file format -(@code{gnus-summary-save-article-body-file}). - -@item O h -@kindex O h (Summary) -@findex gnus-summary-save-article-folder -Save the current article in mh folder format -(@code{gnus-summary-save-article-folder}). - -@item O v -@kindex O v (Summary) -@findex gnus-summary-save-article-vm -Save the current article in a VM folder -(@code{gnus-summary-save-article-vm}). - -@item O p -@itemx | -@kindex O p (Summary) -@kindex | (Summary) -@findex gnus-summary-pipe-output -@vindex gnus-summary-pipe-output-default-command -Save the current article in a pipe. Uhm, like, what I mean is---Pipe -the current article to a process (@code{gnus-summary-pipe-output}). -If given a symbolic prefix (@pxref{Symbolic Prefixes}), include the -complete headers in the piped output. The symbolic prefix @code{r} is -special; it lets this command pipe a raw article including all headers. -The @code{gnus-summary-pipe-output-default-command} variable can be set -to a string containing the default command and options (default -@code{nil}). - -@item O P -@kindex O P (Summary) -@findex gnus-summary-muttprint -@vindex gnus-summary-muttprint-program -Save the current article into muttprint. That is, print it using the -external program @uref{http://muttprint.sourceforge.net/, -Muttprint}. The program name and options to use is controlled by the -variable @code{gnus-summary-muttprint-program}. -(@code{gnus-summary-muttprint}). - -@end table - -@vindex gnus-prompt-before-saving -All these commands use the process/prefix convention -(@pxref{Process/Prefix}). If you save bunches of articles using these -functions, you might get tired of being prompted for files to save each -and every article in. The prompting action is controlled by -the @code{gnus-prompt-before-saving} variable, which is @code{always} by -default, giving you that excessive prompting action you know and -loathe. If you set this variable to @code{t} instead, you'll be prompted -just once for each series of articles you save. If you like to really -have Gnus do all your thinking for you, you can even set this variable -to @code{nil}, which means that you will never be prompted for files to -save articles in. Gnus will simply save all the articles in the default -files. - - -@vindex gnus-default-article-saver -You can customize the @code{gnus-default-article-saver} variable to make -Gnus do what you want it to. You can use any of the eight ready-made -functions below, or you can create your own. - -@table @code - -@item gnus-summary-save-in-rmail -@findex gnus-summary-save-in-rmail -@vindex gnus-rmail-save-name -@findex gnus-plain-save-name -This is the default format, that used by the Rmail package. Since Emacs -23, Rmail uses standard mbox format. Before this, it used the -@dfn{Babyl} format. Accordingly, this command writes mbox format since -Emacs 23, unless appending to an existing Babyl file. In older versions -of Emacs, it always uses Babyl format. Uses the function in the -@code{gnus-rmail-save-name} variable to get a file name to save the -article in. The default is @code{gnus-plain-save-name}. - -@item gnus-summary-save-in-mail -@findex gnus-summary-save-in-mail -@vindex gnus-mail-save-name -Save in a Unix mail (mbox) file. Uses the function in the -@code{gnus-mail-save-name} variable to get a file name to save the -article in. The default is @code{gnus-plain-save-name}. - -@item gnus-summary-save-in-file -@findex gnus-summary-save-in-file -@vindex gnus-file-save-name -@findex gnus-numeric-save-name -Append the article straight to an ordinary file. Uses the function in -the @code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-write-to-file -@findex gnus-summary-write-to-file -Write the article straight to an ordinary file. The file is -overwritten if it exists. Uses the function in the -@code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-save-body-in-file -@findex gnus-summary-save-body-in-file -Append the article body to an ordinary file. Uses the function in the -@code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-write-body-to-file -@findex gnus-summary-write-body-to-file -Write the article body straight to an ordinary file. The file is -overwritten if it exists. Uses the function in the -@code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-save-in-folder -@findex gnus-summary-save-in-folder -@findex gnus-folder-save-name -@findex gnus-Folder-save-name -@vindex gnus-folder-save-name -@cindex rcvstore -@cindex MH folders -Save the article to an MH folder using @code{rcvstore} from the MH -library. Uses the function in the @code{gnus-folder-save-name} variable -to get a file name to save the article in. The default is -@code{gnus-folder-save-name}, but you can also use -@code{gnus-Folder-save-name}, which creates capitalized names. - -@item gnus-summary-save-in-vm -@findex gnus-summary-save-in-vm -Save the article in a VM folder. You have to have the VM mail -reader to use this setting. - -@item gnus-summary-save-in-pipe -@findex gnus-summary-save-in-pipe -Pipe the article to a shell command. This function takes optional two -arguments COMMAND and RAW@. Valid values for COMMAND include: - -@itemize @bullet -@item a string@* -The executable command name and possibly arguments. -@item @code{nil}@* -You will be prompted for the command in the minibuffer. -@item the symbol @code{default}@* -It will be replaced with the command which the variable -@code{gnus-summary-pipe-output-default-command} holds or the command -last used for saving. -@end itemize - -Non-@code{nil} value for RAW overrides @code{:decode} and -@code{:headers} properties (see below) and the raw article including all -headers will be piped. -@end table - -The symbol of each function may have the following properties: - -@table @code -@item :decode -The value non-@code{nil} means save decoded articles. This is -meaningful only with @code{gnus-summary-save-in-file}, -@code{gnus-summary-save-body-in-file}, -@code{gnus-summary-write-to-file}, -@code{gnus-summary-write-body-to-file}, and -@code{gnus-summary-save-in-pipe}. - -@item :function -The value specifies an alternative function which appends, not -overwrites, articles to a file. This implies that when saving many -articles at a time, @code{gnus-prompt-before-saving} is bound to -@code{t} and all articles are saved in a single file. This is -meaningful only with @code{gnus-summary-write-to-file} and -@code{gnus-summary-write-body-to-file}. - -@item :headers -The value specifies the symbol of a variable of which the value -specifies headers to be saved. If it is omitted, -@code{gnus-save-all-headers} and @code{gnus-saved-headers} control what -headers should be saved. -@end table - -@vindex gnus-article-save-directory -All of these functions, except for the last one, will save the article -in the @code{gnus-article-save-directory}, which is initialized from the -@env{SAVEDIR} environment variable. This is @file{~/News/} by -default. - -As you can see above, the functions use different functions to find a -suitable name of a file to save the article in. Below is a list of -available functions that generate names: - -@table @code - -@item gnus-Numeric-save-name -@findex gnus-Numeric-save-name -File names like @file{~/News/Alt.andrea-dworkin/45}. - -@item gnus-numeric-save-name -@findex gnus-numeric-save-name -File names like @file{~/News/alt.andrea-dworkin/45}. - -@item gnus-Plain-save-name -@findex gnus-Plain-save-name -File names like @file{~/News/Alt.andrea-dworkin}. - -@item gnus-plain-save-name -@findex gnus-plain-save-name -File names like @file{~/News/alt.andrea-dworkin}. - -@item gnus-sender-save-name -@findex gnus-sender-save-name -File names like @file{~/News/larsi}. -@end table - -@vindex gnus-split-methods -You can have Gnus suggest where to save articles by plonking a regexp into -the @code{gnus-split-methods} alist. For instance, if you would like to -save articles related to Gnus in the file @file{gnus-stuff}, and articles -related to VM in @file{vm-stuff}, you could set this variable to something -like: - -@lisp -(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff") - ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff") - (my-choosing-function "../other-dir/my-stuff") - ((equal gnus-newsgroup-name "mail.misc") "mail-stuff")) -@end lisp - -We see that this is a list where each element is a list that has two -elements---the @dfn{match} and the @dfn{file}. The match can either be -a string (in which case it is used as a regexp to match on the article -head); it can be a symbol (which will be called as a function with the -group name as a parameter); or it can be a list (which will be -@code{eval}ed). If any of these actions have a non-@code{nil} result, -the @dfn{file} will be used as a default prompt. In addition, the -result of the operation itself will be used if the function or form -called returns a string or a list of strings. - -You basically end up with a list of file names that might be used when -saving the current article. (All ``matches'' will be used.) You will -then be prompted for what you really want to use as a name, with file -name completion over the results from applying this variable. - -This variable is @code{((gnus-article-archive-name))} by default, which -means that Gnus will look at the articles it saves for an -@code{Archive-name} line and use that as a suggestion for the file -name. - -Here's an example function to clean up file names somewhat. If you have -lots of mail groups called things like -@samp{nnml:mail.whatever}, you may want to chop off the beginning of -these group names before creating the file name to save to. The -following will do just that: - -@lisp -(defun my-save-name (group) - (when (string-match "^nnml:mail." group) - (substring group (match-end 0)))) - -(setq gnus-split-methods - '((gnus-article-archive-name) - (my-save-name))) -@end lisp - - -@vindex gnus-use-long-file-name -Finally, you have the @code{gnus-use-long-file-name} variable. If it is -@code{nil}, all the preceding functions will replace all periods -(@samp{.}) in the group names with slashes (@samp{/})---which means that -the functions will generate hierarchies of directories instead of having -all the files in the top level directory -(@file{~/News/alt/andrea-dworkin} instead of -@file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default -on most systems. However, for historical reasons, this is @code{nil} on -Xenix and usg-unix-v machines by default. - -This function also affects kill and score file names. If this variable -is a list, and the list contains the element @code{not-score}, long file -names will not be used for score files, if it contains the element -@code{not-save}, long file names will not be used for saving, and if it -contains the element @code{not-kill}, long file names will not be used -for kill files. - -If you'd like to save articles in a hierarchy that looks something like -a spool, you could - -@lisp -(setq gnus-use-long-file-name '(not-save)) ; @r{to get a hierarchy} -(setq gnus-default-article-saver - 'gnus-summary-save-in-file) ; @r{no encoding} -@end lisp - -Then just save with @kbd{o}. You'd then read this hierarchy with -ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and -the top level directory as the argument (@file{~/News/}). Then just walk -around to the groups/directories with @code{nneething}. - - -@node Decoding Articles -@section Decoding Articles -@cindex decoding articles - -Sometime users post articles (or series of articles) that have been -encoded in some way or other. Gnus can decode them for you. - -@menu -* Uuencoded Articles:: Uudecode articles. -* Shell Archives:: Unshar articles. -* PostScript Files:: Split PostScript. -* Other Files:: Plain save and binhex. -* Decoding Variables:: Variables for a happy decoding. -* Viewing Files:: You want to look at the result of the decoding? -@end menu - -@cindex series -@cindex article series -All these functions use the process/prefix convention -(@pxref{Process/Prefix}) for finding out what articles to work on, with -the extension that a ``single article'' means ``a single series''. Gnus -can find out by itself what articles belong to a series, decode all the -articles and unpack/view/save the resulting file(s). - -Gnus guesses what articles are in the series according to the following -simplish rule: The subjects must be (nearly) identical, except for the -last two numbers of the line. (Spaces are largely ignored, however.) - -For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus -will find all the articles that match the regexp @samp{^cat.gif -([0-9]+/[0-9]+).*$}. - -Subjects that are non-standard, like @samp{cat.gif (2/3) Part 6 of a -series}, will not be properly recognized by any of the automatic viewing -commands, and you have to mark the articles manually with @kbd{#}. - - -@node Uuencoded Articles -@subsection Uuencoded Articles -@cindex uudecode -@cindex uuencoded articles - -@table @kbd - -@item X u -@kindex X u (Summary) -@findex gnus-uu-decode-uu -@c @icon{gnus-uu-decode-uu} -Uudecodes the current series (@code{gnus-uu-decode-uu}). - -@item X U -@kindex X U (Summary) -@findex gnus-uu-decode-uu-and-save -Uudecodes and saves the current series -(@code{gnus-uu-decode-uu-and-save}). - -@item X v u -@kindex X v u (Summary) -@findex gnus-uu-decode-uu-view -Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}). - -@item X v U -@kindex X v U (Summary) -@findex gnus-uu-decode-uu-and-save-view -Uudecodes, views and saves the current series -(@code{gnus-uu-decode-uu-and-save-view}). - -@end table - -Remember that these all react to the presence of articles marked with -the process mark. If, for instance, you'd like to decode and save an -entire newsgroup, you'd typically do @kbd{M P a} -(@code{gnus-uu-mark-all}) and then @kbd{X U} -(@code{gnus-uu-decode-uu-and-save}). - -All this is very much different from how @code{gnus-uu} worked with -@sc{gnus 4.1}, where you had explicit keystrokes for everything under -the sun. This version of @code{gnus-uu} generally assumes that you mark -articles in some way (@pxref{Setting Process Marks}) and then press -@kbd{X u}. - -@vindex gnus-uu-notify-files -Note: When trying to decode articles that have names matching -@code{gnus-uu-notify-files}, which is hard-coded to -@samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will -automatically post an article on @samp{comp.unix.wizards} saying that -you have just viewed the file in question. This feature can't be turned -off. - - -@node Shell Archives -@subsection Shell Archives -@cindex unshar -@cindex shell archives -@cindex shared articles - -Shell archives (``shar files'') used to be a popular way to distribute -sources, but it isn't used all that much today. In any case, we have -some commands to deal with these: - -@table @kbd - -@item X s -@kindex X s (Summary) -@findex gnus-uu-decode-unshar -Unshars the current series (@code{gnus-uu-decode-unshar}). - -@item X S -@kindex X S (Summary) -@findex gnus-uu-decode-unshar-and-save -Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}). - -@item X v s -@kindex X v s (Summary) -@findex gnus-uu-decode-unshar-view -Unshars and views the current series (@code{gnus-uu-decode-unshar-view}). - -@item X v S -@kindex X v S (Summary) -@findex gnus-uu-decode-unshar-and-save-view -Unshars, views and saves the current series -(@code{gnus-uu-decode-unshar-and-save-view}). -@end table - - -@node PostScript Files -@subsection PostScript Files -@cindex PostScript - -@table @kbd - -@item X p -@kindex X p (Summary) -@findex gnus-uu-decode-postscript -Unpack the current PostScript series (@code{gnus-uu-decode-postscript}). - -@item X P -@kindex X P (Summary) -@findex gnus-uu-decode-postscript-and-save -Unpack and save the current PostScript series -(@code{gnus-uu-decode-postscript-and-save}). - -@item X v p -@kindex X v p (Summary) -@findex gnus-uu-decode-postscript-view -View the current PostScript series -(@code{gnus-uu-decode-postscript-view}). - -@item X v P -@kindex X v P (Summary) -@findex gnus-uu-decode-postscript-and-save-view -View and save the current PostScript series -(@code{gnus-uu-decode-postscript-and-save-view}). -@end table - - -@node Other Files -@subsection Other Files - -@table @kbd -@item X o -@kindex X o (Summary) -@findex gnus-uu-decode-save -Save the current series -(@code{gnus-uu-decode-save}). - -@item X b -@kindex X b (Summary) -@findex gnus-uu-decode-binhex -Unbinhex the current series (@code{gnus-uu-decode-binhex}). This -doesn't really work yet. - -@item X Y -@kindex X Y (Summary) -@findex gnus-uu-decode-yenc -yEnc-decode the current series and save it (@code{gnus-uu-decode-yenc}). -@end table - - -@node Decoding Variables -@subsection Decoding Variables - -Adjective, not verb. - -@menu -* Rule Variables:: Variables that say how a file is to be viewed. -* Other Decode Variables:: Other decode variables. -* Uuencoding and Posting:: Variables for customizing uuencoding. -@end menu - - -@node Rule Variables -@subsubsection Rule Variables -@cindex rule variables - -Gnus uses @dfn{rule variables} to decide how to view a file. All these -variables are of the form - -@lisp - (list '(regexp1 command2) - '(regexp2 command2) - ...) -@end lisp - -@table @code - -@item gnus-uu-user-view-rules -@vindex gnus-uu-user-view-rules -@cindex sox -This variable is consulted first when viewing files. If you wish to use, -for instance, @code{sox} to convert an @file{.au} sound file, you could -say something like: -@lisp -(setq gnus-uu-user-view-rules - (list '("\\\\.au$" "sox %s -t .aiff > /dev/audio"))) -@end lisp - -@item gnus-uu-user-view-rules-end -@vindex gnus-uu-user-view-rules-end -This variable is consulted if Gnus couldn't make any matches from the -user and default view rules. - -@item gnus-uu-user-archive-rules -@vindex gnus-uu-user-archive-rules -This variable can be used to say what commands should be used to unpack -archives. -@end table - - -@node Other Decode Variables -@subsubsection Other Decode Variables - -@table @code -@vindex gnus-uu-grabbed-file-functions - -@item gnus-uu-grabbed-file-functions -All functions in this list will be called right after each file has been -successfully decoded---so that you can move or view files right away, -and don't have to wait for all files to be decoded before you can do -anything. Ready-made functions you can put in this list are: - -@table @code - -@item gnus-uu-grab-view -@findex gnus-uu-grab-view -View the file. - -@item gnus-uu-grab-move -@findex gnus-uu-grab-move -Move the file (if you're using a saving function.) -@end table - -@item gnus-uu-be-dangerous -@vindex gnus-uu-be-dangerous -Specifies what to do if unusual situations arise during decoding. If -@code{nil}, be as conservative as possible. If @code{t}, ignore things -that didn't work, and overwrite existing files. Otherwise, ask each -time. - -@item gnus-uu-ignore-files-by-name -@vindex gnus-uu-ignore-files-by-name -Files with name matching this regular expression won't be viewed. - -@item gnus-uu-ignore-files-by-type -@vindex gnus-uu-ignore-files-by-type -Files with a @acronym{MIME} type matching this variable won't be viewed. -Note that Gnus tries to guess what type the file is based on the name. -@code{gnus-uu} is not a @acronym{MIME} package (yet), so this is slightly -kludgy. - -@item gnus-uu-tmp-dir -@vindex gnus-uu-tmp-dir -Where @code{gnus-uu} does its work. - -@item gnus-uu-do-not-unpack-archives -@vindex gnus-uu-do-not-unpack-archives -Non-@code{nil} means that @code{gnus-uu} won't peek inside archives -looking for files to display. - -@item gnus-uu-view-and-save -@vindex gnus-uu-view-and-save -Non-@code{nil} means that the user will always be asked to save a file -after viewing it. - -@item gnus-uu-ignore-default-view-rules -@vindex gnus-uu-ignore-default-view-rules -Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing -rules. - -@item gnus-uu-ignore-default-archive-rules -@vindex gnus-uu-ignore-default-archive-rules -Non-@code{nil} means that @code{gnus-uu} will ignore the default archive -unpacking commands. - -@item gnus-uu-kill-carriage-return -@vindex gnus-uu-kill-carriage-return -Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns -from articles. - -@item gnus-uu-unmark-articles-not-decoded -@vindex gnus-uu-unmark-articles-not-decoded -Non-@code{nil} means that @code{gnus-uu} will mark unsuccessfully -decoded articles as unread. - -@item gnus-uu-correct-stripped-uucode -@vindex gnus-uu-correct-stripped-uucode -Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix -uuencoded files that have had trailing spaces deleted. - -@item gnus-uu-pre-uudecode-hook -@vindex gnus-uu-pre-uudecode-hook -Hook run before sending a message to @code{uudecode}. - -@item gnus-uu-view-with-metamail -@vindex gnus-uu-view-with-metamail -@cindex metamail -Non-@code{nil} means that @code{gnus-uu} will ignore the viewing -commands defined by the rule variables and just fudge a @acronym{MIME} -content type based on the file name. The result will be fed to -@code{metamail} for viewing. - -@item gnus-uu-save-in-digest -@vindex gnus-uu-save-in-digest -Non-@code{nil} means that @code{gnus-uu}, when asked to save without -decoding, will save in digests. If this variable is @code{nil}, -@code{gnus-uu} will just save everything in a file without any -embellishments. The digesting almost conforms to RFC 1153---no easy way -to specify any meaningful volume and issue numbers were found, so I -simply dropped them. - -@end table - - -@node Uuencoding and Posting -@subsubsection Uuencoding and Posting - -@table @code - -@item gnus-uu-post-include-before-composing -@vindex gnus-uu-post-include-before-composing -Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode -before you compose the article. If this variable is @code{t}, you can -either include an encoded file with @kbd{C-c C-i} or have one included -for you when you post the article. - -@item gnus-uu-post-length -@vindex gnus-uu-post-length -Maximum length of an article. The encoded file will be split into how -many articles it takes to post the entire file. - -@item gnus-uu-post-threaded -@vindex gnus-uu-post-threaded -Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a -thread. This may not be smart, as no other decoder I have seen is able -to follow threads when collecting uuencoded articles. (Well, I have -seen one package that does that---@code{gnus-uu}, but somehow, I don't -think that counts@dots{}) Default is @code{nil}. - -@item gnus-uu-post-separate-description -@vindex gnus-uu-post-separate-description -Non-@code{nil} means that the description will be posted in a separate -article. The first article will typically be numbered (0/x). If this -variable is @code{nil}, the description the user enters will be included -at the beginning of the first article, which will be numbered (1/x). -Default is @code{t}. - -@end table - - -@node Viewing Files -@subsection Viewing Files -@cindex viewing files -@cindex pseudo-articles - -After decoding, if the file is some sort of archive, Gnus will attempt -to unpack the archive and see if any of the files in the archive can be -viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz} -containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will -uncompress and de-tar the main file, and then view the two pictures. -This unpacking process is recursive, so if the archive contains archives -of archives, it'll all be unpacked. - -Finally, Gnus will normally insert a @dfn{pseudo-article} for each -extracted file into the summary buffer. If you go to these -``articles'', you will be prompted for a command to run (usually Gnus -will make a suggestion), and then the command will be run. - -@vindex gnus-view-pseudo-asynchronously -If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait -until the viewing is done before proceeding. - -@vindex gnus-view-pseudos -If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert -the pseudo-articles into the summary buffer, but view them -immediately. If this variable is @code{not-confirm}, the user won't even -be asked for a confirmation before viewing is done. - -@vindex gnus-view-pseudos-separately -If @code{gnus-view-pseudos-separately} is non-@code{nil}, one -pseudo-article will be created for each file to be viewed. If -@code{nil}, all files that use the same viewing command will be given as -a list of parameters to that command. - -@vindex gnus-insert-pseudo-articles -If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert -pseudo-articles when decoding. It is @code{t} by default. - -So; there you are, reading your @emph{pseudo-articles} in your -@emph{virtual newsgroup} from the @emph{virtual server}; and you think: -Why isn't anything real anymore? How did we get here? - - -@node Article Treatment -@section Article Treatment - -Reading through this huge manual, you may have quite forgotten that the -object of newsreaders is to actually, like, read what people have -written. Reading articles. Unfortunately, people are quite bad at -writing, so there are tons of functions and variables to make reading -these articles easier. - -@menu -* Article Highlighting:: You want to make the article look like fruit salad. -* Article Fontisizing:: Making emphasized text look nice. -* Article Hiding:: You also want to make certain info go away. -* Article Washing:: Lots of way-neat functions to make life better. -* Article Header:: Doing various header transformations. -* Article Buttons:: Click on URLs, Message-IDs, addresses and the like. -* Article Button Levels:: Controlling appearance of buttons. -* Article Date:: Grumble, UT! -* Article Display:: Display various stuff: - X-Face, Picons, Gravatars, Smileys. -* Article Signature:: What is a signature? -* Article Miscellanea:: Various other stuff. -@end menu - - -@node Article Highlighting -@subsection Article Highlighting -@cindex highlighting - -Not only do you want your article buffer to look like fruit salad, but -you want it to look like technicolor fruit salad. - -@table @kbd - -@item W H a -@kindex W H a (Summary) -@findex gnus-article-highlight -@findex gnus-article-maybe-highlight -Do much highlighting of the current article -(@code{gnus-article-highlight}). This function highlights header, cited -text, the signature, and adds buttons to the body and the head. - -@item W H h -@kindex W H h (Summary) -@findex gnus-article-highlight-headers -@vindex gnus-header-face-alist -Highlight the headers (@code{gnus-article-highlight-headers}). The -highlighting will be done according to the @code{gnus-header-face-alist} -variable, which is a list where each element has the form -@code{(@var{regexp} @var{name} @var{content})}. -@var{regexp} is a regular expression for matching the -header, @var{name} is the face used for highlighting the header name -(@pxref{Faces and Fonts}) and @var{content} is the face for highlighting -the header value. The first match made will be used. Note that -@var{regexp} shouldn't have @samp{^} prepended---Gnus will add one. - -@item W H c -@kindex W H c (Summary) -@findex gnus-article-highlight-citation -Highlight cited text (@code{gnus-article-highlight-citation}). - -Some variables to customize the citation highlights: - -@table @code -@vindex gnus-cite-parse-max-size - -@item gnus-cite-parse-max-size -If the article size in bytes is bigger than this variable (which is -25000 by default), no citation highlighting will be performed. - -@item gnus-cite-max-prefix -@vindex gnus-cite-max-prefix -Maximum possible length for a citation prefix (default 20). - -@item gnus-cite-face-list -@vindex gnus-cite-face-list -List of faces used for highlighting citations (@pxref{Faces and Fonts}). -When there are citations from multiple articles in the same message, -Gnus will try to give each citation from each article its own face. -This should make it easier to see who wrote what. - -@item gnus-supercite-regexp -@vindex gnus-supercite-regexp -Regexp matching normal Supercite attribution lines. - -@item gnus-supercite-secondary-regexp -@vindex gnus-supercite-secondary-regexp -Regexp matching mangled Supercite attribution lines. - -@item gnus-cite-minimum-match-count -@vindex gnus-cite-minimum-match-count -Minimum number of identical prefixes we have to see before we believe -that it's a citation. - -@item gnus-cite-attribution-prefix -@vindex gnus-cite-attribution-prefix -Regexp matching the beginning of an attribution line. - -@item gnus-cite-attribution-suffix -@vindex gnus-cite-attribution-suffix -Regexp matching the end of an attribution line. - -@item gnus-cite-attribution-face -@vindex gnus-cite-attribution-face -Face used for attribution lines. It is merged with the face for the -cited text belonging to the attribution. - -@item gnus-cite-ignore-quoted-from -@vindex gnus-cite-ignore-quoted-from -If non-@code{nil}, no citation highlighting will be performed on lines -beginning with @samp{>From }. Those lines may have been quoted by MTAs -in order not to mix up with the envelope From line. The default value -is @code{t}. - -@end table - - -@item W H s -@kindex W H s (Summary) -@vindex gnus-signature-separator -@vindex gnus-signature-face -@findex gnus-article-highlight-signature -Highlight the signature (@code{gnus-article-highlight-signature}). -Everything after @code{gnus-signature-separator} (@pxref{Article -Signature}) in an article will be considered a signature and will be -highlighted with @code{gnus-signature-face}, which is @code{italic} by -default. - -@end table - -@xref{Customizing Articles}, for how to highlight articles automatically. - - -@node Article Fontisizing -@subsection Article Fontisizing -@cindex emphasis -@cindex article emphasis - -@findex gnus-article-emphasize -@kindex W e (Summary) -People commonly add emphasis to words in news articles by writing things -like @samp{_this_} or @samp{*this*} or @samp{/this/}. Gnus can make -this look nicer by running the article through the @kbd{W e} -(@code{gnus-article-emphasize}) command. - -@vindex gnus-emphasis-alist -How the emphasis is computed is controlled by the -@code{gnus-emphasis-alist} variable. This is an alist where the first -element is a regular expression to be matched. The second is a number -that says what regular expression grouping is used to find the entire -emphasized word. The third is a number that says what regexp grouping -should be displayed and highlighted. (The text between these two -groupings will be hidden.) The fourth is the face used for -highlighting. - -@lisp -(setq gnus-emphasis-alist - '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline) - ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold))) -@end lisp - -@cindex slash -@cindex asterisk -@cindex underline -@cindex / -@cindex * - -@vindex gnus-emphasis-underline -@vindex gnus-emphasis-bold -@vindex gnus-emphasis-italic -@vindex gnus-emphasis-underline-bold -@vindex gnus-emphasis-underline-italic -@vindex gnus-emphasis-bold-italic -@vindex gnus-emphasis-underline-bold-italic -By default, there are seven rules, and they use the following faces: -@code{gnus-emphasis-bold}, @code{gnus-emphasis-italic}, -@code{gnus-emphasis-underline}, @code{gnus-emphasis-bold-italic}, -@code{gnus-emphasis-underline-italic}, -@code{gnus-emphasis-underline-bold}, and -@code{gnus-emphasis-underline-bold-italic}. - -If you want to change these faces, you can either use @kbd{M-x -customize}, or you can use @code{copy-face}. For instance, if you want -to make @code{gnus-emphasis-italic} use a red face instead, you could -say something like: - -@lisp -(copy-face 'red 'gnus-emphasis-italic) -@end lisp - -@vindex gnus-group-highlight-words-alist - -If you want to highlight arbitrary words, you can use the -@code{gnus-group-highlight-words-alist} variable, which uses the same -syntax as @code{gnus-emphasis-alist}. The @code{highlight-words} group -parameter (@pxref{Group Parameters}) can also be used. - -@xref{Customizing Articles}, for how to fontize articles automatically. - - -@node Article Hiding -@subsection Article Hiding -@cindex article hiding - -Or rather, hiding certain things in each article. There usually is much -too much cruft in most articles. - -@table @kbd - -@item W W a -@kindex W W a (Summary) -@findex gnus-article-hide -Do quite a lot of hiding on the article buffer -(@kbd{gnus-article-hide}). In particular, this function will hide -headers, @acronym{PGP}, cited text and the signature. - -@item W W h -@kindex W W h (Summary) -@findex gnus-article-hide-headers -Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding -Headers}. - -@item W W b -@kindex W W b (Summary) -@findex gnus-article-hide-boring-headers -Hide headers that aren't particularly interesting -(@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}. - -@item W W s -@kindex W W s (Summary) -@findex gnus-article-hide-signature -Hide signature (@code{gnus-article-hide-signature}). @xref{Article -Signature}. - -@item W W l -@kindex W W l (Summary) -@findex gnus-article-hide-list-identifiers -@vindex gnus-list-identifiers -Strip list identifiers specified in @code{gnus-list-identifiers}. These -are strings some mailing list servers add to the beginning of all -@code{Subject} headers---for example, @samp{[zebra 4711]}. Any leading -@samp{Re: } is skipped before stripping. @code{gnus-list-identifiers} -may not contain @code{\\(..\\)}. - -@table @code - -@item gnus-list-identifiers -@vindex gnus-list-identifiers -A regular expression that matches list identifiers to be removed from -subject. This can also be a list of regular expressions. - -@end table - -@item W W P -@kindex W W P (Summary) -@findex gnus-article-hide-pem -Hide @acronym{PEM} (privacy enhanced messages) cruft -(@code{gnus-article-hide-pem}). - -@item W W B -@kindex W W B (Summary) -@findex gnus-article-strip-banner -@vindex gnus-article-banner-alist -@vindex gnus-article-address-banner-alist -@cindex banner -@cindex OneList -@cindex stripping advertisements -@cindex advertisements -Strip the banner specified by the @code{banner} group parameter -(@code{gnus-article-strip-banner}). This is mainly used to hide those -annoying banners and/or signatures that some mailing lists and moderated -groups adds to all the messages. The way to use this function is to add -the @code{banner} group parameter (@pxref{Group Parameters}) to the -group you want banners stripped from. The parameter either be a string, -which will be interpreted as a regular expression matching text to be -removed, or the symbol @code{signature}, meaning that the (last) -signature should be removed, or other symbol, meaning that the -corresponding regular expression in @code{gnus-article-banner-alist} is -used. - -For instance: - -@lisp -(setq gnus-article-banner-alist - ((googleGroups . - "^\n*--~--~---------\\(.+\n\\)+"))) -@end lisp - -Regardless of a group, you can hide things like advertisements only when -the sender of an article has a certain mail address specified in -@code{gnus-article-address-banner-alist}. - -@table @code - -@item gnus-article-address-banner-alist -@vindex gnus-article-address-banner-alist -Alist of mail addresses and banners. Each element has the form -@code{(@var{address} . @var{banner})}, where @var{address} is a regexp -matching a mail address in the From header, @var{banner} is one of a -symbol @code{signature}, an item in @code{gnus-article-banner-alist}, -a regexp and @code{nil}. If @var{address} matches author's mail -address, it will remove things like advertisements. For example, if a -sender has the mail address @samp{hail@@yoo-hoo.co.jp} and there is a -banner something like @samp{Do You Yoo-hoo!?} in all articles he -sends, you can use the following element to remove them: - -@lisp -("@@yoo-hoo\\.co\\.jp\\'" . - "\n_+\nDo You Yoo-hoo!\\?\n.*\n.*\n") -@end lisp - -@end table - -@item W W c -@kindex W W c (Summary) -@findex gnus-article-hide-citation -Hide citation (@code{gnus-article-hide-citation}). Some variables for -customizing the hiding: - -@table @code - -@item gnus-cited-opened-text-button-line-format -@itemx gnus-cited-closed-text-button-line-format -@vindex gnus-cited-closed-text-button-line-format -@vindex gnus-cited-opened-text-button-line-format -Gnus adds buttons to show where the cited text has been hidden, and to -allow toggle hiding the text. The format of the variable is specified -by these format-like variable (@pxref{Formatting Variables}). These -specs are valid: - -@table @samp -@item b -Starting point of the hidden text. -@item e -Ending point of the hidden text. -@item l -Number of characters in the hidden region. -@item n -Number of lines of hidden text. -@end table - -@item gnus-cited-lines-visible -@vindex gnus-cited-lines-visible -The number of lines at the beginning of the cited text to leave -shown. This can also be a cons cell with the number of lines at the top -and bottom of the text, respectively, to remain visible. - -@end table - -@item W W C-c -@kindex W W C-c (Summary) -@findex gnus-article-hide-citation-maybe - -Hide citation (@code{gnus-article-hide-citation-maybe}) depending on the -following two variables: - -@table @code -@item gnus-cite-hide-percentage -@vindex gnus-cite-hide-percentage -If the cited text is of a bigger percentage than this variable (default -50), hide the cited text. - -@item gnus-cite-hide-absolute -@vindex gnus-cite-hide-absolute -The cited text must have at least this length (default 10) before it -is hidden. -@end table - -@item W W C -@kindex W W C (Summary) -@findex gnus-article-hide-citation-in-followups -Hide cited text in articles that aren't roots -(@code{gnus-article-hide-citation-in-followups}). This isn't very -useful as an interactive command, but might be a handy function to stick -have happen automatically (@pxref{Customizing Articles}). - -@end table - -All these ``hiding'' commands are toggles, but if you give a negative -prefix to these commands, they will show what they have previously -hidden. If you give a positive prefix, they will always hide. - -Also @pxref{Article Highlighting} for further variables for -citation customization. - -@xref{Customizing Articles}, for how to hide article elements -automatically. - - -@node Article Washing -@subsection Article Washing -@cindex washing -@cindex article washing - -We call this ``article washing'' for a really good reason. Namely, the -@kbd{A} key was taken, so we had to use the @kbd{W} key instead. - -@dfn{Washing} is defined by us as ``changing something from something to -something else'', but normally results in something looking better. -Cleaner, perhaps. - -@xref{Customizing Articles}, if you want to change how Gnus displays -articles by default. - -@table @kbd - -@item C-u g -This is not really washing, it's sort of the opposite of washing. If -you type this, you see the article exactly as it exists on disk or on -the server. - -@item g -Force redisplaying of the current article -(@code{gnus-summary-show-article}). This is also not really washing. -If you type this, you see the article without any previously applied -interactive Washing functions but with all default treatments -(@pxref{Customizing Articles}). - -@item W l -@kindex W l (Summary) -@findex gnus-summary-stop-page-breaking -Remove page breaks from the current article -(@code{gnus-summary-stop-page-breaking}). @xref{Misc Article}, for page -delimiters. - -@item W r -@kindex W r (Summary) -@findex gnus-summary-caesar-message -@c @icon{gnus-summary-caesar-message} -Do a Caesar rotate (rot13) on the article buffer -(@code{gnus-summary-caesar-message}). -Unreadable articles that tell you to read them with Caesar rotate or rot13. -(Typically offensive jokes and such.) - -It's commonly called ``rot13'' because each letter is rotated 13 -positions in the alphabet, e.g., @samp{B} (letter #2) -> @samp{O} (letter -#15). It is sometimes referred to as ``Caesar rotate'' because Caesar -is rumored to have employed this form of, uh, somewhat weak encryption. - -@item W m -@kindex W m (Summary) -@findex gnus-summary-morse-message -Morse decode the article buffer (@code{gnus-summary-morse-message}). - -@item W i -@kindex W i (Summary) -@findex gnus-summary-idna-message -Decode IDNA encoded domain names in the current articles. IDNA -encoded domain names looks like @samp{xn--bar}. If a string remain -unencoded after running invoking this, it is likely an invalid IDNA -string (@samp{xn--bar} is invalid). You must have GNU Libidn -(@url{http://www.gnu.org/software/libidn/}) installed for this command -to work. - -@item W t -@item t -@kindex W t (Summary) -@kindex t (Summary) -@findex gnus-summary-toggle-header -Toggle whether to display all headers in the article buffer -(@code{gnus-summary-toggle-header}). - -@item W v -@kindex W v (Summary) -@findex gnus-summary-verbose-headers -Toggle whether to display all headers in the article buffer permanently -(@code{gnus-summary-verbose-headers}). - -@item W o -@kindex W o (Summary) -@findex gnus-article-treat-overstrike -Treat overstrike (@code{gnus-article-treat-overstrike}). - -@item W d -@kindex W d (Summary) -@findex gnus-article-treat-dumbquotes -@vindex gnus-article-dumbquotes-map -@cindex Smartquotes -@cindex M****s*** sm*rtq**t*s -@cindex Latin 1 -Treat M****s*** sm*rtq**t*s according to -@code{gnus-article-dumbquotes-map} -(@code{gnus-article-treat-dumbquotes}). Note that this function guesses -whether a character is a sm*rtq**t* or not, so it should only be used -interactively. - -Sm*rtq**t*s are M****s***'s unilateral extension to the character map in -an attempt to provide more quoting characters. If you see something -like @code{\222} or @code{\264} where you're expecting some kind of -apostrophe or quotation mark, then try this wash. - -@item W U -@kindex W U (Summary) -@findex gnus-article-treat-non-ascii -@cindex Unicode -@cindex Non-@acronym{ASCII} -Translate many non-@acronym{ASCII} characters into their -@acronym{ASCII} equivalents (@code{gnus-article-treat-non-ascii}). -This is mostly useful if you're on a terminal that has a limited font -and doesn't show accented characters, ``advanced'' punctuation, and the -like. For instance, @samp{»} is translated into @samp{>>}, and so on. - -@item W Y f -@kindex W Y f (Summary) -@findex gnus-article-outlook-deuglify-article -@cindex Outlook Express -Full deuglify of broken Outlook (Express) articles: Treat dumbquotes, -unwrap lines, repair attribution and rearrange citation. -(@code{gnus-article-outlook-deuglify-article}). - -@item W Y u -@kindex W Y u (Summary) -@findex gnus-article-outlook-unwrap-lines -@vindex gnus-outlook-deuglify-unwrap-min -@vindex gnus-outlook-deuglify-unwrap-max -Unwrap lines that appear to be wrapped citation lines. You can control -what lines will be unwrapped by frobbing -@code{gnus-outlook-deuglify-unwrap-min} and -@code{gnus-outlook-deuglify-unwrap-max}, indicating the minimum and -maximum length of an unwrapped citation line. -(@code{gnus-article-outlook-unwrap-lines}). - -@item W Y a -@kindex W Y a (Summary) -@findex gnus-article-outlook-repair-attribution -Repair a broken attribution line.@* -(@code{gnus-article-outlook-repair-attribution}). - -@item W Y c -@kindex W Y c (Summary) -@findex gnus-article-outlook-rearrange-citation -Repair broken citations by rearranging the text. -(@code{gnus-article-outlook-rearrange-citation}). - -@item W w -@kindex W w (Summary) -@findex gnus-article-fill-cited-article -Do word wrap (@code{gnus-article-fill-cited-article}). - -You can give the command a numerical prefix to specify the width to use -when filling. - -@item W Q -@kindex W Q (Summary) -@findex gnus-article-fill-long-lines -Fill long lines (@code{gnus-article-fill-long-lines}). - -@item W C -@kindex W C (Summary) -@findex gnus-article-capitalize-sentences -Capitalize the first word in each sentence -(@code{gnus-article-capitalize-sentences}). - -@item W c -@kindex W c (Summary) -@findex gnus-article-remove-cr -Translate CRLF pairs (i.e., @samp{^M}s on the end of the lines) into LF -(this takes care of DOS line endings), and then translate any remaining -CRs into LF (this takes care of Mac line endings) -(@code{gnus-article-remove-cr}). - -@item W q -@kindex W q (Summary) -@findex gnus-article-de-quoted-unreadable -Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}). -Quoted-Printable is one common @acronym{MIME} encoding employed when -sending non-@acronym{ASCII} (i.e., 8-bit) articles. It typically -makes strings like @samp{d@'ej@`a vu} look like @samp{d=E9j=E0 vu}, -which doesn't look very readable to me. Note that this is usually -done automatically by Gnus if the message in question has a -@code{Content-Transfer-Encoding} header that says that this encoding -has been done. If a prefix is given, a charset will be asked for. - -@item W 6 -@kindex W 6 (Summary) -@findex gnus-article-de-base64-unreadable -Treat base64 (@code{gnus-article-de-base64-unreadable}). Base64 is -one common @acronym{MIME} encoding employed when sending -non-@acronym{ASCII} (i.e., 8-bit) articles. Note that this is -usually done automatically by Gnus if the message in question has a -@code{Content-Transfer-Encoding} header that says that this encoding -has been done. If a prefix is given, a charset will be asked for. - -@item W Z -@kindex W Z (Summary) -@findex gnus-article-decode-HZ -Treat HZ or HZP (@code{gnus-article-decode-HZ}). HZ (or HZP) is one -common encoding employed when sending Chinese articles. It typically -makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}. - -@item W A -@kindex W A (Summary) -@findex gnus-article-treat-ansi-sequences -@cindex @acronym{ANSI} control sequences -Translate @acronym{ANSI} SGR control sequences into overlays or -extents (@code{gnus-article-treat-ansi-sequences}). @acronym{ANSI} -sequences are used in some Chinese hierarchies for highlighting. - -@item W u -@kindex W u (Summary) -@findex gnus-article-unsplit-urls -Remove newlines from within URLs. Some mailers insert newlines into -outgoing email messages to keep lines short. This reformatting can -split long URLs onto multiple lines. Repair those URLs by removing -the newlines (@code{gnus-article-unsplit-urls}). - -@item W h -@kindex W h (Summary) -@findex gnus-article-wash-html -Treat @acronym{HTML} (@code{gnus-article-wash-html}). Note that this is -usually done automatically by Gnus if the message in question has a -@code{Content-Type} header that says that the message is @acronym{HTML}. - -If a prefix is given, a charset will be asked for. If it is a number, -the charset defined in @code{gnus-summary-show-article-charset-alist} -(@pxref{Paging the Article}) will be used. - -The default is to use the function specified by -@code{mm-text-html-renderer} (@pxref{Display Customization, ,Display -Customization, emacs-mime, The Emacs MIME Manual}) to convert the -@acronym{HTML}. Pre-defined functions you can use include: - -@table @code -@item shr -Use Gnus simple html renderer. - -@item gnus-w3m -Use Gnus rendered based on w3m. - -@item w3 -Use Emacs/W3. - -@item w3m -Use @uref{http://emacs-w3m.namazu.org/, emacs-w3m}. - -@item w3m-standalone -Use @uref{http://w3m.sourceforge.net/, w3m}. - -@item links -Use @uref{http://links.sf.net/, Links}. - -@item lynx -Use @uref{http://lynx.isc.org/, Lynx}. - -@item html2text -Use html2text---a simple @acronym{HTML} converter included with Gnus. - -@end table - -@item W b -@kindex W b (Summary) -@findex gnus-article-add-buttons -Add clickable buttons to the article (@code{gnus-article-add-buttons}). -@xref{Article Buttons}. - -@item W B -@kindex W B (Summary) -@findex gnus-article-add-buttons-to-head -Add clickable buttons to the article headers -(@code{gnus-article-add-buttons-to-head}). - -@item W p -@kindex W p (Summary) -@findex gnus-article-verify-x-pgp-sig -Verify a signed control message -(@code{gnus-article-verify-x-pgp-sig}). Control messages such as -@code{newgroup} and @code{checkgroups} are usually signed by the -hierarchy maintainer. You need to add the @acronym{PGP} public key of -the maintainer to your keyring to verify the -message.@footnote{@acronym{PGP} keys for many hierarchies are -available at @uref{ftp://ftp.isc.org/pub/pgpcontrol/README.html}} - -@item W s -@kindex W s (Summary) -@findex gnus-summary-force-verify-and-decrypt -Verify a signed (@acronym{PGP}, @acronym{PGP/MIME} or -@acronym{S/MIME}) message -(@code{gnus-summary-force-verify-and-decrypt}). @xref{Security}. - -@item W a -@kindex W a (Summary) -@findex gnus-article-strip-headers-in-body -Strip headers like the @code{X-No-Archive} header from the beginning of -article bodies (@code{gnus-article-strip-headers-in-body}). - -@item W E l -@kindex W E l (Summary) -@findex gnus-article-strip-leading-blank-lines -Remove all blank lines from the beginning of the article -(@code{gnus-article-strip-leading-blank-lines}). - -@item W E m -@kindex W E m (Summary) -@findex gnus-article-strip-multiple-blank-lines -Replace all blank lines with empty lines and then all multiple empty -lines with a single empty line. -(@code{gnus-article-strip-multiple-blank-lines}). - -@item W E t -@kindex W E t (Summary) -@findex gnus-article-remove-trailing-blank-lines -Remove all blank lines at the end of the article -(@code{gnus-article-remove-trailing-blank-lines}). - -@item W E a -@kindex W E a (Summary) -@findex gnus-article-strip-blank-lines -Do all the three commands above -(@code{gnus-article-strip-blank-lines}). - -@item W E A -@kindex W E A (Summary) -@findex gnus-article-strip-all-blank-lines -Remove all blank lines -(@code{gnus-article-strip-all-blank-lines}). - -@item W E s -@kindex W E s (Summary) -@findex gnus-article-strip-leading-space -Remove all white space from the beginning of all lines of the article -body (@code{gnus-article-strip-leading-space}). - -@item W E e -@kindex W E e (Summary) -@findex gnus-article-strip-trailing-space -Remove all white space from the end of all lines of the article -body (@code{gnus-article-strip-trailing-space}). - -@end table - -@xref{Customizing Articles}, for how to wash articles automatically. - - -@node Article Header -@subsection Article Header - -These commands perform various transformations of article header. - -@table @kbd - -@item W G u -@kindex W G u (Summary) -@findex gnus-article-treat-unfold-headers -Unfold folded header lines (@code{gnus-article-treat-unfold-headers}). - -@item W G n -@kindex W G n (Summary) -@findex gnus-article-treat-fold-newsgroups -Fold the @code{Newsgroups} and @code{Followup-To} headers -(@code{gnus-article-treat-fold-newsgroups}). - -@item W G f -@kindex W G f (Summary) -@findex gnus-article-treat-fold-headers -Fold all the message headers -(@code{gnus-article-treat-fold-headers}). - -@item W E w -@kindex W E w (Summary) -@findex gnus-article-remove-leading-whitespace -Remove excessive whitespace from all headers -(@code{gnus-article-remove-leading-whitespace}). - -@end table - - -@node Article Buttons -@subsection Article Buttons -@cindex buttons - -People often include references to other stuff in articles, and it would -be nice if Gnus could just fetch whatever it is that people talk about -with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse -button on these references. - -@vindex gnus-button-man-handler -Gnus adds @dfn{buttons} to certain standard references by default: -Well-formed URLs, mail addresses, Message-IDs, Info links, man pages and -Emacs or Gnus related references. This is controlled by two variables, -one that handles article bodies and one that handles article heads: - -@table @code - -@item gnus-button-alist -@vindex gnus-button-alist -This is an alist where each entry has this form: - -@lisp -(@var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par}) -@end lisp - -@table @var - -@item regexp -All text that match this regular expression (case insensitive) will be -considered an external reference. Here's a typical regexp that matches -embedded URLs: @samp{]*\\)>}. This can also be a -variable containing a regexp, useful variables to use include -@code{gnus-button-url-regexp} and @code{gnus-button-mid-or-mail-regexp}. - -@item button-par -Gnus has to know which parts of the matches is to be highlighted. This -is a number that says what sub-expression of the regexp is to be -highlighted. If you want it all highlighted, you use 0 here. - -@item use-p -This form will be @code{eval}ed, and if the result is non-@code{nil}, -this is considered a match. This is useful if you want extra sifting to -avoid false matches. Often variables named -@code{gnus-button-@var{*}-level} are used here, @xref{Article Button -Levels}, but any other form may be used too. - -@c @code{use-p} is @code{eval}ed only if @code{regexp} matches. - -@item function -This function will be called when you click on this button. - -@item data-par -As with @var{button-par}, this is a sub-expression number, but this one -says which part of the match is to be sent as data to @var{function}. - -@end table - -So the full entry for buttonizing URLs is then - -@lisp -("]*\\)>" 0 t gnus-button-url 1) -@end lisp - -@item gnus-header-button-alist -@vindex gnus-header-button-alist -This is just like the other alist, except that it is applied to the -article head only, and that each entry has an additional element that is -used to say what headers to apply the buttonize coding to: - -@lisp -(@var{header} @var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par}) -@end lisp - -@var{header} is a regular expression. -@end table - -@subsubsection Related variables and functions - -@table @code -@item gnus-button-@var{*}-level -@xref{Article Button Levels}. - -@c Stuff related to gnus-button-browse-level - -@item gnus-button-url-regexp -@vindex gnus-button-url-regexp -A regular expression that matches embedded URLs. It is used in the -default values of the variables above. - -@c Stuff related to gnus-button-man-level - -@item gnus-button-man-handler -@vindex gnus-button-man-handler -The function to use for displaying man pages. It must take at least one -argument with a string naming the man page. - -@c Stuff related to gnus-button-message-level - -@item gnus-button-mid-or-mail-regexp -@vindex gnus-button-mid-or-mail-regexp -Regular expression that matches a message ID or a mail address. - -@item gnus-button-prefer-mid-or-mail -@vindex gnus-button-prefer-mid-or-mail -This variable determines what to do when the button on a string as -@samp{foo123@@bar.invalid} is pushed. Strings like this can be either a -message ID or a mail address. If it is one of the symbols @code{mid} or -@code{mail}, Gnus will always assume that the string is a message ID or -a mail address, respectively. If this variable is set to the symbol -@code{ask}, always query the user what to do. If it is a function, this -function will be called with the string as its only argument. The -function must return @code{mid}, @code{mail}, @code{invalid} or -@code{ask}. The default value is the function -@code{gnus-button-mid-or-mail-heuristic}. - -@item gnus-button-mid-or-mail-heuristic -@findex gnus-button-mid-or-mail-heuristic -Function that guesses whether its argument is a message ID or a mail -address. Returns @code{mid} if it's a message IDs, @code{mail} if -it's a mail address, @code{ask} if unsure and @code{invalid} if the -string is invalid. - -@item gnus-button-mid-or-mail-heuristic-alist -@vindex gnus-button-mid-or-mail-heuristic-alist -An alist of @code{(RATE . REGEXP)} pairs used by the function -@code{gnus-button-mid-or-mail-heuristic}. - -@c Misc stuff - -@item gnus-article-button-face -@vindex gnus-article-button-face -Face used on buttons. - -@item gnus-article-mouse-face -@vindex gnus-article-mouse-face -Face used when the mouse cursor is over a button. - -@end table - -@xref{Customizing Articles}, for how to buttonize articles automatically. - - -@node Article Button Levels -@subsection Article button levels -@cindex button levels -The higher the value of the variables @code{gnus-button-@var{*}-level}, -the more buttons will appear. If the level is zero, no corresponding -buttons are displayed. With the default value (which is 5) you should -already see quite a lot of buttons. With higher levels, you will see -more buttons, but you may also get more false positives. To avoid them, -you can set the variables @code{gnus-button-@var{*}-level} local to -specific groups (@pxref{Group Parameters}). Here's an example for the -variable @code{gnus-parameters}: - -@lisp -;; @r{increase @code{gnus-button-*-level} in some groups:} -(setq gnus-parameters - '(("\\<\\(emacs\\|gnus\\)\\>" (gnus-button-emacs-level 10)) - ("\\" (gnus-button-man-level 10)) - ("\\" (gnus-button-tex-level 10)))) -@end lisp - -@table @code - -@item gnus-button-browse-level -@vindex gnus-button-browse-level -Controls the display of references to message IDs, mail addresses and -news URLs. Related variables and functions include -@code{gnus-button-url-regexp}, @code{browse-url}, and -@code{browse-url-browser-function}. - -@item gnus-button-emacs-level -@vindex gnus-button-emacs-level -Controls the display of Emacs or Gnus references. Related functions are -@code{gnus-button-handle-custom}, -@code{gnus-button-handle-describe-function}, -@code{gnus-button-handle-describe-variable}, -@code{gnus-button-handle-symbol}, -@code{gnus-button-handle-describe-key}, -@code{gnus-button-handle-apropos}, -@code{gnus-button-handle-apropos-command}, -@code{gnus-button-handle-apropos-variable}, -@code{gnus-button-handle-apropos-documentation}, and -@code{gnus-button-handle-library}. - -@item gnus-button-man-level -@vindex gnus-button-man-level -Controls the display of references to (Unix) man pages. -See @code{gnus-button-man-handler}. - -@item gnus-button-message-level -@vindex gnus-button-message-level -Controls the display of message IDs, mail addresses and news URLs. -Related variables and functions include -@code{gnus-button-mid-or-mail-regexp}, -@code{gnus-button-prefer-mid-or-mail}, -@code{gnus-button-mid-or-mail-heuristic}, and -@code{gnus-button-mid-or-mail-heuristic-alist}. - -@end table - - -@node Article Date -@subsection Article Date - -The date is most likely generated in some obscure timezone you've never -heard of, so it's quite nice to be able to find out what the time was -when the article was sent. - -@table @kbd - -@item W T u -@kindex W T u (Summary) -@findex gnus-article-date-ut -Display the date in UT (aka. GMT, aka ZULU) -(@code{gnus-article-date-ut}). - -@item W T i -@kindex W T i (Summary) -@findex gnus-article-date-iso8601 -@cindex ISO 8601 -Display the date in international format, aka. ISO 8601 -(@code{gnus-article-date-iso8601}). - -@item W T l -@kindex W T l (Summary) -@findex gnus-article-date-local -Display the date in the local timezone (@code{gnus-article-date-local}). - -@item W T p -@kindex W T p (Summary) -@findex gnus-article-date-english -Display the date in a format that's easily pronounceable in English -(@code{gnus-article-date-english}). - -@item W T s -@kindex W T s (Summary) -@vindex gnus-article-time-format -@findex gnus-article-date-user -@findex format-time-string -Display the date using a user-defined format -(@code{gnus-article-date-user}). The format is specified by the -@code{gnus-article-time-format} variable, and is a string that's passed -to @code{format-time-string}. See the documentation of that variable -for a list of possible format specs. - -@item W T e -@kindex W T e (Summary) -@findex gnus-article-date-lapsed -@findex gnus-start-date-timer -@findex gnus-stop-date-timer -Say how much time has elapsed between the article was posted and now -(@code{gnus-article-date-lapsed}). It looks something like: - -@example -Date: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago -@end example - -To make this line updated continually, set the -@code{gnus-article-update-date-headers} variable to the frequency in -seconds (the default is @code{nil}). - -@item W T o -@kindex W T o (Summary) -@findex gnus-article-date-original -Display the original date (@code{gnus-article-date-original}). This can -be useful if you normally use some other conversion function and are -worried that it might be doing something totally wrong. Say, claiming -that the article was posted in 1854. Although something like that is -@emph{totally} impossible. Don't you trust me? *titter* - -@end table - -@xref{Customizing Articles}, for how to display the date in your -preferred format automatically. - - -@node Article Display -@subsection Article Display -@cindex picons -@cindex x-face -@cindex smileys -@cindex gravatars - -These commands add various frivolous display gimmicks to the article -buffer in Emacs versions that support them. - -@code{X-Face} headers are small black-and-white images supplied by the -message headers (@pxref{X-Face}). - -@code{Face} headers are small colored images supplied by the message -headers (@pxref{Face}). - -Smileys are those little @samp{:-)} symbols that people like to litter -their messages with (@pxref{Smileys}). - -Picons, on the other hand, reside on your own system, and Gnus will -try to match the headers to what you have (@pxref{Picons}). - -Gravatars reside on-line and are fetched from -@uref{http://www.gravatar.com/} (@pxref{Gravatars}). - -All these functions are toggles---if the elements already exist, -they'll be removed. - -@table @kbd -@item W D x -@kindex W D x (Summary) -@findex gnus-article-display-x-face -Display an @code{X-Face} in the @code{From} header. -(@code{gnus-article-display-x-face}). - -@item W D d -@kindex W D d (Summary) -@findex gnus-article-display-face -Display a @code{Face} in the @code{From} header. -(@code{gnus-article-display-face}). - -@item W D s -@kindex W D s (Summary) -@findex gnus-treat-smiley -Display smileys (@code{gnus-treat-smiley}). - -@item W D f -@kindex W D f (Summary) -@findex gnus-treat-from-picon -Piconify the @code{From} header (@code{gnus-treat-from-picon}). - -@item W D m -@kindex W D m (Summary) -@findex gnus-treat-mail-picon -Piconify all mail headers (i.e., @code{Cc}, @code{To}) -(@code{gnus-treat-mail-picon}). - -@item W D n -@kindex W D n (Summary) -@findex gnus-treat-newsgroups-picon -Piconify all news headers (i.e., @code{Newsgroups} and -@code{Followup-To}) (@code{gnus-treat-newsgroups-picon}). - -@item W D g -@kindex W D g (Summary) -@findex gnus-treat-from-gravatar -Gravatarify the @code{From} header (@code{gnus-treat-from-gravatar}). - -@item W D h -@kindex W D h (Summary) -@findex gnus-treat-mail-gravatar -Gravatarify all mail headers (i.e., @code{Cc}, @code{To}) -(@code{gnus-treat-from-gravatar}). - -@item W D D -@kindex W D D (Summary) -@findex gnus-article-remove-images -Remove all images from the article buffer -(@code{gnus-article-remove-images}). - -@item W D W -@kindex W D W (Summary) -@findex gnus-html-show-images -If you're reading an @acronym{HTML} article rendered with -@code{gnus-article-html}, then you can insert any blocked images in -the buffer with this command. -(@code{gnus-html-show-images}). - -@end table - - - -@node Article Signature -@subsection Article Signature -@cindex signatures -@cindex article signature - -@vindex gnus-signature-separator -Each article is divided into two parts---the head and the body. The -body can be divided into a signature part and a text part. The variable -that says what is to be considered a signature is -@code{gnus-signature-separator}. This is normally the standard -@samp{^-- $} as mandated by son-of-RFC 1036. However, many people use -non-standard signature separators, so this variable can also be a list -of regular expressions to be tested, one by one. (Searches are done -from the end of the body towards the beginning.) One likely value is: - -@lisp -(setq gnus-signature-separator - '("^-- $" ; @r{The standard} - "^-- *$" ; @r{A common mangling} - "^-------*$" ; @r{Many people just use a looong} - ; @r{line of dashes. Shame!} - "^ *--------*$" ; @r{Double-shame!} - "^________*$" ; @r{Underscores are also popular} - "^========*$")) ; @r{Pervert!} -@end lisp - -The more permissive you are, the more likely it is that you'll get false -positives. - -@vindex gnus-signature-limit -@code{gnus-signature-limit} provides a limit to what is considered a -signature when displaying articles. - -@enumerate -@item -If it is an integer, no signature may be longer (in characters) than -that integer. -@item -If it is a floating point number, no signature may be longer (in lines) -than that number. -@item -If it is a function, the function will be called without any parameters, -and if it returns @code{nil}, there is no signature in the buffer. -@item -If it is a string, it will be used as a regexp. If it matches, the text -in question is not a signature. -@end enumerate - -This variable can also be a list where the elements may be of the types -listed above. Here's an example: - -@lisp -(setq gnus-signature-limit - '(200.0 "^---*Forwarded article")) -@end lisp - -This means that if there are more than 200 lines after the signature -separator, or the text after the signature separator is matched by -the regular expression @samp{^---*Forwarded article}, then it isn't a -signature after all. - - -@node Article Miscellanea -@subsection Article Miscellanea - -@table @kbd -@item A t -@kindex A t (Summary) -@findex gnus-article-babel -Translate the article from one language to another -(@code{gnus-article-babel}). - -@end table - - -@node MIME Commands -@section MIME Commands -@cindex MIME decoding -@cindex attachments -@cindex viewing attachments - -The following commands all understand the numerical prefix. For -instance, @kbd{3 K v} means ``view the third @acronym{MIME} part''. - -@table @kbd -@item b -@itemx K v -@kindex b (Summary) -@kindex K v (Summary) -View the @acronym{MIME} part. - -@item K o -@kindex K o (Summary) -Save the @acronym{MIME} part. - -@item K O -@kindex K O (Summary) -Prompt for a file name, then save the @acronym{MIME} part and strip it -from the article. The stripped @acronym{MIME} object will be referred -via the message/external-body @acronym{MIME} type. - -@item K r -@kindex K r (Summary) -Replace the @acronym{MIME} part with an external body. - -@item K d -@kindex K d (Summary) -Delete the @acronym{MIME} part and add some information about the -removed part. - -@item K c -@kindex K c (Summary) -Copy the @acronym{MIME} part. - -@item K e -@kindex K e (Summary) -View the @acronym{MIME} part externally. - -@item K i -@kindex K i (Summary) -View the @acronym{MIME} part internally. - -@item K | -@kindex K | (Summary) -Pipe the @acronym{MIME} part to an external command. -@end table - -The rest of these @acronym{MIME} commands do not use the numerical prefix in -the same manner: - -@table @kbd -@item K H -@kindex K H (Summary) -@findex gnus-article-browse-html-article -View @samp{text/html} parts of the current article with a WWW browser. -Inline images embedded in a message using the @code{cid} scheme, as they -are generally considered to be safe, will be processed properly. The -message header is added to the beginning of every @acronym{HTML} part -unless the prefix argument is given. - -Warning: Spammers use links to images (using the @code{http} scheme) in -@acronym{HTML} articles to verify whether you have read the message. As -this command passes the @acronym{HTML} content to the browser without -eliminating these ``web bugs'' you should only use it for mails from -trusted senders. - -If you always want to display @acronym{HTML} parts in the browser, set -@code{mm-text-html-renderer} to @code{nil}. - -This command creates temporary files to pass @acronym{HTML} contents -including images if any to the browser, and deletes them when exiting -the group (if you want). - -@item K b -@kindex K b (Summary) -Make all the @acronym{MIME} parts have buttons in front of them. This is -mostly useful if you wish to save (or perform other actions) on inlined -parts. - -@item K m -@kindex K m (Summary) -@findex gnus-summary-repair-multipart -Some multipart messages are transmitted with missing or faulty headers. -This command will attempt to ``repair'' these messages so that they can -be viewed in a more pleasant manner -(@code{gnus-summary-repair-multipart}). - -@item X m -@kindex X m (Summary) -@findex gnus-summary-save-parts -Save all parts matching a @acronym{MIME} type to a directory -(@code{gnus-summary-save-parts}). Understands the process/prefix -convention (@pxref{Process/Prefix}). - -@item M-t -@kindex M-t (Summary) -@findex gnus-summary-toggle-display-buttonized -Toggle the buttonized display of the article buffer -(@code{gnus-summary-toggle-display-buttonized}). - -@item W M w -@kindex W M w (Summary) -@findex gnus-article-decode-mime-words -Decode RFC 2047-encoded words in the article headers -(@code{gnus-article-decode-mime-words}). - -@item W M c -@kindex W M c (Summary) -@findex gnus-article-decode-charset -Decode encoded article bodies as well as charsets -(@code{gnus-article-decode-charset}). - -This command looks in the @code{Content-Type} header to determine the -charset. If there is no such header in the article, you can give it a -prefix, which will prompt for the charset to decode as. In regional -groups where people post using some common encoding (but do not -include @acronym{MIME} headers), you can set the @code{charset} group/topic -parameter to the required charset (@pxref{Group Parameters}). - -@item W M v -@kindex W M v (Summary) -@findex gnus-mime-view-all-parts -View all the @acronym{MIME} parts in the current article -(@code{gnus-mime-view-all-parts}). - -@end table - -Relevant variables: - -@table @code -@item gnus-ignored-mime-types -@vindex gnus-ignored-mime-types -This is a list of regexps. @acronym{MIME} types that match a regexp from -this list will be completely ignored by Gnus. The default value is -@code{nil}. - -To have all Vcards be ignored, you'd say something like this: - -@lisp -(setq gnus-ignored-mime-types - '("text/x-vcard")) -@end lisp - -@item gnus-article-loose-mime -@vindex gnus-article-loose-mime -If non-@code{nil}, Gnus won't require the @samp{MIME-Version} header -before interpreting the message as a @acronym{MIME} message. This helps -when reading messages from certain broken mail user agents. The -default is @code{t}. - -@item gnus-article-emulate-mime -@vindex gnus-article-emulate-mime -@cindex uuencode -@cindex yEnc -There are other, non-@acronym{MIME} encoding methods used. The most common -is @samp{uuencode}, but yEncode is also getting to be popular. If -this variable is non-@code{nil}, Gnus will look in message bodies to -see if it finds these encodings, and if so, it'll run them through the -Gnus @acronym{MIME} machinery. The default is @code{t}. Only -single-part yEnc encoded attachments can be decoded. There's no support -for encoding in Gnus. - -@item gnus-unbuttonized-mime-types -@vindex gnus-unbuttonized-mime-types -This is a list of regexps. @acronym{MIME} types that match a regexp from -this list won't have @acronym{MIME} buttons inserted unless they aren't -displayed or this variable is overridden by -@code{gnus-buttonized-mime-types}. The default value is -@code{(".*/.*")}. This variable is only used when -@code{gnus-inhibit-mime-unbuttonizing} is @code{nil}. - -@item gnus-buttonized-mime-types -@vindex gnus-buttonized-mime-types -This is a list of regexps. @acronym{MIME} types that match a regexp from -this list will have @acronym{MIME} buttons inserted unless they aren't -displayed. This variable overrides -@code{gnus-unbuttonized-mime-types}. The default value is @code{nil}. -This variable is only used when @code{gnus-inhibit-mime-unbuttonizing} -is @code{nil}. - -E.g., to see security buttons but no other buttons, you could set this -variable to @code{("multipart/signed")} and leave -@code{gnus-unbuttonized-mime-types} at the default value. - -You could also add @code{"multipart/alternative"} to this list to -display radio buttons that allow you to choose one of two media types -those mails include. See also @code{mm-discouraged-alternatives} -(@pxref{Display Customization, ,Display Customization, emacs-mime, The -Emacs MIME Manual}). - -@item gnus-inhibit-mime-unbuttonizing -@vindex gnus-inhibit-mime-unbuttonizing -If this is non-@code{nil}, then all @acronym{MIME} parts get buttons. The -default value is @code{nil}. - -@item gnus-article-mime-part-function -@vindex gnus-article-mime-part-function -For each @acronym{MIME} part, this function will be called with the @acronym{MIME} -handle as the parameter. The function is meant to be used to allow -users to gather information from the article (e.g., add Vcard info to -the bbdb database) or to do actions based on parts (e.g., automatically -save all jpegs into some directory). - -Here's an example function the does the latter: - -@lisp -(defun my-save-all-jpeg-parts (handle) - (when (equal (car (mm-handle-type handle)) "image/jpeg") - (with-temp-buffer - (insert (mm-get-part handle)) - (write-region (point-min) (point-max) - (read-file-name "Save jpeg to: "))))) -(setq gnus-article-mime-part-function - 'my-save-all-jpeg-parts) -@end lisp - -@vindex gnus-mime-multipart-functions -@item gnus-mime-multipart-functions -Alist of @acronym{MIME} multipart types and functions to handle them. - -@vindex gnus-mime-display-multipart-alternative-as-mixed -@item gnus-mime-display-multipart-alternative-as-mixed -Display "multipart/alternative" parts as "multipart/mixed". - -@vindex gnus-mime-display-multipart-related-as-mixed -@item gnus-mime-display-multipart-related-as-mixed -Display "multipart/related" parts as "multipart/mixed". - -If displaying @samp{text/html} is discouraged, see -@code{mm-discouraged-alternatives}, images or other material inside a -"multipart/related" part might be overlooked when this variable is -@code{nil}. @ref{Display Customization, Display Customization, , -emacs-mime, Emacs-Mime Manual}. - -@vindex gnus-mime-display-multipart-as-mixed -@item gnus-mime-display-multipart-as-mixed -Display "multipart" parts as "multipart/mixed". If @code{t}, it -overrides @code{nil} values of -@code{gnus-mime-display-multipart-alternative-as-mixed} and -@code{gnus-mime-display-multipart-related-as-mixed}. - -@vindex mm-file-name-rewrite-functions -@item mm-file-name-rewrite-functions -List of functions used for rewriting file names of @acronym{MIME} parts. -Each function takes a file name as input and returns a file name. - -Ready-made functions include@* -@code{mm-file-name-delete-whitespace}, -@code{mm-file-name-trim-whitespace}, -@code{mm-file-name-collapse-whitespace}, and -@code{mm-file-name-replace-whitespace}. The later uses the value of -the variable @code{mm-file-name-replace-whitespace} to replace each -whitespace character in a file name with that string; default value -is @code{"_"} (a single underscore). -@findex mm-file-name-delete-whitespace -@findex mm-file-name-trim-whitespace -@findex mm-file-name-collapse-whitespace -@findex mm-file-name-replace-whitespace -@vindex mm-file-name-replace-whitespace - -The standard functions @code{capitalize}, @code{downcase}, -@code{upcase}, and @code{upcase-initials} may be useful, too. - -Everybody knows that whitespace characters in file names are evil, -except those who don't know. If you receive lots of attachments from -such unenlightened users, you can make live easier by adding - -@lisp -(setq mm-file-name-rewrite-functions - '(mm-file-name-trim-whitespace - mm-file-name-collapse-whitespace - mm-file-name-replace-whitespace)) -@end lisp - -@noindent -to your @file{~/.gnus.el} file. - -@end table - - -@node Charsets -@section Charsets -@cindex charsets - -People use different charsets, and we have @acronym{MIME} to let us know what -charsets they use. Or rather, we wish we had. Many people use -newsreaders and mailers that do not understand or use @acronym{MIME}, and -just send out messages without saying what character sets they use. To -help a bit with this, some local news hierarchies have policies that say -what character set is the default. For instance, the @samp{fj} -hierarchy uses @code{iso-2022-jp}. - -@vindex gnus-group-charset-alist -This knowledge is encoded in the @code{gnus-group-charset-alist} -variable, which is an alist of regexps (use the first item to match full -group names) and default charsets to be used when reading these groups. - -@vindex gnus-newsgroup-ignored-charsets -In addition, some people do use soi-disant @acronym{MIME}-aware agents that -aren't. These blithely mark messages as being in @code{iso-8859-1} -even if they really are in @code{koi-8}. To help here, the -@code{gnus-newsgroup-ignored-charsets} variable can be used. The -charsets that are listed here will be ignored. The variable can be -set on a group-by-group basis using the group parameters (@pxref{Group -Parameters}). The default value is @code{(unknown-8bit x-unknown)}, -which includes values some agents insist on having in there. - -@vindex gnus-group-posting-charset-alist -When posting, @code{gnus-group-posting-charset-alist} is used to -determine which charsets should not be encoded using the @acronym{MIME} -encodings. For instance, some hierarchies discourage using -quoted-printable header encoding. - -This variable is an alist of regexps and permitted unencoded charsets -for posting. Each element of the alist has the form @code{(}@var{test -header body-list}@code{)}, where: - -@table @var -@item test -is either a regular expression matching the newsgroup header or a -variable to query, -@item header -is the charset which may be left unencoded in the header (@code{nil} -means encode all charsets), -@item body-list -is a list of charsets which may be encoded using 8bit content-transfer -encoding in the body, or one of the special values @code{nil} (always -encode using quoted-printable) or @code{t} (always use 8bit). -@end table - -@cindex Russian -@cindex koi8-r -@cindex koi8-u -@cindex iso-8859-5 -@cindex coding system aliases -@cindex preferred charset - -@xref{Encoding Customization, , Encoding Customization, emacs-mime, -The Emacs MIME Manual}, for additional variables that control which -MIME charsets are used when sending messages. - -Other charset tricks that may be useful, although not Gnus-specific: - -If there are several @acronym{MIME} charsets that encode the same Emacs -charset, you can choose what charset to use by saying the following: - -@lisp -(put-charset-property 'cyrillic-iso8859-5 - 'preferred-coding-system 'koi8-r) -@end lisp - -This means that Russian will be encoded using @code{koi8-r} instead of -the default @code{iso-8859-5} @acronym{MIME} charset. - -If you want to read messages in @code{koi8-u}, you can cheat and say - -@lisp -(define-coding-system-alias 'koi8-u 'koi8-r) -@end lisp - -This will almost do the right thing. - -And finally, to read charsets like @code{windows-1251}, you can say -something like - -@lisp -(codepage-setup 1251) -(define-coding-system-alias 'windows-1251 'cp1251) -@end lisp - - -@node Article Commands -@section Article Commands - -@table @kbd - -@item A P -@cindex PostScript -@cindex printing -@kindex A P (Summary) -@vindex gnus-ps-print-hook -@findex gnus-summary-print-article -Generate and print a PostScript image of the article buffer -(@code{gnus-summary-print-article}). @code{gnus-ps-print-hook} will -be run just before printing the buffer. An alternative way to print -article is to use Muttprint (@pxref{Saving Articles}). - -@item A C -@vindex gnus-fetch-partial-articles -@findex gnus-summary-show-complete-article -If @code{-fetch-partial-articles} is non-@code{nil}, Gnus will -fetch partial articles, if the backend it fetches them from supports -it. Currently only @code{nnimap} does. If you're looking at a -partial article, and want to see the complete article instead, then -the @kbd{A C} command (@code{gnus-summary-show-complete-article}) will -do so. - -@end table - - -@node Summary Sorting -@section Summary Sorting -@cindex summary sorting - -You can have the summary buffer sorted in various ways, even though I -can't really see why you'd want that. - -@table @kbd - -@item C-c C-s C-n -@kindex C-c C-s C-n (Summary) -@findex gnus-summary-sort-by-number -Sort by article number (@code{gnus-summary-sort-by-number}). - -@item C-c C-s C-m C-n -@kindex C-c C-s C-n (Summary) -@findex gnus-summary-sort-by-most-recent-number -Sort by most recent article number -(@code{gnus-summary-sort-by-most-recent-number}). - -@item C-c C-s C-a -@kindex C-c C-s C-a (Summary) -@findex gnus-summary-sort-by-author -Sort by author (@code{gnus-summary-sort-by-author}). - -@item C-c C-s C-t -@kindex C-c C-s C-t (Summary) -@findex gnus-summary-sort-by-recipient -Sort by recipient (@code{gnus-summary-sort-by-recipient}). - -@item C-c C-s C-s -@kindex C-c C-s C-s (Summary) -@findex gnus-summary-sort-by-subject -Sort by subject (@code{gnus-summary-sort-by-subject}). - -@item C-c C-s C-d -@kindex C-c C-s C-d (Summary) -@findex gnus-summary-sort-by-date -Sort by date (@code{gnus-summary-sort-by-date}). - -@item C-c C-s C-m C-d -@kindex C-c C-s C-m C-d (Summary) -@findex gnus-summary-sort-by-most-recent-date -Sort by most recent date (@code{gnus-summary-sort-by-most-recent-date}). - -@item C-c C-s C-l -@kindex C-c C-s C-l (Summary) -@findex gnus-summary-sort-by-lines -Sort by lines (@code{gnus-summary-sort-by-lines}). - -@item C-c C-s C-c -@kindex C-c C-s C-c (Summary) -@findex gnus-summary-sort-by-chars -Sort by article length (@code{gnus-summary-sort-by-chars}). - -@item C-c C-s C-i -@kindex C-c C-s C-i (Summary) -@findex gnus-summary-sort-by-score -Sort by score (@code{gnus-summary-sort-by-score}). - -@item C-c C-s C-r -@kindex C-c C-s C-r (Summary) -@findex gnus-summary-sort-by-random -Randomize (@code{gnus-summary-sort-by-random}). - -@item C-c C-s C-o -@kindex C-c C-s C-o (Summary) -@findex gnus-summary-sort-by-original -Sort using the default sorting method -(@code{gnus-summary-sort-by-original}). -@end table - -These functions will work both when you use threading and when you don't -use threading. In the latter case, all summary lines will be sorted, -line by line. In the former case, sorting will be done on a -root-by-root basis, which might not be what you were looking for. To -toggle whether to use threading, type @kbd{T T} (@pxref{Thread -Commands}). - -If a prefix argument if given, the sort order is reversed. - - -@node Finding the Parent -@section Finding the Parent -@cindex parent articles -@cindex referring articles - -@table @kbd -@item ^ -@kindex ^ (Summary) -@findex gnus-summary-refer-parent-article -If you'd like to read the parent of the current article, and it is not -displayed in the summary buffer, you might still be able to. That is, -if the current group is fetched by @acronym{NNTP}, the parent hasn't expired -and the @code{References} in the current article are not mangled, you -can just press @kbd{^} or @kbd{A r} -(@code{gnus-summary-refer-parent-article}). If everything goes well, -you'll get the parent. If the parent is already displayed in the -summary buffer, point will just move to this article. - -If given a positive numerical prefix, fetch that many articles back into -the ancestry. If given a negative numerical prefix, fetch just that -ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the -grandparent and the great-grandparent of the current article. If you say -@kbd{-3 ^}, Gnus will only fetch the great-grandparent of the current -article. - -@item A R (Summary) -@findex gnus-summary-refer-references -@kindex A R (Summary) -Fetch all articles mentioned in the @code{References} header of the -article (@code{gnus-summary-refer-references}). - -@item A T (Summary) -@findex gnus-summary-refer-thread -@kindex A T (Summary) -Display the full thread where the current article appears -(@code{gnus-summary-refer-thread}). This command has to fetch all the -headers in the current group to work, so it usually takes a while. If -you do it often, you may consider setting @code{gnus-fetch-old-headers} -to @code{invisible} (@pxref{Filling In Threads}). This won't have any -visible effects normally, but it'll make this command work a whole lot -faster. Of course, it'll make group entry somewhat slow. - -@vindex gnus-refer-thread-limit -The @code{gnus-refer-thread-limit} variable says how many old (i.e., -articles before the first displayed in the current group) headers to -fetch when doing this command. The default is 200. If @code{t}, all -the available headers will be fetched. This variable can be overridden -by giving the @kbd{A T} command a numerical prefix. - -@item M-^ (Summary) -@findex gnus-summary-refer-article -@kindex M-^ (Summary) -@cindex Message-ID -@cindex fetching by Message-ID -You can also ask Gnus for an arbitrary article, no matter what group it -belongs to. @kbd{M-^} (@code{gnus-summary-refer-article}) will ask you -for a @code{Message-ID}, which is one of those long, hard-to-read -thingies that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. -You have to get it all exactly right. No fuzzy searches, I'm afraid. - -Gnus looks for the @code{Message-ID} in the headers that have already -been fetched, but also tries all the select methods specified by -@code{gnus-refer-article-method} if it is not found. -@end table - -@vindex gnus-refer-article-method -If the group you are reading is located on a back end that does not -support fetching by @code{Message-ID} very well (like @code{nnspool}), -you can set @code{gnus-refer-article-method} to an @acronym{NNTP} method. It -would, perhaps, be best if the @acronym{NNTP} server you consult is the one -updating the spool you are reading from, but that's not really -necessary. - -It can also be a list of select methods, as well as the special symbol -@code{current}, which means to use the current select method. If it -is a list, Gnus will try all the methods in the list until it finds a -match. - -Here's an example setting that will first try the current method, and -then ask Google if that fails: - -@lisp -(setq gnus-refer-article-method - '(current - (nnweb "google" (nnweb-type google)))) -@end lisp - -Most of the mail back ends support fetching by @code{Message-ID}, but -do not do a particularly excellent job at it. That is, @code{nnmbox}, -@code{nnbabyl}, @code{nnmaildir}, @code{nnml}, are able to locate -articles from any groups, while @code{nnfolder}, and @code{nnimap} are -only able to locate articles that have been posted to the current -group. @code{nnmh} does not support this at all. - -Fortunately, the special @code{nnregistry} back end is able to locate -articles in any groups, regardless of their back end (@pxref{Registry -Article Refer Method, fetching by @code{Message-ID} using the -registry}). - -@node Alternative Approaches -@section Alternative Approaches - -Different people like to read news using different methods. This being -Gnus, we offer a small selection of minor modes for the summary buffers. - -@menu -* Pick and Read:: First mark articles and then read them. -* Binary Groups:: Auto-decode all articles. -@end menu - - -@node Pick and Read -@subsection Pick and Read -@cindex pick and read - -Some newsreaders (like @code{nn} and, uhm, @code{Netnews} on VM/CMS) use -a two-phased reading interface. The user first marks in a summary -buffer the articles she wants to read. Then she starts reading the -articles with just an article buffer displayed. - -@findex gnus-pick-mode -@kindex M-x gnus-pick-mode -Gnus provides a summary buffer minor mode that allows -this---@code{gnus-pick-mode}. This basically means that a few process -mark commands become one-keystroke commands to allow easy marking, and -it provides one additional command for switching to the summary buffer. - -Here are the available keystrokes when using pick mode: - -@table @kbd -@item . -@kindex . (Pick) -@findex gnus-pick-article-or-thread -Pick the article or thread on the current line -(@code{gnus-pick-article-or-thread}). If the variable -@code{gnus-thread-hide-subtree} is true, then this key selects the -entire thread when used at the first article of the thread. Otherwise, -it selects just the article. If given a numerical prefix, go to that -thread or article and pick it. (The line number is normally displayed -at the beginning of the summary pick lines.) - -@item SPACE -@kindex SPACE (Pick) -@findex gnus-pick-next-page -Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If -at the end of the buffer, start reading the picked articles. - -@item u -@kindex u (Pick) -@findex gnus-pick-unmark-article-or-thread. -Unpick the thread or article -(@code{gnus-pick-unmark-article-or-thread}). If the variable -@code{gnus-thread-hide-subtree} is true, then this key unpicks the -thread if used at the first article of the thread. Otherwise it unpicks -just the article. You can give this key a numerical prefix to unpick -the thread or article at that line. - -@item RET -@kindex RET (Pick) -@findex gnus-pick-start-reading -@vindex gnus-pick-display-summary -Start reading the picked articles (@code{gnus-pick-start-reading}). If -given a prefix, mark all unpicked articles as read first. If -@code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer -will still be visible when you are reading. - -@end table - -All the normal summary mode commands are still available in the -pick-mode, with the exception of @kbd{u}. However @kbd{!} is available -which is mapped to the same function -@code{gnus-summary-tick-article-forward}. - -If this sounds like a good idea to you, you could say: - -@lisp -(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) -@end lisp - -@vindex gnus-pick-mode-hook -@code{gnus-pick-mode-hook} is run in pick minor mode buffers. - -@vindex gnus-mark-unpicked-articles-as-read -If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark -all unpicked articles as read. The default is @code{nil}. - -@vindex gnus-summary-pick-line-format -The summary line format in pick mode is slightly different from the -standard format. At the beginning of each line the line number is -displayed. The pick mode line format is controlled by the -@code{gnus-summary-pick-line-format} variable (@pxref{Formatting -Variables}). It accepts the same format specs that -@code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}). - - -@node Binary Groups -@subsection Binary Groups -@cindex binary groups - -@findex gnus-binary-mode -@kindex M-x gnus-binary-mode -If you spend much time in binary groups, you may grow tired of hitting -@kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode} -is a minor mode for summary buffers that makes all ordinary Gnus article -selection functions uudecode series of articles and display the result -instead of just displaying the articles the normal way. - -@kindex g (Binary) -@findex gnus-binary-show-article -The only way, in fact, to see the actual articles is the @kbd{g} -command, when you have turned on this mode -(@code{gnus-binary-show-article}). - -@vindex gnus-binary-mode-hook -@code{gnus-binary-mode-hook} is called in binary minor mode buffers. - - -@node Tree Display -@section Tree Display -@cindex trees - -@vindex gnus-use-trees -If you don't like the normal Gnus summary display, you might try setting -@code{gnus-use-trees} to @code{t}. This will create (by default) an -additional @dfn{tree buffer}. You can execute all summary mode commands -in the tree buffer. - -There are a few variables to customize the tree display, of course: - -@table @code -@item gnus-tree-mode-hook -@vindex gnus-tree-mode-hook -A hook called in all tree mode buffers. - -@item gnus-tree-mode-line-format -@vindex gnus-tree-mode-line-format -A format string for the mode bar in the tree mode buffers (@pxref{Mode -Line Formatting}). The default is @samp{Gnus: %%b %S %Z}. For a list -of valid specs, @pxref{Summary Buffer Mode Line}. - -@item gnus-selected-tree-face -@vindex gnus-selected-tree-face -Face used for highlighting the selected article in the tree buffer. The -default is @code{modeline}. - -@item gnus-tree-line-format -@vindex gnus-tree-line-format -A format string for the tree nodes. The name is a bit of a misnomer, -though---it doesn't define a line, but just the node. The default value -is @samp{%(%[%3,3n%]%)}, which displays the first three characters of -the name of the poster. It is vital that all nodes are of the same -length, so you @emph{must} use @samp{%4,4n}-like specifiers. - -Valid specs are: - -@table @samp -@item n -The name of the poster. -@item f -The @code{From} header. -@item N -The number of the article. -@item [ -The opening bracket. -@item ] -The closing bracket. -@item s -The subject. -@end table - -@xref{Formatting Variables}. - -Variables related to the display are: - -@table @code -@item gnus-tree-brackets -@vindex gnus-tree-brackets -This is used for differentiating between ``real'' articles and -``sparse'' articles. The format is -@example -((@var{real-open} . @var{real-close}) - (@var{sparse-open} . @var{sparse-close}) - (@var{dummy-open} . @var{dummy-close})) -@end example -and the default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}. - -@item gnus-tree-parent-child-edges -@vindex gnus-tree-parent-child-edges -This is a list that contains the characters used for connecting parent -nodes to their children. The default is @code{(?- ?\\ ?|)}. - -@end table - -@item gnus-tree-minimize-window -@vindex gnus-tree-minimize-window -If this variable is non-@code{nil}, Gnus will try to keep the tree -buffer as small as possible to allow more room for the other Gnus -windows. If this variable is a number, the tree buffer will never be -higher than that number. The default is @code{t}. Note that if you -have several windows displayed side-by-side in a frame and the tree -buffer is one of these, minimizing the tree window will also resize all -other windows displayed next to it. - -You may also wish to add the following hook to keep the window minimized -at all times: - -@lisp -(add-hook 'gnus-configure-windows-hook - 'gnus-tree-perhaps-minimize) -@end lisp - -@item gnus-generate-tree-function -@vindex gnus-generate-tree-function -@findex gnus-generate-horizontal-tree -@findex gnus-generate-vertical-tree -The function that actually generates the thread tree. Two predefined -functions are available: @code{gnus-generate-horizontal-tree} and -@code{gnus-generate-vertical-tree} (which is the default). - -@end table - -Here's an example from a horizontal tree buffer: - -@example -@{***@}-(***)-[odd]-[Gun] - | \[Jan] - | \[odd]-[Eri] - | \(***)-[Eri] - | \[odd]-[Paa] - \[Bjo] - \[Gun] - \[Gun]-[Jor] -@end example - -Here's the same thread displayed in a vertical tree buffer: - -@example -@group -@{***@} - |--------------------------\-----\-----\ -(***) [Bjo] [Gun] [Gun] - |--\-----\-----\ | -[odd] [Jan] [odd] (***) [Jor] - | | |--\ -[Gun] [Eri] [Eri] [odd] - | - [Paa] -@end group -@end example - -If you're using horizontal trees, it might be nice to display the trees -side-by-side with the summary buffer. You could add something like the -following to your @file{~/.gnus.el} file: - -@lisp -(setq gnus-use-trees t - gnus-generate-tree-function 'gnus-generate-horizontal-tree - gnus-tree-minimize-window nil) -(gnus-add-configuration - '(article - (vertical 1.0 - (horizontal 0.25 - (summary 0.75 point) - (tree 1.0)) - (article 1.0)))) -@end lisp - -@xref{Window Layout}. - - -@node Mail Group Commands -@section Mail Group Commands -@cindex mail group commands - -Some commands only make sense in mail groups. If these commands are -invalid in the current group, they will raise a hell and let you know. - -All these commands (except the expiry and edit commands) use the -process/prefix convention (@pxref{Process/Prefix}). - -@table @kbd - -@item B e -@kindex B e (Summary) -@findex gnus-summary-expire-articles -@cindex expiring mail -Run all expirable articles in the current group through the expiry -process (@code{gnus-summary-expire-articles}). That is, delete all -expirable articles in the group that have been around for a while. -(@pxref{Expiring Mail}). - -@item B C-M-e -@kindex B C-M-e (Summary) -@findex gnus-summary-expire-articles-now -@cindex expiring mail -Delete all the expirable articles in the group -(@code{gnus-summary-expire-articles-now}). This means that @strong{all} -articles eligible for expiry in the current group will -disappear forever into that big @file{/dev/null} in the sky. - -@item B DEL -@kindex B DEL (Summary) -@cindex deleting mail -@findex gnus-summary-delete-article -@c @icon{gnus-summary-mail-delete} -Delete the mail article. This is ``delete'' as in ``delete it from your -disk forever and ever, never to return again.'' Use with caution. -(@code{gnus-summary-delete-article}). - -@item B m -@kindex B m (Summary) -@cindex move mail -@findex gnus-summary-move-article -@vindex gnus-preserve-marks -Move the article from one mail group to another -(@code{gnus-summary-move-article}). Marks will be preserved if -@code{gnus-preserve-marks} is non-@code{nil} (which is the default). - -@item B c -@kindex B c (Summary) -@cindex copy mail -@findex gnus-summary-copy-article -@c @icon{gnus-summary-mail-copy} -Copy the article from one group (mail group or not) to a mail group -(@code{gnus-summary-copy-article}). Marks will be preserved if -@code{gnus-preserve-marks} is non-@code{nil} (which is the default). - -@item B B -@kindex B B (Summary) -@cindex crosspost mail -@findex gnus-summary-crosspost-article -Crosspost the current article to some other group -(@code{gnus-summary-crosspost-article}). This will create a new copy of -the article in the other group, and the Xref headers of the article will -be properly updated. - -@item B i -@kindex B i (Summary) -@findex gnus-summary-import-article -Import an arbitrary file into the current mail newsgroup -(@code{gnus-summary-import-article}). You will be prompted for a file -name, a @code{From} header and a @code{Subject} header. - -@item B I -@kindex B I (Summary) -@findex gnus-summary-create-article -Create an empty article in the current mail newsgroups -(@code{gnus-summary-create-article}). You will be prompted for a -@code{From} header and a @code{Subject} header. - -@item B r -@kindex B r (Summary) -@findex gnus-summary-respool-article -@vindex gnus-summary-respool-default-method -Respool the mail article (@code{gnus-summary-respool-article}). -@code{gnus-summary-respool-default-method} will be used as the default -select method when respooling. This variable is @code{nil} by default, -which means that the current group select method will be used instead. -Marks will be preserved if @code{gnus-preserve-marks} is non-@code{nil} -(which is the default). - -@item B w -@itemx e -@kindex B w (Summary) -@kindex e (Summary) -@findex gnus-summary-edit-article -@kindex C-c C-c (Article) -@findex gnus-summary-edit-article-done -Edit the current article (@code{gnus-summary-edit-article}). To finish -editing and make the changes permanent, type @kbd{C-c C-c} -(@code{gnus-summary-edit-article-done}). If you give a prefix to the -@kbd{C-c C-c} command, Gnus won't re-highlight the article. - -@item B q -@kindex B q (Summary) -@findex gnus-summary-respool-query -If you want to re-spool an article, you might be curious as to what group -the article will end up in before you do the re-spooling. This command -will tell you (@code{gnus-summary-respool-query}). - -@item B t -@kindex B t (Summary) -@findex gnus-summary-respool-trace -Similarly, this command will display all fancy splitting patterns used -when respooling, if any (@code{gnus-summary-respool-trace}). - -@item B p -@kindex B p (Summary) -@findex gnus-summary-article-posted-p -Some people have a tendency to send you ``courtesy'' copies when they -follow up to articles you have posted. These usually have a -@code{Newsgroups} header in them, but not always. This command -(@code{gnus-summary-article-posted-p}) will try to fetch the current -article from your news server (or rather, from -@code{gnus-refer-article-method} or @code{gnus-select-method}) and will -report back whether it found the article or not. Even if it says that -it didn't find the article, it may have been posted anyway---mail -propagation is much faster than news propagation, and the news copy may -just not have arrived yet. - -@item K E -@kindex K E (Summary) -@findex gnus-article-encrypt-body -@vindex gnus-article-encrypt-protocol -Encrypt the body of an article (@code{gnus-article-encrypt-body}). -The body is encrypted with the encryption protocol specified by the -variable @code{gnus-article-encrypt-protocol}. - -@end table - -@vindex gnus-move-split-methods -@cindex moving articles -If you move (or copy) articles regularly, you might wish to have Gnus -suggest where to put the articles. @code{gnus-move-split-methods} is a -variable that uses the same syntax as @code{gnus-split-methods} -(@pxref{Saving Articles}). You may customize that variable to create -suggestions you find reasonable. (Note that -@code{gnus-move-split-methods} uses group names where -@code{gnus-split-methods} uses file names.) - -@lisp -(setq gnus-move-split-methods - '(("^From:.*Lars Magne" "nnml:junk") - ("^Subject:.*gnus" "nnfolder:important") - (".*" "nnml:misc"))) -@end lisp - - -@node Various Summary Stuff -@section Various Summary Stuff - -@menu -* Summary Group Information:: Information oriented commands. -* Searching for Articles:: Multiple article commands. -* Summary Generation Commands:: -* Really Various Summary Commands:: Those pesky non-conformant commands. -@end menu - -@table @code -@vindex gnus-summary-display-while-building -@item gnus-summary-display-while-building -If non-@code{nil}, show and update the summary buffer as it's being -built. If @code{t}, update the buffer after every line is inserted. -If the value is an integer, @var{n}, update the display every @var{n} -lines. The default is @code{nil}. - -@vindex gnus-summary-display-arrow -@item gnus-summary-display-arrow -If non-@code{nil}, display an arrow in the fringe to indicate the -current article. - -@vindex gnus-summary-mode-hook -@item gnus-summary-mode-hook -This hook is called when creating a summary mode buffer. - -@vindex gnus-summary-generate-hook -@item gnus-summary-generate-hook -This is called as the last thing before doing the threading and the -generation of the summary buffer. It's quite convenient for customizing -the threading variables based on what data the newsgroup has. This hook -is called from the summary buffer after most summary buffer variables -have been set. - -@vindex gnus-summary-prepare-hook -@item gnus-summary-prepare-hook -It is called after the summary buffer has been generated. You might use -it to, for instance, highlight lines or modify the look of the buffer in -some other ungodly manner. I don't care. - -@vindex gnus-summary-prepared-hook -@item gnus-summary-prepared-hook -A hook called as the very last thing after the summary buffer has been -generated. - -@vindex gnus-summary-ignore-duplicates -@item gnus-summary-ignore-duplicates -When Gnus discovers two articles that have the same @code{Message-ID}, -it has to do something drastic. No articles are allowed to have the -same @code{Message-ID}, but this may happen when reading mail from some -sources. Gnus allows you to customize what happens with this variable. -If it is @code{nil} (which is the default), Gnus will rename the -@code{Message-ID} (for display purposes only) and display the article as -any other article. If this variable is @code{t}, it won't display the -article---it'll be as if it never existed. - -@vindex gnus-alter-articles-to-read-function -@item gnus-alter-articles-to-read-function -This function, which takes two parameters (the group name and the list -of articles to be selected), is called to allow the user to alter the -list of articles to be selected. - -For instance, the following function adds the list of cached articles to -the list in one particular group: - -@lisp -(defun my-add-cached-articles (group articles) - (if (string= group "some.group") - (append gnus-newsgroup-cached articles) - articles)) -@end lisp - -@vindex gnus-newsgroup-variables -@item gnus-newsgroup-variables -A list of newsgroup (summary buffer) local variables, or cons of -variables and their default expressions to be evalled (when the default -values are not @code{nil}), that should be made global while the summary -buffer is active. - -Note: The default expressions will be evaluated (using function -@code{eval}) before assignment to the local variable rather than just -assigned to it. If the default expression is the symbol @code{global}, -that symbol will not be evaluated but the global value of the local -variable will be used instead. - -These variables can be used to set variables in the group parameters -while still allowing them to affect operations done in other -buffers. For example: - -@lisp -(setq gnus-newsgroup-variables - '(message-use-followup-to - (gnus-visible-headers . - "^From:\\|^Newsgroups:\\|^Subject:\\|^Date:\\|^To:"))) -@end lisp - -Also @pxref{Group Parameters}. - -@end table - - -@node Summary Group Information -@subsection Summary Group Information - -@table @kbd - -@item H d -@kindex H d (Summary) -@findex gnus-summary-describe-group -Give a brief description of the current group -(@code{gnus-summary-describe-group}). If given a prefix, force -rereading the description from the server. - -@item H h -@kindex H h (Summary) -@findex gnus-summary-describe-briefly -Give an extremely brief description of the most important summary -keystrokes (@code{gnus-summary-describe-briefly}). - -@item H i -@kindex H i (Summary) -@findex gnus-info-find-node -Go to the Gnus info node (@code{gnus-info-find-node}). -@end table - - -@node Searching for Articles -@subsection Searching for Articles - -@table @kbd - -@item M-s -@kindex M-s (Summary) -@findex gnus-summary-search-article-forward -Search through all subsequent (raw) articles for a regexp -(@code{gnus-summary-search-article-forward}). - -@item M-r -@kindex M-r (Summary) -@findex gnus-summary-search-article-backward -Search through all previous (raw) articles for a regexp -(@code{gnus-summary-search-article-backward}). - -@item M-S -@kindex M-S (Summary) -@findex gnus-summary-repeat-search-article-forward -Repeat the previous search forwards -(@code{gnus-summary-repeat-search-article-forward}). - -@item M-R -@kindex M-R (Summary) -@findex gnus-summary-repeat-search-article-backward -Repeat the previous search backwards -(@code{gnus-summary-repeat-search-article-backward}). - -@item & -@kindex & (Summary) -@findex gnus-summary-execute-command -This command will prompt you for a header, a regular expression to match -on this field, and a command to be executed if the match is made -(@code{gnus-summary-execute-command}). If the header is an empty -string, the match is done on the entire article. If given a prefix, -search backward instead. - -For instance, @kbd{& RET some.*string RET #} will put the process mark on -all articles that have heads or bodies that match @samp{some.*string}. - -@item M-& -@kindex M-& (Summary) -@findex gnus-summary-universal-argument -Perform any operation on all articles that have been marked with -the process mark (@code{gnus-summary-universal-argument}). -@end table - -@node Summary Generation Commands -@subsection Summary Generation Commands - -@table @kbd - -@item Y g -@kindex Y g (Summary) -@findex gnus-summary-prepare -Regenerate the current summary buffer (@code{gnus-summary-prepare}). - -@item Y c -@kindex Y c (Summary) -@findex gnus-summary-insert-cached-articles -Pull all cached articles (for the current group) into the summary buffer -(@code{gnus-summary-insert-cached-articles}). - -@item Y d -@kindex Y d (Summary) -@findex gnus-summary-insert-dormant-articles -Pull all dormant articles (for the current group) into the summary buffer -(@code{gnus-summary-insert-dormant-articles}). - -@item Y t -@kindex Y t (Summary) -@findex gnus-summary-insert-ticked-articles -Pull all ticked articles (for the current group) into the summary buffer -(@code{gnus-summary-insert-ticked-articles}). - -@end table - - -@node Really Various Summary Commands -@subsection Really Various Summary Commands - -@table @kbd - -@item A D -@itemx C-d -@kindex C-d (Summary) -@kindex A D (Summary) -@findex gnus-summary-enter-digest-group -If the current article is a collection of other articles (for instance, -a digest), you might use this command to enter a group based on the that -article (@code{gnus-summary-enter-digest-group}). Gnus will try to -guess what article type is currently displayed unless you give a prefix -to this command, which forces a ``digest'' interpretation. Basically, -whenever you see a message that is a collection of other messages of -some format, you @kbd{C-d} and read these messages in a more convenient -fashion. - -@vindex gnus-auto-select-on-ephemeral-exit -The variable @code{gnus-auto-select-on-ephemeral-exit} controls what -article should be selected after exiting a digest group. Valid values -include: - -@table @code -@item next -Select the next article. - -@item next-unread -Select the next unread article. - -@item next-noselect -Move the cursor to the next article. This is the default. - -@item next-unread-noselect -Move the cursor to the next unread article. -@end table - -If it has any other value or there is no next (unread) article, the -article selected before entering to the digest group will appear. - -@item C-M-d -@kindex C-M-d (Summary) -@findex gnus-summary-read-document -This command is very similar to the one above, but lets you gather -several documents into one biiig group -(@code{gnus-summary-read-document}). It does this by opening several -@code{nndoc} groups for each document, and then opening an -@code{nnvirtual} group on top of these @code{nndoc} groups. This -command understands the process/prefix convention -(@pxref{Process/Prefix}). - -@item C-t -@kindex C-t (Summary) -@findex gnus-summary-toggle-truncation -Toggle truncation of summary lines -(@code{gnus-summary-toggle-truncation}). This will probably confuse the -line centering function in the summary buffer, so it's not a good idea -to have truncation switched off while reading articles. - -@item = -@kindex = (Summary) -@findex gnus-summary-expand-window -Expand the summary buffer window (@code{gnus-summary-expand-window}). -If given a prefix, force an @code{article} window configuration. - -@item C-M-e -@kindex C-M-e (Summary) -@findex gnus-summary-edit-parameters -Edit the group parameters (@pxref{Group Parameters}) of the current -group (@code{gnus-summary-edit-parameters}). - -@item C-M-a -@kindex C-M-a (Summary) -@findex gnus-summary-customize-parameters -Customize the group parameters (@pxref{Group Parameters}) of the current -group (@code{gnus-summary-customize-parameters}). - -@end table - - -@node Exiting the Summary Buffer -@section Exiting the Summary Buffer -@cindex summary exit -@cindex exiting groups - -Exiting from the summary buffer will normally update all info on the -group and return you to the group buffer. - -@table @kbd - -@item Z Z -@itemx Z Q -@itemx q -@kindex Z Z (Summary) -@kindex Z Q (Summary) -@kindex q (Summary) -@findex gnus-summary-exit -@vindex gnus-summary-exit-hook -@vindex gnus-summary-prepare-exit-hook -@vindex gnus-group-no-more-groups-hook -@c @icon{gnus-summary-exit} -Exit the current group and update all information on the group -(@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is -called before doing much of the exiting, which calls -@code{gnus-summary-expire-articles} by default. -@code{gnus-summary-exit-hook} is called after finishing the exit -process. @code{gnus-group-no-more-groups-hook} is run when returning to -group mode having no more (unread) groups. - -@item Z E -@itemx Q -@kindex Z E (Summary) -@kindex Q (Summary) -@findex gnus-summary-exit-no-update -Exit the current group without updating any information on the group -(@code{gnus-summary-exit-no-update}). - -@item Z c -@itemx c -@kindex Z c (Summary) -@kindex c (Summary) -@findex gnus-summary-catchup-and-exit -@c @icon{gnus-summary-catchup-and-exit} -Mark all unticked articles in the group as read and then exit -(@code{gnus-summary-catchup-and-exit}). - -@item Z C -@kindex Z C (Summary) -@findex gnus-summary-catchup-all-and-exit -Mark all articles, even the ticked ones, as read and then exit -(@code{gnus-summary-catchup-all-and-exit}). - -@item Z n -@kindex Z n (Summary) -@findex gnus-summary-catchup-and-goto-next-group -Mark all articles as read and go to the next group -(@code{gnus-summary-catchup-and-goto-next-group}). - -@item Z p -@kindex Z p (Summary) -@findex gnus-summary-catchup-and-goto-prev-group -Mark all articles as read and go to the previous group -(@code{gnus-summary-catchup-and-goto-prev-group}). - -@item Z R -@itemx C-x C-s -@kindex Z R (Summary) -@kindex C-x C-s (Summary) -@findex gnus-summary-reselect-current-group -Exit this group, and then enter it again -(@code{gnus-summary-reselect-current-group}). If given a prefix, select -all articles, both read and unread. - -@item Z G -@itemx M-g -@kindex Z G (Summary) -@kindex M-g (Summary) -@findex gnus-summary-rescan-group -@c @icon{gnus-summary-mail-get} -Exit the group, check for new articles in the group, and select the -group (@code{gnus-summary-rescan-group}). If given a prefix, select all -articles, both read and unread. - -@item Z N -@kindex Z N (Summary) -@findex gnus-summary-next-group -Exit the group and go to the next group -(@code{gnus-summary-next-group}). - -@item Z P -@kindex Z P (Summary) -@findex gnus-summary-prev-group -Exit the group and go to the previous group -(@code{gnus-summary-prev-group}). - -@item Z s -@kindex Z s (Summary) -@findex gnus-summary-save-newsrc -Save the current number of read/marked articles in the dribble buffer -and then save the dribble buffer (@code{gnus-summary-save-newsrc}). If -given a prefix, also save the @file{.newsrc} file(s). Using this -command will make exit without updating (the @kbd{Q} command) worthless. -@end table - -@vindex gnus-exit-group-hook -@code{gnus-exit-group-hook} is called when you exit the current group -with an ``updating'' exit. For instance @kbd{Q} -(@code{gnus-summary-exit-no-update}) does not call this hook. - -@findex gnus-summary-wake-up-the-dead -@findex gnus-dead-summary-mode -@vindex gnus-kill-summary-on-exit -If you're in the habit of exiting groups, and then changing your mind -about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}. -If you do that, Gnus won't kill the summary buffer when you exit it. -(Quelle surprise!) Instead it will change the name of the buffer to -something like @file{*Dead Summary ... *} and install a minor mode -called @code{gnus-dead-summary-mode}. Now, if you switch back to this -buffer, you'll find that all keys are mapped to a function called -@code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead -summary buffer will result in a live, normal summary buffer. - -There will never be more than one dead summary buffer at any one time. - -@vindex gnus-use-cross-reference -The data on the current group will be updated (which articles you have -read, which articles you have replied to, etc.)@: when you exit the -summary buffer. If the @code{gnus-use-cross-reference} variable is -@code{t} (which is the default), articles that are cross-referenced to -this group and are marked as read, will also be marked as read in the -other subscribed groups they were cross-posted to. If this variable is -neither @code{nil} nor @code{t}, the article will be marked as read in -both subscribed and unsubscribed groups (@pxref{Crosspost Handling}). - - -@node Crosspost Handling -@section Crosspost Handling - -@cindex velveeta -@cindex spamming -Marking cross-posted articles as read ensures that you'll never have to -read the same article more than once. Unless, of course, somebody has -posted it to several groups separately. Posting the same article to -several groups (not cross-posting) is called @dfn{spamming}, and you are -by law required to send nasty-grams to anyone who perpetrates such a -heinous crime. - -Remember: Cross-posting is kinda ok, but posting the same article -separately to several groups is not. Massive cross-posting (aka. -@dfn{velveeta}) is to be avoided at all costs, and you can even use the -@code{gnus-summary-mail-crosspost-complaint} command to complain about -excessive crossposting (@pxref{Summary Mail Commands}). - -@cindex cross-posting -@cindex Xref -@cindex @acronym{NOV} -One thing that may cause Gnus to not do the cross-posting thing -correctly is if you use an @acronym{NNTP} server that supports @sc{xover} -(which is very nice, because it speeds things up considerably) which -does not include the @code{Xref} header in its @acronym{NOV} lines. This is -Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing -even with @sc{xover} by registering the @code{Xref} lines of all -articles you actually read, but if you kill the articles, or just mark -them as read without reading them, Gnus will not get a chance to snoop -the @code{Xref} lines out of these articles, and will be unable to use -the cross reference mechanism. - -@cindex LIST overview.fmt -@cindex overview.fmt -To check whether your @acronym{NNTP} server includes the @code{Xref} header -in its overview files, try @samp{telnet your.nntp.server nntp}, -@samp{MODE READER} on @code{inn} servers, and then say @samp{LIST -overview.fmt}. This may not work, but if it does, and the last line you -get does not read @samp{Xref:full}, then you should shout and whine at -your news admin until she includes the @code{Xref} header in the -overview files. - -If you want Gnus to get the @code{Xref}s right all the time, you have to -set @code{nntp-nov-is-evil} to @code{t}, which slows things down -considerably. Also @pxref{Slow/Expensive Connection}. - -C'est la vie. - -For an alternative approach, @pxref{Duplicate Suppression}. - - -@node Duplicate Suppression -@section Duplicate Suppression - -By default, Gnus tries to make sure that you don't have to read the same -article more than once by utilizing the crossposting mechanism -(@pxref{Crosspost Handling}). However, that simple and efficient -approach may not work satisfactory for some users for various -reasons. - -@enumerate -@item -The @acronym{NNTP} server may fail to generate the @code{Xref} header. This -is evil and not very common. - -@item -The @acronym{NNTP} server may fail to include the @code{Xref} header in the -@file{.overview} data bases. This is evil and all too common, alas. - -@item -You may be reading the same group (or several related groups) from -different @acronym{NNTP} servers. - -@item -You may be getting mail that duplicates articles posted to groups. -@end enumerate - -I'm sure there are other situations where @code{Xref} handling fails as -well, but these four are the most common situations. - -If, and only if, @code{Xref} handling fails for you, then you may -consider switching on @dfn{duplicate suppression}. If you do so, Gnus -will remember the @code{Message-ID}s of all articles you have read or -otherwise marked as read, and then, as if by magic, mark them as read -all subsequent times you see them---in @emph{all} groups. Using this -mechanism is quite likely to be somewhat inefficient, but not overly -so. It's certainly preferable to reading the same articles more than -once. - -Duplicate suppression is not a very subtle instrument. It's more like a -sledge hammer than anything else. It works in a very simple -fashion---if you have marked an article as read, it adds this Message-ID -to a cache. The next time it sees this Message-ID, it will mark the -article as read with the @samp{M} mark. It doesn't care what group it -saw the article in. - -@table @code -@item gnus-suppress-duplicates -@vindex gnus-suppress-duplicates -If non-@code{nil}, suppress duplicates. - -@item gnus-save-duplicate-list -@vindex gnus-save-duplicate-list -If non-@code{nil}, save the list of duplicates to a file. This will -make startup and shutdown take longer, so the default is @code{nil}. -However, this means that only duplicate articles read in a single Gnus -session are suppressed. - -@item gnus-duplicate-list-length -@vindex gnus-duplicate-list-length -This variable says how many @code{Message-ID}s to keep in the duplicate -suppression list. The default is 10000. - -@item gnus-duplicate-file -@vindex gnus-duplicate-file -The name of the file to store the duplicate suppression list in. The -default is @file{~/News/suppression}. -@end table - -If you have a tendency to stop and start Gnus often, setting -@code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If -you leave Gnus running for weeks on end, you may have it @code{nil}. On -the other hand, saving the list makes startup and shutdown much slower, -so that means that if you stop and start Gnus often, you should set -@code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up -to you to figure out, I think. - -@node Security -@section Security - -Gnus is able to verify signed messages or decrypt encrypted messages. -The formats that are supported are @acronym{PGP}, @acronym{PGP/MIME} -and @acronym{S/MIME}, however you need some external programs to get -things to work: - -@enumerate -@item -To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to -install an OpenPGP implementation such as GnuPG@. The Lisp interface -to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG, -epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg, -PGG Manual}), and Mailcrypt are also supported. - -@item -To handle @acronym{S/MIME} message, you need to install OpenSSL@. OpenSSL 0.9.6 -or newer is recommended. - -@end enumerate - -The variables that control security functionality on reading/composing -messages include: - -@table @code -@item mm-verify-option -@vindex mm-verify-option -Option of verifying signed parts. @code{never}, not verify; -@code{always}, always verify; @code{known}, only verify known -protocols. Otherwise, ask user. - -@item mm-decrypt-option -@vindex mm-decrypt-option -Option of decrypting encrypted parts. @code{never}, no decryption; -@code{always}, always decrypt; @code{known}, only decrypt known -protocols. Otherwise, ask user. - -@item mm-sign-option -@vindex mm-sign-option -Option of creating signed parts. @code{nil}, use default signing -keys; @code{guided}, ask user to select signing keys from the menu. - -@item mm-encrypt-option -@vindex mm-encrypt-option -Option of creating encrypted parts. @code{nil}, use the first -public-key matching the @samp{From:} header as the recipient; -@code{guided}, ask user to select recipient keys from the menu. - -@item mml1991-use -@vindex mml1991-use -Symbol indicating elisp interface to OpenPGP implementation for -@acronym{PGP} messages. The default is @code{epg}, but @code{pgg}, -and @code{mailcrypt} are also supported although -deprecated. By default, Gnus uses the first available interface in -this order. - -@item mml2015-use -@vindex mml2015-use -Symbol indicating elisp interface to OpenPGP implementation for -@acronym{PGP/MIME} messages. The default is @code{epg}, but -@code{pgg}, and @code{mailcrypt} are also supported -although deprecated. By default, Gnus uses the first available -interface in this order. - -@end table - -By default the buttons that display security information are not -shown, because they clutter reading the actual e-mail. You can type -@kbd{K b} manually to display the information. Use the -@code{gnus-buttonized-mime-types} and -@code{gnus-unbuttonized-mime-types} variables to control this -permanently. @ref{MIME Commands} for further details, and hints on -how to customize these variables to always display security -information. - -@cindex snarfing keys -@cindex importing PGP keys -@cindex PGP key ring import -Snarfing OpenPGP keys (i.e., importing keys from articles into your -key ring) is not supported explicitly through a menu item or command, -rather Gnus do detect and label keys as @samp{application/pgp-keys}, -allowing you to specify whatever action you think is appropriate -through the usual @acronym{MIME} infrastructure. You can use a -@file{~/.mailcap} entry (@pxref{mailcap, , mailcap, emacs-mime, The -Emacs MIME Manual}) such as the following to import keys using GNU -Privacy Guard when you click on the @acronym{MIME} button -(@pxref{Using MIME}). - -@example -application/pgp-keys; gpg --import --interactive --verbose; needsterminal -@end example -@noindent -This happens to also be the default action defined in -@code{mailcap-mime-data}. - -More information on how to set things for sending outgoing signed and -encrypted messages up can be found in the message manual -(@pxref{Security, ,Security, message, Message Manual}). - -@node Mailing List -@section Mailing List -@cindex mailing list -@cindex RFC 2396 - -@kindex A M (summary) -@findex gnus-mailing-list-insinuate -Gnus understands some mailing list fields of RFC 2369. To enable it, -add a @code{to-list} group parameter (@pxref{Group Parameters}), -possibly using @kbd{A M} (@code{gnus-mailing-list-insinuate}) in the -summary buffer. - -That enables the following commands to the summary buffer: - -@table @kbd - -@item C-c C-n h -@kindex C-c C-n h (Summary) -@findex gnus-mailing-list-help -Send a message to fetch mailing list help, if List-Help field exists. - -@item C-c C-n s -@kindex C-c C-n s (Summary) -@findex gnus-mailing-list-subscribe -Send a message to subscribe the mailing list, if List-Subscribe field exists. - -@item C-c C-n u -@kindex C-c C-n u (Summary) -@findex gnus-mailing-list-unsubscribe -Send a message to unsubscribe the mailing list, if List-Unsubscribe -field exists. - -@item C-c C-n p -@kindex C-c C-n p (Summary) -@findex gnus-mailing-list-post -Post to the mailing list, if List-Post field exists. - -@item C-c C-n o -@kindex C-c C-n o (Summary) -@findex gnus-mailing-list-owner -Send a message to the mailing list owner, if List-Owner field exists. - -@item C-c C-n a -@kindex C-c C-n a (Summary) -@findex gnus-mailing-list-archive -Browse the mailing list archive, if List-Archive field exists. - -@end table - - -@node Article Buffer -@chapter Article Buffer -@cindex article buffer - -The articles are displayed in the article buffer, of which there is only -one. All the summary buffers share the same article buffer unless you -tell Gnus otherwise. - -@menu -* Hiding Headers:: Deciding what headers should be displayed. -* Using MIME:: Pushing articles through @acronym{MIME} before reading them. -* HTML:: Reading @acronym{HTML} messages. -* Customizing Articles:: Tailoring the look of the articles. -* Article Keymap:: Keystrokes available in the article buffer. -* Misc Article:: Other stuff. -@end menu - - -@node Hiding Headers -@section Hiding Headers -@cindex hiding headers -@cindex deleting headers - -The top section of each article is the @dfn{head}. (The rest is the -@dfn{body}, but you may have guessed that already.) - -@vindex gnus-show-all-headers -There is a lot of useful information in the head: the name of the person -who wrote the article, the date it was written and the subject of the -article. That's well and nice, but there's also lots of information -most people do not want to see---what systems the article has passed -through before reaching you, the @code{Message-ID}, the -@code{References}, etc. ad nauseam---and you'll probably want to get rid -of some of those lines. If you want to keep all those lines in the -article buffer, you can set @code{gnus-show-all-headers} to @code{t}. - -Gnus provides you with two variables for sifting headers: - -@table @code - -@item gnus-visible-headers -@vindex gnus-visible-headers -If this variable is non-@code{nil}, it should be a regular expression -that says what headers you wish to keep in the article buffer. All -headers that do not match this variable will be hidden. - -For instance, if you only want to see the name of the person who wrote -the article and the subject, you'd say: - -@lisp -(setq gnus-visible-headers "^From:\\|^Subject:") -@end lisp - -This variable can also be a list of regexps to match headers to -remain visible. - -@item gnus-ignored-headers -@vindex gnus-ignored-headers -This variable is the reverse of @code{gnus-visible-headers}. If this -variable is set (and @code{gnus-visible-headers} is @code{nil}), it -should be a regular expression that matches all lines that you want to -hide. All lines that do not match this variable will remain visible. - -For instance, if you just want to get rid of the @code{References} line -and the @code{Xref} line, you might say: - -@lisp -(setq gnus-ignored-headers "^References:\\|^Xref:") -@end lisp - -This variable can also be a list of regexps to match headers to -be removed. - -Note that if @code{gnus-visible-headers} is non-@code{nil}, this -variable will have no effect. - -@end table - -@vindex gnus-sorted-header-list -Gnus can also sort the headers for you. (It does this by default.) You -can control the sorting by setting the @code{gnus-sorted-header-list} -variable. It is a list of regular expressions that says in what order -the headers are to be displayed. - -For instance, if you want the name of the author of the article first, -and then the subject, you might say something like: - -@lisp -(setq gnus-sorted-header-list '("^From:" "^Subject:")) -@end lisp - -Any headers that are to remain visible, but are not listed in this -variable, will be displayed in random order after all the headers listed in this variable. - -@findex gnus-article-hide-boring-headers -@vindex gnus-boring-article-headers -You can hide further boring headers by setting -@code{gnus-treat-hide-boring-headers} to @code{head}. What this function -does depends on the @code{gnus-boring-article-headers} variable. It's a -list, but this list doesn't actually contain header names. Instead it -lists various @dfn{boring conditions} that Gnus can check and remove -from sight. - -These conditions are: -@table @code -@item empty -Remove all empty headers. -@item followup-to -Remove the @code{Followup-To} header if it is identical to the -@code{Newsgroups} header. -@item reply-to -Remove the @code{Reply-To} header if it lists the same addresses as -the @code{From} header, or if the @code{broken-reply-to} group -parameter is set. -@item newsgroups -Remove the @code{Newsgroups} header if it only contains the current group -name. -@item to-address -Remove the @code{To} header if it only contains the address identical to -the current group's @code{to-address} parameter. -@item to-list -Remove the @code{To} header if it only contains the address identical to -the current group's @code{to-list} parameter. -@item cc-list -Remove the @code{Cc} header if it only contains the address identical to -the current group's @code{to-list} parameter. -@item date -Remove the @code{Date} header if the article is less than three days -old. -@item long-to -Remove the @code{To} and/or @code{Cc} header if it is very long. -@item many-to -Remove all @code{To} and/or @code{Cc} headers if there are more than one. -@end table - -To include these three elements, you could say something like: - -@lisp -(setq gnus-boring-article-headers - '(empty followup-to reply-to)) -@end lisp - -This is also the default value for this variable. - - -@node Using MIME -@section Using MIME -@cindex @acronym{MIME} - -Mime is a standard for waving your hands through the air, aimlessly, -while people stand around yawning. - -@acronym{MIME}, however, is a standard for encoding your articles, aimlessly, -while all newsreaders die of fear. - -@acronym{MIME} may specify what character set the article uses, the encoding -of the characters, and it also makes it possible to embed pictures and -other naughty stuff in innocent-looking articles. - -@vindex gnus-display-mime-function -@findex gnus-display-mime -Gnus pushes @acronym{MIME} articles through @code{gnus-display-mime-function} -to display the @acronym{MIME} parts. This is @code{gnus-display-mime} by -default, which creates a bundle of clickable buttons that can be used to -display, save and manipulate the @acronym{MIME} objects. - -The following commands are available when you have placed point over a -@acronym{MIME} button: - -@table @kbd -@findex gnus-article-press-button -@item RET (Article) -@kindex RET (Article) -@itemx BUTTON-2 (Article) -Toggle displaying of the @acronym{MIME} object -(@code{gnus-article-press-button}). If built-in viewers can not display -the object, Gnus resorts to external viewers in the @file{mailcap} -files. If a viewer has the @samp{copiousoutput} specification, the -object is displayed inline. - -@findex gnus-mime-view-part -@item M-RET (Article) -@kindex M-RET (Article) -@itemx v (Article) -Prompt for a method, and then view the @acronym{MIME} object using this -method (@code{gnus-mime-view-part}). - -@findex gnus-mime-view-part-as-type -@item t (Article) -@kindex t (Article) -View the @acronym{MIME} object as if it were a different @acronym{MIME} media type -(@code{gnus-mime-view-part-as-type}). - -@findex gnus-mime-view-part-as-charset -@item C (Article) -@kindex C (Article) -Prompt for a charset, and then view the @acronym{MIME} object using this -charset (@code{gnus-mime-view-part-as-charset}). - -@findex gnus-mime-save-part -@item o (Article) -@kindex o (Article) -Prompt for a file name, and then save the @acronym{MIME} object -(@code{gnus-mime-save-part}). - -@findex gnus-mime-save-part-and-strip -@item C-o (Article) -@kindex C-o (Article) -Prompt for a file name, then save the @acronym{MIME} object and strip it from -the article. Then proceed to article editing, where a reasonable -suggestion is being made on how the altered article should look -like. The stripped @acronym{MIME} object will be referred via the -message/external-body @acronym{MIME} type. -(@code{gnus-mime-save-part-and-strip}). - -@findex gnus-mime-replace-part -@item r (Article) -@kindex r (Article) -Prompt for a file name, replace the @acronym{MIME} object with an -external body referring to the file via the message/external-body -@acronym{MIME} type. (@code{gnus-mime-replace-part}). - -@findex gnus-mime-delete-part -@item d (Article) -@kindex d (Article) -Delete the @acronym{MIME} object from the article and replace it with some -information about the removed @acronym{MIME} object -(@code{gnus-mime-delete-part}). - -@c FIXME: gnus-auto-select-part should be documented here - -@findex gnus-mime-copy-part -@item c (Article) -@kindex c (Article) -Copy the @acronym{MIME} object to a fresh buffer and display this buffer -(@code{gnus-mime-copy-part}). If given a prefix, copy the raw contents -without decoding. If given a numerical prefix, you can do semi-manual -charset stuff (see @code{gnus-summary-show-article-charset-alist} in -@ref{Paging the Article}). Compressed files like @file{.gz} and -@file{.bz2} are automatically decompressed if -@code{auto-compression-mode} is enabled (@pxref{Compressed Files,, -Accessing Compressed Files, emacs, The Emacs Editor}). - -@findex gnus-mime-print-part -@item p (Article) -@kindex p (Article) -Print the @acronym{MIME} object (@code{gnus-mime-print-part}). This -command respects the @samp{print=} specifications in the -@file{.mailcap} file. - -@findex gnus-mime-inline-part -@item i (Article) -@kindex i (Article) -Insert the contents of the @acronym{MIME} object into the buffer -(@code{gnus-mime-inline-part}) as @samp{text/plain}. If given a prefix, insert -the raw contents without decoding. If given a numerical prefix, you can -do semi-manual charset stuff (see -@code{gnus-summary-show-article-charset-alist} in @ref{Paging the -Article}). Compressed files like @file{.gz} and @file{.bz2} are -automatically decompressed depending on @code{jka-compr} regardless of -@code{auto-compression-mode} (@pxref{Compressed Files,, Accessing -Compressed Files, emacs, The Emacs Editor}). - -@findex gnus-mime-view-part-internally -@item E (Article) -@kindex E (Article) -View the @acronym{MIME} object with an internal viewer. If no internal -viewer is available, use an external viewer -(@code{gnus-mime-view-part-internally}). - -@findex gnus-mime-view-part-externally -@item e (Article) -@kindex e (Article) -View the @acronym{MIME} object with an external viewer. -(@code{gnus-mime-view-part-externally}). - -@findex gnus-mime-pipe-part -@item | (Article) -@kindex | (Article) -Output the @acronym{MIME} object to a process (@code{gnus-mime-pipe-part}). - -@findex gnus-mime-action-on-part -@item . (Article) -@kindex . (Article) -Interactively run an action on the @acronym{MIME} object -(@code{gnus-mime-action-on-part}). - -@end table - -Gnus will display some @acronym{MIME} objects automatically. The way Gnus -determines which parts to do this with is described in the Emacs -@acronym{MIME} manual. - -It might be best to just use the toggling functions from the article -buffer to avoid getting nasty surprises. (For instance, you enter the -group @samp{alt.sing-a-long} and, before you know it, @acronym{MIME} has -decoded the sound file in the article and some horrible sing-a-long song -comes screaming out your speakers, and you can't find the volume button, -because there isn't one, and people are starting to look at you, and you -try to stop the program, but you can't, and you can't find the program -to control the volume, and everybody else in the room suddenly decides -to look at you disdainfully, and you'll feel rather stupid.) - -Any similarity to real events and people is purely coincidental. Ahem. - -Also @pxref{MIME Commands}. - - -@node HTML -@section @acronym{HTML} -@cindex @acronym{HTML} - -If you have @code{w3m} installed on your system, Gnus can display -@acronym{HTML} articles in the article buffer. There are many Gnus -add-ons for doing this, using various approaches, but there's one -(sort of) built-in method that's used by default. - -For a complete overview, consult @xref{Display Customization, -,Display Customization, emacs-mime, The Emacs MIME Manual}. This -section only describes the default method. - -@table @code -@item mm-text-html-renderer -@vindex mm-text-html-renderer -If set to @code{gnus-article-html}, Gnus will use the built-in method, -that's based on @code{w3m}. - -@item gnus-blocked-images -@vindex gnus-blocked-images -External images that have @acronym{URL}s that match this regexp won't -be fetched and displayed. For instance, do block all @acronym{URL}s -that have the string ``ads'' in them, do the following: - -@lisp -(setq gnus-blocked-images "ads") -@end lisp - -This can also be a function to be evaluated. If so, it will be -called with the group name as the parameter. The default value is -@code{gnus-block-private-groups}, which will return @samp{"."} for -anything that isn't a newsgroup. This means that no external images -will be fetched as a result of reading mail, so that nobody can use -web bugs (and the like) to track whether you've read email. - -Also @pxref{Misc Article} for @code{gnus-inhibit-images}. - -@item gnus-html-cache-directory -@vindex gnus-html-cache-directory -Gnus will download and cache images according to how -@code{gnus-blocked-images} is set. These images will be stored in -this directory. - -@item gnus-html-cache-size -@vindex gnus-html-cache-size -When @code{gnus-html-cache-size} bytes have been used in that -directory, the oldest files will be deleted. The default is 500MB. - -@item gnus-html-frame-width -@vindex gnus-html-frame-width -The width to use when rendering HTML@. The default is 70. - -@item gnus-max-image-proportion -@vindex gnus-max-image-proportion -How big pictures displayed are in relation to the window they're in. -A value of 0.7 (the default) means that they are allowed to take up -70% of the width and height of the window. If they are larger than -this, and Emacs supports it, then the images will be rescaled down to -fit these criteria. - -@end table - -To use this, make sure that you have @code{w3m} and @code{curl} -installed. If you have, then Gnus should display @acronym{HTML} -automatically. - - - -@node Customizing Articles -@section Customizing Articles -@cindex article customization - -A slew of functions for customizing how the articles are to look like -exist. You can call these functions interactively -(@pxref{Article Washing}), or you can have them -called automatically when you select the articles. - -To have them called automatically, you should set the corresponding -``treatment'' variable. For instance, to have headers hidden, you'd set -@code{gnus-treat-hide-headers}. Below is a list of variables that can -be set, but first we discuss the values these variables can have. - -Note: Some values, while valid, make little sense. Check the list below -for sensible values. - -@enumerate -@item -@code{nil}: Don't do this treatment. - -@item -@code{t}: Do this treatment on all body parts. - -@item -@code{head}: Do the treatment on the headers. - -@item -@code{first}: Do this treatment on the first body part. - -@item -@code{last}: Do this treatment on the last body part. - -@item -An integer: Do this treatment on all body parts that have a length less -than this number. - -@item -A list of strings: Do this treatment on all body parts that are in -articles that are read in groups that have names that match one of the -regexps in the list. - -@item -A list where the first element is not a string: - -The list is evaluated recursively. The first element of the list is a -predicate. The following predicates are recognized: @code{or}, -@code{and}, @code{not} and @code{typep}. Here's an example: - -@lisp -(or last - (typep "text/x-vcard")) -@end lisp - -@item -A function: the function is called with no arguments and should return -@code{nil} or non-@code{nil}. The current article is available in the -buffer named by @code{gnus-article-buffer}. - -@end enumerate - -You may have noticed that the word @dfn{part} is used here. This refers -to the fact that some messages are @acronym{MIME} multipart articles that may -be divided into several parts. Articles that are not multiparts are -considered to contain just a single part. - -@vindex gnus-article-treat-types -Are the treatments applied to all sorts of multipart parts? Yes, if you -want to, but by default, only @samp{text/plain} parts are given the -treatment. This is controlled by the @code{gnus-article-treat-types} -variable, which is a list of regular expressions that are matched to the -type of the part. This variable is ignored if the value of the -controlling variable is a predicate list, as described above. - -@ifinfo -@c Avoid sort of redundant entries in the same section for the printed -@c manual, but add them in info to allow `i gnus-treat-foo-bar RET' or -@c `i foo-bar'. -@vindex gnus-treat-buttonize -@vindex gnus-treat-buttonize-head -@vindex gnus-treat-capitalize-sentences -@vindex gnus-treat-overstrike -@vindex gnus-treat-strip-cr -@vindex gnus-treat-strip-headers-in-body -@vindex gnus-treat-strip-leading-blank-lines -@vindex gnus-treat-strip-multiple-blank-lines -@vindex gnus-treat-strip-pem -@vindex gnus-treat-strip-trailing-blank-lines -@vindex gnus-treat-unsplit-urls -@vindex gnus-treat-wash-html -@vindex gnus-treat-date -@vindex gnus-treat-from-picon -@vindex gnus-treat-mail-picon -@vindex gnus-treat-newsgroups-picon -@vindex gnus-treat-from-gravatar -@vindex gnus-treat-mail-gravatar -@vindex gnus-treat-display-smileys -@vindex gnus-treat-body-boundary -@vindex gnus-treat-display-x-face -@vindex gnus-treat-display-face -@vindex gnus-treat-emphasize -@vindex gnus-treat-fill-article -@vindex gnus-treat-fill-long-lines -@vindex gnus-treat-hide-boring-headers -@vindex gnus-treat-hide-citation -@vindex gnus-treat-hide-citation-maybe -@vindex gnus-treat-hide-headers -@vindex gnus-treat-hide-signature -@vindex gnus-treat-strip-banner -@vindex gnus-treat-strip-list-identifiers -@vindex gnus-treat-highlight-citation -@vindex gnus-treat-highlight-headers -@vindex gnus-treat-highlight-signature -@vindex gnus-treat-play-sounds -@vindex gnus-treat-x-pgp-sig -@vindex gnus-treat-unfold-headers -@vindex gnus-treat-fold-headers -@vindex gnus-treat-fold-newsgroups -@vindex gnus-treat-leading-whitespace -@end ifinfo - -The following treatment options are available. The easiest way to -customize this is to examine the @code{gnus-article-treat} customization -group. Values in parenthesis are suggested sensible values. Others are -possible but those listed are probably sufficient for most people. - -@table @code -@item gnus-treat-buttonize (t, integer) -@item gnus-treat-buttonize-head (head) - -@xref{Article Buttons}. - -@item gnus-treat-capitalize-sentences (t, integer) -@item gnus-treat-overstrike (t, integer) -@item gnus-treat-strip-cr (t, integer) -@item gnus-treat-strip-headers-in-body (t, integer) -@item gnus-treat-strip-leading-blank-lines (t, first, integer) -@item gnus-treat-strip-multiple-blank-lines (t, integer) -@item gnus-treat-strip-pem (t, last, integer) -@item gnus-treat-strip-trailing-blank-lines (t, last, integer) -@item gnus-treat-unsplit-urls (t, integer) -@item gnus-treat-wash-html (t, integer) - -@xref{Article Washing}. - -@item gnus-treat-date (head) - -This will transform/add date headers according to the -@code{gnus-article-date-headers} variable. This is a list of Date -headers to display. The formats available are: - -@table @code -@item ut -Universal time, aka GMT, aka ZULU. - -@item local -The user's local time zone. - -@item english -A semi-readable English sentence. - -@item lapsed -The time elapsed since the message was posted. - -@item combined-lapsed -Both the original date header and a (shortened) elapsed time. - -@item original -The original date header. - -@item iso8601 -ISO8601 format, i.e., ``2010-11-23T22:05:21''. - -@item user-defined -A format done according to the @code{gnus-article-time-format} -variable. - -@end table - -@xref{Article Date}. - -@item gnus-treat-from-picon (head) -@item gnus-treat-mail-picon (head) -@item gnus-treat-newsgroups-picon (head) - -@xref{Picons}. - -@item gnus-treat-from-gravatar (head) -@item gnus-treat-mail-gravatar (head) - -@xref{Gravatars}. - -@item gnus-treat-display-smileys (t, integer) - -@item gnus-treat-body-boundary (head) - -@vindex gnus-body-boundary-delimiter -Adds a delimiter between header and body, the string used as delimiter -is controlled by @code{gnus-body-boundary-delimiter}. - -@xref{Smileys}. - -@vindex gnus-treat-display-x-face -@item gnus-treat-display-x-face (head) - -@xref{X-Face}. - -@vindex gnus-treat-display-face -@item gnus-treat-display-face (head) - -@xref{Face}. - -@vindex gnus-treat-emphasize -@item gnus-treat-emphasize (t, head, integer) -@vindex gnus-treat-fill-article -@item gnus-treat-fill-article (t, integer) -@vindex gnus-treat-fill-long-lines -@item gnus-treat-fill-long-lines (t, integer) -@vindex gnus-treat-hide-boring-headers -@item gnus-treat-hide-boring-headers (head) -@vindex gnus-treat-hide-citation -@item gnus-treat-hide-citation (t, integer) -@vindex gnus-treat-hide-citation-maybe -@item gnus-treat-hide-citation-maybe (t, integer) -@vindex gnus-treat-hide-headers -@item gnus-treat-hide-headers (head) -@vindex gnus-treat-hide-signature -@item gnus-treat-hide-signature (t, last) -@vindex gnus-treat-strip-banner -@item gnus-treat-strip-banner (t, last) -@vindex gnus-treat-strip-list-identifiers -@item gnus-treat-strip-list-identifiers (head) - -@xref{Article Hiding}. - -@vindex gnus-treat-highlight-citation -@item gnus-treat-highlight-citation (t, integer) -@vindex gnus-treat-highlight-headers -@item gnus-treat-highlight-headers (head) -@vindex gnus-treat-highlight-signature -@item gnus-treat-highlight-signature (t, last, integer) - -@xref{Article Highlighting}. - -@vindex gnus-treat-play-sounds -@item gnus-treat-play-sounds -@item gnus-treat-ansi-sequences (t) -@vindex gnus-treat-x-pgp-sig -@item gnus-treat-x-pgp-sig (head) - -@vindex gnus-treat-unfold-headers -@item gnus-treat-unfold-headers (head) -@vindex gnus-treat-fold-headers -@item gnus-treat-fold-headers (head) -@vindex gnus-treat-fold-newsgroups -@item gnus-treat-fold-newsgroups (head) -@vindex gnus-treat-leading-whitespace -@item gnus-treat-leading-whitespace (head) - -@xref{Article Header}. - - -@end table - -@vindex gnus-part-display-hook -You can, of course, write your own functions to be called from -@code{gnus-part-display-hook}. The functions are called narrowed to the -part, and you can do anything you like, pretty much. There is no -information that you have to keep in the buffer---you can change -everything. - - -@node Article Keymap -@section Article Keymap - -Most of the keystrokes in the summary buffer can also be used in the -article buffer. They should behave as if you typed them in the summary -buffer, which means that you don't actually have to have a summary -buffer displayed while reading. You can do it all from the article -buffer. - -@kindex v (Article) -@cindex keys, reserved for users (Article) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. - -A few additional keystrokes are available: - -@table @kbd - -@item SPACE -@kindex SPACE (Article) -@findex gnus-article-next-page -Scroll forwards one page (@code{gnus-article-next-page}). -This is exactly the same as @kbd{h SPACE h}. - -@item DEL -@kindex DEL (Article) -@findex gnus-article-prev-page -Scroll backwards one page (@code{gnus-article-prev-page}). -This is exactly the same as @kbd{h DEL h}. - -@item C-c ^ -@kindex C-c ^ (Article) -@findex gnus-article-refer-article -If point is in the neighborhood of a @code{Message-ID} and you press -@kbd{C-c ^}, Gnus will try to get that article from the server -(@code{gnus-article-refer-article}). - -@item C-c C-m -@kindex C-c C-m (Article) -@findex gnus-article-mail -Send a reply to the address near point (@code{gnus-article-mail}). If -given a prefix, include the mail. - -@item s -@kindex s (Article) -@findex gnus-article-show-summary -Reconfigure the buffers so that the summary buffer becomes visible -(@code{gnus-article-show-summary}). - -@item ? -@kindex ? (Article) -@findex gnus-article-describe-briefly -Give a very brief description of the available keystrokes -(@code{gnus-article-describe-briefly}). - -@item TAB -@kindex TAB (Article) -@findex gnus-article-next-button -Go to the next button, if any (@code{gnus-article-next-button}). This -only makes sense if you have buttonizing turned on. - -@item M-TAB -@kindex M-TAB (Article) -@findex gnus-article-prev-button -Go to the previous button, if any (@code{gnus-article-prev-button}). - -@item R -@kindex R (Article) -@findex gnus-article-reply-with-original -Send a reply to the current article and yank the current article -(@code{gnus-article-reply-with-original}). If the region is active, -only yank the text in the region. - -@item S W -@kindex S W (Article) -@findex gnus-article-wide-reply-with-original -Send a wide reply to the current article and yank the current article -(@code{gnus-article-wide-reply-with-original}). If the region is -active, only yank the text in the region. - -@item F -@kindex F (Article) -@findex gnus-article-followup-with-original -Send a followup to the current article and yank the current article -(@code{gnus-article-followup-with-original}). If the region is active, -only yank the text in the region. - - -@end table - - -@node Misc Article -@section Misc Article - -@table @code - -@item gnus-single-article-buffer -@vindex gnus-single-article-buffer -@cindex article buffers, several -If non-@code{nil}, use the same article buffer for all the groups. -(This is the default.) If @code{nil}, each group will have its own -article buffer. - -@item gnus-widen-article-window -@cindex gnus-widen-article-window -If non-@code{nil}, selecting the article buffer with the @kbd{h} -command will ``widen'' the article window to take the entire frame. - -@vindex gnus-article-decode-hook -@item gnus-article-decode-hook -@cindex @acronym{MIME} -Hook used to decode @acronym{MIME} articles. The default value is -@code{(article-decode-charset article-decode-encoded-words)} - -@vindex gnus-article-prepare-hook -@item gnus-article-prepare-hook -This hook is called right after the article has been inserted into the -article buffer. It is mainly intended for functions that do something -depending on the contents; it should probably not be used for changing -the contents of the article buffer. - -@item gnus-article-mode-hook -@vindex gnus-article-mode-hook -Hook called in article mode buffers. - -@item gnus-article-mode-syntax-table -@vindex gnus-article-mode-syntax-table -Syntax table used in article buffers. It is initialized from -@code{text-mode-syntax-table}. - -@vindex gnus-article-over-scroll -@item gnus-article-over-scroll -If non-@code{nil}, allow scrolling the article buffer even when there -no more new text to scroll in. The default is @code{nil}. - -@vindex gnus-article-mode-line-format -@item gnus-article-mode-line-format -This variable is a format string along the same lines as -@code{gnus-summary-mode-line-format} (@pxref{Summary Buffer Mode -Line}). It accepts the same format specifications as that variable, -with two extensions: - -@table @samp - -@item w -The @dfn{wash status} of the article. This is a short string with one -character for each possible article wash operation that may have been -performed. The characters and their meaning: - -@table @samp - -@item c -Displayed when cited text may be hidden in the article buffer. - -@item h -Displayed when headers are hidden in the article buffer. - -@item p -Displayed when article is digitally signed or encrypted, and Gnus has -hidden the security headers. (N.B. does not tell anything about -security status, i.e., good or bad signature.) - -@item s -Displayed when the signature has been hidden in the Article buffer. - -@item o -Displayed when Gnus has treated overstrike characters in the article buffer. - -@item e -Displayed when Gnus has treated emphasized strings in the article buffer. - -@end table - -@item m -The number of @acronym{MIME} parts in the article. - -@end table - -@vindex gnus-break-pages - -@item gnus-break-pages -Controls whether @dfn{page breaking} is to take place. If this variable -is non-@code{nil}, the articles will be divided into pages whenever a -page delimiter appears in the article. If this variable is @code{nil}, -paging will not be done. - -@item gnus-page-delimiter -@vindex gnus-page-delimiter -This is the delimiter mentioned above. By default, it is @samp{^L} -(formfeed). - -@cindex IDNA -@cindex internationalized domain names -@vindex gnus-use-idna -@item gnus-use-idna -This variable controls whether Gnus performs IDNA decoding of -internationalized domain names inside @samp{From}, @samp{To} and -@samp{Cc} headers. @xref{IDNA, ,IDNA,message, The Message Manual}, -for how to compose such messages. This requires -@uref{http://www.gnu.org/software/libidn/, GNU Libidn}, and this -variable is only enabled if you have installed it. - -@vindex gnus-inhibit-images -@item gnus-inhibit-images -If this is non-@code{nil}, inhibit displaying of images inline in the -article body. It is effective to images that are in articles as -@acronym{MIME} parts, and images in @acronym{HTML} articles rendered -when @code{mm-text-html-renderer} (@pxref{Display Customization, -,Display Customization, emacs-mime, The Emacs MIME Manual}) is -@code{shr} or @code{gnus-w3m}. - -@end table - - -@node Composing Messages -@chapter Composing Messages -@cindex composing messages -@cindex messages -@cindex mail -@cindex sending mail -@cindex reply -@cindex followup -@cindex post -@cindex using gpg -@cindex using s/mime -@cindex using smime - -@kindex C-c C-c (Post) -All commands for posting and mailing will put you in a message buffer -where you can edit the article all you like, before you send the -article by pressing @kbd{C-c C-c}. @xref{Top, , Overview, message, -Message Manual}. Where the message will be posted/mailed to depends -on your setup (@pxref{Posting Server}). - -@menu -* Mail:: Mailing and replying. -* Posting Server:: What server should you post and mail via? -* POP before SMTP:: You cannot send a mail unless you read a mail. -* Mail and Post:: Mailing and posting at the same time. -* Archived Messages:: Where Gnus stores the messages you've sent. -* Posting Styles:: An easier way to specify who you are. -* Drafts:: Postponing messages and rejected messages. -* Rejected Articles:: What happens if the server doesn't like your article? -* Signing and encrypting:: How to compose secure messages. -@end menu - -Also @pxref{Canceling and Superseding} for information on how to -remove articles you shouldn't have posted. - - -@node Mail -@section Mail - -Variables for customizing outgoing mail: - -@table @code -@item gnus-uu-digest-headers -@vindex gnus-uu-digest-headers -List of regexps to match headers included in digested messages. The -headers will be included in the sequence they are matched. If -@code{nil} include all headers. - -@item gnus-add-to-list -@vindex gnus-add-to-list -If non-@code{nil}, add a @code{to-list} group parameter to mail groups -that have none when you do a @kbd{a}. - -@item gnus-confirm-mail-reply-to-news -@vindex gnus-confirm-mail-reply-to-news -If non-@code{nil}, Gnus will ask you for a confirmation when you are -about to reply to news articles by mail. If it is @code{nil}, nothing -interferes in what you want to do. This can also be a function -receiving the group name as the only parameter which should return -non-@code{nil} if a confirmation is needed, or a regular expression -matching group names, where confirmation should be asked for. - -If you find yourself never wanting to reply to mail, but occasionally -press @kbd{R} anyway, this variable might be for you. - -@item gnus-confirm-treat-mail-like-news -@vindex gnus-confirm-treat-mail-like-news -If non-@code{nil}, Gnus also requests confirmation according to -@code{gnus-confirm-mail-reply-to-news} when replying to mail. This is -useful for treating mailing lists like newsgroups. - -@end table - - -@node Posting Server -@section Posting Server - -When you press those magical @kbd{C-c C-c} keys to ship off your latest -(extremely intelligent, of course) article, where does it go? - -Thank you for asking. I hate you. - -It can be quite complicated. - -@vindex gnus-post-method -When posting news, Message usually invokes @code{message-send-news} -(@pxref{News Variables, , News Variables, message, Message Manual}). -Normally, Gnus will post using the same select method as you're -reading from (which might be convenient if you're reading lots of -groups from different private servers). However. If the server -you're reading from doesn't allow posting, just reading, you probably -want to use some other server to post your (extremely intelligent and -fabulously interesting) articles. You can then set the -@code{gnus-post-method} to some other method: - -@lisp -(setq gnus-post-method '(nnspool "")) -@end lisp - -Now, if you've done this, and then this server rejects your article, or -this server is down, what do you do then? To override this variable you -can use a non-zero prefix to the @kbd{C-c C-c} command to force using -the ``current'' server, to get back the default behavior, for posting. - -If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command, -Gnus will prompt you for what method to use for posting. - -You can also set @code{gnus-post-method} to a list of select methods. -If that's the case, Gnus will always prompt you for what method to use -for posting. - -Finally, if you want to always post using the native select method, -you can set this variable to @code{native}. - -@vindex message-send-mail-function -When sending mail, Message invokes the function specified by the -variable @code{message-send-mail-function}. Gnus tries to set it to a -value suitable for your system. -@xref{Mail Variables, ,Mail Variables,message,Message manual}, for more -information. - - -@node POP before SMTP -@section POP before SMTP -@cindex pop before smtp -@findex mail-source-touch-pop - -Does your @acronym{ISP} use @acronym{POP}-before-@acronym{SMTP} -authentication? This authentication method simply requires you to -contact the @acronym{POP} server before sending email. To do that, -put the following lines in your @file{~/.gnus.el} file: - -@lisp -(add-hook 'message-send-mail-hook 'mail-source-touch-pop) -@end lisp - -@noindent -The @code{mail-source-touch-pop} function does @acronym{POP} -authentication according to the value of @code{mail-sources} without -fetching mails, just before sending a mail. @xref{Mail Sources}. - -If you have two or more @acronym{POP} mail servers set in -@code{mail-sources}, you may want to specify one of them to -@code{mail-source-primary-source} as the @acronym{POP} mail server to be -used for the @acronym{POP}-before-@acronym{SMTP} authentication. If it -is your primary @acronym{POP} mail server (i.e., you are fetching mails -mainly from that server), you can set it permanently as follows: - -@lisp -(setq mail-source-primary-source - '(pop :server "pop3.mail.server" - :password "secret")) -@end lisp - -@noindent -Otherwise, bind it dynamically only when performing the -@acronym{POP}-before-@acronym{SMTP} authentication as follows: - -@lisp -(add-hook 'message-send-mail-hook - (lambda () - (let ((mail-source-primary-source - '(pop :server "pop3.mail.server" - :password "secret"))) - (mail-source-touch-pop)))) -@end lisp - - -@node Mail and Post -@section Mail and Post - -Here's a list of variables relevant to both mailing and -posting: - -@table @code -@item gnus-mailing-list-groups -@findex gnus-mailing-list-groups -@cindex mailing lists - -If your news server offers groups that are really mailing lists -gatewayed to the @acronym{NNTP} server, you can read those groups without -problems, but you can't post/followup to them without some difficulty. -One solution is to add a @code{to-address} to the group parameters -(@pxref{Group Parameters}). An easier thing to do is set the -@code{gnus-mailing-list-groups} to a regexp that matches the groups that -really are mailing lists. Then, at least, followups to the mailing -lists will work most of the time. Posting to these groups (@kbd{a}) is -still a pain, though. - -@item gnus-user-agent -@vindex gnus-user-agent -@cindex User-Agent - -This variable controls which information should be exposed in the -User-Agent header. It can be a list of symbols or a string. Valid -symbols are @code{gnus} (show Gnus version) and @code{emacs} (show Emacs -version). In addition to the Emacs version, you can add @code{codename} -(show (S)XEmacs codename) or either @code{config} (show system -configuration) or @code{type} (show system type). If you set it to a -string, be sure to use a valid format, see RFC 2616. - -@end table - -You may want to do spell-checking on messages that you send out. Or, if -you don't want to spell-check by hand, you could add automatic -spell-checking via the @code{ispell} package: - -@cindex ispell -@findex ispell-message -@lisp -(add-hook 'message-send-hook 'ispell-message) -@end lisp - -If you want to change the @code{ispell} dictionary based on what group -you're in, you could say something like the following: - -@lisp -(add-hook 'gnus-select-group-hook - (lambda () - (cond - ((string-match - "^de\\." (gnus-group-real-name gnus-newsgroup-name)) - (ispell-change-dictionary "deutsch")) - (t - (ispell-change-dictionary "english"))))) -@end lisp - -Modify to suit your needs. - -@vindex gnus-message-highlight-citation -If @code{gnus-message-highlight-citation} is @code{t}, different levels of -citations are highlighted like in Gnus article buffers also in message -mode buffers. - -@node Archived Messages -@section Archived Messages -@cindex archived messages -@cindex sent messages - -Gnus provides a few different methods for storing the mail and news you -send. The default method is to use the @dfn{archive virtual server} to -store the messages. If you want to disable this completely, the -@code{gnus-message-archive-group} variable should be @code{nil}. The -default is "sent.%Y-%m", which gives you one archive group per month. - -For archiving interesting messages in a group you read, see the -@kbd{B c} (@code{gnus-summary-copy-article}) command (@pxref{Mail -Group Commands}). - -@vindex gnus-message-archive-method -@code{gnus-message-archive-method} says what virtual server Gnus is to -use to store sent messages. The default is @code{"archive"}, and when -actually being used it is expanded into: - -@lisp -(nnfolder "archive" - (nnfolder-directory "~/Mail/archive") - (nnfolder-active-file "~/Mail/archive/active") - (nnfolder-get-new-mail nil) - (nnfolder-inhibit-expiry t)) -@end lisp - -@quotation -@vindex gnus-update-message-archive-method -Note: a server like this is saved in the @file{~/.newsrc.eld} file first -so that it may be used as a real method of the server which is named -@code{"archive"} (that is, for the case where -@code{gnus-message-archive-method} is set to @code{"archive"}) ever -since. If it once has been saved, it will never be updated by default -even if you change the value of @code{gnus-message-archive-method} -afterward. Therefore, the server @code{"archive"} doesn't necessarily -mean the @code{nnfolder} server like this at all times. If you want the -saved method to reflect always the value of -@code{gnus-message-archive-method}, set the -@code{gnus-update-message-archive-method} variable to a non-@code{nil} -value. The default value of this variable is @code{nil}. -@end quotation - -You can, however, use any mail select method (@code{nnml}, -@code{nnmbox}, etc.). @code{nnfolder} is a quite likable select method -for doing this sort of thing, though. If you don't like the default -directory chosen, you could say something like: - -@lisp -(setq gnus-message-archive-method - '(nnfolder "archive" - (nnfolder-inhibit-expiry t) - (nnfolder-active-file "~/News/sent-mail/active") - (nnfolder-directory "~/News/sent-mail/"))) -@end lisp - -@vindex gnus-message-archive-group -@cindex Gcc -Gnus will insert @code{Gcc} headers in all outgoing messages that point -to one or more group(s) on that server. Which group to use is -determined by the @code{gnus-message-archive-group} variable. - -This variable can be used to do the following: - -@table @asis -@item a string -Messages will be saved in that group. - -Note that you can include a select method in the group name, then the -message will not be stored in the select method given by -@code{gnus-message-archive-method}, but in the select method specified -by the group name, instead. Suppose @code{gnus-message-archive-method} -has the default value shown above. Then setting -@code{gnus-message-archive-group} to @code{"foo"} means that outgoing -messages are stored in @samp{nnfolder+archive:foo}, but if you use the -value @code{"nnml:foo"}, then outgoing messages will be stored in -@samp{nnml:foo}. - -@item a list of strings -Messages will be saved in all those groups. - -@item an alist of regexps, functions and forms -When a key ``matches'', the result is used. - -@item @code{nil} -No message archiving will take place. -@end table - -Let's illustrate: - -Just saving to a single group called @samp{MisK}: -@lisp -(setq gnus-message-archive-group "MisK") -@end lisp - -Saving to two groups, @samp{MisK} and @samp{safe}: -@lisp -(setq gnus-message-archive-group '("MisK" "safe")) -@end lisp - -Save to different groups based on what group you are in: -@lisp -(setq gnus-message-archive-group - '(("^alt" "sent-to-alt") - ("mail" "sent-to-mail") - (".*" "sent-to-misc"))) -@end lisp - -More complex stuff: -@lisp -(setq gnus-message-archive-group - '((if (message-news-p) - "misc-news" - "misc-mail"))) -@end lisp - -How about storing all news messages in one file, but storing all mail -messages in one file per month: - -@lisp -(setq gnus-message-archive-group - '((if (message-news-p) - "misc-news" - (concat "mail." (format-time-string "%Y-%m"))))) -@end lisp - -Now, when you send a message off, it will be stored in the appropriate -group. (If you want to disable storing for just one particular message, -you can just remove the @code{Gcc} header that has been inserted.) The -archive group will appear in the group buffer the next time you start -Gnus, or the next time you press @kbd{F} in the group buffer. You can -enter it and read the articles in it just like you'd read any other -group. If the group gets really big and annoying, you can simply rename -if (using @kbd{G r} in the group buffer) to something -nice---@samp{misc-mail-september-1995}, or whatever. New messages will -continue to be stored in the old (now empty) group. - -@table @code -@item gnus-gcc-mark-as-read -@vindex gnus-gcc-mark-as-read -If non-@code{nil}, automatically mark @code{Gcc} articles as read. - -@item gnus-gcc-externalize-attachments -@vindex gnus-gcc-externalize-attachments -If @code{nil}, attach files as normal parts in Gcc copies; if a regexp -and matches the Gcc group name, attach files as external parts; if it is -@code{all}, attach local files as external parts; if it is other -non-@code{nil}, the behavior is the same as @code{all}, but it may be -changed in the future. - -@item gnus-gcc-self-resent-messages -@vindex gnus-gcc-self-resent-messages -Like the @code{gcc-self} group parameter, applied only for unmodified -messages that @code{gnus-summary-resend-message} (@pxref{Summary Mail -Commands}) resends. Non-@code{nil} value of this variable takes -precedence over any existing @code{Gcc} header. - -If this is @code{none}, no @code{Gcc} copy will be made. If this is -@code{t}, messages resent will be @code{Gcc} copied to the current -group. If this is a string, it specifies a group to which resent -messages will be @code{Gcc} copied. If this is @code{nil}, @code{Gcc} -will be done according to existing @code{Gcc} header(s), if any. If -this is @code{no-gcc-self}, that is the default, resent messages will be -@code{Gcc} copied to groups that existing @code{Gcc} header specifies, -except for the current group. - -@item gnus-gcc-pre-body-encode-hook -@vindex gnus-gcc-pre-body-encode-hook -@itemx gnus-gcc-post-body-encode-hook -@vindex gnus-gcc-post-body-encode-hook - -These hooks are run before/after encoding the message body of the Gcc -copy of a sent message. The current buffer (when the hook is run) -contains the message including the message header. Changes made to -the message will only affect the Gcc copy, but not the original -message. You can use these hooks to edit the copy (and influence -subsequent transformations), e.g., remove MML secure tags -(@pxref{Signing and encrypting}). - -@end table - - -@node Posting Styles -@section Posting Styles -@cindex posting styles -@cindex styles - -All them variables, they make my head swim. - -So what if you want a different @code{Organization} and signature based -on what groups you post to? And you post both from your home machine -and your work machine, and you want different @code{From} lines, and so -on? - -@vindex gnus-posting-styles -One way to do stuff like that is to write clever hooks that change the -variables you need to have changed. That's a bit boring, so somebody -came up with the bright idea of letting the user specify these things in -a handy alist. Here's an example of a @code{gnus-posting-styles} -variable: - -@lisp -((".*" - (signature "Peace and happiness") - (organization "What me?")) - ("^comp" - (signature "Death to everybody")) - ("comp.emacs.i-love-it" - (organization "Emacs is it"))) -@end lisp - -As you might surmise from this example, this alist consists of several -@dfn{styles}. Each style will be applicable if the first element -``matches'', in some form or other. The entire alist will be iterated -over, from the beginning towards the end, and each match will be -applied, which means that attributes in later styles that match override -the same attributes in earlier matching styles. So -@samp{comp.programming.literate} will have the @samp{Death to everybody} -signature and the @samp{What me?} @code{Organization} header. - -The first element in each style is called the @code{match}. If it's a -string, then Gnus will try to regexp match it against the group name. -If it is the form @code{(header @var{match} @var{regexp})}, then Gnus -will look in the original article for a header whose name is -@var{match} and compare that @var{regexp}. @var{match} and -@var{regexp} are strings. (The original article is the one you are -replying or following up to. If you are not composing a reply or a -followup, then there is nothing to match against.) If the -@code{match} is a function symbol, that function will be called with -no arguments. If it's a variable symbol, then the variable will be -referenced. If it's a list, then that list will be @code{eval}ed. In -any case, if this returns a non-@code{nil} value, then the style is -said to @dfn{match}. - -Each style may contain an arbitrary amount of @dfn{attributes}. Each -attribute consists of a @code{(@var{name} @var{value})} pair. In -addition, you can also use the @code{(@var{name} :file @var{value})} -form or the @code{(@var{name} :value @var{value})} form. Where -@code{:file} signifies @var{value} represents a file name and its -contents should be used as the attribute value, @code{:value} signifies -@var{value} does not represent a file name explicitly. The attribute -name can be one of: - -@itemize @bullet -@item @code{signature} -@item @code{signature-file} -@item @code{x-face-file} -@item @code{address}, overriding @code{user-mail-address} -@item @code{name}, overriding @code{(user-full-name)} -@item @code{body} -@end itemize - -Note that the @code{signature-file} attribute honors the variable -@code{message-signature-directory}. - -The attribute name can also be a string or a symbol. In that case, -this will be used as a header name, and the value will be inserted in -the headers of the article; if the value is @code{nil}, the header -name will be removed. If the attribute name is @code{eval}, the form -is evaluated, and the result is thrown away. - -The attribute value can be a string, a function with zero arguments -(the return value will be used), a variable (its value will be used) -or a list (it will be @code{eval}ed and the return value will be -used). The functions and sexps are called/@code{eval}ed in the -message buffer that is being set up. The headers of the current -article are available through the @code{message-reply-headers} -variable, which is a vector of the following headers: number subject -from date id references chars lines xref extra. - -In the case of a string value, if the @code{match} is a regular -expression, a @samp{gnus-match-substitute-replacement} is proceed on -the value to replace the positional parameters @samp{\@var{n}} by the -corresponding parenthetical matches (see @xref{Replacing Match,, -Replacing the Text that Matched, elisp, The Emacs Lisp Reference Manual}.) - -@vindex message-reply-headers - -If you wish to check whether the message you are about to compose is -meant to be a news article or a mail message, you can check the values -of the @code{message-news-p} and @code{message-mail-p} functions. - -@findex message-mail-p -@findex message-news-p - -So here's a new example: - -@lisp -(setq gnus-posting-styles - '((".*" - (signature-file "~/.signature") - (name "User Name") - (x-face-file "~/.xface") - (x-url (getenv "WWW_HOME")) - (organization "People's Front Against MWM")) - ("^rec.humor" - (signature my-funny-signature-randomizer)) - ((equal (system-name) "gnarly") ;; @r{A form} - (signature my-quote-randomizer)) - (message-news-p ;; @r{A function symbol} - (signature my-news-signature)) - (window-system ;; @r{A value symbol} - ("X-Window-System" (format "%s" window-system))) - ;; @r{If I'm replying to Larsi, set the Organization header.} - ((header "from" "larsi.*org") - (Organization "Somewhere, Inc.")) - ((posting-from-work-p) ;; @r{A user defined function} - (signature-file "~/.work-signature") - (address "user@@bar.foo") - (body "You are fired.\n\nSincerely, your boss.") - ("X-Message-SMTP-Method" "smtp smtp.example.org 587") - (organization "Important Work, Inc")) - ("nnml:.*" - (From (with-current-buffer gnus-article-buffer - (message-fetch-field "to")))) - ("^nn.+:" - (signature-file "~/.mail-signature")))) -@end lisp - -The @samp{nnml:.*} rule means that you use the @code{To} address as the -@code{From} address in all your outgoing replies, which might be handy -if you fill many roles. -You may also use @code{message-alternative-emails} instead. -@xref{Message Headers, ,Message Headers, message, Message Manual}. - -Of particular interest in the ``work-mail'' style is the -@samp{X-Message-SMTP-Method} header. It specifies how to send the -outgoing email. You may want to sent certain emails through certain -@acronym{SMTP} servers due to company policies, for instance. -@xref{Mail Variables, ,Message Variables, message, Message Manual}. - - -@node Drafts -@section Drafts -@cindex drafts - -If you are writing a message (mail or news) and suddenly remember that -you have a steak in the oven (or some pesto in the food processor, you -craaazy vegetarians), you'll probably wish there was a method to save -the message you are writing so that you can continue editing it some -other day, and send it when you feel its finished. - -Well, don't worry about it. Whenever you start composing a message of -some sort using the Gnus mail and post commands, the buffer you get will -automatically associate to an article in a special @dfn{draft} group. -If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the -article will be saved there. (Auto-save files also go to the draft -group.) - -@cindex nndraft -@vindex nndraft-directory -The draft group is a special group (which is implemented as an -@code{nndraft} group, if you absolutely have to know) called -@samp{nndraft:drafts}. The variable @code{nndraft-directory} says where -@code{nndraft} is to store its files. What makes this group special is -that you can't tick any articles in it or mark any articles as -read---all articles in the group are permanently unread. - -If the group doesn't exist, it will be created and you'll be subscribed -to it. The only way to make it disappear from the Group buffer is to -unsubscribe it. The special properties of the draft group comes from -a group property (@pxref{Group Parameters}), and if lost the group -behaves like any other group. This means the commands below will not -be available. To restore the special properties of the group, the -simplest way is to kill the group, using @kbd{C-k}, and restart -Gnus. The group is automatically created again with the -correct parameters. The content of the group is not lost. - -@c @findex gnus-dissociate-buffer-from-draft -@c @kindex C-c M-d (Mail) -@c @kindex C-c M-d (Post) -@c @findex gnus-associate-buffer-with-draft -@c @kindex C-c C-d (Mail) -@c @kindex C-c C-d (Post) -@c If you're writing some super-secret message that you later want to -@c encode with PGP before sending, you may wish to turn the auto-saving -@c (and association with the draft group) off. You never know who might be -@c interested in reading all your extremely valuable and terribly horrible -@c and interesting secrets. The @kbd{C-c M-d} -@c (@code{gnus-dissociate-buffer-from-draft}) command does that for you. -@c If you change your mind and want to turn the auto-saving back on again, -@c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that. -@c -@c @vindex gnus-use-draft -@c To leave association with the draft group off by default, set -@c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default. - -@findex gnus-draft-edit-message -@kindex D e (Draft) -When you want to continue editing the article, you simply enter the -draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do -that. You will be placed in a buffer where you left off. - -Rejected articles will also be put in this draft group (@pxref{Rejected -Articles}). - -@findex gnus-draft-send-all-messages -@kindex D s (Draft) -@findex gnus-draft-send-message -@kindex D S (Draft) -If you have lots of rejected messages you want to post (or mail) without -doing further editing, you can use the @kbd{D s} command -(@code{gnus-draft-send-message}). This command understands the -process/prefix convention (@pxref{Process/Prefix}). The @kbd{D S} -command (@code{gnus-draft-send-all-messages}) will ship off all messages -in the buffer. - -@findex gnus-draft-toggle-sending -@kindex D t (Draft) -If you have some messages that you wish not to send, you can use the -@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message -as unsendable. This is a toggling command. - -Finally, if you want to delete a draft, use the normal @kbd{B DEL} -command (@pxref{Mail Group Commands}). - - -@node Rejected Articles -@section Rejected Articles -@cindex rejected articles - -Sometimes a news server will reject an article. Perhaps the server -doesn't like your face. Perhaps it just feels miserable. Perhaps -@emph{there be demons}. Perhaps you have included too much cited text. -Perhaps the disk is full. Perhaps the server is down. - -These situations are, of course, totally beyond the control of Gnus. -(Gnus, of course, loves the way you look, always feels great, has angels -fluttering around inside of it, doesn't care about how much cited text -you include, never runs full and never goes down.) So Gnus saves these -articles until some later time when the server feels better. - -The rejected articles will automatically be put in a special draft group -(@pxref{Drafts}). When the server comes back up again, you'd then -typically enter that group and send all the articles off. - -@node Signing and encrypting -@section Signing and encrypting -@cindex using gpg -@cindex using s/mime -@cindex using smime - -Gnus can digitally sign and encrypt your messages, using vanilla -@acronym{PGP} format or @acronym{PGP/MIME} or @acronym{S/MIME}. For -decoding such messages, see the @code{mm-verify-option} and -@code{mm-decrypt-option} options (@pxref{Security}). - -@vindex gnus-message-replysign -@vindex gnus-message-replyencrypt -@vindex gnus-message-replysignencrypted -Often, you would like to sign replies to people who send you signed -messages. Even more often, you might want to encrypt messages which -are in reply to encrypted messages. Gnus offers -@code{gnus-message-replysign} to enable the former, and -@code{gnus-message-replyencrypt} for the latter. In addition, setting -@code{gnus-message-replysignencrypted} (on by default) will sign -automatically encrypted messages. - -Instructing @acronym{MML} to perform security operations on a -@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for -signing and the @kbd{C-c C-m c} key map for encryption, as follows. - -@table @kbd - -@item C-c C-m s s -@kindex C-c C-m s s (Message) -@findex mml-secure-message-sign-smime - -Digitally sign current message using @acronym{S/MIME}. - -@item C-c C-m s o -@kindex C-c C-m s o (Message) -@findex mml-secure-message-sign-pgp - -Digitally sign current message using @acronym{PGP}. - -@item C-c C-m s p -@kindex C-c C-m s p (Message) -@findex mml-secure-message-sign-pgp - -Digitally sign current message using @acronym{PGP/MIME}. - -@item C-c C-m c s -@kindex C-c C-m c s (Message) -@findex mml-secure-message-encrypt-smime - -Digitally encrypt current message using @acronym{S/MIME}. - -@item C-c C-m c o -@kindex C-c C-m c o (Message) -@findex mml-secure-message-encrypt-pgp - -Digitally encrypt current message using @acronym{PGP}. - -@item C-c C-m c p -@kindex C-c C-m c p (Message) -@findex mml-secure-message-encrypt-pgpmime - -Digitally encrypt current message using @acronym{PGP/MIME}. - -@item C-c C-m C-n -@kindex C-c C-m C-n (Message) -@findex mml-unsecure-message -Remove security related @acronym{MML} tags from message. - -@end table - -@xref{Security, ,Security, message, Message Manual}, for more information. - -@node Select Methods -@chapter Select Methods -@cindex foreign groups -@cindex select methods - -A @dfn{foreign group} is a group not read by the usual (or -default) means. It could be, for instance, a group from a different -@acronym{NNTP} server, it could be a virtual group, or it could be your own -personal mail group. - -A foreign group (or any group, really) is specified by a @dfn{name} and -a @dfn{select method}. To take the latter first, a select method is a -list where the first element says what back end to use (e.g., @code{nntp}, -@code{nnspool}, @code{nnml}) and the second element is the @dfn{server -name}. There may be additional elements in the select method, where the -value may have special meaning for the back end in question. - -One could say that a select method defines a @dfn{virtual server}---so -we do just that (@pxref{Server Buffer}). - -The @dfn{name} of the group is the name the back end will recognize the -group as. - -For instance, the group @samp{soc.motss} on the @acronym{NNTP} server -@samp{some.where.edu} will have the name @samp{soc.motss} and select -method @code{(nntp "some.where.edu")}. Gnus will call this group -@samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp} -back end just knows this group as @samp{soc.motss}. - -The different methods all have their peculiarities, of course. - -@menu -* Server Buffer:: Making and editing virtual servers. -* Getting News:: Reading USENET news with Gnus. -* Using IMAP:: Reading mail from @acronym{IMAP}. -* Getting Mail:: Reading your personal mail with Gnus. -* Browsing the Web:: Getting messages from a plethora of Web sources. -* Other Sources:: Reading directories, files. -* Combined Groups:: Combining groups into one group. -* Email Based Diary:: Using mails to manage diary events in Gnus. -* Gnus Unplugged:: Reading news and mail offline. -@end menu - - -@node Server Buffer -@section Server Buffer - -Traditionally, a @dfn{server} is a machine or a piece of software that -one connects to, and then requests information from. Gnus does not -connect directly to any real servers, but does all transactions through -one back end or other. But that's just putting one layer more between -the actual media and Gnus, so we might just as well say that each -back end represents a virtual server. - -For instance, the @code{nntp} back end may be used to connect to several -different actual @acronym{NNTP} servers, or, perhaps, to many different ports -on the same actual @acronym{NNTP} server. You tell Gnus which back end to -use, and what parameters to set by specifying a @dfn{select method}. - -These select method specifications can sometimes become quite -complicated---say, for instance, that you want to read from the -@acronym{NNTP} server @samp{news.funet.fi} on port number 13, which -hangs if queried for @acronym{NOV} headers and has a buggy select. Ahem. -Anyway, if you had to specify that for each group that used this -server, that would be too much work, so Gnus offers a way of naming -select methods, which is what you do in the server buffer. - -To enter the server buffer, use the @kbd{^} -(@code{gnus-group-enter-server-mode}) command in the group buffer. - -@menu -* Server Buffer Format:: You can customize the look of this buffer. -* Server Commands:: Commands to manipulate servers. -* Example Methods:: Examples server specifications. -* Creating a Virtual Server:: An example session. -* Server Variables:: Which variables to set. -* Servers and Methods:: You can use server names as select methods. -* Unavailable Servers:: Some servers you try to contact may be down. -@end menu - -@vindex gnus-server-mode-hook -@code{gnus-server-mode-hook} is run when creating the server buffer. - - -@node Server Buffer Format -@subsection Server Buffer Format -@cindex server buffer format - -@vindex gnus-server-line-format -You can change the look of the server buffer lines by changing the -@code{gnus-server-line-format} variable. This is a @code{format}-like -variable, with some simple extensions: - -@table @samp - -@item h -How the news is fetched---the back end name. - -@item n -The name of this server. - -@item w -Where the news is to be fetched from---the address. - -@item s -The opened/closed/denied status of the server. - -@item a -Whether this server is agentized. -@end table - -@vindex gnus-server-mode-line-format -The mode line can also be customized by using the -@code{gnus-server-mode-line-format} variable (@pxref{Mode Line -Formatting}). The following specs are understood: - -@table @samp -@item S -Server name. - -@item M -Server method. -@end table - -Also @pxref{Formatting Variables}. - - -@node Server Commands -@subsection Server Commands -@cindex server commands - -@table @kbd - -@item v -@kindex v (Server) -@cindex keys, reserved for users (Server) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. - -@item a -@kindex a (Server) -@findex gnus-server-add-server -Add a new server (@code{gnus-server-add-server}). - -@item e -@kindex e (Server) -@findex gnus-server-edit-server -Edit a server (@code{gnus-server-edit-server}). - -@item S -@kindex S (Server) -@findex gnus-server-show-server -Show the definition of a server (@code{gnus-server-show-server}). - -@item SPACE -@kindex SPACE (Server) -@findex gnus-server-read-server -Browse the current server (@code{gnus-server-read-server}). - -@item q -@kindex q (Server) -@findex gnus-server-exit -Return to the group buffer (@code{gnus-server-exit}). - -@item k -@kindex k (Server) -@findex gnus-server-kill-server -Kill the current server (@code{gnus-server-kill-server}). - -@item y -@kindex y (Server) -@findex gnus-server-yank-server -Yank the previously killed server (@code{gnus-server-yank-server}). - -@item c -@kindex c (Server) -@findex gnus-server-copy-server -Copy the current server (@code{gnus-server-copy-server}). - -@item l -@kindex l (Server) -@findex gnus-server-list-servers -List all servers (@code{gnus-server-list-servers}). - -@item s -@kindex s (Server) -@findex gnus-server-scan-server -Request that the server scan its sources for new articles -(@code{gnus-server-scan-server}). This is mainly sensible with mail -servers. - -@item g -@kindex g (Server) -@findex gnus-server-regenerate-server -Request that the server regenerate all its data structures -(@code{gnus-server-regenerate-server}). This can be useful if you have -a mail back end that has gotten out of sync. - -@item z -@kindex z (Server) -@findex gnus-server-compact-server - -Compact all groups in the server under point -(@code{gnus-server-compact-server}). Currently implemented only in -nnml (@pxref{Mail Spool}). This removes gaps between article numbers, -hence getting a correct total article count. - -@end table - -Some more commands for closing, disabling, and re-opening servers are -listed in @ref{Unavailable Servers}. - - -@node Example Methods -@subsection Example Methods - -Most select methods are pretty simple and self-explanatory: - -@lisp -(nntp "news.funet.fi") -@end lisp - -Reading directly from the spool is even simpler: - -@lisp -(nnspool "") -@end lisp - -As you can see, the first element in a select method is the name of the -back end, and the second is the @dfn{address}, or @dfn{name}, if you -will. - -After these two elements, there may be an arbitrary number of -@code{(@var{variable} @var{form})} pairs. - -To go back to the first example---imagine that you want to read from -port 15 on that machine. This is what the select method should -look like then: - -@lisp -(nntp "news.funet.fi" (nntp-port-number 15)) -@end lisp - -You should read the documentation to each back end to find out what -variables are relevant, but here's an @code{nnmh} example: - -@code{nnmh} is a mail back end that reads a spool-like structure. Say -you have two structures that you wish to access: One is your private -mail spool, and the other is a public one. Here's the possible spec for -your private mail: - -@lisp -(nnmh "private" (nnmh-directory "~/private/mail/")) -@end lisp - -(This server is then called @samp{private}, but you may have guessed -that.) - -Here's the method for a public spool: - -@lisp -(nnmh "public" - (nnmh-directory "/usr/information/spool/") - (nnmh-get-new-mail nil)) -@end lisp - -@cindex proxy -@cindex firewall - -If you are behind a firewall and only have access to the @acronym{NNTP} -server from the firewall machine, you can instruct Gnus to @code{rlogin} -on the firewall machine and connect with -@uref{http://netcat.sourceforge.net/, netcat} from there to the -@acronym{NNTP} server. -Doing this can be rather fiddly, but your virtual server definition -should probably look something like this: - -@lisp -(nntp "firewall" - (nntp-open-connection-function nntp-open-via-rlogin-and-netcat) - (nntp-via-address "the.firewall.machine") - (nntp-address "the.real.nntp.host")) -@end lisp - -If you want to use the wonderful @code{ssh} program to provide a -compressed connection over the modem line, you could add the following -configuration to the example above: - -@lisp - (nntp-via-rlogin-command "ssh") -@end lisp - -See also @code{nntp-via-rlogin-command-switches}. Here's an example for -an indirect connection: - -@lisp -(setq gnus-select-method - '(nntp "indirect" - (nntp-address "news.server.example") - (nntp-via-user-name "intermediate_user_name") - (nntp-via-address "intermediate.host.example") - (nntp-via-rlogin-command "ssh") - (nntp-via-rlogin-command-switches ("-C")) - (nntp-open-connection-function nntp-open-via-rlogin-and-netcat))) -@end lisp - -This means that you have to have set up @code{ssh-agent} correctly to -provide automatic authorization, of course. - -If you're behind a firewall, but have direct access to the outside world -through a wrapper command like "runsocks", you could open a socksified -netcat connection to the news server as follows: - -@lisp -(nntp "outside" - (nntp-pre-command "runsocks") - (nntp-open-connection-function nntp-open-netcat-stream) - (nntp-address "the.news.server")) -@end lisp - - -@node Creating a Virtual Server -@subsection Creating a Virtual Server - -If you're saving lots of articles in the cache by using persistent -articles, you may want to create a virtual server to read the cache. - -First you need to add a new server. The @kbd{a} command does that. It -would probably be best to use @code{nnml} to read the cache. You -could also use @code{nnspool} or @code{nnmh}, though. - -Type @kbd{a nnml RET cache RET}. - -You should now have a brand new @code{nnml} virtual server called -@samp{cache}. You now need to edit it to have the right definitions. -Type @kbd{e} to edit the server. You'll be entered into a buffer that -will contain the following: - -@lisp -(nnml "cache") -@end lisp - -Change that to: - -@lisp -(nnml "cache" - (nnml-directory "~/News/cache/") - (nnml-active-file "~/News/cache/active")) -@end lisp - -Type @kbd{C-c C-c} to return to the server buffer. If you now press -@kbd{RET} over this virtual server, you should be entered into a browse -buffer, and you should be able to enter any of the groups displayed. - - -@node Server Variables -@subsection Server Variables -@cindex server variables -@cindex server parameters - -One sticky point when defining variables (both on back ends and in Emacs -in general) is that some variables are typically initialized from other -variables when the definition of the variables is being loaded. If you -change the ``base'' variable after the variables have been loaded, you -won't change the ``derived'' variables. - -This typically affects directory and file variables. For instance, -@code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml} -directory variables are initialized from that variable, so -@code{nnml-active-file} will be @file{~/Mail/active}. If you define a -new virtual @code{nnml} server, it will @emph{not} suffice to set just -@code{nnml-directory}---you have to explicitly set all the file -variables to be what you want them to be. For a complete list of -variables for each back end, see each back end's section later in this -manual, but here's an example @code{nnml} definition: - -@lisp -(nnml "public" - (nnml-directory "~/my-mail/") - (nnml-active-file "~/my-mail/active") - (nnml-newsgroups-file "~/my-mail/newsgroups")) -@end lisp - -Server variables are often called @dfn{server parameters}. - -@node Servers and Methods -@subsection Servers and Methods - -Wherever you would normally use a select method -(e.g., @code{gnus-secondary-select-method}, in the group select method, -when browsing a foreign server) you can use a virtual server name -instead. This could potentially save lots of typing. And it's nice all -over. - - -@node Unavailable Servers -@subsection Unavailable Servers - -If a server seems to be unreachable, Gnus will mark that server as -@code{denied}. That means that any subsequent attempt to make contact -with that server will just be ignored. ``It can't be opened,'' Gnus -will tell you, without making the least effort to see whether that is -actually the case or not. - -That might seem quite naughty, but it does make sense most of the time. -Let's say you have 10 groups subscribed to on server -@samp{nephelococcygia.com}. This server is located somewhere quite far -away from you and the machine is quite slow, so it takes 1 minute just -to find out that it refuses connection to you today. If Gnus were to -attempt to do that 10 times, you'd be quite annoyed, so Gnus won't -attempt to do that. Once it has gotten a single ``connection refused'', -it will regard that server as ``down''. - -So, what happens if the machine was only feeling unwell temporarily? -How do you test to see whether the machine has come up again? - -You jump to the server buffer (@pxref{Server Buffer}) and poke it -with the following commands: - -@table @kbd - -@item O -@kindex O (Server) -@findex gnus-server-open-server -Try to establish connection to the server on the current line -(@code{gnus-server-open-server}). - -@item C -@kindex C (Server) -@findex gnus-server-close-server -Close the connection (if any) to the server -(@code{gnus-server-close-server}). - -@item D -@kindex D (Server) -@findex gnus-server-deny-server -Mark the current server as unreachable -(@code{gnus-server-deny-server}). - -@item M-o -@kindex M-o (Server) -@findex gnus-server-open-all-servers -Open the connections to all servers in the buffer -(@code{gnus-server-open-all-servers}). - -@item M-c -@kindex M-c (Server) -@findex gnus-server-close-all-servers -Close the connections to all servers in the buffer -(@code{gnus-server-close-all-servers}). - -@item R -@kindex R (Server) -@findex gnus-server-remove-denials -Remove all marks to whether Gnus was denied connection from any servers -(@code{gnus-server-remove-denials}). - -@item c -@kindex c (Server) -@findex gnus-server-copy-server -Copy a server and give it a new name -(@code{gnus-server-copy-server}). This can be useful if you have a -complex method definition, and want to use the same definition towards -a different (physical) server. - -@item L -@kindex L (Server) -@findex gnus-server-offline-server -Set server status to offline (@code{gnus-server-offline-server}). - -@end table - - -@node Getting News -@section Getting News -@cindex reading news -@cindex news back ends - -A newsreader is normally used for reading news. Gnus currently provides -only two methods of getting news---it can read from an @acronym{NNTP} server, -or it can read from a local spool. - -@menu -* NNTP:: Reading news from an @acronym{NNTP} server. -* News Spool:: Reading news from the local spool. -@end menu - - -@node NNTP -@subsection NNTP -@cindex nntp - -Subscribing to a foreign group from an @acronym{NNTP} server is rather easy. -You just specify @code{nntp} as method and the address of the @acronym{NNTP} -server as the, uhm, address. - -If the @acronym{NNTP} server is located at a non-standard port, setting the -third element of the select method to this port number should allow you -to connect to the right port. You'll have to edit the group info for -that (@pxref{Foreign Groups}). - -The name of the foreign group can be the same as a native group. In -fact, you can subscribe to the same group from as many different servers -you feel like. There will be no name collisions. - -The following variables can be used to create a virtual @code{nntp} -server: - -@table @code - -@item nntp-server-opened-hook -@vindex nntp-server-opened-hook -@cindex @sc{mode reader} -@cindex authinfo -@cindex authentication -@cindex nntp authentication -@findex nntp-send-authinfo -@findex nntp-send-mode-reader -is run after a connection has been made. It can be used to send -commands to the @acronym{NNTP} server after it has been contacted. By -default it sends the command @code{MODE READER} to the server with the -@code{nntp-send-mode-reader} function. This function should always be -present in this hook. - -@item nntp-authinfo-function -@vindex nntp-authinfo-function -@findex nntp-send-authinfo -@vindex nntp-authinfo-file -This function will be used to send @samp{AUTHINFO} to the @acronym{NNTP} -server. The default function is @code{nntp-send-authinfo}, which looks -through your @file{~/.authinfo} (or whatever you've set the -@code{nntp-authinfo-file} variable to) for applicable entries. If none -are found, it will prompt you for a login name and a password. The -format of the @file{~/.authinfo} file is (almost) the same as the -@code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp} -manual page, but here are the salient facts: - -@enumerate -@item -The file contains one or more line, each of which define one server. - -@item -Each line may contain an arbitrary number of token/value pairs. - -The valid tokens include @samp{machine}, @samp{login}, @samp{password}, -@samp{default}. In addition Gnus introduces two new tokens, not present -in the original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and -@samp{force}. (This is the only way the @file{.authinfo} file format -deviates from the @file{.netrc} file format.) @samp{port} is used to -indicate what port on the server the credentials apply to and -@samp{force} is explained below. - -@end enumerate - -Here's an example file: - -@example -machine news.uio.no login larsi password geheimnis -machine nntp.ifi.uio.no login larsi force yes -@end example - -The token/value pairs may appear in any order; @samp{machine} doesn't -have to be first, for instance. - -In this example, both login name and password have been supplied for the -former server, while the latter has only the login name listed, and the -user will be prompted for the password. The latter also has the -@samp{force} tag, which means that the authinfo will be sent to the -@var{nntp} server upon connection; the default (i.e., when there is not -@samp{force} tag) is to not send authinfo to the @var{nntp} server -until the @var{nntp} server asks for it. - -You can also add @samp{default} lines that will apply to all servers -that don't have matching @samp{machine} lines. - -@example -default force yes -@end example - -This will force sending @samp{AUTHINFO} commands to all servers not -previously mentioned. - -Remember to not leave the @file{~/.authinfo} file world-readable. - -@item nntp-server-action-alist -@vindex nntp-server-action-alist -This is a list of regexps to match on server types and actions to be -taken when matches are made. For instance, if you want Gnus to beep -every time you connect to innd, you could say something like: - -@lisp -(setq nntp-server-action-alist - '(("innd" (ding)))) -@end lisp - -You probably don't want to do that, though. - -The default value is - -@lisp -'(("nntpd 1\\.5\\.11t" - (remove-hook 'nntp-server-opened-hook - 'nntp-send-mode-reader))) -@end lisp - -This ensures that Gnus doesn't send the @code{MODE READER} command to -nntpd 1.5.11t, since that command chokes that server, I've been told. - -@item nntp-maximum-request -@vindex nntp-maximum-request -If the @acronym{NNTP} server doesn't support @acronym{NOV} headers, this back end -will collect headers by sending a series of @code{head} commands. To -speed things up, the back end sends lots of these commands without -waiting for reply, and then reads all the replies. This is controlled -by the @code{nntp-maximum-request} variable, and is 400 by default. If -your network is buggy, you should set this to 1. - -@item nntp-connection-timeout -@vindex nntp-connection-timeout -If you have lots of foreign @code{nntp} groups that you connect to -regularly, you're sure to have problems with @acronym{NNTP} servers not -responding properly, or being too loaded to reply within reasonable -time. This is can lead to awkward problems, which can be helped -somewhat by setting @code{nntp-connection-timeout}. This is an integer -that says how many seconds the @code{nntp} back end should wait for a -connection before giving up. If it is @code{nil}, which is the default, -no timeouts are done. - -@item nntp-nov-is-evil -@vindex nntp-nov-is-evil -If the @acronym{NNTP} server does not support @acronym{NOV}, you could set this -variable to @code{t}, but @code{nntp} usually checks automatically whether @acronym{NOV} -can be used. - -@item nntp-xover-commands -@vindex nntp-xover-commands -@cindex @acronym{NOV} -@cindex XOVER -List of strings used as commands to fetch @acronym{NOV} lines from a -server. The default value of this variable is @code{("XOVER" -"XOVERVIEW")}. - -@item nntp-nov-gap -@vindex nntp-nov-gap -@code{nntp} normally sends just one big request for @acronym{NOV} lines to -the server. The server responds with one huge list of lines. However, -if you have read articles 2--5000 in the group, and only want to read -article 1 and 5001, that means that @code{nntp} will fetch 4999 @acronym{NOV} -lines that you will not need. This variable says how -big a gap between two consecutive articles is allowed to be before the -@code{XOVER} request is split into several request. Note that if your -network is fast, setting this variable to a really small number means -that fetching will probably be slower. If this variable is @code{nil}, -@code{nntp} will never split requests. The default is 5. - -@item nntp-xref-number-is-evil -@vindex nntp-xref-number-is-evil -When Gnus refers to an article having the @code{Message-ID} that a user -specifies or having the @code{Message-ID} of the parent article of the -current one (@pxref{Finding the Parent}), Gnus sends a @code{HEAD} -command to the @acronym{NNTP} server to know where it is, and the server -returns the data containing the pairs of a group and an article number -in the @code{Xref} header. Gnus normally uses the article number to -refer to the article if the data shows that that article is in the -current group, while it uses the @code{Message-ID} otherwise. However, -some news servers, e.g., ones running Diablo, run multiple engines -having the same articles but article numbers are not kept synchronized -between them. In that case, the article number that appears in the -@code{Xref} header varies by which engine is chosen, so you cannot refer -to the parent article that is in the current group, for instance. If -you connect to such a server, set this variable to a non-@code{nil} -value, and Gnus never uses article numbers. For example: - -@lisp -(setq gnus-select-method - '(nntp "newszilla" - (nntp-address "newszilla.example.com") - (nntp-xref-number-is-evil t) - @dots{})) -@end lisp - -The default value of this server variable is @code{nil}. - -@item nntp-prepare-server-hook -@vindex nntp-prepare-server-hook -A hook run before attempting to connect to an @acronym{NNTP} server. - -@item nntp-record-commands -@vindex nntp-record-commands -If non-@code{nil}, @code{nntp} will log all commands it sends to the -@acronym{NNTP} server (along with a timestamp) in the @file{*nntp-log*} -buffer. This is useful if you are debugging a Gnus/@acronym{NNTP} connection -that doesn't seem to work. - -@item nntp-open-connection-function -@vindex nntp-open-connection-function -It is possible to customize how the connection to the nntp server will -be opened. If you specify an @code{nntp-open-connection-function} -parameter, Gnus will use that function to establish the connection. -Seven pre-made functions are supplied. These functions can be grouped -in two categories: direct connection functions (four pre-made), and -indirect ones (three pre-made). - -@item nntp-never-echoes-commands -@vindex nntp-never-echoes-commands -Non-@code{nil} means the nntp server never echoes commands. It is -reported that some nntps server doesn't echo commands. So, you may want -to set this to non-@code{nil} in the method for such a server setting -@code{nntp-open-connection-function} to @code{nntp-open-ssl-stream} for -example. The default value is @code{nil}. Note that the -@code{nntp-open-connection-functions-never-echo-commands} variable -overrides the @code{nil} value of this variable. - -@item nntp-open-connection-functions-never-echo-commands -@vindex nntp-open-connection-functions-never-echo-commands -List of functions that never echo commands. Add or set a function which -you set to @code{nntp-open-connection-function} to this list if it does -not echo commands. Note that a non-@code{nil} value of the -@code{nntp-never-echoes-commands} variable overrides this variable. The -default value is @code{(nntp-open-network-stream)}. - -@item nntp-prepare-post-hook -@vindex nntp-prepare-post-hook -A hook run just before posting an article. If there is no -@code{Message-ID} header in the article and the news server provides the -recommended ID, it will be added to the article before running this -hook. It is useful to make @code{Cancel-Lock} headers even if you -inhibit Gnus to add a @code{Message-ID} header, you could say: - -@lisp -(add-hook 'nntp-prepare-post-hook 'canlock-insert-header) -@end lisp - -Note that not all servers support the recommended ID@. This works for -INN versions 2.3.0 and later, for instance. - -@item nntp-server-list-active-group -If @code{nil}, then always use @samp{GROUP} instead of @samp{LIST -ACTIVE}. This is usually slower, but on misconfigured servers that -don't update their active files often, this can help. - - -@end table - -@menu -* Direct Functions:: Connecting directly to the server. -* Indirect Functions:: Connecting indirectly to the server. -* Common Variables:: Understood by several connection functions. -@end menu - - -@node Direct Functions -@subsubsection Direct Functions -@cindex direct connection functions - -These functions are called direct because they open a direct connection -between your machine and the @acronym{NNTP} server. The behavior of these -functions is also affected by commonly understood variables -(@pxref{Common Variables}). - -@table @code -@findex nntp-open-network-stream -@item nntp-open-network-stream -This is the default, and simply connects to some port or other on the -remote system. If both Emacs and the server supports it, the -connection will be upgraded to an encrypted @acronym{STARTTLS} -connection automatically. - -@item network-only -The same as the above, but don't do automatic @acronym{STARTTLS} upgrades. - -@findex nntp-open-tls-stream -@item nntp-open-tls-stream -Opens a connection to a server over a @dfn{secure} channel. To use -this you must have @uref{http://www.gnu.org/software/gnutls/, GnuTLS} -installed. You then define a server as follows: - -@lisp -;; @r{"nntps" is port 563 and is predefined in our @file{/etc/services}} -;; @r{however, @samp{gnutls-cli -p} doesn't like named ports.} -;; -(nntp "snews.bar.com" - (nntp-open-connection-function nntp-open-tls-stream) - (nntp-port-number 563) - (nntp-address "snews.bar.com")) -@end lisp - -@findex nntp-open-ssl-stream -@item nntp-open-ssl-stream -Opens a connection to a server over a @dfn{secure} channel. To use -this you must have @uref{http://www.openssl.org, OpenSSL} -@ignore -@c Defunct URL, ancient package, so don't mention it. -or @uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay} -@end ignore -installed. You then define a server as follows: - -@lisp -;; @r{"snews" is port 563 and is predefined in our @file{/etc/services}} -;; @r{however, @samp{openssl s_client -port} doesn't like named ports.} -;; -(nntp "snews.bar.com" - (nntp-open-connection-function nntp-open-ssl-stream) - (nntp-port-number 563) - (nntp-address "snews.bar.com")) -@end lisp - -@findex nntp-open-netcat-stream -@item nntp-open-netcat-stream -Opens a connection to an @acronym{NNTP} server using the @code{netcat} -program. You might wonder why this function exists, since we have -the default @code{nntp-open-network-stream} which would do the job. (One -of) the reason(s) is that if you are behind a firewall but have direct -connections to the outside world thanks to a command wrapper like -@code{runsocks}, you can use it like this: - -@lisp -(nntp "socksified" - (nntp-pre-command "runsocks") - (nntp-open-connection-function nntp-open-netcat-stream) - (nntp-address "the.news.server")) -@end lisp - -With the default method, you would need to wrap your whole Emacs -session, which is not a good idea. - -@findex nntp-open-telnet-stream -@item nntp-open-telnet-stream -Like @code{nntp-open-netcat-stream}, but uses @code{telnet} rather than -@code{netcat}. @code{telnet} is a bit less robust because of things -like line-end-conversion, but sometimes netcat is simply -not available. The previous example would turn into: - -@lisp -(nntp "socksified" - (nntp-pre-command "runsocks") - (nntp-open-connection-function nntp-open-telnet-stream) - (nntp-address "the.news.server") - (nntp-end-of-line "\n")) -@end lisp -@end table - - -@node Indirect Functions -@subsubsection Indirect Functions -@cindex indirect connection functions - -These functions are called indirect because they connect to an -intermediate host before actually connecting to the @acronym{NNTP} server. -All of these functions and related variables are also said to belong to -the ``via'' family of connection: they're all prefixed with ``via'' to make -things cleaner. The behavior of these functions is also affected by -commonly understood variables (@pxref{Common Variables}). - -@table @code -@item nntp-open-via-rlogin-and-netcat -@findex nntp-open-via-rlogin-and-netcat -Does an @samp{rlogin} on a remote system, and then uses @code{netcat} to connect -to the real @acronym{NNTP} server from there. This is useful for instance if -you need to connect to a firewall machine first. - -@code{nntp-open-via-rlogin-and-netcat}-specific variables: - -@table @code -@item nntp-via-rlogin-command -@vindex nntp-via-rlogin-command -Command used to log in on the intermediate host. The default is -@samp{rsh}, but @samp{ssh} is a popular alternative. - -@item nntp-via-rlogin-command-switches -@vindex nntp-via-rlogin-command-switches -List of strings to be used as the switches to -@code{nntp-via-rlogin-command}. The default is @code{nil}. If you use -@samp{ssh} for @code{nntp-via-rlogin-command}, you may set this to -@samp{("-C")} in order to compress all data connections. -@end table - -@item nntp-open-via-rlogin-and-telnet -@findex nntp-open-via-rlogin-and-telnet -Does essentially the same, but uses @code{telnet} instead of @samp{netcat} -to connect to the real @acronym{NNTP} server from the intermediate host. -@code{telnet} is a bit less robust because of things like -line-end-conversion, but sometimes @code{netcat} is simply not available. - -@code{nntp-open-via-rlogin-and-telnet}-specific variables: - -@table @code -@item nntp-telnet-command -@vindex nntp-telnet-command -Command used to connect to the real @acronym{NNTP} server from the -intermediate host. The default is @samp{telnet}. - -@item nntp-telnet-switches -@vindex nntp-telnet-switches -List of strings to be used as the switches to the -@code{nntp-telnet-command} command. The default is @code{("-8")}. - -@item nntp-via-rlogin-command -@vindex nntp-via-rlogin-command -Command used to log in on the intermediate host. The default is -@samp{rsh}, but @samp{ssh} is a popular alternative. - -@item nntp-via-rlogin-command-switches -@vindex nntp-via-rlogin-command-switches -List of strings to be used as the switches to -@code{nntp-via-rlogin-command}. If you use @samp{ssh}, you may need to set -this to @samp{("-t" "-e" "none")} or @samp{("-C" "-t" "-e" "none")} if -the telnet command requires a pseudo-tty allocation on an intermediate -host. The default is @code{nil}. -@end table - -Note that you may want to change the value for @code{nntp-end-of-line} -to @samp{\n} (@pxref{Common Variables}). - -@item nntp-open-via-telnet-and-telnet -@findex nntp-open-via-telnet-and-telnet -Does essentially the same, but uses @samp{telnet} instead of -@samp{rlogin} to connect to the intermediate host. - -@code{nntp-open-via-telnet-and-telnet}-specific variables: - -@table @code -@item nntp-via-telnet-command -@vindex nntp-via-telnet-command -Command used to @code{telnet} the intermediate host. The default is -@samp{telnet}. - -@item nntp-via-telnet-switches -@vindex nntp-via-telnet-switches -List of strings to be used as the switches to the -@code{nntp-via-telnet-command} command. The default is @samp{("-8")}. - -@item nntp-via-user-password -@vindex nntp-via-user-password -Password to use when logging in on the intermediate host. - -@item nntp-via-envuser -@vindex nntp-via-envuser -If non-@code{nil}, the intermediate @code{telnet} session (client and -server both) will support the @code{ENVIRON} option and not prompt for -login name. This works for Solaris @code{telnet}, for instance. - -@item nntp-via-shell-prompt -@vindex nntp-via-shell-prompt -Regexp matching the shell prompt on the intermediate host. The default -is @samp{bash\\|\$ *\r?$\\|> *\r?}. - -@end table - -Note that you may want to change the value for @code{nntp-end-of-line} -to @samp{\n} (@pxref{Common Variables}). -@end table - - -Here are some additional variables that are understood by all the above -functions: - -@table @code - -@item nntp-via-user-name -@vindex nntp-via-user-name -User name to use when connecting to the intermediate host. - -@item nntp-via-address -@vindex nntp-via-address -Address of the intermediate host to connect to. - -@end table - - -@node Common Variables -@subsubsection Common Variables - -The following variables affect the behavior of all, or several of the -pre-made connection functions. When not specified, all functions are -affected (the values of the following variables will be used as the -default if each virtual @code{nntp} server doesn't specify those server -variables individually). - -@table @code - -@item nntp-pre-command -@vindex nntp-pre-command -A command wrapper to use when connecting through a non native -connection function (all except @code{nntp-open-network-stream}, -@code{nntp-open-tls-stream}, and @code{nntp-open-ssl-stream}). This is -where you would put a @samp{SOCKS} wrapper for instance. - -@item nntp-address -@vindex nntp-address -The address of the @acronym{NNTP} server. - -@item nntp-port-number -@vindex nntp-port-number -Port number to connect to the @acronym{NNTP} server. The default is -@samp{nntp}. If you use @acronym{NNTP} over -@acronym{TLS}/@acronym{SSL}, you may want to use integer ports rather -than named ports (i.e., use @samp{563} instead of @samp{snews} or -@samp{nntps}), because external @acronym{TLS}/@acronym{SSL} tools may -not work with named ports. - -@item nntp-end-of-line -@vindex nntp-end-of-line -String to use as end-of-line marker when talking to the @acronym{NNTP} -server. This is @samp{\r\n} by default, but should be @samp{\n} when -using a non native telnet connection function. - -@item nntp-netcat-command -@vindex nntp-netcat-command -Command to use when connecting to the @acronym{NNTP} server through -@samp{netcat}. This is @emph{not} for an intermediate host. This is -just for the real @acronym{NNTP} server. The default is -@samp{nc}. - -@item nntp-netcat-switches -@vindex nntp-netcat-switches -A list of switches to pass to @code{nntp-netcat-command}. The default -is @samp{()}. - -@end table - -@node News Spool -@subsection News Spool -@cindex nnspool -@cindex news spool - -Subscribing to a foreign group from the local spool is extremely easy, -and might be useful, for instance, to speed up reading groups that -contain very big articles---@samp{alt.binaries.pictures.furniture}, for -instance. - -Anyway, you just specify @code{nnspool} as the method and @code{""} (or -anything else) as the address. - -If you have access to a local spool, you should probably use that as the -native select method (@pxref{Finding the News}). It is normally faster -than using an @code{nntp} select method, but might not be. It depends. -You just have to try to find out what's best at your site. - -@table @code - -@item nnspool-inews-program -@vindex nnspool-inews-program -Program used to post an article. - -@item nnspool-inews-switches -@vindex nnspool-inews-switches -Parameters given to the inews program when posting an article. - -@item nnspool-spool-directory -@vindex nnspool-spool-directory -Where @code{nnspool} looks for the articles. This is normally -@file{/usr/spool/news/}. - -@item nnspool-nov-directory -@vindex nnspool-nov-directory -Where @code{nnspool} will look for @acronym{NOV} files. This is normally@* -@file{/usr/spool/news/over.view/}. - -@item nnspool-lib-dir -@vindex nnspool-lib-dir -Where the news lib dir is (@file{/usr/lib/news/} by default). - -@item nnspool-active-file -@vindex nnspool-active-file -The name of the active file. - -@item nnspool-newsgroups-file -@vindex nnspool-newsgroups-file -The name of the group descriptions file. - -@item nnspool-history-file -@vindex nnspool-history-file -The name of the news history file. - -@item nnspool-active-times-file -@vindex nnspool-active-times-file -The name of the active date file. - -@item nnspool-nov-is-evil -@vindex nnspool-nov-is-evil -If non-@code{nil}, @code{nnspool} won't try to use any @acronym{NOV} files -that it finds. - -@item nnspool-sift-nov-with-sed -@vindex nnspool-sift-nov-with-sed -@cindex sed -If non-@code{nil}, which is the default, use @code{sed} to get the -relevant portion from the overview file. If @code{nil}, -@code{nnspool} will load the entire file into a buffer and process it -there. - -@end table - - -@node Using IMAP -@section Using IMAP -@cindex imap - -The most popular mail backend is probably @code{nnimap}, which -provides access to @acronym{IMAP} servers. @acronym{IMAP} servers -store mail remotely, so the client doesn't store anything locally. -This means that it's a convenient choice when you're reading your mail -from different locations, or with different user agents. - -@menu -* Connecting to an IMAP Server:: Getting started with @acronym{IMAP}. -* Customizing the IMAP Connection:: Variables for @acronym{IMAP} connection. -* Client-Side IMAP Splitting:: Put mail in the correct mail box. -@end menu - - -@node Connecting to an IMAP Server -@subsection Connecting to an IMAP Server - -Connecting to an @acronym{IMAP} can be very easy. Type @kbd{B} in the -group buffer, or (if your primary interest is reading email), say -something like: - -@example -(setq gnus-select-method - '(nnimap "imap.gmail.com")) -@end example - -You'll be prompted for a user name and password. If you grow tired of -that, then add the following to your @file{~/.authinfo} file: - -@example -machine imap.gmail.com login password port imap -@end example - -That should basically be it for most users. - - -@node Customizing the IMAP Connection -@subsection Customizing the IMAP Connection - -Here's an example method that's more complex: - -@example -(nnimap "imap.gmail.com" - (nnimap-inbox "INBOX") - (nnimap-split-methods default) - (nnimap-expunge t) - (nnimap-stream ssl)) -@end example - -@table @code -@item nnimap-address -The address of the server, like @samp{imap.gmail.com}. - -@item nnimap-server-port -If the server uses a non-standard port, that can be specified here. A -typical port would be @code{"imap"} or @code{"imaps"}. - -@item nnimap-stream -How @code{nnimap} should connect to the server. Possible values are: - -@table @code -@item undecided -This is the default, and this first tries the @code{ssl} setting, and -then tries the @code{network} setting. - -@item ssl -This uses standard @acronym{TLS}/@acronym{SSL} connections. - -@item network -Non-encrypted and unsafe straight socket connection, but will upgrade -to encrypted @acronym{STARTTLS} if both Emacs and the server -supports it. - -@item starttls -Encrypted @acronym{STARTTLS} over the normal @acronym{IMAP} port. - -@item shell -If you need to tunnel via other systems to connect to the server, you -can use this option, and customize @code{nnimap-shell-program} to be -what you need. - -@end table - -@item nnimap-authenticator -Some @acronym{IMAP} servers allow anonymous logins. In that case, -this should be set to @code{anonymous}. If this variable isn't set, -the normal login methods will be used. If you wish to specify a -specific login method to be used, you can set this variable to either -@code{login} (the traditional @acronym{IMAP} login method), -@code{plain} or @code{cram-md5}. - -@item nnimap-expunge -If non-@code{nil}, expunge articles after deleting them. This is always done -if the server supports UID EXPUNGE, but it's not done by default on -servers that doesn't support that command. - -@item nnimap-streaming -Virtually all @acronym{IMAP} server support fast streaming of data. -If you have problems connecting to the server, try setting this to -@code{nil}. - -@item nnimap-fetch-partial-articles -If non-@code{nil}, fetch partial articles from the server. If set to -a string, then it's interpreted as a regexp, and parts that have -matching types will be fetched. For instance, @samp{"text/"} will -fetch all textual parts, while leaving the rest on the server. - -@item nnimap-record-commands -If non-@code{nil}, record all @acronym{IMAP} commands in the -@samp{"*imap log*"} buffer. - -@end table - - -@node Client-Side IMAP Splitting -@subsection Client-Side IMAP Splitting - -Many people prefer to do the sorting/splitting of mail into their mail -boxes on the @acronym{IMAP} server. That way they don't have to -download the mail they're not all that interested in. - -If you do want to do client-side mail splitting, then the following -variables are relevant: - -@table @code -@item nnimap-inbox -This is the @acronym{IMAP} mail box that will be scanned for new -mail. This can also be a list of mail box names. - -@item nnimap-split-methods -Uses the same syntax as @code{nnmail-split-methods} (@pxref{Splitting -Mail}), except the symbol @code{default}, which means that it should -use the value of the @code{nnmail-split-methods} variable. - -@item nnimap-split-fancy -Uses the same syntax as @code{nnmail-split-fancy}. - -@item nnimap-unsplittable-articles -List of flag symbols to ignore when doing splitting. That is, -articles that have these flags won't be considered when splitting. -The default is @samp{(%Deleted %Seen)}. - -@end table - -Here's a complete example @code{nnimap} backend with a client-side -``fancy'' splitting method: - -@example -(nnimap "imap.example.com" - (nnimap-inbox "INBOX") - (nnimap-split-methods - (| ("MailScanner-SpamCheck" "spam" "spam.detected") - (to "foo@@bar.com" "foo") - "undecided"))) -@end example - - -@node Getting Mail -@section Getting Mail -@cindex reading mail -@cindex mail - -Reading mail with a newsreader---isn't that just plain WeIrD@? But of -course. - -@menu -* Mail in a Newsreader:: Important introductory notes. -* Getting Started Reading Mail:: A simple cookbook example. -* Splitting Mail:: How to create mail groups. -* Mail Sources:: How to tell Gnus where to get mail from. -* Mail Back End Variables:: Variables for customizing mail handling. -* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. -* Group Mail Splitting:: Use group customize to drive mail splitting. -* Incorporating Old Mail:: What about the old mail you have? -* Expiring Mail:: Getting rid of unwanted mail. -* Washing Mail:: Removing cruft from the mail you get. -* Duplicates:: Dealing with duplicated mail. -* Not Reading Mail:: Using mail back ends for reading other files. -* Choosing a Mail Back End:: Gnus can read a variety of mail formats. -@end menu - - -@node Mail in a Newsreader -@subsection Mail in a Newsreader - -If you are used to traditional mail readers, but have decided to switch -to reading mail with Gnus, you may find yourself experiencing something -of a culture shock. - -Gnus does not behave like traditional mail readers. If you want to make -it behave that way, you can, but it's an uphill battle. - -Gnus, by default, handles all its groups using the same approach. This -approach is very newsreaderly---you enter a group, see the new/unread -messages, and when you read the messages, they get marked as read, and -you don't see them any more. (Unless you explicitly ask for them.) - -In particular, you do not do anything explicitly to delete messages. - -Does this mean that all the messages that have been marked as read are -deleted? How awful! - -But, no, it means that old messages are @dfn{expired} according to some -scheme or other. For news messages, the expire process is controlled by -the news administrator; for mail, the expire process is controlled by -you. The expire process for mail is covered in depth in @ref{Expiring -Mail}. - -What many Gnus users find, after using it a while for both news and -mail, is that the transport mechanism has very little to do with how -they want to treat a message. - -Many people subscribe to several mailing lists. These are transported -via @acronym{SMTP}, and are therefore mail. But we might go for weeks without -answering, or even reading these messages very carefully. We may not -need to save them because if we should need to read one again, they are -archived somewhere else. - -Some people have local news groups which have only a handful of readers. -These are transported via @acronym{NNTP}, and are therefore news. But we may need -to read and answer a large fraction of the messages very carefully in -order to do our work. And there may not be an archive, so we may need -to save the interesting messages the same way we would personal mail. - -The important distinction turns out to be not the transport mechanism, -but other factors such as how interested we are in the subject matter, -or how easy it is to retrieve the message if we need to read it again. - -Gnus provides many options for sorting mail into ``groups'' which behave -like newsgroups, and for treating each group (whether mail or news) -differently. - -Some users never get comfortable using the Gnus (ahem) paradigm and wish -that Gnus should grow up and be a male, er, mail reader. It is possible -to whip Gnus into a more mailreaderly being, but, as said before, it's -not easy. People who prefer proper mail readers should try @sc{vm} -instead, which is an excellent, and proper, mail reader. - -I don't mean to scare anybody off, but I want to make it clear that you -may be required to learn a new way of thinking about messages. After -you've been subjected to The Gnus Way, you will come to love it. I can -guarantee it. (At least the guy who sold me the Emacs Subliminal -Brain-Washing Functions that I've put into Gnus did guarantee it. You -Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way. -You Do.) - - -@node Getting Started Reading Mail -@subsection Getting Started Reading Mail - -It's quite easy to use Gnus to read your new mail. You just plonk the -mail back end of your choice into @code{gnus-secondary-select-methods}, -and things will happen automatically. - -For instance, if you want to use @code{nnml} (which is a ``one file per -mail'' back end), you could put the following in your @file{~/.gnus.el} file: - -@lisp -(setq gnus-secondary-select-methods '((nnml ""))) -@end lisp - -Now, the next time you start Gnus, this back end will be queried for new -articles, and it will move all the messages in your spool file to its -directory, which is @file{~/Mail/} by default. The new group that will -be created (@samp{mail.misc}) will be subscribed, and you can read it -like any other group. - -You will probably want to split the mail into several groups, though: - -@lisp -(setq nnmail-split-methods - '(("junk" "^From:.*Lars Ingebrigtsen") - ("crazy" "^Subject:.*die\\|^Organization:.*flabby") - ("other" ""))) -@end lisp - -This will result in three new @code{nnml} mail groups being created: -@samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the -mail that doesn't fit into the first two groups will be placed in the -last group. - -This should be sufficient for reading mail with Gnus. You might want to -give the other sections in this part of the manual a perusal, though. -Especially @pxref{Choosing a Mail Back End} and @pxref{Expiring Mail}. - - -@node Splitting Mail -@subsection Splitting Mail -@cindex splitting mail -@cindex mail splitting -@cindex mail filtering (splitting) - -@vindex nnmail-split-methods -The @code{nnmail-split-methods} variable says how the incoming mail is -to be split into groups. - -@lisp -(setq nnmail-split-methods - '(("mail.junk" "^From:.*Lars Ingebrigtsen") - ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby") - ("mail.other" ""))) -@end lisp - -This variable is a list of lists, where the first element of each of -these lists is the name of the mail group (they do not have to be called -something beginning with @samp{mail}, by the way), and the second -element is a regular expression used on the header of each mail to -determine if it belongs in this mail group. The first string may -contain @samp{\\1} forms, like the ones used by @code{replace-match} to -insert sub-expressions from the matched text. For instance: - -@lisp -("list.\\1" "From:.* \\(.*\\)-list@@majordomo.com") -@end lisp - -@noindent -In that case, @code{nnmail-split-lowercase-expanded} controls whether -the inserted text should be made lowercase. @xref{Fancy Mail Splitting}. - -The second element can also be a function. In that case, it will be -called narrowed to the headers with the first element of the rule as the -argument. It should return a non-@code{nil} value if it thinks that the -mail belongs in that group. - -@cindex @samp{bogus} group -The last of these groups should always be a general one, and the regular -expression should @emph{always} be @samp{""} so that it matches any mails -that haven't been matched by any of the other regexps. (These rules are -processed from the beginning of the alist toward the end. The first rule -to make a match will ``win'', unless you have crossposting enabled. In -that case, all matching rules will ``win''.) If no rule matched, the mail -will end up in the @samp{bogus} group. When new groups are created by -splitting mail, you may want to run @code{gnus-group-find-new-groups} to -see the new groups. This also applies to the @samp{bogus} group. - -If you like to tinker with this yourself, you can set this variable to a -function of your choice. This function will be called without any -arguments in a buffer narrowed to the headers of an incoming mail -message. The function should return a list of group names that it -thinks should carry this mail message. - -This variable can also be a fancy split method. For the syntax, -see @ref{Fancy Mail Splitting}. - -Note that the mail back ends are free to maul the poor, innocent, -incoming headers all they want to. They all add @code{Lines} headers; -some add @code{X-Gnus-Group} headers; most rename the Unix mbox -@code{From} line to something else. - -@vindex nnmail-crosspost -The mail back ends all support cross-posting. If several regexps match, -the mail will be ``cross-posted'' to all those groups. -@code{nnmail-crosspost} says whether to use this mechanism or not. Note -that no articles are crossposted to the general (@samp{""}) group. - -@vindex nnmail-crosspost-link-function -@cindex crosspost -@cindex links -@code{nnmh} and @code{nnml} makes crossposts by creating hard links to -the crossposted articles. However, not all file systems support hard -links. If that's the case for you, set -@code{nnmail-crosspost-link-function} to @code{copy-file}. (This -variable is @code{add-name-to-file} by default.) - -@kindex M-x nnmail-split-history -@findex nnmail-split-history -If you wish to see where the previous mail split put the messages, you -can use the @kbd{M-x nnmail-split-history} command. If you wish to see -where re-spooling messages would put the messages, you can use -@code{gnus-summary-respool-trace} and related commands (@pxref{Mail -Group Commands}). - -@vindex nnmail-split-header-length-limit -Header lines longer than the value of -@code{nnmail-split-header-length-limit} are excluded from the split -function. - -@vindex nnmail-mail-splitting-decodes -@vindex nnmail-mail-splitting-charset -By default, splitting does not decode headers, so you can not match on -non-@acronym{ASCII} strings. But it is useful if you want to match -articles based on the raw header data. To enable it, set the -@code{nnmail-mail-splitting-decodes} variable to a non-@code{nil} value. -In addition, the value of the @code{nnmail-mail-splitting-charset} -variable is used for decoding non-@acronym{MIME} encoded string when -@code{nnmail-mail-splitting-decodes} is non-@code{nil}. The default -value is @code{nil} which means not to decode non-@acronym{MIME} encoded -string. A suitable value for you will be @code{undecided} or be the -charset used normally in mails you are interested in. - -@vindex nnmail-resplit-incoming -By default, splitting is performed on all incoming messages. If you -specify a @code{directory} entry for the variable @code{mail-sources} -(@pxref{Mail Source Specifiers}), however, then splitting does -@emph{not} happen by default. You can set the variable -@code{nnmail-resplit-incoming} to a non-@code{nil} value to make -splitting happen even in this case. (This variable has no effect on -other kinds of entries.) - -Gnus gives you all the opportunity you could possibly want for shooting -yourself in the foot. Let's say you create a group that will contain -all the mail you get from your boss. And then you accidentally -unsubscribe from the group. Gnus will still put all the mail from your -boss in the unsubscribed group, and so, when your boss mails you ``Have -that report ready by Monday or you're fired!'', you'll never see it and, -come Tuesday, you'll still believe that you're gainfully employed while -you really should be out collecting empty bottles to save up for next -month's rent money. - - -@node Mail Sources -@subsection Mail Sources - -Mail can be gotten from many different sources---the mail spool, from -a @acronym{POP} mail server, from a procmail directory, or from a -maildir, for instance. - -@menu -* Mail Source Specifiers:: How to specify what a mail source is. -* Mail Source Functions:: -* Mail Source Customization:: Some variables that influence things. -* Fetching Mail:: Using the mail source specifiers. -@end menu - - -@node Mail Source Specifiers -@subsubsection Mail Source Specifiers -@cindex POP -@cindex mail server -@cindex procmail -@cindex mail spool -@cindex mail source - -You tell Gnus how to fetch mail by setting @code{mail-sources} -(@pxref{Fetching Mail}) to a @dfn{mail source specifier}. - -Here's an example: - -@lisp -(pop :server "pop3.mailserver.com" :user "myname") -@end lisp - -As can be observed, a mail source specifier is a list where the first -element is a @dfn{mail source type}, followed by an arbitrary number of -@dfn{keywords}. Keywords that are not explicitly specified are given -default values. - -The @code{mail-sources} is global for all mail groups. You can specify -an additional mail source for a particular group by including the -@code{group} mail specifier in @code{mail-sources}, and setting a -@code{mail-source} group parameter (@pxref{Group Parameters}) specifying -a single mail source. When this is used, @code{mail-sources} is -typically just @code{(group)}; the @code{mail-source} parameter for a -group might look like this: - -@lisp -(mail-source . (file :path "home/user/spools/foo.spool")) -@end lisp - -This means that the group's (and only this group's) messages will be -fetched from the spool file @samp{/user/spools/foo.spool}. - -The following mail source types are available: - -@table @code -@item file -Get mail from a single file; typically from the mail spool. - -Keywords: - -@table @code -@item :path -The file name. Defaults to the value of the @env{MAIL} -environment variable or the value of @code{rmail-spool-directory} -(usually something like @file{/usr/mail/spool/user-name}). - -@item :prescript -@itemx :postscript -Script run before/after fetching mail. -@end table - -An example file mail source: - -@lisp -(file :path "/usr/spool/mail/user-name") -@end lisp - -Or using the default file name: - -@lisp -(file) -@end lisp - -If the mail spool file is not located on the local machine, it's best -to use @acronym{POP} or @acronym{IMAP} or the like to fetch the mail. -You can not use ange-ftp file names here---it has no way to lock the -mail spool while moving the mail. - -If it's impossible to set up a proper server, you can use ssh instead. - -@lisp -(setq mail-sources - '((file :prescript "ssh host bin/getmail >%t"))) -@end lisp - -The @samp{getmail} script would look something like the following: - -@example -#!/bin/sh -# getmail - move mail from spool to stdout -# flu@@iki.fi - -MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail -TMP=$HOME/Mail/tmp -rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP -@end example - -Alter this script to fit the @samp{movemail} and temporary -file you want to use. - - -@item directory -@vindex nnmail-scan-directory-mail-source-once -Get mail from several files in a directory. This is typically used -when you have procmail split the incoming mail into several files. -That is, there is a one-to-one correspondence between files in that -directory and groups, so that mail from the file @file{foo.bar.spool} -will be put in the group @code{foo.bar}. (You can change the suffix -to be used instead of @code{.spool}.) Setting -@code{nnmail-scan-directory-mail-source-once} to non-@code{nil} forces -Gnus to scan the mail source only once. This is particularly useful -if you want to scan mail groups at a specified level. - -@vindex nnmail-resplit-incoming -There is also the variable @code{nnmail-resplit-incoming}, if you set -that to a non-@code{nil} value, then the normal splitting process is -applied to all the files from the directory, @ref{Splitting Mail}. - -Keywords: - -@table @code -@item :path -The name of the directory where the files are. There is no default -value. - -@item :suffix -Only files ending with this suffix are used. The default is -@samp{.spool}. - -@item :predicate -Only files that have this predicate return non-@code{nil} are returned. -The default is @code{identity}. This is used as an additional -filter---only files that have the right suffix @emph{and} satisfy this -predicate are considered. - -@item :prescript -@itemx :postscript -Script run before/after fetching mail. - -@end table - -An example directory mail source: - -@lisp -(directory :path "/home/user-name/procmail-dir/" - :suffix ".prcml") -@end lisp - -@item pop -Get mail from a @acronym{POP} server. - -Keywords: - -@table @code -@item :server -The name of the @acronym{POP} server. The default is taken from the -@env{MAILHOST} environment variable. - -@item :port -The port number of the @acronym{POP} server. This can be a number (e.g., -@samp{:port 1234}) or a string (e.g., @samp{:port "pop3"}). If it is a -string, it should be a service name as listed in @file{/etc/services} on -Unix systems. The default is @samp{"pop3"}. On some systems you might -need to specify it as @samp{"pop-3"} instead. - -@item :user -The user name to give to the @acronym{POP} server. The default is the login -name. - -@item :password -The password to give to the @acronym{POP} server. If not specified, -the user is prompted. - -@item :program -The program to use to fetch mail from the @acronym{POP} server. This -should be a @code{format}-like string. Here's an example: - -@example -fetchmail %u@@%s -P %p %t -@end example - -The valid format specifier characters are: - -@table @samp -@item t -The name of the file the mail is to be moved to. This must always be -included in this string. - -@item s -The name of the server. - -@item P -The port number of the server. - -@item u -The user name to use. - -@item p -The password to use. -@end table - -The values used for these specs are taken from the values you give the -corresponding keywords. - -@item :prescript -A script to be run before fetching the mail. The syntax is the same as -the @code{:program} keyword. This can also be a function to be run. - -One popular way to use this is to set up an SSH tunnel to access the -@acronym{POP} server. Here's an example: - -@lisp -(pop :server "127.0.0.1" - :port 1234 - :user "foo" - :password "secret" - :prescript - "nohup ssh -f -L 1234:pop.server:110 remote.host sleep 3600 &") -@end lisp - -@item :postscript -A script to be run after fetching the mail. The syntax is the same as -the @code{:program} keyword. This can also be a function to be run. - -@item :function -The function to use to fetch mail from the @acronym{POP} server. The -function is called with one parameter---the name of the file where the -mail should be moved to. - -@item :authentication -This can be either the symbol @code{password} or the symbol @code{apop} -and says what authentication scheme to use. The default is -@code{password}. - -@item :leave -Non-@code{nil} if the mail is to be left on the @acronym{POP} server -after fetching. Only the built-in @code{pop3-movemail} program (the -default) supports this keyword. - -If this is a number, leave mails on the server for this many days since -you first checked new mails. In that case, mails once fetched will -never be fetched again by the @acronym{UIDL} control. If this is -@code{nil} (the default), mails will be deleted on the server right -after fetching. If this is neither @code{nil} nor a number, all mails -will be left on the server, and you will end up getting the same mails -again and again. - -@vindex pop3-uidl-file -The @code{pop3-uidl-file} variable specifies the file to which the -@acronym{UIDL} data are locally stored. The default value is -@file{~/.pop3-uidl}. - -Note that @acronym{POP} servers maintain no state information between -sessions, so what the client believes is there and what is actually -there may not match up. If they do not, then you may get duplicate -mails or the whole thing can fall apart and leave you with a corrupt -mailbox. - -@end table - -@findex pop3-movemail -@vindex pop3-leave-mail-on-server -If the @code{:program} and @code{:function} keywords aren't specified, -@code{pop3-movemail} will be used. - -Here are some examples for getting mail from a @acronym{POP} server. - -Fetch from the default @acronym{POP} server, using the default user -name, and default fetcher: - -@lisp -(pop) -@end lisp - -Fetch from a named server with a named user and password: - -@lisp -(pop :server "my.pop.server" - :user "user-name" :password "secret") -@end lisp - -Leave mails on the server for 14 days: - -@lisp -(pop :server "my.pop.server" - :user "user-name" :password "secret" - :leave 14) -@end lisp - -Use @samp{movemail} to move the mail: - -@lisp -(pop :program "movemail po:%u %t %p") -@end lisp - -@item maildir -Get mail from a maildir. This is a type of mailbox that is supported by -at least qmail and postfix, where each file in a special directory -contains exactly one mail. - -Keywords: - -@table @code -@item :path -The name of the directory where the mails are stored. The default is -taken from the @env{MAILDIR} environment variable or -@file{~/Maildir/}. -@item :subdirs -The subdirectories of the Maildir. The default is -@samp{("new" "cur")}. - -@c If you sometimes look at your mail through a pop3 daemon before fetching -@c them with Gnus, you may also have to fetch your mails from the -@c @code{cur} directory inside the maildir, like in the first example -@c below. - -You can also get mails from remote hosts (because maildirs don't suffer -from locking problems). - -@end table - -Two example maildir mail sources: - -@lisp -(maildir :path "/home/user-name/Maildir/" - :subdirs ("cur" "new")) -@end lisp - -@lisp -(maildir :path "/user@@remotehost.org:~/Maildir/" - :subdirs ("new")) -@end lisp - -@item imap -Get mail from a @acronym{IMAP} server. If you don't want to use -@acronym{IMAP} as intended, as a network mail reading protocol (i.e., -with nnimap), for some reason or other, Gnus let you treat it similar -to a @acronym{POP} server and fetches articles from a given -@acronym{IMAP} mailbox. @xref{Using IMAP}, for more information. - -Keywords: - -@table @code -@item :server -The name of the @acronym{IMAP} server. The default is taken from the -@env{MAILHOST} environment variable. - -@item :port -The port number of the @acronym{IMAP} server. The default is @samp{143}, or -@samp{993} for @acronym{TLS}/@acronym{SSL} connections. - -@item :user -The user name to give to the @acronym{IMAP} server. The default is the login -name. - -@item :password -The password to give to the @acronym{IMAP} server. If not specified, the user is -prompted. - -@item :stream -What stream to use for connecting to the server, this is one of the -symbols in @code{imap-stream-alist}. Right now, this means -@samp{gssapi}, @samp{kerberos4}, @samp{starttls}, @samp{tls}, -@samp{ssl}, @samp{shell} or the default @samp{network}. - -@item :authentication -Which authenticator to use for authenticating to the server, this is -one of the symbols in @code{imap-authenticator-alist}. Right now, -this means @samp{gssapi}, @samp{kerberos4}, @samp{digest-md5}, -@samp{cram-md5}, @samp{anonymous} or the default @samp{login}. - -@item :program -When using the `shell' :stream, the contents of this variable is -mapped into the @code{imap-shell-program} variable. This should be a -@code{format}-like string (or list of strings). Here's an example: - -@example -ssh %s imapd -@end example - -Make sure nothing is interfering with the output of the program, e.g., -don't forget to redirect the error output to the void. The valid format -specifier characters are: - -@table @samp -@item s -The name of the server. - -@item l -User name from @code{imap-default-user}. - -@item p -The port number of the server. -@end table - -The values used for these specs are taken from the values you give the -corresponding keywords. - -@item :mailbox -The name of the mailbox to get mail from. The default is @samp{INBOX} -which normally is the mailbox which receives incoming mail. - -@item :predicate -The predicate used to find articles to fetch. The default, @samp{UNSEEN -UNDELETED}, is probably the best choice for most people, but if you -sometimes peek in your mailbox with a @acronym{IMAP} client and mark some -articles as read (or; SEEN) you might want to set this to @samp{1:*}. -Then all articles in the mailbox is fetched, no matter what. For a -complete list of predicates, see RFC 2060 section 6.4.4. - -@item :fetchflag -How to flag fetched articles on the server, the default @samp{\Deleted} -will mark them as deleted, an alternative would be @samp{\Seen} which -would simply mark them as read. These are the two most likely choices, -but more flags are defined in RFC 2060 section 2.3.2. - -@item :dontexpunge -If non-@code{nil}, don't remove all articles marked as deleted in the -mailbox after finishing the fetch. - -@end table - -An example @acronym{IMAP} mail source: - -@lisp -(imap :server "mail.mycorp.com" - :stream kerberos4 - :fetchflag "\\Seen") -@end lisp - -@item group -Get the actual mail source from the @code{mail-source} group parameter, -@xref{Group Parameters}. - -@end table - -@table @dfn -@item Common Keywords -Common keywords can be used in any type of mail source. - -Keywords: - -@table @code -@item :plugged -If non-@code{nil}, fetch the mail even when Gnus is unplugged. If you -use directory source to get mail, you can specify it as in this -example: - -@lisp -(setq mail-sources - '((directory :path "/home/pavel/.Spool/" - :suffix "" - :plugged t))) -@end lisp - -Gnus will then fetch your mail even when you are unplugged. This is -useful when you use local mail and news. - -@end table -@end table - -@node Mail Source Functions -@subsubsection Function Interface - -Some of the above keywords specify a Lisp function to be executed. -For each keyword @code{:foo}, the Lisp variable @code{foo} is bound to -the value of the keyword while the function is executing. For example, -consider the following mail-source setting: - -@lisp -(setq mail-sources '((pop :user "jrl" - :server "pophost" :function fetchfunc))) -@end lisp - -While the function @code{fetchfunc} is executing, the symbol @code{user} -is bound to @code{"jrl"}, and the symbol @code{server} is bound to -@code{"pophost"}. The symbols @code{port}, @code{password}, -@code{program}, @code{prescript}, @code{postscript}, @code{function}, -and @code{authentication} are also bound (to their default values). - -See above for a list of keywords for each type of mail source. - - -@node Mail Source Customization -@subsubsection Mail Source Customization - -The following is a list of variables that influence how the mail is -fetched. You would normally not need to set or change any of these -variables. - -@table @code -@item mail-source-crash-box -@vindex mail-source-crash-box -File where mail will be stored while processing it. The default is@* -@file{~/.emacs-mail-crash-box}. - -@cindex Incoming* -@item mail-source-delete-incoming -@vindex mail-source-delete-incoming -If non-@code{nil}, delete incoming files after handling them. If -@code{t}, delete the files immediately, if @code{nil}, never delete any -files. If a positive number, delete files older than number of days -(the deletion will only happen when receiving new mail). You may also -set @code{mail-source-delete-incoming} to @code{nil} and call -@code{mail-source-delete-old-incoming} from a hook or interactively. -@code{mail-source-delete-incoming} defaults to @code{10} in alpha Gnusae -and @code{2} in released Gnusae. @xref{Gnus Development}. - -@item mail-source-delete-old-incoming-confirm -@vindex mail-source-delete-old-incoming-confirm -If non-@code{nil}, ask for confirmation before deleting old incoming -files. This variable only applies when -@code{mail-source-delete-incoming} is a positive number. - -@item mail-source-ignore-errors -@vindex mail-source-ignore-errors -If non-@code{nil}, ignore errors when reading mail from a mail source. - -@item mail-source-directory -@vindex mail-source-directory -Directory where incoming mail source files (if any) will be stored. The -default is @file{~/Mail/}. At present, the only thing this is used for -is to say where the incoming files will be stored if the variable -@code{mail-source-delete-incoming} is @code{nil} or a number. - -@item mail-source-incoming-file-prefix -@vindex mail-source-incoming-file-prefix -Prefix for file name for storing incoming mail. The default is -@file{Incoming}, in which case files will end up with names like -@file{Incoming30630D_} or @file{Incoming298602ZD}. This is really only -relevant if @code{mail-source-delete-incoming} is @code{nil} or a -number. - -@item mail-source-default-file-modes -@vindex mail-source-default-file-modes -All new mail files will get this file mode. The default is @code{#o600}. - -@item mail-source-movemail-program -@vindex mail-source-movemail-program -If non-@code{nil}, name of program for fetching new mail. If -@code{nil}, @code{movemail} in @var{exec-directory}. - -@end table - - -@node Fetching Mail -@subsubsection Fetching Mail - -@vindex mail-sources -The way to actually tell Gnus where to get new mail from is to set -@code{mail-sources} to a list of mail source specifiers -(@pxref{Mail Source Specifiers}). - -If this variable is @code{nil}, the mail back ends will never attempt to -fetch mail by themselves. - -If you want to fetch mail both from your local spool as well as a -@acronym{POP} mail server, you'd say something like: - -@lisp -(setq mail-sources - '((file) - (pop :server "pop3.mail.server" - :password "secret"))) -@end lisp - -Or, if you don't want to use any of the keyword defaults: - -@lisp -(setq mail-sources - '((file :path "/var/spool/mail/user-name") - (pop :server "pop3.mail.server" - :user "user-name" - :port "pop3" - :password "secret"))) -@end lisp - - -When you use a mail back end, Gnus will slurp all your mail from your -inbox and plonk it down in your home directory. Gnus doesn't move any -mail if you're not using a mail back end---you have to do a lot of magic -invocations first. At the time when you have finished drawing the -pentagram, lightened the candles, and sacrificed the goat, you really -shouldn't be too surprised when Gnus moves your mail. - - - -@node Mail Back End Variables -@subsection Mail Back End Variables - -These variables are (for the most part) pertinent to all the various -mail back ends. - -@table @code -@vindex nnmail-read-incoming-hook -@item nnmail-read-incoming-hook -The mail back ends all call this hook after reading new mail. You can -use this hook to notify any mail watch programs, if you want to. - -@vindex nnmail-split-hook -@item nnmail-split-hook -@findex gnus-article-decode-encoded-words -@cindex RFC 1522 decoding -@cindex RFC 2047 decoding -Hook run in the buffer where the mail headers of each message is kept -just before the splitting based on these headers is done. The hook is -free to modify the buffer contents in any way it sees fit---the buffer -is discarded after the splitting has been done, and no changes performed -in the buffer will show up in any files. -@code{gnus-article-decode-encoded-words} is one likely function to add -to this hook. - -@vindex nnmail-pre-get-new-mail-hook -@vindex nnmail-post-get-new-mail-hook -@item nnmail-pre-get-new-mail-hook -@itemx nnmail-post-get-new-mail-hook -These are two useful hooks executed when treating new incoming -mail---@code{nnmail-pre-get-new-mail-hook} (is called just before -starting to handle the new mail) and -@code{nnmail-post-get-new-mail-hook} (is called when the mail handling -is done). Here's and example of using these two hooks to change the -default file modes the new mail files get: - -@lisp -(add-hook 'nnmail-pre-get-new-mail-hook - (lambda () (set-default-file-modes #o700))) - -(add-hook 'nnmail-post-get-new-mail-hook - (lambda () (set-default-file-modes #o775))) -@end lisp - -@item nnmail-use-long-file-names -@vindex nnmail-use-long-file-names -If non-@code{nil}, the mail back ends will use long file and directory -names. Groups like @samp{mail.misc} will end up in directories -(assuming use of @code{nnml} back end) or files (assuming use of -@code{nnfolder} back end) like @file{mail.misc}. If it is @code{nil}, -the same group will end up in @file{mail/misc}. - -@item nnmail-delete-file-function -@vindex nnmail-delete-file-function -@findex delete-file -Function called to delete files. It is @code{delete-file} by default. - -@item nnmail-cache-accepted-message-ids -@vindex nnmail-cache-accepted-message-ids -If non-@code{nil}, put the @code{Message-ID}s of articles imported into -the back end (via @code{Gcc}, for instance) into the mail duplication -discovery cache. The default is @code{nil}. - -@item nnmail-cache-ignore-groups -@vindex nnmail-cache-ignore-groups -This can be a regular expression or a list of regular expressions. -Group names that match any of the regular expressions will never be -recorded in the @code{Message-ID} cache. - -This can be useful, for example, when using Fancy Splitting -(@pxref{Fancy Mail Splitting}) together with the function -@code{nnmail-split-fancy-with-parent}. - -@end table - - -@node Fancy Mail Splitting -@subsection Fancy Mail Splitting -@cindex mail splitting -@cindex fancy mail splitting - -@vindex nnmail-split-fancy -@findex nnmail-split-fancy -If the rather simple, standard method for specifying how to split mail -doesn't allow you to do what you want, you can set -@code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can -play with the @code{nnmail-split-fancy} variable. - -Let's look at an example value of this variable first: - -@lisp -;; @r{Messages from the mailer daemon are not crossposted to any of} -;; @r{the ordinary groups. Warnings are put in a separate group} -;; @r{from real errors.} -(| ("from" mail (| ("subject" "warn.*" "mail.warning") - "mail.misc")) - ;; @r{Non-error messages are crossposted to all relevant} - ;; @r{groups, but we don't crosspost between the group for the} - ;; @r{(ding) list and the group for other (ding) related mail.} - (& (| (any "ding@@ifi\\.uio\\.no" "ding.list") - ("subject" "ding" "ding.misc")) - ;; @r{Other mailing lists@dots{}} - (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list") - (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list") - ;; @r{Both lists below have the same suffix, so prevent} - ;; @r{cross-posting to mkpkg.list of messages posted only to} - ;; @r{the bugs- list, but allow cross-posting when the} - ;; @r{message was really cross-posted.} - (any "bugs-mypackage@@somewhere" "mypkg.bugs") - (any "mypackage@@somewhere" - "bugs-mypackage" "mypkg.list") - ;; @r{People@dots{}} - (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) - ;; @r{Unmatched mail goes to the catch all group.} - "misc.misc") -@end lisp - -This variable has the format of a @dfn{split}. A split is a -(possibly) recursive structure where each split may contain other -splits. Here are the possible split syntaxes: - -@table @code - -@item group -If the split is a string, that will be taken as a group name. Normal -regexp match expansion will be done. See below for examples. - -@c Don't fold this line. -@item (@var{field} @var{value} [- @var{restrict} [@dots{}] ] @var{split} [@var{invert-partial}]) -The split can be a list containing at least three elements. If the -first element @var{field} (a regexp matching a header) contains -@var{value} (also a regexp) then store the message as specified by -@var{split}. - -If @var{restrict} (yet another regexp) matches some string after -@var{field} and before the end of the matched @var{value}, the -@var{split} is ignored. If none of the @var{restrict} clauses match, -@var{split} is processed. - -The last element @var{invert-partial} is optional. If it is -non-@code{nil}, the match-partial-words behavior controlled by the -variable @code{nnmail-split-fancy-match-partial-words} (see below) is -be inverted. (New in Gnus 5.10.7) - -@item (| @var{split} @dots{}) -If the split is a list, and the first element is @code{|} (vertical -bar), then process each @var{split} until one of them matches. A -@var{split} is said to match if it will cause the mail message to be -stored in one or more groups. - -@item (& @var{split} @dots{}) -If the split is a list, and the first element is @code{&}, then -process all @var{split}s in the list. - -@item junk -If the split is the symbol @code{junk}, then don't save (i.e., delete) -this message. Use with extreme caution. - -@item (: @var{function} @var{arg1} @var{arg2} @dots{}) -If the split is a list, and the first element is @samp{:}, then the -second element will be called as a function with @var{args} given as -arguments. The function should return a @var{split}. - -@cindex body split -For instance, the following function could be used to split based on the -body of the messages: - -@lisp -(defun split-on-body () - (save-excursion - (save-restriction - (widen) - (goto-char (point-min)) - (when (re-search-forward "Some.*string" nil t) - "string.group")))) -@end lisp - -The buffer is narrowed to the header of the message in question when -@var{function} is run. That's why @code{(widen)} needs to be called -after @code{save-excursion} and @code{save-restriction} in the example -above. Also note that with the nnimap backend, message bodies will -not be downloaded by default. You need to set -@code{nnimap-split-download-body} to @code{t} to do that -(@pxref{Client-Side IMAP Splitting}). - -@item (! @var{func} @var{split}) -If the split is a list, and the first element is @code{!}, then -@var{split} will be processed, and @var{func} will be called as a -function with the result of @var{split} as argument. @var{func} -should return a split. - -@item nil -If the split is @code{nil}, it is ignored. - -@end table - -In these splits, @var{field} must match a complete field name. - -Normally, @var{value} in these splits must match a complete @emph{word} -according to the fundamental mode syntax table. In other words, all -@var{value}'s will be implicitly surrounded by @code{\<...\>} markers, -which are word delimiters. Therefore, if you use the following split, -for example, - -@example -(any "joe" "joemail") -@end example - -@noindent -messages sent from @samp{joedavis@@foo.org} will normally not be filed -in @samp{joemail}. If you want to alter this behavior, you can use any -of the following three ways: - -@enumerate -@item -@vindex nnmail-split-fancy-match-partial-words -You can set the @code{nnmail-split-fancy-match-partial-words} variable -to non-@code{nil} in order to ignore word boundaries and instead the -match becomes more like a grep. This variable controls whether partial -words are matched during fancy splitting. The default value is -@code{nil}. - -Note that it influences all @var{value}'s in your split rules. - -@item -@var{value} beginning with @code{.*} ignores word boundaries in front of -a word. Similarly, if @var{value} ends with @code{.*}, word boundaries -in the rear of a word will be ignored. For example, the @var{value} -@code{"@@example\\.com"} does not match @samp{foo@@example.com} but -@code{".*@@example\\.com"} does. - -@item -You can set the @var{invert-partial} flag in your split rules of the -@samp{(@var{field} @var{value} @dots{})} types, aforementioned in this -section. If the flag is set, word boundaries on both sides of a word -are ignored even if @code{nnmail-split-fancy-match-partial-words} is -@code{nil}. Contrarily, if the flag is set, word boundaries are not -ignored even if @code{nnmail-split-fancy-match-partial-words} is -non-@code{nil}. (New in Gnus 5.10.7) -@end enumerate - -@vindex nnmail-split-abbrev-alist -@var{field} and @var{value} can also be Lisp symbols, in that case -they are expanded as specified by the variable -@code{nnmail-split-abbrev-alist}. This is an alist of cons cells, -where the @sc{car} of a cell contains the key, and the @sc{cdr} -contains the associated value. Predefined entries in -@code{nnmail-split-abbrev-alist} include: - -@table @code -@item from -Matches the @samp{From}, @samp{Sender} and @samp{Resent-From} fields. -@item to -Matches the @samp{To}, @samp{Cc}, @samp{Apparently-To}, -@samp{Resent-To} and @samp{Resent-Cc} fields. -@item any -Is the union of the @code{from} and @code{to} entries. -@end table - -@vindex nnmail-split-fancy-syntax-table -@code{nnmail-split-fancy-syntax-table} is the syntax table in effect -when all this splitting is performed. - -If you want to have Gnus create groups dynamically based on some -information in the headers (i.e., do @code{replace-match}-like -substitutions in the group names), you can say things like: - -@example -(any "debian-\\b\\(\\w+\\)@@lists.debian.org" "mail.debian.\\1") -@end example - -In this example, messages sent to @samp{debian-foo@@lists.debian.org} -will be filed in @samp{mail.debian.foo}. - -If the string contains the element @samp{\\&}, then the previously -matched string will be substituted. Similarly, the elements @samp{\\1} -up to @samp{\\9} will be substituted with the text matched by the -groupings 1 through 9. - -@vindex nnmail-split-lowercase-expanded -Where @code{nnmail-split-lowercase-expanded} controls whether the -lowercase of the matched string should be used for the substitution. -Setting it as non-@code{nil} is useful to avoid the creation of multiple -groups when users send to an address using different case -(i.e., mailing-list@@domain vs Mailing-List@@Domain). The default value -is @code{t}. - -@findex nnmail-split-fancy-with-parent -@code{nnmail-split-fancy-with-parent} is a function which allows you to -split followups into the same groups their parents are in. Sometimes -you can't make splitting rules for all your mail. For example, your -boss might send you personal mail regarding different projects you are -working on, and as you can't tell your boss to put a distinguishing -string into the subject line, you have to resort to manually moving the -messages into the right group. With this function, you only have to do -it once per thread. - -To use this feature, you have to set @code{nnmail-treat-duplicates} -and @code{nnmail-cache-accepted-message-ids} to a non-@code{nil} -value. And then you can include @code{nnmail-split-fancy-with-parent} -using the colon feature, like so: -@lisp -(setq nnmail-treat-duplicates 'warn ; @r{or @code{delete}} - nnmail-cache-accepted-message-ids t - nnmail-split-fancy - '(| (: nnmail-split-fancy-with-parent) - ;; @r{other splits go here} - )) -@end lisp - -This feature works as follows: when @code{nnmail-treat-duplicates} is -non-@code{nil}, Gnus records the message id of every message it sees -in the file specified by the variable -@code{nnmail-message-id-cache-file}, together with the group it is in -(the group is omitted for non-mail messages). When mail splitting is -invoked, the function @code{nnmail-split-fancy-with-parent} then looks -at the References (and In-Reply-To) header of each message to split -and searches the file specified by @code{nnmail-message-id-cache-file} -for the message ids. When it has found a parent, it returns the -corresponding group name unless the group name matches the regexp -@code{nnmail-split-fancy-with-parent-ignore-groups}. It is -recommended that you set @code{nnmail-message-id-cache-length} to a -somewhat higher number than the default so that the message ids are -still in the cache. (A value of 5000 appears to create a file some -300 kBytes in size.) -@vindex nnmail-cache-accepted-message-ids -When @code{nnmail-cache-accepted-message-ids} is non-@code{nil}, Gnus -also records the message ids of moved articles, so that the followup -messages goes into the new group. - -Also see the variable @code{nnmail-cache-ignore-groups} if you don't -want certain groups to be recorded in the cache. For example, if all -outgoing messages are written to an ``outgoing'' group, you could set -@code{nnmail-cache-ignore-groups} to match that group name. -Otherwise, answers to all your messages would end up in the -``outgoing'' group. - - -@node Group Mail Splitting -@subsection Group Mail Splitting -@cindex mail splitting -@cindex group mail splitting - -@findex gnus-group-split -If you subscribe to dozens of mailing lists but you don't want to -maintain mail splitting rules manually, group mail splitting is for you. -You just have to set @code{to-list} and/or @code{to-address} in group -parameters or group customization and set @code{nnmail-split-methods} to -@code{gnus-group-split}. This splitting function will scan all groups -for those parameters and split mail accordingly, i.e., messages posted -from or to the addresses specified in the parameters @code{to-list} or -@code{to-address} of a mail group will be stored in that group. - -Sometimes, mailing lists have multiple addresses, and you may want mail -splitting to recognize them all: just set the @code{extra-aliases} group -parameter to the list of additional addresses and it's done. If you'd -rather use a regular expression, set @code{split-regexp}. - -All these parameters in a group will be used to create an -@code{nnmail-split-fancy} split, in which the @var{field} is @samp{any}, -the @var{value} is a single regular expression that matches -@code{to-list}, @code{to-address}, all of @code{extra-aliases} and all -matches of @code{split-regexp}, and the @var{split} is the name of the -group. @var{restrict}s are also supported: just set the -@code{split-exclude} parameter to a list of regular expressions. - -If you can't get the right split to be generated using all these -parameters, or you just need something fancier, you can set the -parameter @code{split-spec} to an @code{nnmail-split-fancy} split. In -this case, all other aforementioned parameters will be ignored by -@code{gnus-group-split}. In particular, @code{split-spec} may be set to -@code{nil}, in which case the group will be ignored by -@code{gnus-group-split}. - -@vindex gnus-group-split-default-catch-all-group -@code{gnus-group-split} will do cross-posting on all groups that match, -by defining a single @code{&} fancy split containing one split for each -group. If a message doesn't match any split, it will be stored in the -group named in @code{gnus-group-split-default-catch-all-group}, unless -some group has @code{split-spec} set to @code{catch-all}, in which case -that group is used as the catch-all group. Even though this variable is -often used just to name a group, it may also be set to an arbitrarily -complex fancy split (after all, a group name is a fancy split), and this -may be useful to split mail that doesn't go to any mailing list to -personal mail folders. Note that this fancy split is added as the last -element of a @code{|} split list that also contains a @code{&} split -with the rules extracted from group parameters. - -It's time for an example. Assume the following group parameters have -been defined: - -@example -nnml:mail.bar: -((to-address . "bar@@femail.com") - (split-regexp . ".*@@femail\\.com")) -nnml:mail.foo: -((to-list . "foo@@nowhere.gov") - (extra-aliases "foo@@localhost" "foo-redist@@home") - (split-exclude "bugs-foo" "rambling-foo") - (admin-address . "foo-request@@nowhere.gov")) -nnml:mail.others: -((split-spec . catch-all)) -@end example - -Setting @code{nnmail-split-methods} to @code{gnus-group-split} will -behave as if @code{nnmail-split-fancy} had been selected and variable -@code{nnmail-split-fancy} had been set as follows: - -@lisp -(| (& (any "\\(bar@@femail\\.com\\|.*@@femail\\.com\\)" "mail.bar") - (any "\\(foo@@nowhere\\.gov\\|foo@@localhost\\|foo-redist@@home\\)" - - "bugs-foo" - "rambling-foo" "mail.foo")) - "mail.others") -@end lisp - -@findex gnus-group-split-fancy -If you'd rather not use group splitting for all your mail groups, you -may use it for only some of them, by using @code{nnmail-split-fancy} -splits like this: - -@lisp -(: gnus-group-split-fancy @var{groups} @var{no-crosspost} @var{catch-all}) -@end lisp - -@var{groups} may be a regular expression or a list of group names whose -parameters will be scanned to generate the output split. -@var{no-crosspost} can be used to disable cross-posting; in this case, a -single @code{|} split will be output. @var{catch-all} is the fall back -fancy split, used like @code{gnus-group-split-default-catch-all-group}. -If @var{catch-all} is @code{nil}, or if @code{split-regexp} matches the -empty string in any selected group, no catch-all split will be issued. -Otherwise, if some group has @code{split-spec} set to @code{catch-all}, -this group will override the value of the @var{catch-all} argument. - -@findex gnus-group-split-setup -Unfortunately, scanning all groups and their parameters can be quite -slow, especially considering that it has to be done for every message. -But don't despair! The function @code{gnus-group-split-setup} can be -used to enable @code{gnus-group-split} in a much more efficient way. It -sets @code{nnmail-split-methods} to @code{nnmail-split-fancy} and sets -@code{nnmail-split-fancy} to the split produced by -@code{gnus-group-split-fancy}. Thus, the group parameters are only -scanned once, no matter how many messages are split. - -@findex gnus-group-split-update -However, if you change group parameters, you'd have to update -@code{nnmail-split-fancy} manually. You can do it by running -@code{gnus-group-split-update}. If you'd rather have it updated -automatically, just tell @code{gnus-group-split-setup} to do it for -you. For example, add to your @file{~/.gnus.el}: - -@lisp -(gnus-group-split-setup @var{auto-update} @var{catch-all}) -@end lisp - -If @var{auto-update} is non-@code{nil}, @code{gnus-group-split-update} -will be added to @code{nnmail-pre-get-new-mail-hook}, so you won't ever -have to worry about updating @code{nnmail-split-fancy} again. If you -don't omit @var{catch-all} (it's optional, equivalent to @code{nil}), -@code{gnus-group-split-default-catch-all-group} will be set to its -value. - -@vindex gnus-group-split-updated-hook -Because you may want to change @code{nnmail-split-fancy} after it is set -by @code{gnus-group-split-update}, this function will run -@code{gnus-group-split-updated-hook} just before finishing. - -@node Incorporating Old Mail -@subsection Incorporating Old Mail -@cindex incorporating old mail -@cindex import old mail - -Most people have lots of old mail stored in various file formats. If -you have set up Gnus to read mail using one of the spiffy Gnus mail -back ends, you'll probably wish to have that old mail incorporated into -your mail groups. - -Doing so can be quite easy. - -To take an example: You're reading mail using @code{nnml} -(@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a -satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox -file filled with important, but old, mail. You want to move it into -your @code{nnml} groups. - -Here's how: - -@enumerate -@item -Go to the group buffer. - -@item -Type @kbd{G f} and give the file name to the mbox file when prompted to create an -@code{nndoc} group from the mbox file (@pxref{Foreign Groups}). - -@item -Type @kbd{SPACE} to enter the newly created group. - -@item -Type @kbd{M P b} to process-mark all articles in this group's buffer -(@pxref{Setting Process Marks}). - -@item -Type @kbd{B r} to respool all the process-marked articles, and answer -@samp{nnml} when prompted (@pxref{Mail Group Commands}). -@end enumerate - -All the mail messages in the mbox file will now also be spread out over -all your @code{nnml} groups. Try entering them and check whether things -have gone without a glitch. If things look ok, you may consider -deleting the mbox file, but I wouldn't do that unless I was absolutely -sure that all the mail has ended up where it should be. - -Respooling is also a handy thing to do if you're switching from one mail -back end to another. Just respool all the mail in the old mail groups -using the new mail back end. - - -@node Expiring Mail -@subsection Expiring Mail -@cindex article expiry -@cindex expiring mail - -Traditional mail readers have a tendency to remove mail articles when -you mark them as read, in some way. Gnus takes a fundamentally -different approach to mail reading. - -Gnus basically considers mail just to be news that has been received in -a rather peculiar manner. It does not think that it has the power to -actually change the mail, or delete any mail messages. If you enter a -mail group, and mark articles as ``read'', or kill them in some other -fashion, the mail articles will still exist on the system. I repeat: -Gnus will not delete your old, read mail. Unless you ask it to, of -course. - -To make Gnus get rid of your unwanted mail, you have to mark the -articles as @dfn{expirable}. (With the default key bindings, this means -that you have to type @kbd{E}.) This does not mean that the articles -will disappear right away, however. In general, a mail article will be -deleted from your system if, 1) it is marked as expirable, AND 2) it is -more than one week old. If you do not mark an article as expirable, it -will remain on your system until hell freezes over. This bears -repeating one more time, with some spurious capitalizations: IF you do -NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES. - -@vindex gnus-auto-expirable-marks -You do not have to mark articles as expirable by hand. Gnus provides -two features, called ``auto-expire'' and ``total-expire'', that can help you -with this. In a nutshell, ``auto-expire'' means that Gnus hits @kbd{E} -for you when you select an article. And ``total-expire'' means that Gnus -considers all articles as expirable that are read. So, in addition to -the articles marked @samp{E}, also the articles marked @samp{r}, -@samp{R}, @samp{O}, @samp{K}, @samp{Y} (and so on) are considered -expirable. @code{gnus-auto-expirable-marks} has the full list of -these marks. - -When should either auto-expire or total-expire be used? Most people -who are subscribed to mailing lists split each list into its own group -and then turn on auto-expire or total-expire for those groups. -(@xref{Splitting Mail}, for more information on splitting each list -into its own group.) - -Which one is better, auto-expire or total-expire? It's not easy to -answer. Generally speaking, auto-expire is probably faster. Another -advantage of auto-expire is that you get more marks to work with: for -the articles that are supposed to stick around, you can still choose -between tick and dormant and read marks. But with total-expire, you -only have dormant and ticked to choose from. The advantage of -total-expire is that it works well with adaptive scoring (@pxref{Adaptive -Scoring}). Auto-expire works with normal scoring but not with adaptive -scoring. - -@vindex gnus-auto-expirable-newsgroups -Groups that match the regular expression -@code{gnus-auto-expirable-newsgroups} will have all articles that you -read marked as expirable automatically. All articles marked as -expirable have an @samp{E} in the first column in the summary buffer. - -By default, if you have auto expiry switched on, Gnus will mark all the -articles you read as expirable, no matter if they were read or unread -before. To avoid having articles marked as read marked as expirable -automatically, you can put something like the following in your -@file{~/.gnus.el} file: - -@vindex gnus-mark-article-hook -@lisp -(remove-hook 'gnus-mark-article-hook - 'gnus-summary-mark-read-and-unread-as-read) -(add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read) -@end lisp - -Note that making a group auto-expirable doesn't mean that all read -articles are expired---only the articles marked as expirable -will be expired. Also note that using the @kbd{d} command won't make -articles expirable---only semi-automatic marking of articles as read will -mark the articles as expirable in auto-expirable groups. - -Let's say you subscribe to a couple of mailing lists, and you want the -articles you have read to disappear after a while: - -@lisp -(setq gnus-auto-expirable-newsgroups - "mail.nonsense-list\\|mail.nice-list") -@end lisp - -Another way to have auto-expiry happen is to have the element -@code{auto-expire} in the group parameters of the group. - -If you use adaptive scoring (@pxref{Adaptive Scoring}) and -auto-expiring, you'll have problems. Auto-expiring and adaptive scoring -don't really mix very well. - -@vindex nnmail-expiry-wait -The @code{nnmail-expiry-wait} variable supplies the default time an -expirable article has to live. Gnus starts counting days from when the -message @emph{arrived}, not from when it was sent. The default is seven -days. - -Gnus also supplies a function that lets you fine-tune how long articles -are to live, based on what group they are in. Let's say you want to -have one month expiry period in the @samp{mail.private} group, a one day -expiry period in the @samp{mail.junk} group, and a six day expiry period -everywhere else: - -@vindex nnmail-expiry-wait-function -@lisp -(setq nnmail-expiry-wait-function - (lambda (group) - (cond ((string= group "mail.private") - 31) - ((string= group "mail.junk") - 1) - ((string= group "important") - 'never) - (t - 6)))) -@end lisp - -The group names this function is fed are ``unadorned'' group -names---no @samp{nnml:} prefixes and the like. - -The @code{nnmail-expiry-wait} variable and -@code{nnmail-expiry-wait-function} function can either be a number (not -necessarily an integer) or one of the symbols @code{immediate} or -@code{never}. - -You can also use the @code{expiry-wait} group parameter to selectively -change the expiry period (@pxref{Group Parameters}). - -@vindex nnmail-expiry-target -The normal action taken when expiring articles is to delete them. -However, in some circumstances it might make more sense to move them -to other groups instead of deleting them. The variable -@code{nnmail-expiry-target} (and the @code{expiry-target} group -parameter) controls this. The variable supplies a default value for -all groups, which can be overridden for specific groups by the group -parameter. default value is @code{delete}, but this can also be a -string (which should be the name of the group the message should be -moved to), or a function (which will be called in a buffer narrowed to -the message in question, and with the name of the group being moved -from as its parameter) which should return a target---either a group -name or @code{delete}. - -Here's an example for specifying a group name: -@lisp -(setq nnmail-expiry-target "nnml:expired") -@end lisp - -@findex nnmail-fancy-expiry-target -@vindex nnmail-fancy-expiry-targets -Gnus provides a function @code{nnmail-fancy-expiry-target} which will -expire mail to groups according to the variable -@code{nnmail-fancy-expiry-targets}. Here's an example: - -@lisp - (setq nnmail-expiry-target 'nnmail-fancy-expiry-target - nnmail-fancy-expiry-targets - '((to-from "boss" "nnfolder:Work") - ("subject" "IMPORTANT" "nnfolder:IMPORTANT.%Y.%b") - ("from" ".*" "nnfolder:Archive-%Y"))) -@end lisp - -With this setup, any mail that has @code{IMPORTANT} in its Subject -header and was sent in the year @code{YYYY} and month @code{MMM}, will -get expired to the group @code{nnfolder:IMPORTANT.YYYY.MMM}. If its -From or To header contains the string @code{boss}, it will get expired -to @code{nnfolder:Work}. All other mail will get expired to -@code{nnfolder:Archive-YYYY}. - -@vindex nnmail-keep-last-article -If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never -expire the final article in a mail newsgroup. This is to make life -easier for procmail users. - -@vindex gnus-total-expirable-newsgroups -By the way: That line up there, about Gnus never expiring non-expirable -articles, is a lie. If you put @code{total-expire} in the group -parameters, articles will not be marked as expirable, but all read -articles will be put through the expiry process. Use with extreme -caution. Even more dangerous is the -@code{gnus-total-expirable-newsgroups} variable. All groups that match -this regexp will have all read articles put through the expiry process, -which means that @emph{all} old mail articles in the groups in question -will be deleted after a while. Use with extreme caution, and don't come -crying to me when you discover that the regexp you used matched the -wrong group and all your important mail has disappeared. Be a -@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable -with! So there! - -Most people make most of their mail groups total-expirable, though. - -@vindex gnus-inhibit-user-auto-expire -If @code{gnus-inhibit-user-auto-expire} is non-@code{nil}, user marking -commands will not mark an article as expirable, even if the group has -auto-expire turned on. - -@vindex gnus-mark-copied-or-moved-articles-as-expirable -The expirable marks of articles will be removed when copying or moving -them to a group in which auto-expire is not turned on. This is for -preventing articles from being expired unintentionally. On the other -hand, to a group that has turned auto-expire on, the expirable marks of -articles that are copied or moved will not be changed by default. I.e., -when copying or moving to such a group, articles that were expirable -will be left expirable and ones that were not expirable will not be -marked as expirable. So, even though in auto-expire groups, some -articles will never get expired (unless you read them again). If you -don't side with that behavior that unexpirable articles may be mixed -into auto-expire groups, you can set -@code{gnus-mark-copied-or-moved-articles-as-expirable} to a -non-@code{nil} value. In that case, articles that have been read will -be marked as expirable automatically when being copied or moved to a -group that has auto-expire turned on. The default value is @code{nil}. - - -@node Washing Mail -@subsection Washing Mail -@cindex mail washing -@cindex list server brain damage -@cindex incoming mail treatment - -Mailers and list servers are notorious for doing all sorts of really, -really stupid things with mail. ``Hey, RFC 822 doesn't explicitly -prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the -end of all lines passing through our server, so let's do that!!!!1!'' -Yes, but RFC 822 wasn't designed to be read by morons. Things that were -considered to be self-evident were not discussed. So. Here we are. - -Case in point: The German version of Microsoft Exchange adds @samp{AW: -} to the subjects of replies instead of @samp{Re: }. I could pretend to -be shocked and dismayed by this, but I haven't got the energy. It is to -laugh. - -Gnus provides a plethora of functions for washing articles while -displaying them, but it might be nicer to do the filtering before -storing the mail to disk. For that purpose, we have three hooks and -various functions that can be put in these hooks. - -@table @code -@item nnmail-prepare-incoming-hook -@vindex nnmail-prepare-incoming-hook -This hook is called before doing anything with the mail and is meant for -grand, sweeping gestures. It is called in a buffer that contains all -the new, incoming mail. Functions to be used include: - -@table @code -@item nnheader-ms-strip-cr -@findex nnheader-ms-strip-cr -Remove trailing carriage returns from each line. This is default on -Emacs running on MS machines. - -@end table - -@item nnmail-prepare-incoming-header-hook -@vindex nnmail-prepare-incoming-header-hook -This hook is called narrowed to each header. It can be used when -cleaning up the headers. Functions that can be used include: - -@table @code -@item nnmail-remove-leading-whitespace -@findex nnmail-remove-leading-whitespace -Clear leading white space that ``helpful'' listservs have added to the -headers to make them look nice. Aaah. - -(Note that this function works on both the header on the body of all -messages, so it is a potentially dangerous function to use (if a body -of a message contains something that looks like a header line). So -rather than fix the bug, it is of course the right solution to make it -into a feature by documenting it.) - -@item nnmail-remove-list-identifiers -@findex nnmail-remove-list-identifiers -Some list servers add an identifier---for example, @samp{(idm)}---to the -beginning of all @code{Subject} headers. I'm sure that's nice for -people who use stone age mail readers. This function will remove -strings that match the @code{nnmail-list-identifiers} regexp, which can -also be a list of regexp. @code{nnmail-list-identifiers} may not contain -@code{\\(..\\)}. - -For instance, if you want to remove the @samp{(idm)} and the -@samp{nagnagnag} identifiers: - -@lisp -(setq nnmail-list-identifiers - '("(idm)" "nagnagnag")) -@end lisp - -This can also be done non-destructively with -@code{gnus-list-identifiers}, @xref{Article Hiding}. - -@item nnmail-remove-tabs -@findex nnmail-remove-tabs -Translate all @samp{TAB} characters into @samp{SPACE} characters. - -@item nnmail-ignore-broken-references -@findex nnmail-ignore-broken-references -@c @findex nnmail-fix-eudora-headers -@cindex Eudora -@cindex Pegasus -Some mail user agents (e.g., Eudora and Pegasus) produce broken -@code{References} headers, but correct @code{In-Reply-To} headers. This -function will get rid of the @code{References} header if the headers -contain a line matching the regular expression -@code{nnmail-broken-references-mailers}. - -@end table - -@item nnmail-prepare-incoming-message-hook -@vindex nnmail-prepare-incoming-message-hook -This hook is called narrowed to each message. Functions to be used -include: - -@table @code -@item article-de-quoted-unreadable -@findex article-de-quoted-unreadable -Decode Quoted Readable encoding. - -@end table -@end table - - -@node Duplicates -@subsection Duplicates - -@vindex nnmail-treat-duplicates -@vindex nnmail-message-id-cache-length -@vindex nnmail-message-id-cache-file -@cindex duplicate mails -If you are a member of a couple of mailing lists, you will sometimes -receive two copies of the same mail. This can be quite annoying, so -@code{nnmail} checks for and treats any duplicates it might find. To do -this, it keeps a cache of old @code{Message-ID}s: -@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by -default. The approximate maximum number of @code{Message-ID}s stored -there is controlled by the @code{nnmail-message-id-cache-length} -variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be -stored.) If all this sounds scary to you, you can set -@code{nnmail-treat-duplicates} to @code{warn} (which is what it is by -default), and @code{nnmail} won't delete duplicate mails. Instead it -will insert a warning into the head of the mail saying that it thinks -that this is a duplicate of a different message. - -This variable can also be a function. If that's the case, the function -will be called from a buffer narrowed to the message in question with -the @code{Message-ID} as a parameter. The function must return either -@code{nil}, @code{warn}, or @code{delete}. - -You can turn this feature off completely by setting the variable to -@code{nil}. - -If you want all the duplicate mails to be put into a special -@dfn{duplicates} group, you could do that using the normal mail split -methods: - -@lisp -(setq nnmail-split-fancy - '(| ;; @r{Messages duplicates go to a separate group.} - ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate") - ;; @r{Message from daemons, postmaster, and the like to another.} - (any mail "mail.misc") - ;; @r{Other rules.} - [...] )) -@end lisp -@noindent -Or something like: -@lisp -(setq nnmail-split-methods - '(("duplicates" "^Gnus-Warning:.*duplicate") - ;; @r{Other rules.} - [...])) -@end lisp - -Here's a neat feature: If you know that the recipient reads her mail -with Gnus, and that she has @code{nnmail-treat-duplicates} set to -@code{delete}, you can send her as many insults as you like, just by -using a @code{Message-ID} of a mail that you know that she's already -received. Think of all the fun! She'll never see any of it! Whee! - - -@node Not Reading Mail -@subsection Not Reading Mail - -If you start using any of the mail back ends, they have the annoying -habit of assuming that you want to read mail with them. This might not -be unreasonable, but it might not be what you want. - -If you set @code{mail-sources} and @code{nnmail-spool-file} to -@code{nil}, none of the back ends will ever attempt to read incoming -mail, which should help. - -@vindex nnbabyl-get-new-mail -@vindex nnmbox-get-new-mail -@vindex nnml-get-new-mail -@vindex nnmh-get-new-mail -@vindex nnfolder-get-new-mail -This might be too much, if, for instance, you are reading mail quite -happily with @code{nnml} and just want to peek at some old (pre-Emacs -23) Rmail file you have stashed away with @code{nnbabyl}. All back ends have -variables called back-end-@code{get-new-mail}. If you want to disable -the @code{nnbabyl} mail reading, you edit the virtual server for the -group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}. - -All the mail back ends will call @code{nn}*@code{-prepare-save-mail-hook} -narrowed to the article to be saved before saving it when reading -incoming mail. - - -@node Choosing a Mail Back End -@subsection Choosing a Mail Back End - -Gnus will read the mail spool when you activate a mail group. The mail -file is first copied to your home directory. What happens after that -depends on what format you want to store your mail in. - -There are six different mail back ends in the standard Gnus, and more -back ends are available separately. The mail back end most people use -(because it is possibly the fastest) is @code{nnml} (@pxref{Mail -Spool}). - -@menu -* Unix Mail Box:: Using the (quite) standard Un*x mbox. -* Babyl:: Babyl was used by older versions of Rmail. -* Mail Spool:: Store your mail in a private spool? -* MH Spool:: An mhspool-like back end. -* Maildir:: Another one-file-per-message format. -* nnmaildir Group Parameters:: -* Article Identification:: -* NOV Data:: -* Article Marks:: -* Mail Folders:: Having one file for each group. -* Comparing Mail Back Ends:: An in-depth looks at pros and cons. -@end menu - - - -@node Unix Mail Box -@subsubsection Unix Mail Box -@cindex nnmbox -@cindex unix mail box - -@vindex nnmbox-active-file -@vindex nnmbox-mbox-file -The @dfn{nnmbox} back end will use the standard Un*x mbox file to store -mail. @code{nnmbox} will add extra headers to each mail article to say -which group it belongs in. - -Virtual server settings: - -@table @code -@item nnmbox-mbox-file -@vindex nnmbox-mbox-file -The name of the mail box in the user's home directory. Default is -@file{~/mbox}. - -@item nnmbox-active-file -@vindex nnmbox-active-file -The name of the active file for the mail box. Default is -@file{~/.mbox-active}. - -@item nnmbox-get-new-mail -@vindex nnmbox-get-new-mail -If non-@code{nil}, @code{nnmbox} will read incoming mail and split it -into groups. Default is @code{t}. -@end table - - -@node Babyl -@subsubsection Babyl -@cindex nnbabyl - -@vindex nnbabyl-active-file -@vindex nnbabyl-mbox-file -The @dfn{nnbabyl} back end will use a Babyl mail box to store mail. -@code{nnbabyl} will add extra headers to each mail article to say which -group it belongs in. - -Virtual server settings: - -@table @code -@item nnbabyl-mbox-file -@vindex nnbabyl-mbox-file -The name of the Babyl file. The default is @file{~/RMAIL} - -@item nnbabyl-active-file -@vindex nnbabyl-active-file -The name of the active file for the Babyl file. The default is -@file{~/.rmail-active} - -@item nnbabyl-get-new-mail -@vindex nnbabyl-get-new-mail -If non-@code{nil}, @code{nnbabyl} will read incoming mail. Default is -@code{t} -@end table - - -@node Mail Spool -@subsubsection Mail Spool -@cindex nnml -@cindex mail @acronym{NOV} spool - -The @dfn{nnml} spool mail format isn't compatible with any other known -format. It should be used with some caution. - -@vindex nnml-directory -If you use this back end, Gnus will split all incoming mail into files, -one file for each mail, and put the articles into the corresponding -directories under the directory specified by the @code{nnml-directory} -variable. The default value is @file{~/Mail/}. - -You do not have to create any directories beforehand; Gnus will take -care of all that. - -If you have a strict limit as to how many files you are allowed to store -in your account, you should not use this back end. As each mail gets its -own file, you might very well occupy thousands of inodes within a few -weeks. If this is no problem for you, and it isn't a problem for you -having your friendly systems administrator walking around, madly, -shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should -know that this is probably the fastest format to use. You do not have -to trudge through a big mbox file just to read your new mail. - -@code{nnml} is probably the slowest back end when it comes to article -splitting. It has to create lots of files, and it also generates -@acronym{NOV} databases for the incoming mails. This makes it possibly the -fastest back end when it comes to reading mail. - -Virtual server settings: - -@table @code -@item nnml-directory -@vindex nnml-directory -All @code{nnml} directories will be placed under this directory. The -default is the value of @code{message-directory} (whose default value -is @file{~/Mail}). - -@item nnml-active-file -@vindex nnml-active-file -The active file for the @code{nnml} server. The default is -@file{~/Mail/active}. - -@item nnml-newsgroups-file -@vindex nnml-newsgroups-file -The @code{nnml} group descriptions file. @xref{Newsgroups File -Format}. The default is @file{~/Mail/newsgroups}. - -@item nnml-get-new-mail -@vindex nnml-get-new-mail -If non-@code{nil}, @code{nnml} will read incoming mail. The default is -@code{t}. - -@item nnml-nov-is-evil -@vindex nnml-nov-is-evil -If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The -default is @code{nil}. - -@item nnml-nov-file-name -@vindex nnml-nov-file-name -The name of the @acronym{NOV} files. The default is @file{.overview}. - -@item nnml-prepare-save-mail-hook -@vindex nnml-prepare-save-mail-hook -Hook run narrowed to an article before saving. - -@item nnml-use-compressed-files -@vindex nnml-use-compressed-files -If non-@code{nil}, @code{nnml} will allow using compressed message -files. This requires @code{auto-compression-mode} to be enabled -(@pxref{Compressed Files, ,Compressed Files, emacs, The Emacs Manual}). -If the value of @code{nnml-use-compressed-files} is a string, it is used -as the file extension specifying the compression program. You can set it -to @samp{.bz2} if your Emacs supports it. A value of @code{t} is -equivalent to @samp{.gz}. - -@item nnml-compressed-files-size-threshold -@vindex nnml-compressed-files-size-threshold -Default size threshold for compressed message files. Message files with -bodies larger than that many characters will be automatically compressed -if @code{nnml-use-compressed-files} is non-@code{nil}. - -@end table - -@findex nnml-generate-nov-databases -If your @code{nnml} groups and @acronym{NOV} files get totally out of -whack, you can do a complete update by typing @kbd{M-x -nnml-generate-nov-databases}. This command will trawl through the -entire @code{nnml} hierarchy, looking at each and every article, so it -might take a while to complete. A better interface to this -functionality can be found in the server buffer (@pxref{Server -Commands}). - - -@node MH Spool -@subsubsection MH Spool -@cindex nnmh -@cindex mh-e mail spool - -@code{nnmh} is just like @code{nnml}, except that is doesn't generate -@acronym{NOV} databases and it doesn't keep an active file or marks -file. This makes @code{nnmh} a @emph{much} slower back end than -@code{nnml}, but it also makes it easier to write procmail scripts -for. - -Virtual server settings: - -@table @code -@item nnmh-directory -@vindex nnmh-directory -All @code{nnmh} directories will be located under this directory. The -default is the value of @code{message-directory} (whose default is -@file{~/Mail}) - -@item nnmh-get-new-mail -@vindex nnmh-get-new-mail -If non-@code{nil}, @code{nnmh} will read incoming mail. The default is -@code{t}. - -@item nnmh-be-safe -@vindex nnmh-be-safe -If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make -sure that the articles in the folder are actually what Gnus thinks -they are. It will check date stamps and stat everything in sight, so -setting this to @code{t} will mean a serious slow-down. If you never -use anything but Gnus to read the @code{nnmh} articles, you do not -have to set this variable to @code{t}. The default is @code{nil}. -@end table - - -@node Maildir -@subsubsection Maildir -@cindex nnmaildir -@cindex maildir - -@code{nnmaildir} stores mail in the maildir format, with each maildir -corresponding to a group in Gnus. This format is documented here: -@uref{http://cr.yp.to/proto/maildir.html} and here: -@uref{http://www.qmail.org/man/man5/maildir.html}. @code{nnmaildir} -also stores extra information in the @file{.nnmaildir/} directory -within a maildir. - -Maildir format was designed to allow concurrent deliveries and -reading, without needing locks. With other back ends, you would have -your mail delivered to a spool of some kind, and then you would -configure Gnus to split mail from that spool into your groups. You -can still do that with @code{nnmaildir}, but the more common -configuration is to have your mail delivered directly to the maildirs -that appear as group in Gnus. - -@code{nnmaildir} is designed to be perfectly reliable: @kbd{C-g} will -never corrupt its data in memory, and @code{SIGKILL} will never -corrupt its data in the filesystem. - -@code{nnmaildir} stores article marks and @acronym{NOV} data in each -maildir. So you can copy a whole maildir from one Gnus setup to -another, and you will keep your marks. - -Virtual server settings: - -@table @code -@item directory -For each of your @code{nnmaildir} servers (it's very unlikely that -you'd need more than one), you need to create a directory and populate -it with maildirs or symlinks to maildirs (and nothing else; do not -choose a directory already used for other purposes). Each maildir -will be represented in Gnus as a newsgroup on that server; the -filename of the symlink will be the name of the group. Any filenames -in the directory starting with @samp{.} are ignored. The directory is -scanned when you first start Gnus, and each time you type @kbd{g} in -the group buffer; if any maildirs have been removed or added, -@code{nnmaildir} notices at these times. - -The value of the @code{directory} parameter should be a Lisp form -which is processed by @code{eval} and @code{expand-file-name} to get -the path of the directory for this server. The form is @code{eval}ed -only when the server is opened; the resulting string is used until the -server is closed. (If you don't know about forms and @code{eval}, -don't worry---a simple string will work.) This parameter is not -optional; you must specify it. I don't recommend using -@code{"~/Mail"} or a subdirectory of it; several other parts of Gnus -use that directory by default for various things, and may get confused -if @code{nnmaildir} uses it too. @code{"~/.nnmaildir"} is a typical -value. - -@item target-prefix -This should be a Lisp form which is processed by @code{eval} and -@code{expand-file-name}. The form is @code{eval}ed only when the -server is opened; the resulting string is used until the server is -closed. - -When you create a group on an @code{nnmaildir} server, the maildir is -created with @code{target-prefix} prepended to its name, and a symlink -pointing to that maildir is created, named with the plain group name. -So if @code{directory} is @code{"~/.nnmaildir"} and -@code{target-prefix} is @code{"../maildirs/"}, then when you create -the group @code{foo}, @code{nnmaildir} will create -@file{~/.nnmaildir/../maildirs/foo} as a maildir, and will create -@file{~/.nnmaildir/foo} as a symlink pointing to -@file{../maildirs/foo}. - -You can set @code{target-prefix} to a string without any slashes to -create both maildirs and symlinks in the same @code{directory}; in -this case, any maildirs found in @code{directory} whose names start -with @code{target-prefix} will not be listed as groups (but the -symlinks pointing to them will be). - -As a special case, if @code{target-prefix} is @code{""} (the default), -then when you create a group, the maildir will be created in -@code{directory} without a corresponding symlink. Beware that you -cannot use @code{gnus-group-delete-group} on such groups without the -@code{force} argument. - -@item directory-files -This should be a function with the same interface as -@code{directory-files} (such as @code{directory-files} itself). It is -used to scan the server's @code{directory} for maildirs. This -parameter is optional; the default is -@code{nnheader-directory-files-safe} if -@code{nnheader-directory-files-is-safe} is @code{nil}, and -@code{directory-files} otherwise. -(@code{nnheader-directory-files-is-safe} is checked only once when the -server is opened; if you want to check it each time the directory is -scanned, you'll have to provide your own function that does that.) - -@item get-new-mail -If non-@code{nil}, then after scanning for new mail in the group -maildirs themselves as usual, this server will also incorporate mail -the conventional Gnus way, from @code{mail-sources} according to -@code{nnmail-split-methods} or @code{nnmail-split-fancy}. The default -value is @code{nil}. - -Do @emph{not} use the same maildir both in @code{mail-sources} and as -an @code{nnmaildir} group. The results might happen to be useful, but -that would be by chance, not by design, and the results might be -different in the future. If your split rules create new groups, -remember to supply a @code{create-directory} server parameter. -@end table - -@node nnmaildir Group Parameters -@subsubsection Group parameters - -@code{nnmaildir} uses several group parameters. It's safe to ignore -all this; the default behavior for @code{nnmaildir} is the same as the -default behavior for other mail back ends: articles are deleted after -one week, etc. Except for the expiry parameters, all this -functionality is unique to @code{nnmaildir}, so you can ignore it if -you're just trying to duplicate the behavior you already have with -another back end. - -If the value of any of these parameters is a vector, the first element -is evaluated as a Lisp form and the result is used, rather than the -original value. If the value is not a vector, the value itself is -evaluated as a Lisp form. (This is why these parameters use names -different from those of other, similar parameters supported by other -back ends: they have different, though similar, meanings.) (For -numbers, strings, @code{nil}, and @code{t}, you can ignore the -@code{eval} business again; for other values, remember to use an extra -quote and wrap the value in a vector when appropriate.) - -@table @code -@item expire-age -An integer specifying the minimum age, in seconds, of an article -before it will be expired, or the symbol @code{never} to specify that -articles should never be expired. If this parameter is not set, -@code{nnmaildir} falls back to the usual -@code{nnmail-expiry-wait}(@code{-function}) variables (the -@code{expiry-wait} group parameter overrides @code{nnmail-expiry-wait} -and makes @code{nnmail-expiry-wait-function} ineffective). If you -wanted a value of 3 days, you could use something like @code{[(* 3 24 -60 60)]}; @code{nnmaildir} will evaluate the form and use the result. -An article's age is measured starting from the article file's -modification time. Normally, this is the same as the article's -delivery time, but editing an article makes it younger. Moving an -article (other than via expiry) may also make an article younger. - -@item expire-group -If this is set to a string such as a full Gnus group name, like -@example -"backend+server.address.string:group.name" -@end example -and if it is not the name of the same group that the parameter belongs -to, then articles will be moved to the specified group during expiry -before being deleted. @emph{If this is set to an @code{nnmaildir} -group, the article will be just as old in the destination group as it -was in the source group.} So be careful with @code{expire-age} in the -destination group. If this is set to the name of the same group that -the parameter belongs to, then the article is not expired at all. If -you use the vector form, the first element is evaluated once for each -article. So that form can refer to -@code{nnmaildir-article-file-name}, etc., to decide where to put the -article. @emph{Even if this parameter is not set, @code{nnmaildir} -does not fall back to the @code{expiry-target} group parameter or the -@code{nnmail-expiry-target} variable.} - -@item read-only -If this is set to @code{t}, @code{nnmaildir} will treat the articles -in this maildir as read-only. This means: articles are not renamed -from @file{new/} into @file{cur/}; articles are only found in -@file{new/}, not @file{cur/}; articles are never deleted; articles -cannot be edited. @file{new/} is expected to be a symlink to the -@file{new/} directory of another maildir---e.g., a system-wide mailbox -containing a mailing list of common interest. Everything in the -maildir outside @file{new/} is @emph{not} treated as read-only, so for -a shared mailbox, you do still need to set up your own maildir (or -have write permission to the shared mailbox); your maildir just won't -contain extra copies of the articles. - -@item directory-files -A function with the same interface as @code{directory-files}. It is -used to scan the directories in the maildir corresponding to this -group to find articles. The default is the function specified by the -server's @code{directory-files} parameter. - -@item distrust-Lines: -If non-@code{nil}, @code{nnmaildir} will always count the lines of an -article, rather than use the @code{Lines:} header field. If -@code{nil}, the header field will be used if present. - -@item always-marks -A list of mark symbols, such as @code{['(read expire)]}. Whenever -Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will -say that all articles have these marks, regardless of whether the -marks stored in the filesystem say so. This is a proof-of-concept -feature that will probably be removed eventually; it ought to be done -in Gnus proper, or abandoned if it's not worthwhile. - -@item never-marks -A list of mark symbols, such as @code{['(tick expire)]}. Whenever -Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will -say that no articles have these marks, regardless of whether the marks -stored in the filesystem say so. @code{never-marks} overrides -@code{always-marks}. This is a proof-of-concept feature that will -probably be removed eventually; it ought to be done in Gnus proper, or -abandoned if it's not worthwhile. - -@item nov-cache-size -An integer specifying the size of the @acronym{NOV} memory cache. To -speed things up, @code{nnmaildir} keeps @acronym{NOV} data in memory -for a limited number of articles in each group. (This is probably not -worthwhile, and will probably be removed in the future.) This -parameter's value is noticed only the first time a group is seen after -the server is opened---i.e., when you first start Gnus, typically. -The @acronym{NOV} cache is never resized until the server is closed -and reopened. The default is an estimate of the number of articles -that would be displayed in the summary buffer: a count of articles -that are either marked with @code{tick} or not marked with -@code{read}, plus a little extra. -@end table - -@node Article Identification -@subsubsection Article identification -Articles are stored in the @file{cur/} subdirectory of each maildir. -Each article file is named like @code{uniq:info}, where @code{uniq} -contains no colons. @code{nnmaildir} ignores, but preserves, the -@code{:info} part. (Other maildir readers typically use this part of -the filename to store marks.) The @code{uniq} part uniquely -identifies the article, and is used in various places in the -@file{.nnmaildir/} subdirectory of the maildir to store information -about the corresponding article. The full pathname of an article is -available in the variable @code{nnmaildir-article-file-name} after you -request the article in the summary buffer. - -@node NOV Data -@subsubsection NOV data -An article identified by @code{uniq} has its @acronym{NOV} data (used -to generate lines in the summary buffer) stored in -@code{.nnmaildir/nov/uniq}. There is no -@code{nnmaildir-generate-nov-databases} function. (There isn't much -need for it---an article's @acronym{NOV} data is updated automatically -when the article or @code{nnmail-extra-headers} has changed.) You can -force @code{nnmaildir} to regenerate the @acronym{NOV} data for a -single article simply by deleting the corresponding @acronym{NOV} -file, but @emph{beware}: this will also cause @code{nnmaildir} to -assign a new article number for this article, which may cause trouble -with @code{seen} marks, the Agent, and the cache. - -@node Article Marks -@subsubsection Article marks -An article identified by @code{uniq} is considered to have the mark -@code{flag} when the file @file{.nnmaildir/marks/flag/uniq} exists. -When Gnus asks @code{nnmaildir} for a group's marks, @code{nnmaildir} -looks for such files and reports the set of marks it finds. When Gnus -asks @code{nnmaildir} to store a new set of marks, @code{nnmaildir} -creates and deletes the corresponding files as needed. (Actually, -rather than create a new file for each mark, it just creates hard -links to @file{.nnmaildir/markfile}, to save inodes.) - -You can invent new marks by creating a new directory in -@file{.nnmaildir/marks/}. You can tar up a maildir and remove it from -your server, untar it later, and keep your marks. You can add and -remove marks yourself by creating and deleting mark files. If you do -this while Gnus is running and your @code{nnmaildir} server is open, -it's best to exit all summary buffers for @code{nnmaildir} groups and -type @kbd{s} in the group buffer first, and to type @kbd{g} or -@kbd{M-g} in the group buffer afterwards. Otherwise, Gnus might not -pick up the changes, and might undo them. - - -@node Mail Folders -@subsubsection Mail Folders -@cindex nnfolder -@cindex mbox folders -@cindex mail folders - -@code{nnfolder} is a back end for storing each mail group in a -separate file. Each file is in the standard Un*x mbox format. -@code{nnfolder} will add extra headers to keep track of article -numbers and arrival dates. - -Virtual server settings: - -@table @code -@item nnfolder-directory -@vindex nnfolder-directory -All the @code{nnfolder} mail boxes will be stored under this -directory. The default is the value of @code{message-directory} -(whose default is @file{~/Mail}) - -@item nnfolder-active-file -@vindex nnfolder-active-file -The name of the active file. The default is @file{~/Mail/active}. - -@item nnfolder-newsgroups-file -@vindex nnfolder-newsgroups-file -The name of the group descriptions file. @xref{Newsgroups File -Format}. The default is @file{~/Mail/newsgroups} - -@item nnfolder-get-new-mail -@vindex nnfolder-get-new-mail -If non-@code{nil}, @code{nnfolder} will read incoming mail. The -default is @code{t} - -@item nnfolder-save-buffer-hook -@vindex nnfolder-save-buffer-hook -@cindex backup files -Hook run before saving the folders. Note that Emacs does the normal -backup renaming of files even with the @code{nnfolder} buffers. If -you wish to switch this off, you could say something like the -following in your @file{.emacs} file: - -@lisp -(defun turn-off-backup () - (set (make-local-variable 'backup-inhibited) t)) - -(add-hook 'nnfolder-save-buffer-hook 'turn-off-backup) -@end lisp - -@item nnfolder-delete-mail-hook -@vindex nnfolder-delete-mail-hook -Hook run in a buffer narrowed to the message that is to be deleted. -This function can be used to copy the message to somewhere else, or to -extract some information from it before removing it. - -@item nnfolder-nov-is-evil -@vindex nnfolder-nov-is-evil -If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The -default is @code{nil}. - -@item nnfolder-nov-file-suffix -@vindex nnfolder-nov-file-suffix -The extension for @acronym{NOV} files. The default is @file{.nov}. - -@item nnfolder-nov-directory -@vindex nnfolder-nov-directory -The directory where the @acronym{NOV} files should be stored. If -@code{nil}, @code{nnfolder-directory} is used. - -@end table - - -@findex nnfolder-generate-active-file -@kindex M-x nnfolder-generate-active-file -If you have lots of @code{nnfolder}-like files you'd like to read with -@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file} -command to make @code{nnfolder} aware of all likely files in -@code{nnfolder-directory}. This only works if you use long file names, -though. - -@node Comparing Mail Back Ends -@subsubsection Comparing Mail Back Ends - -First, just for terminology, the @dfn{back end} is the common word for a -low-level access method---a transport, if you will, by which something -is acquired. The sense is that one's mail has to come from somewhere, -and so selection of a suitable back end is required in order to get that -mail within spitting distance of Gnus. - -The same concept exists for Usenet itself: Though access to articles is -typically done by @acronym{NNTP} these days, once upon a midnight dreary, everyone -in the world got at Usenet by running a reader on the machine where the -articles lay (the machine which today we call an @acronym{NNTP} server), and -access was by the reader stepping into the articles' directory spool -area directly. One can still select between either the @code{nntp} or -@code{nnspool} back ends, to select between these methods, if one happens -actually to live on the server (or can see its spool directly, anyway, -via NFS). - -The goal in selecting a mail back end is to pick one which -simultaneously represents a suitable way of dealing with the original -format plus leaving mail in a form that is convenient to use in the -future. Here are some high and low points on each: - -@table @code -@item nnmbox - -UNIX systems have historically had a single, very common, and well-defined -format. All messages arrive in a single @dfn{spool file}, and -they are delineated by a line whose regular expression matches -@samp{^From_}. (My notational use of @samp{_} is to indicate a space, -to make it clear in this instance that this is not the RFC-specified -@samp{From:} header.) Because Emacs and therefore Gnus emanate -historically from the Unix environment, it is simplest if one does not -mess a great deal with the original mailbox format, so if one chooses -this back end, Gnus' primary activity in getting mail from the real spool -area to Gnus' preferred directory is simply to copy it, with no -(appreciable) format change in the process. It is the ``dumbest'' way -to move mail into availability in the Gnus environment. This makes it -fast to move into place, but slow to parse, when Gnus has to look at -what's where. - -@item nnbabyl - -Once upon a time, there was the DEC-10 and DEC-20, running operating -systems called TOPS and related things, and the usual (only?) mail -reading environment was a thing called Babyl. I don't know what format -was used for mail landing on the system, but Babyl had its own internal -format to which mail was converted, primarily involving creating a -spool-file-like entity with a scheme for inserting Babyl-specific -headers and status bits above the top of each message in the file. -Rmail was Emacs's first mail reader, it was written by Richard Stallman, -and Stallman came out of that TOPS/Babyl environment, so he wrote Rmail -to understand the mail files folks already had in existence. Gnus (and -VM, for that matter) continue to support this format because it's -perceived as having some good qualities in those mailer-specific -headers/status bits stuff. Rmail itself still exists as well, of -course, and is still maintained within Emacs. Since Emacs 23, it -uses standard mbox format rather than Babyl. - -Both of the above forms leave your mail in a single file on your -file system, and they must parse that entire file each time you take a -look at your mail. - -@item nnml - -@code{nnml} is the back end which smells the most as though you were -actually operating with an @code{nnspool}-accessed Usenet system. (In -fact, I believe @code{nnml} actually derived from @code{nnspool} code, -lo these years ago.) One's mail is taken from the original spool file, -and is then cut up into individual message files, 1:1. It maintains a -Usenet-style active file (analogous to what one finds in an INN- or -CNews-based news system in (for instance) @file{/var/lib/news/active}, -or what is returned via the @samp{NNTP LIST} verb) and also creates -@dfn{overview} files for efficient group entry, as has been defined for -@acronym{NNTP} servers for some years now. It is slower in mail-splitting, -due to the creation of lots of files, updates to the @code{nnml} active -file, and additions to overview files on a per-message basis, but it is -extremely fast on access because of what amounts to the indexing support -provided by the active file and overviews. - -@code{nnml} costs @dfn{inodes} in a big way; that is, it soaks up the -resource which defines available places in the file system to put new -files. Sysadmins take a dim view of heavy inode occupation within -tight, shared file systems. But if you live on a personal machine where -the file system is your own and space is not at a premium, @code{nnml} -wins big. - -It is also problematic using this back end if you are living in a -FAT16-based Windows world, since much space will be wasted on all these -tiny files. - -@item nnmh - -The Rand MH mail-reading system has been around UNIX systems for a very -long time; it operates by splitting one's spool file of messages into -individual files, but with little or no indexing support---@code{nnmh} -is considered to be semantically equivalent to ``@code{nnml} without -active file or overviews''. This is arguably the worst choice, because -one gets the slowness of individual file creation married to the -slowness of access parsing when learning what's new in one's groups. - -@item nnfolder - -Basically the effect of @code{nnfolder} is @code{nnmbox} (the first -method described above) on a per-group basis. That is, @code{nnmbox} -itself puts @emph{all} one's mail in one file; @code{nnfolder} provides a -little bit of optimization to this so that each of one's mail groups has -a Unix mail box file. It's faster than @code{nnmbox} because each group -can be parsed separately, and still provides the simple Unix mail box -format requiring minimal effort in moving the mail around. In addition, -it maintains an ``active'' file making it much faster for Gnus to figure -out how many messages there are in each separate group. - -If you have groups that are expected to have a massive amount of -messages, @code{nnfolder} is not the best choice, but if you receive -only a moderate amount of mail, @code{nnfolder} is probably the most -friendly mail back end all over. - -@item nnmaildir - -For configuring expiry and other things, @code{nnmaildir} uses -incompatible group parameters, slightly different from those of other -mail back ends. - -@code{nnmaildir} is largely similar to @code{nnml}, with some notable -differences. Each message is stored in a separate file, but the -filename is unrelated to the article number in Gnus. @code{nnmaildir} -also stores the equivalent of @code{nnml}'s overview files in one file -per article, so it uses about twice as many inodes as @code{nnml}. -(Use @code{df -i} to see how plentiful your inode supply is.) If this -slows you down or takes up very much space, a non-block-structured -file system. - -Since maildirs don't require locking for delivery, the maildirs you use -as groups can also be the maildirs your mail is directly delivered to. -This means you can skip Gnus' mail splitting if your mail is already -organized into different mailboxes during delivery. A @code{directory} -entry in @code{mail-sources} would have a similar effect, but would -require one set of mailboxes for spooling deliveries (in mbox format, -thus damaging message bodies), and another set to be used as groups (in -whatever format you like). A maildir has a built-in spool, in the -@code{new/} subdirectory. Beware that currently, mail moved from -@code{new/} to @code{cur/} instead of via mail splitting will not -undergo treatment such as duplicate checking. - -@code{nnmaildir} stores article marks for a given group in the -corresponding maildir, in a way designed so that it's easy to manipulate -them from outside Gnus. You can tar up a maildir, unpack it somewhere -else, and still have your marks. - -@code{nnmaildir} uses a significant amount of memory to speed things up. -(It keeps in memory some of the things that @code{nnml} stores in files -and that @code{nnmh} repeatedly parses out of message files.) If this -is a problem for you, you can set the @code{nov-cache-size} group -parameter to something small (0 would probably not work, but 1 probably -would) to make it use less memory. This caching will probably be -removed in the future. - -Startup is likely to be slower with @code{nnmaildir} than with other -back ends. Everything else is likely to be faster, depending in part -on your file system. - -@code{nnmaildir} does not use @code{nnoo}, so you cannot use @code{nnoo} -to write an @code{nnmaildir}-derived back end. - -@end table - - -@node Browsing the Web -@section Browsing the Web -@cindex web -@cindex browsing the web -@cindex www -@cindex http - -Web-based discussion forums are getting more and more popular. On many -subjects, the web-based forums have become the most important forums, -eclipsing the importance of mailing lists and news groups. The reason -is easy to understand---they are friendly to new users; you just point -and click, and there's the discussion. With mailing lists, you have to -go through a cumbersome subscription procedure, and most people don't -even know what a news group is. - -The problem with this scenario is that web browsers are not very good at -being newsreaders. They do not keep track of what articles you've read; -they do not allow you to score on subjects you're interested in; they do -not allow off-line browsing; they require you to click around and drive -you mad in the end. - -So---if web browsers suck at reading discussion forums, why not use Gnus -to do it instead? - -Gnus has been getting a bit of a collection of back ends for providing -interfaces to these sources. - -@menu -* Archiving Mail:: -* Web Searches:: Creating groups from articles that match a string. -* RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. -@end menu - -All the web sources require Emacs/W3 and the url library or those -alternatives to work. - -The main caveat with all these web sources is that they probably won't -work for a very long time. Gleaning information from the @acronym{HTML} data -is guesswork at best, and when the layout is altered, the Gnus back end -will fail. If you have reasonably new versions of these back ends, -though, you should be ok. - -One thing all these Web methods have in common is that the Web sources -are often down, unavailable or just plain too slow to be fun. In those -cases, it makes a lot of sense to let the Gnus Agent (@pxref{Gnus -Unplugged}) handle downloading articles, and then you can read them at -leisure from your local disk. No more World Wide Wait for you. - -@node Archiving Mail -@subsection Archiving Mail -@cindex archiving mail -@cindex backup of mail - -Some of the back ends, notably @code{nnml}, @code{nnfolder}, and -@code{nnmaildir}, now actually store the article marks with each group. -For these servers, archiving and restoring a group while preserving -marks is fairly simple. - -(Preserving the group level and group parameters as well still -requires ritual dancing and sacrifices to the @file{.newsrc.eld} deity -though.) - -To archive an entire @code{nnml}, @code{nnfolder}, or @code{nnmaildir} -server, take a recursive copy of the server directory. There is no need -to shut down Gnus, so archiving may be invoked by @code{cron} or -similar. You restore the data by restoring the directory tree, and -adding a server definition pointing to that directory in Gnus. The -@ref{Article Backlog}, @ref{Asynchronous Fetching} and other things -might interfere with overwriting data, so you may want to shut down Gnus -before you restore the data. - -@node Web Searches -@subsection Web Searches -@cindex nnweb -@cindex Google -@cindex dejanews -@cindex gmane -@cindex Usenet searches -@cindex searching the Usenet - -It's, like, too neat to search the Usenet for articles that match a -string, but it, like, totally @emph{sucks}, like, totally, to use one of -those, like, Web browsers, and you, like, have to, rilly, like, look at -the commercials, so, like, with Gnus you can do @emph{rad}, rilly, -searches without having to use a browser. - -The @code{nnweb} back end allows an easy interface to the mighty search -engine. You create an @code{nnweb} group, enter a search pattern, and -then enter the group and read the articles like you would any normal -group. The @kbd{G w} command in the group buffer (@pxref{Foreign -Groups}) will do this in an easy-to-use fashion. - -@code{nnweb} groups don't really lend themselves to being solid -groups---they have a very fleeting idea of article numbers. In fact, -each time you enter an @code{nnweb} group (not even changing the search -pattern), you are likely to get the articles ordered in a different -manner. Not even using duplicate suppression (@pxref{Duplicate -Suppression}) will help, since @code{nnweb} doesn't even know the -@code{Message-ID} of the articles before reading them using some search -engines (Google, for instance). The only possible way to keep track -of which articles you've read is by scoring on the @code{Date} -header---mark all articles posted before the last date you read the -group as read. - -If the search engine changes its output substantially, @code{nnweb} -won't be able to parse it and will fail. One could hardly fault the Web -providers if they were to do this---their @emph{raison d'@^etre} is to -make money off of advertisements, not to provide services to the -community. Since @code{nnweb} washes the ads off all the articles, one -might think that the providers might be somewhat miffed. We'll see. - -You must have the @code{url} and @code{W3} package or those alternatives -(try @code{customize-group} on the @samp{mm-url} variable group) -installed to be able to use @code{nnweb}. - -Virtual server variables: - -@table @code -@item nnweb-type -@vindex nnweb-type -What search engine type is being used. The currently supported types -are @code{google}, @code{dejanews}, and @code{gmane}. Note that -@code{dejanews} is an alias to @code{google}. - -@item nnweb-search -@vindex nnweb-search -The search string to feed to the search engine. - -@item nnweb-max-hits -@vindex nnweb-max-hits -Advisory maximum number of hits per search to display. The default is -999. - -@item nnweb-type-definition -@vindex nnweb-type-definition -Type-to-definition alist. This alist says what @code{nnweb} should do -with the various search engine types. The following elements must be -present: - -@table @code -@item article -Function to decode the article and provide something that Gnus -understands. - -@item map -Function to create an article number to message header and URL alist. - -@item search -Function to send the search string to the search engine. - -@item address -The address the aforementioned function should send the search string -to. - -@item id -Format string URL to fetch an article by @code{Message-ID}. -@end table - -@end table - - -@node RSS -@subsection RSS -@cindex nnrss -@cindex RSS - -Some web sites have an RDF Site Summary (@acronym{RSS}). -@acronym{RSS} is a format for summarizing headlines from news related -sites (such as BBC or CNN). But basically anything list-like can be -presented as an @acronym{RSS} feed: weblogs, changelogs or recent -changes to a wiki (e.g., @url{http://cliki.net/site/recent-changes}). - -@acronym{RSS} has a quite regular and nice interface, and it's -possible to get the information Gnus needs to keep groups updated. - -Note: you had better use Emacs which supports the @code{utf-8} coding -system because @acronym{RSS} uses UTF-8 for encoding non-@acronym{ASCII} -text by default. It is also used by default for non-@acronym{ASCII} -group names. - -@kindex G R (Group) -Use @kbd{G R} from the group buffer to subscribe to a feed---you will be -prompted for the location, the title and the description of the feed. -The title, which allows any characters, will be used for the group name -and the name of the group data file. The description can be omitted. - -An easy way to get started with @code{nnrss} is to say something like -the following in the group buffer: @kbd{B nnrss RET RET y}, then -subscribe to groups. - -The @code{nnrss} back end saves the group data file in -@code{nnrss-directory} (see below) for each @code{nnrss} group. File -names containing non-@acronym{ASCII} characters will be encoded by the -coding system specified with the @code{nnmail-pathname-coding-system} -variable or other. Also @xref{Non-ASCII Group Names}, for more -information. - -The @code{nnrss} back end generates @samp{multipart/alternative} -@acronym{MIME} articles in which each contains a @samp{text/plain} part -and a @samp{text/html} part. - -@cindex OPML -You can also use the following commands to import and export your -subscriptions from a file in @acronym{OPML} format (Outline Processor -Markup Language). - -@defun nnrss-opml-import file -Prompt for an @acronym{OPML} file, and subscribe to each feed in the -file. -@end defun - -@defun nnrss-opml-export -Write your current @acronym{RSS} subscriptions to a buffer in -@acronym{OPML} format. -@end defun - -The following @code{nnrss} variables can be altered: - -@table @code -@item nnrss-directory -@vindex nnrss-directory -The directory where @code{nnrss} stores its files. The default is -@file{~/News/rss/}. - -@item nnrss-file-coding-system -@vindex nnrss-file-coding-system -The coding system used when reading and writing the @code{nnrss} groups -data files. The default is the value of -@code{mm-universal-coding-system} (which defaults to @code{emacs-mule} -in Emacs or @code{escape-quoted} in XEmacs). - -@item nnrss-ignore-article-fields -@vindex nnrss-ignore-article-fields -Some feeds update constantly article fields during their publications, -e.g., to indicate the number of comments. However, if there is -a difference between the local article and the distant one, the latter -is considered to be new. To avoid this and discard some fields, set this -variable to the list of fields to be ignored. The default is -@code{'(slash:comments)}. - -@item nnrss-use-local -@vindex nnrss-use-local -@findex nnrss-generate-download-script -If you set @code{nnrss-use-local} to @code{t}, @code{nnrss} will read -the feeds from local files in @code{nnrss-directory}. You can use -the command @code{nnrss-generate-download-script} to generate a -download script using @command{wget}. -@end table - -The following code may be helpful, if you want to show the description in -the summary buffer. - -@lisp -(add-to-list 'nnmail-extra-headers nnrss-description-field) -(setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-15,15f%]%) %s%uX\n") - -(defun gnus-user-format-function-X (header) - (let ((descr - (assq nnrss-description-field (mail-header-extra header)))) - (if descr (concat "\n\t" (cdr descr)) ""))) -@end lisp - -The following code may be useful to open an nnrss url directly from the -summary buffer. - -@lisp -(require 'browse-url) - -(defun browse-nnrss-url (arg) - (interactive "p") - (let ((url (assq nnrss-url-field - (mail-header-extra - (gnus-data-header - (assq (gnus-summary-article-number) - gnus-newsgroup-data)))))) - (if url - (progn - (browse-url (cdr url)) - (gnus-summary-mark-as-read-forward 1)) - (gnus-summary-scroll-up arg)))) - -(eval-after-load "gnus" - #'(define-key gnus-summary-mode-map - (kbd "") 'browse-nnrss-url)) -(add-to-list 'nnmail-extra-headers nnrss-url-field) -@end lisp - -Even if you have added @samp{text/html} to the -@code{mm-discouraged-alternatives} variable (@pxref{Display -Customization, ,Display Customization, emacs-mime, The Emacs MIME -Manual}) since you don't want to see @acronym{HTML} parts, it might be -more useful especially in @code{nnrss} groups to display -@samp{text/html} parts. Here's an example of setting -@code{mm-discouraged-alternatives} as a group parameter (@pxref{Group -Parameters}) in order to display @samp{text/html} parts only in -@code{nnrss} groups: - -@lisp -;; @r{Set the default value of @code{mm-discouraged-alternatives}.} -(eval-after-load "gnus-sum" - '(add-to-list - 'gnus-newsgroup-variables - '(mm-discouraged-alternatives - . '("text/html" "image/.*")))) - -;; @r{Display @samp{text/html} parts in @code{nnrss} groups.} -(add-to-list - 'gnus-parameters - '("\\`nnrss:" (mm-discouraged-alternatives nil))) -@end lisp - - -@node Customizing W3 -@subsection Customizing W3 -@cindex W3 -@cindex html -@cindex url -@cindex Netscape - -Gnus uses the url library to fetch web pages and Emacs/W3 (or those -alternatives) to display web pages. Emacs/W3 is documented in its own -manual, but there are some things that may be more relevant for Gnus -users. - -For instance, a common question is how to make Emacs/W3 follow links -using the @code{browse-url} functions (which will call some external web -browser like Netscape). Here's one way: - -@lisp -(eval-after-load "w3" - '(progn - (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) - (defun w3-fetch (&optional url target) - (interactive (list (w3-read-url-with-default))) - (if (eq major-mode 'gnus-article-mode) - (browse-url url) - (w3-fetch-orig url target))))) -@end lisp - -Put that in your @file{.emacs} file, and hitting links in W3-rendered -@acronym{HTML} in the Gnus article buffers will use @code{browse-url} to -follow the link. - - -@node Other Sources -@section Other Sources - -Gnus can do more than just read news or mail. The methods described -below allow Gnus to view directories and files as if they were -newsgroups. - -@menu -* Directory Groups:: You can read a directory as if it was a newsgroup. -* Anything Groups:: Dired? Who needs dired? -* Document Groups:: Single files can be the basis of a group. -* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. -* The Empty Backend:: The backend that never has any news. -@end menu - - -@node Directory Groups -@subsection Directory Groups -@cindex nndir -@cindex directory groups - -If you have a directory that has lots of articles in separate files in -it, you might treat it as a newsgroup. The files have to have numerical -names, of course. - -This might be an opportune moment to mention @code{ange-ftp} (and its -successor @code{efs}), that most wonderful of all wonderful Emacs -packages. When I wrote @code{nndir}, I didn't think much about it---a -back end to read directories. Big deal. - -@code{ange-ftp} changes that picture dramatically. For instance, if you -enter the @code{ange-ftp} file name -@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name, -@code{ange-ftp} or @code{efs} will actually allow you to read this -directory over at @samp{sina} as a newsgroup. Distributed news ahoy! - -@code{nndir} will use @acronym{NOV} files if they are present. - -@code{nndir} is a ``read-only'' back end---you can't delete or expire -articles with this method. You can use @code{nnmh} or @code{nnml} for -whatever you use @code{nndir} for, so you could switch to any of those -methods if you feel the need to have a non-read-only @code{nndir}. - - -@node Anything Groups -@subsection Anything Groups -@cindex nneething - -From the @code{nndir} back end (which reads a single spool-like -directory), it's just a hop and a skip to @code{nneething}, which -pretends that any arbitrary directory is a newsgroup. Strange, but -true. - -When @code{nneething} is presented with a directory, it will scan this -directory and assign article numbers to each file. When you enter such -a group, @code{nneething} must create ``headers'' that Gnus can use. -After all, Gnus is a newsreader, in case you're forgetting. -@code{nneething} does this in a two-step process. First, it snoops each -file in question. If the file looks like an article (i.e., the first -few lines look like headers), it will use this as the head. If this is -just some arbitrary file without a head (e.g., a C source file), -@code{nneething} will cobble up a header out of thin air. It will use -file ownership, name and date and do whatever it can with these -elements. - -All this should happen automatically for you, and you will be presented -with something that looks very much like a newsgroup. Totally like a -newsgroup, to be precise. If you select an article, it will be displayed -in the article buffer, just as usual. - -If you select a line that represents a directory, Gnus will pop you into -a new summary buffer for this @code{nneething} group. And so on. You can -traverse the entire disk this way, if you feel like, but remember that -Gnus is not dired, really, and does not intend to be, either. - -There are two overall modes to this action---ephemeral or solid. When -doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus -will not store information on what files you have read, and what files -are new, and so on. If you create a solid @code{nneething} group the -normal way with @kbd{G m}, Gnus will store a mapping table between -article numbers and file names, and you can treat this group like any -other groups. When you activate a solid @code{nneething} group, you will -be told how many unread articles it contains, etc., etc. - -Some variables: - -@table @code -@item nneething-map-file-directory -@vindex nneething-map-file-directory -All the mapping files for solid @code{nneething} groups will be stored -in this directory, which defaults to @file{~/.nneething/}. - -@item nneething-exclude-files -@vindex nneething-exclude-files -All files that match this regexp will be ignored. Nice to use to exclude -auto-save files and the like, which is what it does by default. - -@item nneething-include-files -@vindex nneething-include-files -Regexp saying what files to include in the group. If this variable is -non-@code{nil}, only files matching this regexp will be included. - -@item nneething-map-file -@vindex nneething-map-file -Name of the map files. -@end table - - -@node Document Groups -@subsection Document Groups -@cindex nndoc -@cindex documentation group -@cindex help group - -@code{nndoc} is a cute little thing that will let you read a single file -as a newsgroup. Several files types are supported: - -@table @code -@cindex Babyl -@item babyl -The Babyl format. - -@cindex mbox -@cindex Unix mbox -@item mbox -The standard Unix mbox file. - -@cindex MMDF mail box -@item mmdf -The MMDF mail box format. - -@item news -Several news articles appended into a file. - -@cindex rnews batch files -@item rnews -The rnews batch transport format. - -@item nsmail -Netscape mail boxes. - -@item mime-parts -@acronym{MIME} multipart messages. - -@item standard-digest -The standard (RFC 1153) digest format. - -@item mime-digest -A @acronym{MIME} digest of messages. - -@item lanl-gov-announce -Announcement messages from LANL Gov Announce. - -@cindex git commit messages -@item git -@code{git} commit messages. - -@cindex forwarded messages -@item rfc822-forward -A message forwarded according to RFC822. - -@item outlook -The Outlook mail box. - -@item oe-dbx -The Outlook Express dbx mail box. - -@item exim-bounce -A bounce message from the Exim MTA. - -@item forward -A message forwarded according to informal rules. - -@item rfc934 -An RFC934-forwarded message. - -@item mailman -A mailman digest. - -@item clari-briefs -A digest of Clarinet brief news items. - -@item slack-digest -Non-standard digest format---matches most things, but does it badly. - -@item mail-in-mail -The last resort. -@end table - -You can also use the special ``file type'' @code{guess}, which means -that @code{nndoc} will try to guess what file type it is looking at. -@code{digest} means that @code{nndoc} should guess what digest type the -file is. - -@code{nndoc} will not try to change the file or insert any extra headers into -it---it will simply, like, let you use the file as the basis for a -group. And that's it. - -If you have some old archived articles that you want to insert into your -new & spiffy Gnus mail back end, @code{nndoc} can probably help you with -that. Say you have an old @file{RMAIL} file with mail that you now want -to split into your new @code{nnml} groups. You look at that file using -@code{nndoc} (using the @kbd{G f} command in the group buffer -(@pxref{Foreign Groups})), set the process mark on all the articles in -the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) -using @code{nnml}. If all goes well, all the mail in the @file{RMAIL} -file is now also stored in lots of @code{nnml} directories, and you can -delete that pesky @file{RMAIL} file. If you have the guts! - -Virtual server variables: - -@table @code -@item nndoc-article-type -@vindex nndoc-article-type -This should be one of @code{mbox}, @code{babyl}, @code{digest}, -@code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934}, -@code{rfc822-forward}, @code{mime-parts}, @code{standard-digest}, -@code{slack-digest}, @code{clari-briefs}, @code{nsmail}, @code{outlook}, -@code{oe-dbx}, @code{mailman}, and @code{mail-in-mail} or @code{guess}. - -@item nndoc-post-type -@vindex nndoc-post-type -This variable says whether Gnus is to consider the group a news group or -a mail group. There are two valid values: @code{mail} (the default) -and @code{news}. -@end table - -@menu -* Document Server Internals:: How to add your own document types. -@end menu - - -@node Document Server Internals -@subsubsection Document Server Internals - -Adding new document types to be recognized by @code{nndoc} isn't -difficult. You just have to whip up a definition of what the document -looks like, write a predicate function to recognize that document type, -and then hook into @code{nndoc}. - -First, here's an example document type definition: - -@example -(mmdf - (article-begin . "^\^A\^A\^A\^A\n") - (body-end . "^\^A\^A\^A\^A\n")) -@end example - -The definition is simply a unique @dfn{name} followed by a series of -regexp pseudo-variable settings. Below are the possible -variables---don't be daunted by the number of variables; most document -types can be defined with very few settings: - -@table @code -@item first-article -If present, @code{nndoc} will skip past all text until it finds -something that match this regexp. All text before this will be -totally ignored. - -@item article-begin -This setting has to be present in all document type definitions. It -says what the beginning of each article looks like. To do more -complicated things that cannot be dealt with a simple regexp, you can -use @code{article-begin-function} instead of this. - -@item article-begin-function -If present, this should be a function that moves point to the beginning -of each article. This setting overrides @code{article-begin}. - -@item head-begin -If present, this should be a regexp that matches the head of the -article. To do more complicated things that cannot be dealt with a -simple regexp, you can use @code{head-begin-function} instead of this. - -@item head-begin-function -If present, this should be a function that moves point to the head of -the article. This setting overrides @code{head-begin}. - -@item head-end -This should match the end of the head of the article. It defaults to -@samp{^$}---the empty line. - -@item body-begin -This should match the beginning of the body of the article. It defaults -to @samp{^\n}. To do more complicated things that cannot be dealt with -a simple regexp, you can use @code{body-begin-function} instead of this. - -@item body-begin-function -If present, this function should move point to the beginning of the body -of the article. This setting overrides @code{body-begin}. - -@item body-end -If present, this should match the end of the body of the article. To do -more complicated things that cannot be dealt with a simple regexp, you -can use @code{body-end-function} instead of this. - -@item body-end-function -If present, this function should move point to the end of the body of -the article. This setting overrides @code{body-end}. - -@item file-begin -If present, this should match the beginning of the file. All text -before this regexp will be totally ignored. - -@item file-end -If present, this should match the end of the file. All text after this -regexp will be totally ignored. - -@end table - -So, using these variables @code{nndoc} is able to dissect a document -file into a series of articles, each with a head and a body. However, a -few more variables are needed since not all document types are all that -news-like---variables needed to transform the head or the body into -something that's palatable for Gnus: - -@table @code -@item prepare-body-function -If present, this function will be called when requesting an article. It -will be called with point at the start of the body, and is useful if the -document has encoded some parts of its contents. - -@item article-transform-function -If present, this function is called when requesting an article. It's -meant to be used for more wide-ranging transformation of both head and -body of the article. - -@item generate-head-function -If present, this function is called to generate a head that Gnus can -understand. It is called with the article number as a parameter, and is -expected to generate a nice head for the article in question. It is -called when requesting the headers of all articles. - -@item generate-article-function -If present, this function is called to generate an entire article that -Gnus can understand. It is called with the article number as a -parameter when requesting all articles. - -@item dissection-function -If present, this function is called to dissect a document by itself, -overriding @code{first-article}, @code{article-begin}, -@code{article-begin-function}, @code{head-begin}, -@code{head-begin-function}, @code{head-end}, @code{body-begin}, -@code{body-begin-function}, @code{body-end}, @code{body-end-function}, -@code{file-begin}, and @code{file-end}. - -@end table - -Let's look at the most complicated example I can come up with---standard -digests: - -@example -(standard-digest - (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+")) - (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+")) - (prepare-body-function . nndoc-unquote-dashes) - (body-end-function . nndoc-digest-body-end) - (head-end . "^ ?$") - (body-begin . "^ ?\n") - (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$") - (subtype digest guess)) -@end example - -We see that all text before a 70-width line of dashes is ignored; all -text after a line that starts with that @samp{^End of} is also ignored; -each article begins with a 30-width line of dashes; the line separating -the head from the body may contain a single space; and that the body is -run through @code{nndoc-unquote-dashes} before being delivered. - -To hook your own document definition into @code{nndoc}, use the -@code{nndoc-add-type} function. It takes two parameters---the first -is the definition itself and the second (optional) parameter says -where in the document type definition alist to put this definition. -The alist is traversed sequentially, and -@code{nndoc-@var{type}-type-p} is called for a given type @var{type}. -So @code{nndoc-mmdf-type-p} is called to see whether a document is of -@code{mmdf} type, and so on. These type predicates should return -@code{nil} if the document is not of the correct type; @code{t} if it -is of the correct type; and a number if the document might be of the -correct type. A high number means high probability; a low number -means low probability with @samp{0} being the lowest valid number. - - -@node Mail-To-News Gateways -@subsection Mail-To-News Gateways -@cindex mail-to-news gateways -@cindex gateways - -If your local @code{nntp} server doesn't allow posting, for some reason -or other, you can post using one of the numerous mail-to-news gateways. -The @code{nngateway} back end provides the interface. - -Note that you can't read anything from this back end---it can only be -used to post with. - -Server variables: - -@table @code -@item nngateway-address -@vindex nngateway-address -This is the address of the mail-to-news gateway. - -@item nngateway-header-transformation -@vindex nngateway-header-transformation -News headers often have to be transformed in some odd way or other -for the mail-to-news gateway to accept it. This variable says what -transformation should be called, and defaults to -@code{nngateway-simple-header-transformation}. The function is called -narrowed to the headers to be transformed and with one parameter---the -gateway address. - -This default function just inserts a new @code{To} header based on the -@code{Newsgroups} header and the gateway address. -For instance, an article with this @code{Newsgroups} header: - -@example -Newsgroups: alt.religion.emacs -@end example - -will get this @code{To} header inserted: - -@example -To: alt-religion-emacs@@GATEWAY -@end example - -The following pre-defined functions exist: - -@findex nngateway-simple-header-transformation -@table @code - -@item nngateway-simple-header-transformation -Creates a @code{To} header that looks like -@var{newsgroup}@@@code{nngateway-address}. - -@findex nngateway-mail2news-header-transformation - -@item nngateway-mail2news-header-transformation -Creates a @code{To} header that looks like -@code{nngateway-address}. -@end table - -@end table - -Here's an example: - -@lisp -(setq gnus-post-method - '(nngateway - "mail2news@@replay.com" - (nngateway-header-transformation - nngateway-mail2news-header-transformation))) -@end lisp - -So, to use this, simply say something like: - -@lisp -(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS")) -@end lisp - - -@node The Empty Backend -@subsection The Empty Backend -@cindex nnnil - -@code{nnnil} is a backend that can be used as a placeholder if you -have to specify a backend somewhere, but don't really want to. The -classical example is if you don't want to have a primary select -methods, but want to only use secondary ones: - -@lisp -(setq gnus-select-method '(nnnil "")) -(setq gnus-secondary-select-methods - '((nnimap "foo") - (nnml ""))) -@end lisp - - -@node Combined Groups -@section Combined Groups - -Gnus allows combining a mixture of all the other group types into bigger -groups. - -@menu -* Virtual Groups:: Combining articles from many groups. -@end menu - - -@node Virtual Groups -@subsection Virtual Groups -@cindex nnvirtual -@cindex virtual groups -@cindex merging groups - -An @dfn{nnvirtual group} is really nothing more than a collection of -other groups. - -For instance, if you are tired of reading many small groups, you can -put them all in one big group, and then grow tired of reading one -big, unwieldy group. The joys of computing! - -You specify @code{nnvirtual} as the method. The address should be a -regexp to match component groups. - -All marks in the virtual group will stick to the articles in the -component groups. So if you tick an article in a virtual group, the -article will also be ticked in the component group from whence it -came. (And vice versa---marks from the component groups will also be -shown in the virtual group.). To create an empty virtual group, run -@kbd{G V} (@code{gnus-group-make-empty-virtual}) in the group buffer -and edit the method regexp with @kbd{M-e} -(@code{gnus-group-edit-group-method}) - -Here's an example @code{nnvirtual} method that collects all Andrea Dworkin -newsgroups into one, big, happy newsgroup: - -@lisp -(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*") -@end lisp - -The component groups can be native or foreign; everything should work -smoothly, but if your computer explodes, it was probably my fault. - -Collecting the same group from several servers might actually be a good -idea if users have set the Distribution header to limit distribution. -If you would like to read @samp{soc.motss} both from a server in Japan -and a server in Norway, you could use the following as the group regexp: - -@example -"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$" -@end example - -(Remember, though, that if you're creating the group with @kbd{G m}, you -shouldn't double the backslashes, and you should leave off the quote -characters at the beginning and the end of the string.) - -This should work kinda smoothly---all articles from both groups should -end up in this one, and there should be no duplicates. Threading (and -the rest) will still work as usual, but there might be problems with the -sequence of articles. Sorting on date might be an option here -(@pxref{Selecting a Group}). - -One limitation, however---all groups included in a virtual -group have to be alive (i.e., subscribed or unsubscribed). Killed or -zombie groups can't be component groups for @code{nnvirtual} groups. - -@vindex nnvirtual-always-rescan -If the @code{nnvirtual-always-rescan} variable is non-@code{nil} (which -is the default), @code{nnvirtual} will always scan groups for unread -articles when entering a virtual group. If this variable is @code{nil} -and you read articles in a component group after the virtual group has -been activated, the read articles from the component group will show up -when you enter the virtual group. You'll also see this effect if you -have two virtual groups that have a component group in common. If -that's the case, you should set this variable to @code{t}. Or you can -just tap @code{M-g} on the virtual group every time before you enter -it---it'll have much the same effect. - -@code{nnvirtual} can have both mail and news groups as component groups. -When responding to articles in @code{nnvirtual} groups, @code{nnvirtual} -has to ask the back end of the component group the article comes from -whether it is a news or mail back end. However, when you do a @kbd{^}, -there is typically no sure way for the component back end to know this, -and in that case @code{nnvirtual} tells Gnus that the article came from a -not-news back end. (Just to be on the safe side.) - -@kbd{C-c C-n} in the message buffer will insert the @code{Newsgroups} -line from the article you respond to in these cases. - -@code{nnvirtual} groups do not inherit anything but articles and marks -from component groups---group parameters, for instance, are not -inherited. - - -@node Email Based Diary -@section Email Based Diary -@cindex diary -@cindex email based diary -@cindex calendar - -This section describes a special mail back end called @code{nndiary}, -and its companion library @code{gnus-diary}. It is ``special'' in the -sense that it is not meant to be one of the standard alternatives for -reading mail with Gnus. See @ref{Choosing a Mail Back End} for that. -Instead, it is used to treat @emph{some} of your mails in a special way, -namely, as event reminders. - -Here is a typical scenario: - -@itemize @bullet -@item -You've got a date with Andy Mc Dowell or Bruce Willis (select according -to your sexual preference) in one month. You don't want to forget it. -@item -So you send a ``reminder'' message (actually, a diary one) to yourself. -@item -You forget all about it and keep on getting and reading new mail, as usual. -@item -From time to time, as you type `g' in the group buffer and as the date -is getting closer, the message will pop up again to remind you of your -appointment, just as if it were new and unread. -@item -Read your ``new'' messages, this one included, and start dreaming again -of the night you're gonna have. -@item -Once the date is over (you actually fell asleep just after dinner), the -message will be automatically deleted if it is marked as expirable. -@end itemize - -The Gnus Diary back end has the ability to handle regular appointments -(that wouldn't ever be deleted) as well as punctual ones, operates as a -real mail back end and is configurable in many ways. All of this is -explained in the sections below. - -@menu -* The NNDiary Back End:: Basic setup and usage. -* The Gnus Diary Library:: Utility toolkit on top of nndiary. -* Sending or Not Sending:: A final note on sending diary messages. -@end menu - - -@node The NNDiary Back End -@subsection The NNDiary Back End -@cindex nndiary -@cindex the nndiary back end - -@code{nndiary} is a back end very similar to @code{nnml} (@pxref{Mail -Spool}). Actually, it could appear as a mix of @code{nnml} and -@code{nndraft}. If you know @code{nnml}, you're already familiar with -the message storing scheme of @code{nndiary}: one file per message, one -directory per group. - - Before anything, there is one requirement to be able to run -@code{nndiary} properly: you @emph{must} use the group timestamp feature -of Gnus. This adds a timestamp to each group's parameters. @ref{Group -Timestamp} to see how it's done. - -@menu -* Diary Messages:: What makes a message valid for nndiary. -* Running NNDiary:: NNDiary has two modes of operation. -* Customizing NNDiary:: Bells and whistles. -@end menu - -@node Diary Messages -@subsubsection Diary Messages -@cindex nndiary messages -@cindex nndiary mails - -@code{nndiary} messages are just normal ones, except for the mandatory -presence of 7 special headers. These headers are of the form -@code{X-Diary-}, @code{} being one of -@code{Minute}, @code{Hour}, @code{Dom}, @code{Month}, @code{Year}, -@code{Time-Zone} and @code{Dow}. @code{Dom} means ``Day of Month'', and -@code{dow} means ``Day of Week''. These headers actually behave like -crontab specifications and define the event date(s): - -@itemize @bullet -@item -For all headers except the @code{Time-Zone} one, a header value is -either a star (meaning all possible values), or a list of fields -(separated by a comma). -@item -A field is either an integer, or a range. -@item -A range is two integers separated by a dash. -@item -Possible integer values are 0--59 for @code{Minute}, 0--23 for -@code{Hour}, 1--31 for @code{Dom}, 1--12 for @code{Month}, above 1971 -for @code{Year} and 0--6 for @code{Dow} (0 meaning Sunday). -@item -As a special case, a star in either @code{Dom} or @code{Dow} doesn't -mean ``all possible values'', but ``use only the other field''. Note -that if both are star'ed, the use of either one gives the same result. -@item -The @code{Time-Zone} header is special in that it can only have one -value (@code{GMT}, for instance). A star doesn't mean ``all possible -values'' (because it makes no sense), but ``the current local time -zone''. Most of the time, you'll be using a star here. However, for a -list of available time zone values, see the variable -@code{nndiary-headers}. -@end itemize - -As a concrete example, here are the diary headers to add to your message -for specifying ``Each Monday and each 1st of month, at 12:00, 20:00, -21:00, 22:00, 23:00 and 24:00, from 1999 to 2010'' (I'll let you find -what to do then): - -@example -X-Diary-Minute: 0 -X-Diary-Hour: 12, 20-24 -X-Diary-Dom: 1 -X-Diary-Month: * -X-Diary-Year: 1999-2010 -X-Diary-Dow: 1 -X-Diary-Time-Zone: * -@end example - -@node Running NNDiary -@subsubsection Running NNDiary -@cindex running nndiary -@cindex nndiary operation modes - -@code{nndiary} has two modes of operation: ``traditional'' (the default) -and ``autonomous''. In traditional mode, @code{nndiary} does not get new -mail by itself. You have to move (@kbd{B m}) or copy (@kbd{B c}) mails -from your primary mail back end to nndiary groups in order to handle them -as diary messages. In autonomous mode, @code{nndiary} retrieves its own -mail and handles it independently from your primary mail back end. - -One should note that Gnus is not inherently designed to allow several -``master'' mail back ends at the same time. However, this does make -sense with @code{nndiary}: you really want to send and receive diary -messages to your diary groups directly. So, @code{nndiary} supports -being sort of a ``second primary mail back end'' (to my knowledge, it is -the only back end offering this feature). However, there is a limitation -(which I hope to fix some day): respooling doesn't work in autonomous -mode. - -In order to use @code{nndiary} in autonomous mode, you have several -things to do: - -@itemize @bullet -@item -Allow @code{nndiary} to retrieve new mail by itself. Put the following -line in your @file{~/.gnus.el} file: - -@lisp -(setq nndiary-get-new-mail t) -@end lisp -@item -You must arrange for diary messages (those containing @code{X-Diary-*} -headers) to be split in a private folder @emph{before} Gnus treat them. -Again, this is needed because Gnus cannot (yet ?) properly handle -multiple primary mail back ends. Getting those messages from a separate -source will compensate this misfeature to some extent. - -As an example, here's my procmailrc entry to store diary files in -@file{~/.nndiary} (the default @code{nndiary} mail source file): - -@example -:0 HD : -* ^X-Diary -.nndiary -@end example -@end itemize - -Once this is done, you might want to customize the following two options -that affect the diary mail retrieval and splitting processes: - -@defvar nndiary-mail-sources -This is the diary-specific replacement for the standard -@code{mail-sources} variable. It obeys the same syntax, and defaults to -@code{(file :path "~/.nndiary")}. -@end defvar - -@defvar nndiary-split-methods -This is the diary-specific replacement for the standard -@code{nnmail-split-methods} variable. It obeys the same syntax. -@end defvar - - Finally, you may add a permanent @code{nndiary} virtual server -(something like @code{(nndiary "diary")} should do) to your -@code{gnus-secondary-select-methods}. - - Hopefully, almost everything (see the TODO section in -@file{nndiary.el}) will work as expected when you restart Gnus: in -autonomous mode, typing @kbd{g} and @kbd{M-g} in the group buffer, will -also get your new diary mails and split them according to your -diary-specific rules, @kbd{F} will find your new diary groups etc. - -@node Customizing NNDiary -@subsubsection Customizing NNDiary -@cindex customizing nndiary -@cindex nndiary customization - -Now that @code{nndiary} is up and running, it's time to customize it. -The custom group is called @code{nndiary} (no, really ?!). You should -browse it to figure out which options you'd like to tweak. The following -two variables are probably the only ones you will want to change: - -@defvar nndiary-reminders -This is the list of times when you want to be reminded of your -appointments (e.g., 3 weeks before, then 2 days before, then 1 hour -before and that's it). Remember that ``being reminded'' means that the -diary message will pop up as brand new and unread again when you get new -mail. -@end defvar - -@defvar nndiary-week-starts-on-monday -Rather self-explanatory. Otherwise, Sunday is assumed (this is the -default). -@end defvar - - -@node The Gnus Diary Library -@subsection The Gnus Diary Library -@cindex gnus-diary -@cindex the gnus diary library - -Using @code{nndiary} manually (I mean, writing the headers by hand and -so on) would be rather boring. Fortunately, there is a library called -@code{gnus-diary} written on top of @code{nndiary}, that does many -useful things for you. - - In order to use it, add the following line to your @file{~/.gnus.el} file: - -@lisp -(require 'gnus-diary) -@end lisp - - Also, you shouldn't use any @code{gnus-user-format-function-[d|D]} -(@pxref{Summary Buffer Lines}). @code{gnus-diary} provides both of these -(sorry if you used them before). - - -@menu -* Diary Summary Line Format:: A nicer summary buffer line format. -* Diary Articles Sorting:: A nicer way to sort messages. -* Diary Headers Generation:: Not doing it manually. -* Diary Group Parameters:: Not handling them manually. -@end menu - -@node Diary Summary Line Format -@subsubsection Diary Summary Line Format -@cindex diary summary buffer line -@cindex diary summary line format - -Displaying diary messages in standard summary line format (usually -something like @samp{From Joe: Subject}) is pretty useless. Most of -the time, you're the one who wrote the message, and you mostly want to -see the event's date. - - @code{gnus-diary} provides two supplemental user formats to be used in -summary line formats. @code{D} corresponds to a formatted time string -for the next occurrence of the event (e.g., ``Sat, Sep 22 01, 12:00''), -while @code{d} corresponds to an approximate remaining time until the -next occurrence of the event (e.g., ``in 6 months, 1 week''). - - For example, here's how Joe's birthday is displayed in my -@code{nndiary+diary:birthdays} summary buffer (note that the message is -expirable, but will never be deleted, as it specifies a periodic event): - -@example - E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week) -@end example - -In order to get something like the above, you would normally add the -following line to your diary groups'parameters: - -@lisp -(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n") -@end lisp - -However, @code{gnus-diary} does it automatically (@pxref{Diary Group -Parameters}). You can however customize the provided summary line format -with the following user options: - -@defvar gnus-diary-summary-line-format -Defines the summary line format used for diary groups (@pxref{Summary -Buffer Lines}). @code{gnus-diary} uses it to automatically update the -diary groups'parameters. -@end defvar - -@defvar gnus-diary-time-format -Defines the format to display dates in diary summary buffers. This is -used by the @code{D} user format. See the docstring for details. -@end defvar - -@defvar gnus-diary-delay-format-function -Defines the format function to use for displaying delays (remaining -times) in diary summary buffers. This is used by the @code{d} user -format. There are currently built-in functions for English and French; -you can also define your own. See the docstring for details. -@end defvar - -@node Diary Articles Sorting -@subsubsection Diary Articles Sorting -@cindex diary articles sorting -@cindex diary summary lines sorting -@findex gnus-summary-sort-by-schedule -@findex gnus-thread-sort-by-schedule -@findex gnus-article-sort-by-schedule - -@code{gnus-diary} provides new sorting functions (@pxref{Sorting the -Summary Buffer} ) called @code{gnus-summary-sort-by-schedule}, -@code{gnus-thread-sort-by-schedule} and -@code{gnus-article-sort-by-schedule}. These functions let you organize -your diary summary buffers from the closest event to the farthest one. - -@code{gnus-diary} automatically installs -@code{gnus-summary-sort-by-schedule} as a menu item in the summary -buffer's ``sort'' menu, and the two others as the primary (hence -default) sorting functions in the group parameters (@pxref{Diary Group -Parameters}). - -@node Diary Headers Generation -@subsubsection Diary Headers Generation -@cindex diary headers generation -@findex gnus-diary-check-message - -@code{gnus-diary} provides a function called -@code{gnus-diary-check-message} to help you handle the @code{X-Diary-*} -headers. This function ensures that the current message contains all the -required diary headers, and prompts you for values or corrections if -needed. - - This function is hooked into the @code{nndiary} back end, so that -moving or copying an article to a diary group will trigger it -automatically. It is also bound to @kbd{C-c C-f d} in -@code{message-mode} and @code{article-edit-mode} in order to ease the -process of converting a usual mail to a diary one. - - This function takes a prefix argument which will force prompting of -all diary headers, regardless of their presence or validity. That way, -you can very easily reschedule an already valid diary message, for -instance. - -@node Diary Group Parameters -@subsubsection Diary Group Parameters -@cindex diary group parameters - -When you create a new diary group, or visit one, @code{gnus-diary} -automatically checks your group parameters and if needed, sets the -summary line format to the diary-specific value, installs the -diary-specific sorting functions, and also adds the different -@code{X-Diary-*} headers to the group's posting-style. It is then easier -to send a diary message, because if you use @kbd{C-u a} or @kbd{C-u m} -on a diary group to prepare a message, these headers will be inserted -automatically (although not filled with proper values yet). - -@node Sending or Not Sending -@subsection Sending or Not Sending - -Well, assuming you've read all of the above, here are two final notes on -mail sending with @code{nndiary}: - -@itemize @bullet -@item -@code{nndiary} is a @emph{real} mail back end. You really send real diary -messages for real. This means for instance that you can give -appointments to anybody (provided they use Gnus and @code{nndiary}) by -sending the diary message to them as well. -@item -However, since @code{nndiary} also has a @code{request-post} method, you -can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the -message won't actually be sent; just stored locally in the group. This -comes in very handy for private appointments. -@end itemize - -@node Gnus Unplugged -@section Gnus Unplugged -@cindex offline -@cindex unplugged -@cindex agent -@cindex Gnus agent -@cindex Gnus unplugged - -In olden times (ca. February '88), people used to run their newsreaders -on big machines with permanent connections to the net. News transport -was dealt with by news servers, and all the newsreaders had to do was to -read news. Believe it or not. - -Nowadays most people read news and mail at home, and use some sort of -modem to connect to the net. To avoid running up huge phone bills, it -would be nice to have a way to slurp down all the news and mail, hang up -the phone, read for several hours, and then upload any responses you -have to make. And then you repeat the procedure. - -Of course, you can use news servers for doing this as well. I've used -@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail} -for some years, but doing that's a bore. Moving the news server -functionality up to the newsreader makes sense if you're the only person -reading news on a machine. - -Setting up Gnus as an ``offline'' newsreader is quite simple. In -fact, you don't have to configure anything as the agent is now enabled -by default (@pxref{Agent Variables, gnus-agent}). - -Of course, to use it as such, you have to learn a few new commands. - -@menu -* Agent Basics:: How it all is supposed to work. -* Agent Categories:: How to tell the Gnus Agent what to download. -* Agent Commands:: New commands for all the buffers. -* Agent Visuals:: Ways that the agent may effect your summary buffer. -* Agent as Cache:: The Agent is a big cache too. -* Agent Expiry:: How to make old articles go away. -* Agent Regeneration:: How to recover from lost connections and other accidents. -* Agent and flags:: How the Agent maintains flags. -* Agent and IMAP:: How to use the Agent with @acronym{IMAP}. -* Outgoing Messages:: What happens when you post/mail something? -* Agent Variables:: Customizing is fun. -* Example Setup:: An example @file{~/.gnus.el} file for offline people. -* Batching Agents:: How to fetch news from a @code{cron} job. -* Agent Caveats:: What you think it'll do and what it does. -@end menu - - -@node Agent Basics -@subsection Agent Basics - -First, let's get some terminology out of the way. - -The Gnus Agent is said to be @dfn{unplugged} when you have severed the -connection to the net (and notified the Agent that this is the case). -When the connection to the net is up again (and Gnus knows this), the -Agent is @dfn{plugged}. - -The @dfn{local} machine is the one you're running on, and which isn't -connected to the net continuously. - -@dfn{Downloading} means fetching things from the net to your local -machine. @dfn{Uploading} is doing the opposite. - -You know that Gnus gives you all the opportunity you'd ever want for -shooting yourself in the foot. Some people call it flexibility. Gnus -is also customizable to a great extent, which means that the user has a -say on how Gnus behaves. Other newsreaders might unconditionally shoot -you in your foot, but with Gnus, you have a choice! - -Gnus is never really in plugged or unplugged state. Rather, it applies -that state to each server individually. This means that some servers -can be plugged while others can be unplugged. Additionally, some -servers can be ignored by the Agent altogether (which means that -they're kinda like plugged always). - -So when you unplug the Agent and then wonder why is Gnus opening a -connection to the Net, the next step to do is to look whether all -servers are agentized. If there is an unagentized server, you found -the culprit. - -Another thing is the @dfn{offline} state. Sometimes, servers aren't -reachable. When Gnus notices this, it asks you whether you want the -server to be switched to offline state. If you say yes, then the -server will behave somewhat as if it was unplugged, except that Gnus -will ask you whether you want to switch it back online again. - -Let's take a typical Gnus session using the Agent. - -@itemize @bullet - -@item -@findex gnus-unplugged -You start Gnus with @code{gnus-unplugged}. This brings up the Gnus -Agent in a disconnected state. You can read all the news that you have -already fetched while in this mode. - -@item -You then decide to see whether any new news has arrived. You connect -your machine to the net (using PPP or whatever), and then hit @kbd{J j} -to make Gnus become @dfn{plugged} and use @kbd{g} to check for new mail -as usual. To check for new mail in unplugged mode (@pxref{Mail -Source Specifiers}). - -@item -You can then read the new news immediately, or you can download the -news onto your local machine. If you want to do the latter, you press -@kbd{g} to check if there are any new news and then @kbd{J s} to fetch -all the eligible articles in all the groups. (To let Gnus know which -articles you want to download, @pxref{Agent Categories}). - -@item -After fetching the articles, you press @kbd{J j} to make Gnus become -unplugged again, and you shut down the PPP thing (or whatever). And -then you read the news offline. - -@item -And then you go to step 2. -@end itemize - -Here are some things you should do the first time (or so) that you use -the Agent. - -@itemize @bullet - -@item -Decide which servers should be covered by the Agent. If you have a mail -back end, it would probably be nonsensical to have it covered by the -Agent. Go to the server buffer (@kbd{^} in the group buffer) and press -@kbd{J a} on the server (or servers) that you wish to have covered by the -Agent (@pxref{Server Agent Commands}), or @kbd{J r} on automatically -added servers you do not wish to have covered by the Agent. By default, -no servers are agentized. - -@item -Decide on download policy. It's fairly simple once you decide whether -you are going to use agent categories, topic parameters, and/or group -parameters to implement your policy. If you're new to gnus, it -is probably best to start with a category, @xref{Agent Categories}. - -Both topic parameters (@pxref{Topic Parameters}) and agent categories -(@pxref{Agent Categories}) provide for setting a policy that applies -to multiple groups. Which you use is entirely up to you. Topic -parameters do override categories so, if you mix the two, you'll have -to take that into account. If you have a few groups that deviate from -your policy, you can use group parameters (@pxref{Group Parameters}) to -configure them. - -@item -Uhm@dots{} that's it. -@end itemize - - -@node Agent Categories -@subsection Agent Categories - -One of the main reasons to integrate the news transport layer into the -newsreader is to allow greater control over what articles to download. -There's not much point in downloading huge amounts of articles, just to -find out that you're not interested in reading any of them. It's better -to be somewhat more conservative in choosing what to download, and then -mark the articles for downloading manually if it should turn out that -you're interested in the articles anyway. - -One of the more effective methods for controlling what is to be -downloaded is to create a @dfn{category} and then assign some (or all) -groups to this category. Groups that do not belong in any other -category belong to the @code{default} category. Gnus has its own -buffer for creating and managing categories. - -If you prefer, you can also use group parameters (@pxref{Group -Parameters}) and topic parameters (@pxref{Topic Parameters}) for an -alternative approach to controlling the agent. The only real -difference is that categories are specific to the agent (so there is -less to learn) while group and topic parameters include the kitchen -sink. - -Since you can set agent parameters in several different places we have -a rule to decide which source to believe. This rule specifies that -the parameter sources are checked in the following order: group -parameters, topic parameters, agent category, and finally customizable -variables. So you can mix all of these sources to produce a wide range -of behavior, just don't blame me if you don't remember where you put -your settings. - -@menu -* Category Syntax:: What a category looks like. -* Category Buffer:: A buffer for maintaining categories. -* Category Variables:: Customize'r'Us. -@end menu - - -@node Category Syntax -@subsubsection Category Syntax - -A category consists of a name, the list of groups belonging to the -category, and a number of optional parameters that override the -customizable variables. The complete list of agent parameters are -listed below. - -@cindex Agent Parameters -@table @code -@item agent-groups -The list of groups that are in this category. - -@item agent-predicate -A predicate which (generally) gives a rough outline of which articles -are eligible for downloading; and - -@item agent-score -a score rule which (generally) gives you a finer granularity when -deciding what articles to download. (Note that this @dfn{download -score} is not necessarily related to normal scores.) - -@item agent-enable-expiration -a boolean indicating whether the agent should expire old articles in -this group. Most groups should be expired to conserve disk space. In -fact, its probably safe to say that the gnus.* hierarchy contains the -only groups that should not be expired. - -@item agent-days-until-old -an integer indicating the number of days that the agent should wait -before deciding that a read article is safe to expire. - -@item agent-low-score -an integer that overrides the value of @code{gnus-agent-low-score}. - -@item agent-high-score -an integer that overrides the value of @code{gnus-agent-high-score}. - -@item agent-short-article -an integer that overrides the value of -@code{gnus-agent-short-article}. - -@item agent-long-article -an integer that overrides the value of @code{gnus-agent-long-article}. - -@item agent-enable-undownloaded-faces -a symbol indicating whether the summary buffer should display -undownloaded articles using the @code{gnus-summary-*-undownloaded-face} -faces. Any symbol other than @code{nil} will enable the use of -undownloaded faces. -@end table - -The name of a category can not be changed once the category has been -created. - -Each category maintains a list of groups that are exclusive members of -that category. The exclusivity rule is automatically enforced, add a -group to a new category and it is automatically removed from its old -category. - -A predicate in its simplest form can be a single predicate such as -@code{true} or @code{false}. These two will download every available -article or nothing respectively. In the case of these two special -predicates an additional score rule is superfluous. - -Predicates of @code{high} or @code{low} download articles in respect of -their scores in relationship to @code{gnus-agent-high-score} and -@code{gnus-agent-low-score} as described below. - -To gain even finer control of what is to be regarded eligible for -download a predicate can consist of a number of predicates with logical -operators sprinkled in between. - -Perhaps some examples are in order. - -Here's a simple predicate. (It's the default predicate, in fact, used -for all groups that don't belong to any other category.) - -@lisp -short -@end lisp - -Quite simple, eh? This predicate is true if and only if the article is -short (for some value of ``short''). - -Here's a more complex predicate: - -@lisp -(or high - (and - (not low) - (not long))) -@end lisp - -This means that an article should be downloaded if it has a high score, -or if the score is not low and the article is not long. You get the -drift. - -The available logical operators are @code{or}, @code{and} and -@code{not}. (If you prefer, you can use the more ``C''-ish operators -@samp{|}, @code{&} and @code{!} instead.) - -The following predicates are pre-defined, but if none of these fit what -you want to do, you can write your own. - -When evaluating each of these predicates, the named constant will be -bound to the value determined by calling -@code{gnus-agent-find-parameter} on the appropriate parameter. For -example, gnus-agent-short-article will be bound to -@code{(gnus-agent-find-parameter group 'agent-short-article)}. This -means that you can specify a predicate in your category then tune that -predicate to individual groups. - -@table @code -@item short -True if the article is shorter than @code{gnus-agent-short-article} -lines; default 100. - -@item long -True if the article is longer than @code{gnus-agent-long-article} -lines; default 200. - -@item low -True if the article has a download score less than -@code{gnus-agent-low-score}; default 0. - -@item high -True if the article has a download score greater than -@code{gnus-agent-high-score}; default 0. - -@item spam -True if the Gnus Agent guesses that the article is spam. The -heuristics may change over time, but at present it just computes a -checksum and sees whether articles match. - -@item true -Always true. - -@item false -Always false. -@end table - -If you want to create your own predicate function, here's what you have -to know: The functions are called with no parameters, but the -@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to -useful values. - -For example, you could decide that you don't want to download articles -that were posted more than a certain number of days ago (e.g., posted -more than @code{gnus-agent-expire-days} ago) you might write a function -something along the lines of the following: - -@lisp -(defun my-article-old-p () - "Say whether an article is old." - (< (time-to-days (date-to-time (mail-header-date gnus-headers))) - (- (time-to-days (current-time)) gnus-agent-expire-days))) -@end lisp - -with the predicate then defined as: - -@lisp -(not my-article-old-p) -@end lisp - -or you could append your predicate to the predefined -@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or -wherever. - -@lisp -(require 'gnus-agent) -(setq gnus-category-predicate-alist - (append gnus-category-predicate-alist - '((old . my-article-old-p)))) -@end lisp - -and simply specify your predicate as: - -@lisp -(not old) -@end lisp - -If/when using something like the above, be aware that there are many -misconfigured systems/mailers out there and so an article's date is not -always a reliable indication of when it was posted. Hell, some people -just don't give a damn. - -The above predicates apply to @emph{all} the groups which belong to the -category. However, if you wish to have a specific predicate for an -individual group within a category, or you're just too lazy to set up a -new category, you can enter a group's individual predicate in its group -parameters like so: - -@lisp -(agent-predicate . short) -@end lisp - -This is the group/topic parameter equivalent of the agent category default. -Note that when specifying a single word predicate like this, the -@code{agent-predicate} specification must be in dotted pair notation. - -The equivalent of the longer example from above would be: - -@lisp -(agent-predicate or high (and (not low) (not long))) -@end lisp - -The outer parenthesis required in the category specification are not -entered here as, not being in dotted pair notation, the value of the -predicate is assumed to be a list. - - -Now, the syntax of the download score is the same as the syntax of -normal score files, except that all elements that require actually -seeing the article itself are verboten. This means that only the -following headers can be scored on: @code{Subject}, @code{From}, -@code{Date}, @code{Message-ID}, @code{References}, @code{Chars}, -@code{Lines}, and @code{Xref}. - -As with predicates, the specification of the @code{download score rule} -to use in respect of a group can be in either the category definition if -it's to be applicable to all groups in therein, or a group's parameters -if it's to be specific to that group. - -In both of these places the @code{download score rule} can take one of -three forms: - -@enumerate -@item -Score rule - -This has the same syntax as a normal Gnus score file except only a -subset of scoring keywords are available as mentioned above. - -example: - -@itemize @bullet -@item -Category specification - -@lisp -(("from" - ("Lars Ingebrigtsen" 1000000 nil s)) -("lines" - (500 -100 nil <))) -@end lisp - -@item -Group/Topic Parameter specification - -@lisp -(agent-score ("from" - ("Lars Ingebrigtsen" 1000000 nil s)) - ("lines" - (500 -100 nil <))) -@end lisp - -Again, note the omission of the outermost parenthesis here. -@end itemize - -@item -Agent score file - -These score files must @emph{only} contain the permitted scoring -keywords stated above. - -example: - -@itemize @bullet -@item -Category specification - -@lisp -("~/News/agent.SCORE") -@end lisp - -or perhaps - -@lisp -("~/News/agent.SCORE" "~/News/agent.group.SCORE") -@end lisp - -@item -Group Parameter specification - -@lisp -(agent-score "~/News/agent.SCORE") -@end lisp - -Additional score files can be specified as above. Need I say anything -about parenthesis? -@end itemize - -@item -Use @code{normal} score files - -If you don't want to maintain two sets of scoring rules for a group, and -your desired @code{downloading} criteria for a group are the same as your -@code{reading} criteria then you can tell the agent to refer to your -@code{normal} score files when deciding what to download. - -These directives in either the category definition or a group's -parameters will cause the agent to read in all the applicable score -files for a group, @emph{filtering out} those sections that do not -relate to one of the permitted subset of scoring keywords. - -@itemize @bullet -@item -Category Specification - -@lisp -file -@end lisp - -@item -Group Parameter specification - -@lisp -(agent-score . file) -@end lisp -@end itemize -@end enumerate - -@node Category Buffer -@subsubsection Category Buffer - -You'd normally do all category maintenance from the category buffer. -When you enter it for the first time (with the @kbd{J c} command from -the group buffer), you'll only see the @code{default} category. - -The following commands are available in this buffer: - -@table @kbd -@item q -@kindex q (Category) -@findex gnus-category-exit -Return to the group buffer (@code{gnus-category-exit}). - -@item e -@kindex e (Category) -@findex gnus-category-customize-category -Use a customization buffer to set all of the selected category's -parameters at one time (@code{gnus-category-customize-category}). - -@item k -@kindex k (Category) -@findex gnus-category-kill -Kill the current category (@code{gnus-category-kill}). - -@item c -@kindex c (Category) -@findex gnus-category-copy -Copy the current category (@code{gnus-category-copy}). - -@item a -@kindex a (Category) -@findex gnus-category-add -Add a new category (@code{gnus-category-add}). - -@item p -@kindex p (Category) -@findex gnus-category-edit-predicate -Edit the predicate of the current category -(@code{gnus-category-edit-predicate}). - -@item g -@kindex g (Category) -@findex gnus-category-edit-groups -Edit the list of groups belonging to the current category -(@code{gnus-category-edit-groups}). - -@item s -@kindex s (Category) -@findex gnus-category-edit-score -Edit the download score rule of the current category -(@code{gnus-category-edit-score}). - -@item l -@kindex l (Category) -@findex gnus-category-list -List all the categories (@code{gnus-category-list}). -@end table - - -@node Category Variables -@subsubsection Category Variables - -@table @code -@item gnus-category-mode-hook -@vindex gnus-category-mode-hook -Hook run in category buffers. - -@item gnus-category-line-format -@vindex gnus-category-line-format -Format of the lines in the category buffer (@pxref{Formatting -Variables}). Valid elements are: - -@table @samp -@item c -The name of the category. - -@item g -The number of groups in the category. -@end table - -@item gnus-category-mode-line-format -@vindex gnus-category-mode-line-format -Format of the category mode line (@pxref{Mode Line Formatting}). - -@item gnus-agent-short-article -@vindex gnus-agent-short-article -Articles that have fewer lines than this are short. Default 100. - -@item gnus-agent-long-article -@vindex gnus-agent-long-article -Articles that have more lines than this are long. Default 200. - -@item gnus-agent-low-score -@vindex gnus-agent-low-score -Articles that have a score lower than this have a low score. Default -0. - -@item gnus-agent-high-score -@vindex gnus-agent-high-score -Articles that have a score higher than this have a high score. Default -0. - -@item gnus-agent-expire-days -@vindex gnus-agent-expire-days -The number of days that a @samp{read} article must stay in the agent's -local disk before becoming eligible for expiration (While the name is -the same, this doesn't mean expiring the article on the server. It -just means deleting the local copy of the article). What is also -important to understand is that the counter starts with the time the -article was written to the local disk and not the time the article was -read. -Default 7. - -@item gnus-agent-enable-expiration -@vindex gnus-agent-enable-expiration -Determines whether articles in a group are, by default, expired or -retained indefinitely. The default is @code{ENABLE} which means that -you'll have to disable expiration when desired. On the other hand, -you could set this to @code{DISABLE}. In that case, you would then -have to enable expiration in selected groups. - -@end table - - -@node Agent Commands -@subsection Agent Commands -@findex gnus-agent-toggle-plugged -@kindex J j (Agent) - -All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j} -(@code{gnus-agent-toggle-plugged}) command works in all modes, and -toggles the plugged/unplugged state of the Gnus Agent. - - -@menu -* Group Agent Commands:: Configure groups and fetch their contents. -* Summary Agent Commands:: Manually select then fetch specific articles. -* Server Agent Commands:: Select the servers that are supported by the agent. -@end menu - - - - -@node Group Agent Commands -@subsubsection Group Agent Commands - -@table @kbd -@item J u -@kindex J u (Agent Group) -@findex gnus-agent-fetch-groups -Fetch all eligible articles in the current group -(@code{gnus-agent-fetch-groups}). - -@item J c -@kindex J c (Agent Group) -@findex gnus-enter-category-buffer -Enter the Agent category buffer (@code{gnus-enter-category-buffer}). - -@item J s -@kindex J s (Agent Group) -@findex gnus-agent-fetch-session -Fetch all eligible articles in all groups -(@code{gnus-agent-fetch-session}). - -@item J S -@kindex J S (Agent Group) -@findex gnus-group-send-queue -Send all sendable messages in the queue group -(@code{gnus-group-send-queue}). @xref{Drafts}. - -@item J a -@kindex J a (Agent Group) -@findex gnus-agent-add-group -Add the current group to an Agent category -(@code{gnus-agent-add-group}). This command understands the -process/prefix convention (@pxref{Process/Prefix}). - -@item J r -@kindex J r (Agent Group) -@findex gnus-agent-remove-group -Remove the current group from its category, if any -(@code{gnus-agent-remove-group}). This command understands the -process/prefix convention (@pxref{Process/Prefix}). - -@item J Y -@kindex J Y (Agent Group) -@findex gnus-agent-synchronize-flags -Synchronize flags changed while unplugged with remote server, if any. - - -@end table - - -@node Summary Agent Commands -@subsubsection Summary Agent Commands - -@table @kbd -@item J # -@kindex J # (Agent Summary) -@findex gnus-agent-mark-article -Mark the article for downloading (@code{gnus-agent-mark-article}). - -@item J M-# -@kindex J M-# (Agent Summary) -@findex gnus-agent-unmark-article -Remove the downloading mark from the article -(@code{gnus-agent-unmark-article}). - -@cindex % -@item @@ -@kindex @@ (Agent Summary) -@findex gnus-agent-toggle-mark -Toggle whether to download the article -(@code{gnus-agent-toggle-mark}). The download mark is @samp{%} by -default. - -@item J c -@kindex J c (Agent Summary) -@findex gnus-agent-catchup -Mark all articles as read (@code{gnus-agent-catchup}) that are neither cached, downloaded, nor downloadable. - -@item J S -@kindex J S (Agent Summary) -@findex gnus-agent-fetch-group -Download all eligible (@pxref{Agent Categories}) articles in this group. -(@code{gnus-agent-fetch-group}). - -@item J s -@kindex J s (Agent Summary) -@findex gnus-agent-summary-fetch-series -Download all processable articles in this group. -(@code{gnus-agent-summary-fetch-series}). - -@item J u -@kindex J u (Agent Summary) -@findex gnus-agent-summary-fetch-group -Download all downloadable articles in the current group -(@code{gnus-agent-summary-fetch-group}). - -@end table - - -@node Server Agent Commands -@subsubsection Server Agent Commands - -@table @kbd -@item J a -@kindex J a (Agent Server) -@findex gnus-agent-add-server -Add the current server to the list of servers covered by the Gnus Agent -(@code{gnus-agent-add-server}). - -@item J r -@kindex J r (Agent Server) -@findex gnus-agent-remove-server -Remove the current server from the list of servers covered by the Gnus -Agent (@code{gnus-agent-remove-server}). - -@end table - - -@node Agent Visuals -@subsection Agent Visuals - -If you open a summary while unplugged and, Gnus knows from the group's -active range that there are more articles than the headers currently -stored in the Agent, you may see some articles whose subject looks -something like @samp{[Undownloaded article #####]}. These are -placeholders for the missing headers. Aside from setting a mark, -there is not much that can be done with one of these placeholders. -When Gnus finally gets a chance to fetch the group's headers, the -placeholders will automatically be replaced by the actual headers. -You can configure the summary buffer's maneuvering to skip over the -placeholders if you care (See @code{gnus-auto-goto-ignores}). - -While it may be obvious to all, the only headers and articles -available while unplugged are those headers and articles that were -fetched into the Agent while previously plugged. To put it another -way, ``If you forget to fetch something while plugged, you might have a -less than satisfying unplugged session''. For this reason, the Agent -adds two visual effects to your summary buffer. These effects display -the download status of each article so that you always know which -articles will be available when unplugged. - -The first visual effect is the @samp{%O} spec. If you customize -@code{gnus-summary-line-format} to include this specifier, you will add -a single character field that indicates an article's download status. -Articles that have been fetched into either the Agent or the Cache, -will display @code{gnus-downloaded-mark} (defaults to @samp{+}). All -other articles will display @code{gnus-undownloaded-mark} (defaults to -@samp{-}). If you open a group that has not been agentized, a space -(@samp{ }) will be displayed. - -The second visual effect are the undownloaded faces. The faces, there -are three indicating the article's score (low, normal, high), seem to -result in a love/hate response from many Gnus users. The problem is -that the face selection is controlled by a list of condition tests and -face names (See @code{gnus-summary-highlight}). Each condition is -tested in the order in which it appears in the list so early -conditions have precedence over later conditions. All of this means -that, if you tick an undownloaded article, the article will continue -to be displayed in the undownloaded face rather than the ticked face. - -If you use the Agent as a cache (to avoid downloading the same article -each time you visit it or to minimize your connection time), the -undownloaded face will probably seem like a good idea. The reason -being that you do all of our work (marking, reading, deleting) with -downloaded articles so the normal faces always appear. For those -users using the agent to improve online performance by caching the NOV -database (most users since 5.10.2), the undownloaded faces may appear -to be an absolutely horrible idea. The issue being that, since none -of their articles have been fetched into the Agent, all of the -normal faces will be obscured by the undownloaded faces. - -If you would like to use the undownloaded faces, you must enable the -undownloaded faces by setting the @code{agent-enable-undownloaded-faces} -group parameter to @code{t}. This parameter, like all other agent -parameters, may be set on an Agent Category (@pxref{Agent Categories}), -a Group Topic (@pxref{Topic Parameters}), or an individual group -(@pxref{Group Parameters}). - -The one problem common to all users using the agent is how quickly it -can consume disk space. If you using the agent on many groups, it is -even more difficult to effectively recover disk space. One solution -is the @samp{%F} format available in @code{gnus-group-line-format}. -This format will display the actual disk space used by articles -fetched into both the agent and cache. By knowing which groups use -the most space, users know where to focus their efforts when ``agent -expiring'' articles. - -@node Agent as Cache -@subsection Agent as Cache - -When Gnus is plugged, it is not efficient to download headers or -articles from the server again, if they are already stored in the -Agent. So, Gnus normally only downloads headers once, and stores them -in the Agent. These headers are later used when generating the summary -buffer, regardless of whether you are plugged or unplugged. Articles -are not cached in the Agent by default though (that would potentially -consume lots of disk space), but if you have already downloaded an -article into the Agent, Gnus will not download the article from the -server again but use the locally stored copy instead. - -If you so desire, you can configure the agent (see @code{gnus-agent-cache} -@pxref{Agent Variables}) to always download headers and articles while -plugged. Gnus will almost certainly be slower, but it will be kept -synchronized with the server. That last point probably won't make any -sense if you are using a nntp or nnimap back end. - -@node Agent Expiry -@subsection Agent Expiry - -@vindex gnus-agent-expire-days -@findex gnus-agent-expire -@kindex M-x gnus-agent-expire -@kindex M-x gnus-agent-expire-group -@findex gnus-agent-expire-group -@cindex agent expiry -@cindex Gnus agent expiry -@cindex expiry, in Gnus agent - -The Agent back end, @code{nnagent}, doesn't handle expiry. Well, at -least it doesn't handle it like other back ends. Instead, there are -special @code{gnus-agent-expire} and @code{gnus-agent-expire-group} -commands that will expire all read articles that are older than -@code{gnus-agent-expire-days} days. They can be run whenever you feel -that you're running out of space. Neither are particularly fast or -efficient, and it's not a particularly good idea to interrupt them (with -@kbd{C-g} or anything else) once you've started one of them. - -Note that other functions might run @code{gnus-agent-expire} for you -to keep the agent synchronized with the group. - -The agent parameter @code{agent-enable-expiration} may be used to -prevent expiration in selected groups. - -@vindex gnus-agent-expire-all -If @code{gnus-agent-expire-all} is non-@code{nil}, the agent -expiration commands will expire all articles---unread, read, ticked -and dormant. If @code{nil} (which is the default), only read articles -are eligible for expiry, and unread, ticked and dormant articles will -be kept indefinitely. - -If you find that some articles eligible for expiry are never expired, -perhaps some Gnus Agent files are corrupted. There's are special -commands, @code{gnus-agent-regenerate} and -@code{gnus-agent-regenerate-group}, to fix possible problems. - -@node Agent Regeneration -@subsection Agent Regeneration - -@cindex agent regeneration -@cindex Gnus agent regeneration -@cindex regeneration - -The local data structures used by @code{nnagent} may become corrupted -due to certain exceptional conditions. When this happens, -@code{nnagent} functionality may degrade or even fail. The solution -to this problem is to repair the local data structures by removing all -internal inconsistencies. - -For example, if your connection to your server is lost while -downloaded articles into the agent, the local data structures will not -know about articles successfully downloaded prior to the connection -failure. Running @code{gnus-agent-regenerate} or -@code{gnus-agent-regenerate-group} will update the data structures -such that you don't need to download these articles a second time. - -@findex gnus-agent-regenerate -@kindex M-x gnus-agent-regenerate -The command @code{gnus-agent-regenerate} will perform -@code{gnus-agent-regenerate-group} on every agentized group. While -you can run @code{gnus-agent-regenerate} in any buffer, it is strongly -recommended that you first close all summary buffers. - -@findex gnus-agent-regenerate-group -@kindex M-x gnus-agent-regenerate-group -The command @code{gnus-agent-regenerate-group} uses the local copies -of individual articles to repair the local @acronym{NOV}(header) database. It -then updates the internal data structures that document which articles -are stored locally. An optional argument will mark articles in the -agent as unread. - -@node Agent and flags -@subsection Agent and flags - -The Agent works with any Gnus back end including those, such as -nnimap, that store flags (read, ticked, etc.)@: on the server. Sadly, -the Agent does not actually know which backends keep their flags in -the backend server rather than in @file{.newsrc}. This means that the -Agent, while unplugged or disconnected, will always record all changes -to the flags in its own files. - -When you plug back in, Gnus will then check to see if you have any -changed any flags and ask if you wish to synchronize these with the -server. This behavior is customizable by @code{gnus-agent-synchronize-flags}. - -@vindex gnus-agent-synchronize-flags -If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will -never automatically synchronize flags. If it is @code{ask}, which is -the default, the Agent will check if you made any changes and if so -ask if you wish to synchronize these when you re-connect. If it has -any other value, all flags will be synchronized automatically. - -If you do not wish to synchronize flags automatically when you -re-connect, you can do it manually with the -@code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y} -in the group buffer. - -Technical note: the synchronization algorithm does not work by ``pushing'' -all local flags to the server, but rather by incrementally updated the -server view of flags by changing only those flags that were changed by -the user. Thus, if you set one flag on an article, quit the group then -re-select the group and remove the flag; the flag will be set and -removed from the server when you ``synchronize''. The queued flag -operations can be found in the per-server @code{flags} file in the Agent -directory. It's emptied when you synchronize flags. - -@node Agent and IMAP -@subsection Agent and IMAP - -The Agent works with any Gnus back end, including nnimap. However, -since there are some conceptual differences between @acronym{NNTP} and -@acronym{IMAP}, this section (should) provide you with some information to -make Gnus Agent work smoother as a @acronym{IMAP} Disconnected Mode client. - -Some things are currently not implemented in the Agent that you'd might -expect from a disconnected @acronym{IMAP} client, including: - -@itemize @bullet - -@item -Copying/moving articles into nnimap groups when unplugged. - -@item -Creating/deleting nnimap groups when unplugged. - -@end itemize - -@node Outgoing Messages -@subsection Outgoing Messages - -By default, when Gnus is unplugged, all outgoing messages (both mail -and news) are stored in the draft group ``queue'' (@pxref{Drafts}). -You can view them there after posting, and edit them at will. - -You can control the circumstances under which outgoing mail is queued -(see @code{gnus-agent-queue-mail}, @pxref{Agent Variables}). Outgoing -news is always queued when Gnus is unplugged, and never otherwise. - -You can send the messages either from the draft group with the special -commands available there, or you can use the @kbd{J S} command in the -group buffer to send all the sendable messages in the draft group. -Posting news will only work when Gnus is plugged, but you can send -mail at any time. - -If sending mail while unplugged does not work for you and you worry -about hitting @kbd{J S} by accident when unplugged, you can have Gnus -ask you to confirm your action (see -@code{gnus-agent-prompt-send-queue}, @pxref{Agent Variables}). - -@node Agent Variables -@subsection Agent Variables - -@table @code -@item gnus-agent -@vindex gnus-agent -Is the agent enabled? The default is @code{t}. When first enabled, -the agent will use @code{gnus-agent-auto-agentize-methods} to -automatically mark some back ends as agentized. You may change which -back ends are agentized using the agent commands in the server buffer. - -To enter the server buffer, use the @kbd{^} -(@code{gnus-group-enter-server-mode}) command in the group buffer. - - -@item gnus-agent-directory -@vindex gnus-agent-directory -Where the Gnus Agent will store its files. The default is -@file{~/News/agent/}. - -@item gnus-agent-handle-level -@vindex gnus-agent-handle-level -Groups on levels (@pxref{Group Levels}) higher than this variable will -be ignored by the Agent. The default is @code{gnus-level-subscribed}, -which means that only subscribed group will be considered by the Agent -by default. - -@item gnus-agent-plugged-hook -@vindex gnus-agent-plugged-hook -Hook run when connecting to the network. - -@item gnus-agent-unplugged-hook -@vindex gnus-agent-unplugged-hook -Hook run when disconnecting from the network. - -@item gnus-agent-fetched-hook -@vindex gnus-agent-fetched-hook -Hook run when finished fetching articles. - -@item gnus-agent-cache -@vindex gnus-agent-cache -Variable to control whether use the locally stored @acronym{NOV} and -articles when plugged, e.g., essentially using the Agent as a cache. -The default is non-@code{nil}, which means to use the Agent as a cache. - -@item gnus-agent-go-online -@vindex gnus-agent-go-online -If @code{gnus-agent-go-online} is @code{nil}, the Agent will never -automatically switch offline servers into online status. If it is -@code{ask}, the default, the Agent will ask if you wish to switch -offline servers into online status when you re-connect. If it has any -other value, all offline servers will be automatically switched into -online status. - -@item gnus-agent-mark-unread-after-downloaded -@vindex gnus-agent-mark-unread-after-downloaded -If @code{gnus-agent-mark-unread-after-downloaded} is non-@code{nil}, -mark articles as unread after downloading. This is usually a safe -thing to do as the newly downloaded article has obviously not been -read. The default is @code{t}. - -@item gnus-agent-synchronize-flags -@vindex gnus-agent-synchronize-flags -If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will -never automatically synchronize flags. If it is @code{ask}, which is -the default, the Agent will check if you made any changes and if so -ask if you wish to synchronize these when you re-connect. If it has -any other value, all flags will be synchronized automatically. - -@item gnus-agent-consider-all-articles -@vindex gnus-agent-consider-all-articles -If @code{gnus-agent-consider-all-articles} is non-@code{nil}, the -agent will let the agent predicate decide whether articles need to be -downloaded or not, for all articles. When @code{nil}, the default, -the agent will only let the predicate decide whether unread articles -are downloaded or not. If you enable this, you may also want to look -into the agent expiry settings (@pxref{Category Variables}), so that -the agent doesn't download articles which the agent will later expire, -over and over again. - -@item gnus-agent-max-fetch-size -@vindex gnus-agent-max-fetch-size -The agent fetches articles into a temporary buffer prior to parsing -them into individual files. To avoid exceeding the max. buffer size, -the agent alternates between fetching and parsing until all articles -have been fetched. @code{gnus-agent-max-fetch-size} provides a size -limit to control how often the cycling occurs. A large value improves -performance. A small value minimizes the time lost should the -connection be lost while fetching (You may need to run -@code{gnus-agent-regenerate-group} to update the group's state. -However, all articles parsed prior to losing the connection will be -available while unplugged). The default is 10M so it is unusual to -see any cycling. - -@item gnus-server-unopen-status -@vindex gnus-server-unopen-status -Perhaps not an Agent variable, but closely related to the Agent, this -variable says what will happen if Gnus cannot open a server. If the -Agent is enabled, the default, @code{nil}, makes Gnus ask the user -whether to deny the server or whether to unplug the agent. If the -Agent is disabled, Gnus always simply deny the server. Other choices -for this variable include @code{denied} and @code{offline} the latter -is only valid if the Agent is used. - -@item gnus-auto-goto-ignores -@vindex gnus-auto-goto-ignores -Another variable that isn't an Agent variable, yet so closely related -that most will look for it here, this variable tells the summary -buffer how to maneuver around undownloaded (only headers stored in the -agent) and unfetched (neither article nor headers stored) articles. - -The valid values are @code{nil} (maneuver to any article), -@code{undownloaded} (maneuvering while unplugged ignores articles that -have not been fetched), @code{always-undownloaded} (maneuvering always -ignores articles that have not been fetched), @code{unfetched} -(maneuvering ignores articles whose headers have not been fetched). - -@item gnus-agent-queue-mail -@vindex gnus-agent-queue-mail -When @code{gnus-agent-queue-mail} is @code{always}, Gnus will always -queue mail rather than sending it straight away. When @code{t}, Gnus -will queue mail when unplugged only. When @code{nil}, never queue -mail. The default is @code{t}. - -@item gnus-agent-prompt-send-queue -@vindex gnus-agent-prompt-send-queue -When @code{gnus-agent-prompt-send-queue} is non-@code{nil} Gnus will -prompt you to confirm that you really wish to proceed if you hit -@kbd{J S} while unplugged. The default is @code{nil}. - -@item gnus-agent-auto-agentize-methods -@vindex gnus-agent-auto-agentize-methods -If you have never used the Agent before (or more technically, if -@file{~/News/agent/lib/servers} does not exist), Gnus will -automatically agentize a few servers for you. This variable control -which back ends should be auto-agentized. It is typically only useful -to agentize remote back ends. The auto-agentizing has the same effect -as running @kbd{J a} on the servers (@pxref{Server Agent Commands}). -If the file exist, you must manage the servers manually by adding or -removing them, this variable is only applicable the first time you -start Gnus. The default is @samp{nil}. - -@end table - - -@node Example Setup -@subsection Example Setup - -If you don't want to read this manual, and you have a fairly standard -setup, you may be able to use something like the following as your -@file{~/.gnus.el} file to get started. - -@lisp -;; @r{Define how Gnus is to fetch news. We do this over @acronym{NNTP}} -;; @r{from your ISP's server.} -(setq gnus-select-method '(nntp "news.your-isp.com")) - -;; @r{Define how Gnus is to read your mail. We read mail from} -;; @r{your ISP's @acronym{POP} server.} -(setq mail-sources '((pop :server "pop.your-isp.com"))) - -;; @r{Say how Gnus is to store the mail. We use nnml groups.} -(setq gnus-secondary-select-methods '((nnml ""))) - -;; @r{Make Gnus into an offline newsreader.} -;; (gnus-agentize) ; @r{The obsolete setting.} -;; (setq gnus-agent t) ; @r{Now the default.} -@end lisp - -That should be it, basically. Put that in your @file{~/.gnus.el} file, -edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x -gnus}. - -If this is the first time you've run Gnus, you will be subscribed -automatically to a few default newsgroups. You'll probably want to -subscribe to more groups, and to do that, you have to query the -@acronym{NNTP} server for a complete list of groups with the @kbd{A A} -command. This usually takes quite a while, but you only have to do it -once. - -After reading and parsing a while, you'll be presented with a list of -groups. Subscribe to the ones you want to read with the @kbd{u} -command. @kbd{l} to make all the killed groups disappear after you've -subscribe to all the groups you want to read. (@kbd{A k} will bring -back all the killed groups.) - -You can now read the groups at once, or you can download the articles -with the @kbd{J s} command. And then read the rest of this manual to -find out which of the other gazillion things you want to customize. - - -@node Batching Agents -@subsection Batching Agents -@findex gnus-agent-batch - -Having the Gnus Agent fetch articles (and post whatever messages you've -written) is quite easy once you've gotten things set up properly. The -following shell script will do everything that is necessary: - -You can run a complete batch command from the command line with the -following incantation: - -@example -#!/bin/sh -emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-agent-batch >/dev/null 2>&1 -@end example - - -@node Agent Caveats -@subsection Agent Caveats - -The Gnus Agent doesn't seem to work like most other offline -newsreaders. Here are some common questions that some imaginary people -may ask: - -@table @dfn -@item If I read an article while plugged, do they get entered into the Agent? - -@strong{No}. If you want this behavior, add -@code{gnus-agent-fetch-selected-article} to -@code{gnus-select-article-hook}. - -@item If I read an article while plugged, and the article already exists in -the Agent, will it get downloaded once more? - -@strong{No}, unless @code{gnus-agent-cache} is @code{nil}. - -@end table - -In short, when Gnus is unplugged, it only looks into the locally stored -articles; when it's plugged, it talks to your ISP and may also use the -locally stored articles. - - -@node Scoring -@chapter Scoring -@cindex scoring - -Other people use @dfn{kill files}, but we here at Gnus Towers like -scoring better than killing, so we'd rather switch than fight. They do -something completely different as well, so sit up straight and pay -attention! - -@vindex gnus-summary-mark-below -All articles have a default score (@code{gnus-summary-default-score}), -which is 0 by default. This score may be raised or lowered either -interactively or by score files. Articles that have a score lower than -@code{gnus-summary-mark-below} are marked as read. - -Gnus will read any @dfn{score files} that apply to the current group -before generating the summary buffer. - -There are several commands in the summary buffer that insert score -entries based on the current article. You can, for instance, ask Gnus to -lower or increase the score of all articles with a certain subject. - -There are two sorts of scoring entries: Permanent and temporary. -Temporary score entries are self-expiring entries. Any entries that are -temporary and have not been used for, say, a week, will be removed -silently to help keep the sizes of the score files down. - -@menu -* Summary Score Commands:: Adding score entries for the current group. -* Group Score Commands:: General score commands. -* Score Variables:: Customize your scoring. (My, what terminology). -* Score File Format:: What a score file may contain. -* Score File Editing:: You can edit score files by hand as well. -* Adaptive Scoring:: Big Sister Gnus knows what you read. -* Home Score File:: How to say where new score entries are to go. -* Followups To Yourself:: Having Gnus notice when people answer you. -* Scoring On Other Headers:: Scoring on non-standard headers. -* Scoring Tips:: How to score effectively. -* Reverse Scoring:: That problem child of old is not problem. -* Global Score Files:: Earth-spanning, ear-splitting score files. -* Kill Files:: They are still here, but they can be ignored. -* Converting Kill Files:: Translating kill files to score files. -* Advanced Scoring:: Using logical expressions to build score rules. -* Score Decays:: It can be useful to let scores wither away. -@end menu - - -@node Summary Score Commands -@section Summary Score Commands -@cindex score commands - -The score commands that alter score entries do not actually modify real -score files. That would be too inefficient. Gnus maintains a cache of -previously loaded score files, one of which is considered the -@dfn{current score file alist}. The score commands simply insert -entries into this list, and upon group exit, this list is saved. - -The current score file is by default the group's local score file, even -if no such score file actually exists. To insert score commands into -some other score file (e.g., @file{all.SCORE}), you must first make this -score file the current one. - -General score commands that don't actually change the score file: - -@table @kbd - -@item V s -@kindex V s (Summary) -@findex gnus-summary-set-score -Set the score of the current article (@code{gnus-summary-set-score}). - -@item V S -@kindex V S (Summary) -@findex gnus-summary-current-score -Display the score of the current article -(@code{gnus-summary-current-score}). - -@item V t -@kindex V t (Summary) -@findex gnus-score-find-trace -Display all score rules that have been used on the current article -(@code{gnus-score-find-trace}). In the @file{*Score Trace*} buffer, you -may type @kbd{e} to edit score file corresponding to the score rule on -current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the -score file and edit it. - -@item V w -@kindex V w (Summary) -@findex gnus-score-find-favourite-words -List words used in scoring (@code{gnus-score-find-favourite-words}). - -@item V R -@kindex V R (Summary) -@findex gnus-summary-rescore -Run the current summary through the scoring process -(@code{gnus-summary-rescore}). This might be useful if you're playing -around with your score files behind Gnus' back and want to see the -effect you're having. - -@item V c -@kindex V c (Summary) -@findex gnus-score-change-score-file -Make a different score file the current -(@code{gnus-score-change-score-file}). - -@item V e -@kindex V e (Summary) -@findex gnus-score-edit-current-scores -Edit the current score file (@code{gnus-score-edit-current-scores}). -You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score -File Editing}). - -@item V f -@kindex V f (Summary) -@findex gnus-score-edit-file -Edit a score file and make this score file the current one -(@code{gnus-score-edit-file}). - -@item V F -@kindex V F (Summary) -@findex gnus-score-flush-cache -Flush the score cache (@code{gnus-score-flush-cache}). This is useful -after editing score files. - -@item V C -@kindex V C (Summary) -@findex gnus-score-customize -Customize a score file in a visually pleasing manner -(@code{gnus-score-customize}). - -@end table - -The rest of these commands modify the local score file. - -@table @kbd - -@item V m -@kindex V m (Summary) -@findex gnus-score-set-mark-below -Prompt for a score, and mark all articles with a score below this as -read (@code{gnus-score-set-mark-below}). - -@item V x -@kindex V x (Summary) -@findex gnus-score-set-expunge-below -Prompt for a score, and add a score rule to the current score file to -expunge all articles below this score -(@code{gnus-score-set-expunge-below}). -@end table - -The keystrokes for actually making score entries follow a very regular -pattern, so there's no need to list all the commands. (Hundreds of -them.) - -@findex gnus-summary-increase-score -@findex gnus-summary-lower-score - -@enumerate -@item -The first key is either @kbd{I} (upper case i) for increasing the score -or @kbd{L} for lowering the score. -@item -The second key says what header you want to score on. The following -keys are available: -@table @kbd - -@item a -Score on the author name. - -@item s -Score on the subject line. - -@item x -Score on the @code{Xref} line---i.e., the cross-posting line. - -@item r -Score on the @code{References} line. - -@item d -Score on the date. - -@item l -Score on the number of lines. - -@item i -Score on the @code{Message-ID} header. - -@item e -Score on an ``extra'' header, that is, one of those in gnus-extra-headers, -if your @acronym{NNTP} server tracks additional header data in overviews. - -@item f -Score on followups---this matches the author name, and adds scores to -the followups to this author. (Using this key leads to the creation of -@file{ADAPT} files.) - -@item b -Score on the body. - -@item h -Score on the head. - -@item t -Score on thread. (Using this key leads to the creation of @file{ADAPT} -files.) - -@end table - -@item -The third key is the match type. Which match types are valid depends on -what headers you are scoring on. - -@table @code - -@item strings - -@table @kbd - -@item e -Exact matching. - -@item s -Substring matching. - -@item f -Fuzzy matching (@pxref{Fuzzy Matching}). - -@item r -Regexp matching -@end table - -@item date -@table @kbd - -@item b -Before date. - -@item a -After date. - -@item n -This date. -@end table - -@item number -@table @kbd - -@item < -Less than number. - -@item = -Equal to number. - -@item > -Greater than number. -@end table -@end table - -@item -The fourth and usually final key says whether this is a temporary (i.e., -expiring) score entry, or a permanent (i.e., non-expiring) score entry, -or whether it is to be done immediately, without adding to the score -file. -@table @kbd - -@item t -Temporary score entry. - -@item p -Permanent score entry. - -@item i -Immediately scoring. -@end table - -@item -If you are scoring on `e' (extra) headers, you will then be prompted for -the header name on which you wish to score. This must be a header named -in gnus-extra-headers, and @samp{TAB} completion is available. - -@end enumerate - -So, let's say you want to increase the score on the current author with -exact matching permanently: @kbd{I a e p}. If you want to lower the -score based on the subject line, using substring matching, and make a -temporary score entry: @kbd{L s s t}. Pretty easy. - -To make things a bit more complicated, there are shortcuts. If you use -a capital letter on either the second or third keys, Gnus will use -defaults for the remaining one or two keystrokes. The defaults are -``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s -t}, and @kbd{I a R} is the same as @kbd{I a r t}. - -These functions take both the numerical prefix and the symbolic prefix -(@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower -(or increase) the score of the article. A symbolic prefix of @code{a} -says to use the @file{all.SCORE} file for the command instead of the -current score file. - -@vindex gnus-score-mimic-keymap -The @code{gnus-score-mimic-keymap} says whether these commands will -pretend they are keymaps or not. - - -@node Group Score Commands -@section Group Score Commands -@cindex group score commands - -There aren't many of these as yet, I'm afraid. - -@table @kbd - -@item W e -@kindex W e (Group) -@findex gnus-score-edit-all-score -Edit the apply-to-all-groups all.SCORE file. You will be popped into -a @code{gnus-score-mode} buffer (@pxref{Score File Editing}). - -@item W f -@kindex W f (Group) -@findex gnus-score-flush-cache -Gnus maintains a cache of score alists to avoid having to reload them -all the time. This command will flush the cache -(@code{gnus-score-flush-cache}). - -@end table - -You can do scoring from the command line by saying something like: - -@findex gnus-batch-score -@cindex batch scoring -@example -$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score -@end example - - -@node Score Variables -@section Score Variables -@cindex score variables - -@table @code - -@item gnus-use-scoring -@vindex gnus-use-scoring -If @code{nil}, Gnus will not check for score files, and will not, in -general, do any score-related work. This is @code{t} by default. - -@item gnus-kill-killed -@vindex gnus-kill-killed -If this variable is @code{nil}, Gnus will never apply score files to -articles that have already been through the kill process. While this -may save you lots of time, it also means that if you apply a kill file -to a group, and then change the kill file and want to run it over you -group again to kill more articles, it won't work. You have to set this -variable to @code{t} to do that. (It is @code{t} by default.) - -@item gnus-kill-files-directory -@vindex gnus-kill-files-directory -All kill and score files will be stored in this directory, which is -initialized from the @env{SAVEDIR} environment variable by default. -This is @file{~/News/} by default. - -@item gnus-score-file-suffix -@vindex gnus-score-file-suffix -Suffix to add to the group name to arrive at the score file name -(@file{SCORE} by default.) - -@item gnus-score-uncacheable-files -@vindex gnus-score-uncacheable-files -@cindex score cache -All score files are normally cached to avoid excessive re-loading of -score files. However, this might make your Emacs grow big and -bloated, so this regexp can be used to weed out score files unlikely -to be needed again. It would be a bad idea to deny caching of -@file{all.SCORE}, while it might be a good idea to not cache -@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this -variable is @samp{ADAPT$} by default, so no adaptive score files will -be cached. - -@item gnus-save-score -@vindex gnus-save-score -If you have really complicated score files, and do lots of batch -scoring, then you might set this variable to @code{t}. This will make -Gnus save the scores into the @file{.newsrc.eld} file. - -If you do not set this to @code{t}, then manual scores (like those set -with @kbd{V s} (@code{gnus-summary-set-score})) will not be preserved -across group visits. - -@item gnus-score-interactive-default-score -@vindex gnus-score-interactive-default-score -Score used by all the interactive raise/lower commands to raise/lower -score with. Default is 1000, which may seem excessive, but this is to -ensure that the adaptive scoring scheme gets enough room to play with. -We don't want the small changes from the adaptive scoring to overwrite -manually entered data. - -@item gnus-summary-default-score -@vindex gnus-summary-default-score -Default score of an article, which is 0 by default. - -@item gnus-summary-expunge-below -@vindex gnus-summary-expunge-below -Don't display the summary lines of articles that have scores lower than -this variable. This is @code{nil} by default, which means that no -articles will be hidden. This variable is local to the summary buffers, -and has to be set from @code{gnus-summary-mode-hook}. - -@item gnus-score-over-mark -@vindex gnus-score-over-mark -Mark (in the third column) used for articles with a score over the -default. Default is @samp{+}. - -@item gnus-score-below-mark -@vindex gnus-score-below-mark -Mark (in the third column) used for articles with a score below the -default. Default is @samp{-}. - -@item gnus-score-find-score-files-function -@vindex gnus-score-find-score-files-function -Function used to find score files for the current group. This function -is called with the name of the group as the argument. - -Predefined functions available are: -@table @code - -@item gnus-score-find-single -@findex gnus-score-find-single -Only apply the group's own score file. - -@item gnus-score-find-bnews -@findex gnus-score-find-bnews -Apply all score files that match, using bnews syntax. This is the -default. If the current group is @samp{gnu.emacs.gnus}, for instance, -@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and -@file{gnu.all.SCORE} would all apply. In short, the instances of -@samp{all} in the score file names are translated into @samp{.*}, and -then a regexp match is done. - -This means that if you have some score entries that you want to apply to -all groups, then you put those entries in the @file{all.SCORE} file. - -The score files are applied in a semi-random order, although Gnus will -try to apply the more general score files before the more specific score -files. It does this by looking at the number of elements in the score -file names---discarding the @samp{all} elements. - -@item gnus-score-find-hierarchical -@findex gnus-score-find-hierarchical -Apply all score files from all the parent groups. This means that you -can't have score files like @file{all.SCORE}, but you can have -@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE} for each -server. - -@end table -This variable can also be a list of functions. In that case, all -these functions will be called with the group name as argument, and -all the returned lists of score files will be applied. These -functions can also return lists of lists of score alists directly. In -that case, the functions that return these non-file score alists -should probably be placed before the ``real'' score file functions, to -ensure that the last score file returned is the local score file. -Phu. - -For example, to do hierarchical scoring but use a non-server-specific -overall score file, you could use the value -@example -(list (lambda (group) ("all.SCORE")) - 'gnus-score-find-hierarchical) -@end example - -@item gnus-score-expiry-days -@vindex gnus-score-expiry-days -This variable says how many days should pass before an unused score file -entry is expired. If this variable is @code{nil}, no score file entries -are expired. It's 7 by default. - -@item gnus-update-score-entry-dates -@vindex gnus-update-score-entry-dates -If this variable is non-@code{nil}, temporary score entries that have -been triggered (matched) will have their dates updated. (This is how Gnus -controls expiry---all non-matched-entries will become too old while -matched entries will stay fresh and young.) However, if you set this -variable to @code{nil}, even matched entries will grow old and will -have to face that oh-so grim reaper. - -@item gnus-score-after-write-file-function -@vindex gnus-score-after-write-file-function -Function called with the name of the score file just written. - -@item gnus-score-thread-simplify -@vindex gnus-score-thread-simplify -If this variable is non-@code{nil}, article subjects will be -simplified for subject scoring purposes in the same manner as with -threading---according to the current value of -@code{gnus-simplify-subject-functions}. If the scoring entry uses -@code{substring} or @code{exact} matching, the match will also be -simplified in this manner. - -@end table - - -@node Score File Format -@section Score File Format -@cindex score file format - -A score file is an @code{emacs-lisp} file that normally contains just a -single form. Casual users are not expected to edit these files; -everything can be changed from the summary buffer. - -Anyway, if you'd like to dig into it yourself, here's an example: - -@lisp -(("from" - ("Lars Ingebrigtsen" -10000) - ("Per Abrahamsen") - ("larsi\\|lmi" -50000 nil R)) - ("subject" - ("Ding is Badd" nil 728373)) - ("xref" - ("alt.politics" -1000 728372 s)) - ("lines" - (2 -100 nil <)) - (mark 0) - (expunge -1000) - (mark-and-expunge -10) - (read-only nil) - (orphan -10) - (adapt t) - (files "/hom/larsi/News/gnu.SCORE") - (exclude-files "all.SCORE") - (local (gnus-newsgroup-auto-expire t) - (gnus-summary-make-false-root empty)) - (eval (ding))) -@end lisp - -This example demonstrates most score file elements. @xref{Advanced -Scoring}, for a different approach. - -Even though this looks much like Lisp code, nothing here is actually -@code{eval}ed. The Lisp reader is used to read this form, though, so it -has to be valid syntactically, if not semantically. - -Six keys are supported by this alist: - -@table @code - -@item STRING -If the key is a string, it is the name of the header to perform the -match on. Scoring can only be performed on these eight headers: -@code{From}, @code{Subject}, @code{References}, @code{Message-ID}, -@code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to -these headers, there are three strings to tell Gnus to fetch the entire -article and do the match on larger parts of the article: @code{Body} -will perform the match on the body of the article, @code{Head} will -perform the match on the head of the article, and @code{All} will -perform the match on the entire article. Note that using any of these -last three keys will slow down group entry @emph{considerably}. The -final ``header'' you can score on is @code{Followup}. These score -entries will result in new score entries being added for all follow-ups -to articles that matches these score entries. - -Following this key is an arbitrary number of score entries, where each -score entry has one to four elements. -@enumerate - -@item -The first element is the @dfn{match element}. On most headers this will -be a string, but on the Lines and Chars headers, this must be an -integer. - -@item -If the second element is present, it should be a number---the @dfn{score -element}. This number should be an integer in the neginf to posinf -interval. This number is added to the score of the article if the match -is successful. If this element is not present, the -@code{gnus-score-interactive-default-score} number will be used -instead. This is 1000 by default. - -@item -If the third element is present, it should be a number---the @dfn{date -element}. This date says when the last time this score entry matched, -which provides a mechanism for expiring the score entries. It this -element is not present, the score entry is permanent. The date is -represented by the number of days since December 31, 1 BCE. - -@item -If the fourth element is present, it should be a symbol---the @dfn{type -element}. This element specifies what function should be used to see -whether this score entry matches the article. What match types that can -be used depends on what header you wish to perform the match on. -@table @dfn - -@item From, Subject, References, Xref, Message-ID -For most header types, there are the @code{r} and @code{R} (regexp), as -well as @code{s} and @code{S} (substring) types, and @code{e} and -@code{E} (exact match), and @code{w} (word match) types. If this -element is not present, Gnus will assume that substring matching should -be used. @code{R}, @code{S}, and @code{E} differ from the others in -that the matches will be done in a case-sensitive manner. All these -one-letter types are really just abbreviations for the @code{regexp}, -@code{string}, @code{exact}, and @code{word} types, which you can use -instead, if you feel like. - -@item Extra -Just as for the standard string overview headers, if you are using -gnus-extra-headers, you can score on these headers' values. In this -case, there is a 5th element in the score entry, being the name of the -header to be scored. The following entry is useful in your -@file{all.SCORE} file in case of spam attacks from a single origin -host, if your @acronym{NNTP} server tracks @samp{NNTP-Posting-Host} in -overviews: - -@lisp -("111.222.333.444" -1000 nil s - "NNTP-Posting-Host") -@end lisp - -@item Lines, Chars -These two headers use different match types: @code{<}, @code{>}, -@code{=}, @code{>=} and @code{<=}. - -These predicates are true if - -@example -(PREDICATE HEADER MATCH) -@end example - -evaluates to non-@code{nil}. For instance, the advanced match -@code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the -following form: - -@lisp -(< header-value 4) -@end lisp - -Or to put it another way: When using @code{<} on @code{Lines} with 4 as -the match, we get the score added if the article has less than 4 lines. -(It's easy to get confused and think it's the other way around. But -it's not. I think.) - -When matching on @code{Lines}, be careful because some back ends (like -@code{nndir}) do not generate @code{Lines} header, so every article ends -up being marked as having 0 lines. This can lead to strange results if -you happen to lower score of the articles with few lines. - -@item Date -For the Date header we have three kinda silly match types: -@code{before}, @code{at} and @code{after}. I can't really imagine this -ever being useful, but, like, it would feel kinda silly not to provide -this function. Just in case. You never know. Better safe than sorry. -Once burnt, twice shy. Don't judge a book by its cover. Never not have -sex on a first date. (I have been told that at least one person, and I -quote, ``found this function indispensable'', however.) - -@cindex ISO8601 -@cindex date -A more useful match type is @code{regexp}. With it, you can match the -date string using a regular expression. The date is normalized to -ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If -you want to match all articles that have been posted on April 1st in -every year, you could use @samp{....0401.........} as a match string, -for instance. (Note that the date is kept in its original time zone, so -this will match articles that were posted when it was April 1st where -the article was posted from. Time zones are such wholesome fun for the -whole family, eh?) - -@item Head, Body, All -These three match keys use the same match types as the @code{From} (etc.)@: -header uses. - -@item Followup -This match key is somewhat special, in that it will match the -@code{From} header, and affect the score of not only the matching -articles, but also all followups to the matching articles. This allows -you to increase the score of followups to your own articles, or -decrease the score of followups to the articles of some known -trouble-maker. Uses the same match types as the @code{From} header -uses. (Using this match key will lead to creation of @file{ADAPT} -files.) - -@item Thread -This match key works along the same lines as the @code{Followup} match -key. If you say that you want to score on a (sub-)thread started by an -article with a @code{Message-ID} @var{x}, then you add a @samp{thread} -match. This will add a new @samp{thread} match for each article that -has @var{x} in its @code{References} header. (These new @samp{thread} -matches will use the @code{Message-ID}s of these matching articles.) -This will ensure that you can raise/lower the score of an entire thread, -even though some articles in the thread may not have complete -@code{References} headers. Note that using this may lead to -nondeterministic scores of the articles in the thread. (Using this match -key will lead to creation of @file{ADAPT} files.) -@end table -@end enumerate - -@cindex score file atoms -@item mark -The value of this entry should be a number. Any articles with a score -lower than this number will be marked as read. - -@item expunge -The value of this entry should be a number. Any articles with a score -lower than this number will be removed from the summary buffer. - -@item mark-and-expunge -The value of this entry should be a number. Any articles with a score -lower than this number will be marked as read and removed from the -summary buffer. - -@item thread-mark-and-expunge -The value of this entry should be a number. All articles that belong to -a thread that has a total score below this number will be marked as read -and removed from the summary buffer. @code{gnus-thread-score-function} -says how to compute the total score for a thread. - -@item files -The value of this entry should be any number of file names. These files -are assumed to be score files as well, and will be loaded the same way -this one was. - -@item exclude-files -The clue of this entry should be any number of files. These files will -not be loaded, even though they would normally be so, for some reason or -other. - -@item eval -The value of this entry will be @code{eval}ed. This element will be -ignored when handling global score files. - -@item read-only -Read-only score files will not be updated or saved. Global score files -should feature this atom (@pxref{Global Score Files}). (Note: -@dfn{Global} here really means @dfn{global}; not your personal -apply-to-all-groups score files.) - -@item orphan -The value of this entry should be a number. Articles that do not have -parents will get this number added to their scores. Imagine you follow -some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you -will only follow a few of the threads, also want to see any new threads. - -You can do this with the following two score file entries: - -@example - (orphan -500) - (mark-and-expunge -100) -@end example - -When you enter the group the first time, you will only see the new -threads. You then raise the score of the threads that you find -interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{c y}) the -rest. Next time you enter the group, you will see new articles in the -interesting threads, plus any new threads. - -I.e., the orphan score atom is for high-volume groups where a few -interesting threads which can't be found automatically by ordinary -scoring rules exist. - -@item adapt -This entry controls the adaptive scoring. If it is @code{t}, the -default adaptive scoring rules will be used. If it is @code{ignore}, no -adaptive scoring will be performed on this group. If it is a list, this -list will be used as the adaptive scoring rules. If it isn't present, -or is something other than @code{t} or @code{ignore}, the default -adaptive scoring rules will be used. If you want to use adaptive -scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to -@code{t}, and insert an @code{(adapt ignore)} in the groups where you do -not want adaptive scoring. If you only want adaptive scoring in a few -groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and -insert @code{(adapt t)} in the score files of the groups where you want -it. - -@item adapt-file -All adaptive score entries will go to the file named by this entry. It -will also be applied when entering the group. This atom might be handy -if you want to adapt on several groups at once, using the same adaptive -file for a number of groups. - -@item local -@cindex local variables -The value of this entry should be a list of @code{(@var{var} -@var{value})} pairs. Each @var{var} will be made buffer-local to the -current summary buffer, and set to the value specified. This is a -convenient, if somewhat strange, way of setting variables in some -groups if you don't like hooks much. Note that the @var{value} won't -be evaluated. -@end table - - -@node Score File Editing -@section Score File Editing - -You normally enter all scoring commands from the summary buffer, but you -might feel the urge to edit them by hand as well, so we've supplied you -with a mode for that. - -It's simply a slightly customized @code{emacs-lisp} mode, with these -additional commands: - -@table @kbd - -@item C-c C-c -@kindex C-c C-c (Score) -@findex gnus-score-edit-exit -Save the changes you have made and return to the summary buffer -(@code{gnus-score-edit-exit}). - -@item C-c C-d -@kindex C-c C-d (Score) -@findex gnus-score-edit-insert-date -Insert the current date in numerical format -(@code{gnus-score-edit-insert-date}). This is really the day number, if -you were wondering. - -@item C-c C-p -@kindex C-c C-p (Score) -@findex gnus-score-pretty-print -The adaptive score files are saved in an unformatted fashion. If you -intend to read one of these files, you want to @dfn{pretty print} it -first. This command (@code{gnus-score-pretty-print}) does that for -you. - -@end table - -Type @kbd{M-x gnus-score-mode} to use this mode. - -@vindex gnus-score-mode-hook -@code{gnus-score-menu-hook} is run in score mode buffers. - -In the summary buffer you can use commands like @kbd{V f}, @kbd{V e} and -@kbd{V t} to begin editing score files. - - -@node Adaptive Scoring -@section Adaptive Scoring -@cindex adaptive scoring - -If all this scoring is getting you down, Gnus has a way of making it all -happen automatically---as if by magic. Or rather, as if by artificial -stupidity, to be precise. - -@vindex gnus-use-adaptive-scoring -When you read an article, or mark an article as read, or kill an -article, you leave marks behind. On exit from the group, Gnus can sniff -these marks and add score elements depending on what marks it finds. -You turn on this ability by setting @code{gnus-use-adaptive-scoring} to -@code{t} or @code{(line)}. If you want score adaptively on separate -words appearing in the subjects, you should set this variable to -@code{(word)}. If you want to use both adaptive methods, set this -variable to @code{(word line)}. - -@vindex gnus-default-adaptive-score-alist -To give you complete control over the scoring process, you can customize -the @code{gnus-default-adaptive-score-alist} variable. For instance, it -might look something like this: - -@lisp -(setq gnus-default-adaptive-score-alist - '((gnus-unread-mark) - (gnus-ticked-mark (from 4)) - (gnus-dormant-mark (from 5)) - (gnus-del-mark (from -4) (subject -1)) - (gnus-read-mark (from 4) (subject 2)) - (gnus-expirable-mark (from -1) (subject -1)) - (gnus-killed-mark (from -1) (subject -3)) - (gnus-kill-file-mark) - (gnus-ancient-mark) - (gnus-low-score-mark) - (gnus-catchup-mark (from -1) (subject -1)))) -@end lisp - -As you see, each element in this alist has a mark as a key (either a -variable name or a ``real'' mark---a character). Following this key is -a arbitrary number of header/score pairs. If there are no header/score -pairs following the key, no adaptive scoring will be done on articles -that have that key as the article mark. For instance, articles with -@code{gnus-unread-mark} in the example above will not get adaptive score -entries. - -Each article can have only one mark, so just a single of these rules -will be applied to each article. - -To take @code{gnus-del-mark} as an example---this alist says that all -articles that have that mark (i.e., are marked with @samp{e}) will have a -score entry added to lower based on the @code{From} header by -4, and -lowered by @code{Subject} by -1. Change this to fit your prejudices. - -If you have marked 10 articles with the same subject with -@code{gnus-del-mark}, the rule for that mark will be applied ten times. -That means that that subject will get a score of ten times -1, which -should be, unless I'm much mistaken, -10. - -If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all -the read articles will be marked with the @samp{E} mark. This'll -probably make adaptive scoring slightly impossible, so auto-expiring and -adaptive scoring doesn't really mix very well. - -The headers you can score on are @code{from}, @code{subject}, -@code{message-id}, @code{references}, @code{xref}, @code{lines}, -@code{chars} and @code{date}. In addition, you can score on -@code{followup}, which will create an adaptive score entry that matches -on the @code{References} header using the @code{Message-ID} of the -current article, thereby matching the following thread. - -If you use this scheme, you should set the score file atom @code{mark} -to something small---like -300, perhaps, to avoid having small random -changes result in articles getting marked as read. - -After using adaptive scoring for a week or so, Gnus should start to -become properly trained and enhance the authors you like best, and kill -the authors you like least, without you having to say so explicitly. - -You can control what groups the adaptive scoring is to be performed on -by using the score files (@pxref{Score File Format}). This will also -let you use different rules in different groups. - -@vindex gnus-adaptive-file-suffix -The adaptive score entries will be put into a file where the name is the -group name with @code{gnus-adaptive-file-suffix} appended. The default -is @file{ADAPT}. - -@vindex gnus-adaptive-pretty-print -Adaptive score files can get huge and are not meant to be edited by -human hands. If @code{gnus-adaptive-pretty-print} is @code{nil} (the -default) those files will not be written in a human readable way. - -@vindex gnus-score-exact-adapt-limit -When doing adaptive scoring, substring or fuzzy matching would probably -give you the best results in most cases. However, if the header one -matches is short, the possibility for false positives is great, so if -the length of the match is less than -@code{gnus-score-exact-adapt-limit}, exact matching will be used. If -this variable is @code{nil}, exact matching will always be used to avoid -this problem. - -@vindex gnus-default-adaptive-word-score-alist -As mentioned above, you can adapt either on individual words or entire -headers. If you adapt on words, the -@code{gnus-default-adaptive-word-score-alist} variable says what score -each instance of a word should add given a mark. - -@lisp -(setq gnus-default-adaptive-word-score-alist - `((,gnus-read-mark . 30) - (,gnus-catchup-mark . -10) - (,gnus-killed-mark . -20) - (,gnus-del-mark . -15))) -@end lisp - -This is the default value. If you have adaption on words enabled, every -word that appears in subjects of articles marked with -@code{gnus-read-mark} will result in a score rule that increase the -score with 30 points. - -@vindex gnus-default-ignored-adaptive-words -@vindex gnus-ignored-adaptive-words -Words that appear in the @code{gnus-default-ignored-adaptive-words} list -will be ignored. If you wish to add more words to be ignored, use the -@code{gnus-ignored-adaptive-words} list instead. - -@vindex gnus-adaptive-word-length-limit -Some may feel that short words shouldn't count when doing adaptive -scoring. If so, you may set @code{gnus-adaptive-word-length-limit} to -an integer. Words shorter than this number will be ignored. This -variable defaults to @code{nil}. - -@vindex gnus-adaptive-word-syntax-table -When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the -syntax table in effect. It is similar to the standard syntax table, but -it considers numbers to be non-word-constituent characters. - -@vindex gnus-adaptive-word-minimum -If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive -word scoring process will never bring down the score of an article to -below this number. The default is @code{nil}. - -@vindex gnus-adaptive-word-no-group-words -If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus -won't adaptively word score any of the words in the group name. Useful -for groups like @samp{comp.editors.emacs}, where most of the subject -lines contain the word @samp{emacs}. - -After using this scheme for a while, it might be nice to write a -@code{gnus-psychoanalyze-user} command to go through the rules and see -what words you like and what words you don't like. Or perhaps not. - -Note that the adaptive word scoring thing is highly experimental and is -likely to change in the future. Initial impressions seem to indicate -that it's totally useless as it stands. Some more work (involving more -rigorous statistical methods) will have to be done to make this useful. - - -@node Home Score File -@section Home Score File - -The score file where new score file entries will go is called the -@dfn{home score file}. This is normally (and by default) the score file -for the group itself. For instance, the home score file for -@samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}. - -However, this may not be what you want. It is often convenient to share -a common home score file among many groups---all @samp{emacs} groups -could perhaps use the same home score file. - -@vindex gnus-home-score-file -The variable that controls this is @code{gnus-home-score-file}. It can -be: - -@enumerate -@item -A string. Then this file will be used as the home score file for all -groups. - -@item -A function. The result of this function will be used as the home score -file. The function will be called with the name of the group as the -parameter. - -@item -A list. The elements in this list can be: - -@enumerate -@item -@code{(@var{regexp} @var{file-name})}. If the @var{regexp} matches the -group name, the @var{file-name} will be used as the home score file. - -@item -A function. If the function returns non-@code{nil}, the result will -be used as the home score file. The function will be called with the -name of the group as the parameter. - -@item -A string. Use the string as the home score file. -@end enumerate - -The list will be traversed from the beginning towards the end looking -for matches. - -@end enumerate - -So, if you want to use just a single score file, you could say: - -@lisp -(setq gnus-home-score-file - "my-total-score-file.SCORE") -@end lisp - -If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and -@file{rec.SCORE} for all @samp{rec} groups (and so on), you can say: - -@findex gnus-hierarchial-home-score-file -@lisp -(setq gnus-home-score-file - 'gnus-hierarchial-home-score-file) -@end lisp - -This is a ready-made function provided for your convenience. -Other functions include - -@table @code -@item gnus-current-home-score-file -@findex gnus-current-home-score-file -Return the ``current'' regular score file. This will make scoring -commands add entry to the ``innermost'' matching score file. - -@end table - -If you want to have one score file for the @samp{emacs} groups and -another for the @samp{comp} groups, while letting all other groups use -their own home score files: - -@lisp -(setq gnus-home-score-file - ;; @r{All groups that match the regexp @code{"\\.emacs"}} - '(("\\.emacs" "emacs.SCORE") - ;; @r{All the comp groups in one score file} - ("^comp" "comp.SCORE"))) -@end lisp - -@vindex gnus-home-adapt-file -@code{gnus-home-adapt-file} works exactly the same way as -@code{gnus-home-score-file}, but says what the home adaptive score file -is instead. All new adaptive file entries will go into the file -specified by this variable, and the same syntax is allowed. - -In addition to using @code{gnus-home-score-file} and -@code{gnus-home-adapt-file}, you can also use group parameters -(@pxref{Group Parameters}) and topic parameters (@pxref{Topic -Parameters}) to achieve much the same. Group and topic parameters take -precedence over this variable. - - -@node Followups To Yourself -@section Followups To Yourself - -Gnus offers two commands for picking out the @code{Message-ID} header in -the current buffer. Gnus will then add a score rule that scores using -this @code{Message-ID} on the @code{References} header of other -articles. This will, in effect, increase the score of all articles that -respond to the article in the current buffer. Quite useful if you want -to easily note when people answer what you've said. - -@table @code - -@item gnus-score-followup-article -@findex gnus-score-followup-article -This will add a score to articles that directly follow up your own -article. - -@item gnus-score-followup-thread -@findex gnus-score-followup-thread -This will add a score to all articles that appear in a thread ``below'' -your own article. -@end table - -@vindex message-sent-hook -These two functions are both primarily meant to be used in hooks like -@code{message-sent-hook}, like this: -@lisp -(add-hook 'message-sent-hook 'gnus-score-followup-thread) -@end lisp - - -If you look closely at your own @code{Message-ID}, you'll notice that -the first two or three characters are always the same. Here's two of -mine: - -@example - - -@end example - -So ``my'' ident on this machine is @samp{x6}. This can be -exploited---the following rule will raise the score on all followups to -myself: - -@lisp -("references" - ("" - 1000 nil r)) -@end lisp - -Whether it's the first two or first three characters that are ``yours'' -is system-dependent. - - -@node Scoring On Other Headers -@section Scoring On Other Headers -@cindex scoring on other headers - -Gnus is quite fast when scoring the ``traditional'' -headers---@samp{From}, @samp{Subject} and so on. However, scoring -other headers requires writing a @code{head} scoring rule, which means -that Gnus has to request every single article from the back end to find -matches. This takes a long time in big groups. - -@vindex gnus-inhibit-slow-scoring -You can inhibit this slow scoring on headers or body by setting the -variable @code{gnus-inhibit-slow-scoring}. If -@code{gnus-inhibit-slow-scoring} is regexp, slow scoring is inhibited if -the group matches the regexp. If it is @code{t}, slow scoring on it is -inhibited for all groups. - -Now, there's not much you can do about the slowness for news groups, but for -mail groups, you have greater control. In @ref{To From Newsgroups}, -it's explained in greater detail what this mechanism does, but here's -a cookbook example for @code{nnml} on how to allow scoring on the -@samp{To} and @samp{Cc} headers. - -Put the following in your @file{~/.gnus.el} file. - -@lisp -(setq gnus-extra-headers '(To Cc Newsgroups Keywords) - nnmail-extra-headers gnus-extra-headers) -@end lisp - -Restart Gnus and rebuild your @code{nnml} overview files with the -@kbd{M-x nnml-generate-nov-databases} command. This will take a long -time if you have much mail. - -Now you can score on @samp{To} and @samp{Cc} as ``extra headers'' like -so: @kbd{I e s p To RET RET}. - -See? Simple. - - -@node Scoring Tips -@section Scoring Tips -@cindex scoring tips - -@table @dfn - -@item Crossposts -@cindex crossposts -@cindex scoring crossposts -If you want to lower the score of crossposts, the line to match on is -the @code{Xref} header. -@lisp -("xref" (" talk.politics.misc:" -1000)) -@end lisp - -@item Multiple crossposts -If you want to lower the score of articles that have been crossposted to -more than, say, 3 groups: -@lisp -("xref" - ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" - -1000 nil r)) -@end lisp - -@item Matching on the body -This is generally not a very good idea---it takes a very long time. -Gnus actually has to fetch each individual article from the server. But -you might want to anyway, I guess. Even though there are three match -keys (@code{Head}, @code{Body} and @code{All}), you should choose one -and stick with it in each score file. If you use any two, each article -will be fetched @emph{twice}. If you want to match a bit on the -@code{Head} and a bit on the @code{Body}, just use @code{All} for all -the matches. - -@item Marking as read -You will probably want to mark articles that have scores below a certain -number as read. This is most easily achieved by putting the following -in your @file{all.SCORE} file: -@lisp -((mark -100)) -@end lisp -You may also consider doing something similar with @code{expunge}. - -@item Negated character classes -If you say stuff like @code{[^abcd]*}, you may get unexpected results. -That will match newlines, which might lead to, well, The Unknown. Say -@code{[^abcd\n]*} instead. -@end table - - -@node Reverse Scoring -@section Reverse Scoring -@cindex reverse scoring - -If you want to keep just articles that have @samp{Sex with Emacs} in the -subject header, and expunge all other articles, you could put something -like this in your score file: - -@lisp -(("subject" - ("Sex with Emacs" 2)) - (mark 1) - (expunge 1)) -@end lisp - -So, you raise all articles that match @samp{Sex with Emacs} and mark the -rest as read, and expunge them to boot. - - -@node Global Score Files -@section Global Score Files -@cindex global score files - -Sure, other newsreaders have ``global kill files''. These are usually -nothing more than a single kill file that applies to all groups, stored -in the user's home directory. Bah! Puny, weak newsreaders! - -What I'm talking about here are Global Score Files. Score files from -all over the world, from users everywhere, uniting all nations in one -big, happy score file union! Ange-score! New and untested! - -@vindex gnus-global-score-files -All you have to do to use other people's score files is to set the -@code{gnus-global-score-files} variable. One entry for each score file, -or each score file directory. Gnus will decide by itself what score -files are applicable to which group. - -To use the score file -@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and -all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory, -say this: - -@lisp -(setq gnus-global-score-files - '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE" - "/ftp@@ftp.some-where:/pub/score/")) -@end lisp - -@findex gnus-score-search-global-directories -@noindent -Simple, eh? Directory names must end with a @samp{/}. These -directories are typically scanned only once during each Gnus session. -If you feel the need to manually re-scan the remote directories, you can -use the @code{gnus-score-search-global-directories} command. - -Note that, at present, using this option will slow down group entry -somewhat. (That is---a lot.) - -If you want to start maintaining score files for other people to use, -just put your score file up for anonymous ftp and announce it to the -world. Become a retro-moderator! Participate in the retro-moderator -wars sure to ensue, where retro-moderators battle it out for the -sympathy of the people, luring them to use their score files on false -premises! Yay! The net is saved! - -Here are some tips for the would-be retro-moderator, off the top of my -head: - -@itemize @bullet - -@item -Articles heavily crossposted are probably junk. -@item -To lower a single inappropriate article, lower by @code{Message-ID}. -@item -Particularly brilliant authors can be raised on a permanent basis. -@item -Authors that repeatedly post off-charter for the group can safely be -lowered out of existence. -@item -Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest -articles completely. - -@item -Use expiring score entries to keep the size of the file down. You -should probably have a long expiry period, though, as some sites keep -old articles for a long time. -@end itemize - -@dots{} I wonder whether other newsreaders will support global score files -in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue -Wave, xrn and 1stReader are bound to implement scoring. Should we start -holding our breath yet? - - -@node Kill Files -@section Kill Files -@cindex kill files - -Gnus still supports those pesky old kill files. In fact, the kill file -entries can now be expiring, which is something I wrote before Daniel -Quinlan thought of doing score files, so I've left the code in there. - -In short, kill processing is a lot slower (and I do mean @emph{a lot}) -than score processing, so it might be a good idea to rewrite your kill -files into score files. - -Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any -forms into this file, which means that you can use kill files as some -sort of primitive hook function to be run on group entry, even though -that isn't a very good idea. - -Normal kill files look like this: - -@lisp -(gnus-kill "From" "Lars Ingebrigtsen") -(gnus-kill "Subject" "ding") -(gnus-expunge "X") -@end lisp - -This will mark every article written by me as read, and remove the -marked articles from the summary buffer. Very useful, you'll agree. - -Other programs use a totally different kill file syntax. If Gnus -encounters what looks like a @code{rn} kill file, it will take a stab at -interpreting it. - -Two summary functions for editing a @sc{gnus} kill file: - -@table @kbd - -@item M-k -@kindex M-k (Summary) -@findex gnus-summary-edit-local-kill -Edit this group's kill file (@code{gnus-summary-edit-local-kill}). - -@item M-K -@kindex M-K (Summary) -@findex gnus-summary-edit-global-kill -Edit the general kill file (@code{gnus-summary-edit-global-kill}). -@end table - -Two group mode functions for editing the kill files: - -@table @kbd - -@item M-k -@kindex M-k (Group) -@findex gnus-group-edit-local-kill -Edit this group's kill file (@code{gnus-group-edit-local-kill}). - -@item M-K -@kindex M-K (Group) -@findex gnus-group-edit-global-kill -Edit the general kill file (@code{gnus-group-edit-global-kill}). -@end table - -Kill file variables: - -@table @code -@item gnus-kill-file-name -@vindex gnus-kill-file-name -A kill file for the group @samp{soc.motss} is normally called -@file{soc.motss.KILL}. The suffix appended to the group name to get -this file name is detailed by the @code{gnus-kill-file-name} variable. -The ``global'' kill file (not in the score file sense of ``global'', of -course) is just called @file{KILL}. - -@vindex gnus-kill-save-kill-file -@item gnus-kill-save-kill-file -If this variable is non-@code{nil}, Gnus will save the -kill file after processing, which is necessary if you use expiring -kills. - -@item gnus-apply-kill-hook -@vindex gnus-apply-kill-hook -@findex gnus-apply-kill-file-unless-scored -@findex gnus-apply-kill-file -A hook called to apply kill files to a group. It is -@code{(gnus-apply-kill-file)} by default. If you want to ignore the -kill file if you have a score file for the same group, you can set this -hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want -kill files to be processed, you should set this variable to @code{nil}. - -@item gnus-kill-file-mode-hook -@vindex gnus-kill-file-mode-hook -A hook called in kill-file mode buffers. - -@end table - - -@node Converting Kill Files -@section Converting Kill Files -@cindex kill files -@cindex converting kill files - -If you have loads of old kill files, you may want to convert them into -score files. If they are ``regular'', you can use -the @file{gnus-kill-to-score.el} package; if not, you'll have to do it -by hand. - -The kill to score conversion package isn't included in Emacs by default. -You can fetch it from the contrib directory of the Gnus distribution or -from -@uref{http://heim.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}. - -If your old kill files are very complex---if they contain more -non-@code{gnus-kill} forms than not, you'll have to convert them by -hand. Or just let them be as they are. Gnus will still use them as -before. - - -@node Advanced Scoring -@section Advanced Scoring - -Scoring on Subjects and From headers is nice enough, but what if you're -really interested in what a person has to say only when she's talking -about a particular subject? Or what if you really don't want to -read what person A has to say when she's following up to person B, but -want to read what she says when she's following up to person C? - -By using advanced scoring rules you may create arbitrarily complex -scoring patterns. - -@menu -* Advanced Scoring Syntax:: A definition. -* Advanced Scoring Examples:: What they look like. -* Advanced Scoring Tips:: Getting the most out of it. -@end menu - - -@node Advanced Scoring Syntax -@subsection Advanced Scoring Syntax - -Ordinary scoring rules have a string as the first element in the rule. -Advanced scoring rules have a list as the first element. The second -element is the score to be applied if the first element evaluated to a -non-@code{nil} value. - -These lists may consist of three logical operators, one redirection -operator, and various match operators. - -Logical operators: - -@table @code -@item & -@itemx and -This logical operator will evaluate each of its arguments until it finds -one that evaluates to @code{false}, and then it'll stop. If all arguments -evaluate to @code{true} values, then this operator will return -@code{true}. - -@item | -@itemx or -This logical operator will evaluate each of its arguments until it finds -one that evaluates to @code{true}. If no arguments are @code{true}, -then this operator will return @code{false}. - -@item ! -@itemx not -@itemx ¬ -This logical operator only takes a single argument. It returns the -logical negation of the value of its argument. - -@end table - -There is an @dfn{indirection operator} that will make its arguments -apply to the ancestors of the current article being scored. For -instance, @code{1-} will make score rules apply to the parent of the -current article. @code{2-} will make score rules apply to the -grandparent of the current article. Alternatively, you can write -@code{^^}, where the number of @code{^}s (carets) says how far back into -the ancestry you want to go. - -Finally, we have the match operators. These are the ones that do the -real work. Match operators are header name strings followed by a match -and a match type. A typical match operator looks like @samp{("from" -"Lars Ingebrigtsen" s)}. The header names are the same as when using -simple scoring, and the match types are also the same. - - -@node Advanced Scoring Examples -@subsection Advanced Scoring Examples - -Please note that the following examples are score file rules. To -make a complete score file from them, surround them with another pair -of parentheses. - -Let's say you want to increase the score of articles written by Lars -when he's talking about Gnus: - -@example -@group -((& - ("from" "Lars Ingebrigtsen") - ("subject" "Gnus")) - 1000) -@end group -@end example - -Quite simple, huh? - -When he writes long articles, he sometimes has something nice to say: - -@example -((& - ("from" "Lars Ingebrigtsen") - (| - ("subject" "Gnus") - ("lines" 100 >))) - 1000) -@end example - -However, when he responds to things written by Reig Eigil Logge, you -really don't want to read what he's written: - -@example -((& - ("from" "Lars Ingebrigtsen") - (1- ("from" "Reig Eigil Logge"))) - -100000) -@end example - -Everybody that follows up Redmondo when he writes about disappearing -socks should have their scores raised, but only when they talk about -white socks. However, when Lars talks about socks, it's usually not -very interesting: - -@example -((& - (1- - (& - ("from" "redmondo@@.*no" r) - ("body" "disappearing.*socks" t))) - (! ("from" "Lars Ingebrigtsen")) - ("body" "white.*socks")) - 1000) -@end example - -Suppose you're reading a high volume group and you're only interested -in replies. The plan is to score down all articles that don't have -subject that begin with "Re:", "Fw:" or "Fwd:" and then score up all -parents of articles that have subjects that begin with reply marks. - -@example -((! ("subject" "re:\\|fwd?:" r)) - -200) -((1- ("subject" "re:\\|fwd?:" r)) - 200) -@end example - -The possibilities are endless. - -@node Advanced Scoring Tips -@subsection Advanced Scoring Tips - -The @code{&} and @code{|} logical operators do short-circuit logic. -That is, they stop processing their arguments when it's clear what the -result of the operation will be. For instance, if one of the arguments -of an @code{&} evaluates to @code{false}, there's no point in evaluating -the rest of the arguments. This means that you should put slow matches -(@samp{body}, @samp{header}) last and quick matches (@samp{from}, -@samp{subject}) first. - -The indirection arguments (@code{1-} and so on) will make their -arguments work on previous generations of the thread. If you say -something like: - -@example -... -(1- - (1- - ("from" "lars"))) -... -@end example - -Then that means ``score on the from header of the grandparent of the -current article''. An indirection is quite fast, but it's better to say: - -@example -(1- - (& - ("from" "Lars") - ("subject" "Gnus"))) -@end example - -than it is to say: - -@example -(& - (1- ("from" "Lars")) - (1- ("subject" "Gnus"))) -@end example - - -@node Score Decays -@section Score Decays -@cindex score decays -@cindex decays - -You may find that your scores have a tendency to grow without -bounds, especially if you're using adaptive scoring. If scores get too -big, they lose all meaning---they simply max out and it's difficult to -use them in any sensible way. - -@vindex gnus-decay-scores -@findex gnus-decay-score -@vindex gnus-decay-score-function -Gnus provides a mechanism for decaying scores to help with this problem. -When score files are loaded and @code{gnus-decay-scores} is -non-@code{nil}, Gnus will run the score files through the decaying -mechanism thereby lowering the scores of all non-permanent score rules. -If @code{gnus-decay-scores} is a regexp, only score files matching this -regexp are treated. E.g., you may set it to @samp{\\.ADAPT\\'} if only -@emph{adaptive} score files should be decayed. The decay itself if -performed by the @code{gnus-decay-score-function} function, which is -@code{gnus-decay-score} by default. Here's the definition of that -function: - -@lisp -(defun gnus-decay-score (score) - "Decay SCORE according to `gnus-score-decay-constant' -and `gnus-score-decay-scale'." - (let ((n (- score - (* (if (< score 0) -1 1) - (min (abs score) - (max gnus-score-decay-constant - (* (abs score) - gnus-score-decay-scale))))))) - (if (and (featurep 'xemacs) - ;; XEmacs's floor can handle only the floating point - ;; number below the half of the maximum integer. - (> (abs n) (lsh -1 -2))) - (string-to-number - (car (split-string (number-to-string n) "\\."))) - (floor n)))) -@end lisp - -@vindex gnus-score-decay-scale -@vindex gnus-score-decay-constant -@code{gnus-score-decay-constant} is 3 by default and -@code{gnus-score-decay-scale} is 0.05. This should cause the following: - -@enumerate -@item -Scores between -3 and 3 will be set to 0 when this function is called. - -@item -Scores with magnitudes between 3 and 60 will be shrunk by 3. - -@item -Scores with magnitudes greater than 60 will be shrunk by 5% of the -score. -@end enumerate - -If you don't like this decay function, write your own. It is called -with the score to be decayed as its only parameter, and it should return -the new score, which should be an integer. - -Gnus will try to decay scores once a day. If you haven't run Gnus for -four days, Gnus will decay the scores four times, for instance. - -@node Searching -@chapter Searching -@cindex searching - -FIXME: Add a brief overview of Gnus search capabilities. A brief -comparison of nnir, nnmairix, contrib/gnus-namazu would be nice -as well. - -This chapter describes tools for searching groups and servers for -articles matching a query and then retrieving those articles. Gnus -provides a simpler mechanism for searching through articles in a summary buffer -to find those matching a pattern. @xref{Searching for Articles}. - -@menu -* nnir:: Searching with various engines. -* nnmairix:: Searching with Mairix. -@end menu - -@node nnir -@section nnir -@cindex nnir - -This section describes how to use @code{nnir} to search for articles -within gnus. - -@menu -* What is nnir?:: What does @code{nnir} do? -* Basic Usage:: How to perform simple searches. -* Setting up nnir:: How to set up @code{nnir}. -@end menu - -@node What is nnir? -@subsection What is nnir? - -@code{nnir} is a Gnus interface to a number of tools for searching -through mail and news repositories. Different backends (like -@code{nnimap} and @code{nntp}) work with different tools (called -@dfn{engines} in @code{nnir} lingo), but all use the same basic search -interface. - -The @code{nnimap} and @code{gmane} search engines should work with no -configuration. Other engines require a local index that needs to be -created and maintained outside of Gnus. - - -@node Basic Usage -@subsection Basic Usage - -In the group buffer typing @kbd{G G} will search the group on the -current line by calling @code{gnus-group-make-nnir-group}. This prompts -for a query string, creates an ephemeral @code{nnir} group containing -the articles that match this query, and takes you to a summary buffer -showing these articles. Articles may then be read, moved and deleted -using the usual commands. - -The @code{nnir} group made in this way is an @code{ephemeral} group, -and some changes are not permanent: aside from reading, moving, and -deleting, you can't act on the original article. But there is an -alternative: you can @emph{warp} (i.e., jump) to the original group -for the article on the current line with @kbd{A W}, aka -@code{gnus-warp-to-article}. Even better, the function -@code{gnus-summary-refer-thread}, bound by default in summary buffers -to @kbd{A T}, will first warp to the original group before it works -its magic and includes all the articles in the thread. From here you -can read, move and delete articles, but also copy them, alter article -marks, whatever. Go nuts. - -You say you want to search more than just the group on the current line? -No problem: just process-mark the groups you want to search. You want -even more? Calling for an nnir search with the cursor on a topic heading -will search all the groups under that heading. - -Still not enough? OK, in the server buffer -@code{gnus-group-make-nnir-group} (now bound to @kbd{G}) will search all -groups from the server on the current line. Too much? Want to ignore -certain groups when searching, like spam groups? Just customize -@code{nnir-ignored-newsgroups}. - -One more thing: individual search engines may have special search -features. You can access these special features by giving a prefix-arg -to @code{gnus-group-make-nnir-group}. If you are searching multiple -groups with different search engines you will be prompted for the -special search features for each engine separately. - - -@node Setting up nnir -@subsection Setting up nnir - -To set up nnir you may need to do some prep work. Firstly, you may need -to configure the search engines you plan to use. Some of them, like -@code{imap} and @code{gmane}, need no special configuration. Others, -like @code{namazu} and @code{swish}, require configuration as described -below. Secondly, you need to associate a search engine with a server or -a backend. - -If you just want to use the @code{imap} engine to search @code{nnimap} -servers, and the @code{gmane} engine to search @code{gmane} then you -don't have to do anything. But you might want to read the details of the -query language anyway. - -@menu -* Associating Engines:: How to associate engines. -* The imap Engine:: Imap configuration and usage. -* The gmane Engine:: Gmane configuration and usage. -* The swish++ Engine:: Swish++ configuration and usage. -* The swish-e Engine:: Swish-e configuration and usage. -* The namazu Engine:: Namazu configuration and usage. -* The notmuch Engine:: Notmuch configuration and usage. -* The hyrex Engine:: Hyrex configuration and usage. -* Customizations:: User customizable settings. -@end menu - -@node Associating Engines -@subsubsection Associating Engines - - -When searching a group, @code{nnir} needs to know which search engine to -use. You can configure a given server to use a particular engine by -setting the server variable @code{nnir-search-engine} to the engine -name. For example to use the @code{namazu} engine to search the server -named @code{home} you can use - -@lisp -(setq gnus-secondary-select-methods - '((nnml "home" - (nnimap-address "localhost") - (nnir-search-engine namazu)))) -@end lisp - -Alternatively you might want to use a particular engine for all servers -with a given backend. For example, you might want to use the @code{imap} -engine for all servers using the @code{nnimap} backend. In this case you -can customize the variable @code{nnir-method-default-engines}. This is -an alist of pairs of the form @code{(backend . engine)}. By default this -variable is set to use the @code{imap} engine for all servers using the -@code{nnimap} backend, and the @code{gmane} backend for @code{nntp} -servers. (Don't worry, the @code{gmane} search engine won't actually try -to search non-gmane @code{nntp} servers.) But if you wanted to use -@code{namazu} for all your servers with an @code{nnimap} backend you -could change this to - -@lisp -'((nnimap . namazu) - (nntp . gmane)) -@end lisp - -@node The imap Engine -@subsubsection The imap Engine - -The @code{imap} engine requires no configuration. - -Queries using the @code{imap} engine follow a simple query language. -The search is always case-insensitive and supports the following -features (inspired by the Google search input language): - -@table @samp - -@item Boolean query operators -AND, OR, and NOT are supported, and parentheses can be used to control -operator precedence, e.g., (emacs OR xemacs) AND linux. Note that -operators must be written with all capital letters to be -recognized. Also preceding a term with a @minus{} sign is equivalent -to NOT term. - -@item Automatic AND queries -If you specify multiple words then they will be treated as an AND -expression intended to match all components. - -@item Phrase searches -If you wrap your query in double-quotes then it will be treated as a -literal string. - -@end table - -By default the whole message will be searched. The query can be limited -to a specific part of a message by using a prefix-arg. After inputting -the query this will prompt (with completion) for a message part. -Choices include ``Whole message'', ``Subject'', ``From'', and -``To''. Any unrecognized input is interpreted as a header name. For -example, typing @kbd{Message-ID} in response to this prompt will limit -the query to the Message-ID header. - -Finally selecting ``Imap'' will interpret the query as a raw -@acronym{IMAP} search query. The format of such queries can be found in -RFC3501. - -If you don't like the default of searching whole messages you can -customize @code{nnir-imap-default-search-key}. For example to use -@acronym{IMAP} queries by default - -@lisp -(setq nnir-imap-default-search-key "Imap") -@end lisp - -@node The gmane Engine -@subsubsection The gmane Engine - -The @code{gmane} engine requires no configuration. - -Gmane queries follow a simple query language: - -@table @samp -@item Boolean query operators -AND, OR, NOT (or AND NOT), and XOR are supported, and brackets can be -used to control operator precedence, e.g., (emacs OR xemacs) AND linux. -Note that operators must be written with all capital letters to be -recognized. - -@item Required and excluded terms -+ and @minus{} can be used to require or exclude terms, e.g., football -@minus{}american - -@item Unicode handling -The search engine converts all text to utf-8, so searching should work -in any language. - -@item Stopwords -Common English words (like 'the' and 'a') are ignored by default. You -can override this by prefixing such words with a + (e.g., +the) or -enclosing the word in quotes (e.g., "the"). - -@end table - -The query can be limited to articles by a specific author using a -prefix-arg. After inputting the query this will prompt for an author -name (or part of a name) to match. - -@node The swish++ Engine -@subsubsection The swish++ Engine - -FIXME: Say something more here. - -Documentation for swish++ may be found at the swish++ sourceforge page: -@uref{http://swishplusplus.sourceforge.net} - -@table @code - -@item nnir-swish++-program -The name of the swish++ executable. Defaults to @code{search} - -@item nnir-swish++-additional-switches -A list of strings to be given as additional arguments to -swish++. @code{nil} by default. - -@item nnir-swish++-remove-prefix -The prefix to remove from each file name returned by swish++ in order -to get a group name. By default this is @code{$HOME/Mail}. - -@end table - -@node The swish-e Engine -@subsubsection The swish-e Engine - -FIXME: Say something more here. - -Documentation for swish-e may be found at the swish-e homepage -@uref{http://swish-e.org} - -@table @code - -@item nnir-swish-e-program -The name of the swish-e search program. Defaults to @code{swish-e}. - -@item nnir-swish-e-additional-switches -A list of strings to be given as additional arguments to -swish-e. @code{nil} by default. - -@item nnir-swish-e-remove-prefix -The prefix to remove from each file name returned by swish-e in order -to get a group name. By default this is @code{$HOME/Mail}. - -@end table - -@node The namazu Engine -@subsubsection The namazu Engine - -Using the namazu engine requires creating and maintaining index files. -One directory should contain all the index files, and nnir must be told -where to find them by setting the @code{nnir-namazu-index-directory} -variable. - -To work correctly the @code{nnir-namazu-remove-prefix} variable must -also be correct. This is the prefix to remove from each file name -returned by Namazu in order to get a proper group name (albeit with `/' -instead of `.'). - -For example, suppose that Namazu returns file names such as -@samp{/home/john/Mail/mail/misc/42}. For this example, use the -following setting: @code{(setq nnir-namazu-remove-prefix -"/home/john/Mail/")} Note the trailing slash. Removing this prefix from -the directory gives @samp{mail/misc/42}. @code{nnir} knows to remove -the @samp{/42} and to replace @samp{/} with @samp{.} to arrive at the -correct group name @samp{mail.misc}. - -Extra switches may be passed to the namazu search command by setting the -variable @code{nnir-namazu-additional-switches}. It is particularly -important not to pass any any switches to namazu that will change the -output format. Good switches to use include `--sort', `--ascending', -`--early' and `--late'. Refer to the Namazu documentation for further -information on valid switches. - -Mail must first be indexed with the `mknmz' program. Read the documentation -for namazu to create a configuration file. Here is an example: - -@cartouche -@example - package conf; # Don't remove this line! - - # Paths which will not be indexed. Don't use `^' or `$' anchors. - $EXCLUDE_PATH = "spam|sent"; - - # Header fields which should be searchable. case-insensitive - $REMAIN_HEADER = "from|date|message-id|subject"; - - # Searchable fields. case-insensitive - $SEARCH_FIELD = "from|date|message-id|subject"; - - # The max length of a word. - $WORD_LENG_MAX = 128; - - # The max length of a field. - $MAX_FIELD_LENGTH = 256; -@end example -@end cartouche - -For this example, mail is stored in the directories @samp{~/Mail/mail/}, -@samp{~/Mail/lists/} and @samp{~/Mail/archive/}, so to index them go to -the index directory set in @code{nnir-namazu-index-directory} and issue -the following command: - -@example -mknmz --mailnews ~/Mail/archive/ ~/Mail/mail/ ~/Mail/lists/ -@end example - -For maximum searching efficiency you might want to have a cron job run -this command periodically, say every four hours. - - -@node The notmuch Engine -@subsubsection The notmuch Engine - -@table @code -@item nnir-notmuch-program -The name of the notmuch search executable. Defaults to -@samp{notmuch}. - -@item nnir-notmuch-additional-switches -A list of strings, to be given as additional arguments to notmuch. - -@item nnir-notmuch-remove-prefix -The prefix to remove from each file name returned by notmuch in order -to get a group name (albeit with @samp{/} instead of @samp{.}). This -is a regular expression. - -@end table - - -@node The hyrex Engine -@subsubsection The hyrex Engine -This engine is obsolete. - -@node Customizations -@subsubsection Customizations - -@table @code - -@item nnir-method-default-engines -Alist of pairs of server backends and search engines. The default -associations are -@example -(nnimap . imap) -(nntp . gmane) -@end example - -@item nnir-ignored-newsgroups -A regexp to match newsgroups in the active file that should be skipped -when searching all groups on a server. - -@item nnir-summary-line-format -The format specification to be used for lines in an nnir summary buffer. -All the items from `gnus-summary-line-format' are available, along with -three items unique to nnir summary buffers: - -@example -%Z Search retrieval score value (integer) -%G Article original full group name (string) -%g Article original short group name (string) -@end example - -If @code{nil} (the default) this will use @code{gnus-summary-line-format}. - -@item nnir-retrieve-headers-override-function -If non-@code{nil}, a function that retrieves article headers rather than using -the gnus built-in function. This function takes an article list and -group as arguments and populates the `nntp-server-buffer' with the -retrieved headers. It should then return either 'nov or 'headers -indicating the retrieved header format. Failure to retrieve headers -should return @code{nil}. - -If this variable is @code{nil}, or if the provided function returns -@code{nil} for a search result, @code{gnus-retrieve-headers} will be -called instead." - - -@end table - - -@node nnmairix -@section nnmairix - -@cindex mairix -@cindex nnmairix -This paragraph describes how to set up mairix and the back end -@code{nnmairix} for indexing and searching your mail from within -Gnus. Additionally, you can create permanent ``smart'' groups which are -bound to mairix searches and are automatically updated. - -@menu -* About mairix:: About the mairix mail search engine -* nnmairix requirements:: What you will need for using nnmairix -* What nnmairix does:: What does nnmairix actually do? -* Setting up mairix:: Set up your mairix installation -* Configuring nnmairix:: Set up the nnmairix back end -* nnmairix keyboard shortcuts:: List of available keyboard shortcuts -* Propagating marks:: How to propagate marks from nnmairix groups -* nnmairix tips and tricks:: Some tips, tricks and examples -* nnmairix caveats:: Some more stuff you might want to know -@end menu - -@c FIXME: The markup in this section might need improvement. -@c E.g., adding @samp, @var, @file, @command, etc. -@c Cf. (info "(texinfo)Indicating") - -@node About mairix -@subsection About mairix - -Mairix is a tool for indexing and searching words in locally stored -mail. It was written by Richard Curnow and is licensed under the -GPL@. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can -be found at -@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} - -Though mairix might not be as flexible as other search tools like -swish++ or namazu, which you can use via the @code{nnir} back end, it -has the prime advantage of being incredibly fast. On current systems, it -can easily search through headers and message bodies of thousands and -thousands of mails in well under a second. Building the database -necessary for searching might take a minute or two, but only has to be -done once fully. Afterwards, the updates are done incrementally and -therefore are really fast, too. Additionally, mairix is very easy to set -up. - -For maximum speed though, mairix should be used with mails stored in -@code{Maildir} or @code{MH} format (this includes the @code{nnml} back -end), although it also works with mbox. Mairix presents the search -results by populating a @emph{virtual} maildir/MH folder with symlinks -which point to the ``real'' message files (if mbox is used, copies are -made). Since mairix already presents search results in such a virtual -mail folder, it is very well suited for using it as an external program -for creating @emph{smart} mail folders, which represent certain mail -searches. - -@node nnmairix requirements -@subsection nnmairix requirements - -Mairix searches local mail---that means, mairix absolutely must have -direct access to your mail folders. If your mail resides on another -server (e.g., an @acronym{IMAP} server) and you happen to have shell -access, @code{nnmairix} supports running mairix remotely, e.g., via ssh. - -Additionally, @code{nnmairix} only supports the following Gnus back -ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use -one of these back ends for using @code{nnmairix}. Other back ends, like -@code{nnmbox}, @code{nnfolder} or @code{nnmh}, won't work. - -If you absolutely must use mbox and still want to use @code{nnmairix}, -you can set up a local @acronym{IMAP} server, which you then access via -@code{nnimap}. This is a rather massive setup for accessing some mbox -files, so just change to MH or Maildir already... However, if you're -really, really passionate about using mbox, you might want to look into -the package @file{mairix.el}, which comes with Emacs 23. - -@node What nnmairix does -@subsection What nnmairix does - -The back end @code{nnmairix} enables you to call mairix from within Gnus, -either to query mairix with a search term or to update the -database. While visiting a message in the summary buffer, you can use -several pre-defined shortcuts for calling mairix, e.g., to quickly -search for all mails from the sender of the current message or to -display the whole thread associated with the message, even if the -mails are in different folders. - -Additionally, you can create permanent @code{nnmairix} groups which are bound -to certain mairix searches. This way, you can easily create a group -containing mails from a certain sender, with a certain subject line or -even for one specific thread based on the Message-ID@. If you check for -new mail in these folders (e.g., by pressing @kbd{g} or @kbd{M-g}), they -automatically update themselves by calling mairix. - -You might ask why you need @code{nnmairix} at all, since mairix already -creates the group, populates it with links to the mails so that you can -then access it with Gnus, right? Well, this @emph{might} work, but often -does not---at least not without problems. Most probably you will get -strange article counts, and sometimes you might see mails which Gnus -claims have already been canceled and are inaccessible. This is due to -the fact that Gnus isn't really amused when things are happening behind -its back. Another problem can be the mail back end itself, e.g., if you -use mairix with an @acronym{IMAP} server (I had Dovecot complaining -about corrupt index files when mairix changed the contents of the search -group). Using @code{nnmairix} should circumvent these problems. - -@code{nnmairix} is not really a mail back end---it's actually more like -a wrapper, sitting between a ``real'' mail back end where mairix stores -the searches and the Gnus front end. You can choose between three -different mail back ends for the mairix folders: @code{nnml}, -@code{nnmaildir} or @code{nnimap}. @code{nnmairix} will call the mairix -binary so that the search results are stored in folders named -@code{zz_mairix--} on this mail back end, but it will -present these folders in the Gnus front end only with @code{}. -You can use an existing mail back end where you already store your mail, -but if you're uncomfortable with @code{nnmairix} creating new mail -groups alongside your other mail, you can also create, e.g., a new -@code{nnmaildir} or @code{nnml} server exclusively for mairix, but then -make sure those servers do not accidentally receive your new mail -(@pxref{nnmairix caveats}). A special case exists if you want to use -mairix remotely on an IMAP server with @code{nnimap}---here the mairix -folders and your other mail must be on the same @code{nnimap} back end. - -@node Setting up mairix -@subsection Setting up mairix - -First: create a backup of your mail folders (@pxref{nnmairix caveats}). - -Setting up mairix is easy: simply create a @file{.mairixrc} file with -(at least) the following entries: - -@example -# Your Maildir/MH base folder -base=~/Maildir -@end example - -This is the base folder for your mails. All the following directories -are relative to this base folder. If you want to use @code{nnmairix} -with @code{nnimap}, this base directory has to point to the mail -directory where the @acronym{IMAP} server stores the mail folders! - -@example -maildir= ... your maildir folders which should be indexed ... -mh= ... your nnml/mh folders which should be indexed ... -mbox = ... your mbox files which should be indexed ... -@end example - -This specifies all your mail folders and mbox files (relative to the -base directory!) you want to index with mairix. Note that the -@code{nnml} back end saves mails in MH format, so you have to put those -directories in the @code{mh} line. See the example at the end of this -section and mairixrc's man-page for further details. - -@example -omit=zz_mairix-* -@end example - -@vindex nnmairix-group-prefix -This should make sure that you don't accidentally index the mairix -search results. You can change the prefix of these folders with the -variable @code{nnmairix-group-prefix}. - -@example -mformat= ... 'maildir' or 'mh' ... -database= ... location of database file ... -@end example - -The @code{format} setting specifies the output format for the mairix -search folder. Set this to @code{mh} if you want to access search results -with @code{nnml}. Otherwise choose @code{maildir}. - -To summarize, here is my shortened @file{.mairixrc} file as an example: - -@example -base=~/Maildir -maildir=.personal:.work:.logcheck:.sent -mh=../Mail/nnml/*... -mbox=../mboxmail/mailarchive_year* -mformat=maildir -omit=zz_mairix-* -database=~/.mairixdatabase -@end example - -In this case, the base directory is @file{~/Maildir}, where all my Maildir -folders are stored. As you can see, the folders are separated by -colons. If you wonder why every folder begins with a dot: this is -because I use Dovecot as @acronym{IMAP} server, which again uses -@code{Maildir++} folders. For testing nnmairix, I also have some -@code{nnml} mail, which is saved in @file{~/Mail/nnml}. Since this has -to be specified relative to the @code{base} directory, the @code{../Mail} -notation is needed. Note that the line ends in @code{*...}, which means -to recursively scan all files under this directory. Without the three -dots, the wildcard @code{*} will not work recursively. I also have some -old mbox files with archived mail lying around in @file{~/mboxmail}. -The other lines should be obvious. - -See the man page for @code{mairixrc} for details and further options, -especially regarding wildcard usage, which may be a little different -than you are used to. - -Now simply call @code{mairix} to create the index for the first time. -Note that this may take a few minutes, but every following index will do -the updates incrementally and hence is very fast. - -@node Configuring nnmairix -@subsection Configuring nnmairix - -In group mode, type @kbd{G b c} -(@code{nnmairix-create-server-and-default-group}). This will ask you for all -necessary information and create a @code{nnmairix} server as a foreign -server. You will have to specify the following: - -@itemize @bullet - -@item -The @strong{name} of the @code{nnmairix} server---choose whatever you -want. - -@item -The name of the @strong{back end server} where mairix should store its -searches. This must be a full server name, like @code{nnml:mymail}. -Just hit @kbd{TAB} to see the available servers. Currently, servers -which are accessed through @code{nnmaildir}, @code{nnimap} and -@code{nnml} are supported. As explained above, for locally stored -mails, this can be an existing server where you store your mails. -However, you can also create, e.g., a new @code{nnmaildir} or @code{nnml} -server exclusively for @code{nnmairix} in your secondary select methods -(@pxref{Finding the News}). If you use a secondary @code{nnml} server -just for mairix, make sure that you explicitly set the server variable -@code{nnml-get-new-mail} to @code{nil}, or you might lose mail -(@pxref{nnmairix caveats}). If you want to use mairix remotely on an -@acronym{IMAP} server, you have to choose the corresponding -@code{nnimap} server here. - -@item -@vindex nnmairix-mairix-search-options -The @strong{command} to call the mairix binary. This will usually just -be @code{mairix}, but you can also choose something like @code{ssh -SERVER mairix} if you want to call mairix remotely, e.g., on your -@acronym{IMAP} server. If you want to add some default options to -mairix, you could do this here, but better use the variable -@code{nnmairix-mairix-search-options} instead. - -@item -The name of the @strong{default search group}. This will be the group -where all temporary mairix searches are stored, i.e., all searches which -are not bound to permanent @code{nnmairix} groups. Choose whatever you -like. - -@item -If the mail back end is @code{nnimap} or @code{nnmaildir}, you will be -asked if you work with @strong{Maildir++}, i.e., with hidden maildir -folders (=beginning with a dot). For example, you have to answer -@samp{yes} here if you work with the Dovecot @acronym{IMAP} -server. Otherwise, you should answer @samp{no} here. - -@end itemize - -@node nnmairix keyboard shortcuts -@subsection nnmairix keyboard shortcuts - -In group mode: - -@table @kbd - -@item G b c -@kindex G b c (Group) -@findex nnmairix-create-server-and-default-group -Creates @code{nnmairix} server and default search group for this server -(@code{nnmairix-create-server-and-default-group}). You should have done -this by now (@pxref{Configuring nnmairix}). - -@item G b s -@kindex G b s (Group) -@findex nnmairix-search -Prompts for query which is then sent to the mairix binary. Search -results are put into the default search group which is automatically -displayed (@code{nnmairix-search}). - -@item G b m -@kindex G b m (Group) -@findex nnmairix-widget-search -Allows you to create a mairix search or a permanent group more -comfortably using graphical widgets, similar to a customization -group. Just try it to see how it works (@code{nnmairix-widget-search}). - -@item G b i -@kindex G b i (Group) -@findex nnmairix-search-interactive -Another command for creating a mairix query more comfortably, but uses -only the minibuffer (@code{nnmairix-search-interactive}). - -@item G b g -@kindex G b g (Group) -@findex nnmairix-create-search-group -Creates a permanent group which is associated with a search query -(@code{nnmairix-create-search-group}). The @code{nnmairix} back end -automatically calls mairix when you update this group with @kbd{g} or -@kbd{M-g}. - -@item G b q -@kindex G b q (Group) -@findex nnmairix-group-change-query-this-group -Changes the search query for the @code{nnmairix} group under cursor -(@code{nnmairix-group-change-query-this-group}). - -@item G b t -@kindex G b t (Group) -@findex nnmairix-group-toggle-threads-this-group -Toggles the 'threads' parameter for the @code{nnmairix} group under cursor, -i.e., if you want see the whole threads of the found messages -(@code{nnmairix-group-toggle-threads-this-group}). - -@item G b u -@kindex G b u (Group) -@findex nnmairix-update-database -@vindex nnmairix-mairix-update-options -Calls mairix binary for updating the database -(@code{nnmairix-update-database}). The default parameters are @code{-F} -and @code{-Q} for making this as fast as possible (see variable -@code{nnmairix-mairix-update-options} for defining these default -options). - -@item G b r -@kindex G b r (Group) -@findex nnmairix-group-toggle-readmarks-this-group -Keep articles in this @code{nnmairix} group always read or unread, or leave the -marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}). - -@item G b d -@kindex G b d (Group) -@findex nnmairix-group-delete-recreate-this-group -Recreate @code{nnmairix} group on the ``real'' mail back end -(@code{nnmairix-group-delete-recreate-this-group}). You can do this if -you always get wrong article counts with a @code{nnmairix} group. - -@item G b a -@kindex G b a (Group) -@findex nnmairix-group-toggle-allowfast-this-group -Toggles the @code{allow-fast} parameters for group under cursor -(@code{nnmairix-group-toggle-allowfast-this-group}). The default -behavior of @code{nnmairix} is to do a mairix search every time you -update or enter the group. With the @code{allow-fast} parameter set, -mairix will only be called when you explicitly update the group, but not -upon entering. This makes entering the group faster, but it may also -lead to dangling symlinks if something changed between updating and -entering the group which is not yet in the mairix database. - -@item G b p -@kindex G b p (Group) -@findex nnmairix-group-toggle-propmarks-this-group -Toggle marks propagation for this group -(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating -marks}). - -@item G b o -@kindex G b o (Group) -@findex nnmairix-propagate-marks -Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when -@code{nnmairix-propagate-marks-upon-close} is set to @code{nil}. - -@end table - -In summary mode: - -@table @kbd - -@item $ m -@kindex $ m (Summary) -@findex nnmairix-widget-search-from-this-article -Allows you to create a mairix query or group based on the current -message using graphical widgets (same as @code{nnmairix-widget-search}) -(@code{nnmairix-widget-search-from-this-article}). - -@item $ g -@kindex $ g (Summary) -@findex nnmairix-create-search-group-from-message -Interactively creates a new search group with query based on the current -message, but uses the minibuffer instead of graphical widgets -(@code{nnmairix-create-search-group-from-message}). - -@item $ t -@kindex $ t (Summary) -@findex nnmairix-search-thread-this-article -Searches thread for the current article -(@code{nnmairix-search-thread-this-article}). This is effectively a -shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the -current article and enabled threads. - -@item $ f -@kindex $ f (Summary) -@findex nnmairix-search-from-this-article -Searches all messages from sender of the current article -(@code{nnmairix-search-from-this-article}). This is a shortcut for -calling @code{nnmairix-search} with @samp{f:From}. - -@item $ o -@kindex $ o (Summary) -@findex nnmairix-goto-original-article -(Only in @code{nnmairix} groups!) Tries determine the group this article -originally came from and displays the article in this group, so that, -e.g., replying to this article the correct posting styles/group -parameters are applied (@code{nnmairix-goto-original-article}). This -function will use the registry if available, but can also parse the -article file name as a fallback method. - -@item $ u -@kindex $ u (Summary) -@findex nnmairix-remove-tick-mark-original-article -Remove possibly existing tick mark from original article -(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix -tips and tricks}). - -@end table - -@node Propagating marks -@subsection Propagating marks - -First of: you really need a patched mairix binary for using the marks -propagation feature efficiently. Otherwise, you would have to update -the mairix database all the time. You can get the patch at - -@uref{http://www.randomsample.de/mairix-maildir-patch.tar} - -You need the mairix v0.21 source code for this patch; everything else -is explained in the accompanied readme file. If you don't want to use -marks propagation, you don't have to apply these patches, but they also -fix some annoyances regarding changing maildir flags, so it might still -be useful to you. - -With the patched mairix binary, you can use @code{nnmairix} as an -alternative to mail splitting (@pxref{Fancy Mail Splitting}). For -example, instead of splitting all mails from @samp{david@@foobar.com} -into a group, you can simply create a search group with the query -@samp{f:david@@foobar.com}. This is actually what ``smart folders'' are -all about: simply put everything in one mail folder and dynamically -create searches instead of splitting. This is more flexible, since you -can dynamically change your folders any time you want to. This also -implies that you will usually read your mails in the @code{nnmairix} -groups instead of your ``real'' mail groups. - -There is one problem, though: say you got a new mail from -@samp{david@@foobar.com}; it will now show up in two groups, the -``real'' group (your INBOX, for example) and in the @code{nnmairix} -search group (provided you have updated the mairix database). Now you -enter the @code{nnmairix} group and read the mail. The mail will be -marked as read, but only in the @code{nnmairix} group---in the ``real'' -mail group it will be still shown as unread. - -You could now catch up the mail group (@pxref{Group Data}), but this is -tedious and error prone, since you may overlook mails you don't have -created @code{nnmairix} groups for. Of course, you could first use -@code{nnmairix-goto-original-article} (@pxref{nnmairix keyboard -shortcuts}) and then read the mail in the original group, but that's -even more cumbersome. - -Clearly, the easiest way would be if marks could somehow be -automatically set for the original article. This is exactly what -@emph{marks propagation} is about. - -Marks propagation is inactive by default. You can activate it for a -certain @code{nnmairix} group with -@code{nnmairix-group-toggle-propmarks-this-group} (bound to @kbd{G b -p}). This function will warn you if you try to use it with your default -search group; the reason is that the default search group is used for -temporary searches, and it's easy to accidentally propagate marks from -this group. However, you can ignore this warning if you really want to. - -With marks propagation enabled, all the marks you set in a @code{nnmairix} -group should now be propagated to the original article. For example, -you can now tick an article (by default with @kbd{!}) and this mark should -magically be set for the original article, too. - -A few more remarks which you may or may not want to know: - -@vindex nnmairix-propagate-marks-upon-close -Marks will not be set immediately, but only upon closing a group. This -not only makes marks propagation faster, it also avoids problems with -dangling symlinks when dealing with maildir files (since changing flags -will change the file name). You can also control when to propagate marks -via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for -details). - -Obviously, @code{nnmairix} will have to look up the original group for every -article you want to set marks for. If available, @code{nnmairix} will first -use the registry for determining the original group. The registry is very -fast, hence you should really, really enable the registry when using -marks propagation. If you don't have to worry about RAM and disc space, -set @code{gnus-registry-max-entries} to a large enough value; to be on -the safe side, choose roughly the amount of mails you index with mairix. - -@vindex nnmairix-only-use-registry -If you don't want to use the registry or the registry hasn't seen the -original article yet, @code{nnmairix} will use an additional mairix -search for determining the file name of the article. This, of course, is -way slower than the registry---if you set hundreds or even thousands of -marks this way, it might take some time. You can avoid this situation by -setting @code{nnmairix-only-use-registry} to @code{t}. - -Maybe you also want to propagate marks the other way round, i.e., if you -tick an article in a "real" mail group, you'd like to have the same -article in a @code{nnmairix} group ticked, too. For several good -reasons, this can only be done efficiently if you use maildir. To -immediately contradict myself, let me mention that it WON'T work with -@code{nnmaildir}, since @code{nnmaildir} stores the marks externally and -not in the file name. Therefore, propagating marks to @code{nnmairix} -groups will usually only work if you use an IMAP server which uses -maildir as its file format. - -@vindex nnmairix-propagate-marks-to-nnmairix-groups -If you work with this setup, just set -@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t} and see what -happens. If you don't like what you see, just set it to @code{nil} again. -One problem might be that you get a wrong number of unread articles; this -usually happens when you delete or expire articles in the original -groups. When this happens, you can recreate the @code{nnmairix} group on -the back end using @kbd{G b d}. - -@node nnmairix tips and tricks -@subsection nnmairix tips and tricks - -@itemize -@item -Checking Mail - -@findex nnmairix-update-groups -I put all my important mail groups at group level 1. The mairix groups -have group level 5, so they do not get checked at start up (@pxref{Group -Levels}). - -I use the following to check for mails: - -@lisp -(defun my-check-mail-mairix-update (level) - (interactive "P") - ;; if no prefix given, set level=1 - (gnus-group-get-new-news (or level 1)) - (nnmairix-update-groups "mairixsearch" t t) - (gnus-group-list-groups)) - -(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update) -@end lisp - -Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix} -server. See the doc string for @code{nnmairix-update-groups} for -details. - -@item -Example: search group for ticked articles - -For example, you can create a group for all ticked articles, where the -articles always stay unread: - -Hit @kbd{G b g}, enter group name (e.g., @samp{important}), use -@samp{F:f} as query and do not include threads. - -Now activate marks propagation for this group by using @kbd{G b p}. Then -activate the always-unread feature by using @kbd{G b r} twice. - -So far so good---but how do you remove the tick marks in the @code{nnmairix} -group? There are two options: You may simply use -@code{nnmairix-remove-tick-mark-original-article} (bound to @kbd{$ u}) to remove -tick marks from the original article. The other possibility is to set -@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t}, but see the above -comments about this option. If it works for you, the tick marks should -also exist in the @code{nnmairix} group and you can remove them as usual, -e.g., by marking an article as read. - -When you have removed a tick mark from the original article, this -article should vanish from the @code{nnmairix} group after you have updated the -mairix database and updated the group. Fortunately, there is a function -for doing exactly that: @code{nnmairix-update-groups}. See the previous code -snippet and the doc string for details. - -@item -Dealing with auto-subscription of mail groups - -As described before, all @code{nnmairix} groups are in fact stored on -the mail back end in the form @samp{zz_mairix--}. You can -see them when you enter the back end server in the server buffer. You -should not subscribe these groups! Unfortunately, these groups will -usually get @emph{auto-subscribed} when you use @code{nnmaildir} or -@code{nnml}, i.e., you will suddenly see groups of the form -@samp{zz_mairix*} pop up in your group buffer. If this happens to you, -simply kill these groups with C-k. For avoiding this, turn off -auto-subscription completely by setting the variable -@code{gnus-auto-subscribed-groups} to @code{nil} (@pxref{Filtering New -Groups}), or if you like to keep this feature use the following kludge -for turning it off for all groups beginning with @samp{zz_}: - -@lisp -(setq gnus-auto-subscribed-groups - "^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*") -@end lisp - -@end itemize - -@node nnmairix caveats -@subsection nnmairix caveats - -@itemize -@item -You can create a secondary @code{nnml} server just for nnmairix, but then -you have to explicitly set the corresponding server variable -@code{nnml-get-new-mail} to @code{nil}. Otherwise, new mail might get -put into this secondary server (and would never show up again). Here's -an example server definition: - -@lisp -(nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil)) -@end lisp - -(The @code{nnmaildir} back end also has a server variable -@code{get-new-mail}, but its default value is @code{nil}, so you don't -have to explicitly set it if you use a @code{nnmaildir} server just for -mairix.) - -@item -If you use the Gnus registry: don't use the registry with -@code{nnmairix} groups (put them in -@code{gnus-registry-unfollowed-groups}; this is the default). Be -@emph{extra careful} if you use -@code{gnus-registry-split-fancy-with-parent}; mails which are split -into @code{nnmairix} groups are usually gone for good as soon as you -check the group for new mail (yes, it has happened to me...). - -@item -Therefore: @emph{Never ever} put ``real'' mails into @code{nnmairix} -groups (you shouldn't be able to, anyway). - -@item -If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize -@code{nnmairix} groups (though I have no idea what happens if you do). - -@item -mairix does only support us-ascii characters. - -@item -@code{nnmairix} uses a rather brute force method to force Gnus to -completely reread the group on the mail back end after mairix was -called---it simply deletes and re-creates the group on the mail -back end. So far, this has worked for me without any problems, and I -don't see how @code{nnmairix} could delete other mail groups than its -own, but anyway: you really should have a backup of your mail -folders. - -@item -All necessary information is stored in the group parameters -(@pxref{Group Parameters}). This has the advantage that no active file -is needed, but also implies that when you kill a @code{nnmairix} group, -it is gone for good. - -@item -@findex nnmairix-purge-old-groups -If you create and kill a lot of @code{nnmairix} groups, the -``zz_mairix-*'' groups will accumulate on the mail back end server. To -delete old groups which are no longer needed, call -@code{nnmairix-purge-old-groups}. Note that this assumes that you don't -save any ``real'' mail in folders of the form -@code{zz_mairix--}. You can change the prefix of -@code{nnmairix} groups by changing the variable -@code{nnmairix-group-prefix}. - -@item -The following only applies if you @emph{don't} use the mentioned patch -for mairix (@pxref{Propagating marks}): - -A problem can occur when using @code{nnmairix} with maildir folders and -comes with the fact that maildir stores mail flags like @samp{Seen} or -@samp{Replied} by appending chars @samp{S} and @samp{R} to the message -file name, respectively. This implies that currently you would have to -update the mairix database not only when new mail arrives, but also when -mail flags are changing. The same applies to new mails which are indexed -while they are still in the @samp{new} folder but then get moved to -@samp{cur} when Gnus has seen the mail. If you don't update the database -after this has happened, a mairix query can lead to symlinks pointing to -non-existing files. In Gnus, these messages will usually appear with -``(none)'' entries in the header and can't be accessed. If this happens -to you, using @kbd{G b u} and updating the group will usually fix this. - -@end itemize - -@iftex -@iflatex -@chapter Message -@include message.texi -@chapter Emacs MIME -@include emacs-mime.texi -@chapter Sieve -@include sieve.texi -@chapter EasyPG -@include epa.texi -@chapter SASL -@include sasl.texi -@end iflatex -@end iftex - -@node Various -@chapter Various - -@menu -* Process/Prefix:: A convention used by many treatment commands. -* Interactive:: Making Gnus ask you many questions. -* Symbolic Prefixes:: How to supply some Gnus functions with options. -* Formatting Variables:: You can specify what buffers should look like. -* Window Layout:: Configuring the Gnus buffer windows. -* Faces and Fonts:: How to change how faces look. -* Mode Lines:: Displaying information in the mode lines. -* Highlighting and Menus:: Making buffers look all nice and cozy. -* Daemons:: Gnus can do things behind your back. -* Undo:: Some actions can be undone. -* Predicate Specifiers:: Specifying predicates. -* Moderation:: What to do if you're a moderator. -* Fetching a Group:: Starting Gnus just to read a group. -* Image Enhancements:: Modern versions of Emacs/XEmacs can display images. -* Fuzzy Matching:: What's the big fuzz? -* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. -* Spam Package:: A package for filtering and processing spam. -* The Gnus Registry:: A package for tracking messages by Message-ID. -* Other modes:: Interaction with other modes. -* Various Various:: Things that are really various. -@end menu - - -@node Process/Prefix -@section Process/Prefix -@cindex process/prefix convention - -Many functions, among them functions for moving, decoding and saving -articles, use what is known as the @dfn{Process/Prefix convention}. - -This is a method for figuring out what articles the user wants the -command to be performed on. - -It goes like this: - -If the numeric prefix is N, perform the operation on the next N -articles, starting with the current one. If the numeric prefix is -negative, perform the operation on the previous N articles, starting -with the current one. - -@vindex transient-mark-mode -If @code{transient-mark-mode} in non-@code{nil} and the region is -active, all articles in the region will be worked upon. - -If there is no numeric prefix, but some articles are marked with the -process mark, perform the operation on the articles marked with -the process mark. - -If there is neither a numeric prefix nor any articles marked with the -process mark, just perform the operation on the current article. - -Quite simple, really, but it needs to be made clear so that surprises -are avoided. - -Commands that react to the process mark will push the current list of -process marked articles onto a stack and will then clear all process -marked articles. You can restore the previous configuration with the -@kbd{M P y} command (@pxref{Setting Process Marks}). - -@vindex gnus-summary-goto-unread -One thing that seems to shock & horrify lots of people is that, for -instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}. -Since each @kbd{d} (which marks the current article as read) by default -goes to the next unread article after marking, this means that @kbd{3 d} -will mark the next three unread articles as read, no matter what the -summary buffer looks like. Set @code{gnus-summary-goto-unread} to -@code{nil} for a more straightforward action. - -Many commands do not use the process/prefix convention. All commands -that do explicitly say so in this manual. To apply the process/prefix -convention to commands that do not use it, you can use the @kbd{M-&} -command. For instance, to mark all the articles in the group as -expirable, you could say @kbd{M P b M-& E}. - - -@node Interactive -@section Interactive -@cindex interaction - -@table @code - -@item gnus-novice-user -@vindex gnus-novice-user -If this variable is non-@code{nil}, you are either a newcomer to the -World of Usenet, or you are very cautious, which is a nice thing to be, -really. You will be given questions of the type ``Are you sure you want -to do this?'' before doing anything dangerous. This is @code{t} by -default. - -@item gnus-expert-user -@vindex gnus-expert-user -If this variable is non-@code{nil}, you will seldom be asked any -questions by Gnus. It will simply assume you know what you're doing, -no matter how strange. For example, quitting Gnus, exiting a group -without an update, catching up with a group, deleting expired -articles, and replying by mail to a news message will not require -confirmation. - -@item gnus-interactive-catchup -@vindex gnus-interactive-catchup -Require confirmation before catching up a group if non-@code{nil}. It -is @code{t} by default. - -@item gnus-interactive-exit -@vindex gnus-interactive-exit -If non-@code{nil}, require a confirmation when exiting Gnus. If -@code{quiet}, update any active summary buffers automatically without -querying. The default value is @code{t}. -@end table - - -@node Symbolic Prefixes -@section Symbolic Prefixes -@cindex symbolic prefixes - -Quite a lot of Emacs commands react to the (numeric) prefix. For -instance, @kbd{C-u 4 C-f} moves point four characters forward, and -@kbd{C-u 9 0 0 I s s p} adds a permanent @code{Subject} substring score -rule of 900 to the current article. - -This is all nice and well, but what if you want to give a command some -additional information? Well, what most commands do is interpret the -``raw'' prefix in some special way. @kbd{C-u 0 C-x C-s} means that one -doesn't want a backup file to be created when saving the current buffer, -for instance. But what if you want to save without making a backup -file, and you want Emacs to flash lights and play a nice tune at the -same time? You can't, and you're probably perfectly happy that way. - -@kindex M-i (Summary) -@findex gnus-symbolic-argument -I'm not, so I've added a second prefix---the @dfn{symbolic prefix}. The -prefix key is @kbd{M-i} (@code{gnus-symbolic-argument}), and the next -character typed in is the value. You can stack as many @kbd{M-i} -prefixes as you want. @kbd{M-i a C-M-u} means ``feed the @kbd{C-M-u} -command the symbolic prefix @code{a}''. @kbd{M-i a M-i b C-M-u} means -``feed the @kbd{C-M-u} command the symbolic prefixes @code{a} and -@code{b}''. You get the drift. - -Typing in symbolic prefixes to commands that don't accept them doesn't -hurt, but it doesn't do any good either. Currently not many Gnus -functions make use of the symbolic prefix. - -If you're interested in how Gnus implements this, @pxref{Extended -Interactive}. - - -@node Formatting Variables -@section Formatting Variables -@cindex formatting variables - -Throughout this manual you've probably noticed lots of variables called -things like @code{gnus-group-line-format} and -@code{gnus-summary-mode-line-format}. These control how Gnus is to -output lines in the various buffers. There's quite a lot of them. -Fortunately, they all use the same syntax, so there's not that much to -be annoyed by. - -Here's an example format spec (from the group buffer): @samp{%M%S%5y: -%(%g%)\n}. We see that it is indeed extremely ugly, and that there are -lots of percentages everywhere. - -@menu -* Formatting Basics:: A formatting variable is basically a format string. -* Mode Line Formatting:: Some rules about mode line formatting variables. -* Advanced Formatting:: Modifying output in various ways. -* User-Defined Specs:: Having Gnus call your own functions. -* Formatting Fonts:: Making the formatting look colorful and nice. -* Positioning Point:: Moving point to a position after an operation. -* Tabulation:: Tabulating your output. -* Wide Characters:: Dealing with wide characters. -@end menu - -Currently Gnus uses the following formatting variables: -@code{gnus-group-line-format}, @code{gnus-summary-line-format}, -@code{gnus-server-line-format}, @code{gnus-topic-line-format}, -@code{gnus-group-mode-line-format}, -@code{gnus-summary-mode-line-format}, -@code{gnus-article-mode-line-format}, -@code{gnus-server-mode-line-format}, and -@code{gnus-summary-pick-line-format}. - -All these format variables can also be arbitrary elisp forms. In that -case, they will be @code{eval}ed to insert the required lines. - -@kindex M-x gnus-update-format -@findex gnus-update-format -Gnus includes a command to help you while creating your own format -specs. @kbd{M-x gnus-update-format} will @code{eval} the current form, -update the spec in question and pop you to a buffer where you can -examine the resulting Lisp code to be run to generate the line. - - - -@node Formatting Basics -@subsection Formatting Basics - -Each @samp{%} element will be replaced by some string or other when the -buffer in question is generated. @samp{%5y} means ``insert the @samp{y} -spec, and pad with spaces to get a 5-character field''. - -As with normal C and Emacs Lisp formatting strings, the numerical -modifier between the @samp{%} and the formatting type character will -@dfn{pad} the output so that it is always at least that long. -@samp{%5y} will make the field always (at least) five characters wide by -padding with spaces to the left. If you say @samp{%-5y}, it will pad to -the right instead. - -You may also wish to limit the length of the field to protect against -particularly wide values. For that you can say @samp{%4,6y}, which -means that the field will never be more than 6 characters wide and never -less than 4 characters wide. - -Also Gnus supports some extended format specifications, such as -@samp{%&user-date;}. - - -@node Mode Line Formatting -@subsection Mode Line Formatting - -Mode line formatting variables (e.g., -@code{gnus-summary-mode-line-format}) follow the same rules as other, -buffer line oriented formatting variables (@pxref{Formatting Basics}) -with the following two differences: - -@enumerate - -@item -There must be no newline (@samp{\n}) at the end. - -@item -The special @samp{%%b} spec can be used to display the buffer name. -Well, it's no spec at all, really---@samp{%%} is just a way to quote -@samp{%} to allow it to pass through the formatting machinery unmangled, -so that Emacs receives @samp{%b}, which is something the Emacs mode line -display interprets to mean ``show the buffer name''. For a full list of -mode line specs Emacs understands, see the documentation of the -@code{mode-line-format} variable. - -@end enumerate - - -@node Advanced Formatting -@subsection Advanced Formatting - -It is frequently useful to post-process the fields in some way. -Padding, limiting, cutting off parts and suppressing certain values can -be achieved by using @dfn{tilde modifiers}. A typical tilde spec might -look like @samp{%~(cut 3)~(ignore "0")y}. - -These are the valid modifiers: - -@table @code -@item pad -@itemx pad-left -Pad the field to the left with spaces until it reaches the required -length. - -@item pad-right -Pad the field to the right with spaces until it reaches the required -length. - -@item max -@itemx max-left -Cut off characters from the left until it reaches the specified length. - -@item max-right -Cut off characters from the right until it reaches the specified -length. - -@item cut -@itemx cut-left -Cut off the specified number of characters from the left. - -@item cut-right -Cut off the specified number of characters from the right. - -@item ignore -Return an empty string if the field is equal to the specified value. - -@item form -Use the specified form as the field value when the @samp{@@} spec is -used. - -Here's an example: - -@lisp -"~(form (current-time-string))@@" -@end lisp - -@end table - -Let's take an example. The @samp{%o} spec in the summary mode lines -will return a date in compact ISO8601 format---@samp{19960809T230410}. -This is quite a mouthful, so we want to shave off the century number and -the time, leaving us with a six-character date. That would be -@samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before -maxing, and we need the padding to ensure that the date is never less -than 6 characters to make it look nice in columns.) - -Ignoring is done first; then cutting; then maxing; and then as the very -last operation, padding. - - -@node User-Defined Specs -@subsection User-Defined Specs - -All the specs allow for inserting user defined specifiers---@samp{u}. -The next character in the format string should be a letter. Gnus -will call the function @code{gnus-user-format-function-}@samp{X}, where -@samp{X} is the letter following @samp{%u}. The function will be passed -a single parameter---what the parameter means depends on what buffer -it's being called from. The function should return a string, which will -be inserted into the buffer just like information from any other -specifier. This function may also be called with dummy values, so it -should protect against that. - -Also Gnus supports extended user-defined specs, such as @samp{%u&foo;}. -Gnus will call the function @code{gnus-user-format-function-}@samp{foo}. - -You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve -much the same without defining new functions. Here's an example: -@samp{%~(form (count-lines (point-min) (point)))@@}. The form -given here will be evaluated to yield the current line number, and then -inserted. - - -@node Formatting Fonts -@subsection Formatting Fonts - -@cindex %(, %) -@vindex gnus-mouse-face -There are specs for highlighting, and these are shared by all the format -variables. Text inside the @samp{%(} and @samp{%)} specifiers will get -the special @code{mouse-face} property set, which means that it will be -highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer -over it. - -@cindex %@{, %@} -@vindex gnus-face-0 -Text inside the @samp{%@{} and @samp{%@}} specifiers will have their -normal faces set using @code{gnus-face-0}, which is @code{bold} by -default. If you say @samp{%1@{}, you'll get @code{gnus-face-1} instead, -and so on. Create as many faces as you wish. The same goes for the -@code{mouse-face} specs---you can say @samp{%3(hello%)} to have -@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}. - -@cindex %<<, %>>, guillemets -@c @cindex %<<, %>>, %«, %», guillemets -@vindex gnus-balloon-face-0 -Text inside the @samp{%<<} and @samp{%>>} specifiers will get the -special @code{balloon-help} property set to -@code{gnus-balloon-face-0}. If you say @samp{%1<<}, you'll get -@code{gnus-balloon-face-1} and so on. The @code{gnus-balloon-face-*} -variables should be either strings or symbols naming functions that -return a string. When the mouse passes over text with this property -set, a balloon window will appear and display the string. Please -refer to @ref{Tooltips, ,Tooltips, emacs, The Emacs Manual}, -(in Emacs) or the doc string of @code{balloon-help-mode} (in -XEmacs) for more information on this. (For technical reasons, the -guillemets have been approximated as @samp{<<} and @samp{>>} in this -paragraph.) - -Here's an alternative recipe for the group buffer: - -@lisp -;; @r{Create three face types.} -(setq gnus-face-1 'bold) -(setq gnus-face-3 'italic) - -;; @r{We want the article count to be in} -;; @r{a bold and green face. So we create} -;; @r{a new face called @code{my-green-bold}.} -(copy-face 'bold 'my-green-bold) -;; @r{Set the color.} -(set-face-foreground 'my-green-bold "ForestGreen") -(setq gnus-face-2 'my-green-bold) - -;; @r{Set the new & fancy format.} -(setq gnus-group-line-format - "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n") -@end lisp - -I'm sure you'll be able to use this scheme to create totally unreadable -and extremely vulgar displays. Have fun! - -Note that the @samp{%(} specs (and friends) do not make any sense on the -mode-line variables. - -@node Positioning Point -@subsection Positioning Point - -Gnus usually moves point to a pre-defined place on each line in most -buffers. By default, point move to the first colon character on the -line. You can customize this behavior in three different ways. - -You can move the colon character to somewhere else on the line. - -@findex gnus-goto-colon -You can redefine the function that moves the point to the colon. The -function is called @code{gnus-goto-colon}. - -But perhaps the most convenient way to deal with this, if you don't want -to have a colon in your line, is to use the @samp{%*} specifier. If you -put a @samp{%*} somewhere in your format line definition, Gnus will -place point there. - - -@node Tabulation -@subsection Tabulation - -You can usually line up your displays by padding and cutting your -strings. However, when combining various strings of different size, it -can often be more convenient to just output the strings, and then worry -about lining up the following text afterwards. - -To do that, Gnus supplies tabulator specs---@samp{%=}. There are two -different types---@dfn{hard tabulators} and @dfn{soft tabulators}. - -@samp{%50=} will insert space characters to pad the line up to column -50. If the text is already past column 50, nothing will be inserted. -This is the soft tabulator. - -@samp{%-50=} will insert space characters to pad the line up to column -50. If the text is already past column 50, the excess text past column -50 will be removed. This is the hard tabulator. - - -@node Wide Characters -@subsection Wide Characters - -Fixed width fonts in most countries have characters of the same width. -Some countries, however, use Latin characters mixed with wider -characters---most notable East Asian countries. - -The problem is that when formatting, Gnus assumes that if a string is 10 -characters wide, it'll be 10 Latin characters wide on the screen. In -these countries, that's not true. - -@vindex gnus-use-correct-string-widths -To help fix this, you can set @code{gnus-use-correct-string-widths} to -@code{t}. This makes buffer generation slower, but the results will be -prettier. The default value under XEmacs is @code{t} but @code{nil} -for Emacs. - - -@node Window Layout -@section Window Layout -@cindex window layout - -No, there's nothing here about X, so be quiet. - -@vindex gnus-use-full-window -If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all -other windows and occupy the entire Emacs screen by itself. It is -@code{t} by default. - -Setting this variable to @code{nil} kinda works, but there are -glitches. Use at your own peril. - -@vindex gnus-buffer-configuration -@code{gnus-buffer-configuration} describes how much space each Gnus -buffer should be given. Here's an excerpt of this variable: - -@lisp -((group (vertical 1.0 (group 1.0 point))) - (article (vertical 1.0 (summary 0.25 point) - (article 1.0)))) -@end lisp - -This is an alist. The @dfn{key} is a symbol that names some action or -other. For instance, when displaying the group buffer, the window -configuration function will use @code{group} as the key. A full list of -possible names is listed below. - -The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer -should occupy. To take the @code{article} split as an example: - -@lisp -(article (vertical 1.0 (summary 0.25 point) - (article 1.0))) -@end lisp - -This @dfn{split} says that the summary buffer should occupy 25% of upper -half of the screen, and that it is placed over the article buffer. As -you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all -reaching for that calculator there). However, the special number -@code{1.0} is used to signal that this buffer should soak up all the -rest of the space available after the rest of the buffers have taken -whatever they need. There should be only one buffer with the @code{1.0} -size spec per split. - -Point will be put in the buffer that has the optional third element -@code{point}. In a @code{frame} split, the last subsplit having a leaf -split where the tag @code{frame-focus} is a member (i.e., is the third or -fourth element in the list, depending on whether the @code{point} tag is -present) gets focus. - -Here's a more complicated example: - -@lisp -(article (vertical 1.0 (group 4) - (summary 0.25 point) - (article 1.0))) -@end lisp - -If the size spec is an integer instead of a floating point number, -then that number will be used to say how many lines a buffer should -occupy, not a percentage. - -If the @dfn{split} looks like something that can be @code{eval}ed (to be -precise---if the @code{car} of the split is a function or a subr), this -split will be @code{eval}ed. If the result is non-@code{nil}, it will -be used as a split. - -Not complicated enough for you? Well, try this on for size: - -@lisp -(article (horizontal 1.0 - (vertical 0.5 - (group 1.0)) - (vertical 1.0 - (summary 0.25 point) - (article 1.0)))) -@end lisp - -Whoops. Two buffers with the mystery 100% tag. And what's that -@code{horizontal} thingie? - -If the first element in one of the split is @code{horizontal}, Gnus will -split the window horizontally, giving you two windows side-by-side. -Inside each of these strips you may carry on all you like in the normal -fashion. The number following @code{horizontal} says what percentage of -the screen is to be given to this strip. - -For each split, there @emph{must} be one element that has the 100% tag. -The splitting is never accurate, and this buffer will eat any leftover -lines from the splits. - -To be slightly more formal, here's a definition of what a valid split -may look like: - -@example -@group -split = frame | horizontal | vertical | buffer | form -frame = "(frame " size *split ")" -horizontal = "(horizontal " size *split ")" -vertical = "(vertical " size *split ")" -buffer = "(" buf-name " " size *[ "point" ] *[ "frame-focus"] ")" -size = number | frame-params -buf-name = group | article | summary ... -@end group -@end example - -The limitations are that the @code{frame} split can only appear as the -top-level split. @var{form} should be an Emacs Lisp form that should -return a valid split. We see that each split is fully recursive, and -may contain any number of @code{vertical} and @code{horizontal} splits. - -@vindex gnus-window-min-width -@vindex gnus-window-min-height -@cindex window height -@cindex window width -Finding the right sizes can be a bit complicated. No window may be less -than @code{gnus-window-min-height} (default 1) characters high, and all -windows must be at least @code{gnus-window-min-width} (default 1) -characters wide. Gnus will try to enforce this before applying the -splits. If you want to use the normal Emacs window width/height limit, -you can just set these two variables to @code{nil}. - -If you're not familiar with Emacs terminology, @code{horizontal} and -@code{vertical} splits may work the opposite way of what you'd expect. -Windows inside a @code{horizontal} split are shown side-by-side, and -windows within a @code{vertical} split are shown above each other. - -@findex gnus-configure-frame -If you want to experiment with window placement, a good tip is to call -@code{gnus-configure-frame} directly with a split. This is the function -that does all the real work when splitting buffers. Below is a pretty -nonsensical configuration with 5 windows; two for the group buffer and -three for the article buffer. (I said it was nonsensical.) If you -@code{eval} the statement below, you can get an idea of how that would -look straight away, without going through the normal Gnus channels. -Play with it until you're satisfied, and then use -@code{gnus-add-configuration} to add your new creation to the buffer -configuration list. - -@lisp -(gnus-configure-frame - '(horizontal 1.0 - (vertical 10 - (group 1.0) - (article 0.3 point)) - (vertical 1.0 - (article 1.0) - (horizontal 4 - (group 1.0) - (article 10))))) -@end lisp - -You might want to have several frames as well. No prob---just use the -@code{frame} split: - -@lisp -(gnus-configure-frame - '(frame 1.0 - (vertical 1.0 - (summary 0.25 point frame-focus) - (article 1.0)) - (vertical ((height . 5) (width . 15) - (user-position . t) - (left . -1) (top . 1)) - (picon 1.0)))) - -@end lisp - -This split will result in the familiar summary/article window -configuration in the first (or ``main'') frame, while a small additional -frame will be created where picons will be shown. As you can see, -instead of the normal @code{1.0} top-level spec, each additional split -should have a frame parameter alist as the size spec. -@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp -Reference Manual}. Under XEmacs, a frame property list will be -accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)} -is such a plist. -The list of all possible keys for @code{gnus-buffer-configuration} can -be found in its default value. - -Note that the @code{message} key is used for both -@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If -it is desirable to distinguish between the two, something like this -might be used: - -@lisp -(message (horizontal 1.0 - (vertical 1.0 (message 1.0 point)) - (vertical 0.24 - (if (buffer-live-p gnus-summary-buffer) - '(summary 0.5)) - (group 1.0)))) -@end lisp - -One common desire for a multiple frame split is to have a separate frame -for composing mail and news while leaving the original frame intact. To -accomplish that, something like the following can be done: - -@lisp -(message - (frame 1.0 - (if (not (buffer-live-p gnus-summary-buffer)) - (car (cdr (assoc 'group gnus-buffer-configuration))) - (car (cdr (assoc 'summary gnus-buffer-configuration)))) - (vertical ((user-position . t) (top . 1) (left . 1) - (name . "Message")) - (message 1.0 point)))) -@end lisp - -@findex gnus-add-configuration -Since the @code{gnus-buffer-configuration} variable is so long and -complicated, there's a function you can use to ease changing the config -of a single setting: @code{gnus-add-configuration}. If, for instance, -you want to change the @code{article} setting, you could say: - -@lisp -(gnus-add-configuration - '(article (vertical 1.0 - (group 4) - (summary .25 point) - (article 1.0)))) -@end lisp - -You'd typically stick these @code{gnus-add-configuration} calls in your -@file{~/.gnus.el} file or in some startup hook---they should be run after -Gnus has been loaded. - -@vindex gnus-always-force-window-configuration -If all windows mentioned in the configuration are already visible, Gnus -won't change the window configuration. If you always want to force the -``right'' window configuration, you can set -@code{gnus-always-force-window-configuration} to non-@code{nil}. - -If you're using tree displays (@pxref{Tree Display}), and the tree -window is displayed vertically next to another window, you may also want -to fiddle with @code{gnus-tree-minimize-window} to avoid having the -windows resized. - -@subsection Window Configuration Names - -Here's a list of most of the currently known window configurations, -and when they're used: - -@table @code -@item group -The group buffer. - -@item summary -Entering a group and showing only the summary. - -@item article -Selecting an article. - -@item server -The server buffer. - -@item browse -Browsing groups from the server buffer. - -@item message -Composing a (new) message. - -@item only-article -Showing only the article buffer. - -@item edit-article -Editing an article. - -@item edit-form -Editing group parameters and the like. - -@item edit-score -Editing a server definition. - -@item post -Composing a news message. - -@item reply -Replying or following up an article without yanking the text. - -@item forward -Forwarding a message. - -@item reply-yank -Replying or following up an article with yanking the text. - -@item mail-bound -Bouncing a message. - -@item pipe -Sending an article to an external process. - -@item bug -Sending a bug report. - -@item score-trace -Displaying the score trace. - -@item score-words -Displaying the score words. - -@item split-trace -Displaying the split trace. - -@item compose-bounce -Composing a bounce message. - -@item mml-preview -Previewing a @acronym{MIME} part. - -@end table - - -@subsection Example Window Configurations - -@itemize @bullet -@item -Narrow left hand side occupied by group buffer. Right hand side split -between summary buffer (top one-sixth) and article buffer (bottom). - -@ifinfo -@example -+---+---------+ -| G | Summary | -| r +---------+ -| o | | -| u | Article | -| p | | -+---+---------+ -@end example -@end ifinfo - -@lisp -(gnus-add-configuration - '(article - (horizontal 1.0 - (vertical 25 (group 1.0)) - (vertical 1.0 - (summary 0.16 point) - (article 1.0))))) - -(gnus-add-configuration - '(summary - (horizontal 1.0 - (vertical 25 (group 1.0)) - (vertical 1.0 (summary 1.0 point))))) -@end lisp - -@end itemize - - -@node Faces and Fonts -@section Faces and Fonts -@cindex faces -@cindex fonts -@cindex colors - -Fiddling with fonts and faces used to be very difficult, but these days -it is very simple. You simply say @kbd{M-x customize-face}, pick out -the face you want to alter, and alter it via the standard Customize -interface. - - -@node Mode Lines -@section Mode Lines -@cindex mode lines - -@vindex gnus-updated-mode-lines -@code{gnus-updated-mode-lines} says what buffers should keep their mode -lines updated. It is a list of symbols. Supported symbols include -@code{group}, @code{article}, @code{summary}, @code{server}, -@code{browse}, and @code{tree}. If the corresponding symbol is present, -Gnus will keep that mode line updated with information that may be -pertinent. If this variable is @code{nil}, screen refresh may be -quicker. - -@cindex display-time - -@vindex gnus-mode-non-string-length -By default, Gnus displays information on the current article in the mode -lines of the summary and article buffers. The information Gnus wishes -to display (e.g., the subject of the article) is often longer than the -mode lines, and therefore have to be cut off at some point. The -@code{gnus-mode-non-string-length} variable says how long the other -elements on the line is (i.e., the non-info part). If you put -additional elements on the mode line (e.g., a clock), you should modify -this variable: - -@c Hook written by Francesco Potortì -@lisp -(add-hook 'display-time-hook - (lambda () (setq gnus-mode-non-string-length - (+ 21 - (if line-number-mode 5 0) - (if column-number-mode 4 0) - (length display-time-string))))) -@end lisp - -If this variable is @code{nil} (which is the default), the mode line -strings won't be chopped off, and they won't be padded either. Note -that the default is unlikely to be desirable, as even the percentage -complete in the buffer may be crowded off the mode line; the user should -configure this variable appropriately for her configuration. - - -@node Highlighting and Menus -@section Highlighting and Menus -@cindex visual -@cindex highlighting -@cindex menus - -@vindex gnus-visual -The @code{gnus-visual} variable controls most of the Gnus-prettifying -aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy -colors or fonts. This will also inhibit loading the @file{gnus-vis.el} -file. - -This variable can be a list of visual properties that are enabled. The -following elements are valid, and are all included by default: - -@table @code -@item group-highlight -Do highlights in the group buffer. -@item summary-highlight -Do highlights in the summary buffer. -@item article-highlight -Do highlights in the article buffer. -@item highlight -Turn on highlighting in all buffers. -@item group-menu -Create menus in the group buffer. -@item summary-menu -Create menus in the summary buffers. -@item article-menu -Create menus in the article buffer. -@item browse-menu -Create menus in the browse buffer. -@item server-menu -Create menus in the server buffer. -@item score-menu -Create menus in the score buffers. -@item menu -Create menus in all buffers. -@end table - -So if you only want highlighting in the article buffer and menus in all -buffers, you could say something like: - -@lisp -(setq gnus-visual '(article-highlight menu)) -@end lisp - -If you want highlighting only and no menus whatsoever, you'd say: - -@lisp -(setq gnus-visual '(highlight)) -@end lisp - -If @code{gnus-visual} is @code{t}, highlighting and menus will be used -in all Gnus buffers. - -Other general variables that influence the look of all buffers include: - -@table @code -@item gnus-mouse-face -@vindex gnus-mouse-face -This is the face (i.e., font) used for mouse highlighting in Gnus. No -mouse highlights will be done if @code{gnus-visual} is @code{nil}. - -@end table - -There are hooks associated with the creation of all the different menus: - -@table @code - -@item gnus-article-menu-hook -@vindex gnus-article-menu-hook -Hook called after creating the article mode menu. - -@item gnus-group-menu-hook -@vindex gnus-group-menu-hook -Hook called after creating the group mode menu. - -@item gnus-summary-menu-hook -@vindex gnus-summary-menu-hook -Hook called after creating the summary mode menu. - -@item gnus-server-menu-hook -@vindex gnus-server-menu-hook -Hook called after creating the server mode menu. - -@item gnus-browse-menu-hook -@vindex gnus-browse-menu-hook -Hook called after creating the browse mode menu. - -@item gnus-score-menu-hook -@vindex gnus-score-menu-hook -Hook called after creating the score mode menu. - -@end table - - -@node Daemons -@section Daemons -@cindex demons -@cindex daemons - -Gnus, being larger than any program ever written (allegedly), does lots -of strange stuff that you may wish to have done while you're not -present. For instance, you may want it to check for new mail once in a -while. Or you may want it to close down all connections to all servers -when you leave Emacs idle. And stuff like that. - -Gnus will let you do stuff like that by defining various -@dfn{handlers}. Each handler consists of three elements: A -@var{function}, a @var{time}, and an @var{idle} parameter. - -Here's an example of a handler that closes connections when Emacs has -been idle for thirty minutes: - -@lisp -(gnus-demon-close-connections nil 30) -@end lisp - -Here's a handler that scans for @acronym{PGP} headers every hour when -Emacs is idle: - -@lisp -(gnus-demon-scan-pgp 60 t) -@end lisp - -This @var{time} parameter and that @var{idle} parameter work together -in a strange, but wonderful fashion. Basically, if @var{idle} is -@code{nil}, then the function will be called every @var{time} minutes. - -If @var{idle} is @code{t}, then the function will be called after -@var{time} minutes only if Emacs is idle. So if Emacs is never idle, -the function will never be called. But once Emacs goes idle, the -function will be called every @var{time} minutes. - -If @var{idle} is a number and @var{time} is a number, the function will -be called every @var{time} minutes only when Emacs has been idle for -@var{idle} minutes. - -If @var{idle} is a number and @var{time} is @code{nil}, the function -will be called once every time Emacs has been idle for @var{idle} -minutes. - -And if @var{time} is a string, it should look like @samp{07:31}, and -the function will then be called once every day somewhere near that -time. Modified by the @var{idle} parameter, of course. - -@vindex gnus-demon-timestep -(When I say ``minute'' here, I really mean @code{gnus-demon-timestep} -seconds. This is 60 by default. If you change that variable, -all the timings in the handlers will be affected.) - -So, if you want to add a handler, you could put something like this in -your @file{~/.gnus.el} file: - -@findex gnus-demon-add-handler -@lisp -(gnus-demon-add-handler 'gnus-demon-close-connections 30 t) -@end lisp - -@findex gnus-demon-add-scanmail -@findex gnus-demon-add-rescan -@findex gnus-demon-add-scan-timestamps -@findex gnus-demon-add-disconnection -Some ready-made functions to do this have been created: -@code{gnus-demon-add-disconnection}, -@code{gnus-demon-add-nntp-close-connection}, -@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and -@code{gnus-demon-add-scanmail}. Just put those functions in your -@file{~/.gnus.el} if you want those abilities. - -@findex gnus-demon-init -@findex gnus-demon-cancel -@vindex gnus-demon-handlers -If you add handlers to @code{gnus-demon-handlers} directly, you should -run @code{gnus-demon-init} to make the changes take hold. To cancel all -daemons, you can use the @code{gnus-demon-cancel} function. - -Note that adding daemons can be pretty naughty if you over do it. Adding -functions that scan all news and mail from all servers every two seconds -is a sure-fire way of getting booted off any respectable system. So -behave. - - -@node Undo -@section Undo -@cindex undo - -It is very useful to be able to undo actions one has done. In normal -Emacs buffers, it's easy enough---you just push the @code{undo} button. -In Gnus buffers, however, it isn't that simple. - -The things Gnus displays in its buffer is of no value whatsoever to -Gnus---it's all just data designed to look nice to the user. -Killing a group in the group buffer with @kbd{C-k} makes the line -disappear, but that's just a side-effect of the real action---the -removal of the group in question from the internal Gnus structures. -Undoing something like that can't be done by the normal Emacs -@code{undo} function. - -Gnus tries to remedy this somewhat by keeping track of what the user -does and coming up with actions that would reverse the actions the user -takes. When the user then presses the @code{undo} key, Gnus will run -the code to reverse the previous action, or the previous actions. -However, not all actions are easily reversible, so Gnus currently offers -a few key functions to be undoable. These include killing groups, -yanking groups, and changing the list of read articles of groups. -That's it, really. More functions may be added in the future, but each -added function means an increase in data to be stored, so Gnus will -never be totally undoable. - -@findex gnus-undo-mode -@vindex gnus-use-undo -@findex gnus-undo -The undoability is provided by the @code{gnus-undo-mode} minor mode. It -is used if @code{gnus-use-undo} is non-@code{nil}, which is the -default. The @kbd{C-M-_} key performs the @code{gnus-undo} -command, which should feel kinda like the normal Emacs @code{undo} -command. - - -@node Predicate Specifiers -@section Predicate Specifiers -@cindex predicate specifiers - -Some Gnus variables are @dfn{predicate specifiers}. This is a special -form that allows flexible specification of predicates without having -to type all that much. - -These specifiers are lists consisting of functions, symbols and lists. - -Here's an example: - -@lisp -(or gnus-article-unseen-p - gnus-article-unread-p) -@end lisp - -The available symbols are @code{or}, @code{and} and @code{not}. The -functions all take one parameter. - -@findex gnus-make-predicate -Internally, Gnus calls @code{gnus-make-predicate} on these specifiers -to create a function that can be called. This input parameter to this -function will be passed along to all the functions in the predicate -specifier. - - -@node Moderation -@section Moderation -@cindex moderation - -If you are a moderator, you can use the @file{gnus-mdrtn.el} package. -It is not included in the standard Gnus package. Write a mail to -@samp{larsi@@gnus.org} and state what group you moderate, and you'll -get a copy. - -The moderation package is implemented as a minor mode for summary -buffers. Put - -@lisp -(add-hook 'gnus-summary-mode-hook 'gnus-moderate) -@end lisp - -in your @file{~/.gnus.el} file. - -If you are the moderator of @samp{rec.zoofle}, this is how it's -supposed to work: - -@enumerate -@item -You split your incoming mail by matching on -@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted -articles in some mail group---for instance, @samp{nnml:rec.zoofle}. - -@item -You enter that group once in a while and post articles using the @kbd{e} -(edit-and-post) or @kbd{s} (just send unedited) commands. - -@item -If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some -articles that weren't approved by you, you can cancel them with the -@kbd{c} command. -@end enumerate - -To use moderation mode in these two groups, say: - -@lisp -(setq gnus-moderated-list - "^nnml:rec.zoofle$\\|^rec.zoofle$") -@end lisp - - -@node Fetching a Group -@section Fetching a Group -@cindex fetching a group - -@findex gnus-fetch-group -It is sometimes convenient to be able to just say ``I want to read this -group and I don't care whether Gnus has been started or not''. This is -perhaps more useful for people who write code than for users, but the -command @code{gnus-fetch-group} provides this functionality in any case. -It takes the group name as a parameter. - - -@node Image Enhancements -@section Image Enhancements - -XEmacs, as well as Emacs 21@footnote{Emacs 21 on MS Windows doesn't -support images, Emacs 22 does.} and up, are able to display pictures and -stuff, so Gnus has taken advantage of that. - -@menu -* X-Face:: Display a funky, teensy black-and-white image. -* Face:: Display a funkier, teensier colored image. -* Smileys:: Show all those happy faces the way they were meant to be shown. -* Picons:: How to display pictures of what you're reading. -* Gravatars:: Display the avatar of people you read. -* XVarious:: Other XEmacsy Gnusey variables. -@end menu - - -@node X-Face -@subsection X-Face -@cindex x-face - -@code{X-Face} headers describe a 48x48 pixel black-and-white (1 bit -depth) image that's supposed to represent the author of the message. -It seems to be supported by an ever-growing number of mail and news -readers. - -@cindex x-face -@findex gnus-article-display-x-face -@vindex gnus-article-x-face-command -@vindex gnus-article-x-face-too-ugly -@iftex -@iflatex -\include{xface} -@end iflatex -@end iftex -@c @anchor{X-Face} - -Viewing an @code{X-Face} header either requires an Emacs that has -@samp{compface} support (which most XEmacs versions have), or that you -have suitable conversion or display programs installed. If your Emacs -has image support the default action is to display the face before the -@code{From} header. If there's no native @code{X-Face} support, Gnus -will try to convert the @code{X-Face} header using external programs -from the @code{pbmplus} package and friends, see below. For XEmacs it's -faster if XEmacs has been compiled with @code{X-Face} support. The -default action under Emacs without image support is to fork off the -@code{display} program. - -On a GNU/Linux system, the @code{display} program is included in the -ImageMagick package. For external conversion programs look for packages -with names like @code{netpbm}, @code{libgr-progs} and @code{compface}. -On Windows, you may use the packages @code{netpbm} and @code{compface} -from @url{http://gnuwin32.sourceforge.net}. You need to add the -@code{bin} directory to your @code{PATH} environment variable. -@c In fact only the following DLLs and binaries seem to be required: -@c compface1.dll uncompface.exe libnetpbm10.dll icontopbm.exe - -The variable @code{gnus-article-x-face-command} controls which programs -are used to display the @code{X-Face} header. If this variable is a -string, this string will be executed in a sub-shell. If it is a -function, this function will be called with the face as the argument. -If @code{gnus-article-x-face-too-ugly} (which is a regexp) matches the -@code{From} header, the face will not be shown. - -(Note: @code{x-face} is used in the variable/function names, not -@code{xface}). - -@noindent -Face and variable: - -@table @code -@item gnus-x-face -@vindex gnus-x-face -Face to show X-Face. The colors from this face are used as the -foreground and background colors of the displayed X-Faces. The -default colors are black and white. - -@item gnus-face-properties-alist -@vindex gnus-face-properties-alist -Alist of image types and properties applied to Face (@pxref{Face}) and -X-Face images. The default value is @code{((pbm . (:face gnus-x-face)) -(png . nil))} for Emacs or @code{((xface . (:face gnus-x-face)))} for -XEmacs. Here are examples: - -@lisp -;; Specify the altitude of Face and X-Face images in the From header. -(setq gnus-face-properties-alist - '((pbm . (:face gnus-x-face :ascent 80)) - (png . (:ascent 80)))) - -;; Show Face and X-Face images as pressed buttons. -(setq gnus-face-properties-alist - '((pbm . (:face gnus-x-face :relief -2)) - (png . (:relief -2)))) -@end lisp - -@pxref{Image Descriptors, ,Image Descriptors, elisp, The Emacs Lisp -Reference Manual} for the valid properties for various image types. -Currently, @code{pbm} is used for X-Face images and @code{png} is used -for Face images in Emacs. Only the @code{:face} property is effective -on the @code{xface} image type in XEmacs if it is built with the -@samp{libcompface} library. -@end table - -If you use posting styles, you can use an @code{x-face-file} entry in -@code{gnus-posting-styles}, @xref{Posting Styles}. If you don't, Gnus -provides a few convenience functions and variables to allow easier -insertion of X-Face headers in outgoing messages. You also need the -above mentioned ImageMagick, netpbm or other image conversion packages -(depending the values of the variables below) for these functions. - -@findex gnus-random-x-face -@vindex gnus-convert-pbm-to-x-face-command -@vindex gnus-x-face-directory -@code{gnus-random-x-face} goes through all the @samp{pbm} files in -@code{gnus-x-face-directory} and picks one at random, and then -converts it to the X-Face format by using the -@code{gnus-convert-pbm-to-x-face-command} shell command. The -@samp{pbm} files should be 48x48 pixels big. It returns the X-Face -header data as a string. - -@findex gnus-insert-random-x-face-header -@code{gnus-insert-random-x-face-header} calls -@code{gnus-random-x-face} and inserts a @samp{X-Face} header with the -randomly generated data. - -@findex gnus-x-face-from-file -@vindex gnus-convert-image-to-x-face-command -@code{gnus-x-face-from-file} takes a GIF file as the parameter, and then -converts the file to X-Face format by using the -@code{gnus-convert-image-to-x-face-command} shell command. - -Here's how you would typically use the first function. Put something -like the following in your @file{~/.gnus.el} file: - -@lisp -(setq message-required-news-headers - (nconc message-required-news-headers - (list '(X-Face . gnus-random-x-face)))) -@end lisp - -Using the last function would be something like this: - -@lisp -(setq message-required-news-headers - (nconc message-required-news-headers - (list '(X-Face . (lambda () - (gnus-x-face-from-file - "~/My-face.gif")))))) -@end lisp - - -@node Face -@subsection Face -@cindex face - -@c #### FIXME: faces and x-faces' implementations should really be harmonized. - -@code{Face} headers are essentially a funkier version of @code{X-Face} -ones. They describe a 48x48 pixel colored image that's supposed to -represent the author of the message. - -@cindex face -@findex gnus-article-display-face -The contents of a @code{Face} header must be a base64 encoded PNG image. -See @uref{http://quimby.gnus.org/circus/face/} for the precise -specifications. - -The @code{gnus-face-properties-alist} variable affects the appearance of -displayed Face images. @xref{X-Face}. - -Viewing a @code{Face} header requires an Emacs that is able to display -PNG images. -@c Maybe add this: -@c (if (featurep 'xemacs) -@c (featurep 'png) -@c (image-type-available-p 'png)) - -Gnus provides a few convenience functions and variables to allow -easier insertion of Face headers in outgoing messages. - -@findex gnus-convert-png-to-face -@code{gnus-convert-png-to-face} takes a 48x48 PNG image, no longer than -726 bytes long, and converts it to a face. - -@findex gnus-face-from-file -@vindex gnus-convert-image-to-face-command -@code{gnus-face-from-file} takes a JPEG file as the parameter, and then -converts the file to Face format by using the -@code{gnus-convert-image-to-face-command} shell command. - -Here's how you would typically use this function. Put something like the -following in your @file{~/.gnus.el} file: - -@lisp -(setq message-required-news-headers - (nconc message-required-news-headers - (list '(Face . (lambda () - (gnus-face-from-file "~/face.jpg")))))) -@end lisp - - -@node Smileys -@subsection Smileys -@cindex smileys - -@iftex -@iflatex -\gnusfig{-3cm}{0.5cm}{\epsfig{figure=ps/BigFace,height=20cm}} -\input{smiley} -@end iflatex -@end iftex - -@dfn{Smiley} is a package separate from Gnus, but since Gnus is -currently the only package that uses Smiley, it is documented here. - -In short---to use Smiley in Gnus, put the following in your -@file{~/.gnus.el} file: - -@lisp -(setq gnus-treat-display-smileys t) -@end lisp - -Smiley maps text smiley faces---@samp{:-)}, @samp{8-)}, @samp{:-(} and -the like---to pictures and displays those instead of the text smiley -faces. The conversion is controlled by a list of regexps that matches -text and maps that to file names. - -@vindex smiley-regexp-alist -The alist used is specified by the @code{smiley-regexp-alist} -variable. The first item in each element is the regexp to be matched; -the second element is the regexp match group that is to be replaced by -the picture; and the third element is the name of the file to be -displayed. - -The following variables customize the appearance of the smileys: - -@table @code - -@item smiley-style -@vindex smiley-style -Specifies the smiley style. Predefined smiley styles include -@code{low-color} (small 13x14 pixel, three-color images), @code{medium} -(more colorful images, 16x16 pixel), and @code{grayscale} (grayscale -images, 14x14 pixel). The default depends on the height of the default -face. - -@item smiley-data-directory -@vindex smiley-data-directory -Where Smiley will look for smiley faces files. You shouldn't set this -variable anymore. Customize @code{smiley-style} instead. - -@item gnus-smiley-file-types -@vindex gnus-smiley-file-types -List of suffixes on smiley file names to try. - -@end table - - -@node Picons -@subsection Picons - -@iftex -@iflatex -\include{picons} -@end iflatex -@end iftex - -So@dots{} You want to slow down your news reader even more! This is a -good way to do so. It's also a great way to impress people staring -over your shoulder as you read news. - -What are Picons? To quote directly from the Picons Web site: - -@iftex -@iflatex -\margindex{} -@end iflatex -@end iftex - -@quotation -@dfn{Picons} is short for ``personal icons''. They're small, -constrained images used to represent users and domains on the net, -organized into databases so that the appropriate image for a given -e-mail address can be found. Besides users and domains, there are picon -databases for Usenet newsgroups and weather forecasts. The picons are -in either monochrome @code{XBM} format or color @code{XPM} and -@code{GIF} formats. -@end quotation - -@vindex gnus-picon-databases -For instructions on obtaining and installing the picons databases, -point your Web browser at -@uref{http://www.cs.indiana.edu/picons/ftp/index.html}. - -If you are using Debian GNU/Linux, saying @samp{apt-get install -picons.*} will install the picons where Gnus can find them. - -To enable displaying picons, simply make sure that -@code{gnus-picon-databases} points to the directory containing the -Picons databases. - -@vindex gnus-picon-style -The variable @code{gnus-picon-style} controls how picons are displayed. -If @code{inline}, the textual representation is replaced. If -@code{right}, picons are added right to the textual representation. - -@vindex gnus-picon-properties -The value of the variable @code{gnus-picon-properties} is a list of -properties applied to picons. - -The following variables offer control over where things are located. - -@table @code - -@item gnus-picon-databases -@vindex gnus-picon-databases -The location of the picons database. This is a list of directories -containing the @file{news}, @file{domains}, @file{users} (and so on) -subdirectories. Defaults to @code{("/usr/lib/picon" -"/usr/local/faces")}. - -@item gnus-picon-news-directories -@vindex gnus-picon-news-directories -List of subdirectories to search in @code{gnus-picon-databases} for -newsgroups faces. @code{("news")} is the default. - -@item gnus-picon-user-directories -@vindex gnus-picon-user-directories -List of subdirectories to search in @code{gnus-picon-databases} for user -faces. @code{("users" "usenix" "local" "misc")} is the default. - -@item gnus-picon-domain-directories -@vindex gnus-picon-domain-directories -List of subdirectories to search in @code{gnus-picon-databases} for -domain name faces. Defaults to @code{("domains")}. Some people may -want to add @samp{"unknown"} to this list. - -@item gnus-picon-file-types -@vindex gnus-picon-file-types -Ordered list of suffixes on picon file names to try. Defaults to -@code{("xpm" "gif" "xbm")} minus those not built-in your Emacs. - -@item gnus-picon-inhibit-top-level-domains -@vindex gnus-picon-inhibit-top-level-domains -If non-@code{nil} (which is the default), don't display picons for -things like @samp{.net} and @samp{.de}, which aren't usually very -interesting. - -@end table - -@node Gravatars -@subsection Gravatars - -@iftex -@iflatex -\include{gravatars} -@end iflatex -@end iftex - -A gravatar is an image registered to an e-mail address. - -You can submit yours on-line at @uref{http://www.gravatar.com}. - -The following variables offer control over how things are displayed. - -@table @code - -@item gnus-gravatar-size -@vindex gnus-gravatar-size -The size in pixels of gravatars. Gravatars are always square, so one -number for the size is enough. - -@item gnus-gravatar-properties -@vindex gnus-gravatar-properties -List of image properties applied to Gravatar images. - -@item gnus-gravatar-too-ugly -@vindex gnus-gravatar-too-ugly -Regexp that matches mail addresses or names of people of which avatars -should not be displayed, or @code{nil}. It default to the value of -@code{gnus-article-x-face-too-ugly} (@pxref{X-Face}). - -@end table - -If you want to see them in the From field, set: -@lisp -(setq gnus-treat-from-gravatar 'head) -@end lisp - -If you want to see them in the Cc and To fields, set: - -@lisp -(setq gnus-treat-mail-gravatar 'head) -@end lisp - - -@node XVarious -@subsection Various XEmacs Variables - -@table @code -@item gnus-xmas-glyph-directory -@vindex gnus-xmas-glyph-directory -This is where Gnus will look for pictures. Gnus will normally -auto-detect this directory, but you may set it manually if you have an -unusual directory structure. - -@item gnus-xmas-modeline-glyph -@vindex gnus-xmas-modeline-glyph -A glyph displayed in all Gnus mode lines. It is a tiny gnu head by -default. - -@end table - -@subsubsection Toolbar - -@table @code - -@item gnus-use-toolbar -@vindex gnus-use-toolbar -This variable specifies the position to display the toolbar. If -@code{nil}, don't display toolbars. If it is non-@code{nil}, it should -be one of the symbols @code{default}, @code{top}, @code{bottom}, -@code{right}, and @code{left}. @code{default} means to use the default -toolbar, the rest mean to display the toolbar on the place which those -names show. The default is @code{default}. - -@item gnus-toolbar-thickness -@vindex gnus-toolbar-thickness -Cons of the height and the width specifying the thickness of a toolbar. -The height is used for the toolbar displayed on the top or the bottom, -the width is used for the toolbar displayed on the right or the left. -The default is that of the default toolbar. - -@item gnus-group-toolbar -@vindex gnus-group-toolbar -The toolbar in the group buffer. - -@item gnus-summary-toolbar -@vindex gnus-summary-toolbar -The toolbar in the summary buffer. - -@item gnus-summary-mail-toolbar -@vindex gnus-summary-mail-toolbar -The toolbar in the summary buffer of mail groups. - -@end table - -@iftex -@iflatex -\margindex{} -@end iflatex -@end iftex - - -@node Fuzzy Matching -@section Fuzzy Matching -@cindex fuzzy matching - -Gnus provides @dfn{fuzzy matching} of @code{Subject} lines when doing -things like scoring, thread gathering and thread comparison. - -As opposed to regular expression matching, fuzzy matching is very fuzzy. -It's so fuzzy that there's not even a definition of what @dfn{fuzziness} -means, and the implementation has changed over time. - -Basically, it tries to remove all noise from lines before comparing. -@samp{Re: }, parenthetical remarks, white space, and so on, are filtered -out of the strings before comparing the results. This often leads to -adequate results---even when faced with strings generated by text -manglers masquerading as newsreaders. - - -@node Thwarting Email Spam -@section Thwarting Email Spam -@cindex email spam -@cindex spam -@cindex UCE -@cindex unsolicited commercial email - -In these last days of the Usenet, commercial vultures are hanging about -and grepping through news like crazy to find email addresses they can -foist off their scams and products to. As a reaction to this, many -people have started putting nonsense addresses into their @code{From} -lines. I think this is counterproductive---it makes it difficult for -people to send you legitimate mail in response to things you write, as -well as making it difficult to see who wrote what. This rewriting may -perhaps be a bigger menace than the unsolicited commercial email itself -in the end. - -The biggest problem I have with email spam is that it comes in under -false pretenses. I press @kbd{g} and Gnus merrily informs me that I -have 10 new emails. I say ``Golly gee! Happy is me!'' and select the -mail group, only to find two pyramid schemes, seven advertisements -(``New! Miracle tonic for growing full, lustrous hair on your toes!'') -and one mail asking me to repent and find some god. - -This is annoying. Here's what you can do about it. - -@menu -* The problem of spam:: Some background, and some solutions -* Anti-Spam Basics:: Simple steps to reduce the amount of spam. -* SpamAssassin:: How to use external anti-spam tools. -* Hashcash:: Reduce spam by burning CPU time. -@end menu - -@node The problem of spam -@subsection The problem of spam -@cindex email spam -@cindex spam filtering approaches -@cindex filtering approaches, spam -@cindex UCE -@cindex unsolicited commercial email - -First, some background on spam. - -If you have access to e-mail, you are familiar with spam (technically -termed @acronym{UCE}, Unsolicited Commercial E-mail). Simply put, it -exists because e-mail delivery is very cheap compared to paper mail, -so only a very small percentage of people need to respond to an UCE to -make it worthwhile to the advertiser. Ironically, one of the most -common spams is the one offering a database of e-mail addresses for -further spamming. Senders of spam are usually called @emph{spammers}, -but terms like @emph{vermin}, @emph{scum}, @emph{sociopaths}, and -@emph{morons} are in common use as well. - -Spam comes from a wide variety of sources. It is simply impossible to -dispose of all spam without discarding useful messages. A good -example is the TMDA system, which requires senders -unknown to you to confirm themselves as legitimate senders before -their e-mail can reach you. Without getting into the technical side -of TMDA, a downside is clearly that e-mail from legitimate sources may -be discarded if those sources can't or won't confirm themselves -through the TMDA system. Another problem with TMDA is that it -requires its users to have a basic understanding of e-mail delivery -and processing. - -The simplest approach to filtering spam is filtering, at the mail -server or when you sort through incoming mail. If you get 200 spam -messages per day from @samp{random-address@@vmadmin.com}, you block -@samp{vmadmin.com}. If you get 200 messages about @samp{VIAGRA}, you -discard all messages with @samp{VIAGRA} in the message. If you get -lots of spam from Bulgaria, for example, you try to filter all mail -from Bulgarian IPs. - -This, unfortunately, is a great way to discard legitimate e-mail. The -risks of blocking a whole country (Bulgaria, Norway, Nigeria, China, -etc.)@: or even a continent (Asia, Africa, Europe, etc.)@: from contacting -you should be obvious, so don't do it if you have the choice. - -In another instance, the very informative and useful RISKS digest has -been blocked by overzealous mail filters because it @strong{contained} -words that were common in spam messages. Nevertheless, in isolated -cases, with great care, direct filtering of mail can be useful. - -Another approach to filtering e-mail is the distributed spam -processing, for instance DCC implements such a system. In essence, -@var{N} systems around the world agree that a machine @var{X} in -Ghana, Estonia, or California is sending out spam e-mail, and these -@var{N} systems enter @var{X} or the spam e-mail from @var{X} into a -database. The criteria for spam detection vary---it may be the number -of messages sent, the content of the messages, and so on. When a user -of the distributed processing system wants to find out if a message is -spam, he consults one of those @var{N} systems. - -Distributed spam processing works very well against spammers that send -a large number of messages at once, but it requires the user to set up -fairly complicated checks. There are commercial and free distributed -spam processing systems. Distributed spam processing has its risks as -well. For instance legitimate e-mail senders have been accused of -sending spam, and their web sites and mailing lists have been shut -down for some time because of the incident. - -The statistical approach to spam filtering is also popular. It is -based on a statistical analysis of previous spam messages. Usually -the analysis is a simple word frequency count, with perhaps pairs of -words or 3-word combinations thrown into the mix. Statistical -analysis of spam works very well in most of the cases, but it can -classify legitimate e-mail as spam in some cases. It takes time to -run the analysis, the full message must be analyzed, and the user has -to store the database of spam analysis. Statistical analysis on the -server is gaining popularity. This has the advantage of letting the -user Just Read Mail, but has the disadvantage that it's harder to tell -the server that it has misclassified mail. - -Fighting spam is not easy, no matter what anyone says. There is no -magic switch that will distinguish Viagra ads from Mom's e-mails. -Even people are having a hard time telling spam apart from non-spam, -because spammers are actively looking to fool us into thinking they -are Mom, essentially. Spamming is irritating, irresponsible, and -idiotic behavior from a bunch of people who think the world owes them -a favor. We hope the following sections will help you in fighting the -spam plague. - -@node Anti-Spam Basics -@subsection Anti-Spam Basics -@cindex email spam -@cindex spam -@cindex UCE -@cindex unsolicited commercial email - -One way of dealing with spam is having Gnus split out all spam into a -@samp{spam} mail group (@pxref{Splitting Mail}). - -First, pick one (1) valid mail address that you can be reached at, and -put it in your @code{From} header of all your news articles. (I've -chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form -@samp{larsi+usenet@@ifi.uio.no} will be a better choice. Ask your -sysadmin whether your sendmail installation accepts keywords in the local -part of the mail address.) - -@lisp -(setq message-default-news-headers - "From: Lars Magne Ingebrigtsen \n") -@end lisp - -Then put the following split rule in @code{nnmail-split-fancy} -(@pxref{Fancy Mail Splitting}): - -@lisp -(... - (to "larsi@@trym.ifi.uio.no" - (| ("subject" "re:.*" "misc") - ("references" ".*@@.*" "misc") - "spam")) - ...) -@end lisp - -This says that all mail to this address is suspect, but if it has a -@code{Subject} that starts with a @samp{Re:} or has a @code{References} -header, it's probably ok. All the rest goes to the @samp{spam} group. -(This idea probably comes from Tim Pierce.) - -In addition, many mail spammers talk directly to your @acronym{SMTP} server -and do not include your email address explicitly in the @code{To} -header. Why they do this is unknown---perhaps it's to thwart this -thwarting scheme? In any case, this is trivial to deal with---you just -put anything not addressed to you in the @samp{spam} group by ending -your fancy split rule in this way: - -@lisp -( - ... - (to "larsi" "misc") - "spam") -@end lisp - -In my experience, this will sort virtually everything into the right -group. You still have to check the @samp{spam} group from time to time to -check for legitimate mail, though. If you feel like being a good net -citizen, you can even send off complaints to the proper authorities on -each unsolicited commercial email---at your leisure. - -This works for me. It allows people an easy way to contact me (they can -just press @kbd{r} in the usual way), and I'm not bothered at all with -spam. It's a win-win situation. Forging @code{From} headers to point -to non-existent domains is yucky, in my opinion. - -Be careful with this approach. Spammers are wise to it. - - -@node SpamAssassin -@subsection SpamAssassin, Vipul's Razor, DCC, etc -@cindex SpamAssassin -@cindex Vipul's Razor -@cindex DCC - -The days where the hints in the previous section were sufficient in -avoiding spam are coming to an end. There are many tools out there -that claim to reduce the amount of spam you get. This section could -easily become outdated fast, as new products replace old, but -fortunately most of these tools seem to have similar interfaces. Even -though this section will use SpamAssassin as an example, it should be -easy to adapt it to most other tools. - -Note that this section does not involve the @code{spam.el} package, -which is discussed in the next section. If you don't care for all -the features of @code{spam.el}, you can make do with these simple -recipes. - -If the tool you are using is not installed on the mail server, you -need to invoke it yourself. Ideas on how to use the -@code{:postscript} mail source parameter (@pxref{Mail Source -Specifiers}) follow. - -@lisp -(setq mail-sources - '((file :prescript "formail -bs spamassassin < /var/mail/%u") - (pop :user "jrl" - :server "pophost" - :postscript - "mv %t /tmp/foo; formail -bs spamc < /tmp/foo > %t"))) -@end lisp - -Once you manage to process your incoming spool somehow, thus making -the mail contain, e.g., a header indicating it is spam, you are ready to -filter it out. Using normal split methods (@pxref{Splitting Mail}): - -@lisp -(setq nnmail-split-methods '(("spam" "^X-Spam-Flag: YES") - ...)) -@end lisp - -Or using fancy split methods (@pxref{Fancy Mail Splitting}): - -@lisp -(setq nnmail-split-methods 'nnmail-split-fancy - nnmail-split-fancy '(| ("X-Spam-Flag" "YES" "spam") - ...)) -@end lisp - -Some people might not like the idea of piping the mail through various -programs using a @code{:prescript} (if some program is buggy, you -might lose all mail). If you are one of them, another solution is to -call the external tools during splitting. Example fancy split method: - -@lisp -(setq nnmail-split-fancy '(| (: kevin-spamassassin) - ...)) -(defun kevin-spamassassin () - (save-excursion - (save-restriction - (widen) - (if (eq 1 (call-process-region (point-min) (point-max) - "spamc" nil nil nil "-c")) - "spam")))) -@end lisp - -Note that with the nnimap back end, message bodies will not be -downloaded by default. You need to set -@code{nnimap-split-download-body} to @code{t} to do that -(@pxref{Client-Side IMAP Splitting}). - -That is about it. As some spam is likely to get through anyway, you -might want to have a nifty function to call when you happen to read -spam. And here is the nifty function: - -@lisp -(defun my-gnus-raze-spam () - "Submit SPAM to Vipul's Razor, then mark it as expirable." - (interactive) - (gnus-summary-save-in-pipe "razor-report -f -d" t) - (gnus-summary-mark-as-expirable 1)) -@end lisp - -@node Hashcash -@subsection Hashcash -@cindex hashcash - -A novel technique to fight spam is to require senders to do something -costly and demonstrably unique for each message they send. This has -the obvious drawback that you cannot rely on everyone in the world -using this technique, since it is not part of the Internet standards, -but it may be useful in smaller communities. - -While the tools in the previous section work well in practice, they -work only because the tools are constantly maintained and updated as -new form of spam appears. This means that a small percentage of spam -will always get through. It also means that somewhere, someone needs -to read lots of spam to update these tools. Hashcash avoids that, but -instead prefers that everyone you contact through e-mail supports the -scheme. You can view the two approaches as pragmatic vs dogmatic. -The approaches have their own advantages and disadvantages, but as -often in the real world, a combination of them is stronger than either -one of them separately. - -@cindex X-Hashcash -The ``something costly'' is to burn CPU time, more specifically to -compute a hash collision up to a certain number of bits. The -resulting hashcash cookie is inserted in a @samp{X-Hashcash:} header. -For more details, and for the external application @code{hashcash} you -need to install to use this feature, see -@uref{http://www.hashcash.org/}. Even more information can be found -at @uref{http://www.camram.org/}. - -If you wish to generate hashcash for each message you send, you can -customize @code{message-generate-hashcash} (@pxref{Mail Headers, ,Mail -Headers,message, The Message Manual}), as in: - -@lisp -(setq message-generate-hashcash t) -@end lisp - -You will need to set up some additional variables as well: - -@table @code - -@item hashcash-default-payment -@vindex hashcash-default-payment -This variable indicates the default number of bits the hash collision -should consist of. By default this is 20. Suggested useful values -include 17 to 29. - -@item hashcash-payment-alist -@vindex hashcash-payment-alist -Some receivers may require you to spend burn more CPU time than the -default. This variable contains a list of @samp{(@var{addr} -@var{amount})} cells, where @var{addr} is the receiver (email address -or newsgroup) and @var{amount} is the number of bits in the collision -that is needed. It can also contain @samp{(@var{addr} @var{string} -@var{amount})} cells, where the @var{string} is the string to use -(normally the email address or newsgroup name is used). - -@item hashcash-path -@vindex hashcash-path -Where the @code{hashcash} binary is installed. This variable should -be automatically set by @code{executable-find}, but if it's @code{nil} -(usually because the @code{hashcash} binary is not in your path) -you'll get a warning when you check hashcash payments and an error -when you generate hashcash payments. - -@end table - -Gnus can verify hashcash cookies, although this can also be done by -hand customized mail filtering scripts. To verify a hashcash cookie -in a message, use the @code{mail-check-payment} function in the -@code{hashcash.el} library. You can also use the @code{spam.el} -package with the @code{spam-use-hashcash} back end to validate hashcash -cookies in incoming mail and filter mail accordingly (@pxref{Anti-spam -Hashcash Payments}). - -@node Spam Package -@section Spam Package -@cindex spam filtering -@cindex spam - -The Spam package provides Gnus with a centralized mechanism for -detecting and filtering spam. It filters new mail, and processes -messages according to whether they are spam or ham. (@dfn{Ham} is the -name used throughout this manual to indicate non-spam messages.) - -@menu -* Spam Package Introduction:: -* Filtering Incoming Mail:: -* Detecting Spam in Groups:: -* Spam and Ham Processors:: -* Spam Package Configuration Examples:: -* Spam Back Ends:: -* Extending the Spam package:: -* Spam Statistics Package:: -@end menu - -@node Spam Package Introduction -@subsection Spam Package Introduction -@cindex spam filtering -@cindex spam filtering sequence of events -@cindex spam - -You must read this section to understand how the Spam package works. -Do not skip, speed-read, or glance through this section. - -Make sure you read the section on the @code{spam.el} sequence of -events. See @xref{Extending the Spam package}. - -@cindex spam-initialize -@vindex spam-use-stat -To use the Spam package, you @strong{must} first run the function -@code{spam-initialize}: - -@example -(spam-initialize) -@end example - -This autoloads @code{spam.el} and installs the various hooks necessary -to let the Spam package do its job. In order to make use of the Spam -package, you have to set up certain group parameters and variables, -which we will describe below. All of the variables controlling the -Spam package can be found in the @samp{spam} customization group. - -There are two ``contact points'' between the Spam package and the rest -of Gnus: checking new mail for spam, and leaving a group. - -Checking new mail for spam is done in one of two ways: while splitting -incoming mail, or when you enter a group. - -The first way, checking for spam while splitting incoming mail, is -suited to mail back ends such as @code{nnml} or @code{nnimap}, where -new mail appears in a single spool file. The Spam package processes -incoming mail, and sends mail considered to be spam to a designated -``spam'' group. @xref{Filtering Incoming Mail}. - -The second way is suited to back ends such as @code{nntp}, which have -no incoming mail spool, or back ends where the server is in charge of -splitting incoming mail. In this case, when you enter a Gnus group, -the unseen or unread messages in that group are checked for spam. -Detected spam messages are marked as spam. @xref{Detecting Spam in -Groups}. - -@cindex spam back ends -In either case, you have to tell the Spam package what method to use -to detect spam messages. There are several methods, or @dfn{spam back -ends} (not to be confused with Gnus back ends!) to choose from: spam -``blacklists'' and ``whitelists'', dictionary-based filters, and so -forth. @xref{Spam Back Ends}. - -In the Gnus summary buffer, messages that have been identified as spam -always appear with a @samp{$} symbol. - -The Spam package divides Gnus groups into three categories: ham -groups, spam groups, and unclassified groups. You should mark each of -the groups you subscribe to as either a ham group or a spam group, -using the @code{spam-contents} group parameter (@pxref{Group -Parameters}). Spam groups have a special property: when you enter a -spam group, all unseen articles are marked as spam. Thus, mail split -into a spam group is automatically marked as spam. - -Identifying spam messages is only half of the Spam package's job. The -second half comes into play whenever you exit a group buffer. At this -point, the Spam package does several things: - -First, it calls @dfn{spam and ham processors} to process the articles -according to whether they are spam or ham. There is a pair of spam -and ham processors associated with each spam back end, and what the -processors do depends on the back end. At present, the main role of -spam and ham processors is for dictionary-based spam filters: they add -the contents of the messages in the group to the filter's dictionary, -to improve its ability to detect future spam. The @code{spam-process} -group parameter specifies what spam processors to use. @xref{Spam and -Ham Processors}. - -If the spam filter failed to mark a spam message, you can mark it -yourself, so that the message is processed as spam when you exit the -group: - -@table @kbd -@item $ -@itemx M-d -@itemx M s x -@itemx S x -@kindex $ (Summary) -@kindex M-d (Summary) -@kindex S x (Summary) -@kindex M s x (Summary) -@findex gnus-summary-mark-as-spam -@findex gnus-summary-mark-as-spam -Mark current article as spam, showing it with the @samp{$} mark -(@code{gnus-summary-mark-as-spam}). -@end table - -@noindent -Similarly, you can unmark an article if it has been erroneously marked -as spam. @xref{Setting Marks}. - -Normally, a ham message found in a non-ham group is not processed as -ham---the rationale is that it should be moved into a ham group for -further processing (see below). However, you can force these articles -to be processed as ham by setting -@code{spam-process-ham-in-spam-groups} and -@code{spam-process-ham-in-nonham-groups}. - -@vindex gnus-ham-process-destinations -@vindex gnus-spam-process-destinations -The second thing that the Spam package does when you exit a group is -to move ham articles out of spam groups, and spam articles out of ham -groups. Ham in a spam group is moved to the group specified by the -variable @code{gnus-ham-process-destinations}, or the group parameter -@code{ham-process-destination}. Spam in a ham group is moved to the -group specified by the variable @code{gnus-spam-process-destinations}, -or the group parameter @code{spam-process-destination}. If these -variables are not set, the articles are left in their current group. -If an article cannot be moved (e.g., with a read-only backend such -as @acronym{NNTP}), it is copied. - -If an article is moved to another group, it is processed again when -you visit the new group. Normally, this is not a problem, but if you -want each article to be processed only once, load the -@code{gnus-registry.el} package and set the variable -@code{spam-log-to-registry} to @code{t}. @xref{Spam Package -Configuration Examples}. - -Normally, spam groups ignore @code{gnus-spam-process-destinations}. -However, if you set @code{spam-move-spam-nonspam-groups-only} to -@code{nil}, spam will also be moved out of spam groups, depending on -the @code{spam-process-destination} parameter. - -The final thing the Spam package does is to mark spam articles as -expired, which is usually the right thing to do. - -If all this seems confusing, don't worry. Soon it will be as natural -as typing Lisp one-liners on a neural interface@dots{} err, sorry, that's -50 years in the future yet. Just trust us, it's not so bad. - -@node Filtering Incoming Mail -@subsection Filtering Incoming Mail -@cindex spam filtering -@cindex spam filtering incoming mail -@cindex spam - -To use the Spam package to filter incoming mail, you must first set up -fancy mail splitting. @xref{Fancy Mail Splitting}. The Spam package -defines a special splitting function that you can add to your fancy -split variable (either @code{nnmail-split-fancy} or -@code{nnimap-split-fancy}, depending on your mail back end): - -@example -(: spam-split) -@end example - -@vindex spam-split-group -@noindent -The @code{spam-split} function scans incoming mail according to your -chosen spam back end(s), and sends messages identified as spam to a -spam group. By default, the spam group is a group named @samp{spam}, -but you can change this by customizing @code{spam-split-group}. Make -sure the contents of @code{spam-split-group} are an unqualified group -name. For instance, in an @code{nnimap} server @samp{your-server}, -the value @samp{spam} means @samp{nnimap+your-server:spam}. The value -@samp{nnimap+server:spam} is therefore wrong---it gives the group -@samp{nnimap+your-server:nnimap+server:spam}. - -@code{spam-split} does not modify the contents of messages in any way. - -@vindex nnimap-split-download-body -Note for IMAP users: if you use the @code{spam-check-bogofilter}, -@code{spam-check-ifile}, and @code{spam-check-stat} spam back ends, -you should also set the variable @code{nnimap-split-download-body} to -@code{t}. These spam back ends are most useful when they can ``scan'' -the full message body. By default, the nnimap back end only retrieves -the message headers; @code{nnimap-split-download-body} tells it to -retrieve the message bodies as well. We don't set this by default -because it will slow @acronym{IMAP} down, and that is not an -appropriate decision to make on behalf of the user. @xref{Client-Side -IMAP Splitting}. - -You have to specify one or more spam back ends for @code{spam-split} -to use, by setting the @code{spam-use-*} variables. @xref{Spam Back -Ends}. Normally, @code{spam-split} simply uses all the spam back ends -you enabled in this way. However, you can tell @code{spam-split} to -use only some of them. Why this is useful? Suppose you are using the -@code{spam-use-regex-headers} and @code{spam-use-blackholes} spam back -ends, and the following split rule: - -@example - nnimap-split-fancy '(| - (any "ding" "ding") - (: spam-split) - ;; @r{default mailbox} - "mail") -@end example - -@noindent -The problem is that you want all ding messages to make it to the ding -folder. But that will let obvious spam (for example, spam detected by -SpamAssassin, and @code{spam-use-regex-headers}) through, when it's -sent to the ding list. On the other hand, some messages to the ding -list are from a mail server in the blackhole list, so the invocation -of @code{spam-split} can't be before the ding rule. - -The solution is to let SpamAssassin headers supersede ding rules, and -perform the other @code{spam-split} rules (including a second -invocation of the regex-headers check) after the ding rule. This is -done by passing a parameter to @code{spam-split}: - -@example -nnimap-split-fancy - '(| - ;; @r{spam detected by @code{spam-use-regex-headers} goes to @samp{regex-spam}} - (: spam-split "regex-spam" 'spam-use-regex-headers) - (any "ding" "ding") - ;; @r{all other spam detected by spam-split goes to @code{spam-split-group}} - (: spam-split) - ;; @r{default mailbox} - "mail") -@end example - -@noindent -This lets you invoke specific @code{spam-split} checks depending on -your particular needs, and target the results of those checks to a -particular spam group. You don't have to throw all mail into all the -spam tests. Another reason why this is nice is that messages to -mailing lists you have rules for don't have to have resource-intensive -blackhole checks performed on them. You could also specify different -spam checks for your nnmail split vs. your nnimap split. Go crazy. - -You should set the @code{spam-use-*} variables for whatever spam back -ends you intend to use. The reason is that when loading -@file{spam.el}, some conditional loading is done depending on what -@code{spam-use-xyz} variables you have set. @xref{Spam Back Ends}. - -@c @emph{TODO: spam.el needs to provide a uniform way of training all the -@c statistical databases. Some have that functionality built-in, others -@c don't.} - -@node Detecting Spam in Groups -@subsection Detecting Spam in Groups - -To detect spam when visiting a group, set the group's -@code{spam-autodetect} and @code{spam-autodetect-methods} group -parameters. These are accessible with @kbd{G c} or @kbd{G p}, as -usual (@pxref{Group Parameters}). - -You should set the @code{spam-use-*} variables for whatever spam back -ends you intend to use. The reason is that when loading -@file{spam.el}, some conditional loading is done depending on what -@code{spam-use-xyz} variables you have set. - -By default, only unseen articles are processed for spam. You can -force Gnus to recheck all messages in the group by setting the -variable @code{spam-autodetect-recheck-messages} to @code{t}. - -If you use the @code{spam-autodetect} method of checking for spam, you -can specify different spam detection methods for different groups. -For instance, the @samp{ding} group may have @code{spam-use-BBDB} as -the autodetection method, while the @samp{suspect} group may have the -@code{spam-use-blacklist} and @code{spam-use-bogofilter} methods -enabled. Unlike with @code{spam-split}, you don't have any control -over the @emph{sequence} of checks, but this is probably unimportant. - -@node Spam and Ham Processors -@subsection Spam and Ham Processors -@cindex spam filtering -@cindex spam filtering variables -@cindex spam variables -@cindex spam - -@vindex gnus-spam-process-newsgroups -Spam and ham processors specify special actions to take when you exit -a group buffer. Spam processors act on spam messages, and ham -processors on ham messages. At present, the main role of these -processors is to update the dictionaries of dictionary-based spam back -ends such as Bogofilter (@pxref{Bogofilter}) and the Spam Statistics -package (@pxref{Spam Statistics Filtering}). - -The spam and ham processors that apply to each group are determined by -the group's@code{spam-process} group parameter. If this group -parameter is not defined, they are determined by the variable -@code{gnus-spam-process-newsgroups}. - -@vindex gnus-spam-newsgroup-contents -Gnus learns from the spam you get. You have to collect your spam in -one or more spam groups, and set or customize the variable -@code{spam-junk-mailgroups} as appropriate. You can also declare -groups to contain spam by setting their group parameter -@code{spam-contents} to @code{gnus-group-spam-classification-spam}, or -by customizing the corresponding variable -@code{gnus-spam-newsgroup-contents}. The @code{spam-contents} group -parameter and the @code{gnus-spam-newsgroup-contents} variable can -also be used to declare groups as @emph{ham} groups if you set their -classification to @code{gnus-group-spam-classification-ham}. If -groups are not classified by means of @code{spam-junk-mailgroups}, -@code{spam-contents}, or @code{gnus-spam-newsgroup-contents}, they are -considered @emph{unclassified}. All groups are unclassified by -default. - -@vindex gnus-spam-mark -@cindex $ -In spam groups, all messages are considered to be spam by default: -they get the @samp{$} mark (@code{gnus-spam-mark}) when you enter the -group. If you have seen a message, had it marked as spam, then -unmarked it, it won't be marked as spam when you enter the group -thereafter. You can disable that behavior, so all unread messages -will get the @samp{$} mark, if you set the -@code{spam-mark-only-unseen-as-spam} parameter to @code{nil}. You -should remove the @samp{$} mark when you are in the group summary -buffer for every message that is not spam after all. To remove the -@samp{$} mark, you can use @kbd{M-u} to ``unread'' the article, or -@kbd{d} for declaring it read the non-spam way. When you leave a -group, all spam-marked (@samp{$}) articles are sent to a spam -processor which will study them as spam samples. - -Messages may also be deleted in various other ways, and unless -@code{ham-marks} group parameter gets overridden below, marks @samp{R} -and @samp{r} for default read or explicit delete, marks @samp{X} and -@samp{K} for automatic or explicit kills, as well as mark @samp{Y} for -low scores, are all considered to be associated with articles which -are not spam. This assumption might be false, in particular if you -use kill files or score files as means for detecting genuine spam, you -should then adjust the @code{ham-marks} group parameter. - -@defvar ham-marks -You can customize this group or topic parameter to be the list of -marks you want to consider ham. By default, the list contains the -deleted, read, killed, kill-filed, and low-score marks (the idea is -that these articles have been read, but are not spam). It can be -useful to also include the tick mark in the ham marks. It is not -recommended to make the unread mark a ham mark, because it normally -indicates a lack of classification. But you can do it, and we'll be -happy for you. -@end defvar - -@defvar spam-marks -You can customize this group or topic parameter to be the list of -marks you want to consider spam. By default, the list contains only -the spam mark. It is not recommended to change that, but you can if -you really want to. -@end defvar - -When you leave @emph{any} group, regardless of its -@code{spam-contents} classification, all spam-marked articles are sent -to a spam processor, which will study these as spam samples. If you -explicit kill a lot, you might sometimes end up with articles marked -@samp{K} which you never saw, and which might accidentally contain -spam. Best is to make sure that real spam is marked with @samp{$}, -and nothing else. - -@vindex gnus-ham-process-destinations -When you leave a @emph{spam} group, all spam-marked articles are -marked as expired after processing with the spam processor. This is -not done for @emph{unclassified} or @emph{ham} groups. Also, any -@strong{ham} articles in a spam group will be moved to a location -determined by either the @code{ham-process-destination} group -parameter or a match in the @code{gnus-ham-process-destinations} -variable, which is a list of regular expressions matched with group -names (it's easiest to customize this variable with @kbd{M-x -customize-variable @key{RET} gnus-ham-process-destinations}). Each -group name list is a standard Lisp list, if you prefer to customize -the variable manually. If the @code{ham-process-destination} -parameter is not set, ham articles are left in place. If the -@code{spam-mark-ham-unread-before-move-from-spam-group} parameter is -set, the ham articles are marked as unread before being moved. - -If ham can not be moved---because of a read-only back end such as -@acronym{NNTP}, for example, it will be copied. - -Note that you can use multiples destinations per group or regular -expression! This enables you to send your ham to a regular mail -group and to a @emph{ham training} group. - -When you leave a @emph{ham} group, all ham-marked articles are sent to -a ham processor, which will study these as non-spam samples. - -@vindex spam-process-ham-in-spam-groups -By default the variable @code{spam-process-ham-in-spam-groups} is -@code{nil}. Set it to @code{t} if you want ham found in spam groups -to be processed. Normally this is not done, you are expected instead -to send your ham to a ham group and process it there. - -@vindex spam-process-ham-in-nonham-groups -By default the variable @code{spam-process-ham-in-nonham-groups} is -@code{nil}. Set it to @code{t} if you want ham found in non-ham (spam -or unclassified) groups to be processed. Normally this is not done, -you are expected instead to send your ham to a ham group and process -it there. - -@vindex gnus-spam-process-destinations -When you leave a @emph{ham} or @emph{unclassified} group, all -@strong{spam} articles are moved to a location determined by either -the @code{spam-process-destination} group parameter or a match in the -@code{gnus-spam-process-destinations} variable, which is a list of -regular expressions matched with group names (it's easiest to -customize this variable with @kbd{M-x customize-variable @key{RET} -gnus-spam-process-destinations}). Each group name list is a standard -Lisp list, if you prefer to customize the variable manually. If the -@code{spam-process-destination} parameter is not set, the spam -articles are only expired. The group name is fully qualified, meaning -that if you see @samp{nntp:servername} before the group name in the -group buffer then you need it here as well. - -If spam can not be moved---because of a read-only back end such as -@acronym{NNTP}, for example, it will be copied. - -Note that you can use multiples destinations per group or regular -expression! This enables you to send your spam to multiple @emph{spam -training} groups. - -@vindex spam-log-to-registry -The problem with processing ham and spam is that Gnus doesn't track -this processing by default. Enable the @code{spam-log-to-registry} -variable so @code{spam.el} will use @code{gnus-registry.el} to track -what articles have been processed, and avoid processing articles -multiple times. Keep in mind that if you limit the number of registry -entries, this won't work as well as it does without a limit. - -@vindex spam-mark-only-unseen-as-spam -Set this variable if you want only unseen articles in spam groups to -be marked as spam. By default, it is set. If you set it to -@code{nil}, unread articles will also be marked as spam. - -@vindex spam-mark-ham-unread-before-move-from-spam-group -Set this variable if you want ham to be unmarked before it is moved -out of the spam group. This is very useful when you use something -like the tick mark @samp{!} to mark ham---the article will be placed -in your @code{ham-process-destination}, unmarked as if it came fresh -from the mail server. - -@vindex spam-autodetect-recheck-messages -When autodetecting spam, this variable tells @code{spam.el} whether -only unseen articles or all unread articles should be checked for -spam. It is recommended that you leave it off. - -@node Spam Package Configuration Examples -@subsection Spam Package Configuration Examples -@cindex spam filtering -@cindex spam filtering configuration examples -@cindex spam configuration examples -@cindex spam - -@subsubheading Ted's setup - -From Ted Zlatanov . -@example -;; @r{for @code{gnus-registry-split-fancy-with-parent} and spam autodetection} -;; @r{see @file{gnus-registry.el} for more information} -(gnus-registry-initialize) -(spam-initialize) - -(setq - spam-log-to-registry t ; @r{for spam autodetection} - spam-use-BBDB t - spam-use-regex-headers t ; @r{catch X-Spam-Flag (SpamAssassin)} - ;; @r{all groups with @samp{spam} in the name contain spam} - gnus-spam-newsgroup-contents - '(("spam" gnus-group-spam-classification-spam)) - ;; @r{see documentation for these} - spam-move-spam-nonspam-groups-only nil - spam-mark-only-unseen-as-spam t - spam-mark-ham-unread-before-move-from-spam-group t - ;; @r{understand what this does before you copy it to your own setup!} - ;; @r{for nnimap you'll probably want to set nnimap-split-methods, see the manual} - nnimap-split-fancy '(| - ;; @r{trace references to parents and put in their group} - (: gnus-registry-split-fancy-with-parent) - ;; @r{this will catch server-side SpamAssassin tags} - (: spam-split 'spam-use-regex-headers) - (any "ding" "ding") - ;; @r{note that spam by default will go to @samp{spam}} - (: spam-split) - ;; @r{default mailbox} - "mail")) - -;; @r{my parameters, set with @kbd{G p}} - -;; @r{all nnml groups, and all nnimap groups except} -;; @r{@samp{nnimap+mail.lifelogs.com:train} and} -;; @r{@samp{nnimap+mail.lifelogs.com:spam}: any spam goes to nnimap training,} -;; @r{because it must have been detected manually} - -((spam-process-destination . "nnimap+mail.lifelogs.com:train")) - -;; @r{all @acronym{NNTP} groups} -;; @r{autodetect spam with the blacklist and ham with the BBDB} -((spam-autodetect-methods spam-use-blacklist spam-use-BBDB) -;; @r{send all spam to the training group} - (spam-process-destination . "nnimap+mail.lifelogs.com:train")) - -;; @r{only some @acronym{NNTP} groups, where I want to autodetect spam} -((spam-autodetect . t)) - -;; @r{my nnimap @samp{nnimap+mail.lifelogs.com:spam} group} - -;; @r{this is a spam group} -((spam-contents gnus-group-spam-classification-spam) - - ;; @r{any spam (which happens when I enter for all unseen messages,} - ;; @r{because of the @code{gnus-spam-newsgroup-contents} setting above), goes to} - ;; @r{@samp{nnimap+mail.lifelogs.com:train} unless I mark it as ham} - - (spam-process-destination "nnimap+mail.lifelogs.com:train") - - ;; @r{any ham goes to my @samp{nnimap+mail.lifelogs.com:mail} folder, but} - ;; @r{also to my @samp{nnimap+mail.lifelogs.com:trainham} folder for training} - - (ham-process-destination "nnimap+mail.lifelogs.com:mail" - "nnimap+mail.lifelogs.com:trainham") - ;; @r{in this group, only @samp{!} marks are ham} - (ham-marks - (gnus-ticked-mark)) - ;; @r{remembers senders in the blacklist on the way out---this is} - ;; @r{definitely not needed, it just makes me feel better} - (spam-process (gnus-group-spam-exit-processor-blacklist))) - -;; @r{Later, on the @acronym{IMAP} server I use the @samp{train} group for training} -;; @r{SpamAssassin to recognize spam, and the @samp{trainham} group fora} -;; @r{recognizing ham---but Gnus has nothing to do with it.} - -@end example - -@subsubheading Using @code{spam.el} on an IMAP server with a statistical filter on the server -From Reiner Steib . - -My provider has set up bogofilter (in combination with @acronym{DCC}) on -the mail server (@acronym{IMAP}). Recognized spam goes to -@samp{spam.detected}, the rest goes through the normal filter rules, -i.e., to @samp{some.folder} or to @samp{INBOX}. Training on false -positives or negatives is done by copying or moving the article to -@samp{training.ham} or @samp{training.spam} respectively. A cron job on -the server feeds those to bogofilter with the suitable ham or spam -options and deletes them from the @samp{training.ham} and -@samp{training.spam} folders. - -With the following entries in @code{gnus-parameters}, @code{spam.el} -does most of the job for me: - -@lisp - ("nnimap:spam\\.detected" - (gnus-article-sort-functions '(gnus-article-sort-by-chars)) - (ham-process-destination "nnimap:INBOX" "nnimap:training.ham") - (spam-contents gnus-group-spam-classification-spam)) - ("nnimap:\\(INBOX\\|other-folders\\)" - (spam-process-destination . "nnimap:training.spam") - (spam-contents gnus-group-spam-classification-ham)) -@end lisp - -@itemize - -@item @b{The Spam folder:} - -In the folder @samp{spam.detected}, I have to check for false positives -(i.e., legitimate mails, that were wrongly judged as spam by -bogofilter or DCC). - -Because of the @code{gnus-group-spam-classification-spam} entry, all -messages are marked as spam (with @code{$}). When I find a false -positive, I mark the message with some other ham mark -(@code{ham-marks}, @ref{Spam and Ham Processors}). On group exit, -those messages are copied to both groups, @samp{INBOX} (where I want -to have the article) and @samp{training.ham} (for training bogofilter) -and deleted from the @samp{spam.detected} folder. - -The @code{gnus-article-sort-by-chars} entry simplifies detection of -false positives for me. I receive lots of worms (sweN, @dots{}), that all -have a similar size. Grouping them by size (i.e., chars) makes finding -other false positives easier. (Of course worms aren't @i{spam} -(@acronym{UCE}, @acronym{UBE}) strictly speaking. Anyhow, bogofilter is -an excellent tool for filtering those unwanted mails for me.) - -@item @b{Ham folders:} - -In my ham folders, I just hit @kbd{S x} -(@code{gnus-summary-mark-as-spam}) whenever I see an unrecognized spam -mail (false negative). On group exit, those messages are moved to -@samp{training.spam}. -@end itemize - -@subsubheading Reporting spam articles in Gmane groups with @code{spam-report.el} - -From Reiner Steib . - -With following entry in @code{gnus-parameters}, @kbd{S x} -(@code{gnus-summary-mark-as-spam}) marks articles in @code{gmane.*} -groups as spam and reports the to Gmane at group exit: - -@lisp - ("^gmane\\." - (spam-process (gnus-group-spam-exit-processor-report-gmane))) -@end lisp - -Additionally, I use @code{(setq spam-report-gmane-use-article-number nil)} -because I don't read the groups directly from news.gmane.org, but -through my local news server (leafnode). I.e., the article numbers are -not the same as on news.gmane.org, thus @code{spam-report.el} has to check -the @code{X-Report-Spam} header to find the correct number. - -@node Spam Back Ends -@subsection Spam Back Ends -@cindex spam back ends - -The spam package offers a variety of back ends for detecting spam. -Each back end defines a set of methods for detecting spam -(@pxref{Filtering Incoming Mail}, @pxref{Detecting Spam in Groups}), -and a pair of spam and ham processors (@pxref{Spam and Ham -Processors}). - -@menu -* Blacklists and Whitelists:: -* BBDB Whitelists:: -* Gmane Spam Reporting:: -* Anti-spam Hashcash Payments:: -* Blackholes:: -* Regular Expressions Header Matching:: -* Bogofilter:: -* SpamAssassin back end:: -* ifile spam filtering:: -* Spam Statistics Filtering:: -* SpamOracle:: -@end menu - -@node Blacklists and Whitelists -@subsubsection Blacklists and Whitelists -@cindex spam filtering -@cindex whitelists, spam filtering -@cindex blacklists, spam filtering -@cindex spam - -@defvar spam-use-blacklist - -Set this variable to @code{t} if you want to use blacklists when -splitting incoming mail. Messages whose senders are in the blacklist -will be sent to the @code{spam-split-group}. This is an explicit -filter, meaning that it acts only on mail senders @emph{declared} to -be spammers. - -@end defvar - -@defvar spam-use-whitelist - -Set this variable to @code{t} if you want to use whitelists when -splitting incoming mail. Messages whose senders are not in the -whitelist will be sent to the next spam-split rule. This is an -explicit filter, meaning that unless someone is in the whitelist, their -messages are not assumed to be spam or ham. - -@end defvar - -@defvar spam-use-whitelist-exclusive - -Set this variable to @code{t} if you want to use whitelists as an -implicit filter, meaning that every message will be considered spam -unless the sender is in the whitelist. Use with care. - -@end defvar - -@defvar gnus-group-spam-exit-processor-blacklist - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the senders of -spam-marked articles will be added to the blacklist. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-blacklist}, it is recommended -that you use @code{(spam spam-use-blacklist)}. Everything will work -the same way, we promise. - -@end defvar - -@defvar gnus-group-ham-exit-processor-whitelist - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the senders of -ham-marked articles in @emph{ham} groups will be added to the -whitelist. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-whitelist}, it is recommended -that you use @code{(ham spam-use-whitelist)}. Everything will work -the same way, we promise. - -@end defvar - -Blacklists are lists of regular expressions matching addresses you -consider to be spam senders. For instance, to block mail from any -sender at @samp{vmadmin.com}, you can put @samp{vmadmin.com} in your -blacklist. You start out with an empty blacklist. Blacklist entries -use the Emacs regular expression syntax. - -Conversely, whitelists tell Gnus what addresses are considered -legitimate. All messages from whitelisted addresses are considered -non-spam. Also see @ref{BBDB Whitelists}. Whitelist entries use the -Emacs regular expression syntax. - -The blacklist and whitelist file locations can be customized with the -@code{spam-directory} variable (@file{~/News/spam} by default), or -the @code{spam-whitelist} and @code{spam-blacklist} variables -directly. The whitelist and blacklist files will by default be in the -@code{spam-directory} directory, named @file{whitelist} and -@file{blacklist} respectively. - -@node BBDB Whitelists -@subsubsection BBDB Whitelists -@cindex spam filtering -@cindex BBDB whitelists, spam filtering -@cindex BBDB, spam filtering -@cindex spam - -@defvar spam-use-BBDB - -Analogous to @code{spam-use-whitelist} (@pxref{Blacklists and -Whitelists}), but uses the BBDB as the source of whitelisted -addresses, without regular expressions. You must have the BBDB loaded -for @code{spam-use-BBDB} to work properly. Messages whose senders are -not in the BBDB will be sent to the next spam-split rule. This is an -explicit filter, meaning that unless someone is in the BBDB, their -messages are not assumed to be spam or ham. - -@end defvar - -@defvar spam-use-BBDB-exclusive - -Set this variable to @code{t} if you want to use the BBDB as an -implicit filter, meaning that every message will be considered spam -unless the sender is in the BBDB@. Use with care. Only sender -addresses in the BBDB will be allowed through; all others will be -classified as spammers. - -While @code{spam-use-BBDB-exclusive} @emph{can} be used as an alias -for @code{spam-use-BBDB} as far as @code{spam.el} is concerned, it is -@emph{not} a separate back end. If you set -@code{spam-use-BBDB-exclusive} to @code{t}, @emph{all} your BBDB splitting -will be exclusive. - -@end defvar - -@defvar gnus-group-ham-exit-processor-BBDB - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the senders of -ham-marked articles in @emph{ham} groups will be added to the -BBDB. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-BBDB}, it is recommended -that you use @code{(ham spam-use-BBDB)}. Everything will work -the same way, we promise. - -@end defvar - -@node Gmane Spam Reporting -@subsubsection Gmane Spam Reporting -@cindex spam reporting -@cindex Gmane, spam reporting -@cindex Gmane, spam reporting -@cindex spam - -@defvar gnus-group-spam-exit-processor-report-gmane - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the spam-marked -articles groups will be reported to the Gmane administrators via a -HTTP request. - -Gmane can be found at @uref{http://gmane.org}. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-report-gmane}, it is recommended -that you use @code{(spam spam-use-gmane)}. Everything will work the -same way, we promise. - -@end defvar - -@defvar spam-report-gmane-use-article-number - -This variable is @code{t} by default. Set it to @code{nil} if you are -running your own news server, for instance, and the local article -numbers don't correspond to the Gmane article numbers. When -@code{spam-report-gmane-use-article-number} is @code{nil}, -@code{spam-report.el} will fetch the number from the article headers. - -@end defvar - -@defvar spam-report-user-mail-address - -Mail address exposed in the User-Agent spam reports to Gmane. It allows -the Gmane administrators to contact you in case of misreports. The -default is @code{user-mail-address}. - -@end defvar - -@node Anti-spam Hashcash Payments -@subsubsection Anti-spam Hashcash Payments -@cindex spam filtering -@cindex hashcash, spam filtering -@cindex spam - -@defvar spam-use-hashcash - -Similar to @code{spam-use-whitelist} (@pxref{Blacklists and -Whitelists}), but uses hashcash tokens for whitelisting messages -instead of the sender address. Messages without a hashcash payment -token will be sent to the next spam-split rule. This is an explicit -filter, meaning that unless a hashcash token is found, the messages -are not assumed to be spam or ham. - -@end defvar - -@node Blackholes -@subsubsection Blackholes -@cindex spam filtering -@cindex blackholes, spam filtering -@cindex spam - -@defvar spam-use-blackholes - -This option is disabled by default. You can let Gnus consult the -blackhole-type distributed spam processing systems (DCC, for instance) -when you set this option. The variable @code{spam-blackhole-servers} -holds the list of blackhole servers Gnus will consult. The current -list is fairly comprehensive, but make sure to let us know if it -contains outdated servers. - -The blackhole check uses the @code{dig.el} package, but you can tell -@code{spam.el} to use @code{dns.el} instead for better performance if -you set @code{spam-use-dig} to @code{nil}. It is not recommended at -this time to set @code{spam-use-dig} to @code{nil} despite the -possible performance improvements, because some users may be unable to -use it, but you can try it and see if it works for you. - -@end defvar - -@defvar spam-blackhole-servers - -The list of servers to consult for blackhole checks. - -@end defvar - -@defvar spam-blackhole-good-server-regex - -A regular expression for IPs that should not be checked against the -blackhole server list. When set to @code{nil}, it has no effect. - -@end defvar - -@defvar spam-use-dig - -Use the @code{dig.el} package instead of the @code{dns.el} package. -The default setting of @code{t} is recommended. - -@end defvar - -Blackhole checks are done only on incoming mail. There is no spam or -ham processor for blackholes. - -@node Regular Expressions Header Matching -@subsubsection Regular Expressions Header Matching -@cindex spam filtering -@cindex regular expressions header matching, spam filtering -@cindex spam - -@defvar spam-use-regex-headers - -This option is disabled by default. You can let Gnus check the -message headers against lists of regular expressions when you set this -option. The variables @code{spam-regex-headers-spam} and -@code{spam-regex-headers-ham} hold the list of regular expressions. -Gnus will check against the message headers to determine if the -message is spam or ham, respectively. - -@end defvar - -@defvar spam-regex-headers-spam - -The list of regular expressions that, when matched in the headers of -the message, positively identify it as spam. - -@end defvar - -@defvar spam-regex-headers-ham - -The list of regular expressions that, when matched in the headers of -the message, positively identify it as ham. - -@end defvar - -Regular expression header checks are done only on incoming mail. -There is no specific spam or ham processor for regular expressions. - -@node Bogofilter -@subsubsection Bogofilter -@cindex spam filtering -@cindex bogofilter, spam filtering -@cindex spam - -@defvar spam-use-bogofilter - -Set this variable if you want @code{spam-split} to use Eric Raymond's -speedy Bogofilter. - -With a minimum of care for associating the @samp{$} mark for spam -articles only, Bogofilter training all gets fairly automatic. You -should do this until you get a few hundreds of articles in each -category, spam or not. The command @kbd{S t} in summary mode, either -for debugging or for curiosity, shows the @emph{spamicity} score of -the current article (between 0.0 and 1.0). - -Bogofilter determines if a message is spam based on a specific -threshold. That threshold can be customized, consult the Bogofilter -documentation. - -If the @code{bogofilter} executable is not in your path, Bogofilter -processing will be turned off. - -You should not enable this if you use @code{spam-use-bogofilter-headers}. - -@end defvar - -@table @kbd -@item M s t -@itemx S t -@kindex M s t -@kindex S t -@findex spam-bogofilter-score -Get the Bogofilter spamicity score (@code{spam-bogofilter-score}). -@end table - -@defvar spam-use-bogofilter-headers - -Set this variable if you want @code{spam-split} to use Eric Raymond's -speedy Bogofilter, looking only at the message headers. It works -similarly to @code{spam-use-bogofilter}, but the @code{X-Bogosity} header -must be in the message already. Normally you would do this with a -procmail recipe or something similar; consult the Bogofilter -installation documents for details. - -You should not enable this if you use @code{spam-use-bogofilter}. - -@end defvar - -@defvar gnus-group-spam-exit-processor-bogofilter -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, spam-marked articles -will be added to the Bogofilter spam database. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-bogofilter}, it is recommended -that you use @code{(spam spam-use-bogofilter)}. Everything will work -the same way, we promise. -@end defvar - -@defvar gnus-group-ham-exit-processor-bogofilter -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the ham-marked -articles in @emph{ham} groups will be added to the Bogofilter database -of non-spam messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-bogofilter}, it is recommended -that you use @code{(ham spam-use-bogofilter)}. Everything will work -the same way, we promise. -@end defvar - -@defvar spam-bogofilter-database-directory - -This is the directory where Bogofilter will store its databases. It -is not specified by default, so Bogofilter will use its own default -database directory. - -@end defvar - -The Bogofilter mail classifier is similar to @command{ifile} in intent and -purpose. A ham and a spam processor are provided, plus the -@code{spam-use-bogofilter} and @code{spam-use-bogofilter-headers} -variables to indicate to spam-split that Bogofilter should either be -used, or has already been used on the article. The 0.9.2.1 version of -Bogofilter was used to test this functionality. - -@node SpamAssassin back end -@subsubsection SpamAssassin back end -@cindex spam filtering -@cindex spamassassin, spam filtering -@cindex spam - -@defvar spam-use-spamassassin - -Set this variable if you want @code{spam-split} to use SpamAssassin. - -SpamAssassin assigns a score to each article based on a set of rules -and tests, including a Bayesian filter. The Bayesian filter can be -trained by associating the @samp{$} mark for spam articles. The -spam score can be viewed by using the command @kbd{S t} in summary -mode. - -If you set this variable, each article will be processed by -SpamAssassin when @code{spam-split} is called. If your mail is -preprocessed by SpamAssassin, and you want to just use the -SpamAssassin headers, set @code{spam-use-spamassassin-headers} -instead. - -You should not enable this if you use -@code{spam-use-spamassassin-headers}. - -@end defvar - -@defvar spam-use-spamassassin-headers - -Set this variable if your mail is preprocessed by SpamAssassin and -want @code{spam-split} to split based on the SpamAssassin headers. - -You should not enable this if you use @code{spam-use-spamassassin}. - -@end defvar - -@defvar spam-spamassassin-program - -This variable points to the SpamAssassin executable. If you have -@code{spamd} running, you can set this variable to the @code{spamc} -executable for faster processing. See the SpamAssassin documentation -for more information on @code{spamd}/@code{spamc}. - -@end defvar - -SpamAssassin is a powerful and flexible spam filter that uses a wide -variety of tests to identify spam. A ham and a spam processors are -provided, plus the @code{spam-use-spamassassin} and -@code{spam-use-spamassassin-headers} variables to indicate to -spam-split that SpamAssassin should be either used, or has already -been used on the article. The 2.63 version of SpamAssassin was used -to test this functionality. - -@node ifile spam filtering -@subsubsection ifile spam filtering -@cindex spam filtering -@cindex ifile, spam filtering -@cindex spam - -@defvar spam-use-ifile - -Enable this variable if you want @code{spam-split} to use @command{ifile}, a -statistical analyzer similar to Bogofilter. - -@end defvar - -@defvar spam-ifile-all-categories - -Enable this variable if you want @code{spam-use-ifile} to give you all -the ifile categories, not just spam/non-spam. If you use this, make -sure you train ifile as described in its documentation. - -@end defvar - -@defvar spam-ifile-spam-category - -This is the category of spam messages as far as ifile is concerned. -The actual string used is irrelevant, but you probably want to leave -the default value of @samp{spam}. -@end defvar - -@defvar spam-ifile-database - -This is the filename for the ifile database. It is not specified by -default, so ifile will use its own default database name. - -@end defvar - -The ifile mail classifier is similar to Bogofilter in intent and -purpose. A ham and a spam processor are provided, plus the -@code{spam-use-ifile} variable to indicate to spam-split that ifile -should be used. The 1.2.1 version of ifile was used to test this -functionality. - -@node Spam Statistics Filtering -@subsubsection Spam Statistics Filtering -@cindex spam filtering -@cindex spam-stat, spam filtering -@cindex spam-stat -@cindex spam - -This back end uses the Spam Statistics Emacs Lisp package to perform -statistics-based filtering (@pxref{Spam Statistics Package}). Before -using this, you may want to perform some additional steps to -initialize your Spam Statistics dictionary. @xref{Creating a -spam-stat dictionary}. - -@defvar spam-use-stat - -@end defvar - -@defvar gnus-group-spam-exit-processor-stat -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the spam-marked -articles will be added to the spam-stat database of spam messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-stat}, it is recommended -that you use @code{(spam spam-use-stat)}. Everything will work -the same way, we promise. -@end defvar - -@defvar gnus-group-ham-exit-processor-stat -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the ham-marked -articles in @emph{ham} groups will be added to the spam-stat database -of non-spam messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-stat}, it is recommended -that you use @code{(ham spam-use-stat)}. Everything will work -the same way, we promise. -@end defvar - -This enables @code{spam.el} to cooperate with @file{spam-stat.el}. -@file{spam-stat.el} provides an internal (Lisp-only) spam database, -which unlike ifile or Bogofilter does not require external programs. -A spam and a ham processor, and the @code{spam-use-stat} variable for -@code{spam-split} are provided. - -@node SpamOracle -@subsubsection Using SpamOracle with Gnus -@cindex spam filtering -@cindex SpamOracle -@cindex spam - -An easy way to filter out spam is to use SpamOracle. SpamOracle is an -statistical mail filtering tool written by Xavier Leroy and needs to be -installed separately. - -There are several ways to use SpamOracle with Gnus. In all cases, your -mail is piped through SpamOracle in its @emph{mark} mode. SpamOracle will -then enter an @samp{X-Spam} header indicating whether it regards the -mail as a spam mail or not. - -One possibility is to run SpamOracle as a @code{:prescript} from the -@xref{Mail Source Specifiers}, (@pxref{SpamAssassin}). This method has -the advantage that the user can see the @emph{X-Spam} headers. - -The easiest method is to make @file{spam.el} (@pxref{Spam Package}) -call SpamOracle. - -@vindex spam-use-spamoracle -To enable SpamOracle usage by @code{spam.el}, set the variable -@code{spam-use-spamoracle} to @code{t} and configure the -@code{nnmail-split-fancy} or @code{nnimap-split-fancy}. @xref{Spam -Package}. In this example the @samp{INBOX} of an nnimap server is -filtered using SpamOracle. Mails recognized as spam mails will be -moved to @code{spam-split-group}, @samp{Junk} in this case. Ham -messages stay in @samp{INBOX}: - -@example -(setq spam-use-spamoracle t - spam-split-group "Junk" - ;; @r{for nnimap you'll probably want to set nnimap-split-methods, see the manual} - nnimap-split-inbox '("INBOX") - nnimap-split-fancy '(| (: spam-split) "INBOX")) -@end example - -@defvar spam-use-spamoracle -Set to @code{t} if you want Gnus to enable spam filtering using -SpamOracle. -@end defvar - -@defvar spam-spamoracle-binary -Gnus uses the SpamOracle binary called @file{spamoracle} found in the -user's PATH@. Using the variable @code{spam-spamoracle-binary}, this -can be customized. -@end defvar - -@defvar spam-spamoracle-database -By default, SpamOracle uses the file @file{~/.spamoracle.db} as a database to -store its analysis. This is controlled by the variable -@code{spam-spamoracle-database} which defaults to @code{nil}. That means -the default SpamOracle database will be used. In case you want your -database to live somewhere special, set -@code{spam-spamoracle-database} to this path. -@end defvar - -SpamOracle employs a statistical algorithm to determine whether a -message is spam or ham. In order to get good results, meaning few -false hits or misses, SpamOracle needs training. SpamOracle learns -the characteristics of your spam mails. Using the @emph{add} mode -(training mode) one has to feed good (ham) and spam mails to -SpamOracle. This can be done by pressing @kbd{|} in the Summary -buffer and pipe the mail to a SpamOracle process or using -@file{spam.el}'s spam- and ham-processors, which is much more -convenient. For a detailed description of spam- and ham-processors, -@xref{Spam Package}. - -@defvar gnus-group-spam-exit-processor-spamoracle -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameter or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is added -to a group's @code{spam-process} parameter, spam-marked articles will be -sent to SpamOracle as spam samples. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-spamoracle}, it is recommended -that you use @code{(spam spam-use-spamoracle)}. Everything will work -the same way, we promise. -@end defvar - -@defvar gnus-group-ham-exit-processor-spamoracle -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameter or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is added -to a group's @code{spam-process} parameter, the ham-marked articles in -@emph{ham} groups will be sent to the SpamOracle as samples of ham -messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-spamoracle}, it is recommended -that you use @code{(ham spam-use-spamoracle)}. Everything will work -the same way, we promise. -@end defvar - -@emph{Example:} These are the Group Parameters of a group that has been -classified as a ham group, meaning that it should only contain ham -messages. -@example - ((spam-contents gnus-group-spam-classification-ham) - (spam-process ((ham spam-use-spamoracle) - (spam spam-use-spamoracle)))) -@end example -For this group the @code{spam-use-spamoracle} is installed for both -ham and spam processing. If the group contains spam message -(e.g., because SpamOracle has not had enough sample messages yet) and -the user marks some messages as spam messages, these messages will be -processed by SpamOracle. The processor sends the messages to -SpamOracle as new samples for spam. - -@node Extending the Spam package -@subsection Extending the Spam package -@cindex spam filtering -@cindex spam elisp package, extending -@cindex extending the spam elisp package - -Say you want to add a new back end called blackbox. For filtering -incoming mail, provide the following: - -@enumerate - -@item -Code - -@lisp -(defvar spam-use-blackbox nil - "True if blackbox should be used.") -@end lisp - -Write @code{spam-check-blackbox} if Blackbox can check incoming mail. - -Write @code{spam-blackbox-register-routine} and -@code{spam-blackbox-unregister-routine} using the bogofilter -register/unregister routines as a start, or other register/unregister -routines more appropriate to Blackbox, if Blackbox can -register/unregister spam and ham. - -@item -Functionality - -The @code{spam-check-blackbox} function should return @samp{nil} or -@code{spam-split-group}, observing the other conventions. See the -existing @code{spam-check-*} functions for examples of what you can -do, and stick to the template unless you fully understand the reasons -why you aren't. - -@end enumerate - -For processing spam and ham messages, provide the following: - -@enumerate - -@item -Code - -Note you don't have to provide a spam or a ham processor. Only -provide them if Blackbox supports spam or ham processing. - -Also, ham and spam processors are being phased out as single -variables. Instead the form @code{(spam spam-use-blackbox)} or -@code{(ham spam-use-blackbox)} is favored. For now, spam/ham -processor variables are still around but they won't be for long. - -@lisp -(defvar gnus-group-spam-exit-processor-blackbox "blackbox-spam" - "The Blackbox summary exit spam processor. -Only applicable to spam groups.") - -(defvar gnus-group-ham-exit-processor-blackbox "blackbox-ham" - "The whitelist summary exit ham processor. -Only applicable to non-spam (unclassified and ham) groups.") - -@end lisp - -@item -Gnus parameters - -Add -@lisp -(const :tag "Spam: Blackbox" (spam spam-use-blackbox)) -(const :tag "Ham: Blackbox" (ham spam-use-blackbox)) -@end lisp -to the @code{spam-process} group parameter in @code{gnus.el}. Make -sure you do it twice, once for the parameter and once for the -variable customization. - -Add -@lisp -(variable-item spam-use-blackbox) -@end lisp -to the @code{spam-autodetect-methods} group parameter in -@code{gnus.el} if Blackbox can check incoming mail for spam contents. - -Finally, use the appropriate @code{spam-install-*-backend} function in -@code{spam.el}. Here are the available functions. - - -@enumerate - -@item -@code{spam-install-backend-alias} - -This function will simply install an alias for a back end that does -everything like the original back end. It is currently only used to -make @code{spam-use-BBDB-exclusive} act like @code{spam-use-BBDB}. - -@item -@code{spam-install-nocheck-backend} - -This function installs a back end that has no check function, but can -register/unregister ham or spam. The @code{spam-use-gmane} back end is -such a back end. - -@item -@code{spam-install-checkonly-backend} - -This function will install a back end that can only check incoming mail -for spam contents. It can't register or unregister messages. -@code{spam-use-blackholes} and @code{spam-use-hashcash} are such -back ends. - -@item -@code{spam-install-statistical-checkonly-backend} - -This function installs a statistical back end (one which requires the -full body of a message to check it) that can only check incoming mail -for contents. @code{spam-use-regex-body} is such a filter. - -@item -@code{spam-install-statistical-backend} - -This function install a statistical back end with incoming checks and -registration/unregistration routines. @code{spam-use-bogofilter} is -set up this way. - -@item -@code{spam-install-backend} - -This is the most normal back end installation, where a back end that can -check and register/unregister messages is set up without statistical -abilities. The @code{spam-use-BBDB} is such a back end. - -@item -@code{spam-install-mover-backend} - -Mover back ends are internal to @code{spam.el} and specifically move -articles around when the summary is exited. You will very probably -never install such a back end. -@end enumerate - -@end enumerate - -@node Spam Statistics Package -@subsection Spam Statistics Package -@cindex Paul Graham -@cindex Graham, Paul -@cindex naive Bayesian spam filtering -@cindex Bayesian spam filtering, naive -@cindex spam filtering, naive Bayesian - -Paul Graham has written an excellent essay about spam filtering using -statistics: @uref{http://www.paulgraham.com/spam.html,A Plan for -Spam}. In it he describes the inherent deficiency of rule-based -filtering as used by SpamAssassin, for example: Somebody has to write -the rules, and everybody else has to install these rules. You are -always late. It would be much better, he argues, to filter mail based -on whether it somehow resembles spam or non-spam. One way to measure -this is word distribution. He then goes on to describe a solution -that checks whether a new mail resembles any of your other spam mails -or not. - -The basic idea is this: Create a two collections of your mail, one -with spam, one with non-spam. Count how often each word appears in -either collection, weight this by the total number of mails in the -collections, and store this information in a dictionary. For every -word in a new mail, determine its probability to belong to a spam or a -non-spam mail. Use the 15 most conspicuous words, compute the total -probability of the mail being spam. If this probability is higher -than a certain threshold, the mail is considered to be spam. - -The Spam Statistics package adds support to Gnus for this kind of -filtering. It can be used as one of the back ends of the Spam package -(@pxref{Spam Package}), or by itself. - -Before using the Spam Statistics package, you need to set it up. -First, you need two collections of your mail, one with spam, one with -non-spam. Then you need to create a dictionary using these two -collections, and save it. And last but not least, you need to use -this dictionary in your fancy mail splitting rules. - -@menu -* Creating a spam-stat dictionary:: -* Splitting mail using spam-stat:: -* Low-level interface to the spam-stat dictionary:: -@end menu - -@node Creating a spam-stat dictionary -@subsubsection Creating a spam-stat dictionary - -Before you can begin to filter spam based on statistics, you must -create these statistics based on two mail collections, one with spam, -one with non-spam. These statistics are then stored in a dictionary -for later use. In order for these statistics to be meaningful, you -need several hundred emails in both collections. - -Gnus currently supports only the nnml back end for automated dictionary -creation. The nnml back end stores all mails in a directory, one file -per mail. Use the following: - -@defun spam-stat-process-spam-directory -Create spam statistics for every file in this directory. Every file -is treated as one spam mail. -@end defun - -@defun spam-stat-process-non-spam-directory -Create non-spam statistics for every file in this directory. Every -file is treated as one non-spam mail. -@end defun - -Usually you would call @code{spam-stat-process-spam-directory} on a -directory such as @file{~/Mail/mail/spam} (this usually corresponds to -the group @samp{nnml:mail.spam}), and you would call -@code{spam-stat-process-non-spam-directory} on a directory such as -@file{~/Mail/mail/misc} (this usually corresponds to the group -@samp{nnml:mail.misc}). - -When you are using @acronym{IMAP}, you won't have the mails available -locally, so that will not work. One solution is to use the Gnus Agent -to cache the articles. Then you can use directories such as -@file{"~/News/agent/nnimap/mail.yourisp.com/personal_spam"} for -@code{spam-stat-process-spam-directory}. @xref{Agent as Cache}. - -@defvar spam-stat -This variable holds the hash-table with all the statistics---the -dictionary we have been talking about. For every word in either -collection, this hash-table stores a vector describing how often the -word appeared in spam and often it appeared in non-spam mails. -@end defvar - -If you want to regenerate the statistics from scratch, you need to -reset the dictionary. - -@defun spam-stat-reset -Reset the @code{spam-stat} hash-table, deleting all the statistics. -@end defun - -When you are done, you must save the dictionary. The dictionary may -be rather large. If you will not update the dictionary incrementally -(instead, you will recreate it once a month, for example), then you -can reduce the size of the dictionary by deleting all words that did -not appear often enough or that do not clearly belong to only spam or -only non-spam mails. - -@defun spam-stat-reduce-size -Reduce the size of the dictionary. Use this only if you do not want -to update the dictionary incrementally. -@end defun - -@defun spam-stat-save -Save the dictionary. -@end defun - -@defvar spam-stat-file -The filename used to store the dictionary. This defaults to -@file{~/.spam-stat.el}. -@end defvar - -@node Splitting mail using spam-stat -@subsubsection Splitting mail using spam-stat - -This section describes how to use the Spam statistics -@emph{independently} of the @xref{Spam Package}. - -First, add the following to your @file{~/.gnus.el} file: - -@lisp -(require 'spam-stat) -(spam-stat-load) -@end lisp - -This will load the necessary Gnus code, and the dictionary you -created. - -Next, you need to adapt your fancy splitting rules: You need to -determine how to use @code{spam-stat}. The following examples are for -the nnml back end. Using the nnimap back end works just as well. Just -use @code{nnimap-split-fancy} instead of @code{nnmail-split-fancy}. - -In the simplest case, you only have two groups, @samp{mail.misc} and -@samp{mail.spam}. The following expression says that mail is either -spam or it should go into @samp{mail.misc}. If it is spam, then -@code{spam-stat-split-fancy} will return @samp{mail.spam}. - -@lisp -(setq nnmail-split-fancy - `(| (: spam-stat-split-fancy) - "mail.misc")) -@end lisp - -@defvar spam-stat-split-fancy-spam-group -The group to use for spam. Default is @samp{mail.spam}. -@end defvar - -If you also filter mail with specific subjects into other groups, use -the following expression. Only mails not matching the regular -expression are considered potential spam. - -@lisp -(setq nnmail-split-fancy - `(| ("Subject" "\\bspam-stat\\b" "mail.emacs") - (: spam-stat-split-fancy) - "mail.misc")) -@end lisp - -If you want to filter for spam first, then you must be careful when -creating the dictionary. Note that @code{spam-stat-split-fancy} must -consider both mails in @samp{mail.emacs} and in @samp{mail.misc} as -non-spam, therefore both should be in your collection of non-spam -mails, when creating the dictionary! - -@lisp -(setq nnmail-split-fancy - `(| (: spam-stat-split-fancy) - ("Subject" "\\bspam-stat\\b" "mail.emacs") - "mail.misc")) -@end lisp - -You can combine this with traditional filtering. Here, we move all -HTML-only mails into the @samp{mail.spam.filtered} group. Note that since -@code{spam-stat-split-fancy} will never see them, the mails in -@samp{mail.spam.filtered} should be neither in your collection of spam mails, -nor in your collection of non-spam mails, when creating the -dictionary! - -@lisp -(setq nnmail-split-fancy - `(| ("Content-Type" "text/html" "mail.spam.filtered") - (: spam-stat-split-fancy) - ("Subject" "\\bspam-stat\\b" "mail.emacs") - "mail.misc")) -@end lisp - - -@node Low-level interface to the spam-stat dictionary -@subsubsection Low-level interface to the spam-stat dictionary - -The main interface to using @code{spam-stat}, are the following functions: - -@defun spam-stat-buffer-is-spam -Called in a buffer, that buffer is considered to be a new spam mail. -Use this for new mail that has not been processed before. -@end defun - -@defun spam-stat-buffer-is-no-spam -Called in a buffer, that buffer is considered to be a new non-spam -mail. Use this for new mail that has not been processed before. -@end defun - -@defun spam-stat-buffer-change-to-spam -Called in a buffer, that buffer is no longer considered to be normal -mail but spam. Use this to change the status of a mail that has -already been processed as non-spam. -@end defun - -@defun spam-stat-buffer-change-to-non-spam -Called in a buffer, that buffer is no longer considered to be spam but -normal mail. Use this to change the status of a mail that has already -been processed as spam. -@end defun - -@defun spam-stat-save -Save the hash table to the file. The filename used is stored in the -variable @code{spam-stat-file}. -@end defun - -@defun spam-stat-load -Load the hash table from a file. The filename used is stored in the -variable @code{spam-stat-file}. -@end defun - -@defun spam-stat-score-word -Return the spam score for a word. -@end defun - -@defun spam-stat-score-buffer -Return the spam score for a buffer. -@end defun - -@defun spam-stat-split-fancy -Use this function for fancy mail splitting. Add the rule @samp{(: -spam-stat-split-fancy)} to @code{nnmail-split-fancy} -@end defun - -Make sure you load the dictionary before using it. This requires the -following in your @file{~/.gnus.el} file: - -@lisp -(require 'spam-stat) -(spam-stat-load) -@end lisp - -Typical test will involve calls to the following functions: - -@smallexample -Reset: (setq spam-stat (make-hash-table :test 'equal)) -Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") -Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") -Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) -Number of words: (hash-table-count spam-stat) -Test spam: (spam-stat-test-directory "~/Mail/mail/spam") -Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") -Reduce table size: (spam-stat-reduce-size) -Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) -Number of words: (hash-table-count spam-stat) -Test spam: (spam-stat-test-directory "~/Mail/mail/spam") -Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") -@end smallexample - -Here is how you would create your dictionary: - -@smallexample -Reset: (setq spam-stat (make-hash-table :test 'equal)) -Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") -Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") -Repeat for any other non-spam group you need... -Reduce table size: (spam-stat-reduce-size) -Save table: (spam-stat-save) -@end smallexample - -@node The Gnus Registry -@section The Gnus Registry -@cindex registry -@cindex split -@cindex track - -The Gnus registry is a package that tracks messages by their -Message-ID across all backends. This allows Gnus users to do several -cool things, be the envy of the locals, get free haircuts, and be -experts on world issues. Well, maybe not all of those, but the -features are pretty cool. - -Although they will be explained in detail shortly, here's a quick list -of said features in case your attention span is... never mind. - -@enumerate -@item -Split messages to their parent - -This keeps discussions in the same group. You can use the subject and -the sender in addition to the Message-ID@. Several strategies are -available. - -@item -Refer to messages by ID - -Commands like @code{gnus-summary-refer-parent-article} can take -advantage of the registry to jump to the referred article, regardless -of the group the message is in. - -@item -Store custom flags and keywords - -The registry can store custom flags and keywords for a message. For -instance, you can mark a message ``To-Do'' this way and the flag will -persist whether the message is in the nnimap, nnml, nnmaildir, -etc. backends. - -@item -Store arbitrary data - -Through a simple ELisp API, the registry can remember any data for a -message. A built-in inverse map, when activated, allows quick lookups -of all messages matching a particular set of criteria. -@end enumerate - -@menu -* Gnus Registry Setup:: -* Registry Article Refer Method:: -* Fancy splitting to parent:: -* Store custom flags and keywords:: -* Store arbitrary data:: -@end menu - -@node Gnus Registry Setup -@subsection Gnus Registry Setup - -Fortunately, setting up the Gnus registry is pretty easy: - -@lisp -(setq gnus-registry-max-entries 2500) - -(gnus-registry-initialize) -@end lisp - -This adds registry saves to Gnus newsrc saves (which happen on exit -and when you press @kbd{s} from the @file{*Group*} buffer. It also -adds registry calls to article actions in Gnus (copy, move, etc.)@: so -it's not easy to undo the initialization. See -@code{gnus-registry-initialize} for the gory details. - -Here are other settings used by the author of the registry (understand -what they do before you copy them blindly). - -@lisp -(setq - gnus-registry-split-strategy 'majority - gnus-registry-ignored-groups '(("nntp" t) - ("nnrss" t) - ("spam" t) - ("train" t)) - gnus-registry-max-entries 500000 - ;; this is the default - gnus-registry-track-extra '(sender subject)) -@end lisp - -They say: keep a lot of messages around, track messages by sender and -subject (not just parent Message-ID), and when the registry splits -incoming mail, use a majority rule to decide where messages should go -if there's more than one possibility. In addition, the registry -should ignore messages in groups that match ``nntp'', ``nnrss'', -``spam'', or ``train.'' - -You are doubtless impressed by all this, but you ask: ``I am a Gnus -user, I customize to live. Give me more.'' Here you go, these are -the general settings. - -@defvar gnus-registry-unfollowed-groups -The groups that will not be followed by -@code{gnus-registry-split-fancy-with-parent}. They will still be -remembered by the registry. This is a list of regular expressions. -By default any group name that ends with ``delayed'', ``drafts'', -``queue'', or ``INBOX'', belongs to the nnmairix backend, or contains -the word ``archive'' is not followed. -@end defvar - -@defvar gnus-registry-max-entries -The number (an integer or @code{nil} for unlimited) of entries the -registry will keep. -@end defvar - -@defvar gnus-registry-max-pruned-entries -The maximum number (an integer or @code{nil} for unlimited) of entries -the registry will keep after pruning. -@end defvar - -@defvar gnus-registry-cache-file -The file where the registry will be stored between Gnus sessions. By -default the file name is @code{.gnus.registry.eioio} in the same -directory as your @code{.newsrc.eld}. -@end defvar - -@node Registry Article Refer Method -@subsection Fetching by @code{Message-ID} Using the Registry - -The registry knows how to map each @code{Message-ID} to the group it's -in. This can be leveraged to enhance the ``article refer method'', -the thing that tells Gnus how to look up an article given its -Message-ID (@pxref{Finding the Parent}). - -@vindex nnregistry -@vindex gnus-refer-article-method - -The @code{nnregistry} refer method does exactly that. It has the -advantage that an article may be found regardless of the group it's -in---provided its @code{Message-ID} is known to the registry. It can -be enabled by augmenting the start-up file with something along these -lines: - -@example -;; Keep enough entries to have a good hit rate when referring to an -;; article using the registry. Use long group names so that Gnus -;; knows where the article is. -(setq gnus-registry-max-entries 2500) - -(gnus-registry-initialize) - -(setq gnus-refer-article-method - '(current - (nnregistry) - (nnweb "gmane" (nnweb-type gmane)))) -@end example - -The example above instructs Gnus to first look up the article in the -current group, or, alternatively, using the registry, and finally, if -all else fails, using Gmane. - -@node Fancy splitting to parent -@subsection Fancy splitting to parent - -Simply put, this lets you put followup e-mail where it belongs. - -Every message has a Message-ID, which is unique, and the registry -remembers it. When the message is moved or copied, the registry will -notice this and offer the new group as a choice to the splitting -strategy. - -When a followup is made, usually it mentions the original message's -Message-ID in the headers. The registry knows this and uses that -mention to find the group where the original message lives. You only -have to put a rule like this: - -@lisp -(setq nnimap-my-split-fancy '(| - - ;; split to parent: you need this - (: gnus-registry-split-fancy-with-parent) - - ;; other rules, as an example - (: spam-split) - ;; default mailbox - "mail") -@end lisp - -in your fancy split setup. In addition, you may want to customize the -following variables. - -@defvar gnus-registry-track-extra -This is a list of symbols, so it's best to change it from the -Customize interface. By default it's @code{(subject sender recipient)}, -which may work for you. It can be annoying if your mail flow is large -and people don't stick to the same groups. - -When you decide to stop tracking any of those extra data, you can use -the command @code{gnus-registry-remove-extra-data} to purge it from -the existing registry entries. -@end defvar - -@defvar gnus-registry-split-strategy -This is a symbol, so it's best to change it from the Customize -interface. By default it's @code{nil}, but you may want to set it to -@code{majority} or @code{first} to split by sender or subject based on -the majority of matches or on the first found. I find @code{majority} -works best. -@end defvar - -@node Store custom flags and keywords -@subsection Store custom flags and keywords - -The registry lets you set custom flags and keywords per message. You -can use the Gnus->Registry Marks menu or the @kbd{M M x} keyboard -shortcuts, where @code{x} is the first letter of the mark's name. - -@defvar gnus-registry-marks -The custom marks that the registry can use. You can modify the -default list, if you like. If you do, you'll have to exit Emacs -before they take effect (you can also unload the registry and reload -it or evaluate the specific macros you'll need, but you probably don't -want to bother). Use the Customize interface to modify the list. - -By default this list has the @code{Important}, @code{Work}, -@code{Personal}, @code{To-Do}, and @code{Later} marks. They all have -keyboard shortcuts like @kbd{M M i} for Important, using the first -letter. -@end defvar - -@defun gnus-registry-mark-article -Call this function to mark an article with a custom registry mark. It -will offer the available marks for completion. -@end defun - -You can use @code{defalias} to install a summary line formatting -function that will show the registry marks. There are two flavors of -this function, either showing the marks as single characters, using -their @code{:char} property, or showing the marks as full strings. - -@lisp -;; show the marks as single characters (see the :char property in -;; `gnus-registry-marks'): -;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-chars) - -;; show the marks by name (see `gnus-registry-marks'): -;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-names) -@end lisp - - -@node Store arbitrary data -@subsection Store arbitrary data - -The registry has a simple API that uses a Message-ID as the key to -store arbitrary data (as long as it can be converted to a list for -storage). - -@defun gnus-registry-set-id-key (id key value) -Store @code{value} under @code{key} for message @code{id}. -@end defun - -@defun gnus-registry-get-id-key (id key) -Get the data under @code{key} for message @code{id}. -@end defun - -@defvar gnus-registry-extra-entries-precious -If any extra entries are precious, their presence will make the -registry keep the whole entry forever, even if there are no groups for -the Message-ID and if the size limit of the registry is reached. By -default this is just @code{(marks)} so the custom registry marks are -precious. -@end defvar - -@node Other modes -@section Interaction with other modes - -@subsection Dired -@cindex dired - -@code{gnus-dired-minor-mode} provides some useful functions for dired -buffers. It is enabled with -@lisp -(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode) -@end lisp - -@table @kbd -@item C-c C-m C-a -@findex gnus-dired-attach -@cindex attachments, selection via dired -Send dired's marked files as an attachment (@code{gnus-dired-attach}). -You will be prompted for a message buffer. - -@item C-c C-m C-l -@findex gnus-dired-find-file-mailcap -Visit a file according to the appropriate mailcap entry -(@code{gnus-dired-find-file-mailcap}). With prefix, open file in a new -buffer. - -@item C-c C-m C-p -@findex gnus-dired-print -Print file according to the mailcap entry (@code{gnus-dired-print}). If -there is no print command, print in a PostScript image. -@end table - -@node Various Various -@section Various Various -@cindex mode lines -@cindex highlights - -@table @code - -@item gnus-home-directory -@vindex gnus-home-directory -All Gnus file and directory variables will be initialized from this -variable, which defaults to @file{~/}. - -@item gnus-directory -@vindex gnus-directory -Most Gnus storage file and directory variables will be initialized from -this variable, which defaults to the @env{SAVEDIR} environment -variable, or @file{~/News/} if that variable isn't set. - -Note that Gnus is mostly loaded when the @file{~/.gnus.el} file is read. -This means that other directory variables that are initialized from this -variable won't be set properly if you set this variable in -@file{~/.gnus.el}. Set this variable in @file{.emacs} instead. - -@item gnus-default-directory -@vindex gnus-default-directory -Not related to the above variable at all---this variable says what the -default directory of all Gnus buffers should be. If you issue commands -like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's -default directory. If this variable is @code{nil} (which is the -default), the default directory will be the default directory of the -buffer you were in when you started Gnus. - -@item gnus-verbose -@vindex gnus-verbose -This variable is an integer between zero and ten. The higher the value, -the more messages will be displayed. If this variable is zero, Gnus -will never flash any messages, if it is seven (which is the default), -most important messages will be shown, and if it is ten, Gnus won't ever -shut up, but will flash so many messages it will make your head swim. - -@item gnus-verbose-backends -@vindex gnus-verbose-backends -This variable works the same way as @code{gnus-verbose}, but it applies -to the Gnus back ends instead of Gnus proper. - -@item gnus-add-timestamp-to-message -@vindex gnus-add-timestamp-to-message -This variable controls whether to add timestamps to messages that are -controlled by @code{gnus-verbose} and @code{gnus-verbose-backends} and -are issued. The default value is @code{nil} which means never to add -timestamp. If it is @code{log}, add timestamps to only the messages -that go into the @file{*Messages*} buffer (in XEmacs, it is the -@w{@file{ *Message-Log*}} buffer). If it is neither @code{nil} nor -@code{log}, add timestamps not only to log messages but also to the ones -displayed in the echo area. - -@item nnheader-max-head-length -@vindex nnheader-max-head-length -When the back ends read straight heads of articles, they all try to read -as little as possible. This variable (default 8192) specifies -the absolute max length the back ends will try to read before giving up -on finding a separator line between the head and the body. If this -variable is @code{nil}, there is no upper read bound. If it is -@code{t}, the back ends won't try to read the articles piece by piece, -but read the entire articles. This makes sense with some versions of -@code{ange-ftp} or @code{efs}. - -@item nnheader-head-chop-length -@vindex nnheader-head-chop-length -This variable (default 2048) says how big a piece of each article to -read when doing the operation described above. - -@item nnheader-file-name-translation-alist -@vindex nnheader-file-name-translation-alist -@cindex file names -@cindex invalid characters in file names -@cindex characters in file names -This is an alist that says how to translate characters in file names. -For instance, if @samp{:} is invalid as a file character in file names -on your system (you OS/2 user you), you could say something like: - -@lisp -@group -(setq nnheader-file-name-translation-alist - '((?: . ?_))) -@end group -@end lisp - -In fact, this is the default value for this variable on OS/2 and MS -Windows (phooey) systems. - -@item gnus-hidden-properties -@vindex gnus-hidden-properties -This is a list of properties to use to hide ``invisible'' text. It is -@code{(invisible t intangible t)} by default on most systems, which -makes invisible text invisible and intangible. - -@item gnus-parse-headers-hook -@vindex gnus-parse-headers-hook -A hook called before parsing headers. It can be used, for instance, to -gather statistics on the headers fetched, or perhaps you'd like to prune -some headers. I don't see why you'd want that, though. - -@item gnus-shell-command-separator -@vindex gnus-shell-command-separator -String used to separate two shell commands. The default is @samp{;}. - -@item gnus-invalid-group-regexp -@vindex gnus-invalid-group-regexp - -Regexp to match ``invalid'' group names when querying user for a group -name. The default value catches some @strong{really} invalid group -names who could possibly mess up Gnus internally (like allowing -@samp{:} in a group name, which is normally used to delimit method and -group). - -@acronym{IMAP} users might want to allow @samp{/} in group names though. - -@item gnus-safe-html-newsgroups -@vindex gnus-safe-html-newsgroups -Groups in which links in html articles are considered all safe. The -value may be a regexp matching those groups, a list of group names, or -@code{nil}. This overrides @code{mm-w3m-safe-url-regexp}. The default -value is @code{"\\`nnrss[+:]"}. This is effective only when emacs-w3m -renders html articles, i.e., in the case @code{mm-text-html-renderer} is -set to @code{w3m}. @xref{Display Customization, ,Display Customization, -emacs-mime, The Emacs MIME Manual}. - -@end table - -@node The End -@chapter The End - -Well, that's the manual---you can get on with your life now. Keep in -touch. Say hello to your cats from me. - -My @strong{ghod}---I just can't stand goodbyes. Sniffle. - -Ol' Charles Reznikoff said it pretty well, so I leave the floor to him: - -@quotation -@strong{Te Deum} - -@sp 1 -Not because of victories @* -I sing,@* -having none,@* -but for the common sunshine,@* -the breeze,@* -the largess of the spring. - -@sp 1 -Not for victory@* -but for the day's work done@* -as well as I was able;@* -not for a seat upon the dais@* -but at the common table.@* -@end quotation - - -@node Appendices -@chapter Appendices - -@menu -* XEmacs:: Requirements for installing under XEmacs. -* History:: How Gnus got where it is today. -* On Writing Manuals:: Why this is not a beginner's guide. -* Terminology:: We use really difficult, like, words here. -* Customization:: Tailoring Gnus to your needs. -* Troubleshooting:: What you might try if things do not work. -* Gnus Reference Guide:: Rilly, rilly technical stuff. -* Emacs for Heathens:: A short introduction to Emacsian terms. -* Frequently Asked Questions:: The Gnus FAQ -@end menu - - -@node XEmacs -@section XEmacs -@cindex XEmacs -@cindex installing under XEmacs - -XEmacs is distributed as a collection of packages. You should install -whatever packages the Gnus XEmacs package requires. The current -requirements are @samp{gnus}, @samp{mail-lib}, @samp{xemacs-base}, -@samp{eterm}, @samp{sh-script}, @samp{net-utils}, @samp{os-utils}, -@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{W3}, -@samp{pgg}, @samp{mailcrypt}, @samp{ecrypto}, and @samp{sasl}. - - -@node History -@section History - -@cindex history -@sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in -'94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus. - -If you want to investigate the person responsible for this outrage, -you can point your (feh!) web browser to -@uref{http://quimby.gnus.org/}. This is also the primary -distribution point for the new and spiffy versions of Gnus, and is -known as The Site That Destroys Newsrcs And Drives People Mad. - -During the first extended alpha period of development, the new Gnus was -called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for -@dfn{ding is not Gnus}, which is a total and utter lie, but who cares? -(Besides, the ``Gnus'' in this abbreviation should probably be -pronounced ``news'' as @sc{Umeda} intended, which makes it a more -appropriate name, don't you think?) - -In any case, after spending all that energy on coming up with a new and -spunky name, we decided that the name was @emph{too} spunky, so we -renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs. -``@sc{gnus}''. New vs. old. - -@menu -* Gnus Versions:: What Gnus versions have been released. -* Why?:: What's the point of Gnus? -* Compatibility:: Just how compatible is Gnus with @sc{gnus}? -* Conformity:: Gnus tries to conform to all standards. -* Emacsen:: Gnus can be run on a few modern Emacsen. -* Gnus Development:: How Gnus is developed. -* Contributors:: Oodles of people. -* New Features:: Pointers to some of the new stuff in Gnus. -@end menu - - -@node Gnus Versions -@subsection Gnus Versions -@cindex ding Gnus -@cindex September Gnus -@cindex Red Gnus -@cindex Quassia Gnus -@cindex Pterodactyl Gnus -@cindex Oort Gnus -@cindex No Gnus -@cindex Ma Gnus -@cindex Gnus versions - -The first ``proper'' release of Gnus 5 was done in November 1995 when it -was included in the Emacs 19.30 distribution (132 (ding) Gnus releases -plus 15 Gnus 5.0 releases). - -In May 1996 the next Gnus generation (aka. ``September Gnus'' (after 99 -releases)) was released under the name ``Gnus 5.2'' (40 releases). - -On July 28th 1996 work on Red Gnus was begun, and it was released on -January 25th 1997 (after 84 releases) as ``Gnus 5.4'' (67 releases). - -On September 13th 1997, Quassia Gnus was started and lasted 37 releases. -It was released as ``Gnus 5.6'' on March 8th 1998 (46 releases). - -Gnus 5.6 begat Pterodactyl Gnus on August 29th 1998 and was released as -``Gnus 5.8'' (after 99 releases and a CVS repository) on December 3rd -1999. - -On the 26th of October 2000, Oort Gnus was begun and was released as -Gnus 5.10 on May 1st 2003 (24 releases). - -On the January 4th 2004, No Gnus was begun. - -On April 19, 2010 Gnus development was moved to Git. See -http://git.gnus.org for details (http://www.gnus.org will be updated -with the information when possible). - -On the January 31th 2012, Ma Gnus was begun. - -If you happen upon a version of Gnus that has a prefixed name---``(ding) -Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'', -``Pterodactyl Gnus'', ``Oort Gnus'', ``No Gnus'', ``Ma Gnus''---don't -panic. Don't let it know that you're frightened. Back away. Slowly. -Whatever you do, don't run. Walk away, calmly, until you're out of -its reach. Find a proper released version of Gnus and snuggle up to -that instead. - - -@node Why? -@subsection Why? - -What's the point of Gnus? - -I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep'' -newsreader, that lets you do anything you can think of. That was my -original motivation, but while working on Gnus, it has become clear to -me that this generation of newsreaders really belong in the stone age. -Newsreaders haven't developed much since the infancy of the net. If the -volume continues to rise with the current rate of increase, all current -newsreaders will be pretty much useless. How do you deal with -newsgroups that have thousands of new articles each day? How do you -keep track of millions of people who post? - -Gnus offers no real solutions to these questions, but I would very much -like to see Gnus being used as a testing ground for new methods of -reading and fetching news. Expanding on @sc{Umeda}-san's wise decision -to separate the newsreader from the back ends, Gnus now offers a simple -interface for anybody who wants to write new back ends for fetching mail -and news from different sources. I have added hooks for customizations -everywhere I could imagine it being useful. By doing so, I'm inviting -every one of you to explore and invent. - -May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and -@kbd{C-u 100 M-x all-hail-xemacs}. - - -@node Compatibility -@subsection Compatibility - -@cindex compatibility -Gnus was designed to be fully compatible with @sc{gnus}. Almost all key -bindings have been kept. More key bindings have been added, of course, -but only in one or two obscure cases have old bindings been changed. - -Our motto is: -@quotation -@cartouche -@center In a cloud bones of steel. -@end cartouche -@end quotation - -All commands have kept their names. Some internal functions have changed -their names. - -The @code{gnus-uu} package has changed drastically. @xref{Decoding -Articles}. - -One major compatibility question is the presence of several summary -buffers. All variables relevant while reading a group are -buffer-local to the summary buffer they belong in. Although many -important variables have their values copied into their global -counterparts whenever a command is executed in the summary buffer, this -change might lead to incorrect values being used unless you are careful. - -All code that relies on knowledge of @sc{gnus} internals will probably -fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or -changing it in any way, as a matter of fact) is strictly verboten. Gnus -maintains a hash table that points to the entries in this alist (which -speeds up many functions), and changing the alist directly will lead to -peculiar results. - -@cindex hilit19 -@cindex highlighting -Old hilit19 code does not work at all. In fact, you should probably -remove all hilit code from all Gnus hooks -(@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}). -Gnus provides various integrated functions for highlighting. These are -faster and more accurate. To make life easier for everybody, Gnus will -by default remove all hilit calls from all hilit hooks. Uncleanliness! -Away! - -Packages like @code{expire-kill} will no longer work. As a matter of -fact, you should probably remove all old @sc{gnus} packages (and other -code) when you start using Gnus. More likely than not, Gnus already -does what you have written code to make @sc{gnus} do. (Snicker.) - -Even though old methods of doing things are still supported, only the -new methods are documented in this manual. If you detect a new method of -doing something while reading this manual, that does not mean you have -to stop doing it the old way. - -Gnus understands all @sc{gnus} startup files. - -@kindex M-x gnus-bug -@findex gnus-bug -@cindex reporting bugs -@cindex bugs -Overall, a casual user who hasn't written much code that depends on -@sc{gnus} internals should suffer no problems. If problems occur, -please let me know by issuing that magic command @kbd{M-x gnus-bug}. - -@vindex gnus-bug-create-help-buffer -If you are in the habit of sending bug reports @emph{very} often, you -may find the helpful help buffer annoying after a while. If so, set -@code{gnus-bug-create-help-buffer} to @code{nil} to avoid having it pop -up at you. - - -@node Conformity -@subsection Conformity - -No rebels without a clue here, ma'am. We conform to all standards known -to (wo)man. Except for those standards and/or conventions we disagree -with, of course. - -@table @strong - -@item RFC (2)822 -@cindex RFC 822 -@cindex RFC 2822 -There are no known breaches of this standard. - -@item RFC 1036 -@cindex RFC 1036 -There are no known breaches of this standard, either. - -@item Son-of-RFC 1036 -@cindex Son-of-RFC 1036 -We do have some breaches to this one. - -@table @emph - -@item X-Newsreader -@itemx User-Agent -These are considered to be ``vanity headers'', while I consider them -to be consumer information. After seeing so many badly formatted -articles coming from @code{tin} and @code{Netscape} I know not to use -either of those for posting articles. I would not have known that if -it wasn't for the @code{X-Newsreader} header. -@end table - -@item USEFOR -@cindex USEFOR -USEFOR is an IETF working group writing a successor to RFC 1036, based -on Son-of-RFC 1036. They have produced a number of drafts proposing -various changes to the format of news articles. The Gnus towers will -look into implementing the changes when the draft is accepted as an RFC. - -@item MIME---RFC 2045--2049 etc -@cindex @acronym{MIME} -All the various @acronym{MIME} RFCs are supported. - -@item Disposition Notifications---RFC 2298 -Message Mode is able to request notifications from the receiver. - -@item PGP---RFC 1991 and RFC 2440 -@cindex RFC 1991 -@cindex RFC 2440 -RFC 1991 is the original @acronym{PGP} message specification, -published as an informational RFC@. RFC 2440 was the follow-up, now -called Open PGP, and put on the Standards Track. Both document a -non-@acronym{MIME} aware @acronym{PGP} format. Gnus supports both -encoding (signing and encryption) and decoding (verification and -decryption). - -@item PGP/MIME---RFC 2015/3156 -RFC 2015 (superseded by 3156 which references RFC 2440 instead of RFC -1991) describes the @acronym{MIME}-wrapping around the RFC 1991/2440 format. -Gnus supports both encoding and decoding. - -@item S/MIME---RFC 2633 -RFC 2633 describes the @acronym{S/MIME} format. - -@item IMAP---RFC 1730/2060, RFC 2195, RFC 2086, RFC 2359, RFC 2595, RFC 1731 -RFC 1730 is @acronym{IMAP} version 4, updated somewhat by RFC 2060 -(@acronym{IMAP} 4 revision 1). RFC 2195 describes CRAM-MD5 -authentication for @acronym{IMAP}. RFC 2086 describes access control -lists (ACLs) for @acronym{IMAP}. RFC 2359 describes a @acronym{IMAP} -protocol enhancement. RFC 2595 describes the proper @acronym{TLS} -integration (STARTTLS) with @acronym{IMAP}. RFC 1731 describes the -GSSAPI/Kerberos4 mechanisms for @acronym{IMAP}. - -@end table - -If you ever notice Gnus acting non-compliant with regards to the texts -mentioned above, don't hesitate to drop a note to Gnus Towers and let us -know. - - -@node Emacsen -@subsection Emacsen -@cindex Emacsen -@cindex XEmacs -@cindex Mule -@cindex Emacs - -This version of Gnus should work on: - -@itemize @bullet - -@item -Emacs 23.1 and up. - -@item -XEmacs 21.4 and up. - -@end itemize - -This Gnus version will absolutely not work on any Emacsen older than -that. Not reliably, at least. Older versions of Gnus may work on older -Emacs versions. Particularly, Gnus 5.10.8 should also work on Emacs -20.7 and XEmacs 21.1. - -@c No-merge comment: The paragraph added in v5-10 here must not be -@c synced here! - -@node Gnus Development -@subsection Gnus Development - -Gnus is developed in a two-phased cycle. The first phase involves much -discussion on the development mailing list @samp{ding@@gnus.org}, where people -propose changes and new features, post patches and new back ends. This -phase is called the @dfn{alpha} phase, since the Gnusae released in this -phase are @dfn{alpha releases}, or (perhaps more commonly in other -circles) @dfn{snapshots}. During this phase, Gnus is assumed to be -unstable and should not be used by casual users. Gnus alpha releases -have names like ``Oort Gnus'' and ``No Gnus''. @xref{Gnus Versions}. - -After futzing around for 10--100 alpha releases, Gnus is declared -@dfn{frozen}, and only bug fixes are applied. Gnus loses the prefix, -and is called things like ``Gnus 5.10.1'' instead. Normal people are -supposed to be able to use these, and these are mostly discussed on the -@samp{gnu.emacs.gnus} newsgroup. This newgroup is mirrored to the -mailing list @samp{info-gnus-english@@gnu.org} which is carried on Gmane -as @samp{gmane.emacs.gnus.user}. These releases are finally integrated -in Emacs. - -@cindex Incoming* -@vindex mail-source-delete-incoming -Some variable defaults differ between alpha Gnusae and released Gnusae, -in particular, @code{mail-source-delete-incoming}. This is to prevent -lossage of mail if an alpha release hiccups while handling the mail. -@xref{Mail Source Customization}. - -The division of discussion between the ding mailing list and the Gnus -newsgroup is not purely based on publicity concerns. It's true that -having people write about the horrible things that an alpha Gnus release -can do (sometimes) in a public forum may scare people off, but more -importantly, talking about new experimental features that have been -introduced may confuse casual users. New features are frequently -introduced, fiddled with, and judged to be found wanting, and then -either discarded or totally rewritten. People reading the mailing list -usually keep up with these rapid changes, while people on the newsgroup -can't be assumed to do so. - -So if you have problems with or questions about the alpha versions, -direct those to the ding mailing list @samp{ding@@gnus.org}. This list -is also available on Gmane as @samp{gmane.emacs.gnus.general}. - -@cindex Incoming* -@vindex mail-source-delete-incoming -Some variable defaults differ between alpha Gnusae and released Gnusae, -in particular, @code{mail-source-delete-incoming}. This is to prevent -lossage of mail if an alpha release hiccups while handling the mail. -@xref{Mail Source Customization}. - -@node Contributors -@subsection Contributors -@cindex contributors - -The new Gnus version couldn't have been done without the help of all the -people on the (ding) mailing list. Every day for over a year I have -gotten billions of nice bug reports from them, filling me with joy, -every single one of them. Smooches. The people on the list have been -tried beyond endurance, what with my ``oh, that's a neat idea , yup, I'll release it right away no wait, that doesn't -work at all , yup, I'll ship that one off right away no, wait, that absolutely does not work'' policy for releases. -Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that -``worser''? ``much worser''? ``worsest''?) - -I would like to take this opportunity to thank the Academy for@dots{} oops, -wrong show. - -@itemize @bullet - -@item -Masanobu @sc{Umeda}---the writer of the original @sc{gnus}. - -@item -Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el, -nnwarchive and many, many other things connected with @acronym{MIME} and -other types of en/decoding, as well as general bug fixing, new -functionality and stuff. - -@item -Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as -well as numerous other things). - -@item -Luis Fernandes---design and graphics. - -@item -Joe Reiss---creator of the smiley faces. - -@item -Justin Sheehy---the @acronym{FAQ} maintainer. - -@item -Erik Naggum---help, ideas, support, code and stuff. - -@item -Wes Hardaker---@file{gnus-picon.el} and the manual section on -@dfn{picons} (@pxref{Picons}). - -@item -Kim-Minh Kaplan---further work on the picon code. - -@item -Brad Miller---@file{gnus-gl.el} and the GroupLens manual section. - -@item -Sudish Joseph---innumerable bug fixes. - -@item -Ilja Weis---@file{gnus-topic.el}. - -@item -Steven L. Baur---lots and lots and lots of bug detection and fixes. - -@item -Vladimir Alexiev---the refcard and reference booklets. - -@item -Felix Lee & Jamie Zawinski---I stole some pieces from the XGnus -distribution by Felix Lee and JWZ. - -@item -Scott Byer---@file{nnfolder.el} enhancements & rewrite. - -@item -Peter Mutsaers---orphan article scoring code. - -@item -Ken Raeburn---POP mail support. - -@item -Hallvard B Furuseth---various bits and pieces, especially dealing with -.newsrc files. - -@item -Brian Edmonds---@file{gnus-bbdb.el}. - -@item -David Moore---rewrite of @file{nnvirtual.el} and many other things. - -@item -Kevin Davidson---came up with the name @dfn{ding}, so blame him. - -@item -Fran@,{c}ois Pinard---many, many interesting and thorough bug reports, as -well as autoconf support. - -@end itemize - -This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark -Borges, and Jost Krieger proof-reading parts of the manual. - -The following people have contributed many patches and suggestions: - -Christopher Davis, -Andrew Eskilsson, -Kai Grossjohann, -Kevin Greiner, -Jesper Harder, -Paul Jarc, -Simon Josefsson, -David K@aa{}gedal, -Richard Pieri, -Fabrice Popineau, -Daniel Quinlan, -Michael Shields, -Reiner Steib, -Jason L. Tibbitts, III, -Jack Vinson, -Katsumi Yamaoka, @c Yamaoka -and -Teodor Zlatanov. - -Also thanks to the following for patches and stuff: - -Jari Aalto, -Adrian Aichner, -Vladimir Alexiev, -Russ Allbery, -Peter Arius, -Matt Armstrong, -Marc Auslander, -Miles Bader, -Alexei V. Barantsev, -Frank Bennett, -Robert Bihlmeyer, -Chris Bone, -Mark Borges, -Mark Boyns, -Lance A. Brown, -Rob Browning, -Kees de Bruin, -Martin Buchholz, -Joe Buehler, -Kevin Buhr, -Alastair Burt, -Joao Cachopo, -Zlatko Calusic, -Massimo Campostrini, -Castor, -David Charlap, -Dan Christensen, -Kevin Christian, -Jae-you Chung, @c ? -James H. Cloos, Jr., -Laura Conrad, -Michael R. Cook, -Glenn Coombs, -Andrew J. Cosgriff, -Neil Crellin, -Frank D. Cringle, -Geoffrey T. Dairiki, -Andre Deparade, -Ulrik Dickow, -Dave Disser, -Rui-Tao Dong, @c ? -Joev Dubach, -Michael Welsh Duggan, -Dave Edmondson, -Paul Eggert, -Mark W. Eichin, -Karl Eichwalder, -Enami Tsugutomo, @c Enami -Michael Ernst, -Luc Van Eycken, -Sam Falkner, -Nelson Jose dos Santos Ferreira, -Sigbjorn Finne, -Sven Fischer, -Paul Fisher, -Decklin Foster, -Gary D. Foster, -Paul Franklin, -Guy Geens, -Arne Georg Gleditsch, -David S. Goldberg, -Michelangelo Grigni, -Dale Hagglund, -D. Hall, -Magnus Hammerin, -Kenichi Handa, @c Handa -Raja R. Harinath, -Yoshiki Hayashi, @c Hayashi -P. E. Jareth Hein, -Hisashige Kenji, @c Hisashige -Scott Hofmann, -Tassilo Horn, -Marc Horowitz, -Gunnar Horrigmo, -Richard Hoskins, -Brad Howes, -Miguel de Icaza, -Fran@,{c}ois Felix Ingrand, -Tatsuya Ichikawa, @c Ichikawa -Ishikawa Ichiro, @c Ishikawa -Lee Iverson, -Iwamuro Motonori, @c Iwamuro -Rajappa Iyer, -Andreas Jaeger, -Adam P. Jenkins, -Randell Jesup, -Fred Johansen, -Gareth Jones, -Greg Klanderman, -Karl Kleinpaste, -Michael Klingbeil, -Peter Skov Knudsen, -Shuhei Kobayashi, @c Kobayashi -Petr Konecny, -Koseki Yoshinori, @c Koseki -Thor Kristoffersen, -Jens Lautenbacher, -Martin Larose, -Seokchan Lee, @c Lee -Joerg Lenneis, -Carsten Leonhardt, -James LewisMoss, -Christian Limpach, -Markus Linnala, -Dave Love, -Mike McEwan, -Tonny Madsen, -Shlomo Mahlab, -Nat Makarevitch, -Istvan Marko, -David Martin, -Jason R. Mastaler, -Gordon Matzigkeit, -Timo Metzemakers, -Richard Mlynarik, -Lantz Moore, -Morioka Tomohiko, @c Morioka -Erik Toubro Nielsen, -Hrvoje Niksic, -Andy Norman, -Fred Oberhauser, -C. R. Oldham, -Alexandre Oliva, -Ken Olstad, -Masaharu Onishi, @c Onishi -Hideki Ono, @c Ono -Ettore Perazzoli, -William Perry, -Stephen Peters, -Jens-Ulrik Holger Petersen, -Ulrich Pfeifer, -Matt Pharr, -Andy Piper, -John McClary Prevost, -Bill Pringlemeir, -Mike Pullen, -Jim Radford, -Colin Rafferty, -Lasse Rasinen, -Lars Balker Rasmussen, -Joe Reiss, -Renaud Rioboo, -Roland B. Roberts, -Bart Robinson, -Christian von Roques, -Markus Rost, -Jason Rumney, -Wolfgang Rupprecht, -Jay Sachs, -Dewey M. Sasser, -Conrad Sauerwald, -Loren Schall, -Dan Schmidt, -Ralph Schleicher, -Philippe Schnoebelen, -Andreas Schwab, -Randal L. Schwartz, -Danny Siu, -Matt Simmons, -Paul D. Smith, -Jeff Sparkes, -Toby Speight, -Michael Sperber, -Darren Stalder, -Richard Stallman, -Greg Stark, -Sam Steingold, -Paul Stevenson, -Jonas Steverud, -Paul Stodghill, -Kiyokazu Suto, @c Suto -Kurt Swanson, -Samuel Tardieu, -Teddy, -Chuck Thompson, -Tozawa Akihiko, @c Tozawa -Philippe Troin, -James Troup, -Trung Tran-Duc, -Jack Twilley, -Aaron M. Ucko, -Aki Vehtari, -Didier Verna, -Vladimir Volovich, -Jan Vroonhof, -Stefan Waldherr, -Pete Ware, -Barry A. Warsaw, -Christoph Wedler, -Joe Wells, -Lee Willis, -and -Lloyd Zusman. - - -For a full overview of what each person has done, the ChangeLogs -included in the Gnus alpha distributions should give ample reading -(550kB and counting). - -Apologies to everybody that I've forgotten, of which there are many, I'm -sure. - -Gee, that's quite a list of people. I guess that must mean that there -actually are people who are using Gnus. Who'd'a thunk it! - - -@node New Features -@subsection New Features -@cindex new features - -@menu -* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. -* September Gnus:: The Thing Formally Known As Gnus 5.2/5.3. -* Red Gnus:: Third time best---Gnus 5.4/5.5. -* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7. -* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9. -* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11. -* No Gnus:: Very punny. Gnus 5.12/5.13. -* Ma Gnus:: Celebrating 25 years of Gnus. -@end menu - -These lists are, of course, just @emph{short} overviews of the -@emph{most} important new features. No, really. There are tons more. -Yes, we have feeping creaturism in full effect. - -@node ding Gnus -@subsubsection (ding) Gnus - -New features in Gnus 5.0/5.1: - -@itemize @bullet - -@item -The look of all buffers can be changed by setting format-like variables -(@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}). - -@item -Local spool and several @acronym{NNTP} servers can be used at once -(@pxref{Select Methods}). - -@item -You can combine groups into virtual groups (@pxref{Virtual Groups}). - -@item -You can read a number of different mail formats (@pxref{Getting Mail}). -All the mail back ends implement a convenient mail expiry scheme -(@pxref{Expiring Mail}). - -@item -Gnus can use various strategies for gathering threads that have lost -their roots (thereby gathering loose sub-threads into one thread) or it -can go back and retrieve enough headers to build a complete thread -(@pxref{Customizing Threading}). - -@item -Killed groups can be displayed in the group buffer, and you can read -them as well (@pxref{Listing Groups}). - -@item -Gnus can do partial group updates---you do not have to retrieve the -entire active file just to check for new articles in a few groups -(@pxref{The Active File}). - -@item -Gnus implements a sliding scale of subscribedness to groups -(@pxref{Group Levels}). - -@item -You can score articles according to any number of criteria -(@pxref{Scoring}). You can even get Gnus to find out how to score -articles for you (@pxref{Adaptive Scoring}). - -@item -Gnus maintains a dribble buffer that is auto-saved the normal Emacs -manner, so it should be difficult to lose much data on what you have -read if your machine should go down (@pxref{Auto Save}). - -@item -Gnus now has its own startup file (@file{~/.gnus.el}) to avoid -cluttering up the @file{.emacs} file. - -@item -You can set the process mark on both groups and articles and perform -operations on all the marked items (@pxref{Process/Prefix}). - -@item -You can list subsets of groups according to, well, anything -(@pxref{Listing Groups}). - -@item -You can browse foreign servers and subscribe to groups from those -servers (@pxref{Browse Foreign Server}). - -@item -Gnus can fetch articles, asynchronously, on a second connection to the -server (@pxref{Asynchronous Fetching}). - -@item -You can cache articles locally (@pxref{Article Caching}). - -@item -The uudecode functions have been expanded and generalized -(@pxref{Decoding Articles}). - -@item -You can still post uuencoded articles, which was a little-known feature -of @sc{gnus}' past (@pxref{Uuencoding and Posting}). - -@item -Fetching parents (and other articles) now actually works without -glitches (@pxref{Finding the Parent}). - -@item -Gnus can fetch @acronym{FAQ}s and group descriptions (@pxref{Group Information}). - -@item -Digests (and other files) can be used as the basis for groups -(@pxref{Document Groups}). - -@item -Articles can be highlighted and customized (@pxref{Customizing -Articles}). - -@item -URLs and other external references can be buttonized (@pxref{Article -Buttons}). - -@item -You can do lots of strange stuff with the Gnus window & frame -configuration (@pxref{Window Layout}). - -@end itemize - - -@node September Gnus -@subsubsection September Gnus - -@iftex -@iflatex -\gnusfig{-28cm}{0cm}{\epsfig{figure=ps/september,height=20cm}} -@end iflatex -@end iftex - -New features in Gnus 5.2/5.3: - -@itemize @bullet - -@item -A new message composition mode is used. All old customization variables -for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are -now obsolete. - -@item -Gnus is now able to generate @dfn{sparse} threads---threads where -missing articles are represented by empty nodes (@pxref{Customizing -Threading}). - -@lisp -(setq gnus-build-sparse-threads 'some) -@end lisp - -@item -Outgoing articles are stored on a special archive server -(@pxref{Archived Messages}). - -@item -Partial thread regeneration now happens when articles are -referred. - -@item -Gnus can make use of GroupLens predictions. - -@item -Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}). - -@item -A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}). - -@lisp -(setq gnus-use-trees t) -@end lisp - -@item -An @code{nn}-like pick-and-read minor mode is available for the summary -buffers (@pxref{Pick and Read}). - -@lisp -(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) -@end lisp - -@item -In binary groups you can use a special binary minor mode (@pxref{Binary -Groups}). - -@item -Groups can be grouped in a folding topic hierarchy (@pxref{Group -Topics}). - -@lisp -(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) -@end lisp - -@item -Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}). - -@item -Groups can now have a score, and bubbling based on entry frequency -is possible (@pxref{Group Score}). - -@lisp -(add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group) -@end lisp - -@item -Groups can be process-marked, and commands can be performed on -groups of groups (@pxref{Marking Groups}). - -@item -Caching is possible in virtual groups. - -@item -@code{nndoc} now understands all kinds of digests, mail boxes, rnews -news batches, ClariNet briefs collections, and just about everything -else (@pxref{Document Groups}). - -@item -Gnus has a new back end (@code{nnsoup}) to create/read SOUP packets. - -@item -The Gnus cache is much faster. - -@item -Groups can be sorted according to many criteria (@pxref{Sorting -Groups}). - -@item -New group parameters have been introduced to set list-addresses and -expiry times (@pxref{Group Parameters}). - -@item -All formatting specs allow specifying faces to be used -(@pxref{Formatting Fonts}). - -@item -There are several more commands for setting/removing/acting on process -marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}). - -@item -The summary buffer can be limited to show parts of the available -articles based on a wide range of criteria. These commands have been -bound to keys on the @kbd{/} submap (@pxref{Limiting}). - -@item -Articles can be made persistent with the @kbd{*} command -(@pxref{Persistent Articles}). - -@item -All functions for hiding article elements are now toggles. - -@item -Article headers can be buttonized (@pxref{Article Washing}). - -@item -All mail back ends support fetching articles by @code{Message-ID}. - -@item -Duplicate mail can now be treated properly (@pxref{Duplicates}). - -@item -All summary mode commands are available directly from the article -buffer (@pxref{Article Keymap}). - -@item -Frames can be part of @code{gnus-buffer-configuration} (@pxref{Window -Layout}). - -@item -Mail can be re-scanned by a daemonic process (@pxref{Daemons}). -@iftex -@iflatex -\marginpar[\mbox{}\hfill\epsfig{figure=ps/fseptember,height=5cm}]{\epsfig{figure=ps/fseptember,height=5cm}} -@end iflatex -@end iftex - -@item -Groups can be made permanently visible (@pxref{Listing Groups}). - -@lisp -(setq gnus-permanently-visible-groups "^nnml:") -@end lisp - -@item -Many new hooks have been introduced to make customizing easier. - -@item -Gnus respects the @code{Mail-Copies-To} header. - -@item -Threads can be gathered by looking at the @code{References} header -(@pxref{Customizing Threading}). - -@lisp -(setq gnus-summary-thread-gathering-function - 'gnus-gather-threads-by-references) -@end lisp - -@item -Read articles can be stored in a special backlog buffer to avoid -refetching (@pxref{Article Backlog}). - -@lisp -(setq gnus-keep-backlog 50) -@end lisp - -@item -A clean copy of the current article is always stored in a separate -buffer to allow easier treatment. - -@item -Gnus can suggest where to save articles (@pxref{Saving Articles}). - -@item -Gnus doesn't have to do as much prompting when saving (@pxref{Saving -Articles}). - -@lisp -(setq gnus-prompt-before-saving t) -@end lisp - -@item -@code{gnus-uu} can view decoded files asynchronously while fetching -articles (@pxref{Other Decode Variables}). - -@lisp -(setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view) -@end lisp - -@item -Filling in the article buffer now works properly on cited text -(@pxref{Article Washing}). - -@item -Hiding cited text adds buttons to toggle hiding, and how much -cited text to hide is now customizable (@pxref{Article Hiding}). - -@lisp -(setq gnus-cited-lines-visible 2) -@end lisp - -@item -Boring headers can be hidden (@pxref{Article Hiding}). - -@item -Default scoring values can now be set from the menu bar. - -@item -Further syntax checking of outgoing articles have been added. - -@end itemize - - -@node Red Gnus -@subsubsection Red Gnus - -New features in Gnus 5.4/5.5: - -@iftex -@iflatex -\gnusfig{-5.5cm}{-4cm}{\epsfig{figure=ps/red,height=20cm}} -@end iflatex -@end iftex - -@itemize @bullet - -@item -@file{nntp.el} has been totally rewritten in an asynchronous fashion. - -@item -Article prefetching functionality has been moved up into -Gnus (@pxref{Asynchronous Fetching}). - -@item -Scoring can now be performed with logical operators like @code{and}, -@code{or}, @code{not}, and parent redirection (@pxref{Advanced -Scoring}). - -@item -Article washing status can be displayed in the -article mode line (@pxref{Misc Article}). - -@item -@file{gnus.el} has been split into many smaller files. - -@item -Suppression of duplicate articles based on Message-ID can be done -(@pxref{Duplicate Suppression}). - -@lisp -(setq gnus-suppress-duplicates t) -@end lisp - -@item -New variables for specifying what score and adapt files are to be -considered home score and adapt files (@pxref{Home Score File}) have -been added. - -@item -@code{nndoc} was rewritten to be easily extensible (@pxref{Document -Server Internals}). - -@item -Groups can inherit group parameters from parent topics (@pxref{Topic -Parameters}). - -@item -Article editing has been revamped and is now actually usable. - -@item -Signatures can be recognized in more intelligent fashions -(@pxref{Article Signature}). - -@item -Summary pick mode has been made to look more @code{nn}-like. Line -numbers are displayed and the @kbd{.} command can be used to pick -articles (@code{Pick and Read}). - -@item -Commands for moving the @file{.newsrc.eld} from one server to -another have been added (@pxref{Changing Servers}). - -@item -There's a way now to specify that ``uninteresting'' fields be suppressed -when generating lines in buffers (@pxref{Advanced Formatting}). - -@item -Several commands in the group buffer can be undone with @kbd{C-M-_} -(@pxref{Undo}). - -@item -Scoring can be done on words using the new score type @code{w} -(@pxref{Score File Format}). - -@item -Adaptive scoring can be done on a Subject word-by-word basis -(@pxref{Adaptive Scoring}). - -@lisp -(setq gnus-use-adaptive-scoring '(word)) -@end lisp - -@item -Scores can be decayed (@pxref{Score Decays}). - -@lisp -(setq gnus-decay-scores t) -@end lisp - -@item -Scoring can be performed using a regexp on the Date header. The Date is -normalized to compact ISO 8601 format first (@pxref{Score File Format}). - -@item -A new command has been added to remove all data on articles from -the native server (@pxref{Changing Servers}). - -@item -A new command for reading collections of documents -(@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{C-M-d} -(@pxref{Really Various Summary Commands}). - -@item -Process mark sets can be pushed and popped (@pxref{Setting Process -Marks}). - -@item -A new mail-to-news back end makes it possible to post even when the @acronym{NNTP} -server doesn't allow posting (@pxref{Mail-To-News Gateways}). - -@item -A new back end for reading searches from Web search engines -(@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added -(@pxref{Web Searches}). - -@item -Groups inside topics can now be sorted using the standard sorting -functions, and each topic can be sorted independently (@pxref{Topic -Sorting}). - -@item -Subsets of the groups can be sorted independently (@code{Sorting -Groups}). - -@item -Cached articles can be pulled into the groups (@pxref{Summary Generation -Commands}). -@iftex -@iflatex -\marginpar[\mbox{}\hfill\epsfig{figure=ps/fred,width=3cm}]{\epsfig{figure=ps/fred,width=3cm}} -@end iflatex -@end iftex - -@item -Score files are now applied in a more reliable order (@pxref{Score -Variables}). - -@item -Reports on where mail messages end up can be generated (@pxref{Splitting -Mail}). - -@item -More hooks and functions have been added to remove junk from incoming -mail before saving the mail (@pxref{Washing Mail}). - -@item -Emphasized text can be properly fontisized: - -@end itemize - - -@node Quassia Gnus -@subsubsection Quassia Gnus - -New features in Gnus 5.6: - -@itemize @bullet - -@item -New functionality for using Gnus as an offline newsreader has been -added. A plethora of new commands and modes have been added. -@xref{Gnus Unplugged}, for the full story. - -@item -The @code{nndraft} back end has returned, but works differently than -before. All Message buffers are now also articles in the @code{nndraft} -group, which is created automatically. - -@item -@code{gnus-alter-header-function} can now be used to alter header -values. - -@item -@code{gnus-summary-goto-article} now accept Message-IDs. - -@item -A new Message command for deleting text in the body of a message -outside the region: @kbd{C-c C-v}. - -@item -You can now post to component group in @code{nnvirtual} groups with -@kbd{C-u C-c C-c}. - -@item - @code{nntp-rlogin-program}---new variable to ease customization. - -@item -@code{C-u C-c C-c} in @code{gnus-article-edit-mode} will now inhibit -re-highlighting of the article buffer. - -@item -New element in @code{gnus-boring-article-headers}---@code{long-to}. - -@item -@kbd{M-i} symbolic prefix command. @xref{Symbolic Prefixes}, for -details. - -@item -@kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix -@kbd{a} to add the score rule to the @file{all.SCORE} file. - -@item -@code{gnus-simplify-subject-functions} variable to allow greater -control over simplification. - -@item -@kbd{A T}---new command for fetching the current thread. - -@item -@kbd{/ T}---new command for including the current thread in the -limit. - -@item -@kbd{M-RET} is a new Message command for breaking cited text. - -@item -@samp{\\1}-expressions are now valid in @code{nnmail-split-methods}. - -@item -The @code{custom-face-lookup} function has been removed. -If you used this function in your initialization files, you must -rewrite them to use @code{face-spec-set} instead. - -@item -Canceling now uses the current select method. Symbolic prefix -@kbd{a} forces normal posting method. - -@item -New command to translate M******** sm*rtq**t*s into proper -text---@kbd{W d}. - -@item -For easier debugging of @code{nntp}, you can set -@code{nntp-record-commands} to a non-@code{nil} value. - -@item -@code{nntp} now uses @file{~/.authinfo}, a @file{.netrc}-like file, for -controlling where and how to send @sc{authinfo} to @acronym{NNTP} servers. - -@item -A command for editing group parameters from the summary buffer -has been added. - -@item -A history of where mails have been split is available. - -@item -A new article date command has been added---@code{article-date-iso8601}. - -@item -Subjects can be simplified when threading by setting -@code{gnus-score-thread-simplify}. - -@item -A new function for citing in Message has been -added---@code{message-cite-original-without-signature}. - -@item -@code{article-strip-all-blank-lines}---new article command. - -@item -A new Message command to kill to the end of the article has -been added. - -@item -A minimum adaptive score can be specified by using the -@code{gnus-adaptive-word-minimum} variable. - -@item -The ``lapsed date'' article header can be kept continually -updated by the @code{gnus-start-date-timer} command. - -@item -Web listserv archives can be read with the @code{nnlistserv} back end. - -@item -Old dejanews archives can now be read by @code{nnweb}. - -@end itemize - -@node Pterodactyl Gnus -@subsubsection Pterodactyl Gnus - -New features in Gnus 5.8: - -@itemize @bullet - -@item -The mail-fetching functions have changed. See the manual for the -many details. In particular, all procmail fetching variables are gone. - -If you used procmail like in - -@lisp -(setq nnmail-use-procmail t) -(setq nnmail-spool-file 'procmail) -(setq nnmail-procmail-directory "~/mail/incoming/") -(setq nnmail-procmail-suffix "\\.in") -@end lisp - -this now has changed to - -@lisp -(setq mail-sources - '((directory :path "~/mail/incoming/" - :suffix ".in"))) -@end lisp - -@xref{Mail Source Specifiers}. - -@item -Gnus is now a @acronym{MIME}-capable reader. This affects many parts of -Gnus, and adds a slew of new commands. See the manual for details. - -@item -Gnus has also been multilingualized. This also affects too -many parts of Gnus to summarize here, and adds many new variables. - -@item -@code{gnus-auto-select-first} can now be a function to be -called to position point. - -@item -The user can now decide which extra headers should be included in -summary buffers and @acronym{NOV} files. - -@item -@code{gnus-article-display-hook} has been removed. Instead, a number -of variables starting with @code{gnus-treat-} have been added. - -@item -The Gnus posting styles have been redone again and now works in a -subtly different manner. - -@item -New web-based back ends have been added: @code{nnslashdot}, -@code{nnwarchive} and @code{nnultimate}. nnweb has been revamped, -again, to keep up with ever-changing layouts. - -@item -Gnus can now read @acronym{IMAP} mail via @code{nnimap}. - -@end itemize - -@node Oort Gnus -@subsubsection Oort Gnus -@cindex Oort Gnus - -New features in Gnus 5.10: - -@itemize @bullet - -@item Installation changes -@c *********************** - -@itemize @bullet -@item -Upgrading from previous (stable) version if you have used Oort. - -If you have tried Oort (the unstable Gnus branch leading to this -release) but went back to a stable version, be careful when upgrading to -this version. In particular, you will probably want to remove all -@file{.marks} (nnml) and @file{.mrk} (nnfolder) files, so that flags are -read from your @file{.newsrc.eld} instead of from the -@file{.marks}/@file{.mrk} file where this release store flags. See a -later entry for more information about marks. Note that downgrading -isn't save in general. - -@item -Lisp files are now installed in @file{.../site-lisp/gnus/} by default. -It defaulted to @file{.../site-lisp/} formerly. In addition to this, -the new installer issues a warning if other Gnus installations which -will shadow the latest one are detected. You can then remove those -shadows manually or remove them using @code{make -remove-installed-shadows}. - -@item -New @file{make.bat} for compiling and installing Gnus under MS Windows - -Use @file{make.bat} if you want to install Gnus under MS Windows, the -first argument to the batch-program should be the directory where -@file{xemacs.exe} respectively @file{emacs.exe} is located, if you want -to install Gnus after compiling it, give @file{make.bat} @code{/copy} as -the second parameter. - -@file{make.bat} has been rewritten from scratch, it now features -automatic recognition of XEmacs and Emacs, generates -@file{gnus-load.el}, checks if errors occur while compilation and -generation of info files and reports them at the end of the build -process. It now uses @code{makeinfo} if it is available and falls -back to @file{infohack.el} otherwise. @file{make.bat} should now -install all files which are necessary to run Gnus and be generally a -complete replacement for the @code{configure; make; make install} -cycle used under Unix systems. - -The new @file{make.bat} makes @file{make-x.bat} and @file{xemacs.mak} -superfluous, so they have been removed. - -@item -@file{~/News/overview/} not used. - -As a result of the following change, the @file{~/News/overview/} -directory is not used any more. You can safely delete the entire -hierarchy. - -@c FIXME: `gnus-load' is mentioned in README, which is not included in -@c the repository. We should find a better place for this item. -@item -@code{(require 'gnus-load)} - -If you use a stand-alone Gnus distribution, you'd better add -@code{(require 'gnus-load)} into your @file{~/.emacs} after adding the Gnus -lisp directory into load-path. - -File @file{gnus-load.el} contains autoload commands, functions and variables, -some of which may not be included in distributions of Emacsen. - -@end itemize - -@item New packages and libraries within Gnus -@c ***************************************** - -@itemize @bullet - -@item -The revised Gnus @acronym{FAQ} is included in the manual, -@xref{Frequently Asked Questions}. - -@item -@acronym{TLS} wrapper shipped with Gnus - -@acronym{TLS}/@acronym{SSL} is now supported in @acronym{IMAP} and -@acronym{NNTP} via @file{tls.el} and GnuTLS. - -@item -Improved anti-spam features. - -Gnus is now able to take out spam from your mail and news streams -using a wide variety of programs and filter rules. Among the supported -methods are RBL blocklists, bogofilter and white/blacklists. Hooks -for easy use of external packages such as SpamAssassin and Hashcash -are also new. @ref{Thwarting Email Spam} and @ref{Spam Package}. -@c FIXME: @xref{Spam Package}?. Should this be under Misc? - -@item -Gnus supports server-side mail filtering using Sieve. - -Sieve rules can be added as Group Parameters for groups, and the -complete Sieve script is generated using @kbd{D g} from the Group -buffer, and then uploaded to the server using @kbd{C-c C-l} in the -generated Sieve buffer. @xref{Sieve Commands}, and the new Sieve -manual @ref{Top, , Top, sieve, Emacs Sieve}. - -@end itemize - -@item Changes in group mode -@c ************************ - -@itemize @bullet - -@item -@code{gnus-group-read-ephemeral-group} can be called interactively, -using @kbd{G M}. - -@item -Retrieval of charters and control messages - -There are new commands for fetching newsgroup charters (@kbd{H c}) and -control messages (@kbd{H C}). - -@item -The new variable @code{gnus-parameters} can be used to set group parameters. - -Earlier this was done only via @kbd{G p} (or @kbd{G c}), which stored -the parameters in @file{~/.newsrc.eld}, but via this variable you can -enjoy the powers of customize, and simplified backups since you set the -variable in @file{~/.gnus.el} instead of @file{~/.newsrc.eld}. The -variable maps regular expressions matching group names to group -parameters, a'la: -@lisp -(setq gnus-parameters - '(("mail\\..*" - (gnus-show-threads nil) - (gnus-use-scoring nil)) - ("^nnimap:\\(foo.bar\\)$" - (to-group . "\\1")))) -@end lisp - -@item -Unread count correct in nnimap groups. - -The estimated number of unread articles in the group buffer should now -be correct for nnimap groups. This is achieved by calling -@code{nnimap-fixup-unread-after-getting-new-news} from the -@code{gnus-setup-news-hook} (called on startup) and -@code{gnus-after-getting-new-news-hook} (called after getting new -mail). If you have modified those variables from the default, you may -want to add @code{nnimap-fixup-unread-after-getting-new-news} again. If -you were happy with the estimate and want to save some (minimal) time -when getting new mail, remove the function. - -@item -Group names are treated as UTF-8 by default. - -This is supposedly what USEFOR wanted to migrate to. See -@code{gnus-group-name-charset-group-alist} and -@code{gnus-group-name-charset-method-alist} for customization. - -@item -@code{gnus-group-charset-alist} and -@code{gnus-group-ignored-charsets-alist}. - -The regexps in these variables are compared with full group names -instead of real group names in 5.8. Users who customize these -variables should change those regexps accordingly. For example: -@lisp -("^han\\>" euc-kr) -> ("\\(^\\|:\\)han\\>" euc-kr) -@end lisp - -@item -Old intermediate incoming mail files (@file{Incoming*}) are deleted -after a couple of days, not immediately. @xref{Mail Source -Customization}. (New in Gnus 5.10.10 / Emacs 22.2) - -@end itemize - -@item Changes in summary and article mode -@c ************************************** - -@itemize @bullet - -@item -@kbd{F} (@code{gnus-article-followup-with-original}) and @kbd{R} -(@code{gnus-article-reply-with-original}) only yank the text in the -region if the region is active. - -@item -In draft groups, @kbd{e} is now bound to @code{gnus-draft-edit-message}. -Use @kbd{B w} for @code{gnus-summary-edit-article} instead. - -@item -Article Buttons - -More buttons for URLs, mail addresses, Message-IDs, Info links, man -pages and Emacs or Gnus related references. @xref{Article Buttons}. The -variables @code{gnus-button-@var{*}-level} can be used to control the -appearance of all article buttons. @xref{Article Button Levels}. - -@item -Single-part yenc encoded attachments can be decoded. - -@item -Picons - -The picons code has been reimplemented to work in GNU Emacs---some of -the previous options have been removed or renamed. - -Picons are small ``personal icons'' representing users, domain and -newsgroups, which can be displayed in the Article buffer. -@xref{Picons}. - -@item -If the new option @code{gnus-treat-body-boundary} is non-@code{nil}, a -boundary line is drawn at the end of the headers. - -@item -Signed article headers (X-PGP-Sig) can be verified with @kbd{W p}. - -@item -The Summary Buffer uses an arrow in the fringe to indicate the current -article. Use @code{(setq gnus-summary-display-arrow nil)} to disable it. - -@item -Warn about email replies to news - -Do you often find yourself replying to news by email by mistake? Then -the new option @code{gnus-confirm-mail-reply-to-news} is just the thing for -you. - -@item -If the new option @code{gnus-summary-display-while-building} is -non-@code{nil}, the summary buffer is shown and updated as it's being -built. - -@item -Gnus supports RFC 2369 mailing list headers, and adds a number of -related commands in mailing list groups. @xref{Mailing List}. - -@item -The Date header can be displayed in a format that can be read aloud -in English. @xref{Article Date}. - -@item -diffs are automatically highlighted in groups matching -@code{mm-uu-diff-groups-regexp} - -@item -Better handling of Microsoft citation styles - -Gnus now tries to recognize the mangled header block that some Microsoft -mailers use to indicate that the rest of the message is a citation, even -though it is not quoted in any way. The variable -@code{gnus-cite-unsightly-citation-regexp} matches the start of these -citations. - -The new command @kbd{W Y f} -(@code{gnus-article-outlook-deuglify-article}) allows deuglifying broken -Outlook (Express) articles. - -@item -@code{gnus-article-skip-boring} - -If you set @code{gnus-article-skip-boring} to @code{t}, then Gnus will -not scroll down to show you a page that contains only boring text, -which by default means cited text and signature. You can customize -what is skippable using @code{gnus-article-boring-faces}. - -This feature is especially useful if you read many articles that -consist of a little new content at the top with a long, untrimmed -message cited below. - -@item -Smileys (@samp{:-)}, @samp{;-)} etc.)@: are now displayed graphically in -Emacs too. - -Put @code{(setq gnus-treat-display-smileys nil)} in @file{~/.gnus.el} to -disable it. - -@item -Face headers handling. @xref{Face}. - -@item -In the summary buffer, the new command @kbd{/ N} inserts new messages -and @kbd{/ o} inserts old messages. - -@item -Gnus decodes morse encoded messages if you press @kbd{W m}. - -@item -@code{gnus-summary-line-format} - -The default value changed to @samp{%U%R%z%I%(%[%4L: %-23,23f%]%) -%s\n}. Moreover @code{gnus-extra-headers}, -@code{nnmail-extra-headers} and @code{gnus-ignored-from-addresses} -changed their default so that the users name will be replaced by the -recipient's name or the group name posting to for @acronym{NNTP} -groups. - -@item -Deleting of attachments. - -The command @code{gnus-mime-save-part-and-strip} (bound to @kbd{C-o} -on @acronym{MIME} buttons) saves a part and replaces the part with an -external one. @code{gnus-mime-delete-part} (bound to @kbd{d} on -@acronym{MIME} buttons) removes a part. It works only on back ends -that support editing. - -@item -@code{gnus-default-charset} - -The default value is determined from the -@code{current-language-environment} variable, instead of -@code{iso-8859-1}. Also the @samp{.*} item in -@code{gnus-group-charset-alist} is removed. - -@item -Printing capabilities are enhanced. - -Gnus supports Muttprint natively with @kbd{O P} from the Summary and -Article buffers. Also, each individual @acronym{MIME} part can be -printed using @kbd{p} on the @acronym{MIME} button. - -@item -Extended format specs. - -Format spec @samp{%&user-date;} is added into -@code{gnus-summary-line-format-alist}. Also, user defined extended -format specs are supported. The extended format specs look like -@samp{%u&foo;}, which invokes function -@code{gnus-user-format-function-@var{foo}}. Because @samp{&} is used as the -escape character, old user defined format @samp{%u&} is no longer supported. - -@item -@kbd{/ *} (@code{gnus-summary-limit-include-cached}) is rewritten. -@c FIXME: Was this a user-visible change? - -It was aliased to @kbd{Y c} -(@code{gnus-summary-insert-cached-articles}). The new function filters -out other articles. - -@item -Some limiting commands accept a @kbd{C-u} prefix to negate the match. - -If @kbd{C-u} is used on subject, author or extra headers, i.e., @kbd{/ -s}, @kbd{/ a}, and @kbd{/ x} -(@code{gnus-summary-limit-to-@{subject,author,extra@}}) respectively, the -result will be to display all articles that do not match the expression. - -@item -Gnus inlines external parts (message/external). - -@end itemize - -@item Changes in Message mode and related Gnus features -@c **************************************************** - -@itemize @bullet - -@item -Delayed articles - -You can delay the sending of a message with @kbd{C-c C-j} in the Message -buffer. The messages are delivered at specified time. This is useful -for sending yourself reminders. @xref{Delayed Articles}. - -@item -If the new option @code{nnml-use-compressed-files} is non-@code{nil}, -the nnml back end allows compressed message files. - -@item -The new option @code{gnus-gcc-mark-as-read} automatically marks -Gcc articles as read. - -@item -Externalizing of attachments - -If @code{gnus-gcc-externalize-attachments} or -@code{message-fcc-externalize-attachments} is non-@code{nil}, attach -local files as external parts. - -@item -The envelope sender address can be customized when using Sendmail. -@xref{Mail Variables, Mail Variables,, message, Message Manual}. - -@item -Gnus no longer generate the Sender: header automatically. - -Earlier it was generated when the user configurable email address was -different from the Gnus guessed default user address. As the guessing -algorithm is rarely correct these days, and (more controversially) the -only use of the Sender: header was to check if you are entitled to -cancel/supersede news (which is now solved by Cancel Locks instead, -see another entry), generation of the header has been disabled by -default. See the variables @code{message-required-headers}, -@code{message-required-news-headers}, and -@code{message-required-mail-headers}. - -@item -Features from third party @file{message-utils.el} added to @file{message.el}. - -Message now asks if you wish to remove @samp{(was: )} from -subject lines (see @code{message-subject-trailing-was-query}). @kbd{C-c -M-m} and @kbd{C-c M-f} inserts markers indicating included text. -@kbd{C-c C-f a} adds a X-No-Archive: header. @kbd{C-c C-f x} inserts -appropriate headers and a note in the body for cross-postings and -followups (see the variables @code{message-cross-post-@var{*}}). - -@item -References and X-Draft-From headers are no longer generated when you -start composing messages and @code{message-generate-headers-first} is -@code{nil}. - -@item -Easy inclusion of X-Faces headers. @xref{X-Face}. - -@item -Group Carbon Copy (GCC) quoting - -To support groups that contains SPC and other weird characters, groups -are quoted before they are placed in the Gcc: header. This means -variables such as @code{gnus-message-archive-group} should no longer -contain quote characters to make groups containing SPC work. Also, if -you are using the string @samp{nnml:foo, nnml:bar} (indicating Gcc -into two groups) you must change it to return the list -@code{("nnml:foo" "nnml:bar")}, otherwise the Gcc: line will be quoted -incorrectly. Note that returning the string @samp{nnml:foo, nnml:bar} -was incorrect earlier, it just didn't generate any problems since it -was inserted directly. - -@item -@code{message-insinuate-rmail} - -@c FIXME should that not be 'message-user-agent? -Adding @code{(message-insinuate-rmail)} and @code{(setq -mail-user-agent 'gnus-user-agent)} in @file{.emacs} convinces Rmail to -compose, reply and forward messages in message-mode, where you can -enjoy the power of @acronym{MML}. - -@item -@code{message-minibuffer-local-map} - -The line below enables BBDB in resending a message: -@lisp -(define-key message-minibuffer-local-map [(tab)] - 'bbdb-complete-name) -@end lisp - -@item -@code{gnus-posting-styles} - -Add a new format of match like -@lisp -((header "to" "larsi.*org") - (Organization "Somewhere, Inc.")) -@end lisp -The old format like the lines below is obsolete, but still accepted. -@lisp -(header "to" "larsi.*org" - (Organization "Somewhere, Inc.")) -@end lisp - -@item -@code{message-ignored-news-headers} and @code{message-ignored-mail-headers} - -@samp{X-Draft-From} and @samp{X-Gnus-Agent-Meta-Information} have been -added into these two variables. If you customized those, perhaps you -need add those two headers too. - -@item -Gnus supports the ``format=flowed'' (RFC 2646) parameter. On -composing messages, it is enabled by @code{use-hard-newlines}. -Decoding format=flowed was present but not documented in earlier -versions. - -@item -The option @code{mm-fill-flowed} can be used to disable treatment of -``format=flowed'' messages. Also, flowed text is disabled when sending -inline PGP signed messages. @xref{Flowed text, , Flowed text, -emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) -@c This entry is also present in the node "No Gnus". - -@item -Gnus supports the generation of RFC 2298 Disposition Notification requests. - -This is invoked with the @kbd{C-c M-n} key binding from message mode. - -@item -Message supports the Importance: (RFC 2156) header. - -In the message buffer, @kbd{C-c C-f C-i} or @kbd{C-c C-u} cycles through -the valid values. - -@item -Gnus supports Cancel Locks in News. - -This means a header @samp{Cancel-Lock} is inserted in news posting. It is -used to determine if you wrote an article or not (for canceling and -superseding). Gnus generates a random password string the first time -you post a message, and saves it in your @file{~/.emacs} using the Custom -system. While the variable is called @code{canlock-password}, it is not -security sensitive data. Publishing your canlock string on the web -will not allow anyone to be able to anything she could not already do. -The behavior can be changed by customizing @code{message-insert-canlock}. - -@item -Gnus supports @acronym{PGP} (RFC 1991/2440), @acronym{PGP/MIME} (RFC -2015/3156) and @acronym{S/MIME} (RFC 2630--2633). - -It needs an external @acronym{S/MIME} and OpenPGP implementation, but no -additional Lisp libraries. This add several menu items to the -Attachments menu, and @kbd{C-c RET} key bindings, when composing -messages. This also obsoletes @code{gnus-article-hide-pgp-hook}. - -@item -@acronym{MML} (Mime compose) prefix changed from @kbd{M-m} to @kbd{C-c -C-m}. - -This change was made to avoid conflict with the standard binding of -@code{back-to-indentation}, which is also useful in message mode. - -@item -The default for @code{message-forward-show-mml} changed to the symbol -@code{best}. - -The behavior for the @code{best} value is to show @acronym{MML} (i.e., -convert to @acronym{MIME}) when appropriate. @acronym{MML} will not be -used when forwarding signed or encrypted messages, as the conversion -invalidate the digital signature. - -@item -If @code{auto-compression-mode} is enabled, attachments are automatically -decompressed when activated. -@c FIXME: Does this affect article or message mode? - -@item -Support for non-@acronym{ASCII} domain names - -Message supports non-@acronym{ASCII} domain names in From:, To: and -Cc: and will query you whether to perform encoding when you try to -send a message. The variable @code{message-use-idna} controls this. -Gnus will also decode non-@acronym{ASCII} domain names in From:, To: -and Cc: when you view a message. The variable @code{gnus-use-idna} -controls this. - -@item You can now drag and drop attachments to the Message buffer. -See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. -@xref{MIME, ,MIME, message, Message Manual}. -@c New in 5.10.9 / 5.11 (Emacs 22.1) - -@item @code{auto-fill-mode} is enabled by default in Message mode. -See @code{message-fill-column}. @xref{Various Message Variables, , -Message Headers, message, Message Manual}. -@c New in Gnus 5.10.12 / 5.11 (Emacs 22.3) - -@end itemize - -@item Changes in back ends -@c *********************** - -@itemize @bullet -@item -Gnus can display RSS newsfeeds as a newsgroup. @xref{RSS}. - -@item -The nndoc back end now supports mailman digests and exim bounces. - -@item -Gnus supports Maildir groups. - -Gnus includes a new back end @file{nnmaildir.el}. @xref{Maildir}. - -@item -The nnml and nnfolder back ends store marks for each groups. - -This makes it possible to take backup of nnml/nnfolder servers/groups -separately of @file{~/.newsrc.eld}, while preserving marks. It also -makes it possible to share articles and marks between users (without -sharing the @file{~/.newsrc.eld} file) within, e.g., a department. It -works by storing the marks stored in @file{~/.newsrc.eld} in a per-group -file @file{.marks} (for nnml) and @file{@var{groupname}.mrk} (for -nnfolder, named @var{groupname}). If the nnml/nnfolder is moved to -another machine, Gnus will automatically use the @file{.marks} or -@file{.mrk} file instead of the information in @file{~/.newsrc.eld}. -The new server variables @code{nnml-marks-is-evil} and -@code{nnfolder-marks-is-evil} can be used to disable this feature. - -@end itemize - -@item Appearance -@c ************* - -@itemize @bullet - -@item -The menu bar item (in Group and Summary buffer) named ``Misc'' has -been renamed to ``Gnus''. - -@item -The menu bar item (in Message mode) named ``@acronym{MML}'' has been -renamed to ``Attachments''. Note that this menu also contains security -related stuff, like signing and encryption (@pxref{Security, Security,, -message, Message Manual}). - -@item -The tool bars have been updated to use GNOME icons in Group, Summary and -Message mode. You can also customize the tool bars: @kbd{M-x -customize-apropos RET -tool-bar$} should get you started. This is a new -feature in Gnus 5.10.10. (Only for Emacs, not in XEmacs.) - -@item The tool bar icons are now (de)activated correctly -in the group buffer, see the variable @code{gnus-group-update-tool-bar}. -Its default value depends on your Emacs version. This is a new feature -in Gnus 5.10.9. -@end itemize - - -@item Miscellaneous changes -@c ************************ - -@itemize @bullet - -@item -@code{gnus-agent} - -The Gnus Agent has seen a major updated and is now enabled by default, -and all nntp and nnimap servers from @code{gnus-select-method} and -@code{gnus-secondary-select-method} are agentized by default. Earlier -only the server in @code{gnus-select-method} was agentized by the -default, and the agent was disabled by default. When the agent is -enabled, headers are now also retrieved from the Agent cache instead -of the back ends when possible. Earlier this only happened in the -unplugged state. You can enroll or remove servers with @kbd{J a} and -@kbd{J r} in the server buffer. Gnus will not download articles into -the Agent cache, unless you instruct it to do so, though, by using -@kbd{J u} or @kbd{J s} from the Group buffer. You revert to the old -behavior of having the Agent disabled with @code{(setq gnus-agent -nil)}. Note that putting @code{(gnus-agentize)} in @file{~/.gnus.el} -is not needed any more. - -@item -Gnus reads the @acronym{NOV} and articles in the Agent if plugged. - -If one reads an article while plugged, and the article already exists -in the Agent, it won't get downloaded once more. @code{(setq -gnus-agent-cache nil)} reverts to the old behavior. - -@item -Dired integration - -@code{gnus-dired-minor-mode} (see @ref{Other modes}) installs key -bindings in dired buffers to send a file as an attachment, open a file -using the appropriate mailcap entry, and print a file using the mailcap -entry. - -@item -The format spec @code{%C} for positioning point has changed to @code{%*}. - -@item -@code{gnus-slave-unplugged} - -A new command which starts Gnus offline in slave mode. - -@end itemize - -@end itemize - -@node No Gnus -@subsubsection No Gnus -@cindex No Gnus - -New features in No Gnus: -@c FIXME: Gnus 5.12? - -@include gnus-news.texi - -@node Ma Gnus -@subsubsection Ma Gnus -@cindex Ma Gnus - -I'm sure there will be lots of text here. It's really spelled 真 -Gnus. - -New features in Ma Gnus: - -@itemize @bullet - -@item Changes in Message mode and related Gnus features -@c **************************************************** - -@itemize @bullet - -@item -The new hooks @code{gnus-gcc-pre-body-encode-hook} and -@code{gnus-gcc-post-body-encode-hook} are run before/after encoding -the message body of the Gcc copy of a sent message. See -@xref{Archived Messages}. - -@end itemize - -@end itemize - -@iftex - -@page -@node The Manual -@section The Manual -@cindex colophon -@cindex manual - -This manual was generated from a TeXinfo file and then run through -either @code{texi2dvi} -@iflatex -or my own home-brewed TeXinfo to \LaTeX\ transformer, -and then run through @code{latex} and @code{dvips} -@end iflatex -to get what you hold in your hands now. - -The following conventions have been used: - -@enumerate - -@item -This is a @samp{string} - -@item -This is a @kbd{keystroke} - -@item -This is a @file{file} - -@item -This is a @code{symbol} - -@end enumerate - -So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would -mean: - -@lisp -(setq flargnoze "yes") -@end lisp - -If I say ``set @code{flumphel} to @code{yes}'', that would mean: - -@lisp -(setq flumphel 'yes) -@end lisp - -@samp{yes} and @code{yes} are two @emph{very} different things---don't -ever get them confused. - -@iflatex -@c @head -Of course, everything in this manual is of vital interest, so you should -read it all. Several times. However, if you feel like skimming the -manual, look for that gnu head you should see in the margin over -there---it means that what's being discussed is of more importance than -the rest of the stuff. (On the other hand, if everything is infinitely -important, how can anything be more important than that? Just one more -of the mysteries of this world, I guess.) -@end iflatex - -@end iftex - - -@node On Writing Manuals -@section On Writing Manuals - -I guess most manuals are written after-the-fact; documenting a program -that's already there. This is not how this manual is written. When -implementing something, I write the manual entry for that something -straight away. I then see that it's difficult to explain the -functionality, so I write how it's supposed to be, and then I change the -implementation. Writing the documentation and writing the code go hand -in hand. - -This, of course, means that this manual has no, or little, flow. It -documents absolutely everything in Gnus, but often not where you're -looking for it. It is a reference manual, and not a guide to how to get -started with Gnus. - -That would be a totally different book, that should be written using the -reference manual as source material. It would look quite different. - - -@page -@node Terminology -@section Terminology - -@cindex terminology -@table @dfn - -@item news -@cindex news -This is what you are supposed to use this thing for---reading news. -News is generally fetched from a nearby @acronym{NNTP} server, and is -generally publicly available to everybody. If you post news, the entire -world is likely to read just what you have written, and they'll all -snigger mischievously. Behind your back. - -@item mail -@cindex mail -Everything that's delivered to you personally is mail. Some news/mail -readers (like Gnus) blur the distinction between mail and news, but -there is a difference. Mail is private. News is public. Mailing is -not posting, and replying is not following up. - -@item reply -@cindex reply -Send a mail to the person who has written what you are reading. - -@item follow up -@cindex follow up -Post an article to the current newsgroup responding to the article you -are reading. - -@item back end -@cindex back end -Gnus considers mail and news to be mostly the same, really. The only -difference is how to access the actual articles. News articles are -commonly fetched via the protocol @acronym{NNTP}, whereas mail -messages could be read from a file on the local disk. The internal -architecture of Gnus thus comprises a ``front end'' and a number of -``back ends''. Internally, when you enter a group (by hitting -@key{RET}, say), you thereby invoke a function in the front end in -Gnus. The front end then ``talks'' to a back end and says things like -``Give me the list of articles in the foo group'' or ``Show me article -number 4711''. - -So a back end mainly defines either a protocol (the @code{nntp} back -end accesses news via @acronym{NNTP}, the @code{nnimap} back end -accesses mail via @acronym{IMAP}) or a file format and directory -layout (the @code{nnspool} back end accesses news via the common -``spool directory'' format, the @code{nnml} back end access mail via a -file format and directory layout that's quite similar). - -Gnus does not handle the underlying media, so to speak---this is all -done by the back ends. A back end is a collection of functions to -access the articles. - -However, sometimes the term ``back end'' is also used where ``server'' -would have been more appropriate. And then there is the term ``select -method'' which can mean either. The Gnus terminology can be quite -confusing. - -@item native -@cindex native -Gnus will always use one method (and back end) as the @dfn{native}, or -default, way of getting news. Groups from the native select method -have names like @samp{gnu.emacs.gnus}. - -@item foreign -@cindex foreign -You can also have any number of foreign groups active at the same -time. These are groups that use non-native non-secondary back ends -for getting news. Foreign groups have names like -@samp{nntp+news.gmane.org:gmane.emacs.gnus.devel}. - -@item secondary -@cindex secondary -Secondary back ends are somewhere half-way between being native and -being foreign, but they mostly act like they are native, but they, too -have names like @samp{nntp+news.gmane.org:gmane.emacs.gnus.devel}. - -@item article -@cindex article -A message that has been posted as news. - -@item mail message -@cindex mail message -A message that has been mailed. - -@item message -@cindex message -A mail message or news article - -@item head -@cindex head -The top part of a message, where administrative information (etc.)@: is -put. - -@item body -@cindex body -The rest of an article. Everything not in the head is in the -body. - -@item header -@cindex header -A line from the head of an article. - -@item headers -@cindex headers -A collection of such lines, or a collection of heads. Or even a -collection of @acronym{NOV} lines. - -@item @acronym{NOV} -@cindex @acronym{NOV} -@acronym{NOV} stands for News OverView, which is a type of news server -header which provide datas containing the condensed header information -of articles. They are produced by the server itself; in the @code{nntp} -back end Gnus uses the ones that the @acronym{NNTP} server makes, but -Gnus makes them by itself for some backends (in particular, @code{nnml}). - -When Gnus enters a group, it asks the back end for the headers of all -unread articles in the group. Most servers support the News OverView -format, which is more compact and much faster to read and parse than the -normal @sc{head} format. - -The @acronym{NOV} data consist of one or more text lines (@pxref{Text -Lines, ,Motion by Text Lines, elisp, The Emacs Lisp Reference Manual}) -where each line has the header information of one article. The header -information is a tab-separated series of the header's contents including -an article number, a subject, an author, a date, a message-id, -references, etc. - -Those data enable Gnus to generate summary lines quickly. However, if -the server does not support @acronym{NOV} or you disable it purposely or -for some reason, Gnus will try to generate the header information by -parsing each article's headers one by one. It will take time. -Therefore, it is not usually a good idea to set nn*-nov-is-evil -(@pxref{Slow/Expensive Connection}) to a non-@code{nil} value unless you -know that the server makes wrong @acronym{NOV} data. - -@item level -@cindex levels -Each group is subscribed at some @dfn{level} or other (1--9). The ones -that have a lower level are ``more'' subscribed than the groups with a -higher level. In fact, groups on levels 1--5 are considered -@dfn{subscribed}; 6--7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9 -are @dfn{killed}. Commands for listing groups and scanning for new -articles will all use the numeric prefix as @dfn{working level}. - -@item killed groups -@cindex killed groups -No information on killed groups is stored or updated, which makes killed -groups much easier to handle than subscribed groups. - -@item zombie groups -@cindex zombie groups -Just like killed groups, only slightly less dead. - -@item active file -@cindex active file -The news server has to keep track of what articles it carries, and what -groups exist. All this information in stored in the active file, which -is rather large, as you might surmise. - -@item bogus groups -@cindex bogus groups -A group that exists in the @file{.newsrc} file, but isn't known to the -server (i.e., it isn't in the active file), is a @emph{bogus group}. -This means that the group probably doesn't exist (any more). - -@item activating -@cindex activating groups -The act of asking the server for info on a group and computing the -number of unread articles is called @dfn{activating the group}. -Un-activated groups are listed with @samp{*} in the group buffer. - -@item spool -@cindex spool -News servers store their articles locally in one fashion or other. -One old-fashioned storage method is to have just one file per -article. That's called a ``traditional spool''. - -@item server -@cindex server -A machine one can connect to and get news (or mail) from. - -@item select method -@cindex select method -A structure that specifies the back end, the server and the virtual -server settings. - -@item virtual server -@cindex virtual server -A named select method. Since a select method defines all there is to -know about connecting to a (physical) server, taking the thing as a -whole is a virtual server. - -@item washing -@cindex washing -Taking a buffer and running it through a filter of some sort. The -result will (more often than not) be cleaner and more pleasing than the -original. - -@item ephemeral groups -@cindex ephemeral groups -@cindex temporary groups -Most groups store data on what articles you have read. @dfn{Ephemeral} -groups are groups that will have no data stored---when you exit the -group, it'll disappear into the aether. - -@item solid groups -@cindex solid groups -This is the opposite of ephemeral groups. All groups listed in the -group buffer are solid groups. - -@item sparse articles -@cindex sparse articles -These are article placeholders shown in the summary buffer when -@code{gnus-build-sparse-threads} has been switched on. - -@item threading -@cindex threading -To put responses to articles directly after the articles they respond -to---in a hierarchical fashion. - -@item root -@cindex root -@cindex thread root -The first article in a thread is the root. It is the ancestor of all -articles in the thread. - -@item parent -@cindex parent -An article that has responses. - -@item child -@cindex child -An article that responds to a different article---its parent. - -@item digest -@cindex digest -A collection of messages in one file. The most common digest format is -specified by RFC 1153. - -@item splitting -@cindex splitting, terminology -@cindex mail sorting -@cindex mail filtering (splitting) -The action of sorting your emails according to certain rules. Sometimes -incorrectly called mail filtering. - -@end table - - -@page -@node Customization -@section Customization -@cindex general customization - -All variables are properly documented elsewhere in this manual. This -section is designed to give general pointers on how to customize Gnus -for some quite common situations. - -@menu -* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. -* Slow Terminal Connection:: You run a remote Emacs. -* Little Disk Space:: You feel that having large setup files is icky. -* Slow Machine:: You feel like buying a faster machine. -@end menu - - -@node Slow/Expensive Connection -@subsection Slow/Expensive Connection - -If you run Emacs on a machine locally, and get your news from a machine -over some very thin strings, you want to cut down on the amount of data -Gnus has to get from the server. - -@table @code - -@item gnus-read-active-file -Set this to @code{nil}, which will inhibit Gnus from requesting the -entire active file from the server. This file is often very large. You -also have to set @code{gnus-check-new-newsgroups} and -@code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus -doesn't suddenly decide to fetch the active file anyway. - -@item gnus-nov-is-evil -@vindex gnus-nov-is-evil -Usually this one must @emph{always} be @code{nil} (which is the -default). If, for example, you wish to not use @acronym{NOV} -(@pxref{Terminology}) with the @code{nntp} back end (@pxref{Crosspost -Handling}), set @code{nntp-nov-is-evil} to a non-@code{nil} value -instead of setting this. But you normally do not need to set -@code{nntp-nov-is-evil} since Gnus by itself will detect whether the -@acronym{NNTP} server supports @acronym{NOV}. Anyway, grabbing article -headers from the @acronym{NNTP} server will not be very fast if you tell -Gnus not to use @acronym{NOV}. - -As the variables for the other back ends, there are -@code{nndiary-nov-is-evil}, @code{nndir-nov-is-evil}, -@code{nnfolder-nov-is-evil}, @code{nnimap-nov-is-evil}, -@code{nnml-nov-is-evil}, and @code{nnspool-nov-is-evil}. Note that a -non-@code{nil} value for @code{gnus-nov-is-evil} overrides all those -variables. -@end table - - -@node Slow Terminal Connection -@subsection Slow Terminal Connection - -Let's say you use your home computer for dialing up the system that runs -Emacs and Gnus. If your modem is slow, you want to reduce (as much as -possible) the amount of data sent over the wires. - -@table @code - -@item gnus-auto-center-summary -Set this to @code{nil} to inhibit Gnus from re-centering the summary -buffer all the time. If it is @code{vertical}, do only vertical -re-centering. If it is neither @code{nil} nor @code{vertical}, do both -horizontal and vertical recentering. - -@item gnus-visible-headers -Cut down on the headers included in the articles to the -minimum. You can, in fact, make do without them altogether---most of the -useful data is in the summary buffer, anyway. Set this variable to -@samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need. - -Use the following to enable all the available hiding features: -@lisp -(setq gnus-treat-hide-headers 'head - gnus-treat-hide-signature t - gnus-treat-hide-citation t) -@end lisp - -@item gnus-use-full-window -By setting this to @code{nil}, you can make all the windows smaller. -While this doesn't really cut down much generally, it means that you -have to see smaller portions of articles before deciding that you didn't -want to read them anyway. - -@item gnus-thread-hide-subtree -If this is non-@code{nil}, all threads in the summary buffer will be -hidden initially. - - -@item gnus-updated-mode-lines -If this is @code{nil}, Gnus will not put information in the buffer mode -lines, which might save some time. -@end table - - -@node Little Disk Space -@subsection Little Disk Space -@cindex disk space - -The startup files can get rather large, so you may want to cut their -sizes a bit if you are running out of space. - -@table @code - -@item gnus-save-newsrc-file -If this is @code{nil}, Gnus will never save @file{.newsrc}---it will -only save @file{.newsrc.eld}. This means that you will not be able to -use any other newsreaders than Gnus. This variable is @code{t} by -default. - -@item gnus-read-newsrc-file -If this is @code{nil}, Gnus will never read @file{.newsrc}---it will -only read @file{.newsrc.eld}. This means that you will not be able to -use any other newsreaders than Gnus. This variable is @code{t} by -default. - -@item gnus-save-killed-list -If this is @code{nil}, Gnus will not save the list of dead groups. You -should also set @code{gnus-check-new-newsgroups} to @code{ask-server} -and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this -variable to @code{nil}. This variable is @code{t} by default. - -@end table - - -@node Slow Machine -@subsection Slow Machine -@cindex slow machine - -If you have a slow machine, or are just really impatient, there are a -few things you can do to make Gnus run faster. - -Set @code{gnus-check-new-newsgroups} and -@code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster. - -Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and -@code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the -summary buffer faster. Also @pxref{Slow/Expensive Connection}. - - -@page -@node Troubleshooting -@section Troubleshooting -@cindex troubleshooting - -Gnus works @emph{so} well straight out of the box---I can't imagine any -problems, really. - -Ahem. - -@enumerate - -@item -Make sure your computer is switched on. - -@item -Make sure that you really load the current Gnus version. If you have -been running @sc{gnus}, you need to exit Emacs and start it up again before -Gnus will work. - -@item -Try doing an @kbd{M-x gnus-version}. If you get something that looks -like @c -@samp{Gnus v5.13} @c Adjust ../Makefile.in if you change this line! -@c -you have the right files loaded. Otherwise you have some old @file{.el} -files lying around. Delete these. - -@item -Read the help group (@kbd{G h} in the group buffer) for a -@acronym{FAQ} and a how-to. - -@item -@vindex max-lisp-eval-depth -Gnus works on many recursive structures, and in some extreme (and very -rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at -you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or -something like that. -@end enumerate - -If all else fails, report the problem as a bug. - -@cindex bugs -@cindex reporting bugs - -@kindex M-x gnus-bug -@findex gnus-bug -If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug} -command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send -me the backtrace. I will fix bugs, but I can only fix them if you send -me a precise description as to how to reproduce the bug. - -You really can never be too detailed in a bug report. Always use the -@kbd{M-x gnus-bug} command when you make bug reports, even if it creates -a 10Kb mail each time you use it, and even if you have sent me your -environment 500 times before. I don't care. I want the full info each -time. - -It is also important to remember that I have no memory whatsoever. If -you send a bug report, and I send you a reply, and then you just send -back ``No, it's not! Moron!'', I will have no idea what you are -insulting me about. Always over-explain everything. It's much easier -for all of us---if I don't have all the information I need, I will just -mail you and ask for more info, and everything takes more time. - -If the problem you're seeing is very visual, and you can't quite explain -it, copy the Emacs window to a file (with @code{xwd}, for instance), put -it somewhere it can be reached, and include the URL of the picture in -the bug report. - -@cindex patches -If you would like to contribute a patch to fix bugs or make -improvements, please produce the patch using @samp{diff -u}. - -@cindex edebug -If you want to debug your problem further before reporting, possibly -in order to solve the problem yourself and send a patch, you can use -edebug. Debugging Lisp code is documented in the Elisp manual -(@pxref{Debugging, , Debugging Lisp Programs, elisp, The GNU Emacs -Lisp Reference Manual}). To get you started with edebug, consider if -you discover some weird behavior when pressing @kbd{c}, the first -step is to do @kbd{C-h k c} and click on the hyperlink (Emacs only) in -the documentation buffer that leads you to the function definition, -then press @kbd{M-x edebug-defun RET} with point inside that function, -return to Gnus and press @kbd{c} to invoke the code. You will be -placed in the lisp buffer and can single step using @kbd{SPC} and -evaluate expressions using @kbd{M-:} or inspect variables using -@kbd{C-h v}, abort execution with @kbd{q}, and resume execution with -@kbd{c} or @kbd{g}. - -@cindex elp -@cindex profile -@cindex slow -Sometimes, a problem do not directly generate an elisp error but -manifests itself by causing Gnus to be very slow. In these cases, you -can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-g} when things are -slow, and then try to analyze the backtrace (repeating the procedure -helps isolating the real problem areas). - -A fancier approach is to use the elisp profiler, ELP@. The profiler is -(or should be) fully documented elsewhere, but to get you started -there are a few steps that need to be followed. First, instrument the -part of Gnus you are interested in for profiling, e.g., @kbd{M-x -elp-instrument-package RET gnus} or @kbd{M-x elp-instrument-package -RET message}. Then perform the operation that is slow and press -@kbd{M-x elp-results}. You will then see which operations that takes -time, and can debug them further. If the entire operation takes much -longer than the time spent in the slowest function in the profiler -output, you probably profiled the wrong part of Gnus. To reset -profiling statistics, use @kbd{M-x elp-reset-all}. @kbd{M-x -elp-restore-all} is supposed to remove profiling, but given the -complexities and dynamic code generation in Gnus, it might not always -work perfectly. - -@cindex gnu.emacs.gnus -@cindex ding mailing list -If you just need help, you are better off asking on -@samp{gnu.emacs.gnus}. I'm not very helpful. You can also ask on -@email{ding@@gnus.org, the ding mailing list}. Write to -@email{ding-request@@gnus.org} to subscribe. - - -@page -@node Gnus Reference Guide -@section Gnus Reference Guide - -It is my hope that other people will figure out smart stuff that Gnus -can do, and that other people will write those smart things as well. To -facilitate that I thought it would be a good idea to describe the inner -workings of Gnus. And some of the not-so-inner workings, while I'm at -it. - -You can never expect the internals of a program not to change, but I -will be defining (in some details) the interface between Gnus and its -back ends (this is written in stone), the format of the score files -(ditto), data structures (some are less likely to change than others) -and general methods of operation. - -@menu -* Gnus Utility Functions:: Common functions and variable to use. -* Back End Interface:: How Gnus communicates with the servers. -* Score File Syntax:: A BNF definition of the score file standard. -* Headers:: How Gnus stores headers internally. -* Ranges:: A handy format for storing mucho numbers. -* Group Info:: The group info format. -* Extended Interactive:: Symbolic prefixes and stuff. -* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. -* Various File Formats:: Formats of files that Gnus use. -@end menu - - -@node Gnus Utility Functions -@subsection Gnus Utility Functions -@cindex Gnus utility functions -@cindex utility functions -@cindex functions -@cindex internal variables - -When writing small functions to be run from hooks (and stuff), it's -vital to have access to the Gnus internal functions and variables. -Below is a list of the most common ones. - -@table @code - -@item gnus-newsgroup-name -@vindex gnus-newsgroup-name -This variable holds the name of the current newsgroup. - -@item gnus-find-method-for-group -@findex gnus-find-method-for-group -A function that returns the select method for @var{group}. - -@item gnus-group-real-name -@findex gnus-group-real-name -Takes a full (prefixed) Gnus group name, and returns the unprefixed -name. - -@item gnus-group-prefixed-name -@findex gnus-group-prefixed-name -Takes an unprefixed group name and a select method, and returns the full -(prefixed) Gnus group name. - -@item gnus-get-info -@findex gnus-get-info -Returns the group info list for @var{group} (@pxref{Group Info}). - -@item gnus-group-unread -@findex gnus-group-unread -The number of unread articles in @var{group}, or @code{t} if that is -unknown. - -@item gnus-active -@findex gnus-active -The active entry (i.e., a cons cell containing the lowest and highest -article numbers) for @var{group}. - -@item gnus-set-active -@findex gnus-set-active -Set the active entry for @var{group}. - -@item gnus-add-current-to-buffer-list -@findex gnus-add-current-to-buffer-list -Adds the current buffer to the list of buffers to be killed on Gnus -exit. - -@item gnus-continuum-version -@findex gnus-continuum-version -Takes a Gnus version string as a parameter and returns a floating point -number. Earlier versions will always get a lower number than later -versions. - -@item gnus-group-read-only-p -@findex gnus-group-read-only-p -Says whether @var{group} is read-only or not. - -@item gnus-news-group-p -@findex gnus-news-group-p -Says whether @var{group} came from a news back end. - -@item gnus-ephemeral-group-p -@findex gnus-ephemeral-group-p -Says whether @var{group} is ephemeral or not. - -@item gnus-server-to-method -@findex gnus-server-to-method -Returns the select method corresponding to @var{server}. - -@item gnus-server-equal -@findex gnus-server-equal -Says whether two virtual servers are essentially equal. For instance, -two virtual servers may have server parameters in different order, but -this function will consider them equal. - -@item gnus-group-native-p -@findex gnus-group-native-p -Says whether @var{group} is native or not. - -@item gnus-group-secondary-p -@findex gnus-group-secondary-p -Says whether @var{group} is secondary or not. - -@item gnus-group-foreign-p -@findex gnus-group-foreign-p -Says whether @var{group} is foreign or not. - -@item gnus-group-find-parameter -@findex gnus-group-find-parameter -Returns the parameter list of @var{group} (@pxref{Group Parameters}). -If given a second parameter, returns the value of that parameter for -@var{group}. - -@item gnus-group-set-parameter -@findex gnus-group-set-parameter -Takes three parameters; @var{group}, @var{parameter} and @var{value}. - -@item gnus-narrow-to-body -@findex gnus-narrow-to-body -Narrows the current buffer to the body of the article. - -@item gnus-check-backend-function -@findex gnus-check-backend-function -Takes two parameters, @var{function} and @var{group}. If the back end -@var{group} comes from supports @var{function}, return non-@code{nil}. - -@lisp -(gnus-check-backend-function "request-scan" "nnml:misc") -@result{} t -@end lisp - -@item gnus-read-method -@findex gnus-read-method -Prompts the user for a select method. - -@end table - - -@node Back End Interface -@subsection Back End Interface - -Gnus doesn't know anything about @acronym{NNTP}, spools, mail or virtual -groups. It only knows how to talk to @dfn{virtual servers}. A virtual -server is a @dfn{back end} and some @dfn{back end variables}. As examples -of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As -examples of the latter we have @code{nntp-port-number} and -@code{nnmbox-directory}. - -When Gnus asks for information from a back end---say @code{nntp}---on -something, it will normally include a virtual server name in the -function parameters. (If not, the back end should use the ``current'' -virtual server.) For instance, @code{nntp-request-list} takes a virtual -server as its only (optional) parameter. If this virtual server hasn't -been opened, the function should fail. - -Note that a virtual server name has no relation to some physical server -name. Take this example: - -@lisp -(nntp "odd-one" - (nntp-address "ifi.uio.no") - (nntp-port-number 4324)) -@end lisp - -Here the virtual server name is @samp{odd-one} while the name of -the physical server is @samp{ifi.uio.no}. - -The back ends should be able to switch between several virtual servers. -The standard back ends implement this by keeping an alist of virtual -server environments that they pull down/push up when needed. - -There are two groups of interface functions: @dfn{required functions}, -which must be present, and @dfn{optional functions}, which Gnus will -always check for presence before attempting to call 'em. - -All these functions are expected to return data in the buffer -@code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat -unfortunately named, but we'll have to live with it. When I talk about -@dfn{resulting data}, I always refer to the data in that buffer. When I -talk about @dfn{return value}, I talk about the function value returned by -the function call. Functions that fail should return @code{nil} as the -return value. - -Some back ends could be said to be @dfn{server-forming} back ends, and -some might be said not to be. The latter are back ends that generally -only operate on one group at a time, and have no concept of ``server''; -they have a group, and they deliver info on that group and nothing -more. - -Gnus identifies each message by way of group name and article number. A -few remarks about these article numbers might be useful. First of all, -the numbers are positive integers. Secondly, it is normally not -possible for later articles to ``re-use'' older article numbers without -confusing Gnus. That is, if a group has ever contained a message -numbered 42, then no other message may get that number, or Gnus will get -mightily confused.@footnote{See the function -@code{nnchoke-request-update-info}, @ref{Optional Back End Functions}.} -Third, article numbers must be assigned in order of arrival in the -group; this is not necessarily the same as the date of the message. - -The previous paragraph already mentions all the ``hard'' restrictions that -article numbers must fulfill. But it seems that it might be useful to -assign @emph{consecutive} article numbers, for Gnus gets quite confused -if there are holes in the article numbering sequence. However, due to -the ``no-reuse'' restriction, holes cannot be avoided altogether. It's -also useful for the article numbers to start at 1 to avoid running out -of numbers as long as possible. - -Note that by convention, back ends are named @code{nnsomething}, but -Gnus also comes with some @code{nnnotbackends}, such as -@file{nnheader.el}, @file{nnmail.el} and @file{nnoo.el}. - -In the examples and definitions I will refer to the imaginary back end -@code{nnchoke}. - -@cindex @code{nnchoke} - -@menu -* Required Back End Functions:: Functions that must be implemented. -* Optional Back End Functions:: Functions that need not be implemented. -* Error Messaging:: How to get messages and report errors. -* Writing New Back Ends:: Extending old back ends. -* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end. -* Mail-like Back Ends:: Some tips on mail back ends. -@end menu - - -@node Required Back End Functions -@subsubsection Required Back End Functions - -@table @code - -@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD) - -@var{articles} is either a range of article numbers or a list of -@code{Message-ID}s. Current back ends do not fully support either---only -sequences (lists) of article numbers, and most back ends do not support -retrieval of @code{Message-ID}s. But they should try for both. - -The result data should either be HEADs or @acronym{NOV} lines, and the result -value should either be @code{headers} or @code{nov} to reflect this. -This might later be expanded to @code{various}, which will be a mixture -of HEADs and @acronym{NOV} lines, but this is currently not supported by Gnus. - -If @var{fetch-old} is non-@code{nil} it says to try fetching ``extra -headers'', in some meaning of the word. This is generally done by -fetching (at most) @var{fetch-old} extra headers less than the smallest -article number in @code{articles}, and filling the gaps as well. The -presence of this parameter can be ignored if the back end finds it -cumbersome to follow the request. If this is non-@code{nil} and not a -number, do maximum fetches. - -Here's an example HEAD: - -@example -221 1056 Article retrieved. -Path: ifi.uio.no!sturles -From: sturles@@ifi.uio.no (Sturle Sunde) -Newsgroups: ifi.discussion -Subject: Re: Something very droll -Date: 27 Oct 1994 14:02:57 +0100 -Organization: Dept. of Informatics, University of Oslo, Norway -Lines: 26 -Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no> -References: <38jdmq$4qu@@visbur.ifi.uio.no> -NNTP-Posting-Host: holmenkollen.ifi.uio.no -. -@end example - -So a @code{headers} return value would imply that there's a number of -these in the data buffer. - -Here's a BNF definition of such a buffer: - -@example -headers = *head -head = error / valid-head -error-message = [ "4" / "5" ] 2number " " eol -valid-head = valid-message *header "." eol -valid-message = "221 " " Article retrieved." eol -header = eol -@end example - -@cindex BNF -(The version of BNF used here is the one used in RFC822.) - -If the return value is @code{nov}, the data buffer should contain -@dfn{network overview database} lines. These are basically fields -separated by tabs. - -@example -nov-buffer = *nov-line -nov-line = field 7*8[ field ] eol -field = -@end example - -For a closer look at what should be in those fields, -@pxref{Headers}. - - -@item (nnchoke-open-server SERVER &optional DEFINITIONS) - -@var{server} is here the virtual server name. @var{definitions} is a -list of @code{(VARIABLE VALUE)} pairs that define this virtual server. - -If the server can't be opened, no error should be signaled. The back end -may then choose to refuse further attempts at connecting to this -server. In fact, it should do so. - -If the server is opened already, this function should return a -non-@code{nil} value. There should be no data returned. - - -@item (nnchoke-close-server &optional SERVER) - -Close connection to @var{server} and free all resources connected -to it. Return @code{nil} if the server couldn't be closed for some -reason. - -There should be no data returned. - - -@item (nnchoke-request-close) - -Close connection to all servers and free all resources that the back end -have reserved. All buffers that have been created by that back end -should be killed. (Not the @code{nntp-server-buffer}, though.) This -function is generally only called when Gnus is shutting down. - -There should be no data returned. - - -@item (nnchoke-server-opened &optional SERVER) - -If @var{server} is the current virtual server, and the connection to the -physical server is alive, then this function should return a -non-@code{nil} value. This function should under no circumstances -attempt to reconnect to a server we have lost connection to. - -There should be no data returned. - - -@item (nnchoke-status-message &optional SERVER) - -This function should return the last error message from @var{server}. - -There should be no data returned. - - -@item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER) - -The result data from this function should be the article specified by -@var{article}. This might either be a @code{Message-ID} or a number. -It is optional whether to implement retrieval by @code{Message-ID}, but -it would be nice if that were possible. - -If @var{to-buffer} is non-@code{nil}, the result data should be returned -in this buffer instead of the normal data buffer. This is to make it -possible to avoid copying large amounts of data from one buffer to -another, while Gnus mainly requests articles to be inserted directly -into its article buffer. - -If it is at all possible, this function should return a cons cell where -the @code{car} is the group name the article was fetched from, and the @code{cdr} is -the article number. This will enable Gnus to find out what the real -group and article numbers are when fetching articles by -@code{Message-ID}. If this isn't possible, @code{t} should be returned -on successful article retrieval. - - -@item (nnchoke-request-group GROUP &optional SERVER FAST INFO) - -Get data on @var{group}. This function also has the side effect of -making @var{group} the current group. - -If @var{fast}, don't bother to return useful data, just make @var{group} -the current group. - -If @var{info}, it allows the backend to update the group info -structure. - -Here's an example of some result data and a definition of the same: - -@example -211 56 1000 1059 ifi.discussion -@end example - -The first number is the status, which should be 211. Next is the -total number of articles in the group, the lowest article number, the -highest article number, and finally the group name. Note that the total -number of articles may be less than one might think while just -considering the highest and lowest article numbers, but some articles -may have been canceled. Gnus just discards the total-number, so -whether one should take the bother to generate it properly (if that is a -problem) is left as an exercise to the reader. If the group contains no -articles, the lowest article number should be reported as 1 and the -highest as 0. - -@example -group-status = [ error / info ] eol -error = [ "4" / "5" ] 2 " " -info = "211 " 3* [ " " ] -@end example - - -@item (nnchoke-close-group GROUP &optional SERVER) - -Close @var{group} and free any resources connected to it. This will be -a no-op on most back ends. - -There should be no data returned. - - -@item (nnchoke-request-list &optional SERVER) - -Return a list of all groups available on @var{server}. And that means -@emph{all}. - -Here's an example from a server that only carries two groups: - -@example -ifi.test 0000002200 0000002000 y -ifi.discussion 3324 3300 n -@end example - -On each line we have a group name, then the highest article number in -that group, the lowest article number, and finally a flag. If the group -contains no articles, the lowest article number should be reported as 1 -and the highest as 0. - -@example -active-file = *active-line -active-line = name " " " " " " flags eol -name = -flags = "n" / "y" / "m" / "x" / "j" / "=" name -@end example - -The flag says whether the group is read-only (@samp{n}), is moderated -(@samp{m}), is dead (@samp{x}), is aliased to some other group -(@samp{=other-group}) or none of the above (@samp{y}). - - -@item (nnchoke-request-post &optional SERVER) - -This function should post the current buffer. It might return whether -the posting was successful or not, but that's not required. If, for -instance, the posting is done asynchronously, it has generally not been -completed by the time this function concludes. In that case, this -function should set up some kind of sentinel to beep the user loud and -clear if the posting could not be completed. - -There should be no result data from this function. - -@end table - - -@node Optional Back End Functions -@subsubsection Optional Back End Functions - -@table @code - -@item (nnchoke-retrieve-groups GROUPS &optional SERVER) - -@var{groups} is a list of groups, and this function should request data -on all those groups. How it does it is of no concern to Gnus, but it -should attempt to do this in a speedy fashion. - -The return value of this function can be either @code{active} or -@code{group}, which says what the format of the result data is. The -former is in the same format as the data from -@code{nnchoke-request-list}, while the latter is a buffer full of lines -in the same format as @code{nnchoke-request-group} gives. - -@example -group-buffer = *active-line / *group-status -@end example - - -@item (nnchoke-request-update-info GROUP INFO &optional SERVER) - -A Gnus group info (@pxref{Group Info}) is handed to the back end for -alterations. This comes in handy if the back end really carries all -the information (as is the case with virtual and imap groups). This -function should destructively alter the info to suit its needs, and -should return a non-@code{nil} value (exceptionally, -@code{nntp-request-update-info} always returns @code{nil} not to waste -the network resources). - -There should be no result data from this function. - - -@item (nnchoke-request-type GROUP &optional ARTICLE) - -When the user issues commands for ``sending news'' (@kbd{F} in the -summary buffer, for instance), Gnus has to know whether the article the -user is following up on is news or mail. This function should return -@code{news} if @var{article} in @var{group} is news, @code{mail} if it -is mail and @code{unknown} if the type can't be decided. (The -@var{article} parameter is necessary in @code{nnvirtual} groups which -might very well combine mail groups and news groups.) Both @var{group} -and @var{article} may be @code{nil}. - -There should be no result data from this function. - - -@item (nnchoke-request-set-mark GROUP ACTION &optional SERVER) - -Set/remove/add marks on articles. Normally Gnus handles the article -marks (such as read, ticked, expired etc.)@: internally, and store them in -@file{~/.newsrc.eld}. Some back ends (such as @acronym{IMAP}) however carry -all information about the articles on the server, so Gnus need to -propagate the mark information to the server. - -@var{action} is a list of mark setting requests, having this format: - -@example -(RANGE ACTION MARK) -@end example - -@var{range} is a range of articles you wish to update marks on. -@var{action} is @code{add} or @code{del}, used to add marks or remove -marks (preserving all marks not mentioned). @var{mark} is a list of -marks; where each mark is a symbol. Currently used marks are -@code{read}, @code{tick}, @code{reply}, @code{expire}, @code{killed}, -@code{dormant}, @code{save}, @code{download}, @code{unsend}, and -@code{forward}, but your back end should, if possible, not limit -itself to these. - -Given contradictory actions, the last action in the list should be the -effective one. That is, if your action contains a request to add the -@code{tick} mark on article 1 and, later in the list, a request to -remove the mark on the same article, the mark should in fact be removed. - -An example action list: - -@example -(((5 12 30) 'del '(tick)) - ((10 . 90) 'add '(read expire)) - ((92 94) 'del '(read))) -@end example - -The function should return a range of articles it wasn't able to set the -mark on (currently not used for anything). - -There should be no result data from this function. - -@item (nnchoke-request-update-mark GROUP ARTICLE MARK) - -If the user tries to set a mark that the back end doesn't like, this -function may change the mark. Gnus will use whatever this function -returns as the mark for @var{article} instead of the original -@var{mark}. If the back end doesn't care, it must return the original -@var{mark}, and not @code{nil} or any other type of garbage. - -The only use for this I can see is what @code{nnvirtual} does with -it---if a component group is auto-expirable, marking an article as read -in the virtual group should result in the article being marked as -expirable. - -There should be no result data from this function. - - -@item (nnchoke-request-scan &optional GROUP SERVER) - -This function may be called at any time (by Gnus or anything else) to -request that the back end check for incoming articles, in one way or -another. A mail back end will typically read the spool file or query -the @acronym{POP} server when this function is invoked. The -@var{group} doesn't have to be heeded---if the back end decides that -it is too much work just scanning for a single group, it may do a -total scan of all groups. It would be nice, however, to keep things -local if that's practical. - -There should be no result data from this function. - - -@item (nnchoke-request-group-description GROUP &optional SERVER) - -The result data from this function should be a description of -@var{group}. - -@example -description-line = name description eol -name = -description = -@end example - -@item (nnchoke-request-list-newsgroups &optional SERVER) - -The result data from this function should be the description of all -groups available on the server. - -@example -description-buffer = *description-line -@end example - - -@item (nnchoke-request-newgroups DATE &optional SERVER) - -The result data from this function should be all groups that were -created after @samp{date}, which is in normal human-readable date format -(i.e., the date format used in mail and news headers, and returned by -the function @code{message-make-date} by default). The data should be -in the active buffer format. - -It is okay for this function to return ``too many'' groups; some back ends -might find it cheaper to return the full list of groups, rather than -just the new groups. But don't do this for back ends with many groups. -Normally, if the user creates the groups herself, there won't be too -many groups, so @code{nnml} and the like are probably safe. But for -back ends like @code{nntp}, where the groups have been created by the -server, it is quite likely that there can be many groups. - - -@item (nnchoke-request-create-group GROUP &optional SERVER) - -This function should create an empty group with name @var{group}. - -There should be no return data. - - -@item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE) - -This function should run the expiry process on all articles in the -@var{articles} range (which is currently a simple list of article -numbers.) It is left up to the back end to decide how old articles -should be before they are removed by this function. If @var{force} is -non-@code{nil}, all @var{articles} should be deleted, no matter how new -they are. - -This function should return a list of articles that it did not/was not -able to delete. - -There should be no result data returned. - - -@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM &optional LAST) - -This function should move @var{article} (which is a number) from -@var{group} by calling @var{accept-form}. - -This function should ready the article in question for moving by -removing any header lines it has added to the article, and generally -should ``tidy up'' the article. Then it should @code{eval} -@var{accept-form} in the buffer where the ``tidy'' article is. This -will do the actual copying. If this @code{eval} returns a -non-@code{nil} value, the article should be removed. - -If @var{last} is @code{nil}, that means that there is a high likelihood -that there will be more requests issued shortly, so that allows some -optimizations. - -The function should return a cons where the @code{car} is the group name and -the @code{cdr} is the article number that the article was entered as. - -There should be no data returned. - - -@item (nnchoke-request-accept-article GROUP &optional SERVER LAST) - -This function takes the current buffer and inserts it into @var{group}. -If @var{last} in @code{nil}, that means that there will be more calls to -this function in short order. - -The function should return a cons where the @code{car} is the group name and -the @code{cdr} is the article number that the article was entered as. - -The group should exist before the back end is asked to accept the -article for that group. - -There should be no data returned. - - -@item (nnchoke-request-replace-article ARTICLE GROUP BUFFER) - -This function should remove @var{article} (which is a number) from -@var{group} and insert @var{buffer} there instead. - -There should be no data returned. - - -@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER) - -This function should delete @var{group}. If @var{force}, it should -really delete all the articles in the group, and then delete the group -itself. (If there is such a thing as ``the group itself''.) - -There should be no data returned. - - -@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER) - -This function should rename @var{group} into @var{new-name}. All -articles in @var{group} should move to @var{new-name}. - -There should be no data returned. - -@end table - - -@node Error Messaging -@subsubsection Error Messaging - -@findex nnheader-report -@findex nnheader-get-report -The back ends should use the function @code{nnheader-report} to report -error conditions---they should not raise errors when they aren't able to -perform a request. The first argument to this function is the back end -symbol, and the rest are interpreted as arguments to @code{format} if -there are multiple of them, or just a string if there is one of them. -This function must always returns @code{nil}. - -@lisp -(nnheader-report 'nnchoke "You did something totally bogus") - -(nnheader-report 'nnchoke "Could not request group %s" group) -@end lisp - -Gnus, in turn, will call @code{nnheader-get-report} when it gets a -@code{nil} back from a server, and this function returns the most -recently reported message for the back end in question. This function -takes one argument---the server symbol. - -Internally, these functions access @var{back-end}@code{-status-string}, -so the @code{nnchoke} back end will have its error message stored in -@code{nnchoke-status-string}. - - -@node Writing New Back Ends -@subsubsection Writing New Back Ends - -Many back ends are quite similar. @code{nnml} is just like -@code{nnspool}, but it allows you to edit the articles on the server. -@code{nnmh} is just like @code{nnml}, but it doesn't use an active file, -and it doesn't maintain overview databases. @code{nndir} is just like -@code{nnml}, but it has no concept of ``groups'', and it doesn't allow -editing articles. - -It would make sense if it were possible to ``inherit'' functions from -back ends when writing new back ends. And, indeed, you can do that if you -want to. (You don't have to if you don't want to, of course.) - -All the back ends declare their public variables and functions by using a -package called @code{nnoo}. - -To inherit functions from other back ends (and allow other back ends to -inherit functions from the current back end), you should use the -following macros: - -@table @code - -@item nnoo-declare -This macro declares the first parameter to be a child of the subsequent -parameters. For instance: - -@lisp -(nnoo-declare nndir - nnml nnmh) -@end lisp - -@code{nndir} has declared here that it intends to inherit functions from -both @code{nnml} and @code{nnmh}. - -@item defvoo -This macro is equivalent to @code{defvar}, but registers the variable as -a public server variable. Most state-oriented variables should be -declared with @code{defvoo} instead of @code{defvar}. - -In addition to the normal @code{defvar} parameters, it takes a list of -variables in the parent back ends to map the variable to when executing -a function in those back ends. - -@lisp -(defvoo nndir-directory nil - "Where nndir will look for groups." - nnml-current-directory nnmh-current-directory) -@end lisp - -This means that @code{nnml-current-directory} will be set to -@code{nndir-directory} when an @code{nnml} function is called on behalf -of @code{nndir}. (The same with @code{nnmh}.) - -@item nnoo-define-basics -This macro defines some common functions that almost all back ends should -have. - -@lisp -(nnoo-define-basics nndir) -@end lisp - -@item deffoo -This macro is just like @code{defun} and takes the same parameters. In -addition to doing the normal @code{defun} things, it registers the -function as being public so that other back ends can inherit it. - -@item nnoo-map-functions -This macro allows mapping of functions from the current back end to -functions from the parent back ends. - -@lisp -(nnoo-map-functions nndir - (nnml-retrieve-headers 0 nndir-current-group 0 0) - (nnmh-request-article 0 nndir-current-group 0 0)) -@end lisp - -This means that when @code{nndir-retrieve-headers} is called, the first, -third, and fourth parameters will be passed on to -@code{nnml-retrieve-headers}, while the second parameter is set to the -value of @code{nndir-current-group}. - -@item nnoo-import -This macro allows importing functions from back ends. It should be the -last thing in the source file, since it will only define functions that -haven't already been defined. - -@lisp -(nnoo-import nndir - (nnmh - nnmh-request-list - nnmh-request-newgroups) - (nnml)) -@end lisp - -This means that calls to @code{nndir-request-list} should just be passed -on to @code{nnmh-request-list}, while all public functions from -@code{nnml} that haven't been defined in @code{nndir} yet should be -defined now. - -@end table - -Below is a slightly shortened version of the @code{nndir} back end. - -@lisp -;;; @r{nndir.el --- single directory newsgroup access for Gnus} -;; @r{Copyright (C) 1995,1996 Free Software Foundation, Inc.} - -;;; @r{Code:} - -(require 'nnheader) -(require 'nnmh) -(require 'nnml) -(require 'nnoo) -(eval-when-compile (require 'cl)) - -(nnoo-declare nndir - nnml nnmh) - -(defvoo nndir-directory nil - "Where nndir will look for groups." - nnml-current-directory nnmh-current-directory) - -(defvoo nndir-nov-is-evil nil - "*Non-nil means that nndir will never retrieve NOV headers." - nnml-nov-is-evil) - -(defvoo nndir-current-group "" - nil - nnml-current-group nnmh-current-group) -(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory) -(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail) - -(defvoo nndir-status-string "" nil nnmh-status-string) -(defconst nndir-version "nndir 1.0") - -;;; @r{Interface functions.} - -(nnoo-define-basics nndir) - -(deffoo nndir-open-server (server &optional defs) - (setq nndir-directory - (or (cadr (assq 'nndir-directory defs)) - server)) - (unless (assq 'nndir-directory defs) - (push `(nndir-directory ,server) defs)) - (push `(nndir-current-group - ,(file-name-nondirectory - (directory-file-name nndir-directory))) - defs) - (push `(nndir-top-directory - ,(file-name-directory (directory-file-name nndir-directory))) - defs) - (nnoo-change-server 'nndir server defs)) - -(nnoo-map-functions nndir - (nnml-retrieve-headers 0 nndir-current-group 0 0) - (nnmh-request-article 0 nndir-current-group 0 0) - (nnmh-request-group nndir-current-group 0 0) - (nnmh-close-group nndir-current-group 0)) - -(nnoo-import nndir - (nnmh - nnmh-status-message - nnmh-request-list - nnmh-request-newgroups)) - -(provide 'nndir) -@end lisp - - -@node Hooking New Back Ends Into Gnus -@subsubsection Hooking New Back Ends Into Gnus - -@vindex gnus-valid-select-methods -@findex gnus-declare-backend -Having Gnus start using your new back end is rather easy---you just -declare it with the @code{gnus-declare-backend} functions. This will -enter the back end into the @code{gnus-valid-select-methods} variable. - -@code{gnus-declare-backend} takes two parameters---the back end name and -an arbitrary number of @dfn{abilities}. - -Here's an example: - -@lisp -(gnus-declare-backend "nnchoke" 'mail 'respool 'address) -@end lisp - -The above line would then go in the @file{nnchoke.el} file. - -The abilities can be: - -@table @code -@item mail -This is a mailish back end---followups should (probably) go via mail. -@item post -This is a newsish back end---followups should (probably) go via news. -@item post-mail -This back end supports both mail and news. -@item none -This is neither a post nor mail back end---it's something completely -different. -@item respool -It supports respooling---or rather, it is able to modify its source -articles and groups. -@item address -The name of the server should be in the virtual server name. This is -true for almost all back ends. -@item prompt-address -The user should be prompted for an address when doing commands like -@kbd{B} in the group buffer. This is true for back ends like -@code{nntp}, but not @code{nnmbox}, for instance. -@end table - - -@node Mail-like Back Ends -@subsubsection Mail-like Back Ends - -One of the things that separate the mail back ends from the rest of the -back ends is the heavy dependence by most of the mail back ends on -common functions in @file{nnmail.el}. For instance, here's the -definition of @code{nnml-request-scan}: - -@lisp -(deffoo nnml-request-scan (&optional group server) - (setq nnml-article-file-alist nil) - (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group)) -@end lisp - -It simply calls @code{nnmail-get-new-mail} with a few parameters, -and @code{nnmail} takes care of all the moving and splitting of the -mail. - -This function takes four parameters. - -@table @var -@item method -This should be a symbol to designate which back end is responsible for -the call. - -@item exit-function -This function should be called after the splitting has been performed. - -@item temp-directory -Where the temporary files should be stored. - -@item group -This optional argument should be a group name if the splitting is to be -performed for one group only. -@end table - -@code{nnmail-get-new-mail} will call @var{back-end}@code{-save-mail} to -save each article. @var{back-end}@code{-active-number} will be called to -find the article number assigned to this article. - -The function also uses the following variables: -@var{back-end}@code{-get-new-mail} (to see whether to get new mail for -this back end); and @var{back-end}@code{-group-alist} and -@var{back-end}@code{-active-file} to generate the new active file. -@var{back-end}@code{-group-alist} should be a group-active alist, like -this: - -@example -(("a-group" (1 . 10)) - ("some-group" (34 . 39))) -@end example - - -@node Score File Syntax -@subsection Score File Syntax - -Score files are meant to be easily parsable, but yet extremely -malleable. It was decided that something that had the same read syntax -as an Emacs Lisp list would fit that spec. - -Here's a typical score file: - -@lisp -(("summary" - ("Windows 95" -10000 nil s) - ("Gnus")) - ("from" - ("Lars" -1000)) - (mark -100)) -@end lisp - -BNF definition of a score file: - -@example -score-file = "" / "(" *element ")" -element = rule / atom -rule = string-rule / number-rule / date-rule -string-rule = "(" quote string-header quote space *string-match ")" -number-rule = "(" quote number-header quote space *number-match ")" -date-rule = "(" quote date-header quote space *date-match ")" -quote = -string-header = "subject" / "from" / "references" / "message-id" / - "xref" / "body" / "head" / "all" / "followup" -number-header = "lines" / "chars" -date-header = "date" -string-match = "(" quote quote [ "" / [ space score [ "" / - space date [ "" / [ space string-match-t ] ] ] ] ] ")" -score = "nil" / -date = "nil" / -string-match-t = "nil" / "s" / "substring" / "S" / "Substring" / - "r" / "regex" / "R" / "Regex" / - "e" / "exact" / "E" / "Exact" / - "f" / "fuzzy" / "F" / "Fuzzy" -number-match = "(" [ "" / [ space score [ "" / - space date [ "" / [ space number-match-t ] ] ] ] ] ")" -number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<=" -date-match = "(" quote quote [ "" / [ space score [ "" / - space date [ "" / [ space date-match-t ] ] ] ] ")" -date-match-t = "nil" / "at" / "before" / "after" -atom = "(" [ required-atom / optional-atom ] ")" -required-atom = mark / expunge / mark-and-expunge / files / - exclude-files / read-only / touched -optional-atom = adapt / local / eval -mark = "mark" space nil-or-number -nil-or-number = "nil" / -expunge = "expunge" space nil-or-number -mark-and-expunge = "mark-and-expunge" space nil-or-number -files = "files" *[ space ] -exclude-files = "exclude-files" *[ space ] -read-only = "read-only" [ space "nil" / space "t" ] -adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ] -adapt-rule = "(" *[ *[ "(" ")" ] ")" -local = "local" *[ space "(" space
")" ] -eval = "eval" space -space = *[ " " / / ] -@end example - -Any unrecognized elements in a score file should be ignored, but not -discarded. - -As you can see, white space is needed, but the type and amount of white -space is irrelevant. This means that formatting of the score file is -left up to the programmer---if it's simpler to just spew it all out on -one looong line, then that's ok. - -The meaning of the various atoms are explained elsewhere in this -manual (@pxref{Score File Format}). - - -@node Headers -@subsection Headers - -Internally Gnus uses a format for storing article headers that -corresponds to the @acronym{NOV} format in a mysterious fashion. One could -almost suspect that the author looked at the @acronym{NOV} specification and -just shamelessly @emph{stole} the entire thing, and one would be right. - -@dfn{Header} is a severely overloaded term. ``Header'' is used in -RFC 1036 to talk about lines in the head of an article (e.g., -@code{From}). It is used by many people as a synonym for -``head''---``the header and the body''. (That should be avoided, in my -opinion.) And Gnus uses a format internally that it calls ``header'', -which is what I'm talking about here. This is a 9-element vector, -basically, with each header (ouch) having one slot. - -These slots are, in order: @code{number}, @code{subject}, @code{from}, -@code{date}, @code{id}, @code{references}, @code{chars}, @code{lines}, -@code{xref}, and @code{extra}. There are macros for accessing and -setting these slots---they all have predictable names beginning with -@code{mail-header-} and @code{mail-header-set-}, respectively. - -All these slots contain strings, except the @code{extra} slot, which -contains an alist of header/value pairs (@pxref{To From Newsgroups}). - - -@node Ranges -@subsection Ranges - -@sc{gnus} introduced a concept that I found so useful that I've started -using it a lot and have elaborated on it greatly. - -The question is simple: If you have a large amount of objects that are -identified by numbers (say, articles, to take a @emph{wild} example) -that you want to qualify as being ``included'', a normal sequence isn't -very useful. (A 200,000 length sequence is a bit long-winded.) - -The solution is as simple as the question: You just collapse the -sequence. - -@example -(1 2 3 4 5 6 10 11 12) -@end example - -is transformed into - -@example -((1 . 6) (10 . 12)) -@end example - -To avoid having those nasty @samp{(13 . 13)} elements to denote a -lonesome object, a @samp{13} is a valid element: - -@example -((1 . 6) 7 (10 . 12)) -@end example - -This means that comparing two ranges to find out whether they are equal -is slightly tricky: - -@example -((1 . 5) 7 8 (10 . 12)) -@end example - -and - -@example -((1 . 5) (7 . 8) (10 . 12)) -@end example - -are equal. In fact, any non-descending list is a range: - -@example -(1 2 3 4 5) -@end example - -is a perfectly valid range, although a pretty long-winded one. This is -also valid: - -@example -(1 . 5) -@end example - -and is equal to the previous range. - -Here's a BNF definition of ranges. Of course, one must remember the -semantic requirement that the numbers are non-descending. (Any number -of repetition of the same number is allowed, but apt to disappear in -range handling.) - -@example -range = simple-range / normal-range -simple-range = "(" number " . " number ")" -normal-range = "(" start-contents ")" -contents = "" / simple-range *[ " " contents ] / - number *[ " " contents ] -@end example - -Gnus currently uses ranges to keep track of read articles and article -marks. I plan on implementing a number of range operators in C if The -Powers That Be are willing to let me. (I haven't asked yet, because I -need to do some more thinking on what operators I need to make life -totally range-based without ever having to convert back to normal -sequences.) - - -@node Group Info -@subsection Group Info - -Gnus stores all permanent info on groups in a @dfn{group info} list. -This list is from three to six elements (or more) long and exhaustively -describes the group. - -Here are two example group infos; one is a very simple group while the -second is a more complex one: - -@example -("no.group" 5 ((1 . 54324))) - -("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55)) - ((tick (15 . 19)) (replied 3 6 (19 . 3))) - (nnml "") - ((auto-expire . t) (to-address . "ding@@gnus.org"))) -@end example - -The first element is the @dfn{group name}---as Gnus knows the group, -anyway. The second element is the @dfn{subscription level}, which -normally is a small integer. (It can also be the @dfn{rank}, which is a -cons cell where the @code{car} is the level and the @code{cdr} is the -score.) The third element is a list of ranges of read articles. The -fourth element is a list of lists of article marks of various kinds. -The fifth element is the select method (or virtual server, if you like). -The sixth element is a list of @dfn{group parameters}, which is what -this section is about. - -Any of the last three elements may be missing if they are not required. -In fact, the vast majority of groups will normally only have the first -three elements, which saves quite a lot of cons cells. - -Here's a BNF definition of the group info format: - -@example -info = "(" group space ralevel space read - [ "" / [ space marks-list [ "" / [ space method [ "" / - space parameters ] ] ] ] ] ")" -group = quote quote -ralevel = rank / level -level = -rank = "(" level "." score ")" -score = -read = range -marks-lists = nil / "(" *marks ")" -marks = "(" range ")" -method = "(" *elisp-forms ")" -parameters = "(" *elisp-forms ")" -@end example - -Actually that @samp{marks} rule is a fib. A @samp{marks} is a -@samp{} consed on to a @samp{range}, but that's a bitch to say -in pseudo-BNF. - -If you have a Gnus info and want to access the elements, Gnus offers a -series of macros for getting/setting these elements. - -@table @code -@item gnus-info-group -@itemx gnus-info-set-group -@findex gnus-info-group -@findex gnus-info-set-group -Get/set the group name. - -@item gnus-info-rank -@itemx gnus-info-set-rank -@findex gnus-info-rank -@findex gnus-info-set-rank -Get/set the group rank (@pxref{Group Score}). - -@item gnus-info-level -@itemx gnus-info-set-level -@findex gnus-info-level -@findex gnus-info-set-level -Get/set the group level. - -@item gnus-info-score -@itemx gnus-info-set-score -@findex gnus-info-score -@findex gnus-info-set-score -Get/set the group score (@pxref{Group Score}). - -@item gnus-info-read -@itemx gnus-info-set-read -@findex gnus-info-read -@findex gnus-info-set-read -Get/set the ranges of read articles. - -@item gnus-info-marks -@itemx gnus-info-set-marks -@findex gnus-info-marks -@findex gnus-info-set-marks -Get/set the lists of ranges of marked articles. - -@item gnus-info-method -@itemx gnus-info-set-method -@findex gnus-info-method -@findex gnus-info-set-method -Get/set the group select method. - -@item gnus-info-params -@itemx gnus-info-set-params -@findex gnus-info-params -@findex gnus-info-set-params -Get/set the group parameters. -@end table - -All the getter functions take one parameter---the info list. The setter -functions take two parameters---the info list and the new value. - -The last three elements in the group info aren't mandatory, so it may be -necessary to extend the group info before setting the element. If this -is necessary, you can just pass on a non-@code{nil} third parameter to -the three final setter functions to have this happen automatically. - - -@node Extended Interactive -@subsection Extended Interactive -@cindex interactive -@findex gnus-interactive - -Gnus extends the standard Emacs @code{interactive} specification -slightly to allow easy use of the symbolic prefix (@pxref{Symbolic -Prefixes}). Here's an example of how this is used: - -@lisp -(defun gnus-summary-increase-score (&optional score symp) - (interactive (gnus-interactive "P\ny")) - ... - ) -@end lisp - -The best thing to do would have been to implement -@code{gnus-interactive} as a macro which would have returned an -@code{interactive} form, but this isn't possible since Emacs checks -whether a function is interactive or not by simply doing an @code{assq} -on the lambda form. So, instead we have @code{gnus-interactive} -function that takes a string and returns values that are usable to -@code{interactive}. - -This function accepts (almost) all normal @code{interactive} specs, but -adds a few more. - -@table @samp -@item y -@vindex gnus-current-prefix-symbol -The current symbolic prefix---the @code{gnus-current-prefix-symbol} -variable. - -@item Y -@vindex gnus-current-prefix-symbols -A list of the current symbolic prefixes---the -@code{gnus-current-prefix-symbol} variable. - -@item A -The current article number---the @code{gnus-summary-article-number} -function. - -@item H -The current article header---the @code{gnus-summary-article-header} -function. - -@item g -The current group name---the @code{gnus-group-group-name} -function. - -@end table - - -@node Emacs/XEmacs Code -@subsection Emacs/XEmacs Code -@cindex XEmacs -@cindex Emacsen - -While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the -platforms must be the primary one. I chose Emacs. Not because I don't -like XEmacs or Mule, but because it comes first alphabetically. - -This means that Gnus will byte-compile under Emacs with nary a warning, -while XEmacs will pump out gigabytes of warnings while byte-compiling. -As I use byte-compilation warnings to help me root out trivial errors in -Gnus, that's very useful. - -I've also consistently used Emacs function interfaces, but have used -Gnusey aliases for the functions. To take an example: Emacs defines a -@code{run-at-time} function while XEmacs defines a @code{start-itimer} -function. I then define a function called @code{gnus-run-at-time} that -takes the same parameters as the Emacs @code{run-at-time}. When running -Gnus under Emacs, the former function is just an alias for the latter. -However, when running under XEmacs, the former is an alias for the -following function: - -@lisp -(defun gnus-xmas-run-at-time (time repeat function &rest args) - (start-itimer - "gnus-run-at-time" - `(lambda () - (,function ,@@args)) - time repeat)) -@end lisp - -This sort of thing has been done for bunches of functions. Gnus does -not redefine any native Emacs functions while running under XEmacs---it -does this @code{defalias} thing with Gnus equivalents instead. Cleaner -all over. - -In the cases where the XEmacs function interface was obviously cleaner, -I used it instead. For example @code{gnus-region-active-p} is an alias -for @code{region-active-p} in XEmacs, whereas in Emacs it is a function. - -Of course, I could have chosen XEmacs as my native platform and done -mapping functions the other way around. But I didn't. The performance -hit these indirections impose on Gnus under XEmacs should be slight. - - -@node Various File Formats -@subsection Various File Formats - -@menu -* Active File Format:: Information on articles and groups available. -* Newsgroups File Format:: Group descriptions. -@end menu - - -@node Active File Format -@subsubsection Active File Format - -The active file lists all groups available on the server in -question. It also lists the highest and lowest current article numbers -in each group. - -Here's an excerpt from a typical active file: - -@example -soc.motss 296030 293865 y -alt.binaries.pictures.fractals 3922 3913 n -comp.sources.unix 1605 1593 m -comp.binaries.ibm.pc 5097 5089 y -no.general 1000 900 y -@end example - -Here's a pseudo-BNF definition of this file: - -@example -active = *group-line -group-line = group spc high-number spc low-number spc flag -group = -spc = " " -high-number = -low-number = -flag = "y" / "n" / "m" / "j" / "x" / "=" group -@end example - -For a full description of this file, see the manual pages for -@samp{innd}, in particular @samp{active(5)}. - - -@node Newsgroups File Format -@subsubsection Newsgroups File Format - -The newsgroups file lists groups along with their descriptions. Not all -groups on the server have to be listed, and not all groups in the file -have to exist on the server. The file is meant purely as information to -the user. - -The format is quite simple; a group name, a tab, and the description. -Here's the definition: - -@example -newsgroups = *line -line = group tab description -group = -tab = -description = -@end example - - -@page -@node Emacs for Heathens -@section Emacs for Heathens - -Believe it or not, but some people who use Gnus haven't really used -Emacs much before they embarked on their journey on the Gnus Love Boat. -If you are one of those unfortunates whom ``@kbd{C-M-a}'', ``kill the -region'', and ``set @code{gnus-flargblossen} to an alist where the key -is a regexp that is used for matching on the group name'' are magical -phrases with little or no meaning, then this appendix is for you. If -you are already familiar with Emacs, just ignore this and go fondle your -cat instead. - -@menu -* Keystrokes:: Entering text and executing commands. -* Emacs Lisp:: The built-in Emacs programming language. -@end menu - - -@node Keystrokes -@subsection Keystrokes - -@itemize @bullet -@item -Q: What is an experienced Emacs user? - -@item -A: A person who wishes that the terminal had pedals. -@end itemize - -Yes, when you use Emacs, you are apt to use the control key, the shift -key and the meta key a lot. This is very annoying to some people -(notably @code{vi}le users), and the rest of us just love the hell out -of it. Just give up and submit. Emacs really does stand for -``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you -may have heard from other disreputable sources (like the Emacs author). - -The shift keys are normally located near your pinky fingers, and are -normally used to get capital letters and stuff. You probably use it all -the time. The control key is normally marked ``CTRL'' or something like -that. The meta key is, funnily enough, never marked as such on any -keyboard. The one I'm currently at has a key that's marked ``Alt'', -which is the meta key on this keyboard. It's usually located somewhere -to the left hand side of the keyboard, usually on the bottom row. - -Now, us Emacs people don't say ``press the meta-control-m key'', -because that's just too inconvenient. We say ``press the @kbd{C-M-m} -key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the -prefix that means ``control''. So ``press @kbd{C-k}'' means ``press -down the control key, and hold it down while you press @kbd{k}''. -``Press @kbd{C-M-k}'' means ``press down and hold down the meta key and -the control key and then press @kbd{k}''. Simple, ay? - -This is somewhat complicated by the fact that not all keyboards have a -meta key. In that case you can use the ``escape'' key. Then @kbd{M-k} -means ``press escape, release escape, press @kbd{k}''. That's much more -work than if you have a meta key, so if that's the case, I respectfully -suggest you get a real keyboard with a meta key. You can't live without -it. - - - -@node Emacs Lisp -@subsection Emacs Lisp - -Emacs is the King of Editors because it's really a Lisp interpreter. -Each and every key you tap runs some Emacs Lisp code snippet, and since -Emacs Lisp is an interpreted language, that means that you can configure -any key to run any arbitrary code. You just, like, do it. - -Gnus is written in Emacs Lisp, and is run as a bunch of interpreted -functions. (These are byte-compiled for speed, but it's still -interpreted.) If you decide that you don't like the way Gnus does -certain things, it's trivial to have it do something a different way. -(Well, at least if you know how to write Lisp code.) However, that's -beyond the scope of this manual, so we are simply going to talk about -some common constructs that you normally use in your @file{~/.gnus.el} -file to customize Gnus. (You can also use the @file{~/.emacs} file, but -in order to set things of Gnus up, it is much better to use the -@file{~/.gnus.el} file, @xref{Startup Files}.) - -If you want to set the variable @code{gnus-florgbnize} to four (4), you -write the following: - -@lisp -(setq gnus-florgbnize 4) -@end lisp - -This function (really ``special form'') @code{setq} is the one that can -set a variable to some value. This is really all you need to know. Now -you can go and fill your @file{~/.gnus.el} file with lots of these to -change how Gnus works. - -If you have put that thing in your @file{~/.gnus.el} file, it will be -read and @code{eval}ed (which is Lisp-ese for ``run'') the next time you -start Gnus. If you want to change the variable right away, simply say -@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the -previous ``form'', which is a simple @code{setq} statement here. - -Go ahead---just try it, if you're located at your Emacs. After you -@kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which -is the return value of the form you @code{eval}ed. - -Some pitfalls: - -If the manual says ``set @code{gnus-read-active-file} to @code{some}'', -that means: - -@lisp -(setq gnus-read-active-file 'some) -@end lisp - -On the other hand, if the manual says ``set @code{gnus-nntp-server-file} to -@samp{/etc/nntpserver}'', that means: - -@lisp -(setq gnus-nntp-server-file "/etc/nntpserver") -@end lisp - -So be careful not to mix up strings (the latter) with symbols (the -former). The manual is unambiguous, but it can be confusing. - -@page -@include gnus-faq.texi - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index -@printindex cp - -@node Key Index -@chapter Key Index -@printindex ky - -@bye - -@iftex -@iflatex -\end{document} -@end iflatex -@end iftex - -@c Local Variables: -@c mode: texinfo -@c coding: utf-8 -@c End: diff --git a/doc/misc/gpl.texi b/doc/misc/gpl.texi deleted file mode 100644 index 0e2e212acb1..00000000000 --- a/doc/misc/gpl.texi +++ /dev/null @@ -1,717 +0,0 @@ -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW@. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE@. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. diff --git a/doc/misc/htmlfontify.texi b/doc/misc/htmlfontify.texi deleted file mode 100644 index d31a087be2a..00000000000 --- a/doc/misc/htmlfontify.texi +++ /dev/null @@ -1,1595 +0,0 @@ -\input texinfo -@comment %**start of header -@setfilename ../../info/htmlfontify -@settitle Htmlfontify User Manual -@exampleindent 2 -@documentencoding UTF-8 -@comment %**end of header - -@copying -This manual documents Htmlfontify, a source code -> crosslinked + -formatted + syntax colorized html transformer. - -Copyright @copyright{} 2002-2003, 2013-2014 Free Software Foundation, -Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Htmlfontify: (htmlfontify). Convert source code to html. -@end direntry - -@titlepage -@title Htmlfontify User Manual -@sp 4 -@subtitle Htmlfontify version 0.20 -@sp 1 -@subtitle Jun 2002 -@sp 5 -@author Vivek Dasmohapatra -@page - -@vskip 0pt plus 1filll -@noindent -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Htmlfontify - -@insertcopying -@end ifnottex - -@menu -* Introduction:: About Htmlfontify. -* Usage & Examples:: How to use Htmlfontify. -* Customization:: Fine-tuning Htmlfontify's behavior. -* Requirements:: External programs used by Htmlfontify. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Index of contents. -@end menu - -@node Introduction -@chapter Introduction -@cindex Introduction - -Htmlfontify provides a means of converting individual Emacs buffers, -source files, or entire source trees to html, preserving formatting -and Emacs colorization / syntax highlighting as much as possible -through careful application of CSS stylesheets and html tags. - -It can also turn instances of functions, methods and (for some -languages) variables and other constructs and items into links -to their definitions, and create an index file (or files) of -all such symbols, also linked to their points of definition. - -Htmlfontify also provides several customization items, which should -allow it to mesh more-or-less seamlessly with various templating or -publishing systems (in the event, for instance, that you don't want -to produce the html pages directly). - -@node Usage & Examples -@chapter Usage & Examples -@cindex Usage & Examples - -Htmlfontify can be used both interactively and as part of another -elisp function. If you're running it in a modern Emacs, it will also -run when attached to a terminal (i.e., without X) or even when in -batch mode. - -@menu -* Interactive:: Using Htmlfontify interactively. -* Non-interactive:: Using Htmlfontify from elisp. -* Variables:: Variables (other than customization entries). -* Data Structures:: Important data structures. -* Examples:: Example(s) of Htmlfontify in use. -@end menu - -@node Interactive -@section Interactive -@cindex Interactive -@cindex functions (interactive) - -Htmlfontify provides the following interactive functions: - -@table @code -@item htmlfontify-buffer -@findex htmlfontify-buffer -@anchor{htmlfontify-buffer} - -@lisp - -(htmlfontify-buffer &optional @var{srcdir} @var{file}) -@end lisp - -Create a new buffer, named for the current buffer + a .html extension, -containing an inline CSS-stylesheet and formatted CSS-markup html that -reproduces the look of the current Emacs buffer as closely as possible. - -``Dangerous'' characters in the existing buffer are turned into html -entities, so you should even be able to do html-within-html fontified -display. - -You should, however, note that random control or non-ASCII characters -such as ^L (\x0c) or ¤ (\xa4) won't get mapped yet. - -If the @var{srcdir} and @var{file} arguments are set, lookup etags -derived entries in the @ref{hfy-tags-cache} and add html anchors -and hyperlinks as appropriate. - -@item htmlfontify-run-etags -@findex htmlfontify-run-etags -@anchor{htmlfontify-run-etags} - -@lisp - -(htmlfontify-run-etags @var{srcdir}) -@end lisp - -Load the etags cache for @var{srcdir}. See @ref{hfy-load-tags-cache}. - -@item htmlfontify-copy-and-link-dir -@findex htmlfontify-copy-and-link-dir -@anchor{htmlfontify-copy-and-link-dir} - -@lisp - -(htmlfontify-copy-and-link-dir @var{srcdir} @var{dstdir} &optional @var{f-ext} @var{l-ext}) -@end lisp - -Trawl @var{srcdir} and write fontified-and-hyperlinked output in -@var{dstdir}. @var{f-ext} and @var{l-ext} specify values for -@ref{hfy-extn} and @ref{hfy-link-extn}. - -You may also want to set @ref{hfy-page-header} and @ref{hfy-page-footer}. - -@item htmlfontify-load-rgb-file -@findex htmlfontify-load-rgb-file -@anchor{htmlfontify-load-rgb-file} - -@lisp - -(htmlfontify-load-rgb-file &optional @var{file}) -@end lisp - -Load an X11 style rgb.txt file (search @code{hfy-rgb-load-path} if -@var{file} is not specified). - -Note that this is not necessary if all you want is the standard X11 -(XFree86 4.1.0) color name -> rgb triplet mapping. Htmlfontify has -a copy built in, for use when it cannot contact an X server. - -Loads the variable @code{hfy-rgb-txt-color-map}, which is used by -@ref{hfy-fallback-color-values}. - -@item htmlfontify-unload-rgb-file -@findex htmlfontify-unload-rgb-file -@anchor{htmlfontify-unload-rgb-file} - -@lisp - -(htmlfontify-unload-rgb-file) -@end lisp - -Unload the currently loaded X11 style rgb.txt file (if any). -@end table - -@node Non-interactive -@section Non-interactive -@cindex Noninteractive -@cindex functions (noninteractive) - -In addition to the aforementioned interactive methods, Htmlfontify -provides the following non-interactive ones: - -@table @code -@comment AUTOGENERATED BLOCK - -@item hfy-face-to-style -@findex hfy-face-to-style -@anchor{hfy-face-to-style} - -@lisp - -(hfy-face-to-style @var{fn}) -@end lisp - -Take @var{fn}, a font or @code{defface} style font specification, -(as returned by @code{face-attr-construct} or @ref{hfy-face-attr-for-class}) -and return a @ref{hfy-style-assoc}. - -See also: @ref{hfy-face-to-style-i}, @ref{hfy-flatten-style}. - -@item hfy-fallback-color-values -@findex hfy-fallback-color-values -@anchor{hfy-fallback-color-values} - -@lisp - -(hfy-fallback-color-values @var{color-string}) -@end lisp - -Use a fallback method for obtaining the rgb values for a color. -If @ref{htmlfontify-load-rgb-file} has been called, it uses the -color map specified, otherwise it uses Htmlfontify's built in map. - -@item hfy-combined-face-spec -@findex hfy-combined-face-spec -@anchor{hfy-combined-face-spec} - -@lisp - -(hfy-combined-face-spec @var{face}) -@end lisp - -Return a @code{defface} style alist of possible specifications for -@var{face}, with any entries resulting from user customization -(@code{custom-set-faces}) taking precedence. - -See also: @ref{hfy-default-face-def} - -@item hfy-word-regex -@findex hfy-word-regex -@anchor{hfy-word-regex} - -@lisp - -(hfy-word-regex @var{string}) -@end lisp - -Return a regex that matches @var{string} as the first @code{match-string}, -with non word characters on either side (vaguely emulating the perl @code{\b} -regex atom). - -@item hfy-force-fontification -@findex hfy-force-fontification -@anchor{hfy-force-fontification} - -@lisp - -(hfy-force-fontification) -@end lisp - -Emacs's fontification is designed for interactive use. As such, it sometimes -does things like deferring fontification until a section of the buffer is -exposed and rendered, or until Emacs is idle for a while. Sometimes, in -non-interactive circumstances, or if it can't see X, it doesn't bother -with some of the harder stuff. While this is all great from the perspective -of a user waiting for Emacs to load a 20000 line file and colorize it, -it's a pain from the point of view from non-interactive code. This function -lies, cheats, steals and generally bullies Emacs into fontifying a buffer -from start to finish, with all the extra frills, whether it thinks it needs -to or not. Oh yes: it operates on the current buffer. - -@item hfy-link-style-string -@findex hfy-link-style-string -@anchor{hfy-link-style-string} - -@lisp - -(hfy-link-style-string @var{style-string}) -@end lisp - -Replace the end of a CSS style declaration @var{style-string} with the contents -of the variable @ref{hfy-src-doc-link-style}, removing text matching the -regex @ref{hfy-src-doc-link-unstyle} first, if necessary. - - -@item hfy-prepare-index-i -@findex hfy-prepare-index-i -@anchor{hfy-prepare-index-i} - -@lisp - -(hfy-prepare-index-i @var{srcdir} @var{dstdir} @var{filename} &optional @var{stub} @var{map}) -@end lisp - -Prepare a tags index buffer for @var{srcdir}. -@ref{hfy-tags-cache} must already have an entry for @var{srcdir} for -this to work. @ref{hfy-page-header}, @ref{hfy-page-footer}, -@ref{hfy-link-extn} and @ref{hfy-extn} all play a part here. - -If @var{stub} is set, prepare an (appropriately named) index buffer -specifically for entries beginning with @var{stub}. - -If @var{map} is set, use that instead of @ref{hfy-tags-cache}. - -@item hfy-compile-stylesheet -@findex hfy-compile-stylesheet -@anchor{hfy-compile-stylesheet} - -@lisp - -(hfy-compile-stylesheet) -@end lisp - -Trawl the current buffer, construct and return a @ref{hfy-sheet-assoc}. - -@item hfy-css-name -@findex hfy-css-name -@anchor{hfy-css-name} - -@lisp - -(hfy-css-name @var{fn}) -@end lisp - -Strip some of the boring bits from a font-name and return a CSS style -name. If @var{fn} is a @code{defface} attribute list, either construct -a name for it, store it in the cache, and return it, or just fetch it -from the cache if it's already there. - -@item hfy-make-directory -@findex hfy-make-directory -@anchor{hfy-make-directory} - -@lisp - -(hfy-make-directory @var{dir}) -@end lisp - -Approximate equivalent of @code{mkdir -p @var{dir}}. - -@item hfy-triplet -@findex hfy-triplet -@anchor{hfy-triplet} - -@lisp - -(hfy-triplet @var{color}) -@end lisp - -Takes a color name (string) and return a CSS rgb(R, G, B) triplet string. -Uses the definition of ``white'' to map the numbers to the 0-255 range, so -if you've redefined white, (especially if you've redefined it to have -a triplet member lower than that of the color you are processing, -strange things may happen). - -@item hfy-default-footer -@findex hfy-default-footer -@anchor{hfy-default-footer} - -@lisp - -(hfy-default-footer @var{file}) -@end lisp - -Default value for @ref{hfy-page-footer} - -@item hfy-list-files -@findex hfy-list-files -@anchor{hfy-list-files} - -@lisp - -(hfy-list-files @var{directory}) -@end lisp - -Return a list of files under @var{directory}. -Strips any leading @samp{./} from each filename. - -@item hfy-color-vals -@findex hfy-color-vals -@anchor{hfy-color-vals} - -@lisp - -(hfy-color-vals @var{color}) -@end lisp - -Where @var{color} is a color name or #XXXXXX style triplet, return a list of -3 (16 bit) rgb values for said color. If a window system is unavailable, -calls @ref{hfy-fallback-color-values}. - -@item hfy-href-stub -@findex hfy-href-stub -@anchor{hfy-href-stub} - -@lisp - -(hfy-href-stub @var{this-file} @var{def-files} @var{tag}) -@end lisp - -Return an href stub for a tag href: if @var{def-files} (list of files -containing definitions for the tag in question) contains only one entry, -the href should link straight to that file. Otherwise, the link should -be to the index file. - -We are not yet concerned with the file extensions/tag line number and -so on at this point. - -If @ref{hfy-split-index} is set, and the href will be to an index file -rather than a source file, append a @samp{.X} to @ref{hfy-index-file}, where -@samp{X} is the uppercased first character of @var{tag}. - -See also: @ref{hfy-relstub}, @ref{hfy-index-file}. - -@item hfy-line-number -@findex hfy-line-number -@anchor{hfy-line-number} - -@lisp - -(hfy-line-number) -@end lisp - -Returns the line number of the point in the current buffer. - -@item hfy-merge-adjacent-spans -@findex hfy-merge-adjacent-spans -@anchor{hfy-merge-adjacent-spans} - -@lisp - -(hfy-merge-adjacent-spans @var{face-map}) -@end lisp - -Where @var{face-map} is a @ref{hfy-facemap-assoc} for the current buffer, -this function merges adjacent style blocks which are of the same value -and are separated by nothing more interesting than whitespace. - -@code{narf brain} - -(as interpreted from @var{face-map}) would become: - -@code{narf brain} - -Returns a modified copy of @var{face-map} (also a @ref{hfy-facemap-assoc}). - -@item hfy-mark-tag-names -@findex hfy-mark-tag-names -@anchor{hfy-mark-tag-names} - -@lisp - -(hfy-mark-tag-names @var{srcdir} @var{file}) -@end lisp - -Mark tags in @var{file} (lookup @var{srcdir} in @ref{hfy-tags-cache}) with the -@code{hfy-anchor} property, with a value of @samp{tag.line-number}. - -@item hfy-weight -@findex hfy-weight -@anchor{hfy-weight} - -@lisp - -(hfy-weight @var{weight}) -@end lisp - -Derive a font-weight CSS specifier from an Emacs weight specification symbol. - -@item hfy-size -@findex hfy-size -@anchor{hfy-size} - -@lisp - -(hfy-size @var{height}) -@end lisp - -Derive a CSS font-size specifier from an Emacs font @code{:height} attribute. -Does not cope with the case where height is a function to be applied to -the height of the underlying font. - -@item hfy-default-header -@findex hfy-default-header -@anchor{hfy-default-header} - -@lisp - -(hfy-default-header @var{file} @var{style}) -@end lisp - -Default value for @ref{hfy-page-header} - -@item hfy-family -@findex hfy-family -@anchor{hfy-family} - -@lisp - -(hfy-family @var{family}) -@end lisp - -Derives a CSS font-family specifier from an Emacs @code{:family} attribute. - -@item hfy-mark-tag-hrefs -@findex hfy-mark-tag-hrefs -@anchor{hfy-mark-tag-hrefs} - -@lisp - -(hfy-mark-tag-hrefs @var{srcdir} @var{file}) -@end lisp - -Mark href start points with the @code{hfy-link} property (value: href string). - -Mark href end points with the @code{hfy-endl} property (value @code{t}). - -Avoid overlapping links, and mark links in descending length of -tag name in order to prevent subtags from usurping supertags; -e.g., ``term'' for ``terminal''). - -@item hfy-box -@findex hfy-box -@anchor{hfy-box} - -@lisp - -(hfy-box @var{box}) -@end lisp - -Derive CSS border-* attributes from the Emacs @code{:box} attribute. - -@item hfy-box-to-style -@findex hfy-box-to-style -@anchor{hfy-box-to-style} - -@lisp - -(hfy-box-to-style @var{spec}) -@end lisp - -Convert a complex @code{:box} Emacs font attribute set to a list of -CSS border-* attributes. Don't call this directly---it is called by -@ref{hfy-box} when necessary. - -@item hfy-html-enkludge-buffer -@findex hfy-html-enkludge-buffer -@anchor{hfy-html-enkludge-buffer} - -@lisp - -(hfy-html-enkludge-buffer) -@end lisp - -Mark dangerous @samp{["<>]} characters with the @code{hfy-quoteme} property. - -See also @ref{hfy-html-dekludge-buffer}. - -@item hfy-buffer -@findex hfy-buffer -@anchor{hfy-buffer} - -@lisp - -(hfy-buffer) -@end lisp - -Generate and return an Htmlfontify html output buffer for the current -buffer. May trample an existing buffer. - -@item hfy-fontified-p -@findex hfy-fontified-p -@anchor{hfy-fontified-p} - -@lisp - -(hfy-fontified-p) -@end lisp - -@code{font-lock} doesn't like to say a buffer's been fontified when in -batch mode, but we want to know if we should fontify or raw copy, so in -batch mode we check for non-default face properties. Otherwise we test -@code{font-lock-mode} and @code{font-lock-fontified} for truth. - -@item hfy-lookup -@findex hfy-lookup -@anchor{hfy-lookup} - -@lisp - -(hfy-lookup @var{face} @var{style}) -@end lisp - -Where @var{style} is a @ref{hfy-sheet-assoc} and @var{face} is an Emacs face, -return the relevant @var{css} style name. - -@item hfy-fontify-buffer -@findex hfy-fontify-buffer -@anchor{hfy-fontify-buffer} - -@lisp - -(hfy-fontify-buffer &optional @var{srcdir} @var{file}) -@end lisp - -Implement the guts of @ref{htmlfontify-buffer}. - -@item hfy-color -@findex hfy-color -@anchor{hfy-color} - -@lisp - -(hfy-color @var{color}) -@end lisp - -Convert an Emacs :foreground property to a CSS color property. - -@item hfy-flatten-style -@findex hfy-flatten-style -@anchor{hfy-flatten-style} - -@lisp - -(hfy-flatten-style @var{style}) -@end lisp - -Take @var{style} (see @ref{hfy-face-to-style-i}, @ref{hfy-face-to-style}) -and merge any multiple attributes appropriately. Currently only font-size is -merged down to a single occurrence---others may need special handling, but I -haven't encountered them yet. Returns a @ref{hfy-style-assoc}. - -@item hfy-size-to-int -@findex hfy-size-to-int -@anchor{hfy-size-to-int} - -@lisp - -(hfy-size-to-int @var{spec}) -@end lisp - -Convert @var{spec}, a CSS font-size specifier, back to an Emacs -@code{:height} attribute value. Used while merging multiple font-size -attributes. - -@item hfy-sprintf-stylesheet -@findex hfy-sprintf-stylesheet -@anchor{hfy-sprintf-stylesheet} - -@lisp - -(hfy-sprintf-stylesheet @var{css} @var{file}) -@end lisp - -Generates a header, via @ref{hfy-page-header}, for @var{file}, containing the -stylesheet derived from @var{css}, which is a @ref{hfy-sheet-assoc}. Returns a -string containing the same. - -@item hfy-relstub -@findex hfy-relstub -@anchor{hfy-relstub} - -@lisp - -(hfy-relstub @var{file} &optional @var{start}) -@end lisp - -Return a @samp{../} stub of the appropriate length for the current source -tree depth (as determined from @var{file}). @c iyswim. - -@item hfy-compile-face-map -@findex hfy-compile-face-map -@anchor{hfy-compile-face-map} - -@lisp - -(hfy-compile-face-map) -@end lisp - -Compile and return a @ref{hfy-facemap-assoc} for the current buffer. - -@item hfy-prepare-index -@findex hfy-prepare-index -@anchor{hfy-prepare-index} - -@lisp - -(hfy-prepare-index @var{srcdir} @var{dstdir}) -@end lisp - -Return as list of index buffer(s), as determined by @ref{hfy-split-index}. -Uses @ref{hfy-prepare-index-i} to do this. - -@item hfy-prepare-tag-map -@findex hfy-prepare-tag-map -@anchor{hfy-prepare-tag-map} - -@lisp - -(hfy-prepare-tag-map @var{srcdir} @var{dstdir}) -@end lisp - -Prepare the counterpart(s) to the index buffer(s)---a list of buffers with -the same structure, but listing (and linking to) instances of tags (as -opposed to their definitions). - -See also: @ref{hfy-prepare-index}, @ref{hfy-split-index} - -@item hfy-subtract-maps -@findex hfy-subtract-maps -@anchor{hfy-subtract-maps} - -@lisp - -(hfy-subtract-maps @var{srcdir}) -@end lisp - -Internal function---strips definitions of tags from the instance map. -See: @ref{hfy-tags-cache} and @ref{hfy-tags-rmap} - -@item hfy-face-to-style-i -@findex hfy-face-to-style-i -@anchor{hfy-face-to-style-i} - -@lisp - -(hfy-face-to-style-i @var{fn}) -@end lisp - -The guts of @ref{hfy-face-to-style}. @var{fn} should be a @code{defface} -font specification, as returned by @code{face-attr-construct} or -@ref{hfy-face-attr-for-class}. Note that this function does not get -font-sizes right if they are based on inherited modifiers (via the -:inherit) attribute, and any other modifiers that are cumulative if they -appear multiple times need to be merged by the user---@ref{hfy-flatten-style} -should do this. - -@item hfy-face-to-css -@findex hfy-face-to-css -@anchor{hfy-face-to-css} - -@lisp - -(hfy-face-to-css @var{fn}) -@end lisp - -Take @var{fn}, a font or @code{defface} specification (c.f. -@code{face-attr-construct}) and return a CSS style specification. - -See also: @ref{hfy-face-to-style} - -@item hfy-html-quote -@findex hfy-html-quote -@anchor{hfy-html-quote} - -@lisp - -(hfy-html-quote @var{char-string}) -@end lisp - -Map a string (usually 1 character long) to an html safe string -(entity) if need be. - -@item hfy-link-style -@findex hfy-link-style -@anchor{hfy-link-style} - -@lisp - -(hfy-link-style @var{style-string}) -@end lisp - -Convert the CSS style spec @var{style-string} to its equivalent -hyperlink style. - -See: @ref{hfy-link-style-fun}. - -@item hfy-p-to-face -@findex hfy-p-to-face -@anchor{hfy-p-to-face} - -@lisp - -(hfy-p-to-face @var{props}) -@end lisp - -Given @var{props}, a list of text-properties, return the value of the -face property, or @code{nil}. - -@item hfy-box-to-border-assoc -@findex hfy-box-to-border-assoc -@anchor{hfy-box-to-border-assoc} - -@lisp - -(hfy-box-to-border-assoc @var{spec}) -@end lisp - -Helper function for @ref{hfy-box-to-style}. - -@item hfy-face-attr-for-class -@findex hfy-face-attr-for-class -@anchor{hfy-face-attr-for-class} - -@lisp - -(hfy-face-attr-for-class @var{face} &optional @var{class}) -@end lisp - -Return the face attributes for @var{face}. If @var{class} is set, it -must be a @code{defface} alist key [see below]. Prior to version 0.18, -the first face specification returned by @ref{hfy-combined-face-spec} -which @emph{didn't} clash with @var{class} was returned. In versions -from 0.18 onwards, each font attribute list is scored, and the -non-conflicting list with the highest score is returned. (A specification -with a class of @code{t} is considered to match any class you specify. -This matches Emacs's behavior when deciding on which face attributes to -use, to the best of my understanding ). - -If @var{class} is @code{nil}, then you just get get whatever -@code{face-attr-construct} returns; i.e., the current specification in -effect for @var{face}. - -See @ref{hfy-display-class} for details of valid values for @var{class}. - -@item hfy-face-at -@findex hfy-face-at -@anchor{hfy-face-at} - -@lisp - -(hfy-face-at P) -@end lisp - -Find face in effect at point P. If overlays are to be considered -(see @ref{hfy-optimisations}) then this may return a @code{defface} style -list of face properties instead of a face symbol. - -@item hfy-bgcol -@findex hfy-bgcol -@anchor{hfy-bgcol} - -@lisp - -(hfy-bgcol @var{color}) -@end lisp - -As per @ref{hfy-color} but for background colors. - -@item hfy-kludge-cperl-mode -@findex hfy-kludge-cperl-mode -@anchor{hfy-kludge-cperl-mode} - -@lisp - -(hfy-kludge-cperl-mode) -@end lisp - -cperl mode does its best to not do some of its fontification when not -in a windowing system---we try to trick it@dots{} - -@item hfy-href -@findex hfy-href -@anchor{hfy-href} - -@lisp - -(hfy-href @var{this-file} @var{def-files} @var{tag} @var{tag-map}) -@end lisp - -Return a relative href to the tag in question, based on - -@var{this-file} @ref{hfy-link-extn} @ref{hfy-extn} @var{def-files} @var{tag} and @var{tag-map} - -@var{this-file} is the current source file -@var{def-files} is a list of file containing possible link endpoints for @var{tag} -@var{tag} is the @var{tag} in question -@var{tag-map} is the entry in @ref{hfy-tags-cache}. - -@item hfy-shell -@findex hfy-shell -@anchor{hfy-shell} - -@lisp - -(hfy-shell) -@end lisp - -Returns a best guess at a Bourne compatible shell to use: If the current -shell doesn't look promising, fall back to @ref{hfy-shell-file-name}. - -@item hfy-load-tags-cache -@findex hfy-load-tags-cache -@anchor{hfy-load-tags-cache} - -@lisp - -(hfy-load-tags-cache @var{srcdir}) -@end lisp - -Run @ref{hfy-etags-cmd} on @var{srcdir}: load @ref{hfy-tags-cache} and @ref{hfy-tags-sortl}. - -@item hfy-parse-tags-buffer -@findex hfy-parse-tags-buffer -@anchor{hfy-parse-tags-buffer} - -@lisp - -(hfy-parse-tags-buffer @var{srcdir} @var{buffer}) -@end lisp - -Parse a @var{buffer} containing etags formatted output, loading the -@ref{hfy-tags-cache} and @ref{hfy-tags-sortl} entries for @var{srcdir}. - -@item hfy-interq -@findex hfy-interq -@anchor{hfy-interq} - -@lisp - -(hfy-interq @var{set-a} @var{set-b}) -@end lisp - -Return the intersection (using @code{eq}) of 2 lists. - -@item hfy-text-p -@findex hfy-text-p -@anchor{hfy-text-p} - -@lisp - -(hfy-text-p @var{srcdir} @var{file}) -@end lisp - -Is @var{srcdir}/@var{file} text? Uses @ref{hfy-istext-command} to determine this. - -@item hfy-opt -@findex hfy-opt -@anchor{hfy-opt} - -@lisp - -(hfy-opt @var{symbol}) -@end lisp - -Is @ref{hfy-optimisations} member @var{symbol} set or not? - -@item hfy-dirname -@findex hfy-dirname -@anchor{hfy-dirname} - -@lisp - -(hfy-dirname @var{file}) -@end lisp - -Return everything preceding the last @samp{/} from a relative filename, -on the assumption that this will produce a relative directory name. Hardly -bombproof, but good enough in the context in which it is being used. - -@item hfy-html-dekludge-buffer -@findex hfy-html-dekludge-buffer -@anchor{hfy-html-dekludge-buffer} - -@lisp - -(hfy-html-dekludge-buffer) -@end lisp - -Transform all dangerous characters marked with the @code{hfy-quoteme} property -using @ref{hfy-html-quote} - -See also @ref{hfy-html-enkludge-buffer}. - -@item hfy-copy-and-fontify-file -@findex hfy-copy-and-fontify-file -@anchor{hfy-copy-and-fontify-file} - -@lisp - -(hfy-copy-and-fontify-file @var{srcdir} @var{dstdir} @var{file}) -@end lisp - -Open @var{file} in @var{srcdir}---if fontified, write a fontified copy to @var{dstdir} -adding an extension of @ref{hfy-extn}. Fontification is actually done by -@ref{htmlfontify-buffer}. If the buffer is not fontified, just copy it. - -@item hfy-decor -@findex hfy-decor -@anchor{hfy-decor} - -@lisp - -(hfy-decor @var{tag} @var{val}) -@end lisp - -Derive CSS text-decoration specifiers from various Emacs font attributes. - -@item hfy-slant -@findex hfy-slant -@anchor{hfy-slant} - -@lisp - -(hfy-slant @var{slant}) -@end lisp - -Derive a font-style CSS specifier from the Emacs :slant -attribute---CSS does not define the reverse-* styles, so just maps -those to the regular specifiers. - -@item hfy-tags-for-file -@findex hfy-tags-for-file -@anchor{hfy-tags-for-file} - -@lisp - -(hfy-tags-for-file @var{srcdir} @var{file}) -@end lisp - -List of etags tags that have definitions in this @var{file}. Looks up -the tags cache in @ref{hfy-tags-cache} using @var{srcdir} as the key. - -@item hfy-width -@findex hfy-width -@anchor{hfy-width} - -@lisp - -(hfy-width @var{width}) -@end lisp - -Convert an Emacs @code{:width} attribute to a CSS font-stretch attribute. - -@comment /AUTOGENERATED BLOCK -@end table - -@node Variables -@section Variables -@cindex variables - -Important variables that are not customization items: - -@table @code - -@item hfy-tags-cache -@vindex hfy-tags-cache -@anchor{hfy-tags-cache} - -This is an alist of the form: - -@example -(("/src/dir/0" . tag-hash0) ("/src/dir/1" tag-hash1) @dots{} ) -@end example - -Each tag hash entry then contains entries of the form: - -@example -"tag_string" => (("file/name.ext" line char) @dots{} ) -@end example - -i.e., an alist mapping (relative) file paths to line and character offsets. - -See @ref{hfy-load-tags-cache}. - -@item hfy-tags-rmap -@vindex hfy-tags-rmap -@anchor{hfy-tags-rmap} - -@code{hfy-tags-rmap} is an alist of the form: - -@lisp -(("/src/dir" . tag-rmap-hash)) -@end lisp - -Where tag-rmap-hash has entries of the form: - -@example -"tag_string" => ( "file/name.ext" line char ) -@end example - -Unlike @ref{hfy-tags-cache} these are the locations of occurrences of -tagged items, not the locations of their definitions. - -@item hfy-tags-sortl -@vindex hfy-tags-sortl -@anchor{hfy-tags-sortl} - -@code{hfy-tags-sortl} is an alist of the form: - -@example -(("/src/dir" . (tag0 tag1 tag2)) @dots{} ) -@end example - -Where the tags are stored in descending order of length. - -See: @ref{hfy-load-tags-cache}. - -@end table - -@node Data Structures -@section Data Structures -@cindex Data Structures - -Some of the (informal) data structures used in Htmlfontify are detailed here: - -@table @code - -@item hfy-style-assoc -@cindex hfy-style-assoc -@anchor{hfy-style-assoc} - -An assoc representing/describing an Emacs face. Properties may be repeated, -in which case later properties should be treated as if they were inherited -from a ``parent'' font. (For some properties, only the first encountered value -is of any importance, for others the values might be cumulative, and for -others they might be cumulative in a complex way.) - -Some examples: - -@lisp -(hfy-face-to-style 'default) => - - (("background" . "rgb(0, 0, 0)" ) - ("color" . "rgb(255, 255, 255)") - ("font-style" . "normal" ) - ("font-weight" . "500" ) - ("font-stretch" . "normal" ) - ("font-family" . "misc-fixed" ) - ("font-size" . "13pt" ) - ("text-decoration" . "none" )) - -(hfy-face-to-style 'Info-title-3-face) => - - (("font-weight" . "700" ) - ("font-family" . "helv" ) - ("font-size" . "120%" ) - ("text-decoration" . "none") ) -@end lisp - -@item hfy-sheet-assoc -@cindex hfy-sheet-assoc -@anchor{hfy-sheet-assoc} - -An assoc with elements of the form @samp{(face-name style-name . style-string)}. -The actual stylesheet for each page is derived from one of these. - -@lisp -'((default "default" . "@{ background: black; color: white@}") - (font-lock-string-face "string" . "@{ color: rgb(64,224,208) @}")) -@end lisp - -@item hfy-facemap-assoc -@cindex hfy-facemap-assoc -@anchor{hfy-facemap-assoc} - -An assoc of @code{(point . @var{face-symbol})} or -@code{(point . @code{defface} attribute list)} and @code{(point -. end)} elements, in descending order of point value (i.e., from the -file's end to its beginning). The map is in reverse order because -inserting a @samp{} text to embed in the document---the string -returned will be used as the header for the htmlfontified version of -the source file. - -See also: @ref{hfy-page-footer} - -@item hfy-src-doc-link-style -@vindex hfy-src-doc-link-style -@anchor{hfy-src-doc-link-style} - -String to add to the @samp{} section in this way, without -referring to an external file. - -In order to add styles to a subtree, use the @code{:HTML_CONTAINER_CLASS:} -property to assign a class to the tree. In order to specify CSS styles for a -particular headline, you can use the id specified in a @code{:CUSTOM_ID:} -property. - -@c FIXME: More about header and footer styles -@c FIXME: Talk about links and targets. - -@node JavaScript support, , CSS support, HTML export -@subsection JavaScript supported display of web pages - -@cindex Rose, Sebastian -Sebastian Rose has written a JavaScript program especially designed to -enhance the web viewing experience of HTML files created with Org. This -program allows you to view large files in two different ways. The first one -is an @emph{Info}-like mode where each section is displayed separately and -navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys -as well, press @kbd{?} for an overview of the available keys). The second -view type is a @emph{folding} view much like Org provides inside Emacs. The -script is available at @url{http://orgmode.org/org-info.js} and you can find -the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}. -We host the script at our site, but if you use it a lot, you might not want -to be dependent on @url{http://orgmode.org} and prefer to install a local -copy on your own web server. - -All it then takes to use this program is adding a single line to the Org -file: - -@cindex #+INFOJS_OPT -@example -#+INFOJS_OPT: view:info toc:nil -@end example - -@noindent -If this line is found, the HTML header will automatically contain the code -needed to invoke the script. Using the line above, you can set the following -viewing options: - -@example -path: @r{The path to the script. The default is to grab the script from} - @r{@url{http://orgmode.org/org-info.js}, but you might want to have} - @r{a local copy and use a path like @samp{../scripts/org-info.js}.} -view: @r{Initial view when the website is first shown. Possible values are:} - info @r{Info-like interface with one section per page.} - overview @r{Folding interface, initially showing only top-level.} - content @r{Folding interface, starting with all headlines visible.} - showall @r{Folding interface, all headlines and text visible.} -sdepth: @r{Maximum headline level that will still become an independent} - @r{section for info and folding modes. The default is taken from} - @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).} - @r{If this is smaller than in @code{org-export-headline-levels}, each} - @r{info/folding section can still contain child headlines.} -toc: @r{Should the table of contents @emph{initially} be visible?} - @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.} -tdepth: @r{The depth of the table of contents. The defaults are taken from} - @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.} -ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?} - @r{If yes, the toc will never be displayed as a section.} -ltoc: @r{Should there be short contents (children) in each section?} - @r{Make this @code{above} if the section should be above initial text.} -mouse: @r{Headings are highlighted when the mouse is over them. Should be} - @r{@samp{underline} (default) or a background color like @samp{#cccccc}.} -buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the} - @r{default), only one such button will be present.} -@end example -@noindent -@vindex org-html-infojs-options -@vindex org-html-use-infojs -You can choose default values for these options by customizing the variable -@code{org-html-infojs-options}. If you always want to apply the script to your -pages, configure the variable @code{org-html-use-infojs}. - -@node @LaTeX{} and PDF export, Markdown export, HTML export, Exporting -@section @LaTeX{} and PDF export -@cindex @LaTeX{} export -@cindex PDF export - -@LaTeX{} export can produce an arbitrarily complex LaTeX document of any -standard or custom document class. With further processing@footnote{The -default @LaTeX{} output is designed for processing with @code{pdftex} or -@LaTeX{}. It includes packages that are not compatible with @code{xetex} and -possibly @code{luatex}. The @LaTeX{} exporter can be configured to support -alternative TeX engines, see the options -@code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.}, -which the @LaTeX{} exporter is able to control, this back-end is able to -produce PDF output. Because the @LaTeX{} exporter can be configured to use -the @code{hyperref} package, the default setup produces fully-linked PDF -output. - -As in @LaTeX{}, blank lines are meaningful for this back-end: a paragraph -will not be started if two contiguous syntactical elements are not separated -by an empty line. - -This back-end also offers enhanced support for footnotes. Thus, it handles -nested footnotes, footnotes in tables and footnotes in a list item's -description. - -@menu -* @LaTeX{} export commands:: How to export to LaTeX and PDF -* Header and sectioning:: Setting up the export file structure -* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code -* @LaTeX{} specific attributes:: Controlling @LaTeX{} output -@end menu - -@node @LaTeX{} export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export -@subsection @LaTeX{} export commands - -@table @kbd -@orgcmd{C-c C-e l l,org-latex-export-to-latex} -Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{} -file will be @file{myfile.tex}. The file will be overwritten without -warning. -@orgcmd{C-c C-e l L,org-latex-export-as-latex} -Export to a temporary buffer. Do not create a file. -@orgcmd{C-c C-e l p,org-latex-export-to-pdf} -Export as @LaTeX{} and then process to PDF. -@item C-c C-e l o -Export as @LaTeX{} and then process to PDF, then open the resulting PDF file. -@end table - -@node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{} export commands, @LaTeX{} and PDF export -@subsection Header and sectioning structure -@cindex @LaTeX{} class -@cindex @LaTeX{} sectioning structure -@cindex @LaTeX{} header -@cindex header, for @LaTeX{} files -@cindex sectioning structure, for @LaTeX{} export - -By default, the first three outline levels become headlines, defining a -general document structure. Additional levels are exported as @code{itemize} -or @code{enumerate} lists. The transition can also occur at a different -level (@pxref{Export settings}). - -By default, the @LaTeX{} output uses the class @code{article}. - -@vindex org-latex-default-class -@vindex org-latex-classes -@vindex org-latex-default-packages-alist -@vindex org-latex-packages-alist -You can change this globally by setting a different value for -@code{org-latex-default-class} or locally by adding an option like -@code{#+LATEX_CLASS: myclass} in your file, or with -a @code{EXPORT_LATEX_CLASS} property that applies when exporting a region -containing only this (sub)tree. The class must be listed in -@code{org-latex-classes}. This variable defines a header template for each -class@footnote{Into which the values of -@code{org-latex-default-packages-alist} and @code{org-latex-packages-alist} -are spliced.}, and allows you to define the sectioning structure for each -class. You can also define your own classes there. - -@cindex #+LATEX_CLASS -@cindex #+LATEX_CLASS_OPTIONS -@cindex property, EXPORT_LATEX_CLASS -@cindex property, EXPORT_LATEX_CLASS_OPTIONS -The @code{LATEX_CLASS_OPTIONS} keyword or @code{EXPORT_LATEX_CLASS_OPTIONS} -property can specify the options for the @code{\documentclass} macro. These -options have to be provided, as expected by @LaTeX{}, within square brackets. - -@cindex #+LATEX_HEADER -@cindex #+LATEX_HEADER_EXTRA -You can also use the @code{LATEX_HEADER} and -@code{LATEX_HEADER_EXTRA}@footnote{Unlike @code{LATEX_HEADER}, contents -from @code{LATEX_HEADER_EXTRA} keywords will not be loaded when previewing -@LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).} keywords in order -to add lines to the header. See the docstring of @code{org-latex-classes} for -more information. - -An example is shown below. - -@example -#+LATEX_CLASS: article -#+LATEX_CLASS_OPTIONS: [a4paper] -#+LATEX_HEADER: \usepackage@{xyz@} - -* Headline 1 - some text -@end example - -@node Quoting @LaTeX{} code, @LaTeX{} specific attributes, Header and sectioning, @LaTeX{} and PDF export -@subsection Quoting @LaTeX{} code - -Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly -inserted into the @LaTeX{} file. Furthermore, you can add special code that -should only be present in @LaTeX{} export with the following constructs: - -@cindex #+LATEX -@cindex #+BEGIN_LATEX -@example -Code within @@@@latex:some code@@@@ a paragraph. - -#+LATEX: Literal @LaTeX{} code for export - -#+BEGIN_LATEX -All lines between these markers are exported literally -#+END_LATEX -@end example - -@node @LaTeX{} specific attributes, , Quoting @LaTeX{} code, @LaTeX{} and PDF export -@subsection @LaTeX{} specific attributes -@cindex #+ATTR_LATEX - -@LaTeX{} understands attributes specified in an @code{ATTR_LATEX} line. They -affect tables, images, plain lists, special blocks and source blocks. - -@subsubheading Tables in @LaTeX{} export -@cindex tables, in @LaTeX{} export - -For @LaTeX{} export of a table, you can specify a label and a caption -(@pxref{Images and tables}). You can also use attributes to control table -layout and contents. Valid @LaTeX{} attributes include: - -@table @code -@item :mode -@vindex org-latex-default-table-mode -Nature of table's contents. It can be set to @code{table}, @code{math}, -@code{inline-math} or @code{verbatim}. In particular, when in @code{math} or -@code{inline-math} mode, every cell is exported as-is, horizontal rules are -ignored and the table will be wrapped in a math environment. Also, -contiguous tables sharing the same math mode will be wrapped within the same -environment. Default mode is determined in -@code{org-latex-default-table-mode}. -@item :environment -@vindex org-latex-default-table-environment -Environment used for the table. It can be set to any @LaTeX{} table -environment, like @code{tabularx}@footnote{Requires adding the -@code{tabularx} package to @code{org-latex-packages-alist}.}, -@code{longtable}, @code{array}, @code{tabu}@footnote{Requires adding the -@code{tabu} package to @code{org-latex-packages-alist}.}, -@code{bmatrix}@enddots{} It defaults to -@code{org-latex-default-table-environment} value. -@item :caption -@code{#+CAPTION} keyword is the simplest way to set a caption for a table -(@pxref{Images and tables}). If you need more advanced commands for that -task, you can use @code{:caption} attribute instead. Its value should be raw -@LaTeX{} code. It has precedence over @code{#+CAPTION}. -@item :float -@itemx :placement -Float environment for the table. Possible values are @code{sidewaystable}, -@code{multicolumn}, @code{t} and @code{nil}. When unspecified, a table with -a caption will have a @code{table} environment. Moreover, @code{:placement} -attribute can specify the positioning of the float. -@item :align -@itemx :font -@itemx :width -Set, respectively, the alignment string of the table, its font size and its -width. They only apply on regular tables. -@item :spread -Boolean specific to the @code{tabu} and @code{longtabu} environments, and -only takes effect when used in conjunction with the @code{:width} attribute. -When @code{:spread} is non-@code{nil}, the table will be spread or shrunk by the -value of @code{:width}. -@item :booktabs -@itemx :center -@itemx :rmlines -@vindex org-latex-tables-booktabs -@vindex org-latex-tables-centered -They toggle, respectively, @code{booktabs} usage (assuming the package is -properly loaded), table centering and removal of every horizontal rule but -the first one (in a "table.el" table only). In particular, -@code{org-latex-tables-booktabs} (respectively @code{org-latex-tables-centered}) -activates the first (respectively second) attribute globally. -@item :math-prefix -@itemx :math-suffix -@itemx :math-arguments -A string that will be inserted, respectively, before the table within the -math environment, after the table within the math environment, and between -the macro name and the contents of the table. The @code{:math-arguments} -attribute is used for matrix macros that require more than one argument -(e.g., @code{qbordermatrix}). -@end table - -Thus, attributes can be used in a wide array of situations, like writing -a table that will span over multiple pages, or a matrix product: - -@example -#+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l -| ..... | ..... | -| ..... | ..... | - -#+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times -| a | b | -| c | d | -#+ATTR_LATEX: :mode math :environment bmatrix -| 1 | 2 | -| 3 | 4 | -@end example - -In the example below, @LaTeX{} command -@code{\bicaption@{HeadingA@}@{HeadingB@}} will set the caption. - -@example -#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@} -| ..... | ..... | -| ..... | ..... | -@end example - - -@subsubheading Images in @LaTeX{} export -@cindex images, inline in @LaTeX{} -@cindex inlining images in @LaTeX{} - -Images that are linked to without a description part in the link, like -@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF -output file resulting from @LaTeX{} processing. Org will use an -@code{\includegraphics} macro to insert the image@footnote{In the case of -TikZ (@url{http://sourceforge.net/projects/pgf/}) images, it will become an -@code{\input} macro wrapped within a @code{tikzpicture} environment.}. - -You can specify specify image width or height with, respectively, -@code{:width} and @code{:height} attributes. It is also possible to add any -other option with the @code{:options} attribute, as shown in the following -example: - -@example -#+ATTR_LATEX: :width 5cm :options angle=90 -[[./img/sed-hr4049.pdf]] -@end example - -If you need a specific command for the caption, use @code{:caption} -attribute. It will override standard @code{#+CAPTION} value, if any. - -@example -#+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@} -[[./img/sed-hr4049.pdf]] -@end example - -If you have specified a caption as described in @ref{Images and tables}, the -picture will be wrapped into a @code{figure} environment and thus become -a floating element. You can also ask Org to export an image as a float -without specifying caption by setting the @code{:float} attribute. You may -also set it to: -@itemize @minus -@item -@code{t}: if you want to use the standard @samp{figure} environment. It is -used by default if you provide a caption to the image. -@item -@code{multicolumn}: if you wish to include an image which spans multiple -columns in a page. This will export the image wrapped in a @code{figure*} -environment. -@item -@code{wrap}: if you would like to let text flow around the image. It will -make the figure occupy the left half of the page. -@item -@code{nil}: if you need to avoid any floating environment, even when -a caption is provided. -@end itemize -@noindent -To modify the placement option of any floating environment, set the -@code{placement} attribute. - -@example -#+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement @{r@}@{0.4\textwidth@} -[[./img/hst.png]] -@end example - -If the @code{:comment-include} attribute is set to a non-@code{nil} value, -the @LaTeX{} @code{\includegraphics} macro will be commented out. - -@subsubheading Plain lists in @LaTeX{} export -@cindex plain lists, in @LaTeX{} export - -Plain lists accept two optional attributes: @code{:environment} and -@code{:options}. The first one allows the use of a non-standard environment -(e.g., @samp{inparaenum}). The second one specifies additional arguments for -that environment. - -@example -#+ATTR_LATEX: :environment compactitem :options [$\circ$] -- you need ``paralist'' package to reproduce this example. -@end example - -@subsubheading Source blocks in @LaTeX{} export -@cindex source blocks, in @LaTeX{} export - -In addition to syntax defined in @ref{Literal examples}, names and captions -(@pxref{Images and tables}), source blocks also accept a @code{:float} -attribute. You may set it to: -@itemize @minus -@item -@code{t}: if you want to make the source block a float. It is the default -value when a caption is provided. -@item -@code{multicolumn}: if you wish to include a source block which spans multiple -columns in a page. -@item -@code{nil}: if you need to avoid any floating environment, even when a caption -is provided. It is useful for source code that may not fit in a single page. -@end itemize - -@example -#+ATTR_LATEX: :float nil -#+BEGIN_SRC emacs-lisp -Code that may not fit in a single page. -#+END_SRC -@end example - -@subsubheading Special blocks in @LaTeX{} export -@cindex special blocks, in @LaTeX{} export -@cindex abstract, in @LaTeX{} export -@cindex proof, in @LaTeX{} export - -In @LaTeX{} back-end, special blocks become environments of the same name. -Value of @code{:options} attribute will be appended as-is to that -environment's opening string. For example: - -@example -#+BEGIN_ABSTRACT -We demonstrate how to solve the Syracuse problem. -#+END_ABSTRACT - -#+ATTR_LATEX: :options [Proof of important theorem] -#+BEGIN_PROOF -... -Therefore, any even number greater than 2 is the sum of two primes. -#+END_PROOF -@end example - -@noindent -becomes - -@example -\begin@{abstract@} -We demonstrate how to solve the Syracuse problem. -\end@{abstract@} - -\begin@{proof@}[Proof of important theorem] -... -Therefore, any even number greater than 2 is the sum of two primes. -\end@{proof@} -@end example - -If you need to insert a specific caption command, use @code{:caption} -attribute. It will override standard @code{#+CAPTION} value, if any. For -example: - -@example -#+ATTR_LATEX: :caption \MyCaption@{HeadingA@} -#+BEGIN_PROOF -... -#+END_PROOF -@end example - -@subsubheading Horizontal rules -@cindex horizontal rules, in @LaTeX{} export - -Width and thickness of a given horizontal rule can be controlled with, -respectively, @code{:width} and @code{:thickness} attributes: - -@example -#+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt ------ -@end example - -@node Markdown export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting -@section Markdown export -@cindex Markdown export - -@code{md} export back-end generates Markdown syntax@footnote{Vanilla flavor, -as defined at @url{http://daringfireball.net/projects/markdown/}.} for an Org -mode buffer. - -It is built over HTML back-end: any construct not supported by Markdown -syntax (e.g., tables) will be controlled and translated by @code{html} -back-end (@pxref{HTML export}). - -@subheading Markdown export commands - -@table @kbd -@orgcmd{C-c C-e m m,org-md-export-to-markdown} -Export as a text file written in Markdown syntax. For an Org file, -@file{myfile.org}, the resulting file will be @file{myfile.md}. The file -will be overwritten without warning. -@orgcmd{C-c C-e m M,org-md-export-as-markdown} -Export to a temporary buffer. Do not create a file. -@item C-c C-e m o -Export as a text file with Markdown syntax, then open it. -@end table - -@subheading Header and sectioning structure - -@vindex org-md-headline-style -Markdown export can generate both @code{atx} and @code{setext} types for -headlines, according to @code{org-md-headline-style}. The former introduces -a hard limit of two levels, whereas the latter pushes it to six. Headlines -below that limit are exported as lists. You can also set a soft limit before -that one (@pxref{Export settings}). - -@c begin opendocument - -@node OpenDocument Text export, Org export, Markdown export, Exporting -@section OpenDocument Text export -@cindex ODT -@cindex OpenDocument -@cindex export, OpenDocument -@cindex LibreOffice - -Org mode@footnote{Versions 7.8 or later} supports export to OpenDocument Text -(ODT) format. Documents created by this exporter use the -@cite{OpenDocument-v1.2 -specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, -Open Document Format for Office Applications (OpenDocument) Version 1.2}} and -are compatible with LibreOffice 3.4. - -@menu -* Pre-requisites for ODT export:: What packages ODT exporter relies on -* ODT export commands:: How to invoke ODT export -* Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files -* Applying custom styles:: How to apply custom styles to the output -* Links in ODT export:: How links will be interpreted and formatted -* Tables in ODT export:: How Tables are exported -* Images in ODT export:: How to insert images -* Math formatting in ODT export:: How @LaTeX{} fragments are formatted -* Labels and captions in ODT export:: How captions are rendered -* Literal examples in ODT export:: How source and example blocks are formatted -* Advanced topics in ODT export:: Read this if you are a power user -@end menu - -@node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export -@subsection Pre-requisites for ODT export -@cindex zip -The ODT exporter relies on the @file{zip} program to create the final -output. Check the availability of this program before proceeding further. - -@node ODT export commands, Extending ODT export, Pre-requisites for ODT export, OpenDocument Text export -@subsection ODT export commands - -@subsubheading Exporting to ODT -@anchor{x-export-to-odt} - -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@orgcmd{C-c C-e o o,org-odt-export-to-odt} -@cindex property EXPORT_FILE_NAME - -Export as OpenDocument Text file. - -@vindex org-odt-preferred-output-format -If @code{org-odt-preferred-output-format} is specified, automatically convert -the exported file to that format. @xref{x-export-to-other-formats, , -Automatically exporting to other formats}. - -For an Org file @file{myfile.org}, the ODT file will be -@file{myfile.odt}. The file will be overwritten without warning. If there -is an active region,@footnote{This requires @code{transient-mark-mode} to be -turned on} only the region will be exported. If the selected region is a -single tree,@footnote{To select the current subtree, use @kbd{C-c @@}} the -tree head will become the document title. If the tree head entry has, or -inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the -export. - -@kbd{C-c C-e o O} -Export as an OpenDocument Text file and open the resulting file. - -@vindex org-odt-preferred-output-format -If @code{org-odt-preferred-output-format} is specified, open the converted -file instead. @xref{x-export-to-other-formats, , Automatically exporting to -other formats}. -@end table - -@node Extending ODT export, Applying custom styles, ODT export commands, OpenDocument Text export -@subsection Extending ODT export - -The ODT exporter can interface with a variety of document -converters and supports popular converters out of the box. As a result, you -can use it to export to formats like @samp{doc} or convert a document from -one format (say @samp{csv}) to another format (say @samp{ods} or @samp{xls}). - -@cindex @file{unoconv} -@cindex LibreOffice -If you have a working installation of LibreOffice, a document converter is -pre-configured for you and you can use it right away. If you would like to -use @file{unoconv} as your preferred converter, customize the variable -@code{org-odt-convert-process} to point to @code{unoconv}. You can -also use your own favorite converter or tweak the default settings of the -@file{LibreOffice} and @samp{unoconv} converters. @xref{Configuring a -document converter}. - -@subsubsection Automatically exporting to other formats -@anchor{x-export-to-other-formats} - -@vindex org-odt-preferred-output-format -Very often, you will find yourself exporting to ODT format, only to -immediately save the exported document to other formats like @samp{doc}, -@samp{docx}, @samp{rtf}, @samp{pdf} etc. In such cases, you can specify your -preferred output format by customizing the variable -@code{org-odt-preferred-output-format}. This way, the export commands -(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a -format that is of immediate interest to you. - -@subsubsection Converting between document formats -@anchor{x-convert-to-other-formats} - -There are many document converters in the wild which support conversion to -and from various file formats, including, but not limited to the -ODT format. LibreOffice converter, mentioned above, is one such -converter. Once a converter is configured, you can interact with it using -the following command. - -@vindex org-odt-convert -@table @kbd - -@item M-x org-odt-convert RET -Convert an existing document from one format to another. With a prefix -argument, also open the newly produced file. -@end table - -@node Applying custom styles, Links in ODT export, Extending ODT export, OpenDocument Text export -@subsection Applying custom styles -@cindex styles, custom -@cindex template, custom - -The ODT exporter ships with a set of OpenDocument styles -(@pxref{Working with OpenDocument style files}) that ensure a well-formatted -output. These factory styles, however, may not cater to your specific -tastes. To customize the output, you can either modify the above styles -files directly, or generate the required styles using an application like -LibreOffice. The latter method is suitable for expert and non-expert -users alike, and is described here. - -@subsubsection Applying custom styles: the easy way - -@enumerate -@item -Create a sample @file{example.org} file with the below settings and export it -to ODT format. - -@example -#+OPTIONS: H:10 num:t -@end example - -@item -Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist} -to locate the target styles---these typically have the @samp{Org} prefix---and -modify those to your taste. Save the modified file either as an -OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file. - -@item -@cindex #+ODT_STYLES_FILE -@vindex org-odt-styles-file -Customize the variable @code{org-odt-styles-file} and point it to the -newly created file. For additional configuration options -@pxref{x-overriding-factory-styles,,Overriding factory styles}. - -If you would like to choose a style on a per-file basis, you can use the -@code{#+ODT_STYLES_FILE} option. A typical setting will look like - -@example -#+ODT_STYLES_FILE: "/path/to/example.ott" -@end example - -or - -@example -#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png")) -@end example - -@end enumerate - -@subsubsection Using third-party styles and templates - -You can use third-party styles and templates for customizing your output. -This will produce the desired output only if the template provides all -style names that the @samp{ODT} exporter relies on. Unless this condition is -met, the output is going to be less than satisfactory. So it is highly -recommended that you only work with templates that are directly derived from -the factory settings. - -@node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export -@subsection Links in ODT export -@cindex links, in ODT export - -ODT exporter creates native cross-references for internal links. It creates -Internet-style links for all other links. - -A link with no description and destined to a regular (un-itemized) outline -heading is replaced with a cross-reference and section number of the heading. - -A @samp{\ref@{label@}}-style reference to an image, table etc. is replaced -with a cross-reference and sequence number of the labeled entity. -@xref{Labels and captions in ODT export}. - -@node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export -@subsection Tables in ODT export -@cindex tables, in ODT export - -Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el} -tables is supported. However, export of complex @file{table.el} tables---tables -that have column or row spans---is not supported. Such tables are -stripped from the exported document. - -By default, a table is exported with top and bottom frames and with rules -separating row and column groups (@pxref{Column groups}). Furthermore, all -tables are typeset to occupy the same width. If the table specifies -alignment and relative width for its columns (@pxref{Column width and -alignment}) then these are honored on export.@footnote{The column widths are -interpreted as weighted ratios with the default weight being 1} - -@cindex #+ATTR_ODT -You can control the width of the table by specifying @code{:rel-width} -property using an @code{#+ATTR_ODT} line. - -For example, consider the following table which makes use of all the rules -mentioned above. - -@example -#+ATTR_ODT: :rel-width 50 -| Area/Month | Jan | Feb | Mar | Sum | -|---------------+-------+-------+-------+-------| -| / | < | | | < | -| | | | | | -| North America | 1 | 21 | 926 | 948 | -| Middle East | 6 | 75 | 844 | 925 | -| Asia Pacific | 9 | 27 | 790 | 826 | -|---------------+-------+-------+-------+-------| -| Sum | 16 | 123 | 2560 | 2699 | -@end example - -On export, the table will occupy 50% of text area. The columns will be sized -(roughly) in the ratio of 13:5:5:5:6. The first column will be left-aligned -and rest of the columns will be right-aligned. There will be vertical rules -after separating the header and last columns from other columns. There will -be horizontal rules separating the header and last rows from other rows. - -If you are not satisfied with the above formatting options, you can create -custom table styles and associate them with a table using the -@code{#+ATTR_ODT} line. @xref{Customizing tables in ODT export}. - -@node Images in ODT export, Math formatting in ODT export, Tables in ODT export, OpenDocument Text export -@subsection Images in ODT export -@cindex images, embedding in ODT -@cindex embedding images in ODT - -@subsubheading Embedding images -You can embed images within the exported document by providing a link to the -desired image file with no link description. For example, to embed -@samp{img.png} do either of the following: - -@example -[[file:img.png]] -@end example - -@example -[[./img.png]] -@end example - -@subsubheading Embedding clickable images -You can create clickable images by providing a link whose description is a -link to an image file. For example, to embed a image -@file{org-mode-unicorn.png} which when clicked jumps to -@uref{http://Orgmode.org} website, do the following - -@example -[[http://orgmode.org][./org-mode-unicorn.png]] -@end example - -@subsubheading Sizing and scaling of embedded images - -@cindex #+ATTR_ODT -You can control the size and scale of the embedded images using the -@code{#+ATTR_ODT} attribute. - -@cindex identify, ImageMagick -@vindex org-odt-pixels-per-inch -The exporter specifies the desired size of the image in the final document in -units of centimeters. In order to scale the embedded images, the exporter -queries for pixel dimensions of the images using one of a) ImageMagick's -@file{identify} program or b) Emacs `create-image' and `image-size' -APIs@footnote{Use of @file{ImageMagick} is only desirable. However, if you -routinely produce documents that have large images or you export your Org -files that has images using a Emacs batch script, then the use of -@file{ImageMagick} is mandatory.}. The pixel dimensions are subsequently -converted in to units of centimeters using -@code{org-odt-pixels-per-inch}. The default value of this variable is -set to @code{display-pixels-per-inch}. You can tweak this variable to -achieve the best results. - -The examples below illustrate the various possibilities. - -@table @asis -@item Explicitly size the image -To embed @file{img.png} as a 10 cm x 10 cm image, do the following: - -@example -#+ATTR_ODT: :width 10 :height 10 -[[./img.png]] -@end example - -@item Scale the image -To embed @file{img.png} at half its size, do the following: - -@example -#+ATTR_ODT: :scale 0.5 -[[./img.png]] -@end example - -@item Scale the image to a specific width -To embed @file{img.png} with a width of 10 cm while retaining the original -height:width ratio, do the following: - -@example -#+ATTR_ODT: :width 10 -[[./img.png]] -@end example - -@item Scale the image to a specific height -To embed @file{img.png} with a height of 10 cm while retaining the original -height:width ratio, do the following - -@example -#+ATTR_ODT: :height 10 -[[./img.png]] -@end example -@end table - -@subsubheading Anchoring of images - -@cindex #+ATTR_ODT -You can control the manner in which an image is anchored by setting the -@code{:anchor} property of it's @code{#+ATTR_ODT} line. You can specify one -of the following three values for the @code{:anchor} property: -@samp{"as-char"}, @samp{"paragraph"} and @samp{"page"}. - -To create an image that is anchored to a page, do the following: -@example -#+ATTR_ODT: :anchor "page" -[[./img.png]] -@end example - -@node Math formatting in ODT export, Labels and captions in ODT export, Images in ODT export, OpenDocument Text export -@subsection Math formatting in ODT export - -The ODT exporter has special support for handling math. - -@menu -* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments -* Working with MathML or OpenDocument formula files:: How to embed equations in native format -@end menu - -@node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in ODT export, Math formatting in ODT export -@subsubsection Working with @LaTeX{} math snippets - -@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT -document in one of the following ways: - -@cindex MathML -@enumerate -@item MathML - -This option is activated on a per-file basis with - -@example -#+OPTIONS: LaTeX:t -@end example - -With this option, @LaTeX{} fragments are first converted into MathML -fragments using an external @LaTeX{}-to-MathML converter program. The -resulting MathML fragments are then embedded as an OpenDocument Formula in -the exported document. - -@vindex org-latex-to-mathml-convert-command -@vindex org-latex-to-mathml-jar-file - -You can specify the @LaTeX{}-to-MathML converter by customizing the variables -@code{org-latex-to-mathml-convert-command} and -@code{org-latex-to-mathml-jar-file}. - -If you prefer to use @file{MathToWeb}@footnote{See -@uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}} as your -converter, you can configure the above variables as shown below. - -@lisp -(setq org-latex-to-mathml-convert-command - "java -jar %j -unicode -force -df %o %I" - org-latex-to-mathml-jar-file - "/path/to/mathtoweb.jar") -@end lisp - -You can use the following commands to quickly verify the reliability of -the @LaTeX{}-to-MathML converter. - -@table @kbd -@item M-x org-odt-export-as-odf RET -Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file. - -@item M-x org-odt-export-as-odf-and-open RET -Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file -and open the formula file with the system-registered application. -@end table - -@cindex dvipng -@cindex imagemagick -@item PNG images - -This option is activated on a per-file basis with - -@example -#+OPTIONS: tex:dvipng -@end example - -or: - -@example -#+OPTIONS: tex:imagemagick -@end example - -With this option, @LaTeX{} fragments are processed into PNG images and the -resulting images are embedded in the exported document. This method requires -that the @file{dvipng} program or @file{imagemagick} suite be available on -your system. -@end enumerate - -@node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in ODT export -@subsubsection Working with MathML or OpenDocument formula files - -For various reasons, you may find embedding @LaTeX{} math snippets in an -ODT document less than reliable. In that case, you can embed a -math equation by linking to its MathML (@file{.mml}) source or its -OpenDocument formula (@file{.odf}) file as shown below: - -@example -[[./equation.mml]] -@end example - -or - -@example -[[./equation.odf]] -@end example - -@node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export -@subsection Labels and captions in ODT export - -You can label and caption various category of objects---an inline image, a -table, a @LaTeX{} fragment or a Math formula---using @code{#+LABEL} and -@code{#+CAPTION} lines. @xref{Images and tables}. ODT exporter enumerates -each labeled or captioned object of a given category separately. As a -result, each such object is assigned a sequence number based on order of it's -appearance in the Org file. - -In the exported document, a user-provided caption is augmented with the -category and sequence number. Consider the following inline image in an Org -file. - -@example -#+CAPTION: Bell curve -#+LABEL: fig:SED-HR4049 -[[./img/a.png]] -@end example - -It could be rendered as shown below in the exported document. - -@example -Figure 2: Bell curve -@end example - -@vindex org-odt-category-map-alist -You can modify the category component of the caption by customizing the -option @code{org-odt-category-map-alist}. For example, to tag all embedded -images with the string @samp{Illustration} (instead of the default -@samp{Figure}) use the following setting: - -@lisp -(setq org-odt-category-map-alist - (("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p))) -@end lisp - -With this, previous image will be captioned as below in the exported -document. - -@example -Illustration 2: Bell curve -@end example - -@node Literal examples in ODT export, Advanced topics in ODT export, Labels and captions in ODT export, OpenDocument Text export -@subsection Literal examples in ODT export - -Export of literal examples (@pxref{Literal examples}) with full fontification -is supported. Internally, the exporter relies on @file{htmlfontify.el} to -generate all style definitions needed for a fancy listing.@footnote{Your -@file{htmlfontify.el} library must at least be at Emacs 24.1 levels for -fontification to be turned on.} The auto-generated styles have @samp{OrgSrc} -as prefix and inherit their color from the faces used by Emacs -@code{font-lock} library for the source language. - -@vindex org-odt-fontify-srcblocks -If you prefer to use your own custom styles for fontification, you can do -so by customizing the option -@code{org-odt-create-custom-styles-for-srcblocks}. - -@vindex org-odt-create-custom-styles-for-srcblocks -You can turn off fontification of literal examples by customizing the -option @code{org-odt-fontify-srcblocks}. - -@node Advanced topics in ODT export, , Literal examples in ODT export, OpenDocument Text export -@subsection Advanced topics in ODT export - -If you rely heavily on ODT export, you may want to exploit the full -set of features that the exporter offers. This section describes features -that would be of interest to power users. - -@menu -* Configuring a document converter:: How to register a document converter -* Working with OpenDocument style files:: Explore the internals -* Creating one-off styles:: How to produce custom highlighting etc -* Customizing tables in ODT export:: How to define and use Table templates -* Validating OpenDocument XML:: How to debug corrupt OpenDocument files -@end menu - -@node Configuring a document converter, Working with OpenDocument style files, Advanced topics in ODT export, Advanced topics in ODT export -@subsubsection Configuring a document converter -@cindex convert -@cindex doc, docx, rtf -@cindex converter - -The ODT exporter can work with popular converters with little or no -extra configuration from your side. @xref{Extending ODT export}. -If you are using a converter that is not supported by default or if you would -like to tweak the default converter settings, proceed as below. - -@enumerate -@item Register the converter - -@vindex org-odt-convert-processes -Name your converter and add it to the list of known converters by -customizing the option @code{org-odt-convert-processes}. Also specify how -the converter can be invoked via command-line to effect the conversion. - -@item Configure its capabilities - -@vindex org-odt-convert-capabilities -@anchor{x-odt-converter-capabilities} Specify the set of formats the -converter can handle by customizing the variable -@code{org-odt-convert-capabilities}. Use the default value for this -variable as a guide for configuring your converter. As suggested by the -default setting, you can specify the full set of formats supported by the -converter and not limit yourself to specifying formats that are related to -just the OpenDocument Text format. - -@item Choose the converter - -@vindex org-odt-convert-process -Select the newly added converter as the preferred one by customizing the -option @code{org-odt-convert-process}. -@end enumerate - -@node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export -@subsubsection Working with OpenDocument style files -@cindex styles, custom -@cindex template, custom - -This section explores the internals of the ODT exporter and the -means by which it produces styled documents. Read this section if you are -interested in exploring the automatic and custom OpenDocument styles used by -the exporter. - -@anchor{x-factory-styles} -@subsubheading Factory styles - -The ODT exporter relies on two files for generating its output. -These files are bundled with the distribution under the directory pointed to -by the variable @code{org-odt-styles-dir}. The two files are: - -@itemize -@anchor{x-orgodtstyles-xml} -@item -@file{OrgOdtStyles.xml} - -This file contributes to the @file{styles.xml} file of the final @samp{ODT} -document. This file gets modified for the following purposes: -@enumerate - -@item -To control outline numbering based on user settings. - -@item -To add styles generated by @file{htmlfontify.el} for fontification of code -blocks. -@end enumerate - -@anchor{x-orgodtcontenttemplate-xml} -@item -@file{OrgOdtContentTemplate.xml} - -This file contributes to the @file{content.xml} file of the final @samp{ODT} -document. The contents of the Org outline are inserted between the -@samp{}@dots{}@samp{} elements of this file. - -Apart from serving as a template file for the final @file{content.xml}, the -file serves the following purposes: -@enumerate - -@item -It contains automatic styles for formatting of tables which are referenced by -the exporter. - -@item -It contains @samp{}@dots{}@samp{} -elements that control how various entities---tables, images, equations, -etc.---are numbered. -@end enumerate -@end itemize - -@anchor{x-overriding-factory-styles} -@subsubheading Overriding factory styles -The following two variables control the location from which the ODT -exporter picks up the custom styles and content template files. You can -customize these variables to override the factory styles used by the -exporter. - -@itemize -@anchor{x-org-odt-styles-file} -@item -@code{org-odt-styles-file} - -Use this variable to specify the @file{styles.xml} that will be used in the -final output. You can specify one of the following values: - -@enumerate -@item A @file{styles.xml} file - -Use this file instead of the default @file{styles.xml} - -@item A @file{.odt} or @file{.ott} file - -Use the @file{styles.xml} contained in the specified OpenDocument Text or -Template file - -@item A @file{.odt} or @file{.ott} file and a subset of files contained within them - -Use the @file{styles.xml} contained in the specified OpenDocument Text or -Template file. Additionally extract the specified member files and embed -those within the final @samp{ODT} document. - -Use this option if the @file{styles.xml} file references additional files -like header and footer images. - -@item @code{nil} - -Use the default @file{styles.xml} -@end enumerate - -@anchor{x-org-odt-content-template-file} -@item -@code{org-odt-content-template-file} - -Use this variable to specify the blank @file{content.xml} that will be used -in the final output. -@end itemize - -@node Creating one-off styles, Customizing tables in ODT export, Working with OpenDocument style files, Advanced topics in ODT export -@subsubsection Creating one-off styles - -There are times when you would want one-off formatting in the exported -document. You can achieve this by embedding raw OpenDocument XML in the Org -file. The use of this feature is better illustrated with couple of examples. - -@enumerate -@item Embedding ODT tags as part of regular text - -You can inline OpenDocument syntax by enclosing it within -@samp{@@@@odt:...@@@@} markup. For example, to highlight a region of text do -the following: - -@example -@@@@odt:This is a highlighted -text@@@@. But this is a regular text. -@end example - -@strong{Hint:} To see the above example in action, edit your -@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a -custom @samp{Highlight} style as shown below. - -@example - - - -@end example - -@item Embedding a one-line OpenDocument XML - -You can add a simple OpenDocument one-liner using the @code{#+ODT:} -directive. For example, to force a page break do the following: - -@example -#+ODT: -@end example - -@strong{Hint:} To see the above example in action, edit your -@file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a -custom @samp{PageBreak} style as shown below. - -@example - - - -@end example - -@item Embedding a block of OpenDocument XML - -You can add a large block of OpenDocument XML using the -@code{#+BEGIN_ODT}@dots{}@code{#+END_ODT} construct. - -For example, to create a one-off paragraph that uses bold text, do the -following: - -@example -#+BEGIN_ODT - -This paragraph is specially formatted and uses bold text. - -#+END_ODT -@end example - -@end enumerate - -@node Customizing tables in ODT export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in ODT export -@subsubsection Customizing tables in ODT export -@cindex tables, in ODT export - -@cindex #+ATTR_ODT -You can override the default formatting of the table by specifying a custom -table style with the @code{#+ATTR_ODT} line. For a discussion on default -formatting of tables @pxref{Tables in ODT export}. - -This feature closely mimics the way table templates are defined in the -OpenDocument-v1.2 -specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, -OpenDocument-v1.2 Specification}} - -@subsubheading Custom table styles: an illustration - -@vindex org-odt-table-styles -To have a quick preview of this feature, install the below setting and -export the table that follows: - -@lisp -(setq org-odt-table-styles - (append org-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) -@end lisp - -@example -#+ATTR_ODT: :style "TableWithHeaderRowAndColumn" -| Name | Phone | Age | -| Peter | 1234 | 17 | -| Anna | 4321 | 25 | -@end example - -In the above example, you used a template named @samp{Custom} and installed -two table styles with the names @samp{TableWithHeaderRowAndColumn} and -@samp{TableWithFirstRowandLastRow}. (@strong{Important:} The OpenDocument -styles needed for producing the above template have been pre-defined for -you. These styles are available under the section marked @samp{Custom -Table Template} in @file{OrgOdtContentTemplate.xml} -(@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need -additional templates you have to define these styles yourselves. - -@subsubheading Custom table styles: the nitty-gritty -To use this feature proceed as follows: - -@enumerate -@item -Create a table template@footnote{See the @code{} -element of the OpenDocument-v1.2 specification} - -A table template is nothing but a set of @samp{table-cell} and -@samp{paragraph} styles for each of the following table cell categories: - -@itemize @minus -@item Body -@item First column -@item Last column -@item First row -@item Last row -@item Even row -@item Odd row -@item Even column -@item Odd Column -@end itemize - -The names for the above styles must be chosen based on the name of the table -template using a well-defined convention. - -The naming convention is better illustrated with an example. For a table -template with the name @samp{Custom}, the needed style names are listed in -the following table. - -@multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph} -@headitem Table cell type -@tab @code{table-cell} style -@tab @code{paragraph} style -@item -@tab -@tab -@item Body -@tab @samp{CustomTableCell} -@tab @samp{CustomTableParagraph} -@item First column -@tab @samp{CustomFirstColumnTableCell} -@tab @samp{CustomFirstColumnTableParagraph} -@item Last column -@tab @samp{CustomLastColumnTableCell} -@tab @samp{CustomLastColumnTableParagraph} -@item First row -@tab @samp{CustomFirstRowTableCell} -@tab @samp{CustomFirstRowTableParagraph} -@item Last row -@tab @samp{CustomLastRowTableCell} -@tab @samp{CustomLastRowTableParagraph} -@item Even row -@tab @samp{CustomEvenRowTableCell} -@tab @samp{CustomEvenRowTableParagraph} -@item Odd row -@tab @samp{CustomOddRowTableCell} -@tab @samp{CustomOddRowTableParagraph} -@item Even column -@tab @samp{CustomEvenColumnTableCell} -@tab @samp{CustomEvenColumnTableParagraph} -@item Odd column -@tab @samp{CustomOddColumnTableCell} -@tab @samp{CustomOddColumnTableParagraph} -@end multitable - -To create a table template with the name @samp{Custom}, define the above -styles in the -@code{}...@code{} element -of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory -styles}). - -@item -Define a table style@footnote{See the attributes @code{table:template-name}, -@code{table:use-first-row-styles}, @code{table:use-last-row-styles}, -@code{table:use-first-column-styles}, @code{table:use-last-column-styles}, -@code{table:use-banding-rows-styles}, and -@code{table:use-banding-column-styles} of the @code{} element in -the OpenDocument-v1.2 specification} - -@vindex org-odt-table-styles -To define a table style, create an entry for the style in the variable -@code{org-odt-table-styles} and specify the following: - -@itemize @minus -@item the name of the table template created in step (1) -@item the set of cell styles in that template that are to be activated -@end itemize - -For example, the entry below defines two different table styles -@samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow} -based on the same template @samp{Custom}. The styles achieve their intended -effect by selectively activating the individual cell styles in that template. - -@lisp -(setq org-odt-table-styles - (append org-odt-table-styles - '(("TableWithHeaderRowAndColumn" "Custom" - ((use-first-row-styles . t) - (use-first-column-styles . t))) - ("TableWithFirstRowandLastRow" "Custom" - ((use-first-row-styles . t) - (use-last-row-styles . t)))))) -@end lisp - -@item -Associate a table with the table style - -To do this, specify the table style created in step (2) as part of -the @code{ATTR_ODT} line as shown below. - -@example -#+ATTR_ODT: :style "TableWithHeaderRowAndColumn" -| Name | Phone | Age | -| Peter | 1234 | 17 | -| Anna | 4321 | 25 | -@end example -@end enumerate - -@node Validating OpenDocument XML, , Customizing tables in ODT export, Advanced topics in ODT export -@subsubsection Validating OpenDocument XML - -Occasionally, you will discover that the document created by the -ODT exporter cannot be opened by your favorite application. One of -the common reasons for this is that the @file{.odt} file is corrupt. In such -cases, you may want to validate the document against the OpenDocument RELAX -NG Compact Syntax (RNC) schema. - -For de-compressing the @file{.odt} file@footnote{@file{.odt} files are -nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}. For -general help with validation (and schema-sensitive editing) of XML files: -@inforef{Introduction,,nxml-mode}. - -@vindex org-odt-schema-dir -If you have ready access to OpenDocument @file{.rnc} files and the needed -schema-locating rules in a single folder, you can customize the variable -@code{org-odt-schema-dir} to point to that directory. The ODT exporter -will take care of updating the @code{rng-schema-locating-files} for you. - -@c end opendocument - -@node Org export -@section Org export -@cindex Org export - -@code{org} export back-end creates a normalized version of the Org document -in current buffer. In particular, it evaluates Babel code (@pxref{Evaluating -code blocks}) and removes other back-ends specific contents. - -@subheading Org export commands - -@table @kbd -@orgcmd{C-c C-e O o,org-org-export-to-org} -Export as an Org document. For an Org file, @file{myfile.org}, the resulting -file will be @file{myfile.org.org}. The file will be overwritten without -warning. -@orgcmd{C-c C-e O O,org-org-export-as-org} -Export to a temporary buffer. Do not create a file. -@item C-c C-e O v -Export to an Org file, then open it. -@end table - -@node Texinfo export, iCalendar export, Org export, Exporting -@section Texinfo export -@cindex Texinfo export - -@samp{texinfo} export back-end generates Texinfo code and can compile it into -an Info file. - -@menu -* Texinfo export commands:: How to invoke Texinfo export -* Document preamble:: File header, title and copyright page -* Headings and sectioning structure:: Building document structure -* Indices:: Creating indices -* Quoting Texinfo code:: Incorporating literal Texinfo code -* Texinfo specific attributes:: Controlling Texinfo output -* An example:: -@end menu - -@node Texinfo export commands, Document preamble, Texinfo export, Texinfo export -@subsection Texinfo export commands - -@vindex org-texinfo-info-process -@table @kbd -@orgcmd{C-c C-e i t,org-texinfo-export-to-texinfo} -Export as a Texinfo file. For an Org file, @file{myfile.org}, the resulting -file will be @file{myfile.texi}. The file will be overwritten without -warning. -@orgcmd{C-c C-e i i,org-texinfo-export-to-info} -Export to Texinfo and then process to an Info file@footnote{By setting -@code{org-texinfo-info-process}, it is possible to generate other formats, -including DocBook.}. -@end table - -@node Document preamble, Headings and sectioning structure, Texinfo export commands, Texinfo export -@subsection Document preamble - -When processing a document, @samp{texinfo} back-end generates a minimal file -header along with a title page, a copyright page, and a menu. You control -the latter through the structure of the document (@pxref{Headings and -sectioning structure}). Various keywords allow to tweak the other parts. It -is also possible to give directions to install the document in the @samp{Top} -node. - -@subsubheading File header - -@cindex #+TEXINFO_FILENAME -Upon creating the header of a Texinfo file, the back-end guesses a name for -the Info file to be compiled. This may not be a sensible choice, e.g., if -you want to produce the final document in a different directory. Specify an -alternate path with @code{#+TEXINFO_FILENAME} keyword to override the default -destination. - -@vindex org-texinfo-coding-system -@vindex org-texinfo-classes -@cindex #+TEXINFO_HEADER -@cindex #+TEXINFO_CLASS -Along with the output file name, the header contains information about the -language (@pxref{Export settings}) and current encoding used@footnote{See -@code{org-texinfo-coding-system} for more information.}. Insert -a @code{#+TEXINFO_HEADER} keyword for each additional command needed, e.g., -@@code@{@@synindex@}. - -If you happen to regularly install the same set of commands, it may be easier -to define your own class in @code{org-texinfo-classes}, which see. Set -@code{#+TEXINFO_CLASS} keyword accordingly in your document to activate it. - -@subsubheading Title and copyright page - -@cindex #+TEXINFO_PRINTED_TITLE -@cindex #+SUBTITLE -The default template includes a title page for hard copy output. The title -and author displayed on this page are extracted from, respectively, -@code{#+TITLE} and @code{#+AUTHOR} keywords (@pxref{Export settings}). It is -also possible to print a different, more specific, title with -@code{#+TEXINFO_PRINTED_TITLE} keyword, and add subtitles with -@code{#+SUBTITLE} keyword. Both expect raw Texinfo code in their value. - -@cindex #+SUBAUTHOR -Likewise, information brought by @code{#+AUTHOR} may not be enough. You can -include other authors with several @code{#+SUBAUTHOR} keywords. Values are -also expected to be written in Texinfo code. - -@example -#+AUTHOR: Jane Smith -#+SUBAUTHOR: John Doe -#+TEXINFO_PRINTED_TITLE: This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@} -@end example - -@cindex property, COPYING -Copying material is defined in a dedicated headline with a non-nil -@code{:COPYING:} property. The contents are inserted within -a @code{@@copying} command at the beginning of the document whereas the -heading itself does not appear in the structure of the document. - -Copyright information is printed on the back of the title page. - -@example -* Copying - :PROPERTIES: - :COPYING: t - :END: - - This is a short example of a complete Texinfo file, version 1.0. - - Copyright \copy 2014 Free Software Foundation, Inc. -@end example - -@subsubheading The Top node - -@cindex #+TEXINFO_DIR_CATEGORY -@cindex #+TEXINFO_DIR_TITLE -@cindex #+TEXINFO_DIR_DESC -You may ultimately want to install your new Info file to your system. You -can write an appropriate entry in the top level directory specifying its -category and title with, respectively, @code{#+TEXINFO_DIR_CATEGORY} and -@code{#+TEXINFO_DIR_TITLE}. Optionally, you can add a short description -using @code{#+TEXINFO_DIR_DESC}. The following example would write an entry -similar to Org's in the @samp{Top} node. - -@example -#+TEXINFO_DIR_CATEGORY: Emacs -#+TEXINFO_DIR_TITLE: Org Mode: (org) -#+TEXINFO_DIR_DESC: Outline-based notes management and organizer -@end example - -@node Headings and sectioning structure, Indices, Document preamble, Texinfo export -@subsection Headings and sectioning structure - -@vindex org-texinfo-classes -@vindex org-texinfo-default-class -@cindex #+TEXINFO_CLASS -@samp{texinfo} uses a pre-defined scheme, or class, to convert headlines into -Texinfo structuring commands. For example, a top level headline appears as -@code{@@chapter} if it should be numbered or as @code{@@unnumbered} -otherwise. If you need to use a different set of commands, e.g., to start -with @code{@@part} instead of @code{@@chapter}, install a new class in -@code{org-texinfo-classes}, then activate it with @code{#+TEXINFO_CLASS} -keyword. Export process defaults to @code{org-texinfo-default-class} when -there is no such keyword in the document. - -If a headline's level has no associated structuring command, or is below -a certain threshold @pxref{Export settings}, that headline becomes a list in -Texinfo output. - -@cindex property, APPENDIX -As an exception, a headline with a non-nil @code{:APPENDIX:} property becomes -an appendix, independently on its level and the class used. - -@cindex property, DESCRIPTION -Each regular sectioning structure creates a menu entry, named after the -heading. You can provide a different, e.g., shorter, title in -@code{:ALT_TITLE:} property (@pxref{Table of contents}). Optionally, you can -specify a description for the item in @code{:DESCRIPTION:} property. E.g., - -@example -* Controlling Screen Display - :PROPERTIES: - :ALT_TITLE: Display - :DESCRIPTION: Controlling Screen Display - :END: -@end example - -@node Indices, Quoting Texinfo code, Headings and sectioning structure, Texinfo export -@subsection Indices - -@cindex #+CINDEX -@cindex #+FINDEX -@cindex #+KINDEX -@cindex #+PINDEX -@cindex #+TINDEX -@cindex #+VINDEX -Index entries are created using dedicated keywords. @samp{texinfo} back-end -provides one for each predefined type: @code{#+CINDEX}, @code{#+FINDEX}, -@code{#+KINDEX}, @code{#+PINDEX}, @code{#+TINDEX} and @code{#+VINDEX}. For -custom indices, you can write raw Texinfo code (@pxref{Quoting Texinfo -code}). - -@example -#+CINDEX: Defining indexing entries -@end example - -@cindex property, INDEX -To generate an index, you need to set the @code{:INDEX:} property of -a headline to an appropriate abbreviation (e.g., @samp{cp} or @samp{vr}). -The headline is then exported as an unnumbered chapter or section command and -the index is inserted after its contents. - -@example -* Concept Index - :PROPERTIES: - :INDEX: cp - :END: -@end example - -@node Quoting Texinfo code, Texinfo specific attributes, Indices, Texinfo export -@subsection Quoting Texinfo code - -It is possible to insert raw Texinfo code using any of the following -constructs - -@cindex #+TEXINFO -@cindex #+BEGIN_TEXINFO -@example -Richard @@@@texinfo:@@sc@{@@@@Stallman@@@@texinfo:@}@@@@ commence' GNU. - -#+TEXINFO: @@need800 -This paragraph is preceded by... - -#+BEGIN_TEXINFO -@@auindex Johnson, Mark -@@auindex Lakoff, George -#+END_TEXINFO -@end example - -@node Texinfo specific attributes, An example, Quoting Texinfo code, Texinfo export -@subsection Texinfo specific attributes - -@cindex #+ATTR_TEXINFO -@samp{texinfo} back-end understands several attributes in plain lists and -tables. They must be specified using an @code{#+ATTR_TEXINFO} keyword, -written just above the list or table. - -@subsubheading Plain lists - -In Texinfo output, description lists appear as two-column tables, using the -default command @code{@@table}. You can use @code{@@ftable} or -@code{@@vtable}@footnote{For more information, @inforef{Two-column -Tables,,texinfo}.} instead with @code{:table-type} attribute. - -@vindex org-texinfo-def-table-markup -In any case, these constructs require a highlighting command for entries in -the list. You can provide one with @code{:indic} attribute. If you do not, -it defaults to the value stored in @code{org-texinfo-def-table-markup}, which -see. - -@example -#+ATTR_TEXINFO: :indic @@asis -- foo :: This is the text for /foo/, with no highlighting. -@end example - -@subsubheading Tables - -When exporting a table, column widths are deduced from the longest cell in -each column. You can also define them explicitly as fractions of the line -length, using @code{:columns} attribute. - -@example -#+ATTR_TEXINFO: :columns .5 .5 -| a cell | another cell | -@end example - -@node An example, , Texinfo specific attributes, Texinfo export -@subsection An example - -Here is a thorough example, taken from @inforef{GNU Sample Texts,,texinfo}. - -@smallexample -#+MACRO: version 2.0 -#+MACRO: updated last updated 4 March 2014 - -#+OPTIONS: ':t toc:t author:t email:t -#+TITLE: GNU Sample @{@{@{version@}@}@} -#+AUTHOR: A.U. Thor -#+EMAIL: bug-sample@@gnu.org -#+LANGUAGE: en - -#+TEXINFO_FILENAME: sample.info -#+TEXINFO_HEADER: @@syncodeindex pg cp - -#+TEXINFO_DIR_CATEGORY: Texinfo documentation system -#+TEXINFO_DIR_TITLE: sample: (sample) -#+TEXINFO_DIR_DESC: Invoking sample - -#+TEXINFO_PRINTED_TITLE: GNU Sample -#+SUBTITLE: for version 2.0, last updated 4 March 2014 - -* Copying - :PROPERTIES: - :COPYING: t - :END: - - This manual is for GNU Sample (version @{@{@{version@}@}@}, - @{@{@{updated@}@}@}), which is an example in the Texinfo documentation. - - Copyright @@@@texinfo:@@copyright@{@}@@@@ 2013 Free Software Foundation, - Inc. - - #+BEGIN_QUOTE - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation License, - Version 1.3 or any later version published by the Free Software - Foundation; with no Invariant Sections, with no Front-Cover Texts, - and with no Back-Cover Texts. A copy of the license is included in - the section entitled "GNU Free Documentation License". - #+END_QUOTE - -* Invoking sample - - #+PINDEX: sample - #+CINDEX: invoking @@command@{sample@} - - This is a sample manual. There is no sample program to invoke, but - if there were, you could see its basic usage and command line - options here. - -* GNU Free Documentation License - :PROPERTIES: - :APPENDIX: t - :END: - - #+TEXINFO: @@include fdl.texi - -* Index - :PROPERTIES: - :INDEX: cp - :END: -@end smallexample - -@node iCalendar export, Other built-in back-ends, Texinfo export, Exporting -@section iCalendar export -@cindex iCalendar export - -@vindex org-icalendar-include-todo -@vindex org-icalendar-use-deadline -@vindex org-icalendar-use-scheduled -@vindex org-icalendar-categories -@vindex org-icalendar-alarm-time -Some people use Org mode for keeping track of projects, but still prefer a -standard calendar application for anniversaries and appointments. In this -case it can be useful to show deadlines and other time-stamped items in Org -files in the calendar application. Org mode can export calendar information -in the standard iCalendar format. If you also want to have TODO entries -included in the export, configure the variable -@code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT, -and TODO items as VTODO@. It will also create events from deadlines that are -in non-TODO items. Deadlines and scheduling dates in TODO items will be used -to set the start and due dates for the TODO entry@footnote{See the variables -@code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}. -As categories, it will use the tags locally defined in the heading, and the -file/tree category@footnote{To add inherited tags or the TODO state, -configure the variable @code{org-icalendar-categories}.}. See the variable -@code{org-icalendar-alarm-time} for a way to assign alarms to entries with a -time. - -@vindex org-icalendar-store-UID -@cindex property, ID -The iCalendar standard requires each entry to have a globally unique -identifier (UID). Org creates these identifiers during export. If you set -the variable @code{org-icalendar-store-UID}, the UID will be stored in the -@code{:ID:} property of the entry and re-used next time you report this -entry. Since a single entry can give rise to multiple iCalendar entries (as -a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds -prefixes to the UID, depending on what triggered the inclusion of the entry. -In this way the UID remains unique, but a synchronization program can still -figure out from which entry all the different instances originate. - -@table @kbd -@orgcmd{C-c C-e c f,org-icalendar-export-to-ics} -Create iCalendar entries for the current buffer and store them in the same -directory, using a file extension @file{.ics}. -@orgcmd{C-c C-e c a, org-icalendar-export-agenda-files} -@vindex org-agenda-files -Like @kbd{C-c C-e c f}, but do this for all files in -@code{org-agenda-files}. For each of these files, a separate iCalendar -file will be written. -@orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files} -@vindex org-icalendar-combined-agenda-file -Create a single large iCalendar file from all files in -@code{org-agenda-files} and write it to the file given by -@code{org-icalendar-combined-agenda-file}. -@end table - -@vindex org-use-property-inheritance -@vindex org-icalendar-include-body -@cindex property, SUMMARY -@cindex property, DESCRIPTION -@cindex property, LOCATION -The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION -property can be inherited from higher in the hierarchy if you configure -@code{org-use-property-inheritance} accordingly.} properties if the selected -entries have them. If not, the summary will be derived from the headline, -and the description from the body (limited to -@code{org-icalendar-include-body} characters). - -How this calendar is best read and updated, depends on the application -you are using. The FAQ covers this issue. - -@node Other built-in back-ends, Export in foreign buffers, iCalendar export, Exporting -@section Other built-in back-ends -@cindex export back-ends, built-in -@vindex org-export-backends - -On top of the aforementioned back-ends, Org comes with other built-in ones: - -@itemize -@item @file{ox-man.el}: export to a man page. -@end itemize - -To activate these export back-end, customize @code{org-export-backends} or -load them directly with e.g., @code{(require 'ox-man)}. This will add new -keys in the export dispatcher (@pxref{The Export Dispatcher}). - -See the comment section of these files for more information on how to use -them. - -@node Export in foreign buffers, Advanced configuration, Other built-in back-ends, Exporting -@section Export in foreign buffers - -Most built-in back-ends come with a command to convert the selected region -into a selected format and replace this region by the exported output. Here -is a list of such conversion commands: - -@table @code -@item org-html-convert-region-to-html -Convert the selected region into HTML. -@item org-latex-convert-region-to-latex -Convert the selected region into @LaTeX{}. -@item org-texinfo-convert-region-to-texinfo -Convert the selected region into @code{Texinfo}. -@item org-md-convert-region-to-md -Convert the selected region into @code{MarkDown}. -@end table - -This is particularly useful for converting tables and lists in foreign -buffers. E.g., in an HTML buffer, you can turn on @code{orgstruct-mode}, then -use Org commands for editing a list, and finally select and convert the list -with @code{M-x org-html-convert-region-to-html RET}. - -@node Advanced configuration, , Export in foreign buffers, Exporting -@section Advanced configuration - -@subheading Hooks - -@vindex org-export-before-processing-hook -@vindex org-export-before-parsing-hook -Two hooks are run during the first steps of the export process. The first -one, @code{org-export-before-processing-hook} is called before expanding -macros, Babel code and include keywords in the buffer. The second one, -@code{org-export-before-parsing-hook}, as its name suggests, happens just -before parsing the buffer. Their main use is for heavy duties, that is -duties involving structural modifications of the document. For example, one -may want to remove every headline in the buffer during export. The following -code can achieve this: - -@lisp -@group -(defun my-headline-removal (backend) - "Remove all headlines in the current buffer. -BACKEND is the export back-end being used, as a symbol." - (org-map-entries - (lambda () (delete-region (point) (progn (forward-line) (point)))))) - -(add-hook 'org-export-before-parsing-hook 'my-headline-removal) -@end group -@end lisp - -Note that functions used in these hooks require a mandatory argument, -a symbol representing the back-end used. - -@subheading Filters - -@cindex Filters, exporting -Filters are lists of functions applied on a specific part of the output from -a given back-end. More explicitly, each time a back-end transforms an Org -object or element into another language, all functions within a given filter -type are called in turn on the string produced. The string returned by the -last function will be the one used in the final output. - -There are filters sets for each type of element or object, for plain text, -for the parse tree, for the export options and for the final output. They -are all named after the same scheme: @code{org-export-filter-TYPE-functions}, -where @code{TYPE} is the type targeted by the filter. Valid types are: - -@multitable @columnfractions .33 .33 .33 -@item bold -@tab babel-call -@tab center-block -@item clock -@tab code -@tab comment -@item comment-block -@tab diary-sexp -@tab drawer -@item dynamic-block -@tab entity -@tab example-block -@item export-block -@tab export-snippet -@tab final-output -@item fixed-width -@tab footnote-definition -@tab footnote-reference -@item headline -@tab horizontal-rule -@tab inline-babel-call -@item inline-src-block -@tab inlinetask -@tab italic -@item item -@tab keyword -@tab latex-environment -@item latex-fragment -@tab line-break -@tab link -@item node-property -@tab options -@tab paragraph -@item parse-tree -@tab plain-list -@tab plain-text -@item planning -@tab property-drawer -@tab quote-block -@item quote-section -@tab radio-target -@tab section -@item special-block -@tab src-block -@tab statistics-cookie -@item strike-through -@tab subscript -@tab superscript -@item table -@tab table-cell -@tab table-row -@item target -@tab timestamp -@tab underline -@item verbatim -@tab verse-block -@tab -@end multitable - -For example, the following snippet allows me to use non-breaking spaces in -the Org buffer and get them translated into @LaTeX{} without using the -@code{\nbsp} macro (where @code{_} stands for the non-breaking space): - -@lisp -@group -(defun my-latex-filter-nobreaks (text backend info) - "Ensure \" \" are properly handled in LaTeX export." - (when (org-export-derived-backend-p backend 'latex) - (replace-regexp-in-string " " "~" text))) - -(add-to-list 'org-export-filter-plain-text-functions - 'my-latex-filter-nobreaks) -@end group -@end lisp - -Three arguments must be provided to a filter: the code being changed, the -back-end used, and some information about the export process. You can safely -ignore the third argument for most purposes. Note the use of -@code{org-export-derived-backend-p}, which ensures that the filter will only -be applied when using @code{latex} back-end or any other back-end derived -from it (e.g., @code{beamer}). - -@subheading Extending an existing back-end - -This is obviously the most powerful customization, since the changes happen -at the parser level. Indeed, some export back-ends are built as extensions -of other ones (e.g. Markdown back-end an extension of HTML back-end). - -Extending a back-end means that if an element type is not transcoded by the -new back-end, it will be handled by the original one. Hence you can extend -specific parts of a back-end without too much work. - -As an example, imagine we want the @code{ascii} back-end to display the -language used in a source block, when it is available, but only when some -attribute is non-@code{nil}, like the following: - -@example -#+ATTR_ASCII: :language t -@end example - -Because that back-end is lacking in that area, we are going to create a new -back-end, @code{my-ascii} that will do the job. - -@lisp -@group -(defun my-ascii-src-block (src-block contents info) - "Transcode a SRC-BLOCK element from Org to ASCII. -CONTENTS is nil. INFO is a plist used as a communication -channel." - (if (not (org-export-read-attribute :attr_ascii src-block :language)) - (org-export-with-backend 'ascii src-block contents info) - (concat - (format ",--[ %s ]--\n%s`----" - (org-element-property :language src-block) - (replace-regexp-in-string - "^" "| " - (org-element-normalize-string - (org-export-format-code-default src-block info))))))) - -(org-export-define-derived-backend 'my-ascii 'ascii - :translate-alist '((src-block . my-ascii-src-block))) -@end group -@end lisp - -The @code{my-ascii-src-block} function looks at the attribute above the -element. If it isn't true, it gives hand to the @code{ascii} back-end. -Otherwise, it creates a box around the code, leaving room for the language. -A new back-end is then created. It only changes its behavior when -translating @code{src-block} type element. Now, all it takes to use the new -back-end is calling the following from an Org buffer: - -@smalllisp -(org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*") -@end smalllisp - -It is obviously possible to write an interactive function for this, install -it in the export dispatcher menu, and so on. - -@node Publishing, Working With Source Code, Exporting, Top -@chapter Publishing -@cindex publishing - -Org includes a publishing management system that allows you to configure -automatic HTML conversion of @emph{projects} composed of interlinked org -files. You can also configure Org to automatically upload your exported HTML -pages and related attachments, such as images and source code files, to a web -server. - -You can also use Org to convert files into PDF, or even combine HTML and PDF -conversion so that files are available in both formats on the server. - -Publishing has been contributed to Org by David O'Toole. - -@menu -* Configuration:: Defining projects -* Uploading files:: How to get files up on the server -* Sample configuration:: Example projects -* Triggering publication:: Publication commands -@end menu - -@node Configuration, Uploading files, Publishing, Publishing -@section Configuration - -Publishing needs significant configuration to specify files, destination -and many other properties of a project. - -@menu -* Project alist:: The central configuration variable -* Sources and destinations:: From here to there -* Selecting files:: What files are part of the project? -* Publishing action:: Setting the function doing the publishing -* Publishing options:: Tweaking HTML/@LaTeX{} export -* Publishing links:: Which links keep working after publishing? -* Sitemap:: Generating a list of all pages -* Generating an index:: An index that reaches across pages -@end menu - -@node Project alist, Sources and destinations, Configuration, Configuration -@subsection The variable @code{org-publish-project-alist} -@cindex org-publish-project-alist -@cindex projects, for publishing - -@vindex org-publish-project-alist -Publishing is configured almost entirely through setting the value of one -variable, called @code{org-publish-project-alist}. Each element of the list -configures one project, and may be in one of the two following forms: - -@lisp - ("project-name" :property value :property value ...) - @r{i.e., a well-formed property list with alternating keys and values} -@r{or} - ("project-name" :components ("project-name" "project-name" ...)) - -@end lisp - -In both cases, projects are configured by specifying property values. A -project defines the set of files that will be published, as well as the -publishing configuration to use when publishing those files. When a project -takes the second form listed above, the individual members of the -@code{:components} property are taken to be sub-projects, which group -together files requiring different publishing options. When you publish such -a ``meta-project'', all the components will also be published, in the -sequence given. - -@node Sources and destinations, Selecting files, Project alist, Configuration -@subsection Sources and destinations for files -@cindex directories, for publishing - -Most properties are optional, but some should always be set. In -particular, Org needs to know where to look for source files, -and where to put published files. - -@multitable @columnfractions 0.3 0.7 -@item @code{:base-directory} -@tab Directory containing publishing source files -@item @code{:publishing-directory} -@tab Directory where output files will be published. You can directly -publish to a web server using a file name syntax appropriate for -the Emacs @file{tramp} package. Or you can publish to a local directory and -use external tools to upload your website (@pxref{Uploading files}). -@item @code{:preparation-function} -@tab Function or list of functions to be called before starting the -publishing process, for example, to run @code{make} for updating files to be -published. The project property list is scoped into this call as the -variable @code{project-plist}. -@item @code{:completion-function} -@tab Function or list of functions called after finishing the publishing -process, for example, to change permissions of the resulting files. The -project property list is scoped into this call as the variable -@code{project-plist}. -@end multitable -@noindent - -@node Selecting files, Publishing action, Sources and destinations, Configuration -@subsection Selecting files -@cindex files, selecting for publishing - -By default, all files with extension @file{.org} in the base directory -are considered part of the project. This can be modified by setting the -properties -@multitable @columnfractions 0.25 0.75 -@item @code{:base-extension} -@tab Extension (without the dot!) of source files. This actually is a -regular expression. Set this to the symbol @code{any} if you want to get all -files in @code{:base-directory}, even without extension. - -@item @code{:exclude} -@tab Regular expression to match file names that should not be -published, even though they have been selected on the basis of their -extension. - -@item @code{:include} -@tab List of files to be included regardless of @code{:base-extension} -and @code{:exclude}. - -@item @code{:recursive} -@tab non-@code{nil} means, check base-directory recursively for files to publish. -@end multitable - -@node Publishing action, Publishing options, Selecting files, Configuration -@subsection Publishing action -@cindex action, for publishing - -Publishing means that a file is copied to the destination directory and -possibly transformed in the process. The default transformation is to export -Org files as HTML files, and this is done by the function -@code{org-html-publish-to-html}, which calls the HTML exporter (@pxref{HTML -export}). But you also can publish your content as PDF files using -@code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc., -using the corresponding functions. - -If you want to publish the Org file as an @code{.org} file but with the -@i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the -function @code{org-org-publish-to-org}. This will produce @file{file.org} -and put it in the publishing directory. If you want a htmlized version of -this file, set the parameter @code{:htmlized-source} to @code{t}, it will -produce @file{file.org.html} in the publishing directory@footnote{If the -publishing directory is the same than the source directory, @file{file.org} -will be exported as @file{file.org.org}, so probably don't want to do this.}. - -Other files like images only need to be copied to the publishing destination. -For this you can use @code{org-publish-attachment}. For non-org files, you -always need to specify the publishing function: - -@multitable @columnfractions 0.3 0.7 -@item @code{:publishing-function} -@tab Function executing the publication of a file. This may also be a -list of functions, which will all be called in turn. -@item @code{:htmlized-source} -@tab non-@code{nil} means, publish htmlized source. -@end multitable - -The function must accept three arguments: a property list containing at least -a @code{:publishing-directory} property, the name of the file to be published -and the path to the publishing directory of the output file. It should take -the specified file, make the necessary transformation (if any) and place the -result into the destination folder. - -@node Publishing options, Publishing links, Publishing action, Configuration -@subsection Options for the exporters -@cindex options, for publishing - -The property list can be used to set many export options for the exporters. -In most cases, these properties correspond to user variables in Org. The -first table below lists these properties along with the variable they belong -to. The second table list HTML specific properties. See the documentation -string of these options for details. - -@vindex org-display-custom-times -@vindex org-export-default-language -@vindex org-export-exclude-tags -@vindex org-export-headline-levels -@vindex org-export-preserve-breaks -@vindex org-export-publishing-directory -@vindex org-export-select-tags -@vindex org-export-with-archived-trees -@vindex org-export-with-author -@vindex org-export-with-creator -@vindex org-export-with-drawers -@vindex org-export-with-email -@vindex org-export-with-emphasize -@vindex org-export-with-fixed-width -@vindex org-export-with-footnotes -@vindex org-export-with-latex -@vindex org-export-with-planning -@vindex org-export-with-priority -@vindex org-export-with-section-numbers -@vindex org-export-with-special-strings -@vindex org-export-with-sub-superscripts -@vindex org-export-with-tables -@vindex org-export-with-tags -@vindex org-export-with-tasks -@vindex org-export-with-timestamps -@vindex org-export-with-toc -@vindex org-export-with-todo-keywords -@vindex user-mail-address - -@multitable @columnfractions 0.32 0.68 -@item @code{:archived-trees} @tab @code{org-export-with-archived-trees} -@item @code{:exclude-tags} @tab @code{org-export-exclude-tags} -@item @code{:headline-levels} @tab @code{org-export-headline-levels} -@item @code{:language} @tab @code{org-export-default-language} -@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks} -@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} -@item @code{:select-tags} @tab @code{org-export-select-tags} -@item @code{:with-author} @tab @code{org-export-with-author} -@item @code{:with-creator} @tab @code{org-export-with-creator} -@item @code{:with-drawers} @tab @code{org-export-with-drawers} -@item @code{:with-email} @tab @code{org-export-with-email} -@item @code{:with-emphasize} @tab @code{org-export-with-emphasize} -@item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width} -@item @code{:with-footnotes} @tab @code{org-export-with-footnotes} -@item @code{:with-latex} @tab @code{org-export-with-latex} -@item @code{:with-planning} @tab @code{org-export-with-planning} -@item @code{:with-priority} @tab @code{org-export-with-priority} -@item @code{:with-special-strings} @tab @code{org-export-with-special-strings} -@item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts} -@item @code{:with-tables} @tab @code{org-export-with-tables} -@item @code{:with-tags} @tab @code{org-export-with-tags} -@item @code{:with-tasks} @tab @code{org-export-with-tasks} -@item @code{:with-timestamps} @tab @code{org-export-with-timestamps} -@item @code{:with-toc} @tab @code{org-export-with-toc} -@item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords} -@end multitable - -@vindex org-html-doctype -@vindex org-html-container-element -@vindex org-html-html5-fancy -@vindex org-html-xml-declaration -@vindex org-html-link-up -@vindex org-html-link-home -@vindex org-html-link-org-files-as-html -@vindex org-html-link-use-abs-url -@vindex org-html-head -@vindex org-html-head-extra -@vindex org-html-inline-images -@vindex org-html-extension -@vindex org-html-preamble -@vindex org-html-postamble -@vindex org-html-table-default-attributes -@vindex org-html-table-row-tags -@vindex org-html-head-include-default-style -@vindex org-html-head-include-scripts -@multitable @columnfractions 0.32 0.68 -@item @code{:html-doctype} @tab @code{org-html-doctype} -@item @code{:html-container} @tab @code{org-html-container-element} -@item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy} -@item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration} -@item @code{:html-link-up} @tab @code{org-html-link-up} -@item @code{:html-link-home} @tab @code{org-html-link-home} -@item @code{:html-link-org-as-html} @tab @code{org-html-link-org-files-as-html} -@item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url} -@item @code{:html-head} @tab @code{org-html-head} -@item @code{:html-head-extra} @tab @code{org-html-head-extra} -@item @code{:html-inline-images} @tab @code{org-html-inline-images} -@item @code{:html-extension} @tab @code{org-html-extension} -@item @code{:html-preamble} @tab @code{org-html-preamble} -@item @code{:html-postamble} @tab @code{org-html-postamble} -@item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes} -@item @code{:html-table-row-tags} @tab @code{org-html-table-row-tags} -@item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style} -@item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts} -@end multitable - -Most of the @code{org-export-with-*} variables have the same effect in each -exporter. - -@vindex org-publish-project-alist -When a property is given a value in @code{org-publish-project-alist}, its -setting overrides the value of the corresponding user variable (if any) -during publishing. Options set within a file (@pxref{Export settings}), -however, override everything. - -@node Publishing links, Sitemap, Publishing options, Configuration -@subsection Links between published files -@cindex links, publishing - -To create a link from one Org file to another, you would use something like -@samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org.} -(@pxref{Hyperlinks}). When published, this link becomes a link to -@file{foo.html}. You can thus interlink the pages of your "org web" project -and the links will work as expected when you publish them to HTML@. If you -also publish the Org source file and want to link to it, use an @code{http:} -link instead of a @code{file:} link, because @code{file:} links are converted -to link to the corresponding @file{html} file. - -You may also link to related files, such as images. Provided you are careful -with relative file names, and provided you have also configured Org to upload -the related files, these links will work too. See @ref{Complex example}, for -an example of this usage. - -@node Sitemap, Generating an index, Publishing links, Configuration -@subsection Generating a sitemap -@cindex sitemap, of published pages - -The following properties may be used to control publishing of -a map of files for a given project. - -@multitable @columnfractions 0.35 0.65 -@item @code{:auto-sitemap} -@tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project} -or @code{org-publish-all}. - -@item @code{:sitemap-filename} -@tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which -becomes @file{sitemap.html}). - -@item @code{:sitemap-title} -@tab Title of sitemap page. Defaults to name of file. - -@item @code{:sitemap-function} -@tab Plug-in function to use for generation of the sitemap. -Defaults to @code{org-publish-org-sitemap}, which generates a plain list -of links to all files in the project. - -@item @code{:sitemap-sort-folders} -@tab Where folders should appear in the sitemap. Set this to @code{first} -(default) or @code{last} to display folders first or last, -respectively. Any other value will mix files and folders. - -@item @code{:sitemap-sort-files} -@tab How the files are sorted in the site map. Set this to -@code{alphabetically} (default), @code{chronologically} or -@code{anti-chronologically}. @code{chronologically} sorts the files with -older date first while @code{anti-chronologically} sorts the files with newer -date first. @code{alphabetically} sorts the files alphabetically. The date of -a file is retrieved with @code{org-publish-find-date}. - -@item @code{:sitemap-ignore-case} -@tab Should sorting be case-sensitive? Default @code{nil}. - -@item @code{:sitemap-file-entry-format} -@tab With this option one can tell how a sitemap's entry is formatted in the -sitemap. This is a format string with some escape sequences: @code{%t} stands -for the title of the file, @code{%a} stands for the author of the file and -@code{%d} stands for the date of the file. The date is retrieved with the -@code{org-publish-find-date} function and formatted with -@code{org-publish-sitemap-date-format}. Default @code{%t}. - -@item @code{:sitemap-date-format} -@tab Format string for the @code{format-time-string} function that tells how -a sitemap entry's date is to be formatted. This property bypasses -@code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}. - -@item @code{:sitemap-sans-extension} -@tab When non-@code{nil}, remove filenames' extensions from the generated sitemap. -Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}). -Defaults to @code{nil}. - -@end multitable - -@node Generating an index, , Sitemap, Configuration -@subsection Generating an index -@cindex index, in a publishing project - -Org mode can generate an index across the files of a publishing project. - -@multitable @columnfractions 0.25 0.75 -@item @code{:makeindex} -@tab When non-@code{nil}, generate in index in the file @file{theindex.org} and -publish it as @file{theindex.html}. -@end multitable - -The file will be created when first publishing a project with the -@code{:makeindex} set. The file only contains a statement @code{#+INCLUDE: -"theindex.inc"}. You can then build around this include statement by adding -a title, style information, etc. - -@node Uploading files, Sample configuration, Configuration, Publishing -@section Uploading files -@cindex rsync -@cindex unison - -For those people already utilizing third party sync tools such as -@command{rsync} or @command{unison}, it might be preferable not to use the built in -@i{remote} publishing facilities of Org mode which rely heavily on -Tramp. Tramp, while very useful and powerful, tends not to be -so efficient for multiple file transfer and has been known to cause problems -under heavy usage. - -Specialized synchronization utilities offer several advantages. In addition -to timestamp comparison, they also do content and permissions/attribute -checks. For this reason you might prefer to publish your web to a local -directory (possibly even @i{in place} with your Org files) and then use -@file{unison} or @file{rsync} to do the synchronization with the remote host. - -Since Unison (for example) can be configured as to which files to transfer to -a certain remote destination, it can greatly simplify the project publishing -definition. Simply keep all files in the correct location, process your Org -files with @code{org-publish} and let the synchronization tool do the rest. -You do not need, in this scenario, to include attachments such as @file{jpg}, -@file{css} or @file{gif} files in the project definition since the 3rd party -tool syncs them. - -Publishing to a local directory is also much faster than to a remote one, so -that you can afford more easily to republish entire projects. If you set -@code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main -benefit of re-including any changed external files such as source example -files you might include with @code{#+INCLUDE:}. The timestamp mechanism in -Org is not smart enough to detect if included files have been modified. - -@node Sample configuration, Triggering publication, Uploading files, Publishing -@section Sample configuration - -Below we provide two example configurations. The first one is a simple -project publishing only a set of Org files. The second example is -more complex, with a multi-component project. - -@menu -* Simple example:: One-component publishing -* Complex example:: A multi-component publishing example -@end menu - -@node Simple example, Complex example, Sample configuration, Sample configuration -@subsection Example: simple publishing configuration - -This example publishes a set of Org files to the @file{public_html} -directory on the local machine. - -@lisp -(setq org-publish-project-alist - '(("org" - :base-directory "~/org/" - :publishing-directory "~/public_html" - :section-numbers nil - :with-toc nil - :html-head ""))) -@end lisp - -@node Complex example, , Simple example, Sample configuration -@subsection Example: complex publishing configuration - -This more complicated example publishes an entire website, including -Org files converted to HTML, image files, Emacs Lisp source code, and -style sheets. The publishing directory is remote and private files are -excluded. - -To ensure that links are preserved, care should be taken to replicate -your directory structure on the web server, and to use relative file -paths. For example, if your Org files are kept in @file{~/org} and your -publishable images in @file{~/images}, you would link to an image with -@c -@example -file:../images/myimage.png -@end example -@c -On the web server, the relative path to the image should be the -same. You can accomplish this by setting up an "images" folder in the -right place on the web server, and publishing images to it. - -@lisp -(setq org-publish-project-alist - '(("orgfiles" - :base-directory "~/org/" - :base-extension "org" - :publishing-directory "/ssh:user@@host:~/html/notebook/" - :publishing-function org-html-publish-to-html - :exclude "PrivatePage.org" ;; regexp - :headline-levels 3 - :section-numbers nil - :with-toc nil - :html-head "" - :html-preamble t) - - ("images" - :base-directory "~/images/" - :base-extension "jpg\\|gif\\|png" - :publishing-directory "/ssh:user@@host:~/html/images/" - :publishing-function org-publish-attachment) - - ("other" - :base-directory "~/other/" - :base-extension "css\\|el" - :publishing-directory "/ssh:user@@host:~/html/other/" - :publishing-function org-publish-attachment) - ("website" :components ("orgfiles" "images" "other")))) -@end lisp - -@node Triggering publication, , Sample configuration, Publishing -@section Triggering publication - -Once properly configured, Org can publish with the following commands: - -@table @kbd -@orgcmd{C-c C-e P x,org-publish} -Prompt for a specific project and publish all files that belong to it. -@orgcmd{C-c C-e P p,org-publish-current-project} -Publish the project containing the current file. -@orgcmd{C-c C-e P f,org-publish-current-file} -Publish only the current file. -@orgcmd{C-c C-e P a,org-publish-all} -Publish every project. -@end table - -@vindex org-publish-use-timestamps-flag -Org uses timestamps to track when a file has changed. The above functions -normally only publish changed files. You can override this and force -publishing of all files by giving a prefix argument to any of the commands -above, or by customizing the variable @code{org-publish-use-timestamps-flag}. -This may be necessary in particular if files include other files via -@code{#+SETUPFILE:} or @code{#+INCLUDE:}. - -@comment node-name, next, previous, up -@comment Working With Source Code, Miscellaneous, Publishing, Top - -@node Working With Source Code, Miscellaneous, Publishing, Top -@chapter Working with source code -@cindex Schulte, Eric -@cindex Davison, Dan -@cindex source code, working with - -Source code can be included in Org mode documents using a @samp{src} block, -e.g.: - -@example -#+BEGIN_SRC emacs-lisp - (defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) -#+END_SRC -@end example - -Org mode provides a number of features for working with live source code, -including editing of code blocks in their native major-mode, evaluation of -code blocks, converting code blocks into source files (known as @dfn{tangling} -in literate programming), and exporting code blocks and their -results in several formats. This functionality was contributed by Eric -Schulte and Dan Davison, and was originally named Org-babel. - -The following sections describe Org mode's code block handling facilities. - -@menu -* Structure of code blocks:: Code block syntax described -* Editing source code:: Language major-mode editing -* Exporting code blocks:: Export contents and/or results -* Extracting source code:: Create pure source code files -* Evaluating code blocks:: Place results of evaluation in the Org mode buffer -* Library of Babel:: Use and contribute to a library of useful code blocks -* Languages:: List of supported code block languages -* Header arguments:: Configure code block functionality -* Results of evaluation:: How evaluation results are handled -* Noweb reference syntax:: Literate programming in Org mode -* Key bindings and useful functions:: Work quickly with code blocks -* Batch execution:: Call functions from the command line -@end menu - -@comment node-name, next, previous, up -@comment Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code - -@node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code -@section Structure of code blocks -@cindex code block, structure -@cindex source code, block structure -@cindex #+NAME -@cindex #+BEGIN_SRC - -Live code blocks can be specified with a @samp{src} block or -inline.@footnote{Note that @samp{src} blocks may be inserted using Org mode's -@ref{Easy Templates} system} The structure of a @samp{src} block is - -@example -#+NAME: -#+BEGIN_SRC
- -#+END_SRC -@end example - -The @code{#+NAME:} line is optional, and can be used to name the code -block. Live code blocks require that a language be specified on the -@code{#+BEGIN_SRC} line. Switches and header arguments are optional. -@cindex source code, inline - -Live code blocks can also be specified inline using - -@example -src_@{@} -@end example - -or - -@example -src_[
]@{@} -@end example - -@table @code -@item <#+NAME: name> -This line associates a name with the code block. This is similar to the -@code{#+NAME: Name} lines that can be used to name tables in Org mode -files. Referencing the name of a code block makes it possible to evaluate -the block from other places in the file, from other files, or from Org mode -table formulas (see @ref{The spreadsheet}). Names are assumed to be unique -and the behavior of Org mode when two or more blocks share the same name is -undefined. -@cindex #+NAME -@item -The language of the code in the block (see @ref{Languages}). -@cindex source code, language -@item -Optional switches control code block export (see the discussion of switches in -@ref{Literal examples}) -@cindex source code, switches -@item
-Optional header arguments control many aspects of evaluation, export and -tangling of code blocks (see @ref{Header arguments}). -Header arguments can also be set on a per-buffer or per-subtree -basis using properties. -@item source code, header arguments -@item -Source code in the specified language. -@end table - -@comment node-name, next, previous, up -@comment Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code - -@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code -@section Editing source code -@cindex code block, editing -@cindex source code, editing - -@vindex org-edit-src-auto-save-idle-delay -@vindex org-edit-src-turn-on-auto-save -@kindex C-c ' -Use @kbd{C-c '} to edit the current code block. This brings up a language -major-mode edit buffer containing the body of the code block. Manually -saving this buffer with @key{C-x C-s} will write the contents back to the Org -buffer. You can also set @code{org-edit-src-auto-save-idle-delay} to save the -base buffer after some idle delay, or @code{org-edit-src-turn-on-auto-save} -to auto-save this buffer into a separate file using @code{auto-save-mode}. -Use @kbd{C-c '} again to exit. - -The @code{org-src-mode} minor mode will be active in the edit buffer. The -following variables can be used to configure the behavior of the edit -buffer. See also the customization group @code{org-edit-structure} for -further configuration options. - -@table @code -@item org-src-lang-modes -If an Emacs major-mode named @code{-mode} exists, where -@code{} is the language named in the header line of the code block, -then the edit buffer will be placed in that major-mode. This variable -can be used to map arbitrary language names to existing major modes. -@item org-src-window-setup -Controls the way Emacs windows are rearranged when the edit buffer is created. -@item org-src-preserve-indentation -By default, the value is @code{nil}, which means that when code blocks are -evaluated during export or tangled, they are re-inserted into the code block, -which may replace sequences of spaces with tab characters. When non-nil, -whitespace in code blocks will be preserved during export or tangling, -exactly as it appears. This variable is especially useful for tangling -languages such as Python, in which whitespace indentation in the output is -critical. -@item org-src-ask-before-returning-to-edit-buffer -By default, Org will ask before returning to an open edit buffer. Set this -variable to @code{nil} to switch without asking. -@end table - -To turn on native code fontification in the @emph{Org} buffer, configure the -variable @code{org-src-fontify-natively}. - -@comment node-name, next, previous, up -@comment Exporting code blocks, Extracting source code, Editing source code, Working With Source Code - -@node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code -@section Exporting code blocks -@cindex code block, exporting -@cindex source code, exporting - -It is possible to export the @emph{code} of code blocks, the @emph{results} -of code block evaluation, @emph{both} the code and the results of code block -evaluation, or @emph{none}. For most languages, the default exports code. -However, for some languages (e.g., @code{ditaa}) the default exports the -results of code block evaluation. For information on exporting code block -bodies, see @ref{Literal examples}. - -The @code{:exports} header argument can be used to specify export -behavior: - -@subsubheading Header arguments: - -@table @code -@item :exports code -The default in most languages. The body of the code block is exported, as -described in @ref{Literal examples}. -@item :exports results -The code block will be evaluated and the results will be placed in the -Org mode buffer for export, either updating previous results of the code -block located anywhere in the buffer or, if no previous results exist, -placing the results immediately after the code block. The body of the code -block will not be exported. -@item :exports both -Both the code block and its results will be exported. -@item :exports none -Neither the code block nor its results will be exported. -@end table - -It is possible to inhibit the evaluation of code blocks during export. -Setting the @code{org-export-babel-evaluate} variable to @code{nil} will -ensure that no code blocks are evaluated as part of the export process. This -can be useful in situations where potentially untrusted Org mode files are -exported in an automated fashion, for example when Org mode is used as the -markup language for a wiki. It is also possible to set this variable to -@code{'inline-only}. In that case, only inline code blocks will be -evaluated, in order to insert their results. Non-inline code blocks are -assumed to have their results already inserted in the buffer by manual -evaluation. This setting is useful to avoid expensive recalculations during -export, not to provide security. - -@comment node-name, next, previous, up -@comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code -@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code -@section Extracting source code -@cindex tangling -@cindex source code, extracting -@cindex code block, extracting source code - -Creating pure source code files by extracting code from source blocks is -referred to as ``tangling''---a term adopted from the literate programming -community. During ``tangling'' of code blocks their bodies are expanded -using @code{org-babel-expand-src-block} which can expand both variable and -``noweb'' style references (see @ref{Noweb reference syntax}). - -@subsubheading Header arguments - -@table @code -@item :tangle no -The default. The code block is not included in the tangled output. -@item :tangle yes -Include the code block in the tangled output. The output file name is the -name of the org file with the extension @samp{.org} replaced by the extension -for the block language. -@item :tangle filename -Include the code block in the tangled output to file @samp{filename}. -@end table - -@kindex C-c C-v t -@subsubheading Functions - -@table @code -@item org-babel-tangle -Tangle the current file. Bound to @kbd{C-c C-v t}. - -With prefix argument only tangle the current code block. -@item org-babel-tangle-file -Choose a file to tangle. Bound to @kbd{C-c C-v f}. -@end table - -@subsubheading Hooks - -@table @code -@item org-babel-post-tangle-hook -This hook is run from within code files tangled by @code{org-babel-tangle}. -Example applications could include post-processing, compilation or evaluation -of tangled code files. -@end table - -@subsubheading Jumping between code and Org - -When tangling code from an Org-mode buffer to a source code file, you'll -frequently find yourself viewing the file of tangled source code (e.g., many -debuggers point to lines of the source code file). It is useful to be able -to navigate from the tangled source to the Org-mode buffer from which the -code originated. - -The @code{org-babel-tangle-jump-to-org} function provides this jumping from -code to Org-mode functionality. Two header arguments are required for -jumping to work, first the @code{padline} (@ref{padline}) option must be set -to true (the default setting), second the @code{comments} (@ref{comments}) -header argument must be set to @code{links}, which will insert comments into -the source code buffer which point back to the original Org-mode file. - -@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code -@section Evaluating code blocks -@cindex code block, evaluating -@cindex source code, evaluating -@cindex #+RESULTS - -Code blocks can be evaluated@footnote{Whenever code is evaluated there is a -potential for that code to do harm. Org mode provides safeguards to ensure -that code is only evaluated after explicit confirmation from the user. For -information on these safeguards (and on how to disable them) see @ref{Code -evaluation security}.} and the results of evaluation optionally placed in the -Org mode buffer. The results of evaluation are placed following a line that -begins by default with @code{#+RESULTS} and optionally a cache identifier -and/or the name of the evaluated code block. The default value of -@code{#+RESULTS} can be changed with the customizable variable -@code{org-babel-results-keyword}. - -By default, the evaluation facility is only enabled for Lisp code blocks -specified as @code{emacs-lisp}. However, source code blocks in many languages -can be evaluated within Org mode (see @ref{Languages} for a list of supported -languages and @ref{Structure of code blocks} for information on the syntax -used to define a code block). - -@kindex C-c C-c -There are a number of ways to evaluate code blocks. The simplest is to press -@kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The -option @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used to remove code -evaluation from the @kbd{C-c C-c} key binding.}. This will call the -@code{org-babel-execute-src-block} function to evaluate the block and insert -its results into the Org mode buffer. -@cindex #+CALL - -It is also possible to evaluate named code blocks from anywhere in an Org -mode buffer or an Org mode table. Live code blocks located in the current -Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel}) -can be executed. Named code blocks can be executed with a separate -@code{#+CALL:} line or inline within a block of text. - -The syntax of the @code{#+CALL:} line is - -@example -#+CALL: () -#+CALL: []() -@end example - -The syntax for inline evaluation of named code blocks is - -@example -... call_() ... -... call_[]()[] ... -@end example - -@table @code -@item -The name of the code block to be evaluated (see @ref{Structure of code blocks}). -@item -Arguments specified in this section will be passed to the code block. These -arguments use standard function call syntax, rather than -header argument syntax. For example, a @code{#+CALL:} line that passes the -number four to a code block named @code{double}, which declares the header -argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}. -@item -Inside header arguments are passed through and applied to the named code -block. These arguments use header argument syntax rather than standard -function call syntax. Inside header arguments affect how the code block is -evaluated. For example, @code{[:results output]} will collect the results of -everything printed to @code{STDOUT} during execution of the code block. -@item -End header arguments are applied to the calling instance and do not affect -evaluation of the named code block. They affect how the results are -incorporated into the Org mode buffer and how the call line is exported. For -example, @code{:results html} will insert the results of the call line -evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block. - -For more examples of passing header arguments to @code{#+CALL:} lines see -@ref{Header arguments in function calls}. -@end table - -@node Library of Babel, Languages, Evaluating code blocks, Working With Source Code -@section Library of Babel -@cindex babel, library of -@cindex source code, library -@cindex code block, library - -The ``Library of Babel'' consists of code blocks that can be called from any -Org mode file. Code blocks defined in the ``Library of Babel'' can be called -remotely as if they were in the current Org mode buffer (see @ref{Evaluating -code blocks} for information on the syntax of remote code block evaluation). - - -The central repository of code blocks in the ``Library of Babel'' is housed -in an Org mode file located in the @samp{contrib} directory of Org mode. - -Users can add code blocks they believe to be generally useful to their -``Library of Babel.'' The code blocks can be stored in any Org mode file and -then loaded into the library with @code{org-babel-lob-ingest}. - - -@kindex C-c C-v i -Code blocks located in any Org mode file can be loaded into the ``Library of -Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v -i}. - -@node Languages, Header arguments, Library of Babel, Working With Source Code -@section Languages -@cindex babel, languages -@cindex source code, languages -@cindex code block, languages - -Code blocks in the following languages are supported. - -@multitable @columnfractions 0.28 0.3 0.22 0.2 -@item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier} -@item Asymptote @tab asymptote @tab Awk @tab awk -@item Emacs Calc @tab calc @tab C @tab C -@item C++ @tab C++ @tab Clojure @tab clojure -@item CSS @tab css @tab ditaa @tab ditaa -@item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp -@item gnuplot @tab gnuplot @tab Haskell @tab haskell -@item Java @tab java @tab @tab -@item Javascript @tab js @tab LaTeX @tab latex -@item Ledger @tab ledger @tab Lisp @tab lisp -@item Lilypond @tab lilypond @tab MATLAB @tab matlab -@item Mscgen @tab mscgen @tab Objective Caml @tab ocaml -@item Octave @tab octave @tab Org mode @tab org -@item Oz @tab oz @tab Perl @tab perl -@item Plantuml @tab plantuml @tab Python @tab python -@item R @tab R @tab Ruby @tab ruby -@item Sass @tab sass @tab Scheme @tab scheme -@item GNU Screen @tab screen @tab shell @tab sh -@item SQL @tab sql @tab SQLite @tab sqlite -@end multitable - -Language-specific documentation is available for some languages. If -available, it can be found at -@uref{http://orgmode.org/worg/org-contrib/babel/languages.html}. - -The option @code{org-babel-load-languages} controls which languages are -enabled for evaluation (by default only @code{emacs-lisp} is enabled). This -variable can be set using the customization interface or by adding code like -the following to your emacs configuration. - -@quotation -The following disables @code{emacs-lisp} evaluation and enables evaluation of -@code{R} code blocks. -@end quotation - -@lisp -(org-babel-do-load-languages - 'org-babel-load-languages - '((emacs-lisp . nil) - (R . t))) -@end lisp - -It is also possible to enable support for a language by loading the related -elisp file with @code{require}. - -@quotation -The following adds support for evaluating @code{clojure} code blocks. -@end quotation - -@lisp -(require 'ob-clojure) -@end lisp - -@node Header arguments, Results of evaluation, Languages, Working With Source Code -@section Header arguments -@cindex code block, header arguments -@cindex source code, block header arguments - -Code block functionality can be configured with header arguments. This -section provides an overview of the use of header arguments, and then -describes each header argument in detail. - -@menu -* Using header arguments:: Different ways to set header arguments -* Specific header arguments:: List of header arguments -@end menu - -@node Using header arguments, Specific header arguments, Header arguments, Header arguments -@subsection Using header arguments - -The values of header arguments can be set in several way. When the header -arguments in each layer have been determined, they are combined in order from -the first, least specific (having the lowest priority) up to the last, most -specific (having the highest priority). A header argument with a higher -priority replaces the same header argument specified at lower priority. -@menu -* System-wide header arguments:: Set global default values -* Language-specific header arguments:: Set default values by language -* Header arguments in Org mode properties:: Set default values for a buffer or heading -* Language-specific header arguments in Org mode properties:: Set language-specific default values for a buffer or heading -* Code block specific header arguments:: The most common way to set values -* Header arguments in function calls:: The most specific level -@end menu - - -@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments -@subsubheading System-wide header arguments -@vindex org-babel-default-header-args -System-wide values of header arguments can be specified by adapting the -@code{org-babel-default-header-args} variable: - -@example -:session => "none" -:results => "replace" -:exports => "code" -:cache => "no" -:noweb => "no" -@end example - -For example, the following example could be used to set the default value of -@code{:noweb} header arguments to @code{yes}. This would have the effect of -expanding @code{:noweb} references by default when evaluating source code -blocks. - -@lisp -(setq org-babel-default-header-args - (cons '(:noweb . "yes") - (assq-delete-all :noweb org-babel-default-header-args))) -@end lisp - -@node Language-specific header arguments, Header arguments in Org mode properties, System-wide header arguments, Using header arguments -@subsubheading Language-specific header arguments -Each language can define its own set of default header arguments in variable -@code{org-babel-default-header-args:}, where @code{} is the name -of the language. See the language-specific documentation available online at -@uref{http://orgmode.org/worg/org-contrib/babel}. - -@node Header arguments in Org mode properties, Language-specific header arguments in Org mode properties, Language-specific header arguments, Using header arguments -@subsubheading Header arguments in Org mode properties - -Buffer-wide header arguments may be specified as properties through the use -of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see -@ref{Property syntax}). - -For example the following would set @code{session} to @code{*R*} (only for R -code blocks), and @code{results} to @code{silent} for every code block in the -buffer, ensuring that all execution took place in the same session, and no -results would be inserted into the buffer. - -@example -#+PROPERTY: header-args:R :session *R* -#+PROPERTY: header-args :results silent -@end example - -Header arguments read from Org mode properties can also be set on a -per-subtree basis using property drawers (see @ref{Property syntax}). -@vindex org-use-property-inheritance -When properties are used to set default header arguments, they are always -looked up with inheritance, regardless of the value of -@code{org-use-property-inheritance}. Properties are evaluated as seen by the -outermost call or source block.@footnote{The deprecated syntax for default -header argument properties, using the name of the header argument as a -property name directly, evaluates the property as seen by the corresponding -source block definition. This behavior has been kept for backwards -compatibility.} - -In the following example the value of -the @code{:cache} header argument will default to @code{yes} in all code -blocks in the subtree rooted at the following heading: - -@example -* outline header - :PROPERTIES: - :header-args: :cache yes - :END: -@end example - -@kindex C-c C-x p -@vindex org-babel-default-header-args -Properties defined in this way override the properties set in -@code{org-babel-default-header-args} and are applied for all activated -languages. It is convenient to use the @code{org-set-property} function -bound to @kbd{C-c C-x p} to set properties in Org mode documents. - -@node Language-specific header arguments in Org mode properties, Code block specific header arguments, Header arguments in Org mode properties, Using header arguments -@subsubheading Language-specific header arguments in Org mode properties - -Language-specific header arguments are also read from properties -@code{header-args:} where @code{} is the name of the language -targeted. As an example - -@example -* Heading - :PROPERTIES: - :header-args:clojure: :session *clojure-1* - :header-args:R: :session *R* - :END: -** Subheading - :PROPERTIES: - :header-args:clojure: :session *clojure-2* - :END: -@end example - -would independently set a default session header argument for R and clojure -for calls and source blocks under subtree ``Heading'' and change to a -different clojure setting for evaluations under subtree ``Subheading'', while -the R session is inherited from ``Heading'' and therefore unchanged. - -@node Code block specific header arguments, Header arguments in function calls, Language-specific header arguments in Org mode properties, Using header arguments -@subsubheading Code block specific header arguments - -The most common way to assign values to header arguments is at the -code block level. This can be done by listing a sequence of header -arguments and their values as part of the @code{#+BEGIN_SRC} line. -Properties set in this way override both the values of -@code{org-babel-default-header-args} and header arguments specified as -properties. In the following example, the @code{:results} header argument -is set to @code{silent}, meaning the results of execution will not be -inserted in the buffer, and the @code{:exports} header argument is set to -@code{code}, meaning only the body of the code block will be -preserved on export to HTML or @LaTeX{}. - -@example -#+NAME: factorial -#+BEGIN_SRC haskell :results silent :exports code :var n=0 -fac 0 = 1 -fac n = n * fac (n-1) -#+END_SRC -@end example -Similarly, it is possible to set header arguments for inline code blocks - -@example -src_haskell[:exports both]@{fac 5@} -@end example - -Code block header arguments can span multiple lines using @code{#+HEADER:} or -@code{#+HEADERS:} lines preceding a code block or nested between the -@code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block. -@cindex #+HEADER: -@cindex #+HEADERS: - -Multi-line header arguments on an un-named code block: - -@example - #+HEADERS: :var data1=1 - #+BEGIN_SRC emacs-lisp :var data2=2 - (message "data1:%S, data2:%S" data1 data2) - #+END_SRC - - #+RESULTS: - : data1:1, data2:2 -@end example - -Multi-line header arguments on a named code block: - -@example - #+NAME: named-block - #+HEADER: :var data=2 - #+BEGIN_SRC emacs-lisp - (message "data:%S" data) - #+END_SRC - - #+RESULTS: named-block - : data:2 -@end example - -@node Header arguments in function calls, , Code block specific header arguments, Using header arguments -@comment node-name, next, previous, up -@subsubheading Header arguments in function calls - -At the most specific level, header arguments for ``Library of Babel'' or -@code{#+CALL:} lines can be set as shown in the two examples below. For more -information on the structure of @code{#+CALL:} lines see @ref{Evaluating code -blocks}. - -The following will apply the @code{:exports results} header argument to the -evaluation of the @code{#+CALL:} line. - -@example -#+CALL: factorial(n=5) :exports results -@end example - -The following will apply the @code{:session special} header argument to the -evaluation of the @code{factorial} code block. - -@example -#+CALL: factorial[:session special](n=5) -@end example - -@node Specific header arguments, , Using header arguments, Header arguments -@subsection Specific header arguments -Header arguments consist of an initial colon followed by the name of the -argument in lowercase letters. The following header arguments are defined: - -@menu -* var:: Pass arguments to code blocks -* results:: Specify the type of results and how they will - be collected and handled -* file:: Specify a path for file output -* file-desc:: Specify a description for file results -* dir:: Specify the default (possibly remote) - directory for code block execution -* exports:: Export code and/or results -* tangle:: Toggle tangling and specify file name -* mkdirp:: Toggle creation of parent directories of target - files during tangling -* comments:: Toggle insertion of comments in tangled - code files -* padline:: Control insertion of padding lines in tangled - code files -* no-expand:: Turn off variable assignment and noweb - expansion during tangling -* session:: Preserve the state of code evaluation -* noweb:: Toggle expansion of noweb references -* noweb-ref:: Specify block's noweb reference resolution target -* noweb-sep:: String used to separate noweb references -* cache:: Avoid re-evaluating unchanged code blocks -* sep:: Delimiter for writing tabular results outside Org -* hlines:: Handle horizontal lines in tables -* colnames:: Handle column names in tables -* rownames:: Handle row names in tables -* shebang:: Make tangled files executable -* tangle-mode:: Set permission of tangled files -* eval:: Limit evaluation of specific code blocks -* wrap:: Mark source block evaluation results -* post:: Post processing of code block results -* prologue:: Text to prepend to code block body -* epilogue:: Text to append to code block body -@end menu - -Additional header arguments are defined on a language-specific basis, see -@ref{Languages}. - -@node var, results, Specific header arguments, Specific header arguments -@subsubsection @code{:var} -The @code{:var} header argument is used to pass arguments to code blocks. -The specifics of how arguments are included in a code block vary by language; -these are addressed in the language-specific documentation. However, the -syntax used to specify arguments is the same across all languages. In every -case, variables require a default value when they are declared. - -The values passed to arguments can either be literal values, references, or -Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). -References include anything in the Org mode file that takes a @code{#+NAME:} -or @code{#+RESULTS:} line: tables, lists, @code{#+BEGIN_EXAMPLE} blocks, -other code blocks and the results of other code blocks. - -Note: When a reference is made to another code block, the referenced block -will be evaluated unless it has current cached results (see @ref{cache}). - -Argument values can be indexed in a manner similar to arrays (see @ref{var, -Indexable variable values}). - -The following syntax is used to pass arguments to code blocks using the -@code{:var} header argument. - -@example -:var name=assign -@end example - -The argument, @code{assign}, can either be a literal value, such as a string -@samp{"string"} or a number @samp{9}, or a reference to a table, a list, a -literal example, another code block (with or without arguments), or the -results of evaluating another code block. - -Here are examples of passing values by reference: - -@table @dfn - -@item table -an Org mode table named with either a @code{#+NAME:} line - -@example -#+NAME: example-table -| 1 | -| 2 | -| 3 | -| 4 | - -#+NAME: table-length -#+BEGIN_SRC emacs-lisp :var table=example-table -(length table) -#+END_SRC - -#+RESULTS: table-length -: 4 -@end example - -@item list -a simple list named with a @code{#+NAME:} line (note that nesting is not -carried through to the source code block) - -@example -#+NAME: example-list - - simple - - not - - nested - - list - -#+BEGIN_SRC emacs-lisp :var x=example-list - (print x) -#+END_SRC - -#+RESULTS: -| simple | list | -@end example - -@item code block without arguments -a code block name (from the example above), as assigned by @code{#+NAME:}, -optionally followed by parentheses - -@example -#+BEGIN_SRC emacs-lisp :var length=table-length() -(* 2 length) -#+END_SRC - -#+RESULTS: -: 8 -@end example - -@item code block with arguments -a code block name, as assigned by @code{#+NAME:}, followed by parentheses and -optional arguments passed within the parentheses following the -code block name using standard function call syntax - -@example -#+NAME: double -#+BEGIN_SRC emacs-lisp :var input=8 -(* 2 input) -#+END_SRC - -#+RESULTS: double -: 16 - -#+NAME: squared -#+BEGIN_SRC emacs-lisp :var input=double(input=1) -(* input input) -#+END_SRC - -#+RESULTS: squared -: 4 -@end example - -@item literal example -a literal example block named with a @code{#+NAME:} line - -@example -#+NAME: literal-example -#+BEGIN_EXAMPLE -A literal example -on two lines -#+END_EXAMPLE - -#+NAME: read-literal-example -#+BEGIN_SRC emacs-lisp :var x=literal-example - (concatenate 'string x " for you.") -#+END_SRC - -#+RESULTS: read-literal-example -: A literal example -: on two lines for you. - -@end example - -@end table - -@subsubheading Indexable variable values -It is possible to reference portions of variable values by ``indexing'' into -the variables. Indexes are 0 based with negative values counting back from -the end. If an index is separated by @code{,}s then each subsequent section -will index into the next deepest nesting or dimension of the value. Note -that this indexing occurs @emph{before} other table related header arguments -like @code{:hlines}, @code{:colnames} and @code{:rownames} are applied. The -following example assigns the last cell of the first row the table -@code{example-table} to the variable @code{data}: - -@example -#+NAME: example-table -| 1 | a | -| 2 | b | -| 3 | c | -| 4 | d | - -#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1] - data -#+END_SRC - -#+RESULTS: -: a -@end example - -Ranges of variable values can be referenced using two integers separated by a -@code{:}, in which case the entire inclusive range is referenced. For -example the following assigns the middle three rows of @code{example-table} -to @code{data}. - -@example -#+NAME: example-table -| 1 | a | -| 2 | b | -| 3 | c | -| 4 | d | -| 5 | 3 | - -#+BEGIN_SRC emacs-lisp :var data=example-table[1:3] - data -#+END_SRC - -#+RESULTS: -| 2 | b | -| 3 | c | -| 4 | d | -@end example - -Additionally, an empty index, or the single character @code{*}, are both -interpreted to mean the entire range and as such are equivalent to -@code{0:-1}, as shown in the following example in which the entire first -column is referenced. - -@example -#+NAME: example-table -| 1 | a | -| 2 | b | -| 3 | c | -| 4 | d | - -#+BEGIN_SRC emacs-lisp :var data=example-table[,0] - data -#+END_SRC - -#+RESULTS: -| 1 | 2 | 3 | 4 | -@end example - -It is possible to index into the results of code blocks as well as tables. -Any number of dimensions can be indexed. Dimensions are separated from one -another by commas, as shown in the following example. - -@example -#+NAME: 3D -#+BEGIN_SRC emacs-lisp - '(((1 2 3) (4 5 6) (7 8 9)) - ((10 11 12) (13 14 15) (16 17 18)) - ((19 20 21) (22 23 24) (25 26 27))) -#+END_SRC - -#+BEGIN_SRC emacs-lisp :var data=3D[1,,1] - data -#+END_SRC - -#+RESULTS: -| 11 | 14 | 17 | -@end example - -@subsubheading Emacs Lisp evaluation of variables - -Emacs lisp code can be used to initialize variable values. When a variable -value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be -evaluated as Emacs Lisp and the result of the evaluation will be assigned as -the variable value. The following example demonstrates use of this -evaluation to reliably pass the file-name of the Org mode buffer to a code -block---note that evaluation of header arguments is guaranteed to take place -in the original Org mode file, while there is no such guarantee for -evaluation of the code block body. - -@example -#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both - wc -w $filename -#+END_SRC -@end example - -Note that values read from tables and lists will not be evaluated as -Emacs Lisp, as shown in the following example. - -@example -#+NAME: table -| (a b c) | - -#+HEADERS: :var data=table[0,0] -#+BEGIN_SRC perl - $data -#+END_SRC - -#+RESULTS: -: (a b c) -@end example - -@node results, file, var, Specific header arguments -@subsubsection @code{:results} - -There are four classes of @code{:results} header argument. Only one option -per class may be supplied per code block. - -@itemize @bullet -@item -@b{collection} header arguments specify how the results should be collected -from the code block -@item -@b{type} header arguments specify what type of result the code block will -return---which has implications for how they will be processed before -insertion into the Org mode buffer -@item -@b{format} header arguments specify what type of result the code block will -return---which has implications for how they will be inserted into the -Org mode buffer -@item -@b{handling} header arguments specify how the results of evaluating the code -block should be handled. -@end itemize - -@subsubheading Collection -The following options are mutually exclusive, and specify how the results -should be collected from the code block. - -@itemize @bullet -@item @code{value} -This is the default. The result is the value of the last statement in the -code block. This header argument places the evaluation in functional -mode. Note that in some languages, e.g., Python, use of this result type -requires that a @code{return} statement be included in the body of the source -code block. E.g., @code{:results value}. -@item @code{output} -The result is the collection of everything printed to STDOUT during the -execution of the code block. This header argument places the -evaluation in scripting mode. E.g., @code{:results output}. -@end itemize - -@subsubheading Type - -The following options are mutually exclusive and specify what type of results -the code block will return. By default, results are inserted as either a -table or scalar depending on their value. - -@itemize @bullet -@item @code{table}, @code{vector} -The results should be interpreted as an Org mode table. If a single value is -returned, it will be converted into a table with one row and one column. -E.g., @code{:results value table}. -@item @code{list} -The results should be interpreted as an Org mode list. If a single scalar -value is returned it will be converted into a list with only one element. -@item @code{scalar}, @code{verbatim} -The results should be interpreted literally---they will not be -converted into a table. The results will be inserted into the Org mode -buffer as quoted text. E.g., @code{:results value verbatim}. -@item @code{file} -The results will be interpreted as the path to a file, and will be inserted -into the Org mode buffer as a file link. E.g., @code{:results value file}. -@end itemize - -@subsubheading Format - -The following options are mutually exclusive and specify what type of results -the code block will return. By default, results are inserted according to the -type as specified above. - -@itemize @bullet -@item @code{raw} -The results are interpreted as raw Org mode code and are inserted directly -into the buffer. If the results look like a table they will be aligned as -such by Org mode. E.g., @code{:results value raw}. -@item @code{org} -The results are will be enclosed in a @code{BEGIN_SRC org} block. -They are not comma-escaped by default but they will be if you hit @kbd{TAB} -in the block and/or if you export the file. E.g., @code{:results value org}. -@item @code{html} -Results are assumed to be HTML and will be enclosed in a @code{BEGIN_HTML} -block. E.g., @code{:results value html}. -@item @code{latex} -Results assumed to be @LaTeX{} and are enclosed in a @code{BEGIN_LaTeX} block. -E.g., @code{:results value latex}. -@item @code{code} -Result are assumed to be parsable code and are enclosed in a code block. -E.g., @code{:results value code}. -@item @code{pp} -The result is converted to pretty-printed code and is enclosed in a code -block. This option currently supports Emacs Lisp, Python, and Ruby. E.g., -@code{:results value pp}. -@item @code{drawer} -The result is wrapped in a RESULTS drawer. This can be useful for -inserting @code{raw} or @code{org} syntax results in such a way that their -extent is known and they can be automatically removed or replaced. -@end itemize - -@subsubheading Handling -The following results options indicate what happens with the -results once they are collected. - -@itemize @bullet -@item @code{silent} -The results will be echoed in the minibuffer but will not be inserted into -the Org mode buffer. E.g., @code{:results output silent}. -@item @code{replace} -The default value. Any existing results will be removed, and the new results -will be inserted into the Org mode buffer in their place. E.g., -@code{:results output replace}. -@item @code{append} -If there are pre-existing results of the code block then the new results will -be appended to the existing results. Otherwise the new results will be -inserted as with @code{replace}. -@item @code{prepend} -If there are pre-existing results of the code block then the new results will -be prepended to the existing results. Otherwise the new results will be -inserted as with @code{replace}. -@end itemize - -@node file, file-desc, results, Specific header arguments -@subsubsection @code{:file} - -The header argument @code{:file} is used to specify an external file in which -to save code block results. After code block evaluation an Org mode style -@code{[[file:]]} link (see @ref{Link format}) to the file will be inserted -into the Org mode buffer. Some languages including R, gnuplot, dot, and -ditaa provide special handling of the @code{:file} header argument -automatically wrapping the code block body in the boilerplate code required -to save output to the specified file. This is often useful for saving -graphical output of a code block to the specified file. - -The argument to @code{:file} should be either a string specifying the path to -a file, or a list of two strings in which case the first element of the list -should be the path to a file and the second a description for the link. - -@node file-desc, dir, file, Specific header arguments -@subsubsection @code{:file-desc} - -The value of the @code{:file-desc} header argument is used to provide a -description for file code block results which are inserted as Org mode links -(see @ref{Link format}). If the @code{:file-desc} header argument is given -with no value the link path will be placed in both the ``link'' and the -``description'' portion of the Org mode link. - -@node dir, exports, file-desc, Specific header arguments -@subsubsection @code{:dir} and remote execution - -While the @code{:file} header argument can be used to specify the path to the -output file, @code{:dir} specifies the default directory during code block -execution. If it is absent, then the directory associated with the current -buffer is used. In other words, supplying @code{:dir path} temporarily has -the same effect as changing the current directory with @kbd{M-x cd path RET}, and -then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets -the value of the Emacs variable @code{default-directory}. - -When using @code{:dir}, you should supply a relative path for file output -(e.g., @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which -case that path will be interpreted relative to the default directory. - -In other words, if you want your plot to go into a folder called @file{Work} -in your home directory, you could use - -@example -#+BEGIN_SRC R :file myplot.png :dir ~/Work -matplot(matrix(rnorm(100), 10), type="l") -#+END_SRC -@end example - -@subsubheading Remote execution -A directory on a remote machine can be specified using tramp file syntax, in -which case the code will be evaluated on the remote machine. An example is - -@example -#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu: -plot(1:10, main=system("hostname", intern=TRUE)) -#+END_SRC -@end example - -Text results will be returned to the local Org mode buffer as usual, and file -output will be created on the remote machine with relative paths interpreted -relative to the remote directory. An Org mode link to the remote file will be -created. - -So, in the above example a plot will be created on the remote machine, -and a link of the following form will be inserted in the org buffer: - -@example -[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] -@end example - -Most of this functionality follows immediately from the fact that @code{:dir} -sets the value of the Emacs variable @code{default-directory}, thanks to -tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to -install tramp separately in order for these features to work correctly. - -@subsubheading Further points - -@itemize @bullet -@item -If @code{:dir} is used in conjunction with @code{:session}, although it will -determine the starting directory for a new session as expected, no attempt is -currently made to alter the directory associated with an existing session. -@item -@code{:dir} should typically not be used to create files during export with -@code{:exports results} or @code{:exports both}. The reason is that, in order -to retain portability of exported material between machines, during export -links inserted into the buffer will @emph{not} be expanded against @code{default -directory}. Therefore, if @code{default-directory} is altered using -@code{:dir}, it is probable that the file will be created in a location to -which the link does not point. -@end itemize - -@node exports, tangle, dir, Specific header arguments -@subsubsection @code{:exports} - -The @code{:exports} header argument specifies what should be included in HTML -or @LaTeX{} exports of the Org mode file. - -@itemize @bullet -@item @code{code} -The default. The body of code is included into the exported file. E.g., -@code{:exports code}. -@item @code{results} -The result of evaluating the code is included in the exported file. E.g., -@code{:exports results}. -@item @code{both} -Both the code and results are included in the exported file. E.g., -@code{:exports both}. -@item @code{none} -Nothing is included in the exported file. E.g., @code{:exports none}. -@end itemize - -@node tangle, mkdirp, exports, Specific header arguments -@subsubsection @code{:tangle} - -The @code{:tangle} header argument specifies whether or not the code -block should be included in tangled extraction of source code files. - -@itemize @bullet -@item @code{tangle} -The code block is exported to a source code file named after the full path -(including the directory) and file name (w/o extension) of the Org mode file. -E.g., @code{:tangle yes}. -@item @code{no} -The default. The code block is not exported to a source code file. -E.g., @code{:tangle no}. -@item other -Any other string passed to the @code{:tangle} header argument is interpreted -as a path (directory and file name relative to the directory of the Org mode -file) to which the block will be exported. E.g., @code{:tangle path}. -@end itemize - -@node mkdirp, comments, tangle, Specific header arguments -@subsubsection @code{:mkdirp} - -The @code{:mkdirp} header argument can be used to create parent directories -of tangled files when missing. This can be set to @code{yes} to enable -directory creation or to @code{no} to inhibit directory creation. - -@node comments, padline, mkdirp, Specific header arguments -@subsubsection @code{:comments} -By default code blocks are tangled to source-code files without any insertion -of comments beyond those which may already exist in the body of the code -block. The @code{:comments} header argument can be set as follows to control -the insertion of extra comments into the tangled code file. - -@itemize @bullet -@item @code{no} -The default. No extra comments are inserted during tangling. -@item @code{link} -The code block is wrapped in comments which contain pointers back to the -original Org file from which the code was tangled. -@item @code{yes} -A synonym for ``link'' to maintain backwards compatibility. -@item @code{org} -Include text from the Org mode file as a comment. -The text is picked from the leading context of the tangled code and is -limited by the nearest headline or source block as the case may be. -@item @code{both} -Turns on both the ``link'' and ``org'' comment options. -@item @code{noweb} -Turns on the ``link'' comment option, and additionally wraps expanded noweb -references in the code block body in link comments. -@end itemize - -@node padline, no-expand, comments, Specific header arguments -@subsubsection @code{:padline} -Control in insertion of padding lines around code block bodies in tangled -code files. The default value is @code{yes} which results in insertion of -newlines before and after each tangled code block. The following arguments -are accepted. - -@itemize @bullet -@item @code{yes} -Insert newlines before and after each code block body in tangled code files. -@item @code{no} -Do not insert any newline padding in tangled output. -@end itemize - -@node no-expand, session, padline, Specific header arguments -@subsubsection @code{:no-expand} - -By default, code blocks are expanded with @code{org-babel-expand-src-block} -during tangling. This has the effect of assigning values to variables -specified with @code{:var} (see @ref{var}), and of replacing ``noweb'' -references (see @ref{Noweb reference syntax}) with their targets. The -@code{:no-expand} header argument can be used to turn off this behavior. - -@node session, noweb, no-expand, Specific header arguments -@subsubsection @code{:session} - -The @code{:session} header argument starts a session for an interpreted -language where state is preserved. - -By default, a session is not started. - -A string passed to the @code{:session} header argument will give the session -a name. This makes it possible to run concurrent sessions for each -interpreted language. - -@node noweb, noweb-ref, session, Specific header arguments -@subsubsection @code{:noweb} - -The @code{:noweb} header argument controls expansion of ``noweb'' syntax -references (see @ref{Noweb reference syntax}) when the code block is -evaluated, tangled, or exported. The @code{:noweb} header argument can have -one of the five values: @code{no}, @code{yes}, @code{tangle}, or -@code{no-export} @code{strip-export}. - -@itemize @bullet -@item @code{no} -The default. ``Noweb'' syntax references in the body of the code block will -not be expanded before the code block is evaluated, tangled or exported. -@item @code{yes} -``Noweb'' syntax references in the body of the code block will be -expanded before the code block is evaluated, tangled or exported. -@item @code{tangle} -``Noweb'' syntax references in the body of the code block will be expanded -before the code block is tangled. However, ``noweb'' syntax references will -not be expanded when the code block is evaluated or exported. -@item @code{no-export} -``Noweb'' syntax references in the body of the code block will be expanded -before the block is evaluated or tangled. However, ``noweb'' syntax -references will not be expanded when the code block is exported. -@item @code{strip-export} -``Noweb'' syntax references in the body of the code block will be expanded -before the block is evaluated or tangled. However, ``noweb'' syntax -references will be removed when the code block is exported. -@item @code{eval} -``Noweb'' syntax references in the body of the code block will only be -expanded before the block is evaluated. -@end itemize - -@subsubheading Noweb prefix lines -Noweb insertions are now placed behind the line prefix of the -@code{<>}. -This behavior is illustrated in the following example. Because the -@code{<>} noweb reference appears behind the SQL comment syntax, -each line of the expanded noweb reference will be commented. - -This code block: - -@example --- <> -@end example - -expands to: - -@example --- this is the --- multi-line body of example -@end example - -Note that noweb replacement text that does not contain any newlines will not -be affected by this change, so it is still possible to use inline noweb -references. - -@node noweb-ref, noweb-sep, noweb, Specific header arguments -@subsubsection @code{:noweb-ref} -When expanding ``noweb'' style references the bodies of all code block with -@emph{either} a block name matching the reference name @emph{or} a -@code{:noweb-ref} header argument matching the reference name will be -concatenated together to form the replacement text. - -By setting this header argument at the sub-tree or file level, simple code -block concatenation may be achieved. For example, when tangling the -following Org mode file, the bodies of code blocks will be concatenated into -the resulting pure code file@footnote{(The example needs property inheritance -to be turned on for the @code{noweb-ref} property, see @ref{Property -inheritance}).}. - -@example - #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh - <> - #+END_SRC - * the mount point of the fullest disk - :PROPERTIES: - :noweb-ref: fullest-disk - :END: - - ** query all mounted disks - #+BEGIN_SRC sh - df \ - #+END_SRC - - ** strip the header row - #+BEGIN_SRC sh - |sed '1d' \ - #+END_SRC - - ** sort by the percent full - #+BEGIN_SRC sh - |awk '@{print $5 " " $6@}'|sort -n |tail -1 \ - #+END_SRC - - ** extract the mount point - #+BEGIN_SRC sh - |awk '@{print $2@}' - #+END_SRC -@end example - -The @code{:noweb-sep} (see @ref{noweb-sep}) header argument holds the string -used to separate accumulate noweb references like those above. By default a -newline is used. - -@node noweb-sep, cache, noweb-ref, Specific header arguments -@subsubsection @code{:noweb-sep} - -The @code{:noweb-sep} header argument holds the string used to separate -accumulate noweb references (see @ref{noweb-ref}). By default a newline is -used. - -@node cache, sep, noweb-sep, Specific header arguments -@subsubsection @code{:cache} - -The @code{:cache} header argument controls the use of in-buffer caching of -the results of evaluating code blocks. It can be used to avoid re-evaluating -unchanged code blocks. Note that the @code{:cache} header argument will not -attempt to cache results when the @code{:session} header argument is used, -because the results of the code block execution may be stored in the session -outside of the Org mode buffer. The @code{:cache} header argument can have -one of two values: @code{yes} or @code{no}. - -@itemize @bullet -@item @code{no} -The default. No caching takes place, and the code block will be evaluated -every time it is called. -@item @code{yes} -Every time the code block is run a SHA1 hash of the code and arguments -passed to the block will be generated. This hash is packed into the -@code{#+RESULTS:} line and will be checked on subsequent -executions of the code block. If the code block has not -changed since the last time it was evaluated, it will not be re-evaluated. -@end itemize - -Code block caches notice if the value of a variable argument -to the code block has changed. If this is the case, the cache is -invalidated and the code block is re-run. In the following example, -@code{caller} will not be re-run unless the results of @code{random} have -changed since it was last run. - -@example - #+NAME: random - #+BEGIN_SRC R :cache yes - runif(1) - #+END_SRC - - #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random - 0.4659510825295 - - #+NAME: caller - #+BEGIN_SRC emacs-lisp :var x=random :cache yes - x - #+END_SRC - - #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller - 0.254227238707244 -@end example - -@node sep, hlines, cache, Specific header arguments -@subsubsection @code{:sep} - -The @code{:sep} header argument can be used to control the delimiter used -when writing tabular results out to files external to Org mode. This is used -either when opening tabular results of a code block by calling the -@code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block, -or when writing code block results to an external file (see @ref{file}) -header argument. - -By default, when @code{:sep} is not specified output tables are tab -delimited. - -@node hlines, colnames, sep, Specific header arguments -@subsubsection @code{:hlines} - -Tables are frequently represented with one or more horizontal lines, or -hlines. The @code{:hlines} argument to a code block accepts the -values @code{yes} or @code{no}, with a default value of @code{no}. - -@itemize @bullet -@item @code{no} -Strips horizontal lines from the input table. In most languages this is the -desired effect because an @code{hline} symbol is interpreted as an unbound -variable and raises an error. Setting @code{:hlines no} or relying on the -default value yields the following results. - -@example -#+NAME: many-cols -| a | b | c | -|---+---+---| -| d | e | f | -|---+---+---| -| g | h | i | - -#+NAME: echo-table -#+BEGIN_SRC python :var tab=many-cols - return tab -#+END_SRC - -#+RESULTS: echo-table -| a | b | c | -| d | e | f | -| g | h | i | -@end example - -@item @code{yes} -Leaves hlines in the table. Setting @code{:hlines yes} has this effect. - -@example -#+NAME: many-cols -| a | b | c | -|---+---+---| -| d | e | f | -|---+---+---| -| g | h | i | - -#+NAME: echo-table -#+BEGIN_SRC python :var tab=many-cols :hlines yes - return tab -#+END_SRC - -#+RESULTS: echo-table -| a | b | c | -|---+---+---| -| d | e | f | -|---+---+---| -| g | h | i | -@end example -@end itemize - -@node colnames, rownames, hlines, Specific header arguments -@subsubsection @code{:colnames} - -The @code{:colnames} header argument accepts the values @code{yes}, -@code{no}, or @code{nil} for unassigned. The default value is @code{nil}. -Note that the behavior of the @code{:colnames} header argument may differ -across languages. - -@itemize @bullet -@item @code{nil} -If an input table looks like it has column names -(because its second row is an hline), then the column -names will be removed from the table before -processing, then reapplied to the results. - -@example -#+NAME: less-cols -| a | -|---| -| b | -| c | - -#+NAME: echo-table-again -#+BEGIN_SRC python :var tab=less-cols - return [[val + '*' for val in row] for row in tab] -#+END_SRC - -#+RESULTS: echo-table-again -| a | -|----| -| b* | -| c* | -@end example - -Please note that column names are not removed before the table is indexed -using variable indexing @xref{var, Indexable variable values}. - -@item @code{no} -No column name pre-processing takes place - -@item @code{yes} -Column names are removed and reapplied as with @code{nil} even if the table -does not ``look like'' it has column names (i.e., the second row is not an -hline) -@end itemize - -@node rownames, shebang, colnames, Specific header arguments -@subsubsection @code{:rownames} - -The @code{:rownames} header argument can take on the values @code{yes} or -@code{no}, with a default value of @code{no}. Note that Emacs Lisp code -blocks ignore the @code{:rownames} header argument entirely given the ease -with which tables with row names may be handled directly in Emacs Lisp. - -@itemize @bullet -@item @code{no} -No row name pre-processing will take place. - -@item @code{yes} -The first column of the table is removed from the table before processing, -and is then reapplied to the results. - -@example -#+NAME: with-rownames -| one | 1 | 2 | 3 | 4 | 5 | -| two | 6 | 7 | 8 | 9 | 10 | - -#+NAME: echo-table-once-again -#+BEGIN_SRC python :var tab=with-rownames :rownames yes - return [[val + 10 for val in row] for row in tab] -#+END_SRC - -#+RESULTS: echo-table-once-again -| one | 11 | 12 | 13 | 14 | 15 | -| two | 16 | 17 | 18 | 19 | 20 | -@end example - -Please note that row names are not removed before the table is indexed using -variable indexing @xref{var, Indexable variable values}. - -@end itemize - -@node shebang, tangle-mode, rownames, Specific header arguments -@subsubsection @code{:shebang} - -Setting the @code{:shebang} header argument to a string value -(e.g., @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the -first line of any tangled file holding the code block, and the file -permissions of the tangled file are set to make it executable. - - -@node tangle-mode, eval, shebang, Specific header arguments -@subsubsection @code{:tangle-mode} - -The @code{tangle-mode} header argument controls the permission set on tangled -files. The value of this header argument will be passed to -@code{set-file-modes}. For example, to set a tangled file as read only use -@code{:tangle-mode (identity #o444)}, or to set a tangled file as executable -use @code{:tangle-mode (identity #o755)}. Blocks with @code{shebang} -(@ref{shebang}) header arguments will automatically be made executable unless -the @code{tangle-mode} header argument is also used. The behavior is -undefined if multiple code blocks with different values for the -@code{tangle-mode} header argument are tangled to the same file. - -@node eval, wrap, tangle-mode, Specific header arguments -@subsubsection @code{:eval} -The @code{:eval} header argument can be used to limit the evaluation of -specific code blocks. The @code{:eval} header argument can be useful for -protecting against the evaluation of dangerous code blocks or to ensure that -evaluation will require a query regardless of the value of the -@code{org-confirm-babel-evaluate} variable. The possible values of -@code{:eval} and their effects are shown below. - -@table @code -@item never or no -The code block will not be evaluated under any circumstances. -@item query -Evaluation of the code block will require a query. -@item never-export or no-export -The code block will not be evaluated during export but may still be called -interactively. -@item query-export -Evaluation of the code block during export will require a query. -@end table - -If this header argument is not set then evaluation is determined by the value -of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation -security}. - -@node wrap, post, eval, Specific header arguments -@subsubsection @code{:wrap} -The @code{:wrap} header argument is used to mark the results of source block -evaluation. The header argument can be passed a string that will be appended -to @code{#+BEGIN_} and @code{#+END_}, which will then be used to wrap the -results. If not string is specified then the results will be wrapped in a -@code{#+BEGIN/END_RESULTS} block. - -@node post, prologue, wrap, Specific header arguments -@subsubsection @code{:post} -The @code{:post} header argument is used to post-process the results of a -code block execution. When a post argument is given, the results of the code -block will temporarily be bound to the @code{*this*} variable. This variable -may then be included in header argument forms such as those used in @ref{var} -header argument specifications allowing passing of results to other code -blocks, or direct execution via Emacs Lisp. - -The following example illustrates the usage of the @code{:post} header -argument. - -@example -#+name: attr_wrap -#+begin_src sh :var data="" :var width="\\textwidth" :results output - echo "#+ATTR_LATEX :width $width" - echo "$data" -#+end_src - -#+header: :file /tmp/it.png -#+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer - digraph@{ - a -> b; - b -> c; - c -> a; - @} -#+end_src - -#+RESULTS: -:RESULTS: -#+ATTR_LATEX :width 5cm -[[file:/tmp/it.png]] -:END: -@end example - -@node prologue, epilogue, post, Specific header arguments -@subsubsection @code{:prologue} -The value of the @code{prologue} header argument will be prepended to the -code block body before execution. For example, @code{:prologue "reset"} may -be used to reset a gnuplot session before execution of a particular code -block, or the following configuration may be used to do this for all gnuplot -code blocks. Also see @ref{epilogue}. - -@lisp -(add-to-list 'org-babel-default-header-args:gnuplot - '((:prologue . "reset"))) -@end lisp - -@node epilogue, , prologue, Specific header arguments -@subsubsection @code{:epilogue} -The value of the @code{epilogue} header argument will be appended to the code -block body before execution. Also see @ref{prologue}. - -@node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code -@section Results of evaluation -@cindex code block, results of evaluation -@cindex source code, results of evaluation - -The way in which results are handled depends on whether a session is invoked, -as well as on whether @code{:results value} or @code{:results output} is -used. The following table shows the table possibilities. For a full listing -of the possible results header arguments see @ref{results}. - -@multitable @columnfractions 0.26 0.33 0.41 -@item @tab @b{Non-session} @tab @b{Session} -@item @code{:results value} @tab value of last expression @tab value of last expression -@item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output -@end multitable - -Note: With @code{:results value}, the result in both @code{:session} and -non-session is returned to Org mode as a table (a one- or two-dimensional -vector of strings or numbers) when appropriate. - -@subsection Non-session -@subsubsection @code{:results value} -This is the default. Internally, the value is obtained by wrapping the code -in a function definition in the external language, and evaluating that -function. Therefore, code should be written as if it were the body of such a -function. In particular, note that Python does not automatically return a -value from a function unless a @code{return} statement is present, and so a -@samp{return} statement will usually be required in Python. - -This is the only one of the four evaluation contexts in which the code is -automatically wrapped in a function definition. - -@subsubsection @code{:results output} -The code is passed to the interpreter as an external process, and the -contents of the standard output stream are returned as text. (In certain -languages this also contains the error output stream; this is an area for -future work.) - -@subsection Session -@subsubsection @code{:results value} -The code is passed to an interpreter running as an interactive Emacs inferior -process. Only languages which provide tools for interactive evaluation of -code have session support, so some language (e.g., C and ditaa) do not -support the @code{:session} header argument, and in other languages (e.g., -Python and Haskell) which have limitations on the code which may be entered -into interactive sessions, those limitations apply to the code in code blocks -using the @code{:session} header argument as well. - -Unless the @code{:results output} option is supplied (see below) the result -returned is the result of the last evaluation performed by the -interpreter. (This is obtained in a language-specific manner: the value of -the variable @code{_} in Python and Ruby, and the value of @code{.Last.value} -in R). - -@subsubsection @code{:results output} -The code is passed to the interpreter running as an interactive Emacs -inferior process. The result returned is the concatenation of the sequence of -(text) output from the interactive interpreter. Notice that this is not -necessarily the same as what would be sent to @code{STDOUT} if the same code -were passed to a non-interactive interpreter running as an external -process. For example, compare the following two blocks: - -@example -#+BEGIN_SRC python :results output - print "hello" - 2 - print "bye" -#+END_SRC - -#+RESULTS: -: hello -: bye -@end example - -In non-session mode, the `2' is not printed and does not appear. - -@example -#+BEGIN_SRC python :results output :session - print "hello" - 2 - print "bye" -#+END_SRC - -#+RESULTS: -: hello -: 2 -: bye -@end example - -But in @code{:session} mode, the interactive interpreter receives input `2' -and prints out its value, `2'. (Indeed, the other print statements are -unnecessary here). - -@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code -@section Noweb reference syntax -@cindex code block, noweb reference -@cindex syntax, noweb -@cindex source code, noweb reference - -The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate -Programming system allows named blocks of code to be referenced by using the -familiar Noweb syntax: - -@example -<> -@end example - -When a code block is tangled or evaluated, whether or not ``noweb'' -references are expanded depends upon the value of the @code{:noweb} header -argument. If @code{:noweb yes}, then a Noweb reference is expanded before -evaluation. If @code{:noweb no}, the default, then the reference is not -expanded before evaluation. See the @ref{noweb-ref} header argument for -a more flexible way to resolve noweb references. - -It is possible to include the @emph{results} of a code block rather than the -body. This is done by appending parenthesis to the code block name which may -optionally contain arguments to the code block as shown below. - -@example -<> -@end example - -Note: the default value, @code{:noweb no}, was chosen to ensure that -correct code is not broken in a language, such as Ruby, where -@code{<>} is a syntactically valid construct. If @code{<>} is not -syntactically valid in languages that you use, then please consider setting -the default value. - -Note: if noweb tangling is slow in large Org mode files consider setting the -@code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}. -This will result in faster noweb reference resolution at the expense of not -correctly resolving inherited values of the @code{:noweb-ref} header -argument. - -@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code -@section Key bindings and useful functions -@cindex code block, key bindings - -Many common Org mode key sequences are re-bound depending on -the context. - -Within a code block, the following key bindings -are active: - -@multitable @columnfractions 0.25 0.75 -@kindex C-c C-c -@item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block} -@kindex C-c C-o -@item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result} -@kindex M-up -@item @kbd{M-@key{up}} @tab @code{org-babel-load-in-session} -@kindex M-down -@item @kbd{M-@key{down}} @tab @code{org-babel-switch-to-session} -@end multitable - -In an Org mode buffer, the following key bindings are active: - -@multitable @columnfractions 0.45 0.55 -@kindex C-c C-v p -@kindex C-c C-v C-p -@item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block} -@kindex C-c C-v n -@kindex C-c C-v C-n -@item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block} -@kindex C-c C-v e -@kindex C-c C-v C-e -@item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe} -@kindex C-c C-v o -@kindex C-c C-v C-o -@item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result} -@kindex C-c C-v v -@kindex C-c C-v C-v -@item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block} -@kindex C-c C-v u -@kindex C-c C-v C-u -@item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head} -@kindex C-c C-v g -@kindex C-c C-v C-g -@item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block} -@kindex C-c C-v r -@kindex C-c C-v C-r -@item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result} -@kindex C-c C-v b -@kindex C-c C-v C-b -@item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer} -@kindex C-c C-v s -@kindex C-c C-v C-s -@item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree} -@kindex C-c C-v d -@kindex C-c C-v C-d -@item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block} -@kindex C-c C-v t -@kindex C-c C-v C-t -@item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle} -@kindex C-c C-v f -@kindex C-c C-v C-f -@item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file} -@kindex C-c C-v c -@kindex C-c C-v C-c -@item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block} -@kindex C-c C-v j -@kindex C-c C-v C-j -@item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg} -@kindex C-c C-v l -@kindex C-c C-v C-l -@item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session} -@kindex C-c C-v i -@kindex C-c C-v C-i -@item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest} -@kindex C-c C-v I -@kindex C-c C-v C-I -@item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info} -@kindex C-c C-v z -@kindex C-c C-v C-z -@item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session-with-code} -@kindex C-c C-v a -@kindex C-c C-v C-a -@item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash} -@kindex C-c C-v h -@kindex C-c C-v C-h -@item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings} -@kindex C-c C-v x -@kindex C-c C-v C-x -@item @kbd{C-c C-v x} @ @ @r{or} @ @ @kbd{C-c C-v C-x} @tab @code{org-babel-do-key-sequence-in-edit-buffer} -@end multitable - -@c When possible these keybindings were extended to work when the control key is -@c kept pressed, resulting in the following additional keybindings. - -@c @multitable @columnfractions 0.25 0.75 -@c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash} -@c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer} -@c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file} -@c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest} -@c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block} -@c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree} -@c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle} -@c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session} -@c @end multitable - -@node Batch execution, , Key bindings and useful functions, Working With Source Code -@section Batch execution -@cindex code block, batch execution -@cindex source code, batch execution - -It is possible to call functions from the command line. This shell -script calls @code{org-babel-tangle} on every one of its arguments. - -Be sure to adjust the paths to fit your system. - -@example -#!/bin/sh -# -*- mode: shell-script -*- -# -# tangle files with org-mode -# -DIR=`pwd` -FILES="" - -# wrap each argument in the code required to call tangle on it -for i in $@@; do - FILES="$FILES \"$i\"" -done - -emacs -Q --batch \ ---eval "(progn -(add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) -(add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\" t)) -(require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle) -(mapc (lambda (file) - (find-file (expand-file-name file \"$DIR\")) - (org-babel-tangle) - (kill-buffer)) '($FILES)))" 2>&1 |grep tangled -@end example - -@node Miscellaneous, Hacking, Working With Source Code, Top -@chapter Miscellaneous - -@menu -* Completion:: M-TAB knows what you need -* Easy Templates:: Quick insertion of structural elements -* Speed keys:: Electric commands at the beginning of a headline -* Code evaluation security:: Org mode files evaluate inline code -* Customization:: Adapting Org to your taste -* In-buffer settings:: Overview of the #+KEYWORDS -* The very busy C-c C-c key:: When in doubt, press C-c C-c -* Clean view:: Getting rid of leading stars in the outline -* TTY keys:: Using Org on a tty -* Interaction:: Other Emacs packages -* org-crypt:: Encrypting Org files -@end menu - - -@node Completion, Easy Templates, Miscellaneous, Miscellaneous -@section Completion -@cindex completion, of @TeX{} symbols -@cindex completion, of TODO keywords -@cindex completion, of dictionary words -@cindex completion, of option keywords -@cindex completion, of tags -@cindex completion, of property keys -@cindex completion, of link abbreviations -@cindex @TeX{} symbol completion -@cindex TODO keywords completion -@cindex dictionary word completion -@cindex option keyword completion -@cindex tag completion -@cindex link abbreviations, completion of - -Emacs would not be Emacs without completion, and Org mode uses it whenever it -makes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface for -some of the completion prompts, you can specify your preference by setting at -most one of the variables @code{org-completion-use-iswitchb} -@code{org-completion-use-ido}. - -Org supports in-buffer completion. This type of completion does -not make use of the minibuffer. You simply type a few letters into -the buffer and use the key to complete text right there. - -@table @kbd -@kindex M-@key{TAB} -@item M-@key{TAB} -Complete word at point -@itemize @bullet -@item -At the beginning of a headline, complete TODO keywords. -@item -After @samp{\}, complete @TeX{} symbols supported by the exporter. -@item -After @samp{*}, complete headlines in the current buffer so that they -can be used in search links like @samp{[[*find this headline]]}. -@item -After @samp{:} in a headline, complete tags. The list of tags is taken -from the variable @code{org-tag-alist} (possibly set through the -@samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created -dynamically from all tags used in the current buffer. -@item -After @samp{:} and not in a headline, complete property keys. The list -of keys is constructed dynamically from all keys used in the current -buffer. -@item -After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}). -@item -After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or -@samp{OPTIONS} which set file-specific options for Org mode. When the -option keyword is already complete, pressing @kbd{M-@key{TAB}} again -will insert example settings for this keyword. -@item -In the line after @samp{#+STARTUP: }, complete startup keywords, -i.e., valid keys for this line. -@item -Elsewhere, complete dictionary words using Ispell. -@end itemize -@end table - -@node Easy Templates, Speed keys, Completion, Miscellaneous -@section Easy Templates -@cindex template insertion -@cindex insertion, of templates - -Org mode supports insertion of empty structural elements (like -@code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key -strokes. This is achieved through a native template expansion mechanism. -Note that Emacs has several other template mechanisms which could be used in -a similar way, for example @file{yasnippet}. - -To insert a structural element, type a @samp{<}, followed by a template -selector and @kbd{@key{TAB}}. Completion takes effect only when the above -keystrokes are typed on a line by itself. - -The following template selectors are currently supported. - -@multitable @columnfractions 0.1 0.9 -@item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC} -@item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE} -@item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE} -@item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE} -@item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER} -@item @kbd{l} @tab @code{#+BEGIN_LaTeX ... #+END_LaTeX} -@item @kbd{L} @tab @code{#+LaTeX:} -@item @kbd{h} @tab @code{#+BEGIN_HTML ... #+END_HTML} -@item @kbd{H} @tab @code{#+HTML:} -@item @kbd{a} @tab @code{#+BEGIN_ASCII ... #+END_ASCII} -@item @kbd{A} @tab @code{#+ASCII:} -@item @kbd{i} @tab @code{#+INDEX:} line -@item @kbd{I} @tab @code{#+INCLUDE:} line -@end multitable - -For example, on an empty line, typing "Customization} menu. Many -settings can also be activated on a per-file basis, by putting special -lines into the buffer (@pxref{In-buffer settings}). - -@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous -@section Summary of in-buffer settings -@cindex in-buffer settings -@cindex special keywords - -Org mode uses special lines in the buffer to define settings on a -per-file basis. These lines start with a @samp{#+} followed by a -keyword, a colon, and then individual words defining a setting. Several -setting words can be in the same line, but you can also have multiple -lines for the keyword. While these settings are described throughout -the manual, here is a summary. After changing any of those lines in the -buffer, press @kbd{C-c C-c} with the cursor still in the line to -activate the changes immediately. Otherwise they become effective only -when the file is visited again in a new Emacs session. - -@vindex org-archive-location -@table @kbd -@item #+ARCHIVE: %s_done:: -This line sets the archive location for the agenda file. It applies for -all subsequent lines until the next @samp{#+ARCHIVE} line, or the end -of the file. The first such line also applies to any entries before it. -The corresponding variable is @code{org-archive-location}. -@item #+CATEGORY: -This line sets the category for the agenda file. The category applies -for all subsequent lines until the next @samp{#+CATEGORY} line, or the -end of the file. The first such line also applies to any entries before it. -@item #+COLUMNS: %25ITEM ... -@cindex property, COLUMNS -Set the default format for columns view. This format applies when -columns view is invoked in locations where no @code{COLUMNS} property -applies. -@item #+CONSTANTS: name1=value1 ... -@vindex org-table-formula-constants -@vindex org-table-formula -Set file-local values for constants to be used in table formulas. This -line sets the local variable @code{org-table-formula-constants-local}. -The global version of this variable is -@code{org-table-formula-constants}. -@item #+FILETAGS: :tag1:tag2:tag3: -Set tags that can be inherited by any entry in the file, including the -top-level entries. -@item #+DRAWERS: NAME1 ... -@vindex org-drawers -Set the file-local set of additional drawers. The corresponding global -variable is @code{org-drawers}. -@item #+LINK: linkword replace -@vindex org-link-abbrev-alist -These lines (several are allowed) specify link abbreviations. -@xref{Link abbreviations}. The corresponding variable is -@code{org-link-abbrev-alist}. -@item #+PRIORITIES: highest lowest default -@vindex org-highest-priority -@vindex org-lowest-priority -@vindex org-default-priority -This line sets the limits and the default for the priorities. All three -must be either letters A--Z or numbers 0--9. The highest priority must -have a lower ASCII number than the lowest priority. -@item #+PROPERTY: Property_Name Value -This line sets a default inheritance value for entries in the current -buffer, most useful for specifying the allowed values of a property. -@cindex #+SETUPFILE -@item #+SETUPFILE: file -This line defines a file that holds more in-buffer setup. Normally this is -entirely ignored. Only when the buffer is parsed for option-setting lines -(i.e., when starting Org mode for a file, when pressing @kbd{C-c C-c} in a -settings line, or when exporting), then the contents of this file are parsed -as if they had been included in the buffer. In particular, the file can be -any other Org mode file with internal setup. You can visit the file the -cursor is in the line with @kbd{C-c '}. -@item #+STARTUP: -@cindex #+STARTUP -This line sets options to be used at startup of Org mode, when an -Org file is being visited. - -The first set of options deals with the initial visibility of the outline -tree. The corresponding variable for global default settings is -@code{org-startup-folded}, with a default value @code{t}, which means -@code{overview}. -@vindex org-startup-folded -@cindex @code{overview}, STARTUP keyword -@cindex @code{content}, STARTUP keyword -@cindex @code{showall}, STARTUP keyword -@cindex @code{showeverything}, STARTUP keyword -@example -overview @r{top-level headlines only} -content @r{all headlines} -showall @r{no folding of any entries} -showeverything @r{show even drawer contents} -@end example - -@vindex org-startup-indented -@cindex @code{indent}, STARTUP keyword -@cindex @code{noindent}, STARTUP keyword -Dynamic virtual indentation is controlled by the variable -@code{org-startup-indented}@footnote{Emacs 23 and Org mode 6.29 are required} -@example -indent @r{start with @code{org-indent-mode} turned on} -noindent @r{start with @code{org-indent-mode} turned off} -@end example - -@vindex org-startup-align-all-tables -Then there are options for aligning tables upon visiting a file. This -is useful in files containing narrowed table columns. The corresponding -variable is @code{org-startup-align-all-tables}, with a default value -@code{nil}. -@cindex @code{align}, STARTUP keyword -@cindex @code{noalign}, STARTUP keyword -@example -align @r{align all tables} -noalign @r{don't align tables on startup} -@end example - -@vindex org-startup-with-inline-images -When visiting a file, inline images can be automatically displayed. The -corresponding variable is @code{org-startup-with-inline-images}, with a -default value @code{nil} to avoid delays when visiting a file. -@cindex @code{inlineimages}, STARTUP keyword -@cindex @code{noinlineimages}, STARTUP keyword -@example -inlineimages @r{show inline images} -noinlineimages @r{don't show inline images on startup} -@end example - -@vindex org-startup-with-latex-preview -When visiting a file, @LaTeX{} fragments can be converted to images -automatically. The variable @code{org-startup-with-latex-preview} which -controls this behavior, is set to @code{nil} by default to avoid delays on -startup. -@cindex @code{latexpreview}, STARTUP keyword -@cindex @code{nolatexpreview}, STARTUP keyword -@example -latexpreview @r{preview @LaTeX{} fragments} -nolatexpreview @r{don't preview @LaTeX{} fragments} -@end example - -@vindex org-log-done -@vindex org-log-note-clock-out -@vindex org-log-repeat -Logging the closing and reopening of TODO items and clock intervals can be -configured using these options (see variables @code{org-log-done}, -@code{org-log-note-clock-out} and @code{org-log-repeat}) -@cindex @code{logdone}, STARTUP keyword -@cindex @code{lognotedone}, STARTUP keyword -@cindex @code{nologdone}, STARTUP keyword -@cindex @code{lognoteclock-out}, STARTUP keyword -@cindex @code{nolognoteclock-out}, STARTUP keyword -@cindex @code{logrepeat}, STARTUP keyword -@cindex @code{lognoterepeat}, STARTUP keyword -@cindex @code{nologrepeat}, STARTUP keyword -@cindex @code{logreschedule}, STARTUP keyword -@cindex @code{lognotereschedule}, STARTUP keyword -@cindex @code{nologreschedule}, STARTUP keyword -@cindex @code{logredeadline}, STARTUP keyword -@cindex @code{lognoteredeadline}, STARTUP keyword -@cindex @code{nologredeadline}, STARTUP keyword -@cindex @code{logrefile}, STARTUP keyword -@cindex @code{lognoterefile}, STARTUP keyword -@cindex @code{nologrefile}, STARTUP keyword -@cindex @code{logdrawer}, STARTUP keyword -@cindex @code{nologdrawer}, STARTUP keyword -@cindex @code{logstatesreversed}, STARTUP keyword -@cindex @code{nologstatesreversed}, STARTUP keyword -@example -logdone @r{record a timestamp when an item is marked DONE} -lognotedone @r{record timestamp and a note when DONE} -nologdone @r{don't record when items are marked DONE} -logrepeat @r{record a time when reinstating a repeating item} -lognoterepeat @r{record a note when reinstating a repeating item} -nologrepeat @r{do not record when reinstating repeating item} -lognoteclock-out @r{record a note when clocking out} -nolognoteclock-out @r{don't record a note when clocking out} -logreschedule @r{record a timestamp when scheduling time changes} -lognotereschedule @r{record a note when scheduling time changes} -nologreschedule @r{do not record when a scheduling date changes} -logredeadline @r{record a timestamp when deadline changes} -lognoteredeadline @r{record a note when deadline changes} -nologredeadline @r{do not record when a deadline date changes} -logrefile @r{record a timestamp when refiling} -lognoterefile @r{record a note when refiling} -nologrefile @r{do not record when refiling} -logdrawer @r{store log into drawer} -nologdrawer @r{store log outside of drawer} -logstatesreversed @r{reverse the order of states notes} -nologstatesreversed @r{do not reverse the order of states notes} -@end example - -@vindex org-hide-leading-stars -@vindex org-odd-levels-only -Here are the options for hiding leading stars in outline headings, and for -indenting outlines. The corresponding variables are -@code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a -default setting @code{nil} (meaning @code{showstars} and @code{oddeven}). -@cindex @code{hidestars}, STARTUP keyword -@cindex @code{showstars}, STARTUP keyword -@cindex @code{odd}, STARTUP keyword -@cindex @code{even}, STARTUP keyword -@example -hidestars @r{make all but one of the stars starting a headline invisible.} -showstars @r{show all stars starting a headline} -indent @r{virtual indentation according to outline level} -noindent @r{no virtual indentation according to outline level} -odd @r{allow only odd outline levels (1,3,...)} -oddeven @r{allow all outline levels} -@end example - -@vindex org-put-time-stamp-overlays -@vindex org-time-stamp-overlay-formats -To turn on custom format overlays over timestamps (variables -@code{org-put-time-stamp-overlays} and -@code{org-time-stamp-overlay-formats}), use -@cindex @code{customtime}, STARTUP keyword -@example -customtime @r{overlay custom time format} -@end example - -@vindex constants-unit-system -The following options influence the table spreadsheet (variable -@code{constants-unit-system}). -@cindex @code{constcgs}, STARTUP keyword -@cindex @code{constSI}, STARTUP keyword -@example -constcgs @r{@file{constants.el} should use the c-g-s unit system} -constSI @r{@file{constants.el} should use the SI unit system} -@end example - -@vindex org-footnote-define-inline -@vindex org-footnote-auto-label -@vindex org-footnote-auto-adjust -To influence footnote settings, use the following keywords. The -corresponding variables are @code{org-footnote-define-inline}, -@code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}. -@cindex @code{fninline}, STARTUP keyword -@cindex @code{nofninline}, STARTUP keyword -@cindex @code{fnlocal}, STARTUP keyword -@cindex @code{fnprompt}, STARTUP keyword -@cindex @code{fnauto}, STARTUP keyword -@cindex @code{fnconfirm}, STARTUP keyword -@cindex @code{fnplain}, STARTUP keyword -@cindex @code{fnadjust}, STARTUP keyword -@cindex @code{nofnadjust}, STARTUP keyword -@example -fninline @r{define footnotes inline} -fnnoinline @r{define footnotes in separate section} -fnlocal @r{define footnotes near first reference, but not inline} -fnprompt @r{prompt for footnote labels} -fnauto @r{create @code{[fn:1]}-like labels automatically (default)} -fnconfirm @r{offer automatic label for editing or confirmation} -fnplain @r{create @code{[1]}-like labels automatically} -fnadjust @r{automatically renumber and sort footnotes} -nofnadjust @r{do not renumber and sort automatically} -@end example - -@cindex org-hide-block-startup -To hide blocks on startup, use these keywords. The corresponding variable is -@code{org-hide-block-startup}. -@cindex @code{hideblocks}, STARTUP keyword -@cindex @code{nohideblocks}, STARTUP keyword -@example -hideblocks @r{Hide all begin/end blocks on startup} -nohideblocks @r{Do not hide blocks on startup} -@end example - -@cindex org-pretty-entities -The display of entities as UTF-8 characters is governed by the variable -@code{org-pretty-entities} and the keywords -@cindex @code{entitiespretty}, STARTUP keyword -@cindex @code{entitiesplain}, STARTUP keyword -@example -entitiespretty @r{Show entities as UTF-8 characters where possible} -entitiesplain @r{Leave entities plain} -@end example - -@item #+TAGS: TAG1(c1) TAG2(c2) -@vindex org-tag-alist -These lines (several such lines are allowed) specify the valid tags in -this file, and (potentially) the corresponding @emph{fast tag selection} -keys. The corresponding variable is @code{org-tag-alist}. -@cindex #+TBLFM -@item #+TBLFM: -This line contains the formulas for the table directly above the line. - -Table can have multiple lines containing @samp{#+TBLFM:}. Note -that only the first line of @samp{#+TBLFM:} will be applied when -you recalculate the table. For more details see @ref{Using -multiple #+TBLFM lines} in @ref{Editing and debugging formulas}. - -@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:, -@itemx #+OPTIONS:, #+BIND:, -@itemx #+DESCRIPTION:, #+KEYWORDS:, -@itemx #+LaTeX_HEADER:, #+LaTeX_HEADER_EXTRA:, -@itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:, -@itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS: -These lines provide settings for exporting files. For more details see -@ref{Export settings}. -@item #+TODO: #+SEQ_TODO: #+TYP_TODO: -@vindex org-todo-keywords -These lines set the TODO keywords and their interpretation in the -current file. The corresponding variable is @code{org-todo-keywords}. -@end table - -@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous -@section The very busy C-c C-c key -@kindex C-c C-c -@cindex C-c C-c, overview - -The key @kbd{C-c C-c} has many purposes in Org, which are all -mentioned scattered throughout this manual. One specific function of -this key is to add @emph{tags} to a headline (@pxref{Tags}). In many -other circumstances it means something like @emph{``Hey Org, look -here and update according to what you see here''}. Here is a summary of -what this means in different contexts. - -@itemize @minus -@item -If there are highlights in the buffer from the creation of a sparse -tree, or from clock display, remove these highlights. -@item -If the cursor is in one of the special @code{#+KEYWORD} lines, this -triggers scanning the buffer for these lines and updating the -information. -@item -If the cursor is inside a table, realign the table. This command -works even if the automatic table editor has been turned off. -@item -If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to -the entire table. -@item -If the current buffer is a capture buffer, close the note and file it. -With a prefix argument, file it, without further interaction, to the -default location. -@item -If the cursor is on a @code{<<>>}, update radio targets and -corresponding links in this buffer. -@item -If the cursor is in a property line or at the start or end of a property -drawer, offer property commands. -@item -If the cursor is at a footnote reference, go to the corresponding -definition, and @emph{vice versa}. -@item -If the cursor is on a statistics cookie, update it. -@item -If the cursor is in a plain list item with a checkbox, toggle the status -of the checkbox. -@item -If the cursor is on a numbered item in a plain list, renumber the -ordered list. -@item -If the cursor is on the @code{#+BEGIN} line of a dynamic block, the -block is updated. -@item -If the cursor is at a timestamp, fix the day name in the timestamp. -@end itemize - -@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous -@section A cleaner outline view -@cindex hiding leading stars -@cindex dynamic indentation -@cindex odd-levels-only outlines -@cindex clean outline view - -Some people find it noisy and distracting that the Org headlines start with a -potentially large number of stars, and that text below the headlines is not -indented. While this is no problem when writing a @emph{book-like} document -where the outline headings are really section headings, in a more -@emph{list-oriented} outline, indented structure is a lot cleaner: - -@example -@group -* Top level headline | * Top level headline -** Second level | * Second level -*** 3rd level | * 3rd level -some text | some text -*** 3rd level | * 3rd level -more text | more text -* Another top level headline | * Another top level headline -@end group -@end example - -@noindent - -If you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crash -with @code{org-indent-mode}} and version 6.29 of Org, this kind of view can -be achieved dynamically at display time using @code{org-indent-mode}. In -this minor mode, all lines are prefixed for display with the necessary amount -of space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix} -property, such that @code{visual-line-mode} (or purely setting -@code{word-wrap}) wraps long lines (including headlines) correctly indented. -}. Also headlines are prefixed with additional stars, so that the amount of -indentation shifts by two@footnote{See the variable -@code{org-indent-indentation-per-level}.} spaces per level. All headline -stars but the last one are made invisible using the @code{org-hide} -face@footnote{Turning on @code{org-indent-mode} sets -@code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to -@code{nil}.}; see below under @samp{2.} for more information on how this -works. You can turn on @code{org-indent-mode} for all files by customizing -the variable @code{org-startup-indented}, or you can turn it on for -individual files using - -@example -#+STARTUP: indent -@end example - -If you want a similar effect in an earlier version of Emacs and/or Org, or if -you want the indentation to be hard space characters so that the plain text -file looks as similar as possible to the Emacs display, Org supports you in -the following way: - -@enumerate -@item -@emph{Indentation of text below headlines}@* -You may indent text below each headline to make the left boundary line up -with the headline, like - -@example -*** 3rd level - more text, now indented -@end example - -@vindex org-adapt-indentation -Org supports this with paragraph filling, line wrapping, and structure -editing@footnote{See also the variable @code{org-adapt-indentation}.}, -preserving or adapting the indentation as appropriate. - -@item -@vindex org-hide-leading-stars -@emph{Hiding leading stars}@* You can modify the display in such a way that -all leading stars become invisible. To do this in a global way, configure -the variable @code{org-hide-leading-stars} or change this on a per-file basis -with - -@example -#+STARTUP: hidestars -#+STARTUP: showstars -@end example - -With hidden stars, the tree becomes: - -@example -@group -* Top level headline - * Second level - * 3rd level - ... -@end group -@end example - -@noindent -@vindex org-hide @r{(face)} -The leading stars are not truly replaced by whitespace, they are only -fontified with the face @code{org-hide} that uses the background color as -font color. If you are not using either white or black background, you may -have to customize this face to get the wanted effect. Another possibility is -to set this font such that the extra stars are @i{almost} invisible, for -example using the color @code{grey90} on a white background. - -@item -@vindex org-odd-levels-only -Things become cleaner still if you skip all the even levels and use only odd -levels 1, 3, 5..., effectively adding two stars to go from one outline level -to the next@footnote{When you need to specify a level for a property search -or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc.}. In this -way we get the outline view shown at the beginning of this section. In order -to make the structure editing and export commands handle this convention -correctly, configure the variable @code{org-odd-levels-only}, or set this on -a per-file basis with one of the following lines: - -@example -#+STARTUP: odd -#+STARTUP: oddeven -@end example - -You can convert an Org file from single-star-per-level to the -double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels -RET} in that file. The reverse operation is @kbd{M-x -org-convert-to-oddeven-levels}. -@end enumerate - -@node TTY keys, Interaction, Clean view, Miscellaneous -@section Using Org on a tty -@cindex tty key bindings - -Because Org contains a large number of commands, by default many of -Org's core commands are bound to keys that are generally not -accessible on a tty, such as the cursor keys (@key{left}, @key{right}, -@key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used -together with modifiers like @key{Meta} and/or @key{Shift}. To access -these commands on a tty when special keys are unavailable, the following -alternative bindings can be used. The tty bindings below will likely be -more cumbersome; you may find for some of the bindings below that a -customized workaround suits you better. For example, changing a timestamp -is really only fun with @kbd{S-@key{cursor}} keys, whereas on a -tty you would rather use @kbd{C-c .} to re-insert the timestamp. - -@multitable @columnfractions 0.15 0.2 0.1 0.2 -@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2} -@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab -@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}} -@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab -@item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}} -@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab -@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}} -@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab -@item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}} -@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab -@item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab -@item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}} -@item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab -@item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab -@item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab -@item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab -@item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab -@item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab -@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab -@end multitable - - -@node Interaction, org-crypt, TTY keys, Miscellaneous -@section Interaction with other packages -@cindex packages, interaction with other -Org lives in the world of GNU Emacs and interacts in various ways -with other code out there. - -@menu -* Cooperation:: Packages Org cooperates with -* Conflicts:: Packages that lead to conflicts -@end menu - -@node Cooperation, Conflicts, Interaction, Interaction -@subsection Packages that Org cooperates with - -@table @asis -@cindex @file{calc.el} -@cindex Gillespie, Dave -@item @file{calc.el} by Dave Gillespie -Org uses the Calc package for implementing spreadsheet -functionality in its tables (@pxref{The spreadsheet}). Org -checks for the availability of Calc by looking for the function -@code{calc-eval} which will have been autoloaded during setup if Calc has -been installed properly. As of Emacs 22, Calc is part of the Emacs -distribution. Another possibility for interaction between the two -packages is using Calc for embedded calculations. @xref{Embedded Mode, -, Embedded Mode, calc, GNU Emacs Calc Manual}. -@item @file{constants.el} by Carsten Dominik -@cindex @file{constants.el} -@cindex Dominik, Carsten -@vindex org-table-formula-constants -In a table formula (@pxref{The spreadsheet}), it is possible to use -names for natural constants or units. Instead of defining your own -constants in the variable @code{org-table-formula-constants}, install -the @file{constants} package which defines a large number of constants -and units, and lets you use unit prefixes like @samp{M} for -@samp{Mega}, etc. You will need version 2.0 of this package, available -at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for -the function @code{constants-get}, which has to be autoloaded in your -setup. See the installation instructions in the file -@file{constants.el}. -@item @file{cdlatex.el} by Carsten Dominik -@cindex @file{cdlatex.el} -@cindex Dominik, Carsten -Org mode can make use of the CD@LaTeX{} package to efficiently enter -@LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}. -@item @file{imenu.el} by Ake Stenhoff and Lars Lindberg -@cindex @file{imenu.el} -Imenu allows menu access to an index of items in a file. Org mode -supports Imenu---all you need to do to get the index is the following: -@lisp -(add-hook 'org-mode-hook - (lambda () (imenu-add-to-menubar "Imenu"))) -@end lisp -@vindex org-imenu-depth -By default the index is two levels deep---you can modify the depth using -the option @code{org-imenu-depth}. -@item @file{remember.el} by John Wiegley -@cindex @file{remember.el} -@cindex Wiegley, John -Org used to use this package for capture, but no longer does. -@item @file{speedbar.el} by Eric M. Ludlam -@cindex @file{speedbar.el} -@cindex Ludlam, Eric M. -Speedbar is a package that creates a special frame displaying files and -index items in files. Org mode supports Speedbar and allows you to -drill into Org files directly from the Speedbar. It also allows you to -restrict the scope of agenda commands to a file or a subtree by using -the command @kbd{<} in the Speedbar frame. -@cindex @file{table.el} -@item @file{table.el} by Takaaki Ota -@kindex C-c C-c -@cindex table editor, @file{table.el} -@cindex @file{table.el} -@cindex Ota, Takaaki - -Complex ASCII tables with automatic line wrapping, column- and row-spanning, -and alignment can be created using the Emacs table package by Takaaki Ota -(@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22). -Org mode will recognize these tables and export them properly. Because of -interference with other Org mode functionality, you unfortunately cannot edit -these tables directly in the buffer. Instead, you need to use the command -@kbd{C-c '} to edit them, similar to source code snippets. - -@table @kbd -@orgcmd{C-c ',org-edit-special} -Edit a @file{table.el} table. Works when the cursor is in a table.el table. -@c -@orgcmd{C-c ~,org-table-create-with-table.el} -Insert a @file{table.el} table. If there is already a table at point, this -command converts it between the @file{table.el} format and the Org mode -format. See the documentation string of the command -@code{org-convert-table} for the restrictions under which this is -possible. -@end table -@file{table.el} is part of Emacs since Emacs 22. -@item @file{footnote.el} by Steven L. Baur -@cindex @file{footnote.el} -@cindex Baur, Steven L. -Org mode recognizes numerical footnotes as provided by this package. -However, Org mode also has its own footnote support (@pxref{Footnotes}), -which makes using @file{footnote.el} unnecessary. -@end table - -@node Conflicts, , Cooperation, Interaction -@subsection Packages that lead to conflicts with Org mode - -@table @asis - -@cindex @code{shift-selection-mode} -@vindex org-support-shift-select -In Emacs 23, @code{shift-selection-mode} is on by default, meaning that -cursor motions combined with the shift key should start or enlarge regions. -This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change -timestamps, TODO keywords, priorities, and item bullet types if the cursor is -at such a location. By default, @kbd{S-@key{cursor}} commands outside -special contexts don't do anything, but you can customize the variable -@code{org-support-shift-select}. Org mode then tries to accommodate shift -selection by (i) using it outside of the special contexts where special -commands apply, and by (ii) extending an existing active region even if the -cursor moves across a special context. - -@item @file{CUA.el} by Kim. F. Storm -@cindex @file{CUA.el} -@cindex Storm, Kim. F. -@vindex org-replace-disputed-keys -Key bindings in Org conflict with the @kbd{S-} keys used by CUA mode -(as well as @code{pc-select-mode} and @code{s-region-mode}) to select and extend the -region. In fact, Emacs 23 has this built-in in the form of -@code{shift-selection-mode}, see previous paragraph. If you are using Emacs -23, you probably don't want to use another package for this purpose. However, -if you prefer to leave these keys to a different package while working in -Org mode, configure the variable @code{org-replace-disputed-keys}. When set, -Org will move the following key bindings in Org files, and in the agenda -buffer (but not during date selection). - -@example -S-UP @result{} M-p S-DOWN @result{} M-n -S-LEFT @result{} M-- S-RIGHT @result{} M-+ -C-S-LEFT @result{} M-S-- C-S-RIGHT @result{} M-S-+ -@end example - -@vindex org-disputed-keys -Yes, these are unfortunately more difficult to remember. If you want -to have other replacement keys, look at the variable -@code{org-disputed-keys}. - -@item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org} -@cindex @file{ecomplete.el} - -Ecomplete provides ``electric'' address completion in address header -lines in message buffers. Sadly Orgtbl mode cuts ecompletes power -supply: No completion happens when Orgtbl mode is enabled in message -buffers while entering text in address header lines. If one wants to -use ecomplete one should @emph{not} follow the advice to automagically -turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but -instead---after filling in the message headers---turn on Orgtbl mode -manually when needed in the messages body. - -@item @file{filladapt.el} by Kyle Jones -@cindex @file{filladapt.el} - -Org mode tries to do the right thing when filling paragraphs, list items and -other elements. Many users reported they had problems using both -@file{filladapt.el} and Org mode, so a safe thing to do is to disable it like -this: - -@lisp -(add-hook 'org-mode-hook 'turn-off-filladapt-mode) -@end lisp - -@item @file{yasnippet.el} -@cindex @file{yasnippet.el} -The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of -@code{"\t"}) overrules YASnippet's access to this key. The following code -fixed this problem: - -@lisp -(add-hook 'org-mode-hook - (lambda () - (org-set-local 'yas/trigger-key [tab]) - (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand))) -@end lisp - -The latest version of yasnippet doesn't play well with Org mode. If the -above code does not fix the conflict, start by defining the following -function: - -@lisp -(defun yas/org-very-safe-expand () - (let ((yas/fallback-behavior 'return-nil)) (yas/expand))) -@end lisp - -Then, tell Org mode what to do with the new function: - -@lisp -(add-hook 'org-mode-hook - (lambda () - (make-variable-buffer-local 'yas/trigger-key) - (setq yas/trigger-key [tab]) - (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand) - (define-key yas/keymap [tab] 'yas/next-field))) -@end lisp - -@item @file{windmove.el} by Hovav Shacham -@cindex @file{windmove.el} -This package also uses the @kbd{S-} keys, so everything written -in the paragraph above about CUA mode also applies here. If you want make -the windmove function active in locations where Org mode does not have -special functionality on @kbd{S-@key{cursor}}, add this to your -configuration: - -@lisp -;; Make windmove work in org-mode: -(add-hook 'org-shiftup-final-hook 'windmove-up) -(add-hook 'org-shiftleft-final-hook 'windmove-left) -(add-hook 'org-shiftdown-final-hook 'windmove-down) -(add-hook 'org-shiftright-final-hook 'windmove-right) -@end lisp - -@item @file{viper.el} by Michael Kifer -@cindex @file{viper.el} -@kindex C-c / -Viper uses @kbd{C-c /} and therefore makes this key not access the -corresponding Org mode command @code{org-sparse-tree}. You need to find -another key for this command, or override the key in -@code{viper-vi-global-user-map} with - -@lisp -(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree) -@end lisp - - - -@end table - -@node org-crypt, , Interaction, Miscellaneous -@section org-crypt.el -@cindex @file{org-crypt.el} -@cindex @code{org-decrypt-entry} - -Org-crypt will encrypt the text of an entry, but not the headline, or -properties. Org-crypt uses the Emacs EasyPG library to encrypt and decrypt -files. - -Any text below a headline that has a @samp{:crypt:} tag will be automatically -be encrypted when the file is saved. If you want to use a different tag just -customize the @code{org-crypt-tag-matcher} setting. - -To use org-crypt it is suggested that you have the following in your -@file{.emacs}: - -@lisp -(require 'org-crypt) -(org-crypt-use-before-save-magic) -(setq org-tags-exclude-from-inheritance (quote ("crypt"))) - -(setq org-crypt-key nil) - ;; GPG key to use for encryption - ;; Either the Key ID or set to nil to use symmetric encryption. - -(setq auto-save-default nil) - ;; Auto-saving does not cooperate with org-crypt.el: so you need - ;; to turn it off if you plan to use org-crypt.el quite often. - ;; Otherwise, you'll get an (annoying) message each time you - ;; start Org. - - ;; To turn it off only locally, you can insert this: - ;; - ;; # -*- buffer-auto-save-file-name: nil; -*- -@end lisp - -Excluding the crypt tag from inheritance prevents already encrypted text -being encrypted again. - -@node Hacking, MobileOrg, Miscellaneous, Top -@appendix Hacking -@cindex hacking - -This appendix covers some aspects where users can extend the functionality of -Org. - -@menu -* Hooks:: How to reach into Org's internals -* Add-on packages:: Available extensions -* Adding hyperlink types:: New custom link types -* Adding export back-ends:: How to write new export back-ends -* Context-sensitive commands:: How to add functionality to such commands -* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs -* Dynamic blocks:: Automatically filled blocks -* Special agenda views:: Customized views -* Speeding up your agendas:: Tips on how to speed up your agendas -* Extracting agenda information:: Post-processing of agenda information -* Using the property API:: Writing programs that use entry properties -* Using the mapping API:: Mapping over all or selected entries -@end menu - -@node Hooks, Add-on packages, Hacking, Hacking -@section Hooks -@cindex hooks - -Org has a large number of hook variables that can be used to add -functionality. This appendix about hacking is going to illustrate the -use of some of them. A complete list of all hooks with documentation is -maintained by the Worg project and can be found at -@uref{http://orgmode.org/worg/org-configs/org-hooks.php}. - -@node Add-on packages, Adding hyperlink types, Hooks, Hacking -@section Add-on packages -@cindex add-on packages - -A large number of add-on packages have been written by various authors. - -These packages are not part of Emacs, but they are distributed as contributed -packages with the separate release available at @uref{http://orgmode.org}. -See the @file{contrib/README} file in the source code directory for a list of -contributed files. You may also find some more information on the Worg page: -@uref{http://orgmode.org/worg/org-contrib/}. - -@node Adding hyperlink types, Adding export back-ends, Add-on packages, Hacking -@section Adding hyperlink types -@cindex hyperlinks, adding new types - -Org has a large number of hyperlink types built-in -(@pxref{Hyperlinks}). If you would like to add new link types, Org -provides an interface for doing so. Let's look at an example file, -@file{org-man.el}, that will add support for creating links like -@samp{[[man:printf][The printf manpage]]} to show Unix manual pages inside -Emacs: - -@lisp -;;; org-man.el - Support for links to manpages in Org - -(require 'org) - -(org-add-link-type "man" 'org-man-open) -(add-hook 'org-store-link-functions 'org-man-store-link) - -(defcustom org-man-command 'man - "The Emacs command to be used to display a man page." - :group 'org-link - :type '(choice (const man) (const woman))) - -(defun org-man-open (path) - "Visit the manpage on PATH. -PATH should be a topic that can be thrown at the man command." - (funcall org-man-command path)) - -(defun org-man-store-link () - "Store a link to a manpage." - (when (memq major-mode '(Man-mode woman-mode)) - ;; This is a man page, we do make this link - (let* ((page (org-man-get-page-name)) - (link (concat "man:" page)) - (description (format "Manpage for %s" page))) - (org-store-link-props - :type "man" - :link link - :description description)))) - -(defun org-man-get-page-name () - "Extract the page name from the buffer name." - ;; This works for both `Man-mode' and `woman-mode'. - (if (string-match " \\(\\S-+\\)\\*" (buffer-name)) - (match-string 1 (buffer-name)) - (error "Cannot create link to this man page"))) - -(provide 'org-man) - -;;; org-man.el ends here -@end lisp - -@noindent -You would activate this new link type in @file{.emacs} with - -@lisp -(require 'org-man) -@end lisp - -@noindent -Let's go through the file and see what it does. -@enumerate -@item -It does @code{(require 'org)} to make sure that @file{org.el} has been -loaded. -@item -The next line calls @code{org-add-link-type} to define a new link type -with prefix @samp{man}. The call also contains the name of a function -that will be called to follow such a link. -@item -@vindex org-store-link-functions -The next line adds a function to @code{org-store-link-functions}, in -order to allow the command @kbd{C-c l} to record a useful link in a -buffer displaying a man page. -@end enumerate - -The rest of the file defines the necessary variables and functions. -First there is a customization variable that determines which Emacs -command should be used to display man pages. There are two options, -@code{man} and @code{woman}. Then the function to follow a link is -defined. It gets the link path as an argument---in this case the link -path is just a topic for the manual command. The function calls the -value of @code{org-man-command} to display the man page. - -Finally the function @code{org-man-store-link} is defined. When you try -to store a link with @kbd{C-c l}, this function will be called to -try to make a link. The function must first decide if it is supposed to -create the link for this buffer type; we do this by checking the value -of the variable @code{major-mode}. If not, the function must exit and -return the value @code{nil}. If yes, the link is created by getting the -manual topic from the buffer name and prefixing it with the string -@samp{man:}. Then it must call the command @code{org-store-link-props} -and set the @code{:type} and @code{:link} properties. Optionally you -can also set the @code{:description} property to provide a default for -the link description when the link is later inserted into an Org -buffer with @kbd{C-c C-l}. - -When it makes sense for your new link type, you may also define a function -@code{org-PREFIX-complete-link} that implements special (e.g., completion) -support for inserting such a link with @kbd{C-c C-l}. Such a function should -not accept any arguments, and return the full link with prefix. - -@node Adding export back-ends, Context-sensitive commands, Adding hyperlink types, Hacking -@section Adding export back-ends -@cindex Export, writing back-ends - -Org 8.0 comes with a completely rewritten export engine which makes it easy -to write new export back-ends, either from scratch, or from deriving them -from existing ones. - -Your two entry points are respectively @code{org-export-define-backend} and -@code{org-export-define-derived-backend}. To grok these functions, you -should first have a look at @file{ox-latex.el} (for how to define a new -back-end from scratch) and @file{ox-beamer.el} (for how to derive a new -back-end from an existing one. - -When creating a new back-end from scratch, the basic idea is to set the name -of the back-end (as a symbol) and an an alist of elements and export -functions. On top of this, you will need to set additional keywords like -@code{:menu-entry} (to display the back-end in the export dispatcher), -@code{:export-block} (to specify what blocks should not be exported by this -back-end), and @code{:options-alist} (to let the user set export options that -are specific to this back-end.) - -Deriving a new back-end is similar, except that you need to set -@code{:translate-alist} to an alist of export functions that should be used -instead of the parent back-end functions. - -For a complete reference documentation, see -@url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export -Reference on Worg}. - -@node Context-sensitive commands, Tables in arbitrary syntax, Adding export back-ends, Hacking -@section Context-sensitive commands -@cindex context-sensitive commands, hooks -@cindex add-ons, context-sensitive commands -@vindex org-ctrl-c-ctrl-c-hook - -Org has several commands that act differently depending on context. The most -important example is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}). -Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property. - -Add-ons can tap into this functionality by providing a function that detects -special context for that add-on and executes functionality appropriate for -the context. Here is an example from Dan Davison's @file{org-R.el} which -allows you to evaluate commands based on the @file{R} programming language -@footnote{@file{org-R.el} has been replaced by the Org mode functionality -described in @ref{Working With Source Code} and is now obsolete.}. For this -package, special contexts are lines that start with @code{#+R:} or -@code{#+RR:}. - -@lisp -(defun org-R-apply-maybe () - "Detect if this is context for org-R and execute R commands." - (if (save-excursion - (beginning-of-line 1) - (looking-at "#\\+RR?:")) - (progn (call-interactively 'org-R-apply) - t) ;; to signal that we took action - nil)) ;; to signal that we did not - -(add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe) -@end lisp - -The function first checks if the cursor is in such a line. If that is the -case, @code{org-R-apply} is called and the function returns @code{t} to -signal that action was taken, and @kbd{C-c C-c} will stop looking for other -contexts. If the function finds it should do nothing locally, it returns -@code{nil} so that other, similar functions can have a try. - - -@node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking -@section Tables and lists in arbitrary syntax -@cindex tables, in other modes -@cindex lists, in other modes -@cindex Orgtbl mode - -Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a -frequent feature request has been to make it work with native tables in -specific languages, for example @LaTeX{}. However, this is extremely -hard to do in a general way, would lead to a customization nightmare, -and would take away much of the simplicity of the Orgtbl mode table -editor. - -This appendix describes a different approach. We keep the Orgtbl mode -table in its native format (the @i{source table}), and use a custom -function to @i{translate} the table to the correct syntax, and to -@i{install} it in the right location (the @i{target table}). This puts -the burden of writing conversion functions on the user, but it allows -for a very flexible system. - -Bastien added the ability to do the same with lists, in Orgstruct mode. You -can use Org's facilities to edit and structure lists by turning -@code{orgstruct-mode} on, then locally exporting such lists in another format -(HTML, @LaTeX{} or Texinfo.) - - -@menu -* Radio tables:: Sending and receiving radio tables -* A @LaTeX{} example:: Step by step, almost a tutorial -* Translator functions:: Copy and modify -* Radio lists:: Sending and receiving lists -@end menu - -@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax -@subsection Radio tables -@cindex radio tables - -To define the location of the target table, you first need to create two -lines that are comments in the current mode, but contain magic words -@code{BEGIN/END RECEIVE ORGTBL} for Orgtbl mode to find. Orgtbl mode will -insert the translated table between these lines, replacing whatever was there -before. For example in C mode where comments are between @code{/* ... */}: - -@example -/* BEGIN RECEIVE ORGTBL table_name */ -/* END RECEIVE ORGTBL table_name */ -@end example - -@noindent -Just above the source table, we put a special line that tells -Orgtbl mode how to translate this table and where to install it. For -example: -@cindex #+ORGTBL -@example -#+ORGTBL: SEND table_name translation_function arguments... -@end example - -@noindent -@code{table_name} is the reference name for the table that is also used -in the receiver lines. @code{translation_function} is the Lisp function -that does the translation. Furthermore, the line can contain a list of -arguments (alternating key and value) at the end. The arguments will be -passed as a property list to the translation function for -interpretation. A few standard parameters are already recognized and -acted upon before the translation function is called: - -@table @code -@item :skip N -Skip the first N lines of the table. Hlines do count as separate lines for -this parameter! - -@item :skipcols (n1 n2 ...) -List of columns that should be skipped. If the table has a column with -calculation marks, that column is automatically discarded as well. -Please note that the translator function sees the table @emph{after} the -removal of these columns, the function never knows that there have been -additional columns. - -@item :no-escape t -When non-@code{nil}, do not escape special characters @code{&%#_^} when exporting -the table. The default value is @code{nil}. -@end table - -@noindent -The one problem remaining is how to keep the source table in the buffer -without disturbing the normal workings of the file, for example during -compilation of a C file or processing of a @LaTeX{} file. There are a -number of different solutions: - -@itemize @bullet -@item -The table could be placed in a block comment if that is supported by the -language. For example, in C mode you could wrap the table between -@samp{/*} and @samp{*/} lines. -@item -Sometimes it is possible to put the table after some kind of @i{END} -statement, for example @samp{\bye} in @TeX{} and @samp{\end@{document@}} -in @LaTeX{}. -@item -You can just comment the table line-by-line whenever you want to process -the file, and uncomment it whenever you need to edit the table. This -only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment RET} -makes this comment-toggling very easy, in particular if you bind it to a -key. -@end itemize - -@node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax -@subsection A @LaTeX{} example of radio tables -@cindex @LaTeX{}, and Orgtbl mode - -The best way to wrap the source table in @LaTeX{} is to use the -@code{comment} environment provided by @file{comment.sty}. It has to be -activated by placing @code{\usepackage@{comment@}} into the document -header. Orgtbl mode can insert a radio table skeleton@footnote{By -default this works only for @LaTeX{}, HTML, and Texinfo. Configure the -variable @code{orgtbl-radio-table-templates} to install templates for other -modes.} with the command @kbd{M-x orgtbl-insert-radio-table RET}. You will -be prompted for a table name, let's say we use @samp{salesfigures}. You -will then get the following template: - -@cindex #+ORGTBL, SEND -@example -% BEGIN RECEIVE ORGTBL salesfigures -% END RECEIVE ORGTBL salesfigures -\begin@{comment@} -#+ORGTBL: SEND salesfigures orgtbl-to-latex -| | | -\end@{comment@} -@end example - -@noindent -@vindex @LaTeX{}-verbatim-environments -The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function -@code{orgtbl-to-latex} to convert the table into @LaTeX{} and to put it -into the receiver location with name @code{salesfigures}. You may now -fill in the table---feel free to use the spreadsheet features@footnote{If -the @samp{#+TBLFM} line contains an odd number of dollar characters, -this may cause problems with font-lock in @LaTeX{} mode. As shown in the -example you can fix this by adding an extra line inside the -@code{comment} environment that is used to balance the dollar -expressions. If you are using AUC@TeX{} with the font-latex library, a -much better solution is to add the @code{comment} environment to the -variable @code{LaTeX-verbatim-environments}.}: - -@example -% BEGIN RECEIVE ORGTBL salesfigures -% END RECEIVE ORGTBL salesfigures -\begin@{comment@} -#+ORGTBL: SEND salesfigures orgtbl-to-latex -| Month | Days | Nr sold | per day | -|-------+------+---------+---------| -| Jan | 23 | 55 | 2.4 | -| Feb | 21 | 16 | 0.8 | -| March | 22 | 278 | 12.6 | -#+TBLFM: $4=$3/$2;%.1f -% $ (optional extra dollar to keep font-lock happy, see footnote) -\end@{comment@} -@end example - -@noindent -When you are done, press @kbd{C-c C-c} in the table to get the converted -table inserted between the two marker lines. - -Now let's assume you want to make the table header by hand, because you -want to control how columns are aligned, etc. In this case we make sure -that the table translator skips the first 2 lines of the source -table, and tell the command to work as a @i{splice}, i.e., to not produce -header and footer commands of the target table: - -@example -\begin@{tabular@}@{lrrr@} -Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\ -% BEGIN RECEIVE ORGTBL salesfigures -% END RECEIVE ORGTBL salesfigures -\end@{tabular@} -% -\begin@{comment@} -#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2 -| Month | Days | Nr sold | per day | -|-------+------+---------+---------| -| Jan | 23 | 55 | 2.4 | -| Feb | 21 | 16 | 0.8 | -| March | 22 | 278 | 12.6 | -#+TBLFM: $4=$3/$2;%.1f -\end@{comment@} -@end example - -The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of -Orgtbl mode. It uses a @code{tabular} environment to typeset the table -and marks horizontal lines with @code{\hline}. Furthermore, it -interprets the following parameters (see also @pxref{Translator functions}): - -@table @code -@item :splice nil/t -When set to t, return only table body lines, don't wrap them into a -tabular environment. Default is @code{nil}. - -@item :fmt fmt -A format to be used to wrap each field, it should contain @code{%s} for the -original field value. For example, to wrap each field value in dollars, -you could use @code{:fmt "$%s$"}. This may also be a property list with -column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}. -A function of one argument can be used in place of the strings; the -function must return a formatted string. - -@item :efmt efmt -Use this format to print numbers with exponentials. The format should -have @code{%s} twice for inserting mantissa and exponent, for example -@code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This -may also be a property list with column numbers and formats, for example -@code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After -@code{efmt} has been applied to a value, @code{fmt} will also be -applied. Similar to @code{fmt}, functions of two arguments can be -supplied instead of strings. -@end table - -@node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax -@subsection Translator functions -@cindex HTML, and Orgtbl mode -@cindex translator function - -Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv} -(comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values) -@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}. -Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the same -code that produces tables during HTML export.}, these all use a generic -translator, @code{orgtbl-to-generic}. For example, @code{orgtbl-to-latex} -itself is a very short function that computes the column definitions for the -@code{tabular} environment, defines a few field and line separators and then -hands processing over to the generic translator. Here is the entire code: - -@lisp -@group -(defun orgtbl-to-latex (table params) - "Convert the Orgtbl mode TABLE to LaTeX." - (let* ((alignment (mapconcat (lambda (x) (if x "r" "l")) - org-table-last-alignment "")) - (params2 - (list - :tstart (concat "\\begin@{tabular@}@{" alignment "@}") - :tend "\\end@{tabular@}" - :lstart "" :lend " \\\\" :sep " & " - :efmt "%s\\,(%s)" :hline "\\hline"))) - (orgtbl-to-generic table (org-combine-plists params2 params)))) -@end group -@end lisp - -As you can see, the properties passed into the function (variable -@var{PARAMS}) are combined with the ones newly defined in the function -(variable @var{PARAMS2}). The ones passed into the function (i.e., the -ones set by the @samp{ORGTBL SEND} line) take precedence. So if you -would like to use the @LaTeX{} translator, but wanted the line endings to -be @samp{\\[2mm]} instead of the default @samp{\\}, you could just -overrule the default with - -@example -#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]" -@end example - -For a new language, you can either write your own converter function in -analogy with the @LaTeX{} translator, or you can use the generic function -directly. For example, if you have a language where a table is started -with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are -started with @samp{!BL!}, ended with @samp{!EL!}, and where the field -separator is a TAB, you could call the generic translator like this (on -a single line!): - -@example -#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!" - :lstart "!BL! " :lend " !EL!" :sep "\t" -@end example - -@noindent -Please check the documentation string of the function -@code{orgtbl-to-generic} for a full list of parameters understood by -that function, and remember that you can pass each of them into -@code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function -using the generic function. - -Of course you can also write a completely new function doing complicated -things the generic translator cannot do. A translator function takes -two arguments. The first argument is the table, a list of lines, each -line either the symbol @code{hline} or a list of fields. The second -argument is the property list containing all parameters specified in the -@samp{#+ORGTBL: SEND} line. The function must return a single string -containing the formatted table. If you write a generally useful -translator, please post it on @email{emacs-orgmode@@gnu.org} so that -others can benefit from your work. - -@node Radio lists, , Translator functions, Tables in arbitrary syntax -@subsection Radio lists -@cindex radio lists -@cindex org-list-insert-radio-list - -Sending and receiving radio lists works exactly the same way as sending and -receiving radio tables (@pxref{Radio tables}). As for radio tables, you can -insert radio list templates in HTML, @LaTeX{} and Texinfo modes by calling -@code{org-list-insert-radio-list}. - -Here are the differences with radio tables: - -@itemize @minus -@item -Orgstruct mode must be active. -@item -Use the @code{ORGLST} keyword instead of @code{ORGTBL}. -@item -The available translation functions for radio lists don't take -parameters. -@item -@kbd{C-c C-c} will work when pressed on the first item of the list. -@end itemize - -Here is a @LaTeX{} example. Let's say that you have this in your -@LaTeX{} file: - -@cindex #+ORGLST -@example -% BEGIN RECEIVE ORGLST to-buy -% END RECEIVE ORGLST to-buy -\begin@{comment@} -#+ORGLST: SEND to-buy org-list-to-latex -- a new house -- a new computer - + a new keyboard - + a new mouse -- a new life -\end@{comment@} -@end example - -Pressing @kbd{C-c C-c} on @code{a new house} and will insert the converted -@LaTeX{} list between the two marker lines. - -@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking -@section Dynamic blocks -@cindex dynamic blocks - -Org documents can contain @emph{dynamic blocks}. These are -specially marked regions that are updated by some user-written function. -A good example for such a block is the clock table inserted by the -command @kbd{C-c C-x C-r} (@pxref{Clocking work time}). - -Dynamic blocks are enclosed by a BEGIN-END structure that assigns a name -to the block and can also specify parameters for the function producing -the content of the block. - -@cindex #+BEGIN:dynamic block -@example -#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... - -#+END: -@end example - -Dynamic blocks are updated with the following commands - -@table @kbd -@orgcmd{C-c C-x C-u,org-dblock-update} -Update dynamic block at point. -@orgkey{C-u C-c C-x C-u} -Update all dynamic blocks in the current file. -@end table - -Updating a dynamic block means to remove all the text between BEGIN and -END, parse the BEGIN line for parameters and then call the specific -writer function for this block to insert the new content. If you want -to use the original content in the writer function, you can use the -extra parameter @code{:content}. - -For a block with name @code{myblock}, the writer function is -@code{org-dblock-write:myblock} with as only parameter a property list -with the parameters given in the begin line. Here is a trivial example -of a block that keeps track of when the block update function was last -run: - -@example -#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" - -#+END: -@end example - -@noindent -The corresponding block writer function could look like this: - -@lisp -(defun org-dblock-write:block-update-time (params) - (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) - (insert "Last block update at: " - (format-time-string fmt (current-time))))) -@end lisp - -If you want to make sure that all dynamic blocks are always up-to-date, -you could add the function @code{org-update-all-dblocks} to a hook, for -example @code{before-save-hook}. @code{org-update-all-dblocks} is -written in a way such that it does nothing in buffers that are not in -@code{org-mode}. - -You can narrow the current buffer to the current dynamic block (like any -other block) with @code{org-narrow-to-block}. - -@node Special agenda views, Speeding up your agendas, Dynamic blocks, Hacking -@section Special agenda views -@cindex agenda views, user-defined - -@vindex org-agenda-skip-function -@vindex org-agenda-skip-function-global -Org provides a special hook that can be used to narrow down the selection -made by these agenda views: @code{agenda}, @code{agenda*}@footnote{The -@code{agenda*} view is the same than @code{agenda} except that it only -considers @emph{appointments}, i.e., scheduled and deadline items that have a -time specification @code{[h]h:mm} in their time-stamps.}, @code{todo}, -@code{alltodo}, @code{tags}, @code{tags-todo}, @code{tags-tree}. You may -specify a function that is used at each match to verify if the match should -indeed be part of the agenda view, and if not, how much should be skipped. -You can specify a global condition that will be applied to all agenda views, -this condition would be stored in the variable -@code{org-agenda-skip-function-global}. More commonly, such a definition is -applied only to specific custom searches, using -@code{org-agenda-skip-function}. - -Let's say you want to produce a list of projects that contain a WAITING -tag anywhere in the project tree. Let's further assume that you have -marked all tree headings that define a project with the TODO keyword -PROJECT@. In this case you would run a TODO search for the keyword -PROJECT, but skip the match unless there is a WAITING tag anywhere in -the subtree belonging to the project line. - -To achieve this, you must write a function that searches the subtree for -the tag. If the tag is found, the function must return @code{nil} to -indicate that this match should not be skipped. If there is no such -tag, return the location of the end of the subtree, to indicate that -search should continue from there. - -@lisp -(defun my-skip-unless-waiting () - "Skip trees that are not waiting" - (let ((subtree-end (save-excursion (org-end-of-subtree t)))) - (if (re-search-forward ":waiting:" subtree-end t) - nil ; tag found, do not skip - subtree-end))) ; tag not found, continue after end of subtree -@end lisp - -Now you may use this function in an agenda custom command, for example -like this: - -@lisp -(org-add-agenda-custom-command - '("b" todo "PROJECT" - ((org-agenda-skip-function 'my-skip-unless-waiting) - (org-agenda-overriding-header "Projects waiting for something: ")))) -@end lisp - -@vindex org-agenda-overriding-header -Note that this also binds @code{org-agenda-overriding-header} to get a -meaningful header in the agenda view. - -@vindex org-odd-levels-only -@vindex org-agenda-skip-function -A general way to create custom searches is to base them on a search for -entries with a certain level limit. If you want to study all entries with -your custom search function, simply do a search for -@samp{LEVEL>0}@footnote{Note that, when using @code{org-odd-levels-only}, a -level number corresponds to order in the hierarchy, not to the number of -stars.}, and then use @code{org-agenda-skip-function} to select the entries -you really want to have. - -You may also put a Lisp form into @code{org-agenda-skip-function}. In -particular, you may use the functions @code{org-agenda-skip-entry-if} -and @code{org-agenda-skip-subtree-if} in this form, for example: - -@table @code -@item (org-agenda-skip-entry-if 'scheduled) -Skip current entry if it has been scheduled. -@item (org-agenda-skip-entry-if 'notscheduled) -Skip current entry if it has not been scheduled. -@item (org-agenda-skip-entry-if 'deadline) -Skip current entry if it has a deadline. -@item (org-agenda-skip-entry-if 'scheduled 'deadline) -Skip current entry if it has a deadline, or if it is scheduled. -@item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING")) -Skip current entry if the TODO keyword is TODO or WAITING. -@item (org-agenda-skip-entry-if 'todo 'done) -Skip current entry if the TODO keyword marks a DONE state. -@item (org-agenda-skip-entry-if 'timestamp) -Skip current entry if it has any timestamp, may also be deadline or scheduled. -@anchor{x-agenda-skip-entry-regexp} -@item (org-agenda-skip-entry-if 'regexp "regular expression") -Skip current entry if the regular expression matches in the entry. -@item (org-agenda-skip-entry-if 'notregexp "regular expression") -Skip current entry unless the regular expression matches. -@item (org-agenda-skip-subtree-if 'regexp "regular expression") -Same as above, but check and skip the entire subtree. -@end table - -Therefore we could also have written the search for WAITING projects -like this, even without defining a special function: - -@lisp -(org-add-agenda-custom-command - '("b" todo "PROJECT" - ((org-agenda-skip-function '(org-agenda-skip-subtree-if - 'regexp ":waiting:")) - (org-agenda-overriding-header "Projects waiting for something: ")))) -@end lisp - -@node Speeding up your agendas, Extracting agenda information, Special agenda views, Hacking -@section Speeding up your agendas -@cindex agenda views, optimization - -When your Org files grow in both number and size, agenda commands may start -to become slow. Below are some tips on how to speed up the agenda commands. - -@enumerate -@item -Reduce the number of Org agenda files: this will reduce the slowness caused -by accessing a hard drive. -@item -Reduce the number of DONE and archived headlines: this way the agenda does -not need to skip them. -@item -@vindex org-agenda-dim-blocked-tasks -Inhibit the dimming of blocked tasks: -@lisp -(setq org-agenda-dim-blocked-tasks nil) -@end lisp -@item -@vindex org-startup-folded -@vindex org-agenda-inhibit-startup -Inhibit agenda files startup options: -@lisp -(setq org-agenda-inhibit-startup nil) -@end lisp -@item -@vindex org-agenda-show-inherited-tags -@vindex org-agenda-use-tag-inheritance -Disable tag inheritance in agenda: -@lisp -(setq org-agenda-use-tag-inheritance nil) -@end lisp -@end enumerate - -You can set these options for specific agenda views only. See the docstrings -of these variables for details on why they affect the agenda generation, and -this @uref{http://orgmode.org/worg/agenda-optimization.html, dedicated Worg -page} for further explanations. - -@node Extracting agenda information, Using the property API, Speeding up your agendas, Hacking -@section Extracting agenda information -@cindex agenda, pipe -@cindex Scripts, for agenda processing - -@vindex org-agenda-custom-commands -Org provides commands to access agenda information for the command -line in Emacs batch mode. This extracted information can be sent -directly to a printer, or it can be read by a program that does further -processing of the data. The first of these commands is the function -@code{org-batch-agenda}, that produces an agenda view and sends it as -ASCII text to STDOUT@. The command takes a single string as parameter. -If the string has length 1, it is used as a key to one of the commands -you have configured in @code{org-agenda-custom-commands}, basically any -key you can use after @kbd{C-c a}. For example, to directly print the -current TODO list, you could use - -@example -emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr -@end example - -If the parameter is a string with 2 or more characters, it is used as a -tags/TODO match string. For example, to print your local shopping list -(all items with the tag @samp{shop}, but excluding the tag -@samp{NewYork}), you could use - -@example -emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "+shop-NewYork")' | lpr -@end example - -@noindent -You may also modify parameters on the fly like this: - -@example -emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "a" \ - org-agenda-span (quote month) \ - org-agenda-include-diary nil \ - org-agenda-files (quote ("~/org/project.org")))' \ - | lpr -@end example - -@noindent -which will produce a 30-day agenda, fully restricted to the Org file -@file{~/org/projects.org}, not even including the diary. - -If you want to process the agenda data in more sophisticated ways, you -can use the command @code{org-batch-agenda-csv} to get a comma-separated -list of values for each agenda item. Each line in the output will -contain a number of fields separated by commas. The fields in a line -are: - -@example -category @r{The category of the item} -head @r{The headline, without TODO keyword, TAGS and PRIORITY} -type @r{The type of the agenda entry, can be} - todo @r{selected in TODO match} - tagsmatch @r{selected in tags match} - diary @r{imported from diary} - deadline @r{a deadline} - scheduled @r{scheduled} - timestamp @r{appointment, selected by timestamp} - closed @r{entry was closed on date} - upcoming-deadline @r{warning about nearing deadline} - past-scheduled @r{forwarded scheduled item} - block @r{entry has date block including date} -todo @r{The TODO keyword, if any} -tags @r{All tags including inherited ones, separated by colons} -date @r{The relevant date, like 2007-2-14} -time @r{The time, like 15:00-16:50} -extra @r{String with extra planning info} -priority-l @r{The priority letter if any was given} -priority-n @r{The computed numerical priority} -@end example - -@noindent -Time and date will only be given if a timestamp (or deadline/scheduled) -led to the selection of the item. - -A CSV list like this is very easy to use in a post-processing script. -For example, here is a Perl program that gets the TODO list from -Emacs/Org and prints all the items, preceded by a checkbox: - -@example -#!/usr/bin/perl - -# define the Emacs command to run -$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; - -# run it and capture the output -$agenda = qx@{$cmd 2>/dev/null@}; - -# loop over all lines -foreach $line (split(/\n/,$agenda)) @{ - # get the individual values - ($category,$head,$type,$todo,$tags,$date,$time,$extra, - $priority_l,$priority_n) = split(/,/,$line); - # process and print - print "[ ] $head\n"; -@} -@end example - -@node Using the property API, Using the mapping API, Extracting agenda information, Hacking -@section Using the property API -@cindex API, for properties -@cindex properties, API - -Here is a description of the functions that can be used to work with -properties. - -@defun org-entry-properties &optional pom which -Get all properties of the entry at point-or-marker POM.@* -This includes the TODO keyword, the tags, time strings for deadline, -scheduled, and clocking, and any additional properties defined in the -entry. The return value is an alist. Keys may occur multiple times -if the property key was used several times.@* -POM may also be @code{nil}, in which case the current entry is used. -If WHICH is @code{nil} or `all', get all properties. If WHICH is -`special' or `standard', only get that subclass. -@end defun -@vindex org-use-property-inheritance -@findex org-insert-property-drawer -@defun org-entry-get pom property &optional inherit -Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@. By default, -this only looks at properties defined locally in the entry. If @code{INHERIT} -is non-@code{nil} and the entry does not have the property, then also check -higher levels of the hierarchy. If @code{INHERIT} is the symbol -@code{selective}, use inheritance if and only if the setting of -@code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance. -@end defun - -@defun org-entry-delete pom property -Delete the property @code{PROPERTY} from entry at point-or-marker POM. -@end defun - -@defun org-entry-put pom property value -Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM. -@end defun - -@defun org-buffer-property-keys &optional include-specials -Get all property keys in the current buffer. -@end defun - -@defun org-insert-property-drawer -Insert a property drawer for the current entry. Also -@end defun - -@defun org-entry-put-multivalued-property pom property &rest values -Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@. -@code{VALUES} should be a list of strings. They will be concatenated, with -spaces as separators. -@end defun - -@defun org-entry-get-multivalued-property pom property -Treat the value of the property @code{PROPERTY} as a whitespace-separated -list of values and return the values as a list of strings. -@end defun - -@defun org-entry-add-to-multivalued-property pom property value -Treat the value of the property @code{PROPERTY} as a whitespace-separated -list of values and make sure that @code{VALUE} is in this list. -@end defun - -@defun org-entry-remove-from-multivalued-property pom property value -Treat the value of the property @code{PROPERTY} as a whitespace-separated -list of values and make sure that @code{VALUE} is @emph{not} in this list. -@end defun - -@defun org-entry-member-in-multivalued-property pom property value -Treat the value of the property @code{PROPERTY} as a whitespace-separated -list of values and check if @code{VALUE} is in this list. -@end defun - -@defopt org-property-allowed-value-functions -Hook for functions supplying allowed values for a specific property. -The functions must take a single argument, the name of the property, and -return a flat list of allowed values. If @samp{:ETC} is one of -the values, use the values as completion help, but allow also other values -to be entered. The functions must return @code{nil} if they are not -responsible for this property. -@end defopt - -@node Using the mapping API, , Using the property API, Hacking -@section Using the mapping API -@cindex API, for mapping -@cindex mapping entries, API - -Org has sophisticated mapping capabilities to find all entries satisfying -certain criteria. Internally, this functionality is used to produce agenda -views, but there is also an API that can be used to execute arbitrary -functions for each or selected entries. The main entry point for this API -is: - -@defun org-map-entries func &optional match scope &rest skip -Call @code{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}. - -@code{FUNC} is a function or a Lisp form. The function will be called -without arguments, with the cursor positioned at the beginning of the -headline. The return values of all calls to the function will be collected -and returned as a list. - -The call to @code{FUNC} will be wrapped into a save-excursion form, so -@code{FUNC} does not need to preserve point. After evaluation, the cursor -will be moved to the end of the line (presumably of the headline of the -processed entry) and search continues from there. Under some circumstances, -this may not produce the wanted results. For example, if you have removed -(e.g., archived) the current (sub)tree it could mean that the next entry will -be skipped entirely. In such cases, you can specify the position from where -search should continue by making @code{FUNC} set the variable -@code{org-map-continue-from} to the desired buffer position. - -@code{MATCH} is a tags/property/todo match as it is used in the agenda match -view. Only headlines that are matched by this query will be considered -during the iteration. When @code{MATCH} is @code{nil} or @code{t}, all -headlines will be visited by the iteration. - -@code{SCOPE} determines the scope of this command. It can be any of: - -@example -nil @r{the current buffer, respecting the restriction if any} -tree @r{the subtree started with the entry at point} -region @r{The entries within the active region, if any} -file @r{the current buffer, without restriction} -file-with-archives - @r{the current buffer, and any archives associated with it} -agenda @r{all agenda files} -agenda-with-archives - @r{all agenda files with any archive files associated with them} -(file1 file2 ...) - @r{if this is a list, all files in the list will be scanned} -@end example -@noindent -The remaining args are treated as settings for the skipping facilities of -the scanner. The following items can be given here: - -@vindex org-agenda-skip-function -@example -archive @r{skip trees with the archive tag} -comment @r{skip trees with the COMMENT keyword} -function or Lisp form - @r{will be used as value for @code{org-agenda-skip-function},} - @r{so whenever the function returns t, FUNC} - @r{will not be called for that entry and search will} - @r{continue from the point where the function leaves it} -@end example -@end defun - -The function given to that mapping routine can really do anything you like. -It can use the property API (@pxref{Using the property API}) to gather more -information about the entry, or in order to change metadata in the entry. -Here are a couple of functions that might be handy: - -@defun org-todo &optional arg -Change the TODO state of the entry. See the docstring of the functions for -the many possible values for the argument @code{ARG}. -@end defun - -@defun org-priority &optional action -Change the priority of the entry. See the docstring of this function for the -possible values for @code{ACTION}. -@end defun - -@defun org-toggle-tag tag &optional onoff -Toggle the tag @code{TAG} in the current entry. Setting @code{ONOFF} to -either @code{on} or @code{off} will not toggle tag, but ensure that it is -either on or off. -@end defun - -@defun org-promote -Promote the current entry. -@end defun - -@defun org-demote -Demote the current entry. -@end defun - -Here is a simple example that will turn all entries in the current file with -a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}. -Entries in comment trees and in archive trees will be ignored. - -@lisp -(org-map-entries - '(org-todo "UPCOMING") - "+TOMORROW" 'file 'archive 'comment) -@end lisp - -The following example counts the number of entries with TODO keyword -@code{WAITING}, in all agenda files. - -@lisp -(length (org-map-entries t "/+WAITING" 'agenda)) -@end lisp - -@node MobileOrg, History and Acknowledgments, Hacking, Top -@appendix MobileOrg -@cindex iPhone -@cindex MobileOrg - -@i{MobileOrg} is the name of the mobile companion app for Org mode, currently -available for iOS and for Android. @i{MobileOrg} offers offline viewing and -capture support for an Org mode system rooted on a ``real'' computer. It -does also allow you to record changes to existing entries. The -@uref{https://github.com/MobileOrg/, iOS implementation} for the -@i{iPhone/iPod Touch/iPad} series of devices, was started by Richard Moreland -and is now in the hands Sean Escriva. Android users should check out -@uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android} -by Matt Jones. The two implementations are not identical but offer similar -features. - -This appendix describes the support Org has for creating agenda views in a -format that can be displayed by @i{MobileOrg}, and for integrating notes -captured and changes made by @i{MobileOrg} into the main system. - -For changing tags and TODO states in MobileOrg, you should have set up the -customization variables @code{org-todo-keywords} and @code{org-tag-alist} to -cover all important tags and TODO keywords, even if individual files use only -part of these. MobileOrg will also offer you states and tags set up with -in-buffer settings, but it will understand the logistics of TODO state -@i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags -(@pxref{Setting tags}) only for those set in these variables. - -@menu -* Setting up the staging area:: Where to interact with the mobile device -* Pushing to MobileOrg:: Uploading Org files and agendas -* Pulling from MobileOrg:: Integrating captured and flagged items -@end menu - -@node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg -@section Setting up the staging area - -MobileOrg needs to interact with Emacs through a directory on a server. If you -are using a public server, you should consider to encrypt the files that are -uploaded to the server. This can be done with Org mode 7.02 and with -@i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl} -installation on your system. To turn on encryption, set a password in -@i{MobileOrg} and, on the Emacs side, configure the variable -@code{org-mobile-use-encryption}@footnote{If you can safely store the -password in your Emacs setup, you might also want to configure -@code{org-mobile-encryption-password}. Please read the docstring of that -variable. Note that encryption will apply only to the contents of the -@file{.org} files. The file names themselves will remain visible.}. - -The easiest way to create that directory is to use a free -@uref{http://dropbox.com,Dropbox.com} account@footnote{If you cannot use -Dropbox, or if your version of MobileOrg does not support it, you can use a -webdav server. For more information, check out the documentation of MobileOrg and also this -@uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}. -When MobileOrg first connects to your Dropbox, it will create a directory -@i{MobileOrg} inside the Dropbox. After the directory has been created, tell -Emacs about it: - -@lisp -(setq org-mobile-directory "~/Dropbox/MobileOrg") -@end lisp - -Org mode has commands to put files for @i{MobileOrg} into that directory, -and to read captured notes from there. - -@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg -@section Pushing to MobileOrg - -This operation copies all files currently listed in @code{org-mobile-files} -to the directory @code{org-mobile-directory}. By default this list contains -all agenda files (as listed in @code{org-agenda-files}), but additional files -can be included by customizing @code{org-mobile-files}. File names will be -staged with paths relative to @code{org-directory}, so all files should be -inside this directory@footnote{Symbolic links in @code{org-directory} need to -have the same name than their targets.}. - -The push operation also creates a special Org file @file{agendas.org} with -all custom agenda view defined by the user@footnote{While creating the -agendas, Org mode will force ID properties on all referenced entries, so that -these entries can be uniquely identified if @i{MobileOrg} flags them for -further action. If you do not want to get these properties in so many -entries, you can set the variable @code{org-mobile-force-id-on-agenda-items} -to @code{nil}. Org mode will then rely on outline paths, in the hope that -these will be unique enough.}. - -Finally, Org writes the file @file{index.org}, containing links to all other -files. @i{MobileOrg} first reads this file from the server, and then -downloads all agendas and Org files listed in it. To speed up the download, -MobileOrg will only read files whose checksums@footnote{Checksums are stored -automatically in the file @file{checksums.dat}} have changed. - -@node Pulling from MobileOrg, , Pushing to MobileOrg, MobileOrg -@section Pulling from MobileOrg - -When @i{MobileOrg} synchronizes with the server, it not only pulls the Org -files for viewing. It also appends captured entries and pointers to flagged -and changed entries to the file @file{mobileorg.org} on the server. Org has -a @emph{pull} operation that integrates this information into an inbox file -and operates on the pointers to flagged entries. Here is how it works: - -@enumerate -@item -Org moves all entries found in -@file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this -operation.} and appends them to the file pointed to by the variable -@code{org-mobile-inbox-for-pull}. Each captured entry and each editing event -will be a top-level entry in the inbox file. -@item -After moving the entries, Org will attempt to implement the changes made in -@i{MobileOrg}. Some changes are applied directly and without user -interaction. Examples are all changes to tags, TODO state, headline and body -text that can be cleanly applied. Entries that have been flagged for further -action will receive a tag @code{:FLAGGED:}, so that they can be easily found -again. When there is a problem finding an entry or applying the change, the -pointer entry will remain in the inbox and will be marked with an error -message. You need to later resolve these issues by hand. -@item -Org will then generate an agenda view with all flagged entries. The user -should then go through these entries and do whatever actions are necessary. -If a note has been stored while flagging an entry in @i{MobileOrg}, that note -will be displayed in the echo area when the cursor is on the corresponding -agenda line. - -@table @kbd -@kindex ? -@item ? -Pressing @kbd{?} in that special agenda will display the full flagging note in -another window and also push it onto the kill ring. So you could use @kbd{? -z C-y C-c C-c} to store that flagging note as a normal note in the entry. -Pressing @kbd{?} twice in succession will offer to remove the -@code{:FLAGGED:} tag along with the recorded flagging note (which is stored -in a property). In this way you indicate that the intended processing for -this flagged entry is finished. -@end table -@end enumerate - -@kindex C-c a ? -If you are not able to process all flagged entries directly, you can always -return to this agenda view@footnote{Note, however, that there is a subtle -difference. The view created automatically by @kbd{M-x org-mobile-pull RET} -is guaranteed to search all files that have been addressed by the last pull. -This might include a file that is not currently in your list of agenda files. -If you later use @kbd{C-c a ?} to regenerate the view, only the current -agenda files will be searched.} using @kbd{C-c a ?}. - -@node History and Acknowledgments, GNU Free Documentation License, MobileOrg, Top -@appendix History and acknowledgments -@cindex acknowledgments -@cindex history -@cindex thanks - -@section From Carsten - -Org was born in 2003, out of frustration over the user interface of the Emacs -Outline mode. I was trying to organize my notes and projects, and using -Emacs seemed to be the natural way to go. However, having to remember eleven -different commands with two or three keys per command, only to hide and show -parts of the outline tree, that seemed entirely unacceptable to me. Also, -when using outlines to take notes, I constantly wanted to restructure the -tree, organizing it parallel to my thoughts and plans. @emph{Visibility -cycling} and @emph{structure editing} were originally implemented in the -package @file{outline-magic.el}, but quickly moved to the more general -@file{org.el}. As this environment became comfortable for project planning, -the next step was adding @emph{TODO entries}, basic @emph{timestamps}, and -@emph{table support}. These areas highlighted the two main goals that Org -still has today: to be a new, outline-based, plain text mode with innovative -and intuitive editing features, and to incorporate project planning -functionality directly into a notes file. - -Since the first release, literally thousands of emails to me or to -@email{emacs-orgmode@@gnu.org} have provided a constant stream of bug -reports, feedback, new ideas, and sometimes patches and add-on code. -Many thanks to everyone who has helped to improve this package. I am -trying to keep here a list of the people who had significant influence -in shaping one or more aspects of Org. The list may not be -complete, if I have forgotten someone, please accept my apologies and -let me know. - -Before I get to this list, a few special mentions are in order: - -@table @i -@item Bastien Guerry -Bastien has written a large number of extensions to Org (most of them -integrated into the core by now), including the @LaTeX{} exporter and the plain -list parser. His support during the early days, when he basically acted as -co-maintainer, was central to the success of this project. Bastien also -invented Worg, helped establishing the Web presence of Org, and sponsored -hosting costs for the orgmode.org website. -@item Eric Schulte and Dan Davison -Eric and Dan are jointly responsible for the Org-babel system, which turns -Org into a multi-language environment for evaluating code and doing literate -programming and reproducible research. -@item John Wiegley -John has contributed a number of great ideas and patches directly to Org, -including the attachment system (@file{org-attach.el}), integration with -Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO -items, habit tracking (@file{org-habits.el}), and encryption -(@file{org-crypt.el}). Also, the capture system is really an extended copy -of his great @file{remember.el}. -@item Sebastian Rose -Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work -of an ignorant amateur. Sebastian has pushed this part of Org onto a much -higher level. He also wrote @file{org-info.js}, a Java script for displaying -web pages derived from Org using an Info-like or a folding interface with -single-key navigation. -@end table - -@noindent See below for the full list of contributions! Again, please -let me know what I am missing here! - -@section From Bastien - -I (Bastien) have been maintaining Org since January 2011. This appendix -would not be complete without adding a few more acknowledgements and thanks -to Carsten's ones above. - -I am first grateful to Carsten for his trust while handing me over the -maintainership of Org. His unremitting support is what really helped me -getting more confident over time, with both the community and the code. - -When I took over maintainership, I knew I would have to make Org more -collaborative than ever, as I would have to rely on people that are more -knowledgeable than I am on many parts of the code. Here is a list of the -persons I could rely on, they should really be considered co-maintainers, -either of the code or the community: - -@table @i -@item Eric Schulte -Eric is maintaining the Babel parts of Org. His reactivity here kept me away -from worrying about possible bugs here and let me focus on other parts. - -@item Nicolas Goaziou -Nicolas is maintaining the consistency of the deepest parts of Org. His -work on @file{org-element.el} and @file{ox.el} has been outstanding, and -opened the doors for many new ideas and features. He rewrote many of the -old exporters to use the new export engine, and helped with documenting -this major change. More importantly (if that's possible), he has been more -than reliable during all the work done for Org 8.0, and always very -reactive on the mailing list. - -@item Achim Gratz -Achim rewrote the building process of Org, turning some @emph{ad hoc} tools -into a flexible and conceptually clean process. He patiently coped with the -many hiccups that such a change can create for users. - -@item Nick Dokos -The Org mode mailing list would not be such a nice place without Nick, who -patiently helped users so many times. It is impossible to overestimate such -a great help, and the list would not be so active without him. -@end table - -I received support from so many users that it is clearly impossible to be -fair when shortlisting a few of them, but Org's history would not be -complete if the ones above were not mentioned in this manual. - -@section List of contributions - -@itemize @bullet - -@item -@i{Russel Adams} came up with the idea for drawers. -@item -@i{Suvayu Ali} has steadily helped on the mailing list, providing useful -feedback on many features and several patches. -@item -@i{Luis Anaya} wrote @file{ox-man.el}. -@item -@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}. -@item -@i{Michael Brand} helped by reporting many bugs and testing many features. -He also implemented the distinction between empty fields and 0-value fields -in Org's spreadsheets. -@item -@i{Christophe Bataillon} created the great unicorn logo that we use on the -Org mode website. -@item -@i{Alex Bochannek} provided a patch for rounding timestamps. -@item -@i{Jan Böcker} wrote @file{org-docview.el}. -@item -@i{Brad Bozarth} showed how to pull RSS feed data into Org mode files. -@item -@i{Tom Breton} wrote @file{org-choose.el}. -@item -@i{Charles Cave}'s suggestion sparked the implementation of templates -for Remember, which are now templates for capture. -@item -@i{Pavel Chalmoviansky} influenced the agenda treatment of items with -specified time. -@item -@i{Gregory Chernov} patched support for Lisp forms into table -calculations and improved XEmacs compatibility, in particular by porting -@file{nouline.el} to XEmacs. -@item -@i{Sacha Chua} suggested copying some linking code from Planner. -@item -@i{Toby S. Cubitt} contributed to the code for clock formats. -@item -@i{Baoqiu Cui} contributed the DocBook exporter. It has been deleted from -Org 8.0: you can now export to Texinfo and export the @file{.texi} file to -DocBook using @code{makeinfo}. -@item -@i{Eddward DeVilla} proposed and tested checkbox statistics. He also -came up with the idea of properties, and that there should be an API for -them. -@item -@i{Nick Dokos} tracked down several nasty bugs. -@item -@i{Kees Dullemond} used to edit projects lists directly in HTML and so -inspired some of the early development, including HTML export. He also -asked for a way to narrow wide table columns. -@item -@i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for -several years now. He also sponsored the hosting costs until Rackspace -started to host us for free. -@item -@i{Thomas S. Dye} contributed documentation on Worg and helped integrating -the Org-Babel documentation into the manual. -@item -@i{Christian Egli} converted the documentation into Texinfo format, inspired -the agenda, patched CSS formatting into the HTML exporter, and wrote -@file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as -@file{ox-taskjuggler.el} for Org 8.0. -@item -@i{David Emery} provided a patch for custom CSS support in exported -HTML agendas. -@item -@i{Sean Escriva} took over MobileOrg development on the iPhone platform. -@item -@i{Nic Ferrier} contributed mailcap and XOXO support. -@item -@i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes. -@item -@i{John Foerch} figured out how to make incremental search show context -around a match in a hidden outline tree. -@item -@i{Raimar Finken} wrote @file{org-git-line.el}. -@item -@i{Mikael Fornius} works as a mailing list moderator. -@item -@i{Austin Frank} works as a mailing list moderator. -@item -@i{Eric Fraga} drove the development of BEAMER export with ideas and -testing. -@item -@i{Barry Gidden} did proofreading the manual in preparation for the book -publication through Network Theory Ltd. -@item -@i{Niels Giesen} had the idea to automatically archive DONE trees. -@item -@i{Nicolas Goaziou} rewrote much of the plain list code. He also wrote -@file{org-element.el} and @file{org-export.el}, which was a huge step forward -in implementing a clean framework for Org exporters. -@item -@i{Kai Grossjohann} pointed out key-binding conflicts with other packages. -@item -@i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a -book. -@item -@i{Bernt Hansen} has driven much of the support for auto-repeating tasks, -task state change logging, and the clocktable. His clear explanations have -been critical when we started to adopt the Git version control system. -@item -@i{Manuel Hermenegildo} has contributed various ideas, small fixes and -patches. -@item -@i{Phil Jackson} wrote @file{org-irc.el}. -@item -@i{Scott Jaderholm} proposed footnotes, control over whitespace between -folded entries, and column view for properties. -@item -@i{Matt Jones} wrote @i{MobileOrg Android}. -@item -@i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}. -@item -@i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}. -@item -@i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also -provided frequent feedback and some patches. -@item -@i{Matt Lundin} has proposed last-row references for table formulas and named -invisible anchors. He has also worked a lot on the FAQ. -@item -@i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org, -and is a prolific contributor on the mailing list with competent replies, -small fixes and patches. -@item -@i{Jason F. McBrayer} suggested agenda export to CSV format. -@item -@i{Max Mikhanosha} came up with the idea of refiling and sticky agendas. -@item -@i{Dmitri Minaev} sent a patch to set priority limits on a per-file -basis. -@item -@i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler -happy. -@item -@i{Richard Moreland} wrote @i{MobileOrg} for the iPhone. -@item -@i{Rick Moynihan} proposed allowing multiple TODO sequences in a file -and being able to quickly restrict the agenda to a subtree. -@item -@i{Todd Neal} provided patches for links to Info files and Elisp forms. -@item -@i{Greg Newman} refreshed the unicorn logo into its current form. -@item -@i{Tim O'Callaghan} suggested in-file links, search options for general -file links, and TAGS. -@item -@i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text -version of the reference card. -@item -@i{Takeshi Okano} translated the manual and David O'Toole's tutorial -into Japanese. -@item -@i{Oliver Oppitz} suggested multi-state TODO items. -@item -@i{Scott Otterson} sparked the introduction of descriptive text for -links, among other things. -@item -@i{Pete Phillips} helped during the development of the TAGS feature, and -provided frequent feedback. -@item -@i{Francesco Pizzolante} provided patches that helped speeding up the agenda -generation. -@item -@i{Martin Pohlack} provided the code snippet to bundle character insertion -into bundles of 20 for undo. -@item -@i{Rackspace.com} is hosting our website for free. Thank you Rackspace! -@item -@i{T.V. Raman} reported bugs and suggested improvements. -@item -@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality -control. -@item -@i{Paul Rivier} provided the basic implementation of named footnotes. He -also acted as mailing list moderator for some time. -@item -@i{Kevin Rogers} contributed code to access VM files on remote hosts. -@item -@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a -conflict with @file{allout.el}. -@item -@i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with -extensive patches. -@item -@i{Philip Rooke} created the Org reference card, provided lots -of feedback, developed and applied standards to the Org documentation. -@item -@i{Christian Schlauer} proposed angular brackets around links, among -other things. -@item -@i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can -enjoy folding in non-org buffers by using Org headlines in comments. -@item -@i{Paul Sexton} wrote @file{org-ctags.el}. -@item -Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s -@file{organizer-mode.el}. -@item -@i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal -examples, and remote highlighting for referenced code lines. -@item -@i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is -now packaged into Org's @file{contrib} directory. -@item -@i{Daniel Sinder} came up with the idea of internal archiving by locking -subtrees. -@item -@i{Dale Smith} proposed link abbreviations. -@item -@i{James TD Smith} has contributed a large number of patches for useful -tweaks and features. -@item -@i{Adam Spiers} asked for global linking commands, inspired the link -extension system, added support for mairix, and proposed the mapping API. -@item -@i{Ulf Stegemann} created the table to translate special symbols to HTML, -@LaTeX{}, UTF-8, Latin-1 and ASCII. -@item -@i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content -with links transformation to Org syntax. -@item -@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual -chapter about publishing. -@item -@i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter. -@item -@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and -enabled source code highlighting in Gnus. -@item -@i{Stefan Vollmar} organized a video-recorded talk at the -Max-Planck-Institute for Neurology. He also inspired the creation of a -concept index for HTML export. -@item -@i{J@"urgen Vollmer} contributed code generating the table of contents -in HTML output. -@item -@i{Samuel Wales} has provided important feedback and bug reports. -@item -@i{Chris Wallace} provided a patch implementing the @samp{QUOTE} -keyword. -@item -@i{David Wainberg} suggested archiving, and improvements to the linking -system. -@item -@i{Carsten Wimmer} suggested some changes and helped fix a bug in -linking to Gnus. -@item -@i{Roland Winkler} requested additional key bindings to make Org -work on a tty. -@item -@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks -and contributed various ideas and code snippets. -@end itemize - - -@node GNU Free Documentation License, Main Index, History and Acknowledgments, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Main Index, Key Index, GNU Free Documentation License, Top -@unnumbered Concept index - -@printindex cp - -@node Key Index, Command and Function Index, Main Index, Top -@unnumbered Key index - -@printindex ky - -@node Command and Function Index, Variable Index, Key Index, Top -@unnumbered Command and function index - -@printindex fn - -@node Variable Index, , Command and Function Index, Top -@unnumbered Variable index - -This is not a complete index of variables and faces, only the ones that are -mentioned in the manual. For a more complete list, use @kbd{M-x -org-customize @key{RET}} and then click yourself through the tree. - -@printindex vr - -@bye - -@c Local variables: -@c fill-column: 77 -@c indent-tabs-mode: nil -@c paragraph-start: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" -@c paragraph-separate: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" -@c End: - - -@c LocalWords: webdavhost pre diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi deleted file mode 100644 index 6b56bc03223..00000000000 --- a/doc/misc/pcl-cvs.texi +++ /dev/null @@ -1,1441 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/pcl-cvs -@settitle PCL-CVS---Emacs Front-End to CVS -@syncodeindex vr fn -@documentencoding UTF-8 -@c %**end of header - -@copying -Copyright @copyright{} 1991--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* PCL-CVS: (pcl-cvs). Emacs front-end to CVS. -@end direntry - -@c The titlepage section does not appear in the Info file. -@titlepage -@sp 4 -@c The title is printed in a large font. -@center @titlefont{User's Guide} -@sp 1 -@center @titlefont{to} -@sp 1 -@center @titlefont{PCL-CVS---The Emacs Front-End to CVS} -@ignore -@sp 2 -@center release 2.9 -@c -release- -@end ignore -@sp 3 -@center Per Cederqvist -@center Stefan Monnier -@c -date- - -@c The following two commands start the copyright page -@c for the printed manual. This will not appear in the Info file. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c ================================================================ -@c The real text starts here -@c ================================================================ - -@ifnottex -@node Top -@top PCL-CVS - -This manual describes PCL-CVS, the GNU Emacs front-end to CVS@. It -is nowhere near complete, so you are advised to use @kbd{M-x -customize-group RET pcl-cvs @key{RET}} and to look at the documentation strings -of the various commands and major modes for further information. -@c This manual is updated to release 2.5 of PCL-CVS. - -@insertcopying - -@end ifnottex - -@menu -* About PCL-CVS:: Credits, history, @dots{} - -* Getting started:: An introduction with a walk-through example. -* Buffer contents:: An explanation of the buffer contents. -* Selected files:: To which files are commands applied. -* Commands:: All commands, grouped by type. - -* Log Edit Mode:: Major mode to edit log messages. -* Log View Mode:: Major mode to browse log changes. -@c * CVS Status Mode:: Major mode to view CVS' status output. -* Customization:: How you can tailor PCL-CVS to suit your needs. -* Bugs:: Bugs (known and unknown). - -* GNU Free Documentation License:: The license for this documentation. -* Function and Variable Index:: List of functions and variables. -* Concept Index:: List of concepts. -* Key Index:: List of keystrokes. - -@detailmenu - --- The Detailed Node Listing --- - -About PCL-CVS - -* Contributors:: Contributors to PCL-CVS. - -Commands - -* Entering PCL-CVS:: Commands to invoke PCL-CVS -* Setting flags:: Setting flags for CVS commands -* Updating the buffer:: -* Movement commands:: How to move up and down in the buffer -* Marking files:: How to mark files that other commands - will later operate on. -* Committing changes:: Checking in your modifications to the - CVS repository. -* Editing files:: Loading files into Emacs. -* Getting info about files:: Display the log and status of files. -* Adding and removing files:: Adding and removing files -* Undoing changes:: Undoing changes -* Removing handled entries:: Uninteresting lines can easily be removed. -* Ignoring files:: Telling CVS to ignore generated files. -* Viewing differences:: Commands to @samp{diff} different versions. -* Invoking Ediff:: Running @samp{ediff} from @file{*cvs*} buffer. -* Updating files:: Updating files that Need-update. -* Tagging files:: Tagging files. -* Miscellaneous commands:: Miscellaneous commands. - -Customization - -* Customizing Faces:: - -@end detailmenu -@end menu - -@node About PCL-CVS -@chapter About PCL-CVS -@cindex About PCL-CVS - -PCL-CVS is a front-end to CVS versions 1.9 and later. -It concisely shows the present status of a checked out module in an -Emacs buffer and provides single-key access to the most frequently used CVS -commands. Note that the @code{vc-dir} command (@pxref{VC Directory -Mode, , , emacs, The GNU Emacs Manual}) provides similar -functionality, but for several version control systems, including CVS. - -PCL-CVS was originally written many years ago by Per Cederqvist who -proudly maintained it until January 1996, at which point he released the -beta version 2.0b2 and passed on the maintainership to Greg A Woods. -Development stayed mostly dormant for a few years during which -version 2.0 never seemed to be able to leave the ``beta'' stage while a -separate XEmacs version was slowly splitting away. In late 1998, -Stefan Monnier picked up development again, adding some major new -functionality and taking over the maintenance. - -@menu -* Contributors:: Contributors to PCL-CVS. -@end menu - -@node Contributors -@section Contributors to PCL-CVS -@cindex Contributors -@cindex Authors - -Contributions to the package are welcome. I have limited time to work -on this project, but I will gladly add any code that you contribute to -me to this package (@pxref{Bugs}). - -The following persons have made contributions to PCL-CVS. - -@itemize @bullet -@item -Brian Berliner wrote CVS, together with some other contributors. -Without his work on CVS this package would be useless@dots{} - -@item -Per Cederqvist wrote most of the otherwise unattributed functions in -PCL-CVS as well as all the documentation. - -@item -@c inge@@lysator.liu.se -Inge Wallin wrote the skeleton of -@file{pcl-cvs.texi}, and gave useful comments on it. He also wrote -the files @file{elib-node.el} and @file{compile-all.el}. The file -@file{cookie.el} was inspired by Inge. - -@item -@c linus@@lysator.liu.se -Linus Tolke contributed useful comments -on both the functionality and the documentation. - -@item -@c jwz@@jwz.com -Jamie Zawinski contributed -@file{pcl-cvs-lucid.el}, which was later renamed to -@file{pcl-cvs-xemacs.el}. - -@item -Leif Lonnblad contributed RCVS support (since superseded by the new -remote CVS support). - -@item -@c jimb@@cyclic.com -Jim Blandy contributed hooks to automatically -guess CVS log entries from @file{ChangeLog} contents, and initial support of -the new Cygnus / Cyclic remote CVS, as well as various sundry bug fixes -and cleanups. - -@item -@c kingdon@@cyclic.com -Jim Kingdon contributed lots of fixes to -the build and installation procedure. - -@item -@c woods@@weird.com -Greg A. Woods contributed code to implement -the use of per-file diff buffers, and vendor join diffs with emerge and -ediff, as well as various and sundry bug fixes and cleanups. - -@item -@c greg.klanderman@@alum.mit.edu -Greg Klanderman implemented -toggling of marked files, setting of CVS command flags via prefix -arguments, updated the XEmacs support, updated the manual, and fixed -numerous bugs. - -@item -@c monnier@@gnu.org -Stefan Monnier added a slew of other -features and introduced even more new bugs. If there's any bug left, -you can be sure it's his. - -@item -@c wordy to avoid an underfull hbox -@c masata-y@@is.aist-nara.ac.jp -Masatake YAMATO made a gracious -contribution of his cvstree code to display a tree of tags which was later -superseded by the new @code{cvs-status-mode}. -@end itemize - -Apart from these, a lot of people have sent us suggestions, ideas, -requests, bug reports and encouragement. Thanks a lot! Without you -there would be no new releases of PCL-CVS. - - -@node Getting started -@chapter Getting started -@cindex Introduction -@cindex Example run -@cindex Sample session - -This document assumes that you know what CVS is, and that you at least -know the fundamental concepts of CVS@. If that is not the case, you -should read the CVS documentation. Type @kbd{info -f cvs} or @kbd{man -cvs}. - -PCL-CVS is only useful once you have checked out a module. So before -you invoke it, you must have a copy of a module somewhere in the file -system. - -You can invoke PCL-CVS by typing @kbd{M-x cvs-examine @key{RET}}. -You can also invoke it via the menu bar, under @samp{Tools}. -Or, if you prefer, you can also invoke PCL-CVS by simply visiting the -CVS administrative subdirectory of your module, with a prefix argument. -For example, to invoke PCL-CVS in a separate frame, type @kbd{C-u C-x 5 -f ~/my/project/CVS @key{RET}}. - -The function @code{cvs-examine} will ask for a directory. The command -@samp{cvs -n update} will be run in that directory. (It should contain -files that have been checked out from a CVS archive.) The output from -@code{cvs} will be parsed and presented in a table in a buffer called -@file{*cvs*}. It might look something like this: - -@example -Repository : /usr/CVSroot -Module : test -Working dir: /users/ceder/FOO/test - - -In directory .: - Need-Update bar - Need-Update file.txt - Modified namechange - Need-Update newer -In directory sub: - Modified ChangeLog - ---------------------- End --------------------- --- last cmd: cvs -f -z6 -n update -d -P -- -@end example - -In this example, your repository is in @file{/usr/CVSroot} and CVS has -been run in the directory @file{/users/ceder/FOO/test}. The three files -(@file{bar}, @file{file.txt} and -@file{newer}) that are marked with @samp{Need-Update} have been changed -by someone else in the CVS repository. Two files (@file{namechange} -and @file{sub/ChangeLog}) have been modified locally, and need to be -checked in. - -You can move the cursor up and down in the buffer with @kbd{C-n} and -@kbd{C-p} or @kbd{n} and @kbd{p}. If you press @kbd{c} on one of the -@samp{Modified} files, that file will be checked in to the CVS -repository. @xref{Committing changes}. You can also press @kbd{O} to -update any of the files that are marked @samp{Need-Update}. You can -also run @kbd{M-x cvs-update @key{RET}} (bound to @kbd{M-u} in the -@file{*cvs*} buffer) to update all the files. - -You can then press @kbd{=} to easily get a @samp{diff} between your -modified file and the base version that you started from, or you can -press @kbd{l} to get the output from @samp{cvs log}. Many more such -commands are available simply by pressing a key (@pxref{Getting info -about files}). - -@node Buffer contents -@chapter Buffer contents -@cindex Buffer contents -@cindex @file{*cvs*} buffer contents - -The display contains several columns, some of which are optional. -These columns are, from left to right: - -@itemize @bullet - -@item -Optionally, the head revision of the file. This is the latest version -found in the repository. It might also contain (instead of the head -revision) a sub status which typically gives further information about -how we got to the current state, for example @samp{patched}, -@samp{merged}, @dots{} - -@item -An asterisk when the file is @dfn{marked} (@pxref{Selected -files}). - -@item -The actual status of the file wrt the repository. See below. - -@item -Optionally, the base revision of the file. This is the version -which the copy in your working directory is based upon. - -@item -The file name. - -@end itemize - -The @samp{file status} field can have the following values: - -@table @samp -@item Modified -The file is modified in your working directory, and there was no -modification to the same file in the repository. This status can have -the following substatus: - -@table @samp -@item merged -The file was modified in your working directory, and there were -modifications in the repository as well, but they were merged -successfully, without conflict, in your working directory. -@end table - -@item Conflict -A conflict was detected while trying to merge your changes to @var{file} -with changes from the repository. @var{file} (the copy in your -working directory) is now the output of the @code{rcsmerge} command on -the two versions; an unmodified copy of your file is also in your -working directory, with the name @file{.#@var{file}.@var{version}}, -where @var{version} is the RCS revision that your modified file started -from. @xref{Viewing differences}, for more details. - -A conflict can also come from a disagreement on the existence of the file -rather than on its content. This case is indicated by the following -possible substatus: - -@table @samp -@item removed -The file is locally removed but a new revision has been committed to -the repository by someone else. - -@item added -The file is locally added and has also been added to the repository -by someone else. - -@item modified -The file is locally modified but someone else has removed it from the -repository. -@end table - -@item Added -The file has been added by you, but it still needs to be checked in to -the repository. - -@item Removed -The file has been removed by you, but it still needs to be checked in to -the repository. You can resurrect it by typing @kbd{a} (@pxref{Adding -and removing files}). - -@item Unknown -A file that was detected in your directory, but that neither appears in -the repository, nor is present on the list of files that CVS should -ignore. - -@item Up-to-date -The file is up to date with respect to the version in the repository. -This status can have a substatus of: - -@table @samp -@item added -You have just added the file to the repository. - -@item updated -The file was brought up to date with respect to the repository. This is -done for any file that exists in the repository but not in your source, -and for files that you haven't changed but are not the most recent -versions available in the repository. - -@item patched -The file was brought up to date with respect to the remote repository by -way of fetching and applying a patch to the file in your source. This -is equivalent to @samp{updated} except that CVS decided to use a hopefully -more efficient method. - -@item committed -You just committed the file. -@end table - -@item Need-Update -Either a newer version than the one in your source is available in the -repository and you have not modified your checked out version, or the -file exists in the repository but not in your source. Use -@samp{cvs-mode-update} bound to @kbd{O} to update the file. - -@item Need-Merge -You have modified the checked out version of the file, and a newer -version is available in the repository. A merge will take place when -you run a @samp{cvs-update}. - -@item Missing -The file has been unexpectedly removed from your working directory -although it has not been @samp{cvs remove}d. -@end table - -@node Selected files -@chapter Selected files -@cindex Selected files -@cindex Marked files -@cindex File selection -@cindex Active files -@cindex Applicable - -Many of the commands work on the current set of @dfn{selected} files -which can be either the set of marked files (if any file is marked and -marks are not ignored) or whichever file or directory the cursor is on. - -If a directory is selected but the command cannot be applied to a -directory, then it will be applied to the set of files under this -directory which are in the @file{*cvs*} buffer. - -@findex cvs-mode-force-command -@findex cvs-allow-dir-commit -Furthermore, each command only operates on a subset of the selected -files, depending on whether or not the command is @dfn{applicable} to -each file (based on the file's status). For example, -@code{cvs-mode-commit} is not applicable to a file whose status is -@samp{Need-Update}. If it should happen that PCL-CVS guesses the -applicability wrong, you can override it with the special prefix -@code{cvs-mode-force-command} normally bound to @kbd{M-f} (and file a -bug report). The applicability rule can be slightly changed with -@code{cvs-allow-dir-commit} and @code{cvs-force-dir-tag}. - -By default, marks are always in effect (you may change this, however, by -setting the variable @code{cvs-default-ignore-marks}) except for the -commands that @samp{tag} or @samp{diff} a file (which can be changed -with the variable @code{cvs-invert-ignore-marks}). - -In addition, you may use the special prefix @code{cvs-mode-toggle-marks} -normally bound to @key{T} to toggle the use of marks for the following -command. - -This scheme might seem a little complicated, but once one gets used to -it, it is quite powerful. - -For commands to mark and unmark files, see @ref{Marking files}. - -@node Commands -@chapter Commands - -@iftex -This chapter describes all the commands that you can use in PCL-CVS. -@end iftex -@ifnottex -The nodes in this menu contains explanations about all the commands that -you can use in PCL-CVS@. They are grouped together by type. -@end ifnottex - -@menu -* Entering PCL-CVS:: Commands to invoke PCL-CVS -* Setting flags:: Setting flags for CVS commands -* Updating the buffer:: -* Movement commands:: How to move up and down in the buffer -* Marking files:: How to mark files that other commands - will later operate on. -* Committing changes:: Checking in your modifications to the - CVS repository. -* Editing files:: Loading files into Emacs. -* Getting info about files:: Display the log and status of files. -* Adding and removing files:: Adding and removing files -* Undoing changes:: Undoing changes -* Removing handled entries:: Uninteresting lines can easily be removed. -* Ignoring files:: Telling CVS to ignore generated files. -* Viewing differences:: Commands to @samp{diff} different versions. -* Invoking Ediff:: Running @samp{ediff} from @file{*cvs*} buffer. -* Updating files:: Updating files that Need-update. -* Tagging files:: Tagging files. -* Miscellaneous commands:: Miscellaneous commands. -@end menu - - -@node Entering PCL-CVS -@section Entering PCL-CVS -@findex cvs-update -@findex cvs-examine -@findex cvs-status -@findex cvs-checkout -@findex cvs-quickdir -@cindex Creating the *cvs* buffer - -Most commands in PCL-CVS require that you have a @file{*cvs*} -buffer. The commands that you use to get one are listed below. -For each, a @samp{cvs} process will be run, the output will be parsed by -PCL-CVS, and the result will be printed in the @file{*cvs*} buffer (see -@ref{Buffer contents}, for a description of the buffer's contents). - -@table @kbd -@item M-x cvs-update -Run a @samp{cvs update} command. You will be asked for the directory -in which the @samp{cvs update} will be run. - -@item M-x cvs-examine -Run a @samp{cvs -n update} command. This is identical to the previous -command, except that it will only check what needs to be done but will -not change anything. You will be asked for the directory in -which the @samp{cvs -n update} will be run. - -@item M-x cvs-status -Run a @samp{cvs status} command. You will be asked for the directory -in which the @samp{cvs status} will be run. - -@item M-x cvs-checkout -Run a @samp{cvs checkout} command. You will be asked for the directory -in which the @samp{cvs update} will be run and the module to be checked -out. - -@item M-x cvs-quickdir -Populate the @file{*cvs*} buffer by just looking at the @file{CVS/Entries} -files. This is very much like @code{cvs-examine} except that it does -not access the CVS repository, which is a major advantage when the -repository is far away. But of course, it will not be able to detect -when a file needs to be updated or merged. -@end table - -@findex cvs-dired-action -@findex cvs-dired-use-hook -The first four of -those commands are also reachable from the menu bar -under @samp{Tools->PCL-CVS}. Finally, an alternative way is to visit -the CVS administrative subdirectory in your work area with a simple -prefix argument. For example @kbd{C-u C-x C-f ~/my/work/CVS @key{RET}}. This -by default runs @code{cvs-quickdir} but the specific behavior can be -changed with @code{cvs-dired-action} and @code{cvs-dired-use-hook}. - -By default, the commands above will descend recursively into -subdirectories. You can avoid that behavior by including @samp{-l} in -the flags for the command. These flags can be set by giving a prefix -argument to the command (e.g., by typing -@kbd{C-u M-x cvs-update @key{RET} -l @key{RET}}). - - -@node Setting flags -@section Setting flags for CVS commands -@cindex Optional switches to CVS -@cindex Command-line options to CVS - -This section describes the convention used by nearly all PCL-CVS -commands for setting optional flags sent to CVS@. A single @kbd{C-u} -prefix argument is used to cause the command to prompt for flags to be -used for the current invocation of the command only. Two @kbd{C-u} prefix -arguments are used to prompt for flags which will be set permanently, for the -current invocation and all that follow, until the flags are changed, or -unless temporary flags are set which override them. - -Perhaps an example or two is in order. Say you are about to add a -binary file to the repository, and want to specify the flags @samp{-kb} -to @samp{cvs add}. You can type @kbd{C-u a -kb @key{RET}}, -and the file will be added. Subsequent @samp{cvs add} -commands will use the previously prevailing flags. - -As a second example, say you are about to perform a diff and want to see -the result in unified diff format, i.e., you'd like to pass the flag -@samp{-u} to both @samp{cvs diff} and @samp{diff}. You'd also like all -subsequent diffs to use this flag. You can type @kbd{C-u C-u = -u @key{RET}} -and the diff will be performed, and the default flags will be set to -@code{("-u")}. You can of course override this flag for a single diff -by using a single @kbd{C-u} prefix argument. - -@cindex Special prefix -In addition to this, some commands can take @dfn{special prefix} arguments. -These work as follows: When called with a @kbd{C-u} prefix, the user is -prompted for a new value of the special prefix and the special prefix is -activated for the next command. When called without the @kbd{C-u} -prefix, the special prefix is re-activated (with the same value as last -time) for the next command. Calling the prefix command again when it's -already activated deactivates it. Calling it with the @kbd{C-u C-u} -prefix activates it for all subsequent commands until you deactivate it -explicitly. The special prefixes are: - -@table @kbd -@item T -Toggles whether or not marks will be active in the next command. - -@item b -Provide the next command with a branch (can be any version -specifier) to work on. - -@item B -Secondary branch argument. Only meaningful if @kbd{b} is also used. -It can be used to provide a second branch argument to -@code{cvs-mode-diff} or to @code{cvs-mode-update}. - -@item M-f -Forces the next command to apply to every selected file rather than only -to the ones PCL-CVS thinks are relevant. -@end table - -@node Updating the buffer -@section Updating the @file{*cvs*} buffer -@findex cvs-update -@findex cvs-examine -@findex cvs-status -@findex cvs-mode-update -@findex cvs-mode-examine -@findex cvs-mode-status - -The following commands can be used from within the @file{*cvs*} buffer -to update the display: - -@table @kbd -@item M-u -Runs the command @samp{cvs-update}. - -@item M-e -Runs the command @samp{cvs-examine}. - -@item M-s -Runs the command @samp{cvs-status}. -@end table - -In addition to the above commands which operate on the whole module, -you can run the equivalent CVS command on just a subset of the -files/directories with these keys: - -@table @kbd -@item O -Runs @code{cvs-mode-update} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-u}. - -@item e -Runs @code{cvs-mode-examine} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-e}. - -@findex cvs-status-mode -@item s -Runs @code{cvs-mode-status} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-s}, except that -CVS output will be shown in a @file{*cvs-info*} buffer that will be -put in @samp{cvs-status-mode}. -@end table - - -@node Movement commands -@section Movement Commands -@cindex Movement Commands -@findex cvs-mode-next-line -@findex cvs-mode-previous-line -@kindex SPC@r{--Move down one file} -@kindex n@r{--Move down one file} -@kindex p@r{--Move up one file} - -You can use most normal Emacs commands to move forward and backward in -the buffer. Some keys are rebound to functions that take advantage of -the fact that the buffer is a PCL-CVS buffer: - - -@table @kbd -@item @key{SPC} -@itemx n -These keys move the cursor one file forward, towards the end of the -buffer (@code{cvs-mode-next-line}). - -@item p -This key moves one file backward, towards the beginning of the buffer -(@code{cvs-mode-previous-line}). -@end table - - -@node Marking files -@section Marking files -@cindex Selecting files (commands to mark files) -@cindex Marking files -@kindex m@r{--marking a file} -@kindex M@r{--marking all files} -@kindex u@r{--unmark a file} -@kindex ESC DEL@r{--unmark all files} -@kindex DEL@r{--unmark previous file} -@kindex %@r{--mark files matching regexp} -@kindex S@r{--mark files in a particular state} -@kindex T@r{--toggle marks} -@findex cvs-mode-mark -@findex cvs-mode-unmark -@findex cvs-mode-mark-all-files -@findex cvs-mode-unmark-all-files -@findex cvs-mode-unmark-up -@findex cvs-mode-mark-matching-files -@findex cvs-mode-mark-on-state -@findex cvs-mode-toggle-marks - -PCL-CVS works on a set of @dfn{selected files} (@pxref{Selected files}). -You can mark and unmark files with these commands: - -@table @kbd -@item m -This marks the file that the cursor is positioned on. If the cursor is -positioned on a directory all files in that directory are marked -(@code{cvs-mode-mark}). - -@item u -Unmark the file that the cursor is positioned on. If the cursor is on a -directory, all files in that directory are unmarked -(@code{cvs-mode-unmark}). - -@item M -Mark @emph{all} files in the buffer (@code{cvs-mode-mark-all-files}). - -@item M-@key{DEL} -Unmark @emph{all} files (@code{cvs-mode-unmark-all-files}). - -@item @key{DEL} -Unmark the file on the previous line, and move point to that line -(@code{cvs-mode-unmark-up}). - -@item % -Mark all files matching a regular expression -(@code{cvs-mode-mark-matching-files}). - -@item S -Mark all files in a particular state, such as ``Modified'' or -``Removed'' (@code{cvs-mode-mark-on-state}). - -@item T -Toggle use of marks for the next command (@code{cvs-mode-toggle-marks}). -@end table - - -@node Committing changes -@section Committing changes -@cindex Committing changes -@findex cvs-mode-commit -@findex cvs-mode-commit-setup -@kindex c@r{--commit files} -@kindex C@r{--commit files with @file{ChangeLog} message} -@vindex cvs-auto-revert@r{ (variable)} -@cindex Commit buffer -@cindex Edit buffer -@cindex Erasing commit message -@cindex Reverting buffers after commit - -Committing changes basically works as follows: - -@enumerate -@item -After having selected the files you want to commit, you type either -@kbd{c} or @kbd{C} which brings up a special buffer -@file{*cvs-commit*}. - -@item -You type in the log message describing the changes you're about to -commit (@pxref{Log Edit Mode}). - -@item -When you're happy with it, you type @kbd{C-c C-c} to do the actual -commit. -@end enumerate - -There's no hidden state, so you can abort the process or pick it up -again at any time. - -@vindex log-edit-confirm@r{ (variable)} -The set of files actually committed is really decided only during the -very last step, which is a mixed blessing. It allows you to go back and -change your mind about which files to commit, but it also means that you -might inadvertently change the set of selected files. To reduce the -risk of error, @kbd{C-c C-c} will ask for confirmation if the set of -selected files has changed between the first step and the last. You can -change this last detail with @code{log-edit-confirm}. - -As for the difference between @kbd{c} (i.e., @code{cvs-mode-commit}) and -@kbd{C} (i.e., @code{cvs-mode-commit-setup}) is that the first gets you -straight to @file{*cvs-commit*} without erasing it or changing anything -to its content, while the second first erases @file{*cvs-commit*} -and tries to initialize it with a sane default (it does that by either -using a template provided by the CVS administrator or by extracting a -relevant log message from a @file{ChangeLog} file). - -If you are editing the files in your Emacs, an automatic -@samp{revert-buffer} will be performed. (If the file contains -@samp{$@asis{Id}$} keywords, @samp{cvs commit} will write a new file with -the new values substituted. The auto-revert makes sure that you get -them into your buffer.) The revert will not occur if you have modified -your buffer, or if @samp{cvs-auto-revert} is set to -@samp{nil}. - - -@node Editing files -@section Editing files -@cindex Editing files -@cindex Finding files -@cindex Loading files -@cindex Dired -@cindex Invoking dired -@findex cvs-mode-find-file -@findex cvs-mode-find-file-other-window -@findex cvs-mode-add-change-log-entry-other-window -@kindex f@r{--find file or directory} -@kindex o@r{--find file in other window} -@kindex A@r{--add @file{ChangeLog} entry} - -There are currently three commands that can be used to find a file (that -is, load it into a buffer and start editing it there). These commands -work on the line that the cursor is situated at. They always ignore any marked -files. - -@table @kbd -@item f -Find the file that the cursor points to (@code{cvs-mode-find-file}). If -the cursor points to a directory, run @code{dired} on that directory; -@inforef{Dired, , emacs}. - -@item o -Like @kbd{f}, but use another window -(@code{cvs-mode-find-file-other-window}). - -@item A -Invoke @samp{add-change-log-entry-other-window} to edit a -@file{ChangeLog} file. The @file{ChangeLog} file will be found in the -directory of the file the cursor points to, or in a parent of that -directory (@code{cvs-mode-add-change-log-entry-other-window}). -@end table - - -@node Getting info about files -@section Getting info about files -@cindex Status (cvs command) -@cindex Log (RCS/cvs command) -@cindex Getting status -@kindex l@r{--run @samp{cvs log}} -@kindex s@r{--run @samp{cvs status}} -@findex cvs-mode-log -@findex cvs-mode-status - -@table @kbd -@item l -Call the command @code{cvs-mode-log} which runs @samp{cvs log} on all -selected files, and show the result in a temporary buffer -@file{*cvs-info*} (@pxref{Log View Mode}). - -@item s -Call the command @code{cvs-mode-status} which runs @samp{cvs status} on -all selected files, and show the result in a temporary buffer -@file{*cvs-info*}. -@c Fixme: reinstate when node is written: -@c (@pxref{CVS Status Mode}). -@end table - - -@node Adding and removing files -@section Adding and removing files -@cindex Adding files -@cindex Removing files -@cindex Resurrecting files -@cindex Deleting files -@cindex Putting files under CVS control -@kindex a@r{--add a file} -@kindex r@r{--remove a file} -@findex cvs-mode-add -@findex cvs-mode-remove-file - -The following commands are available to make it easy to add files to -and remove them from the CVS repository. - -@table @kbd -@item a -Add all selected files. This command can be used on @samp{Unknown} -files (@pxref{Buffer contents}). The status of the file will change to -@samp{Added}, and you will have to use @kbd{c} (@samp{cvs-mode-commit} -@pxref{Committing changes}), to really add the file to the -repository. - -This command can also be used on @samp{Removed} files (before you commit -them) to resurrect them. - -The command that is run is @code{cvs-mode-add}. - -@item r -This command removes the selected files (after prompting for -confirmation). The files are deleted from your directory and -(unless the status was @samp{Unknown}; @pxref{Buffer contents}) they will -also be @samp{cvs remove}d. If the files' status was @samp{Unknown} -they will disappear from the buffer. Otherwise their status will change to -@samp{Removed}, and you must use @kbd{c} (@samp{cvs-mode-commit}, -@pxref{Committing changes}) to commit the removal. - -The command that is run is @code{cvs-mode-remove-file}. -@end table - - -@node Undoing changes -@section Undoing changes -@cindex Undo changes -@cindex Flush changes -@kindex U@r{--undo changes} -@findex cvs-mode-undo-local-changes - -@table @kbd -@item U -If you have modified a file, and for some reason decide that you don't -want to keep the changes, you can undo them with this command. It works -by removing your working copy of the file and then getting the latest -version from the repository (@code{cvs-mode-undo-local-changes}). -@end table - - -@node Removing handled entries -@section Removing handled entries -@cindex Expunging uninteresting entries -@cindex Uninteresting entries, getting rid of them -@cindex Getting rid of uninteresting lines -@cindex Removing uninteresting (processed) lines -@cindex Handled lines, removing them -@kindex x@r{--remove processed entries} -@kindex C-k@r{--remove selected entries} -@findex cvs-mode-remove-handled -@findex cvs-mode-acknowledge -@findex cvs-mode-ignore - -@table @kbd -@item x -This command allows you to remove all entries that you have processed. -More specifically, the lines for @samp{Up-to-date} files (@pxref{Buffer -contents}) are removed from the buffer. If a directory becomes empty -the heading for that directory is also removed. This makes it easier to -get an overview of what needs to be done. - -@vindex cvs-mode-remove-handled@r{ (variable)} -@kbd{x} invokes @code{cvs-mode-remove-handled}. If -@samp{cvs-auto-remove-handled} is set to non-@code{nil}, this will -automatically be performed after every commit. - -@item C-k -This command can be used for lines that @samp{cvs-mode-remove-handled} would -not delete, but that you want to delete (@code{cvs-mode-acknowledge}). -@end table - - -@node Ignoring files -@section Ignoring files -@cindex Ignoring files -@kindex i@r{--ignoring files} -@findex cvs-mode-ignore - -@table @kbd -@item i -Arrange so that CVS will ignore the selected files. The file names are -added to the @file{.cvsignore} file in the corresponding directory. If -the @file{.cvsignore} file doesn't exist, it will be created. - -The @file{.cvsignore} file should normally be added to the repository, -but you could ignore it as well, if you like it better that way. - -This runs @code{cvs-mode-ignore}. -@end table - -@node Viewing differences -@section Viewing differences -@cindex Diff -@cindex Invoking @code{diff} -@cindex Conflicts, how to resolve them -@cindex Viewing differences -@kindex d=@r{--run @samp{cvs diff}} -@kindex =@r{--run @samp{cvs diff}} -@kindex db@r{--diff against base version} -@kindex dh@r{--diff against head of repository} -@kindex dr@r{--diff between base and head of repository} -@kindex dv@r{--diff against vendor branch} -@kindex dy@r{--diff against yesterday's head} -@findex cvs-mode-diff -@findex cvs-mode-diff-backup -@findex cvs-mode-diff-head -@findex cvs-mode-diff-repository -@findex cvs-mode-diff-vendor -@findex cvs-mode-diff-yesterday -@vindex cvs-invert-ignore-marks@r{ (variable)} - -@table @kbd -@item = -@itemx d = -Display a @samp{cvs diff} between the selected files and the version -that they are based on (@code{cvs-mode-diff}). - -@item d b -If CVS finds a conflict while merging two versions of a file (during a -@samp{cvs update}, @pxref{Updating the buffer}) it will save the -original file in a file called @file{.#@var{file}.@var{version}} where -@var{file} is the name of the file, and @var{version} is the revision -number that @var{file} was based on. - -With the @kbd{d b} command you can run a @samp{diff} on the files -@file{.#@var{file}.@var{version}} and @file{@var{file}}. - -@item d h -Display a @samp{cvs diff} between the selected files and the head -revision (the most recent version on the current -branch) in the repository (@code{cvs-mode-diff-head}). - -@item d r -Display a @samp{cvs diff} between the base revision of the selected -files and the head revision in the repository. This displays the -changes anyone has committed to the repository since you last executed -a checkout, update or commit operation -(@code{cvs-mode-diff-repository}). - -@item d v -Display a @samp{cvs diff} between the selected files and the head -revision of the vendor branch in the repository -(@code{cvs-mode-diff-vendor}). - -@item d y -Display a @samp{cvs diff} between the selected files and yesterday's -head revision in the repository -(@code{cvs-mode-diff-yesterday}). -@end table - -By default, @samp{diff} commands ignore the marks. This can be changed -with @code{cvs-invert-ignore-marks}. - -@node Invoking Ediff -@section Running ediff -@cindex Ediff -@cindex Invoking ediff -@cindex Viewing differences -@cindex Conflicts, how to resolve them -@cindex Resolving conflicts -@kindex e@r{--invoke @samp{ediff}} -@findex cvs-mode-idiff -@findex cvs-mode-imerge - -@table @kbd -@vindex cvs-idiff-imerge-handlers@r{ (variable)} -@item d e -This uses @code{ediff} (or @code{emerge}, depending on -@samp{cvs-idiff-imerge-handlers}) to allow you to view diffs. -If a prefix argument is given, PCL-CVS will prompt for a revision against -which the diff should be made, else the default will be to use the BASE -revision. - -@cindex Merging with @code{ediff} and @code{emerge} -@item d E -This command use @code{ediff} (or @code{emerge}, see above) to allow you -to do an interactive 3-way merge. - -@strong{Please note:} when the file status is @samp{Conflict}, -CVS has already performed a merge. The resulting file is not used in -any way if you use this command. If you use the @kbd{q} command inside -@samp{ediff} (to successfully terminate a merge) the file that CVS -created will be overwritten. -@end table - -@node Updating files -@section Updating files -@findex cvs-mode-update -@cindex Updating files -@kindex O@r{--update files} - -@table @kbd -@item O -Update all selected files with status @samp{Need-update} by running -@samp{cvs update} on them (@code{cvs-mode-update}). -@end table - - -@node Tagging files -@section Tagging files -@findex cvs-mode-tag -@findex cvs-mode-untag -@findex cvs-rtag -@cindex Tagging files -@kindex M-t@r{--repository tag files} -@kindex t@r{--tag files} -@vindex cvs-invert-ignore-marks@r{ (variable)} -@vindex cvs-force-dir-tag@r{ (variable)} - -@table @kbd -@item t -Tag all selected files by running @samp{cvs tag} on -them (@code{cvs-mode-tag}). It's usually preferable to tag a directory -at a time. Rather than selecting all files (which too often doesn't -select all files but only the few that are displayed), clear the -selection with @kbd{M-DEL} (@code{cvs-mode-unmark-all-files}), position -the cursor on the directory you want to tag and hit @kbd{t}. -@end table - -By default, @samp{tag} commands ignore the marks. This can be changed -with @code{cvs-invert-ignore-marks}. Also, by default @samp{tag} can -only be applied to directories, see @code{cvs-force-dir-tag} if you want -to change this behavior. - - -@node Miscellaneous commands -@section Miscellaneous commands -@findex cvs-mode-byte-compile-files -@cindex Recompiling elisp files -@cindex Byte compilation -@findex cvs-mode-delete-lock -@cindex Getting rid of lock files -@cindex Lock files -@kindex q@r{--bury the PCL-CVS buffer} -@findex cvs-bury-buffer -@findex cvs-mode-quit -@cindex Quitting -@kindex h@r{--help} -@kindex ?@r{--help} -@findex cvs-help -@cindex Help - -@table @kbd -@item M-x cvs-mode-byte-compile-files -Byte compile all selected files that end in @file{.el}. - -@item M-x cvs-mode-delete-lock -This command deletes the lock files that -the @file{*cvs*} buffer informs you about. You should normally never have to -use this command, since CVS tries very carefully to always remove the -lock files itself. - -You can only use this command when a message in the @file{*cvs*} buffer tells -you so. You should wait a while before using this command in case -someone else is running a @code{cvs} command. - -Also note that this only works if the repository is local. - -@item ? -@itemx h -Show a summary of common command key bindings in the echo -area (@code{cvs-help}). - -@item q -Bury the PCL-CVS buffer (@code{cvs-bury-buffer}). - -@item M-x cvs-mode-quit -Quit PCL-CVS, killing the @file{*cvs*} buffer. -@end table - -@node Log Edit Mode -@chapter Editing a Log Message - -@cindex Log Edit mode -@cindex mode, Log Edit -Buffers for entering/editing log messages for changes which are about -to be committed are put into Log Edit mode. - -Sometimes the log buffer contains default text when you enter it, -typically the last log message entered. If it does, mark and point -are set around the entire contents of the buffer so that it is easy to -kill the contents of the buffer with @kbd{C-w}. - -@findex log-edit-insert-changelog -If you work by writing entries in the @file{ChangeLog} -(@pxref{Change Log,,, emacs, The GNU Emacs Manual}) and then commit the change under revision -control, you can generate the Log Edit text from the ChangeLog using -@kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for -entries for the file(s) concerned in the top entry in the ChangeLog -and uses those paragraphs as the log text. This text is only inserted -if the top entry was made under your user name on the current date. -@xref{Change Logs and VC,,, emacs, The GNU Emacs Manual}, for the opposite way of -working---generating ChangeLog entries from the revision control log. - -In the Log Edit buffer, @kbd{C-c C-f} (@kbd{M-x log-edit-show-files}) -shows the list of files to be committed in case you need to check -that. - -When you have finished editing the log message, type @kbd{C-c C-c} to -exit the buffer and commit the change. - -@c Fixme: customization variables - -@node Log View Mode -@chapter Browsing a Log of Changes - -@cindex Log View mode -@cindex mode, Log View -@cindex output, logs - -@findex cvs-mode-log -@findex vc-print-log -Log View mode provides a few useful commands for navigating revision -control log output. It is used for the output buffers of both -@code{cvs-mode-log} and @code{vc-print-log}. - -In this mode, @kbd{n} goes to the next message and @kbd{p} goes to the -previous message and @kbd{N} and @kbd{P} go to the next and previous -files, respectively, in multi-file output. With a numeric prefix -argument, these commands move that many messages of files. - -@c @node CVS Status Mode -@c @chapter Viewing CVS' Status output - -@node Customization -@chapter Customization -@vindex log-edit-changelog-full-paragraphs@r{ (variable)} -@vindex cvs-auto-remove-handled@r{ (variable)} -@vindex cvs-auto-remove-directories@r{ (variable)} -@vindex cvs-update-prog-output-skip-regexp@r{ (variable)} -@vindex cvs-cvsroot@r{ (variable)} -@vindex cvs-auto-revert@r{ (variable)} -@vindex log-edit-require-final-newline@r{ (variable)} -@vindex cvs-sort-ignore-file@r{ (variable)} -@cindex Customization -@cindex Variables, list of all -@cindex Erasing input buffer -@cindex Context diff, how to get -@cindex Unidiff, how to get -@cindex Automatically remove handled files -@cindex @samp{-u} option in modules file -@cindex Modules file (@samp{-u} option) -@cindex Update program (@samp{-u} option in modules file) -@cindex Reverting buffers after commit -@cindex Require final newline -@cindex Automatically inserting newline -@cindex Commit message, inserting newline -@cindex Sorting @file{.cvsignore} file -@cindex @file{.cvsignore} file, sorting -@cindex Automatically sorting @file{.cvsignore} -@cindex @samp{CVSROOT}, overriding - -If you have an idea about any customization that would be handy but -isn't present in this list, please tell us! -For info on how to reach us, see @ref{Bugs}. - -@table @samp -@item cvs-auto-remove-handled -If this variable is set to any non-@code{nil} value, -@samp{cvs-mode-remove-handled} will be called every time you check in -files, after the check-in is ready. @xref{Removing handled -entries}. - -@item cvs-auto-remove-directories -If this variable is set to any non-@code{nil} value, directories that do -not contain any files to be checked in will not be listed in the -@file{*cvs*} buffer. - -@item cvs-auto-revert -If this variable is set to any non-@samp{nil} value any buffers you have -that visit a file that is committed will be automatically reverted. -This variable defaults to @samp{t}. @xref{Committing changes}. - -@item cvs-update-prog-output-skip-regexp -The @samp{-u} flag in the @file{modules} file can be used to run a command -whenever a @samp{cvs update} is performed (see @code{cvs(5)}). This regexp -is used to search for the last line in that output. It is normally set -to @samp{$}. That setting is only correct if the command outputs -nothing. Note that PCL-CVS will get very confused if the command -outputs @emph{anything} to @code{stderr}. - -@item cvs-cvsroot -This variable can be set to override @samp{CVSROOT}. It should be a -string. If it is set, then every time a @code{cvs} command is run, it -will be called as @samp{cvs -d @var{cvs-cvsroot}@dots{}}. This can be -useful if your site has several repositories. - -@item log-edit-require-final-newline -@c wordy to avoid underfull hbox -When you enter a log message by typing into the -@file{*cvs-commit-message*} buffer, PCL-CVS normally automatically -inserts a trailing newline, unless there already is one. This behavior -can be controlled via @samp{cvs-commit-buffer-require-final-newline}. -If it is @samp{t} (the default behavior), a newline will always be -appended. If it is @samp{nil}, newlines will never be appended. Any -other value causes PCL-CVS to ask the user whenever there is no trailing -newline in the commit message buffer. - -@findex cvs-mode-changelog-commit -@item log-edit-changelog-full-paragraphs -If this variable is non-@code{nil}, include full @file{ChangeLog} -paragraphs in the CVS log created by @samp{cvs-mode-changelog-commit}. -This may be set in the local variables section of a @file{ChangeLog} -file, to indicate the policy for that @file{ChangeLog}. - -@cindex @file{ChangeLog} paragraphs -A @dfn{@file{ChangeLog} paragraph} is a bunch of log text containing no -blank lines; a paragraph usually describes a set of changes with a -single purpose, but perhaps spanning several functions in several files. -Changes in different paragraphs are unrelated. - -You could argue that the CVS log entry for a file should contain the -full @file{ChangeLog} paragraph mentioning the change to the file, even though -it may mention other files, because that gives you the full context you -need to understand the change. This is the behavior you get when this -variable is set to @code{t}, the default. - -On the other hand, you could argue that the CVS log entry for a change -should contain only the text for the changes which occurred in that -file, because the CVS log is per-file. This is the behavior you get -when this variable is set to @code{nil}. - -@findex cvs-mode-ignore@r{, and @file{.cvsignore} sorting} -@item cvs-sort-ignore-file -If this variable is set to any non-@samp{nil} value, the -@file{.cvsignore} file will always be sorted whenever you use -@samp{cvs-mode-ignore} to add a file to it. This option is on by -default. -@end table - - -@menu -* Customizing Faces:: -@end menu - -@node Customizing Faces -@section Customizing Faces -@vindex cvs-header (face) -@vindex cvs-filename (face) -@vindex cvs-unknown (face) -@vindex cvs-handled (face) -@vindex cvs-need-action (face) -@vindex cvs-marked (face) -@vindex cvs-msg (face) - -PCL-CVS adds a few extra features, including menus, mouse bindings, and -fontification of the @file{*cvs*} buffer. The faces defined for -fontification are listed below: - -@table @samp -@item cvs-header -used to highlight directory changes. - -@item cvs-filename -Used to highlight file names. - -@item cvs-unknown -Used to highlight the status of files which are @samp{Unknown}. - -@item cvs-handled -Used to highlight the status of files which are handled and -need no further action. - -@item cvs-need-action -Used to highlight the status of files which still need action. - -@item cvs-marked -Used to highlight the marked file indicator (@samp{*}). - -@item cvs-msg -Used to highlight CVS messages. -@end table - - -@node Bugs -@chapter Bugs (known and unknown) -@cindex Reporting bugs and ideas -@cindex Bugs, how to report them -@cindex Author, how to reach -@cindex Email to the author -@cindex Known bugs -@cindex Bugs, known -@cindex FAQ -@cindex Problems, list of common - -If you find a bug or misfeature, don't hesitate to tell us! -Use @kbd{M-x report-emacs-bug} to send us a report. -You can follow the same process for feature requests. -We prefer discussing one thing at a time. If you find several unrelated -bugs, please report them separately. If you are running PCL-CVS under -XEmacs, you should also send a copy of bug reports to -the @url{http://lists.xemacs.org/mailman/listinfo/xemacs-beta, -XEmacs mailing list}. - -If you have problems using PCL-CVS or other questions, send them to -the @url{http://lists.gnu.org/mailman/listinfo/help-gnu-emacs, -help-gnu-emacs mailing list}. This is a good place to get help, as is -the @url{http://lists.nongnu.org/mailman/listinfo/info-cvs, info-cvs list}. - -If you have ideas for improvements, or if you have written some -extensions to this package, we would like to hear from you. We hope that -you find this package useful! - -Below is a partial list of currently known problems with PCL-CVS. - -@table @asis -@item Unexpected output from CVS -Unexpected output from CVS may confuse PCL-CVS@. It will create -warning messages in the @file{*cvs*} buffer alerting you to any parse errors. -If you get these messages, please send a bug report to the email -addresses listed above. Include the contents of the @file{*cvs*} buffer, the -output of the CVS process (which should be found in the @file{ *cvs-tmp*} -buffer), and the versions of Emacs, PCL-CVS and CVS you are using. -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - - - -@node Function and Variable Index -@unnumbered Function and Variable Index - -This is an index of all the functions and variables documented in this -manual. - -@printindex fn - -@node Concept Index -@unnumbered Concept Index - -This is an index of concepts discussed in this manual. - -@printindex cp - -@node Key Index -@unnumbered Key Index - -This index includes an entry for each PCL-CVS key sequence documented in -this manual. - -@printindex ky - -@bye diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi deleted file mode 100644 index 53c66c8fb34..00000000000 --- a/doc/misc/pgg.texi +++ /dev/null @@ -1,512 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@include gnus-overrides.texi - -@setfilename ../../info/pgg - -@set VERSION 0.1 -@settitle PGG @value{VERSION} - -@documentencoding UTF-8 - -@copying -This file describes PGG @value{VERSION}, an Emacs interface to various -PGP implementations. - -Copyright @copyright{} 2001, 2003--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* PGG: (pgg). Emacs interface to various PGP implementations. -@end direntry - -@titlepage -@ifset WEBHACKDEVEL -@title PGG (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title PGG -@end ifclear - -@author by Daiki Ueno -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top PGG - -PGG is an interface library between Emacs -and various tools for secure communication. PGG also provides a simple -user interface to encrypt, decrypt, sign, and verify MIME messages. -This package is obsolete; for new code we recommend EasyPG instead. -@xref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: What PGG is. -* Prerequisites:: Complicated stuff you may have to do. -* How to use:: Getting started quickly. -* Architecture:: -* Parsing OpenPGP packets:: -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -* Variable Index:: -@end menu - -@node Overview -@chapter Overview - -PGG is an interface library between Emacs and various tools for secure -communication. Even though Mailcrypt has similar feature, it does not -deal with detached PGP messages, normally used in PGP/MIME -infrastructure. This was the main reason why I wrote the new library. - -Note that the PGG library is now obsolete, replaced by EasyPG. -@xref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}. - -PGP/MIME is an application of MIME Object Security Services (RFC1848). -The standard is documented in RFC2015. - -@node Prerequisites -@chapter Prerequisites - -PGG requires at least one implementation of privacy guard system. -This document assumes that you have already obtained and installed them -and that you are familiar with its basic functions. - -By default, PGG uses GnuPG@. If you are new to such a system, I -recommend that you should look over the GNU Privacy Handbook (GPH) -which is available at @uref{http://www.gnupg.org/documentation/}. - -When using GnuPG, we recommend the use of the @code{gpg-agent} -program, which is distributed with versions 2.0 and later of GnuPG@. -This is a daemon to manage private keys independently from any -protocol, and provides the most secure way to input and cache your -passphrases (@pxref{Caching passphrase}). By default, PGG will -attempt to use @code{gpg-agent} if it is running. @xref{Invoking -GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}. - -PGG also supports Pretty Good Privacy version 2 or version 5. - -@node How to use -@chapter How to use - -The toplevel interface of this library is quite simple, and only -intended to use with public-key cryptographic operation. - -To use PGG, evaluate following expression at the beginning of your -application program. - -@lisp -(require 'pgg) -@end lisp - -If you want to check existence of pgg.el at runtime, instead you can -list autoload setting for desired functions as follows. - -@lisp -(autoload 'pgg-encrypt-region "pgg" - "Encrypt the current region." t) -(autoload 'pgg-encrypt-symmetric-region "pgg" - "Encrypt the current region with symmetric algorithm." t) -(autoload 'pgg-decrypt-region "pgg" - "Decrypt the current region." t) -(autoload 'pgg-sign-region "pgg" - "Sign the current region." t) -(autoload 'pgg-verify-region "pgg" - "Verify the current region." t) -(autoload 'pgg-insert-key "pgg" - "Insert the ASCII armored public key." t) -(autoload 'pgg-snarf-keys-region "pgg" - "Import public keys in the current region." t) -@end lisp - -@menu -* User Commands:: -* Selecting an implementation:: -* Caching passphrase:: -* Default user identity:: -@end menu - -@node User Commands -@section User Commands - -At this time you can use some cryptographic commands. The behavior of -these commands relies on a fashion of invocation because they are also -intended to be used as library functions. In case you don't have the -signer's public key, for example, the function @code{pgg-verify-region} -fails immediately, but if the function had been called interactively, it -would ask you to retrieve the signer's public key from the server. - -@deffn Command pgg-encrypt-region start end recipients &optional sign passphrase -Encrypt the current region between @var{start} and @var{end} for -@var{recipients}. When the function were called interactively, you -would be asked about the recipients. - -If encryption is successful, it replaces the current region contents (in -the accessible portion) with the resulting data. - -If optional argument @var{sign} is non-@code{nil}, the function is -request to do a combined sign and encrypt. This currently is -confirmed to work with GnuPG, but might not work with PGP or PGP5. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. -@end deffn - -@deffn Command pgg-encrypt-symmetric-region &optional start end passphrase -Encrypt the current region between @var{start} and @var{end} using a -symmetric cipher. After invocation you are asked for a passphrase. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. - -symmetric-cipher encryption is currently only implemented for GnuPG. -@end deffn - -@deffn Command pgg-decrypt-region start end &optional passphrase -Decrypt the current region between @var{start} and @var{end}. If -decryption is successful, it replaces the current region contents (in -the accessible portion) with the resulting data. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. -@end deffn - -@deffn Command pgg-sign-region start end &optional cleartext passphrase -Make the signature from text between @var{start} and @var{end}. If the -optional third argument @var{cleartext} is non-@code{nil}, or the -function is called interactively, it does not create a detached -signature. In such a case, it replaces the current region contents (in -the accessible portion) with the resulting data. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. -@end deffn - -@deffn Command pgg-verify-region start end &optional signature fetch -Verify the current region between @var{start} and @var{end}. If the -optional third argument @var{signature} is non-@code{nil}, it is treated -as the detached signature file of the current region. - -If the optional 4th argument @var{fetch} is non-@code{nil}, or the -function is called interactively, we attempt to fetch the signer's -public key from the key server. -@end deffn - -@deffn Command pgg-insert-key -Retrieve the user's public key and insert it as ASCII-armored format. -@end deffn - -@deffn Command pgg-snarf-keys-region start end -Collect public keys in the current region between @var{start} and -@var{end}, and add them into the user's keyring. -@end deffn - -@node Selecting an implementation -@section Selecting an implementation - -Since PGP has a long history and there are a number of PGP -implementations available today, the function which each one has differs -considerably. For example, if you are using GnuPG, you know you can -select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on -the other hand the version 2 of PGP only supports IDEA. - -Which implementation is used is controlled by the @code{pgg-scheme} -variable. If it is @code{nil} (the default), the value of the -@code{pgg-default-scheme} variable will be used instead. - -@defvar pgg-scheme -Force specify the scheme of PGP implementation. The value can be set to -@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}. -@end defvar - -@defvar pgg-default-scheme -The default scheme of PGP implementation. The value should be one of -@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}. -@end defvar - -@node Caching passphrase -@section Caching passphrase - -When using GnuPG (gpg) as the PGP scheme, we recommend using a program -called @code{gpg-agent} for entering and caching -passphrases@footnote{Actually, @code{gpg-agent} does not cache -passphrases but private keys. On the other hand, from a user's point -of view, this technical difference isn't visible.}. - -@defvar pgg-gpg-use-agent -If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible. -The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG -is not the current PGP scheme, PGG's own passphrase-caching mechanism -is used (see below). -@end defvar - -To use @code{gpg-agent} with PGG, you must first ensure that -@code{gpg-agent} is running. For example, if you are running in the X -Window System, you can do this by putting the following line in your -@file{.xsession} file: - -@smallexample -eval "$(gpg-agent --daemon)" -@end smallexample - -For more details on invoking @code{gpg-agent}, @xref{Invoking -GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}. - -Whenever you perform a PGG operation that requires a GnuPG passphrase, -GnuPG will contact @code{gpg-agent}, which prompts you for the -passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so -that subsequent uses will not require you to enter the passphrase -again. (This cache usually expires after a certain time has passed; -you can change this using the @code{--default-cache-ttl} option when -invoking @code{gpg-agent}.) - -If you are running in a X Window System environment, @code{gpg-agent} -prompts for a passphrase by opening a graphical window. However, if -you are running Emacs on a text terminal, @code{gpg-agent} has trouble -receiving input from the terminal, since it is being sent to Emacs. -One workaround for this problem is to run @code{gpg-agent} on a -different terminal from Emacs, with the @code{--keep-tty} option; this -tells @code{gpg-agent} use its own terminal to prompt for passphrases. - -When @code{gpg-agent} is not being used, PGG prompts for a passphrase -through Emacs. It also has its own passphrase caching mechanism, -which is controlled by the variable @code{pgg-cache-passphrase} (see -below). - -There is a security risk in handling passphrases through PGG rather -than @code{gpg-agent}. When you enter your passphrase into an Emacs -prompt, it is temporarily stored as a cleartext string in the memory -of the Emacs executable. If the executable memory is swapped to disk, -the root user can, in theory, extract the passphrase from the -swapfile. Furthermore, the swapfile containing the cleartext -passphrase might remain on the disk after the system is discarded or -stolen. @code{gpg-agent} avoids this problem by using certain tricks, -such as memory locking, which have not been implemented in Emacs. - -@defvar pgg-cache-passphrase -If non-@code{nil}, store passphrases. The default value of this -variable is @code{t}. If you are worried about security issues, -however, you could stop the caching of passphrases by setting this -variable to @code{nil}. -@end defvar - -@defvar pgg-passphrase-cache-expiry -Elapsed time for expiration in seconds. -@end defvar - -If your passphrase contains non-ASCII characters, you might need to -specify the coding system to be used to encode your passphrases, since -GnuPG treats them as a byte sequence, not as a character sequence. - -@defvar pgg-passphrase-coding-system -Coding system used to encode passphrase. -@end defvar - -@node Default user identity -@section Default user identity - -The PGP implementation is usually able to select the proper key to use -for signing and decryption, but if you have more than one key, you may -need to specify the key id to use. - -@defvar pgg-default-user-id -User ID of your default identity. It defaults to the value returned -by @samp{(user-login-name)}. You can customize this variable. -@end defvar - -@defvar pgg-gpg-user-id -User ID of the GnuPG default identity. It defaults to @samp{nil}. -This overrides @samp{pgg-default-user-id}. You can customize this -variable. -@end defvar - -@defvar pgg-pgp-user-id -User ID of the PGP 2.x/6.x default identity. It defaults to -@samp{nil}. This overrides @samp{pgg-default-user-id}. You can -customize this variable. -@end defvar - -@defvar pgg-pgp5-user-id -User ID of the PGP 5.x default identity. It defaults to @samp{nil}. -This overrides @samp{pgg-default-user-id}. You can customize this -variable. -@end defvar - -@node Architecture -@chapter Architecture - -PGG introduces the notion of a "scheme of PGP implementation" (used -interchangeably with "scheme" in this document). This term refers to a -singleton object wrapped with the luna object system. - -Since PGG was designed for accessing and developing PGP functionality, -the architecture had to be designed not just for interoperability but -also for extensibility. In this chapter we explore the architecture -while finding out how to write the PGG back end. - -@menu -* Initializing:: -* Back end methods:: -* Getting output:: -@end menu - -@node Initializing -@section Initializing - -A scheme must be initialized before it is used. -It had better guarantee to keep only one instance of a scheme. - -The following code is snipped out of @file{pgg-gpg.el}. Once an -instance of @code{pgg-gpg} scheme is initialized, it's stored to the -variable @code{pgg-scheme-gpg-instance} and will be reused from now on. - -@lisp -(defvar pgg-scheme-gpg-instance nil) - -(defun pgg-make-scheme-gpg () - (or pgg-scheme-gpg-instance - (setq pgg-scheme-gpg-instance - (luna-make-entity 'pgg-scheme-gpg)))) -@end lisp - -The name of the function must follow the -regulation---@code{pgg-make-scheme-} follows the back end name. - -@node Back end methods -@section Back end methods - -In each back end, these methods must be present. The output of these -methods is stored in special buffers (@ref{Getting output}), so that -these methods must tell the status of the execution. - -@deffn Method pgg-scheme-lookup-key scheme string &optional type -Return keys associated with @var{string}. If the optional third -argument @var{type} is non-@code{nil}, it searches from the secret -keyrings. -@end deffn - -@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase -Encrypt the current region between @var{start} and @var{end} for -@var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign -and encrypt. If encryption is successful, it returns @code{t}, -otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase -Encrypt the current region between @var{start} and @var{end} using a -symmetric cipher and a passphrases. If encryption is successful, it -returns @code{t}, otherwise @code{nil}. This function is currently only -implemented for GnuPG. -@end deffn - -@deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase -Decrypt the current region between @var{start} and @var{end}. If -decryption is successful, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase -Make the signature from text between @var{start} and @var{end}. If the -optional third argument @var{cleartext} is non-@code{nil}, it does not -create a detached signature. If signing is successful, it returns -@code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-verify-region scheme start end &optional signature -Verify the current region between @var{start} and @var{end}. If the -optional third argument @var{signature} is non-@code{nil}, it is treated -as the detached signature of the current region. If the signature is -successfully verified, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-insert-key scheme -Retrieve the user's public key and insert it as ASCII-armored format. -On success, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-snarf-keys-region scheme start end -Collect public keys in the current region between @var{start} and -@var{end}, and add them into the user's keyring. -On success, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@node Getting output -@section Getting output - -The output of the back end methods (@ref{Back end methods}) is stored in -special buffers, so that these methods must tell the status of the -execution. - -@defvar pgg-errors-buffer -The standard error output of the execution of the PGP command is stored -here. -@end defvar - -@defvar pgg-output-buffer -The standard output of the execution of the PGP command is stored here. -@end defvar - -@defvar pgg-status-buffer -The rest of status information of the execution of the PGP command is -stored here. -@end defvar - -@node Parsing OpenPGP packets -@chapter Parsing OpenPGP packets - -The format of OpenPGP messages is maintained in order to publish all -necessary information needed to develop interoperable applications. -The standard is documented in RFC 2440. - -PGG has its own parser for the OpenPGP packets. - -@defun pgg-parse-armor string -List the sequence of packets in @var{string}. -@end defun - -@defun pgg-parse-armor-region start end -List the sequence of packets in the current region between @var{start} -and @var{end}. -@end defun - -@defvar pgg-ignore-packet-checksum -If non-@code{nil}, don't check the checksum of the packets. -@end defvar - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye - -@c End: diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi deleted file mode 100644 index 2a7c52c33d9..00000000000 --- a/doc/misc/rcirc.texi +++ /dev/null @@ -1,949 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/rcirc -@settitle rcirc Manual -@documentencoding UTF-8 -@c %**end of header - -@copying -Copyright @copyright{} 2006--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license is -included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* Rcirc: (rcirc). Internet Relay Chat (IRC) client. -@end direntry - -@titlepage -@title rcirc Manual -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top rcirc Manual - -@code{rcirc} is an Emacs IRC client. - -IRC (Internet Relay Chat) is a multi-user chat protocol. Users -communicate with each other in real-time. Communication occurs both in -topic channels which are collections of many users, or privately, with -just one other user. - -@insertcopying - -@end ifnottex - -@menu -* Basics:: -* Reference:: -* Fighting Information Overload:: -* Hacking and Tweaking:: -* GNU Free Documentation License:: -* Key Index:: -* Variable Index:: -* Index:: - -@detailmenu - --- The Detailed Node Listing --- - -Basics - -* Internet Relay Chat:: -* Getting started with rcirc:: - -Reference - -* rcirc commands:: -* Useful IRC commands:: -* Configuration:: - -Fighting Information Overload - -* Channels:: -* People:: -* Keywords:: -* Notices:: - -Hacking and Tweaking - -* Skipping /away messages using handlers:: -* Using fly spell mode:: -* Scrolling conservatively:: -* Changing the time stamp format:: -* Defining a new command:: -* Reconnecting after you have lost the connection:: - -@end detailmenu -@end menu - -@node Basics -@chapter Basics - -This chapter contains a brief introduction to IRC (Internet Relay Chat), -and a quick tutorial on @code{rcirc}. - -@menu -* Internet Relay Chat:: -* Getting started with rcirc:: -@end menu - -@node Internet Relay Chat -@section Internet Relay Chat -@cindex internet relay chat -@cindex irc - -@cindex channel -@dfn{Internet Relay Chat} (IRC) is a form of instant communication over the -Internet. It is mainly designed for group (many-to-many) communication -in discussion forums called channels, but also allows one-to-one -communication. - -@cindex instant messaging, comparison -@cindex server -@cindex network -Contrary to most Instant Messenger (IM) systems, users usually don't -connect to a central server. Instead, users connect to a random -server in a network, and servers relay messages from one to the next. - -Here's a typical example: - -@cindex redirection to random servers -When you connect to the Freenode network -(@code{http://freenode.net/}), you point your IRC client at the -server @code{irc.freenode.net}. That server will redirect your client -to a random server on the network, such as @code{zelazny.freenode.net}. - -@cindex channel name -@cindex # starts a channel name -Once you're connected, you can send messages to all other users -connected to the same network, and you can join all channels on the same -network. You might join the @code{#emacs} and the @code{#rcirc} -channels, for example. (Typically, channel names begin with a hash -character.) - -Once you have joined a channel, anything you type will be broadcast to -all the other users on the same channel. - -@cindex addressing other people -@cindex other people, addressing them -@cindex talk to other people -If you want to address someone specifically, for example as an answer to -a question, it is customary to prefix the message with the nick followed -by a colon, like this: - -@example -deego: fsbot rules! -@end example - -@cindex nick completion -@cindex completion of nicks -@kindex TAB -Since this is so common, you can use @key{TAB} to do nick completion. - -@node Getting started with rcirc -@section Getting started with rcirc -@cindex getting started -@cindex connecting to a server - -@cindex irc command -Use the command @kbd{M-x irc} to connect using the defaults. -@xref{Configuration}, if you want to change the defaults. - -Use @kbd{C-u M-x irc} if you don't want to use the defaults, e.g., if you -want to connect to a different network, or connect to the same network -using a different nick. This will prompt you for four things: - -@table @asis -@cindex server, connecting -@cindex Freenode network -@item IRC Server -What server do you want to connect to? All the servers in a particular -network are equivalent. Some networks use a round-robin system where a -single server redirects new connections to a random server in the -network. @code{irc.freenode.net} is such a server for the Freenode -network. Freenode provides the network ``for the Free and Open Source -Software communities, for not-for-profit organizations and for related -communities and organizations.'' - -@cindex port, connecting -@cindex 6667, default IRC port -@item IRC Port -All network connections require a port. Just as web servers and clients -use port 80 per default, IRC uses port 6667 per default. You rarely -have to use a different port. - -@cindex nick, connecting -@cindex changing nick -@cindex name changes -@item IRC Nick -@vindex user-login-name -Every users needs a handle on-line. You will automatically be assigned -a slightly different nick if your chosen nick is already in use. If -your @code{user-login-name} is @code{alex}, and this nick is already -in use, you might for example get assigned the nick @code{alex`}. - -@cindex channels, connecting -@cindex initial channels -@cindex startup channels -@item IRC Channels -A space separated list of channels you want to join when connecting. -You don't need to join any channels, if you just want to have one-to-one -conversations with friends on the same network. If you're new to the -Freenode network, join @code{#emacs}, the channel about all things -Emacs, or join @code{#rcirc}, the channel about @code{rcirc}. -@end table - -@cindex server buffer -When you have answered these questions, @code{rcirc} will create a server -buffer, which will be named something like @file{*irc.freenode.net*}, -and a channel buffer for each of the channels you wanted to join. - -@kindex RET -@cindex talking -@cindex communicating -To talk in a channel, just type what you want to say in a channel -buffer, and press @key{RET}. - -@kindex C-c C-c -@cindex multiline messages -@cindex messages, multiple lines -@cindex pasting multiple lines -@cindex edit message before sending -If you want to paste multiple lines, such as source code, you can use -@kbd{C-c C-c} to edit your message in a separate buffer. Use @kbd{C-c -C-c} to finish editing. You still need to press @key{RET} to send it, -though. Generally, IRC users don't like people pasting more than around -four lines of code, so use with care. - -@comment This section copied from the Channels section. -@comment All index markers should point to the original! -Once you are connected to multiple channels, or once you've turned you -attention to other buffers in Emacs, you probably want to be notified -of any activity in channels not currently visible. All you need to do -is switch channel tracking on using @kbd{M-x rcirc-track-minor-mode}. -To make this permanent, add the following to your init file: - -@example -(rcirc-track-minor-mode 1) -@end example - -Use @kbd{C-c C-@key{SPC}} to switch to these buffers. - -@node Reference -@chapter Reference -@cindex reference - -This is the reference section of the manual. It is not complete. For -complete listings of @code{rcirc} features, use Emacs built-in -documentation. - -@menu -* rcirc commands:: -* Useful IRC commands:: -* Configuration:: -@end menu - -@node rcirc commands -@section rcirc commands -@cindex rcirc commands -@cindex commands - -@kindex C-h m -This is a list of commands that you may use in @code{rcirc}. It is not -complete. For a complete listing, press @kbd{C-h m} in an @code{rcirc} -buffer. - -In addition to using regular Emacs key bindings, you can call them by -typing them into an @code{rcirc} buffer. - -@cindex call commands -@cindex typing commands -@cindex commands -For instance, instead of using the command @kbd{C-c C-j} to join a new -channel, you may type this in an @code{rcirc} buffer, and press @key{RET}: - -@example -/join #emacs -@end example - -@cindex / starts a command -@cindex messages starting with a slash disappear -@cindex disappearing messages if starting with a slash -@cindex slash hides message -This is why you cannot start a message with a slash. You will have to -precede the command with a space, or rewrite your message in order to -send it to a channel. - -@cindex multiple words as parameters -@cindex string delimiters -@cindex quotes -@cindex double-quotes -Many commands take parameters. IRC commands usually ignore string -delimiters. Neither quote nor double-quote have special meanings in -IRC. - -@example -/nick "alex schroeder" -@end example - -This will try to change your nick to @code{"alex}. Usually this will -fail because the double quote character is not a valid character for -nicks. - -@cindex case insensitive commands -These commands are case insensitive. - -@cindex new command -@cindex unknown command -@cindex command unknown -If a command isn't known by @code{rcirc}, it will simply be sent along to the -server. There is a list of some useful commands like that in the next -section. - -@table @kbd -@item C-c C-j -@kindex C-c C-j -@cindex /join -@cindex join channels -@cindex other channels -@cindex rooms, joining -@cindex discussion, joining -This joins a channel such as @code{#rcirc} or @code{#emacs}. On most -networks, anybody can create new channels. If you want to talk with -some friends, for example, all you have to do is agree on a valid -channel name and join that channel. (Also @code{/join #emacs}.) - -@item C-c C-p -@kindex C-c C-p -@cindex /part -@cindex part a channel -@cindex leave a channel -@cindex disconnect from a channel -@cindex stop talking on a channel -@cindex kill channel buffer -This leaves the current channel. You can optionally provide a reason -for parting. When you kill a channel buffer, you automatically part the -corresponding channel. (Also @code{/part you are too weird!}.) - -@item C-c C-r -@kindex C-c C-r -@cindex /nick -@cindex change name -@cindex nick changing -@cindex rename yourself -@cindex other name -This changes your nick to some other name. Your nick must be unique -across the network. Most networks don't allow too many nick changes in -quick succession, and have restrictions on the valid characters in nick -names. (Also @code{/nick alex-test}) - -@item C-c C-w -@kindex C-c C-w -@cindex /whois -@cindex who are these people -@cindex identifying people -@cindex channels other people are on -@cindex what channels people are on -Gives you some basic information about a nick. This often includes what -other channels people are on. (Also @code{/whois fsbot}.) - -@item C-c C-q -@kindex C-c C-q -@cindex /query -@cindex starting a private conversation -@cindex one-to-one conversation -@cindex talk privately -@cindex private conversation -@cindex contact one person only -@cindex query a person -Starts a one-to-one conversation with another person on the same -network. A new buffer will be created for this conversation. It works -like a channel with only two members. (Also @code{/query fsbot}.) - -@item C-c @key{RET} -@kindex C-c RET -@cindex /msg -@cindex single message -@cindex message sending -This sends a single message to a nick. Like with @kbd{C-c C-q}, a new -buffer is created, where the response from the other party will show -up. (Also @code{/msg nickserv identify secret}.) - -@item C-c C-x -@kindex C-c C-x -@cindex /quit -@cindex quit -@cindex disconnect -@cindex kill connection -@cindex connection end -@cindex part all channels -@cindex end connection -@cindex server buffer killing -@cindex reason for quitting -This disconnects from the server and parts all channels. You can -optionally provide a reason for quitting. When you kill the server -buffer, you automatically quit the server and part all channels. (Also -@code{/quit ZZZzzz...}.) -@end table - -@node Useful IRC commands -@section Useful IRC commands -@cindex irc commands -@cindex commands - -As mentioned, if a command isn't known by @code{rcirc}, it will simply be sent -along to the server. Some such commands are available on nearly all IRC -servers, such as: - -@table @code -@item /away -@cindex /away -@cindex away status -@cindex pause status -@cindex unavailable status -@cindex set away status -This sets your status as ``being away'' if you provide a reason, or sets -your status as ``being back'' if you do not. People can use the -@kbd{C-c C-w} command to check your status. Example: @code{/away food}. -@end table - -@cindex irc resources -@cindex help about irc -Typical IRC servers implement many more commands. You can read more -about the fantastic world of IRC online at -@uref{http://www.irchelp.org/, the Internet Relay Chat (IRC) help -archive}. - -@node Configuration -@section Configuration -@cindex configuring rcirc - -These are some variables you can change to configure @code{rcirc} to your -liking. - -@table @code -@item rcirc-server-alist -@vindex rcirc-server-alist -@cindex channels, configuration -@cindex initial channels, configuration -@cindex startup channels, configuration -@cindex servers, configuration -@cindex initial servers, configuration -@cindex startup servers, configuration -This variable contains an alist of servers to connect to by default -and the keywords parameters to use. The keyword parameters are -optional. If you don't provide any, the defaults as documented below -will be used. - -The most important parameter is the @code{:channels} parameter. It -controls which channels you will join by default as soon as you are -connected to the server. - -Here's an example of how to set it: - -@example -(add-to-list 'rcirc-server-alist - '("otherworlders.org" - :channels ("#FUDGE" "#game-design"))) -@end example - -By default you will be connected to the @code{rcirc} support channel: -@code{#rcirc} on @code{irc.freenode.net}. - -@table @code -@item :nick -This overrides @code{rcirc-default-nick}. - -@item :port -This overrides @code{rcirc-default-port}. - -@item :user-name -This overrides @code{rcirc-default-user-name}. - -@item :full-name -This overrides @code{rcirc-default-full-name}. - -@item :channels -This describes which channels to join when connecting to the server. -If absent, no channels will be connected to automatically. - -@end table - -@item rcirc-default-nick -@vindex rcirc-default-nick -This variable is used for the default nick. It defaults to the login -name returned by @code{user-login-name}. - -@example -(setq rcirc-default-nick "kensanata") -@end example - -@item rcirc-default-port -@vindex rcirc-default-port -@cindex port -This variable contains the default port to connect to. It is 6667 by -default and rarely needs changing. - -@item rcirc-default-user-name -@vindex rcirc-default-user-name -@cindex user name -This variable contains the default user name to report to the server. -It defaults to the login name returned by @code{user-login-name}, just -like @code{rcirc-default-nick}. - -@item rcirc-default-full-name -@vindex rcirc-default-full-name -@cindex full name -@cindex real name -@cindex surname -This variable is used to set your ``real name'' on IRC@. It defaults -to the name returned by @code{user-full-name}. If you want to hide -your full name, you might want to set it to some pseudonym. - -@example -(setq rcirc-default-full-name "Curious Minds Want To Know") -@end example - -@item rcirc-authinfo -@vindex rcirc-authinfo -@cindex authentication -@cindex identification -@cindex nickserv -@cindex login -This variable is an alist used to automatically identify yourself on -networks. Each sublist starts with a regular expression that is -compared to the server address you're connecting to. The second -element in the list is a symbol representing the method to use, -followed by the arguments this method requires. - -Here is an example to illustrate how you would set it: - -@example -(setq rcirc-authinfo - '(("freenode" nickserv "bob" "p455w0rd") - ("freenode" chanserv "bob" "#bobland" "passwd99") - ("bitlbee" bitlbee "robert" "sekrit"))) -@end example - -And here are the valid method symbols and the arguments they require: - -@table @code -@item nickserv -@cindex nickserv authentication -Use this symbol if you need to identify yourself as follows when -connecting to a network: @code{/msg nickserv identify secret}. The -necessary arguments are the nickname you want to use this for, and the -password to use. - -Before you can use this method, you will have to register your nick and -pick a password for it. Contact @code{nickserv} and check out the -details. (Using @code{/msg nickserv help}, for example.) - -@item chanserv -@cindex chanserv authentication -Use this symbol if you need to identify yourself as follows if you want -to join a particular channel: @code{/msg chanserv identify #underground -secret}. The necessary arguments are the nickname and channel you want -to use this for, and the password to use. - -Before you can use this method, a channel contact must tell you about -the password to use. Contact @code{chanserv} and check out the details. -(Using @code{/msg chanserv help}, for example.) - -@item bitlbee -@cindex bitlbee authentication -Use this symbol if you need to identify yourself in the Bitlbee channel -as follows: @code{identify secret}. The necessary arguments are the -nickname you want to use this for, and the password to use. - -@cindex gateway to other IM services -@cindex instant messaging, other services -@cindex Jabber -@cindex AIM -@cindex ICQ -@cindex MSN -@cindex Yahoo! -Bitlbee acts like an IRC server, but in fact it is a gateway to a lot of -other instant messaging services. You can either install Bitlbee -locally or use a public Bitlbee server. There, you need to create an -account with a password. This is the nick and password you need to -provide for the bitlbee authentication method. - -Later, you will tell Bitlbee about your accounts and passwords on all -the other instant messaging services, and Bitlbee will log you in. All -@code{rcirc} needs to know, is the login to your Bitlbee account. Don't -confuse the Bitlbee account with all the other accounts. - -@end table - -@end table - -@node Fighting Information Overload -@chapter Fighting Information Overload -@cindex information overload - -This is the section of the manual that caters to the busy person -online. There are support channels with several hundred people in -them. Trying to follow a conversation in these channels can be a -daunting task. This chapters tells you how @code{rcirc} can help. - -@menu -* Channels:: -* People:: -* Keywords:: -* Notices:: -@end menu - -@node Channels -@section Channels -@cindex channels -@cindex modeline - -@comment This section copied to the Getting started with rcirc section -@kindex C-c C-SPC -@vindex rcirc-track-minor-mode -@cindex switching channels -@cindex tracking activity -@cindex active channel -@cindex abbreviated channel names -@cindex modeline tracks activity -Most people want a notification when something is said on a channel they -have joined, particularly if they have been addressed directly. There -is a global minor mode that will do this kind of tracking for you. All -you need to do is switch it on using @kbd{M-x rcirc-track-minor-mode}. -To make this permanent, add the following to your init file: - -@example -(rcirc-track-minor-mode 1) -@end example - -When other people say things in buffers that are currently buried (no -window is showing them), the mode line will now show you the abbreviated -channel or nick name. Use @kbd{C-c C-@key{SPC}} to switch to these -buffers. - -@vindex rcirc-mode-hook -If you prefer not to load @code{rcirc} immediately, you can delay the -activation of this mode: - -@example -(add-hook 'rcirc-mode-hook - (lambda () - (rcirc-track-minor-mode 1))) -@end example - -@cindex busy channels -If you've joined a very active support channel, tracking activity is -no longer useful. The channel will be always active. Switching to -active channels using @kbd{C-c C-@key{SPC}} no longer works as -expected. - -@kindex C-c C-l -@cindex low priority channels -The solution is to mark this channel as a low priority channel. -Use @kbd{C-c C-l} to make the current channel a low-priority channel. -Low priority channels have the modeline indicator ``LowPri''. -@kbd{C-c C-@key{SPC}} will not switch to low priority channels unless -you use the @kbd{C-u} prefix. - -@kindex C-c TAB -@cindex ignored channels -If you prefer a channel to never show up in the modeline, then you -have to ignore it. Use @kbd{C-c @key{TAB}} to ignore the current -channel. - -@node People -@section People -@cindex people, how to ignore -@cindex nicks, how to ignore -@cindex friends -@cindex buddies -@cindex trolls - -The most important command available to the discerning IRC user is -@code{/ignore}. It's the big equalizer online: If people aggravate -you, just ignore them. - -This is of course a crude all-or-nothing solution. Fear not, -@code{rcirc} offers alternatives: You can ``brighten'' your buddies -and ``dim'' certain other nicks that you don't want to ignore -altogether. - -@table @code -@item /ignore -@cindex /ignore -@cindex ignoring other people -@cindex trolls, ignoring -@cindex hide some posts -@cindex idiots online -This command toggles the ignore status of a nick, if you provide one. -If you don't provide a nick, the command lists all the nicks you are -ignoring. All messages by ignored nicks are---you guessed it---ignored. -Since only ``operators'' can kick people from channels, the -ignore command is often the only way to deal with some of the more -obnoxious fellows online. Example: @code{/ignore rudybot}. - -@item /bright -@cindex /bright -@cindex highlight other people -@cindex friends, highlight -@cindex buddies, highlight -@cindex nicks, highlight -@cindex brighten nicks -This command toggles the bright status of a nick, if you provide one. -If you don't provide a nick, the command lists all the ``brightened'' -nicks. All messages by brightened nicks are---you guessed -it---brightened. Use this for your friends. Example: @code{/bright -rcy}. - -@item /dim -@cindex /dim -@cindex soft-ignore other people -@cindex obnoxious people online -@cindex rabble online -This command toggles the dim status of a nick, if you provide one. If -you don't provide a nick, the command lists all the ``dimmed'' nicks. -All messages by dimmed nicks are---you guessed it---dimmed. Use this -for boring people and bots. If you are tracking channel activity, -messages by dimmed nicks will not register as activity. Example: -@code{/dim fsbot}. -@end table - - -@node Keywords -@section Keywords -@cindex keywords - -On a busy channel, you might want to ignore all activity (using -@kbd{C-c @key{TAB}}) and just watch for certain keywords. The -following command allows you to highlight certain keywords: - -@table @code -@item /keyword -@cindex /keyword -This command toggles the highlighting of a keyword, if you provide -one. If you don't provide a keyword, the current keywords are -listed. Example: @code{/keyword manual}. -@end table - -@node Notices -@section Notices -@cindex part notices, how to omit -@cindex join notices, how to omit -@cindex quit notices, how to omit -@cindex nick notices, how to omit - -@kindex C-c C-o -@cindex low priority channels -In busy channels you might not be interested in all the joining, -parting, quitting, and renaming that goes on. You can omit those -notices using @kbd{C-c C-o}. - -@vindex rcirc-omit-responses -@cindex away notices, how to omit -You can control which notices get omitted via the -@code{rcirc-omit-responses} variable. Here's an example of how to -omit away messages: - -@example -(setq rcirc-omit-responses '("JOIN" "PART" "QUIT" "NICK" "AWAY")) -@end example - -@vindex rcirc-omit-threshold -Notice that these messages will not be omitted if the nick in question -has recently been active. After all, you don't want to continue a -conversation with somebody who just left. That's why @code{rcirc} -checks recent lines in the buffer to figure out if a nick has been -active and only omits a message if the nick has not been active. The -window @code{rcirc} considers is controlled by the -@code{rcirc-omit-threshold} variable. - -@node Hacking and Tweaking -@chapter Hacking and Tweaking -@cindex hacking and tweaking - -Here are some examples of stuff you can do to configure @code{rcirc}. - -@menu -* Skipping /away messages using handlers:: -* Using fly spell mode:: -* Scrolling conservatively:: -* Changing the time stamp format:: -* Defining a new command:: -* Reconnecting after you have lost the connection:: -@end menu - -@node Skipping /away messages using handlers -@section Skipping @code{/away} messages using handlers -@cindex /away messages - -@cindex handlers -@cindex status codes -The IRC protocol specifies how certain events are signaled from server -to client. These events have numbers and are dealt with using so-called -handlers. You can override existing handlers by exploiting the naming -convention adopted for @code{rcirc}. - -Here's how to stop @code{rcirc} from printing @code{/away} messages. -Since @code{rcirc} doesn't define a 301 handler, you don't need to -require @code{rcirc} before defining the handler: - -@example -(defun rcirc-handler-301 (process cmd sender args) - "/away message handler.") -@end example - -@node Using fly spell mode -@section Using fly spell mode -@cindex fly spell -@cindex spelling -@cindex spell-checking as you type -@cindex automatic spelling -@vindex rcirc-mode-hook - -The following code activates Fly Spell Mode -for @code{rcirc} buffers: - -@example -(add-hook 'rcirc-mode-hook (lambda () - (flyspell-mode 1))) -@end example - -@xref{Spelling, , Flyspell mode, emacs, The GNU Emacs Manual}, -for details. - -@node Scrolling conservatively -@section Scrolling conservatively -@cindex input line -@cindex scrolling -@vindex scroll-conservatively -@vindex rcirc-mode-hook - -IRC buffers are constantly growing. If you want to see as much as -possible at all times, you would want the prompt at the bottom of the -window when possible. The following snippet uses a local value for -@code{scroll-conservatively} to achieve this: - -@example -(add-hook 'rcirc-mode-hook - (lambda () - (set (make-local-variable 'scroll-conservatively) - 8192))) -@end example - -@xref{Scrolling, , Scrolling conservatively, emacs, The GNU Emacs -Manual}, for details. - -@node Changing the time stamp format -@section Changing the time stamp format -@cindex time stamp -@cindex date time -@cindex format time stamp -@vindex rcirc-time-format - -@code{rcirc-time-format} is the format used for the time stamp. Here's -how to include the date in the time stamp: - -@example -(setq rcirc-time-format "%Y-%m-%d %H:%M ") -@end example - -@node Defining a new command -@section Defining a new command -@cindex defining commands -@cindex commands, defining -@cindex new commands, defining - -Here's a simple new command, @code{/sv}. With it, you can boast about -your IRC client. It shows how you can use @code{defun-rcirc-command} to -define new commands. - -We're waiting for the definition of this command until @code{rcirc} is loaded -because @code{defun-rcirc-command} is not yet available, and without -@code{rcirc} loaded, the command wouldn't do us much good anyway. - -@smallexample -(eval-after-load 'rcirc - '(defun-rcirc-command sv (arg) - "Boast about rcirc." - (interactive "i") - (rcirc-send-message process target - (concat "I use " rcirc-id-string)))) -@end smallexample - -@node Reconnecting after you have lost the connection -@section Reconnecting after you have lost the connection -@cindex reconnecting -@cindex disconnecting servers, reconnecting - -If you're chatting from a laptop, then you might be familiar with this -problem: When your laptop falls asleep and wakes up later, your IRC -client doesn't realize that it has been disconnected. It takes several -minutes until the client decides that the connection has in fact been -lost. The simple solution is to use @kbd{M-x rcirc}. The problem is -that this opens an @emph{additional} connection, so you'll have two -copies of every channel buffer, one dead and one live. - -The real answer, therefore, is a @code{/reconnect} command: - -@smallexample -(eval-after-load 'rcirc - '(defun-rcirc-command reconnect (arg) - "Reconnect the server process." - (interactive "i") - (unless process - (error "There's no process for this target")) - (let* ((server (car (process-contact process))) - (port (process-contact process :service)) - (nick (rcirc-nick process)) - channels query-buffers) - (dolist (buf (buffer-list)) - (with-current-buffer buf - (when (eq process (rcirc-buffer-process)) - (remove-hook 'change-major-mode-hook - 'rcirc-change-major-mode-hook) - (if (rcirc-channel-p rcirc-target) - (setq channels (cons rcirc-target channels)) - (setq query-buffers (cons buf query-buffers)))))) - (delete-process process) - (rcirc-connect server port nick - rcirc-default-user-name - rcirc-default-full-name - channels)))) -@end smallexample - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Key Index -@unnumbered Key Index -@printindex ky - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@node Index -@unnumbered Index -@printindex cp - -@bye diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi deleted file mode 100644 index 6d79d352e40..00000000000 --- a/doc/misc/reftex.texi +++ /dev/null @@ -1,6097 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/reftex -@settitle RefTeX User Manual -@documentencoding UTF-8 -@synindex ky cp -@syncodeindex vr cp -@syncodeindex fn cp - -@ifnottex -@macro RefTeX {} -Ref@TeX{} -@end macro -@macro AUCTeX {} -AUC@TeX{} -@end macro -@macro BibTeX {} -Bib@TeX{} -@end macro -@macro ConTeXt {} -Con@TeX{}t -@end macro -@end ifnottex -@tex -\gdef\RefTeX{Ref\TeX} -\gdef\AUCTeX{AUC\TeX} -\gdef\BibTeX{Bib\TeX} -\gdef\ConTeXt{Con\TeX t} -@end tex - -@include emacsver.texi - -@set VERSION @value{EMACSVER} -@set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,@AUCTeX{} web site} -@set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,@RefTeX{} web page} -@set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers} -@set MAINTAINER the @AUCTeX{} project -@set SUPPORTADDRESS @AUCTeX{} user mailing list (@email{auctex@@gnu.org}) -@set DEVELADDRESS @AUCTeX{} developer mailing list (@email{auctex-devel@@gnu.org}) -@set BUGADDRESS @AUCTeX{} bug mailing list (@email{bug-auctex@@gnu.org}) -@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs FTP site} -@c %**end of header - -@copying -This manual documents @RefTeX{} (version @value{VERSION}), a package -to do labels, references, citations and indices for LaTeX documents -with Emacs. - -Copyright @copyright{} 1997--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* RefTeX: (reftex). Emacs support for LaTeX cross-references - and citations. -@end direntry - -@finalout - -@c Macro definitions - -@c Subheadings inside a table. Need a difference between info and the rest. -@macro tablesubheading{text} -@ifinfo -@subsubheading \text\ -@end ifinfo -@ifnotinfo -@item @b{\text\} -@end ifnotinfo -@end macro - -@titlepage -@title @RefTeX{} User Manual -@subtitle Support for @LaTeX{} labels, references, citations and index entries with GNU Emacs -@subtitle Version @value{VERSION} - -@author by Carsten Dominik -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@ifnottex -@node Top -@top @RefTeX{} - -@insertcopying - -@RefTeX{} is a package for managing Labels, References, Citations and -index entries with GNU Emacs. - -This manual documents @RefTeX{} version @value{VERSION}. - -Don't be discouraged by the size of this manual, which covers @RefTeX{} -in great depth. All you need to know to use @RefTeX{} can be summarized -on two pages (@pxref{RefTeX in a Nutshell}). You can go back later to -other parts of this document when needed. - -@menu -* Introduction:: Quick-Start information. - -* Table of Contents:: A Tool to move around quickly. -* Labels and References:: Creating and referencing labels. -* Citations:: Creating Citations. -* Index Support:: Creating and Checking Index Entries. -* Viewing Cross-References:: Who references or cites what? - -* RefTeXs Menu:: The Ref menu in the menubar. -* Key Bindings:: The default key bindings. -* Faces:: Fontification of RefTeX's buffers. -* Multifile Documents:: Document spread over many files. -* Language Support:: How to support other languages. -* Finding Files:: Included @TeX{} files and @BibTeX{} .bib files. -* Optimizations:: When RefTeX is too slow. -* AUCTeX:: Cooperation with @AUCTeX{}. -* Problems and Work-Arounds:: First Aid. -* Imprint:: Author, Web-site, Thanks - -* Commands:: Which are the available commands. -* Options:: How to extend and configure RefTeX. -* Changes:: A List of recent changes to RefTeX. -* GNU Free Documentation License:: The license for this documentation. - -The Index - -* Index:: The full index. - -@detailmenu - --- The Detailed Node Listing --- - -Introduction - -* Installation:: How to install and activate RefTeX. -* RefTeX in a Nutshell:: A brief summary and quick guide. - -Labels and References - -* Creating Labels:: -* Referencing Labels:: -* Builtin Label Environments:: The environments RefTeX knows about. -* Defining Label Environments:: ... and environments it doesn't. -* Reference Info:: View the label corresponding to a \ref. -* Reference Styles:: Macros to be used instead of \ref. -* LaTeX xr Package:: References to external documents. - -Defining Label Environments - -* Theorem and Axiom:: Defined with @code{\newenvironment}. -* Quick Equation:: When a macro sets the label type. -* Figure Wrapper:: When a macro argument is a label. -* Adding Magic Words:: Other words for other languages. -* Using \eqref:: How to switch to this AMS-LaTeX macro. -* Non-Standard Environments:: Environments without \begin and \end -* Putting it Together:: How to combine many entries. - -Citations - -* Creating Citations:: How to create them. -* Citation Styles:: Natbib, Harvard, Chicago and Co. -* Citation Info:: View the corresponding database entry. -* Chapterbib and Bibunits:: Multiple bibliographies in a Document. -* Citations Outside LaTeX:: How to make citations in Emails etc. -* BibTeX Database Subsets:: Extract parts of a big database. - -Index Support - -* Creating Index Entries:: Macros and completion of entries. -* The Index Phrases File:: A special file for global indexing. -* Displaying and Editing the Index:: The index editor. -* Builtin Index Macros:: The index macros RefTeX knows about. -* Defining Index Macros:: ... and macros it doesn't. - -The Index Phrases File - -* Collecting Phrases:: Collecting from document or external. -* Consistency Checks:: Check for duplicates etc. -* Global Indexing:: The interactive indexing process. - -AUCTeX - -* AUCTeX-RefTeX Interface:: How both packages work together -* Style Files:: @AUCTeX{}'s style files can support RefTeX -* Bib-Cite:: Hypertext reading of a document - -Options, Keymaps, Hooks - -* Options - Table of Contents:: -* Options - Defining Label Environments:: -* Options - Creating Labels:: -* Options - Referencing Labels:: -* Options - Creating Citations:: -* Options - Index Support:: -* Options - Viewing Cross-References:: -* Options - Finding Files:: -* Options - Optimizations:: -* Options - Fontification:: -* Options - Misc:: - -@end detailmenu -@end menu - -@end ifnottex - -@node Introduction -@chapter Introduction -@cindex Introduction - -@RefTeX{} is a specialized package for support of labels, references, -citations, and the index in @LaTeX{}. @RefTeX{} wraps itself round four -@LaTeX{} macros: @code{\label}, @code{\ref}, @code{\cite}, and -@code{\index}. Using these macros usually requires looking up different -parts of the document and searching through @BibTeX{} database files. -@RefTeX{} automates these time-consuming tasks almost entirely. It also -provides functions to display the structure of a document and to move -around in this structure quickly. - -@iftex -Don't be discouraged by the size of this manual, which covers @RefTeX{} -in great depth. All you need to know to use @RefTeX{} can be -summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go -back later to other parts of this document when needed. -@end iftex - -@xref{Imprint}, for information about who to contact for help, bug -reports or suggestions. - -@menu -* Installation:: How to install and activate RefTeX. -* RefTeX in a Nutshell:: A brief summary and quick guide. -@end menu - -@node Installation -@section Installation -@cindex Installation - -@RefTeX{} has been bundled and pre-installed with Emacs since -version 20.2. It has also been bundled and pre-installed with XEmacs -19.16--20.x. XEmacs 21.x users want to install the corresponding -plug-in package which is available from the @value{XEMACSFTP}. See the -XEmacs 21.x documentation on package installation for details. - -Users of earlier Emacs distributions (including Emacs 19) or people -craving for new features and bugs can get a copy of the @RefTeX{} -distribution from the maintainer's web page. @xref{Imprint}, for more -information. The following instructions will guide you through the -process of installing such a distribution. - -@subsection Building and Installing - -Note: Currently installation is supported for Emacs only. XEmacs users -might want to refer to the @RefTeX{} package available through the -package system of XEmacs. - -@subsubheading Installation with make - -In order to install RefTeX, unpack the distribution and edit the header -of the Makefile. Basically, you need to change the path specifications -for Emacs Lisp files and info files. Also, enter the name of your Emacs -executable (usually either @samp{emacs} or @samp{xemacs}). - -Then, type - -@example -make -make install -@end example - -to compile and install the code and documentation. - -Per default @RefTeX{} is installed in its own subdirectory which might -not be on your load path. In this case, add it to load path with a -command like the following, replacing the sample directory with the one -where @RefTeX{} is installed in your case. - -@example -(add-to-list 'load-path "/path/to/reftex") -@end example - -Put this command into your init file before other @RefTeX{}-related -settings. - -@subsubheading Installation by Hand - -If you want to get your hands dirty, there is also the possibility to -install by manually copying files. - -@enumerate a -@item -Copy the reftex*.el lisp files to a directory on your load path. Make -sure that no old copy of @RefTeX{} shadows these files. -@item -Byte compile the files. The sequence of compiling should be: -reftex-var.el, reftex.el, and then all the others. -@item -Copy the info file reftex.info to the info directory. -@end enumerate - -@subsection Loading @RefTeX{} - -In order to make the most important functions for entering @RefTeX{} -mode available add the following line to your init file. - -@example -(require 'reftex) -@end example - -@subsection Entering @RefTeX{} Mode - -@findex turn-on-reftex -@findex reftex-mode -@vindex LaTeX-mode-hook -@vindex latex-mode-hook -To turn @RefTeX{} Mode on and off in a particular buffer, use -@kbd{M-x reftex-mode @key{RET}}. To turn on @RefTeX{} Mode for all -LaTeX files, add the following lines to your @file{.emacs} file: - -@example -(add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode -(add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode -@end example - -That's all! - -To get started, read the documentation, in particular the -summary. (@pxref{RefTeX in a Nutshell}) - -In order to produce a printed version of the documentation, use -@code{make pdf} to produce a reftex.pdf file. Analogously you can use -the @code{dvi}, @code{ps}, or @code{html} targets to create DVI, -PostScript or HTML files. - -@subsection Environment -@cindex Finding files -@cindex BibTeX database files, not found -@cindex TeX files, not found -@cindex @code{TEXINPUTS}, environment variable -@cindex @code{BIBINPUTS}, environment variable - -@RefTeX{} needs to access all files which are part of a multifile -document, and the BibTeX database files requested by the -@code{\bibliography} command. To find these files, @RefTeX{} will -require a search path, i.e., a list of directories to check. Normally -this list is stored in the environment variables @code{TEXINPUTS} and -@code{BIBINPUTS} which are also used by @RefTeX{}. However, on some -systems these variables do not contain the full search path. If -@RefTeX{} does not work for you because it cannot find some files, -@xref{Finding Files}. - -@page -@node RefTeX in a Nutshell -@section @RefTeX{} in a Nutshell -@cindex Quick-Start -@cindex Getting Started -@cindex RefTeX in a Nutshell -@cindex Nutshell, RefTeX in a - -@enumerate -@item -@b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show -a table of contents of the document. This buffer can display sections, -labels and index entries defined in the document. From the buffer, you -can jump quickly to every part of your document. Press @kbd{?} to get -help. - -@item -@b{Labels and References}@* @RefTeX{} helps to create unique labels -and to find the correct key for references quickly. It distinguishes -labels for different environments, knows about all standard -environments (and many others), and can be configured to recognize any -additional labeled environments you have defined yourself (variable -@code{reftex-label-alist}). - -@itemize @bullet -@item -@b{Creating Labels}@* -Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point. -@RefTeX{} will either -@itemize @minus -@item -derive a label from context (default for section labels) -@item -prompt for a label string (default for figures and tables) or -@item -insert a simple label made of a prefix and a number (all other -environments) -@end itemize -@noindent -Which labels are created how is configurable with the variable -@code{reftex-insert-label-flags}. - -@item -@b{Referencing Labels}@* To make a reference, type @kbd{C-c )} -(@code{reftex-reference}). This shows an outline of the document with -all labels of a certain type (figure, equation,...) and some label -context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro -into the original buffer. -@end itemize - -@item -@b{Citations}@* -Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a -regular expression to search in current @BibTeX{} database files (as -specified in the @code{\bibliography} command) and pull out a list of -matches for you to choose from. The list is @emph{formatted} and -sorted. The selected article is referenced as @samp{\cite@{@var{key}@}} -(see the variable @code{reftex-cite-format} if you want to insert -different macros). - -@item -@b{Index Support}@* -@RefTeX{} helps to enter index entries. It also compiles all -entries into an alphabetically sorted @file{*Index*} buffer which you -can use to check and edit the entries. @RefTeX{} knows about the -standard index macros and can be configured to recognize any additional -macros you have defined (@code{reftex-index-macros}). Multiple indices -are supported. - -@itemize @bullet -@item -@b{Creating Index Entries}@* -To index the current selection or the word at point, type @kbd{C-c /} -(@code{reftex-index-selection-or-word}). The default macro -@code{reftex-index-default-macro} will be used. For a more complex entry -type @kbd{C-c <} (@code{reftex-index}), select any of the index macros -and enter the arguments with completion. - -@item -@b{The Index Phrases File (Delayed Indexing)}@* -Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add -the current word or selection to a special @emph{index phrase file}. -@RefTeX{} can later search the document for occurrences of these -phrases and let you interactively index the matches. - -@item -@b{Displaying and Editing the Index}@* -To display the compiled index in a special buffer, type @kbd{C-c >} -(@code{reftex-display-index}). From that buffer you can check and edit -all entries. -@end itemize - -@page -@item @b{Viewing Cross-References}@* -When point is on the @var{key} argument of a cross-referencing macro -(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, -@code{\index}, and variations) or inside a @BibTeX{} database entry, you -can press @kbd{C-c &} (@code{reftex-view-crossref}) to display -corresponding locations in the document and associated @BibTeX{} database -files. @* -When the enclosing macro is @code{\cite} or @code{\ref} and no other -message occupies the echo area, information about the citation or label -will automatically be displayed in the echo area. - -@item -@b{Multifile Documents}@* -Multifile Documents are fully supported. The included files must have a -file variable @code{TeX-master} or @code{tex-main-file} pointing to the -master file. @RefTeX{} provides cross-referencing information from -all parts of the document, and across document borders -(@file{xr.sty}). - -@item -@b{Document Parsing}@* @RefTeX{} needs to parse the document in -order to find labels and other information. It does it automatically -once and updates its list internally when @code{reftex-label} and -@code{reftex-index} are used. To enforce reparsing, call any of the -commands described above with a raw @kbd{C-u} prefix, or press the -@kbd{r} key in the label selection buffer, the table of contents -buffer, or the index buffer. - -@item -@b{@AUCTeX{}} @* If your major @LaTeX{} mode is @AUCTeX{}, @RefTeX{} can -cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). @AUCTeX{} -contains style files which trigger appropriate settings in -@RefTeX{}, so that for many of the popular @LaTeX{} packages no -additional customizations will be necessary. - -@item -@b{Useful Settings}@* -To integrate RefTeX with @AUCTeX{}, use -@lisp -(setq reftex-plug-into-AUCTeX t) -@end lisp - -To make your own @LaTeX{} macro definitions known to @RefTeX{}, -customize the variables -@example -@code{reftex-label-alist} @r{(for label macros/environments)} -@code{reftex-section-levels} @r{(for sectioning commands)} -@code{reftex-cite-format} @r{(for @code{\cite}-like macros)} -@code{reftex-index-macros} @r{(for @code{\index}-like macros)} -@code{reftex-index-default-macro} @r{(to set the default macro)} -@end example -If you have a large number of macros defined, you may want to write -an @AUCTeX{} style file to support them with both @AUCTeX{} and -@RefTeX{}. - -@item @b{Where Next?}@* Go ahead and use @RefTeX{}. Use its menus -until you have picked up the key bindings. For an overview of what you -can do in each of the different special buffers, press @kbd{?}. Read -the manual if you get stuck, or if you are curious what else might be -available. The first part of the manual explains in -a tutorial way how to use and customize @RefTeX{}. The second -part is a command and variable reference. -@end enumerate - -@node Table of Contents -@chapter Table of Contents -@cindex @file{*toc*} buffer -@cindex Structure editing -@cindex Table of contents buffer -@findex reftex-toc -@kindex C-c = - -Pressing the keys @kbd{C-c =} pops up a buffer showing the table of -contents of the document. By default, this @file{*toc*} buffer shows -only the sections of a document. Using the @kbd{l} and @kbd{i} keys you -can display all labels and index entries defined in the document as -well. - -With the cursor in any of the lines denoting a location in the -document, simple key strokes will display the corresponding part in -another window, jump to that location, or perform other actions. - -@kindex ? -Here is a list of special commands in the @file{*toc*} buffer. A -summary of this information is always available by pressing -@kbd{?}. - -@table @kbd - -@tablesubheading{General} -@item ? -Display a summary of commands. - -@item 0-9, - -Prefix argument. - -@tablesubheading{Moving around} -@item n -Goto next entry in the table of contents. - -@item p -Goto previous entry in the table of contents. - -@item C-c C-n -Goto next section heading. Useful when many labels and index entries -separate section headings. - -@item C-c C-p -Goto previous section heading. - -@item N z -Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps -to section 3. - -@tablesubheading{Access to document locations} -@item @key{SPC} -Show the corresponding location in another window. This command does -@emph{not} select that other window. - -@item @key{TAB} -Goto the location in another window. - -@item @key{RET} -Go to the location and hide the @file{*toc*} buffer. This will restore -the window configuration before @code{reftex-toc} (@kbd{C-c =}) was -called. - -@item mouse-2 -@vindex reftex-highlight-selection -Clicking with mouse button 2 on a line has the same effect as @key{RET}. -See also variable @code{reftex-highlight-selection}, -@ref{Options - Fontification}. - -@item f -@vindex reftex-toc-follow-mode -@vindex reftex-revisit-to-follow -Toggle follow mode. When follow mode is active, the other window will -always show the location corresponding to the line at point in the -@file{*toc*} buffer. This is similar to pressing @key{SPC} after each -cursor motion. The default for this flag can be set with the variable -@code{reftex-toc-follow-mode}. Note that only context in files already -visited is shown. @RefTeX{} will not visit a file just for follow -mode. See, however, the variable -@code{reftex-revisit-to-follow}. - -@item . -Show calling point in another window. This is the point from where -@code{reftex-toc} was last called. - -@page -@tablesubheading{Promotion and Demotion} - -@item < -Promote the current section. This will convert @code{\section} to -@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is -an active region, all sections in the region will be promoted, including -the one at point. To avoid mistakes, @RefTeX{} requires a fresh -document scan before executing this command; if necessary, it will -automatically do this scan and ask the user to repeat the promotion -command. - -@item > -Demote the current section. This is the opposite of promotion. It will -convert @code{\chapter} to @code{\section} etc. If there is an active -region, all sections in the region will be demoted, including the one at -point. - -@item M-% -Rename the label at point. While generally not recommended, this can be -useful when a package like @file{fancyref} is used where the label -prefix determines the wording of a reference. After a -promotion/demotion it may be necessary to change a few labels from -@samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be -used to do this; it launches a query replace to rename the definition -and all references of a label. - -@tablesubheading{Exiting} -@item q -Hide the @file{*toc*} buffer, return to the position where -@code{reftex-toc} was last called. - -@item k -Kill the @file{*toc*} buffer, return to the position where -@code{reftex-toc} was last called. - -@item C-c > -Switch to the @file{*Index*} buffer of this document. With prefix -@samp{2}, restrict the index to the section at point in the @file{*toc*} -buffer. - -@tablesubheading{Controlling what gets displayed} - -@item t -@vindex reftex-toc-max-level -Change the maximum level of toc entries displayed in the @file{*toc*} -buffer. Without prefix arg, all levels will be included. With prefix -arg (e.g., @kbd{3 t}), ignore all toc entries with level greater than -@var{arg} (3 in this case). Chapters are level 1, sections are level 2. -The mode line @samp{T<>} indicator shows the current value. The default -depth can be configured with the variable -@code{reftex-toc-max-level}. - -@item F -@vindex reftex-toc-include-file-boundaries -Toggle the display of the file borders of a multifile document in the -@file{*toc*} buffer. The default for this flag can be set with the -variable @code{reftex-toc-include-file-boundaries}. - -@item l -@vindex reftex-toc-include-labels -Toggle the display of labels in the @file{*toc*} buffer. The default -for this flag can be set with the variable -@code{reftex-toc-include-labels}. When called with a prefix argument, -@RefTeX{} will prompt for a label type and include only labels of -the selected type in the @file{*toc*} buffer. The mode line @samp{L<>} -indicator shows which labels are included. - -@item i -@vindex reftex-toc-include-index-entries -Toggle the display of index entries in the @file{*toc*} buffer. The -default for this flag can be set with the variable -@code{reftex-toc-include-index-entries}. When called with a prefix -argument, @RefTeX{} will prompt for a specific index and include -only entries in the selected index in the @file{*toc*} buffer. The mode -line @samp{I<>} indicator shows which index is used. - -@item c -@vindex reftex-toc-include-context -Toggle the display of label and index context in the @file{*toc*} -buffer. The default for this flag can be set with the variable -@code{reftex-toc-include-context}. - -@tablesubheading{Updating the buffer} - -@item g -Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the -document. - -@item r -@vindex reftex-enable-partial-scans -Reparse the @LaTeX{} document and rebuild the @file{*toc*} buffer. When -@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this -location is defined in, not the entire document. - -@item C-u r -Reparse the @emph{entire} @LaTeX{} document and rebuild the @file{*toc*} -buffer. - -@item x -Switch to the @file{*toc*} buffer of an external document. When the -current document is using the @code{xr} package (@pxref{LaTeX xr Package}), -@RefTeX{} will switch to one of the external documents. - - -@tablesubheading{Automatic recentering} - -@item d -Toggle the display of a dedicated frame displaying just the @file{*toc*} -buffer. Follow mode and visiting locations will not work that frame, -but automatic recentering will make this frame always show your current -editing location in the document (see below). - -@item a -Toggle the automatic recentering of the @file{*toc*} buffer. When this -option is on, moving around in the document will cause the @file{*toc*} -to always highlight the current section. By default, this option is -active while the dedicated @file{*TOC*} frame exists. See also the -variable @code{reftex-auto-recenter-toc}. - -@end table - -@vindex reftex-toc-map -In order to define additional commands for the @file{*toc*} buffer, the -keymap @code{reftex-toc-map} may be used. - -@findex reftex-toc-recenter -@vindex reftex-auto-recenter-toc -@vindex reftex-idle-time -@cindex @file{*toc*} buffer, recentering -@cindex Table of contents buffer, recentering -@kindex C-c - -If you call @code{reftex-toc} while the @file{*toc*} buffer already -exists, the cursor will immediately jump to the right place, i.e., the -section from which @code{reftex-toc} was called will be highlighted. -The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay -the @file{*toc*} buffer and highlight the correct line without actually -selecting the @file{*toc*} window. This can be useful to quickly find -out where in the document you currently are. You can also automate this -by asking RefTeX to keep track of your current editing position in the -TOC@. The TOC window will then be updated whenever you stop typing for -more than @code{reftex-idle-time} seconds. By default this works only -with the dedicated @file{*TOC*} frame. But you can also force automatic -recentering of the TOC window on the current frame with -@lisp -(setq reftex-auto-recenter-toc t) -@end lisp - - -@cindex Sectioning commands -@cindex KOMA-Script, LaTeX classes -@cindex LaTeX classes, KOMA-Script -@cindex TOC entries for environments -@vindex reftex-section-levels -The section macros recognized by @RefTeX{} are all @LaTeX{} section -macros (from @code{\part} to @code{\subsubparagraph}) and the commands -@code{\addchap} and @code{\addsec} from the KOMA-Script classes. -Additional macros can be configured with the variable -@code{reftex-section-levels}. It is also possible to add certain @LaTeX{} -environments to the table of contents. This is probably only useful for -theorem-like environments. @xref{Defining Label Environments}, for an -example. - -@node Labels and References -@chapter Labels and References -@cindex Labels in LaTeX -@cindex References in LaTeX -@cindex Label category -@cindex Label environment -@cindex @code{\label} - -@LaTeX{} provides a powerful mechanism to deal with cross-references in a -document. When writing a document, any part of it can be marked with a -label, like @samp{\label@{mark@}}. @LaTeX{} records the current value of a -certain counter when a label is defined. Later references to this label -(like @samp{\ref@{mark@}}) will produce the recorded value of the -counter. - -Labels can be used to mark sections, figures, tables, equations, -footnotes, items in enumerate lists etc. @LaTeX{} is context sensitive in -doing this: A label defined in a figure environment automatically -records the figure counter, not the section counter. - -Several different environments can share a common counter and therefore -a common label category. For example labels in both @code{equation} and -@code{eqnarray} environments record the value of the same counter: the -equation counter. - -@menu -* Creating Labels:: -* Referencing Labels:: -* Builtin Label Environments:: The environments RefTeX knows about. -* Defining Label Environments:: ... and environments it doesn't. -* Reference Info:: View the label corresponding to a \ref. -* Reference Styles:: Macros to be used instead of \ref. -* LaTeX xr Package:: References to external documents. -@end menu - -@node Creating Labels -@section Creating Labels -@cindex Creating labels -@cindex Labels, creating -@cindex Labels, deriving from context -@kindex C-c ( -@findex reftex-label - -In order to create a label in a @LaTeX{} document, press @kbd{C-c (} -(@code{reftex-label}). Just like @LaTeX{}, @RefTeX{} is context sensitive -and will figure out the environment it currently is in and adapt the -label to that environment. A label usually consists of a short prefix -indicating the type of the label and a unique mark. @RefTeX{} has -three different modes to create this mark. - -@enumerate -@item -@vindex reftex-translate-to-ascii-function -@vindex reftex-derive-label-parameters -@vindex reftex-label-illegal-re -@vindex reftex-abbrev-parameters -A label can be derived from context. This means, @RefTeX{} takes -the context of the label definition and constructs a label from -that@footnote{Note that the context may contain constructs which are -invalid in labels. @RefTeX{} will therefore strip the accent from -accented Latin-1 characters and remove everything else which is not -valid in labels. This mechanism is safe, but may not be satisfactory -for non-western languages. Check the following variables if you need to -change things: @code{reftex-translate-to-ascii-function}, -@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re}, -@code{reftex-abbrev-parameters}.}. This works best for section labels, -where the section heading is used to construct a label. In fact, -@RefTeX{}'s default settings use this method only for section -labels. You will be asked to confirm the derived label, or edit -it. - -@item -We may also use a simple unique number to identify a label. This is -mostly useful for labels where it is difficult to come up with a very -good descriptive name. @RefTeX{}'s default settings use this method -for equations, enumerate items and footnotes. The author of @RefTeX{} -tends to write documents with many equations and finds it impossible -to come up with good names for each of them. These simple labels are -inserted without query, and are therefore very fast. Good descriptive -names are not really necessary as @RefTeX{} will provide context to -reference a label (@pxref{Referencing Labels}). - -@item -The third method is to ask the user for a label. This is most -useful for things which are easy to describe briefly and do not turn up -too frequently in a document. @RefTeX{} uses this for figures and -tables. Of course, one can enter the label directly by typing the full -@samp{\label@{mark@}}. The advantage of using @code{reftex-label} -anyway is that @RefTeX{} will know that a new label has been defined. -It will then not be necessary to rescan the document in order to access -this label later. -@end enumerate - -@vindex reftex-insert-label-flags -If you want to change the way certain labels are created, check out the -variable @code{reftex-insert-label-flags} (@pxref{Options - Creating -Labels}). - -If you are using @AUCTeX{} to write your @LaTeX{} documents, you can -set it up to delegate the creation of labels to -@RefTeX{}. @xref{AUCTeX}, for more information. - -@node Referencing Labels -@section Referencing Labels -@cindex Referencing labels -@cindex Labels, referencing -@cindex Selection buffer, labels -@cindex Selection process -@cindex @code{\ref} -@kindex C-c ) -@findex reftex-reference - -@vindex reftex-trust-label-prefix -@RefTeX{} scans the document in order to find all labels. To make -referencing labels easier, it assigns to each label a category, the -@emph{label type} (for example section, table, figure, equation, etc.). -In order to determine the label type, @RefTeX{} parses around each label -to see in what kind of environments it is located. You can speed up -the parsing by using type-specific prefixes for labels and configuring -the variable @code{reftex-trust-label-prefix}. - -Referencing Labels is really at the heart of @RefTeX{}. Press @kbd{C-c -)} in order to reference a label (@code{reftex-reference}). This will -start a selection process and finally insert the complete -@samp{\ref@{label@}} into the buffer. - -@vindex reftex-ref-macro-prompt -First, you can select which reference macro you want to use, -e.g., @samp{\ref} or @samp{\pageref}. Later in the process you have -another chance to make this selection and you can therefore disable this -step by customizing @code{reftex-ref-macro-prompt} if you find it too -intrusive. @xref{Reference Styles}. - -Then, @RefTeX{} will determine the label category which is required. -Often that can be figured out from context. For example, if you write -@samp{As shown in eq.} and then press @kbd{C-c )}, @RefTeX{} knows that -an equation label is going to be referenced. If it cannot figure out -what label category is needed, it will query for one. - -You will then be presented with a label selection menu. This is a -special buffer which contains an outline of the document along with all -labels of the given label category. In addition, next to the label -there will be one line of context of the label definition, which is some -text in the buffer near the label definition. Usually this is -sufficient to identify the label. If you are unsure about a certain -label, pressing @key{SPC} will show the label definition point in -another window. - -In order to reference a label, move the cursor to the correct label and -press @key{RET}. You can also reference several labels with a single -call to @code{reftex-reference} by marking entries with the @kbd{m} -key (see below). - -@kindex ? -Here is a list of special commands in the selection buffer. A summary -of this information is always available from the selection process by -pressing @kbd{?}. - - - -@table @kbd -@tablesubheading{General} -@item ? -Show a summary of available commands. - -@item 0-9,- -Prefix argument. - -@tablesubheading{Moving around} -@item n -Go to next label. - -@item p -Go to previous label. - -@item b -Jump back to the position where you last left the selection buffer. -Normally this should get you back to the last referenced label. - -@item C-c C-n -Goto next section heading. - -@item C-c C-p -Goto previous section heading. - -@item N z -Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to -section 3. - -@tablesubheading{Displaying Context} -@item @key{SPC} -Show the surroundings of the definition of the current label in another -window. See also the @kbd{f} key. - -@item f -@vindex reftex-revisit-to-follow -Toggle follow mode. When follow mode is active, the other window will -always display the full context of the current label. This is similar -to pressing @key{SPC} after each cursor motion. Note that only context -in files already visited is shown. @RefTeX{} will not visit a file -just for follow mode. See, however, the variable -@code{reftex-revisit-to-follow}. - -@item . -Show insertion point in another window. This is the point from where you -called @code{reftex-reference}. - -@tablesubheading{Selecting a label and creating the reference} -@item @key{RET} -Insert a reference to the label at point into the buffer from which the -selection process was started. When entries have been marked, @key{RET} -references all marked labels. - -@item mouse-2 -@vindex reftex-highlight-selection -Clicking with mouse button 2 on a label will accept it like @key{RET} -would. See also variable @code{reftex-highlight-selection}, -@ref{Options - Misc}. - -@vindex reftex-multiref-punctuation -@item m - + , -Mark the current entry. When several entries have been marked, pressing -@kbd{RET} will accept all of them and place them into several -@code{\ref} macros. The special markers @samp{,-+} also store a -separator to be inserted before the corresponding reference. So marking -six entries with the keys @samp{m , , - , +} will give a reference list -like this (see the variable @code{reftex-multiref-punctuation}) -@example -In eqs. (1), (2), (3)--(4), (5) and (6) -@end example - -@item u -Unmark a marked entry. - -@c FIXME: Do we need `A' as well for consistency? -@cindex LaTeX packages, @code{saferef} -@cindex @code{saferef}, LaTeX package -@item a -Accept the marked entries and put all labels as a comma-separated list -into one @emph{single} @code{\ref} macro. Some packages like -@file{saferef.sty} support multiple references in this way. - -@item l -Use the last referenced label(s) again. This is equivalent to moving to -that label and pressing @key{RET}. - -@item @key{TAB} -Enter a label with completion. This may also be a label which does not -yet exist in the document. - -@item v -Cycle forward through active reference macros. The selected macro is -displayed by the @samp{S<...>} indicator in the mode line of the -selection buffer. This mechanism comes in handy if you are using -@LaTeX{} packages like @code{varioref} or @code{fancyref} and want to -use the special referencing macros they provide (e.g., @code{\vref} or -@code{\fref}) instead of @code{\ref}. - -@item V -Cycle backward through active reference macros. - -@tablesubheading{Exiting} - -@item q -Exit the selection process without inserting any reference into the -buffer. - -@tablesubheading{Controlling what gets displayed} -@vindex reftex-label-menu-flags -The defaults for the following flags can be configured with the variable -@code{reftex-label-menu-flags} (@pxref{Options - Referencing Labels}). - -@item c -Toggle the display of the one-line label definition context in the -selection buffer. - -@item F -Toggle the display of the file borders of a multifile document in the -selection buffer. - -@item t -Toggle the display of the table of contents in the selection buffer. -With prefix @var{arg}, change the maximum level of toc entries displayed -to @var{arg}. Chapters are level 1, sections are level 2. - -@item # -Toggle the display of a label counter in the selection buffer. - -@item % -Toggle the display of labels hidden in comments in the selection -buffers. Sometimes, you may have commented out parts of your document. -If these parts contain label definitions, @RefTeX{} can still display -and reference these labels. - -@tablesubheading{Updating the buffer} -@item g -Update the menu. This will rebuilt the menu from the internal label -list, but not reparse the document (see @kbd{r}). - -@item r -@vindex reftex-enable-partial-scans -Reparse the document to update the information on all labels and rebuild -the menu. If the variable @code{reftex-enable-partial-scans} is -non-@code{nil} and your document is a multifile document, this will -reparse only a part of the document (the file in which the label at -point was defined). - -@item C-u r -Reparse the @emph{entire} document. - -@item s -Switch the label category. After prompting for another label category, -a menu for that category will be shown. - -@item x -Reference a label from an external document. With the @LaTeX{} package -@code{xr} it is possible to reference labels defined in another -document. This key will switch to the label menu of an external -document and let you select a label from there (@pxref{LaTeX xr Package,,xr}). - -@end table - -@vindex reftex-select-label-map -In order to define additional commands for the selection process, the -keymap @code{reftex-select-label-map} may be used. - -@node Builtin Label Environments -@section Builtin Label Environments -@cindex Builtin label environments -@cindex Label environments, builtin -@cindex Environments, builtin -@vindex reftex-label-alist -@vindex reftex-label-alist-builtin - -@RefTeX{} needs to be aware of the environments which can be referenced -with a label (i.e., which carry their own counters). By default, @RefTeX{} -recognizes all labeled environments and macros discussed in @cite{The -@LaTeX{} Companion by Goossens, Mittelbach & Samarin, Addison-Wesley -1994.}. These are: - -@itemize @minus -@item -@cindex @code{figure}, LaTeX environment -@cindex @code{figure*}, LaTeX environment -@cindex @code{table}, LaTeX environment -@cindex @code{table*}, LaTeX environment -@cindex @code{equation}, LaTeX environment -@cindex @code{eqnarray}, LaTeX environment -@cindex @code{enumerate}, LaTeX environment -@cindex @code{\footnote}, LaTeX macro -@cindex LaTeX macro @code{footnote} -@cindex LaTeX core -@code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation}, -@code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is -the @LaTeX{} core stuff) -@item -@cindex AMS-LaTeX -@cindex @code{amsmath}, LaTeX package -@cindex LaTeX packages, @code{amsmath} -@cindex @code{align}, AMS-LaTeX environment -@cindex @code{gather}, AMS-LaTeX environment -@cindex @code{multline}, AMS-LaTeX environment -@cindex @code{flalign}, AMS-LaTeX environment -@cindex @code{alignat}, AMS-LaTeX environment -@cindex @code{xalignat}, AMS-LaTeX environment -@cindex @code{xxalignat}, AMS-LaTeX environment -@cindex @code{subequations}, AMS-LaTeX environment -@code{align}, @code{gather}, @code{multline}, @code{flalign}, -@code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations} -(from AMS-@LaTeX{}'s @file{amsmath.sty} package) -@item -@cindex @code{endnote}, LaTeX package -@cindex LaTeX packages, @code{endnote} -@cindex @code{\endnote}, LaTeX macro -the @code{\endnote} macro (from @file{endnotes.sty}) -@item -@cindex @code{fancybox}, LaTeX package -@cindex LaTeX packages, @code{fancybox} -@cindex @code{Beqnarray}, LaTeX environment -@code{Beqnarray} (@file{fancybox.sty}) -@item -@cindex @code{floatfig}, LaTeX package -@cindex LaTeX packages, @code{floatfig} -@cindex @code{floatingfig}, LaTeX environment -@code{floatingfig} (@file{floatfig.sty}) -@item -@cindex @code{longtable}, LaTeX package -@cindex LaTeX packages, @code{longtable} -@cindex @code{longtable}, LaTeX environment -@code{longtable} (@file{longtable.sty}) -@item -@cindex @code{picinpar}, LaTeX package -@cindex LaTeX packages, @code{picinpar} -@cindex @code{figwindow}, LaTeX environment -@cindex @code{tabwindow}, LaTeX environment -@code{figwindow}, @code{tabwindow} (@file{picinpar.sty}) -@item -@cindex @code{sidecap}, LaTeX package -@cindex LaTeX packages, @code{sidecap} -@cindex @code{SCfigure}, LaTeX environment -@cindex @code{SCtable}, LaTeX environment -@code{SCfigure}, @code{SCtable} (@file{sidecap.sty}) -@item -@cindex @code{rotating}, LaTeX package -@cindex LaTeX packages, @code{rotating} -@cindex @code{sidewaysfigure}, LaTeX environment -@cindex @code{sidewaystable}, LaTeX environment -@code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty}) -@item -@cindex @code{subfig}, LaTeX package -@cindex LaTeX packages, @code{subfigure} -@cindex @code{subfigure}, LaTeX environment -@cindex @code{subfigure*}, LaTeX environment -@code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro -(@file{subfigure.sty}) -@item -@cindex @code{supertab}, LaTeX package -@cindex LaTeX packages, @code{supertab} -@cindex @code{supertabular}, LaTeX environment -@code{supertabular} (@file{supertab.sty}) -@item -@cindex @code{wrapfig}, LaTeX package -@cindex LaTeX packages, @code{wrapfig} -@cindex @code{wrapfigure}, LaTeX environment -@code{wrapfigure} (@file{wrapfig.sty}) -@end itemize - -If you want to use other labeled environments, defined with -@code{\newtheorem}, @RefTeX{} needs to be configured to recognize -them (@pxref{Defining Label Environments}). - -@node Defining Label Environments -@section Defining Label Environments -@cindex Label environments, defining - -@vindex reftex-label-alist -@RefTeX{} can be configured to recognize additional labeled -environments and macros. This is done with the variable -@code{reftex-label-alist} (@pxref{Options - Defining Label -Environments}). If you are not familiar with Lisp, you can use the -@code{custom} library to configure this rather complex variable. To do -this, use - -@example -@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}} -@end example - -@vindex reftex-label-alist-builtin -Here we will discuss a few examples, in order to make things clearer. -It can also be instructive to look at the constant -@code{reftex-label-alist-builtin} which contains the entries for -all the builtin environments and macros (@pxref{Builtin Label -Environments}). - -@menu -* Theorem and Axiom:: Defined with @code{\newenvironment}. -* Quick Equation:: When a macro sets the label type. -* Figure Wrapper:: When a macro argument is a label. -* Adding Magic Words:: Other words for other languages. -* Using \eqref:: How to switch to this AMS-@LaTeX{} macro. -* Non-Standard Environments:: Environments without \begin and \end -* Putting it Together:: How to combine many entries. -@end menu - -@node Theorem and Axiom -@subsection Theorem and Axiom Environments -@cindex @code{theorem}, newtheorem -@cindex @code{axiom}, newtheorem -@cindex @code{\newtheorem} - -Suppose you are using @code{\newtheorem} in @LaTeX{} in order to define two -new environments, @code{theorem} and @code{axiom} - -@example -\newtheorem@{axiom@}@{Axiom@} -\newtheorem@{theorem@}@{Theorem@} -@end example - -@noindent -to be used like this: - -@example -\begin@{axiom@} -\label@{ax:first@} - .... -\end@{axiom@} -@end example - -So we need to tell @RefTeX{} that @code{theorem} and @code{axiom} are new -labeled environments which define their own label categories. We can -either use Lisp to do this (e.g., in @file{.emacs}) or use the custom -library. With Lisp it would look like this - -@lisp -(setq reftex-label-alist - '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) - ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3))) -@end lisp - -The type indicator characters @code{?a} and @code{?h} are used for -prompts when @RefTeX{} queries for a label type. @code{?h} -was chosen for @code{theorem} since @code{?t} is already taken by -@code{table}. Note that also @code{?s}, @code{?f}, @code{?e}, -@code{?i}, @code{?n} are already used for standard environments. - -@noindent -The labels for Axioms and Theorems will have the prefixes @samp{ax:} and -@samp{thr:}, respectively. @xref{AUCTeX}, for information on how -@AUCTeX{} can use @RefTeX{} to automatically create labels when a new -environment is inserted into a buffer. Additionally, the following -needs to be added to one's .emacs file before @AUCTeX{} will -automatically create labels for the new environments. - -@lisp -(add-hook 'LaTeX-mode-hook - (lambda () - (LaTeX-add-environments - '("axiom" LaTeX-env-label) - '("theorem" LaTeX-env-label)))) -@end lisp - - -@noindent -The @samp{~\ref@{%s@}} is a format string indicating how to insert -references to these labels. - -@noindent -The next item indicates how to grab context of the label definition. -@itemize @minus -@item -@code{t} means to get it from a default location (from the beginning of -a @code{\macro} or after the @code{\begin} statement). @code{t} is -@emph{not} a good choice for eqnarray and similar environments. -@item -@code{nil} means to use the text right after the label definition. -@item -For more complex ways of getting context, see the variable -@code{reftex-label-alist} (@ref{Options - Defining Label Environments}). -@end itemize - -The following list of strings is used to guess the correct label type -from the word before point when creating a reference. For example if you -write: @samp{As we have shown in Theorem} and then press @kbd{C-c )}, -@RefTeX{} will know that you are looking for a theorem label and -restrict the menu to only these labels without even asking. - -The final item in each entry is the level at which the environment -should produce entries in the table of context buffer. If the number is -positive, the environment will produce numbered entries (like -@code{\section}), if it is negative the entries will be unnumbered (like -@code{\section*}). Use this only for environments which structure the -document similar to sectioning commands. For everything else, omit the -item. - -To do the same configuration with @code{customize}, you need to click on -the @code{[INS]} button twice to create two templates and fill them in -like this: - -@example -Reftex Label Alist: [Hide] -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: axiom - Type specification : [Value Menu] Char : a - Label prefix string : [Value Menu] String: ax: - Label reference format: [Value Menu] String: ~\ref@{%s@} - Context method : [Value Menu] After label - Magic words: - [INS] [DEL] String: axiom - [INS] [DEL] String: ax. - [INS] - [X] Make TOC entry : [Value Menu] Level: -2 -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: theorem - Type specification : [Value Menu] Char : h - Label prefix string : [Value Menu] String: thr: - Label reference format: [Value Menu] String: ~\ref@{%s@} - Context method : [Value Menu] Default position - Magic words: - [INS] [DEL] String: theorem - [INS] [DEL] String: theor. - [INS] [DEL] String: th. - [INS] - [X] Make TOC entry : [Value Menu] Level: -3 -@end example - -@vindex reftex-insert-label-flags -@vindex reftex-label-menu-flags -Depending on how you would like the label insertion and selection for -the new environments to work, you might want to add the letters @samp{a} -and @samp{h} to some of the flags in the variables -@code{reftex-insert-label-flags} (@pxref{Options - Creating Labels}) -and @code{reftex-label-menu-flags} (@pxref{Options - Referencing Labels}). - - -@node Quick Equation -@subsection Quick Equation Macro -@cindex Quick equation macro -@cindex Macros as environment wrappers - -Suppose you would like to have a macro for quick equations. It -could be defined like this: - -@example -\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@} -@end example - -@noindent -and used like this: - -@example -Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}. -@end example - -We need to tell @RefTeX{} that any label defined in the argument of the -@code{\quickeq} is an equation label. Here is how to do this with lisp: - -@lisp -(setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil))) -@end lisp - -The first element in this list is now the macro with empty braces as an -@emph{image} of the macro arguments. @code{?e} indicates that this is -an equation label, the different @code{nil} elements indicate to use the -default values for equations. The @samp{1} as the fifth element -indicates that the context of the label definition should be the first -argument of the macro. - -Here is again how this would look in the customization buffer: - -@example -Reftex Label Alist: [Hide] -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: \quickeq@{@} - Type specification : [Value Menu] Char : e - Label prefix string : [Value Menu] Default - Label reference format: [Value Menu] Default - Context method : [Value Menu] Macro arg nr: 1 - Magic words: - [INS] - [ ] Make TOC entry : [Value Menu] No entry -@end example - -@node Figure Wrapper -@subsection Figure Wrapping Macro -@cindex Macros as environment wrappers -@cindex Figure wrapping macro - -Suppose you want to make figures not directly with the figure -environment, but with a macro like - -@example -\newcommand@{\myfig@}[5][tbp]@{% - \begin@{figure@}[#1] - \epsimp[#5]@{#2@} - \caption@{#3@} - \label@{#4@} - \end@{figure@}@} -@end example - -@noindent -which would be called like - -@example -\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@} -@end example - -Now we need to tell @RefTeX{} that the fourth argument of the -@code{\myfig} macro @emph{is itself} a figure label, and where to find -the context. - -@lisp -(setq reftex-label-alist - '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3))) -@end lisp - -The empty pairs of brackets indicate the different arguments of the -@code{\myfig} macro. The @samp{*} marks the label argument. @code{?f} -indicates that this is a figure label which will be listed together with -labels from normal figure environments. The @code{nil} entries for -prefix and reference format mean to use the defaults for figure labels. -The @samp{3} for the context method means to grab the third macro argument: -the caption. - -As a side effect of this configuration, @code{reftex-label} will now -insert the required naked label (without the @code{\label} macro) when -point is directly after the opening parenthesis of a @code{\myfig} macro -argument. - -Again, here the configuration in the customization buffer: - -@example -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@} - Type specification : [Value Menu] Char : f - Label prefix string : [Value Menu] Default - Label reference format: [Value Menu] Default - Context method : [Value Menu] Macro arg nr: 3 - Magic words: - [INS] - [ ] Make TOC entry : [Value Menu] No entry -@end example - -@node Adding Magic Words -@subsection Adding Magic Words -@cindex Magic words -@cindex German magic words -@cindex Label category - -Sometimes you don't want to define a new label environment or macro, but -just change the information associated with a label category. Maybe you -want to add some magic words, for another language. Changing only the -information associated with a label category is done by giving -@code{nil} for the environment name and then specify the items you want -to define. Here is an example which adds German magic words to all -predefined label categories. - -@lisp -(setq reftex-label-alist - '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil")) - (nil ?e nil nil nil ("Gleichung" "Gl.")) - (nil ?t nil nil nil ("Tabelle")) - (nil ?f nil nil nil ("Figur" "Abbildung" "Abb.")) - (nil ?n nil nil nil ("Anmerkung" "Anm.")) - (nil ?i nil nil nil ("Punkt")))) -@end lisp - -@node Using \eqref -@subsection Using @code{\eqref} -@cindex @code{\eqref}, AMS-LaTeX macro -@cindex AMS-LaTeX -@cindex Label category - -Another case where one only wants to change the information associated -with the label category is to change the macro which is used for -referencing the label. When working with the AMS-@LaTeX{}, you might -prefer @code{\eqref} for doing equation references. Here is how to -do this: - -@lisp -(setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil))) -@end lisp - -@RefTeX{} has also a predefined symbol for this special purpose. The -following is equivalent to the line above. - -@lisp -(setq reftex-label-alist '(AMSTeX)) -@end lisp - -Note that this is automatically done by the @file{amsmath.el} style file -of @AUCTeX{} (@pxref{Style Files}); so if you use @AUCTeX{}, -this configuration will not be necessary. - -@node Non-Standard Environments -@subsection Non-standard Environments -@cindex Non-standard environments -@cindex Environments without @code{\begin} -@cindex Special parser functions -@cindex Parser functions, for special environments - -Some @LaTeX{} packages define environment-like structures without using the -standard @samp{\begin..\end} structure. @RefTeX{} cannot parse -these directly, but you can write your own special-purpose parser and -use it instead of the name of an environment in an entry for -@code{reftex-label-alist}. The function should check if point is -currently in the special environment it was written to detect. If so, -it must return a buffer position indicating the start of this -environment. The return value must be @code{nil} on failure to detect -the environment. The function is called with one argument @var{bound}. -If non-@code{nil}, @var{bound} is a boundary for backwards searches -which should be observed. We will discuss two examples. - -@cindex LaTeX commands, abbreviated - -Some people define abbreviations for -environments, like @code{\be} for @code{\begin@{equation@}}, and -@code{\ee} for @code{\end@{equation@}}. The parser function would have -to search backward for these macros. When the first match is -@code{\ee}, point is not in this environment. When the first match is -@code{\be}, point is in this environment and the function must return -the beginning of the match. To avoid scanning too far, we can also look -for empty lines which cannot occur inside an equation environment. -Here is the setup: - -@lisp -;; Setup entry in reftex-label-alist, using all defaults for equations -(setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil))) - -(defun detect-be-ee (bound) - ;; Search backward for the macros or an empty line - (if (re-search-backward - "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t) - (if (match-beginning 2) - (match-beginning 2) ; Return start of environment - nil) ; Return nil because env is closed - nil)) ; Return nil for not found -@end lisp - -@cindex @code{linguex}, LaTeX package -@cindex LaTeX packages, @code{linguex} -A more complex example is the @file{linguex.sty} package which defines -list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are -terminated by @samp{\z.} or by an empty line. - -@example -\ex. \label@{ex:12@} Some text in an exotic language ... - \a. \label@{ex:13@} more stuff - \b. \label@{ex:14@} still more stuff - \a. List on a deeper level - \b. Another item - \b. and the third one - \z. - \b. Third item on this level. - -... text after the empty line terminating all lists -@end example - -The difficulty is that the @samp{\a.} lists can nest and that an empty -line terminates all list levels in one go. So we have to count nesting -levels between @samp{\a.} and @samp{\z.}. Here is the implementation -for @RefTeX{}. - -@lisp -(setq reftex-label-alist - '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) - -(defun detect-linguex (bound) - (let ((cnt 0)) - (catch 'exit - (while - ;; Search backward for all possible delimiters - (re-search-backward - (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|" - "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)") - nil t) - ;; Check which delimiter was matched. - (cond - ((match-beginning 1) - ;; empty line terminates all - return nil - (throw 'exit nil)) - ((match-beginning 2) - ;; \z. terminates one list level - decrease nesting count - (decf cnt)) - ((match-beginning 3) - ;; \ex. : return match unless there was a \z. on this level - (throw 'exit (if (>= cnt 0) (match-beginning 3) nil))) - ((match-beginning 4) - ;; \a. : return match when on level 0, otherwise - ;; increment nesting count - (if (>= cnt 0) - (throw 'exit (match-beginning 4)) - (incf cnt)))))))) -@end lisp - -@node Putting it Together -@subsection Putting it all together - -When you have to put several entries into @code{reftex-label-alist}, just -put them after each other in a list, or create that many templates in -the customization buffer. Here is a lisp example which uses several of -the entries described above: - -@lisp -(setq reftex-label-alist - '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) - ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3) - ("\\quickeq@{@}" ?e nil nil 1 nil) - AMSTeX - ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3) - (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) -@end lisp - -@node Reference Info -@section Reference Info -@findex reftex-view-crossref -@findex reftex-mouse-view-crossref -@cindex Cross-references, displaying -@cindex Reference info -@cindex Displaying cross-references -@cindex Viewing cross-references -@kindex C-c & -@kindex S-mouse-2 - -When point is idle for more than @code{reftex-idle-time} seconds on the -argument of a @code{\ref} macro, the echo area will display some -information about the label referenced there. Note that the information -is only displayed if the echo area is not occupied by a different -message. - -@RefTeX{} can also display the label definition corresponding to a -@code{\ref} macro, or all reference locations corresponding to a -@code{\label} macro. @xref{Viewing Cross-References}, for more -information. - -@node Reference Styles -@section Reference Styles - -In case you defined your own macros for referencing or you are using -@LaTeX{} packages providing specialized macros to be used instead of -@code{\ref}, @RefTeX{} provides ways to select and insert them in a -convenient way. - -@RefTeX{} comes equipped with a set of so-called reference styles where -each relates to one or more reference macros. The standard macros -@samp{\ref} and @samp{\pageref} or provided by the ``Default'' style. -The ``Varioref'' style offers macros for the @samp{varioref} @LaTeX{} -package (@samp{\vref}, @samp{\Vref}, @samp{\Ref}, @samp{\vpageref}), -``Fancyref'' for the @samp{fancyref} package (@samp{\fref}, -@samp{\Fref}) and ``Hyperref'' for the @samp{hyperref} package -(@samp{\autoref}, @samp{\autopageref}). - -@vindex reftex-ref-style-default-list -A style can be toggled by selecting the respective entry in the -@samp{Reference Style} menu. Changes made through the menu will only -last for the Emacs session. In order to configure a preference -permanently, the variable @code{reftex-ref-style-default-list} should be -customized. This variable specifies the list of styles to be activated. -It can also be set as a file variable if the preference should be set -for a specific file. - -@vindex reftex-ref-style-alist -In case the built-in styles do not suffice, you can add additional -macros and styles to the variable @code{reftex-ref-style-alist}. Those -do not necessarily have to be related to a certain @LaTeX{} package but -can follow an arbitrary grouping rule. For example you could define a -style called ``Personal'' for your personal referencing macros. (When -changing the variable you should be aware that other Emacs packages, -like @AUCTeX{}, might rely on the entries from the default value to be -present.) - -Once a style is active the macros it relates to are available for -selection when you are about to insert a reference. In general this -process involves three steps: the selection of a reference macro, a -label type and a label. Reference macros can be chosen in the first and -last step. - -@vindex reftex-ref-macro-prompt -In the first step you will be presented with a list of macros from which -you can select one by typing a single key. If you dislike having an -extra step for reference macro selection, you can disable it by -customizing @code{reftex-ref-macro-prompt} and relying only on the -selection facilities provided in the last step. - -In the last step, i.e., the label selection, two key bindings are -provided to set the reference macro. Type @key{v} in order to cycle -forward through the list of available macros or @key{V} to cycle -backward. The mode line of the selection buffer shows the macro -currently selected. - -In case you are not satisfied with the order of macros when cycling -through them you should adapt the order of entries in the variable -@code{reftex-ref-style-alist} to fit your liking. - -For each entry in @code{reftex-ref-style-alist} a function with the name -@code{reftex--} (e.g., @code{reftex-varioref-vref}) will -be created automatically by @RefTeX{}. These functions can be used -instead of @kbd{C-c )} and provide an alternative way of having your -favorite referencing macro preselected and if cycling through the macros -seems inconvenient to you.@footnote{You could, e.g., bind -@code{reftex-varioref-vref} to @kbd{C-c v} and -@code{reftex-fancyref-fref} to @kbd{C-c f}.} - -@cindex @code{varioref}, LaTeX package -@cindex LaTeX packages, @code{varioref} -@cindex @code{fancyref}, LaTeX package -@cindex LaTeX packages, @code{fancyref} -@vindex reftex-vref-is-default (deprecated) -@vindex reftex-fref-is-default (deprecated) -In former versions of @RefTeX{} only support for @code{varioref} and -@code{fancyref} was included. @code{varioref} is a @LaTeX{} package to -create cross-references with page information. @code{fancyref} is a -package where a macro call like @code{\fref@{@var{fig:map-of-germany}@}} -creates not only the number of the referenced counter but also the -complete text around it, like @samp{Figure 3 on the preceding page}. In -order to make it work you need to use label prefixes like @samp{fig:} -consistently---something @RefTeX{} does automatically. For each of -these packages a variable could be configured to make its macros to take -precedence over @code{\ref}. Those were @code{reftex-vref-is-default} -and @code{reftex-fref-is-default} respectively. While still working, -these variables are deprecated now. Instead of setting them, the -variable @code{reftex-ref-style-default-list} should be adapted now. - -@node LaTeX xr Package -@section @code{xr}: Cross-Document References -@cindex @code{xr}, LaTeX package -@cindex LaTeX packages, @code{xr} -@cindex @code{\externaldocument} -@cindex External documents -@cindex References to external documents -@cindex Cross-document references - -The @LaTeX{} package @code{xr} makes it possible to create references to -labels defined in external documents. The preamble of a document using -@code{xr} will contain something like this: - -@example -\usepackage@{xr@} -\externaldocument[V1-]@{volume1@} -\externaldocument[V3-]@{volume3@} -@end example - -@noindent -and we can make references to any labels defined in these -external documents by using the prefixes @samp{V1-} and @samp{V3-}, -respectively. - -@RefTeX{} can be used to create such references as well. Start the -referencing process normally, by pressing @kbd{C-c )}. Select a label -type if necessary. When you see the label selection buffer, pressing -@kbd{x} will switch to the label selection buffer of one of the external -documents. You may then select a label as before and @RefTeX{} will -insert it along with the required prefix. - -For this kind of inter-document cross-references, saving of parsing -information and the use of multiple selection buffers can mean a large -speed-up (@pxref{Optimizations}). - -@node Citations -@chapter Citations -@cindex Citations -@cindex @code{\cite} - -Citations in @LaTeX{} are done with the @code{\cite} macro or variations of -it. The argument of the macro is a citation key which identifies an -article or book in either a @BibTeX{} database file or in an explicit -@code{thebibliography} environment in the document. @RefTeX{}'s -support for citations helps to select the correct key quickly. - -@menu -* Creating Citations:: How to create them. -* Citation Styles:: Natbib, Harvard, Chicago and Co. -* Citation Info:: View the corresponding database entry. -* Chapterbib and Bibunits:: Multiple bibliographies in a Document. -* Citations Outside LaTeX:: How to make citations in Emails etc. -* BibTeX Database Subsets:: Extract parts of a big database. -@end menu - -@node Creating Citations -@section Creating Citations -@cindex Creating citations -@cindex Citations, creating -@findex reftex-citation -@kindex C-c [ -@cindex Selection buffer, citations -@cindex Selection process - -In order to create a citation, press @kbd{C-c [}. @RefTeX{} then -prompts for a regular expression which will be used to search through -the database and present the list of matches to choose from in a -selection process similar to that for selecting labels -(@pxref{Referencing Labels}). - -The regular expression uses an extended syntax: @samp{&&} defines a -logic @code{and} for regular expressions. For example -@samp{Einstein&&Bose} will match all articles which mention -Bose-Einstein condensation, or which are co-authored by Bose and -Einstein. When entering the regular expression, you can complete on -known citation keys. @RefTeX{} also offers a default when prompting for -a regular expression. This default is the word before the cursor or the -word before the current @samp{\cite} command. Sometimes this may be a -good search key. - -@cindex @code{\bibliography} -@cindex @code{thebibliography}, LaTeX environment -@cindex @code{BIBINPUTS}, environment variable -@cindex @code{TEXBIB}, environment variable -@RefTeX{} prefers to use @BibTeX{} database files specified with a -@code{\bibliography} macro to collect its information. Just like -@BibTeX{}, it will search for the specified files in the current directory -and along the path given in the environment variable @code{BIBINPUTS}. -If you do not use @BibTeX{}, but the document contains an explicit -@code{thebibliography} environment, @RefTeX{} will collect its -information from there. Note that in this case the information -presented in the selection buffer will just be a copy of relevant -@code{\bibitem} entries, not the structured listing available with -@BibTeX{} database files. - -@kindex ? -In the selection buffer, the following keys provide special commands. A -summary of this information is always available from the selection -process by pressing @kbd{?}. - -@table @kbd -@tablesubheading{General} -@item ? -Show a summary of available commands. - -@item 0-9,- -Prefix argument. - -@tablesubheading{Moving around} -@item n -Go to next article. - -@item p -Go to previous article. - -@tablesubheading{Access to full database entries} -@item @key{SPC} -Show the database entry corresponding to the article at point, in -another window. See also the @kbd{f} key. - -@item f -Toggle follow mode. When follow mode is active, the other window will -always display the full database entry of the current article. This is -equivalent to pressing @key{SPC} after each cursor motion. With @BibTeX{} -entries, follow mode can be rather slow. - -@tablesubheading{Selecting entries and creating the citation} -@item @key{RET} -Insert a citation referencing the article at point into the buffer from -which the selection process was started. - -@item mouse-2 -@vindex reftex-highlight-selection -Clicking with mouse button 2 on a citation will accept it like @key{RET} -would. See also variable @code{reftex-highlight-selection}, -@ref{Options - Misc}. - -@item m -Mark the current entry. When one or several entries are marked, -pressing @kbd{a} or @kbd{A} accepts all marked entries. Also, -@key{RET} behaves like the @kbd{a} key. - -@item u -Unmark a marked entry. - -@item a -Accept all (marked) entries in the selection buffer and create a single -@code{\cite} macro referring to them. - -@item A -Accept all (marked) entries in the selection buffer and create a -separate @code{\cite} macro for each of it. - -@item e -Create a new @BibTeX{} database file which contains all @i{marked} entries -in the selection buffer. If no entries are marked, all entries are -selected. - -@item E -Create a new @BibTeX{} database file which contains all @i{unmarked} -entries in the selection buffer. If no entries are marked, all entries -are selected. - -@item @key{TAB} -Enter a citation key with completion. This may also be a key which does -not yet exist. - -@item . -Show insertion point in another window. This is the point from where you -called @code{reftex-citation}. - -@tablesubheading{Exiting} -@item q -Exit the selection process without inserting a citation into the -buffer. - -@tablesubheading{Updating the buffer} - -@item g -Start over with a new regular expression. The full database will be -rescanned with the new expression (see also @kbd{r}). - -@c FIXME: Should we use something else here? r is usually rescan! -@item r -Refine the current selection with another regular expression. This will -@emph{not} rescan the entire database, but just the already selected -entries. - -@end table - -@vindex reftex-select-bib-map -In order to define additional commands for this selection process, the -keymap @code{reftex-select-bib-map} may be used. - -Note that if you do not use Emacs to edit the @BibTeX{} database files, -@RefTeX{} will ask if the related buffers should be updated once it -detects that the files were changed externally. If you do not want to -be bothered by such queries, you can activate Auto Revert mode for these -buffers by adding the following expression to your init file: - -@lisp -(add-hook 'bibtex-mode-hook 'turn-on-auto-revert-mode) -@end lisp - - -@node Citation Styles -@section Citation Styles -@cindex Citation styles -@cindex Citation styles, @code{natbib} -@cindex Citation styles, @code{harvard} -@cindex Citation styles, @code{chicago} -@cindex Citation styles, @code{jurabib} -@cindex Citation styles, @ConTeXt{} -@cindex @code{natbib}, citation style -@cindex @code{harvard}, citation style -@cindex @code{chicago}, citation style -@cindex @code{jurabib}, citation style -@cindex @ConTeXt{}, citation style - -@vindex reftex-cite-format -The standard @LaTeX{} macro @code{\cite} works well with numeric or -simple key citations. To deal with the more complex task of author-year -citations as used in many natural sciences, a variety of packages has -been developed which define derived forms of the @code{\cite} macro. -@RefTeX{} can be configured to produce these citation macros as well by -setting the variable @code{reftex-cite-format}. For the most commonly -used @LaTeX{} packages (@code{natbib}, @code{harvard}, @code{chicago}, -@code{jurabib}) and for @ConTeXt{} this may be done from the menu, under -@code{Ref->Citation Styles}. Since there are usually several macros to -create the citations, executing @code{reftex-citation} (@kbd{C-c [}) -starts by prompting for the correct macro. For the Natbib style, this -looks like this: - -@example -SELECT A CITATION FORMAT - -[^M] \cite@{%l@} -[t] \citet@{%l@} -[T] \citet*@{%l@} -[p] \citep@{%l@} -[P] \citep*@{%l@} -[e] \citep[e.g.][]@{%l@} -[s] \citep[see][]@{%l@} -[a] \citeauthor@{%l@} -[A] \citeauthor*@{%l@} -[y] \citeyear@{%l@} -@end example - -@vindex reftex-cite-prompt-optional-args -If citation formats contain empty pairs of square brackets, @RefTeX{} -will prompt for values of these optional arguments if you call the -@code{reftex-citation} command with a @kbd{C-u} prefix. -Following the most generic of these packages, @code{natbib}, the builtin -citation packages always accept the @kbd{t} key for a @emph{textual} -citation (like: @code{Jones et al. (1997) have shown...}) as well as -the @kbd{p} key for a parenthetical citation (like: @code{As shown -earlier (Jones et al, 1997)}). - -To make one of these styles the default, customize the variable -@code{reftex-cite-format} or put into @file{.emacs}: - -@lisp -(setq reftex-cite-format 'natbib) -@end lisp - -You can also use @AUCTeX{} style files to automatically set the -citation style based on the @code{usepackage} commands in a given -document. @xref{Style Files}, for information on how to set up the style -files correctly. - -@node Citation Info -@section Citation Info -@cindex Displaying citations -@cindex Citations, displaying -@cindex Citation info -@cindex Viewing citations -@kindex C-c & -@kindex S-mouse-2 -@findex reftex-view-crossref -@findex reftex-mouse-view-crossref - -When point is idle for more than @code{reftex-idle-time} seconds on the -argument of a @code{\cite} macro, the echo area will display some -information about the article cited there. Note that the information is -only displayed if the echo area is not occupied by a different message. - -@RefTeX{} can also display the @code{\bibitem} or @BibTeX{} database -entry corresponding to a @code{\cite} macro, or all citation locations -corresponding to a @code{\bibitem} or @BibTeX{} database entry. -@xref{Viewing Cross-References}. - -@node Chapterbib and Bibunits -@section Chapterbib and Bibunits -@cindex @code{chapterbib}, LaTeX package -@cindex @code{bibunits}, LaTeX package -@cindex Bibliographies, multiple - -@code{chapterbib} and @code{bibunits} are two @LaTeX{} packages which -produce multiple bibliographies in a document. This is no problem for -@RefTeX{} as long as all bibliographies use the same @BibTeX{} database -files. If they do not, it is best to have each document part in a -separate file (as it is required for @code{chapterbib} anyway). Then -@RefTeX{} will still scan the locally relevant databases correctly. If -you have multiple bibliographies within a @emph{single file}, this may -or may not be the case. - -@node Citations Outside LaTeX -@section Citations outside @LaTeX{} -@cindex Citations outside LaTeX -@vindex reftex-default-bibliography - -The command @code{reftex-citation} can also be executed outside a @LaTeX{} -buffer. This can be useful to reference articles in the mail buffer and -other documents. You should @emph{not} enter @code{reftex-mode} for -this, just execute the command. The list of @BibTeX{} files will in this -case be taken from the variable @code{reftex-default-bibliography}. -Setting the variable @code{reftex-cite-format} to the symbol -@code{locally} does a decent job of putting all relevant information -about a citation directly into the buffer. Here is the lisp code to add -the @kbd{C-c [} binding to the mail buffer. It also provides a local -binding for @code{reftex-cite-format}. - -@lisp -(add-hook 'mail-setup-hook - (lambda () (define-key mail-mode-map "\C-c[" - (lambda () - (interactive) - (let ((reftex-cite-format 'locally)) - (reftex-citation)))))) -@end lisp - -@node BibTeX Database Subsets -@section Database Subsets -@cindex BibTeX database subsets -@findex reftex-create-bibtex-file - -@RefTeX{} offers two ways to create a new @BibTeX{} database file. - -The first option produces a file which contains only the entries -actually referenced in the current document. This can be useful if -the database is only meant for a single document and you want to clean -it of old and unused ballast. It can also be useful while writing a -document together with collaborators, in order to avoid sending around -the entire (possibly very large) database. To create the file, use -@kbd{M-x reftex-create-bibtex-file}, also available from the menu -under @code{Ref->Global Actions->Create Bibtex File}. The command will -prompt for a @BibTeX{} file name and write the extracted entries to that -file. - -The second option makes use of the selection process started by the -command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a -regular expression to select entries, and lists them in a formatted -selection buffer. After pressing the @kbd{e} key (mnemonics: Export), -the command will prompt for the name of a new @BibTeX{} file and write -the selected entries to that file. You can also first mark some -entries in the selection buffer with the @kbd{m} key and then export -either the @i{marked} entries (with the @kbd{e} key) or the -@i{unmarked} entries (with the @kbd{E} key). - -@node Index Support -@chapter Index Support -@cindex Index Support -@cindex @code{\index} - -@LaTeX{} has builtin support for creating an Index. The @LaTeX{} core -supports two different indices, the standard index and a glossary. With -the help of special @LaTeX{} packages (@file{multind.sty} or -@file{index.sty}), any number of indices can be supported. - -Index entries are created with the @code{\index@{@var{entry}@}} macro. -All entries defined in a document are written out to the @file{.aux} -file. A separate tool must be used to convert this information into a -nicely formatted index. Tools used with @LaTeX{} include @code{MakeIndex} -and @code{xindy}. - -Indexing is a very difficult task. It must follow strict conventions to -make the index consistent and complete. There are basically two -approaches one can follow, and both have their merits. - -@enumerate -@item -Part of the indexing should already be done with the markup. The -document structure should be reflected in the index, so when starting -new sections, the basic topics of the section should be indexed. If the -document contains definitions, theorems or the like, these should all -correspond to appropriate index entries. This part of the index can -very well be developed along with the document. Often it is worthwhile -to define special purpose macros which define an item and at the same -time make an index entry, possibly with special formatting to make the -reference page in the index bold or underlined. To make @RefTeX{} -support for indexing possible, these special macros must be added to -@RefTeX{}'s configuration (@pxref{Defining Index Macros}). - -@item -The rest of the index is often just a collection of where in the -document certain words or phrases are being used. This part is -difficult to develop along with the document, because consistent entries -for each occurrence are needed and are best selected when the document -is ready. @RefTeX{} supports this with an @emph{index phrases file} -which collects phrases and helps indexing the phrases globally. -@end enumerate - -Before you start, you need to make sure that @RefTeX{} knows about -the index style being used in the current document. @RefTeX{} has -builtin support for the default @code{\index} and @code{\glossary} -macros. Other @LaTeX{} packages, like the @file{multind} or @file{index} -package, redefine the @code{\index} macro to have an additional -argument, and @RefTeX{} needs to be configured for those. A -sufficiently new version of @AUCTeX{} (9.10c or later) will do this -automatically. If you really don't use @AUCTeX{} (you should!), this -configuration needs to be done by hand with the menu (@code{Ref->Index -Style}), or globally for all your documents with - -@lisp -(setq reftex-index-macros '(multind)) @r{or} -(setq reftex-index-macros '(index)) -@end lisp - -@menu -* Creating Index Entries:: Macros and completion of entries. -* The Index Phrases File:: A special file for global indexing. -* Displaying and Editing the Index:: The index editor. -* Builtin Index Macros:: The index macros RefTeX knows about. -* Defining Index Macros:: ... and macros it doesn't. -@end menu - -@node Creating Index Entries -@section Creating Index Entries -@cindex Creating index entries -@cindex Index entries, creating -@kindex C-c < -@findex reftex-index -@kindex C-c / -@findex reftex-index-selection-or-word - -In order to index the current selection or the word at the cursor press -@kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the -selection or word @samp{@var{word}} to be replaced with -@samp{\index@{@var{word}@}@var{word}}. The macro which is used -(@code{\index} by default) can be configured with the variable -@code{reftex-index-default-macro}. When the command is called with a -prefix argument (@kbd{C-u C-c /}), you get a chance to edit the -generated index entry. Use this to change the case of the word or to -make the entry a subentry, for example by entering -@samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes -(@kbd{C-u C-u C-c /}), you will be asked for the index macro as well. -When there is nothing selected and no word at point, this command will -just call @code{reftex-index}, described below. - -In order to create a general index entry, press @kbd{C-c <} -(@code{reftex-index}). @RefTeX{} will prompt for one of the -available index macros and for its arguments. Completion will be -available for the index entry and, if applicable, the index tag. The -index tag is a string identifying one of multiple indices. With the -@file{multind} and @file{index} packages, this tag is the first argument -to the redefined @code{\index} macro. - -@node The Index Phrases File -@section The Index Phrases File -@cindex Index phrase file -@cindex Phrase file -@kindex C-c | -@findex reftex-index-visit-phrases-buffer -@cindex Macro definition lines, in phrase buffer - -@RefTeX{} maintains a file in which phrases can be collected for -later indexing. The file is located in the same directory as the master -file of the document and has the extension @file{.rip} (@b{R}eftex -@b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c -|} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it -is initialized by inserting a file header which contains the definition -of the available index macros. This list is initialized from -@code{reftex-index-macros} (@pxref{Defining Index Macros}). You can -edit the header as needed, but if you define new @LaTeX{} indexing macros, -don't forget to add them to @code{reftex-index-macros} as well. Here is -a phrase file header example: - -@example -% -*- mode: reftex-index-phrases -*- -% Key Macro Format Repeat -%---------------------------------------------------------- ->>>INDEX_MACRO_DEFINITION: i \index@{%s@} t ->>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil ->>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t ->>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil -%---------------------------------------------------------- -@end example - -The macro definition lines consist of a unique letter identifying a -macro, a format string and the @var{repeat} flag, all separated by -@key{TAB}. The format string shows how the macro is to be applied, the -@samp{%s} will be replaced with the index entry. The repeat flag -indicates if @var{word} is indexed by the macro as -@samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as -@samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the -above example it is assumed that the macro @code{\index*@{@var{word}@}} -already typesets its argument in the text, so that it is unnecessary to -repeat @var{word} outside the macro. - -@menu -* Collecting Phrases:: Collecting from document or external. -* Consistency Checks:: Check for duplicates etc. -* Global Indexing:: The interactive indexing process. -@end menu - -@node Collecting Phrases -@subsection Collecting Phrases -@cindex Collecting index phrases -@cindex Index phrases, collection -@cindex Phrases, collecting - -Phrases for indexing can be collected while writing the document. The -command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) -copies the current selection (if active) or the word near point into the -phrases buffer. It then selects this buffer, so that the phrase line -can be edited. To return to the @LaTeX{} document, press @kbd{C-c C-c} -(@code{reftex-index-phrases-save-and-return}). - -You can also prepare the list of index phrases in a different way and -copy it into the phrases file. For example you might want to start from -a word list of the document and remove all words which should not be -indexed. - -The phrase lines in the phrase buffer must have a specific format. -@RefTeX{} will use font-lock to indicate if a line has the proper -format. A phrase line looks like this: - -@example -[@var{key}] @var{phrase} [ @var{arg}[&&@var{arg}]... [ || @var{arg}]...] -@end example - -@code{} stands for white space containing at least one @key{TAB}. -@var{key} must be at the start of the line and is the character -identifying one of the macros defined in the file header. It is -optional; when omitted, the first macro definition line in the file -will be used for this phrase. The @var{phrase} is the phrase to be -searched for when indexing. It may contain several words separated by -spaces. By default the search phrase is also the text entered as -argument of the index macro. If you want the index entry to be -different from the search phrase, enter another @key{TAB} and the index -argument @var{arg}. If you want to have each match produce several -index entries, separate the different index arguments with @samp{ && -}@footnote{@samp{&&} with optional spaces, see -@code{reftex-index-phrases-logical-and-regexp}.}. If you want to be -able to choose at each match between several different index arguments, -separate them with @samp{ || }@footnote{@samp{||} with optional spaces, -see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an -example: - -@example -%-------------------------------------------------------------------- -I Sun -i Planet Planets -i Vega Stars!Vega - Jupiter Planets!Jupiter -i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars -i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto -@end example - - -So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while -@samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}. -@samp{Vega} will be indexed as a subitem of @samp{Stars}. The -@samp{Jupiter} line will also use the @samp{i} macro as it was the first -macro definition in the file header (see above example). At each -occurrence of @samp{Mars} you will be able choose between indexing it as -a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}. -Finally, every occurrence of @samp{Pluto} will be indexed as -@samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto} -and will therefore create two different index entries. - -@node Consistency Checks -@subsection Consistency Checks -@cindex Index phrases, consistency checks -@cindex Phrases, consistency checks -@cindex Consistency check for index phrases - -@kindex C-c C-s -Before indexing the phrases in the phrases buffer, they should be -checked carefully for consistency. A first step is to sort the phrases -alphabetically; this is done with the command @kbd{C-c C-s} -(@code{reftex-index-sort-phrases}). It will sort all phrases in the -buffer alphabetically by search phrase. If you want to group certain -phrases and only sort within the groups, insert empty lines between the -groups. Sorting will only change the sequence of phrases within each -group (see the variable @code{reftex-index-phrases-sort-in-blocks}). - -@kindex C-c C-i -A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info}) -which lists information about the phrase at point, including an example -of how the index entry will look like and the number of expected matches -in the document. - -@kindex C-c C-t -Another important check is to find out if there are double or -overlapping entries in the buffer. For example if you are first -searching and indexing @samp{Mars} and then @samp{Planet Mars}, the -second phrase will not match because of the index macro inserted before -@samp{Mars} earlier. The command @kbd{C-c C-t} -(@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in -the buffer which is either duplicate or a subphrase of another phrase. -In order to check the whole buffer like this, start at the beginning and -execute this command repeatedly. - -@node Global Indexing -@subsection Global Indexing -@cindex Global indexing -@cindex Indexing, global -@cindex Indexing, from @file{phrases} buffer - -Once the index phrases have been collected and organized, you are set -for global indexing. I recommend to do this only on an otherwise -finished document. Global indexing starts from the phrases buffer. -There are several commands which start indexing: @kbd{C-c C-x} acts on -the current phrase line, @kbd{C-c C-r} on all lines in the current -region and @kbd{C-c C-a} on all phrase lines in the buffer. It is -probably good to do indexing in small chunks since your concentration -may not last long enough to do everything in one go. - -@RefTeX{} will start at the first phrase line and search the phrase -globally in the whole document. At each match it will stop, compute the -replacement string and offer you the following choices@footnote{Windows -users: Restrict yourself to the described keys during indexing. Pressing -@key{Help} at the indexing prompt can apparently hang Emacs.}: - -@table @kbd -@item y -Replace this match with the proposed string. -@item n -Skip this match. -@item ! -Replace this and all further matches in this file. -@item q -Skip this match, start with next file. -@item Q -Skip this match, start with next phrase. -@item o -Select a different indexing macro for this match. -@item 1-9 -Select one of multiple index keys (those separated with @samp{||}). -@item e -Edit the replacement text. -@item C-r -Recursive edit. Use @kbd{C-M-c} to return to the indexing process. -@item s -Save this buffer and ask again about the current match. -@item S -Save all document buffers and ask again about the current match. -@item C-g -Abort the indexing process. -@end table - -The @samp{Find and Index in Document} menu in the phrases buffer also -lists a few options for the indexing process. The options have -associated customization variables to set the defaults -(@pxref{Options - Index Support}). Here is a short explanation of -what the options do: - -@table @i -@item Match Whole Words -When searching for index phrases, make sure whole words are matched. -This should probably always be on. -@item Case Sensitive Search -Search case sensitively for phrases. I recommend to have this setting -off, in order to match the capitalized words at the beginning of a -sentence, and even typos. You can always say @emph{no} at a match you -do not like. -@item Wrap Long Lines -Inserting index macros increases the line length. Turn this option on -to allow @RefTeX{} to wrap long lines. -@item Skip Indexed Matches -When this is on, @RefTeX{} will at each match try to figure out if -this match is already indexed. A match is considered indexed if it is -either the argument of an index macro, or if an index macro is directly -(without whitespace separation) before or after the match. Index macros -are those configured in @code{reftex-index-macros}. Intended for -re-indexing a documents after changes have been made. -@end table - -Even though indexing should be the last thing you do to a document, you -are bound to make changes afterwards. Indexing then has to be applied -to the changed regions. The command -@code{reftex-index-phrases-apply-to-region} is designed for this -purpose. When called from a @LaTeX{} document with active region, it will -apply @code{reftex-index-all-phrases} to the current region. - -@node Displaying and Editing the Index -@section Displaying and Editing the Index -@cindex Displaying the Index -@cindex Editing the Index -@cindex Index entries, creating -@cindex Index, displaying -@cindex Index, editing -@kindex C-c > -@findex reftex-display-index - -In order to compile and display the index, press @kbd{C-c >}. If the -document uses multiple indices, @RefTeX{} will ask you to select -one. Then, all index entries will be sorted alphabetically and -displayed in a special buffer, the @file{*Index*} buffer. From that -buffer you can check and edit each entry. - -The index can be restricted to the current section or the region. Then -only entries in that part of the document will go into the compiled -index. To restrict to the current section, use a numeric prefix -@samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current -region, make the region active and use a numeric prefix @samp{3} (press -@kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the -restriction can be moved from one section to the next by pressing the -@kbd{<} and @kbd{>} keys. - -One caveat: @RefTeX{} finds the definition point of an index entry -by searching near the buffer position where it had found to macro during -scanning. If you have several identical index entries in the same -buffer and significant changes have shifted the entries around, you must -rescan the buffer to ensure the correspondence between the -@file{*Index*} buffer and the definition locations. It is therefore -advisable to rescan the document (with @kbd{r} or @kbd{C-u r}) -frequently while editing the index from the @file{*Index*} -buffer. - -@kindex ? -Here is a list of special commands available in the @file{*Index*} buffer. A -summary of this information is always available by pressing -@kbd{?}. - -@table @kbd -@tablesubheading{General} -@item ? -Display a summary of commands. - -@item 0-9, - -Prefix argument. - -@tablesubheading{Moving around} -@item ! A..Z -Pressing any capital letter will jump to the corresponding section in -the @file{*Index*} buffer. The exclamation mark is special and jumps to -the first entries alphabetically sorted below @samp{A}. These are -usually non-alphanumeric characters. -@item n -Go to next entry. -@item p -Go to previous entry. - -@tablesubheading{Access to document locations} -@item @key{SPC} -Show the place in the document where this index entry is defined. - -@item @key{TAB} -Go to the definition of the current index entry in another -window. - -@item @key{RET} -Go to the definition of the current index entry and hide the -@file{*Index*} buffer window. - -@item f -@vindex reftex-index-follow-mode -@vindex reftex-revisit-to-follow -Toggle follow mode. When follow mode is active, the other window will -always show the location corresponding to the line in the @file{*Index*} -buffer at point. This is similar to pressing @key{SPC} after each -cursor motion. The default for this flag can be set with the variable -@code{reftex-index-follow-mode}. Note that only context in files -already visited is shown. @RefTeX{} will not visit a file just for -follow mode. See, however, the variable -@code{reftex-revisit-to-follow}. - -@tablesubheading{Entry editing} -@item e -Edit the current index entry. In the minibuffer, you can edit the -index macro which defines this entry. - -@item C-k -Kill the index entry. Currently not implemented because I don't know -how to implement an @code{undo} function for this. - -@item * -Edit the @var{key} part of the entry. This is the initial part of the -entry which determines the location of the entry in the index. - -@item | -Edit the @var{attribute} part of the entry. This is the part after the -vertical bar. With @code{MakeIndex}, this part is an encapsulating -macro. With @code{xindy}, it is called @emph{attribute} and is a -property of the index entry that can lead to special formatting. When -called with @kbd{C-u} prefix, kill the entire @var{attribute} -part. - -@item @@ -Edit the @var{visual} part of the entry. This is the part after the -@samp{@@} which is used by @code{MakeIndex} to change the visual -appearance of the entry in the index. When called with @kbd{C-u} -prefix, kill the entire @var{visual} part. - -@item ( -Toggle the beginning of page range property @samp{|(} of the -entry. - -@item ) -Toggle the end of page range property @samp{|)} of the entry. - -@item _ -Make the current entry a subentry. This command will prompt for the -superordinate entry and insert it. - -@item ^ -Remove the highest superordinate entry. If the current entry is a -subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy -(@samp{bbb!ccc}). - -@tablesubheading{Exiting} -@item q -Hide the @file{*Index*} buffer. - -@item k -Kill the @file{*Index*} buffer. - -@item C-c = -Switch to the Table of Contents buffer of this document. - -@tablesubheading{Controlling what gets displayed} -@item c -@vindex reftex-index-include-context -Toggle the display of short context in the @file{*Index*} buffer. The -default for this flag can be set with the variable -@code{reftex-index-include-context}. - -@item @} -Restrict the index to a single document section. The corresponding -section number will be displayed in the @code{R<>} indicator in the -mode line and in the header of the @file{*Index*} buffer. - -@item @{ -Widen the index to contain all entries of the document. - -@item < -When the index is currently restricted, move the restriction to the -previous section. - -@item > -When the index is currently restricted, move the restriction to the -next section. - -@tablesubheading{Updating the buffer} -@item g -Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the -document. However, it sorts the entries again, so that edited entries -will move to the correct position. - -@item r -@vindex reftex-enable-partial-scans -Reparse the @LaTeX{} document and rebuild the @file{*Index*} buffer. When -@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this -location is defined in, not the entire document. - -@item C-u r -Reparse the @emph{entire} @LaTeX{} document and rebuild the @file{*Index*} -buffer. - -@item s -Switch to a different index (for documents with multiple -indices). -@end table - - -@node Builtin Index Macros -@section Builtin Index Macros -@cindex Builtin index macros -@cindex Index macros, builtin -@vindex reftex-index-macros -@cindex @code{multind}, LaTeX package -@cindex @code{index}, LaTeX package -@cindex LaTeX packages, @code{multind} -@cindex LaTeX packages, @code{index} - -@RefTeX{} by default recognizes the @code{\index} and -@code{\glossary} macros which are defined in the @LaTeX{} core. It has -also builtin support for the re-implementations of @code{\index} -in the @file{multind} and @file{index} packages. However, since -the different definitions of the @code{\index} macro are incompatible, -you will have to explicitly specify the index style used. -@xref{Creating Index Entries}, for information on how to do that. - -@node Defining Index Macros -@section Defining Index Macros -@cindex Defining Index Macros -@cindex Index macros, defining -@vindex reftex-index-macros - -When writing a document with an index you will probably define -additional macros which make entries into the index. -Let's look at an example. - -@example -\newcommand@{\ix@}[1]@{#1\index@{#1@}@} -\newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@} -\newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@} -@end example - -The first macro @code{\ix} typesets its argument in the text and places -it into the index. The second macro @code{\nindex} typesets its -argument in the text and places it into a separate index with the tag -@samp{name}@footnote{We are using the syntax of the @file{index} package -here.}. The last macro also places its argument into the index, but as -subitems under the main index entry @samp{Astronomical Objects}. Here -is how to make @RefTeX{} recognize and correctly interpret these -macros, first with Emacs Lisp. - -@lisp -(setq reftex-index-macros - '(("\\ix@{*@}" "idx" ?x "" nil nil) - ("\\nindex@{*@}" "name" ?n "" nil nil) - ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t))) -@end lisp - -Note that the index tag is @samp{idx} for the main index, and -@samp{name} for the name index. @samp{idx} and @samp{glo} are reserved -for the default index and for the glossary. - -The character arguments @code{?x}, @code{?n}, and @code{?o} are for -quick identification of these macros when @RefTeX{} inserts new -index entries with @code{reftex-index}. These codes need to be -unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the -@code{\index}, @code{\index*}, and @code{\glossary} macros, -respectively. - -The following string is empty unless your macro adds a superordinate -entry to the index key; this is the case for the @code{\astobj} macro. - -The next entry can be a hook function to exclude certain matches, it -almost always can be @code{nil}. - -The final element in the list indicates if the text being indexed needs -to be repeated outside the macro. For the normal index macros, this -should be @code{t}. Only if the macro typesets the entry in the text -(like @code{\ix} and @code{\nindex} in the example do), this should be -@code{nil}. - -To do the same thing with customize, you need to fill in the templates -like this: - -@example -Repeat: -[INS] [DEL] List: - Macro with args: \ix@{*@} - Index Tag : [Value Menu] String: idx - Access Key : x - Key Prefix : - Exclusion hook : nil - Repeat Outside : [Toggle] off (nil) -[INS] [DEL] List: - Macro with args: \nindex@{*@} - Index Tag : [Value Menu] String: name - Access Key : n - Key Prefix : - Exclusion hook : nil - Repeat Outside : [Toggle] off (nil) -[INS] [DEL] List: - Macro with args: \astobj@{*@} - Index Tag : [Value Menu] String: idx - Access Key : o - Key Prefix : Astronomical Objects! - Exclusion hook : nil - Repeat Outside : [Toggle] on (non-nil) -[INS] -@end example - -With the macro @code{\ix} defined, you may want to change the default -macro used for indexing a text phrase (@pxref{Creating Index Entries}). -This would be done like this - -@lisp -(setq reftex-index-default-macro '(?x "idx")) -@end lisp - -which specifies that the macro identified with the character @code{?x} (the -@code{\ix} macro) should be used for indexing phrases and words already -in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}). -The index tag is "idx". - -@node Viewing Cross-References -@chapter Viewing Cross-References -@findex reftex-view-crossref -@findex reftex-mouse-view-crossref -@kindex C-c & -@kindex S-mouse-2 - -@RefTeX{} can display cross-referencing information. This means, -if two document locations are linked, @RefTeX{} can display the -matching location(s) in another window. The @code{\label} and @code{\ref} -macros are one way of establishing such a link. Also, a @code{\cite} -macro is linked to the corresponding @code{\bibitem} macro or a @BibTeX{} -database entry. - -The feature is invoked by pressing @kbd{C-c &} -(@code{reftex-view-crossref}) while point is on the @var{key} argument -of a macro involved in cross-referencing. You can also click with -@kbd{S-mouse-2} on the macro argument. Here is what will happen for -individual classes of macros: - -@table @asis - -@item @code{\ref} -@cindex @code{\ref} -Display the corresponding label definition. All usual -variants@footnote{all macros that start with @samp{ref} or end with -@samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for -cross-reference display. This works also for labels defined in an -external document when the current document refers to them through the -@code{xr} interface (@pxref{LaTeX xr Package}). - -@item @code{\label} -@cindex @code{\label} -@vindex reftex-label-alist -Display a document location which references this label. Pressing -@kbd{C-c &} several times moves through the entire document and finds -all locations. Not only the @code{\label} macro but also other macros -with label arguments (as configured with @code{reftex-label-alist}) are -active for cross-reference display. - -@item @code{\cite} -@cindex @code{\cite} -Display the corresponding @BibTeX{} database entry or @code{\bibitem}. -All usual variants@footnote{all macros that either start or end with -@samp{cite}} of the @code{\cite} macro are active for cross-reference -display. - -@item @code{\bibitem} -@cindex @code{\bibitem} -Display a document location which cites this article. Pressing -@kbd{C-c &} several times moves through the entire document and finds -all locations. - -@item @BibTeX{} -@cindex BibTeX buffer, viewing cite locations from -@cindex Viewing cite locations from BibTeX buffer -@kbd{C-c &} is also active in @BibTeX{} buffers. All locations in a -document where the database entry at point is cited will be displayed. -On first use, @RefTeX{} will prompt for a buffer which belongs to -the document you want to search. Subsequent calls will use the same -document, until you break this link with a prefix argument to @kbd{C-c -&}. - -@item @code{\index} -@cindex @code{\index} -Display other locations in the document which are marked by an index -macro with the same key argument. Along with the standard @code{\index} -and @code{\glossary} macros, all macros configured in -@code{reftex-index-macros} will be recognized. -@end table - -@vindex reftex-view-crossref-extra -While the display of cross referencing information for the above -mentioned macros is hard-coded, you can configure additional relations -in the variable @code{reftex-view-crossref-extra}. - -@iftex -@chapter All the Rest -@end iftex -@ifnottex -@raisesections -@end ifnottex - -@node RefTeXs Menu -@section @RefTeX{}'s Menu -@cindex RefTeXs Menu -@cindex Menu, in the menu bar - -@RefTeX{} installs a @code{Ref} menu in the menu bar on systems -which support this. From this menu you can access all of -@RefTeX{}'s commands and a few of its options. There is also a -@code{Customize} submenu which can be used to access @RefTeX{}'s -entire set of options. - -@node Key Bindings -@section Default Key Bindings -@cindex Key Bindings, summary - -Here is a summary of the available key bindings. - -@kindex C-c = -@kindex C-c - -@kindex C-c ( -@kindex C-c ) -@kindex C-c [ -@kindex C-c & -@kindex S-mouse-2 -@kindex C-c / -@kindex C-c \ -@kindex C-c | -@kindex C-c < -@kindex C-c > -@example -@kbd{C-c =} @code{reftex-toc} -@kbd{C-c -} @code{reftex-toc-recenter} -@kbd{C-c (} @code{reftex-label} -@kbd{C-c )} @code{reftex-reference} -@kbd{C-c [} @code{reftex-citation} -@kbd{C-c &} @code{reftex-view-crossref} -@kbd{S-mouse-2} @code{reftex-mouse-view-crossref} -@kbd{C-c /} @code{reftex-index-selection-or-word} -@kbd{C-c \} @code{reftex-index-phrase-selection-or-word} -@kbd{C-c |} @code{reftex-index-visit-phrases-buffer} -@kbd{C-c <} @code{reftex-index} -@kbd{C-c >} @code{reftex-display-index} -@end example - -Note that the @kbd{S-mouse-2} binding is only provided if this key is -not already used by some other package. @RefTeX{} will not override an -existing binding to @kbd{S-mouse-2}. - -Personally, I also bind some functions in the users @kbd{C-c} map for -easier access. - -@c FIXME: Do we need bindings for the Index macros here as well? -@c C-c i C-c I or so???? -@c How about key bindings for reftex-reset-mode and reftex-parse-document? -@kindex C-c t -@kindex C-c l -@kindex C-c r -@kindex C-c c -@kindex C-c v -@kindex C-c s -@kindex C-c g -@example -@kbd{C-c t} @code{reftex-toc} -@kbd{C-c l} @code{reftex-label} -@kbd{C-c r} @code{reftex-reference} -@kbd{C-c c} @code{reftex-citation} -@kbd{C-c v} @code{reftex-view-crossref} -@kbd{C-c s} @code{reftex-search-document} -@kbd{C-c g} @code{reftex-grep-document} -@end example - -@noindent These keys are reserved for the user, so I cannot bind them by -default. If you want to have these key bindings available, set in your -@file{.emacs} file: - -@vindex reftex-extra-bindings -@lisp -(setq reftex-extra-bindings t) -@end lisp - -@vindex reftex-load-hook -Changing and adding to @RefTeX{}'s key bindings is best done in the hook -@code{reftex-load-hook}. For information on the keymaps -which should be used to add keys, see @ref{Keymaps and Hooks}. - -@node Faces -@section Faces -@cindex Faces - -@RefTeX{} uses faces when available to structure the selection and -table of contents buffers. It does not create its own faces, but uses -the ones defined in @file{font-lock.el}. Therefore, @RefTeX{} will -use faces only when @code{font-lock} is loaded. This seems to be -reasonable because people who like faces will very likely have it -loaded. If you wish to turn off fontification or change the involved -faces, see @ref{Options - Fontification}. - -@node Multifile Documents -@section Multifile Documents -@cindex Multifile documents -@cindex Documents, spread over files - -The following is relevant when working with documents spread over many -files: - -@itemize @bullet -@item -@RefTeX{} has full support for multifile documents. You can edit parts of -several (multifile) documents at the same time without conflicts. -@RefTeX{} provides functions to run @code{grep}, @code{search} and -@code{query-replace} on all files which are part of a multifile -document. - -@item -@vindex tex-main-file -@vindex TeX-master -All files belonging to a multifile document should define a File -Variable (@code{TeX-master} for @AUCTeX{} or @code{tex-main-file} for the -standard Emacs @LaTeX{} mode) containing the name of the master file. For -example, to set the file variable @code{TeX-master}, include something -like the following at the end of each @TeX{} file: - -@example -%%% Local Variables: *** -%%% mode:latex *** -%%% TeX-master: "thesis.tex" *** -%%% End: *** -@end example - -@AUCTeX{} with the setting - -@lisp -(setq-default TeX-master nil) -@end lisp - -will actually ask you for each new file about the master file and insert -this comment automatically. For more details see the documentation of -the @AUCTeX{} (@pxref{Multifile,,,auctex, The AUCTeX User Manual}), the -documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs, -The GNU Emacs Manual}) and the Emacs documentation on File Variables -(@pxref{File Variables,,,emacs, The GNU Emacs Manual}). - -@item -The context of a label definition must be found in the same file as the -label itself in order to be processed correctly by @RefTeX{}. The only -exception is that section labels referring to a section statement -outside the current file can still use that section title as -context. -@end itemize - -@node Language Support -@section Language Support -@cindex Language support - -Some parts of @RefTeX{} are language dependent. The default -settings work well for English. If you are writing in a different -language, the following hints may be useful: - -@itemize @bullet -@item -@vindex reftex-derive-label-parameters -@vindex reftex-abbrev-parameters -The mechanism to derive a label from context includes the abbreviation -of words and omission of unimportant words. These mechanisms may have -to be changed for other languages. See the variables -@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}. - -@item -@vindex reftex-translate-to-ascii-function -@vindex reftex-label-illegal-re -Also, when a label is derived from context, @RefTeX{} clears the -context string from non-ASCII characters in order to make a valid label. -If there should ever be a version of @TeX{} which allows extended -characters @emph{in labels}, then we will have to look at the -variables @code{reftex-translate-to-ascii-function} and -@code{reftex-label-illegal-re}. - -@item -When a label is referenced, @RefTeX{} looks at the word before point -to guess which label type is required. These @emph{magic words} are -different in every language. For an example of how to add magic words, -see @ref{Adding Magic Words}. - -@vindex reftex-multiref-punctuation -@vindex reftex-cite-punctuation -@item -@RefTeX{} inserts ``punctuation'' for multiple references and -for the author list in citations. Some of this may be language -dependent. See the variables @code{reftex-multiref-punctuation} and -@code{reftex-cite-punctuation}. -@end itemize - -@node Finding Files -@section Finding Files -@cindex Finding files - -In order to find files included in a document via @code{\input} or -@code{\include}, @RefTeX{} searches all directories specified in the -environment variable @code{TEXINPUTS}. Similarly, it will search the -path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for -@BibTeX{} database files. - -When searching, @RefTeX{} will also expand recursive path -definitions (directories ending in @samp{//} or @samp{!!}). But it will -only search and expand directories @emph{explicitly} given in these -variables. This may cause problems under the following circumstances: - -@itemize @bullet -@item -Most @TeX{} system have a default search path for both @TeX{} files and @BibTeX{} -files which is defined in some setup file. Usually this default path is -for system files which @RefTeX{} does not need to see. But if your -document needs @TeX{} files or @BibTeX{} database files in a directory only -given in the default search path, @RefTeX{} will fail to find them. -@item -Some @TeX{} systems do not use environment variables at all in order to -specify the search path. Both default and user search path are then -defined in setup files. -@end itemize - -@noindent -There are three ways to solve this problem: - -@itemize @bullet -@item -Specify all relevant directories explicitly in the environment -variables. If for some reason you don't want to mess with the default -variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own -variables and configure @RefTeX{} to use them instead: - -@lisp -(setq reftex-texpath-environment-variables '("MYTEXINPUTS")) -(setq reftex-bibpath-environment-variables '("MYBIBINPUTS")) -@end lisp - -@item -Specify the full search path directly in @RefTeX{}'s variables. - -@lisp -(setq reftex-texpath-environment-variables - '("./inp:/home/cd/tex//:/usr/local/tex//")) -(setq reftex-bibpath-environment-variables - '("/home/cd/tex/lit/")) -@end lisp - -@item -Some @TeX{} systems provide stand-alone programs to do the file search just -like @TeX{} and @BibTeX{}. E.g., Thomas Esser's @code{teTeX} uses the -@code{kpathsearch} library which provides the command @code{kpsewhich} -to search for files. @RefTeX{} can be configured to use this -program. Note that the exact syntax of the @code{kpsewhich} -command depends upon the version of that program. - -@lisp -(setq reftex-use-external-file-finders t) -(setq reftex-external-file-finders - '(("tex" . "kpsewhich -format=.tex %f") - ("bib" . "kpsewhich -format=.bib %f"))) -@end lisp -@end itemize - -@cindex Noweb files -@vindex reftex-file-extensions -@vindex TeX-file-extensions -Some people like to use RefTeX with noweb files, which usually have the -extension @file{.nw}. In order to deal with such files, the new -extension must be added to the list of valid extensions in the variable -@code{reftex-file-extensions}. When working with @AUCTeX{} as major mode, -the new extension must also be known to @AUCTeX{} via the variable -@code{TeX-file-extension}. For example: - -@lisp -(setq reftex-file-extensions - '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib"))) -(setq TeX-file-extensions - '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo")) -@end lisp - -@node Optimizations -@section Optimizations -@cindex Optimizations - -@b{Note added 2002. Computers have gotten a lot faster, so most of the -optimizations discussed below will not be necessary on new machines. I -am leaving this stuff in the manual for people who want to write thick -books, where some of it still might be useful.} - -Implementing the principle of least surprises, the default settings of -@RefTeX{} ensure a safe ride for beginners and casual users. However, -when using @RefTeX{} for a large project and/or on a small computer, -there are ways to improve speed or memory usage. - -@itemize @bullet -@item -@b{Removing Lookup Buffers}@* -@cindex Removing lookup buffers -@RefTeX{} will load other parts of a multifile document as well as @BibTeX{} -database files for lookup purposes. These buffers are kept, so that -subsequent use of the same files is fast. If you can't afford keeping -these buffers around, and if you can live with a speed penalty, try - -@vindex reftex-keep-temporary-buffers -@lisp -(setq reftex-keep-temporary-buffers nil) -@end lisp - -@item -@b{Partial Document Scans}@* -@cindex Partial documents scans -@cindex Document scanning, partial -A @kbd{C-u} prefix on the major @RefTeX{} commands @code{reftex-label} -(@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}), -@code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c -=}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates -re-parsing of the entire document in order to update the parsing -information. For a large document this can be unnecessary, in -particular if only one file has changed. @RefTeX{} can be configured -to do partial scans instead of full ones. @kbd{C-u} re-parsing then -does apply only to the current buffer and files included from it. -Likewise, the @kbd{r} key in both the label selection buffer and the -table-of-contents buffer will only prompt scanning of the file in which -the label or section macro near the cursor was defined. Re-parsing of -the entire document is still available by using @kbd{C-u C-u} as a -prefix, or the capital @kbd{R} key in the menus. To use this feature, -try - -@vindex reftex-enable-partial-scans -@lisp -(setq reftex-enable-partial-scans t) -@end lisp - -@item -@b{Saving Parser Information}@* -@cindex Saving parser information -@cindex Parse information, saving to a file -@vindex reftex-parse-file-extension -Even with partial scans enabled, @RefTeX{} still has to make one full -scan, when you start working with a document. To avoid this, parsing -information can be stored in a file. The file @file{MASTER.rel} is used -for storing information about a document with master file -@file{MASTER.tex}. It is written automatically when you kill a buffer -in @code{reftex-mode} or when you exit Emacs. The information is -restored when you begin working with a document in a new editing -session. To use this feature, put into @file{.emacs}: - -@vindex reftex-save-parse-info -@lisp -(setq reftex-save-parse-info t) -@end lisp - -@item -@b{Identifying label types by prefix}@* -@cindex Parse information, saving to a file -@vindex reftex-trust-label-prefix -@RefTeX{} normally parses around each label to check in which -environment this label is located, in order to assign a label type to -the label. If your document contains thousands of labels, document -parsing will take considerable time. If you have been using label prefixes -like tab: and fn: consistently, you can tell @RefTeX{} to get the -label type directly from the prefix, without additional parsing. This -will be faster and also allow labels to end up in the correct category -if for some reason it is not possible to derive the correct type from -context. For example, to enable this feature for footnote and -equation labels, use - -@lisp -(setq reftex-trust-label-prefix '("fn:" "eq:")) -@end lisp - -@item -@b{Automatic Document Scans}@* -@cindex Automatic document scans -@cindex Document scanning, automatic -At rare occasions, @RefTeX{} will automatically rescan a part of the -document. If this gets into your way, it can be turned off with - -@vindex reftex-allow-automatic-rescan -@lisp -(setq reftex-allow-automatic-rescan nil) -@end lisp - -@RefTeX{} will then occasionally annotate new labels in the selection -buffer, saying that their position in the label list in uncertain. A -manual document scan will fix this. - -@item -@b{Multiple Selection Buffers}@* -@cindex Multiple selection buffers -@cindex Selection buffers, multiple -Normally, the selection buffer @file{*RefTeX Select*} is re-created for -every selection process. In documents with very many labels this can -take several seconds. @RefTeX{} provides an option to create a -separate selection buffer for each label type and to keep this buffer -from one selection to the next. These buffers are updated automatically -only when a new label has been added in the buffers category with -@code{reftex-label}. Updating the buffer takes as long as recreating it -- so the time saving is limited to cases where no new labels of that -category have been added. To turn on this feature, use - -@vindex reftex-use-multiple-selection-buffers -@lisp -(setq reftex-use-multiple-selection-buffers t) -@end lisp - -@noindent -@cindex Selection buffers, updating -You can also inhibit the automatic updating entirely. Then the -selection buffer will always pop up very fast, but may not contain the -most recently defined labels. You can always update the buffer by hand, -with the @kbd{g} key. To get this behavior, use instead - -@vindex reftex-auto-update-selection-buffers -@lisp -(setq reftex-use-multiple-selection-buffers t - reftex-auto-update-selection-buffers nil) -@end lisp -@end itemize - -@need 2000 -@noindent -@b{As a summary}, here are the settings I recommend for heavy use of -@RefTeX{} with large documents: - -@lisp -@group -(setq reftex-enable-partial-scans t - reftex-save-parse-info t - reftex-use-multiple-selection-buffers t) -@end group -@end lisp - -@node AUCTeX -@section @AUCTeX{} -@cindex @code{AUCTeX}, Emacs package -@cindex Emacs packages, @code{AUCTeX} - -@AUCTeX{} is without doubt the best major mode for editing @TeX{} and @LaTeX{} -files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}). -If @AUCTeX{} is not part of your Emacs distribution, you can get -it@footnote{XEmacs 21.x users may want to install the corresponding -XEmacs package.} by FTP from the @value{AUCTEXSITE}. - -@menu -* AUCTeX-RefTeX Interface:: How both packages work together -* Style Files:: @AUCTeX{}'s style files can support RefTeX -* Bib-Cite:: Hypertext reading of a document -@end menu - -@node AUCTeX-RefTeX Interface -@subsection The @AUCTeX{}-@RefTeX{} Interface - -@RefTeX{} contains code to interface with @AUCTeX{}. When this -interface is turned on, both packages will interact closely. Instead of -using @RefTeX{}'s commands directly, you can then also use them -indirectly as part of the @AUCTeX{} -environment@footnote{@RefTeX{} 4.0 and @AUCTeX{} 9.10c will be -needed for all of this to work. Parts of it work also with earlier -versions.}. The interface is turned on with - -@lisp -(setq reftex-plug-into-AUCTeX t) -@end lisp - -If you need finer control about which parts of the interface are used -and which not, read the docstring of the variable -@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x -customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}. - -The following list describes the individual parts of the interface. - -@itemize @bullet -@item -@findex reftex-label -@vindex LaTeX-label-function, @r{AUCTeX} -@kindex C-c C-e -@kindex C-c C-s -@findex LaTeX-section, @r{AUCTeX} -@findex TeX-insert-macro, @r{AUCTeX} -@b{@AUCTeX{} calls @code{reftex-label} to insert labels}@* -When a new section is created with @kbd{C-c C-s}, or a new environment -is inserted with @kbd{C-c C-e}, @AUCTeX{} normally prompts for a label to -go with it. With the interface, @code{reftex-label} is called instead. -For example, if you type @kbd{C-c C-e equation @key{RET}}, @AUCTeX{} and -@RefTeX{} will insert - -@example -\begin@{equation@} -\label@{eq:1@} - -\end@{equation@} -@end example - -@noindent -without further prompts. - -Similarly, when you type @kbd{C-c C-s section @key{RET}}, @RefTeX{} -will offer its default label which is derived from the section title. - -@item -@b{@AUCTeX{} tells @RefTeX{} about new sections}@* -When creating a new section with @kbd{C-c C-s}, @RefTeX{} will not -have to rescan the buffer in order to see it. - -@item -@findex reftex-arg-label -@findex TeX-arg-label, @r{AUCTeX function} -@findex reftex-arg-ref -@findex TeX-arg-ref, @r{AUCTeX function} -@findex reftex-arg-cite -@findex TeX-arg-cite, @r{AUCTeX function} -@findex reftex-arg-index -@findex TeX-arg-index, @r{AUCTeX function} -@findex TeX-insert-macro, @r{AUCTeX function} -@kindex C-c @key{RET} -@b{@RefTeX{} supplies macro arguments}@* When you insert a macro -interactively with @kbd{C-c @key{RET}}, @AUCTeX{} normally prompts for -macro arguments. Internally, it uses the functions -@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to -prompt for arguments which are labels, citation keys and index entries. -The interface takes over these functions@footnote{@code{fset} is used to -do this, which is not reversible. However, @RefTeX{} implements the -old functionality when you later decide to turn off the interface.} and -supplies the macro arguments with @b{@RefTeX{}'s} mechanisms. For -example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @RefTeX{} -will supply its label selection process (@pxref{Referencing -Labels}). - -@item -@b{@RefTeX{} tells @AUCTeX{} about new labels, citation and index keys}@* -@RefTeX{} will add all newly created labels to @AUCTeX{}'s completion list. -@end itemize - -@node Style Files -@subsection Style Files -@cindex Style files, AUCTeX -@findex TeX-add-style-hook, @r{AUCTeX} -Style files are Emacs Lisp files which are evaluated by @AUCTeX{} in -association with the @code{\documentclass} and @code{\usepackage} -commands of a document (@pxref{Style Files,,,auctex}). Support for -@RefTeX{} in such a style file is useful when the @LaTeX{} style -defines macros or environments connected with labels, citations, or the -index. Many style files (e.g., @file{amsmath.el} or @file{natbib.el}) -distributed with @AUCTeX{} already support @RefTeX{} in this -way. - -Before calling a @RefTeX{} function, the style hook should always -test for the availability of the function, so that the style file will -also work for people who do not use @RefTeX{}. - -Additions made with style files in the way described below remain local -to the current document. For example, if one package uses AMSTeX, the -style file will make @RefTeX{} switch over to @code{\eqref}, but -this will not affect other documents. - -@findex reftex-add-label-environments -@findex reftex-add-to-label-alist -A style hook may contain calls to -@code{reftex-add-label-environments}@footnote{This used to be the -function @code{reftex-add-to-label-alist} which is still available as an -alias for compatibility.} which defines additions to -@code{reftex-label-alist}. The argument taken by this function must have -the same format as @code{reftex-label-alist}. The @file{amsmath.el} -style file of @AUCTeX{} for example contains the following: - -@lisp -@group -(TeX-add-style-hook "amsmath" - (lambda () - (if (fboundp 'reftex-add-label-environments) - (reftex-add-label-environments '(AMSTeX))))) -@end group -@end lisp - -@noindent -@findex LaTeX-add-environments, @r{AUCTeX} -while a package @code{myprop} defining a @code{proposition} environment -with @code{\newtheorem} might use - -@lisp -@group -(TeX-add-style-hook "myprop" - (lambda () - (LaTeX-add-environments '("proposition" LaTeX-env-label)) - (if (fboundp 'reftex-add-label-environments) - (reftex-add-label-environments - '(("proposition" ?p "prop:" "~\\ref@{%s@}" t - ("Proposition" "Prop.") -3)))))) -@end group -@end lisp - -@findex reftex-set-cite-format -Similarly, a style hook may contain a call to -@code{reftex-set-cite-format} to set the citation format. The style -file @file{natbib.el} for the Natbib citation style does switch -@RefTeX{}'s citation format like this: - -@lisp -(TeX-add-style-hook "natbib" - (lambda () - (if (fboundp 'reftex-set-cite-format) - (reftex-set-cite-format 'natbib)))) -@end lisp - -@findex reftex-add-index-macros -The hook may contain a call to @code{reftex-add-index-macros} to -define additional @code{\index}-like macros. The argument must have -the same format as @code{reftex-index-macros}. It may be a symbol, to -trigger support for one of the builtin index packages. For example, -the style @file{multind.el} contains - -@lisp -(TeX-add-style-hook "multind" - (lambda () - (and (fboundp 'reftex-add-index-macros) - (reftex-add-index-macros '(multind))))) -@end lisp - -If you have your own package @file{myindex} which defines the -following macros to be used with the @LaTeX{} @file{index.sty} file -@example -\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@} -\newcommand@{\aindex@}[1]@{#1\index[author]@{#1@} -@end example - -you could write this in the style file @file{myindex.el}: - -@lisp -(TeX-add-style-hook "myindex" - (lambda () - (TeX-add-symbols - '("molec" TeX-arg-index) - '("aindex" TeX-arg-index)) - (if (fboundp 'reftex-add-index-macros) - (reftex-add-index-macros - '(("molec@{*@}" "idx" ?m "Molecules!" nil nil) - ("aindex@{*@}" "author" ?a "" nil nil)))))) -@end lisp - -@findex reftex-add-section-levels -Finally the hook may contain a call to @code{reftex-add-section-levels} -to define additional section statements. For example, the FoilTeX class -has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here -is a style file @file{foils.el} that will inform @RefTeX{} about these: - -@lisp -(TeX-add-style-hook "foils" - (lambda () - (if (fboundp 'reftex-add-section-levels) - (reftex-add-section-levels '(("foilhead" . 3) - ("rotatefoilhead" . 3)))))) -@end lisp - -@node Bib-Cite -@subsection Bib-Cite -@cindex @code{bib-cite}, Emacs package -@cindex Emacs packages, @code{bib-cite} - -Once you have written a document with labels, references and citations, -it can be nice to read it like a hypertext document. @RefTeX{} has -support for that: @code{reftex-view-crossref} (bound to @kbd{C-c -&}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and -@code{reftex-search-document}. A somewhat fancier interface with mouse -highlighting is provided (among other things) by Peter S. Galbraith's -@file{bib-cite.el}. There is some overlap in the functionalities of -Bib-cite and @RefTeX{}. Bib-cite.el comes bundled with -@AUCTeX{}. - -Bib-cite version 3.06 and later can be configured so that bib-cite's -mouse functions use @RefTeX{} for displaying references and citations. -This can be useful in particular when working with the @LaTeX{} @code{xr} -package or with an explicit @code{thebibliography} environment (rather -than @BibTeX{}). Bib-cite cannot handle those, but @RefTeX{} does. To -make use of this feature, try - -@vindex bib-cite-use-reftex-view-crossref -@lisp -(setq bib-cite-use-reftex-view-crossref t) -@end lisp - -@page -@node Problems and Work-Arounds -@section Problems and Work-arounds -@cindex Problems and work-arounds - -@itemize @bullet -@item -@b{@LaTeX{} commands}@* -@cindex LaTeX commands, not found -@code{\input}, @code{\include}, and @code{\section} (etc.)@: statements -have to be first on a line (except for white space). - -@item -@b{Commented regions}@* -@cindex Labels, commented out -@RefTeX{} sees also labels in regions commented out and will refuse to -make duplicates of such labels. This is considered to be a feature. - -@item -@b{Wrong section numbers}@* -@cindex Section numbers, wrong -@vindex reftex-enable-partial-scans -When using partial scans (@code{reftex-enable-partial-scans}), the section -numbers in the table of contents may eventually become wrong. A full -scan will fix this. - -@item -@b{Local settings}@* -@cindex Settings, local -@findex reftex-add-label-environments -@findex reftex-set-cite-format -@findex reftex-add-section-levels -The label environment definitions in @code{reftex-label-alist} are -global and apply to all documents. If you need to make definitions -local to a document, because they would interfere with settings in other -documents, you should use @AUCTeX{} and set up style files with calls to -@code{reftex-add-label-environments}, @code{reftex-set-cite-format}, -@code{reftex-add-index-macros}, and @code{reftex-add-section-levels}. -Settings made with these functions remain local to the current -document. @xref{AUCTeX}. - -@item -@b{Funny display in selection buffer}@* -@cindex @code{x-symbol}, Emacs package -@cindex Emacs packages, @code{x-symbol} -@cindex @code{isotex}, Emacs package -@cindex Emacs packages, @code{isotex} -@cindex @code{iso-cvt}, Emacs package -@cindex Emacs packages, @code{iso-cvt} -When using packages which make the buffer representation of a file -different from its disk representation (e.g., x-symbol, isotex, -iso-cvt) you may find that @RefTeX{}'s parsing information sometimes -reflects the disk state of a file. This happens only in @emph{unvisited} -parts of a multifile document, because @RefTeX{} visits these files -literally for speed reasons. Then both short context and section -headings may look different from what you usually see on your screen. -In rare cases @code{reftex-toc} may have problems to jump to an affected -section heading. There are three possible ways to deal with -this: -@itemize @minus -@item -@vindex reftex-keep-temporary-buffers -@code{(setq reftex-keep-temporary-buffers t)}@* -This implies that @RefTeX{} will load all parts of a multifile -document into Emacs (i.e., there won't be any temporary buffers). -@item -@vindex reftex-initialize-temporary-buffers -@code{(setq reftex-initialize-temporary-buffers t)}@* -This means full initialization of temporary buffers. It involves -a penalty when the same unvisited file is used for lookup often. -@item -Set @code{reftex-initialize-temporary-buffers} to a list of hook -functions doing a minimal initialization. -@end itemize -@vindex reftex-refontify-context -See also the variable @code{reftex-refontify-context}. - -@item -@b{Labels as arguments to \begin}@* -@cindex @code{pf}, LaTeX package -@cindex LaTeX packages, @code{pf} -Some packages use an additional argument to a @code{\begin} macro -to specify a label. E.g., Lamport's @file{pf.sty} uses both -@example -\step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@} - @var{claim} - \end@{step+@} -@end example - -@noindent -We need to trick @RefTeX{} into swallowing this: - -@lisp -@group -;; Configuration for Lamport's pf.sty -(setq reftex-label-alist - '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St.")) - ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000))) -@end group -@end lisp - -@noindent -The first line is just a normal configuration for a macro. For the -@code{step+} environment we actually tell @RefTeX{} to look for the -@emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first} -argument (which really is a second argument to the macro @code{\begin}) -as a label of type @code{?p}. Argument count for this macro starts only -after the @samp{@{step+@}}, also when specifying how to get -context. - -@item -@b{Idle timers in XEmacs}@* -@cindex Idle timer restart -@vindex reftex-use-itimer-in-xemacs -In XEmacs, idle timer restart does not work reliably after fast -keystrokes. Therefore @RefTeX{} currently uses the post command -hook to start the timer used for automatic crossref information. When -this bug gets fixed, a real idle timer can be requested with -@lisp -(setq reftex-use-itimer-in-xemacs t) -@end lisp - -@item -@b{Viper mode}@* -@cindex Viper mode -@cindex Key bindings, problems with Viper mode -@findex viper-harness-minor-mode -With @i{Viper} mode prior to Vipers version 3.01, you need to protect -@RefTeX{}'s keymaps with - -@lisp -(viper-harness-minor-mode "reftex") -@end lisp - -@end itemize - -@page -@node Imprint -@section Imprint -@cindex Imprint -@cindex Maintainer -@cindex Acknowledgments -@cindex Thanks -@cindex Bug reports -@cindex @code{http}, @RefTeX{} home page -@cindex @code{ftp}, @RefTeX{} site - -@c dominik@@science.uva.nl -@RefTeX{} was written by @i{Carsten Dominik}, with contributions by @i{Stephen -Eglen}. @RefTeX{} is currently maintained by @value{MAINTAINER}, see -the @value{MAINTAINERSITE} for detailed information. - -If you have questions about @RefTeX{}, you can send email to the -@value{SUPPORTADDRESS}. If you want to contribute code or ideas, write -to the @value{DEVELADDRESS}. And in the rare case of finding a bug, -please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a -bug report with useful information about your setup. Remember to add -essential information like a recipe for reproducing the bug, what you -expected to happen, and what actually happened. Send the bug report to -the @value{BUGADDRESS}. - -There are also several Usenet groups which have competent readers who -might be able to help: @code{comp.emacs}, @code{gnu.emacs.help}, -@code{comp.emacs.xemacs}, and @code{comp.text.tex}. - -Thanks to the people on the Net who have used @RefTeX{} and helped -developing it with their reports. In particular thanks to @i{Ralf -Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton, -Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai -Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan -Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz, -Juri Linkov, Wolfgang Mayer, Rory Molinari, Stefan Monnier, Laurent -Mugnier, Dan Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, -Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof, Christoph -Wedler, Alan Williams, Roland Winkler, Hans-Christoph Wirth, Eli -Zaretskii}. - -The @code{view-crossref} feature was inspired by @i{Peter Galbraith's} -@file{bib-cite.el}. - -Finally thanks to @i{Uwe Bolick} who first got me interested in -supporting @LaTeX{} labels and references with an editor (which was -MicroEmacs at the time). - -@c Turn off the raising that we turned on in ``All the rest''. -@ifnottex -@lowersections -@end ifnottex - -@node Commands -@chapter Commands -@cindex Commands, list of - -Here is a summary of @RefTeX{}'s commands which can be executed from -@LaTeX{} files. Command which are executed from the special buffers are -not described here. All commands are available from the @code{Ref} -menu. See @xref{Key Bindings}. - -@deffn Command reftex-toc -Show the table of contents for the current document. When called with -one ore two @kbd{C-u} prefixes, rescan the document first. -@end deffn - -@deffn Command reftex-label -Insert a unique label. With one or two @kbd{C-u} prefixes, enforce -document rescan first. -@end deffn - -@deffn Command reftex-reference -Start a selection process to select a label, and insert a reference to -it. With one or two @kbd{C-u} prefixes, enforce document rescan first. -@end deffn - -@deffn Command reftex-citation -Make a citation using @BibTeX{} database files. After prompting for a regular -expression, scans the buffers with @BibTeX{} entries (taken from the -@code{\bibliography} command or a @code{thebibliography} environment) -and offers the matching entries for selection. The selected entry is -formatted according to @code{reftex-cite-format} and inserted into the -buffer. @* -When called with a @kbd{C-u} prefix, prompt for optional arguments in -cite macros. When called with a numeric prefix, make that many citations. -When called with point inside the braces of a @code{\cite} command, it -will add another key, ignoring the value of -@code{reftex-cite-format}. @* -The regular expression uses an expanded syntax: @samp{&&} is interpreted -as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain -both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion -on knows citation keys is possible. @samp{=} is a good regular -expression to match all entries in all files. -@end deffn - -@deffn Command reftex-index -Query for an index macro and insert it along with its arguments. The -index macros available are those defined in @code{reftex-index-macro} or -by a call to @code{reftex-add-index-macros}, typically from an @AUCTeX{} -style file. @RefTeX{} provides completion for the index tag and the -index key, and will prompt for other arguments. -@end deffn - -@deffn Command reftex-index-selection-or-word -Put current selection or the word near point into the default index -macro. This uses the information in @code{reftex-index-default-macro} -to make an index entry. The phrase indexed is the current selection or -the word near point. When called with one @kbd{C-u} prefix, let the -user have a chance to edit the index entry. When called with 2 -@kbd{C-u} as prefix, also ask for the index macro and other stuff. When -called inside @TeX{} math mode as determined by the @file{texmathp.el} -library which is part of @AUCTeX{}, the string is first processed with the -@code{reftex-index-math-format}, which see. -@end deffn - -@deffn Command reftex-index-phrase-selection-or-word -Add current selection or the word at point to the phrases buffer. -When you are in transient-mark-mode and the region is active, the -selection will be used; otherwise the word at point. -You get a chance to edit the entry in the phrases buffer; to save the -buffer and return to the @LaTeX{} document, finish with @kbd{C-c C-c}. -@end deffn - -@deffn Command reftex-index-visit-phrases-buffer -Switch to the phrases buffer, initialize if empty. -@end deffn - -@deffn Command reftex-index-phrases-apply-to-region -Index all index phrases in the current region. -This works exactly like global indexing from the index phrases buffer, -but operation is restricted to the current region. -@end deffn - -@deffn Command reftex-display-index -Display a buffer with an index compiled from the current document. -When the document has multiple indices, first prompts for the correct one. -When index support is turned off, offer to turn it on. -With one or two @kbd{C-u} prefixes, rescan document first. -With prefix 2, restrict index to current document section. -With prefix 3, restrict index to active region. -@end deffn - -@deffn Command reftex-view-crossref -View cross reference of macro at point. Point must be on the @var{key} -argument. Works with the macros @code{\label}, @code{\ref}, -@code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of -these. Where it makes sense, subsequent calls show additional -locations. See also the variable @code{reftex-view-crossref-extra} and -the command @code{reftex-view-crossref-from-bibtex}. With one or two -@kbd{C-u} prefixes, enforce rescanning of the document. With argument -2, select the window showing the cross reference. -@end deffn - -@deffn Command reftex-view-crossref-from-bibtex -View location in a @LaTeX{} document which cites the @BibTeX{} entry at point. -Since @BibTeX{} files can be used by many @LaTeX{} documents, this function -prompts upon first use for a buffer in @RefTeX{} mode. To reset this -link to a document, call the function with a prefix arg. Calling -this function several times find successive citation locations. -@end deffn - -@deffn Command reftex-create-tags-file -Create TAGS file by running @code{etags} on the current document. The -TAGS file is also immediately visited with -@code{visit-tags-table}. -@end deffn - -@deffn Command reftex-grep-document -Run grep query through all files related to this document. -With prefix arg, force to rescan document. -No active TAGS table is required. -@end deffn - -@deffn Command reftex-search-document -Regexp search through all files of the current document. -Starts always in the master file. Stops when a match is found. -No active TAGS table is required. -@end deffn - -@deffn Command reftex-query-replace-document -Run a query-replace-regexp of @var{from} with @var{to} over the entire -document. With prefix arg, replace only word-delimited matches. No -active TAGS table is required. -@end deffn - -@deffn Command reftex-isearch-minor-mode -Toggle a minor mode which enables incremental search to work globally -on the entire multifile document. Files will be searched in the -sequence they appear in the document. -@end deffn - -@deffn Command reftex-goto-label -Prompt for a label (with completion) and jump to the location of this -label. Optional prefix argument @var{other-window} goes to the label in -another window. -@end deffn - - -@deffn Command reftex-change-label -Query replace @var{from} with @var{to} in all @code{\label} and -@code{\ref} commands. Works on the entire multifile document. No -active TAGS table is required. -@end deffn - -@deffn Command reftex-renumber-simple-labels -Renumber all simple labels in the document to make them sequentially. -Simple labels are the ones created by RefTeX, consisting only of the -prefix and a number. After the command completes, all these labels will -have sequential numbers throughout the document. Any references to the -labels will be changed as well. For this, @RefTeX{} looks at the -arguments of any macros which either start or end with the string -@samp{ref}. This command should be used with care, in particular in -multifile documents. You should not use it if another document refers -to this one with the @code{xr} package. -@end deffn - -@deffn Command reftex-find-duplicate-labels -Produce a list of all duplicate labels in the document. -@end deffn - -@deffn Command reftex-create-bibtex-file -@vindex reftex-create-bibtex-header -@vindex reftex-create-bibtex-footer -Create a new @BibTeX{} database file with all entries referenced in -document. The command prompts for a filename and writes the collected -entries to that file. Only entries referenced in the current document -with any @code{\cite}-like macros are used. The sequence in the new -file is the same as it was in the old database. - -Entries referenced from other entries must appear after all referencing -entries. - -You can define strings to be used as header or footer for the created -files in the variables @code{reftex-create-bibtex-header} or -@code{reftex-create-bibtex-footer} respectively. -@end deffn - -@deffn Command reftex-customize -Run the customize browser on the @RefTeX{} group. -@end deffn -@deffn Command reftex-show-commentary -Show the commentary section from @file{reftex.el}. -@end deffn -@deffn Command reftex-info -Run info on the top @RefTeX{} node. -@end deffn -@deffn Command reftex-parse-document -Parse the entire document in order to update the parsing information. -@end deffn -@deffn Command reftex-reset-mode -Enforce rebuilding of several internal lists and variables. Also -removes the parse file associated with the current document. -@end deffn - -@node Options -@chapter Options, Keymaps, Hooks -@cindex Options, list of - -Here is a complete list of @RefTeX{}'s configuration variables. All -variables have customize support, so if you are not familiar with Emacs -Lisp (and even if you are) you might find it more comfortable to use -@code{customize} to look at and change these variables. @kbd{M-x -reftex-customize} will get you there. - -@menu -* Options - Table of Contents:: -* Options - Defining Label Environments:: -* Options - Creating Labels:: -* Options - Referencing Labels:: -* Options - Creating Citations:: -* Options - Index Support:: -* Options - Viewing Cross-References:: -* Options - Finding Files:: -* Options - Optimizations:: -* Options - Fontification:: -* Options - Misc:: -* Keymaps and Hooks:: -@end menu - -@node Options - Table of Contents -@section Table of Contents -@cindex Options, table of contents -@cindex Table of contents, options - -@defopt reftex-include-file-commands -List of @LaTeX{} commands which input another file. -The file name is expected after the command, either in braces or separated -by whitespace. -@end defopt - -@defopt reftex-max-section-depth -Maximum depth of section levels in document structure. -Standard @LaTeX{} needs 7, default is 12. -@end defopt - -@defopt reftex-section-levels -Commands and levels used for defining sections in the document. The -@code{car} of each cons cell is the name of the section macro. The -@code{cdr} is a number indicating its level. A negative level means the -same as the positive value, but the section will never get a number. -The @code{cdr} may also be a function which then has to return the -level. This list is also used for promotion and demotion of sectioning -commands. If you are using a document class which has several sets of -sectioning commands, promotion only works correctly if this list is -sorted first by set, then within each set by level. The promotion -commands always select the nearest entry with the correct new level. - -@end defopt - -@defopt reftex-toc-max-level -The maximum level of toc entries which will be included in the TOC@. -Section headings with a bigger level will be ignored. In RefTeX, -chapters are level 1, sections level 2 etc. This variable can be -changed from within the @file{*toc*} buffer with the @kbd{t} key. -@end defopt - -@defopt reftex-part-resets-chapter -Non-@code{nil} means, @code{\part} is like any other sectioning command. -This means, part numbers will be included in the numbering of chapters, and -chapter counters will be reset for each part. -When @code{nil} (the default), parts are special, do not reset the -chapter counter and also do not show up in chapter numbers. -@end defopt - -@defopt reftex-auto-recenter-toc -Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on. -When active, the @file{*TOC*} window will always show the section you -are currently working in. Recentering happens whenever Emacs is idle for -more than @code{reftex-idle-time} seconds. - -Value @code{t} means, turn on immediately when RefTeX gets started. Then, -recentering will work for any toc window created during the session. - -Value @code{frame} (the default) means, turn automatic recentering on -only while the dedicated TOC frame does exist, and do the recentering -only in that frame. So when creating that frame (with @kbd{d} key in an -ordinary TOC window), the automatic recentering is turned on. When the -frame gets destroyed, automatic recentering is turned off again. - -This feature can be turned on and off from the menu -(Ref->Options). -@end defopt - -@defopt reftex-toc-split-windows-horizontally -Non-@code{nil} means, create TOC window by splitting window -horizontally. The default is to split vertically. -@end defopt - -@defopt reftex-toc-split-windows-fraction -Fraction of the width or height of the frame to be used for TOC window. -@end defopt - -@defopt reftex-toc-keep-other-windows -Non-@code{nil} means, split the selected window to display the -@file{*toc*} buffer. This helps to keep the window configuration, but -makes the @file{*toc*} small. When @code{nil}, all other windows except -the selected one will be deleted, so that the @file{*toc*} window fills -half the frame. -@end defopt - -@defopt reftex-toc-include-file-boundaries -Non-@code{nil} means, include file boundaries in @file{*toc*} buffer. -This flag can be toggled from within the @file{*toc*} buffer with the -@kbd{i} key. -@end defopt - -@defopt reftex-toc-include-labels -Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag -can be toggled from within the @file{*toc*} buffer with the @kbd{l} -key. -@end defopt - -@defopt reftex-toc-include-index-entries -Non-@code{nil} means, include index entries in @file{*toc*} buffer. -This flag can be toggled from within the @file{*toc*} buffer with the -@kbd{i} key. -@end defopt - -@defopt reftex-toc-include-context -Non-@code{nil} means, include context with labels in the @file{*toc*} -buffer. Context will only be shown if the labels are visible as well. -This flag can be toggled from within the @file{*toc*} buffer with the -@kbd{c} key. -@end defopt - -@defopt reftex-toc-follow-mode -Non-@code{nil} means, point in @file{*toc*} buffer (the -table-of-contents buffer) will cause other window to follow. The other -window will show the corresponding part of the document. This flag can -be toggled from within the @file{*toc*} buffer with the @kbd{f} -key. -@end defopt - -@deffn {Normal Hook} reftex-toc-mode-hook -Normal hook which is run when a @file{*toc*} buffer is -created. -@end deffn - -@deffn Keymap reftex-toc-map -The keymap which is active in the @file{*toc*} buffer. -(@pxref{Table of Contents}). -@end deffn - -@node Options - Defining Label Environments -@section Defining Label Environments -@cindex Options, defining label environments -@cindex Defining label environments, options - -@defopt reftex-default-label-alist-entries -Default label alist specifications. It is a list of symbols with -associations in the constant @code{reftex-label-alist-builtin}. -@code{LaTeX} should always be the last entry. -@end defopt - -@defopt reftex-label-alist -Set this variable to define additions and changes to the defaults in -@code{reftex-default-label-alist-entries}. The only things you -@emph{must not} change is that @code{?s} is the type indicator for -section labels, and @key{SPC} for the @code{any} label type. These are -hard-coded at other places in the code. - -The value of the variable must be a list of items. Each item is a list -itself and has the following structure: - -@example - (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format} - @var{context-method} (@var{magic-word} ... ) @var{toc-level}) -@end example - -Each list entry describes either an environment carrying a counter for -use with @code{\label} and @code{\ref}, or a @LaTeX{} macro defining a -label as (or inside) one of its arguments. The elements of each list -entry are: - -@table @asis -@item @var{env-or-macro} -Name of the environment (like @samp{table}) or macro (like -@samp{\myfig}). For macros, indicate the arguments, as in -@samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional -arguments, a star to mark the label argument, if any. The macro does -not have to have a label argument; you could also use -@samp{\label@{...@}} inside one of its arguments. - -Special names: @code{section} for section labels, @code{any} to define a -group which contains all labels. - -This may also be a function to do local parsing and identify point to be -in a non-standard label environment. The function must take an -argument @var{bound} and limit backward searches to this value. It -should return either @code{nil} or a cons cell @code{(@var{function} -. @var{position})} with the function symbol and the position where the -special environment starts. See the Info documentation for an -example. - -Finally this may also be @code{nil} if the entry is only meant to change -some settings associated with the type indicator character (see -below). - -@item @var{type-key} -Type indicator character, like @code{?t}, must be a printable ASCII -character. The type indicator is a single character which defines a -label type. Any label inside the environment or macro is assumed to -belong to this type. The same character may occur several times in this -list, to cover cases in which different environments carry the same -label type (like @code{equation} and @code{eqnarray}). If the type -indicator is @code{nil} and the macro has a label argument @samp{@{*@}}, -the macro defines neutral labels just like @code{\label}. In this case -the remainder of this entry is ignored. - -@item @var{label-prefix} -Label prefix string, like @samp{tab:}. The prefix is a short string -used as the start of a label. It may be the empty string. The prefix -may contain the following @samp{%} escapes: - -@example -%f Current file name, directory and extension stripped. -%F Current file name relative to master file directory. -%m Master file name, directory and extension stripped. -%M Directory name (without path) where master file is located. -%u User login name, on systems which support this. -%S A section prefix derived with variable @code{reftex-section-prefixes}. -@end example - -@noindent -Example: In a file @file{intro.tex}, @samp{eq:%f:} will become -@samp{eq:intro:}. - -@item @var{reference-format} -Format string for reference insertion in buffer. @samp{%s} will be -replaced by the label. When the format starts with @samp{~}, this -@samp{~} will only be inserted when the character before point is -@emph{not} a whitespace. - -@item @var{context-method} -Indication on how to find the short context. -@itemize @minus -@item -If @code{nil}, use the text following the @samp{\label@{...@}} macro. -@item -If @code{t}, use -@itemize @minus -@item -the section heading for section labels. -@item -text following the @samp{\begin@{...@}} statement of environments (not -a good choice for environments like eqnarray or enumerate, where one has -several labels in a single environment). -@item -text after the macro name (starting with the first arg) for -macros. -@end itemize -@item -If an integer, use the nth argument of the macro. As a special case, -1000 means to get text after the last macro argument. -@item -If a string, use as regexp to search @emph{backward} from the label. -Context is then the text following the end of the match. E.g., setting -this to @samp{\\caption[[@{]} will use the caption in a figure or table -environment. @samp{\\begin@{eqnarray@}\|\\\\} works for -eqnarrays. -@item -If any of @code{caption}, @code{item}, @code{eqnarray-like}, -@code{alignat-like}, this symbol will internally be translated into an -appropriate regexp (see also the variable -@code{reftex-default-context-regexps}). -@item -If a function, call this function with the name of the environment/macro -as argument. On call, point will be just after the @code{\label} macro. -The function is expected to return a suitable context string. It should -throw an exception (error) when failing to find context. As an example, -here is a function returning the 10 chars following the label macro as -context: - -@example -(defun my-context-function (env-or-mac) - (if (> (point-max) (+ 10 (point))) - (buffer-substring (point) (+ 10 (point))) - (error "Buffer too small"))) -@end example -@end itemize - -Label context is used in two ways by @RefTeX{}: For display in the label -menu, and to derive a label string. If you want to use a different -method for each of these, specify them as a dotted pair. -E.g., @code{(nil . t)} uses the text after the label (@code{nil}) for -display, and text from the default position (@code{t}) to derive a label -string. This is actually used for section labels. - -@item @var{magic-word-list} -List of magic words which identify a reference to be of this type. If -the word before point is equal to one of these words when calling -@code{reftex-reference}, the label list offered will be automatically -restricted to labels of the correct type. If the first element of this -word list is the symbol `regexp', the strings are interpreted as regular -expressions. - -@item @var{toc-level} -The integer level at which this environment should be added to the table -of contents. See also @code{reftex-section-levels}. A positive value -will number the entries mixed with the sectioning commands of the same -level. A negative value will make unnumbered entries. Useful only for -theorem-like environments which structure the document. Will be ignored -for macros. When omitted or @code{nil}, no TOC entries will be -made. -@end table - -If the type indicator characters of two or more entries are the same, -@RefTeX{} will use -@itemize @minus -@item -the first non-@code{nil} format and prefix -@item -the magic words of all involved entries. -@end itemize - -Any list entry may also be a symbol. If that has an association in -@code{reftex-label-alist-builtin}, the @code{cddr} of that association is -spliced into the list. However, builtin defaults should normally be set -with the variable @code{reftex-default-label-alist-entries}. -@end defopt - -@defopt reftex-section-prefixes -Prefixes for section labels. When the label prefix given in an entry in -@code{reftex-label-alist} contains @samp{%S}, this list is used to -determine the correct prefix string depending on the current section -level. The list is an alist, with each entry of the form -@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro -names like @samp{chapter}, integer section levels (as given in -@code{reftex-section-levels}), and @code{t} for the default. -@end defopt - -@defopt reftex-default-context-regexps -Alist with default regular expressions for finding context. The emacs -lisp form @w{@code{(format regexp (regexp-quote environment))}} is used -to calculate the final regular expression, so @samp{%s} will be -replaced with the environment or macro. -@end defopt - -@defopt reftex-trust-label-prefix -Non-@code{nil} means, trust the label prefix when determining label type. -It is customary to use special label prefixes to distinguish different label -types. The label prefixes have no syntactic meaning in @LaTeX{} (unless -special packages like fancyref) are being used. RefTeX can and by -default does parse around each label to detect the correct label type, -but this process can be slow when a document contains thousands of -labels. If you use label prefixes consistently, you may speed up -document parsing by setting this variable to a non-@code{nil} value. RefTeX -will then compare the label prefix with the prefixes found in -`reftex-label-alist' and derive the correct label type in this way. -Possible values for this option are: - -@example -t @r{This means to trust any label prefixes found.} -regexp @r{If a regexp, only prefixes matched by the regexp are trusted.} -list @r{List of accepted prefixes, as strings. The colon is part of} - @r{the prefix, e.g., ("fn:" "eqn:" "item:").} -nil @r{Never trust a label prefix.} -@end example -The only disadvantage of using this feature is that the label context -displayed in the label selection buffer along with each label is -simply some text after the label definition. This is no problem if you -place labels keeping this in mind (e.g., @i{before} the equation, @i{at -the beginning} of a fig/tab caption ...). Anyway, it is probably best -to use the regexp or the list value types to fine-tune this feature. -For example, if your document contains thousands of footnotes with -labels fn:xxx, you may want to set this variable to the value "^fn:$" or -("fn:"). Then RefTeX will still do extensive parsing for any -non-footnote labels. -@end defopt - -@node Options - Creating Labels -@section Creating Labels -@cindex Options, creating labels -@cindex Creating labels, options - -@defopt reftex-insert-label-flags -Flags governing label insertion. The value has the form - -@example -(@var{derive} @var{prompt}) -@end example - -If @var{derive} is @code{t}, @RefTeX{} will try to derive a sensible -label from context. A section label for example will be derived from -the section heading. The conversion of the context to a valid label is -governed by the specifications given in -@code{reftex-derive-label-parameters}. If @var{derive} is @code{nil}, -the default label will consist of the prefix and a unique number, like -@samp{eq:23}. - -If @var{prompt} is @code{t}, the user will be prompted for a label -string. When @var{prompt} is @code{nil}, the default label will be -inserted without query. - -So the combination of @var{derive} and @var{prompt} controls label -insertion. Here is a table describing all four possibilities: - -@example -@group -@var{derive} @var{prompt} @var{action} ------------------------------------------------------------ -nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.} -nil t @r{Prompt for label.} -t nil @r{Derive a label from context and insert. No query.} -t t @r{Derive a label from context, prompt for confirmation.} -@end group -@end example - -Each flag may be set to @code{t}, @code{nil}, or a string of label type -letters indicating the label types for which it should be true. Thus, -the combination may be set differently for each label type. The default -settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from -headings (with confirmation). Prompt for figure and table labels. Use -simple labels without confirmation for everything else. - -The available label types are: @code{s} (section), @code{f} (figure), -@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} -(footnote), @code{N} (endnote) plus any definitions in -@code{reftex-label-alist}. -@end defopt - -@deffn Hook reftex-format-label-function -If non-@code{nil}, should be a function which produces the string to -insert as a label definition. The function will be called with two -arguments, the @var{label} and the @var{default-format} (usually -@samp{\label@{%s@}}). It should return the string to insert into the -buffer. -@end deffn - -@deffn Hook reftex-string-to-label-function -Function to turn an arbitrary string into a valid label. -@RefTeX{}'s default function uses the variable -@code{reftex-derive-label-parameters}. -@end deffn - -@deffn Hook reftex-translate-to-ascii-function -Filter function which will process a context string before it is used to -derive a label from it. The intended application is to convert ISO or -Mule characters into something valid in labels. The default function -@code{reftex-latin1-to-ascii} removes the accents from Latin-1 -characters. X-Symbol (>=2.6) sets this variable to the much more -general @code{x-symbol-translate-to-ascii}. -@end deffn - -@defopt reftex-derive-label-parameters -Parameters for converting a string into a label. This variable is a -list of the following items: -@table @asis -@item @var{nwords} -Number of words to use. -@item @var{maxchar} -Maximum number of characters in a label string. -@item @var{invalid} -@code{nil}: Throw away any words containing characters invalid in labels.@* -@code{t}: Throw away only the invalid characters, not the whole word. -@item @var{abbrev} -@code{nil}: Never abbreviate words.@* -@code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@* -@code{1}: Abbreviate words if necessary to shorten label string. -@item @var{separator} -String separating different words in the label. -@item @var{ignorewords} -List of words which should not be part of labels. -@item @var{downcase} -@code{t}: Downcase words before putting them into the label.@* -@end table -@end defopt - -@defopt reftex-label-illegal-re -Regexp matching characters not valid in labels. -@end defopt - -@defopt reftex-abbrev-parameters -Parameters for abbreviation of words. A list of four parameters. -@table @asis -@item @var{min-chars} -Minimum number of characters remaining after abbreviation. -@item @var{min-kill} -Minimum number of characters to remove when abbreviating words. -@item @var{before} -Character class before abbrev point in word. -@item @var{after} -Character class after abbrev point in word. -@end table -@end defopt - -@node Options - Referencing Labels -@section Referencing Labels -@cindex Options, referencing labels -@cindex Referencing labels, options - -@defopt reftex-label-menu-flags -List of flags governing the label menu makeup. The flags are: -@table @asis -@item @var{table-of-contents} -Show the labels embedded in a table of context. -@item @var{section-numbers} -Include section numbers (like 4.1.3) in table of contents. -@item @var{counters} -Show counters. This just numbers the labels in the menu. -@item @var{no-context} -Non-@code{nil} means do @emph{not} show the short context. -@item @var{follow} -Follow full context in other window. -@item @var{show-commented} -Show labels from regions which are commented out. -@item @var{match-everywhere} -Obsolete flag. -@item @var{show-files} -Show begin and end of included files. -@end table - -Each of these flags can be set to @code{t} or @code{nil}, or to a string -of type letters indicating the label types for which it should be true. -These strings work like character classes in regular expressions. Thus, -setting one of the flags to @samp{"sf"} makes the flag true for section -and figure labels, @code{nil} for everything else. Setting it to -@samp{"^sf"} makes it the other way round. - -The available label types are: @code{s} (section), @code{f} (figure), -@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} -(footnote), plus any definitions in @code{reftex-label-alist}. - -Most options can also be switched from the label menu itself, so if you -decide here to not have a table of contents in the label menu, you can -still get one interactively during selection from the label menu. -@end defopt - -@defopt reftex-multiref-punctuation -Punctuation strings for multiple references. When marking is used in -the selection buffer to select several references, this variable -associates the 3 marking characters @samp{,-+} with prefix strings to be -inserted into the buffer before the corresponding @code{\ref} macro. -This is used to string together whole reference sets, like -@samp{eqs. 1,2,3-5,6 and 7} in a single call to -@code{reftex-reference}. -@end defopt - -@defopt reftex-ref-style-alist -Alist of reference styles. Each element is a list of the style name, -the name of the @LaTeX{} package associated with the style or @code{t} -for any package, and an alist of macros where the first entry of each -item is the reference macro and the second a key for selecting the macro -when the macro type is being prompted for. (See also -@code{reftex-ref-macro-prompt}.) The keys, represented as characters, -have to be unique. -@end defopt - -@defopt reftex-ref-style-default-list -List of reference styles to be activated by default. The order is -significant and controls the order in which macros can be cycled in the -buffer for selecting a label. The entries in the list have to match the -respective reference style names used in the variable -@code{reftex-ref-style-alist}. -@end defopt - -@defopt reftex-ref-macro-prompt -Controls if @code{reftex-reference} prompts for the reference macro. -@end defopt - -@deffn Hook reftex-format-ref-function -If non-@code{nil}, should be a function which produces the string to -insert as a reference. Note that the insertion format can also be -changed with @code{reftex-label-alist}. This hook also is used by the -special commands to insert, e.g., @code{\vref} and @code{\fref} -references, so even if you set this, your setting will be ignored by the -special commands. The function will be called with three arguments, the -@var{label}, the @var{default format} which normally is -@samp{~\ref@{%s@}} and the @var{reference style}. The function should -return the string to insert into the buffer. -@end deffn - -@defopt reftex-level-indent -Number of spaces to be used for indentation per section level. -@end defopt - -@defopt reftex-guess-label-type -Non-@code{nil} means, @code{reftex-reference} will try to guess the -label type. To do that, @RefTeX{} will look at the word before the -cursor and compare it with the magic words given in -@code{reftex-label-alist}. When it finds a match, @RefTeX{} will -immediately offer the correct label menu; otherwise it will prompt you -for a label type. If you set this variable to @code{nil}, @RefTeX{} -will always prompt for a label type. -@end defopt - -@deffn {Normal Hook} reftex-display-copied-context-hook -Normal Hook which is run before context is displayed anywhere. Designed -for @w{@code{X-Symbol}}, but may have other uses as well. -@end deffn - -@deffn Hook reftex-pre-refontification-functions -@code{X-Symbol} specific hook. Probably not useful for other purposes. -The functions get two arguments, the buffer from where the command -started and a symbol indicating in what context the hook is -called. -@end deffn - -@deffn {Normal Hook} reftex-select-label-mode-hook -Normal hook which is run when a selection buffer enters -@code{reftex-select-label-mode}. -@end deffn - -@deffn Keymap reftex-select-label-map -The keymap which is active in the labels selection process -(@pxref{Referencing Labels}). -@end deffn - -@node Options - Creating Citations -@section Creating Citations -@cindex Options, creating citations -@cindex Creating citations, options - -@defopt reftex-bibliography-commands -@LaTeX{} commands which specify the @BibTeX{} databases to use with the document. -@end defopt - -@defopt reftex-bibfile-ignore-regexps -List of regular expressions to exclude files in -@code{\\bibliography@{..@}}. File names matched by any of these regexps -will not be parsed. Intended for files which contain only -@code{@@string} macro definitions and the like, which are ignored by -@RefTeX{} anyway. -@end defopt - -@defopt reftex-default-bibliography -List of @BibTeX{} database files which should be used if none are specified. -When @code{reftex-citation} is called from a document with neither -a @samp{\bibliography@{...@}} statement nor a @code{thebibliography} -environment, @RefTeX{} will scan these files instead. Intended for -using @code{reftex-citation} in non-@LaTeX{} files. The files will be -searched along the BIBINPUTS or TEXBIB path. -@end defopt - -@defopt reftex-sort-bibtex-matches -Sorting of the entries found in @BibTeX{} databases by reftex-citation. -Possible values: -@example -nil @r{Do not sort entries.} -author @r{Sort entries by author name.} -year @r{Sort entries by increasing year.} -reverse-year @r{Sort entries by decreasing year.} -@end example -@end defopt - -@defopt reftex-cite-format -The format of citations to be inserted into the buffer. It can be a -string, an alist or a symbol. In the simplest case this is just the string -@samp{\cite@{%l@}}, which is also the default. See the definition of -@code{reftex-cite-format-builtin} for more complex examples. - -If @code{reftex-cite-format} is a string, it will be used as the format. -In the format, the following percent escapes will be expanded. - -@table @code -@item %l -The @BibTeX{} label of the citation. -@item %a -List of author names, see also @code{reftex-cite-punctuation}. -@item %2a -Like %a, but abbreviate more than 2 authors like Jones et al. -@item %A -First author name only. -@item %e -Works like @samp{%a}, but on list of editor names. (@samp{%2e} and -@samp{%E} work a well). -@end table - -It is also possible to access all other @BibTeX{} database fields: - -@example -%b booktitle %c chapter %d edition %h howpublished -%i institution %j journal %k key %m month -%n number %o organization %p pages %P first page -%r address %s school %u publisher %t title -%v volume %y year -%B booktitle, abbreviated %T title, abbreviated -@end example - -@noindent -Usually, only @samp{%l} is needed. The other stuff is mainly for the -echo area display, and for @code{(setq reftex-comment-citations t)}. - -@samp{%<} as a special operator kills punctuation and space around it -after the string has been formatted. - -A pair of square brackets indicates an optional argument, and RefTeX -will prompt for the values of these arguments. - -Beware that all this only works with @BibTeX{} database files. When -citations are made from the @code{\bibitems} in an explicit -@code{thebibliography} environment, only @samp{%l} is available. - -If @code{reftex-cite-format} is an alist of characters and strings, the -user will be prompted for a character to select one of the possible -format strings. - -In order to configure this variable, you can either set -@code{reftex-cite-format} directly yourself or set it to the -@emph{symbol} of one of the predefined styles. The predefined symbols -are those which have an association in the constant -@code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format -'natbib)}. -@end defopt - -@deffn Hook reftex-format-cite-function -If non-@code{nil}, should be a function which produces the string to -insert as a citation. Note that the citation format can also be changed -with the variable @code{reftex-cite-format}. The function will be -called with two arguments, the @var{citation-key} and the -@var{default-format} (taken from @code{reftex-cite-format}). It should -return the string to insert into the buffer. -@end deffn - -@defopt reftex-cite-prompt-optional-args -Non-@code{nil} means, prompt for empty optional arguments in cite macros. -When an entry in @code{reftex-cite-format} ist given with square brackets to -indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can -prompt for values. Possible values are: -@example -nil @r{Never prompt for optional arguments} -t @r{Always prompt} -maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg} -@end example -Unnecessary empty optional arguments are removed before insertion into -the buffer. See @code{reftex-cite-cleanup-optional-args}. -@end defopt - -@defopt reftex-cite-cleanup-optional-args -Non-@code{nil} means, remove empty optional arguments from cite macros -if possible. -@end defopt - -@defopt reftex-comment-citations -Non-@code{nil} means add a comment for each citation describing the full -entry. The comment is formatted according to -@code{reftex-cite-comment-format}. -@end defopt - -@defopt reftex-cite-comment-format -Citation format used for commented citations. Must @emph{not} contain -@samp{%l}. See the variable @code{reftex-cite-format} for possible -percent escapes. -@end defopt - -@defopt reftex-cite-punctuation -Punctuation for formatting of name lists in citations. This is a list -of 3 strings. -@enumerate -@item -normal names separator, like @samp{, } in Jones, Brown and Miller -@item -final names separator, like @samp{ and } in Jones, Brown and Miller -@item -The @samp{et al.} string, like @samp{ @{\it et al.@}} in -Jones @{\it et al.@} -@end enumerate -@end defopt - -@deffn {Normal Hook} reftex-select-bib-mode-hook -Normal hook which is run when a selection buffer enters -@code{reftex-select-bib-mode}. -@end deffn - -@deffn Keymap reftex-select-bib-map -The keymap which is active in the citation-key selection process -(@pxref{Creating Citations}). -@end deffn - -@defopt reftex-cite-key-separator -String used to separate several keys in a single @samp{\\cite} macro. -Per default this is @samp{","} but if you often have to deal with a lot -of entries and need to break the macro across several lines you might -want to change it to @samp{", "}. -@end defopt - -@defopt reftex-create-bibtex-header -Header to insert in BibTeX files generated by -@code{reftex-create-bibtex-file}. -@end defopt - -@defopt reftex-create-bibtex-footer -Footer to insert in BibTeX files generated by -@code{reftex-create-bibtex-file}. -@end defopt - - -@node Options - Index Support, Options - Viewing Cross-References, Options - Creating Citations, Options -@section Index Support -@cindex Options, Index support -@cindex Index support, options - -@defopt reftex-support-index -Non-@code{nil} means, index entries are parsed as well. Index support -is resource intensive and the internal structure holding the parsed -information can become quite big. Therefore it can be turned off. When -this is @code{nil} and you execute a command which requires index -support, you will be asked for confirmation to turn it on and rescan the -document. -@end defopt - -@defopt reftex-index-special-chars -List of special characters in index entries, given as strings. These -correspond to the @code{MakeIndex} keywords -@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}. -@end defopt - -@defopt reftex-index-macros -List of macros which define index entries. The structure of each entry -is -@lisp -(@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat}) -@end lisp - -@var{macro} is the macro. Arguments should be denoted by empty braces, -as for example in @samp{\index[]@{*@}}. Use square brackets to denote -optional arguments. The star marks where the index key is. - -@var{index-tag} is a short name of the index. @samp{idx} and @samp{glo} -are reserved for the default index and the glossary. Other indices can -be defined as well. If this is an integer, the Nth argument of the -macro holds the index tag. - -@var{key} is a character which is used to identify the macro for input -with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are -reserved for default index and glossary. - -@var{prefix} can be a prefix which is added to the @var{key} part of the -index entry. If you have a macro -@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix -should be @samp{Molecules!}. - -@var{exclude} can be a function. If this function exists and returns a -non-@code{nil} value, the index entry at point is ignored. This was -implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts -in the @LaTeX{}2e @code{index} package. - -@var{repeat}, if non-@code{nil}, means the index macro does not typeset -the entry in the text, so that the text has to be repeated outside the -index macro. Needed for @code{reftex-index-selection-or-word} and for -indexing from the phrase buffer. - -The final entry may also be a symbol. It must have an association in -the variable @code{reftex-index-macros-builtin} to specify the main -indexing package you are using. Valid values are currently -@example -default @r{The @LaTeX{} default; unnecessary to specify this one} -multind @r{The multind.sty package} -index @r{The index.sty package} -index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.} - @r{Should not be used; only for old documents} -@end example -Note that @AUCTeX{} sets these things internally for @RefTeX{} as well, -so with a sufficiently new version of @AUCTeX{}, you should not set the -package here. -@end defopt - -@defopt reftex-index-default-macro -The default index macro for @code{reftex-index-selection-or-word}. -This is a list with @code{(@var{macro-key} @var{default-tag})}. - -@var{macro-key} is a character identifying an index macro; see -@code{reftex-index-macros}. - -@var{default-tag} is the tag to be used if the macro requires a -@var{tag} argument. When this is @code{nil} and a @var{tag} is needed, -@RefTeX{} will ask for it. When this is the empty string and the -TAG argument of the index macro is optional, the TAG argument will be -omitted. -@end defopt - -@defopt reftex-index-default-tag -Default index tag. When working with multiple indexes, RefTeX queries -for an index tag when creating index entries or displaying a specific -index. This variable controls the default offered for these queries. -The default can be selected with @key{RET} during selection or -completion. Valid values of this variable are: -@example -nil @r{Do not provide a default index} -"tag" @r{The default index tag given as a string, e.g., "idx"} -last @r{The last used index tag will be offered as default} -@end example -@end defopt - -@defopt reftex-index-math-format -Format of index entries when copied from inside math mode. When -@code{reftex-index-selection-or-word} is executed inside @TeX{} math mode, -the index key copied from the buffer is processed with this format -string through the @code{format} function. This can be used to add the -math delimiters (e.g., @samp{$}) to the string. Requires the -@file{texmathp.el} library which is part of @AUCTeX{}. -@end defopt - -@defopt reftex-index-phrase-file-extension -File extension for the index phrase file. This extension will be added -to the base name of the master file. -@end defopt - -@defopt reftex-index-phrases-logical-and-regexp -Regexp matching the @samp{and} operator for index arguments in phrases -file. When several index arguments in a phrase line are separated by -this operator, each part will generate an index macro. So each match of -the search phrase will produce @emph{several} different index entries. -Make sure this does no match things which are not separators. This -logical @samp{and} has higher priority than the logical @samp{or} -specified in @code{reftex-index-phrases-logical-or-regexp}. -@end defopt - -@defopt reftex-index-phrases-logical-or-regexp -Regexp matching the @samp{or} operator for index arguments in phrases -file. When several index arguments in a phrase line are separated by -this operator, the user will be asked to select one of them at each -match of the search phrase. The first index arg will be the default. A -number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make -sure this does no match things which are not separators. The logical -@samp{and} specified in @code{reftex-index-phrases-logical-or-regexp} -has higher priority than this logical @samp{or}. -@end defopt - -@defopt reftex-index-phrases-search-whole-words -Non-@code{nil} means phrases search will look for whole words, not subwords. -This works by requiring word boundaries at the beginning and end of -the search string. When the search phrase already has a non-word-char -at one of these points, no word boundary is required there. -@end defopt - -@defopt reftex-index-phrases-case-fold-search -Non-@code{nil} means, searching for index phrases will ignore -case. -@end defopt - -@defopt reftex-index-verify-function -A function which is called at each match during global indexing. -If the function returns @code{nil}, the current match is skipped. -@end defopt - -@defopt reftex-index-phrases-skip-indexed-matches -Non-@code{nil} means, skip matches which appear to be indexed already. -When doing global indexing from the phrases buffer, searches for some -phrases may match at places where that phrase was already indexed. In -particular when indexing an already processed document again, this -will even be the norm. When this variable is non-@code{nil}, -@RefTeX{} checks if the match is an index macro argument, or if an -index macro is directly before or after the phrase. If that is the -case, that match will be ignored. -@end defopt - -@defopt reftex-index-phrases-wrap-long-lines -Non-@code{nil} means, when indexing from the phrases buffer, wrap lines. -Inserting indexing commands in a line makes the line longer, often -so long that it does not fit onto the screen. When this variable is -non-@code{nil}, newlines will be added as necessary before and/or after the -indexing command to keep lines short. However, the matched text -phrase and its index command will always end up on a single line. -@end defopt - -@defopt reftex-index-phrases-sort-prefers-entry -Non-@code{nil} means when sorting phrase lines, the explicit index entry -is used. Phrase lines in the phrases buffer contain a search phrase, and -sorting is normally based on these. Some phrase lines also have -an explicit index argument specified. When this variable is -non-@code{nil}, the index argument will be used for sorting. -@end defopt - -@defopt reftex-index-phrases-sort-in-blocks -Non-@code{nil} means, empty and comment lines separate phrase buffer -into blocks. Sorting will then preserve blocks, so that lines are -re-arranged only within blocks. -@end defopt - -@defopt reftex-index-phrases-map -Keymap for the Index Phrases buffer. -@end defopt - -@defopt reftex-index-phrases-mode-hook -Normal hook which is run when a buffer is put into -@code{reftex-index-phrases-mode}. -@end defopt - -@defopt reftex-index-section-letters -The letters which denote sections in the index. Usually these are all -capital letters. Don't use any downcase letters. Order is not -significant, the index will be sorted by whatever the sort function -thinks is correct. In addition to these letters, @RefTeX{} will -create a group @samp{!} which contains all entries sorted below the -lowest specified letter. In the @file{*Index*} buffer, pressing any of -these capital letters or @kbd{!} will jump to that section. -@end defopt - -@defopt reftex-index-include-context -Non-@code{nil} means, display the index definition context in the -@file{*Index*} buffer. This flag may also be toggled from the -@file{*Index*} buffer with the @kbd{c} key. -@end defopt - -@defopt reftex-index-follow-mode -Non-@code{nil} means, point in @file{*Index*} buffer will cause other -window to follow. The other window will show the corresponding part of -the document. This flag can be toggled from within the @file{*Index*} -buffer with the @kbd{f} key. -@end defopt - -@deffn Keymap reftex-index-map -The keymap which is active in the @file{*Index*} buffer -(@pxref{Index Support}). -@end deffn - -@node Options - Viewing Cross-References -@section Viewing Cross-References -@cindex Options, viewing cross-references -@cindex Viewing cross-references, options - -@defopt reftex-view-crossref-extra -Macros which can be used for the display of cross references. -This is used when `reftex-view-crossref' is called with point in an -argument of a macro. Note that crossref viewing for citations, -references (both ways) and index entries is hard-coded. This variable -is only to configure additional structures for which crossreference -viewing can be useful. Each entry has the structure -@example -(@var{macro-re} @var{search-re} @var{highlight}). -@end example -@var{macro-re} is matched against the macro. @var{search-re} is the -regexp used to search for cross references. @samp{%s} in this regexp is -replaced with the macro argument at point. @var{highlight} is an -integer indicating which subgroup of the match should be highlighted. -@end defopt - -@defopt reftex-auto-view-crossref -Non-@code{nil} means, initially turn automatic viewing of crossref info -on. Automatic viewing of crossref info normally uses the echo area. -Whenever point is idle for more than @code{reftex-idle-time} seconds on -the argument of a @code{\ref} or @code{\cite} macro, and no other -message is being displayed, the echo area will display information about -that cross reference. You can also set the variable to the symbol -@code{window}. In this case a small temporary window is used for the -display. This feature can be turned on and off from the menu -(Ref->Options). -@end defopt - -@defopt reftex-idle-time -Time (secs) Emacs has to be idle before automatic crossref display -or toc recentering is done. -@end defopt - -@defopt reftex-cite-view-format -Citation format used to display citation info in the message area. See -the variable @code{reftex-cite-format} for possible percent -escapes. -@end defopt - -@defopt reftex-revisit-to-echo -Non-@code{nil} means, automatic citation display will revisit files if -necessary. When @code{nil}, citation display in echo area will only be active -for cached echo strings (see @code{reftex-cache-cite-echo}), or for -@BibTeX{} database files which are already visited by a live associated -buffers. -@end defopt - -@defopt reftex-cache-cite-echo -Non-@code{nil} means, the information displayed in the echo area for -cite macros (see variable @code{reftex-auto-view-crossref}) is cached and -saved along with the parsing information. The cache survives document -scans. In order to clear it, use @kbd{M-x reftex-reset-mode}. -@end defopt - -@node Options - Finding Files -@section Finding Files -@cindex Options, Finding Files -@cindex Finding files, options - -@defopt reftex-texpath-environment-variables -List of specifications how to retrieve the search path for @TeX{} files. -Several entries are possible. -@itemize @minus -@item -If an element is the name of an environment variable, its content is -used. -@item -If an element starts with an exclamation mark, it is used as a command -to retrieve the path. A typical command with the kpathsearch library -would be @w{@code{"!kpsewhich -show-path=.tex"}}. -@item -Otherwise the element itself is interpreted as a path. -@end itemize -Multiple directories can be separated by the system dependent -@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will -be expanded recursively. See also @code{reftex-use-external-file-finders}. -@end defopt - -@defopt reftex-bibpath-environment-variables -List of specifications how to retrieve the search path for @BibTeX{} -files. Several entries are possible. -@itemize @minus -@item -If an element is the name of an environment variable, its content is -used. -@item -If an element starts with an exclamation mark, it is used as a command -to retrieve the path. A typical command with the kpathsearch library -would be @w{@code{"!kpsewhich -show-path=.bib"}}. -@item -Otherwise the element itself is interpreted as a path. -@end itemize -Multiple directories can be separated by the system dependent -@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will -be expanded recursively. See also @code{reftex-use-external-file-finders}. -@end defopt - -@defopt reftex-file-extensions -Association list with file extensions for different file types. -This is a list of items, each item is like: -@code{(@var{type} . (@var{def-ext} @var{other-ext} ...))} -@example -@var{type}: @r{File type like @code{"bib"} or @code{"tex"}.} -@var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.} -@var{other-ext}: @r{Any number of other valid extensions for this file type.} -@end example -When a files is searched and it does not have any of the valid extensions, -we try the default extension first, and then the naked file name. -@end defopt - -@defopt reftex-search-unrecursed-path-first -Non-@code{nil} means, search all specified directories before trying -recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./}, -then @samp{/tex/}, and then all subdirectories of @samp{./}. If this -option is @code{nil}, the subdirectories of @samp{./} are searched -before @samp{/tex/}. This is mainly for speed; most of the time the -recursive path is for the system files and not for the user files. Set -this to @code{nil} if the default makes @RefTeX{} finding files with -equal names in wrong sequence. -@end defopt - -@defopt reftex-use-external-file-finders -Non-@code{nil} means, use external programs to find files. Normally, -@RefTeX{} searches the paths given in the environment variables -@code{TEXINPUTS} and @code{BIBINPUTS} to find @TeX{} files and @BibTeX{} -database files. With this option turned on, it calls an external -program specified in the option @code{reftex-external-file-finders} -instead. As a side effect, the variables -@code{reftex-texpath-environment-variables} and -@code{reftex-bibpath-environment-variables} will be ignored. -@end defopt - -@defopt reftex-external-file-finders -Association list with external programs to call for finding files. Each -entry is a cons cell @w{@code{(@var{type} . @var{program})}}. -@var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a -string containing the external program to use with any arguments. -@code{%f} will be replaced by the name of the file to be found. Note -that these commands will be executed directly, not via a shell. Only -relevant when @code{reftex-use-external-file-finders} is -non-@code{nil}. -@end defopt - -@page -@node Options - Optimizations -@section Optimizations -@cindex Options, optimizations -@cindex Optimizations, options - -@defopt reftex-keep-temporary-buffers -Non-@code{nil} means, keep buffers created for parsing and lookup. -@RefTeX{} sometimes needs to visit files related to the current -document. We distinguish files visited for -@table @asis -@item PARSING -Parts of a multifile document loaded when (re)-parsing the -document. -@item LOOKUP -@BibTeX{} database files and @TeX{} files loaded to find a reference, to -display label context, etc. -@end table -The created buffers can be kept for later use, or be thrown away -immediately after use, depending on the value of this variable: - -@table @code -@item nil -Throw away as much as possible. -@item t -Keep everything. -@item 1 -Throw away buffers created for parsing, but keep the ones created for -lookup. -@end table - -If a buffer is to be kept, the file is visited normally (which is -potentially slow but will happen only once). If a buffer is to be thrown -away, the initialization of the buffer depends upon the variable -@code{reftex-initialize-temporary-buffers}. -@end defopt - -@defopt reftex-initialize-temporary-buffers -Non-@code{nil} means do initializations even when visiting file -temporarily. When @code{nil}, @RefTeX{} may turn off find-file hooks and -other stuff to briefly visit a file. When @code{t}, the full default -initializations are done (@code{find-file-hook} etc.). Instead of -@code{t} or @code{nil}, this variable may also be a list of hook -functions to do a minimal initialization. -@end defopt - -@defopt reftex-no-include-regexps -List of regular expressions to exclude certain input files from parsing. -If the name of a file included via @code{\include} or @code{\input} is -matched by any of the regular expressions in this list, that file is not -parsed by @RefTeX{}. -@end defopt - -@defopt reftex-enable-partial-scans -Non-@code{nil} means, re-parse only 1 file when asked to re-parse. -Re-parsing is normally requested with a @kbd{C-u} prefix to many @RefTeX{} -commands, or with the @kbd{r} key in menus. When this option is -@code{t} in a multifile document, we will only parse the current buffer, -or the file associated with the label or section heading near point in a -menu. Requesting re-parsing of an entire multifile document then -requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in -menus. -@end defopt - -@defopt reftex-save-parse-info -Non-@code{nil} means, save information gathered with parsing in files. -The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is -used to save the information. When this variable is @code{t}, -@itemize @minus -@item -accessing the parsing information for the first time in an editing -session will read that file (if available) instead of parsing the -document. -@item -exiting Emacs or killing a buffer in reftex-mode will cause a new -version of the file to be written. -@end itemize -@end defopt - -@defopt reftex-parse-file-extension -File extension for the file in which parser information is stored. -This extension is added to the base name of the master file. -@end defopt - -@defopt reftex-allow-automatic-rescan -Non-@code{nil} means, @RefTeX{} may rescan the document when this seems -necessary. Applies (currently) only in rare cases, when a new label -cannot be placed with certainty into the internal label list. -@end defopt - -@defopt reftex-use-multiple-selection-buffers -Non-@code{nil} means use a separate selection buffer for each label -type. These buffers are kept from one selection to the next and need -not be created for each use, so the menu generally comes up faster. -The selection buffers will be erased (and therefore updated) -automatically when new labels in its category are added. See the -variable @code{reftex-auto-update-selection-buffers}. -@end defopt - -@defopt reftex-auto-update-selection-buffers -Non-@code{nil} means, selection buffers will be updated automatically. -When a new label is defined with @code{reftex-label}, all selection -buffers associated with that label category are emptied, in order to -force an update upon next use. When @code{nil}, the buffers are left -alone and have to be updated by hand, with the @kbd{g} key from the -label selection process. The value of this variable will only have any -effect when @code{reftex-use-multiple-selection-buffers} is -non-@code{nil}. -@end defopt - -@node Options - Fontification -@section Fontification -@cindex Options, fontification -@cindex Fontification, options - -@defopt reftex-use-fonts -Non-@code{nil} means, use fonts in label menu and on-the-fly help. -Font-lock must be loaded as well to actually get fontified -display. After changing this option, a rescan may be necessary to -activate it. -@end defopt - -@defopt reftex-refontify-context -Non-@code{nil} means, re-fontify the context in the label menu with -font-lock. This slightly slows down the creation of the label menu. It -is only necessary when you definitely want the context fontified. - -This option may have 3 different values: -@table @code -@item nil -Never refontify. -@item t -Always refontify. -@item 1 -Refontify when necessary, e.g., with old versions of the x-symbol -package. -@end table -The option is ignored when @code{reftex-use-fonts} is @code{nil}. -@end defopt - -@defopt reftex-highlight-selection -Non-@code{nil} means, highlight selected text in selection and -@file{*toc*} buffers. Normally, the text near the cursor is the -@emph{selected} text, and it is highlighted. This is the entry most -keys in the selection and @file{*toc*} buffers act on. However, if you -mainly use the mouse to select an item, you may find it nice to have -mouse-triggered highlighting @emph{instead} or @emph{as well}. The -variable may have one of these values: - -@example -nil @r{No highlighting.} -cursor @r{Highlighting is cursor driven.} -mouse @r{Highlighting is mouse driven.} -both @r{Both cursor and mouse trigger highlighting.} -@end example - -Changing this variable requires to rebuild the selection and *toc* -buffers to become effective (keys @kbd{g} or @kbd{r}). -@end defopt - -@defopt reftex-cursor-selected-face -Face name to highlight cursor selected item in toc and selection buffers. -See also the variable @code{reftex-highlight-selection}. -@end defopt -@defopt reftex-mouse-selected-face -Face name to highlight mouse selected item in toc and selection buffers. -See also the variable @code{reftex-highlight-selection}. -@end defopt -@defopt reftex-file-boundary-face -Face name for file boundaries in selection buffer. -@end defopt -@defopt reftex-label-face -Face name for labels in selection buffer. -@end defopt -@defopt reftex-section-heading-face -Face name for section headings in toc and selection buffers. -@end defopt -@defopt reftex-toc-header-face -Face name for the header of a toc buffer. -@end defopt -@defopt reftex-bib-author-face -Face name for author names in bib selection buffer. -@end defopt -@defopt reftex-bib-year-face -Face name for year in bib selection buffer. -@end defopt -@defopt reftex-bib-title-face -Face name for article title in bib selection buffer. -@end defopt -@defopt reftex-bib-extra-face -Face name for bibliographic information in bib selection buffer. -@end defopt -@defopt reftex-select-mark-face -Face name for marked entries in the selection buffers. -@end defopt -@defopt reftex-index-header-face -Face name for the header of an index buffer. -@end defopt -@defopt reftex-index-section-face -Face name for the start of a new letter section in the index. -@end defopt -@defopt reftex-index-tag-face -Face name for index names (for multiple indices). -@end defopt -@defopt reftex-index-face -Face name for index entries. -@end defopt - -@node Options - Misc -@section Miscellaneous -@cindex Options, misc - -@defopt reftex-extra-bindings -Non-@code{nil} means, make additional key bindings on startup. These -extra bindings are located in the users @samp{C-c letter} -map. @xref{Key Bindings}. -@end defopt - -@defopt reftex-plug-into-AUCTeX -Plug-in flags for @AUCTeX{} interface. This variable is a list of -5 boolean flags. When a flag is non-@code{nil}, @RefTeX{} -will - -@example -- supply labels in new sections and environments (flag 1) -- supply arguments for macros like @code{\label} (flag 2) -- supply arguments for macros like @code{\ref} (flag 3) -- supply arguments for macros like @code{\cite} (flag 4) -- supply arguments for macros like @code{\index} (flag 5) -@end example - -You may also set the variable itself to @code{t} or @code{nil} in -order to turn all options on or off, respectively.@* -Supplying labels in new sections and environments applies when creating -sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@* -Supplying macro arguments applies when you insert such a macro -interactively with @kbd{C-c @key{RET}}.@* -See the @AUCTeX{} documentation for more information. -@end defopt - -@defopt reftex-revisit-to-follow -Non-@code{nil} means, follow-mode will revisit files if necessary. -When @code{nil}, follow-mode will be suspended for stuff in unvisited files. -@end defopt - -@defopt reftex-allow-detached-macro-args -Non-@code{nil} means, allow arguments of macros to be detached by -whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb -[xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that -this will be the case even if @code{\bb} is defined with zero or one -argument. -@end defopt - -@node Keymaps and Hooks -@section Keymaps and Hooks -@cindex Keymaps - -@RefTeX{} has the usual general keymap, load hook and mode hook. - -@deffn Keymap reftex-mode-map -The keymap for @RefTeX{} mode. -@end deffn - -@deffn {Normal Hook} reftex-load-hook -Normal hook which is being run when loading @file{reftex.el}. -@end deffn - -@deffn {Normal Hook} reftex-mode-hook -Normal hook which is being run when turning on @RefTeX{} mode. -@end deffn - -Furthermore, the four modes used for referencing labels, creating -citations, the table of contents buffer and the phrases buffer have -their own keymaps and mode hooks. See the respective sections. There -are many more hooks which are described in the relevant sections about -options for a specific part of @RefTeX{}. - -@node Changes -@chapter Changes -@cindex Changes - -Here is a list of recent changes to @RefTeX{}. - -@noindent @b{Version 4.33} - -@itemize @bullet -@item -Update to GPLv3. -@item -Parse files are created in a way that does not interfere with recentf -mode. -@end itemize - -@noindent @b{Version 4.32} - -@itemize @bullet -@item -First release by @AUCTeX{} project. -@item -Installation routine rewritten after structure of source package -changed. -@item -Activation of @RefTeX{} changed, so make sure you read the installation -instructions and remove obsolete cruft related to @RefTeX{} from your -init file. -@item -Fixed bug where point would end up in the wrong buffer when jumping -between several @LaTeX{} and phrases buffers. -@item -Fixed bug where @BibTeX{} keys with hyphens were parsed incorrectly. -@item -Some performance improvements. -@item -The separator used between multiple citations in a \cite macro can now -be changed by customizing the variable @code{reftex-cite-key-separator}. -@end itemize - -@noindent @b{Version 4.28} -@itemize @bullet -@item Support for the Jurabib package. -@item Improvements when selecting several items in a selection buffer. -@end itemize - -@noindent @b{Version 4.26} -@itemize @bullet -@item -Support for global incremental search. -@item -Some improvements for XEmacs compatibility. -@end itemize - -@noindent @b{Version 4.25} -@itemize @bullet -@item -Fixed bug with @samp{%F} in a label prefix. Added new escapes -@samp{%m} and @samp{%M} for mater file name and master directory. -@end itemize - -@noindent @b{Version 4.24} -@itemize @bullet -@item -Inserting citation commands now prompts for optional arguments -when called with a prefix argument. Related new options are -@code{reftex-cite-prompt-optional-args} and -@code{reftex-cite-cleanup-optional-args}. -@item -New option @code{reftex-trust-label-prefix}. Configure this variable -if you'd like RefTeX to base its classification of labels on prefixes. -This can speed-up document parsing, but may in some cases reduce the -quality of the context used by RefTeX to describe a label. -@item -Fixed bug in @code{reftex-create-bibtex-file} when -@code{reftex-comment-citations} is non-@code{nil}. -@item -Fixed bugs in indexing: Case-sensitive search, quotes before and/or -after words. Disabled indexing in comment lines. -@end itemize - -@noindent @b{Version 4.22} -@itemize @bullet -@item -New command @code{reftex-create-bibtex-file} to create a new database -with all entries referenced in the current document. -@item -New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file -from entries marked in a citation selection buffer. -@end itemize - -@noindent @b{Version 4.21} -@itemize @bullet -@item -Renaming labels from the toc buffer with key @kbd{M-%}. -@end itemize - -@noindent @b{Version 4.20} -@itemize @bullet -@item -Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in -the TOC buffer promote/demote the section at point or all sections in -the current region. -@item -New option @code{reftex-toc-split-windows-fraction} to set the size of -the window used by the TOC@. This makes the old variable -@code{reftex-toc-split-windows-horizontally-fraction} obsolete. -@item -A dedicated frame can show the TOC with the current section -always automatically highlighted. The frame is created and -deleted from the toc buffer with the @kbd{d} key. -@end itemize - -@noindent @b{Version 4.19} -@itemize @bullet -@item -New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current -section in the TOC buffer without selecting the TOC window. -@item -Recentering happens automatically in idle time when the option -@code{reftex-auto-recenter-toc} is turned on. -@item -Fixed several bugs related to automatic cursor positioning in the TOC -buffer. -@item -The highlight in the TOC buffer stays when the focus moves to a -different window. -@item -New command `reftex-goto-label'. -@item -Part numbers are no longer included in chapter numbers, and a new -part does not reset the chapter counter. See new option -@code{reftex-part-resets-chapter}. -@end itemize - -@noindent @b{Version 4.18} -@itemize @bullet -@item -@code{reftex-citation} uses the word before the cursor as a default -search string. -@item -Simplified several regular expressions for speed. -@item -Better support for chapterbib. -@end itemize - -@noindent @b{Version 4.17} -@itemize @bullet -@item -The toc window can be split off horizontally. See new options -@code{reftex-toc-split-windows-horizontally}, -@code{reftex-toc-split-windows-horizontally-fraction}. -@item -It is possible to specify a function which verifies an index match -during global indexing. See new option @code{reftex-index-verify-function}. -@item -The macros which input a file in LaTeX (like \input, \include) can -be configured. See new option @code{reftex-include-file-commands}. -@item -The macros which specify the bibliography file (like \bibliography) can -be configured. See new option @code{reftex-bibliography-commands}. -@item -The regular expression used to search for the \bibliography macro has -been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by -chapterbib. -@item -Small bug fixes. -@end itemize - -@noindent @b{Version 4.15} -@itemize @bullet -@item -Fixed bug with parsing of BibTeX files, when fields contain quotes or -unmatched parenthesis. -@item -Small bug fixes. -@item -Improved interaction with Emacs LaTeX mode. -@end itemize - -@noindent @b{Version 4.12} -@itemize @bullet -@item -Support for @file{bibentry} citation style. -@end itemize - -@noindent @b{Version 4.11} -@itemize @bullet -@item -Fixed bug which would parse @samp{\Section} just like @samp{\section}. -@end itemize - -@noindent @b{Version 4.10} -@itemize @bullet -@item -Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict -with @file{reftex-vars.el} on DOS machines. -@item -New options @code{reftex-parse-file-extension} and -@code{reftex-index-phrase-file-extension}. -@end itemize - -@noindent [.....] -@ignore -@noindent @b{Version 4.09} -@itemize @bullet -@item -New option @code{reftex-toc-max-level} to limit the depth of the toc. -New key binding @kbd{t} in the @file{*toc*} buffer to change this -setting. -@item -RefTeX maintains an @file{Index Phrases} file in which phrases can be -collected. When the document is ready, RefTeX can search all -these phrases and assist indexing all matches. -@item -The variables @code{reftex-index-macros} and -@code{reftex-index-default-macro} have changed their syntax slightly. -The @var{repeat} parameter has move from the latter to the former. -Also calls to @code{reftex-add-index-macros} from AUCTeX style files -need to be adapted. -@item -The variable @code{reftex-section-levels} no longer contains the -default stuff which has been moved to a constant. -@item -Environments like theorems can be placed into the TOC by putting -entries for @samp{"begin@{theorem@}"} in -@code{reftex-section-levels}. -@end itemize - -@noindent @b{Version 4.06} -@itemize @bullet -@item -@code{reftex-section-levels} can contain a function to compute the level -of a sectioning command. -@item -Multiple @code{thebibliography} environments recognized. -@end itemize - -@noindent @b{Version 4.04} -@itemize @bullet -@item -New option @code{reftex-index-default-tag} implements a default for queries. -@end itemize - -@noindent @b{Version 4.02} -@itemize @bullet -@item -macros ending in @samp{refrange} are considered to contain references. -@item -Index entries made with @code{reftex-index-selection-or-word} in TeX -math mode automatically get enclosing @samp{$} to preserve math mode. See -new option @code{reftex-index-math-format}. Requires AUCTeX. -@end itemize - -@noindent @b{Version 4.01} -@itemize @bullet -@item -New command @code{reftex-index-globally} to index a word in many -places in the document. Also available from the index buffer with -@kbd{&}. -@item -The first item in a @code{reftex-label-alist} entry may now also be a parser -function to do non-standard parsing. -@item -@code{reftex-auto-view-crossref} no longer interferes with -@code{pop-up-frames} (patch from Stefan Monnier). -@end itemize - -@noindent @b{Version 4.00} -@itemize @bullet -@item -RefTeX has been split into several smaller files which are autoloaded on -demand. -@item -Index support, along with many new options. -@item -The selection of keys for @code{\ref} and @code{\cite} now allows to -select multiple items by marking entries with the @kbd{m} key. -@item -Fancyref support. -@end itemize - -@noindent @b{Version 3.43} -@itemize @bullet -@item -Viewing cross-references generalized. Now works on @code{\label}, -@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of -these, and from BibTeX buffers. -@item -New option @code{reftex-view-crossref-extra}. -@item -Support for the additional sectioning commands @code{\addchap} and -@code{\addsec} which are defined in the LaTeX KOMA-Script classes. -@item -Files in @code{reftex-default-bibliography} will be searched along -@code{BIBINPUTS} path. -@item -Reading a parse file now checks consistency. -@end itemize - -@noindent @b{Version 3.42} -@itemize @bullet -@item -File search further refined. New option @code{reftex-file-extensions}. -@item -@file{*toc*} buffer can show the file boundaries of a multifile -document, all labels and associated context. New keys @kbd{i}, @kbd{l}, -and @kbd{c}. New options @code{reftex-toc-include-labels}, -@code{reftex-toc-include-context}, -@code{reftex-toc-include-file-boundaries}. -@end itemize - -@noindent @b{Version 3.41} -@itemize @bullet -@item -New options @code{reftex-texpath-environment-variables}, -@code{reftex-use-external-file-finders}, -@code{reftex-external-file-finders}, -@code{reftex-search-unrecursed-path-first}. -@item -@emph{kpathsearch} support. See new options and -@code{reftex-bibpath-environment-variables}. -@end itemize - -@noindent @b{Version 3.38} -@itemize @bullet -@item -@code{reftex-view-crossref} no longer moves to find a macro. Point has -to be on the macro argument. -@end itemize - -@noindent @b{Version 3.36} -@itemize @bullet -@item -New value @code{window} for option @code{reftex-auto-view-crossref}. -@end itemize - -@noindent @b{Version 3.35} -@itemize @bullet -@item -ISO 8859 Latin-1 chars are converted to ASCII to derive better labels. -This takes back the related changes in 3.34 for safety reasons. -@end itemize - -@noindent @b{Version 3.34} -@itemize @bullet -@item -Additional flag in @code{reftex-derive-label-parameters} do make only -lowercase labels (default @code{t}). -@item -All @file{.rel} files have a final newline to avoid queries. -@item -Single byte representations of accented European letters (ISO-8859-1) -are now valid in labels. -@end itemize - -@noindent @b{Version 3.33} -@itemize @bullet -@item -Multiple selection buffers are now hidden buffers (they start with a -SPACE). -@item -Fixed bug with file search when TEXINPUTS environment variable is empty. -@end itemize - -@noindent @b{Version 3.30} -@itemize @bullet -@item -In @code{reftex-citation}, the regular expression used to scan BibTeX -files can be specified using completion on known citation keys. -@item -New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all} -entries. -@item -New command @code{reftex-renumber-simple-labels} to renumber simple -labels like @samp{eq:13} sequentially through a document. -@end itemize - -@noindent @b{Version 3.28} -@itemize @bullet -@item -Auto view crossref for XEmacs uses @code{post-command-hook} to restart the -timer, since itimer restart is not reliable. -@item -Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}. -@item -Expansion of recursive tex and bib path rewritten. -@item -Fixed problem where @RefTeX{} did not scan unsaved buffers. -@item -Fixed bug with section numbering after *-red sections. -@end itemize - -@noindent @b{Version 3.27} -@itemize @bullet -@item -Macros can define @emph{neutral} labels, just like @code{\label} -itself. -@item -New option @code{reftex-allow-detached-macro-args}, default @code{nil}! -@end itemize - -@noindent @b{Version 3.26} -@itemize @bullet -@item -[X]Emacs 19 no longer supported. Use 3.22 for Emacs 19. -@item -New hooks @code{reftex-translate-to-ascii-function}, -@code{reftex-string-to-label-function}. -@item -Made sure automatic crossref display will not visit/scan files. -@end itemize - -@noindent @b{Version 3.25} -@itemize @bullet -@item -Echoing of citation info caches the info for displayed entries. -New option @code{reftex-cache-cite-echo}. -@item -@kbd{M-x reftex-reset-mode} now also removes the file with parsing -info. -@item -Default of @code{reftex-revisit-to-follow} changed to @code{nil}. -@end itemize - -@noindent @b{Version 3.24} -@itemize @bullet -@item -New option @code{reftex-revisit-to-echo}. -@item -Interface with X-Symbol (>=2.6) is now complete and stable. -@item -Adapted to new outline, which uses overlays. -@item -File names in @code{\bibliography} may now have the @code{.bib} -extension. -@item -Fixed Bug with parsing "single file" from master file buffer. -@end itemize - -@noindent @b{Version 3.23} -@itemize @bullet -@item -Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs. -@item -@code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse -file. -@item -The cursor inside a @code{\ref} or @code{\cite} macro can now trigger -automatic display of crossref information in the echo area. See -variable @code{reftex-auto-view-crossref}. -@item -AUCTeX interface updates: -@itemize @minus -@item -AUCTeX 9.9c and later notifies @RefTeX{} about new sections. -@item -@RefTeX{} notifies AUCTeX about new labels. -@item -@code{TeX-arg-ref} no longer used (introduction was unnecessary). -@item -@code{reftex-arg-label} and @code{reftex-arg-cite} fixed up. -@item -Settings added to @RefTeX{} via style files remain local. -@end itemize -@item -Fixed bug with @code{reftex-citation} in non-latex buffers. -@item -Fixed bug with syntax table and context refontification. -@item -Safety-net for name change of @code{font-lock-reference-face}. -@end itemize - -@noindent @b{Version 3.22} -@itemize @bullet -@item -Fixed bug with empty context strings. -@item -@code{reftex-mouse-view-crossref} is now bound by default at -@kbd{S-mouse-2}. -@end itemize - -@noindent @b{Version 3.21} -@itemize @bullet -@item -New options for all faces used by @RefTeX{}. They're in the -customization group @code{reftex-fontification-configurations}. -@end itemize - -@noindent @b{Version 3.19} -@itemize @bullet -@item -Fixed bug with AUCTeX @code{TeX-master}. -@end itemize - -@noindent @b{Version 3.18} -@itemize @bullet -@item -The selection now uses a recursive edit, much like minibuffer input. -This removes all restrictions during selection. E.g., you can now -switch buffers at will, use the mouse etc. -@item -New option @code{reftex-highlight-selection}. -@item -@kbd{mouse-2} can be used to select in selection and @file{*toc*} -buffers. -@item -Fixed some problems regarding the interaction with VIPER mode. -@item -Follow-mode is now only used after point motion. -@item -@RefTeX{} now finally does not fontify temporary files anymore. -@end itemize - -@noindent @b{Version 3.17} -@itemize @bullet -@item -Additional bindings in selection and @file{*toc*} buffers. @kbd{g} -redefined. -@item -New command @code{reftex-save-all-document-buffers}. -@item -Magic word matching made more intelligent. -@item -Selection process can switch to completion (with @key{TAB}). -@item -@code{\appendix} is now recognized and influences section numbering. -@item -File commentary shortened considerably (use Info documentation). -@item -New option @code{reftex-no-include-regexps} to skip some include files. -@item -New option @code{reftex-revisit-to-follow}. -@end itemize - -@noindent @b{Version 3.16} -@itemize @bullet -@item -New hooks @code{reftex-format-label-function}, -@code{reftex-format-ref-function}, @code{reftex-format-cite-function}. -@item -TeXInfo documentation completed. -@item -Some restrictions in Label inserting and referencing removed. -@item -New variable @code{reftex-default-bibliography}. -@end itemize - -@noindent @b{Version 3.14} -@itemize @bullet -@item -Selection buffers can be kept between selections: this is faster. -See new variable @code{reftex-use-multiple-selection-buffers}. -@item -Prefix interpretation of reftex-view-crossref changed. -@item -Support for the @code{varioref} package (@kbd{v} key in selection -buffer). -@end itemize - -@noindent @b{Version 3.12} -@itemize @bullet -@item -There are 3 new keymaps for customization: @code{reftex-toc-map}, -@code{reftex-select-label-map}, @code{reftex-select-bib-map}. -@item -Refontification uses more standard font-lock stuff. -@item -When no BibTeX database files are specified, citations can also use -@code{\bibitem} entries from a @code{thebibliography} environment. -@end itemize - -@noindent @b{Version 3.11} -@itemize @bullet -@item -Fixed bug which led to naked label in (e.g.@:) footnotes. -@item -Added scroll-other-window functions to RefTeX-Select. -@end itemize - -@noindent @b{Version 3.10} -@itemize @bullet -@item -Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19. -@item -Removed unimportant code which caused OS/2 Emacs to crash. -@item -All customization variables now accessible from menu. -@end itemize - -@noindent @b{Version 3.07} -@itemize @bullet -@item -@code{Ref} menu improved. -@end itemize - -@noindent @b{Version 3.05} -@itemize @bullet -@item -Compatibility code now first checks for XEmacs feature. -@end itemize - -@noindent @b{Version 3.04} -@itemize @bullet -@item -Fixed BUG in the @emph{xr} support. -@end itemize - -@noindent @b{Version 3.03} -@itemize @bullet -@item -Support for the LaTeX package @code{xr}, for inter-document -references. -@item -A few (minor) Mule-related changes. -@item -Fixed bug which could cause @emph{huge} @file{.rel} files. -@item -Search for input and @file{.bib} files with recursive path definitions. -@end itemize - -@noindent @b{Version 3.00} -@itemize @bullet -@item -@RefTeX{} should work better for very large projects: -@item -The new parser works without creating a master buffer. -@item -Rescanning can be limited to a part of a multifile document. -@item -Information from the parser can be stored in a file. -@item -@RefTeX{} can deal with macros having a naked label as an argument. -@item -Macros may have white space and newlines between arguments. -@item -Multiple identical section headings no longer confuse -@code{reftex-toc}. -@item -@RefTeX{} should work correctly in combination with buffer-altering -packages like outline, folding, x-symbol, iso-cvt, isotex, etc. -@item -All labeled environments discussed in @emph{The LaTeX Companion} by -Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of -@RefTeX{}'s defaults. -@end itemize - -@noindent @b{Version 2.17} -@itemize @bullet -@item -Label prefix expands % escapes with current file name and other stuff. -@item -Citation format now with % escapes. This is not backward -compatible! -@item -TEXINPUTS variable recognized when looking for input files. -@item -Context can be the nth argument of a macro. -@item -Searching in the select buffer is now possible (@kbd{C-s} and -@kbd{C-r}). -@item -Display and derive-label can use two different context methods. -@item -AMSmath @code{xalignat} and @code{xxalignat} added. -@end itemize - -@noindent @b{Version 2.14} -@itemize @bullet -@item -Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with -AUCTeX. -@end itemize - -@noindent @b{Version 2.11} -@itemize @bullet -@item -Submitted for inclusion to Emacs and XEmacs. -@end itemize - -@noindent @b{Version 2.07} -@itemize @bullet -@item -New functions @code{reftex-search-document}, -@code{reftex-query-replace-document}. -@end itemize - -@noindent @b{Version 2.05} -@itemize @bullet -@item -Support for @file{custom.el}. -@item -New function @code{reftex-grep-document} (thanks to Stephen Eglen). -@end itemize - -@noindent @b{Version 2.03} -@itemize @bullet -@item -@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to -default environments. -@item -@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari). -@item -New functions @code{reftex-arg-label}, @code{reftex-arg-ref}, -@code{reftex-arg-cite}. -@item -Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is -required. -@item -@code{reftex-add-to-label-alist} (to be called from AUCTeX style -files). -@item -Finding context with a hook function. -@item -Sorting BibTeX entries (new variable: -@code{reftex-sort-bibtex-matches}). -@end itemize - -@noindent @b{Version 2.00} -@itemize @bullet -@item -Labels can be derived from context (default for sections). -@item -Configuration of label insertion and label referencing revised. -@item -Crossref fields in BibTeX database entries. -@item -@code{reftex-toc} introduced (thanks to Stephen Eglen). -@end itemize - -@noindent @b{Version 1.09} -@itemize @bullet -@item -Support for @code{tex-main-file}, an analogue for -@code{TeX-master}. -@item -MS-DOS support. -@end itemize - -@noindent @b{Version 1.07} -@itemize @bullet -@item -@RefTeX{} gets its own menu. -@end itemize - -@noindent @b{Version 1.05} -@itemize @bullet -@item -XEmacs port. -@end itemize - -@noindent @b{Version 1.04} -@itemize @bullet -@item -Macros as wrappers, AMSTeX support, delayed context parsing for -new labels. -@end itemize -@end ignore - -@noindent @b{Version 1.00} -@itemize @bullet -@item -released on 7 Jan 1997. -@end itemize - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@bye diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi deleted file mode 100644 index 5e2c1e2b0f6..00000000000 --- a/doc/misc/remember.texi +++ /dev/null @@ -1,445 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/remember -@settitle Remember Manual -@syncodeindex fn cp -@documentencoding UTF-8 -@c %**end of header - -@copying -This manual is for Remember Mode, version 2.0 - -Copyright @copyright{} 2001, 2004--2005, 2007--2014 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Remember: (remember). Simple information manager for Emacs. -@end direntry - -@titlepage -@title Guide to Remember Mode -@subtitle a simple information manager -@subtitle for Emacs and XEmacs - -@c The following two commands -@c start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Remember - -@insertcopying -@end ifnottex - -@menu -* Preface:: About the documentation. -* Introduction:: What is Remember Mode? -* Implementation:: How Remember came into existence. -* Quick Start:: Get started using Remember. -* Function Reference:: Interactive functions in remember.el. -* Keystrokes:: Keystrokes bound in Remember Mode. -* Backends:: Backends for saving notes. -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: Search for terms. - -@detailmenu - --- The Detailed Node Listing --- - -Backends - -* Text File:: Saving to a text file. -* Separate Text Files:: Saving to separate text files. -* Diary:: Saving to a Diary file. -* Mailbox:: Saving to a mailbox. -* Org:: Saving to an Org Mode file. - -@end detailmenu -@end menu - -@node Preface -@chapter Preface - -This document describes remember.el, which was written by John Wiegley, -was once maintained by Sacha Chua, and is now maintained by the Emacs -developers. - -This document is a work in progress, and your contribution will be -greatly appreciated. - -@node Introduction -@chapter Introduction - -Todo lists, schedules, phone databases... everything we use databases -for is really just a way to extend the power of our memory, to be able -to remember what our conscious mind may not currently have access to. - -There are many different databases out there---and good ones---which -this mode is not trying to replace. Rather, it's how that data gets -there that's the question. Most of the time, we just want to say -``Remember so-and-so's phone number, or that I have to buy dinner for the -cats tonight.'' That's the FACT@. How it's stored is really the -computer's problem. But at this point in time, it's most definitely -also the user's problem, and sometimes so laboriously so that people -just let data slip, rather than expend the effort to record it. - -``Remember'' is a mode for remembering data. It uses whatever -back-end is appropriate to record and correlate the data, but its main -intention is to allow you to express as @emph{little} structure as -possible up front. If you later want to express more powerful -relationships between your data, or state assumptions that were at -first too implicit to be recognized, you can ``study'' the data later -and rearrange it. But the initial ``just remember this'' impulse -should be as close to simply throwing the data at Emacs as possible. - -Have you ever noticed that having a laptop to write on doesn't -@emph{actually} increase the amount of quality material that you turn -out, in the long run? Perhaps it's because the time we save -electronically in one way, we're losing electronically in another; the -tool should never dominate one's focus. As the mystic Faridu'd-Din -`Attar wrote: ``Be occupied as little as possible with things of the -outer world but much with things of the inner world; then right action -will overcome inaction.'' - -If Emacs could become a more intelligent data store, where brainstorming -would focus on the @emph{ideas} involved---rather than the structuring -and format of those ideas, or having to stop your current flow of work -in order to record them---it would map much more closely to how the mind -(well, at least mine) works, and hence would eliminate that very -manual-ness which computers from the very beginning have been championed -as being able to reduce. - -@node Implementation -@chapter Implementation - -Hyperbole, as a data presentation tool, always struck me as being very -powerful, but it seemed to require a lot of ``front-end'' work before -that data was really available. The problem with BBDB, or keeping up -a Bibl-mode file, is that you have to use different functions to -record the data, and it always takes time to stop what you're doing, -format the data in the manner expected by that particular data -interface, and then resume your work. - -With ``remember'', you just hit @kbd{M-x remember} (you'd probably -want to bind this to an easily accessible keystroke, like @kbd{C-x -M-r}), slam in your text however you like, and then hit @kbd{C-c C-c}. -It will file the data away for later retrieval, and possibly indexing. - -Indexing is to data what ``studying'' is in the real world. What you do -when you study (or lucubrate, for some of us) is to realize certain -relationships implicit in the data, so that you can make use of those -relationships. Expressing that a certain quote you remembered was a -literary quote, and that you want the ability to pull up all quotes of a -literary nature, is what studying does. This is a more labor intensive -task than the original remembering of the data, and it's typical in real -life to set aside a special period of time for doing this work. - -``Remember'' works in the same way. When you enter data, either by -typing it into a buffer, or using the contents of the selected region, -it will store that data---unindexed, uninterpreted---in a data pool. -It will also try to remember as much context information as possible -(any text properties that were set, where you copied it from, when, -how, etc.). Later, you can walk through your accumulated set of data -(both organized, and unorganized) and easily begin moving things -around, and making annotations that will express the full meaning of -that data, as far as you know it. - -Obviously this latter stage is more user-interface intensive, and it -would be nice if ``remember'' could do it as elegantly as possible, -rather than requiring a billion keystrokes to reorganize your -hierarchy. Well, as the future arrives, hopefully experience and user -feedback will help to make this as intuitive a tool as possible. - -@node Quick Start -@chapter Quick Start - -@itemize - -@item -Type @kbd{M-x remember}. The @file{*Remember*} buffer should be -displayed. - -@item -Type in what you want to remember. The first line will be treated as -the headline, and the rest of the buffer will contain the body of the -note. - -@item -Type @kbd{C-c C-c} (@code{remember-finalize}) to save the note and close -the @file{*Remember*} buffer. -@end itemize - -By default, @code{remember-finalize} saves the note in @file{~/emacs.d/notes}. -You can edit it now to see the remembered and timestamped note. You -can edit this file however you want. New entries will always be added -to the end. - -To remember a region of text, use the universal prefix. @kbd{C-u M-x -remember} displays a @file{*Remember*} buffer with the region as the -initial contents. - -As a simple beginning, you can start by using the Text File backend, -keeping your @file{~/.emacs.d/notes} file in outline-mode format, with a final -entry called @samp{* Raw data}. Remembered data will be added to the -end of the file. Every so often, you can move the data that gets -appended there into other files, or reorganize your document. - -You can also store remembered data in other backends. @xref{Backends}. - -Here is one way to map the remember functions in your init file -(@pxref{Init File, , The Emacs Initialization File, emacs, GNU Emacs -Manual}) to very accessible keystrokes facilities using the mode: - -@lisp -(define-key global-map (kbd " r") 'remember) -(define-key global-map (kbd " R") 'remember-region) -@end lisp - -@cindex annotation -By default, remember uses the first annotation returned by -@code{remember-annotation-functions}. To include all of the annotations, -set @code{remember-run-all-annotation-functions-flag} to a -non-@code{nil} value. - -@defopt remember-run-all-annotation-functions-flag -Non-@code{nil} means use all annotations returned by -@code{remember-annotation-functions}. -@end defopt - -You can write custom functions that use a different set of -remember-annotation-functions. For example: - -@lisp -(defun my/remember-with-filename () - "Always use the filename." - (interactive) - (let ((remember-annotation-functions '(buffer-file-name))) - (call-interactively 'remember))) -@end lisp - -@cindex notes -The @code{remember-notes} command creates a @dfn{notes} buffer that -visits the file specified by the option @code{remember-data-file}. -The option @code{remember-notes-buffer-name} specifies the name of the -buffer. The buffer uses @code{remember-notes-initial-major-mode} and -@code{remember-notes-mode} minor mode. Use @kbd{C-c C-c} to save -and bury the buffer. The command @code{save-some-buffers} saves this -buffer without asking. This function is a suitable setting for -@code{initial-buffer-choice}. - - -@node Function Reference -@chapter Function Reference - -@file{remember.el} defines the following interactive functions: - -@defun remember &optional initial -Remember an arbitrary piece of data. With a prefix, it will use the -region as @var{initial}. -@end defun - -@defun remember-other-frame &optional initial -Like @code{remember}, but uses a new frame. -@end defun - -@defun remember-region &optional beg end -If called from within the remember buffer, @var{beg} and @var{end} are -ignored, and the entire buffer will be remembered. If called from any -other buffer, that region, plus any context information specific to -that region, will be remembered. -@end defun - -@defun remember-clipboard -Remember the contents of the current clipboard. This is most useful -for remembering things from Netscape or other X Windows applications. -@end defun - -@defun remember-finalize -Remember the contents of the current buffer. -@end defun - -@defun remember-destroy -Destroy the current remember buffer. -@end defun - -@defun remember-mode -This enters the major mode (@pxref{Major Modes, , Major Modes, emacs, -GNU Emacs Manual}) for output from @code{remember}. This buffer is -used to collect data that you want remember. Just hit @kbd{C-c C-c} -when you're done entering, and it will go ahead and file the data for -latter retrieval, and possible indexing. -@end defun - -@defun remember-notes &optional switch-to -This returns the notes buffer, creating it if needed, and switches -to it if called interactively (or if @var{switch-to} is non-@code{nil}). -The notes buffer visits @code{remember-data-file}, and -is named @code{remember-notes-buffer-name}. It uses -@code{remember-notes-initial-major-mode} and @code{remember-notes-mode} -minor mode. -@end defun - -@defun remember-notes-mode &optional arg -This is a minor mode for the notes buffer. It sets -@code{buffer-save-without-query} so that @code{save-some-buffers} will -save the notes buffer without asking. Use @kbd{C-c C-c} to -run the command @code{remember-notes-save-and-bury-buffer}. -@end defun - -@defun remember-notes-save-and-bury-buffer -Save (if it is modified) and bury the current buffer. -@end defun - -@node Keystrokes -@chapter Keystroke Reference - -@file{remember.el} defines the following keybindings by default: - -@table @kbd - -@item C-c C-c -@itemx C-x C-s -Remember the contents of the current buffer (`remember-finalize'). - -@item C-c C-k -Destroy the current @file{*Remember*} buffer (`remember-destroy'). - -@end table - -@node Backends -@chapter Backends - -You can save remembered notes to a variety of backends. - -@menu -* Text File:: Saving to a text file. -* Separate Text Files:: Saving to separate text files. -* Diary:: Saving to a Diary file. -* Mailbox:: Saving to a mailbox. -* Org:: Saving to an Org Mode file. -@end menu - -@node Text File -@section Saving to a Text File -@cindex text file, saving to - -@subheading Insinuation - -@lisp -(setq remember-handler-functions '(remember-append-to-file)) -@end lisp - -@subheading Options - -@defopt remember-data-file -The file in which to store unprocessed data. -@end defopt - -@defopt remember-leader-text -The text used to begin each remember item. -@end defopt - - -@node Separate Text Files -@section Saving to Separate Text Files -@cindex text files, saving to separate - -@subheading Insinuation - -@lisp -(setq remember-handler-functions '(remember-store-in-files)) -@end lisp - -@subheading Options - -@defopt remember-data-directory -The directory in which to store remember data as files. -@end defopt - -@defopt remember-directory-file-name-format -A format string to use for naming files in the remember directory. -File names are formed by calling @code{format-time-string} at the time -of saving, using this format string. -@end defopt - - -@node Diary -@section Saving to a Diary file -@cindex diary, integration - -@subheading Insinuation - -@lisp -(add-to-list 'remember-handler-functions 'remember-diary-extract-entries) -@end lisp - -@subheading Options - -@defopt remember-diary-file -File for extracted diary entries. -If this is @code{nil}, then @code{diary-file} will be used instead. -@end defopt - -@node Mailbox -@section Saving to a Mailbox -@cindex mailbox, saving to - -@subheading Insinuation - -@lisp -(add-to-list 'remember-handler-functions 'remember-store-in-mailbox) -@end lisp - -@subheading Options - -@defopt remember-mailbox -The file in which to store remember data as mail. -@end defopt - -@defopt remember-default-priority -The default priority for remembered mail messages. -@end defopt - -@node Org -@section Saving to an Org Mode file -@cindex org mode, integration - -@ignore -From org.texi: -Up to version 6.36 Org used a special setup -for @file{remember.el}. @file{org-remember.el} is still part of Org mode for -backward compatibility with existing setups. You can find the documentation -for org-remember at @url{http://orgmode.org/org-remember.pdf}. -@end ignore -For instructions on how to integrate Remember with Org Mode, -consult @ref{Capture, , , org}. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Index - -@printindex cp - -@bye diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi deleted file mode 100644 index ce3300dcc5b..00000000000 --- a/doc/misc/sasl.texi +++ /dev/null @@ -1,276 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@include gnus-overrides.texi - -@setfilename ../../info/sasl - -@set VERSION 0.2 -@settitle Emacs SASL Library @value{VERSION} - -@documentencoding UTF-8 - -@copying -This file describes the Emacs SASL library, version @value{VERSION}. - -Copyright @copyright{} 2000, 2004--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* SASL: (sasl). The Emacs SASL library. -@end direntry - - -@titlepage -@ifset WEBHACKDEVEL -@title Emacs SASL Library @value{VERSION} (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Emacs SASL Library @value{VERSION} -@end ifclear - -@author by Daiki Ueno -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - - -@node Top -@top Emacs SASL - -SASL is a common interface to share several authentication mechanisms between -applications using different protocols. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: What Emacs SASL library is. -* How to use:: Adding authentication support to your applications. -* Data types:: -* Back end drivers:: Writing your own drivers. -* GNU Free Documentation License:: The license for this documentation. -* Index:: -* Function Index:: -* Variable Index:: -@end menu - -@node Overview -@chapter Overview - -@sc{sasl} is short for @dfn{Simple Authentication and Security Layer}. -This standard is documented in RFC2222. It provides a simple method for -adding authentication support to various application protocols. - -The toplevel interface of this library is inspired by Java @sc{sasl} -Application Program Interface. It defines an abstraction over a series -of authentication mechanism drivers (@ref{Back end drivers}). - -Back end drivers are designed to be close as possible to the -authentication mechanism. You can access the additional configuration -information anywhere from the implementation. - -@node How to use -@chapter How to use - -(Not yet written). - -To use Emacs SASL library, please evaluate following expression at the -beginning of your application program. - -@lisp -(require 'sasl) -@end lisp - -If you want to check existence of sasl.el at runtime, instead you -can list autoload settings for functions you want. - -@node Data types -@chapter Data types - -There are three data types to be used for carrying a negotiated -security layer---a mechanism, a client parameter and an authentication -step. - -@menu -* Mechanisms:: -* Clients:: -* Steps:: -@end menu - -@node Mechanisms -@section Mechanisms - -A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl} -authentication mechanism driver. - -@defvar sasl-mechanisms -A list of mechanism names. -@end defvar - -@defun sasl-find-mechanism mechanisms - -Retrieve an appropriate mechanism. -This function compares @var{mechanisms} and @code{sasl-mechanisms} then -returns appropriate @code{sasl-mechanism} object. - -@example -(let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5"))) - (setq mechanism (sasl-find-mechanism server-supported-mechanisms))) -@end example - -@end defun - -@defun sasl-mechanism-name mechanism -Return name of mechanism, a string. -@end defun - -If you want to write an authentication mechanism driver (@ref{Back end -drivers}), use @code{sasl-make-mechanism} and modify -@code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly. - -@defun sasl-make-mechanism name steps -Allocate a @code{sasl-mechanism} object. -This function takes two parameters---name of the mechanism, and a list -of authentication functions. - -@example -(defconst sasl-anonymous-steps - '(identity ;no initial response - sasl-anonymous-response)) - -(put 'sasl-anonymous 'sasl-mechanism - (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps)) -@end example - -@end defun - -@node Clients -@section Clients - -A client (@code{sasl-client} object) initialized with four -parameters---a mechanism, a user name, name of the service and name of -the server. - -@defun sasl-make-client mechanism name service server -Prepare a @code{sasl-client} object. -@end defun - -@defun sasl-client-mechanism client -Return the mechanism (@code{sasl-mechanism} object) of client. -@end defun - -@defun sasl-client-name client -Return the authorization name of client, a string. -@end defun - -@defun sasl-client-service client -Return the service name of client, a string. -@end defun - -@defun sasl-client-server client -Return the server name of client, a string. -@end defun - -If you want to specify additional configuration properties, please use -@code{sasl-client-set-property}. - -@defun sasl-client-set-property client property value -Add the given property/value to client. -@end defun - -@defun sasl-client-property client property -Return the value of the property of client. -@end defun - -@defun sasl-client-set-properties client plist -Destructively set the properties of client. -The second argument is the new property list. -@end defun - -@defun sasl-client-properties client -Return the whole property list of client configuration. -@end defun - -@node Steps -@section Steps - -A step (@code{sasl-step} object) is an abstraction of authentication -``step'' which holds the response value and the next entry point for the -authentication process (the latter is not accessible). - -@defun sasl-step-data step -Return the data which @var{step} holds, a string. -@end defun - -@defun sasl-step-set-data step data -Store @var{data} string to @var{step}. -@end defun - -To get the initial response, you should call the function -@code{sasl-next-step} with the second argument @code{nil}. - -@example -(setq name (sasl-mechanism-name mechanism)) -@end example - -At this point we could send the command which starts a SASL -authentication protocol exchange. For example, - -@example -(process-send-string - process - (if (sasl-step-data step) ;initial response - (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t)) - (format "AUTH %s\r\n" name))) -@end example - -To go on with the authentication process, all you have to do is call -@code{sasl-next-step} consecutively. - -@defun sasl-next-step client step -Perform the authentication step. -At the first time @var{step} should be set to @code{nil}. -@end defun - -@node Back end drivers -@chapter Back end drivers - -(Not yet written). - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@node Function Index -@unnumbered Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@summarycontents -@contents -@bye - -@c End: diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi deleted file mode 100644 index 83429a8e8e2..00000000000 --- a/doc/misc/sc.texi +++ /dev/null @@ -1,1926 +0,0 @@ -\input texinfo @comment -*-texinfo-*- -@comment 3.48 -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/sc -@settitle Supercite User's Manual -@documentencoding UTF-8 -@iftex -@finalout -@end iftex - -@c @setchapternewpage odd % For book style double sided manual. -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -This document describes Supercite, an Emacs package for citing and -attributing replies to mail and news messages. - -Copyright @copyright{} 1993, 2001--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@c @smallbook - -@dircategory Emacs network features -@direntry -* SC: (sc). Supercite lets you cite parts of messages - you're replying to, in flexible ways. -@end direntry - -@titlepage -@title Supercite User's Manual -@subtitle cite and attribute mail and -@subtitle news, in flexible ways - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@ifnottex -@node Top -@top Supercite - -@insertcopying - -The manual is divided -into the following chapters. - -@menu -* Introduction:: -* Citations:: -* Information Keys and the Info Alist:: -* Reference Headers:: -* Getting Connected:: -* Replying and Yanking:: -* Selecting an Attribution:: -* Configuring the Citation Engine:: -* Post-yank Formatting Commands:: -* Hints to MUA Authors:: -* Thanks and History:: - -* GNU Free Documentation License:: -* Concept Index:: -* Command Index:: -* Key Index:: -* Variable Index:: -@end menu -@end ifnottex - - -@node Introduction -@chapter Introduction - -@cindex MUA -@cindex NUA -Supercite is a GNU Emacs package written entirely in Emacs Lisp. It -interfaces to most of the commonly used Emacs mail user agents -(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides -sophisticated facilities for the citing and attributing of message -replies. Supercite has a very specific and limited role in the -process of composing replies to both USENET network news and -electronic mail. - -The preferred way to spell Supercite is with a capital @samp{S}, -lowercase @samp{upercite}. - -@menu -* Usage Overview:: -* What Supercite Does Not Do:: -* What Supercite Does:: -@end menu - -@c FIXME: move it above the menu? --xfq -Supercite is only useful in conjunction with MUAs and NUAs such as VM, -Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a -reply buffer has been setup. Thereafter, Supercite's many commands and -formatting styles are available in that reply buffer until the reply is -sent. Supercite is re-initialized in each new reply buffer. - - -@node Usage Overview -@section Usage Overview -@kindex r -@kindex f -@kindex C-c C-y -@cindex yank -@cindex cite, citing -@cindex attribute, attributing - -Typical usage is as follows. You want to reply or followup to a -message in your MUA@. You will probably hit @kbd{r} (i.e., ``reply'') -or @kbd{f} (i.e., ``forward'') to begin composing the reply. In -response, the MUA will create a reply buffer and initialize the -outgoing mail headers appropriately. The body of the reply will -usually be empty at this point. You now decide that you would like to -include part of the original message in your reply. To do this, you -@dfn{yank} the original message into the reply buffer, typically with -a key stroke such as @kbd{C-c C-y}. This sequence will invoke an -MUA-specific function which fills the body of the reply with the -original message and then @dfn{attributes} this text to its author. -This is called @dfn{citing} and its effect is to prefix every line -from the original message with a special text tag. Most MUAs provide -some default style of citing; by using Supercite you gain a wider -flexibility in the look and style of citations. Supercite's only job -is to cite the original message. - -@node What Supercite Does Not Do -@section What Supercite Doesn't Do - -Because of this clear division of labor, there are useful features which -are the sole responsibility of the MUA, even though it might seem that -Supercite should provide them. For example, many people would like to -be able to yank (and cite) only a portion of the original message. -Since Supercite only modifies the text it finds in the reply buffer as -set up by the MUA, it is the MUA's responsibility to do partial yanking. -@xref{Reply Buffer Initialization}. - -@vindex mail-header-separator -Another potentially useful thing would be for Supercite to set up the -outgoing mail headers with information it gleans from the reply buffer. -But by previously agreed upon convention, any text above the -@code{mail-header-separator} which separates mail headers from message -bodies cannot be modified by Supercite. Supercite, in fact, doesn't -know anything about the meaning of these headers, and never ventures -outside the designated region. @xref{Hints to MUA Authors}, for more -details. - -@node What Supercite Does -@section What Supercite Does -@findex sc-cite-original - -Supercite is invoked for the first time on a reply buffer via your MUA's -reply or forward command. This command will actually perform citations -by calling a hook variable to which Supercite's top-level function -@code{sc-cite-original} has been added. When @code{sc-cite-original} is -executed, the original message must be set up in a very specific way, -but this is handled automatically by the MUA@. @xref{Hints to MUA -Authors}. - -@cindex info alist -The first thing Supercite does, via @code{sc-cite-original}, is to parse -through the original message's mail headers. It saves this data in an -@dfn{information association list}, or @dfn{info alist}. The information -in this list is used in a number of places throughout Supercite. -@xref{Information Keys and the Info Alist}. - -@cindex nuking mail headers -@cindex reference header -After the mail header info is extracted, the headers are optionally -removed (@dfn{nuked}) from the reply. Supercite then writes a -@dfn{reference header} into the buffer. This reference header is a -string carrying details about the citation it is about to perform. - -@cindex modeline -Next, Supercite visits each line in the reply, transforming the line -according to a customizable ``script''. Lines which were not previously -cited in the original message are given a citation, while already cited -lines remain untouched, or are coerced to your preferred style. -Finally, Supercite installs a keymap into the reply buffer so that you -have access to Supercite's post-yank formatting and reciting commands as -you subsequently edit your reply. You can tell that Supercite has been -installed into the reply buffer because that buffer's modeline will -display the minor mode string @samp{SC}. - -@cindex filladapt -@cindex gin-mode -@vindex fill-prefix -@findex fill-paragraph -When the original message is cited by @code{sc-cite-original}, it will -(optionally) be filled by Supercite. However, if you manually edit the -cited text and want to re-fill it, you must use an add-on package such -as @cite{filladapt} or @cite{gin-mode}. These packages can recognize -Supercited text and will fill them appropriately. Emacs's built-in -filling routines, e.g., @code{fill-paragraph}, do not recognize cited -text and will not re-fill them properly because it cannot guess the -@code{fill-prefix} being used. -@xref{Post-yank Formatting Commands}, for details. - -As mentioned above, Supercite provides commands to recite or uncite -regions of text in the reply buffer, and commands to perform other -beautifications on the cited original text, maintaining consistent and -informative citations throughout. Supercite tries to be as configurable -as possible to allow for a wide range of personalized citation styles, -but it is also immediately useful with the default configuration, once -it has been properly connected to your MUA@. @xref{Getting Connected}, -for more details. - -@node Citations -@chapter Citations -@cindex nested citations -@cindex citation - -A @dfn{citation} is the acknowledgment of the original author of a mail -message in the body of the reply. There are two basic citation styles -which Supercite supports. The first, called @dfn{nested citations} is -an anonymous form of citation; in other words, an indication is made -that the cited line was written by someone @emph{other} that the current -message author (i.e., other than you, the person composing the reply), -but no reference is made as to the identity of the original author. -This style should look familiar since its use on the net is widespread. -Here's an example of what a message buffer would look like using nested -citations after multiple replies: - -@example ->> John originally wrote this ->> and this as well -> Jane said that John didn't know -> what he was talking about -And that's what I think too. -@end example - -@menu -* Citation Elements:: -* Recognizing Citations:: -@end menu - -Note that multiple inclusions of the original messages result in a -nesting of the @samp{@code{>}} characters. This can sometimes be quite -confusing when many levels of citations are included since it may be -difficult or impossible to figure out who actually participated in the -thread, and multiple nesting of @samp{@code{>}} characters can sometimes -make the message very difficult for the eye to scan. - -@cindex non-nested citations -In @dfn{non-nested citations}, each cited line begins with an -informative string attributing that line to the original author. Only -the first level of attribution will be shown; subsequent citations -don't nest the citation strings. The above dialog might look like -this when non-nested citations are used: - -@example -John> John originally wrote this -John> and this as well -Jane> Jane said that John didn't know -Jane> what he was talking about -And that's what I think too. -@end example - -Notice here that my inclusion of Jane's inclusion of John's original -message did not result in a line cited with @samp{Jane>John>}. - -@vindex sc-nested-citation-p -@vindex nested-citation-p (sc-) -Supercite supports both styles of citation, and the variable -@code{sc-nested-citation-p} controls which style it will use when -citing previously uncited text. When this variable is @code{nil} (the -default), non-nested citations are used. When non-@code{nil}, nested -citations are used. - - -@node Citation Elements -@section Citation Elements -@cindex citation string - -@dfn{Citation strings} are composed of one or more elements. -Non-nested citations are composed of four elements, three of which are -directly user definable. The elements are concatenated together, in -this order: - -@cindex citation leader -@vindex citation-leader (sc-) -@vindex sc-citation-leader -@enumerate -@item -The @dfn{citation leader}. The citation leader is contained in the -variable @code{sc-citation-leader}, and has the default value of a -string containing four spaces. - -@cindex attribution string -@item -The @dfn{attribution string}. This element is supplied automatically by -Supercite, based on your preferences and the original message's mail -headers, though you may be asked to confirm Supercite's choice. -@xref{Selecting an Attribution}, for more details. - -@cindex citation delimiter -@vindex sc-citation-delimiter -@vindex citation-delimiter (sc-) -@item -The @dfn{citation delimiter}. This string, contained in the variable -@code{sc-citation-delimiter} visually separates the citation from the -text of the line. This variable has a default value of @code{">"} and -for best results, the string should consist of only a single character. - -@cindex citation separator -@vindex citation-separator (sc-) -@vindex sc-citation-separator -@item -The @dfn{citation separator}. The citation separator is contained in -the variable @code{sc-citation-separator}, and has the default value of -a string containing a single space. -@end enumerate - -For example, suppose you were using the default values for the above -variables, and Supercite provided the attribution string @samp{Jane}. -In this case, the composed, non-nested citation string used might be -something like -@code{@asis{" Jane> "}}. -This citation string will be inserted in front of -every line in the original message that is not already cited. - -Nested citations, being simpler than non-nested citations, are composed -of the same elements, sans the attribution string. Supercite is smart -enough to not put additional spaces between citation delimiters for -multi-level nested citations. - -@node Recognizing Citations -@section Recognizing Citations - -Supercite also recognizes citations in the original article, and can -transform these already cited lines in a number of ways. This is how -Supercite suppresses the multiple citing of non-nested citations. -Recognition of cited lines is controlled by variables analogous to -those that make up the citation string as mentioned previously. - -@vindex sc-citation-leader-regexp -@vindex citation-leader-regexp (sc-) -@vindex sc-citation-delimiter-regexp -@vindex citation-delimiter-regexp (sc-) -@vindex sc-citation-separator-regexp -@vindex citation-separator-regexp (sc-) -@vindex sc-citation-root-regexp -@vindex citation-root-regexp (sc-) -@vindex sc-citation-nonnested-root-regexp -@vindex citation-nonnested-root-regexp (sc-) - -The variable @code{sc-citation-leader-regexp} describes how citation -leaders can look, by default it matches any number of spaces or tabs. -Note that since the lisp function @code{looking-at} is used to do the -matching, if you change this variable it need not start with a leading -@code{"^"}. - -Similarly, the variables @code{sc-citation-delimiter-regexp} and -@code{sc-citation-separator-regexp} respectively describe how citation -delimiters and separators can look. They follow the same rule as -@code{sc-citation-leader-regexp} above. - -When Supercite composes a citation string, it provides the attribution -automatically. The analogous variable which handles recognition of the -attribution part of citation strings is @code{sc-citation-root-regexp}. -This variable describes the attribution root for both nested and -non-nested citations. By default it can match zero-to-many alphanumeric -characters (also ``.'', ``-'', and ``_''). But in some situations, -Supercite has to determine whether it is looking at a nested or -non-nested citation. Thus the variable -@code{sc-citation-nonnested-root-regexp} is used to describe only -non-nested citation roots. It is important to remember that if you -change @code{sc-citation-root-regexp} you should always also change -@code{sc-citation-nonnested-root-regexp}. - -@node Information Keys and the Info Alist -@chapter Information Keys and the Info Alist -@cindex information keys -@cindex Info Alist -@cindex information extracted from mail fields -@findex sc-mail-field -@findex mail-field (sc-) - -@dfn{Mail header information keys} are nuggets of information that -Supercite extracts from the various mail headers of the original -message, placed in the reply buffer by the MUA@. Information is kept -in the @dfn{Info Alist} as key-value pairs, and can be retrieved for -use in various places within Supercite, such as in header rewrite -functions and attribution selection. Other bits of data, composed and -created by Supercite, are also kept as key-value pairs in this alist. -In the case of mail fields, the key is the name of the field, omitting -the trailing colon. Info keys are always case insensitive (as are -mail headers), and the value for a corresponding key can be retrieved -from the alist with the @code{sc-mail-field} function. Thus, if the -following fields were present in the original article: - -@example -Date:@: 08 April 1991, 17:32:09 EST -Subject:@: Better get out your asbestos suit -@end example - -@vindex sc-mumble -@vindex mumble (sc-) -@noindent -then, the following lisp constructs return: - -@example -(sc-mail-field "date") -==> "08 April 1991, 17:32:09 EST" - -(sc-mail-field "subject") -==> "Better get out your asbestos suit" -@end example - -Since the argument to @code{sc-mail-field} can be any string, it is -possible that the mail field will not be present on the info alist -(possibly because the mail header was not present in the original -message). In this case, @code{sc-mail-field} will return the value of -the variable @code{sc-mumble}. - -Supercite always places all mail fields found in the yanked original -article into the info alist. If possible, Supercite will also places -the following keys into the info alist: - -@table @code -@cindex sc-attribution info field -@cindex attribution info field (sc-) -@item "sc-attribution" -the selected attribution string. - -@cindex sc-citation info field -@cindex citation info field (sc-) -@item "sc-citation" -the non-nested citation string. - -@cindex sc-from-address info field -@cindex from-address info field (sc-) -@item "sc-from-address" -email address extracted from the @samp{From:@:} field. - -@cindex sc-reply-address info field -@cindex reply-address info field (sc-) -@item "sc-reply-address" -email address extracted from the @samp{Reply-To:@:} field. - -@cindex sc-sender-address info field -@cindex sender-address info field (sc-) -@item "sc-sender-address" -email address extracted from the @samp{Sender:@:} field. - -@cindex sc-emailname info field -@cindex emailname info field (sc-) -@item "sc-emailname" -email terminus extracted from the @samp{From:@:} field. - -@cindex sc-initials info field -@cindex initials info field (sc-) -@item "sc-initials" -the author's initials. - -@cindex sc-author info field -@cindex author info field (sc-) -@item "sc-author" -the author's full name. - -@cindex sc-firstname info field -@cindex firstname info field (sc-) -@item "sc-firstname" -the author's first name. - -@cindex sc-lastname info field -@cindex lastname info field (sc-) -@item "sc-lastname" -the author's last name. - -@cindex sc-middlename-1 info field -@cindex middlename-1 info field (sc-) -@item "sc-middlename-1" -the author's first middle name. -@end table - -If the author's name has more than one middle name, they will appear as -info keys with the appropriate index (e.g., @code{"sc-middlename-2"}, -@dots{}). @xref{Selecting an Attribution}. - -@node Reference Headers -@chapter Reference Headers -@cindex reference headers - -Supercite will insert an informative @dfn{reference header} at the -beginning of the cited body of text, which display more detail about the -original article and provides the mapping between the attribution and -the original author in non-nested citations. Whereas the citation -string usually only contains a portion of the original author's name, -the reference header can contain such information as the author's full -name, email address, the original article's subject, etc. In fact any -information contained in the info alist can be inserted into a reference -header. - -@menu -* The Built-in Header Rewrite Functions:: -* Electric References:: -@end menu - -@cindex header rewrite functions -@vindex sc-rewrite-header-list -@vindex rewrite-header-list (sc-) -There are a number of built-in @dfn{header rewrite functions} supplied -by Supercite, but you can write your own custom header rewrite -functions (perhaps using the built-in ones as examples). The variable -@code{sc-rewrite-header-list} contains the list of such header rewrite -functions. This list is consulted both when inserting the initial -reference header, and when displaying @dfn{electric references}. -@xref{Electric References}. - -@vindex sc-preferred-header-style -@vindex preferred-header-style (sc-) -When Supercite is initially run on a reply buffer (via -@code{sc-cite-original}), it will automatically call one of these -functions. The one it uses is defined in the variable -@code{sc-preferred-header-style}. The value of this variable is an -integer which is an index into the @code{sc-rewrite-header-list}, -beginning at zero. - -@node The Built-in Header Rewrite Functions -@section The Built-in Header Rewrite Functions -@cindex header rewrite functions, built-in - -Below are examples of the various built-in header rewrite functions. -Please note the following: first, the text which appears in the -examples below as @var{infokey} indicates that the corresponding value -of the info key from the info alist will be inserted there. -(@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said} -below, @var{date} and @var{from} correspond to the values of the -@samp{Date:@:} and @samp{From:@:} mail headers respectively. - -@vindex sc-reference-tag-string -@vindex reference-tag-string (sc-) -Also, the string @code{">>>>>"} below is really the value of the -variable @code{sc-reference-tag-string}. This variable is used in all -built-in header rewrite functions, and you can customize its value to -change the tag string globally. - -Finally, the references headers actually written may omit certain parts -of the header if the info key associated with @var{infokey} is not -present in the info alist. In fact, for all built-in headers, if the -@samp{From:@:} field is not present in the mail headers, the entire -reference header will be omitted (but this usually signals a serious -problem either in your MUA or in Supercite's installation). - -@table @code -@findex sc-no-header -@findex no-header (sc-) -@item sc-no-header -This function produces no header. It should be used instead of -@code{nil} to produce a blank header. This header can possibly -contain a blank line after the @code{mail-header-separator} line. - -@item sc-no-blank-line-or-header -@findex sc-no-blank-line-or-header -@findex no-blank-line-or-header (sc-) -This function is similar to @code{sc-no-header} except that any blank -line after the @code{mail-header-separator} line will be removed. - -@item sc-header-on-said -@findex sc-header-on-said -@findex header-on-said (sc-) -@code{>>>>> On @var{date}, @var{from} said:} - -@item sc-header-inarticle-writes -@findex sc-header-inarticle-writes -@findex header-inarticle-writes (sc-) -@code{>>>>> In article @var{message-id}, @var{from} writes:} - -@item sc-header-regarding-adds -@findex sc-header-regarding-adds -@findex header-regarding-adds (sc-) -@code{>>>>> Regarding @var{subject}; @var{from} adds:} - -@item sc-header-attributed-writes -@findex sc-header-attributed-writes -@findex header-attributed-writes (sc-) -@code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:} - -@item sc-header-author-writes -@findex sc-header-author-writes -@findex header-author-writes (sc-) -@code{>>>>> @var{sc-author} writes:} - -@item sc-header-verbose -@findex sc-header-verbose -@findex header-verbose (sc-) -@code{>>>>> On @var{date},}@* -@code{>>>>> @var{sc-author}}@* -@code{>>>>> from the organization of @var{organization}}@* -@code{>>>>> who can be reached at:@: @var{sc-reply-address}}@* -@code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@* -@code{>>>>> had this to say in article @var{message-id}}@* -@code{>>>>> in newsgroups @var{newsgroups}}@* -@code{>>>>> concerning the subject of @var{subject}}@* -@code{>>>>> see @var{references} for more details} -@end table - -@node Electric References -@section Electric References -@cindex electric references - -By default, when Supercite cites the original message for the first -time, it just goes ahead and inserts the reference header indexed by -@code{sc-preferred-header-style}. However, you may want to select -different reference headers based on the type of reply or forwarding -you are doing. You may also want to preview the reference header -before deciding whether to insert it into the reply buffer or -not. Supercite provides an optional @dfn{electric reference} mode -which you can drop into to give you this functionality. - -@vindex sc-electric-references-p -@vindex electric-references-p (sc-) -If the variable @code{sc-electric-references-p} is non-@code{nil}, -Supercite will bring up an electric reference mode buffer and place you -into a recursive edit. The electric reference buffer is read-only, so -you cannot directly modify the reference text until you exit electric -references and insert the text into the reply buffer. But you can cycle -through all the reference header rewrite functions in your -@code{sc-rewrite-header-list}. - -You can also set a new preferred header style, jump to any header, or -jump to the preferred header. The header will be shown in the electric -reference buffer and the header index and function name will appear in -the echo area. - -The following commands are available while in electric reference mode -(shown here with their default key bindings): - -@table @asis -@item @code{sc-eref-next} (@kbd{n}) -@findex sc-eref-next -@findex eref-next (sc-) -@kindex n -@vindex sc-electric-circular-p -@vindex electric-circular-p (sc-) -Displays the next reference header in the electric reference buffer. If -the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking -@code{sc-eref-next} while viewing the last reference header in the list -will wrap around to the first header. - -@item @code{sc-eref-prev} (@kbd{p}) -@findex sc-eref-prev -@findex eref-prev (sc-) -@kindex p -Displays the previous reference header in the electric reference buffer. -If the variable @code{sc-electric-circular-p} is non-@code{nil}, -invoking @code{sc-eref-prev} will wrap around to the last header. - -@item @code{sc-eref-goto} (@kbd{g}) -@findex sc-eref-goto -@findex eref-goto (sc-) -@kindex g -Goes to a specified reference header. The index (into the -@code{sc-rewrite-header-list}) can be specified as a numeric argument to -the command. Otherwise, Supercite will query you for the index in the -minibuffer. - -@item @code{sc-eref-jump} (@kbd{j}) -@findex sc-eref-jump -@findex eref-jump (sc-) -@kindex j -Display the preferred reference header, i.e., the one indexed by the current -value of @code{sc-preferred-header-style}. - -@item @code{sc-eref-setn} (@kbd{s}) -@findex sc-eref-setn -@findex eref-setn (sc-) -@kindex s -Set the preferred reference header (i.e., -@code{sc-preferred-header-style}) to the currently displayed header. - -@item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c}) -@kindex RET -@kindex C-j -@kindex q -@findex sc-eref-exit -@findex eref-exit (sc-) -Exit from electric reference mode and insert the current header into the -reply buffer. - -@item @code{sc-eref-abort} (@kbd{q}, @kbd{x}) -@findex sc-eref-abort -@findex eref-abort (sc-) -@kindex x -Exit from electric reference mode without inserting the current header. -@end table - -@vindex sc-electric-mode-hook -@vindex electric-mode-hook (sc-) -@noindent -Supercite will execute the hook @code{sc-electric-mode-hook} before -entering electric reference mode. - -@node Getting Connected -@chapter Getting Connected -@cindex citation interface specification - -@vindex mail-citation-hook -@cindex .emacs file -In most cases, all that is necessary to begin using Supercite is to add -the following to @file{~.emacs}: - -@example -(add-hook 'mail-citation-hook 'sc-cite-original) -@end example - -@noindent For more details of the process, read on@dots{} - -Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the -original message into the reply buffer. In reality, the citation of the -original message is performed via a call through a configurable hook -variable. The name of this variable has been agreed to in advance as -part of the @dfn{citation interface specification}. By default this -hook variable has a @code{nil} value, which the MUA recognizes to mean, -``use your default citation function.'' When you add Supercite's -citation function to the hook, thereby giving the variable a -non-@code{nil} value, it tells the MUA to run the hook via -@code{run-hooks} instead of using the default citation. - -Early in Supercite's development, the Supercite author, a few MUA -authors, and some early Supercite users got together and agreed upon a -standard interface between MUAs and citation packages (of which -Supercite is currently the only known add-on @t{:-)}. Supercite can -probably be used with most Emacs MUAs, with a greater or lesser degree -of effort. - -To learn exactly how to connect Supercite to the software systems you -are using, read the appropriate following sections. For details on the -interface specifications, or if you are writing or maintaining an MUA, -@pxref{Hints to MUA Authors}. - -@cindex autoload -@cindex .emacs file -@findex sc-cite-original -@findex cite-original (sc-) -The first thing that everyone should do, regardless of the MUA you are -using is to set up Emacs so it will load Supercite at the appropriate -time. This happens automatically if Supercite is distributed with your -Emacs version. If not, you can set up an @dfn{autoload} for Supercite. - -To do the latter, put the following in your @file{.emacs} file: - -@example -(autoload 'sc-cite-original "supercite" nil t) -@end example - -@cindex point -@cindex mark -The function @code{sc-cite-original} is the top-level Supercite function -designed to be run from the citation hook. It expects -@samp{point} and @samp{mark} to be set around the region to cite, and it -expects the original article's mail headers to be present within this -region. Note that Supercite @emph{never} touches any text outside this -region. Note further that the region need not be active -for @code{sc-cite-original} to do its job. -@xref{Hints to MUA Authors}. - -The other step in the getting connected process is to make sure your -MUA calls @code{sc-cite-original} at the right time. As mentioned -above, some MUAs handle this differently. Read the sections that follow -pertaining to the MUAs you are using. - -@vindex sc-load-hook -@vindex load-hook (sc-) -@vindex sc-pre-hook -@vindex pre-hook (sc-) -One final note. After Supercite is loaded into your Emacs session, it -runs the hook @code{sc-load-hook}. You can put any customizations into -this hook since it is only run once. This will not work, however, if -your Emacs maintainer has put Supercite into your dumped Emacs image. -In that case, you can use the @code{sc-pre-hook} variable, but this will -get executed every time @code{sc-cite-original} is called. @xref{Reply -Buffer Initialization}. - -@node Replying and Yanking -@chapter Replying and Yanking - -This chapter explains what happens when you reply and yank an original -message from an MUA. - -@menu -* Reply Buffer Initialization:: -* Filling Cited Text:: -@end menu - -@node Reply Buffer Initialization -@section Reply Buffer Initialization -@findex sc-cite-original -@findex cite-original (sc-) - -Executing @code{sc-cite-original} performs the following steps as it -initializes the reply buffer: - -@enumerate -@item -@vindex sc-pre-hook -@vindex pre-hook (sc-) -@emph{Runs @code{sc-pre-hook}.} -This hook variable is run before @code{sc-cite-original} does any other -work. You could conceivably use this hook to set certain Supercite -variables based on the reply buffer's mode or name (i.e., to do -something different based on whether you are replying or following up to -an article). - -@item -@emph{Inserts Supercite's keymap.} -@vindex sc-mode-map-prefix -@vindex mode-map-prefix (sc-) -@kindex C-c C-p -@cindex keymap prefix -Supercite provides a number of commands for performing post-yank -modifications to the reply buffer. These commands are installed on -Supercite's top-level keymap. Since Supercite has to interface with a -wide variety of MUAs, it does not install all of its commands directly -into the reply buffer's keymap. Instead, it puts its commands on a -keymap prefix, then installs this prefix onto the buffer's keymap. What -this means is that you typically have to type more characters to invoke -a Supercite command, but Supercite's key bindings can be made much more -consistent across MUAs. - -You can control what key Supercite uses as its keymap prefix by changing -the variable @code{sc-mode-map-prefix}. By default, this variable is -set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the -best default due to the scarcity of available key bindings in many MUAs. - -@item -@emph{Turns on Supercite minor mode.} -@cindex modeline -The modeline of the reply buffer should indicate that Supercite is -active in that buffer by displaying the string @samp{SC}. - -@item -@emph{Sets the ``Undo Boundary.''} -@cindex undo boundary -Supercite sets an undo boundary before it begins to modify the original -yanked text. This allows you to easily undo Supercite's changes to -affect alternative citing styles. - -@item -@emph{Processes the mail headers.} -@vindex sc-confirm-always-p -@vindex confirm-always-p (sc-) -@vindex sc-mail-warn-if-non-rfc822-p -@vindex mail-warn-if-non-rfc822-p (sc-) -All previously retrieved info key-value pairs are deleted from the info -alist, then the mail headers in the body of the yanked message are -scanned. Info key-value pairs are created for each header found. Also, -such useful information as the author's name and email address are -extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is -non-@code{nil}, then Supercite will warn you if it finds a mail header -that does not conform to RFC822. This is rare and indicates a problem -either with your MUA or the original author's MUA, or some MTA (mail -transport agent) along the way. - -@vindex sc-nuke-mail-headers -@vindex sc-nuke-mail-header-list -@vindex nuke-mail-headers (sc-) -@vindex nuke-mail-header-list (sc-) -Once the info keys have been extracted from the mail headers, the -headers are nuked from the reply buffer. You can control exactly which -headers are removed or kept, but by default, all headers are removed. - -There are two variables which control mail header nuking. The variable -@code{sc-nuke-mail-headers} controls the overall behavior of the header -nuking routines. By setting this variable to @code{'all}, you -automatically nuke all mail headers. Likewise, setting this variable to -@code{'none} inhibits nuking of any mail headers. In between these -extremes, you can tell Supercite to nuke only a specified list of mail -headers by setting this variable to @code{'specified}, or to keep only a -specified list of headers by setting it to @code{'keep}. - -If @code{sc-nuke-mail-headers} is set to @code{'specified} or -@code{'keep}, then the variable @code{sc-nuke-mail-header-list} is -consulted for the list of headers to nuke or keep. This variable -contains a list of regular expressions. If the mail header line matches -a regular expression in this list, the header will be nuked or kept. -The line is matched against the regexp using @code{looking-at} rooted at -the beginning of the line. - -@vindex sc-blank-lines-after-headers -@vindex blank-lines-after-headers (sc-) -If the variable @code{sc-blank-lines-after-headers} is non-@code{nil}, -it contains the number of blank lines remaining in the buffer after mail -headers are nuked. By default, only one blank line is left in the buffer. - -@item -@emph{Selects the attribution and citation strings.} -Once the mail headers have been processed, Supercite selects a -attribution string and a citation string which it will use to cite the -original message. @xref{Selecting an Attribution}, for details. - -@item -@emph{Cites the message body.} -@vindex sc-cite-region-limit -@vindex cite-region-limit (sc-)b -After the selection of the attribution and citation strings, Supercite -cites the original message by inserting the citation string prefix in -front of every uncited line. You may not want Supercite to -automatically cite very long messages however. For example, some email -could contain a smaller header section followed by a huge uuencoded -message. It wouldn't make sense to cite the uuencoded message part when -responding to the original author's short preface. For this reason, -Supercite provides a variable which limits the automatic citation of -long messages to a certain maximum number of lines. The variable is -called @code{sc-cite-region-limit}. If this variable contains an -integer, messages with more lines that this will not be cited at all, -and a warning message will be displayed. Supercite has performed -everything necessary, though, for you to manually cite only the small -portion of the original message that you want to use. - -If @code{sc-cite-region-limit} contains a non-@code{nil} value, the -original message will always be cited, regardless of its size. If the -variable contains the value @code{nil}, the region will never be cited -automatically. Use this if you always want to be able to edit and cite -the message manually. - -@vindex sc-cite-blank-lines-p -@vindex cite-blank-lines-p (sc-) -The variable @code{sc-cite-blank-lines-p} controls whether blank lines -in the original message should be cited or not. If this variable is -non-@code{nil}, blank lines will be cited just like non-blank lines. -Otherwise, blank lines will be treated as paragraph separators. - -Citing of the original message is highly configurable. Supercite's -default setup does a pretty good job of citing many common forms of -previously cited messages. But there are as many citation styles out -there as people on the net, or just about! It would be impossible for -Supercite to anticipate every style in existence, and you probably -wouldn't encounter them all anyway. But you can configure Supercite to -recognize those styles you see often. -@xref{Configuring the Citation Engine}, for details. - -@item -@emph{Runs @code{sc-post-hook}.} -@vindex sc-post-hook -@vindex post-hook (sc-) -This variable is very similar to @code{sc-pre-hook}, except that it runs -after @code{sc-cite-original} is finished. This hook is provided mostly -for completeness and backward compatibility. Perhaps it could be used to -reset certain variables set in @code{sc-pre-hook}. -@end enumerate - -@node Filling Cited Text -@section Filling Cited Text -@cindex filling paragraphs -@vindex sc-auto-fill-region-p -@vindex auto-fill-region-p (sc-) -@cindex filladapt -@cindex gin-mode -@findex sc-setup-filladapt -@findex setup-filladapt (sc-) -@vindex sc-load-hook -@vindex load-hook (sc-) - -Supercite will automatically fill newly cited text from the original -message unless the variable @code{sc-auto-fill-region-p} has a -@code{nil} value. Supercite will also re-fill paragraphs when you -manually cite or re-cite text. - -However, during normal editing, Supercite itself cannot be used to fill -paragraphs. This is a change from version 2. There are other add-on -lisp packages which do filling much better than Supercite ever did. The -two best known are @dfn{filladapt} and @dfn{gin-mode}. Both work well -with Supercite and both are available at the normal Emacs Lisp archive -sites. @dfn{gin-mode} works pretty well out of the box, but if you use -@dfn{filladapt}, you may want to run the function -@code{sc-setup-filladapt} from your @code{sc-load-hook}. This simply -makes @dfn{filladapt} a little more Supercite savvy than its default -setup. - -@vindex sc-fixup-whitespace-p -@vindex fixup-whitespace-p (sc-) -Also, Supercite will collapse leading whitespace between the citation -string and the text on a line when the variable -@code{sc-fixup-whitespace-p} is non-@code{nil}. The default value for -this variable is @code{nil}. - -@vindex fill-prefix -Its important to understand that Supercite's automatic filling (during -the initial citation of the reply) is very fragile. That is because -figuring out the @code{fill-prefix} for a particular paragraph is a -really hard thing to do automatically. This is especially the case when -the original message contains code or some other text where leading -whitespace is important to preserve. For this reason, many Supercite -users typically run with @code{sc-auto-fill-region-p} (and possibly also -@code{sc-fixup-whitespace-p}) set to @code{nil}. They then manually -fill each cited paragraph in the reply buffer. - -I usually run with both these variables containing their default values. -When Supercite's automatic filling breaks on a particular message, I -will use Emacs's undo feature to undo back before the citation was -applied to the original message. Then I'll toggle the variables and -manually cite those paragraphs that I don't want to fill or collapse -whitespace on. @xref{Variable Toggling Shortcuts}. - -@kindex C-c C-p C-p -If you find that Supercite's automatic filling is just too fragile for -your tastes, you might consider one of these alternate approaches. -Also, to make life easier, a shortcut function to toggle the state of -both of these variables is provided on the key binding -@kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix}; -@pxref{Post-yank Formatting Commands}). - -You will noticed that the minor mode string will -show the state of these variables as qualifier characters. When both -variables are @code{nil}, the Supercite minor mode string will display -@samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the -string will display @samp{SC:f}, and when just -@code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display -@samp{SC:w}. When both variables are non-@code{nil}, the string will -display @samp{SC:fw}. Note that the qualifiers chosen are mnemonics for -the default bindings of the toggling function for each respective -variable. -@xref{Variable Toggling Shortcuts}. - -Why are these variables not set to @code{nil} by default? It is because -many users won't manually fill paragraphs that are Supercited, and there -have been widespread complaints on the net about mail and news messages -containing lines greater than about 72 characters. So the default is to -fill cited text. - -@node Selecting an Attribution -@chapter Selecting an Attribution -@cindex attribution list -@vindex sc-preferred-attribution-list -@vindex preferred-attribution-list (sc-) - -As you know, the attribution string is the part of the author's name -that will be used to composed a non-nested citation string. Supercite -scans the various mail headers present in the original article and uses -a number of heuristics to extract strings which it puts into the -@dfn{attribution association list} or @dfn{attribution alist}. This is -analogous, but different than, the info alist previously mentioned. Each -element in the attribution alist is a key-value pair containing such -information as the author's first name, middle names, and last name, the -author's initials, and the author's email terminus. - -@menu -* Attribution Preferences:: -* Anonymous Attributions:: -* Author Names:: -@end menu - -@node Attribution Preferences -@section Attribution Preferences - -When you cite an original message, you can tell Supercite which part of -the author's name you would prefer it to use as the attribution. The -variable @code{sc-preferred-attribution-list} controls this; it contains -keys which are matched against the attribution alist in the given order. -The first value of a key that produces a non-@code{nil}, non-empty -string match is used as the attribution string, and if no keys match, a -secondary mechanism is used to generate the attribution. -@xref{Anonymous Attributions}. - -The following preferences are always available in the attribution alist -(barring error): - -@table @code -@item "emailname" -the author's email terminus. - -@item "initials" -the author's initials. - -@item "firstname" -the author's first name. - -@item "lastname" -the author's last name. - -@item "middlename-1" -the author's first middle name. - -@item "sc-lastchoice" -the last attribution string you have selected. This is useful when you -recite paragraphs in the reply. - -@item "sc-consult" -@vindex sc-attrib-selection-list -@vindex attrib-selection-list (sc-) -consults the customizable list @code{sc-attrib-selection-list} which can -be used to select special attributions based on the value of any info -key. See below for details. - -@item "x-attribution" -the original author's suggestion for attribution string choice. See below -for details. -@end table - -Middle name indexes can be any positive integer greater than zero, -though it is unlikely that many authors will have more than one middle -name, if that many. - -At this point, let me digress into a discussion of etiquette. It is my -belief that while the style of the citations is a reflection of the -personal tastes of the replier (i.e., you), the attribution selection is -ultimately the personal choice of the original author. In a sense it is -his or her ``net nickname'', and therefore the author should have some -say in the selection of attribution string. Imagine how you would feel -if someone gave you a nickname that you didn't like? - -For this reason, Supercite recognizes a special mail header, -@samp{X-Attribution:}, which if present, tells Supercite the attribution -string preferred by the original author. It is the value of this header -that is associated with the @code{"x-attribution"} key in the -attribution alist. Currently, you can override the preference of this -key by changing @code{sc-preferred-attribution-list}, but that isn't -polite, and in the future Supercite may hard-code this. For now, it is -suggested that if you change the order of the keys in this list, that -@code{"x-attribution"} always be first, or possible second behind only -@code{"sc-lastchoice"}. This latter is the default. - -@vindex sc-attrib-selection-list -@vindex attrib-selection-list (sc-) -The value @code{"sc-consult"} in @code{sc-preferred-attribution-list} -has a special meaning during attribution selection. When Supercite -encounters this preference, it begins processing a customizable list of -attributions, contained in the variable @code{sc-attrib-selection-list}. -Each element in this list contains lists of the following form: - -@example -@group -(@var{infokey} ((@var{regexp} . @var{attribution}) - (@var{regexp} . @var{attribution}) - (@dots{}))) -@end group -@end example - -@noindent -@findex sc-mail-field -@findex mail-field (sc-) -where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp} -is a regular expression to match against the @var{infokey}'s value. If -@var{regexp} matches the @var{infokey}'s value, the @var{attribution} is -used as the attribution string. Actually, @var{attribution} can be a -string or a list; if it is a list, it is @code{eval}uated and the return -value (which must be a string), is used as the attribution. - -This can be very useful for when you are replying to net acquaintances -who do not use the @samp{X-Attribution:@:} mail header. You may know -what nickname they would prefer to use, and you can set up this list to -match against a specific mail field, e.g., @samp{From:@:}, allowing you -to cite your friend's message with the appropriate attribution. - -@node Anonymous Attributions -@section Anonymous Attributions -@vindex sc-default-author-name -@vindex default-author-name (sc-) -@vindex sc-default-attribution -@vindex default-attribution (sc-) - -When the author's name cannot be found in the @samp{From:@:} mail -header, a fallback author name and attribution string must be supplied. -The fallback author name is contained in the variable -@code{sc-default-author-name} and the fallback attribution string is -contained in the variable @code{sc-default-attribution}. Default values -for these variables are @code{"Anonymous"} and @code{"Anon"}, -respectively. Note that in most circumstances, getting the default -author name or attribution is a sign that something is set up -incorrectly. - -@vindex sc-use-only-preference-p -@vindex use-only-preference-p (sc-) -Also, if the preferred attribution, which you specified in your -@code{sc-preferred-attribution-list} variable cannot be found, a -secondary method can be employed to find a valid attribution string. The -variable @code{sc-use-only-preference-p} controls what happens in this -case. If the variable's value is non-@code{nil}, then -@code{sc-default-author-name} and @code{sc-default-attribution} are -used, otherwise, the following steps are taken to find a valid -attribution string, and the first step to return a non-@code{nil}, -non-empty string becomes the attribution: - -@enumerate -@item -Use the last selected attribution, if there is one. - -@item -Use the value of the @code{"x-attribution"} key. - -@item -Use the author's first name. - -@item -Use the author's last name. - -@item -Use the author's initials. - -@item -Find the first non-@code{nil}, non-empty attribution string in the -attribution alist. - -@item -@code{sc-default-attribution} is used. -@end enumerate - -@vindex sc-confirm-always-p -@vindex confirm-always-p (sc-) -Once the attribution string has been automatically selected, a number of -things can happen. If the variable @code{sc-confirm-always-p} is -non-@code{nil}, you are queried for confirmation of the chosen -attribution string. The possible values for completion are those strings -in the attribution alist, however you are not limited to these choices. -You can type any arbitrary string at the confirmation prompt. The string -you enter becomes the value associated with the @code{"sc-lastchoice"} -key in the attribution alist. - -@vindex sc-downcase-p -@vindex downcase-p (sc-) -Once an attribution string has been selected, Supercite will force the -string to lower case if the variable @code{sc-downcase-p} is -non-@code{nil}. - -@vindex sc-attribs-preselect-hook -@vindex attribs-preselect-hook (sc-) -@vindex sc-attribs-postselect-hook -@vindex attribs-postselect-hook (sc-) - -Two hook variables provide even greater control of the attribution -selection process. The hook @code{sc-attribs-preselect-hook} is run -before any attribution is selected. Likewise, the hook -@code{sc-attribs-postselect-hook} is run after the attribution is -selected (and the corresponding citation string is built), but before -these values are committed for use by Supercite. During the -post-selection hook, the local variables @code{attribution} and -@code{citation} are bound to the appropriate strings. By changing these -variables in your hook functions, you change the attribution and -citation strings used by Supercite. One possible use of this would be -to override any automatically derived attribution string when it is only -one character long; e.g., you prefer to use @code{"initials"} but the -author only has one name. - -@node Author Names -@section Author Names -@cindex author names - -Supercite employs a number of heuristics to decipher the author's name -based on value of the @samp{From:@:} mail field of the original message. -Supercite can recognize almost all of the common @samp{From:@:} field -formats in use. If you encounter a @samp{From:@:} field that Supercite -cannot parse, please report this bug using @kbd{M-x report-emacs-bug}. - -@vindex sc-titlecue-regexp -@vindex titlecue-regexp (sc-) -There are a number of Supercite variables that control how author names -are extracted from the @samp{From:@:} header. Some headers may contain a -descriptive title as in: - -@example -From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker) -@end example - -Supercite knows which part of the @samp{From:@:} header is email address -and which part is author name, but in this case the string @code{"Decent -Hacker"} is not part of the author's name. You can tell Supercite to -ignore the title, while still recognizing hyphenated names through the -use of a regular expression in the variable @code{sc-titlecue-regexp}. -This variable has the default value of @code{"\\\\s +-+\\\\s +"}. Any -text after this regexp is encountered is ignored as noise. - -@vindex sc-name-filter-alist -@vindex name-filter-alist (sc-) -Some @samp{From:@:} headers may contain extra titles in the name fields -not separated by a title cue, but which are nonetheless not part of the -author's name proper. Examples include the titles ``Dr.'', ``Mr.'', -``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third). -Also, some companies prepend or append the name of the division, -organization, or project on the author's name. All of these titles are -noise which should be ignored. The variable @code{sc-name-filter-alist} -is used for this purpose. As implied by its name, this variable is an -association list, where each element is a cons cell of the form: - -@example -(@var{regexp} . @var{position}) -@end example - -@noindent -where @var{regexp} is a regular expression that is matched (using -@code{string-match}) against each element of the @samp{From:@:} field's -author name. @var{position} is a position indicator, starting at zero. -Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name, -@code{sc-name-filter-alist} would have an entry such as: - -@example -("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" . 0) -@end example - -@noindent -which only removes them if they appear as the first word in the name. -The position indicator is an integer, or one of the two special symbols -@code{last} or @code{any}. @code{last} always matches against the last -word in the name field, while @code{any} matches against every word in -the name field. - -@node Configuring the Citation Engine -@chapter Configuring the Citation Engine -@cindex Regi -@cindex frames (Regi) -@cindex entries (Regi) - -At the heart of Supercite is a regular expression interpreting engine -called @dfn{Regi}. Regi operates by interpreting a data structure -called a Regi-frame (or just @dfn{frame}), which is a list of -Regi-entries (or just @dfn{entry}). Each entry contains a predicate, -typically a regular expression, which is matched against a line of text -in the current buffer. If the predicate matches true, an associated -expression is @code{eval}uated. In this way, an entire region of text -can be transformed in an @emph{awk}-like manner. Regi is used -throughout Supercite, from mail header information extraction, to header -nuking, to citing text. - -@menu -* Using Regi:: -* Frames You Can Customize:: -@end menu - -While the details of Regi are discussed below (@pxref{Using Regi}), only -those who wish to customize certain aspects of Supercite need concern -themselves with it. It is important to understand though, that any -conceivable citation style that can be described by a regular expression -can be recognized by Supercite. This leads to some interesting -applications. For example, if you regularly receive email from a -co-worker that uses an uncommon citation style (say one that employs a -@samp{|} or @samp{@}} character at the front of the line), it is -possible for Supercite to recognize this and @emph{coerce} the citation -to your preferred style, for consistency. In theory, it is possible for -Supercite to recognize such things as uuencoded messages or C code and -cite or fill those differently than normal text. None of this is -currently part of Supercite, but contributions are welcome! - -@node Using Regi -@section Using Regi -@findex regi-interpret -@findex eval -@findex looking-at - -Regi works by interpreting frames with the function -@code{regi-interpret}. A frame is a list of arbitrary size where each -element is a entry of the following form: - -@example -(@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]]) -@end example - -Regi starts with the first entry in a frame, evaluating the @var{pred} -of that entry against the beginning of the line that @samp{point} is on. -If the @var{pred} evaluates to true (or false if the optional -@var{negate-p} is non-@code{nil}), then the @var{func} for that entry is -@code{eval}uated. How processing continues is determined by the return -value for @var{func}, and is described below. If @var{pred} was false -the next entry in the frame is checked until all entries have been -matched against the current line. If no entry matches, @samp{point} is -moved forward one line and the frame is reset to the first entry. - -@var{pred} can be a string, a variable, a list or one of the following -symbols: @code{t}, @code{begin}, @code{end}, or @code{every}. If -@var{pred} is a string, or a variable or list that @code{eval}uates to a -string, it is interpreted as a regular expression. This regexp is -matched against the current line, from the beginning, using -@code{looking-at}. This match folds case if the optional -@var{case-fold-search} is non-@code{nil}. If @var{pred} is not a -string, or does not @code{eval}uate to a string, it is interpreted as a -binary value (@code{nil} or non-@code{nil}). - -The four special symbol values for @var{pred} are recognized: - -@table @code -@item t -Always produces a true outcome. -@item begin -Always executed before the frame is interpreted. This can be used to -initialize some global variables for example. -@item end -Always executed after frame interpreting is completed. This can be used -to perform any necessary post-processing. -@item every -Executes whenever the frame is reset, usually after the entire frame has -been matched against the current line. -@end table - -Note that @var{negate-p} and @var{case-fold-search} are ignored if -@var{pred} is one of these special symbols. Only the first occurrence of -each symbol in a frame is used; any duplicates are ignored. Also -note that for performance reasons, the entries associated with these -symbols are removed from the frame during the main interpreting loop. - -Your @var{func} can return certain values which control continued Regi -processing. By default, if your @var{func} returns @code{nil} (as it -should be careful to do explicitly), Regi will reset the frame to the -first entry, and advance @samp{point} to the beginning of the next line. -If a list is returned from your function, it can contain any combination -of the following elements: - -@table @asis -@item the symbol @code{continue} -This tells Regi to continue processing entries after a match, instead of -resetting the frame and moving @samp{point}. In this way, lines of text -can have multiple matches, but you have to be careful to avoid entering -infinite loops. - -@item the symbol @code{abort} -This tells Regi to terminate frame processing. However, any @code{end} -entry is still processed. - -@item the list @code{(frame . @var{newframe})} -This tells Regi to substitute @var{newframe} as the frame it is -interpreting. In other words, your @var{func} can modify the Regi frame -on the fly. @var{newframe} can be a variable containing a frame, or it -can be the frame in-lined. - -@item the list @code{(step . @var{step})} -Tells Regi to move @var{step} number of lines forward as it continues -processing. By default, Regi moves forward one line. @var{step} can be -zero or negative of course, but watch out for infinite loops. -@end table - -During execution of your @var{func}, the following variables will be -temporarily bound to some useful information: - -@table @code -@item curline -The current line in the buffer that Regi is @code{looking-at}, as a string. -@item curframe -The current frame being interpreted. -@item curentry -The current frame entry being interpreted. -@end table - -@node Frames You Can Customize -@section Frames You Can Customize -@vindex sc-nuke-mail-header - -As mentioned earlier, Supercite uses various frames to perform -certain jobs such as mail header information extraction and mail header -nuking. However, these frames are not available for you to customize, -except through abstract interfaces such as @code{sc-nuke-mail-header}, -et al. - -@vindex sc-default-cite-frame -However, the citation frames Supercite uses provide a lot of customizing -power and are thus available to you to change to suit your needs. The -workhorse of citation is the frame contained in the variable -@code{sc-default-cite-frame}. This frame recognizes many situations, -such as blank lines, which it interprets as paragraph separators. It -also recognizes previously cited nested and non-nested citations in the -original message. By default it will coerce non-nested citations into -your preferred citation style, and it will add a level of citation to -nested citations. It will also simply cite uncited lines in your -preferred style. - -@cindex unciting -@cindex reciting -@vindex sc-default-uncite-frame -@vindex sc-default-recite-frame -In a similar vein, there are default frames for @dfn{unciting} and -@dfn{reciting}, contained in the variables -@code{sc-default-uncite-frame} and @code{sc-default-recite-frame} -respectively. - -As mentioned earlier (@pxref{Recognizing Citations}), citations are -recognized through the values of the regular expressions -@code{sc-citation-root-regexp}, et al. To recognize odd styles, you -could modify these variables, or you could modify the default citing -frame. Alternatively, you could set up association lists of frames for -recognizing specific alternative forms. - -@vindex sc-cite-frame-alist -@vindex sc-uncite-frame-alist -@vindex sc-recite-frame-alist -For each of the actions---citing, unciting, and reciting---an alist is -consulted to find the frame to use (@code{sc-cite-frame-alist}, -@code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist} -respectively). These frames can contain alists of the form: - -@example -((@var{infokey} (@var{regexp} . @var{frame}) (@var{regexp} . @var{frame}) @dots{}) - (@var{infokey} (@var{regexp} . @var{frame}) (@var{regexp} . @var{frame}) @dots{}) - (@dots{})) -@end example - -@vindex sc-mail-field -@findex string-match -Where @var{infokey} is a key suitable for @code{sc-mail-field}, -@var{regexp} is a regular expression which is @code{string-match}'d -against the value of the @code{sc-mail-field} key, and @var{frame} is -the frame to use if a match occurred. @var{frame} can be a variable -containing a frame or a frame in-lined. - -When Supercite is about to cite, uncite, or recite a region, it consults -the appropriate alist and attempts to find a frame to use. If one -is not found from the alist, then the appropriate default frame is used. - -@node Post-yank Formatting Commands -@chapter Post-yank Formatting Commands -@vindex sc-mode-map-prefix -@vindex mode-map-prefix (sc-) -@kindex C-c C-p - -Once the original message has been yanked into the reply buffer, and -@code{sc-cite-original} has had a chance to do its thing, a number of -useful Supercite commands will be available to you. Since there is wide -variety in the keymaps that MUAs set up in their reply buffers, it is -next to impossible for Supercite to properly sprinkle its commands into -the existing keymap. For this reason Supercite places its commands on a -separate keymap, putting this keymap onto a prefix key in the reply -buffer. You can customize the prefix key Supercite uses by changing the -variable @code{sc-mode-map-prefix}. By default, the -@code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice, -but unfortunately the best general solution so far. In the rest of this -chapter, we'll assume you've installed Supercite's keymap on the default -prefix. - -@menu -* Citing Commands:: -* Insertion Commands:: -* Variable Toggling Shortcuts:: -* Mail Field Commands:: -* Miscellaneous Commands:: -@end menu - -@node Citing Commands -@section Commands to Manually Cite, Recite, and Uncite -@vindex sc-cite-region-limit - -Probably the three most common post-yank formatting operations that you -will perform will be the manual citing, reciting, and unciting of -regions of text in the reply buffer. Often you may want to recite a -paragraph to use a nickname, or manually cite a message when setting -@code{sc-cite-region-limit} to @code{nil}. The following commands -perform these functions on the region of text between @samp{point} and -@samp{mark}. Each of them sets the @dfn{undo boundary} before modifying -the region so that the command can be undone in the standard Emacs -way. - -Here is the list of Supercite citing commands: - -@table @asis -@findex sc-cite-region -@findex cite-region (sc-) -@kindex C-c C-p c -@vindex sc-pre-cite-hook -@vindex pre-cite-hook (sc-) -@vindex sc-confirm-always-p -@vindex confirm-always-p -@kindex C-u -@item @code{sc-cite-region} (@kbd{C-c C-p c}) -This command cites each line in the region of text by interpreting the -selected frame from @code{sc-cite-frame-alist}, or the default citing -frame @code{sc-default-cite-frame}. It runs the hook -@code{sc-pre-cite-hook} before interpreting the frame. With an optional -universal argument (@kbd{C-u}), it temporarily sets -@code{sc-confirm-always-p} to @code{t} so you can confirm the -attribution string for a single manual citing. -@xref{Configuring the Citation Engine}. - -@findex sc-uncite-region -@findex uncite-region (sc-) -@kindex C-c C-p u -@item @code{sc-uncite-region} (@kbd{C-c C-p u}) -This command removes any citation strings from the beginning of each -cited line in the region by interpreting the selected frame from -@code{sc-uncite-frame-alist}, or the default unciting frame -@code{sc-default-uncite-frame}. It runs the hook -@code{sc-pre-uncite-hook} before interpreting the frame. -@xref{Configuring the Citation Engine}. - -@findex sc-recite-region -@findex recite-region (sc-) -@kindex C-c C-p r -@item @code{sc-recite-region} (@kbd{C-c C-p r}) -This command recites each line the region by interpreting the selected -frame from @code{sc-recite-frame-alist}, or the default reciting frame -@code{sc-default-recite-frame}. It runs the hook -@code{sc-pre-recite-hook} before interpreting the frame. -@xref{Configuring the Citation Engine}. - -@vindex sc-confirm-always-p -@vindex confirm-always-p (sc-) -Supercite will always ask you to confirm the attribution when reciting a -region, regardless of the value of @code{sc-confirm-always-p}. -@end table - -@node Insertion Commands -@section Insertion Commands - -These two functions insert various strings into the reply buffer. - -@table @asis -@findex sc-insert-reference -@findex insert-reference (sc-) -@kindex C-c C-p w -@item @code{sc-insert-reference} (@kbd{C-c C-p w}) -@vindex sc-preferred-header-style -@vindex preferred-header-style (sc-) -Inserts a reference header into the reply buffer at @samp{point}. With -no arguments, the header indexed by @code{sc-preferred-header-style} is -inserted. An optional numeric argument is the index into -@code{sc-rewrite-header-list} indicating which reference header to -write. - -With just the universal argument (@kbd{C-u}), electric reference mode is -entered, regardless of the value of @code{sc-electric-references-p}. - -@findex sc-insert-citation -@findex insert-citation (sc-) -@kindex C-c C-p i -@item @code{sc-insert-citation} (@kbd{C-c C-p i}) -Inserts the current citation string at the beginning of the line that -@samp{point} is on. If the line is already cited, Supercite will issue -an error and will not cite the line. -@end table - -@node Variable Toggling Shortcuts -@section Variable Toggling Shortcuts -@cindex toggling variables - -Supercite defines a number of commands that make it easier for you to -toggle and set various Supercite variables as you are editing the reply -buffer. For example, you may want to turn off filling or whitespace -cleanup, but only temporarily. These toggling shortcut commands make -this easy to do. - -@kindex C-c C-p C-t -Like Supercite commands in general, the toggling commands are placed on -a keymap prefix within the greater Supercite keymap. For the default -value of @code{sc-mode-map-prefix}, this will be -@kbd{C-c C-p C-t}. - -The following commands toggle the value of certain Supercite variables -which take only a binary value: - -@table @kbd -@item C-c C-p C-t b -Toggles the variable @code{sc-mail-nuke-blank-lines-p}. - -@item C-c C-p C-t c -Toggles the variable @code{sc-confirm-always-p}. - -@item C-c C-p C-t d -Toggles the variable @code{sc-downcase-p}. - -@item C-c C-p C-t e -Toggles the variable @code{sc-electric-references-p}. - -@item C-c C-p C-t f -Toggles the variable @code{sc-auto-fill-region-p}. - -@item C-c C-p C-t o -Toggles the variable @code{sc-electric-circular-p}. - -@item C-c C-p C-t s -Toggles the variable @code{sc-nested-citation-p}. - -@item C-c C-p C-t u -Toggles the variable @code{sc-use-only-preferences-p}. - -@item C-c C-p C-t w -Toggles the variable @code{sc-fixup-whitespace-p}. -@end table - -@findex set-variable -The following commands let you set the value of multi-value variables, -in the same way that Emacs's @code{set-variable} does: - -@table @kbd -@item C-c C-p C-t a -Sets the value of the variable @code{sc-preferred-attribution-list}. - -@item C-c C-p C-t l -Sets the value of the variable @code{sc-cite-region-limit}. - -@item C-c C-p C-t n -Sets the value of the variable @code{sc-mail-nuke-mail-headers}. - -@item C-c C-p C-t N -Sets the value of the variable @code{sc-mail-header-nuke-list}. - -@item C-c C-p C-t p -Sets the value of the variable @code{sc-preferred-header-style}. -@end table - -@kindex C-c C-p C-p -One special command is provided to toggle both -@code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together. -This is because you typically want to run Supercite with either variable -as @code{nil} or non-@code{nil}. The command to toggle these variables -together is bound on @kbd{C-c C-p C-p}. - -Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?}) -brings up a Help message on the toggling keymap. - - -@node Mail Field Commands -@section Mail Field Commands - -These commands allow you to view, modify, add, and delete various bits -of information from the info alist. -@xref{Information Keys and the Info Alist}. - -@table @asis -@kindex C-c C-p f -@findex sc-mail-field-query -@findex mail-field-query (sc-) -@kindex C-c C-p f -@item @code{sc-mail-field-query} (@kbd{C-c C-p f}) -Allows you to interactively view, modify, add, and delete info alist -key-value pairs. With no argument, you are prompted (with completion) -for a info key. The value associated with that key is displayed in the -minibuffer. With an argument, this command will first ask if you want -to view, modify, add, or delete an info key. Viewing is identical to -running the command with no arguments. - -If you want to modify the value of a key, Supercite will first prompt -you (with completion) for the key of the value you want to change. It -will then put you in the minibuffer with the key's current value so you -can edit the value as you wish. When you hit @key{RET}, the key's value -is changed. Minibuffer history is kept for the values. - -If you choose to delete a key-value pair, Supercite will prompt you (with -completion) for the key to delete. - -If you choose to add a new key-value pair, Supercite firsts prompts you -for the key to add. Note that completion is turned on for this prompt, -but you can type any key name here, even one that does not yet exist. -After entering the key, Supercite prompts you for the key's value. It -is not an error to enter a key that already exists, but the new value -will override any old value. It will not replace it though; if you -subsequently delete the key-value pair, the old value will reappear. - -@findex sc-mail-process-headers -@findex mail-process-headers (sc-) -@kindex C-c C-p g -@item @code{sc-mail-process-headers} (@kbd{C-c C-p g}) -This command lets you re-initialize Supercite's info alist from any set -of mail headers in the region between @samp{point} and @samp{mark}. -This function is especially useful for replying to digest messages where -Supercite will initially set up its information for the digest -originator, but you want to cite each component article with the real -message author. Note that unless an error during processing occurs, any -old information is lost. -@end table - -@node Miscellaneous Commands -@section Miscellaneous Commands - -@table @asis -@findex sc-open-line -@findex open-line (sc-) -@findex open-line -@kindex C-c C-p o -@item @code{sc-open-line} (@kbd{C-c C-p o}) -Similar to Emacs's standard @code{open-line} commands, but inserts the -citation string in front of the new line. As with @code{open-line}, -an optional numeric argument inserts that many new lines. -@end table - -@node Hints to MUA Authors -@chapter Hints to MUA Authors - -In June of 1989, some discussion was held between the various MUA -authors, the Supercite author, and other Supercite users. These -discussions centered around the need for a standard interface between -MUAs and Supercite (or any future Supercite-like packages). This -interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in -a mail message to the Supercite mailing list: - -@example - Martin> Each news/mail-reader should provide a form of - Martin> mail-yank-original that - - Martin> 1: inserts the original message incl. header into the - Martin> reply buffer; no indentation/prefixing is done, the header - Martin> tends to be a "full blown" version rather than to be - Martin> stripped down. - - Martin> 2: `point' is at the start of the header, `mark' at the - Martin> end of the message body. - - Martin> 3: (run-hooks 'mail-yank-hooks) - - Martin> [Supercite] should be run as such a hook and merely - Martin> rewrite the message. This way it isn't anymore - Martin> [Supercite]'s job to gather the original from obscure - Martin> sources. [@dots{}] -@end example - -@vindex mail-citation-hook -@vindex mail-yank-hooks -@cindex sendmail.el -@findex mail-yank-original -@findex defvar -This specification was adopted, but underwent a slight modification with -the release of Emacs 19. Instead of the variable -@code{mail-yank-hooks}, the hook variable that the MUA should provide is -@code{mail-citation-hook}. Richard Stallman suggests that the MUAs -should @code{defvar} @code{mail-citation-hook} to @code{nil} and perform -some default citing when that is the case. - -If you are writing a new MUA package, or maintaining an existing MUA -package, you should make it conform to this interface so that your users -will be able to link Supercite easily and seamlessly. To do this, when -setting up a reply or forward buffer, your MUA should follow these -steps: - -@enumerate -@item -Insert the original message, including the mail headers into the reply -buffer. At this point you should not modify the raw text in any way -(except for any necessary decoding, e.g., of quoted-printable text), and -you should place all the original headers into the body of the reply. -This means that many of the mail headers will be duplicated, one copy -above the @code{mail-header-separator} line and one copy below, however -there will probably be more headers below this line. - -@item -Set @samp{point} to the beginning of the line containing the first mail -header in the body of the reply. Set @samp{mark} at the end of the -message text. It is very important that the region be set around the -text Supercite is to modify and that the mail headers are within this -region. Supercite will not venture outside the region for any reason, -and anything within the region is fair game, so don't put anything that -@strong{must} remain unchanged inside the region. - -@item -Run the hook @code{mail-citation-hook}. You will probably want to -provide some kind of default citation functions in cases where the user -does not have Supercite installed. By default, your MUA should -@code{defvar} @code{mail-citation-hook} to @code{nil}, and in your -yanking function, check its value. If it finds -@code{mail-citation-hook} to be @code{nil}, it should perform some -default citing behavior. User who want to connect to Supercite then -need only add @code{sc-cite-original} to this list of hooks using -@code{add-hook}. -@end enumerate - -If you do all this your MUA will join the ranks of those that conform to -this interface ``out of the box.'' - -@node Thanks and History -@chapter Thanks and History - -The Supercite package was derived from its predecessor Superyank 1.11 -which was inspired by various bits of code and ideas from Martin Neitzel -and Ashwin Ram. They were the folks who came up with the idea of -non-nested citations and implemented some rough code to provide this -style. Superyank and Supercite version 2 evolved to the point where much -of the attribution selection mechanism was automatic, and features have -been continuously added through the comments and suggestions of the -Supercite mailing list participants. - -With version 3, Supercite underwent an almost complete rewrite, -benefiting in a number of ways, including vast improvements in the -speed of performance, a big reduction in size of the code and in the use -of Emacs resources, and a much cleaner and flexible internal -architecture. Most of this work was internal and not of very great -importance to the casual user. There were some changes at the -user-visible level, but for the most part, the Supercite configuration -variables from version 2 should still be relevant to version 3. -Hopefully Supercite version 3 is faster, smaller, and much more flexible -than its predecessors. - -In the version 2 manual I thanked some specific people for their help in -developing Supercite 2. You folks know who you are and your continued -support is greatly appreciated. I wish to thank everyone on the -Supercite mailing list, especially the brave alpha testers, who helped -considerably in testing out the concepts and implementation of Supercite -version 3. Special thanks go out to the MUA and Emacs authors Kyle -Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming -to a quick agreement on the new @code{mail-citation-hook} interface, and -for adding the magic lisp to their code to support this. - -All who have helped and contributed have been greatly appreciated. - -Supercite was written by Barry Warsaw. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@node Command Index -@unnumbered Command Index - -Since all supercite commands are prepended with the string -``@code{sc-}'', each appears under its @code{sc-}@var{command} name and -its @var{command} name. -@iftex -@sp 2 -@end iftex -@printindex fn - -@node Key Index -@unnumbered Key Index -@printindex ky - -@node Variable Index -@unnumbered Variable Index - -Since all supercite variables are prepended with the string -``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and -its @var{variable} name. -@iftex -@sp 2 -@end iftex -@printindex vr -@bye diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi deleted file mode 100644 index ebd301cf5f9..00000000000 --- a/doc/misc/sem-user.texi +++ /dev/null @@ -1,1325 +0,0 @@ -@c This is part of the Semantic manual. -@c Copyright (C) 1999-2005, 2007, 2009-2014 Free Software Foundation, -@c Inc. -@c See file semantic.texi for copying conditions. - -You can begin using @semantic{} by enabling Semantic mode, a global -minor mode: type @kbd{M-x semantic-mode}, or open the @samp{Tools} -menu and click on the menu item named @samp{Source Code Parsers -(Semantic)}. @xref{Semantic mode}. - -When Semantic mode is turned on, Emacs automatically parses each file -you visit. You can then use @semantic{} user commands in those -buffers (@pxref{Semantic mode user commands}). You can also choose to -enable a number of ``helper'' minor modes for saving tags, displaying -tag information, and so forth. - -To enable Semantic mode each time you start Emacs, add the line -@code{(semantic-mode 1)} to your initialization file. @xref{Init -File,,,emacs,Emacs manual}. - -@menu -* Semantic mode:: Global minor mode for @semantic{}. -* SemanticDB:: Caching parsed buffers between sessions. -* Idle Scheduler:: @semantic{} actions that occur when idle. -* Analyzer:: Semantic tools for analyzing code. -* Speedbar:: Using @semantic{} with the Speedbar. -* SymRef:: Interface to symbol reference tools. -* MRU Bookmarks:: Managing tag "bookmarks". -* Sticky Func Mode:: Showing declarations in the header line. -* Highlight Func Mode:: Highlight the current function declaration. -* Tag Decoration Mode:: Minor mode to decorate tags. -@end menu - -@node Semantic mode -@section Semantic mode -@cindex Semantic mode - -Semantic mode is a global minor mode for @semantic{} as a whole. When -enabled, each file you visit is automatically parsed, provided its -major mode is specified in the variable -@code{semantic-new-buffer-setup-functions} (the default value of this -variable sets up parsing for all the parsers included with Emacs, but -you may add to it if you install additional parsers). - -In each parser-enabled buffer, a number of @semantic{} commands are -available for navigating, querying, and editing source code. -@xref{Semantic mode user commands}. Enabling Semantic mode also -installs a @samp{Development} menu on the menu-bar, with many of these -commands. - -In addition, enabling Semantic mode turns on certain auxiliary global -minor modes. The variable @code{semantic-default-submodes} determines -which auxiliary modes are enabled; the defaults are SemanticDB mode -(@pxref{SemanticDB}) and Global Semantic Idle Scheduler mode -(@pxref{Idle Scheduler}). You can also toggle the auxiliary minor -modes separately, using their mode functions (e.g., @kbd{M-x -semanticdb-minor-mode}), or via the @samp{Development} menu. The -various auxiliary minor modes are described in the following sections. - -@defvar semantic-new-buffer-setup-functions -The value of this variable is an alist of functions to call for -setting up @semantic{} parsing in the buffer. Each element has the -form @code{(@var{mode} . @var{fn})}, where @var{mode} is a value of -@code{major-mode} for the buffer and @var{fn} is the corresponding -function for setting up the parser. @var{fn} is called, with no -arguments, after the major mode is initialized (and after the mode -hooks have been run). - -The default value enables @semantic{} for all supported major modes -(i.e., C, C++, Scheme, Javascript, Java, HTML, SRecode, and Make), but -you can remove modes from this list if you don't want to use -@semantic{} with them. -@end defvar - -@defvar semantic-default-submodes -The value of this variable is a list of symbols, specifying the -auxiliary minor modes to enable when enabling Semantic mode. The -valid mode symbols are: - -@itemize -@item @code{global-semantic-idle-scheduler-mode} (@pxref{Idle Scheduler}). -@item @code{global-semanticdb-minor-mode} (@pxref{SemanticDB}). -@item @code{global-semantic-idle-summary-mode} (@pxref{Idle Summary Mode}). -@item @code{global-semantic-idle-completions-mode} (@pxref{Idle Completions Mode}). -@item @code{global-semantic-highlight-func-mode} (@pxref{Highlight Func Mode}). -@item @code{global-semantic-decoration-mode} (@pxref{Tag Decoration Mode}). -@item @code{global-semantic-stickyfunc-mode} (@pxref{Sticky Func Mode}). -@item @code{global-semantic-mru-bookmark-mode} (@pxref{MRU Bookmarks}). -@end itemize -@end defvar - -@menu -* Semantic mode user commands:: -@end menu - -@node Semantic mode user commands -@subsection Semantic mode user commands - -Semantic mode provides a number of commands for navigating, querying, -and editing source code in a language-aware manner. These commands -generally act on @dfn{tags}, which are the source-code units deemed -``important'' by the present programming language (e.g., functions in -the C programming language). - -These commands may be used in any buffer that has been parsed by -@semantic{}. Several of them prompt for a tag name using the -minibuffer; here, the @kbd{TAB} key can be used to complete tag names. -Others act on the @dfn{current tag}, meaning the tag at (or around) -point. - -@table @kbd -@item C-c , j -Prompt for a tag defined in the current file, and move point to it -(@code{semantic-complete-jump-local}). - -@item C-c , J -Prompt for a tag defined in any file that Emacs has parsed, and move -point to it (@code{semantic-complete-jump}). - -@item C-c , l -Display a list of the possible completions of the current tag -(@code{semantic-analyze-possible-completions}). - -@item C-c , g -Prompt for a tag, and display a list of tags that call it -(@code{semantic-symref-symbol}). This relies on the presence of an -external symbol reference tool. @xref{SymRef}. - -@item C-c , G -Display a list of tags that call the current tag -(@code{semantic-symref}). This relies on the presence of an external -symbol reference tool. @xref{SymRef}. - -@item C-c , p -Move point to the previous tag (@code{senator-previous-tag}). - -@item C-c , n -Move point to the next tag (@code{senator-next-tag}). - -@item C-c , u -Move point ``up'' one reference (@code{senator-go-to-up-reference}). -The meaning of ``up'' is language-dependent; in C++, for instance, -this means moving to the parent of the current tag. - -@item C-c, @key{SPC} -Display a list of possible completions for the symbol at point -(@code{semantic-complete-analyze-inline}). This also activates a -special set of keybindings for choosing a completion: @key{RET} -accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through -possible completions, @key{TAB} completes as far as possible and then -cycles, and @kbd{C-g} or any other key aborts the completion. -@xref{Smart Completion}. - -@item C-c , C-w -Kill the current tag (@code{senator-kill-tag}). This removes the text -for that tag, placing it in the kill ring. You can retrieve the text -with @kbd{C-y}. This also places the tag in the @dfn{tag ring}, so -that you can yank it with @kbd{\C-c,\C-y}, below. - -@item C-c , M-w -Copy the current tag into the kill ring as well as the tag ring -(@code{senator-copy-tag}). - -@item C-c , C-y -Yank a tag from the tag ring (@code{senator-yank-tag}). - -@item C-c , r -Copy the current tag into a register -(@code{senator-copy-tag-to-register}). With an optional argument, -kill it as well. This allows you to insert or jump to that tag with -the usual register commands. @xref{Registers,,,emacs,Emacs manual}. - -@item C-c , @kbd{up} -Transpose the current tag with the previous one -(@code{senator-transpose-tags-up}). - -@item C-c , @kbd{down} -Transpose the current tag with the next one -(@code{senator-transpose-tags-down}). -@end table - -@node SemanticDB -@section Semantic Database -@cindex SemanticDB - -The Semantic Database (SemanticDB) caches the results of parsing -source code files. This data can be saved to disk when you exit -Emacs, and reloaded automatically when you subsequently revisit the -same source code files. This saves time by eliminating the need to -re-parse unmodified files. - -SemanticDB also provides an @acronym{API} that programs can use to -acquire information about source code tags. This information can be -accessed without loading the original the source files into memory. -It can also be used to create alternate ``back-ends'' for storing tag -information in alternative on-disk formats. - -By default, SemanticDB is enabled together with Semantic mode. To -disable it, remove it from @code{semantic-default-submodes} -(@pxref{Semantic mode}). You can also enable or disable SemanticDB -with @kbd{M-x global-semanticdb-minor-mode}. - -@deffn Command global-semanticdb-minor-mode -Toggle SemanticDB mode. When enabled, any source code parsed by -@semantic{} is cached in a database. -@end deffn - -SemanticDB offers a large number of customizable options, which are -described in the following subsections. - -@menu -* Semanticdb Tag Storage:: -* Semanticdb Search Configuration:: -* Changing Backends:: -* Create System Databases:: -@end menu - -@node Semanticdb Tag Storage -@subsection Semanticdb Tag Storage - -Each time you exit Emacs, any data cached by SemanticDB is saved in -the directory @file{.emacs.d/semanticdb/}, located in your home -directory. Within this directory, the cache data is written into a -set of files according to a SemanticDB-specific filename convention. -If the SemanticDB directory does not exist, Emacs first asks if you -want to create it. - -You can change the name of the SemanticDB directory by customizing the -variable @code{semanticdb-default-save-directory}. - -@deffn Option semanticdb-default-save-directory -The name of the directory where SemanticDB cache files are saved. If -the value is @code{nil}, SemanticDB saves its data into a single file, -in the current directory, whose filename is given by -@code{semanticdb-default-file-name}. -@end deffn - -@deffn Option semanticdb-default-file-name -The name of a cache file in which to save SemanticDB, when -@code{semanticdb-default-save-directory} is @code{nil}. -@end deffn - -You can force SemanticDB to save the data from only certain files, or -suppress saving altogether, by customizing -@code{semanticdb-persistent-path}: - -@deffn Option semanticdb-persistent-path -List of valid paths for SemanticDB to cache. Each element should be a -directory name (a string); then the parse data from any file in that -directory is saved. - -As a special exception, the value of this variable can be a list -containing a single symbol: @code{never}, @code{always}, or -@code{project}. The symbol @code{never} disables saving anywhere; -@code{always} enables saving everywhere; and @code{project} enables -saving directory based on the variable -@code{semanticdb-project-predicate-functions}. - -The default value is @code{(always)}. -@end deffn - -@defvar semanticdb-project-predicate-functions -The value of this variable is a list of predicates for indicating that -a directory belongs to a project. This list is used when the value of -@code{semanticdb-persistent-path} is @code{(project)}. If the list is -empty, all paths are considered valid. - -Project management packages, such as EDE (@pxref{Top,,,ede,EDE -manual}), may add their own predicates with @dfn{add-hook} to this -variable. This allows SemanticDB to save tag caches in directories -controlled by them. -@end defvar - -@deffn Option semanticdb-save-database-functions -Abnormal hook run after a database is saved. Each function is called -with one argument, the object representing the database recently -written. -@end deffn - -@node Semanticdb Search Configuration -@subsection Semanticdb Search Configuration - - When another part of @semantic{} (or another Emacs package using -@semantic{}) queries the SemanticDB library for a source code tag, the -search need not be limited to tags defined within the current file. -It can include tags defined elsewhere, such as @dfn{header files} -referenced by the current file (e.g., via the C/C++ @code{#include} -directive). While performing the search, the SemanticDB library may -even automatically visit other files and parse them, if necessary. - - The variable @code{semanticdb-find-default-throttle} determines how -aggressively SemanticDB searches for source code tags. @xref{Search -Throttle}. - - The details of SemanticDB searches can vary from language to -language. In C/C++ code, for example, SemanticDB distinguishes -between @dfn{project header files} and @dfn{system header files}, -based on whether the @code{#include} directive uses the @code{""} or -@code{<>} filename delimiter. SemanticDB looks for system header in -the @dfn{system include path} (@pxref{Include paths}). - -@menu -* Search Throttle:: Controlling how semanticdb searches occur. -* Semanticdb Roots:: Specifying the root of different projects. -* Include paths:: Specifying the directories to search. -* Semanticdb search debugging commands:: -@end menu - -@node Search Throttle -@subsubsection SemanticDB Search Throttle - -The SemanticDB @dfn{search throttle} determines how aggressive -SemanticDB searches are. It is controlled by the variable -@code{semanticdb-find-default-throttle}. The default value of this -variable aims for maximum accuracy, at the expense of search time. - -Other parts of the @semantic{} package, particularly the different -language parsers, may change the value of -@code{semanticdb-find-default-throttle}. You can override its value, -for a given major mode, like this: - -@example -(setq-mode-local c-mode - semanticdb-find-default-throttle - '(project unloaded system recursive)) -@end example - -@defvar semanticdb-find-default-throttle -The default throttle for @code{semanticdb-find} routines. -The throttle controls how detailed the list of database -tables is for a symbol lookup. The value is a list with -the following keys: - -@table @code -@item file -The file the search is being performed from. This option is here for -completeness only, and is assumed to always be on. -@item local -Tables from the same local directory are included. This includes -files directly referenced by a file name which might be in a different -directory. -@item project -Tables from the same local project are included If @code{project} is -specified, then @code{local} is assumed. -@item unloaded -If a table is not in memory, load it. If it is not cached on disk -either, get the source, parse it, and create the table. -@item system -Tables from system databases. These are specifically tables -from system header files, or language equivalent. -@item recursive -For include based searches, includes tables referenced by included -files. -@item omniscience -Included system databases which are omniscience, or somehow know -everything. Omniscience databases are found in -@code{semanticdb-project-system-databases}. The Emacs Lisp system -@var{db} is an omniscience database. -@end table -@end defvar - -@node Semanticdb Roots -@subsubsection SemanticDB project roots - -The @code{project} setting in the SemanticDB search throttle -(@pxref{Search Throttle}) tells SemanticDB to search within the -current single code project. For @semantic{}'s point of view, -@dfn{projects} are determined by their top-level directories, or -@dfn{project roots}; every subdirectory of a project root is -considered part of the same project. - -If you use EDE for project management, it will set the project roots -automatically. @xref{Top,,,ede,EDE manual}. You can also specify -them yourself. - -@deffn Option semanticdb-project-roots -The value of this variable is a list of directories (strings) that are -project roots. All subdirectories of a project root are considered -part of the same project. This variable can be overridden by -@code{semanticdb-project-root-functions}. -@end deffn - -@defvar semanticdb-project-root-functions -The value of this variable is a list of functions to determine a given -directory's project root. These functions are called, one at a time, -with one argument (the directory name), and must return either -@code{nil}, a string (the project root), or a list of strings -(multiple project roots, for complex systems). The first -non-@code{nil} return value, if any, is taken to be the project root, -overriding @code{semanticdb-project-roots}. -@end defvar - -@node Include paths -@subsubsection Include Paths - -System include paths are standard locations to find source code tags, -such as the @dfn{header files} in @file{/usr/include} and its -subdirectories on Unix-like operating systems. - -You can add and remove system include paths using the following -commands: - -@deffn Command semantic-add-system-include dir &optional mode -Prompts for a directory, @var{dir}, and add it as a system include -path for the current major mode. When called non-interactively, the -major mode can be specified with the @var{mode} argument. -@end deffn - -@deffn Command semantic-remove-system-include dir &optional mode -Prompt for a directory, @var{dir}, and remove it from the system -include path for the current major mode (or @var{mode}). -@end deffn - -@deffn Command semantic-customize-system-include-path &optional mode -Customize the system include path for the current major mode (or -@var{mode}). -@end deffn - -@defvar semanticdb-implied-include-tags -Include tags implied for all files of a given mode. You can set this -variable with @code{defvar-mode-local} for a particular mode so that -any symbols that exist for all files for that mode are included. -@end defvar - -@c @xref{Search Optimization}, for more information on include paths. - -@node Semanticdb search debugging commands -@subsubsection Semanticdb search debugging commands - -You can use @kbd{M-x semanticdb-dump-all-table-summary} to see the -list of databases that will be searched from a given buffer. You can -follow up with @kbd{M-x semanticdb-find-test-translate-path} to then -make sure specific tables from the path are discovered correctly. -Alternately, you can get a list of include files @semantic{} -encountered, but could not find on disk using @kbd{M-x -semanticdb-find-adebug-lost-includes}. - -@deffn Command semanticdb-dump-all-table-summary -Dump a list of all databases in Emacs memory. -@end deffn - -@deffn Command semanticdb-find-test-translate-path &optional arg -Call and output results of @dfn{semanticdb-find-translate-path}. In -the displayed buffer, you can type @key{SPC} to expand items. With -@var{arg} non-@code{nil}, specify a @var{brutish} translation. -@end deffn - -@deffn Command semanticdb-find-adebug-lost-includes -Translate the current path, then display the lost includes. -Examines the variable @code{semanticdb-find-lost-includes}. -@end deffn - -Lastly, you can test an explicit search term using this command: - -@deffn Command semantic-adebug-searchdb regex -Search the semanticdb for @var{regex} for the current buffer. -Display the results as a debug list. -@end deffn - -@node Changing Backends -@subsection Changing Backends - -If you want to use some other form of backend, you can use this -variable to choose which back end class to use for your general tag -storage. - -The default is to save databases in flat files. Alternatively, you -could write a new database backend that stores tags into a database, -or other storage system. - -@defvar semanticdb-new-database-class -The default type of database created for new files. This can be -changed on a per file basis, so that some directories are saved using -one mechanism, and some directories via a different mechanism. -@end defvar - -@node Create System Databases -@subsection Create System Databases - -If your supported language stores the system libraries in readily -available parsable source code, you can pre-generate database files -for them once, which will be used over and over for tools such as -summary-mode, or the analyzer. - -@deffn Command semanticdb-create-ebrowse-database dir -Create an Ebrowse database for directory @var{dir}. The database file -is stored in ~/.semanticdb, or whichever directory is specified by -@code{semanticdb-default-system-save-directory}. -@end deffn - -@node Idle Scheduler -@section Idle Scheduler -@cindex Idle Scheduler - -The @dfn{Semantic Idle Scheduler} is a part of @semantic{} that -performs various operations while Emacs is waiting for user input -(idle time). Its primary job is to perform buffer parsing during idle -time. You can also use the Idle Scheduler to display function -prototypes (@pxref{Idle Summary Mode}) or symbol completions -(@pxref{Idle Completions Mode}). - -@deffn Command global-semantic-idle-scheduler-mode &optional arg -This command toggles Semantic Idle Scheduler mode in every -@semantic{}-enabled buffer. This minor mode ensures that the buffer -is automatically reparsed whenever Emacs is idle. If there is -additional idle time, it runs jobs scheduled by other parts of -@semantic{}, such as Semantic Idle Summary mode (@pxref{Idle Summary -Mode}) and Semantic Idle Completions mode (@pxref{Idle Completions -Mode}). -@end deffn - -@deffn Option semantic-idle-scheduler-idle-time -The value of this variable is the amount of idle time, in seconds, -before the Semantic idle scheduler activates. The default is 1. -@end deffn - -@deffn Option semantic-idle-scheduler-verbose-flag -If this variable is non-@code{nil}, the idle scheduler prints verbose -messages while running, which are useful for debugging. -@end deffn - -@menu -* Reparsing Options:: Reparsing the current buffer in idle time. -* Idle Working Options:: Options for extra work done at idle time. -* Debugging Idle Time Issues:: How to produce good bug reports. -* Idle Summary Mode:: Display prototype of symbol under cursor. -* Idle Completions Mode:: Smart completion pop-up help. -@end menu - -@node Reparsing Options -@subsection Reparsing Options - -When activated during idle time, the Semantic idle scheduler -automatically reparses all buffers that need it. Any arriving user -input cancels this, returning Emacs to its normal editing behavior. - -@deffn Option semantic-idle-scheduler-max-buffer-size -Maximum size in bytes of buffers automatically reparsed. If this -value is less than or equal to @var{0}, buffers are automatically -reparsed regardless of their size. -@end deffn - -@deffn Option semantic-idle-scheduler-no-working-message -If non-@code{nil}, disable display of working messages while reparsing. -@end deffn - -@deffn Option semantic-idle-scheduler-working-in-modeline-flag -If non-@code{nil}, show working messages in the mode line. Normally, -re-parsing shows messages in the minibuffer; this moves the parse -message to the modeline instead. -@end deffn - -@defvar semantic-before-idle-scheduler-reparse-hook -This normal hook is run just before the idle scheduler begins -reparsing. If any hook function throws an error, the value of this -variable is reset to @code{nil}. This hook is not protected from -lexical errors. -@end defvar - -@defvar semantic-after-idle-scheduler-reparse-hook - -This normal hook is run after the idle scheduler finishes reparsing. -If any hook throws an error, this variable is reset to @code{nil}. -This hook is not protected from lexical errors. -@end defvar - -@node Idle Working Options -@subsection Idle Working Options - -In addition to reparsing buffers, the Semantic idle scheduler performs -additional operations, including the following: - -@itemize -@item -Creating the include path caches required for symbol lookup. -@item -Create data type caches. -@item -Saving SemanticDB caches to disk. -@item -Speculatively parsing the files in the same directory as the current -buffer. -@end itemize - -Because this extra work is quite time-consuming, it is only carried -out after a longer idle delay. The following features control how the -idle work is performed. - -@deffn Option semantic-idle-scheduler-work-idle-time -The value of this variable is the amount of idle time, in seconds, -before commencing idle work. The default is 60. -@end deffn - -@deffn Option semantic-idle-work-parse-neighboring-files-flag -If the value of this variable is non-@code{nil}, the Semantic idle -scheduler uses idle work time to parse files in the same directory as -the current buffer. This improves the accuracy of tag searches and -saves time when visiting those files later, at the cost of doing a lot -of parsing. The default is @code{t}. -@end deffn - -@node Debugging Idle Time Issues -@subsection Debugging Idle Time Issues - -If you see an error signaled during idle time, it could be an -indication of a more serious issue elsewhere. It is not enough to -enable @code{debug-on-error}, because the idle scheduler inhibits the -debugger. Instead, use the following commands to debug the error: - -@deffn Command semantic-debug-idle-function -Run the Semantic idle function with debugging turned on. -@end deffn - -@deffn Command semantic-debug-idle-work-function -Run the Semantic idle work function with debugging turned on. -@end deffn - -@node Idle Summary Mode -@subsection Idle Summary Mode - -Semantic Idle Summary mode is a minor mode that displays a short -summary of the symbol at point, such as its function prototype, in the -echo area. Its functionality is similar to what ElDoc mode provides -for Emacs Lisp (@pxref{Lisp Doc,,,emacs,Emacs manual}). - -@deffn global-semantic-idle-summary-mode &optional arg -This command toggles Semantic Idle Summary mode in all -@semantic{}-enabled buffers. You can also toggle it via the -@samp{Show Tag Summaries} menu item in the @samp{Development} menu. -@end deffn - -When Semantic Idle Summary mode is active, a summary of the tag at -point is displayed in the echo area. This display takes place during -the idle time, as given by @code{semantic-idle-scheduler-idle-time} -(@pxref{Idle Scheduler}). - -You can override the method for getting the current tag to display by -setting @code{idle-summary-current-symbol-info}. - -@deffn Option semantic-idle-summary-function -The value of this variable should be a function to call to display tag -information during idle time. See the variable -@code{semantic-format-tag-functions} for a list of useful functions. -@end deffn - -@defvar semantic-idle-summary-out-of-context-faces -The value of this variable is a list of font-lock faces indicating -useless summary contexts. These are generally faces used to highlight -comments or strings. Semantic Idle Summary mode does not display its -usual summary if the text at point has one of these faces. -@end defvar - -@node Idle Completions Mode -@subsection Idle Completions Mode - -Semantic Idle Completions mode is a minor mode for performing -@dfn{code completions} during idle time. The completions are -displayed inline, with keybindings that allow you to cycle through -different alternatives. - -Semantic Idle Completions mode performs completion based on the -Semantic Analyzer (@pxref{Analyzer}). - -@deffn global-semantic-idle-completions-mode &optional arg -This command toggles Semantic Idle Completions mode in every -@semantic{}-enabled buffer. You can also toggle it via the @samp{Show -Tag Completions} menu item in the @samp{Development} menu. -@end deffn - -If the tag at point has at least one completion, Semantic Idle -Completions mode displays that completion inline---i.e., as part of -the buffer text (you can change the display method by customizing -@code{semantic-complete-inline-analyzer-idle-displayor-class}, as -described below). The completed part is highlighted, to indicate that -it is not yet properly inserted into the buffer. The echo area shows -the completion, and whether there are other possible completions, like -this: - -@example -besselj [1 of 6 matches] -@end example - -@noindent -While the completion is being displayed, the following keybindings -take effect: - -@table @kbd -@item @key{RET} -@itemx C-m -Accept the current completion (@code{semantic-complete-inline-done}), -placing it in the buffer and moving point to the end of the completed -tag. -@item M-n -Select the next possible completion -(@code{semantic-complete-inline-down}). The new completion is shown -inline, replacing the old completion. -@item M-p -Select the previous possible completion -(@code{semantic-complete-inline-up}). -@item @key{TAB} -@item C-i -Accept as much of the completion as possible. If no additional -completion can be accepted without ambiguity, select the next possible -completion (@code{semantic-complete-inline-TAB}). -@item C-g -Quit without completing (@code{semantic-complete-inline-quit}). -@end table - -@noindent -You can also exit inline completion by issuing any other Emacs -command. The completion text then disappears from the buffer. - -@deffn Command semantic-complete-analyze-inline-idle -This is the command for performing inline code completion. It is -called by Semantic Idle Completions mode during idle time, but you can -also call it yourself. It returns immediately, leaving the buffer in -a state for inline completion. -@end deffn - -@deffn Option semantic-complete-inline-analyzer-idle-displayor-class -The value of this variable determines how -@code{semantic-complete-analyze-inline-idle} shows its completions. -Possible values include: - -@table @code -@item semantic-displayor-ghost -Display completions ``inline'' with the buffer text, as described -above. This is the default value. - -@item semantic-displayor-tooltip -Display completions in a tooltip. - -@item semantic-displayor-traditional -Display completions in a separate window. -@end table -@end deffn - -@node Analyzer -@section Analyzer -@cindex Analyzer - -The Semantic Analyzer is a library for performing context analysis on -source code. It provides user commands for displaying, completing, -and navigating through source code. - -@menu -* Smart Completion:: Performing code completion. -* Smart Summary:: Displaying help on a symbol. -* Smart Jump:: Jumping to the definition of a tag. -* Analyzer Debug:: Debugging problems with the analyzer. -@end menu - -@node Smart Completion -@subsection Smart Completion - -The Semantic Analyzer can be used to perform code completion in a -manner that takes the local context into account. (In addition to the -user commands in this section, Semantic Idle Completions mode also -uses the Semantic Analyzer. @xref{Idle Completions Mode}.) - -@deffn Command semantic-analyze-possible-completions context -This is the most basic command for Semantic Analyzer-based completion. -Called interactively, it displays a list of the possible completions -for the symbol at point. - -When called from a Lisp program, -@code{semantic-analyze-possible-completions} does not display a -completions list. The argument @var{context} should be either a -buffer position, or a context object. The return value is a list of -@semantic{} tag objects that complete the symbol for @var{context}, -based on the following criteria: - -@itemize -@item Elements currently in scope. -@item Constants currently in scope. -@item Elements matching the context's @code{:prefix}. -@item Type of the completion matching the type of the context. -@end itemize - -Most of the other commands documented in this section call -@code{semantic-analyze-possible-completions} internally. -@end deffn - -@deffn Command semantic-complete-analyze-inline -This command is bound to @kbd{C-c , @key{SPC}} when Semantic mode is -enabled (@pxref{Semantic mode user commands}). It displays a list of -possible completions for the symbol at point, and activates a special -set of keybindings for choosing a completion. - -You can type @key{RET} to accept the current completion, @kbd{M-n} and -@kbd{M-p} to cycle through the possible completions, @key{TAB} to -complete as far as possible and then cycle through completions, and -either @kbd{C-g} or any other key to abort the completion. - -This command is similar to the completion performed by Semantic Idle -Completions mode. The main difference is that it is called -explicitly, whereas Semantic Idle Completions mode completes during -idle time (@pxref{Idle Completions Mode}). -@end deffn - -@deffn Option semantic-complete-inline-analyzer-idle-displayor-class -The value of this variable determines how -@code{semantic-complete-analyze-inline} shows its completions. -Possible values include: - -@table @code -@item semantic-displayor-traditional -Display completions in a separate window. This is the default value. - -@item semantic-displayor-ghost -Display completions ``inline'' with the buffer text, similar to the -default behavior of Semantic Idle Completions mode (@pxref{Idle -Completions Mode}). - -@item semantic-displayor-tooltip -Display completions in a tooltip. -@end table -@end deffn - -In addition to @code{semantic-complete-analyze-inline}, you can use -the simpler command @code{semantic-ia-complete-symbol point}. This -behaves like the usual @kbd{M-@key{TAB}} (@code{complete-symbol}) -command (@pxref{Symbol Completion,,,emacs,Emacs manual}), except it -uses the Semantic Analyzer. - -@deffn Command semantic-ia-complete-symbol point -Complete the current symbol at @var{point}. -@end deffn - -@node Smart Summary -@subsection Smart Summary - -You can use the following commands to obtain information about the -code at point: - -@deffn Command semantic-ia-show-summary pos -Display a summary for the symbol at @var{pos}. Called interactively, -@var{pos} defaults to point. -@end deffn - -@deffn Command semantic-ia-show-doc pos -Display the code-level documentation for the symbol at @var{pos}. -Called interactively, @var{pos} defaults to point. -@end deffn - -@deffn Command semantic-ia-describe-class typename -Prompt for the name of a data type, @var{typename}, and display its -components. For instance, if the type in question is a class, this -displays the methods and member variables. -@end deffn - -You can also use Semantic Idle Summary mode to show information about -the current symbol in the echo area during idle time. @xref{Idle -Summary Mode}. - -@node Smart Jump -@subsection Smart Jump - -The Semantic Analyzer can be used to jump directly to the definition -for a code symbol. - -@deffn Command semantic-ia-fast-jump pos -Jump to the definition for the symbol at @var{pos}. Called -interactively, @var{pos} defaults to point. -@end deffn - -@defun semantic-ia-fast-mouse-jump event -Jump to the definition for the symbol at the position of the mouse -event @var{event}. This command is meant to be bound to a mouse -command, like this: - -@example -(global-set-key '[(S-mouse-1)] semantic-ia-fast-mouse-jump) -@end example -@end defun - -These commands are often more accurate than the @code{find-tag} -command (@pxref{Tags,,,emacs,Emacs manual}), because the Semantic -Analyzer is context-sensitive. - -You can also use @kbd{C-c , j} (@code{semantic-complete-jump-local}) -and @kbd{C-c , J} (@code{semantic-complete-jump}) to navigate tags. -@xref{Semantic mode user commands}. Those commands do not make use of -the Semantic Analyzer. - -@node Analyzer Debug -@subsection Debugging the Semantic Analyzer - -If the Semantic Analyzer does not analyze your code properly, you can -take steps to identify and solve the problem. This section was -written with C/C++ in mind, but should be relevant for any typed -language. - -@subsubsection Step 1: Check the context - -To check the current context, type @kbd{M-x -semantic-analyze-current-context}. - -@deffn Command semantic-analyze-current-context pos -Analyze the context at @var{pos}. This function is used by most of -the other Semantic Analyzer commands to obtain the context of the code -at a given buffer position. The return value is an EIEIO object -describing the context at @var{pos} (@pxref{Top,,,eieio,EIEIO -manual}). - -When called interactively, this displays a @file{*Semantic Context -Analysis*} buffer containing a summary of the context at point. -@end deffn - -@noindent -The Prefix section of the @file{*Semantic Context Analysis*} buffer -lists the tags based on the text at point. If it shows only a simple -string, the Semantic was unable to identify what the data type was. - -The first item in the list of the prefix is the first lookup failure -in the chain, and that is the item to focus debugging effort on. For -example: - -@example -Context Type: # -Bounds: (182 . 185) -Prefix: Foo* bar - int bbb (const char* y) -Prefix Types: class Foo @{@} --------- --> Local Vars: int argc - char** argv -@end example - -In this example you can see that the prefix has two fully found tags. -In the following example, the symbol ``bbb'' is incomplete, and could -not be found: - -@example -Context Type: # -Bounds: (182 . 184) -Prefix: Foo* bar - "bb" -Prefix Classes: 'function - 'variable -Prefix Types: class Foo @{@} --------- --> Local Vars: int argc - char** argv -@end example - -@subsubsection Step 2 : Check your include path - -Once you know the missing symbol, check your include path. The header -or include file containing the needed definition may not be in the -list of headers @semantic{} is searching through. To get a basic -list, you can use @kbd{M-x semanticdb-find-test-translate-path}. -@xref{Semanticdb search debugging commands}. - -If items should be loaded but aren't, or if you see some tables that -have no tags in them, then you you may have an incorrectly-set search -throttle (@pxref{Search Throttle}). For example, - -@example -*# -*# -@end example - -Here, @semantic{} found @file{foo.hh}, but there are 0 tags. This may -be because you had set the throttle to avoid reading and parsing files -that Emacs has not visited. To fix this, visit the file and let -@semantic{} parse it. - -For C++, check also that the @samp{#include} statements for your -project-level files use quotes, not angle brackets; angle brackets are -for system files. - -@subsubsection Step 3: Check the local scope - -If your data type is somehow abbreviated based on scope, such as from -a @code{using} statement, you should make sure that the symbol you -want is in the local scope. Examine the scope with @kbd{M-x -semantic-calculate-scope}. The scope structure is displayed in ADEBUG -mode, so use @kbd{SPC} to expand different elements and looking for -your symbol. - -If your symbol should be in the scope, but you cannot find it, then -you may have found a language support bug in the local-variable -parser, or using statement parser. - -Calling @kbd{M-x bovinate} should force a reset on the scope in case -there is merely some bad state. - -@example - ] Name: Cache - ] Class: #'semantic-scope-cache - ] :table # - ] tag createMoose : class moose - ] scopetypes 'nil - ] parents # - ] scope # - ] fullscope # - ] localvar # -@end example - -In the above sample output, the @code{tag} slot specifies where within -you source this scope is relevant. @code{Parents} should contain any -in scope parents, such as the class a method belongs to. -@code{Localvar} should contain your local variables. @code{Scope} -should contain datatypes in scope due to a @code{using} statement or -the like. - -@subsubsection Step 4: Check the typecache - -For complex typed languages like C++, @semantic{} creates a typecache, -or an optimized search table with all the various data types in it. -Elements in the typecache do not obey local scope. It only contains -fully qualified names. You can examine the typecache with -@kbd{M-x semanticdb-typecache-dump}. - -If your data types are not in the typecache, there may be some parsing -error or other bug. Calling @kbd{M-x bovinate} should force a reset on -the typecache in case there is merely some bad state. - -@example -]# - ] Name: /home/zappo/cedet/semantic/tests/testsubclass.cpp - ] Class: #'semanticdb-typecache - ] filestream 'nil - ] includestream # - ] stream 'nil - ] dependants 'nil -@end example - -In the above example, the output of @kbd{M-x semanticdb-typecache-dump} -was expanded one level. The @code{filestream} slot should contain -datatypes in the current file. The @code{includestream} should -contain all the datatypes in all included header files. - -The @code{dependants} slot will specify other files that depend on -this one. - -@subsubsection Step 5: Check the parser - -Go to the location where your unfound tag should be. You can call -@kbd{M-x bovinate}, and see a dump of the raw tag structure. To see a -navigable tree, use @kbd{M-x semantic-adebug-bovinate} instead. You -can then look to make sure your tag has been properly parsed. - -If it has not, then you may have found a parser bug. To get a feel -how @semantic{} treats your file, type @kbd{M-x -global-semantic-show-unmatched-syntax-mode}. This causes any syntax -it cannot parse to be underlined in red. - -If your type is not parsable, it could be for a couple of reasons: - -@enumerate -@item -If there is a MACRO keyword used in the definition of the type, you -may need to update the @code{semantic-lex-c-preprocessor-symbol-map} -to account for it. - -@item -Or perhaps the parser needs to be fixed. -@end enumerate - -@node Speedbar -@section Speedbar -@cindex speedbar - -You can integrate @semantic{} with the Speedbar. -@xref{Speedbar,,,emacs,Emacs manual}. To do this, add the following -line to your init file: - -@example -(add-hook 'speedbar-load-hook (lambda () (require 'semantic/sb))) -@end example - -@noindent -Or, alternatively: - -@example -(require 'semantic/sb) -@end example - -Once installed, the Speedbar will use @semantic{} to find and display -tags. Tags from @semantic{} are displayed with more details than -ordinary Speedbar tags, such as function arguments and return type. - -In addition, you can use the Speedbar to show the output of the -Semantic Analyzer (@pxref{Analyzer}). To do this, go to the -@samp{Display} menu item on the Speedbar menu and select -@samp{Analyze}; or type @kbd{M-x semantic-speedbar-analysis}. - -@deffn Command semantic-speedbar-analysis -Start the Speedbar in Semantic Analysis mode. -@end deffn - -In Semantic Analysis mode, the Speedbar displays information about the -local context, such as the current function, local arguments and -variables, and details on the prefix (the current symbol). Each entry -has an @samp{} button; clicking on this shows a summary of what -@semantic{} knows about that variable or type. The Speedbar also -displays a list of possible completions at point. - -@node SymRef -@section Symbol References -@cindex symref - -@semantic{} can interface with external @dfn{symbol reference tools}, -such as GNU Global and GNU Idutils. These tools provide information -about where different tags or symbols appear. - -By default, @semantic{} tries to look for the best external symbol -reference tool that can be used. The supported tools are GNU Global, -GNU Idutils, CScope, and Grep (the fallback method). For best -results, use GNU Global. However, @semantic{} does not manage your -GNU Global tables for you; you must manage them yourself. - -@defvar semantic-symref-tool -The value of this variable is a symbol that determines the external -symbol reference tool to use. The default value, @code{detect}, says -to look for the best available tool. Other possible values are -@code{global}, @code{idutils}, @code{cscope}, and @code{grep}. Note -that @code{grep} is much slower than the others. -@end defvar - -The commands to display symbol references are @kbd{C-c , g} -(@code{semantic-symref-symbol} and @kbd{C-c , G} -(@code{semantic-symref}). These keybindings are available whenever -Semantic mode is enabled (@pxref{Semantic mode user commands}). - -@deffn Command semantic-symref-symbol sym -This command (normally bound to @kbd{C-c , g}) prompts for a symbol -name, and uses an external reference tool to find references to that -tag. -@end deffn - -@deffn Command semantic-symref -This command (normally bound to @kbd{C-c , G}) uses an external -reference tool to find references to the current tag. -@end deffn - -Both @code{semantic-symref-symbol} and @code{semantic-symref} display -a list of symbol references in a separate buffer. The entries are -organized by file, and by function name. Typing @key{RET} on the -@samp{[+]} next to each function name ``expands'' that entry, listing -all references to the target symbol occurring within that function. -Typing @kbd{RET} on a reference line jumps to that reference. - -@node MRU Bookmarks -@section MRU Bookmarks mode -@cindex semantic-mru-bookmark-mode - -Semantic MRU Bookmarks mode is a minor mode that keeps track of the -tags you have edited, allowing you to quickly return to them later -(MRU stands for ``Most Recently Used''). - -@deffn Command global-semantic-mru-bookmark-mode &optional arg -Toggle Semantic MRU Bookmarks mode globally. The minor mode can be -turned on only if the current buffer was set up for parsing. With -argument @var{arg}, turn the minor mode if @var{arg} is positive, and -off otherwise. -@end deffn - -Semantic MRU Bookmarks mode takes note of each tag you edit. -Afterwards, you can type @kbd{C-x B} -(@code{semantic-mrub-switch-tags}) to return to a tag. This command -prompts for a tag name, completing with the names of edited tags; at -the prompt, you can use @kbd{M-p} and @kbd{M-n} to cycle through tags -in order of last modification time. - -@node Sticky Func Mode -@section Sticky Function mode - -Semantic Sticky Function minor mode displays a header line that shows -the declaration line of the function or tag on the topmost line in the -text area. This allows you to keep that declaration line in view at -all times, even if it is scrolls off the ``top'' of the screen. - -In addition, clicking @kbd{Mouse-1} on the header line opens a context -menu that contains menu items for copying, killing, or narrowing to -that tag. - -@deffn Command global-semantic-stickyfunc-mode &optional arg -Toggle Semantic Sticky Function mode in all Semantic-enabled buffers. -With an optional argument @var{arg}, enable if @var{arg} is positive, -and disable otherwise. -@end deffn - -@defvar semantic-stickyfunc-sticky-classes -The value of this variable is a list of tag classes that Semantic -Sticky Function mode makes ``sticky''. The default is -@code{'(function type)}, meaning function declarations and type -declarations. Other possible tag classes are @code{variable}, -@code{include}, and @code{package}. -@end defvar - -@node Highlight Func Mode -@section Highlight Func Mode -@cindex semantic-highlight-func-mode - -Semantic Highlight Function minor mode highlights the declaration line -of the current function or tag (that is to say, the first line that -describes the rest of the construct). - -In addition, clicking @kbd{Mouse-3} on the highlighted declaration -line opens a context menu that contains menu items for copying, -killing, or narrowing to that tag. - -The tag classes highlighted by Semantic Highlight Function mode are -the same ones given by @code{semantic-stickyfunc-sticky-classes}. -@xref{Sticky Func Mode}. - -@defun global-semantic-highlight-func-mode &optional arg -Toggle Semantic Highlight Function mode in all Semantic-enabled -buffers. With an optional argument @var{arg}, enable if @var{arg} is -positive, and disable otherwise. -@end defun - -@deffn Face semantic-highlight-func-current-tag-face -This face is used to highlight declaration lines in Semantic Highlight -Func mode. -@end deffn - -@node Tag Decoration Mode -@section Tag Decoration Mode -@cindex semantic-decoration-mode - -Semantic Tag Decoration mode ``decorates'' each tag based on certain -arbitrary features of that tag. Decorations are specified using the -variable @code{semantic-decoration-styles}. - -@deffn Command global-semantic-decoration-mode &optional arg -Toggle Semantic Tag Decoration mode in all Semantic-enabled buffers. -With an optional argument @var{arg}, enable if @var{arg} is positive, -and disable otherwise. -@end deffn - -@defvar semantic-decoration-styles -The value of this variable is a list of decoration styles for Semantic -Tag Decoration mode. Each element in this list should have the form -@code{(@var{name} . @var{flag})}, where @var{name} is a style name (a -symbol) and @var{flag} is non-@code{nil} if the style is enabled. - -The following styles are available: - -@table @code -@item semantic-tag-boundary -Place an overline in front of each long tag (excluding prototypes). - -@item semantic-decoration-on-private-members -Highlight class members that are designated as private. - -@item semantic-decoration-on-protected-members -Highlight class members that are designated as protected. - -@item semantic-decoration-on-includes -Highlight class members that are includes. Clicking on the -highlighted include statements opens a context menu for configuring -@semantic{} includes. -@end table -@end defvar - -To enable or disable specific decorations, use this function: - -@deffn Command semantic-toggle-decoration-style name &optional arg -Prompt for a decoration style, @var{name}, and turn it on or off. -With prefix argument @var{arg}, turn on if positive, otherwise off. -Return non-@code{nil} if the decoration style is enabled. -@end deffn - -@deffn Face semantic-tag-boundary-face -Face for long tags in the @code{semantic-tag-boundary} decoration -style. -@end deffn - -@deffn Face semantic-decoration-on-private-members-face -Face for privately-scoped tags in the -@code{semantic-decoration-on-private-members} decoration style. -@end deffn - -@deffn Face semantic-decoration-on-protected-members-face -Face for protected tags in the -@code{semantic-decoration-on-protected-members} decoration style. -@end deffn - -@deffn Face semantic-decoration-on-includes -Face for includes that are not in some other state, in the -@code{semantic-decoration-on-includes} decoration style. -@end deffn - -@deffn Face semantic-decoration-on-unknown-includes -Face for includes that cannot be found, in the -@code{semantic-decoration-on-includes} decoration style. -@end deffn - -@deffn Face semantic-decoration-on-unparsed-includes -Face for includes that have not yet been parsed, in the -@code{semantic-decoration-on-includes} decoration style. -@end deffn - -@subsection Creating New Decoration Modes - -You can create new types of decorations using the following function: - -@defun define-semantic-decoration-style name doc &rest flags -Define a new decoration style with @var{name}. -@var{doc} is a documentation string describing the decoration style @var{name}. -It is appended to auto-generated doc strings. -An optional list of @var{flags} can also be specified. Flags are: - @code{:enabled} - specify the default enabled value for @var{name}. - - -This defines two new overload functions respectively called @code{NAME-p} -and @code{NAME-highlight}, for which you must provide a default -implementation in respectively the functions @code{NAME-p-default} and -@code{NAME-highlight-default}. Those functions are passed a tag. @code{NAME-p} -must return non-@code{nil} to indicate that the tag should be decorated by -@code{NAME-highlight}. - -To put primary decorations on a tag @code{NAME-highlight}, use -functions like @dfn{semantic-set-tag-face}, -@dfn{semantic-set-tag-intangible}, etc., found in the -semantic-decorate library. - -To add other kind of decorations on a tag, @code{NAME-highlight} must use -@dfn{semantic-decorate-tag}, and other functions of the semantic -decoration @var{api} found in this library. -@end defun diff --git a/doc/misc/semantic.texi b/doc/misc/semantic.texi deleted file mode 100644 index 0b0d7a364d6..00000000000 --- a/doc/misc/semantic.texi +++ /dev/null @@ -1,627 +0,0 @@ -\input texinfo -@setfilename ../../info/semantic -@set TITLE Semantic Manual -@set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim -@settitle @value{TITLE} -@documentencoding UTF-8 - -@c ************************************************************************* -@c @ Header -@c ************************************************************************* - -@c Merge all indexes into a single index for now. -@c We can always separate them later into two or more as needed. -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex ky cp -@syncodeindex pg cp -@syncodeindex tp cp - -@c @footnotestyle separate -@c @paragraphindent 2 -@c @@smallbook -@c %**end of header - -@copying -This manual documents the Semantic library and utilities. - -Copyright @copyright{} 1999--2005, 2007, 2009--2014 Free Software -Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Semantic: (semantic). Source code parser library and utilities. -@end direntry - -@titlepage -@center @titlefont{Semantic} -@sp 4 -@center by @value{AUTHOR} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage -@page - -@macro semantic{} -@i{Semantic} -@end macro - -@macro keyword{kw} -@anchor{\kw\} -@b{\kw\} -@end macro - -@macro obsolete{old,new} -@sp 1 -@strong{Compatibility}: -@code{\new\} introduced in @semantic{} version 2.0 supersedes -@code{\old\} which is now obsolete. -@end macro - -@c ************************************************************************* -@c @ Document -@c ************************************************************************* -@contents - -@node top -@top @value{TITLE} - -@semantic{} is a suite of Emacs libraries and utilities for parsing -source code. At its core is a lexical analyzer and two parser -generators (@code{bovinator} and @code{wisent}) written in Emacs Lisp. -@semantic{} provides a variety of tools for making use of the parser -output, including user commands for code navigation and completion, as -well as enhancements for imenu, speedbar, whichfunc, eldoc, -hippie-expand, and several other parts of Emacs. - -To send bug reports, or participate in discussions about semantic, -use the mailing list cedet-semantic@@sourceforge.net via the URL: -@url{http://lists.sourceforge.net/lists/listinfo/cedet-semantic} - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Introduction:: -* Using Semantic:: -* Semantic Internals:: -* Glossary:: -* GNU Free Documentation License:: -* Index:: -@end menu - -@node Introduction -@chapter Introduction - -This chapter gives an overview of @semantic{} and its goals. - -Ordinarily, Emacs uses regular expressions (and syntax tables) to -analyze source code for purposes such as syntax highlighting. This -approach, though simple and efficient, has its limitations: roughly -speaking, it only ``guesses'' the meaning of each piece of source code -in the context of the programming language, instead of rigorously -``understanding'' it. - -@semantic{} provides a new infrastructure to analyze source code using -@dfn{parsers} instead of regular expressions. It contains two -built-in parser generators (an @acronym{LL} generator named -@code{Bovine} and an @acronym{LALR} generator named @code{Wisent}, -both written in Emacs Lisp), and parsers for several common -programming languages. It can also make use of @dfn{external -parsers}---programs such as GNU Global and GNU IDUtils. - -@semantic{} provides a uniform, language-independent @acronym{API} for -accessing the parser output. This output can be used by other Emacs -Lisp programs to implement ``syntax-aware'' behavior. @semantic{} -itself includes several such utilities, including user-level Emacs -commands for navigating, searching, and completing source code. - -The following diagram illustrates the structure of the @semantic{} -package: - -@table @strong -@item Please Note: -The words in all-capital are those that @semantic{} itself provides. -Others are current or future languages or applications that are not -distributed along with @semantic{}. -@end table - -@example - Applications - and - Utilities - ------- - / \ - +---------------+ +--------+ +--------+ - C --->| C PARSER |--->| | | | - +---------------+ | | | | - +---------------+ | COMMON | | COMMON |<--- SPEEDBAR - Java --->| JAVA PARSER |--->| PARSE | | | - +---------------+ | TREE | | PARSE |<--- SEMANTICDB - +---------------+ | FORMAT | | API | - Scheme --->| SCHEME PARSER |--->| | | |<--- ecb - +---------------+ | | | | - +---------------+ | | | | - Texinfo --->| TEXI. PARSER |--->| | | | - +---------------+ | | | | - - ... ... ... ... - - +---------------+ | | | | - Lang. Y --->| Y Parser |--->| | | |<--- app. ? - +---------------+ | | | | - +---------------+ | | | |<--- app. ? - Lang. Z --->| Z Parser |--->| | | | - +---------------+ +--------+ +--------+ -@end example - -@menu -* Semantic Components:: -@end menu - -@node Semantic Components -@section Semantic Components - -In this section, we provide a more detailed description of the major -components of @semantic{}, and how they interact with one another. - -The first step in parsing a source code file is to break it up into -its fundamental components. This step is called lexical analysis: - -@example - syntax table, keywords list, and options - | - | - v - input file ----> Lexer ----> token stream -@end example - -@noindent -The output of the lexical analyzer is a list of tokens that make up -the file. The next step is the actual parsing, shown below: - -@example - parser tables - | - v - token stream ---> Parser ----> parse tree -@end example - -@noindent -The end result, the parse tree, is @semantic{}'s internal -representation of the language grammar. @semantic{} provides an -@acronym{API} for Emacs Lisp programs to access the parse tree. - -Parsing large files can take several seconds or more. By default, -@semantic{} automatically caches parse trees by saving them in your -@file{.emacs.d} directory. When you revisit a previously-parsed file, -the parse tree is automatically reloaded from this cache, to save -time. @xref{SemanticDB}. - -@node Using Semantic -@chapter Using Semantic - -@include sem-user.texi - -@node Semantic Internals -@chapter Semantic Internals - -This chapter provides an overview of the internals of @semantic{}. -This information is usually not needed by application developers or -grammar developers; it is useful mostly for the hackers who would like -to learn more about how @semantic{} works. - -@menu -* Parser code:: Code used for the parsers -* Tag handling:: Code used for manipulating tags -* Semanticdb Internals:: Code used in the semantic database -* Analyzer Internals:: Code used in the code analyzer -* Tools:: Code used in user tools -* Tests:: Code used for testing -@end menu - -@node Parser code -@section Parser code - -@semantic{} parsing code is spread across a range of files. - -@table @file -@item semantic.el -The core infrastructure sets up buffers for parsing, and has all the -core parsing routines. Most parsing routines are overloadable, so the -actual implementation may be somewhere else. - -@item semantic-edit.el -Incremental reparse based on user edits. - -@item semantic-grammar.el -@itemx semantic-grammar.wy -Parser for the different grammar languages, and a major mode for -editing grammars in Emacs. - -@item semantic-lex.el -Infrastructure for implementing lexical analyzers. Provides macros -for creating individual analyzers for specific features, and a way to -combine them together. - -@item semantic-lex-spp.el -Infrastructure for a lexical symbolic preprocessor. This was written -to implement the C preprocessor, but could be used for other lexical -preprocessors. - -@item bovine/bovine-grammar.el -@itemx bovine/bovine-grammar-macros.el -@itemx bovine/semantic-bovine.el -The ``bovine'' grammar. This is the first grammar mode written for -@semantic{} and is useful for simple creating simple parsers. - -@item wisent/wisent.el -@itemx wisent/bison-wisent.el -@itemx wisent/semantic-wisent.el -@itemx wisent/semantic-debug-grammar.el -A port of bison to Emacs. This infrastructure lets you create LALR -based parsers for @semantic{}. - -@item semantic-ast.el -Manage Abstract Syntax Trees for parsers. - -@item semantic-debug.el -Infrastructure for debugging grammars. - -@item semantic-util.el -Various utilities for manipulating tags, such as describing the tag -under point, adding labels, and the all important -@code{semantic-something-to-tag-table}. - -@end table - -@node Tag handling -@section Tag handling - -A tag represents an individual item found in a buffer, such as a -function or variable. Tag handling is handled in several source -files. - -@table @file -@item semantic-tag.el -Basic tag creation, queries, cloning, binding, and unbinding. - -@item semantic-tag-write.el -Write a tag or tag list to a stream. These routines are used by -@file{semanticdb-file.el} when saving a list of tags. - -@item semantic-tag-file.el -Files associated with tags. Goto-tag, file for include, and file for -a prototype. - -@item semantic-tag-ls.el -Language dependent features of a tag, such as parent calculation, slot -protection, and other states like abstract, virtual, static, and leaf. - -@item semantic-dep.el -Include file handling. Contains the include path concepts, and -routines for looking up file names in the include path. - -@item semantic-format.el -Convert a tag into a nicely formatted and colored string. Use -@code{semantic-test-all-format-tag-functions} to test different output -options. - -@item semantic-find.el -Find tags matching different conditions in a tag table. -These routines are used by @file{semanticdb-find.el} once the database -has been converted into a simpler tag table. - -@item semantic-sort.el -Sorting lists of tags in different ways. Includes sorting a plain -list of tags forward or backward. Includes binning tags based on -attributes (bucketize), and tag adoption for multiple references to -the same thing. - -@item semantic-doc.el -Capture documentation comments from near a tag. - -@end table - -@node Semanticdb Internals -@section Semanticdb Internals - -@acronym{Semanticdb} complexity is certainly an issue. It is a rather -hairy problem to try and solve. - -@table @file -@item semanticdb.el -Defines a @dfn{database} and a @dfn{table} base class. You can -instantiate these classes, and use them, but they are not persistent. - -This file also provides support for @code{semanticdb-minor-mode}, -which automatically associates files with tables in databases so that -tags are @emph{saved} while a buffer is not in memory. - -The database and tables both also provide applicable cache information, -and cache flushing system. The semanticdb search routines use caches -to save data structures that are complex to calculate. - -Lastly, it provides the concept of @dfn{project root}. It is a system -by which a file can be associated with the root of a project, so if -you have a tree of directories and source files, it can find the root, -and allow a tag-search to span all available databases in that -directory hierarchy. - -@item semanticdb-file.el -Provides a subclass of the basic table so that it can be saved to -disk. Implements all the code needed to unbind/rebind tags to a -buffer and writing them to a file. - -@item semanticdb-el.el -Implements a special kind of @dfn{system} database that uses Emacs -internals to perform queries. - -@item semanticdb-ebrowse.el -Implements a system database that uses Ebrowse to parse files into a -table that can be queried for tag names. Successful tag hits during a -find causes @semantic{} to pick up and parse the reference files to -get the full details. - -@item semanticdb-find.el -Infrastructure for searching groups @semantic{} databases, and dealing -with the search results format. - -@item semanticdb-ref.el -Tracks crossreferences. Cross references are needed when buffer is -reparsed, and must alert other tables that any dependent caches may -need to be flushed. References are in the form of include files. - -@end table - -@node Analyzer Internals -@section Analyzer Internals - -The @semantic{} analyzer is a complex engine which has been broken -down across several modules. When the @semantic{} analyzer fails, -start with @code{semantic-analyze-debug-assist}, then dive into some -of these files. - -@table @file -@item semantic-analyze.el -The core analyzer for defining the @dfn{current context}. The -current context is an object that contains references to aspects of -the local context including the current prefix, and a tag list -defining what the prefix means. - -@item semantic-analyze-complete.el -Provides @code{semantic-analyze-possible-completions}. - -@item semantic-analyze-debug.el -The analyzer debugger. Useful when attempting to get everything -configured. - -@item semantic-analyze-fcn.el -Various support functions needed by the analyzer. - -@item semantic-ctxt.el -Local context parser. Contains overloadable functions used to move -around through different scopes, get local variables, and collect the -current prefix used when doing completion. - -@item semantic-scope.el -Calculate @dfn{scope} for a location in a buffer. The scope includes -local variables, and tag lists in scope for various reasons, such as -C++ using statements. - -@item semanticdb-typecache.el -The typecache is part of @code{semanticdb}, but is used primarily by -the analyzer to look up datatypes and complex names. The typecache is -bound across source files and builds a master lookup table for data -type names. - -@item semantic-ia.el -Interactive Analyzer functions. Simple routines that do completion or -lookups based on the results from the Analyzer. These routines are -meant as examples for application writers, but are quite useful as -they are. - -@item semantic-ia-sb.el -Speedbar support for the analyzer, displaying context info, and -completion lists. - -@end table - -@node Tools -@section Tools - -These files contain various tools a user can use. - -@table @file -@item semantic-idle.el -Idle scheduler for @semantic{}. Manages reparsing buffers after -edits, and large work tasks in idle time. Includes modes for showing -summary help and pop-up completion. - -@item senator.el -The @semantic{} navigator. Provides many ways to move through a -buffer based on the active tag table. - -@item semantic-decorate.el -A minor mode for decorating tags based on details from the parser. -Includes overlines for functions, or coloring class fields based on -protection. - -@item semantic-decorate-include.el -A decoration mode for include files, which assists users in setting up -parsing for their includes. - -@item semantic-complete.el -Advanced completion prompts for reading tag names in the minibuffer, or -inline in a buffer. - -@item semantic-imenu.el -Imenu support for using @semantic{} tags in imenu. - -@item semantic-mru-bookmark.el -Automatic bookmarking based on tags. Jump to locations you've been -before based on tag name. - -@item semantic-sb.el -Support for @semantic{} tag usage in Speedbar. - -@item semantic-util-modes.el -A bunch of small minor-modes that exposes aspects of the semantic -parser state. Includes @code{semantic-stickyfunc-mode}. - -@item document.el -@itemx document-vars.el -Create an update comments for tags. - -@item semantic-adebug.el -Extensions of @file{data-debug.el} for @semantic{}. - -@item semantic-chart.el -Draw some charts from stats generated from parsing. - - -@item semantic-elp.el -Profiler for helping to optimize the @semantic{} analyzer. - - -@end table - -@node Tests -@section Tests - -@table @file - -@item semantic-utest.el -Basic testing of parsing and incremental parsing for most supported -languages. - -@item semantic-ia-utest.el -Test the semantic analyzer's ability to provide smart completions. - -@item semantic-utest-c.el -Tests for the C parser's lexical pre-processor. - -@item semantic-regtest.el -Regression tests from the older Semantic 1.x API. - -@end table - -@node Glossary -@appendix Glossary - -@table @asis -@item BNF -In semantic 1.4, a BNF file represented ``Bovine Normal Form'', the -grammar file used for the 1.4 parser generator. This was a play on -Backus-Naur Form which proved too confusing. - -@item bovinate -A verb representing what happens when a bovine parser parses a file. - -@item bovine lambda -In a bovine, or LL parser, the bovine lambda is a function to execute -when a specific set of match rules has succeeded in matching text from -the buffer. - -@item bovine parser -A parser using the bovine parser generator. It is an LL parser -suitable for small simple languages. - -@item context - -@item LALR - -@item lexer -A program which converts text into a stream of tokens by analyzing -them lexically. Lexers will commonly create strings, symbols, -keywords and punctuation, and strip whitespaces and comments. - -@item LL - -@item nonterminal -A nonterminal symbol or simply a nonterminal stands for a class of -syntactically equivalent groupings. A nonterminal symbol name is used -in writing grammar rules. - -@item overloadable -Some functions are defined via @code{define-overload}. -These can be overloaded via .... - -@item parser -A program that converts @b{tokens} to @b{tags}. - -@item tag -A tag is a representation of some entity in a language file, such as a -function, variable, or include statement. In semantic, the word tag is -used the same way it is used for the etags or ctags tools. - -A tag is usually bound to a buffer region via overlay, or it just -specifies character locations in a file. - -@item token -A single atomic item returned from a lexer. It represents some set -of characters found in a buffer. - -@item token stream -The output of the lexer as well as the input to the parser. - -@item wisent parser -A parser using the wisent parser generator. It is a port of bison to -Emacs Lisp. It is an LALR parser suitable for complex languages. -@end table - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@iftex -@contents -@summarycontents -@end iftex - -@bye - -@c Following comments are for the benefit of ispell. - -@c LocalWords: alist API APIs arg argc args argv asis assoc autoload Wisent -@c LocalWords: backquote bnf bovinate bovinates LALR -@c LocalWords: bovinating bovination bovinator bucketize -@c LocalWords: cb cdr charquote checkcache cindex CLOS -@c LocalWords: concat concocting const ctxt Decl defcustom -@c LocalWords: deffn deffnx defun defvar destructor's dfn diff dir -@c LocalWords: doc docstring EDE EIEIO elisp emacsman emph enum -@c LocalWords: eq Exp EXPANDFULL expression fn foo func funcall -@c LocalWords: ia ids ifinfo imenu imenus init int isearch itemx java kbd -@c LocalWords: keymap keywordtable lang languagemode lexer lexing Ludlam -@c LocalWords: menubar metaparent metaparents min minibuffer Misc mode's -@c LocalWords: multitable NAvigaTOR noindent nomedian nonterm noselect -@c LocalWords: nosnarf obarray OLE OO outputfile paren parsetable POINT's -@c LocalWords: popup positionalonly positiononly positionormarker pre -@c LocalWords: printf printindex Programmatically pt quotemode -@c LocalWords: ref regex regexp Regexps reparse resetfile samp sb -@c LocalWords: scopestart SEmantic semanticdb setfilename setq -@c LocalWords: settitle setupfunction sexp sp SPC speedbar speedbar's -@c LocalWords: streamorbuffer struct subalist submenu submenus -@c LocalWords: subsubsection sw sym texi texinfo titlefont titlepage -@c LocalWords: tok TOKEN's toplevel typemodifiers uml unset untar -@c LocalWords: uref usedb var vskip xref yak diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi deleted file mode 100644 index 2e1159a98fe..00000000000 --- a/doc/misc/ses.texi +++ /dev/null @@ -1,1169 +0,0 @@ -\input texinfo @c -*- mode: texinfo; coding: utf-8; -*- -@c %**start of header -@setfilename ../../info/ses -@settitle @acronym{SES}: Simple Emacs Spreadsheet -@setchapternewpage off -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@documentencoding UTF-8 -@c %**end of header - -@copying -This file documents @acronym{SES}: the Simple Emacs Spreadsheet. - -Copyright @copyright{} 2002--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* @acronym{SES}: (ses). Simple Emacs Spreadsheet. -@end direntry - -@finalout - -@titlepage -@title @acronym{SES} -@subtitle Simple Emacs Spreadsheet -@author Jonathan A. Yavner -@author @email{jyavner@@member.fsf.org} - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c =================================================================== - -@ifnottex -@node Top -@comment node-name, next, previous, up -@top @acronym{SES}: Simple Emacs Spreadsheet - -@display -@acronym{SES} is a major mode for GNU Emacs to edit spreadsheet files, which -contain a rectangular grid of cells. The cells' values are specified -by formulas that can refer to the values of other cells. -@end display -@end ifnottex - -To report bugs, use @kbd{M-x report-emacs-bug}. - -@insertcopying - -@menu -* Sales Pitch:: Why use @acronym{SES}? -* Quick Tutorial:: A quick introduction -* The Basics:: Basic spreadsheet commands -* Advanced Features:: Want to know more? -* For Gurus:: Want to know @emph{even more}? -* Index:: Concept, Function and Variable Index -* Acknowledgments:: Acknowledgments -* GNU Free Documentation License:: The license for this documentation. -@end menu - -@c =================================================================== - -@node Sales Pitch -@comment node-name, next, previous, up -@chapter Sales Pitch -@cindex features - -@itemize @bullet -@item Create and edit simple spreadsheets with a minimum of fuss. -@item Full undo/redo/autosave. -@item Immune to viruses in spreadsheet files. -@item Cell formulas are straight Emacs Lisp. -@item Printer functions for control of cell appearance. -@item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc. -@item ``Spillover'' of lengthy cell values into following blank cells. -@item Header line shows column letters or a selected row. -@item Completing-read for entering symbols as cell values. -@item Cut, copy, and paste can transfer formulas and printer functions. -@item Import and export of tab-separated values or tab-separated formulas. -@item Plaintext, easily-hacked file format. -@end itemize - -@c =================================================================== - -@node Quick Tutorial -@chapter Quick Tutorial -@cindex introduction -@cindex tutorial - -If you want to get started quickly and think that you know what to -expect from a simple spreadsheet, this chapter may be all that you -need. - -First, visit a new file with the @file{.ses} extension. -Emacs presents you with an empty spreadsheet containing a single cell. - -Begin by inserting a headline: @kbd{"Income"@key{RET}}. The double -quotes indicate that this is a text cell. (Notice that Emacs -automatically inserts the closing quotation mark.) - -To insert your first income value, you must first resize the -spreadsheet. Press @key{TAB} to add a new cell and navigate back up -to it. Enter a number, such as @samp{2.23}. Then proceed to add a -few more income entries, e.g.: - -@example -@group -A - Income - 2.23 - 0.02 - 15.76 - -4.00 -@end group -@end example - -To add up the values, enter a Lisp expression: - -@example -(+ A2 A3 A4 A5) -@end example - -Perhaps you want to add a cell to the right of cell A4 to explain -why you have a negative entry. Pressing @kbd{TAB} in that cell -adds an entire new column @samp{B}, where you can add such a note. - -The column is fairly narrow by default, but pressing @kbd{w} allows -you to resize it as needed. Make it 20 characters wide. You can -now add descriptive legends for all the entries, e.g.: - -@example -@group -A B - Income - 2.23 Consulting fee - 0.02 Informed opinion - 15.76 Lemonade stand - -4 Loan to Joe - 14.01 Total -@end group -@end example - -By default, the labels in column B are right-justified. To change -that, you can enter a printer function for the whole column, using -e.g., @kbd{M-p ("%s")}. You can override a column's printer function -in any individual cell using @kbd{p}. - -If Joe pays back his loan, you might blank that entry; e.g., by -positioning the cursor in cell A5 and pressing @kbd{C-d} twice. -If you do that, the total cell will display @samp{######}. That is -because the regular @code{+} operator does not handle a range that -contains some empty cells. Instead of emptying the cell, you could -enter a literal @samp{0}, or delete the entire row using @kbd{C-k}. -An alternative is to use the special function @code{ses+} instead of -the regular @code{+}: - -@example -(ses+ A2 A3 A4 A5) -@end example - -To make a formula robust against changes in the spreadsheet geometry, -you can use the @code{ses-range} macro to refer to a range of cells by -the end-points, e.g.: - -@example -(apply 'ses+ (ses-range A2 A5)) -@end example - -(The @code{apply} is necessary because @code{ses-range} produces a -@emph{list} of values. This allows for more complex possibilities.) - -@c =================================================================== - -@node The Basics -@comment node-name, next, previous, up -@chapter The Basics -@cindex basic commands -@findex ses-jump -@findex ses-mark-row -@findex ses-mark-column -@findex ses-mark-whole-buffer -@findex set-mark-command -@findex keyboard-quit - -To create a new spreadsheet, visit a nonexistent file whose name ends - with ".ses". For example, @kbd{C-x C-f test.ses RET}. - - -A @dfn{cell identifier} is a symbol with a column letter and a row -number. Cell B7 is the 2nd column of the 7th row. For very wide -spreadsheets, there are two column letters: cell AB7 is the 28th -column of the 7th row. Super wide spreadsheets get AAA1, etc. -You move around with the regular Emacs movement commands. - -@table @kbd -@item j -Moves point to cell, specified by identifier (@code{ses-jump}). -@end table - -Point is always at the left edge of a cell, or at the empty endline. -When mark is inactive, the current cell is underlined. When mark is -active, the range is the highlighted rectangle of cells (@acronym{SES} always -uses transient mark mode). Drag the mouse from A1 to A3 to create the -range A1-A2. Many @acronym{SES} commands operate only on single cells, not -ranges. - -@table @kbd -@item C-@key{SPC} -@itemx C-@@ -Set mark at point (@code{set-mark-command}). - -@item C-g -Turn off the mark (@code{keyboard-quit}). - -@item M-h -Highlight current row (@code{ses-mark-row}). - -@item S-M-h -Highlight current column (@code{ses-mark-column}). - -@item C-x h -Highlight all cells (@code{mark-whole-buffer}). -@end table - -@menu -* Formulas:: -* Resizing:: -* Printer functions:: -* Clearing cells:: -* Copy/cut/paste:: -* Customizing @acronym{SES}:: -@end menu - -@node Formulas -@section Cell formulas -@cindex formulas -@cindex formulas, entering -@cindex values -@cindex cell values -@cindex editing cells -@findex ses-read-cell -@findex ses-read-symbol -@findex ses-edit-cell -@findex ses-recalculate-cell -@findex ses-recalculate-all - -To insert a value into a cell, simply type a numeric expression, -@samp{"double-quoted text"}, or a Lisp expression. - -@table @kbd -@item 0..9 -Self-insert a digit (@code{ses-read-cell}). - -@item - -Self-insert a negative number (@code{ses-read-cell}). - -@item . -Self-insert a fractional number (@code{ses-read-cell}). - -@item " -Self-insert a quoted string. The ending double-quote -is inserted for you (@code{ses-read-cell}). - -@item ( -Self-insert an expression. The right-parenthesis is inserted for you -(@code{ses-read-cell}). To access another cell's value, just use its -identifier in your expression. Whenever the other cell is changed, -this cell's formula will be reevaluated. While typing in the -expression, you can use @kbd{M-@key{TAB}} to complete symbol names. - -@item ' @r{(apostrophe)} -Enter a symbol (ses-read-symbol). @acronym{SES} remembers all symbols that have -been used as formulas, so you can type just the beginning of a symbol -and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it. -@end table - -To enter something else (e.g., a vector), begin with a digit, then -erase the digit and type whatever you want. - -@table @kbd -@item RET -Edit the existing formula in the current cell (@code{ses-edit-cell}). - -@item C-c C-c -Force recalculation of the current cell or range (@code{ses-recalculate-cell}). - -@item C-c C-l -Recalculate the entire spreadsheet (@code{ses-recalculate-all}). -@end table - -@node Resizing -@section Resizing the spreadsheet -@cindex resizing spreadsheets -@cindex dimensions -@cindex row, adding or removing -@cindex column, adding or removing -@cindex adding rows or columns -@cindex inserting rows or columns -@cindex removing rows or columns -@cindex deleting rows or columns -@findex ses-insert-row -@findex ses-insert-column -@findex ses-delete-row -@findex ses-delete-column -@findex ses-set-column-width -@findex ses-forward-or-insert -@findex ses-append-row-jump-first-column - - -Basic commands: - -@table @kbd -@item C-o -(@code{ses-insert-row}) - -@item M-o -(@code{ses-insert-column}) - -@item C-k -(@code{ses-delete-row}) - -@item M-k -(@code{ses-delete-column}) - -@item w -(@code{ses-set-column-width}) - -@item TAB -Moves point to the next rightward cell, or inserts a new column if -already at last cell on line, or inserts a new row if at endline -(@code{ses-forward-or-insert}). - -@item C-j -Linefeed inserts below the current row and moves to column A -(@code{ses-append-row-jump-first-column}). -@end table - -Resizing the spreadsheet (unless you're just changing a column width) -relocates all the cell-references in formulas so they still refer to -the same cells. If a formula mentioned B1 and you insert a new first -row, the formula will now mention B2. - -If you delete a cell that a formula refers to, the cell-symbol is -deleted from the formula, so @code{(+ A1 B1 C1)} after deleting the third -column becomes @code{(+ A1 B1)}. In case this is not what you wanted: - -@table @kbd -@item C-_ -@itemx C-x u -Undo previous action (@code{(undo)}). -@end table - - -@node Printer functions -@section Printer functions -@cindex printer functions -@cindex cell formatting -@cindex formatting cells -@findex ses-read-cell-printer -@findex ses-read-column-printer -@findex ses-read-default-printer -@findex ses-center -@findex ses-center-span -@findex ses-dashfill -@findex ses-dashfill-span -@findex ses-tildefill-span - - -Printer functions convert binary cell values into the print forms that -Emacs will display on the screen. - -A printer can be a format string, like @samp{"$%.2f"}. The result -string is right-aligned within the print cell. To get left-alignment, -use parentheses: @samp{("$%.2f")}. A printer can also be a -one-argument function (a symbol or a lambda), whose result is a string -(right-aligned) or list of one string (left-aligned). While typing in -a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols. - -Each cell has a printer. If @code{nil}, the column-printer for the cell's -column is used. If that is also @code{nil}, the default-printer for the -spreadsheet is used. - -@table @kbd -@item p -Enter a printer for current cell or range (@code{ses-read-cell-printer}). - -@item M-p -Enter a printer for the current column (@code{ses-read-column-printer}). - -@item C-c C-p -Enter the default printer for the spreadsheet -(@code{ses-read-default-printer}). -@end table - -The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer -history, which is preloaded with the set of all printers used in this -spreadsheet, plus the standard printers. - -The standard printers are suitable only for cells, not columns or -default, because they format the value using the column-printer (or -default-printer if @code{nil}) and then center the result: - -@table @code -@item ses-center -Just centering. - -@item ses-center-span -Centering with spill-over to following blank cells. - -@item ses-dashfill -Centering using dashes (-) instead of spaces. - -@item ses-dashfill-span -Centering with dashes and spill-over. - -@item ses-tildefill-span -Centering with tildes (~) and spill-over. -@end table - - -@node Clearing cells -@section Clearing cells -@cindex clearing commands -@findex ses-clear-cell-backward -@findex ses-clear-cell-forward - -These commands set both formula and printer to @code{nil}: - -@table @kbd -@item DEL -Clear cell and move left (@code{ses-clear-cell-backward}). - -@item C-d -Clear cell and move right (@code{ses-clear-cell-forward}). -@end table - - -@node Copy/cut/paste -@section Copy, cut, and paste -@cindex copy -@cindex cut -@cindex paste -@findex kill-ring-save -@findex mouse-set-region -@findex mouse-set-secondary -@findex ses-kill-override -@findex yank -@findex clipboard-yank -@findex mouse-yank-at-click -@findex mouse-yank-at-secondary -@findex ses-yank-pop - -The copy functions work on rectangular regions of cells. You can paste the -copies into non-@acronym{SES} buffers to export the print text. - -@table @kbd -@item M-w -@itemx [copy] -@itemx [C-insert] -Copy the highlighted cells to kill ring and primary clipboard -(@code{kill-ring-save}). - -@item [drag-mouse-1] -Mark a region and copy it to kill ring and primary clipboard -(@code{mouse-set-region}). - -@item [M-drag-mouse-1] -Mark a region and copy it to kill ring and secondary clipboard -(@code{mouse-set-secondary}). - -@item C-w -@itemx [cut] -@itemx [S-delete] -The cut functions do not actually delete rows or columns---they copy -and then clear (@code{ses-kill-override}). - -@item C-y -@itemx [S-insert] -Paste from kill ring (@code{yank}). The paste functions behave -differently depending on the format of the text being inserted: -@itemize @bullet -@item -When pasting cells that were cut from a @acronym{SES} buffer, the print text is -ignored and only the attached formula and printer are inserted; cell -references in the formula are relocated unless you use @kbd{C-u}. -@item -The pasted text overwrites a rectangle of cells whose top left corner -is the current cell. If part of the rectangle is beyond the edges of -the spreadsheet, you must confirm the increase in spreadsheet size. -@item -Non-@acronym{SES} text is usually inserted as a replacement formula for the -current cell. If the formula would be a symbol, it's treated as a -string unless you use @kbd{C-u}. Pasted formulas with syntax errors -are always treated as strings. -@end itemize - -@item [paste] -Paste from primary clipboard or kill ring (@code{clipboard-yank}). - -@item [mouse-2] -Set point and paste from primary clipboard (@code{mouse-yank-at-click}). - -@item [M-mouse-2] -Set point and paste from secondary clipboard (@code{mouse-yank-secondary}). - -@item M-y -Immediately after a paste, you can replace the text with a preceding -element from the kill ring (@code{ses-yank-pop}). Unlike the standard -Emacs yank-pop, the @acronym{SES} version uses @code{undo} to delete the old -yank. This doesn't make any difference? -@end table - -@node Customizing @acronym{SES} -@section Customizing @acronym{SES} -@cindex customizing -@vindex enable-local-eval -@vindex ses-mode-hook -@vindex safe-functions -@vindex enable-local-eval - - -By default, a newly-created spreadsheet has 1 row and 1 column. The -column width is 7 and the default printer is @samp{"%.7g"}. Each of these -can be customized. Look in group ``ses''. - -After entering a cell value, point normally moves right to the next -cell. You can customize @code{ses-after-entry-functions} to move left or -up or down. For diagonal movement, select two functions from the -list. - -@code{ses-mode-hook} is a normal mode hook (list of functions to -execute when starting @acronym{SES} mode for a buffer). - -The variable @code{safe-functions} is a list of possibly-unsafe -functions to be treated as safe when analyzing formulas and printers. -@xref{Virus protection}. Before customizing @code{safe-functions}, -think about how much you trust the person who's suggesting this -change. The value @code{t} turns off all anti-virus protection. A -list-of-functions value might enable a ``gee whiz'' spreadsheet, but it -also creates trapdoors in your anti-virus armor. In order for virus -protection to work, you must always press @kbd{n} when presented with -a virus warning, unless you understand what the questionable code is -trying to do. Do not listen to those who tell you to customize -@code{enable-local-eval}---this variable is for people who don't wear -safety belts! - - -@c =================================================================== - -@node Advanced Features -@chapter Advanced Features -@cindex advanced features -@findex ses-read-header-row - - -@table @kbd -@item C-c M-C-h -(@code{ses-set-header-row}). -@findex ses-set-header-row -@kindex C-c M-C-h -The header line at the top of the @acronym{SES} -window normally shows the column letter for each column. You can set -it to show a copy of some row, such as a row of column titles, so that -row will always be visible. Default is to set the current row as the -header; use C-u to prompt for header row. Set the header to row 0 to -show column letters again. -@item [header-line mouse-3] -Pops up a menu to set the current row as the header, or revert to -column letters. -@item M-x ses-rename-cell -@findex ses-rename-cell -Rename a cell from a standard A1-like name to any -string. -@item M-x ses-repair-cell-reference-all -@findex ses-repair-cell-reference-all -When you interrupt a cell formula update by clicking @kbd{C-g}, then -the cell reference link may be broken, which will jeopardize automatic -cell update when any other cell on which it depends is changed. To -repair that use function @code{ses-repair-cell-reference-all} -@end table - -@menu -* The print area:: -* Ranges in formulas:: -* Sorting by column:: -* Standard formula functions:: -* More on cell printing:: -* Import and export:: -* Virus protection:: -* Spreadsheets with details and summary:: -@end menu - -@node The print area -@section The print area -@cindex print area -@findex widen -@findex ses-renarrow-buffer -@findex ses-reprint-all - -A @acronym{SES} file consists of a print area and a data area. Normally the -buffer is narrowed to show only the print area. The print area is -read-only except for special @acronym{SES} commands; it contains cell values -formatted by printer functions. The data area records the formula and -printer functions, etc. - -@table @kbd -@item C-x n w -Show print and data areas (@code{widen}). - -@item C-c C-n -Show only print area (@code{ses-renarrow-buffer}). - -@item S-C-l -@itemx M-C-l -Recreate print area by reevaluating printer functions for all cells -(@code{ses-reprint-all}). -@end table - -@node Ranges in formulas -@section Ranges in formulas -@cindex ranges -@findex ses-insert-range-click -@findex ses-insert-range -@findex ses-insert-ses-range-click -@findex ses-insert-ses-range -@vindex from -@vindex to - -A formula like -@lisp -(+ A1 A2 A3) -@end lisp -is the sum of three specific cells. If you insert a new second row, -the formula becomes -@lisp -(+ A1 A3 A4) -@end lisp -and the new row is not included in the sum. - -The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of -the values in a rectangle of cells. If your formula is -@lisp -(apply '+ (ses-range A1 A3)) -@end lisp -and you insert a new second row, it becomes -@lisp -(apply '+ (ses-range A1 A4)) -@end lisp -and the new row is included in the sum. - -While entering or editing a formula in the minibuffer, you can select -a range in the spreadsheet (using mouse or keyboard), then paste a -representation of that range into your formula. Suppose you select -A1-C1: - -@table @kbd -@item [S-mouse-3] -Inserts "A1 B1 C1" @code{(ses-insert-range-click}) - -@item C-c C-r -Keyboard version (@code{ses-insert-range}). - -@item [C-S-mouse-3] -Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}). - -@item C-c C-s -Keyboard version (@code{ses-insert-ses-range}). -@end table - -If you delete the @var{from} or @var{to} cell for a range, the nearest -still-existing cell is used instead. If you delete the entire range, -the formula relocator will delete the ses-range from the formula. - -If you insert a new row just beyond the end of a one-column range, or -a new column just beyond a one-row range, the new cell is included in -the range. New cells inserted just before a range are not included. - -Flags can be added to @code{ses-range} immediately after the @var{to} -cell. -@table @code -@item ! -Empty cells in range can be removed by adding the @code{!} flag. An -empty cell is a cell the value of which is one of symbols @code{nil} -or @code{*skip*}. For instance @code{(ses-range A1 A4 !)} will do the -same as @code{(list A1 A3)} when cells @code{A2} and @code{A4} are -empty. -@item _ -Empty cell values are replaced by the argument following flag -@code{_}, or @code{0} when flag @code{_} is last in argument list. For -instance @code{(ses-range A1 A4 _ "empty")} will do the same as -@code{(list A1 "empty" A3 "empty")} when cells @code{A2} and @code{A4} -are empty. Similarly, @code{(ses-range A1 A4 _ )} will do the same as -@code{(list A1 0 A3 0)}. -@item >v -When order matters, list cells by reading cells row-wise from top left -to bottom right. This flag is provided for completeness only as it is -the default reading order. -@item -List cells by reading cells column-wise from top left to bottom right. -@item v< -List cells by reading cells column-wise from top right to bottom left. -@item v -A short hand for @code{v>}. -@item ^ -A short hand for @code{^>}. -@item > -A short hand for @code{>v}. -@item < -A short hand for @code{>^}. -@item * -Instead of listing cells, it makes a Calc vector or matrix of it -(@pxref{Top,,,calc,GNU Emacs Calc Manual}). If the range contains only -one row or one column a vector is made, otherwise a matrix is made. -@item *2 -Same as @code{*} except that a matrix is always made even when there -is only one row or column in the range. -@item *1 -Same as @code{*} except that a vector is always made even when there -is only one row or column in the range, that is to say the -corresponding matrix is flattened. -@end table - -@node Sorting by column -@section Sorting by column -@cindex sorting -@findex ses-sort-column -@findex ses-sort-column-click - -@table @kbd -@item C-c M-C-s -Sort the cells of a range using one of the columns -(@code{ses-sort-column}). The rows (or partial rows if the range -doesn't include all columns) are rearranged so the chosen column will -be in order. - -@item [header-line mouse-2] -The easiest way to sort is to click mouse-2 on the chosen column's header row -(@code{ses-sort-column-click}). -@end table - -The sort comparison uses @code{string<}, which works well for -right-justified numbers and left-justified strings. - -With prefix arg, sort is in descending order. - -Rows are moved one at a time, with relocation of formulas. This works -well if formulas refer to other cells in their row, not so well for -formulas that refer to other rows in the range or to cells outside the -range. - - -@node Standard formula functions -@section Standard formula functions -@cindex standard formula functions -@cindex *skip* -@cindex *error* -@findex ses-delete-blanks -@findex ses-average -@findex ses+ - -Oftentimes you want a calculation to exclude the blank cells. Here -are some useful functions to call from your formulas: - -@table @code -@item (ses-delete-blanks &rest @var{args}) -Returns a list from which all blank cells (value is either @code{nil} or -'*skip*) have been deleted. - -@item (ses+ &rest @var{args}) -Sum of non-blank arguments. - -@item (ses-average @var{list}) -Average of non-blank elements in @var{list}. Here the list is passed -as a single argument, since you'll probably use it with @code{ses-range}. -@end table - -@node More on cell printing -@section More on cell printing -@cindex cell printing, more -@findex ses-truncate-cell -@findex ses-recalculate-cell - -Special cell values: -@itemize -@item nil prints the same as "", but allows previous cell to spill over. -@item '*skip* replaces nil when the previous cell actually does spill over; -nothing is printed for it. -@item '*error* indicates that the formula signaled an error instead of -producing a value: the print cell is filled with hash marks (#). -@end itemize - -If the result from the printer function is too wide for the cell and -the following cell is @code{nil}, the result will spill over into the -following cell. Very wide results can spill over several cells. If -the result is too wide for the available space (up to the end of the -row or the next non-@code{nil} cell), the result is truncated if the cell's -value is a string, or replaced with hash marks otherwise. - -@acronym{SES} could get confused by printer results that contain newlines or -tabs, so these are replaced with question marks. - -@table @kbd -@item t -Confine a cell to its own column (@code{ses-truncate-cell}). This -allows you to move point to a rightward cell that would otherwise be -covered by a spill-over. If you don't change the rightward cell, the -confined cell will spill over again the next time it is reprinted. - -@item c -When applied to a single cell, this command displays in the echo area -any formula error or printer error that occurred during -recalculation/reprinting (@code{ses-recalculate-cell}). You can use -this to undo the effect of @kbd{t}. -@end table - -When a printer function signals an error, the fallback printer -@samp{"%s"} is substituted. This is useful when your column printer -is numeric-only and you use a string as a cell value. Note that the -standard default printer is ``%.7g'' which is numeric-only, so cells -that are empty of contain strings will use the fallback printer. -@kbd{c} on such cells will display ``Format specifier doesn't match -argument type''. - - -@node Import and export -@section Import and export -@cindex import and export -@cindex export, and import -@findex ses-export-tsv -@findex ses-export-tsf - -@table @kbd -@item x t -Export a range of cells as tab-separated values (@code{ses-export-tsv}). -@item x T -Export a range of cells as tab-separated formulas (@code{ses-export-tsf}). -@end table - -The exported text goes to the kill ring; you can paste it into -another buffer. Columns are separated by tabs, rows by newlines. - -To import text, use any of the yank commands where the text to paste -contains tabs and/or newlines. Imported formulas are not relocated. - -@node Virus protection -@section Virus protection -@cindex virus protection - -Whenever a formula or printer is read from a file or is pasted into -the spreadsheet, it receives a ``needs safety check'' marking. Later, -when the formula or printer is evaluated for the first time, it is -checked for safety using the @code{unsafep} predicate; if found to be -``possibly unsafe'', the questionable formula or printer is displayed -and you must press Y to approve it or N to use a substitute. The -substitute always signals an error. - -Formulas or printers that you type in are checked immediately for -safety. If found to be possibly unsafe and you press N to disapprove, -the action is canceled and the old formula or printer will remain. - -Besides viruses (which try to copy themselves to other files), -@code{unsafep} can also detect all other kinds of Trojan horses, such as -spreadsheets that delete files, send email, flood Web sites, alter -your Emacs settings, etc. - -Generally, spreadsheet formulas and printers are simple things that -don't need to do any fancy computing, so all potentially-dangerous -parts of the Emacs Lisp environment can be excluded without cramping -your style as a formula-writer. See the documentation in @file{unsafep.el} -for more info on how Lisp forms are classified as safe or unsafe. - -@node Spreadsheets with details and summary -@section Spreadsheets with details and summary -@cindex details and summary -@cindex summary, and details - -A common organization for spreadsheets is to have a bunch of ``detail'' -rows, each perhaps describing a transaction, and then a set of -``summary'' rows that each show reduced data for some subset of the -details. @acronym{SES} supports this organization via the @code{ses-select} -function. - -@table @code -@item (ses-select @var{fromrange} @var{test} @var{torange}) -Returns a subset of @var{torange}. For each member in @var{fromrange} -that is equal to @var{test}, the corresponding member of @var{torange} -is included in the result. -@end table - -Example of use: -@lisp -(ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5))) -@end lisp -This computes the average of the B column values for those rows whose -A column value is the symbol 'Smith. - -Arguably one could specify only @var{fromrange} plus -@var{to-row-offset} and @var{to-column-offset}. The @var{torange} is -stated explicitly to ensure that the formula will be recalculated if -any cell in either range is changed. - -File @file{etc/ses-example.el} in the Emacs distribution is an example of a -details-and-summary spreadsheet. - - -@c =================================================================== - -@node For Gurus -@chapter For Gurus -@cindex advanced features - -@menu -* Deferred updates:: -* Nonrelocatable references:: -* The data area:: -* Buffer-local variables in spreadsheets:: -* Uses of defadvice in @acronym{SES}:: -@end menu - -@node Deferred updates -@section Deferred updates -@cindex deferred updates -@cindex updates, deferred -@vindex run-with-idle-timer - -To save time by avoiding redundant computations, cells that need -recalculation due to changes in other cells are added to a set. At -the end of the command, each cell in the set is recalculated once. -This can create a new set of cells that need recalculation. The -process is repeated until either the set is empty or it stops changing -(due to circular references among the cells). In extreme cases, you -might see progress messages of the form ``Recalculating... (@var{nnn} -cells left)''. If you interrupt the calculation using @kbd{C-g}, the -spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or -@kbd{C-c C-l} to fix it. - -To save even more time by avoiding redundant writes, cells that have -changes are added to a set instead of being written immediately to the -data area. Each cell in the set is written once, at the end of the -command. If you change vast quantities of cells, you might see a -progress message of the form ``Writing... (@var{nnn} cells left)''. -These deferred cell-writes cannot be interrupted by @kbd{C-g}, so -you'll just have to wait. - -@acronym{SES} uses @code{run-with-idle-timer} to move the cell underline when -Emacs will be scrolling the buffer after the end of a command, and -also to narrow and underline after @kbd{C-x C-v}. This is visible as -a momentary glitch after C-x C-v and certain scrolling commands. You -can type ahead without worrying about the glitch. - - -@node Nonrelocatable references -@section Nonrelocatable references -@cindex nonrelocatable references -@cindex references, nonrelocatable - -@kbd{C-y} relocates all cell-references in a pasted formula, while -@kbd{C-u C-y} relocates none of the cell-references. What about mixed -cases? - -You can use -@lisp -(symbol-value 'B3) -@end lisp -to make an @dfn{absolute reference}. The formula relocator skips over -quoted things, so this will not be relocated when pasted or when -rows/columns are inserted/deleted. However, B3 will not be recorded -as a dependency of this cell, so this cell will not be updated -automatically when B3 is changed. - -The variables @code{row} and @code{col} are dynamically bound while a -cell formula is being evaluated. You can use -@lisp -(ses-cell-value row 0) -@end lisp -to get the value from the leftmost column in the current row. This -kind of dependency is also not recorded. - - -@node The data area -@section The data area -@cindex data area -@findex ses-reconstruct-all - -Begins with an 014 character, followed by sets of cell-definition -macros for each row, followed by column-widths, column-printers, -default-printer, and header-row. Then there's the global parameters -(file-format ID, numrows, numcols) and the local variables (specifying -@acronym{SES} mode for the buffer, etc.). - -When a @acronym{SES} file is loaded, first the numrows and numcols values are -loaded, then the entire data area is @code{eval}ed, and finally the local -variables are processed. - -You can edit the data area, but don't insert or delete any newlines -except in the local-variables part, since @acronym{SES} locates things by -counting newlines. Use @kbd{C-x C-e} at the end of a line to install -your edits into the spreadsheet data structures (this does not update -the print area, use, e.g., @kbd{C-c C-l} for that). - -The data area is maintained as an image of spreadsheet data -structures that area stored in buffer-local variables. If the data -area gets messed up, you can try reconstructing the data area from the -data structures: - -@table @kbd -@item C-c M-C-l -(@code{ses-reconstruct-all}). -@end table - - -@node Buffer-local variables in spreadsheets -@section Buffer-local variables in spreadsheets -@cindex buffer-local variables -@cindex variables, buffer-local - -You can add additional local variables to the list at the bottom of -the data area, such as hidden constants you want to refer to in your -formulas. - -You can override the variable @code{ses--symbolic-formulas} to be a list of -symbols (as parenthesized strings) to show as completions for the ' -command. This initial completions list is used instead of the actual -set of symbols-as-formulas in the spreadsheet. - -For an example of this, see file @file{etc/ses-example.ses}. - -If (for some reason) you want your formulas or printers to save data -into variables, you must declare these variables as buffer-locals in -order to avoid a virus warning. - -You can define functions by making them values for the fake local -variable @code{eval}. Such functions can then be used in your -formulas and printers, but usually each @code{eval} is presented to -the user during file loading as a potential virus. This can get -annoying. - -You can define functions in your @file{.emacs} file. Other people can -still read the print area of your spreadsheet, but they won't be able -to recalculate or reprint anything that depends on your functions. To -avoid virus warnings, each function used in a formula needs -@lisp -(put 'your-function-name 'safe-function t) -@end lisp - -@node Uses of defadvice in @acronym{SES} -@section Uses of defadvice in @acronym{SES} -@cindex defadvice -@cindex undo-more -@cindex copy-region-as-kill -@cindex yank - -@table @code -@item undo-more -Defines a new undo element format (@var{fun} . @var{args}), which -means ``undo by applying @var{fun} to @var{args}''. For spreadsheet -buffers, it allows undos in the data area even though that's outside -the narrowing. - -@item copy-region-as-kill -When copying from the print area of a spreadsheet, treat the region as -a rectangle and attach each cell's formula and printer as 'ses -properties. - -@item yank -When yanking into the print area of a spreadsheet, first try to yank -as cells (if the yank text has 'ses properties), then as tab-separated -formulas, then (if all else fails) as a single formula for the current -cell. -@end table - -@c =================================================================== -@node Index -@unnumbered Index - -@printindex cp - -@c =================================================================== - -@node Acknowledgments -@unnumbered Acknowledgments - -Coding by: -@quotation -@c jyavner@@member.fsf.org -Jonathan Yavner, -@c monnier@@gnu.org -Stefan Monnier, -@c shigeru.fukaya@@gmail.com -Shigeru Fukaya -@end quotation - -@noindent -Texinfo manual by: -@quotation -@c jyavner@@member.fsf.org -Jonathan Yavner, -@c brad@@chenla.org -Brad Collins -@end quotation - -@noindent -Ideas from: -@quotation -@c christoph.conrad@@gmx.de -Christoph Conrad, -@c cyberbob@@redneck.gacracker.org -CyberBob, -@c syver-en@@online.no -Syver Enstad, -@c fischman@@zion.bpnetworks.com -Ami Fischman, -@c Thomas.Gehrlein@@t-online.de -Thomas Gehrlein, -@c c.f.a.johnson@@rogers.com -Chris F.A. Johnson, -@c lyusong@@hotmail.com -Yusong Li, -@c juri@@jurta.org -Juri Linkov, -@c maierh@@myself.com -Harald Maier, -@c anash@@san.rr.com -Alan Nash, -@c pinard@@iro.umontreal.ca -François Pinard, -@c ppinto@@cs.cmu.edu -Pedro Pinto, -@c xsteve@@riic.at -Stefan Reichör, -@c epameinondas@@gmx.de -Oliver Scholz, -@c rms@@gnu.org -Richard M. Stallman, -@c teirllm@@dms.auburn.edu -Luc Teirlinck, -@c jotto@@pobox.com -J. Otto Tennant, -@c jphil@@acs.pagesjaunes.fr -Jean-Philippe Theberge -@end quotation - -@c =================================================================== - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi deleted file mode 100644 index 422468c2210..00000000000 --- a/doc/misc/sieve.texi +++ /dev/null @@ -1,366 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@include gnus-overrides.texi - -@setfilename ../../info/sieve -@settitle Emacs Sieve Manual -@documentencoding UTF-8 -@synindex fn cp -@synindex vr cp -@synindex pg cp - -@copying -This file documents the Emacs Sieve package, for server-side mail filtering. - -Copyright @copyright{} 2001--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs network features -@direntry -* Sieve: (sieve). Managing Sieve scripts in Emacs. -@end direntry -@iftex -@finalout -@end iftex -@setchapternewpage odd - -@titlepage -@ifset WEBHACKDEVEL -@title Emacs Sieve Manual (DEVELOPMENT VERSION) -@end ifset -@ifclear WEBHACKDEVEL -@title Emacs Sieve Manual -@end ifclear - -@author by Simon Josefsson -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@node Top -@top Sieve Support for Emacs - -This is intended as a users manual for Sieve Mode and Manage Sieve, and -as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp -API. - -Sieve is a language for server-side filtering of mail. The language -is documented in RFC 3028. This manual does not attempt to document -the language, so keep RFC 3028 around. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Installation:: Getting ready to use the package. -* Sieve Mode:: Editing Sieve scripts. -* Managing Sieve:: Managing Sieve scripts on a remote server. -* Examples :: A few Sieve code snippets. -* Manage Sieve API :: Interfacing to the Manage Sieve Protocol API. -* Standards:: A summary of RFCs and working documents used. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Function and variable index. -@end menu - - -@node Installation -@chapter Installation -@cindex Install -@cindex Setup - -The Sieve package should come with your Emacs version, and should be -ready for use directly. - -However, to manually set up the package you can put the following -commands in your @code{~/.emacs}: - -@lisp -(autoload 'sieve-mode "sieve-mode") -@end lisp -@lisp -(setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode) - auto-mode-alist)) -@end lisp - - -@node Sieve Mode -@chapter Sieve Mode - -Sieve mode provides syntax-based indentation, font-locking support and -other handy functions to make editing Sieve scripts easier. - -Use @samp{M-x sieve-mode} to switch to this major mode. This command -runs the hook @code{sieve-mode-hook}. - -@vindex sieve-mode-map -@vindex sieve-mode-syntax-table -Sieve mode is derived from @code{c-mode}, and is very similar except -for the syntax of comments. The keymap (@code{sieve-mode-map}) is -inherited from @code{c-mode}, as are the variables for customizing -indentation. Sieve mode has its own abbrev table -(@code{sieve-mode-abbrev-table}) and syntax table -(@code{sieve-mode-syntax-table}). - -In addition to the editing utility functions, Sieve mode also contains -bindings to manage Sieve scripts remotely. @xref{Managing Sieve}. - -@table @kbd - -@item C-c RET -@kindex C-c RET -@findex sieve-manage -@cindex manage remote sieve script -Open a connection to a remote server using the Managesieve protocol. - -@item C-c C-l -@kindex C-c C-l -@findex sieve-upload -@cindex upload sieve script -Upload the Sieve script to the currently open server. - -@end table - - -@node Managing Sieve -@chapter Managing Sieve - -Manage Sieve is a special mode used to display Sieve scripts available -on a remote server. It can be invoked with @kbd{M-x sieve-manage -RET}, which queries the user for a server and if necessary, user -credentials to use. - -When a server has been successfully contacted, the Manage Sieve buffer -looks something like: - -@example -Server : mailserver:sieve - -2 scripts on server, press RET on a script name edits it, or -press RET on to create a new script. - - ACTIVE .sieve - template.siv -@end example - -One of the scripts are highlighted, and standard point navigation -commands (@kbd{}, @kbd{} etc.)@: can be used to navigate the -list. - -The following commands are available in the Manage Sieve buffer: - -@table @kbd - -@item m -@kindex m -@findex sieve-activate -Activates the currently highlighted script. - -@item u -@kindex u -@findex sieve-deactivate -Deactivates the currently highlighted script. - -@item C-M-? -@kindex C-M-? -@findex sieve-deactivate-all -Deactivates all scripts. - -@item r -@kindex r -@findex sieve-remove -Remove currently highlighted script. - -@item RET -@item mouse-2 -@item f -@kindex RET -@kindex mouse-2 -@kindex f -@findex sieve-edit-script -Bury the server buffer and download the currently highlighted script -into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}). - -@item o -@kindex o -@findex sieve-edit-script-other-window -Create a new buffer in another window containing the currently -highlighted script for editing in Sieve mode (@pxref{Sieve Mode}). - -@item q -@kindex q -@findex sieve-bury-buffer -Bury the Manage Sieve buffer without closing the connection. - -@item ? -@item h -@kindex ? -@kindex h -@findex sieve-help -Displays help in the minibuffer. - -@item Q -@kindex Q -@findex sieve-manage-quit -Quit Manage Sieve and close the connection. - -@end table - -@node Examples -@chapter Examples - -If you are not familiar with Sieve, this chapter contains a few simple -code snippets that you can cut'n'paste and modify at will, until you -feel more comfortable with the Sieve language to write the rules from -scratch. - -The following complete Sieve script places all messages with a matching -@samp{Sender:} header into the given mailbox. Many mailing lists uses -this format. The first line makes sure your Sieve server understands -the @code{fileinto} command. - -@example -require "fileinto"; - -if address "sender" "owner-w3-beta@@xemacs.org" @{ - fileinto "INBOX.w3-beta"; -@} -@end example - -A few mailing lists do not use the @samp{Sender:} header, but has a -unique identifier in some other header. The following is not a -complete script, it assumes that @code{fileinto} has already been -required. - -@example -if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{ - fileinto "INBOX.auc-tex"; -@} -@end example - -At last, we have the hopeless mailing lists that does not have any -unique identifier and you are forced to match on the @samp{To:} and -@samp{Cc} headers. As before, this snippet assumes that @code{fileinto} -has been required. - -@example -if address ["to", "cc"] "kerberos@@mit.edu" @{ - fileinto "INBOX.kerberos"; -@} -@end example - -@node Manage Sieve API -@chapter Manage Sieve API - -The @file{sieve-manage.el} library contains low-level functionality -for talking to a server with the @sc{managesieve} protocol. - -A number of user-visible variables exist, which all can be customized -in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}): - -@table @code - -@item sieve-manage-default-port -@vindex sieve-manage-default-port -Sets the default port to use, the suggested port number is @code{2000}. - -@item sieve-manage-log -@vindex sieve-manage-log -If non-@code{nil}, should be a string naming a buffer where a protocol trace -is dumped (for debugging purposes). - -@end table - -The API functions include: - -@table @code - -@item sieve-manage-open -@findex sieve-manage-open -Open connection to managesieve server, returning a buffer to be used -by all other API functions. - -@item sieve-manage-opened -@findex sieve-manage-opened -Check if a server is open or not. - -@item sieve-manage-close -@findex sieve-manage-close -Close a server connection. - -@item sieve-manage-authenticate -@findex sieve-manage-authenticate -Authenticate to the server. - -@item sieve-manage-capability -@findex sieve-manage-capability -Return a list of capabilities the server supports. - -@item sieve-manage-listscripts -@findex sieve-manage-listscripts -List scripts on the server. - -@item sieve-manage-havespace -@findex sieve-manage-havespace -Return non-@code{nil} if the server has room for a script of given -size. - -@item sieve-manage-getscript -@findex sieve-manage-getscript -Download script from server. - -@item sieve-manage-putscript -@findex sieve-manage-putscript -Upload script to server. - -@item sieve-manage-setactive -@findex sieve-manage-setactive -Indicate which script on the server should be active. - -@end table - -@node Standards -@chapter Standards - -The Emacs Sieve package implements all or parts of a small but -hopefully growing number of RFCs and drafts documents. This chapter -lists the relevant ones. They can all be fetched from -@uref{http://quimby.gnus.org/notes/}. - -@table @dfn - -@item RFC3028 -Sieve: A Mail Filtering Language. - -@item RFC5804 -A Protocol for Remotely Managing Sieve Scripts - -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@bye - -@c End: diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi deleted file mode 100644 index cb22dc87d2a..00000000000 --- a/doc/misc/smtpmail.texi +++ /dev/null @@ -1,443 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/smtpmail -@settitle Emacs SMTP Library -@documentencoding UTF-8 -@syncodeindex vr fn -@copying -Copyright @copyright{} 2003--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs lisp libraries -@direntry -* SMTP: (smtpmail). Emacs library for sending mail via SMTP. -@end direntry - -@titlepage -@title Emacs SMTP Library -@subtitle An Emacs package for sending mail via SMTP -@author Simon Josefsson, Alex Schroeder -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs SMTP Library - -@insertcopying -@end ifnottex - -@menu -* How Mail Works:: Brief introduction to mail concepts. -* Emacs Speaks SMTP:: How to use the SMTP library in Emacs. -* Authentication:: Authenticating yourself to the server. -* Encryption:: Protecting your connection to the server. -* Queued delivery:: Sending mail without an internet connection. -* Server workarounds:: Mail servers with special requirements. -* Debugging:: Tracking down problems. -* GNU Free Documentation License:: The license for this documentation. - -Indices - -* Index:: Index over variables and functions. -@end menu - -@node How Mail Works -@chapter How Mail Works - -@cindex SMTP -@cindex MTA - On the internet, mail is sent from mail host to mail host using the -simple mail transfer protocol (SMTP). To send and receive mail, you -must get it from and send it to a mail host. Every mail host runs a -mail transfer agent (MTA) such as Exim that accepts mails and passes -them on. The communication between a mail host and other clients does -not necessarily involve SMTP, however. Here is short overview of what -is involved. - -@cindex MUA - The mail program---also called a mail user agent (MUA)---usually -sends outgoing mail to a mail host. When your computer is -permanently connected to the internet, it might even be a mail host -itself. In this case, the MUA will pipe mail to the -@file{/usr/lib/sendmail} application. It will take care of your mail -and pass it on to the next mail host. - -@cindex ISP - When you are only connected to the internet from time to time, your -internet service provider (ISP) has probably told you which mail host -to use. You must configure your MUA to use that mail host. Since you -are reading this manual, you probably want to configure Emacs to use -SMTP to send mail to that mail host. More on that in the next -section. - -@cindex MDA - Things are different when reading mail. The mail host responsible -for your mail keeps it in a file somewhere. The messages get into the -file by way of a mail delivery agent (MDA) such as procmail. These -delivery agents often allow you to filter and munge your mails before -you get to see it. When your computer is that mail host, this file is -called a spool, and sometimes located in the directory -@file{/var/spool/mail/}. All your MUA has to do is read mail from the -spool, then. - -@cindex POP3 -@cindex IMAP - When your computer is not always connected to the internet, you -must get the mail from the remote mail host using a protocol such as -POP3 or IMAP@. POP3 essentially downloads all your mail from the mail -host to your computer. The mail is stored in some file on your -computer, and again, all your MUA has to do is read mail from the -spool. - - When you read mail from various machines, downloading mail from the -mail host to your current machine is not convenient. In that case, -you will probably want to use the IMAP protocol. Your mail is kept on -the mail host, and you can read it while you are connected via IMAP to -the mail host. - -@cindex Webmail - So how does reading mail via the web work, you ask. In that case, -the web interface just allows you to remote-control a MUA on the web -host. Whether the web host is also a mail host, and how all the -pieces interact is completely irrelevant. You usually cannot use -Emacs to read mail via the web, unless you use software that parses -the ever-changing HTML of the web interface. - -@node Emacs Speaks SMTP -@chapter Emacs Speaks SMTP - - Emacs includes a package for sending your mail to a SMTP server and -have it take care of delivering it to the final destination, rather -than letting the MTA on your local system take care of it. This can -be useful if you don't have a MTA set up on your host, or if your -machine is often disconnected from the internet. - - Sending mail via SMTP requires configuring your mail user agent -(@pxref{Mail Methods,,,emacs}) to use the SMTP library. If you -have not configured anything, then in Emacs 24.1 and later the first -time you try to send a mail Emacs will ask how you want to send -mail. To use this library, answer @samp{smtp} when prompted. Emacs -then asks for the name of the SMTP server. - - If you prefer, or if you are using a non-standard mail user agent, -you can configure this yourself. The normal way to do this is to set -the variable @code{send-mail-function} (@pxref{Mail -Sending,,,emacs}) to the value you want to use. To use this library: - -@smallexample -(setq send-mail-function 'smtpmail-send-it) -@end smallexample - -@noindent -The default value for this variable is @code{sendmail-query-once}, -which interactively asks how you want to send mail. - -Your mail user agent might use a different variable for this purpose. -It should inherit from @code{send-mail-function}, but if it does not, -or if you prefer, you can set that variable directly. Consult your -mail user agent's documentation for more details. For example, -(@pxref{Mail Variables,,,message}). - - Before using SMTP you must find out the hostname of the SMTP server -to use. Your system administrator or mail service provider should -supply this information. Often it is some variant of the server you -receive mail from. If your email address is -@samp{yourname@@example.com}, then the name of the SMTP server is -may be something like @samp{smtp.example.com}. - -@table @code -@item smtpmail-smtp-server -@vindex smtpmail-smtp-server -@vindex SMTPSERVER - The variable @code{smtpmail-smtp-server} controls the hostname of -the server to use. It is a string with an IP address or hostname. It -defaults to the contents of the @env{SMTPSERVER} environment -variable, or, if empty, the contents of -@code{smtpmail-default-smtp-server}. - -@item smtpmail-default-smtp-server -@vindex smtpmail-default-smtp-server - The variable @code{smtpmail-default-smtp-server} controls the -default hostname of the server to use. It is a string with an IP -address or hostname. It must be set before the SMTP library is -loaded. It has no effect if set after the SMTP library has been -loaded, or if @code{smtpmail-smtp-server} is defined. It is usually -set by system administrators in a site wide initialization file. -@end table - -The following example illustrates what you could put in -@file{~/.emacs} to set the SMTP server name. - -@example -;; Send mail using SMTP via mail.example.org. -(setq smtpmail-smtp-server "mail.example.org") -@end example - -@cindex Mail Submission -SMTP is normally used on the registered ``smtp'' TCP service port 25. -Some environments use SMTP in ``Mail Submission'' mode, which uses -port 587. Using other ports is not uncommon, either for security by -obscurity purposes, port forwarding, or otherwise. - -@table @code -@item smtpmail-smtp-service -@vindex smtpmail-smtp-service - The variable @code{smtpmail-smtp-service} controls the port on the -server to contact. It is either a string, in which case it will be -translated into an integer using system calls, or an integer. -@end table - -The following example illustrates what you could put in -@file{~/.emacs} to set the SMTP service port. - -@example -;; Send mail using SMTP on the mail submission port 587. -(setq smtpmail-smtp-service 587) -@end example - -@node Authentication -@chapter Authentication - -@cindex password -@cindex user name -Most SMTP servers require clients to authenticate themselves before -they are allowed to send mail. Authentication usually involves -supplying a user name and password. - -If you have not configured anything, then the first time you try to -send mail via a server, Emacs (version 24.1 and later) prompts you -for the user name and password to use, and then offers to save the -information. By default, Emacs stores authentication information in -a file @file{~/.authinfo}. - -@cindex authinfo -The basic format of the @file{~/.authinfo} file is one line for each -set of credentials. Each line consists of pairs of variables and -values. A simple example would be: - -@smallexample -machine mail.example.org port 25 login myuser password mypassword -@end smallexample - -@noindent -This specifies that when using the SMTP server called @samp{mail.example.org} -on port 25, Emacs should send the user name @samp{myuser} and the -password @samp{mypassword}. Either or both of the login and password -fields may be absent, in which case Emacs prompts for the information -when you try to send mail. (This replaces the old -@code{smtpmail-auth-credentials} variable used prior to Emacs 24.1.) - -@vindex smtpmail-smtp-user - When the SMTP library connects to a host on a certain port, it -searches the @file{~/.authinfo} file for a matching entry. If an -entry is found, the authentication process is invoked and the -credentials are used. If the variable @code{smtpmail-smtp-user} is -set to a non-@code{nil} value, then only entries for that user are -considered. For more information on the @file{~/.authinfo} -file, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. - -@cindex SASL -@cindex CRAM-MD5 -@cindex PLAIN -@cindex LOGIN -The process by which the SMTP library authenticates you to the server -is known as ``Simple Authentication and Security Layer'' (SASL). -There are various SASL mechanisms, and this library supports three of -them: CRAM-MD5, PLAIN, and LOGIN@. It tries each of them, in that order, -until one succeeds. The first uses a form of encryption to obscure -your password, while the other two do not. - - -@node Encryption -@chapter Encryption - -@cindex STARTTLS -@cindex TLS -@cindex SSL -For greater security, you can encrypt your connection to the SMTP -server. If this is to work, both Emacs and the server must support it. - -The SMTP library supports the ``Transport Layer Security'' (TLS), and -the older ``Secure Sockets Layer'' (SSL) encryption mechanisms. -It also supports STARTTLS, which is a variant of TLS in which the -initial connection to the server is made in plain text, requesting a -switch to an encrypted channel for the rest of the process. - -@vindex smtpmail-stream-type -The variable @code{smtpmail-stream-type} controls what form of -connection the SMTP library uses. The default value is @code{nil}, -which means to use a plain connection, but try to switch to a STARTTLS -encrypted connection if the server supports it. Other possible values -are: @code{starttls} to insist on STARTTLS; @code{ssl} to use TLS/SSL; -and @code{plain} for encryption. - -Use of any form of TLS/SSL requires support in Emacs. You can either -use the built-in support (in Emacs 24.1 and later), or the -@file{starttls.el} Lisp library. The built-in support uses the GnuTLS -@footnote{@url{http://www.gnu.org/software/gnutls/}} library. -If your Emacs has GnuTLS support built-in, the function -@code{gnutls-available-p} is defined and returns non-@code{nil}. -Otherwise, you must use the @file{starttls.el} library (see that file for -more information on customization options, etc.). The Lisp library -requires one of the following external tools to be installed: - -@enumerate -@item -The GnuTLS command line tool @samp{gnutls-cli}, which you can get from -@url{http://www.gnu.org/software/gnutls/}. This is the recommended -tool, mainly because it can verify server certificates. - -@item -The @samp{starttls} external program, which you can get from -@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}. -@end enumerate - -@cindex certificates -@cindex keys -The SMTP server may also request that you verify your identity by -sending a certificate and the associated encryption key to the server. -If you need to do this, you can use an @file{~/.authinfo} entry like this: - -@smallexample -machine mail.example.org port 25 key "~/.my_smtp_tls.key" cert "~/.my_smtp_tls.cert" -@end smallexample - -@noindent -(This replaces the old @code{smtpmail-starttls-credentials} variable used -prior to Emacs 24.1.) - - -@node Queued delivery -@chapter Queued delivery - -@cindex Dialup connection -If you connect to the internet via a dialup connection, or for some -other reason don't have permanent internet connection, sending mail -will fail when you are not connected. The SMTP library implements -queued delivery, and the following variable control its behavior. - -@table @code -@item smtpmail-queue-mail -@vindex smtpmail-queue-mail - The variable @code{smtpmail-queue-mail} controls whether a simple -off line mail sender is active. This variable is a boolean, and -defaults to @code{nil} (disabled). If this is non-@code{nil}, mail is -not sent immediately but rather queued in the directory -@code{smtpmail-queue-dir} and can be later sent manually by invoking -@code{smtpmail-send-queued-mail} (typically when you connect to the -internet). - -@item smtpmail-queue-dir -@vindex smtpmail-queue-dir - The variable @code{smtpmail-queue-dir} specifies the name of the -directory to hold queued messages. It defaults to -@file{~/Mail/queued-mail/}. -@end table - -@findex smtpmail-send-queued-mail - The function @code{smtpmail-send-queued-mail} can be used to send -any queued mail when @code{smtpmail-queue-mail} is enabled. It is -typically invoked interactively with @kbd{M-x -smtpmail-send-queued-mail RET} when you are connected to the internet. - -@node Server workarounds -@chapter Server workarounds - -Some SMTP servers have special requirements. The following variables -implement support for common requirements. - -@table @code - -@item smtpmail-local-domain -@vindex smtpmail-local-domain - The variable @code{smtpmail-local-domain} controls the hostname sent -in the first @code{EHLO} or @code{HELO} command sent to the server. -It should only be set if the @code{system-name} function returns a -name that isn't accepted by the server. Do not set this variable -unless your server complains. - -@item smtpmail-sendto-domain -@vindex smtpmail-sendto-domain - The variable @code{smtpmail-sendto-domain} makes the SMTP library -add @samp{@@} and the specified value to recipients specified in the -message when they are sent using the @code{RCPT TO} command. Some -configurations of sendmail requires this behavior. Don't bother to -set this unless you have get an error like: - -@example - Sending failed; SMTP protocol error -@end example - -when sending mail, and the debug buffer (@pxref{Debugging})) contains -an error such as: - -@example - RCPT TO: @var{someone} - 501 @var{someone}: recipient address must contain a domain -@end example - -@end table - - -@node Debugging -@chapter Debugging - -Sometimes delivery fails, often with the generic error message -@samp{Sending failed; SMTP protocol error}. Enabling one or both of -the following variables and inspecting a trace buffer will often give -clues to the reason for the error. - -@table @code - -@item smtpmail-debug-info -@vindex smtpmail-debug-info - The variable @code{smtpmail-debug-info} controls whether to print -the SMTP protocol exchange in the minibuffer, and retain the entire -exchange in a buffer @file{*trace of SMTP session to @var{server}*}, -where @var{server} is the name of the mail server to which you send -mail. - -@item smtpmail-debug-verb -@vindex smtpmail-debug-verb - The variable @code{smtpmail-debug-verb} controls whether to send the -@code{VERB} token to the server. The @code{VERB} server instructs the -server to be more verbose, and often also to attempt final delivery -while your SMTP session is still running. It is usually only useful -together with @code{smtpmail-debug-info}. Note that this may cause -mail delivery to take considerable time if the final destination -cannot accept mail. - -@end table - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index - -@section Concept Index - -@printindex cp - -@section Function and Variable Index - -@printindex fn - -@bye diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi deleted file mode 100644 index f5acc254c53..00000000000 --- a/doc/misc/speedbar.texi +++ /dev/null @@ -1,1232 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/speedbar -@settitle Speedbar: File/Tag summarizing utility -@documentencoding UTF-8 -@syncodeindex fn cp - -@copying -Copyright @copyright{} 1999--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Speedbar: (speedbar). File/Tag summarizing utility. -@end direntry - -@titlepage -@sp 10 -@center @titlefont{Speedbar} -@sp 2 -@center Eric Ludlam -@vskip 0pt plus 1 fill -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top Speedbar - -Speedbar is a program for Emacs which can be used to summarize -information related to the current buffer. Its original inspiration -is the `explorer' often used in modern development environments, office -packages, and web browsers. - -Speedbar displays a narrow frame in which a tree view is shown. This -tree view defaults to containing a list of files and directories. Files -can be `expanded' to list tags inside. Directories can be expanded to -list the files within itself. Each file or tag can be jumped to -immediately. - -Speedbar expands upon `explorer' windows by maintaining context with the -user. For example, when using the file view, the current buffer's file -is highlighted. Speedbar also mimics the explorer windows by providing -multiple display modes. These modes come in two flavors. Major display -modes remain consistent across buffers, and minor display modes appear -only when a buffer of the applicable type is shown. This allows -authors of other packages to provide speedbar summaries customized to -the needs of that mode. - -Throughout this manual, activities are defined as `clicking on', or -`expanding' items. Clicking means using @kbd{Mouse-2} on a -button. Expanding refers to clicking on an expansion button to display -an expanded summary of the entry the expansion button is -on. @xref{Basic Navigation}. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Introduction:: Basics of speedbar. -* Basic Navigation:: Basics of speedbar common between all modes. -* File Mode:: Summarizing files. -* Buffer Mode:: Summarizing buffers. -* Minor Modes:: Additional minor modes such as Info and RMAIL. -* Customizing:: Changing speedbar behavior. -* Extending:: Extend speedbar for your own project. -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - -@node Introduction -@chapter Introduction -@cindex introduction - -To start using speedbar use the command @kbd{M-x speedbar RET} or -select it from the @samp{Options->Show/Hide} sub-menu. This command -will open a new frame to summarize the local files. On X Window -systems or on MS-Windows, speedbar's frame is twenty characters wide, -and will mimic the height of the frame from which it was started. It -positions itself to the left or right of the frame you started it -from. - -To use speedbar effectively, it is important to understand its -relationship with the frame you started it from. This frame is the -@dfn{attached frame} which speedbar will use as a reference point. Once -started, speedbar watches the contents of this frame, and attempts to -make its contents relevant to the buffer loaded into the attached -frame. In addition, all requests made in speedbar that require the -display of another buffer will display in the attached frame. - -When used in terminal mode, the new frame appears the same size as the -terminal. Since it is not visible while working in the attached frame, -speedbar will save time by using the @dfn{slowbar mode}, where no tracking is -done until speedbar is requested to show itself (i.e., the speedbar's -frame becomes the selected frame). - -@cindex @code{speedbar-get-focus} -The function to use when switching between frames using the keyboard is -@code{speedbar-get-focus}. This function will toggle between frames, and -it's useful to bind it to a key in terminal mode. @xref{Customizing}. - -@node Basic Navigation -@chapter Basic Navigation - -Speedbar can display different types of data, and has several display -and behavior modes. These modes all have a common behavior, menu -system, and look. If one mode is learned, then the other modes are easy -to use. - -@menu -* Basic Key Bindings:: -* Basic Visuals:: -* Mouse Bindings:: -* Displays Submenu:: -@end menu - -@node Basic Key Bindings -@section Basic Key Bindings -@cindex key bindings - -These key bindings are common across all modes: - -@table @kbd -@item Q -@cindex quitting speedbar -Quit speedbar, and kill the frame. -@item q -Quit speedbar, and hide the frame. This makes it faster to restore the -speedbar frame, than if you press @kbd{Q}. -@item g -@cindex refresh speedbar display -Refresh whatever contents are in speedbar. -@item t -@cindex slowbar mode -Toggle speedbar to and from slowbar mode. In slowbar mode, frame -tracking is not done. -@item n -@itemx p -@cindex navigation -Move, respectively, to the next or previous item. A summary of that -item will be displayed in the attached frame's minibuffer. -@item M-n -@itemx M-p -Move to the next or previous item in a restricted fashion. If a list is -open, the cursor will skip over it. If the cursor is in an open list, -it will not leave it. -@item C-M-n -@itemx C-M-p -Move forwards and backwards across extended groups. This lets you -quickly skip over all files, directories, or other common sub-items at -the same current depth. -@item C-x b -Switch buffers in the attached frame. -@end table - -Speedbar can handle multiple modes. Two are provided by default. -These modes are File mode, and Buffers mode. There are accelerators to -switch into these different modes. - -@cindex mode switching hotkeys -@table @kbd -@item b -Switch into Quick Buffers mode (@pxref{Buffer Mode}). After one use, the -previous display mode is restored. -@item f -Switch into File mode. -@item r -Switch back to the previous mode. -@end table - -Some modes provide groups, lists and tags. @xref{Basic Visuals}. When -these are available, some additional common bindings are available. - -@cindex common keys -@table @kbd -@item RET -@itemx e -Edit/Open the current group or tag. This behavior is dependent on the -mode. In general, files or buffers are opened in the attached frame, -and directories or group nodes are expanded locally. -@item + -@itemx = -Expand the current group, displaying sub items. -When used with a prefix argument, any data that may have been cached is -flushed. This is similar to a power click. @xref{Mouse Bindings}. -@item - -Contract the current group, hiding sub items. -@end table - -@node Basic Visuals -@section Basic Visuals -@cindex visuals - -Speedbar has visual cues for indicating different types of data. These -cues are used consistently across the different speedbar modes to make -them easier to interpret. - -At a high level, in File mode, there are directory buttons, sub -directory buttons, file buttons, tag buttons, and expansion buttons. -This makes it easy to use the mouse to navigate a directory tree, and -quickly view files, or a summary of those files. - -The most basic visual effect used to distinguish between these button -types is color and mouse highlighting. Anything the mouse highlights -can be clicked on and is called a button (@pxref{Mouse Bindings}). -Anything not highlighted by the mouse will not be clickable. - -Text in speedbar consists of four different types of data. Knowing how -to read these textual elements will make it easier to navigate by -identifying the types of data available. - -@subsection Groups -@cindex groups - -Groups summarize information in a single line, and provide a high level -view of more complex systems, like a directory tree, or manual chapters. - -Groups appear at different indentation levels, and are prefixed with a -@samp{+} in some sort of `box'. The group name will summarize the -information within it, and the expansion box will display that -information inline. In File mode, directories and files are `groups' -where the @samp{+} is surrounded by brackets like this: - -@example -<+> include -<-> src - [+] foo.c -@end example - -In this example, we see both open and closed directories, in addition to -a file. The directories have a box consisting of angle brackets, and a -file uses square brackets. - -In all modes, a group can be `edited' by pressing @kbd{RET}, meaning a -file will be opened, or a directory explicitly opened in speedbar. A -group can be expanded or contracted using @kbd{+} or -@kbd{-}. @xref{Basic Key Bindings}. - -Sometimes groups may have a @samp{?} in its indicator box. This means -that it is a group type, but there are no contents, or no known way of -extracting contents of that group. - -When a group has been expanded, the indicator button changes from -@samp{+} to @samp{-}. This indicates that the contents are being shown. -Click the @samp{-} button to contract the group, or hide the contents -currently displayed. - -@subsubsection Tags -@cindex tags - -Tags are the leaf nodes of the tree system. Tags are generally prefixed -with a simple character, such as @samp{>}. Tags can only be jumped to using -@kbd{RET} or @kbd{e}. - -@subsubsection Boolean Flags - -Sometimes a group or tag is given a boolean flag. These flags appear as -extra text characters at the end of the line. File mode uses boolean -flags, such as a @samp{*} to indicate that a file has been checked out -of a versioning system. - -For additional flags, see -@c Note to self, update these to sub-nodes which are more relevant. -@ref{File Mode}, and @ref{Version Control}. - -@subsubsection Unadorned Text - -Unadorned text generally starts in column 0, without any special symbols -prefixing them. In Buffers mode different buffer groups are prefixed -with a description of what the following buffers are (Files, scratch -buffers, and invisible buffers.) - -Unadorned text will generally be colorless, and not clickable. - -@subsubsection Color Cues - -Each type of Group, item indicator, and label is given a different -color. The colors chosen are dependent on whether the background color -is light or dark. -Of important note is that the `current item', which may be a buffer or -file name, is highlighted red, and underlined. - -Colors can be customized from the group @code{speedbar-faces}. Some -modes, such as for Info, will use the Info colors instead of default -speedbar colors as an indication of what is currently being displayed. - -The face naming convention mirrors the File display mode. Modes which -do not use files will attempt to use the same colors on analogous -entries. - -@node Mouse Bindings -@section Mouse Bindings -@cindex mouse bindings - -The mouse has become a common information navigation tool. Speedbar -will use the mouse to navigate file systems, buffer lists, and other -data. The different textual cues provide buttons which can be clicked -on (@pxref{Basic Visuals}). Anything that highlights can be clicked on -with the mouse, or affected by the menu. - -The mouse bindings are: - -@table @kbd -@item Mouse-1 -Move cursor to that location. -@item Mouse-2 -@itemx Double-Mouse-1 -Activate the current button. @kbd{Double-Mouse-1} is called a @dfn{double -click} on other platforms, and is useful for windows users with two -button mice. -@c Isn't it true that with two-button mice, the right button is Mouse-2? -@c On GNU/Linux, the right button is Mouse-3. -@item S-Mouse-2 -@itemx S-Double-Mouse-1 -@cindex power click -This has the same effect as @kbd{Mouse-2}, except it is called a power -click. This means that if a group with an expansion button @samp{+} is -clicked, any caches are flushed, and subitems re-read. If it is a name, -it will be opened in a new frame. -@item Mouse-3 -Activate the speedbar menu. The item selected affects the line clicked, -not the line where the cursor was. -@item Mouse-1 @r{(mode line)} -Activate the menu. This affects the item the cursor is on before the -click, since the mouse was not clicked on anything. -@item C-Mouse-1 -Buffers sub-menu. The buffer in the attached frame is switched. -@end table - -When the mouse moves over buttons in speedbar, details of that item -should be displayed in the minibuffer of the attached frame. Sometimes -this can contain extra information such as file permissions, or tag -location. - -@node Displays Submenu -@section Displays Submenu -@cindex displays submenu - -You can display different data by using different display modes. These -specialized modes make it easier to navigate the relevant pieces of -information, such as files and directories, or buffers. - -In the main menu, found by clicking @kbd{Mouse-3}, there is a submenu -labeled @samp{Displays}. This submenu lets you easily choose between -different display modes. - -The contents are modes currently loaded into emacs. By default, this -would include Files, Quick Buffers, and Buffers. Other major display -modes such as Info are loaded separately. - -@node File Mode -@chapter File Mode -@cindex file mode - -File mode displays a summary of your current directory. You can display -files in the attached frame, or summarize the tags found in files. You -can even see if a file is checked out of a version control system, or -has some associated object file. - -Advanced behavior, like copying and renaming files, is also provided. - -@menu -* Directory Display:: What the display means. -* Hidden Files:: How to display hidden files. -* File Key Bindings:: Performing file operations. -@end menu - -@node Directory Display -@section Directory Display -@cindex directory display - -There are three major sections in the display. The first line or two is -the root directory speedbar is currently viewing. You can jump to one -of the parent directories by clicking on the name of the directory you -wish to jump to. - -Next, directories are listed. A directory starts with the group -indicator button @samp{<+>}. Clicking the directory name makes speedbar -load that directory as the root directory for its display. Clicking the -@samp{<+>} button will list all directories and files beneath. - -Next, files are listed. Files start with the group indicator @samp{[+]} -or @samp{[?]}. You can jump to a file in the attached frame by clicking -on the file name. You can expand a file and look at its tags by -clicking on the @samp{[+]} symbol near the file name. - -A typical session might look like this: - -@example -~/lisp/ -<+> checkdoc -<+> eieio -<-> speedbar - [+] Makefile - [+] rpm.el # - [+] sb-gud.el # - [+] sb-info.el # - [+] sb-rmail.el # - [+] sb-w3.el - [-] speedbar.el *! - @{+@} Types - @{+@} Variables - @{+@} def (group) - @{+@} speedbar- - [+] speedbar.texi * -<+> testme -[+] align.el -[+] autoconf.el -@end example - -In this example, you can see several directories. The directory -@file{speedbar} has been opened inline. Inside the directory -@file{speedbar}, the file @file{speedbar.el} has its tags exposed. -These tags are extensive, and they are summarized into tag groups. - -Files get additional boolean flags associated with them. Valid flags are: - -@cindex file flags -@table @code -@item * -This file has been checked out of a version control -system. @xref{Version Control}. -@cindex @code{speedbar-obj-alist} -@item # -This file has an up to date object file associated with it. The -variable @code{speedbar-obj-alist} defines how speedbar determines this -value. -@item ! -This file has an out of date object file associated with it. -@end table - -A Tag group is prefixed with the symbol @samp{@{+@}}. Clicking this -symbol will show all symbols that have been organized into that group. -Different types of files have unique tagging methods as defined by their -major mode. Tags are generated with either the @code{imenu} package, or -through the @code{etags} interface. - -Tag groups are defined in multiple ways which make it easier to find the -tag you are looking for. Imenu keywords explicitly create groups, and -speedbar will automatically create groups if tag lists are too long. - -In our example, Imenu created the groups @samp{Types} and -@samp{Variables}. All remaining top-level symbols are then regrouped -based on the variable @code{speedbar-tag-hierarchy-method}. The -subgroups @samp{def} and @samp{speedbar-} are groupings where the first -few characters of the given symbols are specified in the group name. -Some group names may say something like @samp{speedbar-t to speedbar-v}, -indicating that all symbols which alphabetically fall between those -categories are included in that sub-group. @xref{Tag Hierarchy Methods}. - -@node Hidden Files -@section Hidden Files -@cindex hidden files - -On GNU and Unix systems, a hidden file is a file whose name starts -with a period. They are hidden from a regular directory listing -because the user is not generally interested in them. - -In speedbar, a hidden file is a file which isn't very interesting and -might prove distracting to the user. Any uninteresting files are -removed from the File display. There are two levels of uninterest in -speedbar. The first level of uninterest are files which have no -expansion method, or way of extracting tags. The second level is any -file that matches the same pattern used for completion in -@code{find-file}. This is derived from the variable -@code{completion-ignored-extensions}. - -You can toggle the display of uninteresting files from the toggle menu -item @samp{Show All Files}. This will display all level one hidden files. -These files will be shown with a @samp{?} indicator. Level 2 hidden -files will still not be shown. - -Object files fall into the category of level 2 hidden files. You can -determine their presence by the @samp{#} and @samp{!} file indicators. -@xref{Directory Display}. - -@node File Key Bindings -@section File Key Bindings -@cindex file key bindings - -File mode has key bindings permitting different file system operations -such as copy or rename. These commands all operate on the @dfn{current -file}. In this case, the current file is the file at point, or clicked -on when pulling up the menu. - -@table @kbd -@item U -Move the entire speedbar display up one directory. -@item I -Display information in the minibuffer about this line. This is the same -information shown when navigating with @kbd{n} and @kbd{p}, or moving -the mouse over an item. -@item B -Byte compile the Emacs Lisp file on this line. -@item L -Load the Emacs Lisp file on this line. If a @file{.elc} file exists, -optionally load that. -@item C -Copy the current file to some other location. -@item R -Rename the current file, possibly moving it to some other location. -@item D -Delete the current file. -@item O -Delete the current file's object file. Use the symbols @samp{#} and -@samp{!} to determine if there is an object file available. -@end table - -One menu item toggles the display of all available files. By default, -only files which Emacs understands, and knows how to convert into a tag -list, are shown. By showing all files, additional files such as text files are -also displayed, but they are prefixed with the @samp{[?]} symbol. This -means that it is a file, but Emacs doesn't know how to expand it. - -@node Buffer Mode -@chapter Buffer Mode -@cindex buffer mode - -Buffer mode is very similar to File mode, except that instead of -tracking the current directory and all files available there, the -current list of Emacs buffers is shown. - -These buffers can have their tags expanded in the same way as files, -and uses the same unknown file indicator (@pxref{File Mode}). - -Buffer mode does not have file operation bindings, but the following -buffer specific key bindings are available: - -@table @kbd -@item k -Kill this buffer. Do not touch its file. -@item r -Revert this buffer, reloading from disk. -@end table - -In addition to Buffer mode, there is also Quick Buffer mode. In fact, -Quick Buffers is bound to the @kbd{b} key. The only difference between -Buffers and Quick Buffers is that after one operation is performed -which affects the attached frame, the display is immediately reverted to -the last displayed mode. - -Thus, if you are in File mode, and you need quick access to a buffer, -press @kbd{b}, click on the buffer you want, and speedbar will revert -back to File mode. - -@node Minor Modes -@chapter Minor Display Modes -@cindex minor display modes - -For some buffers, a list of files and tags makes no sense. This could -be because files are not currently in reference (such as web pages), or -that the files you might be interested have special properties (such as -email folders.) - -In these cases, a minor display mode is needed. A minor display mode -will override any major display mode currently being displayed for the -duration of the specialized buffer's use. Minor display modes -will follow the general rules of their major counterparts in terms of -key bindings and visuals, but will have specialized behaviors. - -@menu -* RMAIL:: Managing folders. -* Info:: Browsing topics. -* GDB:: Watching expressions or managing the current - stack trace. -@end menu - -@node RMAIL -@section RMAIL -@cindex RMAIL - -When using RMAIL, speedbar will display two sections. The first is a -layer one reply button. Clicking here will initialize a reply buffer -showing only this email address in the @samp{To:} field. - -The second section lists all RMAIL folders in the same directory as your -main RMAIL folder. The general rule is that RMAIL folders always appear -in all caps, or numbers. It is possible to save mail in folders with -lower case letters, but there is no clean way of detecting such RMAIL folders -without opening them all. - -Each folder can be visited by clicking the name. You can move mail from -the current RMAIL folder into a different folder by clicking the -@samp{} button. The @samp{M} stands for Move. - -In this way you can manage your existing RMAIL folders fairly easily -using the mouse. - -@node Info -@section Info -@cindex Info - -When browsing Info files, all local relevant information is displayed in -the info buffer and a topical high-level view is provided in speedbar. -All top-level info nodes are shown in the speedbar frame, and can be -jumped to by clicking the name. - -You can open these nodes with the @samp{[+]} button to see what sub-topics -are available. Since these sub-topics are not examined until you click -the @samp{[+]} button, sometimes a @samp{[?]} will appear when you click on -a @samp{[+]}, indicating that there are no sub-topics. - -@node GDB -@section GDB -@cindex gdb -@cindex gud - -You can debug an application with GDB in Emacs using graphical mode or -text command mode (@pxref{GDB Graphical Interface,,, emacs, The -extensible self-documenting text editor}). - -If you are using graphical mode you can see how selected variables -change each time your program stops (@pxref{Watch Expressions,,, -emacs, The extensible self-documenting text editor}). - -If you are using text command mode, speedbar can show -you the current stack when the current buffer is the @file{*gdb*} -buffer. Usually, it will just report that there is no stack, but when -the application is stopped, the current stack will be shown. - -You can click on any stack element and gdb will move to that stack -level. You can then check variables local to that level at the GDB -prompt. - -@node Customizing -@chapter Customizing -@cindex customizing - -Speedbar is highly customizable, with a plethora of control elements. -Since speedbar is so visual and reduces so much information, this is an -important aspect of its behavior. - -In general, there are three custom groups you can use to quickly modify -speedbar's behavior. - -@table @code -@item speedbar -Basic speedbar behaviors. -@item speedbar-vc -Customizations regarding version control handling. -@item speedbar-faces -Customize speedbar's many colors and fonts. -@end table - -@menu -* Frames and Faces:: Visible behaviors. -* Tag Hierarchy Methods:: Customizing how tags are displayed. -* Version Control:: Adding new VC detection modes. -* Hooks:: The many hooks you can use. -@end menu - -@node Frames and Faces -@section Frames and Faces -@cindex faces -@cindex frame parameters - -There are several faces speedbar generates to provide a consistent -color scheme across display types. You can customize these faces using -your favorite method. They are: - -@table @asis -@cindex @code{speedbar-button-face} -@item speedbar-button-face -Face used on expand/contract buttons. -@cindex @code{speedbar-file-face} -@item speedbar-file-face -Face used on Files. Should also be used on non-directory like nodes. -@cindex @code{speedbar-directory-face} -@item speedbar-directory-face -Face used for directories, or nodes which consist of groups of other nodes. -@cindex @code{speedbar-tag-face} -@item speedbar-tag-face -Face used for tags in a file, or for leaf items. -@cindex @code{speedbar-selected-face} -@item speedbar-selected-face -Face used to highlight the selected item. This would be the current -file being edited. -@cindex @code{speedbar-highlight-face} -@item speedbar-highlight-face -Face used when the mouse passes over a button. -@end table - -You can also customize speedbar's initial frame parameters. How this is -accomplished is dependent on your platform being Emacs or XEmacs. - -@cindex @code{speedbar-frame-parameters}, Emacs -In Emacs, change the alist @code{speedbar-frame-parameters}. This -variable is used to set up initial details. Height is also -automatically added when speedbar is created, though you can override -it. - -@cindex @code{speedbar-frame-plist}, XEmacs -In XEmacs, change the plist @code{speedbar-frame-plist}. This is the -XEmacs way of doing the same thing. - -@node Tag Hierarchy Methods -@section Tag Hierarchy Methods -@cindex tag hierarchy -@cindex tag groups -@cindex tag sorting - -When listing tags within a file, it is possible to get an annoyingly -long list of entries. Imenu (which generates the tag list in Emacs) -will group some classes of items automatically. Even here, however, -some tag groups can be quite large. - -@cindex @code{speedbar-tag-hierarchy-method} -To solve this problem, tags can be grouped into logical units through a -hierarchy processor. The specific variable to use is -@code{speedbar-tag-hierarchy-method}. There are several methods that -can be applied in any order. They are: - -@table @code -@cindex @code{speedbar-trim-words-tag-hierarchy} -@item speedbar-trim-words-tag-hierarchy -Find a common prefix for all elements of a group, and trim it off. -@cindex @code{speedbar-prefix-group-tag-hierarchy} -@item speedbar-prefix-group-tag-hierarchy -If a group is too large, place sets of tags into bins based on common -prefixes. -@cindex @code{speedbar-simple-group-tag-hierarchy} -@item speedbar-simple-group-tag-hierarchy -Take all items in the top level list not in a group, and stick them into -a @samp{Tags} group. -@cindex @code{speedbar-sort-tag-hierarchy} -@item speedbar-sort-tag-hierarchy -Sort all items, leaving groups on top. -@end table - -You can also add your own functions to reorganize tags as you see fit. - -Some other control variables are: - -@table @code -@cindex @code{speedbar-tag-group-name-minimum-length} -@item speedbar-tag-group-name-minimum-length -Default value: 4. - -The minimum length of a prefix group name before expanding. Thus, if -the @code{speedbar-tag-hierarchy-method} includes -@code{speedbar-prefix-group-tag-hierarchy} and one such group's common -characters is less than this number of characters, then the group name -will be changed to the form of: - -@example -worda to wordb -@end example - -instead of just - -@example -word -@end example - -This way we won't get silly looking listings. - -@cindex @code{speedbar-tag-split-minimum-length} -@item speedbar-tag-split-minimum-length -Default value: 20. - -Minimum length before we stop trying to create sub-lists in tags. -This is used by all tag-hierarchy methods that break large lists into -sub-lists. - -@cindex @code{speedbar-tag-regroup-maximum-length} -@item speedbar-tag-regroup-maximum-length -Default value: 10. - -Maximum length of submenus that are regrouped. -If the regrouping option is used, then if two or more short subgroups -are next to each other, then they are combined until this number of -items is reached. -@end table - -@node Version Control -@section Version Control -@cindex version control -@cindex vc extensions - -When using the file mode in speedbar, information regarding a version -control system adds small details to the display. If a file is in a -version control system, and is ``checked out'' or ``locked'' locally, an -asterisk @samp{*} appears at the end of the file name. In addition, -the directory name for Version Control systems are left out of the -speedbar display. - -@cindex @code{speedbar-directory-unshown-regexp} -You can easily add new version control systems into speedbar's detection -scheme. To make a directory ``disappear'' from the list, use the variable -@code{speedbar-directory-unshown-regexp}. - -@cindex @code{speedbar-vc-path-enable-hook} -Next, you need to write entries for two hooks. The first is -@code{speedbar-vc-path-enable-hook} which will enable a VC check in the -current directory for the group of files being checked. Your hook -function should take one parameter (the directory to check) and return -@code{t} if your VC method is in control here. - -@cindex @code{speedbar-vc-in-control-hook} -The second function is @code{speedbar-vc-in-control-hook}. This hook -takes two parameters, the @var{path} of the file to check, and the -@var{file} name. Return @code{t} if you want to have the asterisk -placed near this file. - -@cindex @code{speedbar-vc-indicator} -Lastly, you can change the VC indicator using the variable -@code{speedbar-vc-indicator}, and specify a single character string. - -@node Hooks -@section Hooks -@cindex hooks - -There are several hooks in speedbar allowing custom behaviors to be -added. Available hooks are: - -@table @code -@cindex @code{speedbar-visiting-file-hook} -@item speedbar-visiting-file-hook -Hooks run when speedbar visits a file in the selected frame. -@cindex @code{speedbar-visiting-tag-hook} -@item speedbar-visiting-tag-hook -Hooks run when speedbar visits a tag in the selected frame. -@cindex @code{speedbar-load-hook} -@item speedbar-load-hook -Hooks run when speedbar is loaded. -@cindex @code{speedbar-reconfigure-keymaps-hook} -@item speedbar-reconfigure-keymaps-hook -Hooks run when the keymaps are regenerated. Keymaps are reconfigured -whenever modes change. This will let you add custom key bindings. -@cindex @code{speedbar-before-popup-hook} -@item speedbar-before-popup-hook -Hooks called before popping up the speedbar frame. -New frames are often popped up when ``power clicking'' on an item to view -it. -@cindex @code{speedbar-before-delete-hook} -@item speedbar-before-delete-hook -Hooks called before deleting or hiding the speedbar frame. -@cindex @code{speedbar-mode-hook} -@item speedbar-mode-hook -Hooks called after creating a speedbar buffer. -@cindex @code{speedbar-timer-hook} -@item speedbar-timer-hook -Hooks called after running the speedbar timer function. -@cindex @code{speedbar-scanner-reset-hook} -@item speedbar-scanner-reset-hook -Hook called whenever generic scanners are reset. -Set this to implement your own scanning or rescan safe functions with -state data. -@end table - -@node Extending -@chapter Extending -@cindex extending - -Speedbar can run different types of Major display modes such as Files -(@pxref{File Mode}), and Buffers (@pxref{Buffer Mode}). It can also manage -different minor display modes for use with buffers handling specialized -data. - -These major and minor display modes are handled through an extension -system which permits specialized keymaps and menu extensions, in -addition to a unique rendering function. You can also specify a wide -range of tagging functions. The default uses @code{imenu}, but new -tagging methods can be easily added. In this chapter, you will -learn how to write your own major or minor display modes, and how to -create specialized tagging functions. - -@menu -* Minor Display Modes:: How to create a minor display mode. -* Major Display Modes:: How to create a major display mode. -* Tagging Extensions:: How to create your own tagging methods. -* Creating a display:: How to insert buttons and hierarchies. -@end menu - -@node Minor Display Modes -@section Minor Display Modes -@cindex create minor display mode - -A @dfn{minor display mode} is a mode useful when using a specific type of -buffer. This mode might not be useful for any other kind of data or -mode, or may just be more useful that a files or buffers based mode when -working with a specialized mode. - -Examples that already exist for speedbar include RMAIL, Info, and gdb. -These modes display information specific to the major mode shown in the -attached frame. - -To enable a minor display mode in your favorite Major mode, follow these -steps. The string @samp{@var{name}} is the name of the major mode being -augmented with speedbar. - -@enumerate -@item -Create the keymap variable @code{@var{name}-speedbar-key-map}. - -@item -Create a function, named whatever you like, which assigns values into your -keymap. Use this command to create the keymap before assigning -bindings: - -@smallexample - (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap)) -@end smallexample - -This function creates a special keymap for use in speedbar. - -@item -Call your install function, or assign it to a hook like this: - -@smallexample -(if (featurep 'speedbar) - (@var{name}-install-speedbar-variables) - (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables)) -@end smallexample - -@item -Create an easymenu compatible vector named -@code{@var{name}-speedbar-menu-items}. This will be spliced into -speedbar's control menu. - -@item -Create a function called @code{@var{name}-speedbar-buttons}. This function -should take one variable, which is the buffer for which it will create -buttons. At this time @code{(current-buffer)} will point to the -uncleared speedbar buffer. -@end enumerate - -When writing @code{@var{name}-speedbar-buttons}, the first thing you will -want to do is execute a check to see if you need to re-create your -display. If it needs to be cleared, you need to erase the speedbar -buffer yourself, and start drawing buttons. @xref{Creating a display}. - -@node Major Display Modes -@section Major Display Modes -@cindex create major display mode - -Creating a @dfn{Major Display Mode} for speedbar requires authoring a keymap, -an easy-menu segment, and writing several functions. These items can be -given any name, and are made the same way as in a minor display mode -(@pxref{Minor Display Modes}). Once this is done, these items need to be -registered. - -Because this setup activity may or may not have speedbar available when -it is being loaded, it is necessary to create an install function. This -function should create and initialize the keymap, and add your -expansions into the customization tables. - -@cindex @code{speedbar-make-specialized-keymap} -When creating the keymap, use the function -@code{speedbar-make-specialized-keymap} instead of other keymap making -functions. This will provide you with the initial bindings needed. -Some common speedbar functions you might want to bind are: - -@table @code -@cindex @code{speedbar-edit-line} -@item speedbar-edit-line -Edit the item on the current line. -@cindex @code{speedbar-expand-line} -@item speedbar-expand-line -Expand the item under the cursor. -With a numeric argument (@kbd{C-u}), flush cached data before expanding. -@cindex @code{speedbar-contract-line} -@item speedbar-contract-line -Contract the item under the cursor. -@end table - -@cindex @code{speedbar-line-path} -These function require that function @code{speedbar-line-path} be -correctly overloaded to work. - -Next, register your extension like this; - -@example - (speedbar-add-expansion-list '("MyExtension" - MyExtension-speedbar-menu-items - MyExtension-speedbar-key-map - MyExtension-speedbar-buttons)) -@end example - -There are no limitations to the names you use. - -The first parameter is the string representing your display mode. -The second parameter is a variable name containing an easymenu compatible -menu definition. This will be stuck in the middle of speedbar's menu. -The third parameter is the variable name containing the keymap we -discussed earlier. -The last parameter is a function which draws buttons for your mode. -This function must take two parameters. The directory currently being -displayed, and the depth at which you should start rendering buttons. -The function will then draw (starting at the current cursor position) -any buttons deemed necessary based on the input parameters. -@xref{Creating a display}. - -Next, you need to register function overrides. This may look something -like this: - -@example -(speedbar-add-mode-functions-list - '("MYEXTENSION" - (speedbar-item-info . MyExtension-speedbar-item-info) - (speedbar-line-path . MyExtension-speedbar-line-path))) -@end example - -The first element in the list is the name of you extension. The second -is an alist of functions to overload. The function to overload is -first, followed by what you want called instead. - -For @code{speedbar-line-path} your function should take an optional DEPTH -parameter. This is the starting depth for heavily indented lines. If -it is not provided, you can derive it like this: - -@example -(save-match-data - (if (not depth) - (progn - (beginning-of-line) - (looking-at "^\\([0-9]+\\):") - (setq depth (string-to-int (match-string 1))))) -@end example - -@noindent -where the depth is stored as invisible text at the beginning of each -line. - -The path returned should be the full path name of the file associated -with that line. If the cursor is on a tag, then the file containing -that tag should be returned. This is critical for built in file based -functions to work (meaning less code for you to write). If your display -does not deal in files, you do not need to overload this function. - -@cindex @code{speedbar-item-info} -The function @code{speedbar-item-info}, however, is very likely to need -overloading. This function takes no parameters and must derive a text -summary to display in the minibuffer. - -There are several helper functions you can use if you are going to use -built in tagging. These functions can be @code{or}ed since each one -returns non-@code{nil} if it displays a message. They are: - -@table @code -@cindex @code{speedbar-item-info-file-helper} -@item speedbar-item-info-file-helper -This takes an optional @var{filename} parameter. You can derive your own -filename, or it will derive it using a (possibly overloaded) function -@code{speedbar-line-file}. It shows details about a file. -@cindex @code{speedbar-item-info-tag-helper} -@item speedbar-item-info-tag-helper -If the current line is a tag, then display information about that tag, -such as its parent file, and location. -@end table - -Your custom function might look like this: - -@example -(defun MyExtension-item-info () - "Display information about the current line." - (or (speedbar-item-info-tag-helper) - (message "Interesting detail."))) -@end example - -Once you have done all this, speedbar will show an entry in the -@samp{Displays} menu declaring that your extension is available. - -@node Tagging Extensions -@section Tagging Extensions - -It is possible to create new methods for tagging files in speedbar. -To do this, you need two basic functions, one function to fetch the -tags from a buffer, the other to insert them below the filename. - -@defun my-fetch-dynamic-tags file -Parse @var{file} for a list of tags. Return the list, or @code{t} if there was -an error. -@end defun - -The non-error return value can be anything, as long as it can be -inserted by its paired function: - -@defun my-insert-tag-list level lst -Insert a list of tags @var{lst} started at indentation level -@var{level}. Creates buttons for each tag, and provides any other -display information required. -@end defun - -@cindex @code{speedbar-create-tag-hierarchy} -It is often useful to use @code{speedbar-create-tag-hierarchy} on your -token list. See that function's documentation for details on what it -requires. - -@cindex @code{speedbar-dynamic-tags-function-list} -Once these two functions are written, modify the variable -@code{speedbar-dynamic-tags-function-list} to include your parser at the -beginning, like this: - -@example -(add-to-list 'speedbar-dynamic-tags-function-list - '(my-fetch-dynamic-tags . my-insert-tag-list)) -@end example - -If your parser is only good for a few types of files, make sure that it -is either a buffer local modification, or that the tag generator returns -@code{t} for non valid buffers. - -@node Creating a display -@section Creating a display -@cindex creating a display - -Rendering a display in speedbar is completely flexible. When your -button function is called, see @ref{Minor Display Modes}, and @ref{Major -Display Modes}, you have control to @code{insert} anything you want. - -The conventions allow almost anything to be inserted, but several helper -functions are provided to make it easy to create the standardized -buttons. - -To understand the built in functions, each `button' in speedbar consists -of four important pieces of data. The text to be displayed, token -data to be associated with the text, a function to call, and some face to -display it in. - -When a function is provided, then that text becomes mouse activated, -meaning the mouse will highlight the text. - -Additionally, for data which can form deep trees, each line is given a -depth which indicates how far down the tree it is. This information is -stored in invisible text at the beginning of each line, and is used by -the navigation commands. - -@defun speedbar-insert-button text face mouse function &optional token prevline -This function inserts one button into the current location. -@var{text} is the text to insert. @var{face} is the face in which it -will be displayed. @var{mouse} is the face to display over the text -when the mouse passes over it. @var{function} is called whenever the -user clicks on the text. - -The optional argument @var{token} is extra data to associated with the -text. Lastly @var{prevline} should be non-@code{nil} if you want this line to -appear directly after the last button which was created instead of on -the next line. -@end defun - -@defun speedbar-make-tag-line exp-button-type exp-button-char exp-button-function exp-button-data tag-button tag-button-function tag-button-data tag-button-face depth - -Create a tag line with @var{exp-button-type} for the small expansion -button. This is the button that expands or contracts a node (if -applicable), and @var{exp-button-char} the character in it (@samp{+}, -@samp{-}, @samp{?}, etc.). @var{exp-button-function} is the function -to call if it's clicked on. Button types are @code{bracket}, -@code{angle}, @code{curly}, @code{expandtag}, @code{statictag}, and -@code{nil}. @var{exp-button-data} is extra data attached to the text -forming the expansion button. - -Next, @var{tag-button} is the text of the tag. -@var{tag-button-function} is the function to call if clicked on, and -@var{tag-button-data} is the data to attach to the text field (such a -tag positioning, etc.). @var{tag-button-face} is a face used for this -type of tag. - -Lastly, @var{depth} shows the depth of expansion. - -This function assumes that the cursor is in the speedbar window at the -position to insert a new item, and that the new item will end with a CR. -@end defun - -@defun speedbar-insert-generic-list level list expand-fun find-fun - -At @var{level}, (the current indentation level desired) insert a generic -multi-level alist @var{list}. Associations with lists get @samp{@{+@}} -tags (to expand into more nodes) and those with positions or other data -just get a @samp{>} as the indicator. @samp{@{+@}} buttons will have the -function @var{expand-fun} and the token is the @code{cdr} list. The -token name will have the function @var{find-fun} and not token. - -Each element of the list can have one of these forms: - -@table @code -@item (@var{name} . marker-or-number) -One tag at this level. -@item (@var{name} (@var{name} . marker-or-number) (@var{name} . marker-or-number) ... ) -One group of tags. -@item (@var{name} marker-or-number (@var{name} . marker-or-number) ... ) -One Group of tags where the group has a starting position. -@end table - -When you use @code{speedbar-insert-generic-list}, there are some -variables you can set buffer-locally to change the behavior. The most -obvious is @code{speedbar-tag-hierarchy-method}. -@xref{Tag Hierarchy Methods}. - -@defvar speedbar-generic-list-group-expand-button-type -This is the button type used for groups of tags, whether expanded -or added in via a hierarchy method. Two good values are -@code{curly} and @code{expandtag}. Curly is the default button, and -@code{expandtag} is useful if the groups also has a position. -@end defvar - -@defvar speedbar-generic-list-tag-button-type -This is the button type used for a single tag. -Two good values are @code{nil} and @code{statictag}. -@code{nil} is the default, and @code{statictag} has the same width as -@code{expandtag}. -@end defvar - -@end defun - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Index -@unnumbered Concept Index -@printindex cp - -@bye -@c LocalWords: speedbar's xref slowbar kbd subsubsection -@c LocalWords: keybindings diff --git a/doc/misc/srecode.texi b/doc/misc/srecode.texi deleted file mode 100644 index cd72656c91b..00000000000 --- a/doc/misc/srecode.texi +++ /dev/null @@ -1,1800 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/srecode -@set TITLE SRecoder Manual -@set AUTHOR Eric M. Ludlam -@settitle @value{TITLE} -@documentencoding UTF-8 - -@c Merge all indexes into a single index for now. -@c We can always separate them later into two or more as needed. -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex ky cp -@syncodeindex pg cp -@syncodeindex tp cp -@c %**end of header - -@copying -Copyright @copyright{} 2007--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* SRecode: (srecode). Semantic template code generator. -@end direntry - -@titlepage -@sp 10 -@center @titlefont{SRecode} -@vskip 0pt plus 1 fill -@center by @value{AUTHOR} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@macro semantic{} -@i{Semantic} -@end macro - -@macro EIEIO{} -@i{EIEIO} -@end macro - -@macro srecode{} -@i{SRecode} -@end macro - -@node Top -@top @value{TITLE} - -@srecode{} is the @i{Semantic Recoder}. Where @semantic{} will parse -source files into lists of tags, the @i{Semantic Recoder} will aid in -converting @semantic{} tags and various other information back into -various types of code. - -While the @srecode{} tool provides a template language, templates for -several languages, and even a sequence of heuristics that aid the user -in choosing a template to insert, this is not the main goal of -@srecode{}. - -The goal of @srecode{} is to provide an application framework where -someone can write a complex code generator, and the underlying -template commonality allows it to work in multiple languages with -ease. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Quick Start:: Basic Setup for template insertion. -* User Templates:: Custom User Templates -* Parts of SRecode:: Parts of the system -* SRecode Minor Mode:: A minor mode for using templates -* Template Writing:: How to write a template -* Dictionaries:: How dictionaries work -* Developing Template Functions:: How to write your own template insert functions. -* Template Naming Conventions:: Creating a set of core templates -* Inserting Tag Lists:: Inserting Semantic tags via templates -* Application Writing:: Writing an @srecode{}r application -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - - -@node Quick Start -@chapter Quick Start - -When you install CEDET and enable @srecode{}, an @code{SRecoder} menu -item should appear. - -To toggle @srecode{} minor mode on and off use: - -@example -M-x srecode-minor-mode RET -@end example -or -@example -M-x global-srecode-minor-mode RET -@end example - -or add - -@example -(srecode-minor-mode 1) -@end example - -into a language hook function to force it on (which is the default) or -pass in @code{-1} to force it off. - -See @ref{SRecode Minor Mode} for more on using the minor mode. - -Use the menu to insert templates into the current file. - -You can add your own templates in @file{~/.srecode}, or update the -template map path: - -@deffn Option srecode-map-load-path -@anchor{srecode-map-load-path} -Global load path for SRecode template files. -@end deffn - - -Once installed, you can start inserting templates using the menu, or -the command: - -@deffn Command srecode-insert template-name &rest dict-entries -@anchor{srecode-insert} -Insert the template @var{template-name} into the current buffer at point. -@var{dict-entries} are additional dictionary values to add. -@end deffn - -SRecode Insert will prompt for a template name. Template names are -specific to each major mode. A typical name is of the form: -@code{CONTEXT:NAME} where a @var{CONTEXT} might be something like -@code{file} or @code{declaration}. The same @var{NAME} can occur in -multiple contexts. - -@node User Templates -@chapter User Templates - -@srecode{} builds and maintains a map of all template files. The root -template files resides in the @srecode{} distribution. User written -templates files are saved in @file{~/.srecode}, along with the -@srecode{} map file. - -@defvar srecode-map-save-file -@anchor{srecode-map-save-file} -The save location for SRecode's map file. -@end defvar - -Template files end with a @file{.srt} extension. Details on how to -write templates are in @ref{Template Writing}. - -Each template file you write is dedicated to a single major mode. In -it, you can write templates within the same context and with the same -name as core templates. You can force your templates to override the -core templates for a particular major mode by setting the -priority. See @ref{Special Variables}. - -To get going quickly, open a new @file{.srt} file. It will start in -the @srecode{} template writing mode. Use the @srecode{} minor mode -menu to insert the @code{empty} file template. - -When using templates in other modes (such as C++ or Emacs Lisp -templates), use the ``Edit Template'' menu to find a template you -would like to update. Copy it into your user template file, and -change it. - -If you were to update @code{declaration:function} in your user -template file, then you would get this new template instead of the one -that comes with @srecode{}. Higher level applications should always -use @code{declaration:function} when generating their own code, so -higher level templates will then adopt your changes to -@code{declaration:function} into themselves. - -You can also override variables. Core variables are stored in the -@srecode{} root template file @file{default.srt}, and that contains -the copyright usually used, and some basic file setup formats. -Override variables like this by specifying a @code{mode} of -@code{default} like this: - -@example -set mode "default" -@end example - -@node Parts of SRecode -@chapter Parts of SRecode - -The @srecode{} system is made up of several layers which work together -to generate code. - -@section Template Layer -The template layer provides a way to write, and compile templates. The -template layer is the scheme used to insert text into an Emacs buffer. - -The @srecode{} template layer is more advanced than other modes like the -Emacs packages @code{skeleton} or @code{tempo} in that it allows -multiple layers of templates to be created with the same names. This -means that @srecode{} can provide a wide range of templates, and users -can override only the small sections they want, instead of either -accepting someone else's template, or writing large new templates of -their own. - -Templates are written in @file{.srt} files. You can learn how to -author new @file{.srt} files @ref{Template Writing}. - -While the template system was designed for @srecode{} based -applications it can also be used independently for simple template -insertion during typical coding. - -@section Template Manager -Once templates have been written, a scheme for loading and selecting -templates is needed. The template manager has a loader for finding -template files, and determining which templates are relevant to the -current buffer. Template files are sorted by priority, with user -templates being found first, and system level default templates last. -Templates are also sorted by application. Each application has its -own templates, and are kept separate from the generic templates. - -@section Dictionary -Dictionaries contain values associated with variable. Variables are -used in macros in a template. Variables are what allows a generic -template such as a function to be made specific, such as a function -named foo. The value of a variable can be one of three things; a -string, a list of more dictionaries, or a special -@code{srecode-dictionary-compound-value} object subclass. See -@ref{Variables} for more. - -@section Template Insertion -The template insertion layer involves extensions to the basic template -layer. A wide range of custom variables are available for mixing derived -data as macros into the plain text of a template. - -In addition, templates can be declared with arguments. These -arguments represent predetermined sets of dictionary values, such as -features of the current file name, user name, time, etc. - -Some arguments are major-mode specific, such as the @code{:el} or -@code{:cpp} arguments. - -@section Template Insertion Context -A context can be provided for templates in a file. This helps -auto-selection of templates by name, or allows templates in different -contexts to have the same name. Some standard contexts are -@code{file}, @code{declaration}, and @code{classdecl}. - -A context can be automatically derived as well based on the parsing -state from @i{Semantic}. @inforef{Top, Semantic Manual, semantic}. - -@section Applications -Commands that do a particular user task which involves also writing -Emacs Lisp code. Applications are at the top layer. These -applications have their own template files and logic needed to fill in -dictionaries or position a cursor. SRecode comes with an example -@code{srecode-document} application for creating comments for Semantic -tags. The CEDET application @i{EDE} has a project type that is an -@srecode{} application. - -@section Field Editing -If the variable @code{srecode-insert-ask-variable-method} is set to -'field, then variables that would normally ask a question, will -instead create ``fields'' in the buffer. A field-editing layer -provides simple interaction through the fields. Typing in a field -will cause all variable locations that are the same to edit at the -same time. Pressing TAB on a field will move you to the next field. - -@node SRecode Minor Mode -@chapter SRecode Minor Mode - -The Semantic Recode minor mode enables a keymap and menu that provides -simple access to different templates or template applications. - -The key prefix is @key{C-c /}. - -If the variable @code{srecode-takeover-INS-key} is set, then the key -@key{} can also be used. - -The most important key is bound to @code{srecode-insert} which is -@key{C-c / /}, or @key{insert insert}. @ref{Quick Start}. - -Major keybindings are: - -@table @key -@item C-c / / -Insert a template whose name is typed into the minibuffer. -@item C-c / -Reserved for direct binding of simple templates to keys using a -keybinding command in the template file. -@item C-c / -Reserved for template applications (Such as comment or get/set inserter.) -@item C-c / E -Edit the code of a template. -@item C-c / . -Insert template again. This will cause the previously inserted -template to be inserted again. -@end table - -@section Field Editing - -By default, when inserting a template, if the user needs to enter text -to fill in a part of the template, then the minibuffer is used to -query for that information. SRecode also supports a field-editing mode -that can be used instead. To enable it set: - -@defun srecode-insert-ask-variable-method -@anchor{srecode-insert-ask-variable-method} -Determine how to ask for a dictionary value when inserting a template. -Only the @var{ASK} style inserter will query the user for a value. -Dictionary value references that ask begin with the ? character. -Possible values are: -@table @code -@item ask -Prompt in the minibuffer as the value is inserted. -@item field -Use the dictionary macro name as the inserted value, -and place a field there. Matched fields change together. -@end table - -@b{NOTE}: The field feature does not yet work with XEmacs. -@end defun - -Field editing mode is supported in newer versions of Emacs. You -will not be prompted to fill in values while the template is -inserted. Instead, short regions will be highlighted, and the cursor -placed in a field. Typing in the field will then fill in the value. -Several fields might be linked together. In that case, typing in one -area will modify the other linked areas. Pressing TAB will move -between editable fields in the template. - -Once the cursor moves out of the are inserted by the template, all the -fields are canceled. - -@b{NOTE}: Some conveniences in templates, such as completion, or -character restrictions are lost when using field editing mode. - -@node Template Writing -@chapter Template Writing -@anchor{@code{SRecode-template-mode}} - -@code{srecode-template-mode} is the major mode used for designing new -templates. @srecode{} files (Extension @file{.srt}) are made up of -variable settings and template declarations. - -Here is an overview of the terminology you will need for the next few -sections: - -@table @asis -@item template file -A file with a @file{.srt} extension which contains settings, -variables, and templates. -@item template -One named entity which represents a block of text that will be -inserted. The text is compiled into a sequence of insertable -entities. The entities are string constants, and macros. -@item macro -A macro is a text sequence within template text that is replaced with -some other value. -@item dictionary -A table of variable names and values. -@item subdictionary -A dictionary that is subordinate under another dictionary as a value -to some variable. -@item variable -A variable is an entry in a dictionary which has a value. -@end table - -@menu -* Variables:: Creating special and regular variables. -* Templates:: Creating templates -* Contexts:: Templates are grouped by context -* Prompts:: Setting prompts for interactive insert macros -@end menu - -@node Variables -@section Variables - -Variables can be set up and used in templates. Many variables you may -use are set up via template arguments, but some may be preferences a -user can set up that are used in system templates. - -When expanding a template, variables are stored in a @dfn{dictionary}. -Dictionary entries are variables. Variables defined in templates can -have string like values. - -A variable can be set like this: -@example -set VARNAME "some value" -@end example - -Note that a VARIABLE is a name in a dictionary that can be used in a -MACRO in a template. The macro references some variable by name. - -@menu -* String Values:: Basic Variable values -* Multi-string Values:: Complex variable values -* Section Show:: Enabling the display of a named section. -* Special Variables:: Variables with special names -* Automatic Loop Variables:: Variables automatically set in section loops. -* Compound Variable Values:: Compound Variable Values -@end menu - -@node String Values -@subsection String Values - -Variables can be set to strings. Strings may contain newlines or any -other characters. Strings are interpreted by the Emacs Lisp reader so -@code{\n}, @code{\t}, and @code{\"} work. - -When a string is inserted as part of a template, nothing within the -string is interpreted, such as template escape characters. - -@node Multi-string Values -@subsection Multi-string Values - -A variable can be set to multiple strings. A compound value is -usually used when you want to use dictionary entries as part of a -variable later on. - -Multi-string variable values are set like string values except there -are more than one. For example - -@example -set NAME "this" "-mode" -@end example - -These two strings will be concatenated together. - -A more useful thing is to include dictionary variables and concatenate -those into the string. Use the ``macro'' keyword to include the name -of a variable. This is like macros in a template. For example: - -@example -set NAME macro "MODE" "-mode" -@end example - -will extract the value of the dictionary variable MODE and append -``-mode'' to the end. - -@node Section Show -@subsection Section Show - -To set a variable to show a template section, use the @code{show} -command. Sections are blocks of a template wrapped in section macros. -If there is a section macro using @var{NAME} it will be shown for each -dictionary associated with the @var{NAME} macro. - -@example -show NAME -@end example - -This will enable that section. - - -NOTE: May 11, 2008: I haven't used this yet, so I don't know if it works. - - -@node Special Variables -@subsection Special Variables - -Some variables have special meaning that changes attributes when -templates are compiled, including: - -@table @code -@item escape-start -This is the character sequence that escapes from raw text to template -macro names. The ability to change the escape characters are key for -enabling @srecode{} templates to work across many kinds of languages. -@item escape-end -This is the character sequence that escapes the end of a template -macro name. - -Example: -@example -set escape_start "$" -set escape_end "$" -@end example -@item mode -This is the major mode, as a string with the full Emacs Lisp symbol in -it. All templates in this file will be installed into the template -table for this major mode. - -Multiple template files can use the same mode, and all those templates -will be available in buffers of that mode. - -Example: -@example -set mode "emacs-lisp-mode" -@end example - -@item priority -The priority of a file is a number in a string constant that -indicates where it lies in the template search order. System -templates default to low priority numbers. User templates default to -high priority numbers. You can specify the priority of your template -to insert it anywhere in the template search list. - -If there are multiple templates with the same context and name, the -template with the highest priority number will be used. - -If multiple files have the same priority, then then sort order is -unpredictable. If no template names match, then it doesn't matter. - -Example: -@example -set priority "35" -@end example - -@item application -If a template file contains templates only needed for a particular -application, then specify an application. Template files for an -application are stored in the template repository, but are not used in -the generic template insertion case. - -The application with a particular name will access these templates -from Lisp code. - -Example: -@example -set application "document" -@end example - -@item project -If a template file contains templates, or template overrides specific -to a set of files under a particular directory, then that template -file can specify a ``project'' that it belongs to. - -Set the ``project'' special variable to a directory name. Only files -under that directory will be able to access the templates in that -file. - -Any template file that has a project specified will get have a -priority that is set between SRecode base templates, and user defined -templates. - -Templates can be compiled via a project system, such as EDE@. EDE -loaded templates will get a @var{project} set automatically. - -Example: -@example -set project "/tmp/testproject" -@end example - -@end table - -If you need to insert the characters that belong to the variables -@code{escape_start} or @code{escape_end}, then place those into -a variable. For example - -@example -set escape_start "$" -set escape_end "$" -set DOLLAR "$" -@end example - -@node Automatic Loop Variables -@subsection Automatic Loop Variables - -When section macros are used, that section is repeated for each -subdictionary bound to the loop variable. - -Each dictionary added will automatically get values for positional -macros which will enable different @var{sections}. The automatic -section variables are. - -@itemize @bullet -@item @var{first}---The first entry in the table. -@item @var{notfirst}---Not the first entry in the table. -@item @var{last}---The last entry in the table -@item @var{notlast}---Not the last entry in the table. -@end itemize - -@node Compound Variable Values -@subsection Compound Variable Values - -A variable can also have a compound value. This means the value of -the variable is an @EIEIO{} object, which is a subclass of -@code{srecode-dictionary-compound-value}. - -New compound variables can only be setup from Lisp code. See -@ref{Compound Dictionary Values} for details on setting up compound -variables from Lisp. - -@node Templates -@section Templates - -A template represents a text pattern that can be inserted into -a buffer. - -A basic template is declared like this: - -@example -template TEMPLATENAME :arg1 :arg2 -"Optional documentation string" ----- -The text to your template goes here. ----- -bind "a" -@end example - -Templates are stored in a template table by name, and are inserted by -the @var{templatename} provided. - -The documentation string is optional. This documentation string will -be used to aid users in selecting which template they want to use. - -The code that makes up the raw template occurs between the lines that -contain the text "-----". - -@menu -* Template Section Dictionaries:: Template Scoped Macro values -* Template Macros:: Macros occurring in template patterns -@end menu - -@node Template Section Dictionaries -@subsection Template Section Dictionaries - -To add variable values to section dictionaries used within a specific -template, you can add them to the beginning of the template -declaration like this: - -@example -template TEMPLATENAME :arg1 :arg2 -"Optional documentation string" -sectiondictionary "A" -set NAME "foo" ----- -A beginning line @{@{NAME@}@} -@{@{#A@}@}Optional string @{@{NAME@}@} here@{@{/A@}@} -An end line ----- -@end example - -In this example, the @var{NAME} variable gets the value ``foo'', but -only while it is inside section macro A@. The outer scoped NAME will -be empty. - -This is particularly useful while using an include macro to pull in a -second template. In this way, you can pass values known from one -template to a subordinate template where some value is not known. - -From the Emacs Lisp default template file, a syntax table is just a -variable with a specialized value. - -If a variable is declared like this (where $ is the escape character): - -@example -template variable :el -"Insert a variable. -DOC is optional." ----- -(defvar $?NAME$ $^$ - "$DOC$") ----- -@end example - -then you can see that there is a NAME and DOC that is needed. -The @code{^} point inserter is also a handy key here. - -The syntax table wants a variable, but knows the values of some of -these variables, and can recast the problem like this by using -template specific @code{sectiondictionary} macro declarations. - -@example -template syntax-table -"Create a syntax table." -sectiondictionary "A" -set NAME macro "?MODESYM" "-mode-syntax-table" -set DOC "Syntax table used in " macro "?MODESYM" " buffers." ----- -$'' will include another template. Include -macros would look like this: - -@example -@{@{>FOO:defun@}@} -@end example - -where @code{FOO} is the dictionary variable for the sub-dictionary used for -expanding the template @code{defun}. The @code{defun} template will -be looked up in the template repository for the current mode, or in -any inherited modes. - -Another way to include another template is with an include macro that -will also wrap section text. The includewrap insertion method looks -like this: - -@example -@{@{FOO:declaration:function@}@} -@end example - -@node Contexts -@section Context - -Each template belongs to a context. When prompting for a template by -name, such as with @kbd{C-c / /}, the name is prefixed by the current -context. If there is no context, it defaults to @code{declaration}. - -You can change context like this: - -@example -context NAME -@end example - -where @var{name} is some symbol that represents any context. - -A context resides over all templates that come after it until the next -context statement. Thus: - -@example -context C1 - -template foo -"Foo template in C1" ----- ----- - -context C2 - -template foo -"Foo template in C2" ----- ----- -@end example - -creates two @code{foo} templates. The first one is when in context -C1. The second is available in context C2. - -This is useful if there are multiple ways to declare something like a -function or variable that differ only by where it is in the syntax of -the language. The name @code{foo} is not ambiguous because each is in -a different context. - -@node Prompts -@section Prompt - -Some templates use prompting macro insertion. A macro that needs a -prompt looks like this: - -@example -@{@{?NAME@}@} -@end example - -where ? comes after the first escape character. - -by default, it will use a prompt like this when it is encountered: - -@example -Specify NAME: -@end example - -For such macros, you can pre-define prompts for any dictionary entry. -When that dictionary entry is first encountered, the user is prompted, -and subsequent occurrences of that dictionary entry use the same value. - -To get a different prompt, use a prompt command like this: - -@example -prompt VARNAME "Nice Way to ask for VARNAME: " -@end example - -Now, if you put this in a template: - -@example -template variable ----- -(defvar @{@{?VARNAME@}@} nil - "") ----- -@end example - -when VARNAME is encountered, it will use the nice prompt. - -Prompts can be extended as well. For example: - -@example -prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p -@end example - -In this case, the @code{default} keyword indicates that -@code{"srecode"} is the default string to use, and @code{y-or-n-p} is -the function to use to ask the question. - -For @code{y-or-n-p} if you type ``y'' it inserts the default string, -otherwise it inserts empty. - -For any other symbol that occurs after the @code{read} token, it is -expected to take the same argument list as @code{read-string}. As -such, you can create your own prompts that do completing reads on -deterministic values. - -To have the default be calculated later from a dictionary entry, you -need to use the @code{defaultmacro} keyword instead. - -@example -prompt VARNAME "Varname: " defaultmacro "PREFIX" -@end example - -now, when it attempts to read in VARNAME, it will pre-populate the text -editing section with whatever the value of PREFIX is. - -Some language arguments may supply possible prefixes for prompts. -Look for these when creating your prompts. - -@node Dictionaries -@chapter Dictionaries - -Dictionaries are a set of variables. The values associated with the -variable names could be anything, but how it is handled is dependent -on the type of macro being inserted. - -Most of this chapter is for writing Lisp programs that use @srecode{}. -If you only want to write template files, then you only need to read -the @ref{Template Argument Dictionary Entries} section. - -@menu -* Create a Dictionary:: -* Setting Dictionary Values:: Basic dictionary values -* Compound Dictionary Values:: Complex dictionary values -* Argument Resolution:: Automatic template argument resolution -* Creating new Arguments:: Create new arguments for use in templates -* Querying a Dictionary:: Querying a dictionary for values. -* Template Argument Dictionary Entries:: Catalog of arguments -@end menu - -@node Create a Dictionary -@section Create a Dictionary - -@defun srecode-create-dictionary &optional buffer -@anchor{srecode-create-dictionary} -Create a dictionary for @var{buffer}. -If @var{buffer} is not specified, use the current buffer. -The dictionary is initialized with no variables or enabled sections. -Any variables defined with @code{set} in the template, however, -becomes a name in the dictionary. -@end defun - -@node Setting Dictionary Values -@section Setting Dictionary Values - -When building an @srecode{} based application, you will need to setup -your dictionary values yourself. There are several utility functions -for this. - -In the simplest form, you can associate a string with a variable. - -@defun srecode-dictionary-set-value dict name value -@anchor{srecode-dictionary-set-value} -In dictionary @var{dict}, set @var{name} to have @var{value}. -@end defun - -For section macros, you can have alternate values. A section can -either be toggled as visible, or it can act as a loop. - -@defun srecode-dictionary-show-section dict name -@anchor{srecode-dictionary-show-section} -In dictionary @var{dict}, indicate that the section @var{name} should be exposed. -@end defun - - -@defun srecode-dictionary-add-section-dictionary dict name show-only -@anchor{srecode-dictionary-add-section-dictionary} -In dictionary @var{DICT}, add a section dictionary for section macro @var{NAME}. -Return the new dictionary. - -You can add several dictionaries to the same section entry. -For each dictionary added to a variable, the block of codes in -the template will be repeated. - -If optional argument @var{SHOW-ONLY} is non-@code{nil}, then don't add -a new dictionary if there is already one in place. Also, don't add -@var{FIRST}/@var{LAST} entries. -These entries are not needed when we are just showing a section. - -Each dictionary added will automatically get values for positional macros -which will enable @var{SECTIONS} to be enabled. - -@table @var -@item first -The first entry in the table. -@item notfirst -Not the first entry in the table. -@item last -The last entry in the table -@item notlast -Not the last entry in the table. -@end table - -Adding a new dictionary will alter these values in previously -inserted dictionaries. -@end defun - -@node Compound Dictionary Values -@section Compound Dictionary Values - -If you want to associate a non-string value with a dictionary -variable, then you will need to use a compound value. Compound -dictionary values are derived using @EIEIO{} from a base class for -handling arbitrary data in a macro. - -@deffn Type srecode-dictionary-compound-value -@anchor{srecode-dictionary-compound-value} -A compound dictionary value. -Values stored in a dictionary must be a @var{string}, -a dictionary for showing sections, or an instance of a subclass -of this class. - -Compound dictionary values derive from this class, and must -provide a sequence of method implementations to convert into -a string. -@end deffn - -Your new subclass of the compound value needs to implement these -methods: - -@defun srecode-compound-toString cp function dictionary -@anchor{srecode-compound-toString} -Convert the compound dictionary value @var{cp} to a string. -If @var{function} is non-@code{nil}, then @var{function} is somehow applied to an aspect -of the compound value. The @var{function} could be a fraction -of some function symbol with a logical prefix excluded. -@end defun - -The next method is for dumping out tables during debugging. - -@defun srecode-dump cp &optional indent -@anchor{srecode-dump} -Display information about this compound value. -@end defun - - -Here is an example of wrapping a semantic tag in a compound value: - -@example -(defclass srecode-semantic-tag (srecode-dictionary-compound-value) - ((prime :initarg :prime - :type semantic-tag - :documentation - "This is the primary insertion tag.") - ) - "Wrap up a collection of semantic tag information. -This class will be used to derive dictionary values.") - -(defmethod srecode-compound-toString((cp srecode-semantic-tag) - function - dictionary) - "Convert the compound dictionary value CP to a string. -If FUNCTION is non-nil, then FUNCTION is somehow applied to an -aspect of the compound value." - (if (not function) - ;; Just format it in some handy dandy way. - (semantic-format-tag-prototype (oref cp :prime)) - ;; Otherwise, apply the function to the tag itself. - (funcall function (oref cp :prime)) - )) -@end example - -@node Argument Resolution -@section Argument Resolution - -Some dictionary entries can be set via template arguments in the -template declaration. For examples of template arguments, see -@ref{Template Argument Dictionary Entries}. - - You can resolve an argument list into a dictionary with: - -@defun srecode-resolve-arguments temp dict -@anchor{srecode-resolve-arguments} -Resolve all the arguments needed by the template @var{temp}. -Apply anything learned to the dictionary @var{dict}. -@end defun - -@node Creating new Arguments -@section Creating new Arguments - -You can create new arguments for use in template files by writing new -Emacs Lisp functions. Doing so is easy. Here is an example for the -@code{:user} argument: - -@example -(defun srecode-semantic-handle-:user (dict) - "Add macros into the dictionary DICT based on the current :user." - (srecode-dictionary-set-value dict "AUTHOR" (user-full-name)) - (srecode-dictionary-set-value dict "LOGIN" (user-login-name)) - ;; ... - ) -@end example - -In this case, a function with the name prefix -@code{srecode-semantic-handle-} that ends in @code{:user} creates a -new argument @code{:user} that can be used in a template. - -Your argument handler must take one argument @var{dict}, which is the -dictionary to fill in. Inside your function, you can do whatever you -want, but adding dictionary values is the right thing. - -@node Querying a Dictionary -@section Querying a Dictionary - -When creating a new argument, it may be useful to ask the dictionary -what entries are already set there, and conditionally create new -entries based on those. - -In this way, a template author can get additional logic through more -advanced arguments. - -@defun srecode-dictionary-lookup-name dict name -@anchor{srecode-dictionary-lookup-name} -Return information about the current @var{DICT}'s value for @var{NAME}. -@var{DICT} is a dictionary, and @var{NAME} is a string that is the name of -a symbol in the dictionary. -This function derives values for some special NAMEs, such as @var{FIRST} -and '@var{LAST}'. -@end defun - - - -@node Template Argument Dictionary Entries -@section Template Argument Dictionary Entries - -When a dictionary is initialized for a template, then the dictionary -will be initialized with a predefined set of macro values. - -A template of the form: - -@example -template template-name :arg1 :arg2 ----- -Your template goes here ----- -@end example - -specifies two arguments :arg1, and :arg2. - -The following built-in simple arguments are available: - -@menu -* Base Arguments:: -* Semantic Arguments:: -* Language Arguments:: -@end menu - -@node Base Arguments -@subsection Base Arguments - -@subsubsection Argument :indent - -Supplies the @code{INDENT} macro. When @code{INDENT} is non-@code{nil}, then -each line is individually indented with -@code{indent-according-to-mode} during macro processing. - -@subsubsection Argument :blank - -Specifying this argument adds a special @code{:blank} handler at the -beginning and end of the template. This handler will insert @code{\n} -if the insertion point is not on a line by itself. - -@subsubsection Argument :region - -If there is an active region via @code{transient-mark-mode}, or -@code{mouse-drag-region}, then the @code{REGION} section will be -enabled. - -In addition, @code{REGIONTEXT} will be set the the text in the region, -and that region of text will be ``killed'' from the current buffer. - -If standard-output is NOT the current buffer, then the region will not -be deleted. In this way, you can safely use @code{:region} using -templates in arbitrary output streams. - -@subsubsection Argument :user - -Sets up variables about the current user. - -@table @code -@item AUTHOR -Value of the Emacs function @code{user-full-name} -@item EMAIL -Current Emacs user's email address. -@item LOGIN -Current Emacs user's login name. -@item UID -Current Emacs user's login ID. -@item EMACSINITFILE -This Emacs sessions' init file. -@end table - -@subsubsection Argument :time - -Sets up variables with the current date and time. - -@table @code -@item YEAR -The current year. -@item MONTH -The current month as a number. -@item MONTHNAME -The current month name, unabbreviated. -@item DAY -The current day as a number. -@item WEEKDAY -The current day of the week as an abbreviated name -@item HOUR -The current hour in 24 hour format. -@item HOUR12 -The current hour in 12 hour format. -@item AMPM -Locale equivalent of AM or PM@. Useful with HOUR12. -@item MINUTE -The current minute. -@item SECOND -The current second. -@item TIMEZONE -The timezone string. -@item DATE -The Locale supported date (%D). -@item TIME -The Locale supported time format (%X). -@end table - -@subsubsection Argument :file - -Sets up variables with details about the current file. - -@table @code -@item FILENAME -The filename without the directory part of the current buffer. -@item FILE -The filename without the directory or extension -@item EXTENSION -The filename extension. -@item DIRECTORY -The directory in which the current buffer resides. -@item MODE -Major mode of this buffer. -@item SHORTMODE -Major mode of this buffer without ``-mode''. -Useful for inserting the Emacs mode specifier. -@item section RCS -Show the section RCS if there is a CVS or RCS directory here. -@end table - -@subsubsection Argument :system - -Sets up variables with computer system information. - -@table @code -@item SYSTEMCONF -The ``system-configuration''. -@item SYSTEMTYPE -The ``system-type''. -@item SYSTEMNAME -The ``system-name''. -@item MAILHOST -The name of the machine Emacs derived mail ``comes from''. -@end table - -@subsubsection Argument :kill - -@table @code -@item KILL -The top-most item from the kill ring. -@item KILL2 -The second item in the kill ring. -@item KILL3 -The third item in the kill ring. -@item KILL4 -The fourth item in the kill ring. -@end table - -@node Semantic Arguments -@subsection Semantic Arguments - -@subsubsection Argument :tag - -The :tag argument is filled in with information from Semantic. -The tag in question is queried from the senator tag ring, or passed -in from @srecode{} utilities that use tags in templates. - -@table @code -@item TAG -This is a compound value for the tag in the current senator kill ring, -or something handled via the variable -@code{srecode-semantic-selected-tag}. - -@defvar srecode-semantic-selected-tag -@anchor{srecode-semantic-selected-tag} -The tag selected by a @code{:tag} template argument. -If this is @code{nil}, then @code{senator-tag-ring} is used. -@end defvar - -Use the function part of a macro insert to extract obscure parts -of the tag. -@item NAME -The name of the tag as a string. -@item TYPE -The data type of the tag as a string. -@end table - -If @var{tag} is a function, you will get these additional dictionary -entries. - -@table @code -@item ARGS -A Loop macro value. Each argument is inserted in ARGS@. To create a -comma separated list of arguments, you might do this: - -@example -@{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@} -@end example - -Within the section dictionaries for each argument, you will find both -@var{NAME} and @var{TYPE}, in addition to the automatic section values -for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}. -@item PARENT -The string name of the parent of this function, if the function is a -method of some class. -@item THROWS -In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified. -@end table - -If @var{tag} is a variable, you will get these dictionary entries. - -@table @code -@item DEFAULTVALUE -Enabled if there is a @var{VALUE}. -@item VALUE -An entry in the @var{HAVEDEFAULT} subdictionary that represents the -textual representation of the default value of this variable. -@end table - -If @var{tag} is a datatype, you will get these dictionary entries. - -@table @code -@item PARENTS -Section dictionaries for the parents of this class. Each parent will -have a @var{NAME}. -@item INTERFACES -Section dictionaries for all the implemented interfaces of this -class. Each interface will have a @var{NAME}. -@end table - -Note that data type templates should always have a @code{@{@{^@}@}} -macro in it where the core contents of that type will go. This is why -data types don't have subdictionaries full of the slots in the classes -or structs. - -@node Language Arguments -@subsection language Arguments - -Each language typically has its own argument. These arguments can be -used to fill in language specific values that will be useful. - -@subsubsection Argument :srt - -Used for SRecoder template files. - -@table @code -@item ESCAPE_START -The characters used for an escape start -@item ESCAPE_END -The characters used for an escape end -@end table - -@subsubsection Argument :cpp - -@table @code -@item HEADER -Shows this section if the current file is a header file. -@item NOTHEADER -The opposite of @code{HEADER}. -@item FILENAME_SYMBOL -The current filename reformatted as a C friendly symbol. -@end table - -@subsection Argument :java - -@table @code -@item FILENAME_AS_PACKAGE -Converts the filename into text that would be suitable as a package -name. -@item FILENAME_AS_CLASS -Converts the filename into text that would be suitable as a class-name -for the main class in the file. -@item CURRENT_PACKAGE -Finds the occurrence of ``package'' and gets its value. -@end table - -@subsubsection Argument :el - -Sets @code{PRENAME}. This would be a common prefix from all the -tags in the current buffer. - -Most Emacs Lisp packages have some common prefix used in a way similar -to namespaces in other languages. - -@subsubsection Argument :el-custom - -@table @code -@item GROUP -The name of the Emacs Custom group that instances of @code{defcustom} -ought to use. -@item FACEGROUP -The name of the Emacs Custom group that faces declared with -@code{defface} ought to use. -@end table - -@subsubsection Argument :texi - -@table @code -@item LEVEL -The current section level, such as @code{chapter} or @code{section}. -@item NEXTLEVEL -The next level down, so if @code{LEVEL} is @code{chapter}, then -@code{NEXTLEVEL} would be @code{section}. -@end table - -@subsubsection Argument :texitag - -The @code{:texitag} argument is like the @code{:tag} argument, except that -additional variable @code{TAGDOC} is provided for each tag. - -The @code{TAGDOC} is filled with derived documentation from the tag in -question, and that documentation is also reformatted to be mostly -texinfo compatible. - -@subsection Argument :android - -The @code{:android} argument pulls in information from your current -project. - -@@TODO - add more here. - -@node Developing Template Functions -@chapter Developing Template Functions - -You can develop your own custom template insertion functions. -Doing so is relatively simple, and requires that you write an Emacs -Lisp command. - -If the built in commands don't provide enough options, you will need -to write your own function in order to provide your dictionaries with -the values needed for custom templates. - -In this way, you can build your own code generator for any language -based on a set of predefined macros whos values you need to derive -from Emacs Lisp code yourself. - -For example: - -@example -(defun my-srecode-insert (template-name) - "Insert the template TEMPLATE-NAME into the current buffer at point." - - ;; Read in a template name. - (interactive (list (srecode-read-template-name "Template Name: "))) - (if (not (srecode-table)) - (error "No template table found for mode %s" major-mode)) - (let ((temp (srecode-template-get-table (srecode-table) template-name)) - - ;; Create a new dictionary - (newdict (srecode-create-dictionary))) - - (if (not temp) - (error "No Template named %s" template-name)) - - ;; Add some values into the dictionary! - (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo)) - ;; Optionally show a section - (srecode-dictionary-show-section newdict "BLARG") - - ;; Add in several items over a loop - (let ((my-stuff (get-my-stuff-list))) - (while my-stuff - (let ((subdict (srecode-dictionary-add-section-dictionary - newdict "LOOP"))) - (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff)) - (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff)) - (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff)) - ) - (setq my-stuff (cdr my-stuff))) - - ;; Some templates have arguments that need to be resolved. - (srecode-resolve-arguments temp newdict) - - ;; Do the expansion - (srecode-insert-fcn temp newdict) - )) -@end example - -Lets look at the key functions involved above: - -@section Interactive Completion: - -@defun srecode-read-template-name prompt -@anchor{srecode-read-template-name} -Completing read for Semantic Recoder template names. -@var{prompt} is used to query for the name of the template desired. -@end defun - -@section Template Lookup - -Even if your program does not query the user for a template name, you -will need to locate a template. First, you need to locate the table -to look the template up in. - -@defun srecode-table &optional mode -@anchor{srecode-table} -Return the currently active Semantic Recoder table for this buffer. -Optional argument @var{MODE} specifies the mode table to use. -@end defun - - -@defun srecode-template-get-table tab template-name &optional context application -@anchor{srecode-template-get-table} -Find in the template in mode table @var{TAB}, the template with @var{TEMPLATE-NAME}. -Optional argument @var{CONTEXT} specifies a context a particular template -would belong to. -Optional argument @var{APPLICATION} restricts searches to only template tables -belonging to a specific application. If @var{APPLICATION} is @code{nil}, then only -tables that do not belong to an application will be searched. -@end defun - -For purposes of an @srecode{} application, it is important to decide -what to call your application, and use that with this method call. - -@section Creating dictionaries - -Several dictionary calls are made in this example, including: -@table @code -@item srecode-create-dictionary -@item srecode-dictionary-set-value -@item srecode-dictionary-show-section -@item srecode-dictionary-add-section-dictionary -@end table - -These are documented more fully @ref{Dictionaries}. - -Also used is @code{srecode-resolve-arguments}. To learn more about -that, see @ref{Argument Resolution}. - -@section Template Insertion Commands - -There are several ways to insert a template. It is easiest to just -start with the main entry point. - -@defun srecode-insert-fcn template dictionary &optional stream -@anchor{srecode-insert-fcn} -Insert @var{template} using @var{dictionary} into @var{stream}. -If @var{stream} is @code{nil}, then use the current buffer. -@end defun - -@node Template Naming Conventions -@chapter Template Naming Conventions - -For @srecode{} to work across languages reliably, templates need to -follow a predictable pattern. For every language of similar nature -(OO, functional, doc based) if they all provide the same base -templates, then an application can be written against the base -templates, and it will work in each of the supported language. - -Having consistent templates also makes it easy to use those templates -from a user perspective during basic interactive insertion via -@code{srecode-minor-mode}. - - -NOTES ON THIS CHAPTER: - -These conventions are being worked on. Check w/ CEDET-DEVEL mailing -list if you want to support a language, or write an application and -provide your opinions on this topic. Any help is appreciated. - - -@section Context: File - -Each language should support the @code{file:empty} template. This -will generally use the default copyright insertion mechanism. - -@section Context: Declaration - -Functional languages should attempt to support the following: - -@table @code -@item function -A standalone function. Not a method, external method, or other. -@item method -A method belonging to some class declared outside the textual bounds -of that class' declaration. -@item variable -A global variable. -@item type -A data type. If the language supports several types of datatypes -then do not use this, use more specific ones instead. -@item class -For OO languages, use this instead of @code{type}. -@item include -Include files. -@end table - -For any @semantic{} tag class in your language, you will likely want -to have a corresponding template. - -In order for the @srecode{} function -@code{srecode-semantic-insert-tag} to work, you can create templates -similar to those mentioned above, except with @code{-tag} appended to -the end. This lets a template like @code{function} have user -conveniences when referencing @code{function-tag}, while also -allowing the tag inserter to do its job with a simpler template. - -@section Context: Classdef - -Inside a class definition. These are to be inserted inside the -textual bounds of a class declaration. - -@table @code -@item function -This would be a method of the class being inserted into. -@item constructor -@itemx destructor -Like @code{function} but specific to alloc/delete of an object. -@item variable -This would be a field of the class being inserted into. -@end table - -@section Context: Code - -Inside a body of code, such as a function or method body. - - ---no conventions yet. - -@section Standard Dictionary Values - -For these variables to be useful, standard names should be used. -These values could be provided directly from a Semantic tag, or by an -application. - -@table @var -@item NAME -The name of the declaration being created. -@item PARENT -If the item belongs to some parent type, it would be the full name of -that type, including namespaces. -@item TYPE -A datatype name for a variable, or the return value of a function. -@item DOC -If there is some documentation associated with the item, then DOC -should contain the value. (Optional) -@item ARGS -The ARGS variable defines a section for 0 or more arguments to a function -or method. Each entry in ARGS will follow the rest of these naming -conventions, such as for NAME and TYPE. -@end table - -For templates used by @code{srecode-semantic-insert-tag}, there is -also the following useful dictionary values. - -@table @var -@item TAG -A special insertion value TAG@. You can use semantic functions to turn -the tag into a string. -@item HAVEDEFAULT -@itemx DEFAULT -Default value for a variable. -@end table - -@node Inserting Tag Lists -@chapter Inserting Tag Lists - -Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for -@srecode{} is to convert lists of tags, as produced by @semantic{} -back into code. - -A single function provides the interface for programs to do this, but -it requires any particular language to have provided the correct -templates to make it work. - -@defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries -@anchor{srecode-semantic-insert-tag} -Insert @var{tag} into a buffer using srecode templates at point. - -Optional @var{style-option} is a list of minor configuration of styles, -such as the symbol @code{'prototype} for prototype functions, or -@code{'system} for system includes, and @code{'doxygen}, for a doxygen style -comment. - -Optional third argument @var{point-insert-fcn} is a hook that is run after -@var{tag} is inserted that allows an opportunity to fill in the body of -some thing. This hook function is called with one argument, the @var{tag} -being inserted. - -The rest of the arguments are @var{dict-entries}. @var{dict-entries} -is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{} NAMEn VALUEn). - -The exact template used is based on the current context. -The template used is found within the toplevel context as calculated -by @dfn{srecode-calculate-context}, such as @code{declaration}, @code{classdecl}, -or @code{code}. - -For various conditions, this function looks for a template with -the name @var{class}-tag, where @var{class} is the tag class. If it cannot -find that, it will look for that template in the -@code{declaration}context (if the current context was not @code{declaration}). - -If @var{prototype} is specified, it will first look for templates with -the name @var{class}-tag-prototype, or @var{class}-prototype as above. - -See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in -the dictionary when the templates are called. - -This function returns to location in the buffer where the -inserted tag @var{ends}, and will leave point inside the inserted -text based on any occurrence of a point-inserter. Templates such -as @dfn{function} will leave point where code might be inserted. -@end defun - - -@node Application Writing -@chapter Application Writing - -The main goal of @srecode{} is to provide a strong platform for -writing code generating applications. - -Any templates that are application specific should make an application -declaration for each template file they use. This prevents those -templates from being used outside of that application. - -For example, add this to a file: -@example -set application "getset" -@end example - -In your application Emacs Lisp code, you would then load those -templates. A typical initialization would look like this: - -@example - (srecode-load-tables-for-mode major-mode) - (srecode-load-tables-for-mode major-mode 'getset) -@end example - -These two lines will load in the base templates for the major mode, -and then the application specific templates. - -@defun srecode-load-tables-for-mode mmode &optional appname -@anchor{srecode-load-tables-for-mode} -Load all the template files for @var{mmode}. -Templates are found in the SRecode Template Map. -See @dfn{srecode-get-maps} for more. -@var{appname} is the name of an application. In this case, -all template files for that application will be loaded. -@end defun - - - todo: Add examples. Most core stuff is already described above. - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Index -@unnumbered Index -@printindex cp - -@iftex -@contents -@summarycontents -@end iftex - -@bye diff --git a/doc/misc/todo-mode.texi b/doc/misc/todo-mode.texi deleted file mode 100644 index 9b0ec6e85a3..00000000000 --- a/doc/misc/todo-mode.texi +++ /dev/null @@ -1,1921 +0,0 @@ -\input texinfo.tex @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/todo-mode -@settitle Todo Mode User Manual -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@documentencoding UTF-8 -@c %**end of header - -@copying -Copyright @copyright{} 2013-2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Todo Mode: (todo-mode). Make and maintain todo lists. -@end direntry - -@titlepage -@title Todo Mode User Manual -@subtitle Facilities for making and maintaining todo lists. - -@author Stephen Berman -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex - -@node Top -@top Todo Mode User Manual - -This manual describes the version of Todo mode first appearing in -Emacs 24.4. - -@insertcopying -@end ifnottex - -@menu -* Overview:: -* Todo Mode Entry Points:: -* Key Binding Conventions:: -* Navigation:: Moving within and between categories. -* Editing:: Adding, deleting and changing todo - files, categories and items. -* Todo Archives:: Files of done todo items. -* Marked Items:: Acting on multiple items simultaneously. -* Todo Categories Mode:: Table of categories and item counts. -* Searching for Items:: -* Todo Filtered Items Mode:: Making virtual categories of items from - different categories and files. -* Todo Display Features:: -* Printing Todo Buffers:: -* Legacy Todo Mode Files:: Converting old-style todo files. - -* GNU Free Documentation License:: - -@detailmenu ---- The Detailed Node Listing --- - -Overview - -* Levels of Organization:: -* Todo Items as Diary Entries:: - -Editing - -* File Editing:: -* Category Editing:: -* Item Editing:: - -Item Editing - -* Inserting New Items:: -* Editing Item Headers and Text:: -* Relocating and Removing Items:: - -Relocating and Removing Items - -* Reprioritizing Items:: -* Moving and Deleting Items:: -* Done Items:: - -Todo Archives - -* Creating and Visiting Archives:: -* Todo Archive Mode:: - -Todo Categories Mode - -* Table of Item Counts:: -* Reordering Categories:: - -Todo Filtered Items Mode - -* Filtering Items:: -* Todo Filtered Items Mode Commands:: -* Files of Filtered Items:: - -Todo Display Features - -* Faces:: -* Item Prefix:: -* Other Display Commands and Options:: -@end detailmenu -@end menu - -@node Overview, Todo Mode Entry Points, Top, Top -@chapter Overview - -The Todo mode package provides facilities for making and maintaining -todo lists. A todo list is a list of todo items---things to do (in the -widest sense)---arranged in order of priority, with the highest priority -item at the top of the list and the lowest priority item at the bottom. - -This manual describes the Todo mode user interface. Todo mode comprises -a large number of commands and user options for creating, displaying, -navigating and editing todo lists, distributed across five major modes. -The principle major mode is Todo mode; the other four (Todo Edit mode, -Todo Archive mode, Todo Categories mode, and Todo Filtered Items mode) -are subsidiary to and accessible from Todo mode. - -This version of Todo mode greatly expands on, and in significant ways -differs from, the original version; for details and consequences of the -most important differences, @ref{Legacy Todo Mode Files}. - -@menu -* Levels of Organization:: -* Todo Items as Diary Entries:: -@end menu - -@node Levels of Organization, Todo Items as Diary Entries, , Overview -@section Levels of Organization - -In Todo mode each todo list is identified with a named category, so you -can group together thematically related todo items. Each category is -stored in a file, which thus provides a further level of organization. -You can create as many todo files, and in each as many categories, as -you want. - -All todo files reside in a single directory, whose location is specified -by the user option @code{todo-directory}. This directory may also -contain other types of Todo files, which are discussed later -(@pxref{Todo Archive Mode} and @ref{Todo Filtered Items Mode}). -@c Emacs recognizes Todo files by their extension, so when you visit -@c the files the buffer is in the appropriate mode and the current -@c category is correctly displayed. -When you use a Todo mode command to create a todo file, the extension -@samp{.todo} is automatically added to the base name you choose (as a -rule, this name is also used for the other types of Todo files, which -have their own extensions). As a user, you only have to deal with the -base name of a Todo file. - -When you create a new todo file, you must also add at least one category -to it, and each todo item belongs to a category. It is not possible to -have an uncategorized todo list, but you can always make a catch-all -category with a generic name like ``Todo'', which is in fact the default -name assigned to the first category when you create a new todo file, if -you don't provide a different name; you can change the default by -customizing @code{todo-initial-category}. - -The most basic level of organization is the todo item itself, since it -contains the information about what you want to do. As detailed in -subsequent sections of this manual, most Todo mode commands and user -options concern ways of classifying and deploying this information by -associating various kinds of metadata with it, e.g., the category it -belongs to, its priority, whether it is to be included in the Emacs -diary, date and time stamps, whether it is done or still to do. - -@node Todo Items as Diary Entries, , Levels of Organization, Overview -@section Todo Items as Diary Entries - -You can have todo items show up in the Emacs Fancy Diary display by -including the todo file in your diary file (@pxref{Fancy Diary -Display,,, emacs}). This effectively augments the Emacs diary with -categorized diary entries. All items in an included todo file will -appear in the Fancy Diary display except for those that are marked -with @code{todo-nondiary-marker}. You can add or omit this marking -upon creating a new todo item, or you can do so by editing an existing -item, see @ref{Inserting New Items} and @ref{Editing Item Headers and -Text} for details. - -To ensure the proper display of todo items in the Fancy Diary display, -they must have the format of diary entries, i.e., they have to begin -with a date string recognized by the Emacs diary,@footnote{Two types of -dates recognized by the Emacs diary are not supported in the current -Todo mode implementation: sexp diary entries and date strings in which -the year is omitted (however, the latter type is equivalent to using -@samp{*} for an arbitrary year, which Todo mode does support).} and if -they are longer than one line, all lines but the first must begin with -white space. Todo mode ensures that these requirements are satisfied -(@pxref{Other Display Commands and Options}). - -The Fancy Diary display is also Todo mode aware: if it contains an item -from a Todo mode file, clicking or typing @key{RET} on this item will -switch to the buffer visiting that file and properly display the item's -category, with point on the item. - -@node Todo Mode Entry Points, Key Binding Conventions, Overview, Top -@chapter Todo Mode Entry Points - -To initialize your first todo file, invoke the command @code{todo-show}. -This prompts you for a file name (defaulting to the value of -@code{todo-initial-file}), prompts you for the name of the first -category (defaulting to the value of @code{todo-initial-category}), -creates and visits the file and displays the category in Todo mode, and -then prompts you to enter the first item. If you choose not to enter an -item now, simply type @kbd{C-g}, which leaves the category empty but -otherwise well-formed. If you prefer not to be prompted to enter an -item on adding a new category, disable the option -@code{todo-add-item-if-new-category}. - -Once at least one todo file exists, invoking @code{todo-show} enters -Todo mode. Invoked with a prefix argument, the command prompts for -which todo file to visit. Otherwise, the first invocation of this -command after loading the Todo mode package visits the default todo file -(option @code{todo-default-todo-file}) and shows its first category. -(You can get a different display with the first invocation of -@code{todo-show} by customizing the option @code{todo-show-first}; -@pxref{Todo Categories Mode} and @ref{Files of Filtered Items}.) - -If you leave Todo mode and later invoke @code{todo-show} to re-enter it, -by default this returns you to the current (i.e., last displayed) -category of the current todo file, which is the one in the most recently -selected and still live buffer visiting a todo file. If you disable the -option @code{todo-show-current-file}, then non-initial invocations of -@code{todo-show} always return to the first or current category of the -default todo file. - -If you want to enter Todo mode and go directly to a specific category -instead the first or current category in the current or default todo -file, use the command @code{todo-jump-to-category}; @ref{Navigation}, -for details. You can also enter Todo mode by invoking the command -@code{todo-insert-item}; @ref{Inserting New Items}, for details. - -The most convenient way to use these commands to enter Todo mode is to -define global key bindings for them in your init file. Good choices -are @kbd{C-c t} for @code{todo-show}, @kbd{C-c j} for -@code{todo-jump-to-category} and @kbd{C-c i} for -@code{todo-insert-item}, since these commands are bound to @kbd{t}, -@kbd{j} and @kbd{i}, respectively, in Todo mode. - -@c You can also visit a Todo file via @code{find-file} or Dired, like any -@c other file, and since Emacs recognizes it, the buffer will automatically -@c be in the appropriate Todo mode. Moreover, as long as the command you -@c use to visit the file is listed in the option -@c @code{todo-visit-files-commands} (which by default contains -@c @code{find-file} and @code{dired-find-file}), it will also correctly -@c display the file's first category on first visiting the file (otherwise -@c you have to use one of the commands for navigating between categories in -@c order to get a proper display). - -You can leave Todo mode by typing @kbd{q} (@code{todo-quit}), which -buries the current todo file buffer. Doing this also saves any changes -you have made to the file, and leaves both the file and the category -that was displayed on quitting current for subsequent Todo mode commands -(unless the buffer made current by quitting is visiting another file and -category in Todo mode, in which case the latter become current for Todo -mode commands). - -@node Key Binding Conventions, Navigation, Todo Mode Entry Points, Top -@chapter Key Binding Conventions - -For Todo mode commands to function properly, it is essential to maintain -the correct format at all three levels of organization---item, category, -and file. Todo mode tries to minimize the risk of format corruption by -hiding certain parts of the format from the user, making the buffer -read-only and suppressing the self-insertion keys. Consequently, it is -normally impossible to make changes to your todo files without -explicitly invoking Todo mode commands. - -A beneficial side effect of this restrictiveness is that you can invoke -almost all Todo commands by typing ordinary printing characters, either -singly or in specified sequences, without using modifier keys, except -for the shift key for capitalization and the raw prefix argument -@kbd{C-u}; numeric prefix arguments can be entered just by typing a -number key. - -The predefined key bindings in Todo are more or less mnemonic. As a -rule, key sequences beginning with @kbd{C} (capital @samp{C}, not the -control key) are bound to commands applying to categories, sequences -beginning with @kbd{F} apply to (non-archive) file-level commands, and -those beginning with @kbd{A} apply to archives (a special type of Todo -file; @ref{Todo Archive Mode}). Todo commands applying to items, -which constitute the majority, are bound to lower case key sequences. - -@node Navigation, Editing, Key Binding Conventions, Top -@chapter Navigation - -The navigation commands are for making another todo file, category, or -item the current one by moving point to it.@footnote{Many editing -commands can also do this by side effect, but since that is not their -main function, they are not included in this section.} Since these -commands are likely to be used frequently and repetitively, it is -convenient for their key bindings to be single lower case keys, even for -navigation commands applying to categories and files. - -Two of the navigation commands were already mentioned in @ref{Todo -Mode Entry Points}: - -@table @kbd - -@item t -Display another todo file in the selected window (@code{todo-show}). -When you invoke this command in Todo mode, it prompts for a file name, -which you can choose via minibuffer completion (like invoking -@code{todo-show} with a prefix argument outside of Todo mode). If a -buffer is already visiting that file, it displays its current category; -if invoking @kbd{t} opens the file, it display its first category (by -default; see the option @code{todo-show-first} for other possibilities). - -@item j -Display another todo category in the selected window -(@code{todo-jump-to-category}). When you invoke this command, it -prompts for a category name, which you can choose via minibuffer -completion. The candidates for completion include the categories in the -current todo file as well as those in the files listed in the option -@code{todo-category-completions-files}. If you type @key{RET} without -choosing a category, the current category of the current todo file is -automatically selected (this can be a useful shortcut when you invoke -@code{todo-jump-to-category} outside of Todo mode). If you type the -name of a non-existing category, you can add this to the file as a new -category and jump to it. If you invoke this command with a prefix -argument, it first you prompts for which todo file to jump to (which you -can also choose with minibuffer completion) and then for which category -from that file; in this case, completion is only against the categories -in the selected file. -@end table - -It is also convenient to navigate back and forth sequentially between -the categories of a single todo file. The categories of a todo file are -numbered consecutively starting with @samp{1}.@footnote{A category's -number is automatically assigned when the category is created: the -category is appended to the end of the file, so its number is simply the -highest until another category is added. There is no command in Todo -mode to reorder the numbering of the categories in a todo file, but this -is possible from the file's table of categories; @ref{Todo Categories -Mode}.} The current category's number and name appear in the mode line. - -@table @kbd - -@item f -Move point to the first item of the category numerically directly -following the current category (@code{todo-forward-category}). - -@item b -Move point to the first item of the category numerically directly -preceding the current category (@code{todo-backward-category}). -@end table - -With @kbd{f} and @kbd{b} you can cycle through the categories, so for example, -if the last category is current and you type @kbd{f}, then the first -category becomes current. - -You can also navigate between the items in the current category: - -@table @kbd - -@item n -Move point down to the next item below the current one (i.e., to the -item with the next lower priority) (@code{todo-next-item}). - -@item p -Move point up to the item directly above the current one (i.e., to the -item with the next higher priority) (@code{todo-previous-item}). -@end table - -These commands also accept a positive numeric prefix argument; e.g., -typing @kbd{5 n} or @kbd{5 p} navigates in one step to the item five items lower -or higher than the current one. - -Navigation to other types of Todo files is discussed in the relevant -sections below. - -@node Editing, Todo Archives, Navigation, Top -@chapter Editing - -Editing in Todo mode means making structural or textual changes at one -of the levels of organization (file, category, or item). Structural -editing includes adding, relocating and removing units of information -at a level; textual editing includes renaming files or categories and -changing an item's content or date/time stamp, or adding certain kinds -of marks or tags to items. Todo mode provides commands, detailed in -the following sections, which enable you to quickly and safely make -changes to your todo lists, without having to worry about preserving -the file format. - -To save changes you make to the current todo file, -type @kbd{s} (@code{todo-save}). Changes are also saved on quitting -Todo mode with @kbd{q}. - -@menu -* File Editing:: -* Category Editing:: -* Item Editing:: -@end menu - -@node File Editing, Category Editing, , Editing -@section File Editing and Todo Edit Mode - -There are four file-level editing commands: - -@table @kbd - -@item F a -Add a new todo file (@code{todo-add-file}). This command prompts for -a name and creates the file in @code{todo-directory}, adding the -@samp{.todo} extension (so you should not include the extension in the -name you enter). The command also prompts for the file's first -category and, if option @code{todo-add-item-if-new-category} is -enabled (the default), for that category's first item. - -@item F r -Rename the current todo file (@code{todo-rename-file}). If called with -a prefix argument, prompt for a todo file and rename it. If the todo -file has an archive (@pxref{Todo Archive Mode}) or there are -corresponding filtered items files (@pxref{Todo Filtered Items Mode}), -this command renames these accordingly. If there are live buffers -visiting any of these files, the command also renames them accordingly. - -@item F k -Delete the current todo file (@code{todo-delete-file}).@footnote{The key -binding of this command is mnemonic for ``kill'' to parallel the binding -@kbd{k} for item deletion, since @kbd{d} is bound to another item -editing command (@pxref{Done Items}).} If the todo file has an archive -(@pxref{Todo Archive Mode}), prompt for whether to delete that as well. -This command also kills the buffers visiting the deleted files. - -@item F e -This command (@code{todo-edit-file}) changes the buffer's major mode to -Todo Edit mode. In this mode the entire file is visible, the buffer is -writable and you can use the self-insertion keys and standard Emacs -editing commands to make changes. To return to Todo mode, type @kbd{C-x -C-q} (@code{todo-edit-quit}). - -The command @kbd{F e} is not intended for normal editing of items and -categories, as it circumvents the restrictions that Todo imposes to -protect against file format corruption (i.e., all categories, not just -the current one, and all internal formatting are exposed and editable). -It is provided primarily as a convenience for two types of use cases -that are likely to arise infrequently. One is to be able to use -standard Emacs commands like @code{query-replace} to replace a piece of -text that occurs in different categories throughout the file. The other -use case is to recover from a mistake, such as accidentally deleting an -item, since this cannot be undone in Todo mode. - -Using @kbd{C-x C-q} to quit Todo Edit mode provides a measure of -safety, since it runs a file format check, signaling an error if the -format has become invalid. However, this check cannot tell if the -number of items or categories changed, which could result in the file -containing inconsistent information (see the cautionary note in -@ref{Reordering Categories}, for more details). Invoking @kbd{F e} -displays a warning to this effect. -@end table - -@node Category Editing, Item Editing, File Editing, Editing -@section Category Editing - -The following commands are available for editing specifically at the -category level (for two other category-editing commands, which are -extensions of item commands, @pxref{Editing Item Headers and Text}): - -@table @kbd - -@item C a -Add a new category to the current todo file and make that category -current (@code{todo-add-category}). If called with a prefix argument, -prompt for a file name and add the new category to that file. This -command is similar to using @kbd{j}, but it only accepts category names -that are not the name of an existing category in the file. - -@item C r -Rename the current category (@code{todo-rename-category}). If this -category's file has an archive (@pxref{Todo Archive Mode}) with a -corresponding category, rename the category there as well. - -@item C m -Move the current category (with all its items) to another todo file -(@code{todo-move-category}). If this category's file has an archive -(@pxref{Todo Archive Mode}) with a corresponding category, this command -also moves that category to the archive file corresponding to the moved -to todo file; if there is no such archive file, the command creates it -and adds the category. - -@item C k -Delete the current category (@code{todo-delete-category}).@footnote{This -binding is mnemonic for ``kill'' to parallel the binding @kbd{k} for -item deletion, since @kbd{d} is bound to another item editing command -(@pxref{Done Items}).} To delete a category that contains items, you -have to confirm your intent; if the category is empty, deletion is -immediate. - -@item C g -Merge the items of one category into another category, delete the first -category and make the second category current -(@code{todo-merge-category}). If both the first and second categories -also have archived items (@pxref{Todo Archive Mode}), merge the former -to the latter. If only the first category has archived items, rename -the archive category to the merged to category. Minibuffer completion -of the name of the category merged to works as with the navigation -command @kbd{j}, and as with that command, passing a prefix argument, -i.e., typing @kbd{C-u C g}, prompts for a file and confines merging to a -category in that file. -@end table - -@node Item Editing, , Category Editing, Editing -@section Item Editing - -Todo mode provides commands for adding new items as well as textually -changing, deleting and relocating existing items. The commands and -associated options for adding and editing items, in particular, offer -you a lot of flexibility to fine-tune these operations to your needs. - -@menu -* Inserting New Items:: -* Editing Item Headers and Text:: -* Relocating and Removing Items:: -@end menu - -@node Inserting New Items, Editing Item Headers and Text, , Item Editing -@subsection Inserting New Items - -To add a new todo item to a category, type @kbd{i}, which is bound to -the command @code{todo-insert-item}. - -@table @kbd - -@item i -This command is the entry point for inserting new items into a -category (@code{todo-insert-item}). It prompts for additional keys -until reaching a complete key sequence, which specifies the insertion -parameters you wish to apply (see below). It then prompts for the -text of the item, which you enter in the minibuffer.@footnote{There -are two insertion parameters that override prompting for and manually -entering the new item's text, see below.} Called with one prefix -argument, it also prompts for a category, and called with two prefix -arguments, it prompts for both a file and a category from that file, -and inserts the item accordingly; category name completion works as -with the navigation command @kbd{j}. Finally, it inserts the item -into the current or selected category of the current or selected todo -file at the position in the list corresponding to the priority you -choose, which also depends on the insertion parameters. -@end table - -@noindent -The name of this command reflects the fact that you can insert a new -item into the category at any position, giving each new item any -priority in the list, whereas speaking of adding an item to a category -suggests appending it to the top or bottom. - -In addition to its file and category, each newly inserted todo item -has a priority in the category and begins with a header string, which -includes at least the current date in the same format used by -@code{diary-insert-entry} (@pxref{Date Formats,,, emacs}). You can -specify the priority and the content of the header string in two ways. -First, you can set the following item insertion options, which apply -on every invocation of @code{todo-insert-item}. - -@itemize @bullet - -@item -@code{todo-default-priority} is for automatically assigning a new item -the highest or lowest priority in the category, if you do not -explicitly assign it a priority on invoking @code{todo-insert-item}. -By default, such new items are given highest priority, i.e., inserted -at the top of the list. - -@item -@code{todo-always-add-time-string} is for including or omitting the -current time in the new item's header. By default, this time string -is omitted. - -@item -@code{todo-include-in-diary} is for specifying whether the item -appears in the Fancy Diary display (when the todo file is included in -the Emacs diary file) by adding or omitting -@code{todo-nondiary-marker}. By default, new todo items are so -marked, thus excluded from the diary. - -@item -@code{todo-diary-nonmarking} is for adding or omitting -@code{diary-nonmarking-symbol} to items displayed in the diary, to -control whether they are marked in the calendar (@pxref{Format of -Diary File,,, emacs}). By default, todo items that are diary entries -lack this symbol, thus are marked in the calendar. -@end itemize - -Beside setting these options, for more flexibility you can also pass -certain parameters on each invocation of @code{todo-insert-item}. -These parameters concern not only the new item's priority and header, -but also its textual content. You pass these parameters by typing a -sequence of one or more keys after the initial @kbd{i}. - -Here is a list of the item insertion parameters together with their -mnemonically associated keys@footnote{The non-mnemonic choice of -@kbd{i} for the parameter @samp{default} is motivated by the -convenience of repeating the @kbd{i} used to invoke -@code{todo-insert-item}.} and descriptions of their effect in -@code{todo-insert-item}: - -@enumerate - -@item -@samp{default} (@kbd{i}): Prompt for the new item's priority -(a number between 1 and one more than the number of items already in -the category) and add a header string conforming to the values of the -above options. - -@samp{copy} (@kbd{p}): Make an exact copy of the item at point, -including its header string, and prompt for its priority. (This is -useful for quickly making a new todo item whose text or header you -want to differ only partly from that of an existing item: after -inserting the copy, you can quickly edit it as needed by using -operations described in the next section.) - -@item -@samp{diary} (@kbd{y}): Override the option -@code{todo-include-in-diary}; that is, add @code{todo-nondiary-marker} -if the option is non-@code{nil}, omit this marker if the option is @code{nil}. - -@samp{nonmarking} (@kbd{k}): Override the option -@code{todo-diary-nonmarking}; that is, add -@code{diary-nonmarking-symbol} if the option is non-@code{nil}, omit this -symbol if the option is @code{nil}. Since this symbol only applies to diary -items, the new item is automatically marked as such, i.e., lacks -@code{todo-nondiary-marker}. - -@item -@samp{calendar} (@kbd{c}): Pop up the Emacs calendar and click a date -in it to use that date in the new todo item's header. - -@samp{date} (@kbd{d}): Prompt for entering in the minibuffer -the year, month (with completion) and day number components of the -header. - -@samp{dayname} (@kbd{n}): Prompt for entering in the minibuffer -a weekday name as the date header instead of a year-month-day string. - -@item -@samp{time} (@kbd{t}): Prompt for entering a time string in -the minibuffer instead of automatically inserting the current time; -however, typing @key{RET} at the prompt enters the current time if -@code{todo-always-add-time-string} is non-@code{nil}, otherwise it enters the -empty string (i.e., no time string). - -@item -@samp{here} (@kbd{h}): Insert the new item in the position of -the item at point, pushing that and all lower items in the category -down, i.e., lowering their priority, by one. - -@samp{region} (@kbd{r}): Use the text of the selected region as the -text of the new item, and insert this in accordance with the item -insertion options and other parameters passed. If the option -@code{todo-use-only-highlighted-region} is non-@code{nil}, then use the -region only when it is highlighted; otherwise, use the region -regardless of highlighting. -@end enumerate - -Note that the parameters are divided into five numbered groups; within -a group, the parameters are mutually exclusive. Hence, to build a -complete insertion operation, you select at most one parameter from at -least one of these groups, by typing the corresponding key. If you -want to apply more than one parameter, you must type the corresponding -keys in the order of the numbered groups, subject to the following -constraints. - -The keys of groups 2-4 are continuation keys, that is, each can be -followed by a key from a following group. If you want to finish the -sequence with a continuation key, you must double the final key. For -example, @kbd{i y} is not a complete key sequence; rather, you must -type @kbd{i y y}. - -By contrast, the keys of groups 1 and 5 are final keys; for example, -@kbd{i i} and @kbd{i h} are complete sequences. The reason for making -two separate groups of the final keys is that the parameters -@samp{default} and @samp{copy} cannot be combined with any other -parameters, while @samp{here} and @samp{region} can be combined with -any of the parameters from groups 2-4. - -To aid you in building item insertion key sequences, when you type an -insertion key, this displays a prompt in the echo area showing pairs -of the remaining possible keys and their associated parameters, -grouped and ordered in accordance with the above list. The initial -prompt, after typing @kbd{i} to invoke @code{todo-insert-item}, looks -like this: - -@example -Press a key (so far `i'): @{ i=>default p=>copy @} @{ y=>diary k=>nonmarking @} @{ c=>calendar d=>date n=>dayname @} t=>time @{ h=>here r=>region @} -@end example - -@noindent If you now type @kbd{y}, the prompt changes to this: - -@example -Press a key (so far `i y'): y=>diary:GO! @{ c=>calendar d=>date n=>dayname @} t=>time @{ h=>here r=>region @} -@end example - -@noindent Notice that the pair @samp{k=>nonmarking} is now absent, since it -belongs to the same group as the selected pair @samp{y=>diary}, hence -is no longer available for this sequence. Since @kbd{y} is a -continuation key, it is still available, but now the string -@samp{:GO!} is appended to the pair to remind you that pressing this -key again will complete the sequence. - - - -@c Here are some examples of item insertion command key sequences: - -@c @itemize @bullet - -@c @item -@c @kbd{i h} inserts a new item at the position of the item at point (pushing -@c the latter down) with a header containing the current date and, -@c depending on the values of the mentioned options, possibly the current -@c time and diary-related markings. -@c @item -@c @kbd{i y h} does the same as the preceding command, except that -@c @code{todo-nondiary-marker} is added if @code{todo-include-in-diary} is -@c non-@code{nil} and omitted if that option is @code{nil}; that is, -@c the diary key @kbd{y} @c overrides the setting of this option. -@c @item -@c @kbd{i y t h} does the same as the preceding command, except that it -@c prompts for a time string instead of automatically inserting the -@c current time; however, typing @key{RET} at the prompt returns the -@c current time if @code{todo-always-add-time-string} is non-@code{nil}, -@c otherwise the empty string (i.e., no time string). -@c @item -@c @kbd{i y t t} does the same as the preceding command, except that it -@c prompts for the item's priority and inserts it accordingly. -@c @end itemize - - -An alternative to the key sequence @kbd{i c c} for choosing the item's -date from the calendar is also available: when point is already on a -date in the calendar, typing @kbd{i t} -(@code{todo-insert-item-from-calendar}) prompts for a new item and its -priority and inserts it in the current category. This command, like -@code{todo-insert-item}, also accepts one or two prefix arguments for -choosing the category via minibuffer completion. Note, however, that -the key sequence @kbd{i t} is not defined in Todo mode but in the -Calendar mode keymap. It is a convenient shortcut if you happen to be -using the calendar when you decide to make a new todo item. (Contrast -this with passing the @samp{calendar} parameter, which pops open the -calendar after you have entered the item's text, and then you can -choose a date from the calendar.) - - -@node Editing Item Headers and Text, Relocating and Removing Items, Inserting New Items, Item Editing -@subsection Editing Item Headers and Text - -To make changes to an existing item's content or header, type @kbd{e}, -which is bound to the command @code{todo-edit-item}. - -@table @kbd - -@item e -This command is the entry point for textually editing existing items -in a category (@code{todo-edit-item}). It prompts for additional keys -until reaching a complete key sequence, which specifies the editing -parameters you wish to apply (see below), and then executes the -editing operation accordingly. -@end table - -Here is a list of the item editing parameters together with their -mnemonically associated keys and descriptions of their effect in -@code{todo-edit-item}. The list is divided into three groups, for -reasons explained below. - -@enumerate 1 - -@item -@samp{edit} (@kbd{e}): Edit the text of the current item in the -minibuffer; the item's header is omitted. - -@samp{header} (@kbd{h}): Edit the text and header of the current item -in the minibuffer. - -@samp{multiline} (@kbd{m}): Edit the text of the current item in a -special buffer in Todo Edit mode. After editing, type @kbd{C-x C-q} -to return to Todo mode.@footnote{This runs a format check to ensure -the item is well-formed. However, unlike the command @kbd{F e} -(@pxref{File Editing}), @kbd{e m} does not expose you to the risk of -putting the file in an inconsistent state, since it puts only the -current item in Todo Edit mode.} - -@samp{diary} (@kbd{y}): Change the current item's diary inclusion -status by adding @code{todo-nondiary-marker} if the item lacks this, -or by removing it if present. - -@samp{nonmarking} (@kbd{k}): Change the current item's calendar -marking status by adding @code{diary-nonmarking-symbol} if the item -lacks this, or by removing it if present. Since this symbol only -applies to diary items, the item is automatically marked as such, -i.e., if @code{todo-nondiary-marker} is present, it is removed. - -@samp{date} (@kbd{d}): Prompt for a final key from the second group -of item editing parameters to edit the current item's date string. - -@samp{time} (@kbd{t}): Edit the current item's time string, if -present; otherwise, add one. Typing @key{RET} at the prompt enters -the current time if @code{todo-always-add-time-string} is non-@code{nil}, -otherwise it enters the empty string (i.e., no time string). -@end enumerate - -@noindent -Editing the text of a lengthy item in the minibuffer can be -inconvenient; therefore, if you type @kbd{e e} or @kbd{e h} on an item -whose text contains more than one logical line, the effect is the same -as if you had typed @kbd{e m}, that is, you switch a special buffer in -Todo Edit mode. - -When you pass any of the parameters of the preceding group, except for -the @samp{date} parameter, this completes the item editing invocation -begun by typing @kbd{e}. Pressing @kbd{d} to pass the @samp{date} -parameter, however, prompts you with the following parameters and -their associated keys, and pressing any of these completes the -invocation. - -@enumerate 2 - -@item -@samp{full} (@kbd{f}): Successively prompt for editing the year, month -(with completion) and day number parts of the current item's date -string, and, if the option @code{todo-always-add-time-string} is -non-@code{nil}, also for editing its time string. - -@samp{calendar} (@kbd{c}): This pops up the Emacs calendar, and after -you type @key{RET} on a date in the calendar makes that date the -item's date. - -@samp{today} (@kbd{a}): Make the item's date today's date. - -@samp{dayname} (@kbd{n}): Prompt for a weekday name (with completion) -and make it the item's date header. Note that this replaces an -existing date string, it does not add the day name to the date string. - -@samp{year} (@kbd{y}): Edit just the year component of the current -item's date string. - -@samp{month} (@kbd{m}): Edit just the month component of the current -item's date string (with completion). - -@samp{daynum} (@kbd{d}): Edit just the day number component of the -current item's date string. -@end enumerate - -@noindent -With the latter three parameters you can add a positive or negative -numeric prefix argument to the invocation: this increments or -decrements the selected date component by the given number and -automatically adjusts the other date components if necessary. For -example, if the item's date string is ``January 1, 2013'', then typing -@kbd{- 3 e d d} results in ``December 29, 2012''. - -The first two groups of parameters apply only to todo items that are -not marked as done (@pxref{Done Items}); the two parameters of the -third group, in contrast, apply only to done todo items. You cannot -edit the text of such items, but you can edit or delete the comment -you may have added on marking the item as done (@pxref{Done Items, -@code{todo-item-done}},), or retroactively add a comment, by passing -either of these parameters. - -@enumerate 3 - -@item -@samp{add/edit comment} (@kbd{c}): Edit the current done item's -comment, if it has one; otherwise, prompt for and add a comment. - -@samp{delete comment} (@kbd{d}): Delete the current done item's -comment, if it has one. -@end enumerate - -The command @code{todo-edit-item} is sensitive to the distinction -between not done and done todo items. If you type @kbd{e} when point -is on a done item, this displays the following prompt in the echo -area: - -@example -Press a key (so far `e'): c=>add/edit comment d=>delete comment -@end example - -@noindent -Only by typing @kbd{c} or @kbd{d} in response to this prompt can you -complete the invocation. In contrast, if you type @kbd{e} when point -is on a non-done todo item, this displays the following prompt in the -echo area, and you can continue or complete the invocation only by -typing one of the listed keys: - -@example -Press a key (so far `e'): e=>edit h=>header m=>multiline y=>diary k=>nonmarking d=>date t=>time -@end example - -As noted above, passing the @samp{date} parameter does not complete -the invocation of @code{todo-edit-item}; rather, it displays the -following prompt, and typing any of these keys does complete the -invocation: - -@example -Press a key (so far `e d'): f=>full c=>calendar a=>today n=>dayname y=>year m=>month d=>daynum -@end example - -In addition to the item-level invocations @kbd{e y}, to change the -current item's diary inclusion status, and @kbd{e k}, to change the -current item's calendar marking status, Todo mode also has two related -category-level commands: - -@table @kbd - -@item C e y -@itemx C e k -Add @code{todo-nondiary-marker} and @code{diary-nonmarking-symbol}, -respectively, to all todo items in the current category; if invoked with -a prefix argument, these markings are removed from all items in the -category. -@end table - -@noindent -Like @kbd{e k}, @kbd{C e k} automatically removes @code{todo-nondiary-marker} -from all items it is present on, since only diary items can bear -@code{diary-nonmarking-symbol}. - -Since categories often contain a mix of items marked for diary -inclusion and exclusion, and of the former, a mix of those to be -marked and those not to be marked in the calendar, it is more useful -for these category-level commands, unlike the item-level commands, not -to be toggles, but to have the same effect on all items in the -category, and take a prefix argument to reverse the effect. (If you -really want to toggle the diary-inclusion and calendar-marking status -of all items in the category, you can do this by marking all the items -and then invoking @kbd{e y} or @kbd{e k}, @pxref{Marked Items}). - -@node Relocating and Removing Items, , Editing Item Headers and Text, Item Editing -@subsection Relocating and Removing Items - -In addition to inserting a new todo item and changing the text or header -of an existing item, you can also move an item to another category -(i.e., recategorize it), change its priority within its category, delete -it from the category and file, or mark it as a ``done'' item, which -removes it from the todo list but does not delete it. - -@menu -* Reprioritizing Items:: -* Moving and Deleting Items:: -* Done Items:: -@end menu - -@node Reprioritizing Items, Moving and Deleting Items, , Relocating and Removing Items -@subsubsection Reprioritizing Items - -There are three ways to change a todo item's priority: - -@table @kbd - -@item r -Raise the current item's priority by one, exchanging its position in the list -with that of the item directly above it (@code{todo-raise-item-priority}). - -@item l -Lower the current item's priority by one, exchanging its position in the list -with that of the item directly below it (@code{todo-lower-item-priority}). - -@item # -Prompt for a number and relocate the item to the corresponding -position in the list (@code{todo-set-item-priority}). For example, -entering @kbd{3} at the prompt makes the item the third in the -category, i.e., gives it third highest priority; all lower priority -items are pushed down by one. You can also pass the desired priority -as a numeric prefix argument, e.g., @kbd{3 #} gives the item third -highest priority without prompting. (Prefix arguments have no effect -with @kbd{r} or @kbd{l}.) -@end table - -@node Moving and Deleting Items, Done Items, Reprioritizing Items, Relocating and Removing Items -@subsubsection Moving and Deleting Items - -You can move an item to another category, thereby recategorizing it: - -@table @kbd - -@item m -Move the item at point to another category (@code{todo-move-item}). -This prompts for a category to move the item to, displays that category, -prompts for the priority of the moved item in the category moved to and -inserts the item accordingly. Minibuffer completion of the name of the -category moved to works as with the navigation command @kbd{j}, and as -with that command, passing a prefix argument prompts for a file and -moves the item to a category in that file; and if the category name you -enter is new, then you are asked whether to add the category to the -file, and if you affirm, the item is moved to the new category. -@end table - -You can delete an item, thereby permanently (and, as far as Todo mode -is concerned, irrevocably) removing it from the todo file: - -@table @kbd - -@item k -Delete the todo item at point (@code{todo-delete-item}; the binding is -mnemonic for ``kill'', since @kbd{d} is used for marking items as done -(@pxref{Done Items}); but note that @kbd{k} does not put the item into -the kill ring). This command requires confirmation that you want to -delete the item, since you cannot undo the deletion in Todo mode. (You -could use @kbd{F e} to recover the item, but be aware that this would -put the file in an inconsistent state, which you can recover from, but -not without a risk; cf.@: the cautionary note in @ref{Reordering -Categories}.) -@end table - -@quotation Note -Todo commands that require user confirmation, such as @kbd{k}, use a -modified form of @code{y-or-n-p}, which by default only accepts @kbd{y} -or @kbd{Y}, but not @key{SPC}, as an affirmative answer. This is to -diminish the risk of unintentionally executing the command, which is -especially important with commands that do deletion, since there is no -Todo command to undo a deletion. If you want to be able to use @key{SPC} for -confirmation, enable the option @code{todo-y-with-space}. -@end quotation - -@node Done Items, , Moving and Deleting Items, Relocating and Removing Items -@subsubsection Done Items - -When the activity or thing that a todo item is about has been done, it -is natural to eliminate the item from the todo list. But instead of -deleting it permanently, you may prefer to keep a record of your -accomplishments by marking the item as done. In Todo mode, this removes -the done item from the todo list, so as not to clutter it up, and stores -it elsewhere. Such stored items form a record or diary of things done. -The Todo package provides two such stores: the ``done items'' section of -a Todo category, described here, and done item archives (@pxref{Todo -Archive Mode}). - -@table @kbd - -@anchor{todo-item-done} -@item d -This command (@code{todo-item-done}) removes the todo item at point -from the todo list, appends to the original header a header consisting -of @code{todo-done-string} (by default @samp{DONE }) and the current -date, and if @code{todo-always-add-time-string} is enabled, also the -current time, and adds the resulting done item to the top of the done -items section of the category. Invoked with a prefix argument, it -also prompts you to enter a comment, which is appended to the end of -the done item, prefixed with @code{todo-comment-string} (by default -@samp{COMMENT: }). -@end table - -A category's done items section is located below the last todo (i.e., -not done) item in the category. By default this section is hidden from -view. There are two commands for viewing and hiding done items; since -these are toggle commands, for convenience they also have a single key -binding: - -@table @kbd - -@item C v -@itemx v -Make the done items section of the current category visible if it is -hidden, or hide it if it is visible -(@code{todo-toggle-view-done-items}). If you always want to see the -done items section on entering a category, enable the option -@code{todo-show-with-done}; you can still use @kbd{C v} or @kbd{v} to -hide (and unhide) it. - -@item F V -@itemx V -Toggle the standard category display in the current todo file, i.e., -display only the done items section of each category in the file, or if -this is visible, hide it again and display only the todo items section -(@code{todo-toggle-view-done-only}). -@end table - -Since done items are meant to be a record of your finished todo items, -you cannot apply to them the same kinds of editing operations -available to unfinished todo items. However, as explained in -@ref{Editing Item Headers and Text} and repeated below for -convenience, you can edit or delete a done item's comment, or -retroactively add a comment. You can also relocate a done item, and -you can revert its done status, making it an unfinished item again. - -@table @kbd - -@item e c -Edit the current done item's comment, if it has one; otherwise, prompt -for and add a comment. - -@item e d -Delete the current done item's comment, if it has one. - -@item m -Move the done item at point to the top of the done items section of -another category (@code{todo-move-item}). This is useful in case, -after having finished a todo item and relocated it to its category's -done items section, you create a category that is better suited to the -content of the done item than its current category; in other words, -you can retroactively recategorize the done item. - -@item u -If you decide the done item at point is not done after all, this command -``undoes'' it, i.e., restores it to the todo list of its category, with -the priority you choose for it (@code{todo-item-undone}). If the done -item has a comment, you are asked whether to delete it from the restored -item. -@end table - -@node Todo Archives, Marked Items, Editing, Top -@chapter Todo Archives - -When the done items section of a category itself starts to become -cluttered, or if you just want to store some accomplished todo items in -a separate file, you can move them to a Todo archive. This is a file -with exactly the same structure as a todo file, i.e., divided into -categories, but differs in that the categories contain only done items. -Todo archives reside, like todo files, in @code{todo-directory} but have -the extension @samp{.toda} instead of @samp{.todo}. - -@menu -* Creating and Visiting Archives:: -* Todo Archive Mode:: -@end menu - -@node Creating and Visiting Archives, Todo Archive Mode, , Todo Archives -@section Creating and Visiting Archives - -Todo mode provides the following command for archiving items: - -@table @kbd - -@item A d -This command (@code{todo-archive-done-item}) archives the done item at point. -Invoked with a prefix argument, it archives all done items in the -current todo category. If an archive for the current todo file -already exists and contains a category with the same name as the -current todo category, then this command moves the done item to the -top of the corresponding archive category. If the archive exists but -it does not have a corresponding category, this command creates the -category in the archive and moves the done item to it. If no archive -for the todo file exists, the command creates both the archive file, -using the same base name as that of the todo file, as well as the -category, and moves the done item to it. -@end table - -Typing @kbd{A d} is also the only way within the Todo mode package to -create an archive file and its categories. Consequently, as a rule each -archive file corresponds to exactly one todo file and has the same base -name as this file, and each category in an archive file corresponds to -and has the same name as a category in the corresponding todo file. -Exceptions can only arise if you delete a todo file but not the -corresponding archive, or if you delete a category in a todo file that -has a corresponding category in an archive. - -You might be inclined to do the latter if you have archived all the -items from a given todo category and you don't plan to add new items to -it. In particular, if you have numerous such empty categories in a todo -file, this can make sequential navigation in the file annoying. You can -avoid this annoyance by deleting these categories, but only at the cost -of putting the todo file out of synch with the archive file. - -You may find it preferable not to delete empty todo categories but to -enable the option @code{todo-skip-archived-categories}. When this is -non-@code{nil}, such empty todo categories are skipped over by the sequential -category navigation commands @kbd{f} and @kbd{b}, so they don't distract you -while navigating and you maintain the structural correspondence between -todo and archive files (you can also still jump to empty todo categories -with @kbd{j}). - -If you rename a todo category that has a corresponding category in an -archive, the archive category is also automatically identically renamed. -Likewise, if you move such a todo category to another file; in this -case, if there is no archive file corresponding to the todo file the -category is moved to, then the archive is automatically created and the -archived category is moved to it. - -There are two commands in Todo mode for visiting archive files: - -@table @kbd - -@item A f -Switch to a buffer displaying the archived category corresponding to the -current todo category (@code{todo-find-archive}). If the todo category -has no archived items, the command asks if you want to visit the archive -anyway. If there is no archive for this todo file, it asks if you want -to visit another archive, which you can select via minibuffer -completion. - -@item A c -Choose an archive to visit, whether or not the current todo file has an -archive (@code{todo-choose-archive}). -@end table - -As with todo files, you can also visit a Todo archive by invoking a -standard Emacs file-visiting command; this displays the first (on the -initial invocation) or current category of the archive. - -@node Todo Archive Mode, , Creating and Visiting Archives, Todo Archives -@section Todo Archive Mode - -When you visit a Todo archive, the buffer is in Todo Archive mode. It -displays categories just as in Todo mode, except that they only contain -done items. It provides the same sequential navigation commands as -Todo mode: @kbd{f} and @kbd{b} navigate between the categories of the current -archive, and @kbd{n} and @kbd{p} navigate between the done items of the current -archive category. - -The commands @kbd{t} and @kbd{j} are also available in Todo Archive -mode, and they work the same as in Todo mode, which means they can only -be used to return to Todo mode: @kbd{t} prompt for and switch to a todo -file, and with @kbd{j} you can only jump to a todo category. These -commands exclude archives because an archive file has the same base name -as the corresponding todo file, and category name completion uses only -the base names, so the commands cannot know which type of file you want -to visit. For this reason, there is a special command in Todo Archive -mode for jumping to another archive category or visiting another archive -file: - -@table @kbd - -@item a -This command (@code{todo-jump-to-archive-category}) prompts for a category in the -current archive and jumps to it. Called with a prefix argument, it -prompts for another archive, then for a category in it and jumps to -that category. -@end table - -None of the Todo mode editing commands are available in Todo Archive -mode, since archives are meant to be static records of accomplished todo -items. Should you, however, archive an item by mistake or simply change -your mind about the archival status of an item, you can ``unarchive'' it: - -@table @kbd - -@item u -Restore the done item at point to the top of the done items section of -the corresponding category in the corresponding todo file, i.e., an -unarchived item remains a done item (@code{todo-unarchive-items}). When -the last item in an archive category has been unarchived, the category -is automatically deleted from the archive. If this was the only -category in the archive, the archive file is also automatically deleted. -@end table - -Since it is natural to visit an archive from the corresponding todo -file, it would be convenient to easily return to the todo file when you -have finished browsing the archive. If you type @kbd{q} to quit Todo -Archive mode, this switches to the corresponding todo file and shows the -todo category corresponding to the archive category you were just -visiting. - -The command @kbd{F k} (@pxref{File Editing}) is also available in Todo -Archive mode. It deletes the current archive file and prompts you -whether to delete the corresponding todo file. - -@node Marked Items, Todo Categories Mode, Todo Archives, Top -@chapter Marked Items - -For many item editing commands it can make sense and be convenient to -apply them simultaneously to more than one item in the current category. -Todo facilitates this by means of marked items. - -@table @kbd - -@item * -Mark the item at point if it is unmarked, and remove the mark it is -already marked (@code{todo-toggle-mark-item}). The mark is a string -specified by the option @code{todo-item-mark} (by default @samp{*}) -appended in front of the item header (more precisely, in front of the -item's priority number or prefix; see @ref{Todo Display Features}, for -details of the latter). After marking the current item, the command -advances point to the next item. It also accepts a numeric prefix -argument, which allows toggling the mark of multiple consecutive items. - -@item C * -Mark all todo items in the current category. - -@item C u -Unmark all todo item in the current category. -@end table - -You can also use the last two commands to mark or unmark all done items in -the category, but only when only the done items section is being -displayed, i.e., after invoking @kbd{C V} or @kbd{V}. - -The following commands operate on marked items: - -@itemize @bullet - -@item -@kbd{k} (deleting) -@item -@kbd{m} (moving to another category) -@item -@kbd{d} (moving to the done items section; note that @kbd{C-u d} adds -the same comment to all marked items) -@item -@kbd{A d} (archiving) -@item -@kbd{u} (both in Todo mode for undoing a done item and in Todo Archive -mode for unarchiving an item) -@item -the commands for editing the item header (those beginning with the -prefix @kbd{e d} as well as @kbd{e t}, @kbd{e y} and @kbd{e k}) -@end itemize - -@noindent -The item insertion, textual editing and priority changing commands do -not operate on marked items. - -If you use @kbd{m}, @kbd{d}, @kbd{A d} or @kbd{u} on multiple -noncontiguous marked items, the relocated items retain their relative -order but are now listed consecutively en bloc. - -You can mark both todo and done items, but note that only @kbd{m} and -@kbd{k} can apply to both; other commands only affect either marked -todo or marked done items, so if both types of items are marked, -invoking these commands has no effect and informs you of your -erroneous attempt. - -@node Todo Categories Mode, Searching for Items, Marked Items, Top -@chapter Todo Categories Mode - -It can be helpful to have a compact overview of the categories in a -todo file and the types of items it contains; the Todo package -provides a tabular view of this information. - -@table @kbd - -@item F c -Typing this command (@code{todo-show-categories-table}) in Todo mode or Todo -Archive mode switches to a buffer displaying a table that gives an -overview of the categories in the current todo or archive file. This -buffer is in Todo Categories mode. -@end table - -The table consists of a column containing the names of the categories in -the file, followed by columns containing counts of certain types of -items in each category. With todo files there are four count types: all -todo (i.e., not done) items, diary items (i.e., those todo items lacking -the @code{todo-nondiary-marker}, which hence can appear in the Fancy Diary -display), done (but not archived) items, and archived items. With -archive files all items are done, so the table only has a column for -this count. The final row of the table gives total item counts across -all categories in the file. - -Aside from explicitly invoking @kbd{F c} to display the table of -categories, you can also arrange to have it displayed on the first -invocation of @code{todo-show} for a given file (i.e., either using -@code{todo-show} to initiate a Todo session, or calling it in Todo mode -to visit another todo file). To do this customize the option -@code{todo-show-first}. - -@menu -* Table of Item Counts:: -* Reordering Categories:: -@end menu - -@node Table of Item Counts, Reordering Categories, , Todo Categories Mode -@section Table of Item Counts - -Above each column of the table is a labeled button you can press by -clicking with the mouse or by typing @key{RET} on it. Pressing an item -count button sorts the table alternately in ascending or descending -order according to the type of count. Pressing the category button -alternates between the initial numerical order of the categories and -alphabetical order. In numerical order the column of category names is -preceded by a column containing the corresponding category numbers; this -column is not displayed in the alphabetical listing. Instead of -pressing the buttons, you can also sort the table by typing the -following keys: - -@itemize - -@item @kbd{c} -to sort by category numerically or alphabetically; -@item @kbd{t} -to sort by todo item counts; -@item @kbd{y} -to sort by diary item counts; -@item @kbd{d} -to sort by done item counts; -@item @kbd{a} -to sort by archived item counts. -@end itemize - -Each row of the table is also buttonized; pressing one of these exits -the buffer (killing it), returns to the buffer of the file from which -you had invoked @kbd{F c}, and displays the category that was named in -the row button you pressed (i.e., pressing this button jumps to that -category). However, if the category named in the row is in a todo -file and all of its items have been archived, and you have enabled the -option @code{todo-skip-archived-categories}, then pressing the button -jumps to the archive category instead of the empty todo category. You -can recognize such categories by their items counts in the table---all -columns but the archived one have counts of zero---and in addition, -their lines in the table are also distinguished from the others by a -different face (@pxref{Faces}). - -You can navigate around the table: - -@table @kbd - -@item n -@itemx @key{TAB} -Advance point to the next button. - -@item p -@itemx S-@key{TAB} -Put point on the previous button. -@end table - -These commands are cyclic, e.g. when point is on the last button, -pressing @kbd{n} moves it to the first button. - -Typing @kbd{q} exits Todo Categories mode, killing the buffer and returning -to the current category in the Todo mode or Todo Archive mode buffer -from which you had invoked @kbd{F c}. - -@node Reordering Categories, , Table of Item Counts, Todo Categories Mode -@section Reordering Categories - -Todo Categories mode provide commands with which you can change the -numbering of the categories in the current file. This renumbering has -the effect of reordering the categories for sequential navigation by -@kbd{f} and @kbd{b} in Todo mode and Todo Archive mode. These commands -are only operative when the table displays the categories in their -numerical order. They work just like reprioritizing items in Todo mode, -hence have the same key bindings: - -@table @kbd - -@item r -Raise the current line of the table (the one the cursor is on), -decreasing the category's number by one (@code{todo-raise-category}). -This command exchanges lines, and hence the numbers, of the category at -point and the one above it before invoking the command. - -@item l -Lower the current line of the table, increasing the category's number by -one (@code{todo-lower-category}). This command exchanges lines, and -hence the numbers, of the category at point and the one below it before -invoking the command. - -@item # -Prompt for a number between 1 and the number of categories in the file -and reorder the table accordingly (@code{todo-set-category-number}). If -called with a numeric prefix argument within the allowed range, reorder -the table without prompting. -@end table - -The reordering done by these commands remains in effect when you return -to Todo mode or Todo Archive mode and, as long as you save the todo -or archive file after reordering, in subsequent sessions as well. - -@quotation @strong{Caution} -It is important to be aware that renumbering the categories does not -change the textual order of the categories in the file. This is -significant if you should invoke @kbd{F e} to edit the entire file -manually and in so doing alter the number of categories or the number -of items in a category: this will make the information shown in the -table of categories of this file inconsistent with its actual state. -You can repair this inconsistency by invoking the command -@code{todo-repair-categories-sexp} (which lacks a key binding, since -it is meant to be a rarely needed rescue operation). But this will -revert any renumbering of the categories you have made, so you will -have to renumber them again. This is one reason why you should -exercise caution when using @kbd{F e}. -@end quotation - -@node Searching for Items, Todo Filtered Items Mode, Todo Categories Mode, Top -@chapter Searching for Items - -It can be useful to be able to locate and examine all todo items that -fit certain criteria, regardless of which category they belong to. One -way to do this in Todo mode is by sequentially searching in the file: - -@table @kbd - -@item S -This command (@code{todo-search}; the key is capital @kbd{S}) prompts for a -regular expression, searches from the beginning of the current todo file -and displays the category containing the first match it finds, with the -match highlighted. If there are further matches, a message saying how -many are left is displayed and you are asked if you want to go to the -next match. When you reach the last match, or if you decide not to go -to further matches, you are asked whether the match highlighting should -be removed. - -@item X -This command (@code{todo-clear-matches}) removes any highlighting added by @kbd{S}. -This is so you can leave the matches highlighted at the end of the -search and remove the highlighting later. -@end table - -These commands are also available in Todo Archive mode. - -@node Todo Filtered Items Mode, Todo Display Features, Searching for Items, Top -@chapter Todo Filtered Items Mode - -A more powerful alternative to sequential searching is item filtering, -by which items from different categories that match specified criteria -are gathered and displayed in a new buffer as a kind of virtual -category in a distinct mode, Todo Filtered Items mode. - -@menu -* Filtering Items:: -* Todo Filtered Items Mode Commands:: -* Files of Filtered Items:: -@end menu - -@node Filtering Items, Todo Filtered Items Mode Commands, , Todo Filtered Items Mode -@section Filtering Items - -Todo mode provides three ways to filter items: a general filter for -items matching a user-entered regular expression, as with the search -command; and two specific filters, one for diary-displayable items -(i.e., those lacking @code{todo-nondiary-marker}) and one for top -priority items (more on the latter below). The commands for each -filter come in pairs, one for filtering just the current todo file and -one for filtering a user-specified list of todo files. Thus, there -are six item filtering commands:@footnote{The use of @kbd{F} in the key -sequences of these commands naturally recalls ``filter'', but is also -consistent with the Todo mode mnemonic key binding convention, since the -commands involve one or more whole files.} - -@itemize @bullet - -@item -@kbd{F x x} (@code{todo-filter-regexp-items}) -@item -@kbd{F x m} (@code{todo-filter-regexp-items-multifile}) -@item -@kbd{F y y} (@code{todo-filter-diary-items}) -@item -@kbd{F y m} (@code{todo-filter-diary-items-multifile}) -@item -@kbd{F t t} (@code{todo-filter-top-priorities}) -@item -@kbd{F t m} (@code{todo-filter-top-priorities-multifile}) -@end itemize - -There are two ways to specify which files the multifile filtering -commands apply to. If there are files you want to filter every time you -use these commands, customize the option @code{todo-filter-files}. If you -leave this option empty (the default), invoking a multifile filtering -command pops up a buffer similar to the Customization buffer for -@code{todo-filter-files}, in which you can select files to filter just for -this invocation. - -Diary and top priority items are by definition non-done todo items, but -when filtering by regular expression, you can extend the scope of the -command to done items by enabling the option @code{todo-filter-done-items}. -Then @kbd{F x x} and @kbd{F x m} will gather both matching todo and matching -done items (including done items from any archive files corresponding to -the selected todo files) into the virtual category of filtered items. - -There are several ways to specify how many items in each category count -as top priorities and hence get filtered by @kbd{F t t} and @kbd{F t m}: - -@itemize @bullet - -@item -The option @code{todo-top-priorities} specifies a single default number -for all categories and all todo files; its default value is 1, which -means just the highest priority item in every category is filtered, -unless otherwise specified. -@item -The option @code{todo-top-priorities-overrides} lists file-wide overrides -of @code{todo-top-priorities} as well as category-specific overrides. It -is empty by default. However, using the Custom facility to set this -option would be tedious and error-prone, so instead you should use the -commands @kbd{F t s} and @kbd{C t s}. The former sets (i.e., overrides) the -default number of top priorities for all categories in the current -todo file, and the latter sets the number of top priorities for the -current category. To exclude a category or file from filtering by @kbd{F t t} -and @kbd{F t m}, set the number to @samp{0}. -@item -You can invoke @kbd{F t t} and @kbd{F t m} with a numeric prefix argument, -which specifies the number of top priorities in each category just for -this invocation, overriding both @code{todo-top-priorities-overrides} and -@code{todo-top-priorities}. -@end itemize - -@node Todo Filtered Items Mode Commands, Files of Filtered Items, Filtering Items, Todo Filtered Items Mode -@section Todo Filtered Items Mode Commands - -The output of the item filtering commands looks similar to a regular -Todo category, but it is not contained in any todo file and does not -have a name on being created, so it is not a ``real'' category but a -``virtual'' category. Another difference is the lack of a done items -section; either there are no done items in the list (when the filtered -items are diary or top priority items), or these are displayed in the -same list as todo items (if you filtered by regular expression and -allowed done items). A further difference is that the items have an -additional header, between the item's date/time header and its text, -specifying which category (and if you invoked a multifile command, also -which file) the item comes from, and if you filtered by regular -expression, also whether the item comes from a Todo archive. - -The sequential item navigation commands @kbd{n} and @kbd{p} work the same in -Todo Filtered Items mode as in Todo mode, as do the file and category -jumping commands @kbd{t} and @kbd{j}; however, the sequential category -navigation commands are unavailable, since virtual categories of -filtered items are not ordered with respect to ``real'' categories. In -addition, Todo Filtered Items mode provides a special navigation -command: - -@table @kbd - -@item g -@itemx @key{RET} -If you type this command (@code{todo-go-to-source-item}) with point on a -filtered item, the buffer switches to the item's source file (in Todo -mode or Todo Archive mode, as the case may be) and displays its -category, with point on the item. -@end table - -Filtered items cannot be textually edited, moved to another category, -marked done or archived like items in a real todo category, since these -would then be out of synch with each other. But there is one type of -editing command that does work in Todo Filtered Items mode: changing an -item's priority: - -@table @kbd - -@item r -@itemx l -@itemx # -These commands raise, lower, or set, respectively, the current item's -priority in the virtual category. -@end table - -@noindent -Using these commands, you can create a cross-category (and even -cross-file) prioritized list of filtered items. However, there is a -restriction on these commands in Todo Filtered Items mode: you cannot -change the relative priorities of items from the same real category, -since that would make the filtered list inconsistent with the source -todo list. - -@node Files of Filtered Items, , Todo Filtered Items Mode Commands, Todo Filtered Items Mode -@section Files of Filtered Items - -Typing @kbd{s} in Todo Filtered Items mode saves the buffer of filtered -items to a file in @code{todo-directory}. Files of items filtered by -regular expression have the extension @samp{.todr}, those with filtered -diary items have the extension @samp{.tody} and those with filtered top -priorities have the extension @samp{.todt}. The extensions are added -automatically the first time you save the buffer to a file. - -With filtered top priority or diary items, the file is automatically -named on first saving it, using as the base name either the same base -name as the single todo file it was generated from, or combining the -base names of the todo files used in multifile filtering commands. -With items filtered by regular expression, it can be useful to save -separate lists generated from the same file(s) using different regular -expressions, so when saving such a list, you are prompted for a short -identifying string to add to the file name. - -When you invoke one of the item filtering commands without a prefix -argument and a corresponding file already exists, the command visits -this file (if, for the current file or chosen files, there are multiple -files of items filtered by regular expression, you are prompted to -choose one). To force generation of a new filtered list, invoke the -command with a prefix argument (in the case of top priority items, -either numeric as described above, or the raw prefix argument @kbd{C-u} to -use the values of @code{todo-top-priorities-overrides} or -@code{todo-top-priorities}). - -Aside from explicitly invoking an item filtering command to display a -saved list of items filtered by a given method from given todo files, -there are two other ways to visit a saved file of filtered items. You -can invoke a command similar to @code{find-file}: - -@table @kbd -@item F f -Visit a saved file of filtered items, which you choose via minibuffer -completion (@code{todo-find-filtered-items-file}). -@end table - -@noindent -Alternatively, as with tables of categories, by customizing -@code{todo-show-first} you can have the first invocation of -@code{todo-show} for a given todo file display the corresponding saved -file of filtered items. If there is no saved filtered items list for -the file, @code{todo-show} simply defaults to visiting the file and -displaying its first category, as usual. - -The command @kbd{F k} (@pxref{File Editing}) is also available in Todo -Filtered Items mode. It deletes the current filtered items file. - -@node Todo Display Features, Printing Todo Buffers, Todo Filtered Items Mode, Top -@chapter Todo Display Features - -You can change the appearance of Todo mode buffers in a variety of ways. - -@menu -* Faces:: -* Item Prefix:: -* Other Display Commands and Options:: -@end menu - -@node Faces, Item Prefix, , Todo Display Features -@section Faces - -Each of the Todo modes uses faces to distinguish various aspects of -the display, both structural and informational. For example, the -faces for the date and time strings of todo item headers -(@code{todo-date} and @code{todo-time}, respectively) by default -inherit the attributes of the corresponding faces used by the Emacs -diary; but when the date and time of a Todo diary item (i.e., an item -lacking @code{todo-nondiary-marker}) is earlier than the current date -and time, they are displayed in a different face -(@code{todo-diary-expired}). In this way, you can readily recognize -diary items that have ``expired'' and act accordingly (e.g., by -tagging them as done or by updating the deadlines). - -Another example of an informational face is the face used to -distinguish top priority items (@code{todo-top-priority}). A third -case is the face used in Todo Categories mode to mark rows of the -table containing categories with only archived items -(@code{todo-archived-only}). - -The @code{todo-faces} customization group contains a complete list of -Todo mode faces and brief descriptions of their use. - - -@node Item Prefix, Other Display Commands and Options, Faces, Todo Display Features -@section Item Prefix - -In the default display of (real or virtual) categories in Todo mode, -Todo Archive mode and Todo Filtered Item mode the items are visually -numbered in ascending order, starting with @samp{1} on the top item, -displayed to the left of its header (date/time string). With todo items -the numbers indicate each item's priority in the list, so when you -reprioritize an item with @kbd{#} or move it with @kbd{m}, these numbers make -it easier to choose the item's new priority. The numbering also lets -you to see at a glance how many items there are in the list. When an -item is inserted, deleted, or moved, the numbering is automatically -updated. In Todo mode, the todo and done items sections in each -category are separately numbered. - -If you prefer not to have item numbering displayed, disable the option -@code{todo-number-prefix}; then the display of each item starts by default -simply with its header. But you can also replace the numbering with a -visually distinctive string of your choice by customizing the option -@code{todo-prefix} (the empty string by default). Another alternative is to -temporarily hide the item numbering: - -@table @kbd - -@item F N -@itemx N -Toggle between displaying item numbering and displaying the -@code{todo-prefix} string in the current Todo file (todo, archive, or -saved virtual category of filtered items). (This command also works in -buffers of filtered items that have not yet been written to a file.) -@end table - -In the todo items section of each Todo mode category, the item prefix -(whether a priority number or a fixed string) of the top priority -items (determined as specified in @pxref{Filtering Items}) is -displayed in a face (@code{todo-top-priority}) different from the face -of the prefix of non-top-priority items, so you see at a glance how -many items in the category are top priorities. - -@node Other Display Commands and Options, , Item Prefix, Todo Display Features -@section Other Display Commands and Options - -There are two additional toggle commands that affect display in the -current file: - -@table @kbd - -@item F h -@itemx h -Hide the item headers if visible, or show them if they are hidden. -With done items, only the done header (i.e. the done tag and date-time -string inserted when the item was marked done) is hidden, the original -date-time string is not. With filtered items, the category (or -category-file) tag is not hidden. - -@item F H -@itemx H -Highlight the current item (with the face @code{hl-line}) if -unhighlighted, or remove its highlighting. When item highlighting is -enabled, it follows navigation by @kbd{n} or @kbd{p}. If you want to -have current item highlighting by default, enable the option -@code{todo-highlight-item}. @kbd{F H} or @kbd{H} will still toggle -it. -@end table - -There are two options which affect the display of items whose content is -longer than one screen line: - -@itemize @bullet{} - -@item -@code{todo-indent-to-here} sets the amount of indentation for all lines -after the first in multiline todo items, which is necessary in order -for todo diary items to be fully visible in the Fancy Diary display. -The default indentation is 3 spaces. For a uniform appearance this -option applies to all items, i.e., diary and nondiary todo items and -also done items. - -@item -@code{todo-wrap-lines} allows you to choose, for the purposes of -insertion and editing, between treating multiline todo items as -containing multiple logical lines with hard line breaks or as multiple -visual lines using Visual Line mode; the latter is the default. Since -multiparagraph items also contain hard line breaks in Visual Line mode, -for a uniform appearance this display shows indentation on wrapped lines -by using a wrap-prefix of @code{todo-indent-to-here} spaces. -@end itemize - -The indentation inserted after a hard newline is actually a tab -character, and the Todo modes that display items bind @code{tab-width} to -@code{todo-indent-to-here}, so if you change the default value of the -latter, the next time you visit a Todo file, the indentation will -reflect your change. - -By default, the todo and done items sections of a todo category are -visually separated by a line as wide as the window the buffer is -displayed in. You can change the appearance and width of the separator -by customizing @code{todo-done-separator-string}; you can also change the -face of the separator string (@code{todo-done-sep}). - -There are also several options for changing the appearance in Todo -Categories mode and Todo Filtered Items mode, beyond those mentioned -above in the sections on these modes; see the customization groups -@code{todo-categories} and @code{todo-filtered} for details. - -@node Printing Todo Buffers, Legacy Todo Mode Files, Todo Display Features, Top -@chapter Printing Todo Buffers - -If you print a Todo buffer using one of the standard Emacs printing -commands, it does not look exactly like what you see in the buffer. -This is because some of the display features are non-printable -(specifically, those using overlays, word-wrap and wrap-prefix). Todo -mode provides two print commands that produce output which includes -printable counterparts of such display features: - -@table @kbd - -@item P B -Send the printable buffer output directly to your printer. - -@item P F -Prompt for a file name and write the printable output to that file. -@end table - -By default, Todo uses @code{ps-print-buffer-with-faces} to make the -printable version; you can change this by setting the option -@code{todo-print-function}. - -@node Legacy Todo Mode Files, GNU Free Documentation License, Printing Todo Buffers, Top -@chapter Legacy Todo Mode Files - -Users of the original version of Todo mode will recognize from the -description in this user manual that, although the new version shares -with the original version the same basic user interface and handling of -todo items, there are some incompatible differences between them, such -as the done items sections (there are also other file format -incompatibilities behind the scenes that are normally not visible to -users). - -The most significant incompatibility concerns the item prefix. In the -earlier version of Todo mode the prefix was the initial part of the item -string itself, so in order for the item to be displayable in the Emacs -diary, the prefix had to be a date/time pattern recognizable by the -diary (although the todo item also has its own date/time header). -Moreover, since all items had the same prefix string in the original -version, this means that either only all or no items could appear in the -Fancy Diary display on any given date. This considerably restricts the -practicality of including todo items in the diary. In contrast, the -current version of Todo mode uses overlays for item priority numbering -or prefixes, and item-specific diary-compatible date/time headers and -special marks for todo items to be excluded from the diary, so you can -determine for each item whether and when it appears in the Fancy Diary -display. - -Due to these incompatibilities, files created with the original version -of Todo mode cannot be displayed or edited with the current version. -However, this version provides a function that converts the two main -types of files used by the original version into new-style valid todo -and archive files, respectively, and saves them in -@code{todo-directory}.@footnote{The original version of Todo mode also -allowed saving a file of top priority items, but since you can readily -create such a file with the new version, which is also more flexible, -no conversion is provided for this file.} - -This conversion function is automatically called the first time you -invoke @code{todo-show} (i.e., before you have created a todo file with -the new version), and if it finds the old-style files, it offers to -convert them, making them the first new-style todo and archive files. -If you choose not to convert the old-style files at this time, you can -do so later by invoking the command @code{todo-convert-legacy-files} -(there is no key binding for it, since it shouldn't be necessary to use -it often). (A delicate part of the conversion concerns the customizable -format of item date/time headers in the old-style; see the documentation -string of @code{todo-legacy-date-time-regexp} for details.) - -@node GNU Free Documentation License, , Legacy Todo Mode Files, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye - -@c End: diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi deleted file mode 100644 index 1f6eaef6880..00000000000 --- a/doc/misc/tramp.texi +++ /dev/null @@ -1,3978 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/tramp -@c %**start of header -@settitle TRAMP User Manual -@documentencoding UTF-8 -@c %**end of header - -@c This is *so* much nicer :) -@footnotestyle end - -@c In the Tramp repository, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. - -@c Additionally, flags are set with respect to the Emacs flavor; and -@c depending whether Tramp is packaged into (X)Emacs, or standalone. - -@include trampver.texi - -@c Macro for formatting a file name according to the respective syntax. -@c xxx and yyy are auxiliary macros in order to omit leading and -@c trailing whitespace. Not very elegant, but I don't know it better. - -@c There are subtle differences between texinfo 4.13 and 5.0. We must -@c declare two versions of the macro. This will be improved, hopefully. - -@c Texinfo 5.0. -@ifset txicommandconditionals -@macro xxx {one} -@set \one\ -@end macro - -@macro yyy {one, two} -@xxx{x\one\}@c -@ifclear x -\one\@w{}\two\@c -@end ifclear -@clear x\one\ -@end macro - -@macro trampfn {method, user, host, localname} -@value{prefix}@c -@yyy{\method\,@value{postfixhop}}@c -@yyy{\user\,@@}@c -\host\@value{postfix}\localname\ -@end macro -@end ifset - -@c Texinfo 4.13. -@ifclear txicommandconditionals -@macro xxx {one}@c -@set \one\@c -@end macro - -@macro yyy {one, two}@c -@xxx{x\one\}@c -@ifclear x@c -\one\@w{}\two\@c -@end ifclear -@clear x\one\@c -@end macro - -@macro trampfn {method, user, host, localname}@c -@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c -@end macro -@end ifclear - -@copying -Copyright @copyright{} 1999--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual.'' -@end quotation -@end copying - -@c Entries for @command{install-info} to use -@dircategory @value{emacsname} network features -@direntry -* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol - @value{emacsname} remote file access via ssh and scp. -@end direntry - -@titlepage -@title @value{tramp} version @value{trampver} User Manual -@author by Daniel Pittman -@author based on documentation by Kai Gro@ss{}johann -@page -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview, (dir), (dir) -@top @value{tramp} version @value{trampver} User Manual - -This file documents @value{tramp} version @value{trampver}, a remote file -editing package for @value{emacsname}. - -@value{tramp} stands for `Transparent Remote (file) Access, Multiple -Protocol'. This package provides remote file editing, similar to -@value{ftppackagename}. - -The difference is that @value{ftppackagename} uses FTP to transfer -files between the local and the remote host, whereas @value{tramp} uses a -combination of @command{rsh} and @command{rcp} or other work-alike -programs, such as @command{ssh}/@command{scp}. - -You can find the latest version of this document on the web at -@uref{http://www.gnu.org/software/tramp/}. - -@c Pointer to the other Emacs flavor is necessary only in case of -@c standalone installation. -@ifset installchapter -The manual has been generated for @value{emacsname}. -@ifinfo -If you want to read the info pages for @value{emacsothername}, you -should read in @ref{Installation} how to create them. -@end ifinfo -@ifhtml -If you're using the other Emacs flavor, you should read the -@uref{@value{emacsotherfilename}, @value{emacsothername}} pages. -@end ifhtml -@end ifset - -@ifhtml -The latest release of @value{tramp} is available for -@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see -@ref{Obtaining Tramp} for more details, including the Git server -details. - -@value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/, -Savannah Project Page}. -@end ifhtml - -There is a mailing list for @value{tramp}, available at -@email{tramp-devel@@gnu.org}, and archived at -@uref{http://lists.gnu.org/archive/html/tramp-devel/, the -@value{tramp} Mail Archive}. -@ifhtml -Older archives are located at -@uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel, -SourceForge Mail Archive} and -@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/, -The Mail Archive}. -@c in HTML output, there's no new paragraph. -@*@* -@end ifhtml - -@insertcopying - -@end ifnottex - -@menu -* Overview:: What @value{tramp} can and cannot do. - -For the end user: - -* Obtaining Tramp:: How to obtain @value{tramp}. -* History:: History of @value{tramp}. -@ifset installchapter -* Installation:: Installing @value{tramp} with your @value{emacsname}. -@end ifset -* Configuration:: Configuring @value{tramp} for use. -* Usage:: An overview of the operation of @value{tramp}. -* Bug Reports:: Reporting Bugs and Problems. -* Frequently Asked Questions:: Questions and answers from the mailing list. - -For the developer: - -* Files directories and localnames:: How file names, directories and localnames are mangled and managed. -* Traces and Profiles:: How to Customize Traces. -* Issues:: Debatable Issues and What Was Decided. - -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: @value{tramp} functions. -* Variable Index:: User options and variables. -* Concept Index:: An item for each concept. - -@detailmenu - --- The Detailed Node Listing --- -@c -@ifset installchapter -Installing @value{tramp} with your @value{emacsname} - -* Installation parameters:: Parameters in order to control installation. -* Load paths:: How to plug-in @value{tramp} into your environment. - -@end ifset - -Configuring @value{tramp} for use - -* Connection types:: Types of connections made to remote hosts. -* Inline methods:: Inline methods. -* External methods:: External methods. -@ifset emacsgvfs -* GVFS based methods:: GVFS based external methods. -@end ifset -@ifset emacsgw -* Gateway methods:: Gateway methods. -@end ifset -* Default Method:: Selecting a default method. -* Default User:: Selecting a default user. -* Default Host:: Selecting a default host. -* Multi-hops:: Connecting to a remote host using multiple hops. -* Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. -* Password handling:: Reusing passwords for several connections. -* Connection caching:: Reusing connection related information. -* Predefined connection information:: - Setting own connection related information. -* Remote Programs:: How @value{tramp} finds and uses programs on the remote host. -* Remote shell setup:: Remote shell setup hints. -* Android shell setup:: Android shell setup hints. -* Auto-save and Backup:: Auto-save and Backup. -* Windows setup hints:: Issues with Cygwin ssh. - -Using @value{tramp} - -* File name Syntax:: @value{tramp} file name conventions. -* File name completion:: File name completion. -* Ad-hoc multi-hops:: Declaring multiple hops in the file name. -* Remote processes:: Integration with other @value{emacsname} packages. -* Cleanup remote connections:: Cleanup remote connections. - -How file names, directories and localnames are mangled and managed - -* Localname deconstruction:: Breaking a localname into its components. -@ifset emacs -* External packages:: Integration with external Lisp packages. -@end ifset - -@end detailmenu -@end menu - - -@node Overview -@chapter An overview of @value{tramp} -@cindex overview - -After the installation of @value{tramp} into your @value{emacsname}, you -will be able to access files on remote hosts as though they were -local. Access to the remote file system for editing files, version -control, and @code{dired} are transparently enabled. - -Your access to the remote host can be with the @command{rsh}, -@command{rlogin}, @command{telnet} programs or with any similar -connection method. This connection must pass @acronym{ASCII} -successfully to be usable but need not be 8-bit clean. - -The package provides support for @command{ssh} connections out of the -box, one of the more common uses of the package. This allows -relatively secure access to hosts, especially if @command{ftp} -access is disabled. - -Under Windows, @value{tramp} is integrated with the PuTTY package, -using the @command{plink} program. - -The majority of activity carried out by @value{tramp} requires only that -the remote login is possible and is carried out at the terminal. In -order to access remote files @value{tramp} needs to transfer their content -to the local host temporarily. - -@value{tramp} can transfer files between the hosts in a variety of ways. -The details are easy to select, depending on your needs and the -hosts in question. - -The fastest transfer methods for large files rely on a remote file -transfer package such as @command{rcp}, @command{scp}, @command{rsync} -or (under Windows) @command{pscp}. - -If the remote copy methods are not suitable for you, @value{tramp} also -supports the use of encoded transfers directly through the shell. -This requires that the @command{mimencode} or @command{uuencode} tools -are available on the remote host. These methods are generally -faster for small files. - -@value{tramp} is still under active development and any problems you encounter, -trivial or major, should be reported to the @value{tramp} developers. -@xref{Bug Reports}. - - -@subsubheading Behind the scenes -@cindex behind the scenes -@cindex details of operation -@cindex how it works - -This section tries to explain what goes on behind the scenes when you -access a remote file through @value{tramp}. - -Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name, -then hit @kbd{@key{TAB}} for completion. Suppose further that this is -the first time that @value{tramp} is invoked for the host in question. Here's -what happens: - -@itemize -@item -@value{tramp} discovers that it needs a connection to the host. So it -invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l -@var{user}} or a similar tool to connect to the remote host. -Communication with this process happens through an -@value{emacsname} buffer, that is, the output from the remote end -goes into a buffer. - -@item -The remote host may prompt for a login name (for @command{telnet}). -The login name is given in the file name, so @value{tramp} sends the -login name and a newline. - -@item -The remote host may prompt for a password or pass phrase (for -@command{rsh} or for @command{telnet} after sending the login name). -@value{tramp} displays the prompt in the minibuffer, asking you for the -password or pass phrase. - -You enter the password or pass phrase. @value{tramp} sends it to the remote -host, followed by a newline. - -@item -@value{tramp} now waits for the shell prompt or for a message that the login -failed. - -If @value{tramp} sees neither of them after a certain period of time -(a minute, say), then it issues an error message saying that it -couldn't find the remote shell prompt and shows you what the remote -host has sent. - -If @value{tramp} sees a @samp{login failed} message, it tells you so, -aborts the login attempt and allows you to try again. - -@item -Suppose that the login was successful and @value{tramp} sees the shell prompt -from the remote host. Now @value{tramp} invokes @command{/bin/sh} because -Bourne shells and C shells have different command -syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login -shell doesn't recognize @samp{exec /bin/sh} as a valid command. -Maybe you use the Scheme shell @command{scsh}@dots{}} - -After the Bourne shell has come up, @value{tramp} sends a few commands to -ensure a good working environment. It turns off echoing, it sets the -shell prompt, and a few other things. - -@item -Now the remote shell is up and it good working order. Remember, what -was supposed to happen is that @value{tramp} tries to find out what files exist -on the remote host so that it can do file name completion. - -So, @value{tramp} basically issues @command{cd} and @command{ls} commands and -also sometimes @command{echo} with globbing. Another command that is -often used is @command{test} to find out whether a file is writable or a -directory or the like. The output of each command is parsed for the -necessary operation. - -@item -Suppose you are finished with file name completion, have entered @kbd{C-x -C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to -transfer the file contents from the remote host to the local host so -that you can edit them. - -See above for an explanation of how @value{tramp} transfers the file contents. - -For inline transfers, @value{tramp} issues a command like @samp{mimencode -b -/path/to/remote/file}, waits until the output has accumulated in the -buffer that's used for communication, then decodes that output to -produce the file contents. - -For external transfers, @value{tramp} issues a command like the -following: -@example -rcp user@@host:/path/to/remote/file /tmp/tramp.4711 -@end example -It then reads the local temporary file @file{/tmp/tramp.4711} into a -buffer and deletes the temporary file. - -@item -You now edit the buffer contents, blithely unaware of what has happened -behind the scenes. (Unless you have read this section, that is.) When -you are finished, you type @kbd{C-x C-s} to save the buffer. - -@item -Again, @value{tramp} transfers the file contents to the remote host -either inline or external. This is the reverse of what happens when -reading the file. -@end itemize - -I hope this has provided you with a basic overview of what happens -behind the scenes when you open a file with @value{tramp}. - - -@c For the end user -@node Obtaining Tramp -@chapter Obtaining Tramp. -@cindex obtaining Tramp - -@value{tramp} is freely available on the Internet and the latest -release may be downloaded from @uref{ftp://ftp.gnu.org/gnu/tramp/}. -This release includes the full documentation and code for -@value{tramp}, suitable for installation. But Emacs (22 or later) -includes @value{tramp} already, and there is a @value{tramp} package -for XEmacs, as well. So maybe it is easier to just use those. But if -you want the bleeding edge, read on@dots{} - -For the especially brave, @value{tramp} is available from Git. The Git -version is the latest version of the code and may contain incomplete -features or new issues. Use these versions at your own risk. - -Instructions for obtaining the latest development version of @value{tramp} -from Git can be found by going to the Savannah project page at the -following URL and then clicking on the Git link in the navigation bar -at the top. - -@noindent -@uref{http://savannah.gnu.org/projects/tramp/} - -@noindent -Or follow the example session below: - -@example -] @strong{cd ~/@value{emacsdir}} -] @strong{git clone git://git.savannah.gnu.org/tramp.git} -@end example - -@noindent -Tramp developers use instead - -@example -] @strong{git clone login@@git.sv.gnu.org:/srv/git/tramp.git} -@end example - -@noindent -You should now have a directory @file{~/@value{emacsdir}/tramp} -containing the latest version of @value{tramp}. You can fetch the latest -updates from the repository by issuing the command: - -@example -] @strong{cd ~/@value{emacsdir}/tramp} -] @strong{git pull} -@end example - -@noindent -Once you've got updated files from the Git repository, you need to run -@command{autoconf} in order to get an up-to-date @file{configure} -script: - -@example -] @strong{cd ~/@value{emacsdir}/tramp} -] @strong{autoconf} -@end example - - -@node History -@chapter History of @value{tramp} -@cindex history -@cindex development history - -Development was started end of November 1998. The package was called -@file{rssh.el}, back then. It only provided one method to access a -file, using @command{ssh} to log in to a remote host and using -@command{scp} to transfer the file contents. After a while, the name -was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way, -many more methods for getting a remote shell and for transferring the -file contents were added. Support for VC was added. - -After that, there were added the multi-hop methods in April 2000 and -the unification of @value{tramp} and Ange-FTP file names in July 2002. -In July 2004, multi-hop methods have been replaced by proxy hosts. -Running commands on remote hosts was introduced in December 2005. -@ifset emacsgw -Support of gateways exists since April 2007. -@end ifset -@ifset emacsgvfs -GVFS integration started in February 2009. -@end ifset -@ifset emacs -Remote commands on Windows hosts are available since September 2011. -@end ifset -Ad-hoc multi-hop methods (with a changed syntax) have been reenabled -in November 2011. In November 2012, Juergen Hoetzel's -@file{tramp-adb.el} has been added. - -In December 2001, @value{tramp} has been added to the XEmacs package -repository. Being part of the Emacs repository happened in June 2002, -the first release including @value{tramp} was Emacs 22.1. - -@value{tramp} is also a Debian GNU/Linux package since February 2001. - - -@c Installation chapter is necessary only in case of standalone -@c installation. Text taken from trampinst.texi. -@ifset installchapter -@include trampinst.texi -@end ifset - - -@node Configuration -@chapter Configuring @value{tramp} for use -@cindex configuration - -@cindex default configuration -@value{tramp} is (normally) fully functional when it is initially -installed. It is initially configured to use the @command{scp} -program to connect to the remote host. So in the easiest case, you -just type @kbd{C-x C-f} and then enter the file name -@file{@trampfn{, user, host, /path/to.file}}. - -On some hosts, there are problems with opening a connection. These are -related to the behavior of the remote shell. See @xref{Remote shell -setup}, for details on this. - -If you do not wish to use these commands to connect to the remote -host, you should change the default connection and transfer method -that @value{tramp} uses. There are several different methods that @value{tramp} -can use to connect to remote hosts and transfer files -(@pxref{Connection types}). - -If you don't know which method is right for you, see @xref{Default -Method}. - - -@menu -* Connection types:: Types of connections made to remote hosts. -* Inline methods:: Inline methods. -* External methods:: External methods. -@ifset emacsgvfs -* GVFS based methods:: GVFS based external methods. -@end ifset -@ifset emacsgw -* Gateway methods:: Gateway methods. -@end ifset -* Default Method:: Selecting a default method. - Here we also try to help those who - don't have the foggiest which method - is right for them. -* Default User:: Selecting a default user. -* Default Host:: Selecting a default host. -* Multi-hops:: Connecting to a remote host using multiple hops. -* Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. -* Password handling:: Reusing passwords for several connections. -* Connection caching:: Reusing connection related information. -* Predefined connection information:: - Setting own connection related information. -* Remote Programs:: How @value{tramp} finds and uses programs on the remote host. -* Remote shell setup:: Remote shell setup hints. -* Android shell setup:: Android shell setup hints. -* Auto-save and Backup:: Auto-save and Backup. -* Windows setup hints:: Issues with Cygwin ssh. -@end menu - - -@node Connection types -@section Types of connections made to remote hosts -@cindex connection types, overview - -There are two basic types of transfer methods, each with its own -advantages and limitations. Both types of connection make use of a -remote shell access program such as @command{rsh}, @command{ssh} or -@command{telnet} to connect to the remote host. - -This connection is used to perform many of the operations that @value{tramp} -requires to make the remote file system transparently accessible from -the local host. It is only when visiting files that the methods -differ. - -@cindex inline methods -@cindex external methods -@cindex methods, inline -@cindex methods, external -Loading or saving a remote file requires that the content of the file -be transferred between the two hosts. The content of the file can -be transferred using one of two methods: the @dfn{inline method} over -the same connection used to log in to the remote host, or the -@dfn{external method} through another connection using a remote copy -program such as @command{rcp}, @command{scp} or @command{rsync}. - -The performance of the external methods is generally better than that -of the inline methods, at least for large files. This is caused by -the need to encode and decode the data when transferring inline. - -The one exception to this rule are the @command{scp} based transfer -methods. While these methods do see better performance when actually -transferring files, the overhead of the cryptographic negotiation at -startup may drown out the improvement in file transfer times. - -External methods should be configured such a way that they don't -require a password (with @command{ssh-agent}, or such alike). Modern -@command{scp} implementations offer options to reuse existing -@command{ssh} connections, which will be enabled by default if -available. If it isn't possible, you should consider @ref{Password -handling}, otherwise you will be prompted for a password every copy -action. - - -@node Inline methods -@section Inline methods -@cindex inline methods -@cindex methods, inline - -The inline methods in @value{tramp} are quite powerful and can work in -situations where you cannot use an external transfer program to connect. -Inline methods are the only methods that work when connecting to the -remote host via telnet. (There are also strange inline methods which -allow you to transfer files between @emph{user identities} rather than -hosts, see below.) - -These methods depend on the existence of a suitable encoding and -decoding command on remote host. Locally, @value{tramp} may be able to -use features of @value{emacsname} to decode and encode the files or -it may require access to external commands to perform that task. - -@cindex uuencode -@cindex mimencode -@cindex base-64 encoding -@value{tramp} checks the availability and usability of commands like -@command{mimencode} (part of the @command{metamail} package) or -@command{uuencode} on the remote host. The first reliable command -will be used. The search path can be customized, see @ref{Remote -Programs}. - -If both commands aren't available on the remote host, @value{tramp} -transfers a small piece of Perl code to the remote host, and tries to -apply it for encoding and decoding. - -The variable @var{tramp-inline-compress-start-size} controls, whether -a file shall be compressed before encoding. This could increase -transfer speed for large text files. - - -@table @asis -@item @option{rsh} -@cindex method rsh -@cindex rsh method - -Connect to the remote host with @command{rsh}. Due to the unsecure -connection it is recommended for very local host topology only. - -On operating systems which provide the command @command{remsh} instead -of @command{rsh}, you can use the method @option{remsh}. This is true -for HP-UX or Cray UNICOS, for example. - - -@item @option{ssh} -@cindex method ssh -@cindex ssh method - -Connect to the remote host with @command{ssh}. This is identical to -the previous option except that the @command{ssh} package is used, -making the connection more secure. - -All the methods based on @command{ssh} have an additional feature: you -can specify a host name which looks like @file{host#42} (the real host -name, then a hash sign, then a port number). This means to connect to -the given host but to also pass @code{-p 42} as arguments to the -@command{ssh} command. - - -@item @option{telnet} -@cindex method telnet -@cindex telnet method - -Connect to the remote host with @command{telnet}. This is as unsecure -as the @option{rsh} method. - - -@item @option{su} -@cindex method su -@cindex su method - -This method does not connect to a remote host at all, rather it uses -the @command{su} program to allow you to edit files as another user. -That means, the specified host name in the file name must be either -@samp{localhost} or the host name as returned by the function -@command{(system-name)}. For an exception of this rule see -@ref{Multi-hops}. - - -@item @option{sudo} -@cindex method sudo -@cindex sudo method - -This is similar to the @option{su} method, but it uses @command{sudo} -rather than @command{su} to become a different user. - -Note that @command{sudo} must be configured to allow you to start a -shell as the user. It would be nice if it was sufficient if -@command{ls} and @command{mimencode} were allowed, but that is not -easy to implement, so I haven't got around to it, yet. - - -@item @option{sshx} -@cindex method sshx -@cindex sshx method - -As you would expect, this is similar to @option{ssh}, only a little -different. Whereas @option{ssh} opens a normal interactive shell on -the remote host, this option uses @samp{ssh -t -t @var{host} -l -@var{user} /bin/sh} to open a connection. This is useful for users -where the normal login shell is set up to ask them a number of -questions when logging in. This procedure avoids these questions, and -just gives @value{tramp} a more-or-less `standard' login shell to work -with. - -Note that this procedure does not eliminate questions asked by -@command{ssh} itself. For example, @command{ssh} might ask ``Are you -sure you want to continue connecting?'' if the host key of the remote -host is not known. @value{tramp} does not know how to deal with such a -question (yet), therefore you will need to make sure that you can log -in without such questions. - -This is also useful for Windows users where @command{ssh}, when -invoked from an @value{emacsname} buffer, tells them that it is not -allocating a pseudo tty. When this happens, the login shell is wont -to not print any shell prompt, which confuses @value{tramp} mightily. - -This supports the @samp{-p} argument. - - -@item @option{krlogin} -@cindex method krlogin -@cindex krlogin method -@cindex Kerberos (with krlogin method) - -This method is also similar to @option{ssh}. It only uses the -@command{krlogin -x} command to log in to the remote host. - - -@item @option{ksu} -@cindex method ksu -@cindex ksu method -@cindex Kerberos (with ksu method) - -This is another method from the Kerberos suite. It behaves like @option{su}. - - -@item @option{plink} -@cindex method plink -@cindex plink method - -This method is mostly interesting for Windows users using the PuTTY -implementation of SSH@. It uses @samp{plink -ssh} to log in to the -remote host. - -This supports the @samp{-P} argument. - - -@item @option{plinkx} -@cindex method plinkx -@cindex plinkx method - -Another method using PuTTY on Windows. Instead of host names, it -expects PuTTY session names, calling @samp{plink -load @var{session} --t"}. User names are relevant only in case the corresponding session -hasn't defined a user name. Different port numbers must be defined in -the session. - -@end table - - -@node External methods -@section External methods -@cindex methods, external -@cindex external methods - -The external methods operate through multiple channels, using the -remote shell connection for many actions while delegating file -transfers to an external transfer utility. - -This saves the overhead of encoding and decoding that multiplexing the -transfer through the one connection has with the inline methods. - -Since external methods need their own overhead opening a new channel, -all files which are smaller than @var{tramp-copy-size-limit} are still -transferred with the corresponding inline method. It should provide a -fair trade-off between both approaches. - -@table @asis -@item @option{rcp}---@command{rsh} and @command{rcp} -@cindex method rcp -@cindex rcp method -@cindex rcp (with rcp method) -@cindex rsh (with rcp method) - -This method uses the @command{rsh} and @command{rcp} commands to connect -to the remote host and transfer files. This is probably the fastest -connection method available. - -The alternative method @option{remcp} uses the @command{remsh} and -@command{rcp} commands. It should be applied on hosts where -@command{remsh} is used instead of @command{rsh}. - - -@item @option{scp}---@command{ssh} and @command{scp} -@cindex method scp -@cindex scp method -@cindex scp (with scp method) -@cindex ssh (with scp method) - -Using @command{ssh} to connect to the remote host and @command{scp} to -transfer files between the hosts is the best method for securely -connecting to a remote host and accessing files. - -The performance of this option is also quite good. It may be slower than -the inline methods when you often open and close small files however. -The cost of the cryptographic handshake at the start of an @command{scp} -session can begin to absorb the advantage that the lack of encoding and -decoding presents. - -All the @command{ssh} based methods support the @samp{-p} feature -where you can specify a port number to connect to in the host name. -For example, the host name @file{host#42} tells @value{tramp} to -specify @samp{-p 42} in the argument list for @command{ssh}, and to -specify @samp{-P 42} in the argument list for @command{scp}. - - -@item @option{sftp}---@command{ssh} and @command{sftp} -@cindex method sftp -@cindex sftp method -@cindex sftp (with sftp method) -@cindex ssh (with sftp method) - -That is mostly the same method as @option{scp}, but using -@command{sftp} as transfer command. So the same remarks are valid. - -This command does not work like @value{ftppackagename}, where -@command{ftp} is called interactively, and all commands are send from -within this session. Instead of, @command{ssh} is used for login. - -This method supports the @samp{-p} argument. - - -@item @option{rsync}---@command{ssh} and @command{rsync} -@cindex method rsync -@cindex rsync method -@cindex rsync (with rsync method) -@cindex ssh (with rsync method) - -Using the @command{ssh} command to connect securely to the remote -host and the @command{rsync} command to transfer files is almost -identical to the @option{scp} method. - -While @command{rsync} performs much better than @command{scp} when -transferring files that exist on both hosts, this advantage is lost if -the file exists only on one side of the connection. A file can exists -on both the remote and local host, when you copy a file from/to a -remote host. When you just open a file from the remote host (or write -a file there), a temporary file on the local side is kept as long as -the corresponding buffer, visiting this file, is alive. - -This method supports the @samp{-p} argument. - - -@item @option{scpx}---@command{ssh} and @command{scp} -@cindex method scpx -@cindex scpx method -@cindex scp (with scpx method) -@cindex ssh (with scpx method) - -As you would expect, this is similar to @option{scp}, only a little -different. Whereas @option{scp} opens a normal interactive shell on -the remote host, this option uses @samp{ssh -t -t @var{host} -l -@var{user} /bin/sh} to open a connection. This is useful for users -where the normal login shell is set up to ask them a number of -questions when logging in. This procedure avoids these questions, and -just gives @value{tramp} a more-or-less `standard' login shell to work -with. - -This is also useful for Windows users where @command{ssh}, when -invoked from an @value{emacsname} buffer, tells them that it is not -allocating a pseudo tty. When this happens, the login shell is wont -to not print any shell prompt, which confuses @value{tramp} mightily. - -This method supports the @samp{-p} argument. - - -@item @option{pscp}---@command{plink} and @command{pscp} -@cindex method pscp -@cindex pscp method -@cindex pscp (with pscp method) -@cindex plink (with pscp method) -@cindex PuTTY (with pscp method) - -This method is similar to @option{scp}, but it uses the -@command{plink} command to connect to the remote host, and it uses -@command{pscp} for transferring the files. These programs are part -of PuTTY, an SSH implementation for Windows. - -This method supports the @samp{-P} argument. - - -@item @option{psftp}---@command{plink} and @command{psftp} -@cindex method psftp -@cindex psftp method -@cindex psftp (with psftp method) -@cindex plink (with psftp method) -@cindex PuTTY (with psftp method) - -As you would expect, this method is similar to @option{sftp}, but it -uses the @command{plink} command to connect to the remote host, and it -uses @command{psftp} for transferring the files. These programs are -part of PuTTY, an SSH implementation for Windows. - -This method supports the @samp{-P} argument. - - -@item @option{fcp}---@command{fsh} and @command{fcp} -@cindex method fcp -@cindex fcp method -@cindex fsh (with fcp method) -@cindex fcp (with fcp method) - -This method is similar to @option{scp}, but it uses the @command{fsh} -command to connect to the remote host, and it uses @command{fcp} for -transferring the files. @command{fsh/fcp} are a front-end for -@command{ssh} which allow for reusing the same @command{ssh} session -for submitting several commands. This avoids the startup overhead of -@command{scp} (which has to establish a secure connection whenever it -is called). Note, however, that you can also use one of the inline -methods to achieve a similar effect. - -This method uses the command @samp{fsh @var{host} -l @var{user} -/bin/sh -i} to establish the connection, it does not work to just say -@command{fsh @var{host} -l @var{user}}. - -@cindex method fsh -@cindex fsh method - -There is no inline method using @command{fsh} as the multiplexing -provided by the program is not very useful in our context. @value{tramp} -opens just one connection to the remote host and then keeps it open, -anyway. - - -@item @option{ftp} -@cindex method ftp -@cindex ftp method - -This is not a native @value{tramp} method. Instead, it forwards all -requests to @value{ftppackagename}. -@ifset xemacs -This works only for unified file names, see @ref{Issues}. -@end ifset - - -@item @option{smb}---@command{smbclient} -@cindex method smb -@cindex smb method - -This is another not native @value{tramp} method. It uses the -@command{smbclient} command on different Unices in order to connect to -an SMB server. An SMB server might be a Samba (or CIFS) server on -another UNIX host or, more interesting, a host running MS Windows. So -far, it is tested against MS Windows NT, MS Windows 2000, MS Windows -XP, MS Windows Vista, and MS Windows 7. - -The first directory in the localname must be a share name on the remote -host. Remember that the @code{$} character, in which default shares -usually end, must be written @code{$$} due to environment variable -substitution in file names. If no share name is given (i.e., remote -directory @code{/}), all available shares are listed. - -Since authorization is done on share level, you will always be -prompted for a password if you access another share on the same host. -This can be suppressed by @ref{Password handling}. - -For authorization, MS Windows uses both a user name and a domain name. -Because of this, the @value{tramp} syntax has been extended: you can -specify a user name which looks like @code{user%domain} (the real user -name, then a percent sign, then the domain name). So, to connect to -the host @code{melancholia} as user @code{daniel} of the domain -@code{BIZARRE}, and edit @file{.emacs} in the home directory (share -@code{daniel$}) I would specify the file name @file{@trampfn{smb, -daniel%BIZARRE, melancholia, /daniel$$/.emacs}}. - -Depending on the Windows domain configuration, a Windows user might be -considered as domain user per default. In order to connect as local -user, the WINS name of that host must be given as domain name. -Usually, it is the host name in capital letters. In the example -above, the local user @code{daniel} would be specified as -@file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}. - -The domain name as well as the user name are optional. If no user -name is specified at all, the anonymous user (without password -prompting) is assumed. This is different from all other @value{tramp} -methods, where in such a case the local user name is taken. - -The @option{smb} method supports the @samp{-p} argument. - -@strong{Please note:} If @value{emacsname} runs locally under MS -Windows, this method isn't available. Instead, you can use UNC -file names like @file{//melancholia/daniel$$/.emacs}. The only -disadvantage is that there's no possibility to specify another user -name. - - -@item @option{adb} -@cindex method adb -@cindex adb method - -This special method uses the Android Debug Bridge for accessing -Android devices. The Android Debug Bridge must be installed locally. -Some GNU/Linux distributions offer it for installation, otherwise it -can be installed as part of the Android SDK. If the @command{adb} -program is not found via the @env{PATH} environment variable, the -variable @var{tramp-adb-program} must point to its absolute path. - -Tramp does not connect Android devices to @command{adb}. This must be -performed outside @value{emacsname}. If there is exactly one Android -device connected to @command{adb}, a host name is not needed in the -remote file name. The default @value{tramp} name to be used is -@file{@trampfn{adb, , ,}} therefore. Otherwise, one could find -potential host names with the command @command{adb devices}. - -Usually, the @command{adb} method does not need any user name. It -runs under the permissions of the @command{adbd} process on the -Android device. If a user name is specified, @value{tramp} applies an -@command{su} on the device. This does not work with all Android -devices, especially with unrooted ones. In that case, an error -message is displayed. - -@end table - - -@ifset emacsgvfs -@node GVFS based methods -@section GVFS based external methods -@cindex methods, gvfs -@cindex gvfs based methods -@cindex dbus - -The connection methods described in this section are based on GVFS -@uref{http://en.wikipedia.org/wiki/GVFS}. Via GVFS, the remote -filesystem is mounted locally through FUSE@. @value{tramp} uses -this local mounted directory internally. - -The communication with GVFS is implemented via D-Bus messages. -Therefore, your @value{emacsname} must have D-Bus integration, -@pxref{Top, , D-Bus, dbus}. - -@table @asis -@item @option{dav} -@cindex method dav -@cindex method davs -@cindex dav method -@cindex davs method - -This method provides access to WebDAV files and directories. There -exists also the external method @option{davs}, which uses SSL -encryption for the access. - -Both methods support the port number specification as discussed above. - - -@item @option{obex} -@cindex method obex -@cindex obex method - -OBEX is an FTP-like access protocol for simple devices, like cell -phones. For the time being, @value{tramp} only supports OBEX over Bluetooth. - - -@item @option{synce} -@cindex method synce -@cindex synce method - -The @option{synce} method allows communication with Windows Mobile -devices. Beside GVFS for mounting remote files and directories via -FUSE, it also needs the SYNCE-GVFS plugin. - -@end table - -@defopt tramp-gvfs-methods -This customer option, a list, defines the external methods which -shall be used with GVFS@. Per default, these are @option{dav}, -@option{davs}, @option{obex} and @option{synce}. Other possible -values are @option{ftp}, @option{sftp} and @option{smb}. -@end defopt -@end ifset - - -@ifset emacsgw -@node Gateway methods -@section Gateway methods -@cindex methods, gateway -@cindex gateway methods - -Gateway methods are not methods to access a remote host directly. -These methods are intended to pass firewalls or proxy servers. -Therefore, they can be used for proxy host declarations -(@pxref{Multi-hops}) only. - -A gateway method must always come along with a method which supports -port setting. This is because @value{tramp} targets the accompanied -method to @file{localhost#random_port}, from where the firewall or -proxy server is accessed. - -Gateway methods support user name and password declarations. These -are used to authenticate towards the corresponding firewall or proxy -server. They can be passed only if your friendly administrator has -granted your access. - -@table @asis -@item @option{tunnel} -@cindex method tunnel -@cindex tunnel method - -This method implements an HTTP tunnel via the @command{CONNECT} -command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server -shall support this command. - -As authentication method, only @option{Basic Authentication} (see RFC -2617) is implemented so far. If no port number is given in the -declaration, port @option{8080} is used for the proxy server. - - -@item @option{socks} -@cindex method socks -@cindex socks method - -The @command{socks} method provides access to SOCKSv5 servers (see -RFC 1928). @option{Username/Password Authentication} according to RFC -1929 is supported. - -The default port number of the socks server is @option{1080}, if not -specified otherwise. - -@end table -@end ifset - - -@node Default Method -@section Selecting a default method -@cindex default method - -@vindex tramp-default-method -When you select an appropriate transfer method for your typical usage -you should set the variable @code{tramp-default-method} to reflect that -choice. This variable controls which method will be used when a method -is not specified in the @value{tramp} file name. For example: - -@lisp -(setq tramp-default-method "ssh") -@end lisp - -@vindex tramp-default-method-alist -You can also specify different methods for certain user/host -combinations, via the variable @code{tramp-default-method-alist}. For -example, the following two lines specify to use the @option{ssh} -method for all user names matching @samp{john} and the @option{rsync} -method for all host names matching @samp{lily}. The third line -specifies to use the @option{su} method for the user @samp{root} on -the host @samp{localhost}. - -@lisp -(add-to-list 'tramp-default-method-alist '("" "john" "ssh")) -(add-to-list 'tramp-default-method-alist '("lily" "" "rsync")) -(add-to-list 'tramp-default-method-alist - '("\\`localhost\\'" "\\`root\\'" "su")) -@end lisp - -@noindent -See the documentation for the variable -@code{tramp-default-method-alist} for more details. - -External methods are normally preferable to inline methods, giving -better performance. - -@xref{Inline methods}. -@xref{External methods}. - -Another consideration with the selection of transfer methods is the -environment you will use them in and, especially when used over the -Internet, the security implications of your preferred method. - -The @option{rsh} and @option{telnet} methods send your password as -plain text as you log in to the remote host, as well as -transferring the files in such a way that the content can easily be -read from other hosts. - -If you need to connect to remote systems that are accessible from the -Internet, you should give serious thought to using @option{ssh} based -methods to connect. These provide a much higher level of security, -making it a non-trivial exercise for someone to obtain your password -or read the content of the files you are editing. - - -@subsection Which method is the right one for me? -@cindex choosing the right method - -Given all of the above, you are probably thinking that this is all fine -and good, but it's not helping you to choose a method! Right you are. -As a developer, we don't want to boss our users around but give them -maximum freedom instead. However, the reality is that some users would -like to have some guidance, so here I'll try to give you this guidance -without bossing you around. You tell me whether it works @dots{} - -My suggestion is to use an inline method. For large files, external -methods might be more efficient, but I guess that most people will -want to edit mostly small files. And if you access large text files, -compression (driven by @var{tramp-inline-compress-start-size}) shall -still result in good performance. - -I guess that these days, most people can access a remote host by -using @command{ssh}. So I suggest that you use the @option{ssh} -method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost, -/etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other -host. - -If you can't use @option{ssh} to log in to the remote host, then -select a method that uses a program that works. For instance, Windows -users might like the @option{plink} method which uses the PuTTY -implementation of @command{ssh}. Or you use Kerberos and thus like -@option{krlogin}. - -For the special case of editing files on the local host as another -user, see the @option{su} or @option{sudo} methods. They offer -shortened syntax for the @samp{root} account, like -@file{@trampfn{su, , , /etc/motd}}. - -People who edit large files may want to consider @option{scp} instead -of @option{ssh}, or @option{pscp} instead of @option{plink}. These -external methods are faster than inline methods for large files. -Note, however, that external methods suffer from some limitations. -Please try first whether you really get a noticeable speed advantage -from using an external method! Maybe even for large files, inline -methods are fast enough. - - -@node Default User -@section Selecting a default user -@cindex default user - -The user part of a @value{tramp} file name can be omitted. Usually, -it is replaced by the user name you are logged in. Often, this is not -what you want. A typical use of @value{tramp} might be to edit some -files with root permissions on the local host. This case, you should -set the variable @code{tramp-default-user} to reflect that choice. -For example: - -@lisp -(setq tramp-default-user "root") -@end lisp - -@code{tramp-default-user} is regarded as obsolete, and will be removed -soon. - -@vindex tramp-default-user-alist -You can also specify different users for certain method/host -combinations, via the variable @code{tramp-default-user-alist}. For -example, if you always have to use the user @samp{john} in the domain -@samp{somewhere.else}, you can specify the following: - -@lisp -(add-to-list 'tramp-default-user-alist - '("ssh" ".*\\.somewhere\\.else\\'" "john")) -@end lisp - -@noindent -See the documentation for the variable @code{tramp-default-user-alist} -for more details. - -One trap to fall in must be known. If @value{tramp} finds a default -user, this user will be passed always to the connection command as -parameter (for example @command{ssh here.somewhere.else -l john}. If -you have specified another user for your command in its configuration -files, @value{tramp} cannot know it, and the remote access will fail. -If you have specified in the given example in @file{~/.ssh/config} the -lines - -@example -Host here.somewhere.else - User lily -@end example - -@noindent -than you must discard selecting a default user by @value{tramp}. This -will be done by setting it to @code{nil} (or @samp{lily}, likewise): - -@lisp -(add-to-list 'tramp-default-user-alist - '("ssh" "\\`here\\.somewhere\\.else\\'" nil)) -@end lisp - -The last entry in @code{tramp-default-user-alist} could be your -default user you'll apply predominantly. You shall @emph{append} it -to that list at the end: - -@lisp -(add-to-list 'tramp-default-user-alist '(nil nil "jonas") t) -@end lisp - - -@node Default Host -@section Selecting a default host -@cindex default host - -@vindex tramp-default-host -Finally, it is even possible to omit the host name part of a -@value{tramp} file name. This case, the value of the variable -@code{tramp-default-host} is used. Per default, it is initialized -with the host name your local @value{emacsname} is running. - -If you, for example, use @value{tramp} mainly to contact the host -@samp{target} as user @samp{john}, you can specify: - -@lisp -(setq tramp-default-user "john" - tramp-default-host "target") -@end lisp - -Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you -to John's home directory on target. -@ifset emacs -Note, however, that the most simplification @samp{/::} won't work, -because @samp{/:} is the prefix for quoted file names. -@end ifset - -@vindex tramp-default-host-alist -Like with methods and users, you can also specify different default -hosts for certain method/user combinations via the variable -@code{tramp-default-host-alist}. Usually, this isn't necessary, -because @code{tramp-default-host} should be sufficient. For some -methods, like @option{adb}, that default value must be overwritten, -which is already the initial value of @code{tramp-default-host-alist}. - -@noindent -See the documentation for the variable @code{tramp-default-host-alist} -for more details. - - -@node Multi-hops -@section Connecting to a remote host using multiple hops -@cindex multi-hop -@cindex proxy hosts - -Sometimes, the methods described before are not sufficient. -Sometimes, it is not possible to connect to a remote host using a -simple command. For example, if you are in a secured network, you -might have to log in to a bastion host first before you can connect to -the outside world. Of course, the target host may also require a -bastion host. - -@vindex tramp-default-proxies-alist -@defopt tramp-default-proxies-alist -In order to specify multiple hops, it is possible to define a proxy -host to pass through, via the variable -@code{tramp-default-proxies-alist}. This variable keeps a list of -triples (@var{host} @var{user} @var{proxy}). - -The first matching item specifies the proxy host to be passed for a -file name located on a remote target matching @var{user}@@@var{host}. -@var{host} and @var{user} are regular expressions or @code{nil}, which -is interpreted as a regular expression which always matches. - -@var{proxy} must be a Tramp file name which localname part is ignored. -Method and user name on @var{proxy} are optional, which is interpreted -with the default values. -@ifset emacsgw -The method must be an inline or gateway method (@pxref{Inline -methods}, @pxref{Gateway methods}). -@end ifset -@ifclear emacsgw -The method must be an inline method (@pxref{Inline methods}). -@end ifclear -If @var{proxy} is @code{nil}, no additional hop is required reaching -@var{user}@@@var{host}. - -If you, for example, must pass the host @samp{bastion.your.domain} as -user @samp{bird} for any remote host which is not located in your local -domain, you can set - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}")) -(add-to-list 'tramp-default-proxies-alist - '("\\.your\\.domain\\'" nil nil)) -@end lisp - -Please note the order of the code. @code{add-to-list} adds elements at the -beginning of a list. Therefore, most relevant rules must be added last. - -Proxy hosts can be cascaded. If there is another host called -@samp{jump.your.domain}, which is the only one in your local domain who -is allowed connecting @samp{bastion.your.domain}, you can add another -rule: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\`bastion\\.your\\.domain\\'" - "\\`bird\\'" - "@trampfn{ssh, , jump.your.domain,}")) -@end lisp - -@var{proxy} can contain the patterns @code{%h} or @code{%u}. These -patterns are replaced by the strings matching @var{host} or -@var{user}, respectively. - -If you, for example, wants to work as @samp{root} on hosts in the -domain @samp{your.domain}, but login as @samp{root} is disabled for -non-local access, you might add the following rule: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}")) -@end lisp - -Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect -first @samp{randomhost.your.domain} via @code{ssh} under your account -name, and perform @code{sudo -u root} on that host afterwards. It is -important to know that the given method is applied on the host which -has been reached so far. @code{sudo -u root}, applied on your local -host, wouldn't be useful here. - -@var{host}, @var{user} and @var{proxy} can also be Lisp forms. These -forms are evaluated, and must return a string, or @code{nil}. The -previous example could be generalized then: For all hosts except my -local one connect via @command{ssh} first, and apply @command{sudo -u -root} afterwards: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '(nil "\\`root\\'" "@trampfn{ssh, , %h,}")) -(add-to-list 'tramp-default-proxies-alist - '((regexp-quote (system-name)) nil nil)) -@end lisp - -This is the recommended configuration to work as @samp{root} on remote -Ubuntu hosts. - -@ifset emacsgw -Finally, @code{tramp-default-proxies-alist} can be used to pass -firewalls or proxy servers. Imagine your local network has a host -@samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to -the outer world. Your friendly administrator has granted you access -under your user name to @samp{host.other.domain} on that proxy -server.@footnote{HTTP tunnels are intended for secure SSL/TLS -communication. Therefore, many proxy server restrict the tunnels to -related target ports. You might need to run your ssh server on your -target host @samp{host.other.domain} on such a port, like 443 (https). -See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall} -for discussion of ethical issues.} You would need to add the -following rule: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\`host\\.other\\.domain\\'" nil - "@trampfn{tunnel, , proxy.your.domain#3128,}")) -@end lisp - -Gateway methods can be declared as first hop only in a multiple hop -chain. -@end ifset -@end defopt - -Hops to be passed tend to be restricted firewalls and alike. -Sometimes they offer limited features only, like running @command{rbash} -(restricted bash). This must be told to @value{tramp}. - -@vindex tramp-restricted-shell-hosts-alist -@defopt tramp-restricted-shell-hosts-alist -This variable keeps a list of regular expressions, which denote hosts -running a registered shell like "rbash". Those hosts can be used as -proxies only. - -If the bastion host from the example above runs a restricted shell, -you shall apply - -@lisp -(add-to-list 'tramp-restricted-shell-hosts-alist - "\\`bastion\\.your\\.domain\\'") -@end lisp -@end defopt - - -@node Customizing Methods -@section Using Non-Standard Methods -@cindex customizing methods -@cindex using non-standard methods -@cindex create your own methods - -There is a variable @code{tramp-methods} which you can change if the -predefined methods don't seem right. - -For the time being, I'll refer you to the Lisp documentation of that -variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. - - -@node Customizing Completion -@section Selecting config files for user/host name completion -@cindex customizing completion -@cindex selecting config files -@vindex tramp-completion-function-alist - -The variable @code{tramp-completion-function-alist} is intended to -customize which files are taken into account for user and host name -completion (@pxref{File name completion}). For every method, it keeps -a set of configuration files, accompanied by a Lisp function able to -parse that file. Entries in @code{tramp-completion-function-alist} -have the form (@var{method} @var{pair1} @var{pair2} ...). - -Each @var{pair} is composed of (@var{function} @var{file}). -@var{function} is responsible to extract user names and host names -from @var{file} for completion. There are two functions which access -this variable: - -@defun tramp-get-completion-function method -This function returns the list of completion functions for @var{method}. - -Example: -@example -(tramp-get-completion-function "rsh") - - @result{} ((tramp-parse-rhosts "/etc/hosts.equiv") - (tramp-parse-rhosts "~/.rhosts")) -@end example -@end defun - -@defun tramp-set-completion-function method function-list -This function sets @var{function-list} as list of completion functions -for @var{method}. - -Example: -@example -(tramp-set-completion-function "ssh" - '((tramp-parse-sconfig "/etc/ssh_config") - (tramp-parse-sconfig "~/.ssh/config"))) - - @result{} ((tramp-parse-sconfig "/etc/ssh_config") - (tramp-parse-sconfig "~/.ssh/config")) -@end example -@end defun - -The following predefined functions parsing configuration files exist: - -@table @asis -@item @code{tramp-parse-rhosts} -@findex tramp-parse-rhosts - -This function parses files which are syntactical equivalent to -@file{~/.rhosts}. It returns both host names and user names, if -specified. - -@item @code{tramp-parse-shosts} -@findex tramp-parse-shosts - -This function parses files which are syntactical equivalent to -@file{~/.ssh/known_hosts}. Since there are no user names specified -in such files, it can return host names only. - -@item @code{tramp-parse-sconfig} -@findex tramp-parse-shosts - -This function returns the host nicknames defined by @code{Host} entries -in @file{~/.ssh/config} style files. - -@item @code{tramp-parse-shostkeys} -@findex tramp-parse-shostkeys - -SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and -@file{~/ssh2/hostkeys/*}. Hosts are coded in file names -@file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names -are always @code{nil}. - -@item @code{tramp-parse-sknownhosts} -@findex tramp-parse-shostkeys - -Another SSH2 style parsing of directories like -@file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This -case, hosts names are coded in file names -@file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}. - -@item @code{tramp-parse-hosts} -@findex tramp-parse-hosts - -A function dedicated to @file{/etc/hosts} style files. It returns -host names only. - -@item @code{tramp-parse-passwd} -@findex tramp-parse-passwd - -A function which parses @file{/etc/passwd} like files. Obviously, it -can return user names only. - -@item @code{tramp-parse-netrc} -@findex tramp-parse-netrc - -Finally, a function which parses @file{~/.netrc} like files. This -includes also @file{~/.authinfo}-style files. - -@end table - -If you want to keep your own data in a file, with your own structure, -you might provide such a function as well. This function must meet -the following conventions: - -@defun my-tramp-parse file -@var{file} must be either a file name on your host, or @code{nil}. -The function must return a list of (@var{user} @var{host}), which are -taken as candidates for user and host name completion. - -Example: -@example -(my-tramp-parse "~/.my-tramp-hosts") - - @result{} ((nil "toto") ("daniel" "melancholia")) -@end example -@end defun - - -@node Password handling -@section Reusing passwords for several connections -@cindex passwords - -Sometimes it is necessary to connect to the same remote host several -times. Reentering passwords again and again would be annoying, when -the chosen method does not support access without password prompt -through own configuration. - -The best recommendation is to use the method's own mechanism for -password handling. Consider @command{ssh-agent} for @option{ssh}-like -methods, or @command{pageant} for @option{plink}-like methods. - -However, if you cannot apply such native password handling, -@value{tramp} offers alternatives. - - -@anchor{Using an authentication file} -@subsection Using an authentication file - -@vindex auth-sources -The package @file{auth-source.el}, originally developed in No Gnus, -offers the possibility to read passwords from a file, like FTP does it -from @file{~/.netrc}. The default authentication file is -@file{~/.authinfo.gpg}, this can be changed via the variable -@code{auth-sources}. - -@noindent -A typical entry in the authentication file would be - -@example -machine melancholia port scp login daniel password geheim -@end example - -The port can be any @value{tramp} method (@pxref{Inline methods}, -@pxref{External methods}), to match only this method. When you omit -the port, you match all @value{tramp} methods. - -In case of problems, setting @code{auth-source-debug} to @code{t} -gives useful debug messages. - - -@anchor{Caching passwords} -@subsection Caching passwords - -If there is no authentication file, @value{tramp} caches the passwords -entered by you. They will be reused next time if a connection needs -them for the same user name and host name, independently of the -connection method. - -@vindex password-cache-expiry -Passwords are not saved permanently, that means the password caching -is limited to the lifetime of your @value{emacsname} session. You -can influence the lifetime of password caching by customizing the -variable @code{password-cache-expiry}. The value is the number of -seconds how long passwords are cached. Setting it to @code{nil} -disables the expiration. - -@vindex password-cache -If you don't like this feature for security reasons, password caching -can be disabled totally by customizing the variable -@code{password-cache} (setting it to @code{nil}). - -Implementation Note: password caching is based on the package -@file{password-cache.el}. For the time being, it is activated only -when this package is seen in the @code{load-path} while loading -@value{tramp}. -@ifset installchapter -If you don't use No Gnus, you can take @file{password.el} from the -@value{tramp} @file{contrib} directory, see @ref{Installation -parameters}. -@end ifset - - -@node Connection caching -@section Reusing connection related information -@cindex caching - -@vindex tramp-persistency-file-name -In order to reduce initial connection time, @value{tramp} stores -connection related information persistently. The variable -@code{tramp-persistency-file-name} keeps the file name where these -information are written. Its default value is -@ifset emacs -@file{~/.emacs.d/tramp}. -@end ifset -@ifset xemacs -@file{~/.xemacs/tramp}. -@end ifset -It is recommended to choose a local file name. - -@value{tramp} reads this file during startup, and writes it when -exiting @value{emacsname}. You can simply remove this file if -@value{tramp} shall be urged to recompute these information next -@value{emacsname} startup time. - -Using such persistent information can be disabled by setting -@code{tramp-persistency-file-name} to @code{nil}. - -Once consequence of reusing connection related information is that -@var{tramp} needs to distinguish hosts. If you, for example, run a -local @code{sshd} on port 3001, which tunnels @command{ssh} to another -host, you could access both @file{@trampfn{ssh, , localhost,}} and -@file{@trampfn{ssh, , localhost#3001,}}. @var{tramp} would use the -same host related information (like paths, Perl variants, etc) for -both connections, although the information is valid only for one of -them. - -In order to avoid trouble, you must use another host name for one of -the connections, like introducing a @option{Host} section in -@file{~/.ssh/config} (@pxref{Frequently Asked Questions}) or applying -multiple hops (@pxref{Multi-hops}). - -When @value{tramp} detects a changed operating system version on a -remote host (via the command @command{uname -sr}), it flushes all -connection related information for this host, and opens the -connection again. - - -@node Predefined connection information -@section Setting own connection related information - -Sometimes, @var{tramp} is not able to detect correct connection -related information. In such cases, you could tell @var{tramp} which -value it has to take. Since this could result in errors, it has to be -used with care. - -@vindex tramp-connection-properties -Such settings can be performed via the list -@code{tramp-connection-properties}. An entry in this list has the -form @code{(@var{regexp} @var{property} @var{value})}. @var{regexp} -matches remote file names for which a property shall be predefined. -It can be @code{nil}. @var{property} is a string, and @var{value} the -corresponding value. @var{property} could be any property found in -the file @code{tramp-persistency-file-name}. - -A special property is @code{"busybox"}. This must be set, if the -remote host runs a very restricted busybox as shell, which closes the -connection at will. Since there is no reliable test for this, -@var{tramp} must be indicated this way. Example: - -@lisp -(add-to-list 'tramp-connection-properties - (list (regexp-quote "@trampfn{ssh, user, randomhost.your.domain,}") - "busybox" t)) -@end lisp - - -@node Remote Programs -@section How @value{tramp} finds and uses programs on the remote host - -@value{tramp} depends on a number of programs on the remote host in order to -function, including @command{ls}, @command{test}, @command{find} and -@command{cat}. - -In addition to these required tools, there are various tools that may be -required based on the connection method. See @ref{Inline methods} and -@ref{External methods} for details on these. - -Certain other tools, such as @command{perl} (or @command{perl5}) and -@command{grep} will be used if they can be found. When they are -available, they are used to improve the performance and accuracy of -remote file access. - -@vindex tramp-remote-path -@vindex tramp-default-remote-path -@vindex tramp-own-remote-path -@defopt tramp-remote-path -When @value{tramp} connects to the remote host, it searches for the -programs that it can use. The variable @code{tramp-remote-path} -controls the directories searched on the remote host. - -By default, this is set to a reasonable set of defaults for most -hosts. The symbol @code{tramp-default-remote-path} is a place -holder, it is replaced by the list of directories received via the -command @command{getconf PATH} on your remote host. For example, -on Debian GNU/Linux this is @file{/bin:/usr/bin}, whereas on Solaris -this is @file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. -It is recommended to apply this symbol on top of -@code{tramp-remote-path}. - -It is possible, however, that your local (or remote ;) system -administrator has put the tools you want in some obscure local -directory. - -In this case, you can still use them with @value{tramp}. You simply -need to add code to your @file{.emacs} to add the directory to the -remote path. This will then be searched by @value{tramp} when you -connect and the software found. - -To add a directory to the remote search path, you could use code such -as: - -@lisp -@i{;; We load @value{tramp} to define the variable.} -(require 'tramp) -@i{;; We have @command{perl} in "/usr/local/perl/bin"} -(add-to-list 'tramp-remote-path "/usr/local/perl/bin") -@end lisp - -Another possibility is to reuse the path settings of your remote -account when you log in. Usually, these settings are overwritten, -because they might not be useful for @value{tramp}. The place holder -@code{tramp-own-remote-path} preserves these settings. You can -activate it via - -@lisp -(add-to-list 'tramp-remote-path 'tramp-own-remote-path) -@end lisp -@end defopt - -@value{tramp} caches several information, like the Perl binary -location. The changed remote search path wouldn't affect these -settings. In order to force @value{tramp} to recompute these values, -you must exit @value{emacsname}, remove your persistency file -(@pxref{Connection caching}), and restart @value{emacsname}. - - -@node Remote shell setup -@section Remote shell setup hints -@cindex remote shell setup -@cindex @file{.profile} file -@cindex @file{.login} file -@cindex shell init files - -As explained in the @ref{Overview} section, @value{tramp} connects to the -remote host and talks to the shell it finds there. Of course, when you -log in, the shell executes its init files. Suppose your init file -requires you to enter the birth date of your mother; clearly @value{tramp} -does not know this and hence fails to log you in to that host. - -There are different possible strategies for pursuing this problem. One -strategy is to enable @value{tramp} to deal with all possible situations. -This is a losing battle, since it is not possible to deal with -@emph{all} situations. The other strategy is to require you to set up -the remote host such that it behaves like @value{tramp} expects. This might -be inconvenient because you have to invest a lot of effort into shell -setup before you can begin to use @value{tramp}. - -The package, therefore, pursues a combined approach. It tries to -figure out some of the more common setups, and only requires you to -avoid really exotic stuff. For example, it looks through a list of -directories to find some programs on the remote host. And also, it -knows that it is not obvious how to check whether a file exists, and -therefore it tries different possibilities. (On some hosts and -shells, the command @command{test -e} does the trick, on some hosts -the shell builtin doesn't work but the program @command{/usr/bin/test --e} or @command{/bin/test -e} works. And on still other hosts, -@command{ls -d} is the right way to do this.) - -Below you find a discussion of a few things that @value{tramp} does not deal -with, and that you therefore have to set up correctly. - -@table @asis -@item @var{shell-prompt-pattern} -@vindex shell-prompt-pattern - -After logging in to the remote host, @value{tramp} has to wait for the remote -shell startup to finish before it can send commands to the remote -shell. The strategy here is to wait for the shell prompt. In order to -recognize the shell prompt, the variable @code{shell-prompt-pattern} has -to be set correctly to recognize the shell prompt on the remote host. - -Note that @value{tramp} requires the match for @code{shell-prompt-pattern} -to be at the end of the buffer. Many people have something like the -following as the value for the variable: @code{"^[^>$][>$] *"}. Now -suppose your shell prompt is @code{a c $ }. In this case, -@value{tramp} recognizes the @code{>} character as the end of the prompt, -but it is not at the end of the buffer. - -@item @var{tramp-shell-prompt-pattern} -@vindex tramp-shell-prompt-pattern - -This regular expression is used by @value{tramp} in the same way as -@code{shell-prompt-pattern}, to match prompts from the remote shell. -This second variable exists because the prompt from the remote shell -might be different from the prompt from a local shell---after all, -the whole point of @value{tramp} is to log in to remote hosts as a -different user. The default value of -@code{tramp-shell-prompt-pattern} is the same as the default value of -@code{shell-prompt-pattern}, which is reported to work well in many -circumstances. - -@item @var{tramp-password-prompt-regexp} -@vindex tramp-password-prompt-regexp -@vindex tramp-wrong-passwd-regexp - -During login, @value{tramp} might be forced to enter a password or a -passphrase. The difference between both is that a password is -requested from the shell on the remote host, while a passphrase is -needed for accessing local authentication information, like your ssh -key. - -@var{tramp-password-prompt-regexp} handles the detection of such -requests for English environments. When you use another localization -of your (local or remote) host, you might need to adapt this. Example: - -@lisp -(setq - tramp-password-prompt-regexp - (concat - "^.*" - (regexp-opt - '("passphrase" "Passphrase" - ;; English - "password" "Password" - ;; Deutsch - "passwort" "Passwort" - ;; Fran@,{c}ais - "mot de passe" "Mot de passe") t) - ".*:\0? *")) -@end lisp - -In parallel, it might also be necessary to adapt -@var{tramp-wrong-passwd-regexp}. - -@item @command{tset} and other questions -@cindex Unix command tset -@cindex tset Unix command - -Some people invoke the @command{tset} program from their shell startup -scripts which asks the user about the terminal type of the shell. -Maybe some shells ask other questions when they are started. -@value{tramp} does not know how to answer these questions. There are -two approaches for dealing with this problem. One approach is to take -care that the shell does not ask any questions when invoked from -@value{tramp}. You can do this by checking the @env{TERM} -environment variable, it will be set to @code{dumb} when connecting. - -@vindex tramp-terminal-type -The variable @code{tramp-terminal-type} can be used to change this value -to @code{dumb}. - -@vindex tramp-actions-before-shell -The other approach is to teach @value{tramp} about these questions. See -the variable @code{tramp-actions-before-shell}. Example: - -@lisp -(defconst my-tramp-prompt-regexp - (concat (regexp-opt '("Enter the birth date of your mother:") t) - "\\s-*") - "Regular expression matching my login prompt question.") - -(defun my-tramp-action (proc vec) - "Enter \"19000101\" in order to give a correct answer." - (save-window-excursion - (with-current-buffer (tramp-get-connection-buffer vec) - (tramp-message vec 6 "\n%s" (buffer-string)) - (tramp-send-string vec "19000101")))) - -(add-to-list 'tramp-actions-before-shell - '(my-tramp-prompt-regexp my-tramp-action)) -@end lisp - - -@item Environment variables named like users in @file{.profile} - -If you have a user named frumple and set the variable @env{FRUMPLE} in -your shell environment, then this might cause trouble. Maybe rename -the variable to @env{FRUMPLE_DIR} or the like. - -This weird effect was actually reported by a @value{tramp} user! - - -@item Non-Bourne commands in @file{.profile} - -After logging in to the remote host, @value{tramp} issues the command -@command{exec /bin/sh}. (Actually, the command is slightly -different.) When @command{/bin/sh} is executed, it reads some init -files, such as @file{~/.shrc} or @file{~/.profile}. - -Now, some people have a login shell which is not @code{/bin/sh} but a -Bourne-ish shell such as bash or ksh. Some of these people might put -their shell setup into the files @file{~/.shrc} or @file{~/.profile}. -This way, it is possible for non-Bourne constructs to end up in those -files. Then, @command{exec /bin/sh} might cause the Bourne shell to -barf on those constructs. - -As an example, imagine somebody putting @command{export FOO=bar} into -the file @file{~/.profile}. The standard Bourne shell does not -understand this syntax and will emit a syntax error when it reaches -this line. - -Another example is the tilde (@code{~}) character, say when adding -@file{~/bin} to @env{PATH}. Many Bourne shells will not expand this -character, and since there is usually no directory whose name consists -of the single character tilde, strange things will happen. - -What can you do about this? - -Well, one possibility is to make sure that everything in -@file{~/.shrc} and @file{~/.profile} on all remote hosts is -Bourne-compatible. In the above example, instead of @command{export -FOO=bar}, you might use @command{FOO=bar; export FOO} instead. - -The other possibility is to put your non-Bourne shell setup into some -other files. For example, bash reads the file @file{~/.bash_profile} -instead of @file{~/.profile}, if the former exists. So bash -aficionados just rename their @file{~/.profile} to -@file{~/.bash_profile} on all remote hosts, and Bob's your uncle. - -The @value{tramp} developers would like to circumvent this problem, so -if you have an idea about it, please tell us. However, we are afraid -it is not that simple: before saying @command{exec /bin/sh}, -@value{tramp} does not know which kind of shell it might be talking -to. It could be a Bourne-ish shell like ksh or bash, or it could be a -csh derivative like tcsh, or it could be zsh, or even rc. If the -shell is Bourne-ish already, then it might be prudent to omit the -@command{exec /bin/sh} step. But how to find out if the shell is -Bourne-ish? - - -@item Interactive shell prompt - -@value{tramp} redefines the shell prompt in order to parse the shell's -output robustly. When calling an interactive shell by @kbd{M-x -shell}, this doesn't look nice. - -You can redefine the shell prompt by checking the environment variable -@env{INSIDE_EMACS}, which is set by @value{tramp}, in your startup -script @file{~/.emacs_SHELLNAME}. @env{SHELLNAME} might be the string -@code{bash} or similar, in case of doubt you could set it the -environment variable @env{ESHELL} in your @file{.emacs}: - -@lisp -(setenv "ESHELL" "bash") -@end lisp - -Your file @file{~/.emacs_SHELLNAME} could contain code like - -@example -# Reset the prompt for remote Tramp shells. -if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then - PS1="[\u@@\h \w]$ " -fi -@end example - -@ifinfo -@ifset emacs -@xref{Interactive Shell, , , @value{emacsdir}}. -@end ifset -@end ifinfo - -@end table - - -@node Android shell setup -@section Android shell setup hints -@cindex android shell setup - -Android devices use a restricted shell. They can be accessed via the -@option{adb} method. However, this restricts the access to a USB -connection, and it requires the installation of the Android SDK on the -local host. - -When an @command{sshd} process runs on the Android device, like -provided by the @code{SSHDroid} app, any @option{ssh}-based method can -be used. This requires some special settings. - -The default shell @code{/bin/sh} does not exist. Instead, you shall -use just @code{sh}, which invokes the shell installed on the device. -You can instruct @value{tramp} by this form: - -@lisp -(add-to-list 'tramp-connection-properties - (list (regexp-quote "192.168.0.26") "remote-shell" "sh")) -@end lisp - -@noindent -with @samp{192.168.0.26} being the IP address of your Android device -(@pxref{Predefined connection information}). - -The user settings for the @env{PATH} environment variable must be -preserved. It has also been reported, that the commands in -@file{/system/xbin} are better suited than the ones in -@file{/system/bin}. Add these setting: - -@lisp -(add-to-list 'tramp-remote-path 'tramp-own-remote-path) -(add-to-list 'tramp-remote-path "/system/xbin") -@end lisp - -@noindent -If the Android device is not @samp{rooted}, you must give the shell a -writable directory for temporary files: - -@lisp -(add-to-list 'tramp-remote-process-environment "TMPDIR=$HOME") -@end lisp - -@noindent -Now you shall be able to open a remote connection with @kbd{C-x C-f -@trampfn{ssh, , 192.168.0.26#2222, }}, given that @command{sshd} -listens on port @samp{2222}. - -It is also recommended to add a corresponding entry to your -@file{~/.ssh/config} for that connection, like - -@example -Host android - HostName 192.168.0.26 - User root - Port 2222 -@end example - -@noindent -In this case, you must change the setting for the remote shell to - -@lisp -(add-to-list 'tramp-connection-properties - (list (regexp-quote "android") "remote-shell" "sh")) -@end lisp - -@noindent -You would open the connection with @kbd{C-x C-f @trampfn{ssh, , -android, }} then. - - -@node Auto-save and Backup -@section Auto-save and Backup configuration -@cindex auto-save -@cindex backup -@ifset emacs -@vindex backup-directory-alist -@end ifset -@ifset xemacs -@vindex bkup-backup-directory-info -@end ifset - -Normally, @value{emacsname} writes backup files to the same directory -as the original files, but this behavior can be changed via the -variable -@ifset emacs -@code{backup-directory-alist}. -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info}. -@end ifset -In connection with @value{tramp}, this can have unexpected side -effects. Suppose that you specify that all backups should go to the -directory @file{~/.emacs.d/backups/}, and then you edit the file -@file{@trampfn{su, root, localhost, /etc/secretfile}}. The effect is -that the backup file will be owned by you and not by root, thus -possibly enabling others to see it even if they were not intended to -see it. - -When -@ifset emacs -@code{backup-directory-alist} -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info} -@end ifset -is @code{nil} (the default), such problems do not occur. - -Therefore, it is useful to set special values for @value{tramp} -files. For example, the following statement effectively `turns off' -the effect of -@ifset emacs -@code{backup-directory-alist} -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info} -@end ifset -for @value{tramp} files: - -@ifset emacs -@lisp -(add-to-list 'backup-directory-alist - (cons tramp-file-name-regexp nil)) -@end lisp -@end ifset -@ifset xemacs -@lisp -(require 'backup-dir) -(add-to-list 'bkup-backup-directory-info - (list tramp-file-name-regexp "")) -@end lisp -@end ifset - -@ifset emacs -It is also possible to disable backups depending on the used method. -The following code disables backups for the @option{su} and -@option{sudo} methods: - -@lisp -(setq backup-enable-predicate - (lambda (name) - (and (normal-backup-enable-predicate name) - (not - (let ((method (file-remote-p name 'method))) - (when (stringp method) - (member method '("su" "sudo")))))))) -@end lisp -@end ifset - - -Another possibility is to use the @value{tramp} variable -@ifset emacs -@code{tramp-backup-directory-alist}. -@end ifset -@ifset xemacs -@code{tramp-bkup-backup-directory-info}. -@end ifset -This variable has the same meaning like -@ifset emacs -@code{backup-directory-alist}. -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info}. -@end ifset -If a @value{tramp} file is backed up, and DIRECTORY is an absolute -local file name, DIRECTORY is prepended with the @value{tramp} file -name prefix of the file to be backed up. - -@noindent -Example: - -@ifset emacs -@lisp -(add-to-list 'backup-directory-alist - (cons "." "~/.emacs.d/backups/")) -(setq tramp-backup-directory-alist backup-directory-alist) -@end lisp -@end ifset -@ifset xemacs -@lisp -(require 'backup-dir) -(add-to-list 'bkup-backup-directory-info - (list "." "~/.emacs.d/backups/" 'full-path)) -(setq tramp-bkup-backup-directory-info bkup-backup-directory-info) -@end lisp -@end ifset - -@noindent -The backup file name of @file{@trampfn{su, root, localhost, -/etc/secretfile}} would be -@ifset emacs -@file{@trampfn{su, root, localhost, -~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}} -@end ifset -@ifset xemacs -@file{@trampfn{su, root, localhost, -~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}} -@end ifset - -The same problem can happen with auto-saving files. -@ifset emacs -The variable @code{auto-save-file-name-transforms} keeps information, -on which directory an auto-saved file should go. By default, it is -initialized for @value{tramp} files to the local temporary directory. - -On some versions of @value{emacsname}, namely the version built for -Debian GNU/Linux, the variable @code{auto-save-file-name-transforms} -contains the directory where @value{emacsname} was built. A -workaround is to manually set the variable to a sane value. - -If auto-saved files should go into the same directory as the original -files, @code{auto-save-file-name-transforms} should be set to @code{nil}. - -Another possibility is to set the variable -@code{tramp-auto-save-directory} to a proper value. -@end ifset -@ifset xemacs -For this purpose you can set the variable @code{auto-save-directory} -to a proper value. -@end ifset - - -@node Windows setup hints -@section Issues with Cygwin ssh -@cindex Cygwin, issues - -This section needs a lot of work! Please help. - -@cindex method sshx with Cygwin -@cindex sshx method with Cygwin -The recent Cygwin installation of @command{ssh} works only with a -Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x -eshell}, and starting @kbd{ssh test.host}. The problem is evident -if you see a message like this: - -@example -Pseudo-terminal will not be allocated because stdin is not a terminal. -@end example - -Older @command{ssh} versions of Cygwin are told to cooperate with -@value{tramp} selecting @option{sshx} as the connection method. You -can find information about setting up Cygwin in their FAQ at -@uref{http://cygwin.com/faq/}. - -@cindex method scpx with Cygwin -@cindex scpx method with Cygwin -If you wish to use the @option{scpx} connection method, then you might -have the problem that @value{emacsname} calls @command{scp} with a -Windows file name such as @code{c:/foo}. The Cygwin version of -@command{scp} does not know about Windows file names and interprets -this as a remote file name on the host @code{c}. - -One possible workaround is to write a wrapper script for @option{scp} -which converts the Windows file name to a Cygwinized file name. - -@cindex Cygwin and ssh-agent -@cindex SSH_AUTH_SOCK and @value{emacsname} on Windows -If you want to use either @option{ssh} based method on Windows, then -you might encounter problems with @command{ssh-agent}. Using this -program, you can avoid typing the pass-phrase every time you log in. -However, if you start @value{emacsname} from a desktop shortcut, then -the environment variable @env{SSH_AUTH_SOCK} is not set and so -@value{emacsname} and thus @value{tramp} and thus @command{ssh} and -@command{scp} started from @value{tramp} cannot communicate with -@command{ssh-agent}. It works better to start @value{emacsname} from -the shell. - -If anyone knows how to start @command{ssh-agent} under Windows in such a -way that desktop shortcuts can profit, please holler. I don't really -know anything at all about Windows@dots{} - - -@node Usage -@chapter Using @value{tramp} -@cindex using @value{tramp} - -Once you have installed @value{tramp} it will operate fairly -transparently. You will be able to access files on any remote host -that you can log in to as though they were local. - -Files are specified to @value{tramp} using a formalized syntax specifying the -details of the system to connect to. This is similar to the syntax used -by the @value{ftppackagename} package. - -@cindex type-ahead -Something that might happen which surprises you is that -@value{emacsname} remembers all your keystrokes, so if you see a -password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}} -twice instead of once, then the second keystroke will be processed by -@value{emacsname} after @value{tramp} has done its thing. Why, this -type-ahead is normal behavior, you say. Right you are, but be aware -that opening a remote file might take quite a while, maybe half a -minute when a connection needs to be opened. Maybe after half a -minute you have already forgotten that you hit that key! - -@menu -* File name Syntax:: @value{tramp} file name conventions. -* File name completion:: File name completion. -* Ad-hoc multi-hops:: Declaring multiple hops in the file name. -* Remote processes:: Integration with other @value{emacsname} packages. -* Cleanup remote connections:: Cleanup remote connections. -@end menu - - -@node File name Syntax -@section @value{tramp} file name conventions -@cindex file name syntax -@cindex file name examples - -To access the file @var{localname} on the remote host @var{host} -you would specify the file name @file{@trampfn{, , host, -localname}}. This will connect to @var{host} and transfer the file -using the default method. @xref{Default Method}. - -Some examples of @value{tramp} file names are shown below. - -@table @file -@item @value{prefix}melancholia@value{postfix}.emacs -Edit the file @file{.emacs} in your home directory on the host -@code{melancholia}. - -@item @value{prefix}melancholia.danann.net@value{postfix}.emacs -This edits the same file, using the fully qualified domain name of -the host. - -@item @value{prefix}melancholia@value{postfix}~/.emacs -This also edits the same file; the @file{~} is expanded to your -home directory on the remote host, just like it is locally. - -@item @value{prefix}melancholia@value{postfix}~daniel/.emacs -This edits the file @file{.emacs} in the home directory of the user -@code{daniel} on the host @code{melancholia}. The @file{~} -construct is expanded to the home directory of that user on the remote -host. - -@item @value{prefix}melancholia@value{postfix}/etc/squid.conf -This edits the file @file{/etc/squid.conf} on the host -@code{melancholia}. - -@end table - -@var{host} can also be an IPv4 or IPv6 address, like in -@file{@trampfn{, , 127.0.0.1, .emacs}} or @file{@trampfn{, , -@value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}. -@ifset emacs -For syntactical reasons, IPv6 addresses must be embedded in square -brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}. -@end ifset - -Unless you specify a different name to use, @value{tramp} will use the -current local user name as the remote user name to log in with. If you -need to log in as a different user, you can specify the user name as -part of the file name. - -To log in to the remote host as a specific user, you use the syntax -@file{@trampfn{, user, host, path/to.file}}. That means that -connecting to @code{melancholia} as @code{daniel} and editing -@file{.emacs} in your home directory you would specify -@file{@trampfn{, daniel, melancholia, .emacs}}. - -It is also possible to specify other file transfer methods -(@pxref{Inline methods}, @pxref{External methods}) as part of the -file name. -@ifset emacs -This is done by putting the method before the user and host name, as -in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the -trailing colon). -@end ifset -@ifset xemacs -This is done by replacing the initial @file{@value{prefix}} with -@file{@value{prefix}@value{postfixhop}}. (Note the trailing -slash!). -@end ifset -The user, host and file specification remain the same. - -So, to connect to the host @code{melancholia} as @code{daniel}, -using the @option{ssh} method to transfer files, and edit -@file{.emacs} in my home directory I would specify the file name -@file{@trampfn{ssh, daniel, melancholia, .emacs}}. - -@ifset emacs -A remote file name containing a host name only, which is equal to a -method name, is not allowed. If such a host name is used, it must -always be preceded by an explicit method name, like -@file{@value{prefix}ssh@value{postfixhop}ssh@value{postfix}}. -@end ifset - -Finally, for some methods it is possible to specify a different port -number than the default one, given by the method. This is specified -by adding @file{#} to the host name, like in @file{@trampfn{ssh, -daniel, melancholia#42, .emacs}}. - - -@node File name completion -@section File name completion -@cindex file name completion - -File name completion works with @value{tramp} for completion of method -names, of user names and of host names as well as for completion of -file names on remote hosts. -@ifset emacs -In order to enable this, partial completion must be activated in your -@file{.emacs}. -@ifinfo -@xref{Completion Options, , , @value{emacsdir}}. -@end ifinfo -@end ifset - -If you, for example, type @kbd{C-x C-f @value{prefix}t -@key{TAB}}, @value{tramp} might give you as result the choice for - -@example -@c @multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}} -@multitable @columnfractions .5 .5 -@ifset emacs -@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/ -@item @value{prefixhop}toto@value{postfix} @tab -@end ifset -@ifset xemacs -@item @value{prefixhop}telnet@value{postfixhop} @tab @value{prefixhop}toto@value{postfix} -@end ifset -@end multitable -@end example - -@samp{@value{prefixhop}telnet@value{postfixhop}} -is a possible completion for the respective method, -@ifset emacs -@samp{tmp/} stands for the directory @file{/tmp} on your local host, -@end ifset -and @samp{@value{prefixhop}toto@value{postfix}} -might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts} -file (given you're using default method @option{ssh}). - -If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to -@samp{@value{prefix}telnet@value{postfixhop}}. -Next @kbd{@key{TAB}} brings you all host names @value{tramp} detects in -your @file{/etc/hosts} file, let's say - -@example -@multitable @columnfractions .5 .5 -@c @multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}} -@item @trampfn{telnet, , 127.0.0.1,} @tab @trampfn{telnet, , 192.168.0.1,} -@item @trampfn{telnet, , @value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet, , localhost,} -@item @trampfn{telnet, , melancholia.danann.net,} @tab @trampfn{telnet, , melancholia,} -@end multitable -@end example - -Now you can choose the desired host, and you can continue to -complete file names on that host. - -If the configuration files (@pxref{Customizing Completion}), which -@value{tramp} uses for analysis of completion, offer user names, those user -names will be taken into account as well. - -Remote hosts which have been visited in the past and kept -persistently (@pxref{Connection caching}) will be offered too. - -Once the remote host identification is completed, it comes to -file name completion on the remote host. This works pretty much like -for files on the local host, with the exception that minibuffer -killing via a double-slash works only on the file name part, except -that file name part starts with @file{//}. -@ifset emacs -A triple-slash stands for the default behavior. -@end ifset -@ifinfo -@xref{Minibuffer File, , , @value{emacsdir}}. -@end ifinfo - -@noindent -Example: - -@example -@ifset emacs -@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//etc} @key{TAB}} - @print{} @trampfn{telnet, , melancholia, /etc} - -@kbd{C-x C-f @trampfn{telnet, , melancholia, //etc} @key{TAB}} - @print{} /etc - -@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin///etc} @key{TAB}} - @print{} /etc -@end ifset - -@ifset xemacs -@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//}} - @print{} @trampfn{telnet, , melancholia, /} - -@kbd{C-x C-f @trampfn{telnet, , melancholia, //}} - @print{} / -@end ifset -@end example - -A remote directory might have changed its contents out of -@value{emacsname} control, for example by creation or deletion of -files by other processes. Therefore, during file name completion, the -remote directory contents are reread regularly in order to detect such -changes, which would be invisible otherwise (@pxref{Connection caching}). - -@defopt tramp-completion-reread-directory-timeout -This variable defines the number of seconds since last remote command -before rereading a directory contents. A value of 0 would require an -immediate reread during file name completion, @code{nil} means to use -always cached values for the directory contents. -@end defopt - - -@node Ad-hoc multi-hops -@section Declaring multiple hops in the file name -@cindex multi-hop, ad-hoc -@cindex proxy hosts, ad-hoc - -Multiple hops are configured with the variable -@code{tramp-default-proxies-alist} (@pxref{Multi-hops}). However, -sometimes it is desirable to reach a remote host immediately, without -configuration changes. This can be reached by an ad-hoc specification -of the proxies. - -A proxy looks like a remote file name specification without the local -file name part. It is prepended to the target remote file name, -separated by @samp{|}. As an example, a remote file on -@samp{you@@remotehost}, passing the proxy @samp{bird@@bastion}, could -be opened by - -@example -@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh, you, -@c remotehost, /path}} -@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path} -@end example - -Multiple hops can be cascaded, separating all proxies by @samp{|}. -The proxies can also contain the patterns @code{%h} or @code{%u}. - -The ad-hoc definition is added on the fly to -@code{tramp-default-proxies-alist}. Therefore, during the lifetime of -the @value{emacsname} session it is not necessary to enter this ad-hoc -specification, again. The remote file name @samp{@trampfn{ssh, you, -remotehost, /path}} would be sufficient from now on. - -@vindex tramp-save-ad-hoc-proxies -@defopt tramp-save-ad-hoc-proxies -This customer option controls whether ad-hoc definitions are kept -persistently in @code{tramp-default-proxies-alist}. That means, those -definitions are available also for future @value{emacsname} sessions. -@end defopt - - -@node Remote processes -@section Integration with other @value{emacsname} packages -@cindex compile -@cindex recompile - -@value{tramp} supports running processes on a remote host. This -allows to exploit @value{emacsname} packages without modification for -remote file names. It does not work for the @option{ftp} method. -Association of a pty, as specified in @code{start-file-process}, is -not supported. - -@code{process-file} and @code{start-file-process} work on the remote -host when the variable @code{default-directory} is remote: - -@lisp -(let ((default-directory "/ssh:remote.host:")) - (start-file-process "grep" (get-buffer-create "*grep*") - "/bin/sh" "-c" "grep -e tramp *")) -@end lisp - -@ifset emacsgvfs -If the remote host is mounted via GVFS (see @ref{GVFS based methods}), -the remote filesystem is mounted locally. Therefore, there are no -remote processes; all processes run still locally on your host with -an adapted @code{default-directory}. This section does not apply for -such connection methods. -@end ifset - -Remote processes are started when a corresponding command is executed -from a buffer belonging to a remote file or directory. Up to now, the -packages @file{compile.el} (commands like @code{compile} and -@code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}) have been -integrated. Integration of further packages is planned, any help for -this is welcome! - -When your program is not found in the default search path -@value{tramp} sets on the remote host, you should either use an -absolute path, or extend @code{tramp-remote-path} (see @ref{Remote -Programs}): - -@lisp -(add-to-list 'tramp-remote-path "~/bin") -(add-to-list 'tramp-remote-path "/appli/pub/bin") -@end lisp - -The environment for your program can be adapted by customizing -@code{tramp-remote-process-environment}. This variable is a list of -strings. It is structured like @code{process-environment}. Each -element is a string of the form @code{"ENVVARNAME=VALUE"}. An entry -@code{"ENVVARNAME="} disables the corresponding environment variable, -which might have been set in your init file like @file{~/.profile}. - -@noindent -Adding an entry can be performed via @code{add-to-list}: - -@lisp -(add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java") -@end lisp - -Changing or removing an existing entry is not encouraged. The default -values are chosen for proper @value{tramp} work. Nevertheless, if for -example a paranoid system administrator disallows changing the -@env{HISTORY} environment variable, you can customize -@code{tramp-remote-process-environment}, or you can apply the -following code in your @file{.emacs}: - -@lisp -(let ((process-environment tramp-remote-process-environment)) - (setenv "HISTORY" nil) - (setq tramp-remote-process-environment process-environment)) -@end lisp - -If you use other @value{emacsname} packages which do not run -out-of-the-box on a remote host, please let us know. We will try to -integrate them as well. @xref{Bug Reports}. - - -@subsection Running remote programs that create local X11 windows - -If you want to run a remote program, which shall connect the X11 -server you are using with your local host, you can set the -@env{DISPLAY} environment variable on the remote host: - -@lisp -(add-to-list 'tramp-remote-process-environment - (format "DISPLAY=%s" (getenv "DISPLAY"))) -@end lisp - -@noindent -@code{(getenv "DISPLAY")} shall return a string containing a host -name, which can be interpreted on the remote host; otherwise you might -use a fixed host name. Strings like @code{:0} cannot be used properly -on the remote host. - -Another trick might be that you put @code{ForwardX11 yes} or -@code{ForwardX11Trusted yes} to your @file{~/.ssh/config} file for -that host. - - -@subsection Running @code{shell} on a remote host -@cindex shell - -Calling @kbd{M-x shell} in a buffer related to a remote host runs the -local shell as defined in @option{shell-file-name}. This might be -also a valid file name for a shell to be applied on the remote host, -but it will fail at least when your local and remote hosts belong to -different system types, like @samp{windows-nt} and @samp{gnu/linux}. - -You must set the variable @option{explicit-shell-file-name} to the -shell file name on the remote host, in order to start that shell on -the remote host. - -@ifset emacs -Starting with Emacs 24 this won't be necessary, if you call -@code{shell} interactively. You will be asked for the remote shell -file name, if you are on a remote buffer, and if -@option{explicit-shell-file-name} is equal to @code{nil}. -@end ifset - - -@subsection Running @code{shell-command} on a remote host -@cindex shell-command - -@code{shell-command} allows to execute commands in a shell, either -synchronously, either asynchronously. This works also on remote -hosts. Example: - -@example -@kbd{C-x C-f @trampfn{sudo, , , } @key{RET}} -@kbd{M-! tail -f /var/log/syslog.log & @key{RET}} -@end example - -You will see the buffer @file{*Async Shell Command*}, containing the -continuous output of the @command{tail} command. - -@ifset emacs -A similar behavior can be reached by @kbd{M-x auto-revert-tail-mode}, -if available. -@end ifset - - -@subsection Running @code{eshell} on a remote host -@cindex eshell - -@value{tramp} is integrated into @file{eshell.el}. That is, you can -open an interactive shell on your remote host, and run commands there. -After you have started @kbd{M-x eshell}, you could perform commands -like this: - -@example -@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET} -@b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET} -host -@b{@trampfn{sudo, root, host, /etc} $} id @key{RET} -uid=0(root) gid=0(root) groups=0(root) -@b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET} -# -@b{@trampfn{sudo, root, host, /etc} $} -@end example - -@ifset emacs -Since @value{emacsname} 23.2, @code{eshell} has also an own -implementation of the @code{su} and @code{sudo} commands. Both -commands change the default directory of the @file{*eshell*} buffer to -the value related to the user the command has switched to. This works -even on remote hosts, adding silently a corresponding entry to the -variable @code{tramp-default-proxies-alist} (@pxref{Multi-hops}): - -@example -@b{~ $} cd @trampfn{ssh, user, remotehost, /etc} @key{RET} -@b{@trampfn{ssh, user, remotehost, /etc} $} find-file shadow @key{RET} -File is not readable: @trampfn{ssh, user, remotehost, /etc/shadow} -@b{@trampfn{ssh, user, remotehost, /etc} $} sudo find-file shadow @key{RET} -# - -@b{@trampfn{ssh, user, remotehost, /etc} $} su - @key{RET} -@b{@trampfn{su, root, remotehost, /root} $} id @key{RET} -uid=0(root) gid=0(root) groups=0(root) -@b{@trampfn{su, root, remotehost, /root} $} -@end example -@end ifset - - -@anchor{Running a debugger on a remote host} -@subsection Running a debugger on a remote host -@cindex gud -@cindex gdb -@cindex perldb - -@file{gud.el} offers an unified interface to several symbolic -debuggers -@ifset emacs -@ifinfo -(@ref{Debuggers, , , @value{emacsdir}}). -@end ifinfo -@end ifset -With @value{tramp}, it is possible to debug programs on -remote hosts. You can call @code{gdb} with a remote file name: - -@example -@kbd{M-x gdb @key{RET}} -@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET} -@end example - -The file name can also be relative to a remote default directory. -Given you are in a buffer that belongs to the remote directory -@trampfn{ssh, , host, /home/user}, you could call - -@example -@kbd{M-x perldb @key{RET}} -@b{Run perldb (like this):} perl -d myprog.pl @key{RET} -@end example - -It is not possible to use just the absolute local part of a remote -file name as program to debug, like @kbd{perl -d -/home/user/myprog.pl}, though. - -Arguments of the program to be debugged are taken literally. That -means, file names as arguments must be given as ordinary relative or -absolute file names, without any remote specification. - - -@subsection Running remote processes on Windows hosts -@cindex winexe -@cindex powershell - -With the help of the @command{winexe} it is possible tu run processes -on a remote Windows host. @value{tramp} has implemented this for -@code{process-file} and @code{start-file-process}. - -The variable @code{tramp-smb-winexe-program} must contain the file -name of your local @command{winexe} command. On the remote host, -Powershell V2.0 must be installed; it is used to run the remote -process. - -In order to open a remote shell on the Windows host via @kbd{M-x -shell}, you must set the variables @option{explicit-shell-file-name} -and @option{explicit-*-args}. If you want, for example, run -@command{cmd}, you must set: - -@lisp -(setq explicit-shell-file-name "cmd" - explicit-cmd-args '("/q")) -@end lisp - -@noindent -In case of running @command{powershell} as remote shell, the settings are - -@lisp -(setq explicit-shell-file-name "powershell" - explicit-powershell-args '("-file" "-")) -@end lisp - - -@node Cleanup remote connections -@section Cleanup remote connections -@cindex cleanup - -Sometimes it is useful to cleanup remote connections. The following -commands support this. - -@deffn Command tramp-cleanup-connection vec -This command flushes all connection related objects. @option{vec} is -the internal representation of a remote connection. Called -interactively, the command offers all active remote connections in the -minibuffer as remote file name prefix like @file{@trampfn{method, -user, host, }}. The cleanup includes password cache (@pxref{Password -handling}), file cache, connection cache (@pxref{Connection caching}), -connection buffers. -@end deffn - -@deffn Command tramp-cleanup-this-connection -This command flushes all objects of the current buffer's remote -connection. The same objects are removed as in -@code{tramp-cleanup-connection}. -@end deffn - -@deffn Command tramp-cleanup-all-connections -This command flushes objects for all active remote connections. The -same objects are removed as in @code{tramp-cleanup-connection}. -@end deffn - -@deffn Command tramp-cleanup-all-buffers -Like in @code{tramp-cleanup-all-connections}, all remote connections -are cleaned up. Additionally all buffers, which are related to a -remote connection, are killed. -@end deffn - - -@node Bug Reports -@chapter Reporting Bugs and Problems -@cindex bug reports - -Bugs and problems with @value{tramp} are actively worked on by the -development team. Feature requests and suggestions are also more than -welcome. - -The @value{tramp} mailing list is a great place to get information on -working with @value{tramp}, solving problems and general discussion -and advice on topics relating to the package. It is moderated so -non-subscribers can post but messages will be delayed, possibly up to -48 hours (or longer in case of holidays), until the moderator approves -your message. - -The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to -this address go to all the subscribers. This is @emph{not} the address -to send subscription requests to. - -Subscribing to the list is performed via -@uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/, -the @value{tramp} Mail Subscription Page}. - -@ifset emacs -@ifset installchapter -Before sending a bug report, you could check whether @value{tramp} -works at all. Run the test suite on your local host, @ref{Testing}. -@end ifset -@end ifset - -@findex tramp-bug -To report a bug in @value{tramp}, you should execute @kbd{M-x -tramp-bug}. This will automatically generate a buffer with the details -of your system and @value{tramp} version. - -When submitting a bug report, please try to describe in excruciating -detail the steps required to reproduce the problem, the setup of the -remote host and any special conditions that exist. You should also -check that your problem is not described already in @xref{Frequently -Asked Questions}. - -If you can identify a minimal test case that reproduces the problem, -include that with your bug report. This will make it much easier for -the development team to analyze and correct the problem. - -Sometimes, there might be also problems due to Tramp caches. Flush -all caches before running the test, @ref{Cleanup remote connections}. - -Before reporting the bug, you should set the verbosity level to 6 -(@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and -repeat the bug. Then, include the contents of the @file{*tramp/foo*} -and @file{*debug tramp/foo*} buffers in your bug report. A verbosity -level greater than 6 will produce a very huge debug buffer, which is -mostly not necessary for the analysis. - -Please be aware that, with a verbosity level of 6 or greater, the -contents of files and directories will be included in the debug -buffer. Passwords you've typed will never be included there. - - -@node Frequently Asked Questions -@chapter Frequently Asked Questions -@cindex frequently asked questions -@cindex FAQ - -@itemize @bullet -@item -Where can I get the latest @value{tramp}? - -@value{tramp} is available under the URL below. - -@noindent -@uref{ftp://ftp.gnu.org/gnu/tramp/} - -@noindent -There is also a Savannah project page. - -@noindent -@uref{http://savannah.gnu.org/projects/tramp/} - - -@item -Which systems does it work on? - -The package has been used successfully on Emacs 22, Emacs 23, Emacs -24, XEmacs 21 (starting with 21.4), and SXEmacs 22. - -The package was intended to work on Unix, and it really expects a -Unix-like system on the remote end (except the @option{smb} method), -but some people seemed to have some success getting it to work on MS -Windows XP/Vista/7 @value{emacsname}. - - -@item -How could I speed up @value{tramp}? - -In the backstage, @value{tramp} needs a lot of operations on the -remote host. The time for transferring data from and to the remote -host as well as the time needed to perform the operations there count. -In order to speed up @value{tramp}, one could either try to avoid some -of the operations, or one could try to improve their performance. - -Use an external method, like @option{scp}. - -Use caching. This is already enabled by default. Information about -the remote host as well as the remote files are cached for reuse. The -information about remote hosts is kept in the file specified in -@code{tramp-persistency-file-name}. Keep this file. If you are -confident that files on remote hosts are not changed out of -@value{emacsname}' control, set @code{remote-file-name-inhibit-cache} -to @code{nil}. Set also @code{tramp-completion-reread-directory-timeout} -to @code{nil}, @ref{File name completion}. - -Disable version control. If you access remote files which are not -under version control, a lot of check operations can be avoided by -disabling VC@. This can be achieved by - -@lisp -(setq vc-ignore-dir-regexp - (format "\\(%s\\)\\|\\(%s\\)" - vc-ignore-dir-regexp - tramp-file-name-regexp)) -@end lisp - -Disable excessive traces. The default trace level of @value{tramp}, -defined in the variable @code{tramp-verbose}, is 3. You should -increase this level only temporarily, hunting bugs. - - -@item -@value{tramp} does not connect to the remote host - -When @value{tramp} does not connect to the remote host, there are three -reasons heading the bug mailing list: - -@itemize @minus -@item -Unknown characters in the prompt - -@value{tramp} needs to recognize the prompt on the remote host -after execution any command. This is not possible when the prompt -contains unknown characters like escape sequences for coloring. This -should be avoided on the remote side. @xref{Remote shell setup}. for -setting the regular expression detecting the prompt. - -You can check your settings after an unsuccessful connection by -switching to the @value{tramp} connection buffer @file{*tramp/foo*}, -setting the cursor at the top of the buffer, and applying the expression - -@example -@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))} -@end example - -If it fails, or the cursor is not moved at the end of the buffer, your -prompt is not recognized correctly. - -A special problem is the zsh shell, which uses left-hand side and -right-hand side prompts in parallel. Therefore, it is necessary to -disable the zsh line editor on the remote host. You shall add to -@file{~/.zshrc} the following command: - -@example -[ $TERM = "dumb" ] && unsetopt zle && PS1='$ ' -@end example - -Similar fancy prompt settings are known from the fish shell. Here you -must add in @file{~/.config/fish/config.fish}: - -@example -function fish_prompt - if test $TERM = "dumb" - echo "\$ " - else - @dots{} - end -end -@end example - -Furthermore it has been reported, that @value{tramp} (like sshfs, -incidentally) doesn't work with WinSSHD due to strange prompt settings. - -@item -Echoed characters after login - -When the remote host opens an echoing shell, there might be control -characters in the welcome message. @value{tramp} tries to suppress -such echoes via the @command{stty -echo} command, but sometimes this -command is not reached, because the echoed output has confused -@value{tramp} already. In such situations it might be helpful to use -the @option{sshx} or @option{scpx} methods, which allocate a pseudo tty. -@xref{Inline methods}. - -@item -@value{tramp} doesn't transfer strings with more than 500 characters -correctly - -On some few systems, the implementation of @code{process-send-string} -seems to be broken for longer strings. It is reported for HP-UX, -FreeBSD and Tru64 Unix, for example. This case, you should customize -the variable @code{tramp-chunksize} to 500. For a description how to -determine whether this is necessary see the documentation of -@code{tramp-chunksize}. - -Additionally, it will be useful to set @code{file-precious-flag} to -@code{t} for @value{tramp} files. Then the file contents will be -written into a temporary file first, which is checked for correct -checksum. -@ifinfo -@pxref{Saving Buffers, , , elisp} -@end ifinfo - -@lisp -(add-hook - 'find-file-hook - (lambda () - (when (file-remote-p default-directory) - (set (make-local-variable 'file-precious-flag) t)))) -@end lisp -@end itemize - - -@item -@value{tramp} does not recognize hung @command{ssh} sessions - -When your network connection is down, @command{ssh} sessions might -hang. @value{tramp} cannot detect it safely, because it still sees a -running @command{ssh} process. Timeouts cannot be used as well, -because it cannot be predicted how long a remote command will last, -for example when copying very large files. - -Therefore, you must configure the @command{ssh} process to die -in such a case. The following entry in @file{~/.ssh/config} would do -the job: - -@example -Host * - ServerAliveInterval 5 -@end example - - -@item -@value{tramp} does not use my @command{ssh} @code{ControlPath} - -Your @code{ControlPath} setting will be overwritten by @command{ssh} -sessions initiated by @value{tramp}. This is because a master -session, initiated outside @value{emacsname}, could be closed, which -would stall all other @command{ssh} sessions for that host inside -@value{emacsname}. - -Consequently, if you connect to a remote host via @value{tramp}, you -might be prompted for a password again, even if you have established -already an @command{ssh} connection to that host. Further -@value{tramp} connections to that host, for example in order to run a -process on that host, will reuse that initial @command{ssh} -connection. - -If your @command{ssh} version supports the @code{ControlPersist} -option, you could customize the variable -@code{tramp-ssh-controlmaster-options} to use your @code{ControlPath}, -for example: - -@lisp -(setq tramp-ssh-controlmaster-options - (concat - "-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p " - "-o ControlMaster=auto -o ControlPersist=yes")) -@end lisp - -Note, that "%r", "%h" and "%p" must be encoded as "%%r", "%%h" and -"%%p", respectively. - -These settings can be suppressed, if they are configured properly in -your @file{~/.ssh/config}: - -@lisp -(setq tramp-use-ssh-controlmaster-options nil) -@end lisp - - -@item -File name completion does not work with @value{tramp} - -When you log in to the remote host, do you see the output of -@command{ls} in color? If so, this may be the cause of your problems. - -@command{ls} outputs @acronym{ANSI} escape sequences that your terminal -emulator interprets to set the colors. These escape sequences will -confuse @value{tramp} however. - -In your @file{.bashrc}, @file{.profile} or equivalent on the remote -host you probably have an alias configured that adds the option -@option{--color=yes} or @option{--color=auto}. - -You should remove that alias and ensure that a new login @emph{does not} -display the output of @command{ls} in color. If you still cannot use -file name completion, report a bug to the @value{tramp} developers. - - -@item -File name completion does not work in large directories - -@value{tramp} uses globbing for some operations. (Globbing means to use the -shell to expand wildcards such as `*.c'.) This might create long -command lines, especially in directories with many files. Some shells -choke on long command lines, or don't cope well with the globbing -itself. - -If you have a large directory on the remote end, you may wish to execute -a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs. -Note that you must first start the right shell, which might be -@command{/bin/sh}, @command{ksh} or @command{bash}, depending on which -of those supports tilde expansion. - - -@item -How can I get notified when @value{tramp} file transfers are complete? - -The following snippet can be put in your @file{~/.emacs} file. It -makes @value{emacsname} beep after reading from or writing to the -remote host. - -@lisp -(defadvice tramp-handle-write-region - (after tramp-write-beep-advice activate) - "Make tramp beep after writing a file." - (interactive) - (beep)) - -(defadvice tramp-handle-do-copy-or-rename-file - (after tramp-copy-beep-advice activate) - "Make tramp beep after copying a file." - (interactive) - (beep)) - -(defadvice tramp-handle-insert-file-contents - (after tramp-insert-beep-advice activate) - "Make tramp beep after inserting a file." - (interactive) - (beep)) -@end lisp - - -@ifset emacs -@item -I'ld like to get a Visual Warning when working in a sudo:ed context - -When you are working with @samp{root} privileges, it might be useful -to get an indication in the buffer's modeline. The following code, -tested with @value{emacsname} 22.1, does the job. You should put it -into your @file{~/.emacs}: - -@lisp -(defun my-mode-line-function () - (when (string-match "^/su\\(do\\)?:" default-directory) - (setq mode-line-format - (format-mode-line mode-line-format 'font-lock-warning-face)))) - -(add-hook 'find-file-hook 'my-mode-line-function) -(add-hook 'dired-mode-hook 'my-mode-line-function) -@end lisp -@end ifset - - -@ifset emacs -@item -I'ld like to see a host indication in the mode line when I'm remote - -The following code has been tested with @value{emacsname} 22.1. You -should put it into your @file{~/.emacs}: - -@lisp -(defconst my-mode-line-buffer-identification - (list - '(:eval - (let ((host-name - (if (file-remote-p default-directory) - (tramp-file-name-host - (tramp-dissect-file-name default-directory)) - (system-name)))) - (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) - (substring host-name 0 (match-beginning 1)) - host-name))) - ": %12b")) - -(setq-default - mode-line-buffer-identification - my-mode-line-buffer-identification) - -(add-hook - 'dired-mode-hook - (lambda () - (setq - mode-line-buffer-identification - my-mode-line-buffer-identification))) -@end lisp - -Since @value{emacsname} 23.1, the mode line contains an indication if -@code{default-directory} for the current buffer is on a remote host. -The corresponding tooltip includes the name of that host. If you -still want the host name as part of the mode line, you can use the -example above, but the @code{:eval} clause can be simplified: - -@lisp - '(:eval - (let ((host-name - (or (file-remote-p default-directory 'host) - (system-name)))) - (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) - (substring host-name 0 (match-beginning 1)) - host-name))) -@end lisp -@end ifset - - -@ifset emacs -@item -My remote host does not understand default directory listing options - -@value{emacsname} computes the @command{dired} options depending on -the local host you are working. If your @command{ls} command on the -remote host does not understand those options, you can change them -like this: - -@lisp -(add-hook - 'dired-before-readin-hook - (lambda () - (when (file-remote-p default-directory) - (setq dired-actual-switches "-al")))) -@end lisp -@end ifset - - -@item -There's this @file{~/.sh_history} file on the remote host which keeps -growing and growing. What's that? - -Sometimes, @value{tramp} starts @command{ksh} on the remote host for -tilde expansion. Maybe @command{ksh} saves the history by default. -@value{tramp} tries to turn off saving the history, but maybe you have -to help. For example, you could put this in your @file{.kshrc}: - -@example -if [ -f $HOME/.sh_history ] ; then - /bin/rm $HOME/.sh_history -fi -if [ "$@{HISTFILE-unset@}" != "unset" ] ; then - unset HISTFILE -fi -if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then - unset HISTSIZE -fi -@end example - -Furthermore, if you use an @option{ssh}-based method, you could add -the following line to your @file{~/.ssh/environment} file: - -@example -HISTFILE=/dev/null -@end example - - -@item There are longish file names to type. How to shorten this? - -Let's say you need regularly access to @file{@trampfn{ssh, news, -news.my.domain, /opt/news/etc}}, which is boring to type again and -again. The following approaches can be mixed: - -@enumerate - -@item Use default values for method and user name: - -You can define default methods and user names for hosts, -(@pxref{Default Method}, @pxref{Default User}): - -@lisp -(setq tramp-default-method "ssh" - tramp-default-user "news") -@end lisp - -The file name left to type would be -@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}. - -Note that there are some useful settings already. Accessing your -local host as @samp{root} user, is possible just by @kbd{C-x C-f -@trampfn{su, , ,}}. - -@item Use configuration possibilities of your method: - -Several connection methods (i.e., the programs used) offer powerful -configuration possibilities (@pxref{Customizing Completion}). In the -given case, this could be @file{~/.ssh/config}: - -@example -Host xy - HostName news.my.domain - User news -@end example - -The file name left to type would be @kbd{C-x C-f @trampfn{ssh, , xy, -/opt/news/etc}}. Depending on files in your directories, it is even -possible to complete the host name with @kbd{C-x C-f -@value{prefix}ssh@value{postfixhop}x @key{TAB}}. - -@item Use environment variables: - -File names typed in the minibuffer can be expanded by environment -variables. You can set them outside @value{emacsname}, or even with -Lisp: - -@lisp -(setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}") -@end lisp - -Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you -are. The disadvantage is that you cannot edit the file name, because -environment variables are not expanded during editing in the -minibuffer. - -@item Define own keys: - -You can define your own key sequences in @value{emacsname}, which can -be used instead of @kbd{C-x C-f}: - -@lisp -(global-set-key - [(control x) (control y)] - (lambda () - (interactive) - (find-file - (read-file-name - "Find Tramp file: " - "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))) -@end lisp - -Simply typing @kbd{C-x C-y} would initialize the minibuffer for -editing with your beloved file name. - -See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the -Emacs Wiki} for a more comprehensive example. - -@item Define own abbreviation (1): - -It is possible to define an own abbreviation list for expanding file -names: - -@lisp -(add-to-list - 'directory-abbrev-alist - '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")) -@end lisp - -This shortens the file opening command to @kbd{C-x C-f /xy -@key{RET}}. The disadvantage is, again, that you cannot edit the file -name, because the expansion happens after entering the file name only. - -@item Define own abbreviation (2): - -The @code{abbrev-mode} gives more flexibility for editing the -minibuffer: - -@lisp -(define-abbrev-table 'my-tramp-abbrev-table - '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))) - -(add-hook - 'minibuffer-setup-hook - (lambda () - (abbrev-mode 1) - (setq local-abbrev-table my-tramp-abbrev-table))) - -(defadvice minibuffer-complete - (before my-minibuffer-complete activate) - (expand-abbrev)) - -;; If you use partial-completion-mode -(defadvice PC-do-completion - (before my-PC-do-completion activate) - (expand-abbrev)) -@end lisp - -After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is -expanded, and you can continue editing. - -@item Use bookmarks: - -Bookmarks can be used to visit Tramp files or directories. -@ifinfo -@pxref{Bookmarks, , , @value{emacsdir}} -@end ifinfo - -When you have opened @file{@trampfn{ssh, news, news.my.domain, -/opt/news/etc/}}, you should save the bookmark via -@ifset emacs -@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}. -@end ifset - -Later on, you can always navigate to that bookmark via -@ifset emacs -@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}. -@end ifset - -@item Use recent files: - -@ifset emacs -@file{recentf} -@end ifset -@ifset xemacs -@file{recent-files} -@end ifset -remembers visited places. -@ifinfo -@ifset emacs -@pxref{File Conveniences, , , @value{emacsdir}} -@end ifset -@ifset xemacs -@pxref{recent-files, , , edit-utils} -@end ifset -@end ifinfo - -You could keep remote file names in the recent list without checking -their readability through a remote access: - -@lisp -@ifset emacs -(recentf-mode 1) -@end ifset -@ifset xemacs -(recent-files-initialize) -(add-hook - 'find-file-hook - (lambda () - (when (file-remote-p (buffer-file-name)) - (recent-files-make-permanent))) - 'append) -@end ifset -@end lisp - -The list of files opened recently is reachable via -@ifset emacs -@kbd{@key{menu-bar} @key{file} @key{Open Recent}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{Recent Files}}. -@end ifset - -@ifset emacs -@item Use filecache: - -@file{filecache} remembers visited places. Add the directory into -the cache: - -@lisp -(eval-after-load "filecache" - '(file-cache-add-directory - "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")) -@end lisp - -Whenever you want to load a file, you can enter @kbd{C-x C-f -C-@key{TAB}} in the minibuffer. The completion is done for the given -directory. -@end ifset - -@ifset emacs -@item Use bbdb: - -@file{bbdb} has a built-in feature for @value{ftppackagename} files, -which works also for @value{tramp}. -@ifinfo -@pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb} -@end ifinfo - -You need to load @file{bbdb}: - -@lisp -(require 'bbdb) -(bbdb-initialize) -@end lisp - -Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}. -Because BBDB is not prepared for @value{tramp} syntax, you must -specify a method together with the user name when needed. Example: - -@example -@kbd{M-x bbdb-create-ftp-site @key{RET}} -@b{Ftp Site:} news.my.domain @key{RET} -@b{Ftp Directory:} /opt/news/etc/ @key{RET} -@b{Ftp Username:} ssh@value{postfixhop}news @key{RET} -@b{Company:} @key{RET} -@b{Additional Comments:} @key{RET} -@end example - -When you have opened your BBDB buffer, you can access such an entry by -pressing the key @key{F}. -@end ifset - -@end enumerate - -I would like to thank all @value{tramp} users who have contributed to -the different recipes! - - -@ifset emacs -@item -How can I use @value{tramp} to connect to a remote @value{emacsname} -session? - -You can configure Emacs Client doing this. -@ifinfo -@xref{Emacs Server, , , @value{emacsdir}}. -@end ifinfo - -On the remote host, you start the Emacs Server: - -@lisp -(require 'server) -(setq server-host (system-name) - server-use-tcp t) -(server-start) -@end lisp - -Make sure that the result of @code{(system-name)} can be resolved on -your local host; otherwise you might use a hard coded IP address. - -The resulting file @file{~/.emacs.d/server/server} must be copied to -your local host, at the same location. You can call then the Emacs -Client from the command line: - -@example -emacsclient @trampfn{ssh, user, host, /file/to/edit} -@end example - -@code{user} and @code{host} shall be related to your local host. - -If you want to use Emacs Client also as editor for other programs, you -could write a script @file{emacsclient.sh}: - -@example -#!/bin/sh -emacsclient @trampfn{ssh, $(whoami), $(hostname --fqdn), $1} -@end example - -Then you must set the environment variable @env{EDITOR} pointing to -that script: - -@example -export EDITOR=/path/to/emacsclient.sh -@end example -@end ifset - - -@item -There are packages which call @value{tramp} although I haven't entered -a remote file name ever. I dislike it, how could I disable it? - -In general, @value{tramp} functions are used only when -you apply remote file name syntax. However, some packages enable -@value{tramp} on their own. - -@itemize @minus -@item -@file{ido.el} - -You could disable @value{tramp} file name completion: - -@lisp -(custom-set-variables - '(ido-enable-tramp-completion nil)) -@end lisp - -@item -@file{rlogin.el} - -You could disable remote directory tracking mode: - -@lisp -(rlogin-directory-tracking-mode -1) -@end lisp -@end itemize - - -@item -How can I disable @value{tramp} at all? - -Shame on you, why did you read until now? - -@itemize @minus -@ifset emacs -@item -If you just want to have @value{ftppackagename} as default remote -files access package, you should apply the following code: - -@lisp -(setq tramp-default-method "ftp") -@end lisp -@end ifset - -@item -In order to disable -@ifset emacs -@value{tramp} (and @value{ftppackagename}), -@end ifset -@ifset xemacs -@value{tramp}, -@end ifset -you must set @code{tramp-mode} to @code{nil}: - -@lisp -(setq tramp-mode nil) -@end lisp - -@item -Unloading @value{tramp} can be achieved by applying @kbd{M-x -tramp-unload-tramp}. -@ifset emacs -This resets also the @value{ftppackagename} plugins. -@end ifset -@end itemize -@end itemize - - -@c For the developer -@node Files directories and localnames -@chapter How file names, directories and localnames are mangled and managed. - -@menu -* Localname deconstruction:: Breaking a localname into its components. -@ifset emacs -* External packages:: Integration with external Lisp packages. -@end ifset -@end menu - - -@node Localname deconstruction -@section Breaking a localname into its components - -@value{tramp} file names are somewhat different, obviously, to ordinary file -names. As such, the lisp functions @code{file-name-directory} and -@code{file-name-nondirectory} are overridden within the @value{tramp} -package. - -Their replacements are reasonably simplistic in their approach. They -dissect the file name, call the original handler on the localname and -then rebuild the @value{tramp} file name with the result. - -This allows the platform specific hacks in the original handlers to take -effect while preserving the @value{tramp} file name information. - - -@ifset emacs -@node External packages -@section Integration with external Lisp packages -@subsection File name completion. - -While reading file names in the minibuffer, @value{tramp} must decide -whether it completes possible incomplete file names, or not. Imagine -there is the following situation: You have typed @kbd{C-x C-f -@value{prefix}ssh@value{postfixhop} @key{TAB}}. @value{tramp} cannot -know, whether @option{ssh} is a method or a host name. It checks -therefore the last input character you have typed. If this is -@key{TAB}, @key{SPACE} or @kbd{?}, @value{tramp} assumes that you are -still in file name completion, and it does not connect to the possible -remote host @option{ssh}. - -External packages, which use other characters for completing file names -in the minibuffer, must signal this to @value{tramp}. For this case, -the variable @code{non-essential} can be bound temporarily to -a non-@code{nil} value. - -@lisp -(let ((non-essential t)) - ...) -@end lisp - - -@subsection File attributes cache. - -When @value{tramp} runs remote processes, files on the remote host -could change their attributes. Consequently, @value{tramp} must flush -its complete cache keeping attributes for all files of the remote host -it has seen so far. - -This is a performance degradation, because the lost file attributes -must be recomputed when needed again. In cases where the caller of -@code{process-file} knows that there are no file attribute changes, it -should let-bind the variable @code{process-file-side-effects} to -@code{nil}. Then @value{tramp} won't flush the file attributes cache. - -@lisp -(let (process-file-side-effects) - ...) -@end lisp - -For asynchronous processes, @value{tramp} flushes the file attributes -cache via a process sentinel. If the caller of -@code{start-file-process} knows that there are no file attribute -changes, it should set the process sentinel to the default. In cases -where the caller defines its own process sentinel, @value{tramp}'s process -sentinel is overwritten. The caller can still flush the file -attributes cache in its process sentinel with this code: - -@lisp -(unless (memq (process-status proc) '(run open)) - (dired-uncache remote-directory)) -@end lisp - -@code{remote-directory} shall be the root directory, where file -attribute changes can happen during the process lifetime. -@value{tramp} traverses all subdirectories, starting at this -directory. Often, it is sufficient to use @code{default-directory} of -the process buffer as root directory. -@end ifset - - -@node Traces and Profiles -@chapter How to Customize Traces - -All @value{tramp} messages are raised with a verbosity level. The -verbosity level can be any number between 0 and 10. Only messages with -a verbosity level less than or equal to @code{tramp-verbose} are -displayed. - -The verbosity levels are - - @w{ 0} silent (no @value{tramp} messages at all) -@*@indent @w{ 1} errors -@*@indent @w{ 2} warnings -@*@indent @w{ 3} connection to remote hosts (default verbosity) -@*@indent @w{ 4} activities -@*@indent @w{ 5} internal -@*@indent @w{ 6} sent and received strings -@*@indent @w{ 7} file caching -@*@indent @w{ 8} connection properties -@*@indent @w{ 9} test commands -@*@indent @w{10} traces (huge) - -When @code{tramp-verbose} is greater than or equal to 4, the messages -are also written into a @value{tramp} debug buffer. This debug buffer -is useful for analyzing problems; sending a @value{tramp} bug report -should be done with @code{tramp-verbose} set to a verbosity level of at -least 6 (@pxref{Bug Reports}). - -The debug buffer is in -@ifinfo -@ref{Outline Mode, , , @value{emacsdir}}. -@end ifinfo -@ifnotinfo -Outline Mode. -@end ifnotinfo -That means, you can change the level of messages to be viewed. If you -want, for example, see only messages up to verbosity level 5, you must -enter @kbd{C-u 6 C-c C-q}. -@ifinfo -Other keys for navigating are described in -@ref{Outline Visibility, , , @value{emacsdir}}. -@end ifinfo - -@value{tramp} errors are handled internally in order to raise the -verbosity level 1 messages. When you want to get a Lisp backtrace in -case of an error, you need to set both - -@lisp -(setq debug-on-error t - debug-on-signal t) -@end lisp - -Sometimes, it might be even necessary to step through @value{tramp} -function call traces. Such traces are enabled by the following code: - -@lisp -(require 'tramp) -(require 'trace) -(dolist (elt (all-completions "tramp-" obarray 'functionp)) - (trace-function-background (intern elt))) -(untrace-function 'tramp-read-passwd) -(untrace-function 'tramp-gw-basic-authentication) -@end lisp - -The function call traces are inserted in the buffer -@file{*trace-output*}. @code{tramp-read-passwd} and -@code{tramp-gw-basic-authentication} shall be disabled when the -function call traces are added to @value{tramp}, because both -functions return password strings, which should not be distributed. - - -@node Issues -@chapter Debatable Issues and What Was Decided - -@itemize @bullet -@item The uuencode method does not always work. - -Due to the design of @value{tramp}, the encoding and decoding programs -need to read from stdin and write to stdout. On some systems, -@command{uudecode -o -} will read stdin and write the decoded file to -stdout, on other systems @command{uudecode -p} does the same thing. -But some systems have uudecode implementations which cannot do this at -all---it is not possible to call these uudecode implementations with -suitable parameters so that they write to stdout. - -Of course, this could be circumvented: the @code{begin foo 644} line -could be rewritten to put in some temporary file name, then -@command{uudecode} could be called, then the temp file could be -printed and deleted. - -But I have decided that this is too fragile to reliably work, so on some -systems you'll have to do without the uuencode methods. - -@item The @value{tramp} file name syntax differs between Emacs and XEmacs. - -The Emacs maintainers wish to use a unified file name syntax for -Ange-FTP and @value{tramp} so that users don't have to learn a new -syntax. It is sufficient to learn some extensions to the old syntax. - -For the XEmacs maintainers, the problems caused from using a unified -file name syntax are greater than the gains. The XEmacs package system -uses EFS for downloading new packages. So, obviously, EFS has to be -installed from the start. If the file names were unified, @value{tramp} -would have to be installed from the start, too. - -@ifset xemacs -@strong{Note:} If you'd like to use a similar syntax like -@value{ftppackagename}, you need the following settings in your init -file: - -@lisp -(setq tramp-unified-filenames t) -(require 'tramp) -@end lisp - -The autoload of the @value{emacsname} @value{tramp} package must be -disabled. This can be achieved by setting file permissions @code{000} -to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}. - -In case of unified file names, all @value{emacsname} download sites are -added to @code{tramp-default-method-alist} with default method -@option{ftp} @xref{Default Method}. These settings shouldn't be -touched for proper working of the @value{emacsname} package system. - -The syntax for unified file names is described in the @value{tramp} manual -for @value{emacsothername}. -@end ifset -@end itemize - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Function Index -@unnumbered Function Index -@printindex fn - - -@node Variable Index -@unnumbered Variable Index -@printindex vr - - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@bye - -@c TODO -@c -@c * Say something about the .login and .profile files of the remote -@c shells. -@c * Explain how tramp.el works in principle: open a shell on a remote -@c host and then send commands to it. -@c * Consistent small or capitalized words especially in menus. -@c * Make a unique declaration of @trampfn. diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi deleted file mode 100644 index 3b66239f284..00000000000 --- a/doc/misc/trampver.texi +++ /dev/null @@ -1,69 +0,0 @@ -@c -*-texinfo-*- -@c texi/trampver.texi. Generated from trampver.texi.in by configure. - -@c This is part of the Emacs manual. -@c Copyright (C) 2003-2014 Free Software Foundation, Inc. -@c See file doclicense.texi for copying conditions. - -@c In the Tramp CVS, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. -@set trampver 2.2.9-24.4 - -@c Other flags from configuration -@set instprefix /usr/local -@set lispdir /usr/local/share/emacs/site-lisp -@set infodir /usr/local/share/info - -@c Formatting of the tramp program name consistent. -@set tramp @sc{tramp} - -@c Whether or not describe GVFS integration. -@ifclear noemacsgvfs -@set emacsgvfs -@end ifclear - -@c Whether or not describe gateway methods. -@ifclear noemacsgw -@set emacsgw -@end ifclear - -@c Some flags which make the text independent on the (X)Emacs flavor. -@c "emacs" resp "xemacs" are set in the Makefile. Default is "emacs". -@ifclear emacs -@ifclear xemacs -@set emacs -@end ifclear -@end ifclear - -@c Emacs values. -@ifset emacs -@set emacsname Emacs -@set emacsdir emacs -@set ftppackagename Ange-FTP -@set prefix / -@set prefixhop -@set postfix : -@set postfixhop : -@set ipv6prefix [ -@set ipv6postfix ] -@set emacsothername XEmacs -@set emacsotherdir xemacs -@set emacsotherfilename tramp-xemacs.html -@end ifset - -@c XEmacs counterparts. -@ifset xemacs -@set emacsname XEmacs -@set emacsdir xemacs -@set ftppackagename EFS -@set prefix /[ -@set prefixhop [ -@set postfix ] -@set postfixhop / -@set ipv6prefix -@set ipv6postfix -@set emacsothername Emacs -@set emacsotherdir emacs -@set emacsotherfilename tramp-emacs.html -@end ifset diff --git a/doc/misc/url.texi b/doc/misc/url.texi deleted file mode 100644 index 765d97d5980..00000000000 --- a/doc/misc/url.texi +++ /dev/null @@ -1,1316 +0,0 @@ -\input texinfo -@setfilename ../../info/url -@settitle URL Programmer's Manual - -@documentencoding UTF-8 - -@iftex -@c @finalout -@end iftex -@c @setchapternewpage odd -@c @smallbook - -@tex -\overfullrule=0pt -%\global\baselineskip 30pt % for printing in double space -@end tex -@dircategory Emacs lisp libraries -@direntry -* URL: (url). URL loading package. -@end direntry - -@copying -This is the manual for the @code{url} Emacs Lisp library. - -Copyright @copyright{} 1993--1999, 2002, 2004--2014 Free Software -Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@c -@titlepage -@title URL Programmer's Manual -@subtitle First Edition, URL Version 2.0 -@author William M. Perry @email{wmperry@@gnu.org} -@author David Love @email{fx@@gnu.org} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top URL - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Introduction:: About the @code{url} library. -* URI Parsing:: Parsing (and unparsing) URIs. -* Retrieving URLs:: How to use this package to retrieve a URL. -* Supported URL Types:: Descriptions of URL types currently supported. -* General Facilities:: URLs can be cached, accessed via a gateway - and tracked in a history list. -* Customization:: Variables you can alter. -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -* Variable Index:: -* Concept Index:: -@end menu - -@node Introduction -@chapter Introduction -@cindex URL -@cindex URI -@cindex uniform resource identifier -@cindex uniform resource locator - -A @dfn{Uniform Resource Identifier} (URI) is a specially-formatted -name, such as an Internet address, that identifies some name or -resource. The format of URIs is described in RFC 3986, which updates -and replaces the earlier RFCs 2732, 2396, 1808, and 1738. A -@dfn{Uniform Resource Locator} (URL) is an older but still-common -term, which basically refers to a URI corresponding to a resource that -can be accessed (usually over a network) in a specific way. - - Here are some examples of URIs (taken from RFC 3986): - -@example -ftp://ftp.is.co.za/rfc/rfc1808.txt -http://www.ietf.org/rfc/rfc2396.txt -ldap://[2001:db8::7]/c=GB?objectClass?one -mailto:John.Doe@@example.com -news:comp.infosystems.www.servers.unix -tel:+1-816-555-1212 -telnet://192.0.2.16:80/ -urn:oasis:names:specification:docbook:dtd:xml:4.1.2 -@end example - - This manual describes the @code{url} library, an Emacs Lisp library -for parsing URIs and retrieving the resources to which they refer. -(The library is so-named for historical reasons; nowadays, the ``URI'' -terminology is regarded as the more general one, and ``URL'' is -technically obsolete despite its widespread vernacular usage.) - -@node URI Parsing -@chapter URI Parsing - - A URI consists of several @dfn{components}, each having a different -meaning. For example, the URI - -@example -http://www.gnu.org/software/emacs/ -@end example - -@noindent -specifies the scheme component @samp{http}, the hostname component -@samp{www.gnu.org}, and the path component @samp{/software/emacs/}. - -@cindex parsed URIs - The format of URIs is specified by RFC 3986. The @code{url} library -provides the Lisp function @code{url-generic-parse-url}, a (mostly) -standard-compliant URI parser, as well as function -@code{url-recreate-url}, which converts a parsed URI back into a URI -string. - -@defun url-generic-parse-url uri-string -This function returns a parsed version of the string @var{uri-string}. -@end defun - -@defun url-recreate-url uri-obj -@cindex unparsing URLs -Given a parsed URI, this function returns the corresponding URI string. -@end defun - -@cindex parsed URI - The return value of @code{url-generic-parse-url}, and the argument -expected by @code{url-recreate-url}, is a @dfn{parsed URI}: a CL -structure whose slots hold the various components of the URI@. -@xref{Top,the CL Manual,,cl,GNU Emacs Common Lisp Emulation}, for -details about CL structures. Most of the other functions in the -@code{url} library act on parsed URIs. - -@menu -* Parsed URIs:: Format of parsed URI structures. -* URI Encoding:: Non-@acronym{ASCII} characters in URIs. -@end menu - -@node Parsed URIs -@section Parsed URI structures - - Each parsed URI structure contains the following slots: - -@table @code -@item type -The URI scheme (a string, e.g., @code{http}). @xref{Supported URL -Types}, for a list of schemes that the @code{url} library knows how to -process. This slot can also be @code{nil}, if the URI is not fully -specified. - -@item user -The user name (a string), or @code{nil}. - -@item password -The user password (a string), or @code{nil}. The use of this URI -component is strongly discouraged; nowadays, passwords are transmitted -by other means, not as part of a URI. - -@item host -The host name (a string), or @code{nil}. If present, this is -typically a domain name or IP address. - -@item port -The port number (an integer), or @code{nil}. Omitting this component -usually means to use the ``standard'' port associated with the URI -scheme. - -@item filename -The combination of the ``path'' and ``query'' components of the URI (a -string), or @code{nil}. If the query component is present, it is the -substring following the first @samp{?} character, and the path -component is the substring before the @samp{?}. The meaning of these -components is scheme-dependent; they do not necessarily refer to a -file on a disk. - -@item target -The fragment component (a string), or @code{nil}. The fragment -component specifies a ``secondary resource'', such as a section of a -webpage. - -@item fullness -This is @code{t} if the URI is fully specified, i.e., the -hierarchical components of the URI (the hostname and/or username -and/or password) are preceded by @samp{//}. -@end table - -@findex url-type -@findex url-user -@findex url-password -@findex url-host -@findex url-port -@findex url-filename -@findex url-target -@findex url-attributes -@findex url-fullness -These slots have accessors named @code{url-@var{part}}, where -@var{part} is the slot name. For example, the accessor for the -@code{host} slot is the function @code{url-host}. The @code{url-port} -accessor returns the default port for the URI scheme if the parsed -URI's @var{port} slot is @code{nil}. - - The slots can be set using @code{setf}. For example: - -@example -(setf (url-port url) 80) -@end example - -@node URI Encoding -@section URI Encoding - -@cindex percent encoding - The @code{url-generic-parse-url} parser does not obey RFC 3986 in -one respect: it allows non-@acronym{ASCII} characters in URI strings. - - Strictly speaking, RFC 3986 compatible URIs may only consist of -@acronym{ASCII} characters; non-@acronym{ASCII} characters are -represented by converting them to UTF-8 byte sequences, and performing -@dfn{percent encoding} on the bytes. For example, the o-umlaut -character is converted to the UTF-8 byte sequence @samp{\xD3\xA7}, -then percent encoded to @samp{%D3%A7}. (Certain ``reserved'' -@acronym{ASCII} characters must also be percent encoded when they -appear in URI components.) - - The function @code{url-encode-url} can be used to convert a URI -string containing arbitrary characters to one that is properly -percent-encoded in accordance with RFC 3986. - -@defun url-encode-url url-string -This function return a properly URI-encoded version of -@var{url-string}. It also performs @dfn{URI normalization}, -e.g., converting the scheme component to lowercase if it was -previously uppercase. -@end defun - - To convert between a string containing arbitrary characters and a -percent-encoded all-@acronym{ASCII} string, use the functions -@code{url-hexify-string} and @code{url-unhex-string}: - -@defun url-hexify-string string &optional allowed-chars -This function performs percent-encoding on @var{string}, and returns -the result. - -If @var{string} is multibyte, it is first converted to a UTF-8 byte -string. Each byte corresponding to an allowed character is left -as-is, while all other bytes are converted to a three-character -sequence: @samp{%} followed by two upper-case hex digits. - -@vindex url-unreserved-chars -@cindex unreserved characters -The allowed characters are specified by @var{allowed-chars}. If this -argument is @code{nil}, the allowed characters are those specified as -@dfn{unreserved characters} by RFC 3986 (see the variable -@code{url-unreserved-chars}). Otherwise, @var{allowed-chars} should -be a vector whose @var{n}-th element is non-@code{nil} if character -@var{n} is allowed. -@end defun - -@defun url-unhex-string string &optional allow-newlines -This function replaces percent-encoding sequences in @var{string} with -their character equivalents, and returns the resulting string. - -If @var{allow-newlines} is non-@code{nil}, it allows the decoding of -carriage returns and line feeds, which are normally forbidden in URIs. -@end defun - -@node Retrieving URLs -@chapter Retrieving URLs - - The @code{url} library defines the following three functions for -retrieving the data specified by a URL@. The actual retrieval protocol -depends on the URL's URI scheme, and is performed by lower-level -scheme-specific functions. (Those lower-level functions are not -documented here, and generally should not be called directly.) - - In each of these functions, the @var{url} argument can be either a -string or a parsed URL structure. If it is a string, that string is -passed through @code{url-encode-url} before using it, to ensure that -it is properly URI-encoded (@pxref{URI Encoding}). - -@defun url-retrieve-synchronously url -This function synchronously retrieves the data specified by @var{url}, -and returns a buffer containing the data. The return value is -@code{nil} if there is no data associated with the URL (as is the case -for @code{dired}, @code{info}, and @code{mailto} URLs). -@end defun - -@defun url-retrieve url callback &optional cbargs silent no-cookies -This function retrieves @var{url} asynchronously, calling the function -@var{callback} when the object has been completely retrieved. The -return value is the buffer into which the data will be inserted, or -@code{nil} if the process has already completed. - -The callback function is called this way: - -@example -(apply @var{callback} @var{status} @var{cbargs}) -@end example - -@noindent -where @var{status} is a plist representing what happened during the -retrieval, with most recent events first, or an empty list if no -events have occurred. Each pair in the plist is one of: - -@table @code -@item (:redirect @var{redirected-to}) -This means that the request was redirected to the URL -@var{redirected-to}. - -@item (:error (@var{error-symbol} . @var{data})) -This means that an error occurred. If so desired, the error can be -signaled with @code{(signal @var{error-symbol} @var{data})}. -@end table - -When the callback function is called, the current buffer is the one -containing the retrieved data (if any). The buffer also contains any -MIME headers associated with the data retrieval. - -If the optional argument @var{silent} is non-@code{nil}, progress -messages are suppressed. If the optional argument @var{no-cookies} is -non-@code{nil}, cookies are not stored or sent. -@end defun - -@defun url-queue-retrieve url callback &optional cbargs silent no-cookies -This function acts like @code{url-retrieve}, but with limits on the -number of concurrently-running network processes. The option -@code{url-queue-parallel-processes} controls the number of concurrent -processes, and the option @code{url-queue-timeout} sets a timeout in -seconds. - -To use this function, you must @code{(require 'url-queue)}. -@end defun - -@vindex url-queue-parallel-processes -@defopt url-queue-parallel-processes -The value of this option is an integer specifying the maximum number -of concurrent @code{url-queue-retrieve} network processes. If the -number of @code{url-queue-retrieve} calls is larger than this number, -later ones are queued until earlier ones are finished. -@end defopt - -@vindex url-queue-timeout -@defopt url-queue-timeout -The value of this option is a number specifying the maximum lifetime -of a @code{url-queue-retrieve} network process, once it is started. -If a process is not finished by then, it is killed and removed from -the queue. -@end defopt - -@node Supported URL Types -@chapter Supported URL Types - -This chapter describes functions and variables affecting URL retrieval -for specific schemes. - -@menu -* http/https:: Hypertext Transfer Protocol. -* file/ftp:: Local files and FTP archives. -* info:: Emacs "Info" pages. -* mailto:: Sending email. -* news/nntp/snews:: Usenet news. -* rlogin/telnet/tn3270:: Remote host connectivity. -* irc:: Internet Relay Chat. -* data:: Embedded data URLs. -* nfs:: Networked File System -* ldap:: Lightweight Directory Access Protocol -* man:: Unix man pages. -@end menu - -@node http/https -@section @code{http} and @code{https} - -The @code{http} scheme refers to the Hypertext Transfer Protocol. The -@code{url} library supports HTTP version 1.1, specified in RFC 2616. -Its default port is 80. - - The @code{https} scheme is a secure version of @code{http}, with -transmission via SSL@. It is defined in RFC 2069, and its default port -is 443. When using @code{https}, the @code{url} library performs SSL -encryption via the @code{ssl} library, by forcing the @code{ssl} -gateway method to be used. @xref{Gateways in general}. - -@defopt url-honor-refresh-requests -If this option is non-@code{nil} (the default), the @code{url} library -honors the HTTP @samp{Refresh} header, which is used by servers to -direct clients to reload documents from the same URL or a or different -one. If the value is @code{nil}, the @samp{Refresh} header is -ignored; any other value means to ask the user on each request. -@end defopt - -@menu -* Cookies:: -* HTTP language/coding:: -* HTTP URL Options:: -* Dealing with HTTP documents:: -@end menu - -@node Cookies -@subsection Cookies - -@findex url-cookie-delete -@defun url-cookie-list -This command creates a @file{*url cookies*} buffer listing the current -cookies, if there are any. You can remove a cookie using the -@kbd{C-k} (@code{url-cookie-delete}) command. -@end defun - -@defopt url-cookie-file -The file in which cookies are stored, defaulting to @file{cookies} in -the directory specified by @code{url-configuration-directory}. -@end defopt - -@defopt url-cookie-confirmation -Specifies whether confirmation is require to accept cookies. -@end defopt - -@defopt url-cookie-multiple-line -Specifies whether to put all cookies for the server on one line in the -HTTP request to satisfy broken servers like -@url{http://www.hotmail.com}. -@end defopt - -@defopt url-cookie-trusted-urls -A list of regular expressions matching URLs from which to accept -cookies always. -@end defopt - -@defopt url-cookie-untrusted-urls -A list of regular expressions matching URLs from which to reject -cookies always. -@end defopt - -@defopt url-cookie-save-interval -The number of seconds between automatic saves of cookies to disk. -Default is one hour. -@end defopt - - -@node HTTP language/coding -@subsection Language and Encoding Preferences - -HTTP allows clients to express preferences for the language and -encoding of documents which servers may honor. For each of these -variables, the value is a string; it can specify a single choice, or -it can be a comma-separated list. - -Normally, this list is ordered by descending preference. However, each -element can be followed by @samp{;q=@var{priority}} to specify its -preference level, a decimal number from 0 to 1; e.g., for -@code{url-mime-language-string}, @w{@code{"de, en-gb;q=0.8, -en;q=0.7"}}. An element that has no @samp{;q} specification has -preference level 1. - -@defopt url-mime-charset-string -@cindex character sets -@cindex coding systems -This variable specifies a preference for character sets when documents -can be served in more than one encoding. - -HTTP allows specifying a series of MIME charsets which indicate your -preferred character set encodings, e.g., Latin-9 or Big5, and these -can be weighted. The default series is generated automatically from -the associated MIME types of all defined coding systems, sorted by the -coding system priority specified in Emacs. @xref{Recognize Coding, , -Recognizing Coding Systems, emacs, The GNU Emacs Manual}. -@end defopt - -@defopt url-mime-language-string -@cindex language preferences -A string specifying the preferred language when servers can serve -files in several languages. Use RFC 1766 abbreviations, e.g., -@samp{en} for English, @samp{de} for German. - -The string can be @code{"*"} to get the first available language (as -opposed to the default). -@end defopt - -@node HTTP URL Options -@subsection HTTP URL Options - -HTTP supports an @samp{OPTIONS} method describing things supported by -the URL@. - -@defun url-http-options url -Returns a property list describing options available for URL@. The -property list members are: - -@table @code -@item methods -A list of symbols specifying what HTTP methods the resource -supports. - -@item dav -@cindex DAV -A list of numbers specifying what DAV protocol/schema versions are -supported. - -@item dasl -@cindex DASL -A list of supported DASL search types supported (string form). - -@item ranges -A list of the units available for use in partial document fetches. - -@item p3p -@cindex P3P -The @dfn{Platform For Privacy Protection} description for the resource. -Currently this is just the raw header contents. -@end table - -@end defun - -@node Dealing with HTTP documents -@subsection Dealing with HTTP documents - -HTTP URLs are retrieved into a buffer containing the HTTP headers -followed by the body. Since the headers are quasi-MIME, they may be -processed using the MIME library. @xref{Top,, Emacs MIME, -emacs-mime, The Emacs MIME Manual}. - -@node file/ftp -@section file and ftp -@cindex files -@cindex FTP -@cindex File Transfer Protocol -@cindex compressed files -@cindex dired - -The @code{ftp} and @code{file} schemes are defined in RFC 1808. The -@code{url} library treats @samp{ftp:} and @samp{file:} as synonymous. -Such URLs have the form - -@example -ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} -file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} -@end example - -@noindent -If the URL specifies a local file, it is retrieved by reading the file -contents in the usual way. If it specifies a remote file, it is -retrieved using the Ange-FTP package. @xref{Remote Files,,, emacs, -The GNU Emacs Manual}. - - When retrieving a compressed file, it is automatically uncompressed -if it has the file suffix @file{.z}, @file{.gz}, @file{.Z}, -@file{.bz2}, or @file{.xz}. (The list of supported suffixes is -hard-coded, and cannot be altered by customizing -@code{jka-compr-compression-info-list}.) - -@defopt url-directory-index-file -This option specifies the filename to look for when a @code{file} or -@code{ftp} URL specifies a directory. The default is -@file{index.html}. If this file exists and is readable, it is viewed. -Otherwise, Emacs visits the directory using Dired. -@end defopt - -@node info -@section info -@cindex Info -@cindex Texinfo -@findex Info-goto-node - -The @code{info} scheme is non-standard. Such URLs have the form - -@example -info:@var{file}#@var{node} -@end example - -@noindent -and are retrieved by invoking @code{Info-goto-node} with argument -@samp{(@var{file})@var{node}}. If @samp{#@var{node}} is omitted, the -@samp{Top} node is opened. - -@node mailto -@section mailto - -@cindex mailto -@cindex email -A @code{mailto} URL specifies an email message to be sent to a given -email address. For example, @samp{mailto:foo@@bar.com} specifies -sending a message to @samp{foo@@bar.com}. The ``retrieval method'' -for such URLs is to open a mail composition buffer in which the -appropriate content (e.g., the recipient address) has been filled in. - - As defined in RFC 2368, a @code{mailto} URL has the form - -@example -@samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]} -@end example - -@noindent -where an arbitrary number of @var{header}s can be added. If the -@var{header} is @samp{body}, then @var{contents} is put in the message -body; otherwise, a @var{header} header field is created with -@var{contents} as its contents. Note that the @code{url} library does -not perform any checking of @var{header} or @var{contents}, so you -should check them before sending the message. - -@defopt url-mail-command -@vindex mail-user-agent -The value of this variable is the function called whenever url needs -to send mail. This should normally be left its default, which is the -standard mail-composition command @code{compose-mail}. @xref{Sending -Mail,,, emacs, The GNU Emacs Manual}. -@end defopt - - If the document containing the @code{mailto} URL itself possessed a -known URL, Emacs automatically inserts an @samp{X-Url-From} header -field into the mail buffer, specifying that URL. - -@node news/nntp/snews -@section @code{news}, @code{nntp} and @code{snews} -@cindex news -@cindex network news -@cindex usenet -@cindex NNTP -@cindex snews - -The @code{news}, @code{nntp}, and @code{snews} schemes, defined in RFC -1738, are used for reading Usenet newsgroups. For compatibility with -non-standard-compliant news clients, the @code{url} library allows -host and port fields to be included in @code{news} URLs, even though -they are properly only allowed for @code{nntp} and @code{snews}. - - @code{news} and @code{nntp} URLs have the following form: - -@table @samp -@item news:@var{newsgroup} -Retrieves a list of messages in @var{newsgroup}; -@item news:@var{message-id} -Retrieves the message with the given @var{message-id}; -@item news:* -Retrieves a list of all available newsgroups; -@item nntp://@var{host}:@var{port}/@var{newsgroup} -@itemx nntp://@var{host}:@var{port}/@var{message-id} -@itemx nntp://@var{host}:@var{port}/* -Similar to the @samp{news} versions. -@end table - - The default port for @code{nntp} (and @code{news}) is 119. The -difference between an @code{nntp} URL and a @code{news} URL is that an -@code{nttp} URL may specify an article by its number. The -@samp{snews} scheme is the same as @samp{nntp}, except that it is -tunneled through SSL and has default port 563. - - These URLs are retrieved via the Gnus package. - -@cindex environment variable -@vindex NNTPSERVER -@defopt url-news-server -This variable specifies the default news server from which to fetch -news, if no server was specified in the URL@. The default value, -@code{nil}, means to use the server specified by the standard -environment variable @samp{NNTPSERVER}, or @samp{news} if that -environment variable is unset. -@end defopt - -@node rlogin/telnet/tn3270 -@section rlogin, telnet and tn3270 -@cindex rlogin -@cindex telnet -@cindex tn3270 -@cindex terminal emulation -@findex terminal-emulator - -These URL schemes are defined in RFC 1738, and are used for logging in -via a terminal emulator. They have the form - -@example -telnet://@var{user}:@var{password}@@@var{host}:@var{port} -@end example - -@noindent -but the @var{password} component is ignored. - -To handle rlogin, telnet and tn3270 URLs, a @code{rlogin}, -@code{telnet} or @code{tn3270} (the program names and arguments are -hardcoded) session is run in a @code{terminal-emulator} buffer. -Well-known ports are used if the URL does not specify a port. - -@node irc -@section irc -@cindex IRC -@cindex Internet Relay Chat -@cindex ZEN IRC -@cindex ERC -@cindex rcirc - - The @code{irc} scheme is defined in the Internet Draft at -@url{http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt} (which -was never approved as an RFC). Such URLs have the form - -@example -irc://@var{host}:@var{port}/@var{target},@var{needpass} -@end example - -@noindent -and are retrieved by opening an @acronym{IRC} session using the -function specified by @code{url-irc-function}. - -@defopt url-irc-function -The value of this option is a function, which is called to open an IRC -connection for @code{irc} URLs. This function must take five -arguments, @var{host}, @var{port}, @var{channel}, @var{user} and -@var{password}. The @var{channel} argument specifies the channel to -join immediately, and may be @code{nil}. - -The default is @code{url-irc-rcirc}, which uses the Rcirc package. -Other options are @code{url-irc-erc} (which uses ERC) and -@code{url-irc-zenirc} (which uses ZenIRC). -@end defopt - -@node data -@section data -@cindex data URLs - - The @code{data} scheme, defined in RFC 2397, contains MIME data in -the URL itself. Such URLs have the form - -@example -data:@r{[}@var{media-type}@r{]}@r{[};@var{base64}@r{]},@var{data} -@end example - -@noindent -@var{media-type} is a MIME @samp{Content-Type} string, possibly -including parameters. It defaults to -@samp{text/plain;charset=US-ASCII}. The @samp{text/plain} can be -omitted but the charset parameter supplied. If @samp{;base64} is -present, the @var{data} are base64-encoded. - -@node nfs -@section nfs -@cindex NFS -@cindex Network File System -@cindex automounter - -The @code{nfs} scheme, defined in RFC 2224, is similar to @code{ftp} -except that it points to a file on a remote host that is handled by an -NFS automounter on the local host. Such URLs have the form - -@example -nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} -@end example - -@defvar url-nfs-automounter-directory-spec -@end defvar -A string saying how to invoke the NFS automounter. Certain @samp{%} -sequences are recognized: - -@table @samp -@item %h -The hostname of the NFS server; -@item %n -The port number of the NFS server; -@item %u -The username to use to authenticate; -@item %p -The password to use to authenticate; -@item %f -The filename on the remote server; -@item %% -A literal @samp{%}. -@end table - -Each can be used any number of times. - -@node ldap -@section ldap -@cindex LDAP -@cindex Lightweight Directory Access Protocol - -The LDAP scheme is defined in RFC 2255. - -@node man -@section man -@cindex @command{man} -@cindex Unix man pages -@findex man - -The @code{man} scheme is a non-standard one. Such URLs have the form - -@example -@samp{man:@var{page-spec}} -@end example - -@noindent -and are retrieved by passing @var{page-spec} to the Lisp function -@code{man}. - -@node General Facilities -@chapter General Facilities - -@menu -* Disk Caching:: -* Proxies:: -* Gateways in general:: -* History:: -@end menu - -@node Disk Caching -@section Disk Caching -@cindex Caching -@cindex Persistent Cache -@cindex Disk Cache - -The disk cache stores retrieved documents locally, whence they can be -retrieved more quickly. When requesting a URL that is in the cache, -the library checks to see if the page has changed since it was last -retrieved from the remote machine. If not, the local copy is used, -saving the transmission over the network. -@cindex Cleaning the cache -@cindex Clearing the cache -@cindex Cache cleaning -Currently the cache isn't cleared automatically. -@c Running the @code{clean-cache} shell script -@c fist is recommended, to allow for future cleaning of the cache. This -@c shell script will remove all files that have not been accessed since it -@c was last run. To keep the cache pared down, it is recommended that this -@c script be run from @i{at} or @i{cron} (see the manual pages for -@c crontab(5) or at(1) for more information) - -@defopt url-automatic-caching -Setting this variable non-@code{nil} causes documents to be cached -automatically. -@end defopt - -@defopt url-cache-directory -This variable specifies the -directory to store the cache files. It defaults to sub-directory -@file{cache} of @code{url-configuration-directory}. -@end defopt - -@defopt url-cache-creation-function -The cache relies on a scheme for mapping URLs to files in the cache. -This variable names a function which sets the type of cache to use. -It takes a URL as argument and returns the absolute file name of the -corresponding cache file. The two supplied possibilities are -@code{url-cache-create-filename-using-md5} and -@code{url-cache-create-filename-human-readable}. -@end defopt - -@defun url-cache-create-filename-using-md5 url -Creates a cache file name from @var{url} using MD5 hashing. -This is creates entries with very few cache collisions and is fast. -@cindex MD5 -@smallexample -(url-cache-create-filename-using-md5 "http://www.example.com/foo/bar") - @result{} "/home/fx/.url/cache/fx/http/com/example/www/b8a35774ad20db71c7c3409a5410e74f" -@end smallexample -@end defun - -@defun url-cache-create-filename-human-readable url -Creates a cache file name from @var{url} more obviously connected to -@var{url} than for @code{url-cache-create-filename-using-md5}, but -more likely to conflict with other files. -@smallexample -(url-cache-create-filename-human-readable "http://www.example.com/foo/bar") - @result{} "/home/fx/.url/cache/fx/http/com/example/www/foo/bar" -@end smallexample -@end defun - -@defun url-cache-expired -This function returns non-@code{nil} if a cache entry has expired (or is absent). -The arguments are a URL and optional expiration delay in seconds -(default @var{url-cache-expire-time}). -@end defun - -@defopt url-cache-expire-time -This variable is the default number of seconds to use for the -expire-time argument of the function @code{url-cache-expired}. -@end defopt - -@defun url-fetch-from-cache -This function takes a URL as its argument and returns a buffer -containing the data cached for that URL. -@end defun - -@c Fixme: never actually used currently? -@c @defopt url-standalone-mode -@c @cindex Relying on cache -@c @cindex Cache only mode -@c @cindex Standalone mode -@c If this variable is non-@code{nil}, the library relies solely on the -@c cache for fetching documents and avoids checking if they have changed -@c on remote servers. -@c @end defopt - -@c With a large cache of documents on the local disk, it can be very handy -@c when traveling, or any other time the network connection is not active -@c (a laptop with a dial-on-demand PPP connection, etc.). Emacs/W3 can rely -@c solely on its cache, and avoid checking to see if the page has changed -@c on the remote server. In the case of a dial-on-demand PPP connection, -@c this will keep the phone line free as long as possible, only bringing up -@c the PPP connection when asking for a page that is not located in the -@c cache. This is very useful for demonstrations as well. - -@node Proxies -@section Proxies and Gatewaying - -@c fixme: check/document url-ns stuff -@cindex proxy servers -@cindex proxies -@cindex environment variables -@vindex HTTP_PROXY -Proxy servers are commonly used to provide gateways through firewalls -or as caches serving some more-or-less local network. Each protocol -(HTTP, FTP, etc.)@: can have a different gateway server. Proxying is -conventionally configured commonly amongst different programs through -environment variables of the form @code{@var{protocol}_proxy}, where -@var{protocol} is one of the supported network protocols (@code{http}, -@code{ftp} etc.). The library recognizes such variables in either -upper or lower case. Their values are of one of the forms: -@itemize @bullet -@item @code{@var{host}:@var{port}} -@item A full URL; -@item Simply a host name. -@end itemize - -@vindex NO_PROXY -The @code{NO_PROXY} environment variable specifies URLs that should be -excluded from proxying (on servers that should be contacted directly). -This should be a comma-separated list of hostnames, domain names, or a -mixture of both. Asterisks can be used as wildcards, but other -clients may not support that. Domain names may be indicated by a -leading dot. For example: -@example -NO_PROXY="*.aventail.com,home.com,.seanet.com" -@end example -@noindent says to contact all machines in the @samp{aventail.com} and -@samp{seanet.com} domains directly, as well as the machine named -@samp{home.com}. If @code{NO_PROXY} isn't defined, @code{no_PROXY} -and @code{no_proxy} are also tried, in that order. - -Proxies may also be specified directly in Lisp. - -@defopt url-proxy-services -This variable is an alist of URL schemes and proxy servers that -gateway them. The items are of the form @w{@code{(@var{scheme} -. @var{host}:@var{portnumber})}}, says that the URL @var{scheme} is -gatewayed through @var{portnumber} on the specified @var{host}. An -exception is the pseudo scheme @code{"no_proxy"}, which is paired with -a regexp matching host names not to be proxied. This variable is -initialized from the environment as above. - -@example -(setq url-proxy-services - '(("http" . "proxy.aventail.com:80") - ("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com"))) -@end example -@end defopt - -@node Gateways in general -@section Gateways in General -@cindex gateways -@cindex firewalls - -The library provides a general gateway layer through which all -networking passes. It can both control access to the network and -provide access through gateways in firewalls. This may make direct -connections in some cases and pass through some sort of gateway in -others.@footnote{Proxies (which only operate over HTTP) are -implemented using this.} The library's basic function responsible for -making connections is @code{url-open-stream}. - -@defun url-open-stream name buffer host service -@cindex opening a stream -@cindex stream, opening -Open a stream to @var{host}, possibly via a gateway. The other -arguments are as for @code{open-network-stream}. This will not make a -connection if @code{url-gateway-unplugged} is non-@code{nil}. -@end defun - -@defvar url-gateway-local-host-regexp -This is a regular expression that matches local hosts that do not -require the use of a gateway. If @code{nil}, all connections are made -through the gateway. -@end defvar - -@defvar url-gateway-method -This variable controls which gateway method is used. It may be useful -to bind it temporarily in some applications. It has values taken from -a list of symbols. Possible values are: - -@table @code -@item telnet -@cindex @command{telnet} -Use this method if you must first telnet and log into a gateway host, -and then run telnet from that host to connect to outside machines. - -@item rlogin -@cindex @command{rlogin} -This method is identical to @code{telnet}, but uses @command{rlogin} -to log into the remote machine without having to send the username and -password over the wire every time. - -@item socks -@cindex @sc{socks} -Use if the firewall has a @sc{socks} gateway running on it. The -@sc{socks} v5 protocol is defined in RFC 1928. - -@c @item ssl -@c This probably shouldn't be documented -@c Fixme: why not? -- fx - -@item native -This method uses Emacs's builtin networking directly. This is the -default. It can be used only if there is no firewall blocking access. -@end table -@end defvar - -The following variables control the gateway methods. - -@defopt url-gateway-telnet-host -The gateway host to telnet to. Once logged in there, you then telnet -out to the hosts you want to connect to. -@end defopt -@defopt url-gateway-telnet-parameters -This should be a list of parameters to pass to the @command{telnet} program. -@end defopt -@defopt url-gateway-telnet-password-prompt -This is a regular expression that matches the password prompt when -logging in. -@end defopt -@defopt url-gateway-telnet-login-prompt -This is a regular expression that matches the username prompt when -logging in. -@end defopt -@defopt url-gateway-telnet-user-name -The username to log in with. -@end defopt -@defopt url-gateway-telnet-password -The password to send when logging in. -@end defopt -@defopt url-gateway-prompt-pattern -This is a regular expression that matches the shell prompt. -@end defopt - -@defopt url-gateway-rlogin-host -Host to @samp{rlogin} to before telnetting out. -@end defopt -@defopt url-gateway-rlogin-parameters -Parameters to pass to @samp{rsh}. -@end defopt -@defopt url-gateway-rlogin-user-name -User name to use when logging in to the gateway. -@end defopt -@defopt url-gateway-prompt-pattern -This is a regular expression that matches the shell prompt. -@end defopt - -@defopt socks-server -This specifies the default server, it takes the form -@w{@code{("Default server" @var{server} @var{port} @var{version})}} -where @var{version} can be either 4 or 5. -@end defopt -@defvar socks-password -If this is @code{nil} then you will be asked for the password, -otherwise it will be used as the password for authenticating you to -the @sc{socks} server. -@end defvar -@defvar socks-username -This is the username to use when authenticating yourself to the -@sc{socks} server. By default this is your login name. -@end defvar -@defvar socks-timeout -This controls how long, in seconds, to wait for responses from the -@sc{socks} server; it is 5 by default. -@end defvar -@c fixme: these have been effectively commented-out in the code -@c @defopt socks-server-aliases -@c This a list of server aliases. It is a list of aliases of the form -@c @var{(alias hostname port version)}. -@c @end defopt -@c @defopt socks-network-aliases -@c This a list of network aliases. Each entry in the list takes the form -@c @var{(alias (network))} where @var{alias} is a string that names the -@c @var{network}. The networks can contain a pair (not a dotted pair) of -@c @sc{ip} addresses which specify a range of @sc{ip} addresses, an @sc{ip} -@c address and a netmask, a domain name or a unique hostname or @sc{ip} -@c address. -@c @end defopt -@c @defopt socks-redirection-rules -@c This a list of redirection rules. Each rule take the form -@c @var{(Destination network Connection type)} where @var{Destination -@c network} is a network alias from @code{socks-network-aliases} and -@c @var{Connection type} can be @code{nil} in which case a direct -@c connection is used, or it can be an alias from -@c @code{socks-server-aliases} in which case that server is used as a -@c proxy. -@c @end defopt -@defopt socks-nslookup-program -@cindex @command{nslookup} -This the @samp{nslookup} program. It is @code{"nslookup"} by default. -@end defopt - -@menu -* Suppressing network connections:: -@end menu -@c * Broken hostname resolution:: - -@node Suppressing network connections -@subsection Suppressing Network Connections - -@cindex network connections, suppressing -@cindex suppressing network connections -@cindex bugs, HTML -@cindex HTML `bugs' -In some circumstances it is desirable to suppress making network -connections. A typical case is when rendering HTML in a mail user -agent, when external URLs should not be activated, particularly to -avoid ``bugs'' which ``call home'' by fetch single-pixel images and the -like. To arrange this, bind the following variable for the duration -of such processing. - -@defvar url-gateway-unplugged -If this variable is non-@code{nil} new network connections are never -opened by the URL library. -@end defvar - -@c @node Broken hostname resolution -@c @subsection Broken Hostname Resolution - -@c @cindex hostname resolver -@c @cindex resolver, hostname -@c Some C libraries do not include the hostname resolver routines in -@c their static libraries. If Emacs was linked statically, and was not -@c linked with the resolver libraries, it will not be able to get to any -@c machines off the local network. This is characterized by being able -@c to reach someplace with a raw ip number, but not its hostname -@c (@url{http://129.79.254.191/} works, but -@c @url{http://www.cs.indiana.edu/} doesn't). This used to happen on -@c SunOS4 and Ultrix, but is now probably now rare. If Emacs can't be -@c rebuilt linked against the resolver library, it can use the external -@c @command{nslookup} program instead. - -@c @defopt url-gateway-broken-resolution -@c @cindex @code{nslookup} program -@c @cindex program, @code{nslookup} -@c If non-@code{nil}, this variable says to use the program specified by -@c @code{url-gateway-nslookup-program} program to do hostname resolution. -@c @end defopt - -@c @defopt url-gateway-nslookup-program -@c The name of the program to do hostname lookup if Emacs can't do it -@c directly. This program should expect a single argument on the command -@c line---the hostname to resolve---and should produce output similar to -@c the standard Unix @command{nslookup} program: -@c @example -@c Name: www.cs.indiana.edu -@c Address: 129.79.254.191 -@c @end example -@c @end defopt - -@node History -@section History - -@findex url-do-setup -The library can maintain a global history list tracking URLs accessed. -URL completion can be done from it. The history mechanism is set up -automatically via @code{url-do-setup} when it is configured to be on. -Note that the size of the history list is currently not limited. - -@vindex url-history-hash-table -The history ``list'' is actually a hash table, -@code{url-history-hash-table}. It contains access times keyed by URL -strings. The times are in the format returned by @code{current-time}. - -@defun url-history-update-url url time -This function updates the history table with an entry for @var{url} -accessed at the given @var{time}. -@end defun - -@defopt url-history-track -If non-@code{nil}, the library will keep track of all the URLs -accessed. If it is @code{t}, the list is saved to disk at the end of -each Emacs session. The default is @code{nil}. -@end defopt - -@defopt url-history-file -The file storing the history list between sessions. It defaults to -@file{history} in @code{url-configuration-directory}. -@end defopt - -@defopt url-history-save-interval -@findex url-history-setup-save-timer -The number of seconds between automatic saves of the history list. -Default is one hour. Note that if you change this variable directly, -rather than using Custom, after @code{url-do-setup} has been run, you -need to run the function @code{url-history-setup-save-timer}. -@end defopt - -@defun url-history-parse-history &optional fname -Parses the history file @var{fname} (default @code{url-history-file}) -and sets up the history list. -@end defun - -@defun url-history-save-history &optional fname -Saves the current history to file @var{fname} (default -@code{url-history-file}). -@end defun - -@defun url-completion-function string predicate function -You can use this function to do completion of URLs from the history. -@end defun - -@node Customization -@chapter Customization - -@cindex environment variables - The following environment variables affect the @code{url} library's -operation at startup. - -@table @code -@item TMPDIR -@vindex TMPDIR -@vindex url-temporary-directory -If this is defined, @var{url-temporary-directory} is initialized from -it. -@end table - - The following user options affect the general operation of -@code{url} library. - -@defopt url-configuration-directory -@cindex configuration files -The value of this variable specifies the name of the directory where -the @code{url} library stores its various configuration files, cache -files, etc. - -The default value specifies a subdirectory named @file{url/} in the -standard Emacs user data directory specified by the variable -@code{user-emacs-directory} (normally @file{~/.emacs.d}). However, -the old default was @file{~/.url}, and this directory is used instead -if it exists. -@end defopt - -@defopt url-debug -@cindex debugging -Specifies the types of debug messages which are logged to -the @file{*URL-DEBUG*} buffer. -@code{t} means log all messages. -A number means log all messages and show them with @code{message}. -It may also be a list of the types of messages to be logged. -@end defopt -@defopt url-personal-mail-address -@end defopt -@defopt url-privacy-level -@end defopt -@defopt url-uncompressor-alist -@end defopt -@defopt url-passwd-entry-func -@end defopt -@defopt url-standalone-mode -@end defopt -@defopt url-bad-port-list -@end defopt -@defopt url-max-password-attempts -@end defopt -@defopt url-temporary-directory -@end defopt -@defopt url-show-status -@end defopt -@defopt url-confirmation-func -The function to use for asking yes or no functions. This is normally -either @code{y-or-n-p} or @code{yes-or-no-p}, but could be another -function taking a single argument (the prompt) and returning @code{t} -only if an affirmative answer is given. -@end defopt -@defopt url-gateway-method -@c fixme: describe gatewaying -A symbol specifying the type of gateway support to use for connections -from the local machine. The supported methods are: - -@table @code -@item telnet -Run telnet in a subprocess to connect; -@item rlogin -Rlogin to another machine to connect; -@item socks -Connect through a socks server; -@item ssl -Connect with SSL; -@item native -Connect directly. -@end table -@end defopt - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Command and Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@bye diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi deleted file mode 100644 index e7a53e768a7..00000000000 --- a/doc/misc/vip.texi +++ /dev/null @@ -1,1947 +0,0 @@ -\input texinfo -@setfilename ../../info/vip -@settitle VIP - -@documentencoding UTF-8 - -@copying -Copyright @copyright{} 1987, 2001--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@titlepage -@sp 10 -@center @titlefont{VIP} -@sp 1 -@center A Vi Package for GNU Emacs -@center (Version 3.5, September 15, 1987) -@sp 2 -@center Masahiko Sato -@page -@vskip 0pt plus1filll -@insertcopying -@end titlepage - -@finalout -@contents - -@dircategory Emacs misc features -@direntry -* VIP: (vip). An older VI-emulation for Emacs. -@end direntry - -@ifnottex -@node Top -@top VIP - -VIP is a Vi emulating package written in Emacs Lisp. VIP implements most -Vi commands including Ex commands. It is therefore hoped that this package -will enable you to do Vi style editing under the powerful GNU Emacs -environment. This info file describes the usage of VIP assuming that you -are fairly accustomed to Vi but not so much with Emacs. Also we will -concentrate mainly on differences from Vi, especially features unique to -VIP. - -It is recommended that you read nodes on survey and on customization before -you start using VIP@. Other nodes may be visited as needed. - -Comments and bug reports are welcome. Please send messages to -@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to -@code{masahiko@@sato.riec.tohoku.junet} if you are in Japan. - -@insertcopying - -@end ifnottex - -@menu -* Survey:: A survey of VIP. -* Vi Commands:: Details of Vi commands. -* Ex Commands:: Details of Ex commands. -* Customization:: How to customize VIP. -* GNU Free Documentation License:: The license for this documentation. - -@end menu -@iftex -@unnumbered Introduction - -VIP is a Vi emulating package written in Emacs Lisp. VIP implements most -Vi commands including Ex commands. It is therefore hoped that this package -will enable you to do Vi style editing under the powerful GNU Emacs -environment. This manual describes the usage of VIP assuming that you are -fairly accustomed to Vi but not so much with Emacs. Also we will -concentrate mainly on differences from Vi, especially features unique to -VIP. - -It is recommended that you read chapters on survey and on customization -before you start using VIP@. Other chapters may be used as future -references. - -Comments and bug reports are welcome. Please send messages to -@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to -@code{masahiko@@unsun.riec.tohoku.junet} if you are in Japan. -@end iftex - -@node Survey -@chapter A Survey of VIP - -In this chapter we describe basics of VIP with emphasis on the features not -found in Vi and on how to use VIP under GNU Emacs. - -@menu -* Basic Concepts:: Basic concepts in Emacs. -* Loading VIP:: How to load VIP automatically. -* Modes in VIP:: VIP has three modes, which are orthogonal to modes - in Emacs. -* Differences from Vi:: Differences of VIP from Vi is explained. -@end menu - -@node Basic Concepts -@section Basic Concepts - -We begin by explaining some basic concepts of Emacs. These concepts are -explained in more detail in the GNU Emacs Manual. - -@cindex buffer -@cindex point -@cindex mark -@cindex text -@cindex looking at -@cindex end (of buffer) -@cindex region - -Conceptually, a @dfn{buffer} is just a string of @acronym{ASCII} characters and two -special characters @key{PNT} (@dfn{point}) and @key{MRK} (@dfn{mark}) such -that the character @key{PNT} occurs exactly once and @key{MRK} occurs at -most once. The @dfn{text} of a buffer is obtained by deleting the -occurrences of @key{PNT} and @key{MRK}. If, in a buffer, there is a -character following @key{PNT} then we say that point is @dfn{looking at} -the character; otherwise we say that point is @dfn{at the end of buffer}. -@key{PNT} and @key{MRK} are used -to indicate positions in a buffer and they are not part of the text of the -buffer. If a buffer contains a @key{MRK} then the text between @key{MRK} -and @key{PNT} is called the @dfn{region} of the buffer. - -@cindex window - -Emacs provides (multiple) @dfn{windows} on the screen, and you can see the -content of a buffer through the window associated with the buffer. The -cursor of the screen is always positioned on the character after @key{PNT}. - -@cindex mode -@cindex keymap -@cindex local keymap -@cindex global keymap - -A @dfn{keymap} is a table that records the bindings between characters and -command functions. There is the @dfn{global keymap} common to all the -buffers. Each buffer has its @dfn{local keymap} that determines the -@dfn{mode} of the buffer. Local keymap overrides global keymap, so that if -a function is bound to some key in the local keymap then that function will -be executed when you type the key. If no function is bound to a key in the -local map, however, the function bound to the key in the global map becomes -in effect. - -@node Loading VIP -@section Loading VIP - -The recommended way to load VIP automatically is to include the line: -@example -(load "vip") -@end example -@noindent -in your @file{.emacs} file. The @file{.emacs} file is placed in your home -directory and it will be executed every time you invoke Emacs. If you wish -to be in vi mode whenever Emacs starts up, you can include the following -line in your @file{.emacs} file instead of the above line: -@example -(add-hook 'emacs-startup-hook 'vip-mode) -@end example -@noindent -(@xref{Vi Mode}, for the explanation of vi mode.) - -Even if your @file{.emacs} file does not contain any of the above lines, -you can load VIP and enter vi mode by typing the following from within -Emacs. -@example -M-x vip-mode -@end example -@noindent - -@node Modes in VIP -@section Modes in VIP - -@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) -@kindex 0301 @kbd{C-x C-z} (@code{suspend-emacs}) - -Loading VIP has the effect of globally binding @kbd{C-z} (@kbd{Control-z}) -to the function @code{vip-change-mode-to-vi}. The default binding of @kbd{C-z} -in GNU Emacs is @code{suspend-emacs}, but, you can also call -@code{suspend-emacs} by typing @kbd{C-x C-z}. Other than this, all the -key bindings of Emacs remain the same after loading VIP. - -@cindex vi mode - -Now, if you hit @kbd{C-z}, the function @code{vip-change-mode-to-vi} will be -called and you will be in @dfn{vi mode}. (Some major modes may locally bind -@kbd{C-z} to some special functions. In such cases, you can call -@code{vip-change-mode-to-vi} by @code{execute-extended-command} which is -invoked by @kbd{M-x}. Here @kbd{M-x} means @kbd{Meta-x}, and if your -terminal does not have a @key{META} key you can enter it by typing -@kbd{@key{ESC} x}. The same effect can also be achieve by typing -@kbd{M-x vip-mode}.) - -@cindex mode line - -You can observe the change of mode by looking at the @dfn{mode line}. For -instance, if the mode line is: -@example ------Emacs: *scratch* (Lisp Interaction)----All------------ -@end example -@noindent -then it will change to: -@example ------Vi: *scratch* (Lisp Interaction)----All------------ -@end example -@noindent -Thus the word @samp{Emacs} in the mode line will change to @samp{Vi}. - -@cindex insert mode -@cindex emacs mode - -You can go back to the original @dfn{emacs mode} by typing @kbd{C-z} in -vi mode. Thus @kbd{C-z} toggles between these two modes. - -Note that modes in VIP exist orthogonally to modes in Emacs. This means -that you can be in vi mode and at the same time, say, shell mode. - -Vi mode corresponds to Vi's command mode. From vi mode you can enter -@dfn{insert mode} (which corresponds to Vi's insert mode) by usual Vi command -keys like @kbd{i}, @kbd{a}, @kbd{o} @dots{} etc. - -In insert mode, the mode line will look like this: -@example ------Insert *scratch* (Lisp Interaction)----All------------ -@end example -@noindent -You can exit from insert mode by hitting @key{ESC} key as you do in Vi. - -That VIP has three modes may seem very complicated, but in fact it is not -so. VIP is implemented so that you can do most editing remaining only -in the two modes for Vi (that is vi mode and insert mode). - -@ifinfo -The figure below shows the transition of three modes in VIP. -@display - - - === C-z ==> == i,o ... ==> -emacs mode vi mode insert mode - <== X-z === <=== ESC ==== -@end display -@end ifinfo - -@menu -* Emacs Mode:: This is the mode you should know better. -* Vi Mode:: Vi commands are executed in this mode. -* Insert Mode:: You can enter text, and also can do editing if you - know enough Emacs commands. -@end menu - -@node Emacs Mode -@subsection Emacs Mode - -@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) - -You will be in this mode just after you loaded VIP@. You can do all -normal Emacs editing in this mode. Note that the key @kbd{C-z} is globally -bound to @code{vip-change-mode-to-vi}. So, if you type @kbd{C-z} in this mode -then you will be in vi mode. - -@node Vi Mode -@subsection Vi Mode - -This mode corresponds to Vi's command mode. Most Vi commands work as they -do in Vi. You can go back to emacs mode by typing @kbd{C-z}. You can -enter insert mode, just as in Vi, by typing @kbd{i}, @kbd{a} etc. - -@node Insert Mode -@subsection Insert Mode - -The key bindings in this mode is the same as in the emacs mode except for -the following 4 keys. So, you can move around in the buffer and change -its content while you are in insert mode. - -@table @kbd -@item @key{ESC} -@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) -This key will take you back to vi mode. -@item C-h -@kindex 010 @kbd{C-h} (@code{vip-delete-backward-char}) (insert mode) -Delete previous character. -@item C-w -@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) -Delete previous word. -@item C-z -@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) -Typing this key has the same effect as typing @key{ESC} in emacs mode. -Thus typing @kbd{C-z x} in insert mode will have the same effect as typing -@kbd{ESC x} in emacs mode. -@end table - -@node Differences from Vi -@section Differences from Vi - -The major differences from Vi are explained below. - -@menu -* Undoing:: You can undo more in VIP. -* Changing:: Commands for changing the text. -* Searching:: Search commands. -* z Command:: You can now use zH, zM and zL as well as z- etc. -* Counts:: Some Vi commands which do not accept a count now - accept one. -* Marking:: You can now mark the current point, beginning of - the buffer etc. -* Region Commands:: You can now give a region as an argument for delete - commands etc. -* New Commands:: Some new commands not available in Vi are added. -* New Bindings:: Bindings of some keys are changed for the - convenience of editing under Emacs. -* Window Commands:: Commands for moving among windows etc. -* Buffer Commands:: Commands for selecting buffers etc. -* File Commands:: Commands for visiting files etc. -* Misc Commands:: Other useful commands. -@end menu - -@node Undoing -@subsection Undoing - -@kindex 165 @kbd{u} (@code{vip-undo}) -@kindex 056 @kbd{.} (@code{vip-repeat}) - -You can repeat undoing by the @kbd{.} key. So, @kbd{u} will undo -a single change, while @kbd{u .@: .@: .@:}, for instance, will undo 4 previous -changes. Undo is undoable as in Vi. So the content of the buffer will -be the same before and after @kbd{u u}. - -@node Changing -@subsection Changing - -Some commands which change a small number of characters are executed -slightly differently. Thus, if point is at the beginning of a word -@samp{foo} and you wished to change it to @samp{bar} by typing @w{@kbd{c w}}, -then VIP will prompt you for a new word in the minibuffer by the prompt -@samp{foo => }. You can then enter @samp{bar} followed by @key{RET} or -@key{ESC} to complete the command. Before you enter @key{RET} or -@key{ESC} you can abort the command by typing @kbd{C-g}. In general, -@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -you can abort a partially formed command by typing @kbd{C-g}. - -@node Searching -@subsection Searching - -@kindex 057 @kbd{/} (@code{vip-search-forward}) -@kindex 077 @kbd{?} (@code{vip-search-backward}) - -As in Vi, searching is done by @kbd{/} and @kbd{?}. The string will be -searched literally by default. To invoke a regular expression search, -first execute the search command @kbd{/} (or @kbd{?}) with empty search -string. (I.e., type @kbd{/} followed by @key{RET}.) -A search for empty string will toggle the search mode between vanilla -search and regular expression search. You cannot give an offset to the -search string. (It is a limitation.) By default, search will wrap around -the buffer as in Vi. You can change this by rebinding the variable -@code{vip-search-wrap-around}. @xref{Customization}, for how to do this. - -@node z Command -@subsection z Command - -@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) -@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) -@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) -@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) -@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) -@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) - -For those of you who cannot remember which of @kbd{z} followed by @key{RET}, -@kbd{.}@: and @kbd{-} do what. You can also use @kbd{z} followed by @kbd{H}, -@kbd{M} and @kbd{L} to place the current line in the Home (Middle, and -Last) line of the window. - -@node Counts -@subsection Counts - -Some Vi commands which do not accept a count now accept one - -@table @kbd -@item p -@itemx P -@kindex 160 @kbd{p} (@code{vip-put-back}) -@kindex 120 @kbd{P} (@code{vip-Put-back}) -Given counts, text will be yanked (in Vi's sense) that many times. Thus -@kbd{3 p} is the same as @kbd{p p p}. -@item o -@itemx O -@kindex 157 @kbd{o} (@code{vip-open-line}) -@kindex 117 @kbd{O} (@code{vip-Open-line}) -Given counts, that many copies of text will be inserted. Thus -@kbd{o a b c @key{ESC}} will insert 3 lines of @samp{abc} below the current -line. -@item / -@itemx ? -@kindex 057 @kbd{/} (@code{vip-search-forward}) -@kindex 077 @kbd{?} (@code{vip-search-backward}) -Given a count @var{n}, @var{n}-th occurrence will be searched. -@end table - -@node Marking -@subsection Marking - -Typing an @kbd{m} followed by a lower-case character @var{ch} marks the -point to the register named @var{ch} as in Vi. In addition to these, we -have following key bindings for marking. - -@kindex 155 @kbd{m} (@code{vip-mark-point}) - -@table @kbd -@item m < -Set mark at the beginning of buffer. -@item m > -Set mark at the end of buffer. -@item m . -Set mark at point (and push old mark on mark ring). -@item m , -Jump to mark (and pop mark off the mark ring). -@end table - -@node Region Commands -@subsection Region Commands - -@cindex region - -Vi operators like @kbd{d}, @kbd{c} etc. are usually used in combination -with motion commands. It is now possible to use current region as the -argument to these operators. (A @dfn{region} is a part of buffer -delimited by point and mark.) The key @kbd{r} is used for this purpose. -Thus @kbd{d r} will delete the current region. If @kbd{R} is used instead -of @kbd{r} the region will first be enlarged so that it will become the -smallest region containing the original region and consisting of whole -lines. Thus @kbd{m .@: d R} will have the same effect as @kbd{d d}. - -@node New Commands -@subsection Some New Commands - -Note that the keys below (except for @kbd{R}) are not used in Vi. - -@table @kbd -@item C-a -@kindex 001 @kbd{C-a} (@code{vip-beginning-of-line}) -Move point to the beginning of line. -@item C-n -@kindex 016 @kbd{C-n} (@code{vip-next-window}) -If you have two or more windows in the screen, this key will move point to -the next window. -@item C-o -@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) -Insert a newline and leave point before it, and then enter insert mode. -@item C-r -@kindex 022 @kbd{C-r} (@code{isearch-backward}) -Backward incremental search. -@item C-s -@kindex 023 @kbd{C-s} (@code{isearch-forward}) -Forward incremental search. -@item C-c -@itemx C-x -@itemx @key{ESC} -@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) -@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) -@kindex 033 @kbd{ESC} (@code{vip-ESC}) -These keys will exit from vi mode and return to emacs mode temporarily. If -you hit one of these keys, Emacs will be in emacs mode and will believe -that you hit that key in emacs mode. For example, if you hit @kbd{C-x} -followed by @kbd{2}, then the current window will be split into 2 and you -will be in vi mode again. -@item \ -@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) -Escape to emacs mode. Hitting @kbd{\} will take you to emacs mode, and you -can execute a single Emacs command. After executing the Emacs command you -will be in vi mode again. You can give a count before typing @kbd{\}. -Thus @kbd{5 \ *}, as well as @kbd{\ C-u 5 *}, will insert @samp{*****} -before point. Similarly @kbd{1 0 \ C-p} will move the point 10 lines above -the current line. -@item K -@kindex 113 @kbd{K} (@code{vip-kill-buffer}) -Kill current buffer if it is not modified. Useful when you selected a -buffer which you did not want. -@item Q -@itemx R -@kindex 121 @kbd{Q} (@code{vip-query-replace}) -@kindex 122 @kbd{R} (@code{vip-replace-string}) -@kbd{Q} is for query replace and @kbd{R} is for replace. By default, -string to be replaced are treated literally. If you wish to do a regular -expression replace, first do replace with empty string as the string to be -replaced. In this way, you can toggle between vanilla and regular -expression replacement. -@item v -@itemx V -@kindex 166 @kbd{v} (@code{vip-find-file}) -@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) -These keys are used to Visit files. @kbd{v} will switch to a buffer -visiting file whose name can be entered in the minibuffer. @kbd{V} is -similar, but will use window different from the current window. -@item # -@kindex 0430 @kbd{#} (@code{vip-command-argument}) -If followed by a certain character @var{ch}, it becomes an operator whose -argument is the region determined by the motion command that follows. -Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q} and -@kbd{s}. -@item # c -@kindex 0432 @kbd{# c} (@code{downcase-region}) -Change upper-case characters in the region to lower case -(@code{downcase-region}). -@item # C -@kindex 0431 @kbd{# C} (@code{upcase-region}) -Change lower-case characters in the region to upper case. For instance, -@kbd{# C 3 w} will capitalize 3 words from the current point -(@code{upcase-region}). -@item # g -@kindex 0432 @kbd{# g} (@code{vip-global-execute}) -Execute last keyboard macro for each line in the region -(@code{vip-global-execute}). -@item # q -@kindex 0432 @kbd{# q} (@code{vip-quote-region}) -Insert specified string at the beginning of each line in the region -(@code{vip-quote-region}). -@item # s -@kindex 0432 @kbd{# s} (@code{spell-region}) -Check spelling of words in the region (@code{spell-region}). -@item * -@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) -Call last keyboard macro. -@end table - -@node New Bindings -@subsection New Key Bindings - -In VIP the meanings of some keys are entirely different from Vi. These key -bindings are done deliberately in the hope that editing under Emacs will -become easier. It is however possible to rebind these keys to functions -which behave similarly as in Vi. @xref{Customizing Key Bindings}, for -details. - -@table @kbd -@item C-g -@itemx g -@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -@kindex 147 @kbd{g} (@code{vip-info-on-file}) -In Vi, @kbd{C-g} is used to get information about the file associated to -the current buffer. Here, @kbd{g} will do that, and @kbd{C-g} is -used to abort a command (this is for compatibility with emacs mode.) -@item SPC -@itemx @key{RET} -@kindex 040 @kbd{SPC} (@code{vip-scroll}) -@kindex 015 @kbd{RET} (@code{vip-scroll-back}) -Now these keys will scroll up and down the text of current window. -Convenient for viewing the text. -@item s -@itemx S -@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) -@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) -They are used to switch to a specified buffer. Useful for switching to -already existing buffer since buffer name completion is provided. Also -a default buffer will be given as part of the prompt, to which you can -switch by just typing @key{RET} key. @kbd{s} is used to select buffer -in the current window, while @kbd{S} selects buffer in another window. -@item C -@itemx X -@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) -@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) -These keys will exit from vi mode and return to emacs mode temporarily. -If you type @kbd{C} (@kbd{X}), Emacs will be in emacs mode and will believe -that you have typed @kbd{C-c} (@kbd{C-x}) in emacs mode. Moreover, -if the following character you type is an upper-case letter, then Emacs -will believe that you have typed the corresponding control character. -You will be in vi mode again after the command is executed. For example, -typing @kbd{X S} in vi mode is the same as typing @kbd{C-x C-s} in emacs -mode. You get the same effect by typing @kbd{C-x C-s} in vi mode, but -the idea here is that you can execute useful Emacs commands without typing -control characters. For example, if you hit @kbd{X} (or @kbd{C-x}) followed -by @kbd{2}, then the current window will be split into 2 and you will be in -vi mode again. -@end table - -In addition to these, @code{ctl-x-map} is slightly modified: - -@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) - -@table @kbd -@item X 3 -@itemx C-x 3 -This is equivalent to @kbd{C-x 1 C-x 2} (1 + 2 = 3). -@end table - -@node Window Commands -@subsection Window Commands - -In this and following subsections, we give a summary of key bindings for -basic functions related to windows, buffers and files. - -@table @kbd -@item C-n -@kindex 016 @kbd{C-n} (@code{vip-next-window}) -Switch to next window. -@item X 1 -@itemx C-x 1 -@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) -Delete other windows. -@item X 2 -@itemx C-x 2 -@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) -Split current window into two windows. -@item X 3 -@itemx C-x 3 -@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) -Show current buffer in two windows. -@end table - -@node Buffer Commands -@subsection Buffer Commands - -@table @kbd -@item s -@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) -Switch to the specified buffer in the current window -(@code{vip-switch-to-buffer}). -@item S -@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) -Switch to the specified buffer in another window -(@code{vip-switch-to-buffer-other-window}). -@item K -@kindex 113 @kbd{K} (@code{vip-kill-buffer}) -Kill the current buffer if it is not modified. -@item X S -@itemx C-x C-s -@kindex 1302 @kbd{X S} (@code{save-buffer}) -Save the current buffer in the file associated to the buffer. -@end table - -@node File Commands -@subsection File Commands - -@table @kbd -@item v -@kindex 166 @kbd{v} (@code{vip-find-file}) -Visit specified file in the current window. -@item V -@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) -Visit specified file in another window. -@item X W -@itemx C-x C-w -@kindex 1302 @kbd{X W} (@code{write-file}) -Write current buffer into the specified file. -@item X I -@itemx C-x C-i -@kindex 1302 @kbd{X I} (@code{insert-file}) - -Insert specified file at point. -@end table - -@node Misc Commands -@subsection Miscellaneous Commands - -@table @kbd -@item X ( -@itemx C-x ( -@kindex 1301 @kbd{X (} (@code{start-kbd-macro}) -Start remembering keyboard macro. -@item X ) -@itemx C-x ) -@kindex 1301 @kbd{X )} (@code{end-kbd-macro}) -Finish remembering keyboard macro. -@item * -@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) -Call last remembered keyboard macro. -@item X Z -@itemx C-x C-z -@kindex 1302 @kbd{X Z} (@code{suspend-emacs}) -Suspend Emacs. -@item Z Z -Exit Emacs. -@item Q -Query replace. -@item R -Replace. -@end table - -@node Vi Commands -@chapter Vi Commands - -This chapter describes Vi commands other than Ex commands implemented in -VIP@. Except for the last section which discusses insert mode, all the -commands described in this chapter are to be used in vi mode. - -@menu -* Numeric Arguments:: Many commands accept numeric arguments -* Important Keys:: Some very important keys. -* Buffers and Windows:: Commands for handling buffers and windows. -* Files:: Commands for handling files. -* Viewing the Buffer:: How you can view the current buffer. -* Mark Commands:: Marking positions in a buffer. -* Motion Commands:: Commands for moving point. -* Searching and Replacing:: Commands for searching and replacing. -* Modifying Commands:: Commands for modifying the buffer. -* Other Vi Commands:: Miscellaneous Commands. -* Commands in Insert Mode:: Commands for entering insert mode. -@end menu - -@node Numeric Arguments -@section Numeric Arguments - -@cindex numeric arguments -@cindex count -@kindex 061 @kbd{1} (numeric argument) -@kindex 062 @kbd{2} (numeric argument) -@kindex 063 @kbd{3} (numeric argument) -@kindex 064 @kbd{4} (numeric argument) -@kindex 065 @kbd{5} (numeric argument) -@kindex 066 @kbd{6} (numeric argument) -@kindex 067 @kbd{7} (numeric argument) -@kindex 068 @kbd{8} (numeric argument) -@kindex 069 @kbd{9} (numeric argument) - -Most Vi commands accept a @dfn{numeric argument} which can be supplied as -a prefix to the commands. A numeric argument is also called a @dfn{count}. -In many cases, if a count is given, the command is executed that many times. -For instance, @kbd{5 d d} deletes 5 lines while simple @kbd{d d} deletes a -line. In this manual the metavariable @var{n} will denote a count. - -@node Important Keys -@section Important Keys - -The keys @kbd{C-g} and @kbd{C-l} are unique in that their associated -functions are the same in any of emacs, vi and insert mode. - -@table @kbd -@item C-g -@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -Quit. Cancel running or partially typed command (@code{keyboard-quit}). -@item C-l -@kindex 014 @kbd{C-l} (@code{recenter}) -Clear the screen and reprint everything (@code{recenter}). -@end table - -In Emacs many commands are bound to the key strokes that start with -@kbd{C-x}, @kbd{C-c} and @key{ESC}. These commands can be -accessed from vi mode as easily as from emacs mode. - -@table @kbd -@item C-x -@itemx C-c -@itemx @key{ESC} -@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) -@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) -@kindex 033 @kbd{ESC} (@code{vip-ESC}) -Typing one of these keys have the same effect as typing it in emacs mode. -Appropriate command will be executed according as the keys you type after -it. You will be in vi mode again after the execution of the command. -For instance, if you type @kbd{@key{ESC} <} (in vi mode) then the cursor will -move to the beginning of the buffer and you will still be in vi mode. -@item C -@itemx X -@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) -@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) -Typing one of these keys have the effect of typing the corresponding -control character in emacs mode. Moreover, if you type an upper-case -character following it, that character will also be translated to the -corresponding control character. Thus typing @kbd{X W} in vi mode is the -same as typing @kbd{C-x C-w} in emacs mode. You will be in vi mode again -after the execution of a command. -@item \ -@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) -Escape to emacs mode. Hitting the @kbd{\} key will take you to emacs mode, -and you can execute a single Emacs command. After executing the -Emacs command you will be in vi mode again. You can give a count before -typing @kbd{\}. Thus @kbd{5 \ +}, as well as @kbd{\ C-u 5 +}, will insert -@samp{+++++} before point. -@end table - -@node Buffers and Windows -@section Buffers and Windows - -@cindex buffer -@cindex selected buffer -@cindex current buffer - -In Emacs the text you edit is stored in a @dfn{buffer}. -See GNU Emacs Manual, for details. There is always one @dfn{current} -buffer, also called the @dfn{selected buffer}. - -@cindex window -@cindex modified (buffer) - -You can see the contents of buffers through @dfn{windows} created by Emacs. -When you have multiple windows on the screen only one of them is selected. -Each buffer has a unique name, and each window has a mode line which shows -the name of the buffer associated with the window and other information -about the status of the buffer. You can change the format of the mode -line, but normally if you see @samp{**} at the beginning of a mode line it -means that the buffer is @dfn{modified}. If you write out the content of -the buffer to a file, then the buffer will become not modified. Also if -you see @samp{%%} at the beginning of the mode line, it means that the file -associated with the buffer is write protected. - -We have the following commands related to windows and buffers. - -@table @kbd -@item C-n -@kindex 016 @kbd{C-n} (@code{vip-next-window}) -Move cursor to the next-window (@code{vip-next-window}). -@item X 1 -@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) -Delete other windows and make the selected window fill the screen -@*(@code{delete-other-windows}). -@item X 2 -@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) -Split current window into two windows (@code{split-window-vertically}). -@item X 3 -@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) -Show current buffer in two windows. -@item s @var{buffer} @key{RET} -@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) -Select or create a buffer named @var{buffer} (@code{vip-switch-to-buffer}). -@item S @var{buffer} @key{RET} -@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) -Similar but select a buffer named @var{buffer} in another window -@*(@code{vip-switch-to-buffer-other-window}). -@item K -@kindex 113 @kbd{K} (@code{vip-kill-buffer}) -Kill the current buffer if it is not modified or if it is not associated -with a file @*(@code{vip-kill-buffer}). -@item X B -@kindex 1302 @kbd{X B} (@code{list-buffers}) -List the existing buffers (@code{list-buffers}). -@end table - -@cindex buffer name completion - -As @dfn{buffer name completion} is provided, you have only to type in -initial substring of the buffer name which is sufficient to identify it -among names of existing buffers. After that, if you hit @key{TAB} the rest -of the buffer name will be supplied by the system, and you can confirm it -by @key{RET}. The default buffer name to switch to will also be prompted, -and you can select it by giving a simple @key{RET}. See GNU Emacs Manual -for details of completion. - -@node Files -@section Files - -We have the following commands related to files. They are used to visit, -save and insert files. - -@table @kbd -@item v @var{file} @key{RET} -@kindex 166 @kbd{v} (@code{vip-find-file}) -Visit specified file in the current window (@code{vip-find-file}). -@item V @var{file} @key{RET} -@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) -Visit specified file in another window (@code{vip-find-file-other-window}). -@item X S -@kindex 1302 @kbd{X S} (@code{save-buffer}) -Save current buffer to the file associated with the buffer. If no file is -associated with the buffer, the name of the file to write out the content -of the buffer will be asked in the minibuffer. -@item X W @var{file} @key{RET} -@kindex 1302 @kbd{X W} (@code{write-file}) -Write current buffer into a specified file. -@item X I @var{file} @key{RET} -@kindex 1302 @kbd{X I} (@code{insert-file}) -Insert a specified file at point. -@item g -@kindex 147 @kbd{g} (@code{vip-info-on-file}) -Give information on the file associated with the current buffer. Tell you -the name of the file associated with the buffer, the line number of the -current point and total line numbers in the buffer. If no file is -associated with the buffer, this fact will be indicated by the null file -name @samp{""}. -@end table - -@cindex visiting (a file) -@cindex default directory - -In Emacs, you can edit a file by @dfn{visiting} it. If you wish to visit a -file in the current window, you can just type @kbd{v}. Emacs maintains the -@dfn{default directory} which is specific to each buffer. Suppose, for -instance, that the default directory of the current buffer is -@file{/usr/masahiko/lisp/}. Then you will get the following prompt in the -minibuffer. -@example -visit file: /usr/masahiko/lisp/ -@end example -@noindent -@cindex file name completion -If you wish to visit, say, @file{vip.el} in this directory, then you can -just type @samp{vip.el} followed by @key{RET}. If the file @file{vip.el} -already exists in the directory, Emacs will visit that file, and if not, -the file will be created. Emacs will use the file name (@file{vip.el}, in -this case) as the name of the buffer visiting the file. In order to make -the buffer name unique, Emacs may add a suffix (@pxref{Uniquify,,, -emacs, The GNU Emacs Manual}). As @dfn{file name completion} is provided here, you -can sometimes save typing. For instance, suppose there is only one file in the -default directory whose name starts with @samp{v}, that is @samp{vip.el}. -Then if you just type @kbd{v @key{TAB}} then it will be completed to -@samp{vip.el}. Thus, in this case, you just have to type @kbd{v v @key{TAB} -@key{RET}} to visit @file{/usr/masahiko/lisp/vip.el}. Continuing the -example, let us now suppose that you wished to visit the file -@file{/usr/masahiko/man/vip.texinfo}. Then to the same prompt which you get -after you typed @kbd{v}, you can enter @samp{/usr/masahiko/man/vip.texinfo} or -@samp{../man/vip.texinfo} followed by @key{RET}. - -Use @kbd{V} instead of @kbd{v}, if you wish to visit a file in another -window. - -You can verify which file you are editing by typing @kbd{g}. (You can also -type @kbd{X B} to get information on other buffers too.) If you type -@kbd{g} you will get an information like below in the echo area: -@example -"/usr/masahiko/man/vip.texinfo" line 921 of 1949 -@end example - -After you edited the buffer (@samp{vip.texinfo}, in our example) for a while, -you may wish to save it in a file. If you wish to save it in the file -associated with the buffer (@file{/usr/masahiko/man/vip.texinfo}, in this -case), you can just say @kbd{X S}. If you wish to save it in another file, -you can type @kbd{X W}. You will then get a similar prompt as you get for -@kbd{v}, to which you can enter the file name. - -@node Viewing the Buffer -@section Viewing the Buffer - -In this and next section we discuss commands for moving around in the -buffer. These command do not change the content of the buffer. The -following commands are useful for viewing the content of the current -buffer. - -@table @kbd -@item @key{SPC} -@itemx C-f -@kindex 040 @kbd{SPC} (@code{vip-scroll}) -@kindex 006 @kbd{C-f} (@code{vip-scroll-back}) -Scroll text of current window upward almost full screen. You can go -@i{forward} in the buffer by this command (@code{vip-scroll}). -@item @key{RET} -@itemx C-b -@kindex 015 @kbd{RET} (@code{vip-scroll-back}) -@kindex 002 @kbd{C-b} (@code{vip-scroll-back}) -Scroll text of current window downward almost full screen. You can go -@i{backward} in the buffer by this command (@code{vip-scroll-back}). -@item C-d -@kindex 004 @kbd{C-d} (@code{vip-scroll-up}) -Scroll text of current window upward half screen. You can go -@i{down} in the buffer by this command (@code{vip-scroll-down}). -@item C-u -@kindex 025 @kbd{C-u} (@code{vip-scroll-down}) -Scroll text of current window downward half screen. You can go -@i{up} in the buffer by this command (@code{vip-scroll-up}). -@item C-y -@kindex 031 @kbd{C-y} (@code{vip-scroll-down-one}) -Scroll text of current window upward by one line (@code{vip-scroll-down-one}). -@item C-e -@kindex 005 @kbd{C-e} (@code{vip-scroll-up-one}) -Scroll text of current window downward by one line (@code{vip-scroll-up-one}). -@end table -@noindent -You can repeat these commands by giving a count. Thus, @kbd{2 @key{SPC}} -has the same effect as @kbd{@key{SPC} @key{SPC}}. - -The following commands reposition point in the window. - -@table @kbd -@item z H -@itemx z @key{RET} -@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) -@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) -Put point on the top (@i{home}) line in the window. So the current line -becomes the top line in the window. Given a count @var{n}, point will be -placed in the @var{n}-th line from top (@code{vip-line-to-top}). -@item z M -@itemx z . -@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) -@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) -Put point on the @i{middle} line in the window. Given a count @var{n}, -point will be placed in the @var{n}-th line from the middle line -(@code{vip-line-to-middle}). -@item z L -@itemx z - -@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) -@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) -Put point on the @i{bottom} line in the window. Given a count @var{n}, -point will be placed in the @var{n}-th line from bottom -(@code{vip-line-to-bottom}). -@item C-l -Center point in window and redisplay screen (@code{recenter}). -@end table - -@node Mark Commands -@section Mark Commands - -The following commands are used to mark positions in the buffer. - -@table @kbd -@item m @var{ch} -@kindex 155 @kbd{m} (@code{vip-mark-point}) -Store current point in the register @var{ch}. @var{ch} must be a -lower-case @acronym{ASCII} letter. -@item m < -Set mark at the beginning of current buffer. -@item m > -Set mark at the end of current buffer. -@item m . -Set mark at point. -@item m , -Jump to mark (and pop mark off the mark ring). -@end table - -@cindex mark ring - -Emacs uses the @dfn{mark ring} to store marked positions. The commands -@kbd{m <}, @kbd{m >} and @kbd{m .}@: not only set mark but also add it as the -latest element of the mark ring (replacing the oldest one). By repeating -the command `@kbd{m ,}' you can visit older and older marked positions. You -will eventually be in a loop as the mark ring is a ring. - -@node Motion Commands -@section Motion Commands - -Commands for moving around in the current buffer are collected here. These -commands are used as an `argument' for the delete, change and yank commands -to be described in the next section. - -@table @kbd -@item h -@kindex 150 @kbd{h} (@code{vip-backward-char}) -Move point backward by one character. Signal error if point is at the -beginning of buffer, but (unlike Vi) do not complain otherwise -(@code{vip-backward-char}). -@item l -@kindex 154 @kbd{l} (@code{vip-forward-char}) -Move point backward by one character. Signal error if point is at the -end of buffer, but (unlike Vi) do not complain otherwise -(@code{vip-forward-char}). -@item j -@kindex 152 @kbd{j} (@code{vip-next-line}) -Move point to the next line keeping the current column. If point is on the -last line of the buffer, a new line will be created and point will move to -that line (@code{vip-next-line}). -@item k -@kindex 153 @kbd{k} (@code{vip-previous-line}) -Move point to the previous line keeping the current column -(@code{vip-next-line}). -@item + -@kindex 053 @kbd{+} (@code{vip-next-line-at-bol}) -Move point to the next line at the first non-white character. If point is -on the last line of the buffer, a new line will be created and point will -move to the beginning of that line (@code{vip-next-line-at-bol}). -@item - -@kindex 055 @kbd{-} (@code{vip-previous-line-at-bol}) -Move point to the previous line at the first non-white character -(@code{vip-previous-line-at-bol}). -@end table -@noindent -If a count is given to these commands, the commands will be repeated that -many times. - -@table @kbd -@item 0 -@kindex 060 @kbd{0} (@code{vip-beginning-of-line}) -Move point to the beginning of line (@code{vip-beginning-of-line}). -@item ^ -@kindex 136 @kbd{^} (@code{vip-bol-and-skip-white}) -Move point to the first non-white character on the line -(@code{vip-bol-and-skip-white}). -@item $ -@kindex 044 @kbd{$} (@code{vip-goto-eol}) -Move point to the end of line (@code{vip-goto-eol}). -@item @var{n} | -@kindex 174 @kbd{|} (@code{vip-goto-col}) -Move point to the @var{n}-th column on the line (@code{vip-goto-col}). -@end table -@noindent -Except for the @kbd{|} command, these commands neglect a count. - -@cindex word - -@table @kbd -@item w -@kindex 167 @kbd{w} (@code{vip-forward-word}) -Move point forward to the beginning of the next word -(@code{vip-forward-word}). -@item W -@kindex 127 @kbd{W} (@code{vip-forward-Word}) -Move point forward to the beginning of the next word, where a @dfn{word} is -considered as a sequence of non-white characters (@code{vip-forward-Word}). -@item b -@kindex 142 @kbd{b} (@code{vip-backward-word}) -Move point backward to the beginning of a word (@code{vip-backward-word}). -@item B -@kindex 102 @kbd{B} (@code{vip-backward-Word}) -Move point backward to the beginning of a word, where a @i{word} is -considered as a sequence of non-white characters (@code{vip-forward-Word}). -@item e -@kindex 145 @kbd{e} (@code{vip-end-of-word}) -Move point forward to the end of a word (@code{vip-end-of-word}). -@item E -@kindex 105 @kbd{E} (@code{vip-end-of-Word}) -Move point forward to the end of a word, where a @i{word} is -considered as a sequence of non-white characters (@code{vip-end-of-Word}). -@end table -@noindent -@cindex syntax table -Here the meaning of the word `word' for the @kbd{w}, @kbd{b} and @kbd{e} -commands is determined by the @dfn{syntax table} effective in the current -buffer. Each major mode has its syntax mode, and therefore the meaning of -a word also changes as the major mode changes. See GNU Emacs Manual for -details of syntax table. - -@table @kbd -@item H -@kindex 110 @kbd{H} (@code{vip-window-top}) -Move point to the beginning of the @i{home} (top) line of the window. -Given a count @var{n}, go to the @var{n}-th line from top -(@code{vip-window-top}). -@item M -@kindex 115 @kbd{M} (@code{vip-window-middle}) -Move point to the beginning of the @i{middle} line of the window. Given -a count @var{n}, go to the @var{n}-th line from the middle line -(@code{vip-window-middle}). -@item L -@kindex 114 @kbd{L} (@code{vip-window-bottom}) -Move point to the beginning of the @i{lowest} (bottom) line of the -window. Given count, go to the @var{n}-th line from bottom -(@code{vip-window-bottom}). -@end table -@noindent -These commands can be used to go to the desired line visible on the screen. - -@table @kbd -@item ( -@kindex 050 @kbd{(} (@code{vip-backward-sentence}) -Move point backward to the beginning of the sentence -(@code{vip-backward-sentence}). -@item ) -@kindex 051 @kbd{)} (@code{vip-forward-sentence}) -Move point forward to the end of the sentence -(@code{vip-forward-sentence}). -@item @{ -@kindex 173 @kbd{@{} (@code{vip-backward-paragraph}) -Move point backward to the beginning of the paragraph -(@code{vip-backward-paragraph}). -@item @} -@kindex 175 @kbd{@}} (@code{vip-forward-paragraph}) -Move point forward to the end of the paragraph -(@code{vip-forward-paragraph}). -@end table -@noindent -A count repeats the effect for these commands. - -@table @kbd -@item G -@kindex 107 @kbd{G} (@code{vip-goto-line}) -Given a count @var{n}, move point to the @var{n}-th line in the buffer on -the first non-white character. Without a count, go to the end of the buffer -(@code{vip-goto-line}). -@item ` ` -@kindex 140 @kbd{`} (@code{vip-goto-mark}) -Exchange point and mark (@code{vip-goto-mark}). -@item ` @var{ch} -Move point to the position stored in the register @var{ch}. @var{ch} must -be a lower-case letter. -@item ' ' -@kindex 047 @kbd{'} (@code{vip-goto-mark-and-skip-white}) -Exchange point and mark, and then move point to the first non-white -character on the line (@code{vip-goto-mark-and-skip-white}). -@item ' @var{ch} -Move point to the position stored in the register @var{ch} and skip to the -first non-white character on the line. @var{ch} must be a lower-case letter. -@item % -@kindex 045 @kbd{%} (@code{vip-paren-match}) -Move point to the matching parenthesis if point is looking at @kbd{(}, -@kbd{)}, @kbd{@{}, @kbd{@}}, @kbd{[} or @kbd{]} -@*(@code{vip-paren-match}). -@end table -@noindent -The command @kbd{G} mark point before move, so that you can return to the -original point by @kbd{` `}. The original point will also be stored in -the mark ring. - -The following commands are useful for moving points on the line. A count -will repeat the effect. - -@table @kbd -@item f @var{ch} -@kindex 146 @kbd{f} (@code{vip-find-char-forward}) -Move point forward to the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-find-char-forward}). -@item F @var{ch} -@kindex 106 @kbd{F} (@code{vip-find-char-backward}) -Move point backward to the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-find-char-backward}). -@item t @var{ch} -@kindex 164 @kbd{t} (@code{vip-goto-char-forward}) -Move point forward upto the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-goto-char-forward}). -@item T @var{ch} -@kindex 124 @kbd{T} (@code{vip-goto-char-backward}) -Move point backward upto the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-goto-char-backward}). -@item ; -@kindex 073 @kbd{;} (@code{vip-repeat-find}) -Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command -(@code{vip-repeat-find}). -@item , -@kindex 054 @kbd{,} (@code{vip-repeat-find-opposite}) -Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command, in the -opposite direction (@code{vip-repeat-find-opposite}). -@end table - -@node Searching and Replacing -@section Searching and Replacing - -Following commands are available for searching and replacing. - -@cindex regular expression (search) - -@table @kbd -@item / @var{string} @key{RET} -@kindex 057 @kbd{/} (@code{vip-search-forward}) -Search the first occurrence of the string @var{string} forward starting -from point. Given a count @var{n}, the @var{n}-th occurrence of -@var{string} will be searched. If the variable @code{vip-re-search} has value -@code{t} then @dfn{regular expression} search is done and the string -matching the regular expression @var{string} is found. If you give an -empty string as @var{string} then the search mode will change from vanilla -search to regular expression search and vice versa -(@code{vip-search-forward}). -@item ? @var{string} @key{RET} -@kindex 077 @kbd{?} (@code{vip-search-backward}) -Same as @kbd{/}, except that search is done backward -(@code{vip-search-backward}). -@item n -@kindex 156 @kbd{n} (@code{vip-search-next}) -Search the previous search pattern in the same direction as before -(@code{vip-search-next}). -@item N -@kindex 116 @kbd{N} (@code{vip-search-Next}) -Search the previous search pattern in the opposite direction -(@code{vip-search-Next}). -@item C-s -@kindex 023 @kbd{C-s} (@code{isearch-forward}) -Search forward incrementally. See GNU Emacs Manual for details -(@code{isearch-forward}). -@item C-r -@kindex 022 @kbd{C-r} (@code{isearch-backward}) -Search backward incrementally (@code{isearch-backward}). -@cindex vanilla (replacement) -@cindex regular expression (replacement) -@item R @var{string} RET @var{newstring} -@kindex 122 @kbd{R} (@code{vip-replace-string}) -There are two modes of replacement, @dfn{vanilla} and @dfn{regular expression}. -If the mode is @i{vanilla} you will get a prompt @samp{Replace string:}, -and if the mode is @i{regular expression} you will ge a prompt -@samp{Replace regexp:}. The mode is initially @i{vanilla}, but you can -toggle these modes by giving a null string as @var{string}. If the mode is -vanilla, this command replaces every occurrence of @var{string} with -@var{newstring}. If the mode is regular expression, @var{string} is -treated as a regular expression and every string matching the regular -expression is replaced with @var{newstring} (@code{vip-replace-string}). -@item Q @var{string} RET @var{newstring} -@kindex 121 @kbd{Q} (@code{vip-query-replace}) -Same as @kbd{R} except that you will be asked form confirmation before each -replacement -@*(@code{vip-query-replace}). -@item r @var{ch} -@kindex 162 @kbd{r} (@code{vip-replace-char}) -Replace the character point is looking at by the character @var{ch}. Give -count, replace that many characters by @var{ch} (@code{vip-replace-char}). -@end table -@noindent -The commands @kbd{/} and @kbd{?} mark point before move, so that you can -return to the original point by @w{@kbd{` `}}. - -@node Modifying Commands -@section Modifying Commands - -In this section, commands for modifying the content of a buffer are -described. These commands affect the region determined by a motion command -which is given to the commands as their argument. - -@cindex point commands -@cindex line commands - -We classify motion commands into @dfn{point commands} and -@dfn{line commands}. The point commands are as follows: -@example -@kbd{h}, @kbd{l}, @kbd{0}, @kbd{^}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, @kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, @kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,} -@end example -@noindent -The line commands are as follows: -@example -@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, @kbd{@}}, @kbd{G}, @kbd{'} -@end example -@noindent -@cindex expanding (region) -If a point command is given as an argument to a modifying command, the -region determined by the point command will be affected by the modifying -command. On the other hand, if a line command is given as an argument to a -modifying command, the region determined by the line command will be -enlarged so that it will become the smallest region properly containing the -region and consisting of whole lines (we call this process @dfn{expanding -the region}), and then the enlarged region will be affected by the modifying -command. - -@menu -* Delete Commands:: Commands for deleting text. -* Yank Commands:: Commands for yanking text in Vi's sense. -* Put Back Commands:: Commands for putting back deleted/yanked text. -* Change Commands:: Commands for changing text. -* Repeating and Undoing Modifications:: -@end menu -@node Delete Commands -@subsection Delete Commands - -@table @kbd -@item d @var{motion-command} -@kindex 1440 @kbd{d} (@code{vip-command-argument}) -Delete the region determined by the motion command @var{motion-command}. -@end table -@noindent -For example, @kbd{d $} will delete the region between point and end of -current line since @kbd{$} is a point command that moves point to end of line. -@kbd{d G} will delete the region between the beginning of current line and -end of the buffer, since @kbd{G} is a line command. A count given to the -command above will become the count for the associated motion command. -Thus, @kbd{3 d w} will delete three words. - -@kindex 042 @kbd{"} (@code{vip-command-argument}) -It is also possible to save the deleted text into a register you specify. -For example, you can say @kbd{" t 3 d w} to delete three words and save it -to register @kbd{t}. The name of a register is a lower-case letter between -@kbd{a} and @kbd{z}. If you give an upper-case letter as an argument to -a delete command, then the deleted text will be appended to the content of -the register having the corresponding lower-case letter as its name. So, -@kbd{" T d w} will delete a word and append it to register @kbd{t}. Other -modifying commands also accept a register name as their argument, and we -will not repeat similar explanations. - -We have more delete commands as below. - -@table @kbd -@item d d -@kindex 1442 @kbd{d d} -Delete a line. Given a count @var{n}, delete @var{n} lines. -@item d r -@kindex 1442 @kbd{d r} -Delete current region. -@item d R -@kindex 1441 @kbd{d R} -Expand current region and delete it. -@item D -@kindex 104 @kbd{D} (@code{vip-kill-line}) -Delete to the end of a line (@code{vip-kill-line}). -@item x -@kindex 170 @kbd{x} (@code{vip-delete-char}) -Delete a character after point. Given @var{n}, delete @var{n} characters -(@code{vip-delete-char}). -@item @key{DEL} -@kindex 177 @kbd{DEL} (@code{vip-delete-backward-char}) -Delete a character before point. Given @var{n}, delete @var{n} characters -(@code{vip-delete-backward-char}). -@end table - -@node Yank Commands -@subsection Yank Commands - -@cindex yank - -Yank commands @dfn{yank} a text of buffer into a (usually anonymous) register. -Here the word `yank' is used in Vi's sense. Thus yank commands do not -alter the content of the buffer, and useful only in combination with -commands that put back the yanked text into the buffer. - -@table @kbd -@item y @var{motion-command} -@kindex 1710 @kbd{y} (@code{vip-command-argument}) -Yank the region determined by the motion command @var{motion-command}. -@end table -@noindent -For example, @kbd{y $} will yank the text between point and the end of line -into an anonymous register, while @kbd{"c y $} will yank the same text into -register @kbd{c}. - -Use the following command to yank consecutive lines of text. - -@table @kbd -@item y y -@itemx Y -@kindex 131 @kbd{Y} (@code{vip-yank-line}) -@kindex 1712 @kbd{y y} (@code{vip-yank-line}) -Yank a line. Given @var{n}, yank @var{n} lines (@code{vip-yank-line}). -@item y r -@kindex 1712 @kbd{y r} -Yank current region. -@item y R -@kindex 1711 @kbd{y R} -Expand current region and yank it. -@end table - -@node Put Back Commands -@subsection Put Back Commands -Deleted or yanked texts can be put back into the buffer by the command -below. - -@table @kbd -@item p -@kindex 160 @kbd{p} (@code{vip-put-back}) -Insert, after the character point is looking at, most recently -deleted/yanked text from anonymous register. Given a register name -argument, the content of the named register will be put back. Given a -count, the command will be repeated that many times. This command also -checks if the text to put back ends with a new line character, and if so -the text will be put below the current line (@code{vip-put-back}). -@item P -@kindex 120 @kbd{P} (@code{vip-Put-back}) -Insert at point most recently deleted/yanked text from anonymous register. -Given a register name argument, the content of the named register will -be put back. Given a count, the command will be repeated that many times. -This command also checks if the text to put back ends with a new line -character, and if so the text will be put above the current line rather -than at point (@code{vip-Put-back}). -@end table -@noindent -@cindex number register -Thus, @kbd{" c p} will put back the content of the register @kbd{c} into the -buffer. It is also possible to specify @dfn{number register} which is a -numeral between @kbd{1} and @kbd{9}. If the number register @var{n} is -specified, @var{n}-th previously deleted/yanked text will be put back. It -is an error to specify a number register for the delete/yank commands. - -@node Change Commands -@subsection Change Commands - -Most commonly used change command takes the following form. - -@table @kbd -@item c @var{motion-command} -@kindex 1430 @kbd{c} (@code{vip-command-argument}) -Replace the content of the region determined by the motion command -@var{motion-command} by the text you type. If the motion command is a -point command then you will type the text into minibuffer, and if the -motion command is a line command then the region will be deleted first and -you can insert the text in @var{insert mode}. -@end table -@noindent -For example, if point is at the beginning of a word @samp{foo} and you -wish to change it to @samp{bar}, you can type @kbd{c w}. Then, as @kbd{w} -is a point command, you will get the prompt @samp{foo =>} in the -minibuffer, for which you can type @kbd{b a r @key{RET}} to complete the change -command. - -@table @kbd -@item c c -@kindex 1432 @kbd{c c} -Change a line. Given a count, that many lines are changed. -@item c r -@kindex 1432 @kbd{c r} -Change current region. -@item c R -@kindex 1431 @kbd{c R} -Expand current region and change it. -@end table - -@node Repeating and Undoing Modifications -@subsection Repeating and Undoing Modifications - -VIP records the previous modifying command, so that it is easy to repeat -it. It is also very easy to undo changes made by modifying commands. - -@table @kbd -@item u -@kindex 165 @kbd{u} (@code{vip-undo}) -Undo the last change. You can undo more by repeating undo by the repeat -command @samp{.}. For example, you can undo 5 previous changes by typing -@samp{u....}. If you type @samp{uu}, then the second @samp{u} undoes the -first undo command (@code{vip-undo}). -@item . -@kindex 056 @kbd{.} (@code{vip-repeat}) -Repeat the last modifying command. Given count @var{n} it becomes the new -count for the repeated command. Otherwise, the count for the last -modifying command is used again (@code{vip-repeat}). -@end table - -@node Other Vi Commands -@section Other Vi Commands - -Miscellaneous Vi commands are collected here. - -@table @kbd -@item Z Z -@kindex 132 @kbd{Z Z} (@code{save-buffers-kill-emacs}) -Exit Emacs. If modified buffers exist, you will be asked whether you wish -to save them or not (@code{save-buffers-kill-emacs}). -@item !@: @var{motion-command} @var{format-command} -@itemx @var{n} !@: !@: @var{format-command} -@kindex 041 @kbd{!} (@code{vip-command-argument}) -The region determined by the motion command @var{motion-command} will be -given to the shell command @var{format-command} and the region will be -replaced by its output. If a count is given, it will be passed to -@var{motion-command}. For example, @samp{3!Gsort} will sort the region -between point and the 3rd line. If @kbd{!} is used instead of -@var{motion-command} then @var{n} lines will be processed by -@var{format-command} (@code{vip-command-argument}). -@item J -@kindex 112 @kbd{J} (@code{vip-join-lines}) -Join two lines. Given count, join that many lines. A space will be -inserted at each junction (@code{vip-join-lines}). -@item < @var{motion-command} -@itemx @var{n} < < -@kindex 074 @kbd{<} (@code{vip-command-argument}) -Shift region determined by the motion command @var{motion-command} to -left by @var{shift-width} (default is 8). If @kbd{<} is used instead of -@var{motion-command} then shift @var{n} lines -@*(@code{vip-command-argument}). -@item > @var{motion-command} -@itemx @var{n} > > -@kindex 076 @kbd{>} (@code{vip-command-argument}) -Shift region determined by the motion command @var{motion-command} to -right by @var{shift-width} (default is 8). If @kbd{<} is used instead of -@var{motion-command} then shift @var{n} lines -@*(@code{vip-command-argument}). -@item = @var{motion-command} -@kindex 075 @kbd{=} (@code{vip-command-argument}) -Indent region determined by the motion command @var{motion-command}. If -@kbd{=} is used instead of @var{motion-command} then indent @var{n} lines -(@code{vip-command-argument}). -@item * -@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) -Call last remembered keyboard macro. -@item # -A new vi operator. @xref{New Commands}, for more details. -@end table - -The following keys are reserved for future extensions, and currently -assigned to a function that just beeps (@code{vip-nil}). - -@kindex 046 @kbd{&} (@code{vip-nil}) -@kindex 100 @kbd{@@} (@code{vip-nil}) -@kindex 125 @kbd{U} (@code{vip-nil}) -@kindex 133 @kbd{[} (@code{vip-nil}) -@kindex 135 @kbd{]} (@code{vip-nil}) -@kindex 137 @kbd{_} (@code{vip-nil}) -@kindex 161 @kbd{q} (@code{vip-nil}) -@kindex 176 @kbd{~} (@code{vip-nil}) - -@example -&, @@, U, [, ], _, q, ~ -@end example - -VIP uses a special local keymap to interpret key strokes you enter in vi -mode. The following keys are bound to @code{nil} in the keymap. Therefore, -these keys are interpreted by the global keymap of Emacs. We give below a -short description of the functions bound to these keys in the global -keymap. See GNU Emacs Manual for details. - -@table @kbd -@item C-@@ -@kindex 000 @kbd{C-@@} (@code{set-mark-command}) -Set mark and push previous mark on mark ring (@code{set-mark-command}). -@item TAB -@kindex 011 TAB (@code{indent-for-tab-command}) -Indent line for current major mode (@code{indent-for-tab-command}). -@item C-j -@kindex 012 @kbd{C-j} (@code{electric-newline-and-maybe-indent}) -Insert a newline, and maybe indent according to mode. -@item C-k -@kindex 013 @kbd{C-k} (@code{kill-line}) -Kill the rest of the current line; before a newline, kill the newline. -With a numeric argument, kill that many lines from point. Negative arguments -kill lines backward (@code{kill-line}). -@item C-l -@kindex 014 @kbd{C-l} (@code{recenter}) -Clear the screen and reprint everything (@code{recenter}). -@item @var{n} C-p -@kindex 020 @kbd{C-p} (@code{previous-line}) -Move cursor vertically up @var{n} lines (@code{previous-line}). -@item C-q -@kindex 021 @kbd{C-q} (@code{quoted-insert}) -Read next input character and insert it. Useful for inserting control -characters -@*(@code{quoted-insert}). -@item C-r -@kindex 022 @kbd{C-r} (@code{isearch-backward}) -Search backward incrementally (@code{isearch-backward}). -@item C-s -@kindex 023 @kbd{C-s} (@code{isearch-forward}) -Search forward incrementally (@code{isearch-forward}). -@item @var{n} C-t -@kindex 024 @kbd{C-t} (@code{transpose-chars}) -Interchange characters around point, moving forward one character. With -count @var{n}, take character before point and drag it forward past @var{n} -other characters. If no argument and at end of line, the previous two -characters are exchanged (@code{transpose-chars}). -@item @var{n} C-v -@kindex 026 @kbd{C-v} (@code{scroll-up}) -Scroll text upward @var{n} lines. If @var{n} is not given, scroll near -full screen (@code{scroll-up}). -@item C-w -@kindex 027 @kbd{C-w} (@code{kill-region}) -Kill between point and mark. The text is save in the kill ring. The -command @kbd{P} or @kbd{p} can retrieve it from kill ring -(@code{kill-region}). -@end table - -@node Commands in Insert Mode -@section Insert Mode - -You can enter insert mode by one of the following commands. In addition to -these, you will enter insert mode if you give a change command with a line -command as the motion command. Insert commands are also modifying commands -and you can repeat them by the repeat command @kbd{.} (@code{vip-repeat}). - -@table @kbd -@item i -@kindex 151 @kbd{i} (@code{vip-insert}) -Enter insert mode at point (@code{vip-insert}). -@item I -@kindex 111 @kbd{I} (@code{vip-Insert}) -Enter insert mode at the first non white character on the line -(@code{vip-Insert}). -@item a -@kindex 141 @kbd{a} (@code{vip-append}) -Move point forward by one character and then enter insert mode -(@code{vip-append}). -@item A -@kindex 101 @kbd{A} (@code{vip-Append}) -Enter insert mode at end of line (@code{vip-Append}). -@item o -@kindex 157 @kbd{o} (@code{vip-open-line}) -Open a new line below the current line and enter insert mode -(@code{vip-open-line}). -@item O -@kindex 117 @kbd{O} (@code{vip-Open-line}) -Open a new line above the current line and enter insert mode -(@code{vip-Open-line}). -@item C-o -@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) -Insert a newline and leave point before it, and then enter insert mode -@*(@code{vip-open-line-at-point}). -@end table - -Insert mode is almost like emacs mode. Only the following 4 keys behave -differently from emacs mode. - -@table @kbd -@item @key{ESC} -@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) -This key will take you back to vi mode (@code{vip-change-mode-to-vi}). -@item C-h -@kindex 010 @kbd{C-h} (@code{delete-backward-char}) (insert mode) -Delete previous character (@code{delete-backward-char}). -@item C-w -@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) -Delete previous word (@code{vip-delete-backward-word}). -@item C-z -@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) -This key simulates @key{ESC} key in emacs mode. For instance, typing -@kbd{C-z x} in insert mode is the same as typing @kbd{ESC x} in emacs mode -(@code{vip-ESC}). -@end table -@noindent -You can also bind @kbd{C-h} to @code{help-command} if you like. -(@xref{Customizing Key Bindings}, for details.) Binding @kbd{C-h} to -@code{help-command} has the effect of making the meaning of @kbd{C-h} -uniform among emacs, vi and insert modes. - -When you enter insert mode, VIP records point as the start point of -insertion, and when you leave insert mode the region between point and -start point is saved for later use by repeat command etc. Therefore, repeat -command will not really repeat insertion if you move point by emacs -commands while in insert mode. - -@node Ex Commands -@chapter Ex Commands - -@kindex 072 @kbd{:} (@code{vip-ex}) - -In vi mode, you can execute an Ex command @var{ex-command} by typing: -@example -@kbd{:@: @var{ex-command} @key{RET}} -@end example -Every Ex command follows the following pattern: -@example -@var{address command} @kbd{!}@: @var{parameters count flags} -@end example -@noindent -@cindex address -where all parts are optional. For the syntax of @dfn{address}, the reader -is referred to the reference manual of Ex. - -@cindex magic -@cindex regular expression - -In the current version of VIP, searching by Ex commands is always -@dfn{magic}. That is, search patterns are always treated as @dfn{regular -expressions}. For example, a typical forward search would be invoked by -@kbd{:/@var{pat}/}. If you wish to include @samp{/} as part of -@var{pat} you must preceded it by @samp{\}. VIP strips off these @kbd{\}'s -before @kbd{/} and the resulting @var{pat} becomes the actual search -pattern. Emacs provides a different and richer class or regular -expressions than Vi/Ex, and VIP uses Emacs's regular expressions. See GNU -Emacs Manual for details of regular expressions. - -Several Ex commands can be entered in a line by separating them by a pipe -character @samp{|}. - -@menu -* Ex Command Reference:: Explain all the Ex commands available in VIP. -@end menu -@node Ex Command Reference -@section Ex Command Reference -In this section we briefly explain all the Ex commands supported by VIP@. -Most Ex commands expect @var{address} as their argument, and they use -default addresses if they are not explicitly given. In the following, such -default addresses will be shown in parentheses. - -Most command names can and preferably be given in abbreviated forms. In -the following, optional parts of command names will be enclosed in -brackets. For example, @samp{co[py]} will mean that copy command can be -give as @samp{co} or @samp{cop} or @samp{copy}. - -If @var{command} is empty, point will move to the beginning of the line -specified by the @var{address}. If @var{address} is also empty, point will -move to the beginning of the current line. - -@cindex flag - -Some commands accept @dfn{flags} which are one of @kbd{p}, @kbd{l} and -@kbd{#}. If @var{flags} are given, the text affected by the commands will -be displayed on a temporary window, and you will be asked to hit return to -continue. In this way, you can see the text affected by the commands -before the commands will be executed. If you hit @kbd{C-g} instead of -@key{RET} then the commands will be aborted. Note that the meaning of -@var{flags} is different in VIP from that in Vi/Ex. - -@table @kbd -@item (.,.@:) co[py] @var{addr} @var{flags} -@itemx (.,.@:) t @var{addr} @var{flags} -Place a copy of specified lines after @var{addr}. If @var{addr} is -@kbd{0}, it will be placed before the first line. -@item (.,.@:) d[elete] @var{register} @var{count} @var{flags} -Delete specified lines. Text will be saved in a named @var{register} if a -lower-case letter is given, and appended to a register if a capital letter is -given. -@item e[dit] !@: +@var{addr} @var{file} -@itemx e[x] !@: +@var{addr} @var{file} -@itemx vi[sual] !@: +@var{addr} @var{file} -Edit a new file @var{file} in the current window. The command will abort -if current buffer is modified, which you can override by giving @kbd{!}. -If @kbd{+}@var{addr} is given, @var{addr} becomes the current line. -@item file -Give information about the current file. -@item (1,$) g[lobal] !@: /@var{pat}/ @var{cmds} -@itemx (1,$) v /@var{pat}/ @var{cmds} -Among specified lines first mark each line which matches the regular -expression @var{pat}, and then execute @var{cmds} on each marked line. -If @kbd{!}@: is given, @var{cmds} will be executed on each line not matching -@var{pat}. @kbd{v} is same as @kbd{g!}. -@item (.,.+1) j[oin] !@: @var{count} @var{flags} -Join specified lines into a line. Without @kbd{!}, a space character will -be inserted at each junction. -@item (.@:) k @var{ch} -@itemx (.@:) mar[k] @var{ch} -Mark specified line by a lower-case character @var{ch}. Then the -addressing form @kbd{'}@var{ch} will refer to this line. No white space is -required between @kbd{k} and @var{ch}. A white space is necessary between -@kbd{mark} and @var{ch}, however. -@item map @var{ch} @var{rhs} -Define a macro for vi mode. After this command, the character @var{ch} -will be expanded to @var{rhs} in vi mode. -@item (.,.@:) m[ove] @var{addr} -Move specified lines after @var{addr}. -@item (.@:) pu[t] @var{register} -Put back previously deleted or yanked text. If @var{register} is given, -the text saved in the register will be put back; otherwise, last deleted or -yanked text will be put back. -@item q[uit] ! -Quit from Emacs. If modified buffers with associated files exist, you will -be asked whether you wish to save each of them. At this point, you may -choose not to quit, by hitting @kbd{C-g}. If @kbd{!}@: is given, exit from -Emacs without saving modified buffers. -@item (.@:) r[ead] @var{file} -Read in the content of the file @var{file} after the specified line. -@item (.@:) r[ead] !@: @var{command} -Read in the output of the shell command @var{command} after the specified -line. -@item se[t] -Set a variable's value. @xref{Customizing Constants}, for the list of variables -you can set. -@item sh[ell] -Run a subshell in a window. -@item (.,.@:) s[ubstitute] /@var{pat}/@var{repl}/ @var{options} @var{count} @var{flags} -@itemx (.,.@:) & @var{options} @var{count} @var{flags} -On each specified line, the first occurrence of string matching regular -expression @var{pat} is replaced by replacement pattern @var{repl}. Option -characters are @kbd{g} and @kbd{c}. If global option character @kbd{g} -appears as part of @var{options}, all occurrences are substituted. If -confirm option character @kbd{c} appears, you will be asked to give -confirmation before each substitution. If @kbd{/@var{pat}/@var{repl}/} is -missing, the last substitution is repeated. -@item st[op] -Suspend Emacs. -@item ta[g] @var{tag} -@cindex tag -@cindex selected tags table -Find first definition of @var{tag}. If no @var{tag} is given, previously -given @var{tag} is used and next alternate definition is find. By default, -the file @file{TAGS} in the current directory becomes the @dfn{selected tags -table}. You can select another tags table by @kbd{set} command. -@xref{Customizing Constants}, for details. -@item und[o] -Undo the last change. -@item unm[ap] @var{ch} -The macro expansion associated with @var{ch} is removed. -@item ve[rsion] -Tell the version number of VIP. -@item (1,$) w[rite] !@: @var{file} -Write out specified lines into file @var{file}. If no @var{file} is given, -text will be written to the file associated to the current buffer. Unless -@kbd{!}@: is given, if @var{file} is different from the file associated to -the current buffer and if the file @var{file} exists, the command will not -be executed. Unlike Ex, @var{file} becomes the file associated to the -current buffer. -@item (1,$) w[rite]>> @var{file} -Write out specified lines at the end of file @var{file}. @var{file} -becomes the file associated to the current buffer. -@item (1,$) wq !@: @var{file} -Same as @kbd{write} and then @kbd{quit}. If @kbd{!}@: is given, same as -@kbd{write !}@: then @kbd{quit}. -@item (.,.) y[ank] @var{register} @var{count} -Save specified lines into register @var{register}. If no register is -specified, text will be saved in an anonymous register. -@item @var{addr} !@: @var{command} -Execute shell command @var{command}. The output will be shown in a new -window. If @var{addr} is given, specified lines will be used as standard -input to @var{command}. -@item ($) = -Print the line number of the addressed line. -@item (.,.) > @var{count} @var{flags} -Shift specified lines to the right. The variable @code{vip-shift-width} -(default value is 8) determines the amount of shift. -@item (.,.) < @var{count} @var{flags} -Shift specified lines to the left. The variable @code{vip-shift-width} -(default value is 8) determines the amount of shift. -@item (.,.@:) ~ @var{options} @var{count} @var{flags} -Repeat the previous @kbd{substitute} command using previous search pattern -as @var{pat} for matching. -@end table - -The following Ex commands are available in Vi, but not implemented in VIP. -@example -@kbd{abbreviate}, @kbd{list}, @kbd{next}, @kbd{print}, @kbd{preserve}, @kbd{recover}, @kbd{rewind}, @kbd{source}, -@kbd{unabbreviate}, @kbd{xit}, @kbd{z} -@end example - -@node Customization -@chapter Customization - -If you have a file called @file{~/.emacs.d/vip} (or @file{~/.vip}), then it -will also be loaded when VIP is loaded. This file is thus useful for -customizing VIP. - -@menu -* Customizing Constants:: How to change values of constants. -* Customizing Key Bindings:: How to change key bindings. -@end menu - -@node Customizing Constants -@section Customizing Constants -An easy way to customize VIP is to change the values of constants used -in VIP@. Here is the list of the constants used in VIP and their default -values. - -@table @code -@item vip-shift-width 8 -The number of columns shifted by @kbd{>} and @kbd{<} command. -@item vip-re-replace nil -If @code{t} then do regexp replace, if @code{nil} then do string replace. -@item vip-search-wrap-around t -If @code{t}, search wraps around the buffer. -@item vip-re-search nil -If @code{t} then search is reg-exp search, if @code{nil} then vanilla -search. -@item vip-case-fold-search nil -If @code{t} search ignores cases. -@item vip-re-query-replace nil -If @code{t} then do reg-exp replace in query replace. -@item vip-open-with-indent nil -If @code{t} then indent to the previous current line when open a new line -by @kbd{o} or @kbd{O} command. -@item vip-tags-file-name "TAGS" -The name of the file used as the tags table. -@item vip-help-in-insert-mode nil -If @code{t} then @key{C-h} is bound to @code{help-command} in insert mode, -if @code{nil} then it sis bound to @code{delete-backward-char}. -@end table -@noindent -You can reset these constants in VIP by the Ex command @kbd{set}. Or you -can include a line like this in your @file{~/.emacs.d/vip} file: -@example -(setq vip-case-fold-search t) -@end example - -@node Customizing Key Bindings -@section Customizing Key Bindings - -@cindex local keymap - -VIP uses @code{vip-command-mode-map} as the @dfn{local keymap} for vi mode. -For example, in vi mode, @key{SPC} is bound to the function -@code{vip-scroll}. But, if you wish to make @key{SPC} and some other keys - behave like Vi, you can include the following lines in your -@file{~/.emacs.d/vip} file. - -@example -(define-key vip-command-mode-map "\C-g" 'vip-info-on-file) -(define-key vip-command-mode-map "\C-h" 'vip-backward-char) -(define-key vip-command-mode-map "\C-m" 'vip-next-line-at-bol) -(define-key vip-command-mode-map " " 'vip-forward-char) -(define-key vip-command-mode-map "g" 'vip-keyboard-quit) -(define-key vip-command-mode-map "s" 'vip-substitute) -(define-key vip-command-mode-map "C" 'vip-change-to-eol) -(define-key vip-command-mode-map "R" 'vip-change-to-eol) -(define-key vip-command-mode-map "S" 'vip-substitute-line) -(define-key vip-command-mode-map "X" 'vip-delete-backward-char) -@end example - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - - -@unnumbered Key Index - -@printindex ky - -@unnumbered Concept Index -@printindex cp - -@bye diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi deleted file mode 100644 index ae122f5aae4..00000000000 --- a/doc/misc/viper.texi +++ /dev/null @@ -1,4552 +0,0 @@ -% -*-texinfo-*- -\input texinfo - -@comment Using viper.info instead of viper in setfilename breaks DOS. -@comment @setfilename viper -@comment @setfilename viper.info -@setfilename ../../info/viper - -@documentencoding UTF-8 - -@copying -Copyright @copyright{} 1995--1997, 2001--2014 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual.'' -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* VIPER: (viper). A VI-emulation mode for Emacs. -@end direntry - -@finalout - -@titlepage -@title Viper Is a Package for Emacs Rebels -@subtitle a Vi emulator for Emacs -@subtitle November 2008, Viper Version 3.11.2 - -@author Michael Kifer (Viper) -@author Aamod Sane (VIP 4.4) -@author Masahiko Sato (VIP 3.5) - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Viper - -We believe that one or more of the following statements are adequate -descriptions of Viper: - -@example -Viper Is a Package for Emacs Rebels; -it is a VI Plan for Emacs Rescue -and/or a venomous VI PERil. -@end example - -Technically speaking, Viper is a Vi emulation package for Emacs. It -implements all Vi and Ex commands, occasionally improving on them and -adding many new features. It gives the user the best of both worlds: Vi -keystrokes for editing combined with the power of the Emacs environment. - -Viper emulates Vi at several levels, from the one that closely follows Vi -conventions to the one that departs from many of them. It has many -customizable options, which can be used to tailor Viper to the work habits -of various users. -This manual describes Viper, concentrating on the differences from Vi and -new features of Viper. - -Viper, formerly known as VIP-19, was written by Michael Kifer. It is based -on VIP version 3.5 by Masahiko Sato and VIP version 4.4 by Aamod Sane. -About 15% of the code still comes from those older packages. - -Viper is intended to be usable without reading this manual; the defaults -are set to make Viper as close to Vi as possible. At startup, Viper will -try to set the most appropriate default environment for you, based on -your familiarity with Emacs. It will also tell you the basic GNU Emacs window -management commands to help you start immediately. - -Although this manual explains how to customize Viper, some basic -familiarity with Emacs Lisp is a plus. - -It is recommended that you read the Overview node. The other nodes may -be visited as needed. - -Comments and bug reports are welcome. -@code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. -Please use the Ex command @kbd{:submitReport} for this purpose. - -@insertcopying -@end ifnottex - -@menu -* Overview:: Read for a smoother start -* Improvements over Vi:: New features, Improvements -* Customization:: How to customize Viper -* Commands:: Vi and Ex Commands -* GNU Free Documentation License:: The license for this documentation. -* Acknowledgments:: -* Key Index:: Index of Vi and Ex Commands -* Function Index:: Index of Viper Functions -* Variable Index:: Index of Viper Variables -* Package Index:: Index of Packages Mentioned in this Document -* Concept Index:: Vi, Ex and Emacs concepts -@end menu -@iftex -@unnumbered Introduction - -We believe that one or more of the following statements are adequate -descriptions of Viper: - -@example -Viper Is a Package for Emacs Rebels; -it is a VI Plan for Emacs Rescue -and/or a venomous VI PERil. -@end example - -Viper is a Vi emulation package for Emacs. Viper contains virtually all -of Vi and Ex functionality and much more. It gives you the best of both -worlds: Vi keystrokes for editing combined with the GNU Emacs -environment. Viper also fixes some common complaints with Vi commands. -This manual describes Viper, concentrating on the differences from Vi -and on the new features of Viper. - -Viper was written by Michael Kifer. It is based on VIP version 3.5 by -Masahiko Sato and VIP version 4.4 by Aamod Sane. About 15% of the code -still comes from those older packages. - -Viper is intended to be usable out of the box, without reading this manual; -the defaults are set to make Viper as close to Vi as possible. At -startup, Viper will attempt to set the most appropriate default environment -for you, based on your familiarity with Emacs. It will also tell you the -basic GNU Emacs window management commands to help you start immediately. - -Although this manual explains how to customize Viper, some basic -familiarity with Emacs Lisp is a plus. - -It is recommended that you read the chapter Overview. The other chapters -will be useful for customization and advanced usage. - -You should also learn to use the Info on-line hypertext manual system that -comes with Emacs. This manual can be read as an Info file. Try the command -@kbd{@key{ESC} x info} with vanilla Emacs sometime. - -Comments and bug reports are welcome. -@code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. -Please use the Ex command @kbd{:submitReport} for this purpose. - -@end iftex - -@node Overview -@chapter Overview of Viper - -Viper is a Vi emulation on top of Emacs. At the same time, Viper provides a -virtually unrestricted access to Emacs facilities. Perfect compatibility -with Vi is possible but not desirable. This chapter tells you about the -Emacs ideas that you should know about, how to use Viper within Emacs and -some incompatibilities. - -This manual is written with the assumption that you are an experienced Vi -user who wants to switch to Emacs while retaining the ability to edit files -Vi style. Incredible as it might seem, there are experienced Emacs users -who use Viper as a backdoor into the superior (as every Vi user already knows) -world of Vi! These users are well familiar with Emacs bindings and prefer them -in some cases, especially in the Vi Insert state. John Hawkins - has provided a set of customizations, which -enables additional Emacs bindings under Viper. These customizations can be -included in your @file{~/.emacs.d/viper} file and are found at the -following URL: @file{http://traeki.freeshell.org/files/viper-sample}. - -@menu -* Emacs Preliminaries:: Basic concepts in Emacs. -* Loading Viper:: Loading and Preliminary Configuration. -* States in Viper:: Viper has four states orthogonal to Emacs - modes. -* The Minibuffer:: Command line in Emacs. -* Multiple Files in Viper:: True multiple file handling. -* Unimplemented Features:: That are unlikely to be implemented. -@end menu - -@node Emacs Preliminaries -@section Emacs Preliminaries - -@cindex buffer -@cindex point -@cindex mark -@cindex text -@cindex looking at -@cindex end (of buffer) -@cindex end (of line) -@cindex region - -Emacs can edit several files at once. A file in Emacs is placed in a -@dfn{buffer} that usually has the same name as the file. Buffers are also used -for other purposes, such as shell interfaces, directory editing, etc. -@xref{Dired,,Directory Editor,emacs,The -GNU Emacs Manual}, for an example. - -A buffer has a distinguished position called the @dfn{point}. -A @dfn{point} is always between 2 characters, and is @dfn{looking at} -the right hand character. The cursor is positioned on the right hand -character. Thus, when the @dfn{point} is looking at the end-of-line, -the cursor is on the end-of-line character, i.e., beyond the last -character on the line. This is the default Emacs behavior. - -The default settings of Viper try to mimic the behavior of Vi, preventing -the cursor from going beyond the last character on the line. By using -Emacs commands directly (such as those bound to arrow keys), it is possible -to get the cursor beyond the end-of-line. However, this won't (or -shouldn't) happen if you restrict yourself to standard Vi keys, unless you -modify the default editing style. @xref{Customization}. - -In addition to the @dfn{point}, there is another distinguished buffer -position called the @dfn{mark}. @xref{Mark,,Mark,emacs,The GNU Emacs -manual}, for more info on the mark. The text between the @dfn{point} and -the @dfn{mark} is called the @dfn{region} of the buffer. For the Viper -user, this simply means that in addition to the Vi textmarkers a--z, there -is another marker called @dfn{mark}. This is similar to the unnamed Vi -marker used by the jump commands @kbd{``} and @kbd{''}, which move the -cursor to the position of the last absolute jump. Viper provides access to -the region in most text manipulation commands as @kbd{r} and @kbd{R} suffix -to commands that operate on text regions, e.g., @kbd{dr} to delete region, -etc. - -Furthermore, Viper lets Ex-style commands to work on the current region. -This is done by typing a digit argument before @kbd{:}. For instance, -typing @kbd{1:} will prompt you with something like @emph{:123,135}, -assuming that the current region starts at line 123 and ends at line -135. There is no need to type the line numbers, since Viper inserts them -automatically in front of the Ex command. - -@xref{Basics}, for more info. - -@cindex window -@cindex mode line -@cindex buffer information -@cindex Minibuffer -@cindex command line -@cindex buffer (modified) - -Emacs divides the screen into tiled @dfn{windows}. You can see the -contents of a buffer through the window associated with the buffer. The -cursor of the screen is positioned on the character after @dfn{point}. -Every window has a @dfn{mode line} that displays information about the buffer. -You can change the format of the mode -line, but normally if you see @samp{**} at the beginning of a mode line it -means that the buffer is @dfn{modified}. If you write out the contents of -a buffer to a file, then the buffer will become not modified. Also if -you see @samp{%%} at the beginning of the mode line, it means that the file -associated with the buffer is write protected. The mode line will also -show the buffer name and current major and minor modes (see below). -A special buffer called @dfn{Minibuffer} is displayed as the last line -in a minibuffer window. The minibuffer window is used for command input -output. Viper uses minibuffer window for @kbd{/} and @kbd{:} -commands. - -@cindex mode -@cindex keymap -@cindex local keymap -@cindex global keymap -@cindex major mode -@cindex minor mode - -An Emacs buffer can have a @dfn{major mode} that customizes Emacs for -editing text of a particular sort by changing the functionality of the keys. -Keys are defined using a @dfn{keymap} that records the bindings between -keystrokes and -functions. The @dfn{global keymap} is common to all the -buffers. Additionally, each buffer has its @dfn{local keymap} that determines the -@dfn{mode} of the buffer. If a function is bound to some key in the local -keymap then that function will be executed when you type the key. -If no function is bound to a key in the -local map, however, the function bound to the key in the global map -will be executed. @xref{Major Modes,Major Modes,Major Modes,emacs,The -GNU Emacs Manual}, for more information. - -A buffer can also have a @dfn{minor mode}. Minor modes are options that -you can use or not. A buffer in @code{text-mode} can have -@code{auto-fill-mode} as minor mode, which can be turned off or on at -any time. In Emacs, a minor mode may have it own keymap, -which overrides the local keymap when the minor mode is turned on. For -more information, @pxref{Minor Modes,Minor Modes,Minor Modes,emacs,The -GNU Emacs Manual}. - -@cindex Viper as minor mode -@cindex Control keys -@cindex Meta key - -Viper is implemented as a collection of minor modes. Different minor modes -are involved when Viper emulates Vi command mode, Vi insert mode, etc. -You can also turn Viper on and off at any time while in Vi command mode. -@xref{States in Viper}, for -more information. - -Emacs uses Control and Meta modifiers. These are denoted as C and M, -e.g., @kbd{^Z} as @kbd{C-z} and @kbd{Meta-x} as @kbd{M-x}. The Meta key is -usually located on each side of the Space bar; it is used in a manner -similar to the Control key, e.g., @kbd{M-x} means typing @kbd{x} while -holding the Meta key down. For keyboards that do not have a Meta key, -@key{ESC} is used as Meta. Thus @kbd{M-x} is typed as @kbd{@key{ESC} -x}. Viper uses @key{ESC} to switch from Insert state to Vi state. Therefore -Viper defines @kbd{C-\} as its Meta key in Vi state. @xref{Vi State}, for -more info. - -Emacs is structured as a Lisp interpreter around a C core. Emacs keys -cause Lisp functions to be called. It is possible to call these -functions directly, by typing @kbd{M-x function-name}. - -@node Loading Viper -@section Loading Viper - -The most common way to load it automatically is to include the following -lines (in the given order!): - -@lisp -(setq viper-mode t) -(require 'viper) -@end lisp - -@noindent -in your @file{~/.emacs} file. The @file{.emacs} file is placed in your -home directory and it is be executed every time you invoke Emacs. This is -the place where all general Emacs customization takes place. Beginning with -version 20.0, Emacsen have an interactive interface, which simplifies the -job of customization significantly. - -Viper also uses the file @file{~/.emacs.d/viper} for Viper-specific customization. -The location of Viper customization file can be changed by setting the -variable @code{viper-custom-file-name} in @file{.emacs} @emph{prior} to loading -Viper. - -The latest versions of Emacs have an interactive customization facility, -which allows you to (mostly) bypass the use of the @file{.emacs} and -@code{viper-custom-file-name} files. You can reach this customization -facility from within Viper's VI state by executing the Ex command -@kbd{:customize}. - -Once invoked, Viper will arrange to bring up Emacs buffers in Vi state -whenever this makes sense. -@xref{Packages that Change Keymaps}, to find out when forcing Vi command state -on a buffer may be counter-productive. - -Even if your @file{.emacs} file does not invoke Viper automatically, -you can still load Viper and enter the Vi command state by typing the -following from within Emacs: - -@lisp -M-x viper-mode -@end lisp - -When Emacs first comes up, if you have not specified a file on the -command line, it will show the @file{*scratch*} buffer, in the -@samp{Lisp Interaction} mode. After you invoke Viper, you can start -editing files by using @kbd{:e}, @kbd{:vi}, or @kbd{v} commands. -(@xref{File and Buffer Handling}, for more information on @kbd{v} and other -new commands that, in many cases, are more convenient than @kbd{:e}, -@kbd{:vi}, and similar old-style Vi commands.) - -Finally, if at some point you would want to de-Viperize your running -copy of Emacs after Viper has been loaded, the command @kbd{M-x -viper-go-away} will do it for you. The function @code{toggle-viper-mode} -toggles Viperization of Emacs on and off. - -@node States in Viper -@section States in Viper - -@kindex @kbd{C-z} -@kindex @key{ESC} -@kindex @kbd{i} -@cindex Emacs state -@cindex Vi state -@cindex Insert state -@cindex Replace state -@cindex Ex commands -@findex @code{viper-go-away} -@findex @code{toggle-viper-mode} - -Viper has four states, Emacs, Vi, Insert, and Replace. - -@table @samp -@item Emacs state -This is the state plain vanilla Emacs is normally in. After you have loaded -Viper, @kbd{C-z} will normally take you to Vi command state. Another -@kbd{C-z} will take you back to Emacs state. This toggle key can be -changed, @pxref{Customization} You can also type @kbd{M-x viper-mode} to -change to Vi state. - - -For users who chose to set their user level to 1 at Viper setup time, -switching to Emacs state is deliberately made harder in order to not -confuse the novice user. In this case, @kbd{C-z} will either iconify Emacs -(if Emacs runs as an application under X) or it will stop Emacs (if -Emacs runs on a dumb terminal or in an Xterm window). - -@item Vi state -This is the Vi command mode. Any of the Vi commands, such as @kbd{i, o, a}, -@dots{}, will take you to Insert state. All Vi commands may -be used in this mode. Most Ex commands can also be used. -For a full list of Ex commands supported by Viper, type -@kbd{:} and then @key{TAB}. To get help on any issue, including the Ex -commands, type @kbd{:help}. This will invoke Viper Info -(if it is installed). Then typing @kbd{i} will prompt you for a topic to -search in the index. Note: to search for Ex commands in the index, you -should start them with a @kbd{:}, e.g., @kbd{:WW}. - -In Viper, Ex commands can be made to work on the current Emacs region. -This is done by typing a digit argument before @kbd{:}. -For instance, typing @kbd{1:} will prompt you with something like -@emph{:123,135}, assuming that the current region starts at line 123 and -ends at line 135. There is no need to type the line numbers, since Viper -inserts them automatically in front of the Ex command. - -@item Insert state -Insert state is the Vi insertion mode. @key{ESC} will take you back to -Vi state. Insert state editing can be done, including auto-indentation. By -default, Viper disables Emacs key bindings in Insert state. - -@item Replace state -Commands like @kbd{cw} invoke the Replace state. When you cross the -boundary of a replacement region (usually designated via a @samp{$} sign), -it will automatically change to Insert state. You do not have to worry -about it. The key bindings remain practically the same as in Insert -state. If you type @key{ESC}, Viper will switch to Vi command mode, terminating the -replacement state. -@end table - -@cindex mode line - -The modes are indicated on the @dfn{mode line} as , , , and , -so that the multiple modes do not confuse you. Most of your editing can be -done in Vi and Insert states. Viper will try to make all new buffers be in Vi -state, but sometimes they may come up in Emacs state. @kbd{C-z} -will take you to Vi state in such a case. In some major modes, like Dired, -Info, Gnus, etc., you should not switch to Vi state (and Viper will not -attempt to do so) because these modes are not intended for text editing and -many of the Vi keys have special meaning there. If you plan to read news, -browse directories, read mail, etc., from Emacs (which you should start -doing soon!), you should learn about the meaning of the various keys in -those special modes (typing @kbd{C-h m} in a buffer provides -help with key bindings for the major mode of that buffer). - -If you switch to Vi in Dired or similar modes, no harm is done. It is just -that the special key bindings provided by those modes will be temporarily -overshadowed by Viper's bindings. Switching back to Viper's Emacs state -will revive the environment provided by the current major mode. - -States in Viper are orthogonal to Emacs major modes, such as C mode or Dired -mode. You can turn Viper on and off for any Emacs state. When Viper is turned -on, Vi state can be used to move around. In Insert state, the bindings for -these modes can be accessed. For beginners (users at Viper levels 1 and 2), -these bindings are suppressed in Insert state, so that new users are not -confused by the Emacs states. Note that unless you allow Emacs bindings in -Insert state, you cannot do many interesting things, like language -sensitive editing. For the novice user (at Viper level 1), all major mode -bindings are turned off in Vi state as well. This includes the bindings for -key sequences that start with @kbd{C-c}, which practically means that all -major mode bindings are unsupported. @xref{Customization}, to find out how -to allow Emacs keys in Insert state. - -@menu -* Emacs State:: This is the state you should learn more about when - you get up to speed with Viper. -* Vi State:: Vi commands are executed in this state. -* Insert State:: You can enter text, and also can do sophisticated - editing if you know enough Emacs commands. -* Replace State:: Like Insert mode, but it is invoked via the - replacement commands, such as cw, C, R, etc. -@end menu - -@node Emacs State -@subsection Emacs State - -@kindex @kbd{C-z} -@cindex Emacs state - - -You will be in this mode only by accident (hopefully). This is the state -Emacs is normally in (imagine!!). Now leave it as soon as possible by -typing @kbd{C-z}. Then you will be in Vi state (sigh of relief) :-). - -Emacs state is actually a Viperism to denote all the major and minor modes -(@pxref{Emacs Preliminaries}) other than Viper that Emacs can be in. Emacs -can have several modes, such as C mode for editing C programs, LaTeX mode -for editing LaTeX documents, Dired for directory editing, etc. These are -major modes, each with a different set of key-bindings. Viper states are -orthogonal to these Emacs major modes. The presence of these language -sensitive and other modes is a major win over Vi. @xref{Improvements over -Vi}, for more. - -The bindings for these modes can be made available in the Viper Insert state -as well as in Emacs state. Unless you specify your user level as 1 (a -novice), all major mode key sequences that start with @kbd{C-x} and -@kbd{C-c} are also available in Vi state. This is important because major -modes designed for editing files, such as cc-mode or latex-mode, use key -sequences that begin with @kbd{C-x} and @kbd{C-c}. - -There is also a key that lets you temporarily escape to Vi command state -from the Insert state: typing @kbd{C-z} will let you execute a -single Vi command while staying in Viper's Insert state. - - -@node Vi State -@subsection Vi State - -@cindex Vi state - -This is the Vi command mode. When Viper is in Vi state, you will see the sign - in the mode line. Most keys will work as in Vi. The notable -exceptions are: - -@table @kbd -@item C-x -@kindex @kbd{C-x} -@kbd{C-x} is used to invoke Emacs commands, mainly those that do window -management. @kbd{C-x 2} will split a window, @kbd{C-x 0} will close a -window. @kbd{C-x 1} will close all other windows. @kbd{C-xb} is used to -switch buffers in a window, and @kbd{C-xo} to move through windows. -These are about the only necessary keystrokes. -For the rest, see the GNU Emacs Manual. - -@item C-c -@kindex @kbd{C-c} -For user levels 2 and higher, this key serves as a prefix key for the key -sequences used by various major modes. For users at Viper level 1, @kbd{C-c} -simply beeps. - -@item C-g and C-] -@kindex @kbd{C-g} -@kindex @kbd{C-]} - -These are the Emacs @samp{quit} keys. -There will be cases where you will have to -use @kbd{C-g} to quit. Similarly, @kbd{C-]} is used to exit -@samp{Recursive Edits} in Emacs for which there is no comparable Vi -functionality and no key-binding. Recursive edits are indicated by -@samp{[]} brackets framing the modes on the mode line. -@xref{Recursive Edit,Recursive -Edit,Recursive Edit,emacs,The GNU Emacs Manual}. -At user level 1, @kbd{C-g} is bound to @code{viper-info-on-file} -function instead. -@item C-\ -@kindex @kbd{C-\} -@cindex Meta key - -Viper uses @key{ESC} as a switch between Insert and Vi states. Emacs uses -@key{ESC} for Meta. The Meta key is very important in Emacs since many -functions are accessible only via that key as @kbd{M-x function-name}. -Therefore, we need to simulate it somehow. In Viper's Vi, Insert, and -Replace states, the meta key is set to be @kbd{C-\}. Thus, to get -@kbd{M-x}, you should type @kbd{C-\ x} (if the keyboard has no Meta key, -which is rare these days). -This works both in the Vi command state and in the Insert and Replace -states. In Vi command state, you can also use @kbd{\ @key{ESC}} as the -meta key. - -Note: Emacs binds @kbd{C-\} to a function that offers to change the -keyboard input method in the multilingual environment. Viper overrides this -binding. However, it is still possible to switch the input method by typing -@kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state. -Or you can use the MULE menu in the menubar. -@end table -@noindent -Other differences are mostly improvements. The ones you should know -about are: - -@table @samp -@item Undo -@kindex @kbd{u} -@kbd{u} will undo. Undo can be repeated by the @kbd{.} key. Undo itself -can be undone. Another @kbd{u} will change the direction. The presence -of repeatable undo means that @kbd{U}, undoing lines, is not very -important. Therefore, @kbd{U} also calls @code{viper-undo}. -@cindex multiple undo -@cindex undo - - -@item Counts -Most commands, @kbd{~}, @kbd{[[}, @kbd{p}, @kbd{/}, @dots{}, etc., take counts. - -@comment ]] Just to balance parens -@item Regexps -Viper uses Emacs Regular Expressions for searches. These are a superset of -Vi regular -expressions, excepting the change-of-case escapes @samp{\u}, @samp{\L}, -@dots{}, etc. @xref{Regexps,,Syntax of Regular Expressions,emacs,The -GNU Emacs Manual}, for details. -Files specified to @kbd{:e} use @code{csh} regular expressions -(globbing, wildcards, what have you). -However, the function @code{viper-toggle-search-style}, bound to @kbd{C-c /}, -lets the user switch from search with regular expressions to plain vanilla -search and vice versa. It also lets one switch from case-sensitive search -to case-insensitive and back. -@xref{Viper Specials}, for more details. -@cindex regular expressions -@cindex vanilla search -@cindex case-sensitive search -@cindex case-insensitive search -@kindex @kbd{C-c /} - -@item Ex commands -@cindex Ex commands -The current working directory of a buffer is automatically inserted in the -minibuffer if you type @kbd{:e} then space. Absolute filenames are -required less often in Viper. For file names, Emacs uses a convention that -is slightly different from other programs. It is designed to minimize the -need for deleting file names that Emacs provides in its prompts. (This is -usually convenient, but occasionally the prompt may suggest a wrong file -name for you.) If you see a prompt @kbd{/usr/foo/} and you wish to edit the -file @kbd{~/.file}, you don't have to erase the prompt. Instead, simply -continue typing what you need. Emacs will interpret @kbd{/usr/foo/~/.file} -correctly. Similarly, if the prompt is @kbd{~/foo/} and you need to get to -@kbd{/bar/file}, keep typing. Emacs interprets @kbd{~/foo//bar/} as -@kbd{/bar/file}, since when it sees @samp{//}, it understands that -@kbd{~/foo/} is to be discarded. - -The command @kbd{:cd} will change the default directory for the -current buffer. The command @kbd{:e} will interpret the -filename argument in @code{csh}. @xref{Customization}, if you -want to change the default shell. -The command @kbd{:next} takes counts from -@kbd{:args}, so that @kbd{:rew} is obsolete. Also, @kbd{:args} will show only -the invisible files (i.e., those that are not currently seen in Emacs -windows). - -When applicable, Ex commands support file completion and history. This -means that by typing a partial file name and then @key{TAB}, Emacs will try -to complete the name or it will offer a menu of possible completions. -This works similarly to Tcsh and extends the behavior of Csh. While Emacs -is waiting for a file name, you can type @kbd{M-p} to get the previous file -name you typed. Repeatedly typing @kbd{M-p} and @kbd{M-n} will let you -browse through the file history. - -Like file names, partially typed Ex commands can be completed by typing -@key{TAB}, and Viper keeps the history of Ex commands. After typing -@kbd{:}, you can browse through the previously entered Ex commands by -typing @kbd{M-p} and @kbd{M-n}. Viper tries to rationalize when it puts Ex -commands on the history list. For instance, if you typed @kbd{:w!@: foo}, -only @kbd{:w!} will be placed on the history list. This is because the -last history element is the default that can be invoked simply by typing -@kbd{: @key{RET}}. If @kbd{:w!@: foo} were placed on the list, it would be all to -easy to override valuable data in another file. Reconstructing the full -command, @kbd{:w!@: foo}, from the history is still not that hard, since Viper -has a separate history for file names. By typing @kbd{: M-p}, you will get -@kbd{:w!} in the minibuffer. Then, repeated @kbd{M-p} will get you through -the file history, inserting one file name after another. - -In contrast to @kbd{:w!@: foo}, if the command were @kbd{:r foo}, the entire -command will appear in the history list. This is because having @kbd{:r} -alone as a default is meaningless, since this command requires a file -argument. -@end table -@noindent -As in Vi, Viper's destructive commands can be re-executed by typing `@kbd{.}'. -However, in addition, Viper keeps track of the history of such commands. This -history can be perused by typing @kbd{C-c M-p} and @kbd{C-c M-n}. -Having found the appropriate command, it can be then executed by typing -`@kbd{.}'. -@xref{Improvements over Vi}, for more information. - -@node Insert State -@subsection Insert State - -@cindex Insert state - -To avoid confusing the beginner (at Viper level 1 and 2), Viper makes only the -standard Vi keys available in Insert state. The implication is that -Emacs major modes cannot be used in Insert state. -It is strongly recommended that as soon as you are comfortable, make the -Emacs state bindings visible (by changing your user level to 3 or higher). -@xref{Customization}, -to see how to do this. - -Once this is done, it is possible to do quite a bit of editing in -Insert state. For instance, Emacs has a @dfn{yank} command, @kbd{C-y}, -which is similar to Vi's @kbd{p}. However, unlike @kbd{p}, @kbd{C-y} can be -used in Insert state of Viper. Emacs also has a kill ring where it keeps -pieces of text you deleted while editing buffers. The command @kbd{M-y} is -used to delete the text previously put back by Emacs's @kbd{C-y} or by Vi's -@kbd{p} command and reinsert text that was placed on the kill-ring earlier. - -This works both in Vi and Insert states. -In Vi state, @kbd{M-y} is a much better alternative to the usual Vi's way -of recovering the 10 previously deleted chunks of text. In Insert state, -you can -use this as follows. Suppose you deleted a piece of text and now you need -to re-insert it while editing in Insert mode. The key @kbd{C-y} will put -back the most recently deleted chunk. If this is not what you want, type -@kbd{M-y} repeatedly and, hopefully, you will find the chunk you want. - -Finally, in Insert and Replace states, Viper provides the history of -pieces of text inserted in previous insert or replace commands. These -strings of text can be recovered by repeatedly typing @kbd{C-c M-p} or -@kbd{C-c M-n} while in Insert or Replace state. (This feature is disabled -in the minibuffer: the above keys are usually bound to other histories, -which are more appropriate in the minibuffer.) - - -@cindex Meta key - -You can call Meta functions from Insert state. As in Vi state, the Meta key -is @kbd{C-\}. Thus @kbd{M-x} is typed as @kbd{C-\ x}. - -Other Emacs commands that are useful in Insert state are @kbd{C-e} -and @kbd{C-a}, which move the cursor to the end and the beginning of the -current line, respectively. You can also use @kbd{M-f} and @kbd{M-b}, -which move the cursor forward (or backward) one word. -If your display has a Meta key, these functions are invoked by holding the -Meta key and then typing @kbd{f} and @kbd{b}, respectively. On displays -without the Meta key, these functions are invoked by typing -@kbd{C-\ f} and @kbd{C-\ b} (@kbd{C-\} simulates the Meta key in Insert -state, as explained above). - -The key @kbd{C-z} is sometimes also useful in Insert state: it allows you -to execute a single command in Vi state without leaving the Insert state! -For instance, @kbd{C-z d2w} will delete the next two words without leaving -the Insert state. - -When Viper is in Insert state, you will see in the mode line. - -@node Replace State -@subsection Replace State - -@cindex Replace state - -This state is entered through Vi replacement commands, such as @kbd{C}, -@kbd{cw}, etc., or by typing @kbd{R}. In Replace state, Viper puts in -the mode line to let you know which state is in effect. If Replace state is -entered through @kbd{R}, Viper stays in that state until the user hits -@key{ESC}. If this state is entered via the other replacement commands, -then Replace state is in effect until you hit @key{ESC} or until you cross -the rightmost boundary of the replacement region. In the latter case, Viper -changes its state from Replace to Insert (which you will notice by the -change in the mode line). - -Since Viper runs under Emacs, it is possible to switch between buffers -while in Replace state. You can also move the cursor using the arrow keys -(even on dumb terminals!)@: and the mouse. Because of this freedom (which is -unattainable in regular Vi), it is possible to take the cursor outside the -replacement region. (This may be necessary for several reasons, including -the need to enable text selection and region-setting with the mouse.) - -The issue then arises as to what to do when the user -hits the @key{ESC} key. In Vi, this would cause the text between cursor and -the end of the replacement region to be deleted. But what if, as is -possible in Viper, the cursor is not inside the replacement region? - -To solve the problem, Viper keeps track of the last cursor position while it -was still inside the replacement region. So, in the above situation, Viper -would delete text between this position and the end of the replacement -region. - -@node The Minibuffer -@section The Minibuffer - -@cindex Minibuffer - -The minibuffer is where commands are entered in. Editing can be done -by commands from Insert state, namely: - -@table @kbd -@item C-h -Backspace -@item C-w -Delete Word -@item C-u -Erase line -@item C-v -Quote the following character -@item @key{RET} -Execute command -@item C-g and C-] -Emacs quit and abort keys. These may be necessary. @xref{Vi State}, for an -explanation. -@item M-p and M-n -These keys are bound to functions that peruse minibuffer history. The -precise history to be perused depends on the context. It may be the history -of search strings, Ex commands, file names, etc. -@item C-s -If the minibuffer is entered via the Viper search commands @kbd{/} or -@kbd{?}, then this key inserts the last search string used by the -Emacs incremental search command -(which is bound to @kbd{C-s} everywhere except in this case). -@end table - -Most of the Emacs keys are functional in the minibuffer. While in the -minibuffer, Viper tries to make editing resemble Vi's behavior when the -latter is waiting for the user to type an Ex command. In particular, you -can use the regular Vi commands to edit the minibuffer. You can switch -between the Vi state and Insert state at will, and even use the replace mode. -Initially, the minibuffer comes up in Insert state. - -Some users prefer plain Emacs bindings in the minibuffer. To this end, set -@code{viper-vi-style-in-minibuffer} to @code{nil} in -your Viper customization file. @xref{Customization}, to learn how to do this. - -When the minibuffer changes Viper states, you will notice that the appearance -of the text there changes as well. This is useful because the minibuffer -has no mode line to tell which Vi state it is in. -The appearance of the text in the minibuffer can be changed. -@xref{Viper Specials}, for more details. - -@node Multiple Files in Viper -@section Multiple Files in Viper - -@cindex multiple files -@cindex managing multiple files - -Viper can edit multiple files. This means, for example that you never need -to suffer through @code{No write since last change} errors. -Some Viper elements are common over all the files. - -@table @samp -@item Textmarkers -@cindex markers -@cindex textmarkers -Textmarkers remember @emph{files and positions}. -If you set marker @samp{a} in -file @file{foo}, start editing file @file{bar} and type @kbd{'a}, then -@emph{YOU WILL SWITCH TO FILE @file{foo}}. You can see the contents of a -textmarker using the Viper command @kbd{[} where are the -textmarkers, e.g., @kbd{[a} to view marker @samp{a} . -@item Repeated Commands -Command repetitions are common over files. Typing @kbd{!!} will repeat the -last @kbd{!} command whichever file it was issued from. -Typing @kbd{.} will repeat the last command from any file, and -searches will repeat the last search. Ex commands can be repeated by typing -@kbd{: @key{RET}}. -Note: in some rare cases, that @kbd{: @key{RET}} may do something dangerous. -However, usually its effect can be undone by typing @kbd{u}. -@item Registers -@cindex registers -Registers are common to files. Also, text yanked with @kbd{y} can be -put back (@kbd{p}) into any file. The Viper command @kbd{]}, where are -the registers, can be used to look at the contents of a register, e.g., -type @kbd{]a} to view register @samp{a}. - -There is one difference in text deletion that you should be -aware of. This difference comes from Emacs and was adopted in Viper -because we find it very useful. In Vi, if you delete a line, say, and then -another line, these two deletions are separated and are put back -separately if you use the @samp{p} command. In Emacs (and Viper), successive -series of deletions that are @emph{not interrupted} by other commands are -lumped together, so the deleted text gets accumulated and can be put back -as one chunk. If you want to break a sequence of deletions so that the -newly deleted text could be put back separately from the previously deleted -text, you should perform a non-deleting action, e.g., move the cursor one -character in any direction. -@item Absolute Filenames -@cindex absolute file names -The current directory name for a file is automatically prepended to the -file name in any -@kbd{:e}, @kbd{:r}, @kbd{:w}, etc., command (in Emacs, each buffer has a -current directory). -This directory is inserted in the minibuffer once you type space after -@kbd{:e, r}, etc. Viper also supports completion of file names and Ex -commands (@key{TAB}), and it keeps track of -command and file history (@kbd{M-p}, @kbd{M-n}). -Absolute filenames are required less -often in Viper. - -You should be aware that Emacs interprets @kbd{/foo/bar//bla} as -@kbd{/bla} and @kbd{/foo/~/bar} as @kbd{~/bar}. This is designed to -minimize the need for erasing file names that Emacs suggests in its -prompts, if a suggested file name is not what you wanted. - -The command @kbd{:cd} will change the default directory for the -current Emacs buffer. The Ex command @kbd{:e} will interpret the -filename argument in @samp{csh}, by default. @xref{Customization}, if you -want to change this. -@end table - -@noindent -Currently undisplayed files can be listed using the @kbd{:ar} command. The -command @kbd{:n} can be given counts from the @kbd{:ar} list to switch to -other files. For example, use `:n3' to move to the third file in that list. - -@node Unimplemented Features -@section Unimplemented Features - -Unimplemented features include: - -@itemize @bullet -@item -@kbd{:ab} and @kbd{:una} are not implemented, since -@kbd{:ab} is considered obsolete, since Emacs has much -more powerful facilities for defining abbreviations. -@item -@kbd{:set option?} is not implemented. The current -@kbd{:set} can also be used to set Emacs variables. -@item -@kbd{:se list} requires modification of the display code for Emacs, so -it is not implemented. -A useful alternative is @code{cat -t -e file}. Unfortunately, it cannot -be used directly inside Emacs, since Emacs will obdurately change @samp{^I} -back to normal tabs. -@end itemize - -@node Improvements over Vi -@chapter Improvements over Vi - -Some common problems with Vi and Ex have been solved in Viper. This -includes better implementation of existing commands, new commands, and -the facilities provided by Emacs. - -@menu -* Basics:: Basic Viper differences, Multi-file effects. -* Undo and Backups:: Multiple undo, auto-save, backups and changes -* History:: History for Ex and Vi commands. -* Macros and Registers:: Keyboard Macros (extended ".")@: @@reg execution. -* Completion:: Filename and Command Completion for Ex. -* Improved Search:: Incremental Search and Buffer Content Search. -* Abbreviation Facilities:: Normal Abbrevs, Templates, and Dynamic Abbrevs. -* Movement and Markers:: Screen Editor movements, viewing textmarkers. -* New Commands:: Commands that do not exist in Vi. -* Useful Packages:: A Sampling of some Emacs packages, and things - you should know about. -@end menu - -@node Basics -@section Basics - -The Vi command set is based on the idea of combining motion commands -with other commands. The motion command is used as a text region -specifier for other commands. -We classify motion commands into @dfn{point commands} and -@dfn{line commands}. - -@cindex point commands - -The point commands are: - -@quotation -@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, -@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, -@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} -@end quotation - -@cindex line commands - -The line commands are: - -@quotation -@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, -@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} -@end quotation - -@cindex region -@cindex region specification -@cindex expanding (region) -@cindex describing regions -@cindex movement commands - -@noindent -If a point command is given as an argument to a modifying command, the -region determined by the point command will be affected by the modifying -command. On the other hand, if a line command is given as an argument to a -modifying command, the region determined by the line command will be -enlarged so that it will become the smallest region properly containing the -region and consisting of whole lines (we call this process @dfn{expanding -the region}), and then the enlarged region will be affected by the modifying -command. -Text Deletion Commands (@pxref{Deleting Text}), Change commands -(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) -use these commands to describe a region of text to operate on. -Thus, type @kbd{dw} to delete a word, @kbd{>@}} to shift a paragraph, or -@kbd{!'afmt} to format a region from @samp{point} to textmarker -@samp{a}. - -@cindex r and R region specifiers - -Viper adds the region specifiers @samp{r} and @samp{R}. Emacs has a -special marker called @dfn{mark}. The text-area between the current cursor -position @dfn{point} and the @dfn{mark} is called the @dfn{region}. -@samp{r} specifies the raw region and @samp{R} is the expanded region -(i.e., the minimal contiguous chunk of full lines that contains the raw -region). -@kbd{dr} will now delete the region, @kbd{>r} will shift it, etc. -@kbd{r,R} are not motion commands, however. The special mark is set by -@kbd{m.} and other commands. @xref{Marking}, for more info. - -Viper also adds counts to most commands for which it would make sense. - -In the Overview chapter, some Multiple File issues were discussed -(@pxref{Multiple Files in Viper}). In addition to the files, Emacs has -buffers. These can be seen in the @kbd{:args} list and switched using -@kbd{:next} if you type @kbd{:set ex-cycle-through-non-files t}, or -specify @code{(setq ex-cycle-through-non-files t)} in your -Viper customization file. @xref{Customization}, for details. - -@node Undo and Backups -@section Undo and Backups - -@cindex undo - -Viper provides multiple undo. The number of undo's and the size is limited -by the machine. The Viper command @kbd{u} does an undo. Undo can be -repeated by typing @kbd{.} (a period). Another @kbd{u} will undo the undo, -and further -@kbd{.} will repeat it. Typing @kbd{u} does the first undo, and changes the -direction. - -@cindex backup files -@cindex auto save - -Since the undo size is limited, Viper can create backup files and -auto-save files. It will normally do this automatically. It is possible -to have numbered backups, etc. For details, @pxref{Backup,,Backup and -Auto-Save,emacs,The GNU Emacs Manual}. - -@comment [ balance parens -@cindex viewing registers and markers -@cindex registers -@cindex markers -@cindex textmarkers - -The results of the 9 previous changes are available in the 9 numeric -registers, as in Vi. The extra goody is the ability to @emph{view} these -registers, in addition to being able to access them through @kbd{p} and -@kbd{M-y} (@xref{Insert State}, for details.) -The Viper command @kbd{] register} will display the contents of any -register, numeric or alphabetical. The related command @kbd{[ textmarker} -will show the text around the textmarker. @samp{register} and @samp{textmarker} -can be any letters from a through z. -@comment ] balance parens - -@node History -@section History - -@cindex history -@cindex Minibuffer - -History is provided for Ex commands, Vi searches, file names, pieces of -text inserted in earlier commands that use Insert or Replace state, and for -destructive commands in Vi state. These are -useful for fixing those small typos that screw up searches and @kbd{:s}, -and for eliminating routine associated with repeated typing of file names -or pieces of text that need to be inserted frequently. -At the @kbd{:} or @kbd{/} prompts in the minibuffer, you can do the following: - -@table @kbd -@item M-p and M-n -To move to previous and next history items. This causes the history -items to appear on the command line, where you can edit them, or -simply type Return to execute. -@item M-r and M-s -To search backward and forward through the history. -@item @key{RET} -Type @key{RET} to accept a default (which is displayed in the prompt). -@end table - -The history of insertions can be perused by -typing @kbd{C-c M-p} and @kbd{C-c M-n} while in Insert or Replace state. -The history of destructive Vi commands can be perused via the same keys -when Viper is in Vi state. @xref{Viper Specials}, for details. - -All Ex commands have a file history. For instance, typing @kbd{:e}, space -and then @kbd{M-p} will bring up the name of the previously typed file -name. Repeatedly typing @kbd{M-p}, @kbd{M-n}, etc., will let you browse -through the file history. - -Similarly, commands that have to do with switching buffers -have a buffer history, and commands that expect strings or regular -expressions keep a history on those items. - -@node Macros and Registers -@section Macros and Registers - -@cindex keyboard macros -@cindex macros -@cindex registers -@cindex register execution - -Viper facilitates the use of Emacs-style keyboard macros. @kbd{@@#} will -start a macro definition. As you type, the commands will be executed, and -remembered (This is called ``learn mode'' in some editors.) -@kbd{@@register} will complete the macro, putting it into @samp{register}, -where @samp{register} is any character from @samp{a} through @samp{z}. Then -you can execute this macro using @kbd{@@register}. It is, of course, -possible to yank some text into a register and execute it using -@kbd{@@register}. Typing @kbd{@@@@}, @kbd{@@RET}, or @kbd{@@C-j} will -execute the last macro that was executed using @kbd{@@register}. - -Viper will automatically lowercase the register, so that pressing the -@kbd{SHIFT} key for @kbd{@@} will not create problems. This is for -@kbd{@@} macros and @kbd{"p} @emph{only}. In the case of @kbd{y}, -@kbd{"Ayy} will append to @emph{register a}. For @kbd{[,],',`}, it -is an error to use a Uppercase register name. - -@comment [ balance parens -@cindex viewing registers and markers - -The contents of a register can be seen by @kbd{]register}. (@kbd{[textmarker} -will show the contents of a textmarker). -@comment ] balance parens - -@cindex last keyboard macro - -The last keyboard macro can also be executed using -@kbd{*}, and it can be yanked into a register using @kbd{@@!register}. -This is useful for Emacs style keyboard macros defined using @kbd{C-x(} -and @kbd{C-x)}. Emacs keyboard macros have more capabilities. -@xref{Keyboard Macros,,Keyboard Macros,emacs, The GNU Emacs Manual}, for -details. - -Keyboard Macros allow an interesting form of Query-Replace: -@kbd{/pattern} or @kbd{n} to go to the next pattern (the query), followed by a -Keyboard Macro execution @kbd{@@@@} (the replace). - -Viper also provides Vi-style macros. @xref{Vi Macros}, for details. - - -@node Completion -@section Completion - -@cindex completion - -Completion is done when you type @key{TAB}. The Emacs completer does not -grok wildcards in file names. Once you type a wildcard, the completer will -no longer work for that file name. Remember that Emacs interprets a file name -of the form @kbd{/foo//bar} as @kbd{/bar} and @kbd{/foo/~/bar} as -@kbd{~/bar}. - -@node Improved Search -@section Improved Search - -@cindex buffer search -@cindex word search - -Viper provides buffer search, the ability to search the buffer for a region -under the cursor. You have to turn this on in your Viper customization file -either by calling - -@example -(viper-buffer-search-enable) -@end example - -@noindent -or by setting @code{viper-buffer-search-char} to, say, @kbd{f3}: -@example -(setq viper-buffer-search-char ?g) -@end example - -@noindent -If the user calls @code{viper-buffer-search-enable} explicitly (the first -method), then @code{viper-buffer-search-char} will be set to @kbd{g}. -Regardless of how this feature is enabled, the key -@code{viper-buffer-search-char} will take movement commands, like -@kbd{w,/,e}, to find a region and then search for the contents of that -region. This command is very useful for searching for variable names, etc., -in a program. The search can be repeated by @kbd{n} or reversed by @kbd{N}. - -@cindex incremental search - -Emacs provides incremental search. As you type the string in, the -cursor will move to the next match. You can snarf words from the buffer -as you go along. Incremental Search is normally bound to @kbd{C-s} and -@kbd{C-r}. @xref{Customization}, to find out how to change the bindings -of @kbd{C-r or C-s}. -For details, @pxref{Incremental Search,,Incremental -Search,emacs,The GNU Emacs Manual}. - -@cindex query replace - -Viper also provides a query replace function that prompts through the -minibuffer. It is invoked by the @kbd{Q} key in Vi state. - -@cindex mouse search - -On a window display, Viper supports mouse search, i.e., you can search for a -word by clicking on it. @xref{Viper Specials}, for details. - -Finally, on a window display, Viper highlights search patterns as it finds -them. This is done through what is known as @emph{faces} in Emacs. The -variable that controls how search patterns are highlighted is -@code{viper-search-face}. If you don't want any highlighting at all, put -@example -(copy-face 'default 'viper-search-face) -@end example -@vindex @code{viper-search-face} -@noindent -in your Viper customization file. If you want to change how patterns are -highlighted, you will have to change @code{viper-search-face} to your liking. -The easiest way to do this is to use Emacs customization widget, which is -accessible from the menubar. Viper customization group is located under the -@emph{Emulations} customization group, which in turn is under the -@emph{Editing} group (or simply by typing @kbd{:customize}). All Viper -faces are grouped together under Viper's -@emph{Highlighting} group. - -Try it: it is really simple! - -@node Abbreviation Facilities -@section Abbreviation Facilities - -@cindex abbrevs - -It is possible in Emacs to define abbrevs based on the contents of the -buffer. -Sophisticated templates can be defined using the Emacs abbreviation -facilities. @xref{Abbrevs,,Abbreviations,emacs,The GNU Emacs Manual}, for -details. - -@cindex dynamic abbrevs - -Emacs also provides Dynamic Abbreviations. Given a partial word, Emacs -will search the buffer to find an extension for this word. For instance, -one can type @samp{Abbreviations} by typing @samp{A}, followed by a keystroke -that completed the @samp{A} to @samp{Abbreviations}. Repeated typing -will search further back in the buffer, so that one could get -@samp{Abbrevs} by repeating the -keystroke, which appears earlier in the text. Emacs binds this to -@kbd{@key{ESC} /}, so you will have to find a key and bind the function -@code{dabbrev-expand} to that key. -Facilities like this make Vi's @kbd{:ab} command obsolete. - -@node Movement and Markers -@section Movement and Markers - -@cindex Ex style motion -@cindex line editor motion - -Viper can be set free from the line--limited movements in Vi, such as @kbd{l} -refusing to move beyond the line, @key{ESC} moving one character back, -etc. These derive from Ex, which is a line editor. If your -Viper customization file contains - -@example -@code{(setq viper-ex-style-motion nil)} -@end example - -@noindent -the motion will be a true screen editor motion. One thing you must then -watch out for is that it is possible to be on the end-of-line character. -The keys @kbd{x} and @kbd{%} will still work correctly, i.e., as if they -were on the last character. - -@vindex @code{viper-syntax-preference} -@cindex syntax table - -The word-movement commands @kbd{w}, @kbd{e}, etc., and the associated -deletion/yanking commands, @kbd{dw}, @kbd{yw}, etc., can be made to -understand Emacs syntax tables. If the variable -@code{viper-syntax-preference} is set to @code{strict-vi} then -the meaning of @emph{word} is the same as in -Vi. However, if the value is @code{reformed-vi} (the default) then the -alphanumeric symbols will be those specified by the current Emacs syntax -table (which may be different for different major modes) plus the -underscore symbol @kbd{_}, minus some non-word symbols, like '.;,|, etc. -Both @code{strict-vi} and @code{reformed-vi} work close to Vi in -traditional cases, but @code{reformed-vi} does a better job when editing -text in non-Latin alphabets. - -The user can also specify the value @code{emacs}, which would -make Viper use exactly the Emacs notion of word. In particular, the -underscore may not be part of a word. Finally, if -@code{viper-syntax-preference} is set to @code{extended}, Viper words would -consist of characters that are classified as alphanumeric @emph{or} as -parts of symbols. This is convenient for writing programs and in many other -situations. - -@code{viper-syntax-preference} is a local variable, so it can have different -values for different major modes. For instance, in programming modes it can -have the value @code{extended}. In text modes where words contain special -characters, such as European (non-English) letters, Cyrillic letters, etc., -the value can be @code{reformed-vi} or @code{emacs}. - -Changes to @code{viper-syntax-preference} should be done in the hooks to -various major modes by executing @code{viper-set-syntax-preference} as in -the following example: - -@example -(viper-set-syntax-preference nil "emacs") -@end example - -@findex @code{viper-set-syntax-preference} - -The above discussion of the meaning of Viper's words concerns only Viper's -movement commands. In regular expressions, words remain the same as in -Emacs. That is, the expressions @code{\w}, @code{\>}, @code{\<}, etc., use -Emacs's idea of what is a word, and they don't look into the value of -variable @code{viper-syntax-preference}. This is because Viper doesn't change -syntax tables in fear of upsetting the various major modes that set these -tables. - -@cindex textmarkers - -Textmarkers in Viper remember the file and the position, so that you can -switch files by simply doing @kbd{'a}. If you set up a regimen for using -Textmarkers, this is very useful. Contents of textmarkers can be viewed -by @kbd{[marker}. (Contents of registers can be viewed by @kbd{]register}). - -@node New Commands -@section New Commands - -These commands have no Vi analogs. - -@table @kbd -@item C-x, C-c -@kindex @kbd{C-x} -@kindex @kbd{C-c} -These two keys invoke many important Emacs functions. For example, if you -hit @kbd{C-x} followed by @kbd{2}, then the current window will be split -into 2. Except for novice users, @kbd{C-c} is also set to execute an Emacs -command from the current major mode. @key{ESC} will do the same, if you -configure @key{ESC} as Meta by setting @code{viper-no-multiple-ESC} to -@code{nil} in your Viper customization file. @xref{Customization}. -@kbd{C-\} in Insert, Replace, or Vi states will make Emacs think -@kbd{Meta} has been hit. -@item \ -@kindex @kbd{\} -Escape to Emacs to execute a single Emacs command. For instance, -@kbd{\ @key{ESC}} will act like a Meta key. -@item Q -@kindex @kbd{Q} -@cindex query replace -@kbd{Q} is for query replace. By default, -each string to be replaced is treated as a regular expression. You can use -@code{(setq viper-re-query-replace nil)} in your @file{.emacs} file to -turn this off. (For normal searches, @kbd{:se nomagic} will work. Note -that @kbd{:se nomagic} turns Regexps off completely, unlike Vi). -@item v -@itemx V -@itemx C-v -@kindex @kbd{v} -@kindex @kbd{V} -@kindex @kbd{C-v} -These keys are used to visit files. @kbd{v} will switch to a buffer -visiting file whose name can be entered in the minibuffer. @kbd{V} is -similar, but will use a window different from the current window. -@kbd{C-v} is like @kbd{V}, except that a new frame (X window) will be used -instead of a new Emacs window. -@item # -@kindex @kbd{#} -If followed by a certain character @var{ch}, it becomes an operator whose -argument is the region determined by the motion command that follows -(indicated as ). -Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q}, and -@kbd{s}. For instance, @kbd{#qr} will prompt you for a string and then -prepend this string to each line in the buffer. -@item # c -@kindex @kbd{#c} -@cindex changing case -Change upper-case characters in the region to lower-case -(@code{downcase-region}). -Emacs command @kbd{M-l} does the same for words. -@item # C -@kindex @kbd{#C} -Change lower-case characters in the region to upper-case. For instance, -@kbd{# C 3 w} will capitalize 3 words from the current point -(@code{upcase-region}). -Emacs command @kbd{M-u} does the same for words. -@item # g -@kindex @kbd{#g} -Execute last keyboard macro for each line in the region -(@code{viper-global-execute}). -@item # q -@kindex @kbd{#q} -Insert specified string at the beginning of each line in the region -(@code{viper-quote-region}). The default string is composed of the comment -character(s) appropriate for the current major mode. -@item # s -@kindex @kbd{#s} -Check spelling of words in the region (@code{spell-region}). -The function used for spelling is determined from the variable -@code{viper-spell-function}. -@vindex @code{viper-spell-function} -@item * -@kindex @kbd{*} -Call last keyboard macro. -@item m . -Set mark at point and push old mark off the ring -@item m< -@item m> -Set mark at beginning and end of buffer, respectively. -@item m, -Jump to mark and pop mark off the ring. @xref{Mark,,Mark,emacs,The GNU -Emacs Manual}, for more info. -@item ] register -@kindex @kbd{]} -View contents of register -@item [ textmarker -@kindex @kbd{[} -View filename and position of textmarker -@item @@# -@item @@register -@item @@! -@kindex @kbd{@@#} -@kindex @kbd{@@} -@kindex @kbd{@@!} -@cindex keyboard macros -@cindex register execution - -Begin/end keyboard macro. @@register has a different meaning when used after -a @kbd{@@#}. @xref{Macros and Registers}, for details -@item [] -@kindex @kbd{[]} -Go to end of heading. -@item g <@emph{movement command}> -Search buffer for text delimited by movement command. The canonical -example is @kbd{gw} to search for the word under the cursor. -@xref{Improved Search}, for details. -@item C-g and C-] -@kindex @kbd{C-g} -@kindex @kbd{C-]} -Quit and Abort Recursive edit. These may be necessary on occasion. -@xref{Vi State}, for a reason. -@item C-c C-g -@kindex @kbd{C-c C-g} -Hitting @kbd{C-c} followed by @kbd{C-g} will display the information on the -current buffer. This is the same as hitting @kbd{C-g} in Vi, but, as -explained above, @kbd{C-g} is needed for other purposes in Emacs. -@item C-c / -@kindex @kbd{C-c /} -Without a prefix argument, this command toggles -case-sensitive/case-insensitive search modes and plain vanilla/regular -expression search. With the prefix argument 1, i.e., -@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, -toggles plain vanilla search and search using -regular expressions. @xref{Viper Specials}, for alternative ways to invoke -this function. -@cindex vanilla search -@cindex case-sensitive search -@cindex case-insensitive search - -@item M-p and M-n -@kindex @kbd{M-p} -@kindex @kbd{M-n} -In the minibuffer, these commands navigate through the minibuffer -histories, such as the history of search strings, Ex commands, etc. - -@item C-s -@kindex @kbd{C-s} -If the minibuffer is entered via a Viper search commands @kbd{/} or @kbd{?}, -then typing this key inserts the last search string used by the -Emacs incremental search command (that is bound to @kbd{C-s} everywhere -except in this case). - -@item C-c M-p and C-c M-n -@kindex @kbd{C-c M-p} -@kindex @kbd{C-c M-n} -@cindex Insertion history -@cindex Insertion ring -@cindex Command history -@cindex Command ring - -In Insert or Replace state, these commands let the user -peruse the history of insertion strings used in previous insert or replace -commands. Try to hit @kbd{C-c M-p} or @kbd{C-c M-n} repeatedly and see what -happens. @xref{Viper Specials}, for more. - -In Vi state, these commands let the user peruse the history of Vi-style -destructive commands, such as @kbd{dw}, @kbd{J}, @kbd{a}, etc. -By repeatedly typing @kbd{C-c M-p} or @kbd{C-c M-n} you will cycle Viper -through the recent history of Vi commands, displaying the commands one by -one. Once -an appropriate command is found, it can be executed by typing `@kbd{.}'. - -Since typing @kbd{C-c M-p} is tedious, it is more convenient to bind an -appropriate function to a function key on the keyboard and use that key. -@xref{Viper Specials}, for details. - -@item Ex commands -@findex @kbd{Ex args} -@findex @kbd{Ex n} -@findex @kbd{Ex pwd} -@findex @kbd{Ex pre} -The commands @kbd{:args}, @kbd{:next}, @kbd{:pre} behave -differently. @kbd{:pwd} exists to get current directory. -The commands @kbd{:b} and @kbd{:B} switch buffers around. @xref{File and -Buffer Handling}, for details. -There are also the new commands @kbd{:RelatedFile} and -@kbd{PreviousRelatedFile} (which abbreviate to @kbd{R} and @kbd{P}, -respectively. @xref{Viper Specials}, for details. -@findex @kbd{Ex RelatedFile} -@findex @kbd{Ex PreviousRelatedFile} -@end table - -Apart from the new commands, many old commands have been enhanced. Most -notably, Vi style macros are much more powerful in Viper than in Vi. @xref{Vi -Macros}, for details. - -@node Useful Packages -@section Useful Packages - -Some Emacs packages are mentioned here as an aid to the new Viper user, to -indicate what Viper is capable of. -A vast number comes with the standard Emacs distribution, and many more exist -on the net and on the archives. - -This manual also mentions some Emacs features a new user -should know about. The details of these are found in the GNU Emacs -Manual. - -The features first. For details, look up the Emacs Manual. - -@table @samp -@item Make -@cindex make -@cindex compiling - -Makes and Compiles can be done from the editor. Error messages will be -parsed and you can move to the error lines. -@item Shell -@cindex shell -@cindex interactive shell -You can talk to Shells from inside the editor. Your entire shell session -can be treated as a file. -@item Mail -@cindex email -@cindex mail -Mail can be read from and sent within the editor. Several sophisticated -packages exist. -@item Language Sensitive Editing -Editing modes are written for most computer languages in existence. By -controlling indentation, they catch punctuation errors. -@end table - -The packages, below, represents a drop in the sea of special-purpose -packages that come with standard distribution of Emacs. - -@table @samp -@item Transparent FTP -@cindex transparent ftp -@pindex ange-ftp.el -@code{ange-ftp.el} can ftp from the editor to files on other machines -transparent to the user. -@item RCS Interfaces -@cindex version maintenance -@cindex RCS -@pindex vc.el -@code{vc.el} for doing RCS commands from inside the editor -@item Directory Editor -@cindex dired -@pindex dired.el -@code{dired.el} for editing contents of directories and for navigating in -the file system. -@item Syntactic Highlighting -@cindex font-lock -@pindex font-lock.el -@code{font-lock.el} for automatic highlighting various parts of a buffer -using different fonts and colors. -@item Saving Emacs Configuration -@cindex desktop -@pindex desktop.el -@code{desktop.el} for saving/restoring configuration on Emacs exit/startup. -@item Spell Checker -@cindex ispell -@pindex ispell.el -@code{ispell.el} for spell checking the buffer, words, regions, etc. -@item File and Buffer Comparison -@cindex ediff -@pindex ediff.el -@code{ediff.el} for finding differences between files and for applying -patches. -@end table - -@noindent -Emacs Lisp archives exist on -@samp{archive.cis.ohio-state.edu} -and @samp{wuarchive.wustl.edu} - - -@node Customization -@chapter Customization - -@cindex customization - -Customization can be done in 2 ways. - -@itemize @bullet -@item -@cindex initialization -@cindex .viper -Elisp code in a @file{~/.emacs.d/viper} (or @file{~/.viper}) file. -Viper loads this file just before it does the binding for mode hooks. -This is recommended for experts only. -@item -@cindex .emacs -Elisp code in your @file{.emacs} file before and after the @code{(require -'viper)} line. This method is @emph{not} recommended, unless you know what -you are doing. Only two variables, @code{viper-mode} and -@code{viper-custom-file-name}, are supposed to be customized in @file{.emacs}, -prior to loading Viper (i.e., prior to @code{(require 'viper)} command. -@item -@cindex Ex customize -By executing the @kbd{:customize} Ex command. This takes you to the Emacs -customization widget, which lets you change the values of Viper -customizable variables easily. This method is good for novice and -experts alike. The customization code in the form of Lisp commands will be -placed in @file{~/.emacs} or some other customization file depending on the -version of Emacs that you use. Still, it is recommended to separate -Viper-related customization produced by the Emacs customization widget -and keep it in your Viper customization file. - -Some advanced customization cannot be accomplished this way, however, and -has to be done in Emacs Lisp in your Viper customization file. For the common -cases, examples are provided that you can use directly. -@end itemize - - -@menu -* Rudimentary Changes:: Simple constant definitions. -* Key Bindings:: Enabling Emacs Keys, Rebinding keys, etc. -* Packages that Change Keymaps:: How to deal with such beasts. -* Viper Specials:: Special Viper commands. -* Vi Macros:: How to do Vi style macros. -@end menu - -@node Rudimentary Changes -@section Rudimentary Changes - -@cindex setting variables -@cindex variables for customization -@findex @kbd{Ex set} - -An easy way to customize Viper is to change the values of constants used in -Viper. Here is the list of the constants used in Viper and their default -values. The corresponding :se command is also indicated. (The symbols -@code{t} and @code{nil} represent ``true'' and ``false'' in Lisp). - -Viper supports both the abbreviated Vi variable names and their full -names. Variable completion is done on full names only. @key{TAB} and -@key{SPC} complete -variable names. Typing `=' will complete the name and then will prompt for -a value, if applicable. For instance, @kbd{:se au @key{SPC}} will complete the -command to @kbd{:set autoindent}; @kbd{:se ta @key{SPC}} will complete the command -and prompt further like this: @kbd{:set tabstop = }. -However, typing @kbd{:se ts @key{SPC}} will produce a ``No match'' message -because @kbd{ts} is an abbreviation for @kbd{tabstop} and Viper supports -completion on full names only. However, you can still hit @key{RET} -or @kbd{=}, which will complete the command like this: @kbd{:set ts = } and -Viper will be waiting for you to type a value for the tabstop variable. -To get the full list of Vi variables, type @kbd{:se @key{SPC} @key{TAB}}. - -@table @code -@item viper-auto-indent nil -@itemx :se ai (:se autoindent) -@itemx :se ai-g (:se autoindent-global) -If @code{t}, enable auto indentation. -by @key{RET}, @kbd{o} or @kbd{O} command. - -@code{viper-auto-indent} is a local variable. To change the value globally, use -@code{setq-default}. It may be useful for certain major modes to have their -own values of @code{viper-auto-indent}. This can be achieved by using -@code{setq} to change the local value of this variable in the hooks to the -appropriate major modes. - -@kbd{:se ai} changes the value of @code{viper-auto-indent} in the current -buffer only; @kbd{:se ai-g} does the same globally. -@item viper-electric-mode t -If not @code{nil}, auto-indentation becomes electric, which means that -@key{RET}, @kbd{O}, and @kbd{o} indent cursor according to the current -major mode. In the future, this variable may control additional electric -features. - -This is a local variable: @code{setq} changes the value of this variable -in the current buffer only. Use @code{setq-default} to change the value in -all buffers. -@item viper-case-fold-search nil -@itemx :se ic (:se ignorecase) -If not @code{nil}, search ignores cases. -This can also be toggled by quickly hitting @kbd{/} twice. -@item viper-re-search nil -@itemx :se magic -If not @code{nil}, search will use regular expressions; if @code{nil} then -use vanilla search. -This behavior can also be toggled by quickly hitting @kbd{/} trice. -@item buffer-read-only -@itemx :se ro (:se readonly) -Set current buffer to read only. To change globally put -@code{(setq-default buffer-read-only t)} in your @file{.emacs} file. -@item blink-matching-paren t -@itemx :se sm (:se showmatch) -Show matching parens by blinking cursor. -@item tab-width t (default setting via @code{setq-default}) -@itemx :se ts=value (:se tabstop=value) -@itemx :se ts-g=value (:se tabstop-global=value) -@code{tab-width} is a local variable that controls the width of the tab stops. -To change the value globally, use @code{setq-default}; for local settings, -use @code{setq}. - -The command @kbd{:se ts} -sets the tab width in the current -buffer only; it has no effect on other buffers. - -The command @kbd{:se ts-g} sets tab width globally, -for all buffers where the tab is not yet set locally, -including the new buffers. - -Note that typing @key{TAB} normally -doesn't insert the tab, since this key is usually bound to -a text-formatting function, @code{indent-for-tab-command} (which facilitates -programming and document writing). Instead, the tab is inserted via the -command @code{viper-insert-tab}, which is bound to @kbd{S-tab} (shift + tab). - -On some non-windowing terminals, Shift doesn't modify the @key{TAB} key, so -@kbd{S-tab} behaves as if it were @key{TAB}. In such a case, you will have -to bind @code{viper-insert-tab} to some other convenient key. - -@item viper-shift-width 8 -@itemx :se sw=value (:se shiftwidth=value) -The number of columns shifted by @kbd{>} and @kbd{<} commands. -@item viper-search-wrap-around t -@itemx :se ws (:se wrapscan) -If not @code{nil}, search wraps around the end/beginning of buffer. -@item viper-search-scroll-threshold 2 -If search lands within this many lines of the window top or bottom, the -window will be scrolled up or down by about 1/7-th of its size, to reveal -the context. If the value is negative, don't scroll. -@item viper-tags-file-name "TAGS" -The name of the file used as the tag table. -@item viper-re-query-replace nil -If not @code{nil}, use reg-exp replace in query replace. -@item viper-want-ctl-h-help nil -If not @code{nil}, @kbd{C-h} is bound to @code{help-command}; -otherwise, @kbd{C-h} is bound as usual in Vi. -@item viper-vi-style-in-minibuffer t -If not @code{nil}, Viper provides a high degree of compatibility with Vi -insert mode when you type text in the minibuffer; if @code{nil}, typing in -the minibuffer feels like plain Emacs. -@item viper-no-multiple-ESC t -If you set this to @code{nil}, you can use @key{ESC} as Meta in Vi state. -Normally, this is not necessary, since graphical displays have separate -Meta keys (usually on each side of the space bar). On a dumb terminal, Viper -sets this variable to @code{twice}, which is almost like @code{nil}, except -that double @key{ESC} beeps. This, too, lets @key{ESC} to be used as a Meta. -@item viper-fast-keyseq-timeout 200 -Key sequences separated by this many milliseconds are treated as Vi-style -keyboard macros. If the key sequence is defined as such a macro, it will be -executed. Otherwise, it is processed as an ordinary sequence of typed keys. - -Setting this variable too high may slow down your typing. Setting it too -low may make it hard to type macros quickly enough. -@item viper-ex-style-motion t -Set this to @code{nil}, if you want @kbd{l,h} to cross -lines, etc. @xref{Movement and Markers}, for more info. -@item viper-ex-style-editing t -Set this to @code{nil}, if you want -@kbd{C-h} and @key{DEL} to not stop -at the beginning of a line in Insert state, @key{X} and @key{x} to delete -characters across lines in Vi command state, etc. -@item viper-ESC-moves-cursor-back t -It @code{t}, cursor moves back 1 character when switching from insert state to vi -state. If @code{nil}, the cursor stays where it was before the switch. -@item viper-always t -@code{t} means: leave it to Viper to decide when a buffer must be brought -up in Vi state, -Insert state, or Emacs state. This heuristics works well in virtually all -cases. @code{nil} means you either has to invoke @code{viper-mode} manually -for each buffer (or you can add @code{viper-mode} to the appropriate major mode -hooks using @code{viper-load-hook}). - -This option must be set in your Viper customization file. -@item viper-custom-file-name "~/.emacs.d/viper" -File used for Viper-specific customization. -Change this setting, if you want. Must be set in @file{.emacs} -before Viper is loaded. Note that you -have to set it as a string inside double quotes. -@item viper-spell-function 'ispell-region -Function used by the command @kbd{#c} to spell. -@item viper-glob-function -The value of this variable is the function symbol used to expand wildcard -symbols. This is platform-dependent. The default tries to set this variable -to work with most shells, MS Windows, OS/2, etc. However, if it -doesn't work the way you expect, you should write your own. -Use @code{viper-glob-unix-files} and @code{viper-glob-mswindows-files} in -@file{viper-util.el} as examples. - -This feature is used to expand wildcards in the Ex command @kbd{:e}. -Note that Viper doesn't support wildcards in the @kbd{:r} and @kbd{:w} -commands, because file completion is a better mechanism. -@findex @code{viper-glob-function} - -@item ex-cycle-other-window t -If not @code{nil}, @kbd{:n} and @kbd{:b} will cycle through files in another -window, if one exists. -@item ex-cycle-through-non-files nil -@kbd{:n} does not normally cycle through buffers. Set this to get -buffers also. -@item viper-want-emacs-keys-in-insert -This is set to @code{nil} for user levels 1 and 2 and to @code{t} for user -levels 3 and 4. Users who specify level 5 are allowed to set this variable -as they please (the default for this level is @code{t}). If set to -@code{nil}, complete Vi compatibility is provided in Insert state. This is -really not recommended, as this precludes you from using language-specific -features provided by the major modes. -@item viper-want-emacs-keys-in-vi -This is set to @code{nil} for user -level 1 and to @code{t} for user levels 2--4. -At level 5, users are allowed to set this variable as they please (the -default for this level is @code{t}). -If set to @code{nil}, complete Vi compatibility is provided -in Vi command state. Setting this to @code{nil} is really a bad idea, -unless you are a novice, as this precludes the use -of language-specific features provided by the major modes. -@item viper-keep-point-on-repeat t -If not @code{nil}, point is not moved when the user repeats the previous -command by typing `.' This is very useful for doing repeated changes with -the @kbd{.} key. -@item viper-repeat-from-history-key 'f12 -Prefix key used to invoke the macros @kbd{f12 1} and @kbd{f12 2} that repeat -the second-last and the third-last destructive command. -Both these macros are bound (as Viper macros) to -@code{viper-repeat-from-history}, -which checks the second key by which it is invoked to see which of the -previous commands to invoke. Viper binds @kbd{f12 1} and @kbd{f12 2} only, -but the user can bind more in his/her Viper customization file. -@xref{Vi Macros}, for how to do this. -@item viper-keep-point-on-undo nil -If not @code{nil}, Viper tries to not move point when undoing commands. -Instead, it will briefly move the cursor to the place where change has -taken place. However, if the undone piece of text is not seen in window, -then point will be moved to the place where the change took place. -Set it to @code{t} and see if you like it better. -@item viper-delete-backwards-in-replace nil -If not @code{nil}, @key{DEL} key will delete characters while moving the cursor -backwards. If @code{nil}, the cursor will move backwards without deleting -anything. -@item viper-replace-overlay-face 'viper-replace-overlay-face -On a graphical display, Viper highlights replacement regions instead of -putting a @samp{$} at the end. This variable controls the so called -@dfn{face} used to highlight the region. - -By default, @code{viper-replace-overlay-face} underlines the replacement on -monochrome displays and also lays a stipple over them. On color displays, -replacement regions are highlighted with color. - -If you know something about Emacs faces and don't like how Viper highlights -replacement regions, you can change @code{viper-replace-overlay-face} by -specifying a new face. (Emacs faces are described in the Emacs Lisp -reference.) On a color display, the following customization method is -usually most effective: -@smallexample -(set-face-foreground viper-replace-overlay-face "DarkSlateBlue") -(set-face-background viper-replace-overlay-face "yellow") -@end smallexample -For a complete list of colors available to you, evaluate the expression -@code{(x-defined-colors)}. (Type it in the buffer @file{*scratch*} and then -hit the @kbd{C-j} key. - -@item viper-replace-overlay-cursor-color "Red" -@vindex @code{viper-replace-overlay-cursor-color} -Cursor color when it is inside the replacement region. -This has effect only on color displays and only when Emacs runs as an X -application. -@item viper-insert-state-cursor-color nil -@vindex @code{viper-insert-state-cursor-color} -If set to a valid color, this will be the cursor color when Viper is in -insert state. -@item viper-emacs-state-cursor-color nil -@vindex @code{viper-emacs-state-cursor-color} -If set to a valid color, this will be the cursor color when Viper is in -emacs state. -@item viper-replace-region-end-delimiter "$" -A string used to mark the end of replacement regions. It is used only on -TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}. -@item viper-replace-region-start-delimiter "" -A string used to mark the beginning of replacement regions. It is used -only on TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}. -@item viper-use-replace-region-delimiters -If non-@code{nil}, Viper will always use @code{viper-replace-region-end-delimiter} and -@code{viper-replace-region-start-delimiter} to delimit replacement regions, -even on color displays (where this is unnecessary). By default, this -variable is non-@code{nil} only on TTYs or monochrome displays. -@item viper-allow-multiline-replace-regions t -If non-@code{nil}, multi-line text replacement regions, such as those produced by -commands @kbd{c55w}, @kbd{3C}, etc., will stay around until the user exits -the replacement mode. In this variable is set to @code{nil}, Viper will -emulate the standard Vi behavior, which supports only intra-line -replacement regions (and multi-line replacement regions are deleted). -@item viper-toggle-key "\C-z" -Specifies the key used to switch from Emacs to Vi and back. -Must be set in your Viper customization file. This variable can't be -changed interactively after Viper is loaded. - -In Insert state, this key acts as a temporary escape to Vi state, i.e., it -will set Viper up so that the very next command will be executed as if it -were typed in Vi state. -@item viper-buffer-search-char nil -Key used for buffer search. @xref{Viper Specials}, for details. -@item viper-surrounding-word-function 'viper-surrounding-word -The value of this variable is a function name that is used to determine -what constitutes a word clicked upon by the mouse. This is used by mouse -search and insert. -@item viper-search-face 'viper-search-face -Variable that controls how search patterns are highlighted when they are -found. -@item viper-vi-state-hook nil -List of parameterless functions to be run just after entering the Vi -command state. -@item viper-insert-state-hook nil -Same for Insert state. This hook is also run after entering Replace state. -@item viper-replace-state-hook nil -List of (parameterless) functions called just after entering Replace state -(and after all @code{viper-insert-state-hook}). -@item viper-emacs-state-hook nil -List of (parameterless) functions called just after switching from Vi state -to Emacs state. -@item viper-load-hook nil -List of (parameterless) functions called just after loading Viper. This is -the last chance to do customization before Viper is up and running. -@end table -@noindent -You can reset some of these constants in Viper with the Ex command @kbd{:set} -(when so indicated in the table). Or you -can include a line like this in your Viper customization file: -@example -(setq viper-case-fold-search t) -@end example -@vindex @code{viper-auto-indent} -@vindex @code{viper-electric-mode} -@vindex @code{viper-case-fold-search} -@vindex @code{viper-re-search} -@vindex @code{viper-shift-width} -@vindex @code{buffer-read-only} -@vindex @code{viper-search-wrap-around} -@vindex @code{viper-search-scroll-threshold} -@vindex @code{viper-search-face} -@vindex @code{viper-tags-file-name} -@vindex @code{viper-re-query-replace} -@vindex @code{viper-want-ctl-h-help} -@vindex @code{viper-vi-style-in-minibuffer} -@vindex @code{viper-no-multiple-ESC} -@vindex @code{viper-always} -@vindex @code{viper-fast-keyseq-timeout} -@vindex @code{viper-ex-style-motion} -@vindex @code{viper-ex-style-editing} -@vindex @code{viper-ESC-moves-cursor-back} -@vindex @code{viper-custom-file-name} -@vindex @code{viper-spell-function} -@vindex @code{ex-cycle-other-window} -@vindex @code{ex-cycle-through-non-files} -@vindex @code{viper-want-emacs-keys-in-insert} -@vindex @code{viper-want-emacs-keys-in-vi} -@vindex @code{viper-keep-point-on-repeat} -@vindex @code{viper-keep-point-on-undo} -@vindex @code{viper-delete-backwards-in-replace} -@vindex @code{viper-replace-overlay-face} -@vindex @code{viper-replace-region-end-symbol} -@vindex @code{viper-replace-region-start-symbol} -@vindex @code{viper-allow-multiline-replace-regions} -@vindex @code{viper-toggle-key} -@vindex @code{viper-buffer-search-char} -@vindex @code{viper-surrounding-word-function} -@vindex @code{viper-vi-state-hook} -@vindex @code{viper-insert-state-hook} -@vindex @code{viper-replace-state-hook} -@vindex @code{viper-emacs-state-hook} - -@node Key Bindings -@section Key Bindings - -@cindex key bindings -@cindex keymaps - -Viper lets you define hot keys, i.e., you can associate keyboard keys -such as F1, Help, PgDn, etc., with Emacs Lisp functions (that may already -exist or that you will write). Each key has a "preferred form" in -Emacs. For instance, the Up key's preferred form is [up], the Help key's -preferred form is [help], and the Undo key has the preferred form [f14]. -You can find out the preferred form of a key by typing @kbd{M-x -describe-key-briefly} and then typing the key you want to know about. - -Under the X Window System, every keyboard key emits its preferred form, -so you can just type - -@lisp -(global-set-key [f11] 'calendar) ; L1, Stop -(global-set-key [f14] 'undo) ; L4, Undo -@end lisp - -@noindent -to bind L1 (a key that exists on some SUN workstations) so it will invoke -the Emacs Calendar and to bind L4 so it will undo changes. -However, on a dumb terminal or in an Xterm window, even the standard arrow -keys may -not emit the right signals for Emacs to understand. To let Emacs know about -those keys, you will have to find out which key sequences they emit -by typing @kbd{C-q} and then the key (you should switch to Emacs state -first). Then you can bind those sequences to their preferred forms using -@code{input-decode-map} as follows: - -@lisp -(cond ((string= (getenv "TERM") "xterm") -(define-key input-decode-map "\e[192z" [f11]) ; L1 -(define-key input-decode-map "\e[195z" [f14]) ; L4, Undo -@end lisp - -The above illustrates how to do this for Xterm. On VT100, you would have to -replace "xterm" with "vt100" and also change the key sequences (the same -key may emit different sequences on different types of terminals). - -The above keys are global, so they are overwritten by the local maps -defined by the major modes and by Viper itself. Therefore, if you wish to -change a binding set by a major mode or by Viper, read this. - -Viper users who wish to specify their own key bindings should be concerned -only with the following three keymaps: -@code{viper-vi-global-user-map} for Vi state commands, -@code{viper-insert-global-user-map} for Insert state commands, -and @code{viper-emacs-global-user-map} for Emacs state commands (note: -customized bindings for Emacs state made to @code{viper-emacs-global-user-map} -are @emph{not} inherited by Insert state). - -For more information on Viper keymaps, see the header of the file -@file{viper.el}. -If you wish to change a Viper binding, you can use the -@code{define-key} command, to modify @code{viper-vi-global-user-map}, -@code{viper-insert-global-user-map}, and @code{viper-emacs-global-user-map}, as -explained below. Each of these key maps affects the corresponding Viper state. -The keymap @code{viper-insert-global-user-map} also affects Viper's Replace -state. - -@noindent -If you want to -bind a key, say @kbd{C-v}, to the function that scrolls -page down and to make @kbd{0} display information on the current buffer, -putting this in your Viper customization file will do the trick in Vi state: -@example -(define-key viper-vi-global-user-map "\C-v" 'scroll-down) -@end example -@noindent -To set a key globally, -@example -(define-key viper-emacs-global-user-map "\C-c m" 'smail) -(define-key viper-vi-global-user-map "0" 'viper-info-on-file) -@end example -@noindent -Note, however, that this binding may be overwritten by other keymaps, since -the global keymap has the lowest priority. -To make sure that nothing will override a binding in Emacs state, you -can write this: -@example -(define-key viper-emacs-global-user-map "\C-c m" 'smail) -@end example -@noindent -To customize the binding for @kbd{C-h} in Insert state: -@example -(define-key viper-insert-global-user-map "\C-h" - 'my-del-backwards-function) -@end example -@noindent - -Each Emacs command key calls some Lisp function. If you have enabled the -Help, (@pxref{Rudimentary Changes}) @kbd{C-h k} will show you the function -for each specific key; @kbd{C-h b} will show all bindings, and @kbd{C-h m} -will provide information on the major mode in effect. If Help is not -enabled, you can still get help in Vi state by prefixing the above commands -with @kbd{\}, e.g., @kbd{\ C-h k} (or you can use the Help menu in the -menu bar, if Emacs runs under X). - -Viper users can also change bindings on a per major mode basis. As with -global bindings, this can be done separately for each of the three main Viper -states. To this end, Viper provides the function -@code{viper-modify-major-mode}. -@findex @code{viper-modify-major-mode} - -To modify keys in Emacs state for @code{my-favorite-major-mode}, the user -needs to create a sparse keymap, say, @code{my-fancy-map}, bind whatever -keys necessary in that keymap, and put - -@example -(viper-modify-major-mode 'dired-mode 'emacs-state my-fancy-map) -@end example - -@noindent -in your Viper customization file. To do the same in Vi and Insert states, you -should use @code{vi-state} and @code{insert-state}. Changes in Insert state -are also in effect in Replace state. For instance, suppose that the user wants -to use @kbd{dd} in Vi state under Dired mode to delete files, @kbd{u} to unmark -files, etc. The following code in the Viper customization file will then do -the job: - -@example -(setq my-dired-modifier-map (make-sparse-keymap)) -(define-key my-dired-modifier-map "dd" 'dired-flag-file-deletion) -(define-key my-dired-modifier-map "u" 'dired-unmark) -(viper-modify-major-mode 'dired-mode 'vi-state my-dired-modifier-map) -@end example - -A Vi purist may want to modify Emacs state under Dired mode so that -@kbd{k}, @kbd{l}, etc., will move around in directory buffers, as in -Vi. Although this is not recommended, as these keys are bound to useful -Dired functions, the trick can be accomplished via the following code: - -@example -(setq my-dired-vi-purist-map (make-sparse-keymap)) -(define-key my-dired-vi-purist-map "k" 'viper-previous-line) -(define-key my-dired-vi-purist-map "l" 'viper-forward-char) -(viper-modify-major-mode 'dired-mode - 'emacs-state my-dired-vi-purist-map) -@end example - -Yet another way to customize key bindings in a major mode is to edit the -list @code{viper-major-mode-modifier-list} using the customization widget. -@vindex @code{viper-major-mode-modifier-list} -(This variable is in the Viper-misc customization group.) -The elements of this list are triples of the form: (major-mode viper-state -keymap), where the keymap contains bindings that are supposed to be active -in the given major mode and the given viper-state. - -Effects similar to key binding changes can be achieved by defining Vi -keyboard macros using the Ex commands @kbd{:map} and @kbd{:map!}. The -difference is that multi-key Vi macros do not override the keys they are -bound to, unless these keys are typed in quick succession. So, with macros, -one can use the normal keys alongside with the macros. If per-mode -modifications are needed, the user can try both ways and see which one is -more convenient. -@findex @kbd{Ex map} -@xref{Vi Macros}, for details. - -Note: in major modes that come up in @emph{Emacs state} by default, the -aforesaid modifications may not take place immediately (but only after the -buffer switches to some other Viper state and then back to Emacs state). To -avoid this, one should add @code{viper-change-state-to-emacs} to an -appropriate hook of that major mode. (Check the function -@code{viper-set-hooks} in @file{viper.el} for examples.) However, if you -did not set @code{viper-always} to @code{nil}, chances are that you won't -need to perform the above procedure, because Viper will take care of most -useful defaults. - - -Finally, Viper has a facility that lets the user define per-buffer -bindings, i.e., bindings that are in effect in some specific buffers -only. Unlike per-mode bindings described above, per-buffer bindings can be -defined based on considerations other than the major mode. This is done -via the function @code{viper-add-local-keys}, which lets one specify bindings -that should be in effect in the current buffer only and for a specific Viper -state. For instance, -@lisp -(viper-add-local-keys 'vi-state '(("ZZ" .@: TeX-command-master) - ("ZQ" .@: viper-save-kill-buffer))) -@end lisp -@noindent -redefines @kbd{ZZ} to invoke @code{TeX-command-master} in @code{vi-state} -and @kbd{ZQ} to save-then-kill the current buffer. These bindings take -effect only in the buffer where this command is executed. The typical use -of this function is to execute the above expression from within a function -that is included in a hook to some major mode. For instance, the above -expression -could be called from a function, @code{my-tex-init}, which may be added to -@code{tex-mode-hook} as follows: -@lisp -(add-hook 'tex-mode-hook 'my-tex-init) -@end lisp -@noindent -When TeX mode starts, the hook is executed and the above Lisp expression is -evaluated. Then, the bindings for @kbd{ZZ} and @kbd{ZQ} are changed in Vi -command mode for all buffers in TeX mode. - -Another useful application is to bind @kbd{ZZ} to @code{send-mail} -in the Mail mode buffers (the specifics of this depend on which mail -package you are using, @code{rmail}, @code{mh-e}, @code{vm}, etc. -For instance, here is how to do this for @code{mh-e}, the Emacs interface -to MH: -@lisp -(defun mh-add-vi-keys () - "Set up ZZ for MH-e and XMH." - (viper-add-local-keys 'vi-state '(("ZZ" .@: mh-send-letter)))) -(add-hook 'mh-letter-mode-hook 'mh-add-vi-keys) -@end lisp - -You can also use @code{viper-add-local-keys} to set per buffer -bindings in Insert state and Emacs state by passing as a parameter the -symbols @code{insert-state} and @code{emacs-state}, respectively. -As with global bindings, customized local bindings done to Emacs state -are not inherited by Insert state. - -On rare occasions, local keys may be added by mistake. Usually this is done -indirectly, by invoking a major mode that adds local keys (e.g., -@code{shell-mode} redefines @key{RET}). In such a case, exiting the wrong -major mode won't rid you from unwanted local keys, since these keys are -local to Viper state and the current buffer, not to the major mode. -In such situations, the remedy is to type @kbd{M-x viper-zap-local-keys}. - -So much about Viper-specific bindings. -@xref{Customization,,Customization,emacs,The GNU Emacs -Manual}, and the Emacs quick reference card for the general info on key -bindings in Emacs. - -@vindex @code{input-decode-map} -@vindex @code{function-key-map} -@vindex @code{viper-vi-global-user-map} -@vindex @code{viper-insert-global-user-map} -@vindex @code{viper-emacs-global-user-map} -@findex @code{viper-add-local-keys} -@findex @code{viper-zap-local-keys} - -@node Packages that Change Keymaps -@section Packages that Change Keymaps -@cindex C-c and Viper -@cindex Viper and C-c - -Viper is designed to coexist with all major and minor modes of Emacs. This -means that bindings set by those modes are generally available with Viper -(unless you explicitly prohibit them by setting -@code{viper-want-emacs-keys-in-vi} and @code{viper-want-emacs-keys-in-insert} to -@code{nil}). -If @code{viper-always} is set to @code{t} (which is the default), Viper -will try to bring each buffer -in the Viper state that is most appropriate for that buffer. -Usually, this would be the Vi state, but sometimes it could be the Insert -state or the Emacs state. - -Some major mode bindings will necessarily be overwritten by Viper. Indeed, in -Vi state, most of the 1-character keys are used for Vi-style editing. This -usually causes no problems because most packages designed for editing files -typically do not bind such keys. Instead, they use key sequences that start -with @kbd{C-x} and @kbd{C-c}. This is why it was so important for us to -free up @kbd{C-x} and @kbd{C-c}. -It is common for language-specific major modes to bind @key{TAB} and -@kbd{C-j} (the line feed) keys to various formatting functions. This is -extremely useful, but may require some getting used to for a Vi user. If you -decide that this feature is not for you, you can re-bind these keys as -explained earlier (@pxref{Customization}). - -Binding for @key{TAB} is one of the most unusual aspects of Viper for many -novice users. In Emacs, @key{TAB} is used to format text and programs, and -is extremely useful. For instance, hitting @key{TAB} causes the current -line to be re-indented in accordance with the context. In programming, -this is very important, since improper automatic indentation would -immediately alert the programmer to a possible error. For instance, if a -@kbd{)} or a @kbd{"} is missing somewhere above the current -line, @key{TAB} is likely to mis-indent the line. - -For this reason, Viper doesn't change the standard Emacs binding of -@key{TAB}, thereby sacrificing Vi compatibility -(except for users at level 1). Instead, in Viper, the key -@kbd{S-tab} (shift+ tab) is chosen to emulate Vi's @key{TAB}. - -We should note that on some non-windowing terminals, Shift doesn't modify -the @key{TAB} key, so @kbd{S-tab} behaves as if it were @key{TAB}. In such -a case, you will have to bind @code{viper-insert-tab} to some other -convenient key. - -Some packages, notably Dired, Gnus, Info, etc., attach special meaning to -common keys like @key{SPC}, @kbd{x}, @kbd{d}, @kbd{v}, and others. This -means that Vi command state is inappropriate for working with these -packages. Fortunately, these modes operate on read-only buffers and are -designed not for editing files, but for special-purpose browsing, reading -news, mail, etc., and Vi commands are meaningless in these situations. For -this reason, Viper doesn't force Vi state on such major modes---it -brings them in Emacs state. You can switch to Vi state by typing @kbd{C-z} -if, for instance, you want to do Vi-style search in a buffer (although, -usually, incremental search, which is bound to @kbd{C-s}, is sufficient in -these situations). But you should then switch back to Emacs state if you -plan to continue using these major modes productively. You can also switch -to Vi temporarily, to execute just one command. This is done by typing -@kbd{C-c \}. (In some of these modes, @kbd{/} and @kbd{:} are bound -Vi-style, unless these keys perform essential duties.) - -If you would like certain major modes to come up in Emacs state rather than -Vi state (but Viper thinks otherwise), you should put these major modes -on the @code{viper-emacs-state-mode-list} list and delete them from -@code{viper-vi-state-mode-list}. -Likewise, you can force Viper's Insert state on a major mode by putting it -in @code{viper-insert-state-mode-list}. -@vindex @code{viper-emacs-state-mode-list} -@vindex @code{viper-insert-state-mode-list} -@vindex @code{viper-vi-state-mode-list} - -It is also possible to impose Vi on some major modes, even though they may -bind common keys to specialized commands. This might make sense for modes -that bind only a small number of common keys. For instance, Viper subverts -the Shell mode by changing the bindings for @kbd{C-m} and @kbd{C-d} using -@code{viper-add-local-keys} described in the section on customization -(@pxref{Customization}). - -In some cases, some @emph{minor} modes might override certain essential -bindings in Vi command state. This is not a big problem because this -can happen only in the beginning, when the minor mode kicks in. Typing -@code{M-x viper-mode} will correct the situation. Viper knows about -several such minor modes and takes care of them, so the above trick -is usually not necessary. If you find that some minor mode, e.g., -@code{nasty-mode} interferes with Viper, putting the following in -your Viper customization file should fix the problem: -@lisp -(viper-harness-minor-mode "nasty-mode") -@end lisp -@noindent -The argument to @code{viper-harness-minor-mode} is the name of the file for the -offending minor mode with the suffixes @file{.el} and @file{.elc} removed. - -It may not be always obvious which minor mode is at fault. The only -guidance here is to look into the file that defines the minor mode you are -suspecting, say @file{nasty-mode.el}, and see if it has a variable called -@code{nasty-mode-map}. Then check if there is a statement of the form -@lisp -(define-key nasty-mode-map key function) -@end lisp -@noindent -that binds the misbehaving -keys. If so, use the above line to harness @code{nasty-mode}. If your -suspicion is wrong, no harm is done if you harness a minor mode that -doesn't need to be harnessed. - -It is recommended to harness even those minor modes that don't override -Viper keys, but still have their own keymaps. A general way to -make a minor mode, @code{my-mode}, -compatible with Viper is to have the file @file{my-mode.el} include the following code: - -@lisp -(when (fboundp 'viper-harness-minor-mode) - (let ((lib (file-name-sans-extension - (file-name-nondirectory load-file-name)))) - (viper-harness-minor-mode lib))) -@end lisp - -@vindex @code{viper-want-emacs-keys-in-vi} -@vindex @code{viper-want-emacs-keys-in-insert} -@vindex @code{viper-always} -@findex @code{viper-set-hooks} -@findex @code{viper-mode} -@findex @code{viper-harness-minor-mode} -@findex @code{remove-hook} -@findex @code{add-hook} - -@node Viper Specials -@section Viper Specials - -Viper extends Vi with a number of useful features. This includes various -search functions, histories of search strings, Ex commands, insertions, and -Vi's destructive commands. In addition, Viper supports file name completion -and history, completion of Ex commands and variables, and many other -features. Some of these features are explained in detail elsewhere in this -document. Other features are explained here. - -@table @code -@item (viper-buffer-search-enable) -@item viper-buffer-search-char nil -Enable buffer search. Explicit call to @code{viper-buffer-search-enable} -sets @code{viper-buffer-search-char} to @kbd{g}. Alternatively, the user can -set @code{viper-buffer-search-char} in his/her Viper customization file to a key -sequence to be used for buffer search. There is no need to call -@code{viper-buffer-search-enable} in that case. -@findex @code{viper-buffer-search-enable} -@vindex @code{viper-buffer-search-char} -@item viper-toggle-search-style -This function, bound to @kbd{C-c /}, lets one toggle case-sensitive and -case-insensitive search, and also switch between plain vanilla search and -search via regular expressions. Without the prefix argument, the user is -asked which mode to toggle. With prefix argument 1, this toggles -case-sensitivity. With prefix argument 2, regular expression/vanilla search -will be toggled. - -However, we found that the most convenient way to toggle -these options is to bind a Vi macro to -bind @kbd{//} to toggles case sensitivity and to @kbd{///} to toggles -vanilla search. Thus, quickly hitting @kbd{/} twice will switch Viper from -case sensitive search to case-insensitive. Repeating this once again will -restore the original state. Likewise, quickly hitting @kbd{/} three times -will switch you from vanilla-style search to search via regular expressions. -If you hit something other than @kbd{/} after the first @kbd{/} or if the -second @kbd{/} doesn't follow quickly enough, then Viper will issue the -usual prompt @kbd{/} and will wait for input, as usual in Vi. -If you don't like this behavior, you can ``unrecord'' these macros in your -Viper customization file. For instance, if you don't like the above -feature, put this in the file: -@example -(viper-set-searchstyle-toggling-macros 'undefine) -@end example -@findex @code{viper-set-searchstyle-toggling-macros} - -If you don't like this feature as a default, but would still like to have -it in some major modes, you can do so by first unsetting it globally, as -shown above, and then setting it in the desired major modes as follows: -@example -(viper-set-searchstyle-toggling-macros nil 'c-mode) -(viper-set-searchstyle-toggling-macros nil 'lisp-mode) -@end example - -@item Vi-isms in Emacs state -Some people find it useful to use the Vi-style search key, `/', to invoke -search in modes which Viper leaves in emacs-state. These modes are: -@code{dired-mode}, @code{mh-folder-mode}, -@code{Info-mode}, and @code{Buffer-menu-mode} -(more may be added in the future). So, in the above modes, Viper binds `/' -so that it will behave Vi-style. Furthermore, in those major modes, Viper -binds `:' to invoke ex-style commands, like in vi-state. And, as described -above, `//' and `///' get bound to Vi-style macros that toggle -case-insensitivity and regexp-search. - -If you don't like these features---which I don't really understand---you -can unbind `/' and `:' in @code{viper-dired-modifier-map} (for Dired) or in -@code{viper-slash-and-colon-map}, for other modes. -@vindex @code{viper-slash-and-colon-map} -@vindex @code{viper-dired-modifier-map} - -To unbind the macros `//' and `///' for a major mode where you feel they -are undesirable, execute @code{viper-set-emacs-state-searchstyle-macros} with a -non-@code{nil} argument. This can be done either interactively, by supplying a -prefix argument, or by placing -@example -(viper-set-emacs-state-searchstyle-macros 'undefine) -@end example -@findex @code{viper-set-emacs-state-searchstyle-macros} -in the hook to the major mode (e.g., @code{dired-mode-hook}). -@xref{Vi Macros}, for more information on Vi macros. - -@item viper-heading-start -@item viper-heading-end -@cindex headings -@cindex sections -@cindex paragraphs -@cindex sentences -Regular Expressions for @kbd{[[} and @kbd{]]}. Note that Emacs defines -Regexps for paragraphs and sentences. @xref{Paragraphs,,Paragraphs and -Sentences,emacs,The GNU Emacs Manual}, for details. -@item M-x viper-set-expert-level -@findex @code{viper-set-expert-level} -Change your user level interactively. -@item viper-smart-suffix-list '("" "tex" "c" "cc" "el" "p") -@vindex @code{viper-smart-suffix-list} -Viper supports Emacs-style file completion when it prompts the user for a -file name. However, in many cases, the same directory may contain files -with identical prefix but different suffixes, e.g., prog.c, prog.o, -paper.tex, paper.dvi. In such cases, completion will stop at the `.'. -If the above variable is a list of strings representing suffixes, Viper will -try these suffixes -in the order listed and will check if the corresponding file exists. - -For instance, if completion stopped at `paper.'@: and the user typed -@key{RET}, -then Viper will check if the files `paper.', `paper.tex', `paper.c', etc., exist. -It will take the first such file. If no file exists, Viper will give a chance -to complete the file name by typing the appropriate suffix. If `paper.'@: was -the intended file name, hitting return will accept it. - -To turn this feature off, set the above variable to @code{nil}. - -@item viper-insertion-ring-size 14 -@vindex @code{viper-insertion-ring-size} -@cindex Insertion ring -Viper remembers what was previously inserted in Insert and Replace states. -Several such recent insertions are kept in a special ring of strings of size -@code{viper-insertion-ring-size}. -If you enter Insert or Replace state you can reinsert strings from this -ring by typing @kbd{C-c M-p} or @kbd{C-c M-n}. The former will search the -ring in -the direction of older insertions, and the latter will search in -the direction of newer insertions. Hitting @kbd{C-c M-p} or @kbd{C-c M-n} -in succession -will undo the previous insertion from the ring and insert the next item on -the ring. If a larger ring size is needed, change the value of the above -variable in the Viper customization file. - -Since typing these sequences of keys may be tedious, it is suggested that the -user should bind a function key, such as @kbd{f31}, as follows: -@example -(define-key viper-insert-global-user-map [f31] - 'viper-insert-prev-from-insertion-ring) -@end example -This binds @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) -to the function that inserts the previous string in the insertion history. -To rotate the history in the opposite -direction, you can either bind an unused key to -@code{viper-insert-next-from-insertion-ring} or hit any digit (1 to 9) then -@kbd{f31}. - -One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since -this will interfere with the minibuffer histories and, possibly, other -major modes. - -@item viper-command-ring-size 14 -@vindex @code{viper-command-ring-size} -@cindex Destructive command ring -@cindex Destructive command history -Viper keeps track of the recent history of destructive -commands, such as @kbd{dw}, @kbd{i}, etc. -In Vi state, -the most recent command can be re-executed by hitting `@kbd{.}', as in Vi. -However, repeated typing @kbd{C-c M-p} will cause Viper to show the -previous destructive commands in the minibuffer. Subsequent hitting `@kbd{.}' -will execute the command that was displayed last. -The key @kbd{C-c M-n} will cycle through the command history in the -opposite direction. -Since typing @kbd{C-c M-p} may be tedious, it is more convenient to bind an -appropriate function to an unused function key on the keyboard and use that -key. For instance, the following -@example -(define-key viper-vi-global-user-map [f31] - 'viper-prev-destructive-command) -@end example -binds the key @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) -to the function that searches the command history in the direction of older -commands. To search in the opposite -direction, you can either bind an unused key to -@code{viper-next-destructive-command} or hit any digit (1 to 9) then @kbd{f31}. - -One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since -this will interfere with the minibuffer histories and, possibly, other -major modes. - -@item viper-minibuffer-vi-face 'viper-minibuffer-vi-face -@item viper-minibuffer-insert-face 'viper-minibuffer-insert-face -@item viper-minibuffer-emacs-face 'viper-minibuffer-emacs-face -These faces control the appearance of the minibuffer text in the -corresponding Viper states. You can change the appearance of these faces -through Emacs's customization widget, which is accessible through the -menubar. - -Viper is located in this widget under the @emph{Emulations} customization -subgroup of the @emph{Editing} group. All Viper faces are grouped together -in Viper's @emph{Highlighting} customization subgroup. - -Note that only the text you type in is affected by the above faces. -Prompts and minibuffer messages are not affected. - -Purists who do not like adornments in the minibuffer can always zap them by -putting -@example -(copy-face 'default 'viper-minibuffer-vi-face) -(copy-face 'default 'viper-minibuffer-insert-face) -(copy-face 'default 'viper-minibuffer-emacs-face) -@end example -in their Viper customization file or through the customization widget, as -described above. However, in that case, the user will not have any -indication of the current Viper state in the minibuffer. (This is important -if the user accidentally switches to another Viper state by typing @key{ESC} or -@kbd{C-z}). -@item M-x viper-go-away -@findex @code{viper-go-away} -Make Viper disappear from the face of your running Emacs instance. If your -fingers start aching again, @kbd{M-x viper-mode} might save your day. -@item M-x toggle-viper-mode -@findex @code{toggle-viper-mode} -Toggle Viperization of Emacs on and off. -@end table - -@cindex Multifile documents and programs - -Viper provides some support for multi-file documents and programs. -If a document consists of several files we can designate one of them as a -master and put the following at the end of that file: -@lisp -;; Local Variables: -;; eval: (viper-setup-master-buffer "file1" "file2" "file3" "file4") -;; End: -@end lisp -@noindent -where @code{file1} to @code{file4} are names of files related to the master -file. Next time, when the master file is visited, the command -@code{viper-setup-master-buffer} will be evaluated and the above files will -be associated with the master file. Then, the new Ex command -@kbd{:RelatedFile} (abbr.@: @kbd{:R}) will display files 1 to 4 one after -another, so you can edit them. If a file is not in any Emacs buffer, it -will be visited. The command @kbd{PreviousRelatedFile} (abbr., @kbd{:P}) -goes through the file list in the opposite direction. -@findex @kbd{Ex RelatedFile} -@findex @kbd{Ex PreviousRelatedFile} - -These commands are akin to @kbd{:n} and @kbd{:N}, but they allow the user to -focus on relevant files only. - -Note that only the master file needs to have the aforementioned block of -commands. Also, ";;" above can be replaced by some other -markers. Semicolon is good for Lisp programs, since it is considered a -comment designator there. For LaTeX, this could be "%%%", and for C the -above block should be commented out. - -Even though these commands are sometimes useful, they are no substitute for -the powerful @emph{tag table} facility of Emacs. Viper's @kbd{:tag} command -in a primitive interface to Emacs tags. @xref{Tags,Tags,Tags,emacs, -The GNU Emacs Manual}, for more information on tags. - -The following two commands are normally bound to a mouse click and are part -of Viper. They work only if Emacs runs as an application under X -Windows (or under some other window system for which a port of GNU Emacs 20 -is available). Clicking the mouse when Emacs is invoked in an Xterm window -(using @code{emacs -nw}) will do no good. - -@table @code -@cindex mouse -@cindex mouse-search -@item viper-mouse-search-key (meta shift 1) -@vindex @code{viper-mouse-insert-key} -This variable controls the @emph{mouse-search} feature of Viper. The -default value -states that holding Meta and Shift keys while clicking mouse button 1 -should initiate search for a region under the mouse pointer (defined -below). This command can take a prefix argument, which indicates the -occurrence of the pattern to search for. - -Note: while loading initially, Viper binds this mouse action only if it is -not already bound to something else. If you want to use the mouse-search -feature, and the @kbd{Meta-Shift-Mouse-1} mouse action is already bound to -something else, you can rebind the mouse-search feature by setting -@code{viper-mouse-search-key} to something else in -your Viper customization file: -@lisp -(setq viper-mouse-search-key '(meta 1)) -@end lisp -This would bind mouse search to the action invoked by pressing the -Meta key and clicking mouse button 1. The allowed values of -@code{viper-mouse-search-key} are lists that contain a mouse-button number -(1,2, or 3) and any combination of the words `control', `meta', and -`shift'. - -If the requested mouse action (e.g., (meta 1)) is already taken for other -purposes then you have to confirm your intention by placing the following -command in your Viper customization file after setting -@code{viper-mouse-search-key}: -@lisp -(viper-bind-mouse-search-key 'force) -@end lisp - -You can also change this setting interactively, through the customization -widget of Emacs (type @kbd{:customize}). - -The region that is chosen as a pattern to search for is determined as -follows. If search is invoked via a single click, Viper chooses the region -that lies between the beginning of the ``word'' under the pointer (``word'' -is understood in Vi sense) and the end of that word. The only difference -with Vi's words is that in Lisp major modes `-' is considered an -alphanumeric symbol. This is done for the convenience of working with Lisp -symbols, which often have an `-' in them. Also, if you click on a -non-alphanumeric character that is not a word separator (in Vi sense) then -this character will also be considered alphanumeric, provided that it is -adjacent (from either side) to an alphanumeric character. This useful -feature gives added control over the patterns selected by the mouse click. - -On a double-click, the region is determined by the beginning of the current -Vi's ``Word'' (i.e., the largest non-separator chunk of text) and the End -of that ``Word'' (as determined by the @kbd{E} command). - -On a triple-click, the region consists of the entire line where the click -occurred with all leading and trailing spaces and tabs removed. - -@cindex mouse-insert -@item viper-mouse-insert-key (meta shift 2) -@vindex @code{viper-mouse-insert-key} -This variable controls the @emph{mouse-insert} feature of Viper. -The above default value states that -holding Meta and Shift keys while clicking mouse button 2 -should insert the region surrounding the -mouse pointer. The rules defining this region are the same as for -mouse-search. This command takes an optional prefix argument, which -indicates how many such regions to snarf from the buffer and insert. (In -case of a triple-click, the prefix argument is ignored.) - -Note: while loading initially, Viper binds this mouse action only if it not -already bound to something else. If you want to use this feature and the -default mouse action is already bound, you can rebind mouse-insert by -placing this command in your Viper customization file: -@lisp -(setq viper-mouse-insert-key '(meta 2)) -@end lisp -If you want to bind mouse-insert to an action even if this action is -already taken for other purposes in Emacs, then you should add this command -to your Viper customization file, after setting @code{viper-mouse-insert-key}: -@lisp -(viper-bind-mouse-insert-key 'force) -@end lisp - -This value can also be changed via the Emacs customization widget at the -menubar. - -@item viper-multiclick-timeout -This variable controls the rate at which double-clicking must occur for the -purpose of mouse search and mouse insert. By default, this is set to -@code{double-click-time} in Emacs and to -@code{mouse-track-multi-click-time} milliseconds in XEmacs. -@end table -@kindex @kbd{S-Mouse-1} -@kindex @kbd{S-Mouse-2} -@kindex @kbd{meta shift button1up} -@kindex @kbd{meta shift button2up} -@vindex @code{viper-multiclick-timeout} -@findex @code{viper-mouse-click-insert-word} -@findex @code{viper-mouse-click-search-word} - -Note: The above functions search and insert in the selected window of -the latest active frame. This means that you can click in another window or -another frame and have search or insertion done in the frame and window you -just left. This lets one use these functions in a multi-frame -configuration. However, this may require some getting used to. For -instance, if you are typing in a frame, A, and then move the mouse to frame -B and click to invoke mouse search, search (or insertion) will be performed -in frame A@. To perform search/insertion in frame B, you will first have to -shift focus there, which doesn't happen until you type a character or -perform some other action in frame B---mouse search doesn't shift focus. - -If you decide that you don't like the above feature and always want -search/insertion be performed in the frame where the click occurs, don't -bind (and unbind, if necessary) @code{viper-mouse-catch-frame-switch} from -the mouse event it is bound to. - -Mouse search is integrated with Vi-style search, so you can -repeat it with @kbd{n} and @kbd{N}. It should be also noted that, while -case-sensitivity of search in Viper is controlled by the variable -@code{viper-case-fold-search}, the case of mouse search is -controlled by the Emacs variable @code{case-fold-search}, which may be set -differently from @code{viper-case-fold-search}. Therefore, case-sensitivity -of mouse search may be different from that of the usual Vi-style search. - -Finally, if the way Viper determines the word to be searched for or to be -inserted is not what you want, there is a variable, -@code{viper-surrounding-word-function}, which can be changed to indicate -another function for snarfing words out of the buffer. The catch is that -you will then have to write such a function and make it known to your -Emacs. The function @code{viper-surrounding-word} in @file{viper.el} can be -used as a guiding example. - -@node Vi Macros -@section Vi Macros - -@cindex Vi macros - -Viper supports much enhanced Vi-style macros and also facilitates the use -of Emacs-style macros. To define a temporary macro, it is generally more -convenient to use Emacs keyboard macro facility. Emacs keyboard macros are -usually defined anonymously, and the latest macro can be executed by typing -@kbd{C-x e} (or @kbd{*}, if Viper is in Vi state). If you need to use several -temporary macros, Viper lets you save them to a -register (a lowercase letter); such macros can then be executed by typing -@kbd{@@a} in Vi state (if a macro was previously saved in register -@kbd{a}). -@xref{Macros and Registers}, for details. - -If, however, you need to use a macro regularly, it must be given a -permanent name and saved. Emacs manual explains how to do this, but -invocation of named Emacs macros is quite different from Vi's. First, -invocation of permanent Emacs macros takes time because it requires typing -too many keys (to a Vi user's taste, anyway). -Second, binding such macros to function keys, for -fast access, hogs valuable real estate on the keyboard. - -Vi-style macros are better in that respect, since Vi lets the user overload -the meaning of key sequences: keys typed in fast succession are treated -specially, if this key sequence is bound to a macro. - -Viper provides Vi-style keyboard macros through the usual Ex commands, -@kbd{:map} and -@kbd{:map!}. These macros are much more powerful in Viper than -they are in the original Vi and in other emulators. This is because Viper -implements an enhanced vi-style -interface to the powerful Emacs keyboard macro facility. - -First, any Emacs -command can be executed while defining a macro, not just the Vi -commands. In particular, the user can invoke Emacs commands via @kbd{M-x -command-name} or by pressing various function keys on the keyboard. One -can even use the mouse, although this is usually not useful and is not -recommended (and macros defined with the use of the mouse cannot be saved in -command history and in the startup file, for future use). - -Macros defined by mixing Vi and Emacs commands are represented as -vectors. So, don't be confused when you see one (usually through the -history of Ex commands). For instance, if @kbd{gg} is defined by typing -@kbd{l}, the up-arrow key and @kbd{M-x next-line}, its definition will look -as follows in Emacs: - -@example -[l up (meta x) n e x t - l i n e return] -@end example - -Second, Viper macros are defined in a WYSIWYG style. This means that -commands are executed as you type them, so you can see precisely what is -being defined. Third, macros can be bound to arbitrary sequences of keys, -not just to printable keys. For instance, one can define a macro that will -be invoked by hitting @kbd{f3} then @kbd{f2} function keys. (The keys -@kbd{delete} and @kbd{backspace} are excluded; also, a macro invocation -sequence can't start with @key{ESC}. Some other keys, such as @kbd{f1} and -@kbd{help}, can't be bound to macros under Emacs, since they -are bound in @code{key-translation-map}, which overrides any other binding -the user gives to keys. In general, keys that have a binding in -@code{key-translation-map} can't be bound to a macro.) - -Fourth, in Viper, one can define macros that are specific to a given -buffer, a given major mode, or macros that are defined for all buffers. In -fact, the same macro name can have several different definitions: one -global, several definitions for various major modes, and -definitions for various specific buffers. Buffer-specific definitions -override mode-specific definitions, which, in turn, override global -definitions. - -As if all that is not enough, Viper (through its interface to Emacs -macros) lets the user define keyboard macros that ask for confirmation or -even prompt the user for input and then continue. To do this, one should -type @kbd{C-x q} (for confirmation) or @kbd{C-u C-x q} (for prompt). -For details, @pxref{Keyboard Macro Query,,Customization,emacs,The GNU Emacs -Manual}. - -When the user finishes defining a macro (which is done by typing @kbd{C-x)}, -a departure from Vi), you will be asked whether you want this -macro to be global, mode-specific, or buffer-specific. You will also be -given a chance to save the macro in your Viper customization file. -This is the easiest way to save a macro and make -it permanently available. If you work your startup files with bare hands, -here is how Viper saves the above macro so that it will be -available in Viper's Insert state (and Replace state) in buffer @code{my-buf} -only: - -@example -(viper-record-kbd-macro "gg" 'insert-state - [l up (meta x) n e x t - l i n e return] - "my-buf") -@end example - -@noindent -To do the same for Vi state and all buffers with the major mode -@code{cc-mode}, use: - -@example -(viper-record-kbd-macro "gg" 'vi-state - [l up (meta x) n e x t - l i n e return] - 'cc-mode) -@end example - -@noindent -Both macro names and macro definitions are vectors of symbols that denote -keys on the keyboard. Some keys, like @kbd{\}, @kbd{ }, or digit-keys must -be escaped with a backslash. Modified keys are represented as lists. For -instance, holding Meta and Control and pressing @kbd{f4} is represented as -@kbd{(control meta f4)}. -If all members of a vectors are printable characters (or sequences, such as -@kbd{\e}, @kbd{\t}, for @key{ESC} and @key{TAB}), then they can also be represented as -strings: - -@example -(viper-record-kbd-macro "aa" 'vi-state "aaa\e" "my-buffer") -@end example - -@noindent -Thus, typing @kbd{aa} fast in Vi state will switch Viper to Insert state -(due to the first @kbd{a}), insert @kbd{aa}, and then it will switch back to Vi -state. All this will take effect only in the buffer named @code{my-buffer}. - -Note that the last argument to @code{viper-record-kbd-macro} must be either a -string (a buffer name), a symbol representing a major mode, or @code{t}; -the latter says that the macro is to be defined for all buffers -(which is how macros are defined in original Vi). - -For convenience, Viper also lets you define Vi-style macros in its Emacs -state. There is no Ex command, like @kbd{:map} and @kbd{:map!} for doing -this, but the user can include such a macro in the Viper customization file. -The only thing is that the @code{viper-record-kbd-macro} command should specify -@code{emacs-state} instead of @code{vi-state} or @code{insert-state}. - -The user can get rid of a macro either by using the Ex commands @kbd{:unmap} -and @kbd{:unmap!} or by issuing a call to @code{viper-unrecord-kbd-macro}. -The latter is more powerful, since it can delete macros even in -@code{emacs-state}. However, @code{viper-unrecord-kbd-macro} is usually -needed only when the user needs to get rid of the macros that are already -predefined in Viper. -The syntax is: -@findex @code{viper-unrecord-kbd-macro} -@example -(viper-unrecord-kbd-macro macro state) -@end example -@noindent -The second argument must be @code{vi-state}, @code{insert-state}, or -@code{emacs-state}. The first argument is a name of a macro. To avoid -mistakes in specifying names of existing macros, type @kbd{M-x -viper-describe-kbd-macros} and use a name from the list displayed by this -command. - -If an error occurs during macro definition, Emacs -aborts the process, and it must be repeated. This is analogous to Vi, -except that in Vi the user doesn't know there is an error until the macro is -actually run. All that means that in order for a definition to be -successful, the user must do some simple planning of the process in -advance, to avoid errors. For instance, if you want to map @kbd{gg} to -@kbd{llll} in Vi state, you must make sure that there is enough room on the -current line. Since @kbd{l} moves the cursor forward, it may signal an -error on reaching the end of line, which will abort the definition. - -These precautions are necessary only when defining macros; they will help -avoid the need to redo the job. When macros are actually run, an error -during the execution will simply terminate the current execution -(but the macro will remain mapped). - -A macro name can be a string of characters or a vector of keys. -The latter makes it possible to define macros bound to, say, double-hits -on a function key, such as @kbd{up} or @kbd{f13}. -This is very useful if you run out of function keys on your keyboard; it -makes Viper macro facility a @emph{keyboard doubler}, so to speak. - -Elsewhere (@xref{Key Bindings}, for details), we review -the standard Emacs mechanism for binding function keys to commands. -For instance, - -@example -(global-set-key [f13] 'repeat-complex-command) -@end example - -@noindent -binds the key f13 to the Emacs function that repeats the last minibuffer -command. Under Viper, however, you may still use this key for additional -purposes, if you bind, say, a double-hitting action for that key to some -other function. Emacs doesn't allow the user to do that, but Viper does -this through its keyboard macro facility. To do this, type @kbd{:map } -first. When you are asked to enter a macro name, hit f13 twice, followed by -@key{RET} or @key{SPC}. - -Emacs will now start the mapping process by actually executing -Vi and Emacs commands, so that you could see what will happen each time the -macro is executed. Suppose now we wanted to bind the key sequence -@kbd{f13 f13} to the command @code{eval-last-sexp}. To accomplish this, we -can type @kbd{M-x eval-last-sexp} followed by @kbd{C-x )}. -If you answer positively to Viper's offer to save this macro in your -Viper customization file for future uses, the following will be inserted -in that file: - -@example -(viper-record-kbd-macro [f16 f16] 'vi-state - [(meta x) e v a l - l a s t - s e x p] - 'lisp-interaction-mode) -@end example - -To illustrate the above point, Viper provides two canned macros, which, by -default, are bound to @kbd{[f12 \1]} and @kbd{[f12 \2]} (invoked by typing -@kbd{f12} then @kbd{1} and @kbd{2}, respectively). These macros are useful -shortcuts to Viper's command ring history. The first macro will execute the -second-last destructive command (the last one is executed by @kbd{.}, as -usual). The second macro executes the third-last command. - -If you need to go deeper into the command history, you will have to use -other commands, as described earlier in this section; or you can bind, -say, @kbd{f12 \3} like this: - -@example -(viper-record-kbd-macro [f12 \3] 'vi-state - [(meta x) r e p e a t - f r o m - h i s t o r y] - t) -@end example - - -Note that even though the macro uses the function key @kbd{f12}, the key is -actually free and can still be bound to some Emacs function via -@code{define-key} or @code{global-set-key}. - - -Viper allows the user to define macro names that are prefixes of other macros. -For instance, one can define @kbd{[[} and @kbd{[[[[} to be macros. -If you type the exact sequence of such keys and then pause, Viper will -execute the right macro. However, if you don't pause and, say, type -@kbd{[[[[text} then the conflict is resolved as follows. If only one of the -key sequences, @kbd{[[} or @kbd{[[[[} has a definition applicable to the -current buffer, then, in fact, there is no conflict and the right macro -will be chosen. If both have applicable definitions, then the first one -found will be executed. Usually this is the macro with a shorter name. So, -in our case, @kbd{[[[[text} will cause the macro @kbd{[[} to be executed -twice and then the remaining keys, @kbd{t e x t}, will be processed. - -When defining macros using @kbd{:map} or @kbd{:map!}, the user enters -the actually keys to be used to invoke the macro. For instance, you -should hit the actual key @kbd{f6} if it is to be part of a macro -name; you do @emph{not} write @kbd{f 6}. When entering keys, Viper -displays them as strings or vectors (e.g., @code{"abc"} or @code{[f6 -f7 a]}). The same holds for unmapping. Hitting @key{TAB} while -typing a macro name in the @kbd{:unmap} or @kbd{:unmap!} command will -cause name completion. Completions are displayed as strings or -vectors. However, as before, you don't actually type @samp{"}, -@samp{[}, or @samp{]} that appear in the completions. These are -meta-symbols that indicate whether the corresponding macro name is a -vector or a string. - -One last difference from Vi: Vi-style keyboard macros cannot be defined in -terms of other Vi-style keyboard macros (but named Emacs macros are OK). -More precisely, while defining or executing a macro, the special meaning -of key sequences (as Vi macros) is ignored. -This is because it is all too easy to create an infinite loop in this way. -Since Viper macros are much more powerful than Vi's it is impossible to -detect such loops. In practice, this is not really a limitation but, -rather, a feature. - -We should also note that Vi macros are disabled in the minibuffer, which -helps keep some potential troubles away. - -The rate at which the user must type keys in order for them to be -recognized as a timeout macro is controlled by the variable -@code{viper-fast-keyseq-timeout}, which defaults to 200 milliseconds. - -For the most part, Viper macros defined in the Viper customization file can -be shared between X and TTY modes. -The problem with TTY may be that the function keys there generate sequences -of events instead of a single event (as under a window system). -Emacs maps some of these sequences back to the logical keys -(e.g., the sequences generated by the arrow keys are mapped to @kbd{up}, -@kbd{left}, etc.). However, not all function keys are mapped in this way. -Macros that are bound to key sequences that contain such unmapped function -keys have to be redefined for TTY's (and possibly for every type of TTY you -may be using). To do this, start Emacs on an appropriate TTY device and -define the macro using @kbd{:map}, as usual. - -@findex @code{viper-describe-kbd-macros} -Finally, Viper provides a function that conveniently displays all macros -currently defined. To see all macros along with their definitions, type -@kbd{M-x viper-describe-kbd-macros}. - -@node Commands -@chapter Commands - -This section is a semi-automatically bowdlerized version of the Vi -reference created by @* @samp{maart@@cs.vu.nl} and others. It can be -found on the Vi archives. This reference has been adapted for Viper. - -@menu -* Groundwork:: Textual Conventions and Viper basics -* Text Handling:: Moving, Editing, Undoing. -* Display:: Scrolling. -* File and Buffer Handling:: Editing, Writing and Quitting. -* Mapping:: Mapping Keys, Keyboard Macros -* Shell Commands:: Accessing Shell Commands, Processing Text -* Options:: Ex options, the @kbd{:set} commands -* Emacs Related Commands:: Meta Keys, Windows -* Mouse-bound Commands:: Search and insertion of text -@end menu - -@node Groundwork -@section Groundwork - -The VI command set is based on the idea of combining motion commands -with other commands. The motion command is used as a text region -specifier for other commands. -We classify motion commands into @dfn{point commands} and -@dfn{line commands}. - -@cindex point commands - -The point commands are: - -@quotation -@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, -@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, -@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} -@end quotation - -@cindex line commands - -The line commands are: - -@quotation -@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, -@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} -@end quotation -@noindent - -Text Deletion Commands (@pxref{Deleting Text}), Change commands -(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) -use these commands to describe a region of text to operate on. - -@cindex r and R region specifiers - -Viper adds two region descriptors, @kbd{r} and @kbd{R}. These describe -the Emacs regions (@pxref{Basics}), but they are not movement commands. - -The command description uses angle brackets @samp{<>} to indicate -metasyntactic variables, since the normal conventions of using simple -text can be confusing with Viper where the commands themselves are -characters. Watch out where @kbd{<} shift commands and @kbd{} are -mentioned together!!! - -@kindex -@kindex -@kindex
-@cindex -@cindex -@cindex
-@cindex movements - -@samp{} refers to the above movement commands, and @samp{} -refers to registers or textmarkers from @samp{a} to @samp{z}. Note -that the @samp{} is described by full move commands, that is to -say they will take counts, and otherwise behave like normal move commands. -@cindex Ex addresses -@samp{
} refers to Ex line addresses, which include - -@table @kbd -@item .@: -Current line -@item .+n .-n -Add or subtract for current line -@item number -Actual line number, use @kbd{.=} to get the line number -@item ' -Textmarker -@item $ -Last line -@item x,y -Where x and y are one of the above -@item % -@cindex % (Ex address) -For the whole file, same as (1,$). -@item // -@itemx ?? -Next or previous line with pattern . - -Note that the pattern is allowed to contain newline character (inserted as -@kbd{C-qC-j}). Therefore, one can search for patterns that span several -lines. -@end table - -@cindex % (Current file) -Note that @samp{%} is used in Ex commands @kbd{:e} and @kbd{:r } -to mean current file. If you want a @samp{%} in your command, it must be -escaped as @samp{\%}. Note that @kbd{:w} and the regular @kbd{:r } -command doesn't support the meta symbols @samp{%} and @samp{#}, because -file history is a better mechanism. -@cindex # (Previous file) -Similarly, @samp{#} expands to the previous file. The previous file is -the first file in @kbd{:args} listing. This defaults to previous window -in the VI sense if you have one window only. - -@kindex -@kindex -@cindex -@cindex -@noindent -Others like @samp{ -- arguments}, @samp{ -- command} etc. -should be fairly obvious. - -@noindent -Common characters referred to include: - -@table @kbd -@item -Space -@item -Tab -@item -Linefeed -@item -Escape -@item -Return, Enter -@end table -@cindex -@cindex -@cindex -@cindex -@cindex - -@cindex words -@cindex WORDS -@cindex char -@cindex CHAR - -We also use @samp{word} for alphanumeric/non-alphanumeric words, and -@samp{WORD} for whitespace delimited words. @samp{char} refers to any -@acronym{ASCII} character, @samp{CHAR} to non-whitespace character. -Brackets @samp{[]} indicate optional parameters; @samp{} also -optional, usually defaulting to 1. Brackets are elided for -@samp{} to eschew obfuscation. - -Viper's idea of Vi's words is slightly different from Vi. First, Viper -words understand Emacs symbol tables. Therefore, all symbols declared to be -alphanumeric in a symbol table can automatically be made part of the Viper -word. This is useful when, for instance, editing text containing European, -Cyrillic, Japanese, etc., texts. - -Second, Viper lets you depart from Vi's idea of a word by changing the a -syntax preference via the customization widget (the variable -@code{viper-syntax-preference}) or by executing -@code{viper-set-syntax-preference} interactively. - -By default, Viper syntax preference is @code{reformed-vi}, which means that -Viper considers only those symbols to be part of a word that are specified -as word-symbols by the current Emacs syntax table (which may be different -for different major modes) plus the underscore symbol @kbd{_}, minus the -symbols that are not considered words in Vi (e.g., `,',;, etc.), but may be -considered as word-symbols by various Emacs major modes. Reformed-Vi works -very close to Vi, and it also recognizes words in other -alphabets. Therefore, this is the most appropriate mode for editing text -and is likely to fit all your needs. - -You can also set Viper syntax preference to @code{strict-vi}, which would -cause Viper to view all non-English letters as non-word-symbols. - -You can also specify @code{emacs} as your preference, which would -make Viper use exactly the same notion of a word as Emacs does. In -particular, the underscore may not be part of a word in some major modes. - -Finally, if @code{viper-syntax-preference} is set to @code{extended}, Viper -words would consist of characters that are classified as alphanumeric -@emph{or} as parts of symbols. This is convenient for editing programs. - -@code{viper-syntax-preference} is a local variable, so it can have different -values for different major modes. For instance, in programming modes it can -have the value @code{extended}. In text modes where words contain special -characters, such as European (non-English) letters, Cyrillic letters, etc., -the value can be @code{reformed-vi} or @code{emacs}. -If you consider using different syntactic preferences for different major -modes, you should execute, for example, - -@example -(viper-set-syntax-preference nil "extended") -@end example - -in the appropriate major mode hooks. - -@vindex @code{viper-syntax-preference} -@findex @code{viper-set-syntax-preference} -@cindex syntax table - - - -The above discussion concerns only the movement commands. In regular -expressions, words remain the same as in Emacs. That is, the expressions -@code{\w}, @code{\>}, @code{\<}, etc., use Emacs's idea of what is a word, -and they don't look into the value of variable -@code{viper-syntax-preference}. This is because Viper avoids changing -syntax tables in order to not thwart the various major modes that set these -tables. - -The usual Emacs convention is used to indicate Control Characters, i.e., -C-h for Control-h. @emph{Do not confuse this with a sequence of separate -characters -C, -, h!!!} The @kbd{^} is itself, never used to indicate a -Control character. - -Finally, we note that Viper's Ex-style commands can be made to work on the -current Emacs region. This is done by typing a digit argument before -@kbd{:}. For instance, typing @kbd{1:} will prompt you with something like -@emph{:123,135}, assuming that the current region starts at line 123 and -ends at line 135. There is no need to type the line numbers, since Viper -inserts them automatically in front of the Ex command. -@cindex Ex commands - -@node Text Handling -@section Text Handling - -@menu -* Move Commands:: Moving, Searching -* Marking:: Textmarkers in Viper and the Emacs Mark. -* Appending Text:: Text insertion, Shifting, Putting -* Editing in Insert State:: Autoindent, Quoting etc. -* Deleting Text:: Deleting -* Changing Text:: Changing, Replacement, Joining -* Search and Replace:: Searches, Query Replace, Pattern Commands -* Yanking:: Yanking, Viewing Registers -* Undoing:: Multiple Undo, Backups -@end menu - -@node Move Commands -@subsection Move Commands - -@cindex movement commands -@cindex searching -@cindex textmarkers -@cindex markers -@cindex column movement -@cindex paragraphs -@cindex headings -@cindex sections -@cindex sentences -@cindex matching parens -@cindex paren matching - -@table @kbd -@item h C-h - chars to the left. -@item j C-n - lines downward. -@item l - chars to the right. -@item k C-p - lines upward. -@item $ -To the end of line from the cursor. -@item ^ -To the first CHAR @minus{} 1 lines lower. -@item - -To the first CHAR lines higher. -@item + -To the first CHAR lines lower. -@item 0 -To the first char of the line. -@item | -To column -@item f - s to the right (find). -@item t -Till before s to the right. -@item F - s to the left. -@item T -Till after s to the left. -@item ; -Repeat latest @kbd{f t F T} times. -@item , -Repeat latest @kbd{f t F T} - times in opposite direction. -@item w - words forward. -@item W - WORDS forward. -@item b - words backward. -@item B - WORDS backward. -@item e -To the end of word forward. -@item E -To the end of WORD forward. -@item G -Go to line (default end-of-file). -@item H -To line from top of the screen (home). -@item L -To line from bottom of the screen (last). -@item M -To the middle line of the screen. -@item ) - sentences forward. -@item ( - sentences backward. -@item @} - paragraphs forward. -@item @{ - paragraphs backward. -@item ]] -To the th heading. -@item [[ -To the th previous heading. -@item [] -To the end of th heading. -@item m -Mark the cursor position with a letter. -@item ` -To the mark. -@item ' -To the first CHAR of the line with the mark. -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@item `` -To the cursor position before the latest absolute -jump (of which are examples @kbd{/} and @kbd{G}). -@item '' -To the first CHAR of the line on which the cursor -was placed before the latest absolute jump. -@item / -To the th occurrence of . -@item / -To the th occurrence of from previous @kbd{/ or ?}. -@item ? -To the th previous occurrence of . -@item ? -To the th previous occurrence of from previous @kbd{?@: or /}. -@item n -Repeat latest @kbd{/} @kbd{?} (next). -@item N -Repeat latest search in opposite direction. -@item C-c / -Without a prefix argument, this command toggles -case-sensitive/case-insensitive search modes and plain vanilla/regular -expression search. With the prefix argument 1, i.e., -@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, -toggles plain vanilla search and search using -regular expressions. @xref{Viper Specials}, for alternative ways to invoke -this function. -@cindex vanilla search -@cindex case-sensitive search -@cindex case-insensitive search -@item % -Find the next bracket/parenthesis/brace and go to its match. -By default, Viper ignores brackets/parentheses/braces that occur inside -parentheses. You can change this by setting -@code{viper-parse-sexp-ignore-comments} to @code{nil} in your Viper -customization file. -This option can also be toggled interactively if you quickly hit @kbd{%%%}. - -This latter feature is implemented as a vi-style keyboard macro. If you -don't want this macro, put - -@example -(viper-set-parsing-style-toggling-macro 'undefine) -@end example -@findex @code{viper-set-parsing-style-toggling-macro} - -in your Viper customization file. - -@end table -@kindex @kbd{%} -@kindex @kbd{C-c /} -@kindex @kbd{N} -@kindex @kbd{n} -@kindex @kbd{?} -@kindex @kbd{/} -@kindex @kbd{?} -@kindex @kbd{/} -@kindex @kbd{''} -@kindex @kbd{``} -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{'} -@kindex @kbd{`} -@kindex @kbd{m} -@kindex @kbd{[]} -@kindex @kbd{[[} -@kindex @kbd{]]} -@kindex @kbd{@{} -@kindex @kbd{@}} -@kindex @kbd{(} -@kindex @kbd{)} -@kindex @kbd{M} -@kindex @kbd{L} -@kindex @kbd{H} -@kindex @kbd{G} -@kindex @kbd{E} -@kindex @kbd{e} -@kindex @kbd{B} -@kindex @kbd{b} -@kindex @kbd{W} -@kindex @kbd{w} -@kindex @kbd{,} -@kindex @kbd{;} -@kindex @kbd{T} -@kindex @kbd{F} -@kindex @kbd{t} -@kindex @kbd{f} -@kindex @kbd{|} -@kindex @kbd{0} -@kindex @kbd{} -@kindex @kbd{+} -@kindex @kbd{-} -@kindex @kbd{^} -@kindex @kbd{$} -@kindex @kbd{C-p} -@kindex @kbd{} -@kindex @kbd{} -@kindex @kbd{C-n} -@kindex @kbd{C-h} -@kindex @kbd{h} -@kindex @kbd{j} -@kindex @kbd{k} -@kindex @kbd{l} -@vindex @code{viper-parse-sexp-ignore-comments} - -@node Marking -@subsection Marking - -Emacs mark is referred to in the region specifiers @kbd{r} and @kbd{R}. -@xref{Emacs Preliminaries}, and @xref{Basics}, for explanation. Also -see @ref{Mark,,Mark,emacs,The GNU Emacs manual}, for an explanation of -the Emacs mark ring. - -@cindex marking - -@table @kbd -@item m -Mark the current file and position with the specified letter. -@item m . -Set the Emacs mark (@pxref{Emacs Preliminaries}) at point. -@item m ^ -Set the Emacs mark (@pxref{Emacs Preliminaries}) back to where it was last -set with the @kbd{m.} command. This is useful when you set the mark with -@kbd{m.}, but then some other command (such as @kbd{L} or @kbd{G}) changes -it in a way that you didn't like. -@item m < -Set the Emacs mark at beginning of buffer. -@item m > -Set the Emacs mark at end of buffer. -@item m , -Jump to the Emacs mark. -@item :mark -Mark position with text marker named . This is an Ex command. -@item :k -Same as @kbd{:mark}. -@item `` -Exchange point and mark. -@item '' -Exchange point and mark and go to the first CHAR on line. -@item ' -Go to specified Viper mark. -@item ` -Go to specified Viper mark and go to the first CHAR on line. -@end table -@kindex @kbd{m} -@kindex @kbd{m.} -@kindex @kbd{m>} -@kindex @kbd{m<} -@kindex @kbd{m,} -@kindex @kbd{m^} -@findex @kbd{Ex mark} -@findex @kbd{Ex k} -@kindex @kbd{''} -@kindex @kbd{``} -@kindex @kbd{`} -@kindex @kbd{'} - -@node Appending Text -@subsection Appending Text - -@xref{Options}, to see how to change tab and shiftwidth size. See the GNU -Emacs manual, or try @kbd{C-ha tabs} (If you have turned Emacs help on). -Check out the variable @code{indent-tabs-mode} to put in just spaces. -Also see options for word-wrap. - -@cindex inserting -@cindex appending -@cindex paste -@cindex put - -@table @kbd -@item a - times after the cursor. -@item A - times at the end of line. -@item i - times before the cursor (insert). -@item I - times before the first CHAR of the line -@item o -On a new line below the current (open). -The count is only useful on a slow terminal. -@item O -On a new line above the current. -The count is only useful on a slow terminal. -@item > -Shift the lines described by one -shiftwidth to the right (layout!). -@item >> -Shift lines one shiftwidth to the right. -@item ["]p -Put the contents of the (default undo) buffer - times after the cursor. The register will -be automatically down-cased. -@item ["]P -Put the contents of the (default undo) buffer - times before the cursor. The register will -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@item . -Repeat previous command times. For destructive -commands as well as undo. -@item f1 1 and f1 2 -While @kbd{.} repeats the last destructive command, -these two macros repeat the second-last and the third-last destructive -commands. @xref{Vi Macros}, for more information on Vi macros. -@item C-c M-p and C-c M-n -In Vi state, -these commands help peruse the history of Vi's destructive commands. -Successive typing of @kbd{C-c M-p} causes Viper to search the history in -the direction -of older commands, while hitting @kbd{C-c M-n} does so in reverse -order. Each command in the history is displayed in the minibuffer. The -displayed command can -then be executed by typing `@kbd{.}'. - -Since typing the above sequences of keys may be tedious, the -functions doing the perusing can be bound to unused keyboard keys in the -Viper customization file. @xref{Viper Specials}, for details. -@end table -@kindex @kbd{C-c M-p} -@kindex @kbd{C-c M-n} -@kindex @kbd{.} -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{P} -@kindex @kbd{p} -@kindex @kbd{"p} -@kindex @kbd{"P} -@kindex @kbd{>>} -@kindex @kbd{>} -@kindex @kbd{O} -@kindex @kbd{o} -@kindex @kbd{i} -@kindex @kbd{A} -@kindex @kbd{a} - -@node Editing in Insert State -@subsection Editing in Insert State - -Minibuffer can be edited similarly to Insert state, and you can switch -between Insert/Replace/Vi states at will. -Some users prefer plain Emacs feel in the minibuffer. To this end, set -@var{viper-vi-style-in-minibuffer} to @code{nil}. - -@cindex Insert state - -@table @kbd -@item C-v -Deprive the next char of its special meaning (quoting). -@item C-h -One char back. -@item C-w -One word back. -@item C-u -Back to the begin of the change on the -current line. - -@end table -@kindex @kbd{C-u} -@kindex @kbd{C-w} -@kindex @kbd{C-v} - -@node Deleting Text -@subsection Deleting Text - - -There is one difference in text deletion that you should be -aware of. This difference comes from Emacs and was adopted in Viper -because we find it very useful. In Vi, if you delete a line, say, and then -another line, these two deletions are separated and are put back -separately if you use the @samp{p} command. In Emacs (and Viper), successive -series of deletions that are @emph{not interrupted} by other commands are -lumped together, so the deleted text gets accumulated and can be put back -as one chunk. If you want to break a sequence of deletions so that the -newly deleted text could be put back separately from the previously deleted -text, you should perform a non-deleting action, e.g., move the cursor one -character in any direction. - -@cindex shifting text - -@table @kbd -@item x -Delete chars under and after the cursor. -@item X -Delete chars before the cursor. -@item d -Delete from point to endpoint of . -@item dd -Delete lines. -@item D -The rest of the line. -@item < -Shift the lines described by one -shiftwidth to the left (layout!). -@item << -Shift lines one shiftwidth to the left. -@end table -@kindex @kbd{<<} -@kindex @kbd{<} -@kindex @kbd{D} -@kindex @kbd{dd} -@kindex @kbd{d} -@kindex @kbd{X} -@kindex @kbd{x} - -@node Changing Text -@subsection Changing Text - -@cindex joining lines -@cindex changing case -@cindex quoting regions -@cindex substitution - -@table @kbd -@item r -Replace chars by ; no . -@item R -Overwrite the rest of the line, -appending change @var{count} @minus{} 1 times. -@item s -Substitute chars. -@item S -Change lines. -@item c -Change from begin to endpoint of . -@item cc -Change lines. -@item C -The rest of the line and @minus{} 1 next lines. -@item = -Reindent the region described by move. -@item ~ -Switch lower and upper cases. -@item J -Join lines (default 2). -@item :[x,y]s/// -Substitute (on lines x through y) the pattern - (default the last pattern) with . Useful -flags are @samp{g} for @samp{global} (i.e., change every -non-overlapping occurrence of ) and @samp{c} for -@samp{confirm} (type @samp{y} to confirm a particular -substitution, else @samp{n} ). Instead of @kbd{/} any -punctuation CHAR unequal to and can be used as -delimiter. - -In Emacs, @samp{\&} stands for the last matched expression, so -@kbd{s/[ab]+/\&\&/} will double the string matched by @kbd{[ab]}. -Viper doesn't treat @samp{&} specially, unlike Vi: use @samp{\&} instead. - -Viper does not parse search patterns and does not expand special symbols -found there (e.g., @samp{~} is not expanded to the result of the previous -substitution). - -Note: @emph{The newline character (inserted as @kbd{C-qC-j}) -can be used in }. -@item :[x,y]copy [z] -Copy text between @kbd{x} and @kbd{y} to the position after @kbd{z}. -@item :[x,y]t [z] -Same as @kbd{:copy}. -@item :[x,y]move [z] -Move text between @kbd{x} and @kbd{y} to the position after @kbd{z}. -@item & -Repeat latest Ex substitute command, e.g., -@kbd{:s/wrong/right}. -@item :x,yp -@itemx :g/Pat/p -@itemx :v/Pat/p -The above commands display certain buffer lines in a -temporary buffer. The first form above displays the buffer lines between -@kbd{x} and @kbd{y}. The second displays the lines of the buffer, which -match a given pattern. The third form displays the lines that do @emph{not} -match the given pattern. -@item #c -Change upper-case characters in the region to lower-case. -@item #C -Change lower-case characters in the region to upper-case. -@item #q -Insert specified string at the beginning of each line in the region -@item C-c M-p and C-c M-n -In Insert and Replace states, these keys are bound to commands that peruse -the history of the text -previously inserted in other insert or replace commands. By repeatedly typing -@kbd{C-c M-p} or @kbd{C-c M-n}, you will cause Viper to -insert these previously used strings one by one. -When a new string is inserted, the previous one is deleted. - -In Vi state, these keys are bound to functions that peruse the history of -destructive Vi commands. -@xref{Viper Specials}, for details. -@end table -@kindex @kbd{C-c M-p} -@kindex @kbd{C-c M-n} -@kindex @kbd{#q } -@kindex @kbd{#C} -@kindex @kbd{#c} -@kindex @kbd{&} -@kindex @kbd{\&} -@findex @kbd{Ex substitute///} -@findex @kbd{Ex s///} -@findex @kbd{Ex copy [z]} -@findex @kbd{Ex t [z]} -@findex @kbd{Ex move [z]} -@kindex @kbd{J} -@kindex @kbd{~} -@kindex @kbd{=} -@kindex @kbd{C} -@kindex @kbd{cc} -@kindex @kbd{c} -@kindex @kbd{S} -@kindex @kbd{s} -@kindex @kbd{R} -@kindex @kbd{r} - -@node Search and Replace -@subsection Search and Replace - -@xref{Groundwork}, for Ex address syntax. @xref{Options}, to see how to -get literal (non-regular-expression) search and how to stop search from -wrapping around. - -@table @kbd -@item C-c / -Toggle case-sensitive search. With prefix argument, toggle vanilla/regular -expression search. -@item / -To the th occurrence of . - -Viper does not parse search patterns and does not expand special symbols -found there (e.g., @samp{~} is not expanded to the result of the previous -substitution). - -After typing @kbd{/} or @kbd{?} all the usual Emacs minibuffer commands, such as -@kbd{M-p} and @kbd{M-n} are available. In addition, typing @kbd{C-s} will -insert the last search string used by the Emacs incremental search command -(which is bound to @kbd{C-s} everywhere except in this case). - -@item ? -To the th previous occurrence of . -@item g -Search for the text described by move. (off by default) -@item n -Repeat latest @kbd{/} @kbd{?} (next). -@item N -Idem in opposite direction. -@item % -Find the next bracket and go to its match -@item :[x,y]g// -@cindex text processing -Search globally [from line x to y] for -and execute the Ex on each occurrence. -@item :[x,y]v// -Execute on the lines that don't match. -@item #g -Execute the last keyboard macro for each line in the region. -@xref{Macros and Registers}, for more info. -@item Q -Query Replace. -@item :ta -Search in the tags file where is defined (file, line), and go to it. -@item :[x,y]s/// -Substitute (on lines x through y) the pattern (default the last -pattern) with . Useful -flags are @samp{g} for @samp{global} (i.e., change every -non-overlapping occurrence of ) and @samp{c} for -@samp{confirm} (type @samp{y} to confirm a particular -substitution, else @samp{n}). Instead of @kbd{/} any -punctuation character other than and can be used as -delimiter. - -Note: @emph{The newline character (inserted as @kbd{C-qC-j}) -can be used in }. -@item & -Repeat latest Ex substitute command, e.g., @kbd{:s/wrong/right}. -@item :global // -@itemx :g // -Execute on all lines that match . -@item :vglobal // -@itemx :v // -Execute on all lines that do not match . -@end table -@kindex @kbd{&} -@findex @kbd{Ex substitute///} -@kindex @kbd{Q} -@kindex @kbd{#g} -@findex @kbd{Ex v} -@findex @kbd{Ex g} -@findex @kbd{Ex global} -@findex @kbd{Ex vglobal} -@findex @kbd{Ex tag } -@kindex @kbd{%} -@kindex @kbd{N} -@kindex @kbd{n} -@kindex @kbd{g} -@kindex @kbd{?} -@kindex @kbd{/} - -@node Yanking -@subsection Yanking - -@cindex cut and paste -@cindex paste - -@table @kbd -@item y -Yank from begin to endpoint of . -@item "y -Yank from begin to endpoint of to register. -@item "y -Yank from begin to endpoint of and append -to register. -@item yy - lines. -@item Y -Idem (should be equivalent to @kbd{y$} though). -@item m -Mark the cursor position with a letter. -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@item ["]p -Put the contents of the (default undo) buffer - times after the cursor. The register will -be automatically down-cased. -@item ["]P -Put the contents of the (default undo) buffer - times before the cursor. The register will -@end table -@kindex @kbd{P} -@kindex @kbd{p} -@kindex @kbd{"p} -@kindex @kbd{"P} -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{m} -@kindex @kbd{Y} -@kindex @kbd{yy} -@kindex @kbd{"y} -@kindex @kbd{"y} -@kindex @kbd{y} -@kindex @kbd{yank} -@findex @kbd{Ex yank} - -@node Undoing -@subsection Undoing - -@cindex undo -@cindex backup files - -@table @kbd -@item u U -Undo the latest change. -@item . -Repeat undo. -@item :q! -Quit Vi without writing. -@item :e! -Re-edit a messed-up file. -@item :rec -Recover file from autosave. Viper also creates backup files -that have a @samp{~} appended to them. -@end table -@findex @kbd{Ex rec} -@findex @kbd{Ex e!} -@findex @kbd{Ex q!} -@kindex @kbd{.} -@kindex @kbd{U} -@kindex @kbd{u} - -@node Display -@section Display - -@cindex scrolling - -@table @kbd -@item C-g -At user level 1, -give file name, status, current line number -and relative position.@* -At user levels 2 and higher, abort the current command. -@item C-c g -Give file name, status, current line number and relative position---all -user levels. -@item C-l -Refresh the screen. -@item C-e -Expose more lines at bottom, cursor stays put (if possible). -@item C-y -Expose more lines at top, cursor stays put (if possible). -@item C-d -Scroll lines downward (default the number of the previous scroll; -initialization: half a page). -@item C-u -Scroll lines upward (default the number of the previous scroll; -initialization: half a page). -@item C-f - pages forward. -@item C-b - pages backward (in older versions @kbd{C-b} only works without count). -@item z -@item zH -Put line at the top of the window (default the current line). -@item z- -@item zL -Put line at the bottom of the window -(default the current line). -@item z. -@item zM -Put line in the center of the window -(default the current line). -@end table -@kindex @kbd{zM} -@kindex @kbd{zL} -@kindex @kbd{zH} -@kindex @kbd{z} -@kindex @kbd{z.} -@kindex @kbd{z-} -@kindex @kbd{z} -@kindex @kbd{C-b} -@kindex @kbd{C-f} -@kindex @kbd{C-u} -@kindex @kbd{C-d} -@kindex @kbd{C-y} -@kindex @kbd{C-e} -@kindex @kbd{C-l} -@kindex @kbd{C-g} - - -@node File and Buffer Handling -@section File and Buffer Handling - -@cindex multiple files - -In all file handling commands, space should be typed before entering the file -name. If you need to type a modifier, such as @kbd{>>} or @kbd{!}, don't -put any space between the command and the modifier. - -Note that many Ex commands, e.g., @kbd{:w}, accept command arguments. The -effect is that the command would start acting on the current region. For -instance, if the current region spans the lines 11 through 22, then if you -type @kbd{1:w} you would see @samp{:11,22w} in the minibuffer. - -@table @kbd -@item :q -Quit buffer except if modified. -@item :q! -Quit buffer without checking. In Viper, these two commands -are identical. Confirmation is required if exiting modified buffers that -visit files. -@item :suspend -@item :stop -Suspend Viper -@item :[x,y] w -Write the file. Viper makes sure that a final newline is always added to -any file where this newline is missing. This is done by setting Emacs -variable @code{require-final-newline} to @code{t}. If you don't like this -feature, use @code{setq-default} to set @code{require-final-newline} to -@code{nil}. This must be done in the Viper customization file. -@item :[x,y] w -Write to the file . -@item :[x,y] w>> -Append the buffer to the file . There should be no space between -@kbd{w} and @kbd{>>}. Type space after the @kbd{>>} and see what happens. -@item :w!@: -Overwrite the file . In Viper, @kbd{:w} and @kbd{:w!} are identical. -Confirmation is required for writing to an existing file (if this is not -the file the buffer is visiting) or to a read-only file. -@item :x,y w -Write lines x through y to the file . -@item :wq -Write the file and kill buffer. -@item :r [ ...] -Read file into a buffer, inserting its contents after the current line. -@item :xit -Same as @kbd{:wq}. -@item :Write -@itemx :W -Save all unsaved buffers, asking for confirmation. -@item :WWrite -@itemx :WW -Like @kbd{W}, but without asking for confirmation. -@item ZZ -Save current buffer and kill it. If user level is 1, then save all files -and kill Emacs. Killing Emacs is the wrong way to use it, so you should -switch to higher user levels as soon as possible. -@item :x [] -Save and kill buffer. -@item :x!@: [] -@kbd{:w![]} and @kbd{:q}. -@item :pre -Preserve the file---autosave buffers. -@item :rec -Recover file from autosave. -@item :f [] -without the argument, prints file name and character/line information afout -the currently visited file. With an argument, sets the currently visited -filename to @file{file}. -@item :cd [] -Set the working directory to (default home directory). -@item :pwd -Print present working directory. -@item :e [+] -Edit files. If no filename is given, edit the file visited by the current -buffer. If buffer was modified or the file changed on disk, ask for -confirmation. Unlike Vi, Viper allows @kbd{:e} to take multiple arguments. -The first file is edited the same way as in Vi. The rest are visited -in the usual Emacs way. -@item :e!@: [+] -Re-edit file. If no filename, re-edit current file. -In Viper, unlike Vi, @kbd{e!} is identical to @kbd{:e}. In both cases, the -user is asked to confirm if there is a danger of discarding changes to a -buffer. -@item :q! -Quit Vi without writing. -@item C-^ -Edit the alternate (normally the previous) file. -@item :rew -Obsolete -@item :args -List files not shown anywhere with counts for next -@item :n [count] [+] [] -Edit file, or edit files. The count comes from @kbd{:args}. -@item :N [count] [+] [] -Like @kbd{:n}, but the meaning of the variable -@var{ex-cycle-other-window} is reversed. -@item :b -Switch to another buffer. If @var{ex-cycle-other-window} is @code{t}, -switch in another window. Buffer completion is supported. -The variable @var{viper-read-buffer-function} controls which function is -actually used to read the buffer name. The default is @code{read-buffer}, -but better alternatives are also available in Emacs (e.g., -@code{ido-read-buffer}). -@vindex @var{viper-read-buffer-function} -@item :B -Like @kbd{:b}, but the meaning of @var{ex-cycle-other-window} is reversed. -@item :
r -Read the file into the buffer after the line
. -@item v, V, C-v -Edit a file in current or another window, or in another frame. File name -is typed in minibuffer. File completion and history are supported. -@end table -@kindex @kbd{v} -@kindex @kbd{V} -@findex @kbd{Ex args} -@findex @kbd{Ex rew} -@kindex @kbd{C-^} -@findex @kbd{Ex e!@: []} -@findex @kbd{Ex e []} -@findex @kbd{Ex edit []} -@findex @kbd{Ex edit!@: []} -@findex @kbd{Ex q!} -@findex @kbd{Ex q} -@findex @kbd{Ex quit} -@findex @kbd{Ex quit!} -@findex @kbd{Ex f} -@findex @kbd{Ex rec} -@findex @kbd{Ex r} -@findex @kbd{Ex read} -@findex @kbd{Ex pre} -@kindex @kbd{ZZ} -@findex @kbd{Ex wq} -@findex @kbd{Ex w } -@findex @kbd{Ex w!@: } -@findex @kbd{Ex w >> } -@findex @kbd{Ex write } -@findex @kbd{Ex write!@: } -@findex @kbd{Ex write >> } -@findex @kbd{Ex W} -@findex @kbd{Ex WW} -@findex @kbd{Ex Write} -@findex @kbd{Ex WWrite} -@findex @kbd{Ex WWrite} -@findex @kbd{Ex x} -@findex @kbd{Ex x!} -@findex @kbd{Ex suspend} -@findex @kbd{Ex stop} -@findex @kbd{Ex n [ | ]} -@findex @kbd{Ex cd []} -@findex @kbd{Ex pwd} - -@node Mapping -@section Mapping - -@cindex key bindings -@cindex key mapping - -@table @kbd -@item :map -Start defining a Vi-style keyboard macro. -For instance, typing -@kbd{:map www} followed by @kbd{:!wc %} and then typing @kbd{C-x )} -will cause @kbd{www} to run wc on -current file (Vi replaces @samp{%} with the current file name). -@item C-x ) -Finish defining a keyboard macro. -In Viper, this command completes the process of defining all keyboard -macros, whether they are Emacs-style or Vi-style. -This is a departure from Vi, needed to allow WYSIWYG mapping of -keyboard macros and to permit the use of function keys and arbitrary Emacs -functions in the macros. -@item :unmap -Deprive of its mappings in Vi state. -@item :map!@: -Map a macro for Insert state. -@item :unmap!@: -Deprive of its mapping in Insert state (see @kbd{:unmap}). -@item @@ -In Vi state, -execute the contents of register as a command. -@item @@@@ -In Vi state, -repeat last register command. -@item @@# -In Vi state, -begin keyboard macro. End with @@. This will -put the macro in the proper register. Register will -be automatically down-cased. -@xref{Macros and Registers}, for more info. -@item @@! -In Vi state, -yank anonymous macro to register -@item * -In Vi state, -execute anonymous macro (defined by C-x( and C-x )). -@item C-x e -Like @kbd{*}, but works in all Viper states. -@item #g -Execute the last keyboard macro for each line in the region. -@xref{Macros and Registers}, for more info. -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@end table -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{#g} -@kindex @kbd{*} -@kindex @kbd{@@!} -@kindex @kbd{@@#} -@kindex @kbd{@@@@} -@kindex @kbd{@@} -@findex @kbd{Ex unmap } -@findex @kbd{Ex map } -@findex @kbd{Ex unmap!@: } -@findex @kbd{Ex map!@: } - -@node Shell Commands -@section Shell Commands - -@cindex % (Current file) - -The symbol @samp{%} is used in Ex shell commands to mean current file. If -you want a @samp{%} in your command, it must be escaped as @samp{\%}. -@cindex @samp{%} (Ex address) -However if @samp{%} is the first character, it stands as the address for -the whole file. -@cindex @samp{#} (Previous file) -Similarly, @samp{#} expands to the previous file. The previous file is the -first file in @kbd{:args} listing. This defaults to the previous file in -the VI sense if you have one window. - -Symbols @samp{%} and @samp{#} are also used in the Ex commands @kbd{:e} and -@kbd{:r }. The commands @kbd{:w} and the regular @kbd{:r -} command don't support these meta symbols, because file history is a -better mechanism. - -@cindex shell commands - -@table @kbd -@item :sh -Execute a subshell in another window -@item :[x,y]! -Execute a shell [on lines x through y; -% is replace by current file, \% is changed to % -@item :[x,y]!!@: [] -Repeat last shell command [and append ]. -@item :! -Just execute command and display result in a buffer. -@item :!!@: -Repeat last shell command and append -@item ! -The shell executes , with standard -input the lines described by , -next the standard output replaces those lines -(think of @samp{cb}, @samp{sort}, @samp{nroff}, etc.). -@item !! -Give lines as standard input to the -shell , next let the standard output -replace those lines. -@item :[x,y] w ! -Let lines x to y be standard input for -(notice the between @kbd{w} and @kbd{!}). -@item :
r ! -Put the output of after the line
(default current). -@item :
r -Read the file into the buffer after the line
(default -current). -@item :make -Run the make command in the current directory. -@end table -@findex @kbd{Ex
r } -@findex @kbd{Ex
r !} -@findex @kbd{!} -@findex @kbd{!!} -@findex @kbd{!} -@findex @kbd{Ex w !} -@findex @kbd{Ex x,y w !} -@findex @kbd{Ex !!@: } -@findex @kbd{Ex !} -@findex @kbd{Ex sh} -@findex @kbd{Ex make} - -@node Options -@section Options - -@cindex Vi options - -@table @kbd -@item autoindent -@itemx ai -@cindex autoindent -autoindent: In append mode after a the -cursor will move directly below the first -character on the previous line. -This setting affects the current buffer only. -@item autoindent-global -@itemx ai-global -Same as `autoindent', but affects all buffers. -@item noautoindent -@itemx noai -Cancel autoindent. -@item noautoindent-global -@itemx noai-g -Cancel autoindent-global. -@item ignorecase -@itemx ic -@cindex case and searching -ignorecase: No distinction between upper and lower cases when searching. -@item noignorecase -@itemx noic -Cancel ignorecase. -@item magic -@itemx ma -@cindex literal searching -Regular expressions used in searches; nomagic means no regexps. -@item nomagic -@item noma -Cancel magic. -@item readonly -@itemx ro -@cindex readonly files -readonly: The file is not to be changed. -If the user attempts to write to this file, confirmation will be requested. -@item noreadonly -@itemx noro -Cancel readonly. -@item shell= -@itemx sh= -@cindex shell -shell: The program to be used for shell escapes -(default @samp{$SHELL} (default @file{/bin/sh})). -@item shiftwidth= -@itemx sw= -@cindex layout -@cindex shifting text -shiftwidth: Gives the shiftwidth (default 8 positions). -@item showmatch -@itemx sm -@cindex paren matching -@cindex matching parens -showmatch: Whenever you append a @kbd{)}, Vi shows -its match if it's on the same page; also with -@kbd{@{} and @kbd{@}}. If there's no match, Vi will beep. -@item noshowmatch -@itemx nosm -Cancel showmatch. -@item tabstop= -@itemx ts= -@cindex changing tab width -@cindex tabbing -tabstop: The length of a ; warning: this is -only IN the editor, outside of it s have -their normal length (default 8 positions). -This setting affects the current buffer only. -@item tabstop-global -@itemx ts-g -Same as `tabstop', but affects all buffers. -@item wrapmargin= -@itemx wm= -@cindex auto fill -@cindex word wrap -wrapmargin: In append mode Vi automatically -puts a whenever there is a or -within columns from the right margin. -@item wrapscan -@itemx ws -@cindex searching -wrapscan: When searching, the end is -considered @samp{stuck} to the begin of the file. -@item nowrapscan -@itemx nows -Cancel wrapscan. -@item :set